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
@@ -0,0 +1,360 @@
1
+ /**
2
+ * RM(参考手册)载体获取:双通道 + 逐线覆盖验证。
3
+ *
4
+ * 取证(2026-11-07 实测,全部零登录匿名):
5
+ * 主通道 = ST 官方 sitemap:https://www.st.com/content/st_com/sitemap{1..10}.xml
6
+ * (37,647 条 <loc>,其中 132 条 /resource/en/reference_manual/*.pdf 直链;
7
+ * RM0490 直链 HEAD 200 application/pdf 11,536,384 B)。slug 含族名
8
+ * (rm0490-stm32c0-series-…),族级匹配可用;不锁「号→URL」表——清单每次从站点现取。
9
+ * 备案通道 = ST 中国官网 stmcu.com.cn:分类页
10
+ * /Designresource/list/<族>/document/reference_manual(200 可解析 detail 链接;
11
+ * 连打 3 次触发 429,必须节流)→ 详情页 /Designresource/detail/document/<id>
12
+ * (匿名 200)→ 内联 JS 里 window.open 的 www.st.com.cn/content/ccc/…/translations/
13
+ * zh.DMxxxxxx.pdf 直链(匿名 200;RM0490 中文实测与你本地那份逐字节同哈希)。
14
+ * stmcu 自己的 design_resource_download token 端点匿名 303 跳 SSO,**不可用**。
15
+ *
16
+ * 覆盖验证:Node 解流抽取(inflate content stream → 拼文本字面量 → 去噪归一化)。
17
+ * EN RM0490 实测命中 BOOT_LOCK/nBOOT_SEL/OPTKEY1/0x08192A3B/DBG_SWEN 与
18
+ * STM32C011xx…STM32C092xx 全部六线(Table 3..6 就是逐线边界地址表)。
19
+ * 中文 PDF 是 CID 编码字体,这个抽取器抽不出线名——所以覆盖判定只信 EN 通道。
20
+ */
21
+ import { createHash } from "node:crypto";
22
+ import fs from "node:fs";
23
+ import path from "node:path";
24
+ import { inflateSync } from "node:zlib";
25
+ import { fetchOne } from "./fetch.js";
26
+ import { factsRoot } from "./facts.js";
27
+ const SITEMAP_BASE = "https://www.st.com/content/st_com/sitemap";
28
+ export const RM_SITEMAP_PAGES = 10;
29
+ function fetchText(url, fetchImpl, timeoutMs) {
30
+ const ac = new AbortController();
31
+ const timer = setTimeout(() => ac.abort(), timeoutMs);
32
+ return fetchImpl(url, { signal: ac.signal, redirect: "follow", headers: { "User-Agent": "dsh-stm32/facts" } })
33
+ .then(async (r) => ({ status: r.status, body: await r.text() }))
34
+ .finally(() => clearTimeout(timer));
35
+ }
36
+ /** 从 sitemap XML 文本抽英文 reference_manual 直链清单(纯函数,可单测)。 */
37
+ export function parseRmSitemap(xml) {
38
+ const out = [];
39
+ for (const m of xml.matchAll(/<loc>(https:\/\/www\.st\.com\/resource\/en\/reference_manual\/[^<]+\.pdf)<\/loc>/g)) {
40
+ const url = m[1] ?? "";
41
+ const slug = url.split("/").pop() ?? "";
42
+ const docId = (slug.match(/rm\d{4}/i) ?? [""])[0].toLowerCase();
43
+ const tokens = [...new Set([...slug.toLowerCase().matchAll(/stm32[a-z0-9]+|cortex[a-z0-9+]+/g)].map((x) => x[0]))];
44
+ out.push({ url, docId, tokens });
45
+ }
46
+ return out;
47
+ }
48
+ /** 抓全 10 张 sitemap 合成 RM 目录。串行、单张失败不炸(记进 errors)。 */
49
+ export async function fetchRmCatalog(o = {}) {
50
+ const fetchImpl = o.fetchImpl ?? fetch;
51
+ const timeoutMs = o.timeoutMs ?? 30_000;
52
+ const pages = o.pages ?? RM_SITEMAP_PAGES;
53
+ const entries = [];
54
+ const errors = [];
55
+ const seen = new Set();
56
+ for (let i = 1; i <= pages; i += 1) {
57
+ try {
58
+ const r = await fetchText(SITEMAP_BASE + String(i) + ".xml", fetchImpl, timeoutMs);
59
+ if (r.status !== 200) {
60
+ errors.push("sitemap" + String(i) + " HTTP " + String(r.status));
61
+ continue;
62
+ }
63
+ for (const e of parseRmSitemap(r.body)) {
64
+ if (seen.has(e.url))
65
+ continue;
66
+ seen.add(e.url);
67
+ entries.push(e);
68
+ }
69
+ }
70
+ catch (error) {
71
+ errors.push("sitemap" + String(i) + " " + (error instanceof Error ? error.message : String(error)));
72
+ }
73
+ }
74
+ return { entries, errors };
75
+ }
76
+ /** 目标线(STM32C051)/族(STM32C0)→ 从目录里选最匹配的 RM;返回候选(按优先级)与落选原因。 */
77
+ export function matchRmForLine(catalog, family, line) {
78
+ const fam = family.toLowerCase(); // stm32c0
79
+ const ln = line.toLowerCase(); // stm32c051
80
+ const lineXx = ln + "xx";
81
+ const famSeries = fam + "-series";
82
+ const scored = catalog
83
+ .filter((e) => e.url.toLowerCase().includes(fam))
84
+ .map((e) => {
85
+ const u = e.url.toLowerCase();
86
+ let score = 0;
87
+ if (u.includes(lineXx))
88
+ score += 100; // slug 直接列了这条线(stm32l41xxx 这类不含 412,走下一层)
89
+ // 线号首位:STM32L412 → stm32l41(slug 写 stm32l41xxx);slice(0,7) 恰好是族名,不能用
90
+ const tail = ln.slice(fam.length).replace(/[^0-9]/gu, "");
91
+ const stem = tail === "" ? "" : fam + tail.charAt(0);
92
+ if (stem !== "" && u.includes(stem))
93
+ score += 60;
94
+ if (u.includes(famSeries))
95
+ score += 40; // 族级 series 手册(rm0490-stm32c0-series)
96
+ if (u.includes(fam))
97
+ score += 20;
98
+ return { e, score };
99
+ })
100
+ .filter((x) => x.score > 0)
101
+ .sort((a, b) => b.score - a.score || a.e.docId.localeCompare(b.e.docId));
102
+ return { picked: scored[0]?.e ?? null, candidates: scored.map(x => x.e) };
103
+ }
104
+ /**
105
+ * 解 PDF content stream 抽文本字面量(Tj/TJ 里的 (…))。自研扫描器而不是正则:
106
+ * 需要区分布局算子插入的负数间距(…) -2457 (… 是大间距→空格)与 kerning 小数
107
+ * ([(a)-5(b)] 是同一个词)。失败退回 latin1 原文(会偏松,但只作为回退)。
108
+ */
109
+ export function extractPdfLatinText(buf) {
110
+ const latin = buf.toString("latin1");
111
+ let hay = "";
112
+ const re = /stream\r?\n?/g;
113
+ let m;
114
+ while ((m = re.exec(latin)) !== null) {
115
+ const start = m.index + m[0].length;
116
+ const stop = latin.indexOf("endstream", start);
117
+ if (stop < 0)
118
+ continue;
119
+ const raw = buf.subarray(start, stop);
120
+ try {
121
+ hay += inflateSync(raw).toString("latin1");
122
+ }
123
+ catch {
124
+ hay += raw.toString("latin1");
125
+ }
126
+ }
127
+ let out = "";
128
+ let i = 0;
129
+ while (i < hay.length) {
130
+ const ch = hay.charCodeAt(i);
131
+ if (ch === 40) {
132
+ i += 1;
133
+ let s = "";
134
+ while (i < hay.length) {
135
+ const c = hay[i];
136
+ if (c === "\\") {
137
+ const nx = hay[i + 1];
138
+ if (nx !== undefined && /[0-7]/.test(nx)) {
139
+ let oct = "";
140
+ let k = i + 1;
141
+ while (k < hay.length && oct.length < 3 && /[0-7]/.test(hay[k] ?? "")) {
142
+ oct += hay[k];
143
+ k += 1;
144
+ }
145
+ s += String.fromCharCode(parseInt(oct, 8));
146
+ i = k;
147
+ continue;
148
+ }
149
+ s += nx ?? "";
150
+ i += 2;
151
+ continue;
152
+ }
153
+ if (c === "(") {
154
+ s += "(";
155
+ i += 1;
156
+ continue;
157
+ }
158
+ if (c === ")") {
159
+ i += 1;
160
+ break;
161
+ }
162
+ s += c;
163
+ i += 1;
164
+ }
165
+ out += s;
166
+ continue;
167
+ }
168
+ // TJ 数组里的元素间距:(str) -578 (str) —— 数字前必须是 ")"、后接 "(" 或 "]"。
169
+ // kerning 小数(±100 以下)与坐标数不置空格;≥200 才当空格。
170
+ if (ch === 45 || ch === 43 || ch === 46 || (ch >= 48 && ch <= 57)) {
171
+ const prev = i > 0 ? hay.charCodeAt(i - 1) : -1;
172
+ if (prev === 41) {
173
+ let j = i;
174
+ if (hay[j] === "-" || hay[j] === "+")
175
+ j += 1;
176
+ const d0 = j;
177
+ while (j < hay.length && hay.charCodeAt(j) >= 48 && hay.charCodeAt(j) <= 57)
178
+ j += 1;
179
+ if (j > d0) {
180
+ const after = j < hay.length ? hay.charCodeAt(j) : -1;
181
+ if (after === 40 || after === 93) {
182
+ const num = Number(hay.slice(i, j));
183
+ if (Number.isFinite(num) && Math.abs(num) >= 200)
184
+ out += " ";
185
+ i = j;
186
+ continue;
187
+ }
188
+ }
189
+ }
190
+ }
191
+ i += 1;
192
+ }
193
+ return out;
194
+ }
195
+ /** 引文回查用的归一化:八位组/括号/反斜杠转义清掉、小写、非字母数字→单空格(保短语与常数)。 */
196
+ export function normalizePdfText(text) {
197
+ return text
198
+ .replace(/\\[nrtbf]/g, " ")
199
+ .replace(/\\[0-7]{1,3}/g, " ")
200
+ .replace(/\\(.)/g, "$1")
201
+ .toLowerCase()
202
+ .replace(/[^a-z0-9]+/g, " ")
203
+ .trim();
204
+ }
205
+ /** 全压平索引(只留字母数字小写):覆盖判定与短语回查的公共底座。 */
206
+ export function pdfCoverageIndex(buf) {
207
+ return normalizePdfText(extractPdfLatinText(buf)).replace(/[^a-z0-9]/g, "");
208
+ }
209
+ /** 线覆盖判定:压平索引里找 <line>xx(STM32C051 → stm32c051xx)。 */
210
+ export function lineCovered(index, line) {
211
+ return index.includes(line.toLowerCase() + "xx");
212
+ }
213
+ /** 节流 + 429 退避的页面抓取(stmcu 连打 3 次就 429,实测)。 */
214
+ async function politeGet(url, o) {
215
+ // 429 是这站的礼貌闸:连打必触发(实测 3 次即 429),所以退避要真等,重试上限 2 次。
216
+ for (let attempt = 0; attempt <= 2; attempt += 1) {
217
+ const wait = attempt === 0 ? o.minGapMs - (Date.now() - o.lastAtRef.t) : o.retryGapMs * attempt;
218
+ if (wait > 0)
219
+ await new Promise((r) => setTimeout(r, wait));
220
+ const ac = new AbortController();
221
+ const timer = setTimeout(() => ac.abort(), o.timeoutMs);
222
+ try {
223
+ const res = await o.fetchImpl(url, { signal: ac.signal, redirect: "follow", headers: { "User-Agent": o.ua, Referer: "https://www.stmcu.com.cn/design_resource" } });
224
+ o.lastAtRef.t = Date.now();
225
+ const body = await res.text();
226
+ if (res.status === 429) {
227
+ if (attempt < 2)
228
+ continue;
229
+ }
230
+ return { status: res.status, body };
231
+ }
232
+ catch (error) {
233
+ o.lastAtRef.t = Date.now();
234
+ if (attempt === 2)
235
+ return null;
236
+ void error;
237
+ }
238
+ finally {
239
+ clearTimeout(timer);
240
+ }
241
+ }
242
+ return null;
243
+ }
244
+ function shaHex(buf) {
245
+ return createHash("sha256").update(buf).digest("hex");
246
+ }
247
+ function baseAcquired() {
248
+ return { ok: false, channel: "", file: "", url: "", docId: "", sha256: "", bytes: 0, coverage: {}, notes: [], error: "" };
249
+ }
250
+ /** 主通道:sitemap 目录 → 族匹配 → 下载 → 覆盖验证。 */
251
+ export async function acquireRmViaSitemap(family, line, o = {}) {
252
+ const base = baseAcquired();
253
+ const fetchImpl = o.fetchImpl ?? fetch;
254
+ const catalog = await fetchRmCatalog({ fetchImpl, timeoutMs: o.timeoutMs ?? 30000 });
255
+ if (catalog.entries.length === 0) {
256
+ return { ...base, error: "sitemap 没拿到任何 reference_manual(网络或站点变了):" + catalog.errors.slice(0, 3).join(";") };
257
+ }
258
+ const matched = matchRmForLine(catalog.entries, family, line);
259
+ const picked = matched.picked;
260
+ if (picked === null) {
261
+ return { ...base, error: "RM 目录里找不到 " + family + " 族(目录 " + String(catalog.entries.length) + " 条,族名不匹配)" };
262
+ }
263
+ if (matched.candidates.length > 1) {
264
+ base.notes.push("族匹配到 " + String(matched.candidates.length) + " 份 RM,按线名具体性选 " + picked.docId.toUpperCase() + "(其余:" + matched.candidates.slice(1, 4).map((c) => c.docId.toUpperCase()).join(",") + ")");
265
+ }
266
+ const cacheDir = o.cacheDir ?? path.join(factsRoot(o.env ?? process.env), "rm");
267
+ const name = picked.docId + ".pdf";
268
+ const outcome = await fetchOne({ path: name, urls: [picked.url], minBytes: 200000, markers: ["%PDF"] }, cacheDir, { fetchImpl, timeoutMs: o.timeoutMs ?? 240000, signal: o.signal, stallMs: 20000, minBytesPerSec: 4096 });
269
+ if (!outcome.ok)
270
+ return { ...base, error: "RM 下载失败(" + picked.docId.toUpperCase() + "):" + outcome.error };
271
+ const file = path.join(cacheDir, name);
272
+ const buf = fs.readFileSync(file);
273
+ const index = pdfCoverageIndex(buf);
274
+ const coverage = {};
275
+ for (const m of index.matchAll(/stm32[a-z]\d{3}xx/g))
276
+ coverage[String(m[0]).toUpperCase()] = true;
277
+ const info = { channel: "sitemap", file, url: picked.url, docId: picked.docId.toUpperCase(), sha256: shaHex(buf), bytes: buf.byteLength, coverage, notes: base.notes };
278
+ if (!lineCovered(index, line)) {
279
+ return { ...base, ...info, error: "下载成功但正文索引里找不到 " + line + "xx——这份 " + picked.docId.toUpperCase() + " 不覆盖该线(中文 CID PDF 也会出现这个结果,所以覆盖判定只信英文通道)" };
280
+ }
281
+ return { ...base, ...info, ok: true, error: "" };
282
+ }
283
+ /** 备案通道:stmcu 分类页 → 详情页 → CCC 直链(zh→en 翻译替换)→ 下载 → 覆盖验证。 */
284
+ export async function acquireRmViaStmcu(family, line, o = {}) {
285
+ const base = baseAcquired();
286
+ const fetchImpl = o.fetchImpl ?? fetch;
287
+ const opts = {
288
+ fetchImpl,
289
+ ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/125 Safari/537.36",
290
+ minGapMs: o.minGapMs ?? 3000,
291
+ retryGapMs: o.minGapMs === undefined ? 8000 : o.minGapMs,
292
+ lastAtRef: { t: 0 },
293
+ timeoutMs: o.timeoutMs ?? 30000,
294
+ };
295
+ const famName = "STM32" + family.slice(5).toUpperCase();
296
+ const cat = await politeGet("https://www.stmcu.com.cn/Designresource/list/" + famName + "/document/reference_manual", opts);
297
+ if (cat === null)
298
+ return { ...base, error: "stmcu 分类页两次都没拿到(网络或限流)" };
299
+ if (cat.status !== 200)
300
+ return { ...base, error: "stmcu 分类页 HTTP " + String(cat.status) + "(连打会 429,需要更长的 minGapMs)" };
301
+ const items = parseStmcuCategory(cat.body).filter((x) => x.title.toUpperCase().includes(famName));
302
+ if (items.length === 0)
303
+ return { ...base, error: "stmcu 分类页里没有 " + famName + " 的 RM(该页混入他族条目,已按标题里的族名筛过)" };
304
+ const cacheDir = o.cacheDir ?? path.join(factsRoot(o.env ?? process.env), "rm");
305
+ const tried = [];
306
+ for (const item of items) {
307
+ const det = await politeGet("https://www.stmcu.com.cn/Designresource/detail/document/" + item.detailId, opts);
308
+ if (det === null || det.status !== 200) {
309
+ tried.push(item.docId + "(detail HTTP " + (det === null ? "n/a" : String(det.status)) + ")");
310
+ continue;
311
+ }
312
+ const d = parseStmcuDetail(det.body);
313
+ if (d.cccUrl === "") {
314
+ // token 端点匿名 303 跳 SSO(实测),没有 CCC 直链就下不动
315
+ tried.push(item.docId + "(页面没有 CCC 直链;token 端点要登录)");
316
+ continue;
317
+ }
318
+ // CCC 直链默认指中文译文:zh. → en. 换英文版(RM0490 实测 200、11,536,384 B)。
319
+ const enUrl = d.cccUrl.replace("/translations/zh.", "/translations/en.");
320
+ const name = item.docId.toLowerCase() + "-stmcu.pdf";
321
+ const outcome = await fetchOne({ path: name, urls: [enUrl, d.cccUrl], minBytes: 200000, markers: ["%PDF"] }, cacheDir, { fetchImpl, timeoutMs: o.timeoutMs ?? 240000, signal: o.signal, stallMs: 20000, minBytesPerSec: 4096 });
322
+ if (!outcome.ok) {
323
+ tried.push(item.docId + "(" + outcome.error.slice(0, 60) + ")");
324
+ continue;
325
+ }
326
+ const file = path.join(cacheDir, name);
327
+ const buf = fs.readFileSync(file);
328
+ const index = pdfCoverageIndex(buf);
329
+ const coverage = {};
330
+ for (const m of index.matchAll(/stm32[a-z]\d{3}xx/g))
331
+ coverage[String(m[0]).toUpperCase()] = true;
332
+ const usedEn = outcome.url === enUrl;
333
+ const info = { channel: "stmcu", file, url: outcome.url, docId: item.docId.toUpperCase(), sha256: shaHex(buf), bytes: buf.byteLength, coverage, notes: ["备案通道 stmcu→CCC(" + (usedEn ? "英文译文" : "中文原版") + ")"] };
334
+ if (!lineCovered(index, line)) {
335
+ return { ...base, ...info, error: "stmcu 拿到的 " + item.docId.toUpperCase() + " 索引里找不到 " + line + "xx" + (usedEn ? "" : "(拿到的是中文 CID PDF,覆盖判定只信英文文本)") };
336
+ }
337
+ return { ...base, ...info, ok: true, error: "" };
338
+ }
339
+ return { ...base, error: "stmcu 通道的 " + String(items.length) + " 条候选都没取到可用 PDF:" + tried.join(";") };
340
+ }
341
+ /** 分类页 HTML → detail 条目(纯函数)。立创页混他族条目,族名要出现在标题里才算。 */
342
+ export function parseStmcuCategory(html) {
343
+ const out = [];
344
+ for (const m of html.matchAll(/href="https:\/\/www\.stmcu\.com\.cn\/Designresource\/detail\/document\/(\d+)"[^>]*title="([^"]{4,140})"/g)) {
345
+ const id = m[1] ?? "";
346
+ const title = (m[2] ?? "").trim();
347
+ const docId = (title.match(/RM\d{4}/i) ?? [""])[0].toUpperCase();
348
+ if (docId === "" || id === "")
349
+ continue;
350
+ out.push({ detailId: id, docId, title, fileName: "", cccUrl: "" });
351
+ }
352
+ const seen = new Set();
353
+ return out.filter((x) => (seen.has(x.detailId) ? false : (seen.add(x.detailId), true)));
354
+ }
355
+ /** 详情页 HTML → file_name / is_outside_file / CCC 直链(纯函数)。 */
356
+ export function parseStmcuDetail(html) {
357
+ const fn = html.match(/var sla = \d+, file_name = "([^"]+)"/);
358
+ const ccc = html.match(/window\.open\("(https:\/\/www\.st\.com\.cn\/content\/ccc\/resource[^"]+)"/);
359
+ return { fileName: fn?.[1] ?? "", cccUrl: ccc?.[1] ?? "" };
360
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * pymupdf 页文本桥:给 rm-extract 的引文回查供「与被核验同源」的文本。
3
+ *
4
+ * 为什么单独成模块而且可注入:
5
+ * · 引文必须来自被核验的那一份文本(docs §76),所以本插件的自研 Node 抽取器
6
+ * (rm-sources.extractPdfLatinText,压平、无页边界)只用于覆盖判定,不进回查口径;
7
+ * · dsh 主进程 env 完整时 `python` 一般可用(pymupdf 装在 user site 也能 import);
8
+ * run_code 的 execFile 是空 env,user-site 探测会假阴性——候选与失败原因都要能看见。
9
+ * · 单测注入 bridge,不依赖本机 Python。
10
+ */
11
+ import { spawnSync } from "node:child_process";
12
+ const PY_CODE = [
13
+ "import json, sys",
14
+ "import pymupdf",
15
+ "d = pymupdf.open(sys.argv[1])",
16
+ "want = [int(x) for x in sys.argv[2].split(',') if x]",
17
+ "out = [{'page': n, 'text': d[n - 1].get_text()} for n in want if 0 < n <= d.page_count]",
18
+ "print(json.dumps(out))",
19
+ ].join("\n");
20
+ function pythonCandidates(env) {
21
+ const custom = (env.DSH_STM32_PYTHON ?? "").trim();
22
+ if (custom !== "")
23
+ return [custom];
24
+ return ["python", "python3", "py"];
25
+ }
26
+ /** 默认桥:按候选解释器逐个试(第一个能 import pymupdf 且跑通 JSON 的胜出)。 */
27
+ export const defaultPdfTextBridge = async (pdfPath, pages) => {
28
+ const tried = [];
29
+ const list = [...new Set(pages)].sort((a, b) => a - b);
30
+ if (list.length === 0)
31
+ return { ok: false, pages: [], error: "没请求任何页", tried };
32
+ for (const py of pythonCandidates(process.env)) {
33
+ const r = spawnSync(py, ["-c", PY_CODE, pdfPath, list.join(",")], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 180_000 });
34
+ if (r.error !== undefined && r.error !== null) {
35
+ tried.push(py + " → 起进程失败:" + r.error.message);
36
+ continue;
37
+ }
38
+ if (r.status !== 0) {
39
+ const last = String(r.stderr || "").split("\n").filter(Boolean).pop() || ("退出码 " + String(r.status));
40
+ tried.push(py + " → " + last.slice(0, 160));
41
+ continue;
42
+ }
43
+ try {
44
+ const parsed = JSON.parse(r.stdout);
45
+ if (!Array.isArray(parsed) || parsed.length === 0) {
46
+ tried.push(py + " → 输出里没有页");
47
+ continue;
48
+ }
49
+ return { ok: true, pages: parsed, error: "", tried };
50
+ }
51
+ catch (error) {
52
+ tried.push(py + " → JSON 解析失败:" + (error instanceof Error ? error.message : String(error)).slice(0, 120));
53
+ }
54
+ }
55
+ return { ok: false, pages: [], error: "pymupdf 桥全候选都没跑通(给某个解释器装 pymupdf,或用 DSH_STM32_PYTHON 指定)", tried };
56
+ };