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
@@ -20,13 +20,13 @@ import fs from "node:fs";
20
20
  import path from "node:path";
21
21
  import { fileURLToPath } from "node:url";
22
22
  export const ASSETS_MANIFEST_FILE = "manifest.json";
23
- /** 老版本安装布局的标记文件(flat 内置资源没有它)。 */
23
+ /** 老版本安装布局的标记文件(flat 内置资源不含该文件)。 */
24
24
  export const ASSETS_INSTALL_FILE = "install.json";
25
25
  /** 设备事实在资源根里的相对路径(插件唯一的芯片事实来源)。 */
26
26
  export const ASSETS_DEVICE_FACTS_FILE = "device/f1/chips.json";
27
- /** 缺资源时对用户说的那句话(工具卡片、错误、note 都复用它,避免各写一套)。 */
27
+ /** 缺资源时面向用户的固定提示(工具卡片、错误与 note 共用该文案,避免各处重复编写)。 */
28
28
  export const ASSETS_REFRESH_HINT = "资源随插件内置(assets/):缺文件说明插件安装不完整,重装插件后重试;stm32_assets verify 可定位缺了哪些";
29
- /** 只给 core / full;空串按 core 处理,别的值返回 null(由调用方给可读报错,不瞎猜)。 */
29
+ /** 仅接受 core / full;空串按 core 处理,其他值返回 null(由调用方给出可读报错,不做猜测)。 */
30
30
  export function normalizeProfile(value) {
31
31
  const text = (value ?? "core").trim().toLowerCase();
32
32
  if (text === "")
@@ -171,7 +171,7 @@ export function normalizeAssetPath(raw) {
171
171
  return null;
172
172
  return parts.join("/");
173
173
  }
174
- /** glob → 正则:** 跨目录,* 不跨目录,? 单字符。manifest 的 profiles 就靠它筛文件。 */
174
+ /** glob → 正则:** 跨目录,* 不跨目录,? 匹配单字符。manifest 的 profiles 依赖该规则筛选文件。 */
175
175
  function globToRegExp(pattern) {
176
176
  let out = "^";
177
177
  let index = 0;
@@ -528,7 +528,7 @@ export function resolveAssetFile(profile, relPath, env = process.env) {
528
528
  return empty("资源清单里没有这个文件:" + normalized + "(action=list 看这一版有哪些文件)");
529
529
  const allowed = profileFiles(state.manifest, normalizedProfile).some((file) => file.path === normalized);
530
530
  if (!allowed) {
531
- return empty("文件 " + normalized + " 不在 profile=" + normalizedProfile + " 里(它属于 profile=" + entry.profile + ");用 profile=full 查一次。");
531
+ return empty("文件 " + normalized + " 不在 profile=" + normalizedProfile + " 里(该项属于 profile=" + entry.profile + ");用 profile=full 查一次。");
532
532
  }
533
533
  const localPath = path.join(state.versionDir, normalized);
534
534
  try {
@@ -10,7 +10,7 @@
10
10
  * 预算来源(优先级从高到低):
11
11
  * 1. 内置资源 chips.json 里给这颗芯片写的 breakpoints / watchpoints;
12
12
  * 2. 按内核的硬件上限(data/family.ts 的 debugBudgetForCore):M0/M0+ 4/2、M3/M4 6/4、M7/M33/M55 8/4;
13
- * 3. 都没有(没有 .ioc / 认不出族)→ F1 实测值 6 / 4,并在 note 里说清是兜底。
13
+ * 3. 均无(没有 .ioc / 无法识别族)→ F1 实测值 6 / 4,并在 note 中说明属回退值。
14
14
  *
15
15
  * 为什么不按族写死:比较器个数是**内核**属性(FPB/DWT),同族不同内核会对不上;
16
16
  * 按内核算一次就对,也能覆盖 MPU 之外的所有 STM32。
@@ -73,7 +73,7 @@ export function readIocCpn(projectDir) {
73
73
  /**
74
74
  * `.ioc` 里的 `Mcu.Name`(db 分组名,例如 STM32F103C(8-B)Tx);读不到返回空串。
75
75
  *
76
- * 用它去查本机 CubeMX db 的 `<Core>`:族画像里的 core 是"手写兜底",db 才是逐型号的真源
76
+ * 以该名称查询本机 CubeMX db 的 `<Core>`:族画像中的 core 为手工回退值,db 才是逐型号的权威来源
77
77
  * (同一族里 MPU/双核/单核写法不同,见 cubemx-db.ts 里 CubemxMcuFacts.core 的注释)。
78
78
  */
79
79
  function readIocMcuName(projectDir) {
@@ -123,7 +123,7 @@ export function resolveBreakpointBudget(projectDir, env = process.env) {
123
123
  budget: coreBudget,
124
124
  source: "core",
125
125
  chip: cpn,
126
- note: "断点预算按内核 " + coreText + "(" + (coreSource === "db" ? "本机 CubeMX db 的 <Core>" : "族画像兜底") + ")的硬件上限:"
126
+ note: "断点预算按内核 " + coreText + "(" + (coreSource === "db" ? "本机 CubeMX db 的 <Core>" : "族画像回退值") + ")的硬件上限:"
127
127
  + String(coreBudget.code) + " 个硬件断点 / " + String(coreBudget.data) + " 个观察点(" + why + ")",
128
128
  };
129
129
  };
@@ -232,7 +232,7 @@ export function collectBreakpointRequests(input) {
232
232
  }
233
233
  return { requested, notes };
234
234
  }
235
- /** 超预算时的一句话(放进 errors[0],用户最先看到的就是它)。 */
235
+ /** 超预算时的提示语(放入 errors[0],用户首先看到该条)。 */
236
236
  function overflowDetail(codeAsked, dataAsked, budget, overCode, overData) {
237
237
  const parts = [];
238
238
  if (overCode > 0)
@@ -246,7 +246,7 @@ function overflowDetail(codeAsked, dataAsked, budget, overCode, overData) {
246
246
  function overflowSuggestion(budget, overCode, overData) {
247
247
  const parts = [];
248
248
  if (overCode > 0) {
249
- parts.push("删掉多出来的 " + String(overCode) + " 个 break:硬件断点占 FPB 比较器,第 " + String(budget.code + 1) + " 个 gdb 只会报 Cannot insert breakpoint 并把整次调试带崩;要连着停几个点就改用 tbreak(命中即删),或者先 break 一个、到点再换下一个");
249
+ parts.push("删除多余的 " + String(overCode) + " 个 break:硬件断点占用 FPB 比较器,第 " + String(budget.code + 1) + " 个 gdb 只会报 Cannot insert breakpoint 并导致整次调试失败;需要连续停在多个位置时改用 tbreak(命中即删),或先设一个 break,到达后再改为下一个");
250
250
  }
251
251
  if (overData > 0) {
252
252
  parts.push("观察点同理:DWT 只有 " + String(budget.data) + " 个数据比较器,超出的改成一次 watch 一个、或用 print / x 轮询变量");
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 下载缓存("可检索的缓存目录")。
3
3
  *
4
- * 为什么要有它:寄存器版模板、未来的各类模板与工具链产物都不能预置进插件(用户 2026-10-24 决定:
4
+ * 设计原因:寄存器版模板、后续各类模板与工具链产物都不能预置进插件(用户 2026-10-24 决定:
5
5
  * 插件要能覆盖任意 STM32,不可能每颗芯片都打一份进 npm 包)。做法是第一次用时从网上下载,
6
6
  * 落到一个**可检索**的本地缓存目录,之后一律复用——所以缓存必须自带一份 index.json:
7
7
  * 谁、哪一代、从哪个 URL 下的、多大、什么时候下的,都要能直接读出来,而不是靠猜目录里有什么。
@@ -67,7 +67,7 @@ export function readCacheIndex(env = process.env) {
67
67
  };
68
68
  }
69
69
  catch (error) {
70
- return { index: emptyCacheIndex(), error: "缓存索引读不了(" + info.indexPath + "):" + errorText(error) + ";当作空索引,重新下载会覆盖它。", path: info.indexPath };
70
+ return { index: emptyCacheIndex(), error: "缓存索引读不了(" + info.indexPath + "):" + errorText(error) + ";当作空索引,重新下载会覆盖该索引。", path: info.indexPath };
71
71
  }
72
72
  }
73
73
  function isCacheEntry(value) {
@@ -78,7 +78,7 @@ function isCacheEntry(value) {
78
78
  }
79
79
  /**
80
80
  * 写索引失败(可识别、带路径)。单独一个类型是为了让调用方把「索引没写成」和
81
- * 「网络挂了」分开,并且能依赖一条硬承诺:抛错时旧索引逐字节没动。
81
+ * 「网络故障」分开,并且可依赖一条硬承诺:抛错时旧索引逐字节未变。
82
82
  */
83
83
  export class CacheIndexWriteError extends Error {
84
84
  indexPath;
@@ -121,7 +121,7 @@ function safeRemove(remove, file) {
121
121
  }
122
122
  /**
123
123
  * 索引读不出来时先留一份 index.json.broken-<ts> 再重建:
124
- * 坏文件里其它条目还有人工救回来的价值,直接覆盖等于把它们一起抹掉。
124
+ * 损坏文件中其余条目仍有手工恢复的价值,直接覆盖会将其一并清除。
125
125
  */
126
126
  function preserveBrokenIndex(indexPath, reason) {
127
127
  const backup = freeBackupPath(indexPath, "broken");
@@ -2,9 +2,9 @@
2
2
  * 派生频率键的「跟随改写」(RCC.<外设>Freq_Value 这类)。
3
3
  *
4
4
  * 背景:.ioc 里每个外设都有一份自己的时钟值(USART1Freq_Value、I2C1Freq_Value、MCO1PinFreq_Value…),
5
- * 它们由 CubeMX 的时钟树按“多路选择器 + 分频”算出来。插件只写自己算得出的那几组
5
+ * 这些值由 CubeMX 的时钟树按“多路选择器 + 分频”算出。插件只写自身可算出的那几组
6
6
  * (SYSCLK/HCLK/APB1/APB2/ADC/TIM),其余交给 CubeMX 保存时重算 → ioc_verify 里每次都会多出一批
7
- * “派生键被重算”的记录(不参与 benign 判定,但噪声大,也说明我们承认了“不知道”)。
7
+ * “派生键被重算”的记录(不参与 benign 判定,但噪声较大,也表明插件承认“未知”)。
8
8
  *
9
9
  * 这里补一条保守规则:**旧值等于某个时钟域、且该域的新旧都唯一** 的派生键,跟着那个域改写。
10
10
  * 依据是 CubeMX 自己的默认选择(2026-11 C0 板级往返实测:I2C1/I2S1/USART1/MCO1Pin/MCO2Pin 五个键
@@ -48,7 +48,7 @@ function readSourceHz(entries, source) {
48
48
  /**
49
49
  * .ioc 里配了外部晶振没有:看有没有引脚的 Signal=RCC_OSC_IN/OUT。
50
50
  * 不能看「有没有 RCC.HSE_VALUE」——CubeMX 生成的模板**都**带这个键(默认 8 MHz),
51
- * 板上没晶振时它只是个占位值,拿它当「有 HSE」会把 C0 规划成 8 MHz。
51
+ * 板上未接晶振时该键只是占位值,按「有 HSE」处理会把 C0 规划成 8 MHz。
52
52
  */
53
53
  function hasHseCrystal(entries) {
54
54
  for (const value of entries.values()) {
@@ -223,7 +223,7 @@ export function planClockDirect(input) {
223
223
  // ADCFreqValue 连写),按原样写正则必漏一半。
224
224
  const derivedValueOf = (name) => {
225
225
  const lower = name.toLowerCase();
226
- // WatchDogFreq_Value 不在这一组:它是 LSI 32 kHz(C0 实测 CubeMX 回写 32000,按 SYSCLK 写就是错值)
226
+ // WatchDogFreq_Value 不在这一组:该值取自 LSI 32 kHz(C0 实测 CubeMX 回写 32000,按 SYSCLK 写入即为错值)
227
227
  if (/^(sysclk|hclk|ahb|cortex|fclkcortex|pwr)freq_value$/u.test(lower))
228
228
  return best.sysclkHz;
229
229
  if (/^apb2timfreq_value$/u.test(lower))
@@ -248,7 +248,7 @@ export function planClockDirect(input) {
248
248
  draft.set("RCC." + name, String(value));
249
249
  derivedWritten += 1;
250
250
  }
251
- // 5) RCC.IPParameters:已有名单 ∪ 本次写入(CubeMX 按 ASCII 升序写这一列,我们跟着排)
251
+ // 5) RCC.IPParameters:已有名单 ∪ 本次写入(CubeMX 按 ASCII 升序写这一列,本插件按同一顺序排列)
252
252
  const existing = (entries.get("RCC.IPParameters") ?? "").split(",").map((item) => item.trim()).filter((item) => item !== "");
253
253
  const merged = [...existing];
254
254
  for (const key of draft.keys()) {
@@ -1,11 +1,11 @@
1
1
  /**
2
- * L2:F1 时钟规划 —— 把「我要 60 MHz」变成一整套 RCC 键值 + 逐外设频率表。
2
+ * L2:F1 时钟规划 —— 把「目标 60 MHz」转换为一整套 RCC 键值 + 逐外设频率表。
3
3
  *
4
4
  * 为什么不是独立工具:时钟就是 .ioc 里的一段键,单开一个 stm32_clock_plan 会让"改引脚"和
5
5
  * "改时钟"变成两次 plan、两次 apply,中间还可能出现 PLL 与 APB 分频不自洽的中间态。
6
6
  * 所以 clock 作为 stm32_ioc_plan 的一个入参,和 entries/pins 一起算、一起写、一起回滚。
7
7
  *
8
- * 三条硬规则(踩坑换来的):
8
+ * 三条硬性规则(由已发生的问题得出):
9
9
  * 1) 只改 RCC.PLLMUL 是不够的:CubeMX 按 RCC.*Freq_Value 生成 SystemClock_Config,
10
10
  * 20 个派生键必须成套重算,否则 HAL_RCC_ClockConfig 用旧值算错总线频率。
11
11
  * 2) 目标频率可能根本不可达(板上 8 MHz HSE 只能出 8 的整数倍)。这时不猜、不静默:取
@@ -14,7 +14,7 @@
14
14
  * 其它频率下 USBFreq_Value 退化成 PLLCLK,报告必须点明"USB 不可用"。
15
15
  */
16
16
  import { adcDivFromValue, adcDivValue, apbDivFromValue, apbDivValue, F1_FACTS, pllMulValue, pllSourceById, } from "../data/clock-f1.js";
17
- /** 当前这次规划用的时钟事实(db 派生或 F1 兜底)。planClock 是同步单线程,入口赋值即可。 */
17
+ /** 本次规划使用的时钟事实(db 派生或 F1 回退)。planClock 为同步单线程,入口赋值即可。 */
18
18
  let activeFacts = F1_FACTS;
19
19
  /** 当前这颗芯片的 HSI 频率(Hz)。planClock 入口从 .ioc 的 RCC.HSI_VALUE 读,缺省 8 MHz。 */
20
20
  let activeHsiHz = 8_000_000;
@@ -499,7 +499,7 @@ function finish(input) {
499
499
  parts.push(chain.pllSourceLabel + " 拼不出这一档");
500
500
  }
501
501
  }
502
- // 换源提示:另一个可用源也许正好凑得出目标,但没说它能替代(HSI 精度差 / 要换晶振)。
502
+ // 换源提示:另一个可用源可能刚好能命中目标,但该提示不表示此源可替代(HSI 精度较差 / 需更换晶振)。
503
503
  if (!input.reachable && input.targetHz > 0 && input.targetHz <= activeFacts.limits.sysclkHz) {
504
504
  const mulList = activeFacts.muls.map((fact) => fact.mul);
505
505
  const lowestMul = mulList.length === 0 ? 2 : Math.min(...mulList);
@@ -523,7 +523,7 @@ function finish(input) {
523
523
  ? "这要板上真接着晶振(.ioc 里没写 RCC_OSC_IN,也没启 HSE)"
524
524
  : "需要板上换晶振";
525
525
  parts.push("(改用 " + other.label + " ×" + String(mul) + " 正好 " + formatHz(input.targetHz) +
526
- ",但 " + why + ",默认没选它)");
526
+ ",但 " + why + ",默认未选该项)");
527
527
  break;
528
528
  }
529
529
  }
@@ -532,7 +532,7 @@ function finish(input) {
532
532
  }
533
533
  if (!chain.usbAvailable && input.usbWanted) {
534
534
  // 同样别写死 "F1 的":db 派生的族把 requiresPllClkHz 记 0(USB 规则没建模),
535
- // 这里得说「没建模」,不能声称它们有 F1 那条 PLLCLK÷1.5 的路。
535
+ // 此处需说明「未建模」,不能声称这些族具备 F1 的 PLLCLK÷1.5 路径。
536
536
  const requires = activeFacts.usb.requiresPllClkHz;
537
537
  warnings.push(requires > 0
538
538
  ? "USB 不可用:这一族的 48 MHz 只在 PLLCLK=" + formatHz(requires) + " 时拿得到;当前 SYSCLK " +
@@ -613,7 +613,7 @@ function finish(input) {
613
613
  errors,
614
614
  };
615
615
  }
616
- /** 定点模式没命中目标时,顺手给出附近的可选档(方便用户改主意)。 */
616
+ /** 定点模式未命中目标时,同时给出附近的可选档(便于用户调整目标)。 */
617
617
  function nearestList(base, chosenHz, targetHz, hasHse, hseHz, request) {
618
618
  const sources = [];
619
619
  const wantedSource = request.pllSource === undefined ? null : pllSourceById(request.pllSource, activeFacts.sources);
@@ -199,7 +199,7 @@ export function planClockPllmn(input) {
199
199
  // H5/U5 的 PLL 有显式开关:不写 PLLUsed=1 时 CubeMX 认为 PLL 不用,SYSCLK 回落 HSI。
200
200
  if (facts.pllEnable !== undefined) {
201
201
  // 只写 PLLUsed=1:PLLState 是 db 里按 PLLUsed 派生的(Condition=PLLUsed=0 时给 OFF),
202
- // 写它反而会被 CubeMX 丢掉(F4/F7 实测:missingKeys 里出现 RCC.PLLState、IPParameters 判成改写)。
202
+ // 写入该键反而会被 CubeMX 丢弃(F4/F7 实测:missingKeys 里出现 RCC.PLLState、IPParameters 判成改写)。
203
203
  draft.set(facts.pllEnable.usedKey, facts.pllEnable.usedValue);
204
204
  }
205
205
  // SYSCLK 源的键名按 db 决定:F303 只有 SYSCLKSourceVirtual 生效(写 RCC.SYSCLKSource 会被丢)。
@@ -207,7 +207,7 @@ export function planClockPllmn(input) {
207
207
  // 分频键的取值必须来自 db 的枚举名:AHB 与 APB 不是同一套名字(F2/F4/F7 的 AHB 是
208
208
  // RCC_SYSCLK_DIVn,APB 是 RCC_HCLK_DIVn;C0 反过来)。写错名字 CubeMX **不报错**,
209
209
  // 载入时直接死循环(F2 实测 >240 s 停在 setPackage),所以这里按 div 去枚举里查,
210
- // 查不到就不写这个键(缺省值本来就是 ÷1,正好是我们要的)。
210
+ // 查不到则不写该键(缺省值本身为 ÷1,即所需值)。
211
211
  const divValueOf = (divs, div, fallback) => divFact(divs, div)?.iocValue ?? fallback(div);
212
212
  const ahbValue = divValueOf(facts.ahbDivs, 1, () => "");
213
213
  if (ahbValue !== "")
@@ -218,8 +218,8 @@ export function planClockPllmn(input) {
218
218
  const known = facts.knownDerivedNames ?? [];
219
219
  const setDerived = (names, value) => {
220
220
  const list = typeof names === "string" ? [names] : names;
221
- // SYSCLKFreq_VALUE 的尾巴是 _VALUE(不是 Freq_Value),所以它永远不在 derivedNames 名单里,
222
- // 但这一族一定有它(每个族的 RCC Modes 都带),必须写。
221
+ // SYSCLKFreq_VALUE 的后缀是 _VALUE(不是 Freq_Value),因此该键永远不在 derivedNames 名单里,
222
+ // 但该族一定有该键(每个族的 RCC Modes 都带),必须写入。
223
223
  const name = list.includes("SYSCLKFreq_VALUE")
224
224
  ? "SYSCLKFreq_VALUE"
225
225
  : known.length === 0
@@ -232,7 +232,7 @@ export function planClockPllmn(input) {
232
232
  setDerived("SYSCLKFreq_VALUE", best.sysclkHz);
233
233
  setDerived("HCLKFreq_Value", best.sysclkHz);
234
234
  // AHB 只 ÷1(上面写的 AHBCLKDivider 就是 ÷1),所以 AHB 与 Cortex 都等于 HCLK。
235
- // 不写它们 CubeMX 保存时会按自己的树重算一遍,verify 里就成了「值被改写」的噪声(F2 实测)。
235
+ // 不写这些键时,CubeMX 保存会按自身的树重新计算一遍,verify 中即出现「值被改写」的噪声(F2 实测)。
236
236
  setDerived("AHBFreq_Value", best.sysclkHz);
237
237
  // Cortex(SysTick)只有在 db 没给选择/分频参数时才等于 HCLK。H5/U5/WBA/L4+ 有 Cortex_Div 这类参数,
238
238
  // 实测同一族两次往返能反着改(H5 写 HCLK 被改成 HCLK÷8,U5 写 HCLK÷8 又被改回 HCLK)——
@@ -254,7 +254,7 @@ export function planClockPllmn(input) {
254
254
  setDerived(["ADCFreqValue", "ADCFreq_Value"], adcHz);
255
255
  }
256
256
  }
257
- // RCC.IPParameters 要把上面这些名字并进去(CubeMX 按它决定读哪些键)
257
+ // RCC.IPParameters 需并入上述名字(CubeMX 按该键决定读取哪些键)
258
258
  const existing = (entries.get("RCC.IPParameters") ?? "").split(",").map((item) => item.trim()).filter((item) => item !== "");
259
259
  const merged = [...existing];
260
260
  for (const key of draft.keys()) {
@@ -1,12 +1,12 @@
1
1
  /**
2
2
  * L2:cmake-sources —— 让 cmake/stm32cubemx/CMakeLists.txt 跟着工程的实际内容更新。
3
3
  *
4
- * 背景(审计后补的老洞):这份文件由脚手架从 templates/scaffold 拷进来,之后 CubeMX 不再重写它。
5
- * 实测证据:demo 工程里它的 mtime 与模板拷贝时间相同,而 Core/Src/main.c 已经更新过一轮。
6
- * 于是它一直是「C8T6 + GPIO」的快照:设备宏写死 STM32F103xB、启动文件写死 startup_stm32f103xb.s、
4
+ * 背景(审计后补充的旧问题):该文件由脚手架从 templates/scaffold 拷贝进来,此后 CubeMX 不再重写。
5
+ * 实测证据:demo 工程中该文件的 mtime 与模板拷贝时间相同,而 Core/Src/main.c 已更新过一轮。
6
+ * 因此该文件一直是「C8T6 + GPIO」的快照:设备宏固定为 STM32F103xB、启动文件固定为 startup_stm32f103xb.s、
7
7
  * HAL 模块清单只有 gpio/dma/pwr/flash/exti/cortex/rcc 那一圈。只要在 CubeMX 里开一个 UART/CAN/USB,
8
8
  * 编译能过、链接报 undefined reference to HAL_UART_Init —— 而源清单里根本没有那个 .c,
9
- * 报错信息完全不指向真正的病因,这是最费时间的一类坑。
9
+ * 报错信息完全不指向真正的成因,这是最耗时的一类问题。
10
10
  *
11
11
  * 做法:只动三处(设备宏、应用源清单、驱动源清单),文件里其余的行原样保留。
12
12
  * - 设备宏与启动文件:从工程根真实存在的 startup_stm32*.s 反推(stm32f103xb → STM32F103xB),
@@ -44,7 +44,7 @@ export function listStartupFiles(projectDir) {
44
44
  return [];
45
45
  }
46
46
  }
47
- /** 选工程根那个启动文件:唯一就是它;多个按字典序取第一个并说明(芯片换了要人删掉旧的)。 */
47
+ /** 选择工程根目录下的启动文件:仅有一个时即使用该文件;有多个时按字典序取第一个并说明(更换芯片后需人工删除旧文件)。 */
48
48
  export function pickStartupFile(projectDir) {
49
49
  const files = listStartupFiles(projectDir);
50
50
  if (files.length === 0)
@@ -74,7 +74,7 @@ export function startupStem(file) {
74
74
  */
75
75
  export function deviceDefineFromStartup(file) {
76
76
  const stem = startupStem(file);
77
- // 太短的名字没尾缀可拆(例如 startup_stm32.s):原样大写,别在这里瞎猜。
77
+ // 名称过短时无可拆分的后缀(例如 startup_stm32.s):原样大写,不在此处做猜测。
78
78
  if (stem.length < 8)
79
79
  return stem.toUpperCase();
80
80
  return stem.slice(0, -2).toUpperCase() + defineSuffix(stem.slice(-2));
@@ -155,7 +155,7 @@ function readTextOrNull(path) {
155
155
  * 这个工程用到了哪些 HAL 模块。
156
156
  *
157
157
  * 主依据是 stm32f1xx_hal_conf.h:CubeMX 只把真正用到的外设模块的 HAL_xxx_MODULE_ENABLED 打开,
158
- * 那份文件就是它对「要编译哪些 .c」的声明(不要扫 hal_conf 里的 #include —— 那里每个模块都列了一遍,
158
+ * 该文件即「要编译哪些 .c」的声明(不要扫描 hal_conf 中的 #include —— 其中每个模块都列了一遍,
159
159
  * 只是被 #ifdef 包住,全当「用到」会把整个 HAL 都编进去)。
160
160
  * 再并上 Core 源码里显式 #include 的模块,兜住手写代码的情况。
161
161
  */
@@ -208,7 +208,7 @@ export function halModulesInUse(projectDir, family) {
208
208
  export function collectCmakeSources(projectDir) {
209
209
  const startup = pickStartupFile(projectDir);
210
210
  if (startup === null) {
211
- return { error: "工程根没有 startup_stm32*.s(不是脚手架建的 HAL 工程?),无从反推芯片与源清单" };
211
+ return { error: "工程根没有 startup_stm32*.s(可能不是脚手架创建的 HAL 工程),无法反推芯片与源清单" };
212
212
  }
213
213
  // 优先信磁盘上的 HAL 目录(WBA/WL 这种三四字符族段的启动文件名拆不出族);拆不出再回退文件名规则。
214
214
  const family = familyTokensFromDriversDir(projectDir) ?? familyTokensFromStartup(startup.file);
@@ -399,7 +399,7 @@ export function refreshCubemxCmakeLists(projectDir, options = {}) {
399
399
  const eol = dominantEol(file.text);
400
400
  const original = file.text.split(/\r?\n/u);
401
401
  const endedWithEol = /\r?\n$/u.test(file.text);
402
- // 按行切完末尾会多出一个空串;不摘掉它,每跑一次就多一个空行(幂等就断了)。
402
+ // 按行切分后末尾会多出一个空字符串;不移除该字符串时,每次运行都会多一个空行(幂等性即被破坏)。
403
403
  if (endedWithEol)
404
404
  original.pop();
405
405
  let lines = original;
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * 红线(用户规格 §7):任何写 C 代码的动作都必须落在
5
5
  * `/* USER CODE BEGIN X *\/` 与 `/* USER CODE END X *\/` 之间,否则 CubeMX 下次生成会覆盖掉。
6
- * 这个模块负责把它变成**机械保证**:
6
+ * 本模块负责将该约束变为**机械保证**:
7
7
  * - 目标块必须存在(找不到就报可用标签,让模型自己改,不猜);
8
8
  * - 替换会先备份原文件到 .dsh-stm32/backups/<stamp>-patch/,再原子写(临时文件 + rename);
9
9
  * - 只改目标块内的行,块外的字节原样保留(含 CRLF / 缩进 / 其它 USER CODE 区)。
@@ -49,7 +49,7 @@ function isBraceOnly(line) {
49
49
  const codeOnly = (line.split("//")[0] ?? "").trim();
50
50
  return codeOnly !== "" && /^[{}]+$/u.test(codeOnly);
51
51
  }
52
- /** append 的落点:跳过块尾连续的收尾括号行,插在它们之前。 */
52
+ /** append 的落点:跳过块尾连续的收尾括号行,插入到这些行之前。 */
53
53
  function appendPosition(previousBody) {
54
54
  let index = previousBody.length;
55
55
  while (index > 0 && isBraceOnly(previousBody[index - 1] ?? ""))
@@ -93,7 +93,7 @@ export function patchUserCode(request) {
93
93
  const encoding = detectEncoding(originalBuffer);
94
94
  if (encoding === "unknown") {
95
95
  return fail("文件 " + fileRel + " 的编码认不出来(既不是 UTF-8 也不是 GB18030):为避免把中文注释写坏,不做改动。" +
96
- "先把它转成 UTF-8(VS Code 右下角编码 → 通过编码保存 → UTF-8)再试。");
96
+ "先转为 UTF-8(VS Code 右下角编码 → 通过编码保存 → UTF-8)再试。");
97
97
  }
98
98
  const original = decodeText(originalBuffer, encoding);
99
99
  const lines = splitLines(original);
@@ -109,7 +109,7 @@ export function patchUserCode(request) {
109
109
  const body = splitLines(request.code.replace(/\r?\n$/u, ""));
110
110
  const previousBody = lines.slice(range.begin + 1, range.end);
111
111
  // replace 会删掉块内原有的行。CubeMX 的 `USER CODE BEGIN 3` / `END 3` 之间夹着 while(1) 的收尾 `}`,
112
- // 删掉它 = 把整个 main() 变成没闭合的函数(实测 build 报 invalid storage class for function 'MX_GPIO_Init')。
112
+ // 删除该行会使整个 main() 成为未闭合的函数(实测 build 报 invalid storage class for function 'MX_GPIO_Init')。
113
113
  // 所以:replace 只允许"删掉空白或纯代码行",碰到块内原有的结构行(含 { 或 })就拒绝,让人改用 append。
114
114
  if (mode === "replace") {
115
115
  const structural = previousBody.filter((line) => {
@@ -118,7 +118,7 @@ export function patchUserCode(request) {
118
118
  });
119
119
  if (structural.length > 0) {
120
120
  return fail("块 \"" + request.block + "\" 的原有内容里有 " + String(structural.length) + " 行结构代码(含 { 或 }):" +
121
- "replace 会把它们删掉,块结构随即坏掉(例如 USER CODE 3 之间夹着 while(1) 的收尾括号)。" +
121
+ "replace 会删除这些行,块结构随即损坏(例如 USER CODE 3 之间夹着 while(1) 的收尾括号)。" +
122
122
  "改用 mode=\"append\" 追加,或把这些行一并写进 code。块内的结构行:" +
123
123
  structural.map((line) => line.trim()).join(" / ").slice(0, 200), { labels });
124
124
  }
@@ -4,9 +4,9 @@
4
4
  * 为什么需要:CubeMX 是**单实例**应用。GUI 已经开着的时候再执行
5
5
  * `jre/bin/java.exe -jar STM32CubeMX.exe -q <script>`,命令行会被转发给那个 GUI 进程 ——
6
6
  * `-q`(无界面)失效,脚本在 GUI 里跑,于是弹出 "Warning: Load Project … would you like to save the project ?"
7
- * 这类**模态框**:没人点它,生成就一直挂着(一次 3–4 分钟的活变成无限等)。
7
+ * 这类**模态框**:无人点击时生成会一直阻塞(3–4 分钟的任务变为无限等待)。
8
8
  *
9
- * 插件这边能做的不是"替你点按钮"(SWT 原生窗口,UIA/SendKeys 都不稳),而是**先发现、先拒绝**,
9
+ * 插件无法代为点击按钮(SWT 原生窗口,UIA/SendKeys 均不稳定),只能**先发现、先拒绝**,
10
10
  * 让人把 GUI 关掉再重跑 —— 报错比卡死便宜。
11
11
  */
12
12
  import { runCapture } from "./subprocess-runner.js";
@@ -38,7 +38,7 @@ export async function findRunningCubeMxGui(subprocess, signal) {
38
38
  /** 检测到 GUI 时给用户的一句话(直接进 errors/message)。 */
39
39
  export function describeCubeMxGuiConflict(processes) {
40
40
  const list = processes.map((process) => process.name + "#" + String(process.pid)).join("、");
41
- return ("检测到 STM32CubeMX 图形界面正在运行(" + list + "):CubeMX 是单实例,命令行会被转发给它," +
41
+ return ("检测到 STM32CubeMX 图形界面正在运行(" + list + "):CubeMX 是单实例,命令行会被转发至该进程," +
42
42
  "无头模式(-q)失效并可能弹出\"是否保存工程\"这类模态框,生成会一直等下去。" +
43
43
  "请先关掉 CubeMX 窗口(或保存后退出),再重跑;不想关也可以先用 CubeMX 自己 Generate Code,再回来跑 stm32_build");
44
44
  }
@@ -1,13 +1,13 @@
1
1
  /**
2
2
  * L1:STM32CubeProgrammer CLI 烧录后端(openocd 之外的第二条腿)。
3
3
  *
4
- * 为什么需要它(2026-11-08 真机教训):openocd 0.12 没有 C0/U0 等族的 target 脚本,
4
+ * 为什么需要该后端(2026-11-08 真机问题):openocd 0.12 没有 C0/U0 等族的 target 脚本,
5
5
  * 插件内置适配版也只覆盖到「flash 驱动能借用」的程度;C0 那次靠会话外手敲
6
6
  * STM32_Programmer_CLI 才烧进去——这条能力必须在插件里,而不是在用户的肌肉记忆里。
7
7
  *
8
8
  * 探针支持面(-h 实测 + 本机 -l 实测):CLI 的 SWD 路径只认 **ST-LINK**
9
9
  * (port=SWD 的参数全是 ST-LINK 系;DAPLink/CMSIS-DAP 不走这条)。
10
- * 所以它是「插着 ST-LINK 时的第二后端」,不是万能替补,报告里要如实说。
10
+ * 因此该后端仅适用于已插入 ST-LINK 的场景,不能替代其他探针,报告中须如实说明。
11
11
  *
12
12
  * 判据短语全部来自对本机 v2.19.0 的 STM32_Programmer_CLI.exe / CubeProgrammer_API.dll
13
13
  * 内嵌消息表的实测提取(UTF-16 串扫描),不是文档转述:
@@ -82,7 +82,7 @@ export async function runCubeProgrammerFlash(subprocess, request) {
82
82
  });
83
83
  if (cli === null) {
84
84
  return empty(["没找到 STM32_Programmer_CLI.exe"], "烧不了:本机找不到 STM32CubeProgrammer 的 CLI(查过 " + describeSearchScope(config.cubePrgBins, "STM32_CUBE_PRG_ROOT") + ")。" +
85
- "装上它就有了不依赖 openocd target 脚本的第二条后端(H5/WBA/WB0/WL3 只能走它):" +
85
+ "安装后即具备不依赖 openocd target 脚本的第二条后端(H5/WBA/WB0/WL3 只能使用该后端):" +
86
86
  "https://www.st.com/en/development-tools/stm32cubeprog.html(默认安装路径会被自动发现;已装在别处就设 STM32_CUBE_PRG_ROOT 指到安装根或 bin)");
87
87
  }
88
88
  const args = [cli, ...buildCubeProgrammerArgs(request.elfPath, {
@@ -133,5 +133,5 @@ export async function runCubeProgrammerFlash(subprocess, request) {
133
133
  }
134
134
  /** 报告卡片里给这行署名:烧的是哪条后端。 */
135
135
  export function cubeProgrammerBackendNote(cliPath) {
136
- return "烧录后端:STM32CubeProgrammer CLI(" + basename(cliPath) + ");注意它只认 ST-LINK,DAPLink/CMSIS-DAP 探针仍走 openocd。";
136
+ return "烧录后端:STM32CubeProgrammer CLI(" + basename(cliPath) + ");注意该后端只认 ST-LINK,DAPLink/CMSIS-DAP 探针仍走 openocd。";
137
137
  }
@@ -4,7 +4,7 @@
4
4
  * 为什么这么做:用户要求「能在 db 查到的,只写查询逻辑」。CubeMX 安装目录里的
5
5
  * db/mcu/*.xml 就是芯片事实(引脚、Signal、IP 实例、最高频率),
6
6
  * db/mcu/IP/*_Modes.xml 就是各 IP 的合法模式名,db/package.xml 是库版本。
7
- * 这些文件随用户的 CubeMX 版本变化,所以我们不在插件里内置副本,运行时按版本找。
7
+ * 这些文件随用户的 CubeMX 版本变化,因此插件不内置副本,运行时按版本查找。
8
8
  *
9
9
  * 结构(实测 DB.6.0.150):
10
10
  * db/package.xml → <PackDescription Release="DB.6.0.150"/>
@@ -110,7 +110,7 @@ export function parseMcuXml(text) {
110
110
  }
111
111
  const ips = new Map();
112
112
  // 两种写法都要认(U5 实测):自闭合 <IP …/>(F1/F2/F4 这些单上下文族)与带子节点的
113
- // <IP …>…</IP>(TrustZone/多上下文族:<IP> 里挂 <ContextSplit>/<ContextIP>)。
113
+ // <IP …>…</IP>(TrustZone/多上下文族:<IP> 内含 <ContextSplit>/<ContextIP>)。
114
114
  // 早先只认自闭合,U5 的 110 个 <IP> 里只有 1 个是自闭合的 —— RCC 正好不是,
115
115
  // 于是 readMcuFacts 读出来的 ips 里没有 RCC,时钟事实整族读不到(假结论「db 没有这一族的 RCC」)。
116
116
  // 键统一大写:.ioc 的 Mcu.IP<i> 与信号名都是大写实例名,而 ipModesPath/hasIpInstance 也按大写查。
@@ -211,9 +211,9 @@ export function readIpModeNames(db, facts, instanceName) {
211
211
  /**
212
212
  * 读某个 IP 实例的合法参数名(Modes 文件里的 <RefParameter Name="…">),例如 USART1 的
213
213
  * BaudRate / WordLength / Parity。.ioc 里 `<IP>.<参数>` 的键名必须逐字等于这些名字,
214
- * 拼错就会被 CubeMX 静默丢弃——所以覆盖率闸门用它校验「形状对、名字错」。
214
+ * 拼错会被 CubeMX 静默丢弃,因此覆盖率闸门以该清单校验「形状对、名字错」。
215
215
  *
216
- * F1 系列有个坑:参数名不在 `db/mcu/<Mcu>.xml`(那里只有 <IP> 的实例清单,RefParameter 为 0),
216
+ * F1 系列存在已知问题:参数名不在 `db/mcu/<Mcu>.xml`(该文件只有 <IP> 的实例清单,RefParameter 为 0),
217
217
  * 而在 `db/mcu/IP/<Name>-<Version>_Modes.xml` 里,所以要按 ipModesPath 再走一次。
218
218
  * 返回空数组表示「查不到,别据此判错」(调用方据此跳过校验)。
219
219
  */
@@ -237,12 +237,12 @@ export function readIpParameterNames(db, facts, instanceName) {
237
237
  * 这颗芯片上「真的有引脚」的外设族(USART / TIM / ADC / SPI …)。
238
238
  *
239
239
  * 用途:.ioc 的 Mcu.IPn 里除了真外设,还会出现内核项(CORTEX_M0+)、板名(NUCLEO-C031C6)、
240
- * SYS / DEBUG 这类没有引脚的东西。判断「进了 Mcu.IPn 却没有脚指向它 → CubeMX 会忽略」时,
241
- * 必须先排除它们——它们本来就不该有脚。db 的 <Pin><Signal Name=…> 是权威来源:
240
+ * SYS / DEBUG 这类无引脚的内核项。判断「已进入 Mcu.IPn 却无引脚指向 → CubeMX 会忽略」时,
241
+ * 必须先排除这些内核项,其本身就不应有引脚。db 的 <Pin><Signal Name=…> 是权威来源:
242
242
  * 芯片真实的引脚复用里出现过哪些外设族,就只校验这些族。
243
243
  *
244
244
  * 实测(2026-11,DB.6.0.150):C0 的 STM32C031C(4-6)Tx.xml 的引脚信号里没有 CORTEX_M0+、
245
- * 也没有板名,而 USART2_TX / TIM3_CH1 / ADC1_IN13 都在 → 用它做判据不会误报内核项。
245
+ * 也没有板名,而 USART2_TX / TIM3_CH1 / ADC1_IN13 均存在 → 以该清单为判据不会误报内核项。
246
246
  */
247
247
  export function instancesWithPins(facts) {
248
248
  const out = new Set();
@@ -5,7 +5,7 @@
5
5
  * - 常驻的**只有 openocd**(gdb server 占着探针,但这是唯一的占用者);
6
6
  * - 每次 stm32_debug_eval 临时起一个 `gdb -batch` 连上去,跑完命令 → `monitor resume` → detach 退出,
7
7
  * 不在插件进程里留 gdb;
8
- * - 租约:空闲 90 s 自动关、总时长 10 min 硬上限;`turn/end`(agent 输出完、等你回复)立刻关;
8
+ * - 租约:空闲 90 s 自动关闭、总时长上限 10 min;`turn/end`(agent 输出结束、等待用户回复)立即关闭;
9
9
  * - `build` / `flash` / `generate` 动手前先让会话让出探针(`releaseProbe`)。
10
10
  *
11
11
  * 探针只有一块:任何时刻只允许一个会话,重复 start 会先把旧的关掉。
@@ -65,7 +65,7 @@ export function parseGdbPrintedHex(output) {
65
65
  * 老做法是按 `$N = 0x...` 的出现顺序对齐地址,但失败的命令只打一行
66
66
  * "Cannot access memory at address ..."、不产生 `$N`,于是中间有一个地址读失败,
67
67
  * 后面所有值就整体前移、张冠李戴,报告里还标着 ok=true。
68
- * 现在每个地址前面先 echo 一个 ===DSH:<address>=== 标记,值只在它自己那一段里找。
68
+ * 现在每个地址前面先 echo 一个 ===DSH:<address>=== 标记,值只在对应标记段内查找。
69
69
  */
70
70
  export function parseMarkedWords(output, addresses) {
71
71
  const values = new Map();
@@ -98,8 +98,8 @@ export function parseMarkedWords(output, addresses) {
98
98
  * 从 openocd 启动日志里解析各服务的监听端口。
99
99
  *
100
100
  * openocd 0.12 会打印三行独立的 "Listening on port N for <svc> connections"(tcl / telnet / gdb)。
101
- * B3 的读寄存器快路径只要 tcl 那个:走它的 RPC 口 halt → mdw → resume,一次连接几毫秒。
102
- * 解析不到就是 0,调用方回退到 gdb(慢一点但能用),不把整个工具搞挂。
101
+ * B3 的读寄存器快路径仅使用 tcl:通过该通道的 RPC 口执行 halt → mdw → resume,一次连接耗时几毫秒。
102
+ * 解析失败时为 0,调用方回退到 gdb(较慢但可用),不影响整个工具。
103
103
  */
104
104
  export function parseListeningPorts(text) {
105
105
  const ports = { gdb: 0, tcl: 0, telnet: 0 };
@@ -309,7 +309,7 @@ export class DebugSessionManager {
309
309
  this.ensureSweeper();
310
310
  // 真机踩过:openocd 打完 "Listening on port …" 之后仍可能因为探针 HID 错误当场退出
311
311
  // (hid_write/WaitForSingleObject 0x3E5 + CMSIS-DAP CMD_INFO failed)。status() 只看内存里的
312
- // 会话对象,于是后面每个工具都报「会话进行中」,实际全程失败。这里连一下 Tcl 口确认它真活着
312
+ // 会话对象,于是后续每个工具都报「会话进行中」,实际全程失败。此处连接一次 Tcl 口确认该会话仍在运行
313
313
  // (探针可注入,单测用假进程替代)。
314
314
  if (session.tclPort > 0) {
315
315
  let alive = await this.aliveProbe(session.tclPort);
@@ -324,7 +324,7 @@ export class DebugSessionManager {
324
324
  this.stopSweeper();
325
325
  handle.terminate();
326
326
  await handle.waitForExit().catch(() => undefined);
327
- return emptyReport(["会话的 openocd 起来后立刻没了:Tcl 端口 " + String(session.tclPort) + " 连不上(探针掉线?插拔探针后重试)", tail], "没开会话:openocd 起来后立刻退出");
327
+ return emptyReport(["会话的 openocd 起来后立刻没了:Tcl 端口 " + String(session.tclPort) + " 连不上(探针可能掉线,插拔探针后重试)", tail], "没开会话:openocd 起来后立刻退出");
328
328
  }
329
329
  }
330
330
  if (request.reset !== undefined && request.reset !== "none") {
@@ -445,7 +445,7 @@ export class DebugSessionManager {
445
445
  lines.push(normalized + ":已停下 —— " + formatStopLocation(stopped) + keepHint);
446
446
  }
447
447
  catch {
448
- lines.push(normalized + ":目标已继续运行(" + String(waitMs) + " ms 内没命中断点);下条命令会先 -exec-interrupt 把它停下");
448
+ lines.push(normalized + ":目标已继续运行(" + String(waitMs) + " ms 内未命中断点);下条命令会先 -exec-interrupt 使目标停止");
449
449
  }
450
450
  continue;
451
451
  }
@@ -546,7 +546,7 @@ export class DebugSessionManager {
546
546
  }
547
547
  }
548
548
  /**
549
- * 借正在跑的调试会话(它已经占着 openocd + CMSIS-DAP)读 32 位字。
549
+ * 借用正在运行的调试会话(该会话已占用 openocd + CMSIS-DAP)读取 32 位字。
550
550
  *
551
551
  * 为什么要借:再起一个 openocd 会抢同一块探针,实测报
552
552
  * "CMSIS-DAP transfer count mismatch: expected 3, got 2"。所以有会话时一律走 gdb 表达式
@@ -884,7 +884,7 @@ export class DebugSessionManager {
884
884
  return {
885
885
  ok: true,
886
886
  stopped: false,
887
- message: "没关:这个会话是另一个调用方起的(" + session.owner + "),不动它(" + reason + ")",
887
+ message: "未关闭:该会话由另一个调用方启动(" + session.owner + "),不做变更(" + reason + ")",
888
888
  };
889
889
  }
890
890
  this.current = null;
@@ -894,9 +894,9 @@ export class DebugSessionManager {
894
894
  resetWatchState();
895
895
  if (session === null)
896
896
  return { ok: true, stopped: false, message: "本来就没有会话(" + reason + ")" };
897
- // 先让 openocd 自己 shutdown:直接 kill 时它来不及给探针发断开命令,
897
+ // 先让 openocd 自行 shutdown:直接 kill 时该进程来不及向探针发送断开命令,
898
898
  // CMSIS-DAP 固件会被留在「半连接」状态,下一次 CMD_INFO 直接超时(实测踩过两次)。
899
- // P3:先收掉常驻 gdb(它握着 gdb server 端口),再让 openocd shutdown。
899
+ // P3:先关闭常驻 gdb(该进程占用 gdb server 端口),再让 openocd shutdown。
900
900
  if (session.mi !== null) {
901
901
  await session.mi.stop().catch(() => undefined);
902
902
  session.mi = null;
@@ -936,7 +936,7 @@ export class DebugSessionManager {
936
936
  }
937
937
  /** 进程内单例:工具、turn/end 监听、dispose 共用同一个会话。 */
938
938
  export const debugSessions = new DebugSessionManager();
939
- /** 通过 Tcl 口让 openocd 自己 shutdown(探针能收到正常的断开序列)。失败就交给 kill 兜底。 */
939
+ /** 通过 Tcl 口让 openocd 自行 shutdown(探针能收到正常的断开序列)。失败时交由 kill 回退处理。 */
940
940
  function requestOpenocdShutdown(port, timeoutMs) {
941
941
  if (!Number.isFinite(port) || port <= 0)
942
942
  return Promise.resolve();
@@ -107,7 +107,7 @@ export async function waitForListening(handle, timeoutMs, onText) {
107
107
  return sawListening;
108
108
  };
109
109
  while (Date.now() - startedAt < timeoutMs) {
110
- // openocd 的日志其实走 stderr,两路都要读,否则永远等不到 "Listening on port"。
110
+ // openocd 的日志实际走 stderr,两路都需读取,否则将一直等不到 "Listening on port"。
111
111
  if (drain())
112
112
  return { ok: true, text };
113
113
  const exit = await Promise.race([handle.done.then(() => true), sleep(200).then(() => false)]);
@@ -164,7 +164,7 @@ export async function runDebugRun(subprocess, request) {
164
164
  return { ...empty, message: "没调试:找不到 .elf", durationMs: Date.now() - startedAt };
165
165
  }
166
166
  // B4:超预算就到此为止——不 spawn openocd(探针不动),也不让 gdb 报一串
167
- // "Cannot insert breakpoint" 再把整次调试带崩。文案直接给"超了几个"和"删哪个/换什么"。
167
+ // "Cannot insert breakpoint" 导致整次调试失败。文案直接给出"超出几个"和"删除哪个/更换什么"。
168
168
  if (!plan.ok) {
169
169
  errors.push("断点超预算:" + plan.detail);
170
170
  notes.push(...collected.notes);
@@ -238,7 +238,7 @@ export async function runDebugRun(subprocess, request) {
238
238
  });
239
239
  if (!listening.ok) {
240
240
  // F2:旧版只回"openocd 起不来"+15 行尾巴,真正的 adapter init 失败常被挤掉。
241
- // 现在先归类(与 flash 同一套规则),再把有信息量的行留下,并顺手做一次 USB 形态诊断。
241
+ // 先归类(与 flash 使用同一套规则),再保留有信息量的行,同时做一次 USB 形态诊断。
242
242
  const lines = listening.text.split(/\r?\n/u).filter((line) => line.trim() !== "");
243
243
  // 此时 openocd 还没结算,退出码未知(给 null);归类规则与 flash 完全同一份。
244
244
  const probeError = classifyProbeFailure({ lines, exitCode: null, stage: "debug" });