AntOmniEvo进阶扩展:对接云端存储与自定义Coding Agent后端完全指南
AntOmniEvo进阶扩展:对接云端存储与自定义Coding Agent后端完全指南
AntOmniEvo 是一个让 AI 自动进化的开源框架——你可以把它理解为一支 7×24 小时在线的"算法工程师团队",它把系统里可调的文件(Skill、提示词、工作流配置)当作基因,自动跑"选择→改写→评估→反思"的进化循环。本文带你完成两项进阶扩展:对接云端存储(自定义 CandidateStore)与自定义 Coding Agent 后端(自定义 Proposer),全程只需改动很小的代码量。
一、为什么要扩展:先认识 AntOmniEvo 的 7 个可插拔组件
AntOmniEvo 的设计哲学是"通用引擎 + 任务插件":主循环、调度、预算控制、断点续跑全部由框架负责,你的任务只需插入 7 个可插拔组件。官方扩展文档 docs/extensibility.md 把它们分成三个角色:
| 角色 | 组件 | 职责 | 常见默认实现 |
|---|---|---|---|
| 目标端 | System |
用候选的可调文件运行系统 | Text2SQLSystem、TerminalBenchSystem |
| 目标端 | Evaluator |
给运行结果打分,其评分标准就是优化目标 | TextSQLEvaluator 等 |
| 目标端 | DataInst + loader |
一条评测实例及其加载方式 | 各场景 loader |
| 优化端 | Optimizer |
进化主循环 | 基类 + 场景子类 |
| 优化端 | Proposer |
读失败轨迹、改写文件的 Coding Agent | PiCodingAgentProposer、ClaudeCodeProposer |
| 优化端 | EvolutionAlgorithm |
决定谁被选育、谁被淘汰 | ParetoFrontierEvolutionAlgorithm |
| 持久化 | CandidateStore |
持久化全部进化状态 | LocalCandidateStore(文件系统) |
在这 7 个组件里,绝大多数用户只需要替换前 3 个目标端组件。而本文讲的两条扩展轴,正好对应另外两个位置:
- 换 Coding Agent 后端:继承 BaseProposer,实现一个方法即可;
- 接云端存储:继承 CandidateStore 抽象基类,实现"本地 + 透明同步"子类。
两条轴都不需要修改主循环一行代码。
二、扩展轴一:对接云端存储(自定义 CandidateStore)
2.1 存储里到底存了什么
一次优化运行 = 一个 Optimizer 进程 + 一个本地存储。所有候选体(candidate)的"基因"与进化记忆都落在 workspace/ 目录下,默认实现 LocalCandidateStore 的目录结构长这样:
workspace/
└── candidates/
└── {candidate_id}/
├── artifact/ # 该候选的可调文件(技能、提示词、配置…)
└── data/
├── meta.json # 候选元信息
├── changelog.jsonl
├── summary.json # 分数汇总
├── system_run/ # 训练集运行记录
└── proposer_run/ # 分析/变异轨迹
这就是为什么 AntOmniEvo 天然可中断、可续跑:状态全在磁盘上,重启后自动恢复。
2.2 官方推荐的云存储方案:本地 + 透明同步
很多团队的第一反应是"把存储整体搬到对象存储/数据库",但官方文档在 docs/extensibility.zh-CN.md 中给出了一个更稳妥的结论:请实现一个"本地 + 透明同步"的 CandidateStore 子类,而不是"多 worker 共享一个远端 store"。原因是:
- 候选的
artifact_dir会被直接当作工作目录(cwd)交给 Coding Agent 子进程就地改文件,也作为--artifact-dir传给系统子进程——它必须是真实可写的本地目录,远端 URI 无法胜任; - 存储接口依赖文件修改时间(mtime)来判断"哪些运行记录还没被分析",远端后端必须提供等价的时间戳语义;
changelog.jsonl等文件由外部 CLI 子进程并发追加写入,远端需支持安全的追加语义。
因此正确姿势是:优化过程仍在本地 workspace/ 跑,每次写入时顺带把产物同步到对象存储/数据库;运行前从云端拉取初始可调文件作为种子,运行后把最终产物推给下游消费。主循环及其并发(进程内的 num_proposals 槽位)完全不用动。
2.3 三步落地:自定义 CandidateStore 子类
第 1 步:继承抽象基类。 在 antomnievo/interface/candidate_store.py 中,CandidateStore 是一个 ABC(抽象基类),__init__ 是具体实现(只需保存 workspace_dir 和 cleanup_unavailable 两个跨实现配置项):
class CloudSyncStore(CandidateStore):
def __init__(self, workspace_dir, bucket, cleanup_unavailable=True):
super().__init__(workspace_dir, cleanup_unavailable) # 必须先调 super
self._local = LocalCandidateStore(workspace_dir, cleanup_unavailable)
self._bucket = bucket # 你的对象存储/数据库句柄
第 2 步:委托本地 + 写入时同步。 把所有读方法直接委托给 LocalCandidateStore(它已带内存缓存),再在写路径(save_meta、save_run_record、append_changelog、update_analysis、轨迹保存等)之后,把对应文件/目录增量同步到云端。
第 3 步:处理两个"物化"时机。
create_root时:从云端拉取初始可调文件目录,在本地artifact/物化,再交给子进程;- 运行结束(或每个候选被接受时):把
artifact/树推送到云端,供下游(部署、报表)消费。
契约类接口(artifact_dir / data_dir / system_run_dir 等路径方法)全部照抄 LocalCandidateStore 的路径拼接即可,因为它们最终都指向本地目录。完整契约细节写在该接口类的 docstring 中(antomnievo/interface/candidate_store.py#L36-L68),实现前务必通读一遍。
2.4 接入入口:只改一行
组件装配通常写在 example/ 下的入口脚本中,比如 antomnievo/example/terminalbench/terminalbench.py#L95:
candidate_store = LocalCandidateStore(workspace_dir, cleanup_unavailable=False)
换成你的云端子类后,Optimizer、Proposer、EvolutionAlgorithm 都通过 candidate_store= 参数持有同一个对象,因此其余代码一行不动。这也是 AntOmniEvo"面向接口编程"的直接收益:optimizer / proposer / system 全部只依赖 CandidateStore 抽象。
三、扩展轴二:自定义 Coding Agent 后端(自定义 Proposer)
3.1 核心思想:两阶段流水线已经替你写好了
Proposer 是 AntOmniEvo 里真正"干活"的 AI:它先做阶段 1 分析(读取未分析的失败运行记录,让 Agent 写出失败归因),再做阶段 2 变异(根据分析结果改写可调文件,产出新候选)。这套两阶段流水线、提示词模板、changelog 校验脚本全部固化在 BaseProposer 中。
所以自定义后端只需要回答一个问题:怎么调用你自己的 Coding Agent CLI/SDK,并把会话解析成轨迹。也就是实现这一个抽象方法(antomnievo/proposer/base_proposer.py#L94-L101):
async def invoke_agent(self, prompt: str, cwd: str) -> tuple[Trajectory, UsageStats]:
"""调用你的 Agent,返回 (轨迹, 用量统计)。"""
prompt:框架已组装好的完整提示词(含评分标准、可调文件 schema、失败分析内容等),你原样传给 Agent 即可;cwd:本次会话的工作目录。阶段 1 是父候选的data_dir,阶段 2 是新候选的artifact_dir(框架通过 snapshot_files 前后对比目录来判断"文件是否真的被修改");- 返回值:
Trajectory是 span 树结构(见 antomnievo/model/trajectory.py#L38),UsageStats记录 token 用量,用于预算统计。
3.2 一个最小自定义 Proposer 长什么样
假设你的团队内部有一个叫 myagent 的编码 CLI。参考现有实现 PiCodingAgentProposer(它同时展示了重试、并发信号量等生产级写法):
class MyAgentProposer(BaseProposer):
def __init__(self, *, api_key: str, concurrency: int = 4, **kwargs):
super().__init__(concurrency=concurrency, **kwargs)
self._api_key = api_key
async def invoke_agent(self, prompt: str, cwd: str) -> tuple[Trajectory, UsageStats]:
async with self._sem: # 复用父类的并发信号量
raw = await invoke_my_agent_cli(prompt, cwd, self._api_key)
return parse_my_agent_output(raw) # 你的解析函数
就这么多。提示词模板(antomnievo/proposer/template/)、分析结果校验、changelog 追加、反思链路(Mara Chain)全部继承而来。
3.3 三个生产级要点(现有后端的经验)
阅读 pi_coding_agent_proposer.py 时你会发现几个值得抄的细节:
- 瞬时错误重试:对 429/5xx/过载等瞬时错误用 tenacity 做指数退避重试,且退避期间继续持有并发信号量——这是刻意的背压设计,避免限流期间又堆进新的并发请求;
- 并发上限:通过
concurrency参数 +asyncio.Semaphore控制同时在跑的 Agent 会话数,阶段 1 的多组data_id分析用asyncio.gather并发; - 防"假成功":Agent 会话退出码为 0 不代表文件真的落地。框架会在阶段 1 校验分析结果文件是否在会话期间被写入、阶段 2 对比目录快照判断文件是否被修改,未修改则视为失败,避免把半成品候选推入种群。你的解析函数只需如实填好
Trajectory.errors,这些防御逻辑就自动生效。
四、验证你的扩展:跑起来并可视化
扩展完成后,用 example/ 下任意入口脚本把组件指向你的新实现即可启动进化。跑起来之后,强烈建议装一下可视化器(docs/visualizer.zh-CN.md)来验收效果:
pip install -e .
pip install -e ./visualizer
cd visualizer && npm install
antomnievo-visualizer-manage start --workspace /path/to/workspace/<run>
前端默认在 http://localhost:5173。候选种群被渲染成一座"龙虾健身房",按分数分层归入不同房间;点击候选可以看祖先链、元信息,并用内置文件查看器浏览 system_run / proposer_run 的全部产物——自定义存储同步是否正常、自定义 Agent 的轨迹解析是否正确,在这里一目了然。
五、避坑清单:新手常踩的 5 个坑 🐚
- 把
artifact_dir返回成远端 URI —— 它会被当作cwd交给子进程,必须是本地可写目录; - 忘记
super().__init__(workspace_dir, cleanup_unavailable)——workspace_dir和cleanup_unavailable会被Optimizer通过接口回读用于启动恢复与日志; - 忽略 mtime 语义 ——
find_unanalyzed_runs靠"运行记录比分析结果更新"来判断待分析项,远端对象必须有可用的最后修改时间; - 自定义 Proposer 里不填
Trajectory.errors—— 框架靠它触发失败落盘与重试分类,吞掉错误会导致半成品候选混入种群; - 试图多机共享一个 store 做跨主机并发进化 —— 这是另一套模型,框架开箱不支持;"一次运行 = 一个本地 store + 透明同步"才是官方姿势。
六、延伸阅读
- 扩展机制全貌:docs/extensibility.md(含 7 组件表格与云存储架构图)
- 断点续跑与崩溃恢复:docs/checkpoint-resume.zh-CN.md
- workspace 目录结构与产物归因:docs/workspace-artifacts.zh-CN.md
- 何时该用 AntOmniEvo:docs/when-to-use.zh-CN.md
两条扩展轴加起来,一个熟练的 Python 用户半天内就能跑通:CandidateStore 子类负责"进化记忆上云",BaseProposer 子类负责"换上你自己的 AI 工程师"。剩下的,交给 AntOmniEvo 的自动进化循环。





