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
package/lib/engine/ioc.js CHANGED
@@ -9,21 +9,60 @@
9
9
  * 烧录后再也连不上(本项目实测踩过,见规格书 §8)。
10
10
  */
11
11
  const JTAG_SIGNALS = new Set(["SYS_JTMS-SWDIO", "SYS_JTCK-SWCLK", "SYS_JTDI", "SYS_JTDO-SWO", "SYS_NJTRST"]);
12
- /** 解码 CubeMX 在值里写的转义(实测只有 ":")。 */
12
+ /**
13
+ * 解码 CubeMX 写的转义。实测会出现转义的地方:值里的 ":"(NVIC 的 true\:0\:0…)、
14
+ * "#"(ADC1.IPParameters=Rank-0\#ChannelRegularConversion)、键里的空格和括号
15
+ * ("TIM2.Channel-PWM\ Generation1\ CH1"、"PA13\ (JTMS/SWDIO)")。
16
+ */
13
17
  export function decodeIocValue(raw) {
14
- return raw.replace(/\\([:\\])/gu, "$1");
18
+ return raw.replace(/\\(.)/gu, "$1");
19
+ }
20
+ /** 解码键名:键里也会转义(空格、括号、"#"),内存里统一用解码后的形式。 */
21
+ export function decodeIocKey(raw) {
22
+ return raw.replace(/\\(.)/gu, "$1");
23
+ }
24
+ /** 行尾有几个连续反斜杠(Java properties:奇数个 = 续行)。 */
25
+ function trailingBackslashes(line) {
26
+ let count = 0;
27
+ for (let index = line.length - 1; index >= 0 && line[index] === "\\"; index -= 1)
28
+ count += 1;
29
+ return count;
30
+ }
31
+ /**
32
+ * 按 Java properties 的续行规则把物理行合成逻辑行。
33
+ *
34
+ * 为什么需要:官方板级 .ioc 里真的出现过被折断的长值(例如
35
+ * `ProjectManager.functionlistsort=` 的值跨到下一行,形如
36
+ * `…,6-MX_LPUART1` 单独一行)。按物理行解析会把后半截当垃圾行丢掉。
37
+ */
38
+ export function iocLogicalLines(text) {
39
+ const physical = text.split(/\r?\n/u);
40
+ const result = [];
41
+ let index = 0;
42
+ while (index < physical.length) {
43
+ const startIndex = index;
44
+ let line = physical[index];
45
+ index += 1;
46
+ while (trailingBackslashes(line) % 2 === 1 && index < physical.length) {
47
+ line = line.slice(0, -1) + physical[index].trimStart();
48
+ index += 1;
49
+ }
50
+ result.push({ line, startIndex, lineCount: index - startIndex });
51
+ }
52
+ return result;
15
53
  }
16
54
  /** 把 .ioc 文本拆成有序键值对。注释(# 开头)与空行忽略,重复键后者覆盖前者。 */
17
55
  export function parseIocEntries(text) {
18
56
  const entries = new Map();
19
- for (const rawLine of text.split(/\r?\n/u)) {
57
+ for (const item of iocLogicalLines(text)) {
58
+ const rawLine = item.line;
20
59
  const line = rawLine.trim();
21
60
  if (line === "" || line.startsWith("#"))
22
61
  continue;
23
62
  const eq = line.indexOf("=");
24
63
  if (eq <= 0)
25
64
  continue;
26
- entries.set(line.slice(0, eq).trim(), decodeIocValue(line.slice(eq + 1).trim()));
65
+ entries.set(decodeIocKey(line.slice(0, eq).trim()), decodeIocValue(line.slice(eq + 1).trim()));
27
66
  }
28
67
  return entries;
29
68
  }
@@ -1295,7 +1295,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1295
1295
  let cubemxReady = false;
1296
1296
  if (binDir !== "" && existsSync(binDir)) {
1297
1297
  const searchConfig = resolveSearchConfig(env);
1298
- const probeConfig = { binDirs: [binDir], cubeMxRoots: [...searchConfig.cubeMxRoots] };
1298
+ const probeConfig = { binDirs: [binDir], cubeMxRoots: [...searchConfig.cubeMxRoots], cubePrgBins: [] };
1299
1299
  const wanted = buildTargets(probeConfig);
1300
1300
  const probeWanted = wanted.filter((item) => VERIFY_IDS.includes(item.id));
1301
1301
  planProbed = await probeAll(subprocess, probeWanted, probeConfig, {
@@ -1388,7 +1388,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1388
1388
  notes.push(usageNote(facts, download, packages));
1389
1389
  notes.push("这只是计划:没有下载、没有建目录、没有写注册表、没有改配置。");
1390
1390
  const confirmHint = nothingToDo
1391
- ? "已经齐了:直接 stm32_env_probe 看四项能力,或 stm32_build 编译;要换一份 MSYS2 就传 targetDir。"
1391
+ ? "已经齐了:直接 stm32_doctor 看四项能力,或 stm32_build 编译;要换一份 MSYS2 就传 targetDir。"
1392
1392
  : existing && pacmanUnknown
1393
1393
  ? "确认无误就带 confirm:true、dryRun:false 再调一次(真装时会先 pacman -Q,只补缺的包,不升级已装的);想只装指定包就传 packages。"
1394
1394
  : existing
@@ -1776,7 +1776,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1776
1776
  beginStep(steps, verifyStep, request.onProgress);
1777
1777
  if (isAborted(request.signal))
1778
1778
  return abortRest(verifyStep);
1779
- const probeConfig = { binDirs: [binDir], cubeMxRoots: [] };
1779
+ const probeConfig = { binDirs: [binDir], cubeMxRoots: [], cubePrgBins: [] };
1780
1780
  const targets = buildTargets(probeConfig).filter((item) => VERIFY_IDS.includes(item.id));
1781
1781
  const probed = await probeAll(subprocess, targets, probeConfig, {
1782
1782
  timeoutMs: PROBE_TIMEOUT_MS,
@@ -1865,6 +1865,6 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1865
1865
  ? " pacman 那一步的修法:先在 " + msys64 + " 里跑 " + bashLine(msys64, PACMAN_UPGRADE_COMMAND) + "(整体升级),再重调本工具;只同步软件库再补单个包属于局部升级,依赖会解不开。"
1866
1866
  : "");
1867
1867
  return finish(ok, message, ok
1868
- ? "直接重跑你刚才的工具(stm32_build / stm32_flash / stm32_debug_run);也可以用 stm32_env_probe 复看一遍。"
1868
+ ? "直接重跑你刚才的工具(stm32_build / stm32_flash / stm32_debug_run);也可以用 stm32_doctor 复看一遍。"
1869
1869
  : "看 steps 里失败那一步的 detail;修好后重调本工具,已完成的步骤会自动跳过(不会重复下载、不会重复写 PATH)。");
1870
1870
  }
@@ -0,0 +1,231 @@
1
+ /**
2
+ * B2:结构化探针错误 —— flash / debug / session 三条路径共用一份分类。
3
+ *
4
+ * 为什么要有它:2d 的错误码只是一张枚举,失败时模型还得去读中文 message 才知道下一步。
5
+ * 现在一次分类就给全五样东西:
6
+ * - kind:契约字段(模型可以按它分支),旧错误码字段直接删掉,不做兼容别名(用户已定);
7
+ * - cause:一句话根因,给人看也够;
8
+ * - hint:可执行的下一步(四类真机验过的故障各自有专属文案);
9
+ * - evidence:原始日志行,逐字保留,别让模型凭二手转述猜;
10
+ * - retryable:照 hint 弄完再调一次同一个工具有没有意义(true=值得重试)。
11
+ *
12
+ * 归类顺序敏感:先 no-probe 再 probe-busy —— 把"被占用"读成"没插"会让人白拔线。
13
+ * 同一套规则同时服务 flash(openocd program)与 debug(openocd + gdb),改一处两边一起变。
14
+ */
15
+ /** 枚举的运行时形态(工具 schema 的 enum 也用它,避免第二个真相)。 */
16
+ export const PROBE_ERROR_KINDS = [
17
+ "no-probe",
18
+ "probe-interface-mismatch",
19
+ "probe-busy",
20
+ "swd-locked",
21
+ "flash-protected",
22
+ "no-power",
23
+ "target-mismatch",
24
+ "timeout",
25
+ "unknown",
26
+ ];
27
+ // ── 文案:hint 是给用户的下一步,cause 是一句话根因 ────────────────────────────────
28
+ export const HINT_PROBE = "找不到 CMSIS-DAP 探针:检查 USB、是否被 openocd/调试会话占用(先停掉正在跑的调试),必要时换一根数据线再试。";
29
+ export const HINT_BUSY = "探针没有正常响应:先确认没有第二个 openocd / 调试会话在同时用它(两个 openocd 抢同一个 CMSIS-DAP 时不报错,而是满屏 transfer count mismatch);如果确认只有一个进程,那就是探针固件卡住了——把探针拔下来等 3 秒再插回,然后重试。";
30
+ export const HINT_DP = "连不上芯片(Error connecting DP):固件里可能关了 SWD(__HAL_AFIO_REMAP_SWJ_DISABLE),需要 BOOT0=1 重启进系统 bootloader 再烧,或按住复位键在连接瞬间松开。";
31
+ export const HINT_FLASH_PROTECTED = "Flash 被写保护/读保护挡住:先做一次全片擦除(openocd 的 stm32f1x mass_erase)或解除读保护(RDP)再烧;量产片上确实要保持保护时,这次烧录就不可能成功,别再原地重试。";
32
+ export const HINT_NO_POWER = "目标板没供电:量一下 3V3/GND,检查 BOOT0/BOOT1 跳线与杜邦线接触,USB 供电不足时换独立电源再试。";
33
+ export const HINT_TARGET_MISMATCH = "连上的不是目标芯片:openocd 的 target 配置(stm32f1x)与实测 device id 不符——确认板上确实是 STM32F103 系列,或把 .ioc / 芯片型号参数改对再试。";
34
+ export const HINT_TIMEOUT = "超时:目标没在等(断点没命中、程序跑飞)或探针链路太慢——先把 adapter speed 降到 1000 或 100,确认固件真的会跑到断点,再适度加大 timeoutMs 重试。";
35
+ export const HINT_UNKNOWN = "日志里没有能归类的特征:把 evidence 或日志尾部贴出来核对,并用 stm32_doctor 看探针占用与工具链状态,别盲目重试。";
36
+ const HINT_INTERFACE_MISMATCH = "interface 配置与实插探针不匹配:跑 stm32_doctor 看「USB:探针在线(…)」那行报的类型," +
37
+ "把工程 openocd.cfg 里的 interface/ 那行换成对应驱动(ST-Link→interface/stlink.cfg,CMSIS-DAP/DAPLink→interface/cmsis-dap.cfg);" +
38
+ "工程没有 openocd.cfg 时插件会按 doctor 实见类型自动选,不用手写。stm32_flash 遇到本错误也会先换另一个 interface 自动重试一次。";
39
+ const HINT_BY_KIND = {
40
+ "no-probe": HINT_PROBE,
41
+ "probe-interface-mismatch": HINT_INTERFACE_MISMATCH,
42
+ "probe-busy": HINT_BUSY,
43
+ "swd-locked": HINT_DP,
44
+ "flash-protected": HINT_FLASH_PROTECTED,
45
+ "no-power": HINT_NO_POWER,
46
+ "target-mismatch": HINT_TARGET_MISMATCH,
47
+ timeout: HINT_TIMEOUT,
48
+ unknown: HINT_UNKNOWN,
49
+ };
50
+ /**
51
+ * retryable 的判据只有一个:「照 hint 处理完,再调一次同一个工具有没有意义」。
52
+ * 需要换流程/换芯片/改工程配置才能过的,一律 false——否则模型会拿同一条命令空转。
53
+ */
54
+ const RETRYABLE_BY_KIND = {
55
+ "no-probe": true, // 插好线 / 停掉占用就能再烧
56
+ "probe-interface-mismatch": true, // flash 引擎换另一个 interface 自动重试;手写配置时改一行即可
57
+ "probe-busy": true, // 让出探针即可重试
58
+ "swd-locked": true, // 按 hint 用 BOOT0 进 bootloader 后同一条命令能成
59
+ "flash-protected": false, // 要先解保护,不属于"再试一次"
60
+ "no-power": true, // 供电接好就能再烧
61
+ "target-mismatch": false, // 芯片或配置不对,重试只会得到同样的报错
62
+ timeout: true, // 降速/加大超时是有效调整
63
+ unknown: false, // 没有依据,重试等于赌
64
+ };
65
+ const CAUSE_TIMEOUT = {
66
+ flash: "烧录超时:openocd 没在 timeoutMs 内跑完 program",
67
+ debug: "调试超时:gdb 没在 timeoutMs 内命中断点或没能收尾",
68
+ session: "会话超时:openocd 没在超时前开始监听 gdb 端口",
69
+ };
70
+ /**
71
+ * 日志特征表(顺序即优先级):判据全部沿用 2d 的那套正则,一条都没改,
72
+ * 只是从"返回枚举"变成"带根因的有序表"。
73
+ */
74
+ const MATCHERS = [
75
+ {
76
+ // 2026-11-08 实测教训:工程里的 openocd.cfg 写死了 interface/cmsis-dap.cfg,
77
+ // 插的却是 ST-Link(或反是)——这跟"没插"是两种答案:前者换一行配置就好。
78
+ kind: "probe-interface-mismatch",
79
+ cause: "openocd 找不到配置里指定的探针驱动(interface 配置与实插的探针类型不匹配)",
80
+ re: /unable to find a matching (cmsis-dap|stlink|st-link) device/u,
81
+ },
82
+ {
83
+ kind: "no-probe",
84
+ cause: "openocd 找不到探针(没插好 / 被占用 / 本机没认到 USB 设备)",
85
+ re: /no device found|open failed/u,
86
+ },
87
+ {
88
+ kind: "probe-busy",
89
+ cause: "探针被另一个进程攥着(adapter 初始化没抢到)",
90
+ re: /adapter speed could not be limited|target is openocd and must be halted/u,
91
+ },
92
+ {
93
+ // 真板子取证(2026-10-28):两个 openocd 同时抓同一个 CMSIS-DAP 时,openocd 不会报"忙",
94
+ // 而是两边交替收发导致 DAP 事务错位——满屏 transfer count mismatch / command mismatch。
95
+ kind: "probe-busy",
96
+ // 实测两种成因都会落到这里:① 两个 openocd 同时抓探针 → transfer/command mismatch;
97
+ // ② 探针固件卡住(上一次会话被硬杀)→ CMSIS-DAP command CMD_INFO failed,此时没有任何
98
+ // 并发进程,Windows 里 HID 设备状态也正常,只能拔插恢复(2026-10-31 复现两次)。
99
+ cause: "探针没有正常响应(被另一个进程同时访问,或探针固件卡住)",
100
+ re: /cmsis-dap (transfer count mismatch|command mismatch)|cmsis-dap command cmd_\w+ failed|libusb_error_busy/u,
101
+ },
102
+ {
103
+ kind: "swd-locked",
104
+ cause: "芯片侧 SWD 连不上(固件关了调试口 / 调试访问口被锁)",
105
+ re: /error connecting dp|cannot read idr|ap lock|sticky error/u,
106
+ },
107
+ {
108
+ kind: "flash-protected",
109
+ cause: "Flash 被写保护/读保护挡住",
110
+ re: /flash programming|write protected|read protected|memory protected/u,
111
+ },
112
+ {
113
+ kind: "no-power",
114
+ cause: "目标芯片供电不足或没供电",
115
+ re: /target voltage may be too low|no power/u,
116
+ },
117
+ {
118
+ kind: "target-mismatch",
119
+ cause: "连上的芯片 ID 与 target 配置(stm32f1x)不一致",
120
+ // 不要用 `device id` 这种宽词:openocd 正常烧录时也会打 `Info : device id = 0x20036410`,
121
+ // 一命中就会把成功路径误判成型号不符。只认真正的失败措辞(2026-10-31 实测)。
122
+ re: /cannot identify target|unexpected idcode|unknown device|doesn't match the target/u,
123
+ },
124
+ ];
125
+ /** 一条"看起来像根因"的行;只用于 unknown / 超时的 evidence 兜底。 */
126
+ const PROBLEM_LINE_RE = /error|unable to find|no device found|couldn't bind|cannot open|invalid/u;
127
+ const MAX_EVIDENCE = 4;
128
+ function nonEmpty(lines) {
129
+ return lines.filter((line) => line.trim() !== "");
130
+ }
131
+ /** 命中同一特征的所有原始行(逐字保留,去重,最多 MAX_EVIDENCE 条)。 */
132
+ function evidenceOf(lines, re) {
133
+ const kept = [];
134
+ const seen = new Set();
135
+ for (const line of lines) {
136
+ if (!re.test(line.toLowerCase()))
137
+ continue;
138
+ if (seen.has(line))
139
+ continue;
140
+ seen.add(line);
141
+ kept.push(line);
142
+ if (kept.length >= MAX_EVIDENCE)
143
+ break;
144
+ }
145
+ return kept;
146
+ }
147
+ /** 日志里第一条真正说明问题的行(给 message 用,避免只报"起不来")。 */
148
+ export function firstProblemLine(lines) {
149
+ const hit = lines.find((line) => /^Error|unable to find|no device found|couldn't bind|cannot open|invalid/i.test(line));
150
+ return (hit ?? lines[lines.length - 1] ?? "").trim();
151
+ }
152
+ /** openocd 报"找不到设备"的那几行错误行(2a 的判定基准,纯函数便于单测)。 */
153
+ export function probeMissingLines(errors) {
154
+ return errors.filter((line) => /CMSIS-DAP device|no device found/iu.test(line));
155
+ }
156
+ /** USB 形态诊断的结论该以什么 note 呈现(unknown 静默:诊断失败不能把失败报告搞得更吵)。 */
157
+ export function usbNoteFor(kind, detail) {
158
+ if (kind === "unknown")
159
+ return null;
160
+ return "USB 形态:" + detail;
161
+ }
162
+ /** 每一类的默认根因(调用方没给更准的说法时用它,避免出现"未知原因"这种废话)。 */
163
+ const CAUSE_BY_KIND = {
164
+ "no-probe": "找不到探针(没插好 / 被占用 / 本机没认到 USB 设备)",
165
+ "probe-interface-mismatch": "openocd 找不到配置里指定的探针驱动(interface 与实插类型不匹配)",
166
+ "probe-busy": "探针或探针口被另一个进程占着",
167
+ "swd-locked": "芯片侧 SWD 连不上(固件关了调试口 / 调试访问口被锁)",
168
+ "flash-protected": "Flash 被写保护/读保护挡住",
169
+ "no-power": "目标芯片供电不足或没供电",
170
+ "target-mismatch": "连上的芯片 ID 与 target 配置(stm32f1x)不一致",
171
+ timeout: "超时",
172
+ unknown: "有失败但日志特征都不命中,分不出是哪一类原因",
173
+ };
174
+ export function buildProbeError(kind, cause, evidence) {
175
+ return { kind, cause, hint: HINT_BY_KIND[kind], evidence, retryable: RETRYABLE_BY_KIND[kind] };
176
+ }
177
+ /**
178
+ * 直接按类构造一条 ProbeError(B3 端口被占这种"没有 openocd 日志可归类"的场景用)。
179
+ * hint / retryable 仍然只有一份真相:都来自同一张表。
180
+ */
181
+ export function makeProbeError(kind, detail = {}) {
182
+ return buildProbeError(kind, detail.cause ?? CAUSE_BY_KIND[kind], detail.evidence ?? []);
183
+ }
184
+ /**
185
+ * 把一次失败归到 8 类之一(B2 的唯一分类入口)。
186
+ *
187
+ * 判定顺序:日志特征(MATCHERS,先见者优先)→ 超时 → 进程没起来 → unknown。
188
+ * 具体特征优先于超时:既打印了 "Error connecting DP" 又超时的,说"锁片"比说"超时"有用。
189
+ */
190
+ export function classifyProbeFailure(input) {
191
+ const lines = nonEmpty(input.lines);
192
+ for (const matcher of MATCHERS) {
193
+ const evidence = evidenceOf(lines, matcher.re);
194
+ if (evidence.length > 0)
195
+ return buildProbeError(matcher.kind, matcher.cause, evidence);
196
+ }
197
+ if (input.timedOut === true) {
198
+ const timeoutLines = evidenceOf(lines, /timed out|timeout/u);
199
+ const evidence = timeoutLines.length > 0 ? timeoutLines : lines.slice(-1);
200
+ return buildProbeError("timeout", CAUSE_TIMEOUT[input.stage], evidence);
201
+ }
202
+ const spawnError = input.spawnError ?? "";
203
+ if (spawnError.trim() !== "") {
204
+ return buildProbeError("unknown", input.stage === "flash" ? "openocd 启动失败:" + spawnError.trim() : "调试进程启动失败:" + spawnError.trim(), [spawnError.trim()]);
205
+ }
206
+ const problems = evidenceOf(lines, PROBLEM_LINE_RE);
207
+ const evidence = problems.length > 0 ? problems : lines.slice(-MAX_EVIDENCE);
208
+ const exitText = input.exitCode === undefined || input.exitCode === null ? "" : "(退出码 " + String(input.exitCode) + ")";
209
+ return buildProbeError("unknown", "有失败但日志特征都不命中,分不出是哪一类原因" + exitText, evidence);
210
+ }
211
+ /**
212
+ * 工具层 output schema 里的 probeError 片段:flash / debug(以及后续会话)共用同一份,
213
+ * 加一个 kind 只改这里。**不进 required** —— 成功路径引擎给 null,而宿主不接受 null,
214
+ * 工具层会用 flashReportForHost / debugReportForHost 把 null 摘掉再交给宿主。
215
+ */
216
+ export const PROBE_ERROR_SCHEMA = {
217
+ type: "object",
218
+ additionalProperties: false,
219
+ properties: {
220
+ kind: { type: "string", enum: [...PROBE_ERROR_KINDS] },
221
+ cause: { type: "string" },
222
+ hint: { type: "string" },
223
+ evidence: { type: "array", items: { type: "string" } },
224
+ retryable: { type: "boolean" },
225
+ },
226
+ required: ["kind", "cause", "hint", "evidence", "retryable"],
227
+ };
228
+ /** 报告卡片与 errors 摘要统一用这句:「错误:<kind> — <cause>;建议:<hint>」。 */
229
+ export function formatProbeError(error) {
230
+ return "错误:" + error.kind + " — " + error.cause + ";建议:" + error.hint;
231
+ }