MetaHarness 是一个 AI Agent Harness 生成器：一条npx命令，就能为你的项目铸造一个带品牌、带记忆、带治理策略的专属 Agent Harness。而它最独特的能力，是同一个 Harness 可以同时适配 10 个不同的 AI Agent 宿主（host）——无论团队用 Claude Code、OpenAI Codex、GitHub Copilot，还是把 Agent 放进 GitHub Actions 自动流水线，都不需要重写任何代码。

一、MetaHarness 是什么？为什么强调"宿主适配"

可以把 MetaHarness 理解为AI Agent 框架的工厂：

• 输入：一个 GitHub 仓库地址，或一张白纸（自定义模板）
• 输出：一个可直接npm publish的 Harness 压缩包，包含专属npx <你的名字>CLI、本地 MCP Server、项目级记忆、技能（Skills）和见证签名（witness-signed）的发布凭证

关键在于"宿主"（host）这一层。不同的 Agent 宿主对配置的期望完全不同：

• Claude Code 读 JSON 的.claude/settings.json和 hooks
• Codex 读 TOML 格式的~/.codex/config.toml
• pi.dev 干脆拒绝 MCP，只用 TypeScript 扩展
• Copilot 则需要 VSCode 的.vscode/mcp.json

MetaHarness 通过 宿主适配器架构（见 ADR-004）解决了这个问题：内核定义统一契约，每个宿主对应一个独立的小适配器包，生成时自动为所选宿主输出原生配置文件。你选几个宿主，它就生成几套配置，内容完全一致。

二、十大宿主适配完整清单

官方宿主目录定义在 packages/create-agent-harness/src/index.ts 的HOSTS常量中，共 10 个。完整清单如下：

每个宿主都有独立的适配器包与 README，源码在packages/下：

• Claude Code：packages/host-claude-code/
• Codex：packages/host-codex/
• Copilot：packages/host-copilot/
• GitHub Actions：packages/host-github-actions/
• Prime Agent：packages/host-prime-agent/
• 其余：packages/host-pi-dev/ · packages/host-hermes/ · packages/host-openclaw/ · packages/host-rvm/ · packages/host-opencode/

三、重点宿主的适配细节

1️⃣ Claude Code：参考宿主，能力面最全

作为第一个实现的参考适配器，它输出三层作用域中的项目级.claude/settings.json（可提交进仓库共享），并生成claude mcp add注册命令。独有的原生 hooks 系统支持PreToolUse/PostToolUse等生命周期事件，配合Bash(rm *)这类匹配器实现工具调用拦截。技能、斜杠命令、子 Agent 分别写入.claude/skills/、.claude/commands/、.claude/agents/约定目录，宿主自动发现。

2️⃣ OpenAI Codex：TOML 配置 + 两个已知坑

Codex 的 MCP 注册走[mcp_servers.<name>]TOML 表（不是 JSON）。适配时需注意两点：一是项目级.codex/config.toml只有在项目被标记为trusted后才会生效；二是 Codex 没有原生 hooks，Harness 的生命周期事件通过 MCP 工具调用或bin/包装器的内核侧钩子来近似，保证与 Claude Code 上行为一致。

3️⃣ GitHub Copilot：VSCode 工作区内的 MCP

Copilot 适配器生成.vscode/mcp.json，同时输出新版servers与旧版mcpServers两种键以保证向前向后兼容。约束是 VSCode 1.99+ 且需要有效订阅；另外 VSCode 有工作区信任门（第一次打开需信任一次），适配器会附带install.md安装手册引导完成这一步。

4️⃣ GitHub Actions：把 Harness 变成 CI 机器人

这是质变型的宿主——没有人在键盘前。适配器输出触发式 workflow、可复用复合 action 和接线手册，并将 ADR-022 的默认拒绝策略映射到 workflow 的permissions:块：默认只给contents: read，仅按 Harness 策略 allow-list 授予最小写权限（如create-pr→contents: write）。适合"打标签自动发版""评论触发 triage"这类无人值守场景。

四、多宿主一次生成：一条命令覆盖全团队

MetaHarness 支持多宿主 Harness：重复传--host（或逗号分隔）即可。官方 multi-host 示例 的用法：

npx metaharness ops-demo \ --template vertical:devops \ --host claude-code \ --host codex

生成的目录里会同时出现.claude/settings.json与.codex/config.toml，Agent 与记忆内容完全一致，.harness/manifest.json会记录hosts: ["claude-code", "codex"]。团队里有人用 Claude Code、有人用 Codex，跑同一个 Harness，记忆跨宿主共享。

不确定选什么模板和宿主时，运行向导即可：

npx metaharness --wizard

已有仓库则走 Repo → Harness 推荐流：Studio 会做只读分析（不执行仓库代码），按语言、CI 配置、MCP 信号等打分并给出推荐方案：

五、生成后如何验证与打磨

每个宿主都会跑同一套契约测试与 smoke 检查；仓库里 examples/host-tour/ 提供了"一次遍历全部宿主"的可运行演示，全部返回HEALTHY才算通过。

生成 Harness 之后，日常用内置的harnessCLI 体检：

harness doctor # 脚手架冒烟检查 harness validate # 跑全部发布门禁 harness score # 0-100 评分 + 徽章 harness verify # 校验 witness 签名，防篡改

Studio 的 Verify 页面也做同类检查：上传生成的.zip，在浏览器本地完成结构、内核依赖、宿主接线、MCP 策略、密钥读取等校验，全程不上传任何数据：

六、延伸：单独生成技能、Agent 或命令

除了整包 Harness，Studio 还支持只铸造单个制品——一个技能（SKILL.md 文件夹）、一个 Agent 定义或一条斜杠命令，从精选目录选起点或自己撰写，直接预览并打包下载：

七、相关资源

• 宿主集成模型设计文档：docs/adrs/ADR-004-host-integration-model.md
• GitHub Actions 宿主决策记录：docs/adrs/ADR-033-host-github-actions.md
• 多宿主示例（Claude Code + Codex 双宿主）：examples/multi-host/
• 全宿主轮测脚本：examples/host-tour/
• 大白话用户指南：docs/USERGUIDE.md

一句话总结：MetaHarness 让"选宿主"从架构决策降级成勾选框——10 个宿主、一套内核、共享记忆与治理策略，生成时自动输出各宿主的原生配置，验证时走同一套契约测试。写一次 Harness，全团队的 Agent 环境直接可用。