尧图网页设计 
claude-howto 插件 Subagent 实战用 api-documenter 自动化生成完整 API 文档【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto关联文档uk/07-plugins/documentation/agents/api-documenter.md另见英文版 07-plugins/documentation/agents/api-documenter.md在 Claude Code 的插件体系中api-documenter是一个专职负责 API 文档产出的 Subagent子代理。它接收主会话委派的文档任务在独立上下文窗口中运行交付涵盖端点说明、参数描述、响应模式、多语言调用示例与错误码的完整 Markdown 文档。本篇将围绕该子代理的定义文件、与之配套的generate-api-docs斜杠命令以及api-endpoint.md、function-docs.md两套模板讲清它在 claude-howto 仓库中的角色定位、配置机制、工作流程与落地实操帮助你将其接入自己的项目文档流水线。一、api-documenter 是什么文档插件中的专职 API 文档代理api-documenter是 claude-howto 仓库07-plugins/documentation插件内置的三个文档类 Subagent 之一其职责边界定义在 07-plugins/documentation/agents/api-documenter.mdCreates comprehensive API documentation创建全面的 API 文档与插件内另外两个代理形成明确分工代理职责可用工具api-documenter端点文档、参数描述、响应模式、代码示例、错误码Read, Write, Grepcode-commentatorJSDoc/docstring、行内注释、参数与返回值说明Read, Write, Editexample-generator入门指南、常见用例、集成示例、最佳实践、排障场景Read, Write从工具授权即可看出定位差异code-commentator拿到Edit工具用于就地修改代码注释而api-documenter持有Grep用于全库检索端点定义配合Read/Write完成读取源码 → 分析 → 写出独立文档文件的完整闭环。这正体现了 Subagent 的核心设计思想——每个代理使用独立上下文窗口只拿到任务所需的最小工具集避免主会话上下文被文档生成这类重 IO 任务污染参见 04-subagents/README.md。二、Subagent 定义文件结构与 frontmatter 配置解析api-documenter的定义文件采用YAML frontmatter Markdown 系统提示词的标准结构全文极简但信息完整--- name: api-documenter description: API documentation specialist tools: Read, Write, Grep --- # API Documenter Creates comprehensive API documentation: - Endpoint documentation - Parameter descriptions - Response schemas - Code examples (curl, JS, Python) - Error codes各字段含义字段机制详见 04-subagents/README.md 的 Configuration 章节字段是否必填本代理取值说明name是api-documenter唯一标识符小写字母加连字符:被保留用于插件命名空间不得出现在名称中description是API documentation specialist自然语言描述触发时机主代理据此判断何时委派任务tools否Read, Write, Grep逗号分隔的允许工具列表省略该字段则继承全部工具显式列出则严格受限定义文件正文frontmatter 之后的部分即该代理的系统提示词。这里用一句话声明职责、五个要点列出产出物清晰定义了输入什么、输出什么的边界。值得注意的细节claude-howto 中的api-documenter没有声明model、permissionMode、memory等可选字段这意味着它默认继承父会话的模型配置与权限模式。从源码结构可以推断插件内置代理刻意保持配置精简把运行细节交给宿主会话决定符合插件代理安全受限的设计——插件的 Subagent 不允许自定义hooks、mcpServers和permissionMode以防权限提升或任意命令执行04-subagents/README.md 的 Plugin Subagent Security 一节。插件代理的文件位置与优先级api-documenter位于插件的agents/目录属于四级代理来源中优先级最低的一级。同名代理的解析顺序为CLI 定义claude --agents json仅对当前会话生效最高优先级项目级.claude/agents/作用于当前项目用户级~/.claude/agents/作用于所有项目插件级插件agents/目录最低优先级这意味着如果你在项目.claude/agents/下定义了同名api-documenter将覆盖插件内置版本——你可以借此按团队规范定制默认输出风格。三、五大产出物一份完整 API 文档到底包含什么api-documenter的系统提示词明确列出五项核心产出这正是判断其输出是否合格的验收清单端点文档Endpoint documentation——每个 REST 端点的用途、认证方式、参数、响应与错误码参数描述Parameter descriptions——路径参数、查询参数、请求体字段的名称、类型、必填性与默认值响应模式Response schemas——成功与失败响应的 JSON 结构示例代码示例Code examples in curl, JS, Python——让不同技术栈的调用方都能开箱即用错误码Error codes——统一异常响应的错误编码体系。这五项并非孤立的清单而是层层递进端点文档是骨架参数描述和响应模式是接口契约代码示例是使用证据错误码则是调用方集成时最需要的排障信息。将它们组合起来恰好构成一份可被其他开发者、Agent 乃至自动化测试直接消费的接口说明。四、配套斜杠命令/generate-api-docs 的完整工作流api-documenter通常不直接被用户调用而是由文档插件的斜杠命令/generate-api-docs委派。该命令定义于 07-plugins/documentation/commands/generate-api-docs.mdGenerate complete API documentation: 1. Scan API endpoints 2. Extract function signatures and JSDoc 3. Organize by module/endpoint 4. Create markdown with examples 5. Include request/response schemas 6. Add error documentation插件 README 的 07-plugins/documentation/README.md 给出了从用户输入到文档落盘的端到端示例User: /generate-api-docs Claude: 1. Scans all API endpoints in /src/api/ 2. Delegates to api-documenter subagent 3. Extracts function signatures and JSDoc 4. Organizes by module/endpoint 5. Uses api-endpoint.md template 6. Generates comprehensive markdown docs 7. Includes curl, JavaScript, and Python examples Result: ✅ API documentation generated Files created: - docs/api/users.md - docs/api/auth.md - docs/api/products.md Coverage: 23/23 endpoints documented整个链路的关键点在于扫描与分析在主会话完成文档撰写被委派给api-documenter子代理。这样做的收益是——主会话只需接收最终结果并做覆盖率核对如示例中的23/23 endpoints大量逐端点阅读源码、构造示例、撰写描述的中间过程全部发生在子代理的独立上下文中不挤占主对话上下文。这也印证了 Subagent 的适用场景判断复杂、多步骤、会产生大量中间内容的文档任务适合委派而简单的单步任务则不必动用子代理04-subagents/README.md。除generate-api-docs外文档插件还提供三个配套命令共同维护文档生命周期命令作用/generate-api-docs从源码扫描并生成 API 文档/generate-readme创建或更新 README/sync-docs检测代码变更、定位过期文档并更新见 07-plugins/documentation/commands/sync-docs.md/validate-docs校验文档有效性安装整个插件只需一条命令07-plugins/documentation/README.md/plugin install documentation要求 Claude Code 2.1如需将文档同步到远端仓库则需配置 GitHub 访问令牌export GITHUB_TOKENyour_github_token五、模板体系api-endpoint.md 逐段拆解api-documenter生成文档时依赖 07-plugins/documentation/templates/api-endpoint.md 保证输出格式统一。该模板以# [METHOD] /api/v1/[endpoint]为标题规范了九个章节1. Description 与 Authentication端点用途的一句话说明 认证方式声明如 Bearer token。2. Parameters三种参数分类模板对参数做了严格的分类表格这是接口契约的核心部分Path Parameters| Name | Type | Required | Description | |------|------|----------|-------------| | id | string | Yes | Resource ID |Query Parameters| Name | Type | Required | Description | |------|------|----------|-------------| | page | integer | No | Page number (default: 1) | | limit | integer | No | Items per page (default: 20) |注意查询参数表格中default: 1 / default: 20的写法——模板要求标注默认值这比单纯声明可选更能帮助调用方做出正确的缺省假设。Request BodyJSON 示例{ field: value }3. Responses成功与失败响应模板分别给出200 OK、400 Bad Request、404 Not Found三种代表性响应并统一了错误响应结构——error.codeerror.message的组合这与错误码产出物直接对应{ success: false, error: { code: VALIDATION_ERROR, message: Invalid input } }4. Examples三种语言同一端点用三种调用方式呈现覆盖最常见的消费方cURL命令行直接可跑curl -X GET https://api.example.com/api/v1/endpoint \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/jsonJavaScriptfetch 风格const response await fetch(/api/v1/endpoint, { headers: { Authorization: Bearer token, Content-Type: application/json } }); const data await response.json();Pythonrequests 风格import requests response requests.get( https://api.example.com/api/v1/endpoint, headers{Authorization: Bearer token} ) data response.json()5. Rate Limits 与 Related Endpoints模板末尾要求标注限流策略如1000 requests per hour for authenticated users和关联端点帮助调用方理解调用约束与导航相邻接口。这套模板直接回答了api-documenter系统提示词中五项产出物的格式是什么——子代理只需按照模板填空就能保证多端点、多模块的文档风格完全一致这也是插件 README 最佳实践中Use templates for consistency用模板保证一致性的具体落地。六、函数级文档模板function-docs.md当 API 文档需要细化到单个函数或方法时api-documenter可切换到 07-plugins/documentation/templates/function-docs.md。该模板以# Function: functionName开头章节结构包括SignatureTypeScript 签名function functionName(param1: Type1, param2: Type2): ReturnTypeParameters 表格参数、类型、必填、说明四列与Returns返回类型 语义描述ParameterTypeRequiredDescriptionparam1Type1YesDescription of param1param2Type2NoDescription of param2Throws异常清单Error: When invalid input is providedTypeError: When wrong type is passedExamplesBasic Usage / Advanced Usage 两级示例与Notes注意事项、性能考虑、最佳实践。对比两个模板可以发现设计层次api-endpoint.md面向 HTTP 接口消费者curl/JS/Python、认证、限流function-docs.md面向代码层调用者签名、参数、异常。api-documenter在扫描阶段通过Grep识别端点与函数再按对象类型套用对应模板实现接口级 函数级双粒度覆盖。插件内还有第三套 adr-template.md用于记录架构决策ADR但那是documentation插件的另一类文档场景与 API 文档生成职责不同。七、将 api-documenter 接入项目的实操建议结合插件 README 的最佳实践清单07-plugins/documentation/README.md与 Subagent 使用规范落地建议如下安装插件在 Claude Code 中执行/plugin install documentation即可获得api-documenter子代理与/generate-api-docs等命令。让文档贴近代码插件内置工作流默认扫描/src/api/并按模块产出docs/api/module.md建议将生成结果纳入版本控制随代码变更一起评审。明确委派方式既可以直接输入/generate-api-docs也可以在普通对话中显式要求——Use the api-documenter subagent to document the auth module在description中加入 use PROACTIVELY 可鼓励主代理在检测到 API 变更时自动委派04-subagents/README.md。用模板锁定格式自定义模板或沿用仓库自带的两套模板确保跨模块文档的章节结构、表格列、JSON 示例风格完全一致。与同步命令配合代码变更后运行/sync-docs让子代理定位过期文档并更新/validate-docs可定期校验文档完整性形成生成 → 同步 → 校验的维护闭环。覆盖同类定义以定制行为如需团队级默认约束可在项目.claude/agents/下定义同名api-documenter优先级高于插件级例如收紧工具集为仅Read, Write或追加输出必须包含变更日志的提示词。八、小结api-documenter展示了 Claude Code 插件体系中命令负责编排、子代理负责执行、模板负责格式的三层协作模式/generate-api-docs负责扫描与委派api-documenter在独立上下文中完成端点分析、参数梳理、响应建模与多语言示例撰写api-endpoint.md/function-docs.md模板则保证产出格式统一、可直接提交版本库。其定义文件本身也极具示范价值——三行 frontmattername/description/tools加一段职责清单就足以让主代理在正确时机准确委派并产出高一致性的专业文档。若你的项目正苦于 API 文档缺失、过期或风格混乱将这套插件内置的子代理接入日常流程是最低成本的起点。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-howto 插件 Subagent 实战：用 api-documenter 自动化生成完整 API 文档
claude-howto 插件 Subagent 实战用 api-documenter 自动化生成完整 API 文档【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto关联文档uk/07-plugins/documentation/agents/api-documenter.md另见英文版 07-plugins/documentation/agents/api-documenter.md在 Claude Code 的插件体系中api-documenter是一个专职负责 API 文档产出的 Subagent子代理。它接收主会话委派的文档任务在独立上下文窗口中运行交付涵盖端点说明、参数描述、响应模式、多语言调用示例与错误码的完整 Markdown 文档。本篇将围绕该子代理的定义文件、与之配套的generate-api-docs斜杠命令以及api-endpoint.md、function-docs.md两套模板讲清它在 claude-howto 仓库中的角色定位、配置机制、工作流程与落地实操帮助你将其接入自己的项目文档流水线。一、api-documenter 是什么文档插件中的专职 API 文档代理api-documenter是 claude-howto 仓库07-plugins/documentation插件内置的三个文档类 Subagent 之一其职责边界定义在 07-plugins/documentation/agents/api-documenter.mdCreates comprehensive API documentation创建全面的 API 文档与插件内另外两个代理形成明确分工代理职责可用工具api-documenter端点文档、参数描述、响应模式、代码示例、错误码Read, Write, Grepcode-commentatorJSDoc/docstring、行内注释、参数与返回值说明Read, Write, Editexample-generator入门指南、常见用例、集成示例、最佳实践、排障场景Read, Write从工具授权即可看出定位差异code-commentator拿到Edit工具用于就地修改代码注释而api-documenter持有Grep用于全库检索端点定义配合Read/Write完成读取源码 → 分析 → 写出独立文档文件的完整闭环。这正体现了 Subagent 的核心设计思想——每个代理使用独立上下文窗口只拿到任务所需的最小工具集避免主会话上下文被文档生成这类重 IO 任务污染参见 04-subagents/README.md。二、Subagent 定义文件结构与 frontmatter 配置解析api-documenter的定义文件采用YAML frontmatter Markdown 系统提示词的标准结构全文极简但信息完整--- name: api-documenter description: API documentation specialist tools: Read, Write, Grep --- # API Documenter Creates comprehensive API documentation: - Endpoint documentation - Parameter descriptions - Response schemas - Code examples (curl, JS, Python) - Error codes各字段含义字段机制详见 04-subagents/README.md 的 Configuration 章节字段是否必填本代理取值说明name是api-documenter唯一标识符小写字母加连字符:被保留用于插件命名空间不得出现在名称中description是API documentation specialist自然语言描述触发时机主代理据此判断何时委派任务tools否Read, Write, Grep逗号分隔的允许工具列表省略该字段则继承全部工具显式列出则严格受限定义文件正文frontmatter 之后的部分即该代理的系统提示词。这里用一句话声明职责、五个要点列出产出物清晰定义了输入什么、输出什么的边界。值得注意的细节claude-howto 中的api-documenter没有声明model、permissionMode、memory等可选字段这意味着它默认继承父会话的模型配置与权限模式。从源码结构可以推断插件内置代理刻意保持配置精简把运行细节交给宿主会话决定符合插件代理安全受限的设计——插件的 Subagent 不允许自定义hooks、mcpServers和permissionMode以防权限提升或任意命令执行04-subagents/README.md 的 Plugin Subagent Security 一节。插件代理的文件位置与优先级api-documenter位于插件的agents/目录属于四级代理来源中优先级最低的一级。同名代理的解析顺序为CLI 定义claude --agents json仅对当前会话生效最高优先级项目级.claude/agents/作用于当前项目用户级~/.claude/agents/作用于所有项目插件级插件agents/目录最低优先级这意味着如果你在项目.claude/agents/下定义了同名api-documenter将覆盖插件内置版本——你可以借此按团队规范定制默认输出风格。三、五大产出物一份完整 API 文档到底包含什么api-documenter的系统提示词明确列出五项核心产出这正是判断其输出是否合格的验收清单端点文档Endpoint documentation——每个 REST 端点的用途、认证方式、参数、响应与错误码参数描述Parameter descriptions——路径参数、查询参数、请求体字段的名称、类型、必填性与默认值响应模式Response schemas——成功与失败响应的 JSON 结构示例代码示例Code examples in curl, JS, Python——让不同技术栈的调用方都能开箱即用错误码Error codes——统一异常响应的错误编码体系。这五项并非孤立的清单而是层层递进端点文档是骨架参数描述和响应模式是接口契约代码示例是使用证据错误码则是调用方集成时最需要的排障信息。将它们组合起来恰好构成一份可被其他开发者、Agent 乃至自动化测试直接消费的接口说明。四、配套斜杠命令/generate-api-docs 的完整工作流api-documenter通常不直接被用户调用而是由文档插件的斜杠命令/generate-api-docs委派。该命令定义于 07-plugins/documentation/commands/generate-api-docs.mdGenerate complete API documentation: 1. Scan API endpoints 2. Extract function signatures and JSDoc 3. Organize by module/endpoint 4. Create markdown with examples 5. Include request/response schemas 6. Add error documentation插件 README 的 07-plugins/documentation/README.md 给出了从用户输入到文档落盘的端到端示例User: /generate-api-docs Claude: 1. Scans all API endpoints in /src/api/ 2. Delegates to api-documenter subagent 3. Extracts function signatures and JSDoc 4. Organizes by module/endpoint 5. Uses api-endpoint.md template 6. Generates comprehensive markdown docs 7. Includes curl, JavaScript, and Python examples Result: ✅ API documentation generated Files created: - docs/api/users.md - docs/api/auth.md - docs/api/products.md Coverage: 23/23 endpoints documented整个链路的关键点在于扫描与分析在主会话完成文档撰写被委派给api-documenter子代理。这样做的收益是——主会话只需接收最终结果并做覆盖率核对如示例中的23/23 endpoints大量逐端点阅读源码、构造示例、撰写描述的中间过程全部发生在子代理的独立上下文中不挤占主对话上下文。这也印证了 Subagent 的适用场景判断复杂、多步骤、会产生大量中间内容的文档任务适合委派而简单的单步任务则不必动用子代理04-subagents/README.md。除generate-api-docs外文档插件还提供三个配套命令共同维护文档生命周期命令作用/generate-api-docs从源码扫描并生成 API 文档/generate-readme创建或更新 README/sync-docs检测代码变更、定位过期文档并更新见 07-plugins/documentation/commands/sync-docs.md/validate-docs校验文档有效性安装整个插件只需一条命令07-plugins/documentation/README.md/plugin install documentation要求 Claude Code 2.1如需将文档同步到远端仓库则需配置 GitHub 访问令牌export GITHUB_TOKENyour_github_token五、模板体系api-endpoint.md 逐段拆解api-documenter生成文档时依赖 07-plugins/documentation/templates/api-endpoint.md 保证输出格式统一。该模板以# [METHOD] /api/v1/[endpoint]为标题规范了九个章节1. Description 与 Authentication端点用途的一句话说明 认证方式声明如 Bearer token。2. Parameters三种参数分类模板对参数做了严格的分类表格这是接口契约的核心部分Path Parameters| Name | Type | Required | Description | |------|------|----------|-------------| | id | string | Yes | Resource ID |Query Parameters| Name | Type | Required | Description | |------|------|----------|-------------| | page | integer | No | Page number (default: 1) | | limit | integer | No | Items per page (default: 20) |注意查询参数表格中default: 1 / default: 20的写法——模板要求标注默认值这比单纯声明可选更能帮助调用方做出正确的缺省假设。Request BodyJSON 示例{ field: value }3. Responses成功与失败响应模板分别给出200 OK、400 Bad Request、404 Not Found三种代表性响应并统一了错误响应结构——error.codeerror.message的组合这与错误码产出物直接对应{ success: false, error: { code: VALIDATION_ERROR, message: Invalid input } }4. Examples三种语言同一端点用三种调用方式呈现覆盖最常见的消费方cURL命令行直接可跑curl -X GET https://api.example.com/api/v1/endpoint \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/jsonJavaScriptfetch 风格const response await fetch(/api/v1/endpoint, { headers: { Authorization: Bearer token, Content-Type: application/json } }); const data await response.json();Pythonrequests 风格import requests response requests.get( https://api.example.com/api/v1/endpoint, headers{Authorization: Bearer token} ) data response.json()5. Rate Limits 与 Related Endpoints模板末尾要求标注限流策略如1000 requests per hour for authenticated users和关联端点帮助调用方理解调用约束与导航相邻接口。这套模板直接回答了api-documenter系统提示词中五项产出物的格式是什么——子代理只需按照模板填空就能保证多端点、多模块的文档风格完全一致这也是插件 README 最佳实践中Use templates for consistency用模板保证一致性的具体落地。六、函数级文档模板function-docs.md当 API 文档需要细化到单个函数或方法时api-documenter可切换到 07-plugins/documentation/templates/function-docs.md。该模板以# Function: functionName开头章节结构包括SignatureTypeScript 签名function functionName(param1: Type1, param2: Type2): ReturnTypeParameters 表格参数、类型、必填、说明四列与Returns返回类型 语义描述ParameterTypeRequiredDescriptionparam1Type1YesDescription of param1param2Type2NoDescription of param2Throws异常清单Error: When invalid input is providedTypeError: When wrong type is passedExamplesBasic Usage / Advanced Usage 两级示例与Notes注意事项、性能考虑、最佳实践。对比两个模板可以发现设计层次api-endpoint.md面向 HTTP 接口消费者curl/JS/Python、认证、限流function-docs.md面向代码层调用者签名、参数、异常。api-documenter在扫描阶段通过Grep识别端点与函数再按对象类型套用对应模板实现接口级 函数级双粒度覆盖。插件内还有第三套 adr-template.md用于记录架构决策ADR但那是documentation插件的另一类文档场景与 API 文档生成职责不同。七、将 api-documenter 接入项目的实操建议结合插件 README 的最佳实践清单07-plugins/documentation/README.md与 Subagent 使用规范落地建议如下安装插件在 Claude Code 中执行/plugin install documentation即可获得api-documenter子代理与/generate-api-docs等命令。让文档贴近代码插件内置工作流默认扫描/src/api/并按模块产出docs/api/module.md建议将生成结果纳入版本控制随代码变更一起评审。明确委派方式既可以直接输入/generate-api-docs也可以在普通对话中显式要求——Use the api-documenter subagent to document the auth module在description中加入 use PROACTIVELY 可鼓励主代理在检测到 API 变更时自动委派04-subagents/README.md。用模板锁定格式自定义模板或沿用仓库自带的两套模板确保跨模块文档的章节结构、表格列、JSON 示例风格完全一致。与同步命令配合代码变更后运行/sync-docs让子代理定位过期文档并更新/validate-docs可定期校验文档完整性形成生成 → 同步 → 校验的维护闭环。覆盖同类定义以定制行为如需团队级默认约束可在项目.claude/agents/下定义同名api-documenter优先级高于插件级例如收紧工具集为仅Read, Write或追加输出必须包含变更日志的提示词。八、小结api-documenter展示了 Claude Code 插件体系中命令负责编排、子代理负责执行、模板负责格式的三层协作模式/generate-api-docs负责扫描与委派api-documenter在独立上下文中完成端点分析、参数梳理、响应建模与多语言示例撰写api-endpoint.md/function-docs.md模板则保证产出格式统一、可直接提交版本库。其定义文件本身也极具示范价值——三行 frontmattername/description/tools加一段职责清单就足以让主代理在正确时机准确委派并产出高一致性的专业文档。若你的项目正苦于 API 文档缺失、过期或风格混乱将这套插件内置的子代理接入日常流程是最低成本的起点。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考