Skill2

SKILL.md

\---

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）



\## 输出格式示例

```markdown

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



\## 概述

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



\## 函数：register\_user



\### 语法

```python

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