Claude Code --output-format json 與 stream-json 結構化輸出怎麼用:嵌進自動化腳本解析消息流

在無頭腳本模式(claude -p)下,--output-format 支持 text、json 與 stream-json 三種輸出格式。本文講清完整返回體字段、NDJSON 逐行事件流解析以及搭配 jq 與 Python 的自動化寫法。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 Pro 帳號

結論先說

  1. 僅限非交互打印模式生效:--output-format 必須配合 -p(或 --print)無頭模式使用,可選值為 text(預設純文本)、json 和 stream-json。
  2. 短任務等結果選 json:進程跑完後一次性輸出單個 JSON 對象,內含 result(最終回覆)、session_id、is_error、duration_ms 與費用統計,最適合用 jq 直接取值。
  3. 長任務盯進度選 stream-json:按換行符分隔(NDJSON)逐行實時吐出初始化、模型消息、工具調用與最終彙總事件;加上 --include-partial-messages 還能拿到逐字增量塊。
  4. 自動續聊靠 session_id 串聯:從首輪 json 輸出裏提取 session_id,下一條腳本命令用 claude -p -r "$SESSION_ID" 即可無縫繼承上下文。
  5. 腳本配額與開通入口:批量自動化腳本對 5 小時與周度配額消耗較快;國內開發者可通過本站 Claude Code 訂閱專頁 或 5 倍額度的 Claude Max 升級服務 開通,輕量腳本測試也可選免密兌換的 Claude Pro iOS 卡密。

三種無頭輸出格式對比

圖:本站根據 Claude Code 官方文檔:CLI reference 整理的示意圖

本文根據 Claude Code 官方文檔《CLI reference》與《Run Claude Code programmatically》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。

適用於誰

  • 想在 Shell、Python 或 CI 流水線裏調用 claude -p,並準確提取最終文本、session_id、耗時與費用的開發者;
  • 運行長任務時不想幹等幾分鐘黑盒輸出,需要實時監聽工具調用進度與增量文本流的人;
  • 分不清 json、stream-json 與 --include-partial-messages 搭配關係的人。

一、text、json 與 stream-json 三種格式怎麼選

在自動化腳本里直接抓預設 text 純文本有兩個痛點:一是拿不到本次運行的會話 ID 和耗時帳單,二是長任務執行期間你不知道它是正在讀文件還是卡住了。官方提供的三種格式分工如下:

格式參數輸出形態寫出時機典型下游消費方式
text(預設)人類可讀純文本全部執行完畢後一次性打印簡單管道重定向生成 .md 或終端直看
json單個標準 JSON 對象全部執行完畢後一次性打印用 jq -r '.result' 取答案或取 session_id
stream-json每行一個 JSON(NDJSON)每發生一次消息或工具動作實時刷出一行Python / Node 逐行流式讀取做進度條或日誌審計

如果你只需要讓模型嚴格按你給定的業務字段(如漏洞數組)返回 JSON,還應疊加 --json-schema;若想了解完整 CI 流水線接入,見 Claude Code 在 CI 裏無頭運行示例。

二、--output-format json 實戰:提取結果與串聯多輪會話

最穩妥的 Shell 批處理模式是先跑一輪 json 拿到結果和 session_id,需要追問時再按 ID 續跑:

bash
resp=$(claude -p "統計 src 目錄下未捕獲異常的異步函數" --output-format json)

# 提取模型最終文本回答與會話 ID
echo "$resp" | jq -r '.result'
sid=$(echo "$resp" | jq -r '.session_id')

# 基於同一上下文繼續下一輪動作
claude -p -r "$sid" "給剛才列出的第一個函數補上 try/catch" --output-format json

返回的單體 JSON 中,最常用於監控告警的四個頂層字段是:

  • is_error:布爾值,腳本可據此判斷本輪調用是否異常終止;
  • result:最終彙總文本字符串;
  • session_id:當前會話唯一標識,後續恢復歷史用法可參考 Claude Code 查看與恢復歷史會話;
  • total_cost_usd 與 duration_ms:便於記錄單次構建任務的耗時與成本帳單。
自動化腳本配額與帳號提示:在本地批處理或定時巡檢腳本里循環調用 claude -p 時,很容易在半小時內觸及普通 Pro 帳號的滾動窗口上限。日常自動化負載較高的開發者建議直接配置 Claude Max 會員升級 或在 Claude Pro 自助充值頁 提前備好訂閱,防止流水線跑到一半因限額中斷。

三、--output-format stream-json 實戰:逐行解析實時事件流

當單個重構或代碼掃描任務要跑三五分鐘時,stream-json 會按事件順序逐行輸出 NDJSON(注意新版本通常需同時傳入 --verbose):

stream-json 實時事件流消費步驟

圖:本站根據 Claude Code 官方文檔:Run Claude Code programmatically 整理的示意圖

bash
claude -p "檢查當前分支改動並運行相關單測" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages | while IFS= read -r line; do
    etype=$(echo "$line" | jq -r '.type // empty')
    echo "[事件類型] $etype"
done

逐行事件流主要包含四類記錄:

  1. system(subtype: "init"):第一行刷出,帶出當前工作目錄、已加載工具列表、模型名稱與 session_id;
  2. assistant:模型發出的推理文本塊或發起的 tool_use(如準備讀取哪個文件、執行哪條 Bash);
  3. user:工具執行完畢回傳給模型的 tool_result;
  4. result:最後一行收尾事件,結構與單體 json 模式一致,代表整輪執行閉環。

如果你是在自定義前端面板裏做打字機效果,加上 --include-partial-messages 即可收到細粒度的增量片段;若業務已經升級到用代碼庫直接編排智能體,也可以對比 Claude Agent SDK 流式輸出與權限控制。平時想手動導出交互歷史裏的 .jsonl 文件結構做對比,見 Claude Code 導出會話與 .jsonl 記錄說明。

常見問題

問:為什麼直接敲 claude --output-format json 不帶 -p 沒有輸出 JSON?

答:因為 --output-format 只對非交互打印模式生效。不加 -p 會進入全屏交互終端(TUI),該標誌會被忽略或報錯提示需搭配 --print。

問:用 Python subprocess 讀 stream-json 為什麼半天收不到一行?

答:排查兩點:一是確認按命令行提示帶上了 --verbose;二是在 Python 讀取子進程標準輸出時開啟按行緩衝(bufsize=1, text=True),並用 for line in proc.stdout: 逐行迭代而不是 proc.communicate() 阻塞等待。

問:管道里跑自動化怎麼避免卡在「是否允許修改文件」的交互確認?

答:無頭模式下沒有人工按鍵,若任務需要改文件或跑測試命令,必須通過 --allowedTools "Edit,Bash(npm test:*)" 顯式放行白名單工具,否則工具調用會被拒絕。

問:國內團隊沒有外幣卡,怎麼開通跑自動化所需的訂閱並開具報銷發票?

答:可通過本站 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 條評論

登入 後參與評論

還沒有評論,來搶沙發~