dsh-stm32 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +52 -23
  2. package/README_EN.md +50 -21
  3. package/docs/development-notes.md +466 -4
  4. package/docs/reading-guide.md +738 -0
  5. package/lib/commands/register.js +49 -0
  6. package/lib/data/chips.js +134 -4
  7. package/lib/data/clock-f1.js +158 -0
  8. package/lib/data/cmsis-sources.js +211 -42
  9. package/lib/data/f1-ram.generated.js +34 -0
  10. package/lib/data/stm32f1.js +186 -0
  11. package/lib/engine/build.js +115 -16
  12. package/lib/engine/cache.js +56 -0
  13. package/lib/engine/clock-plan.js +608 -0
  14. package/lib/engine/cmake-sources.js +428 -0
  15. package/lib/engine/debug.js +75 -10
  16. package/lib/engine/doctor.js +395 -4
  17. package/lib/engine/fetch.js +174 -30
  18. package/lib/engine/flash.js +95 -6
  19. package/lib/engine/generate.js +11 -0
  20. package/lib/engine/hal-chip.js +230 -0
  21. package/lib/engine/ioc-plan.js +28 -2
  22. package/lib/engine/msys2-install.js +332 -61
  23. package/lib/engine/project-export.js +129 -0
  24. package/lib/engine/register-clock.js +132 -0
  25. package/lib/engine/register-linker.js +129 -0
  26. package/lib/engine/register-template.js +88 -17
  27. package/lib/engine/scaffold.js +104 -28
  28. package/lib/engine/zip.js +142 -0
  29. package/lib/index.js +2 -0
  30. package/lib/skill/stm32-workflow.js +3 -3
  31. package/lib/tools/build.js +12 -0
  32. package/lib/tools/cache.js +39 -8
  33. package/lib/tools/debug.js +7 -0
  34. package/lib/tools/doctor.js +11 -2
  35. package/lib/tools/flash.js +3 -0
  36. package/lib/tools/ioc-plan.js +195 -4
  37. package/lib/tools/project-create.js +26 -1
  38. package/lib/tools/project-export.js +100 -0
  39. package/package.json +5 -3
  40. package/templates/register/CMakeLists.txt +19 -6
  41. package/templates/register/Core/Src/main.c +18 -9
  42. package/templates/scaffold/openocd.cfg +8 -0
package/README.md CHANGED
@@ -1,18 +1,18 @@
1
1
  # dsh-stm32
2
2
 
3
- > 让 DSH 接管 STM32F103C8T6 的整条开发链:探测工具链 → 建工程 → 改 .ioc → 生成代码 → 编译 → 调试 → 烧录。
3
+ > 让 DSH 接管 **STM32F1 全系**(F100/101/102/103/105/107)的整条开发链:探测工具链 → 建工程 → 改 .ioc(含时钟) → 生成代码 → 编译 → 调试 → 烧录。
4
4
 
5
- **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.
5
+ **English:** STM32F1 toolchain (F100/101/102/103/105/107) 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.
6
6
 
7
7
  [English](./README_EN.md) · [快速开始](#快速开始最小验证空目录到灯在闪) · [功能一览](#功能一览) · [工具参考](#工具参考) · [斜杠命令](#斜杠命令) · [设计要点](#设计要点) · [已知限制](#已知限制) · [排错](#排错) · [规格书](docs/dsh-stm32-plugin-规格.md)
8
8
 
9
9
  [![GitHub stars](https://img.shields.io/github/stars/JingYu-er/dsh-stm32?color=4a6cf7)](https://github.com/JingYu-er/dsh-stm32)
10
10
  [![license](https://img.shields.io/github/license/JingYu-er/dsh-stm32)](LICENSE)
11
11
  [![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-4a6cf7)](#已知限制)
12
- [![MCU](https://img.shields.io/badge/MCU-STM32F103C8T6-4a6cf7)](#已知限制)
13
- [![version](https://img.shields.io/badge/version-0.1.1-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
12
+ [![MCU](https://img.shields.io/badge/MCU-STM32F1xx-4a6cf7)](#已知限制)
13
+ [![version](https://img.shields.io/badge/version-0.1.2-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
14
14
 
15
- 这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 19 个工具、6 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
15
+ 这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 20 个工具、7 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
16
16
 
17
17
  ## 为什么需要它
18
18
 
@@ -56,7 +56,7 @@ dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
56
56
 
57
57
  `dsh plugin` 做的事就是在 profile 目录里跑 `pnpm add`。装完它会把 `dsh-stm32` 写进该 profile 的 `dsh.profile.bundles`,重启 dsh 即生效(把 `desktop` 换成 `web` 就装到 web profile)。
58
58
 
59
- 装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.1`;重启后 `/stm32-doctor` 有输出。
59
+ 装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.2`;重启后 `/stm32-doctor` 有输出。
60
60
 
61
61
 
62
62
  **卸载**:`dsh plugin --profile desktop remove dsh-stm32`,重启 dsh。
@@ -68,7 +68,9 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
68
68
  cd dsh-stm32
69
69
  npm install --no-audit --no-fund # 只装 typescript
70
70
  npm run build # tsc -> lib/(提交前必须跑)
71
- npm test # 可选:309 个离线用例,不需要板子
71
+ npm test # 可选:418 个离线用例、29 个套件,不需要板子
72
+ npm run test:pack # 打包 tarball → 解包 → 用解包出来的 lib 真建一次寄存器工程
73
+ npm run test:size # 包体护栏:tarball ≤1.2 MB、templates ≤60 KB、包内不许二进制/图表
72
74
  ```
73
75
 
74
76
  挂进 dsh 的 profile——**改代码时必须用 `link:`,不要用 `file:`**:
@@ -105,6 +107,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
105
107
  /stm32-flash # 只烧录,不进调试会话
106
108
  /stm32-debug # 烧录 + 停在 main
107
109
  /stm32-stop # 关掉调试会话,把探针还给 VS Code
110
+ /stm32-setup # 体检 + 安装计划(说「装」才真装)
108
111
  ```
109
112
 
110
113
  ### 这只是最小验证,不是能力上限
@@ -121,7 +124,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
121
124
  | 烧完确认外设真的在动 | `stm32_regs_read` 读任意外设寄存器(`TIM2_CNT`、`USART1_SR`、`ADC1_DR`…),或 `stm32_debug_eval` 读变量 | 按物理地址读寄存器已实测(`GPIOC_ODR` / `AFIO_MAPR`) |
122
125
  | 出问题要看现场 | `stm32_debug_run` 停在 `main` 抓一次;要连续调就开 `stm32_debug_session` + `stm32_debug_eval` | 已实测(停在 `main () at main.c:67`) |
123
126
 
124
- 所以闪灯是验收用的最小样例,不是这套工具的能力上限:**它覆盖的是整条工程链,而不是一个 demo。** 真正的边界在[已知限制](#已知限制)里——芯片只支持 F103C8T6、宿主只在 Windows 上验证、探针默认 CMSIS-DAP,以及上面那条「新增外设要手工补 HAL 源」。外设种类本身不受工具限制:`.ioc` 里配得出来的,生成、编译、烧录、读回都走同一条链;只是除闪灯外还没有逐项上板实测,正式开项目前先跑一遍 `stm32_doctor`。
127
+ 所以闪灯是验收用的最小样例,不是这套工具的能力上限:**它覆盖的是整条工程链,而不是一个 demo。** 真正的边界在[已知限制](#已知限制)里——芯片支持 F1 全系(F100/101/102/103/105/107,本机验证板是 C8T6)但只到 F1、宿主只在 Windows 上验证、探针默认 CMSIS-DAP,以及上面那条「新增外设要手工补 HAL 源」。外设种类本身不受工具限制:`.ioc` 里配得出来的,生成、编译、烧录、读回都走同一条链;只是除闪灯外还没有逐项上板实测,正式开项目前先跑一遍 `stm32_doctor`。
125
128
 
126
129
  ## 功能一览
127
130
 
@@ -131,12 +134,13 @@ pnpm add "link:D:\path\to\dsh-stm32"
131
134
  | 开工前门禁 | 每个会动工具链的工具先过 `ensureToolchain`:缺件就拦住并写清装什么、缺了会怎样;`envCheck: "block"`(默认)/ `"warn"` / `"off"` 由调用方决定 |
132
135
  | 装工具链 | `stm32_env_install`:先只出计划(下载什么、多大、要改哪条 PATH),你点头才真装 MSYS2 + 5 个 pacman 包 + 用户级 PATH,装完自己写进配置文件 |
133
136
  | 选技术路线 | `stm32_route_plan`:先按**这个工程**的需求,把每个外设的 HAL 版与寄存器版代价摆出来(效率 / 可读性 / 排错),再告诉你缺的是「能代装的」还是「只能人装的」(CubeMX 是 GUI 向导 + 要 ST 账号、固件包只由 CubeMX 包管理器维护) |
134
- | 从零建工程 | `stm32_project_create`:`route: "hal"` 用模板快照 + 固件包 Drivers(与 CubeMX GUI 新建的工程逐字节一致);`route: "register"` 建不用 CubeMX 的寄存器版工程,CMSIS 模板首次从网上下到缓存、之后复用 |
137
+ | 从零建工程 | `stm32_project_create`:`route: "hal"` 用模板快照 + 固件包 Drivers(与 CubeMX GUI 新建的工程逐字节一致);`route: "register"` 建不用 CubeMX 的寄存器版工程,CMSIS 模板首次从网上下到缓存、之后复用(每个文件都钉了上游 sha256,改过就拒绝落盘);`mcu` 指定型号(两条路线都吃;HAL 路线按型号渲染启动文件 / 设备宏 / `<DeviceId>_FLASH.ld`);两条路线都会带一份 `openocd.cfg`(CMSIS-DAP + `hla_swd` + 2 MHz) |
138
+ | 导出工程 | `stm32_project_export`:源码打成一个 zip(默认不带 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`),可选把 `.elf` 一起带上,并写一份开箱 README |
135
139
  | `.ioc` 事务 | `stm32_ioc_inspect`(只读解析)→ `stm32_ioc_plan`(算 diff,不写盘)→ `stm32_ioc_apply`(SHA 校验 + 备份 + 回滚) |
136
140
  | 只改 USER CODE | `stm32_code_patch`:只写 `/* USER CODE BEGIN X */` 与 `END X` 之间,块外逐字节不动 |
137
141
  | 生成代码 | `stm32_generate`:无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 |
138
- | 编译 | `stm32_build`:构建目录与 `.elf` 自动推断、错误去重、链接后解析 RAM/FLASH 占用 |
139
- | 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire |
142
+ | 编译 | `stm32_build`:构建目录与 `.elf` 自动推断、错误去重、链接后解析 RAM/FLASH 占用;`artifacts` 里要 `hex` / `bin` 就用同一套 `arm-none-eabi-objcopy` 转出来 |
143
+ | 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire;失败时给 `errorCode`(`no-probe` / `probe-busy` / `swd-locked` …) |
140
144
  | 调试 | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
141
145
  | 验证"真的在跑" | `stm32_regs_read`:按物理地址把任意外设寄存器读回来,halt 读值后 `resume`,不复位芯片 |
142
146
  | 给模型的工作纪律 | 随插件下发 SKILL `stm32-workflow`(只改 USER CODE、不动生成区、烧录与调试分开、结论要带寄存器证据) |
@@ -151,8 +155,9 @@ pnpm add "link:D:\path\to\dsh-stm32"
151
155
  | `stm32_env_install` | 缺工具链时的一条龙:`dryRun`(默认)只给计划——官方 MSYS2 安装包多大、要装哪 5 个包、PATH 会加哪一条;`dryRun: false` + `confirm: true` 才真干活(下载 → 装 MSYS2 → `pacman -S` → 写 **用户级** PATH → 自检 → 写 `~/.dsh-stm32/config.json`)。已装 msys64 时只补包。不做卸载 |
152
156
  | `stm32_route_plan` | 动手前先把路线问清楚:`requirement` 必填(如「按键控制 LED,串口每秒打印一次状态」),返回 `verdict`(`register-ok` / `both-viable` / `hal-only` / `unclear`)、逐外设的 `halEffort`/`regEffort` 与 `advice`、两种写法的差别、落地的下一步、工具链缺件(每条标 `installability`:`auto` 可代装 / `manual` 只能人装)与手动安装指引全文。不做通用对照表——结论只对当前需求成立 |
153
157
  | `stm32_doctor` | 一次回答三件事:工具链齐不齐、探针被谁占(`openocd.exe` / gdb 进程 / 3333 端口)、这个工程能不能烧 |
154
- | `stm32_project_create` | 空目录 → 完整 CMake 工程。`route: "hal"`(默认)走 CubeMX 那套(含 `.vscode` 里"① 只烧录 / ② 烧录并调试"两份配置);`route: "register"` 建**不用 CubeMX、不用 HAL** 的寄存器版工程(`mcu` 指定型号,CMSIS 头与启动文件从缓存取)。目标目录非空默认拒绝,`overwrite: true` 才覆盖 |
158
+ | `stm32_project_create` | 空目录 → 完整 CMake 工程。`route: "hal"`(默认)走 CubeMX 那套(含 `.vscode` 里"① 只烧录 / ② 烧录并调试"两份配置);`route: "register"` 建**不用 CubeMX、不用 HAL** 的寄存器版工程(`mcu` 指定型号——F1 全系都吃;寄存器版从缓存取 CMSIS 头与启动文件,HAL 版按型号渲染启动文件 / 设备宏 / `.ld`)。目标目录非空默认拒绝,`overwrite: true` 才覆盖 |
155
159
  | `stm32_cache` | 看 / 验 / 拉 / 清下载缓存:`action: "list"`(默认)列条目、`"verify"` 逐文件校验、`"fetch"` 按 `mcu` 拉一次模板(已缓存则直接复用,不联网)、`"purge"` 删条目(不给 `id` 就清空)。缓存里放的是"不属于插件、但建工程要用"的 CMSIS 设备头 + 启动文件 + 内核头,第一次用时才下载,之后一直复用 |
160
+ | `stm32_project_export` | 把工程打成一个 zip 交给别人:默认收源码、CMake、`.vscode`、`.ioc`,跳过 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`;`includePrebuilt: true` 把 `.elf` 一起带上,`readme: false` 不写包内 README,`outDir` 指定落点(默认工程同级的 `<name>-export.zip`) |
156
161
  | `stm32_firmware_install` | 缺固件包时的一条龙:`dryRun`(默认)只出计划——装到哪、下哪两个源码仓、几条自检判据;`dryRun: false` + `confirm: true` 才真下(GitHub 上 HAL 驱动与 CMSIS 设备支持两个源码包 + 内核头,合计约 2 MB),组装成与官方同构的 `STM32Cube_FW_<族>_V<版本>` 包(自写 `package.xml`)并过五条自检。已有官方包时什么都不做;默认装到 `<CubeMX 根>/dsh-firmware`(不是 `Repository`——塞自造版本号会被 CubeMX 静默忽略),生成时由 `stm32_generate` 用 `setCustomFWPath` 指过去 |
157
162
 
158
163
  ### .ioc:只读与事务
@@ -160,7 +165,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
160
165
  | 工具 | 作用 |
161
166
  | --- | --- |
162
167
  | `stm32_ioc_inspect` | 解析 MCU 型号、引脚/信号/标签、外设与中断、时钟树、工程设置;会报「没开 Serial Wire 会生成 `SWJ_DISABLE`」这类致命风险 |
163
- | `stm32_ioc_plan` | 改 `.ioc` 的第一步:算出逐键 diff 与源 SHA-256,返回 `planId`,**不动源文件**。支持改键、删键、按引脚表加 GPIO、一键补 Serial Wire |
168
+ | `stm32_ioc_plan` | 改 `.ioc` 的第一步:算出逐键 diff 与源 SHA-256,返回 `planId`,**不动源文件**。支持改键、删键、按引脚表加 GPIO、一键补 Serial Wire、按目标频率改时钟(`clock: { targetHz }`,就近取档 + 派生键重算 + 逐外设频率) |
164
169
  | `stm32_ioc_apply` | 必须带 `planId`;写盘前再核 SHA(中途被手改就拒绝),备份后原子替换,写完重新解析校验,不过自动回滚。支持 `rollbackFrom` |
165
170
 
166
171
  ### 代码与构建
@@ -169,13 +174,13 @@ pnpm add "link:D:\path\to\dsh-stm32"
169
174
  | --- | --- |
170
175
  | `stm32_code_patch` | 只在 `USER CODE` 块内 replace/append;块外字节(含 CRLF)原样保留;写前备份、临时文件 + rename 原子替换。标签写错会把该文件所有可用标签列给你 |
171
176
  | `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 里警告 |
172
- | `stm32_build` | `cmake --build`,构建目录从 `CMakePresets.json` 与 `build/*/CMakeCache.txt` 推断;首次构建自动 configure;会拦住"CMakeCache 目录不一致但 ninja 退出码 0"的假成功 |
177
+ | `stm32_build` | `cmake --build`,构建目录从 `CMakePresets.json` 与 `build/*/CMakeCache.txt` 推断;首次构建自动 configure;会拦住"CMakeCache 目录不一致但 ninja 退出码 0"的假成功。`artifacts: ["hex","bin"]` 时链接后用 `arm-none-eabi-objcopy` 转出,转换失败只记 note、不判编译失败 |
173
178
 
174
179
  ### 烧录与调试
175
180
 
176
181
  | 工具 | 作用 |
177
182
  | --- | --- |
178
- | `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点)) |
183
+ | `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点))。失败会带 `errorCode`(`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `unknown`);日志里找不到设备时,还会把 USB 形态(这台机器没有 USB / 没插探针 / 驱动异常)写进 notes |
179
184
  | `stm32_debug_run` | 起 openocd + gdb,`break main` → `continue` → 抓 pc/sp/lr/bt/locals → `reset run` + `detach`,不写 Flash、不常驻 |
180
185
  | `stm32_debug_session` | 常驻 openocd 会话(`.elf` 自动解析),空闲 90 s 自动关、硬上限 10 min |
181
186
  | `stm32_debug_eval` | 在会话里执行 gdb 命令或读表达式(如 `g_led_blink_count`),读完立刻 `resume` + `detach` |
@@ -189,6 +194,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
189
194
  | 命令 | 做什么 | 会不会动板子 |
190
195
  | --- | --- | --- |
191
196
  | `/stm32-doctor` | 体检:工具链、被占用的调试进程、端口、`.elf`、`.ioc` 告警 | 否 |
197
+ | `/stm32-setup` | 体检 + 安装计划一次跑完;命令里带「装」字才真装(例如 `/stm32-setup 装上缺的`) | 否 |
192
198
  | `/stm32-env` | 看四项能力(编译 / 烧录 / 调试 / 生成代码)各缺什么、装什么、装完怎么自检;缺件也照常出卡片 | 否 |
193
199
  | `/stm32-build [dir] [--clean]` | 编译,打印内存占用 / `.elf` / 错误 | 否 |
194
200
  | `/stm32-flash [dir]` | **烧录**:program + verify + reset,不建调试会话、不下断点 | 是 |
@@ -205,6 +211,12 @@ pnpm add "link:D:\path\to\dsh-stm32"
205
211
  - **烧前守卫。** 如果 `.ioc` 的 SYS 调试口不是 Serial Wire(PA13/PA14 缺失或被设成 `No_Debug`),CubeMX 会生成 `__HAL_AFIO_REMAP_SWJ_DISABLE()`——烧进去 SWD 立刻失联,只能 BOOT0 救砖。这种工程 `stm32_flash` 直接拒绝;确实要烧得显式传 `allowNoDebug: true`。
206
212
  - **探针只有一块。** 烧录、调试、后台会话同一时刻只能有一个;`build` / `flash` / `debug_run` / `generate` 开跑前会先把占着探针的会话关掉。
207
213
 
214
+ ## 芯片、链接脚本与时钟
215
+
216
+ - **型号是参数,不是常量。** `stm32_project_create` / `stm32_generate` 按 `mcu` 一起换三样:启动文件(`startup_stm32f103xe.s`)、设备宏(`STM32F103xE`)、链接脚本(`STM32F103RCTx_FLASH.ld`)。HAL 路线走 `src/engine/hal-chip.ts`(`resolveHalChip()` + `renderStartupAndDefine` / `renderLinkerScript` / `renderIoc`),寄存器路线走 `src/data/stm32f1.ts`(`resolveF1Chip()`,14 个容量档,每个启动文件都钉了上游 sha256)。认不出的型号直接给原因,不猜一个上游不存在的启动文件名。
217
+ - **链接脚本按 `DeviceId` 命名:`<DeviceId>_FLASH.ld`。** C8T6 → `STM32F103C8Tx_FLASH.ld`(64 KiB Flash / 20 KiB RAM),RCT6 → `STM32F103RCTx_FLASH.ld`(256 / 48),F107VCT6 → `STM32F107VCTx_FLASH.ld`(256 / 64)。模板里那份旧的 `STM32F103XX_FLASH.ld` 只作 C8T6 的兼容副本;CMake 的 `-T` 一律指向按型号渲染的那份(`pointLinkerFlagAt()` 把工具链文件里的旧名改指过去,避免两个 `-T` 让 ld 取错脚本)。
218
+ - **时钟就近,不可达就明说。** `stm32_ioc_plan` 的 `clock: { targetHz }`(也可 `pllMul` 钉死倍频、`pllSource` 选 HSE / HSI)枚举全部可行的 PLL 组合,取 |SYSCLK − 目标| 最小的一档,并把差距写进结论:要 60 MHz 时 F1 的 PLL 只能整数倍频、HSE 8 MHz 拼不出这一档,于是选 64 MHz 并标注「不可达,已选 64 MHz(+4 MHz)」(同距取更高档)。同一次 plan 里把 `SYSCLKFreq_VALUE` / `HCLKFre` / `PLLMUL` / APB1·APB2·ADC 分频这些派生键**全量重算**——只改 SYSCLK 不动它们,CubeMX 会按旧值重算或干脆不认;同时列出逐外设频率、UART 波特率的整除误差与几个备选档。超限(SYSCLK > 72 MHz、APB1 > 36 MHz、ADC > 14 MHz、USB 要 48 MHz 却不在 PLLCLK/1.5 这条路上)时**一个键都不写**。
219
+ - **烧前五项一致。** `stm32_doctor` 核对「`.ioc` 型号 ↔ 启动文件名 ↔ cmake 里的设备宏 ↔ `.ld` 的 MEMORY 容量 ↔ `.elf` 的 Flash 占用」,任一错配报 blocker。`.elf` 那份占用是读 ELF program header 的 `p_filesz` 累加,不是文件大小——带 `-g3` 时 20 KiB 固件的 `.elf` 能有 600 KB,按文件大小判会误报「超 Flash」。
208
220
  ## 配置
209
221
 
210
222
  ### 用户配置文件(`~/.dsh-stm32/config.json`)
@@ -311,7 +323,7 @@ source [find target/stm32f1x.cfg]
311
323
  | 限制 | 说明 | 有没有办法 |
312
324
  | --- | --- | --- |
313
325
  | 只在 **Windows** 上验证 | `stm32_generate` 依赖 `<CubeMX>/STM32CubeMX.exe` + `jre/bin/java.exe`,Linux/macOS 上的 CubeMX 不是这个形态 | 暂无;烧录/调试/读寄存器在 Linux 上若 openocd 与 gdb 齐全可能可用,但未验证 |
314
- | 只支持 **STM32F103C8T6** | 引脚表、`.ioc` 引脚校验、链接脚本模板都按 64 KiB Flash / 20 KiB RAM 的 C8T6 写 | 换芯片要改 `src/data/chips.ts` 与 `templates/` |
326
+ | 只覆盖 **STM32F1 全系** | 型号 → 启动文件 / 设备宏 / 链接脚本的映射只做了 F1(`src/data/stm32f1.ts` + `src/engine/hal-chip.ts`,14 个容量档);时钟树也只认 F1(HSE 8 MHz、PLL ×2..×16、SYSCLK ≤72 MHz) | 加其它族要补真实仓库名与逐文件实测 sha256(`src/data/cmsis-sources.ts`、`src/data/firmware-packages.ts`)并补一份时钟上限表;引脚表可由本机 CubeMX `db/mcu/*.xml` 派生(`deriveChipPinTable`) |
315
327
  | 默认探针是 **CMSIS-DAP** | 没有 `openocd.cfg` 时回退 cmsis-dap | 用 `openocd.cfg` 换 `interface/stlink.cfg`(见上) |
316
328
  | 新增外设要**手工补 HAL 源** | 插件只落位 CubeMX 的 `Src/` 与 `Inc/`(→ `Core/Src`、`Core/Inc`),CubeMX 生成的 `cmake/stm32cubemx/CMakeLists.txt` 不搬;开了定时器/串口/ADC 之后要自己把 `stm32f1xx_hal_<外设>.c` 加进源清单 | 改工程里 `cmake/stm32cubemx/CMakeLists.txt` 的 `STM32_Drivers_Src`,或写进 `cmake/user/CMakeLists.txt` 的 `target_sources` |
317
329
  | 生成/建工程需要 **CubeMX + F1 固件包** | 固件包版本默认 `STM32Cube_FW_F1_V1.8.7` | 换版本传 `firmwarePackage` |
@@ -321,6 +333,7 @@ source [find target/stm32f1x.cfg]
321
333
 
322
334
  | 现象 | 原因与处理 |
323
335
  | --- | --- |
336
+ | 装插件时 `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` | 这是**取包这一跳**连不上 GitHub(`dsh plugin add github:…` 会走 git 去拉仓库),跟 pnpm 11 的 `allowBuilds` 白名单、包体签名、包本身都没关系——换个网络就能装上。三条路按省事程度排:① 用 npm 上的正式包:`dsh plugin --profile desktop add dsh-stm32`(走 npm registry,不碰 GitHub);② 一定要从 GitHub 装,就只给这一条命令挂代理,用进程级 `GIT_CONFIG_*` 临时生效、**不动你的全局 git 配置**:`$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main`(端口换成你自己的);③ 绕开 git、直接吃 HTTPS 包:`dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`。**装最新**永远用 `github:JingYu-er/dsh-stm32#main`,已经 publish 的版本用 `dsh-stm32@latest`——两者内容一致,后者不依赖 GitHub |
324
337
  | 烧完连不上、SWD 失联 | 固件里生成了 `__HAL_AFIO_REMAP_SWJ_DISABLE()`。按住 BOOT0 上电进系统 bootloader 重烧,然后把 SYS 设回 Serial Wire——`stm32_flash` 现在会先拦这种情况 |
325
338
  | `Error: No device found` / `transfer count mismatch` | 探针被别的进程占着。先 `/stm32-stop`,再用 `stm32_doctor` 看 openocd / gdb 进程与 3333 端口。调试会话开着时读寄存器不会再有这个问题:`stm32_regs_read` 复用会话的 openocd,不另起第二个 |
326
339
  | 调试会话开着时读寄存器,`report.command` 是一条 `gdb-multiarch … target extended-remote 127.0.0.1:3333` | 这是「复用会话」的正常形态:`stm32_debug_session` 活着时,`stm32_regs_read` 用会话自己的 gdb 连接执行 `print/x $pc` 与 `print/x *(unsigned int *)0x…`,读完 `monitor resume` 再 detach,notes 第一条写「复用调试会话(端口 N)的 openocd,没有另起一个」;只有没有会话时才另起 openocd。旧版在这里会报 `CMSIS-DAP transfer count mismatch: expected N, got M` |
@@ -337,12 +350,25 @@ source [find target/stm32f1x.cfg]
337
350
 
338
351
  ```powershell
339
352
  npm run build # tsc -> lib/(lib/ 入库,改完 src 必须重建后一起提交)
340
- npm test # 24 个离线套件、309 个用例;不需要板子、CubeMX、工具链
353
+ npm test # 29 个离线套件、418 个用例;不需要板子、CubeMX、工具链
354
+ npm run test:pack # 把包打成 tarball、解开、用解包出来的 lib 真建一次寄存器工程
355
+ npm run test:size # 包体护栏:tarball ≤1.2 MB、templates ≤60 KB、包内不许二进制/图表
341
356
  ```
342
357
 
343
- CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test`(windows-latest)。
358
+ CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test → test:pack → test:size`(windows-latest)。
359
+
360
+ GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **416 pass + 2 skipped**,开发机上是 418 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
361
+
362
+ ### 发布形态三分法(先把东西放哪想清楚,再写包)
363
+
364
+ | 放哪 | 内容 | 量级 |
365
+ | --- | --- | --- |
366
+ | 随包(npm tarball) | `lib/**`(含 `lib/client.js`)、`client/client.js`、`templates/scaffold/**`、`cordis.patch.yml`、两份 README、`LICENSE`、`docs/*.md` | 99 个文件 / 525.7 KB,解包 1538.3 KB;其中 `templates/**` 38.5 KB |
367
+ | 进 git 不进包 | `src/**`、`test/**`、`scripts/**`、`docs/diagrams/**`(两张可交互 HTML) | diagrams 2 MB 原始 / 891 KB gz;`package.json` 的 `files` 把 `docs` 收窄成 `docs/*.md` |
368
+ | 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头(寄存器版首次用时下到缓存,逐文件钉 sha256);HAL 固件包 | 缓存可用 `stm32_cache list/verify/purge` 管 |
369
+ | 现造 | `.ioc` 内容(`renderIoc`)、`.ld` 的 MEMORY(`renderLinkerScript`)、cmake 源清单 | 按型号渲染,模板里不落盘 |
344
370
 
345
- GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **307 pass + 2 skipped**,开发机上是 309 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
371
+ 护栏是 `scripts/pack-size.mjs`(`npm run test:size`):tarball ≤ 1.2 MB(1 200 000 B)、`templates/**` ≤ 60 KB、包内禁止 `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll`,且必须含 `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md`。
346
372
 
347
373
  真机 e2e 会写板子,需要你指一个能构建的工程:
348
374
 
@@ -358,20 +384,23 @@ node test\e2e-flash.mjs
358
384
  ```text
359
385
  src/
360
386
  index.ts 插件入口(name / inject / apply)
361
- tools/ 19 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
387
+ tools/ 20 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
362
388
  engine/ 纯逻辑与工作流(generate / build / flash / debug / ioc / scaffold …)
363
- commands/register.ts 6 条斜杠命令
389
+ commands/register.ts 7 条斜杠命令
364
390
  skill/stm32-workflow.ts 随插件下发的 SKILL
365
391
  data/ 路径与芯片数据(路径是数据不是逻辑)
366
392
  templates/scaffold/ 建工程用的模板快照(CMake / .ld / .vscode / .ioc)
367
- test/ 离线套件 + fixtures + 真机 e2e
368
- docs/ 规格书 + 开发笔记
393
+ test/ 离线套件(29 个)+ fixtures + 真机 e2e
394
+ scripts/ 护栏与生成脚本(pack-size / pack-smoke / gen-chip-table / gen-xcube-catalog / copy-client)
395
+ docs/ 规格书 + 开发笔记 + 精读指南 + diagrams/(不进 npm 包)
369
396
  ```
370
397
 
371
398
  ## 文档
372
399
 
373
400
  - [规格书](docs/dsh-stm32-plugin-规格.md):工具契约、状态机、验收 A1–A13 的判定标准
374
401
  - [开发笔记](docs/development-notes.md):里程碑、宿主契约踩坑、每个工具的实现细节与实测数据
402
+ - [源码精读指南](docs/reading-guide.md):分层阅读顺序、每个文件的职责与关键导出、14 张流程图、20 条不变量
403
+ - 可视化:[架构总览](docs/diagrams/dsh-stm32-architecture.html) / [主线旅程](docs/diagrams/dsh-stm32-journey.html)(单文件 HTML,离线可开,可导出 PNG/SVG)
375
404
 
376
405
  ## 许可证
377
406
 
package/README_EN.md CHANGED
@@ -1,16 +1,16 @@
1
1
  # dsh-stm32
2
2
 
3
- > Hand the whole STM32F103C8T6 development chain to DSH: probe the toolchain → scaffold a project → edit the .ioc → generate code → build → debug → flash.
3
+ > Hand the whole **STM32F1 family** (F100/101/102/103/105/107) development chain to DSH: probe the toolchain → scaffold a project → edit the .ioc (clocks included) → generate code → build → debug → flash.
4
4
 
5
5
  [中文](./README.md) · [Quick start](#quick-start-a-minimal-end-to-end-check-empty-directory-to-a-blinking-led) · [Features](#features) · [Tool reference](#tool-reference) · [Slash commands](#slash-commands) · [Design notes](#design-notes) · [Known limitations](#known-limitations) · [Troubleshooting](#troubleshooting) · [Specification](docs/dsh-stm32-plugin-规格.md)
6
6
 
7
7
  [![GitHub stars](https://img.shields.io/github/stars/JingYu-er/dsh-stm32?color=4a6cf7)](https://github.com/JingYu-er/dsh-stm32)
8
8
  [![license](https://img.shields.io/github/license/JingYu-er/dsh-stm32)](LICENSE)
9
9
  [![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-4a6cf7)](#known-limitations)
10
- [![MCU](https://img.shields.io/badge/MCU-STM32F103C8T6-4a6cf7)](#known-limitations)
11
- [![version](https://img.shields.io/badge/version-0.1.1-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
10
+ [![MCU](https://img.shields.io/badge/MCU-STM32F1xx-4a6cf7)](#known-limitations)
11
+ [![version](https://img.shields.io/badge/version-0.1.2-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
12
12
 
13
- A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers 19 tools, 6 slash commands and 1 SKILL shipped with the plugin, so the model can probe the toolchain, scaffold a CubeMX CMake project, edit the `.ioc`, run CubeMX, build, flash and debug on its own, then read the state back out of the registers — hardware programming that actually stays inside DSH.
13
+ A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers 20 tools, 7 slash commands and 1 SKILL shipped with the plugin, so the model can probe the toolchain, scaffold a CubeMX CMake project, edit the `.ioc`, run CubeMX, build, flash and debug on its own, then read the state back out of the registers — hardware programming that actually stays inside DSH.
14
14
 
15
15
  ## Why you need it
16
16
 
@@ -55,7 +55,7 @@ dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
55
55
 
56
56
  All `dsh plugin` does is run `pnpm add` inside the profile directory. On success it also appends `dsh-stm32` to that profile's `dsh.profile.bundles`, so a restart of dsh is all that is left (use `web` instead of `desktop` to target the web profile).
57
57
 
58
- Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.1`); after a restart `/stm32-doctor` should respond.
58
+ Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.2`); after a restart `/stm32-doctor` should respond.
59
59
 
60
60
 
61
61
  **Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
@@ -67,7 +67,9 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
67
67
  cd dsh-stm32
68
68
  npm install --no-audit --no-fund # typescript only
69
69
  npm run build # tsc -> lib/ (required before committing)
70
- npm test # optional: 309 offline cases, no board needed
70
+ npm test # optional: 418 offline cases in 29 suites, no board needed
71
+ npm run test:pack # pack a tarball, unpack it, scaffold a real register project from it
72
+ npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
71
73
  ```
72
74
 
73
75
  Link it into your dsh profile — **while editing code use `link:`, never `file:`**:
@@ -104,6 +106,7 @@ On the model side it is one sentence: "create a blinking-LED project for STM32F1
104
106
  /stm32-flash # flash only, no debug session
105
107
  /stm32-debug # flash + halt at main
106
108
  /stm32-stop # close the debug session, hand the probe back to VS Code
109
+ /stm32-setup # health check + install plan (the word "install" in the command actually installs)
107
110
  ```
108
111
 
109
112
  ### This is a minimal check, not the ceiling
@@ -120,7 +123,7 @@ The blinking LED is the **smallest smoke test** for this chain: it walks create
120
123
  | Confirm a peripheral is really running after flashing | `stm32_regs_read` reads any peripheral register (`TIM2_CNT`, `USART1_SR`, `ADC1_DR` …), or `stm32_debug_eval` reads a variable | Reading registers by physical address verified (`GPIOC_ODR` / `AFIO_MAPR`) |
121
124
  | Something is wrong and you need the live state | `stm32_debug_run` halts at `main` for one snapshot; use `stm32_debug_session` + `stm32_debug_eval` for continuous debugging | Verified (halts at `main () at main.c:67`) |
122
125
 
123
- So the blinking LED is the acceptance sample, not the ceiling: **this covers the whole engineering chain, not one demo.** The real boundaries are the ones under [Known limitations](#known-limitations) — F103C8T6 only, verified on Windows only, CMSIS-DAP by default, plus the manual HAL-source step above. Peripheral types themselves are not limited by the tools: whatever the `.ioc` can configure goes through the same generate → build → flash → read-back chain; it just has not been tested peripheral by peripheral yet, so run `stm32_doctor` before starting a real project.
126
+ So the blinking LED is the acceptance sample, not the ceiling: **this covers the whole engineering chain, not one demo.** The real boundaries are the ones under [Known limitations](#known-limitations) — the STM32F1 family only (F100/101/102/103/105/107; the verified board is a C8T6), verified on Windows only, CMSIS-DAP by default, plus the manual HAL-source step above. Peripheral types themselves are not limited by the tools: whatever the `.ioc` can configure goes through the same generate → build → flash → read-back chain; it just has not been tested peripheral by peripheral yet, so run `stm32_doctor` before starting a real project.
124
127
 
125
128
  ## Features
126
129
 
@@ -130,12 +133,13 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
130
133
  | Pre-flight gate | Every tool that needs the toolchain runs `ensureToolchain` first: missing pieces are refused up front with what to install and what stops working; `envCheck: "block"` (default) / `"warn"` / `"off"` |
131
134
  | Install the toolchain | `stm32_env_install`: plan first (what is downloaded, how large, which PATH entry changes), install only after you confirm — MSYS2 + 5 pacman packages + a **user-level** PATH entry, then it writes the config file itself |
132
135
  | Choose the technical route | `stm32_route_plan`: for **this project's** requirements, lays out the HAL and register cost per peripheral (effort / readability / debugging), then says whether what is missing is installable-by-the-plugin or human-only (CubeMX is a GUI wizard needing an ST account; firmware packages are only maintained by the CubeMX package manager) |
133
- | Project from scratch | `stm32_project_create`: `route: "hal"` uses the template snapshot + firmware Drivers (byte-identical to a CubeMX GUI project); `route: "register"` builds a register-level project with no CubeMX at all, pulling the CMSIS template into the cache on first use |
136
+ | Project from scratch | `stm32_project_create`: `route: "hal"` uses the template snapshot + firmware Drivers (byte-identical to a CubeMX GUI project); `route: "register"` builds a register-level project with no CubeMX at all, pulling the CMSIS template into the cache on first use (every file is pinned by upstream sha256 and refused if it changed); `mcu` names the part (both routes accept it; the HAL route renders its startup file / device define / `<DeviceId>_FLASH.ld` from it); both routes also ship an `openocd.cfg` (CMSIS-DAP + `hla_swd` + 2 MHz) |
137
+ | Export a project | `stm32_project_export`: packs the sources into one zip (without `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`), optionally including the `.elf`, plus a hand-off README |
134
138
  | `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
135
139
  | USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
136
140
  | Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
137
- | Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking |
138
- | Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled |
141
+ | Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking; ask for `artifacts: ["hex","bin"]` and the same toolchain's `arm-none-eabi-objcopy` produces them |
142
+ | Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled; failures carry an `errorCode` (`no-probe` / `probe-busy` / `swd-locked` …) |
139
143
  | Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
140
144
  | Prove it is running | `stm32_regs_read`: reads any peripheral register back by physical address, halts, reads, then `resume` — no chip reset |
141
145
  | Working discipline for the model | SKILL `stm32-workflow` shipped with the plugin (USER CODE only, never touch generated regions, flash and debug are separate, claims need register evidence) |
@@ -152,6 +156,7 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
152
156
  | `stm32_doctor` | Answers three questions at once: is the toolchain complete, who holds the probe (`openocd.exe` / gdb processes / port 3333), can this project be flashed |
153
157
  | `stm32_project_create` | Empty directory → full CMake project. `route: "hal"` (default) is the CubeMX route (including both "flash only" and "flash and debug" launch configs in `.vscode`); `route: "register"` builds a **no-CubeMX, no-HAL** register-level project (`mcu` picks the part, CMSIS headers and startup file come from the cache). Refuses a non-empty target unless `overwrite: true` |
154
158
  | `stm32_cache` | Inspect / verify / fetch / purge the download cache: `action: "list"` (default), `"verify"` (per-file check), `"fetch"` (pull the template for an `mcu`, reusing the cache without touching the network), `"purge"` (drop entries; clears everything without an `id`). The cache holds what the register route needs but the plugin does not ship — CMSIS device headers, startup file, core headers — downloaded once, reused forever |
159
+ | `stm32_project_export` | Hands the project to someone else as one zip: sources, CMake, `.vscode` and the `.ioc` by default, skipping `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`; `includePrebuilt: true` also packs the `.elf`, `readme: false` skips the in-archive README, `outDir` moves the output (default `<name>-export.zip` next to the project) |
155
160
  | `stm32_firmware_install` | One-stop firmware-package install: `dryRun` (default) returns only the plan — where it would land, which two source repos it would download, which checks must pass; `dryRun: false` + `confirm: true` actually downloads (HAL driver + CMSIS device support + core headers, ~2 MB total from GitHub), assembles an official-shaped `STM32Cube_FW_<family>_V<version>` package (writing `package.xml` itself) and runs five checks. Does nothing when the official package is already installed; installs into `<CubeMX root>/dsh-firmware` by default (not `Repository` — a self-made version there is silently ignored), and `stm32_generate` points CubeMX at it with `setCustomFWPath` |
156
161
 
157
162
  ### .ioc: read-only and transactions
@@ -159,7 +164,7 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
159
164
  | Tool | What it does |
160
165
  | --- | --- |
161
166
  | `stm32_ioc_inspect` | Parses MCU part, pins/signals/labels, peripherals and interrupts, clock tree, project settings; reports fatal risks such as "no Serial Wire means a generated `SWJ_DISABLE`" |
162
- | `stm32_ioc_plan` | Step one of any `.ioc` change: computes a per-key diff plus the source SHA-256 and returns a `planId`, **without touching the source**. Supports setting/removing keys, adding GPIO from the chip pin table, and one-shot Serial Wire repair |
167
+ | `stm32_ioc_plan` | Step one of any `.ioc` change: computes a per-key diff plus the source SHA-256 and returns a `planId`, **without touching the source**. Supports setting/removing keys, adding GPIO from the chip pin table, one-shot Serial Wire repair, and retargeting clocks to the nearest reachable frequency (`clock: { targetHz }`, derived keys recomputed, per-peripheral frequencies reported) |
163
168
  | `stm32_ioc_apply` | Requires a `planId`; re-checks the SHA before writing (refuses if the file changed meanwhile), backs up, replaces atomically, re-parses to validate, rolls back on failure. Supports `rollbackFrom` |
164
169
 
165
170
  ### Code and build
@@ -168,13 +173,13 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
168
173
  | --- | --- |
169
174
  | `stm32_code_patch` | replace/append inside `USER CODE` blocks only; bytes outside (including CRLF) are preserved; backs up first, then writes a temp file and renames it. A wrong label lists every available label in the file |
170
175
  | `stm32_generate` | Runs `java -jar STM32CubeMX.exe -q` headless, then places output under `Core/Src` and `Core/Inc`, carrying USER CODE from the old files by label. Background job by default. **When the `.ioc`, the CubeMX build and every output hash are unchanged it reuses the previous result** (`skipped: true`, ~1 s; pass `skipIfUnchanged: false` or delete `.dsh-stm32/generate-cache.json` to force a rerun). Projects that use no X-CUBE pack (`Mcu.ThirdPartyNb=0`) have `~/.stm32cubemx/thirdparties/pdsc` parked for the run and restored afterwards, saving ~25 s; pass `thirdpartyPacks: "keep"` to keep the index. **The need for the index is not guessed from keywords**: `Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` in the `.ioc` is matched by name against a built-in pack catalog (67 packs, generated by `scripts/gen-xcube-catalog.mjs`), and a pack this machine lacks is reported in the notes up front |
171
- | `stm32_build` | `cmake --build`, with the build directory inferred from `CMakePresets.json` and `build/*/CMakeCache.txt`; configures on first build; rejects the "CMakeCache directory mismatch but ninja exits 0" false success |
176
+ | `stm32_build` | `cmake --build`, with the build directory inferred from `CMakePresets.json` and `build/*/CMakeCache.txt`; configures on first build; rejects the "CMakeCache directory mismatch but ninja exits 0" false success. With `artifacts: ["hex","bin"]` it converts the `.elf` afterwards via `arm-none-eabi-objcopy`; a failed conversion is only a note, not a build failure |
172
177
 
173
178
  ### Flash and debug
174
179
 
175
180
  | Tool | What it does |
176
181
  | --- | --- |
177
- | `stm32_flash` | **Flash**: openocd `program verify reset exit`, no debug session, no halt at `main`. Reads the `.ioc` first and refuses when the debug port is disabled (see [Design notes](#design-notes)) |
182
+ | `stm32_flash` | **Flash**: openocd `program verify reset exit`, no debug session, no halt at `main`. Reads the `.ioc` first and refuses when the debug port is disabled (see [Design notes](#design-notes)). Failures carry an `errorCode` (`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `unknown`), and when no device is found the USB shape (no USB on this machine / probe unplugged / driver problem) is added to the notes |
178
183
  | `stm32_debug_run` | Starts openocd + gdb, `break main` → `continue` → captures pc/sp/lr/bt/locals → `reset run` + `detach`; no Flash write, nothing left running |
179
184
  | `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
180
185
  | `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
@@ -188,6 +193,7 @@ Tools are for the model; when you want to act yourself, use a command — one co
188
193
  | Command | What it does | Touches the board |
189
194
  | --- | --- | --- |
190
195
  | `/stm32-doctor` | Health check: toolchain, busy debug processes, ports, `.elf`, `.ioc` warnings | No |
196
+ | `/stm32-setup` | Health check plus an install plan in one go; only actually installs when the command says so (e.g. `/stm32-setup install the missing ones`) | No |
191
197
  | `/stm32-env` | Shows what each of the four capabilities (build / flash / debug / generate) is missing, what to install and how to self-check; a missing toolchain still renders the card | No |
192
198
  | `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
193
199
  | `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
@@ -204,6 +210,12 @@ Tools are for the model; when you want to act yourself, use a command — one co
204
210
  - **Flash guard.** If SYS is not Serial Wire (PA13/PA14 missing or set to `No_Debug`), CubeMX generates `__HAL_AFIO_REMAP_SWJ_DISABLE()` — flash that and SWD is gone, recoverable only via BOOT0. `stm32_flash` refuses such projects; pass `allowNoDebug: true` if you really mean it.
205
211
  - **One probe at a time.** Flashing, debugging and a background session cannot coexist; `build` / `flash` / `debug_run` / `generate` release any session holding the probe before they start.
206
212
 
213
+ ## Chips, linker scripts and clocks
214
+
215
+ - **The part is a parameter, not a constant.** `stm32_project_create` / `stm32_generate` swap three things together from `mcu`: the startup file (`startup_stm32f103xe.s`), the device define (`STM32F103xE`) and the linker script (`STM32F103RCTx_FLASH.ld`). The HAL route goes through `src/engine/hal-chip.ts` (`resolveHalChip()` + `renderStartupAndDefine` / `renderLinkerScript` / `renderIoc`); the register route goes through `src/data/stm32f1.ts` (`resolveF1Chip()`, 14 density grades, every startup file pinned by upstream sha256). An unknown part returns a reason instead of inventing a startup file that does not exist upstream.
216
+ - **Linker scripts are named after the `DeviceId`: `<DeviceId>_FLASH.ld`.** C8T6 → `STM32F103C8Tx_FLASH.ld` (64 KiB Flash / 20 KiB RAM), RCT6 → `STM32F103RCTx_FLASH.ld` (256 / 48), F107VCT6 → `STM32F107VCTx_FLASH.ld` (256 / 64). The old `STM32F103XX_FLASH.ld` in the template survives only as a C8T6 compatibility copy; CMake's `-T` always points at the rendered one (`pointLinkerFlagAt()` rewrites the old name inside the toolchain file so you never end up with two `-T` flags and the wrong script).
217
+ - **Clocks: nearest, and say so when unreachable.** `stm32_ioc_plan`'s `clock: { targetHz }` (or `pllMul` to pin the multiplier, `pllSource` to pick HSE / HSI) enumerates every reachable PLL combination, takes the one with the smallest |SYSCLK − target| and states the gap: for 60 MHz the F1 PLL only multiplies integers and HSE 8 MHz cannot hit that step, so it picks 64 MHz and reports "unreachable, chose 64 MHz (+4 MHz)" (ties go to the higher step). The same plan **recomputes every derived key** (`SYSCLKFreq_VALUE`, `HCLKFre`, `PLLMUL`, APB1/APB2/ADC dividers) — changing only SYSCLK leaves CubeMX recomputing from stale values or ignoring them — and lists per-peripheral frequencies, UART baud error and a few alternatives. On an out-of-range request (SYSCLK > 72 MHz, APB1 > 36 MHz, ADC > 14 MHz, USB wanting 48 MHz outside PLLCLK/1.5) it **writes no key at all**.
218
+ - **Five consistency checks before flashing.** `stm32_doctor` cross-checks `.ioc` part ↔ startup file name ↔ device define in cmake ↔ `.ld` MEMORY sizes ↔ `.elf` Flash usage, and reports a blocker on any mismatch. The `.elf` figure sums `p_filesz` from the ELF program headers rather than using the file size — with `-g3` a 20 KiB firmware produces a 600 KB `.elf`, which would false-alarm "over Flash".
207
219
  ## Configuration
208
220
 
209
221
  ### User config file (`~/.dsh-stm32/config.json`)
@@ -308,7 +320,7 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
308
320
  | Limitation | Detail | Workaround |
309
321
  | --- | --- | --- |
310
322
  | Only verified on **Windows** | `stm32_generate` depends on `<CubeMX>/STM32CubeMX.exe` + `jre/bin/java.exe`; CubeMX on Linux/macOS is not shaped like that | None yet; flash/debug/register reads may work on Linux with openocd and gdb present, but are untested |
311
- | **STM32F103C8T6** only | The pin table, `.ioc` pin validation and linker-script template assume a C8T6 with 64 KiB Flash / 20 KiB RAM | Porting means editing `src/data/chips.ts` and `templates/` |
323
+ | **STM32F1 family** only | The part → startup file / device define / linker script maps exist for F1 only (`src/data/stm32f1.ts` + `src/engine/hal-chip.ts`, 14 density grades); the clock tree knows F1 only (HSE 8 MHz, PLL ×2..×16, SYSCLK ≤72 MHz) | Another family needs real repo names plus per-file measured sha256 (`src/data/cmsis-sources.ts`, `src/data/firmware-packages.ts`) and a clock-limit table; the pin table itself can be derived from the local CubeMX `db/mcu/*.xml` (`deriveChipPinTable`) |
312
324
  | Default probe is **CMSIS-DAP** | Falls back to cmsis-dap without an `openocd.cfg` | Put `interface/stlink.cfg` into `openocd.cfg` (see above) |
313
325
  | Adding a peripheral needs a **manual HAL source entry** | The plugin only relocates CubeMX's `Src/` and `Inc/` (→ `Core/Src`, `Core/Inc`); the `cmake/stm32cubemx/CMakeLists.txt` CubeMX emits is not applied. Enable a timer/UART/ADC and you must add the matching `stm32f1xx_hal_<peripheral>.c` yourself | Edit `STM32_Drivers_Src` in the project's `cmake/stm32cubemx/CMakeLists.txt`, or add a `target_sources` line in `cmake/user/CMakeLists.txt` |
314
326
  | Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
@@ -318,6 +330,7 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
318
330
 
319
331
  | Symptom | Cause and fix |
320
332
  | --- | --- |
333
+ | `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` while installing | The **package fetch hop** cannot reach GitHub (`dsh plugin add github:…` clones over git). It is unrelated to the pnpm 11 `allowBuilds` allow-list, package signatures, or a broken tarball — the same command works from another network. Three options, easiest first: (1) install the published package: `dsh plugin --profile desktop add dsh-stm32` (npm registry, no GitHub); (2) if you must install from GitHub, proxy **only that one command** with process-scoped `GIT_CONFIG_*` (your global git config stays untouched): `$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main` (use your own port); (3) skip git entirely and take the HTTPS tarball: `dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`. For the newest code use `github:JingYu-er/dsh-stm32#main`; for a published release use `dsh-stm32@latest` — same content, no GitHub dependency |
321
334
  | SWD lost after flashing | The firmware generated `__HAL_AFIO_REMAP_SWJ_DISABLE()`. Hold BOOT0 while powering up to enter the system bootloader and reflash, then set SYS back to Serial Wire — `stm32_flash` now blocks this case first |
322
335
  | `Error: No device found` / `transfer count mismatch` | Another process holds the probe. Run `/stm32-stop`, then use `stm32_doctor` to inspect openocd / gdb processes and port 3333. Reading registers while a debug session is open no longer hits this: `stm32_regs_read` reuses the session's openocd instead of starting a second one |
323
336
  | Reading registers with a live session shows a `gdb-multiarch … target extended-remote 127.0.0.1:3333` `report.command` | That is the normal "reuse" shape: while `stm32_debug_session` is alive, `stm32_regs_read` drives the session's own gdb connection with `print/x $pc` and `print/x *(unsigned int *)0x…`, then `monitor resume` and detach; the first note reads "reusing the openocd of the debug session (port N), not starting another". Only without a session does it start its own openocd. Older builds failed here with `CMSIS-DAP transfer count mismatch: expected N, got M` |
@@ -334,12 +347,25 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
334
347
 
335
348
  ```powershell
336
349
  npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
337
- npm test # 24 offline suites, 309 cases; no board, CubeMX, or toolchain needed
350
+ npm test # 29 offline suites, 418 cases; no board, CubeMX, or toolchain needed
351
+ npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
352
+ npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
338
353
  ```
339
354
 
340
- CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test` on every push and PR (windows-latest).
355
+ CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test → test:pack → test:size` on every push and PR (windows-latest).
356
+
357
+ A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **416 passed + 2 skipped**, while a developer machine runs all 418. The offline suites only read the bundled [`test/fixtures/`](test/fixtures/README.md); the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
358
+
359
+ ### What ships where (decide before you add a file)
360
+
361
+ | Where | What | Size |
362
+ | --- | --- | --- |
363
+ | npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` | 99 files / 525.7 KB packed, 1538.3 KB unpacked; `templates/**` alone is 38.5 KB |
364
+ | Git only, not packed | `src/**`, `test/**`, `scripts/**`, `docs/diagrams/**` (two interactive HTML pages) | diagrams are 2 MB raw / 891 KB gz; `files` in `package.json` narrows `docs` to `docs/*.md` |
365
+ | Downloaded on demand | CMSIS device headers / startup files / core headers (fetched into the cache on first use, pinned per file by sha256); HAL firmware packages | manage the cache with `stm32_cache list/verify/purge` |
366
+ | Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
341
367
 
342
- A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **307 passed + 2 skipped**, while a developer machine runs all 309. The offline suites only read the bundled [`test/fixtures/`](test/fixtures/README.md); the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
368
+ The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤ 1.2 MB (1 200 000 B), `templates/**` ≤ 60 KB, no `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll` inside, and `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md` all present.
343
369
 
344
370
  Hardware e2e writes to the board and needs a project you point it at:
345
371
 
@@ -355,20 +381,23 @@ See the [development notes](docs/development-notes.md) for the suite breakdown a
355
381
  ```text
356
382
  src/
357
383
  index.ts plugin entry (name / inject / apply)
358
- tools/ the 19 tools, L3 (parameter schema + output contract + rendering)
384
+ tools/ the 20 tools, L3 (parameter schema + output contract + rendering)
359
385
  engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
360
- commands/register.ts the 6 slash commands
386
+ commands/register.ts the 7 slash commands
361
387
  skill/stm32-workflow.ts the SKILL shipped with the plugin
362
388
  data/ paths and chip data (paths are data, not logic)
363
389
  templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
364
- test/ offline suites + fixtures + hardware e2e
365
- docs/ specification + development notes
390
+ test/ offline suites (29) + fixtures + hardware e2e
391
+ scripts/ guards and generators (pack-size / pack-smoke / gen-chip-table / gen-xcube-catalog / copy-client)
392
+ docs/ specification + development notes + reading guide + diagrams/ (not packed)
366
393
  ```
367
394
 
368
395
  ## Documentation
369
396
 
370
397
  - [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
371
398
  - [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
399
+ - [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 20 invariants
400
+ - Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
372
401
 
373
402
  ## License
374
403