AVO — 智能体变异算子

这是 《AVO：用于自主进化搜索的智能体变异算子》（Chen、Ye、Xu 等，NVIDIA，2026）的开放复现，可在笔记本电脑上运行。

经典的进化搜索，以及随后的 LLM 增强系统，将变异算子分解为固定流水线：

Vary(P_t) = Generate(Sample(P_t))

该框架对父代进行采样；模型从它们中生成一个候选。AVO 用一次自主的智能体运行取代了这整个分解：

Vary(P_t) = Agent(P_t, K, f)

智能体看到完整的谱系 P_t、领域知识库 K 和评分函数 f —— 并自行决定读取什么、更改什么、以及何时测量。它不再是候选生成器，而是变成了变异算子。

本仓库实现了该框架，以及论文描述的相关机制：基于 git 的谱系、正确性门控的得分向量、匹配或改进提交策略、在停滞时介入的监督器，以及轨迹图。仓库附带两个优化目标。

关键之处：它在你已有的会话中运行

默认驱动不会生成智能体，也不会调用 API。它把变异提示交给您正在对话的 Claude Code 会话，由该会话完成工作。不会产生额外费用，不需要 ANTHROPIC_API_KEY，执行优化的智能体是真正的通用编码智能体 —— 这正是论文所用的方式。

无人值守模式（每一步生成一个智能体，并让它运行数天，就像论文的 7 天实验一样）也可用，并且需要主动选择启用，正是因为它会消耗配额。

Related MCP server: AgentPrism Workflows

安装

git clone https://github.com/gatordevin/avo
cd avo
pip install -e ".[all]"     # or: pip install -e .  for the core only
avo doctor

在 Python 由外部管理的系统上（Homebrew、大多数 Linux 发行版），请使用 virtualenv —— --system-site-packages 标志会复用您已有的 NumPy 和 Matplotlib：

python3 -m venv --system-site-packages .venv
.venv/bin/pip install -e ".[all]"
.venv/bin/avo doctor

要求：Python 3.10+、git，以及如果您想要 attention_c 目标，还需要 C 编译器。内置目标需要 numpy，绘图需要 matplotlib。核心框架仅依赖 PyYAML。

快速入门 —— 用您已有的智能体驱动它

完整协议（包括 Codex 和纯 CLI 用法）见 docs/DRIVING.md。

Claude Code

在用户范围注册 MCP 服务器一次，以便它在每个文件夹中都可用：

claude mcp add avo -s user -- python3 -m avo.mcp_server
# from a virtualenv, point at its interpreter:
claude mcp add avo -s user -- /path/to/avo/.venv/bin/python -m avo.mcp_server

claude mcp list 应显示 avo — ✔ Connected。可选地安装内置技能，以便 /avo 在任何地方都能工作：

cp -r .claude/skills/avo ~/.claude/skills/avo

然后，在任何目录的 Claude Code 会话中：

使用 avo 工具将 game2048 目标进化 10 步。调用 avo_start_run，然后循环：avo_next_step，完成它要求的工作，反复 avo_evaluate 直到您满意，然后 avo_submit。如果它报告停滞，调用 avo_supervisor_brief，回答它，并用 avo_record_supervisor 记录。

这十一个工具就是完整的循环：

Codex

Codex CLI 支持 MCP 并读取 AGENTS.md，所以这两部分都能工作：

codex mcp add avo -- python3 -m avo.mcp_server

位于仓库根目录的 AGENTS.md 记录了该循环以及保持运行诚实性的规则；Codex 在此目录中工作时会自动发现它。

不使用 MCP

每个工具都有一个对应的 CLI 版本，因此普通 shell 也能同样工作 —— 这是最便携的选项，适用于任何智能体，或手动操作：

avo start --target game2048          # seeds x0 and prints the first prompt
# ... edit runs/<id>/work/, run runs/<id>/avo-eval as often as you like ...
avo submit -m "expectimax depth 2 with a positional weight matrix"
avo prompt                           # the next step's prompt
avo status
avo plot -o trajectory.png

已完成的运行

仓库附带两个完整的运行，两者均由 Claude Code 会话以会话模式驱动，并且都包含各自的死胡同。

attention_decode —— 击败厂商内核

examples/attention-decode-run/ 进化 attention 的解码步骤：一个查询 token 对应长 KV 缓存，这是 LLM 为每个生成的 token 运行的计算。评分基准是 mx.fast.scaled_dot_product_attention —— Apple 自己的融合 Metal 内核。

三步内 0.05 → 1.14× MLX。 这就是进化出的内核真正击败厂商实现的那个例子，而有趣之处在于如何：

• 第 1 步是实现 —— split-K flash-decoding 将内核从 1.6 GB/s 提升到 106 GB/s，约为机器流式极限的 95%。这达到了 0.95× MLX，并耗尽了那个杠杆：你不可能比内存控制器交付字节的速度更快地读取字节。

• 第 2 步是数学。 该目标的门控是输出误差预算，而不是完全相等，因此搜索可以改变计算。测量显示，99.9% 的 softmax 概率质量集中在 ~11% 的键中，因此内核现在对每个键评分，但只在高于某个阈值时读取 V，该阈值经过推导，使得被丢弃的概率质量可证明低于 0.3%。这突破了 1.0，花费了 2% 的误差预算。

这一教训具有普遍性：一旦受带宽限制的内核达到屋顶线，剩下的唯一杠杆就是减少读取的字节数，而这正是一种算法层面的改变。

阅读完整报告 →

attention_c —— 论文自身的领域

examples/attention-c-run/ 在 C 中进化一个前向 attention 内核，达到简单 NumPy/BLAS 实现的 2.2×，并接近 NEON 屋顶线。请注意这种诚实的表述：该基线不是经过调优的 attention 库，而且该内核比 torch 的 CPU SDPA 和 MLX 更慢 —— Apple 的 AMX 矩阵单元无法从可移植 C 访问。报告给出了完整对比。

其中有三个发现值得点击：

• 论文自己的算法在这里是错误的答案。 采用流式在线 softmax 的 FlashAttention 风格分块内核两次测量都更差。在这些规模下，整个 head 可以放入 L2，因此为利用局部性而分块毫无收益，而逐块的重新缩放纯粹是额外工作。代价是算术，而不是内存。

• -ffast-math 会静默破坏标准的快速 exp，因为它从代数上抵消了该快速 exp 所依赖的加魔法常数舍入技巧。正确性门控在一个 N=3 的形状上抓住了它；而吞吐量数字永远不可能。

• 这次运行迫使对目标进行了修复。 在一台处理其他工作的笔记本电脑上对原始 GFLOP/s 评分并不是一种测量 —— 相同的代码在二十分钟内在 44–76 GFLOP/s 之间波动。现在 eval.py 在同一进程内、与候选交替地对 NumPy/BLAS 参考进行计时，并对比值评分。

阅读完整报告 →

game2048 —— 进化游戏策略

examples/game2048-run/ 是 game2048 目标的一次完整 8 步运行，由 Claude Code 会话以会话模式驱动。该目录保存了未经编辑的输出：进化出的策略、算子的工作笔记、完整轨迹、它构建的筛选工具，以及它的死胡同。

876 → 43 826 —— 种子的 50 倍，最强基线的 14 倍。 达到 2048 的游戏：0% → 77%。最佳方块：512 → 8192。Apple M5，单线程，仅使用标准库。

改进以被平台期隔开的离散跳跃形式到来，与论文的图 5 相符。两个平坦版本是纯吞吐量工作，为下一步花费的预算买单 —— 与论文的 v19→v20 无分支重缩放变化所起的作用相同。

最大的一次单项提升（+50.5%）不是优化。该基准对累积的游戏得分进行评分；而启发式只衡量棋盘看起来有多可存活，因此搜索中没有任何东西知道合并两个 256 会获得 512 分。四步吞吐量工作合计只值 +27%；一步检查实际在优化什么，却值 +50%。

阅读完整报告 →

随仓库附带的内容

game2048 —— 进化游戏策略

在严格的思考时间预算下，将 agent.py 进化成你能做到的最强 2048 玩家。评分方式为四组、每组十二个确定性种子的平均游戏得分的几何均值。超出 120 秒预算会得零分，而不是“略少一点”—— 因此搜索深度、评估函数成本和剪枝相互权衡，而这一权衡就是问题所在。

在 Apple M5 上测得：

强 expectimax 玩家的得分可达数万。上面的已完成运行达到了 43 826。

attention_c —— 进化一个内核，论文自身的领域

在 C 中进化一个单精度前向 attention 内核：O = softmax(QKᵀ/√D)V，支持因果和非因果，D = 64。门控条件是与 float64 参考在十八种形状上的一致性 —— 包括质数和差一（off-by-one）序列长度，因此一个不能正确处理尾部的内核会失败，而不是悄悄获得好分数。

评分方式为与在同一进程中计时的 NumPy/BLAS 参考相比的加速比，取四种序列长度 × 两种掩码模式的几何均值。1.0 表示与库持平。对比值而不是原始 GFLOP/s 进行评分，使基准对机器正在做的其他任何事情免疫 —— 在共享笔记本电脑上，绝对吞吐量的波动幅度超过大多数优化本身的价值。

知识库涵盖在线 softmax 公式、分块与块大小选择、CPU 向量化、线程，以及如何探测主机而不是假设某种 ISA。要击败 BLAS，需要其中大部分。

工作原理

运行目录

runs/<run-id>/
  work/              the candidate x_t — a standalone git repo whose history IS the lineage
    .avo/scores.jsonl    every committed version's full score vector
  kb/                the knowledge base K, copied in so paths are stable
  avo-eval           f, as a zero-argument shim the agent can call at will
  NOTES.md           scratch space that survives across steps
  trajectory.jsonl   every step, accepted or rejected
  rejected/          the diff of each rejected candidate, kept for the record
  logs/              evaluator and agent logs

将谱系做成 git 仓库，意味着智能体可以用它已经熟悉的工具来检查 P_t —— git log、git show v7:attention.c、git diff v6 v7 —— 而不是专用的 API。每个被接受的版本都是一个标记为 vN 的提交，其提交信息携带得分向量。

提交策略

论文 §3.2：候选只有通过正确性门控并且匹配或改进截至目前最佳已提交得分时，才会被提交。其他一切都会被回滚，其 diff 会被存档 —— 它仍然是智能体内部搜索轨迹的一部分，但永远不会进入谱系。

正确性是一道门，而不是一个维度。失败的候选无论其测量结果如何，都只得零分（§3.1）。在 attention_c 中，这意味着一个快 10 倍但数值错误的内核，与一个无法编译的内核价值完全相同。

得分向量

f(x) = (f_1(x), …, f_n(x)) —— 每个基准配置一个数值，以几何均值作为被最大化的标量。这正是让每个配置的变动具有诊断性的原因：一个对 n1024 有帮助但对 n128 有害的改动是一个阻塞性问题，而不是一次胜利，仅看聚合值会掩盖这一点。

监督者

论文 §3.3：长时间自主运行会以两种方式失败——智能体在耗尽当前攻击路线时会停滞，或者陷入不断失败的无产出编辑循环。在没有新最优值的情况下经过 N 步（默认 3 步）后，AVO 会停止并请求重定向：对整条轨迹进行回顾，提出几个具体且不同的优化方向。该重定向作为强先验被注入到下一个变异提示中，并且只被一个步骤消耗。

在会话模式下，监督者就是同一个会话换了一顶帽子，这足够廉价，可以实际使用。在无人值守模式下，它是一个以只读意图运行的独立代理。

轨迹

avo plot 渲染论文中的图 5/6：运行最优几何均值作为阶梯函数，每个新最优值处有实心圆点，每个配置的曲线用虚线表示，基线用水平线表示。与论文相同的注意事项——它展示的是已提交的序列，而不是提交之间探索的内部搜索树。

无人值守模式

要复现论文的设置，其中操作者是一个生成的代理，且没有人监控：

avo run --target attention_c --backend claude_cli --max-steps 40 --time 12h
avo run --resume runs/attention_c-20260321-091500 --time 24h

后端：claude_cli（Claude Code 无头模式——最接近论文代理的类比）、api（基于 Messages API 的自包含代理循环，适用于只有 API 密钥的人）、agent_sdk（通过 claude-agent-sdk 进行进程内运行），以及 mock（一个 shell 命令，用于在没有模型的情况下测试机制）。

这会消耗每个步骤的配额或积分。会话模式则不会。

添加你自己的目标

目标是一个包含 target.yaml、种子程序、知识库和评估器的目录。评估器可以是任何语言的任何可执行文件；整个契约是 stdout 上的一个 JSON 对象：

{"correct": true,
 "metrics": {"config_a": 1520.3, "config_b": 1477.0},
 "error": null,
 "notes": "shown to the agent"}

correct 是门控。metrics 是分数向量。被优化的标量是它们的几何均值，除非你提供了显式的 primary。

name: my_target
description: One line, shown in `avo targets`.
seed: seed                 # copied to work/ as x_0
knowledge_base: kb         # copied to the run dir as K
entrypoint: kernel.c       # informational, used in prompts

evaluate:
  command: ["python3", "{target}/eval.py", "--workdir", "{workdir}"]
  timeout: 30m

baselines:                 # optional, measured once before evolution starts
  command: ["python3", "{target}/eval.py", "--baselines"]

score:
  direction: maximize

agent:
  goal: |
    What the agent is actually trying to do, and what the trade-offs are.

完整契约见 docs/TARGETS.md，最小工作示例见 tests/fixtures/toy/。

知识库值得认真投入。它是 Agent(P_t, K, f) 中的 K，也是区分一个代理用十步从第一性原理重新发现平铺，还是两步就达到目标的差异所在。

什么是忠实的，什么不是

忠实的：

• 算子公式 Vary(P_t) = Agent(P_t, K, f) —— 一个真实的编码代理，具有文件编辑、shell 访问和持久记忆，没有任务特定的修改

• 基于 git 备份状态的单谱系连续演化（§3.3）

• 正确性门控和 n 维分数向量（§3.1）

• 匹配或改进的提交策略，失败的尝试被排除在谱系之外（§3.2）

• 监督者对停滞和无产出循环的干预（§3.3）

• 跨基准配置的几何均值聚合，以及 Figure 5/6 轨迹图

不忠实的，且有意为之：

• 硬件。 论文在 B200 GPU 上针对 cuDNN 和 FlashAttention-4 演化注意力核。attention_c 是在 CPU 上针对 NumPy/BLAS 的相同问题。优化在种类上可迁移（平铺、在线 softmax、向量化、调度），但在幅度上不可迁移。

• 规模。 论文运行了 7 天，40 个提交版本，500 多个探索方向。会话模式运行 10–20 步是演示，不是复现。

• 种群结构。 与论文一样，这实现了单谱系情况以隔离算子。存档和岛屿机制与公式兼容，但未实现。

仓库布局

src/avo/
  types.py        Score, LineageEntry, the correctness gate, geomean
  config.py       target specs and run configuration
  lineage.py      P_t as git history
  scoring.py      f as an external process
  knowledge.py    K
  prompts.py      the variation and supervisor prompts — the whole framework/agent interface
  run.py          run state: seed, evaluate, commit policy, trajectory
  session.py      driver: the session you already have is the operator
  loop.py         driver: unattended, spawns an agent per step
  mcp_server.py   the same operations as MCP tools (no dependencies)
  cli.py          the same operations as subcommands
  plot.py         Figure 5/6
  agents/         backends for unattended mode
targets/
  game2048/       policy evolution under a time budget
  attention_c/    kernel evolution — the paper's domain, on a CPU
examples/
  attention-decode-run/  beats Apple's own fused kernel by changing the maths
  attention-c-run/       CPU kernel evolution, with an honest baseline caveat
  attention-metal-run/   GPU prefill — every CUDA instinct measured worse
  game2048-run/          policy evolution — 50x the seed
docs/
  PAPER_MAP.md    every section of the paper, and where it lives in the code
  TARGETS.md      the evaluator contract
  DRIVING.md      how to drive a run from Claude Code, Codex, or a shell
AGENTS.md         cross-agent instructions (read automatically by Codex)
.claude/skills/   the `/avo` skill for Claude Code

引用

这是一个独立的复现。引用原始工作：

@article{chen2026avo,
  title  = {AVO: Agentic Variation Operators for Autonomous Evolutionary Search},
  author = {Chen, Terry and Ye, Zhifan and Xu, Bing and Ye, Zihao and Liu, Timmy
            and Hassani, Ali and Chen, Tianqi and Kerr, Andrew and Wu, Haicheng
            and Xu, Yang and Chen, Yu-Jung and Chen, Hanfeng and Kane, Aditya
            and Krashinsky, Ronny and Liu, Ming-Yu and Grover, Vinod and Ceze, Luis
            and Bringmann, Roger and Tran, John and Liu, Wei and Xie, Fung
            and Lightstone, Michael and Shi, Humphrey},
  journal = {arXiv preprint arXiv:2603.24517},
  year    = {2026}
}

根据 Apache-2.0 许可。与 NVIDIA 无关，也未获得其认可。