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

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

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

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

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

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

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

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

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

### Anthropic (Claude)

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

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

### DeepSeek V4

```text
high -> max
```

- 2 реальных уровня.
- `low` и `medium` фактически поднимаются до `high`.
- `xhigh` фактически поднимается до `max`.
- Маппинг выполняется на стороне 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`.

### OpenRouter / GPT-5.5

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

`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 | На стороне сервера |
| OpenRouter/GPT-5.5 | Локального маппинга нет | `ai-openrouter` отправляет значение как есть |
| 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-openrouter`)
запоминает свой уровень effort отдельно. Логика гибридная:

- `low` / `medium` / `high` / `xhigh` живут нативно в `settings.json` лаунчера.
  `/effort` внутри сессии работает как обычно, уровень сохраняется между сессиями.
- `max` - единственный уровень, который Claude Code не сохраняет в `settings.json`
  (он session-only). Поэтому его восстанавливаем через `CLAUDE_CODE_EFFORT_LEVEL`.
  Текущий уровень, включая `max`, лаунчер записывает в `~/.cache/ai-setup/effort_<launcher>`.

Важное следствие только для `max`: когда восстановлена `max`-сессия, выставлена
`CLAUDE_CODE_EFFORT_LEVEL=max`, и `/effort` внутри нее не сменит уровень, потому что
env-переменная работает как жесткий override Claude Code.

Как выйти из `max` или форсить любой уровень:

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

Дефолты при пустом кеше: `xhigh` для `ai-claude`, `high` для остальных Claude Code лаунчеров.

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

- Для повседневной работы: `high` или `xhigh`.
- `max` effort имеет реальный эффект у Anthropic и DeepSeek; у Kimi это все тот же thinking on.
- `low`/`medium` у DeepSeek и Kimi фактически не снижают reasoning.
- Смена уровня на `low`..`xhigh`: обычным `/effort`; выход из `max`: через `AI_EFFORT=<lvl> ai-<launcher>`.