ruflo metaharness-architect AgentADR-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-architectruflo 中的 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/* ecosystems capabilities through ruflos UX while keeping ruflo independently operational at all times。它不是一个执行型 Agent而是一个承担架构守护职责的角色——其提示词中固化的核心内容包括ADR-150 四条不变量load-bearing即“承重墙”级约束6 个 skill 的职责与调用时机表subprocess-only 工具契约只允许子进程调用上游二进制禁止库级 importPhase 0–3 的推进跟踪器。理解这个 Agent 的关键在于理解它守护的那条架构红线MetaHarness 只能增强 ruflo绝不能成为 ruflo 的必需运行时依赖。下面逐条展开。二、ADR-150 的 four 条 load-bearing 不变量Agent 文件将 ADR-150 的四条约束列为“承重”条款任何 PR 只要破坏其中任意一条即被视为 breaking change必须单独撰写一个新的 ADR 来取代该约束。四条不变量如下#不变量具体要求1Removable可移除移除全部metaharness/*包后npm ls --without-deps metaharness/*ruflo 必须仍然产出一个可工作的 CLI2Optional in package.json依赖可选每个metaharness/*包必须位于optionalDependencies或peerDependenciesoptional绝不允许出现在dependencies中3Graceful degradation优雅降级所有导入metaharness/*符号的代码路径必须捕获MODULE_NOT_FOUND并回退scripts/_harness.mjs 中的emitDegradedJsonAndExit()助手就是参考实现4CI gateCI 门禁至少一个 CI job 要在不安装任何 MetaHarness 包的环境下运行 ruflo并断言 smoke 契约仍然通过这四条规则出自 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静态检查扫描根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运行时演练drill将每个 skill 指向一个不可解析的 npm registry断言其输出结构化降级载荷graceful degradation而不是崩溃。配套的 metaharness-ci.yml 则负责“有 MetaHarness 在场”的一侧score / mcp-scan / router 兼容性等正向契约。两条工作流一正一反共同锁死可选依赖的边界。三、Agent 暴露的 6 个 Skill职责与调用时机Agent 文件给出的 skill 清单如下该表是 Agent 的“知识基线”每个 skill 对应一个SKILL.md与一个脚本Skill角色何时调用harness-score5 维数值记分卡mint 前就绪度检查CI 回归门禁harness-genome7 节分类报告mint 前架构评审随时间做漂移检测harness-mcp-scan静态 MCP 安全发现每个 PR企业安全评审harness-threat-model分类威胁报告发布前评审周期性 OIA 审计节奏harness-oia-audit复合周审计 workeriter 7Cron 定时将 oia threat mcp 打包为metaharness-audit命名空间中一条带时间戳的记录harness-mint脚手架一个自定义 harness用户想 fork 时永远先 dry-run绝不写入项目根目录下面结合仓库中的脚本与命令文档补充各 skill 的实战细节。3.1 harness-score5 维记分卡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-L17node 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-genome7 节分类报告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复合周审计 workerharness-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唯一可写的 skillharness-mint 的 SKILL.md 明确它是插件中唯一具备写能力的 skill其余全部纯读。其安全设计load-bearing有三条默认 dry-run不带--confirm时只打印将要执行的动作并 exit 0不触碰磁盘拒绝项目根--target若解析到当前工作目录或其内部任何路径直接以 exit 2 报错目标必须是调用仓库外部的绝对路径默认新建/tmp/ruflo-mint-ts-name/拒绝已存在目标绝不覆盖脚手架只能落入不存在的目录。模板覆盖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插件 READMEplugins/ruflo-metaharness/README.md显示插件后续又扩展到十余个 skillsimilarity、evolve、drift-from-history、security-bench、learn、gepa 等但其底层全部仍走同一条_harness.mjs子进程桥约束体系不变。四、Subprocess-Only 工具契约为什么禁止库 importAgent 文件的 “Tools” 一节给出四条契约这四条是整个集成设计的骨架所有 skill 只 shell out 到固定版本的metaharness/harness二进制metaharness~0.3.0本地安装或一次性版本化缓存——永不latest统一经由_harness.mjs共享助手每个子进程 60s 硬超时输出被捕获并解析强制--json标志除非脚本显式退出 JSON 模式除 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 -ylatestdist-tag存在两个问题——安全HIGHlatest意味着被入侵的上游发布会在下次 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→0low→1medium/warn→2high/error→3critical→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-L37runMetaharness返回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-below2 配置错误或上游评分失败。这套约定让 CI 可以精确区分“集成缺失”应容忍与“门禁未过”应失败。六、Phase 跟踪器与当前推进状态Agent 文件内嵌了四阶段推进跟踪器它是理解整个集成节奏的索引阶段状态内容Phase 0 — Measurement spike✅ 完成ruflo 自身记分卡于 2026-06-16 采集harnessFit 82risk_score 0.27publish_readiness 0.9Phase 1 — MVP plugin 进行中本提交 CI 门禁 KRR 重训练Phase 2 — Expansion⏳ 待推进eject 命令、SelfEvolvingRouter 并行日志、harness registry、oia-audit workerPhase 3 — Harness Intelligence Layer⏳ 待推进每个条目单独走 ADR从 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两处的optionalDependenciesPhase 2 交付了npx ruflo eject默认 dry-run、拒绝仓库内目标与覆盖已存在目标、插件注册表中的type: harness、oia-audit复合 worker 及其周级 cron以及SelfEvolvingRouter的并行记录/分析链路CLAUDE_FLOW_ROUTER_PARALLEL_LOG1门控未设置时零开销。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 中的工作流依赖侧新增的metaharness/*包是否只落在optionalDependencies是否同步了 package.json 与v3/claude-flow/cli/package.json两处的 pin且是波浪号范围而非latest/ caretno-metaharness-smoke.yml的静态检查会逐文件扫描拦截。导入侧新代码是否引入了import metaharness/*若非neural-router.ts的三重门控路径一律打回插件侧能力一律走_harness.mjs桥。降级侧新脚本是否在degraded: true时调用emitDegradedJsonAndExit并 exit 0退出码语义0/1/2是否与家族一致边界侧mint 是否仍拒绝项目根写入、仍默认 dry-runfrom-repo是否依然未被包装成 MCP 工具门禁侧是否更新了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.mjsskill 实现示例score.mjs、scripts 目录命令参考plugins/ruflo-metaharness/commands/ruflo-metaharness.mdskill 文档harness-score、harness-mint、harness-genome、harness-mcp-scan、harness-threat-model、harness-oia-auditCI 门禁.github/workflows/no-metaharness-smoke.yml、.github/workflows/metaharness-ci.ymlCLI 顶层分发器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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
