Add documentation and scripts

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/github-token-permissions.md

@@ -0,0 +1,170 @@
+# GitHub Personal Access Token 权限配置指南
+
+## 问题：`refusing to allow a Personal Access Token to create or update workflow`
+
+### 原因
+
+GitHub 要求推送 `.github/workflows/` 目录下的文件时，Personal Access Token 必须包含 `workflow` 权限。
+
+### 解决方案
+
+## 方案一：更新 Token 权限（推荐）
+
+### 步骤 1：创建新的 Personal Access Token
+
+1. 访问：https://github.com/settings/tokens
+2. 点击 **Generate new token (classic)**
+3. 填写 Token 名称：`wecom-ai-assistant-full-access`
+4. 选择过期时间：根据你的需求（推荐 90 天或 No expiration）
+5. **选择以下权限**：
+   - ✅ **repo**（完整仓库访问权限）
+     - ✅ repo:status
+     - ✅ repo_deployment
+     - ✅ public_repo
+     - ✅ repo:invite
+     - ✅ security_events
+   - ✅ **workflow**（工作流权限）**← 必需**
+   - ✅ **write:packages**（推送 Docker 镜像到 GHCR）
+   - ✅ **read:packages**（从 GHCR 拉取镜像）
+6. 点击 **Generate token**
+7. **立即复制 token**（只显示一次）
+
+### 步骤 2：更新配置文件
+
+编辑 `.github-config` 文件，更新 token：
+
+```bash
+GITHUB_TOKEN=你的新token
+```
+
+### 步骤 3：更新 Git 远程 URL
+
+```powershell
+# 使用新 token 更新远程 URL
+git remote set-url origin https://bujie9527:你的新token@github.com/bujie9527/wecom-ai-assistant.git
+
+# 验证
+git remote -v
+
+# 重新推送
+git push -u origin main
+```
+
+## 方案二：临时跳过 Workflow 文件（快速解决）
+
+如果暂时不想更新 token，可以先推送其他文件：
+
+### 步骤 1：移除 workflow 文件从暂存区
+
+```powershell
+# 从暂存区移除 workflow 文件
+git reset HEAD .github/workflows/
+
+# 提交其他文件
+git commit -m "Initial commit: 企业微信 AI 机器人助理 MVP (without workflows)"
+
+# 推送
+git push -u origin main
+```
+
+### 步骤 2：稍后单独推送 workflow 文件
+
+更新 token 后：
+
+```powershell
+# 添加 workflow 文件
+git add .github/workflows/
+
+# 提交
+git commit -m "Add GitHub Actions workflows"
+
+# 推送
+git push origin main
+```
+
+## 方案三：使用 GitHub CLI（gh）
+
+如果安装了 GitHub CLI：
+
+```powershell
+# 安装 GitHub CLI（如果还没有）
+# 下载：https://cli.github.com/
+
+# 登录（会自动处理权限）
+gh auth login
+
+# 推送代码
+git push -u origin main
+```
+
+## Token 权限说明
+
+### 必需权限
+
+| 权限 | 说明 | 用途 |
+|------|------|------|
+| `repo` | 完整仓库访问 | 推送代码、创建分支等 |
+| `workflow` | 工作流权限 | 推送 `.github/workflows/` 文件 |
+| `write:packages` | 写入包 | 推送 Docker 镜像到 GHCR |
+| `read:packages` | 读取包 | 从 GHCR 拉取镜像 |
+
+### 权限范围
+
+- **Full control of private repositories**：如果你使用私有仓库
+- **Public repositories only**：如果使用公开仓库
+
+## 验证 Token 权限
+
+推送成功后，检查：
+
+1. **仓库文件**：https://github.com/bujie9527/wecom-ai-assistant
+2. **Workflow 文件**：https://github.com/bujie9527/wecom-ai-assistant/tree/main/.github/workflows
+3. **Actions**：https://github.com/bujie9527/wecom-ai-assistant/actions
+
+## 安全建议
+
+1. **Token 安全**：
+   - 不要将 token 提交到 Git
+   - 定期轮换 token（每 90 天）
+   - 如果 token 泄露，立即撤销
+
+2. **最小权限原则**：
+   - 只授予必要的权限
+   - 使用 Fine-grained tokens（如果可用）限制仓库范围
+
+3. **Token 存储**：
+   - 存储在 `.github-config`（已添加到 `.gitignore`）
+   - 或使用环境变量
+   - 或使用 Git Credential Manager
+
+## 故障排查
+
+### 问题：仍然提示权限不足
+
+**解决方案**：
+1. 确认 token 已更新并包含 `workflow` 权限
+2. 清除 Git 凭据缓存：
+   ```powershell
+   git credential-manager-core erase
+   git credential reject https://github.com
+   ```
+3. 重新推送
+
+### 问题：Token 在哪里查看/更新？
+
+**答案**：
+- 查看现有 tokens：https://github.com/settings/tokens
+- 创建新 token：https://github.com/settings/tokens/new
+
+### 问题：如何撤销旧 Token？
+
+**答案**：
+1. 访问：https://github.com/settings/tokens
+2. 找到对应的 token
+3. 点击 **Revoke**（撤销）
+
+## 相关文档
+
+- [GitHub Token 文档](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+- [GitHub Actions 权限](https://docs.github.com/en/actions/security-guides/automatic-token-authentication)
+- [项目 Git 配置指南](./github-config-guide.md)