Claude Code SDK #2：`--output-format` 三种模式全解——把 Claude 嵌进任何脚本的正确姿势

上一期我们拆解了 query() 函数——SDK 的 Python/TypeScript 程序化入口。

但很多场景下你并不想写代码，只是需要在 shell 脚本、CI 流水线或 Makefile 里调用一条 claude 命令，然后把输出管道给下一个工具。

这时你必须搞清楚 --output-format 的三种模式。选错了，你的脚本要么因为 ANSI 转义符乱码挂掉，要么因为格式不固定漏掉关键信息。

docs.anthropic.com

Claude Code SDK 文档

Anthropic 官方 Claude Code SDK 完整参考，涵盖 CLI 用法、API 接口、输出格式与会话管理

正在加载链接预览…

为什么 output-format 是自动化脚本的关键

claude 命令的默认输出是给「人眼看」的：带颜色、带进度状态、有交互提示。

一旦你把它放进管道：

claude --print "解释这个函数" | grep "返回值"

默认模式会把 ANSI 转义码一起塞进管道，grep 匹配失败，脚本静默出错，你花半小时 debug。

--output-format 就是为这个场景设计的。1

三种模式对比

模式	命令	输出内容	适用场景
`text`	`--output-format text`	纯文本，无颜色，无结构	管道进文本工具、写入文件
`json`	`--output-format json`	单条 JSON 对象，命令结束后输出	需要元数据（token 用量、stop reason）的场景
`stream-json`	`--output-format stream-json`	多行流式 JSON，每行一个事件对象	实时处理、长任务进度跟踪

`text` 模式：最简单的管道搭档

claude --print "用一句话解释什么是 context window" \
  --output-format text

输出就是裸文本，没有任何包装。直接可以：

# 写进文件
claude --print "写一个 Python 函数说明文档" \
  --output-format text > docstring.txt

# 管道给 wc 统计字数
claude --print "解释 transformer 架构" \
  --output-format text | wc -w

# 过滤关键行
claude --print "列出项目的5个主要风险" \
  --output-format text | grep "^[0-9]"

注意： 即使是 text 模式，也需要搭配 --print（或 -p）flag。没有 --print，claude 会启动交互式会话而不是直接运行后退出。

`json` 模式：拿到完整元数据

当你不只要回答，还要知道「花了多少 token」「为什么停止生成」时，用 json 模式。

result=$(claude --print "分析这段代码有什么潜在 bug" \
  --output-format json \
  < code.py)

# 提取回答文本
echo $result | python3 -c "import sys,json; print(json.load(sys.stdin)['result'])"

# 提取 token 用量
echo $result | python3 -c "
import sys, json
data = json.load(sys.stdin)
usage = data.get('usage', {})
print(f\"输入: {usage.get('input_tokens', 0)} tokens\")
print(f\"输出: {usage.get('output_tokens', 0)} tokens\")
"

json 模式输出的对象结构：

{
  "type": "result",
  "subtype": "success",
  "result": "这是 Claude 的回答正文...",
  "session_id": "sess_01abc...",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 342,
    "output_tokens": 156,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  },
  "is_error": false
}

stop_reason 有三个值需要重点处理：

end_turn：正常结束，Claude 主动停止生成
max_tokens：达到 token 上限被截断——你可能漏掉了后半段回答
stop_sequence：命中了你设置的停止序列

在自动化脚本里，检查 stop_reason 是判断「Claude 是不是给了完整回答」的唯一可靠手段。

docs.anthropic.com

Claude Code CLI 参数完整参考

claude 命令的全部 flag 说明，包括 --output-format、--print、--session-id、--max-turns 等参数的详细描述

正在加载链接预览…

`stream-json` 模式：逐事件实时处理

对于长任务（生成大型文件、多步分析），你需要知道进展，而不是等一个 JSON 在最后才出现。

claude --print "对这个仓库做全面的安全审计" \
  --output-format stream-json \
  < context.txt | while IFS= read -r line; do
    type=$(echo "$line" | python3 -c "import sys,json; print(json.load(sys.stdin).get('type',''))" 2>/dev/null)
    case "$type" in
      "assistant")
        # 有新的文本片段
        text=$(echo "$line" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for block in data.get('message', {}).get('content', []):
    if block.get('type') == 'text':
        print(block['text'], end='')
")
        printf "%s" "$text"
        ;;
      "result")
        echo ""
        echo "--- 完成 ---"
        ;;
      "system")
        # session_id 等元数据
        ;;
    esac
  done

stream-json 的事件流结构如下，每行是独立的 JSON 对象：

{"type":"system","subtype":"init","session_id":"sess_01...","tools":[...]}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"开始分析..."}]}}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"第一个风险是..."}]}}
...
{"type":"result","subtype":"success","result":"完整回答...","usage":{...}}

核心特点：

每一行都是完整的 JSON，可以独立解析，不需要等整个流结束
assistant 事件是流式到达的，可以实时渲染进度
最后的 result 事件包含汇总元数据（token 用量、session_id）

与 `--session-id` 结合：有状态的脚本

三种输出格式都支持通过 --session-id 传递已有会话 ID，实现多轮对话的自动化：

# 第一轮：建立上下文
session=$(claude --print "你是一个代码审查助手，专注于 Python 安全问题" \
  --output-format json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")

# 第二轮：基于上下文继续
claude --print "审查这个函数" \
  --session-id "$session" \
  --output-format json \
  < function.py

# 第三轮：追问
claude --print "上面的第2个问题能详细解释吗" \
  --session-id "$session" \
  --output-format text

json 和 stream-json 的输出里都包含 session_id 字段，可以直接提取后传入下一条命令，串成多步工作流。

四个实用组合模式

1. CI 代码审查机器人

#!/bin/bash
review=$(git diff HEAD~1 | claude --print "审查这次提交有什么问题" \
  --output-format json)

if echo "$review" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print('ok' if 'LGTM' in data.get('result','') else 'needs-review')
" | grep -q "needs-review"; then
  echo "::warning::Claude 发现潜在问题，请检查审查意见"
  echo "$review" | python3 -c "import sys,json; print(json.load(sys.stdin)['result'])"
fi

2. 批量文档生成

for file in src/**/*.py; do
  claude --print "为这个模块生成 README" \
    --output-format text \
    < "$file" > "docs/$(basename $file .py).md"
done

3. 流式输出写进日志

claude --print "分析这份错误日志的根本原因" \
  --output-format stream-json \
  < error.log | python3 -c "
import sys, json
for line in sys.stdin:
    data = json.loads(line)
    if data.get('type') == 'assistant':
        for block in data['message']['content']:
            if block['type'] == 'text':
                print(block['text'], end='', flush=True)
" | tee analysis.txt

4. 错误检测与重试

attempt=1
max_attempts=3

while [ $attempt -le $max_attempts ]; do
  result=$(claude --print "$prompt" --output-format json)
  stop=$(echo "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['stop_reason'])")

if [ "$stop" = "max_tokens" ]; then
    echo "回答被截断，尝试 $attempt/$max_attempts，增加上下文..."
    # 用 session_id 追问剩余部分
    session=$(echo "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
    result=$(claude --print "请继续上面未完成的回答" --session-id "$session" --output-format json)
  fi

if [ "$(echo "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['stop_reason'])")" = "end_turn" ]; then
    break
  fi
  attempt=$((attempt + 1))
done

总结：选哪种模式

写脚本、接管道、存文件 → text
需要 token 统计、stop reason 判断、session_id 提取 → json
长任务、需要实时进度、流式处理 → stream-json

三种模式覆盖了把 Claude Code 嵌进任何自动化工具链的所有场景。

code.claude.com

Claude Code 官方文档：SDK 集成指南

在脚本、CI/CD 管道和自动化工具中嵌入 Claude Code 的完整指南，包含 TypeScript 与 Python 代码示例

正在加载链接预览…

下一期我们继续拆解 --max-turns 参数——在让 Claude 自主运行多步工具调用时，如何精确控制它能走多远。

参考来源：

参考来源

1Claude Code SDK 官方文档

Claude Code SDK #2：--output-format 三种模式全解——把 Claude 嵌进任何脚本的正确姿势

Claude Code SDK #2：--output-format 三种模式全解——把 Claude 嵌进任何脚本的正确姿势

Claude Code SDK 文档

为什么 output-format 是自动化脚本的关键

三种模式对比

text 模式：最简单的管道搭档

json 模式：拿到完整元数据

Claude Code CLI 参数完整参考

stream-json 模式：逐事件实时处理

与 --session-id 结合：有状态的脚本

四个实用组合模式

1. CI 代码审查机器人

2. 批量文档生成

3. 流式输出写进日志

4. 错误检测与重试

总结：选哪种模式

Claude Code 官方文档：SDK 集成指南

参考来源

Claude Code SDK 文档

Claude Code CLI 参数完整参考

Claude Code 官方文档：SDK 集成指南

Claude Code SDK #2：`--output-format` 三种模式全解——把 Claude 嵌进任何脚本的正确姿势

`text` 模式：最简单的管道搭档

`json` 模式：拿到完整元数据

`stream-json` 模式：逐事件实时处理

与 `--session-id` 结合：有状态的脚本