unica for DeepSeek Harness
Порт публичного плагина Unica на DeepSeek Harness.
Unica — инструментарий разработки на 1С:Предприятии: 50 навыков и один stdio MCP-сервер с 11 инструментами для метаданных, форм, ролей, СКД и MXL, внешних обработок и отчётов, сборки и обновления информационных баз, поиска и диагностики BSL-кода. Апстрим поддерживает Codex и Claude Code; DSH в нём не поддерживается, поэтому этот репозиторий — интеграционный слой.
Порт поднимает unica на каждый рабочий каталог сессии: один профиль DSH
обслуживает сколько угодно проектов, и unica.search/check/view всегда
смотрят в тот каталог, из которого пришёл вызов.
Код апстрима не изменяется и не форкается. Переписывается ровно одно: пространство имён инструментов (см. Как это работает).
Версия и артефакты
Опубликованный релиз v0.15.0.6
содержит шестую ревизию порта на Unica 0.15.0-rc.5. Первой с
нативным мостом вместо MCP-строки была 0.15.0.3: рабочий каталог берётся из
сессии (см. Совместимость с DSH). В 0.15.0.4 установщик
на Windows возвращает приглашение после irm ... | iex и не оставляет за собой
демон unica. В 0.15.0.5 установщик восстанавливает плагин и профиль при
ошибке обновления, а нативный мост поддерживает отмену вызова во время запуска.
В 0.15.0.6 выгрузка плагина во время initialize завершает запускающийся
MCP-сервер и отклоняет ожидающие вызовы до выполнения инструмента.
| Unica | 0.15.0-rc.5 |
| Ревизия порта | 6 |
| Инструментов | 11 |
| Навыков | 50 |
| Файлов справочников | 46 |
v8-runner |
0.15.3 |
| Ядро рантайма | ≈15 МБ, движки скачиваются отдельно |
Поверхность 0.15 — один сервер с 11 инструментами и 50 навыками. Линия 0.12 (74 действия, 76 навыков, 300 МБ бинарников в поставке) портом не поддерживается: апстрим переработал поверхность в 0.13.0 и с тех пор публикует архив рантайма вместо бинарников bootstrap.
Проверка порта и находки
Документы под docs/:
| Файл | Что внутри |
|---|---|
| native-verification.md | как проверить, что плагин установлен и работает: автотесты моста, патч профиля, рабочее пространство сессии, изоляция двух сессий, запись метаданных, диагностика — только то, что не зависит от платформы 1С |
| platform-verification.md | расширенный сценарий: платформенные операции (make, infobase.create, push), формы, СКД, роли, перехватчики, расширения, лицензия, живучесть задач |
| platform-findings.md | что важно знать о платформе 1С под DSH: целостность кэша, XML, который она считает критичным, лицензия, Vanessa |
Возможности
- Навыки Unica как навыки DSH — 50 каталогов, все ссылки на справочники сохранены.
- Нативный мост к
unica— 11 инструментов:view,apply,resolve,search,check,diff,run,docs,task.get/result/cancel. - Рабочий каталог на каждый вызов — мост берёт его из сессии DSH и держит пул процессов unica по каталогам, поэтому две сессии в разных проектах видят разные кодовые базы.
- Адресация через
at—<sourceSet>:<Kind>[.<Name>...]вместо путей. - План перед записью —
applyвозвращаетexecutionTokenи меняет файлы только повторным вызовом с этим токеном. - Родные инструменты DSH — модель видит их как
mcp__unica__…(имена сохранены от прежней MCP-строки), рядом сread,writeи остальными.
Требования
- Node.js — установщик, лаунчер и упаковщик.
- DSH 0.2.2-rc.1 или новее — мосту нужен сервис
ctx.workingDirectory; проверено на 0.2.2-rc.1. На более старых DSH ставьте ревизию0.15.0.2. - 1С:Предприятие — только для операций, которые реально запускают платформу. Чтение метаданных, разбор форм, СКД и MXL, поиск и диагностика BSL работают без неё.
- Сеть при первом запуске — ядро unica (~15 МБ), а затем движки
(
v8-runner,bsl-analyzer,rlm-tools-bsl) в фоне. Следующие запуски используют кэш. - Платформы — Windows x64, Linux x64, macOS arm64.
Совместимость с DSH
Установщик поддерживает шаблоны DSH начиная с 0.2.0. В 0.2.1 DSH убрал переменную
{{cwd}} и строку persona.suffix из стандартного шаблона, поэтому начиная с
0.15.0.2 правила сессии добавляются ключом suffix в существующую строку
persona, а не заменой строки шаблона. Ревизии начиная с 0.15.0.3 требуют DSH с
сервисом ctx.workingDirectory — мост берёт из него каталог сессии; проверено
на DSH 0.2.2-rc.1 (DSH Desktop, macOS arm64). Более старая ревизия 0.15.0.2
(MCP-строка) ставилась и на 0.2.0-rc.2.
Установка
Одной командой — скачает релизный архив, сверит SHA-256, распакует плагин и сразу проверит, что unica поднимается и отвечает:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/malinovme/dsh-unica/main/install.sh | sh
# Windows
irm https://raw.githubusercontent.com/malinovme/dsh-unica/main/install.ps1 | iex
Чтобы закрепить версию, передайте её процессу sh (для Windows — параметр
-Version):
curl -fsSL https://raw.githubusercontent.com/malinovme/dsh-unica/main/install.sh | UNICA_VERSION=v0.15.0.6 sh
Скрипт сам выбирает профиль (desktop, если он есть, иначе web), а если
каталог кэша отказывает демону сервера — переносит кэш без вашего участия.
Для распаковки архива установщику нужен tar, а для запуска плагина — Node.js.
Если у вас стоят и Desktop, и Web GUI, запустите установщик для каждого профиля.
В install.sh профиль задаётся переменной UNICA_PROFILE (web или desktop).
В PowerShell сохраните install.ps1 и запустите .\install.ps1 -Profile web,
затем .\install.ps1 -Profile desktop. Подробнее о выборе профиля — в
README плагина.
Из исходников — если хотите править порт:
git clone https://github.com/malinovme/dsh-unica.git
cd dsh-unica/dsh-unica-plugin
node install.mjs --target both --verify
Вручную из архива — архив раскрывается без обёртки, его содержимое и есть каталог плагина:
tar -xzf dsh-plugin-unica.tar.gz && node install.mjs --verify
Установщик сам определит $DSH_HOME (~/.dsh), ОС и способ запуска, и пропишет
абсолютные пути вашей машины. Флаг --verify запускает мост в каталоге проверки
и печатает результат — native check : ok serverInfo unica 0.15.0-rc.5, 11 tools in … ms, workspace …; без него установка проверяет только записанные
файлы.
Затем перезапустите сервер DSH и начните новую сессию, выбрав пресет «Unica 1C».
Варианты установки
| Команда | Что делает |
|---|---|
node install.mjs |
только агент-пресет для Web GUI (по умолчанию) |
node install.mjs --verify |
то же плюс самопроверка: поднимает unica и читает unica.view {} |
node install.mjs --cache-dir D:\unica-cache |
перенести кэш, если каталог по умолчанию отказывает демону |
node install.mjs --verify-cwd D:\proj\ib |
каталог, в котором --verify проверяет мост (пина проекта больше нет) |
node install.mjs --target both |
ещё и патч профиля headless |
node install.mjs --target preset --profile desktop |
установка в DSH Desktop |
node install.mjs --dry-run |
показать план, ничего не записывать |
Не размещайте кэш рантайма внутри рабочего каталога. DSH помечает файлы в рабочем каталоге низкой целостностью (Low), и метка наследуется на всё, что там создаётся.
v8-runner.exeиз такого кэша запускается с Low-токеном, а его дети —1cv8,ibcmd— не могут писать в профиль пользователя, куда 1С обязана писать (%LOCALAPPDATA%\1C\1cv8). Симптомы:ibcmdпадает с «доступ запрещён» или ошибкойstandalone-server/lock.pid, а1cv8 DESIGNERзависает, потребляя процессор. Держите кэш вне рабочего каталога — по умолчанию он и так лежит в$DSH_HOME/unica/runtimes.
Какой вариант нужен. Web GUI и DSH Desktop собирают сессии из агент-пресета,
поэтому им нужен --target preset (у Desktop дополнительно --profile desktop).
Для headless, tui, sdk и acp укажите --target profile --profile <имя>.
Команда node install.mjs --target both по умолчанию устанавливает пресет в
web и строки плагина в headless. Скрипты install.sh и install.ps1
по умолчанию устанавливают пресет в выбранный профиль.
Обновление установленной версии
При обновлении скрипт распаковывает релиз рядом с каталогом плагина и проверяет
install.mjs и имя пакета. До успешного завершения установки и самопроверки
он хранит прежнюю версию и копию cordis.patch.yml выбранного профиля.
Если установка завершилась с ошибкой, скрипт восстанавливает их по прежним
путям. Скачанный кэш рантайма переиспользуется. Для обновления повторите
команду установки:
curl -fsSL https://raw.githubusercontent.com/malinovme/dsh-unica/main/install.sh | sh
Затем перезапустите DSH и начните новую сессию: состав пресета фиксируется при её создании.
Как выбрать пресет
Пресет — это строка плагина в cordis.patch.yml профиля, а не каталог на диске:
так устроен DSH 0.2.0 (в 0.1.x пресеты сканировались из
$DSH_HOME/.agent-presets, и этот механизм удалён). Поэтому список пресетов
пересобирается при загрузке профиля:
- Перезапустите сервер
dsh web(или приложение DSH Desktop). - Начните новую сессию — состав сессии фиксируется при её создании.
Пресет называется «Unica 1C». Если его нет в списке — см. Известные ограничения и диагностику в README плагина.
Использование
После выбора пресета модель видит 11 инструментов unica и 50 навыков. Типичный
цикл работы:
view {} → view {at} → apply (план) → diff (executionToken) → apply (executionToken) → check
view {}показывает рабочий каталог и наборы исходников.view {at}читает узел по логическому адресу.resolveпомогает найти логический адрес по пути к файлу исходников.applyсatиopsстроит план и возвращаетdata.executionToken. Передайте токен вdiff, чтобы посмотреть изменения, затем вapply, чтобы записать их.checkзапускает валидаторы для выбранного вида узла.docsищет по документации 1С. Список операций узла находится в полеcanответаview {at}. Аргументы конкретной операции описаны по адресу<узел>.Can.<операция>.searchищет код и метаданные.runзапускает операции. Если вызов вернулtaskId, запросите результат черезtask.resultс этим идентификатором.
В учебном проекте «Калькулятор цены» вы найдёте
объявление BSL-функции и её вызов, добавите пояснение на форму и соберёте
расширение в .cfe. Для прохождения урока скачайте или клонируйте ветку main:
в ней находятся исходники проекта и готовые запросы.
Что полезно знать при работе
cwdбольше нет. Адрес узла передаётся вat, рабочее пространство берётся из сессии.applyбез токена ничего не пишет. Это и есть dry run по умолчанию.- Первый вызов движка требует сети и заметно дольше остальных.
- Первый
checkпосле старта сервера прогревает индекс и может ответить «BSL analysis did not complete … Repeat the call» — повторите, это не дефект. *.validateне существует. Валидация — черезcheck.- Права шире песочницы нужны для правки исходников 1С вне рабочего каталога.
Как это работает
Порт не форкает Unica. Навыки и справочники — копия апстрима, а единственное семантическое изменение — имена инструментов.
Unica называет инструменты с точками (unica.view). Мост публикует их под теми
же именами, что раньше давала MCP-строка: mcp__unica__<имя>, а при потере
информации в нормализации дописывает 12 hex-символов SHA-256 от
"unica\0<raw name>":
unica.view -> mcp__unica__unica_view_6f3a42290cc8
Формула воспроизведена в host/lib/naming.js и покрыта тестом: все 11 имён
совпадают с прежней MCP-строкой бит в бит. Карта соответствия — tool-map.json,
переписывание — tools/build-skills.mjs (679 ссылок в 52 файлах). Навык,
упомянувший имя вне карты, валит генерацию.
Каталог на каждый вызов. У инструмента есть execute(args, exec), и exec
несёт агента: мост спрашивает у ctx.workingDirectory.ensure(exec.agent) текущий
каталог сессии и берёт процесс unica из пула по этому каталогу. Процесс
стартует лениво, живёт idleMs и вытесняется по LRU; смена каталога в сессии
сама переключает проект — перезапуск DSH не нужен.
Слой запуска — свой, на Node (bootstrap/launch.mjs). С 0.13 манифест
описывает не один архив, а артефакты: ядро и движки, которые Unica берёт
извне — bsl-analyzer, rlm-tools-bsl, v8-runner. Лаунчер ставит каждый в
стандартную раскладку кэша
<cache>/<artifact>/<version>--<asset sha256>/<target>/
сверяет SHA-256 скачанного ассета, распаковывает во временный каталог, пишет
маркер .ready.json и только потом переименовывает каталог в место. Затем
передаёт управление серверу. Порт по-прежнему не поставляет исполняемых файлов:
всё скачивается в кэш при первом запуске, поэтому лицензии движков (AGPL у
v8-runner, LGPL у bsl-analyzer) не превращаются в обязательства
распространения.
Раскладку нельзя угадать. Unica ищет движки не рядом с собой, а в кэше
артефактов, и узнаёт о нём из UNICA_ARTIFACT_CACHE — лаунчер выставляет её
серверу. Без переменной любой вызов, которому нужен движок, отвечает
bundled_tool_missing и указывает на <runtime>/bin/win-x64/v8-runner, куда
ничего класть не надо. Манифест не пишется руками: node tools/build-runtime-manifest.mjs собирает его из third-party/tools.lock.json
(проверка на устаревание — --check).
Релей ответов. Лаунчер не отдаёт stdio сервера напрямую: он построчно читает
tools/call-ответы и, если успешный ответ пришёл с пустым content и полезной
нагрузкой только в structuredContent, подставляет её одним текстовым блоком.
Иначе DSH — он проецирует модели только content — показывает
(unica.view returned no model-visible content) и не пускает в кадр ни
executionToken, ни can-словарь узла, ни next-подсказки, ни taskId. Ошибки
Unica и так дублирует текст, поэтому до правки ломались ровно успешные вызовы.
structuredContent остаётся нетронутым, ответы с собственным текстом проходят
байт в байт.
| Переменная | Смысл |
|---|---|
UNICA_BRIDGE_TEXT_FALLBACK=0 |
отключить релей, вернуть сырой stdio |
UNICA_WORKSPACE_ROOT=<путь> |
лаунчер: закрепить каталог при ручном запуске (мост его не использует) |
UNICA_ARTIFACT_DELIVERY=background|eager|off |
докачка движков: за сервером (по умолчанию), до старта, или никогда |
UNICA_LAUNCH_SELFTEST_COMMAND=<json argv> |
тестовый хук: подменить рантайм |
По умолчанию лаунчер запускает ядро и в фоне скачивает отсутствующие в кэше
движки в порядке v8-runner, bsl-analyzer, rlm-tools-bsl. Если инструмент
сообщил, что нужный движок ещё недоступен, дождитесь строки
unica launcher: <engine> delivered в журнале сервера и повторите вызов.
Почему пина больше нет. Прежняя MCP-строка поднимала один сервер на профиль,
и unica фиксировала каталог при старте — приходилось выбирать проект и
перезапускать DSH. Нативный мост решает это иначе: процессами владеет плагин,
каталог приходит из сессии на каждом вызове. Переменная UNICA_WORKSPACE_ROOT
осталась только у лаунчера — для ручного запуска и тестов
(node tools/verify-bridge.mjs, режим --fake без сети; живые движки
включаются UNICA_TEST_ENGINES=1 и UNICA_TEST_WORKSPACE=<проект>).
Структура
dsh-unica-plugin/
install.mjs установщик: профили, патчи, самопроверка
host/ нативный мост: пул процессов, имена, рендер, selftest
bootstrap/launch.mjs лаунчер: скачивает и запускает unica
runtime-manifest.json дескрипторы рантайма на три цели
tool-map.json 11 инструментов: raw -> публичное имя DSH
skills/ 50 навыков unica-*
references/ 46 справочников
tools/ генератор навыков и проверки
examples/price-extension/ учебный проект 1С и запросы Unica
examples/verify-price-extension.mjs проверка урока на временной копии
ci/ проверка минимальной версии DSH и обновления из релиза
install.sh / install.ps1 установка одной командой
.github/workflows/ задания GitHub Actions
Проверки
Из корня репозитория с Node.js 24 или новее:
node examples/verify-price-extension.mjs
Эту команду запускает задание price-extension на Ubuntu и Windows. На временной
копии проекта оно находит объявление и вызов BSL-функции, сверяет исходник формы
после предпросмотра, применяет правку по токену и запускает валидаторы form
и cfe. Для такой проверки достаточно ядра Unica. Чтобы дополнительно собрать
файл расширения и сверить его SHA-256, запустите ту же команду с --build на
машине с v8-runner и платформой 1С с ibcmd.
Проверки самого плагина:
cd dsh-unica-plugin
node tools/check-refs.mjs . # ссылки навыков на справочники
node tools/check-encoding.mjs skills references
node tools/check-tool-names.mjs # все имена инструментов резолвятся
node tools/build-runtime-manifest.mjs --check # манифест артефактов не отстал от лока
node tools/verify-bridge.mjs # лаунчер: релей ответов и защита доставки
node tools/ci-dryrun.mjs # эмуляция CI-прогонов
node host/selftest.js --cwd . # сквозная проверка моста без DSH
Как проверять живой режим в DSH (две сессии, две кодовые базы) — см. инструкцию проверки.
В CI задание minimum-dsh устанавливает DSH 0.2.2-rc.1, создаёт агента и
вызывает зарегистрированный unica.view через нативный исполнитель DSH.
Тестовый MCP-сервер возвращает фактический каталог процесса. Проверка сверяет
его с рабочим каталогом сессии. Для локального запуска укажите каталог установки
npm в DSH_INSTALL_ROOT и выполните node ci/minimum-dsh.mjs из корня репозитория.
Проверка обновления между опубликованными релизами
В GitHub Actions выберите Published release upgrade → Run workflow и задайте
два тега: from_tag — установленная версия, to_tag — версия обновления.
Вариант для GitHub CLI:
gh workflow run published-upgrade.yml --ref main -f from_tag=v0.15.0.5 -f to_tag=v0.15.0.6
Ubuntu и Windows скачивают архивы с GitHub Releases, сверяют SHA-256 и
проверяют сохранность пользовательских настроек Web-профиля. Сценарий вызывает
ошибку самопроверки после записи нового профиля, сравнивает восстановленные файлы
и профиль с исходными, проверяет запуск старого ядра и повторяет обновление.
Целевой релиз должен поддерживать откат (с v0.15.0.5). Начиная с v0.15.0.6
на установленном плагине также запускаются тесты closeAll() из целевого тега.
Обновление порта на новый апстрим
- Прочитать changelog апстрима и проверить, что он публикует архивы рантайма
под
darwin-arm64,linux-x64,win-x64— без них порт не соберётся. - Склонировать апстрим и посмотреть, что стало с навыками и справочниками.
- Обновить
runtime-manifest.jsonиз релизных дескрипторов. - Пересчитать
tool-map.jsonпо живомуtools/list(формула выше). UNICA_UPSTREAM_PLUGIN=<путь> node tools/build-skills.mjs— перегенерировать навыки; генератор упадёт, если появятся неизвестные имена инструментов.- Перечитать правила в персоне (
install.mjs) — они описывают контракт инструментов и устаревают вместе с ним. - Прогнать
--verifyи проверки, пересобрать архив, выпустить релиз.
Перенос на другую машину
curl -fsSL https://raw.githubusercontent.com/malinovme/dsh-unica/main/install.sh | sh
Либо скопировать каталог и поставить из него: node install.mjs --target both --verify. Абсолютные пути в файлах плагина не хранятся.
Удаление
rm -rf ~/.local/share/unica-plugin # macOS / Linux
rm -rf "${DSH_HOME:-$HOME/.dsh}/unica" # кэш рантайма и состояние демона
и удалить строки порта из cordis.patch.yml нужного профиля: preset-unica-1c
в пресетном, unica-native и skill-filesystem-unica — в остальных.
Известные ограничения
- Windows x64. CI проверяет установщик PowerShell и учебный проект на настоящем
ядре Unica. Установка и работа в DSH Desktop описаны в проверке нативного
режима. Платформенные операции (
infobase.create,make,launch, Vanessa) проверялись на 1С 8.3.27.2325 и Unica 0.15.0-rc.1. - macOS: проверен целиком, но только arm64. DSH Desktop 0.2.2-rc.1, платформа
8.3.27.2342: метаданные, формы, СКД, расширения, роли,
make,push,download,infobase.create,extensions.list. Intel-маки апстрим не покрывает. - Linux x64. На Ubuntu CI проверяет установку, нативный мост на минимальной
версии DSH и учебный проект. Проверка сборки
.cfeна Linux требует отдельного запуска с установленной платформой 1С. - Справочники апстрима упоминают десять имён инструментов 0.12 в спеках форм и DSL. Это документация, а не инструкции; порт её не переписывает, чтобы не выдавать догадку за текст апстрима.
- Пресет не виден в списке — почти всегда значит, что мост не поднялся.
Запустите
node install.mjs --verify: он назовёт причину, а при отказе каталога перенесёт кэш сам.
Лицензии
Код порта — LGPL-3.0-or-later, см. LICENSE. Навыки и
справочники — из Unica под той же лицензией; авторы и сторонние компоненты
перечислены в dsh-unica-plugin/ATTRIBUTIONS.md
и dsh-unica-plugin/LICENSE. Порт не распространяет
сторонние бинарники: рантайм и движки скачиваются на машине пользователя.
Ссылки
- Unica — апстрим, документация и changelog.
- README плагина — установка, Архитектура, проверки.
No comments yet. Be the first to write one.