RuView OpenAPI 文档智能体：一个带模式学习的 API 文档自动化 Agent 设计全解

本文以 RuView 仓库中的智能体定义文件 docs-api-openapi.md 为主体，完整拆解这个「OpenAPI Documentation Specialist」Agent 的元数据结构、触发机制、权限与路径约束、执行钩子中的模式学习流水线，以及它所承载的 OpenAPI 3.0 规范骨架与最佳实践。读完后你将能够：独立设计一个受约束的文档类 Agent 定义文件，理解 pre_execution / post_execution / on_error 钩子如何把「历史文档模式」沉淀为可复用的生成模板，并掌握一份可复制的 OpenAPI 3.0 规格结构与文档要素清单。

1. 这个 Agent 在 RuView 仓库中的位置

RuView 是一个基于 WiFi/RF 信号的空间感知系统，生产实现位于 v2/crates，同时在仓库中维护了一套完整的 Claude Code / Codex 智能体工作流。仓库根目录的 CLAUDE.md 和 AGENTS.md 定义了全局协作契约（例如：证据必须可溯源、权限默认最小化、生成的产物需经审查才能进入规范语料），而 .claude/agents/ 目录则存放了按领域划分的专项智能体定义，documentation/ 子目录下就是这个 OpenAPI 文档专家：

• 当前版本：docs-api-openapi.md（frontmatter 中 version: "2.0.0-alpha"，updated: 2025-12-03）
• 旧版本留档：api-docs/docs-api-openapi.md（version: "1.0.0"，创建于 2025-07-25）

两份文件对比可以看出演进脉络：1.0.0 是一个纯粹的「文档生成器」；2.0.0-alpha 在其基础上增加了 v2_capabilities（self_learning、context_enhancement、fast_processing、smart_coordination）、钩子中的模式检索与存储逻辑，以及正文中的完整自学习协议。本文以 2.0.0-alpha 为主体展开。

该文件由两部分组成：文件头 YAML frontmatter（Agent 的「运行合同」）和 Markdown 正文（Agent 的「人设与技能手册」）。两者缺一不可：frontmatter 决定 Agent 何时被触发、能用什么工具、能碰哪些文件；正文决定它如何组织一次文档生成任务。

2. Frontmatter 详解：一个文档 Agent 的运行合同

2.1 身份与元数据

name: "api-docs"
description: "Expert agent for creating OpenAPI documentation with pattern learning"
color: "indigo"
type: "documentation"
version: "2.0.0-alpha"
created: "2025-07-25"
updated: "2025-12-03"
author: "Claude Code"
metadata:
  description: "Expert agent for creating OpenAPI documentation with pattern learning"
  specialization: "OpenAPI 3.0, API documentation, pattern-based generation"
  complexity: "moderate"
  autonomous: true
  v2_capabilities:
    - "self_learning"
    - "context_enhancement"
    - "fast_processing"
    - "smart_coordination"

几个关键字段值得注意：

• autonomous: true 表示该 Agent 可以自主完成任务而不必每步确认；
• complexity: "moderate" 是其任务复杂度的自我标注；
• v2_capabilities 声明了 v2 能力面——自学习、上下文增强、快速处理与智能协调，这四项与后文钩子和正文中的实现一一对应。

2.2 触发机制：什么时候该轮到它出场

triggers:
  keywords:
    - "api documentation"
    - "openapi"
    - "swagger"
    - "api docs"
    - "endpoint documentation"
  file_patterns:
    - "**/openapi.yaml"
    - "**/swagger.yaml"
    - "**/api-docs/**"
    - "**/api.yaml"
  task_patterns:
    - "document * api"
    - "create openapi spec"
    - "update api documentation"
  domains:
    - "documentation"
    - "api"

触发条件分四层：用户话语中的关键词（如 openapi、swagger）、被触碰的文件 glob（任何 openapi.yaml / swagger.yaml / api.yaml）、任务描述模式（create openapi spec 之类），以及领域标签。四层互为补充，使 Agent 调度器能在「用户提到了 API 文档」或「用户正在编辑 openapi.yaml」两种场景下都能命中。

2.3 能力边界：给文档 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"

这里体现了仓库 CLAUDE.md 中「默认只读、最小权限」原则在 Agent 粒度上的落地：

• 只允许读（Read/Grep/Glob）与写（Write/Edit/MultiEdit）文件，明确限制 Bash（无需执行）、Task（聚焦文档不派发子任务）、WebSearch；
• 硬预算：最多 50 次文件操作、300 秒执行时间上限；
• memory_access: "read" 表示它只能读记忆库、不能直接改写记忆——模式的写入只能通过钩子中的受控命令完成（见第 4 节）。

2.4 路径与文件类型约束

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"

写入面被收窄到 docs/**、api/**、openapi/**、swagger/** 以及顶层的 YAML/JSON 文件；node_modules、.git、secrets 被显式禁写；单文件上限 2MB（2097152 字节）。结合 CLAUDE.md 中「绝不提交凭据、.env、原始转录或私有记忆」的硬性规则，这套约束保证了文档 Agent 的输出不会越界触碰机密目录。

2.5 行为、通信与协作

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"
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 文档、变更 API 版本号——这是文档领域的典型破坏性操作；
• 出错策略是 lenient（容忍性处理）且不自动回滚，配合 logging_level: info 保留排查信息；
• 通信风格为技术性、按摘要频率汇报、允许贴代码片段、少用 emoji；
• 它不能再孵化子 Agent（can_spawn: []），但可以把工作委托给 analyze-api，并与后端开发、集成测试两个 Agent 共享上下文——这形成了「后端开发 → 文档 → 集成测试」的最小协作链；
• 优化参数：并行操作开启、批大小 10、不缓存结果（文档场景结果复用价值低）、256MB 内存上限。

3. 执行钩子：把「历史文档模式」接进 Agent 生命周期

hooks 段是 2.0.0-alpha 的核心增量，包含 pre_execution、post_execution、on_error 三个 shell 钩子。

3.1 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

# 🧠 v3.0.0-alpha.1: Learn from past documentation patterns
SIMILAR_DOCS=$(npx claude-flow@alpha memory search-patterns "API documentation: $TASK" --k=5 --min-reward=0.85 2>/dev/null || echo "")
if [ -n "$SIMILAR_DOCS" ]; then
  echo "📚 Found similar successful documentation patterns"
  npx claude-flow@alpha memory get-pattern-stats "API documentation" --k=5 2>/dev/null || true
fi

# Store task start
npx claude-flow@alpha memory store-pattern \
  --session-id "api-docs-$(date +%s)" \
  --task "Documentation: $TASK" \
  --input "$TASK_CONTEXT" \
  --status "started" 2>/dev/null || true

逻辑分三步：

1. 现状盘点：find 出仓库里已有的路由文件（*.route.js、*.controller.js、routes.js）和已有规格文件（openapi.yaml、swagger.yaml、api.yaml），避免重复造文档；
2. 模式检索：调用 claude-flow@alpha memory search-patterns，以 "API documentation: $TASK" 为查询键，取 top-k=5 且质量分（reward）不低于 0.85 的历史文档模式；命中后再用 get-pattern-stats 拉取统计；
3. 落启动记录：store-pattern --status started 以秒级时间戳为 session-id，把任务上下文写入模式记忆，为结束时的闭环统计做铺垫。

所有外部命令都带 2>/dev/null || echo "" / || true 兜底——记忆服务不可用时任务继续降级执行，这与 CLAUDE.md 中「Ruflo 不可用时用本地源码检查继续并报告降级」的处理风格一致。

3.2 post_execution：校验规格并沉淀模式

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

ENDPOINT_COUNT=$(grep -c "^  /" openapi.yaml 2>/dev/null || echo "0")
SCHEMA_COUNT=$(grep -c "^    [A-Z]" openapi.yaml 2>/dev/null || echo "0")
REWARD="0.9"
SUCCESS="true"

npx claude-flow@alpha memory store-pattern \
  --session-id "api-docs-$(date +%s)" \
  --task "Documentation: $TASK" \
  --output "OpenAPI spec with $ENDPOINT_COUNT endpoints, $SCHEMA_COUNT schemas" \
  --reward "$REWARD" \
  --success "$SUCCESS" \
  --critique "Comprehensive documentation with examples and schemas" 2>/dev/null || true

# Train neural patterns on successful documentation
if [ "$SUCCESS" = "true" ]; then
  npx claude-flow@alpha neural train \
    --pattern-type "coordination" \
    --training-data "$TASK_OUTPUT" \
    --epochs 50 2>/dev/null || true
fi

结束钩子做三件事：

1. 轻量校验：确认 openapi.yaml 存在，grep 出 openapi:、info:、paths: 三个顶层键，快速验证结构完整性；
2. 量化输出并归档：用 grep -c "^ /" 数端点数、grep -c "^ [A-Z]" 数 schema 数，连同固定的 reward（此处脚本里写死 0.9）和 success 标记存入模式库；
3. 触发训练：成功时调用 neural train --pattern-type coordination --epochs 50，把本次任务输出作为训练数据。

3.3 on_error：失败也要入档

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

npx claude-flow@alpha memory store-pattern \
  --session-id "api-docs-$(date +%s)" \
  --task "Documentation: $TASK" \
  --output "Failed: {{error_message}}" \
  --reward "0.0" \
  --success "false" \
  --critique "Error: {{error_message}}" 2>/dev/null || true

失败路径以 reward 0.0 入库——这意味着检索端 --min-reward=0.85 的门槛天然会把失败模式过滤掉，只有被验证过的成功文档结构才能作为模板被复用。{{error_message}} 是钩子框架的模板占位符，由调度器在执行失败时注入。

4. 正文自学习协议：Before / During / After 三阶段

Markdown 正文（Agent 实际接收的系统提示）把钩子脚本的行为翻译成 TypeScript 伪代码协议，分三个阶段描述。

4.1 Before：从模式库学习历史文档结构

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

if (similarDocs.length > 0) {
  similarDocs.forEach(pattern => {
    console.log(`- ${pattern.task}: ${pattern.reward} quality score`);
    console.log(`  Structure: ${pattern.output}`);
  });

  // Extract documentation templates
  const bestTemplates = similarDocs
    .filter(p => p.reward > 0.9)
    .map(p => extractTemplate(p.output));
}

对应钩子中的 search-patterns --k=5 --min-reward=0.85。注意这里有两道阈值：检索门槛 0.85 决定「哪些历史模式可见」，模板提取门槛 0.9 决定「哪些模式够格直接当模板」——分层过滤让复用只发生在高质量产出上。

4.2 During：GNN 增强的相似 API 结构检索

const graphContext = {
  nodes: [userAPI, authAPI, productAPI, orderAPI],
  edges: [[0, 1], [2, 3], [1, 2]], // API relationships
  edgeWeights: [0.9, 0.8, 0.7],
  nodeLabels: ['UserAPI', 'AuthAPI', 'ProductAPI', 'OrderAPI']
};

const similarAPIs = await agentDB.gnnEnhancedSearch(
  apiEmbedding,
  { k: 10, graphContext, gnnLayers: 3 }
);

文档以一段注释说明「Use GNN to find similar API structures (+12.4% accuracy)」——这个数字是文档自身给出的能力描述，应视为 Agent 声明而非仓库实测结论（CLAUDE.md 也要求性能类表述必须标注 MEASURED/CLAIMED/SYNTHETIC）。从源码结构看，该段的核心思想是：把仓库中各 API 子域建成图（节点为 API 模块、边为依赖关系、边权为关联强度），用图神经网络在嵌入空间做 top-10 近邻检索，为当前要写的端点找到结构最相近的历史端点作为参考。

4.3 After：把本次产出存回模式库

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

与 shell 钩子相比，正文协议多记录了 tokensUsed 与 latencyMs 两个成本维度——模式库因此不仅能回答「哪种文档结构质量高」，还能比较「哪种结构生成得快、省 token」。

4.4 领域模板与快速生成

文档进一步给出按 API 类型组织的模板结构：

const docTemplates = {
  'REST CRUD': {
    endpoints: ['list', 'get', 'create', 'update', 'delete'],
    schemas: ['Resource', 'ResourceList', 'Error'],
    examples: ['200', '400', '401', '404', '500']
  },
  'Authentication': {
    endpoints: ['login', 'logout', 'refresh', 'register'],
    schemas: ['Credentials', 'Token', 'User'],
    security: ['bearerAuth', 'apiKey']
  },
  'GraphQL': {
    types: ['Query', 'Mutation', 'Subscription'],
    schemas: ['Input', 'Output', 'Error'],
    examples: ['queries', 'mutations']
  }
};

const template = await reasoningBank.searchPatterns({
  task: `API documentation: ${apiType}`,
  k: 1,
  minReward: 0.9
});

这三类模板（CRUD、认证、GraphQL）给出了每类 API 的标准端点集、必备 schema 与必须覆盖的状态码/示例集——例如 CRUD 必须覆盖 200/400/401/404/500 五类响应，认证类必须声明 bearerAuth 或 apiKey 安全方案。取模板时用 k: 1, minReward: 0.9，即「只取唯一且高分的最优模板」。

针对大型规格，文档还描述了一条快速路径：端点数超过 50 时切换到 Flash Attention 检索（注释中声明 "2.49x-7.47x faster"，同样属于文档自身的性能声明）：

if (endpointCount > 50) {
  const result = await agentDB.flashAttention(
    queryEmbedding, endpointEmbeddings, endpointEmbeddings
  );
}

5. OpenAPI 3.0 规格骨架与文档要素

正文最后给出了该 Agent 产出物应遵循的规格骨架，这也是任何手工编写 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: 3.0.0）、API 元信息（info）、部署地址（servers）、路径与操作（paths，其中每个操作带 summary/description/parameters/responses）、响应内容（content 下声明 MIME 类型、schema 与 example）、可复用组件（components.schemas，配合 $ref 引用）。

Agent 的职责清单与最佳实践与之配套：

• 职责：产出符合 OpenAPI 3.0 的规格；为每个端点写描述和示例；准确定义请求/响应 schema；包含认证与安全方案；为每个操作提供清晰示例；（v2 新增）学习历史文档模式、用 GNN 找相似 API 结构、存储文档模板供复用；
• 最佳实践：描述性 summary/description、请求与响应示例齐全、穷尽所有可能的错误响应、可复用组件一律 $ref、严格遵循 OpenAPI 3.0 规范、用 tags 按逻辑分组端点；
• 文档要素：清晰的 operationId、请求/响应示例、错误响应文档、安全要求、限流（rate limiting）信息。

6. 工程细节：从 1.0.0 到 2.0.0-alpha 的演进证据

同目录留档的 1.0.0 版本 api-docs/docs-api-openapi.md 提供了很好的对照基线：

维度	1.0.0	2.0.0-alpha
触发器	相同（keywords/file_patterns/task_patterns/domains 完全一致）	相同
工具与约束	相同（6 个允许工具、3 个受限工具、50 次操作、300 秒）	相同
钩子	仅有现状盘点 + 规格校验	增加模式检索、启动记录、模式归档、neural 训练、失败入档
正文	仅职责清单 + 最佳实践 + 规格骨架	增加三阶段自学习协议、领域模板、快速生成路径

可见演进策略是「触发面与权限面保持稳定，学习面持续加厚」——安全边界（工具白名单、路径禁写、2MB 上限）在两版间一字未动，这正是 CLAUDE.md 中「学习晋升需要显式授权、生成物不得自我晋升」原则在 Agent 配置层的体现：Agent 的能力扩展只发生在「读记忆 → 写记忆」这条受控通道内。

7. 如何阅读与扩展这份 Agent 配置

如果你要在自己的项目中复现或改造这个文档 Agent，可以按以下路径在 RuView 仓库中核对实现：

1. 定义文件本体：docs-api-openapi.md，先看 frontmatter 再读正文，确认「合同」与「手册」一致；
2. 旧版本对照：api-docs/docs-api-openapi.md，用于理解各字段的增量来源；
3. 全局协作规则：CLAUDE.md 与 AGENTS.md，其中「最小权限」「证据必须 MEASURED/CLAIMED/SYNTHETIC 标注」「默认只读」是理解该 Agent 为何限制 Bash、为何记忆写入只走钩子的关键背景；
4. 同层其他领域 Agent（.claude/agents 下的 analysis、development、testing 等目录）可以作为「同类文档结构」的横向参照。

改造时的两条经验性边界：其一，任何新增写路径都必须与 forbidden_paths 做交集检查，机密目录（secrets/**、.git/**）永不允许出现在 allowed_paths 中；其二，模式检索的 min-reward 门槛（0.85/0.9 两层）是质量闸门，放宽它会直接把历史失败结构引入生成过程——这套钩子设计的精髓，就是用「失败以 0 分入库 + 检索设门槛」两个机制保证只有被验证过的文档模板才会被复用。