# eddy-antomnievo-experiment

Adopt this skill: https://proskills.md/skills/other/ant-research-antomnievo-skills-eddy-antomnievo-experiment

Page: https://proskills.md/skills/other/ant-research-antomnievo-skills-eddy-antomnievo-experiment
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/eddy-antomnievo-experiment/SKILL.md
size: 74599
sha: 32b1e9e9585f6c214d78ccca1d5a49d68b9b479a
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/SKILL.md
truncated: true

```text
---
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 
```

## File: skills/eddy-antomnievo-experiment/references/context-recovery-recipe.md
size: 4696
sha: 713b2c0d86d4d43503cbfc4dcfe3290ab9bd6d2f
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/context-recovery-recipe.md

````text
# 上下文恢复配方(长跑优化 → 用户清上下文后)

优化是长会话(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 验证。
````

## File: skills/eddy-antomnievo-experiment/references/data-layer-recipe.md
size: 5170
sha: 387d264939eaa38969ac0d99caff6f34495efbb9
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/data-layer-recipe.md

````text
# 数据层配方 (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` 都非空即过。
````

## File: skills/eddy-antomnievo-experiment/references/entry-recipe.md
size: 14588
sha: bfa0f30ed8a991a3616eba4cc3ffb4bba1fb0956
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/entry-recipe.md

````text
# 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`
````

## File: skills/eddy-antomnievo-experiment/references/evaluator-recipe.md
size: 7396
sha: fe6bd62341e9f745591c329dbbacad487aac6e46
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/evaluator-recipe.md

```text
# 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` 签名务必和它对齐。
```

## File: skills/eddy-antomnievo-experiment/references/generate-evaluate-recipe.md
size: 38243
sha: 9444cf2e730fc186395d544194e2243b55f6b7a0
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/generate-evaluate-recipe.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/generate-evaluate-recipe.md

## File: skills/eddy-antomnievo-experiment/references/optimizer-recipe.md
size: 8562
sha: b567eccee4b0a56ad0d4f4df241894678eb0aee0
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/optimizer-recipe.md

````text
# 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`
````

## File: skills/eddy-antomnievo-experiment/references/system-recipe.md
size: 15119
sha: 6d24af63d77bf1b26476731b1f6868cef994d059
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/system-recipe.md

```text
# 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` 签名务必和它对齐。
```

## File: skills/eddy-antomnievo-experiment/references/tunable-artifact-recipe.md
size: 9073
sha: d4ea79e5058e4f5456017c04caf48eb8b81afae0
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/tunable-artifact-recipe.md

````text
# 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 的确认。
````

## File: skills/eddy-antomnievo-experiment/references/workspace-setup-recipe.md
size: 7793
sha: 9f3926113f38e1a71b90ad756aa89c904b473bb9
upstream: https://github.com/ant-research/antomnievo/blob/main/skills/eddy-antomnievo-experiment/references/workspace-setup-recipe.md

````text
# 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 备齐,让你写后续模块时有据可依。
````

## File: README.md
upstream: https://github.com/ant-research/antomnievo/blob/main/README.md

````text
# AntOmniEvo

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

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE) [![Papers](https://img.shields.io/badge/Papers-1-b31b1b.svg)](#papers)

> **English** · [中文](./README.zh-CN.md)

---

**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 provide | Role |
| --- | --- |
| `System` | how to **run** your system on one eval instance |
| `Evaluator` | how to **score** its output (0–1) — its scoring criteria *is* the optimization objective |
| **data** | the train/val instances that define "good" |
| `TunableArtifactSchema` | maps your system's tunable artifacts onto a directory: the file tree + what each file is for |
| **initial tunable artifacts** | the 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/`](./skills) ships per-scenario [Agent Skills](https://agentskills.io): 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

| Topic | English | 中文 |
| --- | --- | --- |
| Install & quick start | [docs/quickstart.md](./docs/quickstart.md) | [docs/quickstart.zh-CN.md](./docs/quickstart.zh-CN.md) |
| Features | [docs/features.md](./docs/features.md) | [docs/features.zh-CN.md](./docs/features.zh-CN.md) |
| Extensibility | [docs/extensibility.md](./docs/extensibility.md) | [docs/extensibility.zh-CN.md](./docs/extensibility.zh-CN.md) |
| When to use it | [docs/when-to-use.md](./docs/when-to-use.md) | [docs/when-to-use.zh-CN.md](./docs/when-to-use.zh-CN.md) |
| System design | [docs/system-design.md](./docs/system-design.md) | [docs/system-design.zh-CN.md](./docs/system-design.zh-CN.md) |
| Workspace artifacts & attribution | [docs/workspace-artifacts.md](./docs/workspace-artifacts.md) | [docs/workspace-artifacts.zh-CN.md](./docs/workspace-artifacts.zh-CN.md) |
| Checkpoint resume & crash recovery | [docs/checkpoint-resume.md](./docs/checkpoint-resume.md) | [docs/checkpoint-resume.zh-CN.md](./docs/checkpoint-resume.zh-CN.md) |
| Visualizer | [docs/visualizer.md](./docs/visualizer.md) | [docs/visualizer.zh-CN.md](./docs/visualizer.zh-CN.md) |

## 🧪 Paper Resources

The paper's experiment scripts, artifacts before and after evolution, and datasets are open-sourced at [ant-research/AntOmniEvoDatasetsAndScripts](https://github.com/ant-research/AntOmniEvoDatasetsAndScripts).

<a id="papers"></a>

## 📄 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](https://arxiv.org/abs/2609.35855)**

  ```bibtex
  @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](./LICENSE). Legal disclaimer: see [`LEGAL.md`](./LEGAL.md).
````
