Unica

Unica (Ю́ника) — плагин для Codex, Claude Code и ZCode для разработки на 1С:Предприятии. Он добавляет навыки и один MCP-сервер unica, через который агент создаёт и проверяет метаданные, формы, роли, СКД, внешние обработки и отчёты, запускает 1С и ищет BSL-код.

Все три хоста получают один и тот же каталог плагина: манифесты лежат рядом, а .mcp.json определяет корень плагина по той переменной, которую подставляет конкретный хост.

Требования

• один из агентов:
  • Codex CLI;
  • Claude Code;
  • ZCode Desktop с поддержкой .zcode-plugin (контракт проверяется для 3.14.4);
• стандартный Git, включая Git for Windows на Windows;
• платформа 1С только для операций, которым реально требуется запуск 1С.

Поддерживаемые версии платформы 1С

Версия платформы	Статус	Что это означает
8.5.1.x, 8.5.4.x	Планируется	Хотим добавить в ближайшее время.
8.3.27.x	Поддерживается	Unica поддерживает все актуальные релизы ветки 8.3.27.
8.3.26.x и ниже	Не планируется	Помогаем мигрировать на 8.3.27. Если вам действительно нужна более старая версия, создайте issue и опишите причину — нам важно понимать такой сценарий.

Установка

Codex

codex plugin marketplace add IngvarConsulting/unica-marketplace --ref main
codex plugin add unica@unica

После установки откройте new Codex task: список навыков и MCP-конфигурация фиксируются на границе новой задачи, а не подменяются в уже работающей сессии.

Claude Code

claude plugin marketplace add IngvarConsulting/unica-marketplace
claude plugin install unica@unica

Затем выполните /reload-plugins либо начните новую сессию. Навыки становятся доступны с префиксом плагина, например /unica:meta-info.

ZCode

Пакет содержит нативный .zcode-plugin/plugin.json, общий .mcp.json и те же навыки и runtime, что для Codex и Claude Code. Отдельный MCP-сервер, launcher или преобразователь аргументов для ZCode не требуется.

В ZCode откройте Plugin Marketplace → Add → Add Plugin Marketplace и добавьте каталог выпуска, содержащего ZCode-манифест. Для локальной проверки используйте корень собранного marketplace, а не исходный plugins/unica: его .mcp.json предназначен для разработки через Cargo. В Personal найдите плагин и установите его; установленными плагинами управляет Settings → Plugins. Оставьте включённой только одну установку Юники, чтобы не запускать две версии.

После установки начните новую задачу и попросите вызвать unica.run с {} без запуска 1С. Ожидается словарь операций текущей версии, а не требование заполнить все аргументы. Уже открытая сессия может хранить старую схему runtime.execute; она не проверяет новый пакет. Успешная упаковка или прямой tools/list не заменяет этот тест через выбранную модель и провайдера. Подробности локальной проверки — в CONTRIBUTING.md.

Доставка ядра и движков

При старте MCP bootstrap скачивает только ядро unica из релиза IngvarConsulting/unica для текущей ОС и архитектуры. После запуска ядро доставляет нужный движок из закреплённого релиза unica-toolchain перед первым вызовом, которому этот движок действительно нужен. Архив, ассет и каждый файл проверяются по SHA-256; неполная или повреждённая загрузка не получает маркер готовности.

Если доставка движка не завершилась внутри ограниченного окна, вызов возвращает work.status=working и не запускает обработчик. Повторите тот же предметный вызов: отдельного публичного инструмента установки нет. Параллельные вызовы делят одну загрузку.

Корень кэша зависит от хоста:

Хост	Каталог кэша
Codex	$CODEX_HOME/unica/runtimes, при стандартном CODEX_HOME — ~/.codex/unica/runtimes
Claude Code	${CLAUDE_PLUGIN_DATA}/runtimes, по умолчанию — ~/.claude/plugins/data/unica-unica/...; этот каталог переживает обновление плагина
ZCode	${ZCODE_PLUGIN_DATA}/runtimes; хост также передаёт совместимый CLAUDE_PLUGIN_DATA с тем же значением

Явные UNICA_RUNTIME_CACHE_DIR и UNICA_PROVIDER_STATE_DIR сохраняют приоритет над настройками хостов. При запуске через bootstrap состояние провайдеров без переопределения размещается в <каталог данных плагина>/unica/provider-state. Локальный debug-пакет запускает ядро напрямую: без UNICA_PROVIDER_STATE_DIR оно использует ~/.unica/provider-state, а не каталог данных плагина. Оба пути — корни хранилища, не идентичность рабочего проекта. Рабочую папку ZCode передаёт через ZCODE_PROJECT_DIR и совместимый CLAUDE_PROJECT_DIR; конфликт значений даёт отказ, а не выбор чужого проекта. Эти переменные фиксируются при запуске сервера. Если клиент в сессии до протокола 2026-07-28 объявил MCP roots, Unica заново запрашивает их на каждом предметном вызове и берёт первый root. Так новый проект сессии подхватывается без перезапуска сервера.

Внутри корня каждая неизменяемая поставка лежит по адресу /<version>--/<target>. Поэтому пересобранные байты с той же версией не перезаписывают прежний движок. Для образа, который после сборки работает без сети, заранее доставьте ядро и все движки:

/bootstrap/bin/<target>/unica-bootstrap prefetch --plugin-root 

Обновление

Codex

codex plugin marketplace upgrade unica
codex plugin remove unica@unica
codex plugin add unica@unica

Затем откройте new Codex task: уже работающая сессия не загрузит обновлённые навыки и MCP-конфигурацию.

Отдельной команды codex plugin upgrade в поддерживаемом CLI нет, поэтому переустановка плагина после обновления каталога является намеренным шагом.

Claude Code

claude plugin marketplace update unica
claude plugin update unica@unica

Затем выполните /reload-plugins.

ZCode

В источниках mark