Ruflo 的 $agent-docs-api-openapi：面向 Codex CLI 的 OpenAPI 文档智能体技能深度解析

在 Ruflo（Claude Flow 系多智能体编排平台）仓库中，.agents/ 目录承载了面向 OpenAI Codex CLI 的完整技能（Skill）体系，其中 agent-docs-api-openapi 技能 是一个专职负责创建与维护 OpenAPI 3.0 / Swagger 文档的"专家型"智能体技能。本文以该技能的 SKILL.md 为骨架，逐字段解析它的触发条件、能力边界、沙箱约束、生命周期钩子与协作关系，并结合 Codex 模板源码 与 SKILL.md 生成器 说明该技能在 Ruflo 技能体系中的分发机制，读完后可完整理解"如何用一个声明式 YAML 定义一个受控的文档智能体，并用 $agent-docs-api-openapi 语法在 Codex CLI 中调用它"。

1. 技能在 Ruflo 仓库中的定位

Ruflo 支持跨智能体运行（Claude Code、Codex、Copilot 等），其 根 SKILL.md 说明项目以 npx ruflo <command> 的形式运行，技能目录则按目标智能体分派：Codex CLI 使用 .agents/ 目录。.agents/README.md 给出了标准目录结构：

.agents/
  config.toml     # Main configuration file
  skills/         # Skill definitions
    skill-name/
      SKILL.md    # Skill instructions
      scripts/    # Optional scripts
      docs/       # Optional documentation

关键规则是：技能通过 $skill-name 语法调用，每个技能由一段"带 YAML frontmatter 元数据的 SKILL.md"组成，并声明触发条件、跳过条件、命令与示例。而项目级配置 config.toml 控制模型选择、审批策略、沙箱模式、MCP 连接与技能开关。在 Ruflo 中，agent-docs-api-openapi 只是 .agents/skills/ 下约 140 个技能目录之一（同级的还有 agent-coder、agent-reviewer、agent-dev-backend-api 等），它属于模板常量中被标注为 "Agent skills (converted from Claude Code agents)" 的一类——即从 Claude Code 的 agent 定义转写而来的技能。

1.1 技能如何进入 Codex 初始化流程

模板源码 v3/@claude-flow/codex/src/templates/index.ts 中的 ALL_AVAILABLE_SKILLS 数组列出了初始化时可分发的全部技能，agent-docs-api-openapi 位于其中（第 152 行）。该文件同时定义了四档模板：

模板	说明	技能数量
minimal	仅核心技能	2
default	常用技能	4
full	全量技能（137+）	137
enterprise	全量 + 治理	137

其中只有 full 与 enterprise 模板会带上 agent-docs-api-openapi（DEFAULT_SKILLS_BY_TEMPLATE 中 full: ALL_AVAILABLE_SKILLS）。同一文件里的 PLATFORM_MAPPING 还明确了两大平台的差异：Claude Code 的技能调用语法是 /skill-name，而 Codex 是 $skill-name；Claude Code 的配置载体是 CLAUDE.md（JSON settings），Codex 是 AGENTS.md（TOML config）。因此在 Codex CLI 中，本文主题技能的调用形式就是：

$agent-docs-api-openapi

1.2 文件布局与本地覆盖

DIRECTORY_STRUCTURE 常量描述了完整的落盘结构：.agents/config.toml（项目级 Codex 配置）、.agents/skills/（技能定义）、.codex/config.toml（用户级本地覆盖，gitignored）、.claude-flow/（运行时数据）。这解释了为何 config.toml 里既有 sandbox_mode、approval_policy 等全局策略，又能在 [profiles.dev]、[profiles.safe]、[profiles.ci] 中按场景切换审批与沙箱强度——文档智能体的受控行为正是叠加在这一层平台配置之上生效的。

2. SKILL.md 的文件结构：frontmatter 与"legacy YAML"块

SKILL.md 整体分为三部分：

1. YAML frontmatter（技能元数据）：

---
name: agent-docs-api-openapi
description: Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi
---

frontmatter 极简：name 是技能 ID（即 .agents/skills/ 下的目录名，与调用语法 $name 一致），description 直接提示了调用方式。这种"目录名 = 技能 ID = 调用名"的约定在 skill-md.ts 生成器 中得到印证：generateSkillMd() 渲染的 frontmatter 首字段就是 name，正文标题由 formatSkillName(name) 按连字符拆分并首字母大写生成。

2. legacy agent-definition YAML 块（第 6～127 行）：这是技能最核心的机器可读定义。文件里有一段注释解释它为何被包在 yaml 代码栅栏中——历史上它是第二个 --- 围栏块，但渲染器（skills.sh、GitHub web 视图）把第二个 --- 当成水平分割线，导致原始 YAML 被直接倾倒进页面正文（仓库标注为 issue #2469）。因此现在用 ```yaml 代码块包裹，"既按代码渲染，又保持机器可读"。

3. Markdown 正文（第 129 行起）：面向执行者的系统提示（system prompt），包含职责、最佳实践、OpenAPI 结构模板与文档要素清单。

这种"元数据 + 机器定义 + 执行提示"的三段式结构，是 Ruflo 全部 agent 技能的通用形态。

3. 智能体定义逐字段解析

下面把 legacy YAML 块按逻辑分组完整拆解，这是该技能真正的"配置面"。

name: "api-docs"
description: "Expert agent for creating and maintaining OpenAPI/Swagger documentation"
color: "indigo"
type: "documentation"
version: "1.0.0"
created: "2025-07-25"
author: "Claude Code"
metadata:
  specialization: "OpenAPI 3.0 specification, API documentation, interactive docs"
  complexity: "moderate"
  autonomous: true

• name: "api-docs" 是智能体身份名（供 can_spawn/can_delegate_to 引用的短名），与技能 ID agent-docs-api-openapi 不同，二者分属"调度层"与"文件系统层"两套命名；
• type: "documentation" 与 color: "indigo" 用于编排 UI 的展示与分类；
• autonomous: true 声明该智能体可自主推进任务，但自主边界由后文的 constraints 与 behavior 收紧。

3.1 triggers：三类触发条件

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" 等）、文件模式命中（工作区出现 openapi.yaml、swagger.yaml、api.yaml 或 api-docs/ 目录）、任务模式命中（"create openapi spec" 之类的任务短语），以及领域归属。需要说明：本仓库技能文件中的 $ 是特殊字符转义写法（同目录 agent-dev-backend-api 技能 的钩子脚本里同样以 2>$dev$null 形式出现），还原后 file_patterns 的意图是匹配任意深度下的 *openapi.yaml、*swagger.yaml、*api-docs/**、*api.yaml；task_patterns 中的 * 是通配词。阅读此类技能时按"通配/转义"理解即可，不必当作字面文件名。

3.2 capabilities：工具白名单与资源配额

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/Write/Edit/MultiEdit/Grep/Glob）——文档智能体需要读代码、写 YAML，但不需要别的；
• 禁用 Bash（"No need for execution"）、禁用 Task（专注文档、不派生子任务）、禁用 WebSearch（不依赖外部资料）；
• 配额：单次任务最多 50 次文件操作、300 秒执行时限；
• memory_access: "read" 表示对记忆库只读——它可以检索既有的 API 模式，但不能写入学习记录。

对比同族的 agent-dev-backend-api 技能：它允许 Bash 与 Task、配额放大到 100 次操作 / 600 秒、memory_access: "both"，因为后端开发需要跑测试并沉淀模式。文档智能体与开发智能体在同一 schema 下呈现出清晰的"职责—权限"梯度，这也是从源码结构看 Ruflo 智能体体系的典型设计：能力与副作用正相关地递增。

3.3 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"

围栏含义：写入只能发生在 docs/、api/、openapi/、swagger/ 目录及仓库任意位置的 *.yaml / *.yml / *.json；显式禁止触碰 node_modules/、.git/ 和 secrets/（注意 .agents/config.toml 的 [security] 段也独立配置了 blocked_patterns 拦截 .env、credentials.json、.pem、.key，两层防护叠加）。单文件上限 2MB，可操作扩展名收敛到 yaml/yml/json/md 四种——正好覆盖 OpenAPI 生态的全部载体格式。

3.4 behavior 与 communication：交互行为约定

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"：遇到个别端点解析失败时继续生成其余文档，而非整体中止（对比 backend 技能的 "strict"）；
• 仅两类操作需人工确认：删除 API 文档、变更 API 版本——其余文档生成可自动完成；
• auto_rollback: false：不回滚，因为文档是增量产物，回滚意义有限；
• 通信风格为技术性、按"摘要"频率汇报、必须附代码片段、emoji 克制——与 hooks 段里大量 emoji 提示形成对照（hooks 输出面向运维日志，communication 面向用户交互）。

3.5 integration 与 optimization：协作与性能参数

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"

这段定义了该智能体在 Ruflo 智能体图（agent graph）中的位置：

• 不能 spawn 任何子智能体（can_spawn: []），也不需要上级审批（requires_approval_from: []）——它是叶子节点；
• 可把子问题委派给 analyze-api（端点分析智能体）；
• 与 dev-backend-api、test-integration 共享上下文。这与 agent-dev-backend-api 技能 中 can_spawn: ["test-unit", "test-integration", "docs-api"] 互为镜像：后端开发智能体可以 spawn 出 docs-api（即本智能体），二者组成"实现 → 测试 → 文档"的标准流水线；
• 性能参数：允许并行操作、批大小 10、不缓存结果（cache_results: false，文档输出通常是一次性的）、内存上限 256MB。

3.6 hooks：执行前后的自动化脚本

hooks:
  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
  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
  on_error: |
    echo "⚠️ Documentation error: {{error_message}}"
    echo "🔧 Check OpenAPI specification syntax"

三段钩子的工程意图：

• pre_execution（侦察）：先 find 出路由/控制器文件（*.route.js、*.controller.js、routes.js）确定待文档化的端点范围，再探测是否已存在 openapi.yaml/swagger.yaml/api.yaml——决定"新建"还是"增量更新"；
• post_execution（验收）：确认 openapi.yaml 存在后，用 grep -E "^(openapi:|info:|paths:)" 抽查三大顶层键是否齐备，作为文档完整性的快速自检；
• on_error（诊断）：{{error_message}} 模板占位符由运行期填充，提示方向直接指向"OpenAPI 规范语法"。

值得注意的细节：该技能 restricted_tools 禁用了 Bash，但这些钩子是平台侧生命周期脚本（由 Codex 运行时按 config.toml 的 [hooks] 段执行，pre_task = true、post_task = true），与智能体自身可交互的工具白名单是两套机制——钩子提供确定性脚手架，智能体在白名单内做判断性工作。

3.7 examples：触发示例与预期应答

examples:
  - trigger: "create OpenAPI documentation for user API"
    response: "I'll create comprehensive OpenAPI 3.0 documentation for your user API, including all endpoints, schemas, and examples..."
  - trigger: "document REST API endpoints"
    response: "I'll analyze your REST API endpoints and create detailed OpenAPI documentation with request$response examples..."

examples 是 few-shot 锚点，用于让宿主智能体在路由阶段识别"这句话应该命中该技能"。（再次提示：request$response 中的 $ 为转义字符，原文意图是 "request/response examples"。）

4. 执行提示正文：职责、最佳实践与 OpenAPI 骨架

SKILL.md 的 Markdown 正文（第 129 行起）是给智能体的系统提示，结构为"角色 → 职责 → 最佳实践 → 规范骨架 → 要素清单"：

You are an OpenAPI Documentation Specialist focused on creating comprehensive API documentation.

五大核心职责（Key responsibilities）：

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

六条最佳实践（Best practices）：

• 使用描述性的 summary 与 description；
• 附请求与响应示例；
• 文档化所有可能的错误响应；
• 用 $ref（即 OpenAPI 标准 $ref）引用可复用组件；
• 严格遵循 OpenAPI 3.0 规范；
• 用 tags 对端点做逻辑分组。

OpenAPI 结构骨架（原文档给出的最小可运行模板，$ 为转义字符，还原后如下）：

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

这个骨架体现了职责与最佳实践的落地形态：servers 声明环境；paths 下每个方法带 summary/description 双层描述；响应同时给出 schema 与 example；可复用模型集中放入 components.schemas 以便 $ref 引用。

**文档要素清单（Documentation elements）**收尾：清晰的 operation ID、请求/响应示例、错误响应文档、安全要求（security requirements）、限流信息（rate limiting）——其中限流与安全正是"API 契约"区别于普通接口清单的关键部分。

5. SKILL.md 的生成与校验机制（源码级佐证）

技能文件是"手写"还是"生成"？v3/@claude-flow/codex/src/generators/skill-md.ts 给出两种路径，可帮助理解该文件的来源与约束：

1. generateSkillMd(options)：从类型化选项（name、description、version、tags、triggers、skipWhen、commands 等）渲染一个全新 SKILL.md。frontmatter 格式与本技能一致（name + description: > 折叠块，并自动并入 "Use when: ..." 触发句），正文固定为 Purpose / When to Trigger / When to Skip / Commands / Scripts / References / Best Practices 七节——agent-docs-api-openapi 这类由 Claude Code agent 转写而来的技能内容更丰富，超出了该模板的骨架，属于"以模板为起点的手工增强"。
2. generateBuiltInSkill(skillName)：对内置技能（BUILT_IN_SKILL_NAMES 中的 6 个核心技能：swarm-orchestration、memory-management、sparc-methodology、security-audit、performance-analysis、github-automation）直接从包内 .agents/skills 树读取规范定义（canonical definition），"使直接生成、项目初始化与 npm 产物三者不产生漂移"（源码注释原话）。

该模块还内置了安全校验：readPayloadTree() 拒绝技能目录中的符号链接与越界相对路径（../ 或绝对路径直接抛错），validateBuiltInSkillPayload() 则用正则抽取 SKILL.md 中所有 `scripts/...` / `references/...` 本地引用，逐一核对文件确实随技能树分发。这意味着技能文件的"自包含性"是被代码强制的——对 agent-docs-api-openapi 这类仅含单个 SKILL.md 的轻量技能，校验天然通过；而携带 scripts/、docs/ 的技能则受同等约束。

6. 实际使用方式与适用边界

结合 .agents/ 的文档与 config.toml，在 Codex CLI 中使用该技能的完整链条是：

1. 技能落位：技能文件位于 .agents/skills/agent-docs-api-openapi/SKILL.md。若项目经 Ruflo 初始化，full/enterprise 模板会把 ALL_AVAILABLE_SKILLS 中的技能（含本技能）拷贝进项目的 .agents/skills/；default 模板则只装 4 个核心技能，需要手动补充该目录。
2. 触发：在 Codex CLI 会话中直接使用 $agent-docs-api-openapi 显式调用；或在任务文本中命中 "openapi"、"swagger"、"api documentation" 等关键词，或在 openapi.yaml 等文件存在时由触发器路由命中。
3. 平台约束叠加：技能自身的 capabilities/constraints 之外，config.toml 的 sandbox_mode = "workspace-write"、approval_policy = "on-request"、[security] 段的 input_validation、path_traversal_prevention、secret_scanning、blocked_patterns 会继续生效；CI 场景可切到 [profiles.ci]（approval_policy = "never" + workspace-write）。
4. 行为预期：技能会先侦察路由文件与既有 spec（pre hook），在 docs/**、api/**、openapi/**、swagger/** 或仓库级 *.yaml/*.json 内生成/更新 OpenAPI 3.0 文档，写后抽查 openapi:/info:/paths: 顶层键（post hook）；执行中删除文档或变更 API 版本前必须向用户确认。

适用边界：该技能面向 OpenAPI 3.0 文档，max_file_size 为 2MB，不适合超大型拆分规范（multi-file spec）的跨文件重构；它不生成代码、不执行测试（Bash/Task 被禁），验证手段仅限于钩子里的文本级抽查。若需要端点级语义分析，按 can_delegate_to: ["analyze-api"] 的设计，应由编排层委派专门的 API 分析智能体完成。

7. 小结

agent-docs-api-openapi 是 Ruflo 智能体技能体系的一个标准样本：一个 SKILL.md 同时承担了技能注册信息（frontmatter）、机器可读的智能体契约（legacy YAML 块：触发、工具白名单、路径围栏、确认点、钩子、协作关系、性能配额）与执行提示（OpenAPI 3.0 职责与最佳实践）三重角色。它通过 templates/index.ts 的技能清单随 full/enterprise 模板分发，通过 skill-md.ts 的 payload 校验保证自包含性，并通过与 dev-backend-api、test-integration 的上下文共享嵌入"实现—测试—文档"流水线。对维护者而言，理解这套字段语义（尤其是 triggers 的四维触发、capabilities 的工具白名单与 constraints 的路径围栏）就能照着同一 schema 写出新的领域专家技能；对使用者而言，记住 $agent-docs-api-openapi 的调用语法与它的两条确认红线（删文档、改版本），即可在 Codex CLI 中安全地用它产出可交互的 API 文档。