自动化文档更新指南

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

概述

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

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

配置

必需的 Secrets

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

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

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

如何获取智谱 API Key

访问智谱 AI 开放平台
注册或登录您的账户
导航到 API Key 管理
创建新的 API 密钥
复制密钥并添加到 GitHub Secrets

必需的权限

确保 GitHub Actions 具有写入权限：

转到 Settings → Actions → General
在 Workflow permissions 下，选择：
✅ Read and write permissions
点击 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 响应：

{
  "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 中添加英文评论：

## 📝 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

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

查看结果

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

手动验证

在本地验证更改：

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

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

本地测试

先决条件

# 安装 Python 依赖
pip install requests

设置环境变量

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"

运行脚本

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

典型使用的费用非常低。

高级配置

使用不同的模型

要使用不同的智谱模型：

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

自定义文档章节

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

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

跳过工作流程

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

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

贡献

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

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

支持

遇到问题或有疑问时：

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