结论先说
- 三参数固定组合:必须同时带上
-p、--output-format json与--json-schema '<Schema>'。 - 从
.structured_output取值:启用 Schema 后,校验通过的原生 JSON 对象存放在外层信封的structured_output字段,用jq '.structured_output'直接读取,无需二次反序列化字符串。 - 不阻碍中间工具调用:Schema 只约束最终交付格式,执行期间 Claude 仍可正常调用
Read、Grep与Bash。 - Schema 存独立文件最稳:把定义写进
.json文件再读入变量传参,可避开命令行引号转义错误。 - 开通与配额入口:自动化批量审计消耗配额集中;国内无外币卡用户可在 Claude Code 订阅专页 或免密兑换的 Claude Pro iOS 卡密 开通,高频流水线建议看 5 倍额度的 Claude Max 升级服务。

图:本站根据 Claude Code 官方文档:Run Claude Code programmatically 整理的示意图
本文根据 Claude Code 官方文档《CLI reference》与《Run Claude Code programmatically》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。
适用于谁
- 在脚本里让 Claude 审代码或出变更单,但总被 JSON 前后夹带的解释文字弄崩
jq解析的人; - 想保留 Claude Code 多步读文件、搜代码能力,仅在最后一步拿到严格类型化 JSON 的开发者;
- 在 PowerShell 或 Bash 里传 JSON Schema 字符串常遇到引号转义报错的人。
一、纯提示词求 JSON 与 --json-schema 的区别
只在提示词里写「只输出 JSON」时,模型仍可能包一层 Markdown 代码围栏或漏掉必填键。官方参数对比如下:
| 对比项 | 仅靠提示词求 JSON | 仅开 --output-format json | 叠加 --json-schema |
|---|---|---|---|
| 业务结果位置 | 自由文本无固定字段 | .result(仍是字符串) | .structured_output(原生对象) |
| 必填项与枚举保证 | 无,易拼错键名或漏键 | 无业务字段校验 | 严格按 Schema 校验类型与枚举 |
| 下游消费复杂度 | 需写正则剥离代码围栏 | 需二次 fromjson 解析 | jq '.structured_output' 直接用 |
结构化输出的通用 Schema 写法也可对比 Gemini 结构化输出 JSON Schema 指南。
二、实战一:提取代码安全审计报告(Bash 写法)
先将结构定义存为 audit-schema.json:
json
{
"type": "object",
"properties": {
"blocking": { "type": "boolean" },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"file": { "type": "string" },
"line": { "type": "integer" },
"severity": { "type": "string", "enum": ["high", "medium", "low"] }
},
"required": ["file", "line", "severity"]
}
}
},
"required": ["blocking", "issues"]
}
在脚本中读取文件并提取结构化结果:
bash
SCHEMA=$(jq -c . audit-schema.json)
claude -p "审查当前分支新增接口的鉴权与注入风险" \
--output-format json \
--json-schema "$SCHEMA" \
| jq '.structured_output' > report.json
CI 只需检查 jq -e '.blocking == false' report.json 即可判定门禁是否通过。完整流水线集成见 Claude Code 在 CI 里无头运行完整示例。
批量审计与订阅配额提示:每次带--json-schema扫描仓库时,模型仍需多轮读取文件并完成格式校验,密集跑批较易触及 Pro 档 5 小时限额。长期跑代码检查的开发者可在 Claude Pro 会员自助充值 或大额度的 Claude Max 订阅升级 中按需选型;订阅与 API 成本对比见 Claude Code 用 Pro、Max 还是 API 划算。
三、实战二:Windows PowerShell 生成发版变更单
PowerShell 下直接内联双引号极易被截断,用 Get-Content -Raw 最省心:

图:本站根据 Claude Code 官方文档:CLI reference 整理的示意图
powershell
$schema = Get-Content -Path .\changelog-schema.json -Raw
$res = claude -p "对比 main..HEAD 生成结构化变更单" --output-format json --json-schema $schema
($res | ConvertFrom-Json).structured_output | ConvertTo-Json -Depth 5
编写 Schema 时牢记四条工程实践细节:
- 所有必选字段都列进
required数组:JSON Schema 默认允许属性缺省,只要没写进对应对象层级的required列表,模型在拿不准或偷懒时就可能直接省略该键,导致下游入库脚本报空指针; - 分类与等级字段一律用
enum锁死取值:例如把严重程度限定为["high", "medium", "low"],避免一次输出大写"HIGH"、下一次又输出"critical"或中文"高危"; - 善用
description写明字段业务口径:在属性里加上简短的"description": "相对于仓库根目录的文件路径",比把字段解释全堆在外部提示词里更不容易跑偏; - 控制单次扫描范围与最大轮次:在大仓库跑自动提取时,建议配合
--max-turns与明确的git diff范围限制输入体积,既能防止中途超时拿不到最终结构化对象,也能大幅节省单次调用的 Token 开销。刚接触 CLI 基础命令的读者可先阅读 Claude Code 中文入门教程。
常见问题
问:为什么返回 JSON 里没有 structured_output 字段?
答:先核对是否漏了 --output-format json,再看返回里的 is_error 是否为 true(如触发 --max-turns 轮次上限提前中止,尚未走到最终输出步骤)。
问:提示 JSON Schema 无效怎么排查?
答:九成是命令行引号被 Shell 吞掉。先用 jq . schema.json 验证文件合法,再改为变量传参。
问:能不能一边改文件一边最后返回结构化变更清单?
答:可以,搭配 --allowedTools "Edit" 放行编辑权限后,它会先按要求改完业务源码文件,最后一步再严格按照你传入的 Schema 汇总输出本次改动涉及的文件路径、修改行数与风险说明列表。
问:国内没有外币信用卡,怎么开通订阅并开报销发票?
答:可通过本站 Claude Code 订阅专页 或 AI 会员充值总览 办理,支持支付宝、微信支付与 AlipayHK,提供免密卡密自助兑换,企业采购可开具国内增值税发票。实时价格与售后边界以页面展示为准:订阅期内非违规掉订阅按剩余天数折退,风控封号不在质保范围。
相关教程
- Claude Code 在 CI 里跑:从 claude -p 到自动审 PR
- Gemini 结构化输出怎么用:JSON Schema 示例
- Claude Code 用 Pro、Max 还是 API 划算
- Claude Code 中文入门教程
参考资料
- Claude Code 官方文档:CLI reference — https://code.claude.com/docs/en/cli-reference
- Claude Code 官方文档:Run Claude Code programmatically — https://code.claude.com/docs/en/headless
0 条评论
还没有评论,来抢沙发~