better-github-skill

better-github-skill

知道命令时，优先直接使用 gh；这些脚本只替代 Agent 反复出错的流程。脚本可直接运行 TS（node ≥ 23.6），无需依赖项。

脚本

脚本	用途
scripts/pr-snapshot.ts [pr] [-R o/r]	一次调用获取完整 PR 状态：元数据、可合并性、检查、文件、评审、评论和线程计数。可替代手动拼接 pr view --json 字段集合，或串联调用 view/checks/comments。
scripts/pr-threads.ts [pr] [-R o/r] [--all] [--author X] [--since ISO]	获取完整评审对话：评审正文、议题评论和未解决的行内线程（gh 无法通过常规接口获取其解决状态）。默认隐藏已解决或已过时的线程，并在标题中统计数量；--all 会将它们一并列出。只读：除非收到明确指示，否则绝不回复或解决线程。
scripts/ci-failures.ts [run-id] [--pr N] [--list] [-R o/r]	获取失败的检查 → 失败的作业/步骤 → 每项的日志片段；完整日志会保存到文件（并打印路径），应使用 rg 搜索这些文件，而不是重新获取日志。--list [--workflow W] [-L n] 会显示最近运行记录及其结论；用它查找失败运行的 ID，而不要使用 gh run list --json 字段集合。

经验法则：pr-snapshot 回答“这个 PR 的状态如何”，pr-threads 回答“评审者写了什么”。两者不能互相替代。

所有脚本都支持 --json 输出结构化结果，支持 --help 查看用法（包括 --json 的结构）。省略 PR 编号时，会使用当前分支的 PR。默认输出针对上下文长度进行了控制；只有截断标记（[…+N chars]）隐藏了所需内容时，才传入 --full。即使 CI 失败或仍有未解决线程，只要报告成功生成，脚本就会以 0 退出。

注意事项（每一条都曾在实际会话中反复造成问题）

• 切勿将 gh 的输出管道传给 head：SIGPIPE 可能会在 gh 写入过程中将其终止（导致虚假的非零退出，具体取决于 shell），也可能静默截断大型输出。 请将输出重定向到文件并读取，或使用 --jq '.[0:20]' 截取。
• gh pr diff 不支持 --stat，也不支持正向路径规格（gh ≥ 2.95 支持 --name-only 和 -e/--exclude 通配模式）。按文件查看统计信息： gh api 'repos/{owner}/{repo}/pulls/N/files' --jq '.[]|[.filename,.additions,.deletions]|@tsv' 完整差异：运行一次 gh pr diff N > "$TMPDIR/pr.diff"，然后用 rg/sed 搜索文件。
• gh pr checks 以 1 退出表示失败，以 8 退出表示仍在进行，这是预期行为；追加 || true，然后读取表格。
• 获取任意引用下的文件，无需进行 base64 转换： gh api 'repos/{owner}/{repo}/contents/PATH?ref=SHA' -H 'Accept: application/vnd.github.raw'
• gh api 会从当前工作目录所在的仓库填充 {owner}/{repo}（GH_REPO=o/r 可覆盖此设置）。 路径中含 ? 的 api 命令必须加引号（zsh 会将其视为通配符），或者使用 -X GET -F per_page=100 （不带 -X GET 时，任何 -f/-F 都会静默地将请求改为 POST）。
• 对任何列表端点（/comments、/files、/reviews）使用 --paginate；--jq 已经会逐页运行，不要添加 --slurp。
• PR/评论正文：使用 --body-file file.md 或带引号的 heredoc。切勿将包含反引号的内容直接写入 --body "..."。
• 字段速查：PR 上的 CI 状态 = statusCheckRollup（pr view）；步骤位于 gh run view N --json jobs 中；gh search prs 的字段 ≠ gh pr view 的字段。
• gh 不支持 -C；每条命令都传入 -R owner/repo，或者先切换目录。
• 在现代仓库中，分支规则位于 gh api 'repos/{owner}/{repo}/rulesets'；除非启用了经典保护且你拥有管理员权限，否则 /branches/main/protection 会返回 404（“Branch not protected”或纯粹的“Not Found”都表示应检查 rulesets；两者都不是路径错误）。
• 分支偏移情况：gh api 'repos/{owner}/{repo}/compare/BASE...HEAD' --jq '{ahead_by,behind_by}'
• 超过一行的 jq 程序：将程序写入文件并运行 jq -f prog.jq；行内引号在 zsh 中会出问题。
• 不要通过 sleep 轮询运行或检查；可使用 gh run watch ID 和 gh pr checks N --watch --fail-fast；让运行环境在后台执行它们。