v1.9.40: add Codex integration — skill setup, deploy, GUI buttons
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
IPGO Developer
409
CODEX_SKILL_SETUP.md
Normal file
409
CODEX_SKILL_SETUP.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# Развёртывание 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/CODING/server-manager/.codex/skills/server-manager/SKILL.md)
|
||||
- [command-matrix.md](/home/code/CODING/server-manager/.codex/skills/server-manager/references/command-matrix.md)
|
||||
- [project.md](/home/code/CODING/server-manager/.codex/skills/server-manager/references/project.md)
|
||||
- [server-manager-doctor.sh](/home/code/CODING/server-manager/.codex/skills/server-manager/scripts/server-manager-doctor.sh)
|
||||
- [server-manager-doctor.cmd](/home/code/CODING/server-manager/.codex/skills/server-manager/scripts/server-manager-doctor.cmd)
|
||||
- [codex-ssh-wrapper.sh](/home/code/CODING/server-manager/.codex/skills/server-manager/scripts/codex-ssh-wrapper.sh)
|
||||
- [codex-ssh-wrapper.cmd](/home/code/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/CODING/server-manager/tools/ssh.py)
|
||||
2. [tools/skill-ssh.md](/home/code/CODING/server-manager/tools/skill-ssh.md)
|
||||
3. [core/claude_setup.py](/home/code/CODING/server-manager/core/claude_setup.py)
|
||||
4. [build.py](/home/code/CODING/server-manager/build.py)
|
||||
5. [SKILL.md](/home/code/CODING/server-manager/.codex/skills/server-manager/SKILL.md)
|
||||
6. [command-matrix.md](/home/code/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
|
||||
Reference in New Issue
Block a user