ruflo-goals 插件契约（ADR-0001）解读：命名空间协调、GOAP/档案工作流与 smoke-as-contract 治理实践
【免费下载链接】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仓库中 ruflo-goals 插件的架构决策记录 ADR-0001（2026-05-04 提出、2026-05-09 更新，状态 Accepted），系统梳理该插件如何通过一份 ADR 同时解决三类工程问题：六个 AgentDB 命名空间在 legacy 与 canonical 两种命名规范之间的兼容映射、以 GOAP A* 规划与 ADR-099 档案调查为核心的工作流契约、以及用smoke.sh十项结构性检查将"契约"固化为可自动验证的门禁。读完本文，你将掌握 ruflo 插件体系的命名空间治理范式、ruflo-goals 四大 Agent 与五大 Skill 的完整能力清单，以及如何用"smoke-as-contract"模式保证文档与实现不漂移。
一、背景：ruflo-goals v0.2.0 的插件表面
ruflo-goals 是 ruflo 生态中承担长周期规划 + 深度研究 + 档案调查的插件（v0.2.0）。其表面（surface）相当丰富，ADR-0001 在 Context 一节中给出了官方清单：
- 4 个 Agent：
goal-planner（GOAP A* 规划）deep-researcher（线性、问题驱动的多源研究）horizon-tracker（跨会话目标跟踪）dossier-investigator（递归并行多源调查，对应 ADR-099）
- 5 个 Skill：
goal-plan、deep-research、research-synthesize、horizon-track、dossier-collect - 1 个命令：
/goals（列出活跃 horizon、检查进度、查看研究成果）
从 README.md 的 Selection guide 可以看到，插件已经按任务形态做了明确分化：
| 你的需求 | 使用 |
|---|---|
| 一个问题（question） | deep-researcher/deep-research |
| 一个种子实体需要向外展开（seed entity） | dossier-investigator/dossier-collect |
| 一个多步骤目标（multi-step） | goal-planner/goal-plan |
| 一个长期运行的目标（long-running） | horizon-tracker/horizon-track |
这份选择指南同时是 smoke.sh 第 3 项检查的断言对象（见下文验证章节），说明"四类任务模式"本身就是契约的一部分。
从源码看四个 Agent 的分工
阅读四个 Agent 的定义文件可以印证 ADR 中的定位：
- goal-planner.md 明确了 GOAP 方法论五步：状态评估（State Assessment）、动作分析（Action Analysis，含前置条件/效果/代价）、计划生成（A* 搜索）、执行监控（OODA 环：Observe–Orient–Decide–Act）、动态重规划；并提供 Focused / Closed / Open 三种执行模式。
- deep-researcher.md 定义了七步研究流程，核心是证据分级（Evidence Grading）：High（多个独立来源一致、可直接观察、可复现）、Medium（单一可信来源、间接支持、合理）、Low（传闻、单一未验证来源、推测），并将研究结果持久化到
research与research-sources命名空间。 - horizon-tracker.md 负责跨会话目标跟踪，在
horizons与horizon-sessions命名空间读写状态，并定义了五类漂移检测信号（时间线、范围、方法、依赖、优先级漂移）。 - dossier-investigator.md 实现 ADR-099 的递归并行调查（详见第四节）。
二、命名空间审计：六个命名空间，合规性参差不齐
ADR-0001 的核心洞察是：ruflo-goals 使用了AgentDB 的六个命名空间，但这些命名空间先于 ruflo-agentdb ADR-0001 的命名规范而存在，合规状况不一。ADR 用一张审计表完整记录了现状：
| 命名空间 | 使用方 | 规范合规性 |
|---|---|---|
adr | dossier-investigator、dossier-collect | 不合规— 应引用 ruflo-adr ADR-0001 中拥有权的 canonicaladr-patterns |
dossier | dossier-investigator写入 | 已记录的例外— 基础名称（base-name）规则，参见 ruflo-federation 的federation先例 |
research | deep-researcher | 不合规— 按 kebab-case 的<plugin-stem>-<intent>规则应为goals-research |
research-sources | deep-researcher | 不合规— 应为goals-research-sources |
horizons | horizon-tracker | 不合规— 应为goals-horizons |
horizon-sessions | horizon-tracker | 不合规— 应为goals-horizon-sessions |
命名规范来自哪里
ADR-0001 明确引用了 ruflo-agentdb ADR-0001 中提出的命名空间约定——<plugin-stem>-<intent>的 kebab-case 形式。该 ADR 指出，在规范确立之前，各下游插件（ruflo-browser 定义browser-sessions / browser-selectors / browser-templates / browser-cookies，ruflo-rag-memory 引用claude-memories / patterns / tasks / solutions，ruflo-intelligence 写入pattern）都在各自发明命名空间，缺少统一契约。ruflo-goals 的六个命名空间正是这种历史状态的产物。
base-name 例外先例
dossier命名空间之所以被豁免，是因为 ruflo-federation ADR-0001 确立了"基础名称（base-name）例外"先例——federation命名空间允许以插件名本身作为命名空间。dossier遵循同样的例外逻辑，因此被标记为"已记录的例外（Documented exception）"，而非不合规。
为什么不能直接改名
这六个命名空间先于规范存在，直接重命名会破坏已在这些旧命名空间中存有数据的项目。因此 ADR-0001 记录了一条双轨策略（这是本 ADR 最具实操价值的部分）：
- 既有存储继续使用 legacy 名称（本轮不做迁移）；
- 新写入SHOULD 使用 canonical kebab-case 形式（
goals-research、goals-horizons等）； - 读取同时检查新旧两个名称以保持向后兼容；
- 未来的数据可移植路径（data-portability）设计完成后，再由后续 ADR 提出改名 + 迁移方案。
这一策略在 README.md 的 Namespace coordination 一节被落实为一张"legacy → canonical"映射表：
| Legacy（当前） | Canonical（前进方向） | 状态 |
|---|---|---|
adr | adr-patterns（由 ruflo-adr 拥有） | 遵从 canonical 拥有方 — 本插件不再写入 |
dossier | dossier | 已记录的 base-name 例外（参见federation） |
research | goals-research | legacy 读取 + 新写入待数据可移植 ADR |
research-sources | goals-research-sources | legacy 读取 + 新写入待定 |
horizons | goals-horizons | legacy 读取 + 新写入待定 |
horizon-sessions | goals-horizon-sessions | legacy 读取 + 新写入待定 |
同时 README 强调：保留命名空间（pattern、claude-memories、default）不得被遮蔽（MUST NOT be shadowed）。
三、其他缺口盘点
ADR-0001 在审计命名空间之外，还诚实记录了插件的四个其他缺口：
- 没有插件级 ADR—— 本 ADR 正是为此而建（此前 ruflo-goals 缺少自己的架构决策记录）；
- 没有冒烟测试—— 缺少可自动化的契约验证入口；
- 没有 Compatibility（兼容性）章节—— 未声明对底层 CLI 的版本钉扎；
- ADR-099 被引用但 README 未外链——
dossier-collect依赖 ADR-099 的规格，但 README 没有交叉链接指向它。
这些缺口构成了后续决策的直接动因。
四、决策：一份 ADR 同时收敛四件事
ADR-0001 的 Decision 部分给出四项决策，每项都对应一个可验证的落地产物：
- 新增本 ADR（Proposed → Accepted）：补上插件级架构决策记录；
- README 增强，包含四块内容：
- Compatibility：钉扎
@claude-flow/cliv3.6； - Namespace coordination block：上文所述的 legacy-vs-canonical 映射；
- ADR-099 交叉链接：为
dossier-collect外链规格文档； - Verification + Architecture Decisions 章节；
- Compatibility：钉扎
- 插件元数据保持 0.2.0（已符合节奏），关键词新增
mcp、evidence-grading、legacy-namespaces（gop是goap的笔误，跳过不加入）； - 新增
scripts/smoke.sh：10 项结构性检查，作为契约门禁。
从仓库现状看，这些决策已经全部落地：.claude-plugin/plugin.json当前版本为0.2.1，关键词数组中实际包含goap、research、planning、deep-research、long-horizon、dossier、investigation、osint、mcp、evidence-grading、legacy-namespaces；README 已包含 Compatibility、Namespace coordination、Dossier-investigator (ADR-099)、Verification、Architecture Decisions 各章节。
决策 2 的落点：README 的契约化组织
对照 README.md 可以看到契约元素的组织方式：
- Compatibility章节声明：CLI 钉扎到
@claude-flow/cliv3.6 major+minor；验证入口为bash plugins/ruflo-goals/scripts/smoke.sh； - Dossier-investigator (ADR-099)章节列出四条关键不变量（invariants）：Seed-driven（实体而非问题）、Graph output（图结构而非线性报告）、Budget caps（hop 数、token、时间）、Provenance per claim（每条事实带来源归因）。
五、GOAP 与档案工作流契约：agent-skill 对偶
ADR-0001 标题中的"GOAP/dossier workflow contract"指的是规划与调查两类工作流分别由 agent + skill 成对承载，且 skill 是 agent 的可执行契约层。下面分别展开。
GOAP 工作流：goal-planner × goal-plan
goal-plan/SKILL.md 将 GOAP 流程固化为 11 步可执行动作：定义目标状态 → 评估当前状态 → 识别差距 → 盘点动作（前置条件/效果/成本估算）→ A* 生成最优动作序列 → 轨迹记录（trajectory-start）→ 任务创建（task_create）→ 按依赖序执行（执行前验证前置条件、执行后验证效果、逐步记录trajectory-step）→ 监控与重规划 → 完成轨迹（trajectory-end）→ 将成功计划存入goap-plans命名空间。
其允许工具列表（allowed-tools）严格限定在task_*、memory_*、neural_predict、workflow_*、hooks_intelligence_trajectory-*以及Bash/Read/Write/Edit，没有通配符授权——这正是 smoke.sh 第 10 项检查要守护的边界。
SKILL 还给出了计划输出格式与重规划触发器：
Goal: [concrete objective] Current State: [key facts] Plan Cost: [estimated effort] Steps: 1. [action] — precondition: [X], effect: [Y], cost: [Z] ... Risk Factors: [what could force a replan] Fallback: [alternative approach if primary path fails]重规划触发条件包括：动作失败（前置条件不再满足）、检测到意外副作用、新信息改变目标定义、成本超阈值、外部依赖不可用。执行完成后，goal-planner.md 还给出了神经学习回填命令：
npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --store-results true档案工作流：dossier-investigator × dossier-collect（ADR-099）
dossier-investigator与dossier-collect实现 ADR-099（递归并行多源研究）。该 ADR 明确其设计灵感来自 maigret 模式（并行扇出 + 递归扩展 + 结构化档案），并复用 ruflo 已有的全部原语：混合语义搜索（memory_search_unified）、向量搜索（embeddings_search）、模式召回（agentdb_pattern-search）、知识图谱遍历（kg-traverse）、Web 搜索/抓取（WebSearch/WebFetch）、代码库查询（Grep/Glob/Read）、ADR 索引（ruflo-adr:adr-index）、Git 情报（ruflo-jujutsu:diff-analyze）与轨迹记录（hooks_intelligence_trajectory-*）。
dossier-investigator.md 定义了完整的输入参数：
| 参数 | 默认值 | 含义 |
|---|---|---|
seed | 必填 | 起始实体，自动类型识别：文件路径 / 代码符号 / 用户名 / URL / ADR-id / 自由文本概念 |
sources | 全部适用源 | 可用源子集 |
maxDepth | 2 | 自种子的递归深度 |
maxBreadth | 8 | 每轮每源最多追逐的新实体数 |
budget | 可选 | { tokens?, usd? }，命中即干净中止 |
exact | false | 禁用 embedding 相似度去重，用于实体身份敏感的场景 |
其来源矩阵（source matrix）按种子类型选择工具：
| 来源 | 工具 | 最适合 |
|---|---|---|
| 混合记忆 | memory_search_unified | 任意概念 |
| 模式库 | agentdb_pattern-search | 重复模式 |
| 分层召回 | agentdb_hierarchical-recall | 分层上下文 |
| 向量（HNSW） | embeddings_search | 语义近邻 |
| 知识图谱 | hooks_intelligence_pattern-search+kg-traverse | 实体边 |
| Web 搜索 | WebSearch | 用户名、URL、当前状态 |
| Web 抓取 | WebFetch | 主页、README |
| 代码库 | Grep/Glob/Read | 符号、文件路径 |
| ADR 索引 | memory_search（namespaceadr） | ADR-id、设计决策 |
| Git 情报 | Bash（git log/git blame） | 作者、文件历史 |
递归循环采用广度优先（BFS）：种子 → 第 0 轮并行扇出 → 提取实体 → 去重（embedding 余弦相似度阈值 0.92，除非--exact）→ 第 1 轮以新实体重新播种 → 直到 depth ≥ maxDepth 或预算耗尽 → 聚合成图 + 渲染 Markdown + 输出 JSON。每轮内所有源查询必须在同一条消息中批量发出，绝不要把可并行的查询串行化。
产出三份工件（默认写入v3/docs/examples/dossiers/<seed-slug>/）：
<slug>.md：人类可读档案（执行摘要、实体表、mermaid 图、每条主张的来源溯源）；<slug>.json：机器可读图，结构为{ seed, depth, nodes: [{id, type, attrs, sources}], edges: [{from, to, kind, source, confidence}] }；- 命名空间
dossier下的记忆写入，key =<slug>。
dossier-collect/SKILL.md 提供了用户可直接调用的参数形式与示例：
/ruflo-goals:dossier-collect ruvnet /ruflo-goals:dossier-collect ADR-097 --max-depth 1 /ruflo-goals:dossier-collect "src/memory/hnsw.ts" --sources codebase,git,memory /ruflo-goals:dossier-collect "ruflo-goals" --max-breadth 5 --budget-usd 1其纪律条款包括：预算耗尽时干净中止并输出标记truncated: true的部分档案，绝不静默超支；每条节点与边都必须携带产生它的来源（无来源即无主张）；两个来源命名同一实体时"去重但不合并"（在同一节点上挂两个来源，不虚构综合主张）；递归扩展必须是 BFS（先完成第 k 轮再调度第 k+1 轮，避免深度优先导致成本爆炸）。
六、smoke-as-contract：把契约固化为 10 项结构性检查
ADR-0001 最重要的工程实践是"冒烟测试即契约"（smoke as contract）。决策第 4 项要求新增scripts/smoke.sh，执行 10 项结构性检查。对照 smoke.sh 源码，这 10 项检查逐一对应 ADR 的承诺：
| # | 检查项 | 断言内容 |
|---|---|---|
| 1 | plugin.json 声明 0.2.1 且含新关键词 | 版本号精确匹配0.2.1；关键词必须包含mcp、evidence-grading、legacy-namespaces |
| 2 | 5 skills + 4 agents + 1 command 齐全 | 每个skills/<name>/SKILL.md存在且含name:与description:frontmatter；4 个 agent 文件与命令文件存在 |
| 3 | 选择指南记录 4 类任务模式 | README 必须同时出现question、seed entity、multi-step、long-running四个 token |
| 4 | ADR-099 交叉链接 | README 必须同时出现ADR-099与dossier-investigator |
| 5 | README 钉扎 @claude-flow/cli v3.6 | 必须匹配@claude-flow/cli.*v3.6或v3.6.*claude-flow/cli |
| 6 | README 引用 ruflo-agentdb 命名空间规范 | 必须同时出现ruflo-agentdb与namespace convention |
| 7 | legacy-vs-canonical 映射已文档化 | README 必须同时出现horizons/goals-horizons与research/goals-research四组 token |
| 8 | ADR-0001 存在且状态为 Accepted | 文件存在且 frontmatter 匹配^status:\s*Accepted |
| 9 | 档案 ADR-099 不变量已文档化 | README 必须出现Seed-driven、Graph output、Budget caps、Provenance |
| 10 | skills 无通配符工具授权 | 任何skills/*/SKILL.md不允许^allowed-tools:\s*\* |
脚本采用简单的累加统计：PASS/FAIL计数，最终输出"10 passed, 0 failed"且失败时退出码为 1，可直接接入 CI。
验证命令
ADR-0001 与 README 均给出同一验证命令：
bash plugins/ruflo-goals/scripts/smoke.sh # Expected: "10 passed, 0 failed"从脚本逻辑看，set -u保证未定义变量即报错；ROOT通过$(cd "$(dirname "$0")/.." && pwd)解析到插件根目录，因此无论从仓库何处调用，检查的都是插件自身目录下的文件。值得注意的是，第 1 项检查要求插件版本为0.2.1而非 ADR 正文中的0.2.0——这反映了决策"元数据保持在 0.2.0 节奏"被后续版本演进覆盖的事实，也说明 smoke 契约随版本一起更新。
七、后果评估：正反两面与中性项
ADR-0001 对后果做了平衡评估：
- 正面：legacy 命名空间现在被明确标注为 legacy，并给出了 canonical 前进路径；后续以 goals 为模板新建的插件不会再复制不合规的命名方式（相当于为整个插件生态踩住了刹车）。
- 负面：legacy-vs-canonical 双轨制增加了文档表面积（documentation surface）。这不是免费的，但鉴于既有数据的存在是合理的代价。
- 中性：无任何功能变更，插件行为不变——这是一份纯治理型 ADR。
八、实现状态与关联文档
ADR-0001 的 Implementation status 一节确认：插件 v0.2.0 已发布并列入 marketplace.json，源码位于 plugins/ruflo-goals/。契约元素均已实现：
- 6 个命名空间映射到正确的
memory_*路由； - GOAP A* 规划器、ADR-099 档案递归扇出、horizon-track 跨会话 Agent 均已上线；
- smoke-as-contract 门禁定义于 scripts/smoke.sh。
与本文直接相关的仓库文档：
- ruflo-agentdb ADR-0001 —— 命名空间规范（
<plugin-stem>-<intent>）的源头； - ruflo-adr ADR-0001 —— 拥有 canonical
adr-patterns命名空间； - ruflo-federation ADR-0001 —— base-name 例外先例（
federation命名空间）； - ADR-099 —— dossier-collect 的完整规格；
- ruflo-goals README —— 契约元素的最终落点。
结语：一份 ADR 的多重治理价值
ruflo-goals ADR-0001 的价值不在于新增了什么功能，而在于它把历史负债、前进路径、验证门禁一次性收敛进一份可审计的文档：legacy 命名空间被显式承认并给出双轨读写策略，规避了破坏既有数据的迁移风险；GOAP 与 dossier 两类工作流通过 agent-skill 对偶被固化为可执行契约；smoke.sh的 10 项检查让 README 承诺、插件元数据、文件结构与命名规范全部变成可自动验证的断言。这种"以 ADR 定义契约、以 smoke 验证契约"的模式，是 ruflo 插件生态中可复用的治理样板——任何新建插件都可以照此模板，在第一天就把命名空间规范、版本钉扎与文档完整性钉死。
【免费下载链接】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），仅供参考
