- name
- doc-generator
- description
- |
文档生成器 (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 --chinese2. 通用文档分析（任意语言）
对于非 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. 输出到飞书文档
提取内容后，使用飞书文档工具创建云文档：
步骤：
- 运行
extract_api.py生成 Markdown 内容（或 Agent 直接生成） - 调用飞书文档创建工具（
feishu-create-docskill）将内容写入飞书
飞书输出要求（遵循 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} |输出格式选择
| 格式 | 适用场景 | 工具 |
|---|---|---|
| 飞书文档 | 团队协作、项目文档 | feishu-create-doc |
| 本地 Markdown | Git 版本管理、README | write |
| OpenAPI YAML | API 规范、代码生成 | write + 格式化 |
注意事项
- 代码优先：从代码实际实现提取，不臆造接口
- 类型准确：参数和返回值类型必须与代码一致
- 示例真实：使用真实可运行的示例数据
- 错误完整：列出所有可能的错误码和处理建议
- 版本标注：标注 API 版本和文档更新时间
- 飞书格式：输出到飞书时使用 Lark-flavored Markdown，不使用标准 Markdown 表格替代
<lark-table>