meta-harness-studio

# Meta-Harness 工作室 **一次性编写 AI 编程框架。将其投射到每个工具上。然后让它从执行轨迹中自我改进。** 一个规范的 `.harness/` 成为 **Claude Code、Codex（命令行 + 桌面版）、OpenCode、Cline、Kilo Code 和 Pi** 的正确、本机配置 —— 不仅仅是指令，还有命令、子代理、钩子、MCP 服务器和权限。然后，`harness optimize` 按照 [Meta-Harness 论文](https://arxiv.org/abs/2603.28052) 的描述，关闭循环：一个可交换的代理提议者读取原始执行轨迹的存储，并提议框架编辑，在帕累托前沿进行评分。 ``` .harness/ ──► CLAUDE.md · AGENTS.md · .mcp.json · config.toml · opencode.json .clinerules/ · .kilocode/mcp.json · .pi/extensions/ · hooks · skills · … ``` --- ## 为什么存在 每个编码代理都重新发明相同的配置：这里的 `CLAUDE.md`，那里的 `AGENTS.md`，`config.toml`，`.clinerules/`，四种不同的 MCP 格式，每个工具的钩子。手动保持它们的一致性很快就会失效 —— 指令与它们引用的脚本不同步（**"规则漂移"**：一个 `CLAUDE.md` 文件仍然显示 `npm run check`，而脚本已被重命名），并且没有工具进行检查。 像 **Ruler** 和 **rulesync** 这样的工具解决了其中的一半问题：它们是从单一真实来源到 N 个工具的单向编译器。但是，正如该类别中评分最高的批评所说， *"编译确保一致性，而不是行为。"* 同步的规则并不使代理遵守，**执行结果从未反馈** 以改进规则。 Meta-Harness 工作室同时完成了这两部分： 1. **正确地投射到每个地方** —— 包括同步工具跳过的内容：生成的 **强制执行**（钩子 + 权限拒绝），五种真正不同的 **MCP 序列化**（六个工具 —— Cline 和 Kilo 共享 Roo 家族形状），以及当工具无法表达某个功能时的优雅降级。 2. **关闭循环** —— 摄取执行反馈，让代理提议者从 **原始轨迹** 中诊断并编辑框架，验证，并报告帕累托前沿。没有其他跨工具配置工具执行此操作。 --- ## 快速入门 ```bash # 从此存储库 npm install && npm run build node dist/cli.js --help # 或 `npm link` 以获取全局 `harness` # 在任何项目中 harness init # 搭建 .harness/（如果存在，则导入现有的 AGENTS.md/CLAUDE.md） harness author # 或：扫描存储库并自动编写一个可用的 .harness/（确定性） harness apply # 为每个启用的工具生成本机配置 harness verify # 审计漂移 + 过时引用 + 强制执行覆盖 harness optimize # 关闭循环（模拟提议者 —— 无令牌，无模型） ``` `harness init` 配备了一个小型评估集，因此 `optimize` 可以立即运行： ```text 优化 "acme-api" — 提议者=模拟，3 个搜索任务(s)，≤3 次迭代 v00 基线 通过 100% ctx 297 tok 0.0157s v01 候选 通过 100% ctx 175 tok 0.0137s v02 收敛 — 提议者未找到进一步的改进。 结果 ✔ 最佳变体 v01：context_tokens 297 → 175（-122 tok），pass_rate 100% → 100%（+0 pts）。 保留测试集：通过 100%（基线 100%）在 1 个任务上（提议者从未见过）。 ``` 这就是论文的标题结果 —— **在较少的令牌下保持相同的通过率** —— 在离线环境中重现。 参见 [`examples/demo-project/`](examples/demo-project/) 以获取完整的示例 —— MCP 服务器、子代理、输出样式和强制执行规则。运行 `harness -C examples/demo-project apply` 以为所有 6 个工具生成本机配置（生成的 文件被 gitignore，因此您自己生成它们）。 --- ## 规范 —— `.harness/` ``` .harness/ harness.toml # 目标、投影策略、优化器配置 AGENTS.md # 规范指令 —— 便携式主干（5 个工具中 5 个原生读取） instructions/**/AGENTS.md # 可选的嵌套每包（monorepo 最近获胜） mcp.toml # 规范 MCP 服务器（一种模式 → 6 种序列化） permissions.toml # 允许 / 拒绝 / 询问 + 沙盒意图（按工具降级） enforce.toml # "必须发生" 规则 → 钩子 + 权限拒绝（Claude Code）/ 建议其他地方 skills/<name>/SKILL.md # 代理技能标准 agents/<name>.md # 子代理规格 commands/<name>.md # 斜杠命令 / 提示模板 output-styles/<name>.md # 在支持的地方发出（今天的 Claude） history/ # 优化器的经验存储（原始轨迹）—— 默认 gitignored ``` 指令位于 **AGENTS.md** 中，因为它是事实上的标准，5 个目标中 5 个原生读取（Claude Code 通过生成的 `CLAUDE.md` → `@AGENTS.md` 适配器导入）。机器配置是 **TOML**（Codex 的原生格式，并且它干净地转换为 JSON）。我们不发明指令格式 —— 只有四个小型 TOML 文件是新增的。 --- ## 支持的工具 | 工具 | 指令 | MCP | 备注 | |------|--------------|-----|-------| | **Claude Code** | `CLAUDE.md` + `@AGENTS.md` 导入适配器 | `.mcp.json` | 最丰富的目标：真正的钩子和权限强制执行 | | **Codex** （命令行 + 桌面版） | `AGENTS.md` （原生） | `config.toml` `[mcp_servers]` | 共享 `~/.codex`；项目配置需要信任 | | **OpenCode** | `AGENTS.md` （原生） | `opencode.json` （命令作为数组） | 最大的 MCP 分歧 —— 已处理 | | **Cline** | `AGENTS.md` + `.clinerules/` | 全局存储（作为引用发出） | 命令 → 工作流；无子代理 | | **Kilo Code** | `AGENTS.md` （大写） | `.kilocode/mcp.json` | Roo+Cline 家族 | | **Pi** | `AGENTS.md` **和** `CLAUDE.md` | 生成的 TS 扩展 | 极简主义核心；MCP 是代码生成 | 运行 `harness list-targets` 以获取完整的功能矩阵，并运行 `harness doctor` 以查看哪些代理 CLI 已安装。 > **添加/删除目标是一个编辑** 至 `src/targets/registry.ts`。目标变化很快（Gemini CLI 在 2026 年中期停止；Kilo/Antigravity 分叉成 IDE+CLI），因此适配器列表是数据驱动的，而不是硬编码到引擎中。 --- ## MCP：一个定义，五种形式 MCP 是唯一一个没有共享格式的功能。一个规范的服务器在 `mcp.toml` 中： ```toml [servers.github] transport = "stdio" command = "npx" args = ["-y", "@modelcontextprotocol/server-github"] env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" } # ${ENV} 引用 — 绝不直接使用机密 ``` 被转换为每个工具的真实形状 —— Claude/Cline/Kilo JSON（`mcpServers`，但 Cline/Kilo 添加 `disabled`+`alwaysAllow`），Codex TOML（`bearer_token_env_var` 用于 HTTP），OpenCode 的数组合并 `command` + `environment` + `enabled`，以及 **为 Pi 生成 TypeScript 扩展**（它没有 MCP 配置键）。这些不能被符号链接 —— 只能被转换。 --- ## 优化器 忠实于 [论文](https://arxiv.org/abs/2603.28052)，离线友好。薄外循环，胖提议者： ``` 快照 → 提议者编辑 → 接口验证 → 泄漏审计 → 评估 → 记录 → 帕累托 ``` - **存储是资产，不是算法。** 每个变体都保留其框架快照、分数、 **原始执行轨迹** 和 `history/<id>/` 下的书面诊断。论文的决定性消融表明，原始轨迹优于摘要（50.0 vs 34.9），因此轨迹 **从不预先摘要** —— 提议者按需 grep。 - **可交换的提议者。** 默认是一个确定性的、 **无令牌的模拟提议者** （压缩冗余上下文，同时保留测试集）。传递 `--proposer "claude -p"` 以获取真正的代理提议者。 - **多目标。** `pass_rate × context_tokens × wall_clock × usd` 的帕累托前沿 —— 您可以选择操作点。 - **防护栏。** 评估前的接口验证；保留测试集提议者从未看到；每次迭代的泄漏/过拟合审计（代码空间是可检查的 —— 我们使其成为一个功能）；每次迭代的人工可审计配置差异。 ```bash harness optimize # 模拟，清除历史/ harness optimize --apply # 采用最佳变体到 .harness/ # 真实的代理提议者。无头编码代理被沙盒化，因此授予写入 + # 读取相邻历史/存储 — 否则提议者只能诊断 # 并且没有编辑持续（它收敛到无操作）： harness optimize --proposer "claude -p --dangerously-skip-permissions --add-dir ../.." --iterations 5 ``` 在 `eval/search/` 和 `eval/test/` 下定义评估任务，每个任务都有一个 `task.toml`： ```toml cmd = 'grep -q "npm run build" "$HARNESS_DIR/AGENTS.md"' expect_exit = 0 ``` `HARNESS_DIR` 指向候选人的 `.harness/`，因此任务断言针对候选人 —— 例如“构建命令是否仍然被记录”，这会阻止优化器压缩掉基本上下文。 --- ## 命令 | 命令 | 执行操作 | |---------|--------------| | `harness init [--yes]` | 搭建 `.harness/`；导入现有的 `AGENTS.md`/`CLAUDE.md`/.cursorrules | | `harness author [--force] [--proposer <cmd>] [--optimize]` | 扫描存储库并自动编写一个可用的 `.harness/`（确定性；`init --from-repo` 是别名）。 `--proposer "claude -p"` 添加一个选择加入的 LLM 传递（验证或恢复）； `--optimize` 链接循环 | | `harness apply [--dry-run]` | 验证 → 将规范投射到每个启用的工具 | | `harness verify` | 审计漂移、过时脚本引用和强制执行覆盖（CI 友好退出代码） | | `harness optimize [--proposer <cmd>] [--iterations <n>] [--apply]` | 关闭循环 | | `harness list-targets` | 跨所有目标的功能矩阵 | | `harness doctor` | 节点版本 + 已安装的代理 CLI | 全局： `-C, --cwd <dir>` 以运行在另一个目录下， `-q, --quiet`。 --- ## 使其与众不同（对比 Ruler / rulesync / ai-rules） 那些工具完成了商品化的一半 —— 将规则集中起来，分发到 N 个工具。Meta-Harness 工作室匹配并添加了另外四个它们没有的功能： 1. **封闭的执行反馈循环** —— 一个原始轨迹驱动的提议者演化框架。 2. **编译强制执行** —— `enforce.toml` 成为真正的 Claude Code 钩子 + 权限拒绝，而不仅仅是文本。 3. **合规性和覆盖率报告** —— `verify` 告诉您哪些不变量是确定性强制执行的，而哪些是建议性的，按工具划分。 4. **语义漂移检测** —— 引用的脚本与 `package.json` 进行检查，而不仅仅是字节比较。 --- ## 设计原则 - **不要抗拒标准。** AGENTS.md 是主干；普通的规则同步已经商品化。 - **接口，而不是算法。** 优化器管理文件系统存储并调用强大的编码代理。没有自定义搜索引擎需要维护。 - **诚实的降级。** 当工具无法表达某个功能（Codex 没有输出样式；Pi 没有 MCP 配置键）时，我们在警告中说明，而不是发出静默无效的内容。 - **仅生成已声明的内容。** 仅在支持的地方生成输出样式，Pi MCP 代码生成仅在存在服务器时，钩子仅来自真正的 `enforce.toml` 不变量。 --- ## 路线图（故意不在 v1 范围内） - 即时/在线优化服务（今天仅限离线批处理）。 - 更多目标（Cursor、Copilot、Windsurf）—— 每个注册表条目。 - 共同演化的模型权重（论文的未来工作）。 --- ## 致谢 优化器基于 **"Meta-Harness: End-to-End Optimization of Model Harnesses"** （Lee, Nair, Zhang, Lee, Khattab, Finn — [arXiv:2603.28052](https://arxiv.org/abs/2603.28052)）。指令主干建立在 [AGENTS.md](https://agents.md/) 的基础上。 MIT © 2026 Pragnesh ([@fugitivexyz](https://github.com/fugitivexyz))