AI Agent / 系统课时
处理结构化输入输出
处理结构化输入输出
当 Claude Code 要接入脚本、日志流水线或其他命令行工具时,最重要的是把“给模型的数据”和“给程序消费的数据”分开。本节用非交互模式、JSON、JSON Schema 与 stream-json 建立可被脚本稳定解析的输入输出边界。
学习目标
- 使用
-p从标准输入接收数据,并用 JSON 获取可解析的结果与会话信息 - 使用
--json-schema把模型结果约束为下游程序需要的字段 - 使用
stream-json逐行消费实时事件,而不是等待完整响应结束
选择合适的数据边界
claude -p 会在非交互模式中处理一次请求并退出,因此很适合 Unix 管道。普通日志、diff 或命令输出可以直接走标准输入;输出端则按消费者选择 text、json 或 stream-json。其中 stream-json 是按行分隔的 JSON 事件流,整段 stdout 不能当作一个 JSON 文档解析。以下示例假定 claude 已可用并完成认证,同时系统已安装 jq。

用 JSON 包装一次性任务
下面把一条固定日志通过 stdin 交给 Claude Code,再让 jq 只保留脚本真正需要的 result 和 session_id。这样下游不必解析面向人的终端排版。
# stdin 负责输入日志,JSON 模式让下游只读取明确字段
printf '%s\n' 'ERROR db connection refused at 127.0.0.1:5432' \
| claude -p '分析标准输入中的日志,只说明最直接的失败原因,不要修改文件。' --output-format json \
| jq -c '{result,session_id}'预期输出:
{"result":"<VALUE>","session_id":"<ID>"}<VALUE> 是模型生成的分析文本,<ID> 是本次会话标识,实际值每次可能不同。自动化脚本应明确提取需要的字段,不要依赖字段顺序,也不要把整个 JSON 对象直接当作最终业务数据。
用 JSON Schema 固定下游协议
如果下游程序需要固定字段,仅使用“请返回 JSON”仍然不够稳妥。可以把 JSON Schema 交给 --json-schema;Claude Code 完成任务后,会把符合该结构的结果放在响应的 structured_output 字段中。
# Schema 约束最终业务对象,避免下游解析自由文本
schema='{"type":"object","properties":{"category":{"type":"string"},"summary":{"type":"string"}},"required":["category","summary"],"additionalProperties":false}'
printf '%s\n' 'ERROR db connection refused at 127.0.0.1:5432' \
| claude -p '分析标准输入日志,给出错误类别和一句话摘要。' \
--output-format json \
--json-schema "$schema" \
| jq '.structured_output'预期输出:
{
"category": "<VALUE>",
"summary": "<VALUE>"
}这里的占位值会随模型判断变化,但字段集合由 Schema 固定。若消费者要进一步做告警分级,可以继续收紧 enum、数值范围或必填字段,而不是在 shell 中用正则从自然语言里“猜”答案。
用 stream-json 消费实时事件
需要在 Claude 工作过程中更新进度、记录事件或把结果转给长运行程序时,使用 --output-format stream-json。开启 --verbose 与 --include-partial-messages 后,stdout 会持续产生一行一个 JSON 对象的事件;最终仍会出现 result 类型的结束消息。
# 事件逐行到达;这里只保留最终 result 事件
claude -p '用一句话解释为什么连接拒绝通常表示目标端口没有可接受连接的服务。' \
--output-format stream-json \
--verbose \
--include-partial-messages \
| jq -c 'select(.type == "result") | {type,result,session_id}'预期输出:
{"type":"result","result":"<VALUE>","session_id":"<ID>"}如果需要边生成边显示文本,可以筛选 stream_event 中的文本增量;如果只关心最终结果,则像上例一样只接收 result。消费者最好忽略自己不认识的事件类型,而不是假定流中永远只有固定几种事件,这样更能适应后续增加的系统事件。
处理流式输入与自动化边界
CLI 还提供 --input-format stream-json,用于 print 模式下接收结构化流式输入。它更适合已经按 Claude Code 消息协议生产事件的程序;普通日志分析、diff 审查和单次脚本调用,直接使用 stdin 文本通常更简单。若需要双向长连接、回调和更细粒度的事件对象,优先考虑 Agent SDK,而不是在 shell 中手写复杂协议。
一次性脚本优先选择 --output-format json,需要严格业务对象时叠加 --json-schema,需要实时反馈时再使用 stream-json。把这三种模式区分清楚,就能让 Claude Code 像普通命令行组件一样嵌入日志处理、检查脚本和自动化流水线,而不是让后续程序去解析不可预测的对话文本。