# MCUDebugforAI — 给 AI 用的 MCU 编译/调试器

为 AI 智能体设计的 MCU 编译/调试工具（交互习惯参考 Keil uVision 等传统嵌入式
IDE，方便工程师零成本上手）：所有能力通过统一 op 接口开放
（CLI / MCP / TCP 自控端口 / GUI 四通道同源），让 AI 能自主完成
编译 → 下载 → 断点 → 采样 → Flash 反读取 的完整调试闭环，人通过 GUI 实时看到
AI 的每一步操作（人机联调同账本）。

## 功能

- **编译**：Keil UV4 命令行封装，编译日志解析回执
- **调试**：断点（行级/使能失能）、观察点、语句级单步、运行控制、寄存器
- **采样**：断点自动采样循环、运行态 live 采样，数据落盘回执路径+摘要
- **Flash**：反读取（bin+hex 双格式）、与本地固件比对、全片 dump（三重验证门+降速阶梯）
- **芯片**：CPUID 判内核（M0/M3/M4/M7/M33）+ 家族容量寄存器（F1/F4/H7/F7 布局）
- **符号**：DWARF 源码定位（Go To Definition/Reference）、结构体/数组树形展开
- **源码**：文件树、头文件包含展开、单文件/全工程搜索
- **GUI**：调试工作台（参考 Keil uVision 交互习惯：代码阅读器+断点红点+Watch 树+状态总线自动跟随）

## 双探针后端

| 后端 | 探针 | 说明 |
|---|---|---|
| J-Link | SEGGER | 全功能首选（pylink 封装） |
| pyOCD | ST-Link/CMSIS-DAP | 内存/下载；F4 寄存器建议走 J-Link |
| mock | 无 | 无板演示/CI 全链演练 |

## 快速开始

```bash
pip install -r requirements.txt
python selftest.py                 # 无板自测（应全 PASS）
python main.py                     # 启动 GUI
python cli.py ai '{"op":"help"}'   # AI 冷启动：接口自描述
python mcp_server.py               # MCP stdio 服务（工具面自动生成）
```

## AI 接入（MCP）

MCP 工具面由 op 注册表自动生成（`dbg.connect`→`dbg_connect`）。
AI 冷启动第一调 `{"op":"help"}` 即可拿到全部可执行示例；
接口唯一权威清单见 `docs/API.md`。

## 无板演示

内置 mock 引擎（64KB Flash 模拟+演示固件循环+变量演化），
selftest 与 GUI 全链可无板跑通。

## 商标声明

本工具为独立开发的开源软件，与 ARM、Keil、SEGGER 无任何隶属、合作或背书关系。
Keil、MDK、uVision 为 Arm 及其关联方的商标，SEGGER、J-Link 为 SEGGER Microcontroller
的商标——文中提及仅用于描述本工具的兼容性（指示性使用），不构成对这些商标的
任何权利主张。用户需自行持有相应工具链（Keil MDK、J-Link 驱动等）的合法授权。

## License

MIT