dsh-stm32 0.1.2 → 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 (225) hide show
  1. package/README.md +92 -40
  2. package/README_EN.md +85 -36
  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 +94 -71
  133. package/lib/data/chips.js +38 -51
  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 +264 -17
  137. package/lib/data/db-presets.js +252 -0
  138. package/lib/data/device-facts.js +274 -0
  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 +95 -150
  148. package/lib/data/svd.js +643 -0
  149. package/lib/data/toolchain-config.js +0 -14
  150. package/lib/engine/assets.js +659 -0
  151. package/lib/engine/breakpoints.js +297 -0
  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 +576 -22
  161. package/lib/engine/debug.js +99 -46
  162. package/lib/engine/doctor.js +162 -19
  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 +317 -76
  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 +1247 -63
  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 +231 -0
  177. package/lib/engine/probe-session.js +347 -0
  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 +130 -45
  183. package/lib/engine/regs.js +43 -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 +758 -0
  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 +12 -2
  192. package/lib/skill/stm32-workflow.js +2 -2
  193. package/lib/tools/assets.js +272 -0
  194. package/lib/tools/cache.js +8 -0
  195. package/lib/tools/debug-session.js +41 -6
  196. package/lib/tools/debug.js +41 -11
  197. package/lib/tools/doctor.js +65 -4
  198. package/lib/tools/firmware-install.js +31 -6
  199. package/lib/tools/flash.js +47 -10
  200. package/lib/tools/generate.js +25 -0
  201. package/lib/tools/ioc-apply.js +2 -0
  202. package/lib/tools/ioc-inspect.js +2 -0
  203. package/lib/tools/ioc-plan.js +59 -2
  204. package/lib/tools/ioc-verify.js +237 -0
  205. package/lib/tools/project-create.js +63 -3
  206. package/lib/tools/regs.js +453 -61
  207. package/lib/tools/route-plan.js +3 -0
  208. package/lib/tools/rtt.js +470 -0
  209. package/lib/tools/watch.js +256 -0
  210. package/package.json +5 -4
  211. package/templates/openocd/stm32c0x.cfg +83 -0
  212. package/templates/openocd/stm32u0x.cfg +64 -0
  213. package/templates/register/CMakeLists.txt +8 -2
  214. package/templates/register/Core/Inc/rtt.h +138 -0
  215. package/templates/register/Core/Src/main.c +42 -25
  216. package/templates/register/Core/Src/rtt.c +373 -0
  217. package/templates/scaffold/RTT.md +90 -0
  218. package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
  219. package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
  220. package/templates/scaffold/openocd.cfg +5 -3
  221. package/templates/scaffold/vscode/launch.json +8 -4
  222. package/docs/development-notes.md +0 -2116
  223. package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
  224. package/docs/logic-audit.md +0 -607
  225. package/lib/data/f1-ram.generated.js +0 -34
@@ -1,7 +1,7 @@
1
1
  # dsh-stm32 源码精读指南
2
2
 
3
3
  > 面向:第一次读这个仓库、并且要改它的人。
4
- > 规模:72 个 TypeScript 文件约 24.3k 行(另有脚本生成的 src/data/chip-table.json 2044 行),外加一个手写的浏览器 bundle(client/client.js,682 行)。
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(19 个文件:20 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
- | L2 逻辑层 | src/engine(41 个模块) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
31
- | L1 事实表 | src/data(8 张事实表 + 1 份生成的芯片薄表) | 芯片表(含由 CubeMX db 派生的引脚表与 chip-table.json)、镜像 URL、固件族、F1 容量档、F1 时钟树、安装指引、搜索路径、配置读写 | 起进程、写工程文件 |
29
+ | L3 契约层 | src/tools(23 个文件:22 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
+ | L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
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,16 +44,16 @@
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/>20 个工具"]
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 路由"]
51
51
  IDX --> EVT["turn/end、session/disposed、dispose<br/>把探针还回去"]
52
- TOOLS --> ENGINE["src/engine/*<br/>41 个纯逻辑模块"]
52
+ TOOLS --> ENGINE["src/engine/*<br/>45 个纯逻辑模块"]
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/>8 张事实表"]
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"]
@@ -66,14 +66,16 @@ flowchart TD
66
66
 
67
67
  | 目录 | 文件数 | 行数 | 说明 |
68
68
  | --- | --- | --- | --- |
69
- | src/ | 4 | 795 | index.ts 119、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
70
- | src/tools/ | 19 | 5078 | 20 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 route-plan.ts 573 行 |
71
- | src/engine/ | 41 | 15919 | 见第 5 章;最大的是 msys2-install.ts 2313 行,其次是 clock-plan.ts 801 行 |
72
- | src/data/ | 9 | 4592 | 8 张 .ts 事实表共 2548 行 + 脚本生成的 chip-table.json(2044 行 / 2016 颗芯片),见第 6 章 |
73
- | templates/ | 17 | — | 工程脚手架与寄存器版模板(CMake、链接脚本、launch/settings、openocd.cfg、demo.ioc) |
69
+ | src/ | 4 | 803 | index.ts 127、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
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
+ | 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/ | 29 套件 + 15 个 e2e 脚本 + 4 个辅助脚本 | — | 见第 9 章 |
76
- | scripts/ | 5 | 776 | copy-client.mjs(24)、gen-chip-table.mjs(371)、gen-xcube-catalog.mjs(151)、pack-size.mjs(80)、pack-smoke.mjs(150) |
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
+
78
+ > 全书行数统一口径:按文件里的换行符数(`content.split("\n").length`,等价于编辑器的「块末行号」),2026-10-31(D 阶段末)重数过一遍——第 1、4.1、4.2、5、6 章都按这个口径,和本指南更早版本的数字会有几行到几十行的差异。
77
79
 
78
80
  ## 2. 阅读顺序
79
81
 
@@ -93,12 +95,12 @@ flowchart TD
93
95
 
94
96
  ## 3. 入口层
95
97
 
96
- ### 3.1 src/index.ts(119 行)
98
+ ### 3.1 src/index.ts(127 行)
97
99
 
98
100
  三件事,只有三件:
99
101
 
100
102
  1. **声明身份与依赖**:`export const name = "dsh-stm32"`、`export const inject = ["tools", "subprocess", "jobs"]`。这三个是硬依赖,缺了插件不加载。
101
- 2. **apply(ctx) 里按「先探测、再操作」的顺序注册 20 个工具**: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 → 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。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
102
104
  3. **注册可选层并挂三个事件**:commands / skills 走 `ctx.inject([...], scope => ...)`,宿主没组合这些服务时静默跳过,工具照常工作;webServer 路由在`registerWebRoutes` 里自己判断。
103
105
 
104
106
  三个事件是本插件唯一的「状态清理入口」,也是很容易读漏的地方:
@@ -152,11 +154,11 @@ ctx.on("dispose", () => { void debugSessions.stop("插件卸载"); });
152
154
 
153
155
  7 条命令里有 6 条最终调用 engine 的同一个函数(build → runBuild,flash → runFlash …),所以它们和工具的唯一差别是:输入来自文本而不是 JSON、输出是一段中文。
154
156
 
155
- ## 4. tools 层:20 个工具 + 1 个基础设施
157
+ ## 4. tools 层:22 个工具 + 1 个基础设施
156
158
 
157
159
  ### 4.1 一个工具文件的固定骨架
158
160
 
159
- 以 src/tools/flash.ts(185 行)为例,每个工具都是同一个模子:
161
+ 以 src/tools/flash.ts(203 行)为例,每个工具都是同一个模子:
160
162
 
161
163
  ```ts
162
164
  export const FLASH_TOOL = "stm32_flash"; // 1. 名字常量(测试与命令复用)
@@ -184,39 +186,41 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
184
186
 
185
187
  三个细节值得记住:
186
188
 
187
- 1. **输出 schema 是硬的。** 宿主会拿 `output.schema` 校验 execute 的返回值,report 上任何没声明的字段都会被判「工具返回了非法输出」——这正是 0.1.2 上板时抓到的缺陷(flash 失败带 errorCode,而 schema 漏声明它,于是失败路径直接崩)。改 report 结构必须同步改 schema,test/schema-guard.mjs 就是为这条存在的。
189
+ 1. **输出 schema 是硬的。** 宿主会拿 `output.schema` 校验 execute 的返回值,report 上任何没声明的字段都会被判「工具返回了非法输出」——这正是 0.1.2 上板时抓到的缺陷(flash 失败时带一个故障分类字段,而 schema 漏声明它,于是失败路径直接崩;这个字段在 B2 之后叫 `probeError`,见 §5.4)。改 report 结构必须同步改 schema,test/schema-guard.mjs 就是为这条存在的。
188
190
  2. **门禁在工具层,不在 engine。** engine 假设工具链就位;`blockedReport` / `emptyReport` 是门禁拦截与早退时造「同形报告」的工厂,保证失败也是合法输出。
189
191
  3. **`resolveProjectDir` + `validateToolArgs`(tools/project-dir.ts,120 行)是所有工具的共同入口**:前者把 `projectDir` 参数 / 会话工作目录落成绝对路径,后者按 `RequiredArgSpec` 校验必填参数类型,报错文案统一。
190
192
 
191
- ### 4.2 20 个工具一览
193
+ ### 4.2 22 个工具一览
192
194
 
193
195
  | 工具 | 文件(行) | engine 入口 | 门禁能力 |
194
196
  | --- | --- | --- | --- |
195
- | `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 | 无 |
196
198
  | `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
197
199
  | `stm32_firmware_install` | firmware-install.ts(288) | firmware-install.planOrInstallFirmware | 无 |
198
- | `stm32_project_create` | project-create.ts(344) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
200
+ | `stm32_project_create` | project-create.ts(387) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
199
201
  | `stm32_project_export` | project-export.ts(122) | project-export.runExport | 无 |
200
202
  | `stm32_code_patch` | code-patch.ts(130) | code-patch.patchUserCode | 无 |
201
- | `stm32_generate` | generate.ts(308) | generate.runGenerate | generate(CubeMX 启动器 + JRE) |
202
- | `stm32_ioc_inspect` | ioc-inspect.ts(241) | ioc.summarizeIoc | 无 |
203
- | `stm32_ioc_plan` | ioc-plan.ts(395) | ioc-plan.planIocChanges + clock-plan.planClockChanges(引脚 / 键 / 时钟进同一个 candidate) | 无 |
204
- | `stm32_ioc_apply` | ioc-apply.ts(135) | ioc-plan.applyIocPlan / rollbackIoc | 无 |
203
+ | `stm32_generate` | generate.ts(311) | generate.runGenerate | generate(CubeMX 启动器 + JRE) |
204
+ | `stm32_ioc_inspect` | ioc-inspect.ts(243) | ioc.summarizeIoc | 无 |
205
+ | `stm32_ioc_plan` | ioc-plan.ts(398) | ioc-plan.planIocChanges + clock-plan.planClockChanges(引脚 / 键 / 时钟进同一个 candidate) | 无 |
206
+ | `stm32_ioc_apply` | ioc-apply.ts(137) | ioc-plan.applyIocPlan / rollbackIoc | 无 |
205
207
  | `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
206
- | `stm32_flash` | flash.ts(185) | flash.runFlash | flash(openocd) |
207
- | `stm32_debug_run` | debug.ts(211) | debug.runDebugRun | debug(openocd + gdb) |
208
- | `stm32_debug_session` / `_eval` / `_stop` | debug-session.ts(265,三工具同文件) | debug-session.DebugSessionManager(单例 debugSessions)+ releaseProbeFor | debug(仅 session 启动时) |
209
- | `stm32_regs_read` | regs.ts(218) | regs.runRegsRead | debug |
210
- | `stm32_route_plan` | route-plan.ts(573) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
211
- | `stm32_cache` | cache.ts(274) | engine/cache 全套 | 无 |
212
- | `stm32_doctor` | doctor.ts(192) | doctor.runDoctor + collectChipConsistency(型号/启动文件/设备宏/.ld/Flash 五项一致性) | 无(它自己就是体检) |
208
+ | `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
209
+ | `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
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 需要会话) |
212
+ | `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
213
+ | `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
214
+ | `stm32_route_plan` | route-plan.ts(576) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
215
+ | `stm32_cache` | cache.ts(306) | engine/cache 全套 | 无 |
216
+ | `stm32_doctor` | doctor.ts(202) | doctor.runDoctor + collectChipConsistency(型号/启动文件/设备宏/.ld/Flash 五项一致性) | 无(它自己就是体检) |
213
217
  | —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
214
218
 
215
- 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**route-plan.ts 573 行**是 tools 层里最大的,因为它的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
219
+ 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**regs.ts 735 行**现在是 tools 层最大的(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**退居第二——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
216
220
 
217
- ## 5. engine 层:41 个模块,十个域
221
+ ## 5. engine 层:45 个模块,十个域
218
222
 
219
- 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。
223
+ 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。表里列 45 个;`src/engine/` 目录里实际有 46 个 `.ts`——`assets.ts`(内置资源装配与完整性校验,flat 布局)还没单独成行,读内置资源那条链路时直接从 §5.7 与 `src/data/device-facts.ts` 一起看。
220
224
 
221
225
  ### 5.1 进程与路径(3 个,413 行)
222
226
 
@@ -242,17 +246,22 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
242
246
  | build.ts(493) | `runBuild(subprocess, request)`:选 preset(`pickConfigurePreset` 优先 Debug)→ `cmake --preset` → `cmake --build` → `findElf`(= `pickElf`:CMakeCache 的 CMAKE_PROJECT_NAME 优先,否则取 mtime 最新的 .elf;`elfCandidates` 列出全部候选,`elfSelectionNote` 在候选多于 1 个时把「选了哪个、其他候选的 mtime」写进 notes)→ 解析内存占用(`parseMemoryUsage`,GNU ld 的 `RAM: 1584 B 20 KB 7.73%` 格式)→ 错误行(`parseBuildErrors`)与警告数(`countWarnings`)→ 按需跑 objcopy 出 hex/bin(`converted`,失败只写 note 不判失败)。辅助导出:`presetDirs`、`detectBuildDir`。 |
243
247
  | layout.ts(50) | 生成物的落位约定:`GEN_SRC_DIR = "Src"`、`GEN_INC_DIR = "Inc"`、`PROJECT_SRC_DIR = "Core/Src"`、`PROJECT_INC_DIR = "Core/Inc"`、`mapGeneratedPath(rel)`、`listGeneratedFiles`。CubeMX 无头模式吐在 `.dsh-stm32/gen/Src|Inc`,由这里映射回工程的 Core/。 |
244
248
 
245
- ### 5.4 烧录、调试与诊断(5 个,2257 行)
249
+ ### 5.4 烧录、调试与诊断(9 个,4087 行)
246
250
 
247
251
  | 模块 | 职责与关键导出 |
248
252
  | --- | --- |
249
- | flash.ts(424) | `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` 认 ** Programming Finished ** / ** Verified OK **,成功序列里的偶发 Error 行进 noise)→ 失败时分类(`errorCodeOfLines` → no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / unknown)→ 追加 USB 形态提示(`usbNoteFor` / `probeMissingLines`)。`toOpenOcdPath` 只把反斜杠换成正斜杠。`HINT_PROBE` / `HINT_DP` / `HINT_BUSY` 三个提示常量是 export 的,debug.ts 复用同一套文案。 |
250
- | debug.ts(406) | 一次性调试快照 `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)。失败时:`errorCodeOfLines` 归类(与 flash 同一枚举)、`debugHintFor` 给下一步、`probeMissingLines` 命中就跑 `usbDiagnosis`、日志用 `keyLogTail(lines, 40)`(优先留 adapter/Error 行,而不是「最后 15 行」)、`firstProblemLine` 把首条根因塞进 errors。 |
251
- | debug-session.ts(516) | 长会话租约。`DebugSessionManager` 管「一个常驻 openocd + 多次短命 gdb -batch eval」,空闲 90 s、总时长 10 min、turn/end 立刻释放;`releaseProbeFor(reason)` 是别的工具(flash/regs/debug_run)动探针前必须调的一步(审计 B16:先释放再门禁)。三个纯函数是好单测点:`normalizeHexAddress`、`parseGdbPrintedHex`、`parseMarkedWords`(按 `echo ===DSH:<tag>===` 分段对齐,修「中间某个地址读失败导致后面值整体前移」)。 |
252
- | regs.ts(246) | 读内存映射寄存器。`normalizeAddress`(0x 可省)、`buildRegsScript`(生成 openocd 脚本:init → halt → mdw)、`parseRegsLog` → `runRegsRead`。与 debug-session 的区别是「一次性、不复位」,起完就关。 |
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 不会再各写一套漂移。 |
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 三元组。 |
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(...)`。 |
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` 是什么。 |
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 三条路径共用同一份规则。 |
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。 |
260
+ | rtt.ts(724) | RTT 日志(C 阶段)。控制块沿用 SEGGER 约定(首 10 字节 `"SEGGER RTT"`、描述符 24 字节),传输交给 openocd 的 `rtt setup/start/server start`,本模块只管帧与状态:`startRtt`(`mdw` 三个字校验魔数 `RTT_MAGIC_WORD_0/1/2_LOW` → 发三条命令 → 起本地端口)/`dumpRtt`(连端口读 N 秒或 M 条 → `parseRttFrames` 解帧 → 按 `level` 上限过滤 → `truncated` / `dropped` 如实报)/`stopRtt` / `rttStatus`(`src/index.ts` 在 turn/end 时调 `stopRtt`)。帧是 13 字节头:4B 长度 LE(= 9 + payload)、1B 级别 1..4、8B 时间戳 ms LE、UTF-8 payload;`len < 9` 或 `> 4096` 判失步并按字节滑动重找,单帧坏掉不炸整次 dump。常量 `DEFAULT_RTT_PORT=9090`、`DEFAULT_RTT_SIZE=0x400`、`DEFAULT_DUMP_SECONDS=3`、`DEFAULT_MAX_RECORDS=200`、`RTT_FRAME_HEADER_BYTES=13`、`RTT_MIN_FRAME_BYTES=9`;八条 hint(地址写错 / 没有会话 / 控制块全 0 / 魔数不符 / 端口占用 / 连不上 / Tcl 超时 / 帧失步)只此一份。 |
261
+ | breakpoints.ts(294) | 断点预算(B4)。`BreakpointBudget{code,data}`、`F1_BREAKPOINT_BUDGET = {code:6, data:4}`、`quotaOf(used, limit)`(used 夹在 [0,limit],给出 used/limit/remaining 三元组)、`budgetFromChipFact`、`readIocCpn`、`resolveBreakpointBudget(projectDir)`(.ioc 的 Mcu.CPN → chips.json 里可选的 breakpoints/watchpoints;没 .ioc、chips.json 没这颗、或没写值都回退 F1 6/4 并说明原因)、`parseBreakpointSpec` / `breakpointFromGdbCommand`、`collectBreakpointRequests({breakAt,breakpoints,preCommands})`(preCommands 里的 break / watch 也计数,同 kind+location 去重)、`planBreakpoints` 出 detail + suggestion。超限在 spawn openocd **之前**就失败,不碰探针、也不关已有会话。 |
253
262
  | doctor.ts(665) | 体检 + 配套性核对。`runDoctor`:逐组件探测 + 进程残留(`parseTasklistCsv` 认 openocd/gdb)+ 端口占用(`checkPortBusy`)+ .ioc 告警 + USB 形态(`usbDiagnosis` / `diagnoseUsb`:只认行内 ASCII 本体,因为中文系统的 pnputil 字段名是 GBK 乱码)+ elf/构建目录;最后跑 **checkChipConsistency / collectChipConsistency** 的五项一致性:① 型号 ↔ 启动文件名 ② 启动文件 ↔ cmake 设备宏 ③ `.ld` MEMORY 容量 ↔ 芯片实际容量 ④ `.elf` Flash 占用 ↔ Flash 容量 ⑤ .ioc 用到的引脚是否在封装内。配套纯函数 `parseLinkerMemory`(认 20K / 0x5000 / 65536,算式不算)、`deviceDefinesIn`、`elfFlashBytes`(读 ELF program header,只累加 `p_paddr` 落在 0x08000000 起 1 MiB 的 PT_LOAD 的 `p_filesz`)、`findLinkerScript` / `linkerScriptNames`(多个 .ld 时优先非 STM32F103XX_FLASH.ld 的那个)。 |
254
263
 
255
- ### 5.5 生成、编码、.ioc 事务与时钟(10 个,3659 行)
264
+ ### 5.5 生成、编码、.ioc 事务与时钟(10 个,3657 行)
256
265
 
257
266
  | 模块 | 职责与关键导出 |
258
267
  | --- | --- |
@@ -263,29 +272,29 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
263
272
  | code-patch.ts(215) | `patchUserCode`:只改一个 USER CODE 块(replace / append),块内出现 `{` 或 `}` 拒绝(结构行守卫),写前备份,写回**按字节拼接**(见 text-file)。`listUserCodeLabels` 列出可用标签。 |
264
273
  | text-file.ts(172) | 编码层。`detectEncoding`(BOM → utf8-bom;空 → utf8;严格 UTF-8 成 → utf8;再试 gb18030;否则 unknown)、`decodeText`、`encodeText`(gb18030 只允许纯 ASCII——Node 只有解码器没有编码器)、`readTextFile`、`lineStarts`、`replaceLineRange`(未改的行原字节照抄,只把新增行按原编码插入)。**这是「中文注释不被写坏」的唯一保障**。 |
265
274
  | ioc.ts(202) | .ioc 只读解析:`parseIocEntries`、`decodeIocValue`、`summarizeIoc`(MCU、时钟树、引脚、外设、调试口、工程设置、警告)。 |
266
- | ioc-plan.ts(614) | .ioc 事务。`planIocChanges` 算出逐键 diff + 源 SHA-256 → planId;`applyIocPlan` 校验 SHA 后原子替换(备份到 backups/<stamp>-ioc);`rollbackIoc(backupFrom)` 回滚;辅助 `renderIocText`、`compareEntries`、`sha256Hex`、`encodeIocValue`、`loadPlan`。引脚写入保序(审计 A3):只追加新增,不因缺 .Signal 删已有项。 |
275
+ | ioc-plan.ts(612) | .ioc 事务。`planIocChanges` 算出逐键 diff + 源 SHA-256 → planId;`applyIocPlan` 校验 SHA 后原子替换(备份到 backups/<stamp>-ioc);`rollbackIoc(backupFrom)` 回滚;辅助 `renderIocText`、`compareEntries`、`sha256Hex`、`encodeIocValue`、`loadPlan`。引脚写入保序(审计 A3):只追加新增,不因缺 .Signal 删已有项。 |
267
276
  | clock-plan.ts(801) | 时钟规划(t3 新增)。`planClockChanges`:枚举 PLL 源 × 倍频 × 分频的全部可行组合 → 取 `|sysclk − target|` 最小(同距取更高档,所以 60 MHz 的目标落在 64 MHz,报告里写「不可达,已选 64 MHz(+4 MHz)」)→ 与 .ioc 现有键做 diff,`PLLMUL`、`SYSCLKFreq_VALUE`、`HCLKFrequency`、`APB1/APB2Prescaler` 这些派生键**全量重算**(只改源键会让 CubeMX 按旧频率理解)→ 再给逐外设频率表与 UART 波特率整除误差。`mode` 四态:`snapshot`(只看不写)/ `nearest`(默认就近)/ `explicit`(钉死 pllMul)/ `none`。超限(SYSCLK >72、APB1 >36、ADC >14)时**一个键都不写**,只报错。参数化在 src/data/clock-f1.ts。 |
268
277
  | cmake-sources.ts(480) | **老洞的补丁**:CubeMX 无头生成从不重写 `cmake/stm32cubemx/CMakeLists.txt`,那份源清单永远停在脚手架快照上。`collectCmakeSources` 从磁盘反推真相(`pickStartupFile` 选启动文件 → `deviceDefineFromStartup` 得 `STM32F103xB` → `familyTokensFromStartup` 得家族目录 `STM32F1xx` → `halModulesInUse` 由 `stm32f1xx_hal_conf.h` 的 `HAL_xxx_MODULE_ENABLED`(先 `stripComments`,注释掉的不算)∪ `Core/Src` 源码里的 `#include "stm32f1xx_hal_x.h"` 求并集),`refreshCubemxCmakeLists` 只重写三个 managed 块(设备宏 / 应用清单 / 驱动清单),保留原顺序、摘掉磁盘上已不存在的条目、缺的追加到末尾;`dominantEol` 按多数行尾写回、内容一致时一个字节都不写;`describeRefresh` 生成一句人话进 generate 的 notes。 |
269
278
 
270
- ### 5.6 造工程、链接脚本与导出(8 个,2198 行)
279
+ ### 5.6 造工程、链接脚本与导出(8 个,2224 行)
271
280
 
272
281
  | 模块 | 职责与关键导出 |
273
282
  | --- | --- |
274
283
  | scaffold.ts(518) | HAL 路线脚手架。`preflightTarget`(工程名合法 → 目录非空 → hal 且已有同名 .ioc 就拒绝,指向 ioc_plan/apply)、`backupBeforeOverwrite` + `backupWarning`(只备份真会被覆盖的文件)、`mkdirTracked` / `cleanupAfterFailure`(失败只回收本次新建)、`resolveFirmwareRoot`(Repository → dsh-firmware → extraDirs)、`createProjectScaffold`、`templateDir`、常量 `DEFAULT_FIRMWARE_PACKAGE` / `SCAFFOLD_PROJECT_NAME`。复制走 fs-longpath。型号相关的启动文件、设备宏、`<DeviceId>_FLASH.ld` 与 demo.ioc 由 hal-chip 在**写盘之前**渲染成字符串,渲染失败时一个字节都不写。 |
275
284
  | hal-chip.ts(284) | HAL 路线的「型号 → 生成物」派生与纯文本渲染(t1 新增)。`resolveHalChip(input)` 复用 F1Chip,`renderStartupAndDefine`(RCT6 → startup_stm32f103xe.s + STM32F103xE)、`renderLinkerScript`(把 STM32F103XX_FLASH.ld 的 MEMORY 两行与注释两行换成 `<DeviceId>_FLASH.ld`,RCT6 是 256 KiB / 48 KiB)、`renderIoc`(demo.ioc 的 Mcu.CPN、引脚、时钟键)、`pointLinkerFlagAt`(把工具链文件里写死的 `-T STM32F103XX_FLASH.ld` 改指新名,否则命令行上会出现两个 -T)。全是字符串函数,所以能先渲染后落盘。 |
276
- | register-template.ts(558) | 寄存器路线(不碰 CubeMX)。`resolveStartupChoice`(按型号/族选启动文件与宏)、`ensureCmsisTemplate`(从镜像下载 10 个文件到缓存并校验 sha256)、`createRegisterProject`(拷模板 → 写设备头/启动文件/链接脚本 → 生成 main.c)。模板文件缺失分「必需」与「可选」(.gitignore 是可选,缺了给 warning 不阻断)。模板里已不写死任何型号:启动文件、设备宏、设备头、`.ld`、时钟全部按 `resolveF1Chip` 的结果参数化(14 个容量档)。 |
285
+ | register-template.ts(584) | 寄存器路线(不碰 CubeMX)。`resolveStartupChoice`(按型号/族选启动文件与宏)、`ensureCmsisTemplate`(从镜像下载 10 个文件到缓存并校验 sha256)、`createRegisterProject`(拷模板 → 写设备头/启动文件/链接脚本 → 生成 main.c)。模板文件缺失分「必需」与「可选」(.gitignore 是可选,缺了给 warning 不阻断)。模板里已不写死任何型号:启动文件、设备宏、设备头、`.ld`、时钟全部按 `resolveF1Chip` 的结果参数化(14 个容量档)。 |
277
286
  | register-clock.ts(261) | 寄存器版的时钟初始化代码生成(不碰 CubeMX)。按 line 取最高 SYSCLK:F100 24 / F101 36 / F102 48 / F103·F105·F107 72 MHz;HSE 8 MHz ×N(F101 走 HSE/2×9 凑 36 MHz);FLASH latency 按频率给 0/1/2(F100 的设备头里没有 latency 字段,自动跳过);APB1 在 >36 MHz 时 ÷2;HSE 起不来就退 HSI/2×N 并写警告。产出的 `clock_init()` 插在 main() 第一行,末尾 `SystemCoreClockUpdate()` 让 SysTick 与 delay_ms 跟着对。 |
278
287
  | register-linker.ts(152) | 寄存器版的链接脚本渲染:按型号换掉 `<DeviceId>_FLASH.ld` 的 MEMORY RAM/FLASH 两行。F100/F101/F102 的 RAM 不在 src/data/stm32f1.ts 的表里,用 CubeMX db 的最小值兜底**并明确警告**(宁可小——栈必须留在真 RAM 内)。 |
279
288
  | vscode-config.ts(118) | `VSCODE_PLACEHOLDERS`(gdb / toolchain / cmake / svd 四个占位符)、`detectVscodeFill`(按本机探测结果填)、`fillVscodeTemplate`(没值的整行删掉并记 dropped,绝不写空串)、`describeDroppedPlaceholder`。模板里因此不出现任何开发机绝对路径(审计 B1)。 |
280
289
  | project-export.ts(155) | `runExport`:收集源文件(跳过 build / .dsh-stm32 / node_modules / .git)→ 可选带 prebuilt(elf/hex/bin)→ 可选内联 README → 打 zip。 |
281
290
  | zip.ts(152) | 自写的最小 store-only zip(不压缩、不引依赖):`crc32`、`makeZip`、`listZipEntries`(测试用来验内容)。 |
282
291
 
283
- ### 5.7 下载、缓存与固件包(7 个,2456 行)
292
+ ### 5.7 下载、缓存与固件包(7 个,2502 行)
284
293
 
285
294
  | 模块 | 职责与关键导出 |
286
295
  | --- | --- |
287
296
  | fetch.ts(347) | `fetchOne(target, destRoot, options)`:按 URL 列表依次尝试 → 校验内容特征(markers)→ 校验 sha256(有声明时)→ 落到目标路径;`fetchAll` 汇总。失败信息带「期望 / 实际」两个哈希,方便判断是上游挪了内容。**同一源内断点续传**(F3c):`streamOnce(url, part, startAt, …)` 用 `Range: bytes=N-` 流式写 `.part-<pid>-<seq>`,watchdog 在 `stallMs`(默认 10 s)内判停滞或平均速率 < `minBytesPerSec`(默认 1024)就 abort,返回 `slow: true` 让 `fetchOne` 从已落盘字节续一次;服务器回 200(无视 Range)时截断重写,只有 206 才追加——**换源一律从零开始**(不同源的字节不保证同一份)。**校验失败必须连 `.part` 一起删**(T1 实测抓到的泄漏):体量 / 网页 / markers / sha256 四道都不通过时走局部 `reject(reason)`——它把失败原因记进 `attempts` 再 `removeQuietly(part)`,否则半成品会长期躺在缓存目录里等着占满磁盘。 |
288
- | cache.ts(370) | 缓存索引(默认 %LOCALAPPDATA%\dsh-stm32\cache,可用 DSH_STM32_CACHE 覆盖)。`CACHE_INDEX_VERSION`、`readCacheIndex` / `writeCacheIndex`(坏索引先改名 index.json.broken-<ts>;tmp 唯一名 + rename 失败先备份旧索引再重试;`CacheIndexWriteError` 让上层知道是索引写坏了,审计 A2/A12)、`upsertCacheEntry` / `removeCacheEntry` / `findCacheEntry`、`checkCacheEntry`(按 sha256 验证,审计 A38)、`sha256OfFile`、`describeCacheBytes`。 |
297
+ | cache.ts(416) | 缓存索引(默认 %LOCALAPPDATA%\dsh-stm32\cache,可用 DSH_STM32_CACHE 覆盖)。`CACHE_INDEX_VERSION`、`readCacheIndex` / `writeCacheIndex`(坏索引先改名 index.json.broken-<ts>;tmp 唯一名 + rename 失败先备份旧索引再重试;`CacheIndexWriteError` 让上层知道是索引写坏了,审计 A2/A12)、`upsertCacheEntry` / `removeCacheEntry` / `findCacheEntry`、`checkCacheEntry`(按 sha256 验证,审计 A38)、`sha256OfFile`、`describeCacheBytes`。 |
289
298
  | tar.ts(288) | `extractTarGz(archive, destRoot, options)`:解 gzip + tar,路径白名单(`isSafeRelative` 拒反斜杠、冒号、.. 与空段)、类型白名单(`entryKind`:0/空/5 正常,x/g/L/K 元数据,其余跳过并记名,审计 A4)、声明长度超出实际数据判截断整次失败。 |
290
299
  | firmware-install.ts(760) | 固件包下载与组装。`firmwareInstallPlan` / `installFirmware` / `planOrInstallFirmware`:选址(`isProtectedSystemDir` 拒绝 Program Files 之类、`orderCubeMxRoots` 把本机存在的排前面、`hasCubeMxExe` 只对真 CubeMX 目录建 dsh-firmware)→ 下载 2 个归档 + 5 个内核头 → `extractTarGz` → `verifyFirmwarePackage` → 写 `installed.json` 记录(`FIRMWARE_RECORD_FILE`)→ `firmwareExtraDirs` 让 generate/scaffold 也能找到非标准落点。 |
291
300
  | thirdparty.ts(281) | 生成期间临时停放 CubeMX 的第三方包索引(`PARKED_NAME = "pdsc.dsh-parked"`、`needsThirdpartyPacks`、`parkThirdpartyDb`),有 X-CUBE 包的工程保持原样;`cubeMxUserHome`。 |
@@ -311,19 +320,20 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
311
320
  | --- | --- |
312
321
  | route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
313
322
 
314
- ## 6. data 层:8 张事实表(2548 行)+ 1 份生成的芯片薄表
323
+ ## 6. data 层:10 个数据模块(3599 行;芯片事实来自包内 assets/)
315
324
 
316
325
  | 模块 | 行数 | 内容 |
317
326
  | --- | --- | --- |
318
- | chips.ts | 202 | 内置 `CHIPS` 芯片表(F103C8T6 等)、`findChip`、`isKnownPin`(未知型号一律放行,不猜),外加**由本机 CubeMX db 派生引脚表**的一整套:`parseMcuDbXmlPins`(`<Pin Name= Position=>`,`Position<=0` 的虚拟脚丢弃,`PC13-TAMPER-RTC → PC13`,电源脚不算)、`findMcuDbDir`(`<CubeMX>/db/mcu`)、`readMcuDbPins`、`deriveChipPinTable({cpn, mcuName, dbMcuDir})` → `kind: db / builtin / unknown`(db 命中就注明来源 XML 与引脚数,否则明说「未与本机 db 校验」)。引脚合法性由它兜底。 |
319
- | cmsis-sources.ts | 392 | 寄存器路线的下载源与型号映射:四个镜像(jsdelivr fastly/cdn、raw.githubusercontent、ghproxy)、`CMSIS_FAMILIES`、`startupChoiceFor(mcu)`(委托 resolveF1Chip,兼容 `F1:B` / `F1:8` / `F103:xb` / `STM32F103C8T6` 四种写法)、`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 真实下载实测的。 |
320
- | stm32f1.ts | 234 | F1 的容量档事实表(两条路线共用的唯一型号来源)。`F1_LINES`(6 条 line:100 xb/xe、101 x6/xb/xe/xg、102 x6/xb、103 x6/xb/xe/xg、105 xc、107 xc)、`GROUP_BY_LETTER`、`FLASH_BY_LETTER`、`RAM_BY_LINE_LETTER`(同字母在不同 line 差很多:字母 C 在 F103 是 256 KiB Flash / 48 KiB RAM,在 F105/F107 是 64 KiB RAM)、`PINS_BY_PACKAGE`(T36 / C48 / R64 / V100 / Z144)、`resolveF1Chip(input)` → `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`。 |
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 就明说「引脚存在性不校验」,绝不拿内置表冒充)。 |
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 真实下载实测的。 |
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 没有这一容量档。 |
321
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 名单。 |
322
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`。 |
323
332
  | install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
324
333
  | search-roots.ts | 421 | 见 5.2。 |
325
334
  | toolchain-config.ts | 370 | 见 5.2。 |
326
- | chip-table.json | 2044 | **脚本生成的薄表**(`node scripts/gen-chip-table.mjs` 产出,不要手改):2016 颗芯片的 CPN / 内核 / 主频 / RAM / Flash / 电压 / 引脚数,来源是本机 CubeMX 的 `db/mcu/*.xml`。插件当前只消费 F1 那一段,其余为将来扩族备查;`--check` 模式给 CI 用(生成物与 db 不一致就红)。 |
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` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
327
337
 
328
338
  ## 7. 关键流程
329
339
 
@@ -444,12 +454,12 @@ flowchart TD
444
454
  E --> F["openocd -f ... -c program <elf> verify reset exit"]
445
455
  F --> G["parseFlashLog:认 Programming Finished / Verified OK<br/>成功序列里的偶发 Error 行进 noise"]
446
456
  G --> H{"ok?"}
447
- H -->|是| OK["programmed + verified,errorCode 缺省"]
448
- H -->|否| I["errorCodeOfLines 分类:no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / unknown"]
457
+ H -->|是| OK["programmed + verified,probeError 缺省(成功时字段根本不出现)"]
458
+ H -->|否| I["classifyProbeFailure 分 8 类:no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / timeout / unknown"]
449
459
  I --> J["notes:USB 形态(usbNoteFor)+ probe-busy 专用提示(HINT_BUSY)"]
450
460
  ```
451
461
 
452
- 真板子取证过的一个细节:两个进程同时访问同一个 CMSIS-DAP 时,日志不是「设备忙」,而是交替出现 CMSIS-DAP command mismatch / transfer count mismatch / Failed to write memory at 0x00000004。所以 errorCodeOfLines 里专门把这几种行归到 probe-busy。
462
+ 真板子取证过的一个细节:两个进程同时访问同一个 CMSIS-DAP 时,日志不是「设备忙」,而是交替出现 CMSIS-DAP command mismatch / transfer count mismatch / Failed to write memory at 0x00000004。所以 probe-error.ts 的 MATCHERS 里专门把这几种行归到 probe-busy(`/cmsis-dap (transfer count mismatch|command mismatch)|cmsis-dap command cmd_\w+ failed|libusb_error_busy/`)。
453
463
 
454
464
  ### 7.6 调试三件套与会话租约
455
465
 
@@ -458,8 +468,8 @@ stateDiagram-v2
458
468
  [*] --> 空闲
459
469
  空闲 --> 启动中: stm32_debug_session(start)
460
470
  启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
461
- 启动中 --> 空闲: 端口占用 / 探针失败、带 errorCode 提示
462
- 活跃 --> 活跃: stm32_debug_eval、每次新起 gdb -batch:连上 → halt → 命令 → resume → detach
471
+ 启动中 --> 空闲: 端口占用 / 探针失败、带 probeError(kind / cause / hint)
472
+ 活跃 --> 活跃: stm32_debug_eval、优先常驻 MI(连不上才每次新起 gdb -batch:连上 → halt → 命令 → resume → detach)
463
473
  活跃 --> 空闲: stm32_debug_stop
464
474
  活跃 --> 空闲: 空闲 90 s
465
475
  活跃 --> 空闲: 总时长 10 min
@@ -470,9 +480,15 @@ stateDiagram-v2
470
480
  三条设计理由:
471
481
  1. **只有 openocd 常驻**,gdb 每次短命——gdb 崩了不会把会话带死,也避免 gdb 自己攒一堆状态。
472
482
  2. **归属(A9)**:turn/end 事件里尽量掏 agent id,只关这条会话自己开的;掏不到就全关(宁可按最短释放,也不攥着探针)。
473
- 3. **别人要用探针先 releaseProbeFor**:flash / regs_read / debug_run 都在自己起 openocd 之前调它,否则就是「两个 openocd 抢一个 CMSIS-DAP」。
483
+ 3. **别人要用探针先 releaseProbeFor**:flash / debug_run 在自己起 openocd 之前调它,否则就是「两个 openocd 抢一个 CMSIS-DAP」。**regs_read 是例外(B3 起)**:它反过来复用会话里的那个 openocd,连读时不再一读一起一停。
484
+
485
+ B3 的快路径不是「gdb -batch 跑快一点」,而是绕开 gdb:会话里 openocd 的 Tcl RPC 端口(`debug-session.ts` 的 `parseListeningPorts` 从启动日志的 `Listening on` 行取,`TCL_PORT_SETTLE_MS = 120` 后拿完整缓冲再解析一次,存进 `session.tclPort`;`probe-session.ts` 只消费它)上一条 TCP 连接依次发 halt → `reg pc` → `mdw`×N → resume,帧用 0x1a 分隔(`readWordsViaSession`)。假探针实测:旧的一次性路径 1493 ms/次;新路径起会话 790 ms(第一次含启动),之后 10 连读单次 13–18 ms、总计 154 ms,openocd 进程数 1。没有 tcl 端口或 RPC 失败就回退到会话里的 gdb 并把原因写进 notes。**真机计时还欠着**:现插的 WCH-Link(VID_C251&PID_F001)openocd 0.12 init 直接报 `Error: CMSIS-DAP command CMD_INFO failed`,换回 CMSIS-DAP 探针后跑 `stm32_regs_read` 连读 10 次 0x4001100C 即可复测。
486
+
487
+ B4 的断点预算在同一条 execute 里先算(`resolveBreakpointBudget` 读 .ioc 的 Mcu.CPN → chips.json 的 breakpoints/watchpoints,缺就按 F1 默认 6 硬件断点 / 4 观察点并说明原因),超限在 spawn openocd **之前**就失败——不占探针、也不关你正开着的会话;报告里 `breakpoints` / `watchpoints` 各是 `{used, limit, remaining}`。
488
+
489
+ **debug_run 失败时说什么**(0.1.2 修复):以前只回一句「openocd 起不来」外加日志最后 15 行,真正的原因(adapter init 失败、探针被占)常被后面的噪声挤掉。现在改成和 flash **同一个函数** `classifyProbeFailure`(stage "debug",同一组 kind)归类,hint 也从 probe-error.ts 那一份来,`probeMissingLines` 命中时顺手跑 `usbDiagnosis` 分清「没插 / 没认到 / 驱动异常」,日志改用 `keyLogTail` 挑有信息量的行,`firstProblemLine` 把首条根因写进 errors,kind 不是 unknown 时把 hint 也塞进 notes。
474
490
 
475
- **debug_run 失败时说什么**(0.1.2 修复):以前只回一句「openocd 起不来」外加日志最后 15 行,真正的原因(adapter init 失败、探针被占)常被后面的噪声挤掉。现在先按 flash 同一套 `errorCodeOfLines` 归类,再用 `debugHintFor` 给一条可执行提示,`probeMissingLines` 命中时顺手跑 `usbDiagnosis` 分清「没插 / 没认到 / 驱动异常」,日志改用 `keyLogTail` 挑有信息量的行,`firstProblemLine` 把首条根因写进 errors。报告里的 `errorCode` 是**可选字段**(成功时不出现),且必须在 tools/debug.ts 的 reportSchema 里声明——漏声明就会重演 flash 那次「失败路径被判非法输出」。
491
+ 报告里的 `probeError` 是**结构化对象**(`kind` / `cause` / `hint` / `evidence` / `retryable`),由 `PROBE_ERROR_SCHEMA` 声明(additionalProperties:false、五个字段 required)。注意一个宿主层细节:引擎在成功路径上给的是 `null`,而宿主 schema 不接受 null——所以 tools/flash.ts 与 tools/debug.ts 最后都过一遍 `flashReportForHost` / `debugReportForHost`,把 null 摘掉,让「成功时字段不出现」这件事真的成立。漏这一步就会重演 flash 那次「失败路径被判非法输出」。
476
492
 
477
493
  ### 7.7 .ioc 事务:plan → 用户确认 → apply / rollback
478
494
 
@@ -662,6 +678,7 @@ flowchart LR
662
678
  | 20 | 零运行时依赖、lib/ 入库 | 装上就坏 / 用户机器没有编译器 | package.json、tsconfig |
663
679
  | 21 | cmake 源清单必须跟着 startup 与 hal_conf 走 | 开了外设也链接失败(undefined reference to HAL_xxx_Init) | cmake-sources.refreshCubemxCmakeLists、generate.ts 两处调用 |
664
680
  | 22 | 链接脚本按 `<DeviceId>` 命名,命令行上只能有一个 `-T` | 链接的是别人的 MEMORY:编译过、烧到小容量芯片上跑飞(.ld 说 256 KiB,实际只有 64 KiB) | hal-chip.pointLinkerFlagAt、register-linker.renderLinkerScript、doctor.checkChipConsistency ①③ |
681
+ | 23 | 寄存器名字只能来自 SVD,插件不许内置寄存器表 | 手写表必然过期:偏移错一位就解释错位域,比不给名字更糟 | data/svd.ts(严格解析 + 整份拒绝)、test/svd-units |
665
682
 
666
683
  ## 9. 测试体系
667
684
 
@@ -669,15 +686,15 @@ flowchart LR
669
686
 
670
687
  | 层 | 位置 | 说明 |
671
688
  | --- | --- | --- |
672
- | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 29 个套件 418 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
689
+ | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 41 个套件 654 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
673
690
  | e2e 脚本 | test/e2e-*.mjs(15 个) | 开发期手动跑的端到端(真 CubeMX / 真 openocd / 真工具链),不进 npm test |
674
- | 发布形态 | 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 上两连跑 |
675
692
 
676
- ### 9.2 29 个套件一览(test/run-units.mjs 的 suites 数组顺序)
693
+ ### 9.2 41 个套件一览(test/run-units.mjs 的 suites 数组顺序)
677
694
 
678
- build-units、cache-units、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、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。
679
696
 
680
- 开发机上 418 例全跑;CI 上是 **416 pass + 2 skipped**(两条用例依赖本机路径)。
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。
681
698
 
682
699
  约定:
683
700
  - 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
@@ -706,16 +723,19 @@ const fake = {
706
723
  | --- | --- | --- |
707
724
  | 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
708
725
  | 改报告字段 | src/tools/<x>.ts 的 reportSchema + 渲染 | schema-guard 必须有对应断言 |
709
- | 加芯片族(F4/G0…) | src/data/cmsis-sources.ts(启动文件与宏)、firmware-packages.ts(FIRMWARE_FAMILIES 的仓库名要 curl 核实)、data/chips.ts(引脚表可交给 deriveChipPinTable 从 db 派生)、再补一份 clock-f1 那样的时钟上限表(否则寄存器版只能不出 clock_init) | 仓库名不能猜;sha256 逐文件实测并把来源 URL 记进表里(F1 的 14 条就是这么来的) |
710
- | 加芯片型号(同族容量档) | src/data/stm32f1.ts(容量档与引脚数)→ src/engine/hal-chip.ts(渲染启动文件/宏/.ld/.ioc)→ register-template.ts / register-linker.ts / register-clock.ts | 三条路都要试:HAL 建工程、寄存器建工程、doctor 一致性;stm32f1-units / hal-route-units / doctor-chip-units 会红 |
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 一致性 |
711
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」「超限一个键都不写」;派生键必须全量重算 |
712
- | 更新芯片薄表 | `node scripts/gen-chip-table.mjs` 重跑 → src/data/chip-table.json 更新 | 生成物不要手改;`--check` 给 CI;读不到 CubeMX db 时必须报错退出而不是写半截文件 |
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/`,与内置资源同构 |
713
730
  | 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
714
731
  | 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
715
732
  | 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
716
733
  | 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
717
- | 给工具加错误码 | engine/flash.ts 的 `errorCodeOfLines` 与 `FlashErrorCode`(debug_run 复用同一枚举) | 三个地方同改:engine 归类、reportSchema 声明、schema-guard 用例 |
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 |
718
735
  | 改 cmake 源清单的认法(设备宏、startup、HAL 模块) | engine/cmake-sources.ts 的 `collectCmakeSources` / `halModulesInUse` | 注释掉的 `#define` 与 `#include` 不能算启用;内容没变必须零写入(cmake-sources-units 15 例兜这两条) |
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) |
737
+ | 改寄存器写法的解析或位域解释 | `src/data/svd.ts`(符号解析 / 反向查 / 解码)+ `src/tools/regs.ts`(五种写法、去重、dump、渲染、建议文案) | `svd-units` 39 例兜着;夹具在 `test/fixtures/svd/`(flat / versioned / badline 三种布局);改渲染要同步两份 README 与 development-notes §31 |
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,升级后自动失效 |
719
739
  | 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
720
740
 
721
741
  ## 11. 已知的坑与未做的事
@@ -723,15 +743,18 @@ const fake = {
723
743
  1. **只有 F1 在 FIRMWARE_FAMILIES**:其他族要接入必须先核实真实仓库名(stm32g4xx-hal-driver 之类),不能照 F1 改字母。
724
744
  2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
725
745
  3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
726
- 4. **四种 errorCode 只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验。
727
- 5. **P2(多芯片 + HAL 外设源文件按需落位)与 P3(gdb MI 常驻)** 未开工。
728
- 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 个文件。
746
+ 4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
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 个文件。
729
749
  7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
730
750
  8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
731
751
  9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
732
752
  10. **裸 `cmake -S . -B build` 会丢工具链文件**:工具链只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不走 preset 就得自己给 `-DCMAKE_TOOLCHAIN_FILE`,否则 configure 用宿主 gcc、链接时找不到启动文件。
733
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 时才退回文件大小并注明是粗算。
734
754
  12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
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`。
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。
735
758
 
736
759
  ---
737
760
 
package/lib/data/chips.js CHANGED
@@ -1,47 +1,44 @@
1
1
  /**
2
- * L1:芯片型号 → 可用引脚表。
2
+ * L1:引脚名合法性 + 由本机 CubeMX db 派生的引脚表。
3
3
  *
4
- * 两条来源,优先本机 CubeMX 的数据库:
5
- * 1. `<CubeMX 安装根>/db/mcu/<Mcu.Name>.xml` 里的 `<Pin Name="PA1" Position="3"/>`——
6
- * Position>0 才是真实封装引脚(Position=0 是虚拟引脚,例如 VP_SYS_VS_Systick 的占位)。
7
- * 名字常带功能后缀(`PA0-WKUP`、`PC13-TAMPER-RTC`、`PD0-OSC_IN`),这里归一化成 PA0/PC13/PD0。
8
- * 2. 内置表(CHIPS):机器上没装 CubeMX 时兜底,能跑但**没有跟本机 db 校验过**,
9
- * deriveChipPinTable 会在 notes 里把这件事说清楚。
4
+ * 用户 2026-10-31「内置表删了吧」之后,这里**不再有任何内置芯片/引脚表**(原来的 CHIPS / KNOWN_CHIPS /
5
+ * findChip 已删)。原因:芯片事实的唯一来源是内置资源 device/f1/chips.json,而那份文件只有 pinCount
6
+ * (封装上有多少根脚),没有「这个封装有哪几根 GPIO」的清单——拿 pinCount 去猜 PA0-PB15… 等于又造一张表。
10
7
  *
11
- * 放行语义(从第一天就在,不能变):isKnownPin 只认内置表;未知型号、虚拟引脚(VP_*)一律 true。
12
- * 校验是为了拦住手误,不是为了当数据源;没校验过的东西绝不当"不存在"。
8
+ * 于是分工变成:
9
+ * 1. isKnownPin(pin):只校验**引脚名**是不是 STM32 的合法名(P + A..K + 0..15,虚拟引脚 VP_* 恒放行)。
10
+ * 它拦的是手误(PA99、PZ9、PA-1),不再假装知道某个封装有没有这根脚。
11
+ * 2. deriveChipPinTable():引脚**存在性**只认本机 CubeMX 的 db/mcu XML
12
+ * (<Pin Name="PA1" Position="3"/>,Position>0 才是真实封装引脚)。本机没装 CubeMX / 没有这个 XML 时
13
+ * kind="unknown",notes 里明说「没校验」,绝不拿猜测冒充实测。
14
+ *
15
+ * 放行语义(从第一天就在,不能变):没把握的一律当「不是不存在」,只拦一定写错的东西。
13
16
  */
14
17
  import { existsSync, readFileSync } from "node:fs";
15
18
  import { join } from "node:path";
16
- function port(prefix, from, to) {
17
- const out = [];
18
- for (let index = from; index <= to; index += 1)
19
- out.push(prefix + String(index));
20
- return out;
21
- }
22
- const CHIPS = [
23
- {
24
- cpn: "STM32F103C8T6",
25
- // LQFP48:PA0-15、PB0-15、PC13-15、PD0-1(PD0/PD1 默认是 OSC_IN/OSC_OUT)。
26
- pins: [...port("PA", 0, 15), ...port("PB", 0, 15), "PC13", "PC14", "PC15", "PD0", "PD1"],
27
- flashBytes: 64 * 1024,
28
- ramBytes: 20 * 1024,
29
- },
30
- ];
31
- export function findChip(cpn) {
32
- const wanted = cpn.trim().toUpperCase();
33
- return CHIPS.find((chip) => chip.cpn.toUpperCase() === wanted) ?? null;
34
- }
35
- /** 引脚名是否属于该型号;未知型号或虚拟引脚(VP_*)一律放行。 */
36
- export function isKnownPin(cpn, pin) {
37
- if (pin.startsWith("VP_"))
19
+ /** STM32 的 GPIO 引脚名:PA0..PK15。F1 只用到 A..E,这里按族上界放到 K。 */
20
+ const PIN_NAME = /^P([A-K])(\d{1,2})$/u;
21
+ /** 每个端口最多 16 根(0..15);再大的一定是写错了。 */
22
+ const MAX_PIN_NUMBER = 15;
23
+ /**
24
+ * 引脚名是否合法(未知/虚拟引脚一律放行)。
25
+ *
26
+ * 为什么不再按型号判「有没有这根脚」:那需要「封装 → 引脚清单」的事实,而内置资源只给了 pinCount。
27
+ * 真正的引脚存在性请用 deriveChipPinTable(本机 CubeMX db)——它给的是实测清单,不是符号表。
28
+ */
29
+ export function isKnownPin(pin) {
30
+ const raw = pin.trim().toUpperCase();
31
+ if (raw === "")
38
32
  return true;
39
- const chip = findChip(cpn);
40
- if (chip === null)
33
+ if (raw.startsWith("VP_"))
41
34
  return true;
42
- return chip.pins.includes(pin.toUpperCase());
35
+ // .ioc 里同一根脚会带功能后缀(PA0-WKUP / PC13-TAMPER-RTC),比较时只看引脚名本身。
36
+ const name = (raw.split(/[-/]/u)[0] ?? "").trim();
37
+ const matched = PIN_NAME.exec(name);
38
+ if (matched === null)
39
+ return false;
40
+ return Number.parseInt(matched[2] ?? "", 10) <= MAX_PIN_NUMBER;
43
41
  }
44
- export const KNOWN_CHIPS = CHIPS;
45
42
  // ── 本机 CubeMX db/mcu 派生 ─────────────────────────────────────────────────
46
43
  /** db 里 Pin 的 Name 形如 `PA0-WKUP` / `PC13-TAMPER-RTC` / `PD0-OSC_IN` / `PA13` / `VDD_1`。 */
47
44
  function normalizeDbPinName(raw) {
@@ -113,16 +110,16 @@ export function readMcuDbPins(dbMcuDir, names) {
113
110
  return { xmlPath, pins };
114
111
  }
115
112
  catch {
116
- // 读不了/不是合法 db:退回内置表,notes 里会说明没校验。
113
+ // 读不了/不是合法 db:当作没有 db,notes 里会说明没校验。
117
114
  }
118
115
  }
119
116
  return null;
120
117
  }
121
118
  /**
122
- * 型号 → 引脚表(db 优先,退回内置表)。
119
+ * 型号 → 引脚表(只认本机 CubeMX db)。
123
120
  *
124
- * "没校验"这件事必须写进 notes:内置表只收了 C8T6 一款,别的型号拿它当"真实引脚"会误判,
125
- * 所以内置表路径只说"这里是内置表,未与本机 db 校验",不假装校验过。
121
+ * "没校验"这件事必须写进 notes:没有 db 就没有任何引脚存在性事实,此时 pins 是空的、kind=unknown,
122
+ * 报告里要说清「没校验」,而不是让上层以为「这个型号没有引脚」。
126
123
  */
127
124
  export function deriveChipPinTable(input) {
128
125
  const cpn = input.cpn.trim();
@@ -140,27 +137,17 @@ export function deriveChipPinTable(input) {
140
137
  ],
141
138
  };
142
139
  }
143
- const builtin = findChip(cpn);
144
140
  const why = input.dbMcuDir === null || input.dbMcuDir === undefined
145
141
  ? "本机没找到 CubeMX 的 db/mcu"
146
142
  : "db/mcu 下没有 " + (names.length === 0 ? "该型号" : names.join(" / ")) + ".xml";
147
- if (builtin !== null) {
148
- return {
149
- kind: "builtin",
150
- cpn,
151
- mcuName,
152
- pins: builtin.pins,
153
- notes: ["引脚表:内置表(" + String(builtin.pins.length) + " 个引脚,未与本机 db 校验:" + why + ")"],
154
- };
155
- }
156
143
  return {
157
144
  kind: "unknown",
158
145
  cpn,
159
146
  mcuName,
160
147
  pins: [],
161
148
  notes: [
162
- "引脚表:型号 " + (cpn === "" ? "(空)" : cpn) + " 不在内置表,也没有本机 CubeMX db(未与本机 db 校验:" + why +
163
- ");未知引脚一律放行(isKnownPin 语义不变)",
149
+ "引脚表:没有本机 CubeMX db(" + why + "),引脚存在性不校验(isKnownPin 只查引脚名是否合法);" +
150
+ "插件不内置引脚表(内置资源里也不再有 db 副本),需要逐脚校验就装 CubeMX —— 插件直接读它的 db/mcu",
164
151
  ],
165
152
  };
166
153
  }