FirmwareLoop

面向 AI Agent 的固件开发与实验室自动化平台（开源版）。 目标不是"AI 帮工程师写代码"，而是让 AI 基于真实硬件产生的观测数据参与开发、调试、测试与回归验证。

FirmwareLoop 把固件工程的完整闭环交给 AI Agent 编排：理解工程 → 修改 → 编译 → 烧录 → 复位 → UART/CAN/Debug → 逻辑分析仪/示波器测量 → 自动测试 → PASS/FAIL → 失败分析 → 再修改 → 重新验证。

核心原则：优先复用现成开源/官方能力，不构建大而全的自研 Firmware Lab MCP。所有工具是薄适配层，任何环节失败都返回结构化 JSON + 统一 Error Class（BUILD_ERROR / SAFETY_LIMIT / TARGET_MISMATCH …），证据自动落盘——判定功能正确必须同时有 Build Evidence + Runtime Evidence + Measurement Evidence + Assertion，禁止只看 exit code == 0。

---

架构

┌────────────────────────────────────────────┐
│               AI Agent (Qoder / CLI)       │
│  Code / Planning / Diagnosis / Orchestration│
└────────────────────┬───────────────────────┘
         ┌───────────┼───────────────┐
         ▼           ▼               ▼
     Shell/CLI      MCP           pytest
         │           │               │
         ▼   ┌───────┴──────┐       ▼
       tools/  Agentic HIL  Saleae  HIL 测试
         │     │            │
         ▼     ▼            ▼
   Build  Flash UART CAN    Logic
   Adapter Reset Debug      Analyzer
         │
         └─────────┬───────────────┐
                   ▼               ▼
                  DUT         PyVISA / SCPI
                               Scope / PSU / DMM / AWG

细节见 AI_DEV_GUIDE.md（Agent 强制规则，设计约束由此衍生；原始内部需求文档不随仓库发布）。

---

双层 MCP 架构与接入模式

FirmwareLoop 提供开箱即用的双层 MCP 架构：

1. 上层工作流 MCP (fwloop / firmwareloop)：面向工程构建（Keil/CMake/Make 等 7 大后端）、pytest 12项自动化 HIL 测试、安全测量与全链路验收。
2. 下层硬件驱动 MCP (agentic-hil)：面向物理探针（ST-LINK / J-Link）、JTAG/SWD 固件刷写、芯片复位、串口会话与符号级断点调试。

接入模式一：电脑全局安装（首选推荐，一次安装，所有工程通用）

用户只需在终端执行以下命令，即可将 fwloop 与 agentic-hil 安装为系统全局工具：

# 1. 全局安装 CLI 工具到系统
uv tool install git+https://github.com/Jeffrey1799/FirmwareLoop.git
uv tool install agentic-hil

# 2. 全局注册到各大 Agent（一次配置，所有单片机项目直接使用）
# Claude Code CLI (全局级):
claude mcp add --scope user fwloop -- fwloop
claude mcp add --scope user agentic-hil -- agentic-hil mcp-stdio

# Qoder IDE 接入（支持以下两种官方方式）：
#   方式 A (GUI): 按快捷键 Ctrl+Shift+,（Mac: Cmd+Shift+,）-> 进入「MCP」->「我的服务」-> 点击「+ 添加」粘贴配置
#   方式 B (工作区): 项目根目录放 .mcp.json，Qoder 会自动发现并加载
#   方式 C (CLI): qoder.cmd mcp add --global fwloop -- fwloop

效果：在电脑任意目录、任意 STM32 / Keil 独立工程下打开 Agent，Agent 均可直接调起 MCP，无需在每个工程中重复配置！

---

接入模式二：免克隆即时运行（零安装，按需从 GitHub 拉取）

如果不想全局安装，可直接配置 Agent 通过 uvx 临时拉取运行：

• Claude Code CLI 注册：

  claude mcp add fwloop -- uvx --from git+https://github.com/Jeffrey1799/FirmwareLoop.git fwloop
  claude mcp add agentic-hil -- uvx agentic-hil mcp-stdio
  

• Qoder / Cursor / Antigravity（在工程 .mcp.json 中配置）：

  {
    "mcpServers": {
      "fwloop": {
        "command": "uvx",
        "args": [
          "--from", "git+https://github.com/Jeffrey1799/FirmwareLoop.git",
          "fwloop"
        ]
      },
      "agentic-hil": {
        "command": "uvx",
        "args": ["agentic-hil", "mcp-stdio"]
      }
    }
  }
  

---

接入模式三：源码二次开发模式（本地 Git 克隆）

适合需要修改 FirmwareLoop 源码或离线开发的用户：

# 1. 克隆与环境初始化
git clone https://github.com/Jeffrey1799/FirmwareLoop.git D:\Tools\FirmwareLoop
cd D:\Tools\FirmwareLoop
uv pip install -e .

# 2. 注册到 Claude Code
claude mcp add fwloop -- "D:\Tools\FirmwareLoop\.venv\Scripts\fwloop.exe"
claude mcp add agentic-hil -- "D:\Tools\FirmwareLoop\.venv\Scripts\agentic-hil.exe" mcp-stdio

---

常用 CLI 终端命令与一键更新（支持简短别名 fwloop）

本项目支持名称兼容，fwloop 与 firmwareloop 完全等价，用户与开发者可在终端直接使用更简短的 fwloop：

# 在任意单片机工程根目录下一键初始化多 Agent 规范 (AGENTS.md, CLAUDE.md, GEMINI.md) 与台架配置
fwloop init           # 或: firmwareloop init

# 一键自动更新至最新版本（自动拉取最新代码并热重载依赖）
fwloop update         # 或: firmwareloop update

# 环境健康体检与依赖诊断
fwloop doctor         # 或: firmwareloop doctor

# 查看或生成各大 Agent MCP 注册指令
fwloop setup          # 或: firmwareloop setup

# 查看当前版本
fwloop version        # 或: firmwareloop version

---

在任意工程中纯对话开发

在你的任意单片机工程目录下启动 Agent，直接通过自然语言交互：

• “帮我将当前单片机工程初始化为 FirmwareLoop 项目” → Agent 自动调用 fw_init_project 生成 AGENTS.md、CLAUDE.md、GEMINI.md 与 lab/lab.yaml
• “帮我将当前工程设为 Keil5 编译，目标芯片是 STM32F103C8T6，串口为 COM5” → Agent 自动调用 fw_configure_lab
• “扫描已连接的 ST-LINK / J-Link 调试器” → Agent 自动调用 fw_scan_hardware
• “编译当前 Keil 工程并刷入板子，复位后读取串口输出” → Agent 自动闭环调用 fw_build、fw_flash、fw_reset

---

特性

• 多 Agent 规范体系：自动生成 AGENTS.md、CLAUDE.md、GEMINI.md 与 skills/firmwareloop/SKILL.md，支持主流 Agent 无缝协同
• Build 适配：自动探测 Keil (UV4.exe) / CMake / Make / IAR / PlatformIO 等已有构建系统，只做包装不重造；输出结构化 firmware-build-result/v1（含 file/line/col 诊断）
• pytest HIL：12 项开箱测试（boot / UART / 协议 / 电源 / PWM / 逻辑分析），无硬件自动 skip，产物 JUnit + firmware-hil-result/v1 + evidence
• 逻辑分析：capture → decode → assert 全链路（I2C / SPI / UART），Saleae MCP 或 sigrok fallback
• 仪器层：PyVISA/SCPI，每一次写入都受 lab/limits.yaml 安全限制保护，超限返回 SAFETY_LIMIT（raw_scpi 刻意未实现）
• 硬件门（Agentic HIL）：probe → 身份校验 → 动作；目标不符立即 STOP；CAN TX 默认需人工授权；Mass Erase / OTP / RDP 等永久禁止
• 仿真模式：无硬件也能完整验收——模拟 DUT 是真实编译产物（stdio 即 UART），仪器/逻辑分析有确定性 simulator 后端
• 审计闭环：每次运行保存 run_id / git commit / modified files / artifact sha256 / uart.log / measurements / 报告

---

与同类项目定位

	FirmwareLoop	pytest-embedded	PlatformIO Test	Labgrid
编排主体	AI Agent	pytest	pytest	资源调度
测量证据	逻辑分析 + VISA 仪器	串口/日志	基础	弱
安全策略	limits.yaml + 权限模型	无	无	弱
迭代闭环	build→测→改→重测（≤3 次）	无	部分	无

---

目录结构

├── tools/            fw_mcp_server / setup-agent-mcp / doctor / build / test /
│                     flash / reset / can / logic_* / instrument_cli / acceptance-scenario
├── tests/            unit/ (mcp_server) / hil/ / plans/ / safety/ / backend/
├── lab/              lab.example.yaml / limits.example.yaml / protocol-decode.yaml
├── test-plans/       smoke.yaml / real-smoke.yaml / regression.yaml
├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
├── demo-make/        示例固件（Make；构建测试载体）
├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.0.8)
├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
├── CLAUDE.md         Claude Code CLI 指南
├── GEMINI.md         Antigravity / Gemini CLI 指南
└── AI_DEV_GUIDE.md   AGENT 强制规则

---

能力验证状态（v0.0.8）

状态定义：Implemented（已实现）/ Simulator Validated（模拟验证）/ Real Hardware Validated（真机验证）/ Experimental / Not Implemented

能力	状态
双层 MCP 服务（13 个工作流与硬件工具）	✅ Implemented + Protocol Validated（31/31 测试通过）
一键多 Agent 脚手架（fwloop init / fw_init_project）	✅ Implemented + Multi-Agent Validated
一键终端更新（fwloop update）	✅ Implemented + Auto-updater Validated
uvx 免克隆即时运行（Zero-Clone Mode）	✅ Implemented + PEP 517/621 Validated
Build：keil (UV4.exe) / cmake / make / platformio / iar / zephyr / esp-idf	✅ Implemented + Multi-backend Validated
pytest HIL（12 项，simulator）	✅ Implemented + Simulator Validated
pytest HIL（real UART）	⚠️ Implemented（Agentic HIL 插件已就绪）→ Real Hardware Validated 待 DUT
Agentic HIL MCP（42 硬件工具）	✅ Implemented + discovery 验证 → 真机待 DUT
逻辑分析 capture/decode/assert（I2C/SPI/UART）	✅ Simulator Validated → Real Hardware Validated 待 LA
VISA 仪器（simulator）	✅ Simulator Validated → Real Hardware Validated 待仪器
Safety Policy（limits.yaml）	✅ Implemented（simulator 校验）→ 外置权威配置
自动修复闭环（M6 载体）	✅ Simulator Validated → Real Hardware Validated 待 DUT

---

接入真实硬件

1. Copy-Item lab\lab.example.yaml lab\lab.yaml，填入 COM 口 / 目标身份 / 探针序列号 / 仪器 resource（真实值永不入库）
2. agentic-hil adopt-hardware 载入探针（CLI 已含于 venv）
3. .\tools\doctor.ps1 -Json 复核
4. probe_target 确认目标身份后，.\tools\acceptance-scenario.ps1 -Hardware agentic-hil -Json

---

贡献

见 CONTRIBUTING.md。版本记录见 CHANGELOG.md，安全相关见 SECURITY.md。

---

License

MIT © Jeffrey1799。第三方组件（Agentic HIL / Logic 2 / PyVISA / pytest / CMake / Ninja / MinGW）归各自作者所有；本项目只做薄适配层。