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-00012026-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 个 Agentgoal-plannerGOAP A* 规划deep-researcher线性、问题驱动的多源研究horizon-tracker跨会话目标跟踪dossier-investigator递归并行多源调查对应 ADR-0995 个 Skillgoal-plan、deep-research、research-synthesize、horizon-track、dossier-collect1 个命令/goals列出活跃 horizon、检查进度、查看研究成果从 README.md 的 Selection guide 可以看到插件已经按任务形态做了明确分化你的需求使用一个问题questiondeep-researcher/deep-research一个种子实体需要向外展开seed entitydossier-investigator/dossier-collect一个多步骤目标multi-stepgoal-planner/goal-plan一个长期运行的目标long-runninghorizon-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 GradingHigh多个独立来源一致、可直接观察、可复现、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 用一张审计表完整记录了现状命名空间使用方规范合规性adrdossier-investigator、dossier-collect不合规— 应引用 ruflo-adr ADR-0001 中拥有权的 canonicaladr-patternsdossierdossier-investigator写入已记录的例外— 基础名称base-name规则参见 ruflo-federation 的federation先例researchdeep-researcher不合规— 按 kebab-case 的plugin-stem-intent规则应为goals-researchresearch-sourcesdeep-researcher不合规— 应为goals-research-sourceshorizonshorizon-tracker不合规— 应为goals-horizonshorizon-sessionshorizon-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-cookiesruflo-rag-memory 引用claude-memories / patterns / tasks / solutionsruflo-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前进方向状态adradr-patterns由 ruflo-adr 拥有遵从 canonical 拥有方 — 本插件不再写入dossierdossier已记录的 base-name 例外参见federationresearchgoals-researchlegacy 读取 新写入待数据可移植 ADRresearch-sourcesgoals-research-sourceslegacy 读取 新写入待定horizonsgoals-horizonslegacy 读取 新写入待定horizon-sessionsgoals-horizon-sessionslegacy 读取 新写入待定同时 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 部分给出四项决策每项都对应一个可验证的落地产物新增本 ADRProposed → Accepted补上插件级架构决策记录README 增强包含四块内容Compatibility钉扎claude-flow/cliv3.6Namespace coordination block上文所述的 legacy-vs-canonical 映射ADR-099 交叉链接为dossier-collect外链规格文档Verification Architecture Decisions 章节插件元数据保持 0.2.0已符合节奏关键词新增mcp、evidence-grading、legacy-namespacesgop是goap的笔误跳过不加入新增scripts/smoke.sh10 项结构性检查作为契约门禁。从仓库现状看这些决策已经全部落地.claude-plugin/plugin.json当前版本为0.2.1关键词数组中实际包含goap、research、planning、deep-research、long-horizon、dossier、investigation、osint、mcp、evidence-grading、legacy-namespacesREADME 已包含 Compatibility、Namespace coordination、Dossier-investigator (ADR-099)、Verification、Architecture Decisions 各章节。决策 2 的落点README 的契约化组织对照 README.md 可以看到契约元素的组织方式Compatibility章节声明CLI 钉扎到claude-flow/cliv3.6 majorminor验证入口为bash plugins/ruflo-goals/scripts/smoke.shDossier-investigator (ADR-099)章节列出四条关键不变量invariantsSeed-driven实体而非问题、Graph output图结构而非线性报告、Budget capshop 数、token、时间、Provenance per claim每条事实带来源归因。五、GOAP 与档案工作流契约agent-skill 对偶ADR-0001 标题中的GOAP/dossier workflow contract指的是规划与调查两类工作流分别由 agent skill 成对承载且 skill 是 agent 的可执行契约层。下面分别展开。GOAP 工作流goal-planner × goal-plangoal-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/clilatest hooks post-task --task-id TASK_ID --success true --store-results true档案工作流dossier-investigator × dossier-collectADR-099dossier-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全部适用源可用源子集maxDepth2自种子的递归深度maxBreadth8每轮每源最多追逐的新实体数budget可选{ tokens?, usd? }命中即干净中止exactfalse禁用 embedding 相似度去重用于实体身份敏感的场景其来源矩阵source matrix按种子类型选择工具来源工具最适合混合记忆memory_search_unified任意概念模式库agentdb_pattern-search重复模式分层召回agentdb_hierarchical-recall分层上下文向量HNSWembeddings_search语义近邻知识图谱hooks_intelligence_pattern-searchkg-traverse实体边Web 搜索WebSearch用户名、URL、当前状态Web 抓取WebFetch主页、README代码库Grep/Glob/Read符号、文件路径ADR 索引memory_searchnamespaceadrADR-id、设计决策Git 情报Bashgit 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 轮再调度第 k1 轮避免深度优先导致成本爆炸。六、smoke-as-contract把契约固化为 10 项结构性检查ADR-0001 最重要的工程实践是冒烟测试即契约smoke as contract。决策第 4 项要求新增scripts/smoke.sh执行 10 项结构性检查。对照 smoke.sh 源码这 10 项检查逐一对应 ADR 的承诺#检查项断言内容1plugin.json 声明 0.2.1 且含新关键词版本号精确匹配0.2.1关键词必须包含mcp、evidence-grading、legacy-namespaces25 skills 4 agents 1 command 齐全每个skills/name/SKILL.md存在且含name:与description:frontmatter4 个 agent 文件与命令文件存在3选择指南记录 4 类任务模式README 必须同时出现question、seed entity、multi-step、long-running四个 token4ADR-099 交叉链接README 必须同时出现ADR-099与dossier-investigator5README 钉扎 claude-flow/cli v3.6必须匹配claude-flow/cli.*v3.6或v3.6.*claude-flow/cli6README 引用 ruflo-agentdb 命名空间规范必须同时出现ruflo-agentdb与namespace convention7legacy-vs-canonical 映射已文档化README 必须同时出现horizons/goals-horizons与research/goals-research四组 token8ADR-0001 存在且状态为 Accepted文件存在且 frontmatter 匹配^status:\s*Accepted9档案 ADR-099 不变量已文档化README 必须出现Seed-driven、Graph output、Budget caps、Provenance10skills 无通配符工具授权任何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 —— 拥有 canonicaladr-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），仅供参考