# Codex Plugins для начинающих: что пришло на смену обычным Skills > Исчерпывающее руководство по экосистеме плагинов в Codex: разница между Skills и Plugins, подключение Marketplaces, установка через GUI и CLI, интеграция MCP-серверов и разработка собственного плагина. ## 1. Эволюция экосистемы: от базовых Skills к модульным Plugins На ранних этапах работы со средами автономной разработки основным инструментом настройки поведения ИИ-агента были **Skills** — изолированные папки с инструкциями в формате Markdown (`SKILL.md`), объясняющие модели выполнение конкретных задач: проведение код-ревью по корпоративным стандартам, оптимизацию запросов к базе данных или написание документации. Skills остаются базовым строительным блоком знаний, однако их ручное копирование между проектами, отсутствие версионирования и невозможность поставлять исполняемые инструменты вместе с инструкциями привели к появлению полноценной модульной экосистемы — **Codex Plugins** и каталогов **Marketplaces**. ```mermaid flowchart TD subgraph Distribution ["Уровень дистрибуции"] M["Marketplace (Git-репозиторий или локальная папка)"] end subgraph Packaging ["Уровень пакетирования: Plugin"] P["Codex Plugin"] P --> S["Skills (Инструкции и экспертиза)"] P --> T["MCP Tools (Внешние API: GitHub, Slack, Figma)"] P --> H["Hooks (Автоматические триггеры событий)"] P --> C["Config (Манифест plugin.json)"] end subgraph Execution ["Уровень выполнения"] Session["Новая рабочая сессия Codex"] end M -->|codex plugin add| P P -->|Инициализация расширений| Session ``` ### Сравнение архитектуры: Skill против Plugin | Характеристика | Базовый Skill | Модульный Plugin | | :--- | :--- | :--- | | **Основное назначение** | Описание правил и пошагового процесса для отдельной задачи | Полноценный пакет расширения среды выполнения агента | | **Содержимое пакета** | Текстовый файл `SKILL.md` + вспомогательные справочные файлы | Набор Skills, MCP-серверы, хуки жизненного цикла, конфигурации | | **Внешние интеграции** | Не поддерживает нативное подключение к сторонним API | Интегрирует внешние сервисы через протокол MCP | | **Дистрибуция** | Ручное копирование файлов в рабочую директорию проекта | Установка одной командой в CLI или в один клик через Marketplaces | | **Обновления** | Ручная замена файлов инженером | Автоматическое обновление через CLI или каталог расширений | > [!NOTE] > Самая точная аналогия из мира разработки: **Skills — это отдельные библиотечные функции**, а **Plugins — готовые пакеты (npm-модули)**. Если вам требуется простая локальная инструкция, достаточно обычного Skill. Если же вы хотите предоставить модели инструменты взаимодействия с GitHub, Slack или Figma вместе с готовыми сценариями — используйте Plugin. --- ## 2. Анатомия плагина: Skills, MCP-серверы, конфигурации и хуки Плагин в Codex — это не просто большой системный промпт. Это структурированный каталог или архив, включающий декларативный манифест и исполняемые компоненты. ```text my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Обязательный манифест плагина ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Первый встроенный скил │ └── perf-audit/ │ └── SKILL.md # Второй встроенный скил ├── mcp/ │ └── server-config.json # Конфигурация MCP-сервера └── README.md # Документация для разработчиков ``` ### Составные части современного плагина 1. **Манифест (`.codex-plugin/plugin.json`):** Главный конфигурационный файл, определяющий уникальный идентификатор плагина, его версию, автора, зависимости и точки входа. 2. **Набор навыков (`skills/`):** Один или несколько каталогов с файлами `SKILL.md`, обучающими Codex инженерным подходам. 3. **MCP-серверы (Model Context Protocol):** Исполняемые серверы или адаптеры, предоставляющие агенту инструменты прямого вызова API (например, чтение pull requests в GitHub, создание задач в Linear или экспорт макетов из Figma). 4. **Хуки жизненного цикла (Lifecycle Hooks):** Скрипты, автоматически запускающиеся при определенных событиях в сессии (например, запуск линтера перед созданием коммита). ```json { "name": "developer-toolkit", "version": "1.2.0", "description": "Комплексный набор инструментов для аудита кода и автоматизации GitHub", "author": "Engineering Team", "skills": [ "./skills/code-review", "./skills/perf-audit" ], "mcpServers": { "github-connector": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } } ``` > [!IMPORTANT] > В отличие от обычных промптов, плагины расширяют технический инструментарий агента (tooling capabilities). Без плагина с MCP-сервером агент лишь рассуждает о работе с GitHub; с установленным плагином он получает нативные команды для непосредственного обращения к GitHub API. --- ## 3. Что такое Marketplaces: каталоги расширений и источники дистрибуции Для централизованного поиска, проверки и распространения плагинов в Codex используется концепция **Marketplaces** (каталогов расширений). Marketplace — это реестр или репозиторий со списком доступных плагинов, метаданными и адресами источников для скачивания. Вместо ручной загрузки архивов из непроверенных источников разработчик подключает доверенный маркетплейс и устанавливает пакеты по их короткому идентификатору. ```mermaid flowchart LR subgraph Sources ["Источники каталогов"] Official["Официальный реестр OpenAI"] Community["Публичные GitHub-каталоги"] Private["Внутренние корпоративные реестры"] Local["Локальные папки разработчика"] end subgraph Client ["Клиентская среда Codex"] Reg["Менеджер Marketplaces"] Reg --> P1["Plugin: GitHub Sync"] Reg --> P2["Plugin: PostgreSQL Inspector"] Reg --> P3["Plugin: Team Styleguide"] end Official --> Reg Community --> Reg Private --> Reg Local --> Reg ``` ### Типы поддерживаемых маркетплейсов - **Официальный публичный каталог:** Встроенный реестр, доступный по умолчанию всем пользователям Codex. Содержит верифицированные плагины для популярных сервисов (Figma, Notion, Google Workspace, GitHub). - **Git-репозитории сообщества:** Публичные или приватные репозитории на GitHub/GitLab, оформленные по спецификации маркетплейса. - **Корпоративные закрытые реестры:** Каталоги компаний, содержащие плагины для работы с закрытыми микросервисами, корпоративными VPN и базами данных. - **Локальные директории разработки:** Папки на локальном диске, используемые для сборки, тестирования и отладки новых плагинов перед их публикацией. --- ## 4. Работа через графический интерфейс: команда /plugins и управление Для повседневного использования разработчику не требуется запоминать терминальные команды — в Codex встроен удобный графический браузер плагинов. ### Вызов визуального каталога Чтобы открыть менеджер плагинов, введите в строке ввода активной сессии Codex команду: ```bash /plugins ``` Интерактивный интерфейс позволяет: - **Просматривать установленные плагины:** Видеть список всех активных расширений и их текущий статус. - **Искать новые пакеты:** Фильтровать плагины по имени, тегам и категориям (Development, DevOps, Analytics, Design). - **Переключаться между каталогами:** Фильтровать доступные плагины по конкретным подключенным маркетплейсам. - **Управлять активностью:** В один клик включать (Enable) или временно отключать (Disable) плагины без их удаления. > [!WARNING] > **Правило новой сессии:** После установки плагина или включения ранее деактивированного расширения его инструменты и навыки активируются **только в новых рабочих сессиях**. Текущая сессия сохраняет свое исходное состояние; всегда открывайте новый диалог после изменения состава плагинов. --- ## 5. Управление плагинами через CLI: список, установка и удаление Для разработчиков, предпочитающих терминал, а также для сценариев автоматизации в CI/CD и контейнерах, Codex предоставляет набор команд `codex plugin`. ### Базовые команды для работы с плагинами :::tabs @tab Список установленных ```bash # Вывести список всех плагинов, установленных в текущем окружении codex plugin list ``` @tab Список доступных ```bash # Просмотреть список всех плагинов из подключенных маркетплейсов codex plugin list --available # Получить детальный вывод в машиночитаемом формате JSON codex plugin list --available --json ``` @tab Установка плагина ```bash # Установить плагин по уникальному имени codex plugin add github-toolkit # Установить плагин из конкретного маркетплейса codex plugin add dev-suite@company-internal ``` @tab Удаление плагина ```bash # Полностью удалить плагин из локального окружения codex plugin remove github-toolkit # Удалить плагин с привязкой к конкретному источнику codex plugin remove dev-suite@company-internal ``` ::: Команда `codex plugin list` отображает имя каждого плагина, его версию, источник и статус активности. --- ## 6. Управление Marketplaces: добавление репозиториев, обновление и удаление Для расширения каталога доступных плагинов подключите внешние источники с помощью подкоманд `codex plugin marketplace`. ### Просмотр подключенных каталогов ```bash codex plugin marketplace list ``` Команда выводит имя каждого каталога, протокол источника (git или local) и его URI. ### Добавление новых маркетплейсов Codex поддерживает несколько форматов подключения в зависимости от сетевой инфраструктуры: :::tabs @tab GitHub Shorthand ```bash # Короткая запись для репозиториев GitHub (owner/repo) codex plugin marketplace add orlov-ai/community-plugins ``` @tab HTTPS Git URL ```bash # Стандартный HTTPS-адрес (подходит для открытых GitLab/Bitbucket) codex plugin marketplace add https://github.com/company/internal-codex-plugins.git ``` @tab SSH Git URL ```bash # Подключение через приватные SSH-ключи для корпоративных репозиториев codex plugin marketplace add git@github.com:enterprise/secure-plugins.git ``` @tab Локальная папка ```bash # Подключение локальной директории для разработки и тестирования codex plugin marketplace add ./my-local-marketplace ``` ::: ### Обновление и удаление каталогов ```bash # Обновить индекс конкретного маркетплейса codex plugin marketplace upgrade community-plugins # Обновить индексы всех подключенных Git-маркетплейсов codex plugin marketplace upgrade # Удалить маркетплейс из списка источников codex plugin marketplace remove community-plugins ``` > [!TIP] > Если плагин недавно обновился или опубликован коллегами, но еще не отображается в списке, выполните `codex plugin marketplace upgrade` для синхронизации локального индекса. --- ## 7. Плагины с MCP-серверами: авторизация, права доступа и безопасность Когда плагин содержит **MCP-сервер**, он получает возможность взаимодействовать со сторонними системами (базами данных, облачными хранилищами, API). Это превращает Codex из помощника по генерации кода в активного агента автоматизации. ```mermaid sequenceDiagram autonumber actor Dev as Инженер participant Codex as Сессия Codex participant Plugin as Плагин (MCP Adapter) participant Cloud as Внешний сервис (GitHub API) Dev->>Codex: "Создай issue с результатами аудита" Codex->>Plugin: Вызов инструмента create_issue() alt Требуется авторизация Plugin-->>Dev: Запрос подтверждения OAuth или токена Dev->>Plugin: Подтверждение учетных данных end Plugin->>Cloud: POST /repos/:owner/:repo/issues Cloud-->>Plugin: HTTP 201 Created (Issue #42) Plugin-->>Codex: Результат с ссылкой на issue Codex-->>Dev: "Issue #42 успешно создан!" ``` ### Механизмы авторизации во внешних сервисах 1. **OAuth-аутентификация:** Облачные сервисы (Google Drive, Slack, GitHub) при первом вызове инструмента открывают окно браузера для подтверждения доступа к аккаунту. 2. **Переменные окружения для секретов:** Адаптеры баз данных и закрытых API (PostgreSQL, Supabase) считывают ключи из `.env` файлов или настроек Codex. 3. **Гранулярные разрешения (Permissions):** Codex запрашивает подтверждение пользователя перед выполнением потенциально опасных действий (удаление строк в БД, отправка сообщений, закрытие pull request). > [!WARNING] > **Безопасность MCP-серверов:** Никогда не устанавливайте плагины с MCP-серверами из непроверенных источников. Вредоносный MCP-сервер может прочитать локальные файлы или отправить приватные API-ключи на сторонние серверы. Всегда проверяйте исходный код перед установкой. --- ## 8. Жизненный цикл: отключение, удаление плагина или удаление каталога Разработчики часто путают три уровня деактивации расширений: | Действие | Команда / Способ | Влияние на файловую систему | Последствия для сессий | | :--- | :--- | :--- | :--- | | **Отключение плагина (Disable)** | Переключатель в `/plugins` | Файлы остаются на диске, настройки сохраняются | Навыки и MCP-инструменты становятся неактивны в новых сессиях | | **Удаление плагина (Uninstall)** | `codex plugin remove ` | Файлы плагина полностью удаляются из локального кэша | Полная очистка; для повторного использования потребуется повторная установка | | **Удаление маркетплейса** | `codex plugin marketplace remove ` | Удаляется только источник; установленные плагины остаются | Нельзя получать обновления или устанавливать новые плагины из этого каталога | ### Практическое руководство по выбору - Если плагин временно не нужен или конфликтует с другим инструментом — **отключите его (Disable)** через интерфейс `/plugins`. - Если проект завершен и плагин больше не понадобится — **удалите его полностью (Remove)** через CLI. - Если сторонний каталог перестал поддерживаться — **удалите маркетплейс (Marketplace Remove)**. --- ## 9. Разработка собственного Plugin: манифест, упаковка Skills и локальное тестирование Создание собственного плагина — лучший способ стандартизировать инженерные практики команды и обеспечить стабильное качество генерации кода. ### Пошаговое руководство по созданию плагина #### Шаг 1. Подготовка структуры проекта Создайте директорию для плагина: ```bash mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review ``` #### Шаг 2. Создание манифеста `plugin.json` Создайте файл `.codex-plugin/plugin.json`: ```json { "name": "team-architecture-plugin", "version": "1.0.0", "description": "Корпоративные правила архитектуры и аудит чистоты слоев", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] } ``` #### Шаг 3. Добавление инструкций в `SKILL.md` Создайте файл `my-team-plugin/skills/architecture-review/SKILL.md`: ```markdown --- name: architecture-review description: Проверка соответствия модулей принципам Domain-Driven Design (DDD) --- При анализе архитектурных модулей проверяй соблюдение следующих правил: 1. Бизнес-логика никогда не должна напрямую импортировать ORM или драйвер базы данных. 2. Внешние интеграции должны определяться как интерфейсы (порты) во внутреннем слое. 3. Каждая мутация состояния должна сопровождаться генерацией доменного события. ``` #### Шаг 4. Подключение локального маркетплейса и тестирование Чтобы протестировать плагин локально без публикации на GitHub, зарегистрируйте родительскую папку как локальный маркетплейс: ```bash # Подключаем локальную директорию как источник маркетплейса codex plugin marketplace add ./local-market # Устанавливаем наш созданный плагин codex plugin add team-architecture-plugin # Проверяем статус установки codex plugin list ``` Откройте новую сессию в Codex и протестируйте работу плагина на реальной задаче по ревью архитектуры. --- ## 10. Итоговая шпаргалка по командам и чек-лист безопасности перед установкой Сохраните эту сводку для быстрой навигации в терминале и поддержания безопасности рабочего окружения. ### Справочник команд CLI ```bash # ─── Работа с плагинами ─────────────────────────────────────────── codex plugin list # Список установленных плагинов codex plugin list --available # Список доступных плагинов в каталогах codex plugin add # Установить плагин codex plugin add # Установить из конкретного каталога codex plugin remove # Удалить плагин # ─── Работа с Marketplaces ──────────────────────────────────────── codex plugin marketplace list # Список подключенных маркетплейсов codex plugin marketplace add # Добавить маркетплейс (GitHub / URL / локальный) codex plugin marketplace upgrade # Обновить индекс конкретного каталога codex plugin marketplace upgrade # Обновить все подключенные каталоги codex plugin marketplace remove # Отключить каталог # ─── Графический интерфейс ───────────────────────────────────────── /plugins # Открыть интерактивный браузер плагинов ``` ### Чек-лист безопасности перед установкой стороннего плагина - [ ] **Репутация источника:** Маркетплейс принадлежит официальному разработчику или проверенному сообществу. - [ ] **Аудит манифеста:** В `plugin.json` отсутствуют сомнительные команды или непроверенные бинарные зависимости. - [ ] **Проверка сетевых адресов MCP:** Сервер MCP отправляет запросы исключительно на официальные API-эндпоинты сервиса. - [ ] **Отсутствие конфликтов:** Навыки плагина не перекрывают глобальные системные правила. - [ ] **Тестирование в песочнице:** Новый плагин проверен в тестовом изолированном проекте перед добавлением в основной репозиторий.