github

所有操作都使用 gh CLI。用户的令牌已导出为环境变量， gh 会自动读取它——由于沙盒中没有配置文件，gh auth status 会显示“not logged in”， 但所有需要身份验证的子命令都能正常工作。两种模式下的命令完全相同； 只有权限范围不同，因此在排查 403 之前，先确认你处于哪种模式：

if [ -n "$GITHUB_TOKEN" ]; then echo "mode: pat (user-created token)"; \
elif [ -n "$GH_TOKEN" ]; then echo "mode: oauth"; \
else echo "no GitHub connection — connect at https://studio.acedata.cloud/console/connectors"; fi

两者都是机密信息——在各自权限范围内拥有完整的账户访问权限。切勿回显或 打印它们。

gh --help 和 gh <subcommand> --help 始终是最新的。不确定时， 先阅读帮助信息，不要猜测标志。

已授予的权限范围——你能做什么，不能做什么

在 PAT 模式（$GITHUB_TOKEN）下，权限范围取决于用户创建令牌时的选择， 细粒度令牌可能仅限于少数几个仓库。你无法可靠地检查这些权限范围——请将每个 403 / 404 都视为可能由权限限制导致，并明确说明，而不是重试。

在 OAuth 模式（$GH_TOKEN）下，连接请求的权限范围恰好有五项： read:user、user:email、repo、read:org、gist。下面的操作指南都在这些权限范围内。 以下操作不在范围内，无论你如何组织调用都会失败：

想要……	所需权限范围	结果
关注 / 取消关注用户	user:follow（或完整的 user）	✗ 我们只有 read:user
屏蔽 / 取消屏蔽用户	user	✗
读取 / 写入 Projects V2	read:project / project	✗ INSUFFICIENT_SCOPES
管理 SSH / GPG 密钥	admin:public_key / admin:gpg_key	✗
管理组织成员资格、团队	write:org / admin:org	✗ 通过 read:org 只能读取
管理仓库 Webhook	admin:repo_hook	✗

用户在安装时选择权限范围，每个选项都是可选的，因此上面五项也可能只授予了其中一部分。 对于你确定存在的内容，如果收到 404，或收到 403，通常意味着缺少权限范围——而不是 URL 错误。请明确说明这一点， 并引导用户前往 studio.acedata.cloud/console/connectors，重新连接并勾选相应选项（OAuth），或粘贴具有更广泛权限的令牌（PAT）。

调用 gh 的两种方式——优先使用子命令

方式 A：专用子命令——从这里开始

gh issue、gh pr、gh repo、gh search、gh release、gh workflow、 gh run、gh status、gh label、gh secret、gh variable、gh gist、 gh org、gh ruleset。只要这些命令能完成任务，就优先使用；它们默认 输出格式化文本，也可通过 --json <fields> [--jq <expr>] 输出结构化 JSON。

没有 gh star / gh watch 子命令——这些操作要通过 gh api 执行（见下文）。gh repo fork 确实存在。

方式 B：通过 gh api 调用原始 REST / GraphQL

REST 使用 gh api <endpoint>，GraphQL 使用 gh api graphql -f query='…'。 当没有专用子命令时，这种方式很有用。值得注意的标志：

• -X POST|PATCH|PUT|DELETE — 覆盖请求方法（默认为 GET，设置 -f / -F 后会自动变为 POST）。
• -f key=value — 字符串字段；-F key=value — JSON 类型字段 （true / 123 / @file.json）；两者在 GET 请求中都会进行 URL 编码，在 请求体方法中都会进行 JSON 编码。
• -q '<jq>' — 与 --jq 相同。顶层值为基本类型（字符串 / 数字）时，会直接输出原始值（不带引号）。
• -H 'Accept: application/vnd.github.raw' — 获取文件的原始字节 而非 JSON 封装内容。
• --paginate — 自动遍历 Link: rel="next"。

操作指南

查看待处理事项（issue + PR + 评审 + 提及）

gh status

列出仓库中的近期 issue

gh issue list --repo OWNER/REPO --limit 20
gh issue list --repo OWNER/REPO --state all --limit 20 \
  --json number,title,state,author,updatedAt,labels --jq '.[]'

查看包含评论的 issue

gh issue view 123 --repo OWNER/REPO --comments
gh issue view 123 --repo OWNER/REPO --json title,body,comments \
  --jq '{title, body, comments: [.comments[] | {author: .author.login, body, createdAt}]}'

创建 / 评论 / 关闭 issue

gh issue create --repo OWNER/REPO --title "Bug: foo" --body "Repro steps…" --label bug
gh issue comment 123 --repo OWNER/REPO --body "LGTM"
gh issue close 123 --repo OWNER/REPO --comment "Fixed in #456"
gh issue reopen 123 --repo OWNER/REPO

编辑 issue — 标签、受理人、里程碑、标题、正文

gh issue edit 123 --repo OWNER/REPO --add-label bug --add-assignee @me
gh issue edit 123 --repo OWNER/REPO --remove-label wontfix --milestone "v2.0"
gh issue edit 123 --repo OWNER/REPO --title "New title" --body "Rewritten body"
gh issue lock 123 --repo OWNER/REPO --reason spam
gh issue transfer 123 OWNER/OTHER_REPO --repo OWNER/REPO

--add-project / --remove-project 需要我们没有的 project 权限范围； 它们会失败。此列表中的其他操作均可使用。

列出分配给我 / 由我创建的 PR

gh search prs --assignee=@me --state=open --json number,title,repository,updatedAt
gh search prs --author=@me --state=open
gh search prs --review-requested=@me --state=open

查看包含差异和 CI 检查的 PR

gh pr view 456 --repo OWNER/REPO
gh pr diff 456 --repo OWNER/REPO
gh pr checks 456 --repo OWNER/REPO

创建 / 编辑 PR

gh pr create --repo OWNER/REPO --base main --head feature-branch \
  --title "Add foo" --body "Closes #123" --draft
gh pr edit 456 --repo OWNER/REPO --add-reviewer octocat --add-label review-needed
gh pr edit 456 --repo OWNER/REPO --base develop --title "Retitled"
gh pr ready 456 --repo OWNER/REPO          # draft → ready for review

评论 / 审查 / 合并 PR

gh pr comment 456 --repo OWNER/REPO --body "Please rebase on main."
gh pr review 456 --repo OWNER/REPO --approve --body "LGTM"
gh pr review 456 --repo OWNER/REPO --request-changes --body "See nits"
gh pr merge 456 --repo OWNER/REPO --squash --delete-branch
gh pr update-branch 456 --repo OWNER/REPO  # merge base into the PR branch
gh pr close 456 --repo OWNER/REPO

merge、close 和 review --approve 都是不可逆操作或会公开显示。除非用户明确要求执行相应操作，否则运行前请先向用户确认。

为仓库加星标 / 取消星标

没有 gh 子命令可用——请使用 REST 路由。204 表示成功；已加星标时，GET 返回 204，未加星标时返回 404。

gh api -X PUT    user/starred/OWNER/REPO      # star
gh api -X DELETE user/starred/OWNER/REPO      # unstar
gh api           user/starred/OWNER/REPO      # 204 = starred, 404 = not
gh api user/starred --paginate --jq '.[].full_name'   # list my stars

关注 / 取消关注仓库（通知订阅）

gh api -X PUT repos/OWNER/REPO/subscription -F subscribed=true    # watch
gh api -X PUT repos/OWNER/REPO/subscription -F ignored=true       # ignore
gh api -X DELETE repos/OWNER/REPO/subscription                    # unwatch
gh api user/subscriptions --paginate --jq '.[].full_name'

关注与加星标不同：加星标是公开书签，关注只会改变哪些内容进入用户的通知。

Fork 仓库

gh repo fork OWNER/REPO --clone=false
gh repo fork OWNER/REPO --org MY_ORG --default-branch-only
gh api repos/OWNER/REPO/forks --jq '.[].full_name'

加星标和 Fork 操作会显示在用户的公开个人资料中。除非用户明确要求，否则对他人的仓库执行这些操作前请先确认。

通知

gh api notifications --jq '.[] | "\(.repository.full_name) \(.subject.type) \(.subject.title)"'
gh api -X PATCH notifications                                # mark all read
gh api -X PATCH notifications/threads/<THREAD_ID>            # mark one read

创建 / 管理仓库

gh repo create OWNER/NEW_REPO --private --description "…"
gh repo view OWNER/REPO --json description,url,stargazerCount,defaultBranchRef
gh repo edit OWNER/REPO --description "New desc" --add-topic ai --visibility private
gh repo list OWNER --limit 30 --json name,visibility,updatedAt
gh repo archive OWNER/REPO --yes

gh repo delete 需要 delete_repo，但并未授予此权限，因此会失败。切勿尝试使用它。

发布版本

gh release list --repo OWNER/REPO --limit 10
gh release view v1.2.0 --repo OWNER/REPO
gh release create v1.2.0 --repo OWNER/REPO --title "v1.2.0" --notes "Changelog…"
gh release create v1.2.0 --repo OWNER/REPO --generate-notes ./dist/app.zip
gh release upload v1.2.0 ./extra-asset.tar.gz --repo OWNER/REPO
gh release download v1.2.0 --repo OWNER/REPO --pattern '*.zip'

Gist

gh gist list --limit 20
gh gist create ./script.py --public --desc "Handy script"
gh gist view <GIST_ID>
gh gist edit <GIST_ID>
gh gist delete <GIST_ID>

标签和里程碑

gh label list --repo OWNER/REPO
gh label create urgent --repo OWNER/REPO --color FF0000 --description "Drop everything"
gh label edit bug --repo OWNER/REPO --color 00FF00
gh label clone SOURCE_OWNER/SOURCE_REPO --repo OWNER/REPO

# Milestones have no gh subcommand — use the API
gh api repos/OWNER/REPO/milestones --jq '.[] | "\(.number) \(.title) \(.open_issues) open"'
gh api -X POST repos/OWNER/REPO/milestones -f title="v2.0" -f due_on="2026-12-31T23:59:59Z"

分支、提交和比较

gh api repos/OWNER/REPO/branches --jq '.[].name'
gh api "repos/OWNER/REPO/commits?per_page=20" \
  --jq '.[] | "\(.sha[0:7]) \(.commit.author.date) \(.commit.message | split("\n")[0])"'
gh api repos/OWNER/REPO/compare/main...feature-branch \
  --jq '{ahead: .ahead_by, behind: .behind_by, files: [.files[].filename]}'
gh api -X DELETE repos/OWNER/REPO/git/refs/heads/stale-branch

读取 / 写入仓库中的文件

# Read raw bytes, no base64 dance
gh api "repos/OWNER/REPO/contents/path/to/file.ts" \
  -H 'Accept: application/vnd.github.raw'

# Write requires base64 content + the current blob sha when replacing
SHA=$(gh api repos/OWNER/REPO/contents/README.md --jq .sha)
gh api -X PUT repos/OWNER/REPO/contents/README.md \
  -f message="docs: update readme" \
  -f content="$(base64 < ./README.md | tr -d '\n')" \
  -f sha="$SHA"

在 GitHub 上搜索

gh search code 'someFunction language:typescript' --limit 20 \
  --json repository,path,url --jq '.[] | "\(.repository.nameWithOwner) \(.path)"'
gh search repos 'topic:mcp stars:>100' --limit 20 --json fullName,stargazersCount
gh search commits 'fix memory leak' --repo OWNER/REPO --limit 10
gh search issues 'is:open label:bug' --owner OWNER --limit 20

触发 / 检查 Actions 工作流

gh workflow list --repo OWNER/REPO
gh workflow run ci.yaml --repo OWNER/REPO --ref main -f key=value
gh run list --repo OWNER/REPO --workflow ci.yaml --limit 5
gh run view <RUN_ID> --repo OWNER/REPO --log-failed
gh run rerun <RUN_ID> --repo OWNER/REPO --failed
gh run cancel <RUN_ID> --repo OWNER/REPO
gh run watch <RUN_ID> --repo OWNER/REPO

Actions 密钥和变量

gh secret list --repo OWNER/REPO
gh secret set MY_TOKEN --repo OWNER/REPO --body "value"
gh variable list --repo OWNER/REPO
gh variable set MY_VAR --repo OWNER/REPO --body "value"

密钥值只能写入，不能读取——你可以设置密钥并列出名称，但无法读回密钥值。切勿将用户提供的密钥回显到评论、议题或提交中。

组织（在 read:org 权限下只读）

gh org list
gh api user/orgs --jq '.[].login'
gh api orgs/ORG/members --jq '.[].login'
gh api orgs/ORG/repos --paginate --jq '.[].full_name'

使用 GraphQL 完成 REST 无法实现的操作

gh api graphql -f query='
  query($owner: String!, $repo: String!, $num: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $num) {
        title
        timelineItems(first: 50) {
          nodes { __typename ... on CrossReferencedEvent { source { ... on PullRequest { number title state } } } }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F num=123

Projects V2 只能通过 GraphQL 使用，并且需要 read:project 权限；该权限未获授，因此这些查询会返回 INSUFFICIENT_SCOPES。请勿基于此编写操作方案。

注意事项

• 对于私有仓库，用户在 studio.acedata.cloud/console/connectors 授权连接时必须授予 repo 权限。对于你确定存在的仓库，如果返回 404，通常意味着缺少权限，而不是 URL 错误。
• 如果 --json 拒绝某个字段名，gh 会打印所有有效字段；请重新阅读错误信息并从中选择。
• gh issue list --search 和 gh search issues 使用 GitHub 搜索语法（is:open、assignee:@me、repo:owner/name 等）。跨仓库查询请使用 gh search issues / gh search prs；单个仓库请使用 gh issue list。
• gh api --paginate 仅适用于会返回 Link 标头的端点；对于基于游标的分页端点，你必须自行跟进 pagination.next。
• 无需请求正文的写入端点（加星标、关注、删除关注）成功时会返回 204 No Content——空响应表示成功，而非失败。
• 此连接可以在计划任务中无人值守地运行。公开操作（加星标、Fork、议题 / PR 评论、审查、合并）会在用户账户上留下永久且可公开追溯的记录。无人值守运行时，务必严格遵循任务授权的操作。