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

> **آخرین بازبینی**: 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](/docs/advanced/headless) را ببینید.

---

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

| فرمت | فلگ | شکل خروجی | کاربرد |
|------|------|---------|---------|
| متن ساده | `--output-format text` (پیش‌فرض) | یک بلوک متن ساده | خواندن انسانی، pipeهای ساده |
| 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` است: stdout صرفاً پاسخ نهایی مدل است — مناسب برای خواندن مستقیم یا تغذیه یک pipe ساده.

```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 تنها «پاسخ» را به شما می‌دهد — بدون هزینه، مصرف توکن یا فراداده شناسه نشست، و وظایف چندمرحله‌ای از نتیجه نهایی قابل تفکیک نیستند. وقتی به این موارد نیاز دارید، به `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` | مصرف توکن (ورودی / خروجی / کش و غیره) |
| `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
```

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

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

```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` قرار دهید. کاربران چین می‌توانند از `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) و سطحی را انتخاب کنید که با حجم خودکارسازی شما سازگار باشد.