ruflo harness-genome：构建七段式仓库就绪报告与风险告警 CI 门禁

ruflo 的 harness-genome 技能将上游 metaharness CLI 的 genome 子命令封装为一个纯只读的仓库体检工具：一次调用即可输出覆盖仓库类型、Agent 拓扑建议、风险分、MCP 攻击面、测试置信度与发布就绪度的七段式报告。读完本文，你将掌握该技能完整的参数用法与退出码语义、Phase-0 基线数据的解读方法、三类典型落地场景（预铸造评审、漂移检测、CI 门禁），以及其底层子进程桥的版本固定、硬超时与优雅降级实现原理。

技能定位：scorecard 与 genome 的分工

harness-genome 与 harness-score 技能 是姊妹技能，二者回答同一问题——“这个仓库是否准备好被 harness 化”——但输出形态不同：

• harness-score 输出 5 维数值记分卡（harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness，外加 estCostPerRunUsd 与 scaffoldReady）；
• harness-genome 输出 7 段分类/数值混合报告，覆盖 repo_type、agent_topology 建议、risk_score（0–1）、mcp_surface 攻击面、test_confidence（0–1）、publish_readiness（0–1）。

用原文档的一句话概括：“Where score is a 5-dimension numeric scorecard, genome is a 7-section categorical/numeric report.” 两者配对使用才能得到完整的就绪度视图（数值视角 + 分类视角）。技能定义见 harness-genome SKILL.md，整个插件的架构与技能清单见 ruflo-metaharness README。

输出契约：七段字段与判定通道

genome 的核心价值在于输出是机器可校验的固定形状。从源码看，genome.mjs 中的 isGenomePayload() 函数就是这份契约的运行时守卫，它逐字段断言类型：

字段	类型	含义
repo_type	string	仓库类型分类（如 node_mcp_ci）
agent_topology	string[]	推荐的 Agent 拓扑角色列表
risk_score	number	风险分，0–1，越低越好
mcp_surface	string	MCP 攻击面分类（如 remote）
test_confidence	number	测试置信度，0–1
publish_readiness	number	发布就绪度，0–1

在此基础上，上游 CLI 还会用一个判定通道（verdict channel）编码整体结论：退出码 0 表示 ready，1 表示 needs-work，2 表示 blocked。genome.mjs 的 main() 做了一个关键语义转换——needs-work 和 blocked 仍然是合法的报告，因此只要退出码属于 {0, 1, 2} 且载荷形状完整，wrapper 就将其归一化为自己的退出码 0，同时把上游结论显式保留在载荷的 verdict 与 verdictExitCode 字段中（映射逻辑见 verdictFromExitCode）。只有“既非三个合法退出码、或 JSON 形状不合法”的报告才被视为失败，以退出码 2 终止。这样 CLI 调用方和 MCP 调用方都可以安全地消费完整报告，而不必把“仓库需要整改”误读为“脚本执行失败”。

使用方法与参数

技能参数提示（argument-hint）为 [--path .] [--alert-on-risk-above 0.5] [--format table|json]。参数解析实现见 genome.mjs 的 ARGS 构造：

参数	默认值	说明
--path <dir>	.	被评估的仓库路径
--alert-on-risk-above N	无	当 risk_score > N 时以退出码 1 告警；N 必须是有限数字，否则退出码 2
--format table|json	json	输出形态：结构化 JSON（默认）或 Markdown 表格

直接在脚本层面调用（不经过 Agent 技能）的方式：

# 默认：评估当前目录，输出 JSON
node plugins/ruflo-metaharness/scripts/genome.mjs

# CI 门禁用法：风险分超过 0.5 即失败
node plugins/ruflo-metaharness/scripts/genome.mjs --path <dir> --alert-on-risk-above 0.5 --format json

wrapper 的最终退出码语义（见 genome.mjs 头部注释）：

退出码	含义
0	有效报告（包含 needs-work / blocked 结论）
1	--alert-on-risk-above 阈值被击穿（告警真正触发时）
2	配置错误或 genome 调用失败（无有效报告）

启用告警时，载荷中会额外附带一个 alert 对象，含 threshold、triggered 与人类可读的 reason（如 risk_score 0.27 ≤ 0.5 — OK），便于日志审计。--format 非 json 时，输出渲染 会生成一张七段 Markdown 表格，附 verdict、耗时（durationMs）与告警结论。

算法流程：五步流水线

原文档描述的算法为：

1. 子进程调用 metaharness genome <path> --json，60 秒硬超时；
2. 解析 { repo_type, agent_topology[], risk_score, mcp_surface, test_confidence, publish_readiness } 形状；
3. 保留上游的 verdict 为 verdict 与 verdictExitCode（上游 1 = needs-work，2 = blocked，均为合法报告）；
4. 若提供 --alert-on-risk-above N，当 risk_score > N 时退出 1；
5. 输出 JSON（默认）或 Markdown。

从源码实现看，第 1 步的“子进程调用”有一个值得注意的演进：早期文档形态是 npx metaharness genome <path> --json，而当前实现已经不再走 npx。_harness.mjs 的注释明确说明这是取代了“iter-27 的 npx-with-@latest-dist-tag 路径”，解决两个问题：一是安全——@latest 意味着上游一次被投毒的发布会在下次技能调用时直接在用户机器上执行任意代码；二是性能——@latest 每次都强制一次 npm registry 元数据检查。当前解析策略（resolveMetaharnessBins）为两级：

1. 本地已装副本：从插件目录和 $CWD 向上遍历 node_modules，只要满足固定版本范围（~0.3.0 的 tilde 区间，patch 级更新才接受）就直接使用，零成本；
2. 一次性版本化缓存：首次缺失时执行一次 npm install --prefix ~/.ruflo/metaharness-cache-0.3.0，之后每次调用都是本地 node <绝对路径> 直接 spawn，零网络往返。缓存目录名带 pin 版本号，升级 pin 会自动使旧缓存失效。

二进制入口不硬编码，而是从已解析包内的 package.json bin map 动态读取（readBinMap），上游在 pin 区间内调整布局不会悄悄打断调用。60 秒硬超时常量定义在 DEFAULT_TIMEOUT_MS。

Phase-0 基线：ruflo 对自身的首次体检

原文档记录了 2026-06-16 对 ruflo 仓库自身的实测基线，这也是 ADR-150 Phase-0 测量尖峰（measurement spike）的产物：

{
  "repo_type": "node_mcp_ci",
  "agent_topology": ["maintainer", "tester", "security", "release"],
  "risk_score": 0.27,
  "mcp_surface": "remote",
  "test_confidence": 0.8,
  "publish_readiness": 0.9
}

解读（原文档给出的语义）：risk_score: 0.27 属于低风险（好）；publish_readiness: 0.9 处于高位；mcp_surface: "remote" 反映了 ruflo 的 MCP 服务器是托管（hosted）而非随包捆绑的。repo_type: node_mcp_ci 则把它归类为一个带 CI 的 Node + MCP 仓库，agent_topology 给出维持者、测试者、安全、发布四个推荐 Agent 角色。这份基线在 ADR-150 的实现笔记 与 插件 README 的 Phase-0 小节 中均有对应记录，可作为后续快照 diff 的对照锚点。

三个落地场景

原文档“When to use”一节给出三类用法，均可直接复制执行：

1. 预铸造评审（Pre-mint review）：在“从这个仓库脚手架一个自定义 harness 之前，该不该做？”的问题上，genome 给出分类式（categorical）回答，而不是一个需要人为解读阈值的裸分数。
2. 漂移检测（Drift detection）：随时间累积 genome 快照，用 cost-diff 风格的工具做 diff，观察 agent_topology 推荐何时偏离了有意为之的架构选择。
3. CI 门禁：--alert-on-risk-above 0.5 让仓库风险画像越过阈值时构建直接失败。由于告警语义已被封装为退出码 1，接入 CI 无需额外解析 JSON。

优雅降级：ADR-150 约束的体现

ruflo-metaharness 插件 整体遵循 ADR-150 的承重架构约束——“移除所有 MetaHarness 包后 ruflo 依然可用”。其中规则 #3（优雅降级）在 genome 上的体现是：当 metaharness 包无法解析或安装（离线、registry 不可达等）时，runMetaharness() 返回 degraded: true, reason: 'metaharness-not-available' 的降级结果，genome.mjs 检测到后调用 emitDegradedJsonAndExit()——它由 _invoke.mjs 的 makeDegradedEmitter 工厂构建——输出如下结构化载荷后以退出码 0 结束：

{
  "degraded": true,
  "reason": "metaharness-not-available",
  "hint": "Install with `npm i -D metaharness@~0.3.0` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install."
}

注意降级载荷中的 hint 给出了正确的固定版本安装指引（~0.3.0 tilde 区间），这与 _harness.mjs 中 METAHARNESS_PIN_VERSION 同源。降级原因的区分也有讲究：_invoke.mjs 的 classifyDegraded 把“被超时杀死（exitCode 为 null）”归为 *-timeout，把“包不可用”（stderr 命中 MODULE_NOT_FOUND / ENOTFOUND / getaddrinfo / npm ERR 等特征正则）归为 *-not-available，两种运维信号互不混淆。

这条契约不是口头承诺，而是有测试锁定的：test-graceful-degradation.mjs 把 npm registry 指向一个不可解析的域名，再逐个调用 score / genome / mcp-scan / threat-model / oia-audit 等技能，断言每个都必须退出 0 且输出中出现 "degraded": true。该脚本同时暴露了两个测试接缝环境变量——RUFLO_METAHARNESS_CACHE_BASE（把缓存根目录指向空临时目录）与 RUFLO_METAHARNESS_SKIP_LOCAL=1（禁用本地 node_modules 解析）——确保在已有缓存的开发机上演练依然有效，不会变成空转测试。

与相邻技能的配合

原文档“Pairs with”一节列出的三个相邻技能，与 genome 构成互补的就绪度工具链：

• harness-score —— 数值型就绪度记分卡（genome 的分类视角之补）；
• harness-mcp-scan —— 静态 MCP 安全发现（纯只读、不做 dispatch），关注 .mcp/servers.json 等配置面的具体风险点；
• harness-threat-model —— 企业评审级威胁模型（clean/low/medium/high + findings）。

三者命令形态与 genome 一致（--path / --format table|json + 各自的告警标志），完整命令参考见 ruflo-metaharness 命令文档。

小结

harness-genome 的设计可以归纳为四条工程决策：固定形状的七段输出契约（isGenomePayload 类型守卫）、把上游非零退出码当作数据而非错误（verdict 通道归一化）、把风险告警下沉为退出码（CI 即插即用）、以及版本固定 + 版本化缓存 + 优雅降级共同构成的可选依赖边界（ADR-150）。它既是 ruflo 对自身仓库做持续体检的基线工具（0.27 风险分 / 0.9 发布就绪度的 Phase-0 快照），也是评估任意候选仓库“是否值得 harness 化”的第一道闸门。