⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

eddy-antomnievo-experiment

ant-research@ant-research⭐ 1.2k stars· last commit 4d ago· 1 open issues

主动沟通型的 AntOmniEvo 优化实验搭建助手的前置步骤集——帮用户把某个 eddy 业务 agent 接入 AntOmniEvo:对齐实验根目录(exp_root)与 candidate store 目录(两个概念分开)、创建 venv、装 AntOmniEvo、读 README 选 example;对齐数据格式并在 antomnievo/dataset 写 data_inst + data_loader;和用户对齐 agent module 在哪、启动入口、要优化哪些文件,照 example 可调产物写 AntOmniEvo 可调产物;在业务项目 scripts 写 generate(做 load 可调产物)和 evaluate;检查业务仓库代码 venv;冒烟测试并把产物路径给用户确认。当用户要"为某个 eddy 业务 agent 搭 AntOmniEvo 优化实验""接入 AntOmniEvo""写 generate/evaluate""先搞数据再写 gen/eval"、或想开始 AntOmniEvo 实验搭建时使用。

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.2k on GitHubGitHub ↗

Very popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

AntOmniEvo

An auto-evolution framework that optimizes anything — your 7×24 team of algorithm engineers.

License Papers

English · 中文


AntOmniEvo is an auto-evolution framework with a strict division of labor: you define your system's tunable artifacts and what "good" means — the framework controls the loop, AI agents do the work — and it delivers optimized tunable artifacts.

Your system's tunable parts are abstracted as tunable artifacts — a real directory of files: an agent's SKILL.md + references + scripts, a workflow's pipeline.json + node scripts, a single-file algorithm + its description. Anything so representable, and repeatably evaluatable, AntOmniEvo can optimize — optimization becomes plain file editing. The system-under-optimization need not contain an LLM; the proposer must be agents.

🚀 What it is

AntOmniEvo is an auto-evolution framework for AI agent systems. It treats your system's tunable artifacts (skills, prompts, workflow configs, pipeline code) as the genome, and runs a concurrent evolution loop where a coding-agent Proposer reads failure trajectories and rewrites those artifacts — the way a human would edit code.

It works for any system that can be expressed as a directory of tunable files and has a repeatable, reasonably-cheap evaluation:

  • AI agents — skill / harness / memory / extension directories (NL2SQL skills, coding-agent skills+harness, agentic-API skills, system prompts + strategy docs, etc).
  • Workflows / pipelines — config + node code (a retrieval DAG's pipeline.json + nodes/*.py).
  • Single-file algorithms — a .py / .ts + its description.

🧩 How it works

Division of labor: you define, framework controls, AI works.

You define — five things, once:

You provideRole
Systemhow to run your system on one eval instance
Evaluatorhow to score its output (0–1) — its scoring criteria is the optimization objective
datathe train/val instances that define "good"
TunableArtifactSchemamaps your system's tunable artifacts onto a directory: the file tree + what each file is for
initial tunable artifactsthe starting point

The framework controls — it runs the evolution loop, and all the control and engineering work inside it: scheduling, budgets, selection / elimination, persistence — deterministic machinery you don't write, keeping the strongest candidates in the population. Every candidate, run, analysis, and changelog is persisted to a CandidateStore — interruptible and resumable.

The AI works — the changing itself is done by a coding-agent Proposer: it reads failure trajectories, locates which file to edit, and lands a structured change as a new candidate's tunable artifacts — the way a human would edit code.

It delivers — the best candidate's tunable artifacts: a real directory of files you can diff, review, and deploy, with a change lineage attributing every edit to the failure evidence that motivated it.

🤖 Skills

skills/ ships per-scenario Agent Skills: hand one to your coding agent and it drives the experiment setup for you — interviews you for the few facts only you know (repo, dataset, metric), then picks components, writes the entry script, launches the run, and triages failures against its built-in pitfall log. It currently contains eddy-antomnievo-experiment (for the eddy high-code agent runtime; content in Chinese) — follow it as a template to distill your own scenario's best practices into a skill of your own.

📚 Documentation

🧪 Paper Resources

The paper's experiment scripts, artifacts before and after evolution, and datasets are open-sourced at ant-research/AntOmniEvoDatasetsAndScripts.

📄 Papers

If you find this work useful, please cite the relevant paper:

  • Mara Chain: Rethinking Failure as a Stepping Stone for AI System Auto-Evolution

    @misc{lyu2026marachain,
          title={Mara Chain: Rethinking Failure as a Stepping Stone for AI System Auto-Evolution},
          author={Yubin Lyu and Fu Li and Jiawei Fei and Yang Zhao and Weixing Mei and Yinan Wu},
          year={2026},
          eprint={2609.35855},
          archivePrefix={arXiv},
          primaryClass={cs.LG},
          url={https://arxiv.org/abs/2609.35855},
    }
    

License

Licensed under the Apache License 2.0. Legal disclaimer: see LEGAL.md.

// HOW IT'S BUILT

// FILES

11 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/eddy-antomnievo-experiment/SKILL.md73 KB32b1e9e9585ftruncatedupstream ↗

    Showing the inlined prefix. The rest is in the upstream file.

    ---
    name: eddy-antomnievo-experiment
    description: 主动沟通型的 AntOmniEvo 优化实验搭建助手的前置步骤集——帮用户把某个 eddy 业务 agent 接入 AntOmniEvo:对齐实验根目录(exp_root)与 candidate store 目录(两个概念分开)、创建 venv、装 AntOmniEvo、读 README 选 example;对齐数据格式并在 antomnievo/dataset 写 data_inst + data_loader;和用户对齐 agent module 在哪、启动入口、要优化哪些文件,照 example 可调产物写 AntOmniEvo 可调产物;在业务项目 scripts 写 generate(做 load 可调产物)和 evaluate;检查业务仓库代码 venv;冒烟测试并把产物路径给用户确认。当用户要"为某个 eddy 业务 agent 搭 AntOmniEvo 优化实验""接入 AntOmniEvo""写 generate/evaluate""先搞数据再写 gen/eval"、或想开始 AntOmniEvo 实验搭建时使用。
    user-invocable: true
    ---
    
    # 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 
  • skills/eddy-antomnievo-experiment/references/context-recovery-recipe.md4.6 KB713b2c0d86d4upstream ↗
    # 上下文恢复配方(长跑优化 → 用户清上下文后)
    
    优化是长会话(max_iterations × batch = 数天甚至数周)。用户清上下文/重启对话后,执行者不会记得上次跑到哪。
    
    > 目录概念(见 SKILL.md『两个目录概念』):`<exp_root>` = 实验根目录(NOTES.md/config/run.env 在这);`<run_dir>` = candidate store 的单次 run 目录(`<candidate_store_root>/run_<ts>/`,candidates//logs/statistics.json 在这)。
    
    ## 1. 保存动作(每次跑优化或跑完必做)
    
    在 `<exp_root>/NOTES.md` 追加 `## 优化运行 <时间戳>`:
    
    1. 路径:`<run_dir>` + config YAML + log + statistics.json
    2. 配置摘要:smoke / eval_stage / hyperparams / proposer model / budget
    3. **config YAML 里所有 credential 的过期时间**:遍历 `system.*` 和 `proposer.*` 里所有 token-like 字段(以 `eyJ` 开头的 JWT),用 python decode `exp` claim 记录;非 JWT 的 credential 标"非过期型,无需检查"。如果离过期 <2h → 立刻提醒用户换 credential。
    4. 运行状态:current_iteration / accepted / rejected / best_candidate_id / best batch sum(via statistics.json + grep log)
    5. 遗留事项(比如"可调 min_improvement_per_batch 加速";"credential N 小时后过期需换")
    
    ## 2. 恢复操作(新上下文第一步)
    
    ```bash
    # 1. 读 NOTES.md(最快的恢复入口: 路径+配置+状态+遗留事项一目了然)
    cat <exp_root>/NOTES.md
    # 2. 读 statistics.json: current_iteration / best_candidate_id / avg_score
    python3 -c "import json; s=json.load(open('<run_dir>/logs/statistics.json')); print(s)"
    # 3. tail log: 看最新进展(iteration / scores / accepted / rejected)
    tail -20 "<run_dir>/optim_*.log"
    # 4. grep batch scores: Parent→Child improvement 历史
    grep -E "Parent.*scores|Child.*scores|accepting|rejecting" "<run_dir>/optim_*.log"
    # 5. 看是否还在跑
    pgrep -af "<entry script pattern>"
    # 6. 如果停了: resume = 同 --config (config 里 <run_dir> 不变 → AntOmniEvo 自动 resume from checkpoint)
    ```
    
    ## 3. credential 过期检测(通用,不只针对某个 token)
    
    - 遍历 config YAML 里所有 credential 字段(system.* + proposer.*),用 python decode JWT exp claim(如果是 JWT);非 JWT 的 credential 不需要检查。
    - **batch scores 突然从高跌到低(如高分突降为异常低分) = credential 过期的典型症状** → 第一步检查 credential 是否过期 → 从用户拿新 credential → 更新 config YAML + 重物化 `run.env` → resume。
    
    ## 4. 蚂蚁内部 MCP credential 过期 → 主动诊断 + 引导用户换 token
    
    章节前提:蚂蚁内部 MCP(adconfig MCP / <your-mcp-server-host>)的 JWT token 有效期 24h,过期后 agent 拿不到 MCP 资源 → batch score 从高跌到低。此章节含两步:主动诊断 + 引导用户去签发新 token。
    
    ### 4.1 什么时候怀疑 MCP credential 过期
    
    如果优化跑着跑着 batch score 突然从高分异常跌到低分,或者 process judge reason 中出现以下关键词,第一个要排除的是 **MCP credential 过期**:
    
    - `MCP_ERROR` / `McpError` / `认证不可用` / `无员工身份` / `403` / `身份` / `token 过期`
    - agent 日志里 MCP connect failure(traceback `connect_to_server / failed for server`)
    
    → **执行者主动跟用户说**: "batch score 异常从高分跌到异常低分, 看起来是 MCP credentials(token)过期了 — agent 拿不到 MCP baseline, process judge 批仅给低分。你能否去以下地址重新签发 MCP token?"
    
    ### 4.2 蚂蚁内部 MCP token 换取(用户操作步骤)
    
    1. 打开签发页: `https://<your-intranet-sso-host>/pub/oauth/AppAuthorize.htm?token=<app-token>` (token 参数可能更新; 问用户最新的 URL)
    2. 在页面输入栏输入 MCP server host: `<your-mcp-server-host>`
    3. 页面签发 JWT 身份凭证 = 你的 `system.iam_token` 值
    4. 把签发的 token **原值**贴给执行者(不要手敲 → silent corruption;copy-paste)
    5. 执行者用 python 精确更新 config YAML + `.env.local` + 重物化 `<run_dir>/run.env`:
       ```python
       import yaml, os
       cfg = yaml.safe_load(open("opt_config.yaml"))
       cfg["system"]["iam_token"] = "<用户贴过来的原值>"
       yaml.dump(cfg, open("opt_config.yaml", "w"), allow_unicode=True, default_flow_style=False, sort_keys=False)
       # 更新 .env.local 的 IAM_TOKEN=\<新原值>
       # 重物化 <run_dir>/run.env 追加 IAM_TOKEN=\<新原值>
       ```
    6. **resume**: 同 `--config opt_config.yaml`(config 里 `<run_dir>` 不变 → AntOmniEvo 自动 resume from checkpoint;不用停现行程 — 下一个 candidate 的 generate.py 会自动读新 run.env)
    7. **不要手敲 credential** (长 JWT 手敲易错 → 一字符错 → MCP 持续 403); 用 python 按精确值替换 + decode exp 验证。
  • skills/eddy-antomnievo-experiment/references/data-layer-recipe.md5.0 KB387d264939eaupstream ↗
    # 数据层配方 (data_inst + data_loader)
    
    新领域接入 AntOmniEvo 的数据层(对应 SKILL.md 步骤 2)。范式对照 `antomnievo/dataset/<既有某 domain>/` 任选一份(结构/契约对齐,别照字段)。
    
    ## 基类契约
    
    `antomnievo.interface.data_inst.DataInst` 是 pydantic `BaseModel`,只强求三字段 + 算个 `.name`:
    
    ```python
    class DataInst(BaseModel):
        id: str         # 数据实例标识
        query: str      # 输入问题/需求
        golden_answer: str  # ground truth(结构化对象先 json.dumps 成字符串)
        @property
        def name(self) -> str: return self.__class__.__name__
    ```
    
    子类只管加领域字段 + 重数据留 `raw`。
    
    ## 文件清单(放组件目录 `<exp_root>/antomnievo/<scenario>/dataset/`;不改已装的包)
    
    ```
    <exp_root>/antomnievo/<scenario>/dataset/
      __init__.py
      <domain>_data_inst.py        # <Domain>DataInst(DataInst)
      <domain>_dataset_loader.py    # async load_dataset(...)
    ```
    
    ## `<domain>_data_inst.py` 模板(结构对照所选既有 domain 的 `*_data_inst.py`)
    
    ```python
    from __future__ import annotations
    import json
    from pydantic import Field
    from antomnievo.interface.data_inst import DataInst
    
    
    class <Domain>DataInst(DataInst):
        """<领域> case 数据实例。范式:<输入> → agent 产出 <产物> → 与 <gold> 比对。
    
        原始 case 行整行留在 ``raw``(``exclude=True``,不进 RunRecord),
        供 to_case_dict 原样回写 _batch.jsonl——子进程常要原始全字段。
        """
    
        category: str = Field(default="", description="Case 分类,供 proposer 参考")
        # ……其它领域分析用字段
        raw: dict = Field(default_factory=dict, exclude=True)
    
        def to_case_dict(self) -> dict:
            return self.raw
    
        @classmethod
        def from_raw(cls, raw: dict) -> "<Domain>DataInst":
            case_id = raw.get("case_id", "") or raw.get("id", "")
            inp = raw.get("input", {}) or {}
            query = str(inp.get("user_request") or inp.get("query") or "")
            # 回放/约束上下文按该领域实际位置取
            # gold:可能直接答案,也可能结构化对象
            expected = raw.get("expected", {}) or {}
            golden_answer = json.dumps(expected, ensure_ascii=False)  # 整体结构化 -> str
            category = str(raw.get("category", ""))
            return cls(id=str(case_id), query=query, golden_answer=golden_answer,
                       category=category, raw=raw)
    ```
    
    ## `<domain>_dataset_loader.py` 模板
    
    ```python
    import json, logging, os, random
    from antomnievo.dataset.<domain>.<domain>_data_inst import <Domain>DataInst
    logger = logging.getLogger(__name__)
    
    async def load_dataset(cases_jsonl: str, max_samples: int = 0, shuffle: bool = False) -> list[<Domain>DataInst]:
        if not os.path.isfile(cases_jsonl):
            raise FileNotFoundError(cases_jsonl)
        result = []
        with open(cases_jsonl, encoding="utf-8") as f:
            for line in f:
                line = line.strip()
                if not line: continue
                try: raw = json.loads(line)
                except json.JSONDecodeError as e: logger.warning(f"Skip malformed: {e}"); continue
                if not (raw.get("case_id") or raw.get("id")): logger.warning("Skip no-id"); continue
                result.append(<Domain>DataInst.from_raw(raw))
        if max_samples > 0: result = result[:max_samples]
        if shuffle: random.shuffle(result)
        logger.info(f"Loaded {len(result)} <domain> cases from {cases_jsonl}")
        return result
    ```
    
    ## 抽取要领(结构对照所选既有 domain)
    
    从所选既有 domain 的 `*_data_inst.py:from_raw` 学**抽取手法**(**别套字段名**),再按新领域**实际样本**改:
    - `id` ←  case row 的唯一标识字段(pos: `case_id`/`query_id`/`id`…)
    - `query` ←  输入字段 + (如有)回放/约束 extra_context 拼进去
    - `golden_answer` ←  gold 字段(结构化对象先 `json.dumps` 成 str,基类要 str)
    - 可选分析字段(类目/难度…)
    - `raw` ←  整 case 行(供 `to_case_dict()` 回写)
    
    ## 坑
    
    1. **`golden_answer` 必须是 str**。若 gold 是结构化对象/列表,先 `json.dumps`。后续 evaluate 再按领域逻辑反序列化比对。
    2. **重数据留 `raw` + `exclude=True`**。不要为了"好看"把整个 case 摊成几十个 pydantic 字段——会爆、会丢类型、会难回写。`to_case_dict()` 原样回原始行。
    3. **先对齐再写**:实际读样本确认字段名/嵌套层级,**别照别的领域猜**。新领域的字段结构(输入/gold/extra)与既有 domain 可能完全不同 —— 以你和用户读样本后确认的为准。
    4. **load_dataset 是 async**:AntOmniEvo 框架按 await 调。纯文件读取但签名也要 `async def`。
    5. **registry**:若 `antomnievo/dataset/__init__.py` 或别处有域名登记,记得按同样方式注册新域名,否则入口找不到。
    
    ## sanity check(写完立刻自测)
    
    ```bash
    python -c "import asyncio;from antomnievo.dataset.<domain>.<domain>_dataset_loader import load_dataset as L;\
    r=asyncio.run(L('<test_path>', max_samples=3));\
    print(len(r));print(r[0].id, r[0].query[:40], r[0].golden_answer[:40]);assert all(x.id and x.query for x in r)"
    ```
    N 条、`id/query/golden_answer` 都非空即过。
    
  • skills/eddy-antomnievo-experiment/references/entry-recipe.md14 KBbfa0f30ed8a9upstream ↗
    # AntOmniEvo Example 入口脚本编写配方(步骤 10)
    
    对应 AntOmniEvo 的**入口脚本**:把 System + Evaluator + Optimizer + Proposer + EA +
    CandidateStore 装起来、跑 `await optimizer.optimize()`。**所有配置(含 secrets)
    放一个 workspace YAML 文件,入口加载,绝不硬编码 secrets。**(本配方是对标
    `antomnievo/example/text2sql/birdtest_text2sql.py`;但 text2sql 把 secrets 读 env + 写
    码里,本配方要求集中到 workspace YAML。)
    
    ---
    
    ## §0 放哪
    入口脚本:`<exp_root>/antomnievo/<scenario>/<domain>_optimize.py`(组件目录的场景包,统一约定;参照结构读已装包里的 `antomnievo/example/text2sql/`)。
    配置 YAML(含 secrets):**`<exp_root>` 下**,一个专门文件(如 `<exp_root>/opt_config.yaml`),入口 `--config` 加载。**别**放业务仓库 / 别提交。
    
    ---
    
    ## §1 先读
    - 入口范本 `antomnievo/example/text2sql/birdtest_text2sql.py`(wire System+Evaluator+Proposer+EA+CandidateStore+Optimizer + `optimize()`,怎么 `import`/构造/`config.yaml` 加载)。
    - 你的 System(步骤 7)/Evaluator(步骤 8)/Optimizer 子类(步骤 9)的**构造参数** —— 入口要用;kwarg 签名已在 7/8/9 对齐。
    - agent proposer(抽象名;`antomnievo/proposer/` 里 `BaseProposer` 的具体实现,以已装包实际为准、不写死实现名)构造(tunable_artifact_schema/candidate_store/evaluator/system/api_key/base_url/model/provider/... 以所选实现签名) → 你要的 proposer 配置(YAML `proposer.*` + tunable_artifact_def)。
    - `ParetoFrontierEvolutionAlgorithm`/`Budget`/`LocalCandidateStore` 构造。
    - **tunable_artifact_def**(步骤 3 或本步写,`<exp_root>/antomnievo/<scenario>/tunable_artifact_defs/<domain>_tunable_artifact_def.py`)→ 喂给 proposer。
    - 看 `Optimizer.optimize()` 主循环背的依赖 → 确认你入口备全(train/val/budget/initial_artifacts_dir)。
    
    ---
    
    ## §2 怎么写
    
    ### 主动问用户要配置(别硬编码)
    入口要的 secrets/config **让用户提供**,你**主动问**(不猜):
    1. **proposer**:`api_key` + `base_url`(+ `model`/`provider` 等,以所选实现签名,可问默认)。**proposer 固定用 pi 实现**(不让用户选 claude —— claude 目前有问题):**先确认 `pi` CLI 装了**(`which pi`,没装 → `npm install -g @mariozechner/pi-coding-agent`,需 Node ≥ v22.22.1,装完 `pi --version` 确认)。
    2. **system**(agent/mcp 跑要的,看项目主进程读的 env 名):模型 key(本项目 `THETA_API_KEY`)+ MCP 身份 token(本项目 `IAM_TOKEN`)。
    3. 路径(repo/源码仓库/cases/schema_manifest)+ workspace_dir + `initial_artifacts_dir`/`tunable`。超参不问用户,先用默认(batch_size/num_proposals 用 Optimizer 默认);预算跟用户讲清支持的类型(`max_iterations`/`max_rollouts`/`max_system_runs`/`max_tokens`/`max_elapsed_seconds`),**默认时间预算 8 小时**(`max_elapsed_seconds: 28800`),并告诉用户调参位置 = config YAML 的 `hyperparams` 段。
    用户告诉你 → 你写 YAML;或用户直接给文件你接。收齐后**自查缺不缺**(入口 `--check-config` 列缺失),少了让用户补,最终加载进 YAML。
    
    ### ⚠ workspace_dir:实验目录(不是单一 workspace,是一个父目录下的 timestamped 子目录)
    
    `workspace_dir` 在 YAML 里指向 **一个带时间戳的实验子目录**(不是父目录)。AntOmniEvo 的 `LocalCandidateStore` 初始化时:目录不存在 → 新建(fresh);已存在且有 `statistics.json`+`root_candidate_id` → **自动续跑**(resume)。
    
    ```
    opt_workspace/                         ← 父目录(放很多次不同实验)
      run_20260829_200011/                 ← 实验 1(timestamped)
        candidates/                         ← candidate store
        logs/                                ← optimizer 日志
        statistics.json                      ← Optimizer 统计(有 root_candidate_id → resume)
        run.env                              ← 物化的 THETA/IAM
        optim_*.log                          ← 运行日志
      run_20260901_120000/                 ← 实验 2(timestamped,新的)
        ...
    ```
    
    YAML:
    ```yaml
    workspace_dir: /Users/jacklv/<repo>/opt_workspace/run_20260829_200011   # ← 指向 timestamped 实验子目录
    ```
    
    - **续跑同个实验**:用**同一** `workspace_dir`(同一个 timestamped 子目录路径)。AntOmniEvo 检查 `statistics.root_candidate_id`(README §8:存在 → 续跑跳 root baseline;不存在 → 从头建)。
    - **开新实验**:换成**新** timestamped 子目录(`run_<新时间戳>/`)。老实验的目录留着不动。
    - **不需要 flag**:resume 是 AntOmniEvo 的内置行为 —— `workspace_dir` 有数据就 resume,没数据就新建。**唯一要注意的就是路径**(README §8 原文:"续跑就用同一入口脚本、同一 workspace_dir。重新跑就换一个带时间戳的 workspace_dir。")。
    
    ⚠ `initial_artifacts_dir` ≠ `--agent-src`(agent module)!`initial_artifacts_dir` 是用脚本从 agent module **只抽出可调部分**生成的干净 artifact 目录:
    ```bash
    # scripts/extract_initial_artifacts.py — 抽取可调产物
    python scripts/extract_initial_artifacts.py \
      --agent-src src/<pkg> \  # agent module 包根
      --tunable <entry1> \   # 步骤 3 对齐的可调条目(e.g. agents),可重复
      --output <workspace>/initial_artifacts  # 输出
    ```
    - **为什么**:LocalCandidateStore `create_root` 整树 `copytree`(只 ignore `__pycache__`)→ 把 `initial_artifacts_dir` 整份拷进每个候 → 跑代留下基线快照。如果你把 `initial_artifacts_dir` 设成整个 agent module,会把 config/ + knowledge_data/*.jsonl(重数据)+ main.py/app.py(平台 bootstrap)也拷进每个候选 → ① 重数据 × 候选 × rollout = 存储爆炸、② proposer 能碰非可调(破坏平台 bootstrap / 运行配置)。
    - **可调产物 ≠ agent module**:可调产物只是你跟用户对齐的**可调行为面**(步骤 3 — 如本项目的 `agents/` 子包);agent module 还包含**不可调**的 config/、knowledge_data/、main.py/app.py/solution.py(在 generate.py 的 `--agent-src` 里用,运行时代理包)。可调产物放 `initial_artifacts`,agent module 在 `--agent-src`,generate.py `--tunable <ent>` 把候选的可调 `<ent>` overlay 回运行期包跑(见步骤 4 load 可调产物)。
    - **脚本放 `scripts/extract_initial_artifacts.py`**(业务仓库);`--tunable` 用步骤 3 跟用户对齐的列表(e.g. `agents`);若用 `agents`+另一 `--tunable <another>`,脚本会拷两份,放进 `initial_artifacts/<ent>` 各自 pkg-rel path 位置。
    - 跑完脚本把 `<workspace>/initial_artifacts` 写进 YAML 的 `initial_artifacts_dir:` 即可;**`initial_artifacts_dir` 不能设成 `--agent-src`/`src/<pkg>`**。
    ```yaml
    # <workspace>/config.yaml — secrets do NOT commit.
    workspace_dir: <workspace>
    repo: <业务仓库>; local_source_repo: <项目源码仓库>
    cases: <cases jsonl>; schema_manifest: <prebuilt manifest>
    agent_src: <repo>/src/<pkg>; initial_artifacts_dir: <同左>; tunable: ["<可调根>"]
    system:  # entry 从这两条物化 <workspace>/run.env 给 generate.py --env-file
      python: <repo>/.venv/bin/python
      generate_script: <repo>/scripts/generate.py; evaluate_script: <repo>/scripts/evaluate.py
      theta_api_key: "..."   # REQUIRED (model key)
      iam_token: "..."       # REQUIRED (MCP 身份; 无 MCP 可省)
      timeout: 1200; concurrency: 1;  # + 项目特定 flag(看 evaluate.py --help + 跟用户对齐)
    proposer:
      api_key: "..."         # REQUIRED (coding-agent key)
      base_url: "..."; model: kimi-k2.5; pi_path: pi; provider: anthropic
      max_turns: 150; timeout: 3600; concurrency: 2
    hyperparams: {train_max, val_max, batch_size, max_iterations, num_proposals, max_reflection_iterations, min_improvement_per_batch}
    budget:
      max_iterations: 1000        # 迭代上限(必填,或用 hyperparams.max_iterations = 实际写法)
      max_tokens: 5000000         # LLM token 累计上限(安全网;None=不限,但建议设)
      max_elapsed_seconds: 86400  # 一天(安全网;None=不限,但建议设)
    evolution: {max_candidate_num: 3}
    ```
    必填 secrets(入口 `--check-config` 校验):`system.theta_api_key`、`system.iam_token`(用 MCP 时)、`proposer.api_key`、`proposer.base_url`、`proposer.model`(**model 没有默认值,用户必须认真填**)。
    
    ⚠ **`proposer.model` 不是可选的** —— 之前用了 `prop.get("model", "kimi-k2.5")` 给默认值,但你换了 LLM 网关(antchat / GLM)就填错 model 名 → 要么连不上,要么用错模型。现在 `--check-config` 必查它:缺了报 `missing required: ['proposer.model']` → 用户必须填(在 YAML 的 `proposer.model:` 里写真实 model 名,如 `GLM-5.2`)。
    
    ### 入口脚本(`<exp_root>/antomnievo/<scenario>/<domain>_optimize.py`)
    `argparse --config`(或 env `<DOMAIN>_CONFIG`/默认 `./config.yaml`)+ `--check-config`(只校验、不跑)→ `yaml.safe_load` → 校验必填 secrets → **物化 `<workspace>/run.env`**(从 `system.theta_api_key`/`iam_token` 写 `THETA_API_KEY`/`IAM_TOKEN=` 两行)→ 构造 `System(env_file=run.env)` + Evaluator + agent proposer(`BaseProposer` 具体实现以已装包为准;`tunable_artifact_schema=<tunable_artifact_def>, ..., api_key/ base_url/ model/... = YAML`) + `ParetoFrontierEvolutionAlgorithm` + `LocalCandidateStore(workspace_dir)` + `<Domain>Optimizer(..., initial_artifacts_dir=...)` → `len(train)=train_max`/`val` 顺序子集切 → `await optimizer.optimize()`。**绝不**在代码里 `api_key="..."`。
    
    ---
    
    ## §3 坑
    1. **别把 secrets 写进代码** —— 放 workspace YAML(`--config`),入口加载;别提交 YAML。
    2. 配置**主动问用户**、收齐 `--check-config` 查缺(必填缺就停,让用户补)。
    3. **`run.env` 由入口从 YAML `system.*` 物化**(generate.py `--env-file` 读),**单源 = YAML**(别同时硬填 `.env.local`,否则两源打架)。
    4. **proposer 需 `pi` coding-agent CLI**(装好)+ proposer key;全量 `optimize()` 还要 model key + MCP 权限 + sandbox 仓库 + schema manifest + 大开销(每候选真跑 agent + LLM 改可调产物),**别误跑**;先 `--check-config` 再小 budget。
    5. **数据集对齐**(train/val 哪来 / 本地 / 云端 / 格式跟步骤 2 对齐 / val 可能空) —— **主动跟用户对齐** THEN 在 YAML `hyperparams` 里写 **真跑数量**(`train_max`=用户对齐的数(如 98);`val_max` 默认 0 = 空 val)。`cases`(gold 文件路径)。⚠ **不要在代码里给 `val_max` 非 0 默认**(我之前默认 2,矛盾,已改 0)。
    
        ⚠ **冒烟数据量别改 hyperparams——用 `smoke: true` 开关 override**:
        - YAML 顶层加 `smoke: true` → 代码 override 到 `train_max=2, val_max=0, max_iterations=1, num_proposals=1, batch_size=1`(**快速冒烟**,不改 hyperparams)。
        - 冒烟完 → YAML 改 `smoke: false` → 用 hyperparams 里的真跑数量(**自动恢复**到对齐的量)。
        - **为什么不改 hyperparams 冒烟**:改了数字冒烟完要手动恢复,容易忘 → 我之前就写成 train=2 忘了恢复。开关隔离了冒烟 vs 真跑 ——hyperparams 永远是对齐的真跑数量,smoke 只是把数据量临时 override 小。
    6. 路径全绝对(通用约定)、测试 workspace 没 → `/tmp`(通用约定)。
    7. `system_description`(步骤 7)/`scoring_criteria`(步骤 8)已写好 → proposer 用,错或空→错误归因(通用约定)。
    
    ---
    
    ## §4 怎么验证
    1. **`--check-config`**:列必填 secrets 缺不缺(没少才跑);列出缺的 optional 字段(会回退默认)。
    2. **小 budget `optimize()`**(可能/重):`max_iterations=1`、`train≈2`、`val≈1`、`num_proposals=1` 跑一次 —— 看根 baseline → proposer 改可调产物 → 子候选 跑+评 → 比较/淘汰 循环通(proposer CLI + 全前置就绪后)。
    3. 再放大 budget,关注 Pareto/采纳数 + token/时间预算。
    
    ### ⚠ `eval_stage`(全量 vs 快档)—— 选择 + 持久化路径
    
    - `eval_stage` 是**你的 evaluate.py 接受的 stage flag** —— 看项目 `--help`,跟用户讨论用哪个 (e.g. fast "deterministic" vs full "all" 是一个项目对 evaluate.py 可能的两种调用形态,但具体名字 + 跑什么 + 产出什么是项目-specific 的)。**Skill 不预设 stage 名 / 跑什么 stage 内容 / 产出什么文件** —— 看 `scripts/evaluate.py --help` + 跟用户确认。
    - **从 fast → full 的通用 trade-off**:fast(e.g. 一档)是走快路径快速给 optimizer 信号;detailed(e.g. full + LLM judge + runtime)慢(~分钟/case vs ~秒/case);**在 optimizer loop 跑 detailed 档,每候选 evaluation 变慢 → optimizer 迭代慢** → 跟用户讨论你需要 fast 还是 detailed 作为 optimizer 的 metric 而不是 skill 预设。
    - ⚠ **optimizer 的 `_run_and_evaluate` 把 gen + eval 产物持久化到 workspace**(`workspace/<candidate_id>/<batch_label>_<timestamp>/{generate,evaluate}/`,不用 tempfile),evaluate 产物不删 —— 这样用户在 workspace 里就能看 evaluate.py 写出的完整 multi-stage 报告 (per-case details / report / 各 stage 中间产出),不用再跑一遍。LLM judge 等中产物都跟着 persist;**这是通用方法论,不是 skill 决定跑哪 stage**。
    
    ### ⚠ val=0 时怎么看结果(关键)
    当 `val_max=0`(val 空):
    - **`summary.json` 的 `avg_score` 始终 0**(无 val → `_step_validate` 跑空 → `0/0 fallback = 0`),**不能用 avg_score 判断"优化了没"**。
    - **看优化器日志里每个 iteration 的 batch 对比**:
      ```
      Parent <id> scores: [case_id=0.6, ...], Child <id> scores: [case_id=0.8, ...]
      New candidate <id> ... (new=2.4, old=1.8, threshold=0.5), accepting / rejecting
      ```
      - `old` = parent 在 train batch 的分数和 → `new` = child 在同 batch 的分数和 → `improvement = new - old`。
      - `improvement >= threshold` → 采纳(child 确实 iterative 变好了)→ 进入下一 iteration。
      - `improvement < threshold` → 拒绝 → EA 选下一候选再试。
    - **per-iteration 的 batch improvement 才是 val=0 时的优化信号**:每一轮 `old → new → improvement` 是你要看的东西;不是 summary.json.avg_score(那是 val 的,空=0)。
    - 这就是你为什么要跟用户对齐 "train 用多少数据" —— train batch 上的分数提升 = 你的优化效果度量;val=0 时,优化循环仍然可以通过 train batch improvement 接纳更优候选。
    
    ---
    
    ## §5 ad-config 实例代码位置(请直接读代码,不在此拆业务细节)
    - 入口: `antomnievo/example/adconfig/adconfig_optimize.py`
    - tunable_artifact_def: `antomnievo/model/tunable_artifact_defs/adconfig_tunable_artifact_def.py`
    - 初始可调产物抽取: `scripts/extract_initial_artifacts.py`
    
  • skills/eddy-antomnievo-experiment/references/evaluator-recipe.md7.2 KBfe6bd62341e9upstream ↗
    # AntOmniEvo Evaluator 模块编写配方(步骤 8)
    
    对应 AntOmniEvo 优化循环里的 **Evaluator**:接 System 的 predictions,打分(`score∈[0,1]` + `reason`)给优化循环选优 / 淘汰。本配方主要覆盖**"评分 = 调外部 evaluate.py 子进程"**形态(对标 text2sql;本项目 evaluate.py 就是这种)。其它形态(自带 scorer / in-process)照最像的一份 example 改结构。
    
    > 接在步骤 7(System)之后;System + Evaluator 配套(optimizer 子类步骤 9 串起来)。
    
    ---
    
    ## §0 放哪 —— 组件目录(同步骤 7,统一约定)
    - `<exp_root>/antomnievo/<scenario>/evaluator/<domain>_evaluator.py`(跟 System 同一场景包;参照结构读已装包里的 `antomnievo/evaluator/text2sql/` 等,不改已装的包)。
    放哪在步骤 7 / system-recipe §0 已定;Evaluator 跟着走。
    
    ---
    
    ## §1 先读:看清 Evaluator 契约 + 找最像的 example
    1. `antomnievo/interface/evaluator.py` — `Evaluator(ABC)`:`_evaluate(data_inst, system_result) -> EvaluationResult` 抽象;基类有 `run` / `evaluate_batch`(gather)、`scoring_criteria()` 抽象(返 str,注入 proposer prompt)。看清 `_evaluate` vs `evaluate_batch`。
    2. `antomnievo/model/evaluation_result.py` — `EvaluationResult{data_id, metric_name, score∈[0,1], reason, usage}`。
    3. **最像的 example**(子进程 evaluate 形态)→ `antomnievo/evaluator/text2sql/text2sql_evaluator.py`(它 override `evaluate_batch` 跑 evaluate.py 子进程、读 per-case 产物文件建 `EvaluationResult`)。看它怎么拼命令、读回产物、解析 score+reason。
    4. **项目的 `scripts/evaluate.py` CLI + 输出**:看 `--help`(收什么 flag、跑什么 stage、写什么 output file)、⚠ **实读一份真 per-case 产物文件**确认 score / reason / id 键名 —— 别假设,每项目不同。
    5. **看 optimizer 怎么调 evaluator**:`antomnievo/optimizer/optimizer.py` 的 `Optimizer._run_and_evaluate` 调 `evaluator.evaluate_batch(data_list, results)` **不传任何 kwargs**(纯 in-process 默认);scenario 子类 override 它、传 `output_dir`+`predictions_path`+`cases_path`。**你 Evaluator 的 `evaluate_batch` 签名要跟步骤 9 optimizer 子类对齐。**
    
    ---
    
    ## §2 怎么写(子进程 evaluate.py 形态,对标 `Text2SQLEvaluator`)
    - **override `evaluate_batch`**(不是 `_evaluate`):签名 `evaluate_batch(self, data_list, system_results, *, output_dir, predictions_path, cases_path, **kwargs) -> list[EvaluationResult]`(kwargs 跟你的 optimizer 子类对齐)。
    - **构造参数**(全**绝对路径**):`evaluate_script`、`python_path`(业务项目 venv python;evaluate.py 的 deps 在那)、`timeout`、`extra_args`;项目需要的话有项目特定的 flag(如 `schema_manifest`、`eval_stage`、`accuracy_threshold` 等 —— 看你 evaluate.py `--help` + 跟用户对齐,**别预设什么 flag**)。
    - **拼命令**:`[python_path, evaluate_script, --predictions <predictions_path>, --cases <cases_path>, --output <output_dir>]` + 项目需要的项目特定 flag(从 `--help` 确认后加) + extra_args。
    - **跑子进程**:`subprocess.run(cmd, capture_output=True, timeout=timeout)` 经 `loop.run_in_executor`(别阻塞 event loop);rc≠0 记 stderr 但不 raise(继续读产物)。
    - **读回** `<output_dir>/`<你 evaluate.py `--help` 说写的 per-case 产物文件> → 按 per-case id 键建 dict;`data_list` 每条按 `data_inst.id` 匹配 → `EvaluationResult(data_id, metric_name, score, reason)`;**缺该 case → score=0 / "no evaluation detail"**。
    - **score 归一化到 [0,1]**(项目 metric 可能 0–100 / EX×… 等 → 除上限 / 按项目确认);**`system_results` 不消费**(评分读 predictions 文件,同 Text2SQLEvaluator)。
    - **`_evaluate`** raise NotImplementedError(batch-only,别 pass)。**`scoring_criteria()`** 准确反映 evaluate.py 打分机制(见 SKILL『通用约定』)。
    
    ---
    
    ## §3 坑(本形态 / 实测)
    1. **generic `Optimizer` 不传 kwargs** → 配套写 optimizer 子类(步骤 9)给 `evaluate_batch` 传 `output_dir`+`predictions_path`+`cases_path`;Evaluator 签名收这三个 kwarg。**别只写 Evaluator 不写 optimizer 子类**,否则 `evaluate_batch(data_list, results)` 没参数跑不了。
    2. **`predictions_path` = System 的 `<gen_dir>/predictions.jsonl`;`cases_path` = batch cases(全行带 gold,`to_case_dict()` 写,同步骤 7)** —— evaluate.py 读 `--cases` 的 gold。
    3. **per-case 产物的 score/reason/id 键以实读为准** —— 别假设键名;每项目不同。先实读一份真 per-case 产物文件(per-case 产物 = 你 evaluate.py `--help` 说写的那个文件 —— 看项目的,不假设文件名 / 键名)。
    4. **score 必须归一化到 [0,1]**(optimizer 要 [0,1] metric;项目 metric 可能是 0–100 / EX×(0.7+0.3*VES) → 按项目确认归一方式)。
    5. **reason 要有信息量**(指名漏改 / 错改 / 多改哪个字段);空 / "correct" fallback = 坏信号(应来自项目 evaluator 的 detail 文案)。
    6. **`eval_stage`**(项目特定的 stage flag,看你 evaluate.py `--help` 支持哪些 stage):fast 档(无 LLM,快)适合优化循环;detailed/full 档(可能含 LLM judge / runtime)慢 → 用不用、用哪档跟用户讨论 trade-off。**skill 不预设 stage 名**。
    7. **项目特定前置 flag**(如 `--schema-manifest` / `--source-repo` 等):按你 evaluate.py `--help` 需要 + 跟用户对齐(**skill 不预设**);如果项目 evaluate.py 跑某阶段需要某个前置输入(如 pre-built manifest / repo path),没传就跑不下去 → 在构造参数 + YAML config 里都列上,跟 System 共用。
    8. **`scoring_criteria()` 要机制准确**(见 SKILL『通用约定』;拿什么比、分数语义 0/1 各代表什么、reason 来源、依赖什么前置如 schema manifest)—— 错或空让 proposer 错误归因。
    9. **`_evaluate` raise NotImplementedError**(别 pass → 误调用静默返回 None)。
    10. 路径全绝对;eval 输出按『通用约定』放 `<smoke dir>/eval` 子目录(没 workspace → `/tmp`),保留不清给用户回看。
    
    ---
    
    ## §4 怎么验证写对了
    1. `import` + `issubclass(X, Evaluator)` + `scoring_criteria()` 非空。
    2. **离线**用一份真 per-case 产物文件(从之前 evaluate 跑留的产出,或步骤 6 冒烟的 `eval/`)喂 `_read` / 解析逻辑 → 验 `EvaluationResult` 字段对(score/reason/id 键对、score∈[0,1])—— 直接验真 schema,省一次 evaluate.py 跑。
    3. **端到端** `evaluate_batch` 1 case 冒烟:复用步骤 7 System 冒烟的真产物(`<smoke dir>` 的 `gen/predictions.jsonl` + batch cases),`output_dir` 放 `<smoke dir>/eval`(没 workspace → `/tmp`),`await evaluator.evaluate_batch(...)`;断言:返回 `EvaluationResult` 数==batch 数、`data_id` 对、`score∈[0,1]`、`reason` 非空、(已知正确的 case)score 应高;evaluate.py 落盘的产物文件可看。
    4. 修 bug 后**离线复验**(不必重跑 evaluate.py)。
    
    ---
    
    ## §5 ad-config 实例代码位置(请直接读代码,不在此拆业务细节)
    - Evaluator: `antomnievo/evaluator/adconfig/adconfig_evaluator.py`
    
    ---
    
    ## §6 配套
    optimizer 子类(步骤 9)怎么把 System + Evaluator 串进 `_run_and_evaluate`(造 tempdir → 写 batch cases → `system.run_batch(output_dir, cases_path)` → `evaluator.evaluate_batch(output_dir, predictions_path, cases_path)`)见后续 optimizer-recipe(待写)。Evaluator 的 `evaluate_batch` 签名务必和它对齐。
    
  • skills/eddy-antomnievo-experiment/references/generate-evaluate-recipe.md37 KB9444cf2e730fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/eddy-antomnievo-experiment/references/optimizer-recipe.md8.4 KBb567eccee4b0upstream ↗
    # AntOmniEvo Optimizer 子类编写配方(步骤 9)
    
    对应 AntOmniEvo 优化循环里的 **Optimizer 子类**:override `Optimizer._run_and_evaluate`,把 System.run_batch + Evaluator.evaluate_batch 经 kwargs 串起来、每候选一个 tempdir 跑+评。(入口脚本 + tunable_artifact_def + config 是步骤 10,见 `entry-recipe.md`。)
    
    ---
    
    ## §0 放哪 + 用默认还是扩展?(关键决策,看 generate/evaluate 的输入输出)
    
    **放哪**:组件目录(同步骤 7,统一约定)—— optimizer 子类 → `<exp_root>/antomnievo/<scenario>/optimizer/<domain>_optimizer.py`,入口 → `<exp_root>/antomnievo/<scenario>/<domain>_optimize.py`。
    
    **用默认还是扩展?** —— 看你(步骤 4)写的 generate.py / evaluate.py 的输入输出:
    - **子进程 + 文件路径 I/O**:generate 取 `--cases`/`--output-dir`/`--artifact-dir`,evaluate 取 `--predictions`/`--cases`/`--output` —— 默认 `Optimizer._run_and_evaluate`(调 `system.run_batch(meta, data_list)` + `evaluator.evaluate_batch(data_list, results)` **不传任何 kwargs**,纯 in-process)给不出这些路径 → **必须 subclass + override `_run_and_evaluate`**(造 tempdir → 写 batch cases → thread `output_dir`/`cases_path`/`predictions_path`)。对标 `Text2SQLOptimizer`。
    - **in-process**:System/Evaluator 拿 `data_inst` 直接出 `SystemResult`/`EvaluationResult`、无文件 I/O —— 默认 `Optimizer` 就够,**别 subclass**(用通用约定里说的现成 `Optimizer(...)`)。
    
    本项目 generate/evaluate 都是子进程 → 要 subclass。**这个决策不是猜的,是看 generate/evaluate 实际要什么 I/O 得出的**。
    
    ---
    
    ## §1 先读:optimizer 契约 + 找最像的 example
    1. `antomnievo/optimizer/optimizer.py` —— `Optimizer`:`_run_and_evaluate(candidate_id, data_list) -> RolloutEvalResult`(默认调 `run_batch(meta,data_list)` + `evaluate_batch(data_list, results)` 不传 kwargs);`optimize()` 主循环(选优 → proposer → 比 → 淘汰 → 验证 → persist run-record → Budget)。看清楚默认 `_run_and_evaluate` 跟 `optimize()` / `_run_and_evaluate_wrapper` / `_save_run_record_list` 的分工(你 override 的是 `_run_and_evaluate`,persist/计数在 wrapper 里)。
    2. **最像的 example**(subclass 形态)→ `antomnievo/optimizer/text2sql/text2sql_optimizer.py`(`Text2SQLOptimizer._run_and_evaluate`:tempdir → 写 dataset_batch → `run_batch(output_dir, contexts_path)` → `evaluate_batch(output_dir, predicted_sql_path, contexts_path)`)。
    3. `Optimizer.__init__`(constructor 要什么):`system`/`proposer`/`evaluator`/`evolution_algorithm`/`candidate_store`/`train_dataset`/`val_dataset`/`batch_size`/`budget`/`num_proposals`/`max_reflection_iterations`/`min_improvement_per_batch`/`initial_artifacts_dir`。
    4. `ParetoFrontierEvolutionAlgorithm`(EA;`candidate_store`+`max_candidate_num`)、`Budget`(`max_iterations`/`max_rollouts`/...)、`LocalCandidateStore`(`workspace_dir`,`cleanup_unavailable`)、agent proposer(抽象名;`antomnievo/proposer/` 里 `BaseProposer` 的具体实现,以已装包实际为准、不写死实现名;`tunable_artifact_schema`/`candidate_store`/`evaluator`/`system`/`api_key`/`model`/... 以所选实现签名) —— 看构造参数。
    
    ---
    
    ## §2 怎么写(subclass + tunable_artifact_def + 入口)
    
    ### Optimizer 子类(override `_run_and_evaluate`)
    ```
    async def _run_and_evaluate(self, candidate_id, data_list) -> RolloutEvalResult:
        meta = self.candidate_store.get_meta(candidate_id)
        with tempfile.TemporaryDirectory(prefix=f"<domain>_{candidate_id}_") as tmp:
            gen_dir = tmp/"generate"; eval_dir = tmp/"evaluate"; mkboth
            batch_path = tmp/"cases_batch.jsonl"
            write batch cases = sorted(data_list, by id) -> each data_inst.to_case_dict() 每行
            results = await self.system.run_batch(meta, data_list, output_dir=gen_dir, cases_path=batch_path)
            predictions_path = gen_dir/"predictions.jsonl"
            evals = await self.evaluator.evaluate_batch(data_list, results, output_dir=eval_dir,
                                                        predictions_path=predictions_path, cases_path=batch_path)
        return RolloutEvalResult(results=results, evals=evals)
    ```
    - **kwarg 名要跟步骤 7/8 你写的 System/Evaluator 的 `run_batch`/`evaluate_batch` 签名对齐**(本例:`output_dir`/`cases_path`/`predictions_path`)。
    - batch cases **全行带 gold**(`data_inst.to_case_dict()`)—— generate 读 app/env/base_version、evaluate 读 `expected.artifact.changes`。
    - per-candidate per-batch 独立 tempdir(产物隔离)。
    
    ### tunable_artifact_def(`<exp_root>/antomnievo/<scenario>/tunable_artifact_defs/<domain>_tunable_artifact_def.py`)
    `TunableArtifactSchema = FolderSchema(name=<步骤 3 约定的可调根>, description=<本场景 agent 行为 + 树>, files=[FileSchema/FolderSchema ...])` + **约束段**(无冗余/矛盾、跨实例泛化、改后仍 `python -c "import <入口>"` 通过、保工具流+HITL、别耦合单 case、别动非可调的 runtime/重数据)。proposer 靠它 mut 可调产物。可对号已装包里 `antomnievo/model/tunable_artifact_defs/text2sql_tunable_artifact_def.py` 的结构(别套业务字段)。
    
    ### 入口脚本(跑 `await optimizer.optimize()`)
    装 System(步骤 7)+ Evaluator(步骤 8)+ agent proposer(抽象名;`BaseProposer` 具体实现以已装包为准,`tunable_artifact_schema=<tunable_artifact_def>, candidate_store, evaluator, system, api_key, ...`)+ Ea(`ParetoFrontierEvolutionAlgorithm`)+ `LocalCandidateStore(workspace_dir)`+ `<Domain>Optimizer(..., initial_artifacts_dir=<extracted artifact dir>)` → `await optimizer.optimize()`。train/val(无划分 → 顺序子集切先冒烟;正式分层按用户对齐)。对标 `antomnievo/example/text2sql/birdtest_text2sql.py`。
    
    ---
    
    ## §3 坑(实测得的)
    1. **默认 Optimizer 不传 kwargs** → 子进程形态必须 subclass(决策见 §0,看 generate/evaluate I/O)。
    2. batch cases **全行带 gold**(`to_case_dict`),否则 generate 读不到 app/env/base_version、evaluate 读不到 gold。
    3. **kwargs 签名跟步骤 7/8 的 System/Evaluator 对齐**(`output_dir`/`cases_path`/`predictions_path`)—— 名字对不上就 TypeError。
    4. per-candidate per-batch 独立 tempdir(产物隔离,别共用)。
    5. `_run_and_evaluate` **自己不 persist run-record**(`_save_run_record_list` 在 `_run_and_evaluate_wrapper`/`_evolve_one` 里)—— 裸调它做 wiring 冒烟看不到 `run_*.json` 是正常的;要 persist 走 `optimize()` 或 `_run_and_evaluate_wrapper`。
    6. **agent proposer 需要其对应的 coding-agent CLI + api_key**(要哪个 CLI 看所选实现的实现名/文档/报错);全量 `optimize()` 还要 model key + MCP 权限 + sandbox 仓库 + 预建 schema manifest —— 都是重开销(每候选 = 真跑 agent + LLM coding agent 改可调产物,多代多候选),**别误跑**(确定好再跑)。
    7. train/val 划分 → 入口里切(无统一划分用顺序子集够冒烟;正式分层按用户对齐)。
    8. 路径全绝对(通用约定);测试/`candidate_store` workspace 没 workspace → 放 `/tmp`(通用约定),正式跑用真 workspace。
    9. `system_description`(步骤 7)/`scoring_criteria`(步骤 8)已写好 → proposer 会用,错或空会让它错误归因(通用约定)。
    
    ---
    
    ## §4 怎么验证(两层)
    1. **wiring 冒烟(必做,不跑 proposer)**:构造 optimizer(proposer 用占位 `api_key`、**不调它**)+ `candidate_store.create_root(initial_artifacts_dir=<exp_root>/initial_artifacts)`(步骤 3 抽好的目录) → `await optimizer._run_and_evaluate(root_id, [1 case])` → `RolloutEvalResult`;断言:`results[0]` SystemResult `prediction_present=True`(+ artifact 字段)、`evals[0]` `EvaluationResult(score∈[0,1], reason)`、已知正确 case `score≥0.9`。验证 System↔Evaluator 经 optimizer 的 kwargs 串通 + 候选可调产物能 load(≈1 agent run)。没 workspace → candidate_store workspace + 输出放 `/tmp`。
    2. **全量 `optimize()`(可选/重)**:入口跑 `await optimizer.optimize()`,需 proposer 对应 CLI + proposer api_key + 全前置。先**小 budget**(`max_iterations=1`、`train≈2`、`val≈1`)验证 root baseline → propose → child → 比较 循环通,再放大。轨迹/统计看 `<workspace>/NOTES.md` + candidate_store 的 `statistics.json`/`summary.json`。
    
    ---
    
    ## §5 ad-config 实例代码位置(请直接读代码,不在此拆业务细节)
    - Optimizer 子类: `antomnievo/optimizer/adconfig/adconfig_optimizer.py`
    - tunable_artifact_def: `antomnievo/model/tunable_artifact_defs/adconfig_tunable_artifact_def.py`
    
  • skills/eddy-antomnievo-experiment/references/system-recipe.md15 KB6d24af63d77bupstream ↗
    # AntOmniEvo System 模块编写配方(后续阶段:用户确认冒烟无误后)
    
    对应 AntOmniEvo 优化循环里的 **System** 组件:把一个候选可调产物跑起来、产出预测(trajectory + output)给 Evaluator 评分。本配方主要覆盖**"系统 = 调外部 generate.py 子进程"**这种形态(本项目的 eddy generate.py 就是这种,对标 text2sql)。其它形态(in-process agent / 容器化)照系统形态最像的一份 example 改结构。
    
    > 这是 AntOmniEvo bootstrap(步骤 1–6)之后的接线活。写之前,步骤 1–6 须已完成(workspace + venv + AntOmniEvo 装好、数据层 + generate/evaluate 冒烟通过)。System/Evaluator/Proposer/optimizer 一起把 `await optimizer.optimize()` 跑起来。
    
    ---
    
    ## 0. 组件放哪:pip 装包 → `<exp_root>/antomnievo/<scenario>/`(统一约定)
    
    AntOmniEvo 一律 **pip 装包**(`pip install ant-omnievo`;不拉源码 clone),本实验补充的组件**全部放专门目录 `<exp_root>/antomnievo/`**(默认;步骤 1 已布局好):
    
    - 里面建本场景包 `<scenario>/`(如 `peizhiagent/`):System → `<scenario>/system/<domain>_system.py`,Evaluator → `<scenario>/evaluator/`,Optimizer 子类 → `<scenario>/optimizer/`,数据层 → `<scenario>/dataset/`,tunable_artifact_def → `<scenario>/tunable_artifact_defs/`,入口脚本 → `<scenario>/<domain>_optimize.py`,辅助脚本 → `<scenario>/scripts/`。
    - 组件目录带最小 `pyproject.toml`,步骤 1 已 `uv pip install -e <exp_root>/antomnievo` 进 AntOmniEvo venv → 场景包直接 `import <scenario>.system...`;入口 `import antomnievo` 拿基类(pip 包)。**不要去改已装的包。**
    - 参照结构从已装包里读:`<pkg> = $(<exp_root>/antomnievo/.venv/bin/python -c "import antomnievo,os;print(os.path.dirname(antomnievo.__file__))")`,看 `<pkg>/system|evaluator|optimizer|dataset|example/<既有 domain>/`(对标 `text2sql` / `rag_pipeline` / `terminalbench` / `appworld` 这些 domain 目录)。
    
    ---
    
    ## 1. 先读:看清 System 契约 + 找最像的 example
    
    System 是 AntOmniEvo 五个可插拔接口之一。写之前**必读**(在 AntOmniEvo 仓库/包里):
    
    1. `antomnievo/interface/system.py` — `System(ABC)` 抽象基类:只强求 `async _run(candidate_meta, data_inst) -> SystemResult`;基类提供 `run`(带信号量并发)和 `run_batch`(gather fan-out)。看清 `_run` vs `run_batch` 的关系。
    2. `antomnievo/model/system_result.py` + `rollout_result.py` + `trajectory.py` + `usage_stats.py` — `SystemResult = {trajectory: Trajectory, output: RolloutResult, usage}`。`RolloutResult.content` 是"系统最终答案"(**str**,结构化对象先 `json.dumps`);`Trajectory` 是 **span 树**(`root_span_list: list[Span]`,`Span` 有 `name/span_type/input/output/children/metadata`,`Trajectory` 还有 `metadata/errors`)。
    3. `antomnievo/model/candidate_data.py` 的 `CandidateMeta` —— **`candidate_meta.artifact_dir` 是候选的可调产物目录**(你 load 回 runtime 的那个 `--artifact-dir`)。
    4. **最像的 example**(挑系统形态最像的一份照**结构**,不照字段):
       - "调外部 generate.py 子进程" 形态 → `antomnievo/system/text2sql/text2sql_system.py` + 入口 `antomnievo/example/text2sql/birdtest_text2sql.py` + `antomnievo/optimizer/text2sql/text2sql_optimizer.py`。
       - "最简单的 in-process agent" 形态 → `antomnievo/system/rag_pipeline/` 下那组。
       读 example 时重点看:构造参数怎么传(scenario-specific 路径在**构造时**给,不进 `run_batch` kwargs)、`run_batch` 怎么拼命令/怎么读回产物/怎么建 `SystemResult`。
    5. **关键:看 optimizer 怎么调 system**。`antomnievo/optimizer/optimizer.py` 的 `Optimizer._run_and_evaluate` 调 `system.run_batch(meta, data_list)` **不传任何 kwargs**(纯 in-process 默认路径);scenario 子类(如 `Text2SQLOptimizer._run_and_evaluate`)override 它、造 tempdir、写 batch 文件、再给 `run_batch` 传 `output_dir`/`cases_path` 等 kwargs。**你写 System 的 `run_batch` 签名要跟你将来写的 optimizer 子类对齐**——System 和 Optimizer 是一对,配套写(见坑 1)。
    
    ---
    
    ## 2. 怎么写(子进程 generate.py 形态,对标 `Text2SQLSystem`)
    
    - **override `run_batch`(不是 `_run`)**:跑一个 generate.py 子进程处理整批,比每条一个子进程高效。签名 `run_batch(self, candidate_meta, data_list, *, output_dir, cases_path, **kwargs) -> list[SystemResult]`(kwargs 跟你的 optimizer 子类对齐)。
    - **构造参数**(scenario-specific,构造时给,全**绝对路径**):`generate_script`、`python_path`(业务项目 venv 的 python,generate.py 的 deps 在那)、`agent_src`、`tunable`(步骤 3 约定的可调条目,list)、`local_source_repo`(写型 agent 的源码仓库)、`env_file`、`timeout`(单 case 超时)、`concurrency`(generate.py 的 case 级并发)、`local_sandbox_transport`、`no_install_deps`、`extra_args`。
    - **拼命令**:`[python_path, generate_script, --agent-src, --artifact-dir <candidate_meta.artifact_dir>, --tunable <ent>...(repeat), --cases <cases_path>, --output-dir <output_dir>, --concurrency, --timeout-seconds]` + 写型加 `--local-sandbox-transport --local-source-repo` + `--env-file`(可选)+ `--no-install-deps` + extra_args。
    - **跑子进程**:`subprocess.run(cmd, capture_output=True, timeout=timeout*len(data_list)+300)` 用 `loop.run_in_executor` 包(别阻塞 event loop)。rc≠0 记 stderr 但别 raise(继续读产物,失败 case 在 SystemResult 里体现)。
    - **读回**:`predictions.jsonl`(一行一 case,按 `case_id` 建 dict)+ `trajectories.jsonl`(一行一 case 的轨迹 dict)。
    - **建 per-data_inst `SystemResult`**:按 `str(data_inst.id)` 匹配 case_id;`output=RolloutResult(content=json.dumps({case_id, prediction_present, run_status, final_text, artifact_source, artifact_summary(截断重数据), error}))`;`trajectory=<span 树,见坑 6>`;`usage=None`(generate.py 不产 UsageStats 就留 None)。
    - **`_run` 也要实现**:`raise NotImplementedError`(你是 batch-only;别 `pass`,pass 会让误调用静默返回 None)。
    - **`system_description()` + `Evaluator.scoring_criteria()` 必须准确反映 generate.py / evaluate.py 的机制**(你已写/读了这俩脚本,该懂原理 —— 见 SKILL『通用约定』):
      - `system_description()` 写清 agent 行为 —— 输入 / run-context 怎么来的、工具面 + 工作流、产出什么 artifact、在哪停(awaiting/HITL)、空产物的失败因(漏改而非崩溃)。
      - `scoring_criteria()`(Evaluator)写清怎么打分 —— 拿什么比、分数语义(0/1 各代表什么)、reason 来源、依赖什么前置(如 schema manifest)。
      - 这俩字符串注入 proposer / 分析 prompt —— **错或空会让它错误归因(把系统/数据问题算到可调产物头上)**。写 System/Evaluator 时一并写好,别留空 / 泛泛。
    
    - ⚠ **eddy → AntOmniEvo Trajectory 解析: 用共享 parser,不要自己重写**
      - 代码位置: `antomnievo/common/utils/trajectory_parser.py` 函数 `parse_eddy_trajectory`
      - API:`parse_eddy_trajectory(raw_trajectory: dict, *, tool_output_max_chars=4000, root_output_max_chars=4000, pre_reasoning_max_chars=300) -> tuple[Trajectory, UsageStats]`
      - 你的 System 的 `_build_trajectory` 只是**一行调**:`return parse_eddy_trajectory(traj, tool_output_max_chars=self.X, ...)[0]`;别自己写消息扫描/工具配对/截断/错误检测 —— 都在 parser 里了。
      - 3 个 size 参数(作为 class 常量暴露给你的 System,用户可调):`tool_output_max_chars`(tool output 超就截,保 `output_truncated=True` flag)、`root_output_max_chars`(root output/final_text 截)、`pre_reasoning_max_chars`(每个 tool_call 前的 reasoning 累积文本截)。默认 4000/4000/300;调了让你看效果 + 成本权衡。
      - 输出结构:1 root span(`eddy_agent_run`) + N tool_call child spans(每个带 input=args / output=result(截断) / metadata `{tool_call_id, output_truncated?, output_original_len?, pre_reasoning?}` — **无冗余 `raw_tool_call`/`raw_tool_result`**)。root metadata 带 case_id/run_status/n_messages/content_type_counts/human_input_required。
      - 为什么有 `pre_reasoning`:proposer(pi+LLM)分析 agent 失败时,光看 tool 调用列表你看不到 "为什么 agent 跳过了验证、为什么选了 sibling config" 等决策原因。`pre_reasoning` 从 eddy 的 `type=reasoning` 消息流里按 tool_call 前后截一小段(val ~300 字)塞进 metadata,proposer 能看到 dive agent 思维,帮助定位可调产物问题。
      - 跟别的 parser 一样: `parse_stream_json` (claude CLI)、`parse_pi_json_output` (Pi CLI)、`parse_eddy_trajectory` (eddy) 共用 `Trait UsageStats + _collect_agent_errors`。
    
    ---
    
    ## 3. 坑(本形态 / eddy 特有,实测得的)
    
    1. **generic `Optimizer` 不传 kwargs** → 必须配套写 optimizer 子类 override `_run_and_evaluate`(对标 `Text2SQLOptimizer`):造 tempdir → 写 `cases_path` → `system.run_batch(meta, data_list, output_dir=…, cases_path=…)` → `evaluator.evaluate_batch(…)`。System 的 `run_batch` 签名收 `output_dir`+`cases_path`。**别只写 System 不写 optimizer 子类**,否则 `run_batch(meta, data_list)` 没参数跑不了。
    2. **`cases_path` 必须是完整 case 行(带 gold)**:generate.py 从 case 读 app/env/base_version(+ code_version 从 extra_context);evaluate.py 读 `expected.artifact.changes` gold。batch cases jsonl 用 `data_inst.to_case_dict()` 写(步骤 2 数据层保证它回原行)**,别只写 id/query**。
    3. **`candidate_meta.artifact_dir` = `--artifact-dir`**:候选的可调产物目录;配 `--tunable <pkg-rel>` 做 "load artifact"(把候选面替换到 runtime checkout 上)。baseline 候选的 artifact_dir 可以是 agent 包根本身(tunable as-is)。
    4. **写型 agent 要 `--local-sandbox-transport`**:只读 `LOCAL_WORKSPACE` 产不了产物(见 generate-evaluate-recipe 运行路径坑)。System 构造默认带 + `--local-source-repo`。冒烟前 sandbox 源码仓库要在、cases 里的 code_version 要能在那解析到。
    5. **`SystemResult.output.content` 是 str,产物是结构化 → `json.dumps`**;重数据(target_config 之类)截断(别把 46k 全塞进 RunRecord)。⚠ **产物形态以实读为准**:本项目 generate.py 的 prediction-row `artifact` = `{all_change_summary, changes[0]{config_name/app/env/base_config_version/target_type/target_config/summary}}`——**别假设是 `payload.field_name`**(我第一次就猜错了,提取全 None)。**写提取前先实读一份 predictions.jsonl 确认 artifact 的真实键**;换领域形态会不同。
    6. **`Trajectory` 用 span 树,别留空**(text2sql 留空是因为它没解析 eddy trace;eddy 有轨迹就该填)。把 tool_call 流做成 root 的 child `Span`(按 `tool_call_id` 配对 tool_result,input=args/output=result);其余(`message_summary`/`n_messages`/`human_input_required`/`run_status`)放 root span `metadata`;`errors` 标 error/timeout/空轨迹。proposer 靠 trajectory 分析失败,**空轨迹 = 没优化信号**。tool 事件优先从 trajectory 的 `tool_calls`/`tool_results` 取,没有再扫 `messages[].content[]` 里 `type==tool_call/tool_result`。
      - ⚠ **控制 trajectory 文件大小**(实测得的坑 — trajectory 一度数百 KB,其中大量是冗余 metadata + 大 tool output 没截断)—— trajectory 落盘进 candidate store 给 proposer 读;太大 = 浪 token + 浪磁盘。**两条规则**(共享 parser `parse_eddy_trajectory` 用 3 个 kwargs 控制):
        - **不冗余**:`span.input` 已有 tool args、`span.output` 已有 tool result → **不要在 `metadata` 里也拷 raw 全量**(那是 50% 冗余);metadata 只留 `tool_call_id` + 截断 flag + `pre_reasoning`。
        - **截断大输出**:`tool_output_max_chars`(默认 4000)超过就截 + 标 `output_truncated=True`。
      - **代码位置**:共享 parser `antomnievo/common/utils/trajectory_parser.py` `parse_eddy_trajectory()`;你的 System class 上加 `TOOL_OUTPUT_MAX_CHARS` / `ROOT_OUTPUT_MAX_CHARS` / `PRE_REASONING_MAX_CHARS` class 常量,调大 = 更多上下文给 proposer(代价 = 更大文件)。
    7. **运行前置(model key + MCP 权限 + sandbox 源码仓库)**:generate-evaluate-recipe 坑节讲过;System 冒烟前同样要备齐,否则 `run_batch` 跑完 `prediction_present=False`(空跑,看着没崩但没产物)。
       - ⚠ **继承 shell 的旧 credential 会 shadow env 文件(实测坑)**:generate.py 的 dotenv 加载是 **shell 优先**(key 已在 os.environ 就跳过文件值)。若用户 shell 环境里有同名**旧** credential(如过期 IAM_TOKEN),System 起子进程时继承它 → 文件里的好 token 被 shadow → agent 中途报 MCP `无员工身份` 这类身份错误,且你手动 `source .env.local` 跑又是好的(覆盖了旧值),极难复现定位。**System 拼好 cmd 后:把 env 文件里声明的 KEY 从继承 env 里 pop 掉再 `subprocess.run(env=...)`**(只解析 KEY 名不读值),保证文件值生效。
    8. **路径全绝对**:构造参数 + `run_batch` 的 `output_dir`/`cases_path` + `candidate_meta.artifact_dir` 全绝对路径,子进程 cwd 无关。
    9. **回到步骤 0 的组件目录**:写 `<exp_root>/antomnievo/<scenario>/system/<domain>_system.py`,入口从场景包 import。
    
    ---
    
    ## 4. 怎么验证写对了(必做,别跳)
    
    1. **import + 子类校验**:`from antomnievo.system.<...> import <System>; issubclass(X, System)` 通过(基类契约 + pydantic 没破)。
    2. **离线验 `_build_system_result`(用真产物最好)**:拿之前 generate 冒烟留下的 `predictions.jsonl`/`trajectories.jsonl` 喂 `_build_system_result`,断言 `SystemResult` 能构造(pydantic 过)、`content` JSON 可解析、artifact 字段提取对(对照 gold)、trajectory span 树 + tool_call 配对对。**这一步直接验真实 artifact 形态(坑 5),省一次 agent 跑**。
    3. **端到端冒烟:实跑 `run_batch` 1 条 case**(真模型):造 `CandidateMeta(artifact_dir=baseline 包根)` + batch cases(1 条,`to_case_dict()`)+ `output_dir`(`<workspace>/tests/system_smoke/`,见 SKILL『通用约定』),`await system.run_batch(...)`;断言:
       - 返回 `SystemResult` 数 == batch 数;
       - `prediction_present=True` + `artifact_summary` 对齐 gold(config_name / base_version / app / env / target_type);
       - trajectory 有 tool_call child span + `run_status` + HITL 捕获 + `errors` 空;
       - (写型 agent)`run_status` ∈ {completed, awaiting}。
       跑不过先分清:**运行前置没备齐**(MCP 403/无 VFS → `prediction_present=False`,去看 generate-evaluate-recipe 坑)还是**你提取/构造 bug**(对照真 `predictions.jsonl` 修,坑 5)。
    4. 修了提取 bug 后**离线复验** `_build_system_result`(不必再跑 agent):拿同一份 predictions/trajectories 重跑提取,确认字段对——省时间。
    
    ---
    
    ## 5. ad-config 实例代码位置(请直接读代码,不在此拆业务细节)
    
    - System: `antomnievo/system/adconfig/adconfig_system.py`
    - 使用 `parse_eddy_trajectory` `(antomnievo/common/utils/trajectory_parser.py)` 做轨迹解析。
    
    > 配套的 optimizer 子类怎么写见 optimizer-recipe。System 的 `run_batch` 签名务必和它对齐。
    
  • skills/eddy-antomnievo-experiment/references/tunable-artifact-recipe.md8.9 KBd4ea79e5058eupstream ↗
    # AntOmniEvo 可调产物配法(可调产物 = module 的可调文件集)
    
    被 SKILL.md「步骤 3」引用。可调产物 = 跟用户约定好的**可调文件集**(按 `<pkg>`-相对路径摆放),作为 AntOmniEvo 的优化面 —— 不是整包,也不外置。参照结构:已装包里 `antomnievo/model/tunable_artifact_schema.py` 的 `TunableArtifactSchema`,以及在已装包的 `antomnievo/model/tunable_artifact_defs/` 选一份**系统形态最像的** `<x>_tunable_artifact_def`(只照结构,别照它的范围/字段)。
    
    ## 0. 为什么不能拿整个 module 当可调产物(AntOmniEvo 机制)
    
    - `LocalCandidateStore.create_root/create_child` 整树 `shutil.copytree(initial_artifacts_dir, candidate_artifact_dir, ignore=ignore_patterns("__pycache__"))` —— `initial_artifacts_dir` 里有什么就全量拷进每个 candidate × 每代 × 每次 rollout;只忽略 `__pycache__`。
    - `TunableArtifactSchema` 只软提示:只 `render_tunable_artifact_schema` 渲染进 proposer/分析 prompt(`base_proposer.py:442/459/584`),**无任何校验**;proposer 在 `cwd=artifact_dir` 改任意文件,唯一程序化后检查是 `mtime`,**无路径白名单**(`base_proposer.py:412`)。
    - 结论:`initial_artifacts_dir = 整个 src/<pkg>` ⇒ env/bootstrap/(大/重的非行为数据) 全进每个 candidate、全机器可改 + 爆炸。"少动"描述不是硬隔离。
    - **正确:`initial_artifacts_dir` = agent module 的包根、只保留可调文件**(自定义 `CandidateStore` 的 `ignore_patterns` 丢非可调 → 候选只剩可调文件按 `<pkg>`-相对排好;或精心 curated);non-tunable 物理上不进 candidate。可调产物是 module 的一部分(非整包、非外置)。
    
    ## 1. TunableArtifactSchema 形态(`antomnievo/model/tunable_artifact_schema.py`)
    
    ```python
    class FileSchema(BaseModel):   name: str; description: str          # type="file"
    class FolderSchema(BaseModel): name: str; description: str; files: list[FileSchema|FolderSchema] = []   # type="folder"
    TunableArtifactSchema = FileSchema | FolderSchema      # tunable_artifact_def 产出一个根 FolderSchema
    ```
    
    `render_tunable_artifact_schema(s)` 渲染成"树 + 逐项 description"的 markdown 进 proposer prompt —— 唯一作用(软提示)。
    
    ## 2. 对齐 module + 入口 + 划"可调文件集"
    
    1. **module 路径**(运行期包,任何名字,如 `<业务项目>/src/<pkg>`) = generate 的 `--agent-src`、= `INITIAL_ARTIFACTS_DIR` 的包根。
    2. **找启动入口**(不假定具体名;很多 eddy 入口的入口在 `<pkg>` 下某处(如可调子包,但不限),但不限):grep `builder.build()`/`AgentBuilder`/模块顶 `agent = …`;读 `app-metadata.yml`/`server-simple.yaml`(`module_path`+`attr`)/`pyproject[tool.arec]`/`eddy run`/`CLAUDE.md`;列 `*agent*.py` 候选;候选给用户 → 确认入口(`<包内路径>:<attr>`);多义/找不到 → 让用户给。入口 = **"code integrity" 的 import 锚**。
    3. **扫 module 全部文件/目录,过滤 `__pycache__`/`.pyc`**,逐个说清用途、逐条确认,**跟用户约定要优化哪些文件/目录**(= generate 的 `--tunable` 条目)。可调样例(以用户确认的为准,不硬挑):
       - 用 `<pkg>`-相对路径表达每条目:`<可调子包>`、`<可调子包>/<子集>`、`<顶层可调文件>` …(名字以项目实际为准)
       - 非可调(留 module,不进可调产物):env 运行配置、启动 bootstrap、(日志等非行为组件)、(大/重的非行为数据)、以及任何不打算改的部分。
       - ⚠ 可调部分**通常不能单独 import 跑**(入口 import 顶层非可调兄弟,如 顶层非可调兄弟(如运行配置/日志等;具体名以项目为准));运行靠 generate 的 "load 可调产物" 按可调条目合并回整个 module 才能跑(见 generate-evaluate-recipe)。
    
    ## 3. initial_artifacts_dir + load 流程
    
    - `INITIAL_ARTIFACTS_DIR = <module>`(**包根**),入口脚本(后续)里设。
    - 用**自定义 `CandidateStore`** 重写 `create_root`/`create_child` 的 `ignore_patterns`,**丢非可调**(步骤 2 里确认的非可调条目(以实际扫描+用户确认为准;别套任何别的项目的名));给窄集(只一个 skill/散落)时给一份精心 curated 的根(也按 `<pkg>`-相对路径)。AntOmniEvo `copytree(INITIAL_ARTIFACTS_DIR, candidate_artifact_dir)` → 候选可调产物 = 可调文件按 `<pkg>`-相对排好。
    - 候选改那些;generate 跑候选时 HAPPENS: `generate --agent-src <module> --artifact-dir <candidate_artifact_dir> --tunable <pkg-rel-path> …` — load 按 `--tunable` 条目逐个对应到 `<pkg>/<ent>`(见 generate-evaluate-recipe §"load 可调产物 映射")。
    - **重数据 (大/重的非行为数据) 不进可调产物**;generate 把它从运行期 symlink 进 checkout,不每 rollout 拷 重数据。即便真要优化它,另按单份共享 + symlink 进可调产物处理。
    
    ## 4. 写 `<exp_root>/antomnievo/<scenario>/tunable_artifact_defs/<domain>_tunable_artifact_def.py`(只列与用户对齐的那棵可调树;不改已装的包)
    
    照搬一份**系统形态最像的** `<x>_tunable_artifact_def`(选 `tunable_artifact_schema.py` 的 `FileSchema`/`FolderSchema` + 描述 + 约束),`files` 树**只列跟你/用户约定的可调条目树**(把 env/bootstrap/非可调面 全删);各 path+description 用步骤 2 跟用户对齐的用途(过滤 pycache):
    
    ```python
    from antomnievo.model.tunable_artifact_defs.common_descriptions import _ADDITIONAL_FILES_DESCRIPTION
    from antomnievo.model.tunable_artifact_schema import FileSchema, FolderSchema, TunableArtifactSchema
    
    _<DOMAIN>_ARTIFACT_DIR_DESCRIPTION = """\
    The tunable-artifact directory holds the agreed TUNABLE artifacts of the ``<pkg>`` agent — only the files/dirs that the user chose to optimize. Non-tunable runtime (env config, bootstrap, 日志、大或重的非行为数据) is OUT of the tunable artifacts.
    <一句话:agent 吃什么输入、产什么、怎么打分>.
    
    ## Global constraints
    ### No redundancy  <每条规则/工具/知识只在一处;规则与工具实现不许重复编码同一检查>
    ### No contradiction <系统 prompt 与 docstring/module/知识不许冲突;冲突选一处 canonical>
    ### Generalization  <每个通用陈述配一个具体例子(before/after 或真实失败 case)>
    ### Code integrity
    - Edits MUST NOT break import relationships: after any change, ``python -c "import <步骤2入口 module>"`` must still succeed.
    - 入口仍 import 顶层非可调兄弟(顶层非可调兄弟(如运行配置/日志等;具体名以项目为准));可调改动不得破坏这些 import。
    - Do NOT introduce dangling references (删了还在 import / 改名没改调用点)。
    """
    
    <DOMAIN>_TUNABLE_ARTIFACT_SCHEMA: TunableArtifactSchema = FolderSchema(
        name=<根>,                    # 用 step2 约定的根名(按步骤2 确认的根名)
        description=_<DOMAIN>_ARTIFACT_DIR_DESCRIPTION,
        files=[
            FileSchema(name="<确认的入口文件>.py", description="<系统 prompt + 装配;步骤2确认的入口>"),
            FolderSchema(name="<可调子包1>", description="<用途;与步骤2对齐>", files=[]),
            FolderSchema(name="<可调子包2>", description="<用途;与步骤2对齐>", files=[]),
            # ……按与用户对齐的可调条目树列,非可调一律不列……
            FileSchema(name="...", description=_ADDITIONAL_FILES_DESCRIPTION),
        ],
    )
    ```
    
    - `INITIAL_ARTIFACTS_DIR` 在入口脚本设 `= os.path.normpath(os.path.join(<业务项目根>,"src","<pkg>"))`(配合自定义 store 的 ignore)。本步只写 `*_TUNABLE_ARTIFACT_SCHEMA`。
    
    ## 5. 坑
    
    1. **别拿整个 module 当可调产物**(全进每 candidate、可改 env/bootstrap、爆炸);收窄到与用户约定的可调集 + 包根 initial_artifacts。
    2. **TunableArtifactSchema "少动"是软提示不是隔离**;隔离 = 可调产物只含可调文件(initial_artifacts 根 + ignore/curated)。
    3. **load 必 rm 后再 copy**(dir: `rm`+`copytree`;file: `copyfile`)—— `copytree(dirs_exist_ok=True)` 是 merge、会让删除/改名残留;见 generate-evaluate-recipe §load 映射。
    4. **`__pycache__`/`.pyc` 一律过滤**;(大/重的非行为数据) 默认不进可调产物(symlink 进 checkout)。
    5. **入口/包名别照抄现有 tunable_artifact_def**;用步骤 2 用户的确认结果。
    6. **AgentSkills-style agent**(顶层 skill 文件 + scripts/ + references/ + assets/):`agent_skill_tunable_artifact_def.py` 是可照的系统形态之一(可调产物根就是那些 skill 文件);eddy python-package agent:用整条可调子包(或与用户约定的子集)作可调集。
    
    ## 6. sanity check(写完即自测)
    
    ```bash
    <workspace>/.venv/bin/python -c "
    from antomnievo.model.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)[:1200])
    "
    ```
    渲染出的树**必须只含与用户约定的可调条目**(无 env/bootstrap/非可调面/`__pycache__`)。把这段渲染给用户做步骤 3 的确认。
    
  • skills/eddy-antomnievo-experiment/references/workspace-setup-recipe.md7.6 KB9f3926113f38upstream ↗
    # workspace 准备配方(AntOmniEvo 实验)
    
    被 SKILL.md「步骤 1」引用:动手前先备好 AntOmniEvo 实验的落地基础。参照 `antomnievo/README.md` §5。
    
    ## 0. 两个目录概念(先分清)
    
    "workspace" 拆成两个**不同**概念(详见 SKILL.md『两个目录概念』):
    
    - **实验根目录(`<exp_root>`)**:整个实验的**非候选**产物 —— **本实验组件目录(`<exp_root>/antomnievo/`,默认;不是源码 clone —— AntOmniEvo 一律 pip 装包,这里放本实验补充的组件 + 入口脚本 + 最小 pyproject;venv 也在里面:`<exp_root>/antomnievo/.venv/`,是 AntOmniEvo 的专用环境)**、`NOTES.md`、config YAML、`run.env`、`tests/`、`initial_artifacts/`。**每实验自包含**(组件目录 + venv 都在 exp_root 内,不共享外部 venv);一个实验一个,跨多次 run 复用。
    - **candidate store 根目录(`<candidate_store_root>`)**:**单独一个目录,只放优化 run 的候选数据**;里边每次 run 一个时间戳子目录 `<run_dir> = <candidate_store_root>/run_YYYYMMDD_HHMMSS/`(= `LocalCandidateStore(workspace_dir=<run_dir>)` 的落盘路径)。**resume = 同一个 `<run_dir>`;新 run = 新时间戳子目录。**
    
    ## 1. 让用户定两个路径
    
    主动问用户(都要绝对路径、独立、可写、不和业务项目混),确认再往下。**问法:给候选 + 允许自输,别开放式问** —— 给 2~3 个**具体候选路径**让用户挑,也允许用户自己输入;候选按当前环境推断(如 `<cwd>/exp-<agent>`、`<work_root>/exp-<agent>`),每个候选附一句取舍说明;用户确认前不动手:
    
    - **`<exp_root>`** 放哪;
    - **`<candidate_store_root>`** 放哪(候选给:默认 `<exp_root>/workspace`(**推荐**)、`<exp_root>/candidate_store/`、独立路径(候选数据 = 可调产物树 × 候选 × 代,体积可能很大,想放别的盘就独立路径,用户自输))。
    
    ```
    <exp_root>/                      # 实验根目录(步骤 1 创建)
      antomnievo/                      # 本实验组件目录(非源码 clone;本实验补充的组件/脚本都放这)
        .venv/                       # AntOmniEvo 专用 python 环境(python ≥ 3.12;pip install ant-omnievo)
        pyproject.toml               # 最小打包,让 <scenario>/ 场景包可 import(uv pip install -e .)
        <scenario>/                  # 本场景组件包(如 peizhiagent/)
          dataset/  tunable_artifact_defs/  system/  evaluator/  optimizer/  scripts/  <domain>_optimize.py
      NOTES.md                       # 实验记忆(每步追加)
      opt_config.yaml                # config YAML(步骤 10 写;secrets 在这)
      run.env                        # 入口从 YAML 物化(步骤 10)
      initial_artifacts/                  # 抽出的初始可调产物(步骤 9/10)
      tests/<smoke_name>/            # 冒烟/测试产物(保留不清)
      examples/                      # (可选)从 antomnievo/example/ 拷来的入口脚本、改写的 entry-point
    
    <candidate_store_root>/          # candidate store 根目录(单独目录;步骤 1 只建根,不建 run 子目录)
      run_YYYYMMDD_HHMMSS/           # <run_dir>:每次优化 run 一个时间戳子目录(步骤 10 optimize() 时才建)
        candidates/<candidate id>/   #   各 candidate:可调产物树 / meta / changelog / best / run 产物
        logs/statistics.json         #   优化统计(resume 判定:有无 root_candidate_id)
    ```
    
    > candidate store 输出 = `LocalCandidateStore(workspace_dir=<run_dir>, cleanup_unavailable=False)`;config YAML 里 `<run_dir>` 的 key 叫 `workspace_dir`(与参数同名)—— 它指 candidate store 的单次 run 目录,不是 `<exp_root>`。
    
    ## 2. 建组件目录 + 专用 python 环境 + pip 装 AntOmniEvo(不拉源码)
    
    路径定了后,**建 `<exp_root>/antomnievo/`(本实验组件目录,非源码 clone)**,并在其中**创建一个专供 AntOmniEvo 使用的 python 环境**(`<exp_root>/antomnievo/.venv/`,python ≥ 3.12):
    
    ```bash
    # 建组件目录(本实验补充的 dataset/tunable_artifact_def/System/Evaluator/Optimizer/入口脚本都放这)
    mkdir -p <exp_root>/antomnievo
    
    # 在其中建 AntOmniEvo 专用 venv(python ≥ 3.12)
    uv venv --python 3.12 <exp_root>/antomnievo/.venv
    
    # pip 装 AntOmniEvo(不拉源码 clone;core 依赖 pydantic ≥2/httpx/tenacity/pyyaml 跟着进)
    uv pip install ant-omnievo --python <exp_root>/antomnievo/.venv/bin/python
    
    # 问用户要不要可视化前端:要 → 装 visualizer 包(README §9;前端 React 还要 npm install)
    uv pip install ant-omnievo-visualizer --python <exp_root>/antomnievo/.venv/bin/python
    
    # 组件目录放最小 pyproject + editable-install 装进同一 venv → 场景包可 import(PYTHONPATH 兜底)
    uv pip install -e <exp_root>/antomnievo --python <exp_root>/antomnievo/.venv/bin/python
    ```
    
    组件目录的最小 `pyproject.toml`(`<scenario>` 换成本场景包名,如 `peizhiagent`):
    
    ```toml
    [build-system]
    requires = ["setuptools>=68.0", "wheel"]
    build-backend = "setuptools.build_meta"
    
    [project]
    name = "antomnievo-exp-components"
    version = "0.1.0"
    requires-python = ">=3.10"
    
    [tool.setuptools.packages.find]
    include = ["<scenario>*"]
    ```
    
    > **业务项目自己的运行/打分 harness 不在这里装**:README §5 明确——your `System`/`Evaluator` 若 shell out 到自己的运行/打分,各自单独装;AntOmniEvo 不管。本 skill 的 `generate.py`/`evaluate.py` 跑在**业务项目自己的 venv**,不是这个 AntOmniEvo venv。
    
    > **proposer 的 coding-agent CLI 也分开装**(步骤 10 启动 proposer 才需要):
    > - agent proposer **固定默认用 pi 实现**(`antomnievo/proposer/` 里 pi-based 的 `BaseProposer` 实现;**不给用户选 claude 实现 —— claude 目前有问题**):先 `which pi && pi --version` 检查;**没装 → `npm install -g @mariozechner/pi-coding-agent`**(需 **Node ≥ v22.22.1**;没 Node → `brew install node` 或 `nvm install 22.22.1`)。`pi` 启动可能要登录 / 设模型网关 key(按 CLI 提示),提前跑 `pi --help` 看格式;proposer YAML 里的 `api_key`/`base_url` 是喂给 `pi` 的 LLM 网关。
    
    ## 3. 读 README + 选 example(从已装包里读,不 clone)
    
    - 先定位已装包:`<pkg> = $(<exp_root>/antomnievo/.venv/bin/python -c "import antomnievo,os;print(os.path.dirname(antomnievo.__file__))")`。
    - 读 README(随包装在 `<pkg>/../README*.md`;没有就 `pip download` 或让用户给仓库地址只读参考),重点 §5/§6/§7/§8。
    - `<pkg>/example/` 是**参考实现**(每份是一个不同系统形态的入口接线):挑最像的一份当起点。
      - `example/rag/agentic_rag_internal.py` —— 最简单端到端(in-process system + 基础 `Optimizer`)。
      - `example/text2sql/birdtest_text2sql.py` —— batch-subprocess `System` + 场景 `Optimizer` 子类(更接近"调业务项目脚本"的形态,**本 skill 的 gen/eval 主要对标这种**)。
      - 另:`example/terminalbench/`、`example/appworld/` 也可参。
    
    ## 4. entry-point 形态(不在此复制)
    
    去读 AntOmniEvo 的 example(见上 §3)即可,按你选中的那份 entry-point 改;**本 recipe 不重复贴骨架**,以免和上游 example 跑偏。
    
    ## 5. sanity check(写完即自测)
    
    ```bash
    <exp_root>/antomnievo/.venv/bin/python -c "import antomnievo; print(antomnievo.__file__)"   # 应指向该 venv 的 site-packages(证明用的 pip 包)
    <exp_root>/antomnievo/.venv/bin/python -c "from antomnievo.store.candidate_store import LocalCandidateStore; print(LocalCandidateStore)"
    ```
    能 import `antomnievo` + `LocalCandidateStore` 即环境 OK。
    
    > 注:`System` / `Evaluator` / 4 个组件的接线和 `await optimizer.optimize()` 属于 AntOmniEvo **后续步骤**(System 跑你写的 generate、Evaluator 调你写的 evaluate),不在本 skill(本 skill 只到 data + gen/eval + 冒烟确认)。本 recipe 只把 workspace/venv/README 备齐,让你写后续模块时有据可依。
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/ant-research-antomnievo-skills-eddy-antomnievo-experiment.md

// REPO STATS

1.2k stars
1 open issues
Last commit: 4d ago