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

> **آخر تحقق**: 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](/docs/advanced/headless).

---

## 1. الصيغ الثلاث في لمحة

| الصيغة | الخيار | شكل الإخراج | حالة الاستخدام |
|------|------|---------|---------|
| نص عادي | `--output-format text` (الافتراضي) | كتلة واحدة من نص عادي | قراءة الإنسان، أنابيب بسيطة |
| JSON | `--output-format json` | كائن JSON منظم **واحد** | تحليل السكربتات، وقراءة التكلفة/الاستخدام/معرّف الجلسة |
| JSON متدفق | `--output-format stream-json` | تدفق أحداث JSON **مفصول بأسطر جديدة** | التقدم المباشر، والاستهلاك خطوة بخطوة، والمهام الطويلة |

```bash
# 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`: المخرجات القياسية هي ببساطة إجابة النموذج النهائية — مناسبة للقراءة المباشرة أو للتغذية في أنبوب بسيط.

```bash
# 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 **واحدًا** **بعد** اكتمال المهمة، ويتضمن النتيجة النهائية مع مجموعة من حقول البيانات الوصفية. وهذا هو التنسيق الذي تستخدمه النصوص البرمجية أكثر من غيره.

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

الحقول الشائعة في الكائن المُعاد (تعتمد الحقول الفعلية على مخرجات إصدارك):

| الحقل | المعنى |
|------|------|
| `result` | نص الإجابة النهائية |
| `total_cost_usd` | تكلفة هذا الاستدعاء (USD) |
| `usage` | استخدام token (الإدخال / الإخراج / التخزين المؤقت، إلخ) |
| `session_id` | معرّف الجلسة، ويمكن استخدامه مع `--resume` للمتابعة |

### التحليل باستخدام jq

تنسيق `json` ملائم بطبيعته لـ [`jq`](https://jqlang.org/):

```bash
# 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}'
```

### التفرّع وتجميع التكلفة في نص برمجي

```bash
#!/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:

```bash
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)، حدث واحد في كل سطر، تُكتب فورًا. وهو مناسب للتقدم المباشر في المهام الطويلة، وواجهات المستخدم المتدفقة، وخطوط المعالجة التي تستهلك الإخراج أثناء إنتاجه.

```bash
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 صالح، لذا يمكنك معالجته أثناء تدفقه:

```bash
# 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)"'
```

```bash
# 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

```yaml
- 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')"
```

### إضافة بوابة تكلفة (الفشل عند تجاوز الميزانية)

```bash
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'
```

### تجميع التكلفة عبر عدة استدعاءات

```bash
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](/docs/getting-started/endpoints-and-api-paths).

---

## 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](/docs/advanced/headless) — المرجع الكامل لأعلام headless ووصفات CI/CD
- [الوكلاء الفرعيون](/docs/advanced/subagents) — اجعل Claude Code ينسّق وكلاء خلفيين على التوازي
- [تحسين التكلفة](/docs/usage/cost-optimization) — إدارة التكلفة عبر `total_cost_usd`
- [نقاط النهاية وصيغ API](/docs/getting-started/endpoints-and-api-paths) — النطاقات الثلاثة ومسارات البروتوكول

> بعد ربط Claude Code بخط الأنابيب لديك، تظهر التكلفة مباشرة في الإخراج — [اطّلع على خطط QCode وأسعارها](https://qcode.cc/pricing) واختر الفئة التي تناسب حجم الأتمتة لديك.