输入输出格式

输入输出格式

人用 Claude Code 聊天，机器用 Claude Code 对接——后者需要结构化的输入输出。这一页讲清楚三种输出格式、两种输入格式、JSON Schema 强约束，以及 headless 场景下怎么稳稳地把 Claude 嵌进流水线。

三种输出格式

--output-format 决定 Claude 怎么吐结果。

格式	像什么	用途
text	人话	默认，给人看的纯文本
json	表格	一次性结构化结果，含 cost/session_id 等元信息
stream-json	流水	流式逐条输出，每条事件一个 JSON 对象

# 默认 text，给人看
claude -p "解释这段代码"

# JSON，给脚本解析
claude -p "列出所有 TODO" --output-format json

# 流式 JSON，给实时处理
claude -p "重构这个模块" --output-format stream-json

JSON 响应结构

--output-format json 跑完会输出一个 JSON 对象，包含结果和元信息。

{
  "type": "result",
  "subtype": "success",
  "result": "这是 Claude 的最终回答文本",
  "session_id": "abc123def456",
  "cost_usd": 0.042,
  "duration_ms": 3200,
  "num_turns": 4,
  "is_error": false
}

常用字段：

字段	含义
result	最终回答文本
session_id	会话 ID，可用于后续 -r 接续
cost_usd	本次花费（美元）
duration_ms	耗时
num_turns	agentic 轮数
is_error	是否出错

用 jq 提取关键字段：claude -p "..." --output-format json | jq '.result'。

流式 JSON

--output-format stream-json 输出多个 JSON 对象，每行一个，对应一个事件：助手消息、工具调用、工具结果、最终结果。适合实时追踪进度或做 UI 渲染。

claude -p "修这个 Bug" --output-format stream-json | jq 'select(.type=="tool_use")'

每条事件的 type 字段标识种类（assistant、tool_use、tool_result、result 等），用 jq 过滤即可。

两种输入格式

格式	用途
text	默认，单次输入字符串
stream-json	多轮对话，按 JSON 流喂入

# 单次 text 输入
claude -p "解释这个函数" --input-format text

# 多轮 stream-json（适合编程式对话）
echo '{"type":"user","content":"你好"}' | claude -p --input-format stream-json --output-format stream-json

stream-json 输入配合 stream-json 输出，构成完整的「编程式多轮对话」通道——你可以在脚本里和 Claude 来回聊，每轮都是结构化消息。

–print / -p 是必需的

所有 headless 用法都必须带 -p / --print，否则会进入交互模式而不是跑完即退。

# ✅ 正确：带 -p
claude -p "做某事"

# ❌ 错误：没 -p，进交互模式了
claude "做某事"

–json-schema：结构化输出

需要 Claude 输出严格符合某个 schema 的 JSON？用 --json-schema。

claude -p "分析这个 PR 的风险点" \
  --json-schema '{
    "type": "object",
    "properties": {
      "risk_level": {"type": "string", "enum": ["low","medium","high"]},
      "issues": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["risk_level","issues"]
  }'

输出会被验证：符合 schema 才返回，不符合会重试或报错。这比「让模型随便吐 JSON 然后祈祷」可靠得多——适合做 CI 检查、自动分类、数据抽取。

流式与事件控制

几个 flag 让流式输出更精细。

Flag	作用
--include-partial-messages	在 stream-json 里包含部分消息（增量片段）
--include-hook-events	包含 hook 触发的事件，便于追踪 hooks 行为
--replay-user-messages	在输出里回显用户消息，便于对齐对话

# 调试 hooks 时看事件流
claude -p "跑测试" --output-format stream-json --include-hook-events | jq .

headless 最佳实践

把 Claude 嵌进脚本/CI 时，稳是第一要务。

1. 用 jq 解析

result=$(claude -p "列出所有 TODO" --output-format json | jq -r '.result')
echo "$result"

2. 错误处理

检查 is_error 字段，别假设一定成功。

json=$(claude -p "..." --output-format json)
if [ "$(echo "$json" | jq -r '.is_error')" = "true" ]; then
  echo "失败：$(echo "$json" | jq -r '.result')"
  exit 1
fi

3. 设 timeout

Claude 可能跑很久，加 timeout 防卡死。

timeout 300 claude -p "跑全量测试" --output-format json

4. 会话管理

长任务用 --name 起名，失败后用 -r 接续，别从头跑。

# 第一次跑
claude --name ci-build -p "构建并测试"

# 失败了接着跑
claude -r ci-build -p "继续上次的修复"

5. 限制失控

CI 里务必加护栏：--max-budget-usd 限钱、--max-turns 限轮数。

claude -p "修 Bug" \
  --max-budget-usd 5 \
  --max-turns 30 \
  --permission-mode dontAsk \
  --output-format json

常见组合配方

几套实战中常用的 flag 组合，直接抄。

# 1. CI 里做代码审查，输出结构化结论
claude -p "审查这个 diff 的风险" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"risk":{"type":"string"},"issues":{"type":"array","items":{"type":"string"}}}}' \
  --max-budget-usd 2

# 2. 流式监控长任务进度
claude -p "重构 src/legacy 模块" \
  --output-format stream-json \
  --include-partial-messages | jq 'select(.type=="tool_use")'

# 3. 多轮对话脚本（输入输出都用 stream-json）
echo '{"type":"user","content":"先列出所有 TODO"}' | \
  claude -p --input-format stream-json --output-format stream-json

# 4. 失败重试：失败就接续，不重头跑
claude --name ci-fix -p "修这个测试失败" || \
  claude -r ci-fix -p "换个思路继续修"

一句话总结

headless 场景下，Claude 不是聊天对象，是一个会吐 JSON 的函数。-p 是入口，--output-format json 是出口，--json-schema 是契约，jq 是管道，--max-budget-usd 是保险丝——把这五件配齐，Claude 就能稳稳嵌进你的流水线。

回去看 CLI Flags 速查 把所有相关 flag 复习一遍。🔌