410 lines
16 KiB
Markdown
410 lines
16 KiB
Markdown
# Развёртывание Codex Skill Для ServerManager
|
||
|
||
Этот документ описывает текущее состояние интеграции `ServerManager -> Codex`, автоматическое и ручное развёртывание, проверку и все известные edge cases.
|
||
|
||
Поддерживаемый deployment target для этой интеграции:
|
||
|
||
- Linux
|
||
- macOS
|
||
- Windows
|
||
|
||
## Что именно разворачивается
|
||
|
||
Интеграция для Codex состоит из трёх слоёв:
|
||
|
||
1. Общий локальный backend:
|
||
- `~/.server-connections/ssh.py`
|
||
- `~/.server-connections/encryption.py`
|
||
- `~/.server-connections/servers.json`
|
||
2. Codex skill package:
|
||
- `~/.codex/skills/server-manager/`
|
||
3. Безопасный wrapper для вызова backend из Codex:
|
||
- `~/.server-connections/codex-ssh` на Linux/macOS
|
||
- `~/.server-connections/codex-ssh.cmd` на Windows
|
||
|
||
В репозитории исходники skill лежат здесь:
|
||
|
||
- [SKILL.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/SKILL.md)
|
||
- [command-matrix.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/references/command-matrix.md)
|
||
- [project.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/references/project.md)
|
||
- [server-manager-doctor.sh](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/server-manager-doctor.sh)
|
||
- [server-manager-doctor.cmd](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/server-manager-doctor.cmd)
|
||
- [codex-ssh-wrapper.sh](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/codex-ssh-wrapper.sh)
|
||
- [codex-ssh-wrapper.cmd](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/codex-ssh-wrapper.cmd)
|
||
|
||
## Как это работает
|
||
|
||
Модель безопасности та же, что и у Claude integration:
|
||
|
||
```text
|
||
Codex skill -> ~/.server-connections/codex-ssh -> ~/.server-connections/ssh.py -> encrypted servers.json
|
||
```
|
||
|
||
Ключевая идея:
|
||
|
||
- Codex видит только алиасы и безопасные результаты команд.
|
||
- `ssh.py` сам читает credentials из локального зашифрованного хранилища.
|
||
- Codex не должен читать `servers.json`, `settings.json` или `encryption.py` напрямую.
|
||
|
||
## Что уже автоматизировано
|
||
|
||
Теперь Codex integration встроена в продуктовый setup flow:
|
||
|
||
- `core/claude_setup.py` ставит `ssh.py`, `encryption.py`, `~/.claude/commands/ssh.md`, `~/.codex/skills/server-manager/`, wrapper `~/.server-connections/codex-ssh` и блок в `~/.claude/CLAUDE.md`
|
||
- вкладка `Setup` в GUI показывает отдельные статусы для Claude skill, Codex skill и Codex wrapper
|
||
- `build.py` после сборки автоматически синхронизирует Claude- и Codex-артефакты в локальный runtime
|
||
|
||
Платформенный split такой:
|
||
|
||
- Linux/macOS: используются `codex-ssh-wrapper.sh` и `server-manager-doctor.sh`
|
||
- Windows: используются `codex-ssh-wrapper.cmd` и `server-manager-doctor.cmd`
|
||
|
||
Ручная установка всё ещё полезна как fallback path, если нужен точечный repair или offline debugging.
|
||
|
||
## Предварительные условия
|
||
|
||
Перед установкой Codex skill должны уже существовать или быть установлены через `Setup`:
|
||
|
||
1. `~/.server-connections/ssh.py`
|
||
2. `~/.server-connections/encryption.py`
|
||
3. `~/.server-connections/servers.json`
|
||
4. `codex` CLI
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
ls -la ~/.server-connections
|
||
codex --help
|
||
```
|
||
|
||
Если `~/.server-connections/ssh.py` отсутствует:
|
||
|
||
1. Открыть ServerManager GUI
|
||
2. Перейти в `Setup`
|
||
3. Нажать `Install Everything`
|
||
|
||
Это поставит backend, Claude skill и Codex skill целиком.
|
||
|
||
## Рекомендуемый путь: установка через GUI
|
||
|
||
1. Открыть ServerManager
|
||
2. Перейти в `Setup`
|
||
3. Нажать `Install Everything`
|
||
4. Проверить, что зелёные статусы появились у:
|
||
- `ssh.py`
|
||
- `Encryption module`
|
||
- `Claude /ssh skill`
|
||
- `Codex skill`
|
||
- `Codex wrapper`
|
||
- `SSH key`
|
||
|
||
Для точечного ремонта можно использовать отдельные кнопки `Claude skill` и `Codex skill` в той же вкладке.
|
||
|
||
## Ручная установка Codex Skill
|
||
|
||
### 1. Скопировать skill package в глобальный Codex home
|
||
|
||
```bash
|
||
mkdir -p ~/.codex/skills
|
||
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
|
||
```
|
||
|
||
### 2. Установить wrapper в shared runtime directory
|
||
|
||
Linux/macOS:
|
||
|
||
```bash
|
||
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh
|
||
```
|
||
|
||
Windows:
|
||
|
||
```bat
|
||
copy .codex\skills\server-manager\scripts\codex-ssh-wrapper.cmd %USERPROFILE%\.server-connections\codex-ssh.cmd
|
||
```
|
||
|
||
### 3. Проверить doctor script
|
||
|
||
Linux/macOS:
|
||
|
||
```bash
|
||
~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
|
||
```
|
||
|
||
Windows:
|
||
|
||
```bat
|
||
%USERPROFILE%\.codex\skills\server-manager\scripts\server-manager-doctor.cmd
|
||
```
|
||
|
||
Ожидается:
|
||
|
||
- `ssh.py` найден
|
||
- `encryption.py` найден
|
||
- `codex-ssh` executable
|
||
|
||
### 4. Проверить wrapper без раскрытия credentials
|
||
|
||
Linux/macOS:
|
||
|
||
```bash
|
||
~/.server-connections/codex-ssh --list
|
||
```
|
||
|
||
Windows:
|
||
|
||
```bat
|
||
%USERPROFILE%\.server-connections\codex-ssh.cmd --list
|
||
```
|
||
|
||
Это безопасная базовая проверка. Она должна вывести список алиасов и типов серверов.
|
||
|
||
### 5. Перезапустить Codex
|
||
|
||
Если у вас уже была открыта интерактивная Codex session, её нужно перезапустить. Новый skill обычно подхватывается новым процессом Codex, а не уже живой сессией.
|
||
|
||
## Как проверить, что Codex реально видит skill
|
||
|
||
Самый надёжный способ:
|
||
|
||
```bash
|
||
codex exec --skip-git-repo-check -s read-only -C /tmp \
|
||
"A user asks: Using the locally installed ServerManager integration, what is the safest first command to enumerate configured servers? Reply with only the command."
|
||
```
|
||
|
||
Если skill подхватился корректно, Codex должен сам прочитать `~/.codex/skills/server-manager/SKILL.md` и ответить:
|
||
|
||
```bash
|
||
$HOME/.server-connections/codex-ssh --list
|
||
```
|
||
|
||
## Что Codex должен делать через skill
|
||
|
||
Правильный workflow для любой server operation:
|
||
|
||
1. Сначала `--list`
|
||
2. Прочитать колонку `Type`
|
||
3. Выбрать команду строго по типу сервера
|
||
4. Выполнить ровно одно подключение/одно действие
|
||
5. Вернуть результат без IP/логинов/паролей/портов
|
||
|
||
Безопасные discovery-команды:
|
||
|
||
```bash
|
||
$HOME/.server-connections/codex-ssh --list
|
||
$HOME/.server-connections/codex-ssh --info ALIAS
|
||
$HOME/.server-connections/codex-ssh --status
|
||
```
|
||
|
||
## Источники истины по интеграции
|
||
|
||
Если меняется поведение интеграции, проверять нужно в таком порядке:
|
||
|
||
1. [tools/ssh.py](/home/code/Desktop/CODING/server-manager/tools/ssh.py)
|
||
2. [tools/skill-ssh.md](/home/code/Desktop/CODING/server-manager/tools/skill-ssh.md)
|
||
3. [core/claude_setup.py](/home/code/Desktop/CODING/server-manager/core/claude_setup.py)
|
||
4. [build.py](/home/code/Desktop/CODING/server-manager/build.py)
|
||
5. [SKILL.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/SKILL.md)
|
||
6. [command-matrix.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/references/command-matrix.md)
|
||
|
||
Если меняется семантика `ssh.py`, нужно обновлять и Claude skill, и Codex skill.
|
||
|
||
## Edge Cases
|
||
|
||
### 1. `python` alias отсутствует
|
||
|
||
В этой среде `python` отсутствует, но `ssh.py` имеет shebang `#!/usr/bin/env python3` и executable bit.
|
||
|
||
Поэтому wrapper вызывает `ssh.py` напрямую:
|
||
|
||
```bash
|
||
~/.server-connections/codex-ssh --list
|
||
```
|
||
|
||
Это намеренно лучше, чем завязка на `python ~/.server-connections/ssh.py`.
|
||
|
||
### 2. `ssh.py --help` не поддерживается
|
||
|
||
`ssh.py` не имеет полноценного `--help`. Попытка вызвать `--help` возвращает список доступных alias'ов, а не usage.
|
||
|
||
Поэтому для безопасной проверки используются:
|
||
|
||
- `--list`
|
||
- `--info ALIAS`
|
||
- `--status`
|
||
|
||
### 3. Skill установлен в repo, но не установлен глобально
|
||
|
||
Наличие `.codex/skills/server-manager/` внутри репозитория полезно как source of truth, но новый Codex процесс по умолчанию ищет глобальные skills в `~/.codex/skills`.
|
||
|
||
Если skill есть только в repo:
|
||
|
||
- документация в проекте будет на месте
|
||
- глобальный Codex может его не увидеть
|
||
|
||
Для надёжности нужен именно глобальный install в `~/.codex/skills/server-manager`.
|
||
|
||
### 4. Wrapper отсутствует, а skill уже установлен
|
||
|
||
В этом случае Codex прочитает skill, но не сможет выполнить рекомендуемую команду `$HOME/.server-connections/codex-ssh ...`.
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
|
||
```
|
||
|
||
Исправление:
|
||
|
||
```bash
|
||
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh
|
||
```
|
||
|
||
### 5. Backend отсутствует
|
||
|
||
Если нет `~/.server-connections/ssh.py` или `encryption.py`, skill бесполезен: он знает workflow, но не имеет локального transport layer.
|
||
|
||
Исправление:
|
||
|
||
1. Запустить ServerManager
|
||
2. `Setup -> Install Everything`
|
||
|
||
### 6. Интерактивный Codex уже был запущен до установки skill
|
||
|
||
Новая интерактивная сессия обычно увидит skill, старая может не увидеть.
|
||
|
||
Исправление:
|
||
|
||
- закрыть старую Codex session
|
||
- запустить новый процесс `codex`
|
||
|
||
### 7. `codex exec` не может проверить skill из-за sandbox/network policy
|
||
|
||
Во время non-interactive проверки Codex может упереться не в skill, а в сетевую политику среды:
|
||
|
||
- websocket backend заблокирован
|
||
- sandbox запрещает соединение
|
||
|
||
Симптом:
|
||
|
||
```text
|
||
failed to connect to websocket ... Operation not permitted
|
||
```
|
||
|
||
Это не означает, что skill неверный. Это означает, что проверка упёрлась в runtime policy Codex backend.
|
||
|
||
### 8. Повторная установка поверх существующего skill
|
||
|
||
GUI installer и `install_codex_skill()` синхронизируют дерево skill поверх существующей директории без полного удаления. Это безопасно для обычных обновлений.
|
||
|
||
Но при ручном `cp -R` возможен stale state, если какие-то файлы были удалены из repo, а старая глобальная копия осталась.
|
||
|
||
Полная ручная пересинхронизация нужна только если вы осознанно хотите очистить старые файлы:
|
||
|
||
1. удалить старую копию осознанно
|
||
2. снова скопировать skill целиком
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
rm -rf ~/.codex/skills/server-manager
|
||
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
|
||
```
|
||
|
||
Делать это только если вы уверены, что хотите полностью пересобрать глобальную копию.
|
||
|
||
### 9. Изменился `tools/ssh.py`, но глобальная установка осталась старой
|
||
|
||
Это самый вероятный operational drift.
|
||
|
||
Что может устареть:
|
||
|
||
- `~/.server-connections/ssh.py`
|
||
- `~/.codex/skills/server-manager/*`
|
||
- `~/.server-connections/codex-ssh`
|
||
|
||
После изменения `tools/ssh.py` или skill docs нужно заново синхронизировать:
|
||
|
||
```bash
|
||
cp tools/ssh.py ~/.server-connections/ssh.py
|
||
cp core/encryption.py ~/.server-connections/encryption.py
|
||
rm -rf ~/.codex/skills/server-manager
|
||
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
|
||
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh
|
||
```
|
||
|
||
### 10. Windows / macOS / Linux split
|
||
|
||
Сейчас runtime path intentionally разделён по платформам:
|
||
|
||
- Linux/macOS: shell wrapper `codex-ssh-wrapper.sh`
|
||
- Windows: native wrapper `codex-ssh-wrapper.cmd`
|
||
|
||
Installer на Windows кладёт wrapper как:
|
||
|
||
- `~/.server-connections/codex-ssh.cmd`
|
||
|
||
Installer на Linux/macOS кладёт wrapper как:
|
||
|
||
- `~/.server-connections/codex-ssh`
|
||
|
||
Что это закрывает:
|
||
|
||
- Linux/macOS path без platform-specific разветвления в skill
|
||
- запуск через `cmd.exe`
|
||
- запуск из PowerShell
|
||
- отсутствие bash-зависимости для стандартного Windows deployment path
|
||
|
||
Ограничение остаётся одно: в текущей среде я прогнал end-to-end smoke только на Linux. macOS и Windows path подготовлены в installer/docs, но не smoke-tested здесь из-за отсутствия соответствующих runner'ов.
|
||
|
||
### 11. `ssh.py` intentionally не должен читать secrets в контекст AI
|
||
|
||
Это не баг. Даже если кажется проще открыть `servers.json`, делать этого нельзя.
|
||
|
||
Skill намеренно запрещает:
|
||
|
||
- `cat ~/.server-connections/servers.json`
|
||
- `cat ~/.server-connections/settings.json`
|
||
- `python -c "...read servers.json..."`
|
||
- `--list-full`
|
||
|
||
### 12. fail2ban / anti-bruteforce edge case
|
||
|
||
Повторные неудачные подключения опасны. Поэтому skill зафиксирован как:
|
||
|
||
- максимум 1 попытка на действие
|
||
- при timeout/ошибке остановиться и сообщить пользователю
|
||
|
||
Это обязательное правило, а не рекомендация.
|
||
|
||
## Рекомендуемый Update Workflow
|
||
|
||
После любых изменений, затрагивающих Codex integration:
|
||
|
||
1. Обновить исходники в repo:
|
||
- `tools/ssh.py`
|
||
- `.codex/skills/server-manager/*`
|
||
- этот документ
|
||
2. Синхронизировать глобальную установку
|
||
3. Прогнать doctor
|
||
4. Прогнать `~/.server-connections/codex-ssh --list`
|
||
5. Прогнать свежий `codex exec` smoke test
|
||
|
||
## Минимальный Smoke Test
|
||
|
||
```bash
|
||
~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
|
||
~/.server-connections/codex-ssh --list
|
||
codex exec --skip-git-repo-check -s read-only -C /tmp \
|
||
"A user asks: Using the locally installed ServerManager integration, what is the safest first command to enumerate configured servers? Reply with only the command."
|
||
```
|
||
|
||
## Что ещё желательно автоматизировать позже
|
||
|
||
Чтобы интеграция стала production-complete, в проект ещё полезно добавить:
|
||
|
||
1. отдельный smoke test script внутри репозитория для проверки именно Codex integration
|
||
2. e2e smoke test на Windows runner
|
||
3. e2e smoke test на macOS runner
|
||
4. optional PowerShell-native wrapper, если понадобится richer Windows logging
|