走出终端：非交互模式与 CI

10.1 不坐在终端前也让它干活

前面九章都假设你在终端前面盯着。但有些任务天生不需要人盯：给三十个文件加类型注解、每天早上跑一遍依赖检查、在每个 PR 上自动做一轮 review。

这类场景要用非交互模式（也叫打印模式）：给一个提示，拿一个结果，不进入对话。

claude -p "总结 CHANGELOG.md 里最近三个版本的破坏性变更"

它可以接管道，也可以被管道接走：

git diff main...HEAD | claude -p "列出这次改动引入的公开 API 变化"

10.2 让输出可被程序消费

默认输出是给人看的文本。要接进脚本，用结构化输出：

claude -p "检查这个仓库有没有硬编码的密钥，列出文件和行号" \
  --output-format json

可选的格式有纯文本、JSON、以及流式 JSON（适合需要实时处理中间过程的场景）。

配合 jq 就能进流水线：

claude -p "列出所有缺少测试的导出函数" --output-format json \
  | jq -r '.result' > missing-tests.md

10.3 非交互模式的安全要点

这一节比技巧更重要。

非交互模式下不会弹出信任对话框。这意味着：如果你在一个没有信任过的目录里跑 claude -p，这个项目自带的钩子和 .mcp.json 里配置的服务器会被执行，而你不会看到任何确认提示。

对策是两条：

# 1. 用 --bare 得到可复现、不加载项目配置的运行
claude -p "..." --bare

# 2. 显式限定它能用的工具
claude -p "..." --allowedTools "Read,Grep,Edit"

再加一条：给它设上限，避免失控循环。

claude -p "..." --max-turns 15

10.4 批量任务：先在三个文件上试

批量改造是非交互模式最实用的场景。但直接对一百个文件开跑是新手最容易踩的坑——先在两三个文件上验证提示。

# 第一步：只在三个文件上试
head -3 files.txt | while read f; do
  claude -p "给 $f 里所有导出函数补 JSDoc 注释，不要改实现" \
    --allowedTools "Read,Edit" --max-turns 8
done

# 检查这三个的 diff，确认无误后再放开
git diff

确认没问题后，去掉 head -3，并且在一个干净的分支上跑，这样出问题时一条 git reset 就能回退。

10.5 接进 GitHub Actions

官方提供了现成的 Action。最快的接入方式是在会话里执行：

/install-github-app

它会引导你完成 GitHub App 安装和密钥配置。

手写工作流大概是这个形状：

name: Claude Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            审查这个 PR 的改动。只报告正确性问题和与描述不符的地方，
            不要提风格建议。每条问题指出文件和行号。

两种使用形态：

• 交互式：有人在 issue 或 PR 里 @claude 提及时触发；
• 自动化：满足条件（如 PR 打开）时按固定 prompt 执行。

几个需要知道的约束：触发者必须有写权限且不能是机器人账号；安装 GitHub App 时授予的是一组固定权限，GitHub 不允许只勾选其中一部分——所以这是一次需要团队知情的决策，而不是你一个人点两下的事。

10.6 再往前一步：Agent SDK

如果你要做的不是”在流水线里调用一次”，而是”把这套能力嵌进自己的产品”，那么下一站是官方的 Agent SDK（Python 和 TypeScript 都有）。它自带 Claude Code CLI，提供一次性查询和持续会话两种入口，也支持把你自己的函数注册成工具。

按本项目的约定，Python 侧用 uv 管理依赖：

uv add claude-agent-sdk

需要注意的是它由早先的 “Claude Code SDK” 改名而来，网上不少示例代码用的还是旧包名和旧接口，迁移时对照官方仓库的迁移说明。

10.7 常见坑

10.8 本章练习与检查点

你现在的成果：你的工作流里现在有了不需要你在场的部分。这也意味着，成本和安全这两件事从”可控”变成了”必须主动管理”——正是接下来两章的主题。