ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

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

RuView 的 api-docs Agent 设计:一份受控的 OpenAPI 文档专家工作流 RuView 的 api-docs Agent 设计一份受控的 OpenAPI 文档专家工作流【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView本篇围绕 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由两部分组成YAML frontmatter声明 Agent 的身份name: api-docs、version: 1.0.0、type: documentation、触发条件、可用工具、资源与路径约束、行为策略、协作关系、优化参数以及生命周期钩子Markdown 系统提示词定义 Agent 的职责清单、最佳实践、OpenAPI 3.0 规范骨架和必须覆盖的文档要素。从仓库整体结构看该 Agent 属于 Claude Flow 智能体编队中的专业开发分组。.claude-flow/CAPABILITIES.md中的 Agent 路由表明确给出了任务类型到 Agent 的映射任务类型推荐 Agent拓扑Docsresearcher, api-docsmesh也就是说当任务被判定为文档类工作时api-docs会与researcher一起、以 mesh 拓扑被调度负责其中的 OpenAPI/API 文档部分。仓库中还存在一份同名的进阶版本.claude/agents/documentation/docs-api-openapi.mdversion: 2.0.0-alpha在前者基础上增加了模式学习钩子调用claude-flow memory store-pattern沉淀文档经验本文以 v1.0.0 文件为主体末尾会给出两者差异对照。二、触发机制四类条件决定何时唤起 api-docsfrontmatter 的triggers段定义了 Agent 被路由到的四种匹配条件字段取值含义keywordsapi documentation、openapi、swagger、api docs、endpoint documentation用户指令中出现这些关键词时命中file_patterns**/openapi.yaml、**/swagger.yaml、**/api-docs/**、**/api.yaml任务涉及这些 glob 模式的文件时命中task_patternsdocument * api、create openapi spec、update api documentation任务描述匹配时命中domainsdocumentation、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: 20971522MB限制单次处理的文件体积防止超大产物拖垮后续校验。五、行为策略与协作关系行为与沟通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: minimalerror_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 自身不派生新 Agentcan_spawn: []但可以把API 分析子任务委托给analyze-api它与后端开发 Agentdev-backend-api和集成测试 Agenttest-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 的五项核心职责创建符合 OpenAPI 3.0 的规格为所有端点编写描述与示例精确定义请求/响应 schema包含认证与安全方案security schemes为每个操作提供清晰示例。配套的 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的docsjob约 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, indent2) - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages84c30a85c19949d7eee79c4ff27748b70285e453 continue-on-error: true with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs destination_dir: api-docs可以看到实际产物链路在 archive/v1/src/api/main.py 定义 FastAPIapp后直接调用app.openapi()在 CI 中即时导出openapi.json——也就是说规格由框架从路由定义自动生成而非纯手工维护生成的规格随docs目录发布到 GitHub Pages 的api-docs子目录部署步骤标记continue-on-errorCI 注释明确说明生成 openapi.json 才是真正的校验Pages 部署是尽力而为。服务侧的证据也与OpenAPI 是公开只读面这一定位一致archive/v1/src/config/settings.py 中openapi_url的默认值即/openapi.jsonarchive/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-reward0.85检索历史文档模式作为先验模板post_execution统计端点数/schema 数grep -c ^ /以固定reward0.9调用memory store-pattern沉淀本次结果成功时触发neural train50 epochson_error同样以reward0.0存储失败模式。v1.0.0本文主体不含上述学习闭环是一套无状态、纯规则驱动的文档 Agentv2 则尝试让文档生成从历史成功案例中复用模板。若只需确定性的文档维护行为v1 定义更简单可控。十、关键参数速查参数值作用max_file_operations50单任务文件操作上限max_execution_time300单任务时长上限秒max_file_size2097152单文件处理上限2MBmemory_accessread记忆库只读error_handlinglenient非致命错误不中断confirmation_required删文档 / 改 API 版本破坏性操作需确认batch_size/memory_limit10 / 256MB并行批大小 / 内存上限can_delegate_toanalyze-api唯一的可委托对象小结RuView 的api-docsAgent 定义展示了声明式 Agent的一个完整样本——用 frontmatter 声明触发条件、工具白名单、路径围栏、配额与钩子用系统提示词固定产出物标准OpenAPI 3.0 骨架 文档要素清单再与 CI 中 FastAPI 自动导出的规格生成流程配合构成Agent 维护文档规范、流水线物化规格的双轨 API 文档体系。理解这套结构后可以为任意语言栈的项目套用同样的 Agent 定义范式来治理 API 文档。【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表