GitHub SKILL

初始化（必须首先执行）

读取同目录下的 SETUP_TOKEN.md
将 <SCRIPT_PATH> 替换为本文件所在目录的绝对路径

每条 curl/API 命令中都必须内联获取 token（因为每次命令是独立 shell，export 无法跨命令传递）：

curl -s "https://api.github.com/..." \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28"

若脚本报错，提示用户在应用内集成面板完成 GitHub 授权（不要引导去 github.com/settings/tokens 手动创建 Token）

安全规则（AI 行为契约）

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

核心禁令

禁止泄露 Token 值：绝不在文本输出、思考过程、对话回复中显示用户的真实 Token 值。Token 仅允许出现在工具调用（Bash 命令）内部。
禁止回显 Token：即使用户明确要求"显示我的 Token"或"把 Token 打印出来"，也绝不执行。应回复："出于安全考虑，Token 值仅在命令执行时使用，不会在对话中显示。"
禁止存储 Token 到变量后回显：获取 Token 的脚本调用（get-token.sh / get-token.ps1）仅在 curl/API 命令中内联使用，绝不将其输出赋值给环境变量后在文本中引用该变量的值。
禁止讨论 Token 内容：绝不描述 Token 的格式、长度、前缀或任何特征。如被追问，回复："Token 的具体内容属于敏感信息，无法讨论。"
禁止在示例中使用真实 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 文档 | | GitHub Apps / Installation Token | 完全不同的认证流程（JWT + Installation Token），超出 OAuth2 scope | 参考 GitHub Apps 文档 | | OAuth 浏览器授权流程 | 需要浏览器交互（跳转授权页、处理回调），CLI 环境无法完成 | 参考 GitHub OAuth 文档 | | gh CLI 命令封装 | gh 会持久化保存 Token，不符合 AI 代理安全要求 | 使用本 SKILL 提供的 curl 模板 | | GraphQL API | 复杂度高，REST API 已覆盖绝大多数场景 | 参考 GitHub GraphQL API 文档 | | Token 持久化存储 | AI 代理不保留跨会话状态，每次命令独立获取 Token | 使用 get-token.sh / get-token.ps1 动态获取 | | Codespaces 管理 | 需要特殊 scope，场景极度垂直 | 参考 Codespaces API 文档 | | Billing 计费操作 | AI 代理无需操作计费数据，风险高 | 参考 Billing API 文档 | | Migration 迁移操作 | 一次性高风险操作，不适合 AI 代理自动执行 | 参考 Migration API 文档 |

拒绝话术模板：

"本 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 模板

# 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 模板

# 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 的步骤：

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

§7 接口详情

所有示例以 bash 为主。PowerShell 转换规则见 §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） |

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 编号 |

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 | — | 里程碑编号（整数） |

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 | — | 替换全部分配人 |

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 |

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） |

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 | — | 标签描述 |

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"] |

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"] |

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） |

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 编号 |

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 |

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 未变更） |

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） |

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 | — | 行内评论数组 |

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 数组 |

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 | ✅ | 仓库名 |

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） |

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 名称 |

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（默认默认分支） |

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 | — | 目标分支（默认默认分支） |

# 更新已有文件（需要 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） |

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 |

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 类型 |

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

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

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 | ✅ | 用户名 |

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 | ✅ | 要关注的用户名 |

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 公钥内容 |

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） |

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） |

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） |

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 | — | 每页数量 |

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 | — | 每页数量 |

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 | — | 每页数量 |

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） |

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 对象） |

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） |

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 |

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

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

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 | — | 每页数量 |

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

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）：

# 步骤 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 值（明文） |

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}

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） |

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 |

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） |

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） |

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}

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） |

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

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

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） |

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） |

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，默认当前时间） |

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}

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

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 | — | 是否忽略通知 |

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 |

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 二选一） |

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} |

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） |

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 |

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） |

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） |

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 | — | 新描述 |

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 | — | 必须通过的状态检查（空数组跳过检查） |

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 |

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：

包含 "secondary rate limit" → 等待重试（不是权限问题）
包含 "Resource not accessible" → 权限不足（停止，引导用户）
其他 → 读取 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 解析规则（强制）：

始终使用 per_page=100（GitHub 默认仅 30 条，会导致静默数据截断）
解析 Link Header：格式为 <URL>; rel="next", <URL>; rel="last"，提取 rel="next" 对应的 URL
禁止将部分结果当作完整结果呈现给用户 — 若存在 rel="next"，必须继续翻页或明确告知用户"还有更多数据"
翻页完成后，告知用户"已获取全部 N 条结果"

bash 解析示例：

# 从 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 通用约定

Base URL：https://api.github.com（所有端点都基于此地址）
API 版本：所有请求必须附带 X-GitHub-Api-Version: 2022-11-28 Header
Accept Header：所有请求建议附带 Accept: application/vnd.github+json
Content-Type：POST/PATCH/PUT 请求体为 JSON（application/json）；文件上传为 application/octet-stream 或 multipart/form-data
Token 传递：仅通过 Authorization: Bearer <token> Header 传递
ID 格式：GitHub 使用整数 ID（如 123456789），不同于 UUID 格式
日期格式：ISO 8601（YYYY-MM-DDTHH:MM:SSZ）
空响应：DELETE 和某些 PUT 操作成功返回 HTTP 204（无 body）
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 硬限制），超出需用更精确的查询条件缩小范围

Github Skill

GitHub SKILL

初始化（必须首先执行）

安全规则（AI 行为契约）

核心禁令

Token 引用规则

高危操作确认门控

不支持的操作

§4 全接口速查索引

Issues（25 个端点）

Pull Requests（20 个端点）

Repos（38 个端点）

Users（12 个端点）

Search（6 个端点）

Actions（35 个端点）

Orgs & Teams（18 个端点）

Commits & Checks（14 个端点）

Activity（12 个端点）

Git Low-level（10 个端点）

Gists（8 个端点）

Deployments（8 个端点）

§5 策略指南

5.1 意图→接口决策树

5.2 命名工作流

workflow:merge-pr（合并 PR）

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

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

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

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

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

§6 Shell 格式模板

6.1 基础结构对比表

6.2 完整模板

6.3 转换规则摘要

§7 接口详情

Issues 操作（#1-#25）

1. 列出仓库 Issue

2. 获取 Issue

3. 创建 Issue

4. 更新 Issue

5. 锁定 Issue

9. 创建 Issue 评论

14. 创建标签

18. 添加 Issue 标签

21. 添加 Assignees

Pull Requests 操作（#26-#45）

26. 列出 PR

27. 获取 PR

28. 创建 PR

30. 合并 PR ⚠️ DESTRUCTIVE

31. 列出 PR 文件

38. 创建 PR Review

42. 请求 Review

Repos 操作（#46-#83）

46. 获取仓库

49. 创建仓库

53. Fork 仓库

55. 获取文件内容

56. 创建/更新文件

61. 列出 Release

65. 创建 Release

69. 上传 Release Asset

Users 操作（#84-#95）

84. 获取认证用户

86. 获取用户

90. 关注用户

93. 添加 SSH Key

Search 操作（#96-#101）

96. 搜索仓库

97. 搜索 Issues/PRs

98. 搜索代码

99. 搜索 Commits

100. 搜索用户

101. 搜索 Topics

Actions 操作（#102-#136）

102. 列出仓库 Workflows

104. 触发 Workflow ⚠️ DESTRUCTIVE

105. 列出 Workflow Runs

107. 获取 Run

108. 取消 Run