# Форматы вывода: json / text / stream-json

В скриптах, 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` (по умолчанию) | Один блок простого текста | Чтение человеком, простые пайпы |
| JSON | `--output-format json` | **Один** структурированный JSON-объект | Разбор в скриптах, чтение стоимости/расхода/ID сессии |
| Потоковый JSON | `--output-format stream-json` | Поток JSON-событий, **разделённых переводами строк** | Прогресс в реальном времени, пошаговое потребление, долгие задачи |

```bash
# text — это значение по умолчанию, поэтому две строки ниже эквивалентны
claude -p "Объясни идемпотентность одним предложением"
claude -p "Объясни идемпотентность одним предложением" --output-format text
```

---

## 2. text: простой текст по умолчанию

Без `--output-format` вы получаете `text`: stdout — это просто финальный ответ модели, удобно читать напрямую или передать в простой пайп.

```bash
# Читать напрямую
claude -p "Перепиши эту функцию в async-форме"

# Передать другому инструменту
claude -p "Сгенерируй 5 вариантов commit message" | head -5

# Записать в файл
claude -p "Напиши краткое введение в README для этого репозитория" > intro.txt
```

**Ограничение**: text даёт только «ответ» — без стоимости, расхода токенов и ID сессии, а в многошаговых задачах нельзя отделить промежуточный процесс от итога. Когда это нужно, переключайтесь на `json` или `stream-json`.

---

## 3. json: один структурированный объект

`--output-format json` выводит **один** JSON-объект **после** завершения задачи, содержащий финальный результат и набор полей метаданных. Это самый используемый в скриптах формат.

```bash
claude -p "Посчитай количество комментариев TODO в src/" --output-format json
```

Типичные поля возвращаемого объекта (фактические поля зависят от вывода вашей версии):

| Поле | Значение |
|------|------|
| `result` | Текст финального ответа |
| `total_cost_usd` | Стоимость этого вызова (USD) |
| `usage` | Расход токенов (вход / выход / кэш и т. д.) |
| `session_id` | ID сессии, можно использовать с `--resume` для продолжения |

### Разбор с помощью jq

Формат `json` идеально подходит для [`jq`](https://jqlang.org/):

```bash
# Только финальный ответ
claude -p "Опиши это изменение одним предложением" --output-format json | jq -r '.result'

# Извлечь стоимость этого вызова
claude -p "Проверь auth.py" --output-format json | jq '.total_cost_usd'

# Получить несколько полей сразу
claude -p "Проанализируй архитектуру" --output-format json \
  | jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'
```

### Ветвление и накопление стоимости в скрипте

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

out=$(claude -p "Напиши юнит-тесты для 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"
echo "Стоимость вызова: \$$cost"
echo "ID сессии: $sid (продолжить: claude --resume $sid)"
```

> **Совет**: `json` выдаёт весь объект разом по завершении задачи — во время долгой задачи вывода нет. Чтобы следить за прогрессом вживую, используйте `stream-json` ниже.

---

## 4. stream-json: поток событий в реальном времени

`--output-format stream-json` разбивает выполнение на **JSON-события, разделённые переводами строк** (NDJSON), по одному событию на строку, записывая их немедленно. Подходит для прогресса долгих задач в реальном времени, потоковых UI или конвейеров, потребляющих вывод по мере его появления.

```bash
claude -p "Отрефактори весь каталог utils и добавь тесты" \
  --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
# Печатать тип каждого события в реальном времени
claude -p "Мигрируй на новый API" --output-format stream-json \
  | jq -r '.type'

# Извлечь результат и стоимость только при появлении финального события
claude -p "Мигрируй на новый API" --output-format stream-json \
  | jq -r 'select(.type == "result") | "\(.result)\nСтоимость $\(.total_cost_usd)"'
```

```bash
# Обработка построчно в цикле while для живой обратной связи о прогрессе
claude -p "Ревью кода по всему репозиторию" --output-format stream-json | \
while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    system) echo "▶ Запуск…" ;;
    assistant) echo "… думаю" ;;
    result) echo "✓ Готово: $(echo "$line" | jq -r '.result')" ;;
  esac
done
```

> **`json` vs `stream-json`**: `json` ждёт завершения задачи и даёт **один** полный объект — разбирать просто; `stream-json` потоково выдаёт **множество** событий на протяжении всего выполнения, обеспечивая живую обратную связь, но требуя построчного разбора. В CI используйте `json` для финального результата и `stream-json` для логов прогресса.

---

## 5. Примеры для CI / конвейеров

### Получить результат и опубликовать комментарий в GitHub Actions

```yaml
- name: Ревью Claude
  env:
    ANTHROPIC_BASE_URL: https://api.qcode.cc/api
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
  run: |
    out=$(claude -p "Проверь diff этого PR и перечисли проблемы" \
            --output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
    echo "$out" | jq -r '.result' > review.md
    echo "Это ревью стоило \$$(echo "$out" | jq -r '.total_cost_usd')"
```

### Добавить контроль стоимости (падать при превышении бюджета)

```bash
out=$(claude -p "Сгенерируй заметки о релизе" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# Сравнение с плавающей точкой через awk: уронить CI, если больше $0.50
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
  || { echo "Стоимость \$$cost превысила бюджет"; exit 1; }
echo "$out" | jq -r '.result'
```

### Суммировать стоимость нескольких вызовов

```bash
total=0
for f in src/*.py; do
  out=$(claude -p "Напиши docstring для $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"
```

> **Указать на 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`.
- **Нельзя `jq` по `stream-json` целиком**: это 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) и выберите план под ваш объём автоматизации.