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,255 @@
1
+ /**
2
+ * L3:stm32_firmware_install —— 把"这台机器缺固件包"变成一次可复核的下载。
3
+ *
4
+ * 为什么默认只出计划:要联网下 ~2 MB、要往 CubeMX 目录(dsh-firmware)或用户缓存里写目录,
5
+ * 用户看过"装哪、下多少、做哪几步"再说 confirm:true + dryRun:false 才真下。
6
+ *
7
+ * 为什么不代装 CubeMX 本体:那是 GUI 向导 + 要 ST 账号,没法静默装(见 install-guides.ts)。
8
+ * 固件包不一样 —— 它就是一棵目录树 + 一个 257 字节的 package.xml,可以完全自动化。
9
+ */
10
+ import { firmwareInstallPlan, installFirmware } from "../engine/firmware-install.js";
11
+ import { resolveSearchConfig } from "../data/search-roots.js";
12
+ export const FIRMWARE_INSTALL_TOOL = "stm32_firmware_install";
13
+ const STEP_MARK = {
14
+ pending: "[ ]",
15
+ running: "[..]",
16
+ done: "[OK]",
17
+ skipped: "[--]",
18
+ failed: "[!!]",
19
+ };
20
+ /* ------------------------------ schema ------------------------------ */
21
+ const stepSchema = {
22
+ type: "object",
23
+ description: "安装步骤及其结果",
24
+ additionalProperties: false,
25
+ properties: {
26
+ id: { type: "string" },
27
+ label: { type: "string" },
28
+ status: { type: "string", enum: ["pending", "running", "done", "skipped", "failed"] },
29
+ detail: { type: "string" },
30
+ },
31
+ required: ["id", "label", "status", "detail"],
32
+ };
33
+ const checkSchema = {
34
+ type: "object",
35
+ additionalProperties: false,
36
+ properties: {
37
+ label: { type: "string" },
38
+ path: { type: "string" },
39
+ ok: { type: "boolean" },
40
+ },
41
+ required: ["label", "path", "ok"],
42
+ };
43
+ const reportSchema = {
44
+ type: "object",
45
+ description: "固件包下载/组装计划或结果",
46
+ additionalProperties: false,
47
+ properties: {
48
+ ok: { type: "boolean" },
49
+ mode: { type: "string", enum: ["plan", "install"] },
50
+ family: { type: "string" },
51
+ version: { type: "string" },
52
+ packageName: { type: "string", description: "STM32Cube_FW_F1_V1.8.7 这样的目录名" },
53
+ targetKind: { type: "string", enum: ["existing", "cubeMx", "repository", "cache", "custom", ""] },
54
+ targetDir: { type: "string" },
55
+ cacheRoot: { type: "string" },
56
+ cubeMxRoots: { type: "array", items: { type: "string" } },
57
+ steps: { type: "array", items: stepSchema },
58
+ verify: {
59
+ type: "object",
60
+ additionalProperties: false,
61
+ properties: {
62
+ ok: { type: "boolean" },
63
+ checks: { type: "array", items: checkSchema },
64
+ },
65
+ required: ["ok", "checks"],
66
+ },
67
+ download: {
68
+ type: "object",
69
+ additionalProperties: false,
70
+ properties: {
71
+ files: { type: "number" },
72
+ bytes: { type: "number" },
73
+ },
74
+ required: ["files", "bytes"],
75
+ },
76
+ notes: { type: "array", items: { type: "string" } },
77
+ message: { type: "string" },
78
+ nextStep: { type: "string" },
79
+ },
80
+ required: [
81
+ "ok",
82
+ "mode",
83
+ "family",
84
+ "version",
85
+ "packageName",
86
+ "targetKind",
87
+ "targetDir",
88
+ "cacheRoot",
89
+ "cubeMxRoots",
90
+ "steps",
91
+ "verify",
92
+ "download",
93
+ "notes",
94
+ "message",
95
+ "nextStep",
96
+ ],
97
+ };
98
+ export const outputSchema = {
99
+ type: "object",
100
+ additionalProperties: false,
101
+ properties: {
102
+ mode: { type: "string", enum: ["job", "report"] },
103
+ jobId: { type: "string" },
104
+ message: { type: "string" },
105
+ report: reportSchema,
106
+ },
107
+ required: ["mode", "jobId", "message", "report"],
108
+ };
109
+ /* ------------------------------ 文字卡 ------------------------------ */
110
+ export function formatFirmwareReport(report) {
111
+ const lines = [];
112
+ lines.push(report.message);
113
+ if (report.packageName !== "") {
114
+ lines.push("固件包:" + report.packageName + "(" + report.version + ")");
115
+ }
116
+ if (report.targetDir !== "") {
117
+ lines.push("位置:" + report.targetDir + "(" + report.targetKind + ")");
118
+ }
119
+ if (report.steps.length > 0) {
120
+ lines.push("步骤:");
121
+ for (const step of report.steps) {
122
+ lines.push(" " + STEP_MARK[step.status] + " " + step.label);
123
+ if (step.detail !== "") {
124
+ for (const part of step.detail.split("\n"))
125
+ lines.push(" " + part);
126
+ }
127
+ }
128
+ }
129
+ if (report.verify.checks.length > 0) {
130
+ lines.push("自检:" + (report.verify.ok ? "三条判据全过" : "有缺失"));
131
+ for (const check of report.verify.checks) {
132
+ lines.push(" " + (check.ok ? "OK " : "MISS") + " " + check.label);
133
+ }
134
+ }
135
+ if (report.notes.length > 0) {
136
+ lines.push("说明:");
137
+ for (const note of report.notes)
138
+ lines.push(" · " + note);
139
+ }
140
+ if (report.nextStep !== "")
141
+ lines.push("下一步:" + report.nextStep);
142
+ return lines;
143
+ }
144
+ /* ------------------------------ 注册 ------------------------------ */
145
+ export function registerFirmwareInstall(ctx) {
146
+ ctx.tools.register({
147
+ name: FIRMWARE_INSTALL_TOOL,
148
+ description: "下载并组装 STM32 固件包(STM32Cube_FW_<族>_V<版本>),默认装到 <CubeMX>/dsh-firmware(与 Repository 并列,不动官方包)。" +
149
+ "从 GitHub 拉 HAL 驱动与 CMSIS 设备支持两个子模块仓库 + 5 个内核头,自己补 package.xml。" +
150
+ "重要:实测把自造版本号丢进 Repository 会被 CubeMX 静默忽略,真正生效的是生成脚本里的 project setCustomFWPath —— 那一步由 stm32_generate 自动做。" +
151
+ "默认只出计划:列出装到哪、下多大、做哪几步,不下载、不建目录。真装必须同时给 dryRun:false 与 confirm:true。已有官方包时什么都不做。",
152
+ parameters: {
153
+ type: "object",
154
+ additionalProperties: false,
155
+ properties: {
156
+ family: { type: "string", description: "芯片族,例如 F1;不给就用 mcu 推" },
157
+ mcu: { type: "string", description: "芯片型号,例如 STM32F103C8T6" },
158
+ version: { type: "string", description: "包版本(不带 V),默认 1.8.7" },
159
+ target: {
160
+ type: "string",
161
+ enum: ["auto", "repository", "cache"],
162
+ description: "装哪:auto(默认,装到 <CubeMX>/dsh-firmware;CubeMX 目录不可写才落用户缓存)/ repository(硬塞官方仓库)/ cache(只落用户缓存)",
163
+ },
164
+ targetDir: { type: "string", description: "直接指定包目录(自定义布局用,跳过自动选址)" },
165
+ cubeMxRoot: { type: "string", description: "CubeMX 安装根;不给就用配置/自动发现" },
166
+ dryRun: { type: "boolean", description: "默认 true:只出计划。必须是 false 才可能真下" },
167
+ confirm: { type: "boolean", description: "确认真的联网下载并写磁盘;默认 false" },
168
+ foreground: { type: "boolean", description: "true = 同步等装完;默认后台 job" },
169
+ },
170
+ required: [],
171
+ },
172
+ timeoutMs: 15 * 60_000,
173
+ isConcurrencySafe: () => false,
174
+ output: {
175
+ schema: outputSchema,
176
+ render: (_args, value) => {
177
+ const typed = value;
178
+ const lines = formatFirmwareReport(typed.report);
179
+ if (typed.mode === "job") {
180
+ lines.unshift(typed.message);
181
+ lines.push("job:" + typed.jobId + "(用 job_output 读进度,job_kill 停止)");
182
+ }
183
+ return [{ type: "text", text: lines.join("\n") }];
184
+ },
185
+ },
186
+ async execute(rawArgs, exec) {
187
+ const args = rawArgs ?? {};
188
+ const realInstall = args.dryRun === false && args.confirm === true;
189
+ const config = resolveSearchConfig(process.env, args.cubeMxRoot === undefined ? {} : { cubeMxRoots: [args.cubeMxRoot] });
190
+ const base = {
191
+ ...(args.family === undefined ? {} : { family: args.family }),
192
+ ...(args.mcu === undefined ? {} : { mcu: args.mcu }),
193
+ ...(args.version === undefined ? {} : { version: args.version }),
194
+ ...(args.target === undefined ? {} : { target: args.target }),
195
+ ...(args.targetDir === undefined ? {} : { targetDir: args.targetDir }),
196
+ cubeMxRoots: config.cubeMxRoots,
197
+ };
198
+ const plan = firmwareInstallPlan({ ...base, env: process.env });
199
+ if (!realInstall || plan.targetKind === "existing" || !plan.ok) {
200
+ return { mode: "report", jobId: "", message: plan.message, report: plan };
201
+ }
202
+ const jobs = ctx.get("jobs");
203
+ if (args.foreground === true || jobs === undefined) {
204
+ const report = await installFirmware({ ...base, mode: "install", env: process.env, signal: exec.signal });
205
+ return { mode: "report", jobId: "", message: report.message, report };
206
+ }
207
+ const controller = new AbortController();
208
+ const onAbort = () => controller.abort();
209
+ exec.signal.addEventListener("abort", onAbort, { once: true });
210
+ const jobId = jobs.start({
211
+ kind: "stm32-firmware-install",
212
+ label: FIRMWARE_INSTALL_TOOL + " " + plan.packageName,
213
+ ...(exec.agent === undefined ? {} : { owner: exec.agent.id }),
214
+ run: (handle) => {
215
+ handle.append("开始下载 " + plan.packageName + " → " + plan.targetDir + "\n");
216
+ const done = installFirmware({
217
+ ...base,
218
+ mode: "install",
219
+ env: process.env,
220
+ signal: controller.signal,
221
+ onProgress: (line) => handle.append(line + "\n"),
222
+ })
223
+ .then((report) => {
224
+ handle.append("\n" + formatFirmwareReport(report).join("\n") + "\n");
225
+ return { status: report.ok ? "completed" : "failed", detail: report.message };
226
+ })
227
+ .catch((error) => {
228
+ // 不接住这个 reject,job 会永远停在 running(审计 A36)。
229
+ const text = error instanceof Error ? error.message : String(error);
230
+ handle.append("\n安装异常终止:" + text + "\n");
231
+ return { status: "failed", detail: "安装异常终止:" + text };
232
+ })
233
+ .finally(() => {
234
+ // 取消要一直有效,直到这次安装真的结束;以前这里返回到期就摘掉了监听。
235
+ exec.signal.removeEventListener("abort", onAbort);
236
+ });
237
+ return {
238
+ done,
239
+ cancel: (reason) => {
240
+ handle.append("\n被取消:" + (reason ?? "用户停止") + "\n");
241
+ controller.abort();
242
+ },
243
+ };
244
+ },
245
+ });
246
+ const startMessage = "已在后台下载固件包 " + plan.packageName + " → " + plan.targetDir + ",进度看 job 输出。";
247
+ return {
248
+ mode: "job",
249
+ jobId,
250
+ message: startMessage,
251
+ report: { ...plan, mode: "install", message: startMessage },
252
+ };
253
+ },
254
+ });
255
+ }
@@ -7,6 +7,8 @@
7
7
  */
8
8
  import { runFlash } from "../engine/flash.js";
9
9
  import { releaseProbeFor } from "../engine/debug-session.js";
10
+ import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
11
+ import { resolveProjectDir } from "./project-dir.js";
10
12
  export const FLASH_TOOL = "stm32_flash";
11
13
  const reportSchema = {
12
14
  type: "object",
@@ -28,6 +30,7 @@ const reportSchema = {
28
30
  logTail: { type: "string" },
29
31
  notes: { type: "array", items: { type: "string" } },
30
32
  guard: { type: "string" },
33
+ errorCode: { type: "string", enum: ["", "no-probe", "probe-busy", "swd-locked", "flash-protected", "no-power", "target-mismatch", "unknown"] },
31
34
  },
32
35
  required: ["ok", "projectDir", "elfPath", "elfSize", "command", "args", "durationMs", "programmed", "verified", "errors", "message", "logTail", "notes"],
33
36
  };
@@ -40,6 +43,12 @@ export const outputSchema = {
40
43
  },
41
44
  required: ["message", "report"],
42
45
  };
46
+ /** 门禁档位参数:三个档位的说明文字与 build 工具保持一致。 */
47
+ const ENV_CHECK_SCHEMA = {
48
+ type: "string",
49
+ enum: ["block", "warn", "off"],
50
+ description: "工具链检查:block 缺件就拒绝(默认)、warn 只警告、off 不检查",
51
+ };
43
52
  export function formatFlashReport(report) {
44
53
  const lines = [];
45
54
  lines.push((report.ok ? "烧录成功" : "烧录失败") + ":" + report.message);
@@ -50,6 +59,8 @@ export function formatFlashReport(report) {
50
59
  if (report.command !== "")
51
60
  lines.push("命令:" + report.command);
52
61
  lines.push("写入=" + (report.programmed ? "是" : "否") + ",校验=" + (report.verified ? "是" : "否"));
62
+ if (report.errorCode !== undefined && report.errorCode !== "")
63
+ lines.push("错误码:[" + report.errorCode + "]");
53
64
  for (const note of report.notes)
54
65
  lines.push("· " + note);
55
66
  for (const error of report.errors.slice(0, 10))
@@ -73,10 +84,12 @@ export function registerFlash(ctx) {
73
84
  elfPath: { type: "string", description: "显式指定要烧的 .elf;缺省从构建目录推断。" },
74
85
  buildDir: { type: "string", description: "显式构建目录;缺省自动推断(优先 Debug)。" },
75
86
  configFile: { type: "string", description: "openocd 配置文件(相对工程目录);缺省找 openocd.cfg。" },
87
+ iocPath: { type: "string", description: "SWD 守卫要看的 .ioc(工程里有多个 .ioc 时用它指定)。" },
76
88
  adapterSpeed: { type: "number", description: "adapter speed(kHz);连不上时可降到 1000 或 100。" },
77
89
  timeoutMs: { type: "number", description: "超时毫秒数,默认 120000。" },
78
90
  allowNoDebug: { type: "boolean", description: ".ioc 里没有 Serial Wire 时是否仍然烧录(默认 false:拒绝,避免烧掉 SWD)。" },
79
91
  binDirs: { type: "array", items: { type: "string" }, description: "工具链目录候选,优先于默认值。" },
92
+ envCheck: ENV_CHECK_SCHEMA,
80
93
  },
81
94
  required: [],
82
95
  },
@@ -96,25 +109,51 @@ export function registerFlash(ctx) {
96
109
  const report = emptyReport("宿主缺少 subprocess 服务,无法烧录");
97
110
  return { message: report.message, report };
98
111
  }
99
- // 探针只有一块:有调试会话占着就先让它让出来(规格 §6)。
112
+ const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
113
+ // 门禁:烧录只需要 openocd。缺件且 envCheck=block 时连 openocd 都不起,
114
+ // 免得"探针被占 / 连不上"这类假象盖住真正的原因。
115
+ const gate = await ensureToolchain(ctx, {
116
+ capability: "flash",
117
+ ...(args.binDirs === undefined ? {} : { binDirs: args.binDirs }),
118
+ envCheck: args.envCheck,
119
+ signal: exec.signal,
120
+ });
121
+ if (!gate.ok && gate.mode === "block") {
122
+ const blocked = blockedReport(resolution.projectDir, gate);
123
+ return { message: blocked.message, report: blocked };
124
+ }
125
+ // 探针只有一块:门禁通过后才让调试会话让出来(B16:缺件时不该把别人的探针收走)。
100
126
  const released = await releaseProbeFor("stm32_flash");
101
127
  const report = await runFlash(subprocess, {
102
- projectDir: args.projectDir ?? process.cwd(),
128
+ projectDir: resolution.projectDir,
103
129
  ...(args.elfPath === undefined ? {} : { elfPath: args.elfPath }),
104
130
  ...(args.buildDir === undefined ? {} : { buildDir: args.buildDir }),
105
131
  ...(args.configFile === undefined ? {} : { configFile: args.configFile }),
132
+ ...(args.iocPath === undefined ? {} : { iocPath: args.iocPath }),
106
133
  ...(args.adapterSpeed === undefined ? {} : { adapterSpeed: args.adapterSpeed }),
107
134
  ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
108
135
  ...(args.binDirs === undefined ? {} : { binDirs: args.binDirs }),
109
136
  ...(args.allowNoDebug === undefined ? {} : { allowNoDebug: args.allowNoDebug }),
110
137
  signal: exec.signal,
111
138
  });
139
+ if (!gate.ok)
140
+ report.notes.unshift(gate.message);
112
141
  if (released !== null)
113
142
  report.notes.push(released);
143
+ if (resolution.note !== null)
144
+ report.notes.push(resolution.note);
114
145
  return { message: report.message, report };
115
146
  },
116
147
  });
117
148
  }
149
+ /** 门禁拒绝时的报告:形如 emptyReport,但 notes 换成"缺什么、装在哪"。 */
150
+ function blockedReport(projectDir, gate) {
151
+ return {
152
+ ok: false, projectDir, elfPath: "", elfSize: 0, command: "", args: [], configs: [],
153
+ durationMs: 0, programmed: false, verified: false,
154
+ errors: [], message: gate.message, logTail: "", notes: gateReportNotes(gate),
155
+ };
156
+ }
118
157
  function emptyReport(message) {
119
158
  return {
120
159
  ok: false, projectDir: "", elfPath: "", elfSize: 0, command: "", args: [], configs: [],
@@ -6,6 +6,8 @@
6
6
  */
7
7
  import { runGenerate } from "../engine/generate.js";
8
8
  import { releaseProbeFor } from "../engine/debug-session.js";
9
+ import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
10
+ import { resolveProjectDir } from "./project-dir.js";
9
11
  export const GENERATE_TOOL = "stm32_generate";
10
12
  const verdictSchema = {
11
13
  type: "object",
@@ -26,7 +28,7 @@ const fileSchema = {
26
28
  target: { type: "string" },
27
29
  action: {
28
30
  type: "string",
29
- enum: ["created", "overwritten", "skipped-no-user-code-markers", "would-write"],
31
+ enum: ["created", "overwritten", "skipped-no-user-code-markers", "skipped-encoding", "would-write", "unchanged-cached"],
30
32
  },
31
33
  preserved: { type: "array", items: { type: "string" } },
32
34
  droppedLabels: { type: "array", items: { type: "string" } },
@@ -42,6 +44,20 @@ const reportSchema = {
42
44
  iocPath: { type: "string" },
43
45
  layout: { type: "string", enum: ["coupled", "per-ip"] },
44
46
  durationMs: { type: "number" },
47
+ skipped: { type: "boolean" },
48
+ cacheKey: { type: "string" },
49
+ thirdparty: {
50
+ type: "object",
51
+ additionalProperties: false,
52
+ properties: {
53
+ parked: { type: "boolean" },
54
+ detail: { type: "string" },
55
+ },
56
+ required: ["parked", "detail"],
57
+ },
58
+ firmwareDir: { type: "string" },
59
+ firmwarePackage: { type: "string" },
60
+ firmwareSource: { type: "string", enum: ["repository", "dsh-firmware", "cache", "custom", ""] },
45
61
  message: { type: "string" },
46
62
  script: { type: "string" },
47
63
  command: { type: "string" },
@@ -51,7 +67,7 @@ const reportSchema = {
51
67
  files: { type: "array", items: fileSchema },
52
68
  notes: { type: "array", items: { type: "string" } },
53
69
  },
54
- required: ["ok", "projectDir", "iocPath", "layout", "durationMs", "message", "script", "command", "logTail", "backupDir", "verdict", "files", "notes"],
70
+ required: ["ok", "projectDir", "iocPath", "layout", "durationMs", "skipped", "cacheKey", "thirdparty", "message", "script", "command", "logTail", "backupDir", "verdict", "files", "notes"],
55
71
  };
56
72
  export const outputSchema = {
57
73
  type: "object",
@@ -64,6 +80,24 @@ export const outputSchema = {
64
80
  },
65
81
  required: ["mode", "jobId", "message"],
66
82
  };
83
+ /** 门禁档位参数:三个档位的说明文字与 build 工具保持一致。 */
84
+ const ENV_CHECK_SCHEMA = {
85
+ type: "string",
86
+ enum: ["block", "warn", "off"],
87
+ description: "工具链检查:block 缺件就拒绝(默认)、warn 只警告、off 不检查",
88
+ };
89
+ /** 固件包来源的中文标签;引擎侧的 firmwareSourceLabel 是同一套措辞(工具层不额外依赖引擎模块)。 */
90
+ function firmwareSourceText(source) {
91
+ if (source === "repository")
92
+ return "CubeMX 仓库";
93
+ if (source === "dsh-firmware")
94
+ return "插件的 dsh-firmware 目录";
95
+ if (source === "cache")
96
+ return "插件的下载缓存";
97
+ if (source === "custom")
98
+ return "调用方指定的目录";
99
+ return "来源未知";
100
+ }
67
101
  function formatReport(report) {
68
102
  const lines = [];
69
103
  lines.push((report.ok ? "生成成功" : "生成失败") + ":" + report.message);
@@ -72,6 +106,13 @@ function formatReport(report) {
72
106
  lines.push(".ioc:" + report.iocPath + "(布局 " + report.layout + ")");
73
107
  if (report.durationMs > 0)
74
108
  lines.push("耗时:" + (report.durationMs / 1000).toFixed(1) + " s");
109
+ if (report.skipped)
110
+ lines.push("本次没有跑 CubeMX:直接复用上次生成结果(产物 hash 全部一致)");
111
+ if (report.firmwareDir !== "") {
112
+ lines.push("固件包:" + report.firmwarePackage + "(" + firmwareSourceText(report.firmwareSource) + ")");
113
+ }
114
+ if (report.thirdparty.detail !== "")
115
+ lines.push("第三方包索引:" + report.thirdparty.detail);
75
116
  if (report.verdict.successLine !== "")
76
117
  lines.push("CubeMX:" + report.verdict.successLine);
77
118
  for (const error of report.verdict.errors.slice(0, 5))
@@ -98,10 +139,22 @@ function formatReport(report) {
98
139
  function summarize(report) {
99
140
  return report.message;
100
141
  }
142
+ /** 门禁拒绝时的报告:jobs 一条都不起,字段按 outputSchema.required 补齐。 */
143
+ function blockedReport(projectDir, gate) {
144
+ return {
145
+ ok: false, projectDir, iocPath: "", layout: "coupled", durationMs: 0, skipped: false,
146
+ cacheKey: "",
147
+ thirdparty: { parked: false, detail: "" },
148
+ firmwareDir: "", firmwarePackage: "", firmwareSource: "",
149
+ message: gate.message, script: "", command: "", logTail: "", backupDir: "",
150
+ verdict: { ok: false, successLine: "", errors: [], knownNoise: [] },
151
+ files: [], notes: gateReportNotes(gate),
152
+ };
153
+ }
101
154
  export function registerGenerate(ctx) {
102
155
  ctx.tools.register({
103
156
  name: GENERATE_TOOL,
104
- description: "用 STM32CubeMX 无头模式(java -jar STM32CubeMX.exe -q)按 .ioc 生成代码,并把产物从 Src/Inc 落位到工程的 Core/Src、Core/Inc;目标文件已存在时搬运 USER CODE 区内容,覆盖前备份到 .dsh-stm32/backups。默认后台运行(3–4 分钟),返回 jobId,用 job_output 看进度;foreground=true 则同步返回完整报告。dryRun=true 只生成不改工程(CubeMX 仍会写 Src/Inc)。",
157
+ description: "用 STM32CubeMX 无头模式(java -jar STM32CubeMX.exe -q)按 .ioc 生成代码,并把产物从 Src/Inc 落位到工程的 Core/Src、Core/Inc;目标文件已存在时搬运 USER CODE 区内容,覆盖前备份到 .dsh-stm32/backups。默认后台运行(首次 3–4 分钟),返回 jobId,用 job_output 看进度;foreground=true 则同步返回完整报告。dryRun=true 只生成不改工程(CubeMX 仍会写 Src/Inc)。skipIfUnchanged(默认 true)让 .ioc 没变时直接复用上次产物、跳过 CubeMX;thirdpartyPacks=auto 在没有 X-CUBE 扩展包的工程里生成期间临时停放第三方包索引(省约 25 s,结束自动还原)。只改 USER CODE、不动 .ioc 的日常循环不需要重新生成,改动只需 stm32_build + stm32_flash。",
105
158
  parameters: {
106
159
  type: "object",
107
160
  additionalProperties: false,
@@ -114,8 +167,18 @@ export function registerGenerate(ctx) {
114
167
  description: "生成布局。auto 按现有 Core/Src/main.c 的 USER CODE 标签推断;coupled 把外设初始化并入 main.c(ST 默认工程);per-ip 每外设一对 .c/.h。",
115
168
  },
116
169
  dryRun: { type: "boolean", description: "只跑 CubeMX 并给出落位计划,不改动 Core/**。" },
170
+ skipIfUnchanged: {
171
+ type: "boolean",
172
+ description: "默认 true:.ioc、CubeMX 版本、布局都没变且产物 hash 全部一致时直接复用上次结果,不跑 CubeMX(3–4 分钟 → 0 s)。传 false 强制重新生成。",
173
+ },
174
+ thirdpartyPacks: {
175
+ type: "string",
176
+ enum: ["auto", "keep"],
177
+ description: "第三方包索引(~/.stm32cubemx/thirdparties/pdsc)策略。auto(默认)= .ioc 没有 X-CUBE/第三方包时生成期间临时停放,省约 25 s,结束后自动还原;keep = 始终原样加载。",
178
+ },
117
179
  foreground: { type: "boolean", description: "同步执行并返回完整报告(默认 false,走后台 job)。" },
118
180
  cubeMxRoots: { type: "array", items: { type: "string" }, description: "STM32CubeMX 安装根目录候选,优先于默认值/环境变量。" },
181
+ envCheck: ENV_CHECK_SCHEMA,
119
182
  timeoutMs: { type: "number", description: "超时毫秒数,默认 600000(10 分钟)。" },
120
183
  },
121
184
  required: [],
@@ -138,7 +201,20 @@ export function registerGenerate(ctx) {
138
201
  if (subprocess === undefined) {
139
202
  return { mode: "report", jobId: "", message: "宿主缺少 subprocess 服务,无法生成代码" };
140
203
  }
141
- const projectDir = args.projectDir ?? process.cwd();
204
+ const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
205
+ const projectDir = resolution.projectDir;
206
+ // 门禁:无头生成要 CubeMX 启动器 + 它自带的 JRE。缺件时不必等 3–4 分钟才报错。
207
+ const gate = await ensureToolchain(ctx, {
208
+ capability: "generate",
209
+ ...(args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots }),
210
+ envCheck: args.envCheck,
211
+ signal: exec.signal,
212
+ });
213
+ if (!gate.ok && gate.mode === "block") {
214
+ const blocked = blockedReport(projectDir, gate);
215
+ return { mode: "report", jobId: "", message: blocked.message, report: blocked };
216
+ }
217
+ const gateNote = gate.ok ? null : gate.message;
142
218
  // CubeMX 生成期间别让 openocd 占着探针(单飞,规格 I5)。
143
219
  const released = await releaseProbeFor("stm32_generate");
144
220
  const jobs = ctx.get("jobs");
@@ -149,38 +225,49 @@ export function registerGenerate(ctx) {
149
225
  ...(args.iocPath === undefined ? {} : { iocPath: args.iocPath }),
150
226
  ...(args.layout === undefined ? {} : { layout: args.layout }),
151
227
  ...(args.dryRun === undefined ? {} : { dryRun: args.dryRun }),
228
+ ...(args.skipIfUnchanged === undefined ? {} : { skipIfUnchanged: args.skipIfUnchanged }),
229
+ ...(args.thirdpartyPacks === undefined ? {} : { thirdpartyPacks: args.thirdpartyPacks }),
152
230
  ...(args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots }),
153
231
  ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
154
232
  signal: exec.signal,
155
233
  });
234
+ if (gateNote !== null)
235
+ report.notes.unshift(gateNote);
156
236
  if (released !== null)
157
237
  report.notes.push(released);
238
+ if (resolution.note !== null)
239
+ report.notes.push(resolution.note);
158
240
  return { mode: "report", jobId: "", message: summarize(report), report };
159
241
  }
160
242
  const registry = jobs;
161
243
  const controller = new AbortController();
162
- let report = null;
163
244
  const jobId = registry.start({
164
245
  kind: "stm32-generate",
165
246
  label: "stm32_generate " + projectDir,
166
247
  ...(exec.agent === undefined ? {} : { owner: exec.agent.id }),
167
248
  run: (handle) => {
168
- handle.append("开始无头生成:" + projectDir + "\n");
249
+ if (gateNote !== null)
250
+ handle.append(gateNote + "\n");
251
+ // A35:后台模式下也要看得到「探针已让出 / 会话已停」,否则之后 eval 报没会话时无从追溯。
252
+ if (released !== null)
253
+ handle.append(released + "\n");
254
+ handle.append("开始无头生成:" + projectDir + "\n" + (resolution.note === null ? "" : resolution.note + "\n"));
169
255
  const done = runGenerate(subprocess, {
170
256
  projectDir,
171
257
  ...(args.iocPath === undefined ? {} : { iocPath: args.iocPath }),
172
258
  ...(args.layout === undefined ? {} : { layout: args.layout }),
173
259
  ...(args.dryRun === undefined ? {} : { dryRun: args.dryRun }),
260
+ ...(args.skipIfUnchanged === undefined ? {} : { skipIfUnchanged: args.skipIfUnchanged }),
261
+ ...(args.thirdpartyPacks === undefined ? {} : { thirdpartyPacks: args.thirdpartyPacks }),
174
262
  ...(args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots }),
175
263
  ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
176
264
  signal: controller.signal,
177
265
  onProgress: (line) => handle.append(line + "\n"),
178
266
  }).then((result) => {
179
- report = result;
180
267
  handle.append("\n" + formatReport(result).join("\n") + "\n");
181
268
  return {
182
269
  status: result.ok ? "completed" : "failed",
183
- detail: result.ok ? result.message : result.message,
270
+ detail: result.message,
184
271
  };
185
272
  });
186
273
  return {
@@ -192,11 +279,10 @@ export function registerGenerate(ctx) {
192
279
  };
193
280
  },
194
281
  });
195
- void report;
196
282
  return {
197
283
  mode: "job",
198
284
  jobId,
199
- message: "已在后台开始生成 " + projectDir + "(CubeMX 启动约 90–150 s,整体 3–4 分钟)",
285
+ message: "已在后台开始生成 " + projectDir + (resolution.note === null ? "" : "(" + resolution.note + ")") + "(CubeMX 启动约 90–150 s,整体 3–4 分钟)",
200
286
  };
201
287
  },
202
288
  });