AI技术文档自动生成工具

## 技能简介
AI技术文档自动生成工具能够解析源代码中的注释、函数签名以及类结构，将其转换为符合行业规范的技术文档。该工具支持多种编程语言（如 Python、Java、JavaScript、C# 等），并能够生成 Markdown、HTML 或 JSON 格式的输出，便于直接嵌入项目文档或 API 文档站点。

## 适用场景
- **新项目启动**：在编写核心代码的同时自动生成接口文档，降低后期文档维护成本。
- **代码重构**：快速生成重构后函数的文档，确保新旧接口同步更新。
- **团队协作**：统一文档风格，提升代码可读性和团队沟通效率。
- **自动化 CI/CD**：在代码提交后触发文档生成，实现文档的持续更新。

## 输入要求
1. **源代码文件**：支持单个文件或多个文件（zip/tar 包）。
2. **注释格式**：推荐使用 Javadoc、Docstring、Doxygen 或 XML 注释等标准化格式。若使用非标准注释，工具会尽力提取，但仍可能影响文档完整性。
3. **函数签名**：必须包含函数名、参数列表、返回值类型（若有）以及可见性修饰符（public、private 等）。
4. **额外元数据**（可选）：如作者、版本号、许可证信息，可在文件头部添加专用标签。

## 调用步骤
1. **准备输入**：将待处理的源代码文件放入指定目录或压缩包中。确保文件编码为 UTF-8，以避免字符乱码。
2. **发送请求**：使用如下 JSON 结构向模型发起调用：
```json
{
  "source_code": "....",
  "output_format": "markdown",
  "language": "python"
}
```
   - `source_code`：源代码的完整文本或 Base64 编码的压缩文件路径。
   - `output_format`：可选 `markdown`、`html`、`json`，默认 `markdown`。
   - `language`：目标语言标识，如 `python`、`java`，帮助模型选择对应的文档模板。
3. **等待处理**：模型会在数秒内完成解析并返回生成的文档内容。
4. **检查结果**：审阅生成的文档，确保注释、参数说明、返回值描述完整且符合项目规范。
5. **保存或发布**：将文档保存为相应文件（如 `README.md`）或直接提交到文档仓库。

## 输出示例（Markdown）
```markdown
## `add(int a, int b)`

**功能**：返回两个整数的和。

**参数**：
- `a` (int) – 第一个加数。
- `b` (int) – 第二个加数。

**返回值**：int，和的结果。

**示例**：
```python
result = add(2, 3)  # result = 5
```
```

## 注意事项
- **注释质量**：文档的完整性高度依赖源码中注释的完整性与规范性。建议在函数声明前使用统一的注释模板。
- **多语言混用**：若项目包含多种语言，务必在请求中指定对应语言的 `language`，否则可能产生语言不匹配的文档模板。
- **安全性**：上传的源代码可能包含业务敏感信息，请确保在可信的环境中使用，或先对代码进行脱敏处理。
- **自定义模板**：系统支持用户自定义文档模板（通过 `template` 参数），可针对公司内部文档规范进行适配。
- **错误处理**：若解析失败（如缺少必要注释），模型会返回警告信息并尽可能补全缺失部分，用户应仔细核对。

## 常见问题（FAQ）
- **Q: 生成的文档出现乱码怎么办？**  
  A: 请确认源代码文件使用 UTF-8 编码，并在请求时指定正确的语言标识。
- **Q: 支持的编程语言有哪些？**  
  A: 目前已支持 Python、Java、JavaScript、C#、Go、Rust 等常见语言，其他语言会逐步扩展。
- **Q: 如何在 CI/CD 流程中集成？**  
  A: 可以将生成的文档通过 webhook 自动推送到文档仓库，或在构建脚本中使用 `curl` 调用本服务的 API。

通过上述流程，用户可以快速将手写代码转化为专业、易读的技术文档，显著提升项目文档化的效率和质量。