ruflo metaharness-architect Agent：ADR-150 四不变量约束下的 MetaHarness 集成架构与子进程桥设计

ruflo metaharness-architect Agent：ADR-150 四不变量约束下的 MetaHarness 集成架构与子进程桥设计

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

本文以 ruflo 仓库中的 Agent 定义文件 metaharness-architect.md 为主体，拆解metaharness-architect这个架构师 Agent 如何通过 ADR-150 的四条 load-bearing 不变量、6 个 skill 子命令和唯一的子进程桥_harness.mjs，把上游@metaharness/*生态的能力（score / genome / mint / mcp-scan / threat-model）暴露到 ruflo 的 UX 中，同时保证 ruflo 在任何时刻都保持独立可运行。读完后你将掌握一套完整的“可选依赖集成”工程模式：固定版本子进程调用、优雅降级参考实现、CI 门禁验证，以及破坏约束时的 ADR 评审流程。

一、metaharness-architect：ruflo 中的 MetaHarness 集成架构师

metaharness-architect.md 是 ruflo-metaharness 插件下的一个 Agent 提示词文件，其 frontmatter 声明了基础元数据：

--- name: metaharness-architect description: MetaHarness integration architect for ruflo. Surfaces score/genome/mint/mcp-scan/threat-model upstream capabilities via skills; enforces ADR-150 architectural constraint (MetaHarness as removable augmentation, never required runtime dep); coordinates Phase 1 MVP rollout model: haiku ---

该 Agent 的职责在文件开头即被明确定义：通过 ruflo 的 UX 暴露@metaharness/*生态的能力，同时让 ruflo 在任何时候都保持独立可运行（expose the @metaharness/* ecosystem's capabilities through ruflo's UX while keeping ruflo independently operational at all times）。它不是一个执行型 Agent，而是一个承担架构守护职责的角色——其提示词中固化的核心内容包括：

1. ADR-150 四条不变量（load-bearing，即“承重墙”级约束）；
2. 6 个 skill 的职责与调用时机表；
3. subprocess-only 工具契约（只允许子进程调用上游二进制，禁止库级 import）；
4. Phase 0–3 的推进跟踪器。

理解这个 Agent 的关键，在于理解它守护的那条架构红线：MetaHarness 只能增强 ruflo，绝不能成为 ruflo 的必需运行时依赖。下面逐条展开。

二、ADR-150 的 four 条 load-bearing 不变量

Agent 文件将 ADR-150 的四条约束列为“承重”条款，任何 PR 只要破坏其中任意一条，即被视为 breaking change，必须单独撰写一个新的 ADR 来取代该约束。四条不变量如下：

这四条规则出自 ADR-150 决策文档的“Architectural Constraint (load-bearing invariant)”一节，其核心表述是：

MetaHarness may augment ruflo. MetaHarness must never become a required runtime dependency for core orchestration, memory, routing, MCP dispatch, agent execution, or federation.（MetaHarness 只能增强 ruflo，绝不能成为核心编排、记忆、路由、MCP 分发、Agent 执行或联邦功能的必需运行时依赖。）

ADR-150 还有一句被写进“API surface contract”的判据句："Ruflo remains operational if every MetaHarness package is removed."（如果移除每一个 MetaHarness 包，ruflo 依然保持运行。）这句话现在就是架构契约本身。

2.1 CI 层的强制验证：no-metaharness-smoke

不变量 #4 不是口头承诺，而是由 no-metaharness-smoke.yml 工作流落地执行。该工作流的职责在文件头部注释中写明：

• 用--no-optional（或等效手段）安装 ruflo，使所有@metaharness/*与metaharness包都被排除；
• 随后运行scripts/smoke-all-plugins.mjs，断言 ruflo 的整个插件编队仍通过结构化契约；
• 若该 job 失败，说明某个 MetaHarness 包被意外提升成了硬运行时要求——修复方式只有二选一：让新代码路径优雅降级，或撰写一个新 ADR 取代该约束。

具体地，工作流包含两类检查（见 no-metaharness-smoke.yml）：

1. 静态检查：扫描根package.json、ruflo/package.json、v3/@claude-flow/cli/package.json以及所有plugins/*/package.json，凡在dependencies中匹配metaharness或@metaharness/*的条目都会触发ADR-150 architectural constraint rule #2 violated并 exit 1；
2. 运行时演练（drill）：将每个 skill 指向一个不可解析的 npm registry，断言其输出结构化降级载荷（graceful degradation），而不是崩溃。

配套的 metaharness-ci.yml 则负责“有 MetaHarness 在场”的一侧：score / mcp-scan / router 兼容性等正向契约。两条工作流一正一反，共同锁死可选依赖的边界。

三、Agent 暴露的 6 个 Skill：职责与调用时机

Agent 文件给出的 skill 清单如下（该表是 Agent 的“知识基线”，每个 skill 对应一个SKILL.md与一个脚本）：

下面结合仓库中的脚本与命令文档补充各 skill 的实战细节。

3.1 harness-score：5 维记分卡

harness-score 的 SKILL.md 说明它把上游metaharness scoreCLI 包装为 ruflo skill：子进程调用（单发、60s 硬超时），解析形如{ harnessFit, compileConfidence, taskCoverage, toolSafety, memoryUsefulness, estCostPerRunUsd, recommendedMode, archetype, template, scaffoldReady, hardConstraints }的 JSON，输出 JSON（默认）或 markdown 表格。

对应的实现 scripts/score.mjs 支持以下参数与退出码（score.mjs#L8-L17）：

node scripts/score.mjs # 当前目录 node scripts/score.mjs --path <dir> # 指定目录 node scripts/score.mjs --alert-on-fit-below 70 # harnessFit < 70 时 exit 1 node scripts/score.mjs --format json # EXIT CODES: 0 评分成功（或降级）/ 1 触发 alert 阈值 / 2 配置错误或评分失败

--alert-on-fit-below N的语义在 score.mjs#L45-L57 中实现：阈值必须是有限数字（否则 exit 2），命中时输出alert.triggered: true与原因文本，最后process.exit(1)。这使得该 skill 可以直接充当 CI 回归门禁——ADR-150 的决策中正是把npx metaharness score . --json（断言 exitCode === 0）加进了 PR CI。ruflo 自身 2026-06-16 的 Phase-0 基线为：harnessFit 82、compileConfidence 100、taskCoverage 79、toolSafety 100、memoryUsefulness 40（最弱维度）、estCostPerRunUsd 0.048、archetypetypescript-sdk-harness、templatevertical:coding、scaffoldReady true。

3.2 harness-genome：7 节分类报告

harness-genome 输出 7 节仓库就绪度报告（repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness 等）。命令文档指出它与 harness-score 互补——score 是数值，genome 是分类，二者配对构成完整的就绪度视图；needs-work与blocked都是合法的报告结论，只有报告本身非法/缺失才算致命错误。其用途之一是漂移检测：随时间对 genome 做快照并 diff，可以发现 agent_topology 的偏移。ruflo 自身的基线为 repo_typenode_mcp_ci、risk_score 0.27（低）、publish_readiness 0.9。

3.3 harness-mcp-scan 与 harness-threat-model：静态安全面

harness mcp-scan是对.mcp/servers.json与.harness/claims.json的纯读静态安全扫描，按 low/medium/high 分级，--fail-on默认high（可收紧到medium甚至low），默认不派发任何 MCP 调用；harness-threat-model则输出企业评审级威胁模型，返回worst严重度与分类的findings[]，输出适合直接交给 security/infosec 团队。两者配对使用：mcp-scan 给发现项，threat-model 给分类归因。

3.4 harness-oia-audit：复合周审计 worker

harness-oia-audit是 Phase-2 引入（iter 7 提前）的复合 worker：把 oia-manifest + threat-model + mcp-scan 打包为一条带时间戳的审计记录，持久化到metaharness-audit记忆命名空间；--alert-on-worst high在复合最严重度达到 high 时 exit 1，--dry-run跳过记忆持久化。从源码结构看，oia-audit.mjs 使用_harness.mjs的异步变体（runMetaharnessAsync/runHarnessAsync）把 5 个子进程调用并行化，把最坏墙钟时间从 5×TIMEOUT 压到 1×TIMEOUT，并在输出中附带timing.{wallMs, sumComponentMs, parallelSpeedup}字段防止“静默串行化”回归。配合周级 cron（每周日 04:17 UTC），审计漂移可以靠记忆 diff 持续跟踪。

3.5 harness-mint：唯一可写的 skill

harness-mint 的 SKILL.md 明确它是插件中唯一具备写能力的 skill，其余全部纯读。其安全设计（load-bearing）有三条：

1. 默认 dry-run：不带--confirm时只打印将要执行的动作并 exit 0，不触碰磁盘；
2. 拒绝项目根：--target若解析到当前工作目录或其内部任何路径，直接以 exit 2 报错；目标必须是调用仓库外部的绝对路径（默认新建/tmp/ruflo-mint-<ts>-<name>/）；
3. 拒绝已存在目标：绝不覆盖，脚手架只能落入不存在的目录。

模板覆盖minimal+ 19 个垂直域（vertical:coding、vertical:devops、vertical:legal、vertical:trading等），宿主覆盖claude-code、codex、hermes、opencode、github-actions等。ADR-150 的沙箱化约束还特别强调：harness from-repo <url>（可克隆任意 Git URL）永远不暴露给 Agent 调用，from-repo是刻意保留的 human-in-the-loop 步骤。

补充说明：Agent 文件记录的是 Phase 1 核心的 6 个 skill；插件 README（plugins/ruflo-metaharness/README.md）显示插件后续又扩展到十余个 skill（similarity、evolve、drift-from-history、security-bench、learn、gepa 等），但其底层全部仍走同一条_harness.mjs子进程桥，约束体系不变。

四、Subprocess-Only 工具契约：为什么禁止库 import

Agent 文件的 “Tools” 一节给出四条契约，这四条是整个集成设计的骨架：

1. 所有 skill 只 shell out 到固定版本的metaharness/harness二进制（metaharness@~0.3.0，本地安装或一次性版本化缓存——永不@latest），统一经由_harness.mjs共享助手；
2. 每个子进程 60s 硬超时；
3. 输出被捕获并解析，强制--json标志（除非脚本显式退出 JSON 模式）；
4. 除 neural-router.ts 中的 optional-router 路径外，不出现任何@metaharness/*import 语句。

第 4 条值得单独强调：ADR-150 的“Quote architecture invariant”一节指出，ruflo 非测试源码中唯一静态（动态）导入@metaharness/*包的文件是v3/@claude-flow/cli/src/ruvector/neural-router.ts（导入@metaharness/router，且受三重门控：环境变量 + 制品 + import 成功），其余全部代码只通过_harness.mjs子进程桥触达 MetaHarness。之所以在插件侧选择子进程而非库导入，ADR-150 的“Neutral / accepted trade-offs”给出了解释：子进程每次约 200ms 冷启动开销，对不在热路径上的 MCP 工具可接受；而路由路径（亚毫秒延迟需求）保持库导入不变。

4.1_harness.mjs的固定版本解析链

_harness.mjs 是该 Agent 不变量 #3 的参考实现，其固定版本策略在 第 58–59 行 声明：

const METAHARNESS_PKG = 'metaharness'; const METAHARNESS_PIN_VERSION = '~0.3.0'; // 波浪号固定（仅允许补丁更新），NEVER @latest

文件头部注释（第 21–40 行）交代了为什么必须固定版本：此前实现使用npx -y+@latestdist-tag，存在两个问题——安全（HIGH）：@latest意味着被入侵的上游发布会在下次 skill 调用时于用户机器上执行任意代码；性能：@latest每次调用都要做 npm registry 元数据检查。现行解析链为：

resolveMetaharnessBins() ├─ (a) findLocalPackageDir：向上遍历 node_modules，找满足 pin 的已安装副本（零成本） └─ (b) 未命中 → ensureCachedInstall：一次性安装到 ~/.ruflo/metaharness-cache-<pin> 此后每次调用都是 `node <bin绝对路径> spawn`，零网络

两个二进制（metaharness与harness，后者随同一metaharness包发布）的入口路径从包的package.jsonbin map 动态读取（readBinMap），而非硬编码——这样上游在固定范围内调整布局也不会悄悄弄坏集成。

对外 API 为四个（第 223–239 行）：

runMetaharness(args, opts) // 同步调用 metaharness 二进制 runHarness(args, opts) // 同步调用 harness 二进制 runMetaharnessAsync(args, opts) // 异步变体（供 oia-audit 并行化） runHarnessAsync(args, opts)

返回结构统一为{ stdout, stderr, exitCode, json|null, durationMs, degraded, reason? }：--json标志在opts.json !== false时自动追加；spawnSync的timeout参数默认 60_000ms；被超时杀死的子进程报告reason: 'metaharness-timeout'。同步主路径 execBin 还支持cwd重定向（mint.mjs 需要把子进程工作目录指到目标目录）与环境变量透传。

除了调用桥，_harness.mjs还是该插件家族的共享契约层：SEVERITY_RANK/rankSeverity()（第 261–272 行）统一了 oia-audit、audit-trend、mcp-scan 三个脚本的严重度排名（clean/info→0，low→1，medium/warn→2，high/error→3，critical→4，未知字符串安全地返回 0 而非 undefined，消除 NaN 比较隐患）；parseMcpScanText()（第 292–319 行）把上游harness mcp-scan即便在--json下仍输出的纯文本解析成结构化 findings，兼容新旧版本的标签格式（[LOW]与补齐空格的[LOW ]）。

五、优雅降级：emitDegradedJsonAndExit()参考实现

不变量 #3 的参考实现是 第 326 行 的降级发射器：

// Exit 0 — ADR-150 architectural constraint says ruflo continues to // function when MetaHarness is absent. Skills emit a structured // degraded payload rather than failing. export const emitDegradedJsonAndExit = makeDegradedEmitter(METAHARNESS_PKG, METAHARNESS_PIN_VERSION);

以 harness-score 为例（score.mjs#L32-L37），runMetaharness返回degraded: true时，脚本调用emitDegradedJsonAndExit(r.reason)并立即返回。当metaharness未安装且npx无法拉取（离线、无网络、registry 不可达）时，输出形如：

{ "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." }

并 exit 0。这正是插件 README 强调的语义：graceful 路径是默认行为，不是特例（the graceful path is the default behavior, not a special case）。退出码语义全插件统一：0 = 成功或降级；1 = 业务告警阈值被触发（如--alert-on-fit-below）；2 = 配置错误或上游评分失败。这套约定让 CI 可以精确区分“集成缺失”（应容忍）与“门禁未过”（应失败）。

六、Phase 跟踪器与当前推进状态

Agent 文件内嵌了四阶段推进跟踪器，它是理解整个集成节奏的索引：

从 ADR-150 的实现注记可以读出各阶段在仓库中的落点：Phase 1 交付了plugins/ruflo-metaharness/插件本体、npx ruflo metaharness <subcommand>顶层分发器（metaharness.ts）、三条 CI 工作流（metaharness-ci / no-metaharness-smoke / 兼容性 tripwire 脚本），并把metaharness@~0.3.0以波浪号固定写入@claude-flow/cli与ruflo两处的optionalDependencies；Phase 2 交付了npx ruflo eject（默认 dry-run、拒绝仓库内目标与覆盖已存在目标）、插件注册表中的type: 'harness'、oia-audit复合 worker 及其周级 cron，以及SelfEvolvingRouter的并行记录/分析链路（CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1门控，未设置时零开销）。Phase 3 的“Harness Intelligence Layer”（基因组相似度检索、harness 推荐引擎、舰队级架构漂移检测等）在 ADR-150 中仅为 scope 声明，且被要求同样满足四条不变量。

Phase 0 的完整基线（插件 README 中的 JSON）值得存档：

{ "harnessFit": 82, "compileConfidence": 100, "taskCoverage": 79, "toolSafety": 100, "memoryUsefulness": 40, "estCostPerRunUsd": 0.048, "recommendedMode": "CLI + MCP", "archetype": "typescript-sdk-harness", "template": "vertical:coding", "scaffoldReady": true, "risk_score": 0.27, "publish_readiness": 0.9 }

其中memoryUsefulness: 40是最弱维度，被 SKILL.md 明确标注为“未来 AgentDB 记忆工作的先行指标”。

七、实战视角：触碰 MetaHarness 集成路径的 PR 如何过审

把 Agent 文件的不变量、_harness.mjs契约与 CI 工作流串起来，可以提炼出一份可操作的评审清单——这正是 metaharness-architect 这个角色在 code review 中的工作流：

1. 依赖侧：新增的@metaharness/*包是否只落在optionalDependencies？是否同步了 package.json 与v3/@claude-flow/cli/package.json两处的 pin，且是波浪号范围而非@latest/ caret？（no-metaharness-smoke.yml的静态检查会逐文件扫描拦截。）
2. 导入侧：新代码是否引入了import '@metaharness/*'？若非neural-router.ts的三重门控路径，一律打回；插件侧能力一律走_harness.mjs桥。
3. 降级侧：新脚本是否在degraded: true时调用emitDegradedJsonAndExit并 exit 0？退出码语义（0/1/2）是否与家族一致？
4. 边界侧：mint 是否仍拒绝项目根写入、仍默认 dry-run？from-repo是否依然未被包装成 MCP 工具？
5. 门禁侧：是否更新了smoke.sh的结构化断言与metaharness-ci.yml/no-metaharness-smoke.yml的演练范围？

任何一项答案为“否”，按 Agent 文件的裁定——该 PR 是 breaking change，需要自己的 ADR。

参考文件

• Agent 定义（本文主体）：plugins/ruflo-metaharness/agents/metaharness-architect.md
• 架构决策：ADR-150
• 子进程桥参考实现：plugins/ruflo-metaharness/scripts/_harness.mjs
• skill 实现示例：score.mjs、scripts 目录
• 命令参考：plugins/ruflo-metaharness/commands/ruflo-metaharness.md
• skill 文档：harness-score、harness-mint、harness-genome、harness-mcp-scan、harness-threat-model、harness-oia-audit
• CI 门禁：.github/workflows/no-metaharness-smoke.yml、.github/workflows/metaharness-ci.yml
• CLI 顶层分发器：v3/@claude-flow/cli/src/commands/metaharness.ts
• 插件总览：plugins/ruflo-metaharness/README.md

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo