# 自动化文档更新指南

本指南介绍使用智谱 GLM-4.5-X API 的 GNS3 Copilot 项目自动文档更新系统。

## 概述

当您创建或更新到 `Development` 分支的 Pull Request (PR) 时，自动文档更新系统将：

1. **分析代码变更** - 检测源代码中的更改
2. **生成文档** - 使用智谱 GLM-4.5-X AI 生成文档更新
3. **更新文档** - 自动更新英文和中文文档文件
4. **提交更改** - 将文档更新提交到您的 PR 分支
5. **创建 PR 评论** - 在您的 PR 中添加英文摘要评论

## 配置

### 必需的 Secrets

在 GitHub 仓库中配置以下密钥：

1. 转到 **Settings** → **Secrets and variables** → **Actions**
2. 点击 **New repository secret** 并添加：

| Secret 名称 | 值 | 描述 |
|-------------|-----|------|
| `ZHIPU_API_KEY` | 您的智谱 API Key | 从 https://open.bigmodel.cn/ 获取 |
| `ZHIPU_MODEL` | `glm-4-flash`（推荐） | 快速且经济的模型 |

#### 如何获取智谱 API Key

1. 访问 [智谱 AI 开放平台](https://open.bigmodel.cn/)
2. 注册或登录您的账户
3. 导航到 **API Key 管理**
4. 创建新的 API 密钥
5. 复制密钥并添加到 GitHub Secrets

### 必需的权限

确保 GitHub Actions 具有写入权限：

1. 转到 **Settings** → **Actions** → **General**
2. 在 **Workflow permissions** 下，选择：
   - ✅ **Read and write permissions**
3. 点击 **Save**

## 工作流程

### 触发事件

工作流程在以下 PR 事件触发：
- `opened` - 创建新 PR
- `synchronize` - 使用新提交更新 PR 分支
- `reopened` - 重新打开之前关闭的 PR

### 流程图

```
PR 创建/更新
    ↓
触发 GitHub Actions
    ↓
检出代码并获取 Development 分支
    ↓
运行 auto_update_docs.py
    ↓
    ├─ 获取 git diff
    ├─ 过滤源代码变更
    ├─ 调用智谱 GLM-4.5-X API
    ├─ 解析 AI 响应（JSON）
    ├─ 更新 README.md（英文）
    ├─ 更新 README_ZH.md（中文）
    ├─ 更新 docs/*.md（英文）
    └─ 更新 Architecture/*.md（英文）
    ↓
提交文档更新
    ↓
推送更改到 PR 分支
    ↓
创建英文 PR 评论
```

## 更新的文档

系统可以更新以下文档文件：

| 文件 | 语言 | 更新时机 |
|------|------|----------|
| `README.md` | 英文 | 新功能、配置更改 |
| `README_ZH.md` | 中文 | 新功能、配置更改 |
| `docs/packaging-guide.md` | 英文 | 依赖更改 |
| `docs/manual_testing_guide.md` | 英文 | 新测试 |
| `Architecture/gns3_copilot_architecture.md` | 英文 | 架构更改 |

## AI 输出格式

智谱 GLM-4.5-X API 返回 JSON 响应：

```json
{
  "english_summary": "Added new tool for GNS3 node management",
  "chinese_summary": "新增 GNS3 节点管理工具",
  "doc_updates": {
    "README.md": {
      "section": "Features",
      "content": "- Added new GNS3 node management tool\n  - Supports node creation and deletion"
    },
    "README_ZH.md": {
      "section": "功能列表",
      "content": "- 新增 GNS3 节点管理工具\n  - 支持节点创建和删除"
    }
  }
}
```

## PR 评论格式

系统自动在您的 PR 中添加英文评论：

```markdown
## 📝 Documentation Update Summary

Added new tool for GNS3 node management. The tool supports creating and deleting nodes in GNS3 topologies.

---
*This comment was automatically generated by Zhipu GLM-4.5-X API*
```

## 使用示例

### 创建 PR

1. 更改源代码
2. 提交更改
3. 推送到新分支
4. 创建到 `Development` 分支的 PR
5. 工作流程将自动：
   - 在后台运行
   - 更新文档
   - 添加 PR 评论

### 查看结果

检查 PR 中的 **Actions** 标签页以查看：
- 工作流程执行状态
- 详细日志
- 更新的文档文件

### 手动验证

在本地验证更改：

```bash
# 获取更新后的分支
git fetch origin

# 检查文档更新
git diff origin/Development...HEAD -- README.md
git diff origin/Development...HEAD -- README_ZH.md
```

## 本地测试

### 先决条件

```bash
# 安装 Python 依赖
pip install requests
```

### 设置环境变量

```bash
export ZHIPU_API_KEY="your-api-key"
export ZHIPU_MODEL="glm-4-flash"
export PR_NUMBER="test"
export GITHUB_TOKEN="test"
export REPO_OWNER="test"
export REPO_NAME="test"
```

### 运行脚本

```bash
python scripts/auto_update_docs.py
```

## 故障排除

### 工作流程未触发

**问题**: 创建 PR 时工作流程不运行。

**解决方案**:
- 确保 PR 目标是 `Development` 分支
- 检查工作流程文件路径：`.github/workflows/auto-doc-update.yaml`
- 验证在仓库设置中启用了 GitHub Actions

### API Key 错误

**问题**: `ERROR: ZHIPU_API_KEY not found`

**解决方案**:
- 检查 `ZHIPU_API_KEY` 是否添加到仓库 Secrets
- 验证密钥名称完全为 `ZHIPU_API_KEY`
- 确保密钥值正确

### API 调用失败

**问题**: `API Error 401: Unauthorized`

**解决方案**:
- 验证您的智谱 API 密钥有效
- 检查 API 密钥是否有足够权限
- 确保您有足够的 API 配额

### 权限被拒绝

**问题**: `fatal: could not read Username for 'https://github.com'`

**解决方案**:
- 为 GitHub Actions 启用写入权限
- 检查工作流程权限：**Settings** → **Actions** → **General**
- 确保令牌具有 `contents: write` 权限

### 没有文档更新

**问题**: 文档文件未更新

**解决方案**:
- 检查工作流程日志中的 AI 响应
- 验证 JSON 响应格式正确
- 确保文档文件存在
- 检查章节格式是否正确

### Git 推送失败

**问题**: 更改未推送到 PR 分支

**解决方案**:
- 验证 `GITHUB_TOKEN` 具有写入权限
- 检查分支是否受保护
- 确保 PR 不是来自 fork

## 费用

使用 `glm-4-flash` 模型：

| 指标 | 估算 |
|------|------|
| 每个 PR 的 Tokens | ~1,500 tokens |
| 每个 PR 的费用 | ~¥0.00075 |
| 每月 50 个 PR 的费用 | ~¥0.0375 |

典型使用的费用非常低。

## 高级配置

### 使用不同的模型

要使用不同的智谱模型：

1. 使用您偏好的模型添加 `ZHIPU_MODEL` 密钥
2. 可用模型：
   - `glm-4-flash` - 快速、低成本（推荐）
   - `glm-4` - 标准性能
   - `glm-4-plus` - 高性能

### 自定义文档章节

修改脚本以定位不同的章节：

```python
# 在 scripts/auto_update_docs.py 中
doc_updates = {
    "README.md": {
        "section": "自定义章节",
        "content": "您的自定义内容"
    }
}
```

### 跳过工作流程

要跳过自动文档更新，在提交消息中添加 `[skip doc]`：

```bash
git commit -m "添加新功能 [skip doc]"
```

## 贡献

为自动文档系统做贡献时：

1. 推送前在本地测试更改
2. 确保 API 密钥配置正确
3. 在 Actions 标签页中验证工作流程执行
4. 检查 PR 评论是否正确生成

## 支持

遇到问题或有疑问时：

1. 首先查阅本指南
2. 在 Actions 标签页中查看工作流程日志
3. 在仓库中创建 issue
4. 联系维护者寻求帮助

## 参考资料

- [智谱 AI 文档](https://open.bigmodel.cn/dev/api)
- [GitHub Actions 文档](https://docs.github.com/en/actions)
- [PyProject.toml](../pyproject.toml) - 项目配置
- [打包指南](packaging-guide.md) - 打包文档
