第 10 章 · 02 输出格式与 jq 管道

第 10 章 · 02 输出格式与 jq 管道

本节摘要:打印模式的价值在于"输出可编程"。本节讲透三种输出格式(text/json/stream-json)与相关标志(--input-format、--include-partial-messages、--json-schema、--max-budget-usd),再给 8 个 jq 解析示例,最后落到三大工程场景:CI/CD 集成、脚本管道、JSON API 集成。学完本节,你能把 Claude Code 当"会思考的 API"接进任何自动化流水线。

学习目标

1. 说出三种输出格式的差异与选择依据。
2. 说出 --json-schema 与 --max-budget-usd 的用途。
3. 掌握 8 个 jq 解析模式:字段提取、过滤、多字段、CSV、条件、嵌套、统计、变形。
4. 说出 CI/CD 与批量处理场景的标准命令组合。

一、三种输出格式

打印模式下,输出由 --output-format 决定:

# 纯文本(默认)
claude -p "explain this code"

# JSON 供程序使用
claude -p --output-format json "list all functions in main.py"

# 事件流实时处理
claude -p --output-format stream-json "generate a long report"

# 流式事件需要额外参数时
claude -p --output-format stream-json --include-partial-messages "query"
​

配套标志一览:

二、结构化输出:--json-schema

问题场景:直接让模型"输出 JSON",常常得到格式不整、字段缺失的结果。--json-schema 用 Schema 约束输出结构,不合格就重试:

claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
  "find bugs in this code and return as JSON"
​

排障口诀:JSON 乱了 → 加 schema 约束结构 → 提示里写明字段含义 → 用 --output-format json(光在提示里说"给我 JSON"不算数)。

三、jq 解析八式

Claude 的 JSON 输出 + jq = 可编程 API。八个高频模式:

# ① 提取字段
claude -p --output-format json "analyze this code" | jq '.result'

# ② 过滤数组元素(只留高优先级)
claude -p --output-format json "list issues" | jq -r '.issues[] | select(.severity=="high")'

# ③ 提取多个字段
claude -p --output-format json "describe the project" | jq -r '.{name, version, description}'

# ④ 转 CSV
claude -p --output-format json "list functions" | jq -r '.functions[] | [.name, .lineCount] | @csv'

# ⑤ 条件判断(脚本分支用)
claude -p --output-format json "check security" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end'

# ⑥ 提取嵌套值
claude -p --output-format json "analyze performance" | jq '.metrics.cpu.usage'

# ⑦ 统计
claude -p --output-format json "find todos" | jq '.todos | length'

# ⑧ 变形输出
claude -p --output-format json "list improvements" | jq 'map({title: .title, priority: .priority})'
​

完整实战:把 JSON 结果接进脚本逻辑,实现"审查 → 判断 → 动作":

RESULT=$(claude -p --output-format json "is this code secure? answer with {secure: boolean, issues: []}" < code.py)
if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then
  echo "Security issues found!"
  echo "$RESULT" | jq '.issues[]'
fi
​

四、工程场景一:CI/CD 集成

GitHub Actions 自动代码审查

name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --output-format json \
            --max-turns 1 \
            "Review the changes in this PR for:
            - Security vulnerabilities
            - Performance issues
            - Code quality
            Output as JSON with 'issues' array" > review.json
​

无头 PR 审查门禁(v2.1.120+)

- name: Claude ultrareview
  run: claude ultrareview ${{ github.event.pull_request.number }} --json > review.json
​

claude ultrareview 干净通过退出 0、有发现退出 1——天然是 PR 门禁,--timeout 可覆盖默认 30 分钟。

CI 命令标准组合:claude -p --output-format json --max-turns N --max-budget-usd X——一次性、可解析、有上限。

五、工程场景二:脚本管道

管道输入 = 让 Claude 处理不落盘的数据:

# 日志分析
tail -1000 /var/log/app/error.log | claude -p "summarize these errors and suggest fixes"

# git 历史解读
git log --oneline -50 | claude -p "summarize recent development activity"

# 代码审查
cat src/auth.ts | claude -p "review this authentication code for security issues"

# TODO 汇总分级
grep -r "TODO" src/ | claude -p "prioritize these TODOs by importance"
​

批量处理(注意用 -p + 轻量模型控制成本):

# 逐文件处理
for file in src/*.ts; do
  echo "Processing $file..."
  claude -p --model haiku "summarize this file: $(cat $file)" >> summaries.md
done

# 批量生成测试
for module in $(ls src/modules/); do
  claude -p "generate unit tests for src/modules/$module" > "tests/$module.test.ts"
done
​

六、工程场景三:JSON API 集成

把 Claude 当"按次付费的智能端点":

# 结构化分析(带 schema 约束)
claude -p --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \
  "analyze main.py and return function list with complexity rating"

# 管道流转
claude -p --output-format json "list all API endpoints" | jq '.endpoints[]'
​

小结

• 格式三选一:人看用 text、程序解析用 json、实时流用 stream-json。
• 质量双保险:--json-schema 约束结构 + 提示里写清字段。
• jq 八式:提取/过滤/CSV/条件/嵌套/统计/变形,覆盖九成解析需求。
• 预算纪律:自动化必带 --max-budget-usd 与 --max-turns,防止失控花费。

下一节预告:最后一块拼图——--agents 配置、环境变量与故障排查。