Перейти к основному содержимому

Интеграция AI-агента

С 2.3.0 в MultiProg встроен IPC-мост, через который внешний AI-агент (Claude, Cursor, GLM, opencode или любой MCP-клиент) может управлять тем же Lua-движком, который крутит in-app Script Console. Агент кладёт файл-запрос в папку, MultiProg выполняет Lua и пишет файл-результат — всё в плоских JSON-файлах, без сокетов.

Это тот же mp.* API, что доступен в Script Console (см. Scripting) — программирование, hex-буфер, файлы, база таргетов, контрольные суммы.

Settings > AI Agent Integration

Диалог Settings → AI Agent Integration с тумблером Enable, путём к IPC-папке, строкой Auth token (Show / Copy / Regenerate) и кнопкой Copy starter prompt for external agent.

Где включается​

Settings → AI Agent Integration открывает диалог настройки. Всё необходимое — там.

Диалог настроек​

  • Enable Agent IPC bridge — главный тумблер. Если выключен, файлы-запросы в папке игнорируются.
  • IPC folder — папка, за которой следит MultiProg. По умолчанию — под пользовательским профилем; кнопки Browse…, Open folder и Copy path позволяют быстро направить агента в нужное место.
  • Auth token — 64-символьный hex-токен на пользователя, обязательный в каждом запросе. Кнопки: Show / Hide, Copy, Regenerate. Регенерация отзывает любого клиента, который ещё держит старое значение.
  • Copy starter prompt for external agent — генерирует готовый брифинг (пути, auth-токен, точки входа в протокол) и копирует в буфер обмена. Вставляете в агента, дописываете задачу, отправляете.
  • Apply / Close — Apply переконфигурирует runner налету; перезапуск не нужен.

Токен лежит по пути %APPDATA%/KuragaTech/MultiProg/agent_token (NTFS DACL — только текущий пользователь). Обращайтесь с ним как с session secret — не коммитьте в исходники, не отдавайте обратно в ответах агента.

CLI-флаги и переменные окружения​

Есть два способа форс-включить мост снаружи GUI:

  • --agent-mode — флаг командной строки. Стартует MultiProg с включённым мостом на дефолтном пути IPC и с заблокированными по умолчанию деструктивными backend-операциями (write / erase / flash). Скрипту, которому нужно писать в железо, придётся явно разрешить через mp.app.allow_hw_writes(true). В --agent-mode диалог блокирует все контролы (показывает read-only баннер).
  • MULTIPROG_AGENT_IPC_DIR — переменная окружения. Перекрывает путь к IPC-папке. Удобно для CI-пайплайнов. Поле пути в диалоге блокируется и показывает активное значение.

Приоритет переопределений (высший → низший):

--agent-mode  >  MULTIPROG_AGENT_IPC_DIR  >  сохранённые настройки

Что появляется в IPC-папке​

Когда мост работает, MultiProg сам наполняет папку:

ФайлНаправлениеНазначение
AGENT_README.mdMP → агентГлавный справочник по протоколу. Перегенерируется при каждом запуске. Читать первым.
agent_request.jsonагент → MPСледующий запрос к выполнению. Записать .tmp, затем переименовать — атомарная доставка.
agent_result.jsonMP → агентРезультат последнего запроса.
agent_stream.logMP → агентЛайв-стрим mp.log.* для длинных скриптов (читайте tail'ом).
agent_tokenобщий секретPer-user 64-hex auth-токен. Лежит в %APPDATA%/KuragaTech/MultiProg/, не в IPC-папке.
session.lockслужебныйЗащищает от гонки двух MultiProg на одной IPC-папке.

Быстрый старт​

  1. Открыть Settings → AI Agent Integration.
  2. Включить мост, выбрать (или принять) IPC-папку.
  3. Нажать Copy starter prompt for external agent.
  4. Вставить в AI-клиент (Claude Code, Cursor, opencode, GLM, любой MCP-агент), дописать задачу, отправить.

Стартовый prompt говорит агенту:

  • прочитать AGENT_README.md ради протокола;
  • сделать интроспекцию API запросом print(mp.utils.json_encode(mp.app.api_surface()));
  • всегда передавать auth в каждом запросе, включая cancel и op:"quit";
  • выставлять timeout_ms на каждом запросе (watchdog по умолчанию — 10 минут);
  • для длинных операций следить за agent_stream.log, не опрашивать result-файл;
  • избегать mp.ui.* модальных диалогов в автономном режиме.

Связь со Script Console​

  • Тот же Lua-движок, тот же mp.* API — всё, что можно сделать в Script Console, можно сделать через IPC.
  • Script Console крутит скрипты, которые вы печатаете в GUI; IPC-мост крутит скрипты, которые присылает агент в виде файлов.
  • В одно время выполняется только один скрипт. Если занят Console — IPC-запрос получит reason:"busy" и должен повторить; и наоборот.

Безопасность​

Граница доверия

Любой процесс с правом записи в IPC-папку может выполнять код от имени MultiProg. Выбирайте путь, который контролируете только вы. 64-символьный auth-токен аутентифицирует протокол, но реальная граница доверия — права на запись в папку: как только request-файл лёг, MultiProg прочитает поле auth и примет запрос, если оно совпадёт.

  • Auth-токен лежит под %APPDATA%, где NTFS DACL ограничивает доступ только вашим пользователем.
  • --agent-mode по умолчанию блокирует деструктивные операции; чтобы прошить железо, скрипт должен явно вызвать mp.app.allow_hw_writes(true).
  • Операция Erase всегда требует подтверждения пользователя. mp.backend.erase и mp.backend.erase_blocks поднимают синхронный модальный диалог подтверждения в GUI на каждый вызов («Script requested mp.backend.erase() on target XXX — Allow this erase?»), даже после mp.app.allow_hw_writes(true) и даже вне --agent-mode. Флага-обхода нет. Erase стирает калибровку / серийники / pairing-данные, которых может не быть в вашем HEX, поэтому требуется человек у клавиатуры. Диалог блокирует запрос до ответа пользователя; отмена возвращает {false, "erase canceled by user"}. В момент появления диалога мост пишет [QT-WARN] mp.backend.<op>: GUI confirmation modal raised — … в agent_stream.log, чтобы агент, читающий лог tail'ом, видел причину «зависания». Закладывайте человека в IPC-флоу либо обходитесь без erase.
  • Стандартные Lua os.* и io.* в движке песочничены — для работы с файловой системой и процессами используется mp.file.*, mp.app.list_dir, mp.app.run_process.
  • Отмена: отправьте { "id": <next>, "auth": "<token>", "cancel": true } — остановит выполняющийся скрипт.
  • Завершение: { "id": <next>, "auth": "<token>", "op": "quit" } — попросит MultiProg корректно завершиться. Мост напишет последний result-файл (reason: "quitting"), потом приложение закрывается.

Полный протокол​

Полный формат запроса/ответа, все значения reason, модель «buffer vs device», дисциплина автономного режима, семантика cancel, streaming и угловые случаи — в файле AGENT_README.md, который MultiProg кладёт в IPC-папку при каждом запуске. Это главный справочник; начинайте оттуда, если пишете клиент.

Сам Lua API — в разделе Scripting и справочнике API.