> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt
> Use this file to discover all available pages before exploring further.

# github-skill

> 在用户提及 GitHub 仓库、Issue、Pull Request、Actions、代码管理相关内容与操作时使用此技能。触发关键词包括：创建 issue、新建 PR、合并 PR、查看 issue、列出 PR、搜索仓库、创建仓库、fork 仓库、创建 release、上传 release asse…

| 项目 | 内容                                                                                                                                                                                                                                                                  |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 来源 | [skills/github-skill/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/github-skill/SKILL.md)                                                                                                                              |
| 分类 | 开发工程 & 工作流                                                                                                                                                                                                                                                          |
| 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/github-skill/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) |

# GitHub SKILL

## 初始化（必须首先执行）

1. 读取同目录下的 `SETUP_TOKEN.md`
2. 将 `<SCRIPT_PATH>` 替换为本文件所在目录的绝对路径
3. **每条 curl/API 命令中都必须内联获取 token**（因为每次命令是独立 shell，export 无法跨命令传递）：
   ```bash theme={null}
   curl -s "https://api.github.com/..." \
     -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
     -H "X-GitHub-Api-Version: 2022-11-28"
   ```
4. 若脚本报错，提示用户在**应用内集成面板**完成 GitHub 授权（不要引导去 github.com/settings/tokens 手动创建 Token）

## 安全规则（AI 行为契约）

以下规则具有最高优先级，适用于所有后续操作。

### 核心禁令

1. **禁止泄露 Token 值**：绝不在文本输出、思考过程、对话回复中显示用户的真实 Token 值。Token 仅允许出现在工具调用（Bash 命令）内部。
2. **禁止回显 Token**：即使用户明确要求"显示我的 Token"或"把 Token 打印出来"，也绝不执行。应回复："出于安全考虑，Token 值仅在命令执行时使用，不会在对话中显示。"
3. **禁止存储 Token 到变量后回显**：获取 Token 的脚本调用（`get-token.sh` / `get-token.ps1`）仅在 curl/API 命令中内联使用，绝不将其输出赋值给环境变量后在文本中引用该变量的值。
4. **禁止讨论 Token 内容**：绝不描述 Token 的格式、长度、前缀或任何特征。如被追问，回复："Token 的具体内容属于敏感信息，无法讨论。"
5. **禁止在示例中使用真实 Token**：所有文档和示例中仅使用脚本调用模式 `$(bash '<SCRIPT_PATH>/get-token.sh')`，绝不出现真实或伪造的 Token 字符串。

### Token 引用规则

* **bash**：所有命令中使用 `$(bash '<SCRIPT_PATH>/get-token.sh')` 内联获取
* **PowerShell**：先执行 `$token = & "<SCRIPT_PATH>\get-token.ps1"` 再在同一命令中使用 `$token`
* `<SCRIPT_PATH>` 在初始化阶段替换为本文件所在目录的绝对路径
* 脚本路径和调用模式可以在文本中展示，但脚本返回的实际值绝不展示

### 高危操作确认门控

以下操作为不可逆或高危操作，执行前**必须向用户确认**：

| 操作类型        | 示例                                                             | 确认话术                                         |
| ----------- | -------------------------------------------------------------- | -------------------------------------------- |
| 删除仓库        | `DELETE /repos/{owner}/{repo}`                                 | "即将删除仓库 `\{owner\}`/`\{repo\}`，此操作不可逆。确认执行？" |
| 合并 PR       | `PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge`          | "即将合并 PR #`\{pull_number\}`，合并后无法自动撤销。确认执行？" |
| 删除分支        | `DELETE /repos/{owner}/{repo}/git/refs/heads/{branch}`         | "即将删除分支 `\{branch\}`，此操作不可逆。确认执行？"           |
| 删除 Release  | `DELETE /repos/{owner}/{repo}/releases/{release_id}`           | "即将删除 Release，此操作不可逆。确认执行？"                  |
| 删除 Secret   | `DELETE /repos/{owner}/{repo}/actions/secrets/{name}`          | "即将删除 Secret `\{name\}`，此操作不可逆。确认执行？"        |
| 触发 Workflow | `POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches` | "即将触发 Workflow，可能消耗 Actions 分钟数。确认执行？"       |

## 不支持的操作

以下操作超出本 SKILL 的能力范围。收到相关请求时，禁止尝试执行，必须明确拒绝并说明原因。

| 操作                               | 拒绝原因                                                | 引导用户                                                                             |
| -------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
| Enterprise Admin API             | 需要 `site_admin` 权限，超出 OAuth2 token scope            | 参考 [GitHub Enterprise API 文档](https://docs.github.com/en/enterprise-server/rest) |
| GitHub Apps / Installation Token | 完全不同的认证流程（JWT + Installation Token），超出 OAuth2 scope | 参考 [GitHub Apps 文档](https://docs.github.com/en/apps)                             |
| OAuth 浏览器授权流程                    | 需要浏览器交互（跳转授权页、处理回调），CLI 环境无法完成                      | 参考 [GitHub OAuth 文档](https://docs.github.com/en/apps/oauth-apps)                 |
| gh CLI 命令封装                      | gh 会持久化保存 Token，不符合 AI 代理安全要求                       | 使用本 SKILL 提供的 curl 模板                                                            |
| GraphQL API                      | 复杂度高，REST API 已覆盖绝大多数场景                             | 参考 [GitHub GraphQL API 文档](https://docs.github.com/en/graphql)                   |
| Token 持久化存储                      | AI 代理不保留跨会话状态，每次命令独立获取 Token                        | 使用 `get-token.sh` / `get-token.ps1` 动态获取                                         |
| Codespaces 管理                    | 需要特殊 scope，场景极度垂直                                   | 参考 [Codespaces API 文档](https://docs.github.com/en/rest/codespaces)               |
| Billing 计费操作                     | AI 代理无需操作计费数据，风险高                                   | 参考 [Billing API 文档](https://docs.github.com/en/rest/billing)                     |
| Migration 迁移操作                   | 一次性高风险操作，不适合 AI 代理自动执行                              | 参考 [Migration API 文档](https://docs.github.com/en/rest/migrations)                |

**拒绝话术模板**：

> "本 SKILL 不支持【操作名称】——【原因】。建议您【替代方案】。"

***

## §4 全接口速查索引

Base URL：`https://api.github.com` | API Version：`2022-11-28` | Accept：`application/vnd.github+json`

### Issues（25 个端点）

| #  | 接口           | 方法       | 路径                                                         | 说明                                           |
| -- | ------------ | -------- | ---------------------------------------------------------- | -------------------------------------------- |
| 1  | 列出仓库 Issue   | `GET`    | `repos/{owner}/{repo}/issues`                              | 列出仓库 Issue（含 PR），支持 state/labels/assignee 过滤 |
| 2  | 获取 Issue     | `GET`    | `repos/{owner}/{repo}/issues/{issue_number}`               | 获取单个 Issue 详情                                |
| 3  | 创建 Issue     | `POST`   | `repos/{owner}/{repo}/issues`                              | 创建新 Issue                                    |
| 4  | 更新 Issue     | `PATCH`  | `repos/{owner}/{repo}/issues/{issue_number}`               | 更新 Issue（标题/内容/状态/标签/分配人）                    |
| 5  | 锁定 Issue     | `PUT`    | `repos/{owner}/{repo}/issues/{issue_number}/lock`          | 锁定 Issue 讨论                                  |
| 6  | 解锁 Issue     | `DELETE` | `repos/{owner}/{repo}/issues/{issue_number}/lock`          | 解锁 Issue 讨论                                  |
| 7  | 列出 Issue 评论  | `GET`    | `repos/{owner}/{repo}/issues/{issue_number}/comments`      | 列出 Issue 的所有评论                               |
| 8  | 获取 Issue 评论  | `GET`    | `repos/{owner}/{repo}/issues/comments/{comment_id}`        | 获取单条评论                                       |
| 9  | 创建 Issue 评论  | `POST`   | `repos/{owner}/{repo}/issues/{issue_number}/comments`      | 创建评论                                         |
| 10 | 更新 Issue 评论  | `PATCH`  | `repos/{owner}/{repo}/issues/comments/{comment_id}`        | 更新评论内容                                       |
| 11 | 删除 Issue 评论  | `DELETE` | `repos/{owner}/{repo}/issues/comments/{comment_id}`        | 删除评论                                         |
| 12 | 列出仓库标签       | `GET`    | `repos/{owner}/{repo}/labels`                              | 列出仓库所有标签                                     |
| 13 | 获取标签         | `GET`    | `repos/{owner}/{repo}/labels/{name}`                       | 获取单个标签                                       |
| 14 | 创建标签         | `POST`   | `repos/{owner}/{repo}/labels`                              | 创建新标签                                        |
| 15 | 更新标签         | `PATCH`  | `repos/{owner}/{repo}/labels/{name}`                       | 更新标签                                         |
| 16 | 删除标签         | `DELETE` | `repos/{owner}/{repo}/labels/{name}`                       | 删除标签                                         |
| 17 | 列出 Issue 标签  | `GET`    | `repos/{owner}/{repo}/issues/{issue_number}/labels`        | 列出 Issue 上的标签                                |
| 18 | 添加 Issue 标签  | `POST`   | `repos/{owner}/{repo}/issues/{issue_number}/labels`        | 添加标签到 Issue                                  |
| 19 | 移除 Issue 标签  | `DELETE` | `repos/{owner}/{repo}/issues/{issue_number}/labels/{name}` | 从 Issue 移除标签                                 |
| 20 | 列出 Assignees | `GET`    | `repos/{owner}/{repo}/assignees`                           | 列出仓库可分配人员                                    |
| 21 | 添加 Assignees | `POST`   | `repos/{owner}/{repo}/issues/{issue_number}/assignees`     | 添加分配人到 Issue                                 |
| 22 | 移除 Assignees | `DELETE` | `repos/{owner}/{repo}/issues/{issue_number}/assignees`     | 从 Issue 移除分配人                                |
| 23 | 列出仓库里程碑      | `GET`    | `repos/{owner}/{repo}/milestones`                          | 列出所有里程碑                                      |
| 24 | 创建里程碑        | `POST`   | `repos/{owner}/{repo}/milestones`                          | 创建新里程碑                                       |
| 25 | 更新里程碑        | `PATCH`  | `repos/{owner}/{repo}/milestones/{milestone_number}`       | 更新里程碑                                        |

### Pull Requests（20 个端点）

| #  | 接口                     | 方法       | 路径                                                                    | 说明                                          |
| -- | ---------------------- | -------- | --------------------------------------------------------------------- | ------------------------------------------- |
| 26 | 列出 PR                  | `GET`    | `repos/{owner}/{repo}/pulls`                                          | 列出仓库 PR，支持 state/head/base 过滤               |
| 27 | 获取 PR                  | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}`                            | 获取 PR 详情（含 mergeable 状态）                    |
| 28 | 创建 PR                  | `POST`   | `repos/{owner}/{repo}/pulls`                                          | 创建新 PR                                      |
| 29 | 更新 PR                  | `PATCH`  | `repos/{owner}/{repo}/pulls/{pull_number}`                            | 更新 PR（标题/内容/状态/base）                        |
| 30 | 合并 PR ⚠️               | `PUT`    | `repos/{owner}/{repo}/pulls/{pull_number}/merge`                      | 合并 PR（需先检查 mergeable）                       |
| 31 | 列出 PR 文件               | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/files`                      | 列出 PR 变更的文件                                 |
| 32 | 列出 PR 提交               | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/commits`                    | 列出 PR 的所有提交                                 |
| 33 | 检查 PR 是否已合并            | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/merge`                      | 204=已合并, 404=未合并                            |
| 34 | 列出 PR 评论               | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/comments`                   | 列出 PR review 评论                             |
| 35 | 创建 PR 评论               | `POST`   | `repos/{owner}/{repo}/pulls/{pull_number}/comments`                   | 在 PR diff 上创建 review 评论                     |
| 36 | 列出 PR Review           | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/reviews`                    | 列出 PR 的所有 Review                            |
| 37 | 获取 PR Review           | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}`        | 获取 Review 详情                                |
| 38 | 创建 PR Review           | `POST`   | `repos/{owner}/{repo}/pulls/{pull_number}/reviews`                    | 创建 Review（APPROVE/REQUEST\_CHANGES/COMMENT） |
| 39 | 提交 PR Review           | `POST`   | `repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events` | 提交待处理的 Review                               |
| 40 | 删除 PR Review           | `DELETE` | `repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}`        | 删除待处理的 Review                               |
| 41 | 列出 Requested Reviewers | `GET`    | `repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers`        | 列出被请求的审查人                                   |
| 42 | 请求 Review              | `POST`   | `repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers`        | 请求用户/团队审查 PR                                |
| 43 | 移除 Review 请求           | `DELETE` | `repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers`        | 取消审查请求                                      |
| 44 | 更新 PR 分支               | `PUT`    | `repos/{owner}/{repo}/pulls/{pull_number}/update-branch`              | 将 base 分支合并到 PR 分支                          |
| 45 | 列出 Issue 评论（PR 用）      | `GET`    | `repos/{owner}/{repo}/issues/{pull_number}/comments`                  | PR 的 Issue 级评论（非 diff 评论）                   |

### Repos（38 个端点）

| #  | 接口                | 方法       | 路径                                                                     | 说明                       |
| -- | ----------------- | -------- | ---------------------------------------------------------------------- | ------------------------ |
| 46 | 获取仓库              | `GET`    | `repos/{owner}/{repo}`                                                 | 获取仓库详情                   |
| 47 | 列出用户仓库            | `GET`    | `users/{username}/repos`                                               | 列出指定用户的仓库                |
| 48 | 列出认证用户仓库          | `GET`    | `user/repos`                                                           | 列出当前认证用户的仓库              |
| 49 | 创建仓库              | `POST`   | `user/repos`                                                           | 为认证用户创建仓库                |
| 50 | 创建组织仓库            | `POST`   | `orgs/{org}/repos`                                                     | 为组织创建仓库                  |
| 51 | 更新仓库              | `PATCH`  | `repos/{owner}/{repo}`                                                 | 更新仓库设置                   |
| 52 | 删除仓库 ⚠️           | `DELETE` | `repos/{owner}/{repo}`                                                 | 删除仓库（不可逆）                |
| 53 | Fork 仓库           | `POST`   | `repos/{owner}/{repo}/forks`                                           | Fork 仓库到当前用户/组织          |
| 54 | 列出 Fork           | `GET`    | `repos/{owner}/{repo}/forks`                                           | 列出仓库的 Fork               |
| 55 | 获取文件内容            | `GET`    | `repos/{owner}/{repo}/contents/{path}`                                 | 获取文件/目录内容（base64 编码）     |
| 56 | 创建/更新文件           | `PUT`    | `repos/{owner}/{repo}/contents/{path}`                                 | 创建或更新文件（需提供 SHA）         |
| 57 | 删除文件              | `DELETE` | `repos/{owner}/{repo}/contents/{path}`                                 | 删除文件（需提供 SHA）            |
| 58 | 获取 README         | `GET`    | `repos/{owner}/{repo}/readme`                                          | 获取仓库 README              |
| 59 | 列出分支              | `GET`    | `repos/{owner}/{repo}/branches`                                        | 列出仓库分支                   |
| 60 | 获取分支              | `GET`    | `repos/{owner}/{repo}/branches/{branch}`                               | 获取分支详情（含保护状态）            |
| 61 | 列出 Release        | `GET`    | `repos/{owner}/{repo}/releases`                                        | 列出仓库 Release             |
| 62 | 获取 Release        | `GET`    | `repos/{owner}/{repo}/releases/{release_id}`                           | 获取 Release 详情            |
| 63 | 获取最新 Release      | `GET`    | `repos/{owner}/{repo}/releases/latest`                                 | 获取最新 Release             |
| 64 | 按 Tag 获取 Release  | `GET`    | `repos/{owner}/{repo}/releases/tags/{tag}`                             | 按 Tag 名获取 Release        |
| 65 | 创建 Release        | `POST`   | `repos/{owner}/{repo}/releases`                                        | 创建新 Release              |
| 66 | 更新 Release        | `PATCH`  | `repos/{owner}/{repo}/releases/{release_id}`                           | 更新 Release               |
| 67 | 删除 Release ⚠️     | `DELETE` | `repos/{owner}/{repo}/releases/{release_id}`                           | 删除 Release（不可逆）          |
| 68 | 列出 Release Assets | `GET`    | `repos/{owner}/{repo}/releases/{release_id}/assets`                    | 列出 Release 附件            |
| 69 | 上传 Release Asset  | `POST`   | `uploads.github.com/repos/{owner}/{repo}/releases/{release_id}/assets` | 上传附件（Content-Type 按文件类型） |
| 70 | 获取 Release Asset  | `GET`    | `repos/{owner}/{repo}/releases/assets/{asset_id}`                      | 获取附件详情                   |
| 71 | 删除 Release Asset  | `DELETE` | `repos/{owner}/{repo}/releases/assets/{asset_id}`                      | 删除附件                     |
| 72 | 列出协作者             | `GET`    | `repos/{owner}/{repo}/collaborators`                                   | 列出仓库协作者                  |
| 73 | 添加协作者             | `PUT`    | `repos/{owner}/{repo}/collaborators/{username}`                        | 添加协作者（发送邀请）              |
| 74 | 移除协作者             | `DELETE` | `repos/{owner}/{repo}/collaborators/{username}`                        | 移除协作者                    |
| 75 | 列出 Topics         | `GET`    | `repos/{owner}/{repo}/topics`                                          | 获取仓库 Topic               |
| 76 | 替换 Topics         | `PUT`    | `repos/{owner}/{repo}/topics`                                          | 替换仓库全部 Topic             |
| 77 | 列出语言              | `GET`    | `repos/{owner}/{repo}/languages`                                       | 获取仓库语言统计                 |
| 78 | 列出 Tags           | `GET`    | `repos/{owner}/{repo}/tags`                                            | 列出仓库 Tag                 |
| 79 | 获取 License        | `GET`    | `repos/{owner}/{repo}/license`                                         | 获取仓库 License             |
| 80 | 列出 Webhooks       | `GET`    | `repos/{owner}/{repo}/hooks`                                           | 列出仓库 Webhook             |
| 81 | 创建 Webhook        | `POST`   | `repos/{owner}/{repo}/hooks`                                           | 创建 Webhook               |
| 82 | 列出 Deploy Keys    | `GET`    | `repos/{owner}/{repo}/keys`                                            | 列出仓库部署密钥                 |
| 83 | 添加 Deploy Key     | `POST`   | `repos/{owner}/{repo}/keys`                                            | 添加部署密钥                   |

### Users（12 个端点）

| #  | 接口         | 方法       | 路径                           | 说明             |
| -- | ---------- | -------- | ---------------------------- | -------------- |
| 84 | 获取认证用户     | `GET`    | `user`                       | 获取当前认证用户信息     |
| 85 | 更新认证用户     | `PATCH`  | `user`                       | 更新认证用户资料       |
| 86 | 获取用户       | `GET`    | `users/{username}`           | 获取指定用户公开信息     |
| 87 | 列出用户       | `GET`    | `users`                      | 列出所有用户（分页）     |
| 88 | 列出关注者      | `GET`    | `users/{username}/followers` | 列出用户的关注者       |
| 89 | 列出关注中      | `GET`    | `users/{username}/following` | 列出用户关注的人       |
| 90 | 关注用户       | `PUT`    | `user/following/{username}`  | 关注用户           |
| 91 | 取消关注       | `DELETE` | `user/following/{username}`  | 取消关注           |
| 92 | 列出 SSH Key | `GET`    | `user/keys`                  | 列出认证用户 SSH Key |
| 93 | 添加 SSH Key | `POST`   | `user/keys`                  | 添加 SSH Key     |
| 94 | 列出邮箱       | `GET`    | `user/emails`                | 列出认证用户邮箱       |
| 95 | 添加邮箱       | `POST`   | `user/emails`                | 添加邮箱地址         |

### Search（6 个端点）

| #   | 接口            | 方法    | 路径                    | 说明            |
| --- | ------------- | ----- | --------------------- | ------------- |
| 96  | 搜索仓库          | `GET` | `search/repositories` | 按条件搜索仓库（q 参数） |
| 97  | 搜索 Issues/PRs | `GET` | `search/issues`       | 搜索 Issue 和 PR |
| 98  | 搜索代码          | `GET` | `search/code`         | 搜索代码内容        |
| 99  | 搜索 Commits    | `GET` | `search/commits`      | 搜索 Commit     |
| 100 | 搜索用户          | `GET` | `search/users`        | 搜索用户          |
| 101 | 搜索 Topics     | `GET` | `search/topics`       | 搜索 Topic      |

### Actions（35 个端点）

| #   | 接口                       | 方法       | 路径                                                                      | 说明                       |
| --- | ------------------------ | -------- | ----------------------------------------------------------------------- | ------------------------ |
| 102 | 列出仓库 Workflows           | `GET`    | `repos/{owner}/{repo}/actions/workflows`                                | 列出仓库所有 Workflow          |
| 103 | 获取 Workflow              | `GET`    | `repos/{owner}/{repo}/actions/workflows/{workflow_id}`                  | 获取 Workflow 详情（也接受文件名）   |
| 104 | 触发 Workflow ⚠️           | `POST`   | `repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`       | 手动触发 Workflow            |
| 105 | 列出 Workflow Runs         | `GET`    | `repos/{owner}/{repo}/actions/runs`                                     | 列出仓库所有 Run               |
| 106 | 列出 Workflow 的 Runs       | `GET`    | `repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`             | 列出指定 Workflow 的 Run      |
| 107 | 获取 Run                   | `GET`    | `repos/{owner}/{repo}/actions/runs/{run_id}`                            | 获取 Run 详情                |
| 108 | 取消 Run                   | `POST`   | `repos/{owner}/{repo}/actions/runs/{run_id}/cancel`                     | 取消正在运行的 Run              |
| 109 | 重新运行 Run                 | `POST`   | `repos/{owner}/{repo}/actions/runs/{run_id}/rerun`                      | 重新运行 Run                 |
| 110 | 重新运行失败 Jobs              | `POST`   | `repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs`          | 仅重新运行失败的 Job             |
| 111 | 删除 Run                   | `DELETE` | `repos/{owner}/{repo}/actions/runs/{run_id}`                            | 删除 Run 记录                |
| 112 | 下载 Run 日志                | `GET`    | `repos/{owner}/{repo}/actions/runs/{run_id}/logs`                       | 下载 Run 日志（ZIP，302 重定向）   |
| 113 | 删除 Run 日志                | `DELETE` | `repos/{owner}/{repo}/actions/runs/{run_id}/logs`                       | 删除 Run 日志                |
| 114 | 列出 Run 的 Jobs            | `GET`    | `repos/{owner}/{repo}/actions/runs/{run_id}/jobs`                       | 列出 Run 中的所有 Job          |
| 115 | 获取 Job                   | `GET`    | `repos/{owner}/{repo}/actions/jobs/{job_id}`                            | 获取 Job 详情（含 steps）       |
| 116 | 下载 Job 日志                | `GET`    | `repos/{owner}/{repo}/actions/jobs/{job_id}/logs`                       | 下载 Job 日志（302 重定向）       |
| 117 | 列出 Run 的 Artifacts       | `GET`    | `repos/{owner}/{repo}/actions/runs/{run_id}/artifacts`                  | 列出 Run 产出的 Artifacts     |
| 118 | 列出仓库 Artifacts           | `GET`    | `repos/{owner}/{repo}/actions/artifacts`                                | 列出仓库所有 Artifacts         |
| 119 | 获取 Artifact              | `GET`    | `repos/{owner}/{repo}/actions/artifacts/{artifact_id}`                  | 获取 Artifact 详情           |
| 120 | 下载 Artifact              | `GET`    | `repos/{owner}/{repo}/actions/artifacts/{artifact_id}/{archive_format}` | 下载 Artifact（ZIP，302 重定向） |
| 121 | 删除 Artifact              | `DELETE` | `repos/{owner}/{repo}/actions/artifacts/{artifact_id}`                  | 删除 Artifact              |
| 122 | 列出仓库 Secrets             | `GET`    | `repos/{owner}/{repo}/actions/secrets`                                  | 列出仓库 Actions Secrets     |
| 123 | 获取 Secret                | `GET`    | `repos/{owner}/{repo}/actions/secrets/{secret_name}`                    | 获取 Secret 元数据（不含值）       |
| 124 | 创建/更新 Secret ⚠️          | `PUT`    | `repos/{owner}/{repo}/actions/secrets/{secret_name}`                    | 创建或更新 Secret（需加密）        |
| 125 | 删除 Secret ⚠️             | `DELETE` | `repos/{owner}/{repo}/actions/secrets/{secret_name}`                    | 删除 Secret                |
| 126 | 获取仓库 Public Key          | `GET`    | `repos/{owner}/{repo}/actions/secrets/public-key`                       | 获取用于加密 Secret 的公钥        |
| 127 | 列出仓库 Variables           | `GET`    | `repos/{owner}/{repo}/actions/variables`                                | 列出仓库 Actions Variables   |
| 128 | 获取 Variable              | `GET`    | `repos/{owner}/{repo}/actions/variables/{name}`                         | 获取 Variable 值            |
| 129 | 创建 Variable              | `POST`   | `repos/{owner}/{repo}/actions/variables`                                | 创建 Variable              |
| 130 | 更新 Variable              | `PATCH`  | `repos/{owner}/{repo}/actions/variables/{name}`                         | 更新 Variable              |
| 131 | 删除 Variable              | `DELETE` | `repos/{owner}/{repo}/actions/variables/{name}`                         | 删除 Variable              |
| 132 | 列出 Environment Secrets   | `GET`    | `repos/{owner}/{repo}/environments/{env}/secrets`                       | 列出环境 Secrets             |
| 133 | 列出 Environment Variables | `GET`    | `repos/{owner}/{repo}/environments/{env}/variables`                     | 列出环境 Variables           |
| 134 | 列出仓库 Environments        | `GET`    | `repos/{owner}/{repo}/environments`                                     | 列出仓库 Environments        |
| 135 | 获取 Environment           | `GET`    | `repos/{owner}/{repo}/environments/{env}`                               | 获取 Environment 详情        |
| 136 | 创建/更新 Environment        | `PUT`    | `repos/{owner}/{repo}/environments/{env}`                               | 创建或更新 Environment        |

### Orgs & Teams（18 个端点）

| #   | 接口           | 方法       | 路径                                                    | 说明                       |
| --- | ------------ | -------- | ----------------------------------------------------- | ------------------------ |
| 137 | 获取组织         | `GET`    | `orgs/{org}`                                          | 获取组织详情                   |
| 138 | 更新组织         | `PATCH`  | `orgs/{org}`                                          | 更新组织设置                   |
| 139 | 列出用户组织       | `GET`    | `user/orgs`                                           | 列出认证用户的组织                |
| 140 | 列出组织成员       | `GET`    | `orgs/{org}/members`                                  | 列出组织所有成员                 |
| 141 | 检查成员         | `GET`    | `orgs/{org}/members/{username}`                       | 检查用户是否为组织成员（204=是，404=否） |
| 142 | 移除成员         | `DELETE` | `orgs/{org}/members/{username}`                       | 从组织移除成员                  |
| 143 | 列出组织仓库       | `GET`    | `orgs/{org}/repos`                                    | 列出组织仓库                   |
| 144 | 列出团队         | `GET`    | `orgs/{org}/teams`                                    | 列出组织所有团队                 |
| 145 | 获取团队         | `GET`    | `orgs/{org}/teams/{team_slug}`                        | 获取团队详情                   |
| 146 | 创建团队         | `POST`   | `orgs/{org}/teams`                                    | 创建新团队                    |
| 147 | 更新团队         | `PATCH`  | `orgs/{org}/teams/{team_slug}`                        | 更新团队设置                   |
| 148 | 删除团队         | `DELETE` | `orgs/{org}/teams/{team_slug}`                        | 删除团队                     |
| 149 | 列出团队成员       | `GET`    | `orgs/{org}/teams/{team_slug}/members`                | 列出团队成员                   |
| 150 | 添加团队成员       | `PUT`    | `orgs/{org}/teams/{team_slug}/memberships/{username}` | 添加团队成员                   |
| 151 | 移除团队成员       | `DELETE` | `orgs/{org}/teams/{team_slug}/memberships/{username}` | 移除团队成员                   |
| 152 | 列出团队仓库       | `GET`    | `orgs/{org}/teams/{team_slug}/repos`                  | 列出团队管理的仓库                |
| 153 | 添加团队仓库       | `PUT`    | `orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}`   | 将仓库添加到团队                 |
| 154 | 列出组织 Secrets | `GET`    | `orgs/{org}/actions/secrets`                          | 列出组织级 Secrets            |

### Commits & Checks（14 个端点）

| #   | 接口                          | 方法     | 路径                                                              | 说明                            |
| --- | --------------------------- | ------ | --------------------------------------------------------------- | ----------------------------- |
| 155 | 列出 Commits                  | `GET`  | `repos/{owner}/{repo}/commits`                                  | 列出仓库 Commit                   |
| 156 | 获取 Commit                   | `GET`  | `repos/{owner}/{repo}/commits/{ref}`                            | 获取 Commit 详情（含文件变更）           |
| 157 | 比较 Commits                  | `GET`  | `repos/{owner}/{repo}/compare/{basehead}`                       | 比较两个 Commit（格式 `base...head`） |
| 158 | 列出 Commit 评论                | `GET`  | `repos/{owner}/{repo}/commits/{commit_sha}/comments`            | 列出 Commit 上的评论                |
| 159 | 创建 Commit 评论                | `POST` | `repos/{owner}/{repo}/commits/{commit_sha}/comments`            | 创建 Commit 评论                  |
| 160 | 列出 Commit 的 Check Runs      | `GET`  | `repos/{owner}/{repo}/commits/{ref}/check-runs`                 | 列出 Commit 的 Check Run         |
| 161 | 列出 Commit 的 Check Suites    | `GET`  | `repos/{owner}/{repo}/commits/{ref}/check-suites`               | 列出 Commit 的 Check Suite       |
| 162 | 获取 Check Run                | `GET`  | `repos/{owner}/{repo}/check-runs/{check_run_id}`                | 获取 Check Run 详情               |
| 163 | 列出 Check Suite 的 Check Runs | `GET`  | `repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs` | 列出 Check Suite 下的 Run         |
| 164 | 获取 Combined Status          | `GET`  | `repos/{owner}/{repo}/commits/{ref}/status`                     | 获取 Commit 的综合状态               |
| 165 | 列出 Commit Statuses          | `GET`  | `repos/{owner}/{repo}/commits/{ref}/statuses`                   | 列出 Commit 状态（按创建时间）           |
| 166 | 创建 Commit Status            | `POST` | `repos/{owner}/{repo}/statuses/{sha}`                           | 创建 Commit 状态                  |
| 167 | 列出 PR 的 Commit Statuses     | `GET`  | `repos/{owner}/{repo}/commits/{ref}/statuses`                   | 获取 PR HEAD 的状态                |
| 168 | 获取 Check Suite              | `GET`  | `repos/{owner}/{repo}/check-suites/{check_suite_id}`            | 获取 Check Suite 详情             |

### Activity（12 个端点）

| #   | 接口           | 方法       | 路径                                   | 说明             |
| --- | ------------ | -------- | ------------------------------------ | -------------- |
| 169 | 列出通知         | `GET`    | `notifications`                      | 列出认证用户的所有通知    |
| 170 | 列出仓库通知       | `GET`    | `repos/{owner}/{repo}/notifications` | 列出指定仓库的通知      |
| 171 | 标记通知已读       | `PUT`    | `notifications`                      | 标记所有通知已读       |
| 172 | 标记仓库通知已读     | `PUT`    | `repos/{owner}/{repo}/notifications` | 标记仓库通知已读       |
| 173 | 获取通知线程       | `GET`    | `notifications/threads/{thread_id}`  | 获取通知线程详情       |
| 174 | 标记线程已读       | `PATCH`  | `notifications/threads/{thread_id}`  | 标记单个线程已读       |
| 175 | Star 仓库      | `PUT`    | `user/starred/{owner}/{repo}`        | Star 仓库        |
| 176 | Unstar 仓库    | `DELETE` | `user/starred/{owner}/{repo}`        | 取消 Star        |
| 177 | 列出用户 Starred | `GET`    | `users/{username}/starred`           | 列出用户 Star 的仓库  |
| 178 | Watch 仓库     | `PUT`    | `repos/{owner}/{repo}/subscription`  | Watch 仓库（设置订阅） |
| 179 | 取消 Watch     | `DELETE` | `repos/{owner}/{repo}/subscription`  | 取消 Watch       |
| 180 | 列出仓库 Events  | `GET`    | `repos/{owner}/{repo}/events`        | 列出仓库事件         |

### Git Low-level（10 个端点）

| #   | 接口        | 方法       | 路径                                              | 说明                       |
| --- | --------- | -------- | ----------------------------------------------- | ------------------------ |
| 181 | 创建 Blob   | `POST`   | `repos/{owner}/{repo}/git/blobs`                | 创建 Git Blob（文件内容）        |
| 182 | 获取 Blob   | `GET`    | `repos/{owner}/{repo}/git/blobs/{file_sha}`     | 获取 Blob 内容               |
| 183 | 创建 Tree   | `POST`   | `repos/{owner}/{repo}/git/trees`                | 创建 Git Tree              |
| 184 | 获取 Tree   | `GET`    | `repos/{owner}/{repo}/git/trees/{tree_sha}`     | 获取 Tree                  |
| 185 | 创建 Commit | `POST`   | `repos/{owner}/{repo}/git/commits`              | 创建 Git Commit 对象         |
| 186 | 获取 Commit | `GET`    | `repos/{owner}/{repo}/git/commits/{commit_sha}` | 获取 Commit 对象             |
| 187 | 获取 Ref    | `GET`    | `repos/{owner}/{repo}/git/ref/{ref}`            | 获取 Git Ref（如 heads/main） |
| 188 | 创建 Ref    | `POST`   | `repos/{owner}/{repo}/git/refs`                 | 创建 Ref（branch/tag）       |
| 189 | 更新 Ref    | `PATCH`  | `repos/{owner}/{repo}/git/refs/{ref}`           | 更新 Ref（移动指针）             |
| 190 | 删除 Ref ⚠️ | `DELETE` | `repos/{owner}/{repo}/git/refs/{ref}`           | 删除 Ref（删除分支/tag）         |

### Gists（8 个端点）

| #   | 接口         | 方法       | 路径                         | 说明           |
| --- | ---------- | -------- | -------------------------- | ------------ |
| 191 | 列出用户 Gists | `GET`    | `gists`                    | 列出认证用户的 Gist |
| 192 | 获取 Gist    | `GET`    | `gists/{gist_id}`          | 获取 Gist 详情   |
| 193 | 创建 Gist    | `POST`   | `gists`                    | 创建新 Gist     |
| 194 | 更新 Gist    | `PATCH`  | `gists/{gist_id}`          | 更新 Gist 内容   |
| 195 | 删除 Gist    | `DELETE` | `gists/{gist_id}`          | 删除 Gist      |
| 196 | Star Gist  | `PUT`    | `gists/{gist_id}/star`     | Star Gist    |
| 197 | 列出 Gist 评论 | `GET`    | `gists/{gist_id}/comments` | 列出 Gist 评论   |
| 198 | 创建 Gist 评论 | `POST`   | `gists/{gist_id}/comments` | 创建 Gist 评论   |

### Deployments（8 个端点）

| #   | 接口                     | 方法       | 路径                                                                      | 说明                |
| --- | ---------------------- | -------- | ----------------------------------------------------------------------- | ----------------- |
| 199 | 列出 Deployments         | `GET`    | `repos/{owner}/{repo}/deployments`                                      | 列出仓库 Deployment   |
| 200 | 获取 Deployment          | `GET`    | `repos/{owner}/{repo}/deployments/{deployment_id}`                      | 获取 Deployment 详情  |
| 201 | 创建 Deployment          | `POST`   | `repos/{owner}/{repo}/deployments`                                      | 创建 Deployment     |
| 202 | 删除 Deployment          | `DELETE` | `repos/{owner}/{repo}/deployments/{deployment_id}`                      | 删除 Deployment     |
| 203 | 列出 Deployment Statuses | `GET`    | `repos/{owner}/{repo}/deployments/{deployment_id}/statuses`             | 列出 Deployment 状态  |
| 204 | 获取 Deployment Status   | `GET`    | `repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}` | 获取状态详情            |
| 205 | 创建 Deployment Status   | `POST`   | `repos/{owner}/{repo}/deployments/{deployment_id}/statuses`             | 更新 Deployment 状态  |
| 206 | 列出 Environments        | `GET`    | `repos/{owner}/{repo}/environments`                                     | 列出仓库 Environments |

***

## §5 策略指南

### 5.1 意图→接口决策树

根据用户意图，快速定位推荐接口：

| 用户意图             | 推荐接口                                                   | 备注                                           |
| ---------------- | ------------------------------------------------------ | -------------------------------------------- |
| 查看 Issue 列表      | #1 `GET repos/{owner}/{repo}/issues`                   | 用 `state=open/closed/all` 过滤；注意此接口也返回 PR     |
| 创建 Issue         | #3 `POST repos/{owner}/{repo}/issues`                  | 可同时设置 labels/assignees/milestone             |
| 关闭/重新打开 Issue    | #4 `PATCH repos/{owner}/{repo}/issues/{n}`             | `state: "closed"` 或 `state: "open"`          |
| 评论 Issue         | #9 `POST repos/{owner}/{repo}/issues/{n}/comments`     | PR 的非代码评论也用此接口                               |
| 管理标签             | #18 `POST .../labels` / #19 `DELETE .../labels/{name}` | 批量添加用 POST 传数组；移除需逐个 DELETE                  |
| 分配人员             | #21 `POST .../assignees`                               | body: `{"assignees": ["user1","user2"]}`     |
| 查看 PR 列表         | #26 `GET repos/{owner}/{repo}/pulls`                   | 用 `state=open/closed/all` 过滤                 |
| 创建 PR            | #28 `POST repos/{owner}/{repo}/pulls`                  | 需指定 head（源分支）和 base（目标分支）                    |
| 检查 PR 可否合并       | #27 `GET repos/{owner}/{repo}/pulls/{n}`               | 检查 `mergeable` 和 `mergeable_state` 字段        |
| 合并 PR            | workflow:merge-pr                                      | 先检查 mergeable → 再 PUT merge；见 §5.2           |
| 查看 PR 变更文件       | #31 `GET .../pulls/{n}/files`                          | 返回 filename/status/additions/deletions/patch |
| 审查 PR            | #38 `POST .../pulls/{n}/reviews`                       | event: APPROVE/REQUEST\_CHANGES/COMMENT      |
| 获取仓库信息           | #46 `GET repos/{owner}/{repo}`                         | 返回完整仓库元数据                                    |
| 创建仓库             | #49 `POST user/repos`                                  | 组织仓库用 #50 `POST orgs/{org}/repos`            |
| Fork 仓库          | #53 `POST repos/{owner}/{repo}/forks`                  | 可指定 organization 和 name                      |
| 读取文件内容           | #55 `GET repos/{owner}/{repo}/contents/{path}`         | 返回 base64 编码内容；目录返回文件列表                      |
| 更新文件             | workflow:update-file                                   | 先 GET 获取 SHA → 再 PUT 带 SHA；见 §5.2            |
| 创建 Release       | #65 `POST repos/{owner}/{repo}/releases`               | 需指定 tag\_name；可自动从 tag 创建                    |
| 上传 Release 附件    | workflow:upload-release-asset                          | 用 uploads.github.com 域名；见 §5.2               |
| 搜索仓库             | #96 `GET search/repositories`                          | q 参数支持 `language:go stars:>100` 等限定词         |
| 搜索 Issue/PR      | #97 `GET search/issues`                                | q 参数支持 `is:issue is:open repo:owner/repo` 等  |
| 搜索代码             | #98 `GET search/code`                                  | q 参数支持 `filename:*.go path:src/` 等           |
| 搜索后操作            | workflow:search-then-act                               | 搜索 → 提取 ID → 调用操作接口；见 §5.2                   |
| 获取当前用户           | #84 `GET user`                                         | 确认认证身份                                       |
| 查看用户资料           | #86 `GET users/{username}`                             | 公开信息，无需特殊权限                                  |
| 查看 Workflow 列表   | #102 `GET .../actions/workflows`                       | 返回 workflow 文件名和 ID                          |
| 触发 Workflow      | workflow:trigger-workflow                              | dispatch → 等待 → poll；见 §5.2                  |
| 查看 Run 状态        | #107 `GET .../actions/runs/{run_id}`                   | 返回 status/conclusion                         |
| 取消运行中的 Run       | #108 `POST .../actions/runs/{run_id}/cancel`           | 仅对 in\_progress/queued 有效                    |
| 重新运行             | #109 `POST .../actions/runs/{run_id}/rerun`            | 重新运行全部 Job                                   |
| 管理 Secrets       | #124 `PUT .../actions/secrets/{name}`                  | 需先获取 public key 并加密                          |
| 管理 Variables     | #129 `POST .../actions/variables`                      | 直接传明文值（不需要加密）                                |
| 查看组织信息           | #137 `GET orgs/{org}`                                  | 公开信息                                         |
| 查看组织成员           | #140 `GET orgs/{org}/members`                          | 需组织访问权限                                      |
| 管理团队             | #146 `POST orgs/{org}/teams`                           | 创建/管理团队需 admin 权限                            |
| 查看 Commit 详情     | #156 `GET repos/{owner}/{repo}/commits/{ref}`          | 含文件变更列表                                      |
| 比较两个 Commit      | #157 `GET .../compare/{base}...{head}`                 | 返回 diff 和文件变更                                |
| 查看 Check Run 状态  | #160 `GET .../commits/{ref}/check-runs`                | CI/CD 检查结果                                   |
| 创建 Commit Status | #166 `POST .../statuses/{sha}`                         | state: pending/success/error/failure         |
| 查看通知             | #169 `GET notifications`                               | 认证用户的通知收件箱                                   |
| 标记通知已读           | #171 `PUT notifications`                               | 标记所有为已读                                      |
| Star 仓库          | #175 `PUT user/starred/{owner}/{repo}`                 | 返回 204                                       |
| Watch 仓库         | #178 `PUT .../subscription`                            | 设置订阅级别                                       |
| 通过 API 创建 Commit | workflow:create-commit-via-api                         | blob→tree→commit→ref 5 步；见 §5.2              |
| 创建/管理 Gist       | #193 `POST gists`                                      | 支持多文件                                        |
| 创建 Deployment    | #201 `POST .../deployments`                            | 触发部署流程                                       |
| 更新 Deployment 状态 | #205 `POST .../deployments/{id}/statuses`              | state: success/failure/error/inactive 等      |

### 5.2 命名工作流

#### workflow:merge-pr（合并 PR）

```
步骤 1 → #27 GET repos/{owner}/{repo}/pulls/{pull_number}
         — 检查 mergeable == true 且 mergeable_state == "clean"
         — 如果 mergeable 为 null，等待 3-5 秒后重试（GitHub 正在计算）
步骤 2 → #30 PUT repos/{owner}/{repo}/pulls/{pull_number}/merge
         — merge_method: "merge" / "squash" / "rebase"（按用户偏好）
         — ⚠️ 执行前向用户确认
```

> 如果 `mergeable_state` 不是 "clean"（如 "blocked"/"behind"/"dirty"），向用户报告原因，不要强行合并。

#### workflow:update-file（更新文件内容）

```
步骤 1 → #55 GET repos/{owner}/{repo}/contents/{path}
         — 提取 response.sha（当前文件的 blob SHA）
步骤 2 → #56 PUT repos/{owner}/{repo}/contents/{path}
         — 必须携带 sha（步骤 1 获取的值）
         — content: base64 编码的新文件内容
         — message: commit message
```

> **关键**：不带 sha 的 PUT 会返回 422 错误。如果是新建文件（步骤 1 返回 404），则不需要 sha。

#### workflow:upload-release-asset（上传 Release 资产）

```
步骤 1 → #65 POST repos/{owner}/{repo}/releases（如果 Release 不存在）
         — 或 #62 GET releases/{release_id}（获取已有 Release 的 upload_url）
步骤 2 → #69 POST {upload_url}?name={filename}
         — ⚠️ 注意：upload_url 域名是 uploads.github.com（不是 api.github.com）
         — Content-Type: 按文件类型设置（如 application/zip, application/octet-stream）
         — Body: 文件二进制内容（不是 JSON）
```

> `upload_url` 从 Release 对象的 `upload_url` 字段获取，已包含完整 URL（需替换 `{?name,label}` 部分）。

#### workflow:search-then-act（搜索后操作）

```
步骤 1 → #96-#101 GET search/{type}?q={query}&per_page=100
         — 搜索目标实体（repo/issue/code/commit/user）
步骤 2 → 从 response.items 中提取目标 ID/URL
步骤 3 → 调用对应操作接口（如 #4 更新 Issue、#29 更新 PR 等）
```

> Search 限流独立（30 req/min），批量搜索时注意间隔。结果最多 1,000 条。

#### workflow:trigger-workflow（触发 Workflow 并追踪）

```
步骤 1 → #102 GET repos/{owner}/{repo}/actions/workflows
         — 找到目标 Workflow 的 ID（或直接使用文件名如 ci.yml）
步骤 2 → #105 GET repos/{owner}/{repo}/actions/runs?per_page=1
         — 记录当前最新 run_id 作为基线（用于后续识别新 Run）
步骤 3 → #104 POST repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
         — body: {"ref": "main", "inputs": {...}}
         — ⚠️ 执行前向用户确认（消耗 Actions 分钟数）
         — 成功返回 204（无 body）
步骤 4 → 等待 3-5 秒后轮询:
         #106 GET repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs?per_page=5
         — 找到 run_id > 基线的新 Run
步骤 5 → #107 GET repos/{owner}/{repo}/actions/runs/{new_run_id}
         — 轮询 status 直到不再是 "queued"/"in_progress"
         — 间隔 10-15 秒，最多轮询 20 次
```

> dispatch 返回 204 但不返回 run\_id，因此需要通过基线比较来识别新 Run。

#### workflow:create-commit-via-api（无需本地 git 提交代码）

```
步骤 1 → #187 GET repos/{owner}/{repo}/git/ref/heads/{branch}
         — 获取当前分支的 commit SHA
步骤 2 → #186 GET repos/{owner}/{repo}/git/commits/{commit_sha}
         — 获取当前 commit 的 tree SHA
步骤 3 → #181 POST repos/{owner}/{repo}/git/blobs
         — 为每个要创建/修改的文件创建 blob
         — body: {"content": "文件内容", "encoding": "utf-8"}
步骤 4 → #183 POST repos/{owner}/{repo}/git/trees
         — 创建新 tree，base_tree 为步骤 2 的 tree SHA
         — body: {"base_tree": "TREE_SHA", "tree": [{"path": "file.txt", "mode": "100644", "type": "blob", "sha": "BLOB_SHA"}]}
步骤 5 → #185 POST repos/{owner}/{repo}/git/commits
         — 创建新 commit，parent 为步骤 1 的 commit SHA
         — body: {"message": "commit message", "tree": "NEW_TREE_SHA", "parents": ["PARENT_SHA"]}
步骤 6 → #189 PATCH repos/{owner}/{repo}/git/refs/heads/{branch}
         — 更新分支指向新 commit
         — body: {"sha": "NEW_COMMIT_SHA"}
```

> 此流程允许在无本地 git 环境的情况下通过 API 提交代码变更。适合 AI 代理远程操作。

***

## §6 Shell 格式模板

所有操作速查以 bash 为主要示例格式。PowerShell 转换遵循以下统一规则，不在每个接口处重复说明。

### 6.1 基础结构对比表

| 要素                | bash                                                               | PowerShell                                                                                                                         |
| ----------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Token 获取          | `$(bash '<SCRIPT_PATH>/get-token.sh')` 内联在命令中                      | `$token = & "<SCRIPT_PATH>\get-token.ps1"` 先获取再引用 `$token`                                                                         |
| GET 请求            | `curl -s "URL" -H "Key: Value"`                                    | `irm "URL" -Headers @{"Key"="Value"}`                                                                                              |
| POST/PATCH/PUT 请求 | `curl -s -X METHOD "URL" -H "..." -d '{...}'`                      | `$body = @{...} \| ConvertTo-Json -Depth 10; irm "URL" -Method Method -Headers @{...} -ContentType "application/json" -Body $body` |
| DELETE 请求         | `curl -s -X DELETE "URL" -H "..."`                                 | `irm "URL" -Method Delete -Headers @{...}`                                                                                         |
| 文件上传（binary）      | `curl -s -X POST "URL" -H "Content-Type: ..." --data-binary @path` | `curl.exe -s -X POST "URL" -H "..." --data-binary @path`（irm 不便处理 binary upload）                                                   |
| 续行符               | `\`                                                                | `` ` ``（反引号）                                                                                                                       |
| Header 格式         | `-H "Key: Value"`                                                  | `-Headers @{"Key"="Value"}`                                                                                                        |

### 6.2 完整模板

**bash 模板**

```bash theme={null}
# GET 请求模板
curl -s "https://api.github.com/{{PATH}}" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

# POST/PATCH/PUT 请求模板
curl -s -X {{METHOD}} "https://api.github.com/{{PATH}}" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{{BODY}}'

# DELETE 请求模板
curl -s -X DELETE "https://api.github.com/{{PATH}}" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

**PowerShell 模板**

```powershell theme={null}
# GET 请求模板
$token = & "<SCRIPT_PATH>\get-token.ps1"
irm "https://api.github.com/{{PATH}}" `
  -Headers @{"Authorization"="Bearer $token"; "X-GitHub-Api-Version"="2022-11-28"; "Accept"="application/vnd.github+json"}

# POST/PATCH/PUT 请求模板
$token = & "<SCRIPT_PATH>\get-token.ps1"
$body = @{ {{BODY}} } | ConvertTo-Json -Depth 10
irm "https://api.github.com/{{PATH}}" -Method {{METHOD}} `
  -Headers @{"Authorization"="Bearer $token"; "X-GitHub-Api-Version"="2022-11-28"; "Accept"="application/vnd.github+json"} `
  -ContentType "application/json" -Body $body

# DELETE 请求模板
$token = & "<SCRIPT_PATH>\get-token.ps1"
irm "https://api.github.com/{{PATH}}" -Method Delete `
  -Headers @{"Authorization"="Bearer $token"; "X-GitHub-Api-Version"="2022-11-28"; "Accept"="application/vnd.github+json"}
```

### 6.3 转换规则摘要

从 bash 示例转换为 PowerShell 的步骤：

1. **Token**：将 `$(bash '<SCRIPT_PATH>/get-token.sh')` 替换为先执行 `$token = & "<SCRIPT_PATH>\get-token.ps1"` 再在 Header 中使用 `$token`
2. **命令**：将 `curl -s` 替换为 `irm`，`-X METHOD` 替换为 `-Method Method`
3. **Header**：将 `-H "Key: Value"` 替换为 `-Headers @{"Key"="Value"}`
4. **Body**：将 `-d '{...}'` 替换为 `$body = @{...} | ConvertTo-Json -Depth 10` + `-Body $body`
5. **续行**：将 `\` 替换为 `` ` ``；文件上传场景改用 `curl.exe` 而非 `irm`
6. **Accept Header**：始终包含 `Accept: application/vnd.github+json`（GitHub API 推荐）

***

## §7 接口详情

> 所有示例以 bash 为主。PowerShell 转换规则见 [§6 Shell 格式模板](#6-shell-格式模板)，不在每个接口处重复。
> `<SCRIPT_PATH>` 在初始化阶段替换为本文件所在目录的绝对路径。

***

### Issues 操作（#1-#25）

#### 1. 列出仓库 Issue

`GET repos/{owner}/{repo}/issues`

| 参数        | 位置    | 必填 | 说明                                         |
| --------- | ----- | -- | ------------------------------------------ |
| owner     | path  | ✅  | 仓库所有者                                      |
| repo      | path  | ✅  | 仓库名                                        |
| state     | query | —  | `open`/`closed`/`all`（默认 open）             |
| labels    | query | —  | 逗号分隔的标签名（如 `bug,help wanted`）              |
| assignee  | query | —  | 用户名（`*` = 任何已分配，`none` = 未分配）              |
| sort      | query | —  | `created`/`updated`/`comments`（默认 created） |
| direction | query | —  | `asc`/`desc`（默认 desc）                      |
| per\_page | query | —  | 每页数量（**强制使用 100**）                         |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/issues?state=open&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> **注意**：此接口同时返回 Issue 和 PR。纯 Issue 过滤：排除含 `pull_request` 字段的项。

#### 2. 获取 Issue

`GET repos/{owner}/{repo}/issues/{issue_number}`

| 参数            | 位置   | 必填 | 说明       |
| ------------- | ---- | -- | -------- |
| owner         | path | ✅  | 仓库所有者    |
| repo          | path | ✅  | 仓库名      |
| issue\_number | path | ✅  | Issue 编号 |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 3. 创建 Issue

`POST repos/{owner}/{repo}/issues`

| 参数        | 位置   | 必填 | 说明                           |
| --------- | ---- | -- | ---------------------------- |
| owner     | path | ✅  | 仓库所有者                        |
| repo      | path | ✅  | 仓库名                          |
| title     | body | ✅  | Issue 标题                     |
| body      | body | —  | Issue 内容（Markdown）           |
| labels    | body | —  | 标签数组 `["bug","help wanted"]` |
| assignees | body | —  | 分配人数组 `["user1"]`            |
| milestone | body | —  | 里程碑编号（整数）                    |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Issue 标题",
    "body": "Issue 描述内容",
    "labels": ["bug"],
    "assignees": ["username"]
  }'
```

#### 4. 更新 Issue

`PATCH repos/{owner}/{repo}/issues/{issue_number}`

| 参数            | 位置   | 必填 | 说明                                   |
| ------------- | ---- | -- | ------------------------------------ |
| issue\_number | path | ✅  | Issue 编号                             |
| title         | body | —  | 新标题                                  |
| body          | body | —  | 新内容                                  |
| state         | body | —  | `open`/`closed`                      |
| state\_reason | body | —  | `completed`/`not_planned`/`reopened` |
| labels        | body | —  | 替换全部标签                               |
| assignees     | body | —  | 替换全部分配人                              |

```bash theme={null}
curl -s -X PATCH "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"state": "closed", "state_reason": "completed"}'
```

#### 5. 锁定 Issue

`PUT repos/{owner}/{repo}/issues/{issue_number}/lock`

| 参数           | 位置   | 必填 | 说明                                         |
| ------------ | ---- | -- | ------------------------------------------ |
| lock\_reason | body | —  | `off-topic`/`too heated`/`resolved`/`spam` |

```bash theme={null}
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/lock" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"lock_reason": "resolved"}'
```

#### 9. 创建 Issue 评论

`POST repos/{owner}/{repo}/issues/{issue_number}/comments`

| 参数            | 位置   | 必填 | 说明                   |
| ------------- | ---- | -- | -------------------- |
| issue\_number | path | ✅  | Issue 编号（也适用于 PR 编号） |
| body          | body | ✅  | 评论内容（Markdown）       |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/comments" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"body": "评论内容"}'
```

#### 14. 创建标签

`POST repos/{owner}/{repo}/labels`

| 参数          | 位置   | 必填 | 说明                          |
| ----------- | ---- | -- | --------------------------- |
| name        | body | ✅  | 标签名                         |
| color       | body | ✅  | 颜色（6 位 hex，不带 #，如 `ff0000`） |
| description | body | —  | 标签描述                        |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/labels" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "priority-high", "color": "ff0000", "description": "高优先级"}'
```

#### 18. 添加 Issue 标签

`POST repos/{owner}/{repo}/issues/{issue_number}/labels`

| 参数     | 位置   | 必填 | 说明                            |
| ------ | ---- | -- | ----------------------------- |
| labels | body | ✅  | 标签名数组 `["bug","help wanted"]` |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["bug", "help wanted"]}'
```

#### 21. 添加 Assignees

`POST repos/{owner}/{repo}/issues/{issue_number}/assignees`

| 参数        | 位置   | 必填 | 说明                        |
| --------- | ---- | -- | ------------------------- |
| assignees | body | ✅  | 用户名数组 `["user1","user2"]` |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"assignees": ["username"]}'
```

***

### Pull Requests 操作（#26-#45）

#### 26. 列出 PR

`GET repos/{owner}/{repo}/pulls`

| 参数        | 位置    | 必填 | 说明                                              |
| --------- | ----- | -- | ----------------------------------------------- |
| state     | query | —  | `open`/`closed`/`all`（默认 open）                  |
| head      | query | —  | 过滤源分支（格式 `user:branch`）                         |
| base      | query | —  | 过滤目标分支                                          |
| sort      | query | —  | `created`/`updated`/`popularity`/`long-running` |
| per\_page | query | —  | 每页数量（**强制使用 100**）                              |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/pulls?state=open&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 27. 获取 PR

`GET repos/{owner}/{repo}/pulls/{pull_number}`

| 参数           | 位置   | 必填 | 说明    |
| ------------ | ---- | -- | ----- |
| pull\_number | path | ✅  | PR 编号 |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 返回 `mergeable`（bool/null）和 `mergeable_state`（"clean"/"dirty"/"blocked"/"behind"/"unknown"）。`mergeable` 为 null 表示 GitHub 正在计算，需等待重试。

#### 28. 创建 PR

`POST repos/{owner}/{repo}/pulls`

| 参数    | 位置   | 必填 | 说明                          |
| ----- | ---- | -- | --------------------------- |
| title | body | ✅  | PR 标题                       |
| head  | body | ✅  | 源分支（或 `user:branch` 跨 fork） |
| base  | body | ✅  | 目标分支                        |
| body  | body | —  | PR 描述（Markdown）             |
| draft | body | —  | 是否为草稿 PR                    |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/pulls" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PR 标题",
    "head": "feature-branch",
    "base": "main",
    "body": "PR 描述"
  }'
```

#### 30. 合并 PR ⚠️ DESTRUCTIVE

`PUT repos/{owner}/{repo}/pulls/{pull_number}/merge`

| 参数              | 位置   | 必填 | 说明                        |
| --------------- | ---- | -- | ------------------------- |
| commit\_title   | body | —  | 合并 commit 标题              |
| commit\_message | body | —  | 合并 commit 描述              |
| merge\_method   | body | —  | `merge`/`squash`/`rebase` |
| sha             | body | —  | PR HEAD SHA（确保合并时 PR 未变更） |

```bash theme={null}
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/merge" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"merge_method": "squash", "commit_title": "feat: 新功能"}'
```

#### 31. 列出 PR 文件

`GET repos/{owner}/{repo}/pulls/{pull_number}/files`

| 参数        | 位置    | 必填 | 说明                 |
| --------- | ----- | -- | ------------------ |
| per\_page | query | —  | 每页数量（**强制使用 100**） |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/files?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 38. 创建 PR Review

`POST repos/{owner}/{repo}/pulls/{pull_number}/reviews`

| 参数       | 位置   | 必填 | 说明                                    |
| -------- | ---- | -- | ------------------------------------- |
| event    | body | ✅  | `APPROVE`/`REQUEST_CHANGES`/`COMMENT` |
| body     | body | —  | Review 总结评论                           |
| comments | body | —  | 行内评论数组                                |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"event": "APPROVE", "body": "LGTM!"}'
```

#### 42. 请求 Review

`POST repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers`

| 参数              | 位置   | 必填 | 说明         |
| --------------- | ---- | -- | ---------- |
| reviewers       | body | —  | 用户名数组      |
| team\_reviewers | body | —  | 团队 slug 数组 |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/requested_reviewers" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"reviewers": ["reviewer-username"]}'
```

***

### Repos 操作（#46-#83）

#### 46. 获取仓库

`GET repos/{owner}/{repo}`

| 参数    | 位置   | 必填 | 说明    |
| ----- | ---- | -- | ----- |
| owner | path | ✅  | 仓库所有者 |
| repo  | path | ✅  | 仓库名   |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 49. 创建仓库

`POST user/repos`

| 参数                  | 位置   | 必填 | 说明                               |
| ------------------- | ---- | -- | -------------------------------- |
| name                | body | ✅  | 仓库名                              |
| description         | body | —  | 仓库描述                             |
| private             | body | —  | 是否私有（默认 false）                   |
| auto\_init          | body | —  | 是否自动初始化 README                   |
| gitignore\_template | body | —  | .gitignore 模板（如 `Go`/`Node`）     |
| license\_template   | body | —  | License 模板（如 `mit`/`apache-2.0`） |

```bash theme={null}
curl -s -X POST "https://api.github.com/user/repos" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-repo",
    "description": "仓库描述",
    "private": false,
    "auto_init": true
  }'
```

#### 53. Fork 仓库

`POST repos/{owner}/{repo}/forks`

| 参数           | 位置   | 必填 | 说明                 |
| ------------ | ---- | -- | ------------------ |
| organization | body | —  | Fork 到指定组织（默认当前用户） |
| name         | body | —  | 自定义 Fork 名称        |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/forks" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### 55. 获取文件内容

`GET repos/{owner}/{repo}/contents/{path}`

| 参数   | 位置    | 必填 | 说明                        |
| ---- | ----- | -- | ------------------------- |
| path | path  | ✅  | 文件路径（如 `src/main.go`）     |
| ref  | query | —  | 分支/tag/commit SHA（默认默认分支） |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/contents/README.md" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 返回 `content`（base64 编码）和 `sha`。解码内容：`echo "$content" | base64 -d`。目录返回文件对象数组。

#### 56. 创建/更新文件

`PUT repos/{owner}/{repo}/contents/{path}`

| 参数      | 位置   | 必填 | 说明                      |
| ------- | ---- | -- | ----------------------- |
| path    | path | ✅  | 文件路径                    |
| message | body | ✅  | Commit message          |
| content | body | ✅  | base64 编码的文件内容          |
| sha     | body | ⚠️ | 更新已有文件时**必填**（从 GET 获取） |
| branch  | body | —  | 目标分支（默认默认分支）            |

```bash theme={null}
# 更新已有文件（需要 sha）
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/contents/path/to/file.txt" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "更新文件",
    "content": "SGVsbG8gV29ybGQ=",
    "sha": "CURRENT_FILE_SHA"
  }'
```

#### 61. 列出 Release

`GET repos/{owner}/{repo}/releases`

| 参数        | 位置    | 必填 | 说明                 |
| --------- | ----- | -- | ------------------ |
| per\_page | query | —  | 每页数量（**强制使用 100**） |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/releases?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 65. 创建 Release

`POST repos/{owner}/{repo}/releases`

| 参数                       | 位置   | 必填 | 说明                     |
| ------------------------ | ---- | -- | ---------------------- |
| tag\_name                | body | ✅  | Tag 名（如 `v1.0.0`）      |
| name                     | body | —  | Release 标题             |
| body                     | body | —  | Release 说明（Markdown）   |
| draft                    | body | —  | 是否为草稿                  |
| prerelease               | body | —  | 是否为预发布                 |
| target\_commitish        | body | —  | 创建 Tag 的目标（branch/SHA） |
| generate\_release\_notes | body | —  | 自动生成 Release Notes     |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/releases" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0",
    "name": "Release v1.0.0",
    "body": "## 变更内容\n- 新功能",
    "generate_release_notes": true
  }'
```

#### 69. 上传 Release Asset

`POST uploads.github.com/repos/{owner}/{repo}/releases/{release_id}/assets`

| 参数           | 位置     | 必填 | 说明         |
| ------------ | ------ | -- | ---------- |
| release\_id  | path   | ✅  | Release ID |
| name         | query  | ✅  | 文件名        |
| label        | query  | —  | 显示标签       |
| Content-Type | header | ✅  | 文件 MIME 类型 |

```bash theme={null}
curl -s -X POST "https://uploads.github.com/repos/OWNER/REPO/releases/RELEASE_ID/assets?name=app.zip" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/zip" \
  --data-binary @app.zip
```

> **注意**：域名是 `uploads.github.com`（不是 `api.github.com`），Content-Type 按文件实际类型设置。

***

### Users 操作（#84-#95）

#### 84. 获取认证用户

`GET user`

| 参数 | 位置 | 必填 | 说明  |
| -- | -- | -- | --- |
| —  | —  | —  | 无参数 |

```bash theme={null}
curl -s "https://api.github.com/user" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 86. 获取用户

`GET users/{username}`

| 参数       | 位置   | 必填 | 说明  |
| -------- | ---- | -- | --- |
| username | path | ✅  | 用户名 |

```bash theme={null}
curl -s "https://api.github.com/users/USERNAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 90. 关注用户

`PUT user/following/{username}`

| 参数       | 位置   | 必填 | 说明      |
| -------- | ---- | -- | ------- |
| username | path | ✅  | 要关注的用户名 |

```bash theme={null}
curl -s -X PUT "https://api.github.com/user/following/USERNAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 成功返回 204（无 body）。

#### 93. 添加 SSH Key

`POST user/keys`

| 参数    | 位置   | 必填 | 说明       |
| ----- | ---- | -- | -------- |
| title | body | ✅  | Key 标题   |
| key   | body | ✅  | SSH 公钥内容 |

```bash theme={null}
curl -s -X POST "https://api.github.com/user/keys" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"title": "My SSH Key", "key": "ssh-ed25519 AAAA..."}'
```

***

### Search 操作（#96-#101）

> **限流提醒**：Search API 独立限流 30 req/min（见 §8.5）。批量搜索时注意间隔。

#### 96. 搜索仓库

`GET search/repositories`

| 参数        | 位置    | 必填 | 说明                                             |
| --------- | ----- | -- | ---------------------------------------------- |
| q         | query | ✅  | 搜索查询（支持限定词：`language:go stars:>100 topic:cli`） |
| sort      | query | —  | `stars`/`forks`/`help-wanted-issues`/`updated` |
| order     | query | —  | `asc`/`desc`                                   |
| per\_page | query | —  | 每页数量（最大 100）                                   |

```bash theme={null}
curl -s "https://api.github.com/search/repositories?q=language:go+stars:>1000&sort=stars&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 返回 `total_count` + `items` 数组。`items` 中每个对象含 `full_name`、`html_url`、`description` 等。

#### 97. 搜索 Issues/PRs

`GET search/issues`

| 参数        | 位置    | 必填 | 说明                                                     |
| --------- | ----- | -- | ------------------------------------------------------ |
| q         | query | ✅  | 搜索查询（限定词：`is:issue is:open repo:owner/repo label:bug`） |
| sort      | query | —  | `comments`/`reactions`/`created`/`updated`             |
| order     | query | —  | `asc`/`desc`                                           |
| per\_page | query | —  | 每页数量（最大 100）                                           |

```bash theme={null}
curl -s "https://api.github.com/search/issues?q=is:issue+is:open+repo:cli/cli+label:bug&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> **常用限定词**：`is:issue`/`is:pr`、`is:open`/`is:closed`、`repo:owner/repo`、`author:user`、`label:name`、`assignee:user`。

#### 98. 搜索代码

`GET search/code`

| 参数        | 位置    | 必填 | 说明                                                  |
| --------- | ----- | -- | --------------------------------------------------- |
| q         | query | ✅  | 搜索查询（限定词：`filename:*.go repo:owner/repo path:src/`） |
| sort      | query | —  | `indexed`（按索引日期）                                    |
| order     | query | —  | `asc`/`desc`                                        |
| per\_page | query | —  | 每页数量（最大 100）                                        |

```bash theme={null}
curl -s "https://api.github.com/search/code?q=handleError+repo:cli/cli+filename:*.go&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 代码搜索**必须**指定 `repo:`、`org:` 或 `user:` 限定词，否则返回 422。

#### 99. 搜索 Commits

`GET search/commits`

| 参数        | 位置    | 必填 | 说明                                      |
| --------- | ----- | -- | --------------------------------------- |
| q         | query | ✅  | 搜索查询（限定词：`repo:owner/repo author:user`） |
| sort      | query | —  | `author-date`/`committer-date`          |
| per\_page | query | —  | 每页数量                                    |

```bash theme={null}
curl -s "https://api.github.com/search/commits?q=fix+repo:cli/cli&sort=author-date&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 100. 搜索用户

`GET search/users`

| 参数        | 位置    | 必填 | 说明                                               |
| --------- | ----- | -- | ------------------------------------------------ |
| q         | query | ✅  | 搜索查询（限定词：`type:user location:china language:go`） |
| sort      | query | —  | `followers`/`repositories`/`joined`              |
| per\_page | query | —  | 每页数量                                             |

```bash theme={null}
curl -s "https://api.github.com/search/users?q=type:user+language:go+followers:>100&sort=followers&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 101. 搜索 Topics

`GET search/topics`

| 参数        | 位置    | 必填 | 说明          |
| --------- | ----- | -- | ----------- |
| q         | query | ✅  | Topic 名称关键词 |
| per\_page | query | —  | 每页数量        |

```bash theme={null}
curl -s "https://api.github.com/search/topics?q=machine-learning&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

***

### Actions 操作（#102-#136）

#### 102. 列出仓库 Workflows

`GET repos/{owner}/{repo}/actions/workflows`

| 参数        | 位置    | 必填 | 说明                 |
| --------- | ----- | -- | ------------------ |
| per\_page | query | —  | 每页数量（**强制使用 100**） |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/actions/workflows?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 104. 触发 Workflow ⚠️ DESTRUCTIVE

`POST repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`

| 参数           | 位置   | 必填 | 说明                           |
| ------------ | ---- | -- | ---------------------------- |
| workflow\_id | path | ✅  | Workflow ID 或文件名（如 `ci.yml`） |
| ref          | body | ✅  | 目标分支/tag                     |
| inputs       | body | —  | Workflow 输入参数（key-value 对象）  |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/workflows/ci.yml/dispatches" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"ref": "main", "inputs": {"environment": "staging"}}'
```

> 成功返回 204（无 body）。不返回 run\_id，需通过 workflow:trigger-workflow 流程追踪。

#### 105. 列出 Workflow Runs

`GET repos/{owner}/{repo}/actions/runs`

| 参数        | 位置    | 必填 | 说明                                                |
| --------- | ----- | -- | ------------------------------------------------- |
| status    | query | —  | `completed`/`in_progress`/`queued`/`waiting` 等    |
| branch    | query | —  | 过滤分支                                              |
| event     | query | —  | 触发事件（`push`/`pull_request`/`workflow_dispatch` 等） |
| per\_page | query | —  | 每页数量（**强制使用 100**）                                |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs?status=completed&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 107. 获取 Run

`GET repos/{owner}/{repo}/actions/runs/{run_id}`

| 参数      | 位置   | 必填 | 说明     |
| ------- | ---- | -- | ------ |
| run\_id | path | ✅  | Run ID |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 关键字段：`status`（queued/in\_progress/completed）、`conclusion`（success/failure/cancelled/skipped）。

#### 108. 取消 Run

`POST repos/{owner}/{repo}/actions/runs/{run_id}/cancel`

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/cancel" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 109. 重新运行 Run

`POST repos/{owner}/{repo}/actions/runs/{run_id}/rerun`

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/rerun" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 114. 列出 Run 的 Jobs

`GET repos/{owner}/{repo}/actions/runs/{run_id}/jobs`

| 参数        | 位置    | 必填 | 说明                    |
| --------- | ----- | -- | --------------------- |
| filter    | query | —  | `latest`（仅最新尝试）/`all` |
| per\_page | query | —  | 每页数量                  |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/jobs?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 120. 下载 Artifact

`GET repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip`

```bash theme={null}
curl -sL "https://api.github.com/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID/zip" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -o artifact.zip
```

> 返回 302 重定向到下载 URL，使用 `-L` 跟随重定向。

#### 124. 创建/更新 Secret（需加密）

`PUT repos/{owner}/{repo}/actions/secrets/{secret_name}`

**加密流程**（必须先获取 public key）：

```bash theme={null}
# 步骤 1：获取仓库 public key
curl -s "https://api.github.com/repos/OWNER/REPO/actions/secrets/public-key" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
# 返回：{"key_id": "...", "key": "base64_public_key"}

# 步骤 2：使用 openssl 加密 Secret（无需 libsodium）
# 注意：GitHub 使用 libsodium sealed box 加密，openssl 不能直接替代
# 推荐方式：使用 Python 或 Node.js 的 tweetnacl 库
python3 -c "
import base64, sys
from nacl.public import SealedBox, PublicKey
public_key = base64.b64decode('BASE64_PUBLIC_KEY')
sealed_box = SealedBox(PublicKey(public_key))
encrypted = sealed_box.encrypt(b'SECRET_VALUE')
print(base64.b64encode(encrypted).decode())
"

# 步骤 3：创建/更新 Secret
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/actions/secrets/MY_SECRET" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"encrypted_value": "ENCRYPTED_BASE64", "key_id": "KEY_ID"}'
```

> Secret 值必须使用 libsodium sealed box 加密。Python `pynacl` 或 Node.js `tweetnacl` 均可完成。

#### 129. 创建 Variable

`POST repos/{owner}/{repo}/actions/variables`

| 参数    | 位置   | 必填 | 说明             |
| ----- | ---- | -- | -------------- |
| name  | body | ✅  | Variable 名称    |
| value | body | ✅  | Variable 值（明文） |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/variables" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "ENV_NAME", "value": "production"}'
```

***

### Orgs & Teams 操作（#137-#154）

#### 137. 获取组织

`GET orgs/{org}`

```bash theme={null}
curl -s "https://api.github.com/orgs/ORG_NAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 140. 列出组织成员

`GET orgs/{org}/members`

| 参数        | 位置    | 必填 | 说明                             |
| --------- | ----- | -- | ------------------------------ |
| role      | query | —  | `all`/`admin`/`member`（默认 all） |
| per\_page | query | —  | 每页数量（**强制使用 100**）             |

```bash theme={null}
curl -s "https://api.github.com/orgs/ORG_NAME/members?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 146. 创建团队

`POST orgs/{org}/teams`

| 参数          | 位置   | 必填 | 说明                              |
| ----------- | ---- | -- | ------------------------------- |
| name        | body | ✅  | 团队名称                            |
| description | body | —  | 团队描述                            |
| privacy     | body | —  | `secret`（仅成员可见）/`closed`（组织内可见） |
| permission  | body | —  | `pull`/`push`/`admin`           |

```bash theme={null}
curl -s -X POST "https://api.github.com/orgs/ORG_NAME/teams" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "frontend-team", "description": "前端团队", "privacy": "closed"}'
```

#### 150. 添加团队成员

`PUT orgs/{org}/teams/{team_slug}/memberships/{username}`

| 参数   | 位置   | 必填 | 说明                               |
| ---- | ---- | -- | -------------------------------- |
| role | body | —  | `member`/`maintainer`（默认 member） |

```bash theme={null}
curl -s -X PUT "https://api.github.com/orgs/ORG_NAME/teams/TEAM_SLUG/memberships/USERNAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'
```

***

### Commits & Checks 操作（#155-#168）

#### 155. 列出 Commits

`GET repos/{owner}/{repo}/commits`

| 参数        | 位置    | 必填 | 说明                  |
| --------- | ----- | -- | ------------------- |
| sha       | query | —  | 分支名或 commit SHA     |
| path      | query | —  | 过滤修改了指定路径的 commit   |
| author    | query | —  | 过滤作者（GitHub 用户名或邮箱） |
| since     | query | —  | 起始时间（ISO 8601）      |
| until     | query | —  | 截止时间（ISO 8601）      |
| per\_page | query | —  | 每页数量（**强制使用 100**）  |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/commits?sha=main&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 156. 获取 Commit

`GET repos/{owner}/{repo}/commits/{ref}`

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 返回 `files` 数组含每个变更文件的 filename/status/additions/deletions/patch。

#### 157. 比较 Commits

`GET repos/{owner}/{repo}/compare/{basehead}`

| 参数       | 位置   | 必填 | 说明                                   |
| -------- | ---- | -- | ------------------------------------ |
| basehead | path | ✅  | 格式 `base...head`（如 `main...feature`） |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/compare/main...feature-branch" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 160. 列出 Commit 的 Check Runs

`GET repos/{owner}/{repo}/commits/{ref}/check-runs`

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA/check-runs?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 164. 获取 Combined Status

`GET repos/{owner}/{repo}/commits/{ref}/status`

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA/status" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 返回 `state`（pending/success/error/failure）和 `statuses` 数组。

#### 166. 创建 Commit Status

`POST repos/{owner}/{repo}/statuses/{sha}`

| 参数          | 位置   | 必填 | 说明                                    |
| ----------- | ---- | -- | ------------------------------------- |
| sha         | path | ✅  | Commit SHA                            |
| state       | body | ✅  | `pending`/`success`/`error`/`failure` |
| target\_url | body | —  | 状态详情链接                                |
| description | body | —  | 状态描述                                  |
| context     | body | —  | 状态上下文标识（如 `ci/build`）                 |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/statuses/COMMIT_SHA" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "success",
    "target_url": "https://ci.example.com/build/123",
    "description": "Build passed",
    "context": "ci/build"
  }'
```

***

### Activity 操作（#169-#180）

#### 169. 列出通知

`GET notifications`

| 参数            | 位置    | 必填 | 说明                 |
| ------------- | ----- | -- | ------------------ |
| all           | query | —  | `true` 包含已读通知      |
| participating | query | —  | `true` 仅参与的        |
| since         | query | —  | 起始时间（ISO 8601）     |
| per\_page     | query | —  | 每页数量（**强制使用 100**） |

```bash theme={null}
curl -s "https://api.github.com/notifications?all=false&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 171. 标记通知已读

`PUT notifications`

| 参数             | 位置   | 必填 | 说明                             |
| -------------- | ---- | -- | ------------------------------ |
| last\_read\_at | body | —  | 标记此时间之前的通知为已读（ISO 8601，默认当前时间） |

```bash theme={null}
curl -s -X PUT "https://api.github.com/notifications" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"last_read_at": "2024-01-01T00:00:00Z"}'
```

#### 175. Star 仓库

`PUT user/starred/{owner}/{repo}`

```bash theme={null}
curl -s -X PUT "https://api.github.com/user/starred/OWNER/REPO" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 成功返回 204（无 body）。

#### 177. 列出用户 Starred

`GET users/{username}/starred`

```bash theme={null}
curl -s "https://api.github.com/users/USERNAME/starred?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

#### 178. Watch 仓库

`PUT repos/{owner}/{repo}/subscription`

| 参数         | 位置   | 必填 | 说明     |
| ---------- | ---- | -- | ------ |
| subscribed | body | —  | 是否订阅通知 |
| ignored    | body | —  | 是否忽略通知 |

```bash theme={null}
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/subscription" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"subscribed": true, "ignored": false}'
```

***

### Git Low-level 操作（#181-#190）

#### 181. 创建 Blob

`POST repos/{owner}/{repo}/git/blobs`

| 参数       | 位置   | 必填 | 说明                    |
| -------- | ---- | -- | --------------------- |
| content  | body | ✅  | 文件内容                  |
| encoding | body | —  | `utf-8`（默认）或 `base64` |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/blobs" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"content": "文件内容", "encoding": "utf-8"}'
```

#### 183. 创建 Tree

`POST repos/{owner}/{repo}/git/trees`

| 参数         | 位置   | 必填 | 说明                   |
| ---------- | ---- | -- | -------------------- |
| tree       | body | ✅  | Tree 条目数组            |
| base\_tree | body | —  | 基础 tree SHA（增量更新时使用） |

每个 tree 条目：

| 字段      | 必填 | 说明                                                      |
| ------- | -- | ------------------------------------------------------- |
| path    | ✅  | 文件路径                                                    |
| mode    | ✅  | `100644`（普通文件）/`100755`（可执行）/`040000`（目录）/`160000`（子模块） |
| type    | ✅  | `blob`/`tree`/`commit`                                  |
| sha     | ⚠️ | Blob SHA（与 content 二选一）                                 |
| content | ⚠️ | 直接内联内容（与 sha 二选一）                                       |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/trees" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_tree": "BASE_TREE_SHA",
    "tree": [
      {"path": "src/main.go", "mode": "100644", "type": "blob", "sha": "BLOB_SHA"}
    ]
  }'
```

#### 185. 创建 Commit

`POST repos/{owner}/{repo}/git/commits`

| 参数      | 位置   | 必填 | 说明                         |
| ------- | ---- | -- | -------------------------- |
| message | body | ✅  | Commit message             |
| tree    | body | ✅  | Tree SHA                   |
| parents | body | ✅  | 父 commit SHA 数组            |
| author  | body | —  | 作者信息 `{name, email, date}` |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/commits" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "feat: 通过 API 创建的 commit",
    "tree": "NEW_TREE_SHA",
    "parents": ["PARENT_COMMIT_SHA"]
  }'
```

#### 187. 获取 Ref

`GET repos/{owner}/{repo}/git/ref/{ref}`

| 参数  | 位置   | 必填 | 说明                                 |
| --- | ---- | -- | ---------------------------------- |
| ref | path | ✅  | Ref 路径（如 `heads/main`、`tags/v1.0`） |

```bash theme={null}
curl -s "https://api.github.com/repos/OWNER/REPO/git/ref/heads/main" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
```

> 返回 `object.sha` 即为当前分支指向的 commit SHA。

#### 188. 创建 Ref

`POST repos/{owner}/{repo}/git/refs`

| 参数  | 位置   | 必填 | 说明                                 |
| --- | ---- | -- | ---------------------------------- |
| ref | body | ✅  | Ref 全路径（如 `refs/heads/new-branch`） |
| sha | body | ✅  | 指向的 commit SHA                     |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/refs" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"ref": "refs/heads/new-branch", "sha": "COMMIT_SHA"}'
```

#### 189. 更新 Ref

`PATCH repos/{owner}/{repo}/git/refs/{ref}`

| 参数    | 位置   | 必填 | 说明                     |
| ----- | ---- | -- | ---------------------- |
| ref   | path | ✅  | Ref 路径（如 `heads/main`） |
| sha   | body | ✅  | 新指向的 commit SHA        |
| force | body | —  | 是否强制更新（非 fast-forward） |

```bash theme={null}
curl -s -X PATCH "https://api.github.com/repos/OWNER/REPO/git/refs/heads/main" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"sha": "NEW_COMMIT_SHA"}'
```

***

### Gists 操作（#191-#198）

#### 193. 创建 Gist

`POST gists`

| 参数          | 位置   | 必填 | 说明                                      |
| ----------- | ---- | -- | --------------------------------------- |
| files       | body | ✅  | 文件对象 `{"filename": {"content": "..."}}` |
| description | body | —  | Gist 描述                                 |
| public      | body | —  | 是否公开（默认 false）                          |

```bash theme={null}
curl -s -X POST "https://api.github.com/gists" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "代码片段",
    "public": false,
    "files": {
      "hello.py": {"content": "print(\"Hello World\")"}
    }
  }'
```

#### 194. 更新 Gist

`PATCH gists/{gist_id}`

| 参数          | 位置   | 必填 | 说明                                 |
| ----------- | ---- | -- | ---------------------------------- |
| files       | body | —  | 文件变更（content=null 删除文件，新 key 添加文件） |
| description | body | —  | 新描述                                |

```bash theme={null}
curl -s -X PATCH "https://api.github.com/gists/GIST_ID" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "hello.py": {"content": "print(\"Updated\")"},
      "new_file.txt": {"content": "新文件内容"}
    }
  }'
```

***

### Deployments 操作（#199-#206）

#### 201. 创建 Deployment

`POST repos/{owner}/{repo}/deployments`

| 参数                 | 位置   | 必填 | 说明                            |
| ------------------ | ---- | -- | ----------------------------- |
| ref                | body | ✅  | 部署的分支/tag/SHA                 |
| environment        | body | —  | 环境名（如 `production`/`staging`） |
| description        | body | —  | 部署描述                          |
| auto\_merge        | body | —  | 是否自动合并（默认 true）               |
| required\_contexts | body | —  | 必须通过的状态检查（空数组跳过检查）            |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/deployments" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "environment": "production",
    "description": "部署到生产环境",
    "required_contexts": []
  }'
```

#### 205. 创建 Deployment Status

`POST repos/{owner}/{repo}/deployments/{deployment_id}/statuses`

| 参数               | 位置   | 必填 | 说明                                                                      |
| ---------------- | ---- | -- | ----------------------------------------------------------------------- |
| state            | body | ✅  | `error`/`failure`/`inactive`/`in_progress`/`queued`/`pending`/`success` |
| description      | body | —  | 状态描述                                                                    |
| environment\_url | body | —  | 环境 URL                                                                  |
| log\_url         | body | —  | 日志 URL                                                                  |

```bash theme={null}
curl -s -X POST "https://api.github.com/repos/OWNER/REPO/deployments/DEPLOYMENT_ID/statuses" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "success",
    "description": "部署成功",
    "environment_url": "https://app.example.com"
  }'
```

***

## §8 运维契约

### 8.1 HTTP 错误→AI 行为映射表

收到 API 错误时，AI 必须按以下表格执行对应行为：

| HTTP 状态码                              | 含义                             | AI 行为                                                                          |
| ------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| 400                                   | Bad Request                    | 检查请求体 JSON 语法和必填参数，对照 §7 参数表修正后重试                                              |
| 401                                   | Unauthorized / Bad credentials | 提示用户检查 Token 是否有效或已过期；**绝不在输出中显示 Token 值**                                     |
| 403（body 含 "secondary rate limit"）    | 次级限流                           | 执行限流处理算法（见 §8.3），等待 `retry-after` 或指数退避后重试                                     |
| 403（body 含 "Resource not accessible"） | 权限不足                           | 告知用户：当前 Token 无权执行此操作。引导用户检查 Token scope 或仓库权限设置                               |
| 403（其他）                               | 禁止访问                           | 检查 body 中的 `message` 字段，根据具体原因引导用户（如 "Repository access blocked" → 检查 IP 允许列表） |
| 404                                   | Not Found                      | 验证 owner/repo/资源 ID 是否正确；检查仓库是否为 private（可能需要额外 scope）；提示用户确认资源是否存在            |
| 409                                   | Conflict                       | 存在并发修改冲突（如 merge conflict），报告具体冲突原因，由用户决定处理方式                                  |
| 422                                   | Validation Failed              | 检查请求参数格式（如缺少必填字段、SHA 不匹配、branch 已存在等），解析 `errors` 数组获取详细原因，修正后重试               |
| 429                                   | Rate Limited                   | 执行限流处理算法（见 §8.3）；**所有 HTTP 方法均可重试**                                            |
| 500                                   | Internal Server Error          | 仅对幂等方法（GET/DELETE）自动重试（最多 2 次，指数退避）；POST/PATCH/PUT 报告错误，由用户决定是否重试              |
| 502                                   | Bad Gateway                    | 同 500 处理策略                                                                     |
| 503                                   | Service Unavailable            | 同 500 处理策略                                                                     |

**403 三义歧义处理（关键）**：收到 403 时，AI **必须**先检查响应 body：

1. 包含 `"secondary rate limit"` → **等待重试**（不是权限问题）
2. 包含 `"Resource not accessible"` → **权限不足**（停止，引导用户）
3. 其他 → **读取 message 字段**判断具体原因

### 8.2 Link 头分页契约（算法）

GitHub REST API 使用 `Link` Header 进行分页（不同于 Notion 的 `has_more` / `next_cursor` 模式）。

```
FUNCTION paginate(endpoint, params):
  all_results = []
  url = endpoint + "?" + urlencode(params) + "&per_page=100"

  LOOP:
    response = CALL GET url
    all_results.APPEND(response.body)

    link_header = response.headers["Link"]
    IF link_header CONTAINS rel="next" THEN
      url = EXTRACT url FROM link_header WHERE rel="next"
      GOTO LOOP
    ELSE
      RETURN all_results
    END IF
```

**Link Header 解析规则（强制）**：

1. **始终使用 `per_page=100`**（GitHub 默认仅 30 条，会导致静默数据截断）
2. **解析 `Link` Header**：格式为 `<URL>; rel="next", <URL>; rel="last"`，提取 `rel="next"` 对应的 URL
3. **禁止将部分结果当作完整结果呈现给用户** — 若存在 `rel="next"`，必须继续翻页或明确告知用户"还有更多数据"
4. 翻页完成后，告知用户"已获取全部 N 条结果"
5. **bash 解析示例**：
   ```bash theme={null}
   # 从 Link Header 中提取 next URL
   next_url=$(echo "$link_header" | grep -oP '<\K[^>]+(?=>; rel="next")')
   ```

### 8.3 双路限流处理算法

GitHub 有两层限流机制：

**Primary Rate Limit（主限流）**：

* 认证用户：5,000 requests/hour
* 通过 `x-ratelimit-remaining` 和 `x-ratelimit-reset` Header 监控
* 触发时返回 HTTP 429

**Secondary Rate Limit（次级限流）**：

* 针对短时间内大量请求的额外保护
* 触发时返回 HTTP 403（body 含 `"secondary rate limit"`）
* 通常由并发请求或短时间内创建大量内容触发

```
FUNCTION handle_rate_limit(response, attempt):
  IF attempt > MAX_RETRIES(2) THEN
    FAIL "超过最大重试次数，请稍后再试"
  END IF

  # 检查是否为 429（主限流）
  IF response.status == 429 THEN
    IF response.headers["retry-after"] EXISTS THEN
      wait_seconds = response.headers["retry-after"]
    ELIF response.headers["x-ratelimit-reset"] EXISTS THEN
      wait_seconds = response.headers["x-ratelimit-reset"] - NOW_UNIX
    ELSE
      wait_seconds = MIN(1 * 2^attempt + random(0, 1), 60)
    END IF
  END IF

  # 检查是否为 403 次级限流
  IF response.status == 403 AND response.body CONTAINS "secondary rate limit" THEN
    IF response.headers["retry-after"] EXISTS THEN
      wait_seconds = response.headers["retry-after"]
    ELSE
      wait_seconds = MIN(60 * 2^attempt, 300)  # 次级限流等待更久
    END IF
  END IF

  SLEEP(MIN(wait_seconds, 300))
  RETRY request
```

**x-ratelimit-* Header 说明*\*：

| Header                  | 说明               | 示例                            |
| ----------------------- | ---------------- | ----------------------------- |
| `x-ratelimit-limit`     | 每小时总配额           | `5000`                        |
| `x-ratelimit-remaining` | 当前窗口剩余配额         | `4999`                        |
| `x-ratelimit-reset`     | 配额重置时间（Unix 时间戳） | `1713456000`                  |
| `x-ratelimit-used`      | 当前窗口已使用配额        | `1`                           |
| `x-ratelimit-resource`  | 限流资源类型           | `core` / `search` / `graphql` |

**主动预防**：

* 每次请求后检查 `x-ratelimit-remaining`，若低于 100 则降低请求频率
* 若为 0，等待至 `x-ratelimit-reset` 时间点后再请求

### 8.4 通用约定

1. **Base URL**：`https://api.github.com`（所有端点都基于此地址）
2. **API 版本**：所有请求必须附带 `X-GitHub-Api-Version: 2022-11-28` Header
3. **Accept Header**：所有请求建议附带 `Accept: application/vnd.github+json`
4. **Content-Type**：POST/PATCH/PUT 请求体为 JSON（`application/json`）；文件上传为 `application/octet-stream` 或 `multipart/form-data`
5. **Token 传递**：仅通过 `Authorization: Bearer <token>` Header 传递
6. **ID 格式**：GitHub 使用整数 ID（如 `123456789`），不同于 UUID 格式
7. **日期格式**：ISO 8601（`YYYY-MM-DDTHH:MM:SSZ`）
8. **空响应**：DELETE 和某些 PUT 操作成功返回 HTTP 204（无 body）
9. **PowerShell 注意**：`irm` 是 `Invoke-RestMethod` 别名；文件上传需用 `curl.exe`；续行符为反引号 `` ` `` 而非 `\`

### 8.5 Search API 独立限流说明

Search API 有独立的限流配额，不与核心 API 共享：

| 限制   | 值               | 说明                                   |
| ---- | --------------- | ------------------------------------ |
| 认证用户 | 30 requests/min | 通过 `x-ratelimit-resource: search` 识别 |
| 未认证  | 10 requests/min | 不适用（本 SKILL 始终使用 Token）              |

**Search 限流处理**：

* Search 限流通过 `x-ratelimit-resource: search` 区分
* 触发 429 后按 §8.3 算法处理，但等待时间通常以分钟为单位
* **建议**：批量搜索时在每次请求间间隔 2-3 秒，主动避免触发限流
* Search 结果最多返回前 1,000 条匹配项（GitHub 硬限制），超出需用更精确的查询条件缩小范围