RuView 的 api-docs Agent 设计：一份受控的 OpenAPI 文档专家工作流

本篇围绕 RuView 仓库中的 api-docs Agent 定义文件 展开，逐段解析这个 "OpenAPI Documentation Specialist" 智能体的触发机制、工具权限、路径约束、生命周期钩子及其内置的 OpenAPI 3.0 规范模板。读完后，你将理解 RuView 的 Claude Flow 多智能体体系中"文档类 Agent"是如何被声明、限制和调度的，并能把这套声明式 Agent 配置模式（frontmatter 元数据 + 系统提示词 + shell 钩子）迁移到自己的 API 文档维护流程中。

一、定位：Claude Flow 体系中的文档专家 Agent

该文档是 RuView 多智能体开发体系中的一个 Agent 定义文件，位于 .claude/agents/documentation/api-docs/docs-api-openapi.md，由两部分组成：

1. YAML frontmatter：声明 Agent 的身份（name: "api-docs"、version: "1.0.0"、type: "documentation"）、触发条件、可用工具、资源与路径约束、行为策略、协作关系、优化参数以及生命周期钩子；
2. Markdown 系统提示词：定义 Agent 的职责清单、最佳实践、OpenAPI 3.0 规范骨架和必须覆盖的文档要素。

从仓库整体结构看，该 Agent 属于 Claude Flow 智能体编队中的"专业开发"分组。.claude-flow/CAPABILITIES.md 中的 Agent 路由表明确给出了任务类型到 Agent 的映射：

任务类型	推荐 Agent	拓扑
Docs	researcher, api-docs	mesh

也就是说，当任务被判定为文档类工作时，api-docs 会与 researcher 一起、以 mesh 拓扑被调度，负责其中的 OpenAPI/API 文档部分。

仓库中还存在一份同名的进阶版本 .claude/agents/documentation/docs-api-openapi.md（version: "2.0.0-alpha"），在前者基础上增加了"模式学习"钩子（调用 claude-flow memory store-pattern 沉淀文档经验），本文以 v1.0.0 文件为主体，末尾会给出两者差异对照。

二、触发机制：四类条件决定何时唤起 api-docs

frontmatter 的 triggers 段定义了 Agent 被路由到的四种匹配条件：

字段	取值	含义
keywords	api documentation、openapi、swagger、api docs、endpoint documentation	用户指令中出现这些关键词时命中
file_patterns	**/openapi.yaml、**/swagger.yaml、**/api-docs/**、**/api.yaml	任务涉及这些 glob 模式的文件时命中
task_patterns	document * api、create openapi spec、update api documentation	任务描述匹配时命中
domains	documentation、api	任务领域归属时命中

metadata 段同时标注了该 Agent 的能力画像：specialization: "OpenAPI 3.0 specification, API documentation, interactive docs"、complexity: "moderate"、autonomous: true（可自主执行，无需逐步确认）。

三、工具与资源边界：能读能写，但不能执行

capabilities 段对 Agent 的行动空间做了精确裁剪：

capabilities:
  allowed_tools:
    - Read
    - Write
    - Edit
    - MultiEdit
    - Grep
    - Glob
  restricted_tools:
    - Bash  # No need for execution
    - Task  # Focused on documentation
    - WebSearch
  max_file_operations: 50
  max_execution_time: 300
  memory_access: "read"

设计意图很明确：

• 允许集覆盖"阅读代码 + 编辑文档"的最小闭环：Read/Grep/Glob 用于从源码和路由文件中提取端点信息，Write/Edit/MultiEdit 用于产出和修订 YAML/Markdown 规格；
• 受限集禁用了 Bash（注释写明 "No need for execution"——文档 Agent 不应在仓库中执行任意命令）、Task（不再递归派生子任务，保持职责单一）和 WebSearch（禁止引入外部不确定信息）；
• 配额：最多 50 次文件操作、单任务最长 300 秒、记忆库只读（memory_access: "read"），从数量和时间两个维度防止文档任务失控。

四、路径与文件类型约束：只碰文档，不碰源码和密钥

constraints 段进一步把活动范围收窄到文档目录：

constraints:
  allowed_paths:
    - "docs/**"
    - "api/**"
    - "openapi/**"
    - "swagger/**"
    - "*.yaml"
    - "*.yml"
    - "*.json"
  forbidden_paths:
    - "node_modules/**"
    - ".git/**"
    - "secrets/**"
  max_file_size: 2097152  # 2MB
  allowed_file_types:
    - ".yaml"
    - ".yml"
    - ".json"
    - ".md"

结合 allowed_paths 中的通配 yaml/yml/json 规则可以推断：该 Agent 可以读取仓库根下任意位置的 YAML/JSON 配置（例如路由定义、现有 openapi.yaml）来"取材"，但对源码树的常规目录（如 src/** 下的 .py/.rs 文件）并不在其写入白名单内；forbidden_paths 则硬性排除依赖目录、版本库内部和 secrets/，避免文档生成过程触碰敏感信息。max_file_size: 2097152（2MB）限制单次处理的文件体积，防止超大产物拖垮后续校验。

五、行为策略与协作关系

行为与沟通

behavior:
  error_handling: "lenient"
  confirmation_required:
    - "deleting API documentation"
    - "changing API versions"
  auto_rollback: false
  logging_level: "info"
communication:
  style: "technical"
  update_frequency: "summary"
  include_code_snippets: true
  emoji_usage: "minimal"

• error_handling: lenient 表示遇到非致命错误（如单个端点描述缺失）时继续推进，而不是中断整个文档任务；
• confirmation_required 列出两个必须人工确认的高危操作：删除 API 文档和变更 API 版本号——这是典型的"破坏性操作二次确认"设计；
• 沟通风格为技术化表达、按摘要频率汇报、允许附带代码片段、极少使用 emoji。

协作与优化参数

integration:
  can_spawn: []
  can_delegate_to:
    - "analyze-api"
  requires_approval_from: []
  shares_context_with:
    - "dev-backend-api"
    - "test-integration"
optimization:
  parallel_operations: true
  batch_size: 10
  cache_results: false
  memory_limit: "256MB"

从该声明看：api-docs 自身不派生新 Agent（can_spawn: []），但可以把"API 分析"子任务委托给 analyze-api；它与后端开发 Agent dev-backend-api 和集成测试 Agent test-integration 共享上下文——这条共享链暗示了实际工作流：后端开发 Agent 产出路由与接口，api-docs 消费同一上下文生成规格，集成测试 Agent 再依据规格验证。优化参数允许 10 个一批的并行文件操作，但不开结果缓存（文档内容易变，缓存收益低），内存上限 256MB。

六、生命周期钩子：三个 shell 脚本串起执行流程

hooks 段声明了 pre/post/error 三个 shell 钩子，是这份 Agent 定义中最具"可运行性"的部分。

pre_execution：先盘点现有路由与已有规格

echo "📝 OpenAPI Documentation Specialist starting..."
echo "🔍 Analyzing API endpoints..."
# Look for existing API routes
find . -name "*.route.js" -o -name "*.controller.js" -o -name "routes.js" | grep -v node_modules | head -10
# Check for existing OpenAPI docs
find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "api.yaml" | grep -v node_modules

执行前先做两件事的侦察：一是按 *.route.js / *.controller.js / routes.js 三种命名约定找出 API 路由文件（取前 10 个），二是检查是否已存在 openapi.yaml、swagger.yaml、api.yaml——若已存在则走"增量更新"而非"从零创建"路径。

post_execution：对产出的规格做基本校验

echo "✅ API documentation completed"
echo "📊 Validating OpenAPI specification..."
# Check if the spec exists and show basic info
if [ -f "openapi.yaml" ]; then
  echo "OpenAPI spec found at openapi.yaml"
  grep -E "^(openapi:|info:|paths:)" openapi.yaml | head -5
fi

收尾时用 grep -E "^(openapi:|info:|paths:)" 抽查三个一级键是否齐备。这是最轻量的规格完整性检查（不是完整 schema 校验，但能拦截"文件缺失关键段"这类低级错误）。

on_error：错误提示与人工排查指引

echo "⚠️ Documentation error: {{error_message}}"
echo "🔧 Check OpenAPI specification syntax"

错误钩子只做提示并给出排查方向（检查 YAML 语法），与 error_handling: lenient 的策略一致：报错不自动回滚（auto_rollback: false），交给后续人工或下一轮任务修正。

frontmatter 末尾的 examples 段还给了两条标准问答样例（"create OpenAPI documentation for user API" / "document REST API endpoints"），用于校准 Agent 的响应口径：承诺产出包含全部端点、schema 和示例的完整 3.0 规格。

七、内置 OpenAPI 3.0 规范模板与文档要素

系统提示词部分（文档正文）定义了 Agent 的五项核心职责：

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

配套的 OpenAPI 结构骨架如下（即该 Agent 被要求产出/维护的规格形态）：

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

最佳实践清单要求：描述性的 summary/description、成对的请求/响应示例、覆盖所有可能的错误响应码、用 $ref 复用 components 中的可复用结构、严格遵循 3.0 规范、用 tags 对端点做逻辑分组。最后还列出了四到五个"文档要素"检查项：清晰的 operationId、请求/响应示例、错误响应文档、安全要求（Security requirements）以及限流信息（Rate limiting information）——这几项正好对应后端服务常见的横切关注点。

八、仓库实证：RuView 实际如何生成与发布 OpenAPI 规格

Agent 定义描述的是"谁负责写文档"，而仓库的 CI 流水线展示了"规格如何真正落地产物化"，两者形成互补。

.github/workflows/ci.yml 中有一个名为 API Documentation 的 docs job（约 L453-L499），仅在 main 分支、依赖 docker-build 成功后运行，核心步骤是：

- name: Generate OpenAPI spec
  working-directory: archive/v1
  env:
    MOCK_POSE_DATA: "true"   # no CSI hardware in CI
  run: |
    python -c "
    from src.api.main import app
    import json
    with open('openapi.json', 'w') as f:
      json.dump(app.openapi(), f, indent=2)
    "

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453
  continue-on-error: true
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./docs
    destination_dir: api-docs

可以看到实际产物链路：

1. 在 archive/v1/src/api/main.py 定义 FastAPI app 后，直接调用 app.openapi() 在 CI 中即时导出 openapi.json——也就是说规格由框架从路由定义自动生成，而非纯手工维护；
2. 生成的规格随 docs 目录发布到 GitHub Pages 的 api-docs 子目录；
3. 部署步骤标记 continue-on-error，CI 注释明确说明"生成 openapi.json 才是真正的校验，Pages 部署是尽力而为"。

服务侧的证据也与"OpenAPI 是公开只读面"这一定位一致：archive/v1/src/config/settings.py 中 openapi_url 的默认值即 "/openapi.json"；archive/v1/src/api/middleware/auth.py 与 archive/v1/src/middleware/rate_limit.py 都把 /openapi.json 列入免认证/免限流的公共路由，保证规格本身可被任何人无需凭据拉取。这与 api-docs Agent "产出公开可交互 API 文档"的职责完全对齐。

九、版本对照：v1.0.0 与 v2.0.0-alpha 的差异

同目录体系下的 docs-api-openapi.md 是同一 Agent 的 2.0.0-alpha 变体，metadata.v2_capabilities 标注了四项新能力（self_learning、context_enhancement、fast_processing、smart_coordination）。相对 v1.0.0 的主要增量都在钩子里：

• pre_execution 增加 claude-flow memory search-patterns：按 min-reward=0.85 检索历史文档模式作为先验模板；
• post_execution 统计端点数/schema 数（grep -c "^ /"），以固定 reward=0.9 调用 memory store-pattern 沉淀本次结果，成功时触发 neural train（50 epochs）；
• on_error 同样以 reward=0.0 存储失败模式。

v1.0.0（本文主体）不含上述学习闭环，是一套"无状态、纯规则驱动"的文档 Agent；v2 则尝试让文档生成从历史成功案例中复用模板。若只需确定性的文档维护行为，v1 定义更简单可控。

十、关键参数速查

参数	值	作用
max_file_operations	50	单任务文件操作上限
max_execution_time	300	单任务时长上限（秒）
max_file_size	2097152	单文件处理上限（2MB）
memory_access	read	记忆库只读
error_handling	lenient	非致命错误不中断
confirmation_required	删文档 / 改 API 版本	破坏性操作需确认
batch_size / memory_limit	10 / 256MB	并行批大小 / 内存上限
can_delegate_to	analyze-api	唯一的可委托对象

小结：RuView 的 api-docs Agent 定义展示了"声明式 Agent"的一个完整样本——用 frontmatter 声明触发条件、工具白名单、路径围栏、配额与钩子，用系统提示词固定产出物标准（OpenAPI 3.0 骨架 + 文档要素清单），再与 CI 中 FastAPI 自动导出的规格生成流程配合，构成"Agent 维护文档规范、流水线物化规格"的双轨 API 文档体系。理解这套结构后，可以为任意语言栈的项目套用同样的 Agent 定义范式来治理 API 文档。