dsh-stm32 0.1.0 → 0.1.2

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 (82) hide show
  1. package/README.md +127 -29
  2. package/README_EN.md +125 -29
  3. package/client/client.js +682 -0
  4. package/docs/development-notes.md +1385 -5
  5. package/docs/logic-audit.md +607 -0
  6. package/docs/reading-guide.md +738 -0
  7. package/lib/client.js +682 -0
  8. package/lib/commands/register.js +214 -12
  9. package/lib/data/chips.js +134 -4
  10. package/lib/data/clock-f1.js +158 -0
  11. package/lib/data/cmsis-sources.js +316 -0
  12. package/lib/data/f1-ram.generated.js +34 -0
  13. package/lib/data/firmware-packages.js +352 -0
  14. package/lib/data/install-guides.js +190 -0
  15. package/lib/data/search-roots.js +135 -15
  16. package/lib/data/stm32f1.js +186 -0
  17. package/lib/data/toolchain-config.js +310 -0
  18. package/lib/engine/build.js +121 -16
  19. package/lib/engine/cache.js +336 -0
  20. package/lib/engine/clock-plan.js +608 -0
  21. package/lib/engine/cmake-sources.js +428 -0
  22. package/lib/engine/code-patch.js +18 -6
  23. package/lib/engine/debug-session.js +163 -4
  24. package/lib/engine/debug.js +84 -19
  25. package/lib/engine/doctor.js +395 -4
  26. package/lib/engine/fetch.js +287 -0
  27. package/lib/engine/firmware-install.js +668 -0
  28. package/lib/engine/flash.js +145 -15
  29. package/lib/engine/fs-longpath.js +107 -0
  30. package/lib/engine/generate-cache.js +118 -0
  31. package/lib/engine/generate-script.js +30 -8
  32. package/lib/engine/generate.js +296 -14
  33. package/lib/engine/hal-chip.js +230 -0
  34. package/lib/engine/ioc-plan.js +47 -8
  35. package/lib/engine/msys2-install.js +1870 -0
  36. package/lib/engine/probe.js +57 -6
  37. package/lib/engine/project-export.js +129 -0
  38. package/lib/engine/register-clock.js +132 -0
  39. package/lib/engine/register-linker.js +129 -0
  40. package/lib/engine/register-template.js +449 -0
  41. package/lib/engine/regs.js +18 -4
  42. package/lib/engine/route-plan.js +553 -0
  43. package/lib/engine/scaffold.js +303 -72
  44. package/lib/engine/subprocess-runner.js +2 -0
  45. package/lib/engine/tar.js +250 -0
  46. package/lib/engine/text-file.js +150 -0
  47. package/lib/engine/thirdparty.js +243 -0
  48. package/lib/engine/tool-env.js +51 -0
  49. package/lib/engine/toolchain-gate.js +386 -0
  50. package/lib/engine/vscode-config.js +99 -0
  51. package/lib/engine/web-api.js +375 -0
  52. package/lib/engine/web-routes.js +100 -0
  53. package/lib/engine/xcube-catalog.js +102 -0
  54. package/lib/engine/xcube.js +254 -0
  55. package/lib/engine/zip.js +142 -0
  56. package/lib/index.js +44 -2
  57. package/lib/skill/stm32-workflow.js +3 -3
  58. package/lib/tools/build.js +55 -3
  59. package/lib/tools/cache.js +250 -0
  60. package/lib/tools/code-patch.js +29 -2
  61. package/lib/tools/debug-session.js +56 -14
  62. package/lib/tools/debug.js +43 -2
  63. package/lib/tools/doctor.js +16 -3
  64. package/lib/tools/env-install.js +472 -0
  65. package/lib/tools/env-probe.js +6 -2
  66. package/lib/tools/firmware-install.js +255 -0
  67. package/lib/tools/flash.js +41 -2
  68. package/lib/tools/generate.js +96 -10
  69. package/lib/tools/ioc-apply.js +27 -11
  70. package/lib/tools/ioc-inspect.js +4 -2
  71. package/lib/tools/ioc-plan.js +209 -11
  72. package/lib/tools/project-create.js +229 -21
  73. package/lib/tools/project-dir.js +95 -0
  74. package/lib/tools/project-export.js +100 -0
  75. package/lib/tools/regs.js +82 -7
  76. package/lib/tools/route-plan.js +467 -0
  77. package/package.json +11 -4
  78. package/templates/register/CMakeLists.txt +52 -0
  79. package/templates/register/Core/Src/main.c +72 -0
  80. package/templates/scaffold/openocd.cfg +8 -0
  81. package/templates/scaffold/vscode/launch.json +8 -6
  82. package/templates/scaffold/vscode/settings.json +5 -11
@@ -0,0 +1,449 @@
1
+ /**
2
+ * 寄存器版工程:从缓存拉 CMSIS 模板,再拼出一个不用 CubeMX / 不用 HAL 的 CMake 工程。
3
+ *
4
+ * 为什么模板不预置进插件(用户 2026-10-24 决定):插件要覆盖任意 STM32,每颗芯片的
5
+ * startup + 设备头 + 内核头都打一份进 npm 包,包会大到不可用。所以:
6
+ * 第一次用 → 从网上下载(多候选源,见 fetch.ts)→ 落到可检索缓存目录(见 cache.ts)
7
+ * 以后用 → 直接复用缓存,不联网
8
+ *
9
+ * 工程里的 Drivers/CMSIS 与 HAL 工程布局一致(ST 固件包的摆放),所以同一套 include 约定、
10
+ * 同一个工具链文件、同一个链接脚本都能直接复用;差别只是源文件里不出现 HAL 调用。
11
+ */
12
+ import fs from "node:fs";
13
+ import path from "node:path";
14
+ import { fileURLToPath } from "node:url";
15
+ import { CMSIS_FAMILIES, cmsisTemplatePlan, startupChoiceFor } from "../data/cmsis-sources.js";
16
+ import { cacheRootInfo, checkCacheEntry, readCacheIndex, resolveCacheEntry, sha256OfFile, upsertCacheEntry } from "./cache.js";
17
+ import { fetchAll } from "./fetch.js";
18
+ import { planRegisterClock, renderClockInit } from "./register-clock.js";
19
+ import { planRegisterLinker, renderLinkerScript } from "./register-linker.js";
20
+ import { backupBeforeOverwrite, backupWarning, cleanupAfterFailure, mkdirTracked, preflightTarget, templateDir } from "./scaffold.js";
21
+ /** 寄存器版模板目录:lib/engine/register-template.js → ../../templates/register。 */
22
+ export function registerTemplateDir() {
23
+ return fileURLToPath(new URL("../../templates/register/", import.meta.url));
24
+ }
25
+ /** 型号/族 → 启动文件与设备宏;认不出返回 null(不猜文件名)。 */
26
+ export function resolveStartupChoice(request) {
27
+ const mcu = (request.mcu ?? "").trim();
28
+ if (mcu !== "")
29
+ return startupChoiceFor(mcu);
30
+ const family = (request.family ?? "F1").trim().toUpperCase();
31
+ // 只给族时按中容量档(F1 → xB):蓝丸 C8T6 正是这一档,也是最常见的入门芯片。
32
+ return startupChoiceFor(family + ":B");
33
+ }
34
+ function emptyResult(cacheRoot, error, message) {
35
+ return { ok: false, family: "", id: "", cacheRoot, entryDir: "", cacheHit: false, startup: "", deviceDefine: "", deviceHeader: "", files: 0, bytes: 0, error, message };
36
+ }
37
+ /**
38
+ * 确保某颗芯片的 CMSIS 模板在缓存里。
39
+ *
40
+ * 顺序:查索引 → 校验文件(缺/大小不对就重下)→ 下载(并发 3、每个文件多候选源)→
41
+ * 写 THIRD_PARTY_NOTICES.md → 写索引。任何一步失败都返回 ok:false + 人话原因,
42
+ * 不抛异常(工具层要把原因贴到卡片上)。
43
+ */
44
+ export async function ensureCmsisTemplate(request = {}) {
45
+ const env = request.env ?? process.env;
46
+ const info = cacheRootInfo(env);
47
+ const choice = resolveStartupChoice(request);
48
+ if (choice === null) {
49
+ const asked = (request.mcu ?? request.family ?? "").trim();
50
+ // F103 家族里上游没有的容量档要单独说清楚(A24):说"认不出"会让人以为插件坏了。
51
+ const f103 = /^STM32F103([A-Z])([0-9A-Z])/u.exec(asked.toUpperCase());
52
+ const densityNote = f103 !== null
53
+ ? "上游 CMSIS 只有 x6 / xB / xE 三套启动文件,没有容量档 " + (f103[2] ?? "") + " 这一套:F103 的 4/8/6 档归到 x6 或 xB,C/D/E 档归到 xE。换 STM32F103C8T6 / CBT6 这类型号,"
54
+ : "换 F103 型号,";
55
+ return emptyResult(info.root, "unsupported-mcu", "认不出这颗芯片的启动文件(目前只做 STM32F1 的 F103 系列):" + (asked || "(没给型号)") + "。" + densityNote + "或改用 HAL 路线(.ioc + CubeMX)。");
56
+ }
57
+ const plan = cmsisTemplatePlan(choice);
58
+ if (plan === null)
59
+ return emptyResult(info.root, "unsupported-family", "这一代还没有下载清单:" + choice.family + "。");
60
+ const { index, error: indexError } = readCacheIndex(env);
61
+ if (indexError !== null)
62
+ request.onProgress?.(indexError);
63
+ // 用别名解析而不是精确匹配:0.1 建过的 cmsis:F1:startup_stm32f103xb 条目内容完全一样,
64
+ // 认不出就会白下一遍 14 个文件(还可能在慢网里失败)。
65
+ const existing = resolveCacheEntry(index, plan.id);
66
+ if (existing !== null) {
67
+ const health = checkCacheEntry(existing);
68
+ if (health.ok) {
69
+ return {
70
+ ok: true,
71
+ family: plan.family,
72
+ id: plan.id,
73
+ cacheRoot: info.root,
74
+ entryDir: existing.root,
75
+ cacheHit: true,
76
+ startup: choice.startup,
77
+ deviceDefine: choice.define,
78
+ deviceHeader: choice.deviceHeader,
79
+ files: existing.files.length,
80
+ bytes: existing.totalBytes,
81
+ error: "",
82
+ message: "缓存里已有 " + plan.id + "(" + String(existing.files.length) + " 个文件),没有联网。",
83
+ };
84
+ }
85
+ const broken = health.missing.length + health.changed.length;
86
+ request.onProgress?.("缓存条目 " + plan.id + " 有 " + String(broken) + " 个文件缺失或大小不对,重新下载。");
87
+ }
88
+ if (request.download === false) {
89
+ return {
90
+ ...emptyResult(info.root, "not-cached", "寄存器模板不在缓存里(" + plan.id + "):这台机器还没下载过,而这次调用被要求不联网。去掉 download=false 再试一次。"),
91
+ family: plan.family,
92
+ id: plan.id,
93
+ startup: choice.startup,
94
+ deviceDefine: choice.define,
95
+ deviceHeader: choice.deviceHeader,
96
+ };
97
+ }
98
+ const entryDir = path.join(info.root, plan.dirName);
99
+ fs.mkdirSync(entryDir, { recursive: true });
100
+ request.onProgress?.("下载 " + String(plan.targets.length) + " 个模板文件到 " + entryDir + "(第一次用需要联网,以后复用缓存)。");
101
+ const options = {
102
+ onProgress: (outcome, done, total) => {
103
+ request.onProgress?.("下载 " + String(done) + "/" + String(total) + ":" + outcome.path + (outcome.ok ? " ✓" : " ✗ " + outcome.error));
104
+ },
105
+ };
106
+ if (request.fetchImpl !== undefined)
107
+ options.fetchImpl = request.fetchImpl;
108
+ if (request.signal !== undefined)
109
+ options.signal = request.signal;
110
+ const targets = request.hashes === undefined
111
+ ? plan.targets
112
+ : plan.targets.map((target) => ({ ...target, sha256: request.hashes?.[target.path] }));
113
+ const fetched = await fetchAll(targets, entryDir, options);
114
+ if (fetched.failed > 0) {
115
+ const failures = fetched.results.filter((item) => !item.ok).slice(0, 3).map((item) => item.path + ":" + item.error);
116
+ const failedResults = fetched.results.filter((item) => !item.ok);
117
+ const allNotFound = failedResults.length > 0 && failedResults.every((item) => item.attempts.length > 0 && item.attempts.every((line) => line.includes("HTTP 404")));
118
+ // 半截缓存比没有缓存更糟:下一次会把不完整的目录当成模板用。
119
+ // 但直接 rm 会把并发方正在读的目录抽走(A24):先改名成 .stale-<时间戳>,再删;
120
+ // 改名失败(被占用)就留着,至少不删到一半。
121
+ const staleDir = entryDir + ".stale-" + new Date().toISOString().replace(/[:.]/gu, "-");
122
+ let renamed = false;
123
+ try {
124
+ fs.renameSync(entryDir, staleDir);
125
+ renamed = true;
126
+ }
127
+ catch {
128
+ renamed = false;
129
+ }
130
+ let cleaned = false;
131
+ if (renamed) {
132
+ try {
133
+ fs.rmSync(staleDir, { recursive: true, force: true });
134
+ cleaned = true;
135
+ }
136
+ catch {
137
+ cleaned = false;
138
+ }
139
+ }
140
+ const cleanupNote = renamed
141
+ ? (cleaned ? "已把半截目录改名后清掉(" + staleDir + ")。" : "半截目录已改名成 " + staleDir + ",但没删掉(可能被占用),可以手工删。")
142
+ : "半截目录 " + entryDir + " 被占用,改名失败也没删(下次会重下覆盖)。";
143
+ return {
144
+ ...emptyResult(info.root, "download-failed", "模板没下下来(" + String(fetched.failed) + "/" + String(plan.targets.length) + " 个文件失败)。" + cleanupNote + "第一条失败原因:" + (failures[0] ?? "(未知)") + "。"
145
+ + (allNotFound ? "这几个文件在上游就是 404:多半是这一代/这一档的模板清单写错了(插件 bug),换型号没用,先走 HAL 路线或报告这个问题。" : "多半是网络/代理问题:换网络重试,或手动把 ST 固件包(STM32Cube_FW_F1_*)装到 CubeMX 的 Repository 里走 HAL 路线。")),
146
+ family: plan.family,
147
+ id: plan.id,
148
+ startup: choice.startup,
149
+ deviceDefine: choice.define,
150
+ deviceHeader: choice.deviceHeader,
151
+ };
152
+ }
153
+ // 每个下载的文件登记 sha256(A38):字节数挡不住"同样大小、内容被换掉"。
154
+ const files = fetched.results.map((outcome) => {
155
+ const item = { path: outcome.path, bytes: outcome.bytes, url: outcome.url };
156
+ try {
157
+ item.sha256 = sha256OfFile(path.join(entryDir, ...outcome.path.split("/")));
158
+ }
159
+ catch {
160
+ // 落盘文件读不出来就别登记哈希,校验时退回只看字节数。
161
+ }
162
+ return item;
163
+ });
164
+ const upstream = new Set();
165
+ for (const target of plan.targets)
166
+ for (const url of target.urls)
167
+ upstream.add(url);
168
+ // notices 也是条目的一部分,必须进 files[](A24):否则 checkCacheEntry 永远不校验它,
169
+ // 人手删掉之后索引照样显示"完整"。
170
+ const noticesName = "THIRD_PARTY_NOTICES.md";
171
+ const noticesPath = path.join(entryDir, noticesName);
172
+ fs.writeFileSync(noticesPath, plan.license, "utf8");
173
+ const noticesFile = { path: noticesName, bytes: Buffer.byteLength(plan.license, "utf8"), url: "" };
174
+ try {
175
+ noticesFile.sha256 = sha256OfFile(noticesPath);
176
+ }
177
+ catch {
178
+ // 同上。
179
+ }
180
+ files.push(noticesFile);
181
+ const totalBytes = fetched.bytes + noticesFile.bytes;
182
+ const entry = {
183
+ id: plan.id,
184
+ kind: "cmsis",
185
+ family: plan.family,
186
+ label: plan.family + " / " + choice.startup.replace(/\.s$/u, "") + "(CMSIS 设备头 + 启动文件 + 内核头)",
187
+ root: entryDir,
188
+ createdAt: new Date().toISOString(),
189
+ totalBytes,
190
+ files,
191
+ sources: Array.from(upstream).sort(),
192
+ license: plan.license,
193
+ };
194
+ upsertCacheEntry(entry, env);
195
+ request.onProgress?.("缓存已更新:" + plan.id);
196
+ return {
197
+ ok: true,
198
+ family: plan.family,
199
+ id: plan.id,
200
+ cacheRoot: info.root,
201
+ entryDir,
202
+ cacheHit: false,
203
+ startup: choice.startup,
204
+ deviceDefine: choice.define,
205
+ deviceHeader: choice.deviceHeader,
206
+ files: files.length,
207
+ bytes: totalBytes,
208
+ error: "",
209
+ message: "已下载 " + String(files.length) + " 个模板文件到缓存(" + entryDir + "),下次直接用。",
210
+ };
211
+ }
212
+ /**
213
+ * 从 HAL 骨架模板里借来的**与 HAL 无关**的文件(工具链、presets、.gitignore)。
214
+ *
215
+ * 链接脚本不在这张表里:它是寄存器路线里唯一必须按型号改的模板(ST 那份写死
216
+ * 64K FLASH / 20K RAM),所以从 HAL 骨架读原文本、改 MEMORY 两行、另存为
217
+ * <DeviceId>_FLASH.ld(见 register-linker.ts)。拷贝数不变,工程文件总数还是 7 个。
218
+ */
219
+ const SHARED_TEMPLATE_FILES = ["CMakePresets.json", ".gitignore", "cmake/gcc-arm-none-eabi.cmake", "openocd.cfg"];
220
+ /** 链接脚本的"源模板"(HAL 骨架里那份,按型号渲染后另存)。 */
221
+ const LINKER_TEMPLATE_FILE = "STM32F103XX_FLASH.ld";
222
+ function countFiles(root) {
223
+ let count = 0;
224
+ const walk = (dir) => {
225
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
226
+ if (entry.isDirectory())
227
+ walk(path.join(dir, entry.name));
228
+ else
229
+ count += 1;
230
+ }
231
+ };
232
+ if (fs.existsSync(root))
233
+ walk(root);
234
+ return count;
235
+ }
236
+ /**
237
+ * 建一个寄存器版工程:模板(CMakeLists + main.c)来自插件,CMSIS/启动文件来自缓存,
238
+ * 工具链与链接脚本复用 HAL 骨架里那几份**不含 HAL 内容**的文件。
239
+ */
240
+ export async function createRegisterProject(request) {
241
+ const startedAt = Date.now();
242
+ const targetDir = path.resolve(request.targetDir);
243
+ const projectName = request.projectName ?? path.basename(targetDir);
244
+ const mcu = (request.mcu ?? "STM32F103C8T6").trim();
245
+ const fail = (message, warnings = []) => ({
246
+ ok: false,
247
+ targetDir,
248
+ projectName,
249
+ route: "register",
250
+ mcu,
251
+ family: "",
252
+ startup: "",
253
+ deviceDefine: "",
254
+ deviceId: "",
255
+ linkerScript: "",
256
+ flashBytes: 0,
257
+ ramBytes: 0,
258
+ sysclkHz: 0,
259
+ clockSummary: "",
260
+ cacheRoot: cacheRootInfo(request.env ?? process.env).root,
261
+ cacheHit: false,
262
+ templateFiles: 0,
263
+ driverFiles: 0,
264
+ durationMs: Date.now() - startedAt,
265
+ warnings,
266
+ message,
267
+ });
268
+ // 先判"能不能写"(工程名 / 目录非空),下载和写盘都在后面:
269
+ // 工具层会在门禁之前先跑同一个判定(免得用户先装工具再撞第二个错),这里再来一次是为了
270
+ // 让直接调用引擎的人(测试、别的工具)也拿到同一套拒绝理由。
271
+ const refusal = preflightTarget({
272
+ targetDir,
273
+ projectName,
274
+ route: "register",
275
+ ...(request.overwrite === undefined ? {} : { overwrite: request.overwrite }),
276
+ });
277
+ if (refusal !== null)
278
+ return fail(refusal);
279
+ const template = await ensureCmsisTemplate({
280
+ ...(request.mcu === undefined ? {} : { mcu: request.mcu }),
281
+ ...(request.family === undefined ? {} : { family: request.family }),
282
+ ...(request.env === undefined ? {} : { env: request.env }),
283
+ ...(request.fetchImpl === undefined ? {} : { fetchImpl: request.fetchImpl }),
284
+ ...(request.hashes === undefined ? {} : { hashes: request.hashes }),
285
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
286
+ ...(request.onProgress === undefined ? {} : { onProgress: request.onProgress }),
287
+ ...(request.download === undefined ? {} : { download: request.download }),
288
+ });
289
+ if (!template.ok)
290
+ return fail(template.message);
291
+ const choice = resolveStartupChoice({ ...(request.mcu === undefined ? {} : { mcu: request.mcu }), ...(request.family === undefined ? {} : { family: request.family }) });
292
+ if (choice === null || cmsisTemplatePlan(choice) === null)
293
+ return fail("内部错误:缓存条目对应的下载清单没了(" + template.family + ")。");
294
+ const chip = choice.chip;
295
+ if (chip === undefined)
296
+ return fail("内部错误:缓存条目没带回芯片信息(" + template.family + ")。");
297
+ // 链接脚本与时钟初始化都按型号现算:寄存器路线没有 CubeMX 替我们算这两样,
298
+ // 写死 C8T6 的 64K/20K 与 8 MHz HSI 会让 F103ZE / F100C6 这类芯片要么链不下、要么跑得莫名其妙。
299
+ const linker = planRegisterLinker(chip);
300
+ const clock = planRegisterClock(chip);
301
+ const spec = CMSIS_FAMILIES[template.family];
302
+ if (spec === undefined)
303
+ return fail("内部错误:这一代没有设备头规格(" + template.family + ")。");
304
+ const familyDir = spec.deviceDefinePrefix + "xx";
305
+ const regTpl = registerTemplateDir();
306
+ const halTpl = templateDir();
307
+ if (!fs.existsSync(regTpl))
308
+ return fail("插件模板目录缺失:" + regTpl + "(重新安装插件)");
309
+ // 要读的模板文件、要拷的 Drivers,全部在**写盘之前**检查一遍:
310
+ // 半路才发现插件包缺文件,留下的就是一个比没有更糟的半成品工程。
311
+ // 例外:.gitignore 不在检查列表里——npm 打包永远排除点文件(.gitignore 同时是它的
312
+ // 忽略过滤器),npm 安装的用户模板里必然没有它;缺它只影响 git 状态观感,工程照建。
313
+ const missingOptional = [];
314
+ // 全量预检(0b):把所有缺失的必需文件一次列完,别让用户修一个跑一次再撞下一个。
315
+ const required = [
316
+ path.join(regTpl, "CMakeLists.txt"),
317
+ path.join(regTpl, "Core", "Src", "main.c"),
318
+ // 链接脚本模板:按型号渲染的那份是从它改出来的,缺了就只能建 C8T6 尺寸的工程
319
+ path.join(halTpl, LINKER_TEMPLATE_FILE),
320
+ ...SHARED_TEMPLATE_FILES.filter((rel) => rel !== ".gitignore").map((rel) => path.join(halTpl, rel)),
321
+ ];
322
+ const missingRequired = required.filter((source) => !fs.existsSync(source));
323
+ if (missingRequired.length > 0) {
324
+ const list = missingRequired.map((source) => " · " + source).join("\n");
325
+ return fail("插件模板缺 " + String(missingRequired.length) + " 个文件(一次列完):\n" + list +
326
+ "\n这是插件包损坏(安装中断或目录被杀毒软件动过),不是工程或配置的问题;" +
327
+ "带插件版本号(见 package.json)反馈最有效。");
328
+ }
329
+ if (!fs.existsSync(path.join(halTpl, ".gitignore")))
330
+ missingOptional.push(".gitignore");
331
+ const driversSrc = path.join(template.entryDir, "Drivers");
332
+ if (!fs.existsSync(driversSrc))
333
+ return fail("缓存的模板目录不完整(缺 Drivers):" + template.entryDir + "。删掉它再试一次会重新下载。");
334
+ // 覆盖前先备份将被覆盖的同名文件;备份失败就一个字节都不写(否则用户的 main.c 就没了)。
335
+ let backup;
336
+ try {
337
+ backup = backupBeforeOverwrite(targetDir, ["CMakeLists.txt", "Core/Src/main.c", linker.fileName, ...SHARED_TEMPLATE_FILES], "register");
338
+ }
339
+ catch (error) {
340
+ return fail("没写任何文件:覆盖前的备份失败(" + String(error.message) + ")。目标目录 " + targetDir + " 未被改动。");
341
+ }
342
+ const backupNote = backupWarning(backup);
343
+ // 1) 寄存器版 CMakeLists / main.c:替换七个占位符
344
+ const chipBanner = (chip.cpn.toUpperCase().startsWith("STM32") ? chip.cpn : "STM32F" + clock.line + "(" + chip.group + " 档)")
345
+ + " · " + linker.summary + " · SYSCLK " + String(Math.round(clock.sysclkHz / 1e6)) + " MHz";
346
+ const replacements = {
347
+ __PROJECT_NAME__: projectName,
348
+ __FAMILY_DIR__: familyDir,
349
+ __STARTUP_FILE__: template.startup,
350
+ __DEVICE_DEFINE__: template.deviceDefine,
351
+ __LINKER_SCRIPT__: linker.fileName,
352
+ __MCU_BANNER__: chipBanner,
353
+ __CLOCK_INIT__: renderClockInit(clock),
354
+ };
355
+ const fill = (text) => {
356
+ let out = text;
357
+ for (const [key, value] of Object.entries(replacements))
358
+ out = out.split(key).join(value);
359
+ return out;
360
+ };
361
+ // 链接脚本先渲染(纯字符串替换):模板被人改过导致四处标记缺一处时,要在写盘之前就拒绝,
362
+ // 而不是生成一个 RAM/Flash 尺寸错的工程——那种工程能编译、烧进去才崩。
363
+ const linkerText = renderLinkerScript(linker, fs.readFileSync(path.join(halTpl, LINKER_TEMPLATE_FILE), "utf8"));
364
+ if (linkerText === null) {
365
+ return fail("链接脚本模板里没找到该改的四处(MEMORY 的 RAM/FLASH 两行 + 注释两行):" + path.join(halTpl, LINKER_TEMPLATE_FILE) +
366
+ "。这是插件模板被改坏,不是工程问题;带插件版本号反馈最有效。一个字节都没写。");
367
+ }
368
+ const targetExistedBefore = fs.existsSync(targetDir);
369
+ const driversExistedBefore = fs.existsSync(path.join(targetDir, "Drivers"));
370
+ const createdDirs = [];
371
+ let templateFiles = 2;
372
+ try {
373
+ mkdirTracked(path.join(targetDir, "Core", "Src"), createdDirs);
374
+ mkdirTracked(path.join(targetDir, "Core", "Inc"), createdDirs);
375
+ // 1) CMakeLists.txt
376
+ fs.writeFileSync(path.join(targetDir, "CMakeLists.txt"), fill(fs.readFileSync(path.join(regTpl, "CMakeLists.txt"), "utf8")), "utf8");
377
+ // 2) 寄存器版 main.c:芯片注释 + 按型号生成的 clock_init()
378
+ fs.writeFileSync(path.join(targetDir, "Core", "Src", "main.c"), fill(fs.readFileSync(path.join(regTpl, "Core", "Src", "main.c"), "utf8")), "utf8");
379
+ // 3) 与 HAL 无关的公共文件:工具链 / presets(.gitignore 缺失时跳过,见上面 missingOptional)
380
+ for (const rel of SHARED_TEMPLATE_FILES) {
381
+ if (rel === ".gitignore" && missingOptional.includes(rel))
382
+ continue;
383
+ const dest = path.join(targetDir, rel);
384
+ mkdirTracked(path.dirname(dest), createdDirs);
385
+ fs.copyFileSync(path.join(halTpl, rel), dest);
386
+ templateFiles += 1;
387
+ }
388
+ // 4) 按型号渲染的链接脚本:MEMORY 两行 + 注释两行换成本芯片的真实 Flash/RAM
389
+ fs.writeFileSync(path.join(targetDir, linker.fileName), linkerText, "utf8");
390
+ templateFiles += 1;
391
+ // 5) CMSIS:缓存条目里的 Drivers 整棵拷进工程(与 HAL 工程布局一致)
392
+ fs.cpSync(driversSrc, path.join(targetDir, "Drivers"), { recursive: true });
393
+ }
394
+ catch (error) {
395
+ // Drivers 整棵是本次拷的(原来没有)→ 可以整棵删;原来就有(覆盖场景)则一个都不动。
396
+ if (!driversExistedBefore) {
397
+ try {
398
+ fs.rmSync(path.join(targetDir, "Drivers"), { recursive: true, force: true });
399
+ }
400
+ catch {
401
+ // 删不掉就留着:下面 cleanup 会说清哪个目录没清干净,但绝不递归删用户的文件。
402
+ }
403
+ }
404
+ const cleanup = cleanupAfterFailure(targetDir, targetExistedBefore, createdDirs);
405
+ return fail("写盘失败(已写 " + String(templateFiles) + " 个工程文件):" + String(error.message) + ";路径:" + targetDir + "。" + cleanup, backupNote === null ? [] : [backupNote]);
406
+ }
407
+ const driverFiles = countFiles(path.join(targetDir, "Drivers"));
408
+ const warnings = [];
409
+ if (missingOptional.includes(".gitignore")) {
410
+ warnings.push("插件包里没有 .gitignore(npm 打包会排除它):工程功能不受影响,只是 git 状态会多出 build/ 目录。" +
411
+ "想干净就在工程根目录建一个 .gitignore,内容一行:build/");
412
+ }
413
+ // 备份清单放第一条:用户看到"覆盖成功"时,第一眼得知道旧文件去哪了。
414
+ if (backupNote !== null)
415
+ warnings.push(backupNote);
416
+ warnings.push("模板里的 LED 是蓝丸的 PC13;换板子改 Core/Src/main.c 顶部的 LED_PORT / LED_PIN。", "寄存器版没有 .ioc:不需要 CubeMX,也不需要固件包;要换成 HAL 版就用 stm32_project_create route=hal。", "链接脚本已按型号渲染:" + linker.fileName + "(" + linker.summary + "),拷自 templates/scaffold/" + LINKER_TEMPLATE_FILE + "。", "时钟在 main.c 的 clock_init() 里现配:" + clock.summary + "(HSE 不起振就自动退回 HSI/2 ×" + String(clock.hsiMul) + ")。");
417
+ // 链接脚本/时钟的告警来自按型号推导本身(RAM 用了保守下限、F100 没有延迟位、HSI 到不了上限…),
418
+ // 用户需要知道"为什么是 64 MHz 而不是 72"。
419
+ warnings.push(...linker.warnings, ...clock.warnings);
420
+ if (template.cacheHit)
421
+ warnings.push("这次用的是缓存模板(" + template.entryDir + "),没有联网。");
422
+ else
423
+ warnings.push("模板已下载到缓存(" + template.entryDir + "),以后再建工程不联网。");
424
+ return {
425
+ ok: true,
426
+ targetDir,
427
+ projectName,
428
+ route: "register",
429
+ mcu,
430
+ family: template.family,
431
+ startup: template.startup,
432
+ deviceDefine: template.deviceDefine,
433
+ deviceId: linker.deviceId,
434
+ linkerScript: linker.fileName,
435
+ flashBytes: linker.flashBytes,
436
+ ramBytes: linker.ramBytes,
437
+ sysclkHz: clock.sysclkHz,
438
+ clockSummary: clock.summary,
439
+ cacheRoot: template.cacheRoot,
440
+ cacheHit: template.cacheHit,
441
+ templateFiles,
442
+ driverFiles,
443
+ durationMs: Date.now() - startedAt,
444
+ warnings,
445
+ message: "寄存器版工程已建好(" + String(templateFiles) + " 个工程文件 + " + String(driverFiles) + " 个 CMSIS 文件):" + targetDir +
446
+ ";芯片 " + chipBanner +
447
+ (backupNote === null ? "" : ";" + backupNote),
448
+ };
449
+ }
@@ -12,7 +12,7 @@ import { join, resolve } from "node:path";
12
12
  import { resolveSearchConfig } from "../data/search-roots.js";
13
13
  import { STATE_DIR } from "./generate.js";
14
14
  import { defaultConfigs, findProjectConfig, quoteForDisplay, toOpenOcdPath } from "./flash.js";
15
- import { resolveFromDirs } from "./probe.js";
15
+ import { resolveToolIn } from "./probe.js";
16
16
  import { runStreaming } from "./subprocess-runner.js";
17
17
  /** "4001100c" / "0x4001100C" → "0x4001100C";非法返回 null。 */
18
18
  export function normalizeAddress(input) {
@@ -108,7 +108,7 @@ export async function runRegsRead(subprocess, request) {
108
108
  const config = resolveSearchConfig(process.env, request.binDirs === undefined ? {} : { binDirs: request.binDirs });
109
109
  const openOcd = request.openOcdPath !== undefined && request.openOcdPath !== ""
110
110
  ? request.openOcdPath
111
- : resolveFromDirs("openocd", config.binDirs);
111
+ : await resolveToolIn(subprocess, ["openocd"], config.binDirs);
112
112
  if (openOcd === null) {
113
113
  return { ...base, ok: false, errors: ["找不到 openocd"], message: "没读:找不到 openocd" };
114
114
  }
@@ -124,9 +124,23 @@ export async function runRegsRead(subprocess, request) {
124
124
  }
125
125
  const script = buildRegsScript(addresses);
126
126
  const tmpDir = join(projectDir, STATE_DIR, "tmp");
127
- mkdirSync(tmpDir, { recursive: true });
128
127
  const scriptPath = join(tmpDir, "regs-" + String(startedAt) + ".tcl");
129
- writeFileSync(scriptPath, script, "utf8");
128
+ // A5:工程只读(Program Files、只读共享、库目录)时 mkdirSync 会直接抛,
129
+ // 以前整个工具崩成未捕获异常;现在干净失败,并说清是哪个路径写不进去。
130
+ try {
131
+ mkdirSync(tmpDir, { recursive: true });
132
+ writeFileSync(scriptPath, script, "utf8");
133
+ }
134
+ catch (error) {
135
+ const message = error instanceof Error ? error.message : String(error);
136
+ return {
137
+ ...base,
138
+ ok: false,
139
+ errors: ["写不了 openocd 脚本(" + scriptPath + "):" + message],
140
+ message: "没读:工程目录写不进临时脚本",
141
+ notes: [...notes, "工程目录可能只读;把工程放到可写位置,或先关掉占用它的程序再试。"],
142
+ };
143
+ }
130
144
  const args = [openOcd];
131
145
  for (const cfg of configs)
132
146
  args.push("-f", cfg);