# Effort Mapping - соответствие уровней для Claude Code лаунчеров

## Как это работает

`/effort` и `AI_EFFORT` относятся к лаунчерам, которые запускают Claude Code:
`ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-glm`, `ai-openrouter`, `ai-opencode`.

Нативные лаунчеры `ai-gpt` (OpenAI Codex), `ai-gemini` (Antigravity `agy`) и `ai-cursor`
(Cursor CLI `agent`) не используют эту схему. У них свои настройки reasoning внутри
соответствующего CLI.

Документ отражает текущую реализацию `scripts/ai-setup.sh`.

## Таблица маппинга

| Claude Code `/effort` | Anthropic (`ai-claude`) | DeepSeek V4 (`ai-deepseek`) | Kimi K2.7/K2.6 (`ai-kimi`) | GLM 5.3 (`ai-glm`) | OpenRouter/GPT-5.5 (`ai-openrouter`) | OpenCode Go (`ai-opencode`) |
|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `low` | нативно `low` | нативно `low` | thinking on | нативно `low` | без локального маппинга | без локального маппинга |
| `medium` | нативно `medium` | провайдер поднимает до `high` | thinking on | провайдер опускает до `low` | без локального маппинга | без локального маппинга |
| `high` | нативно `high` | нативно `high` | thinking on | нативно `high` | без локального маппинга | без локального маппинга |
| `xhigh` | нативно `xhigh` | провайдер поднимает до `high` | thinking on | провайдер опускает до `high` | без локального маппинга | без локального маппинга |
| `max` | нативно `max` | нативно `max` | thinking on | нативно `max` | без локального маппинга | без локального маппинга |

Для OpenRouter текущий лаунчер не делает локального преобразования effort и отправляет
значение дальше через Claude Code/OpenRouter. Конкретная интерпретация зависит от выбранной
модели и backend-а OpenRouter.

Для OpenCode Go лаунчер работает через `routatic-proxy`, который транслирует Anthropic-запросы
в OpenAI/Gemini-формат для OpenCode Go API. Локального маппинга effort нет — thinking budget
не транслируется напрямую в OpenCode Go бекенд. Прокси и бекенд-модели выполняют reasoning
на своей стороне независимо от уровня effort.

## Нативные уровни каждого провайдера

### Anthropic (Claude)

```text
low -> medium -> high -> xhigh -> max
```

- 5 уровней, полное соответствие с Claude Code.
- Дефолт `ai-claude`: `xhigh`.
- `max` - максимальный бюджет thinking для самых сложных задач.

### DeepSeek V4

```text
low -> high -> max
```

- 3 реальных уровня.
- `low` остаётся `low` — реально снижает thinking бюджет.
- `medium` и `xhigh` фактически поднимаются до `high`.
- `max` остаётся `max` — максимальный бюджет thinking.
- Маппинг выполняется на стороне DeepSeek API.
- Дефолт `ai-deepseek`: `high`.

### Kimi K2.7/K2.6 (Moonshot AI)

```text
on / off
```

- Бинарный режим: thinking либо включен, либо выключен.
- Все уровни Claude Code effort в текущем лаунчере означают thinking on.
- Градаций глубины reasoning нет.
- Дефолт `ai-kimi`: `high`.

### GLM 5.3 (Zhipu AI)

```text
low -> high -> max
```

- 3 реальных уровня, thinking выключить нельзя (`thinking.type=disabled` тоже даёт reasoning).
- Anthropic-endpoint Z.ai читает `output_config.effort` от Claude Code и принимает все 5 уровней
  (невалидное значение -> HTTP 400 `reasoning_effort must be one of: none, minimal, low, medium, high, xhigh, max`).
- `medium` фактически опускается до `low`, `xhigh` - до `high`.
- Если effort не передан, Z.ai использует `max`. Поэтому `ai-glm` выставляет
  `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1` - иначе Claude Code не считает `glm-5.3` effort-capable
  и параметр не уходит.
- Маппинг выполняется на стороне Z.ai API, `ai-glm` локально effort не преобразует.
- Дефолт `ai-glm`: `xhigh` (= `high` у GLM), задаётся через CLI `--effort` при каждом запуске.
- Официально Z.ai маппинг `medium`/`xhigh` не документирует. Он выведен замером 2026-09-25:
  по 3 запроса на уровень, средний `output_tokens` на счётной задаче - `low` ~1.5K,
  `medium` ~1.1K, `high` ~3.4K, `xhigh` ~2.8K, `max` ~3.8K. `low`/`medium` уверенно короче
  остальных, а `high` и `max` на такой выборке пересекаются по разбросу.

### OpenRouter / GPT-5.5

Текущий `ai-openrouter` работает через Claude Code с `ANTHROPIC_BASE_URL=https://openrouter.ai/api`
и не вызывает локальный effort proxy. Поэтому `low`/`medium`/`high`/`xhigh`/`max` не
преобразуются в shell-лаунчере.

### OpenCode Go (routatic-proxy)

Текущий `ai-opencode` работает через Claude Code с локальным `routatic-proxy`
(`ANTHROPIC_BASE_URL=http://127.0.0.1:3456`), который транслирует запросы в OpenCode Go API.
Effort не преобразуется локально — thinking budget не имеет прямого эффекта на OpenCode Go бекенд.
Дефолт `ai-opencode`: `high`.

`claude-gpt-effort-proxy.py` все еще генерируется как совместимый helper для старого
`claude-code-proxy` backend-а. Если использовать его вручную, он маппит только
`xhigh` -> `high`, потому что `claude-code-proxy` принимает `low`, `medium`, `high`, `max`.

## Где выполняется маппинг

| Провайдер | Кто маппит | Файл/компонент |
|:---|:---|:---|
| Anthropic | Не нужен | - |
| DeepSeek V4 | DeepSeek API | На стороне сервера |
| Kimi K2.7/K2.6 | Moonshot API | На стороне сервера |
| GLM 5.3 | Z.ai API (`low,medium→low`, `high,xhigh→high`, `max`) | На стороне сервера |
| OpenRouter/GPT-5.5 | Локального маппинга нет | `ai-openrouter` отправляет значение как есть |
| OpenCode Go | Локального маппинга нет | `ai-opencode` отправляет значение через routatic-proxy |
| Legacy GPT proxy | helper-маппинг `xhigh` -> `high` | `~/bin/claude-gpt-effort-proxy.py` или `~/.local/bin/claude-gpt-effort-proxy.py` |

## Persistence effort между сессиями

Каждый Claude Code лаунчер (`ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-glm`, `ai-openrouter`, `ai-opencode`)
запоминает свой уровень effort отдельно в `settings.json` лаунчера.

`/effort` внутри сессии работает для всех уровней. `CLAUDE_CODE_EFFORT_LEVEL` не используется.

Форсировать уровень при запуске:

```bash
AI_EFFORT=max ai-deepseek    # включить max
AI_EFFORT=high ai-deepseek   # включить high
ai-deepseek                  # без флага - использовать уровень из settings.json
```

Дефолты: `xhigh` для `ai-claude` и `ai-glm`, `high` для остальных Claude Code лаунчеров.
`ai-glm` передаёт уровень через CLI `--effort`, поэтому каждый запуск стартует на `xhigh`
(или на `AI_EFFORT`), а `/effort` внутри сессии действует до её конца.

## Рекомендации

- Для повседневной работы: `high` или `xhigh`.
- `max` effort имеет реальный эффект у Anthropic, DeepSeek и GLM; у Kimi это всё тот же thinking on.
- `low`/`medium` у Kimi фактически не снижают reasoning; у DeepSeek `low` и у GLM `low`/`medium` дают реальный уровень `low` и экономят бюджет.
- У GLM осмысленно выбирать только `low`, `high` (или `xhigh`) и `max`.
- `ai-eltex`: корпоративный прокси Eltex (LiteLLM) игнорирует effort и thinking, GLM за ним
  думает всегда одинаково. `/effort` и `AI_EFFORT` там ни на что не влияют.