Мост к агентам

Встроенная панель ассистента живёт внутри конструктора: вопрос задаётся в 1С, ответ приходит туда же. Мост открывает те же инструменты наружу — внешнему ИИ-агенту, который работает в вашем редакторе кода (Claude Code, Codex, Cursor и другие MCP-клиенты). Агент подключается к открытому сеансу 1С и видит вашу конфигурацию, вашу схему и ту форму, которую вы открыли на экране.

Из чего состоит мост

У моста две половины, и обе нужны.

Половина	Что делает	Где живёт
MCP-сервер	Говорит с агентом на его протоколе: отдаёт список инструментов и принимает вызовы	Отдельный процесс на Node.js, запускает его агент
Пульт моста	Держит канал к серверу, исполняет вызовы в вашем сеансе, ведёт журнал	Обработка `pw_Мост` в 1С

Вызов проходит так: агент отправляет вызов серверу, сервер кладёт его в очередь, 1С забирает вызов, исполняет в вашем сеансе и возвращает результат, сервер отдаёт его агенту. Ожидание висит на сервере, поэтому агенту устройство канала не видно — он работает с PrintWizard так же, как с любым другим MCP-сервером.

Что нужно на рабочем месте

Платформа 8.3.27 и выше — канал построен на WebSocket-клиенте платформы. Режим совместимости расширения при этом роли не играет.
Тонкий или толстый клиент на вашем компьютере. В веб-клиенте мост не работает.
Node.js — им запускается MCP-сервер. Если его нет, пульт скажет об этом и покажет команду установки под вашу операционную систему (winget install OpenJS.NodeJS.LTS, brew install node, sudo apt install nodejs npm) со ссылкой на страницу загрузки.
Библиотека стандартных подсистем — мост регистрируется её механизмом дополнительных отчётов и обработок.
Установленное расширение PrintWizard не ниже требуемой версии: мост зовёт его механизмы напрямую и без него не работает. Версию проверяет сама обработка, и при отказе БСП покажет текст администратору ещё при регистрации.

Публиковать базу на веб-сервере не нужно. Соединение открывает сама 1С, сервер слушает только 127.0.0.1, поэтому файловая база и тонкий клиент подключаются напрямую.

Установка моста

Мост поставляется отдельным файлом pw_Мост.epf — в состав расширения он не входит и обновляется независимо от него.

Откройте в программе список дополнительных отчётов и обработок и добавьте файл pw_Мост.epf. Вид обработки — «Дополнительная обработка», наименование — «PrintWizard: мост к ИИ-агентам».
У обработки одна команда — «Мост к ИИ-агентам», она открывает пульт.
Назначьте команду тем пользователям, кто работает с внешним агентом.

Безопасный режим у обработки снят намеренно: в безопасном режиме платформа не разрешает исходящее соединение, а канал к серверу — это оно и есть.

Отдельного выключателя у моста нет, и он не нужен: не зарегистрирована обработка — нет и моста, закрыт пульт — закрыт канал.

Пульт моста

Сверху — панель состояния: значок и строка, которая говорит, чего не хватает прямо сейчас, и содержит ссылки-действия — «подключите», «отключите», «установите», «проверьте». Пульт написан так, чтобы связку можно было собрать, не открывая документацию: он сам показывает следующий шаг.

Страница	Что на ней
Основная	Подключение — адрес сервера, токен и ключ соединения; окружение — Node.js, npx, MCP-сервер и команда установки
Настройка агента	Способ запуска сервера, каталог сервера, установка сервера, блок для `.mcp.json` и скилл агента
Сообщение	Отправка произвольного сообщения серверу — проверить канал руками
Журнал	Обмен: какой инструмент агент вызвал, с чем и что получил

Адрес сервера по умолчанию — ws://127.0.0.1:7787, ключ соединения — pw-mcp; токен пульт выдаёт сам при открытии, на сеанс.

В блоке «Окружение» видно не просто «есть или нет», а что именно нашлось: версии Node.js и npx, а у сервера — версия пакета и состояние канала (свободен, занят этим сеансом или другим сеансом 1С). Кнопка «Состояние» в командной панели и ссылка «проверьте» в подсказке делают одно и то же: опрашивают окружение заново.

MCP-сервер и блок для `.mcp.json`

Сервер едет внутри обработки одним собранным файлом, поэтому доступ к реестру пакетов не обязателен — это важно для закрытого контура. Кнопка «Установить сервер» на странице «Настройка агента» спрашивает каталог и кладёт туда файл printwizard-mcp.cjs, после чего пульт сам переключает «Запуск сервера» на «Из каталога» и пересобирает блок настроек.

Способов запуска два, и от выбора зависит только текст блока — сервер в обоих случаях один и тот же:

Способ	Что попадает в блок
Из каталога	`node` и путь к установленному файлу
Через npx	`npx -y @printwizard/mcp` — агент скачивает пакет из реестра сам

Блок выглядит так (порт и токен пульт подставляет свои):

{
  "mcpServers": {
    "printwizard": {
      "command": "node",
      "args": ["C:\\PrintWizard\\mcp\\printwizard-mcp.cjs"],
      "env": {
        "PRINTWIZARD_MCP_TOKEN": "...",
        "PRINTWIZARD_MCP_PORT": "7787"
      }
    }
  }
}

Перенесите блок в файл .mcp.json своего проекта — целиком или в существующий раздел mcpServers — и перезапустите агента. Ссылка «Сохранить в файл» отдаёт блок готовым файлом.

Если установленный файл разошёлся с тем, что приехал с мостом (обновили расширение или сам мост), пульт скажет об этом и предложит установить сервер заново; агента после этого нужно перезапустить.

Скилл агента

Скилл — правила работы с PrintWizard для агента: что инструменты только читают, в каком порядке их звать, как понять, что ответ неполон, и что означает каждый код отказа. Без него агент будет угадывать.

Наружу скилл выдаётся двумя путями, текст в обоих один:

файлом SKILL.md — ссылка «Сохраните» в блоке «Скилл агента» на странице «Настройка агента». Файл кладётся в каталог скиллов агента, у Claude Code это .claude/skills/printwizard. Такой скилл попадает в контекст агента сам, без вызова;
инструментом pw_bridge_skill — тот же текст агент получает вызовом. Этот путь всегда свежий: текст собирается в 1С в момент вызова, тогда как сохранённый файл может отстать от установленной версии.

Подключение

Порядок запуска произволен: можно сначала открыть пульт, можно сначала запустить агента. Пульт при открытии опрашивает окружение и поднимает канал сам; пока 1С не подключилась, агент получает от сервера внятный отказ с указанием, что сделать, а не молчание.

Связка собрана, когда в панели состояния написано, что агент работает с этим сеансом 1С. Две ситуации, на которых чаще всего останавливаются:

токен не совпал — сервер отклоняет подключение. Значит, агент запущен со старым токеном: перенесите блок настроек в .mcp.json заново и перезапустите агента;
канал занят другим сеансом 1С — один сервер обслуживает один сеанс, иначе агент не знал бы, с чьей базой говорит. Закройте пульт в том сеансе либо поднимите для этого сеанса свой сервер на другом порту.

Что видит и умеет агент

Список инструментов публикует 1С — сервер его не задаёт. Поэтому агент видит ровно то, что работает в этой конфигурации: инструменты зарплатно-кадрового блока, например, появляются только там, где есть механизм представлений.

Набор тот же, что у встроенной панели: инструменты ассистента — чтение и поиск по документации, поиск и состав объектов конфигурации, контекст открытой формы. Новых инструментов у моста нет, добавились только служебные:

Инструмент	Зачем
`pw_bridge_status`	Состояние связки: подключена ли 1С и что попросить у человека
`pw_bridge_tools`	Актуальный список инструментов подключённой 1С
`pw_bridge_call`	Вызов инструмента по имени из этого списка
`pw_bridge_fetch`	Дочитать крупный ответ кусками
`pw_bridge_skill`	Правила работы с PrintWizard

pw_bridge_tools и pw_bridge_call нужны не только для подстраховки. Список инструментов приезжает с борта 1С уже после того, как агент запустил сервер, и клиенты, которые не перечитывают его по уведомлению, инструментов PrintWizard просто не видят. Для таких клиентов эта пара — единственный рабочий путь: эти два инструмента сервер объявляет сразу и всегда. Если агент уверяет, что инструментов PrintWizard у него нет, попросите его начать с pw_bridge_status.

Ответ, который не помещается в контекст агента, не обрезается: приходит сводка со ссылкой на снимок, и агент дочитывает его сам.

Границы доступа

Это главное, что стоит знать до того, как включать мост.

Инструменты только читают. Ни один из них ничего не меняет — ни в базе, ни в схеме, ни в макете. Правки вы делаете руками в конструкторе.
Данные информационной базы наружу не уходят — инструменты дают метаданные, схему и документацию, но не содержимое таблиц.
Агент действует вашими правами. Канал живёт в вашем сеансе, отдельной роли у моста нет: что недоступно вам, недоступно и ему.
Сервер слушает только 127.0.0.1 и требует токен — подключение с другой машины невозможно, без токена сервер не пускает никого.
Канал живёт, пока открыт пульт. Закрытие формы разрывает соединение, и если в этот момент агент работает, пульт переспросит. Открытый пульт — и есть признак включённого моста.
Вызовы исполняются по очереди. Сеанс однопоточный: пока идёт печать или другая длительная операция, вызов ждёт, а не теряется.
Ответ уходит провайдеру модели агента. Это провайдер агента, а не PrintWizard: переписка идёт мимо 1С, и что в ней хранится, определяют настройки вашего агента. Про встроенную панель это описано отдельно — данные и приватность.

Журнал обмена

Журнал на одноимённой странице пульта показывает, что агент делал в вашей базе: время с миллисекундами, направление, вид события, инструмент, аргументы, результат, длительность и размер ответа. Свежая запись ложится наверх.

Уровень	Что сохраняется
Кратко	Умолчание: вид события, инструмент, исход, длительность и размер; текст результата ужат
Подробно	К краткому добавляются аргументы вызова и тело ответа — режим разбора полётов
Выключен	Записи не ведутся

Журнал живёт, пока открыт пульт, и держит не больше заданного числа строк («Максимум строк», по умолчанию 500); лишние отсекаются снизу. Кнопка «Очистить журнал» чистит его целиком.

Если агент не отвечает

Отказ приходит агенту кодом и подсказкой, что сделать; та же причина обычно видна и в панели состояния пульта.

Код	Что случилось
`NOT_READY`	1С не подключена к серверу либо порт занят чужой копией сервера
`BUSY`	Сеанс занят печатью или длинной операцией; вызов не потерян, он ждёт очереди
`CHANNEL_LOST`	Канал закрылся посреди вызова: закрыли пульт, перезапустили 1С
`BAD_REQUEST`	Вызов не по схеме: нет обязательного аргумента
`TOOL_UNKNOWN`	Такого инструмента нет — имя придумано
`TOOL_UNAVAILABLE`	Инструмент объявлен, но в этой конфигурации не работает
`NO_FORM`	Клиентский инструмент вызван, когда ни одна форма PrintWizard не открыта. Это предупреждение, а не сбой
`RESOURCE_GONE`	Снимок крупного ответа протух или сервер перезапускался — нужно повторить исходный вызов

Если агент говорит, что ничего не происходит, начните с журнала пульта: по нему видно, дошёл ли вызов до 1С.