Claude Code --json-schema 强制返回指定 JSON 结构怎么用:自动提取代码审计报告与结构化变更单

在无头模式(claude -p)下搭配 --output-format json 与 --json-schema,可让 Claude Code 完成工具调用后按严格 JSON Schema 输出结果至 structured_output 字段。本文附审计与变更单写法。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Pro 账号

结论先说

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

--json-schema 提取结构化报告四步流程

图:本站根据 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 最省心:

Schema 传参与报错排查对照

图:本站根据 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 时牢记四条工程实践细节:

  1. 所有必选字段都列进 required 数组:JSON Schema 默认允许属性缺省,只要没写进对应对象层级的 required 列表,模型在拿不准或偷懒时就可能直接省略该键,导致下游入库脚本报空指针;
  2. 分类与等级字段一律用 enum 锁死取值:例如把严重程度限定为 ["high", "medium", "low"],避免一次输出大写 "HIGH"、下一次又输出 "critical" 或中文 "高危";
  3. 善用 description 写明字段业务口径:在属性里加上简短的 "description": "相对于仓库根目录的文件路径",比把字段解释全堆在外部提示词里更不容易跑偏;
  4. 控制单次扫描范围与最大轮次:在大仓库跑自动提取时,建议配合 --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 官方文档:CLI reference — https://code.claude.com/docs/en/cli-reference
  • Claude Code 官方文档:Run Claude Code programmatically — https://code.claude.com/docs/en/headless

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~