firmwareloop 0.0.8__py3-none-any.whl

firmwareloop-0.0.8.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: firmwareloop
+Version: 0.0.8
+Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
+Author-email: WeilinZhang <19523330249@163.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Jeffrey1799/FirmwareLoop
+Project-URL: Repository, https://github.com/Jeffrey1799/FirmwareLoop.git
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyvisa>=1.14.0
+Requires-Dist: pyvisa-py>=0.7.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pytest>=8.0.0
+Requires-Dist: pyocd>=0.36.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: agentic-hil>=0.14.0
+Dynamic: license-file
+
+# FirmwareLoop
+
+> 面向 AI Agent 的固件开发与实验室自动化平台（开源版）。
+> 目标不是"AI 帮工程师写代码"，而是**让 AI 基于真实硬件产生的观测数据参与开发、调试、测试与回归验证**。
+
+![Windows](https://img.shields.io/badge/windows-10%20%7C%2011-blue)
+![PowerShell](https://img.shields.io/badge/powershell-7+-4E8B8B)
+![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)
+[![CI](https://github.com/Jeffrey1799/FirmwareLoop/actions/workflows/ci.yml/badge.svg)](https://github.com/Jeffrey1799/FirmwareLoop/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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](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` 安装为系统全局工具：
+
+```bash
+# 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 注册**：
+  ```bash
+  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` 中配置）**：
+  ```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 源码或离线开发的用户：
+```powershell
+# 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`：
+
+```bash
+# 在任意单片机工程根目录下一键初始化多 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](CONTRIBUTING.md)。版本记录见 [CHANGELOG.md](CHANGELOG.md)，安全相关见 [SECURITY.md](SECURITY.md)。
+
+---
+
+## License
+
+[MIT](LICENSE) © Jeffrey1799。第三方组件（Agentic HIL / Logic 2 / PyVISA / pytest / CMake / Ninja / MinGW）归各自作者所有；本项目只做薄适配层。

firmwareloop-0.0.8.dist-info/RECORD

@@ -0,0 +1,26 @@
+firmwareloop-0.0.8.dist-info/licenses/LICENSE,sha256=V41Md7EKIAQ1Hn1kf7qgPPo3zAG8xNWLIzAiZMlo3vc,1087
+tools/__init__.py,sha256=onACRqToXs78m8hf-JoyfgW9mmriX0J7BnuBscuDwXA,105
+tools/acceptance-scenario.ps1,sha256=W2LaF8bBQjp6VcpeRuGpf0LA4hlokF4F16DzTbq0CX0,22818
+tools/build.ps1,sha256=FE8LBy-wxrSItlvif0sxySEG_GOAVC0pyMX1e-nHf1Q,8968
+tools/can.ps1,sha256=oVUT_3SQCZTf_eICZcDqTtzkvm-ErUccwBZCX-Geets,6540
+tools/check-qoder-mcp.ps1,sha256=HOufFkrJDJfMnJ03K8LuJyXzBcSHV_yyJ4EfEJMpyPs,4929
+tools/doctor.ps1,sha256=VMqK_zd4DcLkJzbHscZ_PWdK6qSCpDGmij9oNR2gXlM,6279
+tools/flash.ps1,sha256=FfM39T-q2272nBt5hRNESQ_HIAOmJNIV2mvlB9qB5oA,9388
+tools/fw_mcp_server.py,sha256=z-LpgdzdoOuRKUSku7YgfzBGPS2arnpX8lD1mj5A0Cw,49132
+tools/instrument_cli.py,sha256=R-sthWR_pGaigWzNO9qQrqcBknn8iG_1tPlEjEyQJ3w,19398
+tools/logic_capture.ps1,sha256=VulFBErO7U0Hk9-NC-JxHlwTdfAPBTeFgo2FYGhW01g,11021
+tools/logic_decode.ps1,sha256=hxbHT3_lWNR_zfZFxC_qSj-SHgLDlJcavtxRgF8-GfE,13661
+tools/reset.ps1,sha256=F4lcHhg8fKodXndvCjeFpMk1qmiYMovoFEWiZspREKQ,6993
+tools/setup-agent-mcp.ps1,sha256=DTsxS80gHfDnJARL0mgoJeoO_KSYBo2kBdAt7tpKH5o,5870
+tools/test-backends.ps1,sha256=X3FDQ5jKNs4HNoNV6hzZTkSAZi58xL_IrV6ZpUFiXGY,5275
+tools/test.ps1,sha256=sQS8xxWvGdUKtXAt6G0Kol-qayRBmI8G2yQBBASHhTk,8141
+tools/common/build-backends.psm1,sha256=AuLVAQV2PaFXooRx5_6qYNE1BBQDdtNWYdJiPKg9E-I,14035
+tools/common/fw.psm1,sha256=QKONiQR5WiG62bnUBXim09sUrN9rraoCNNrJ_tUlIT8,11312
+tools/common/uart_probe.py,sha256=Wroj2JLQ3bhrteC2wb4s5zCO7763ChTnz-2YTRrl8z4,3139
+tools/lib/__init__.py,sha256=ol9R5bqElha14dNZDGX_i7JKLqkyRWWeL9qNkUNxuOE,43
+tools/lib/instruments.py,sha256=hk1kOof5rQa8m4MMWh69iCbnCNhKqkLGXzptZgzLHY8,6728
+firmwareloop-0.0.8.dist-info/METADATA,sha256=yBCKpP1Q93ErxG7d_8plck0tBEElO1KUNcwBUdX7GqA,13336
+firmwareloop-0.0.8.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+firmwareloop-0.0.8.dist-info/entry_points.txt,sha256=4ahknDf3pWg7dVQVnLd1tR92a45StWjeA0au5mapPY8,156
+firmwareloop-0.0.8.dist-info/top_level.txt,sha256=Ib4ZA2MPBpiT0tC-0qt5RcP9g42gLddRbx9PiYGa-Fc,6
+firmwareloop-0.0.8.dist-info/RECORD,,

firmwareloop-0.0.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

firmwareloop-0.0.8.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+firmwareloop = tools.fw_mcp_server:main
+fw = tools.fw_mcp_server:main
+fw-mcp = tools.fw_mcp_server:main
+fwloop = tools.fw_mcp_server:main

firmwareloop-0.0.8.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeffrey1799
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firmwareloop-0.0.8.dist-info/top_level.txt

@@ -0,0 +1 @@
+tools

tools/__init__.py

@@ -0,0 +1,5 @@
+"""
+FirmwareLoop - AI Agent Firmware Development and Lab Automation Platform.
+"""
+
+__version__ = "0.0.8"