firmwareloop 0.1.8__tar.gz → 0.2.0__tar.gz

{firmwareloop-0.1.8/firmwareloop.egg-info → firmwareloop-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.1.8
+Version: 0.2.0
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -40,7 +40,7 @@ Dynamic: license-file
 
 ---
 
-## 为什么需要 FirmwareLoop？（定位与作用）
+## 为什么需要 FirmwareLoop？
 
 传统的 AI 编程助手（LLM）通常只能停留在**“纯软件文本生成”**阶段。在单片机与嵌入式领域，AI 面临严重的断层：**看不到编译报错行列、无法操作物理烧录器、读取不到串口输出，更无法测量真实的电信号与总线波形**。
 
@@ -57,11 +57,11 @@ FirmwareLoop 为 AI Agent 暴露了开箱即用的 MCP 工具，涵盖 5 大核
 
 | 领域 | 核心 MCP 工具 | 功能说明 |
 |---|---|---|
-| **构建与体检** | `fw_doctor` <br> `fw_build` | 环境工具链诊断；自动调度 Keil MDK 5 (`UV4.exe`)、CMake、Make、PlatformIO 等编译固件并提取精确定位到行列的诊断日志。 |
-| **硬件与探针** | `fw_scan_hardware` <br> `fw_flash` <br> `fw_reset` | 自动扫描连接的 ST-LINK / J-Link / DAPLink 探针与串口；直连 SWD 接口执行固件烧录与芯片硬件复位。 |
-| **总线与协议** | `fw_logic_capture` <br> `fw_logic_decode` | 驱动逻辑分析仪（Saleae / Sigrok）捕获数字信号；自动解码并断言 I2C 地址/ACK、SPI 帧与串口数据完整性。 |
-| **测试与测量** | `fw_run_hil_test` <br> `fw_measure` <br> `fw_acceptance_scenario` | 一键运行 12 项 pytest 自动化硬件在环测试；安全读取 PyVISA 示波器（频率/Vpp）与程控电源（电流/电压）。 |
-| **工程与脚手架** | `fw_init_project` <br> `fw_configure_lab` <br> `fw_get_evidence` | 一键生成 `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` 多 Agent 指南；自然语言修改芯片型号与台架配置；提取全链路审计证据。 |
+| **构建与体检** | `fw_doctor` <br> `fw_build` | 环境诊断；编译固件并提取诊断日志。 |
+| **硬件与探针** | `fw_scan_hardware` <br> `fw_flash` <br> `fw_reset` | 扫描探针与串口；烧录固件、复位芯片。 |
+| **总线与协议** | `fw_logic_capture` <br> `fw_logic_decode` | 逻辑分析仪抓取并解码 I2C / SPI / UART。 |
+| **测试与测量** | `fw_run_hil_test` <br> `fw_measure` <br> `fw_acceptance_scenario` | 运行 HIL 自动化测试；读取示波器 / 程控电源测量值。 |
+| **工程与脚手架** | `fw_init_project` <br> `fw_configure_lab` <br> `fw_get_evidence` | 生成多 Agent 指南；修改台架配置；提取审计证据。 |
 
 ---
 
@@ -104,9 +104,19 @@ FirmwareLoop 为 AI Agent 暴露了开箱即用的 MCP 工具，涵盖 5 大核
 
 ---
 
-## 极速起步（3 步搞定）
+## NDT 公司同事快捷通道（一键离线部署）
 
-无论你使用 **Google Antigravity**、**Claude Code**、**Qoder** 还是 **Cursor**，只需以下 3 步即可开始 AI 驱动的单片机自动化开发：
+拿到 `Fwloop_setup_pack` 交付包后，双击 **`fwloop-deploy-setup.exe`**，按向导填入 NdtDebugTool 根目录即可，全程离线、无需手工配置。
+完整指南与常见错误速查见随包分发的 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
+
+**装完即可用**：重启 AI Agent 后直接对话操作 NdtBox（状态检查 / 数据采集 / 抓波形 / 固件烧录），无需其它命令。
+若还要在某个单片机工程里做编译 / 烧录 / HIL 测试，进入该工程根目录执行一次 `fwloop init`（每个新工程一次）。
+
+---
+
+## 快速开始（在线安装）
+
+无论你使用 **Google Antigravity**、**Claude Code**、**Qoder**、**CodeBuddy** 还是 **Cursor**，只需以下 3 步即可开始 AI 驱动的单片机自动化开发：
 
 ### 第一步：全局安装核心 CLI 工具
 
@@ -131,43 +141,51 @@ fwloop setup
 fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 ```
 
-> 完成以上两步后，Agent 侧即可直接调用 NdtBox 相关工具：
-> `fw_ndtdbg_status`（版本/连通性/模组通断）、`fw_ndtdbg_measure`（数据轮询采集）、
-> `fw_ndtdbg_read_reg` / `fw_ndtdbg_write_reg`（任意寄存器读写，写需 `write_allowed` + `confirm` 双门控）、
-> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）、
-> `fw_ndtdbg_flash`（.bin/.nfw 整片擦写烧录，需 `write_allowed` + `confirm` 双门控，默认拒绝）。
-> 前置硬件要求：NdtBox 已装 CH341 驱动；如需 Saleae 波形证据，另装 sigrok-cli 并配置
-> `libusb-win32` 驱动（详见 `docs/` 交付说明）。测试时请退出 STDataCollection.exe 上位机（USB 独占）。
+**完成以上两步后，Agent 侧即可直接调用 NdtBox 相关工具：**
+
+- `fw_ndtdbg_status` — 版本 / 连通性 / 模组通断
+- `fw_ndtdbg_measure` — 数据轮询采集
+- `fw_ndtdbg_read_reg` / `fw_ndtdbg_write_reg` — 任意寄存器读写（写需 `write_allowed` + `confirm` 双门控）
+- `fw_ndtdbg_capture_seq` — 寄存器序列 + Saleae 波形同窗口取证
+- `fw_ndtdbg_flash` — .bin/.nfw 整片擦写烧录（双门控，默认拒绝）
+
+**前置要求：**
+
+- **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)
+- **USB 独占**：测试时退出 NdtDebugTool 上位机 STDataCollection.exe（同时打开会互踢）
 
 ---
 
 ### 第二步：全局注册到各大 AI Agent
 
-按你日常使用的 Agent 执行对应的注册命令（全电脑仅需配置一次）：
+**一条命令搞定**（全电脑只需运行一次；自动检测本机已安装的 Agent，未安装的自动跳过）：
 
-1. **Google Antigravity / Gemini CLI（全自动配置，推荐）**：
 ```bash
 fwloop setup
 ```
-> **说明**：该命令会自动将双层 MCP 写入 Antigravity 全局配置（`~/.gemini/config/mcp_config.json`），并全自动将全套技能包同步到全局 Skill 目录。
 
-2. **Claude Code CLI**：
-```bash
-claude mcp add --scope user fwloop -- fwloop
-claude mcp add --scope user agentic-hil -- agentic-hil mcp-stdio
-```
+该命令自动完成三件事：
+
+1. **注册双层 MCP**（`fwloop` 工作流层 + `agentic-hil` 硬件层）到以下 Agent 的全局配置，按字段合并写入、不影响已有 MCP 配置：
 
-3. **Qoder / Qoder CN**：
-`fwloop setup` 会直接写入 IDE 设置页读取的用户级文件：
-- 国际版：`~/.qoder/mcp.json`
-- 国内版：`~/.qoder-cn/mcp.json`
+   | Agent | 配置写入位置 |
+   |---|---|
+   | Google Antigravity / Gemini CLI | `~/.gemini/config/mcp_config.json` |
+   | Claude Code CLI | `~/.claude.json` |
+   | Qoder / Qoder CN | `~/.qoder/mcp.json`、`~/.qoder-cn/mcp.json` |
+   | CodeBuddy IDE | `~/.codebuddy/mcp.json` |
 
-不要依赖 `qoder.cmd --add-mcp`：它写到 `%APPDATA%\Qoder\User\mcp.json`，设置页看不到。
+2. **同步技能包**（`firmwareloop`、`fwloop-adapter`）到 Antigravity 与 Claude Code 的全局 Skill 目录。
+3. **生成机器级全局配置** `%APPDATA%\FirmwareLoop\lab.yaml`（NdtBox 配置模板，已存在则不覆盖）。
 
-4. **CodeBuddy IDE**：
-`fwloop setup` 会合并写入用户级配置 `~/.codebuddy/mcp.json`（`mcpServers` 形状与 Qoder 兼容，含官方 `description` 字段；既有条目与 `env` 自定义字段保留）。`~/.codebuddy` 目录不存在时自动跳过。
+> 手动注册（可选）：Claude Code 也可逐条注册，效果相同：
+> ```bash
+> claude mcp add --scope user fwloop -- fwloop
+> claude mcp add --scope user agentic-hil -- agentic-hil mcp-stdio
+> ```
 
-5. **Cursor / 其他 IDE**（在工程根目录的 `.mcp.json` 中并联配置）：
+**Cursor / 其他 IDE**（setup 未覆盖全局注册的，在工程根目录的 `.mcp.json` 中并联配置）：
 ```json
 {
   "mcpServers": {
@@ -363,7 +381,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.1.8)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.0)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -373,7 +391,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.1.8）
+## 能力验证状态（v0.2.0）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -398,6 +416,20 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
+## 常见错误速查（NdtBox / 逻辑分析）
+
+| 现象 | 原因与解决 |
+|---|---|
+| `CONFIG_ERROR: NdtBox DLL 目录未配置` | 未执行 `fwloop ndtdebugtool`（或路径写错）→ 重跑并确认输出"已写入" |
+| `PROBE_NOT_FOUND` | NdtBox 未插 / CH341 驱动未装（跑交付包 `assets\NDTBoxDriver\CH341PAR.EXE`）/ 上位机 STDataCollection.exe 正占用 USB |
+| 写操作 `PERMISSION_DENIED` | 全局 `lab.yaml` 的 `ndtdbg.write_allowed` 为 `false` → 临时改 `true` 并重启 Agent（测试完建议改回 `false`） |
+| sigrok 报 `Failed to receive reply to EP1 command 0x7d` | Saleae 驱动不是 libusb-win32 → 用 Zadig 重装；或设备被 Logic 软件占用（先退出） |
+| `fw_logic_decode` 空帧 | 抓取窗口内无总线事务 → 改用 `fw_ndtdbg_capture_seq`（抓取与寄存器序列同窗口进行），不要串行先抓后写 |
+
+完整速查表与手工部署细节见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
+
+---
+
 ## 接入真实硬件
 
 1. `Copy-Item lab\lab.example.yaml lab\lab.yaml`，填入 **COM 口 / 目标身份 / 探针序列号 / 仪器 resource**（真实值永不入库）