gh CLI的--json+jq已经把PR/issue/Actions全流程脚本化，为什么多数人还在网页上手动点，自动化的起点到底卡在哪？

目录

一、导语：一个被反复验证却很少被解释的现象

在任何一个使用 GitHub 的中大型团队里，几乎都能观察到同一幕：一位资深工程师在终端里熟练地敲 gh pr list --json number,title,reviewDecision，然后用 jq 过滤出待处理的 PR；几秒钟后，他打开浏览器，逐条点进 PR 页面，手动点击 "Approve"、手动选择合并策略、手动触发一次重跑。终端里的查询能力与网页上的操作行为，在同一分钟内并存，且互不干扰。这个现象不是个例，而是行业常态。

GitHub CLI 的 --json 参数自 2.0 版本起成为一等公民，官方文档明确列出了 PR、Issue、Release、Actions 等命令族可导出的字段集合（GitHub CLI Manual, 2024）。jq 作为 JSON 流处理器，其 DSL 早已被证明足以表达过滤、映射、归约、分组等常见数据变换（jq Manual, 2024）。从纯能力角度看，"查询—判断—执行"三段式脚本所需的原语全部就位：查询有 --json，判断有 jq 的 select/if-then-else，执行有 gh pr merge、gh issue edit、gh run rerun。那么，为什么绝大多数人仍然停在"查询用脚本、执行靠手点"的半自动化状态？

笔者认为，把这个问题归因于"开发者懒"或"工具不好用"都是偷懒的解释。真正的原因藏在能力与行为之间：网页界面承载了一套隐式的状态机——它告诉你当前 PR 处于什么状态、下一步允许做什么、做完之后会进入什么状态、出错如何回退。这套状态机从未被显式写下来，因此也从未被脚本继承。脚本继承的是"命令"，而不是"判断"。这就是本文要展开的核心命题。

二、背景与问题定义：能力供给与行为采纳的错位

2.1 能力供给侧的三个里程碑

要理解错位，先要理解供给侧的演进。GitHub 的自动化能力大致经历了三个里程碑。第一个是 REST API 与 GraphQL API 的开放，使程序化访问成为可能，但早期 API 的鉴权、分页与速率限制对脚本作者并不友好。第二个是 GitHub Actions 的发布（2019 年正式可用），把"事件触发—执行"的范式引入平台内部，使 CI/CD 与仓库事件天然耦合。第三个是 GitHub CLI 的 --json 结构化输出与扩展机制，把原本需要手写 GraphQL 查询的工作，收敛为一条带字段列表的命令。

本文评述：这三个里程碑的共同特征是"降低调用成本"，但它们都没有降低"建模成本"。调用一条命令很容易，决定"在什么条件下调用哪条命令、调用失败后怎么办"很难。供给侧的进步集中在动词（verb）层面，而自动化的真正难点在名词（state）与连词（condition）层面。这一判断构成了后文所有分析的前提。

2.2 行为采纳侧的三个摩擦点

从行为采纳的角度看，摩擦点可以归纳为三类。其一是认知摩擦：开发者知道 gh pr list --json 能查，但不确定"合并一个 PR 需要先满足哪些前置条件"，于是宁可让网页的按钮置灰来告诉他。其二是信任摩擦：脚本一旦写错，可能批量误合并、误关闭，破坏性远大于手动点击，因此团队倾向于把"写操作"留在人工环节。其三是维护摩擦：一次性脚本写完就腐化，字段变更、权限调整、仓库迁移都会让它失效，而网页界面由平台维护，永不腐化。

这三类摩擦点并非并列关系。笔者认为，认知摩擦是根因，信任摩擦与维护摩擦是它的派生。因为判断逻辑没有被写下来，所以无法审计、无法测试、无法复用，于是不可信、不可维护。把判断写下来，是同时缓解三类摩擦的唯一杠杆。这一推断与软件工程中"显式优于隐式"（explicit is better than implicit）的经典原则一致，但本文要强调的是它在"人机协作界面"这一特定场景下的具体形态。

2.3 问题重述：从"能不能"到"敢不敢、值不值"

据此，本文把原始问题重述为三个可检验的子问题：第一，gh + jq 在技术上是否足以覆盖 PR/Issue/Actions 的全流程写操作？第二，若足以覆盖，缺失的中间层具体是什么、能否被形式化描述？第三，在什么边界条件下，脚本化的收益会超过其维护成本？这三个子问题分别对应后文的原理、数据与局限三章。

定义（本文采用）：状态机显式化指把某一协作流程中"对象所处状态、允许的转移、转移的触发条件与副作用"以机器可读的形式（脚本、配置或代码）固定下来，使该流程可被程序重复执行、审计与回滚。它与"命令脚本化"的区别在于：后者只固定动词，前者固定动词、名词与连词。

三、原理与技术路线：从命令拼接到状态机显式化

3.1 第一层：结构化查询与字段契约

gh 的 --json 参数接受一个逗号分隔的字段列表，输出稳定的 JSON 数组。以 PR 为例，常用字段包括 number、title、state、isDraft、mergeable、reviewDecision、statusCheckRollup、headRefName、baseRefName、author、updatedAt 等。这些字段构成了脚本可消费的"事实层"。关键在于：字段列表本身就是一份契约，它把"脚本关心什么"显式声明出来，而不是让脚本去解析人类可读的表格输出。

# 拉取开放 PR 的关键字段，输出为 JSON 数组
gh pr list --state open --limit 200 \
  --json number,title,isDraft,mergeable,reviewDecision,statusCheckRollup,headRefName,baseRefName,updatedAt

本文评述：字段契约的价值常被低估。它实际上是把"人看表格时自动忽略的列"变成了"脚本必须显式声明的列"。这种从隐式到显式的转换，正是状态机显式化的第一步——先固定事实，再固定判断。若跳过这一步直接写 if 判断，脚本会迅速退化为对输出格式的脆弱依赖。

3.2 第二层：jq 作为判断表达层

jq 提供 select、map、group_by、reduce、if-then-elif-else 等构造，足以表达"哪些 PR 可以合并"这类判断。一个典型的可合并判定可以写成：非草稿、可合并、评审已通过、且所有必需检查通过。这四条判断在网页上由按钮置灰隐式表达，在脚本中则必须显式写出。

# 可合并判定：把网页按钮的置灰逻辑显式化
gh pr list --state open --limit 200 \
  --json number,isDraft,mergeable,reviewDecision,statusCheckRollup \
| jq -r '
  .[]
  | select(.isDraft == false)
  | select(.mergeable == "MERGEABLE")
  | select(.reviewDecision == "APPROVED")
  | select(
      [.statusCheckRollup[]? | select(.conclusion != "SUCCESS" and .conclusion != "NEUTRAL" and .conclusion != "SKIPPED")] | length == 0
    )
  | .number
'

这段脚本的意义不在于它多聪明，而在于它把"什么算可合并"从人的直觉变成了可读、可评审、可测试的表达式。笔者认为，这是整个自动化链条中性价比最高的一步：成本是一次性的表达式编写，收益是判断逻辑从此可以被 code review、被单元测试、被版本管理。相比之下，直接调用 gh pr merge 而不写判定，等于把判断留在了人的脑子里，脚本只是替手执行，并未替脑思考。

3.3 第三层：状态与转移的形式化

仅有判定还不够。真实流程是有顺序的：先等检查通过，再等评审，再合并，合并后可能还要删分支、关联 Issue、触发下游。这些顺序构成一个状态机。本文建议用一张显式的状态转移表来固定它，而不是用一长串 if 堆叠。

本文评述：这张表的价值在于它把"网页上按钮何时可用"这一隐式知识，转写为可被程序读取的转移规则。一旦有了这张表，脚本就不再是一堆命令的拼接，而是一个可验证的有限状态机。工程上，这意味着可以为每条转移写测试、为每次状态变更记日志、为异常转移设告警。笔者认为，状态转移表是"命令脚本化"与"流程自动化"之间的分水岭，也是本文分析主线的核心载体。

3.4 第四层：事件驱动与幂等性

状态机解决了"做什么"，事件驱动解决了"何时做"。GitHub Actions 的 on: 触发器（pull_request、issues、schedule、workflow_dispatch 等）提供了平台级的事件源，而 gh 命令可以在 workflow 内部调用，形成"事件—判断—动作"的闭环。但这里有一个常被忽视的工程要求：幂等性。事件可能重复投递，脚本可能被重跑，动作必须设计成"执行多次与执行一次效果相同"。

# 幂等示例：仅在尚未打标签时才打标签
if ! gh pr view "$PR" --json labels --jq '.labels[].name' | grep -qx "needs-review"; then
  gh pr edit "$PR" --add-label "needs-review"
fi

本文评述：幂等性是把脚本从"一次性工具"提升为"可长期运行服务"的关键约束。它要求作者在写每个写操作前，先问一句"如果这条命令被执行两次会怎样"。这个问题的答案，往往比命令本身更能暴露流程设计中的漏洞。笔者认为，幂等性检查应当成为 code review 中针对自动化脚本的必检项，其重要性不亚于业务逻辑正确性。

四、关键数据与案例：脚本化的收益边界在哪里

4.1 公开可查的效能数据

关于研发效能与自动化的量化关系，业界已有若干公开研究可供参照。DORA（DevOps Research and Assessment）在其年度报告中长期追踪"部署频率、变更前置时间、变更失败率、恢复时间"四项指标，并指出高绩效团队在"流程自动化"维度上显著领先（Forsgren et al., 2018；DORA Report, 2023）。Google 的《Software Engineering at Google》一书亦讨论了代码审查与自动化检查对评审效率的影响（Winters et al., 2020）。需要说明的是，这些研究测量的是"组织级自动化水平"与"交付绩效"的相关性，而非"gh CLI 脚本化"这一具体手段的直接因果效应。本文引用它们，是为了给"自动化有收益"这一前提提供证据，而非夸大单一工具的作用。

本文评述：在缺乏针对 gh + jq 的对照实验的情况下，任何"脚本化能提升 X%"的具体数字都应被视为估算而非结论。笔者建议团队在内部做小规模前后对照：选取一个仓库、一个季度，记录"人工合并 PR 的平均耗时"与"脚本辅助后的平均耗时"，并注明样本量与置信区间。这种自建数据虽不具普适性，但对本团队决策的价值远高于外部引用。

4.2 一个可复现的案例：批量清理陈旧 PR

考虑一个常见场景：仓库中积累了大量超过 30 天无活动的开放 PR。人工处理需要逐条打开、判断、评论、打标签。用 gh + jq 可以写成一条可审计的流水线：先查询，再过滤，再对每条执行"评论 + 打标签"，且全程幂等。

# 找出 30 天无活动的开放 PR，打上 stale 标签并留言（幂等）
CUTOFF=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-30d +%Y-%m-%dT%H:%M:%SZ)

gh pr list --state open --limit 500 \
  --json number,updatedAt,labels \
| jq -r --arg cutoff "$CUTOFF" '
  .[]
  | select(.updatedAt < $cutoff)
  | select([.labels[].name] | index("stale") | not)
  | .number
' \
| while read -r pr; do
    gh pr edit "$pr" --add-label "stale"
    gh pr comment "$pr" --body "本 PR 已 30 天无活动，标记为 stale。如仍需推进，请留言说明。"
  done

这个案例的工程价值在于三点：其一，判定条件（30 天、无 stale 标签）被显式写出，可被评审；其二，动作幂等，重跑不会重复打标签；其三，整条流水线可放入 Actions 的 schedule 触发器，变成周期性任务。笔者认为，这类"低风险、高频次、规则明确"的流程，是脚本化收益最高的切入点，也是团队建立信任的最佳起点。相反，"高风险、低频次、规则模糊"的流程（如自动合并核心模块）应最后纳入。

4.3 Actions 全流程脚本化的关键约束

Actions 的脚本化有一个容易被忽略的约束：GITHUB_TOKEN 的默认权限是只读的，写操作需要在 workflow 中显式声明 permissions。此外，由 GITHUB_TOKEN 触发的事件不会再次触发 workflow，这一"防递归"设计会影响链式自动化的设计。理解这些边界条件，比记住命令更重要。

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Triage stale PRs
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr list --state open --json number,updatedAt \
          | jq -r '.[] | select(.updatedAt < "2024-01-01T00:00:00Z") | .number' \
          | xargs -r -n1 gh pr edit --add-label stale

本文评述：权限与触发链的约束，恰恰是"信任摩擦"的技术根源。团队不敢把写操作交给脚本，部分原因正是这些约束不透明、出错后难以定位。笔者认为，把权限声明、触发条件、幂等检查三者写进同一份 workflow 文件，并配以清晰的注释，是降低信任摩擦的有效手段。可读的自动化，才是可被信任的自动化。

五、对比与局限：五类自动化路径的取舍矩阵

把 PR/Issue/Actions 流程自动化，并非只有 gh + jq 一条路。下表对比五类常见路径，帮助读者按场景取舍。

本文评述：这张矩阵揭示了一个常被忽视的事实——"自动化程度"并非越高越好，而是要与"流程的规则清晰度"匹配。规则越清晰、频次越高、风险越低，越适合用脚本；规则越模糊、频次越低、风险越高，越应保留人工判断。笔者认为，多数团队的问题不是"自动化不足"，而是"自动化错配"：把该自动的留给了人，把该留人的交给了脚本。识别错配，比追求覆盖率更有价值。

局限方面，本文的分析有三点需要坦白。第一，缺乏针对 gh + jq 的严格对照实验，收益估算依赖间接证据与团队自建数据。第二，gh 的字段集合随版本演进，本文示例基于 2024 年前后的文档，读者应以其所用版本的 gh help 输出为准。第三，状态机显式化本身有成本，对极小团队或极短周期项目，可能得不偿失。这些局限不削弱主线判断，但界定了它的适用边界。

六、落地路径：四阶段操作手册

6.1 阶段一：只读盘点（1–2 周）

目标是把"团队在网页上到底点了什么"变成一份可统计的清单。做法是：用 gh pr list --json、gh issue list --json、gh run list --json 导出近 90 天数据，用 jq 统计各类操作的频次与分布。此阶段严禁写操作，只做观测。产出物是一份"高频操作 Top 10"清单，标注每项的风险等级（是否可逆、影响范围）。

# 统计近 90 天合并 PR 的评审状态分布（只读）
gh pr list --state merged --limit 1000 \
  --json number,reviewDecision,mergedAt \
| jq -r '.[] | select(.mergedAt > "2024-01-01") | .reviewDecision' \
| sort | uniq -c | sort -rn

6.2 阶段二：判定表达式化（2–3 周）

从 Top 10 中挑选"规则明确、可逆、低频风险"的 1–2 项，把其判断条件写成 jq 表达式，并配单元测试（用固定 JSON 输入验证输出）。此阶段仍不自动执行写操作，而是把表达式输出给人工确认，形成"脚本建议、人来执行"的半自动模式。产出物是一组带测试的判定表达式，纳入版本管理。

6.3 阶段三：幂等写操作（3–4 周）

在判定表达式稳定后，接入写操作，但必须满足三条硬约束：每条写操作前有存在性检查（幂等）、每次执行有日志、每个动作可单独回滚。建议先在非核心仓库试运行两周，收集误报与漏报，再推广。产出物是一份可复用的脚本库与一份运行日志规范。

6.4 阶段四：事件驱动与治理（持续）

把稳定运行的脚本迁入 Actions，用 schedule 或 pull_request 触发，并显式声明 permissions。同时建立治理机制：谁可以修改脚本、修改后如何评审、异常如何告警、指标如何度量。产出物是一份"自动化运行手册"，把状态转移表、权限声明、回滚步骤写在一起。至此，隐式的网页操作被完整地转写为显式的、可审计的、可回滚的自动化流程。

延伸阅读：GitHub CLI 官方手册（cli.github.com/manual）、jq 官方手册（jqlang.github.io/jq/manual）、GitHub Actions 权限文档（docs.github.com）。

七、结论与展望：自动化的起点是"写下判断"

回到开篇的问题：gh 的 --json 与 jq 已经把 PR/Issue/Actions 全流程脚本化，为什么多数人还在网页上手动点？本文的答案是：脚本化的是命令，未脚本化的是判断；网页承载的隐式状态机从未被显式写下，因此无法被脚本继承。自动化的起点，不是学会某条命令，而是愿意把"我在什么条件下做什么、做完之后进入什么状态、出错如何回退"写下来。写下判断，是认知摩擦、信任摩擦、维护摩擦的共同解药。

展望未来，笔者认为有三个方向值得关注。其一是"判定即配置"：把状态转移表从脚本中抽出，变成可被工具消费的声明式配置，降低非程序员参与自动化的门槛。其二是"自动化可观测性"：为脚本运行建立指标与告警，使自动化本身成为可被度量的对象。其三是"人机分工的动态调整"：随着规则清晰度提升，逐步把判断从人移交给脚本，而非一次性全盘自动化。这三点的共同前提，仍是本文反复强调的那句话——先把判断写下来。

最后需要强调，本文不主张"消灭手动点击"。手动点击在低频、高风险、规则模糊的场景中仍有不可替代的价值。本文主张的是：让每一次手动点击都有明确的理由，让每一次自动执行都有可查的依据。当团队能清楚说出"这一步为什么手动、那一步为什么自动"时，自动化的起点才算真正跨过。

主要参考文献