firmwareloop 0.9.1__tar.gz → 0.11.2__tar.gz

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.9.1
+Version: 0.11.2
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -109,10 +109,32 @@ FirmwareLoop 为 AI Agent 暴露了开箱即用的 MCP 工具，涵盖 5 大核
 
 ## NDT 公司同事快捷通道（一键离线部署）
 
-拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线、无需手工配置。
+拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线。
 完整指南与常见错误速查见随包分发的 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
 
-**装完即可用**：重启 AI Agent 后直接对话操作 NdtBox（状态检查 / 数据采集 / 抓波形 / 固件烧录），无需其它命令。
+**安装器自动完成**：uv + 离线 wheel 安装 fwloop、`fwloop setup`（注册 Agent + 生成全局配置）、写入 NdtDebugTool 路径、
+Saleae Logic16 固件落位（`%LOCALAPPDATA%\sigrok-firmware`）、sigrok-cli 安装。
+
+**安装器不装驱动 —— 这一步只在需要时由人工完成（两类，互不相关）**
+
+| 需要什么 | 什么时候才需要 | 怎么做 |
+|---|---|---|
+| **NdtBox 驱动（CH341PAR）** | 这台电脑**从没连过 NdtBox** 才需要（上位机报 Device Not Found / 设备管理器带 ⚠️）。平时能用 NdtDebugTool 就说明已装好 | 运行包内 `assets\NDTBoxDriver\CH341PAR.EXE`（串口场景另装 `CH341SER.EXE`） |
+| **逻辑分析仪驱动（Zadig → `libusb-win32`）** | 只做寄存器读写**不需要**；要用**抓波形 / 波形证据**（`fw_logic_capture`、`fw_ndtdbg_capture_seq`）时才需要 | 按 `Fwloop_setup_pack\README.md` 第 2 步：Zadig → 选中 Logic S/16 → 驱动选 `libusb-win32` → 拔插一次。**装好了怎么确认**见下方说明（一句话：让 Agent 抓一次波形，能抓到就算装好了） |
+
+> **怎么确认逻辑分析仪驱动装好了（第 1 条对人足够）**
+>
+> 1. **让 Agent 抓一次波形**，例如对它说"用 fwloop 抓一次 I2C 波形并解码"——**能抓到波形，就说明驱动装好了**；
+> 2. 想亲自核对：设备管理器 → 那台 Saleae → 右键属性 → 驱动程序 → 服务显示 `libusb-win32`；
+> 3. 抓不到时的现象：报 `Failed to open device.` 或 `... EP1 command ... LIBUSB_ERROR_IO` ⇒ 驱动没绑对，回第 1 步重做（换 USB 口后也要重做）；
+> 4. Agent 自查用的技术判据：`fwloop doctor` 的仪器深检项 `checks.instruments` —— `status=ok`，且 `libusb_bound` 中该仪器的 `service` 为 `libusb0`/`libusbK`。
+>
+> **为什么"能扫到"不等于"能用"**：驱动绑定不对时 `sigrok-cli --scan` 依然列得出设备，但采集初始化会失败在
+> `Failed to receive reply to EP1 command 0x7d: LIBUSB_ERROR_IO`。原理与三个高频坑（换 USB 口后需重绑、
+> 拔插后需重试一次、阈值要匹配被测电平）详见下文 **《前置条件：仪器接入（Windows）》**。
+
+**装完后**：重启 AI Agent，先让它跑一次环境检查（`fw_doctor`，它会用人话汇报每台仪器/串口能不能用、缺什么怎么补），再操作 NdtBox
+（状态检查 / 数据采集 / 固件烧录 / 抓波形——抓波形前按上表确认逻辑分析仪驱动已就绪）。
 若还要在某个单片机工程里做编译 / 烧录 / HIL 测试，进入该工程根目录执行一次 `fwloop init`（每个新工程一次）。
 
 ---
@@ -132,6 +154,36 @@ uv tool install agentic-hil
 
 ---
 
+### 前置条件：仪器接入（Windows）
+
+框架通过 libusb / VCP 类后端访问 USB 逻辑分析仪、USB 转 IIC/UART 桥等仪器。
+**首次在这台电脑使用某台仪器、或换过 USB 端口之后**，请先确认驱动绑定——这是"仪器打不开"最常见的原因：
+
+| 仪器类别 | 需要什么 | 自查方法 | 装错/没装时的症状 |
+|---|---|---|---|
+| USB 逻辑分析仪（sigrok/Saleae 类，含 FX2/EZ-USB 固件上传型） | 绑定到 libusb 类驱动（`libusb-win32`，或 `WinUSB`） | 最直接：让它抓一次波形，能抓到就行；手工核对：设备管理器 → 设备 → 属性 → 驱动程序/服务（应显示 `libusb-win32` / `libusb0` / `libusbK` / `WinUSB`）；也可让 Agent 读 `fwloop doctor` 的仪器深检项 | 采集报 `Failed to open device.`；初始化阶段报 `... EP1 command ... LIBUSB_ERROR_IO` |
+| USB 转 IIC/UART 桥（CH340/CH341、CP210x、FTDI…） | 厂商 VCP 驱动 | 出现 COM 口，`fwloop doctor` 的 `com_ports` 能列出 | 端口不存在 / 打开报占用 |
+| 蓝牙或 ELTIMA 等虚拟串口 | 不作为被测口 | `fwloop doctor` 会把虚拟口单独列出来（不与真实口混在一起） | 能打开但永远无数据 |
+
+**用 Zadig 给逻辑分析仪绑定驱动（人工一次，需管理员）**
+
+1. 关闭一切可能占用该设备的软件（厂商上位机、PulseView、Saleae Logic 2 等）——**独占是前提**。
+2. 管理员运行 Zadig（sigrok 安装目录自带 `zadig.exe`；也可用官方包）→ `Options → List All Devices`。
+3. 选中**当前在线**的那台设备（按 VID/PID 核对；忽略"幽灵"残留节点），目标驱动选 `WinUSB` → `Replace Driver`。
+4. **拔插一次**设备，再让 Agent 重试。
+5. 若仍打不开、或初始化阶段报 EP1/命令无应答：对该设备改绑 `libusb-win32` 再试（两者互为 A/B 对照）。
+
+**三个会反复踩的坑**
+
+- 驱动绑定**跟随 USB 端口实例**：换一个 USB 口 = 新的设备实例，Windows 可能重新绑回默认驱动 → 需对该实例重做一次 Zadig。
+- 拔插会**重置设备状态**：刚初始化的设备拔插后要重新初始化；首次打开报"等待设备重启 / 初始化失败"时，等 3–5 秒重试一次通常即可。
+- **阈值/量程必须覆盖被测电平**：采集前确认被测逻辑电平落在仪器档位内（例：1.8 V 逻辑需选覆盖 1.4–3.6 V 的档位，而不是 0.7–1.4 V；示波器注意探针 1x/10x 衰减比）。
+
+> 驱动安装需要管理员权限与设备选择，误绑会影响其它软件，因此框架**不自动安装驱动**，只做「检测 → 指引 → 复验」：
+> `fwloop doctor` 会报告每台仪器当前的就绪状态**和下一步该怎么修**（Agent 读的也是同一份内容）。公司交付包覆盖的环境由安装器代做（见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)）。
+
+---
+
 ### 可选：接入 NdtBox 调试盒（公司内部 USB→IIC 调试工具）
 
 如需用 Agent 直接操作 NdtBox（固件寄存器读写 / 数据采集 / 逻辑分析仪协议验证），安装后执行一次：
@@ -156,7 +208,7 @@ fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 **前置要求：**
 
 - **CH341 驱动**：首次在这台电脑使用 NdtBox 时，运行交付包内 `assets\NDTBoxDriver\CH341PAR.EXE`（USB 转 IIC）；COM 串口场景另装 `CH341SER.EXE`
-- **Saleae 波形证据**（可选）：Saleae Logic16 固件（落位 `%LOCALAPPDATA%\sigrok-firmware`）+ sigrok-cli，并用 Zadig 配置 `libusb-win32` 驱动——交付包一键安装器会自动完成，手工部署详见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)
+- **Saleae 波形证据**（可选）：Saleae Logic16 固件落位 `%LOCALAPPDATA%\sigrok-firmware` + sigrok-cli；**驱动绑定（Zadig）见上文《前置条件：仪器接入（Windows）》**——交付包一键安装器会自动完成这两步，手工部署详见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)
 - **USB 独占**：测试时退出 NdtDebugTool 上位机 STDataCollection.exe（同时打开会互踢）
 
 ---
@@ -182,7 +234,17 @@ fwloop setup
    | DeepSeek Harness (DSH) | `~/.dsh/profiles/<已派生 profile>/cordis.patch.yml` |
    | ZCode IDE | `~/.zcode/cli/config.json` |
 
-2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到 Antigravity 与 Claude Code 的全局 Skill 目录。
+2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到各 Agent 的全局 Skill 目录（探测式：Agent 主目录存在才写入，`skills/` 子目录自动创建）：
+
+   | Agent | Skill 写入位置 |
+   |---|---|
+   | Google Antigravity / Gemini CLI | `~/.gemini/antigravity-cli/skills/` |
+   | Claude Code CLI | `~/.claude/skills/` |
+   | Qoder / Qoder CN | `~/.qoder/skills/`、`~/.qoder-cn/skills/` |
+   | CodeBuddy IDE | `~/.codebuddy/skills/` |
+   | DeepSeek Harness (DSH) | `~/.dsh/skills/` |
+   | ZCode IDE | `~/.zcode/skills/` |
+   | 通用（跨 Agent 工具链） | `~/.agents/skills/`（特殊：无"未安装"概念，机器上不存在时直接创建） |
 3. **生成机器级全局配置** `%APPDATA%\FirmwareLoop\lab.yaml`（NdtBox 配置模板，已存在则不覆盖）。
 
 > 手动注册（可选）：Claude Code 也可逐条注册，效果相同：
@@ -233,7 +295,7 @@ fwloop init
 |---|---|---|---|
 | **`fwloop setup`** | **系统全局级** | 给各大 Agent（Antigravity / Claude Code / Qoder / Qoder CN / CodeBuddy）配置全局 MCP 与同步技能包 | **全电脑只需跑 1 次** |
 | **`fwloop init`** | **工程项目级** | 在当前单片机代码目录下生成 `AGENTS.md`、`GEMINI.md`、`CLAUDE.md` 与台架配置 | **每个新单片机项目跑 1 次** |
-| **`fwloop doctor`** | **环境诊断** | 检查编译器（Keil/GCC）、Python 环境、串口与探针连接健康度 | 随时排查环境时使用 |
+| **`fwloop doctor`** | **环境诊断** | 一屏人话摘要：核心工具链是否正常、仪器能不能用（逻辑分析仪/串口/探针…）、缺什么怎么补。加 `--json` 看原始数据 | 随时排查环境时使用 |
 | **`fwloop update`** | **自动更新** | 一键自动拉取最新代码并热重载依赖 | 升级工具版本时使用 |
 
 ---
@@ -309,7 +371,7 @@ fwloop update
 
 3. 环境健康体检与依赖诊断：
 ```bash
-fwloop doctor
+fwloop doctor          # 人话摘要; 需要原始数据时另加 --json
 ```
 
 4. 查看或生成各大 Agent MCP 注册指令：
@@ -387,7 +449,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.9.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.11.2)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -397,7 +459,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.9.1）
+## 能力验证状态（v0.11.2）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/README.md

@@ -79,10 +79,32 @@ FirmwareLoop 为 AI Agent 暴露了开箱即用的 MCP 工具，涵盖 5 大核
 
 ## NDT 公司同事快捷通道（一键离线部署）
 
-拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线、无需手工配置。
+拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线。
 完整指南与常见错误速查见随包分发的 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
 
-**装完即可用**：重启 AI Agent 后直接对话操作 NdtBox（状态检查 / 数据采集 / 抓波形 / 固件烧录），无需其它命令。
+**安装器自动完成**：uv + 离线 wheel 安装 fwloop、`fwloop setup`（注册 Agent + 生成全局配置）、写入 NdtDebugTool 路径、
+Saleae Logic16 固件落位（`%LOCALAPPDATA%\sigrok-firmware`）、sigrok-cli 安装。
+
+**安装器不装驱动 —— 这一步只在需要时由人工完成（两类，互不相关）**
+
+| 需要什么 | 什么时候才需要 | 怎么做 |
+|---|---|---|
+| **NdtBox 驱动（CH341PAR）** | 这台电脑**从没连过 NdtBox** 才需要（上位机报 Device Not Found / 设备管理器带 ⚠️）。平时能用 NdtDebugTool 就说明已装好 | 运行包内 `assets\NDTBoxDriver\CH341PAR.EXE`（串口场景另装 `CH341SER.EXE`） |
+| **逻辑分析仪驱动（Zadig → `libusb-win32`）** | 只做寄存器读写**不需要**；要用**抓波形 / 波形证据**（`fw_logic_capture`、`fw_ndtdbg_capture_seq`）时才需要 | 按 `Fwloop_setup_pack\README.md` 第 2 步：Zadig → 选中 Logic S/16 → 驱动选 `libusb-win32` → 拔插一次。**装好了怎么确认**见下方说明（一句话：让 Agent 抓一次波形，能抓到就算装好了） |
+
+> **怎么确认逻辑分析仪驱动装好了（第 1 条对人足够）**
+>
+> 1. **让 Agent 抓一次波形**，例如对它说"用 fwloop 抓一次 I2C 波形并解码"——**能抓到波形，就说明驱动装好了**；
+> 2. 想亲自核对：设备管理器 → 那台 Saleae → 右键属性 → 驱动程序 → 服务显示 `libusb-win32`；
+> 3. 抓不到时的现象：报 `Failed to open device.` 或 `... EP1 command ... LIBUSB_ERROR_IO` ⇒ 驱动没绑对，回第 1 步重做（换 USB 口后也要重做）；
+> 4. Agent 自查用的技术判据：`fwloop doctor` 的仪器深检项 `checks.instruments` —— `status=ok`，且 `libusb_bound` 中该仪器的 `service` 为 `libusb0`/`libusbK`。
+>
+> **为什么"能扫到"不等于"能用"**：驱动绑定不对时 `sigrok-cli --scan` 依然列得出设备，但采集初始化会失败在
+> `Failed to receive reply to EP1 command 0x7d: LIBUSB_ERROR_IO`。原理与三个高频坑（换 USB 口后需重绑、
+> 拔插后需重试一次、阈值要匹配被测电平）详见下文 **《前置条件：仪器接入（Windows）》**。
+
+**装完后**：重启 AI Agent，先让它跑一次环境检查（`fw_doctor`，它会用人话汇报每台仪器/串口能不能用、缺什么怎么补），再操作 NdtBox
+（状态检查 / 数据采集 / 固件烧录 / 抓波形——抓波形前按上表确认逻辑分析仪驱动已就绪）。
 若还要在某个单片机工程里做编译 / 烧录 / HIL 测试，进入该工程根目录执行一次 `fwloop init`（每个新工程一次）。
 
 ---
@@ -102,6 +124,36 @@ uv tool install agentic-hil
 
 ---
 
+### 前置条件：仪器接入（Windows）
+
+框架通过 libusb / VCP 类后端访问 USB 逻辑分析仪、USB 转 IIC/UART 桥等仪器。
+**首次在这台电脑使用某台仪器、或换过 USB 端口之后**，请先确认驱动绑定——这是"仪器打不开"最常见的原因：
+
+| 仪器类别 | 需要什么 | 自查方法 | 装错/没装时的症状 |
+|---|---|---|---|
+| USB 逻辑分析仪（sigrok/Saleae 类，含 FX2/EZ-USB 固件上传型） | 绑定到 libusb 类驱动（`libusb-win32`，或 `WinUSB`） | 最直接：让它抓一次波形，能抓到就行；手工核对：设备管理器 → 设备 → 属性 → 驱动程序/服务（应显示 `libusb-win32` / `libusb0` / `libusbK` / `WinUSB`）；也可让 Agent 读 `fwloop doctor` 的仪器深检项 | 采集报 `Failed to open device.`；初始化阶段报 `... EP1 command ... LIBUSB_ERROR_IO` |
+| USB 转 IIC/UART 桥（CH340/CH341、CP210x、FTDI…） | 厂商 VCP 驱动 | 出现 COM 口，`fwloop doctor` 的 `com_ports` 能列出 | 端口不存在 / 打开报占用 |
+| 蓝牙或 ELTIMA 等虚拟串口 | 不作为被测口 | `fwloop doctor` 会把虚拟口单独列出来（不与真实口混在一起） | 能打开但永远无数据 |
+
+**用 Zadig 给逻辑分析仪绑定驱动（人工一次，需管理员）**
+
+1. 关闭一切可能占用该设备的软件（厂商上位机、PulseView、Saleae Logic 2 等）——**独占是前提**。
+2. 管理员运行 Zadig（sigrok 安装目录自带 `zadig.exe`；也可用官方包）→ `Options → List All Devices`。
+3. 选中**当前在线**的那台设备（按 VID/PID 核对；忽略"幽灵"残留节点），目标驱动选 `WinUSB` → `Replace Driver`。
+4. **拔插一次**设备，再让 Agent 重试。
+5. 若仍打不开、或初始化阶段报 EP1/命令无应答：对该设备改绑 `libusb-win32` 再试（两者互为 A/B 对照）。
+
+**三个会反复踩的坑**
+
+- 驱动绑定**跟随 USB 端口实例**：换一个 USB 口 = 新的设备实例，Windows 可能重新绑回默认驱动 → 需对该实例重做一次 Zadig。
+- 拔插会**重置设备状态**：刚初始化的设备拔插后要重新初始化；首次打开报"等待设备重启 / 初始化失败"时，等 3–5 秒重试一次通常即可。
+- **阈值/量程必须覆盖被测电平**：采集前确认被测逻辑电平落在仪器档位内（例：1.8 V 逻辑需选覆盖 1.4–3.6 V 的档位，而不是 0.7–1.4 V；示波器注意探针 1x/10x 衰减比）。
+
+> 驱动安装需要管理员权限与设备选择，误绑会影响其它软件，因此框架**不自动安装驱动**，只做「检测 → 指引 → 复验」：
+> `fwloop doctor` 会报告每台仪器当前的就绪状态**和下一步该怎么修**（Agent 读的也是同一份内容）。公司交付包覆盖的环境由安装器代做（见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)）。
+
+---
+
 ### 可选：接入 NdtBox 调试盒（公司内部 USB→IIC 调试工具）
 
 如需用 Agent 直接操作 NdtBox（固件寄存器读写 / 数据采集 / 逻辑分析仪协议验证），安装后执行一次：
@@ -126,7 +178,7 @@ fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 **前置要求：**
 
 - **CH341 驱动**：首次在这台电脑使用 NdtBox 时，运行交付包内 `assets\NDTBoxDriver\CH341PAR.EXE`（USB 转 IIC）；COM 串口场景另装 `CH341SER.EXE`
-- **Saleae 波形证据**（可选）：Saleae Logic16 固件（落位 `%LOCALAPPDATA%\sigrok-firmware`）+ sigrok-cli，并用 Zadig 配置 `libusb-win32` 驱动——交付包一键安装器会自动完成，手工部署详见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)
+- **Saleae 波形证据**（可选）：Saleae Logic16 固件落位 `%LOCALAPPDATA%\sigrok-firmware` + sigrok-cli；**驱动绑定（Zadig）见上文《前置条件：仪器接入（Windows）》**——交付包一键安装器会自动完成这两步，手工部署详见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)
 - **USB 独占**：测试时退出 NdtDebugTool 上位机 STDataCollection.exe（同时打开会互踢）
 
 ---
@@ -152,7 +204,17 @@ fwloop setup
    | DeepSeek Harness (DSH) | `~/.dsh/profiles/<已派生 profile>/cordis.patch.yml` |
    | ZCode IDE | `~/.zcode/cli/config.json` |
 
-2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到 Antigravity 与 Claude Code 的全局 Skill 目录。
+2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到各 Agent 的全局 Skill 目录（探测式：Agent 主目录存在才写入，`skills/` 子目录自动创建）：
+
+   | Agent | Skill 写入位置 |
+   |---|---|
+   | Google Antigravity / Gemini CLI | `~/.gemini/antigravity-cli/skills/` |
+   | Claude Code CLI | `~/.claude/skills/` |
+   | Qoder / Qoder CN | `~/.qoder/skills/`、`~/.qoder-cn/skills/` |
+   | CodeBuddy IDE | `~/.codebuddy/skills/` |
+   | DeepSeek Harness (DSH) | `~/.dsh/skills/` |
+   | ZCode IDE | `~/.zcode/skills/` |
+   | 通用（跨 Agent 工具链） | `~/.agents/skills/`（特殊：无"未安装"概念，机器上不存在时直接创建） |
 3. **生成机器级全局配置** `%APPDATA%\FirmwareLoop\lab.yaml`（NdtBox 配置模板，已存在则不覆盖）。
 
 > 手动注册（可选）：Claude Code 也可逐条注册，效果相同：
@@ -203,7 +265,7 @@ fwloop init
 |---|---|---|---|
 | **`fwloop setup`** | **系统全局级** | 给各大 Agent（Antigravity / Claude Code / Qoder / Qoder CN / CodeBuddy）配置全局 MCP 与同步技能包 | **全电脑只需跑 1 次** |
 | **`fwloop init`** | **工程项目级** | 在当前单片机代码目录下生成 `AGENTS.md`、`GEMINI.md`、`CLAUDE.md` 与台架配置 | **每个新单片机项目跑 1 次** |
-| **`fwloop doctor`** | **环境诊断** | 检查编译器（Keil/GCC）、Python 环境、串口与探针连接健康度 | 随时排查环境时使用 |
+| **`fwloop doctor`** | **环境诊断** | 一屏人话摘要：核心工具链是否正常、仪器能不能用（逻辑分析仪/串口/探针…）、缺什么怎么补。加 `--json` 看原始数据 | 随时排查环境时使用 |
 | **`fwloop update`** | **自动更新** | 一键自动拉取最新代码并热重载依赖 | 升级工具版本时使用 |
 
 ---
@@ -279,7 +341,7 @@ fwloop update
 
 3. 环境健康体检与依赖诊断：
 ```bash
-fwloop doctor
+fwloop doctor          # 人话摘要; 需要原始数据时另加 --json
 ```
 
 4. 查看或生成各大 Agent MCP 注册指令：
@@ -357,7 +419,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.9.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.11.2)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -367,7 +429,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.9.1）
+## 能力验证状态（v0.11.2）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/firmwareloop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.9.1
+Version: 0.11.2
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -109,10 +109,32 @@ FirmwareLoop 为 AI Agent 暴露了开箱即用的 MCP 工具，涵盖 5 大核
 
 ## NDT 公司同事快捷通道（一键离线部署）
 
-拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线、无需手工配置。
+拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线。
 完整指南与常见错误速查见随包分发的 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
 
-**装完即可用**：重启 AI Agent 后直接对话操作 NdtBox（状态检查 / 数据采集 / 抓波形 / 固件烧录），无需其它命令。
+**安装器自动完成**：uv + 离线 wheel 安装 fwloop、`fwloop setup`（注册 Agent + 生成全局配置）、写入 NdtDebugTool 路径、
+Saleae Logic16 固件落位（`%LOCALAPPDATA%\sigrok-firmware`）、sigrok-cli 安装。
+
+**安装器不装驱动 —— 这一步只在需要时由人工完成（两类，互不相关）**
+
+| 需要什么 | 什么时候才需要 | 怎么做 |
+|---|---|---|
+| **NdtBox 驱动（CH341PAR）** | 这台电脑**从没连过 NdtBox** 才需要（上位机报 Device Not Found / 设备管理器带 ⚠️）。平时能用 NdtDebugTool 就说明已装好 | 运行包内 `assets\NDTBoxDriver\CH341PAR.EXE`（串口场景另装 `CH341SER.EXE`） |
+| **逻辑分析仪驱动（Zadig → `libusb-win32`）** | 只做寄存器读写**不需要**；要用**抓波形 / 波形证据**（`fw_logic_capture`、`fw_ndtdbg_capture_seq`）时才需要 | 按 `Fwloop_setup_pack\README.md` 第 2 步：Zadig → 选中 Logic S/16 → 驱动选 `libusb-win32` → 拔插一次。**装好了怎么确认**见下方说明（一句话：让 Agent 抓一次波形，能抓到就算装好了） |
+
+> **怎么确认逻辑分析仪驱动装好了（第 1 条对人足够）**
+>
+> 1. **让 Agent 抓一次波形**，例如对它说"用 fwloop 抓一次 I2C 波形并解码"——**能抓到波形，就说明驱动装好了**；
+> 2. 想亲自核对：设备管理器 → 那台 Saleae → 右键属性 → 驱动程序 → 服务显示 `libusb-win32`；
+> 3. 抓不到时的现象：报 `Failed to open device.` 或 `... EP1 command ... LIBUSB_ERROR_IO` ⇒ 驱动没绑对，回第 1 步重做（换 USB 口后也要重做）；
+> 4. Agent 自查用的技术判据：`fwloop doctor` 的仪器深检项 `checks.instruments` —— `status=ok`，且 `libusb_bound` 中该仪器的 `service` 为 `libusb0`/`libusbK`。
+>
+> **为什么"能扫到"不等于"能用"**：驱动绑定不对时 `sigrok-cli --scan` 依然列得出设备，但采集初始化会失败在
+> `Failed to receive reply to EP1 command 0x7d: LIBUSB_ERROR_IO`。原理与三个高频坑（换 USB 口后需重绑、
+> 拔插后需重试一次、阈值要匹配被测电平）详见下文 **《前置条件：仪器接入（Windows）》**。
+
+**装完后**：重启 AI Agent，先让它跑一次环境检查（`fw_doctor`，它会用人话汇报每台仪器/串口能不能用、缺什么怎么补），再操作 NdtBox
+（状态检查 / 数据采集 / 固件烧录 / 抓波形——抓波形前按上表确认逻辑分析仪驱动已就绪）。
 若还要在某个单片机工程里做编译 / 烧录 / HIL 测试，进入该工程根目录执行一次 `fwloop init`（每个新工程一次）。
 
 ---
@@ -132,6 +154,36 @@ uv tool install agentic-hil
 
 ---
 
+### 前置条件：仪器接入（Windows）
+
+框架通过 libusb / VCP 类后端访问 USB 逻辑分析仪、USB 转 IIC/UART 桥等仪器。
+**首次在这台电脑使用某台仪器、或换过 USB 端口之后**，请先确认驱动绑定——这是"仪器打不开"最常见的原因：
+
+| 仪器类别 | 需要什么 | 自查方法 | 装错/没装时的症状 |
+|---|---|---|---|
+| USB 逻辑分析仪（sigrok/Saleae 类，含 FX2/EZ-USB 固件上传型） | 绑定到 libusb 类驱动（`libusb-win32`，或 `WinUSB`） | 最直接：让它抓一次波形，能抓到就行；手工核对：设备管理器 → 设备 → 属性 → 驱动程序/服务（应显示 `libusb-win32` / `libusb0` / `libusbK` / `WinUSB`）；也可让 Agent 读 `fwloop doctor` 的仪器深检项 | 采集报 `Failed to open device.`；初始化阶段报 `... EP1 command ... LIBUSB_ERROR_IO` |
+| USB 转 IIC/UART 桥（CH340/CH341、CP210x、FTDI…） | 厂商 VCP 驱动 | 出现 COM 口，`fwloop doctor` 的 `com_ports` 能列出 | 端口不存在 / 打开报占用 |
+| 蓝牙或 ELTIMA 等虚拟串口 | 不作为被测口 | `fwloop doctor` 会把虚拟口单独列出来（不与真实口混在一起） | 能打开但永远无数据 |
+
+**用 Zadig 给逻辑分析仪绑定驱动（人工一次，需管理员）**
+
+1. 关闭一切可能占用该设备的软件（厂商上位机、PulseView、Saleae Logic 2 等）——**独占是前提**。
+2. 管理员运行 Zadig（sigrok 安装目录自带 `zadig.exe`；也可用官方包）→ `Options → List All Devices`。
+3. 选中**当前在线**的那台设备（按 VID/PID 核对；忽略"幽灵"残留节点），目标驱动选 `WinUSB` → `Replace Driver`。
+4. **拔插一次**设备，再让 Agent 重试。
+5. 若仍打不开、或初始化阶段报 EP1/命令无应答：对该设备改绑 `libusb-win32` 再试（两者互为 A/B 对照）。
+
+**三个会反复踩的坑**
+
+- 驱动绑定**跟随 USB 端口实例**：换一个 USB 口 = 新的设备实例，Windows 可能重新绑回默认驱动 → 需对该实例重做一次 Zadig。
+- 拔插会**重置设备状态**：刚初始化的设备拔插后要重新初始化；首次打开报"等待设备重启 / 初始化失败"时，等 3–5 秒重试一次通常即可。
+- **阈值/量程必须覆盖被测电平**：采集前确认被测逻辑电平落在仪器档位内（例：1.8 V 逻辑需选覆盖 1.4–3.6 V 的档位，而不是 0.7–1.4 V；示波器注意探针 1x/10x 衰减比）。
+
+> 驱动安装需要管理员权限与设备选择，误绑会影响其它软件，因此框架**不自动安装驱动**，只做「检测 → 指引 → 复验」：
+> `fwloop doctor` 会报告每台仪器当前的就绪状态**和下一步该怎么修**（Agent 读的也是同一份内容）。公司交付包覆盖的环境由安装器代做（见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)）。
+
+---
+
 ### 可选：接入 NdtBox 调试盒（公司内部 USB→IIC 调试工具）
 
 如需用 Agent 直接操作 NdtBox（固件寄存器读写 / 数据采集 / 逻辑分析仪协议验证），安装后执行一次：
@@ -156,7 +208,7 @@ fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 **前置要求：**
 
 - **CH341 驱动**：首次在这台电脑使用 NdtBox 时，运行交付包内 `assets\NDTBoxDriver\CH341PAR.EXE`（USB 转 IIC）；COM 串口场景另装 `CH341SER.EXE`
-- **Saleae 波形证据**（可选）：Saleae Logic16 固件（落位 `%LOCALAPPDATA%\sigrok-firmware`）+ sigrok-cli，并用 Zadig 配置 `libusb-win32` 驱动——交付包一键安装器会自动完成，手工部署详见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)
+- **Saleae 波形证据**（可选）：Saleae Logic16 固件落位 `%LOCALAPPDATA%\sigrok-firmware` + sigrok-cli；**驱动绑定（Zadig）见上文《前置条件：仪器接入（Windows）》**——交付包一键安装器会自动完成这两步，手工部署详见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)
 - **USB 独占**：测试时退出 NdtDebugTool 上位机 STDataCollection.exe（同时打开会互踢）
 
 ---
@@ -182,7 +234,17 @@ fwloop setup
    | DeepSeek Harness (DSH) | `~/.dsh/profiles/<已派生 profile>/cordis.patch.yml` |
    | ZCode IDE | `~/.zcode/cli/config.json` |
 
-2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到 Antigravity 与 Claude Code 的全局 Skill 目录。
+2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到各 Agent 的全局 Skill 目录（探测式：Agent 主目录存在才写入，`skills/` 子目录自动创建）：
+
+   | Agent | Skill 写入位置 |
+   |---|---|
+   | Google Antigravity / Gemini CLI | `~/.gemini/antigravity-cli/skills/` |
+   | Claude Code CLI | `~/.claude/skills/` |
+   | Qoder / Qoder CN | `~/.qoder/skills/`、`~/.qoder-cn/skills/` |
+   | CodeBuddy IDE | `~/.codebuddy/skills/` |
+   | DeepSeek Harness (DSH) | `~/.dsh/skills/` |
+   | ZCode IDE | `~/.zcode/skills/` |
+   | 通用（跨 Agent 工具链） | `~/.agents/skills/`（特殊：无"未安装"概念，机器上不存在时直接创建） |
 3. **生成机器级全局配置** `%APPDATA%\FirmwareLoop\lab.yaml`（NdtBox 配置模板，已存在则不覆盖）。
 
 > 手动注册（可选）：Claude Code 也可逐条注册，效果相同：
@@ -233,7 +295,7 @@ fwloop init
 |---|---|---|---|
 | **`fwloop setup`** | **系统全局级** | 给各大 Agent（Antigravity / Claude Code / Qoder / Qoder CN / CodeBuddy）配置全局 MCP 与同步技能包 | **全电脑只需跑 1 次** |
 | **`fwloop init`** | **工程项目级** | 在当前单片机代码目录下生成 `AGENTS.md`、`GEMINI.md`、`CLAUDE.md` 与台架配置 | **每个新单片机项目跑 1 次** |
-| **`fwloop doctor`** | **环境诊断** | 检查编译器（Keil/GCC）、Python 环境、串口与探针连接健康度 | 随时排查环境时使用 |
+| **`fwloop doctor`** | **环境诊断** | 一屏人话摘要：核心工具链是否正常、仪器能不能用（逻辑分析仪/串口/探针…）、缺什么怎么补。加 `--json` 看原始数据 | 随时排查环境时使用 |
 | **`fwloop update`** | **自动更新** | 一键自动拉取最新代码并热重载依赖 | 升级工具版本时使用 |
 
 ---
@@ -309,7 +371,7 @@ fwloop update
 
 3. 环境健康体检与依赖诊断：
 ```bash
-fwloop doctor
+fwloop doctor          # 人话摘要; 需要原始数据时另加 --json
 ```
 
 4. 查看或生成各大 Agent MCP 注册指令：
@@ -387,7 +449,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.9.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.11.2)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -397,7 +459,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.9.1）
+## 能力验证状态（v0.11.2）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/firmwareloop.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ tools/flash.ps1
 tools/fw_mcp_server.py
 tools/instrument_cli.py
 tools/logic_capture.ps1
+tools/logic_capture_summary.py
 tools/logic_decode.ps1
 tools/ndtdbg_bridge.ps1
 tools/ndtdbg_cli.py
@@ -29,10 +30,13 @@ tools/test.ps1
 tools/common/build-backends.psm1
 tools/common/fw.psm1
 tools/common/uart_probe.py
+tools/installer/README.md
 tools/lib/__init__.py
+tools/lib/doctor_summary.py
 tools/lib/instruments.py
 tools/lib/ndtdbg.py
 tools/lib/serial_assistant.py
+tools/lib/session_run.py
 tools/templates/lab.example.yaml
 tools/templates/skill-firmwareloop.md
 tools/templates/skill-fwloop-adapter.md

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firmwareloop"
-version = "0.9.1"
+version = "0.11.2"
 description = "AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)"
 readme = "README.md"
 authors = [

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/tools/__init__.py

@@ -2,4 +2,4 @@
 FirmwareLoop - AI Agent Firmware Development and Lab Automation Platform.
 """
 
-__version__ = "0.9.1"
+__version__ = "0.11.2"

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/tools/build.ps1

@@ -49,8 +49,9 @@ $repoRoot = Get-FwRepoRoot
 $sw = [System.Diagnostics.Stopwatch]::StartNew()
 
 function Exit-WithError {
-    param([string]$Class, [string]$Message, [string]$Detail)
-    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    # v0.11.0: -Remedy 透传到 New-FwError (未给则按 error_class 取默认建议)
+    param([string]$Class, [string]$Message, [string]$Detail, [string]$Remedy)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail -Remedy $Remedy
     if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
     exit 2
 }

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/tools/can.ps1

@@ -39,27 +39,30 @@ $repoRoot = Get-FwRepoRoot
 $stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
 
 function Exit-WithError {
-    param([string]$Class, [string]$Message, [string]$Detail)
-    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    # v0.11.0: -Remedy 透传到 New-FwError (未给则按 error_class 取默认建议)
+    param([string]$Class, [string]$Message, [string]$Detail, [string]$Remedy)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail -Remedy $Remedy
     if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
     exit 2
 }
 
 # CAN TX default requires explicit authorization (Spec §12: 人工授权)
 if ($Command -eq 'send' -and -not $Authorized) {
-    Exit-WithError -Class 'PERMISSION_DENIED' -Message 'CAN TX requires explicit human authorization; pass -Authorized after approval (Spec §12/§24).'
+    Exit-WithError -Class 'PERMISSION_DENIED' -Message 'CAN TX requires explicit human authorization; pass -Authorized after approval (Spec §12/§24).' `
+        -Remedy 'CAN TX 属需授权操作: 取得人工批准后加 -Authorized 重跑; 只读场景用 read/session-start'
 }
 
 $cmd = Get-Command agentic-hil -ErrorAction SilentlyContinue
 $tool = if ($cmd) { $cmd.Source } else { $null }
 
 if ($Backend -eq 'agentic-hil' -and -not $tool) {
-    Exit-WithError -Class 'PROBE_NOT_FOUND' -Message "'agentic-hil' is not installed; CAN is not available until Agentic HIL is installed (Spec §32)." -Detail 'Install Agentic HIL, then verify its CAN schema with: agentic-hil --help'
+    Exit-WithError -Class 'PROBE_NOT_FOUND' -Message "'agentic-hil' is not installed; CAN is not available until Agentic HIL is installed (Spec §32)." -Detail 'Install Agentic HIL, then verify its CAN schema with: agentic-hil --help' `
+        -Remedy 'uv tool install agentic-hil (或 uv pip install agentic-hil), 然后 fwloop setup 注册 MCP; 复核: fwloop doctor 的 agentic_hil 项'
 }
 
 # Resolve lab config for adapter/channel/bitrate defaults (never hardcoded)
-$labCfg = Join-Path $repoRoot 'lab\lab.yaml'
-if (-not (Test-Path -LiteralPath $labCfg)) { $labCfg = Join-Path $repoRoot 'lab\lab.example.yaml' }
+$labCfg = Join-Path (Join-Path $repoRoot 'lab') 'lab.yaml'
+if (-not (Test-Path -LiteralPath $labCfg)) { $labCfg = Join-Path (Join-Path $repoRoot 'lab') 'lab.example.yaml' }
 $canCfg = @{}
 if (Test-Path -LiteralPath $labCfg) {
     try {

{firmwareloop-0.9.1 → firmwareloop-0.11.2}/tools/check-qoder-mcp.ps1

@@ -26,8 +26,9 @@ Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
 $repoRoot = Get-FwRepoRoot
 
 function Exit-WithError {
-    param([string]$Class, [string]$Message, [string]$Detail)
-    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    # v0.11.0: -Remedy 透传到 New-FwError (未给则按 error_class 取默认建议)
+    param([string]$Class, [string]$Message, [string]$Detail, [string]$Remedy)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail -Remedy $Remedy
     if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
     exit 2
 }