ruflo-docs 插件实战指南:文档自动生成、漂移检测与 API 文档自动化管线

原创2026-09-09 20:24:131,656 阅读
文章标签:人工智能大模型AI AgentAgent 编排多智能体工具调用MCP 服务Agent 记忆Agent 工作流代码智能体AI 技能CLI插件系统浏览器控制提示词注入防护向量数据库模型评测

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:后台 document worker 在 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(成本最优),职责包括:

  1. 从 JSDoc/TSDoc 注解与源码生成 API 文档;
  2. 维护 README 与架构文档的准确性;
  3. 检测漂移——代码改了但文档没改;
  4. 按项目规范书写清晰、简洁的文档。

其工作流是:识别需要文档化的目标(新 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 项检查构成了"插件结构契约",每一项都对应一个可验证的事实:

  1. 版本与关键词:.claude-plugin/plugin.json 声明 0.2.1,且包含 jsdoc、openapi、mcp 三个关键词;
  2. 两个技能存在且 frontmatter 合法:api-docs 与 doc-gen 各自的 SKILL.md 都必须包含 name:、description:、allowed-tools: 三个字段;
  3. agent 与 command 存在:agents/docs-writer.md 与 commands/ruflo-docs.md 必须存在;
  4. worker 派发被引用:仓库内必须引用 hooks_worker-dispatch 且文档中出现 document trigger;
  5. CLI 版本固定:README 必须出现 @claude-flow/cli 与 v3.6 的绑定关系;
  6. 命名空间约定委托:README 必须引用 ruflo-agentdb 及 "Namespace convention";
  7. 命名空间声明:README 必须声明 docs-drift 命名空间;
  8. 作用域表:README 必须包含 "Document-worker contract" 小节及 api scope 说明;
  9. ADR 存在且 Accepted:docs/adrs/0001-docs-contract.md 存在且状态为 Accepted;
  10. 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 插件生态中"文档基建"的核心价值。

登录后查看全文
ruflo