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

docs: актуализировать README — добавить ru-bypass, структуру scripts/, сетевой раздел

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
vitaly
2026-06-07 20:04:29 +03:00
parent b37482312f
commit 00722b430f
1 changed files with 152 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

326
README.md
View File

@@ -1,88 +1,34 @@
# AI Setup # AI Setup
Набор shell-лаунчеров для локальной установки и запуска нескольких AI coding CLI из единой точки входа. Набор shell-скриптов для установки AI coding CLI и настройки сети с Amnezia VPN.
Точка входа — `setup.sh` (мастер-скрипт с меню). Он вызывает нужный скрипт из `scripts/`. Точка входа - `setup.sh` (мастер-скрипт с меню). Он вызывает нужный скрипт из `scripts/`.
`scripts/ai-setup.sh` настраивает пользовательские директории, устанавливает глобальные правила агентов из `GLOBAL_RULES.md`, разворачивает кастомные скиллы и полностью перегенерирует standalone-скрипты в `~/.local/bin`.
## Что реально устанавливается и генерируется ## Структура репозитория
`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/ home-configs/
├── GLOBAL_RULES.md # глобальные правила для всех агентов ├── GLOBAL_RULES.md # глобальные правила для всех агентов
├── claude/ ├── claude/
│ └── skills/ # кастомные скиллы для Claude Code (и Gemini) │ └── skills/ # кастомные скиллы для Claude Code (и Gemini)
│ ├── el-review/
│ │ └── SKILL.md
│ └── el-review-heavy/
│ └── SKILL.md
├── network/ ├── network/
│ └── README.md # документация по сетевой настройке │ └── README.md # подробная документация по сетевой настройке
├── vless/ ├── vless/
│ └── servers.conf # список VLESS-серверов для прокси │ └── servers.conf # список VLESS-серверов для прокси
├── proxychains/ └── proxychains/
│ └── proxychains-xray.conf # конфиг proxychains (SOCKS5 через xray) └── proxychains-xray.conf # конфиг proxychains (SOCKS5 через xray)
└── xray/ # (зарезервировано под будущие 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`: Запускать от обычного пользователя, не через `sudo`:
@@ -91,13 +37,19 @@ home-configs/
bash setup.sh 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 ещё не видит новые команды: После установки, если shell ещё не видит новые команды:
@@ -105,133 +57,159 @@ bash scripts/ai-setup.sh
exec bash exec bash
``` ```
## Требования ## Сеть: ru-bypass + kill switch
- `bash` Полная документация: [`home-configs/network/README.md`](home-configs/network/README.md)
- `curl`
- `python3`
- Node.js/npm для npm-глобальных инструментов
- (опционально) `proxychains-ng` — для VLESS-режима
- (опционально) `gsettings` — для автонастройки системного прокси
Если 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). Amnezia захватывает весь трафик двумя широкими маршрутами (`0.0.0.0/1` и `128.0.0.0/1` через `amn0`).
- `ai-deepseek` - запускает Claude Code через DeepSeek Anthropic-compatible API. Проверяет и сохраняет DeepSeek API key. `ru-bypass.sh` добавляет тысячи более специфичных маршрутов для .ru IP-блоков через локальный роутер.
- `ai-kimi` - запускает Claude Code через официальный Kimi Code API (`https://api.kimi.com/coding/`). Проверяет и сохраняет Kimi API key. Ядро Linux выбирает самый специфичный маршрут - .ru идёт напрямую, остальное в amn0.
- `ai-openrouter` - запускает Claude Code через OpenRouter API (модели: GPT-5.5, Claude Opus 4.8, Claude Sonnet 4.6 и любые другие с OpenRouter). Проверяет и сохраняет OpenRouter API key.
**Нативные 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`. - `~/.config/ai-setup/deepseek_key` - DeepSeek API key (права 600)
- Kimi key хранится в `~/.config/ai-setup/kimi_key` с правами `600`. - `~/.config/ai-setup/kimi_key` - Kimi API key (права 600)
- OpenRouter key хранится в `~/.config/ai-setup/openrouter_key` с правами `600`. - `~/.config/ai-setup/openrouter_key` - OpenRouter API key (права 600)
- Исходник глобальных правил лежит в `home-configs/GLOBAL_RULES.md`. - `~/.config/ai-setup/global_rules.md` - глобальные правила агентов
- При запуске глобальные правила пишутся в `~/.config/ai-setup/global_rules.md`. - `~/.config/ai-setup/network_$(hostname).conf` - сохранённые GATEWAY/DEV для текущей машины
При запуске `scripts/ai-setup.sh` сразу обновляются native rule-файлы:
- `~/.codex/AGENTS.md`
- `~/.kimi-code/AGENTS.md`
- `~/.claude/CLAUDE.md`
- `~/.gemini/GEMINI.md`
Лаунчеры дополнительно обновляют эти файлы через helper `_build_ai_sys_prompt` при своём запуске.
## Права запуска агентов ## Права запуска агентов
Лаунчеры запускают 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`. Удобно для локального coding workflow, но это не sandbox для недоверенного кода.
- `ai-claude`, `ai-deepseek`, `ai-kimi`, `ai-openrouter` и `ai-gemini` используют `--dangerously-skip-permissions`.
Это удобно для локального 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 без команды и др.).
Кратко правила Карпати: `scripts/ai-setup.sh` копирует их в native rule-файлы всех CLI. Лаунчеры обновляют их при каждом запуске.
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 старого содержимого запрещены.
## Effort Mapping ## 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`). - `bash`, `curl`, `python3`
- Node.js/npm (для ai-gpt через Codex CLI и ai-gemini через agy)
Предназначены для окружения с Amnezia VPN и UFW kill switch (весь трафик через VPN, без VPN - только локалка). - `ipset` (устанавливается автоматически при запуске ru-bypass.sh)
- (опционально) `proxychains-ng` - для VLESS-режима
### ks-off.sh — временно отключить kill switch - (опционально) `gsettings` - для автонастройки системного прокси GNOME
```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
```
## Тесты ## Тесты
В репозитории есть shell-тесты:
```bash ```bash
bash tests/test_fixes.sh bash tests/test_fixes.sh # структура ai-setup.sh и синтаксис bash
bash test_isolated.sh 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`.