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
@@ -5,6 +5,7 @@
5
5
  * 特别是"探针被谁占着"这个在 VS Code 调试与命令行工具之间最容易互相踩的问题。
6
6
  */
7
7
  import { runDoctor } from "../engine/doctor.js";
8
+ import { resolveProjectDir } from "./project-dir.js";
8
9
  export const DOCTOR_TOOL = "stm32_doctor";
9
10
  const toolSchema = {
10
11
  type: "object",
@@ -61,6 +62,14 @@ export const outputSchema = {
61
62
  missingRequired: { type: "array", items: { type: "string" } },
62
63
  tools: { type: "array", items: toolSchema },
63
64
  processes: { type: "array", items: processSchema },
65
+ usb: {
66
+ type: "object",
67
+ properties: {
68
+ kind: { type: "string", enum: ["no-usb", "no-dap", "driver-error", "ok", "unknown"] },
69
+ detail: { type: "string" },
70
+ },
71
+ required: ["kind", "detail"],
72
+ },
64
73
  port: { type: "number" },
65
74
  portBusy: { type: "boolean" },
66
75
  buildDir: { type: "string" },
@@ -73,7 +82,7 @@ export const outputSchema = {
73
82
  },
74
83
  required: [
75
84
  "ok", "projectDir", "message", "durationMs", "missingRequired", "tools", "processes",
76
- "port", "portBusy", "buildDir", "elfPath", "elfSize", "iocPath", "iocWarnings", "blockers", "notes",
85
+ "port", "portBusy", "buildDir", "elfPath", "elfSize", "iocPath", "iocWarnings", "usb", "blockers", "notes",
77
86
  ],
78
87
  },
79
88
  },
@@ -91,6 +100,7 @@ function formatReport(report) {
91
100
  lines.push("可疑进程:" + report.processes.map((process) => process.name + "(" + String(process.pid) + ")").join(" "));
92
101
  }
93
102
  lines.push("gdb 端口:" + String(report.port) + (report.portBusy ? "(被占用)" : "(空闲)"));
103
+ lines.push("USB:" + report.usb.kind + " — " + report.usb.detail);
94
104
  if (report.buildDir !== "")
95
105
  lines.push("构建目录:" + report.buildDir);
96
106
  if (report.elfPath !== "")
@@ -140,19 +150,22 @@ export function registerDoctor(ctx) {
140
150
  message: "宿主缺少 subprocess 服务,无法体检",
141
151
  report: {
142
152
  ok: false, projectDir: args.projectDir ?? "", message: "宿主缺少 subprocess 服务", durationMs: 0,
143
- missingRequired: ["subprocess"], tools: [], processes: [], port: args.port ?? 3333, portBusy: false,
153
+ missingRequired: ["subprocess"], tools: [], processes: [], usb: { kind: "unknown", detail: "宿主没有 subprocess 服务,无法诊断 USB/探针形态。" }, port: args.port ?? 3333, portBusy: false,
144
154
  buildDir: "", elfPath: "", elfSize: 0, iocPath: "", iocWarnings: [], blockers: ["宿主缺少 subprocess 服务"], notes: [],
145
155
  },
146
156
  };
147
157
  }
158
+ const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
148
159
  const report = await runDoctor(subprocess, {
149
- projectDir: args.projectDir ?? process.cwd(),
160
+ projectDir: resolution.projectDir,
150
161
  ...(args.binDirs === undefined ? {} : { binDirs: args.binDirs }),
151
162
  ...(args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots }),
152
163
  ...(args.port === undefined ? {} : { port: args.port }),
153
164
  ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
154
165
  signal: exec.signal,
155
166
  });
167
+ if (resolution.note !== null)
168
+ report.notes.push(resolution.note);
156
169
  return { message: report.message, report };
157
170
  },
158
171
  });
@@ -0,0 +1,472 @@
1
+ /**
2
+ * L3:stm32_env_install —— 把"这台机器缺工具链"变成一次可复核的安装。
3
+ *
4
+ * 为什么默认只出计划:装 MSYS2 要写几百 MB 磁盘、要从网上下安装包、还要改用户级 PATH,
5
+ * 这些都不是"看一眼"能顺手做的事。所以本工具先给一张卡片(装哪、下多大、做哪几步、要不要
6
+ * 决策),用户看过之后再说 confirm:true + dryRun:false 才真装。
7
+ *
8
+ * 为什么不做卸载:删目录这种事一旦做错没法撤销,而且用户自己的东西可能就放在那个目录里;
9
+ * 需要卸载就自己删目录 + 删配置项(nextStep / notes 会写清楚)。
10
+ *
11
+ * 为什么 PATH 只写用户级:机器级 PATH 要管理员权限,插件不请求提权;用户级 PATH 已经够让
12
+ * 命令行和其他工具找到 ucrt64\bin。
13
+ */
14
+ import { formatBytes, msys2StepSkeleton, planOrInstallMsys2, viaLabel, } from "../engine/msys2-install.js";
15
+ export const ENV_INSTALL_TOOL = "stm32_env_install";
16
+ /** 步骤状态的短标记:卡片上一眼能扫出哪一步没过去。 */
17
+ const STEP_MARK = {
18
+ pending: "[ ]",
19
+ running: "[..]",
20
+ done: "[OK]",
21
+ skipped: "[--]",
22
+ failed: "[!!]",
23
+ };
24
+ /**
25
+ * 合法的 pacman 包名形状:字母/数字/@/./_/+,且不以 - 开头。
26
+ * 为什么必须自己校验:包名会被原样拼进 "pacman -S --noconfirm --needed <包…>" 再交给 bash -lc——
27
+ * 以 - 开头会被 pacman 当成选项(等于把开关交给调用方),带空格/引号/& | ; $ 的还会被 bash 二次解释。
28
+ */
29
+ const PACKAGE_NAME_PATTERN = /^[A-Za-z0-9@._+][A-Za-z0-9@._+-]*$/u;
30
+ /** 挑出不合法的包名(原样返回,便于报错里点名);全部合法时是空数组。 */
31
+ export function invalidPackageNames(packages) {
32
+ return packages.filter((name) => !PACKAGE_NAME_PATTERN.test(name));
33
+ }
34
+ /* ------------------------------ schema ------------------------------ */
35
+ const stepSchema = {
36
+ type: "object",
37
+ description: "安装步骤及其结果",
38
+ additionalProperties: false,
39
+ properties: {
40
+ id: { type: "string" },
41
+ label: { type: "string" },
42
+ status: {
43
+ type: "string",
44
+ enum: ["pending", "running", "done", "skipped", "failed"],
45
+ },
46
+ detail: { type: "string" },
47
+ },
48
+ required: ["id", "label", "status", "detail"],
49
+ };
50
+ const downloadSchema = {
51
+ type: "object",
52
+ description: "安装包地址与体量",
53
+ additionalProperties: false,
54
+ properties: {
55
+ url: { type: "string" },
56
+ bytes: { type: "number" },
57
+ cached: { type: "boolean", description: "本机已有有效缓存,不会再下载" },
58
+ },
59
+ required: ["url", "bytes", "cached"],
60
+ };
61
+ const pathSchema = {
62
+ type: "object",
63
+ description: "用户级 PATH(HKCU\\Environment)的处理结果",
64
+ additionalProperties: false,
65
+ properties: {
66
+ done: { type: "boolean" },
67
+ changed: { type: "boolean" },
68
+ before: { type: "string" },
69
+ after: { type: "string" },
70
+ backup: { type: "string", description: "旧 PATH 的备份文件;没写 PATH 时为空串" },
71
+ error: { type: "string" },
72
+ },
73
+ required: ["done", "changed", "before", "after", "backup", "error"],
74
+ };
75
+ const configSchema = {
76
+ type: "object",
77
+ description: "工具链配置(~/.dsh-stm32/config.json)的写入结果",
78
+ additionalProperties: false,
79
+ properties: {
80
+ path: { type: "string" },
81
+ written: { type: "boolean" },
82
+ error: { type: "string" },
83
+ },
84
+ required: ["path", "written", "error"],
85
+ };
86
+ const verifyToolSchema = {
87
+ type: "object",
88
+ additionalProperties: false,
89
+ properties: {
90
+ id: { type: "string" },
91
+ label: { type: "string" },
92
+ found: { type: "boolean" },
93
+ version: { type: "string" },
94
+ },
95
+ required: ["id", "label", "found", "version"],
96
+ };
97
+ const verifySchema = {
98
+ type: "object",
99
+ description: "装完的自检结果",
100
+ additionalProperties: false,
101
+ properties: {
102
+ ok: { type: "boolean" },
103
+ tools: { type: "array", items: verifyToolSchema },
104
+ },
105
+ required: ["ok", "tools"],
106
+ };
107
+ const reportSchema = {
108
+ type: "object",
109
+ description: "安装计划 / 安装结果",
110
+ additionalProperties: false,
111
+ properties: {
112
+ ok: { type: "boolean" },
113
+ mode: { type: "string", enum: ["plan", "install"] },
114
+ needsDecision: {
115
+ type: "string",
116
+ enum: ["", "msys64Dir"],
117
+ description: "非空表示装哪还没定,什么都还没做",
118
+ },
119
+ msys64: { type: "string", description: "计划/实际安装根(正斜杠绝对路径)" },
120
+ resolvedVia: {
121
+ type: "string",
122
+ enum: ["arg", "config", "discovered", "suggested", ""],
123
+ description: "安装根是怎么定下来的",
124
+ },
125
+ binDirs: { type: "array", items: { type: "string" } },
126
+ packages: { type: "array", items: { type: "string" } },
127
+ steps: { type: "array", items: stepSchema },
128
+ download: downloadSchema,
129
+ path: pathSchema,
130
+ config: configSchema,
131
+ verify: verifySchema,
132
+ message: { type: "string" },
133
+ nextStep: { type: "string" },
134
+ notes: { type: "array", items: { type: "string" } },
135
+ durationMs: { type: "number" },
136
+ },
137
+ required: [
138
+ "ok",
139
+ "mode",
140
+ "needsDecision",
141
+ "msys64",
142
+ "resolvedVia",
143
+ "binDirs",
144
+ "packages",
145
+ "steps",
146
+ "download",
147
+ "path",
148
+ "config",
149
+ "verify",
150
+ "message",
151
+ "nextStep",
152
+ "notes",
153
+ "durationMs",
154
+ ],
155
+ };
156
+ export const outputSchema = {
157
+ type: "object",
158
+ description: "stm32_env_install 的结果:后台作业句柄 + 计划/安装报告",
159
+ additionalProperties: false,
160
+ properties: {
161
+ mode: {
162
+ type: "string",
163
+ enum: ["job", "report"],
164
+ description: "job = 真装在后台跑(用 job_output 读进度);report = 同步返回",
165
+ },
166
+ jobId: { type: "string" },
167
+ message: { type: "string" },
168
+ report: reportSchema,
169
+ },
170
+ required: ["mode", "jobId", "message", "report"],
171
+ };
172
+ /**
173
+ * 缺服务/提前错误时也要给完整形状。
174
+ * 为什么不能省字段:宿主按 output.schema 严格校验,缺字段或 null 会让整个工具结果不可读。
175
+ */
176
+ function emptyReport(message, mode) {
177
+ return {
178
+ ok: false,
179
+ mode,
180
+ needsDecision: "",
181
+ msys64: "",
182
+ resolvedVia: "",
183
+ binDirs: [],
184
+ packages: [],
185
+ steps: [],
186
+ download: { url: "", bytes: 0, cached: false },
187
+ path: { done: false, changed: false, before: "", after: "", backup: "", error: "" },
188
+ config: { path: "", written: false, error: "" },
189
+ verify: { ok: false, tools: [] },
190
+ message,
191
+ nextStep: "",
192
+ notes: [],
193
+ durationMs: 0,
194
+ };
195
+ }
196
+ /** 引擎允许 download 为 null(没有下载这个概念),schema 不允许 null:这里归一成空结构。 */
197
+ function toToolReport(report) {
198
+ return {
199
+ ...report,
200
+ download: report.download ?? { url: "", bytes: 0, cached: false },
201
+ };
202
+ }
203
+ /* ------------------------------ 文字卡 ------------------------------ */
204
+ export function formatInstallReport(report, running = false) {
205
+ const lines = [];
206
+ // running:后台 job 还没跑完就返回的那张卡片。此时 report 是"要做的事"的骨架,
207
+ // 套「安装未完成」会读成失败,所以单独给一个「安装进行中」的抬头。
208
+ const headline = running
209
+ ? "安装进行中"
210
+ : report.mode === "install"
211
+ ? report.ok
212
+ ? "安装完成"
213
+ : "安装未完成"
214
+ : report.needsDecision === ""
215
+ ? ""
216
+ : "需要决定安装位置";
217
+ // 计划模式的 message 自己已经把语气写全了("计划(还没动手):…"),再套一层标题会重复。
218
+ lines.push(headline === "" ? report.message : headline + ":" + report.message);
219
+ if (report.msys64 !== "") {
220
+ lines.push("安装位置:" + report.msys64 + "(来源:" + viaLabel(report.resolvedVia) + ")");
221
+ }
222
+ if (report.download !== null) {
223
+ lines.push("安装包:" +
224
+ report.download.url +
225
+ "(" +
226
+ formatBytes(report.download.bytes) +
227
+ (report.download.cached ? ",本机已缓存" : ",需要下载") +
228
+ ")");
229
+ }
230
+ if (report.packages.length > 0)
231
+ lines.push("组件:" + report.packages.join("、"));
232
+ if (report.steps.length > 0) {
233
+ lines.push("步骤:");
234
+ for (const step of report.steps) {
235
+ lines.push(" " + STEP_MARK[step.status] + " " + step.label);
236
+ if (step.detail !== "") {
237
+ for (const part of step.detail.split("\n"))
238
+ lines.push(" " + part);
239
+ }
240
+ }
241
+ }
242
+ if (report.path.changed) {
243
+ lines.push("用户 PATH:已追加" +
244
+ (report.path.backup === "" ? "" : "(旧值备份 " + report.path.backup + ")"));
245
+ }
246
+ else if (report.path.done) {
247
+ lines.push("用户 PATH:已包含目标 bin 目录,没有重复写");
248
+ }
249
+ else if (report.path.error !== "") {
250
+ // 计划模式根本没去写注册表:措辞不能是「没写成功」(那读起来像写坏了)。
251
+ const head = report.mode === "plan" ? "用户 PATH:不会写 —— " : "用户 PATH:没写成功 —— ";
252
+ lines.push(head + (report.path.error.split("\n")[0] ?? ""));
253
+ }
254
+ else if (report.path.after !== "" && report.path.after !== report.path.before) {
255
+ lines.push("用户 PATH:真装时会追加一条(写前先备份旧值)");
256
+ }
257
+ else {
258
+ lines.push("用户 PATH:不动");
259
+ }
260
+ if (report.config.written) {
261
+ lines.push("配置:已写入 " + report.config.path);
262
+ }
263
+ else if (report.config.error !== "") {
264
+ lines.push("配置:写失败 —— " + report.config.error);
265
+ }
266
+ else if (report.config.path !== "") {
267
+ lines.push("配置:" + report.config.path + "(还没写入)");
268
+ }
269
+ if (report.verify.tools.length > 0) {
270
+ lines.push("自检:" + (report.verify.ok ? "全部可用" : "有缺失"));
271
+ for (const item of report.verify.tools) {
272
+ lines.push(" " + (item.found ? "OK " : "MISS") + " " + item.id + (item.version === "" ? "" : " " + item.version));
273
+ }
274
+ }
275
+ else if (report.mode === "plan") {
276
+ lines.push("自检:真装完成后按安装目录跑 gcc / cmake / ninja / openocd / gdb 的版本命令");
277
+ }
278
+ if (report.notes.length > 0) {
279
+ lines.push("说明:");
280
+ for (const note of report.notes)
281
+ lines.push(" · " + note);
282
+ }
283
+ if (report.nextStep !== "")
284
+ lines.push("下一步:" + report.nextStep);
285
+ return lines;
286
+ }
287
+ /* ------------------------------ 注册 ------------------------------ */
288
+ export function registerEnvInstall(ctx) {
289
+ ctx.tools.register({
290
+ name: ENV_INSTALL_TOOL,
291
+ description: "安装/补装 STM32 工具链(MSYS2 + arm-none-eabi-gcc / gdb-multiarch / openocd / cmake / ninja)。" +
292
+ "默认只出计划:列出装到哪、安装包多大、要做哪几步,不下载、不建目录、不写注册表、不改配置。" +
293
+ "真装必须同时给 dryRun:false 与 confirm:true;装到哪先按 targetDir > 配置 msys64 > 自动发现决定," +
294
+ "都没有就返回 needsDecision 并建议 C:/msys64,绝不猜路径。" +
295
+ "PATH 只写用户级(HKCU\\Environment,写前备份,已在其中就不重复写),不请求管理员权限。" +
296
+ "刻意不做卸载:要删就删安装目录并去掉配置里的 msys64 / binDirs。",
297
+ parameters: {
298
+ type: "object",
299
+ additionalProperties: false,
300
+ properties: {
301
+ targetDir: {
302
+ type: "string",
303
+ description: "MSYS2 安装根目录(正斜杠绝对路径,例如 D:/msys64);不给就从配置/自动发现里找",
304
+ },
305
+ packages: {
306
+ type: "array",
307
+ items: { type: "string" },
308
+ description: "要 pacman 装的包;不给就用默认的 5 个工具链组件",
309
+ },
310
+ dryRun: {
311
+ type: "boolean",
312
+ description: "默认 true:只出计划。必须是 false 才可能真装(且还要 confirm:true)",
313
+ },
314
+ confirm: {
315
+ type: "boolean",
316
+ description: "确认真的动磁盘/网络/注册表;默认 false",
317
+ },
318
+ writePath: {
319
+ type: "boolean",
320
+ description: "是否把 <msys64>/ucrt64/bin 追加到用户级 PATH;默认 true(失败不致命)",
321
+ },
322
+ foreground: {
323
+ type: "boolean",
324
+ description: "true = 同步等装完再返回;默认后台 job(用 job_output 看进度)",
325
+ },
326
+ timeoutMs: {
327
+ type: "number",
328
+ description: "下载/解压/pacman 单步超时,默认 15 分钟",
329
+ },
330
+ },
331
+ required: [],
332
+ },
333
+ timeoutMs: 30 * 60_000,
334
+ isConcurrencySafe: () => false,
335
+ output: {
336
+ schema: outputSchema,
337
+ render: (_args, value) => {
338
+ const typed = value;
339
+ // job 模式的 report 已经是 mode="install" 的骨架,抬头由 running 控制(不能再叠一遍 message)。
340
+ const lines = formatInstallReport(typed.report, typed.mode === "job");
341
+ if (typed.mode === "job") {
342
+ // 真正的进度在 job 输出里,卡片只负责说清"去哪儿看"。
343
+ lines.push("job:" + typed.jobId + "(用 job_output 读进度,job_kill 停止)");
344
+ }
345
+ return [{ type: "text", text: lines.join("\n") }];
346
+ },
347
+ },
348
+ async execute(rawArgs, exec) {
349
+ const args = rawArgs ?? {};
350
+ const subprocess = ctx.get("subprocess");
351
+ // 只有"明确说不 dryRun"且"明确确认"才算真装:两个开关都到位,用户才真的点了头。
352
+ const realInstall = args.dryRun === false && args.confirm === true;
353
+ const mode = realInstall ? "install" : "plan";
354
+ if (subprocess === undefined) {
355
+ const report = emptyReport("宿主缺少 subprocess 服务,无法安装工具链", mode);
356
+ return { mode: "report", jobId: "", message: report.message, report };
357
+ }
358
+ // A33:包名先过一遍白名单。绝不把调用方给的字符串直接拼进 pacman 命令行(也不做猜测式改名)。
359
+ if (args.packages !== undefined) {
360
+ const invalid = invalidPackageNames(args.packages);
361
+ if (invalid.length > 0) {
362
+ const report = emptyReport("包名不合法:" +
363
+ invalid.map((name) => JSON.stringify(name)).join("、") +
364
+ ";没有执行任何命令,也没下载任何东西(不会替你猜或改名)。", mode);
365
+ report.nextStep =
366
+ "用 pacman 的完整包名重试,例如 mingw-w64-ucrt-x86_64-cmake;多个包用数组分别给。";
367
+ report.notes = [
368
+ "包名会原样拼进 pacman 的命令行:以 - 开头会被 pacman 当成选项,带空格或引号、& | ; $ 等字符会被 bash 二次解释,所以这里先拒掉。",
369
+ "合法形状:字母 / 数字 / @ / . / _ / +,且第一个字符不能是 -。",
370
+ ];
371
+ return { mode: "report", jobId: "", message: report.message, report };
372
+ }
373
+ }
374
+ const base = {
375
+ ...(args.targetDir === undefined ? {} : { targetDir: args.targetDir }),
376
+ ...(args.packages === undefined ? {} : { packages: args.packages }),
377
+ writePath: args.writePath !== false,
378
+ ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
379
+ };
380
+ // 真装前也先算一次计划:卡片上先把"装哪、多大、做什么"讲清楚 —— 计划本身零副作用,
381
+ // 而且装了没定位置时正好在这里把 needsDecision 交给用户。
382
+ const plan = toToolReport(await planOrInstallMsys2(subprocess, { ...base, mode: "plan", signal: exec.signal }, process.env));
383
+ if (!realInstall) {
384
+ return { mode: "report", jobId: "", message: plan.message, report: plan };
385
+ }
386
+ if (plan.needsDecision !== "") {
387
+ // 装哪都不知道就别开 job:先说清楚需要用户决定什么。
388
+ return { mode: "report", jobId: "", message: plan.message, report: plan };
389
+ }
390
+ const jobs = ctx.get("jobs");
391
+ if (args.foreground === true || jobs === undefined) {
392
+ const report = toToolReport(await planOrInstallMsys2(subprocess, { ...base, mode: "install", signal: exec.signal }, process.env));
393
+ return { mode: "report", jobId: "", message: report.message, report };
394
+ }
395
+ // 下载 + 解压 + pacman 是分钟级:默认丢后台,前端可以边看进度边等。
396
+ const controller = new AbortController();
397
+ const jobId = jobs.start({
398
+ kind: "stm32-env-install",
399
+ label: ENV_INSTALL_TOOL + " " + plan.msys64,
400
+ ...(exec.agent === undefined ? {} : { owner: exec.agent.id }),
401
+ run: (handle) => {
402
+ handle.append("开始安装 MSYS2:" + plan.msys64 + "(来源:" + viaLabel(plan.resolvedVia) + ")\n");
403
+ // A36:工具被取消时 job 也得停。job_kill 走下面的 cancel(),宿主取消整个工具(或用户按了停止)
404
+ // 走 exec.signal —— 两条路都要把 controller 掐掉,否则后台还在下载/解压。
405
+ const bridgeAbort = () => controller.abort();
406
+ if (exec.signal.aborted)
407
+ controller.abort();
408
+ exec.signal.addEventListener("abort", bridgeAbort);
409
+ const detach = () => exec.signal.removeEventListener("abort", bridgeAbort);
410
+ const done = planOrInstallMsys2(subprocess, {
411
+ ...base,
412
+ mode: "install",
413
+ signal: controller.signal,
414
+ // 每步开始一行:用户能在 job 输出里看到"现在在干什么",而不是干等。
415
+ onProgress: (line) => handle.append(line + "\n"),
416
+ }, process.env)
417
+ .then((result) => {
418
+ detach();
419
+ const report = toToolReport(result);
420
+ handle.append("\n" + formatInstallReport(report).join("\n") + "\n");
421
+ return {
422
+ status: report.ok ? "completed" : "failed",
423
+ detail: report.message,
424
+ };
425
+ })
426
+ // 引擎正常情况下不抛(失败都写进 report),但取消/内部异常若漏出来,
427
+ // 不能让 job 卡在 running:留一句中文原因,job 标记失败。
428
+ .catch((error) => {
429
+ detach();
430
+ const reason = error instanceof Error ? error.message : String(error);
431
+ const text = (controller.signal.aborted ? "已取消:" : "安装异常终止:") + reason;
432
+ handle.append("\n" + text + "\n");
433
+ return { status: "failed", detail: text };
434
+ });
435
+ return {
436
+ done,
437
+ cancel: (reason) => {
438
+ handle.append("\n被取消:" + (reason ?? "用户停止") + "\n");
439
+ controller.abort();
440
+ },
441
+ };
442
+ },
443
+ });
444
+ // 卡片上的 message 必须说"正在装",不能把计划模式的"还没动手"贴在一个真在跑的 job 上。
445
+ const startMessage = "已在后台安装 MSYS2 到 " +
446
+ plan.msys64 +
447
+ "(来源:" +
448
+ viaLabel(plan.resolvedVia) +
449
+ "):7 步依次跑,进度看 job 输出。";
450
+ // A21:卡片不能贴计划快照(那会写着"还没动手 / 全 pending / 配置没写",跟真在跑的 job 打架)。
451
+ // 这里给"安装中"的骨架:mode=install、步骤全 pending(detail 保留将要执行的命令)、
452
+ // 配置/自检/PATH 的结论都留空,等 job 输出里再报。
453
+ const runningReport = {
454
+ ...plan,
455
+ mode: "install",
456
+ ok: false,
457
+ // 计划在"什么都不用做"时只回一句话(steps 为空),但真装 job 仍要把 7 步列出来。
458
+ steps: (plan.steps.length > 0 ? plan.steps : msys2StepSkeleton()).map((step) => ({
459
+ ...step,
460
+ status: "pending",
461
+ })),
462
+ path: { done: false, changed: false, before: plan.path.before, after: plan.path.after, backup: "", error: "" },
463
+ config: { path: plan.config.path, written: false, error: "" },
464
+ verify: { ok: false, tools: [] },
465
+ message: startMessage,
466
+ nextStep: "",
467
+ notes: plan.notes.filter((note) => !note.startsWith("这只是计划")),
468
+ };
469
+ return { mode: "job", jobId, message: startMessage, report: runningReport };
470
+ },
471
+ });
472
+ }
@@ -7,7 +7,7 @@
7
7
  * - 顶层给 capabilities(四项能力是否可用)、recommendations(先装什么、什么可选、要不要我帮你装)、
8
8
  * searched(这次查了哪些目录),缺件时不必再猜路径。
9
9
  */
10
- import { describeSearchScope, resolveSearchConfig } from "../data/search-roots.js";
10
+ import { describeSearchScope, resolveSearchConfig, searchConfigWarnings } from "../data/search-roots.js";
11
11
  import { buildTargets, probeAll } from "../engine/probe.js";
12
12
  export const ENV_PROBE_TOOL = "stm32_env_probe";
13
13
  const probeItemSchema = {
@@ -229,7 +229,11 @@ export function registerEnvProbe(ctx) {
229
229
  summary,
230
230
  missingRequired,
231
231
  capabilities,
232
- recommendations: computeRecommendations(results, missingRequired, capabilities),
232
+ recommendations: [
233
+ // 配置里点名但本机不存在的目录先说出来:否则"我明明配了"会变成一句莫名其妙的失败。
234
+ ...searchConfigWarnings(process.env).map((warning) => "⚠ " + warning.message),
235
+ ...computeRecommendations(results, missingRequired, capabilities),
236
+ ],
233
237
  searched: computeSearched(config.binDirs, config.cubeMxRoots),
234
238
  tools: results,
235
239
  };