f5c91adac8
- CLAUDE.md: add rule to never read images directly, only via Agent - CLAUDE.md: add rule to never use chrome-devtools take_screenshot directly - BUG_REPORT_CLAUDE_CODE_PNG_CRASH.md: full root cause analysis - tools/patch_claude_code.js: v2 patcher with mapper media_type fix Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
# CLAUDE.md
|
||
|
||
## Проект
|
||
|
||
ServerManager — **кроссплатформенное** Desktop GUI (CustomTkinter) для управления удалёнными серверами **любых типов**. Работает на **Windows и Linux**. Claude Code управляет серверами через скилл `/ssh`, зная только алиасы.
|
||
|
||
## КРИТИЧНО: Чтение изображений — ТОЛЬКО через Agent
|
||
|
||
**Claude Code CLI v2.1.70 баг:** Read tool крашит сессию на изображениях >150KB.
|
||
Большие изображения проходят через DP1-сжатие, где `data` и `media_type` теряются → API 400 → сессия мертва навсегда.
|
||
|
||
**ПРАВИЛА:**
|
||
- **НИКОГДА** не вызывать `Read` на .png/.jpg/.jpeg/.gif/.webp напрямую
|
||
- **НИКОГДА** не делать скриншоты через `mcp__chrome-devtools__take_screenshot` — результат тоже изображение, крашит так же
|
||
- **ВСЕГДА** читать изображения через `Agent` tool (субагент) — он упадёт изолированно, основная сессия выживет
|
||
- Маленькие (<150KB) работают, но **не рисковать** — всё через агента
|
||
- НЕ тестировать фиксы изображений в основном контексте даже после "исправления"
|
||
|
||
Подробности: `BUG_REPORT_CLAUDE_CODE_PNG_CRASH.md`
|
||
|
||
## КРОССПЛАТФОРМЕННОСТЬ — ОБЯЗАТЕЛЬНО
|
||
|
||
Приложение собирается и работает на **Windows** и **Linux**. При любых правках кода:
|
||
|
||
- **Никогда** не использовать хардкод Linux-путей (`/home`, `/tmp`, `/root`) без проверки `sys.platform`
|
||
- **Никогда** не вызывать Linux-only команды (`ps`, `xhost`, `xdpyinfo`, `xauth`) без `if sys.platform != "win32"`
|
||
- Пути строить через `os.path.join()` / `os.path.expanduser()`, **не** через строковую конкатенацию с `/`
|
||
- Subprocess-вызовы, специфичные для ОС — оборачивать в проверку платформы
|
||
- `os.scandir("/home")` → **сломает Windows** (`FileNotFoundError`). Такой код допустим только внутри `if sys.platform != "win32"`
|
||
- Тестировать билд на Windows (`python build.py`) после каждого изменения
|
||
|
||
## Поддерживаемые типы серверов
|
||
|
||
| Тип | Клиент | GUI-табы | CLI-команды |
|
||
|-----|--------|----------|-------------|
|
||
| ssh | `ssh_client.py` (Paramiko) | Terminal, Files, Info, Keys, 2FA, Setup | `ALIAS "cmd"`, `--upload`, `--download` |
|
||
| telnet | `telnet_client.py` (telnetlib3) | Terminal, Info, Setup | — |
|
||
| mariadb/mssql/postgresql | `sql_client.py` (pymysql/pymssql/psycopg2) | Query, Info, Setup | `--sql`, `--sql-databases`, `--sql-tables` |
|
||
| redis | `redis_client.py` (redis-py) | Console, Info, Setup | `--redis`, `--redis-info`, `--redis-keys` |
|
||
| grafana | `grafana_client.py` (requests) | Dashboards, Info, Setup | `--grafana-dashboards`, `--grafana-alerts` |
|
||
| prometheus | `prometheus_client.py` (requests) | Metrics, Info, Setup | `--prom-query`, `--prom-targets`, `--prom-alerts` |
|
||
| winrm | `winrm_client.py` (pywinrm) | PowerShell, Info, Setup | `--ps`, `--cmd` |
|
||
| s3 | `s3_client.py` (boto3) | Objects, Info, Setup | `--s3-buckets`, `--s3-ls`, `--s3-upload`, `--s3-download`, `--s3-delete`, `--s3-url` |
|
||
| rdp/vnc | `remote_desktop.py` | Launch, Info, Setup | — (запуск внешнего клиента) |
|
||
|
||
## БЕЗОПАСНОСТЬ
|
||
|
||
**Claude НИКОГДА не видит:** IP, логины, пароли, порты, TOTP-секреты. Всё в зашифрованном `servers.json`, скрипт `ssh.py` сам читает credentials.
|
||
|
||
**ЗАПРЕЩЕНО:** читать `~/.server-connections/` напрямую, использовать `--list-full`, добавлять credentials в контекст/логи.
|
||
|
||
## Команды разработки
|
||
|
||
```bash
|
||
python main.py # Запуск
|
||
python build.py # Сборка exe (auto-bump patch)
|
||
python build.py --no-bump # Сборка без бампа
|
||
python build.py --clean # Очистка + сборка
|
||
pip install -r requirements.txt # Зависимости
|
||
```
|
||
|
||
## Workflow — билд → тест → коммит → пуш
|
||
|
||
**ОБЯЗАТЕЛЬНО** после каждого изменения кода:
|
||
|
||
1. `python build.py` — собрать exe
|
||
2. Запустить exe из `releases/`, убедиться что GUI работает
|
||
3. Коммит + пуш:
|
||
```bash
|
||
git add <файлы> version.py releases/ServerManager-vX.Y.Z-win-x64.exe
|
||
git commit -m "vX.Y.Z: описание"
|
||
git push sensey master
|
||
```
|
||
|
||
Старые exe в `releases/` периодически чистить — оставлять первый + последние 5.
|
||
|
||
- Remote: `sensey`, ветка: `master`
|
||
|
||
## Версионирование
|
||
|
||
`build.py` автоинкрементирует patch в `version.py`. Semver: MAJOR (ломающие) | MINOR (фича) | PATCH (автобамп). Для minor/major — вручную изменить `version.py` перед `build.py --no-bump`.
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
core/ # Бизнес-логика
|
||
├── server_store.py # CRUD + encrypted JSON + observer + backups
|
||
├── encryption.py # Fernet
|
||
├── ssh_client.py # ShellSession + SFTPSession (Paramiko)
|
||
├── sql_client.py # MariaDB/MSSQL/PostgreSQL
|
||
├── redis_client.py # Redis (SCAN, авто-тип ключей)
|
||
├── grafana_client.py # Grafana REST API
|
||
├── prometheus_client.py # Prometheus REST API
|
||
├── telnet_client.py # Telnet (тот же интерфейс что ShellSession)
|
||
├── s3_client.py # S3/MinIO (boto3)
|
||
├── winrm_client.py # PowerShell/CMD через WinRM
|
||
├── remote_desktop.py # RDP/VNC (запуск внешнего клиента)
|
||
├── connection_factory.py # Фабрика: тип → клиент (lazy imports)
|
||
├── session_pool.py # LRU пул сессий (max 5)
|
||
├── status_checker.py # Фоновый мониторинг всех типов
|
||
├── i18n.py # EN/RU/ZH, ~300 ключей, t(key) API
|
||
├── claude_setup.py # Установщик интеграции Claude Code
|
||
├── totp.py # TOTP/2FA
|
||
└── logger.py # Rotating file logger
|
||
|
||
gui/
|
||
├── app.py # TAB_REGISTRY + TAB_CLASSES → условные табы по типу
|
||
├── sidebar.py # Список серверов + цветные бейджи типов
|
||
├── server_dialog.py # Адаптивная форма (поля по типу сервера)
|
||
├── tabs/
|
||
│ ├── terminal_tab.py # SSH + Telnet терминал (pyte)
|
||
│ ├── files_tab.py # SFTP файл-менеджер
|
||
│ ├── query_tab.py # SQL-редактор + Treeview + Export CSV
|
||
│ ├── redis_tab.py # Redis-консоль + история
|
||
│ ├── grafana_tab.py # Дашборды + алерты
|
||
│ ├── s3_tab.py # S3 браузер объектов
|
||
│ ├── prometheus_tab.py # PromQL + targets
|
||
│ ├── powershell_tab.py # PS/CMD (WinRM)
|
||
│ ├── launch_tab.py # RDP/VNC кнопка Connect
|
||
│ ├── info_tab.py # Инфо (адаптивные поля по типу)
|
||
│ ├── keys_tab.py, totp_tab.py, setup_tab.py
|
||
│ └── ...
|
||
└── widgets/ # TerminalWidget, StatusBadge, FileList
|
||
|
||
tools/
|
||
├── ssh.py # CLI для Claude Code (все типы серверов)
|
||
└── skill-ssh.md # Шаблон скилла /ssh
|
||
```
|
||
|
||
## Ключевые паттерны
|
||
|
||
- **Duck typing** — все клиенты реализуют `connect/disconnect/check_connection` по соглашению, без ABC
|
||
- **Lazy imports** — отсутствие pymysql/redis/etc не ломает приложение
|
||
- **TAB_REGISTRY** — `gui/app.py` перестраивает табы при смене типа сервера
|
||
- **Observer** — `ServerStore` → UI обновляется автоматически
|
||
- **Session pool** — SSH-сессии живут при переключении серверов
|
||
- **Auto-sudo** — детекция `[sudo] password for`, автоотправка пароля
|
||
- **Windows sanitize** — `ssh.py` автоматически транслирует Linux-команды (ls, cat, grep, ps, etc.) в Windows-эквиваленты (cmd.exe/PowerShell) при подключении к Windows SSH серверам. Pipe-цепочки и && корректно обрабатываются. Кодировка принудительно UTF-8 через `chcp 65001`
|
||
- **i18n** — все строки через `t(key)`, 3 языка
|
||
|
||
## Как пользоваться /ssh
|
||
|
||
```bash
|
||
# SSH
|
||
/ssh ALIAS "command" # Выполнить команду
|
||
/ssh ALIAS --upload local remote # SFTP upload
|
||
/ssh ALIAS --download remote local # SFTP download
|
||
# SQL
|
||
/ssh --sql ALIAS "SELECT * FROM t" # SQL-запрос
|
||
/ssh --sql-databases ALIAS # Список БД
|
||
/ssh --sql-tables ALIAS [db] # Список таблиц
|
||
# Redis
|
||
/ssh --redis ALIAS "GET key" # Redis-команда
|
||
/ssh --redis-info ALIAS # Redis INFO
|
||
/ssh --redis-keys ALIAS "pattern" # SCAN ключей
|
||
# S3 / MinIO
|
||
/ssh --s3-buckets ALIAS # Список бакетов
|
||
/ssh --s3-ls ALIAS bucket[/prefix] # Список объектов
|
||
/ssh --s3-upload ALIAS local bucket/key # Upload файла
|
||
/ssh --s3-download ALIAS bucket/key local # Download файла
|
||
/ssh --s3-delete ALIAS bucket/key # Удалить объект
|
||
/ssh --s3-url ALIAS bucket/key [SEC] # Presigned URL (по умолчанию 1 час)
|
||
# Grafana / Prometheus
|
||
/ssh --grafana-dashboards ALIAS # Дашборды
|
||
/ssh --prom-query ALIAS "up" # PromQL
|
||
/ssh --prom-targets ALIAS # Targets
|
||
# WinRM
|
||
/ssh --ps ALIAS "Get-Process" # PowerShell
|
||
/ssh --cmd ALIAS "dir" # CMD
|
||
# Общие
|
||
/ssh --list # Все серверы
|
||
/ssh --info ALIAS # Инфо (без creds)
|
||
/ssh --status # Online/offline
|
||
/ssh --add ALIAS IP PORT USER PASS # Добавить сервер
|
||
/ssh --remove ALIAS # Удалить сервер
|
||
/ssh --set-note ALIAS "desc" # Обновить заметки
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
- Серверы: `~/.server-connections/servers.json` (Fernet-encrypted)
|
||
- Настройки: `~/.server-connections/settings.json`
|
||
- Бэкапы: `~/.server-connections/backups/`
|
||
|
||
## Дополнительная документация
|
||
|
||
Читай **по необходимости**: `README.md`, `CHANGELOG.md`, `TERMINAL_AUDIT.md`, `plans/`, `tools/skill-ssh.md`.
|