波仔
🐎 第7章 无为而治：Headless 模式与 CI／CD 集成
📄 一句话概括

自动审查有两种接法：用官方封装好的 Action，或者自己装 CLI 再调。前者省事，后者可控。 真解析两份工作流：顶层键一样多（骨架是平台定的）， 差别在步骤——官方只有一步，CLI 是四步，每一步都能插东西。

📝 本章和前面几章的关系

上一节在本地跑管道，这一节搬到 CI 上：每次提 PR 就自动审查一遍。 这一节的两份配置都是教材原样，本沙箱没有 GitHub，跑不起来；但配置的结构可以真解析。

一、两条路

第一条：用官方 Action。它有固定的输入参数，你在 with 下面填。 第二条：自己装 CLI 再调。工作流里跑几条命令，参数自己拼。 差别不在功能，在「谁能改哪些参数」和「出问题时能看见什么」。

所以选择的第一问不是「哪个更好」，是「我要不要在中途插一步」。

二、官方 Action 的形状

整个作业除了检出代码，就只有一步：调用 Action，把密钥和提示词传进去。 权限写在 permissions 段里：读代码、写 PR 评论。这个写法本身就值得学。 它的好处是「不用管版本」——Action 自己维护运行环境，你只填参数。

坏处也一样：它不暴露的东西，你就改不了。

三、直接调 CLI 的形状

四步：检出、装 CLI、跑、看结果。 跑的那一步把参数全写出来了：输出格式、轮数上限、允许的工具、禁止的工具。 这意味着你能精确控制它碰什么、花多少。也能在前后插自己的步骤。

代价是「装」这一步会引入版本问题：装哪个版本、装多久、失败了怎么办。

四、真解析：两份配置差在哪

演示里把两份 YAML 都解析了一遍：顶层键数量一样（三个），步骤数一个二、一个四。 顶层键一样多，是因为工作流的骨架由平台定死，不由写法定。 差别全在步骤里：官方那份，参数藏在 with 下面；CLI 那份，参数摊在命令行上。

「参数摊开」这件事在排查时特别有用：出问题时你一眼能看到它到底带了什么参数。

五、无论哪条路，两件事必须设

第一，权限。工作流默认拿到的令牌权限可能比你想要的大，用 permissions 收窄。 第二，密钥。API Key 只能来自 secrets，不能写在文件里——这和 6.4 节那条是同一条规矩。 审查任务还有第三个要求：它要能在 PR 里留言。所以既要读代码，也要写评论，但不能写代码。

这个「三选二」很关键：给了写代码的权限，它就能自己改，而审查的结论就不独立了。

六、动手 Demo：官方 Action 和直接调 CLI，两份配置差在哪

自动审查有两种接法：用官方封装好的 Action，或者自己装 CLI 再调。 前者省事，后者可控。这里把两份真实形态的工作流解析一遍，看差别落在哪儿。

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "审查这次改动，只报会出问题的地方"

实跑输出：

--------------------------------------------------------------------
官方 Action 和直接调 CLI，两份配置差在哪
--------------------------------------------------------------------

  自动审查这件事有两种接法：用官方封装好的 Action，或者自己装 CLI 再调。
  前者省事，后者可控。差别不在功能，在「谁能改哪些参数」。

  ① 官方 Action 的写法
  --------------------------------------------------------------------

  [工作流文件 · 教材原样，本沙箱不执行]
  | name: code-review
  | on: [pull_request]
  | 
  | jobs:
  |   review:
  |     runs-on: ubuntu-latest
  |     permissions:
  |       contents: read
  |       pull-requests: write
  |     steps:
  |       - uses: actions/checkout@v4
  |       - uses: anthropics/claude-code-action@v1
  |         with:
  |           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
  |           prompt: "审查这次改动，只报会出问题的地方"


  ② 直接调 CLI 的写法
  --------------------------------------------------------------------

  [工作流文件 · 教材原样，本沙箱不执行]
  | name: code-review-cli
  | on: [pull_request]
  | 
  | jobs:
  |   review:
  |     runs-on: ubuntu-latest
  |     steps:
  |       - uses: actions/checkout@v4
  |       - run: npm install -g @anthropic-ai/claude-code
  |       - run: |
  |           claude -p "审查这次改动" \
  |             --output-format json \
  |             --max-turns 8 \
  |             --allowed-tools "Read,Grep" \
  |             --disallowed-tools "Bash,Write" > review.json
  |       - run: cat review.json


  ③ 两份配置真解析一遍
  --------------------------------------------------------------------
| 写法 | 顶层键 | 步骤数 |
|---|:---:|:---:|
| 官方 Action | 3 | 2 |
| 直接调 CLI | 3 | 4 |

  顶层键都一样多——因为工作流的骨架是 GitHub 定的，不是这两种写法定的。
  差别在步骤里：官方 Action 除了 checkout 就一步，参数全藏在 with 下面；
  直接调 CLI 是四步——装、跑、看结果，每一步都能往里插自己的命令。

  ④ 两条路的取舍
  --------------------------------------------------------------------
| 写法 | 上手成本 | 能控的参数 | 出问题时的可见性 |
|---|---|---|---|
| 官方 Action | 一步搞定 | 它暴露的那几个 | 黑盒，出错只能看它的日志 |
| 直接调 CLI | 要装、要拼命令 | 全部 | 白盒，每一步都能加东西 |

  选官方 Action 的条件：需求就是它默认干的那件事。
  选 CLI 的条件：你要在中间插一步（比如先跑 lint、或者把结果发到别的地方）。

  ⑤ 无论哪条路，两件事必须设
  --------------------------------------------------------------------
  第一，权限。工作流默认拿到的令牌权限可能比你想要的大，写在 permissions 里收窄。
  第二，密钥。API Key 只能来自 secrets，不能写在文件里——这和 6.4 节那条规矩是同一条。
  审查任务还有一个额外要求：它要能在 PR 里留言。
  所以既要读权限，也要写评论的权限，但不能给写代码的权限。
  ! 这两份 YAML 是形状演示，字段以官方文档为准；本沙箱没有 GitHub，跑不起来。

①两条路：官方 Action 参数藏在 with 下面；直接调 CLI 参数摊在命令行上。 差别不在功能，在「谁能改哪些参数」和「出问题时能看见什么」。 ②两份 YAML 顶层键一样多（三个），因为工作流的骨架是平台定死的。差别在步骤：一份两步、一份四步。 ③官方那份除了检出就只有一步，不用管版本； CLI 那份四步，能在前后插自己的步骤，代价是「装哪个版本」要自己负责。 ④无论哪条路，两件事必须设：权限用 permissions 收窄，密钥只能来自 secrets。 审查任务还要第三个：能写 PR 评论。但绝不能给写代码的权限——给了它就能自己改，审查的结论就不独立了。

30 秒实验

  1. 给 CLI 那份加一步「先跑 lint，不过就直接退出」，重跑一遍。官方 Action 那份能加吗？为什么？
  2. 把两份配置里的 permissions 都删掉，重跑一遍。解析结果变了吗？ 这说明「结构检查」和「安全检查」是不是一回事？
  3. 把 CLI 那份的 --allowed-tools 从 Read,Grep 改成不限制，重跑一遍。 配置解析得出来，但风险变成什么？

常见误区

  1. 把 API Key 写进工作流文件。文件进版本库，密钥就进了历史。
  2. 给审查任务开写代码的权限。它自己能改，结论就不独立了。
  3. 不写 permissions，用平台默认权限。默认往往比你要的大。
  4. 用官方 Action 却在它不支持的参数上折腾。它不暴露的东西，就是改不了。
  5. 直接在 CI 上试配置。本地跑一遍脚本，比推一次 CI 快十倍。
自测三问（点开对答案） 1. 官方 Action 和直接调 CLI 的根本差别是什么？ —— 可控性。官方只暴露它给的参数，省事但黑盒；CLI 参数全摊开，每一步都能插东西，但要自己管版本。 2. 审查任务需要哪三种权限？不能要哪个？ —— 读代码、写 PR 评论，这两个必须；不能给写代码的权限——给了它就能自己改，审查结论就不独立了。 3. 为什么两份配置的顶层键一样多？ —— 因为工作流的骨架由平台定死，不由写法定。差别全在步骤里。

单步审查会写了，下一节把它放进一条多阶段流水线：前面倒了，后面还跑不跑。

相关笔记