mcu-debug-mcp

mcu-debug-mcp · 嵌入式调试 MCP（领域级）

让 AI"看到并看懂"你手上的板子：串口读写 + 故障模式库（45 条规则）+ 烧录失败模式直译 + Modbus 帧解析 + 编译报错解析 + 引脚冲突检测（三引擎）+ 板级知识库 + 波特率自动探测 + AT 序列回归 + 双口对录 + 会话持久化 + RTT 通道 + 烧录桥接 + 寄存器位域解码 + 调试器探测 + 预验证驱动模板库（9 款）+ 器件选型库（按接口/地址/时序要求） + 外设 API 用法层（初始化顺序硬要求） + 错误码统一查询（6 张表·带出处） + 报文解析（自定义二进制帧 / NMEA-GPS） + 工程结构与工具链探测 + 会话日志治理与交付报告。共 59 个工具 + 16 个 MCP resources + 6 个 prompts（8 静态 resources + 8 模板 resources）。

和"直接问 AI"的本质区别：AI 不再听你转述"传感器好像不太对"，而是亲自读到串口里的真实字节——AT 指令返回了什么、数据是全 0 还是乱码、程序是不是在反复重启、Keil 为什么烧不进去——然后按出厂预置的故障模式库给出诊断和排查步骤。引脚分配前用数据手册级映射表核对（能抓 AI 幻觉接线）。驱动代码来自验证过的模板库（纯函数 PC 可测 + Python 交叉验证），不是 AI 现编的。

安全与隔离：默认不碰硬件

这个 MCP 的工具会真的打开串口、写字节、烧 flash。开发机上常年挂着正在使用的设备 （UART 桥、调试器 CDC 口、正在跑的调试会话），一次误调用就能打断它们。所以默认档位是只读：

项	默认	说明
隔离档位	readonly	读/枚举允许；写串口、AT、波特率扫描、双口对录、烧录一律拒绝，并在拒绝信息里写清「为什么拒 + 什么风险 + 怎么放开」
端口名单	未设置	MCU_DEBUG_MCP_PORT_DENY=COM6,COM28 把你在用的口锁死（支持 * 通配，DENY 优先于 ALLOW）
不可逆操作	双闸门	烧录要 dry_run=False 且 confirm=True 才会写 flash；只给预览
测试隔离	强制	测试进程锁 readonly + 端口全禁 + 真实串口构造被替换；跑测试不会碰你的设备

MCU_DEBUG_MCP_MODE=write              # 放开写权限（做真机操作时）
MCU_DEBUG_MCP_PORT_DENY=COM6,COM28    # 把在用的口锁死（即使放开了写权限也打不开）
MCU_DEBUG_MCP_NO_TOUCH_DTR=1          # 打开端口时不翻转 DTR/RTS，尽量不触发开发板自动复位

完整的风险矩阵（每个操作会做什么、需要什么才能执行、哪些操作没纳入闸门及原因）见 SECURITY.md。随时可用 env_status 查当前档位、名单与「因此被禁用了哪些操作」。

与同类工具的差异（2026-09 竞品调研结论）

同类串口 MCP（qarnet/serial-mcp、mcp-serial、uart-mcp 等）只做「串口通道」；本项目的差异化在知识层：

能力	串口通道类 MCP	本项目
串口读写	✅（普遍更全）	✅ expect 模式等待响应
日志分析	❌ 把原始日志丢给 LLM 现看	✅ 45 条模式库（30 内置 + 15 外置），规则出厂预置+带排查步骤
烧录失败诊断	❌	✅ ST-Link 连接失败/Keil 找不到算法/esptool 进不了下载模式/RDP 读保护…8 条规则族
错误码查询	❌	✅ error_code_lookup：ESP-IDF esp_err_t / ESP-AT 通用响应 / CWJAP / CME / PubSubClient rc / Modbus 异常码，共 6 张表 51 条，每条带出处；未收录明说查不到
编译/链接报错解析	❌	✅ gcc / Keil / armcc / MSVC 四种风格
引脚冲突检测	❌	✅ pin_check 三引擎：F1 固定复用 / F4 AF 表 / ESP32 io_mux 硬约束，可交叉板载外设
板级知识库	❌	✅ board_get：板载外设占用+坑清单按翻车率排序+供电说明（蓝药丸/黑药丸已收录）
会话持久化	❌	✅ 串口会话自动落盘 logs/，隔多少轮对话都能 sessions_list + sessions_get 回看现场
波特率自动探测	❌	✅ baudrate_autodetect 逐档评分排序（支持离线日志样本评分）
AT 批量回归	❌	✅ at_sequence 逐条断言 PASS/FAIL + serial_pair_record 双口对录时间线
预验证驱动库	❌	✅ 9 款，纯函数分离+交叉验证+坑清单+答辩加分点
寄存器位域解码	embedded-mcp 有	✅ 支持手工 fields + CMSIS-SVD 文件
RTT 通道	❌	✅ rtt_read（pyocd 桥接，实验性）
知识库质量保障	❌	✅ validate_knowledge.py 机械核验（引脚数/唯一性/复用唯一/正则可编译），CI 可挂
知识库可扩展	❌	✅ 故障模式/错误码表/引脚映射/板级知识全部 JSON 外置，社区可贡献（逐条标 source）

工具清单（59 个）

工具	功能	依赖
serial_list	枚举串口，识别 CH340/CP2102/FT232 并给驱动建议	pyserial
serial_open / serial_close	打开/关闭串口（返回句柄；会话日志自动落盘，落点见 env_status）	pyserial
serial_read	读数据（expect 正则命中即返回 + idle_ms 静默超时 + 总超时），文本+HEX 双视图	pyserial
serial_send	发指令（AT 自动加 \r\n；支持 HEX；expect 等响应），自动读回	pyserial
serial_session_log	取全量会话日志	pyserial
sessions_list	列出已落盘会话日志（新→旧），隔轮次可回看	无
sessions_get	回看指定会话日志内容（默认尾部 200 行），可喂 analyze_log	无
logs_prune	会话日志保留策略与清理入口（默认 dry-run 只列不删；真删需 write 档 + confirm=True）	无
baudrate_autodetect	波特率自动探测：逐档采样评分排序给推荐（log_text 可离线评分）	pyserial
at_sequence	AT 指令序列批量回归：逐条正则断言 PASS/FAIL/TIMEOUT + 回显尾	pyserial
serial_pair_record	双口对录：两串口时间线交错录制（RS485 主从/双机对话），文本+HEX	pyserial
analyze_log	45 条故障模式分析（见下），每条给人话诊断+排查步骤	无
modbus_crc	Modbus RTU CRC16 计算/校验（RS485 毕设）	无
modbus_parse	Modbus RTU 帧解析：拆寄存器值/线圈，异常响应直译异常码 01-06	无
error_code_lookup	错误码统一查询（esp_idf / at_common / cwjap / cme / modbus_exception / mqtt_rc）：释义+排查方向+出处；未收录明说查不到、不猜	无
pin_check	引脚冲突检测（三引擎）：幻觉接线/同功能双占/SWD 挪用/remap 档/ESP32 硬约束/板载外设交叉	无
pinmap_list / pinmap_get	引脚知识库浏览（列表 / JSON 原文）	无
board_list / board_get	板级知识库：板载外设+坑清单+供电说明（bluepill / blackpill_f411 / esp32_devkitc32）	无
probe_list	探测调试器与目标芯片	pyocd（可选）
rtt_read	RTT 通道读日志（⚠ 实验性，固件需含 SEGGER RTT 控制块）	pyocd（可选）
flash_tool_detect	检测本机烧录工具	无
flash_firmware	烧录固件，桥接 STM32_Programmer_CLI/esptool/st-flash/pyocd，默认 dry-run；烧完自动复位	各工具（可选）
driver_list / driver_get	预验证驱动模板库（9 款，含接线表+验证记录）	无
driver_wiring	驱动接线知识库：接线表+头号坑+日志解读+答辩加分点	无
component_list / component_get	器件选型库：按接口（i2c / uart / timer_pwm / gpio_timing）列器件，带 7 位地址、微秒时序要求、头号坑、出厂验证记录；数据全部派生自预验证驱动库的 meta.json 与 *_port.h，零凭记忆条目	无
peripheral_api_list / peripheral_api_get	外设 API 用法层：每个驱动要占哪些外设（I2C1 / TIM1 / UART2…）+ 初始化顺序硬要求（取自适配层注释原句，如「工程里先完成 HAL_I2C_MspInit 与 hi2c1 初始化」）	无
decode_register	寄存器值按位域拆解	无
decode_register_svd	按 CMSIS-SVD 文件解码位域（含枚举提示）	无
decode_fault	Cortex-M 故障寄存器解码（CFSR/HFSR/BFAR/MMFAR）：20 位逐条给人话成因+排查；三类陷阱在输出里强制拦截（见下）	无
parse_map	.map 解析（GNU ld / Keil / IAR）：段占用 + 最大符号 + 栈深线索；认不出格式就说认不出，不猜；主机 map 会报警	无
symbol_lookup	地址→符号反查：给出函数名+偏移；越界/落在空隙/野指针拒绝硬套函数名	无
stack_unwind	栈回溯：硬件 8 字栈帧还原调用链 + EXC_RETURN 判栈类型（MSP/PSP、标准/扩展帧）+ 跑飞识别	无
env_status	环境自检：依赖 / 串口（含 VID:PID 识别与 Unix 权限）/ 烧录器 / 知识库根与条目数 / 版本，一次问清；探不到的会明说为什么探不到	无
ecosystem_list / ecosystem_get	生态/框架识别知识库（Zephyr / RT-Thread / PlatformIO / Keil / IAR / Rust defmt）：识别特征 + 构建产物 + 日志签名 + 各自的坑，条目级带出处	无
project_detect	工程结构识别：按标志文件/后缀认生态（platformio.ini / *.uvprojx / prj.conf / Cargo.toml…），只探一层（避免 vendor/ 误判）；认不出明说该看什么	无
toolchain_status	工具链探测：编译器 / GDB / SDK 逐个探版本；「未发现」不等于环境坏了——会说明 IDE 自带工具不一定暴露到命令行	无
report_session	交付物生成：会话日志 → Markdown 报告（故障分析 + 原始日志附后）；目标已存在不默认覆盖	无
nmea_parse	NMEA 0183 解析（GPS/北斗）：GGA/RMC/GSA/GSV/VTG/GLL 逐句给人话（经纬度度分+十进制/定位质量/星数/HDOP/速度）；每句验 XOR，不过的明说不可信；非 NMEA 行单独点名跳过	无
frame_parse	通用二进制帧解析：帧头 + 长度字段切帧，支持 sum8 / CRC16-Modbus；校验字节不计入长度字段（Modbus 就靠这条）；切不动/截断/垃圾字节逐条报出，绝不静默丢	无
chip_info	芯片身份与存储信息：型号 / Device ID / 修订 / 内核类型 / Flash 容量 / 96 位 UID / 选项字节（读保护、TZEN、写保护组）；默认 hotplug 档不复位不停内核，要 UID 得显式 mode="full"（会复位目标，受隔离层管辖）	STM32_Programmer_CLI
reset_reason	复位原因 + 内核运行状态：RCC_RSR 逐位直译（引脚/欠压/软件/看门狗/低功耗）并给可执行建议；讲清标志是「累积」的——多个位同时为 1 ≠ 一次同时发生；clear_flags+confirm 支持「清 → 复现 → 再读」定位这一次	STM32_Programmer_CLI
flash_verify	烧录后逐字节校验：把文件与芯片上实际内容比对，报出首个不一致的偏移 + 绝对地址 + 前后 8 字节上下文；支持 .bin / .hex / .elf（ELF 按段表偏移取值）；只读走 hotplug	STM32_Programmer_CLI
timing_analysis	时序/数据率分析：丢帧（序号跳号）、卡顿（间隔离群）、节拍漂移（累计变化量 vs 实际离散度）；窗口不足一个时间戳刻度时明说不给指标，不编数据率	无
stream_capture	长时录测：串口持续采集，按到达时刻逐行打时间戳落盘（无时间戳 = 时序信息永久丢失）；产物可直接喂 timing_analysis(path=...)；重名不覆盖旧现场	pyserial
bridge_probe	桥自检：确认那块跑桥固件的 MCU 活着、认 MCUDBG/1 协议、支持哪些总线——纯握手不碰总线；绝不自动扫口找桥（实测过往别人正在跑的固件里灌探测字节的后果）	pyserial
i2c_scan	I2C 总线扫描：逐地址 ACK 探测，给出 7 位地址 + 读/写地址 + 可能的器件提示（最小表，逐条来自器件数据手册，只提示不判定）；扫不到时给 5 步排查清单（上电/接反/上拉/复用器/共地）	桥固件 + pyserial
i2c_read_reg	I2C 读寄存器（"这颗 IMU 活着吗"第一动作）；读回全 0 / 全 0xFF 分别给不同的成因清单，不代用户判"器件坏了"	桥固件 + pyserial
i2c_write_reg	I2C 写寄存器，可选 verify=True 回读比对（默认关：只写寄存器回读必然不一致，默认开会造成假 FAIL）；7 位地址校验拦下 8 位写地址	桥固件 + pyserial
spi_scan	SPI 扫描：逐 CS 读 JEDEC ID（0x9F），解厂商/容量；明说 SPI 没有地址概念，扫不到传感器/ADC 属正常；空槽（全 0/全 1）如实区分"读回全 0"和"MISO 悬空"	桥固件 + pyserial
spi_read_reg	SPI 按命令字读 N 字节（0x9F 读 JEDEC / 传感器 WHO_AM_I 都通用）	桥固件 + pyserial
onewire_scan	1-Wire 搜索 ROM（AN187 算法 + CRC8 校验）：列出 ROM 码并解家族码（DS18B20 等）；搜不到先怀疑数据线缺 4.7k 上拉	桥固件 + pyserial
rs485_send	RS485 发送（桥负责 DE 时序）；输出里强制写明"只证明发得出去，不证明对端收到"——不当成链路已通的证据	桥固件 + pyserial

总线工具需要一块跑 MCUDBG/1 桥固件的 MCU 当执行端：固件源码在 tools/bridge_fw/ （NUCLEO-H563ZI 现成，附"编译 → 烧录 → 真机验证 → 自动恢复原固件"一条龙脚本）。 为什么不自动扫串口找桥、为什么 SP-Link bridge 和 FT2232H 走不通，见 core.py 总线工具区块头注释。 |

MCP resources（16 个：8 静态 + 8 模板）

知识库只读浏览，AI 可主动引用——每类知识都是「清单 + 明细」两段：清单看有哪些，明细读原文（条目级 source 出处一并可见）。

知识库	清单	明细
预验证驱动	mcu://drivers	mcu://driver/{name} · mcu://wiring/{name}（接线）
器件选型库	mcu://components	mcu://component/{name}（选型详情+接线坑）
外设 API 用法	mcu://peripheralapis	（取自各驱动 *_port.h，随驱动走，无独立明细资源）
引脚复用映射	mcu://pinmaps	mcu://pinmap/{mcu}（pinmap JSON 原文）
板级知识	mcu://boards	mcu://board/{name}
错误码直译表	mcu://errcodes	mcu://errcode/{table}（整表 JSON 原文）
故障位域表	mcu://faultbits	mcu://faultbits/{arch}（如 cortex_m，两种写法都认）
生态/框架识别	mcu://ecosystems	mcu://ecosystem/{name}（如 keil、rtthread，显示名模糊匹配）

pin_check 三引擎

engine	适用	检查逻辑
fixed_mux	F1 系列（stm32f103c8t6）	固定复用表：功能默认档全局唯一，remap 档提示，SWD 挪用警告
af_table	F4 系列（stm32f411ceu6）	AF 复用表：一功能可映射多脚，按表核对
io_mux	ESP32 系列（esp32dev）	GPIO Matrix 任意路由，查硬约束：flash 保留脚（GPIO6-11，必砖级）/ 仅输入脚（GPIO34-39）/ strapping 脚（0/2/5/12/15）

可带 board 参数交叉检查板载外设占用（如 pin_check("stm32f103c8t6", {...}, board="bluepill")——PC13 被板载 LED 占用会警告）。

analyze_log 覆盖的模式（45 条）

内置 30 条：

总线/传感器层（13）：MOJIBAKE 乱码→波特率 · AT_ERROR · AT_NO_RESP · BOOT_LOOP · HARDFAULT+CFSR 位级解读 · SENSOR_ZERO 全 0 · SENSOR_FF 全 FF · DS18B20_85 恒 85°C · DHT_TIMEOUT · NEG_INVALID 错误码负值 · I2C_NACK · I2C_SCAN_EMPTY 扫描零设备 · ADC_SATURATED 恒满量程

ESP 生态（5）：ESP_PANIC Guru Meditation · ESP_BROWNOUT 掉电 · ESP_WDT 看门狗 · ESP_FLASH_CORRUPT 镜像损坏 · CWJAP_ERR 连 WiFi 错误码 1-4

AT/网络协议（4）：AT_CME_ERROR（3GPP 码表）· NET_LINK WiFi 断链 · MQTT_FAIL（PubSubClient rc 码表）· HTTP_ERR 4xx/5xx/curl

RTOS/系统层（4）：RTOS_ASSERT 断言 · RTOS_STACK_OVF 栈溢出 · HAL_ASSERT STM32 HAL 参数断言 · UART_FRAMING 帧错误/溢出

开发期报错（3）：COMPILE_UNDEF 链接未定义符号 · COMPILE_SYNTAX 编译错误（gcc/Keil/armcc/MSVC）· SD_INIT_FAIL

外置 15 条（knowledge/fault_patterns.json，社区可贡献）：

• 烧录失败族（8）：STLINK_CONNECT_FAIL · KEIL_NO_ALGO 找不到 Flash 算法 · KEIL_FLASH_DL_FAIL 下载失败 · OPENOCD_TARGET_FAIL · ESPTOOL_FAIL 进不了下载模式 · PYOCD_PROBE_FAIL · FLASH_READOUT_PROTECT 读保护激活 · SWD_COMM_FAIL 调试中失联
• 总线/网络族（6，v4 新增）：CAN_BUS_OFF（bus-off/error passive，终端电阻 60Ω/ACK 原理）· WIFI_RECONNECT_STORM（断连 ≥3 次计数门槛，供电头号原因）· BLE_CONN_LOST（连接参数/MTU/断开原因码 0x08/0x13）· JLINK_FAIL（克隆许可/DLL 冲突）· DNS_FAIL（DNS 配置/内网域名）· USB_ENUM_FAIL（DP 1.5kΩ 上拉/48MHz 晶振/R10）

串口报错贴进 analyze_log 一样能分析——编译报错、烧录失败日志直接粘进来就行。

预验证驱动库（9 款）

dht11（温湿度）· hcsr04（超声波）· ds18b20（单总线温度，CRC8+补码换算）· mpu6050（六轴，量程换算+静止自检）· esp8266at（AT 响应解析库，IPD 帧+错误码）· ssd1306（OLED，帧缓冲+页寻址）· servo_sg90（舵机，角度→脉宽→定时器 CCR）· stepper_28byj48（步进电机，精确减速比 63.684:1）· hc05（蓝牙 AT 助手，响应分类+命令生成）

每个驱动：纯函数与总线时序分离（PC 可测）· wiring.md（接线表+头号坑清单按翻车率排序+答辩加分点）· meta.json 如实标注验证状态。

会话持久化（"记得住"）

serial_open 自动在 logs/ 落盘会话日志（端口/波特率/时间戳元信息 + 全部收发内容），读写时实时追加。调试被中断、换会话、隔几天之后：sessions_list 列出历史会话 → sessions_get 回看现场 → 整段喂 analyze_log。只读文件系统下静默降级，不影响主流程。

安装

# 方式一：PyPI / pip（发布形态，src 正规包——不污染 site-packages 顶层）
pip install mcu-debug-mcp          # 核心（MCP 框架）
pip install "mcu-debug-mcp[all]"   # + pyserial（串口）+ pyocd（调试器/RTT）

# 方式二：从源码目录安装
pip install .[all]

# 方式三：开发模式（改代码即时生效；测试/审计直接从 src/ 导入）
pip install -e .[all]

# 装完后用 console script 起服务（等价于 python -m mcu_debug_mcp.server）
mcu-debug-mcp

客户端配置

一键安装（Claude Code / Claude Desktop / Cursor）

# Claude Code
pip install "mcu-debug-mcp[all]"
claude mcp add mcu-debug-mcp -- python -m mcu_debug_mcp.server

Claude Desktop（claude_desktop_config.json）/ Cursor（mcp.json）：

{
  "mcpServers": {
    "mcu-debug-mcp": {
      "command": "python",
      "args": ["-m", "mcu_debug_mcp.server"],
      "env": { "MCU_DEBUG_MCP_MODE": "readonly" }
    }
  }
}

默认 readonly 档：读/枚举可用，写串口、烧录等硬件操作被拒并说明如何放开。 调试需要真机写入时再加 "MCU_DEBUG_MCP_MODE": "write" + MCU_DEBUG_MCP_PORT_DENY 锁住在用的口（见上文安全表）。

WorkBuddy（三步上手）

第 1 步：装包（本机需有 Python 3.10+；没有就让 WorkBuddy 代装，见下方提示词）

pip install "mcu-debug-mcp[all]"

第 2 步：配连接器（连接器 → 自定义连接器 → 配置 MCP → 粘贴 → 保存）：

{
  "mcpServers": {
    "mcu-debug-mcp": {
      "command": "python",
      "args": ["-m", "mcu_debug_mcp.server"]
    }
  }
}

若 python 不在 PATH，把 command 换成 python.exe 全路径； 或改用 console script："command": "mcu-debug-mcp.exe" 的全路径 （pip --user 安装在 %APPDATA%\Python\Python312\Scripts\，全局安装在 Python 目录的 Scripts\）。

第 3 步：Trust 信任（连接器列表点「信任」启用）→ 新开任务说"列出 mcu-debug-mcp 下的所有工具"验证。

让 WorkBuddy 代装（复制这段发给 WorkBuddy 即可）

帮我安装 mcu-debug-mcp：执行 pip install "mcu-debug-mcp[all]"，
装好后把 {"mcpServers": {"mcu-debug-mcp": {"command": "python",
"args": ["-m", "mcu_debug_mcp.server"]}}} 写入 MCP 配置并告诉我如何 Trust 启用。

其他客户端

Claude Desktop / Cursor / Windsurf 同格式（python -m mcu_debug_mcp.server）。 Cline 安装参考本 README（llms-install 兼容）。

验证状态（2026-10-13 复验，v4.5.5）

模块	验证方式	状态
analyzer 异常模式库（30 内置 + 15 外置）	tests/test_analyzer.py：99 项断言（正例命中+计数门槛+不误报+永不抛异常）	✅ 本机实测通过
驱动纯函数算法（9 款驱动全量）	tests/test_driver_logic_py.py：49 项断言（与 C 实现同源对拍）	✅ 本机实测通过
9 款 C 驱动编译 + 逻辑测试	tests/run_c_tests.py（gcc 16.2.0 mingw64）：107 checks, 0 failed，9 款全部 -Wall -Wextra 零警告	✅ 本机实测通过
串口读写 + expect/idle_ms（loop:// 回环）	tests/test_serial_tools.py TestSerialLoop：全过 0 skip（Python 3.12 + pyserial 3.5）	✅ 本机实测通过
modbus/pin_check 三引擎/boards/sessions/RTT 降级	tests/test_serial_tools.py	✅ 本机实测通过
知识库数据核验	tests/validate_knowledge.py（引脚数/唯一性/fixed_mux 功能全局唯一/SWD 一致性/onboard pin 字段/正则可编译/条目级 source 强制）	✅ 0 错误（曾抓出 3 处 F103 录入错误）
知识库条目级溯源	15 个知识文件 250 条数据全部带条目级 source；校验器强制（注入缺 source 必报错），并有测试保证注入后文件逐字复原（防止测试改写手写排版）	✅ 本机实测通过
server.py MCP 注册层（59 工具 + 16 resources + 6 prompts）	真 MCP 客户端 stdio 握手实测：list_tools()=59 · 静态 resources=8 · 模板 resources=8	✅ 本机实测通过
MCP 协议层 + 资源层真机	16 个资源全部 read_resource 可读（8 个模板资源 driver/wiring/component/pinmap/board/ecosystem/errcode/faultbits 逐项实测，9 款驱动逐个读）；查不存在的名字一律友好拒绝并列出可选项、不抛异常；tests/test_mcp_resources.py 17 条把资源清单精确锁死	✅ 本机实测通过
符号反查 / 栈回溯（真工具链夹具）	tests/test_symbol_lookup.py 用仓库自带的 bridge_fw/main.c + linker.ld 现场编译真 Cortex-M33 ELF（复用 build.py 的工具链探测，不另写一套），与 arm-none-eabi-readelf 真值交叉核对：符号数/地址/大小逐一吻合；工具链缺失时整组 skip（CI 不红）	✅ 本机实测通过
离线全量（Python 全套 944 项）	python -m pytest tests -q：942 passed, 2 skipped（两个 skip 都需显式授权：真机 USB CDC 用例，以及「该口不是 USB CDC」的对照用例；tests/test_symbol_lookup.py 里另有 25 条在无 ARM 工具链时整组 skip，本机装了 arm-none-eabi-gcc 全部实跑；收集总数由 tests/audit_capability.py 的 pytest_collected 探针机器锁定，手改数字会被审计抓出）	✅ 本机实测通过
隔离与安全（37 条）	tests/test_isolation.py：档位/名单/不可逆确认/虚拟端口豁免/未登记操作 fail-closed，含必须放行的反例（离线打分、dry-run 预览、loop://）；另有静态对账与注入法反自证；并列 6 条守着tools/live_acceptance.py夹具自身（无端口拒跑、dry-run 不开口、DENY 不得设 *、收尾不得假 PASS、破坏关必须单独授权）	✅ 本机实测通过
排故链四工具（fault/map/符号/栈）	tests/test_fault_chain.py：67 项断言，其中 30+ 条是「必须拒绝给结论」的假答案防线；从零删掉 build_tmp 也能自举（setUpModule 现场 gcc 生成夹具）	✅ 本机实测通过
真机验收夹具（N-15）	tools/live_acceptance.py 在 NUCLEO-H563ZI（STM32H563/Cortex-M33，板载 ST-Link V3EC 虚拟串口 COM21） 上实跑：PASS 16 · FAIL 0 · SKIP 1；可反复跑不打死板子；破坏关单独授权后 3/3 PASS	✅ 真机实测通过
真机联调（硬件相关项）	见下方清单；已跑：4/6/7/8/10/11 部分 + 13（NUCLEO-H563ZI，一键全链）	✅ 部分完成（见清单标注）

MCP 真机实测抓出的四个真问题（已修，均为"看似合理的假通过"类）：

1. baudrate_autodetect 在 USB CDC 口上原理上无意义，必须先识别并短路（2026-09-21 师兄指出 ESP32 用的是 USB CDC）。 USB CDC 走芯片自带 USB 外设（CDC ACM），波特率参数不参与数据路径，各档收到的字节流完全相同 ⟹ 所谓"各档评分"只是同一批字节被反复读。 实测铁证：COM4 上同一波特率（115200）连测 3 轮全 0 字节，而另一次 9600 拿到 88064 字节——同波特率结果从 88KB 到 0，差异只来自设备当时有没有在输出。 ⟹ 该口扫档 = 在测"这次打开时设备有没有在说话"，纯随机。原实现给的"9 档同分 0.99"主因也不是采样不足（我上一版归因偏了），而是根本没有波特率差异。 修法：新增 _port_baud_relevance()，按 VID/PID 识别 CDC（303A:1001 Espressif、2E8A:* RP2040 等）与 UART 桥（0403:6010 FT2232H、10C4:EA60 CP210x、1A86:7523 CH340、1366:0105 J-Link 等），CDC 口直接短路并给出「该口不用管波特率 / 读不到别换档 / 真要判必须接独立 UART 桥听 TX 脚」三步指引；serial_open 也附同类提示。显式传 candidates 可强行扫（怀疑枚举成 CDC 实为桥的场合）。同时给 analyze_log 的 MOJIBAKE 诊断加了 USB CDC 例外（原建议「把波特率逐个换」在该口是纯无效动作）。

2. baudrate_autodetect 在真 UART 上自信地给错档（COM4 实测，判别力门禁的由来）：11 个候选里 9 个同分 0.99，工具推荐 460800，真实是 115200；而正确的 115200 反而排最低（0.071）。 根因链：① 打开串口翻转 DTR/RTS ⟹ ESP32 复位 ⟹ 每个档位收到同一段纯 ASCII ROM 启动日志；② if len(buf) > 2048: break 在应用数据到达前退出；③ 同分时稳定排序回退到候选表顺序，而候选表是降序的 ⟹ 永远推荐最高档。 修法：采样上限 2048→8192；新增 _BAUD_MIN_MARGIN = 0.10 判别力门禁——最高分与次高分差距不足门限时，明确输出「★判不出来……别照它改代码」并给手工确认步骤，而不是硬推一个。

3. at_sequence／serial_read／serial_send の expect は全文の部分文字列検索 ⟹ 誤った PASS（COM4 で実測）：デバイスは BQ27421 バッテリーメーターのファームウェアで動作しており、AT 応答はまったくありません。しかし、ログ行 I (371) led: init OK R=IO21 G=IO48 B=IO47 に「OK」が含まれているため、[PASS] と判定されます。 修正：_at_line_match() を追加し、デフォルトで 行全体を一致判定（行頭・行末の空白を許容し、re.fullmatch を使用）するようにします。また、確認しやすいよう「一致した行: …」を出力します。従来の動作が必要な場合は、そのステップに {"loose": true} を指定できます。修正後、同じ状況では [TIMEOUT] が返り、loose=true の対照群では引き続き [PASS] となります。この対照比較が決定的な証拠です。

4. pin_check の io_mux エンジン（ESP32）はピンの存在を検証しない ⟹ ピン名を誤っても「合格」：{"GPIO999": "GPIO"} に対して「✅ 任意ルーティング（GPIO Matrix）… 結論：すべて合格。この配線で接続できます」と返されます。fixed_mux エンジン（STM32）には「この MCU にそのピンはありません」というチェックがありますが、2 つのエンジンの判定基準が非対称です。入力時のタイプミス（GPI08）や、幻覚で作られたピン名でも「合格」と判定されてしまいます。 修正：io_mux 分岐にピンの存在を事前検証する処理を追加し、近似する既知のピンを列挙します。結論は「変更が必要」に変更します。

同時に存在する使い勝手の問題（コード未修正、要判断）——パラメーター名／パラメーターセットが直感に合わない： analyze_log(log_text=) は text ではありません。modbus_crc(hex_frame=) は data ではありません。pin_check(pins=) は assignments ではありません。flash_firmware(file_path=) は firmware ではありません。at_sequence(steps=) のステップ内では cmd が send ではなく、timeout_s が wait_s ではありません。 また、パラメーターセットの不整合も 1 か所ありました（修正済み）。core.baudrate_autodetect には candidates がありますが、server.py の MCP ツールのシグネチャでは公開されていませんでした。そのため、MCP クライアントから「強制スキャン」できず、ドキュメントの説明を実現できませんでした。candidates パラメーターを追加しました。 初回呼び出しで直感に頼ってパラメーター名を推測すると、失敗率が非常に高くなります（今回の実測では、7 回の推測がすべて Pydantic の検証エラーになりました）。README／ツールの説明に「間違えやすいパラメーター名の対照表」を追加するか、server.py でエイリアスをサポートすることを推奨します。

トラブルシューティングチェーン（Cortex-M 障害チェーン）の実測で見つかった本当の問題（修正済み。いずれも「一見もっともらしい誤回答」タイプ、2026-09-22）：

この一連の問題はすべて、実際の gcc で生成した 2 つの .map（ホスト x86 ＋ ターゲット ARM）を使って実行したことで初めて明らかになりました。ユニットテストでは、ハッピーパスを何度実行しても検出できませんでした。

1. symbol_lookup が 0xdeadbeef を app_state+0xbeadb817 と逆引きし、✓ を付ける。 原因：GNU ld の .map にはシンボルサイズが記録されていません。推定されたサイズが .bss セクション末尾のシンボルで 0 になるため、「オフセット < サイズの場合のみ範囲外」というチェックがスキップされ、どれほど大きなオフセットでも「シンボル内」と判定されていました。 修正：各シンボルのアドレス上限を計算します（サイズがあればサイズを使用し、なければ次のシンボルのアドレスを使用し、セクション末尾ではセクション末尾を使用）。アドレスが上限を超えた場合は関数名を返さず、「シンボルテーブルの隙間に位置する = 不正なポインター」と説明します。同じ解析ロジックを _build_bounds として切り出し、symbol_lookup と stack_unwind で共用します。これにより、片方だけ修正してもう片方が従来どおり通してしまうことを防ぎます（実測では、stack_unwind でも当初同じ誤回答が再現しました）。

2. _infer_sizes がセクションをまたいで推定し、384MB の「シンボルサイズ」を算出する。 .text セクションの最後のシンボルが、.data セクションの先頭アドレスを「次のシンボル」として扱い、0x20000000 − 0x0800039c = 402652260 を実際のサイズとして「最大サイズのシンボル」ビューに表示していました。 修正：推定時にセクションをまたぐ場合の保護（2 つのシンボルが同じセクションに属すること）と、セクションサイズの上限（推定値が所属セクションのサイズを超えないこと）を適用します。

3. ホストプログラム（x86 mingw PE）の .map を MCU ファームウェアとしてそのまま受け入れる。 出力には __mingw_module_is_dll、.idata/.rsrc/.pdata などのホスト特有の特徴が混在します。ユーザーが誤った map を使うと、無関係なシンボルが大量に表示され、自分のファームウェアのものだと思ってしまいます。 修正：_map_target_check を追加し、ホスト特有の特徴（ランタイムシンボルが 3 個以上、またはホスト専用セクションが 3 個以上）が見つかった場合、「これは MCU ファームウェアの map ではありません」と明確に警告します。また、実際の arm-none-eabi-ld 形式に合わせて固定した ARM map との逆方向の照合も追加し、正常な MCU map が誤検出されないことを確認します。

4. 挿入済みの FT2232H／J-Link が serial_list で「未登録」と表示される。 原因：core._USB_UART_BRIDGE_IDS では 0403:6010／1366:0105 を認識しますが、analyzer.USB_SERIAL_VIDPID にはこの 2 つがありませんでした。つまり、同じ VID:PID を一方では認識し、もう一方では未認識としていました。 修正：analyzer の表を補完しました（FT2232H／FT232H／CH9102 のバリエーション／J-Link CDC／RP2040／ESP32 USB-JTAG など）。また、2 つの表が分離しないように表間の一貫性テストを追加しました。

5. decode_fault が cortex-m0 を「未対応アーキテクチャ」と報告する——M0 は既知のアーキテクチャであり、CFSR がないだけです。これは「json が足りない」問題ではなく、判定経路が根本的に異なります（スタックに保存されたフレームの PC から逆引きする必要があります）。 修正：M0／M0+ 専用の分岐を設け、利用できない理由と代替手段を提示します（symbol_lookup ＋ stack_unwind はアーキテクチャに依存しません）。 関連する修正：BFARVALID=1（ビットフィールドが「有効」を示す）の場合でも、無条件に値を受け入れないようにしました。センチネル値（0xDEADBEEF、すべて同じバイト、0xFFFFFFFF、<0x100）を識別し、「ビットフィールドが有効 ≠ 値自体が妥当」と提示します。valid=0 でユーザーがそのアドレスを渡していない場合は、値を「読み取った結果のゴミ値」と断言しないようにしました（そもそも読み取っていないためです）。

テスト自体が検出した 2 つのサイレントな失敗（修正済み）：

• @unittest.skipUnless(os.path.isfile(MAP)) デコレーターはクラス定義時に評価されますが、map が生成されるのはその後の setUpModule です。そのため、map が生成されたばかりなのに 14 個のテストがすべてスキップされていました。実行時に判定する関数 _have_demo() に変更しました。
• shutil.which("gcc") が成功しても、gcc が実行できるとは限りません。msys2 の gcc は cc1／as／ld が見つからないと、rc≠0 ＋ 出力なしでサイレントに失敗します。msys2 bin を常に PATH の先頭に追加し、さらに _gcc_works() で --version を実際に実行して確認するようにしました。

1. ssd1306.h のインクルードガード（SSD1306_H）と画面高さマクロ（SSD1306_H = 64）が名前の衝突を起こしていました。ファイルガードが画面高さマクロで上書きされ、#ifdef SSD1306_H の判定が常に真になります。ガードを SSD1306_DRIVER_H に変更しました。
2. mpu6050_read_raw の uint8_t b[14] が初期化されておらず、gcc が -Wmaybe-uninitialized を報告します（スタブ関数が空実装の場合は特に顕著です）。実機では、I2C の読み取りが一部失敗すると不正なデータが残ります。= {0} に変更しました。

シリアルループバックの実測で見つかったテストコードのバグ（修正済み）：TestSerialLoop は一度も実際に実行されていませんでした。初回の実行で 3 つの問題が明らかになりました——serial_for_url("loop://") が返すオブジェクトはすでに自動で open されており、明示的に .open() を呼ぶと「Port is already open.」が発生する、setUpClass で共有されたポートを各テストが相互に close する、_get_session とメソッド名が誤っている（実際は get_session）。各テスト専用のポートを使い、addCleanup を追加する形に書き直しました。

真机验证清单（拿到有硬件的环境后）

1. pip install -r requirements.txt → python tests/test_serial_tools.py ✅ 已跑（全套 222 项 OK）
2. python tests/run_c_tests.py ✅ 已跑（9 款驱动零警告 + 107 checks 全过）
3. python tests/validate_knowledge.py ✅ 已跑（知识库核验 0 错误）
4. 插上任意 STM32/ESP 板子 → serial_list 确认识别芯片 ✅ 已跑（COM4=ESP32-S3 303A:1001，板载固件 bno085_imu V2.4.3-20260920_a023）
5. 故意改错波特率读日志 → baudrate_autodetect 扫档 → 推荐档位与真实波特率一致 ⚠️ 分两种口：① USB CDC 口（ESP32-S3/C3、RP2040 等）——波特率不参与数据路径，工具会识别并短路，拒绝给排序（这是正确行为，不是失败）；② 真 UART / 独立桥（FT2232H、CH340、CP210x、J-Link CDC）——波特率真实生效，扫档有意义。 要验证「能推荐对」，需一台非 USB CDC、且以非 115200 输出的设备接在 UART 桥上。本机 COM4 是 CDC 故只验了短路路径；COM7（FT2232H）无设备接入，扫出全 0 分并被正确提示"设备没在说话"。
6. serial_open + serial_read 读启动日志 → analyze_log 应报 MOJIBAKE ✅ 已跑（COM4 读到 114319 B 真实日志，命中 #EVT type=FAULT fault=0x02000000）
7. serial_send("AT", expect="OK", wait_s=3) 确认 expect 提前返回；at_sequence 跑一组 AT 用例 ✅ 已跑（并因此抓出假 PASS 缺陷，见上）
8. 关掉串口 → sessions_list → sessions_get → 能完整回看刚才的现场 ✅ 已跑（自动落盘 20260921_115559_COM4_h1.log 132.8 KB，可回看）
9. ESP8266 故意输错密码连 WiFi → 日志应命中 CWJAP_ERR（码 2=密码错误）⏳ 无 ESP8266 AT 固件设备
10. RS485 从站故意回异常帧 → modbus_parse 应直译异常码；serial_pair_record 对录主从对话 ✅ 已跑（modbus_parse 异常码 0x02 正确直译；serial_pair_record 用 FT2232H COM7/COM11 实跑，空数据降级提示正确）
11. 在蓝药丸上把 PB7 配成 USART1_RX → pin_check 应提示需要 remap；PC13 配 GPIO + board=bluepill 应报板载 LED 占用 ✅ 已跑（知识层三引擎全部正确；并因此抓出 io_mux 不校验引脚存在性的缺陷）
12. J-Link/DAPLink 连带 RTT 固件的板子 → rtt_read 读日志 ⏳ J-Link 在位（COM6），但本机只有 VS Code ARM 扩展自带的那份 pyocd.exe，当前解释器 import pyocd 失败，所以 rtt_read 还跑不起来。已验的是「模块缺失时如实说明、不崩」的降级路径。pip install pyocd 后可用 NRF52840 板补测（也可直接调那份 exe：pyocd list）。
13. NUCLEO-H563ZI（STM32H563 / Cortex-M33，板载 ST-Link V3EC 虚拟串口 COM21） → 一键 python tools/live_acceptance.py COM21 --allow-write --elf <fw.elf> --map <fw.map> ✅ 已跑（PASS 16 / FAIL 0 / SKIP 1；并抓出 6 个只靠离线测试抓不到的缺陷，见 CHANGELOG 4.2.0）

硬件盘点（本机实测）：COM4=ESP32-S3 原生 USB（303A:1001，跑 BNO085 IMU 固件）｜COM6=JLink CDC UART（1366:0105）｜COM7/COM11=FT2232H 双通道（0403:6010）｜COM8/COM9=蓝牙幻影口。 注意：NRF52840 板只有 SWD + SEGGER RTT，未引出 UART ⟹ 串口类清单项需用上述其他硬件；RTT 类需装 pyocd。

目录结构

mcu-debug-mcp/
├── src/mcu_debug_mcp/  # ★ 正规包（2026-10-13 C 档重构：wheel 不再污染 site-packages 顶层）
│   ├── __init__.py     # 版本单一来源（pyproject dynamic attr 从这读）
│   ├── server.py       # MCP 薄壳（FastMCP 注册 55 工具 + 13 resources + 6 prompts）
│   ├── core.py         # 全部工具实现（零框架依赖，可独立测试）
│   ├── analyzer.py     # 故障模式引擎（30 内置规则 + JSON 外置规则加载 + min_count 计数门槛）
│   ├── guard.py        # 运行时隔离层（默认禁写硬件 + 端口名单 + 不可逆操作二次确认）
│   ├── paths.py        # 数据根定位（$HOME env > ~/.mcu-debug-mcp > 包内置；外置层可合并覆盖）
│   ├── knowledge/      # 领域知识库（JSON 外置，社区可贡献；随包分发）
│   │   ├── fault_patterns.json  # 可外置故障模式规则（正则类，逐条标 source，支持 min_count）
│   │   ├── error_codes/         # 错误码直译表（esp_idf/at_common/cwjap/cme/mqtt_rc/modbus_exception）
│   │   ├── pinmap/              # MCU 引脚复用映射（数据手册级，三引擎：f103c8t6/f411ceu6/esp32dev）
│   │   └── boards/              # 板级知识库（bluepill / blackpill_f411）
│   ├── drivers/        # 预验证驱动模板 9 款（LLM 只选型，不现编代码；.h/.c/port/wiring.md/meta.json）
│   └── tools/          # live_acceptance.py 真机验收夹具（默认只读）+ bridge_fw 桥固件
│                        # + verify_stdio.py 端到端 + mutation_check.py 变异验证
├── setup.py            # 仅保留构建临时目录重定向（打包声明全在 pyproject.toml）
├── coverage.json       # 能力面清单（26 缺口 + 27 能力轴，审计脚本据此对账）
├── SECURITY.md         # 安全与隔离模型 + 破坏性操作矩阵 + 漏洞报告通道
├── pyproject.toml      # src 布局 + include-package-data + console script（v4.5.5）
├── MANIFEST.in         # sdist 收录清单（漏一行就复发「装出来是空壳」）
├── requirements.txt
├── examples/           # offline_demo.py：离线可跑的示例
├── docs/               # AUDIT-2026-10-13.md 审查报告（含修复记录）等
└── tests/
    ├── test_analyzer.py        # 101 项，✅ 已验证
    ├── test_driver_logic_py.py # 49 项，✅ 已验证（C 算法对拍）
    ├── test_driver_logic.c     # C 版同源测试，✅ 107 checks 0 failed（9 款驱动全量）
    ├── run_c_tests.py          # C 测试运行器（无需 make，自动处理 msys2 的 cc1 PATH 坑）
    ├── Makefile.logic          # C 测试 makefile（等价路径）
    ├── validate_knowledge.py   # 知识库核验脚本（CI 可挂），✅ 0 错误
    ├── audit_capability.py     # 能力面审计：广度/深度阶梯/缺口/文档对账/**隔离与安全**
    ├── audit_constants.py      # 常量一致性审计（含版本单一来源 ↔ README）
    ├── conftest.py             # 测试期强制硬件隔离（锁档位 + 禁端口 + 替换串口构造）
    ├── isolation.py            # 临时解除隔离的唯一入口（给「测笼子内部逻辑」的测试用）
    ├── test_isolation.py       # 隔离层专项
    ├── test_package_smoke.py   # 打包冒烟（真构建 sdist+wheel 双安装 + 子进程 + 剔除源码树）
    ├── stub/                   # C 测试桩（port_all.h + 各驱动桩头文件）
    └── test_serial_tools.py    # ✅ 全过（含 loop:// 回环端到端）

Windows 上的 gcc 坑（实测记录）

如果你在 Windows + msys2 下跑 C 测试遇到「gcc 明明在，但编译 rc=1 且没有任何输出」，不是沙箱也不是权限问题：

msys2 的 gcc.exe 单独执行正常（--version 有输出），但真正编译时它要 fork cc1.exe，而 cc1.exe 依赖同目录的运行时 DLL（libgmp-10.dll/libmpfr-6.dll/libisl-*.dll/libmpc-3.dll）。Windows 的 DLL 搜索路径不含 exe 所在目录（除非该目录在 PATH 里），于是 cc1.exe 崩在 STATUS_DLL_NOT_FOUND (0xC0000135)——由于崩溃发生在子进程，父进程拿不到任何 stderr，表现为「静默失败」。

验证方法：gcc -dumpmachine 能输出（驱动本身不 fork cc1），gcc -E foo.c 无输出失败（要 fork cc1）。

修法：把 gcc 的 bin 目录加进 PATH。tests/run_c_tests.py 与 Makefile.logic 都已自动处理，直接用它们即可。

贡献指南

知识库贡献（最高价值，无需写代码）

• 新增故障模式（正则类）：knowledge/fault_patterns.json 加条目（id/patterns/diagnosis/next_steps/source；需要计数门槛的加 min_count，如 WiFi 断连 ≥3 次才算风暴），无需改代码，重启生效
• 新增错误码表：knowledge/error_codes/<表名>.json（entries + source），analyzer 的 _load_code_table 挂载
• 新增 MCU 引脚库：knowledge/pinmap/<型号>.json，必填 engine 字段（fixed_mux/af_table/io_mux 三选一），来源标数据手册；不确定的字段留空并在 caveats 说明，不要编
• 新增开发板：knowledge/boards/<板名>.json（onboard 每项必填 pins 列表或 pin 单值 + note；board_issues 按翻车率排序）
• 改完必跑核验：python tests/validate_knowledge.py——它抓得出引脚数录错、功能名录错、同功能双占、正则写坏、外设条目缺引脚字段（已实测抓出 3 处 F103 数据错误）

代码贡献

• 新增驱动：drivers// 下放 <name>.h/.c/<name>_port.h/wiring.md/meta.json，meta.json 的 verified 字段必须如实写验证状态——评测员和学生都会实测
• 新增异常模式（复杂逻辑类）：analyzer.py 加规则函数+注册 RULES+_DIAG 配文案，test_analyzer.py 补正例+反例（正例命中 + 正常日志不误报，缺一不可）
• 新增工具：core.py 实现（零 MCP 依赖）→ server.py 注册（FastMCP 薄壳）→ tests/ 补用例；能离线测的必须离线可测
• 判断放哪条路：正则能匹配的走 JSON；需要计算（比例/计数/阈值）的写 Python