dsh-stm32

dsh-stm32

让 DSH 接管 STM32F103C8T6 的整条开发链：探测工具链 → 建工程 → 改 .ioc → 生成代码 → 编译 → 调试 → 烧录。

English: STM32F103C8T6 toolchain for DeepSeek Harness — probe the toolchain, scaffold a CMake project, edit .ioc as a transaction, build, flash without starting a debug session, and debug only when you ask for it.

English · 快速开始 · 功能一览 · 工具参考 · 斜杠命令 · 设计要点 · 已知限制 · 排错 · 规格书

这是一个 DeepSeek Harness (DSH) 插件：注册 19 个工具、6 条斜杠命令和 1 个随插件下发的 SKILL，让模型能直接探测工具链、建cubemx cmake工程、改 .ioc、跑 CubeMX、编译、烧录和调试，烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。

为什么需要它

大多数「让 AI 帮忙写 STM32」的做法停在代码层：它给你一段 main.c，至于这段代码能不能编译、烧进去灯到底闪没闪，还是你自己开 CubeMX、切终端、按 F5。模型看不到板子，也就没法对自己的代码负责。

这个插件把硬件侧也接到 DSH 上：.ioc 能读能改（事务 + 回滚）、代码落在 USER CODE 块里、生成和编译能拿到真实的报错行、烧录是一条不经过调试器的独立路径、烧完还能用寄存器把状态读回来。每一步都返回结构化证据（planId、file:line:col、Verified OK、GPIOC_ODR 的 bit13），模型据此决定下一步，而不是猜。

这就是「更彻底的面向 DSH 硬件编程」：模型不只是写代码——它能把代码烧进板子，再把板子上的状态从寄存器里读回来跟自己的预期对账。

环节 · 以前（手写 + CubeMX GUI） · 现在（DSH 全流程） 建工程 · GUI 里点时钟树、引脚、工程设置，生成 CMake，再手写 launch.json · 一句话：stm32_project_create 2 s 出模板工程（与 GUI 产物逐字节一致），.vscode 里两份配置已就位 改配置 · GUI 里改完重新生成，祈祷 USER CODE 不丢 · stm32_ioc_plan 先给 diff（不动源文件）→ 你点头 → stm32_ioc_apply 带 SHA 校验、备份、失败回滚 写代码 · 整文件编辑，一不小心写进生成区，重新生成就没了 · stm32_code_patch 只写 USER CODE 块，块外逐字节不动 编译 · 使用keil编译或使用vscode插件编写cmake文件 · DSH 通过/stm32-build [dir] [--clean] 自动编译 烧录 · 使用keil烧录或自己写 tasks.json 调 openocd · DSH 通过/stm32-debug [dir]自动烧录 验证 · 断点调试，自己查看寄存器的值 · 烧完用 stm32_regs_read 把状态读回来：GPIOC_ODR 两次采样看计数器递增，AFIO_MAPR 确认 SWD 没被固件关掉 调试 · F5 + 手动下断点、看完再关会话 · stm32_debug_run 停在 main 抓一次现场即释放；要连续调才开 stm32_debug_session，空闲自动关

安装

前置条件

依赖 · 用途 · 缺了会怎样 dsh（能加载 bundle 层） · 宿主 · 插件不会被加载 Node ≥ 20 · 构建 / 测试 · npm run build 失败 arm-none-eabi-gcc、arm-none-eabi-gdb（或 gdb-multiarch） · 编译 / 调试 · stm32_doctor 逐个提示缺哪个、去哪装 openocd · 烧录 / 调试 · 烧录与调试不可用，只读工具照常 cmake + ninja · 构建 · stm32_build 失败 STM32CubeMX（含内置 JRE） · stm32_generate、stm32_project_create · 生成类工具不可用，其余照常 STM32Cube 固件包 F1（随 CubeMX 装） · 建骨架时抄 Drivers · 报「找不到固件包」

安装（推荐：一条命令）

dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main

dsh plugin 做的事就是在 profile 目录里跑 pnpm add。装完它会把 dsh-stm32 写进该 profile 的 dsh.profile.bundles，重启 dsh 即生效（把 desktop 换成 web 就装到 web profile）。

装完确认：dsh plugin --profile desktop why dsh-stm32 应显示 0.1.1；重启后 /stm32-doctor 有输出。

卸载：dsh plugin --profile desktop remove dsh-stm32，重启 dsh。

源码安装（要改代码时）

git clone https://github.com/JingYu-er/dsh-stm32.git
cd dsh-stm32
npm install --no-audit --no-fund   # 只装 typescript
npm run build                       # tsc -> lib/（提交前必须跑）
npm test                            # 可选：309 个离线用例，不需要板子

挂进 dsh 的 profile——改代码时必须用 `link:`，不要用 `file:`：

cd "$env:USERPROFILE\.dsh\profiles\desktop"
pnpm add "link:D:\path\to\dsh-stm32"

# 然后在同一目录的 package.json 里，把 "dsh-stm32" 加到 dsh.profile.bundles 数组末尾
# 最后重启 dsh（bundle 层只在进程启动时加载）

为什么改代码必须 `link:`：pnpm 在 nodeLinker: hoisted 下会把 file: 依赖复制成真实目录，之后你重新 tsc 出的 lib/ 宿主读不到——表现为"改完代码、重启还是旧行为"。用 link: 时 lib/ 是实时读的，但仍然要重启 dsh 才会重新加载插件。github: / npm 装的是拷贝，改代码后要重新构建、重新安装。

快速开始：最小验证（空目录到灯在闪）

下面这条链在真板上跑通过（A1 验收，2026-10-22），全程由模型调用工具完成。注意它只是最小验证——每一步用的都是同一套工具，闪灯只是最省的样例：

步 · 做什么 · 工具 · 实测耗时 1 · 体检：工具链、被占用的探针、端口、.elf、.ioc 告警 · stm32_doctor · ~2 s 2 · 空目录建 CMake 工程骨架（14 个模板文件 + 629 个固件文件 + 配好 SWD 的 .ioc） · stm32_project_create · ~2 s 3 · 按 .ioc 无头跑 CubeMX，产物落到 Core/ · stm32_generate · 首次 130–175 s；之后再跑，.ioc 与产物都没变会直接跳过（<1 s） 4 · 编译（首次自动 cmake --preset） · stm32_build · 配置 ~5 s + 编译 3 s 5 · 只烧录：program + verify + reset · stm32_flash · 2.1–2.6 s 6 · 读回 GPIOC_ODR，确认状态确实在翻 · stm32_regs_read · 0.4–1.3 s

模型侧就是一句话：「在 D:\work\blink 建一个 STM32F103C8T6 的闪灯工程，编译并烧进去」。想自己敲就：

/stm32-doctor         # 开工前体检
/stm32-env            # 只看四项能力缺什么（缺件也能看）
/stm32-build          # 编译，打印内存占用与错误
/stm32-flash          # 只烧录，不进调试会话
/stm32-debug          # 烧录 + 停在 main
/stm32-stop           # 关掉调试会话，把探针还给 VS Code

这只是最小验证，不是能力上限

闪灯是这条链的最小 smoke test：它把「建工程 → 生成 → 编译 → 烧录 → 读回状态」每一步走了一遍，用的都是同一套工具，没有一步是闪灯专用的。真实项目走的是同一条链，区别只在 .ioc 里多几个外设、USER CODE 多几个块、代码更长：

完整项目里要做的事 · 走哪条路径 · 上板实测情况 外设配置：GPIO / 定时器 / USART / I2C / SPI / ADC / DMA / 中断 · stm32_ioc_plan 改 .ioc（GPIO 按芯片引脚表校验，外设写 Mcu.IP* / Periph.* 键）→ stm32_ioc_apply → stm32_generate · GPIO、时钟、SWD 已实测；其他外设同一机制，未逐个实测 新增外设后补 HAL 源 · 在 cmake/stm32cubemx/CMakeLists.txt 的 STM32_Drivers_Src 里加 stm32f1xx_hal_.c，或写进 cmake/user/CMakeLists.txt · 这一步要手工补：插件只落位 Src/ 与 Inc/，CubeMX 生成的 cmake/** 不搬 多源文件、自己写的模块 · 写进 cmake/user/CMakeLists.txt，模板已留好位置 · 位置就位；未单独实测 业务代码 · stm32_code_patch 按块写入，重新生成时按标签搬回 · 已实测（append / replace / 标签写错会列出全部可用标签） 调参数、改时钟 · .ioc 事务：先 diff → SHA 校验 → 备份 → 失败回滚 · 已实测 烧完确认外设真的在动 · stm32_regs_read 读任意外设寄存器（TIM2_CNT、USART1_SR、ADC1_DR…），或 stm32_debug_eval 读变量 · 按物理地址读寄存器已实测（GPIOC_ODR / AFIO_MAPR） 出问题要看现场 · stm32_debug_run 停在 main 抓一次；要连续调就开 stm32_debug_session + stm32_debug_eval · 已实测（停在 main () at main.c:67）

所以闪灯是验收用的最小样例，不是这套工具的能力上限：它覆盖的是整条工程链，而不是一个 demo。 真正的边界在已知限制里——芯片只支持 F103C8T6、宿主只在 Windows 上验证、探针默认 CMSIS-DAP，以及上面那条「新增外设要手工补 HAL 源」。外设种类本身不受工具限制：.ioc 里配得出来的，生成、编译、烧录、读回都走同一条链；只是除闪灯外还没有逐项上板实测，正式开项目前先跑一遍 stm32_doctor。

功能一览

能力 · 提供方式 环境体检 · stm32_env_probe（只读）、stm32_doctor（工具链 + 探针占用 + 端口 + 工程告警） 开工前门禁 · 每个会动工具链的工具先过 ensureToolchain：缺件就拦住并写清装什么、缺了会怎样；envCheck: "block"（默认）/ "warn" / "off" 由调用方决定 装工具链 · stm32_env_install：先只出计划（下载什么、多大、要改哪条 PATH），你点头才真装 MSYS2 + 5 个 pacman 包 + 用户级 PATH，装完自己写进配置文件 选技术路线 · stm32_route_plan：先按这个工程的需求，把每个外设的 HAL 版与寄存器版代价摆出来（效率 / 可读性 / 排错），再告诉你缺的是「能代装的」还是「只能人装的」（CubeMX 是 GUI 向导 + 要 ST 账号、固件包只由 CubeMX 包管理器维护） 从零建工程 · stm32_project_create：route: "hal" 用模板快照 + 固件包 Drivers（与 CubeMX GUI 新建的工程逐字节一致）；route: "register" 建不用 CubeMX 的寄存器版工程，CMSIS 模板首次从网上下到缓存、之后复用 .ioc 事务 · stm32_ioc_inspect（只读解析）→ stm32_ioc_plan（算 diff，不写盘）→ stm32_ioc_apply（SHA 校验 + 备份 + 回滚） 只改 USER CODE · stm32_code_patch：只写 /* USER CODE BEGIN X */ 与 END X 之间，块外逐字节不动 生成代码 · stm32_generate：无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 编译 · stm32_build：构建目录与 .elf 自动推断、错误去重、链接后解析 RAM/FLASH 占用 烧录 · stm32_flash：openocd program verify reset exit，烧完释放探针；烧前检查 .ioc 是否开了 Serial Wire 调试 · stm32_debug_run / stm32_debug_session / stm32_debug_eval / stm32_debug_stop 验证"真的在跑" · stm32_regs_read：按物理地址把任意外设寄存器读回来，halt 读值后 resume，不复位芯片 给模型的工作纪律 · 随插件下发 SKILL stm32-workflow（只改 USER CODE、不动生成区、烧录与调试分开、结论要带寄存器证据）

工具参考

环境与工程

工具 · 作用 stm32_env_probe · 探测 gcc / gdb / openocd / cmake / ninja / CubeMX / JRE 的路径与版本；缺什么会写清影响（编译不了 / 烧不了 / 调不了 / 建不了工程）、推荐装法（含可粘贴的 pacman / winget 命令）、装完自检命令，并给 capabilities（四项能力是否可用）与 recommendations（安装顺序 + 要不要我帮你装）。只读、可重复调 stm32_env_install · 缺工具链时的一条龙：dryRun（默认）只给计划——官方 MSYS2 安装包多大、要装哪 5 个包、PATH 会加哪一条；dryRun: false + confirm: true 才真干活（下载 → 装 MSYS2 → pacman -S → 写 用户级 PATH → 自检 → 写 ~/.dsh-stm32/config.json）。已装 msys64 时只补包。不做卸载 stm32_route_plan · 动手前先把路线问清楚：requirement 必填（如「按键控制 LED，串口每秒打印一次状态」），返回 verdict（register-ok / both-viable / hal-only / unclear）、逐外设的 halEffort/regEffort 与 advice、两种写法的差别、落地的下一步、工具链缺件（每条标 installability：auto 可代装 / manual 只能人装）与手动安装指引全文。不做通用对照表——结论只对当前需求成立 stm32_doctor · 一次回答三件事：工具链齐不齐、探针被谁占（openocd.exe / gdb 进程 / 3333 端口）、这个工程能不能烧 stm32_project_create · 空目录 → 完整 CMake 工程。route: "hal"（默认）走 CubeMX 那套（含 .vscode 里"① 只烧录 / ② 烧录并调试"两份配置）；route: "register" 建不用 CubeMX、不用 HAL 的寄存器版工程（mcu 指定型号，CMSIS 头与启动文件从缓存取）。目标目录非空默认拒绝，overwrite: true 才覆盖 stm32_cache · 看 / 验 / 拉 / 清下载缓存：action: "list"（默认）列条目、"verify" 逐文件校验、"fetch" 按 mcu 拉一次模板（已缓存则直接复用，不联网）、"purge" 删条目（不给 id 就清空）。缓存里放的是"不属于插件、但建工程要用"的 CMSIS 设备头 + 启动文件 + 内核头，第一次用时才下载，之后一直复用 stm32_firmware_install · 缺固件包时的一条龙：dryRun（默认）只出计划——装到哪、下哪两个源码仓、几条自检判据；dryRun: false + confirm: true 才真下（GitHub 上 HAL 驱动与 CMSIS 设备支持两个源码包 + 内核头，合计约 2 MB），组装成与官方同构的 STM32Cube_FW__V 包（自写 package.xml）并过五条自检。已有官方包时什么都不做；默认装到 /dsh-firmware（不是 Repository——塞自造版本号会被 CubeMX 静默忽略），生成时由 stm32_generate 用 setCustomFWPath 指过去

.ioc：只读与事务

工具 · 作用 stm32_ioc_inspect · 解析 MCU 型号、引脚/信号/标签、外设与中断、时钟树、工程设置；会报「没开 Serial Wire 会生成 SWJ_DISABLE」这类致命风险 stm32_ioc_plan · 改 .ioc 的第一步：算出逐键 diff 与源 SHA-256，返回 planId，不动源文件。支持改键、删键、按引脚表加 GPIO、一键补 Serial Wire stm32_ioc_apply · 必须带 planId；写盘前再核 SHA（中途被手改就拒绝），备份后原子替换，写完重新解析校验，不过自动回滚。支持 rollbackFrom

代码与构建

工具 · 作用 stm32_code_patch · 只在 USER CODE 块内 replace/append；块外字节（含 CRLF）原样保留；写前备份、临时文件 + rename 原子替换。标签写错会把该文件所有可用标签列给你 stm32_generate · 无头跑 java -jar STM32CubeMX.exe -q，成功后落位到 Core/Src、Core/Inc，旧文件的 USER CODE 按标签搬进新内容。默认后台 job。`.ioc`、CubeMX 版本、产物 hash 都没变时直接复用上次结果（skipped: true，约 1 s；传 skipIfUnchanged: false 或删 .dsh-stm32/generate-cache.json 可强制重跑）。工程没用 X-CUBE 扩展包时（Mcu.ThirdPartyNb=0）会自动把 ~/.stm32cubemx/thirdparties/pdsc 临时停放、跑完还原，省约 25 s；要保留索引传 thirdpartyPacks: "keep"。要不要索引不靠关键词猜：.ioc 里的 Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0 会跟内置的 X-CUBE 包目录（67 个包，scripts/gen-xcube-catalog.mjs 生成）对名字，本机缺这个包会提前在 notes 里警告 stm32_build · cmake --build，构建目录从 CMakePresets.json 与 build/*/CMakeCache.txt 推断；首次构建自动 configure；会拦住"CMakeCache 目录不一致但 ninja 退出码 0"的假成功

烧录与调试

工具 · 作用 stm32_flash · 烧录：openocd program verify reset exit，不建调试会话、不停 main。烧前读 .ioc，调试口没开就拒绝（见 设计要点） stm32_debug_run · 起 openocd + gdb，break main → continue → 抓 pc/sp/lr/bt/locals → reset run + detach，不写 Flash、不常驻 stm32_debug_session · 常驻 openocd 会话（.elf 自动解析），空闲 90 s 自动关、硬上限 10 min stm32_debug_eval · 在会话里执行 gdb 命令或读表达式（如 g_led_blink_count），读完立刻 resume + detach stm32_debug_stop · 立刻释放探针，幂等 stm32_regs_read · 读 GPIOC_ODR、AFIO_MAPR 等物理地址；收尾用 resume 而不是 reset run，避免读一眼就把固件状态清零

斜杠命令

工具是给模型调的；你要自己动手时用命令，一条命令一个动作，不经过模型决策。

命令 · 做什么 · 会不会动板子 /stm32-doctor · 体检：工具链、被占用的调试进程、端口、.elf、.ioc 告警 · 否 /stm32-env · 看四项能力（编译 / 烧录 / 调试 / 生成代码）各缺什么、装什么、装完怎么自检；缺件也照常出卡片 · 否 /stm32-build [dir] [--clean] · 编译，打印内存占用 / .elf / 错误 · 否 /stm32-flash [dir] · 烧录：program + verify + reset，不建调试会话、不下断点 · 是 /stm32-debug [dir] · 烧录 + 调试：烧完停到 main，会话保留（空闲 3 分钟 / 上限 10 分钟，本轮结束也会自动关） · 是 /stm32-stop · 关掉 /stm32-debug 开的会话，把探针还给 VS Code · 否

[dir] 省略时用当前会话的工作目录。

设计要点

• 烧录与调试是两条路。 stm32_flash 只用 openocd 的 program/verify/reset/exit，成功证据是日志里出现 ** Programming Finished ** 与 ** Verified OK **，不是"没报错"。
• 只写 USER CODE。 改逻辑用 stm32_code_patch；stm32_generate 重新生成时按标签把旧内容搬回新文件，所以手改生成区或整文件重写在重新生成后都会丢。
• `.ioc` 是事务。 plan 只算 diff 出 planId，apply 才写盘，写前核 SHA、写后重新解析、失败回滚。
• 烧前守卫。 如果 .ioc 的 SYS 调试口不是 Serial Wire（PA13/PA14 缺失或被设成 No_Debug），CubeMX 会生成 __HAL_AFIO_REMAP_SWJ_DISABLE()——烧进去 SWD 立刻失联，只能 BOOT0 救砖。这种工程 stm32_flash 直接拒绝；确实要烧得显式传 allowNoDebug: true。
• 探针只有一块。 烧录、调试、后台会话同一时刻只能有一个；build / flash / debug_run / generate 开跑前会先把占着探针的会话关掉。

配置

用户配置文件（~/.dsh-stm32/config.json）

工具装在哪，插件自己记。stm32_env_install 装完会写这个文件，之后所有工具读它——不用重启 DSH、也不用设环境变量。手写也行：

{
  "version": 1,
  "msys64": "E:/msys64",
  "binDirs": [],
  "packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
  "cubeMxRoot": "",
  "updatedAt": "2026-02-01T00:00:00.000Z"
}

binDirs 留空时由 msys64 推出 /ucrt64/bin——安装器写的就是这个形状。文件坏了（JSON 不合法）不会让工具报错，只是当它不存在。

优先级：工具参数（binDirs / cubeMxRoots）> 环境变量 > 这个配置文件 > 内置默认值；自动发现只追加在"没点名参数"的那一档尾部。

内置默认值里没有任何"某台机器专属"的路径：只有 C:/msys64/... 与 C:/Program Files/... 这种 Windows 默认安装位置，装在别处靠自动发现兜底。配置或环境变量里点名的目录如果在本机不存在（典型情况：配置是从别的机器拷过来的，带着 D:/app/msys64 这种路径），门禁与 stm32_env_probe 会明确写一句「配置文件里的 X 在本机不存在……这一条搜不到工具」，而不会悄悄改你的配置；安装器也不会拿这种路径当安装目标（盘符都没有时只提示、并要求你给 targetDir）。

设置面板（GUI）

上面那个配置文件也能不碰命令行改：DSH 的 设置 → STM32 工具链（插件自带的浏览器端面板，与宿主同源，零额外依赖）。三张卡：

• 装在哪：读当前配置，改 msys64 / cubeMxRoot / 额外 binDirs 后保存——写的就是上面那个文件，下一条工具调用就读得到，不用重开 DSH；
• 缺什么：跑一次探测（会执行各工具的版本命令，不装任何东西），逐项显示找到的路径与版本、缺件的 hint，以及编译 / 烧录 / 调试 / 生成四项能力徽章；
• 装工具链：先出计划（步骤、下载体积、PATH 与配置会怎么改），再点一次确认才真装；装的过程实时显示步骤与日志尾巴，实际执行与 stm32_env_install 是同一个安装器。工具链已经完整时，计划只回一句话「工具链完整，不需要装任何东西」，不列那七行「已跳过」。

接口是插件注册在宿主上的六条 /dsh-stm32/api/*（读配置、存配置、探测、安装计划、开始安装、安装进度）；面板产物是 lib/client.js，源码在 client/client.js，由 npm run build 原样复制——手写纯 JS、只 require("react")，不引入打包器或运行时依赖。宿主没有 webServer 服务时（纯 CLI 组合）这层注册自动跳过，工具与斜杠命令不受影响。

下载缓存（寄存器版模板）

寄存器版工程要的 CMSIS 设备头、启动文件、内核头不预置进插件（要覆盖任意 STM32，每颗都打一份会让包大到不可用），而是第一次用时从网上下载，落到一个可检索的缓存目录，之后一直复用：

• 位置：DSH_STM32_CACHE（支持 ~）> %LOCALAPPDATA%\dsh-stm32\cache；
• 索引：缓存根下 index.json 记录每条源 URL、字节数、许可（THIRD_PARTY_NOTICES.md 随条目一起写）；
• 下载源：按 fastly.jsdelivr → cdn.jsdelivr → raw.githubusercontent → ghproxy 的顺序回退，HTTP 错误 / 内容像网页 / 字节数明显不对都算该源失败；
• 半截缓存会被整条删掉（比没有缓存更糟）；条目文件缺失或大小对不上时下次自动重下；
• 看得见、清得掉：stm32_cache 的 list / verify / fetch / purge。

固件包下载（HAL 路线）

CubeMX 装好也不一定有这一颗芯片的固件包（安装包里不带，得在包管理器里另装）。插件能代下的那一代，stm32_firmware_install 会从 GitHub 拉两个源码包组装出来：

• 下什么：stm32f1xx-hal-driver（HAL 驱动，BSD-3-Clause）+ cmsis-device-f1（设备头与启动文件，Apache-2.0）+ 5 个 CMSIS 内核头，合计约 2 MB、几秒钟；
• 为什么不能直接解压 STM32CubeF1 的源码包：它的 HAL 与 CMSIS 设备目录是 git 子模块，tarball 里是空目录——解压出来编译必挂（缺 startup、缺 HAL 源文件）；
• 装到哪：默认 /dsh-firmware/（与 Repository 并列、插件自建，不动官方包）；这个根写不进去才退回用户缓存目录。别往 `Repository` 里塞自造版本号——实测 CubeMX 认不出那个版本名，不报错地退回它自己认识的包（生成「成功」，HAL 却是旧版）；
• 生成时怎么用上它：stm32_generate 按 .ioc 的 ProjectManager.FirmwarePackage 找包（Repository 与 /dsh-firmware 都找），并在 CubeMX 脚本里发 project setCustomFWPath ——这是唯一被实测有效的机制，不往 .ioc 里写绝对路径；
• 组装包与官方包同构：自写 6 行 package.xml（版本串 FW..）与 THIRD_PARTY_NOTICES.md，不含任何哈希/清单——CubeMX 也不校验来源（已实测：用 setCustomFWPath 指过去生成，拷出的 HAL 源文件逐字节来自我们目录）；
• 但「生成成功」不能当验收：.ioc 点名了不存在的包时 CubeMX 不报错、退出码 0、只是不拷 HAL。所以装完必须过五条判据（内核头 / HAL Inc / HAL Src / 设备头 / startup_*.s），插件装完自己就验一遍。

环境变量（可选）

变量 · 作用 · 默认 STM32_BIN_DIRS · 工具链目录候选，; 分隔，整份替换内置列表（之后的自动发现仍追加在尾部） · C:/msys64/ucrt64/bin、C:/msys64/mingw64/bin STM32_CUBEMX_ROOT · STM32CubeMX 安装根目录，整份替换内置列表 · C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX STM32_NO_DISCOVER · 设为 1 / true 关掉下面的自动发现（CI、只想用内置列表时） · 不设 = 开着 DSH_STM32_CONFIG · 换一个配置文件路径（多份工具链 / 多工程隔离） · %USERPROFILE%.dsh-stm32\config.json DSH_STM32_NO_CONFIG · 设为 1 / true 完全不读配置文件（只想走环境变量时） · 不设 = 读 DSH_STM32_CACHE · 下载缓存根目录（寄存器版模板等），支持 ~ · %LOCALAPPDATA%\dsh-stm32\cache DSH_STM32_E2E_PROJECT · 真机 e2e 用的工程（含 openocd.cfg 与 build/Debug/*.elf） · 无 DSH_STM32_E2E_ROOT · e2e 临时副本目录 · 系统临时目录

也可以按调用传参：烧录/调试类工具都接受 binDirs、elfPath、buildDir、configFile、adapterSpeed；生成/建工程类接受 cubeMxRoots、firmwarePackage。

自动发现（换台机器通常不用配任何变量）。 没给 binDirs / STM32_BIN_DIRS 时，插件会扫一遍常见位置，把找到的目录追加在候选列表尾部：

• 工具链：/msys64、/msys2、/app/msys64、/tools/msys64、%LOCALAPPDATA%/Programs/msys64 下的 ucrt64/bin、mingw64/bin、clang64/bin（该目录里得真有 arm-none-eabi-gcc.exe / openocd.exe / cmake.exe）。
• CubeMX：注册表 HKLM|HKCU\SOFTWARE\STMicroelectronics\STM32CubeMX 的 InstallDir、...\Uninstall\STM32CubeMX 的 InstallLocation，以及 /、/app、/tools、Program Files\STMicroelectronics\STM32Cube、%LOCALAPPDATA%/Programs 下的 STM32CubeMX（要求 STM32CubeMX.exe 与 jre/bin/java.exe 都在）。

扫一次约 1 s，进程内缓存。用工具参数点名 `binDirs` / `cubeMxRoots` 时不追加——你指哪儿就用哪儿，免得"我明明指定了"变成假的。环境变量里的路径会先净化（去引号、反斜杠转正斜杠、折叠重复斜杠），不用怕 setx "D:\app\msys64\ucrt64\bin" 带进来的引号。找不到工具时，报错和 stm32_doctor 的 notes 都会列出「查过哪些目录」。

openocd.cfg（工程内，优先于内置回退）

CMSIS-DAP（默认）：

source [find interface/cmsis-dap.cfg]
source [find target/stm32f1x.cfg]
adapter speed 4000

ST-Link（换成你的探针）：

source [find interface/stlink.cfg]
transport select hla_swd
source [find target/stm32f1x.cfg]

没有 openocd.cfg 时回退 interface/cmsis-dap.cfg + target/stm32f1x.cfg。ST-Link 用户请把上面第二段写进工程根目录的 openocd.cfg。

.ioc 的两个硬要求

1. SYS 调试口必须是 Serial Wire（PA13 = SYS_JTMS-SWDIO、PA14 = SYS_JTCK-SWCLK）；没有就用 stm32_ioc_plan 的 serialWire: true 补上。
2. `ProjectManager.KeepUserCode=true`；否则重新生成时 USER CODE 不会被保留。