Agentic HIL

Agentic HIL

让 AI 连接现实。

让你的 Agent 自主开发、测试并改进固件，在真实世界中完成这一切。Agentic HIL 通过设置严格的安全边界并在真实硬件上验证结果，构建起一道强制关卡。

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

观看 Agent 创建全新的固件项目、编写固件，并在安装和重启一次后让开发板输出 Hello World。录制内容展示了通过关卡获得的真实硬件反馈。Agent 会保存测试计划，并分别使用正确和刻意设置错误的预期运行测试。你会获得测试计划、报告，以及测试能够通过和失败的证据。运行结束时，租约已释放、安全状态已确认，没有任何内容被隔离。

开始使用

只需一条命令，即可为当前用户安装 Agentic HIL。无需管理员权限。

Linux / macOS（任意 shell）：

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

Windows，在 PowerShell 中运行：

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

安装程序会为它在 PATH 中找到的所有受支持的 Agent CLI 注册技能和 MCP 服务。安装内容会保存在仓库之外。重启 Agent 一次，然后提出你的第一个硬件问题。你的 Agent 会通过 MCP 配置项目的测试台。

如果找不到 claude、codex 或 opencode CLI，安装程序会提示下一步操作。安装 Agent CLI 后，运行 agentic-hil agent-install --agent <claude-code|codex|opencode> 进行注册。

安装程序会询问包管理器用户级 bin 目录的位置，并在需要时将该目录添加到 shell 启动文件或 Windows 用户级 Path。打开新的 shell 即可使用该命令。使用 --no-path（在 PowerShell 中使用 -NoPath）即可自行管理此更改；安装程序会打印需要添加的行。

全新安装会从 PyPI 安装 agentic-hil[can]。使用 --version <x.y.z> 固定版本。重新运行安装程序可以修复现有安装：报告 .devN 版本的可编辑检出会保留，而从路径、URL 或 git 引用安装的 uv 工具会根据记录的来源刷新。若要在运行前检查并验证安装程序，请按照安装说明中的校验和流程操作：从同一发行版下载脚本及其校验和，检查文件，然后运行该文件。

如需体验引导式首次运行，请试试 STM32 入门项目。其中包含固件、测试计划和一个预置缺陷，可在 Nucleo-F446RE 上通过三个步骤完成演练。

Claude Code 也可以通过插件市场安装技能： /plugin marketplace add agentic-hil/agentic-hil，然后运行 /plugin install agentic-hil@agentic-hil。 上面的安装命令仍会提供并注册 MCP 服务，使用经验证的绝对可执行文件路径，且安装位置在仓库之外。

请参阅安装说明，了解 cmd.exe、注册单个 Agent、使用自己的包管理器、设置已连接的测试台、可选组件和升级。agentic-hil upgrade 失败时，也可以使用相同的安装程序命令修复安装。故障排除介绍了启动问题。

在此仓库的克隆副本中，可先在没有开发板的情况下运行检查：

agentic-hil check-plan examples/nucleo-f446re_demo/testconfig.yaml

该命令会输出 All 1 test plan(s) load through the reactor's loader. 并以状态码 0 退出，不会加载测试台配置，也不会接触硬件。

让你的 Agent 完成闭环

你设定目标。你的 Agent 编写并构建固件。Agentic HIL 将固件烧录到开发板上，运行设备并依据测试标准检查其响应。测试失败时，Agent 会收到具体结果，可据此诊断问题、修改代码并重试。

Agentic HIL 提供硬件执行和反馈，让这一开发闭环成为可能。你在工作台上会进行的大部分烧录、测试和检查，都能纳入 Agent 的工作流。你可以一边审查代码，一边查看运行了什么、哪些通过、哪些失败，并将注意力集中在需求、设计决策和测试覆盖率上。

Agentic Hardware-in-the-Loop（Agentic HIL）通过 MCP 工具将编码 Agent 接入工作台，并通过 pytest 插件接入 CI 测试套件。Claude Code、Codex 和 OpenCode 均有相应的设置方式。

每项硬件操作都会返回结构化结果，其中包含操作结果、诊断信息以及报告和日志路径。你的 Agent 会获得可据以采取行动的反馈，你也可以根据记录的运行信息追溯结果。

将工作台接入闭环

Agentic HIL 通过后端连接调试探针：ST-Link 使用 OpenOCD 或 STM32CubeProgrammer CLI，CMSIS-DAP 调试探针使用 pyOCD。它还会通过 esptool 和 ESP32 设备的 USB-UART 桥烧录并重置 ESP32 目标设备，而无需打开调试会话。硬件支持取决于调试探针和后端。

通过 PCAN、SocketCAN 或自定义桥接器，在串行端口和 CAN 总线上发送命令并读取响应。多个运行可以通过代理共用一条 CAN 总线。

Agentic HIL 可在 Linux、macOS 和 Windows 上运行，需要 Python 3.10 或更高版本；CI 覆盖这三个平台。Nucleo-F446RE 示例将引导你在用于演示这一闭环的开发板上完成一次完整运行。有关后端和平台的详情，请参阅安装说明。

测试固件

用便于审查的 YAML 测试计划，写明设备应执行的操作。测试执行器会在接触硬件前验证计划，然后按你指定的顺序烧录、重置并运行设备。检查会将实际响应与精确值、模式或数值范围进行比较。设备符合预期时，检查即通过。

计划使用逻辑设备名称，工作台配置则将它们连接到实际硬件。在桌面和 CI 中使用同一份计划。步骤失败时，运行会停止；会话将被清理，并将已配置的恢复操作及其结果与测试结果一并记录。编写你的第一个硬件测试。

设置可靠的边界

你可以决定 Agent 能使用哪些设备和执行哪些操作。Agentic HIL 会在打开驱动程序前拒绝未声明的设备。它会强制执行权限、验证请求、应用超时，并记录操作情况。CLI、MCP 工具、pytest 插件和测试 reactor 都会经过同一道关卡。

权威配置位于工作区之外，Agent 自己的文件工具无法访问。请检查配置授予的权限。使用你自己的 shell 中的 agentic-hil revoke <key> 或 agentic-hil grant <key> 更改单项授权。通过 MCP，Agent 只能缩小自己的权限范围。只要 allow_raw_debugger_commands 或 allow_mass_erase 任一项处于启用状态，就会拒绝烧录。

设备租约可保护运行过程，避免受到机器上其他操作的干扰；SHA-256 审计链则让硬件记录具备防篡改能力。运行失败时，失败判定会保留，同时按配置执行恢复操作，以还原测试台并记录结果。若审计链损坏，测试台会保持锁定，直到操作员完成恢复，因为其他硬件测试无法重建缺失的证据。

阅读安全模型了解概述，并阅读安全设计了解完整说明。

在真实开发板上试用

从 Nucleo-F446RE 演示开始。连接开发板、构建固件，然后在示例目录中设置 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 会根据已连接的测试台检查配置，并在烧录前报告缺失的工具或硬件。如果你在设置完成后才连接开发板，agentic-hil adopt-hardware 会填写尚未设置的探针标识、后端可执行文件和 COM 设备。先使用 --dry-run 查看拟议的更改。如果主机安装了 OpenOCD，但未安装 STM32CubeProgrammer，则可通过主机的 USB 设备清单识别已连接的 ST-Link。如果连接了多个探针，可使用 --probe-id <serial> 选择其中一个。

运行示例的硬件测试计划：

agentic-hil test-reactor --test-config testconfig.yaml

该计划会烧录固件、打开串口、重置开发板，并检查启动输出中是否包含 Hello World。启动横幅缺失或不正确都会导致测试失败，并返回设备输出以供诊断。运行过程会关闭已打开的会话，包括步骤失败时打开的会话。

你的 Agent 可以通过相同的 MCP 工具执行这些步骤。在示例目录中运行 pytest tests/，将启动检查加入回归测试套件。示例指南介绍了这三种方式；硬件测试则展示了如何为自己的设备编写计划。

深入了解

接下来的步骤	阅读
安装、升级或添加 CAN、pyOCD 或 esptool 支持	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
查看平台支持和响应时间承诺	docs/support.md
诊断运行失败	TROUBLESHOOTING.md
为此项目设置 Agent	AI_AGENT_QUICKSTART.md 和 AGENTS.md

将 agentic-hil 用于软件包安装、CLI 命令、仓库 URL 和 MCP 服务名称。Python 导入、pytest 插件名称、夹具和 Python 示例使用 agentic_hil。

开发

要开发 Agentic HIL 本身：

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

发布版本通过 .github/workflows/workflow.yml 中的 GitHub trusted publishing 发布到 PyPI。请参阅 CONTRIBUTING.md 了解如何参与贡献。

安全

策略绕过行为会被视为漏洞；请参阅 SECURITY.md。

支持

Linux、macOS 和 Windows 获得同等支持。硬件支持取决于探针和后端：通过 OpenOCD 或 STM32CubeProgrammer 使用 ST-Link，通过 pyOCD 使用 CMSIS-DAP，以及通过 esptool 使用 ESP32 USB-UART 桥接器。

工作日内会在 24 小时内回复问题，安全报告则会在七天内回复。完整的支持范围和承诺请参阅支持政策。

可在讨论区 Q&A提问，在展示与分享分享运行结果，或提交你的首次运行报告，无论运行成功还是失败。

许可证

Apache-2.0。请参阅LICENSE。