oc-doc-generator（oc 文档生成器）

文档生成器 (Doc Generator)

从源代码自动生成结构化技术文档，支持飞书云文档输出。

核心能力

工作流程

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>

**请求示例**：

{code example}

**响应示例**：

{response example}

<callout emoji="⚠️" background-color="light-red">
**错误码**：{error codes}
</callout>

---

4. 中文文档模板

API 接口文档模板

# {项目名称} 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} |

**请求示例**

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 | 服务异常 | 联系技术支持 |

技术方案文档模板

# {方案名称} 技术方案

## 背景

{描述问题背景和需求来源}

## 目标

- 目标 1
- 目标 2

## 方案设计

### 整体架构

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} |

输出格式选择

注意事项

• 代码优先：从代码实际实现提取，不臆造接口
• 类型准确：参数和返回值类型必须与代码一致
• 示例真实：使用真实可运行的示例数据
• 错误完整：列出所有可能的错误码和处理建议
• 版本标注：标注 API 版本和文档更新时间
• 飞书格式：输出到飞书时使用 Lark-flavored Markdown，不使用标准 Markdown 表格替代 <lark-table>