Eddy Antomnievo Experiment

eddy-AntOmniEvo-experiment

主动沟通型的 AntOmniEvo 优化实验搭建助手。本技能是一个会主动提问、边做边验证的编程助手,帮用户把某个 eddy 业务 agent 接入 AntOmniEvo。流程分两段:步骤 1–6 是 bootstrap(对齐实验根目录 + candidate store 目录 / 数据 / agent module / 可调产物 / generate-evaluate + 冒烟,用户确认无误);步骤 7 起接 AntOmniEvo 优化循环组件(System → Evaluator → Proposer/optimizer/入口 → await optimizer.optimize()),每接一个先自验再下一步。

用户需要提供什么 vs 执行者自己drive 什么

执行者主动drive 的 — 不需要用户操心:

• 装 AntOmniEvo / 建 venv / 选 example(步骤 1)
• 写 AntOmniEvo 的 System / Evaluator / Optimizer 子类 / 入口脚本(步骤 7–10 代码)
• eddy 轨迹解析(parse_eddy_trajectory)
• 跑冒烟 / 验证 / 日志分析 / 看结果 / 总结

需要用户提供/确认的 — 业务知识,只有用户知道:

• (步骤 0) eddy 高代码系统的代码地址 + 评测代码地址(git 代码地址或本地代码仓路径都行)—— 执行者要下载这些代码做后续所有事;评测代码可能与系统同仓库,也可能独立。同时指定例子脚本:系统运行参照脚本 + 系统评测参照脚本(步骤 4 写 generate/evaluate 的复用对象)。
• (步骤 2) 评测数据在哪?gold schema 长什么样 — 你读 case sample + 跟用户复述确认。
• (步骤 3) agent module 包路径?入口?哪些文件可调?
• (步骤 4) 可参照的系统运行/评测例子脚本(步骤 0 已拿到就直接用,没给才在这步问)?打分标准是什么?
• (步骤 5) 业务项目 venv 是否就绪?model key 够吗?
• (步骤 10) proposer api_key / base_url / model; system 的 model key / MCP token;train/val 数据怎么来 + 多少条

上下文恢复:长跑优化 → 用户清上下文后

📖 详细 → references/context-recovery-recipe.md。SKILL.md 这里只记 trigger: 每次跑优化或跑完,在 <exp_root>/NOTES.md 追加实验状态(路径 + 配置 + credential 过期时间 + iteration/best candidate/遗留事项)。 下次新上下文只读 NOTES.md(<exp_root> 下)+ statistics.json(<run_dir>/logs/ 下)+ tail log 即可恢复。resume = 同 --config(config 里 <run_dir> 不变 → AntOmniEvo 自动 resume from checkpoint)。 ⚠ credential 过期后 batch score 从高跌到低 → 从用户拿新 credential → 更新 config YAML + run.env → resume。

实验记忆 NOTES.md(贯穿所有步骤 — 避免后续重探整个 repo / 网)

实时记,不等步骤做完 —— 目标是"用户随时 clear 上下文,新会话也能无损恢复继续推进"。每个关键动作发生后立刻追加 <exp_root>/NOTES.md(累积 markdown,每段 ## 步骤 N — <标题>;放实验根目录,不放 candidate store 的 run 目录里),续做 / 新会话先读它再动手,不重复翻 repo / 联网重检:

• 进行中状态(最易丢、最关键):正在跑什么(后台任务/冒烟/长命令 + 命令本体 + 产物目录 + 开始时间)、跑到哪个小步骤、下一步打算做什么。任务完成/失败后立刻用结果更新掉。clear 后读到最后一条"进行中",就能接着等/接着查产物。
• 路径/约定:agent module 路径、入口 <pkg>.<module>:<attr>、可调条目(--tunable 列表)、INITIAL_ARTIFACTS_DIR、tunable_artifact_def 文件、generate.py/evaluate.py 路径、业务 venv 路径、model key 是否就绪、cases 路径。
• 决策/对齐:跟用户对齐的"打分法"(哪几层 scorer;阈值)、用户给的对比例子、可调面边界。
• 雷达发现:仓库里 grep/find 到的现有 eval 代码关键文件 + 行号(每项目不同,记你找到的 + 用户确认的)、踩过的坑(以实际为准,如重数据每 rollout 全量拷 → symlink/共享 之类)。
• 已验证状态:exp_root / candidate store 根目录 / run 目录路径、AntOmniEvo import OK、各冒烟过的断言/命令。

新会话恢复流程(clear 后第一条消息先看这个):读 <exp_root>/NOTES.md 尾部 → 定位中断点(哪个步骤、有没有"进行中"任务)→ 若记录里有后台任务/长命令,先查其产物文件是否已生成(inference.jsonl/predictions.jsonl/details.jsonl 等)判断跑完没有 → 补齐中断处继续,不重复已验证的工作。

行为准则(主动沟通)

1. 先问再动手,不要猜:exp_root / candidate store 目录、数据、agent module、业务代码、字段长什么样——先问用户 + 读真实文件确认,再写。拿不准就停下问。
2. 验证后再往下:每一个步骤产出后,自己先冒烟/自测验证正确性。
3. 确认门 = 阶段性同步门(每个步骤都有,直到步骤 6 最终确认都不可省):做完一步:① 把本步产物(路径 + 关键内容/数字 + 怎么看)告诉用户;② 把本步关键信息追加写入 <exp_root>/NOTES.md(见"实验记忆 NOTES.md");③ 告诉用户已完成哪些步骤 + 还剩哪些步骤;④ 问"是否继续下一步"(收到"继续" / 明确同意才进;要改/补就停下补)。
4. 数据先对齐:数据格式不先对齐,后面 generate/evaluate 全是空中楼阁。
5. 写入记忆,省后续重探 + 实时可恢复:每步把"后续会用到的关键事实"(路径/入口/约定/找到的代码/字段/决策/坑)写入 <exp_root>/NOTES.md(#3② 即此动作);进行中状态(在跑什么/产物在哪/下一步做什么)发生即记、完成即更新 —— 用户随时可能 clear 上下文,NOTES.md 是唯一恢复凭据(见"实验记忆 NOTES.md"的恢复流程)。续做先读它,不重复翻 repo / 联网重检。
6. 不在中途擅自连跳:每步只在"阶段同步 + 用户说继续"之后才推下一步;没收到继续就停。所有 6 步都完成、最终确认无误,才进 AntOmniEvo 后续(System/Evaluator/Proposer/await optimizer.optimize())。
7. 禁止随意修改用户已有的文件:业务仓库/评测仓库里的既有文件一律不改,除非用户当场点名要改;新增文件(generate.py/evaluate.py/venv/组件)只落在流程必需处,创建后在同步里显式列出路径。

整个流程:步骤 0 拿代码 + 配各代码目录环境,步骤 1–6 是 bootstrap(冒烟无误后进接线),步骤 7 起接 AntOmniEvo 优化循环;每一步都按"先问/读确认 → 做 → 自验 → 告知用户确认"四小动作为之: 步骤 1 对齐实验根目录 + candidate store 目录 + 配置环境 → 步骤 2 对齐数据格式 + 写数据层 → 步骤 3 对齐 agent module + 写 AntOmniEvo 可调产物 → 步骤 4 写 generate/evaluate → 步骤 5 检查业务仓库代码 venv → 步骤 6 冒烟 + 用户确认 → 步骤 7 写 AntOmniEvo System 模块(候选可调产物 → 预测)→ 步骤 8 Evaluator → 步骤 9 Optimizer 子类 → 步骤 10 example 入口 + config + optimize()。

---

两个目录概念(实验根目录 ≠ candidate store,先分清再动手)

"workspace" 一词在本技能拆成两个不同概念 —— 路径不同、内容不同、resume 语义只挂在第二个上,别混:

• 实验根目录(<exp_root>):整个优化实验的非候选产物都放这 —— 本实验组件目录(<exp_root>/antomnievo/,默认;不是源码 clone —— AntOmniEvo 一律 pip 装包,这里放本实验补充的 dataset/tunable_artifact_def/System/Evaluator/Optimizer 组件 + 入口脚本 + 最小 pyproject;venv 也在里面:<exp_root>/antomnievo/.venv/,它是 AntOmniEvo 的环境)、NOTES.md(实验记忆)、config YAML、run.env、tests/<smoke_name>/(冒烟产物)、initial_artifacts/。每实验自包含:组件目录 + venv 都在 exp_root 内(不共享外部 venv;组件只影响本实验);一个 exp_root 跨多次优化 run 复用。
• candidate store 根目录(<candidate_store_root>):单独开的一个目录,只放优化实验产生的候选数据;里边每次 run 一个以时间为后缀的子目录 <run_dir> = <candidate_store_root>/run_YYYYMMDD_HHMMSS/(= AntOmniEvo LocalCandidateStore(workspace_dir=...) 的落盘路径:candidates/<id>/ 可调产物树/meta/changelog/best、logs/statistics.json、optim 日志)。resume = 同一个 <run_dir>(AntOmniEvo 查 statistics.root_candidate_id:有 → 续跑跳 root baseline;没 → 从头建);新 run = 新开一个时间戳子目录(内置行为,不需要 flag)。

步骤 1 跟用户对齐的是 <exp_root> + <candidate_store_root> 两个路径(后者默认建议 <exp_root>/workspace/,也可完全独立 —— 候选数据 = 可调产物树 × 候选 × 代,体积可能很大,想放别的盘/位置就独立);<run_dir> 步骤 10 跑 optimize() 时才创建(步骤 1 不建)。⚠ config YAML 里 <run_dir> 的 key 叫 workspace_dir(与 LocalCandidateStore 参数同名)—— 它指 candidate store 的单次 run 目录,不是 exp_root、也不是 candidate store 根目录。

---

通用约定(贯穿各步)

跨步骤的规则集中在这,各步引用,别散在步骤里。

• 实验记忆(NOTES.md):每步产出追加写 <exp_root>/NOTES.md(## 步骤 N — <标题>),续做 / 新会话先读它再动手。见上方"实验记忆 NOTES.md"。
• AntOmniEvo 一律 pip 装包,组件放 <exp_root>/antomnievo/(统一约定,不再"代码还是包"二选一,记 NOTES):不拉源码 clone —— pip install ant-omnievo(core;要可视化 → 再 pip install ant-omnievo-visualizer)。本实验补充的模块实现和脚本(dataset / tunable_artifact_def / System / Evaluator / Optimizer 子类 / 入口脚本)全部放专门目录 <exp_root>/antomnievo/(默认):里面建本场景包 <scenario>/(如 peizhiagent/),组件按 dataset|tunable_artifact_defs|system|evaluator|optimizer 子目录排;放一个最小 pyproject.toml + uv pip install -e <exp_root>/antomnievo 让场景包可 import(PYTHONPATH 兜底);venv 在 <exp_root>/antomnievo/.venv/。不改已装的包;README/example 等参照从已装包里读(python -c "import antomnievo,os;print(os.path.dirname(antomnievo.__file__))",下面有 example/、model/tunable_artifact_defs/ 等)。详见 references/system-recipe.md §0。
• tests / smoke 输出目录:所有冒烟/测试产物统一放 <exp_root>/tests/<smoke_name>/(下称 <smoke dir>,如 bootstrap_smoke、system_smoke)—— 不写 /tmp、不写业务仓库的 outputs/,集中放实验根目录下方便用户回看;保留不清(后面 System/Evaluator 要解析这些真实数据的格式 + 用户回看)。各次冒烟用一个独立子目录,路径记进 NOTES。
• 路径全绝对:传子进程 / System 构造的路径(generate_script / python_path / agent_src / local_source_repo / env_file / output_dir / cases_path / candidate_meta.artifact_dir)全用绝对路径,子进程 cwd 无关。详见 references/system-recipe.md §3 坑8。
• 业务字段不写死 / 不耦合业务名:运行上下文 / 可调条目 / scoring 等业务变化部分从 gold/用户读,不写死业务默认值;照范本结构,别照具体业务包名/字段。
• AntOmniEvo 组件的 description 要反映 generate/evaluate 机制:System.system_description() / Evaluator.scoring_criteria() 等描述字符串,要基于你写过的 generate.py / evaluate.py 的真实机制写清 —— system 写:运行上下文怎么来的、agent 工具面 + 工作流、产出什么 artifact、在哪停(awaiting/HITL)、空产物的失败因(漏改而非崩溃);evaluator 写:拿什么比、分数语义(0/1 各代表什么)、reason 来源、依赖什么前置(如 schema manifest)。这俩字符串注入 AntOmniEvo 的 proposer / 分析 prompt —— 错或空会让它错误归因(把系统/数据问题算到可调产物头上)。写 System/Evaluator 时一并写好,别留空 / 泛泛。

---

步骤 0:拿代码地址 + 下载代码 + 配各代码目录环境

🎯 后续所有步骤都要在业务系统代码和评测代码上动手 —— 一开始就把代码拿到本地、把各代码目录的环境配好,后面才不卡。

1. 问用户两个代码地址(别猜,给候选 + 允许自输;git 代码地址或本地代码仓路径都行):
   • eddy 高代码系统代码地址(业务 agent 所在的系统仓库):git URL 或本地已有 checkout 路径。
   • 评测代码地址(评测 pipeline 所在):可能与系统代码同仓库(如仓库内的 eval 目录),也可能是独立仓库 —— 问清楚。
   • 用户告诉地址后,执行者自己下载(git clone 到跟用户确认的位置);本地已有 checkout 就直接用,确认路径 + 当前分支/commit 记 NOTES。
2. 同时问用户指定例子脚本(系统怎么跑、评测怎么跑的参照脚本,步骤 4 写 generate/evaluate 的复用对象):系统运行例子脚本(怎么起 agent、出 predictions/trajectories)+ 系统评测例子脚本(怎么打分、出 reason)—— 脚本路径(仓内相对路径即可)或命令;有就在步骤 0 一并拿到、记 NOTES,步骤 4 不用再问;没有就说没有,步骤 4 从零写。
3. 各代码目录分别配环境:python 项目 → 每个仓库目录下建 venv(uv venv --python 3.12 <repo>/.venv)+ 装依赖(uv pip install -r <repo>/requirements.txt --index-strategy unsafe-best-match;装完别再 uv sync —— 会剪掉 requirements.txt 装进来的 deps)。非 python 代码目录(如 java/proto 源码仓库)只需确认 checkout 可用、版本能解析(评测/沙箱按 case 的 code_version export 快照用)。
4. sanity:各 python venv 能 import 各自主包(<repo>/.venv/bin/python -c "import <pkg>" 不报错)。
5. → [同步] 把各代码目录路径 + 例子脚本路径 + venv 路径 + 依赖状态告诉用户;写 <exp_root>/NOTES.md(步骤 0:系统代码地址/评测代码地址/本地 checkout 路径/例子脚本路径/各 venv 路径/依赖状态);问「是否继续」,继续后进步骤 1。

---

步骤 1:对齐实验根目录 + candidate store 目录 + 配置环境(创建 venv、拉 AntOmniEvo 包)

🎯 把 AntOmniEvo 实验的落地基础备好。📖 具体 venv/安装/目录布局命令 → references/workspace-setup-recipe.md。

1. 让用户定两个路径(『两个目录概念』,都要独立、可写、别和业务项目混,跟用户确认再往下)。问法:给候选 + 允许自输,别开放式问 —— 用 AskUserQuestion(或等效)给 2~3 个具体候选路径让用户选,用户也可以选 Other 自己输入;候选按当前环境推断(默认第一个候选 = 当前工作目录 <cwd> 本身,其余如 <cwd>/exp-<agent>、用户惯用实验目录),每个候选附一句取舍说明(如"与业务仓库同级,自包含" / "放别的盘,候选数据大时合适");用户选完若对默认有疑虑,可给调整后的候选再问一轮,最终路径以用户确认为准:
   • 实验根目录 <exp_root>:放 NOTES.md、config YAML、run.env、tests/ 冒烟产物、initial_artifacts/、AntOmniEvo 入口脚本拷贝(后续从 antomnievo/example/ 拷对应那份再改)、实验日志、(可选).venv。
   • candidate store 根目录 <candidate_store_root>:单独一个目录,只放优化 run 的候选数据;候选给:默认 <exp_root>/workspace(推荐,集中管理)、<exp_root>/candidate_store/、独立路径(想放别的盘/位置,用户自输)。<run_dir>(时间戳子目录)本步不建 —— 步骤 10 跑 optimize() 时才创建。
2. 建组件目录 + 专用 python 环境 + pip 装 AntOmniEvo:路径定了后,建 <exp_root>/antomnievo/(专门目录,非源码 clone),然后在其中创建一个专供 AntOmniEvo 用的 python 环境:uv venv --python 3.12 <exp_root>/antomnievo/.venv(python ≥ 3.12 即可,有更新版本就用机器上已验证过的),pip 装包(不拉源码):uv pip install ant-omnievo --python <exp_root>/antomnievo/.venv/bin/python(core)。问用户要不要用可视化前端:要 → 再 uv pip install ant-omnievo-visualizer --python <exp_root>/antomnievo/.venv/bin/python(README §9;前端还要 npm install,见 recipe)。业务项目自己的运行/打分 harness 不在这里装(README §5:System/Evaluator shells out → 各自单独装);本技能的 generate/evaluate 跑在业务项目自己的 venv,不是这个 AntOmniEvo venv。
3. 读 README + 选最像的 example(从已装包里读,不 clone):<pkg> = $(<exp_root>/antomnievo/.venv/bin/python -c "import antomnievo,os;print(os.path.dirname(antomnievo.__file__))") → 读 <pkg>/../README*.md(随包装;没有就 pip download 或让用户给仓库地址只读参考)重点 §5/§6/§7/§8 + 可调产物概念;扫 <pkg>/example/(terminalbench / text2sql / rag / appworld)挑系统形态最像的一份当起点——example/rag/agentic_rag_internal.py(最简单)、example/text2sql/birdtest_text2sql.py(batch-subprocess System,更接近"调业务项目 generate/evaluate")。后续写各模块就地参考。
4. sanity:<exp_root>/antomnievo/.venv/bin/python -c "import antomnievo; from antomnievo.store.candidate_store import LocalCandidateStore; print(antomnievo.__file__)" 能 import(且 antomnievo.__file__ 指向该 venv 的 site-packages,证明用的是 pip 装的包)。
5. → [同步] 告知用户 exp_root + candidate store 根目录两个路径 + AntOmniEvo import OK;写 <exp_root>/NOTES.md(步骤 1:两个路径/venv/example 选择);告知已完成步骤 1、剩余步骤 2–6;问「是否继续」,继续后进步骤 2。

---

步骤 2:对齐数据格式 + 写 AntOmniEvo 数据层

1. 问清数据 + 读样本:评测数据在哪?要 train / val / test 三个 jsonl(至少 test)。让用户给路径或贴样本,读 2~5 行原始 jsonl,看清楚 schema 再跟用户复述确认。要摸清的字段(以实际样本为准,别套别的领域):唯一 id(case_id/query_id...)、输入(用户需求 / query / input.*...)、gold(可能结构化对象:直接答案 / golden_* / expected.*)、回放/约束上下文、类目难度(可选)。
2. 在组件目录写数据层三个文件:<exp_root>/antomnievo/<scenario>/dataset/ 下放 <domain>_data_inst.py / <domain>_dataset_loader.py / __init__.py(结构对照已装包里 antomnievo/dataset/<既有某 domain>/ 的一份,别改已装的包)。📖 可对号模板 + 字段抽取要领 + 坑 + sanity → references/data-layer-recipe.md。
   • <domain>_data_inst.py:<Domain>DataInst(DataInst)(antomnievo.interface.data_inst:pydantic,基类只强求 id/query/golden_answer(str));from_raw(raw) 抽取轻字段 + 领域字段,重数据留 raw(exclude=True)+ to_case_dict() 回原行,不要摊平。
   • <domain>_dataset_loader.py:async load_dataset(cases_jsonl, max_samples=0, shuffle=False) -> list[<Domain>DataInst],逐行读、跳过无 id / 损坏行、from_raw 构造。
   • __init__.py;若 antomnievo/dataset/__init__.py 有域名注册,按相同方式登记。
3. sanity:asyncio.run(load_dataset('<test>', max_samples=3)) 加载 N 条,且 id/query/golden_answer 都非空。
4. → [同步] 把数据层文件 + 加载条数 + 字段理解告诉用户;写 <exp_root>/NOTES.md(步骤 2:cases 路径/字段抽取/registry 登记);告知完成步骤 2、剩 3–6;问「是否继续」,继续后进步骤 3。

---

步骤 3:对齐 agent module + 写 AntOmniEvo 可调产物(可调产物 = module 的可调文件集)

🎯 AntOmniEvo 可调产物 = 一目录可调文件;LocalCandidateStore 整树 copytree 进每个 candidate(只 ignore __pycache__),proposer 在 candidate 的 artifact_dir 能改任意文件,TunableArtifactSchema 只软提示、无路径白名单。所以 initial_artifacts_dir 既不能指整个 module(env/bootstrap/(大/重的非行为数据) 全进每个 candidate、全机器可改、且 重数据 × 代 × rollout 爆炸),也不该外置。正确:把约定的可调条目抽出成独立目录 <exp_root>/initial_artifacts/(目录名固定叫 initial_artifacts,见 item 5),initial_artifacts_dir 指它;候选可调产物自然就是"按 <pkg>-相对路径排好的可调文件集",步骤 4 的 generate 再按 --tunable 条目逐条 load 回 module。📖 TunableArtifactSchema + 写法 + 映射 → references/tunable-artifact-recipe.md。

1. 和用户对齐 agent module + 启动入口:
   • module 路径(运行期包,任何名字,如 <业务项目>/src/<pkg>)= 步骤 4 generate 的 --agent-src。
   • 找启动入口(不假定具体名;很多 eddy agent 的入口在 <pkg> 下某处(如 agents/ 子包,但不限),但不限):grep builder.build()/AgentBuilder/模块顶层 agent = …、读 app-metadata.yml/server-simple.yaml(module_path+attr)/pyproject[tool.arec] main-entry/eddy run/项目 CLAUDE.md、列 *agent*.py 候选;候选给用户确认入口(<包内路径>:<attr>),多义/找不到 → 让用户给。入口 = "code integrity" 的 import 锚。
2. 和用户对齐"可调文件集"(过滤 __pycache__/.pyc):扫整个 module,逐个说清每个文件/目录用途、逐条确认,跟用户约定要优化哪些文件/目录(即后续 generate 的 --tunable 条目)——
   • 可调 = 想优化的行为面,由用户选:可以是整条可调子包(名以项目实际为准),也可只挑一个 skill(如 <可调子包>/<某子集>/)、一个顶层文件(如 <顶层可调文件>)、或几处散落(如 <可调子包>/<子集>/ + <顶层可调文件>)。边界以用户确认为准;每个条目都用 <pkg>-相对路径表达(<可调子包>、<可调子包>/<子集>、<顶层可调文件>…)。
   • 非可调(留 module,不进可调产物):运行配置、启动 bootstrap、日志/非行为组件、大或重的非行为数据、其它无需优化的部分(具体名以项目扫描 + 用户确认为准) —— 不进 candidate、不被 load 触及。
   • ⚠ 可调部分通常不能单独 import 跑(入口 import 顶层非可调兄弟);运行靠步骤 4 generate 的 "load 可调产物" 把候选的可调部分按 --tunable 合并回整个 module 才能跑。
3. 看范例 + 写可调产物(写在组件目录 <exp_root>/antomnievo/<scenario>/tunable_artifact_defs/<domain>_tunable_artifact_def.py,只列与用户对齐的那棵可调树;在已装包的 antomnievo/model/tunable_artifact_defs/ 选系统形态最像的一份 <x>_tunable_artifact_def 作结构参照 —— tunable_artifact_schema.py 的 FileSchema/FolderSchema、common_descriptions.py 可复用描述):
   • _<DOMAIN>_TUNABLE_ARTIFACT_SCHEMA = FolderSchema(name=<根>, description=<行为源 + 约束…>, files=[…可调条目树…]),约束:无冗余 / 无矛盾 / 泛化(每条通用陈述配一个具体例子)/ 代码完整(任何改动后 python -c "import <步骤1入口>" 仍成功)。
   • INITIAL_ARTIFACTS_DIR = item 5 抽出的 <exp_root>/initial_artifacts/(不指 module 包根)。本步只写 Schema。
4. sanity + 给用户的确认件:<exp_root>/antomnievo/.venv/bin/python -c "from <scenario>.tunable_artifact_defs.<domain>_tunable_artifact_def import <DOMAIN>_TUNABLE_ARTIFACT_SCHEMA; from antomnievo.model.tunable_artifact_schema import render_tunable_artifact_schema; print(render_tunable_artifact_schema(<DOMAIN>_TUNABLE_ARTIFACT_SCHEMA)[:800])"(tunable_artifact_def 从本场景包 import,render_tunable_artifact_schema 从已装 AntOmniEvo import);把三样交给用户确认 —— ① 步骤 2 约定的可调条目清单(--tunable 候变每个条目及其作用)② render_tunable_artifact_schema(...) 渲染出的 可调产物树(应只含可调条目,无 env/bootstrap/(大/重的非行为数据))③ 写好的 <exp_root>/antomnievo/<scenario>/tunable_artifact_defs/<domain>_tunable_artifact_def.py 路径 + 约束段。让用户核对:边界对不对、有没有该进/该出的文件丟了/多了、约束是否合理。
5. 生成初始可调产物 —— 问用户用现有代码还是从零,确认后本步就实际抽出到 <exp_root>/initial_artifacts/(目录名固定叫 initial_artifacts,别用别的名):
   • 用现有代码:把 item 2 约定的可调条目逐项从 module 拷到 <exp_root>/initial_artifacts/(按 <pkg>-相对路径排好,跳 __pycache__/*.pyc;dir 用 rsync -a --exclude __pycache__ <src>/<ent>/ <dst>/<ent>/ —— 源路径带尾斜杠才是拷内容,不带会多套一层目录)。抽完 diff -r 对源验证逐字节一致。候选初值 = 项目现有可调文件 AS-IS,AntOmniEvo 从当前基线开始改。
   • 从零开始:<exp_root>/initial_artifacts/ 留空(或只放最小模板文件),AntOmniEvo 从空白状态摸索出做法。
   • initial_artifacts_dir 永远指 <exp_root>/initial_artifacts/,不指 module 包根(可调产物 ≠ agent module:包根含运行配置/bootstrap/(大/重的非行为数据),整树进每个 candidate 会爆炸,且 proposer 能碰非可调文件)。
   • 同步时必须向用户讲清 initial_artifacts 怎么被使用:它是 AntOmniEvo root candidate(第 0 代基线)的可调产物 —— optimize() 启动时 CandidateStore 把 initial_artifacts/ 整树 copytree 成 root candidate 的 artifact_dir,先跑 baseline 评测;之后每代候选 = proposer 在某候选可调产物副本上改出的新树;评测时 generate.py 用 --artifact-dir <候选 artifact_dir> --tunable <条目>… 把该树 load 回运行期 checkout 跑(步骤 4 的映射)。改 initial_artifacts/ = 改优化起点基线。
   • 写进 <exp_root>/NOTES.md(初始可调产物来源:existing / from-scratch + <exp_root>/initial_artifacts/ 路径 + 条目数/文件数)。
6. → [同步] 把「可调文件集」边界 + 可调产物树 + 约束 + 初始可调产物来源 + <exp_root>/initial_artifacts/ 路径及它怎么被使用(上一条) + 写好的 <domain>_tunable_artifact_def.py 给用户确认;写 <exp_root>/NOTES.md(步骤 3:agent module 路径/入口/可调条目/initial_artifacts_dir/tunable_artifact_def 路径/initial_artifact 来源);告知完成步骤 3、剩 4–6;问「是否继续」,继续后进步骤 4。

注:某些已 ship 的 tunable_artifact_def 把整包当可调产物、只靠"少动"描述做软约束 —— 那是特例,不是隔离手段;新领域收窄到与用户约定的可调集 + 抽出式 <exp_root>/initial_artifacts/ 作 initial_artifacts_dir 才硬隔离。

---

步骤 4:写业务项目侧 generate/evaluate(generate 做 "load 可调产物")

generate 跑一个 (运行期 + 候选可调产物) 组合 —— AntOmniEvo 的 System 跑 generate、Evaluator 跑 evaluate。📖 逐项模式 + 冒烟配方 + 文件形状表 → references/generate-evaluate-recipe.md。

两条 flag,两个概念(别和 AntOmniEvo 的候选可调产物混):

• --agent-src <dir>(必填)= 运行期 agent 包(import 目标 = 完整可 import 的包;按结构找 = 步骤 3.1 的 module)。--agent-module/--agent-attr = 步骤 3.1 跟用户确认的入口(项目具体,别假定值)。
• --artifact-dir <dir>(可选,需配 --tunable)= 候选的可调产物(= AntOmniEvo 候选 artifact_dir,其内部布局按 <pkg>-相对路径排好那批可调文件)。--tunable <pkg-rel-path>(可重复)= 步骤 3 跟用户约定的可调条目(如 <可调子包>、<可调子包>/<子集>、<顶层可调文件>… 名字以项目实际为准)。

“load 可调产物” 映射 —— 按 <pkg>-相对路径、逐条目替换(非整树 merge-copy):

1. 拿 --agent-src 做一份 tmp checkout(整包,跳 __pycache__/(大/重的非行为数据),(大/重的非行为数据) symlink 回源 → 不每 rollout 拷 重数据)。
2. 对每个 --tunable ent:源 = <artifact-dir>/<ent>、目标 = <checkout>/<pkg>/<ent>(同一条相对路径):
   • dir → rm 目标(基线)后再 copytree(源, 目标) —— 候选在该 dir 内的删除/改名能传过去;不能用 copytree(dirs_exist_ok=True)(merge 会让删除文件残留)。
   • file → rm 目标 后 copyfile(源, 目标)。
   • 候选没有 <ent>(候选删了)→ 只 rm。不在 --tunable 里的路径 → checkout 留运行期原样,不动。
3. 从该 checkout import agent 跑(generate 自带 dep 自动安装、data-driven 运行上下文、复用项目 converter)。

• 写 generate/evaluate 之前,先问用户,别自己先一顿调查(步骤 0 已指定例子脚本的直接用、不必重问,只针对性读代码验证;没指定才在这步问):开口第一句就问"有没有可以参照的系统运行脚本(怎么跑 agent、怎么出 predictions/trajectories)和系统评测脚本(怎么打分、出 reason)?路径/命令/获取方法是什么" —— 先问、拿到用户指认后再针对性读代码验证,不要自己先把仓库翻个底朝天再开口(顺序反了,浪费且易认错)。参照/复用 ≠ wholesale delegate,两脚本分工不同:
  • generate.py 必须自己写、自己实现 load 可调产物(checkout + --tunable 逐条替换 + 从 checkout import + 自己的 invoke 循环):项目的现成推理脚本不支持 --artifact-dir/--tunable,直接委托它 = 候选可调产物根本载不进来,达不到 AntOmniEvo 的目标。对现成运行脚本的正确用法是读它、复用它的机制(prompt/运行上下文怎么构造、sandbox-transport 怎么挂、converter/轨迹 builder 直接 import 调),不是 shell 出去。
  • evaluate.py 委托项目评测脚本(委托的前提 = 项目评测脚本能复用已有推理产物、不重跑 agent;具体支不支持、flag 叫什么看项目 eval CLI,以实际为准);项目没有 scorer 才从零写。别闷头自己写一份跟项目不一致的。
• 通用参数 + 能力(可复用底子):generate.py / evaluate.py 有一套每个 eddy 业务都该有的通用参数与能力(按结构定位包/入口、load 可调产物、dep 自动装、并发+单 case 超时、env-file、写型 agent 的 sandbox-transport、委托项目 eval、score∈[0,1] 归一、reason 有信息量…),每条都附为什么 → 详见 references/generate-evaluate-recipe.md §通用参数与能力。给新业务生成 gen/eval 时直接照搬这套,只改业务适配部分(入口名 / 可调条目 / 运行上下文字段 / converter / scorer)。
• --dry-run(仅用于开发自测,不是冒烟):不调 agent,种合成 artifact。冒烟请用真模型(不带 --dry-run)。
• generate.py(写预测,不评分):产物 predictions.jsonl + run_summary.json(含 agent_src/artifact_loaded/artifact_dir/tunable/checkout)+ workspace + 可选 trajectories。eddy agent.invoke(...) 包 RunContext;包按结构定位、--agent-module/--agent-attr=确认入口;dep 自动安装(扫最终跑那份)、运行上下文从 case 的 gold 读、复用项目已有 converter(配 shallow 兜底)。单条失败不连累、按输入序、Semaphore(--concurrency)。
• ⚠ 写法范式:流式写盘(强制) —— generate.py 的 generate_predictions 必须"完成一条立即 append 写盘并释放大对象、全部跑完再聚合(run_summary 从计数器取)",禁止 asyncio.gather 把全量 case 的 row+完整 trajectory 攒内存后最后 write_text 一次写(否则中途"结果一个都没有"+内存爆)。被 evaluate 委托的项目 eval pipeline 里的并发 judge(若你改到)也同范式 + 序列化对齐。骨架/对齐表/验收清单见 references/generate-evaluate-recipe.md §「写法范式:流式写盘(强制)」。
• 写 evaluate.py 前先跟用户对齐"怎么打分"(同步骤 3 的对齐风格;本技能不预设任何业务打分法/指标名/eval 入口——每项目不同,别照搬): ① 让用户给一个 期望产物 vs 真实产物 的对比例子(gold 长怎样、agent 产什么、什么算"对"),把打分基准从抽象落到具体。 ② 或去业务仓库找已有 eval/scorer 代码 —— 用户给线索或自己 grep(eval/score/grade/judge/predictions/offline…),把候选列给用户确认哪个是这项目正确的打分法,以及它的输入(读哪个文件/哪段结构)、输出(产出的 metric 字段名)、per-case 产物(从中合成 reason 的来源)。 ③ 据确认结果写 evaluate.py —— 项目已有 scorer/pipeline → delegate(subprocess 或 import 调它,把它的 metric 归一化到 [0,1] 当 EvalResult.score,从它的 per-case 产出合 reason);用户给了对比例子 → 按例子实现确定性判定;都没 → 通用 recall 兜底 + 把判定逻辑写清给用户确认。别自创与项目已有 scorer 不一致的 scoring。
• evaluate.py(评分,不重跑 agent;每条 case 出 score + reason):读 generate 的产物(用户确认的 format)+ --cases(gold),按确认的打分法调/读 scorer;EvalResult.score∈[0,1] = 把确认的 metric 归一化到 [0,1](给 optimizer 当 metric);per-case 产物 + reason 用确定性文案从 scorer 的 per-case 产出(用户确认的字段来源)抽;--output 才落盘。具体写什么文件 / per-case 文件键名 看项目 evaluate.py --help + 实读一份真产物文件确认。
• AntOmniEvo System 接线(后续):每候选 → 跑 generate --agent-src <module> --artifact-dir <candidate_artifact_dir> --tunable <entry1> --tunable <entry2> …(entry = 步骤 3 约定的);run_summary.checkout 指向那次 checkout,事后核对。
• 并发注意(每候选一个 generate.py 进程):① 每候选独立 --output-dir(不撞产物);② uv pip install 写共享 venv 可能竞争 → 做一次性 dep pre-flight(装齐)后候选运行传 --no-install-deps;③ 每进程留一份 tmp checkout(可加 atexit 清理);④ 多版本同并发注意 model key 限流公平(共用一把 key 会把"慢"伪装成"差")。
• ⚠ 按 agent 是否"写产物"选运行路径(详见 recipe 坑节):只读型 agent(产物=纯检索/推理回答)用 LOCAL_WORKSPACE=1 即可;写型 agent(产物 = config/source edit / release ticket 等)不能只设 LOCAL_WORKSPACE=1 —— 会 status=completed 但 prediction_present=False(没产物)。写型走 sandbox-transport(--local-sandbox-transport --local-source-repo <项目源码仓库 checkout>,复用项目既有的"挂本地 VFS"机制)。agent 用 MCP 时还要先备好 MCP 身份 token + 账号权限(见 recipe 坑节)。
• ⚠ 轨迹要复用项目既有 schema —— generate 写的 trajectories.jsonl 后面要被 evaluate 委托的 eval pipeline (evaluate 委托的项目 eval pipeline 里 LLM-scorer / per-case 分析) 读;schema 缺字段 → 项目的 LLM scorer / judge 判"轨迹为空"→ 全 0 分。复用项目 项目的 trajectory 序列化函数,或照它的 schema 字段(tool_calls/tool_results/message_summary/human_input_required/…) 手动抽装。详见 recipe 坑节。
• → [同步] 把 generate.py/evaluate.py + --help + 关键契约 + load 映射 给用户确认;写 <exp_root>/NOTES.md(步骤 4:flags/--tunable 条目/scoring 对齐结果/找到的 eval 代码);告知完成步骤 4、剩 5–6;问「是否继续」,继续后进步骤 5。

---

步骤 5:检查业务仓库代码 venv

业务项目这边的环境得先就绪,步骤 4 写的 generate/evaluate 才跑得起来(独立于步骤 1 的 AntOmniEvo venv):

• 业务项目自己的 venv 是否就绪(有 .venv、运行依赖装齐——eddy/antmcp 等:uv pip install -r <业务项目>/requirements.txt --index-strategy unsafe-best-match,装完别再 uv sync)。
• 用业务项目的 venv 验证步骤 3.1 确认的 agent 入口能 import:<业务项目>/.venv/bin/python -c "from <确认的入口 module> import <attr>" 不报错;import <步骤 3.1 确认的包名> 能定位到该项目的版本(非别处)。
• agent 在 import 时就会 build() 模型 / 构造 MCP,必须先有 model key(如 THETA_API_KEY)+ 本地跑开关(LOCAL_WORKSPACE=1 跳过 ARCA)等;没有或不确定 → 先跟用户要/确认。
• 先判断 agent 用不用 MCP,再决定要不要 token 那套 —— 有的 agent 不用 MCP,别给不用 MCP 的用户也搞这一套。判断法:grep agent 包里的 MCP 用法(MCP module / antmcp / MCP client 工具;步骤 3 扫 module 时顺手确认)。确认用 MCP 才需要:MCP 身份 token(如 IAM_TOKEN)+ 账号 MCP 权限;蚂蚁内部拿 IAM token 的标准方法 = 内网授权页(login-intranet.alipay.com/pub/oauth/AppAuthorize.htm?...,页面粘贴 mcpnexus.alipay.com 认证后拿 token;项目脚本常内置 --prompt-iam-token 流程,优先让用户走它)—— 详见 references/generate-evaluate-recipe.md 坑节;token 拿到先解码验签名段 + exp,注意聊天粘贴可能截断。不用 MCP → 只要 model key,跳过这套。
• (generate.py 的 dep 自动安装能补装扫描到的缺失第三方包,但基础运行依赖得先在业务 venv 装齐;AntOmniEvo 的 venv 不重复装这些。)
• → [同步] 把「业务 venv 能 import + key / 开关就绪」告诉用户;写 <exp_root>/NOTES.md(步骤 5:venv 路径/deps/key 状态);告知完成步骤 5、只剩步骤 6(最后冒烟 + 最终确认);问「是否继续」,继续后进步骤 6。

---

步骤 6:冒烟 + 用户确认

冒烟产物按『通用约定』放 <smoke dir>(= <exp_root>/tests/bootstrap_smoke/)、保留不清。

冒烟必须真跑 agent(不带 --dry-run) —— 输出的 predictions / trajectories / workspace artifacts 必须是真实数据,因为:① 用户要确认格式对不对;② 后续写 System/Evaluator 要参考这些真实数据的字段结构。合成的数据没参考价值。所以冒烟前先跟用户确认 model key 就绪 +(agent 用 MCP 的话)MCP 身份 token + 账号权限就绪 —— 没准备好就先停等(详见 recipe 坑节)。

冒烟只跑少量数据(强制,别浪费时间):generate 一律 --limit 1(1 条 case;真实 agent 单条可能就要几分钟到十几分钟,绝不在冒烟跑全量/大批量);evaluate 只评这 1 条 predictions(把 predictions 里的 case_id 传给项目 eval,别让它扫全量 cases 文件);load 可调产物冒烟同样 --limit 1。冒烟要验证的是链路和产物格式,不是分数覆盖率 —— 全量跑分是步骤 10 正式 optimize 的事。

逐步命令与断言 → references/generate-evaluate-recipe.md §冒烟:

1. generate 真跑 1 case:按步骤 4"选运行路径"选 —— 只读型 LOCAL_WORKSPACE=1,写型加 --local-sandbox-transport --local-source-repo <项目源码仓库 checkout>。命令形如 <model-key>=<key> generate.py --agent-src <步骤3.1 module> --cases <test> --output-dir <smoke dir>/gen --limit 1 [写型再加 --local-sandbox-transport --local-source-repo <repo>] → 验证 status∈{completed,awaiting} + predictions.jsonl 有真实 artifact(prediction_present=True) + trajectories.jsonl 有真实消息流。
2. evaluate 闭环:对上面的 predictions.jsonl 跑 evaluate.py --predictions <smoke dir>/gen/predictions.jsonl --cases <test> --output <smoke dir>/eval [按步骤 4 跟用户对齐的 eval 参数] → 验证 per-case 产物 score 合理 + reason 非空有诊断价值 + eval 全部中间产物保留。先跑快的(无 LLM)那档确认产物对不对,要多维分再跑全档(具体档位/flag 以项目 eval 为准,别套别的项目的 stage 名 / 文件名)。
3. generate load 可调产物真跑(必须带步骤 3 抽好的 <exp_root>/initial_artifacts/,不是另做的临时可调产物) —— 冒烟要验证的就是正式 optimize() 会用的那份可调产物能被正确 load,拿别的可调产物等于没验到真东西。临时往 initial_artifacts/ 的入口文件加一行无害注释 marker(如 # SMOKE_MARKER),跑 generate.py --artifact-dir <exp_root>/initial_artifacts --tunable <entries> --output-dir <smoke dir>/load --limit 1 → 断言 artifact_loaded=true + checkout 里该文件含 marker(证明跑的是可调产物版而非运行期原版)+ prediction_present=True + status∈{completed,awaiting};断言通过立刻删掉 marker 并 diff -r 验证 initial_artifacts/ 恢复与源码逐字节一致(initial_artifacts 是优化起点基线,不留冒烟痕迹)。

自检(跑完了先自己看,别急着给用户):① 轨迹:trajectories.jsonl 有真实消息流(非空,有 tool_call/tool_result);② 评分:summary 产物 score∈[0,1](0 分 + reason 说"漏改" 是合理的;0 分 + reason 说"轨迹为空" 是 bug —— 轨迹 schema 没对齐 → 修 generate 的 trajectories.jsonl,复用项目既有 prediction.build_trajectory() 而不是自己简化);③ reason:per-case 产物文件每条 reason 有信息量(指名漏改/错改/多改字段,不能只写 "correct"——应来自 evaluate 委托的 项目的 LLM scorer / judge 文案)。(文件名/键名以你 evaluate.py 实际产出为准,别假设。)

最终确认门:把四类产物路径 + 关键数字(score/exact_rate/n_cases/n_failed/artifact_loaded/reason 摘要)告诉用户;把冒烟总结写入 <exp_root>/NOTES.md(步骤 6:通过的全部冒烟点 + 产物路径 + score 基线);再次列全 6 步已完成,接下来就是 AntOmniEvo 后续接线;用户确认无误后才进 AntOmniEvo 后续;没确认前不往下做。

---

步骤 7:写 AntOmniEvo System 模块(候选可调产物 → 预测)

🎯 把 AntOmniEvo 优化循环里的 System 组件写出来:给它一个候选可调产物,它把 agent 跑起来、产出预测(trajectory + output)给 Evaluator 评。本步主要覆盖"系统 = 调外部 generate.py 子进程"形态(对标 text2sql;eddy generate.py 就是这种)。📖 逐项模式 + 坑 + 验证配方 → references/system-recipe.md。

1. 组件放哪(『通用约定』已统一:pip 装包,组件全放 <exp_root>/antomnievo/<scenario>/,不改已装的包):System 写 <exp_root>/antomnievo/<scenario>/system/<domain>_system.py,记 NOTES(组件目录)。📖 references/system-recipe.md §0。
2. 读 System 契约 + 找最像的 example(别凭记忆写):读 antomnievo/interface/system.py(System ABC:_run/run_batch 关系)、model/{system_result,rollout_result,trajectory,candidate_data}.py(SystemResult/RolloutResult/Trajectory span 树/CandidateMeta.artifact_dir)、最像的 example(子进程 generate 形态 → system/text2sql/text2sql_system.py + example/text2sql/birdtest_text2sql.py + optimizer/text2sql/text2sql_optimizer.py;in-process 形态 → system/rag_pipeline/)、optimizer/optimizer.py 的 Optimizer._run_and_evaluate(看清它调 run_batch 传不传 kwargs —— generic 默认 run_batch(meta, data_list) 不传 kwargs,所以你得配套写 optimizer 子类,步骤 8)。📖 system-recipe §1。
3. 写 System(对标 Text2SQLSystem):override run_batch(candidate_meta, data_list, *, output_dir, cases_path, **kwargs);构造参数全绝对路径(generate_script/python_path/agent_src/tunable/local_source_repo/env_file/timeout/concurrency/local_sandbox_transport/no_install_deps);拼 generate.py 命令(--agent-src --artifact-dir <candidate_meta.artifact_dir> --tunable <ent>... --cases <cases_path> --output-dir --local-sandbox-transport --local-source-repo --env-file --no-install-deps --timeout-seconds --concurrency);subprocess.run 经 loop.run_in_executor(超时 timeout*N+300,rc≠0 记 stderr 不 raise);读回 predictions.jsonl+trajectories.jsonl,按 data_inst.id 建 SystemResult(output.content=产物摘要 JSON、trajectory=span 树 + tool_call 子 span);_run raise NotImplementedError;system_description() 准确反映 generate.py 机制(见『通用约定』)。📖 system-recipe §2。
4. 坑(实测得的):① generic Optimizer 不传 kwargs → 配套写 optimizer 子类(步骤 8)给 run_batch 传 output_dir+cases_path;System 的 run_batch 签名收这两个 kwarg;② cases_path 用 to_case_dict() 写全 case 行(带 gold),别只写 id/query;③ candidate_meta.artifact_dir = --artifact-dir,配 --tunable 做 load 可调产物;④ 写型 agent 要 --local-sandbox-transport(只读 LocalWorkspace 产不了产物,见步骤 4 坑);⑤ artifact 形态先实读 predictions.jsonl 确认(别假设 payload.field_name;本场景形如 {all_change_summary, changes[0]{config_name/app/env/base_config_version/target_type/target_config/summary}},换领域以实际为准);⑥ Trajectory 用 span 树别留空(tool_call 做子 span、其余放 root metadata);⑦ 路径全绝对(见『通用约定』);⑧ 运行前置(model key + MCP 权限 + sandbox 仓库,步骤 4/5 坑)要备齐,否则 run_batch 跑完 prediction_present=False(空跑)。📖 system-recipe §3。
5. 验证(必做,别跳):① import + issubclass(X, System);② 离线 _build_system_result 喂真 predictions/trajectories(验产物提取对、pydantic 过、span 树 + tool_call 配对对 —— 直接验真实 artifact 形态,省一次 agent 跑);③ 端到端 run_batch 1 case 真模型冒烟(造 CandidateMeta(artifact_dir=baseline 包根) + batch cases(1 条 to_case_dict)+ output_dir(本步 <smoke dir>,如 system_smoke),await system.run_batch(...);断言:返回 SystemResult 数==batch 数、prediction_present=True + 产物对齐 gold(config_name/base_version/app/env/target_type)、trajectory 有 tool_call 子 span + run_status∈{completed,awaiting} + errors 空);修 bug 后离线复验 _build_system_result(不必重跑 agent)。跑不过先分清:运行前置没备齐(MCP 403/无 VFS → prediction_present=False)还是提取/构造 bug(对照真 predictions.jsonl 修)。📖 system-recipe §4。
6. → [同步] 把 System 模块路径 + run_batch 契约(output_dir/cases_path kwargs)+ 构造参数 + 冒烟证据(产物对齐 gold 的 case_id + 字段)告诉用户;写 <exp_root>/NOTES.md(步骤 7:组件目录/System 路径/构造参数/tunable/run_batch kwargs/冒烟通过点);告知完成步骤 7、剩步骤 8(Evaluator)起;问「是否继续」,继续后进步骤 8。

---