dsh-stm32 0.1.3 → 0.1.4

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 (221) hide show
  1. package/README.md +52 -38
  2. package/README_EN.md +44 -33
  3. package/assets/README.md +85 -0
  4. package/assets/VERSION +1 -0
  5. package/assets/device/c0/chips.json +1108 -0
  6. package/assets/device/f0/chips.json +1570 -0
  7. package/assets/device/f1/chips.json +1238 -0
  8. package/assets/device/f1/svd/100.json +943 -0
  9. package/assets/device/f1/svd/101.json +901 -0
  10. package/assets/device/f1/svd/102.json +522 -0
  11. package/assets/device/f1/svd/103.json +1139 -0
  12. package/assets/device/f1/svd/105.json +1117 -0
  13. package/assets/device/f1/svd/107.json +1195 -0
  14. package/assets/device/f2/chips.json +674 -0
  15. package/assets/device/f3/chips.json +1318 -0
  16. package/assets/device/f4/chips.json +2942 -0
  17. package/assets/device/f7/chips.json +1710 -0
  18. package/assets/device/g0/chips.json +2102 -0
  19. package/assets/device/g4/chips.json +2494 -0
  20. package/assets/device/h5/chips.json +898 -0
  21. package/assets/device/h7/chips.json +1948 -0
  22. package/assets/device/l0/chips.json +2494 -0
  23. package/assets/device/l1/chips.json +1234 -0
  24. package/assets/device/l4/chips.json +2130 -0
  25. package/assets/device/l4+/chips.json +856 -0
  26. package/assets/device/l5/chips.json +226 -0
  27. package/assets/device/u0/chips.json +688 -0
  28. package/assets/device/u3/chips.json +310 -0
  29. package/assets/device/u5/chips.json +884 -0
  30. package/assets/device/wba/chips.json +506 -0
  31. package/assets/device/wl/chips.json +184 -0
  32. package/assets/headers/f1/stm32f100xb.h +5972 -0
  33. package/assets/headers/f1/stm32f100xe.h +6587 -0
  34. package/assets/headers/f1/stm32f101x6.h +5315 -0
  35. package/assets/headers/f1/stm32f101xb.h +5446 -0
  36. package/assets/headers/f1/stm32f101xe.h +6503 -0
  37. package/assets/headers/f1/stm32f101xg.h +6713 -0
  38. package/assets/headers/f1/stm32f102x6.h +6448 -0
  39. package/assets/headers/f1/stm32f102xb.h +6570 -0
  40. package/assets/headers/f1/stm32f103x6.h +10109 -0
  41. package/assets/headers/f1/stm32f103xb.h +10240 -0
  42. package/assets/headers/f1/stm32f103xe.h +11767 -0
  43. package/assets/headers/f1/stm32f103xg.h +11951 -0
  44. package/assets/headers/f1/stm32f105xc.h +14340 -0
  45. package/assets/headers/f1/stm32f107xc.h +15253 -0
  46. package/assets/headers/f1/stm32f1xx.h +273 -0
  47. package/assets/headers/f1/system_stm32f1xx.h +96 -0
  48. package/assets/ioc/family/C0.ioc +82 -0
  49. package/assets/ioc/family/F0.ioc +71 -0
  50. package/assets/ioc/family/F2.ioc +91 -0
  51. package/assets/ioc/family/F3.ioc +94 -0
  52. package/assets/ioc/family/F4.ioc +91 -0
  53. package/assets/ioc/family/F7.ioc +102 -0
  54. package/assets/ioc/family/G0.ioc +90 -0
  55. package/assets/ioc/family/G4.ioc +110 -0
  56. package/assets/ioc/family/H5.ioc +116 -0
  57. package/assets/ioc/family/H7.ioc +133 -0
  58. package/assets/ioc/family/L0.ioc +92 -0
  59. package/assets/ioc/family/L1.ioc +87 -0
  60. package/assets/ioc/family/L4+.ioc +92 -0
  61. package/assets/ioc/family/L4.ioc +93 -0
  62. package/assets/ioc/family/L5.ioc +91 -0
  63. package/assets/ioc/family/U0.ioc +103 -0
  64. package/assets/ioc/family/U3.ioc +113 -0
  65. package/assets/ioc/family/U5.ioc +102 -0
  66. package/assets/ioc/family/WBA.ioc +100 -0
  67. package/assets/ioc/family/WL.ioc +93 -0
  68. package/assets/ioc/minimal/STM32F100C8Tx.ioc +113 -0
  69. package/assets/ioc/minimal/STM32F100RCTx.ioc +113 -0
  70. package/assets/ioc/minimal/STM32F101C4Tx.ioc +113 -0
  71. package/assets/ioc/minimal/STM32F101C8Tx.ioc +113 -0
  72. package/assets/ioc/minimal/STM32F101RCTx.ioc +113 -0
  73. package/assets/ioc/minimal/STM32F101RFTx.ioc +113 -0
  74. package/assets/ioc/minimal/STM32F102C4Tx.ioc +113 -0
  75. package/assets/ioc/minimal/STM32F102C8Tx.ioc +113 -0
  76. package/assets/ioc/minimal/STM32F103C4Tx.ioc +113 -0
  77. package/assets/ioc/minimal/STM32F103C8Tx.ioc +113 -0
  78. package/assets/ioc/minimal/STM32F103RCTx.ioc +113 -0
  79. package/assets/ioc/minimal/STM32F103RFTx.ioc +113 -0
  80. package/assets/ioc/minimal/STM32F105RCTx.ioc +113 -0
  81. package/assets/ioc/minimal/STM32F107RCTx.ioc +113 -0
  82. package/assets/ld/f1/STM32F100C8Tx_FLASH.ld +249 -0
  83. package/assets/ld/f1/STM32F100RCTx_FLASH.ld +249 -0
  84. package/assets/ld/f1/STM32F101C4Tx_FLASH.ld +249 -0
  85. package/assets/ld/f1/STM32F101C8Tx_FLASH.ld +249 -0
  86. package/assets/ld/f1/STM32F101RCTx_FLASH.ld +249 -0
  87. package/assets/ld/f1/STM32F101RFTx_FLASH.ld +249 -0
  88. package/assets/ld/f1/STM32F102C4Tx_FLASH.ld +249 -0
  89. package/assets/ld/f1/STM32F102C8Tx_FLASH.ld +249 -0
  90. package/assets/ld/f1/STM32F103C4Tx_FLASH.ld +249 -0
  91. package/assets/ld/f1/STM32F103C8Tx_FLASH.ld +249 -0
  92. package/assets/ld/f1/STM32F103RCTx_FLASH.ld +249 -0
  93. package/assets/ld/f1/STM32F103RFTx_FLASH.ld +249 -0
  94. package/assets/ld/f1/STM32F105RCTx_FLASH.ld +249 -0
  95. package/assets/ld/f1/STM32F107RCTx_FLASH.ld +249 -0
  96. package/assets/manifest.json +1130 -0
  97. package/assets/startup/f1/startup_stm32f100xb.s +407 -0
  98. package/assets/startup/f1/startup_stm32f100xe.s +449 -0
  99. package/assets/startup/f1/startup_stm32f101x6.s +322 -0
  100. package/assets/startup/f1/startup_stm32f101xb.s +338 -0
  101. package/assets/startup/f1/startup_stm32f101xe.s +423 -0
  102. package/assets/startup/f1/startup_stm32f101xg.s +439 -0
  103. package/assets/startup/f1/startup_stm32f102x6.s +330 -0
  104. package/assets/startup/f1/startup_stm32f102xb.s +346 -0
  105. package/assets/startup/f1/startup_stm32f103x6.s +348 -0
  106. package/assets/startup/f1/startup_stm32f103xb.s +364 -0
  107. package/assets/startup/f1/startup_stm32f103xe.s +470 -0
  108. package/assets/startup/f1/startup_stm32f103xg.s +466 -0
  109. package/assets/startup/f1/startup_stm32f105xc.s +463 -0
  110. package/assets/startup/f1/startup_stm32f107xc.s +472 -0
  111. package/assets/templates/family/C0.ioc +82 -0
  112. package/assets/templates/family/F0.ioc +71 -0
  113. package/assets/templates/family/F2.ioc +91 -0
  114. package/assets/templates/family/F3.ioc +94 -0
  115. package/assets/templates/family/F4.ioc +91 -0
  116. package/assets/templates/family/F7.ioc +102 -0
  117. package/assets/templates/family/G0.ioc +90 -0
  118. package/assets/templates/family/G4.ioc +110 -0
  119. package/assets/templates/family/H5.ioc +116 -0
  120. package/assets/templates/family/H7.ioc +133 -0
  121. package/assets/templates/family/L0.ioc +92 -0
  122. package/assets/templates/family/L1.ioc +87 -0
  123. package/assets/templates/family/L4+.ioc +92 -0
  124. package/assets/templates/family/L4.ioc +93 -0
  125. package/assets/templates/family/L5.ioc +91 -0
  126. package/assets/templates/family/U0.ioc +103 -0
  127. package/assets/templates/family/U3.ioc +113 -0
  128. package/assets/templates/family/U5.ioc +102 -0
  129. package/assets/templates/family/WB.ioc +81 -0
  130. package/assets/templates/family/WBA.ioc +100 -0
  131. package/assets/templates/family/WL.ioc +93 -0
  132. package/docs/reading-guide.md +37 -35
  133. package/lib/data/chips.js +3 -3
  134. package/lib/data/clock-db.js +830 -0
  135. package/lib/data/clock-f1.js +12 -45
  136. package/lib/data/cmsis-sources.js +239 -18
  137. package/lib/data/db-presets.js +252 -0
  138. package/lib/data/device-facts.js +99 -26
  139. package/lib/data/family.js +515 -0
  140. package/lib/data/firmware-packages.js +562 -0
  141. package/lib/data/install-guides.js +2 -2
  142. package/lib/data/ioc-presets.js +248 -0
  143. package/lib/data/ioc-schema.js +1058 -0
  144. package/lib/data/rm-topics/stm32c0.json +227 -0
  145. package/lib/data/rm-topics.js +103 -0
  146. package/lib/data/search-roots.js +42 -1
  147. package/lib/data/stm32f1.js +15 -14
  148. package/lib/data/svd.js +32 -16
  149. package/lib/data/toolchain-config.js +0 -14
  150. package/lib/engine/assets.js +191 -456
  151. package/lib/engine/breakpoints.js +66 -11
  152. package/lib/engine/clock-derived.js +101 -0
  153. package/lib/engine/clock-direct.js +313 -0
  154. package/lib/engine/clock-plan.js +96 -52
  155. package/lib/engine/clock-pllmn.js +319 -0
  156. package/lib/engine/cmake-sources.js +67 -13
  157. package/lib/engine/cube-mx-guard.js +44 -0
  158. package/lib/engine/cube-programmer.js +137 -0
  159. package/lib/engine/cubemx-db.js +273 -0
  160. package/lib/engine/debug-session.js +423 -17
  161. package/lib/engine/debug.js +25 -6
  162. package/lib/engine/doctor.js +160 -17
  163. package/lib/engine/facts-acquire.js +416 -0
  164. package/lib/engine/facts.js +134 -0
  165. package/lib/engine/firmware-install.js +176 -5
  166. package/lib/engine/firmware-official.js +451 -0
  167. package/lib/engine/flash.js +290 -21
  168. package/lib/engine/gdb-mi.js +476 -0
  169. package/lib/engine/generate.js +9 -2
  170. package/lib/engine/hal-chip.js +124 -41
  171. package/lib/engine/ioc-plan.js +1244 -60
  172. package/lib/engine/ioc-rules.js +698 -0
  173. package/lib/engine/ioc-verify.js +706 -0
  174. package/lib/engine/ioc.js +43 -4
  175. package/lib/engine/msys2-install.js +4 -4
  176. package/lib/engine/probe-error.js +25 -6
  177. package/lib/engine/probe-session.js +50 -14
  178. package/lib/engine/probe.js +18 -3
  179. package/lib/engine/register-clock.js +41 -0
  180. package/lib/engine/register-gpio.js +115 -0
  181. package/lib/engine/register-linker.js +12 -7
  182. package/lib/engine/register-template.js +101 -40
  183. package/lib/engine/regs.js +41 -8
  184. package/lib/engine/rm-extract.js +144 -0
  185. package/lib/engine/rm-sources.js +360 -0
  186. package/lib/engine/rm-text.js +56 -0
  187. package/lib/engine/rtt.js +188 -30
  188. package/lib/engine/scaffold.js +185 -18
  189. package/lib/engine/toolchain-gate.js +0 -4
  190. package/lib/engine/watch.js +227 -0
  191. package/lib/index.js +4 -2
  192. package/lib/skill/stm32-workflow.js +2 -2
  193. package/lib/tools/assets.js +39 -108
  194. package/lib/tools/cache.js +2 -2
  195. package/lib/tools/debug-session.js +2 -2
  196. package/lib/tools/doctor.js +55 -5
  197. package/lib/tools/firmware-install.js +31 -6
  198. package/lib/tools/flash.js +32 -4
  199. package/lib/tools/generate.js +22 -0
  200. package/lib/tools/ioc-inspect.js +1 -1
  201. package/lib/tools/ioc-plan.js +56 -2
  202. package/lib/tools/ioc-verify.js +237 -0
  203. package/lib/tools/project-create.js +41 -5
  204. package/lib/tools/regs.js +8 -8
  205. package/lib/tools/route-plan.js +1 -1
  206. package/lib/tools/rtt.js +157 -34
  207. package/lib/tools/watch.js +256 -0
  208. package/package.json +5 -4
  209. package/templates/openocd/stm32c0x.cfg +83 -0
  210. package/templates/openocd/stm32u0x.cfg +64 -0
  211. package/templates/register/CMakeLists.txt +2 -2
  212. package/templates/register/Core/Inc/rtt.h +37 -2
  213. package/templates/register/Core/Src/main.c +17 -25
  214. package/templates/register/Core/Src/rtt.c +85 -9
  215. package/templates/scaffold/RTT.md +6 -2
  216. package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
  217. package/templates/scaffold/openocd.cfg +5 -3
  218. package/templates/scaffold/vscode/launch.json +8 -4
  219. package/docs/development-notes.md +0 -2487
  220. package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
  221. package/docs/logic-audit.md +0 -607
package/README.md CHANGED
@@ -1,18 +1,18 @@
1
1
  # dsh-stm32
2
2
 
3
- > 让 DSH 接管 **STM32F1 全系**(F100/101/102/103/105/107)的整条开发链:探测工具链 → 建工程 → 改 .ioc(含时钟) → 生成代码 → 编译 → 调试 → 烧录。
3
+ > 让 DSH 接管 **STM32 全系列**(27 个族:C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / MP1 / MP2 / N6 / U0 / U3 / U5 / WB / WB0 / WBA / WL / WL3)的整条开发链:探测工具链 → 建工程 → 改 .ioc(含时钟) → 生成代码 → 编译 → 调试 → 烧录。族画像从 `.ioc` 的 `Mcu.Family` 判定:引脚名、SWD 调试信号名、EXTI 的 NVIC 向量分组、openocd target、硬件断点/观察点预算都随族与内核走;**HAL 建工程**(固件包 / 启动文件 / 设备宏 / 链接脚本 / .ioc 模板 / cmake 与调试配置)已按族实现并覆盖 21 个单核族(C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL);寄存器版覆盖 13 族(C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / L0 / L1 / L4 / U0);时钟规划覆盖 18 族(其中 PLL1 四族 H5 / U5 / WBA / L4+),.ioc 外设预设已改为按 CubeMX db 派生;SVD 校验仍只有 F1 —— 未覆盖的能力会**明确拒绝并说明原因**,不会悄悄套 F1 的表(见[已知限制](#已知限制))。
4
4
 
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.
5
+ **English:** STM32 across 27 families (C0 / F0 / F1 / … / WL3) 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. Pin names, SWD debug signals, EXTI NVIC vector grouping, the openocd target and the hardware breakpoint budget all follow the family and its core; HAL scaffolding covers 21 single-core families, the register route 13, clock planning 18 (PLL1 on four families), and .ioc peripheral presets are derived from the CubeMX db; SVD validation is still F1-only, and uncovered capabilities are refused explicitly instead of silently reusing F1 tables.
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-STM32F1xx-4a6cf7)](#已知限制)
13
- [![version](https://img.shields.io/badge/version-0.1.3-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
12
+ [![MCU](https://img.shields.io/badge/MCU-STM32%20family-4a6cf7)](#已知限制)
13
+ [![version](https://img.shields.io/badge/version-0.1.4-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
14
14
 
15
- 这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 21 个工具、7 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
15
+ 这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 23 个工具、7 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
16
16
 
17
17
  ## 为什么需要它
18
18
 
@@ -51,14 +51,14 @@
51
51
  ### 安装(推荐:一条命令)
52
52
 
53
53
  ```powershell
54
- dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
54
+ dsh plugin --profile desktop add dsh-stm32
55
55
  ```
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.3`;重启后 `/stm32-doctor` 有输出。
59
+ 装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.4`;重启后 `/stm32-doctor` 有输出。
60
60
 
61
- > **首次使用要联网拉一次资源包**:插件不内置任何芯片表,设备事实(型号 → 启动文件 / 设备宏 / Flash·RAM 容量)在第一次用到时由 `stm32_assets` 自动装一次(`profile: "core"`,30 个文件约 237 KiB:芯片表 + 内存布局 + `.ioc` 模板 + 链接脚本)。装好之后整条链离线可用,换版本才会再联网。
61
+ > **芯片事实随插件内置**:设备事实(型号 → 启动文件 / 设备宏 / Flash·RAM 容量)来自包内的 `assets/device/<族>/chips.json`(core 75 个文件、full 105 个文件:芯片表 + 内存布局 + `.ioc` 模板 + 链接脚本 + SVD),装好即可离线使用,不需要联网拉资源包。`stm32_assets verify` 可校验完整性;缺文件通常意味着安装不完整。
62
62
 
63
63
 
64
64
  **卸载**:`dsh plugin --profile desktop remove dsh-stm32`,重启 dsh。
@@ -70,9 +70,9 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
70
70
  cd dsh-stm32
71
71
  npm install --no-audit --no-fund # 只装 typescript
72
72
  npm run build # tsc -> lib/(提交前必须跑)
73
- npm test # 可选:497 个离线用例、34 个套件,不需要板子
73
+ npm test # 可选:736 个离线用例、43 个套件,不需要板子
74
74
  npm run test:pack # 打包 tarball → 解包 → 用解包出来的 lib 真建一次寄存器工程
75
- npm run test:size # 包体护栏:tarball ≤1.2 MB、templates ≤60 KB、包内不许二进制/图表
75
+ npm run test:size # 包体护栏:tarball ≤1.2 MB、templates 里的运行时资产(.ioc/.xml/.ld/.json/.cfg)≤40 KB、包内不许二进制/图表
76
76
  ```
77
77
 
78
78
  挂进 dsh 的 profile——**改代码时必须用 `link:`,不要用 `file:`**:
@@ -100,7 +100,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
100
100
  | 5 | **只烧录**:program + verify + reset | `stm32_flash` | 2.1–2.6 s |
101
101
  | 6 | 读回 `GPIOC.ODR`(或地址 `0x4001100C`),确认状态确实在翻 | `stm32_regs_read` | 0.4–1.3 s |
102
102
 
103
- > 第 6 步用的是符号写法(`GPIOC.ODR`)。它靠资源包里的 SVD 表:`stm32_assets action="refresh" profile="full"`(128 个文件,其中 SVD 1.71 MiB)。只装了 `core` 也能读——但要写地址 `0x4001100C`,报告里没有寄存器名,也没有位域解释。
103
+ > 第 6 步用的是符号写法(`GPIOC.ODR`),靠插件内置的 SVD 表(`assets/device/f1/svd/`,full 逻辑层)。只装 `core` 或安装不完整也能读——但要写地址 `0x4001100C`,报告里没有寄存器名,也没有位域解释。
104
104
 
105
105
  模型侧就是一句话:「在 `D:\work\blink` 建一个 STM32F103C8T6 的闪灯工程,编译并烧进去」。想自己敲就:
106
106
 
@@ -125,7 +125,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
125
125
  | 多源文件、自己写的模块 | 写进 `cmake/user/CMakeLists.txt`,模板已留好位置 | 位置就位;未单独实测 |
126
126
  | 业务代码 | `stm32_code_patch` 按块写入,重新生成时按标签搬回 | 已实测(append / replace / 标签写错会列出全部可用标签) |
127
127
  | 调参数、改时钟 | `.ioc` 事务:先 diff → SHA 校验 → 备份 → 失败回滚 | 已实测 |
128
- | 烧完确认外设真的在动 | `stm32_regs_read` 读任意外设寄存器——符号名 `TIM2.CNT` / `USART1.SR` / `ADC1.DR`…或物理地址 `0x40000024`;只写外设名 `GPIOC` 就把它的 7 个寄存器整体 dump。也可以 `stm32_debug_eval` 读变量 | 地址写法已上板实测(`0x4001100C` / `0x40010004`);符号名与位域解释用真实资源包 + 假探针验证,**真机待复测**(开发笔记 §31.11) |
128
+ | 烧完确认外设真的在动 | `stm32_regs_read` 读任意外设寄存器——符号名 `TIM2.CNT` / `USART1.SR` / `ADC1.DR`…或物理地址 `0x40000024`;只写外设名 `GPIOC` 就把它的 7 个寄存器整体 dump。也可以 `stm32_debug_eval` 读变量 | 地址写法已上板实测(`0x4001100C` / `0x40010004`);符号名与位域解释用真实内置 SVD + 假探针验证,**真机待复测**(开发笔记 §31.11) |
129
129
  | 出问题要看现场 | `stm32_debug_run` 停在 `main` 抓一次;要连续调就开 `stm32_debug_session` + `stm32_debug_eval` | 已实测(停在 `main () at main.c:67`) |
130
130
 
131
131
  所以闪灯是验收用的最小样例,不是这套工具的能力上限:**它覆盖的是整条工程链,而不是一个 demo。** 真正的边界在[已知限制](#已知限制)里——芯片支持 F1 全系(F100/101/102/103/105/107,本机验证板是 C8T6)但只到 F1、宿主只在 Windows 上验证、探针默认 CMSIS-DAP,以及上面那条「新增外设要手工补 HAL 源」。外设种类本身不受工具限制:`.ioc` 里配得出来的,生成、编译、烧录、读回都走同一条链;只是除闪灯外还没有逐项上板实测,正式开项目前先跑一遍 `stm32_doctor`。
@@ -134,21 +134,22 @@ pnpm add "link:D:\path\to\dsh-stm32"
134
134
 
135
135
  | 能力 | 提供方式 |
136
136
  | --- | --- |
137
- | 环境体检 | `stm32_env_probe`(只读)、`stm32_doctor`(工具链 + 探针占用 + 端口 + 工程告警) |
137
+ | 环境体检 | `stm32_doctor`(只读)、`stm32_doctor`(工具链 + 探针占用 + 端口 + 工程告警) |
138
138
  | 开工前门禁 | 每个会动工具链的工具先过 `ensureToolchain`:缺件就拦住并写清装什么、缺了会怎样;`envCheck: "block"`(默认)/ `"warn"` / `"off"` 由调用方决定 |
139
139
  | 装工具链 | `stm32_env_install`:先只出计划(下载什么、多大、要改哪条 PATH),你点头才真装 MSYS2 + 5 个 pacman 包 + 用户级 PATH,装完自己写进配置文件 |
140
140
  | 选技术路线 | `stm32_route_plan`:先按**这个工程**的需求,把每个外设的 HAL 版与寄存器版代价摆出来(效率 / 可读性 / 排错),再告诉你缺的是「能代装的」还是「只能人装的」(CubeMX 是 GUI 向导 + 要 ST 账号、固件包只由 CubeMX 包管理器维护) |
141
- | 设备事实(型号 → 启动文件 / 设备宏 / 容量) | 插件**不内置芯片表**:型号、启动文件、设备宏、Flash/RAM 这些事实只从本地资源包缓存读(`~/.dsh-stm32/assets/<版本>/device/f1/chips.json`,`DSH_STM32_ASSETS` 可换根目录),第一次用到时自动装一次(`stm32_assets` 的 `refresh`),装好之后离线可用。没网又没缓存时 `stm32_project_create` / `stm32_doctor` 会明说「先跑 stm32_assets refresh,或检查网络」,不会拿内置表凑一个可能错的启动文件名 |
141
+ | 设备事实(型号 → 启动文件 / 设备宏 / 容量) | 插件**内置芯片表**(随 npm 包分发):型号、启动文件、设备宏、Flash/RAM 只从包内 `assets/device/f1/chips.json` 读(`lib/engine/assets.js` 从包根解析 `assets/`;`DSH_STM32_ASSETS` 仍可指向外部目录做开发覆盖)。文件缺失只说明安装不完整:`stm32_assets verify` 定位,重装插件即可,不需要联网 |
142
142
  | 从零建工程 | `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) |
143
143
  | 导出工程 | `stm32_project_export`:源码打成一个 zip(默认不带 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`),可选把 `.elf` 一起带上,并写一份开箱 README |
144
144
  | `.ioc` 事务 | `stm32_ioc_inspect`(只读解析)→ `stm32_ioc_plan`(算 diff,不写盘)→ `stm32_ioc_apply`(SHA 校验 + 备份 + 回滚) |
145
145
  | 只改 USER CODE | `stm32_code_patch`:只写 `/* USER CODE BEGIN X */` 与 `END X` 之间,块外逐字节不动 |
146
146
  | 生成代码 | `stm32_generate`:无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 |
147
147
  | 编译 | `stm32_build`:构建目录与 `.elf` 自动推断、错误去重、链接后解析 RAM/FLASH 占用;`artifacts` 里要 `hex` / `bin` 就用同一套 `arm-none-eabi-objcopy` 转出来 |
148
- | 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire;失败时给结构化 `probeError`(`kind` / `cause` / `hint` / `evidence` / `retryable`,`kind` 收 8 类) |
148
+ | 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire;失败时给结构化 `probeError`(`kind` / `cause` / `hint` / `evidence` / `retryable`,`kind` 收 9 类) |
149
149
  | 调试 | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
150
150
  | 验证"真的在跑" | `stm32_regs_read`:按地址或符号名(`GPIOC.ODR`)把任意外设寄存器读回来,有 SVD 时顺带解位域(`→ ODR5=1`);halt 读值后 `resume`,不复位芯片 |
151
151
  | 固件日志(RTT) | `stm32_rtt`:控制块按 SEGGER 约定放在 RAM,openocd 的 `rtt setup/start/server start` 把通道 0 搬成 TCP 流,再按 13 字节头解出级别与时间戳——不接串口、不改接线 |
152
+ | 变量监视 / 观察点 | `stm32_watch`:`action=add` 登记表达式(`kind=value` 只是采样,不用开会话);`action=sample` 停下→逐项求值→算 delta→原本在跑就放回;`kind=write/read/access` 装成硬件观察点(gdb `watch`/`rwatch`/`awatch`),受 F1 的 4 个数据比较器预算约束 |
152
153
  | 给模型的工作纪律 | 随插件下发 SKILL `stm32-workflow`(只改 USER CODE、不动生成区、烧录与调试分开、结论要带寄存器证据) |
153
154
 
154
155
  ## 工具参考
@@ -157,23 +158,24 @@ pnpm add "link:D:\path\to\dsh-stm32"
157
158
 
158
159
  | 工具 | 作用 |
159
160
  | --- | --- |
160
- | `stm32_env_probe` | 探测 gcc / gdb / openocd / cmake / ninja / CubeMX / JRE 的路径与版本;缺什么会写清影响(编译不了 / 烧不了 / 调不了 / 建不了工程)、推荐装法(含可粘贴的 pacman / winget 命令)、装完自检命令,并给 `capabilities`(四项能力是否可用)与 `recommendations`(安装顺序 + 要不要我帮你装)。只读、可重复调 |
161
+ | `stm32_doctor` | 探测 gcc / gdb / openocd / cmake / ninja / CubeMX / JRE 的路径与版本;缺什么会写清影响(编译不了 / 烧不了 / 调不了 / 建不了工程)、推荐装法(含可粘贴的 pacman / winget 命令)、装完自检命令,并给 `capabilities`(四项能力是否可用)与 `recommendations`(安装顺序 + 要不要我帮你装)。只读、可重复调 |
161
162
  | `stm32_env_install` | 缺工具链时的一条龙:`dryRun`(默认)只给计划——官方 MSYS2 安装包多大、要装哪 5 个包、PATH 会加哪一条;`dryRun: false` + `confirm: true` 才真干活(下载 → 装 MSYS2 → `pacman -S` → 写 **用户级** PATH → 自检 → 写 `~/.dsh-stm32/config.json`)。已装 msys64 时只补包。不做卸载 |
162
163
  | `stm32_route_plan` | 动手前先把路线问清楚:`requirement` 必填(如「按键控制 LED,串口每秒打印一次状态」),返回 `verdict`(`register-ok` / `both-viable` / `hal-only` / `unclear`)、逐外设的 `halEffort`/`regEffort` 与 `advice`、两种写法的差别、落地的下一步、工具链缺件(每条标 `installability`:`auto` 可代装 / `manual` 只能人装)与手动安装指引全文。不做通用对照表——结论只对当前需求成立 |
163
164
  | `stm32_doctor` | 一次回答三件事:工具链齐不齐、探针被谁占(`openocd.exe` / gdb 进程 / 3333 端口)、这个工程能不能烧 |
164
165
  | `stm32_project_create` | 空目录 → 完整 CMake 工程。`route: "hal"`(默认)走 CubeMX 那套(含 `.vscode` 里"① 只烧录 / ② 烧录并调试"两份配置);`route: "register"` 建**不用 CubeMX、不用 HAL** 的寄存器版工程(`mcu` 指定型号——F1 全系都吃;寄存器版从缓存取 CMSIS 头与启动文件,HAL 版按型号渲染启动文件 / 设备宏 / `.ld`)。目标目录非空默认拒绝,`overwrite: true` 才覆盖 |
165
- | `stm32_assets` | 管**设备事实资源包**(芯片表 / 内存布局 / .ioc 模板 / 链接脚本 / SVD,不是 CMSIS 下载缓存):`action: "refresh"`(默认 `profile: "core"`,30 个文件约 237 KiB;已装同版本直接复用;`profile: "full"` 是 128 个文件,多加 SVD 等表)从 GitHub → jsDelivr → gitcode 多源拉 `manifest.json`,逐文件钉 sha256 装到 `~/.dsh-stm32/assets/<版本>/`;`list` / `verify` / `prune` 管各版本。**插件不再内置任何芯片表**,设备事实只从这里读,第一次用要联网装一次,装好后离线可用 |
166
+ | `stm32_assets` | 管**插件内置资源**(21 个族的芯片表 / 内存布局 / .ioc 模板 / 链接脚本 / SVD,不是 CMSIS 下载缓存):`action: "list"` / `"verify"` 查看与逐文件校验内置 `assets/`(core 75 个文件、full 105 个文件,随包分发,离线可用);`"refresh"` 是 `verify` 的别名(不做下载);`"prune"` 只清 `DSH_STM32_ASSETS` 下遗留的历史版本。缺文件说明安装不完整,重装插件即可 |
166
167
  | `stm32_cache` | 看 / 验 / 拉 / 清下载缓存:`action: "list"`(默认)列条目、`"verify"` 逐文件校验、`"fetch"` 按 `mcu` 拉一次模板(已缓存则直接复用,不联网)、`"purge"` 删条目(不给 `id` 就清空)。缓存里放的是"不属于插件、但建工程要用"的 CMSIS 设备头 + 启动文件 + 内核头,第一次用时才下载,之后一直复用 |
167
168
  | `stm32_project_export` | 把工程打成一个 zip 交给别人:默认收源码、CMake、`.vscode`、`.ioc`,跳过 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`;`includePrebuilt: true` 把 `.elf` 一起带上,`readme: false` 不写包内 README,`outDir` 指定落点(默认工程同级的 `<name>-export.zip`) |
168
- | `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` 指过去 |
169
+ | `stm32_firmware_install` | 缺固件包时的一条龙,两条通道:`source: "auto"`(默认)先按 db 的 `FwLibrary` 拼官方 zip 的 URL 下载(验 `Content-Length` + 逐条 CRC32),再交给 CubeMX 自己的 `swmgr install` 装进 `Repository`——包被包管理器正经认下;装不成(没 CubeMX、跑着 GUI、首次装新族要弹许可协议窗)就把原因写进 `notes`,回退 GitHub 拼包(HAL 驱动 + CMSIS 设备支持 + 内核头约 2 MB,自写 `package.xml`,放进 `<CubeMX 根>/dsh-firmware`,生成时用 `setCustomFWPath` 指过去)。`source: "official"` 只走官网、失败直接报错。`dryRun`(默认)只出计划,`dryRun: false` + `confirm: true` 才真装;已有包时什么都不做 |
169
170
 
170
171
  ### .ioc:只读与事务
171
172
 
172
173
  | 工具 | 作用 |
173
174
  | --- | --- |
174
175
  | `stm32_ioc_inspect` | 解析 MCU 型号、引脚/信号/标签、外设与中断、时钟树、工程设置;会报「没开 Serial Wire 会生成 `SWJ_DISABLE`」这类致命风险 |
175
- | `stm32_ioc_plan` | 改 `.ioc` 的第一步:算出逐键 diff 与源 SHA-256,返回 `planId`,**不动源文件**。支持改键、删键、按引脚表加 GPIO、一键补 Serial Wire、按目标频率改时钟(`clock: { targetHz }`,就近取档 + 派生键重算 + 逐外设频率) |
176
+ | `stm32_ioc_plan` | 改 `.ioc` 的第一步:算出逐键 diff 与源 SHA-256,返回 `planId`,**不动源文件**。支持改键、删键、按引脚表加 GPIO(上下拉/速度/开漏 `outputType: od`/初始电平 `initial`/`interrupt` 一次写全 EXTI 链路 + 中断组)、`interrupts` 使能外设中断(写 9 段 NVIC 值并按 db/SVD 校验中断名)、一键补 Serial Wire、按目标频率改时钟(`clock: { targetHz }`,就近取档 + 派生键重算 + 逐外设频率)。键名按 `src/data/ioc-schema.ts` 的 `.ioc` 真值表(49 条 spec)渲染。覆盖率闸门分两层:不在表里的键给 `[SCHEMA]` 警告;`{ip}.{name}` 这类只证「形状」的命中再按现场审计(db 的 `RefParameter` 参数名、`Mcu.IP<i>` 是否启用、Dma 参数白名单),拼错参数名/实例名同样报出来——拼错的键 CubeMX 静默忽略。启用外设时把 `Mcu.IP<i>` 按 CubeMX 自己的 natural 序重排(`TIM2…TIM4,TIM15`,板名等伪实例置尾),否则每次启用字典序靠前的外设,回写都会冒出几条假 diff |
176
177
  | `stm32_ioc_apply` | 必须带 `planId`;写盘前再核 SHA(中途被手改就拒绝),备份后原子替换,写完重新解析校验,不过自动回滚。支持 `rollbackFrom` |
178
+ | `stm32_ioc_verify` | 让 CubeMX 自己说「它认了什么」:把 `.ioc` 复制到 `.dsh-stm32/verify/<stamp>/`,无头 `config load` + `config save` 回写后逐键 diff(实测一次 100–180 s,工程 `.ioc` 一个字节不动;CubeMX 没保存完直接判失败,不拿「零 diff」假通过)。报 `droppedPeripherals` / `plannedFunctions` / `signalRewrites` / `removedKeys` / `addedKeys` / `changedValues`,以及归因 `attribution`:`orderOnly`(值相同、行序不同)/ `valueNormalized`(只是成员顺序被规范化)/ `valueChanged`(值真被改)/ `ipOrderOnly`(只有 `Mcu.IP<i>` 换位、外设集合不变,不算实质差异)/ `derivedRecomputed`(`RCC.*Freq_Value` 这类**派生频率**被 CubeMX 按 PLL/分频重算——不是设定,计划里没写过就不算差异)/ `derivedAdded`(它按树自己补的派生键)/ `ipParametersAdded`(`RCC.IPParameters` 里它追加的派生名) / `droppedReasons` 与 `addedVerdicts`(**逐键给「为什么它不认」**:外设没进 `Mcu.IP<i>`、参数名不在 db 的 `RefParameter` 清单里、把引脚属性写成了外设参数、前缀纯拼错)/ `benign`——**`benign: true` 就是零实质差异**,可以放心去 `stm32_generate` |
177
179
 
178
180
  ### 代码与构建
179
181
 
@@ -187,12 +189,13 @@ pnpm add "link:D:\path\to\dsh-stm32"
187
189
 
188
190
  | 工具 | 作用 |
189
191
  | --- | --- |
190
- | `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点))。失败会带结构化 `probeError`:`kind`(`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `timeout` / `unknown` 共 8 类)、`cause`(一句话根因)、`hint`(可执行的下一步,每类都有专属建议)、`evidence`(原始日志行)、`retryable`(照 hint 处理完再调一次有没有意义);成功时这个字段根本不出现。日志里找不到设备时,还会把 USB 形态(这台机器没有 USB / 没插探针 / 驱动异常)写进 notes |
192
+ | `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点))。失败会带结构化 `probeError`:`kind`(`no-probe` / `probe-interface-mismatch` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `timeout` / `unknown` 共 9 类)、`cause`(一句话根因)、`hint`(可执行的下一步,每类都有专属建议)、`evidence`(原始日志行)、`retryable`(照 hint 处理完再调一次有没有意义);成功时这个字段根本不出现。日志里找不到设备时,还会把 USB 形态(这台机器没有 USB / 没插探针 / 驱动异常)写进 notes |
191
193
  | `stm32_debug_run` | 起 openocd + gdb,`break main` → `continue` → 抓 pc/sp/lr/bt/locals → `reset run` + `detach`,不写 Flash、不常驻。硬件断点 / 观察点超芯片上限(F1 是 6 个断点 / 4 个观察点)会在起 openocd **之前**就报错,不占探针 |
192
194
  | `stm32_debug_session` | 常驻 openocd 会话(`.elf` 自动解析),空闲 90 s 自动关、硬上限 10 min |
193
195
  | `stm32_debug_eval` | 在会话里执行 gdb 命令或读表达式(如 `g_led_blink_count`),读完立刻 `resume` + `detach` |
194
196
  | `stm32_debug_stop` | 立刻释放探针,幂等 |
195
- | `stm32_regs_read` | 读寄存器,`addresses` 五种写法:物理地址 `0x4001100C` / `4001100C`、符号名 `GPIOC.ODR` / `GPIOC->ODR`、只写外设名 `GPIOC`(按偏移升序把它的 7 个寄存器整体 dump,上限 64 条)。装了资源包的 `full` profile 时,每条样本带规范化名与**置位位域**(`GPIOC.ODR (0x4001100C) = 0x00000020 → ODR5=1`);未知外设会列出可用的前 10 个(共 53 个),未知寄存器会列出该外设的已知寄存器;没有 SVD 时纯地址照读(只是没有名字与位域),符号名报错并提示 `stm32_assets refresh --profile full`。收尾用 `resume` 而不是 `reset run`,避免读一眼就把固件状态清零;连读时复用常驻 openocd 会话(毫秒级,不另起进程),没有会话才起一次并保留 90 s |
197
+ | `stm32_regs_read` | 读寄存器,`addresses` 五种写法:物理地址 `0x4001100C` / `4001100C`、符号名 `GPIOC.ODR` / `GPIOC->ODR`、只写外设名 `GPIOC`(按偏移升序把它的 7 个寄存器整体 dump,上限 64 条)。内置资源含 SVD(full 逻辑层)时,每条样本带规范化名与**置位位域**(`GPIOC.ODR (0x4001100C) = 0x00000020 → ODR5=1`);未知外设会列出可用的前 10 个(共 53 个),未知寄存器会列出该外设的已知寄存器;没有 SVD 时纯地址照读(只是没有名字与位域),符号名报错并提示「SVD 只在 profile=full:重装插件」。收尾用 `resume` 而不是 `reset run`,避免读一眼就把固件状态清零;连读时复用常驻 openocd 会话(毫秒级,不另起进程),没有会话才起一次并保留 90 s |
198
+ | `stm32_watch` | **变量监视与硬件观察点**:`action: "add"` 登记表达式(`expressions`,`kind` 默认 `value`=每次 `sample` 求值;`write` / `read` / `access` 走 gdb `watch` / `rwatch` / `awatch`,是**数据**比较器,和代码断点不共用预算,F1 只有 4 个,超出在起进程之前就拒绝)。`kind=value` 只登记、不需要会话。`action: "sample"` 停下→逐项求值→和上次值算 `delta`→原本在跑就 `monitor resume` 放回去(`resume: false` 可留住);出错时保留上一次的值并写 `lastError`。`action: "list"` / `"remove"`(`ids`)/ `"clear"` 管登记表。生命周期:会话 `stop` 时清表(观察点住在 gdb 进程里);MI 重建会把观察点标成失效并提示重新 `add`。gdb 退回**软件观察点**时会在 `notes` 里警告(会拖慢目标) |
196
199
  | `stm32_rtt` | **RTT 日志**(不占串口):`action: "start"` 先用 `mdw` 读三个字确认 RAM 里真有 `SEGGER RTT` 控制块(`addr` 填控制块起始地址,不是通道缓冲地址),再发 `rtt setup/start/server start`;没有活跃会话时自己起一个。`action: "dump"` 读 `seconds`(默认 3 s)或 `maxRecords`(默认 200 条),返回 `records[{ t, level, text }]`——`level` 是**保留到哪一级**(1 error / 2 warn / 3 info / 4 debug,默认 4 全要),`dropped` / `truncated` 如实报。`action: "stop"` 幂等(turn 结束也会自动停),`action: "status"` 看端口与已运行时长。目标必须**真在跑**(`rtt start` 读的是运行时 RAM)。失败带 `probeError`:控制块全 0 = 固件没调 `rtt_init()`、魔数不符 = `addr` 填错、连不上 = 会话掉了或 9090 端口被占 |
197
200
 
198
201
  ### 固件里怎么加 RTT(最短示例)
@@ -248,7 +251,7 @@ stm32_rtt action=stop # 释放端口;turn 结束也会自
248
251
 
249
252
  ## 芯片、链接脚本与时钟
250
253
 
251
- - **型号是参数,不是常量。** `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)。认不出的型号直接给原因,不猜一个上游不存在的启动文件名。
254
+ - **型号是参数,不是常量。** `stm32_project_create` / `stm32_generate` 按 `mcu` 一起换三样:启动文件(`startup_stm32f103xe.s`)、设备宏(`STM32F103xE`)、链接脚本(`STM32F103RCTx_FLASH.ld`)。HAL 路线走 `src/engine/hal-chip.ts`(`resolveHalChip()` 按族分发:F1 走手写 RAM 表,其它族走内置资源的 `device/<族>/chips.json`;`renderStartupAndDefine` / `renderLinkerScript` / `renderIoc` / `renderCmakeLists` / `renderOpenocdTarget`),寄存器路线走 `src/data/stm32f1.ts`(`resolveF1Chip()`,14 个容量档,每个启动文件都钉了上游 sha256)。认不出的型号直接给原因,不猜一个上游不存在的启动文件名。
252
255
  - **链接脚本按 `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 取错脚本)。
253
256
  - **时钟就近,不可达就明说。** `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 这条路上)时**一个键都不写**。
254
257
  - **烧前五项一致。** `stm32_doctor` 核对「`.ioc` 型号 ↔ 启动文件名 ↔ cmake 里的设备宏 ↔ `.ld` 的 MEMORY 容量 ↔ `.elf` 的 Flash 占用」,任一错配报 blocker。`.elf` 那份占用是读 ELF program header 的 `p_filesz` 累加,不是文件大小——带 `-g3` 时 20 KiB 固件的 `.elf` 能有 600 KB,按文件大小判会误报「超 Flash」。
@@ -273,7 +276,7 @@ stm32_rtt action=stop # 释放端口;turn 结束也会自
273
276
 
274
277
  **优先级**:工具参数(`binDirs` / `cubeMxRoots`)> 环境变量 > 这个配置文件 > 内置默认值;自动发现只追加在"没点名参数"的那一档尾部。
275
278
 
276
- **内置默认值里没有任何"某台机器专属"的路径**:只有 `C:/msys64/...` 与 `C:/Program Files/...` 这种 Windows 默认安装位置,装在别处靠自动发现兜底。配置或环境变量里点名的目录如果在本机不存在(典型情况:配置是从别的机器拷过来的,带着 `D:/app/msys64` 这种路径),门禁与 `stm32_env_probe` 会明确写一句「配置文件里的 X 在本机不存在……这一条搜不到工具」,而**不会**悄悄改你的配置;安装器也不会拿这种路径当安装目标(盘符都没有时只提示、并要求你给 `targetDir`)。
279
+ **内置默认值里没有任何"某台机器专属"的路径**:只有 `C:/msys64/...` 与 `C:/Program Files/...` 这种 Windows 默认安装位置,装在别处靠自动发现兜底。配置或环境变量里点名的目录如果在本机不存在(典型情况:配置是从别的机器拷过来的,带着 `D:/app/msys64` 这种路径),门禁与 `stm32_doctor` 会明确写一句「配置文件里的 X 在本机不存在……这一条搜不到工具」,而**不会**悄悄改你的配置;安装器也不会拿这种路径当安装目标(盘符都没有时只提示、并要求你给 `targetDir`)。
277
280
 
278
281
  ### 设置面板(GUI)
279
282
 
@@ -297,7 +300,12 @@ stm32_rtt action=stop # 释放端口;turn 结束也会自
297
300
 
298
301
  ### 固件包下载(HAL 路线)
299
302
 
300
- CubeMX 装好也不一定有**这一颗芯片**的固件包(安装包里不带,得在包管理器里另装)。插件能代下的那一代,`stm32_firmware_install` 会从 GitHub 拉两个源码包组装出来:
303
+ CubeMX 装好也不一定有**这一颗芯片**的固件包(安装包里不带,得在包管理器里另装)。`stm32_firmware_install` 有两条通道,默认先试官网:
304
+
305
+ - 官网直取(`source: "auto"` 的第一步):按 db 里那颗芯片的 `FwLibrary`(多数族为空,按族名兜底;H7RS / MP13 / WB0 / WL3 有专名)拼 `https://sw-center.st.com/packs/resource/firmware/stm32cube_fw_<族小写>_v<版本去点>.zip`,下载后验 `Content-Length` 与 zip 里每一条的 CRC32,再调 CubeMX 的 `swmgr install <本地 zip> ask` 装进 `Repository`——这个包是 CubeMX 自己记账的,包管理器里看得见、删得掉;
306
+ - 三种失败会把原因写进 `notes` 再回退下面的 GitHub 拼包:没装 CubeMX、CubeMX 正开着 GUI、**首次装某族的新版本时 CubeMX 要弹许可协议窗等人点同意**(无头只能超时,插件不替你点,也不代勾);`source: "official"` 则只走这条,失败直接报错;
307
+
308
+ 回退通道(GitHub 拼包):
301
309
 
302
310
  - 下什么:`stm32f1xx-hal-driver`(HAL 驱动,BSD-3-Clause)+ `cmsis-device-f1`(设备头与启动文件,Apache-2.0)+ 5 个 CMSIS 内核头,合计约 2 MB、几秒钟;
303
311
  - 为什么不能直接解压 `STM32CubeF1` 的源码包:它的 HAL 与 CMSIS 设备目录是 **git 子模块**,tarball 里是空目录——解压出来编译必挂(缺 startup、缺 HAL 源文件);
@@ -346,7 +354,10 @@ transport select hla_swd
346
354
  source [find target/stm32f1x.cfg]
347
355
  ```
348
356
 
349
- 没有 `openocd.cfg` 时回退 `interface/cmsis-dap.cfg` + `target/stm32f1x.cfg`。ST-Link 用户请把上面第二段写进工程根目录的 `openocd.cfg`。
357
+ 没有 `openocd.cfg` 时**按 `.ioc` 的 `Mcu.Family` 选 target**(F1 → `target/stm32f1x.cfg`、F4 → `target/stm32f4x.cfg`、G4 → `target/stm32g4x.cfg` …;L4 与 L4+ 共用 `stm32l4x`)。
358
+ C0 / U0 这两族 openocd 0.12 里没有官方脚本,插件自带一份适配版:建工程时会复制到工程的 `openocd/stm32c0x.cfg`(U0 同理),
359
+ `openocd.cfg` 里写 `source [find openocd/stm32c0x.cfg]`,`.vscode/launch.json` 用 `${workspaceFolder}/openocd/stm32c0x.cfg`。
360
+ 其它没有脚本的族(H5 / N6 / U3 / WBA / WB0 / WL3 / MP2)会**明确拒绝烧录**,不会拿别的族的脚本硬连。ST-Link 用户把上面第二段写进工程根目录的 `openocd.cfg` 即可。
350
361
 
351
362
  ### .ioc 的两个硬要求
352
363
 
@@ -358,13 +369,15 @@ source [find target/stm32f1x.cfg]
358
369
  | 限制 | 说明 | 有没有办法 |
359
370
  | --- | --- | --- |
360
371
  | 只在 **Windows** 上验证 | `stm32_generate` 依赖 `<CubeMX>/STM32CubeMX.exe` + `jre/bin/java.exe`,Linux/macOS 上的 CubeMX 不是这个形态 | 暂无;烧录/调试/读寄存器在 Linux 上若 openocd 与 gdb 齐全可能可用,但未验证 |
361
- | 只覆盖 **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`) |
362
- | 默认探针是 **CMSIS-DAP** | 没有 `openocd.cfg` 时回退 cmsis-dap | 用 `openocd.cfg` 换 `interface/stlink.cfg`(见上) |
372
+ | **C0 / U0 的 target 脚本是插件自带的** | openocd 0.12 没有 `stm32c0x.cfg` / `stm32u0x.cfg`,插件内置适配版(只把 `dap create … -tap` 换成 `-chain-position`),建工程时复制进工程 `openocd/` | 已用 openocd 0.12 验证脚本能完整加载(只差探针);**没有 C0/U0 真板烧写证据** |
373
+ | **HAL 建工程覆盖 21 个单核族** | C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL 已按族实现:固件包按族找(`resolveFamilyFirmwareRoot`)、启动文件/设备宏/链接脚本来自内置资源 `assets/device/<族>/chips.json`、`.ioc` 用 `assets/ioc/family/<族>.ioc` 模板(逐族时钟树)、cmake 与 openocd/launch.json 里的 `STM32F1xx`/`stm32f1x` 按族替换。已实测 F4(407VGT6)create→generate→build 出 elf;寄存器路线覆盖 13 族,13 族都过了 create→generate→build 编译验收 | 双核 WB、MP1/MP2/N6、WB0/WL3 不在 HAL 建工程范围;内置资源里没有的族会明确拒绝(`stm32_assets verify` 定位缺件) |
374
+ | 深层能力按族分级 | 族画像覆盖 27 个族(`src/data/family.ts`):引脚名、SWD 调试信号、EXTI 向量分组、openocd target、断点预算都随族与内核走;HAL 建工程 21 个单核族,寄存器版 13 族;`.ioc` 外设预设全部查 db(`src/data/db-presets.ts`:串口 / TIM PWM / ADC,手写表只剩 db 表达不了的三类与离线兜底);时钟规划从 db 派生(`src/data/clock-db.ts`):pllmul 族 F1/F0/L0 与 pllmn 族 F4/F7/G4/L4 已做往返,PLL1 族 H5/U5/WBA/L4+ 已接入,共 18 族;仍只有 F1 的是 SVD 校验(内置资源只有 `device/f1/svd`) | 未覆盖的能力会**明确拒绝并说明原因**(族画像的 `capabilities` 为 false,或逐条报「这一条为什么不行」),不会悄悄套 F1 表 |
375
+ | 探针按 USB 实见自动选 | ST-Link → `interface/stlink-dap.cfg`(dapdirect)、DAPLink/CMSIS-DAP → `interface/cmsis-dap.cfg`、J-Link → `interface/jlink.cfg` + `transport select swd`;工程自带 `openocd.cfg` 时以它为准 | 插不同探针不用改配置;要固定就手写 `openocd.cfg` |
363
376
  | 新增外设要**手工补 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` |
364
- | 生成/建工程需要 **CubeMX + F1 固件包** | 固件包版本默认 `STM32Cube_FW_F1_V1.8.7` | 换版本传 `firmwarePackage` |
377
+ | 生成/建工程需要 **CubeMX + 该族固件包** | F1 默认 `STM32Cube_FW_F1_V1.8.7`;其它族取本机已装的最高版本(`STM32Cube_FW_<族>_V*`) | 换版本传 `firmwarePackage`;缺包装不上就先在 CubeMX 包管理器里装 |
365
378
  | 未在别人的机器上验证 | 本机:Windows 10 + MSYS2 UCRT64 + DAPLink + 蓝丸;其余组合靠反馈 | 遇到问题请附 `stm32_doctor` 的完整输出开 issue |
366
379
  | **RTT 只有通道 0**,帧是我们自己的约定 | `stm32_rtt` 只解析通道 0,头是 13 字节(4 B 长度 + 1 B 级别 + 8 B 时间戳 + UTF-8 正文);既不是 defmt,也不是 SEGGER 原生裸字节——原生客户端(RTT Viewer / J-Link RTT Client)读通道 0 会把这 13 字节当正文。RTT 还依赖目标 RAM:不调 `rtt_init()` 就没有控制块,环满时整条丢 | 级别当过滤(`level: 3` 只看 info 以上),结构化内容塞进 `text` 里自己放 JSON;通道数与环大小改 `rtt.h` 的 `RTT_UP_CHANNELS` / `RTT_BUF_SIZE`(默认 3×1 KB = 3 KB `.bss`,C8T6 只有 20 KB);要 defmt 解码或原生 RTT 输出是另一个功能 |
367
- | **寄存器符号名与位域解释要靠资源包的 `full` profile** | `GPIOC.ODR` / `GPIOC->ODR` 与外设 dump(只写 `GPIOC`)都从 `device/f1/svd/<line>.json` 解析,这份数据由 ST 的 SVD 派生(ST EULA,1.71 MiB),`core`(30 个文件约 237 KiB)里没有;覆盖线只有 100/101/102/103/105/107。没有 SVD 时纯地址照读,只是没有名字和位域;符号名会报错并提示怎么补 | `stm32_assets action="refresh" profile="full"`(128 个文件);不想装就写 `0x` 开头的地址 |
380
+ | **寄存器符号名与位域解释要靠内置 SVD(full 逻辑层)** | `GPIOC.ODR` / `GPIOC->ODR` 与外设 dump(只写 `GPIOC`)都从 `assets/device/f1/svd/<line>.json` 解析(ST SVD 派生,1.71 MiB),只覆盖 100/101/102/103/105/107。没有 SVD 时纯地址照读,只是没有名字和位域;符号名会报错并提示重装插件(full 也随包) | 写 `0x` 开头的地址;或 `stm32_assets verify` 确认安装完整性 |
368
381
 
369
382
  ## 排错
370
383
 
@@ -376,8 +389,8 @@ source [find target/stm32f1x.cfg]
376
389
  | 调试会话开着时读寄存器,`report.command` 是一条 `gdb-multiarch … target extended-remote 127.0.0.1:3333` | 这是「复用会话」的正常形态:`stm32_debug_session` 活着时,`stm32_regs_read` 借用会话里那个 openocd,notes 会写清「复用调试会话(gdb 端口 N,tcl 端口 M),没有另起 openocd」。B3 之后默认走 **Tcl RPC 直读**(一条 TCP 连接:halt → 读 pc → 连续 `mdw` → resume,毫秒级),所以 `report.command` 是 `gdb-multiarch …` 只说明 Tcl 快路径没成、回退到了会话里的 gdb,原因写在 notes 里;只有没有会话时才另起 openocd。旧版在这里会报 `CMSIS-DAP transfer count mismatch: expected N, got M` |
377
390
  | 编译"成功"但跑的是旧固件 | 复制或改名过带 `build/` 的工程:CMakeCache 里的目录对不上,ninja 仍退出 0。`stm32_build` 会判失败;按提示 clean 或删 `build/Debug` |
378
391
  | 工具直接回「缺 arm-none-eabi-gcc…,这次没有开始编译」 | 这是开工前门禁(`envCheck` 默认 `block`)拦下来的,不是 bug:它比跑到一半才发现省时间。回一句「装」,模型调 `stm32_env_install` 出计划;确认后装好并写配置文件,**下一条命令就能用,不必重启**。想先看全貌就 `/stm32-env`;只想先跑起来就传 `envCheck: "warn"`(照做但写警告)或 `"off"`(不查) |
379
- | 第一次建工程回「设备事实还没就绪……先跑 stm32_assets refresh,或检查网络」 | 插件不内置芯片表:型号 → 启动文件 / 设备宏 / Flash / RAM 的事实只从本地资源包缓存(`~/.dsh-stm32/assets/<版本>/`)读。联网跑一次 `stm32_assets`(`action: "refresh"`,默认 `profile: "core"`,30 个文件约 237 KiB),装好后离线可用;`DSH_STM32_ASSETS` 可换根目录 |
380
- | `stm32_doctor` 说找不到 gcc / openocd | 先看 doctor 的 notes / 报错里的「查过 …」列表与自动发现结果;装上后还找不到就设 `STM32_BIN_DIRS` 或给工具传 `binDirs`。**不知道装什么就先跑 `stm32_env_probe`**:每条缺失项都带 `impact`(缺了影响哪些功能)、`install`(推荐装法,第一条最省事)、`verify`(装完自检),顶层 `recommendations` 给出安装顺序,还会问要不要帮你装 |
392
+ | 第一次建工程回「设备事实还没就绪……」 | 插件随包内置芯片表(`assets/device/f1/chips.json`),正常安装不会出现;报这个说明插件安装不完整。跑 `stm32_assets verify` 看缺了哪些文件,重装插件即可(无需联网);`DSH_STM32_ASSETS` 只用于开发时覆盖资源根 |
393
+ | `stm32_doctor` 说找不到 gcc / openocd | 先看 doctor 的 notes / 报错里的「查过 …」列表与自动发现结果;装上后还找不到就设 `STM32_BIN_DIRS` 或给工具传 `binDirs`。**不知道装什么就先跑 `stm32_doctor`**:每条缺失项都带 `impact`(缺了影响哪些功能)、`install`(推荐装法,第一条最省事)、`verify`(装完自检),顶层 `recommendations` 给出安装顺序,还会问要不要帮你装 |
381
394
  | `stm32_generate` 很慢或像卡住 | 首次(冷启动、无缓存)3.5–4 分钟属正常,之后 .ioc 与产物没变会直接跳过(<1 s)。默认后台 job,用 `job_output` 看进度,或传 `foreground: true` 同步等。想确认是不是漏命中缓存,看返回里的 `skipped` 与 notes 给的 reason |
382
395
  | 生成没变化却每次都跑满 3 分钟 | 缓存键里含 CubeMX 的 size+mtime 与产物 hash:换过 CubeMX、改过生成区文件、或改过落位布局都会失效。看 notes 里的 reason,或删 `.dsh-stm32/generate-cache.json` 从干净状态重来 |
383
396
  | 生成变快了,但 CubeMX GUI 里看不到扩展包了 | `thirdpartyPacks: "auto"` 会在不需要扩展包时把 `thirdparties/pdsc` 停放成 `pdsc.dsh-parked`,生成结束自动还原。若正在 CubeMX GUI 里手工选包,传 `thirdpartyPacks: "keep"` |
@@ -388,25 +401,26 @@ source [find target/stm32f1x.cfg]
388
401
 
389
402
  ```powershell
390
403
  npm run build # tsc -> lib/(lib/ 入库,改完 src 必须重建后一起提交)
391
- npm test # 34 个离线套件、497 个用例;不需要板子、CubeMX、工具链
404
+ npm test # 43 个离线套件、736 个用例;不需要板子、CubeMX、工具链
392
405
  npm run test:pack # 把包打成 tarball、解开、用解包出来的 lib 真建一次寄存器工程
393
- npm run test:size # 包体护栏:tarball ≤1.2 MB、templates ≤60 KB、包内不许二进制/图表
406
+ npm run test:size # 包体护栏:tarball ≤1.2 MB、templates 里的运行时资产(.ioc/.xml/.ld/.json/.cfg)≤40 KB、包内不许二进制/图表
394
407
  ```
395
408
 
396
409
  CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test → test:pack → test:size`(windows-latest)。
397
410
 
398
- GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **495 pass + 2 skipped**,开发机上是 497 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
411
+ GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上会 skip 那 2 条,开发机上是 **736 pass / 0 fail** 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
399
412
 
400
413
  ### 发布形态三分法(先把东西放哪想清楚,再写包)
401
414
 
402
415
  | 放哪 | 内容 | 量级 |
403
416
  | --- | --- | --- |
404
- | 随包(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 |
417
+ | 随包(npm tarball) | `lib/**`(含 `lib/client.js`)、`client/client.js`、`templates/scaffold/**`、`assets/**`、`cordis.patch.yml`、两份 README、`LICENSE`、`docs/*.md` | 265 个文件 / 1750.3 KB,解包 14901.3 KB;`assets/**` 源文件 12.5 MB(headers 压缩率高) |
405
418
  | 进 git 不进包 | `src/**`、`test/**`、`scripts/**`、`docs/diagrams/**`(两张可交互 HTML) | diagrams 2 MB 原始 / 891 KB gz;`package.json` 的 `files` 把 `docs` 收窄成 `docs/*.md` |
406
- | 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头(寄存器版首次用时下到缓存,逐文件钉 sha256);HAL 固件包;**设备事实资源包**(chips.json / memory.json / .ioc 模板 / .ld / SVD,core 30 个文件约 237 KiB、full 128 个文件——SVD 在 full 里;插件不再内置芯片表,首次使用要联网拉一次 `stm32_assets refresh`,之后离线可用) | 缓存可用 `stm32_cache list/verify/purge` 与 `stm32_assets list/verify/prune` 管 |
419
+ | 内置(随包) | 设备事实层(21 个族的 `device/<族>/chips.json`)、`.ioc` 模板、`.ld`、SVD、startup、headers——core 75 个文件、full 105 个文件,随 npm 包分发,离线可用 | `stm32_assets list/verify` 查看与校验;`prune` 只清历史外部版本 |
420
+ | 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头(寄存器版首次用时下到缓存,逐文件钉 sha256);HAL 固件包 | 缓存可用 `stm32_cache list/verify/purge` 管 |
407
421
  | 现造 | `.ioc` 内容(`renderIoc`)、`.ld` 的 MEMORY(`renderLinkerScript`)、cmake 源清单 | 按型号渲染,模板里不落盘 |
408
422
 
409
- 护栏是 `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`。
423
+ 护栏是 `scripts/pack-size.mjs`(`npm run test:size`):tarball ≤ 4 MB(4 000 000 B,`assets/**` 随包后实测 1.76 MB)、`templates/**` 里的运行时资产(`.ioc/.xml/.ld/.json/.cfg/.svd/.csv`)≤ 40 KB 且单文件 ≤ 24 KB(`.md` 文档与 C/CMake 源码不算资产)、包内禁止 `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll`,且必须含 `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md` / `assets/manifest.json` / `assets/device/f1/chips.json`。
410
424
 
411
425
  真机 e2e 会写板子,需要你指一个能构建的工程:
412
426
 
@@ -422,7 +436,7 @@ node test\e2e-flash.mjs
422
436
  ```text
423
437
  src/
424
438
  index.ts 插件入口(name / inject / apply)
425
- tools/ 21 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
439
+ tools/ 23 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
426
440
  engine/ 纯逻辑与工作流(generate / build / flash / debug / ioc / scaffold …)
427
441
  commands/register.ts 7 条斜杠命令
428
442
  skill/stm32-workflow.ts 随插件下发的 SKILL