فرمت خروجی Claude Code: JSON و Stream

از claude -p --output-format با json، stream-json و text در اسکریپت‌ها و CI استفاده کنید: یک شیء JSON، رویدادهای NDJSON، --json-schema و دستورهای jq (2026).

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

آخرین بازبینی: 2026-10-20 · 📄 بر اساس مستندات رسمی (مرجع CLI مربوط به Claude Code و مستندات headless، بررسی‌شده در 2026-10-20)

claude -p --output-format json پس از پایان کار، یک شیء JSON واحد برمی‌گرداند؛ --output-format stream-json در حین اجرا رویدادهای JSON جداشده با خط جدید را برمی‌گرداند؛ text زمانی که فلگ را حذف کنید، مقدار پیش‌فرض است.

در اسکریپت‌ها، CI/CD و خطوط لوله خودکارسازی به چیزی بیشتر از یک پاسخ قابل‌خواندن برای انسان نیاز دارید — به داده ساخت‌یافته‌ای که یک برنامه بتواند تجزیه کند نیاز دارید. حالت headless در Claude Code (claude -p) سه فرمت خروجی از طریق --output-format ارائه می‌دهد و به شما امکان می‌دهد Claude Code را مانند هر ابزار CLI معمولی به یک خط لوله متصل کنید.

این یک قابلیت Claude Code است و به سرویسی که به آن متصل می‌شود وابسته نیست: چه Claude Code به API رسمی اشاره کند و چه به QCode، --output-format یکسان کار می‌کند. این صفحه بر فرمت‌های خروجی تمرکز دارد؛ برای مرجع کامل فلگ‌های headless و قالب‌های CI، خودکارسازی و CI/CD را ببینید.

1. سه فرمت در یک نگاه¶

# text is the default, so these two lines are equivalent
claude -p "Explain idempotence in one sentence"
claude -p "Explain idempotence in one sentence" --output-format text

2. text: متن ساده پیش‌فرض¶

بدون --output-format خروجی text است: stdout صرفاً پاسخ نهایی مدل است — مناسب برای خواندن مستقیم یا تغذیه یک pipe ساده.

# Read directly
claude -p "Rewrite this function to be async"

# Pipe to another tool
claude -p "Generate 5 candidate commit messages" | head -5

# Write to a file
claude -p "Write a short README intro for this repo" > intro.txt

محدودیت: text تنها «پاسخ» را به شما می‌دهد — بدون هزینه، مصرف توکن یا فراداده شناسه نشست، و وظایف چندمرحله‌ای از نتیجه نهایی قابل تفکیک نیستند. وقتی به این موارد نیاز دارید، به json یا stream-json تغییر دهید.

3. json: یک شیء ساختاریافته واحد¶

--output-format json یک شیء JSON را پس از پایان کار تولید می‌کند که شامل نتیجه نهایی به‌همراه مجموعه‌ای از فیلدهای فراداده است. این قالبی است که اسکریپت‌ها بیشترین استفاده را از آن می‌کنند.

claude -p "Count how many TODO comments are under src/" --output-format json

فیلدهای رایج در شیء بازگشتی (فیلدهای واقعی به خروجی نسخه شما بستگی دارد):

تجزیه با jq¶

قالب json برای jq بسیار مناسب است:

# Just the final answer
claude -p "Summarize this change in one sentence" --output-format json | jq -r '.result'

# Pull out the cost of this call
claude -p "Review auth.py" --output-format json | jq '.total_cost_usd'

# Grab several fields at once
claude -p "Analyze the architecture" --output-format json \
  | jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'

شرط‌گذاری بر اساس نتیجه و انباشت هزینه در یک اسکریپت¶

#!/usr/bin/env bash
set -euo pipefail

out=$(claude -p "Write unit tests for UserService" \
        --output-format json --max-turns 8)

result=$(echo "$out" | jq -r '.result')
cost=$(echo "$out"   | jq -r '.total_cost_usd')
sid=$(echo "$out"    | jq -r '.session_id')

echo "Result: $result"
echo "Cost this call: \$$cost"
echo "Session ID: $sid (resume with claude --resume $sid)"

خروجی ساختاریافته با --json-schema¶

گزینه --json-schema و یک تعریف JSON Schema را به --output-format json اضافه کنید تا پاسخ، نتیجه ساختاریافته را در فیلد structured_output در کنار فراداده مربوط به درخواست (شناسه نشست، مصرف و غیره) ارائه دهد. مثال زیر نام‌های توابع را به‌صورت آرایه‌ای از رشته‌ها استخراج می‌کند و فقط بخش ساختاریافته را با jq نگه می‌دارد:

claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

برای چاپ کل پاسخ، بخش | jq '.structured_output' را حذف کنید. اگر مقدار یک JSON Schema معتبر نباشد، claude با Error: --json-schema is not a valid JSON Schema خارج می‌شود و سپس پیام تشخیصی اعتبارسنج دنبال می‌آید.

نکته: json کل شیء را یک‌باره پس از پایان کار تولید می‌کند — هنگام اجرای یک کار طولانی هیچ خروجی‌ای وجود ندارد. برای مشاهده زنده پیشرفت، از stream-json در ادامه استفاده کنید.

4. stream-json: جریان رویداد بلادرنگ¶

--output-format stream-json اجرا را به رویدادهای JSON جداشده با خط جدید (NDJSON) می‌شکند؛ یک رویداد در هر خط که بی‌درنگ نوشته می‌شود. این قالب برای نمایش پیشرفت زنده در کارهای طولانی، رابط‌های کاربری جریانی، یا خط لوله‌هایی که خروجی را همان‌طور که تولید می‌شود مصرف می‌کنند مناسب است.

claude -p "Refactor the whole utils directory and add tests" \
  --output-format stream-json --max-turns 20

خروجی چیزی شبیه این است (هر خط JSON مستقل است؛ فیلدها به نسخه شما بستگی دارد):

{"type":"system","subtype":"init","session_id":"..."}
{"type":"assistant","message":{...}}
{"type":"assistant","message":{...}}
{"type":"result","result":"...","total_cost_usd":0.0123,"usage":{...}}

مصرف خط‌به‌خط¶

هر خط JSON معتبر است، بنابراین می‌توانید آن را همان‌طور که جریان می‌یابد پردازش کنید:

# Print the type of each event in real time
claude -p "Migrate to the new API" --output-format stream-json \
  | jq -r '.type'

# Pull result and cost only when the final event appears
claude -p "Migrate to the new API" --output-format stream-json \
  | jq -r 'select(.type == "result") | "\(.result)\nCost $\(.total_cost_usd)"'

# Process line by line with a while loop for live progress feedback
claude -p "Repository-wide code review" --output-format stream-json | \
while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    system) echo "▶ Starting…" ;;
    assistant) echo "… thinking" ;;
    result) echo "✓ Done: $(echo "$line" | jq -r '.result')" ;;
  esac
done

رویدادهای سطح توکن و زیرعامل¶

• --include-partial-messages: همراه با --output-format stream-json --verbose، توکن‌ها را همان‌طور که تولید می‌شوند دریافت می‌کنید؛ هر خط یک شیء JSON است که یک رویداد را نمایش می‌دهد.
• --include-hook-events: رویدادهای چرخه عمر هوک را در جریان خروجی بگنجانید (نیازمند --output-format stream-json است).
• --forward-subagent-text: متن زیرعامل را به جریان خروجی stream-json منتشر کنید (نیازمند --print و --output-format stream-json است؛ Claude Code v2.1.211 یا جدیدتر). بدون آن، متن یک زیرعامل پیش‌زمینه حذف می‌شود.
• --input-format stream-json: ورودی را در حالت print به‌صورت یک جریان JSON به‌جای prompt متنی دریافت کنید.

json در برابر stream-json: json منتظر پایان کار می‌ماند و یک شیء کامل به شما می‌دهد — تجزیه آن ساده است؛ stream-json در طول اجرا چندین رویداد را جریان می‌دهد، که بازخورد زنده را ممکن می‌کند اما تجزیه خط‌به‌خط را لازم دارد. در CI، برای نتیجه نهایی از json و برای گزارش‌های پیشرفت از stream-json استفاده کنید.

5. دستور‌های آماده CI / خط لوله¶

گرفتن نتیجه و ارسال نظر در GitHub Actions¶

- name: Claude review
  env:
    ANTHROPIC_BASE_URL: https://api.qcode.cc/api
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
  run: |
    out=$(claude -p "Review this PR's diff and list issues" \
            --output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
    echo "$out" | jq -r '.result' > review.md
    echo "This review cost \$$(echo "$out" | jq -r '.total_cost_usd')"

افزودن دروازه هزینه (شکست در صورت فراتر رفتن از بودجه)¶

out=$(claude -p "Generate release notes" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# Float comparison with awk: fail CI if over $0.50
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
  || { echo "Cost \$$cost over budget"; exit 1; }
echo "$out" | jq -r '.result'

جمع‌کردن هزینه در چندین فراخوانی¶

total=0
for f in src/*.py; do
  out=$(claude -p "Write docstrings for $f" --output-format json)
  c=$(echo "$out" | jq -r '.total_cost_usd')
  total=$(awk -v t="$total" -v c="$c" 'BEGIN{ printf "%.4f", t + c }')
done
echo "Total cost across all files: \$$total"

اشاره به QCode: دستورهای بالا برای API رسمی و QCode یکسان‌اند — فقط ANTHROPIC_BASE_URL را به https://api.qcode.cc/api تنظیم کنید (توجه: بدون اسلش انتهایی) و کلید cr_ خود را در ANTHROPIC_AUTH_TOKEN قرار دهید. کاربران چین می‌توانند از asia.qcode.cc استفاده کنند. نقاط پایانی و قالب‌های API را ببینید.

6. دام‌های رایج¶

• حالت json در طول کارهای طولانی بی‌صدا است: تنها یک بار و در پایان خروجی می‌دهد — ندیدن هیچ پیشرفتی طبیعی است؛ برای مشاهده پیشرفت از stream-json استفاده کنید.
• نمی‌توانید stream-json را به‌صورت یک توده واحد با jq پردازش کنید: خروجی NDJSON است؛ چند شیء یک سند JSON واحد نمی‌سازند. از jq خط‌به‌خط، jq -c یا --stream استفاده کنید — دستور jq '.' را روی کل جریان اجرا نکنید.
• --max-turns را فراموش نکنید: در خودکارسازی تعداد نوبت‌ها را محدود کنید تا یک وظیفه از کنترل خارج نشود و هزینه را نسوزاند.
• بدون اسلش انتهایی در BASE_URL: https://api.qcode.cc/api درست است؛ یک / اضافه مسیر نادرستی می‌سازد.
• فیلدهای فراداده بین نسخه‌ها متفاوت‌اند: به خروجی واقعی claude -p ... --output-format json روی سیستم خودتان اعتماد کنید — ابتدا jq 'keys' را اجرا کنید تا ببینید چه چیزی وجود دارد.

گام‌های بعدی¶

• خودکارسازی و CI/CD — مرجع کامل پرچم‌های حالت بدون رابط (headless) و دستورهای آماده CI/CD
• زیرعامل‌ها — به Claude Code بسپارید تا عامل‌های پس‌زمینه را به‌صورت موازی هماهنگ کند
• بهینه‌سازی هزینه — هزینه را با total_cost_usd مدیریت کنید
• نقاط پایانی و قالب‌های API — سه دامنه و مسیرهای پروتکل

وقتی Claude Code به خط لوله شما متصل شد، هزینه همان‌جا در خروجی موجود است — پلن‌ها و قیمت‌گذاری QCode را ببینید و سطحی را انتخاب کنید که با حجم خودکارسازی شما سازگار باشد.

سازمانی ←