项目	内容
来源	skills/github-skill/SKILL.md
分类	开发工程 & 工作流
安装	克隆 Skill 分支后，将 `skills/github-skill/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 Skill 安装方式

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

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

​安全规则（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

​109. 重新运行 Run