前言¶
大多数让 AI 辅助开发 STM32 的做法停留在代码层：模型给出一段 main.c，至于代码能否编译、烧录后灯是否闪烁，还是需要开发者自己打开 CubeMX、切换终端、按 F5。模型看不到硬件，也就没法对自己的代码负责。
DeepSeek Harness（DSH）的定位是「让模型能直接操作硬件」。这个插件把 STM32F103C8T6 的整条开发链接入 DSH：从环境探测、建工程、改 .ioc、生成代码、编译，到只烧录、按需调试，最后从寄存器读回状态进行验证。模型不再是写完代码就结束，而是能把代码烧进板子，再把板子上的状态读回来跟自己的预期对账。
是什么¶
这是 DSH 的一个工作流插件，注册了 16 个工具、6 条斜杠命令和 1 个 SKILL，目标芯片是 STM32F103C8T6。它通过调用 STM32CubeMX 无头生成工程，配合 CMake/Ninja 编译，用 OpenOCD 烧录，并按需启动 GDB 调试。烧录与调试是两条独立路径：烧录不进入调试会话，只有在需要调试时才开启。
核心功能¶
环境探测与工具链检查¶
stm32_env_probe：探测 gcc / gdb / openocd / cmake / ninja / CubeMX / JRE 的路径与版本，列出缺什么、缺了会影响哪些能力、推荐安装方式，并返回四项能力是否可用。
stm32_doctor：一次检查三件事——工具链是否完整、探针被谁占用（openocd.exe / gdb 进程 / 端口 3333）、当前工程是否能烧录。
stm32_env_install：缺工具链时的安装方案。dryRun: true 只给出计划（下载什么、多大、要改哪条 PATH）；dryRun: false + confirm: true 才真正下载并安装 MSYS2 与 5 个 pacman 包，写入用户级 PATH，并自检。
工程创建与 .ioc 事务¶
stm32_project_create：在空目录下生成完整 CMake 工程，包含与 CubeMX GUI 产物逐字节一致的 14 个模板文件、629 个固件包 Drivers 文件，以及配置好 SWD 的 .ioc 文件。默认拒绝非空目录，需 overwrite: true 才覆盖。
.ioc 事务流程：stm32_ioc_inspect（只读解析）→ stm32_ioc_plan（计算 diff，不写盘）→ stm32_ioc_apply（SHA 校验 + 备份 + 失败回滚）。代码与生成区隔离，修改只影响 USER CODE 块，重新生成时按标签搬回。
生成、编译与烧录¶
stm32_generate：无头运行 CubeMX，产物落到 Core/ 目录，USER CODE 按标签搬回。
stm32_build：自动推断构建目录与 .elf，首次运行会自动执行 cmake --preset，之后增量构建。输出内存占用与错误行号。
stm32_flash：使用 OpenOCD 的 program verify reset exit 命令，烧录前检查 .ioc 是否开启了 Serial Wire。烧录完成后释放探针。
调试与状态验证¶
stm32_debug_run / stm32_debug_session：停在某处抓现场即释放；stm32_debug_session 支持连续调试，空闲自动关闭。
stm32_debug_eval：在调试会话中读取变量。
stm32_regs_read：按物理地址读取任意外设寄存器（如 GPIOC_ODR、TIM2_CNT、USART1_SR、ADC1_DR），halt 读值后 resume，不复位芯片，用于验证代码执行结果。
安装与启用¶
前置条件¶
| 依赖 | 用途 | 缺了会怎样 |
|---|---|---|
| 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
安装完成后，插件会被写入 profile 的 dsh.profile.bundles，重启 dsh 即生效。确认版本：
dsh plugin --profile desktop why dsh-stm32
应显示 0.1.1；重启后 /stm32-doctor 有输出。
卸载：
dsh plugin --profile desktop remove dsh-stm32
典型用法¶
最小验证：空目录到灯在闪¶
| 步 | 做什么 | 工具 | 实测耗时 |
|---|---|---|---|
| 1 | 体检：工具链、探针占用、端口、工程告警 | 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 |
修改 .ioc 并生成代码¶
stm32_ioc_plan：先给出 diff，不动源文件。- 确认后执行
stm32_ioc_apply，进行 SHA 校验、备份，失败时回滚。 - 执行
stm32_generate，无头 CubeMX 生成代码，USER CODE 按标签搬回。 - 执行
stm32_build编译。 - 执行
stm32_flash烧录。 - 执行
stm32_regs_read读取寄存器确认执行结果。
适用场景与注意¶
适合需要让模型直接操作硬件、从零搭建 STM32 工程并验证结果的开发者。当前仅支持 STM32F103C8T6，宿主在 Windows 上验证，探针默认 CMSIS-DAP。
插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。新增外设后补 HAL 源需要手工在 cmake/stm32cubemx/CMakeLists.txt 的 STM32_Drivers_Src 里添加对应文件，或写入 cmake/user/CMakeLists.txt。
结尾¶
这个插件把「写代码」扩展为「从环境探测到状态验证」的完整闭环，让模型能对硬件结果负责。更多细节与源码可参考项目目录与 GitHub 仓库。
参考资料¶
- 插件目录：https://www.skillhub.cn/plugins/JingYu-er/dsh-stm32
- GitHub：https://github.com/JingYu-er/dsh-stm32
- DSH 主仓库：https://github.com/deepseek-ai/deepseek-harness
