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 條評論

登入 後參與評論

還沒有評論,來搶沙發~