Skill2

自动解析代码或接口定义，生成结构清晰、格式规范的技术文档，包括参数说明、使用示例和依赖关系。

---

name: doc-autogen

description: 根据代码或接口定义自动生成清晰的技术文档，包括 API 参考、函数说明、使用示例和依赖关系。

version: 1.0.0

author: your-name

tags:

- documentation

- api

- code-generation

triggers:

- 生成文档

- 写API文档

- generate documentation

- document this code

---

# Doc-Autogen Skill

## 描述

这是一个智能文档生成技能，能够解析代码、函数签名或 API 定义，自动生成结构清晰、格式规范的技术文档，包括概述、参数说明、使用示例和注意事项。

## 使用场景

当用户提供代码文件、函数签名、OpenAPI/Swagger 定义，或要求为项目生成技术文档时激活。

## 工作流程

### 第一步：解析输入内容

识别用户提供的输入类型，选择对应的解析策略：

1. **函数/类代码**

- 提取函数名、参数列表、返回值类型

- 识别异常抛出

- 分析依赖关系（导入的模块）

2. **OpenAPI/Swagger JSON/YAML**

- 解析端点定义（URL、HTTP 方法）

- 提取请求/响应模式

- 识别认证方式

3. **纯文本描述**

- 根据用户描述补全为标准技术文档格式

- 引导用户提供必要信息

### 第二步：生成文档结构

根据解析结果，自动生成以下章节：

#### 基础结构

- **概述（Overview）**：模块或接口的核心作用和业务场景

- **语法/端点（Syntax/Endpoint）**：函数签名或 API 地址

#### 详细说明

- **参数表（Parameters）**：使用表格列出所有参数

| 参数名 | 类型 | 必选 | 默认值 | 描述 |

|---|---|---|---|---|

| param1 | string | 是 | - | 参数说明 |

- **返回值/响应示例**：成功和失败的返回格式

- **调用示例**：至少一个可运行的代码示例

#### 扩展信息

- **注意事项**：错误码、限流策略、版本兼容性、性能建议

- **依赖关系**：所需的外部库或服务

### 第三步：格式化输出

- 使用 Markdown 格式，确保可读性

- 合理使用表格、代码块、列表

- 保持语言简洁、无歧义

### 第四步：生成完整文档（多文件场景）

如果用户提供多个文件或模块：

- 生成带目录的完整文档集

- 自动交叉引用相关模块

- 创建索引页方便导航

## 注意事项

- 如果参数类型不明确，标注为 "待定" 并提示用户补充

- 对于复杂嵌套对象，提供 JSON Schema 或类型定义

- 如果用户要求"输出为 PDF/HTML"，则在纯文本下提供转换命令建议（如 pandoc）

## 输出格式示例

\# API 文档：用户管理模块



\## 概述

提供用户注册、登录和资料查询功能。



\## 函数：register\_user



\### 语法

```python

def register\_user(username: str, email: str, password: str) -> dict