Agentic HIL

Ваш AI-агент пишет прошивку, прошивает её в плату на вашем столе, взаимодействует с ней через UART и CAN, считывает обратно то, что фактически сделало оборудование, и исправляет допущенные ошибки; именно запуск на реальной плате решает, завершена ли работа, а вы проверяете pull request, в котором есть доказательства из этого запуска.

https://github.com/user-attachments/assets/8d39ba93-beeb-484e-b9e9-d9ce79538523

В этом запуске ничего не инсценировано. После одного перезапуска после строки установки, в только что созданном проекте прошивки, первая фраза заставляет агента самостоятельно настроить стенд, а вторая — заставить плату вывести Hello World и доказать, что она это сделала: конфигурация создаётся через MCP, а разрешения явно проговариваются, прошивка пишется на месте, flash_firmware и com_read проходят через шлюз, двенадцать байт возвращаются по линии, а план, который он закрепляет, запускается один раз успешно и один раз с заведомо неверным ожиданием, потому что тест, который не может упасть, ничего не доказывает. После этого в проекте остаются план в виде файла, пригодного для проверки, и собственный отчёт запуска: lease освобождён, безопасное состояние подтверждено, ничего не отправлено в карантин.

Install

Linux / macOS (любая оболочка):

curl -LsSf https://agentic-hil.github.io/install.sh | sh

Windows, в PowerShell:

irm https://agentic-hil.github.io/install.ps1 | iex

Команда попадает в пользовательский bin-каталог того менеджера пакетов, который её установил, и установщик спрашивает у этого менеджера, куда именно она попала, а не делает предположений: uv tool dir --bin для установки через uv и сам выбранный интерпретатор для установки через pip --user. Если этого каталога ещё нет в вашем PATH, установщик добавляет его туда и сообщает об этом: одной строкой в единственном профиле оболочки, который читает ваша оболочка, либо в Windows — каталогом перед вашим собственным Path. Откройте новую оболочку — и команда доступна. Передайте --no-path (-NoPath в PowerShell), чтобы внести это изменение самостоятельно; тогда установщик просто напечатает точную строку.

Одна строка устанавливает пакет в пользовательское окружение и регистрирует skill агента и MCP-сервер для каждого agent CLI, найденного в вашем PATH. Права администратора не требуются — никогда, и установщик ничего не трогает внутри каких-либо репозиториев. Если он не находит там CLI claude, codex или opencode, он сообщает об этом и ничего не пишет от имени какого-либо агента: установите agent CLI, затем выполните agentic-hil agent-install --agent самостоятельно — это строка, которую установщик печатает для такого случая. Затем один раз перезапустите агента, и после этого перезапуска ваш агент сам настроит этот проект при первом вопросе об оборудовании, который вы ему зададите.

Строка выше и маршрут с проверкой контрольной суммы в установке запускают один и тот же установщик, и на машине, где ещё ничего нет, оба устанавливают одно и то же — релиз из PyPI: скрипт разрешает agentic-hil[can] через индекс пакетов и вообще не несёт ссылки на ветку или git, а --version вместо этого закрепляет один конкретный релиз. При повторном запуске он ремонтирует уже установленное, а не принудительно заменяет его публичным релизом: установка с версией .devN (редактируемая копия этого репозитория) остаётся нетронутой, а инструмент под управлением uv, установленный из пути, URL или git-ссылки, обновляется из того же записанного источника, а не переключается на индекс. Что добавляет маршрут с проверкой контрольной суммы — сам скрипт, прочитанный до запуска: install.sh и его install.sh.sha256 приходят из одного релиза, один проверяется по другому, и запускается именно тот файл, который вы проверили.

Стартовый проект STM32 — самый короткий способ увидеть это на реальном оборудовании: три шага на Nucleo-F446RE, где прошивка, тестовые планы и один намеренно внесённый дефект уже на месте.

Claude Code также может взять skill из маркетплейса плагинов:

/plugin marketplace add agentic-hil/agentic-hil, затем /plugin install agentic-hil@agentic-hil.

Плагин несёт только skill и ничего больше; сам MCP-сервер по-прежнему появляется из строки установки выше, которая регистрирует проверенный абсолютный путь к исполняемому файлу вне вашего репозитория.

Установка описывает все остальные пути: вариант для cmd.exe, запуск восстановления (та же строка ещё раз, которая переустанавливает на месте, когда сам agentic-hil upgrade не срабатывает), тот маршрут с проверкой контрольной суммы полностью, регистрацию одного агента вместо всех сразу, работу с вашим собственным менеджером пакетов, setup для уже подключённого стенда, необязательные дополнения, обновление, а также все платформы и бэкенды отладчиков. TROUBLESHOOTING.md рассказывает, что делать, когда что-то не запускается.

Первая команда, которой не нужна плата, в клоне этого репозитория: agentic-hil check-plan examples/nucleo-f446re_demo/testconfig.yaml отвечает All 1 test plan(s) load through the reactor's loader. и завершается с кодом 0, не загрузив никакой конфигурации и не коснувшись оборудования.

Agentic Hardware-in-the-Loop (Agentic HIL) — это Python-пакет, который позволяет агенту для программирования разрабатывать прошивку на реальной плате. Он предоставляет ограниченные MCP-инструменты для зондирования, прошивки, сброса, валидации артефактов, подачи стимулов и получения обратной связи по serial и CAN, отчётов и логов — и всё это без предоставления агенту произвольного доступа к хосту или отладчику. Запуск на плате — это шлюз: работа завершена, когда оборудование повело себя как надо, а отчёт, который пишет этот запуск, — доказательство, которое читает проверяющий. Он поддерживает отладочный пробник с его бэкендом, а не конкретную плату: ST-Link через OpenOCD или CLI STM32CubeProgrammer и пробники CMSIS-DAP через pyOCD, поэтому любая плата за таким пробником запускает то же программное обеспечение. В каждом проекте есть ровно одна авторитетная конфигурация, хранящаяся вне репозитория, вне досягаемости собственных файловых инструментов агента.

Why

Успешной сборки недостаточно в разработке встраиваемых систем: прошивка должна корректно работать на реальной плате, поэтому запуск на этой плате — шлюз, который работа должна пройти, прежде чем считаться завершённой. Классические инструменты автоматизируют отдельные шаги (прошить здесь, прочитать лог там), но как только реальное оборудование должно отреагировать, человек снова оказывается в цикле — именно это не даёт агенту довести разработку прошивки до такого шлюза. Если же вместо этого дать агенту сырую оболочку отладчика или прямой доступ к serial, это небезопасно и невоспроизводимо, а проверяющему нечего читать.

Agentic HIL закрывает этот разрыв небольшим проверяемым шлюзом:

Каждое аппаратное действие проверяется по выбранной авторитетной конфигурации, выполняется с тайм-аутами, логируется в .agentic-hil/logs/ и возвращает структурированный JSON-результат (ok, error_type, summary, likely_causes, report_path, log_path), на который агент может реагировать, а проверяющий может прочитать позже. Что агенту вообще разрешено, определяется для каждого устройства и каждого разрешения; а попытка воспользоваться лазейкой отладчика — это то, что лишает его возможности прошивать.

What it drives

Единица, которой он управляет, — это пробник с его бэкендом, а не одна плата: три бэкенда отладчиков (OpenOCD, pyOCD и CLI STM32CubeProgrammer), плюс последовательные порты и CAN (PCAN, SocketCAN или пользовательский мост; несколько запусков могут использовать одну шину), на Linux, macOS и Windows, Python 3.10 или новее, всё протестировано в CI. Рабочий пример в examples/nucleo-f446re_demo/ прогоняет весь цикл на ST Nucleo-F446RE — плате, на которой этот репозиторий доказывает работоспособность пути, а не границе того, что вообще может работать; установка подробно описывает каждый бэкенд и платформу.

The test reactor

План — это то, как шлюз записывается, и один YAML-план управляет всем стендом: прошивка, сброс, запись, чтение с компаратором (точный текст, шаблон или числовой диапазон по захваченному значению), задержки и сессии, которые закрываются сами. Планы называют логические устройства; конфигурация стенда привязывает их к реальному оборудованию, поэтому один и тот же план без изменений выполняется на любой машине, где есть такое оборудование. Неудачный шаг прерывает запуск, а стенд восстанавливается сам: reap, сброс в halt, probe — всё это засвидетельствовано в результате запуска. Как работают планы.

Безопасность на уровне конструкции

Устройство не существует на этом стенде до тех пор, пока ваша конфигурация не объявит его, а вызов, называющий любое другое устройство, отклоняется до открытия драйвера: unknown_device — когда его объявляет запуск, и com_port_not_configured или can_bus_not_configured — когда его называет инструмент порта или шины; последние два при этом перечисляют те устройства, которые конфигурация всё же объявляет. На устройстве, которое она всё же объявляет, сгенерированная конфигурация выдаёт каждое разрешение, за которым стоит инструмент, и удерживает allow_raw_debugger_commands и allow_mass_erase в значении false — блокирующую пару, которая отказывает в прошивке, пока любое из них true. Эта пара по построению имеет значение false, когда MCP project_config_create генерирует конфигурацию без загруженной конфигурации, и именно такие значения по умолчанию записывает agentic-hil init, если ваш agentic-hil.config.example.yaml не открывает одну из них; project_config_create, перегенерирующий существующий стенд, вместо этого переносит загруженные разрешения обратно, включая любую из блокировок, с привязкой к имени записи, а не к тому, был ли ранее найден пробник, поэтому пара, открытая оператором для именованного заполнителя dut, переживает тот самый вызов, который впервые привязывает к нему пробник, и только логическая запись, имени которой не было в загруженной конфигурации, возвращается со значением false. agentic-hil revoke отзывает любое отдельное разрешение, а agentic-hil grant снова открывает его — из вашей собственной оболочки; через MCP агент сужает свои полномочия и никогда не расширяет их. Каждое аппаратное действие проходит валидацию, получает аренду в масштабе всей машины и записывается в цепочку аудита SHA-256. Авторитетная конфигурация находится вне рабочего пространства, где агент не может её редактировать. Принудительное применение намеренно находится в инструменте, а не в хосте агента: система разрешений хоста оценивает строки оболочки и различается от хоста к хосту, тогда как разрешения стенда оценивают само аппаратное действие и переносятся вместе со стендом, поэтому CLI, pytest, CI и test reactor проходят через одни и те же ворота. Неудачный запуск всё равно возвращает стенд: он прерывается со своим вердиктом, действие восстановления сбрасывает и повторно считывает цель, а постоянный карантин сохраняется для единственного состояния, которое ни один последующий контакт не сможет восстановить, — нарушенной цепочки аудита. Модель безопасности — это краткая версия, документ по проектированию безопасности — подробная.

Быстрый старт: один реальный запуск

Разобранный пример — это отдельный проект прошивки. Подключите плату, соберите проект и наведите Agentic HIL на него из этого каталога:

cd examples/nucleo-f446re_demo
cmake --preset Debug && cmake --build --preset Debug   # → build/Debug/nucleo-f446re_demo.elf
agentic-hil setup --agent claude-code                  # or: codex / opencode
agentic-hil doctor

doctor сверяет конфигурацию с подключённым стендом и называет то, что находит (отсутствующий toolchain, недоступный пробник, тип цели, который этот хост не может разрешить), прежде чем что-либо будет прошито. Если плата появилась после запуска setup, agentic-hil adopt-hardware заполняет серийный номер пробника, исполняемый файл бэкенда и COM-устройство, которые остались незаданными (--dry-run сначала показывает план). На хосте с OpenOCD и без STM32CubeProgrammer пробник определяется из собственного списка USB-устройств с серийными номерами хоста, поэтому единственный подключённый ST-Link привязывается без повторного ввода его серийного номера; --probe-id указывает плату, когда рядом с ней подключён второй пробник, не публикующий виртуальный COM-порт.

Когда MCP-хост запущен из этого каталога, агент выполняет четыре вызова:

flash_firmware     {"image_path": "build/Debug/nucleo-f446re_demo.elf"}
com_session_start  {"port_id": "dut_uart"}
reset_target       {"mode": "run"}
com_read           {"port_id": "dut_uart", "wait_timeout_s": 5}
→ feedback contains "Hello World"

Тот же цикл выполняется в headless-режиме как pytest-регрессия: pytest tests/ в этом каталоге прошивает ELF, сбрасывает цель и проверяет загрузочный баннер на UART. examples/nucleo-f446re_demo/ разбирает оба варианта, а docs/testing.md описывает, как вместо этого записать запуск в виде проверяемого YAML-плана.

Где искать подробности

Если вы хотите	Читайте
установить, обновить, добавить CAN или pyOCD либо найти команду	docs/installation.md
что объявляет авторитетная конфигурация и кто может её менять	docs/configuration.md
полный набор MCP-инструментов и то, как из него составляется запуск	docs/mcp-tools.md
зарегистрировать сервер в конкретном MCP-хосте	docs/mcp-hosts.md
писать аппаратные тесты (YAML-планы или pytest)	docs/testing.md
почему безопасно оставить агента наедине со стендом	docs/safety-model.md и docs/security-design.md
диагностировать сбой	TROUBLESHOOTING.md
направить вашего агента на этот репозиторий	AI_AGENT_QUICKSTART.md и AGENTS.md

Имена: дистрибутив/цель установки Python, команда CLI, URL репозитория и имя MCP-сервера используют agentic-hil. Импорты Python, имена плагинов pytest, фикстуры и примеры на Python используют agentic_hil.

Разработка

python -m pip install -e '.[dev]'
ruff check src tests evals tools
pytest
python -m build
twine check dist/*

Пакет настроен для публикации в PyPI через GitHub trusted publishing в .github/workflows/workflow.yml. Рекомендации по участию: CONTRIBUTING.md.

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

Обходы политики рассматриваются как уязвимости; см. SECURITY.md.

Поддержка

Linux, macOS и Windows поддерживаются одинаково; поддерживается отладочный пробник с соответствующим бэкендом (ST-Link через OpenOCD или CLI STM32CubeProgrammer, пробники CMSIS-DAP через pyOCD), а не какой-либо список плат. На обращения отвечают в течение 24 часов по рабочим дням, на отчёты о безопасности — в течение семи дней: docs/support.md — это всё обещание, включая то, что не обещается. Задавайте вопросы в Q&A в Discussions, показывайте запуск в Покажите и расскажите, а первый запуск на своём стенде — зелёный или красный — добавляйте в отчёт о первом запуске.

Лицензия

Apache-2.0. См. LICENSE.