ruflo-docs 插件实战指南:文档自动生成、漂移检测与 API 文档自动化管线
ruflo-docs 插件实战指南:文档自动生成、漂移检测与 API 文档自动化管线
ruflo-docs 是 ruflo 生态中的文档自动化插件:它通过后台 document worker 在代码变更时自动生成文档、检测"代码已改而文档未更"的漂移,并从 TypeScript 接口与 JSDoc 注释中产出 API 参考与 OpenAPI 3.0 规范。读完本文,你将掌握该插件的安装方式、document worker 的双路径调度(CLI 与 MCP)、docs-drift 命名空间协调约定,以及"以 smoke 脚本为契约"的插件质量门禁如何落地。
插件定位与能力总览
ruflo-docs 的目标不是"写一份文档",而是把文档维护变成一条可触发、可检测、可验证的自动化流水线。它包含以下核心能力:
- Auto-Documentation(自动文档):后台 worker 随代码变更自动生成文档;
- Drift Detection(漂移检测):识别文档与实现脱节的场景(代码变了但文档没跟上);
- API Docs(API 文档):从 TypeScript 接口和 JSDoc 自动生成 API 参考文档;
- CAPABILITIES.md 生成:通过
init命令产出完整的能力参考文件; - Document Worker:后台
documentworker 在 API 变更时触发; - SPARC 集成:复用
documenter与docs-writer两种 agent 模式。
在 ADR-0001(插件契约) 中记录了该插件的"真实使用面":通过 mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch 携带 trigger: "document" 触发文档 worker(document 是 CLAUDE.md 定义的 12 个后台 worker 之一);通过 memory_store 记录漂移检测状态;使用 Bash、Read、Write、Grep、Glob 完成源码与文档分析。
安装与依赖
安装命令
在 Claude Code 插件市场中通过以下两条命令安装:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-docs@ruflo
依赖与兼容性
| 项目 | 要求 |
|---|---|
| 运行时依赖 | ruflo-core 插件(提供 MCP server) |
| CLI 版本 | 固定(pin)到 @claude-flow/cli v3.6 主版本 + 次版本 |
| Agent 模型 | Haiku(面向文档工作,成本最优) |
| 验证契约 | bash plugins/ruflo-docs/scripts/smoke.sh |
插件目录结构如下(可直接在仓库中查看):
plugins/ruflo-docs/
├── agents/docs-writer.md # docs-writer agent 定义(Haiku 模型)
├── commands/ruflo-docs.md # /ruflo-docs 命令定义
├── docs/adrs/0001-docs-contract.md# 插件契约 ADR
├── scripts/smoke.sh # 10 项结构校验(契约门禁)
└── skills/
├── api-docs/SKILL.md # API 文档技能(JSDoc + OpenAPI)
└── doc-gen/SKILL.md # 文档生成 + 漂移检测技能
Document-worker 契约:两种触发路径
document 后台 worker 是 ruflo-loop-workers 定义的 12 个 worker 触发词之一(ultralearn、optimize、consolidate、predict、audit、map、preload、deepdive、document、refactor、benchmark、testgaps,见 ruflo-loop-workers ADR-0001)。ruflo-docs 通过两种方式驱动它:
# CLI 路径
npx @claude-flow/cli@latest hooks worker dispatch --trigger document
npx @claude-flow/cli@latest hooks worker dispatch --trigger document --scope api
# MCP 路径
mcp tool call hooks_worker-dispatch --json -- '{"trigger": "document", "scope": "api"}'
作用域与输出对应关系
| Scope | 输出 |
|---|---|
| (无) | 全项目文档生成(Full project documentation pass) |
api |
基于 JSDoc/TSDoc 的 API 参考 + HTTP 端点的 OpenAPI 3.0 规范 |
<file-path> |
单文件文档生成 |
从源码看,该作用域解析逻辑在 命令定义 中有完整实现:解析 $ARGUMENTS,若给出文件路径则对该文件生成文档;若给出 api 则生成 API 文档;若无参数则执行全项目文档生成。执行步骤为:分析目标的公共 API 与既有文档 → 检测代码与文档的漂移 → 生成或更新文档 → 汇报创建/变更内容。
值得注意的是 api-docs 技能 中给出了一条更长的 API 文档生成流水线:先扫描所有公共函数、类与接口的导出(Scan exports),再解析 @param、@returns、@throws、@example 注解(Extract JSDoc),为未文档化的公共 API 补充 JSDoc(Generate missing docs),最后为 HTTP 端点生成 OpenAPI 3.0 定义(OpenAPI spec)。
docs-writer Agent:文档维护的专职角色
插件内置的 docs-writer agent 是一个文档专家角色,明确钉住 model: haiku(成本最优),职责包括:
- 从 JSDoc/TSDoc 注解与源码生成 API 文档;
- 维护 README 与架构文档的准确性;
- 检测漂移——代码改了但文档没改;
- 按项目规范书写清晰、简洁的文档。
其工作流是:识别需要文档化的目标(新 API、变更行为、缺失文档)→ 读取源码理解公共 API 表面 → 判断是更新既有文档还是新建 → 生成带示例与用法模式的文档 → 对大规模生成派发 document worker:
npx @claude-flow/cli@latest hooks worker dispatch --trigger document
Agent 还定义了"文档类型 → 格式 → 触发时机"的映射表:
| 类型 | 格式 | 触发时机 |
|---|---|---|
| API reference | JSDoc/TSDoc → markdown | 新增/变更的导出 |
| Architecture | ADR markdown | 设计决策 |
| Usage examples | 带注释的代码块 | 新特性 |
| CLI help | 命令 + 参数表 | 新命令 |
| Plugin docs | SKILL.md / agent .md | 插件变更 |
漂移检测的具体手法是:用 Grep 搜索源码中的 export 语句,用 Read 读取对应文档,然后标记"未文档化的导出"与"过期文档"。任务完成后还可通过以下命令将成功模式沉淀进神经学习:
npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true
命名空间协调:docs-drift
ruflo-docs 拥有 docs-drift 这个 AgentDB 命名空间(kebab-case),遵循 ruflo-agentdb ADR-0001 的 "Namespace convention" 一节 约定。该命名空间用于存放漂移检测状态(每个文件的 last-seen export hash)。
两个硬性约定:
- 保留命名空间不可遮蔽:
pattern、claude-memories、default属于保留命名空间,MUST NOT 被覆盖或遮蔽(ruflo-agentdb 的 smoke 脚本中还有配套护栏:含冒号的命名空间、超过 205 字符的命名空间都会被拒绝,详见 ruflo-agentdb README); - 访问方式:
docs-drift必须通过命名空间路由的memory_*工具访问,例如 doc-gen 技能 中的memory_store调用。
mcp__plugin_ruflo-core_ruflo__memory_store({ key: "doc-pattern", value: "APPROACH", namespace: "patterns" })
顺带一提,ADR-0001 的"Implementation status"一节提到实际实现中漂移检测状态使用的命名空间名为 docs-state,而 README 对外契约声称的是 docs-drift——这是仓库内部契约描述与实现之间的细微差异,阅读源码时值得留意。
定时文档维护与 scoped 生成
doc-gen 技能 在基础 worker 派发之外提供了两种进阶用法:
定时维护——通过 CronCreate 实现"每两小时跑一次文档 worker"的常驻维护:
CronCreate({ schedule: "0 */2 * * *", prompt: "Run document worker" })
Scoped 生成——支持按作用域细粒度触发:
# API 文档
npx @claude-flow/cli@latest hooks worker dispatch --trigger document --scope api
# 全项目
npx @claude-flow/cli@latest hooks worker dispatch --trigger document --scope full
该技能将"方法沉淀"也纳入流程:把验证过的方案写入 patterns 命名空间,供后续任务复用。
Smoke 即契约:10 项结构校验
ruflo-docs 的核心质量门禁是 scripts/smoke.sh,运行方式:
bash plugins/ruflo-docs/scripts/smoke.sh
# 期望输出: "10 passed, 0 failed"
这 10 项检查构成了"插件结构契约",每一项都对应一个可验证的事实:
- 版本与关键词:
.claude-plugin/plugin.json声明0.2.1,且包含jsdoc、openapi、mcp三个关键词; - 两个技能存在且 frontmatter 合法:
api-docs与doc-gen各自的 SKILL.md 都必须包含name:、description:、allowed-tools:三个字段; - agent 与 command 存在:
agents/docs-writer.md与commands/ruflo-docs.md必须存在; - worker 派发被引用:仓库内必须引用
hooks_worker-dispatch且文档中出现documenttrigger; - CLI 版本固定:README 必须出现
@claude-flow/cli与 v3.6 的绑定关系; - 命名空间约定委托:README 必须引用 ruflo-agentdb 及 "Namespace convention";
- 命名空间声明:README 必须声明
docs-drift命名空间; - 作用域表:README 必须包含 "Document-worker contract" 小节及
apiscope 说明; - ADR 存在且 Accepted:
docs/adrs/0001-docs-contract.md存在且状态为Accepted; - Haiku 模型:
agents/docs-writer.md中model:必须为haiku(成本最优)。
这条契约链与 ruflo-loop-workers ADR-0001 中"worker-trigger → consumer-plugin 归属表"相互印证:document trigger 的消费方正是 ruflo-docs,而 audit 由 ruflo-security-audit、testgaps 由 ruflo-testgen 消费,形成一个可追溯的触发词消费闭环。
与周边插件的协作关系
ruflo-docs 不是孤立的,其协作网络在 README 中明确列出:
- ruflo-agentdb:命名空间约定(
docs-drift)的持有者与仲裁方; - ruflo-loop-workers:
document后台 worker 的定义方(12 个 worker 之一); - ruflo-adr:ADR 状态变更时触发文档生成;
- ruflo-sparc:Documenter 模式(Phase 5 Refinement,即"精化"阶段)消费本插件的文档能力。
整体来看,ruflo-docs 用"worker 触发 + 命名空间状态 + smoke 契约"三个机制,把文档自动化从一次性脚本提升为可验证、可协调、可持续运行的工程环节——这正是它作为 ruflo 插件生态中"文档基建"的核心价值。