dsh-stm32 0.1.6 → 0.1.7

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 (98) hide show
  1. package/README.md +517 -517
  2. package/README_EN.md +510 -510
  3. package/client/client.js +24 -24
  4. package/lib/client.js +24 -24
  5. package/lib/commands/register.js +5 -5
  6. package/lib/data/chips.js +4 -4
  7. package/lib/data/clock-db.js +24 -24
  8. package/lib/data/clock-f1.js +2 -2
  9. package/lib/data/cmsis-sources.js +6 -6
  10. package/lib/data/db-presets.js +4 -4
  11. package/lib/data/device-facts.js +6 -6
  12. package/lib/data/family.js +16 -16
  13. package/lib/data/firmware-packages.js +10 -10
  14. package/lib/data/install-guides.js +18 -18
  15. package/lib/data/ioc-presets.js +3 -3
  16. package/lib/data/ioc-schema.js +32 -32
  17. package/lib/data/rm-topics.js +6 -6
  18. package/lib/data/search-roots.js +62 -16
  19. package/lib/data/serial-config.js +7 -7
  20. package/lib/data/stm32f1.js +1 -1
  21. package/lib/data/svd.js +7 -7
  22. package/lib/data/toolchain-config.js +3 -3
  23. package/lib/engine/assets.js +5 -5
  24. package/lib/engine/breakpoints.js +5 -5
  25. package/lib/engine/cache.js +4 -4
  26. package/lib/engine/clock-derived.js +2 -2
  27. package/lib/engine/clock-direct.js +3 -3
  28. package/lib/engine/clock-plan.js +7 -7
  29. package/lib/engine/clock-pllmn.js +6 -6
  30. package/lib/engine/cmake-sources.js +9 -9
  31. package/lib/engine/code-patch.js +5 -5
  32. package/lib/engine/cube-mx-guard.js +3 -3
  33. package/lib/engine/cube-programmer.js +4 -4
  34. package/lib/engine/cubemx-db.js +7 -7
  35. package/lib/engine/debug-session.js +12 -12
  36. package/lib/engine/debug.js +3 -3
  37. package/lib/engine/doctor.js +12 -12
  38. package/lib/engine/download.js +1 -1
  39. package/lib/engine/facts-acquire.js +3 -3
  40. package/lib/engine/fetch.js +2 -2
  41. package/lib/engine/firmware-install.js +16 -16
  42. package/lib/engine/firmware-official.js +8 -8
  43. package/lib/engine/flash.js +22 -22
  44. package/lib/engine/fs-longpath.js +1 -1
  45. package/lib/engine/gdb-mi.js +7 -7
  46. package/lib/engine/generate-script.js +2 -2
  47. package/lib/engine/generate.js +17 -17
  48. package/lib/engine/hal-chip.js +7 -7
  49. package/lib/engine/ioc-plan.js +52 -52
  50. package/lib/engine/ioc-rules.js +9 -9
  51. package/lib/engine/ioc-verify.js +34 -34
  52. package/lib/engine/msys2-install.js +50 -50
  53. package/lib/engine/probe-error.js +8 -8
  54. package/lib/engine/probe-session.js +3 -3
  55. package/lib/engine/probe.js +47 -50
  56. package/lib/engine/project-export.js +1 -1
  57. package/lib/engine/register-clock.js +5 -5
  58. package/lib/engine/register-gpio.js +3 -3
  59. package/lib/engine/register-linker.js +7 -7
  60. package/lib/engine/register-template.js +22 -22
  61. package/lib/engine/regs.js +3 -3
  62. package/lib/engine/rm-extract.js +2 -2
  63. package/lib/engine/rm-sources.js +1 -1
  64. package/lib/engine/route-plan.js +9 -9
  65. package/lib/engine/rtt.js +18 -18
  66. package/lib/engine/scaffold.js +22 -22
  67. package/lib/engine/serial.js +24 -24
  68. package/lib/engine/tar.js +1 -1
  69. package/lib/engine/text-file.js +1 -1
  70. package/lib/engine/thirdparty.js +3 -3
  71. package/lib/engine/tool-env.js +2 -2
  72. package/lib/engine/toolchain-gate.js +8 -8
  73. package/lib/engine/usercode-merge.js +2 -2
  74. package/lib/engine/vscode-config.js +2 -2
  75. package/lib/engine/web-api.js +1 -1
  76. package/lib/engine/xcube-catalog.js +1 -1
  77. package/lib/index.js +5 -5
  78. package/lib/skill/stm32-workflow.js +1 -1
  79. package/lib/tools/assets.js +1 -1
  80. package/lib/tools/cache.js +2 -2
  81. package/lib/tools/debug-session.js +5 -5
  82. package/lib/tools/doctor.js +2 -2
  83. package/lib/tools/download.js +1 -1
  84. package/lib/tools/env-install.js +3 -3
  85. package/lib/tools/firmware-install.js +5 -5
  86. package/lib/tools/flash.js +8 -8
  87. package/lib/tools/generate.js +1 -1
  88. package/lib/tools/ioc-apply.js +1 -1
  89. package/lib/tools/ioc-plan.js +1 -1
  90. package/lib/tools/ioc-verify.js +11 -11
  91. package/lib/tools/project-create.js +4 -4
  92. package/lib/tools/project-dir.js +1 -1
  93. package/lib/tools/regs.js +10 -10
  94. package/lib/tools/route-plan.js +9 -9
  95. package/lib/tools/rtt.js +9 -9
  96. package/lib/tools/serial.js +8 -8
  97. package/package.json +70 -70
  98. package/templates/scaffold/RTT.md +26 -34
@@ -95,7 +95,7 @@ export function diagnoseUsb(pnputilText) {
95
95
  const probes = parseProbeVidPid(pnputilText);
96
96
  const swdProbes = probes.filter((p) => p.kind === "st-link" || p.kind === "jlink" || p.kind === "cmsis-dap" || p.kind === "daplink");
97
97
  // CH341/CH340 串口桥:2a 扩表的历史契约——"板载探针走串口透传"的形态真实存在,算在线;
98
- // 但它不是 SWD 驱动,不参与 interface 选择(preferredInterfaceConfig 也不认它)。
98
+ // 但该文件不是 SWD 驱动,不参与 interface 选择(preferredInterfaceConfig 同样不识别)。
99
99
  const serialBridges = probes.filter((p) => p.kind === "ch341-serial");
100
100
  const hasDriverProblem = /(?:Problem Code|问题代码)\s*[::]?\s*(?:1[0-9]|2[0-8]|3[0-9]|4[0-3]|5[0-2])/iu.test(pnputilText);
101
101
  const list = swdProbes.map((p) => p.label).join("、");
@@ -142,7 +142,7 @@ export function diagnoseUsb(pnputilText) {
142
142
  };
143
143
  }
144
144
  export async function usbDiagnosis(subprocess, signal) {
145
- // 只读枚举;pnputil 不存在(老系统)或被组策略拦时返回 unknown,绝不让诊断把 doctor 搞挂。
145
+ // 只读枚举;pnputil 不存在(旧系统)或被组策略拦截时返回 unknown,诊断异常不得导致 doctor 失败。
146
146
  try {
147
147
  const outcome = await runCapture(subprocess, {
148
148
  argv: ["pnputil", "/enum-devices", "/connected"],
@@ -170,7 +170,7 @@ export async function usbDiagnosis(subprocess, signal) {
170
170
  }
171
171
  }
172
172
  /**
173
- * 引擎各处(flash / debug / regs / 会话)兜底 interface 的统一入口。
173
+ * 引擎各处(flash / debug / regs / 会话)回退 interface 的统一入口。
174
174
  *
175
175
  * 刻意**不做模块级缓存**:第一版把 60 s 的结果缓存在模块里,同进程连烧两颗不同芯片时
176
176
  * 第二颗会拿到第一颗的探针结论(重试方向还会因此算反),测试里表现为用例互相污染。
@@ -252,9 +252,9 @@ export function recommendationsOf(tools, missingRequired, capabilities) {
252
252
  const step = item.install[0] ?? item.hint;
253
253
  lines.push(item.label + ":" + step + "(自检:" + item.verify + ")");
254
254
  }
255
- lines.push("需要我帮你装吗?回一句「装 gcc」「装 openocd」或「把缺的都装上」,我就照上面的命令在这台机器上装,装完再跑一次 stm32_doctor 复测;你也可以自己装完再跑一次。");
255
+ lines.push("如需安装,回复「装 gcc」「装 openocd」或「把缺的都装上」,将按上面的命令在本机安装,安装完成后再次运行 stm32_doctor 复测;也可自行安装后再次运行。");
256
256
  }
257
- // gdb/openocd 不再恒为 required(只编译的机器不该被它们拦),但缺了要明确说影响哪条腿。
257
+ // gdb/openocd 不再恒为 required(仅编译的机器不应被这两个组件拦截),但缺失时需明确说明影响的功能。
258
258
  const gdb = tools.find((item) => item.id === "gdb");
259
259
  if (!capabilities.flashOpenocd) {
260
260
  const openocd = tools.find((item) => item.id === "openocd");
@@ -264,7 +264,7 @@ export function recommendationsOf(tools, missingRequired, capabilities) {
264
264
  lines.push("openocd:" + (openocd.install[0] ?? openocd.hint) + "(自检:" + openocd.verify + ")");
265
265
  }
266
266
  else {
267
- lines.push("烧录只能走 CubeProgrammer:它只认 ST-LINK,DAPLink/J-Link 与非 ST 探针仍需 openocd。");
267
+ lines.push("烧录只能使用 CubeProgrammer:该后端只认 ST-LINK,DAPLink/J-Link 与非 ST 探针仍需 openocd。");
268
268
  }
269
269
  }
270
270
  if (!capabilities.debug) {
@@ -506,7 +506,7 @@ export function checkChipConsistency(input) {
506
506
  const cmakeText = input.cmakeText ?? null;
507
507
  const cmakeDefines = cmakeText === null ? [] : deviceDefinesIn(cmakeText);
508
508
  if (cmakeText === null) {
509
- notes.push("没有 " + CUBEMX_CMAKE_REL + ":跳过设备宏一致性检查(不是 ST 的 CMake 布局?)");
509
+ notes.push("没有 " + CUBEMX_CMAKE_REL + ":跳过设备宏一致性检查(可能不是 ST 的 CMake 布局)");
510
510
  }
511
511
  else if (cmakeDefines.length === 0) {
512
512
  notes.push(CUBEMX_CMAKE_REL + " 里没有 STM32 设备宏(set(MX_Defines_Syms ...)):跳过设备宏一致性检查");
@@ -529,12 +529,12 @@ export function checkChipConsistency(input) {
529
529
  }
530
530
  else if (memory !== null) {
531
531
  if (memory.flashBytes === null) {
532
- notes.push(linkerLabel + " 里读不到 FLASH 区的 LENGTH(不是 MEMORY 写法?):没校验 Flash 容量");
532
+ notes.push(linkerLabel + " 里读不到 FLASH 区的 LENGTH(可能不是 MEMORY 写法):未校验 Flash 容量");
533
533
  }
534
534
  else if (chip !== null && chip.flashBytes !== null) {
535
535
  if (memory.flashBytes > chip.flashBytes) {
536
536
  blockers.push(linkerLabel + " 的 FLASH 是 " + kib(memory.flashBytes) + ",超过芯片 " + chip.cpn + " 的 " + kib(chip.flashBytes) +
537
- "(链接器会照它放代码,超出物理容量的部分写不进去)");
537
+ "(链接器按该值放置代码,超出物理容量的部分无法写入)");
538
538
  }
539
539
  else if (memory.flashBytes < chip.flashBytes) {
540
540
  notes.push(linkerLabel + " 只给了 " + kib(memory.flashBytes) + " Flash,芯片 " + chip.cpn + " 有 " + kib(chip.flashBytes) +
@@ -577,12 +577,12 @@ export function checkChipConsistency(input) {
577
577
  if (pins.kind === "db" && iocPins.length > 0) {
578
578
  const unknown = iocPins.filter((pin) => !pins.pins.includes(pin));
579
579
  if (unknown.length > 0) {
580
- notes.push(".ioc 里这些引脚不在本机 db 的 " + (mcuName === "" ? cpn : mcuName) + " 封装里:" + unknown.join("、") + "(型号或封装选错了?)");
580
+ notes.push(".ioc 里这些引脚不在本机 db 的 " + (mcuName === "" ? cpn : mcuName) + " 封装里:" + unknown.join("、") + "(型号或封装可能选错)");
581
581
  }
582
582
  }
583
583
  return { blockers, notes, chip, memory, pins };
584
584
  }
585
- /** 从工程读事实再判:runDoctor 用它把四项一致性接进报告(不 spawn、不写盘)。 */
585
+ /** 从工程读取事实后判定:runDoctor 通过该函数把四项一致性检查接入报告(不 spawn、不写盘)。 */
586
586
  export function collectChipConsistency(projectDir, options) {
587
587
  const startupFiles = listStartupFiles(projectDir);
588
588
  let cmakeText = null;
@@ -687,7 +687,7 @@ export async function runDoctor(subprocess, request) {
687
687
  const openOcdProcesses = processes.filter((process) => process.name.toLowerCase() === "openocd.exe");
688
688
  if (openOcdProcesses.length > 0) {
689
689
  blockers.push("有 openocd 正在运行(PID " + openOcdProcesses.map((process) => String(process.pid)).join(", ") +
690
- "),它很可能占着 CMSIS-DAP 探针;先结束这些进程再烧录/调试");
690
+ "),该进程很可能占用 CMSIS-DAP 探针;先结束这些进程再烧录/调试");
691
691
  }
692
692
  if (portBusy) {
693
693
  blockers.push("gdb 端口 " + String(port) + " 已被监听(可能是上一次调试会话没退干净),debug_run/flash 会顺延或失败");
@@ -31,7 +31,7 @@ const ST_PAGES = {
31
31
  cubeprogrammer: {
32
32
  label: "STM32CubeProgrammer",
33
33
  page: "https://www.st.com/en/development-tools/stm32cubeprog.html",
34
- installHint: "从官方页登录 myST、接受许可并下载安装包;默认路径会被 stm32_doctor 自动发现。它的 SWD 路径只认 ST-LINK。",
34
+ installHint: "从官方页登录 myST、接受许可并下载安装包;默认路径会被 stm32_doctor 自动发现。其 SWD 路径只认 ST-LINK。",
35
35
  },
36
36
  };
37
37
  export class DownloadError extends Error {
@@ -48,7 +48,7 @@ function nodeText(node, tag) {
48
48
  * A. 首选按外设收:<peripheral> 的 name==FLASH 下的**全部** <register>。
49
49
  * modm 的寄存器命名逐族不同——C0 带前缀(FLASH_ACR/FLASH_OPTR/FLASH_SECR)、
50
50
  * F1 不带(ACR/OBR/CR…);写死名字清单等于拿 C0 约定套全族,F1 会解析出 0 寄存器
51
- * (自愈真链路就是这么炸的)。名字清单只是兜底口径,不是主口径。
51
+ * (自愈真实链路正是因此失败)。名字清单仅为回退口径,不是主口径。
52
52
  * B. 退回全局按 FACTS_REGISTERS 名单过滤:微型片段 SVD 可能没有 peripheral 包装
53
53
  * (单测夹具就是那形状)。
54
54
  */
@@ -95,7 +95,7 @@ export function parseSvdStructure(xml, registers = FACTS_REGISTERS) {
95
95
  function sha256(buf) {
96
96
  return createHash("sha256").update(buf).digest("hex");
97
97
  }
98
- /** SVD 的候选下载 URL,顺序 = 优先级(同 cmsis-sources 的实测结论:jsDelivr 最稳,raw 兜底)。 */
98
+ /** SVD 的候选下载 URL,顺序即优先级(同 cmsis-sources 的实测结论:jsDelivr 最稳定,raw 为回退)。 */
99
99
  export function svdSourceUrls(relFile, repo = SVD_REPO, ref = SVD_REF) {
100
100
  return [
101
101
  "https://fastly.jsdelivr.net/gh/" + repo + "@" + ref + "/" + relFile,
@@ -266,7 +266,7 @@ export async function buildFacts(o) {
266
266
  const pdfSource = acquired !== null && acquired.ok
267
267
  ? { kind: "rm-pdf", doc: acquired.docId, file: acquired.file.split(/[\\/]/).pop() ?? "", path: acquired.file, sha256: acquired.sha256, bytes: acquired.bytes, url: acquired.url, origin: "auto:" + acquired.channel, coveredLines: Object.keys(acquired.coverage) }
268
268
  : null;
269
- // spec 自动抽取:人没喂 rm-facts 而且这颗芯片有主题清单时,用可用的载体 PDF 自动抽取。
269
+ // spec 自动抽取:未传入 rm-facts 且该芯片有主题清单时,用可用的载体 PDF 自动抽取。
270
270
  // 载体两种都要认:双通道自动下的,和显式 --rm-pdf/--rm-url 给的(用户本地手册场景)。
271
271
  const explicitPdfSource = rm.sources.find((s) => s.kind === "rm-pdf" && typeof s.path === "string" && s.path !== "");
272
272
  const explicitPdfPath = typeof explicitPdfSource?.path === "string" ? explicitPdfSource.path : "";
@@ -29,7 +29,7 @@ function partSize(file) {
29
29
  * 下一次文件到 partPath(F3c):支持从 startAt 字节续传。
30
30
  *
31
31
  * 三个必须的边界:
32
- * 1. 服务器回 200 而不是 206 = 它忽略了 Range,必须**从头写**(截断),不能接在旧字节后面;
32
+ * 1. 服务器返回 200 而非 206 表示该服务器忽略了 Range,必须**从头写**(截断),不能接在旧字节之后;
33
33
  * 2. 10 s 观察窗口内平均速率不足 1 KB/s 就 abort(半截文件留着,交给上层续传或换源);
34
34
  * 3. 外层 signal 取消要能立刻停(不能让一个 30 s 的下载拖住取消)。
35
35
  */
@@ -78,7 +78,7 @@ async function streamOnce(url, partPath, startAt, fetchImpl, options) {
78
78
  if (!response.ok && response.status !== 206) {
79
79
  return { ok: false, bytes: 0, reason: "HTTP " + String(response.status), slow: false };
80
80
  }
81
- // 只有 206 才是"接着上次的字节";200 说明它整份重发,必须截断重写。
81
+ // 只有 206 才表示"接着上次的字节";200 表示整份重发,必须截断重写。
82
82
  const append = startAt > 0 && response.status === 206;
83
83
  const body = response.body;
84
84
  if (body === null)
@@ -9,7 +9,7 @@
9
9
  * ④ 上面都不行 → 落到用户缓存 <cacheRoot>/firmware/<包名>(cache)
10
10
  *
11
11
  * 为什么默认不装进 Repository(2026-10 实测,docs §14):把自造版本号丢进官方仓库,
12
- * CubeMX **不报错也不认**,生成时静默退回它自己认识的版本(拷出来的 HAL 字节数不对)。
12
+ * CubeMX **不报错,也不识别该版本**,生成时静默回退到其自身识别的版本(导出的 HAL 字节数不符)。
13
13
  * 真正让 CubeMX 用上指定包的唯一机制是脚本命令 project setCustomFWPath <包目录>,
14
14
  * 由 generate.ts 在 config load 之后发出去 —— 所以落点与 .ioc 无关,换机器也没有绝对路径残留。
15
15
  *
@@ -67,7 +67,7 @@ export function findInstalledFirmware(cubeMxRoots, packageName) {
67
67
  return "";
68
68
  }
69
69
  /* ------------------------- 安装记录(B10 的桥) ------------------------- */
70
- /** 安装记录文件名:<cacheRoot>/firmware/installed.json 里一串落点,generate 靠它找回落在 CubeMX 根以外的包。 */
70
+ /** 安装记录文件名:<cacheRoot>/firmware/installed.json 中记录若干落点,generate 依据该记录找回位于 CubeMX 根以外的包。 */
71
71
  export const FIRMWARE_RECORD_FILE = "installed.json";
72
72
  /** 记录文件路径(正斜杠)。 */
73
73
  export function firmwareRecordPath(env = process.env) {
@@ -137,7 +137,7 @@ export function firmwareExtraDirs(env = process.env) {
137
137
  }
138
138
  /**
139
139
  * 记一条落点(同一个包名后写的覆盖先写的)。返回空串表示记下了,否则是给人看的一句原因。
140
- * 为什么不让它失败:记录只是给 generate 的线索,写不进去不该把"包已经装好并自检通过"反转成失败。
140
+ * 该步骤不设为失败的原因:记录仅为 generate 提供线索,写入失败不应将「包已安装并自检通过」反转为失败。
141
141
  */
142
142
  function rememberFirmwareInstall(env, packageName, dir, kind) {
143
143
  const recordPath = firmwareRecordPath(env);
@@ -205,7 +205,7 @@ export function orderCubeMxRoots(roots) {
205
205
  * 这个根里有没有 STM32CubeMX.exe(判定"像不像装过 CubeMX"的宽松版)。
206
206
  * 为什么必须判:自动发现会把别的机器上的默认安装路径也列进来;对那种"假根"建 dsh-firmware,
207
207
  * 盘上就多出一份谁也认不到的包,而计划与真装还会给出两个不同落点(B12)。
208
- * 与 data/search-roots.ts 的 looksLikeCubeMxRoot 的区别:那个还要求 jre/bin/java.exe(无头生成要它),
208
+ * 与 data/search-roots.ts 的 looksLikeCubeMxRoot 的区别:后者还要求 jre/bin/java.exe(无头生成依赖该文件),
209
209
  * 这里只决定"往哪放固件包",缺 JRE 但装了 CubeMX 的机器也该能落到 dsh-firmware。
210
210
  */
211
211
  export function hasCubeMxExe(root) {
@@ -276,7 +276,7 @@ function decideTarget(request, plan, create) {
276
276
  }
277
277
  const existing = findInstalledFirmware(request.cubeMxRoots, plan.dirName);
278
278
  if (existing !== "") {
279
- return { kind: "existing", dir: existing, notes: ["CubeMX 仓库里已经有 " + plan.dirName + ",直接用它,不下载。"] };
279
+ return { kind: "existing", dir: existing, notes: ["CubeMX 仓库中已存在 " + plan.dirName + ",直接使用,不下载。"] };
280
280
  }
281
281
  const want = request.target ?? "auto";
282
282
  // 本机真存在的根优先:自动发现会把别的机器上的默认安装路径也列进来,
@@ -325,7 +325,7 @@ function decideTarget(request, plan, create) {
325
325
  }
326
326
  const dir = slash(cacheRoot(request.env ?? process.env)) + "/firmware/" + plan.dirName;
327
327
  notes.push("落点:" + dir + ":没有可用的 CubeMX 目录(没装、或装的位置写不进去、或候选根里没有 STM32CubeMX.exe)," +
328
- "只能放用户目录下的缓存;生成时 stm32_generate 会按缓存与安装记录找到它,靠脚本命令 setCustomFWPath 指过去,不会写进 .ioc。");
328
+ "只能存放于用户目录下的缓存;生成时 stm32_generate 依据缓存与安装记录定位该包,通过脚本命令 setCustomFWPath 指向该目录,不写入 .ioc。");
329
329
  return { kind: "cache", dir, notes };
330
330
  }
331
331
  function baseSteps(plan) {
@@ -440,7 +440,7 @@ function planResult(request, plan, decision) {
440
440
  "):2 个归档 + " +
441
441
  String(plan.coreTargets.length) +
442
442
  " 个内核头,约 2 MB;现在没有下载、没有建目录、没动 CubeMX 安装目录。",
443
- nextStep: "要我装吗?回一句「装固件包」,我给 dryRun:false + confirm:true 真下(约 2 MB)。",
443
+ nextStep: "如需安装,回复「装固件包」,插件将以 dryRun:false + confirm:true 实际下载(约 2 MB)。",
444
444
  };
445
445
  }
446
446
  /** 计划模式:只读探测,零副作用。 */
@@ -463,7 +463,7 @@ function mapperFor(archive) {
463
463
  }
464
464
  /**
465
465
  * 同一落点的跨进程安装锁:文件用 O_EXCL 创建,内容是持有者 pid。
466
- * 崩溃留下的锁在下次进入时按 pid 是否还活着回收;pid 被复用也无害——文件里还有 startedAt,
466
+ * 异常退出遗留的锁在下次进入时按 pid 是否存活回收;pid 被复用亦无影响,文件内还记录 startedAt,
467
467
  * 超过 6 小时一律当陈旧锁。
468
468
  */
469
469
  function acquireInstallLock(dir) {
@@ -533,7 +533,7 @@ function acquireInstallLock(dir) {
533
533
  return { ok: false, release: () => { }, error: "拿不到安装锁:" + lockFile };
534
534
  }
535
535
  const NOTICES_FILE = "THIRD_PARTY_NOTICES.md";
536
- /** 清掉以前崩溃/被杀留下的 .dsh-download-* 暂存目录(只清超过 1 小时的,不碰并发的那一份)。 */
536
+ /** 清理此前异常退出/被终止遗留的 .dsh-download-* 暂存目录(仅清理超过 1 小时的条目,不影响并发中的那一份)。 */
537
537
  function sweepStaleTemps(dir) {
538
538
  try {
539
539
  const now = Date.now();
@@ -561,17 +561,17 @@ function sweepStaleTemps(dir) {
561
561
  * 也不一定知道 CubeMX GUI 里看不见这个包。
562
562
  */
563
563
  function nextStepFor(kind, dir, packageName) {
564
- const locate = "它会按 .ioc 的 ProjectManager.FirmwarePackage 找这个包(CubeMX 根、" + packageName +
564
+ const locate = "该流程按 .ioc 的 ProjectManager.FirmwarePackage 查找此包(CubeMX 根、" + packageName +
565
565
  " 的安装记录、下载缓存都搜),用脚本命令 setCustomFWPath 指过去(" + dir + "),不往 .ioc 里写绝对路径。";
566
566
  if (kind === "cubeMx") {
567
- return "直接调 stm32_generate:" + locate + "CubeMX GUI 如果正开着,先关掉或重启它——它只在启动时扫这类自建目录。";
567
+ return "直接调 stm32_generate:" + locate + "若 CubeMX GUI 正在运行,请先关闭或重启——该程序仅在启动时扫描这类自建目录。";
568
568
  }
569
569
  if (kind === "repository") {
570
- return "直接调 stm32_generate:" + locate + "这个包在 CubeMX 官方 Repository 里,GUI 的包管理器也能看到它。";
570
+ return "直接调 stm32_generate:" + locate + "该包位于 CubeMX 官方 Repository 中,GUI 包管理器亦可看到。";
571
571
  }
572
572
  if (kind === "cache") {
573
573
  return "直接调 stm32_generate:" + locate + "注意包在下载缓存里、不在 CubeMX 安装目录,CubeMX 包管理器里看不到;" +
574
- "要让它出现在包管理器里,重装时用 target=auto 并保证 CubeMX 根可写(落到 dsh-firmware)。";
574
+ "如需该包出现在包管理器中,重装时使用 target=auto 并确保 CubeMX 根可写(落到 dsh-firmware)。";
575
575
  }
576
576
  return "直接调 stm32_generate:" + locate + "这个目录是调用方显式指定的:换机器或挪了目录之后要重新装(或更新安装记录),否则 generate 找不到。";
577
577
  }
@@ -761,7 +761,7 @@ export async function installFirmware(request) {
761
761
  });
762
762
  }
763
763
  // 官网直取(默认 auto):能走通就装进 CubeMX 自己的 Repository,走不通才回退下面的 GitHub 拼包。
764
- // 显式 target=repository 也走这条路——反正落点相同,但官方包更全、不用我们维护 coreHeaders 表。
764
+ // 显式 target=repository 同样走此路径:落点相同,但官方包更完整,无需插件维护 coreHeaders 表。
765
765
  const source = request.source ?? "auto";
766
766
  if (source !== "github" && request.targetDir === undefined && (request.target ?? "auto") !== "cache") {
767
767
  const official = await tryOfficial(request, plan, decision, steps, notes, progress);
@@ -870,7 +870,7 @@ export async function installFirmware(request) {
870
870
  download: { files, bytes },
871
871
  verify: stagedVerify,
872
872
  message: "固件包没装成:暂存包自检缺 " + stagedVerify.missing.join("、") + "。目标目录没有被改动。",
873
- nextStep: "把这段报错贴给我;或者改用 CubeMX 包管理器装官方包。",
873
+ nextStep: "请提供上述报错;或改用 CubeMX 包管理器安装官方包。",
874
874
  });
875
875
  }
876
876
  // 自检通过才换入:旧目录先改名备份,换入失败就还原;成功后才删备份。
@@ -923,7 +923,7 @@ export async function installFirmware(request) {
923
923
  verifyStep.status = "done";
924
924
  verifyStep.detail = "三条判据全过(" + String(verify.checks.length) + " 项检查;原子换入)";
925
925
  // 落点记进 <cacheRoot>/firmware/installed.json:cubeMx 落点靠扫根就能找到,但 cache / 显式 targetDir
926
- // 在 CubeMX 根以外,generate 只能靠这条记录 + 缓存目录把它们找回来(B10)。
926
+ // 位于 CubeMX 根以外,generate 只能依据该记录与缓存目录定位这些包(B10)。
927
927
  const recordProblem = rememberFirmwareInstall(request.env ?? process.env, plan.dirName, decision.dir, decision.kind);
928
928
  if (recordProblem !== "") {
929
929
  notes.push("没写进安装记录(" + recordProblem + "):stm32_generate 仍会搜下载缓存,但显式指定的目录可能找不到。");
@@ -4,11 +4,11 @@
4
4
  * 为什么值得单独一条路(2026-11 实测):
5
5
  * · swmgr install <本地 zip> ask 是 CubeMX 包管理器自己用的那条命令;装完包落在
6
6
  * <CubeMX>/Repository/<包名>,GUI 与 project generate 都认,不像 dsh-firmware 只能靠
7
- * project setCustomFWPath 指过去(那条路在 WBA 上实测会让 project generate 挂住 400 s)。
8
- * · 官方 zip 自带完整 HAL + CMSIS + 示例,比我们从 GitHub 拼 HAL+CMSIS 更全,也不用维护
7
+ * project setCustomFWPath 指过去(该路径在 WBA 上实测会使 project generate 阻塞 400 s)。
8
+ * · 官方 zip 自带完整 HAL + CMSIS + 示例,比插件从 GitHub 拼装的 HAL+CMSIS 更完整,也无需维护
9
9
  * 22 张 coreHeaders 表。
10
10
  *
11
- * 为什么不能只靠它(所以默认 auto + 回退):
11
+ * 不能仅依赖该通道的原因(因此默认 auto 并保留回退):
12
12
  * · 新族/新版本第一次装会弹许可协议(swmgr ... ask),无头进程等不到人点同意就卡住;
13
13
  * 这是许可协议,插件不代点,只能超时、说明、回退。
14
14
  * · 没有 CubeMX(或没有 JRE)、CubeMX GUI 正开着、公司网络挡住 sw-center,都走不通。
@@ -93,10 +93,10 @@ export function readMcuFwLibrary(file) {
93
93
  }
94
94
  /**
95
95
  * 按型号在 db 里找 FwLibrary:只有少数子系列(H7RS / MP13 / WB0 / WL3)才有这个属性,
96
- * 其余族返回 fallback(= 我们的 packageBase,例如 STM32Cube_FW_F1)。
96
+ * 其余族返回 fallback(= 插件的 packageBase,例如 STM32Cube_FW_F1)。
97
97
  *
98
98
  * 为什么按型号而不是按族:STM32H7 里 H743 用 STM32Cube_FW_H7、H7R3 用 STM32Cube_FW_H7RS,
99
- * 同一族两个包;只按族取会把 H7RS 的包喂给 H743。
99
+ * 同一族两个包;仅按族取用会误将 H7RS 的包应用到 H743。
100
100
  */
101
101
  export function resolveFwLibrary(dbRoot, partNumber, fallback) {
102
102
  const part = partNumber.trim().toUpperCase();
@@ -370,7 +370,7 @@ export const SWMGR_TIME_LIMIT_MS = 300_000;
370
370
  * CubeMX 每次启动都会打一行:
371
371
  * [INFO] AnalyticsPlugin:257 - Accepted Firmware Licenses: FW.C0.1.3.0,FW.C0.1.4.0,FW.F4.1.28.0
372
372
  * 实测许可按「族 + 版本」记账:同一个族的另一个版本也要重新点一次同意(FW.C0.1.3.0 与 FW.C0.1.4.0 各一条)。
373
- * 没记过的族/版本,swmgr 会挂在那里等 GUI 弹框;无头 -q 模式下那个框根本不会出现。
373
+ * 没记过的族/版本,swmgr 会阻塞并等待 GUI 弹框;无头 -q 模式下该弹框不会出现。
374
374
  */
375
375
  export function parseAcceptedFirmwareLicences(log) {
376
376
  const seen = [];
@@ -447,7 +447,7 @@ export async function installViaSwmgr(request) {
447
447
  if (licenceTag !== "" && !list.includes(licenceTag)) {
448
448
  missingLicence = licenceTag;
449
449
  if (request.onProgress !== undefined) {
450
- request.onProgress("CubeMX 还没接受 " + licenceTag + " 的许可协议(已接受:" + list.join("、") + "),不再干等它。");
450
+ request.onProgress("CubeMX 还没接受 " + licenceTag + " 的许可协议(已接受:" + list.join("、") + "),不再等待。");
451
451
  }
452
452
  controller.abort();
453
453
  }
@@ -459,7 +459,7 @@ export async function installViaSwmgr(request) {
459
459
  request.signal.removeEventListener("abort", relayAbort);
460
460
  }
461
461
  const log = outcome.stdout + "\n" + outcome.stderr;
462
- // 兜底:进程输出可能在 drain 之前就结束(或没走到 onOutput),结束后再从整段日志里读一次许可清单。
462
+ // 回退:进程输出可能在 drain 之前就结束(或未走到 onOutput),结束后再从整段日志中读取一次许可清单。
463
463
  if (acceptedLicences.length === 0)
464
464
  acceptedLicences = parseAcceptedFirmwareLicences(log);
465
465
  if (missingLicence === "" && licenceTag !== "" && acceptedLicences.length > 0 && !acceptedLicences.includes(licenceTag)) {
@@ -83,7 +83,7 @@ export function checkNoDebugGuard(projectDir, allowNoDebug = false, explicitIoc
83
83
  notes: [
84
84
  "SWD 守卫没生效:" + why + "。烧录前请自己确认 .ioc 里 PA13 是 SYS_JTMS-SWDIO、PA14 是 SYS_JTCK-SWCLK;" +
85
85
  "没启用 Serial Wire 时烧下去会关掉 SWD,之后只能 BOOT0=1 进系统 bootloader 救回来。",
86
- "想让它自动检查:工程根目录只留一个 .ioc,或给 stm32_flash 传 iocPath 指向正确的那份。",
86
+ "如需自动检查:工程根目录只保留一个 .ioc,或为 stm32_flash 传入 iocPath 指向正确文件。",
87
87
  ],
88
88
  };
89
89
  }
@@ -129,7 +129,7 @@ export function quoteForDisplay(item) {
129
129
  return item.includes('"') ? "'" + item + "'" : '"' + item + '"';
130
130
  }
131
131
  /**
132
- * 内置兜底配置:探针只 CMSIS-DAP(规格 §13),target 按芯片族取。
132
+ * 内置回退配置:探针仅 CMSIS-DAP(规格 §13),target 按芯片族选择。
133
133
  *
134
134
  * family 省略/null 时保持历史行为回退 stm32f1x。真正的"按族选 target + 选不出来就拒绝"
135
135
  * 走 chooseOpenocdTarget(data/family.ts)——这里只负责拼相对路径。
@@ -176,7 +176,7 @@ export function parseFlashLog(text) {
176
176
  const programmed = /\*\*\s*Programming Finished\s*\*\*/u.test(text);
177
177
  const verified = /\*\*\s*Verified OK\s*\*\*/u.test(text);
178
178
  // A25:以成功序列为主判据。openocd 成功时也会打 Error: 前缀的行(无关 ACK / DAP 噪声),
179
- // 以前把它们一律当失败,于是「烧录成功、已校验」被判成失败。
179
+ // 以前将这些输出一律视为失败,导致「烧录成功、已校验」被判为失败。
180
180
  const succeeded = programmed && verified;
181
181
  const errors = [];
182
182
  const noise = [];
@@ -222,7 +222,7 @@ function prepareFlashTarget(projectDir, request, startedAt) {
222
222
  }
223
223
  const elfPath = elfResolved.elf;
224
224
  const elfSize = statSync(elfPath).size;
225
- // 多个 .elf 并存时说清"烧的是哪一个、为什么是它"。
225
+ // 多个 .elf 并存时说明"烧录的是哪一个、选择该文件的原因"。
226
226
  const selectionNote = elfSelectionNote(dirname(elfPath));
227
227
  if (selectionNote !== "")
228
228
  notes.push(selectionNote);
@@ -315,7 +315,7 @@ async function runCubeProgrammerBackend(subprocess, request, probeNote) {
315
315
  notes,
316
316
  };
317
317
  }
318
- /** openocd 后端主体;ifaceOverride 只在工程没有自己的 openocd.cfg 时参与兜底 interface 选择。 */
318
+ /** openocd 后端主体;ifaceOverride 仅在工程没有自己的 openocd.cfg 时参与回退 interface 选择。 */
319
319
  async function runOpenocdFlash(subprocess, request, ifaceOverride) {
320
320
  const projectDir = resolve(request.projectDir);
321
321
  const config = resolveSearchConfig(process.env, request.binDirs === undefined ? {} : { binDirs: request.binDirs });
@@ -372,7 +372,7 @@ async function runOpenocdFlash(subprocess, request, ifaceOverride) {
372
372
  const cfg = configs[i] ?? "";
373
373
  args.push("-f", cfg);
374
374
  // J-Link 的 interface/jlink.cfg 只写 `adapter driver jlink`:不显式选 transport 时 openocd
375
- // 默认 jtag,SWD 目标会报 "No J-Link device found"。工程自带 cfg 时按它 source 的 interface 判断。
375
+ // 默认 jtag,SWD 目标会报 "No J-Link device found"。工程自带 cfg 时按其 source 的 interface 判断。
376
376
  if (projectConfig !== null && i === 0) {
377
377
  let projectText = "";
378
378
  try {
@@ -428,7 +428,7 @@ async function runOpenocdFlash(subprocess, request, ifaceOverride) {
428
428
  : classifyProbeFailure({
429
429
  // 分类要看**完整日志**,不能只看解析出的 Error 行:target 不匹配这类故障,
430
430
  // openocd 只打一行 `Warn : Cannot identify target as a STM32 family.`(2026-10-31 实测,
431
- // 只看 errors 时就落到 unknown)。errors 里还有我们自己合成的行(spawn 失败/超时),排在后面。
431
+ // 仅检查 errors 时会落到 unknown)。errors 中还包含本插件合成的行(spawn 失败/超时),排在后面。
432
432
  lines: [
433
433
  ...log.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line !== ""),
434
434
  ...errors,
@@ -441,8 +441,8 @@ async function runOpenocdFlash(subprocess, request, ifaceOverride) {
441
441
  if (probeError !== null && probeError.kind !== "unknown")
442
442
  notes.push(probeError.hint);
443
443
  if (probeError !== null && probeError.kind === "no-probe" && probeMissingLines(errors).length > 0) {
444
- // 2a:找不到设备时顺手做一次 USB 形态诊断——"没插"与"这台机器根本没 USB"是两种答案。
445
- // 诊断失败静默(unknown 不进 notes),绝不能让诊断把失败报告搞得更吵。
444
+ // 2a:找不到设备时同时做一次 USB 形态诊断——"未插入"与"这台机器没有 USB"是两种结论。
445
+ // 诊断失败静默(unknown 不写入 notes),诊断异常不得增加失败报告的噪声。
446
446
  const usb = await usbDiagnosis(subprocess, request.signal);
447
447
  const extra = usbNoteFor(usb.kind, usb.detail);
448
448
  if (extra !== null)
@@ -463,12 +463,12 @@ async function runOpenocdFlash(subprocess, request, ifaceOverride) {
463
463
  /**
464
464
  * 烧录编排器(2026-11-08 复盘后的两层修复):
465
465
  *
466
- * 1. **interface 先探后选**:以前兜底硬编码 cmsis-dap(规格 §13 的旧前提),插 ST-Link 的
466
+ * 1. **interface 先探后选**:以前回退配置硬编码 cmsis-dap(规格 §13 的旧前提),插 ST-Link 的
467
467
  * 用户直接被带偏——openocd 报 "unable to find a matching CMSIS-DAP device",还得人肉猜。
468
468
  * 现在先 usbDiagnosis(VID:PID 分流)按实见探针选 interface;工程自带 openocd.cfg 时不插手
469
469
  * (那是用户显式配置,只在失败后提示改哪一行)。
470
470
  * 2. **换 interface 自动重试一次**:仍报 probe-interface-mismatch 就切另一个驱动再跑。
471
- * 3. **CubeProgrammer 兜底**:openocd 两条都失败、实见探针是 ST-LINK、本机装了 CubeProgrammer、
471
+ * 3. **CubeProgrammer 回退**:openocd 两条路径均失败、实见探针是 ST-LINK、本机安装了 CubeProgrammer、
472
472
  * 且失败不是「换后端也没用」类(swd-locked/no-power/flash-protected)时,走 CLI 第二后端。
473
473
  * DAPLink 用户没有这条腿(CLI 只认 ST-LINK),报告里如实说。
474
474
  */
@@ -480,7 +480,7 @@ export async function runFlash(subprocess, request) {
480
480
  let sawStLink = false;
481
481
  let sawDapFamily = false;
482
482
  let sawJlink = false;
483
- // CLI 后端也要知道探针类型(它只认 ST-LINK),所以不能只按 interfaceConfig 是否显式给来决定探不探。
483
+ // CLI 后端同样需要探针类型(该后端只认 ST-LINK),因此不能只按 interfaceConfig 是否显式给出决定是否探测。
484
484
  if (request.interfaceConfig === undefined || backend === "cubeprogrammer") {
485
485
  const live = await liveProbeChoice(subprocess, request.signal);
486
486
  sawStLink = live.swdProbes.some((p) => p.kind === "st-link");
@@ -493,12 +493,12 @@ export async function runFlash(subprocess, request) {
493
493
  (backend === "cubeprogrammer"
494
494
  ? ""
495
495
  : hasProjectCfg
496
- ? "(工程自带 openocd.cfg,interface 以它为准)"
496
+ ? "(工程自带 openocd.cfg,interface 以其为准)"
497
497
  : ";interface 用 " + live.cfg + "(" + live.why + ")");
498
498
  }
499
499
  }
500
500
  if (backend === "cubeprogrammer") {
501
- // 实见的是 DAPLink/CMSIS-DAP:CLI 这条路根本不通,别让它跑一遍再报一句含糊的 "no ST-Link"。
501
+ // 实见的是 DAPLink/CMSIS-DAP:CLI 路径不可用,不要让其运行一次后仅报出含糊的 "no ST-Link"。
502
502
  if (sawDapFamily && !sawStLink) {
503
503
  return {
504
504
  ok: false, projectDir: resolve(request.projectDir), elfPath: "", elfSize: 0, command: "", args: [], configs: [],
@@ -513,10 +513,10 @@ export async function runFlash(subprocess, request) {
513
513
  let report = await runOpenocdFlash(subprocess, request, ifaceOverride);
514
514
  if (probeNote !== "")
515
515
  report.notes.unshift(probeNote);
516
- // 2) 接口不匹配 → 换另一个 interface 重试一次(仅插件兜底配置的工程;手写 cfg 的让用户按 hint 改)
516
+ // 2) 接口不匹配 → 更换另一个 interface 重试一次(仅限使用插件回退配置的工程;手写 cfg 的工程由用户按 hint 修改)
517
517
  if (!report.ok && !hasProjectCfg && report.probeError !== null && report.probeError.kind === "probe-interface-mismatch") {
518
518
  // 换哪条由**实见探针**决定,不是"把当前值取反":取反在探针结论过期/缺失时会把重试引向
519
- // 与真实硬件无关的方向(CI 上 2 条用例就是这么挂的)。实见 ST-LINK 就先试 stlink。
519
+ // 与真实硬件无关的方向(CI 上 2 条用例即因此失败)。实见 ST-LINK 时先试 stlink。
520
520
  const firstIface = ifaceOverride ?? "interface/cmsis-dap.cfg";
521
521
  const guided = sawStLink ? "interface/stlink-dap.cfg" : sawDapFamily ? "interface/cmsis-dap.cfg" : sawJlink ? "interface/jlink.cfg" : "";
522
522
  const other = guided !== "" && guided !== firstIface
@@ -524,7 +524,7 @@ export async function runFlash(subprocess, request) {
524
524
  : firstIface === "interface/cmsis-dap.cfg" ? "interface/stlink-dap.cfg" : "interface/cmsis-dap.cfg";
525
525
  const firstMessage = report.message;
526
526
  const retry = await runOpenocdFlash(subprocess, request, other);
527
- // notes 归属:retry 是新报告——探针实见行、换接口说明、第一次失败原因都得挂到它身上
527
+ // notes 归属:retry 生成新报告——探针实见行、换接口说明、第一次失败原因均需附加到该报告
528
528
  // (第一版把"自动换…"push 进了旧 report,随对象丢弃,测试当场抓到)。
529
529
  if (probeNote !== "")
530
530
  retry.notes.unshift(probeNote);
@@ -571,22 +571,22 @@ export async function runFlash(subprocess, request) {
571
571
  notes: [...report.notes, cubeProgrammerBackendNote(cli)],
572
572
  };
573
573
  }
574
- report.notes.push("CubeProgrammer 兜底也没成:" + alt.message + "(查过 " + alt.searched + ")");
574
+ report.notes.push("CubeProgrammer 回退同样失败:" + alt.message + "(查过 " + alt.searched + ")");
575
575
  }
576
576
  else {
577
- report.notes.push("实见 ST-LINK 但本机没装 STM32CubeProgrammer(CLI 没找到):装上它,ST-Link 就多一条不依赖 openocd target 脚本的后端" +
578
- "(backend=cubeprogrammer 可直连;H5/WBA/WB0/WL3 只能走它)。下载:https://www.st.com/en/development-tools/stm32cubeprog.html");
577
+ report.notes.push("实见 ST-LINK 但本机未安装 STM32CubeProgrammer(CLI 未找到):安装后可获得一条不依赖 openocd target 脚本的后端" +
578
+ "(backend=cubeprogrammer 可直连;H5/WBA/WB0/WL3 只能使用该后端)。下载:https://www.st.com/en/development-tools/stm32cubeprog.html");
579
579
  }
580
580
  }
581
581
  if (!report.ok && sawJlink && !sawStLink) {
582
582
  // J-Link 也没有 CLI 腿(CubeProgrammer 的 SWD 路径只认 ST-LINK)
583
- report.notes.push("J-Link 没有 CubeProgrammer 兜底腿(CLI 只认 ST-LINK):openocd 的 jlink 驱动需要 `-c \"transport select swd\"`,插着 J-Link 时若仍失败,先确认 J-Link 驱动(SEGGER 的 USB Driver)与 openocd 版本。");
583
+ report.notes.push("J-Link 没有 CubeProgrammer 备选后端(CLI 只认 ST-LINK):openocd 的 jlink 驱动需要 `-c \"transport select swd\"`,插着 J-Link 时若仍失败,先确认 J-Link 驱动(SEGGER 的 USB Driver)与 openocd 版本。");
584
584
  }
585
585
  if (!report.ok && !futile && report.probeError !== null && report.probeError.kind === "no-probe" && sawDapFamily && !sawStLink) {
586
586
  // DAPLink 用户走不了 CLI 这条腿,别让人以为还有救
587
587
  const config = resolveSearchConfig(process.env, {});
588
588
  if (findCubeProgrammerCli(config.cubePrgBins) !== null) {
589
- report.notes.push("本机装了 CubeProgrammer,但它的 SWD 路径只认 ST-LINK:你插的是 CMSIS-DAP/DAPLink 类探针,这条路帮不上(docs §79)。");
589
+ report.notes.push("本机已安装 CubeProgrammer,但其 SWD 路径只认 ST-LINK:当前插入的是 CMSIS-DAP/DAPLink 类探针,该路径不可用(docs §79)。");
590
590
  }
591
591
  }
592
592
  return report;
@@ -21,7 +21,7 @@ const LONG_PREFIX = "\\\\?\\";
21
21
  const UNC_PREFIX = "\\\\?\\UNC\\";
22
22
  /**
23
23
  * 把路径规范成 Windows 扩展长度形式(只在需要时加前缀)。
24
- * 已经是 \\?\ 开头的原样返回;相对路径也原样返回(前缀化会让它指到错误的根)。
24
+ * 已经是 \\?\ 开头的路径原样返回;相对路径同样原样返回(添加前缀会使路径指向错误的根)。
25
25
  */
26
26
  export function toLongPath(p) {
27
27
  if (process.platform !== "win32")
@@ -8,7 +8,7 @@
8
8
  * MI(Machine Interface)是 gdb 的机器可读协议(`--interpreter=mi2`):命令带 token、
9
9
  * 结果以 `^done`/`^error`/`^running` 回,异步事件以 `*stopped`/`*running` 推。VS Code 的
10
10
  * C/C++ 调试器也是这么驱动 gdb 的。这里实现最小可用子集:结果/异步记录解析、带 token 的请求队列、
11
- * 把 `~"..."` 控制台流挂到当前请求上(否则 `print` 的输出找不到归属)。
11
+ * 把 `~"..."` 控制台流关联到当前请求(否则 `print` 的输出无法确定归属)。
12
12
  *
13
13
  * 只读设计约束:零依赖、可单测(解析是纯函数;进程通过 MiSpawner 注入,测试给假进程)。
14
14
  */
@@ -16,7 +16,7 @@ import { spawn } from "node:child_process";
16
16
  /**
17
17
  * 步进命令映射到 MI 的 -exec-*:n/next、s/step 走整行(-exec-next / -exec-step),
18
18
  * ni/nexti、si/stepi 走单指令(-exec-next-instruction / -exec-step-instruction)。
19
- * continue 不在这里(它走 continueTarget,要先清掉旧的停止记录)。返回 null 表示不是步进命令。
19
+ * continue 不在此处(由 continueTarget 处理,需先清除旧的停止记录)。返回 null 表示不是步进命令。
20
20
  */
21
21
  export function steppingCommandFor(command) {
22
22
  const normalized = command.trim().toLowerCase();
@@ -187,14 +187,14 @@ export function parseMiLine(line) {
187
187
  const kind = sigil === "^" ? "result" : sigil === "*" ? "exec" : sigil === "+" ? "status" : "notify";
188
188
  return { token, kind, class: head, data, text: "" };
189
189
  }
190
- /** 常驻的 gdb MI 会话:保持连接,命令带 token 排队,控制台输出挂到当前请求上。 */
190
+ /** 常驻的 gdb MI 会话:保持连接,命令按 token 排队,控制台输出关联到当前请求。 */
191
191
  export class MiSession {
192
192
  child = null;
193
193
  buffer = "";
194
194
  token = 0;
195
195
  pending = null;
196
196
  lastStopped = null;
197
- /** 目标是否在跑。运行态下 gdb 不回任何命令(连 console 的 break 都卡),所以动它之前先看这个。 */
197
+ /** 目标是否处于运行态。运行态下 gdb 不响应任何命令(含 console 的 break),因此操作前先检查该状态。 */
198
198
  runningState = false;
199
199
  stopWaiters = [];
200
200
  lastPromptResolve = null;
@@ -208,7 +208,7 @@ export class MiSession {
208
208
  session.child = spawner(argv, options.cwd ?? process.cwd());
209
209
  session.attach();
210
210
  // MI 模式下 gdb 不一定先吐提示符(而且 "(gdb) " 没有换行,按行读会一直卡着)。
211
- // 所以握手改成「发一条必须有 ^done 的命令」:等到它就算连上了。
211
+ // 因此握手改为「发一条必须返回 ^done 的命令」:收到该回复即视为连接成功。
212
212
  await session.send("-gdb-set confirm off", options.timeoutMs ?? 20_000);
213
213
  await session.send("-gdb-set pagination off", options.timeoutMs ?? 20_000);
214
214
  if (options.elfPath !== undefined && options.elfPath !== "") {
@@ -336,7 +336,7 @@ export class MiSession {
336
336
  };
337
337
  });
338
338
  }
339
- /** 发一条 MI 命令,等它自己的 ^done/^error/^running。 */
339
+ /** 发送一条 MI 命令,等待该命令自身的 ^done/^error/^running。 */
340
340
  send(command, timeoutMs = 20_000) {
341
341
  const child = this.child;
342
342
  if (child === null || this.exited)
@@ -445,7 +445,7 @@ export class MiSession {
445
445
  await this.send("-gdb-exit", timeoutMs);
446
446
  }
447
447
  catch {
448
- // 退出时 gdb 常常不回 ^done:忽略,下面兜底 kill。
448
+ // 退出时 gdb 常不返回 ^done:忽略,随后由回退路径 kill。
449
449
  }
450
450
  const child = this.child;
451
451
  this.child = null;
@@ -20,8 +20,8 @@ function quoteArg(value) {
20
20
  * 注意:generate code 的参数必须是**目录**;传 .ioc 路径会静默无操作(M0 E3)。
21
21
  *
22
22
  * firmwareDir 非空时插一行 project setCustomFWPath —— 这是实测**唯一**能让 CubeMX
23
- * 真的用上指定固件包的机制(docs §14:丢进 Repository 会被静默忽略、只改 .ioc 会挂死)。
24
- * 它必须排在 config load 之后、generate code 之前。
23
+ * 实际用上指定固件包的机制(docs §14:放入 Repository 会被静默忽略,只修改 .ioc 会导致无响应)。
24
+ * 该行必须排在 config load 之后、generate code 之前。
25
25
  */
26
26
  export function buildGenerateScript(iocPath, outDir, layout, firmwareDir = "") {
27
27
  const lines = ["config load " + iocPath];