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
@@ -17,46 +17,122 @@ import { findIocFile } from "./generate.js";
17
17
  import { summarizeIoc } from "./ioc.js";
18
18
  import { buildTargets, probeAll } from "./probe.js";
19
19
  import { runCapture } from "./subprocess-runner.js";
20
+ /** ST-LINK 全系 VID_0483 的这些 PID(openocd interface/stlink.cfg 的 hla_vid_pid 实测同一张表)。 */
21
+ const STLINK_PIDS = new Set(["3744", "3748", "374b", "374d", "374e", "374f", "3752", "3753", "3754"]);
22
+ /** DAPLink 系(板载探针常以 CMSIS-DAP 名义枚举,openocd 却走 cmsis-dap.cfg)。 */
23
+ const DAPLINK_PIDS = new Set(["f111"]);
20
24
  /**
21
- * 解析 `pnputil /enum-devices /connected` 的输出,回答"这台机器上 USB 是什么形态"。
22
- *
23
- * 为什么要分级:云服务器(阿里云 ECS)物理上没有 USB 口,无论用户怎么插线都进不来探针;
24
- * 这和"没插板 / 线只供电 / 驱动没装 / 被占"是四种完全不同的回答,混成一句"找不到探针"
25
- * 会让用户白折腾。诊断只读、失败不阻塞(unknown 也会给一句手查指引)。
25
+ * SEGGER 的 USB VID(J-Link / J-Trace 全系共用,PID 随型号变:靠 VID 认,不列举 PID)。
26
+ * openocd 的 interface/jlink.cfg 只有 `adapter driver jlink`——没有 vid_pid 表、也不选 transport,
27
+ * 所以 J-Link 必须由调用方追加 `-c "transport select swd"`(否则默认 jtag,SWD 目标连不上)。
28
+ */
29
+ const SEGGER_VID = "1366";
30
+ /**
31
+ * 从 pnputil 输出解析所有 USB 设备的 VID:PID 并分类。
32
+ * 只依赖 ASCII(USB\VID_xxxx&PID_yyyy),中文系统的本地化字段不参与匹配(历史教训)。
26
33
  */
34
+ export function parseProbeVidPid(text) {
35
+ const out = [];
36
+ const seen = new Set();
37
+ for (const m of text.matchAll(/USB\\VID_([0-9A-Fa-f]{4})&PID_([0-9A-Fa-f]{4})/gi)) {
38
+ const vid = (m[1] ?? "").toLowerCase();
39
+ const pid = (m[2] ?? "").toLowerCase();
40
+ const key = vid + ":" + pid;
41
+ if (seen.has(key))
42
+ continue;
43
+ seen.add(key);
44
+ let kind = "unknown";
45
+ let label = "USB 设备 " + key;
46
+ if (vid === "0483") {
47
+ if (STLINK_PIDS.has(pid)) {
48
+ kind = "st-link";
49
+ label = "ST-Link(VID:PID " + key + ")";
50
+ }
51
+ else {
52
+ kind = "unknown";
53
+ label = "ST 设备 " + key + "(不在 ST-LINK PID 表,多半是串口/DFU)";
54
+ }
55
+ }
56
+ else if (vid === SEGGER_VID) {
57
+ kind = "jlink";
58
+ label = "J-Link(VID:PID " + key + ",SEGGER)";
59
+ }
60
+ else if (vid === "0d28") {
61
+ kind = "cmsis-dap";
62
+ label = "CMSIS-DAP(VID:PID " + key + ")";
63
+ }
64
+ else if (vid === "c251") {
65
+ kind = "daplink";
66
+ label = "DAPLink(VID:PID " + key + ",走 CMSIS-DAP 协议)";
67
+ }
68
+ else if (vid === "1a86") {
69
+ kind = "ch341-serial";
70
+ label = "CH341 串口桥(VID:PID " + key + ",不是 SWD 探针)";
71
+ }
72
+ out.push({ vid, pid, kind, label });
73
+ }
74
+ return out;
75
+ }
76
+ /** 实见探针 → openocd 该用哪个 interface 配置。ST-LINK 优先(官方探针,且 hla 与 cmsis-dap 互斥)。 */
77
+ export function preferredInterfaceConfig(probes) {
78
+ if (probes.some((p) => p.kind === "st-link")) {
79
+ return { cfg: "interface/stlink-dap.cfg", why: "USB 里实见 ST-LINK(0483:37xx);走 dapdirect 而不是 hla——C0/U0 这类新族的 target 脚本用的是 swj-dp.tcl 那一套,hla 会报 transport 不支持" };
80
+ }
81
+ if (probes.some((p) => p.kind === "jlink")) {
82
+ return { cfg: "interface/jlink.cfg", why: "USB 里实见 SEGGER J-Link(1366:xxxx);openocd 的 jlink 驱动默认选 jtag,SWD 目标必须再跟一条 -c \"transport select swd\"" };
83
+ }
84
+ if (probes.some((p) => p.kind === "cmsis-dap" || p.kind === "daplink"))
85
+ return { cfg: "interface/cmsis-dap.cfg", why: "USB 里实见 CMSIS-DAP/DAPLink" };
86
+ return { cfg: "interface/cmsis-dap.cfg", why: "没认出已知探针,维持历史默认 cmsis-dap" };
87
+ }
27
88
  export function diagnoseUsb(pnputilText) {
28
89
  // 不依赖本地化字段名(中文系统的 pnputil 字段名是 GBK,读出来是乱码):
29
90
  // 只要任意一行里出现 USB\VID_、USB\ROOT_HUB、或 VID_xxxx&PID 形态的 USB 实例,
30
- // 就认定这台机器有 USB 控制器/设备;纯 ASCII 部分(USB、VID、PID、ROOT_HUB)不受编码影响。
91
+ // 就认定这台机器有 USB 控制器/设备;纯 ASCII 部分不受编码影响。
31
92
  const hasUsbController = /USB\\(?:VID_|ROOT_HUB|VID\w{4}&PID)/iu.test(pnputilText) ||
32
93
  /\\USB\\/u.test(pnputilText);
33
- // VID 集(2a):CMSIS-DAP 是 ARM 官方 VID 0x0D28;ST-Link 全系 VID_0483;
34
- // DAPLink 是 VID_C251;CH340 串口桥接的国产探针常见 VID_1A86。ASCII 本体不受编码影响。
35
- const hasDap = /CMSIS-DAP|VID_0D28|VID_0483|VID_C251|VID_1A86/iu.test(pnputilText) ||
36
- /\\usb\\vid_(?:0d28|0483|c251|1a86)/iu.test(pnputilText);
94
+ const probes = parseProbeVidPid(pnputilText);
95
+ const swdProbes = probes.filter((p) => p.kind === "st-link" || p.kind === "jlink" || p.kind === "cmsis-dap" || p.kind === "daplink");
96
+ // CH341/CH340 串口桥:2a 扩表的历史契约——"板载探针走串口透传"的形态真实存在,算在线;
97
+ // 但它不是 SWD 驱动,不参与 interface 选择(preferredInterfaceConfig 也不认它)。
98
+ const serialBridges = probes.filter((p) => p.kind === "ch341-serial");
37
99
  const hasDriverProblem = /(?:Problem Code|问题代码)\s*[::]?\s*(?:1[0-9]|2[0-8]|3[0-9]|4[0-3]|5[0-2])/iu.test(pnputilText);
100
+ const list = swdProbes.map((p) => p.label).join("、");
38
101
  if (!hasUsbController) {
39
102
  return {
40
103
  kind: "no-usb",
104
+ probes,
41
105
  detail: "系统里枚举不到任何 USB 控制器:这台机器多半是云服务器/虚拟机,物理上没有 USB 口," +
42
106
  "插线、换线、装驱动都解决不了。要么换一台有 USB 的物理机,要么用 USB over IP(usbipd/USBIP)把探针从别的机器转发过来" +
43
107
  "(注意 SWD 对延迟敏感,转发方案只建议实验用)。",
44
108
  };
45
109
  }
46
- if (hasDap && hasDriverProblem) {
110
+ if ((swdProbes.length > 0 || serialBridges.length > 0) && hasDriverProblem) {
47
111
  return {
48
112
  kind: "driver-error",
49
- detail: "能看到 CMSIS-DAP 设备但驱动状态异常(Problem Code 非 0):在设备管理器里找到该设备," +
50
- "重装或回退驱动(CMSIS-DAP 用 WinUSB/HID 通用驱动即可;装过 DAPLink 官方驱动的先卸载它)。",
113
+ probes,
114
+ detail: "能看到探针/桥设备(" + (list || serialBridges.map((p) => p.label).join("、")) + ")但驱动状态异常(Problem Code 非 0):设备管理器里重装/回退驱动(CMSIS-DAP 与 ST-Link 走 WinUSB/HID 通用驱动即可)。",
51
115
  };
52
116
  }
53
- if (hasDap) {
54
- return { kind: "ok", detail: "能看到 CMSIS-DAP 设备且驱动正常:探针在线,烧录/调试应当能直接找到它。" };
117
+ if (swdProbes.length > 0) {
118
+ // 文案必须报出具体类型:ST-Link 说成 CMSIS-DAP 会让人写错 openocd interface(2026-11-08 实测教训)
119
+ const iface = preferredInterfaceConfig(swdProbes);
120
+ return { kind: "ok", probes, detail: "探针在线:" + list + ";openocd 应用 " + iface.cfg + "。" };
121
+ }
122
+ if (serialBridges.length > 0) {
123
+ return {
124
+ kind: "ok",
125
+ probes,
126
+ detail: "USB 里只有串口桥(" + serialBridges.map((p) => p.label).join("、") + "):串口烧录/bootloader 通路可用;" +
127
+ "若指望 SWD,需要探针本身(ST-LINK / J-Link / CMSIS-DAP / DAPLink)出现在枚举里,或板载 DAP 的 USB 口接好。",
128
+ };
55
129
  }
56
130
  return {
57
131
  kind: "no-dap",
58
- detail: "有 USB 控制器但没看到常见探针(CMSIS-DAP / ST-Link / DAPLink / CH340 桥接):检查探针有没有插好(有的线只能供电不能传数据)、" +
59
- "板上调试器的跳线/开关位置、以及 BOOT0 是否接错(BOOT0=1 会进系统 bootloader,SWD 不响应)。",
132
+ probes,
133
+ detail: "有 USB 控制器但没看到 SWD 探针(ST-LINK 0483:3744-54 / J-Link 1366 / CMSIS-DAP 0D28 / DAPLink C251)" +
134
+ (probes.length > 0 ? ";看到的其他 USB 设备:" + probes.map((p) => p.label).join("、") : "") +
135
+ ":检查探针有没有插好(有的线只能供电不能传数据)、板上调试器的跳线/开关位置、以及 BOOT0 是否接错(BOOT0=1 会进系统 bootloader,SWD 不响应)。",
60
136
  };
61
137
  }
62
138
  export async function usbDiagnosis(subprocess, signal) {
@@ -71,6 +147,7 @@ export async function usbDiagnosis(subprocess, signal) {
71
147
  if (outcome.spawnError !== null || outcome.exitCode !== 0) {
72
148
  return {
73
149
  kind: "unknown",
150
+ probes: [],
74
151
  detail: "跑不了 pnputil /enum-devices(" +
75
152
  (outcome.spawnError !== null ? outcome.spawnError : "退出码 " + String(outcome.exitCode)) +
76
153
  "),无法判断 USB/探针形态;可在设备管理器里人工核对。",
@@ -81,10 +158,70 @@ export async function usbDiagnosis(subprocess, signal) {
81
158
  catch (error) {
82
159
  return {
83
160
  kind: "unknown",
161
+ probes: [],
84
162
  detail: "USB/探针诊断异常终止(" + (error instanceof Error ? error.message : String(error)) + "),可忽略;设备管理器里人工核对。",
85
163
  };
86
164
  }
87
165
  }
166
+ /**
167
+ * 引擎各处(flash / debug / regs / 会话)兜底 interface 的统一入口。
168
+ *
169
+ * 刻意**不做模块级缓存**:第一版把 60 s 的结果缓存在模块里,同进程连烧两颗不同芯片时
170
+ * 第二颗会拿到第一颗的探针结论(重试方向还会因此算反),测试里表现为用例互相污染。
171
+ * 现在一次工具调用只探一次(调用方自己复用返回值),跨调用永远重新看。
172
+ */
173
+ export async function liveProbeChoice(subprocess, signal) {
174
+ const usb = await usbDiagnosis(subprocess, signal);
175
+ const swd = usb.probes.filter((p) => p.kind === "st-link" || p.kind === "jlink" || p.kind === "cmsis-dap" || p.kind === "daplink");
176
+ const pref = preferredInterfaceConfig(swd);
177
+ return { ...pref, probes: usb.probes, swdProbes: swd };
178
+ }
179
+ /**
180
+ * interface 配置决定的额外 openocd 参数(插在 interface 与 target 之间)。
181
+ *
182
+ * 只有 J-Link 需要:interface/jlink.cfg 不选 transport,openocd 会默认 jtag,
183
+ * 结果是「No J-Link device found」或者连上了却读不到 SWD 目标。其余 interface
184
+ * 自带 transport(cmsis-dap 走 dapdirect_swd、stlink-dap 同理),多写一条反而报错。
185
+ */
186
+ export function openocdTransportArgs(interfaceConfig) {
187
+ return /jlink/iu.test(interfaceConfig) ? ["-c", "transport select swd"] : [];
188
+ }
189
+ export function capabilitiesOf(tools) {
190
+ const found = new Set(tools.filter((tool) => tool.found).map((tool) => tool.id));
191
+ const has = (id) => found.has(id);
192
+ return {
193
+ build: has("gcc") && has("cmake") && has("ninja"),
194
+ flash: has("openocd"),
195
+ debug: has("openocd") && has("gdb"),
196
+ generate: has("cubemx") && has("cubemx-java"),
197
+ };
198
+ }
199
+ export function recommendationsOf(tools, missingRequired, capabilities) {
200
+ const lines = [];
201
+ const missing = tools.filter((tool) => tool.required && !tool.found);
202
+ if (missing.length === 0) {
203
+ lines.push("必需组件齐全:" + (capabilities.build ? "可以编译" : "但编译还缺组件") + "、" +
204
+ (capabilities.flash ? "可以只烧录" : "烧录还缺 openocd") + "、" +
205
+ (capabilities.debug ? "可以烧录并调试" : "调试还缺 gdb") + "。");
206
+ }
207
+ else {
208
+ lines.push("缺 " + missingRequired.join("、") + "。按下面的顺序装,装一项就少一项:");
209
+ for (const item of missing) {
210
+ const step = item.install[0] ?? item.hint;
211
+ lines.push(item.label + ":" + step + "(自检:" + item.verify + ")");
212
+ }
213
+ lines.push("需要我帮你装吗?回一句「装 gcc」「装 openocd」或「把缺的都装上」,我就照上面的命令在这台机器上装,装完再跑一次 stm32_doctor 复测;你也可以自己装完再跑一次。");
214
+ }
215
+ const cubeMx = tools.find((item) => item.id === "cubemx");
216
+ const cubeMxJava = tools.find((item) => item.id === "cubemx-java");
217
+ if (cubeMx !== undefined && !cubeMx.found) {
218
+ lines.push("CubeMX 是可选的:不影响编译、烧录、调试和改 USER CODE,只影响建工程(stm32_project_create)与改 .ioc 后的重新生成(stm32_generate)。要建工程时再装,步骤见上面 cubemx / cubemx-java 两条。");
219
+ }
220
+ else if (cubeMx !== undefined && cubeMx.found && cubeMxJava !== undefined && !cubeMxJava.found) {
221
+ lines.push("CubeMX 装上了但找不到内置 JRE:无头生成(stm32_generate / stm32_project_create)会失败,建议用官网安装包重装一次(只拷 exe 不够)。");
222
+ }
223
+ return lines;
224
+ }
88
225
  /** 会占着探针/端口的进程名(小写比较)。 */
89
226
  const PROBE_PROCESS_NAMES = ["openocd.exe", "gdb-multiarch.exe", "arm-none-eabi-gdb.exe", "stm32cubemx.exe"];
90
227
  /** 解析 `tasklist /NH /FO CSV` 的输出,只留下关心的进程。 */
@@ -533,6 +670,12 @@ export async function runDoctor(subprocess, request) {
533
670
  durationMs: Date.now() - startedAt,
534
671
  missingRequired,
535
672
  tools,
673
+ capabilities: capabilitiesOf(tools),
674
+ recommendations: recommendationsOf(tools, missingRequired, capabilitiesOf(tools)),
675
+ searched: [
676
+ "工具链搜索范围:" + describeSearchScope(config.binDirs, "PATH"),
677
+ "CubeMX 搜索范围:" + describeSearchScope(config.cubeMxRoots),
678
+ ],
536
679
  processes,
537
680
  port,
538
681
  portBusy,
@@ -0,0 +1,416 @@
1
+ /**
2
+ * facts 获取自动化:SVD(结构)与 RM(语义载体)的取得与降级。
3
+ *
4
+ * SVD 上游取证(2026-11-07,GitHub API 实测):github.com/modm-io/cmsis-svd-stm32,
5
+ * default_branch=main、261★、未归档、pushed_at=2026-07-09。布局 <族小写>/<LINE>.svd,
6
+ * 例如 stm32c0/STM32C031.svd(API contents 实测:C0 6 份、F1 5 份、L4 16 份、H5 10 份,命名同规则)。
7
+ * 本机 D:/JingYu/STM32/cmsis-svd-stm32 的 origin 就是该仓。
8
+ *
9
+ * 为什么 SVD 不锁 sha256:本机旧快照(e79021a)与 main 当前内容对同名文件已经漂移
10
+ * (STM32C031.svd 两边字节不同),上游每次 "Update STM32 SVD files" 都可能改。
11
+ * 这里用 minBytes + markers 认「是不是 SVD」,把**实际取到**的 sha256 记进 facts.sources:
12
+ * 可追溯,但不作为失败条件。
13
+ *
14
+ * RM 通道(两条,都不猜):
15
+ * · 本机 PDF:--rm-pdf <路径>,只哈希登记,不解析(语义抽取是下一项工作)。
16
+ * · 显式 URL:--rm-url <https 直链>,下载后按 %PDF 特征校验。
17
+ * 不手搓「RM 号 → st.com 长 slug」表:实测 rm0490 长 slug 直链 200(11.5 MB application/pdf)、
18
+ * 短链 rm0490.pdf 404 —— slug 含整篇标题,只能人从官网页面拿,写死进插件就是失真快照。
19
+ * 语义仍来自人工抽取的 rm-facts JSON({doc, items});拿不到就 semantics=0,
20
+ * facts.needs 说明缺什么,工具层(flash 门禁/describeFacts)自动走只读降级。
21
+ *
22
+ * 联网禁止:opts.allowNetwork=false 或环境变量 DSH_STM32_OFFLINE=1 时只走本地,
23
+ * 本地也没有 → 明确失败并把试过的路径写进 attempts。
24
+ */
25
+ import { createHash } from "node:crypto";
26
+ import fs from "node:fs";
27
+ import path from "node:path";
28
+ import { fetchOne } from "./fetch.js";
29
+ import { acquireRmViaSitemap, acquireRmViaStmcu } from "./rm-sources.js";
30
+ import { factsRoot, partToFamilyLine, readFactsFor } from "./facts.js";
31
+ import { loadRmTopics } from "../data/rm-topics.js";
32
+ import { defaultPdfTextBridge } from "./rm-text.js";
33
+ import { extractRmFacts, assembleRmFacts } from "./rm-extract.js";
34
+ /** SVD 上游仓库与引用(实测见文件头)。 */
35
+ export const SVD_REPO = "modm-io/cmsis-svd-stm32";
36
+ export const SVD_REF = "main";
37
+ /** facts 关注的寄存器(RM/SVD 交叉验证启动与调试门禁就用这三个)。 */
38
+ export const FACTS_REGISTERS = ["FLASH_OPTR", "FLASH_ACR", "FLASH_SECR"];
39
+ function nodeText(node, tag) {
40
+ const m = node.match(new RegExp("<" + tag + ">([^<]*)</" + tag + ">"));
41
+ const value = m?.[1] ?? "";
42
+ return value.replace(/\s+/gu, " ").trim();
43
+ }
44
+ /**
45
+ * 从 SVD XML 抽 FLASH 外设的寄存器结构(含枚举)。
46
+ *
47
+ * 收集策略两级(2026-11-07 实测教训):
48
+ * A. 首选按外设收:<peripheral> 的 name==FLASH 下的**全部** <register>。
49
+ * modm 的寄存器命名逐族不同——C0 带前缀(FLASH_ACR/FLASH_OPTR/FLASH_SECR)、
50
+ * F1 不带(ACR/OBR/CR…);写死名字清单等于拿 C0 约定套全族,F1 会解析出 0 寄存器
51
+ * (自愈真链路就是这么炸的)。名字清单只是兜底口径,不是主口径。
52
+ * B. 退回全局按 FACTS_REGISTERS 名单过滤:微型片段 SVD 可能没有 peripheral 包装
53
+ * (单测夹具就是那形状)。
54
+ */
55
+ export function parseSvdStructure(xml, registers = FACTS_REGISTERS) {
56
+ const result = {};
57
+ const collectFrom = (chunk, filterByName) => {
58
+ for (const m of chunk.matchAll(/<register>([\s\S]*?)<\/register>/g)) {
59
+ const reg = m?.[1] ?? "";
60
+ const name = nodeText(reg, "name");
61
+ if (name === "")
62
+ continue;
63
+ if (filterByName && !registers.includes(name))
64
+ continue;
65
+ const fields = [];
66
+ for (const fm of reg.matchAll(/<field>([\s\S]*?)<\/field>/g)) {
67
+ const fl = fm?.[1] ?? "";
68
+ const enums = [];
69
+ for (const em of fl.matchAll(/<enumeratedValue>([\s\S]*?)<\/enumeratedValue>/g)) {
70
+ const ebody = em?.[1] ?? "";
71
+ enums.push({ value: nodeText(ebody, "value"), description: nodeText(ebody, "description") });
72
+ }
73
+ fields.push({
74
+ name: nodeText(fl, "name"),
75
+ bitOffset: Number(nodeText(fl, "bitOffset")),
76
+ bitWidth: Number(nodeText(fl, "bitWidth")),
77
+ description: nodeText(fl, "description"),
78
+ enums,
79
+ });
80
+ }
81
+ fields.sort((a, b) => a.bitOffset - b.bitOffset);
82
+ result[name] = { description: nodeText(reg, "description"), fields };
83
+ }
84
+ };
85
+ for (const pm of xml.matchAll(/<peripheral>([\s\S]*?)<\/peripheral>/g)) {
86
+ const block = pm?.[1] ?? "";
87
+ if (nodeText(block, "name").toUpperCase() !== "FLASH")
88
+ continue;
89
+ collectFrom(block, false);
90
+ }
91
+ if (Object.keys(result).length === 0)
92
+ collectFrom(xml, true);
93
+ return result;
94
+ }
95
+ function sha256(buf) {
96
+ return createHash("sha256").update(buf).digest("hex");
97
+ }
98
+ /** SVD 的候选下载 URL,顺序 = 优先级(同 cmsis-sources 的实测结论:jsDelivr 最稳,raw 兜底)。 */
99
+ export function svdSourceUrls(relFile, repo = SVD_REPO, ref = SVD_REF) {
100
+ return [
101
+ "https://fastly.jsdelivr.net/gh/" + repo + "@" + ref + "/" + relFile,
102
+ "https://cdn.jsdelivr.net/gh/" + repo + "@" + ref + "/" + relFile,
103
+ "https://raw.githubusercontent.com/" + repo + "/" + ref + "/" + relFile,
104
+ "https://ghproxy.net/https://raw.githubusercontent.com/" + repo + "/" + ref + "/" + relFile,
105
+ ];
106
+ }
107
+ /** 取一份 SVD:显式路径 → 本地仓库根 → 下载缓存 →(允许时)网络下载。 */
108
+ export async function acquireSvd(part, o = {}) {
109
+ const attempts = [];
110
+ const fail = (error) => ({
111
+ ok: false, file: "", source: "", url: "", sha256: "", bytes: 0, attempts, error, structure: {},
112
+ });
113
+ const target = partToFamilyLine(part);
114
+ if (target === null)
115
+ return fail("认不出型号:" + part);
116
+ const rel = target.family + "/" + target.line + ".svd";
117
+ const env = o.env ?? process.env;
118
+ const cacheDir = o.cacheDir ?? path.join(factsRoot(env), "svd");
119
+ const allowNetwork = o.allowNetwork ?? (env.DSH_STM32_OFFLINE ?? "").trim() !== "1";
120
+ const candidates = [];
121
+ if (o.svdPath !== undefined && o.svdPath !== "")
122
+ candidates.push(path.resolve(o.svdPath));
123
+ for (const root of o.svdRoots ?? [])
124
+ candidates.push(path.join(root, rel));
125
+ candidates.push(path.join(cacheDir, rel));
126
+ for (const cand of candidates) {
127
+ if (!fs.existsSync(cand)) {
128
+ attempts.push(cand + " → 不存在");
129
+ continue;
130
+ }
131
+ const buf = fs.readFileSync(cand);
132
+ const structure = parseSvdStructure(buf.toString("utf8"));
133
+ if (Object.keys(structure).length === 0) {
134
+ attempts.push(cand + " → 找到了但没解析出 " + FACTS_REGISTERS.join("/") + "(不是预期内容)");
135
+ return fail("本地 SVD 内容对不上:" + cand);
136
+ }
137
+ return { ok: true, file: cand, source: "local", url: "", sha256: sha256(buf), bytes: buf.byteLength, attempts, error: "", structure };
138
+ }
139
+ if (!allowNetwork)
140
+ return fail("本地没有该 SVD,且联网被禁(DSH_STM32_OFFLINE)");
141
+ const outcome = await fetchOne({
142
+ path: rel,
143
+ urls: svdSourceUrls(rel),
144
+ minBytes: o.minBytes ?? 50_000,
145
+ // markers 认「是不是 SVD」而不是「是不是某个版本」:上游会漂移,见文件头。
146
+ markers: ["<device", "<cpu>"],
147
+ }, cacheDir, { fetchImpl: o.fetchImpl, timeoutMs: o.timeoutMs ?? 240_000, signal: o.signal });
148
+ for (const a of outcome.attempts)
149
+ attempts.push(a);
150
+ if (!outcome.ok)
151
+ return fail(outcome.error);
152
+ const svdFile = path.join(cacheDir, outcome.path === "" ? rel : outcome.path);
153
+ const buf = fs.readFileSync(svdFile);
154
+ const structure = parseSvdStructure(buf.toString("utf8"));
155
+ if (Object.keys(structure).length === 0)
156
+ return fail("下载内容解析不出 " + FACTS_REGISTERS.join("/") + ":" + outcome.url);
157
+ return {
158
+ ok: true,
159
+ file: svdFile,
160
+ source: "remote",
161
+ url: outcome.url,
162
+ sha256: sha256(buf),
163
+ bytes: buf.byteLength,
164
+ attempts,
165
+ error: "",
166
+ structure,
167
+ };
168
+ }
169
+ /** RM 载体:rm-facts(语义)+ 本机 PDF 或显式 URL(只登记哈希,不解析)。 */
170
+ export async function acquireRm(o = {}) {
171
+ const env = o.env ?? process.env;
172
+ const items = [];
173
+ const sources = [];
174
+ const notes = [];
175
+ let doc = null;
176
+ let error = "";
177
+ if (o.rmFactsPath !== undefined && o.rmFactsPath !== "") {
178
+ try {
179
+ const raw = fs.readFileSync(path.resolve(o.rmFactsPath), "utf8");
180
+ const parsed = JSON.parse(raw);
181
+ doc = parsed.doc ?? null;
182
+ if (Array.isArray(parsed.items))
183
+ items.push(...parsed.items);
184
+ sources.push({ kind: "rm-facts", file: path.basename(o.rmFactsPath), sha256: sha256(Buffer.from(raw, "utf8")), path: path.resolve(o.rmFactsPath) });
185
+ }
186
+ catch (e) {
187
+ error = "rm-facts 读不了(" + o.rmFactsPath + "):" + (e instanceof Error ? e.message : String(e));
188
+ notes.push(error);
189
+ }
190
+ }
191
+ if (o.rmPdfPath !== undefined && o.rmPdfPath !== "") {
192
+ const p = path.resolve(o.rmPdfPath);
193
+ if (fs.existsSync(p)) {
194
+ const buf = fs.readFileSync(p);
195
+ if (!buf.subarray(0, 5).toString("latin1").startsWith("%PDF")) {
196
+ notes.push("rm-pdf 不是 PDF 头(" + p + "),只登记不采信");
197
+ }
198
+ sources.push({ kind: "rm-pdf", file: path.basename(p), sha256: sha256(buf), bytes: buf.byteLength, path: p });
199
+ }
200
+ else {
201
+ notes.push("rm-pdf 不存在:" + p);
202
+ }
203
+ }
204
+ if (o.rmUrl !== undefined && o.rmUrl !== "") {
205
+ const allowNetwork = o.allowNetwork ?? (env.DSH_STM32_OFFLINE ?? "").trim() !== "1";
206
+ if (!allowNetwork) {
207
+ notes.push("rm-url 被跳过(离线模式):" + o.rmUrl);
208
+ }
209
+ else {
210
+ const name = path.basename(new URL(o.rmUrl).pathname);
211
+ const destRoot = o.cacheDir ?? path.join(factsRoot(env), "rm");
212
+ const outcome = await fetchOne({ path: name, urls: [o.rmUrl], minBytes: 200_000, markers: ["%PDF"] }, destRoot, { fetchImpl: o.fetchImpl, timeoutMs: o.timeoutMs ?? 240_000, signal: o.signal, stallMs: 20_000, minBytesPerSec: 4096 });
213
+ if (outcome.ok) {
214
+ const buf = fs.readFileSync(path.join(destRoot, outcome.path));
215
+ sources.push({ kind: "rm-pdf", file: name, sha256: sha256(buf), bytes: buf.byteLength, url: outcome.url });
216
+ notes.push("RM PDF 已缓存:" + path.join(destRoot, outcome.path) + "(" + String(buf.byteLength) + " B)");
217
+ }
218
+ else {
219
+ error = error === "" ? "RM 下载失败:" + outcome.error : error + ";RM 下载失败:" + outcome.error;
220
+ notes.push("RM PDF 下载失败(语义不受影响):" + outcome.error);
221
+ }
222
+ }
223
+ }
224
+ return { items, doc, sources, notes, error };
225
+ }
226
+ /**
227
+ * 完整链路:SVD(本地→下载)+ RM(rm-facts/PDF/URL,可缺)→ facts.json。
228
+ * SVD 拿不到 = 失败(结构是 facts 的底线);RM 拿不到 = 降级(semantics=0 + needs 说明)。
229
+ */
230
+ export async function buildFacts(o) {
231
+ const env = o.env ?? process.env;
232
+ const target = partToFamilyLine(o.part);
233
+ const upper = o.part.trim().toUpperCase();
234
+ if (target === null) {
235
+ return { ok: false, message: "认不出型号:" + o.part, file: "", part: upper, family: "", line: "", structure: {}, registers: "", semantics: 0, needs: ["型号解析失败"], notes: [], sources: [] };
236
+ }
237
+ const svd = await acquireSvd(upper, o);
238
+ if (!svd.ok) {
239
+ return { ok: false, message: svd.error, file: "", part: upper, family: target.family, line: target.line, structure: {}, registers: "", semantics: 0, needs: ["SVD 没拿到(本地与下载都失败)"], notes: svd.attempts, sources: [] };
240
+ }
241
+ const rm = await acquireRm(o);
242
+ const notes = [...rm.notes];
243
+ // 自动载体通道:rm-facts 只给语义,PDF 本体(含哈希/页码定位)由这里补齐。
244
+ const rmAuto = o.rmAuto ?? "auto";
245
+ const allowNet = o.allowNetwork ?? ((o.env ?? process.env).DSH_STM32_OFFLINE ?? "").trim() !== "1";
246
+ let acquired = null;
247
+ if (rmAuto !== "off" && allowNet) {
248
+ const hasPdfSource = rm.sources.some((s) => s.kind === "rm-pdf");
249
+ if (!hasPdfSource) {
250
+ const channelOpts = { fetchImpl: o.fetchImpl, cacheDir: o.rmCacheDir, env, timeoutMs: o.timeoutMs, signal: o.signal, minGapMs: o.minGapMs };
251
+ const order = rmAuto === "sitemap" ? ["sitemap"] : rmAuto === "stmcu" ? ["stmcu"] : ["sitemap", "stmcu"];
252
+ for (const ch of order) {
253
+ const attempt = ch === "sitemap"
254
+ ? await acquireRmViaSitemap(target.family, target.line, channelOpts)
255
+ : await acquireRmViaStmcu(target.family, target.line, channelOpts);
256
+ if (attempt.ok) {
257
+ acquired = attempt;
258
+ break;
259
+ }
260
+ notes.push("RM 自动通道 " + ch + " 失败:" + attempt.error);
261
+ if (attempt.url !== "")
262
+ acquired = attempt; // 失败但也带着哈希/覆盖信息,留给 notes
263
+ }
264
+ }
265
+ }
266
+ const pdfSource = acquired !== null && acquired.ok
267
+ ? { kind: "rm-pdf", doc: acquired.docId, file: acquired.file.split(/[\\/]/).pop() ?? "", path: acquired.file, sha256: acquired.sha256, bytes: acquired.bytes, url: acquired.url, origin: "auto:" + acquired.channel, coveredLines: Object.keys(acquired.coverage) }
268
+ : null;
269
+ // spec 自动抽取:人没喂 rm-facts 而且这颗芯片有主题清单时,用可用的载体 PDF 自动抽取。
270
+ // 载体两种都要认:双通道自动下的,和显式 --rm-pdf/--rm-url 给的(用户本地手册场景)。
271
+ const explicitPdfSource = rm.sources.find((s) => s.kind === "rm-pdf" && typeof s.path === "string" && s.path !== "");
272
+ const explicitPdfPath = typeof explicitPdfSource?.path === "string" ? explicitPdfSource.path : "";
273
+ const specPdf = acquired !== null && acquired.ok ? acquired.file : explicitPdfPath;
274
+ if (rm.items.length === 0 && specPdf !== "" && fs.existsSync(specPdf) && o.autoSpec !== false) {
275
+ const loaded = loadRmTopics(target.family, target.line, factsRoot(env));
276
+ if (loaded.hasSpec) {
277
+ const pageSet = new Set();
278
+ for (const tp of loaded.topics)
279
+ for (let n = Math.max(1, tp.page - 3); n <= tp.page + 3; n += 1)
280
+ pageSet.add(n);
281
+ const bridge = o.pdfTextBridge ?? defaultPdfTextBridge;
282
+ const got = await bridge(specPdf, [...pageSet]);
283
+ if (got.ok) {
284
+ // SVD 交叉要 spec 里每条线的结构;目标线现成,其余线懒取(取不到记「该线 SVD 没取到」,不炸)
285
+ const svdByLine = { [target.line]: svd.structure };
286
+ for (const l of loaded.lines) {
287
+ if (svdByLine[l] !== undefined)
288
+ continue;
289
+ const one = await acquireSvd(l, o);
290
+ if (one.ok)
291
+ svdByLine[l] = one.structure;
292
+ }
293
+ const rep = extractRmFacts({ family: target.family, lines: loaded.lines, topics: loaded.topics }, got.pages, svdByLine);
294
+ const asm = assembleRmFacts({ id: loaded.docId !== "" ? loaded.docId : (acquired?.docId ?? "RM?"), source: "auto:rm-topics", origins: loaded.origins }, rep.items);
295
+ rm.items.push(...asm.items);
296
+ if (rm.doc === null)
297
+ rm.doc = asm.doc;
298
+ notes.push("spec 自动抽取:" + String(rep.items.length) + " 条采信 / " + String(rep.rejected.length) + " 条拒收(清单 " + loaded.origins.join(" + ") + ")");
299
+ for (const x of rep.rejected)
300
+ notes.push(" REJECT " + x.id + ":" + x.reason);
301
+ }
302
+ else {
303
+ notes.push("有 rm-topics 清单但 pymupdf 桥不可用:" + got.error + "(" + got.tried.join(";") + ")");
304
+ }
305
+ }
306
+ }
307
+ // 语义按线分级:声明过的适用范围(--rm-lines 优先,其次 rm-facts 的 doc.lines)
308
+ // 不含目标线时一律拒收,宁可降级只读也不把别的线的 RM 结论套过来。
309
+ const declaredLines = (o.rmLines !== undefined && o.rmLines.length > 0 ? o.rmLines : [])
310
+ .concat(typeof rm.doc?.lines === "string" || Array.isArray(rm.doc?.lines)
311
+ ? (Array.isArray(rm.doc?.lines) ? rm.doc?.lines : [String(rm.doc?.lines)]).map((x) => String(x).toUpperCase())
312
+ : []);
313
+ const uniqueLines = [...new Set(declaredLines)];
314
+ // 采信口径:条目级 appliesTo(自动抽取产出)优先,其次包级 doc.lines,都没有就整批按人声明走。
315
+ let items = rm.items.filter((it) => {
316
+ const ap = Array.isArray(it.appliesTo) ? it.appliesTo.map((x) => String(x).toUpperCase()) : [];
317
+ if (ap.length > 0)
318
+ return ap.includes(target.line);
319
+ // 老式条目(无 appliesTo):仍受包级 doc.lines/--rm-lines 约束——修一个刚引入的回归:
320
+ // 若这里直接放行,「doc.lines 不含目标线」的整批门禁对混合数据就失效了。
321
+ return uniqueLines.length === 0 || uniqueLines.includes(target.line);
322
+ });
323
+ const needs = [];
324
+ const wholeBatchRejected = rm.items.length > 0 && items.length === 0;
325
+ if (wholeBatchRejected && uniqueLines.length > 0 && !uniqueLines.includes(target.line)) {
326
+ needs.push("rm-facts 声明只覆盖 " + uniqueLines.join("/") + ",不含 " + target.line + ":语义 " + String(rm.items.length) + " 条已拒收,需要 " + target.line + " 自己的 RM 抽取");
327
+ items = [];
328
+ }
329
+ else if (wholeBatchRejected) {
330
+ needs.push("rm-facts 里没有任何条目声明适用于 " + target.line + "(appliesTo 逐条筛完为空):需要这条线的 RM 抽取");
331
+ items = [];
332
+ }
333
+ else if (rm.items.length > 0 && uniqueLines.length === 0 && !rm.items.some((it) => Array.isArray(it.appliesTo))) {
334
+ notes.push("提醒:rm-facts 没声明适用线(doc.lines/--rm-lines/条目 appliesTo),本次按目标线 " + target.line + " 原样采信;抽取语义的人要自己核对 RM 是否覆盖该线");
335
+ }
336
+ if (items.length === 0 && rm.items.length === 0) {
337
+ if (acquired !== null && acquired.ok) {
338
+ // 载体已经到位:要么这颗芯片没主题清单(不拦烧录,路径可反查),要么有清单但机检没过。
339
+ const hasSpecHere = loadRmTopics(target.family, target.line, factsRoot(env)).hasSpec;
340
+ needs.push(hasSpecHere
341
+ ? target.line + " 有 rm-topics 清单但机检没过/桥不可用:逐条原因见 notes;修好清单或 PDF 改版前,本线按只读对待"
342
+ : "这颗芯片没有 rm-topics 主题清单:只有结构、无语义(不拦烧录);RM 已缓存在本地,调试遇怪行为可按 sources.rm-pdf 的路径反查原文");
343
+ }
344
+ else {
345
+ needs.push("本线只有结构、语义未核实:需要 " + target.line + " 的 RM 手册与 rm-facts 抽取(SVD 只给结构,不给组合规则/流程/引脚)");
346
+ }
347
+ }
348
+ const outDir = o.outDir !== undefined && o.outDir !== "" ? path.resolve(o.outDir) : path.join(factsRoot(env), target.family, target.line);
349
+ const outFile = path.join(outDir, "facts.json");
350
+ const facts = {
351
+ schema: 2,
352
+ part: upper,
353
+ family: "STM32" + target.family.slice(5).toUpperCase(),
354
+ line: target.line,
355
+ generatedAt: new Date().toISOString(),
356
+ sources: [
357
+ { kind: "svd", file: path.basename(svd.file), sha256: svd.sha256, bytes: svd.bytes, path: svd.file, origin: svd.source === "remote" ? svd.url : "local" },
358
+ ...rm.sources,
359
+ ...(pdfSource === null ? [] : [pdfSource]),
360
+ ],
361
+ registers: svd.structure,
362
+ semantics: items,
363
+ ...(rm.doc === null ? {} : { rmDoc: rm.doc }),
364
+ ...(uniqueLines.length === 0 ? {} : { rmAppliesTo: uniqueLines }),
365
+ needs,
366
+ };
367
+ if (o.write !== false) {
368
+ fs.mkdirSync(outDir, { recursive: true });
369
+ fs.writeFileSync(outFile, JSON.stringify(facts, null, 1), "utf8");
370
+ }
371
+ const regs = Object.entries(svd.structure).map(([k, v]) => k + "(" + String(v.fields.length) + ")").join(" ");
372
+ const svdHow = svd.source === "remote" ? "下载(" + svd.url + ")" : "本地(" + svd.file + ")";
373
+ return {
374
+ ok: true,
375
+ message: "facts -> " + outFile + "(SVD 来自" + svdHow + ";语义 " + String(items.length) + " 条)",
376
+ file: outFile,
377
+ part: upper,
378
+ family: facts.family,
379
+ line: target.line,
380
+ structure: svd.structure,
381
+ registers: regs,
382
+ semantics: items.length,
383
+ needs,
384
+ notes,
385
+ sources: facts.sources,
386
+ };
387
+ }
388
+ /**
389
+ * 自愈读:查到就信,查不到/有清单但没核过就当场补一次书(SVD+RM 载体+结构,
390
+ * 有 rm-topics 还带语义抽取),再读一遍返回。用户决定(2026-11-07):
391
+ * 各族一律自动准备资产、无需人为干预;门禁严格与否由「这颗芯片有没有主题清单」决定。
392
+ *
393
+ * 何时重建:facts 不存在,或有清单但没 verified(常见于用户刚放了芯片级 spec)。
394
+ * 已经 verified 的直接返回,不反复下载。构建失败不炸——返回失败后的现状,
395
+ * 由调用方(flash 门禁/风险行)按三态处理。
396
+ */
397
+ export async function ensureFacts(part, env = process.env, o = {}) {
398
+ const first = readFactsFor(part, env);
399
+ const needsBuild = !first.found || (first.hasSpec && !first.verified);
400
+ if (!needsBuild)
401
+ return { summary: first, built: { attempted: false, ok: true, message: "" } };
402
+ const rep = await buildFacts({
403
+ part,
404
+ env,
405
+ ...(o.timeoutMs === undefined ? {} : { timeoutMs: o.timeoutMs }),
406
+ ...(o.allowNetwork === undefined ? {} : { allowNetwork: o.allowNetwork }),
407
+ ...(o.signal === undefined ? {} : { signal: o.signal }),
408
+ ...(o.fetchImpl === undefined ? {} : { fetchImpl: o.fetchImpl }),
409
+ ...(o.pdfTextBridge === undefined ? {} : { pdfTextBridge: o.pdfTextBridge }),
410
+ ...(o.svdPath === undefined ? {} : { svdPath: o.svdPath }),
411
+ ...(o.svdRoots === undefined ? {} : { svdRoots: o.svdRoots }),
412
+ ...(o.rmPdfPath === undefined ? {} : { rmPdfPath: o.rmPdfPath }),
413
+ });
414
+ const after = readFactsFor(part, env);
415
+ return { summary: after, built: { attempted: true, ok: rep.ok, message: rep.message } };
416
+ }