dsh-stm32 0.1.5 → 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 (100) hide show
  1. package/README.md +2 -2
  2. package/README_EN.md +2 -2
  3. package/client/client.js +24 -24
  4. package/docs/reading-guide.md +32 -0
  5. package/lib/client.js +24 -24
  6. package/lib/commands/register.js +5 -5
  7. package/lib/data/chips.js +4 -4
  8. package/lib/data/clock-db.js +24 -24
  9. package/lib/data/clock-f1.js +2 -2
  10. package/lib/data/cmsis-sources.js +6 -6
  11. package/lib/data/db-presets.js +4 -4
  12. package/lib/data/device-facts.js +6 -6
  13. package/lib/data/family.js +16 -16
  14. package/lib/data/firmware-packages.js +10 -10
  15. package/lib/data/install-guides.js +18 -18
  16. package/lib/data/ioc-presets.js +3 -3
  17. package/lib/data/ioc-schema.js +32 -32
  18. package/lib/data/rm-topics.js +6 -6
  19. package/lib/data/search-roots.js +62 -16
  20. package/lib/data/serial-config.js +7 -7
  21. package/lib/data/stm32f1.js +1 -1
  22. package/lib/data/svd.js +7 -7
  23. package/lib/data/toolchain-config.js +3 -3
  24. package/lib/engine/assets.js +5 -5
  25. package/lib/engine/breakpoints.js +5 -5
  26. package/lib/engine/cache.js +4 -4
  27. package/lib/engine/clock-derived.js +2 -2
  28. package/lib/engine/clock-direct.js +3 -3
  29. package/lib/engine/clock-plan.js +7 -7
  30. package/lib/engine/clock-pllmn.js +6 -6
  31. package/lib/engine/cmake-sources.js +9 -9
  32. package/lib/engine/code-patch.js +5 -5
  33. package/lib/engine/cube-mx-guard.js +3 -3
  34. package/lib/engine/cube-programmer.js +4 -4
  35. package/lib/engine/cubemx-db.js +7 -7
  36. package/lib/engine/debug-session.js +12 -12
  37. package/lib/engine/debug.js +3 -3
  38. package/lib/engine/doctor.js +12 -12
  39. package/lib/engine/download.js +1 -1
  40. package/lib/engine/facts-acquire.js +3 -3
  41. package/lib/engine/fetch.js +2 -2
  42. package/lib/engine/firmware-install.js +16 -16
  43. package/lib/engine/firmware-official.js +8 -8
  44. package/lib/engine/flash.js +22 -22
  45. package/lib/engine/fs-longpath.js +1 -1
  46. package/lib/engine/gdb-mi.js +7 -7
  47. package/lib/engine/generate-script.js +2 -2
  48. package/lib/engine/generate.js +17 -17
  49. package/lib/engine/hal-chip.js +7 -7
  50. package/lib/engine/ioc-plan.js +80 -58
  51. package/lib/engine/ioc-rules.js +9 -9
  52. package/lib/engine/ioc-verify.js +34 -34
  53. package/lib/engine/msys2-install.js +50 -50
  54. package/lib/engine/probe-error.js +8 -8
  55. package/lib/engine/probe-session.js +3 -3
  56. package/lib/engine/probe.js +47 -50
  57. package/lib/engine/project-export.js +1 -1
  58. package/lib/engine/register-clock.js +5 -5
  59. package/lib/engine/register-gpio.js +3 -3
  60. package/lib/engine/register-linker.js +7 -7
  61. package/lib/engine/register-template.js +22 -22
  62. package/lib/engine/regs.js +3 -3
  63. package/lib/engine/rm-extract.js +2 -2
  64. package/lib/engine/rm-sources.js +1 -1
  65. package/lib/engine/route-plan.js +9 -9
  66. package/lib/engine/rtt.js +18 -18
  67. package/lib/engine/scaffold.js +22 -22
  68. package/lib/engine/serial.js +34 -30
  69. package/lib/engine/tar.js +1 -1
  70. package/lib/engine/text-file.js +1 -1
  71. package/lib/engine/thirdparty.js +3 -3
  72. package/lib/engine/tool-env.js +2 -2
  73. package/lib/engine/toolchain-gate.js +8 -8
  74. package/lib/engine/usercode-merge.js +2 -2
  75. package/lib/engine/vscode-config.js +2 -2
  76. package/lib/engine/web-api.js +1 -1
  77. package/lib/engine/xcube-catalog.js +1 -1
  78. package/lib/index.js +5 -5
  79. package/lib/skill/stm32-workflow.js +1 -1
  80. package/lib/tools/assets.js +9 -4
  81. package/lib/tools/build.js +0 -1
  82. package/lib/tools/cache.js +2 -2
  83. package/lib/tools/debug-session.js +5 -5
  84. package/lib/tools/doctor.js +2 -2
  85. package/lib/tools/download.js +1 -1
  86. package/lib/tools/env-install.js +3 -3
  87. package/lib/tools/firmware-install.js +5 -5
  88. package/lib/tools/flash.js +8 -8
  89. package/lib/tools/generate.js +1 -1
  90. package/lib/tools/ioc-apply.js +1 -1
  91. package/lib/tools/ioc-plan.js +18 -8
  92. package/lib/tools/ioc-verify.js +11 -11
  93. package/lib/tools/project-create.js +4 -4
  94. package/lib/tools/project-dir.js +1 -1
  95. package/lib/tools/regs.js +10 -10
  96. package/lib/tools/route-plan.js +9 -9
  97. package/lib/tools/rtt.js +9 -9
  98. package/lib/tools/serial.js +8 -8
  99. package/package.json +1 -1
  100. package/templates/scaffold/RTT.md +26 -34
@@ -10,7 +10,7 @@
10
10
  * 就停下来报警——宁可让用户换目录,也不猜"这个 msys64 目录能不能覆盖"。
11
11
  *
12
12
  * 为什么装完不需要用户重读环境变量:插件自己读工具链配置(data/toolchain-config)里的绝对
13
- * 路径,装完立刻生效;PATH 只是顺手给命令行和其他工具用的。
13
+ * 路径,安装完成后立即生效;PATH 仅用于命令行和其他工具。
14
14
  *
15
15
  * 下载只用系统 curl、解压只用官方 sfx,不引第三方包(插件保持零运行时依赖)。
16
16
  */
@@ -48,7 +48,7 @@ function systemExe(name) {
48
48
  *
49
49
  * 以前用 releases/latest 的滚动资产,再靠「MZ 头 + ≥40 MB」判断真伪:镜像和 GitHub 的
50
50
  * 字节数每天可能都不一样,钉 sha256 必然误杀,所以只能粗检。代价是下载通道可以被换源、
51
- * 被中间人塞进任意 40 MB 的 exe,插件随后还会用 `-y` 静默执行它。
51
+ * 被中间人替换为任意 40 MB 的 exe,插件随后还会用 `-y` 静默执行该文件。
52
52
  *
53
53
  * 现在钉死一个有版本号的 release(2026-09-27):文件名、字节数、sha256 全部来自该 release
54
54
  * 的 GitHub API 资产元数据,且与 release 自带的 .sha256 文件一致。镜像站只同步 latest、
@@ -69,7 +69,7 @@ export const MSYS2_INSTALLER_SHA256 = "ad336cccfda47758b5e15cda993fbba421115cb0b
69
69
  /** 该资产的字节数(GitHub API 实测 43,117,824);只用于计划里的用量估算,不参与校验。 */
70
70
  export const MSYS2_INSTALLER_BYTES = 43_117_824;
71
71
  /**
72
- * 真包的体量下限(实测 42.9–43.1 MB)。小于它就是半截文件或错误页:
72
+ * 真包体量的下限(实测 42.9–43.1 MB)。小于该值即为不完整文件或错误页:
73
73
  * 半截文件若被当成有效缓存,解压会永远失败,用户只能自己猜该删哪个文件(F3d)。
74
74
  */
75
75
  const MIN_INSTALLER_BYTES = 40_000_000;
@@ -244,7 +244,7 @@ export function checkInstallerFile(path, expectedSha256) {
244
244
  /**
245
245
  * 缓存能不能当"已经下好的安装包"用(P0-1):体量下限 + MZ 头 + sha256。
246
246
  * 只查体量时,一次超时留下的半截文件、或被换掉的镜像包会被下一次当成有效缓存;
247
- * 哈希不符时保留原文件(不删用户的东西),只是不认它。
247
+ * 哈希不符时保留原文件(不删除用户文件),仅不认可该文件。
248
248
  */
249
249
  function cachedInstallerCheck(path, expectedSha256) {
250
250
  if (!existsSync(path))
@@ -270,7 +270,7 @@ function removeFileQuietly(path) {
270
270
  }
271
271
  /**
272
272
  * 清掉暂存目录/半成品。
273
- * 只对**我们自己建的**路径调用(.part 与 .dsh-msys2-staging):用户的东西一个都不删。
273
+ * 只对**本插件创建的**路径调用(.part 与 .dsh-msys2-staging):用户文件一律不删除。
274
274
  */
275
275
  function removeDirQuietly(dir) {
276
276
  try {
@@ -282,7 +282,7 @@ function removeDirQuietly(dir) {
282
282
  }
283
283
  /**
284
284
  * 是不是 Windows 盘根(C:/、C:、D:\ 这类)。
285
- * Node 的 mkdirSync 对盘根会抛 EPERM(Windows 不允许 mkdir 在盘根上"创建"它),
285
+ * Node 的 mkdirSync 对盘根会抛 EPERM(Windows 不允许 mkdir 在盘根上"创建"该目录),
286
286
  * 而 targetDir=C:/msys64 时 parent 恰好就是盘根——那是本插件自己建议的默认装法,
287
287
  * 不能让推荐路径变成必炸路径。
288
288
  */
@@ -350,7 +350,7 @@ export function resolveInstallerUrls(env) {
350
350
  sha256: "",
351
351
  note: "安装包地址来自环境变量覆盖,但缺少有效哈希",
352
352
  error: "环境变量覆盖了安装包地址,但没有同时给 MSYS2_INSTALLER_SHA256。" +
353
- "请把官方包(或你镜像里那份)的 64 位 sha256 一起写上;" +
353
+ "请同时填写官方包(或镜像副本)的 64 位 sha256;" +
354
354
  "插件不会执行一个无法校验来源的安装包。官方包哈希见 MSYS2_INSTALLER_SHA256 的默认值说明。",
355
355
  };
356
356
  }
@@ -410,7 +410,7 @@ function cacheFilePath(env) {
410
410
  /* --------------------------- pacman 镜像(F3b) --------------------------- */
411
411
  /**
412
412
  * 国内镜像的 pacman 地址。实测 2026-10:四家的 msys/x86_64/msys.db 都是 200 且同一份
413
- * 516,869 B(校验和一致 → 同步是齐的)。放在官方列表**前面**,官方条目原样保留在后面兜底。
413
+ * 516,869 B(校验和一致 → 同步完整)。放在官方列表**前面**,官方条目原样保留在后面作为回退。
414
414
  */
415
415
  const PACMAN_MIRRORS = [
416
416
  {
@@ -434,7 +434,7 @@ const PACMAN_MIRRORS = [
434
434
  mingw: "https://mirrors.aliyun.com/msys2/mingw/$repo/",
435
435
  },
436
436
  ];
437
- const MIRRORLIST_HEADER = "# dsh-stm32:把国内镜像放到最前面(官方源原样保留在后面兜底)。\n" +
437
+ const MIRRORLIST_HEADER = "# dsh-stm32:把国内镜像放到最前面(官方源原样保留在后作为回退)。\n" +
438
438
  "# 想去掉这段:删掉本注释与紧随其后的几行 Server = 即可,其余内容不受影响。\n";
439
439
  /** 把一组 Server 行提到最前;已有的不重复添加(幂等,重复调不会越堆越长)。 */
440
440
  export function preferMirrorServers(text, servers) {
@@ -482,7 +482,7 @@ export function preferChinaMirrors(msys64) {
482
482
  PACMAN_MIRRORS.map((item) => item.label).join(" / ") +
483
483
  " 放到 pacman 镜像列表最前(" +
484
484
  updated.join("、") +
485
- "),官方源保留在后面兜底;pacman 补包因此走国内线路。";
485
+ "),官方源保留在后面作为回退;pacman 补包因此走国内线路。";
486
486
  return { files: updated, note };
487
487
  }
488
488
  /** 路径所在盘符是否真的存在:跨机器的配置(配置里是 D:/app/msys64,本机没有 D 盘)不能当安装目标。 */
@@ -565,7 +565,7 @@ export function viaLabel(via) {
565
565
  case "discovered":
566
566
  return "自动发现";
567
567
  case "suggested":
568
- // 契约里的保留值:自动采用建议路径会把"装到哪"变成隐式决定,我们不这么做。
568
+ // 契约中的保留值:自动采用建议路径会使"安装位置"成为隐式决定,本插件不采用该做法。
569
569
  return "建议路径(尚未确认)";
570
570
  default:
571
571
  return "还没决定";
@@ -722,7 +722,7 @@ function broadcastPathEntry(entry) {
722
722
  if (process.platform === "win32")
723
723
  process.env.Path = next;
724
724
  }
725
- /** 读不到时的兜底说明:给可手动执行的写法,但要求用户自己先确认旧值(我们读不到就无法替他拼)。 */
725
+ /** 读取失败时的回退说明:给出可手动执行的写法,但要求用户先自行确认旧值(本插件读取失败,无法代为拼接)。 */
726
726
  function manualPathHint(entry) {
727
727
  return ("先在命令行跑 reg query \"" +
728
728
  PATH_KEY +
@@ -734,7 +734,7 @@ function manualPathHint(entry) {
734
734
  entry +
735
735
  "\" /f —— 其中 <完整旧值> 必须换成真的旧值(别用空串;也别用 setx,setx 会在 1024 字符处截断 PATH)");
736
736
  }
737
- /** 读失败时的统一开场白:卡片、步骤 detail、message 都用它,测试与用户都能一眼认出。 */
737
+ /** 读失败时的统一开场白:卡片、步骤 detail 与 message 均使用该文案,测试与用户均可直接识别。 */
738
738
  const UNREADABLE_PATH_PREFIX = "读不到当前用户 PATH";
739
739
  function planPathState(current, binDir, writePath) {
740
740
  const state = {
@@ -838,7 +838,7 @@ const EXTRACT_CANCELLED = "已取消(解压还没做完)";
838
838
  async function extractInstaller(subprocess, sfxPath, targetDir, request, timeoutMs) {
839
839
  const parent = toPosix(dirname(targetDir));
840
840
  const staging = parent + "/.dsh-msys2-staging";
841
- // 只清自己建的暂存目录(固定名字):上次崩在中途,残渣也不会被当成成功。
841
+ // 只清理自身创建的暂存目录(固定名称):上次中途异常退出时,残留内容不会被当成成功。
842
842
  removeDirQuietly(staging);
843
843
  try {
844
844
  mkdirSync(staging, { recursive: true });
@@ -868,7 +868,7 @@ async function extractInstaller(subprocess, sfxPath, targetDir, request, timeout
868
868
  ...(request.signal === undefined ? {} : { signal: request.signal }),
869
869
  });
870
870
  // A29:用户按了停止(或被上层 abort)不是"解压失败"。先判取消,别走失败路径去删暂存目录:
871
- // 半份解压结果留着,下次进这里第一件事就是清它,不用用户自己收拾。
871
+ // 未完成的解压结果会保留,下次进入时第一步即清理该目录,无需用户手动处理。
872
872
  if (outcome.aborted || isAborted(request.signal)) {
873
873
  return { ok: false, cancelled: true, detail: EXTRACT_CANCELLED, staging };
874
874
  }
@@ -914,7 +914,7 @@ async function extractInstaller(subprocess, sfxPath, targetDir, request, timeout
914
914
  cancelled: false,
915
915
  detail: "解压好了,但目标目录在解压期间变成非空:" +
916
916
  targetDir +
917
- "(没有覆盖它);解压结果留在 " +
917
+ "(未覆盖原目录);解压结果留在 " +
918
918
  extractedRoot,
919
919
  staging,
920
920
  };
@@ -946,7 +946,7 @@ const PACMAN_UPGRADE_COMMAND = "pacman -Syu --noconfirm";
946
946
  function pacmanOk(outcome) {
947
947
  return outcome.spawnError === null && !outcome.timedOut && outcome.exitCode === 0;
948
948
  }
949
- /** 只用现有数据库补包:已有 MSYS2 上不先 -Sy,免得"局部升级"把依赖解析搞崩。 */
949
+ /** 只用现有数据库补包:已有 MSYS2 上不先执行 -Sy,避免"局部升级"破坏依赖解析。 */
950
950
  function pacmanInstallCommand(packages) {
951
951
  return "pacman -S --noconfirm --needed " + packages.join(" ");
952
952
  }
@@ -1027,7 +1027,7 @@ function shortPackageName(name) {
1027
1027
  function fillPlanDetails(steps, context) {
1028
1028
  const rootLabel = context.msys64 === "" ? "(装哪还没定)" : context.msys64;
1029
1029
  setStep(stepOf(steps, "prepare"), context.existing ? "skipped" : "pending", context.msys64 === ""
1030
- ? "目标目录待定;定了之后先确保它的父目录存在"
1030
+ ? "目标目录待定;确定后先确保其父目录存在"
1031
1031
  : context.existing
1032
1032
  ? context.msys64 + " 里已经有一份能用的 MSYS2(有 usr/bin/bash.exe),不用建目录、不用重装"
1033
1033
  : "确保父目录存在:" +
@@ -1037,7 +1037,7 @@ function fillPlanDetails(steps, context) {
1037
1037
  ? "已有完整 MSYS2,不需要安装包(省 " + formatBytes(MSYS2_INSTALLER_BYTES) + " 下载)"
1038
1038
  : context.cacheOk
1039
1039
  ? "复用缓存:" + context.cachePath + "(" + formatBytes(MSYS2_INSTALLER_BYTES) + ",不会再下载)"
1040
- : "按候选链下载(国内镜像优先,GitHub 兜底),第一个成功的落盘到 " +
1040
+ : "按候选链下载(国内镜像优先,GitHub 回退),第一个成功的落盘到 " +
1041
1041
  context.cachePath +
1042
1042
  "(约 " +
1043
1043
  formatBytes(MSYS2_INSTALLER_BYTES) +
@@ -1116,7 +1116,7 @@ function planMessage(msys64, via, packages, download, facts) {
1116
1116
  ",有 usr/bin/bash.exe)," +
1117
1117
  String(packages.length) +
1118
1118
  " 个组件也都装着" +
1119
- (facts.pathEntryPresent ? ",用户 PATH 里也有它" : "") +
1119
+ (facts.pathEntryPresent ? ",用户 PATH 中也包含该目录" : "") +
1120
1120
  (facts.configMatches ? ",配置已经写好" : "") +
1121
1121
  "。没有下载、没有建目录、没有写注册表、没有改配置。");
1122
1122
  }
@@ -1194,16 +1194,16 @@ function usageNote(facts, download, packages) {
1194
1194
  "(估算:安装包 + 分包的总量按 3 倍粗算,含解压后的文件与 pacman 缓存,不是精确占用)。");
1195
1195
  }
1196
1196
  function decisionMessage(suggested, packages, download) {
1197
- return ("需要你先决定装哪:这台机器上没有可用的 MSYS2(配置里没有、自动扫描也没找到 usr/bin/bash.exe)," +
1198
- "我不猜路径。建议装到 " +
1197
+ return ("需要先确定安装位置:这台机器上没有可用的 MSYS2(配置中未指定,自动扫描也未找到 usr/bin/bash.exe)," +
1198
+ "本插件不猜测路径。建议安装到 " +
1199
1199
  suggested +
1200
1200
  "(安装包 " +
1201
1201
  formatBytes(download.bytes) +
1202
1202
  " + 分包约 " +
1203
1203
  formatBytes(msys2PackagesTotal(packages)) +
1204
- " 估算)。给我 targetDir、或回一句「装到 " +
1204
+ " 估算)。请提供 targetDir,或回复「装到 " +
1205
1205
  suggested +
1206
- "」,我再出计划;现在什么都没装。");
1206
+ "」,随后生成计划;当前未安装任何内容。");
1207
1207
  }
1208
1208
  function verifySummary(verify) {
1209
1209
  const found = verify.tools.filter((tool) => tool.found);
@@ -1220,7 +1220,7 @@ function verifySummary(verify) {
1220
1220
  }
1221
1221
  /**
1222
1222
  * path 是不是在 dir 之下(大小写与斜杠不敏感)。
1223
- * 自检用它确认"跑起来的那个工具"确实来自目标 binDir,而不是 PATH 上的同名文件。
1223
+ * 自检使用该函数确认"实际运行的工具"确实来自目标 binDir,而非 PATH 上的同名文件。
1224
1224
  */
1225
1225
  function isInsideDir(path, dir) {
1226
1226
  const base = toPosix(dir).replace(/\/+$/u, "").toLowerCase();
@@ -1256,7 +1256,7 @@ async function curlOnce(subprocess, url, partPath, cacheDir, timeoutMs, resume,
1256
1256
  "--speed-time",
1257
1257
  String(Math.round(DOWNLOAD_STALL_MS / 1000)),
1258
1258
  ];
1259
- // F3c:-C - 断点续传。缓存目录里有 .part 时从它的长度接着下;没有就当普通下载。
1259
+ // F3c:-C - 断点续传。缓存目录中存在 .part 时从其长度继续下载;不存在时按普通下载处理。
1260
1260
  if (resume)
1261
1261
  argv.push("-C", "-");
1262
1262
  argv.push("-o", partPath, url);
@@ -1376,7 +1376,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1376
1376
  cachePath +
1377
1377
  " 不可用:" +
1378
1378
  cached.reason +
1379
- "。会重新下载;原文件不删,留给你自己判断。");
1379
+ "。会重新下载;原文件不删除,保留给用户自行判断。");
1380
1380
  }
1381
1381
  if (target.warning !== "")
1382
1382
  notes.push("⚠ " + target.warning);
@@ -1430,7 +1430,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1430
1430
  let planProbed = [];
1431
1431
  let verifyOk = false;
1432
1432
  let verifyText = "";
1433
- // CubeMX 不在这 5 件里,但它决定能不能走 HAL 路线:缺它时紧凑卡片必须补一句,
1433
+ // CubeMX 不在这 5 个组件中,但 CubeMX 决定能否走 HAL 路线:缺少 CubeMX 时紧凑卡片必须补充一句,
1434
1434
  // 否则"工具链完整"会让人以为 HAL 工程也能直接生成。
1435
1435
  let cubemxReady = false;
1436
1436
  if (binDir !== "" && existsSync(binDir)) {
@@ -1508,7 +1508,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1508
1508
  (cubemxReady
1509
1509
  ? ""
1510
1510
  : "要写 HAL 库程序还需要从 ST 官网装 STM32CubeMX(含内置 JRE,约 1.5 GB," +
1511
- "https://www.st.com/en/development-tools/stm32cubemx.html);纯寄存器程序不需要它。"),
1511
+ "https://www.st.com/en/development-tools/stm32cubemx.html);纯寄存器程序不需要该组件。"),
1512
1512
  nextStep: "",
1513
1513
  notes: [],
1514
1514
  durationMs: Date.now() - started,
@@ -1555,7 +1555,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1555
1555
  : decisionMessage(suggested, packages, download)),
1556
1556
  nextStep: decided
1557
1557
  ? confirmHint
1558
- : "定下安装位置(targetDir,或回一句「装到 " + suggested + "」),我再出一份计划。",
1558
+ : "定下安装位置(targetDir,或回一句「装到 " + suggested + "」),随后生成一份计划。",
1559
1559
  notes,
1560
1560
  durationMs: Date.now() - started,
1561
1561
  };
@@ -1645,7 +1645,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1645
1645
  String(entries.length) +
1646
1646
  " 项),但不是完整 MSYS2(缺 usr/bin/bash.exe)");
1647
1647
  skipAfter(steps, "prepare", "目标目录不可用,未执行");
1648
- return finish(false, "没有开始:目标目录 " + msys64 + " 已存在且不是一份完整 MSYS2,我不覆盖也不删除它。", "换一个空目录(例如 " +
1648
+ return finish(false, "没有开始:目标目录 " + msys64 + " 已存在且不是一份完整的 MSYS2,不覆盖也不删除该目录。", "换一个空目录(例如 " +
1649
1649
  (msys64 === MSYS2_SUGGESTED_ROOT ? "D:/msys64" : MSYS2_SUGGESTED_ROOT) +
1650
1650
  ")再装,或先确认那个目录里放的是什么。");
1651
1651
  }
@@ -1656,14 +1656,14 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1656
1656
  const reason = describeError(error);
1657
1657
  setStep(prepareStep, "failed", reason);
1658
1658
  skipAfter(steps, "prepare", "父目录建不了,未执行");
1659
- // 0c:失败时给一条不依赖本工具的手动兜底——下载好的 sfx 安装包自己就能解压,
1659
+ // 0c:失败时给出一条不依赖本工具的手动回退路径——已下载的 sfx 安装包可直接解压,
1660
1660
  // 手动装好后重跑本工具会直接走 alreadyInstalled(检测的是 usr/bin/bash.exe,不是本工具写的标记)。
1661
1661
  const manualSteps = [
1662
- "手动兜底(不依赖本工具):",
1662
+ "手动回退方式(不依赖本工具):",
1663
1663
  " 1. 下载安装包(任一源都行):" + primaryUrl,
1664
1664
  " 2. 手动解压到目标盘:进入下载目录后执行 <安装包文件> -y -o" + (parent === "" ? "C:\\\\" : toWindowsDir(parent)),
1665
- " (sfx 会在所选目录下解压出 msys64/;把它改名或移动到 " + msys64 + " 即可)",
1666
- " 3. 重跑本工具:它会检测到 usr/bin/bash.exe 并直接复用,不再下载、不再解压。",
1665
+ " (sfx 会在所选目录下解压出 msys64/;将该目录改名或移动到 " + msys64 + " 即可)",
1666
+ " 3. 重新运行本工具:检测到 usr/bin/bash.exe 后将直接复用,不再下载、不再解压。",
1667
1667
  ].join("\n");
1668
1668
  return finish(false, "没能准备安装目录:" + reason, "检查路径是否合法、有没有写权限,或换一个 targetDir。\n" + manualSteps);
1669
1669
  }
@@ -1747,12 +1747,12 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1747
1747
  return finish(false, "已取消:解压还没做完,安装包已缓存在 " +
1748
1748
  cachePath +
1749
1749
  (extracted.staging === "" ? "" : ",暂存目录 " + extracted.staging + " 保留着") +
1750
- "。", "取消不等于失败——要接着装就再调一次(已下载的安装包直接用),暂存目录会在下次解压开始时自动清掉,不用你先收拾。");
1750
+ "。", "取消不属于失败——如需继续安装,再次调用即可(已下载的安装包直接使用),暂存目录会在下次解压开始时自动清理,无需用户手动处理。");
1751
1751
  }
1752
1752
  if (!extracted.ok) {
1753
1753
  setStep(extractStep, "failed", extracted.detail);
1754
1754
  skipAfter(steps, "extract", "解压没成功,未执行");
1755
- return finish(false, "解压失败:" + extracted.detail, "安装包已缓存在 " + cachePath + ",修好问题后重试不会重新下载;也可以手动把它解压到 " + msys64 + "。");
1755
+ return finish(false, "解压失败:" + extracted.detail, "安装包已缓存在 " + cachePath + ",修复问题后重试不会重新下载;也可以手动将其解压到 " + msys64 + "。");
1756
1756
  }
1757
1757
  // F3d 第三道:解压自检。sfx 退出码 0 不代表解出来的是完整 MSYS2——
1758
1758
  // 半截安装包有时也能压出一半目录,缺 usr/bin/bash.exe 就等于白装。
@@ -1799,7 +1799,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1799
1799
  awaitQuiescence: true,
1800
1800
  ...(request.signal === undefined ? {} : { signal: request.signal }),
1801
1801
  });
1802
- // 先问一句"哪些已经装了"。pacman -S 对已装的包不是"跳过"而是"顺手升级",
1802
+ // 先查询"哪些已经安装"。pacman -S 对已安装的包不是"跳过"而是"同时升级",
1803
1803
  // 在第 4 步把用户整套 mingw 工具链升一个大版本不是本工具的活(那是 pacman -Syu 的事)。
1804
1804
  const query = await runPacman("pacman -Q " + packages.join(" "));
1805
1805
  const installed = parsePacmanQuery(query.stdout);
@@ -1847,7 +1847,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1847
1847
  " 后重试。");
1848
1848
  }
1849
1849
  }
1850
- // -Syu 成功只代表库和基包是新的,我们缺的 5 个组件还得单独补。
1850
+ // -Syu 成功只代表库和基包为最新,缺少的 5 个组件仍需单独安装。
1851
1851
  if (needsSync && command === PACMAN_UPGRADE_COMMAND && pacmanOk(pacman)) {
1852
1852
  command = installCommand;
1853
1853
  pacman = await runPacman(command);
@@ -1868,7 +1868,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1868
1868
  if (existsSync(lockPath)) {
1869
1869
  notes.push("pacman 的锁还在:" +
1870
1870
  lockPath +
1871
- "(一般是被中断或强杀留下的)。先确认没有 pacman / bash 进程在跑,删掉它再重试:" +
1871
+ "(通常由中断或强制结束产生)。先确认没有 pacman / bash 进程在运行,删除该锁后再重试:" +
1872
1872
  bashLine(msys64, "rm -f /var/lib/pacman/db.lck") +
1873
1873
  ";锁在的时候 pacman 会一律拒绝开工。");
1874
1874
  }
@@ -1876,7 +1876,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1876
1876
  if (/conflicting files|exists in filesystem|conflicts with/u.test((pacman.stdout + " " + pacman.stderr).toLowerCase())) {
1877
1877
  notes.push("pacman 报的是文件冲突(conflicting files / exists in filesystem):先整体升级一次(" +
1878
1878
  bashLine(msys64, PACMAN_UPGRADE_COMMAND) +
1879
- ");确认某几个文件被别的包占着、确实要顶掉时再自己加 --overwrite。本工具不会替你覆盖别人的文件。");
1879
+ ");确认某些文件被其他包占用、确需覆盖时再自行添加 --overwrite。本工具不会覆盖属于其他包的文件。");
1880
1880
  }
1881
1881
  // 不当场放弃:MSYS2 本体在,PATH / 配置照写,报告里把失败点写清楚。
1882
1882
  setStep(pacmanStep, "failed", reason +
@@ -1917,7 +1917,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1917
1917
  ? ""
1918
1918
  : "\n手动:把 " +
1919
1919
  toWindowsDir(binDir) +
1920
- " 追加到「环境变量 → 用户变量 → Path」(不要用 setx,它会在 1024 字符处截断 PATH)";
1920
+ " 追加到「环境变量 → 用户变量 → Path」(不要使用 setx,该命令会在 1024 字符处截断 PATH)";
1921
1921
  setStep(pathStep, "failed", pathState.error + manual);
1922
1922
  }
1923
1923
  }
@@ -1929,7 +1929,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1929
1929
  const targets = buildTargets(probeConfig).filter((item) => VERIFY_IDS.includes(item.id));
1930
1930
  const probed = await probeAll(subprocess, targets, probeConfig, {
1931
1931
  timeoutMs: PROBE_TIMEOUT_MS,
1932
- // 自检只认这个目录。允许 PATH 兜底的话,机器上另一份同名工具(STM32CubeIDE 自带、
1932
+ // 自检只认该目录。若允许 PATH 回退,机器上其他同名工具(STM32CubeIDE 自带、
1933
1933
  // xpack、旧的 msys64)会让"没装进目标目录"看起来像"装好了"。
1934
1934
  allowPathFallback: false,
1935
1935
  ...(request.signal === undefined ? {} : { signal: request.signal }),
@@ -1967,14 +1967,14 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1967
1967
  // 一个例外:pacman 补装失败,但 5 个组件都**从 binDir 里**跑起来了(自检通过且没有外来工具),
1968
1968
  // 说明这个目录本来就不缺东西——那不是"没装成",如实记一行、继续当成功。
1969
1969
  // 反过来,只要有一个工具来自 binDir 之外,就不能改判:配置里最终指的是这个目录,
1970
- // 而它其实没装好,用户下次编译才会撞上。
1970
+ // 而该目录实际未安装完整,用户下次编译时才会遇到问题。
1971
1971
  if (verifyState.ok && strayTools.length === 0 && pacmanStep.status === "failed") {
1972
1972
  pacmanStep.status = "done";
1973
1973
  pacmanStep.detail =
1974
1974
  pacmanStep.detail +
1975
1975
  "\n但自检显示 5 个组件都是在 " +
1976
1976
  binDir +
1977
- " 里跑起来的,按「已装」处理(插件不替你升级,要升级自己跑 pacman -Syu)。";
1977
+ " 里运行的,按「已安装」处理(本插件不代为升级,升级需自行运行 pacman -Syu)。";
1978
1978
  }
1979
1979
  const fatal = steps.find((step) => step.status === "failed" && step.id !== "path");
1980
1980
  const ok = fatal === undefined;
@@ -1985,7 +1985,7 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1985
1985
  " 了," +
1986
1986
  verifySummary(verifyState) +
1987
1987
  ";现在可以编译 / 烧录 / 调试。" +
1988
- // 读不到 PATH 与"写了但失败"是两种事:前者一句"没写成功"会让用户以为是我们写坏了,
1988
+ // 读取 PATH 失败与"写入但失败"是两种情况:前者仅提示"未写入成功"会让用户误认为是本插件写坏,
1989
1989
  // 所以这里把"为安全起见没动注册表"直接写进 message。
1990
1990
  (pathFailed
1991
1991
  ? pathState.error.startsWith(UNREADABLE_PATH_PREFIX)
@@ -1998,14 +1998,14 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
1998
1998
  .map((step) => step.label)
1999
1999
  .join("、") +
2000
2000
  "(每一步的原因都在 steps 里)。" +
2001
- // 自检禁用了 PATH 兜底,这里必须说清"能跑"不等于"装到了目标目录",
2002
- // 否则用户看着别处的 gcc 好好的,会以为是我们判错了。
2001
+ // 自检禁用了 PATH 回退,此处必须说明"能运行"不等于"已安装到目标目录",
2002
+ // 否则用户看到其他位置的 gcc 运行正常时,会误认为是本插件判断错误。
2003
2003
  (strayTools.length > 0
2004
2004
  ? " 能跑的那几个不在 " +
2005
2005
  binDir +
2006
2006
  " 里(" +
2007
2007
  strayTools.map((tool) => tool.path).join("、") +
2008
- "),说明它们本来就在别的目录,这个目录并没有装好。"
2008
+ "),说明这些工具原本位于其他目录,该目录并未安装完整。"
2009
2009
  : pacmanStep.status === "failed" && !verifyState.ok
2010
2010
  ? " 自检只在 " + binDir + " 里找:PATH 上另一份同名工具不算装到这个目录。"
2011
2011
  : "") +
@@ -2014,6 +2014,6 @@ export async function planOrInstallMsys2(subprocess, request, env = process.env)
2014
2014
  ? " pacman 那一步的修法:先在 " + msys64 + " 里跑 " + bashLine(msys64, PACMAN_UPGRADE_COMMAND) + "(整体升级),再重调本工具;只同步软件库再补单个包属于局部升级,依赖会解不开。"
2015
2015
  : "");
2016
2016
  return finish(ok, message, ok
2017
- ? "直接重跑你刚才的工具(stm32_build / stm32_flash / stm32_debug_run);也可以用 stm32_doctor 复看一遍。"
2017
+ ? "直接重新运行刚才的工具(stm32_build / stm32_flash / stm32_debug_run);也可使用 stm32_doctor 复查一遍。"
2018
2018
  : "看 steps 里失败那一步的 detail;修好后重调本工具,已完成的步骤会自动跳过(不会重复下载、不会重复写 PATH)。");
2019
2019
  }
@@ -1,18 +1,18 @@
1
1
  /**
2
2
  * B2:结构化探针错误 —— flash / debug / session 三条路径共用一份分类。
3
3
  *
4
- * 为什么要有它:2d 的错误码只是一张枚举,失败时模型还得去读中文 message 才知道下一步。
4
+ * 为什么单独定义:2d 的错误码只是一张枚举,失败时模型仍需阅读中文 message 才能确定下一步。
5
5
  * 现在一次分类就给全五样东西:
6
- * - kind:契约字段(模型可以按它分支),旧错误码字段直接删掉,不做兼容别名(用户已定);
6
+ * - kind:契约字段(模型可按该字段分支),旧错误码字段直接删除,不保留兼容别名(用户已定);
7
7
  * - cause:一句话根因,给人看也够;
8
8
  * - hint:可执行的下一步(四类真机验过的故障各自有专属文案);
9
9
  * - evidence:原始日志行,逐字保留,别让模型凭二手转述猜;
10
- * - retryable:照 hint 弄完再调一次同一个工具有没有意义(true=值得重试)。
10
+ * - retryable:按 hint 处理后再调用同一个工具是否有意义(true=值得重试)。
11
11
  *
12
12
  * 归类顺序敏感:先 no-probe 再 probe-busy —— 把"被占用"读成"没插"会让人白拔线。
13
13
  * 同一套规则同时服务 flash(openocd program)与 debug(openocd + gdb),改一处两边一起变。
14
14
  */
15
- /** 枚举的运行时形态(工具 schema 的 enum 也用它,避免第二个真相)。 */
15
+ /** 枚举的运行时形态(工具 schema 的 enum 同样使用该数组,避免出现第二份定义)。 */
16
16
  export const PROBE_ERROR_KINDS = [
17
17
  "no-probe",
18
18
  "probe-interface-mismatch",
@@ -26,7 +26,7 @@ export const PROBE_ERROR_KINDS = [
26
26
  ];
27
27
  // ── 文案:hint 是给用户的下一步,cause 是一句话根因 ────────────────────────────────
28
28
  export const HINT_PROBE = "找不到 CMSIS-DAP 探针:检查 USB、是否被 openocd/调试会话占用(先停掉正在跑的调试),必要时换一根数据线再试。";
29
- export const HINT_BUSY = "探针没有正常响应:先确认没有第二个 openocd / 调试会话在同时用它(两个 openocd 抢同一个 CMSIS-DAP 时不报错,而是满屏 transfer count mismatch);如果确认只有一个进程,那就是探针固件卡住了——把探针拔下来等 3 秒再插回,然后重试。";
29
+ export const HINT_BUSY = "探针没有正常响应:先确认没有第二个 openocd / 调试会话同时占用该探针(两个 openocd 争用同一个 CMSIS-DAP 时不报错,而是持续输出 transfer count mismatch);确认只有一个进程时,说明探针固件已无响应——拔下探针等待 3 秒再插回,然后重试。";
30
30
  export const HINT_DP = "连不上芯片(Error connecting DP):固件里可能关了 SWD(__HAL_AFIO_REMAP_SWJ_DISABLE),需要 BOOT0=1 重启进系统 bootloader 再烧,或按住复位键在连接瞬间松开。";
31
31
  export const HINT_FLASH_PROTECTED = "Flash 被写保护/读保护挡住:先做一次全片擦除(openocd 的 stm32f1x mass_erase)或解除读保护(RDP)再烧;量产片上确实要保持保护时,这次烧录就不可能成功,别再原地重试。";
32
32
  export const HINT_NO_POWER = "目标板没供电:量一下 3V3/GND,检查 BOOT0/BOOT1 跳线与杜邦线接触,USB 供电不足时换独立电源再试。";
@@ -122,7 +122,7 @@ const MATCHERS = [
122
122
  re: /cannot identify target|unexpected idcode|unknown device|doesn't match the target/u,
123
123
  },
124
124
  ];
125
- /** 一条"看起来像根因"的行;只用于 unknown / 超时的 evidence 兜底。 */
125
+ /** 一条「看起来像根因」的行;只用于 unknown / 超时的 evidence 回退。 */
126
126
  const PROBLEM_LINE_RE = /error|unable to find|no device found|couldn't bind|cannot open|invalid/u;
127
127
  const MAX_EVIDENCE = 4;
128
128
  function nonEmpty(lines) {
@@ -153,13 +153,13 @@ export function firstProblemLine(lines) {
153
153
  export function probeMissingLines(errors) {
154
154
  return errors.filter((line) => /CMSIS-DAP device|no device found/iu.test(line));
155
155
  }
156
- /** USB 形态诊断的结论该以什么 note 呈现(unknown 静默:诊断失败不能把失败报告搞得更吵)。 */
156
+ /** USB 形态诊断结论以何种 note 呈现(unknown 静默:诊断失败不得增加失败报告的噪声)。 */
157
157
  export function usbNoteFor(kind, detail) {
158
158
  if (kind === "unknown")
159
159
  return null;
160
160
  return "USB 形态:" + detail;
161
161
  }
162
- /** 每一类的默认根因(调用方没给更准的说法时用它,避免出现"未知原因"这种废话)。 */
162
+ /** 每一类的默认根因(调用方未给出更准确说法时使用,避免出现「未知原因」这类空泛描述)。 */
163
163
  const CAUSE_BY_KIND = {
164
164
  "no-probe": "找不到探针(没插好 / 被占用 / 本机没认到 USB 设备)",
165
165
  "probe-interface-mismatch": "openocd 找不到配置里指定的探针驱动(interface 与实插类型不匹配)",
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * 背景:`stm32_regs_read` 原来是"起 openocd → mdw → shutdown",实测 1493 ms;而
5
5
  * `stm32_debug_eval` 每次也要新起一个 `gdb -batch`。两者都太慢,但慢的不是"读",
6
- * 是进程启动。这里把"常驻 openocd"这件事抽成一个小门面,让两条路都走它:
6
+ * 是进程启动。此处把「常驻 openocd」抽象为统一入口,两条路径共用:
7
7
  *
8
8
  * - `ensureSession()`:没有会话就起一个(复用 `debug-session.ts` 的租约/Turn 收尾/端口让位),
9
9
  * 有同项目的会话就直接复用(`reused=true`);
@@ -33,7 +33,7 @@ const TCL_FRAME = String.fromCharCode(0x1a);
33
33
  * 不需要再等一个"庄家时间"(那会让每次读白等几十毫秒)。
34
34
  */
35
35
  const TCL_DONE_MS = 0;
36
- /** 响应不齐(比如某条命令被 openocd 拒了但没回帧)时的兜底等待。 */
36
+ /** 响应不齐(例如某条命令被 openocd 拒绝但未回帧)时的回退等待。 */
37
37
  const TCL_IDLE_MS = 120;
38
38
  /** 并发去重:同时来两个 ensureSession 时只起一个 openocd(后到的直接复用同一个 Promise)。 */
39
39
  let starting = null;
@@ -263,7 +263,7 @@ export async function tclRoundTrip(port, commands, timeoutMs = 5_000, signal) {
263
263
  }
264
264
  if (idleTimer !== null)
265
265
  clearTimeout(idleTimer);
266
- // 收齐了就立刻收尾;没齐就按空闲兜底(万一某条命令没回帧,也不至于卡死)。
266
+ // 收齐后立即收尾;未收齐则按空闲时间回退(某条命令未回帧时不会一直阻塞)。
267
267
  idleTimer = setTimeout(() => { finish(null); }, replies.length >= commands.length ? TCL_DONE_MS : TCL_IDLE_MS);
268
268
  };
269
269
  signal?.addEventListener("abort", onAbort, { once: true });