框架自进化度量 proteus-evolve/Proteus

让任何智能体框架自我进化。

接入。进化。度量。

选好你的框架，开始进化。
15 秒进化轨迹。探索交互式演示 →

https://github.com/user-attachments/assets/63311c1e-1ad9-4821-81b4-044cf5bf4650

快速开始 • 内置框架 • 工作原理 • 回合循环 • 接入你的框架 • 配方 • 自带基准测试 • 添加度量 • 可视化运行 • v0.4.0 说明 • 环境 • 度量

接入任何智能体框架 × 任何模型，让它在许多上下文全新的回合里重写自己的框架，并度量框架如何变化——在单个目标、多个目标，甚至完全没有目标的情况下。

名字取自那位随心改变形态的海神：Proteus 观察框架重塑自身，并给你一把尺子去度量这种变化。

🔭 Proteus 有何不同

智能体的自我改进正从权重转向框架——也就是模型运行所依赖的提示词、记忆、技能、工具和控制循环。近来的系统进化框架，是为了提高基准测试分数。Proteus 问的是另一个互补的问题：一个自我进化的框架实际上做了什么，初始条件会留下永久的印记吗？

有三点让它区别于所有现有的框架进化系统：

1. 与框架无关。 其他系统进化的框架是用它们自己的原语搭出来的。Proteus 进化的是你的框架：实现一个很小的 HarnessAdapter，你的智能体——内置的离线 minimal 框架（命令行默认）、DeepSeek Harness、Pi、Aki，或者你自己写的——都能接入同一套框架、沙箱和度量。
2. 有目标 和 无目标，评估器可见或隐藏。 其他方案把单一模式写死：一个基准验证器，智能体看不到分数，目标强制存在。Proteus 覆盖整个空间——no-goal | one goal | many goals，评估器要么让智能体看见（在上下文刷新的阶段），要么永远看不到。无目标、无压力的演化是一等模式。
3. 度量工具，而不只是分数。 其他方案报告任务通过率。Proteus 为框架本身提供标尺：框架状态之间的结构距离（按表面、路径长度）、结晶 / 交换测试（移除倾向，把框架读回来），以及带置换检验的行为距离（动作偏好统计量）。每个条件都用同一把尺子来读。

🚀 60 秒演示（不需要 API key，不需要 Docker）

pip install proteus-evolve==0.4.0 # no model SDK; Python 3.10 adds only a TOML compatibility package

自带的 minimal 框架完全离线运行，所以你能在接入真实智能体之前看到整条流水线：

proteus run --harness minimal \
--arm neutral --arm review:notes --arm review:tools \
--seeds 4 --episodes 8 --out runs/demo
proteus measure --harness minimal --out runs/demo
proteus visualize --out runs/demo # local UI: http://127.0.0.1:8301

arm seeds notes tools (mean units built)
neutral 4 3.5 4.0
review_notes 4 13.0 0.0
review_tools 4 3.8 8.0

behavioural R (between/within arms, last episode): 3.075 p=0.0150

装好的动作偏好会可测量地改变框架长成什么样——而同一个 measure 读无目标运行和有目标运行的方式完全一样。

Proteus Visualize 打开已有的 sweep，支持循环回放、回合详情、快照 / 候选身份，以及同一套结构和行为工具。查看不会调用模型；只有显式通过命令行发起的启动才会调用。
配置、证据和导出边界见 docs/VISUALIZE.md。

🧩 开箱即用的框架

| 适配器 | 是什么 | 需要 |
| minimal | 离线参考框架（模拟策略） | 无 |
| llm | 同一个框架，由实时模型驱动——任何 OpenAI 兼容端点，默认 DeepSeek | API key |
| dsh | DeepSeek Harness，无头配置档，运行在准备好的容器里 | Docker + DeepSeek key |
| pi | Pi——Mario Zechner 的极简编码框架（4 个工具，原生 AGENTS.md + 技能） | Docker + DeepSeek key |
| codex | OpenAI Codex CLI —— 固定版本、可自我演进的 Rust harness，使用原生 codex exec --json 轨迹 | Docker + Codex 认证/API key |
| aki | Aki 研究 harness（论文中的实验装置） | 研究用 checkout |
| 你的 | --harness <module>:<Class> —— 无需注册 | 你的适配器 |

dsh、pi 和 codex 是三个可自我演进的第三方集成。在 seed 阶段，每个适配器会把固定版本 harness 的真实源码提取到 harness/src/。在第 N 个 episode 中，四个阶段都启动同一份只读的 last-valid 快照，同时写入一份单独的候选。reflect 之后，Proteus 重新构建并验证候选；只有通过验证的候选才会在第 N+1 个 episode 中激活。构建失败的候选不会被激活，但它的完整目录树会作为下一个可写修复候选被恢复；下一个 episode 中运行的 harness 依然健康。因此，源码和 instructions、notes、tools、skills 一样，是一层可测量、可快照的 loop 表面。适配器仍然不改动上游仓库：它们安排运行副本、为每个阶段启动一个准备好的容器，并解析 harness 自己的会话日志。

🏗️ 工作原理

flowchart LR
U["Run configharness × modelgoal + evaluatorsarms + seeds"] --> F["Proteus frameworkassemble phase prompts"]
F --> A["HarnessAdapterrun one episode"]
A --> H["harness/evolving, snapshotted subject"]
A --> T["task/optional benchmark workspaceoutside the snapshot"]
A --> L["native harness logs"]
L --> E["evaluatorshidden or observe-visible"]
E --> S["selection + snapshotaccept or preserve-and-restore"]
S --> F

每个 seed 运行 N 个上下文全新的 episode。演进后的 harness 文件会跨越 episode 边界；选择启用框架连续性的适配器还会收到一份有界操作交接，存放在被测量快照之外。默认情况下，一个 episode 包含四个阶段：

observe → propose → act → reflect

- observe —— 盘点现状；如果你配置了可见评估器，这里会显示它在上一 episode 的得分。
- propose —— 列出改进自己 harness 的方法。
- act —— 通过编辑 harness 落实其中一条。如果有目标，每个全新阶段都会宣告它，让观察和规划始终与目标对齐。
- reflect —— 决定保留什么。

框架负责一切不属于 harness 的东西（提示词、目标文本、评估器路由、快照、选择、测量）。适配器负责一切属于 harness 的东西（四个阶段实际如何执行）。正是这种分工让 Proteus 与 harness 无关。

核心对象

| 概念 | 是什么 |
| HarnessAdapter | harness 实现的契约：它的表面、阶段连续性能力、如何运行 episode、如何读取动作轨迹、如何安装/移除 disposition |
| Surface | 一块可编辑、可持久化的区域（memory / skills / tools / code / …），以数据形式声明，因此测量层不需要硬编码名称 |
| Disposition | 动作偏好扰动——在 t=0 施加的单个、可移除改动（提示词后缀、配置值或代码补丁） |
| GoalConfig | 有目标 / 无目标 / 多目标，每个评估器为 HIDDEN 或 OBSERVE 可见，外加外层循环选择（accept_reject） |
| Sandbox | 回合运行的位置；LocalSandbox（可信）或 DockerSandbox（操作系统级隔离，网络可调） |

动作偏好

动作偏好以 Disposition 形式装入，并保证可移除，这样结晶测试就能把它拿走，读出 harness 自己搭出了什么：

from proteus.core import review, record, NEUTRAL
review("memory") # each phase: review your memory, act or not
record("tools") # keep your tools current as you work
NEUTRAL # the control, F0 — no perturbation

目标与评估器

from proteus.core import EvaluatorSpec, GoalConfig, Visibility

GoalConfig.no_goal() # unpressured evolution
GoalConfig.of(text="Become more reliable.") # stated goal, no evaluator
GoalConfig.of(
text="Become more reliable.",
evaluators=(EvaluatorSpec("reliability", my_eval,
visibility=Visibility.OBSERVE),),
) # agent sees the score next episode
GoalConfig.of(text="Pursue A and B together.",
evaluators=(EvaluatorSpec("a", eval_a),
EvaluatorSpec("b", eval_b)),
selection="accept_reject") # outer loop rejects regressions

评估器可以是任何可调用对象 (trace, ctx) -> EvalResult；你可以带上基准验证器、LLM 裁判，或者用内置的评估器（proteus.core.evaluators）。

评估器可见性、选择资格与调度彼此独立。你可以在 H0 评估、每 N 个回合评估一次，或在显式检查点评估，同时在全新上下文中保留带日期的反馈。见评估器控制。默认的四阶段协议也可以自定义；DSH 支持显式中断阶段恢复，且不重新填充工具预算。见回合控制。

沙箱

from proteus.sandbox import SandboxConfig, DockerSandbox
DockerSandbox(SandboxConfig(network="none")) # no egress
DockerSandbox(SandboxConfig(network="host", # needs an LLM endpoint
env_passthrough=("OPENAI_API_KEY",),
mem_limit="4g"))

自编辑智能体会写自己的代码并运行，所以应用层文件沙箱关不住它——Proteus 在容器里运行真实的 harness，容器的文件系统里只有 harness，别无他物。

🔌 接入你的 harness

输入是一个仓库——git URL 或本地路径：

proteus env scaffold --from https://github.com/org/their-harness --name theirs --ref v1.2.0
proteus env build theirs # pinned image, resolved sha recorded in the manifest
write the adapter (7 methods), then:
proteus check --harness mypkg.theirs_adapter:TheirsHarness --episode
proteus run --harness mypkg.theirs_adapter:TheirsHarness --arm neutral ...

proteus check 会用机器验证契约（通过指纹往返验证可移除处置、可快照性、轨迹形状）。完整指南见 docs/ADAPTERS.md。
想从能跑的骨架开始，而不是从空文件起步，可以执行 python -m proteus.scaffold adapter MyHarness，它会复制带完整注释的 proteus/examples/adapter_template.py——详见 CONTRIBUTING.md。这些模板也会发布到 PyPI；在 Git 检出目录之外，默认输出到当前目录（也可以用 --dest 显式指定）。

📦 预制环境

environments/ 里包含两种环境形态。清单驱动的环境把 Dockerfile 或预构建镜像与 environment.toml 配对；内置的 dsh-src/ 和 pi-src/ 镜像则不同，它们从固定版本的上游源码检出构建，因为镜像里必须包含适配器之后要提取并重建的确切源码和工具链。
两种形态下，演化中的状态都放在挂载里，绝不放进每次运行单独的镜像。约定见 environments/README.md；设计说明见 docs/ENVIRONMENTS.md。

📏 测量

from proteus.measure import distance, stream, crystallize

- distance——每个表面的结构距离（新增 / 删除 / 修改）、路径长度（proteus measure --travel）。
- stream——行为距离（频率 / 顺序 / 流程）以及组间/组内置换检验 R。
- crystallize——把演化后的状态挂载到中性处置下，检验它能否读回为自己的终点（两阶段保真度 + 臂偏移）。

要添加逐回合的测量评估器、运行后统计量，或适配器原生的计数器，见 docs/MEASUREMENTS.md。指南覆盖它们各自不同的契约、产物边界、命令行/报告集成、统计规则和测试。

📤 输出

每次运行的主要产物是它的演化历史，形式为一个 git 仓库——每个回合一个提交。你可以留在本地、随意浏览，或推送到任何地方（绝不自动推送）：

proteus repo export runs/demo/runs/run-<id> my-evolution # normal repo, git log = the trajectory
proteus repo push runs/demo/runs/run-<id> git@github.com:you/my-evolution.git

每次 sweep 还会附带一个实时跟踪页面——逐运行进度、逐表面增长曲线、评估器得分——sweep 运行期间持续更新：

proteus watch --out runs/demo # http://localhost:8300/report.html
跟踪数据（条件标签、隐藏分数）存放在 sweep 层级，位于 run 根目录之外，所以不断演化的智能体永远读不到自己的条件。

📊 状态

v0.4.0（研究预览版）。目前可用：离线 minimal harness；实时 llm harness；固定版本、源码可演化的 DeepSeek Harness、Pi 和 Codex CLI 适配器，支持按 episode 冻结激活、自动回滚、精确树边界门禁、重建缓存、回合预算、相位感知的 act-priority 预算计划和智能体自行编写的检查点跟踪，以及任务挂载；Aki 研究适配器；本地、Polyglot 和 SWE-bench 任务集成；可断点续跑的 sweep、可配置相位、定时评估器和本地 Visualize 工作区；完整的测量、审计、可靠性、报告和仓库导出路径；以及适配器/环境工具。CI 覆盖 Python 3.10–3.14。单独的 release-smoke 工作流会在公开发布集（minimal、llm、dsh、pi、codex）上跑两个 episode，走一遍 benchmark 路径，并要求三个容器 harness 都能编辑自己的源码并启动编辑；发布使用固定上游版本，每周的上游 canary 仅供参考。作为跨实现校验，把 Proteus 的行为标尺应用到研究运行上，能独立复现其核心动态：各臂在 episode 1 分开（R = 1.63），到 episode 30 收敛（R = 0.93）。

🤝 贡献

最有价值的两种贡献是新 harness 适配器（演化另一个智能体框架）和新 benchmark（在更多目标下测量）。两者都是单文件、契约校验、CI 门禁的增量：

python -m proteus.scaffold adapter MyHarness # skeleton -> proteus/adapters/myharness.py
python -m proteus.scaffold benchmark my_task # skeleton -> proteus/bench/my_task.py
proteus check --harness proteus.adapters.myharness:MyHarness --episode

分步指南（契约、模板、tests/test_conformance.py 中的一致性门禁、PR 预期）见 CONTRIBUTING.md。

需要帮忙的地方，每条一行——带难度标签的完整列表见 ROADMAP.md：

- 更多 harness — 先做 Hermes Agent（Python，内置自我改进接口），然后是 SWE-agent、OpenClaw、OpenHands、OpenCode、Goose。
- 更多 benchmark — BigCodeBench-lite 和 LiveCodeBench 子集、SWE-bench Lite/Verified 接线，以及完成 swe 的沙箱评分（HumanEval 和 MBPP 已发布）。
- 分析 — proteus compare，用于并排对比各臂/各运行；episode-atlas 视图。
- 可复现性与成本 — 按 episode 统计 token/成本；一条命令复现。

📖 引用

见 CITATION.cff。预印本公开后会补充论文引用。

License

MIT。