cap-evolve

<p align="center"> <img src="docs/assets/cap-evolve-logo.png" alt="cap-evolve" width="200"/> </p> <h1 align="center">cap-evolve</h1> <p align="center"><em>观察能力进化</em></p> <p align="center"> <img src="https://img.shields.io/badge/status-beta%20(0.x)-orange" alt="status"> <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="python"> <img src="https://img.shields.io/badge/runtime%20deps-0%20(stdlib)-success" alt="deps"> <img src="https://img.shields.io/badge/license-Apache--2.0-informational" alt="license"> <img src="https://img.shields.io/badge/agent%20skills-18-7c5cff" alt="skills"> </p> **cap-evolve 是一个基于技能、与主机无关的优化框架，旨在优化任意智能体能力 —— 系统、工具/MCP 或整个技能包 —— 以适应您的评估，并通过代码和每次迭代的 Git 版本控制确保诚实性。** 您只需编写一个小型适配器（或让编码智能体为您编写）。cap-evolve 运行循环：评估 → 诊断失败 → 提出编辑 → 仅在显著提高保留分割得分时保留 → 提交 → 报告单个诚实数字。它优化智能体读取的内容，而不是其权重。 **目录：** [为什么选择 cap-evolve](#为什么选择-cap-evolve) · [安装](#安装) · [简单示例](#简单示例零-api) · [tau2-bench 示例](#tau2-bench-示例真实) · [优化您自己的](#优化您自己的) · [工作原理](#工作原理) · [比较](#比较) · [技能库](#技能库) · [结果](#结果) · [使用指南](#使用指南) · [许可证](#许可证) ## 为什么选择 cap-evolve - **优化提示、工具/MCP 和技能包** — 不仅仅是提示。可以选择一个或多个（`系统提示`, `工具`, `mcp-tool`, `技能包`）进行联合优化。 - **基于代码的优化，而不仅仅是重新措辞**。对于 `工具`，优化器可以编辑工具代码 — 添加验证/循环/组合工具，强制执行规则或执行停滞操作 — 并安全地交换，从不直接删除原始工具。 - **从单个提示为任何基准/智能体进行集成**。将一个接入简报粘贴到您的编码智能体；**接入完成整个集成** — 安装基准，连接适配器（包括轨迹 + 批处理快速路径），编写能力范围的优化器提示，并通过 `cap-evolve check` 门控 — 在花费任何预算之前。无需预先集成。 - **每个任务的因果反馈**。每次迭代，优化器都会看到哪些任务 ID 被以前的编辑**破坏**和**修复**，以及当前通过的集合，以保护它 - 因此它会进行大规模、多集群的编辑，而不会使收益下降。 - **代码中强制诚实，而不是文档中**。密封测试分割仅被精确评估一次，配对的、仅验证的显著性门控（Δ > k·SE)决定每次接受 — 它们都位于 `cap_evolve` 核心，奖励被聚合的唯一地方。 - **主机和智能体无关**。优化器是任意编码智能体 CLI（claude-code, codex, gemini, opencode, ibm-bob, ...），由一行注册表解析。没有框架锁定。 - **Git 版本控制的迭代 + 优化器内存** — 每个候选者都是一个提交；被拒绝的方法被记住，永远不会重新提出。 - **每次迭代的优化器 $ 预算**，由优化器 CLI 自身强制执行（例如 claude `--max-budget-usd`），以及硬性总上限和试运行估计。 - **实时仪表盘** — 每次迭代的优化器和运行器成本 + 时间，接入成本，血统树，每次迭代的差异，以及任务 × 迭代的通过/失败热图。 - **原生技能 & 可轻松扩展** — 一个新能力，算法或优化器是一个文件夹或注册表行。 - **零运行时依赖** — 核心是纯 Python 标准库。 ## 安装 需要 **Python 3.10+** 和 **git**。 ```bash git clone <repo> cap-evolve && cd cap-evolve python3 -m venv .venv && source .venv/bin/activate # 推荐（隔离环境） pip install ./core # 诚实评估核心（包：cap-evolve-core，CLI：cap-evolve） pip install ./dashboard/backend # 可选：实时仪表盘 UI（cap-evolve run --dashboard auto） ./install.sh # 可选：将技能复制到智能体主机的技能目录 cap-evolve version # 验证安装 ``` > **如果您的默认 pip 索引需要身份验证**，请在 `pip install` 行中附加 `--index-url https://pypi.org/simple` > （cap-evolve-core 本身具有零运行时依赖）。 优化真正的智能体还需要：一个作为优化器的编码智能体 CLI（例如 `claude`，`codex`，`gemini`）及其凭证，以及您的**运行器**的模型凭证 — 所有这些都应在存储库根目录的 `.env` 中（例如 `ANTHROPIC_API_KEY`，`OPENAI_API_KEY`，`RITS_API_KEY`，`WATSONX_*`）。下面的简单示例不需要任何这些。 ## 简单示例（零-API） 通过确定性、无密钥运行验证安装。`toy_calc` 是一个占位智能体，只有当其系统提示包含 `[CALC]` 标记时才会正确回答；`mock` 优化器添加了它，因此分数明显上升 — 没有调用模型。 ```bash bash examples/toy_calc/run.sh ``` 预期：种子提示在验证集上的得分 `0.0`；优化后的提示被门控接受，并在密封的测试分割上得分 `1.0`。 ```text baseline_val 0.0 -> test_reward 1.0 (gate-accepted, test sealed) + dashboard.html ``` 这正是 `core/tests/test_e2e_slice.py` 所断言的。 在任何浏览器中打开打印的 `dashboard.html` 以查看运行情况。 ## tau2-bench 示例（真实） 捆绑的 [`examples/tau2_airline`](examples/tau2_airline) 从一个提示带有一个全新的基准到一个诚实、优化的结果。它使用 `claude-opus-4-6` 优化器优化航空公司 **策略 + 工具**，使用 `gpt-oss-120b` 作为 **智能体和用户模拟器**，均通过 IBM RITS。 提交的运行将验证奖励从 **0.496 提升到 0.702（+0.206，≈ +41% 相对）**；请查看下面的标题数字和演练，或只需打开在 [`run_full/ui/`](examples/tau2_airline/run_full/ui/) 下提交的完整交互式仪表盘 — 使用 `cd examples/tau2_airline/run_full/ui && python3 -m http.server 8000` 提供它（然后 http://localhost:8000），或在 GitHub Pages / 任意静态主机上托管。 ```bash # 存储库根目录 .env 中的 RITS 凭证（RITS_API_KEY，RITS_API_URL）；请登录 Claude Code。 bash examples/tau2_airline/setup.sh # 接入：克隆 + pip install -e tau2-bench，搭建 # 项目，连接适配器 + RITS 垫片 + 种子， # 然后 cap-evolve check（硬门控） bash examples/tau2_airline/run.sh # cap-evolve run --dashboard auto：完整循环 + 实时 UI ``` 这是一个两命令路径，只是将 [`PROMPT.md`](examples/tau2_airline/PROMPT.md) 粘贴到您的编码智能体并说 *"按照 [`RUN.md`](RUN.md) 进行"* 的可执行记录。 接入将安装 tau2-bench（记录已解析的提交），连接适配器 — 包括 `run_batch` → tau2 的运行器，批处理 `run_trials` 快速路径，`trajectories()`（原生 tau2 跟踪）和 `score()`（读取 `reward_info`）— 并编写一个能力范围的优化器提示，然后通过 `cap-evolve check`。 它优化航空公司策略 + 工具，涵盖所有 50 个任务（每个任务 10 次试验），在每次迭代中使用每个 `--max-budget-usd` 上限，并带有配对的显著性门控和每次迭代的 Git 提交。 `--dashboard auto` 提供实时 capybara UI；`setup.sh` 标志 `--dashboard` / `--no-dashboard` 切换安装该服务器。 完整演练： [`DEMO.md`](examples/tau2_airline/DEMO.md)；从零开始重现： [`docs/REPRODUCE_tau2.md`](docs/REPRODUCE_tau2.md)。 这是生成此示例的精确提示（完整文本，原样来自 [`PROMPT.md`](examples/tau2_airline/PROMPT.md)) — 将其粘贴到您的编码智能体并说 *"按照 RUN.md 进行"*： ```text 按照 RUN.md 运行 cap-evolve 优化。 将此作为全新基准的接入/集成步骤。以下是接入所需的一切： # 1. 要优化的能力（每次编辑都会复制一份；原始文件不会被触及） - 类型： [系统提示, 工具] # 航空公司策略和工具，联合优化 - 工具含义： 编辑工具文档/描述；编辑工具行为/代码；以及 添加/删除工具，包括调用现有工具的组合工具 - 种子： tau2-bench 的规范航空公司策略 + 其航空公司工具集 - 种子工具： 种子工具文件必须为干净的可运行代码，就像接入方会生成的一样 — 真实工具体，无烘焙优化器/编辑 指令在 docstring 中（优化器可能更改工具生活在技能 SKILL.md 中，而不是种子文件） - capability_sources： 将 `capability_sources` 设置为基准的数据模型/类型 模块（工具导入它们）。 cap-evolve 逐字复制这些到优化器的工作目录 以便它可以针对正确的类型编写新的工具代码。 # 2. 基准测试 / 数据集（评估）- 安装它在接入期间 - 基准测试： tau2-bench，航空领域 - 仓库： https://github.com/sierra-research/tau2-bench （最新的 main；记录已解析的提交） - 安装： 克隆为 sibling 目录 ../tau2-bench，然后 `pip install -e ../tau2-bench` - 任务： "适配器" - 适配器从 tau2 加载所有 50 个航空公司任务 （tau2.domains.airline.environment.get_tasks） - 分割： 所有 50 个任务作为训练 = 验证 = 测试（无保留拟合指标；引擎 记录一个 splits_warning 并且报告将测试编号标记为拟合指标） # 3. 运行器（被测试的智能体）+ 模型 + 凭证 + 环境变量 - 运行方式： tau2 自有批处理运行器（adapter.run_batch -> tau2.runner.run_tasks） - 快速评估： 还要实现可选的适配器方法 run_trials(tasks, ctx, *, n_trials, base_seed) -> {task_id: [Rollout, ...]}。 在一次 tau2 run_tasks 调用中运行所有 num_trials，使用 num_trials=N（按 sim.trial 分组） at TAU2_MAX_CONCURRENCY=125，并返回 {task_id: [trial0, trial1, ...]} （长度 n_trials，trial-ordered）。当存在时，cap-evolve 调用它 ONCE 每候选人 而不是每个试验循环 run_batch；每个试验的持久性 （rollouts/<split>/<task>__<tag>__t<k>.json）保持不变，因此 pass^k / SE / resume 保持工作。 这将 N 个顺序评估传递合并为一个批处理运行。 - 智能体和用户模拟器： openai/gpt-oss-120b 通过 IBM RITS - RITS 连接： litellm 模型 "hosted_vllm/openai/gpt-oss-120b" + 每次调用 api_base + 额外标头 {"RITS_API_KEY": ...} （无 litellm monkeypatch，无 tau2 分叉） - 凭证： 存储库根目录 .env 中的 RITS_API_KEY (+ RITS_API_URL) - 并发性： TAU2_MAX_CONCURRENCY=125 # 4. 评分器（优化目标）- 以及指标来源 - 指标： tau2 自有任务奖励，范围 [0,1]（执行所需操作 + 信息传达） - 指标来源： tau2 在每次模拟中计算 `sim.reward_info.reward`; 每次检查的细分 位于 `sim.reward_info`（db_check / action_checks / communicate_checks / nl_assertions / env_assertions）。 实现适配器.score() 读取奖励 + reward_info，验证 score() 在固定滚动时是确定的（`cap-evolve check` 门控强制执行此操作）。 - 反馈： gold-AWARE 但 gold-SAFE - 哪些所需操作/信息未被遗漏（学习 信号），源自 reward_info 检查；永远不会泄露黄金答案。 - 目标： 在 VAL 分割上最大化平均奖励 # 4b. 轨迹（优化器读取的完整轨迹）- 路径是输入 - 位置： tau2 的批处理运行器可以将原生每个任务的模拟结果 （完整消息转录 + reward_info）持久化到一个目录中 via run_tasks(save_path=...)。 将 run_batch 的 save_path 指向评估下的一个目录，例如 <run_dir>/trajectories/val/ （可以是 tau2 编写的任何结构/格式）。 - 暴露： 实现 adapter.trajectories(split) 以返回该目录。 cap-evolve 复制 它 VERBATIM 到优化器的工作目录作为 ./trajectories/ 每次迭代， 因此优化器读取完整的、未修改的轨迹（不是有损摘要）。 （如果您无法持久化原生文件，请返回 None - cap-evolve 恢复到复制 它自己的每个 rollout JSON，已经嵌入每个 rollout 的完整消息跟踪。） # 5. 优化器（提出编辑）+ 模型 + 凭证 + 上下文 - 优化器： claude-code - 模型： claude-opus-4-6 - 凭证： 一个登录的 Claude Code 会话（或 ANTHROPIC_API_KEY） - runner_repo_path： ../tau2-bench （克隆的 checkout - 作为只读上下文提供给优化器） - 优化器说明： 从 scaffolded 模板中编写 .capevolve/project/optimizer/INSTRUCTIONS.md （保持其 {{...}} 占位符完整 - 套件在每次迭代中填充它们），定制指导 + “阅读这些” 指针（./trajectories/, ./guidance/<cap>/, ./guidance/diagnose/SKILL.md, ./guidance/optimizer/claude-code.md, ./LEDGER.md, ./JOURNAL.md, ./RUNMAP.md + ./prior_iterations/, ./PROCESS.md, ../tau2-bench）此基准。 编写的 INSTRUCTIONS 必须遵循流程： 读取 跨迭代文件 FIRST（LEDGER 事实，整个 JOURNAL 交接，RUNMAP + 迭代差异）和永远不会重新提出被拒绝的方法；解决所有失败 集群每次迭代（为每个集群创建一个子代理，每个工作树中）， 合并所有编辑为一个候选者，运送多个编辑类和一个新的 带有任何能力-差距/停滞集群的代码工具；填写 ./PROCESS.md（必填 可解释性）并追加到 ./JOURNAL.md 每次迭代。 对于工具功能， 代码工具是主要编辑 - 验证工具在代码中强制执行规则然后调用现有工具 并删除原始工具；工作流工具会折叠重复出现的序列； 以及一个复合 WRITE 工具，它执行卡住的多步骤 操作（然后删除原始写入基元），因此智能体无法分析， 确认然后失败执行 - 而不是文档散文。 # 6. 预算 / 门控 - 算法： hill-climb (--focus all) - max_iterations: 10 num_trials: 10 - 每次迭代的优化器 $ 上限： optimizer_usd_per_iter 40 （claude --max-budget-usd，由 CLI 自身强制执行） - optimizer_max_turns: 400 （慷慨；实际迭代上限是 $ 上限） - max_usd: 400 max_optimizer_usd: 400 - 门控： 显著性（paired），k_se 0.2 - 存储： git （每次迭代提交以检查过程） 捆绑的 `examples/tau2_airline/` 是 **结果** 运行此提示：适配器（包括 `run_batch`/`run_trials`/`trajectories`/`score`），RITS 垫片，可编辑种子（`seed_capability/` = `policy/` + `tools/` + `reference/data_model.py`），以及能力范围的 `optimizer/INSTRUCTIONS.md` 是由接入 / 实现并检查流程生成的。 # 可选（提供默认工作值）： materialize(cand_dir, edits) -> None # 将 edits 纯粹写入 cand_dir live(cand_dir) -> ctx (CM) # 使候选者生效以进行一次评估 run_batch(tasks, ctx, *, seed) -> ... # 实现以驱动基准测试的批量运行器（像 tau2 那样） # 而不是 run_target run_trials(tasks, ctx, *, n_trials, base_seed) # 批量快速路径：一次运行所有试验 -> {task_id: [Rollout, ...]} # （折叠 N 次评估通道；pass^k/SE 不变） trajectories(split) -> Path|None # 最后一个评估的运行器的原生跟踪目录； # 原样复制到优化器的 ./trajectories/ 其他部分 - 分割、试验、门控、pass^k、密封测试、内存和 仪表盘 - 由核心提供，不得重新实现（这使得评估诚实）。有两种方法可以实现： **A — 让你的代码代理构建它（无需 Python 代码）。** 打开你已经在仓库根目录中使用的代码代理，并告诉它遵循 `RUN.md`。它加载 `intake` 技能，询问缺少的任何内容（从不捏造需要的输入）， 写入适配器，运行 `cap-evolve check`，然后是整个循环。 [`examples/tau2_airline/PROMPT.md`](examples/tau2_airline/PROMPT.md) 是一个完整的 工作简介（也直接嵌入在上面的 [tau2-bench 示例部分](#tau2-bench-example-real)）。 填写并粘贴到你的代码代理中，并附上 *"follow RUN.md"* — intake 会询问你省略的任何内容，从不捏造需要的输入： ```text 遵循 RUN.md 运行 cap-evolve 优化我的基准测试/代理。如果基准测试尚未安装， intake/integration 步骤应克隆并安装它。这是 intake 需要的所有内容（填写每个字段；如果要 intake 询问，请留空字段）： # 1. 能力（优化的内容 - 编辑每个迭代的副本；原始内容从不触及） - 类型： <一个或多个：system-prompt | tools | mcp-tool | skill-package> # system-prompt = 一个提示/策略文本文件；tools = 代理自己的工具； # mcp-tool = 外部 MCP 服务器提供的工具（仅 docs/exposed-set 编辑）； # skill-package = 一个 Agent Skill 目录（SKILL.md + 引用 + 脚本）。可以组合，例如 [system-prompt, tools]。 - 种子： <要优化的种子工件的路径，例如 policy/policy.md | tools.json | skills/<name>/> - 注意：对于 `tools`：优化器可以编辑工具文档/描述和工具行为/代码， 以及添加/删除调用现有工具的组合工具（包装规则、循环、参数归一化）- 而不仅仅是重新措辞文档。 # 2. 基准测试/数据集（评估） - 基准测试： <名称，例如 my-bench / SWE-bench-lite / 自制套件> - 仓库： <本地路径或 Git URL> # 基准测试代码/数据存储的位置 - 安装： <如何安装它，例如 `pip install -e ../<bench>`；记录已解决的提交以确保可复制性> - 任务： <tasks.jsonl 的路径或 "adapter"> # "adapter" = adapter.tasks(split) 在代码中构建它们 - 任务格式：每个任务 = id + 输入 + 金标准/评估标准 # 每行一个 JSON 对象：{"id": ..., "input": ..., "target"/"criterion": ...} - 分割： <以下之一：> # 种子比率 -> split_seed + split_train/val/test（默认 0.5/0.25/0.25） # 显式 -> split_ids.json {"train":[...],"val":[...],"test":[...]} （例如官方分割） # 无保留拟合 -> train == val == test == 所有 id（将测试编号作为拟合指标报告 FLAGS） # 3. 运行器（被测试的代理）+ 模型 + 凭证 - 如何运行一个任务： <进程内调用 | 子进程 | HTTP 端点 | 基准测试自己的批量运行器 -> 实现 adapter.run_batch 而不是 run_target> - 运行器模型： <被测试的代理使用的模型 ID> - 凭证： <环境变量 / 仓库根目录 .env 键，例如 OPENAI_API_KEY、WATSONX_*、RITS_API_KEY - 永远不要硬编码秘密> - 自定义/OpenAI 兼容端点（vLLM、IBM RITS、网关）： <api_base + 任何自定义身份验证标头> # 通过运行器的 LLM 配置传递（大多数基准测试将额外参数转发到 litellm）； # 优先使用每个调用的配置 - 没有猴子补丁，没有基准测试分支 - 并发控制： <例如环境变量 / 最大并发设置运行器遵循> # 4. 评估标准（优化目标） - 指标： <精确匹配 | [0,1] 中的奖励 | 评分标准 | 通过/失败规则> - 来源： <基准测试自己的验证器或 adapter.py 中的 score() 函数> - 反馈： 必须是通用且金标准安全的 - 它是学习信号；永远不要泄露金标准答案 - 目标： 在验证集上最大化平均奖励 # 5. 优化器（提出编辑）+ 模型 + 凭证 - 优化器： <claude-code | codex | gemini-cli | opencode | cursor | droid | copilot | kimi | pi | antigravity | openclaw | ibm-bob | generic | mock> - 模型： <后端特定的模型 ID> - 凭证： <例如 ANTHROPIC_API_KEY 或已登录的 Claude Code 会话；ibm-bob 的 BOBSHELL_API_KEY> # 6. 预算/门控 - 算法： <hill-climb (--focus all|cyclic|hardest-first) | gepa | skillopt> - 最大迭代次数： <N - 主导成本控制> - 试验次数： <>=3 表示随机代理；仅 1 表示确定性代理> # 启用 pass^k - 最大指标调用次数： <0 = 无限制；否则在运行器评估 N 次后停止> - 最大美元： <运行器 + 优化器 + intake 的总美元上限；0 = 无限制> - 最大优化器美元： <累积优化器仅美元上限；0 = 无限制> - 每次迭代的优化器美元： <优化器 CLI 强制执行的每次迭代美元上限，例如 claude `--max-budget-usd N`> - 优化器最大回合： <传递给代理 CLI 的每次迭代工作上限，例如 claude `--max-turns N`> - 门控： <显著（k_se）| 严格 | 阈值> # 显著：仅当 Δ > k_se · SE 时接受 - k_se 是 val 增益必须清除的 SE 数量 # （例如 0.2 = 宽松，1.0 = 严格）以便噪声不会被误认为是进度 - 停滞： <在 N 个连续拒绝后停止；0 = 运行所有 max_iterations> - 存储： git # 为可检查的过程版本化每次迭代 ``` **B — 自己驱动 `cap-evolve` CLI。** ```bash python3 skills/phases/intake/scripts/run.py --base .capevolve # 搭建适配器存根 + capevolve.yaml # 1. 在 .capevolve/project/adapters/adapter.py 中实现任务/运行目标（或运行批次）/评估 # 2. 在 capevolve.yaml 中设置功能/优化器/算法/分割 cap-evolve check .capevolve/project # 硬性门控 - 必须打印 {"ok": true} cap-evolve estimate --spec .capevolve/project/capevolve.yaml # 干运行成本预览（不花费任何费用） cap-evolve run --spec .capevolve/project/capevolve.yaml --project .capevolve/project open .capevolve/run_*/dashboard.html ``` 从最近的示例开始并编辑其 `adapter.py`： | 您要优化... | 复制 | `capabilities:` | |---------------------------------------------|---------------------------------------------------|--------------------------| | 一个**提示**（零 API 证明） | [`examples/toy_calc`](examples/toy_calc) | `[system-prompt]` | | 一个**系统 + 工具**（真实代理） | [`examples/tau2_airline`](examples/tau2_airline) | `[system-prompt, tools]` | **交换优化器是一个词** 在 `capevolve.yaml` 中 - 一个运行器 （`run-optimizer`) 通过 `skills/optimizers/registry.yaml` 解析名称： ```yaml capabilities: [system-prompt, tools] # 任意：system-prompt | tools | mcp-tool | skill-package optimizer_skill: claude-code # ← 交换：codex | gemini-cli | opencode | cursor | droid | copilot | kimi | pi | antigravity | openclaw | ibm-bob | generic | mock algorithm_skill: hill-climb # hill-climb (--focus all\|cyclic\|hardest-first) | gepa | skillopt num_trials: 4 store: git # 版本控制每次迭代 ``` **扩展同样简单：** 一个新的能力、算法或优化器是一个文件夹或一个 `optimizers/registry.yaml` 行 - 请参阅 [`docs/EXTENDING.md`](docs/EXTENDING.md)。 ## 工作原理 **intake → 实现和检查 → 基线 → 算法 → 完成 → 报告** **Intake 完成整个基准测试集成 - 在花费任何预算之前。** 它 采访您（或阅读您的简介），安装基准测试，并连接 **适配器**（任务/运行目标或运行批次/评估），**轨迹**路径 （`adapter.trajectories(split)` → 运行器的原生跟踪），可选的批量 **运行试验**快速路径，和`capability_sources`（工具导入的数据模型/类型文件）。然后它创建一个**特定于能力的**优化器提示 （`optimizer/INSTRUCTIONS.md`）- 指导和可编辑的工件，仅适用于 选定的能力。缺少的必填输入将被询问，永远不会被捏造。 **实现和检查是硬性门控。** `cap-evolve check` 拒绝继续 直到每个适配器方法（和任何选定技能的抽象方法）都是真实的，并且 `score()` 是确定性的 - 因此在 stub 上不会发生任何花费。 **基线** 冻结种子化的 train/val/test 分割（写入一次；测试 **密封**）并在验证集上评估未修改的种子 - 每次迭代的候选者都必须击败它。 **每个算法迭代**（`hill-climb` / `gepa` / `skillopt`）：**诊断** 将失败的验证跟踪分成失败集群 → **优化器提出** 一个大型、 多部分的编辑 → 在验证集上评估候选者（每个试验都有自己的种子，因此 pass^k 衡量真正的方差）→ 一个**配对显著性门控** （Δ > k·SE，仅验证集）接受或拒绝 → 迭代被 git 提交并且内存 更新。 **完成** 仅一次在**密封测试集**上评估最佳候选者（运行目录强制执行密封）；**报告** 编写 `report.md` 和一个自包含的 `dashboard.html`。 ### 每次迭代优化器接收的内容（以及为什么编辑是大型且非回归的） harness 搭建了一个**特定于能力的**工作目录每次迭代，然后运行 您选择的编码代理 CLI： - **选定的能力技能** - 既作为 `./guidance/<cap>/` 又作为放置在 **原生** 在代理自己的技能目录中（例如 `.claude/skills/`、`.codex/…） 因此无头代理自动加载它们。每个都带有“您可以更改此处”的 菜单和编辑边界。 - **诊断方法** (`./guidance/diagnose/`) - 如何将失败集群成一个 反射性数据集（每个失败任务：输入、生成输出、反馈）。 - **仅当前最佳步骤的完整轨迹** (`./trajectories/`) - 运行器的逐字跟踪 它所建立的候选者，从不是种子 + 每个被拒绝的尝试。 - **支持源/数据模型** (`./guidance/sources/`) - `capability_sources` 文件，原样复制以便新的工具代码可以针对真实类型编写。 - **每个任务的先前候选者的影响** - 哪些任务 ID 每个先前编辑**破坏**（曾经通过）和**修复**，以及**当前通过的集合以保护** - 因果 反馈，以便永远不会重新引入已知的回归。 - **具有干净所有权的跨迭代文件** - `LEDGER.md`（框架所有 事实：每次迭代的结果 + 导致破坏/修复的确切任务），`JOURNAL.md` （优化器所有，整个运行的只追加交接：尝试/工作/回归/ 反驳/关注下一步），`PROCESS.md`（优化器所有可解释性，每次迭代快照 候选者），以及 `RUNMAP.md` + `prior_iterations/`（一个清单加上每个先前 迭代的 PROCESS.md 和能力差异，为了可以访问实际的先前工作）。 因为它一次看到所有的失败集群、保护集和先前的因果影响， 优化器生成**每次迭代的一个大胆的、多部分的候选者，解决每个集群而不会回归胜利** - 不是一行代码的调整。 ### 优化器可以更改的内容 **提示** 和 **工具** 同样是公平的游戏 - 选择最能修复 最多集群的内容： - **提示** ([`system-prompt`](skills/capabilities/system-prompt/SKILL.md))： 重写/合并/添加规则，添加示例，收紧输出合同 - 但 **永远不要删除需要的规则**（更改/合并/添加，不要删除）。 - **工具** ([`tools`](skills/capabilities/tools/SKILL.md))：添加/替换/包装工具， **编辑工具代码** 进行确定性强制执行，改进文档 **和返回值** （可行的错误）用于恢复，添加循环/工作流/组合工具，以及 **通过安全包装器交换** - 永远不要直接删除原始工具。代码承载工具 编辑被强调（一个模型无法跳过的工具比一个句子它可以 忘记的工具更好），但知识差距失败仍然属于提示。 > **诚实在代码中强制执行，而不是文档中。** 分割、奖励聚合、验证 > 仅显著门控（配对，`k_se` 标准误差）和测试密封都存在于 > `cap_evolve` ([`docs/HONEST_EVAL.md`](docs/HONEST_EVAL.md))。每次 > 迭代都被 git 版本控制。基础设施和能力故障通过结构化 > 的 `Rollout.error` 信号区分开来，而不是通过字符串匹配反馈文本。 ### 速度 + 可观察性 候选者的所有 N 次试验都在**一次并发传递**中运行，当适配器 实现 `run_trials(tasks, ctx, *, n_trials, base_seed)`（将 N 次顺序评估传递折叠成一次批量运行；每个试验的持久性和 pass^k/SE 保持不变）。**实时仪表盘** 首先启动并显示 intake 成本/时间/输出，每次迭代的优化器和运行器成本 + 时间，累积最佳阶梯，任务 × 迭代的通过/失败热图，git 差异每次迭代，血统树和门控决策。 ## 比较 | | cap-evolve | DSPy | GEPA | promptfoo | |---|:--:|:--:|:--:|:--:| | 优化提示 | ✅ | ✅ | ✅ | ❌ （仅评估） | | 优化工具/MCP + 技能包 | ✅ | ➖ | ➖ | ❌ | | 代码中强制执行密封测试 + 显著性门控 | ✅ | ➖ | ➖ | ➖ | | 主机和代理无关（无框架锁定） | ✅ | ❌ | ❌ | ➖ | | 从单个提示开始一个基准测试 | ✅ | ❌ | ❌ | ➖ | | git 版本控制的迭代 + 优化器内存 | ✅ | ❌ | ❌ | ❌ | | 实时成本感知仪表盘 | ✅ | ❌ | ❌ | ➖ | | 零运行时依赖 | ✅ | ❌ | ❌ | ❌ | 路线图：[`docs/ROADMAP.md`](docs/ROADMAP.md)。 ## 技能库 cap-evolve 是一个包含 **18** 个[代理技能](https://www.anthropic.com/news/skills)的库 在小型标准库核心之上。8 个每 CLI 优化器折叠成一个 `run-optimizer` 技能 + 一个每优化器的注册表；三个 hill-climb 变体折叠成一个 `hill-climb` 技能，并带有 `--focus`。 | 组件 | 技能 | |-----------|--------| | 协调 | `orchestrate` · `using-cap-evolve` （会话启动路由器） | | 阶段 | `intake` · `implement-and-check` · `baseline` · `evaluate` · `diagnose` · `gate` · `finalize` · `report` | | 能力 | `system-prompt` · `skill-package` · `tools` · `mcp-tool` | | 算法 | `hill-climb` (`--focus all\|cyclic\|hardest-first`) · `gepa` · `skillopt` | | 优化器 | `run-optimizer` + `optimizers/registry.yaml` (`claude-code`, `codex`, `gemini-cli`, `opencode`, `cursor`, `droid`, `copilot`, `kimi`, `pi`, `antigravity`, `openclaw`, `ibm-bob`, `generic`, `mock`) | Claude Code 插件：`claude --plugin-dir ./plugins/cap-evolve` 将每个技能公开为 `/cap-evolve:<skill>` 并武装诚信钩子（PreToolUse 拒绝编辑 到密封测试/金标准；Stop/SubagentStop 在 `cap-evolve check` 和门控变为绿色之前阻止完成）- 所有在**核心所有**脚本中，从不 在可编辑的技能 markdown 中。 ## 结果 实际的 [tau2-bench](https://github.com/sierra-research/tau2-bench) 航空公司运行 —— 使用 `claude-opus-4-6` 优化器和 `gpt-oss-120b` （代理和用户模拟器，通过 IBM RITS）优化航空公司**策略 + 工具**，涵盖所有 50 个航空公司任务（每个任务 10 次试验）。**指标：**平均 tau2 任务奖励，范围在 `[0,1]` 内。 | | 验证奖励（50 个任务 · 10 次试验） | 与基线相比的增幅 | |---|---|---| | **基线**（种子策略 + 工具） | **0.496** | — | | **最佳候选方案**（`cand_0013`） | **0.702** | **+0.206（约 +41% 相对增幅）** | 收益在成对显著性门槛后累积 —— 足够小的收益被视为噪声而被拒绝。接受次数：迭代 1 `+0.110`（0.496→0.606），迭代 2 `+0.054`（→0.660），迭代 9 `+0.020`（→0.680），迭代 13 `+0.022`（→0.702）；其他 11 次迭代被门槛拒绝。10 次迭代的最终评估在其密封分割上仅一次获得最佳候选方案（`cand_0009`），评分为 **0.676 pass@1**（pass^2 0.556）。 **实际变化情况。** 每次接受的迭代都会对工具进行深入的代码修改 —— 而不仅仅是提示调整。根据失败推出的参数级反馈，优化器将策略规则的文本转换为可执行的守卫，放置在现有的工具主体内：例如，迭代 1 单独转换了 5 个规则违规为代码守卫（取消/更新/行李资格检查）以及一个 `get_all_reservation_details` 循环工具；`tools.py` 从 593 行增长到 982 行，策略从 166 行增长到 212 行。详见 [`examples/tau2_airline/DEMO.md`](examples/tau2_airline/DEMO.md) 中的精选故事。 **先睹为快。** 打开已提交的完整交互式仪表盘（所有 15 次迭代，无需后端支持）——静态 UI 导出在 [`examples/tau2_airline/run_full/ui/`](examples/tau2_airline/run_full/ui/) —— 方法是运行 `cd examples/tau2_airline/run_full/ui && python3 -m http.server 8000`（然后访问 http://localhost:8000），或在 GitHub Pages / 任意静态主机上托管（KPI、评估、每次迭代的 git 差异、成本/收益面板、血统、内存）。原始数据：[`run_full/final.json`](examples/tau2_airline/run_full/final.json)。从零开始复现：[`docs/REPRODUCE_tau2.md`](docs/REPRODUCE_tau2.md)。每次迭代都是一个 git 提交。 > 注意：此示例中训练集 = 验证集 = 测试集 = 所有 50 个任务（无留出集），因此验证集 **即为**拟合指标，密封测试分数作为 **拟合指标**（引擎日志记录一个`splits_warning`）；对于留出结果，请通过`split_ids.json`固定 30/10/10 的分割。 ## 操作指南 针对特定套件 + 基准测试组合的逐步指南： | 指南 | 涵盖内容 | |---|---| | [cap-evolve with Exgentic / tau2-bench](docs/how-to/cap-evolve-with-exgentic-tau2.md) | 通过 exgentic 套件和 LiteLLM 代理优化航空公司 `policy.md` + `tools.py` | 更多指南将在后续添加。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [行为准则](CODE_OF_CONDUCT.md)。 通过 [SECURITY.md](SECURITY.md) 报告安全问题。变更记录：[CHANGELOG.md](CHANGELOG.md)。 ## 引用 ```bibtex @software{cap-evolve, title = {cap-evolve: a skills-native, host-agnostic harness for honestly optimizing AI-agent capabilities}, year = {2026}, note = {https://github.com/skillberry-ai/cap-evolve} } ``` **致谢。** `gepa` 和 `skillopt` 技能是 GEPA（arXiv:2507.19457）和 SkillOpt（arXiv:2605.23904）论文的独立实现 —— 不包含第三方代码；两个参考项目均采用 MIT 许可证。cap-evolve 还借鉴了 DSPy、tau-bench/tau2-bench 和 Agent Skills 标准中的想法。完整引用：[docs/sources.bib](docs/sources.bib)。 ## 许可证 Apache-2.0。