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

适用于任何智能体框架的自我进化。

接入。进化。度量。

快速开始 •
框架 •
工作原理 •
回合循环 •
接入你的框架 •
配方 •
自带基准 •
添加度量 •
v0.3.0 说明 •
环境 •
度量

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

以那位随心所欲变换形态的海神命名：Proteus 观察框架重塑自身，并为你提供度量这种变化的标尺。

🔭 Proteus 为何与众不同

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

有三点让它与所有现有的框架进化系统截然不同：

1. 框架无关。 其他系统进化的是用它们自己的原语构建的框架。Proteus 进化的是你的框架：实现一个小的 HarnessAdapter，你的智能体——内置的离线 minimal 框架（CLI 默认）、DeepSeek Harness、Pi、Aki，或你自己的——就能接入同一套框架、沙箱和度量体系。
2. 有目标和无目标，评估器可见或隐藏。 其他系统硬编码单一模式：一个基准验证器、智能体对分数不可见、目标强制存在。Proteus 涵盖
空间——no-goal | one goal | many goals，而评估者要么被智能体看到
（在观察阶段），要么永远看不到。无目标、无压力的演化是一种
一等模式。
3. 一种测量工具，而不仅仅是一个分数。 其他人报告任务通过率。Proteus
为 harness 本身提供了标尺：harness 状态之间的结构距离
（按表面、路径长度）、结晶 / 交换测试（移除 disposition，
回读 harness），以及带置换检验的行为距离（动作偏好统计量）。
每个条件都用同一把标尺读取。

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

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

捆绑的 minimal harness 完全离线运行，因此你可以在接入真实智能体之前
看到整个流水线：

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

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

一个已安装的动作偏好会可测量地改变 harness 所生长出的内容——而同一个
measure 会以相同方式读取无目标运行和有目标运行。

🧩 开箱即用的 Harness

| adapter | 它是什么 | 需要 |
|---|---|---|
| minimal | 离线参考 harness（mock policy） | 无 |
| llm | 由实时模型驱动的同一 harness——任何 OpenAI 兼容端点，默认 DeepSeek | 一个 API key |
| dsh | DeepSeek Harness，headless profile，在准备好的容器中 | Docker + 一个 DeepSeek key |
| pi | Pi——Mario Zechner 的最小编码 harness（4 个工具，原生 AGENTS.md + skills） | Docker + 一个 DeepSeek key |
| aki | Aki 研究 harness（论文的装置） | 研究 checkout |
| yours | --harness :——无需注册 | 你的 adapter |

dsh 和 pi 是源码演化的第三方集成。在 seed 时，每个 adapter
会将固定 harness 的真实 TypeScript 源码提取到 harness/src/。在第 N 个 episode 中，
所有四个阶段都会启动同一个只读的 last-valid 快照，同时写入一个单独的
candidate。在 reflect 之后，Proteus 会重建并验证 candidate；只有通过验证的
candidate 才会在第 N+1 个 episode 中激活。构建失败会被阻止激活，同时
其确切的树会被恢复为下一个可写的修复 candidate；下一个 episode 的
运行中 harness 仍保持健康。因此，源码是一个经过测量、快照化的 loop 表面，
与 instructions、notes、tools 和 skills 并列。该
适配器仍然不改动上游仓库：它们安排运行副本，
为每个阶段启动一个准备好的容器，并解析测试框架自身的会话日志。

🏗️ 工作原理

flowchart LR
U["运行配置测试框架 × 模型目标 + 评估器分支 + 种子"] --> F["Proteus 框架组装阶段提示词"]
F --> A["HarnessAdapter运行一个回合"]
A --> H["harness/不断演化、带快照的被测对象"]
A --> T["task/可选的基准工作区位于快照之外"]
A --> L["原生测试框架日志"]
L --> E["评估器隐藏或观察可见"]
E --> S["选择 + 快照接受或保留并恢复"]
S --> F

每个种子运行 N 个上下文全新的回合。演化后的测试框架文件跨越回合
边界；选择启用框架连续性的适配器还会收到一份有界的操作
交接，存储在测量快照之外。一个回合包含四个阶段：

observe  →  propose  →  act  →  reflect

- observe — 盘点现状；如果你配置了可见评估器，上一个
回合的得分会在这里显示。
- propose — 列出改进自身测试框架的方法。
- act — 通过编辑测试框架来执行其中一项。目标（如果有）会在每个
全新阶段中宣告，以便观察和规划始终与之保持一致。
- reflect — 决定保留什么。

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

核心对象

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

动作偏好

动作偏好以 Disposition 的形式安装，并保证可移除，因此
结晶测试可以将其移除，并读取测试框架自行构建出的内容：

from proteus.core import review, record, NEUTRAL
review("memory")     # 每个阶段：审视你的记忆，决定是否行动
record("tools")      # 在工作过程中保持你的工具为最新
NEUTRAL              # 对照组，F0——无扰动

目标与评估器

from proteus.core import EvaluatorSpec, GoalConfig, Visibility
GoalConfig.no_goal()                                    # 无压力演化
GoalConfig.of(text="Become more reliable.")             # 已声明目标，无评估器
GoalConfig.of(
text="Become more reliable.",
evaluators=(EvaluatorSpec("reliability", my_eval,
visibility=Visibility.OBSERVE),),
)                                                       # 智能体在下一回合看到分数
GoalConfig.of(text="Pursue A and B together.",
evaluators=(EvaluatorSpec("a", eval_a),
EvaluatorSpec("b", eval_b)),
selection="accept_reject")               # 外层循环拒绝回退

评估器是任何可调用对象 (trace, ctx) -> EvalResult；可以引入基准验证器、LLM 评判器，或使用内置评估器之一（proteus.core.evaluators）。

沙箱
python
from proteus.sandbox import SandboxConfig, DockerSandbox
DockerSandbox(SandboxConfig(network="none"))    # 无出口
DockerSandbox(SandboxConfig(network="host",     # 需要 LLM 端点
env_passthrough=("OPENAI_API_KEY",),
mem_limit="4g"))

自编辑智能体会编写并运行自己的代码，因此应用级文件沙箱无法将其限制住——Proteus 在容器中运行真实 harness，该容器的文件系统只包含 harness，别无他物。

🔌 接入你的 harness

输入是一个仓库——git URL 或本地路径：
bash
proteus env scaffold --from https://github.com/org/their-harness --name theirs --ref v1.2.0
proteus env build theirs             # 固定镜像，解析后的 sha 记录在清单中
编写适配器（7 个方法），然后：
proteus check --harness mypkg.theirs_adapter:TheirsHarness --episode
proteus run   --harness mypkg.theirs_adapter:TheirsHarness --arm neutral ...

proteus check 会以机器方式验证契约（通过指纹往返验证可移除处置、可快照性、trace 形状）。完整指南：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。

📏 测量
python
from proteus.measure import distance, stream, crystallize

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

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

📤 输出

每次运行的主要产物是其作为 git 仓库的演化历史——每个回合一次提交。将其保存在本地、浏览它，或推送到任何你喜欢的地方（绝不自动执行）：

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

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

proteus watch --out runs/demo          # http://localhost:8300/report.html

跟踪数据（条件标签、隐藏分数）位于扫描层级，在运行根目录之外，因此演化中的智能体永远无法读取自己的条件。

📊 状态

v0.3.0（研究预览版）。目前可用的功能：离线 minimal 测试框架；实时 llm 测试框架；固定版本、源码可演化的 DeepSeek Harness 和 Pi 适配器，具有冻结的逐回合激活、自动回滚、精确树边界门、重建缓存、回合预算、阶段感知的 act 优先级预算计划和智能体编写的检查点跟踪，以及任务挂载；Aki 研究适配器；本地、Polyglot 和 SWE-bench 任务集成；可恢复的扫描；完整的测量、审计、可靠性、报告和仓库导出路径；以及适配器/环境工具。CI 覆盖 Python 3.10–3.14。单独的 release-smoke 工作流在公共发布集（minimal、llm、dsh、pi）上运行两个回合，演练基准测试路径，并要求两个容器测试框架都编辑自己的源码并启动该编辑；发布使用固定的上游版本，而每周的上游金丝雀测试仅供参考。作为跨实现检查，Proteus 的行为标尺应用于研究运行时，独立复现了它们的核心动态：各臂在第 1 回合分离（R = 1.63），并在第 30 回合收敛（R = 0.93）。

🤝 贡献

两个最有价值的贡献是新的测试框架适配器（演化另一个智能体框架）和新的基准测试（在更多目标下进行测量）。两者都是单文件、契约检查、CI 门控的添加：

python -m proteus.scaffold adapter MyHarness    # skeleton -> proteus/adapters/myharness.pymarkdown
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、Codex CLI、OpenHands、OpenCode、Goose。
- 更多基准测试 — BigCodeBench-lite 和一个 LiveCodeBench 子集，SWE-bench
Lite/Verified 接入，以及完成 swe 的沙箱化评分（HumanEval 和 MBPP
已发布）。
- 分析 — proteus compare 用于并排比较各 arm/运行；一个 episode-atlas 视图。
- 可复现性与成本 — 按 episode 统计 token/成本；一条命令复现。

📖 引用

见 CITATION.cff。预印本公开后将添加论文引用。

许可证

MIT。