前言¶
在 DSH 里让 agent 帮忙烧录、读寄存器或连 gdb，常见做法是直接调用本机 MounRiver 自带的 openocd.exe。OpenOCD 在未指定 -f / -c 时会从当前工作目录隐式加载 ocd.cfg；MounRiver 的 bin 目录里又出厂自带一份面向 ARM/SW-DP 的配置。一次在错误目录下试命令，后续所有 WCH-Link 操作可能被静默切到 ARM 模式，而目标却是 RISC-V 的 CH32V——连不上或行为诡异，且很难从「退出码为 0」里看出问题。另一类事故是调试会话异常结束、软件断点未写回，残值随烧录进 flash，上电就停在断点。
下面介绍维护者 lishuo4096 在社区目录登记的客户端类插件 dsh-wch-debug（GitHub：lishuo4096/dsh-wch-debug）：把 WCH 定制 OpenOCD、WCH-Link、烧录与调试能力封装成 20 个 DSH 工具，并附带 agent 技能 wch-debug，从结构上避免污染 IDE 安装树和隐式 cfg。
这是什么¶
dsh-wch-debug 是 DeepSeek Harness 的本地插件包（@local/dsh-wch-debug，cordis id：wch-debug）。它用插件内私有副本的 WCH OpenOCD（约 30.9 MB，含 bin/、scripts/、share/）配合本机 WCH-Link 与 C:\MounRiver 下的工具链，在命令行完成环境自检、目标探测、flash 读写、寄存器/内存查看、常驻 telnet/gdb 会话，以及带收尾纪律的烧录。插件为 MIT 许可，纯 JavaScript、无 npm 运行时依赖；package.json 标明与 DSH 0.2.0-rc.2 兼容，需要 Node.js >= 20。
与「随手写个烧录脚本」的区别在于：每次运行在 .run/sessions/<id>/ 一次性私有目录；assertPrivateWorkdir() 禁止把 IDE 树当 CWD；cfg 只通过绝对路径 -f 传入；子进程环境会剥掉可能劫持脚本搜索路径的 OPENOCD_SCRIPTS；烧录和关会话默认 清断点 → reset run，并对 OpenOCD 用「日志里是否出现 Error:」而不仅看退出码判成败。
核心功能¶
工具分组（20 个）¶
第一次使用建议先调用 wch_env：汇总插件根路径、隔离副本版本、IDE 原件位置、工具链、WCH-Link 模式与串口、残留 openocd 进程、3333/4444/6666 端口占用，以及当前是否具备干活条件。
| 组别 | 代表工具 | 作用（摘自 README） |
|---|---|---|
| A 环境/清单 | wch_devices、wch_projects、wch_workspace、wch_help |
CH32 型号表（约 20 个 key）、扫 MounRiver 工程 Link.ld、工作区卫生审计/隔离出厂 ocd.cfg、排错剧本 |
| B 只读探针 | wch_probe、wch_regs、wch_mem、wch_flash_info、wch_read_flash |
连一次报告目标信息；读寄存器/CSR；内存 hexdump；flash 详情；读出 bin 到 backups/ |
| C 写目标 | wch_flash、wch_erase、wch_reset、wch_ocd |
烧录（默认先备份、verify、收尾清断点）；擦除；复位；逃生舱执行任意 openocd 命令串（均需 confirm:true） |
| D 会话/连调 | wch_session_open/cmd/close/list、wch_gdb |
常驻 3333 gdb / 4444 telnet / 6666 tcl；批处理 gdb（symbols/load/inspect/raw） |
| E 清理 | wch_clean |
审计、扫描会话目录、清理过期会话、结束残留 openocd |
Agent 技能¶
skills/wch-debug/SKILL.md 面向 agent 的操作手册：何时用一次性工具、何时起常驻会话、连不上与「烧录成功但板子不跑」的排查顺序、断点残值如何确认与清理。工具描述放不下的判断依据写在这里。
器件与外部依赖¶
- 本机需已安装 MounRiver（OpenOCD、gcc/gdb/objcopy、WCH-Link 驱动与工具）。
- 同一 WCH-Link 同时只能被一个 openocd 占用；起会话前用
wch_session_list确认。 - 内存读取约 2.8 kB/s（README 实测：4 KiB 约 1.5 s）；整片 256 KiB flash 读出约 88 s，超时会按字节数估算。
安装与启用¶
安装命令以仓库 README 为准（示例为作者本机插件开发目录，你应改为自己的 bundle 路径或目录页给出的安装方式）：
// 在 DSH 里（一次调用）
plugin_manager({ action: 'install_bundle', target: 'C:\\Users\\lishuo\\Documents\\DSH_Project\\插件开发\\dsh-wch-debug' })
看返回里的 application 字段：applied 才算生效。若出现 changed:false、application:'failed'、error.code:'ambiguous-install'，README 建议先 set_plugin(target:'include:wch-debug', enabled:false) 再 enabled:true，无需重启。
验证是否加载成功：
plugin_manager({ action: 'list_plugins' }) // 看 fiberPhase: 'active'
cordis_inspect_query({ platform:'host', provider:'Tool', method:'listTools' }) // 看 20 个 wch_* 工具
插件加载时控制台应出现类似输出：
[wch-debug] 已注册 20 个工具: wch_env, wch_devices, … , wch_clean
[wch-debug] 已注册技能 provider: wch-debug（skills/ 下的 SKILL.md）
典型用法¶
1、环境自检¶
让 agent 调用 wch_env，根据报告确认 WCH-Link 处于目标芯片所需模式（RV / ARM）、无端口冲突、工具链路径可用。
2、确认型号与配置¶
不传参数调用 wch_devices 列出型号表；对具体工程可用 wch_projects 扫 C:\MounRiver\Project 下的链接脚本推断 FLASH/RAM 与型号。
3、只读看一眼目标¶
wch_probe 连一次并报告时钟、调试模块、PC/SP 等，读完会 reset run，不把芯片留在 halt。
4、烧录固件¶
对 elf/hex/bin/s19 使用 wch_flash，并设 confirm:true。默认先备份到 backups/，再 program … verify，收尾清断点并 reset run。成功判据包含日志中的 **Verified OK ** 与收尾的 reset run，不能只看进程退出码。
5、需要断点/单步时¶
先 wch_session_list，再 wch_session_open 起常驻 openocd；调试过程用 wch_session_cmd 发 telnet 命令；结束用 wch_session_close（先清断点再 shutdown，而非直接杀进程）。查 ELF 符号地址（例如为硬件断点找 main）可用 wch_gdb 的 action: symbols，不连硬件。
6、排错剧本¶
wch_help 提供 first_time、not_connecting、flash_ok_but_dead、bp_residue、session、tools 等场景指引；工作区若怀疑被出厂 ocd.cfg 污染，可对副本做 wch_workspace 的 audit / quarantine（只动插件副本，不动 IDE 原件）。
适用场景与注意¶
适合谁：已在 Windows 上用 MounRiver + WCH-Link 做 CH32（RISC-V 或 ARM Cortex-M）开发，希望在 DSH 对话里用结构化工具完成烧录、读内存、寄存器检查和 gdb 连调，并降低 OpenOCD 工作目录与断点残留类事故的人。
权限与安全：插件以当前 DSH 进程权限在本机启动 openocd、读写工程与 backups/。安装前应在 GitHub 阅读源码与 MIT / THIRD-PARTY.md；社区目录 skillhub.cn 插件页 与 DeepSeek / 幻方无官方从属关系，属社区「一切皆插件」生态中的第三方条目（目录显示星标为 0，以页面为准）。
平台：README 与路径示例面向 Windows + C:\MounRiver；未在资料中承诺其他 OS。
结尾¶
dsh-wch-debug 把 WCH CH32 的 OpenOCD CLI 调试收成 20 个 DSH 工具与一套 agent 技能，用私有 OpenOCD 副本和会话目录把「隐式 ocd.cfg」和「断点/收尾敷衍」类问题写成硬约束。进一步了解可打开 社区目录页 与 GitHub 仓库。
