<div align="center">

# MKLink AI Probe

**嵌入式一站式调试工具** — 固件烧录 · RTT 可视化 · 内存读写 · HardFault 解码 · Modbus RTU · 远程 GUI

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://python.org)
[![Vue](https://img.shields.io/badge/Vue-3-4FC08D?logo=vue.js&logoColor=white)](https://vuejs.org)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[功能概览](#功能概览) · [快速开始](#快速开始) · [高速内存协议](#高速内存协议-dump-memory--flush-memory) · [探针固件](#探针固件-mk-firmware) · [命令速查](#命令速查) · [架构](#架构)

</div>

---

## 功能概览

| 功能 | 说明 |
|------|------|
| **固件烧录** | 一键烧录 Keil/IAR 工程产物（HEX/BIN），自动检测 MCU 与 FLM |
| **RTT 实时捕获** | SEGGER RTT 数据流捕获，内置波形可视化（RTT View / VOFA+） |
| **SuperWatch** | 高频变量连续采样与实时 Web 波形图（支持 `--dump-mem` 高速协议） |
| **高速内存协议** | `dump-memory` 二进制帧采集（固件 B1 自动分块）；`flush-memory` 静默写入 |
| **内存读写** | RAM / Flash / 寄存器读写，十六进制查看器 |
| **探针固件管理** | 内置 V3/V4 匹配 `.uf2`，连接时自动版本检查与升级指引 |
| **符号与类型** | 通过 DWARF/ELF 解析 AXF 符号表、结构体、枚举定义 |
| **HardFault 解码** | Cortex-M Fault 寄存器自动解码，addr2line 源码定位 |
| **Modbus RTU** | 完整 Modbus 调试：扫描、读写、轮询、点表生成、Web Dashboard |
| **串口调试** | 通用 UART 终端，支持自定义协议 Profile |
| **远程 GUI** | FastAPI 后端 + Vue 3 SPA，浏览器即用 |
| **Tauri 桌面** | Rust 桌面应用，Python sidecar，原生窗口体验 |
| **AI Agent 集成** | Claude / Cursor / OpenAI Agent 通过 Skill + CLI 直接操控硬件 |

## Screenshots

<table>
  <tr>
    <td align="center"><b>ConfigView — 工程配置与设备连接</b></td>
    <td align="center"><b>Dashboard — RTT 实时波形可视化</b></td>
  </tr>
  <tr>
    <td><img src="mklink-ai-probe/docs/gui-config.png" width="480" /></td>
    <td><img src="mklink-ai-probe/docs/gui-dashboard.png" width="480" /></td>
  </tr>
  <tr>
    <td align="center" colspan="2"><b>SuperWatch — 高频变量实时监控</b></td>
  </tr>
  <tr>
    <td align="center" colspan="2"><img src="mklink-ai-probe/docs/gui-superwatch.png" width="480" /></td>
  </tr>
</table>

## 快速开始

### 安装为 opencode Skill

如果要让 opencode 自动触发本 Skill，需要把 `mklink-ai-probe/` 注册到 opencode 的 skills 搜索路径。任选一种方式：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": ["./mklink-ai-probe"]
  }
}
```

也可以把 `mklink-ai-probe/` 复制到项目级 `.opencode/skills/mklink-ai-probe/`，或全局 `~/.config/opencode/skills/mklink-ai-probe/`。

修改 skill、agent、plugin 或 `opencode.json` 后需要重启 opencode，运行中的 session 不会热加载配置。

### 给 AI 的一句话

> 请读取 `mklink-ai-probe/` 目录，安装 Mklink AI Probe Skill，并帮我初始化嵌入式调试环境。

### 安装

```bash
# 进入 Python 包 / Skill 目录
cd mklink-ai-probe

# 安装 Python 包（可编辑模式）
pip install -e .

# 安装 GUI 依赖（可选）
pip install -e ".[gui]"

# 典型工作流
python -m mklink project-init   # 自动检测 Keil/IAR 工程、MCU、COM 口
python -m mklink flash          # 烧录固件
python -m mklink rtt --duration 10   # 捕获 RTT 数据
```

AI 会先读取 [`mklink-ai-probe/SKILL.md`](mklink-ai-probe/SKILL.md) 和对应 `references/` 文档，再选择 CLI 命令执行。

启动 GUI：`python -m mklink gui`（浏览器）或 `cd mklink-ai-probe/gui && npx tauri dev`（桌面应用）。

> 手动安装说明见 [mklink-ai-probe/references/install.md](mklink-ai-probe/references/install.md)。

## 高速内存协议（dump-memory / flush-memory）

V3.3.1 / V4.3.1 探针固件新增 `cmd.dump_memory` 与 `cmd.flush_memory` 公共 API。

### dump-memory — 高速采集（固件侧自动分块）

调用 `cmd.dump_memory(addr, size, ..., period)`，返回 `MPMDMPMD` 二进制帧：

| 协议 | 触发条件 | 说明 |
|------|----------|------|
| **OLD** | 单次总量 ≤ 2048 B | 单帧返回全部数据 |
| **B1** | 单次总量 > 2048 B | 固件按 **2048 B/block** 自动分块；CLI 重组后计为 1 个完整样本 |

- 单次上限 **32 KiB**（多 region 合计）；支持最多 16 个 region（`ADDR:SIZE`）
- SuperWatch `--dump-mem` 优先走此协议，不支持时回退 `read_ram` 轮询

```bash
python -m mklink dump-memory 0x20000000:16              # OLD 帧
python -m mklink dump-memory 0x08020000:2049            # 触发 B1 分块
python -m mklink dump-memory 0x20000000:16 --period 0.01 --frames 10
```

### flush-memory — 静默写入（适合与 dump 并发）

成功时**不输出 hexdump**，不会污染 `dump-memory` 二进制流（`write-ram` 会打断帧解析）。

| 场景 | 推荐边界 |
|------|----------|
| 单地址 `ADDR:BYTE,...` | 1~16 字节稳定（varargs 上限约 20 B） |
| 多地址一次提交 | ≤ 8 个地址项，单块 ≤ 12 KB |

```bash
python -m mklink flush-memory 0x20010000:0xDE,0xAD,0xBE,0xEF
python -m mklink flush-memory 0x20010000:0x11,0x22 0x20010100:0x44,0x55 --verify
```

> 边界详情：[references/flush-memory.md](mklink-ai-probe/references/flush-memory.md) · 命令总览：[references/commands-memory.md](mklink-ai-probe/references/commands-memory.md)

## 探针固件（MK-Firmware）

| 文件 | 适用探针 |
|------|----------|
| `MK-Firmware/MicroLink_V3.3.1.uf2` | MicroLink V3 |
| `MK-Firmware/MicroLink_V4.3.1.uf2` | MicroLink V4 |

`firmware_check.py` 在 `project-init` 和 GUI 连接时自动比对探针版本，过低时提示拖入同 major 号的 `.uf2` 升级。`dump-memory` / `flush-memory` 需 V3.3.1 / V4.3.1 及以上固件。

```bash
python -m mklink version       # 查看当前探针固件版本
```

可通过 `MKLINK_FIRMWARE_DIR` 环境变量覆盖固件目录。

## 命令速查

| 命令 | 说明 |
|------|------|
| `project-init` / `project-info` | 初始化 / 查看项目配置 |
| `flash` | 一站式烧录（连接 → IDCODE → FLM → 烧录） |
| `version` | 读取烧录器固件版本 |
| `rtt` / `rtt-integrate` / `rtt-find` | RTT 捕获 / 源码集成 / 地址查找 |
| `read-ram` / `write-ram` / `read-flash` / `read-reg` | 内存与寄存器读写 |
| `dump-memory` (`dump`) | 高速二进制帧采集（B1 自动分块） |
| `flush-memory` | 静默写 RAM，适合与 dump 并发 |
| `vofa` / `watch` / `superwatch` | 变量观测与高频采样 |
| `symbols` / `typeinfo` / `memmap` | AXF 符号、DWARF 类型、段表分析 |
| `hardfault` | Cortex-M Fault 寄存器解码 |
| `halt` / `resume` / `step` / `break` | CPU 停止、恢复、单步、硬件断点控制 |
| `autostart` | 生成上电自动启动 RTT 配置 |
| `modbus` | Modbus RTU 调试（scan/read/write/poll/dashboard） |
| `serial` | 通用串口调试 |
| `resources` | 本地资源管理（释放 stale 串口锁） |
| `serve` | 远程调试 REST API 服务器 |
| `gui` | 启动 Web GUI（FastAPI + Vue） |
| `discover` | 发现 MKLink 探针端口 |

完整命令文档见 [mklink-ai-probe/references/](mklink-ai-probe/references/) 目录。

## 架构

```
┌─────────────────────────────────────────────┐
│              浏览器 GUI (预构建 Vue SPA)       │
├─────────────────────────────────────────────┤
│         FastAPI 服务 (REST + SSE + WS)       │
│               port 8765                     │
├─────────────────────────────────────────────┤
│         Device / DeviceDispatcher            │
│      MKLinkSerialBridge (pyserial)          │
│            进程级 SerialLock                 │
├─────────────────────────────────────────────┤
│         MKLink 探针 (USB CDC)               │
│              SWD / JTAG                     │
├─────────────────────────────────────────────┤
│         目标 MCU (ARM Cortex 内核)           │
└─────────────────────────────────────────────┘
```

**两种使用方式：**

- **CLI 模式** — `python -m mklink <command>`，适合脚本化和 AI Agent 集成
- **GUI 模式** — 浏览器窗口，可视化操作

## 开发构建

工作目录为 `mklink-ai-probe/`（含 `pyproject.toml` 的 Skill 根目录）。

### Python 包

```bash
cd mklink-ai-probe
pip install -e .                    # 基础安装
pip install -e ".[gui]"             # 含 GUI 依赖
python -m mklink serve --port 8765  # 启动 API 服务
```

### Web GUI

```bash
cd mklink-ai-probe/gui
npm install
npx tauri dev                       # 开发模式
npx tauri build                     # 生产构建（MSI + NSIS）
```

> Tauri 构建需要 Rust 工具链和 MSVC Build Tools，详见 [references/install.md](mklink-ai-probe/references/install.md)。

### 测试

```bash
# CLI smoke test
python -B -m mklink --help

# Python 语法扫描（不写入 __pycache__）
python -B -c "import pathlib; [compile(p.read_text(encoding='utf-8-sig'), str(p), 'exec') for p in pathlib.Path('.').rglob('*.py')]; print('syntax ok')"

# 完整测试（如已安装测试依赖）
pytest                              # Python 单元测试
cd gui && npm test                  # 前端单元测试
```

## 可选依赖

| 工具 | 用途 | 安装 |
|------|------|------|
| `arm-none-eabi-readelf` / `arm-none-eabi-addr2line` | AXF 符号解析、DWARF 类型查询、HardFault 源码定位 | `winget install Arm.GnuArmEmbeddedToolchain` |
| `pymodbus` | Modbus RTU 调试 | `pip install -e .` 会自动安装 |

## 支持的 MCU

支持所有 **ARM Cortex 内核** MCU（Cortex-M / Cortex-A 等），通过 MKLink 探针的 SWD/JTAG 接口连接，不限于特定厂商或型号。

- 探针自动读取芯片 IDCODE，匹配烧录算法（FLM）
- 内存映射、Flash 参数等通过 `mklink/mcu_profiles.json` 配置，可按需扩展
- 已内置多厂商常用型号配置（ST、Nationstech、GD、MM32 等），新芯片只需添加对应 profile

## 项目结构

```
mklink-ai-probe/
├── SKILL.md                  # AI Agent Skill 入口
├── agents/                   # AI Agent 配置
├── mklink/                   # 核心 Python 包
│   ├── cli.py                # CLI 命令调度
│   ├── dump_memory.py        # dump_memory 二进制帧解析（OLD + B1）
│   ├── firmware_check.py     # 探针固件版本检查
│   ├── flash.py / rtt.py / superwatch.py
│   ├── remote/               # FastAPI 远程服务
│   ├── modbus/               # Modbus RTU
│   └── serial/               # 串口通信
├── gui/                      # Vue 3 + Tauri GUI
├── references/               # 命令与安装文档（AI 按需读取）
├── MK-Firmware/              # MicroLink 烧录器固件 (.uf2)
└── scripts/                  # 示例脚本
```

## License

MIT License
