ruflo docs-writer 文档专员 Agent:API 文档自动生成、漂移检测与 document 后台 Worker 调度实战

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

ruflo docs-writer 文档专员 Agent:API 文档自动生成、漂移检测与 document 后台 Worker 调度实战

本文围绕 ruflo 仓库中的 docs-writer 文档专员 Agent(plugins/ruflo-docs/agents/docs-writer.md)展开,完整解析 ruflo-docs 插件的文档生成与漂移检测机制:从 Agent 的四项核心职责、五步文档工作流、五类文档类型矩阵,到 document 后台 Worker 的 CLI/MCP 双通道调度、docs-drift 命名空间状态存储,以及以 10 项检查构成的 smoke 契约验证。读完本文,你可以掌握如何用该 Agent 自动从 JSDoc/TSDoc 生成 API 参考、检测"代码变了文档没变"的漂移,并通过 hooks_worker-dispatch 触发批量文档生成。

docs-writer Agent 的角色定义与模型选型

docs-writer 是 ruflo-docs 插件内置的文档专员 Agent,其定义文件以 YAML frontmatter 声明了元信息:

---
name: docs-writer
description: Documentation specialist -- generates and maintains project documentation
model: haiku
---

其中 model: haiku 是一个有明确工程考量的选型决策。插件 README 的 Compatibility 一节将其解释为"Agent model: Haiku (cost-efficient for docs work)"——文档生成属于高频、低创造性、可批量执行的任务,用成本更低的 Haiku 模型承担可以显著压低 token 开销,同时把更强的模型留给架构决策类工作。这个选型不是口头约定:smoke 验证脚本 的第 10 项检查会直接断言 Agent 文件存在 model: haiku 行:

step "10. agent uses Haiku model (cost-efficient)"
grep -qE "^model:[[:space:]]*haiku" "$ROOT/agents/docs-writer.md" \
  && ok || bad "agent model is not Haiku"

也就是说,如果有人把 Agent 改回其他模型,验证契约(bash plugins/ruflo-docs/scripts/smoke.sh,期望输出 "10 passed, 0 failed")就会失败。这正是 ruflo-docs 插件 ADR 中所说的"smoke as contract"实践:ADR-0001 将 10 项 smoke 检查定义为插件契约的一部分。

四项核心职责

Agent 系统提示词将职责归纳为四点,覆盖文档生命周期的不同阶段:

  1. Generate(生成):从 JSDoc/TSDoc 注释和源码生成 API 文档;
  2. Maintain(维护):保证 README 和架构文档的准确性;
  3. Detect drift(漂移检测):发现"代码已变更但文档未同步"的失同步状态;
  4. Write(写作):按项目约定编写清晰、简洁的文档。

其中第 3 项是该 Agent 区别于普通"写文档"角色的核心能力,下文单独展开。

五步文档工作流

Agent 的 Workflow 章节定义了从识别目标到批量生成的完整流水线:

  1. 识别文档需求:判断哪些地方需要文档(新增 API、行为变更、缺失文档);
  2. 阅读源码:理解公共 API 面(public API surface);
  3. 比对现状:检查哪些已有文档需要更新,哪些需要新写;
  4. 生成文档:产出包含示例和用法模式的文档;
  5. 大规模生成时派发 Worker:npx @claude-flow/cli@latest hooks worker dispatch --trigger document。

前四步是 Agent 会话内的交互式流程,第 5 步则是把重活交给 ruflo 的后台 Worker 体系——这是该插件与 ruflo 多 Agent 编排基础设施的集成点,值得深入理解。

文档类型矩阵

Agent 按场景选择文档产出形态,原文档给出的类型表完整如下:

类型 格式 触发时机
API 参考 JSDoc/TSDoc → markdown 新增/变更导出
架构文档 ADR markdown 设计决策
用法示例 带注释的代码块 新功能
CLI 帮助 命令 + 参数表 新命令
插件文档 SKILL.md / agent .md 插件变更

这套分类直接对应 ruflo 仓库自身的文档实践:例如架构类用 v3/docs/adr 下的 ADR 文件,插件能力用各插件的 SKILL.md 与 agents 目录下的 .md 文件描述。

其中"API 参考"一类的具体产出规范,由 api-docs 技能 细化:

  • 扫描导出:找出所有公共函数、类和接口;
  • 提取 JSDoc:解析 @param、@returns、@throws、@example 注解;
  • 补全缺失文档:为没有注释的公共 API 添加 JSDoc;
  • OpenAPI 规格:对 HTTP 端点生成 OpenAPI 3.0 定义。

该技能还约定了 JSDoc 写法规范:每个公共导出必须有 JSDoc 注释,@param 和 @returns 需同时给出类型与描述,已知错误条件写 @throws,非显而易见的用法写 @example。

漂移检测:对比源码导出与已文档化 API

漂移检测(Drift Detection)是 docs-writer 的核心差异化能力。Agent 提示词给出的检测流程只有三步,但每一步都对应明确的工具动作:

  1. Grep 源码中的 export 语句——枚举当前实际存在的公共 API;
  2. Read 对应文档——获取已文档化的 API 集合;
  3. 标记差异——未文档化的导出(undocumented exports)和过期文档(stale docs)。

从工具列表看,这个流程的底座是四个通用工具:

  • Read、Grep、Glob——源码分析侧;
  • Write、Edit——文档输出侧。

值得注意的是,api-docs 技能的 frontmatter 还体现了 ruflo 插件的权限收敛风格:allowed-tools: Bash(npx *) mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch Read Write Grep——Bash 被限定在 npx * 前缀内,MCP 工具只开放 worker 调度这一个入口。ADR-0001 的 smoke 检查中专门有一项"no wildcard tools"(不允许无约束的通配工具授权),smoke 第 10 项之外还有对 Agent 模型、命名空间声明等的检查,构成对插件行为面的静态约束。

document 后台 Worker:调度方式与 Scope 语义

大规模文档生成不走 Agent 会话,而是通过 ruflo-loop-workers 定义的 12 个后台 Worker 中的 document Worker 完成。ruflo-loop-workers 的 README 给出了 12 个 trigger 到消费插件的完整映射表,其中明确写道:document trigger 的消费方是 ruflo-docs,用途是"Generate API docs + drift detection"。

ruflo-docs 提供两条等价的调度通道(CLI 与 MCP),这在 插件 README 的 "Document-worker contract" 一节 中有正式记录:

# 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 参数决定输出形态,scope 与产出的对应关系为:

Scope 输出
(不指定) 全项目文档扫描(Full project documentation pass)
api 从 JSDoc/TSDoc 生成 API 参考;HTTP 端点额外产出 OpenAPI 3.0
<file-path> 单文件文档生成

这个 scope 语义也在 doc-gen 技能 中以命令形式给出:API 文档用 --scope api,全项目用 --scope full;ruflo-docs 命令(用户侧入口 /ruflo-docs)则通过解析 $ARGUMENTS 自动选择:给了文件路径就单文件生成,给了 api 就生成 API 文档,无参数则全项目生成。

源码层面的调度实现

调度链路的另一端在 CLI 的 MCP 工具实现里。hooks-tools.ts 中定义的 hooks_worker-dispatch 工具,其 inputSchema 与插件文档描述的行为逐一对应:

name: 'hooks_worker-dispatch',
inputSchema: {
  type: 'object',
  properties: {
    trigger: {
      type: 'string',
      description: 'Worker trigger type',
      enum: ['ultralearn', 'optimize', 'consolidate', 'predict', 'audit',
              'map', 'preload', 'deepdive', 'document', 'refactor',
              'benchmark', 'testgaps'],
    },
    context: { type: 'string', description: 'Context for the worker (file path, topic, etc.)' },
    priority: { type: 'string', description: 'Priority (low, normal, high, critical)' },
    background: { type: 'boolean', description: 'Run in background (non-blocking)' },
  },
  required: ['trigger'],
},

从源码结构看,可以确认几个文档未明说的实现细节:

  • trigger 白名单校验:handler 用 WORKER_CONFIGS[trigger] 判断 trigger 合法性,未知 trigger 会返回错误并附上 availableTriggers 列表(hooks-tools.ts#L4526-L4532),document 正是 12 个合法枚举值之一;
  • daemon 存在性探测:dispatch 前会检查项目下 .claude-flow/daemon.pid 文件并 process.kill(pid, 0) 探活(hooks-tools.ts#L4540-L4553)。若 daemon 不在,工具会如实返回 no-daemon 状态并提示"Run claude-flow daemon start to enable real worker execution",而不是假装任务已完成——注释中标注这是对 ADR-093 F2 的修正("stop returning status:'completed' for a worker that never ran");
  • 持久化队列:daemon 存活时,后台派发会把任务写入 .claude-flow/daemon-queue/<workerId>.json 队列文件供 daemon 轮询(hooks-tools.ts#L4576-L4599)。注释说明这是针对 issue #1845 的修复:此前 dispatch 只更新进程内 Map,daemon(独立进程)根本看不到,queued 状态名不副实。

这些细节对使用者有实际意义:在验证文档生成是否真的执行前,先确认 daemon 已启动,并核对返回状态是否为诚实的 queued 而非 synthetic-completed。

状态存储:docs-drift 命名空间与持续维护

漂移检测需要跨会话记住"上次看到的导出哈希",ruflo-docs 为此声明了 AgentDB 命名空间。插件 README 的 "Namespace coordination" 一节说明:该插件拥有 kebab-case 的 docs-drift 命名空间,遵循 ruflo-agentdb 的命名空间约定(ADR-0001 §"Namespace convention"),用于存放每文件的 last-seen export hash,访问走 memory_* 工具(namespace-routed);同时明确保留命名空间(pattern、claude-memories、default)不可被占用。smoke 脚本第 7 项检查专门断言 README 中声明了 docs-drift 命名空间,第 6 项检查则断言 README 引用了 ruflo-agentdb 的 namespace convention,保证"命名空间协调"声明长期有效。

对于持续文档维护,doc-gen 技能 还给出了两条进阶用法:

  • 定时任务:用 Claude Code 原生的 CronCreate 挂每 2 小时一次的后台任务(CronCreate({ schedule: "0 */2 * * *", prompt: "Run document worker" })),把文档维护从"想起来才做"变成周期性作业;
  • 经验沉淀:把成功的文档生成方法写入记忆(mcp__plugin_ruflo-core_ruflo__memory_store({ key: "doc-pattern", value: "APPROACH", namespace: "patterns" }))。

契约验证与神经网络学习闭环

ruflo-docs 用 scripts/smoke.sh 作为插件契约验证,共 10 项检查:插件版本与关键词(jsdoc、openapi、mcp);两个技能(api-docs、doc-gen)与 Agent、Command 的 frontmatter 有效性;hooks_worker-dispatch 与 document trigger 的文档引用;@claude-flow/cli v3.6 版本锚定;命名空间协调声明;docs-drift 命名空间声明;document-worker scope 表文档化;ADR-0001 存在且状态为 Accepted;Agent 使用 Haiku 模型。运行方式与期望输出:

bash plugins/ruflo-docs/scripts/smoke.sh
# Expected: "10 passed, 0 failed"

工作流闭环的最后一环是 docs-writer 提示词中的 Neural Learning 步骤:任务完成后,把成功模式回灌给 ruflo 的神经学习系统:

npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true

这条命令让插件把"这次文档任务是怎么成功完成的"作为训练信号存储,与 ADR-0001 中列出的"real surface"(hooks_worker-dispatch、memory_store、Bash/Read/Write/Grep/Glob)共同构成该插件实际依赖的完整能力面。

插件全景与依赖关系

把上述要素拼起来,ruflo-docs 的组成是:1 个 Agent(docs-writer,Haiku)、2 个技能(api-docs、doc-gen)、1 个命令(/ruflo-docs)、1 个 ADR 和 1 个 smoke 契约。安装与依赖关系如下(见 README):

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-docs@ruflo
  • 依赖:ruflo-core 插件(提供 MCP server,hooks_worker-dispatch 等工具由此暴露);
  • 协作插件:ruflo-loop-workers 定义 document 后台 Worker 本体;ruflo-adr 在 ADR 状态变更时触发文档生成;ruflo-sparc 的 Documenter 模式(Phase 5 Refinement)消费本插件;ruflo-agentdb 是命名空间约定的所有方。

适用前提需要说明:CLI 能力锚定在 @claude-flow/cli v3.6 major+minor 之上,MCP 调度通道要求 ruflo-core 提供的 MCP server 可用,且真实执行 Worker 任务需要 daemon 运行(claude-flow daemon start),否则 dispatch 只会返回 no-daemon 的如实记录而非实际生成文档。

登录后查看全文
ruflo