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
@@ -1,7 +1,7 @@
1
1
  # dsh-stm32 源码精读指南
2
2
 
3
3
  > 面向:第一次读这个仓库、并且要改它的人。
4
- > 规模:75 个 TypeScript 文件约 23.2k 行,外加一个手写的浏览器 bundle(client/client.js,682 行)。**芯片事实不在仓库里**:`src/data/device-facts.ts` 只读本地资源包缓存(`~/.dsh-stm32/assets/<版本>/device/f1/chips.json`),插件不内置任何芯片表(2026-10-31 删掉了 chip-table.json / f1-ram.generated.ts / 手写容量档表 / 内置引脚表)。
4
+ > 规模:75 个 TypeScript 文件约 23.2k 行,外加一个手写的浏览器 bundle(client/client.js,682 行)。**芯片事实随包内置**:`src/data/device-facts.ts` 读插件包内 `assets/device/f1/chips.json`(`DSH_STM32_ASSETS` 可覆盖;2026-11 从独立资源仓并入插件),2026-10-31 已删掉手写 chip-table.json / f1-ram.generated.ts / 手写容量档表 / 内置引脚表。
5
5
  > 读完这份指南你应该能回答:一次工具调用从宿主进来到 openocd 退出中间经过了谁;哪几条不变量破了一定出事;要改某个功能得动哪几个文件;哪些行为有测试兜着、哪些只能上板子验。
6
6
  >
7
7
  > 配套文档:docs/development-notes.md(按时间记的决策与被坑记录)、docs/logic-audit.md(历史审计条目)、README.md(用户视角)。
@@ -26,9 +26,9 @@
26
26
  | 层 | 目录 | 干什么 | 绝对不能干的事 |
27
27
  | --- | --- | --- | --- |
28
28
  | L4 装配 | src/index.ts、src/commands、src/skill | 把服务接上、把工具/命令/skill 注册进宿主 | 写业务逻辑 |
29
- | L3 契约层 | src/tools(21 个文件:21 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
29
+ | L3 契约层 | src/tools(23 个文件:22 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
30
  | L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
31
- | L1 事实表 | src/data(10 个数据模块) | 设备事实(`device-facts.ts` 从资源包缓存读 chips.json;插件不内置芯片表)、由本机 CubeMX db 派生的引脚表、镜像 URL、固件族、F1 时钟树、安装指引、搜索路径、配置读写、SVD 寄存器表(`svd.ts`,来自资源包 `full` 档) | 起进程、写工程文件 |
31
+ | L1 事实表 | src/data(10 个数据模块) | 设备事实(`device-facts.ts` 读包内 `assets/device/f1/chips.json`)、由本机 CubeMX db 派生的引脚表、镜像 URL、固件族、F1 时钟树、安装指引、搜索路径、配置读写、SVD 寄存器表(`svd.ts`,来自内置 `assets/device/f1/svd/`,full 逻辑层) | 起进程、写工程文件 |
32
32
 
33
33
  跨层的只有两样东西:**SubprocessService**(进程能力,从 ctx 一路当参数传到 engine)和 **DshContext**(宿主服务袋)。
34
34
 
@@ -44,7 +44,7 @@
44
44
  ```mermaid
45
45
  flowchart TD
46
46
  HOST["DSH 宿主 ctx<br/>tools / subprocess / jobs / webServer / commands / skills"] --> IDX["src/index.ts<br/>apply(ctx) 装配"]
47
- IDX --> TOOLS["src/tools/*<br/>21 个工具"]
47
+ IDX --> TOOLS["src/tools/*<br/>22 个工具"]
48
48
  IDX --> CMDS["src/commands/register.ts<br/>7 条斜杠命令"]
49
49
  IDX --> SKILL["src/skill/stm32-workflow.ts<br/>红线 skill"]
50
50
  IDX --> WEB["src/engine/web-routes.ts<br/>6 条 HTTP 路由"]
@@ -53,7 +53,7 @@ flowchart TD
53
53
  CMDS --> ENGINE
54
54
  WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
55
55
  API --> ENGINE
56
- ENGINE --> DATA["src/data/*<br/>10 个数据模块(芯片事实读资源包缓存;SVD 在 full 档)"]
56
+ ENGINE --> DATA["src/data/*<br/>10 个数据模块(芯片事实读包内 assets/;SVD 在 full 层)"]
57
57
  ENGINE --> RUN["src/engine/subprocess-runner.ts"]
58
58
  RUN --> OS["宿主 subprocess 服务"]
59
59
  OS --> BIN["gcc / cmake / ninja / openocd / gdb<br/>java(CubeMX) / reg.exe / pacman / objcopy"]
@@ -67,13 +67,13 @@ flowchart TD
67
67
  | 目录 | 文件数 | 行数 | 说明 |
68
68
  | --- | --- | --- | --- |
69
69
  | src/ | 4 | 803 | index.ts 127、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
70
- | src/tools/ | 21 | 6623 | 21 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 regs.ts 735 行(D 阶段从 272 涨到 735),其次是 route-plan.ts 576 行 |
71
- | src/engine/ | 46 | 18981 | 见第 5 章(第 5 章表格化了 45 个模块,另有 assets.ts 1162 行没单列);最大的是 msys2-install.ts 2313 行,其次是 assets.ts 1162 行、clock-plan.ts 801 行 |
72
- | src/data/ | 10 | 3599 | 10 个 .ts 数据模块(device-facts.ts 从资源包缓存读设备事实、svd.ts 读 `full` 档的寄存器表;仓库里没有任何芯片表),见第 6 章 |
70
+ | src/tools/ | 23 | 7158 | 22 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 regs.ts 735 行(D 阶段从 272 涨到 735),其次是 route-plan.ts 576 行、rtt.ts 408 行、watch.ts 305 行 |
71
+ | src/engine/ | 51 | 21712 | 见第 5 章(第 5 章表格化了 45 个模块,另有 assets.ts 1162 行没单列);最大的是 msys2-install.ts 2313 行,其次是 assets.ts 1162 行、clock-plan.ts 801 行 |
72
+ | src/data/ | 10 | 3599 | 10 个 .ts 数据模块(device-facts.ts 读包内 assets/、svd.ts 读 full 层的寄存器表),见第 6 章 |
73
73
  | templates/ | 20 | — | 工程脚手架与寄存器版模板(CMake、链接脚本、launch/settings、openocd.cfg、demo.ioc;C 阶段加了寄存器版的 `Core/Src/rtt.c` + `Core/Inc/rtt.h` 与 HAL 脚手架 `scaffold/RTT.md`) |
74
74
  | client/ | 1 | 682 | 设置面板的前端 bundle(手写 JS,不经打包器) |
75
- | test/ | 36 套件(run-units 登记)+ 15 个 e2e 脚本 + 4 个辅助脚本 | — | 见第 9 章 |
76
- | scripts/ | 4 | 405 | copy-client.mjs(24)、gen-xcube-catalog.mjs(151)、pack-size.mjs(80)、pack-smoke.mjs(150)。芯片表的生成脚本 2026-10-31 已挪到资源仓库(`scripts/build-assets.mjs`) |
75
+ | test/ | 41 套件(run-units 登记)+ 15 个 e2e 脚本 + 4 个辅助脚本 | — | 见第 9 章 |
76
+ | scripts/ | 8 | 2115 | copy-client.mjs(24)、copy-data.mjs(20)、gen-xcube-catalog.mjs(151)、pack-size.mjs(105)、pack-smoke.mjs(157)、assets/build-assets.mjs(1042)、assets/family-assets.mjs(238)、assets/svd-f1.mjs(378)。芯片表与 SVD 的生成脚本 2026-11 起随插件放在 `scripts/assets/` |
77
77
 
78
78
  > 全书行数统一口径:按文件里的换行符数(`content.split("\n").length`,等价于编辑器的「块末行号」),2026-10-31(D 阶段末)重数过一遍——第 1、4.1、4.2、5、6 章都按这个口径,和本指南更早版本的数字会有几行到几十行的差异。
79
79
 
@@ -100,7 +100,7 @@ flowchart TD
100
100
  三件事,只有三件:
101
101
 
102
102
  1. **声明身份与依赖**:`export const name = "dsh-stm32"`、`export const inject = ["tools", "subprocess", "jobs"]`。这三个是硬依赖,缺了插件不加载。
103
- 2. **apply(ctx) 里按「先探测、再操作」的顺序注册 21 个工具**:env_probe → env_install → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → build → flash → debug_run → debug_session → regs_read → route_plan → rtt → assets → cache → doctor → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
103
+ 2. **apply(ctx) 里按「先探测、再操作」的顺序注册 22 个工具**:env_probe → env_install → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → build → flash → debug_run → debug_session → watch → regs_read → route_plan → rtt → assets → cache → doctor → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
104
104
  3. **注册可选层并挂三个事件**:commands / skills 走 `ctx.inject([...], scope => ...)`,宿主没组合这些服务时静默跳过,工具照常工作;webServer 路由在`registerWebRoutes` 里自己判断。
105
105
 
106
106
  三个事件是本插件唯一的「状态清理入口」,也是很容易读漏的地方:
@@ -154,7 +154,7 @@ ctx.on("dispose", () => { void debugSessions.stop("插件卸载"); });
154
154
 
155
155
  7 条命令里有 6 条最终调用 engine 的同一个函数(build → runBuild,flash → runFlash …),所以它们和工具的唯一差别是:输入来自文本而不是 JSON、输出是一段中文。
156
156
 
157
- ## 4. tools 层:21 个工具 + 1 个基础设施
157
+ ## 4. tools 层:22 个工具 + 1 个基础设施
158
158
 
159
159
  ### 4.1 一个工具文件的固定骨架
160
160
 
@@ -190,11 +190,11 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
190
190
  2. **门禁在工具层,不在 engine。** engine 假设工具链就位;`blockedReport` / `emptyReport` 是门禁拦截与早退时造「同形报告」的工厂,保证失败也是合法输出。
191
191
  3. **`resolveProjectDir` + `validateToolArgs`(tools/project-dir.ts,120 行)是所有工具的共同入口**:前者把 `projectDir` 参数 / 会话工作目录落成绝对路径,后者按 `RequiredArgSpec` 校验必填参数类型,报错文案统一。
192
192
 
193
- ### 4.2 21 个工具一览
193
+ ### 4.2 22 个工具一览
194
194
 
195
195
  | 工具 | 文件(行) | engine 入口 | 门禁能力 |
196
196
  | --- | --- | --- | --- |
197
- | `stm32_env_probe` | env-probe.ts(284) | probe.buildTargets / probeAll + search-roots.resolveSearchConfig | 无 |
197
+ | `stm32_doctor` | env-probe.ts(284) | probe.buildTargets / probeAll + search-roots.resolveSearchConfig | 无 |
198
198
  | `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
199
199
  | `stm32_firmware_install` | firmware-install.ts(288) | firmware-install.planOrInstallFirmware | 无 |
200
200
  | `stm32_project_create` | project-create.ts(387) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
@@ -208,6 +208,7 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
208
208
  | `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
209
209
  | `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
210
210
  | `stm32_debug_session` / `_eval` / `_stop` | debug-session.ts(305,三工具同文件) | debug-session.DebugSessionManager(单例 debugSessions)+ releaseProbeFor | debug(仅 session 启动时) |
211
+ | `stm32_watch` | watch.ts(305) | engine/watch 的登记表(纯函数)+ debug-session.sampleWatches / addWatchpoints / removeWatchpoints(复用常驻 MI) | debug(add kind=write/read/access 与 sample 需要会话) |
211
212
  | `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
212
213
  | `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
213
214
  | `stm32_route_plan` | route-plan.ts(576) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
@@ -219,7 +220,7 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
219
220
 
220
221
  ## 5. engine 层:45 个模块,十个域
221
222
 
222
- 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。表里列 45 个;`src/engine/` 目录里实际有 46 个 `.ts`——`assets.ts`(资源包装配的小件)还没单独成行,读资源包那条链路时直接从 §5.7 与 `src/data/assets` 一起看。
223
+ 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。表里列 45 个;`src/engine/` 目录里实际有 46 个 `.ts`——`assets.ts`(内置资源装配与完整性校验,flat 布局)还没单独成行,读内置资源那条链路时直接从 §5.7 与 `src/data/device-facts.ts` 一起看。
223
224
 
224
225
  ### 5.1 进程与路径(3 个,413 行)
225
226
 
@@ -251,7 +252,8 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
251
252
  | --- | --- |
252
253
  | flash.ts(388) | `runFlash`:SWD 守卫(`checkNoDebugGuard`:唯一 .ioc 看 PA13/PA14,没有 .ioc 就看 openocd.cfg 的 transport,找不到依据时给 notes 而不是静默放行)→ `resolveElf` → 找 openocd 配置(`findProjectConfig` 认 openocd.cfg/openocd/…;否则 `defaultConfigs` 用 interface/cmsis-dap.cfg + target/stm32f1x.cfg)→ 拼 `program <elf> verify reset exit`(`buildProgramCommand`)→ 解析日志(`parseFlashLog` 只回答 programmed / verified / errors / noise,**不再归类**)→ 失败时只调一次 `classifyProbeFailure`(stage "flash"),产物是 `probeError: ProbeError | null`(成功路径保持 null,由工具层摘掉)→ USB 形态提示(`usbNoteFor` / `probeMissingLines`)。`toOpenOcdPath` 只把反斜杠换成正斜杠。B2 之后分类规则与 hint 常量只在 probe-error.ts 一份,flash 与 debug 不会再各写一套漂移。 |
253
254
  | debug.ts(435) | 一次性调试快照 `runDebugRun`:挑端口(`pickPort`,默认 3333,占用则顺延)→ 起 openocd(`waitForListening` 等 "Listening on port")→ 起 gdb 跑一串 -ex(file / break / info registers / bt / info locals / monitor reset run / detach)→ `parseGdbOutput` 提取断点命中、寄存器、调用栈、locals → ok 判据看 exitCode + probe.errors + hitBreakpoint(审计 A26)。失败时:`classifyProbeFailure` 归类(与 flash 同一个函数、同一组 kind,stage "debug")→ `probeMissingLines` 命中就跑 `usbDiagnosis`、日志用 `keyLogTail(lines, 40)`(优先留 adapter/Error 行,而不是「最后 15 行」)、`firstProblemLine` 把首条根因塞进 errors、kind 不是 unknown 时把 hint 写进 notes。B4 的断点预算(`resolveBreakpointBudget` / `collectBreakpointRequests` / `planBreakpoints`)也在同一条 execute 里先算完,报告带 `breakpoints` / `watchpoints` 两个 used/limit/remaining 三元组。 |
254
- | debug-session.ts(656) | 长会话租约。`DebugSessionManager` 管「一个常驻 openocd + 多次短命 gdb -batch eval」,空闲 90 s、总时长 10 min、turn/end 立刻释放;`releaseProbeFor(reason)` 是别的工具(flash/regs/debug_run)动探针前必须调的一步(审计 B16:先释放再门禁)。三个纯函数是好单测点:`normalizeHexAddress`、`parseGdbPrintedHex`、`parseMarkedWords`(按 `echo ===DSH:<tag>===` 分段对齐,修「中间某个地址读失败导致后面值整体前移」)。 |
255
+ | debug-session.ts(1101) | 长会话租约。`DebugSessionManager` 管「一个常驻 openocd + 多次短命 gdb -batch eval」,空闲 90 s、总时长 10 min、turn/end 立刻释放;`releaseProbeFor(reason)` 是别的工具(flash/regs/debug_run)动探针前必须调的一步(审计 B16:先释放再门禁)。三个纯函数是好单测点:`normalizeHexAddress`、`parseGdbPrintedHex`、`parseMarkedWords`(按 `echo ===DSH:<tag>===` 分段对齐,修「中间某个地址读失败导致后面值整体前移」)。 |
256
+ | watch.ts(266) | 变量监视与硬件观察点(P3 续)。**纯状态层,不碰进程**:`WatchKind`(value/write/read/access)、`watchState` 单例(`entries` + `nextId`)、`registerWatch` / `removeWatchByIds` / `removeAllWatches` / `resetWatchState` / `sampledWatches` / `hardwareWatchpoints` / `markWatchpointsStale`、`recordWatchSample` + `formatWatchDelta`;纯函数还有 `normalizeWatchExpression`(拒空/超 200 字符/含换行或 NUL)、`numericWatchValue`、`formatWatchEntry` / `formatWatchLines`、`parseWatchMarkers`(旧 gdb 兜底路径按 `===DSH:W<id>===` 分段)、`parseWatchpointNumber`、`isHardwareWatchpoint`。真正下达 gdb 的三个动作在 debug-session.ts(`sampleWatches` / `addWatchpoints` / `removeWatchpoints`):值监视要「在跑就先 `-exec-interrupt` → 逐项 `evaluate` → 原本在跑就 `monitor resume`」;观察点要过 `resolveBreakpointBudget` 的 data 预算(F1 只有 4 个)并识别「装成了软件观察点」并告警。生命周期:`stop()` 里 `resetWatchState()`(观察点住在 gdb 进程里,会话一关全没了);`ensureMi` 重建 MI 时 `markWatchpointsStale(...)`。 |
255
257
  | regs.ts(250) | 读内存映射寄存器。`normalizeAddress`(0x 可省)、`buildRegsScript`(生成 openocd 脚本:init → halt → mdw)、`parseRegsLog` → `runRegsRead`。本身只负责脚本生成与日志解析(`buildRegsScript` / `parseRegsLog`,不复位芯片);B3 起工具层换成「复用常驻会话 + Tcl RPC 直读」(`ensureSession` + `readWordsViaSession`,RPC 失败回退到会话里的 gdb),没有会话时才起一个并保留 90 s。D 阶段的符号名解析、位域解释与外设 dump 全在工具层(`src/tools/regs.ts`,735 行)与 data 层(`src/data/svd.ts`):本模块仍然只认地址,不知道 `GPIOC.ODR` 是什么。 |
256
258
  | probe-error.ts(280) | 探针故障的**唯一分类入口**(B2)。`ProbeErrorKind` 8 类(no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / timeout / unknown)、运行期枚举 `PROBE_ERROR_KINDS`、`ProbeError{kind,cause,hint,evidence,retryable}`;`classifyProbeFailure({lines,exitCode,stage,timedOut,spawnError})` 的判定顺序是 **MATCHERS 首个命中 → timedOut(timeout) → spawnError → unknown**,所以 MATCHERS 的顺序是敏感的。hint 常量(`HINT_PROBE` / `HINT_BUSY` / `HINT_DP` / `HINT_FLASH_PROTECTED` / `HINT_NO_POWER` / `HINT_TARGET_MISMATCH` / `HINT_TIMEOUT` / `HINT_UNKNOWN`)只此一份;`firstProblemLine` / `probeMissingLines` / `usbNoteFor` 从 flash.ts 迁过来;`formatProbeError` 出「错误:<kind> — <cause>;建议:<hint>」;`PROBE_ERROR_SCHEMA`(additionalProperties:false,五个字段全 required)。不做兼容别名:`errorCode` 字段已删除,flash / debug / session 三条路径共用同一份规则。 |
257
259
  | probe-session.ts(395) | 会话复用的快路径(B3)。`sessionInfo` / `touch` / `release(reason)` / `ensureSession(projectDir, opts)` / `withSession` / `readWordsViaSession({addresses})`,以及纯函数 `normalizeWordAddress` / `parseMdwReply` / `parsePcReply` / `tclRoundTrip`。会话的唯一真相仍是 debug-session.ts 的 `debugSessions` 单例——这里不自己存句柄、也不自己算租约;并发靠模块级 starting Promise 去重(同时两次调用只起一个进程);端口被占直接报 `probe-busy`,不让 openocd 顺延端口去抢探针。读值走 openocd 的 Tcl RPC、一条 TCP 连接(halt → `reg pc` → `mdw`×N → resume,用 0x1a 分帧),tcl 端口没拿到或 RPC 失败就回退到会话里的 gdb 并写 notes。 |
@@ -318,20 +320,20 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
318
320
  | --- | --- |
319
321
  | route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
320
322
 
321
- ## 6. data 层:10 个数据模块(3599 行;芯片事实来自资源包缓存,仓库里没有芯片表)
323
+ ## 6. data 层:10 个数据模块(3599 行;芯片事实来自包内 assets/)
322
324
 
323
325
  | 模块 | 行数 | 内容 |
324
326
  | --- | --- | --- |
325
327
  | chips.ts | 177 | **不再有内置引脚表**(`CHIPS` / `KNOWN_CHIPS` / `findChip` 2026-10-31 删除)。`isKnownPin(pin)` 只查**引脚名是否合法**(`PA0..PG15`、`VP_*` 虚拟脚放行;顺序不影响——`PA0-WKUP` / `PC13-TAMPER-RTC` 先归一化);这不是「这个封装有没有这根脚」,那条事实只能来自本机 CubeMX db:`parseMcuDbXmlPins`(`<Pin Name= Position=>`,`Position<=0` 的虚拟脚丢弃,电源脚不算)、`findMcuDbDir`(`<CubeMX>/db/mcu`)、`readMcuDbPins`、`deriveChipPinTable({cpn, mcuName, dbMcuDir})` → `kind: db / unknown`(db 命中注明来源 XML 与引脚数;没有 db 就明说「引脚存在性不校验」,绝不拿内置表冒充)。 |
326
328
  | cmsis-sources.ts | 416 | 寄存器路线的下载源与型号映射:四个镜像(jsdelivr fastly/cdn、raw.githubusercontent、ghproxy)、`CMSIS_FAMILIES`、`startupChoiceFor(mcu)`(委托 resolveF1Chip,兼容 `F1:B` / `F1:8` / `F103:xb` / `STM32F103C8T6` 四种写法;只给容量字母的老写法现在从设备事实里挑一颗同档芯片当代表,优先 F103——原来的「字母 → 档位」常量表已删,没缓存就返回 null 让上层提示 refresh)、`cmsisTemplatePlan(choice)`(10 个文件的目标路径)、四个 sha256 表(DEVICE_HEADER / SYSTEM_C / **STARTUP 14 条** / CORE_HEADER)、缓存条目 id 与解析(`chipOf`、`cmsisGroupKey`、`cmsisEntryId` → `cmsis:F1:103xb`、`chipEntryId`、`parseCmsisEntryRef`、`cmsisEntryAliases`)。**改这里等于改「离线可复现」的边界**:F1 的 14 个容量档 sha256 全部是 2026-10-30 真实下载实测的。 |
327
- | stm32f1.ts | 171 | 两条路线共用的**型号解析器**,本身不再存任何事实:`resolveF1Chip(input)` 先做格式/封装/温度档校验,再查 `device-facts.ts`(完整型号按 CPN 精确匹配、无温度后缀按前缀归一化、`F103:xb` 按 line+档取代表芯片),返回 `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`(签名与结构 0.2 不变);`f1GroupsFor(code)` 从事实聚合该 line 的容量档。错误分四类且都带「先跑 `stm32_assets refresh`」提示:没缓存 / 型号不在资源包 / line 不存在 / 该 line 没有这一容量档。 |
329
+ | stm32f1.ts | 171 | 两条路线共用的**型号解析器**,本身不再存任何事实:`resolveF1Chip(input)` 先做格式/封装/温度档校验,再查 `device-facts.ts`(完整型号按 CPN 精确匹配、无温度后缀按前缀归一化、`F103:xb` 按 line+档取代表芯片),返回 `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`(签名与结构 0.2 不变);`f1GroupsFor(code)` 从事实聚合该 line 的容量档。错误分四类且都带「先跑 `stm32_assets verify`」提示:内置资源缺失 / 型号不在内置资源 / line 不存在 / 该 line 没有这一容量档。 |
328
330
  | clock-f1.ts | 215 | F1 时钟树的事实表:PLL 源(HSE 8 MHz / HSI÷2 4 MHz / HSI 8 MHz,后者 `selectable=false`)、倍频 ×2..×16、上限(SYSCLK 72 / APB1 36 / APB2 72 / ADC 14 / USB 48 且必须 PLLCLK=72÷1.5)、APB1/APB2/ADC 分频表、14 条外设→总线、UART 波特率档、20 个 RCC IPParameters 名单。 |
329
331
  | firmware-packages.ts | 463 | 固件包事实表:`FIRMWARE_FAMILIES`(目前只有 F1)、`firmwareFamilyOf`、`firmwareVersionTags`、`packageXmlText`、`firmwarePlanFor`、`verifyFirmwarePackage`、`DSH_FIRMWARE_DIR_NAME = "dsh-firmware"`、`dshFirmwareDir`、`firmwareNeedFromIoc`(从 .ioc 的包名推族与版本)、`looksLikeFirmwarePackage`、`locateFirmwarePackage(root, packageName, extraDirs)` → `FirmwareLocation`(source:repository / dsh-firmware / cache / custom)、`firmwareSourceLabel`、`FirmwareExtraDir`。 |
330
332
  | install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
331
333
  | search-roots.ts | 421 | 见 5.2。 |
332
334
  | toolchain-config.ts | 370 | 见 5.2。 |
333
- | device-facts.ts | 278 | 设备事实读取层(新增):从 `~/.dsh-stm32/assets/<版本>/device/f1/chips.json` 读(`DSH_STM32_ASSETS` 可换根目录,版本取本地已装的最新一版),按 path+size+mtime 缓存一次。`loadDeviceFacts(env?)` → `{ok,path,version,chips,byCpn,byLineGroup,lines,groupsByLine,error}`、`findChipFact(cpn,env?)`(缺失返回 null)、`requireChipFact(cpn,env?)`(抛 `DeviceFactError`,`code: facts-missing / chip-unknown`)、`deviceFactsSource(env?)`(缓存路径或 `"none"`)。**不抛异常、不退回内置表**:没有缓存就把「先跑 stm32_assets refresh,或检查网络」原样交给上层。 |
334
- | svd.ts | 837 | SVD 寄存器表(新增,D 阶段):读 `device/f1/svd/<line>.json`(`profile=full`)。常量 `SVD_REL_DIR`、`SVD_KNOWN_LINES`(100/101/102/103/105/107)、`SVD_FULL_PROFILE_HINT`(一句能照敲的 `stm32_assets refresh --profile full`)。`loadSvd`(返回 `{device,failure}`,不抛)/ `loadSvdForLine` / `requireSvd` / `svdLineForChip(cpn, env)`(走 device-facts 的 line)、`resolveRegisterRef(ref, line, env)`(`GPIOC.ODR` / `GPIOC->ODR` / `0x4001100C` 三种写法等价,返回 base+offset 之后的地址、size、fields)、`describeAddress`(地址 → 寄存器 + 寄存器内偏移,`exact:false` 表示落在寄存器中间)、`decodeRegisterValue`(置位字段 / 清位 / 未覆盖位)、`formatDecodedFields` / `formatAddress` / `formatOffset`;出错抛 `SvdError`(9 类 code)。兼容「装好的 `<root>/<version>/`」与「直接指向资源仓库本体的 flat」两种布局,缓存键 path+size+mtimeMs,`svdCacheStats` / `resetSvdCache` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
335
+ | device-facts.ts | 278 | 设备事实读取层(新增):从插件包内 `assets/device/f1/chips.json` 读(`lib/engine/assets.js` 从包根解析;`DSH_STM32_ASSETS` 可换根目录,外部旧版本仍兼容),按 path+size+mtime 缓存一次。`loadDeviceFacts(env?)` → `{ok,path,version,chips,byCpn,byLineGroup,lines,groupsByLine,error}`、`findChipFact(cpn,env?)`(缺失返回 null)、`requireChipFact(cpn,env?)`(抛 `DeviceFactError`,`code: facts-missing / chip-unknown`)、`deviceFactsSource(env?)`(缓存路径或 `"none"`)。**不抛异常、不退回内置表**:找不到内置文件就把「安装不完整:stm32_assets verify 定位,重装插件」原样交给上层。 |
336
+ | svd.ts | 837 | SVD 寄存器表(新增,D 阶段):读插件包内 `assets/device/f1/svd/<line>.json`(`profile=full`)。常量 `SVD_REL_DIR`、`SVD_KNOWN_LINES`(100/101/102/103/105/107)、`SVD_FULL_PROFILE_HINT`(一句能照做的「SVD 只在 profile=full:重装插件」提示)。`loadSvd`(返回 `{device,failure}`,不抛)/ `loadSvdForLine` / `requireSvd` / `svdLineForChip(cpn, env)`(走 device-facts 的 line)、`resolveRegisterRef(ref, line, env)`(`GPIOC.ODR` / `GPIOC->ODR` / `0x4001100C` 三种写法等价,返回 base+offset 之后的地址、size、fields)、`describeAddress`(地址 → 寄存器 + 寄存器内偏移,`exact:false` 表示落在寄存器中间)、`decodeRegisterValue`(置位字段 / 清位 / 未覆盖位)、`formatDecodedFields` / `formatAddress` / `formatOffset`;出错抛 `SvdError`(9 类 code)。兼容「包内 flat `assets/`」与旧的外部 `<root>/<version>/` 两种布局,缓存键 path+size+mtimeMs,`svdCacheStats` / `resetSvdCache` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
335
337
 
336
338
  ## 7. 关键流程
337
339
 
@@ -467,7 +469,7 @@ stateDiagram-v2
467
469
  空闲 --> 启动中: stm32_debug_session(start)
468
470
  启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
469
471
  启动中 --> 空闲: 端口占用 / 探针失败、带 probeError(kind / cause / hint)
470
- 活跃 --> 活跃: stm32_debug_eval、每次新起 gdb -batch:连上 → halt → 命令 → resume → detach
472
+ 活跃 --> 活跃: stm32_debug_eval、优先常驻 MI(连不上才每次新起 gdb -batch:连上 → halt → 命令 → resume → detach)
471
473
  活跃 --> 空闲: stm32_debug_stop
472
474
  活跃 --> 空闲: 空闲 90 s
473
475
  活跃 --> 空闲: 总时长 10 min
@@ -684,15 +686,15 @@ flowchart LR
684
686
 
685
687
  | 层 | 位置 | 说明 |
686
688
  | --- | --- | --- |
687
- | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 36 个套件 562 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
689
+ | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 41 个套件 654 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
688
690
  | e2e 脚本 | test/e2e-*.mjs(15 个) | 开发期手动跑的端到端(真 CubeMX / 真 openocd / 真工具链),不进 npm test |
689
- | 发布形态 | scripts/pack-smoke.mjs(npm run test:pack)+ scripts/pack-size.mjs(npm run test:size) | npm pack → 解包 → 断言 16 个必须文件 → 用解包出来的 lib 真建一个寄存器工程;pack-size 再守包体(tarball ≤1.2 MB、templates/** ≤60 KB、包内禁二进制、必需文件齐全)。CI 上两连跑 |
691
+ | 发布形态 | scripts/pack-smoke.mjs(npm run test:pack)+ scripts/pack-size.mjs(npm run test:size) | npm pack → 解包 → 断言 16 个必须文件 → 用解包出来的 lib 真建一个寄存器工程;pack-size 再守包体(tarball ≤1.2 MB、templates/** 里的运行时资产 ≤40 KB 且单文件 ≤24 KB、包内禁二进制、必需文件齐全)。CI 上两连跑 |
690
692
 
691
- ### 9.2 36 个套件一览(test/run-units.mjs 的 suites 数组顺序)
693
+ ### 9.2 41 个套件一览(test/run-units.mjs 的 suites 数组顺序)
692
694
 
693
- build-units、cache-units、cache-gc-units、assets-units、probe-error-units(23 例)、probe-session-units(16 例)、breakpoints-units(17 例)、stm32f1-units、hal-route-units、clock-units、doctor-chip-units、cmake-sources-units、commands-units、doctor-regs-units、engine-units、export-units、firmware-units、flash-units、generate-cache-units、ioc-plan-units、install-units、ioc-units、route-plan-units、scaffold-patch-units、search-roots-units、session-units、text-encoding-units、thirdparty-units、tool-contract-units、toolchain-units、vscode-units、web-api-units、xcube-units、rtt-units、svd-units(39 例)、schema-guard。
695
+ build-units、cache-units、cache-gc-units、assets-units、probe-error-units(23 例)、probe-session-units(16 例)、breakpoints-units(17 例)、stm32f1-units、hal-route-units、clock-units、doctor-chip-units、cmake-sources-units、commands-units、doctor-regs-units、engine-units、export-units、firmware-units、flash-units、generate-cache-units、ioc-plan-units、install-units、ioc-units、route-plan-units、scaffold-patch-units、search-roots-units、session-units、text-encoding-units、thirdparty-units、tool-contract-units、toolchain-units、vscode-units、watch-units(16 例)、web-api-units、xcube-units、rtt-units、svd-units(39 例)、schema-guard。
694
696
 
695
- 开发机上 562 例全跑;CI 上仍是 **2 skipped**(两条用例依赖本机路径,即 560 pass + 2 skipped;本轮没在 CI 上重跑)。D 阶段加了 `svd-units`(39 例:26 例符号解析与位域解码 + 13 例工具层端到端,含假 subprocess 与假 Tcl 服务端),工具数不变(仍 21),改的是 `stm32_regs_read` 的 `addresses` 语义与报告字段。B 阶段一次加了三个套件:`probe-error-units`(23 例,8 类 kind 与判定顺序)、`probe-session-units`(16 例,会话复用与 Tcl 分帧)、`breakpoints-units`(17 例,6/4 预算与超限文案)。C 阶段(RTT)加了 `rtt-units`(26 例:20 例帧 / 命令编码 + 6 条模板静态断言),工具数同时从 20 增至 21、engine 模块从 44 增至 45。
697
+ 开发机上 654 例全跑(`node test/run-units.mjs` → TOTAL pass=654 fail=0,41 个套件);CI 上仍是 **2 skipped**(两条用例依赖本机路径,本轮没在 CI 上重跑)。D 阶段加了 `svd-units`(39 例:26 例符号解析与位域解码 + 13 例工具层端到端,含假 subprocess 与假 Tcl 服务端),工具数不变(仍 21),改的是 `stm32_regs_read` 的 `addresses` 语义与报告字段。B 阶段一次加了三个套件:`probe-error-units`(23 例,8 类 kind 与判定顺序)、`probe-session-units`(16 例,会话复用与 Tcl 分帧)、`breakpoints-units`(17 例,6/4 预算与超限文案)。C 阶段(RTT)加了 `rtt-units`(26 例:20 例帧 / 命令编码 + 6 条模板静态断言),工具数同时从 20 增至 21、engine 模块从 44 增至 45。
696
698
 
697
699
  约定:
698
700
  - 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
@@ -721,19 +723,19 @@ const fake = {
721
723
  | --- | --- | --- |
722
724
  | 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
723
725
  | 改报告字段 | src/tools/<x>.ts 的 reportSchema + 渲染 | schema-guard 必须有对应断言 |
724
- | 加芯片族(F4/G0…) | src/data/cmsis-sources.ts(启动文件与宏)、firmware-packages.ts(FIRMWARE_FAMILIES 的仓库名要 curl 核实)、data/chips.ts(引脚存在性交给 deriveChipPinTable 从本机 db 派生)、设备事实(资源仓库的 device/<族>/chips.json,由它的 scripts/build-assets.mjs 生成)、再补一份 clock-f1 那样的时钟上限表(否则寄存器版只能不出 clock_init) | 仓库名不能猜;sha256 逐文件实测并把来源 URL 记进表里(F1 的 14 条就是这么来的) |
725
- | 加芯片型号(同族容量档) | **资源仓库的 device/f1/chips.json**(`node scripts/build-assets.mjs` 从本机 CubeMX `db/mcu` 展开 CPN 并逐字段对账,manifest 里会列 skipped)→ 插件的 src/data/device-facts.ts 自动读到;再对照 src/engine/hal-chip.ts(渲染启动文件/宏/.ld/.ioc)→ register-template.ts / register-linker.ts / register-clock.ts | 资源仓库改完要升 manifest 版本(插件按最新已装版本读);本地 `~/.dsh-stm32/assets/` 是旧版就先 `stm32_assets refresh`。三条路都要试:HAL 建工程、寄存器建工程、doctor 一致性 |
726
+ | 加芯片族(F4/G0…) | src/data/cmsis-sources.ts(启动文件与宏)、firmware-packages.ts(FIRMWARE_FAMILIES 的仓库名要 curl 核实)、data/chips.ts(引脚存在性交给 deriveChipPinTable 从本机 db 派生)、设备事实(包内 assets/device/<族>/chips.json,由 scripts/assets/build-assets.mjs 生成)、再补一份 clock-f1 那样的时钟上限表(否则寄存器版只能不出 clock_init) | 仓库名不能猜;sha256 逐文件实测并把来源 URL 记进表里(F1 的 14 条就是这么来的) |
727
+ | 加芯片型号(同族容量档) | **插件内置 `assets/device/f1/chips.json`**(`node scripts/assets/build-assets.mjs` 从本机 CubeMX `db/mcu` 展开 CPN 并逐字段对账,manifest 里会列 skipped)→ 插件的 src/data/device-facts.ts 自动读到;再对照 src/engine/hal-chip.ts(渲染启动文件/宏/.ld/.ioc)→ register-template.ts / register-linker.ts / register-clock.ts | 改完随插件发版;若用 `DSH_STM32_ASSETS` 指到外部旧版,以外部为准。三条路都要试:HAL 建工程、寄存器建工程、doctor 一致性 |
726
728
  | 改时钟树 | src/data/clock-f1.ts(PLL 源/分频/外设→总线)→ src/engine/clock-plan.ts(枚举/就近/diff)→ src/tools/ioc-plan.ts(参数与渲染)→ src/engine/register-clock.ts(寄存器版) | clock-units 14 例兜「60→64」「超限一个键都不写」;派生键必须全量重算 |
727
- | 更新设备事实(芯片表) | **资源仓库** `node scripts/build-assets.mjs` 重跑 → device/f1/chips.json + memory.json + manifest.json 一起更新;插件侧 `stm32_assets refresh` 拉新版本 | 生成物不要手改;插件已经不再内置芯片表(`scripts/gen-chip-table.mjs` 与 chip-table.json 2026-10-31 删除),没缓存时工具会明说先 refresh。测试夹具在 `test/fixtures/assets/`,与真实资源包同构 |
729
+ | 更新设备事实(芯片表) | **插件内置资源** `node scripts/assets/build-assets.mjs` 重跑 → device/f1/chips.json + manifest.json 一起更新(chipdb 与 memory.json 2026-10-31 已删:前者与 CubeMX 的 db/mcu 重复,后者字段全由 chips.json 派生);随插件发版一起分发 | 生成物不要手改;插件已经不再内置芯片表(`scripts/gen-chip-table.mjs` 与 chip-table.json 2026-10-31 删除),缺文件时工具会明说重装插件。测试夹具在 `test/fixtures/assets/`,与内置资源同构 |
728
730
  | 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
729
731
  | 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
730
732
  | 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
731
733
  | 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
732
734
  | 加 / 改探针错误分类 | engine/probe-error.ts 的 `classifyProbeFailure` 与 `PROBE_ERROR_KINDS`(MATCHERS 顺序敏感;flash / debug / session 三条路径共用同一份) | 三处同改:probe-error 的 MATCHERS 与 hint、tools 层的 `PROBE_ERROR_SCHEMA` 声明、test/probe-error-units 与 schema-guard |
733
735
  | 改 cmake 源清单的认法(设备宏、startup、HAL 模块) | engine/cmake-sources.ts 的 `collectCmakeSources` / `halModulesInUse` | 注释掉的 `#define` 与 `#include` 不能算启用;内容没变必须零写入(cmake-sources-units 15 例兜这两条) |
734
- | 改 RTT 帧格式(头长、级别含义、长度字段) | engine/rtt.ts 的 `RTT_FRAME_HEADER_BYTES` / `RTT_MIN_FRAME_BYTES` / `parseRttFrames` + templates/register/Core/Src/rtt.c 的 `RTT_FRAME_OVERHEAD` / `RTT_FRAME_MIN_BYTES` / `rtt_ring_write` | 两侧常量必须一致(rtt-units 有一条反算断言),还要同步 templates/scaffold/RTT.md 与两份 README 的三行示例;改帧头等于改 ABI,老固件会被判成帧失步 |
736
+ | 改 RTT 帧格式(头长、级别含义、长度字段) | engine/rtt.ts 的 `RTT_FRAME_HEADER_BYTES` / `RTT_MIN_FRAME_BYTES` / `parseRttFrames` + templates/register/Core/Src/rtt.c 的 `RTT_FRAME_OVERHEAD` / `RTT_FRAME_MIN_BYTES` / `rtt_ring_write` | 两侧常量必须一致(rtt-units 有一条反算断言),还要同步 templates/scaffold/RTT.md 与两份 README 的三行示例;改帧头等于改 ABI,老固件会被判成帧失步;dump 侧另有 `resyncRttFrames` 负责把环缓冲首字节/中段对齐到帧边界,并按「时间戳+级别+文本」去重(严格解析器不动,见 development-notes §39、§40) |
735
737
  | 改寄存器写法的解析或位域解释 | `src/data/svd.ts`(符号解析 / 反向查 / 解码)+ `src/tools/regs.ts`(五种写法、去重、dump、渲染、建议文案) | `svd-units` 39 例兜着;夹具在 `test/fixtures/svd/`(flat / versioned / badline 三种布局);改渲染要同步两份 README 与 development-notes §31 |
736
- | 更新 SVD 事实表(新 line / 新资源版本) | **资源仓库** `node scripts/build-assets.mjs` 重新从 cmsis-svd-data 生成 `device/f1/svd/<line>.json`(`files[].profile` 标 full,并带 ST EULA 来源)→ 插件侧 `stm32_assets action=refresh profile="full"` | SVD 严格解析:外设/寄存器/字段有一条不合法就整份拒绝;缓存键是 path+size+mtimeMs,升级后自动失效 |
738
+ | 更新 SVD 事实表(新 line / 新资源版本) | 插件仓内 `node scripts/assets/build-assets.mjs --svd` 重新从 cmsis-svd-data 生成 `assets/device/f1/svd/<line>.json`(`files[].profile` 标 full,并带 ST EULA 来源)→ 再跑 `node scripts/assets/build-assets.mjs` 重写 manifest → `stm32_assets verify` 校验完整性 | SVD 严格解析:外设/寄存器/字段有一条不合法就整份拒绝;缓存键是 path+size+mtimeMs,升级后自动失效 |
737
739
  | 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
738
740
 
739
741
  ## 11. 已知的坑与未做的事
@@ -742,8 +744,8 @@ const fake = {
742
744
  2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
743
745
  3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
744
746
  4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
745
- 5. **P2(多芯片 + HAL 外设源文件按需落位)与 P3(gdb MI 常驻)** 未开工。
746
- 6. **docs/diagrams/** 那两张 HTML 图有 2 MB 原始 / 891 KB gz,已经不进 npm 包**(package.json 的 files 从 docs 收窄成 docs/*.md)。这事现在由 `scripts/pack-size.mjs`(npm run test:size)守着:tarball ≤1.2 MB、templates/** ≤60 KB、包内禁 png/jpg/jpeg/gif/webp/bmp/pdf/html/zip/7z/exe/dll、必须含 README.md / README_EN.md / LICENSE / cordis.patch.yml / docs/reading-guide.md。实测包体 509.9 KB / 99 个文件。
747
+ 5. **P2(多芯片 + HAL 外设源文件按需落位)** 未开工;P3(gdb MI 常驻会话)**已完成**,见 `docs/development-notes.md` §37 —— `stm32_debug_eval` 优先走常驻 MI(单条命令 20–70 ms),MI 连不上才退回每次 `gdb -batch`;`continue`/`next`/`step` 会在 3 s 窗口里等 `*stopped` 并报停点(`formatStopLocation`,见 §40),`si`/`stepi`/`ni`/`nexti` 走单指令步进(`steppingCommandFor`,见 §43.1);`stm32_watch` 的采样提示会区分「目标本来就在停着」(§43.2);RTT dump 尾部失步不再提前收尾,且帧头对齐改在 `parsed.rest` 上做(§43.3);RTT 写侧由弱符号 `rtt_lock`/`rtt_unlock` 兜临界区(裸机存/恢复 PRIMASK,RTOS 覆盖成 mutex,§44.1),周期日志打 `drop=%u` 让丢帧可见(环满期间表现为内容冻结,§44.2),连接被拒/被重置不再误报「目标里没有控制块」(`sessionGoneHint`,§44.4)。
748
+ 6. **docs/diagrams/** 那两张 HTML 图有 2 MB 原始 / 891 KB gz,已经不进 npm 包**(package.json 的 files 从 docs 收窄成 docs/*.md)。这事现在由 `scripts/pack-size.mjs`(npm run test:size)守着:tarball ≤1.2 MB、templates/** 里的运行时资产(.ioc/.xml/.ld/.json/.cfg/.svd/.csv)≤40 KB 且单文件 ≤24 KB(.md 文档与源码不计入资产,见 development-notes §46.4)、包内禁 png/jpg/jpeg/gif/webp/bmp/pdf/html/zip/7z/exe/dll、必须含 README.md / README_EN.md / LICENSE / cordis.patch.yml / docs/reading-guide.md。实测包体 509.9 KB / 99 个文件。
747
749
  7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
748
750
  8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
749
751
  9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
@@ -751,8 +753,8 @@ const fake = {
751
753
  11. **别用 .elf 文件大小判「超 Flash」**:带 `-g3` 的 20 KiB 固件,.elf 里有 600 KB 调试信息,按文件大小判会把正经 C8T6 工程误报成超容量。doctor 因此读 ELF program header,只累加 `p_paddr` 落在 0x08000000 起 1 MiB 的 `PT_LOAD` 的 `p_filesz`;解析不出 program header 时才退回文件大小并注明是粗算。
752
754
  12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
753
755
  13. **B3 的真机计时还欠着**:会话复用快路径只有假探针(假 subprocess + 本地假 Tcl 服务端)的数字,真机 10 连读没测成——当时插的是 WCH-Link(`USB\VID_C251&PID_F001`),openocd 0.12 init 直接报 `Error: CMSIS-DAP command CMD_INFO failed.`,hid / bulk 后端与 `adapter speed 1000` 都试过;同一句在 B3 之前的旧版一次性路径上也复现,所以不是这次改动引入的。**复测方法**:换回 CMSIS-DAP 探针后跑 `stm32_regs_read` 连读 10 次 `0x4001100C`,看报告里的 `durationMs` 与 `reusedSession`。
754
- 14. **RTT 只有离线验证**:`rtt-units` 26 例全离线(假 subprocess + 假端口),真机上只做到「建工程 + 编译 + `nm` 取址」,**没有一次真板子 dump**(手头的 WCH-Link 与坑 13 是同一个问题)。「只有通道 0 / 无 defmt 解码 / 默认占 3 KB RAM」是设计取舍,见 development-notes §30.6。**复测方法**:换回 CMSIS-DAP 探针,烧一个取消 `USER CODE BEGIN 2` 注释的寄存器工程,`nm` 拿 `_SEGGER_RTT`,再跑 `stm32_rtt action=start addr=<addr>` + `action=dump seconds=3`。
755
- 15. **寄存器符号名与位域解释只有离线验证**:`svd-units` 39 例全离线(真实资源包 + 假 subprocess + 假 Tcl 服务端),**没有一次「真板子 + 真探针 + `GPIOC.ODR`」**(与坑 13 同一个 WCH-Link 问题)。**复测方法**:换回 CMSIS-DAP 探针后 `stm32_regs_read addresses=["GPIOC.ODR","0x4001100C"]`,看 `samples[0].name` / `fields` 与 notes 里的 SVD line。
756
+ 14. **RTT 已真机验证(2026-11-01)**:`rtt-units` 33 例仍全离线(假 subprocess + 假端口),但真板上跑通了 start → dump(1 kHz 固件打印、`dma` 与 `t` 1:1)→ stop(openocd 一并退出、探针归还)→ flash 的完整链路,见 development-notes §10.2/§39/§40。剩下的设计取舍(只有通道 0 / 无 defmt 解码 / 默认占 3 KB RAM)见 development-notes §30.6。**复现命令**(`_rich_hal` 上验过):`stm32_rtt action=start projectDir=<工程> addr=0x20000f88` → `action=dump seconds=3` → `action=stop`。
757
+ 15. **寄存器符号名与位域解释只有离线验证**:`svd-units` 39 例全离线(真实内置 SVD + 假 subprocess + 假 Tcl 服务端),**没有一次「真板子 + 真探针 + `GPIOC.ODR`」**(与坑 13 同一个 WCH-Link 问题)。**复测方法**:换回 CMSIS-DAP 探针后 `stm32_regs_read addresses=["GPIOC.ODR","0x4001100C"]`,看 `samples[0].name` / `fields` 与 notes 里的 SVD line。
756
758
 
757
759
  ---
758
760
 
package/lib/data/chips.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * L1:引脚名合法性 + 由本机 CubeMX db 派生的引脚表。
3
3
  *
4
4
  * 用户 2026-10-31「内置表删了吧」之后,这里**不再有任何内置芯片/引脚表**(原来的 CHIPS / KNOWN_CHIPS /
5
- * findChip 已删)。原因:芯片事实的唯一来源是资源包缓存 device/f1/chips.json,而那份文件只有 pinCount
5
+ * findChip 已删)。原因:芯片事实的唯一来源是内置资源 device/f1/chips.json,而那份文件只有 pinCount
6
6
  * (封装上有多少根脚),没有「这个封装有哪几根 GPIO」的清单——拿 pinCount 去猜 PA0-PB15… 等于又造一张表。
7
7
  *
8
8
  * 于是分工变成:
@@ -23,7 +23,7 @@ const MAX_PIN_NUMBER = 15;
23
23
  /**
24
24
  * 引脚名是否合法(未知/虚拟引脚一律放行)。
25
25
  *
26
- * 为什么不再按型号判「有没有这根脚」:那需要「封装 → 引脚清单」的事实,而资源包只给了 pinCount。
26
+ * 为什么不再按型号判「有没有这根脚」:那需要「封装 → 引脚清单」的事实,而内置资源只给了 pinCount。
27
27
  * 真正的引脚存在性请用 deriveChipPinTable(本机 CubeMX db)——它给的是实测清单,不是符号表。
28
28
  */
29
29
  export function isKnownPin(pin) {
@@ -147,7 +147,7 @@ export function deriveChipPinTable(input) {
147
147
  pins: [],
148
148
  notes: [
149
149
  "引脚表:没有本机 CubeMX db(" + why + "),引脚存在性不校验(isKnownPin 只查引脚名是否合法);" +
150
- "插件不内置引脚表,需要逐脚校验请装 CubeMX 或用 stm32_assets 的 chipdb",
150
+ "插件不内置引脚表(内置资源里也不再有 db 副本),需要逐脚校验就装 CubeMX —— 插件直接读它的 db/mcu",
151
151
  ],
152
152
  };
153
153
  }