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
package/client/client.js CHANGED
@@ -9,11 +9,11 @@ window.__ModuleLoader__.load({
9
9
  * dsh-stm32 浏览器端设置面板(手写纯 JS,不经 tsc)。
10
10
  *
11
11
  * 为什么文件第一行就是 load({:宿主客户端模块加载器按这个自执行包装取走并执行本文件,
12
- * 注释放在包装外面会被当成"包装前有别的语句",与 dsh-client-ui-* 的产物形状不一致。
12
+ * 注释放在包装外面会被当成"包装前有其他语句",与 dsh-client-ui-* 的产物形状不一致。
13
13
  *
14
14
  * 为什么是纯 JS:本文件由宿主加载器直接执行,不经过插件的 TS 构建链;
15
15
  * 写成 TS/JSX 会多出一份由 tsc 决定产物路径的中间层,而面板的正确产物就是
16
- * client/client.js 原文(scripts/copy-client.mjs 把它原样复制到 lib/client.js)。
16
+ * client/client.js 原文(scripts/copy-client.mjs 将其原样复制到 lib/client.js)。
17
17
  * 所以这里只用手写 React.createElement,且只 require 外壳种子词:
18
18
  * react / react/jsx-runtime / primitives。
19
19
  *
@@ -44,14 +44,14 @@ window.__ModuleLoader__.load({
44
44
  try {
45
45
  return new URL(API_RELATIVE + path, base).toString();
46
46
  } catch {
47
- // 极早的加载时机(document 还没就位):退回根路径,至少不会让面板整个炸掉。
47
+ // 极早的加载时机(document 还没就位):退回根路径,避免面板整体失效。
48
48
  return "/dsh-stm32/api/" + path;
49
49
  }
50
50
  }
51
51
 
52
52
  /**
53
53
  * 调一次面板接口。返回值刻意统一成 { ok, value } / { ok:false, error }:
54
- * 面板上每个操作只要关心"成了没成、为什么没成",不用各自解析 HTTP 语义。
54
+ * 面板上每个操作只需关心"是否成功、失败原因",无需各自解析 HTTP 语义。
55
55
  */
56
56
  async function callApi(method, path, body) {
57
57
  const url = apiUrl(path);
@@ -466,8 +466,8 @@ window.__ModuleLoader__.load({
466
466
  e(
467
467
  "div",
468
468
  { style: styles.cardHead },
469
- e("h3", { style: styles.cardTitle }, "装在哪"),
470
- e("p", { style: styles.cardNote }, loadingConfig ? "读取配置中…" : configExists ? "配置文件已存在" : "还没有配置文件(保存时创建)"),
469
+ e("h3", { style: styles.cardTitle }, "工具链路径配置"),
470
+ e("p", { style: styles.cardNote }, loadingConfig ? "读取配置中…" : configExists ? "配置文件已加载" : "暂无配置文件,保存时自动生成"),
471
471
  ),
472
472
  e("p", { style: styles.mono }, configPath === "" ? "(配置路径未知)" : "配置: " + configPath),
473
473
  configDisabled
@@ -485,7 +485,7 @@ window.__ModuleLoader__.load({
485
485
  type: "text",
486
486
  value: msys64,
487
487
  spellCheck: false,
488
- placeholder: "例如 D:/app/msys64(空 = 不指定)",
488
+ placeholder: "示例:C:/msys64,留空表示不指定",
489
489
  onChange: (event) => setMsys64(event.target.value),
490
490
  }),
491
491
  ),
@@ -499,20 +499,20 @@ window.__ModuleLoader__.load({
499
499
  type: "text",
500
500
  value: cubeMxRoot,
501
501
  spellCheck: false,
502
- placeholder: "例如 D:/app/STM32CubeMX(空 = 自动找)",
502
+ placeholder: "示例:C:/STM32CubeMX,留空自动检索",
503
503
  onChange: (event) => setCubeMxRoot(event.target.value),
504
504
  }),
505
505
  ),
506
506
  e(
507
507
  "div",
508
508
  { style: { display: "flex", flexDirection: "column", gap: "4px" } },
509
- e("label", { style: { opacity: 0.8 }, htmlFor: "dsh-stm32-bindirs" }, "额外 bin 目录(每行一个,留空 = 用 MSYS2 推导 / 自动发现)"),
509
+ e("label", { style: { opacity: 0.8 }, htmlFor: "dsh-stm32-bindirs" }, "附加 Bin 目录(每行一条,留空将基于 MSYS2 自动推导)"),
510
510
  e("textarea", {
511
511
  id: "dsh-stm32-bindirs",
512
512
  style: styles.textarea,
513
513
  value: binDirsText,
514
514
  spellCheck: false,
515
- placeholder: "D:/app/msys64/ucrt64/bin",
515
+ placeholder: "C:/msys64/ucrt64/bin",
516
516
  onChange: (event) => setBinDirsText(event.target.value),
517
517
  }),
518
518
  ),
@@ -522,7 +522,7 @@ window.__ModuleLoader__.load({
522
522
  e("button", { type: "button", style: styles.buttonPrimary, disabled: saving, onClick: () => void save() }, saving ? "保存中…" : "保存配置"),
523
523
  saveNote === null ? null : e("p", { style: saveNote.ok ? styles.ok : styles.error }, String(saveNote.text)),
524
524
  ),
525
- e("p", { style: styles.cardNote }, "改完立即生效(插件每次自己读配置文件,不用重开 DSH)。"),
525
+ e("p", { style: styles.cardNote }, "配置修改后即时生效,无需重启 DSH。"),
526
526
  );
527
527
 
528
528
  const tools = probe !== null && typeof probe === "object" && Array.isArray(probe.tools) ? probe.tools : [];
@@ -532,8 +532,8 @@ window.__ModuleLoader__.load({
532
532
  e(
533
533
  "div",
534
534
  { style: styles.cardHead },
535
- e("h3", { style: styles.cardTitle }, "缺什么"),
536
- e("p", { style: styles.cardNote }, "按上面三个框里的值探测;留空就走自动发现。"),
535
+ e("h3", { style: styles.cardTitle }, "工具链探测"),
536
+ e("p", { style: styles.cardNote }, "依据上方配置路径执行探测,路径留空时启用自动检索。"),
537
537
  ),
538
538
  e(
539
539
  "div",
@@ -542,7 +542,7 @@ window.__ModuleLoader__.load({
542
542
  ),
543
543
  probeError === "" ? null : e("p", { style: styles.error }, probeError),
544
544
  probe === null
545
- ? e("p", { style: styles.muted }, "还没探测过。探测会跑一次各工具的版本命令,不会装任何东西。")
545
+ ? e("p", { style: styles.muted }, "尚未执行探测。探测仅读取工具版本信息,不会执行安装操作。")
546
546
  : e(
547
547
  "div",
548
548
  { style: { display: "flex", flexDirection: "column", gap: "8px" } },
@@ -564,15 +564,15 @@ window.__ModuleLoader__.load({
564
564
  e(
565
565
  "div",
566
566
  { style: styles.cardHead },
567
- e("h3", { style: styles.cardTitle }, "装工具链"),
568
- e("p", { style: styles.cardNote }, "先出计划(不下载、不写盘),确认后才真装。"),
567
+ e("h3", { style: styles.cardTitle }, "工具链安装"),
568
+ e("p", { style: styles.cardNote }, "首先生成安装方案(不会下载或写入文件),确认后再执行安装。"),
569
569
  ),
570
570
  e(
571
571
  "div",
572
572
  { style: styles.row },
573
- e("button", { type: "button", style: styles.button, disabled: planning, onClick: () => void runPlan() }, planning ? "算计划中…" : "出安装计划"),
573
+ e("button", { type: "button", style: styles.button, disabled: planning, onClick: () => void runPlan() }, planning ?"生成方案中…" : "生成安装方案"),
574
574
  plan !== null && !confirmInstall && taskId === ""
575
- ? e("button", { type: "button", style: styles.buttonDanger, onClick: () => setConfirmInstall(true) }, "开始安装…")
575
+ ? e("button", { type: "button", style: styles.buttonDanger, onClick: () => setConfirmInstall(true) }, "执行安装")
576
576
  : null,
577
577
  ),
578
578
  planError === "" ? null : e("p", { style: styles.error }, planError),
@@ -582,8 +582,8 @@ window.__ModuleLoader__.load({
582
582
  "div",
583
583
  { style: { display: "flex", flexDirection: "column", gap: "8px" } },
584
584
  e("p", { style: styles.note }, String(plan.message ?? "")),
585
- // 没有可做的步骤时(工具链已完整)只留那一句话:不再画"目标/包/下载"与七行"已跳过",
586
- // 否则一张"什么都不用装"的卡片看起来比要装的还长。
585
+ // 没有可做的步骤时(工具链已完整)仅保留该说明:不再画"目标/包/下载"与七行"已跳过",
586
+ // 否则一张"无需安装"的卡片会显得比需要安装的还长。
587
587
  Array.isArray(planSteps) && planSteps.length > 0
588
588
  ? e(
589
589
  "p",
@@ -604,7 +604,7 @@ window.__ModuleLoader__.load({
604
604
  ? e(
605
605
  "div",
606
606
  { style: { ...styles.row, gap: "10px" } },
607
- e("p", { style: styles.note }, "确认在这台机器上真装?会下载安装包、解压到目标目录,需要几分钟。"),
607
+ e("p", { style: styles.note }, "在本机执行安装:系统将下载安装包并解压至目标目录,该过程需要数分钟。"),
608
608
  e("button", { type: "button", style: styles.buttonDanger, disabled: starting, onClick: () => void startInstall() }, starting ? "启动中…" : "确认安装"),
609
609
  e("button", { type: "button", style: styles.button, disabled: starting, onClick: () => setConfirmInstall(false) }, "取消"),
610
610
  )
@@ -622,7 +622,7 @@ window.__ModuleLoader__.load({
622
622
  : e(
623
623
  "p",
624
624
  { style: styles.muted },
625
- "安装任务 " + taskId + " · " +
625
+ "安装任务ID: " + taskId + " · " +
626
626
  (installState !== null && typeof installState === "object" ? String(installState.status ?? "running") : "running"),
627
627
  ),
628
628
  installState !== null && typeof installState === "object" && String(installState.message ?? "") !== ""
@@ -642,7 +642,7 @@ window.__ModuleLoader__.load({
642
642
  e(
643
643
  "p",
644
644
  { style: styles.lead },
645
- "这里只负责「这台机器把工具装在哪、缺什么、怎么装」。工程本身的编译 / 烧录 / 调试仍走斜杠命令与工具,面板不碰你的工程。",
645
+ "本面板仅管理本机 STM32 工具链的位置、缺失检测与安装流程。项目编译、烧录、调试请继续使用斜杠命令,面板不会修改用户工程文件。",
646
646
  ),
647
647
  configCard,
648
648
  probeCard,
@@ -652,7 +652,7 @@ window.__ModuleLoader__.load({
652
652
 
653
653
  /* ------------------------------ 插件入口 ------------------------------ */
654
654
 
655
- /** 客户端插件只声明 slots(注册 settings.section 需要它)。 */
655
+ /** 客户端插件只声明 slots(注册 settings.section 需要该声明)。 */
656
656
  const inject = ["slots"];
657
657
 
658
658
  function apply(ctx) {
package/lib/client.js CHANGED
@@ -9,11 +9,11 @@ window.__ModuleLoader__.load({
9
9
  * dsh-stm32 浏览器端设置面板(手写纯 JS,不经 tsc)。
10
10
  *
11
11
  * 为什么文件第一行就是 load({:宿主客户端模块加载器按这个自执行包装取走并执行本文件,
12
- * 注释放在包装外面会被当成"包装前有别的语句",与 dsh-client-ui-* 的产物形状不一致。
12
+ * 注释放在包装外面会被当成"包装前有其他语句",与 dsh-client-ui-* 的产物形状不一致。
13
13
  *
14
14
  * 为什么是纯 JS:本文件由宿主加载器直接执行,不经过插件的 TS 构建链;
15
15
  * 写成 TS/JSX 会多出一份由 tsc 决定产物路径的中间层,而面板的正确产物就是
16
- * client/client.js 原文(scripts/copy-client.mjs 把它原样复制到 lib/client.js)。
16
+ * client/client.js 原文(scripts/copy-client.mjs 将其原样复制到 lib/client.js)。
17
17
  * 所以这里只用手写 React.createElement,且只 require 外壳种子词:
18
18
  * react / react/jsx-runtime / primitives。
19
19
  *
@@ -44,14 +44,14 @@ window.__ModuleLoader__.load({
44
44
  try {
45
45
  return new URL(API_RELATIVE + path, base).toString();
46
46
  } catch {
47
- // 极早的加载时机(document 还没就位):退回根路径,至少不会让面板整个炸掉。
47
+ // 极早的加载时机(document 还没就位):退回根路径,避免面板整体失效。
48
48
  return "/dsh-stm32/api/" + path;
49
49
  }
50
50
  }
51
51
 
52
52
  /**
53
53
  * 调一次面板接口。返回值刻意统一成 { ok, value } / { ok:false, error }:
54
- * 面板上每个操作只要关心"成了没成、为什么没成",不用各自解析 HTTP 语义。
54
+ * 面板上每个操作只需关心"是否成功、失败原因",无需各自解析 HTTP 语义。
55
55
  */
56
56
  async function callApi(method, path, body) {
57
57
  const url = apiUrl(path);
@@ -466,8 +466,8 @@ window.__ModuleLoader__.load({
466
466
  e(
467
467
  "div",
468
468
  { style: styles.cardHead },
469
- e("h3", { style: styles.cardTitle }, "装在哪"),
470
- e("p", { style: styles.cardNote }, loadingConfig ? "读取配置中…" : configExists ? "配置文件已存在" : "还没有配置文件(保存时创建)"),
469
+ e("h3", { style: styles.cardTitle }, "工具链路径配置"),
470
+ e("p", { style: styles.cardNote }, loadingConfig ? "读取配置中…" : configExists ? "配置文件已加载" : "暂无配置文件,保存时自动生成"),
471
471
  ),
472
472
  e("p", { style: styles.mono }, configPath === "" ? "(配置路径未知)" : "配置: " + configPath),
473
473
  configDisabled
@@ -485,7 +485,7 @@ window.__ModuleLoader__.load({
485
485
  type: "text",
486
486
  value: msys64,
487
487
  spellCheck: false,
488
- placeholder: "例如 D:/app/msys64(空 = 不指定)",
488
+ placeholder: "示例:C:/msys64,留空表示不指定",
489
489
  onChange: (event) => setMsys64(event.target.value),
490
490
  }),
491
491
  ),
@@ -499,20 +499,20 @@ window.__ModuleLoader__.load({
499
499
  type: "text",
500
500
  value: cubeMxRoot,
501
501
  spellCheck: false,
502
- placeholder: "例如 D:/app/STM32CubeMX(空 = 自动找)",
502
+ placeholder: "示例:C:/STM32CubeMX,留空自动检索",
503
503
  onChange: (event) => setCubeMxRoot(event.target.value),
504
504
  }),
505
505
  ),
506
506
  e(
507
507
  "div",
508
508
  { style: { display: "flex", flexDirection: "column", gap: "4px" } },
509
- e("label", { style: { opacity: 0.8 }, htmlFor: "dsh-stm32-bindirs" }, "额外 bin 目录(每行一个,留空 = 用 MSYS2 推导 / 自动发现)"),
509
+ e("label", { style: { opacity: 0.8 }, htmlFor: "dsh-stm32-bindirs" }, "附加 Bin 目录(每行一条,留空将基于 MSYS2 自动推导)"),
510
510
  e("textarea", {
511
511
  id: "dsh-stm32-bindirs",
512
512
  style: styles.textarea,
513
513
  value: binDirsText,
514
514
  spellCheck: false,
515
- placeholder: "D:/app/msys64/ucrt64/bin",
515
+ placeholder: "C:/msys64/ucrt64/bin",
516
516
  onChange: (event) => setBinDirsText(event.target.value),
517
517
  }),
518
518
  ),
@@ -522,7 +522,7 @@ window.__ModuleLoader__.load({
522
522
  e("button", { type: "button", style: styles.buttonPrimary, disabled: saving, onClick: () => void save() }, saving ? "保存中…" : "保存配置"),
523
523
  saveNote === null ? null : e("p", { style: saveNote.ok ? styles.ok : styles.error }, String(saveNote.text)),
524
524
  ),
525
- e("p", { style: styles.cardNote }, "改完立即生效(插件每次自己读配置文件,不用重开 DSH)。"),
525
+ e("p", { style: styles.cardNote }, "配置修改后即时生效,无需重启 DSH。"),
526
526
  );
527
527
 
528
528
  const tools = probe !== null && typeof probe === "object" && Array.isArray(probe.tools) ? probe.tools : [];
@@ -532,8 +532,8 @@ window.__ModuleLoader__.load({
532
532
  e(
533
533
  "div",
534
534
  { style: styles.cardHead },
535
- e("h3", { style: styles.cardTitle }, "缺什么"),
536
- e("p", { style: styles.cardNote }, "按上面三个框里的值探测;留空就走自动发现。"),
535
+ e("h3", { style: styles.cardTitle }, "工具链探测"),
536
+ e("p", { style: styles.cardNote }, "依据上方配置路径执行探测,路径留空时启用自动检索。"),
537
537
  ),
538
538
  e(
539
539
  "div",
@@ -542,7 +542,7 @@ window.__ModuleLoader__.load({
542
542
  ),
543
543
  probeError === "" ? null : e("p", { style: styles.error }, probeError),
544
544
  probe === null
545
- ? e("p", { style: styles.muted }, "还没探测过。探测会跑一次各工具的版本命令,不会装任何东西。")
545
+ ? e("p", { style: styles.muted }, "尚未执行探测。探测仅读取工具版本信息,不会执行安装操作。")
546
546
  : e(
547
547
  "div",
548
548
  { style: { display: "flex", flexDirection: "column", gap: "8px" } },
@@ -564,15 +564,15 @@ window.__ModuleLoader__.load({
564
564
  e(
565
565
  "div",
566
566
  { style: styles.cardHead },
567
- e("h3", { style: styles.cardTitle }, "装工具链"),
568
- e("p", { style: styles.cardNote }, "先出计划(不下载、不写盘),确认后才真装。"),
567
+ e("h3", { style: styles.cardTitle }, "工具链安装"),
568
+ e("p", { style: styles.cardNote }, "首先生成安装方案(不会下载或写入文件),确认后再执行安装。"),
569
569
  ),
570
570
  e(
571
571
  "div",
572
572
  { style: styles.row },
573
- e("button", { type: "button", style: styles.button, disabled: planning, onClick: () => void runPlan() }, planning ? "算计划中…" : "出安装计划"),
573
+ e("button", { type: "button", style: styles.button, disabled: planning, onClick: () => void runPlan() }, planning ?"生成方案中…" : "生成安装方案"),
574
574
  plan !== null && !confirmInstall && taskId === ""
575
- ? e("button", { type: "button", style: styles.buttonDanger, onClick: () => setConfirmInstall(true) }, "开始安装…")
575
+ ? e("button", { type: "button", style: styles.buttonDanger, onClick: () => setConfirmInstall(true) }, "执行安装")
576
576
  : null,
577
577
  ),
578
578
  planError === "" ? null : e("p", { style: styles.error }, planError),
@@ -582,8 +582,8 @@ window.__ModuleLoader__.load({
582
582
  "div",
583
583
  { style: { display: "flex", flexDirection: "column", gap: "8px" } },
584
584
  e("p", { style: styles.note }, String(plan.message ?? "")),
585
- // 没有可做的步骤时(工具链已完整)只留那一句话:不再画"目标/包/下载"与七行"已跳过",
586
- // 否则一张"什么都不用装"的卡片看起来比要装的还长。
585
+ // 没有可做的步骤时(工具链已完整)仅保留该说明:不再画"目标/包/下载"与七行"已跳过",
586
+ // 否则一张"无需安装"的卡片会显得比需要安装的还长。
587
587
  Array.isArray(planSteps) && planSteps.length > 0
588
588
  ? e(
589
589
  "p",
@@ -604,7 +604,7 @@ window.__ModuleLoader__.load({
604
604
  ? e(
605
605
  "div",
606
606
  { style: { ...styles.row, gap: "10px" } },
607
- e("p", { style: styles.note }, "确认在这台机器上真装?会下载安装包、解压到目标目录,需要几分钟。"),
607
+ e("p", { style: styles.note }, "在本机执行安装:系统将下载安装包并解压至目标目录,该过程需要数分钟。"),
608
608
  e("button", { type: "button", style: styles.buttonDanger, disabled: starting, onClick: () => void startInstall() }, starting ? "启动中…" : "确认安装"),
609
609
  e("button", { type: "button", style: styles.button, disabled: starting, onClick: () => setConfirmInstall(false) }, "取消"),
610
610
  )
@@ -622,7 +622,7 @@ window.__ModuleLoader__.load({
622
622
  : e(
623
623
  "p",
624
624
  { style: styles.muted },
625
- "安装任务 " + taskId + " · " +
625
+ "安装任务ID: " + taskId + " · " +
626
626
  (installState !== null && typeof installState === "object" ? String(installState.status ?? "running") : "running"),
627
627
  ),
628
628
  installState !== null && typeof installState === "object" && String(installState.message ?? "") !== ""
@@ -642,7 +642,7 @@ window.__ModuleLoader__.load({
642
642
  e(
643
643
  "p",
644
644
  { style: styles.lead },
645
- "这里只负责「这台机器把工具装在哪、缺什么、怎么装」。工程本身的编译 / 烧录 / 调试仍走斜杠命令与工具,面板不碰你的工程。",
645
+ "本面板仅管理本机 STM32 工具链的位置、缺失检测与安装流程。项目编译、烧录、调试请继续使用斜杠命令,面板不会修改用户工程文件。",
646
646
  ),
647
647
  configCard,
648
648
  probeCard,
@@ -652,7 +652,7 @@ window.__ModuleLoader__.load({
652
652
 
653
653
  /* ------------------------------ 插件入口 ------------------------------ */
654
654
 
655
- /** 客户端插件只声明 slots(注册 settings.section 需要它)。 */
655
+ /** 客户端插件只声明 slots(注册 settings.section 需要该声明)。 */
656
656
  const inject = ["slots"];
657
657
 
658
658
  function apply(ctx) {
@@ -30,7 +30,7 @@ import { formatFlashReport } from "../tools/flash.js";
30
30
  *
31
31
  * 为什么不能"先按空白 split 再剥引号":`"C:/Program Files/ST/demo proj"` 在第一步就被切成两段,
32
32
  * 之后再怎么剥都拼不回原路径 —— projectDir 只剩半截,用户看到的却是「找不到 CMakeLists.txt」,
33
- * 只会以为工程坏了。所以改成一次扫描:引号内不切词、顺手把引号吃掉。
33
+ * 只会判定为工程故障。因此改为一次扫描:引号内不切词,同时移除引号。
34
34
  * 引号没闭合直接抛错:静默按空白切等于把"用户写错了"伪装成"工程坏了"。
35
35
  *
36
36
  * 引号内不做反斜杠转义:Windows 路径里 `\` 到处都是(C:\Users\...),当转义符只会把路径吃掉;
@@ -163,7 +163,7 @@ function err(text) {
163
163
  *
164
164
  * 为什么命令要单独过:/stm32-build、/stm32-flash、/stm32-debug 不经过工具层,缺 gcc 或 openocd 时
165
165
  * 用户只得到一屏 cmake / spawn 原始报错,与工具入口那句「缺 X,装法是 Y」差得太远;
166
- * 而 /stm32-env 摆在那儿,却没人会先想到它。
166
+ * 而 /stm32-env 虽然存在,却常被忽略。
167
167
  *
168
168
  * 为什么固定 envCheck=warn:命令是"人已经决定要干"的动作,门禁没资格替人拦掉,
169
169
  * 但必须把「缺什么、怎么装」放在输出第一行。门禁自带 60 s 探测缓存,连着敲也不贵。
@@ -219,7 +219,7 @@ function envText(rows, configPath) {
219
219
  lines.push(label + " ✘ 缺 " + missing + (install === undefined ? "" : " —— " + install));
220
220
  }
221
221
  // 缺件也是体检结果,不是命令错误;所以两种结尾都是 success。
222
- lines.push(anyMissing ? "要装:回「装」,我跑 stm32_env_install 出计划(先不下载)" : "都齐了:/stm32-build 就能编译");
222
+ lines.push(anyMissing ? "要装:回复「装」,插件执行 stm32_env_install 生成计划(不下载)" : "依赖齐备:/stm32-build 即可编译");
223
223
  return { kind: "success", text: lines.join("\n") };
224
224
  }
225
225
  /** 注册七条斜杠命令;宿主没组合 commands 服务时直接返回(工具不受影响)。 */
@@ -278,7 +278,7 @@ export function registerCommands(ctx) {
278
278
  lines.push("调试:停在 " + location);
279
279
  lines.push("端口:" + String(session.port) + ",探针由调试会话占着(空闲 " + String(Math.round(session.idleTtlMs / 1000)) + " s 自动关)");
280
280
  lines.push("· 读变量/寄存器:stm32_debug_eval(每次调用续租)");
281
- lines.push("· 想把探针交还给 VS Code:/stm32-stop,或者等我这一轮说完(turn/end 会自动关)");
281
+ lines.push("· 探针交还 VS Code:/stm32-stop,或等本轮输出结束(turn/end 自动关闭)");
282
282
  return withGateWarning(warning, { kind: "success", text: lines.join("\n") });
283
283
  }
284
284
  catch (error) {
@@ -292,7 +292,7 @@ export function registerCommands(ctx) {
292
292
  description: "关掉调试会话、释放探针(之后可以在 VS Code 里按 F5)",
293
293
  handler: async () => {
294
294
  try {
295
- const result = await debugSessions.stop("你敲了 /stm32-stop");
295
+ const result = await debugSessions.stop("收到 /stm32-stop");
296
296
  return { kind: "success", text: result.message };
297
297
  }
298
298
  catch (error) {
package/lib/data/chips.js CHANGED
@@ -1,13 +1,13 @@
1
1
  /**
2
2
  * L1:引脚名合法性 + 由本机 CubeMX db 派生的引脚表。
3
3
  *
4
- * 用户 2026-10-31「内置表删了吧」之后,这里**不再有任何内置芯片/引脚表**(原来的 CHIPS / KNOWN_CHIPS /
4
+ * 用户 2026-10-31 决定删除内置表之后,这里**不再有任何内置芯片/引脚表**(原来的 CHIPS / KNOWN_CHIPS /
5
5
  * findChip 已删)。原因:芯片事实的唯一来源是内置资源 device/f1/chips.json,而那份文件只有 pinCount
6
6
  * (封装上有多少根脚),没有「这个封装有哪几根 GPIO」的清单——拿 pinCount 去猜 PA0-PB15… 等于又造一张表。
7
7
  *
8
8
  * 于是分工变成:
9
9
  * 1. isKnownPin(pin):只校验**引脚名**是不是 STM32 的合法名(P + A..K + 0..15,虚拟引脚 VP_* 恒放行)。
10
- * 它拦的是手误(PA99、PZ9、PA-1),不再假装知道某个封装有没有这根脚。
10
+ * 该函数拦截手误(PA99、PZ9、PA-1),不再假定某个封装是否存在该引脚。
11
11
  * 2. deriveChipPinTable():引脚**存在性**只认本机 CubeMX 的 db/mcu XML
12
12
  * (<Pin Name="PA1" Position="3"/>,Position>0 才是真实封装引脚)。本机没装 CubeMX / 没有这个 XML 时
13
13
  * kind="unknown",notes 里明说「没校验」,绝不拿猜测冒充实测。
@@ -24,7 +24,7 @@ const MAX_PIN_NUMBER = 15;
24
24
  * 引脚名是否合法(未知/虚拟引脚一律放行)。
25
25
  *
26
26
  * 为什么不再按型号判「有没有这根脚」:那需要「封装 → 引脚清单」的事实,而内置资源只给了 pinCount。
27
- * 真正的引脚存在性请用 deriveChipPinTable(本机 CubeMX db)——它给的是实测清单,不是符号表。
27
+ * 真正的引脚存在性请用 deriveChipPinTable(本机 CubeMX db)——该函数给出的是实测清单,不是符号表。
28
28
  */
29
29
  export function isKnownPin(pin) {
30
30
  const raw = pin.trim().toUpperCase();
@@ -147,7 +147,7 @@ export function deriveChipPinTable(input) {
147
147
  pins: [],
148
148
  notes: [
149
149
  "引脚表:没有本机 CubeMX db(" + why + "),引脚存在性不校验(isKnownPin 只查引脚名是否合法);" +
150
- "插件不内置引脚表(内置资源里也不再有 db 副本),需要逐脚校验就装 CubeMX —— 插件直接读它的 db/mcu",
150
+ "插件不内置引脚表(内置资源里也不再有 db 副本),需要逐脚校验就安装 CubeMX —— 插件直接读取其 db/mcu",
151
151
  ],
152
152
  };
153
153
  }
@@ -6,7 +6,7 @@
6
6
  * - `db/mcu/<Mcu.Name>.xml` 的 `<Frequency>` 就是该型号的 SYSCLK 上限(MHz);
7
7
  * - `db/mcu/IP/RCC-*.xml`(Modes)里 `<RefParameter Name="PLLMUL" Type="list">` 的
8
8
  * `<PossibleValue Value="RCC_PLL_MUL2" Comment="2"/>` 就是倍频枚举,分频同理。
9
- * 抄快照的问题与预设表一样:换族/换 db 版本就失真(F1 的 `S_TIM2_CH1_ETR` 已经栽过一次)。
9
+ * 抄写快照的局限与预设表相同:更换芯片族或 db 版本后即失真(F1 的 `S_TIM2_CH1_ETR` 已出现过一次错误)。
10
10
  *
11
11
  * 早先以为「APB1/APB2/ADC 的频率上限 db 里没有」,实测是错的:`RCC-*_Modes.xml` 里
12
12
  * `<RefParameter Name="APB1Freq_Value" Max="30000000">`、`APB2Freq_Value`、`ADCFreq_Value`、
@@ -50,7 +50,7 @@ function enumOf(text, parameterName) {
50
50
  if (open === null)
51
51
  return [];
52
52
  // 自闭合 = integer 型(PLLM/PLLN 在 F4 上就是 Min=2 Max=63 这种),没有 PossibleValue。
53
- // 不挡住的话正则会把**下一个** RefParameter 的块当成它的 children —— F4 的 PLLM 曾因此拿到 PLLP 的枚举名。
53
+ // 不加阻止时,正则会把**下一个** RefParameter 的块当成当前块的 children —— F4 的 PLLM 曾因此拿到 PLLP 的枚举名。
54
54
  if (open[0].trimEnd().endsWith("/>"))
55
55
  return [];
56
56
  const from = (open.index ?? 0) + open[0].length;
@@ -75,7 +75,7 @@ function enumOf(text, parameterName) {
75
75
  *
76
76
  * 为什么需要:这些名字**不带** Freq_Value 后缀(H5 的 `EPOD_VALUE` 就是 PLL 源频率信号),
77
77
  * 只看名字认不出是派生量。真机证据(2026-11 H5 @250 MHz 往返):计划没碰 `RCC.EPOD_VALUE`,
78
- * CubeMX 保存时把它从 4 MHz 改成 8 MHz(跟随 PLL 源换成 HSE),ioc_verify 却记成 valueChanged
78
+ * CubeMX 保存时把该值从 4 MHz 改成 8 MHz(跟随 PLL 源换成 HSE),ioc_verify 却记成 valueChanged
79
79
  * → benign 翻 false。名字从 db 取而不是手抄,才能覆盖 27 族。
80
80
  */
81
81
  export function readClockTreeDerivedNames(db, clockTree) {
@@ -100,14 +100,14 @@ export function readClockTreeDerivedNames(db, clockTree) {
100
100
  *
101
101
  * 判据(全部来自 db/plugins/clock/<ClockTree>.xml):
102
102
  * 1. 找 refParameter=SYSCLKSource(WL3 叫 ROOTClkSource)的 multiplexor;
103
- * 2. 它的每条 <Input refValue=...> 是一条源(refValue 决定是 hse/hsi/rc64/…);
103
+ * 2. 该多路选择器的每条 <Input refValue=...> 是一条源(refValue 决定是 hse/hsi/rc64/…);
104
104
  * 3. 顺着 from= 往回走,只有 type="devisor" 的元素才算这一路的分频器,走到源(fixedSource/variedSource)为止。
105
105
  * C0 的 HSISYSCLKDivider 就在 HSI → SysClkSource 中间,所以仍能读到;WB0/WL3 走回去第一个就是源,读出来是空。
106
106
  *
107
- * 返回值语义要分清(关系到能不能信它):
108
- * - null = 没读到时钟树(db 里没有该树的 xml、或 xml 里没有 SYSCLK 多路选择器)→ 调用方可以按名字兜底;
109
- * - 空 Map = **读到了**、而且这些源确实没有 SYSCLK 分频器(WB0/WL3 就是这样)→ 调用方必须当真,不能兜底。
110
- * 早先两者都返回空 Map,WB0 因此仍然走按名字猜的兜底、把 CLKSYS 预分频当成 SYSCLK 分频。
107
+ * 返回值语义需区分(关系到结果是否可信):
108
+ * - null = 没读到时钟树(db 里没有该树的 xml、或 xml 里没有 SYSCLK 多路选择器)→ 调用方可以按名字回退;
109
+ * - 空 Map = **读到了**、而且这些源确实没有 SYSCLK 分频器(WB0/WL3 就是这样)→ 调用方必须采信,不能回退。
110
+ * 早先两者都返回空 Map,WB0 因此仍走按名字推测的回退路径,把 CLKSYS 预分频当成 SYSCLK 分频。
111
111
  */
112
112
  export function readClockTreeSysclkDividers(db, clockTree) {
113
113
  if (clockTree === "")
@@ -189,7 +189,7 @@ function divsWithName(text, names) {
189
189
  * SYSCLK 走 PLL 的哪一路输出(PLLP 还是 PLLR)。
190
190
  *
191
191
  * 从时钟树定义读:db/plugins/clock/<ClockTree>.xml 里 Signal id="PLLCLK" 的 refParameter
192
- * 就是喂给 SYSCLK 多路选择器的那路。实测 L4RS 与 U5 都指向 PLLRCLKFreq_Value,
192
+ * 即传入 SYSCLK 多路选择器的那一路。实测 L4RS 与 U5 都指向 PLLRCLKFreq_Value,
193
193
  * 而 U5 的 PLLP 只有 PLLPoutputFreq_Value(供 SAI/其它外设)——按 PLLP 规划会把
194
194
  * SYSCLK 接到错的分频上。读不到(老 db)返回 null,调用方回退旧启发式。
195
195
  */
@@ -216,8 +216,8 @@ export function readSysclkPllOutput(db, clockTree) {
216
216
  * 判据是 db 里有没有 Cortex 的选择/分频参数(CortexCLockSelectionVirtual / CortexCLockSelection /
217
217
  * Cortex_Div)。有就不能写:那几档(÷1 与 ÷8 都在选项里,.ioc 里的默认值不一定是 CubeMX 保存时
218
218
  * 实际用的那个)—— 实测四次往返都很任性:H5 写 HCLK 被改成 HCLK÷8,U5 写 HCLK÷8 又被改回 HCLK,
219
- * 同一个键两次反着来。这类「CubeMX 自己按树算」的派生量交给它算,我们只写确定等于 HCLK 的那些键,
220
- * verify 里它会归到 derivedRecomputed(不参与 benign)。
219
+ * 同一个键两次往返方向相反。这类「CubeMX 按树自行计算」的派生量交由 CubeMX 计算,本插件只写确定等于 HCLK 的那些键,
220
+ * verify 中该键归到 derivedRecomputed(不参与 benign)。
221
221
  */
222
222
  function cortexFollowsHclk(text) {
223
223
  return !/\bName="(?:CortexCLockSelectionVirtual|CortexCLockSelection|Cortex_Div)"/u.test(text);
@@ -250,7 +250,7 @@ function numAttr(attrs, key) {
250
250
  * 同名参数在 Modes xml 里常常有多个**变体**,各自带 `<Condition Expression="scale1">`
251
251
  * (G0/U0 的 ADC 35000000/16000000/80000000、G4 的 APB1 150M/170M 都是这种)。
252
252
  * 这里取「最小的 Min + 最大的 Max」:CubeMX 允许多少就给多少,规划出来的档位不会因为
253
- * 取错变体而被无故拒绝;真正的兜底还有后面的 SYSCLK 上限与 CubeMX 自己的校验。
253
+ * 取错变体而被无故拒绝;最终仍受后面的 SYSCLK 上限与 CubeMX 自身校验约束。
254
254
  * 名字按顺序试,先读出 Max 的优先(APB1Freq_Value 优先于单 APB 族的 APBFreq_Value)。
255
255
  */
256
256
  function limitOf(text, names) {
@@ -466,7 +466,7 @@ export function readClockDbFacts(db, facts) {
466
466
  : "内部 RC:" + (id === "hsi" ? "" : "二分频后") + "频率以 .ioc 的 RCC.HSI_VALUE 为准(db 不写各族 HSI 频率)",
467
467
  });
468
468
  }
469
- // F0/L0 这类族只有 RCC_PLLSOURCE_HSI 一档,硬件上它就是 HSI/2 进 PLL(不是 HSI 直连):
469
+ // F0/L0 这类族只有 RCC_PLLSOURCE_HSI 一档,硬件上该源以 HSI/2 进入 PLL(不是 HSI 直连):
470
470
  // 少了这一步,规划会把 HSI 8 MHz 当 8 MHz 源算,CubeMX 回写时按 /2 重算 → 频率对不上(F0 实测 48→24 MHz)。
471
471
  if (sources.some((source) => source.id === "hsi") && !sources.some((source) => source.id === "hsi-div2")) {
472
472
  for (const source of sources) {
@@ -484,7 +484,7 @@ export function readClockDbFacts(db, facts) {
484
484
  const ahbDivs = toDivs(enumOf(text, "AHBCLKDivider"));
485
485
  const apb2Divs = toDivs(enumOf(text, "APB2CLKDivider"));
486
486
  const adcDivs = toDivs(enumOf(text, "ADCPresc"));
487
- // db 里某个 RefParameter 的 DefaultValue(Hz):HSE_VALUE/PLL64_VALUE 这类「源标称频率」用它当缺省。
487
+ // db 里某个 RefParameter 的 DefaultValue(Hz):HSE_VALUE/PLL64_VALUE 这类「源标称频率」以此作为缺省。
488
488
  const defaultOf = (name) => {
489
489
  for (const block of refParamBlocks(text)) {
490
490
  if (attrOf(block.attrs, "Name") !== name)
@@ -496,7 +496,7 @@ export function readClockDbFacts(db, facts) {
496
496
  return null;
497
497
  };
498
498
  // direct 模型:SYSCLK 直接取源,没有 PLL。能当源的只有 SYSCLKSource 里的 HSE/HSI
499
- // (LSE/LSI 是 32 kHz 级,规划到 MHz 目标用不上,也不该被当成「凑不到就选最近的」兜底)。
499
+ // (LSE/LSI 是 32 kHz 级,规划到 MHz 目标用不上,也不该作为「无法命中就选最近档」的回退)。
500
500
  // 无线族(WB0/WL3)不叫 SYSCLKSource:WL3 是 ROOTClkSource;WL3 的 HSE 直连是 DIRECT_HSE,
501
501
  // 内部 64 MHz RC 是 RC64MPLL(频率取 db 的 PLL64_VALUE,不读 .ioc)。
502
502
  const directSourceEnum = enumAlias(text, ["SYSCLKSource", "ROOTClkSource"]);
@@ -516,7 +516,7 @@ export function readClockDbFacts(db, facts) {
516
516
  iocValue: entry.value,
517
517
  // 真值从 .ioc 的 RCC.HSE_VALUE / RCC.HSI_VALUE 读;这里给 db 的 DefaultValue 当缺省。
518
518
  defaultHz: id === "hse" ? hseDefaultHz : id === "hsi" ? hsiDefaultHz : rc64Hz,
519
- // RC64MPLL 是固定频率源,.ioc 没有它的频率键(PLL64_VALUE 是派生值,写它等于跟自己较劲)。
519
+ // RC64MPLL 是固定频率源,.ioc 没有该源的频率键(PLL64_VALUE 是派生值,写入该键与自身计算冲突)。
520
520
  ...(id === "rc64" ? {} : { hzKey: id === "hse" ? "RCC.HSE_VALUE" : "RCC.HSI_VALUE" }),
521
521
  selectable: true,
522
522
  note: id === "hse"
@@ -528,7 +528,7 @@ export function readClockDbFacts(db, facts) {
528
528
  }
529
529
  // 源分频:哪一路有分频器、键叫什么,全从时钟树走(readClockTreeSysclkDividers)。
530
530
  // 走不出来(db 没有该树的 xml)才回落到按名字猜的老路——WB0/WL3 的 SYSCLK32/64Divider
531
- // 是 CLKSYS 预分频不是 SYSCLK 分频,名字猜法在它们身上是错的,所以只能当兜底。
531
+ // 是 CLKSYS 预分频而非 SYSCLK 分频,按名字推测在无线族上不成立,因此只能作为回退。
532
532
  const srcDivBySource = {};
533
533
  const treeDividers = readClockTreeSysclkDividers(db, facts.clockTree);
534
534
  for (const [source, names] of treeDividers ?? new Map()) {
@@ -567,11 +567,11 @@ export function readClockDbFacts(db, facts) {
567
567
  derivedNames.push(name);
568
568
  }
569
569
  let model = muls.length > 0 ? "pllmul" : pllM.length > 0 || pllN !== null ? "pllmn" : directSources.length > 0 ? "direct" : "unknown";
570
- // direct 模型只对「SYSCLK 直接取一个固定标称频率的源」成立。两种情况下它看着像 direct、其实是假直连:
570
+ // direct 模型仅对「SYSCLK 直接取一个固定标称频率的源」成立。以下两种情况形似 direct,实为假直连:
571
571
  // · 分相 PLL(H7:DIVM1/DIVN1/DIVP1 + PLL1/2/3 三套 6 参数,SYSCLKSource 里也有 PLLCLK);
572
572
  // · MSI 直连(U3:SYSCLKSource 只有 MSIS/HSI/HSE,MSIS 最高 96 MHz、频率可配,不是固定标称值)。
573
573
  // 两种都归到 unknown 并写清原因:宁可明确拒绝,也不给一个「按 HSI 猜出来」的档位 ——
574
- // 那种计划写进 .ioc 后 CubeMX 会照它算出一个更低的 SYSCLK,verify 还可能因为派生键被重算而看不出错。
574
+ // 此类计划写入 .ioc 后,CubeMX 会据此算出更低的 SYSCLK,verify 还可能因派生键被重算而无法发现该错误。
575
575
  let unknownNote = "";
576
576
  if (model === "direct") {
577
577
  const refNames = [...new Set([...text.matchAll(/<RefParameter[^>]*\bName="([A-Za-z0-9_]+)"/gu)].map((matched) => matched[1]))];
@@ -613,8 +613,8 @@ export function readClockDbFacts(db, facts) {
613
613
  : {
614
614
  apb1Hz: apb1Max,
615
615
  apb2Hz: apb2?.max ?? apb1Max,
616
- // 没有独立 ADC 上限的族(L1 的 ADCFreq_Value 没有 Max)先按 APB2 顶住,
617
- // 反正 adcDivs 为空时 planner 不写 ADCPresc,这条不会生效。
616
+ // 没有独立 ADC 上限的族(L1 的 ADCFreq_Value 没有 Max)先按 APB2 上限处理,
617
+ // adcDivs 为空时 planner 不写 ADCPresc,此条不生效。
618
618
  adcHz: adcLimit?.max ?? apb2?.max ?? apb1Max,
619
619
  };
620
620
  if (busLimits === null) {
@@ -632,7 +632,7 @@ export function readClockDbFacts(db, facts) {
632
632
  ...(vcoIn?.min === null || vcoIn?.min === undefined ? {} : { inMinHz: vcoIn.min }),
633
633
  ...(vcoIn?.max === null || vcoIn?.max === undefined ? {} : { inMaxHz: vcoIn.max }),
634
634
  };
635
- // SYSCLK 源按 db 的 RefParameter 名字决定:有 SYSCLKSourceVirtual 就只能写它(F303),
635
+ // SYSCLK 源按 db 的 RefParameter 名字决定:有 SYSCLKSourceVirtual 时只能写该键(F303),
636
636
  // 无线族(WL3)根本没有 SYSCLKSource,源键叫 ROOTClkSource。
637
637
  const sysclkSourceKey = /\bName="SYSCLKSourceVirtual"/u.test(text)
638
638
  ? "RCC.SYSCLKSourceVirtual"
@@ -668,7 +668,7 @@ export function readClockDbFacts(db, facts) {
668
668
  srcDivSources,
669
669
  srcDivBySource,
670
670
  // 读不到 APB 分频就留空:WB0/WL3 根本没有 APB1CLKDivider,早先这里填 RCC_HCLK_DIV1..16
671
- // 的假枚举,planner 会把它写进 .ioc,CubeMX 当成未知键丢掉(= 计划里的键凭空消失)。
671
+ // 的假枚举,planner 会把这些假枚举写入 .ioc,CubeMX 当成未知键丢弃(= 计划里的键凭空消失)。
672
672
  apbDivs,
673
673
  hasApbDivider: apbDivs.length > 0,
674
674
  ahbDivs,
@@ -726,7 +726,7 @@ export const PLL_VCO_LIMITS = {
726
726
  export function clockFactsFromDb(facts, familyId) {
727
727
  const family = familyId.trim().toUpperCase();
728
728
  // SYSCLK 上限三级回退:MCU xml 的 <Frequency> → db 的 SYSCLKFreq_VALUE Max → APB2 上限。
729
- // 第三级是兜底(G4/U0 的 <Frequency> 读出来是 0,但它们的 SYSCLKFreq_VALUE Max 是有的)。
729
+ // 第三级为回退(G4/U0 的 <Frequency> 读出为 0,但 SYSCLKFreq_VALUE Max 存在)。
730
730
  const sysclkMaxNow = facts.sysclkMaxHz > 0 ? facts.sysclkMaxHz : facts.sysclkMaxDbHz;
731
731
  const limits = BUS_LIMITS[family] ??
732
732
  facts.busLimits ??
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * STM32F1 时钟树事实表(只放"书上写的数字",不放算法)。
3
3
  *
4
- * 为什么单独一张表:F1 的时钟上限、PLL 可选倍频、外设挂在哪条总线,这些是芯片事实,
4
+ * 单独成表的原因:F1 的时钟上限、PLL 可选倍频、外设所属总线,均属芯片事实,
5
5
  * 而"给定目标频率怎么挑组合"是策略(src/engine/clock-plan.ts)。事实和策略分开,
6
6
  * 以后扩 F0/F4 只换这张表,算法不用动。
7
7
  *
@@ -15,7 +15,7 @@ export const F1_PLL_SOURCES = [
15
15
  iocValue: "RCC_PLLSOURCE_HSE",
16
16
  defaultHz: 8_000_000,
17
17
  selectable: true,
18
- note: "外部晶振(板上 8 MHz,值料号 HSE 范围 4–16 MHz)。精度由晶振决定,通常 ≤50 ppm,UART 波特率靠它就够准。",
18
+ note: "外部晶振(开发板 8 MHz,值料号 HSE 范围 4–16 MHz)。精度由晶振决定,通常 ≤50 ppm,UART 波特率精度由晶振保证。",
19
19
  },
20
20
  {
21
21
  id: "hsi-div2",