صيغة إخراج Claude Code: JSON والتدفق

استخدم claude -p --output-format مع json وstream-json وtext في السكربتات وCI: كائن JSON واحد، وأحداث NDJSON، و--json-schema، ووصفات jq (2026).

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

آخر تحقق: 2026-10-20 · 📄 وفق الوثائق الرسمية (مرجع Claude Code CLI ووثائق الوضع بلا واجهة، تم التحقق في 2026-10-20)

يُرجع claude -p --output-format json كائن JSON واحدًا بعد انتهاء المهمة؛ ويُرجع --output-format stream-json أحداث JSON مفصولة بأسطر جديدة أثناء تشغيلها؛ وtext هو الافتراضي عند حذف الخيار.

في السكربتات وخطوط CI/CD والأتمتة تحتاج إلى أكثر من إجابة يقرأها الإنسان — تحتاج إلى بيانات منظمة يستطيع البرنامج تحليلها. يوفّر الوضع بلا واجهة في Claude Code (claude -p) ثلاث صيغ إخراج عبر --output-format، ما يتيح لك ربط Claude Code بخط أنابيب مثل أي أداة CLI عادية.

هذه إمكانية في Claude Code ومستقلة عن الخدمة التي يتصل بها: سواء وجّهت Claude Code إلى API الرسمي أو إلى QCode، يعمل --output-format بالطريقة نفسها. تركّز هذه الصفحة على صيغ الإخراج؛ للاطلاع على المرجع الكامل لخيارات الوضع بلا واجهة وقوالب 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: المخرجات القياسية هي ببساطة إجابة النموذج النهائية — مناسبة للقراءة المباشرة أو للتغذية في أنبوب بسيط.

# 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 سوى «الإجابة» — بلا تكلفة أو استخدام token أو بيانات وصفية لمعرّف الجلسة، ولا يمكن تمييز المهام متعددة الخطوات من النتيجة النهائية. وعند حاجتك إلى ذلك، انتقل إلى 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

أحداث على مستوى token وأحداث الوكلاء الفرعيين¶

• --include-partial-messages: مع --output-format stream-json --verbose، استقبل tokens أثناء توليدها؛ كل سطر كائن JSON يمثّل حدثًا.
• --include-hook-events: ضمّن أحداث دورة حياة hook في تدفق الإخراج (يتطلب --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. يمكن لمستخدمي CN استخدام 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 وأسعارها واختر الفئة التي تناسب حجم الأتمتة لديك.

المؤسسات ←