前言¶
在 DSH（DeepSeek Harness）里做 Cortex-M 固件开发，常见做法是让智能体调用 openocd、读寄存器、烧 flash、看串口日志。若 openocd 与 IDE 共用同一套工具树和工作区配置，容易碰到两类事故：软件断点没清干净就被「读回再烧」固化进固件；或工作区里的 ocd.cfg 被自动 source，行为不可控。另一类生态问题是工具参数的 JSON Schema 有一条不合法，整包 functions 会被 provider 拒绝，表现为「装了插件后对话全崩」。
下面介绍社区插件 dsh-mcu-debug（维护者 lishuo4096，分类：客户端）。它面向 STM32 / PY32，探针走 CMSIS-DAP / DAPLink，底层使用插件自带的 openocd 0.12.0 隔离副本，并提供串口收发；设计上尽量不改动你的 IDE 工程树与 EIDE 工具原件。
这是什么¶
dsh-mcu-debug 是 DSH 插件包名 @local/dsh-mcu-debug，在 harness 内注册的 bundle 名为 mcu-debug（index.js 中 export const name 须与 cordis.patch.yml 的 id 一致）。一句话定位：ARM Cortex-M 调试与烧录 + 串口，共 27 个以 mcu_ 为前缀的工具，并附带技能包 skills/mcu-debug/SKILL.md（触发词含 STM32、PY32、烧录、DAPLink、openocd、断点、串口等）。
- 目录页：https://www.skillhub.cn/plugins/lishuo4096/dsh-mcu-debug
- 源码：https://github.com/lishuo4096/dsh-mcu-debug
- 插件自身许可：MIT；
vendor/openocd/为 OpenOCD 原样再分发，许可为 GNU GPL v2（见仓库THIRD-PARTY.md） - 运行要求：Node.js >= 20.0.0；
package.json标明与 DSH 0.2.0-rc.2 兼容
核心功能¶
独立 openocd 与私有工作目录¶
插件在 <插件>/vendor/openocd/ 携带完整 openocd 副本（资料记载为 932 个文件 / 约 24.4 MB）。在 Windows 上还可通过 NTFS junction 映射到 %LOCALAPPDATA%\dsh-mcu-debug\openocd，避免 Jim-TCL 在含中文路径下按 GBK 解析 source [find …] 失败；junction 不可用时依次退回真实复制或原路径，并在 mcu_env 中说明。
openocd 进程的当前工作目录由 assertPrivateWorkdir() 固定在 <插件>/.run/<id>/，不会指向 IDE 树，从而不会自动加载工作区里的 ocd.cfg / init.cfg。每次运行的 argv、输出等会落盘为 session-record.txt、session.json、openocd.txt，便于事后复盘。
断点收尾与烧录安全¶
针对「断点字节残留在 flash、再烧录后程序永远进不了 main」的问题，插件在每次 openocd 调用收尾固定执行「逐个 rbp → reset run」（lib/ocd.js 的 FOOTERS），在离开目标前清断点。烧录前备份落在 <插件>/backups/；除 .run/ 与 backups/ 外，EIDE openocd 原件与目标工程源码目录按设计为只读。mcu_clean action:"audit" 可扫描私有区并报告可疑痕迹。
多探针锁定¶
CMSIS-DAP 后端在多设备并存时可能静默选错探针。插件在 lib/run.js 的 planProbe() 唯一入口向 -c 序列注入 adapter serial <序列号>，并保证 -c 顺序为：先适配器与 transport select swd，再 target cfg，再业务命令，最后收尾清断点。mcu_probes 的 probe 参数支持序列号、vid:pid、名字片段；多个同类探针同时插入时必须给序列号，给 vid:pid 会因不唯一而报错。
工具分组（27 个）¶
| 组 | 工具 |
|---|---|
| 环境（A） | mcu_env mcu_probes mcu_devices mcu_projects mcu_workspace mcu_help |
| 目标（B/C） | mcu_probe mcu_regs mcu_mem mcu_flash_info mcu_read_flash mcu_flash mcu_erase mcu_reset mcu_bp mcu_ocd |
| 会话（D/E） | mcu_session_open mcu_session_cmd mcu_session_list mcu_session_close mcu_gdb mcu_clean |
| 串口（F） | mcu_serial_list mcu_serial_open mcu_serial_tx mcu_serial_rx mcu_serial_close |
串口：PowerShell 常驻宿主¶
Node 侧无内置串口 API，插件通过 serial-host.ps1 子进程持有 [System.IO.Ports.SerialPort]，用 JSON 行协议与 lib/serial.js 通信，避免每次收发重开端口导致 DTR 拉复位。脚本会先复制到 %LOCALAPPDATA%\dsh-mcu-debug\ 再执行，以规避 PowerShell 5.1 在中文路径下 -File 失败的问题。
Schema 门禁（挂载前）¶
改过工具 parameters 后，挂载前应执行：
node .probe/gate.mjs
该脚本用 harness 的 @deepseek-ai/dsh-tools 校验器验收全部 27 个工具 schema；找不到 harness 时会报错退出。跨机器可用环境变量 DSH_TOOLS_PATH 指向 .../@deepseek-ai/dsh-tools/lib/index.js。插件在 lib/define-tool.js 中对作者侧 type:'json' 做编译，并在注册前 sanitizeSchema，降低「一条非法 schema 拖垮整会话」的风险。
安装与启用¶
插件零 npm 依赖（define-tool.js 自实现工具定义层，避免 link: 安装时找不到宿主 node_modules）。官方 README 给出的安装示例为通过 plugin_manager 安装本地 bundle：
plugin_manager({ action: "install_bundle", target: "C:\\Users\\lishuo\\Documents\\DSH_Project\\插件开发\\dsh-mcu-debug" })
请将 target 换成你本机插件根目录的绝对路径。安装后会在 profile 的 package.json 写入 "@local/dsh-mcu-debug": "link:<绝对路径>"，并把包名加入 dsh.profile.bundles。
手工挂载时，在 profile 的 dsh.profile.bundles 增加 "@local/dsh-mcu-debug"，且 dependencies 里 link: 路径指向插件根目录。
典型用法¶
智能体在挂载技能包后，可按「先环境、再探针与目标、再调试或烧录、串口看日志」推进。下列步骤对应 README 中的工具设计，可在对话中由模型调用（具体参数以 mcu_help 与各工具 schema 为准）。
- 确认环境与探针：
mcu_env查看 openocd 副本与 junction 状态；mcu_probes列出探针，多设备时记下序列号。 - 选器件与工程：
mcu_devices、mcu_projects、mcu_workspace解析 PY32 / STM32 型号与工程上下文。 - 连目标：
mcu_probe绑定探针与 target；只读可先mcu_regs、mcu_mem、mcu_flash_info。 - 烧录与复位：
mcu_read_flash/mcu_flash/mcu_erase；需要时mcu_reset、mcu_bp；底层 openocd 序列也可经mcu_ocd受控执行（收尾仍走统一 FOOTERS）。 - 常驻会话与 GDB：
mcu_session_open→mcu_session_cmd→mcu_session_list/mcu_session_close；mcu_gdb用于 GDB 相关流程。 - 串口：
mcu_serial_list→mcu_serial_open→mcu_serial_tx/mcu_serial_rx→mcu_serial_close。
维护者提供的真机与串口自检脚本包括 .probe/run-target.mjs、.probe/run-serial.mjs 等，适合在挂载前于本机验证链路。
适用场景与注意¶
适合谁：已在 DSH 里做 STM32 / PY32 固件迭代，使用 CMSIS-DAP 或 DAPLink（SWD），希望 openocd 与 IDE 工具树隔离、并需要寄存器/内存/烧录/断点/串口一体化工具链的开发者。
权限与安全：插件以当前 DSH 进程权限运行，会启动 openocd、访问 USB 探针与串口，并在插件目录下写入 .run/ 与 backups/。安装前应自行审阅 https://github.com/lishuo4096/dsh-mcu-debug 源码与 MIT / GPLv2 第三方声明，勿在未信任的环境直接挂载。
平台说明：资料中的 junction、PowerShell 串口宿主与路径规避主要针对 Windows；其他系统行为以仓库当前实现为准，可先跑 mcu_env 与 .probe/ 下只读脚本确认。
生态说明：DSH 社区插件目录（如 SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；本文事实均来自上述 GitHub README 与 package.json。
结尾¶
dsh-mcu-debug 把 Cortex-M 调试烧录收成 27 个 mcu_* 工具：自带 openocd 副本、私有会话目录、固定清断点收尾，并区分多探针与串口长连接。若你正在 harness 里接 STM32 / PY32，可从目录页与仓库 README 的安装与 .probe/gate.mjs 门禁开始。
