| name | doc-generator |
| description | 从源代码自动生成 API 文档、技术文档，支持输出到飞书云文档。包含代码注释提取、
中文文档模板、OpenAPI 规范生成等功能。
**触发场景**：
- 用户要求"生成文档"、"写 API 文档"、"自动生成文档"
- 需要从代码提取注释生成文档
- 需要输出文档到飞书
- 用户提到"API 文档"、"接口文档"、"技术文档"
|
文档生成器 (Doc Generator)
从源代码自动生成结构化技术文档，支持飞书云文档输出。
核心能力
| 能力 | 说明 |
|---|
| API 文档生成 | 从代码提取端点、参数、返回值 |
| 代码注释提取 | 解析 JSDoc / Python docstring / Go doc |
| 飞书文档输出 | 直接创建飞书云文档 |
| 中文模板 | 预置中文技术文档模板 |
| OpenAPI 规范 | 生成 OpenAPI 3.0 YAML/JSON |
工作流程
flowchart LR
A[源代码] --> B[代码分析]
B --> C[注释提取]
C --> D[文档生成]
D --> E{输出目标}
E -->|飞书| F[飞书云文档]
E -->|本地| G[Markdown 文件]
E -->|OpenAPI| H[YAML 规范]
使用方式
1. 提取代码注释（Python）
使用内置脚本从 Python 代码提取 API 信息：
python3 <skill_dir>/scripts/extract_api.py <source_file_or_dir> [--lang python|js|go] [--format markdown|json|openapi]
参数说明：
<source_file_or_dir>：源文件或目录路径--lang：代码语言（python/js/go），默认自动检测--format：输出格式（markdown/json/openapi），默认 markdown--output：输出文件路径（可选，不指定则输出到 stdout）--chinese：使用中文模板（默认中文）--title：文档标题
示例：
python3 scripts/extract_api.py app/routes.py --format markdown
python3 scripts/extract_api.py ./src/api --format openapi --title "用户服务 API"
python3 scripts/extract_api.py app.py --output docs/api.md --chinese
2. 通用文档分析（任意语言）
对于非 Python 代码，Agent 直接读取源文件，按以下规则提取：
JavaScript/TypeScript
async function getUser(userId) { ... }
提取规则：
@param {type} name - description → 参数表@returns {type} description → 返回值@throws {ErrorType} description → 错误码- 路由装饰器
app.get('/path') → 端点信息
Go
func GetUser(c *gin.Context) { ... }
提取规则：
// @Summary → 描述// @Param → 参数// @Success / // @Failure → 响应// @Router → 端点路径
Python (FastAPI / Flask / Django)
@app.get("/users/{user_id}")
async def get_user(user_id: str) -> User:
"""获取用户信息
Args:
user_id: 用户唯一标识
Returns:
User: 用户对象
Raises:
HTTPException: 用户不存在
"""
提取规则：
- 路由装饰器 → 端点路径和方法
- 函数签名 type hints → 参数/返回类型
- docstring (Google/NumPy/Sphinx 格式) → 描述、参数、返回值、异常
3. 输出到飞书文档
提取内容后，使用飞书文档工具创建云文档：
步骤：
- 运行
extract_api.py 生成 Markdown 内容（或 Agent 直接生成）
- 调用飞书文档创建工具（
feishu-create-doc skill）将内容写入飞书
飞书输出要求（遵循 Lark-flavored Markdown 规范）：
- 使用
<callout> 高亮重要警告和提示
- 使用
<lark-table> 展示参数/返回值（复杂内容时）
- 使用
mermaid 代码块生成流程图/架构图
- 使用
<grid> 分栏对比不同方案
- 代码块必须标注语言类型
飞书文档结构模板：
<callout emoji="📋" background-color="light-blue">
文档版本：v1.0 | 最后更新：{date} | 维护人：{author}
</callout>
## 概述
{项目简介，2-3 句话说明 API 的核心功能}
## 认证方式
<callout emoji="🔑" background-color="light-yellow">
所有接口需要在 Header 中携带 Token：
`Authorization: Bearer {your_token}`
</callout>
{认证说明}
## 接口列表
### {METHOD} {path}
**接口说明**：{description}
<lark-table header-row="true">
<lark-tr>
<lark-td>**参数名**</lark-td>
<lark-td>**类型**</lark-td>
<lark-td>**必填**</lark-td>
<lark-td>**说明**</lark-td>
</lark-tr>
{lar参数行}
：
响应示例：
{response example}
**错误码**：{error codes}
### 4. 中文文档模板
#### API 接口文档模板
```markdown
# {项目名称} API 接口文档
## 文档信息
| 项目 | 内容 |
|------|------|
| 版本 | v1.0.0 |
| 更新日期 | {date} |
| 维护团队 | {team} |
| Base URL | `https://api.example.com/v1` |
## 快速开始
<callout emoji="🚀" background-color="light-green">
3 步接入：
1. 获取 API Key
2. 携带 Token 调用接口
3. 解析返回结果
</callout>
## 接口鉴权
所有请求需在 Header 中携带：
Authorization: Bearer <your_api_key>
Content-Type: application/json
## 接口详情
### 1. {接口名称}
**{METHOD}** `{path}`
{接口描述}
**请求参数**
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| {name} | {query/path/body} | {type} | 是/否 | {desc} |
**请求示例**
```bash
curl -X {METHOD} "{base_url}{path}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{request_body}'
响应示例
{
"code": 0,
"message": "success",
"data": { }
}
错误码
| 错误码 | 说明 | 处理建议 |
|---|
| 400 | 参数错误 | 检查请求参数 |
| 401 | 未授权 | 检查 Token 是否有效 |
| 404 | 资源不存在 | 检查资源 ID |
| 500 | 服务异常 | 联系技术支持 |
#### 技术方案文档模板
```markdown
# {方案名称} 技术方案
## 背景
{描述问题背景和需求来源}
## 目标
- 目标 1
- 目标 2
## 方案设计
### 整体架构
```mermaid
graph TD
A[客户端] --> B[API 网关]
B --> C[服务 A]
B --> D[服务 B]
C --> E[(数据库)]
D --> E
核心流程
- 步骤一：{说明}
- 步骤二：{说明}
- 步骤三：{说明}
数据模型
| 字段 | 类型 | 说明 |
|---|
| id | bigint | 主键 |
| name | varchar | 名称 |
影响范围
排期
| 阶段 | 时间 | 负责人 |
|---|
| 设计评审 | {date} | {person} |
| 开发 | {date} | {person} |
| 测试 | {date} | {person} |
| 上线 | {date} | {person} |
## 输出格式选择
| 格式 | 适用场景 | 工具 |
|------|----------|------|
| 飞书文档 | 团队协作、项目文档 | `feishu-create-doc` |
| 本地 Markdown | Git 版本管理、README | `write` |
| OpenAPI YAML | API 规范、代码生成 | `write` + 格式化 |
## 注意事项
- **代码优先**：从代码实际实现提取，不臆造接口
- **类型准确**：参数和返回值类型必须与代码一致
- **示例真实**：使用真实可运行的示例数据
- **错误完整**：列出所有可能的错误码和处理建议
- **版本标注**：标注 API 版本和文档更新时间
- **飞书格式**：输出到飞书时使用 Lark-flavored Markdown，不使用标准 Markdown 表格替代 `<lark-table>`
