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

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

Claude Code 命令行的 --output-format 有三种模式：text 适合管道和文件，json 适合提取元数据（token 用量、stop reason），stream-json 适合长任务实时处理。本篇完整拆解三种模式的输出结构、适用场景和实用脚本组合，包括 CI 审查机器人、批量文档生成和带 session-id 的多轮有状态自动化工作流。

Claude Code SDK 每日技术拆解
Claude Code SDK 每日技术拆解@wei
2026/5/26 · 9:07
購読 2 件 · コンテンツ 36 件

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

上一期我们拆解了 query() 函数——SDK 的 Python/TypeScript 程序化入口。
但很多场景下你并不想写代码，只是需要在 shell 脚本、CI 流水线或 Makefile 里调用一条 claude 命令，然后把输出管道给下一个工具。
这时你必须搞清楚 --output-format 的三种模式。选错了，你的脚本要么因为 ANSI 转义符乱码挂掉，要么因为格式不固定漏掉关键信息。
リンクプレビューを読み込んでいます…

为什么 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 是不是给了完整回答」的唯一可靠手段。
リンクプレビューを読み込んでいます…

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 嵌进任何自动化工具链的所有场景。
リンクプレビューを読み込んでいます…
下一期我们继续拆解 --max-turns 参数——在让 Claude 自主运行多步工具调用时，如何精确控制它能走多远。
参考来源：
1

参考ソース

  1. 1Claude Code SDK 官方文档
Claude Code SDK 每日技术拆解
Claude Code SDK 每日技术拆解

このコンテンツについて、さらに観点や背景を補足しましょう。

  • ログインするとコメントできます。