内容
# AI-HIL
[](https://github.com/hp-8472/aihil/actions/workflows/ci.yml)
**AI-HIL 通过将实际硬件置于编码代理循环中，并使硬件测试可重复，加速嵌入式开发。**
> 适用于希望 Claude Code、Codex、opencode 或其他 MCP 能力代理探测、闪存、重置和读取真实板卡串行反馈的嵌入式工程师。
> 安全模型：AI-HIL 只暴露已配置的高级硬件动作。原始调试器命令、直接主机 COM 访问外部配置端口和大批量擦除默认情况下保持禁用。
它将固件工作转变为硬件循环：编辑、构建、探测、闪存、重置、读取日志、诊断、改进、重复。AI-HIL 是安全的 MCP stdio 控制层，允许代理通过配置工具而不是原始调试器或 COM 端口访问在真实板卡上运行和重复该循环。
## 快速开始
### 从 npm 安装用于固件项目
```bash
npm i -g aihil
cd /path/to/your/firmware-project
aihil init
aihil doctor
aihil mcp-config > .mcp.json
```
将 AI-HIL 添加到现有固件项目时使用此路径。每个项目都有自己的 `.aihil/config.yaml`，用于目标、调试器、工件根目录、权限、报告、日志和可选 COM 端口。如果设置失败，请从 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 开始。
### 运行支持的 Nucleo 演示
```bash
npm i -g aihil
git clone https://github.com/hp-8472/aihil.git
cd aihil/examples/nucleo-f446re_demo
aihil init
aihil doctor
aihil mcp-config > .mcp.json
```
从此存储库的本地克隆中，使用 `npm install --global .` 代替 `npm i -g aihil`。
演示文包括预先构建的首次运行 ELF，位于 `build/Debug/nucleo-f446re_demo.elf`，因此您可以验证硬件循环在安装 ARM 工具链之前。演示 `.aihil/config.yaml` 故意为本地机器状态创建。创建它并使用 `aihil init`，然后编辑仅限主机特定的字段，例如非 `PATH` OpenOCD 可执行文件或配置的 COM 端口。保持固件工件根目录为 `build/`。
## Windows 首次运行
Windows 受支持，但 OpenOCD 和 COM 设备名称通常需要显式本地配置。
如果 `aihil doctor` 报告 `debugger_not_found` 或 `openocd_not_found`，请在 `.aihil/config.yaml` 中设置 `debugger.executable` 为已安装的 OpenOCD 可执行文件：
```yaml
debugger:
type: "openocd"
executable: "C:/Program Files/OpenOCD/bin/openocd.exe"
interface_cfg: "interface/stlink.cfg"
target_cfg: "target/stm32f4x.cfg"
```
对于串行反馈，使用以下命令发现主机端口：
```bash
aihil com-ports
```
然后仅在 `com_ports` 下添加预期的设备，并使用其配置的 `port_id` 从 MCP COM 工具。对于例如，Windows 设备可能是 `COM5`，而 AI-HIL 端口 ID 是 `dut_uart`。不要通过直接串行工具绕过 AI-HIL 在代理工作流中。
有关设置失败，请参阅 [Windows 快速说明](TROUBLESHOOTING.md#windows-quick-notes)、[`openocd_not_found`](TROUBLESHOOTING.md#3-debugger_not_found--openocd_not_found) 和 [COM 端口故障排除](TROUBLESHOOTING.md#10-com-port-does-not-work)。
## 60 秒 Nucleo 循环
连接 USB/ST-LINK 和本地 `.aihil/config.yaml` 创建的 NUCLEO-F446RE：
```bash
aihil doctor
aihil mcp-config > .mcp.json
```
仅当您想要在本地重建演示固件时运行 `cmake --preset Debug` 和 `cmake --build --preset Debug`。
如果 OpenOCD 不在 `PATH` 中或需要串行反馈，请在运行 `aihil doctor` 之前编辑本地 `.aihil/config.yaml`。不要提交 demo 项目中的机器特定 `.aihil/` 文件。
在 `examples/nucleo-f446re_demo` 中打开 Claude Code、opencode、Codex 或另一个 MCP 能力编码代理，并询问：
```text
使用 AI-HIL 探测目标，闪存 build/Debug/nucleo-f446re_demo.elf，重置为运行模式，读取最后的报告，如果有可用的配置的 COM 端口，则读取它。
```
预期固件循环中的硬件路径：
```text
更改固件
构建固件
aihil_probe_target
aihil_flash_firmware
aihil_reset_target
aihil_get_last_report 和可选的 COM 读取
使用真实硬件反馈进行下一次固件补丁
重复
```
如果探测结果有 `ok: true` 和 `target_detected: true`，则 AI-HIL 可以看到板卡。如果闪存结果有 `ok: true`、`verify: true` 和 `reset_after_flash: true`，则第一个硬件循环成功。
## 演示资产
实际的演示 GIF 或视频应显示实际的 NUCLEO-F446RE 会话，而不是模拟的命令输出。使用 [`docs/demo/README.md`](docs/demo/README.md) 中的记录检查清单，然后添加捕获的资产：
```text
docs/demo/aihil-nucleo-loop.gif
docs/demo/aihil-nucleo-loop.mp4
docs/demo/thumbnail.png
```
录制后，在 README 标题下嵌入 GIF，以便首次访问者立即看到探测、闪存、重置、报告和可选的 COM 读取循环在真实硬件上。
## 可重复的硬件测试
AI-HIL 将每次硬件运行视为可重复的。本地 `.aihil/` 设置捕获目标、调试器、权限、允许的固件工件、报告和日志，以便下一个代理、开发人员或 CI 作业可以在相同的约束下检查相同的硬件循环测试。
当前，`.aihil/config.yaml` 包含可移植的项目选择和机器特定的值，例如 OpenOCD 可执行文件路径和 COM 设备。对于检查的示例，请保持 `.aihil/` 被忽略，并记录稳定值而不是提交主机特定的配置文件。
可重复性是其价值的一部分：通过结构化 JSON、原始 OpenOCD 日志、COM 日志、闪存的工件路径和项目配置，可以解释通过或失败的固件结果。
## 为什么它存在
AI 代理可以快速编辑固件，但嵌入式开发只有在代理可以在实际板卡上运行固件、从结果中学习并重复相同的测试时才会加速。AI-HIL 通过使真实硬件成为开发循环的一部分，同时保持硬件访问有界、配置、可重复和可审计，从而填补了这一空白。
## 受众
此 README 面向人类开发人员和硬件操作员。
面向代理的说明位于：
- [`AGENTS.md`](AGENTS.md)
- [`AI_AGENT_QUICKSTART.md`](AI_AGENT_QUICKSTART.md)
- [`skills/aihil-config-setup/SKILL.md`](skills/aihil-config-setup/SKILL.md)
故障排除位于 [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md)。
## 支持的首选路径
官方参考设置故意狭窄：
- 板卡：STM32 Nucleo-F446RE。
- 调试探测器：ST-Link，包括板载 Nucleo ST-Link。
- 调试后端：OpenOCD。
- 主机运行时：Node.js LTS 和 npm。
- OpenOCD 接口配置：`interface/stlink.cfg`。
- OpenOCD 目标配置：`target/stm32f4x.cfg`。
- 固件工件根目录：`build/`。
- 固件工件格式：`.elf`、`.hex` 或 `.bin`。
其他 OpenOCD 支持的板卡、探测器和目标可能在 `.aihil/config.yaml` 中表示，但支持的首选路径是文档、示例和问题再现的基线。
## 工作原理
```text
AI 代理编辑固件
-> 构建工件
AI-HIL MCP stdio
-> .aihil/config.yaml 策略
OpenOCD / ST-Link / 配置的 COM 端口
-> 真实目标板卡
AI-HIL 报告和日志
-> AI 代理改进固件
-> 重复
```
代理不会收到通用 OpenOCD shell。它会收到诸如 `aihil_probe_target`、`aihil_flash_firmware`、`aihil_reset_target` 和配置的 COM 端口工具等狭窄的工具。
## 安装
在本地机器上安装一次 `aihil` 命令：
```bash
npm i -g aihil
```
从此存储库克隆中，使用以下命令安装本地版本：
```bash
npm install --global .
```
用于本地 AI-HIL 开发：
```bash
npm install
npm test
```
AI-HIL 是一个 Node.js CLI。npm 包在安装期间构建 TypeScript，并在全局安装时将 `aihil` 可执行文件安装在 `PATH` 上。
## 分发
npm 是 AI-HIL 的主要分发渠道。该存储库是一个原生 Node.js CLI，带有 `package.json`、TypeScript 构建和用于 `aihil` 命令的包 `bin` 条目。
PyPI 故意不是主要目标。只有当 AI-HIL 为 Python-heavy 嵌入式团队增长出一个刻意的 Python 包装器时，才会发布 Python 包。
发布到 npm 时，请使用 GitHub Actions 和 OIDC 以及 npm 来源证明的受信任发布。这避免了存储库机密中的长期 npm 令牌，并记录了已发布的包的构建来源。
AI-HIL 是本地优先的，因为实际硬件访问依赖于主机 USB、ST-Link、OpenOCD 和串行/COM 设备。通过 npm CLI 和 MCP stdio 保持首次运行路径在主机上。
后续包装候选人是 Homebrew、Scoop 或 WinGet，以及可选的单文件二进制文件。
## 每个项目设置
在固件项目目录中运行设置，而不是从 AI-HIL 源存储库：
```bash
aihil init
aihil doctor
aihil mcp-config > .mcp.json
```
每个固件项目都拥有自己的 `.aihil/` 目录。该目录包含本地目标配置、硬件权限、允许的工件根目录、报告、日志和上传的工件。将它视为本地机器状态，除非项目有共享清理的 AI-HIL 配置的明确策略。
对于支持的首选路径，请从 `aihil init` 开始，并设置重要字段如下：
```yaml
target:
name: "nucleo-f446re"
controller: "stm32f446re"
debugger:
type: "openocd"
executable: null
interface_cfg: "interface/stlink.cfg"
target_cfg: "target/stm32f4x.cfg"
timeout_s: 60
artifacts:
allowed_roots:
- "build"
upload_directory: ".aihil/artifacts"
allowed_extensions:
- ".elf"
- ".hex"
- ".bin"
max_upload_size_mb: 64
allow_upload: true
permissions:
allow_probe: true
allow_flash: true
allow_reset: true
allow_com_read: true
allow_com_write: true
allow_raw_debugger_commands: false
allow_mass_erase: false
```
仅当串行端口是项目设置的一部分时，才添加 `com_ports`。
## 预期输出
确切的路径、时间戳、OpenOCD 版本、经过的时间、COM 设备名称和 SHA-256 值将因机器而异。形状和关键字段应与这些示例匹配。
### `aihil doctor`
```json
{
"ok": true,
"tool": "aihil_doctor",
"summary": "AI-HIL 配置已加载，调试器已检查。",
"config_path": ".aihil/config.yaml",
"mcp": {
"transport": "stdio",
"command": "aihil",
"args": [
"mcp-stdio",
"--config",
".aihil/config.yaml"
]
},
"target": {
"name": "nucleo-f446re",
"controller": "stm32f446re"
},
"com_ports": {
"dut_uart": {
"device": "COM5",
"baudrate": 115200,
"encoding": "utf-8"
}
},
"debugger": {
"ok": true,
"tool": "aihil_debugger_info",
"backend": "openocd",
"executable": "C:/Program Files/OpenOCD/bin/openocd.exe",
"version": "Open On-Chip Debugger 0.12.0",
"summary": "OpenOCD is available."
}
}
```
如果没有配置串行端口，则 `com_ports` 为 `{}`。
### 成功探测报告
在代理调用 `aihil_probe_target` 后，MCP 工具结果和 `.aihil/reports/last-report.json` 应如下所示：
```json
{
"ok": true,
"tool": "aihil_probe_target",
"backend": "openocd",
"started_at": "2026-06-26T10:14:23.121Z",
"finished_at": "2026-06-26T10:14:24.088Z",
"elapsed_ms": 967,
"summary": "Target detected through OpenOCD.",
"log_path": ".aihil/logs/openocd-20260626T101423121Z-aihil_probe_target.log",
"success_confirmed": true,
"target_detected": true,
"report_path": ".aihil/reports/last-report.json"
}
```
### 成功闪存报告
在代理调用 `aihil_flash_firmware` 并 `image_path: "build/firmware.elf"` 后，成功报告应如下所示：
```json
{
"ok": true,
"tool": "aihil_flash_firmware",
"backend": "openocd",
"started_at": "2026-06-26T15:02:42.442Z",
"finished_at": "2026-06-26T15:06:06.659Z",
"elapsed_ms": 4217,
"summary": "Firmware flashed, verified, and target reset.",
"log_path": ".aihil/logs/openocd-20260626T150242442Z-aihil_flash_firmware.log",
"success_confirmed": true,
"artifact": {
"source": "path",
"path": "build/firmware.elf",
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
"verify": true,
"reset_after_flash": true,
"report_path": ".aihil/reports/last-report.json"
}
```
对于失败，请检查 `ok`、`error_type`、`backend_error_type`、`summary`、`likely_causes`、`report_path` 和 `log_path` 在更改配置或固件之前。
### `aihil_get_last_report`
`aihil_get_last_report` 包装 `.aihil/reports/last-report.json` 中最新的报告：
```json
{
"ok": true,
"tool": "aihil_get_last_report",
"report": {
"ok": true,
"tool": "aihil_flash_firmware",
"backend": "openocd",
"summary": "Firmware flashed, verified, and target reset.",
"artifact": {
"source": "path",
"path": "build/Debug/nucleo-f446re_demo.elf",
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
"verify": true,
"reset_after_flash": true,
"report_path": ".aihil/reports/last-report.json",
"log_path": ".aihil/logs/openocd-20260626T150242442Z-aihil_flash_firmware.log"
}
}
```
如果尚未写入报告，则结果为：
```json
{
"ok": false,
"tool": "aihil_get_last_report",
"error_type": "report_not_found",
"summary": "No AI-HIL report has been written yet."
}
```
### `aihil_classify_last_error`
失败的硬件操作后，`aihil_classify_last_error` 返回来自最新报告的紧凑诊断：
```json
{
"ok": true,
"tool": "aihil_classify_last_error",
"error_type": "target_not_detected",
"backend_error_type": "target_not_detected",
"summary": "OpenOCD could not detect the target.",
"likely_causes": [
"target board is not powered",
"debug probe is disconnected or already in use",
"wrong OpenOCD interface or target config",
"SWD/JTAG wiring or boot-mode issue"
],
"report_path": ".aihil/reports/last-report.json",
"log_path": ".aihil/logs/openocd-20260626T101423121Z-aihil_probe_target.log"
}
```
### MCP 客户端配置
AI-HIL 使用 stdio 上的 MCP。生成项目本地的 MCP 发现配置：
```bash
aihil mcp-config > .mcp.json
```
示例 `.mcp.json`:
```json
{
"mcpServers": {
"aihil": {
"command": "aihil",
"args": [
"mcp-stdio",
"--config",
".aihil/config.yaml"
]
}
}
}
```
### 纯 COM 文本 Stdio
使用 MCP COM 工具进行正常的代理工作流。如果显式需要单独的纯文本串行通道，请启动：
```bash
aihil com-stdio --config .aihil/config.yaml --port dut_uart
```
`com-stdio` 不是 MCP。它将一个纯文本流绑定到一个配置的 COM 端口。不要将 COM 文本混入 `mcp-stdio`；MCP 标准输出必须仅为 JSON-RPC。
## 安全模型
AI-HIL 的安全边界是项目本地的 `.aihil/config.yaml` 文件。
默认模型是：
- 探测、闪存、重置和 COM 操作需要显式权限。
- 不暴露原始调试器命令。
- 默认情况下禁用大批量擦除。
- 固件路径必须位于配置的工件根目录下。
- COM 访问仅限于命名的 `com_ports` 条目。
- 每个硬件操作返回结构化 JSON 并为人类检查编写原始日志。
## 存储库布局
```text
.
|-- AGENTS.md
|-- AI_AGENT_QUICKSTART.md
|-- CLAUDE.md
|-- README.md
|-- TROUBLESHOOTING.md
|-- skills/
|-- src/aihil/
|-- tests-ts/
`-- package.json
```
## 代理入口点
如果您希望 AI 编码代理设置固件项目并使用 AI-HIL，请打开固件项目并说：
```text
安装 https://github.com/hp-8472/aihil 并将其用于此固件项目。
```
代理应安装 `aihil`，返回到固件项目，并遵循 `AGENTS.md`、`AI_AGENT_QUICKSTART.md` 和 `skills/aihil-config-setup/SKILL.md`。除非您明确要求，否则它不应将 AI-HIL 源代码树插入固件项目。
## 许可证
Copyright 2026 Hannes Pauli.
本项目使用 Apache License 2.0 许可。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器