ruflo 项目 OpenAPI 文档编写 Agent 全解析：从 Agent 定义、自学习协议到规范落地实践

ruflo（Claude-Flow v3）在 v3/@claude-flow/cli/.claude/agents/ 目录下以 Markdown + YAML frontmatter 的形式内置了一批专业化 Agent，本文聚焦其中的 api-docs（OpenAPI Documentation Specialist）：它是一份完整的、可被 Claude Code 等宿主自动加载的 Agent 定义，既描述了如何编写 OpenAPI 3.0 兼容的 API 文档，也通过"模式自学习"协议让文档产出随经验积累而持续改进。读完本文，你将掌握这套 Agent 定义文件的字段语义、触发与约束机制、生命周期 hooks 的设计，以及如何参照仓库中真实的 cognitum-v1.openapi.yaml 把规范落实到可运行的 API 文档工程中。

关联文档与仓库背景

• 主文档：docs-api-openapi.md（版本 1.0.0）
• 升级版文档：docs-api-openapi.md（版本 2.0.0-alpha，新增自学习与模式生成能力）
• 自学习底层实现：reasoningbank/index.ts（ReasoningBank 向量模式库）
• 协作 Agent：dev-backend-api.md（后端 API 开发者）
• 真实 OpenAPI 示例：cognitum-v1.openapi.yaml

两个版本的文档主体相同：frontmatter 声明 Agent 的触发条件、能力边界、约束与 hooks；正文给出职责清单、最佳实践、OpenAPI 3.0 骨架示例与文档要素。2.0.0-alpha 版额外引入了"Before / During / After"三阶段自学习协议。下文按"定义 → 触发 → 能力 → 规范 → 学习 → 生命周期 → 协作 → 实践"的顺序展开。

一、Agent 定义文件：frontmatter 字段语义

api-docs 的完整定义由 YAML frontmatter 与 Markdown 正文组成。frontmatter 是宿主（Claude Code）加载 Agent 的契约，各字段含义如下：

字段	取值（以主文档为例）	语义
name	api-docs	Agent 唯一标识，用于路由与引用
description	Expert agent for creating and maintaining OpenAPI/Swagger documentation	能力一句话摘要，用于触发匹配
color / type	indigo / documentation	UI 分组与类型标记
version	1.0.0（升级版为 2.0.0-alpha）	定义版本，升级版还带 updated 时间戳
triggers	见下节	关键词、文件模式、任务模式、领域四类触发条件
capabilities	见第四节	可用工具白名单、限制工具、操作上限
constraints	见第三节	路径白名单/黑名单、文件大小与类型限制
behavior / communication	lenient / technical	错误处理策略与沟通风格
integration	见第八节	可委托、共享上下文的 Agent 关系
optimization	parallel_operations: true, batch_size: 10	并行度与资源上限
hooks	见第七节	pre_execution / post_execution / on_error 三阶段脚本

metadata 中 complexity: moderate、autonomous: true 表明该 Agent 定位为中等复杂度、可自主执行的文档任务专员。升级版额外声明了 v2_capabilities：self_learning、context_enhancement、fast_processing、smart_coordination，这正是 2.0.0-alpha 相对 1.0.0 的核心差异。

二、触发机制：何时唤起 api-docs

Agent 通过四类模式自动触发，主文档定义如下：

关键词（keywords）：api documentation、openapi、swagger、api docs、endpoint documentation。

文件模式（file_patterns）：**/openapi.yaml、**/swagger.yaml、**/api-docs/**、**/api.yaml。仓库中 v3/docs/api/cognitum-v1.openapi.yaml 正好命中 **/openapi.yaml 与 **/api/** 类模式，说明该文件即 api-docs 的典型工作对象。

任务模式（task_patterns）：document * api、create openapi spec、update api documentation——以自然语言任务描述触发。

领域（domains）：documentation、api。

在升级版中，这些触发条件被进一步用于自学习：pre_execution hook 会把 $TASK 作为查询键去 ReasoningBank 中检索相似历史模式（见第六节），因此触发越精确，检索到的历史经验越相关。

三、能力边界与约束：安全的工作沙箱

capabilities 与 constraints 共同界定了 Agent 的权限：

• 允许的工具：Read、Write、Edit、MultiEdit、Grep、Glob——纯文档读写与检索类工具；
• 禁用工具：Bash、Task、WebSearch。Bash 被注释为 "No need for execution"（文档任务无需执行命令），Task 被注释为 "Focused on documentation"（保持专注），这从机制上防止文档 Agent 越权执行代码或分发子任务；
• 操作上限：max_file_operations: 50、max_execution_time: 300（秒）、memory_limit: 256MB；
• 路径白名单：docs/**、api/**、openapi/**、swagger/**、*.yaml、*.yml、*.json；
• 路径黑名单：node_modules/**、.git/**、secrets/**；
• 文件限制：单文件最大 2MB（max_file_size: 2097152），允许处理 .yaml、.yml、.json、.md。

行为策略：error_handling: lenient（宽松容错）、auto_rollback: false；删除 API 文档、变更 API 版本两类操作需要人工确认（confirmation_required）。

对比后端开发 Agent dev-backend-api.md 的配置（允许 Bash/Task、max_file_operations: 100、max_execution_time: 600、memory_access: "both"），可以清晰看到"文档 Agent 收窄权限、开发 Agent 放宽权限"的分工设计——工具白名单本身就是一种职责边界约束。

四、五大核心职责与最佳实践

正文部分定义了 Agent 的关键职责（Key responsibilities）：

1. 创建 OpenAPI 3.0 合规的规范文件；
2. 为所有端点编写描述与示例；
3. 准确定义请求/响应 schema；
4. 包含认证与安全方案（security schemes）；
5. 为所有操作提供清晰的示例。

最佳实践（Best practices）要求：

• 使用描述性的 summary 与 description；
• 包含请求/响应示例；
• 记录所有可能的错误响应；
• 用 $ref 复用组件（components）；
• 严格遵循 OpenAPI 3.0 规范；
• 用 tags 对端点进行逻辑分组。

升级版在职责与最佳实践中追加了 8/9/10 三条模式化实践：开始前先搜索相似文档模式、用模式生成保证一致性、存储成功的文档模式以供复用——它们与第六节的自学习协议一一对应，构成"检索—生成—沉淀"闭环。

五、OpenAPI 3.0 规范骨架：可直接套用的最小模板

文档内置的骨架示例（原样继承）：

openapi: 3.0.0
info:
  title: API Title
  version: 1.0.0
  description: API Description
servers:
  - url: https://api.example.com
paths:
  /endpoint:
    get:
      summary: Brief description
      description: Detailed description
      parameters: []
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
              example:
                key: value
components:
  schemas:
    Model:
      type: object
      properties:
        id:
          type: string

这是六段式规范：openapi 版本声明 → info 元信息 → servers 服务器列表 → paths 路径与操作 → responses 响应（含 schema 与 example）→ components.schemas 可复用模型。文档要素（Documentation elements）进一步要求：清晰的 operation ID、请求/响应示例、错误响应文档、安全要求、限流（rate limiting）信息。

仓库中的 cognitum-v1.openapi.yaml 可以视作该骨架的完整落地样例——从 info、paths 到 components 的层级编排与骨架一一对应。实际编写时，凡多个端点复用的模型都应抽到 components.schemas 并用 $ref 引用，这与"Use $ref for reusable components"的最佳实践一致；responses 中除了 200 还应覆盖 400/401/404/500 等错误分支（文档模板中 examples: ['200', '400', '401', '404', '500'] 正是此意）。

六、自学习协议：Before / During / After 三阶段闭环

2.0.0-alpha 版用三段 TypeScript 伪代码定义了自学习协议，其底层能力由仓库中的 ReasoningBank（reasoningbank/index.ts）实现——从源码结构看，这正是 hooks 子系统中的向量模式库。

Before：检索相似模式（searchPatterns）

const similarDocs = await reasoningBank.searchPatterns({
  task: 'API documentation: ' + apiType,
  k: 5,
  minReward: 0.85
});

对应源码 ReasoningBank.searchPatterns：优先走 HNSW 索引（默认 M=16, efConstruction=200, efSearch=100，见 DEFAULT_CONFIG），失败时回退到余弦相似度暴力搜索，并统计 hnswSearchTime / bruteForceSearchTime 以计算加速比。文档里的 minReward: 0.85 对应源码中模式的质量分 quality——质量分由 calculateQuality 计算（0.3 + successRate * 0.7，区间 0.3~1.0），所以 0.85 意味着只采纳"历史上成功率很高"的文档模式。

During：GNN 增强的 API 结构搜索

const graphContext = {
  nodes: [userAPI, authAPI, productAPI, orderAPI],
  edges: [[0, 1], [2, 3], [1, 2]],
  edgeWeights: [0.9, 0.8, 0.7],
  nodeLabels: ['UserAPI', 'AuthAPI', 'ProductAPI', 'OrderAPI']
};
const similarAPIs = await agentDB.gnnEnhancedSearch(apiEmbedding, { k: 10, graphContext, gnnLayers: 3 });

即把 API 之间的关联（如 User→Auth→Product→Order）建模为图，搜索时不仅看端点自身向量相似度，还参考图结构上下文，从而找到结构相似的 API 文档作为生成蓝本。

After：存储成功模式（storePattern）

await reasoningBank.storePattern({
  sessionId: `api-docs-${Date.now()}`,
  task: `API documentation: ${apiType}`,
  output: { endpoints, schemas, examples, quality },
  reward: documentationQuality,
  success: true,
  critique: `Complete OpenAPI spec with ${endpointCount} endpoints`,
});

对应源码 ReasoningBank.storePattern：先用向量相似度去重（dedupThreshold: 0.95，相似度高于阈值则视为重复并累加 usageCount），新模式以 quality: 0.5 起步写入短时记忆（short-term），经 consolidate 或 checkPromotion 判断：当 usageCount >= promotionThreshold(3) 且 quality >= qualityThreshold(0.6) 时晋升为长时记忆（long-term），长时模式在暴力搜索中优先（Search long-term first (higher quality)）。

领域模板：文档结构知识沉淀

升级版内置了三类 API 的文档模板（Domain-Specific Optimizations）：

• REST CRUD：端点 list/get/create/update/delete，schemas Resource/ResourceList/Error，示例覆盖 200/400/401/404/500；
• Authentication：端点 login/logout/refresh/register，schemas Credentials/Token/User，安全方案 bearerAuth/apiKey；
• GraphQL：类型 Query/Mutation/Subscription，schemas Input/Output/Error，示例含 queries/mutations。

同时针对大型规范提供"快速生成"路径：当 endpointCount > 50 时调用 Flash Attention 加速向量检索，以应对大规模 API 的文档生成。

七、hooks 生命周期：pre / post / on_error 三阶段脚本

frontmatter 中的 hooks 定义了 Agent 运行生命周期的三个切面，从源码结构看，这正是 hooks 子系统（v3/@claude-flow/hooks/src/）在 Agent 层的直接体现：

pre_execution（开始前）：

• 声明启动并扫描现有路由：find . -name "*.route.js" -o -name "*.controller.js" -o -name "routes.js" | grep -v node_modules | head -10；
• 检查已有 OpenAPI 文档：find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "api.yaml"；
• 升级版追加：调用 npx claude-flow@alpha memory search-patterns "API documentation: $TASK" --k=5 --min-reward=0.85 检索相似模式，并以 status: started 记录任务开始。

post_execution（完成后）：

• 校验产物：grep -E "^(openapi:|info:|paths:)" openapi.yaml | head -5；
• 统计规模：ENDPOINT_COUNT=$(grep -c "^ /" openapi.yaml)、SCHEMA_COUNT=$(grep -c "^ [A-Z]" openapi.yaml)；
• 升级版追加：以 reward=0.9、success=true 存储模式，并在成功时执行 npx claude-flow@alpha neural train --pattern-type coordination --epochs 50 对神经模式进行训练。

on_error（出错时）：

• 提示检查 OpenAPI 规范语法；升级版追加：以 reward=0.0、success=false 存储失败模式，供未来检索时避坑。

这套"开始检索经验、结束沉淀经验、失败记录教训"的 hook 设计，让每次文档编写都成为下一次的输入——不需要额外维护文档库，模式自动积累。

八、Agent 协作关系：文档与开发的闭环

integration 字段定义了协作拓扑：

• can_delegate_to: ["analyze-api"]：可把 API 分析子任务委托给 analyze-api 分析 Agent（主文档与升级版中该字段指向同名 Agent，负责端点分析）；
• shares_context_with: ["dev-backend-api", "test-integration"]：与后端开发、集成测试 Agent 共享上下文，保证"实现—测试—文档"三者一致；
• can_spawn: []：自身不派生子 Agent，保持文档任务简单专注；
• requires_approval_from: []：无需上级审批即可自主执行。

对比 dev-backend-api.md 的协作配置（can_spawn: ["test-unit", "test-integration", "docs-api"]、can_delegate_to: ["arch-database", "analyze-security"]、requires_approval_from: ["architecture"]），可以看到：后端开发 Agent 会主动 spawn 文档子任务（docs-api），而 api-docs 自身保持单层职责——两者互为上下游，共同构成"开发产出端点 → 文档 Agent 生成规范 → 测试 Agent 校验一致性"的闭环。

九、仓库实践：把规范落到真实 OpenAPI 文件

仓库中现成的 cognitum-v1.openapi.yaml 是 api-docs 工作对象的最佳样本。对照本文第五节骨架，可以观察到完整工程化写法的要点：

1. 版本与信息头：openapi 版本号、info.title、info.version（v1 表明接口版本管理遵循"变更 API 版本需确认"的约束）；
2. 路径组织：按资源划分 paths，每个操作配 summary/description；
3. 组件复用：公共模型集中在 components 中，端点通过 $ref 引用，避免重复定义；
4. 示例与错误分支：成功响应带 example，错误响应（4xx/5xx）单独成节，与文档要素要求一致。

在 ruflo 的实际使用中，api-docs 的完整工作流为：由宿主根据触发条件唤起 → pre hook 检索历史模式与既有文档 → 按本文第五节骨架与领域模板生成 OpenAPI 3.0 规范 → post hook 校验语法并沉淀模式 → 与 dev-backend-api / test-integration 共享上下文保持三端一致。对于端点超过 50 的大型服务，可依赖 Flash Attention 快速检索路径加速生成；对于新增 API 类型，内置的 REST CRUD / Authentication / GraphQL 模板提供了可扩展的起点。

结语

api-docs Agent 定义文件展示了 ruflo 在"用 Agent 维护 API 文档"上的完整思路：用 frontmatter 声明触发、权限与生命周期，用规范骨架保证 OpenAPI 3.0 合规，用 ReasoningBank 向量模式库（reasoningbank/index.ts）实现模式自学习，再通过 hooks 与协作字段接入开发/测试闭环。理解这份定义，既是掌握 ruflo Agent 定义文件语法的入口，也是将"文档即代码、经验即资产"落到 API 工程实践的直接参考——仓库中的 cognitum-v1.openapi.yaml 即为可对照的真实样例。