# https://github.com/ruvnet/metaharness 项目说明书

生成时间：2026-07-05 23:54:23 UTC

## 目录

- [概述、Hosts 与 Verticals 速查](#page-1)
- [系统架构:Rust 内核 + TS 生成器 + 模板系统](#page-2)
- [核心特性:CLI 子命令、MCP、Router、Darwin、Weight-EFT、Host 适配器](#page-3)
- [运维、CI/CD、发布流水线与已知问题](#page-4)

<a id='page-1'></a>

## 概述、Hosts 与 Verticals 速查

### 相关页面

相关主题：[系统架构:Rust 内核 + TS 生成器 + 模板系统](#page-2), [核心特性:CLI 子命令、MCP、Router、Darwin、Weight-EFT、Host 适配器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ruvnet/metaharness/blob/main/README.md)
- [docs/USERGUIDE.md](https://github.com/ruvnet/metaharness/blob/main/docs/USERGUIDE.md)
- [docs/OVERVIEW.md](https://github.com/ruvnet/metaharness/blob/main/docs/OVERVIEW.md)
- [packages/create-agent-harness/src/bin.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/bin.ts)
- [packages/create-agent-harness/src/main.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/main.ts)
- [packages/create-agent-harness/src/subcommands.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/subcommands.ts)
- [packages/create-agent-harness/templates/catalog.json](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/templates/catalog.json)
</details>

# 概述、Hosts 与 Verticals 速查

## 项目定位与核心能力

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` 中定位模板并交给生成器渲染。

```mermaid
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]()

## 速查对照表

| 维度 | 位置 | 作用 |
| --- | --- | --- |
| Host（Claude Code 等） | 模板内 `.claude-plugin/` | 决定宿主加载方式 |
| Vertical | `templates/catalog.json` | 一级分类 |
| Template | `templates/<vertical>/<name>/` | 具体脚手架内容 |
| CLI 入口 | `src/bin.ts → main.ts → subcommands.ts` | 参数解析与模板渲染 |

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

---

<a id='page-2'></a>

## 系统架构:Rust 内核 + TS 生成器 + 模板系统

### 相关页面

相关主题：[概述、Hosts 与 Verticals 速查](#page-1), [核心特性:CLI 子命令、MCP、Router、Darwin、Weight-EFT、Host 适配器](#page-3), [运维、CI/CD、发布流水线与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/kernel/src/lib.rs](https://github.com/ruvnet/metaharness/blob/main/crates/kernel/src/lib.rs)
- [crates/kernel/src/witness.rs](https://github.com/ruvnet/metaharness/blob/main/crates/kernel/src/witness.rs)
- [crates/kernel/src/mcp.rs](https://github.com/ruvnet/metaharness/blob/main/crates/kernel/src/mcp.rs)
- [crates/kernel/src/routing.rs](https://github.com/ruvnet/metaharness/blob/main/crates/kernel/src/routing.rs)
- [crates/kernel-napi/src/lib.rs](https://github.com/ruvnet/metaharness/blob/main/crates/kernel-napi/src/lib.rs)
- [crates/kernel-wasm/src/lib.rs](https://github.com/ruvnet/metaharness/blob/main/crates/kernel-wasm/src/lib.rs)
- [packages/create-agent-harness/src/bin.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/bin.ts)
- [packages/create-agent-harness/dist/bin.js](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/dist/bin.js)
- [packages/create-agent-harness/src/generator.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/generator.ts)
- [packages/create-agent-harness/templates/...](https://github.com/ruvnet/metaharness/tree/main/packages/create-agent-harness/templates)
- [package.json](https://github.com/ruvnet/metaharness/blob/main/package.json)
</details>

# 系统架构:Rust 内核 + TS 生成器 + 模板系统

## 总体架构概览

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

```mermaid
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 绑定:

| 绑定 crate | 目标运行时 | 用途 |
|---|---|---|
| `crates/kernel-napi` | Node.js / CLI | 通过 N-API 给 TS 生成器调用 |
| `crates/kernel-wasm` | 浏览器 / 边缘 | 编译为 wasm 给 Web 端 harness 使用 |

资料来源：[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](https://github.com/ruvnet/metaharness/blob/main/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 发布说明](https://github.com/ruvnet/metaharness/releases/tag/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,模板保持纯文件,从而兼顾速度、可移植性与可维护性。

---

<a id='page-3'></a>

## 核心特性:CLI 子命令、MCP、Router、Darwin、Weight-EFT、Host 适配器

### 相关页面

相关主题：[概述、Hosts 与 Verticals 速查](#page-1), [系统架构:Rust 内核 + TS 生成器 + 模板系统](#page-2), [运维、CI/CD、发布流水线与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/create-agent-harness/src/mcp-cmd.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/mcp-cmd.ts)
- [packages/create-agent-harness/src/score.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/score.ts)
- [packages/create-agent-harness/src/witness-client.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/witness-client.ts)
- [packages/create-agent-harness/src/learn.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/learn.ts)
- [packages/create-agent-harness/src/threat-model.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/threat-model.ts)
- [packages/create-agent-harness/src/oia-manifest.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/oia-manifest.ts)
</details>

# 核心特性:CLI 子命令、MCP、Router、Darwin、Weight-EFT、Host 适配器

## 概述

`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](https://github.com/ruvnet/metaharness/issues/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 子命令 | `mcp-cmd.ts` / `learn.ts` / `score.ts` / `threat-model.ts` / `oia-manifest.ts` | 暴露外部可调用入口 |
| MCP | `mcp-cmd.ts` | 协议边界,标准化对外接口 |
| Router | CLI 入口 + 子命令调度 | 命令/能力分发与演化驱动 |
| Darwin | `score.ts` + Router | 候选评分与选择-淘汰循环 |
| Weight-EFT | `score.ts` | 多维加权评分,供 Darwin 使用 |
| Host 适配器 | `witness-client.ts` / `learn.ts` / `oia-manifest.ts` | 屏蔽宿主差异,声明能力与安全清单 |

## 已知限制

- 所有 CLI 子命令当前受 [Issue #73](https://github.com/ruvnet/metaharness/issues/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]()

---

<a id='page-4'></a>

## 运维、CI/CD、发布流水线与已知问题

### 相关页面

相关主题：[概述、Hosts 与 Verticals 速查](#page-1), [系统架构:Rust 内核 + TS 生成器 + 模板系统](#page-2), [核心特性:CLI 子命令、MCP、Router、Darwin、Weight-EFT、Host 适配器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/create-agent-harness/src/bin.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/bin.ts)
- [packages/create-agent-harness/src/harness-bin.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/harness-bin.ts)
- [scripts/preflight.mjs](https://github.com/ruvnet/metaharness/blob/main/scripts/preflight.mjs)
- [scripts/release.mjs](https://github.com/ruvnet/metaharness/blob/main/scripts/release.mjs)
- [scripts/publish-dryrun.mjs](https://github.com/ruvnet/metaharness/blob/main/scripts/publish-dryrun.mjs)
- [scripts/sbom.mjs](https://github.com/ruvnet/metaharness/blob/main/scripts/sbom.mjs)
</details>

# 运维、CI/CD、发布流水线与已知问题

## 仓库脚本布局与职责划分

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` | 工作区干净、版本号一致、构建产物齐备 | 非零退出码阻断后续阶段 |
| 演练发布 | `scripts/publish-dryrun.mjs` | 不打 tag 前提下验证 `npm publish` 配置 | 仅打印计划，不修改远端 |
| 正式发布 | `scripts/release.mjs` | 版本号 bump、写 CHANGELOG、生成 tag、推 registry | 失败需人工回滚 |
| 合规产物 | `scripts/sbom.mjs` | 输出 SBOM（CycloneDX/SPDX）供审计 | 退出码反映生成结果 |

资料来源：[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 同时升级 `metaharness@0.1.3` 与 `@ruvnet/agent-harness-generator@0.1.1`，核心变更在于 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` 末尾自动调用，确保每次发版都附带合规产物。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: ruvnet/metaharness; human_manual_source: deepwiki_human_wiki -->