dsh-stm32 0.1.7 → 0.1.9

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 (153) hide show
  1. package/README.md +567 -516
  2. package/README_EN.md +544 -510
  3. package/client/client.js +7033 -682
  4. package/docs/reading-guide.md +921 -859
  5. package/lib/client.js +7033 -682
  6. package/lib/commands/register.js +2 -0
  7. package/lib/data/firmware-packages.js +35 -0
  8. package/lib/data/firmware-pins.js +7 -0
  9. package/lib/data/install-guides.js +110 -0
  10. package/lib/data/ioc-presets.js +118 -0
  11. package/lib/engine/artifacts.js +123 -0
  12. package/lib/engine/breakpoint-hits.js +73 -0
  13. package/lib/engine/build.js +161 -5
  14. package/lib/engine/channel-tap.js +227 -0
  15. package/lib/engine/channels.js +48 -0
  16. package/lib/engine/clocks.js +192 -0
  17. package/lib/engine/datasheet/auto.js +74 -0
  18. package/lib/engine/datasheet/digest.js +74 -0
  19. package/lib/engine/datasheet/lcsc.js +60 -0
  20. package/lib/engine/datasheet/pinout.js +119 -0
  21. package/lib/engine/datasheet/price.js +152 -0
  22. package/lib/engine/datasheet/search.js +147 -0
  23. package/lib/engine/datasheet/store.js +371 -0
  24. package/lib/engine/debug-session.js +48 -2
  25. package/lib/engine/ecad/autobuild.js +156 -0
  26. package/lib/engine/ecad/bom.js +238 -0
  27. package/lib/engine/ecad/brief.js +205 -0
  28. package/lib/engine/ecad/checks.js +239 -0
  29. package/lib/engine/ecad/design.js +177 -0
  30. package/lib/engine/ecad/dfm.js +314 -0
  31. package/lib/engine/ecad/easyeda.js +454 -0
  32. package/lib/engine/ecad/fabrication.js +104 -0
  33. package/lib/engine/ecad/gen/footprint.js +159 -0
  34. package/lib/engine/ecad/gen/symbol.js +103 -0
  35. package/lib/engine/ecad/import.js +372 -0
  36. package/lib/engine/ecad/jlcpcb.js +141 -0
  37. package/lib/engine/ecad/libs.js +316 -0
  38. package/lib/engine/ecad/models3d.js +89 -0
  39. package/lib/engine/ecad/netgate.js +286 -0
  40. package/lib/engine/ecad/normalize.js +182 -0
  41. package/lib/engine/ecad/package.js +126 -0
  42. package/lib/engine/ecad/padmerge.js +128 -0
  43. package/lib/engine/ecad/padprecheck.js +123 -0
  44. package/lib/engine/ecad/part-import.js +257 -0
  45. package/lib/engine/ecad/pcb/apply.js +53 -0
  46. package/lib/engine/ecad/pcb/emc-deep.js +396 -0
  47. package/lib/engine/ecad/pcb/emc.js +275 -0
  48. package/lib/engine/ecad/pcb/geometry.js +63 -0
  49. package/lib/engine/ecad/pcb/gerber.js +499 -0
  50. package/lib/engine/ecad/pcb/hand-sync.js +242 -0
  51. package/lib/engine/ecad/pcb/impedance.js +119 -0
  52. package/lib/engine/ecad/pcb/ipc-open.js +78 -0
  53. package/lib/engine/ecad/pcb/ipc-script.js +276 -0
  54. package/lib/engine/ecad/pcb/ipc.js +129 -0
  55. package/lib/engine/ecad/pcb/krt.js +182 -0
  56. package/lib/engine/ecad/pcb/links.js +393 -0
  57. package/lib/engine/ecad/pcb/mech.js +201 -0
  58. package/lib/engine/ecad/pcb/model-fix.js +178 -0
  59. package/lib/engine/ecad/pcb/netlist.js +146 -0
  60. package/lib/engine/ecad/pcb/pcb-svg.js +199 -0
  61. package/lib/engine/ecad/pcb/placement.js +140 -0
  62. package/lib/engine/ecad/pcb/power.js +203 -0
  63. package/lib/engine/ecad/pcb/render3d.js +208 -0
  64. package/lib/engine/ecad/pcb/route.js +167 -0
  65. package/lib/engine/ecad/pcb/router.js +469 -0
  66. package/lib/engine/ecad/pcb/rules.js +122 -0
  67. package/lib/engine/ecad/pcb/scene.js +513 -0
  68. package/lib/engine/ecad/pcb/stackup.js +154 -0
  69. package/lib/engine/ecad/pcb/swap.js +222 -0
  70. package/lib/engine/ecad/pcb/tracks.js +70 -0
  71. package/lib/engine/ecad/runtime.js +227 -0
  72. package/lib/engine/ecad/toolchain.js +146 -0
  73. package/lib/engine/ecad/tsci.js +362 -0
  74. package/lib/engine/ecad/zip.js +98 -0
  75. package/lib/engine/event-bus.js +158 -0
  76. package/lib/engine/event-log.js +335 -0
  77. package/lib/engine/fault-hints.js +146 -0
  78. package/lib/engine/generate-script.js +4 -1
  79. package/lib/engine/generate.js +145 -5
  80. package/lib/engine/interrupts.js +247 -0
  81. package/lib/engine/ioc-diff.js +369 -0
  82. package/lib/engine/ioc-plan.js +12 -2
  83. package/lib/engine/ioc-sync.js +58 -0
  84. package/lib/engine/mcu-info.js +134 -0
  85. package/lib/engine/msys2-install.js +31 -6
  86. package/lib/engine/panel-actions.js +103 -0
  87. package/lib/engine/pdf/curve.js +321 -0
  88. package/lib/engine/pdf/png.js +83 -0
  89. package/lib/engine/pdf/reader.js +336 -0
  90. package/lib/engine/pdf/schematic.js +93 -0
  91. package/lib/engine/pdf/tables.js +249 -0
  92. package/lib/engine/pdf/toolchain.js +50 -0
  93. package/lib/engine/pinout.js +140 -0
  94. package/lib/engine/probe-info.js +95 -0
  95. package/lib/engine/probe.js +45 -0
  96. package/lib/engine/progress.js +99 -0
  97. package/lib/engine/project-conf.js +254 -0
  98. package/lib/engine/project-layout.js +198 -0
  99. package/lib/engine/project-repair.js +205 -0
  100. package/lib/engine/schematic/checks.js +153 -0
  101. package/lib/engine/schematic/draw.js +390 -0
  102. package/lib/engine/schematic/edit.js +229 -0
  103. package/lib/engine/schematic/kicad-sch.js +225 -0
  104. package/lib/engine/schematic/model.js +442 -0
  105. package/lib/engine/schematic/nets.js +219 -0
  106. package/lib/engine/schematic/pcb.js +144 -0
  107. package/lib/engine/schematic/review.js +134 -0
  108. package/lib/engine/schematic/sexpr.js +134 -0
  109. package/lib/engine/schematic/to-ioc.js +197 -0
  110. package/lib/engine/schematic/transform.js +25 -0
  111. package/lib/engine/session-context.js +106 -0
  112. package/lib/engine/source-slice.js +59 -0
  113. package/lib/engine/tool-events.js +119 -0
  114. package/lib/engine/toolchain-gate.js +8 -0
  115. package/lib/engine/watch-admin.js +101 -0
  116. package/lib/engine/watch-record.js +39 -0
  117. package/lib/engine/watch-recorder.js +116 -0
  118. package/lib/engine/web-api.js +1123 -4
  119. package/lib/engine/web-routes.js +18 -1
  120. package/lib/engine/workspace-memo.js +41 -0
  121. package/lib/index.js +118 -24
  122. package/lib/skill/stm32-workflow.js +1 -1
  123. package/lib/tools/build.js +10 -2
  124. package/lib/tools/code-patch.js +2 -2
  125. package/lib/tools/datasheet.js +447 -0
  126. package/lib/tools/debug-session.js +9 -4
  127. package/lib/tools/debug.js +2 -2
  128. package/lib/tools/doctor.js +2 -2
  129. package/lib/tools/ecad.js +903 -0
  130. package/lib/tools/flash.js +2 -2
  131. package/lib/tools/gen.js +166 -0
  132. package/lib/tools/generate.js +7 -5
  133. package/lib/tools/import-circuit.js +146 -0
  134. package/lib/tools/ioc-apply.js +11 -2
  135. package/lib/tools/ioc-inspect.js +2 -2
  136. package/lib/tools/ioc-plan.js +2 -2
  137. package/lib/tools/ioc-verify.js +2 -2
  138. package/lib/tools/layout.js +92 -0
  139. package/lib/tools/mcu-info.js +163 -0
  140. package/lib/tools/part-import.js +182 -0
  141. package/lib/tools/pcb.js +2316 -0
  142. package/lib/tools/pdf.js +423 -0
  143. package/lib/tools/project-create.js +28 -0
  144. package/lib/tools/project-dir.js +25 -1
  145. package/lib/tools/regs.js +2 -2
  146. package/lib/tools/route-plan.js +2 -2
  147. package/lib/tools/rtt.js +10 -2
  148. package/lib/tools/sch-draw.js +433 -0
  149. package/lib/tools/sch-edit.js +145 -0
  150. package/lib/tools/schematic.js +817 -0
  151. package/lib/tools/serial.js +22 -0
  152. package/lib/tools/watch.js +24 -2
  153. package/package.json +1 -1
@@ -0,0 +1,147 @@
1
+ /**
2
+ * 器件搜索(S163):立创的公开搜索接口。
3
+ *
4
+ * 打的是前端自己在用的那个接口(`wmsc.lcsc.com/ftps/wm/search/third`),不需要登录:
5
+ * 搜关键词回产品列表,含编号、型号、品牌、封装、库存、阶梯价、手册地址。
6
+ *
7
+ * 这一层只做三件事:拼请求、把回包削成稳定的形状、按查询缓存(默认 24 小时)。
8
+ * 「该选哪个」不在这里判断——参数、温度等级、寿命都得人看手册。
9
+ */
10
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
11
+ import { join } from "node:path";
12
+ export const LCSC_SEARCH_URL = "https://wmsc.lcsc.com/ftps/wm/search/third";
13
+ export function searchCachePath(env) {
14
+ const home = env.DSH_STM32_HOME;
15
+ return home !== undefined && home !== "" ? join(home, "part-search.json") : join(process.env.USERPROFILE ?? process.env.HOME ?? ".", ".dsh-stm32", "part-search.json");
16
+ }
17
+ function readCache(file) {
18
+ try {
19
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
20
+ if (parsed.version === 1 && typeof parsed.entries === "object" && parsed.entries !== null) {
21
+ return { version: 1, entries: parsed.entries };
22
+ }
23
+ }
24
+ catch {
25
+ // 缓存坏了就当没有:搜索是只读操作,重下一份即可。
26
+ }
27
+ return { version: 1, entries: {} };
28
+ }
29
+ function writeCache(file, cache) {
30
+ try {
31
+ mkdirSync(join(file, ".."), { recursive: true });
32
+ writeFileSync(file, JSON.stringify(cache), "utf8");
33
+ }
34
+ catch {
35
+ // 写不了缓存不影响搜索本身。
36
+ }
37
+ }
38
+ function num(value) {
39
+ const parsed = typeof value === "number" ? value : Number(value);
40
+ return Number.isFinite(parsed) ? parsed : 0;
41
+ }
42
+ function str(value) {
43
+ return typeof value === "string" ? value : "";
44
+ }
45
+ /** 把一页回包削成 `PartHit[]`;字段名跟接口走,缺的下沉成空串/0。 */
46
+ export function parseProductList(payload) {
47
+ const result = payload?.result;
48
+ const list = Array.isArray(result?.productList) ? result.productList : [];
49
+ const hits = [];
50
+ for (const item of list) {
51
+ const code = str(item["productCode"]);
52
+ if (!/^C\d+$/u.test(code))
53
+ continue;
54
+ const rawLadder = Array.isArray(item["productPriceList"]) ? item["productPriceList"] : [];
55
+ const ladder = [];
56
+ for (const step of rawLadder) {
57
+ const qty = num(step["ladder"]);
58
+ const priceUsd = num(step["usdPrice"]);
59
+ if (qty > 0 && priceUsd > 0)
60
+ ladder.push({ qty, priceUsd });
61
+ }
62
+ ladder.sort((a, b) => a.qty - b.qty);
63
+ const stock = num(item["stockNumber"]);
64
+ hits.push({
65
+ code,
66
+ mpn: str(item["productModel"]),
67
+ brand: str(item["brandNameEn"]) || str(item["lcOrderBrandNameEn"]),
68
+ packageName: str(item["encapStandard"]),
69
+ stock,
70
+ minBuy: num(item["minBuyNumber"]),
71
+ priceUsd: ladder.length > 0 ? ladder[0].priceUsd : 0,
72
+ ladder,
73
+ category: str(item["thirdWmCatalogNameEn"]) || str(item["wmCatalogNameEn"]),
74
+ datasheetUrl: str(item["pdfUrl"]),
75
+ inStock: stock > 0,
76
+ });
77
+ }
78
+ return { total: num(result?.totalCount), hits };
79
+ }
80
+ const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
81
+ /** 搜一次;命中缓存直接回,不回网络。 */
82
+ export async function searchParts(query, options = {}) {
83
+ const keyword = query.trim();
84
+ const limit = Math.min(Math.max(Math.round(options.limit ?? 10), 1), 50);
85
+ const page = Math.max(Math.round(options.page ?? 1), 1);
86
+ const empty = { ok: false, error: "", query: keyword, total: 0, hits: [], cached: false, notes: [] };
87
+ if (keyword === "")
88
+ return { ...empty, error: "搜索关键词不能为空:给型号、参数或立创编号,例如 `STM32F103C8T6`、`0603 100nF`" };
89
+ const file = options.cacheFile ?? searchCachePath(process.env);
90
+ const key = String(limit) + "|" + String(page) + "|" + keyword.toLowerCase();
91
+ const now = options.now ?? (() => Date.now());
92
+ if (options.noCache !== true && existsSync(file)) {
93
+ const cache = readCache(file);
94
+ const hit = cache.entries[key];
95
+ if (hit !== undefined && now() - hit.at < (options.ttlMs ?? DEFAULT_TTL_MS)) {
96
+ return { ok: true, error: "", query: keyword, total: hit.total, hits: hit.hits, cached: true, notes: ["这一页来自本地缓存(24 小时内有效)"] };
97
+ }
98
+ }
99
+ const fetchImpl = options.fetchImpl ?? fetch;
100
+ const controller = new AbortController();
101
+ const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 20_000);
102
+ const onAbort = () => controller.abort();
103
+ options.signal?.addEventListener("abort", onAbort);
104
+ try {
105
+ const response = await fetchImpl(LCSC_SEARCH_URL, {
106
+ method: "POST",
107
+ headers: {
108
+ "content-type": "application/json",
109
+ accept: "application/json",
110
+ origin: "https://www.lcsc.com",
111
+ referer: "https://www.lcsc.com/",
112
+ "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) dsh-stm32",
113
+ },
114
+ body: JSON.stringify({ keyword, currentPage: page, pageSize: limit }),
115
+ signal: controller.signal,
116
+ });
117
+ if (!response.ok)
118
+ return { ...empty, error: "立创搜索接口回了 HTTP " + String(response.status) + ":稍后再试,或换成更具体的关键词" };
119
+ const payload = (await response.json());
120
+ const code = num(payload.code);
121
+ if (code !== 200)
122
+ return { ...empty, error: "立创搜索接口回了错误码 " + String(code) + ":" + str(payload.msg) };
123
+ const parsed = parseProductList(payload);
124
+ const notes = [];
125
+ if (parsed.hits.length === 0)
126
+ notes.push("没有匹配结果:试试去掉封装或电压,只留型号主体");
127
+ if (parsed.total > 0)
128
+ notes.push("共 " + String(parsed.total) + " 条匹配,这里只给前 " + String(parsed.hits.length) + " 条");
129
+ const cache = readCache(file);
130
+ cache.entries[key] = { at: now(), total: parsed.total, hits: parsed.hits };
131
+ const keys = Object.keys(cache.entries);
132
+ if (keys.length > 200) {
133
+ for (const stale of keys.slice(0, keys.length - 200))
134
+ delete cache.entries[stale];
135
+ }
136
+ writeCache(file, cache);
137
+ return { ok: true, error: "", query: keyword, total: parsed.total, hits: parsed.hits, cached: false, notes };
138
+ }
139
+ catch (error) {
140
+ const reason = error instanceof Error ? error.message : String(error);
141
+ return { ...empty, error: controller.signal.aborted ? "搜索超时或已取消:" + reason : "搜索失败:" + reason };
142
+ }
143
+ finally {
144
+ clearTimeout(timer);
145
+ options.signal?.removeEventListener("abort", onAbort);
146
+ }
147
+ }
@@ -0,0 +1,371 @@
1
+ /**
2
+ * 数据手册本地缓存(S119)。
3
+ *
4
+ * 目标:同一颗非 STM32 器件只下第一份手册,之后一律读本地。缓存按立创编号分目录,
5
+ * 文件名取 PDF 内容的 sha256 前缀,meta.json 记来源与抓取时间——出处可回溯、内容可校验。
6
+ *
7
+ * 失败也留痕:`_negative/<编号>.json` 记下原因与时间,24 小时内不再重试,避免每次构建都去撞墙。
8
+ */
9
+ import { createHash } from "node:crypto";
10
+ import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
11
+ import { homedir } from "node:os";
12
+ import { join } from "node:path";
13
+ import { fetchLcscProduct } from "./lcsc.js";
14
+ const INDEX_FILE = "index.json";
15
+ const NEGATIVE_DIR = "_negative";
16
+ const NEGATIVE_TTL_MS = 24 * 60 * 60 * 1000;
17
+ const DEFAULT_MAX_MB = 40;
18
+ const DEFAULT_GAP_MS = 1500;
19
+ let lastRequestAt = 0;
20
+ /** 缓存根目录:`DSH_STM32_DATASHEETS` 优先,否则 `~/.dsh-stm32/datasheets`。 */
21
+ export function datasheetCacheDir(env = process.env) {
22
+ const explicit = (env["DSH_STM32_DATASHEETS"] ?? "").trim();
23
+ if (explicit !== "")
24
+ return explicit;
25
+ return join(env["USERPROFILE"]?.trim() || homedir(), ".dsh-stm32", "datasheets");
26
+ }
27
+ export function isLcscCode(value) {
28
+ return /^(?:lcsc:)?C\d{3,}$/iu.test(value.trim());
29
+ }
30
+ export function normalizeCode(value) {
31
+ return value.trim().replace(/^lcsc:/iu, "").toUpperCase();
32
+ }
33
+ function emptyIndex() {
34
+ return { version: 1, entries: {} };
35
+ }
36
+ export function readIndex(cacheDir) {
37
+ const file = join(cacheDir, INDEX_FILE);
38
+ if (!existsSync(file))
39
+ return scanIndex(cacheDir);
40
+ try {
41
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
42
+ if (parsed.version !== 1 || typeof parsed.entries !== "object" || parsed.entries === null)
43
+ return emptyIndex();
44
+ return parsed;
45
+ }
46
+ catch {
47
+ return emptyIndex();
48
+ }
49
+ }
50
+ /** 索引丢了也能从各目录的 meta.json 重建(缓存目录被人手工动过时的自愈)。 */
51
+ function scanIndex(cacheDir) {
52
+ const index = emptyIndex();
53
+ if (!existsSync(cacheDir))
54
+ return index;
55
+ for (const name of readdirSync(cacheDir)) {
56
+ if (name.startsWith("_"))
57
+ continue;
58
+ const metaFile = join(cacheDir, name, "meta.json");
59
+ if (!existsSync(metaFile))
60
+ continue;
61
+ try {
62
+ const entry = JSON.parse(readFileSync(metaFile, "utf8"));
63
+ if (typeof entry.code === "string" && typeof entry.sha256 === "string")
64
+ index.entries[entry.code] = entry;
65
+ }
66
+ catch {
67
+ // 坏掉的 meta 跳过:宁缺,不要把脏数据带进索引。
68
+ }
69
+ }
70
+ return index;
71
+ }
72
+ function writeIndex(cacheDir, index) {
73
+ mkdirSync(cacheDir, { recursive: true });
74
+ writeFileSync(join(cacheDir, INDEX_FILE), JSON.stringify(index, null, 2) + "\n", "utf8");
75
+ }
76
+ export function entryFile(cacheDir, entry) {
77
+ return join(cacheDir, entry.code, entry.pdfFile);
78
+ }
79
+ /** 缓存是否还在:meta 存在、PDF 存在、sha256 对得上。 */
80
+ export function entryUsable(cacheDir, entry) {
81
+ const file = entryFile(cacheDir, entry);
82
+ if (!existsSync(file))
83
+ return false;
84
+ try {
85
+ return sha256Of(readFileSync(file)) === entry.sha256;
86
+ }
87
+ catch {
88
+ return false;
89
+ }
90
+ }
91
+ export function sha256Of(buffer) {
92
+ return createHash("sha256").update(buffer).digest("hex");
93
+ }
94
+ /** 把 `C25137` / `lcsc:C25137` / MPN 解析成本地 PDF 路径。 */
95
+ export function resolveDatasheetRef(cacheDir, ref) {
96
+ if (existsSync(ref))
97
+ return null;
98
+ const index = readIndex(cacheDir);
99
+ const wanted = ref.trim();
100
+ const byCode = index.entries[normalizeCode(wanted)];
101
+ if (byCode !== undefined && entryUsable(cacheDir, byCode))
102
+ return { file: entryFile(cacheDir, byCode), entry: byCode };
103
+ const lowered = wanted.toLowerCase();
104
+ for (const entry of Object.values(index.entries)) {
105
+ if (entry.mpn.toLowerCase() === lowered && entryUsable(cacheDir, entry)) {
106
+ return { file: entryFile(cacheDir, entry), entry };
107
+ }
108
+ }
109
+ return null;
110
+ }
111
+ function negativeFile(cacheDir, code) {
112
+ return join(cacheDir, NEGATIVE_DIR, code + ".json");
113
+ }
114
+ function negativeReason(cacheDir, code) {
115
+ const file = negativeFile(cacheDir, code);
116
+ if (!existsSync(file))
117
+ return "";
118
+ try {
119
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
120
+ if (typeof parsed.at !== "number" || Date.now() - parsed.at > NEGATIVE_TTL_MS)
121
+ return "";
122
+ return parsed.error ?? "上次抓取失败";
123
+ }
124
+ catch {
125
+ return "";
126
+ }
127
+ }
128
+ function writeNegative(cacheDir, code, error) {
129
+ mkdirSync(join(cacheDir, NEGATIVE_DIR), { recursive: true });
130
+ writeFileSync(negativeFile(cacheDir, code), JSON.stringify({ code, error, at: Date.now() }) + "\n", "utf8");
131
+ }
132
+ function clearNegative(cacheDir, code) {
133
+ const file = negativeFile(cacheDir, code);
134
+ if (existsSync(file))
135
+ rmSync(file, { force: true });
136
+ }
137
+ function gapMs() {
138
+ const fromEnv = Number.parseInt(process.env["DSH_STM32_DS_MIN_GAP_MS"] ?? "", 10);
139
+ return Number.isFinite(fromEnv) && fromEnv >= 0 ? fromEnv : DEFAULT_GAP_MS;
140
+ }
141
+ async function throttle() {
142
+ const wait = gapMs() - (Date.now() - lastRequestAt);
143
+ if (wait > 0)
144
+ await new Promise((resolve) => setTimeout(resolve, wait));
145
+ lastRequestAt = Date.now();
146
+ }
147
+ /**
148
+ * 确保某颗器件的 PDF 在本地。
149
+ * 命中缓存时零网络;`offline` 时不发请求;失败写入负缓存(24 小时)。
150
+ */
151
+ export async function ensureDatasheet(codeSpec, options = {}) {
152
+ const cacheDir = options.cacheDir ?? datasheetCacheDir(options.env);
153
+ const code = normalizeCode(codeSpec);
154
+ if (!/^C\d{3,}$/u.test(code)) {
155
+ return { ok: false, error: "编号不像立创商品编号:" + codeSpec + "(形如 C25137)" };
156
+ }
157
+ const index = readIndex(cacheDir);
158
+ const existing = index.entries[code];
159
+ if (existing !== undefined && !(options.refresh ?? false) && entryUsable(cacheDir, existing)) {
160
+ return { ok: true, cached: true, entry: existing, file: entryFile(cacheDir, existing) };
161
+ }
162
+ if (options.offline ?? false) {
163
+ return { ok: false, error: "离线模式(DSH_STM32_OFFLINE=1),本地没有 " + code + " 的手册" };
164
+ }
165
+ if (!(options.refresh ?? false)) {
166
+ const reason = negativeReason(cacheDir, code);
167
+ if (reason !== "")
168
+ return { ok: false, error: "24 小时内抓取失败过,暂不重试:" + reason };
169
+ }
170
+ const fetchImpl = options.fetchImpl ?? fetch;
171
+ await throttle();
172
+ const page = await fetchLcscProduct(code, { fetchImpl, timeoutMs: options.timeoutMs, signal: options.signal });
173
+ if (!page.ok) {
174
+ writeNegative(cacheDir, code, page.error);
175
+ return { ok: false, error: page.error };
176
+ }
177
+ await throttle();
178
+ const controller = new AbortController();
179
+ const timer = setTimeout(() => controller.abort(), 60_000);
180
+ let buffer;
181
+ try {
182
+ const response = await fetchImpl(page.product.pdfUrl, {
183
+ signal: options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]),
184
+ redirect: "follow",
185
+ headers: { "user-agent": "dsh-stm32 datasheet fetcher (pdf)" },
186
+ });
187
+ if (!response.ok) {
188
+ const error = "PDF 返回 HTTP " + String(response.status) + ":" + page.product.pdfUrl;
189
+ writeNegative(cacheDir, code, error);
190
+ return { ok: false, error };
191
+ }
192
+ buffer = Buffer.from(await response.arrayBuffer());
193
+ }
194
+ catch (error) {
195
+ const reason = "下载 PDF 失败:" + (error instanceof Error ? error.message : String(error));
196
+ writeNegative(cacheDir, code, reason);
197
+ return { ok: false, error: reason };
198
+ }
199
+ finally {
200
+ clearTimeout(timer);
201
+ }
202
+ const maxBytes = (options.maxMb ?? DEFAULT_MAX_MB) * 1024 * 1024;
203
+ if (buffer.length > maxBytes) {
204
+ const error = "PDF 超过上限(" + String(Math.round(buffer.length / 1024 / 1024)) + " MB > " + String(options.maxMb ?? DEFAULT_MAX_MB) + " MB)";
205
+ writeNegative(cacheDir, code, error);
206
+ return { ok: false, error };
207
+ }
208
+ if (buffer.subarray(0, 5).toString("latin1") !== "%PDF-") {
209
+ const error = "下载到的不是 PDF(开头不是 %PDF-):" + page.product.pdfUrl;
210
+ writeNegative(cacheDir, code, error);
211
+ return { ok: false, error };
212
+ }
213
+ const entry = storeBuffer(cacheDir, page.product, buffer);
214
+ clearNegative(cacheDir, code);
215
+ return { ok: true, cached: false, entry, file: entryFile(cacheDir, entry) };
216
+ }
217
+ /** 把一份 PDF 写进缓存(下载与手工导入共用)。 */
218
+ export function storeBuffer(cacheDir, product, buffer) {
219
+ const sha256 = sha256Of(buffer);
220
+ const dir = join(cacheDir, product.code);
221
+ mkdirSync(dir, { recursive: true });
222
+ for (const name of readdirSync(dir)) {
223
+ if (name.endsWith(".pdf") && name !== sha256.slice(0, 12) + ".pdf")
224
+ rmSync(join(dir, name), { force: true });
225
+ }
226
+ const pdfFile = sha256.slice(0, 12) + ".pdf";
227
+ writeFileSync(join(dir, pdfFile), buffer);
228
+ const entry = {
229
+ code: product.code,
230
+ mpn: product.mpn,
231
+ brand: product.brand,
232
+ title: product.title,
233
+ sha256,
234
+ bytes: buffer.length,
235
+ pdfFile,
236
+ sourceUrl: product.sourceUrl,
237
+ pdfUrl: product.pdfUrl,
238
+ fetchedAt: new Date().toISOString(),
239
+ };
240
+ writeFileSync(join(dir, "meta.json"), JSON.stringify(entry, null, 2) + "\n", "utf8");
241
+ const index = readIndex(cacheDir);
242
+ index.entries[product.code] = entry;
243
+ writeIndex(cacheDir, index);
244
+ return entry;
245
+ }
246
+ /** 手工导入:用户自己放一份 PDF 进来(离线/反爬时的退路)。 */
247
+ export function importDatasheet(cacheDir, file, product = {}) {
248
+ if (!existsSync(file))
249
+ return { ok: false, error: "文件不存在:" + file };
250
+ const buffer = readFileSync(file);
251
+ if (buffer.subarray(0, 5).toString("latin1") !== "%PDF-")
252
+ return { ok: false, error: "不是 PDF:" + file };
253
+ const code = normalizeCode(product.code ?? "");
254
+ const product2 = {
255
+ code: /^C\d{3,}$/u.test(code) ? code : "manual-" + sha256Of(buffer).slice(0, 8),
256
+ mpn: product.mpn ?? "",
257
+ brand: product.brand ?? "",
258
+ title: product.title ?? file,
259
+ pdfUrl: product.pdfUrl ?? "",
260
+ sourceUrl: product.sourceUrl ?? file,
261
+ };
262
+ const entry = storeBuffer(cacheDir, product2, buffer);
263
+ return { ok: true, cached: false, entry, file: entryFile(cacheDir, entry) };
264
+ }
265
+ export function listDatasheets(cacheDir) {
266
+ const index = readIndex(cacheDir);
267
+ const entries = [];
268
+ let totalBytes = 0;
269
+ for (const entry of Object.values(index.entries)) {
270
+ if (!entryUsable(cacheDir, entry))
271
+ continue;
272
+ entries.push(entry);
273
+ totalBytes += entry.bytes;
274
+ }
275
+ entries.sort((a, b) => a.code.localeCompare(b.code));
276
+ return { cacheDir, entries, totalBytes };
277
+ }
278
+ /** 缓存占用(不影响列表):目录里 PDF 的实际大小,含手写目录。 */
279
+ export function cacheBytes(cacheDir) {
280
+ if (!existsSync(cacheDir))
281
+ return 0;
282
+ let total = 0;
283
+ for (const name of readdirSync(cacheDir)) {
284
+ const file = join(cacheDir, name);
285
+ if (!statSync(file).isFile()) {
286
+ const entry = readIndex(cacheDir).entries[name];
287
+ if (entry !== undefined)
288
+ total += entry.bytes;
289
+ }
290
+ }
291
+ return total;
292
+ }
293
+ /** 手工导入的便捷封装:按位号名复制进缓存(面板/工具用)。 */
294
+ export function importDatasheetFile(cacheDir, source, code, mpn) {
295
+ mkdirSync(cacheDir, { recursive: true });
296
+ const temp = join(cacheDir, "_import.pdf");
297
+ copyFileSync(source, temp);
298
+ const result = importDatasheet(cacheDir, temp, { code, mpn });
299
+ rmSync(temp, { force: true });
300
+ return result;
301
+ }
302
+ /**
303
+ * 清理缓存(S124):按编号删,或按「超过 N 天没再抓过」删。
304
+ *
305
+ * 不做容量上限:手册是外部证据,删多少应该由人决定;这里只提供可复核的入口——
306
+ * 返回删了哪些、释放多少字节、还剩哪些,删之前先确认索引里确实有这一份。
307
+ */
308
+ export function pruneDatasheets(cacheDir, options = {}) {
309
+ const index = readIndex(cacheDir);
310
+ const codes = new Set(Object.keys(index.entries));
311
+ const removed = [];
312
+ const notes = [];
313
+ const wanted = (options.remove ?? []).map((value) => normalizeCode(value)).filter((value) => value !== "");
314
+ for (const code of wanted) {
315
+ const entry = index.entries[code];
316
+ if (entry === undefined) {
317
+ notes.push("缓存里没有 " + code + ",跳过");
318
+ continue;
319
+ }
320
+ removeEntry(cacheDir, entry, removed);
321
+ codes.delete(code);
322
+ }
323
+ if (options.olderThanDays !== undefined && options.olderThanDays > 0) {
324
+ const cutoff = Date.now() - options.olderThanDays * 24 * 3600 * 1000;
325
+ for (const code of [...codes]) {
326
+ const entry = index.entries[code];
327
+ if (entry === undefined)
328
+ continue;
329
+ const stamp = Date.parse(entry.fetchedAt);
330
+ if (Number.isNaN(stamp) || stamp >= cutoff)
331
+ continue;
332
+ removeEntry(cacheDir, entry, removed);
333
+ codes.delete(code);
334
+ }
335
+ }
336
+ if (removed.length === 0 && notes.length === 0)
337
+ notes.push("没有给出要删的编号,也没有超过期限的条目");
338
+ const bytes = removed.reduce((sum, item) => sum + item.bytes, 0);
339
+ const keptEntries = {};
340
+ for (const [code, entry] of Object.entries(index.entries))
341
+ if (codes.has(code))
342
+ keptEntries[code] = entry;
343
+ writeIndex(cacheDir, { version: 1, entries: keptEntries });
344
+ const kept = [...codes].sort((a, b) => a.localeCompare(b));
345
+ return { ok: true, error: "", removed, bytes, kept, notes };
346
+ }
347
+ function removeEntry(cacheDir, entry, removed) {
348
+ const file = entryFile(cacheDir, entry);
349
+ let bytes = entry.bytes;
350
+ try {
351
+ const stat = statSync(file);
352
+ bytes = stat.size;
353
+ }
354
+ catch {
355
+ // 文件已经不在,按索引里记的字节数计
356
+ }
357
+ try {
358
+ rmSync(file, { force: true });
359
+ }
360
+ catch {
361
+ // 删不掉就仍然从索引里摘掉,下次扫描会重建
362
+ }
363
+ const dir = join(cacheDir, entry.code);
364
+ try {
365
+ rmSync(join(dir, "digest.json"), { force: true });
366
+ }
367
+ catch {
368
+ // 索引文件删不掉不影响结论
369
+ }
370
+ removed.push({ code: entry.code, bytes });
371
+ }
@@ -14,6 +14,7 @@ import { existsSync } from "node:fs";
14
14
  import net from "node:net";
15
15
  import { resolveSearchConfig } from "../data/search-roots.js";
16
16
  import { F1_BREAKPOINT_BUDGET, collectBreakpointRequests, planBreakpoints, quotaOf, resolveBreakpointBudget } from "./breakpoints.js";
17
+ import { HitHistory } from "./breakpoint-hits.js";
17
18
  import { isPortBusy, pickPort, resolveElfPath } from "./debug.js";
18
19
  import { MiSession, formatStopLocation, steppingCommandFor } from "./gdb-mi.js";
19
20
  import { WATCH_KIND_LABELS, formatWatchDelta, formatWatchSampleNote, hardwareWatchpoints, isHardwareWatchpoint, markWatchpointsStale, normalizeWatchExpression, parseWatchMarkers, parseWatchpointNumber, recordWatchSample, registerWatch, removeWatchByIds, resetWatchState, sampledWatches, watchState, } from "./watch.js";
@@ -23,6 +24,10 @@ import { liveProbeChoice, openocdTransportArgs } from "./doctor.js";
23
24
  import { resolveToolIn } from "./probe.js";
24
25
  import { runCapture } from "./subprocess-runner.js";
25
26
  import { waitForListening } from "./debug.js";
27
+ /** 轨迹保留条数;面板只要最近几次。 */
28
+ const TRACE_LIMIT = 20;
29
+ /** 单条轨迹保留的输出字符数(从尾部截)。 */
30
+ const TRACE_TEXT_LIMIT = 2000;
26
31
  const DEFAULT_IDLE_TTL_MS = 90_000;
27
32
  const DEFAULT_HARD_TTL_MS = 10 * 60_000;
28
33
  const SWEEP_MS = 5_000;
@@ -123,6 +128,7 @@ function emptyReport(errors, message) {
123
128
  startedAt: 0, idleTtlMs: DEFAULT_IDLE_TTL_MS, hardTtlMs: DEFAULT_HARD_TTL_MS, remainingMs: 0,
124
129
  breakpoints: quotaOf(0, F1_BREAKPOINT_BUDGET.code),
125
130
  watchpoints: quotaOf(0, F1_BREAKPOINT_BUDGET.data),
131
+ owner: "",
126
132
  errors, message,
127
133
  };
128
134
  }
@@ -133,6 +139,10 @@ export class DebugSessionManager {
133
139
  aliveProbe = (port) => isPortBusy(port, 500);
134
140
  current = null;
135
141
  timer = null;
142
+ /** 断点与观察点的命中历史:跨 eval 保留,关会话时清空。 */
143
+ hits = new HitHistory();
144
+ /** 最近几次 eval 的命令与输出尾部:面板展示原始 gdb 输出用,关会话时清空。 */
145
+ traces = [];
136
146
  now;
137
147
  constructor(options = {}) {
138
148
  this.now = options.now ?? (() => Date.now());
@@ -151,11 +161,30 @@ export class DebugSessionManager {
151
161
  setAliveProbe(probe) {
152
162
  this.aliveProbe = probe;
153
163
  }
164
+ /** 本次会话的命中历史,最新在后。 */
165
+ hitHistory() {
166
+ return this.hits.list();
167
+ }
168
+ /** 最近几次 eval 的命令与输出,最新在后。 */
169
+ recentTraces(limit = 5) {
170
+ const count = Math.max(1, Math.min(Math.floor(limit), TRACE_LIMIT));
171
+ return this.traces.slice(-count);
172
+ }
173
+ /** 记一条 eval 轨迹:输出只留尾部,避免面板被长 log 拖住。 */
174
+ rememberTrace(command, ok, output) {
175
+ const text = output.length > TRACE_TEXT_LIMIT ? output.slice(output.length - TRACE_TEXT_LIMIT) : output;
176
+ this.traces.push({ at: this.now(), command: command, ok: ok, output: text });
177
+ while (this.traces.length > TRACE_LIMIT)
178
+ this.traces.shift();
179
+ }
154
180
  isActive() {
155
181
  return this.current !== null;
156
182
  }
157
183
  /**
158
- * 续租:会话刚被用过一次(B3 的 regs 快路径每读一次都算"用过")。
184
+ * 续租:把空闲计时器归零,总时长上限不动。
185
+ *
186
+ * 调用方有两处:regs 快路径每读一次都算"用过";面板「续期」按钮重置空闲计时
187
+ * (盯日志十几分钟不该因为没敲命令被关掉,但也不能让轮询无限延长一次调试)。
159
188
  * 返回是否真的有会话被续租。
160
189
  */
161
190
  touch() {
@@ -175,7 +204,7 @@ export class DebugSessionManager {
175
204
  configFile: session.configFile,
176
205
  elfPath: session.elfPath, startedAt: session.startedAt, idleTtlMs: session.idleTtlMs,
177
206
  hardTtlMs: session.hardTtlMs, remainingMs: this.remainingMs(session),
178
- breakpoints: session.breakpoints, watchpoints: session.watchpoints, errors: [],
207
+ breakpoints: session.breakpoints, watchpoints: session.watchpoints, owner: session.owner, errors: [],
179
208
  message: "调试会话进行中(端口 " + String(session.port) + ",剩余 " + String(Math.ceil(this.remainingMs(session) / 1000)) + " s)",
180
209
  };
181
210
  }
@@ -184,6 +213,13 @@ export class DebugSessionManager {
184
213
  const hardDeadline = session.startedAt + session.hardTtlMs;
185
214
  return Math.max(0, Math.min(idleDeadline, hardDeadline) - this.now());
186
215
  }
216
+ /** 单测用:丢掉内存里的会话记录(不关进程、不碰探针)。 */
217
+ resetForTest() {
218
+ this.current = null;
219
+ this.stopSweeper();
220
+ this.hits.clear();
221
+ this.traces.length = 0;
222
+ }
187
223
  /** 扫一次租约:过期的会话立刻关。定时器与单测共用这一条路径。 */
188
224
  async sweepExpired() {
189
225
  const session = this.current;
@@ -468,6 +504,8 @@ export class DebugSessionManager {
468
504
  if (!miStillActive)
469
505
  miErrors.push("会话在本次 eval 期间已关闭");
470
506
  const miOutput = lines.join("\n").trim();
507
+ this.hits.record(miOutput, this.now());
508
+ this.rememberTrace(commandLine, miErrors.length === 0, miOutput);
471
509
  return {
472
510
  ok: miErrors.length === 0,
473
511
  output: miOutput,
@@ -498,6 +536,8 @@ export class DebugSessionManager {
498
536
  });
499
537
  session.lastUsedAt = this.now();
500
538
  const output = (outcome.stdout + "\n" + outcome.stderr).trim();
539
+ this.hits.record(output, this.now());
540
+ this.rememberTrace(commands.join(" ;; "), outcome.exitCode === 0 && !outcome.timedOut, output);
501
541
  const errors = [];
502
542
  if (outcome.spawnError !== null)
503
543
  errors.push("gdb 启动失败:" + outcome.spawnError);
@@ -889,6 +929,8 @@ export class DebugSessionManager {
889
929
  }
890
930
  this.current = null;
891
931
  this.stopSweeper();
932
+ this.hits.clear();
933
+ this.traces.length = 0;
892
934
  // 观察点住在 gdb 进程里:会话一关就全没了,登记表必须跟着清,
893
935
  // 否则下次会话里 action=list 会报一堆已经不存在的观察点。
894
936
  resetWatchState();
@@ -936,6 +978,10 @@ export class DebugSessionManager {
936
978
  }
937
979
  /** 进程内单例:工具、turn/end 监听、dispose 共用同一个会话。 */
938
980
  export const debugSessions = new DebugSessionManager();
981
+ /** 单测用:清空当前会话摘要,避免用例之间互相影响。 */
982
+ export function resetDebugSessionsForTest() {
983
+ debugSessions.resetForTest();
984
+ }
939
985
  /** 通过 Tcl 口让 openocd 自行 shutdown(探针能收到正常的断开序列)。失败时交由 kill 回退处理。 */
940
986
  function requestOpenocdShutdown(port, timeoutMs) {
941
987
  if (!Number.isFinite(port) || port <= 0)