diff --git a/README.md b/README.md index 1a1f7b8..07533f6 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,34 @@ # AI Setup -Набор shell-лаунчеров для локальной установки и запуска нескольких AI coding CLI из единой точки входа. +Набор shell-скриптов для установки AI coding CLI и настройки сети с Amnezia VPN. -Точка входа — `setup.sh` (мастер-скрипт с меню). Он вызывает нужный скрипт из `scripts/`. -`scripts/ai-setup.sh` настраивает пользовательские директории, устанавливает глобальные правила агентов из `GLOBAL_RULES.md`, разворачивает кастомные скиллы и полностью перегенерирует standalone-скрипты в `~/.local/bin`. +Точка входа - `setup.sh` (мастер-скрипт с меню). Он вызывает нужный скрипт из `scripts/`. -## Что реально устанавливается и генерируется - -`scripts/ai-setup.sh` работает с такими путями: - -- `~/.local/bin` - standalone-лаунчеры и вспомогательные скрипты. -- `~/.config/ai-setup` - сохранённые ключи и глобальные правила. -- `~/.npm-global` - пользовательский npm prefix. -- `~/.claude/skills/` - кастомные скиллы для Claude Code. -- `~/.gemini/config/plugins/local-setup/skills/` - те же скиллы для Gemini/agy. - -После запуска генерируются или обновляются: - -- `~/.local/bin/ai-claude` -- `~/.local/bin/ai-gpt` -- `~/.local/bin/ai-deepseek` -- `~/.local/bin/ai-kimi` -- `~/.local/bin/ai-openrouter` -- `~/.local/bin/ai-gemini` -- `~/.local/bin/ai-api-helpers.sh` -- `~/.local/bin/claude-gpt-effort-proxy.py` - -Все генерируемые standalone-скрипты полностью перезаписываются текущей эталонной версией из `scripts/ai-setup.sh`. Старое содержимое не сливается и не дописывается. - -## Структура конфигов - -Все конфиги, которые разворачиваются в домашнюю директорию, живут в папке `home-configs/`: +## Структура репозитория ``` +setup.sh # мастер-скрипт с меню +scripts/ +├── ai-setup.sh # устанавливает AI-инструменты в ~/.local/bin +├── ru-bypass.sh # .ru трафик напрямую, kill switch для остального +├── ks-off.sh # временно отключить kill switch +└── ks-on.sh # восстановить kill switch home-configs/ ├── GLOBAL_RULES.md # глобальные правила для всех агентов ├── claude/ │ └── skills/ # кастомные скиллы для Claude Code (и Gemini) -│ ├── el-review/ -│ │ └── SKILL.md -│ └── el-review-heavy/ -│ └── SKILL.md ├── network/ -│ └── README.md # документация по сетевой настройке +│ └── README.md # подробная документация по сетевой настройке ├── vless/ │ └── servers.conf # список VLESS-серверов для прокси -├── proxychains/ -│ └── proxychains-xray.conf # конфиг proxychains (SOCKS5 через xray) -└── xray/ # (зарезервировано под будущие xray-конфиги) +└── proxychains/ + └── proxychains-xray.conf # конфиг proxychains (SOCKS5 через xray) +tests/ +├── test_fixes.sh # юнит-тесты структуры ai-setup.sh +└── test_network.sh # тесты маршрутизации +test_isolated.sh # проверка автоустановки ai-gpt и ai-kimi ``` -При запуске `scripts/ai-setup.sh`: -- `GLOBAL_RULES.md` копируется в `~/.config/ai-setup/global_rules.md` и рассылается в нативные rule-файлы (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.kimi-code/AGENTS.md`, `~/.gemini/GEMINI.md`). -- Скиллы из `home-configs/claude/skills/` копируются и в `~/.claude/skills/`, и в `~/.gemini/config/plugins/local-setup/skills/`. Для Gemini также генерируется `plugin.json`, чтобы `agy` распознал плагин `local-setup`. - -Лаунчеры дополнительно обновляют native rule-файлы через helper `_build_ai_sys_prompt` при своём запуске. - -В native rule-файлы попадают только глобальные правила. Полный prompt с проектными `.md` используется в `ai-claude`, `ai-deepseek`, `ai-openrouter` и `ai-gemini`; `ai-gpt` и `ai-kimi` полагаются на native rule-файлы своих CLI. - -## VLESS / Xray (опционально) - -При запуске `scripts/ai-setup.sh` первым делом спрашивает, нужен ли режим VLESS-прокси: - -``` -Установить встроенный vless? [Y/n] -``` - -Если выбрать **Y** (по умолчанию): -- Читает список серверов из `home-configs/vless/servers.conf`. -- Реально проверяет каждый сервер: запускает `xray` с временным конфигом и тестирует curl'ом через SOCKS5. Работающие серверы помечаются зелёным, неработающие — красным. -- Пользователь выбирает сервер. -- Устанавливается Xray (`/usr/local/bin/xray`), генерируется конфиг (`/etc/xray/config.json`), создаётся и запускается systemd-сервис. -- Отключается IPv6 на уровне системы (VLESS с ним конфликтует). -- Устанавливается `proxychains-ng`. -- Firefox настраивается на SOCKS5 (`127.0.0.1:1080`) с remote DNS. -- Системный прокси (GNOME) настраивается для Chrome/Chromium. -- **Все лаунчеры оборачиваются в `proxychains4`** — трафик идёт через xray. - -Если выбрать **n** (direct-режим — или если ранее был включён VLESS, а теперь отключается): -- Останавливается и отключается systemd-сервис xray. -- Системный прокси сбрасывается в `none`. -- Firefox переключается на прямой доступ. -- IPv6 восстанавливается. - ## Установка Запускать от обычного пользователя, не через `sudo`: @@ -91,13 +37,19 @@ home-configs/ bash setup.sh ``` -Мастер-скрипт предложит меню с выбором что запустить. Либо напрямую: +Мастер-скрипт показывает меню: -```bash -bash scripts/ai-setup.sh ``` +Шаги для новой машины: + 1) AI-инструменты + 2) Сеть: ru-bypass + kill switch -Скрипт прямо запрещает запуск от root. При этом, если Node.js не найден, он может попытаться установить Node.js через `apt-get` или `dnf` и тогда попросит `sudo` уже внутри этого шага. +Дополнительно (по необходимости): + 3) Отключить kill switch + 4) Включить kill switch + 5) Статус + 6) Проверить сеть +``` После установки, если shell ещё не видит новые команды: @@ -105,133 +57,159 @@ bash scripts/ai-setup.sh exec bash ``` -## Требования +## Сеть: ru-bypass + kill switch -- `bash` -- `curl` -- `python3` -- Node.js/npm для npm-глобальных инструментов -- (опционально) `proxychains-ng` — для VLESS-режима -- (опционально) `gsettings` — для автонастройки системного прокси +Полная документация: [`home-configs/network/README.md`](home-configs/network/README.md) -Если Node.js отсутствует, скрипт пытается поставить его автоматически для систем с `apt-get` или `dnf`. Для остальных систем Node.js нужно поставить вручную. +### Что это -## Команды +- **.ru сайты** (ozon.ru, госуслуги и др.) - идут **напрямую** через провайдера с российским IP +- **\*.loc офисные адреса** - тоже напрямую через локальный роутер +- **Всё остальное** - только через Amnezia VPN +- **Если Amnezia упала** - не-.ru трафик блокируется UFW (kill switch), .ru и *.loc продолжают работать -**На базе Claude Code:** +### Как работает -- `ai-claude` - запускает оригинальный Claude Code (Anthropic API). -- `ai-deepseek` - запускает Claude Code через DeepSeek Anthropic-compatible API. Проверяет и сохраняет DeepSeek API key. -- `ai-kimi` - запускает Claude Code через официальный Kimi Code API (`https://api.kimi.com/coding/`). Проверяет и сохраняет Kimi API key. -- `ai-openrouter` - запускает Claude Code через OpenRouter API (модели: GPT-5.5, Claude Opus 4.8, Claude Sonnet 4.6 и любые другие с OpenRouter). Проверяет и сохраняет OpenRouter API key. +Amnezia захватывает весь трафик двумя широкими маршрутами (`0.0.0.0/1` и `128.0.0.0/1` через `amn0`). +`ru-bypass.sh` добавляет тысячи более специфичных маршрутов для .ru IP-блоков через локальный роутер. +Ядро Linux выбирает самый специфичный маршрут - .ru идёт напрямую, остальное в amn0. -**Нативные CLI:** +UFW настроен так: +``` +default deny outgoing — запрещено всё по умолчанию +allow out on amn0 — через Amnezia можно всё +before.rules: ipset ru-direct — для .ru IP разрешён прямой выход +before.rules: RFC1918 — 10/8, 172.16/12, 192.168/16 тоже напрямую (*.loc) +``` -- `ai-gpt` - запускает нативный OpenAI Codex CLI. При отсутствии пытается поставить через `https://chatgpt.com/codex/install.sh` (fallback: npm). -- `ai-gemini` - запускает нативный Antigravity CLI `agy`. При отсутствии пытается поставить через `https://antigravity.google/cli/install.sh`. +### Первый запуск +Через меню (`bash setup.sh` → пункт 2) - он автоматически определит GATEWAY и DEV +из `ip route show default` и сохранит их в `~/.config/ai-setup/network_$(hostname).conf`. + +Или напрямую: + +```bash +sudo bash scripts/ru-bypass.sh +# для другой сети: +sudo GATEWAY=10.0.0.1 DEV=eth0 bash scripts/ru-bypass.sh +``` + +### Что устанавливается при первом запуске + +- `ipset` (если не установлен) +- Скрипт копируется в `/usr/local/bin/ru-bypass.sh` +- `ru-ipset-restore.service` - восстанавливает ipset из файла **до старта UFW** при загрузке +- `ru-bypass.service` - обновляет RIPE-список и маршруты после network-online +- NM dispatcher `/etc/NetworkManager/dispatcher.d/99-ru-bypass` - перезапускает скрипт при поднятии amn0 + +При каждом запуске: + +- Скачивает список .ru IP-блоков из RIPE (кэш 24ч, `/var/cache/ru-delegations.txt`) +- Обновляет ipset `ru-direct` (~11000 записей) +- Сохраняет ipset в `/etc/ipset.conf` для восстановления после ребута +- Добавляет маршруты через GATEWAY для всех .ru блоков и RFC1918 + +### ks-off / ks-on + +Для ситуаций когда нужен временный доступ без VPN (сайты, блокирующие нероссийский IP): + +```bash +# 1. Выйти из Claude Code +# 2. Отключить kill switch +sudo bash scripts/ks-off.sh +# 3. Отключить Amnezia в GUI + +# Возврат: +# 4. Подключить Amnezia в GUI (дождаться amn0) +sudo bash scripts/ks-on.sh +# 5. Войти в Claude Code +``` + +### Проверка + +```bash +ip route get 8.8.8.8 # -> dev amn0 (Google через VPN) +ip route get 77.88.8.8 # -> dev wlp1s0 (ya.ru напрямую) +ip route get 10.10.0.1 # -> dev wlp1s0 (*.loc напрямую) +bash tests/test_network.sh # полные тесты +``` + +## AI инструменты + +`scripts/ai-setup.sh` устанавливает и настраивает все AI CLI. + +После запуска генерируются или обновляются в `~/.local/bin`: + +- `ai-claude` - Claude Code (Anthropic API) +- `ai-gpt` - нативный OpenAI Codex CLI +- `ai-deepseek` - Claude Code через DeepSeek API +- `ai-kimi` - Claude Code через официальный Kimi Code API (`api.kimi.com/coding`) +- `ai-openrouter` - Claude Code через OpenRouter (GPT-5.5, Claude и др.) +- `ai-gemini` - нативный Antigravity CLI `agy` +- `ai-api-helpers.sh` - вспомогательные функции для лаунчеров +- `claude-gpt-effort-proxy.py` - прокси для маппинга effort-уровней (GPT backend) + +Все генерируемые скрипты полностью перезаписываются при каждом запуске `scripts/ai-setup.sh`. + +Также устанавливается: +- `~/.config/ai-setup/global_rules.md` и native rule-файлы (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.kimi-code/AGENTS.md`, `~/.gemini/GEMINI.md`) +- Скиллы из `home-configs/claude/skills/` в `~/.claude/skills/` и `~/.gemini/config/plugins/local-setup/skills/` + +## VLESS / Xray (опционально) + +При запуске `scripts/ai-setup.sh` спрашивает, нужен ли VLESS-прокси для AI API запросов. + +Если выбрать **Y**: +- Читает список серверов из `home-configs/vless/servers.conf` +- Проверяет каждый сервер реальным curl'ом через SOCKS5 +- Устанавливает Xray, генерирует конфиг, создаёт systemd сервис +- Все лаунчеры оборачиваются в `proxychains4` + +Если выбрать **n** - VLESS отключается, прокси и IPv6 сбрасываются в дефолт. ## Ключи и конфиги -- DeepSeek key хранится в `~/.config/ai-setup/deepseek_key` с правами `600`. -- Kimi key хранится в `~/.config/ai-setup/kimi_key` с правами `600`. -- OpenRouter key хранится в `~/.config/ai-setup/openrouter_key` с правами `600`. -- Исходник глобальных правил лежит в `home-configs/GLOBAL_RULES.md`. -- При запуске глобальные правила пишутся в `~/.config/ai-setup/global_rules.md`. - -При запуске `scripts/ai-setup.sh` сразу обновляются native rule-файлы: - -- `~/.codex/AGENTS.md` -- `~/.kimi-code/AGENTS.md` -- `~/.claude/CLAUDE.md` -- `~/.gemini/GEMINI.md` - -Лаунчеры дополнительно обновляют эти файлы через helper `_build_ai_sys_prompt` при своём запуске. +- `~/.config/ai-setup/deepseek_key` - DeepSeek API key (права 600) +- `~/.config/ai-setup/kimi_key` - Kimi API key (права 600) +- `~/.config/ai-setup/openrouter_key` - OpenRouter API key (права 600) +- `~/.config/ai-setup/global_rules.md` - глобальные правила агентов +- `~/.config/ai-setup/network_$(hostname).conf` - сохранённые GATEWAY/DEV для текущей машины ## Права запуска агентов -Лаунчеры запускают CLI в максимально свободном режиме: +- `ai-gpt` использует `--dangerously-bypass-approvals-and-sandbox` +- `ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-openrouter`, `ai-gemini` используют `--dangerously-skip-permissions` -- `ai-gpt` использует `--dangerously-bypass-approvals-and-sandbox`. -- `ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-openrouter` и `ai-gemini` используют `--dangerously-skip-permissions`. - -Это удобно для локального coding workflow, но это не sandbox для недоверенного кода. +Удобно для локального coding workflow, но это не sandbox для недоверенного кода. ## Правила агентов -Действуют правила Карпати как есть: английский блок из `GLOBAL_RULES.md` устанавливается в `~/.config/ai-setup/global_rules.md` без перевода и смысловых правок. +В `home-configs/GLOBAL_RULES.md` - правила Карпати (Think Before Coding, Simplicity First, +Surgical Changes, Goal-Driven Execution) плюс пользовательские правила (отвечать по-русски, +не коммитить без команды, не делать git add без команды и др.). -Кратко правила Карпати: - -1. Think Before Coding - не гадать, явно проговаривать допущения, варианты и неясности. -2. Simplicity First - писать минимальный код без speculative features и лишней конфигурируемости. -3. Surgical Changes - трогать только нужное, не рефакторить соседний код, чистить только свои следы. -4. Goal-Driven Execution - формулировать проверяемую цель и доводить работу до верификации. - -Пользовательские глобальные правила: - -1. Всегда отвечать по-русски, на "ты", дружелюбно и как живой программист. -2. Не выполнять `git commit` без прямой и однозначной просьбы. -3. Не выполнять `git add` без прямой просьбы, чтобы изменения оставались видны через обычный `git diff`. -4. Использовать обычный дефис `-`, не em dash. -5. В начале работы внимательно учитывать все проектные `.md` файлы. -6. При повторяющихся инструкциях предлагать reusable skill, но создавать или менять skill-файлы только после явного согласия. - -Правило этого проекта: - -1. При каждом запуске `ai-setup.sh` все генерируемые standalone-скрипты в `~/.local/bin` (`ai-gpt`, `ai-deepseek`, `ai-kimi`, `ai-openrouter`, `ai-gemini`, `ai-api-helpers.sh`, `ai-claude`) должны полностью перезаписываться актуальными версиями. Merge и append старого содержимого запрещены. +`scripts/ai-setup.sh` копирует их в native rule-файлы всех CLI. Лаунчеры обновляют их при каждом запуске. ## Effort Mapping -В репозитории есть `EFFORT_MAPPING.md` — документ с полной таблицей маппинга effort-уровней между провайдерами (Anthropic, GPT-5.5, DeepSeek V4, Kimi K2.6, Gemini 3.x). Описывает, во что превращается `low`/`medium`/`high`/`xhigh`/`max` у каждого провайдера и где именно выполняется маппинг. +`EFFORT_MAPPING.md` - таблица маппинга effort-уровней (`low`/`medium`/`high`/`xhigh`/`max`) +между провайдерами (Anthropic, GPT-5.5, DeepSeek V4, Kimi K2.6, Gemini 3.x). -Также скрипт генерирует `~/.local/bin/claude-gpt-effort-proxy.py` — легковесный прокси, который маппит `xhigh` → `high` для `claude-code-proxy` (GPT-бэкенд). Без него Claude Code не смог бы использовать `xhigh` effort с GPT. +`claude-gpt-effort-proxy.py` маппит `xhigh` → `high` для GPT-бэкенда (нет нативного `xhigh` у GPT). -## Сетевые скрипты (scripts/) +## Требования -Скрипты в `scripts/` **не запускаются автоматически** — ни `setup.sh`, ни системой. Это ручные утилиты, которые нужно запускать явно от root (или через `bash setup.sh`). - -Предназначены для окружения с Amnezia VPN и UFW kill switch (весь трафик через VPN, без VPN - только локалка). - -### ks-off.sh — временно отключить kill switch - -```bash -sudo bash scripts/ks-off.sh -``` - -Отключает UFW. После этого нужно вручную отключить Amnezia через её GUI - трафик пойдёт напрямую через провайдера (российский IP). Используется когда нужен доступ к сайтам, которые блокируют VPN (ozon.ru и т.п.). - -**Перед запуском:** выйди из Claude Code - сессия будет идти с другого IP. - -### ks-on.sh — восстановить kill switch - -```bash -sudo bash scripts/ks-on.sh -``` - -Включает UFW обратно. Перед запуском нужно подключить Amnezia через GUI - иначе скрипт предупредит, что интерфейс `amn0` не найден, и спросит подтверждение (без VPN весь интернет заблокируется). - -### Типичный workflow - -``` -# Нужен доступ к ru-сайтам напрямую: -1. Выйти из Claude Code -2. sudo bash scripts/ks-off.sh -3. Отключить Amnezia в GUI - -# Возврат к нормальному режиму: -4. Подключить Amnezia в GUI (дождаться amn0) -5. sudo bash scripts/ks-on.sh -6. Войти в Claude Code -``` +- `bash`, `curl`, `python3` +- Node.js/npm (для ai-gpt через Codex CLI и ai-gemini через agy) +- `ipset` (устанавливается автоматически при запуске ru-bypass.sh) +- (опционально) `proxychains-ng` - для VLESS-режима +- (опционально) `gsettings` - для автонастройки системного прокси GNOME ## Тесты -В репозитории есть shell-тесты: - ```bash -bash tests/test_fixes.sh -bash test_isolated.sh +bash tests/test_fixes.sh # структура ai-setup.sh и синтаксис bash +bash test_isolated.sh # автоустановка ai-gpt и ai-kimi через mock curl +bash tests/test_network.sh # маршрутизация (нужен активный ru-bypass) ``` - -`tests/test_fixes.sh` проверяет структуру `scripts/ai-setup.sh` и синтаксис bash. `test_isolated.sh` проверяет автоустановочные URL для `ai-gpt` и `ai-kimi` через mock `curl`.