ruflo-docs 插件契约解析文档 Worker 集成、命名空间协调与冒烟即契约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-docs 插件的 ADR-0001 契约文档系统讲解ruflo-docs插件如何把自动文档生成、漂移检测drift detection、API 文档自动化沉淀为一套可验证的插件级契约通过hooks_worker-dispatch驱动document后台 Worker、声明docs-drift命名空间、固定 CLI v3.6 兼容版本并用一份 10 项检查的scripts/smoke.sh把契约固化为可执行的验收门禁。读完本文你将掌握 ruflo 插件生态中ADR 记录决策 → README 声明契约 → 冒烟脚本强制验证的标准治理模式并能直接运行该插件的验证命令。背景ruflo-docs 插件的定位与真实调用面在 v0.1.0 阶段ruflo-docs是一个面向文档写作的轻量插件包含三个核心资产见 plugins/ruflo-docs/README.mdAgentdocs-writer一个文档专家 Agent负责生成 API 文档、维护 README、检测代码变了但文档没变的漂移并派发文档 Worker 做规模化生成。为了控制文档类任务的成本该 Agent 被显式固定在 Haiku 模型上见 agents/docs-writer.md 的model: haiku前置元数据。技能Skillsapi-docs从 TypeScript/JavaScript 源码生成 API 文档支持 JSDoc 与 OpenAPI 3.0见 skills/api-docs/SKILL.md和doc-gen带漂移检测的通用文档生成与维护支持 CronCreate 定时任务见 skills/doc-gen/SKILL.md。命令Command/ruflo-docs一个解析$ARGUMENTS决定作用域单文件 /api/ 全项目的分发入口见 commands/ruflo-docs.md。该插件实际使用的 MCP 面ADR-0001 Context 一节明确列出mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch以trigger: document驱动文档后台 Worker——document是 CLAUDE.md 所列 12 个后台 Worker 之一mcp__plugin_ruflo-core_ruflo__memory_store用于保存漂移检测状态Bash、Read、Write、Grep、Glob等基础工具用于源码与文档分析。ADR 同时指出了当时的标准缺口Standard gaps没有插件级 ADR、没有冒烟测试、没有 Compatibility 章节、没有命名空间协调声明。这四点正是本次契约要补齐的内容。决策把文档 Worker 集成契约化的五个动作ADR-0001 的 Decision 一节将修复方案收敛为五个插件本地动作不改动任何 CLI 源码或底层实现新增本 ADR状态 Proposed验收后转 Accepted。扩充 README新增 Compatibility固定 v3.6、Namespace coordination认领docs-drift、Document-worker contract哪个 trigger 映射哪个输出、Verification 与 Architecture Decisions 五个小节。版本升级0.1.0 → 0.2.0关键词新增jsdoc、openapi、mcp。新增scripts/smoke.sh内含 10 项结构检查详见下文冒烟即契约小节。契约落地后实现状态插件 v0.2.0 已发布并进入 marketplace.json源码位于plugins/ruflo-docs/。这套动作并非孤例而是 ruflo 插件生态中反复出现的治理模式——ruflo-adr 的 ADR-0001 将其总结为pin → ADR → smoke → namespace coordination四步走ruflo-docs是这套模式在文档领域的具体落地。Document-worker contracttrigger 到输出的映射表契约的核心是明确documentWorker 的两种调用路径与三种作用域输出。README 中记录了两条可复制的调用方式# CLI 方式 npx claude-flow/clilatest hooks worker dispatch --trigger document npx claude-flow/clilatest hooks worker dispatch --trigger document --scope api # MCP 方式 mcp tool call hooks_worker-dispatch --json -- {trigger: document, scope: api}作用域与输出的对应关系是契约中最重要的表格Scope输出无全项目文档生成一轮full project documentation passapi基于 JSDoc/TSDoc 的 API 参考 HTTP 端点的 OpenAPI 3.0 定义file-path单个文件的文档生成这套映射在 CLI 源码层有完整实现证据。在 v3/claude-flow/cli/src/mcp-tools/hooks-tools.ts 中WorkerTrigger类型把document列为 12 个合法 trigger 之一注释明确标注 Auto-documentationWORKER_TRIGGER_PATTERNS 的 document 条目 定义了自动触发识别正则包括/document\s(this|the)/i、/generate\sdocs/i、/add\sdocumentation/i、/write\sreadme/i、/api\sdocs/i、/jsdoc/i——这意味着 Agent 在对话中说出这些意图时系统可自动匹配到documentWorkerWORKER_CONFIGS 的 document 配置 给出其运行特征优先级normal、预计耗时 45s、能力标签documentation / writing / generation。hooks_worker-dispatch工具本身定义在 同一文件的 L4500-L4524trigger参数以 enum 形式枚举了全部 12 个 triggerrequired: [trigger]。配套地plugins/ruflo-loop-workers/README.md 的 Worker 归属表中确认documenttrigger 由ruflo-docs消费Generate API docs drift detection其循环调度节奏为600sloop/0 */2 * * *cron见 loop-worker-coordinator.md 与 cron-schedule/SKILL.md。ruflo-loop-workers的 ADR-0001 明确把document到ruflo-docs的归属写进 trigger→消费者映射见 0001-loop-workers-contract.md与本文 ADR 形成双向印证。命名空间协调认领docs-drift不得遮蔽保留命名空间漂移检测需要保存每个文件最后导出的哈希last-seen export hash per file这类状态这需要一个专属的 AgentDB 命名空间。契约的约定是本插件认领docs-drift命名空间kebab-case专门用于存放漂移检测状态并通过memory_*工具命名空间路由访问命名方式遵循 ruflo-agentdb ADR-0001 的Namespace convention章节plugin-stem-intent的 kebab-case 形式保留命名空间不得遮蔽patternReasoningBank 回退写入位置、claude-memoriesClaude Code 自动记忆桥接目标、defaultmemory_store的默认命名空间这三个由 AgentDB 插件本身拥有的命名空间任何下游插件都不得占用。命名空间约定还包含硬性护栏命名空间不得包含:会与桥接层 key 内部定界符冲突、长度必须 ≤200 字符、且必须通过validateIdentifier校验同一校验器也用于 agentdb-tools.ts 的 L122 处。漂移检测的具体流程在 docs-writer 的 Drift Detection 一节 有完整定义先用Grep扫描源码中的export语句再Read对应文档最后标记未文档化的导出与过期文档。冒烟即契约scripts/smoke.sh的 10 项检查ADR 将契约的定义从散文上升为可执行脚本——scripts/smoke.sh运行通过即契约成立运行失败即契约被破坏。这份脚本位于 plugins/ruflo-docs/scripts/smoke.sh是一份纯 Bash 实现set -u无外部依赖10 项检查如下#检查内容验证要点1plugin.json声明 0.2.1 且包含jsdoc、openapi、mcp关键词版本与关键词元数据注脚本期望值已从 ADR 撰写时的 0.2.0 演进为 0.2.12api-docs与doc-gen两个技能都存在且 SKILL.md 前置元数据含name:、description:、allowed-tools:技能资产完整性与 frontmatter 合法性3agents/docs-writer.md与commands/ruflo-docs.md存在Agent 与命令资产齐全4仓库内.md文件引用hooks_worker-dispatch或hooks worker dispatch且documenttrigger 被记录document Worker 集成被文档化5README 中固定claude-flow/cli到 v3.6兼容性 pin匹配生态节奏6README 引用ruflo-agentdb与 Namespace convention命名空间约定引用到位7README 声明docs-drift命名空间命名空间认领存在8README 含 Document-worker contract 标题与apiscope 说明Worker 契约与作用域表被记录9ADR-0001 文件存在且状态为Accepted决策文档状态正确10docs-writerAgent 前置元数据为model: haiku成本效率模型 pinHaiku 对文档任务性价比最高脚本最后输出N passed, M failed任何一项失败都会以退出码 1 终止[[ $FAIL -eq 0 ]] || exit 1可直接接入 CI。README 的 Verification 一节给出了期望输出bash plugins/ruflo-docs/scripts/smoke.sh # Expected: 10 passed, 0 failed注意检查 9 要求 ADR 状态为Accepted——本文对应的 ADR 已从最初的 Proposed 转正实现状态一节也已确认全部契约要素落地。实现状态契约要素逐项核对ADR 的 Implementation status 一节给出了验收结论五个契约要素均已实现document后台 Worker 派发经由hooks_worker-dispatch完成CLI 与 MCP 双路径可用见上文调用示例命名空间docs-drift认领用于漂移检测状态README 与冒烟脚本第 7 项双重确认ADR 正文决策一节同样声明 claimsdocs-driftHaiku 模型 pindocs-writerAgent 前置元数据锁定model: haiku冒烟脚本第 10 项强制校验smoke-as-contract 门禁定义于scripts/smoke.sh10 项检查全部通过方可视为契约成立版本与发布插件 v0.2.0 已发布并列入 marketplace.json。契约带来三方面积极后果插件纳入生态统一节奏、document Worker 集成从口头约定升级为契约化文档、漂移问题可在 CI 中被结构性捕获。ADR 明确记录无负面后果。关联生态契约的上下游协作本 ADR 与 ruflo 插件治理体系深度耦合可在仓库中继续追踪以下关联ruflo-agentdb ADR-0001——命名空间约定的所有权来源本插件向其看齐ruflo-adr ADR-0001——兄弟插件的文档节奏ADR 状态变更会触发文档生成ruflo-loop-workers——定义document后台 Worker 的归属方12 Worker 触发器的规范源v3/claude-flow/cli/src/mcp-tools/hooks-tools.ts——hooks_worker-dispatch的底层实现documenttrigger 的 enum、自动触发模式与 Worker 配置均在此处。依赖关系上ruflo-docs要求ruflo-core插件提供 MCP serverREADME 的 Requires 一节并消费ruflo-sparc的 Documenter 模式Phase 5 Refinement。这套ADR 记录决策 README 声明契约 smoke 脚本强制验证的闭环保证了文档生成这条自动化流水线在仓库演进中始终可验证、可回归。【免费下载链接】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），仅供参考 ruflo-docs 插件契约解析：文档 Worker 集成、命名空间协调与“冒烟即契约“（smoke-as-contract）实践
ruflo-docs 插件契约解析文档 Worker 集成、命名空间协调与冒烟即契约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-docs 插件的 ADR-0001 契约文档系统讲解ruflo-docs插件如何把自动文档生成、漂移检测drift detection、API 文档自动化沉淀为一套可验证的插件级契约通过hooks_worker-dispatch驱动document后台 Worker、声明docs-drift命名空间、固定 CLI v3.6 兼容版本并用一份 10 项检查的scripts/smoke.sh把契约固化为可执行的验收门禁。读完本文你将掌握 ruflo 插件生态中ADR 记录决策 → README 声明契约 → 冒烟脚本强制验证的标准治理模式并能直接运行该插件的验证命令。背景ruflo-docs 插件的定位与真实调用面在 v0.1.0 阶段ruflo-docs是一个面向文档写作的轻量插件包含三个核心资产见 plugins/ruflo-docs/README.mdAgentdocs-writer一个文档专家 Agent负责生成 API 文档、维护 README、检测代码变了但文档没变的漂移并派发文档 Worker 做规模化生成。为了控制文档类任务的成本该 Agent 被显式固定在 Haiku 模型上见 agents/docs-writer.md 的model: haiku前置元数据。技能Skillsapi-docs从 TypeScript/JavaScript 源码生成 API 文档支持 JSDoc 与 OpenAPI 3.0见 skills/api-docs/SKILL.md和doc-gen带漂移检测的通用文档生成与维护支持 CronCreate 定时任务见 skills/doc-gen/SKILL.md。命令Command/ruflo-docs一个解析$ARGUMENTS决定作用域单文件 /api/ 全项目的分发入口见 commands/ruflo-docs.md。该插件实际使用的 MCP 面ADR-0001 Context 一节明确列出mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch以trigger: document驱动文档后台 Worker——document是 CLAUDE.md 所列 12 个后台 Worker 之一mcp__plugin_ruflo-core_ruflo__memory_store用于保存漂移检测状态Bash、Read、Write、Grep、Glob等基础工具用于源码与文档分析。ADR 同时指出了当时的标准缺口Standard gaps没有插件级 ADR、没有冒烟测试、没有 Compatibility 章节、没有命名空间协调声明。这四点正是本次契约要补齐的内容。决策把文档 Worker 集成契约化的五个动作ADR-0001 的 Decision 一节将修复方案收敛为五个插件本地动作不改动任何 CLI 源码或底层实现新增本 ADR状态 Proposed验收后转 Accepted。扩充 README新增 Compatibility固定 v3.6、Namespace coordination认领docs-drift、Document-worker contract哪个 trigger 映射哪个输出、Verification 与 Architecture Decisions 五个小节。版本升级0.1.0 → 0.2.0关键词新增jsdoc、openapi、mcp。新增scripts/smoke.sh内含 10 项结构检查详见下文冒烟即契约小节。契约落地后实现状态插件 v0.2.0 已发布并进入 marketplace.json源码位于plugins/ruflo-docs/。这套动作并非孤例而是 ruflo 插件生态中反复出现的治理模式——ruflo-adr 的 ADR-0001 将其总结为pin → ADR → smoke → namespace coordination四步走ruflo-docs是这套模式在文档领域的具体落地。Document-worker contracttrigger 到输出的映射表契约的核心是明确documentWorker 的两种调用路径与三种作用域输出。README 中记录了两条可复制的调用方式# CLI 方式 npx claude-flow/clilatest hooks worker dispatch --trigger document npx claude-flow/clilatest hooks worker dispatch --trigger document --scope api # MCP 方式 mcp tool call hooks_worker-dispatch --json -- {trigger: document, scope: api}作用域与输出的对应关系是契约中最重要的表格Scope输出无全项目文档生成一轮full project documentation passapi基于 JSDoc/TSDoc 的 API 参考 HTTP 端点的 OpenAPI 3.0 定义file-path单个文件的文档生成这套映射在 CLI 源码层有完整实现证据。在 v3/claude-flow/cli/src/mcp-tools/hooks-tools.ts 中WorkerTrigger类型把document列为 12 个合法 trigger 之一注释明确标注 Auto-documentationWORKER_TRIGGER_PATTERNS 的 document 条目 定义了自动触发识别正则包括/document\s(this|the)/i、/generate\sdocs/i、/add\sdocumentation/i、/write\sreadme/i、/api\sdocs/i、/jsdoc/i——这意味着 Agent 在对话中说出这些意图时系统可自动匹配到documentWorkerWORKER_CONFIGS 的 document 配置 给出其运行特征优先级normal、预计耗时 45s、能力标签documentation / writing / generation。hooks_worker-dispatch工具本身定义在 同一文件的 L4500-L4524trigger参数以 enum 形式枚举了全部 12 个 triggerrequired: [trigger]。配套地plugins/ruflo-loop-workers/README.md 的 Worker 归属表中确认documenttrigger 由ruflo-docs消费Generate API docs drift detection其循环调度节奏为600sloop/0 */2 * * *cron见 loop-worker-coordinator.md 与 cron-schedule/SKILL.md。ruflo-loop-workers的 ADR-0001 明确把document到ruflo-docs的归属写进 trigger→消费者映射见 0001-loop-workers-contract.md与本文 ADR 形成双向印证。命名空间协调认领docs-drift不得遮蔽保留命名空间漂移检测需要保存每个文件最后导出的哈希last-seen export hash per file这类状态这需要一个专属的 AgentDB 命名空间。契约的约定是本插件认领docs-drift命名空间kebab-case专门用于存放漂移检测状态并通过memory_*工具命名空间路由访问命名方式遵循 ruflo-agentdb ADR-0001 的Namespace convention章节plugin-stem-intent的 kebab-case 形式保留命名空间不得遮蔽patternReasoningBank 回退写入位置、claude-memoriesClaude Code 自动记忆桥接目标、defaultmemory_store的默认命名空间这三个由 AgentDB 插件本身拥有的命名空间任何下游插件都不得占用。命名空间约定还包含硬性护栏命名空间不得包含:会与桥接层 key 内部定界符冲突、长度必须 ≤200 字符、且必须通过validateIdentifier校验同一校验器也用于 agentdb-tools.ts 的 L122 处。漂移检测的具体流程在 docs-writer 的 Drift Detection 一节 有完整定义先用Grep扫描源码中的export语句再Read对应文档最后标记未文档化的导出与过期文档。冒烟即契约scripts/smoke.sh的 10 项检查ADR 将契约的定义从散文上升为可执行脚本——scripts/smoke.sh运行通过即契约成立运行失败即契约被破坏。这份脚本位于 plugins/ruflo-docs/scripts/smoke.sh是一份纯 Bash 实现set -u无外部依赖10 项检查如下#检查内容验证要点1plugin.json声明 0.2.1 且包含jsdoc、openapi、mcp关键词版本与关键词元数据注脚本期望值已从 ADR 撰写时的 0.2.0 演进为 0.2.12api-docs与doc-gen两个技能都存在且 SKILL.md 前置元数据含name:、description:、allowed-tools:技能资产完整性与 frontmatter 合法性3agents/docs-writer.md与commands/ruflo-docs.md存在Agent 与命令资产齐全4仓库内.md文件引用hooks_worker-dispatch或hooks worker dispatch且documenttrigger 被记录document Worker 集成被文档化5README 中固定claude-flow/cli到 v3.6兼容性 pin匹配生态节奏6README 引用ruflo-agentdb与 Namespace convention命名空间约定引用到位7README 声明docs-drift命名空间命名空间认领存在8README 含 Document-worker contract 标题与apiscope 说明Worker 契约与作用域表被记录9ADR-0001 文件存在且状态为Accepted决策文档状态正确10docs-writerAgent 前置元数据为model: haiku成本效率模型 pinHaiku 对文档任务性价比最高脚本最后输出N passed, M failed任何一项失败都会以退出码 1 终止[[ $FAIL -eq 0 ]] || exit 1可直接接入 CI。README 的 Verification 一节给出了期望输出bash plugins/ruflo-docs/scripts/smoke.sh # Expected: 10 passed, 0 failed注意检查 9 要求 ADR 状态为Accepted——本文对应的 ADR 已从最初的 Proposed 转正实现状态一节也已确认全部契约要素落地。实现状态契约要素逐项核对ADR 的 Implementation status 一节给出了验收结论五个契约要素均已实现document后台 Worker 派发经由hooks_worker-dispatch完成CLI 与 MCP 双路径可用见上文调用示例命名空间docs-drift认领用于漂移检测状态README 与冒烟脚本第 7 项双重确认ADR 正文决策一节同样声明 claimsdocs-driftHaiku 模型 pindocs-writerAgent 前置元数据锁定model: haiku冒烟脚本第 10 项强制校验smoke-as-contract 门禁定义于scripts/smoke.sh10 项检查全部通过方可视为契约成立版本与发布插件 v0.2.0 已发布并列入 marketplace.json。契约带来三方面积极后果插件纳入生态统一节奏、document Worker 集成从口头约定升级为契约化文档、漂移问题可在 CI 中被结构性捕获。ADR 明确记录无负面后果。关联生态契约的上下游协作本 ADR 与 ruflo 插件治理体系深度耦合可在仓库中继续追踪以下关联ruflo-agentdb ADR-0001——命名空间约定的所有权来源本插件向其看齐ruflo-adr ADR-0001——兄弟插件的文档节奏ADR 状态变更会触发文档生成ruflo-loop-workers——定义document后台 Worker 的归属方12 Worker 触发器的规范源v3/claude-flow/cli/src/mcp-tools/hooks-tools.ts——hooks_worker-dispatch的底层实现documenttrigger 的 enum、自动触发模式与 Worker 配置均在此处。依赖关系上ruflo-docs要求ruflo-core插件提供 MCP serverREADME 的 Requires 一节并消费ruflo-sparc的 Documenter 模式Phase 5 Refinement。这套ADR 记录决策 README 声明契约 smoke 脚本强制验证的闭环保证了文档生成这条自动化流水线在仓库演进中始终可验证、可回归。【免费下载链接】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），仅供参考