feat(api-doc-generator): 添加API文档生成技能及其相关模板和示例

- 创建api-doc-generator技能主文档SKILL.md，定义触发条件和使用指南
- 添加中文接口文档模板templates/接口文档模板.md
- 添加英文接口文档模板templates/api-documentation-template-en.md
- 创建技能使用说明README.md，包含功能特点和工作流程
- 添加扫描和生成示例examples/scan-and-generate-example.md
- 定义详细的代码扫描规则和参数提取方法
- 实现双语模板支持和自动保存到./docs目录功能
- 包含完整的接口信息提取和文档生成工作流程

skills/api-doc-generator/README.md

@@ -0,0 +1,177 @@
+# API Documentation Generator Skill
+
+## 概述
+
+这是一个基于 Agent Skills 规范的接口文档生成技能，可以自动扫描项目中的 Controller 类，提取接口信息（请求地址、请求方式、入参、出参），并生成符合标准的接口文档。
+
+**重要提示**：本技能仅在用户明确提到 **接口文档** 或 **API文档** 时触发，避免与其他文档生成工具产生冲突。
+
+## 功能特点
+
+1. **智能扫描**：自动扫描项目中的 Controller 类，识别所有 API 接口
+2. **信息提取**：提取接口的完整信息，包括请求地址、请求方式、参数、响应结构
+3. **双语模板**：提供中文和英文两种标准接口文档模板，格式统一规范
+4. **自动保存**：生成的文档自动保存到项目 `./docs` 目录
+5. **多语言支持**：支持 Java 和 Kotlin 项目
+6. **框架支持**：支持 Spring Boot、Spring MVC 等框架
+
+## 文件结构
+
+```
+api-doc-generator/
+├── SKILL.md                              # 主技能文档（Agent Skills 规范）
+├── LICENSE.txt                           # Apache 2.0 许可证
+├── README.md                             # 本文件
+├── templates/                            # 模板目录
+│   ├── 接口文档模板.md                   # 标准接口文档模板（中文）
+│   └── api-documentation-template-en.md # 标准接口文档模板（英文）
+└── examples/                             # 示例目录
+    └── scan-and-generate-example.md     # 扫描和生成示例
+```
+
+## 工作流程
+
+技能遵循 4 步系统化工作流程：
+
+1. **扫描代码**：检查当前项目或指定对象的代码，扫描 Controller 类和接口方法
+2. **提取信息**：为每个接口收集完整信息（请求地址、请求方式、入参、出参）
+3. **生成文档**：依据接口模板创建符合当前项目的接口文档
+4. **保存输出**：将生成的文档统一保存到当前项目下的 `./docs` 目录中
+
+## 使用方式
+
+**重要提示**：本技能仅在用户明确提到 **接口文档** 或 **API文档** 时触发。
+
+### 触发短语示例
+
+- ✅ "生成接口文档"
+- ✅ "扫描接口生成文档"
+- ✅ "创建API文档"
+- ✅ "为接口生成文档"
+- ❌ "生成文档"（未明确提到接口，不会触发）
+- ❌ "创建文档"（未明确提到接口，不会触发）
+
+### 使用流程
+
+当用户明确提到生成接口文档时，技能会自动：
+
+1. **选择模板语言**：询问用户偏好语言（中文/英文），或根据项目上下文自动检测
+2. **扫描代码**：查找项目中的 Controller 类
+3. **验证接口**：检查是否有接口方法，如果没有则提示无法生成
+4. **提取信息**：为每个接口提取完整信息
+5. **生成文档**：使用选定的模板（中文或英文）生成接口文档
+6. **保存文件**：保存到 `./docs` 目录
+
+## 扫描规则
+
+### Controller 识别
+
+- **Java/Spring Boot**：
+  - 查找 `@RestController` 或 `@Controller` 注解的类
+  - 常见包路径：`*.controller.*`, `*.web.*`, `*.api.*`
+  - 文件名模式：`*Controller.java` 或 `*Controller.kt`
+
+### 接口方法识别
+
+- 查找以下注解的方法：
+  - `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`
+  - `@RequestMapping(method = RequestMethod.*)`
+
+### 参数提取
+
+- **Path Parameters**：`@PathVariable` 注解的参数
+- **Query Parameters**：`@RequestParam` 注解的参数
+- **Request Body**：`@RequestBody` 注解的参数
+- **Request Headers**：`@RequestHeader` 注解的参数
+
+### 响应提取
+
+- 方法返回类型
+- `@ResponseBody` 注解
+- 泛型类型（如 `R<T>`, `Page<T>`）
+- 响应实体结构
+
+## 文档模板
+
+技能提供**中文**和**英文**两种标准模板，结构完全一致，仅语言不同。
+
+### 中文模板 (`templates/接口文档模板.md`)
+
+1. **文档概览**：版本记录、责任人
+2. **接口一览表**：所有接口的汇总表格
+3. **接口定义**：每个接口的详细定义
+   - 接口说明
+   - 请求信息（Method、URL、Headers、Parameters、Body）
+   - 响应信息（结构、字段、示例）
+4. **统一响应结构**：标准响应格式、分页格式、错误码
+5. **请求头规范**：请求头说明
+6. **注意事项**：重要提示
+
+### 英文模板 (`templates/api-documentation-template-en.md`)
+
+1. **Document Overview**: Version history, responsibilities
+2. **API Interface List**: Summary table of all interfaces
+3. **Interface Definitions**: Detailed definition for each interface
+   - Interface description
+   - Request information (Method, URL, Headers, Parameters, Body)
+   - Response information (structure, fields, examples)
+4. **Standard Response Structure**: Standard response format, pagination format, error codes
+5. **Request Header Specifications**: Request header descriptions
+6. **Important Notes**: Important reminders
+
+### 模板选择
+
+- 技能会自动询问用户偏好语言（中文/英文）
+- 如果未指定，会根据项目上下文（代码注释、包名等）自动检测
+- 两种模板结构完全相同，仅语言不同
+
+## 输出位置
+
+- **默认路径**：`./docs/api-documentation.md`
+- **多模块**：`./docs/{module-name}-api-documentation.md`
+- **自定义**：用户可指定自定义文件名
+
+如果 `./docs` 目录不存在，会自动创建。
+
+## 示例
+
+### 示例 1: 扫描整个项目
+
+**用户**: "生成接口文档"
+
+**AI 执行**:
+1. 扫描项目，发现 3 个 Controller 类
+2. 提取 19 个接口的完整信息
+3. 生成接口文档
+4. 保存到 `./docs/api-documentation.md`
+
+### 示例 2: 扫描指定 Controller
+
+**用户**: "为 OrderController 生成接口文档"
+
+**AI 执行**:
+1. 定位 `OrderController` 类
+2. 提取 5 个接口的完整信息
+3. 生成订单模块接口文档
+4. 保存到 `./docs/order-api-documentation.md`
+
+详细示例请参考 `examples/scan-and-generate-example.md`。
+
+## 注意事项
+
+1. **接口验证**：如果项目中没有 Controller 类或接口方法，会提示无法生成文档
+2. **信息完整性**：尽量从代码注释和注解中提取接口描述信息
+3. **格式规范**：生成的文档严格遵循模板格式
+4. **编码格式**：文档使用 UTF-8 编码保存
+
+## 参考资料
+
+- **模板文件**：
+  - `templates/接口文档模板.md` - 标准接口文档模板（中文）
+  - `templates/api-documentation-template-en.md` - 标准接口文档模板（英文）
+- **示例文件**：`examples/scan-and-generate-example.md` - 使用示例
+- **Agent Skills 规范**：https://agentskills.io/
+
+## 许可证
+
+Apache 2.0 License - 详见 `LICENSE.txt`

skills/api-doc-generator/SKILL.md

@@ -1,22 +1,346 @@
 ---
 name: api-doc-generator
-description: Provides comprehensive guidance for API documentation generation including API documentation creation, formatting, and API documentation best practices. Use when the user asks about API documentation, needs to generate API docs, format API documentation, or create API documentation structures.
+description: |
+  Provides comprehensive guidance for generating API documentation by scanning code interfaces, extracting request/response 
+  information, and creating standardized API documentation. Use ONLY when the user explicitly mentions generating API 
+  documentation, creating API docs, scanning interfaces, or documenting APIs. The skill scans Controller classes, extracts 
+  interface information (URL, method, parameters, response), and generates documentation following standard templates. 
+  Do NOT trigger for generic documentation requests without explicit API documentation mention.
 license: Complete terms in LICENSE.txt
 ---
 
 ## When to use this skill
 
-Use this skill whenever the user wants to:
-- [待完善：根据具体工具添加使用场景]
+**CRITICAL: This skill should ONLY be triggered when the user explicitly mentions generating API documentation, creating API docs, scanning interfaces, or documenting APIs.**
+
+**ALWAYS use this skill when the user mentions:**
+- Generating API documentation (explicitly mentions "API documentation" or "API docs")
+- Creating API documentation from code
+- Scanning interfaces to generate documentation
+- Documenting REST APIs
+- 生成接口文档 (explicitly mentions "接口文档")
+- 扫描接口生成文档 (scan interfaces to generate documentation)
+- 创建API文档 (create API documentation)
+
+**Trigger phrases include:**
+- "生成接口文档" (generate API documentation) - **must include "接口文档"**
+- "扫描接口生成文档" (scan interfaces to generate documentation)
+- "创建API文档" (create API documentation)
+- "为接口生成文档" (generate documentation for interfaces)
+- "接口文档生成" (API documentation generation)
+
+**DO NOT trigger this skill for:**
+- Generic documentation requests without mentioning API/interfaces
+- Code comments generation
+- README file generation
+- Other types of documentation (user guides, technical specs, etc.)
+- "生成文档" without "接口" or "API" (too generic)
 
 ## How to use this skill
 
-[待完善：根据具体工具添加使用指南]
+**CRITICAL: This skill should ONLY be triggered when the user explicitly mentions generating API documentation. Do NOT trigger for generic documentation requests without API context.**
+
+### Workflow Overview
+
+This skill follows a systematic 4-step workflow:
+
+1. **Scan Code** - Check current project or specified objects for Controller classes and API interfaces
+2. **Extract Information** - Scan interfaces to collect request URL, method, parameters, and response information
+3. **Generate Documentation** - Create API documentation following the standard template
+4. **Save Output** - Save documentation to `./docs` directory in the current project
+
+### Step-by-Step Process
+
+#### Step 1: Scan Code for Interfaces
+
+**CRITICAL: Before generating any documentation, you MUST scan the code to find API interfaces.**
+
+1. **Identify Target**:
+   - Ask user if they want to scan the entire project or specific Controller classes
+   - If no target specified, scan the entire project for Controller classes
+   - Common Controller patterns:
+     - Java: `@RestController`, `@Controller` with `@RequestMapping`
+     - Spring Boot: Classes in `controller` or `web` package
+     - Files ending with `Controller.java` or `Controller.kt`
+
+2. **Scan for Controllers**:
+   - Search for Controller classes in the project
+   - Identify all classes annotated with `@RestController` or `@Controller`
+   - List all found Controller classes
+
+3. **Check for Interfaces**:
+   - For each Controller class, scan for methods annotated with:
+     - `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`
+     - `@RequestMapping` with method specification
+   - Count total number of API interfaces found
+
+4. **Validation**:
+   - If no interfaces found, **STOP** and inform user:
+     ```
+     未找到任何接口，无法生成接口文档。请确认：
+     1. 项目中是否存在 Controller 类
+     2. Controller 类中是否有 @GetMapping、@PostMapping 等注解的方法
+     3. 是否指定了正确的扫描路径
+     ```
+   - If interfaces found, proceed to Step 2
+
+**Output**: List of Controller classes and total number of interfaces found.
+
+#### Step 2: Extract Interface Information
+
+**CRITICAL: For each interface, extract complete information including URL, method, parameters, and response.**
+
+For each API interface found, extract:
+
+1. **Basic Information**:
+   - **Interface Name**: Method name or description from annotation
+   - **Request Method**: GET, POST, PUT, DELETE, PATCH
+   - **Request URL**: Full path including class-level and method-level mappings
+   - **Controller Class**: Full class name with package
+   - **Method Name**: Java/Kotlin method name
+
+2. **Request Information**:
+   - **Path Parameters**: Parameters in URL path (e.g., `/user/{id}`)
+     - Parameter name, type, required flag, description
+   - **Query Parameters**: Parameters in query string
+     - Parameter name, type, required flag, default value, description
+   - **Request Body** (for POST/PUT):
+     - Body type (JSON, Form-data, etc.)
+     - Field definitions: name, type, required flag, description
+     - Nested object structures
+   - **Request Headers**:
+     - Common headers: Authorization, Shop-Id, Tenant-Id
+     - Custom headers if any
+
+3. **Response Information**:
+   - **Response Type**: Return type of the method
+   - **Response Structure**: 
+     - Standard response wrapper (e.g., `R<T>`, `ApiResponse<T>`)
+     - Data object structure
+   - **Response Fields**: 
+     - Field name, type, description
+     - Nested object fields
+   - **Response Examples**: Generate example JSON responses
+   - **Error Responses**: Common error codes and messages
+
+4. **Additional Information**:
+   - **Description**: From `@ApiOperation`, `@Operation`, or method comments
+   - **Tags**: From `@Api`, `@Tag` annotations
+   - **Deprecated**: Check for `@Deprecated` annotation
+   - **Security**: Authentication/authorization requirements
+
+**Output**: Structured data for each interface with all extracted information.
+
+#### Step 3: Generate Documentation
+
+**CRITICAL: Generate documentation following the standard template format.**
+
+1. **Select Template Language**:
+   - Ask user for preferred language: Chinese or English
+   - If not specified, detect from project context (code comments, package names, etc.)
+   - Available templates:
+     - Chinese: `templates/接口文档模板.md`
+     - English: `templates/api-documentation-template-en.md`
+
+2. **Load Template**:
+   - Load the appropriate template based on language selection
+   - Use it as the base structure
+
+2. **Organize by Module**:
+   - Group interfaces by Controller class or business module
+   - Create sections for each module
+
+3. **Generate Interface List Table**:
+   - For Chinese template: Create "接口一览表" with columns:
+     - 序号 (Sequence number)
+     - 接口地址 (Interface URL)
+     - 请求方式 (Request Method)
+     - 说明 (Description)
+     - 完成情况 (Status)
+   - For English template: Create "API Interface List" with columns:
+     - No. (Sequence number)
+     - Interface URL
+     - Method
+     - Description
+     - Status
+
+4. **Generate Interface Definitions**:
+   For each interface, generate:
+   - **Interface Name**: Clear, descriptive name
+   - **Interface Address**: Full URL with method
+   - **Description**: 
+     - Corresponding Controller class and method
+     - Business functionality description
+     - Business rules if any
+   - **Request Section**:
+     - Method and URL
+     - Headers table
+     - Path Parameters table
+     - Query Parameters table
+     - Request Body (if applicable) with field definitions
+   - **Response Section**:
+     - Response structure description
+     - Response fields table
+     - Response example (JSON)
+     - Error response examples
+
+5. **Add Standard Sections**:
+   - For Chinese template:
+     - **统一响应结构**: Standard response format
+     - **分页响应格式**: Pagination response format
+     - **错误码约定**: Error code conventions
+     - **请求头规范**: Request header specifications
+     - **注意事项**: Important notes
+   - For English template:
+     - **Standard Response Structure**: Standard response format
+     - **Pagination Response Format**: Pagination response format
+     - **Error Code Conventions**: Error code conventions
+     - **Request Header Specifications**: Request header specifications
+     - **Important Notes**: Important notes
+
+6. **Format Documentation**:
+   - Use proper Markdown formatting
+   - Ensure tables are properly formatted
+   - Include code blocks for JSON examples
+   - Add proper headings hierarchy
+
+**Output**: Complete API documentation in Markdown format.
+
+#### Step 4: Save Documentation
 
-## Best Practices
+**CRITICAL: Save documentation to the `./docs` directory in the current project.**
 
-[待完善：根据具体工具添加最佳实践]
+1. **Determine Output Path**:
+   - Default: `./docs/api-documentation.md`
+   - If multiple modules: `./docs/{module-name}-api-documentation.md`
+   - Ask user if they want a custom filename
+
+2. **Create Directory**:
+   - Check if `./docs` directory exists
+   - If not, create it automatically
+
+3. **Save File**:
+   - Write the generated documentation to the file
+   - Use UTF-8 encoding
+   - Ensure proper line endings
+
+4. **Inform User**:
+   - Tell user where the file was saved
+   - Show the file path
+   - Optionally display a preview of the documentation
+
+**Output**: Documentation file saved to `./docs/api-documentation.md` (or custom path).
+
+### Code Scanning Guidelines
+
+#### Java/Spring Boot Projects
+
+**Controller Identification**:
+- Look for classes annotated with `@RestController` or `@Controller`
+- Check for `@RequestMapping` at class level
+- Common package patterns: `*.controller.*`, `*.web.*`, `*.api.*`
+
+**Method Identification**:
+- Methods annotated with:
+  - `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`
+  - `@RequestMapping(method = RequestMethod.GET)` etc.
+
+**Parameter Extraction**:
+- `@PathVariable`: Path parameters
+- `@RequestParam`: Query parameters
+- `@RequestBody`: Request body
+- `@RequestHeader`: Request headers
+- Parameter types from method signature
+
+**Response Extraction**:
+- Return type from method signature
+- `@ResponseBody` annotation
+- Generic types (e.g., `R<T>`, `Page<T>`)
+- Response entity structure
+
+#### Kotlin/Spring Boot Projects
+
+Similar to Java, but check for:
+- Kotlin data classes for request/response
+- Nullable types (`String?`, `Int?`)
+- Kotlin-specific annotations
+
+### Documentation Template Structure
+
+The generated documentation follows this structure (available in both Chinese and English):
+
+**Chinese Template** (`templates/接口文档模板.md`):
+1. **文档概览** (Document Overview)
+   - Version history table
+   - Responsibility table
+
+2. **接口一览表** (Interface List Table)
+   - Summary table of all interfaces
+
+3. **接口定义** (Interface Definitions)
+   - Detailed definition for each interface
+   - Request and Response sections
+   - Field definitions and examples
+
+4. **统一响应结构** (Standard Response Structure)
+   - Standard response format
+   - Pagination format
+   - Error codes
+
+5. **请求头规范** (Request Header Specifications)
+
+6. **注意事项** (Important Notes)
+
+**English Template** (`templates/api-documentation-template-en.md`):
+1. **Document Overview**
+   - Version history table
+   - Responsibility table
+
+2. **API Interface List**
+   - Summary table of all interfaces
+
+3. **Interface Definitions**
+   - Detailed definition for each interface
+   - Request and Response sections
+   - Field definitions and examples
+
+4. **Standard Response Structure**
+   - Standard response format
+   - Pagination format
+   - Error codes
+
+5. **Request Header Specifications**
+
+6. **Important Notes**
+
+**Template Selection**:
+- Ask user for preferred language (Chinese/English)
+- If not specified, detect from project context
+- Both templates follow the same structure, only language differs
+
+### Best Practices
+
+1. **Complete Information**: Extract all available information from code, including annotations and comments
+2. **Standard Format**: Follow the template structure strictly
+3. **Clear Descriptions**: Use meaningful descriptions from code comments or annotations
+4. **Examples**: Include realistic response examples
+5. **Error Handling**: Document common error scenarios
+6. **Grouping**: Organize interfaces by module or Controller class
+7. **Validation**: Verify all extracted information is accurate
+
+### Reference Documentation
+
+- **Templates**:
+  - `templates/接口文档模板.md` - Standard API documentation template (Chinese)
+  - `templates/api-documentation-template-en.md` - Standard API documentation template (English)
+- **Example**: `examples/scan-and-generate-example.md` - Complete workflow example showing how to scan and generate API documentation
 
 ## Keywords
 
-[待完善：根据具体工具添加关键词]
+**English keywords:**
+api documentation, api docs, generate api documentation, create api docs, scan interfaces, document apis, rest api documentation, interface documentation, api doc generator, scan controllers, extract api information
+
+**Chinese keywords (中文关键词):**
+接口文档, API文档, 生成接口文档, 创建接口文档, 扫描接口, 接口文档生成, API文档生成, 接口文档生成器, 扫描Controller, 提取接口信息, 接口文档模板
+
+**IMPORTANT**: All keywords must include "接口文档" (API documentation) or "API" to avoid false triggers. Generic terms like "生成文档" (generate documentation) without "接口" or "API" should NOT trigger this skill.

skills/api-doc-generator/examples/scan-and-generate-example.md

@@ -0,0 +1,87 @@
+# 接口文档生成示例
+
+## 使用场景
+
+当用户需要为项目生成接口文档时，使用此技能。
+
+## 示例对话
+
+### 场景 1: 扫描整个项目生成接口文档
+
+**用户**: "生成接口文档"
+
+**AI 响应**:
+1. 扫描项目中的 Controller 类
+2. 发现以下 Controller:
+   - `com.example.order.OrderController` (5个接口)
+   - `com.example.user.UserController` (8个接口)
+   - `com.example.product.ProductController` (6个接口)
+3. 提取每个接口的详细信息
+4. 生成接口文档
+5. 保存到 `./docs/api-documentation.md`
+
+### 场景 2: 扫描指定 Controller 生成文档
+
+**用户**: "为 OrderController 生成接口文档"
+
+**AI 响应**:
+1. 定位 `OrderController` 类
+2. 扫描该 Controller 中的所有接口方法
+3. 提取接口信息
+4. 生成该模块的接口文档
+5. 保存到 `./docs/order-api-documentation.md`
+
+### 场景 3: 扫描多个指定类
+
+**用户**: "扫描 OrderController 和 UserController 生成接口文档"
+
+**AI 响应**:
+1. 定位指定的 Controller 类
+2. 分别扫描每个 Controller
+3. 按模块组织接口
+4. 生成完整的接口文档
+5. 保存到 `./docs/api-documentation.md`
+
+## 扫描结果示例
+
+### 扫描到的 Controller
+
+```
+发现以下 Controller 类：
+1. com.example.order.OrderController
+   - 接口数量: 5
+   - 方法: createOrder, getOrderById, updateOrder, deleteOrder, listOrders
+
+2. com.example.user.UserController
+   - 接口数量: 8
+   - 方法: createUser, getUserById, updateUser, deleteUser, listUsers, 
+          login, logout, changePassword
+```
+
+### 生成的文档结构
+
+```markdown
+# 订单模块接口文档
+
+## 接口一览表
+| 序号 | 接口地址 | 请求方式 | 说明 | 完成情况 |
+| :--- | :--- | :--- | :--- | :--- |
+| 1 | `POST /order` | POST | 创建订单 | ✅ 已完成 |
+| 2 | `GET /order/{id}` | GET | 获取订单详情 | ✅ 已完成 |
+
+## 接口定义
+
+### 3.1 创建订单
+- **接口地址**: `POST /order`
+- **说明**：
+  - 该接口对应后端 `OrderController#createOrder`。
+  - 用于创建新订单
+...
+```
+
+## 注意事项
+
+1. 如果项目中没有 Controller 类，会提示用户无法生成文档
+2. 如果 Controller 中没有接口方法，会提示用户检查代码
+3. 生成的文档会自动保存到 `./docs` 目录
+4. 如果 `./docs` 目录不存在，会自动创建

skills/api-doc-generator/templates/api-documentation-template-en.md

@@ -0,0 +1,213 @@
+# {Product Name} - {Module Name} API Documentation V1.0
+
+## 1. Document Overview
+
+### 1.1 Version History
+| Version | Date | Author | Changes | Notes |
+| :--- | :--- | :--- | :--- | :--- |
+| V1.0.0 | {Date} | - | Initial version | - |
+
+### 1.2 Responsibilities
+| Role | Name | Responsibilities |
+| :--- | :--- | :--- |
+| Product | - | Requirements confirmation, acceptance |
+| Frontend | - | API integration, joint debugging |
+| Backend | - | API development, documentation maintenance |
+| Testing | - | API testing, quality control |
+
+---
+
+## 2. API Interface List
+
+| No. | Interface URL | Method | Description | Status |
+| :--- | :--- | :--- | :--- | :--- |
+| 1 | `{interface_path}` | `{GET/POST/PUT/DELETE}` | {interface_description} | ✅ Completed / ⏳ In Progress / ❌ Not Started |
+
+---
+
+## 3. Interface Definitions
+
+### 3.1 {Interface Name}
+
+- **Interface URL**: `{Method} {Interface Path}`
+- **Description**:
+  - This interface corresponds to backend `{Controller Class Name}#{Method Name}`.
+  - {Interface functionality description}
+  - {Business rules if any}
+- **Request**:
+  - Method: `{GET/POST/PUT/DELETE}`
+  - URL: `{Interface Path}`
+  - **Headers**:
+
+    | Parameter Name | Type | Required | Description |
+    |:---------------| :--- | :--- |:-----------|
+    | `Authorization` | String | Yes | Bearer Token (user authentication credential) |
+    | `App-Id` | String | No | Application ID |
+    | `App-Channel` | String | No | Application Channel |
+    | `App-Version` | String | No | Application Version |
+    | `System-Id` | String | No | System ID |
+    | `Tenant-Id` | String | Yes | Tenant ID |
+  - **Path Parameters**:
+
+    | Parameter Name | Type | Required | Description |
+    | :--- | :--- | :--- | :--- |
+    | `{parameter_name}` | {type} | {Yes/No} | {parameter_description} |
+  - **Query Parameters**:
+
+    | Parameter Name | Type | Required | Description |
+    | :--- | :--- | :--- | :--- |
+    | `{parameter_name}` | {type} | {Yes/No} | {parameter_description} |
+  - **Request Body** (POST/PUT requests only):
+    ```json
+    {
+      "{field_name}": "{field_value}",
+      "{field_name}": "{field_value}"
+    }
+    ```
+    - **Request Field Definitions**:
+
+      | Field Name | Type | Required | Description |
+      | :--- | :--- | :--- | :--- |
+      | `{field_name}` | {type} | {Yes/No} | {field_description} |
+- **Response**:
+  - **Response Structure**: Follows standard response structure `R<T>`
+    ```json
+    {
+      "code": 200,
+      "msg": "success",
+      "data": {response_data}
+    }
+    ```
+  - **Response Field Definitions**:
+
+    | Field Name | Type | Description |
+    | :--- | :--- | :--- |
+    | `{field_name}` | {type} | {field_description} |
+  - **Response Example**:
+    ```json
+    {
+      "code": 200,
+      "msg": "success",
+      "data": {
+        "{field_name}": "{field_value}"
+      }
+    }
+    ```
+  - **Error Response Example**:
+    ```json
+    {
+      "code": 400,
+      "msg": "Parameter error",
+      "data": null
+    }
+    ```
+
+### 3.2 {Interface Name 2}
+
+- **Interface URL**: `{Method} {Interface Path}`
+- **Description**:
+  - This interface corresponds to backend `{Controller Class Name}#{Method Name}`.
+  - {Interface functionality description}
+- **Request**:
+  - Method: `{GET/POST/PUT/DELETE}`
+  - URL: `{Interface Path}`
+  - **Query Parameters**:
+
+    | Parameter Name | Type | Required | Description |
+    | :--- | :--- | :--- | :--- |
+    | `{parameter_name}` | {type} | {Yes/No} | {parameter_description} |
+- **Response**:
+  - Returns `{Response Type}` object/list.
+  - **Response Field Definitions ({Response Type})**:
+
+    | Field Name | Type | Description |
+    | :--- | :--- | :--- |
+    | `{field_name}` | {type} | {field_description} |
+  - **Response Example**:
+    ```json
+    {
+      "code": 200,
+      "msg": "success",
+      "data": [
+        {
+          "{field_name}": "{field_value}"
+        }
+      ]
+    }
+    ```
+
+---
+
+## 4. Standard Response Structure
+
+### 4.1 Standard Response Format
+
+All interfaces follow a unified response structure:
+
+```typescript
+interface ApiResponse<T> {
+  code: number;      // 200: Success, >200: Business error
+  msg: string;       // Message
+  data: T;           // Business data
+}
+```
+
+### 4.2 Pagination Response Format
+
+Pagination query interfaces return pagination structure:
+
+```typescript
+interface PageResponse<T> {
+  records: T[];      // Data list
+  total: number;     // Total records
+  size: number;      // Page size
+  current: number;   // Current page
+  pages: number;     // Total pages
+}
+```
+
+### 4.3 Error Code Conventions
+
+| Error Code | Description | Handling Suggestion |
+| :--- | :--- | :--- |
+| 200 | Success | - |
+| 400 | Parameter error | Toast error message |
+| 401 | Token expired | Redirect to login page |
+| 403 | No permission | Toast "No permission to access" |
+| 404 | Resource not found | Toast "Resource not found" |
+| 500 | Server error | Toast "Server error, please try again later" |
+
+---
+
+## 5. Request Header Specifications
+
+All interface requests need to automatically inject the following request headers:
+
+| Header | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `Authorization` | String | Yes | Bearer Token (user authentication credential) |
+| `App-Id` | String | No | Application ID |
+| `App-Channel` | String | No | Application Channel |
+| `App-Version` | String | No | Application Version |
+| `System-Id` | String | No | System ID |
+| `Tenant-Id` | String | Yes | Tenant ID |
+
+---
+
+## 6. Important Notes
+
+1. **System Isolation**: All interfaces need to validate `System-Id` to ensure data isolation
+2. **Application Isolation**: All interfaces need to validate `App-Id` to ensure application data isolation
+3. **Multi-tenant Isolation**: All interfaces need to validate `Tenant-Id` to ensure tenant data isolation
+4. **Permission Control**: Interfaces need to validate user permissions to ensure only authorized data operations
+5. **Parameter Validation**: All required parameters need to be validated, parameter errors return 400 error code
+6. **Exception Handling**: Interface exceptions need to return unified error response format
+7. **Data Format**: Time fields uniformly use `yyyy-MM-dd HH:mm:ss` format
+8. **Amount Fields**: Amount fields uniformly use `BigDecimal` type, retain 2 decimal places
+
+---
+
+**Document Version**: V1.0.0  
+**Created Date**: {Date}  
+**Last Updated**: {Date}  
+**Maintainer**: {Maintainer}

skills/api-doc-generator/templates/接口文档模板.md

@@ -0,0 +1,212 @@
+# {产品名称} - {模块名称}接口文档 V1.0
+
+## 1. 文档概览
+
+### 1.1 版本记录
+| 版本号 | 修改日期 | 修改人 | 修改内容  | 备注 |
+| :--- | :--- | :--- |:------| :--- |
+| V1.0.0 | {日期} | - | 初始版本  | - |
+
+### 1.2 责任人
+| 角色 | 姓名 | 职责 |
+| :--- | :--- | :--- |
+| 前端 | - | 接口对接、联调 |
+| 后端 | - | 接口开发、文档维护 |
+| 测试 | - | 接口测试、质量把控 |
+
+---
+
+## 2. 接口一览表
+
+| 序号 | 接口地址 | 请求方式 | 说明 | 完成情况 |
+| :--- | :--- | :--- | :--- | :--- |
+| 1 | `{接口路径}` | `{GET/POST/PUT/DELETE}` | {接口说明} | ✅ 已完成 / ⏳ 进行中 / ❌ 未开始 |
+
+---
+
+## 3. 接口定义
+
+### 3.1 {接口名称}
+
+- **接口地址**: `{请求方式} {接口路径}`
+- **说明**：
+  - 该接口对应后端 `{Controller类名}#{方法名}`。
+  - {接口功能描述}
+  - {业务规则说明}
+- **Request**:
+  - Method: `{GET/POST/PUT/DELETE}`
+  - URL: `{接口路径}`
+  - **Headers**:
+
+    | 参数名             | 类型 | 必填 | 说明                   |
+    |:----------------| :--- | :--- |:---------------------|
+    | `Authorization` | String | 是 | Bearer Token（用户登录凭证） |
+    | `App-Id`        | String | 否 | 应用ID                 |
+    | `App-Channel`   | String | 否 | 应用渠道                 |
+    | `App-Version`   | String | 否 | 应用版本                 |
+    | `System-Id`     | String | 否 | 系统ID                 |
+    | `Tenant-Id`     | String | 是 | 租户ID                 |
+  - **Path Parameters**:
+  - 
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | `{参数名}` | {类型} | {是/否} | {参数说明} |
+  - **Query Parameters**:
+  - 
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | `{参数名}` | {类型} | {是/否} | {参数说明} |
+  - **Request Body** (仅 POST/PUT 请求):
+    ```json
+    {
+      "{字段名}": "{字段值}",
+      "{字段名}": "{字段值}"
+    }
+    ```
+    - **请求字段说明**:
+    
+      | 字段名 | 类型 | 必填 | 说明 |
+      | :--- | :--- | :--- | :--- |
+      | `{字段名}` | {类型} | {是/否} | {字段说明} |
+- **Response**:
+  - **响应结构**: 遵循统一响应结构 `R<T>`
+    ```json
+    {
+      "code": 200,
+      "msg": "success",
+      "data": {响应数据}
+    }
+    ```
+  - **响应字段详细说明**:
+  
+    | 字段名 | 类型 | 说明 |
+    | :--- | :--- | :--- |
+    | `{字段名}` | {类型} | {字段说明} |
+  - **响应示例**:
+    ```json
+    {
+      "code": 200,
+      "msg": "success",
+      "data": {
+        "{字段名}": "{字段值}"
+      }
+    }
+    ```
+  - **错误响应示例**:
+    ```json
+    {
+      "code": 400,
+      "msg": "参数错误",
+      "data": null
+    }
+    ```
+
+### 3.2 {接口名称2}
+
+- **接口地址**: `{请求方式} {接口路径}`
+- **说明**：
+  - 该接口对应后端 `{Controller类名}#{方法名}`。
+  - {接口功能描述}
+- **Request**:
+  - Method: `{GET/POST/PUT/DELETE}`
+  - URL: `{接口路径}`
+  - **Query Parameters**:
+  
+    | 参数名 | 类型 | 必填 | 说明 |
+    | :--- | :--- | :--- | :--- |
+    | `{参数名}` | {类型} | {是/否} | {参数说明} |
+- **Response**:
+  - 返回 `{响应类型}` 对象/列表。
+  - **响应字段详细说明 ({响应类型})**:
+  
+    | 字段名 | 类型 | 说明 |
+    | :--- | :--- | :--- |
+    | `{字段名}` | {类型} | {字段说明} |
+  - **响应示例**:
+    ```json
+    {
+      "code": 200,
+      "msg": "success",
+      "data": [
+        {
+          "{字段名}": "{字段值}"
+        }
+      ]
+    }
+    ```
+
+---
+
+## 4. 统一响应结构
+
+### 4.1 标准响应格式
+
+所有接口遵循统一的响应结构：
+
+```typescript
+interface ApiResponse<T> {
+  code: number;      // 200: 成功, >200: 业务错误
+  msg: string;       // 提示信息
+  data: T;           // 业务数据
+}
+```
+
+### 4.2 分页响应格式
+
+分页查询接口返回分页结构：
+
+```typescript
+interface PageResponse<T> {
+  records: T[];      // 数据列表
+  total: number;     // 总记录数
+  size: number;      // 每页数量
+  current: number;    // 当前页码
+  pages: number;     // 总页数
+}
+```
+
+### 4.3 错误码约定
+
+| 错误码 | 描述 | 处理建议 |
+| :--- | :--- | :--- |
+| 200 | 成功 | - |
+| 400 | 参数错误 | Toast提示错误信息 |
+| 401 | Token过期 | 跳转登录页 |
+| 403 | 无权限 | Toast提示"无权限访问" |
+| 404 | 资源不存在 | Toast提示"资源不存在" |
+| 500 | 服务器错误 | Toast提示"服务器错误，请稍后重试" |
+
+---
+
+## 5. 请求头规范
+
+所有接口请求需要自动注入以下请求头：
+
+| 请求头 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `Authorization` | String | 是 | Bearer Token（用户登录凭证） |
+| `App-Id`        | String | 否 | 应用ID                 |
+| `App-Channel`   | String | 否 | 应用渠道                 |
+| `App-Version`   | String | 否 | 应用版本                 |
+| `System-Id`     | String | 否 | 系统ID                 |
+| `Tenant-Id`     | String | 是 | 租户ID                 |
+
+---
+
+## 6. 注意事项
+
+1. **系统隔离**：所有接口都需要校验`System-Id`，确保只能操作当前系统的数据
+2. **应用隔离**：所有接口都需要校验`App-Id`，确保只能操作当前应用的数据
+3. **多租户隔离**：所有接口都需要校验`Tenant-Id`，确保租户数据隔离
+4. **权限控制**：接口需要校验用户权限，确保只能操作有权限的数据
+5. **参数校验**：所有必填参数都需要进行校验，参数错误返回400错误码
+6. **异常处理**：接口异常需要返回统一的错误响应格式
+7. **数据格式**：时间字段统一使用 `yyyy-MM-dd HH:mm:ss` 格式
+8. **金额字段**：金额字段统一使用 `BigDecimal` 类型，保留2位小数
+
+---
+
+**文档版本**：V1.0.0  
+**创建时间**：{日期}  
+**最后更新**：{日期}  
+**维护人**：{维护人}