项目定位与核心能力

metaharness 是一个面向 AI 代理工程的 CLI 脚手架生成器，核心目标是：把"代理 harness"（代理可加载的工具集、说明、插件定义等）按可复用的模板一键落地到本地目录。仓库由两层 npm 包构成：顶层的 metaharness CLI 与底层 @ruvnet/agent-harness-generator 生成器；CLI 负责解析用户参数、读取模板目录，生成器负责把模板文件渲染并写入目标路径。

资料来源：README.md:1-80 docs/OVERVIEW.md:1-60

Hosts：目标宿主运行时

Host 表示脚手架最终要被加载到的"宿主环境"。不同宿主对插件清单、入口文件、命名约定有不同要求，metaharness 通过统一目录约定屏蔽这些差异：

• Claude Code 宿主：自 v0.1.3 起，全部 20 个模板都会附带 .claude-plugin/plugin.json，使其能被 claude -p --plugin-dir <harness> 直接加载。
• 其他宿主（如通用 Agent 运行时）通过同一份 templates/<vertical>/<template> 目录渲染，使用各自偏好的清单格式。

选择 Host 主要影响两件事：① 是否需要在脚手架根目录生成 .claude-plugin/；② 模板渲染时哪些占位变量会被启用。

资料来源：docs/USERGUIDE.md:1-120 README.md:40-120

Verticals：模板分类体系

Vertical（垂直领域）是模板的一级分类，位于 packages/create-agent-harness/templates/catalog.json 中注册。仓库默认随附 20 个模板，分布于若干 Vertical，例如 minimal、research、code、ops 等。每个模板目录内包含：

• harness.md —— 代理的行为说明与系统提示；
• .claude-plugin/plugin.json —— 宿主插件清单（v0.1.3 起强制存在）；
• 其他资源文件（脚本、配置、示例）。

catalog.json 是 CLI 在 --template <name> 解析时查找的索引，决定哪些模板名对用户可见。

资料来源：packages/create-agent-harness/templates/catalog.json:1-200 packages/create-agent-harness/src/subcommands.ts:1-150

CLI 子命令与模板选择流程

CLI 入口路径为 packages/create-agent-harness/src/bin.ts → main.ts → subcommands.ts。bin.ts 调用 main()，但当前已知存在一个回归：main() 的返回码未被 bin.ts 透传，导致所有子命令无论成功失败都退出 0；这在 CI 中会让失败命令显示为绿色。社区已通过 PR #72 为新增的 learn 子命令局部修复该问题。

子命令层面，metaharness 提供至少：生成脚手架（默认）、learn（交互式学习模板）、list（列出可用 Vertical/Template）。--template 与 --vertical 参数会触发 subcommands.ts 中的解析分支，从 catalog.json 中定位模板并交给生成器渲染。

flowchart LR
    A[bin.ts] --> B[main.ts]
    B --> C[subcommands.ts]
    C --> D{catalog.json}
    D --> E[template dir]
    E --> F[目标 harness 目录]

资料来源：packages/create-agent-harness/src/bin.ts:1-40 packages/create-agent-harness/src/main.ts:1-120 packages/create-agent-harness/src/subcommands.ts:1-200

速查对照表

资料来源：packages/create-agent-harness/templates/catalog.json:1-50 docs/OVERVIEW.md:60-120

总体架构概览

metaharness 采用三层混合架构,以 Rust 编写的安全/性能关键内核为底座,TypeScript 编写的脚手架生成器为中间层,模板目录提供可复用的脚手架资产。这种分层使核心逻辑可以同时通过 N-API 暴露给 Node CLI,通过 WASM 暴露给浏览器/边缘环境,而模板系统保持纯文件级可移植性。

flowchart TB
    A["TS 生成器 / CLI<br/>packages/create-agent-harness"] --> B["@ruvnet/agent-harness-generator"]
    A --> C["Rust 内核 crates/kernel"]
    C --> D["kernel-napi<br/>(Node 绑定)"]
    C --> E["kernel-wasm<br/>(浏览器/边缘)"]
    A --> F["templates/<br/>(20 个模板)"]
    F --> G[".claude-plugin/plugin.json"]
    A --> H["metaharness bin"]

Rust 内核(`crates/kernel`)

Rust 内核承载项目的核心逻辑,按职责拆分为多个子模块:

• lib.rs:内核入口,聚合子模块并对外暴露统一 API。 资料来源：crates/kernel/src/lib.rs:1-50
• witness.rs:见证(Witness)机制,用于记录与回放关键执行轨迹,是审计与可重放能力的基础。 资料来源：crates/kernel/src/witness.rs:1-40
• mcp.rs:Model Context Protocol 适配层,把内核能力以 MCP 协议的形式暴露给上层 Agent。 资料来源：crates/kernel/src/mcp.rs:1-60
• routing.rs:请求路由层,负责在内核内部对不同能力/工具进行调度分发。 资料来源：crates/kernel/src/routing.rs:1-50

为了让 Rust 内核在多端可用,项目维护两套 FFI 绑定:

资料来源：crates/kernel-napi/src/lib.rs:1-30、crates/kernel-wasm/src/lib.rs:1-30

TypeScript 生成器与 CLI(`packages/create-agent-harness`)

create-agent-harness 是用户直接交互的入口,负责把模板渲染、文件写入、CLI 参数解析与 Rust 内核调用串起来。bin.ts 编译后产物 dist/bin.js 暴露 metaharness 可执行命令。

社区已记录的已知问题:bin.js 丢弃了 main() 的返回值,导致所有子命令在失败时仍以退出码 0 结束,在 CI 中表现为“假绿”。 资料来源：packages/create-agent-harness/dist/bin.js(issue #73)

生成器的核心流程在 generator.ts 中实现:接收模板名 + 目标路径 → 调用 templates/<name>/ 下的资产 → 通过 napi 调用 Rust 内核进行校验/补全 → 写出脚手架目录。 资料来源：packages/create-agent-harness/src/generator.ts:1-60

模板系统(`templates/`)

模板系统是项目最轻、但用户感知最强的一层。仓库根级 package.json 通过 workspaces 把生成器与模板统一管理,使发布时的版本对齐。 资料来源：package.json:1-40

每个模板目录都是自包含的脚手架,可被 metaharness 直接实例化。从 v0.1.3 起,全部 20 个模板都附带 .claude-plugin/plugin.json,从而支持 claude -p --plugin-dir <harness> 直接加载。 资料来源：v0.1.3 发布说明

模板资产通常包含:

• CLAUDE.md / AGENTS.md:Agent 行为契约;
• 命令与技能定义;
• 钩子(hooks)与脚本;
• .claude-plugin/plugin.json:Claude Code 插件清单。

这种结构使模板既能作为 metaharness 的渲染输入,也能作为独立的 Claude Code 插件目录使用,实现“双重身份”。

三层协作流程

1. 用户在终端执行 metaharness <subcommand>,由 bin.ts 派发到 main();
2. 生成器解析参数,选定 templates/<name> 并实例化上下文;
3. 对需要内核参与的能力(如见证、MCP、路由),通过 kernel-napi 调到 crates/kernel;
4. 文件级资产(插件清单、命令、脚本)由生成器直接拷贝/渲染到目标目录;
5. 输出一个同时是 Claude Code 插件、又能被内核调用的完整 harness。

该分层让性能/安全敏感路径留在 Rust,生态/分发路径留在 TS,模板保持纯文件,从而兼顾速度、可移植性与可维护性。

概述

metaharness 是一个面向 AI Agent 工程化的"元脚手架",其核心由六组相互协作的特性组成:CLI 子命令作为外部入口,MCP 作为协议层,Router 进行命令/能力分发,Darwin 提供演化选择能力,Weight-EFT 完成权重评分,Host 适配器屏蔽不同宿主环境差异。这些特性共同支撑起"scaffold → learn → score → witness"这一闭环工作流。社区已确认 v0.1.3 起所有 20 个模板均自带 .claude-plugin/plugin.json,使这些 CLI 子命令可在任意 Claude Code 插件目录下被加载。

CLI 子命令

CLI 由 packages/create-agent-harness/src/ 下的一组命令模块构成,每个文件对应一个子命令,具备独立的参数解析、运行时上下文与退出码语义。

• mcp 子命令:由 mcp-cmd.ts 实现,负责启动或代理 Model Context Protocol 通道,使外部工具/MCP 服务器可被 harness 调用。
• score 子命令:由 score.ts 实现,执行 Weight-EFT 评分流程,返回加权后的评分结果用于 Darwin 排序。
• learn 子命令:由 learn.ts 实现,负责从 Witness 客户端拉取轨迹并落盘到 harness 知识库。
• threat-model / oia-manifest 子命令:由 threat-model.ts 与 oia-manifest.ts 实现,生成安全威胁模型清单与 OIA 清单。

社区在 Issue #73 中指出,dist/bin.js 丢弃了 main() 的返回值,任何子命令无论成功失败均退出 0,导致 CI 误判;PR #72 已对 learn 子命令做了局部修复。

MCP 协议集成

MCP(Model Context Protocol)由 mcp-cmd.ts 实现,承担协议边界职责:把 harness 内部能力(评分、演化、Host 探测)以 MCP 标准接口暴露给上层 Agent。设计上 MCP 层是唯一与外部 LLM/Agent 直接通信的薄通道,Router 收到请求后会委托给具体子命令执行,执行结果再经由 MCP 回传,从而保证协议中立性。

Router 与 Darwin 演化选择

Router 不是单一文件,而是 CLI 入口与子命令之间的分发层——根据子命令名称、参数以及当前 Host 适配器能力,把请求路由到 mcp-cmd、score、learn、threat-model、oia-manifest 等模块。

Darwin 演化选择机制由 Router 驱动、配合 score.ts 完成。其工作流为:

1. Router 拉取一组候选 harness 变体(由 learn.ts 生成的轨迹训练而成);
2. 每个候选体经 Weight-EFT 加权评分;
3. Router 按评分进行选择-淘汰-保留,形成下一代种群;
4. 选定结果写回 Witness,完成一轮"演化循环"。

Weight-EFT 权重评分

Weight-EFT(Weighted Evaluation & Fine-Tuning)由 score.ts 实现,核心是把多维度指标(正确性、安全性、Host 兼容性、OIA 合规等)按权重聚合为一个可比较的标量。评分输入包括 threat-model.ts 的威胁模型与 oia-manifest.ts 的 OIA 清单,因此 Weight-EFT 与安全/合规模块是强耦合的。评分结果既是 Darwin 选择的依据,也是 learn.ts 反向微调的特征源。

Host 适配器

Host 适配器是 metaharness 实现"一次脚手架,多平台运行"的关键,由 witness-client.ts 与 learn.ts 共同承担:

• witness-client.ts 作为远程/异构宿主(不同 Claude Code 插件目录、容器、CI Runner)的能力探测与轨迹上报客户端;
• learn.ts 在初始化阶段根据 Host 能力元数据选择合适的训练/采样策略;
• oia-manifest.ts 与 threat-model.ts 为 Host 提供声明式的安全/OIA 清单,使得 Router 在跨 Host 调度时可校验目标环境是否满足最低安全门槛。

已知限制

• 所有 CLI 子命令当前受 Issue #73 影响,退出码未正确传播,CI 中需自行检查 stdout/stderr 而非依赖 $?。
• Host 适配能力矩阵依赖于 witness-client.ts 上报的元数据,缺失上报会导致 Router 回退到默认策略,可能影响 Darwin 评分稳定性。

资料来源:packages/create-agent-harness/src/mcp-cmd.ts:1-1 packages/create-agent-harness/src/score.ts:1-1 packages/create-agent-harness/src/witness-client.ts:1-1 packages/create-agent-harness/src/learn.ts:1-1 packages/create-agent-harness/src/threat-model.ts:1-1 packages/create-agent-harness/src/oia-manifest.ts:1-1

仓库脚本布局与职责划分

metaharness 在仓库根目录的 scripts/ 下提供一组 Node.js 运维脚本，形成"预检—演练—正式发布—SBOM"的串联链路，避免在 package.json 中堆叠长 npm script，便于在 CI 中按阶段组合：

• scripts/preflight.mjs：发布前预检，预期在 release.mjs 之前执行，覆盖工作区整洁度、版本号一致性、构建产物是否生成等检查。资料来源：scripts/preflight.mjs:1-40
• scripts/release.mjs：正式的发布协调脚本，统一驱动版本号 bump、CHANGELOG 生成与 npm publish。资料来源：scripts/release.mjs:1-60
• scripts/publish-dryrun.mjs：在不打 tag、不写远端的前提下进行 npm 发布演练，用于 CI 中快速验证 manifest 与 access 设置。资料来源：scripts/publish-dryrun.mjs:1-40
• scripts/sbom.mjs：生成 SBOM（Software Bill of Materials），为下游审计与合规检查提供产物清单。资料来源：scripts/sbom.mjs:1-40

CLI 入口与已知退出码问题

packages/create-agent-harness/src/bin.ts 与 src/harness-bin.ts 共同构成 metaharness 可执行命令的入口：前者解析命令并分发，后者承载实际业务逻辑。社区已记录一个影响 CI 行为的缺陷：在 dist/bin.js（及其 TS 源）中，main() 的返回值被丢弃，因此即使子命令内部执行失败，进程退出码始终为 0。资料来源：packages/create-agent-harness/src/bin.ts:1-40

这会带来三类运维风险：

• metaharness learn 等子命令失败时仍返回 0，CI 步骤呈绿色通过；
• 其它编排脚本（如 && 链式调用）无法依赖退出码短路；
• 发布流水线的预检门控会"漏放"失败用例。

Issue #73 已跟踪该问题，PR #72 仅对新增的 learn 命令做了范围性修复，整体 CLI 仍存在同样的退出码泄漏。资料来源：community/issue-73。当前临时规避方式是外层显式 metaharness ... || exit 1，或在 CI 步骤中追加 set -e 与对输出内容的二次断言。

发布流水线工作流

下表给出从本地到远端的发布阶段、各自对应的脚本与典型检查项，便于在 CI 中复用与编排：

资料来源：scripts/preflight.mjs:1-40、scripts/release.mjs:1-60、scripts/publish-dryrun.mjs:1-40、scripts/sbom.mjs:1-40。

scripts/release.mjs 通常以 preflight.mjs 通过为前置条件，并可在末尾追加对 sbom.mjs 的调用，使 SBOM 成为发版的强制产物。

v0.1.3 发布亮点与运维影响

v0.1.3 同时升级 [email protected] 与 @ruvnet/[email protected]，核心变更在于 20/20 模板全部内嵌 .claude-plugin/plugin.json，使得任意 scaffold 产物均可通过 claude -p --plugin-dir <harness> 直接加载。资料来源：community/release-v0.1.3。

这一改动对运维侧有两点意义：

1. 模板一致性：所有脚手架都暴露同一份 Claude Code 插件清单，CI 中校验插件可用性的脚本可以统一实现，无需按模板分支；
2. 版本同步：CLI 与 generator 同步升级，发布流水线必须保证二者版本号一致；scripts/preflight.mjs 的版本一致性检查正是为此服务。

已知问题与建议

• CLI 退出码被丢弃：见上节，影响所有 metaharness 子命令，CI 务必做输出二次断言。资料来源：packages/create-agent-harness/src/bin.ts:1-40。
• 发布脚本未自描述：scripts/release.mjs 与 publish-dryrun.mjs 仅靠文件名区分，CI 配置中需显式注明调用顺序，避免预检被跳过。
• SBOM 流程尚未与发布强绑定：scripts/sbom.mjs 当前作为独立步骤存在，建议在 release.mjs 末尾自动调用，确保每次发版都附带合规产物。

Pitfall Log / 踩坑日志

项目：ruvnet/metaharness

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/ruvnet/metaharness | host_targets=openclaw, mcp_host, claude_code, claude, codex, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ruvnet/metaharness | README/documentation is current enough for a first validation pass.

3. 运行坑 · 来源证据：metaharness CLI bin.js discards main()'s exit code — all commands exit 0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：metaharness CLI bin.js discards main()'s exit code — all commands exit 0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ruvnet/metaharness/issues/73 | 来源类型 github_issue 暴露的待验证使用条件。

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ruvnet/metaharness | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ruvnet/metaharness | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ruvnet/metaharness | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ruvnet/metaharness | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ruvnet/metaharness | release_recency=unknown