vitaly.nikitenko/ai-setup
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync README/QUICK_START/EFFORT_MAPPING with current code

Browse Source 
- Update ai-openrouter models in ai-setup.sh output and header
- Fix effort persistence wording (statusbar -> launcher)
- Unify KS_EXCEPTIONS -> KILL_SWITCH_EXCEPTIONS in docs and setup.sh prompt
- Clarify menu item 7 only updates AI launchers
- Add IPv6 note after ks-off.sh
- Scope UFW before.rules insertion to *filter section

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
vitaly
2026-06-14 09:16:37 +03:00
parent 6c2844ce92
commit 38b5f2710c
8 changed files with 164 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
EFFORT_MAPPING.md
View File

@@ -1,116 +1,112 @@
# Effort Mapping — Соответствие уровней для всех провайдеров
# Effort Mapping - соответствие уровней для Claude Code лаунчеров
## Как это работает
Когда вы меняете effort в Claude Code (через `/effort` или `--effort`), значение передаётся
в API провайдера. Каждый провайдер поддерживает свой набор уровней reasoning effort.
Если выбранного уровня нет у провайдера — он автоматически маппится на ближайший
**более высокий** нативный уровень.
`/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`.
## Таблица маппинга
> Актуально на 12 июня 2026 г.
| 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 | без локального маппинга |
| Claude Code<br>`/effort` | Anthropic<br>(Claude) | GPT-5.5<br>(ChatGPT) | DeepSeek V4 | Kimi K2.7<br>(Moonshot) | Gemini 3.x |
|:---:|:---:|:---:|:---:|:---:|:---:|
| `low` | ✅ `low` | ✅ `low` | ⬆ `high` | 🔛 thinking on | ✅ `LOW` |
| `medium` | ✅ `medium` | ✅ `medium` | ⬆ `high` | 🔛 thinking on | ✅ `MEDIUM` |
| `high` | ✅ `high` | ✅ `high` | ✅ `high` | 🔛 thinking on | ✅ `HIGH` |
| `xhigh` | ✅ `xhigh` | ✅ `xhigh` | ⬆ `max` | 🔛 thinking on | ⬆ `HIGH` |
| `max` | ✅ `max` | ⬆ `xhigh` ¹ | ✅ `max` | 🔛 thinking on | ⬆ `HIGH` |
**Обозначения:**
- ✅ — нативная поддержка (1:1 соответствие)
- ⬆ — маппинг на ближайший доступный уровень вверх
- 🔛 — бинарный режим (thinking вкл/выкл, без градаций)
¹ GPT-5.5 не имеет уровня `max` — effort-proxy (`claude-gpt-effort-proxy.py`) маппит `max` → `xhigh`
Для OpenRouter текущий лаунчер не делает локального преобразования effort и отправляет
значение дальше через Claude Code/OpenRouter. Конкретная интерпретация зависит от выбранной
модели и backend-а OpenRouter.
## Нативные уровни каждого провайдера
### Anthropic (Claude) — эталон
```
low → medium → high → xhigh → max
```
- 5 уровней, полное соответствие с Claude Code
- По умолчанию: `xhigh`
- `max` — максимальный бюджет на thinking, для самых сложных задач
### Anthropic (Claude)
### GPT-5.5 (через claude-code-proxy)
```text
low -> medium -> high -> xhigh -> max
```
low → medium → high → xhigh
```
- 4 основных уровня (также существуют `none` и `minimal`)
- Нет `max` → маппится в `xhigh`
- По умолчанию: `medium`
- Маппинг выполняется effort-proxy на стороне лаунчера
- 5 уровней, полное соответствие с Claude Code.
- Дефолт `ai-claude`: `xhigh`.
- `max` - максимальный бюджет thinking для самых сложных задач.
### DeepSeek V4
```
high → max
```
- Всего 2 реальных уровня
- `low` и `medium` → автоматически поднимаются до `high`
- `xhigh` → автоматически поднимается до `max`
- Маппинг выполняется на стороне DeepSeek API
### Kimi K2.7 (Moonshot AI)
```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 либо включён, либо выключен
- Все уровни effort = thinking включён
- Нет градаций глубины reasoning
- Маппинг выполняется на стороне Moonshot API
### Gemini 3.x (через antigravity-claude-proxy)
```
MINIMAL → LOW → MEDIUM → HIGH
```
- 4 уровня
- Нет `xhigh` и `max` → оба маппятся в `HIGH`
- Pro-модели: по умолчанию `HIGH`
- Flash-модели: по умолчанию `MEDIUM`
- Маппинг выполняется на стороне antigravity-claude-proxy
- Бинарный режим: 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 | Не нужен | — |
| GPT-5.5 | effort-proxy (наш) | `~/.local/bin/claude-gpt-effort-proxy.py` |
| Anthropic | Не нужен | - |
| DeepSeek V4 | DeepSeek API | На стороне сервера |
| Kimi K2.7 | Moonshot API | На стороне сервера |
| Gemini 3.x | antigravity-claude-proxy | npm пакет |
| 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 между сессиями
Каждый лаунчер (`ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-openrouter`) запоминает свой
уровень effort отдельно. Логика гибридная:
Каждый Claude Code лаунчер (`ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-openrouter`)
запоминает свой уровень effort отдельно. Логика гибридная:
- **`low` / `medium` / `high` / `xhigh`** живут нативно в `settings.json` лаунчера.
- `low` / `medium` / `high` / `xhigh` живут нативно в `settings.json` лаунчера.
`/effort` внутри сессии работает как обычно, уровень сохраняется между сессиями.
- **`max`** — единственный, который Claude Code **не сохраняет** в `settings.json`
- `max` - единственный уровень, который Claude Code не сохраняет в `settings.json`
(он session-only). Поэтому его восстанавливаем через `CLAUDE_CODE_EFFORT_LEVEL`.
Текущий уровень (включая `max`) статусбар пишет в `~/.cache/ai-setup/effort_<launcher>`.
Текущий уровень, включая `max`, лаунчер записывает в `~/.cache/ai-setup/effort_<launcher>`.
**Важное следствие (только для `max`):** когда восстановлена `max`-сессия, выставлена
`CLAUDE_CODE_EFFORT_LEVEL=max`, и `/effort` внутри неё **не сменит** уровень
(env-переменная — жёсткий override Claude Code). На остальных уровнях `/effort` свободен.
Важное следствие только для `max`: когда восстановлена `max`-сессия, выставлена
`CLAUDE_CODE_EFFORT_LEVEL=max`, и `/effort` внутри нее не сменит уровень, потому что
env-переменная работает как жесткий override Claude Code.
**Как выйти из `max` (или форсить любой уровень):** перезапусти лаунчер с `AI_EFFORT`:
Как выйти из `max` или форсить любой уровень:
```bash
AI_EFFORT=max ai-deepseek # включить и запомнить max
AI_EFFORT=high ai-deepseek # вернуться на high (выйти из max)
ai-deepseek # без флага - восстанавливает последний уровень
AI_EFFORT=high ai-deepseek # вернуться на high
ai-deepseek # без флага - восстановить последний уровень
```
Дефолты при пустом кэше: `xhigh` для `ai-claude`, `high` для остальных.
Дефолты при пустом кеше: `xhigh` для `ai-claude`, `high` для остальных Claude Code лаунчеров.
## Рекомендации
- **Для повседневной работы:** `high` или `xhigh` — работает одинаково хорошо у всех провайдеров
- **`max` effort:** имеет реальный эффект только у **Anthropic** и **DeepSeek**. Для GPT маппится в `xhigh`, для Gemini и Kimi — в их максимальный уровень
- **`low`/`medium`:** у DeepSeek и Kimi фактически не снижают reasoning — DeepSeek поднимет до `high`, Kimi просто включит thinking
- **Смена уровня:** на `low..xhigh` обычным `/effort`; из `max` — через `AI_EFFORT=<lvl> ai-<launcher>` (в max-сессии `/effort` залочен env-переменной, см. «Persistence effort»)
- Для повседневной работы: `high` или `xhigh`.
- `max` effort имеет реальный эффект у Anthropic и DeepSeek; у Kimi это все тот же thinking on.
- `low`/`medium` у DeepSeek и Kimi фактически не снижают reasoning.
- Смена уровня на `low`..`xhigh`: обычным `/effort`; выход из `max`: через `AI_EFFORT=<lvl> ai-<launcher>`.