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
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  [![license](https://img.shields.io/github/license/JingYu-er/dsh-stm32)](LICENSE)
11
11
  [![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-4a6cf7)](#已知限制)
12
12
  [![MCU](https://img.shields.io/badge/MCU-STM32%20family-4a6cf7)](#已知限制)
13
- [![version](https://img.shields.io/badge/version-0.1.5-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
13
+ [![version](https://img.shields.io/badge/version-0.1.7-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
14
14
 
15
15
  这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 25 个工具、7 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
16
16
 
@@ -56,7 +56,7 @@ dsh plugin --profile desktop add dsh-stm32
56
56
 
57
57
  `dsh plugin` 做的事就是在 profile 目录里跑 `pnpm add`。装完它会把 `dsh-stm32` 写进该 profile 的 `dsh.profile.bundles`,重启 dsh 即生效(把 `desktop` 换成 `web` 就装到 web profile)。
58
58
 
59
- 装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.5`;重启后 `/stm32-doctor` 有输出。
59
+ 装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.7`;重启后 `/stm32-doctor` 有输出。
60
60
 
61
61
  > **芯片事实随插件内置**:设备事实(型号 → 启动文件 / 设备宏 / Flash·RAM 容量)来自包内的 `assets/device/<族>/chips.json`(core 75 个文件、full 105 个文件:芯片表 + 内存布局 + `.ioc` 模板 + 链接脚本 + SVD),装好即可离线使用,不需要联网拉资源包。`stm32_assets verify` 可校验完整性;缺文件通常意味着安装不完整。
62
62
 
package/README_EN.md CHANGED
@@ -8,7 +8,7 @@
8
8
  [![license](https://img.shields.io/github/license/JingYu-er/dsh-stm32)](LICENSE)
9
9
  [![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-4a6cf7)](#known-limitations)
10
10
  [![MCU](https://img.shields.io/badge/MCU-STM32%20family-4a6cf7)](#known-limitations)
11
- [![version](https://img.shields.io/badge/version-0.1.5-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
11
+ [![version](https://img.shields.io/badge/version-0.1.7-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
12
12
 
13
13
  A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers 25 tools, 7 slash commands and 1 SKILL shipped with the plugin, so the model can probe the toolchain, scaffold a CubeMX CMake project, edit the `.ioc`, run CubeMX, build, flash and debug on its own, then read the state back out of the registers — hardware programming that actually stays inside DSH.
14
14
 
@@ -55,7 +55,7 @@ dsh plugin --profile desktop add dsh-stm32
55
55
 
56
56
  All `dsh plugin` does is run `pnpm add` inside the profile directory. On success it also appends `dsh-stm32` to that profile's `dsh.profile.bundles`, so a restart of dsh is all that is left (use `web` instead of `desktop` to target the web profile).
57
57
 
58
- Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.5`); after a restart `/stm32-doctor` should respond.
58
+ Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.7`); after a restart `/stm32-doctor` should respond.
59
59
 
60
60
  > **Chip facts ship with the plugin**: device facts (part → startup file / device define / Flash·RAM size) come from `assets/device/<family>/chips.json` inside the package (75 files for `core`, 105 for `full`: chip tables + memory layout + `.ioc` templates + linker scripts + SVD). Everything works offline once installed — no asset-pack download. Run `stm32_assets verify` to check integrity; missing files usually mean an incomplete install.
61
61
 
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) {
@@ -819,9 +819,41 @@ const fake = {
819
819
  | `src/engine/` | 65 个 `.ts` / 26,961 行 |
820
820
  | `src/data/` | 18 个 `.ts` / 7,785 行 |
821
821
  | 单测 | 60 个套件 / 947 pass / 0 fail(`node test/run-units.mjs`) |
822
+ | TypeScript | 110 个文件、42,261 行(`src/`,不含 client) |
823
+ | `src/tools/` | 24 个文件 / 25 个注册工具 / 7,583 行 |
824
+ | `src/engine/` | 65 个 `.ts` / 26,358 行 |
825
+ | `src/data/` | 17 个 `.ts` / 7,625 行 |
826
+ | 单测 | 61 个套件 / 923 pass / 0 fail(`node test/run-units.mjs`,本机实测) |
822
827
 
823
828
  第 1–11 章的目录表与模块计数保留 D 阶段原样(45 个 engine 模块、23 个 tools 文件),读旧章节时以本节为准。
824
829
 
830
+ ## 14. 0.1.6 增补:宿主 schema 子集与 `pins` / `parameters` 数组化
831
+
832
+ > 接续 §13,同属 0.1.6。这一节不改业务行为,只让 25 个工具的 schema 落进 DSH 0.2.2-rc.1 允许的子集。
833
+
834
+ ### 14.1 先读哪里
835
+
836
+ - `src/types.ts` 的 `JsonSchema`:现在就是宿主子集本身——`type` / `oneOf` / `properties` / `required` / `additionalProperties`(仅 boolean)/ `items` / `enum` / `const` + 注解 `description` / `title` / `default` / `examples`。`minimum` / `maximum` 已删除,看到需要范围时去 `description` 和执行期校验里找。
837
+ - `src/tools/ioc-plan.ts` 的 `parameters`:`peripherals[].pins` / `parameters` 是 `type:"array"` + `items:{key,value}`,`pllMul` 是 `integer` + `enum[2..16]`。
838
+ - `src/engine/ioc-plan.ts` 的 `KeyValuePair` 与 `keyValueMap()`:数组 → `Map` 的唯一入口,空 key / 重复 key 在这里记 `errors`。
839
+ - `src/engine/serial.ts` 的 `SERIAL_SETTINGS_PROPERTIES`:参数 schema 与输出 `settings` schema 复用同一片段,范围只在 `description` 里;真正的越界判定在 `src/data/serial-config.ts` 的 `normalizeSerialSettings`。
840
+ - `test/schema-subset-units.test.mjs`:镜像校验器 + 从 `app.asar` 抽真校验器做真值对齐。改任何工具的 schema 后先跑它。
841
+
842
+ ### 14.2 三条不变量
843
+
844
+ 1. 任何 schema 节点只出现子集关键字;`additionalProperties` 只能是 boolean,`items` 只在数组上,`properties`/`required` 只在对象上。
845
+ 2. 数值范围**不进 schema**:写 `description`,并在执行期校验(`keep`:非法即 `ok=false` 且不动文件;串口:`normalizeSerialSettings` 记 errors 并保持默认值)。
846
+ 3. 「任意键 → 值」的映射不允许再写成 `additionalProperties: {…}`;要么换成 `[{key,value}]` 数组,要么用 `additionalProperties: true` 兜底。
847
+
848
+ ### 14.3 计数口径(0.1.6 起)
849
+
850
+ | 项 | 当前值 |
851
+ | --- | --- |
852
+ | 注册工具 | 25 个(25/25 schema 合规) |
853
+ | 单测 | 61 个套件 / 923 pass / 0 fail |
854
+
855
+ 本机同基线实测为 921,加 2 条新用例后 923;§13.5 表里原有的 937 是另一台机器的发布记录。
856
+
825
857
  ---
826
858
 
827
859
  读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
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
  }