自动生成技术文档助手

## 功能概述

自动生成技术文档助手是一款基于大语言模型的写作插件，专为开发者设计。它能够读取代码文件中的注释、函数签名、类结构以及变量定义，自动提取关键信息并生成符合业界规范的技术文档。生成的文档包括模块说明、函数/方法使用示例、参数描述、返回值说明以及异常处理提示，帮助团队快速产出高质量的内部或外部文档。

## 核心特性

- **多语言支持**：兼容 JavaScript/TypeScript、Python、Java、C#、Go、Rust 等主流编程语言的源码解析。
- **结构化输出**：文档以 Markdown 格式呈现，支持章节编号、代码块、表格和链接，便于在 GitHub、GitLab、Confluence 等平台直接展示。
- **自定义模板**：用户可提供公司或项目专属的文档模板，系统会按照模板的占位符自动填充内容。
- **上下文感知**：结合代码文件的整体上下文（如文件头部的 license、作者信息）生成统一的文档头部。
- **增量更新**：支持对已有文档进行增量合并，只更新变化的部分，保留原有内容不被覆盖。
- **批处理模式**：一次请求可处理多个文件或整个目录，生成完整的项目文档集合。

## 使用场景

1. **新项目启动**：在代码编写阶段即生成 API 参考手册，减少后期文档编写的工作量。
2. **代码重构**：重构后快速更新文档，确保文档与最新实现同步。
3. **开源项目**：对外提供详细的使用说明，提升项目可维护性和社区参与度。
4. **内部知识库**：将代码注释转化为内部培训材料，帮助新成员快速上手。
5. **自动化CI/CD**：在代码提交后自动触发文档生成任务，实现文档持续交付。

## 调用步骤

### 1. 环境准备
- 确保已安装 Node.js（>=14）或 Python（>=3.8）环境。
- 安装插件对应的 SDK：`npm install doc-gen-sdk` 或 `pip install doc-gen-sdk`。
- 获取 API Key（在官方平台注册后获得），并在本地环境变量中配置 `DOC_GEN_API_KEY`。

### 2. 编写配置文件
在项目根目录创建 `docgen.config.json`，示例：
```json
{
  "source": "./src",
  "output": "./docs",
  "language": "zh-CN",
  "template": "./templates/api-template.md",
  "exclude": ["node_modules", "*.test.ts"],
  "incremental": true
}
```
- `source`：源码目录路径。
- `output`：生成的文档存放路径。
- `language`：文档语言，默认为 `zh-CN`。
- `template`：自定义模板文件路径（可选）。
- `exclude`：排除的目录或文件（支持 glob 语法）。
- `incremental`：是否启用增量更新。

### 3. 调用插件
使用 SDK 提供的 `generate()` 方法即可完成文档生成：
```javascript
const { DocGen } = require('doc-gen-sdk');

async function main() {
  const docGen = new DocGen({
    apiKey: process.env.DOC_GEN_API_KEY
  });

  const result = await docGen.generate('./docgen.config.json');
  console.log(`文档已生成：${result.outputDir}`);
}

main().catch(console.error);
```
或使用 Python：
```python
from doc_gen_sdk import DocGen
import os

def main():
    doc_gen = DocGen(api_key=os.getenv('DOC_GEN_API_KEY'))
    result = doc_gen.generate('./docgen.config.json')
    print(f'文档已生成：{result["output_dir"]}')

if __name__ == '__main__':
    main()
```

### 4. 查看生成的文档
生成完成后，系统会在 `output` 目录中创建对应的 Markdown 文件。例如：
- `src/utils/helper.md` → `docs/utils/helper.md`
- `src/api/user.md` → `docs/api/user.md`

打开文件即可查看完整的函数说明、使用示例以及注意事项。

## 注意事项

1. **注释质量决定文档质量**：为保证生成结果的准确性，请在代码中使用标准化的注释风格（如 JSDoc、DocString）。
2. **敏感信息处理**：插件会自动过滤常见的敏感信息（如密码、API Key），但仍建议在代码中避免硬编码机密内容。
3. **自定义模板需遵循占位符规范**：模板中必须使用 `{{module}}`、`{{function}}`、`{{param}}`、`{{return}}` 等占位符，否则系统无法正确填充。
4. **增量更新仅在启用 `incremental` 时生效**：若禁用该选项，每次生成都会覆盖已有文档，可能导致手工添加的说明被删除。
5. **文件编码要求**：源码文件请使用 UTF-8 编码，否则可能导致解析错误。
6. **API 访问限制**：免费版每日调用次数上限为 100 次，超出后需升级至付费套餐或等待次日重置。
7. **生成的内容仍需人工审阅**：自动生成的文档仅供参考，重要业务逻辑、错误码解释等仍建议由业务负责人复核。
8. **多语言项目请明确语言标识**：在 `docgen.config.json` 中设置 `language` 为对应语言，以确保文档标题、描述等文字符合当地阅读习惯。

## 进阶使用

- **自定义解析器**：如需支持尚未覆盖的语言，可实现 `Parser` 接口并注册到 SDK，示例请参考官方文档的《扩展解析器》章节。
- **CI/CD 集成**：将 `doc-gen-sdk` 集成到 GitHub Actions、GitLab CI 或 Jenkins，实现代码提交后自动触发文档更新。
- **文档版本管理**：结合 Git 或 SVN，对生成的 Markdown 文件进行版本控制，确保文档历史可追溯。
- **多租户 SaaS**：若需要为不同客户提供独立的文档生成服务，可在插件中配置 `tenant_id`，实现资源隔离。

## 常见问题（FAQ）

- **Q：生成的文档缺少某些函数的说明？**
  A：请检查源码中对应函数是否有完整的注释或符合项目注释规范的注释块。

- **Q：模板渲染后出现乱码？**
  A：确保模板文件本身使用 UTF-8 编码，并且在模板中使用的占位符与 SDK 要求保持一致。

- **Q：是否支持本地离线生成？**
  A：当前版本需要联网调用大模型 API，后续将提供本地模型部署选项。

---

使用自动生成技术文档助手，让文档编写从繁琐的手工劳动中解放出来，帮助团队更专注于代码本身的实现与创新。