doc-generator

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

# 从目录递归提取，输出 OpenAPI 格式
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

/**
 * 获取用户信息
 * @param {string} userId - 用户ID
 * @returns {Promise<User>} 用户对象
 * @throws {NotFoundError} 用户不存在时抛出
 */
async function getUser(userId) { ... }

提取规则：

• @param {type} name - description → 参数表
• @returns {type} description → 返回值
• @throws {ErrorType} description → 错误码
• 路由装饰器 app.get('/path') → 端点信息

Go

// GetUser godoc
// @Summary 获取用户
// @Param id path string true "用户ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
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. 输出到飞书文档

提取内容后，使用飞书文档工具创建云文档：

步骤：

1. 运行 extract_api.py 生成 Markdown 内容（或 Agent 直接生成）
2. 调用飞书文档创建工具（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参数行}
</lark-table>

**请求示例**：

```{lang}
{code example}

响应示例：

{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

核心流程

1. 步骤一：{说明}
2. 步骤二：{说明}
3. 步骤三：{说明}

数据模型

字段	类型	说明
id	bigint	主键
name	varchar	名称

影响范围

• 模块 A：{影响说明}
• 模块 B：{影响说明}

排期

阶段	时间	负责人
设计评审	{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>`