aibot777/server-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 36 Wiki Activity
Files
master
server-manager/CODEX_SKILL_SETUP.md

16 KiB
Raw Permalink Blame History

Развёртывание 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 лежат здесь:

Как это работает

Модель безопасности та же, что и у Claude integration:

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

Проверка:

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

mkdir -p ~/.codex/skills
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager

2. Установить wrapper в shared runtime directory

Linux/macOS:

install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh

Windows:

copy .codex\skills\server-manager\scripts\codex-ssh-wrapper.cmd %USERPROFILE%\.server-connections\codex-ssh.cmd

3. Проверить doctor script

Linux/macOS:

~/.codex/skills/server-manager/scripts/server-manager-doctor.sh

Windows:

%USERPROFILE%\.codex\skills\server-manager\scripts\server-manager-doctor.cmd

Ожидается:

  • ssh.py найден
  • encryption.py найден
  • codex-ssh executable

4. Проверить wrapper без раскрытия credentials

Linux/macOS:

~/.server-connections/codex-ssh --list

Windows:

%USERPROFILE%\.server-connections\codex-ssh.cmd --list

Это безопасная базовая проверка. Она должна вывести список алиасов и типов серверов.

5. Перезапустить Codex

Если у вас уже была открыта интерактивная Codex session, её нужно перезапустить. Новый skill обычно подхватывается новым процессом Codex, а не уже живой сессией.

Как проверить, что Codex реально видит skill

Самый надёжный способ:

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 и ответить:

$HOME/.server-connections/codex-ssh --list

Что Codex должен делать через skill

Правильный workflow для любой server operation:

  1. Сначала --list
  2. Прочитать колонку Type
  3. Выбрать команду строго по типу сервера
  4. Выполнить ровно одно подключение/одно действие
  5. Вернуть результат без IP/логинов/паролей/портов

Безопасные discovery-команды:

$HOME/.server-connections/codex-ssh --list
$HOME/.server-connections/codex-ssh --info ALIAS
$HOME/.server-connections/codex-ssh --status

Источники истины по интеграции

Если меняется поведение интеграции, проверять нужно в таком порядке:

  1. tools/ssh.py
  2. tools/skill-ssh.md
  3. core/claude_setup.py
  4. build.py
  5. SKILL.md
  6. 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 напрямую:

~/.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 ....

Проверка:

~/.codex/skills/server-manager/scripts/server-manager-doctor.sh

Исправление:

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 запрещает соединение

Симптом:

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 целиком

Пример:

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 нужно заново синхронизировать:

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

~/.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 View Git Blame Copy Permalink