dsh-stm32 0.1.0 → 0.1.2
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.
- package/README.md +127 -29
- package/README_EN.md +125 -29
- package/client/client.js +682 -0
- package/docs/development-notes.md +1385 -5
- package/docs/logic-audit.md +607 -0
- package/docs/reading-guide.md +738 -0
- package/lib/client.js +682 -0
- package/lib/commands/register.js +214 -12
- package/lib/data/chips.js +134 -4
- package/lib/data/clock-f1.js +158 -0
- package/lib/data/cmsis-sources.js +316 -0
- package/lib/data/f1-ram.generated.js +34 -0
- package/lib/data/firmware-packages.js +352 -0
- package/lib/data/install-guides.js +190 -0
- package/lib/data/search-roots.js +135 -15
- package/lib/data/stm32f1.js +186 -0
- package/lib/data/toolchain-config.js +310 -0
- package/lib/engine/build.js +121 -16
- package/lib/engine/cache.js +336 -0
- package/lib/engine/clock-plan.js +608 -0
- package/lib/engine/cmake-sources.js +428 -0
- package/lib/engine/code-patch.js +18 -6
- package/lib/engine/debug-session.js +163 -4
- package/lib/engine/debug.js +84 -19
- package/lib/engine/doctor.js +395 -4
- package/lib/engine/fetch.js +287 -0
- package/lib/engine/firmware-install.js +668 -0
- package/lib/engine/flash.js +145 -15
- package/lib/engine/fs-longpath.js +107 -0
- package/lib/engine/generate-cache.js +118 -0
- package/lib/engine/generate-script.js +30 -8
- package/lib/engine/generate.js +296 -14
- package/lib/engine/hal-chip.js +230 -0
- package/lib/engine/ioc-plan.js +47 -8
- package/lib/engine/msys2-install.js +1870 -0
- package/lib/engine/probe.js +57 -6
- package/lib/engine/project-export.js +129 -0
- package/lib/engine/register-clock.js +132 -0
- package/lib/engine/register-linker.js +129 -0
- package/lib/engine/register-template.js +449 -0
- package/lib/engine/regs.js +18 -4
- package/lib/engine/route-plan.js +553 -0
- package/lib/engine/scaffold.js +303 -72
- package/lib/engine/subprocess-runner.js +2 -0
- package/lib/engine/tar.js +250 -0
- package/lib/engine/text-file.js +150 -0
- package/lib/engine/thirdparty.js +243 -0
- package/lib/engine/tool-env.js +51 -0
- package/lib/engine/toolchain-gate.js +386 -0
- package/lib/engine/vscode-config.js +99 -0
- package/lib/engine/web-api.js +375 -0
- package/lib/engine/web-routes.js +100 -0
- package/lib/engine/xcube-catalog.js +102 -0
- package/lib/engine/xcube.js +254 -0
- package/lib/engine/zip.js +142 -0
- package/lib/index.js +44 -2
- package/lib/skill/stm32-workflow.js +3 -3
- package/lib/tools/build.js +55 -3
- package/lib/tools/cache.js +250 -0
- package/lib/tools/code-patch.js +29 -2
- package/lib/tools/debug-session.js +56 -14
- package/lib/tools/debug.js +43 -2
- package/lib/tools/doctor.js +16 -3
- package/lib/tools/env-install.js +472 -0
- package/lib/tools/env-probe.js +6 -2
- package/lib/tools/firmware-install.js +255 -0
- package/lib/tools/flash.js +41 -2
- package/lib/tools/generate.js +96 -10
- package/lib/tools/ioc-apply.js +27 -11
- package/lib/tools/ioc-inspect.js +4 -2
- package/lib/tools/ioc-plan.js +209 -11
- package/lib/tools/project-create.js +229 -21
- package/lib/tools/project-dir.js +95 -0
- package/lib/tools/project-export.js +100 -0
- package/lib/tools/regs.js +82 -7
- package/lib/tools/route-plan.js +467 -0
- package/package.json +11 -4
- package/templates/register/CMakeLists.txt +52 -0
- package/templates/register/Core/Src/main.c +72 -0
- package/templates/scaffold/openocd.cfg +8 -0
- package/templates/scaffold/vscode/launch.json +8 -6
- package/templates/scaffold/vscode/settings.json +5 -11
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
# 开发笔记(原 README)
|
|
2
2
|
|
|
3
|
-
> 这是 0.1.0 发布前的开发记录:里程碑、宿主契约踩坑、
|
|
3
|
+
> 这是 0.1.0 发布前的开发记录:里程碑、宿主契约踩坑、19 个工具的实现细节、A1–A13 验收与宿主侧复验。
|
|
4
4
|
> 面向使用者的说明已移到仓库根目录的 [README.md](../README.md)。
|
|
5
5
|
# dsh-stm32
|
|
6
6
|
|
|
7
|
-
DSH 插件(宿主侧,无 UI):把
|
|
7
|
+
DSH 插件(宿主侧,无 UI):把 STM32F1 全系(F100/101/102/103/105/107;0.1.x 时只有 STM32F103C8T6 一块板)的 **环境探测 → .ioc 事务(含时钟)→ 生成工程 → 编译 → 烧录 → 调试** 变成一组可被模型调用的工具。
|
|
8
|
+
|
|
9
|
+
> **2026-10-30 更新**:F1 全系已支持,HAL 与寄存器两条路线都吃任意 F1 型号,时钟配置已并入 `stm32_ioc_plan`。本文件正文里凡是「只支持 / 只覆盖 C8T6」的句子都是当时的历史记录(按时间记账的要求保留原文),最新口径见 §28。
|
|
8
10
|
|
|
9
11
|
规格书:[`docs/dsh-stm32-plugin-规格.md`](docs/dsh-stm32-plugin-规格.md)(v0.2)。
|
|
10
12
|
|
|
@@ -27,7 +29,7 @@ git clone git@github.com:JingYu-er/dsh-stm32.git # 或 https://github.com
|
|
|
27
29
|
cd dsh-stm32
|
|
28
30
|
npm install --no-audit --no-fund # 只装 typescript
|
|
29
31
|
npm run build # tsc -> lib/
|
|
30
|
-
npm test # 可选:
|
|
32
|
+
npm test # 可选:418 个离线用例(29 个套件)
|
|
31
33
|
```
|
|
32
34
|
|
|
33
35
|
然后把 `lib/` 用 `link:` 挂进 dsh 的 profile 并重启 dsh(见下一节)。宿主要求:
|
|
@@ -40,7 +42,7 @@ npm test # 可选:80 个离线用
|
|
|
40
42
|
| STM32CubeMX | `stm32_generate`、首次建工程 | 生成类工具不可用,其余照常 |
|
|
41
43
|
| STM32Cube 固件包 F1(随 CubeMX 安装) | `stm32_project_create` 抄 Drivers | 建骨架报「找不到固件包」 |
|
|
42
44
|
|
|
43
|
-
默认路径在 [`src/data/search-roots.ts`](src/data/search-roots.ts)(msys64 优先),可用 `STM32_BIN_DIRS` / `STM32_CUBEMX_ROOT`
|
|
45
|
+
默认路径在 [`src/data/search-roots.ts`](src/data/search-roots.ts)(msys64 优先),可用 `STM32_BIN_DIRS` / `STM32_CUBEMX_ROOT` 覆盖。型号覆盖 **STM32F1 全系**(F100/101/102/103/105/107,2026-10-30 起;本机验证板仍是 C8T6):启动文件 / 设备宏 / 链接脚本由 [`src/data/stm32f1.ts`](src/data/stm32f1.ts) + [`src/engine/hal-chip.ts`](src/engine/hal-chip.ts) 派生,引脚表内置一份、也可由本机 CubeMX `db/mcu/*.xml` 派生(见 §28)。
|
|
44
46
|
## 开发
|
|
45
47
|
|
|
46
48
|
```powershell
|
|
@@ -339,7 +341,7 @@ node test\flash-units.test.mjs # 6 个烧录用例:openocd 命令拼装 /
|
|
|
339
341
|
node test\doctor-regs-units.mjs # 5 个用例:tasklist 解析 / 地址归一化 / regs 的 Tcl 脚本 / openocd 真实日志格式
|
|
340
342
|
node test\ioc-plan-units.test.mjs # 9 个事务用例:plan 不写源文件 / apply 核 SHA / 引脚校验 / rollback
|
|
341
343
|
node test\session-units.test.mjs # 8 个会话用例:租约、续租、超时自动关、重复 start、无会话时 eval
|
|
342
|
-
node test\schema-guard.mjs #
|
|
344
|
+
node test\schema-guard.mjs # 17 个工具的输出契约守卫(未声明键 / null / 类型),离线复刻宿主校验
|
|
343
345
|
node test\e2e-generate.mjs D:\tmp\copy-of-demo # 真调 CubeMX(2–4 分钟),在副本上验证落位与 USER CODE 保活
|
|
344
346
|
node test\e2e-build.mjs # 真编译 demo(clean,约 1 分钟)
|
|
345
347
|
node test\e2e-flash.mjs # 真烧录 demo(会写板子)
|
|
@@ -733,4 +735,1382 @@ recommendations = 「必需组件齐全:可以编译、可以只烧录、可
|
|
|
733
735
|
新增一条“resolveExecutable 一律抛错”的全缺分支,断言 `missingRequired` 五项、能力全 false、建议里出现
|
|
734
736
|
`pacman.exe -S` 与「需要我帮你装吗」。套件 11 个,用例 89 → **90 pass / 0 fail**。
|
|
735
737
|
|
|
738
|
+
## generate 为什么慢:把它测成一条时间线,然后缓存 + 按需停放第三方包索引
|
|
739
|
+
|
|
740
|
+
用户的诉求(原话):「a直接执行,b如果不使用x-cube扩展包就不加载thirdparties/pdsc,使用的时候再加载」——
|
|
741
|
+
(a) 生成没变化就别重跑,(b) 只在真的用到 X-CUBE 扩展包时才让 CubeMX 去挂那套 PDSC 索引。
|
|
742
|
+
|
|
743
|
+
### 1. 先量化:一次生成到底花在哪
|
|
744
|
+
|
|
745
|
+
同一工程(`_timing_m7/blink`,F103C8T6 + HSE 8 MHz + 1 GPIO)连跑四次完整生成,
|
|
746
|
+
墙钟 **216.8 → 170.6 → 155.6 → 130.3 s**(第一次含冷启动与 Windows 文件缓存预热)。
|
|
747
|
+
只把 JVM 拉起来、等 `Code succesfully generated` 之外什么都不干,约 **26 s**——所以"启动 26 s + 剩下全是配置解析"。
|
|
748
|
+
|
|
749
|
+
从 CubeMX 自己的 `*.log` 时间戳拆出来(单位 s,相对进程启动):
|
|
750
|
+
|
|
751
|
+
| 时间窗 | 阶段 | 说明 |
|
|
752
|
+
| --- | --- | --- |
|
|
753
|
+
| 0–12 | JVM 启动 + 18 个 GUI 插件 | 无头模式也照装不误 |
|
|
754
|
+
| 13–16 | 扫 60+ 个 `*.IP` jar | 枚举可用 IP |
|
|
755
|
+
| 16–28 | 扫 `thirdparties/pdsc` 下 **159 个 PDSC** | 就是用户说的那套扩展包索引 |
|
|
756
|
+
| 21–31 | 联网:HomeAdPanel、URL 文件、md5 清单 | 断网时会等超时,更慢 |
|
|
757
|
+
| 32 | UserAuth + JxBrowser 初始化 | 无头也初始化 |
|
|
758
|
+
| 34.8–90.8 | `LoadConfig` | **56 s**,一次性解析 MxCube 的 XML 配置 |
|
|
759
|
+
| 91.6–121.5 | change project 后**再次**枚举 | **≈30 s**,同一批 IP/PDSC 被扫第二遍 |
|
|
760
|
+
| 121.5–160.3 | 真正生成 6 个文件 | **≈39 s** |
|
|
761
|
+
| 160–170 | 退出 | 关 JxBrowser、刷日志 |
|
|
762
|
+
|
|
763
|
+
两个结论直接决定了改法:
|
|
764
|
+
|
|
765
|
+
1. **pdsc 那 159 个文件被扫了两遍**(16–28 s、91.6–121.5 s 里各一次)。把 `pdsc` 临时改名停放后
|
|
766
|
+
整跑降到 **130.3 s**,即省 **≈25 s**。停放不影响产物:同一工程在"停放"与"已还原"两种状态下生成的
|
|
767
|
+
6 个文件整树 sha256 都是 `a78a451dff0ab876d4abf09cd4c8e86791d648f6e509901f31219e379b8f5d99`。
|
|
768
|
+
2. **剩下的 100+ s 全在重复干同一件事**。工程没变就没有理由再跑一遍——这就是 (a)。
|
|
769
|
+
|
|
770
|
+
顺手证伪了一个想法:**不能用 mtime 判断是否需要重新生成**。CubeMX 对内容相同的文件并不重写,
|
|
771
|
+
只打一行 `oldGeneratedFile`,mtime 不动;反过来一次异常慢跑(508 s)里文件也没更新。
|
|
772
|
+
要判断"变了没有"只能比内容 hash。
|
|
773
|
+
|
|
774
|
+
### 2. (a) 缓存跳过:`src/engine/generate-cache.ts`
|
|
775
|
+
|
|
776
|
+
缓存文件 `.dsh-stm32/generate-cache.json`(`CACHE_VERSION=1`),一条 entry = 键 + 每个产物的 sha256。
|
|
777
|
+
|
|
778
|
+
缓存键 = `.ioc` 正文 sha256 + **CubeMX 指纹** + 布局版本:
|
|
779
|
+
|
|
780
|
+
- CubeMX 指纹取 `STM32CubeMX.exe` 旁 `jre` 的 `size:mtime`(`cubeMxStamp`)——
|
|
781
|
+
jar 里没有稳定可解析的版本号入口,升级/换装时 size 与 mtime 必有一个变。
|
|
782
|
+
- 布局版本是落位规则的常量(`layout`),改落位逻辑就自动失效。
|
|
783
|
+
|
|
784
|
+
命中判定 `cacheHit()` 做三重校验,任何一环不满足都退回真跑,并把原因通过 progress 打出来:
|
|
785
|
+
|
|
786
|
+
| 校验 | 不满足时的 reason |
|
|
787
|
+
| --- | --- |
|
|
788
|
+
| 键一致 | `.ioc 内容、CubeMX 版本或布局变过(缓存键不一致)` |
|
|
789
|
+
| 产物都还在 | `缓存里的产物不见了:<target>` |
|
|
790
|
+
| 每个产物 hash 与缓存一致 | `产物与缓存不一致(被改过):<target>` |
|
|
791
|
+
|
|
792
|
+
命中即直接返回 ok 报告:`skipped: true`、`durationMs ≈ 0`、
|
|
793
|
+
`successLine = "(跳过 CubeMX:复用上次生成结果)"`、`files` 全是 `unchanged-cached`,
|
|
794
|
+
notes 提示逃生口(`skipIfUnchanged=false`,或删掉缓存文件)。
|
|
795
|
+
只有确认要真跑时才 `acquireLock`(不白占探针/锁),成功后才写缓存,写缓存失败只加一条 note、不影响生成结果。
|
|
796
|
+
|
|
797
|
+
### 3. (b) pdsc 按需停放:`src/engine/thirdparty.ts`
|
|
798
|
+
|
|
799
|
+
`needsThirdpartyPacks(iocText)` 判断这份 `.ioc` 是否真的用扩展包:
|
|
800
|
+
|
|
801
|
+
| 条件 | 判定 |
|
|
802
|
+
| --- | --- |
|
|
803
|
+
| `Mcu.ThirdPartyNb > 0` | 需要 |
|
|
804
|
+
| `Mcu.ThirdPartyNb < 0` | 当 0 处理 |
|
|
805
|
+
| **`Mcu.ThirdPartyNb` 键缺失** | 保守判"需要"(reason 写明"保守保留") |
|
|
806
|
+
| 正文出现 `X-CUBE` / `I-CUBE` / `STM32CubeExpansion` / `FP-SNS` / `FP-ATR` / `FP-AI` / `FP-LOOP` / `*ThirdParty*=` | 需要 |
|
|
807
|
+
| `Mcu.ThirdPartyNb = 0` 且无上述标记 | 不需要 → 停放 |
|
|
808
|
+
|
|
809
|
+
> 注:这张表是 M7 当时的判定。M8 之后「正文出现标记」这一行已被**包目录实名匹配**取代
|
|
810
|
+
> (`Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` 直接对快照),见下文
|
|
811
|
+
> 「X-CUBE 判定从「关键词猜」改成「实名查目录」」。
|
|
812
|
+
|
|
813
|
+
不需要时把 `~/.stm32cubemx/thirdparties/pdsc` 改名成 `pdsc.dsh-parked`(同盘 rename,瞬时),
|
|
814
|
+
`runStreaming` 的 `finally` 里无论成功失败都 `restore()`。
|
|
815
|
+
|
|
816
|
+
还原这里有个坑:**CubeMX 运行时发现没有 pdsc 目录会自己建一个空的**。所以 `restore()` 不能直接
|
|
817
|
+
rename 回去,要先 `rmdir` 那个空目录;如果它非空(真被写了东西),就两份都保留并给备注
|
|
818
|
+
「CubeMX 运行中重新生成了 …(非空),原索引仍在 …,请手动合并或删除其一」,绝不静默丢数据。
|
|
819
|
+
|
|
820
|
+
用户家目录用 `cubeMxUserHome(env)` 推:`STM32CUBEMX_HOME` 优先,否则 `USERPROFILE`/`HOME` + `/.stm32cubemx`
|
|
821
|
+
(统一转成 `/`);都拿不到就跳过停放、只记 detail。
|
|
822
|
+
`thirdpartyPacks: "keep"` 可强制保留索引(例如正在 CubeMX GUI 里手工选扩展包)。
|
|
823
|
+
|
|
824
|
+
### 4. 真机验证(`_gen_probe/verify-cache.mjs`,直接 import 构建产物 `lib/engine/generate.js`)
|
|
825
|
+
|
|
826
|
+
| | run1(真跑) | run2(命中缓存) |
|
|
827
|
+
| --- | --- | --- |
|
|
828
|
+
| 墙钟 | **175,120 ms** | **688 ms**(自报 11 ms) |
|
|
829
|
+
| `skipped` | false | **true** |
|
|
830
|
+
| 产物 | 6 个 `overwritten`,保活 USER CODE 标签 11 个(`main.c`:Header/WHILE/3/Error_Handler_Debug/6) | 6 个 `unchanged-cached` |
|
|
831
|
+
| thirdparty | `parked: true` | `未探测(本次跳过 CubeMX)` |
|
|
832
|
+
| pdsc 状态 | 跑前 159 文件 / 跑后 **159 文件,`parked=false`** | 仍 159 / false |
|
|
833
|
+
|
|
834
|
+
即:**首次 3 分钟左右,之后只要 `.ioc`、CubeMX 版本、产物都没动,重新生成 ≈0.7 s。**
|
|
835
|
+
|
|
836
|
+
### 5. 测试计数
|
|
837
|
+
|
|
838
|
+
新增 `test/generate-cache-units.test.mjs`(8 条:sha256/键稳定性/CubeMX 指纹/读写/三重校验各自的失败 reason/entryFromFiles)
|
|
839
|
+
与 `test/thirdparty-units.test.mjs`(11 条:ThirdPartyNb 三分支/键缺失保守/七类标记/家目录推导/停放与还原/非空冲突保留)。
|
|
840
|
+
套件 11 → 13,用例 90 → **109 pass / 0 fail**;两套件插在 `flash-units.test.mjs` 与 `session-units.test.mjs` 之后。
|
|
841
|
+
|
|
842
|
+
|
|
843
|
+
|
|
844
|
+
## X-CUBE 判定从「关键词猜」改成「实名查目录」(M8 补)
|
|
845
|
+
|
|
846
|
+
### 1. 为什么要改
|
|
847
|
+
|
|
848
|
+
原来 `needsThirdpartyPacks` 靠 `X-CUBE` / `I-CUBE` 之类的模糊标记判断要不要加载 `thirdparties/pdsc`,
|
|
849
|
+
两类误判都会咬人:
|
|
850
|
+
|
|
851
|
+
- **真用了包却没写标记** → 索引被停放,生成时报缺包;
|
|
852
|
+
- **工程名里带 `X-CUBE-xxx`**(例如 `ProjectManager.ProjectName=X-CUBE-AI-demo`)→ 白加载 25 s 的索引。
|
|
853
|
+
|
|
854
|
+
用户的原话是「我觉得应该把 x-cube 里的目录列表先提前存到程序中,工程真的要用 X-CUBE 扩展包时检索一下就知道是否要 thirdparties/pdsc 了」——
|
|
855
|
+
即:判定不该猜,该拿**包名**去对**目录**。
|
|
856
|
+
|
|
857
|
+
### 2. 目录快照从哪来
|
|
858
|
+
|
|
859
|
+
本机 `~/.stm32cubemx/thirdparties/pdsc` 下有 **159 个 `.pdsc`**(11.6 MB),文件名形如
|
|
860
|
+
`<vendor>.<pack>[.<version>].pdsc`,例如 `STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0.pdsc`、
|
|
861
|
+
`wolfSSL.I-CUBE-wolfMQTT.pdsc`。去掉版本、大小写不敏感合并后是 **67 个包**(`X-CUBE-DPower` 无版本的那条
|
|
862
|
+
与 `X-CUBE-DPOWER.1.3.0` 合并成一条)。
|
|
863
|
+
|
|
864
|
+
快照由 `scripts/gen-xcube-catalog.mjs` 生成成源码,跟着插件一起发布:
|
|
865
|
+
|
|
866
|
+
```powershell
|
|
867
|
+
# 默认:读 <STM32CUBEMX_HOME 或 %USERPROFILE%/.stm32cubemx>/thirdparties/pdsc,写 src/engine/xcube-catalog.ts
|
|
868
|
+
node scripts/gen-xcube-catalog.mjs
|
|
869
|
+
node scripts/gen-xcube-catalog.mjs D:/some/pdsc src/engine/xcube-catalog.ts # 也可以显式给目录
|
|
870
|
+
```
|
|
871
|
+
|
|
872
|
+
生成物 `src/engine/xcube-catalog.ts` **不要手改**:里面是 `XCUBE_PACK_CATALOG`(67 条 `{vendor,name,versions}`)、
|
|
873
|
+
`XCUBE_CATALOG_FILE_COUNT`、`XCUBE_CATALOG_SOURCE`、`XCUBE_CATALOG_GENERATED_AT`。
|
|
874
|
+
在 CubeMX 里装了新扩展包之后目录会旧,重跑一次脚本即可(旧的目录仍然可用,只是不认识新包)。
|
|
875
|
+
|
|
876
|
+
踩过的坑:版本号必须从结尾**连续**剥纯数字段。只剥最后一段会把 `X-CUBE-ALGOBUILD.1.4.0` 拆成
|
|
877
|
+
`name = X-CUBE-ALGOBUILD.1.4` + `version = 0`,条目数变成 154(错的);修好后 67 条。
|
|
878
|
+
|
|
879
|
+
### 3. `.ioc` 里包的身份
|
|
880
|
+
|
|
881
|
+
真实样本 `8110_foc.ioc`(497 行,见 `.ioc` 里能查到这几行):
|
|
882
|
+
|
|
883
|
+
| 行 | 内容 |
|
|
884
|
+
| --- | --- |
|
|
885
|
+
| 206 | `Mcu.Pin35=VP_STMicroelectronics.X-CUBE-ALGOBUILD_VS_DSPOoLibraryJjLibrary_1.4.0_1.4.0` |
|
|
886
|
+
| 214 | `Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` |
|
|
887
|
+
| 215 | `Mcu.ThirdPartyNb=1` |
|
|
888
|
+
| 436-438 | `STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0.<key>=…` |
|
|
889
|
+
| 482 | `VP_STMicroelectronics.X-CUBE-ALGOBUILD_VS_DSPOoLibraryJjLibrary_1.4.0_1.4.0.Mode=…` |
|
|
890
|
+
|
|
891
|
+
⇒ 包身份就是 `<vendor>.<pack>.<version>`,与 `.pdsc` 文件名同构,所以「目录 ↔ `.ioc`」可以直接对名字。
|
|
892
|
+
本机其它 `.ioc`(`demo`、`_timing_m7`、ODrive 等)只有 `Mcu.ThirdPartyNb=0`,没有任何第三方包。
|
|
893
|
+
|
|
894
|
+
### 4. 判定规则(现行,覆盖第 3 节那张表里的「标记」行)
|
|
895
|
+
|
|
896
|
+
`scanIocPacks()` 先扫出包引用,`needsThirdpartyPacks()` 再按顺序下结论:
|
|
897
|
+
|
|
898
|
+
| 依据 | 结论 |
|
|
899
|
+
| --- | --- |
|
|
900
|
+
| `Mcu.ThirdPartyNb > 0` | 需要,reason 列出包名与本机安装情况 |
|
|
901
|
+
| `.ioc` 引用了目录里的包(`Mcu.ThirdParty<k>` 或任意行里的 `vendor.name`) | 需要;若同时 `Nb=0`,reason 注明「两处对不上,保守保留索引」 |
|
|
902
|
+
| 只命中裸包名(凑不出 vendor,例如 `ProjectManager.ProjectName=X-CUBE-AI-demo`) | 需要(保守),整行进 `markers` 当证据 |
|
|
903
|
+
| `Mcu.ThirdParty<k>` 行解析不了(含空值 `Mcu.ThirdParty0=`) | 需要(保守),进 `malformed` |
|
|
904
|
+
| `Mcu.ThirdPartyNb = 0` 且无以上证据 | **不需要 → 停放** |
|
|
905
|
+
| 没有 `Mcu.ThirdPartyNb` 且无证据 | 需要(保守) |
|
|
906
|
+
|
|
907
|
+
安装状态 `installed`:`exact`(本机就有这个版本)/ `other-version`(本机只有别的版本)/ `missing`(本机没有)/
|
|
908
|
+
`unknown`(调用方没给本机索引,不做存在性判断)。
|
|
909
|
+
|
|
910
|
+
给 `needsThirdpartyPacks(ioc, { pdscDir })` 传本机索引目录时,还会产出 `warnings`:
|
|
911
|
+
|
|
912
|
+
| 情况 | warning |
|
|
913
|
+
| --- | --- |
|
|
914
|
+
| `missing` | `工程要用 …,但本机第三方包索引里没有这个包(先在 CubeMX 的 Manage embedded software packages 里装上它,否则生成会报缺包):<pdscDir>` |
|
|
915
|
+
| `other-version` | `工程要用 …,本机索引里只有 1.5.0(CubeMX 会按可用版本处理,必要时在它里面 Migrate)` |
|
|
916
|
+
| 索引目录读不到 | `读不到本机第三方包索引目录(<pdscDir>),没法判断工程要的包在不在本机` |
|
|
917
|
+
|
|
918
|
+
`src/engine/generate.ts` 把 `warnings` 直接并进报告 `notes`,所以**缺包在生成前就能看到**,不用等 CubeMX 报错。
|
|
919
|
+
|
|
920
|
+
### 5. 测试
|
|
921
|
+
|
|
922
|
+
新增 `test/xcube-units.test.mjs`(14 条):目录快照自检(≥60 条、含 `X-CUBE-ALGOBUILD` 1.4.0、无大小写重复、版本号形如数字点号)、
|
|
923
|
+
两处解析器(生成脚本 `parsePdscFileNames` 与运行时 `parsePdscNames`)对同一 fixture 输出一致、
|
|
924
|
+
`identifyPackId` 四类情形(目录命中带/不带版本、目录外的包通用拆法、认不出来返回 null)、
|
|
925
|
+
用 `8110_foc.ioc` 真实片段跑 `scanIocPacks`(`nb=1`、版本由 `Mcu.ThirdParty0` 补全)、
|
|
926
|
+
`installed` 三态、`markers` 与 `malformed`、`listInstalledPacks`、`summarizePacks`、
|
|
927
|
+
带 `pdscDir` 的三类 warning、纯 HAL 工程(`Nb=0`)不告警。
|
|
928
|
+
|
|
929
|
+
套件 13 → 14,用例 109 → **123 pass / 0 fail**。
|
|
930
|
+
|
|
931
|
+
### 6. 教训
|
|
932
|
+
|
|
933
|
+
- 快照是「这台机器上装了什么」的静态镜像;版本更新靠重跑脚本,不靠写更聪明的正则。宁可旧,也不猜。
|
|
934
|
+
- 生成脚本与运行时各有一份解析器,必须有测试对齐,否则快照和判定会慢慢漂。
|
|
935
|
+
- 空值行也算 malformed:`Mcu.ThirdParty0=` 什么都不写,比写错更常见。
|
|
936
|
+
- 保守的方向只有一个:**判不准就加载索引**。多花 25 s 可以接受,漏包生成错代码不行。
|
|
937
|
+
|
|
938
|
+
### 7. 真机验证(`_gen_probe/verify-thirdparty.mjs`,`skipIfUnchanged: false` 强制真跑)
|
|
939
|
+
|
|
940
|
+
| 项 | 结果 |
|
|
941
|
+
| --- | --- |
|
|
942
|
+
| 工程 | `D:/JingYu/Desktop/c8t6_vscode_test/_timing_m7/blink`(`Mcu.ThirdPartyNb=0`) |
|
|
943
|
+
| 墙钟 / 自报 | 117,397 ms / 116,405 ms(ok=true,`skipped=false`) |
|
|
944
|
+
| `thirdparty` | `parked: true`,detail = `已临时停放第三方包索引(…\pdsc.dsh-parked),生成结束后自动还原;判定依据:工程没有第三方包(Mcu.ThirdPartyNb=0),本次生成不需要包索引` |
|
|
945
|
+
| pdsc 状态 | 跑前 159 文件 / `parked=false` → 跑后 **159 文件 / `parked=false`**(自动还原) |
|
|
946
|
+
|
|
947
|
+
同一份代码对真实 `.ioc` 的判定(`needsThirdpartyPacks` 直接调用):
|
|
948
|
+
|
|
949
|
+
| `.ioc` | 结论 |
|
|
950
|
+
| --- | --- |
|
|
951
|
+
| `8110_foc.ioc`(G431 FOC 工程) | needed=true,`工程声明了 1 个第三方包(STMicroelectronics.X-CUBE-ALGOBUILD 1.4.0)`,本机 `exact`(装了 1.4.0 / 1.5.0),无 warning,证据行 `Mcu.ThirdPartyNb=1`、`Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` |
|
|
952
|
+
| `demo.ioc`(本机 C8T6 工程) | needed=false,`工程没有第三方包(Mcu.ThirdPartyNb=0),本次生成不需要包索引`,无包无 warning |
|
|
953
|
+
|
|
954
|
+
本机 pdsc 目录 159 个文件 → `listInstalledPacks()` 解析出 **67 个包**,与快照条数一致。
|
|
955
|
+
|
|
956
|
+
## 调试会话活着时读寄存器:复用它的 openocd(洞 D)
|
|
957
|
+
|
|
958
|
+
### 1. 现象
|
|
959
|
+
|
|
960
|
+
`stm32_debug_session`(`reset: "halt"`)开着的时候调 `stm32_regs_read`,两个采样全部 `ok: false`:
|
|
961
|
+
|
|
962
|
+
```text
|
|
963
|
+
读寄存器失败:Error: CMSIS-DAP transfer count mismatch: expected 3, got 2
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
同一批地址在**没有会话**时是好的(`0x4001100C = 0x00000000`、`0x40010004 = 0x02000000`、`pc = 0x08000248`)。也就是说不是地址写错、也不是探针坏了,是「谁先占着探针」的问题。
|
|
967
|
+
|
|
968
|
+
### 2. 根因
|
|
969
|
+
|
|
970
|
+
两条路各自起一个 openocd:
|
|
971
|
+
|
|
972
|
+
- `stm32_debug_session` → `DebugSessionManager.start()`,openocd 监听 `127.0.0.1:3333`,gdb 通过 `target extended-remote` 连它。
|
|
973
|
+
- `stm32_regs_read` → `runRegsRead()`,**又**起一个 openocd(同一份 `configFiles`、同样绑定 3333),脚本里 `init → halt → mdw <addr> → resume → shutdown`。
|
|
974
|
+
|
|
975
|
+
CMSIS-DAP 探针同一时刻只允许一个调试会话,第二个 openocd 抢到的是「半个探针」:它自己的 transfer 队列和第一个会话交错,于是 `expected 3, got 2` 这种计数错。修 `regs_read` 的脚本写法没用——错在两个 openocd 同时在跑。
|
|
976
|
+
|
|
977
|
+
### 3. 修法:会话活着就借它的 gdb
|
|
978
|
+
|
|
979
|
+
`src/engine/debug-session.ts` 新增 `readWords({ addresses, timeoutMs?, signal? })`:
|
|
980
|
+
|
|
981
|
+
- 没有会话 → 立刻返回 `ok: false`,`errors: ["没有调试会话(先 stm32_debug_session,或短任务用 stm32_debug_run)"]`,不假装读过。
|
|
982
|
+
- 有会话 → `commands = ["print/x $pc", "print/x *(unsigned int *)0x…", …]` 交给已有的 `eval()`。`eval` 自己会 `monitor halt` → 逐条执行 → `monitor resume` → `detach`,所以读值不动固件状态,也不额外占探针。
|
|
983
|
+
- 解析:`parseGdbPrintedHex()` 用 `/\$\d+\s*=\s*(0x[0-9a-fA-F]+)/gu` 按出现顺序取值,第 0 个是 pc;缺值只把那一条标 `ok: false` 并在 `errors` 里说「有 N 个地址没读到值(地址没映射或没对齐)」。
|
|
984
|
+
- 地址规整:`normalizeHexAddress()` 剥 `0x`、限 1–8 位十六进制、统一成 8 位小写(`0x0000024c`),避免 `0X4001100C` 这种写法进 gdb 表达式。
|
|
985
|
+
|
|
986
|
+
工具层 `src/tools/regs.ts` 只做一个分支:
|
|
987
|
+
|
|
988
|
+
```ts
|
|
989
|
+
if (debugSessions.isActive()) {
|
|
990
|
+
const words = await debugSessions.readWords({ addresses, timeoutMs, signal });
|
|
991
|
+
// 组装成同一个 RegsReport:configFile / script 留空,logTail = 输出末 12 行
|
|
992
|
+
notes.unshift("复用调试会话(端口 N)的 openocd,没有另起一个");
|
|
993
|
+
} else {
|
|
994
|
+
runRegsRead(...); // 原路径,一点没改
|
|
995
|
+
}
|
|
996
|
+
```
|
|
997
|
+
|
|
998
|
+
报告形状对调用方不变(还是 `RegsReport`),但 `report.command` 变成那条 gdb 命令行,`logTail` 里能看到 `$1 = 0x8001178` 这样的原始输出,出事时能对着看。
|
|
999
|
+
|
|
1000
|
+
### 4. 真机验证
|
|
1001
|
+
|
|
1002
|
+
会话活着时,仓库里的探针脚本(`_probe/probe-holes.mjs`,验证完已删)直接 import `lib/engine/debug-session.js`:
|
|
1003
|
+
|
|
1004
|
+
| 项 | 结果 |
|
|
1005
|
+
| --- | --- |
|
|
1006
|
+
| `debugSessions.start({ projectDir, reset: "halt" })` | ok,`port=3333` |
|
|
1007
|
+
| `readWords(["0x4001100C","0x40010004"])` | ok=true,`pc=0x8001178`,两值 `0x0` / `0x0` |
|
|
1008
|
+
| 走工具层(省略 `projectDir`,靠会话工作目录) | ok=true,notes = `["复用调试会话(端口 3333)的 openocd,没有另起一个","工程目录缺省取会话工作目录:D:/…/demo"]` |
|
|
1009
|
+
|
|
1010
|
+
重启 dsh 后在真宿主里再打一遍(`stm32_debug_session` → `stm32_regs_read` → `stm32_debug_stop`):
|
|
1011
|
+
|
|
1012
|
+
| 字段 | 值 |
|
|
1013
|
+
| --- | --- |
|
|
1014
|
+
| `message` | 从调试会话(端口 3333)读了 2 个值 |
|
|
1015
|
+
| `report.ok` / `durationMs` | `true` / 2124 |
|
|
1016
|
+
| `report.command` | `gdb-multiarch … -ex "target extended-remote 127.0.0.1:3333" -ex "monitor halt" -ex "print/x $pc" -ex "print/x *(unsigned int *)0x4001100c" -ex "print/x *(unsigned int *)0x40010004" -ex "monitor resume" -ex detach` |
|
|
1017
|
+
| `report.pc` | `0x8001178`(会话停在 `Reset_Handler`) |
|
|
1018
|
+
| `report.samples` | `0x4001100c=0x0`、`0x40010004=0x0`,都 `ok: true` |
|
|
1019
|
+
| `report.logTail` | 含 `$1 = 0x8001178` / `$2 = 0x0` / `$3 = 0x0` 与 `[Inferior 1 (Remote target) detached]` |
|
|
1020
|
+
|
|
1021
|
+
对照:同一地址在**无会话**时走 `runRegsRead` 仍然成功(`0x4001100C = 0x00002000`,那是固件跑到 `while` 之后的值),说明两条路都还在,只是不再同时跑。
|
|
1022
|
+
|
|
1023
|
+
### 5. 教训
|
|
1024
|
+
|
|
1025
|
+
- 一个探针上只能有一个 openocd。凡是「自己起 openocd 读点东西」的工具,都得先问一句会话是不是活着。
|
|
1026
|
+
- 复用会话比新起进程简单得多:gdb 已经连着,`print/x *(unsigned int *)0x…` 一句就够,不用再写 openocd 脚本、不用管 `shutdown`。
|
|
1027
|
+
- 会话活着时读值会**暂停再恢复**(`monitor halt` / `monitor resume`),停在断点时读寄存器不会让程序多跑一步——这正是想要的语义,但要写进 notes 里让人知道。
|
|
1028
|
+
- 错误要能自己承认:没有会话时返回可读错误,比抛 gdb 的 `transfer count mismatch` 好定位。
|
|
1029
|
+
|
|
1030
|
+
### 6. 测试计数
|
|
1031
|
+
|
|
1032
|
+
套件 14 → 15,用例 123 → **137 pass / 0 fail**。新增的 `test/tool-contract-units.test.mjs`(14 例)覆盖 `normalizeHexAddress`、`parseGdbPrintedHex`、无会话时 `readWords` 的可读错误,以及工具层省略 `projectDir` 时确实取会话工作目录。
|
|
1033
|
+
|
|
1034
|
+
## 缺包警告的真机验证:失败报告也必须带 notes
|
|
1035
|
+
|
|
1036
|
+
### 1. 目的
|
|
1037
|
+
|
|
1038
|
+
`needsThirdpartyPacks()` 产出的 `warnings` 此前只有单测覆盖,没在真 CubeMX 上验过。本机 C8T6 工程全是 `Mcu.ThirdPartyNb=0`,所以要造一个「声明了包、但本机缺包或缺版本」的工程真跑一遍。
|
|
1039
|
+
|
|
1040
|
+
### 2. 选包:ALGOBUILD 为什么在 F103C8T6 上能用
|
|
1041
|
+
|
|
1042
|
+
159 个 pdsc 里 **0 个**出现 `STM32F103` / `STM32F1xx` 字样——pdsc 不按型号写死,靠条件匹配。`STMicroelectronics.X-CUBE-ALGOBUILD.pdsc` 的兼容条件写的是内核:
|
|
1043
|
+
|
|
1044
|
+
```xml
|
|
1045
|
+
<condition id="Cortex-M Device"><accept Dcore="Cortex-M3"/> …</condition>
|
|
1046
|
+
```
|
|
1047
|
+
|
|
1048
|
+
F103C8T6 正是 Cortex-M3,所以它在 F1 工程里「能用」;本机装了 1.4.0 / 1.5.0,正好可以构造「版本不存在」。
|
|
1049
|
+
|
|
1050
|
+
### 3. 造测试工程
|
|
1051
|
+
|
|
1052
|
+
- `D:/JingYu/Desktop/c8t6_vscode_test/_xcube_probe` = demo 的完整拷贝(3055 文件,排除 `build`、`_probe`、`dsh-stm32`、`.git`、`.dsh-stm32`)。不能拷到 demo 的子目录里,Node 会报 `ERR_FS_CP_EINVAL: cp returned EINVAL (cannot copy … to a subdirectory of self …)`。
|
|
1053
|
+
- 往 `_xcube_probe/demo.ioc` 写入两条假引用(其余行不动):
|
|
1054
|
+
|
|
1055
|
+
```ini
|
|
1056
|
+
Mcu.ThirdPartyNb=2
|
|
1057
|
+
Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.9.9.9
|
|
1058
|
+
Mcu.ThirdParty1=STMicroelectronics.X-CUBE-F103DEMO.1.0.0
|
|
1059
|
+
```
|
|
1060
|
+
|
|
1061
|
+
一个「包在、版本不在」,一个「包不在」。
|
|
1062
|
+
|
|
1063
|
+
预期(直接调 `lib/engine/thirdparty.js`,`pdscDir=C:/Users/JingYu/.stm32cubemx/thirdparties/pdsc`):
|
|
1064
|
+
|
|
1065
|
+
| 字段 | 值 |
|
|
1066
|
+
| --- | --- |
|
|
1067
|
+
| `needed` | `true` |
|
|
1068
|
+
| `reason` | `工程声明了 2 个第三方包(STMicroelectronics.X-CUBE-ALGOBUILD 9.9.9、STMicroelectronics.X-CUBE-F103DEMO 1.0.0)` |
|
|
1069
|
+
| `warnings[0]` | `工程要用 STMicroelectronics.X-CUBE-ALGOBUILD 9.9.9,本机索引里只有 1.4.0、1.5.0(CubeMX 会按可用版本处理,必要时在它里面 Migrate)` |
|
|
1070
|
+
| `warnings[1]` | `工程要用 STMicroelectronics.X-CUBE-F103DEMO 1.0.0,但本机第三方包索引里没有这个包(先在 CubeMX 的 Manage embedded software packages 里装上它,否则生成会报缺包):C:/Users/JingYu/.stm32cubemx/thirdparties/pdsc` |
|
|
1071
|
+
|
|
1072
|
+
### 4. 第一次跑:`ok=true`,但报告里没有 warning——**探针的错,不是产品的错**
|
|
1073
|
+
|
|
1074
|
+
第一次只声明了 ALGOBUILD 9.9.9,真跑 CubeMX 成功(470,354 ms,6 文件落位,保活 12 个 USER CODE 标签),`notes` 里却只有「第三方包索引:保留第三方包索引:工程声明了 1 个第三方包(…9.9.9)」,没有版本不符的警告。
|
|
1075
|
+
|
|
1076
|
+
原因在探针:脚本由 `run_code` 起,子进程 `process.env` 是空的 → `cubeMxUserHome(process.env)` 返回 `null` → `pdscDir` 为 `undefined` → 只判「要不要索引」,不去比对本机装了哪些包。
|
|
1077
|
+
|
|
1078
|
+
```
|
|
1079
|
+
home({}) = null
|
|
1080
|
+
home({ USERPROFILE: "C:/Users/JingYu" }) = C:/Users/JingYu/.stm32cubemx
|
|
1081
|
+
```
|
|
1082
|
+
|
|
1083
|
+
宿主进程有 `USERPROFILE`,所以产品侧没问题;但**任何脱离 DSH 宿主跑的探针都必须自己补 env**,否则测的是「没装 CubeMX 的机器」那条分支。
|
|
1084
|
+
|
|
1085
|
+
### 5. 顺带发现的真缺陷:失败报告把 notes 写死成空数组
|
|
1086
|
+
|
|
1087
|
+
`src/engine/generate.ts` 的 `fail()` 默认值是 `notes: []`:
|
|
1088
|
+
|
|
1089
|
+
```ts
|
|
1090
|
+
function fail(request: GenerateRequest, message: string, extra: Partial<GenerateReport> = {}): GenerateReport {
|
|
1091
|
+
return { … notes: [], …extra };
|
|
1092
|
+
}
|
|
1093
|
+
```
|
|
1094
|
+
|
|
1095
|
+
而第三方包的 `warnings` 在 `parkNotes` 里(`src/engine/generate.ts:411` 的 `parkNotes.push(...decision.warnings)`),只在成功分支 `src/engine/generate.ts:516` 的 `notes.push(...parkNotes)` 被并入。
|
|
1096
|
+
|
|
1097
|
+
后果很刺眼:**CubeMX 恰恰在最需要那条警告的时候失败**——缺包导致生成报错,而报告里的 notes 是空的,用户看不出缺了什么。
|
|
1098
|
+
|
|
1099
|
+
修法(`src/engine/generate.ts`):
|
|
1100
|
+
|
|
1101
|
+
```ts
|
|
1102
|
+
const failureNotes: string[] = [];
|
|
1103
|
+
if (thirdparty.detail !== "") failureNotes.push("第三方包索引:" + thirdparty.detail);
|
|
1104
|
+
failureNotes.push(...parkNotes);
|
|
1105
|
+
const baseReport = { …, notes: failureNotes, … };
|
|
1106
|
+
```
|
|
1107
|
+
|
|
1108
|
+
四处失败出口(`spawnError` / `aborted` / `timedOut` / `!verdict.ok`)都走 `fail(request, …, baseReport)`,一并继承。
|
|
1109
|
+
|
|
1110
|
+
### 6. 第二次跑:失败也把两条警告带出来了
|
|
1111
|
+
|
|
1112
|
+
同一工程、`skipIfUnchanged: false`、`thirdpartyPacks: "auto"`、`timeoutMs: 480000`,探针顶部补 `process.env.USERPROFILE = "C:/Users/JingYu"`:
|
|
1113
|
+
|
|
1114
|
+
| 项 | 结果 |
|
|
1115
|
+
| --- | --- |
|
|
1116
|
+
| 墙钟 | 481,553 ms,`ok=false`,`message = CubeMX 生成超时`(16:24:31 载入工程后再无输出,被 480 s 杀掉) |
|
|
1117
|
+
| `thirdparty` | `parked: false`,detail = `保留第三方包索引:工程声明了 2 个第三方包(…ALGOBUILD 9.9.9、…X-CUBE-F103DEMO 1.0.0)`(需要包时不停放,符合设计) |
|
|
1118
|
+
| `notes` | 3 条:第三方包索引那行 + **两条警告原文**(见 §3 表) |
|
|
1119
|
+
| pdsc | 159 个原位,无 `pdsc.dsh-parked`(不需要停放) |
|
|
1120
|
+
|
|
1121
|
+
也就是说:**警告在失败报告里也能看到**,第 5 节的修复生效。CubeMX 自己的日志里也有旁证(`ThirdParty IPModes/IPconfigs doesn't exist for :STMicroelectronics.X-CUBE-ALGOBUILD.9.9.9`),被 `parseGenerateLog` 归入 knownNoise。
|
|
1122
|
+
|
|
1123
|
+
### 7. 教训
|
|
1124
|
+
|
|
1125
|
+
- 报告的 `notes` 是**给失败看**的,不是给成功看的。任何 `fail()` 都必须带上「为什么会失败」的上下文;把 `notes` 默认写成 `[]` 等于在最需要信息时静音。
|
|
1126
|
+
- 判定依赖 `process.env` 的代码(`cubeMxUserHome`)在探针里必须显式喂 env,否则测到的是另一条分支,而且「看起来正常」。
|
|
1127
|
+
- 造「缺包」比造「包都在」便宜:改两行 `.ioc` 就够,不必真装一个 X-CUBE 包。
|
|
1128
|
+
- 声明了不存在的包时 CubeMX 不是「报错退出」,而是弹出**模态 Warning 等人点 OK**:`The CMSIS-Pack : STMicroelectronics.X-CUBE-ALGOBUILD.9.9.9 is unknown` / `You must Use the Embedded Software Packages Manager to install this CMSIS-pack from your local environment.` / `Now, STM32CubeMX tools continue to load this project without CMSIS-Pack contains.` / `Please,do not save this project to avoid to corrupt it`。`-q` 无头模式没有人能点这个对话框,于是日志停在 `ThirdParty:883 - exiting critical section [close project]`,直到超时被杀——这就是第二次跑 481 s `ok=false` 的全部原因。
|
|
1129
|
+
- 正因为 CubeMX 在缺包时会弹框卡死,**插件必须提前把这条警告说出来**(§3、§6 的 notes):用户先看到「本机索引里没有 X-CUBE-F103DEMO」「只有 1.4.0、1.5.0」,就不会白等 8 分钟去撞同一个框。
|
|
1130
|
+
|
|
1131
|
+
## L2:用户级工具链配置、开工前门禁与安装器(方案1)
|
|
1132
|
+
|
|
1133
|
+
### 1. 目的
|
|
1134
|
+
|
|
1135
|
+
三件互相咬合的事,起因都是「换台机器就得从头教一遍」:
|
|
1136
|
+
|
|
1137
|
+
| 痛点 | 具体表现 | 这次的做法 |
|
|
1138
|
+
| --- | --- | --- |
|
|
1139
|
+
| 工具链位置无处安放 | 只认环境变量与写死的 `DEFAULT_BIN_DIRS`,换台机器把 msys64 装到别处就得设环境变量 | 加用户级配置文件,装在哪写一次、所有工具都认 |
|
|
1140
|
+
| 缺件时跑一半才炸 | `stm32_build` 会 spawn `cmake`,缺 gcc 时报的是 cmake 的内部错误 | 每个动作工具入口先过门禁,缺件就直接给「缺什么、怎么装」 |
|
|
1141
|
+
| 装工具链全靠人肉 | 新手不知道要装 5 个包、不知道要进 PATH | `stm32_env_install` 先出计划(不下载),确认后才真装,PATH 只写用户级 |
|
|
1142
|
+
|
|
1143
|
+
### 2. 用户级配置(`src/data/toolchain-config.ts`)
|
|
1144
|
+
|
|
1145
|
+
配置文件放在 `%USERPROFILE%/.dsh-stm32/config.json`(可用 `DSH_STM32_CONFIG` 指到别处,`DSH_STM32_NO_CONFIG=1` 整体关掉):
|
|
1146
|
+
|
|
1147
|
+
```json
|
|
1148
|
+
{
|
|
1149
|
+
"version": 1,
|
|
1150
|
+
"msys64": "D:/app/msys64",
|
|
1151
|
+
"binDirs": [],
|
|
1152
|
+
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc"],
|
|
1153
|
+
"cubeMxRoot": "D:/app/STM32CubeMX",
|
|
1154
|
+
"updatedAt": "2026-02-11T12:00:00.000Z"
|
|
1155
|
+
}
|
|
1156
|
+
```
|
|
1157
|
+
|
|
1158
|
+
几个定死的选择:
|
|
1159
|
+
|
|
1160
|
+
- **放 `data` 层,不放 `engine` 层**:`data/search-roots.ts` 的 `resolveSearchConfig()` 要读它,放 engine 会形成 `data → engine` 的循环依赖。分层不是审美,是编译器会真的报错。
|
|
1161
|
+
- **`binDirs` 留空就由 `msys64` 推导**(`binDirsFromConfig()` 返回 `[msys64 + "/ucrt64/bin"]`)。用户只写一个 msys64 路径就能用,不必知道 ucrt64/clang64 的区别。
|
|
1162
|
+
- **优先级四层**:显式参数 > `STM32_BIN_DIRS` / `STM32_CUBEMX_ROOT`(整份替换)> 用户配置(整份替换)> `DEFAULT_BIN_DIRS` / `DEFAULT_CUBEMX_ROOTS`。自动发现(扫盘 + 注册表)只在「没给显式参数」那一档追加到尾部,不会盖掉用户写的。
|
|
1163
|
+
- **坏 JSON 当没配置**:`readToolchainConfig()` 返回 `config: null` + `errors[0] = "配置文件不是合法 JSON:…;已按未配置处理(重新写入会覆盖它)"`。绝不因为一个坏文件让所有工具罢工。
|
|
1164
|
+
- **原子写**:写 `<path>.tmp-<pid>` 再 `rename`,避免写一半断电留下半截 JSON。
|
|
1165
|
+
- **读缓存按 `path + mtimeMs + size`**:门禁每次工具调用都要读一次配置,每次 `stat + readFile` 不贵但没必要;写完立刻失效。
|
|
1166
|
+
|
|
1167
|
+
### 3. 门禁(`src/engine/toolchain-gate.ts`)
|
|
1168
|
+
|
|
1169
|
+
能力 → 必需组件的映射是唯一事实来源:
|
|
1170
|
+
|
|
1171
|
+
```ts
|
|
1172
|
+
export const CAPABILITY_COMPONENTS = {
|
|
1173
|
+
build: ["gcc", "cmake", "ninja"],
|
|
1174
|
+
flash: ["openocd"],
|
|
1175
|
+
debug: ["openocd", "gdb"],
|
|
1176
|
+
generate: ["cubemx", "cubemx-java"],
|
|
1177
|
+
};
|
|
1178
|
+
```
|
|
1179
|
+
|
|
1180
|
+
`ensureToolchain(ctx, { capability, binDirs?, cubeMxRoots?, envCheck?, signal? })` 的判定顺序:
|
|
1181
|
+
|
|
1182
|
+
1. **快路径先走文件存在性**(`resolveFromDirs`,只 `existsSync`,**不 spawn**)。门禁挂在每个工具入口上,如果每次都 `--version` 一遍,编译一次就多五个进程、几百毫秒,还会被杀毒软件拖成秒级。
|
|
1183
|
+
2. 快路径没全命中,才 `probeTarget` 逐个真探测(拿版本号,报告里能显示 `13.3.0` 这种实话),结果按「能力 + binDirs + cubeMxRoots」缓存 **60 s**(`PROBE_CACHE_TTL_MS`)。
|
|
1184
|
+
3. `envCheck` 三档:`block`(默认,缺件不干活,返回 schema 齐全的失败报告)、`warn`(照干,把警告放报告首行)、`off`(不检查,报告里写「(envCheck=off,没有检查)」)。**默认档是 block**:宁可不动手,也不要给一个「跑到一半才炸」的失败。
|
|
1185
|
+
|
|
1186
|
+
blocked 时的 `message` 是一句人话,不是字段堆砌:
|
|
1187
|
+
|
|
1188
|
+
```
|
|
1189
|
+
缺 arm-none-eabi-gcc、CMake、Ninja,这次没有开始编译:arm-none-eabi-gcc 没找到(编译 C 代码用)…。要我装吗?回一句「装」,我先跑 stm32_env_install 出计划(只列大小与步骤、不下载),确认后才真装;想自己装就看下面 missing[0].install 的第一条。
|
|
1190
|
+
```
|
|
1191
|
+
|
|
1192
|
+
`gateReportNotes()` 把它摊成报告 `notes`:首行 message、每个缺件一行「缺 X:hint」+ 一行缩进的「安装:…」、末行 nextStep。**失败报告也必须有 nextStep**——见「缺包警告的真机验证」那节的教训。
|
|
1193
|
+
|
|
1194
|
+
### 4. 安装器(`src/engine/msys2-install.ts` + `src/tools/env-install.ts`)
|
|
1195
|
+
|
|
1196
|
+
默认 `dryRun` 是 `true`:`stm32_env_install` 被调一次,只出计划(7 步、下载大小、PATH 前后对比),**零下载、零写注册表、零建目录**。真装必须 `dryRun: false` **且** `confirm: true` 两个开关同时在。
|
|
1197
|
+
|
|
1198
|
+
计划模式在本机的实测:
|
|
1199
|
+
|
|
1200
|
+
| 字段 | 值 |
|
|
1201
|
+
| --- | --- |
|
|
1202
|
+
| `report.mode` | `plan` |
|
|
1203
|
+
| `report.msys64` / `resolvedVia` | `D:/app/msys64` / `discovered`(正确复用已有工具链,不重复装一份 2.5 GB) |
|
|
1204
|
+
| `report.steps` | 7 步全 `pending` |
|
|
1205
|
+
| `report.config.written` / `report.path.done` | `false` / `false` |
|
|
1206
|
+
| 副作用 | 临时目录零新文件、零 `curl`、零 `reg add` |
|
|
1207
|
+
|
|
1208
|
+
真装的四个技术决定:
|
|
1209
|
+
|
|
1210
|
+
- **下载官方 sfx**:`https://github.com/msys2/msys2-installer/releases/latest/download/msys2-base-x86_64-latest.sfx.exe`(43,060,392 字节)。原本任务书里写的 `msys2-x86_64-latest.sfx.exe` 在 GitHub 上**不存在**,是资产名写错——下载 URL 一定要真访问一次再写进代码。缓存 `<配置目录>/msys2-latest.sfx.exe`,先写 `.part` 再 rename,复用前验 `MZ` 头(`0x4d 0x5a`)。
|
|
1211
|
+
- **sfx 解出来自带一层 `msys64`**:所以先解到 `<targetParent>/.dsh-msys2-staging`,确认里面有 `usr/bin/bash.exe`,再同盘 rename 到 `targetDir`。`-y -o<dir>` 与 `-y -o"<dir>"` 两种写法都试(7z 自解压对带空格路径的引号处理不一致)。
|
|
1212
|
+
- **补包用 pacman,不整包重下**:`<msys64>/usr/bin/bash.exe -lc "pacman -Sy --noconfirm && pacman -S --noconfirm --needed <5 包>"`,5 个包是 `mingw-w64-ucrt-x86_64-arm-none-eabi-gcc`、`-gdb-multiarch`、`-openocd`、`-cmake`、`-ninja`。stderr 命中 keyring 或 `invalid or corrupted package` 就先 `pacman-key --init && pacman-key --populate msys2` 再重试一次(新解压的 MSYS2 第一次 `-Sy` 几乎必然撞签名)。pacman 失败不停整体流程:PATH 与配置照写,报告里 `ok` 由「除 path 外有无 failed 步骤」决定。
|
|
1213
|
+
- **PATH 只写用户级,而且先备份**:`reg query "HKCU\Environment" /v Path` 读出 `REG_EXPAND_SZ`,按 `normalizePathEntry` + 小写比较做幂等,写前备份到 `<配置目录>/path-backup-<ISO>.txt`,**备份失败就不写**。写用 `reg add HKCU\Environment /v Path /t REG_EXPAND_SZ /d <新值> /f`:`setx` 会在 1024 字符处截断,还会把 `%USERPROFILE%` 这类变量展开成死路径。绝不碰 `HKLM`。
|
|
1214
|
+
- **不做卸载**:删工具链要判断「是不是用户自己的目录」,误删代价远大于留着一份。
|
|
1215
|
+
|
|
1216
|
+
### 5. 接入点
|
|
1217
|
+
|
|
1218
|
+
七个动作工具 + 一条命令,能力映射:
|
|
1219
|
+
|
|
1220
|
+
| 工具 | 能力 | 门禁位置 |
|
|
1221
|
+
| --- | --- | --- |
|
|
1222
|
+
| `stm32_build` | build | `src/tools/build.ts:167`(block `:172`) |
|
|
1223
|
+
| `stm32_flash` | flash | `src/tools/flash.ts:137`(block `:142`) |
|
|
1224
|
+
| `stm32_debug_run` | debug | `src/tools/debug.ts:177`(block `:182`) |
|
|
1225
|
+
| `stm32_debug_session` | debug | `src/tools/debug-session.ts:167`(block `:172`) |
|
|
1226
|
+
| `stm32_regs_read` | debug | `src/tools/regs.ts:149`(block `:154`,在「借活跃会话」分支之前) |
|
|
1227
|
+
| `stm32_generate` | generate | `src/tools/generate.ts:215`(block `:220`,在 `releaseProbeFor` 之前,不占探针) |
|
|
1228
|
+
| `stm32_project_create` | generate | `src/tools/project-create.ts:143`(block `:148`) |
|
|
1229
|
+
| `/stm32-env` | 全部四项 | `src/commands/register.ts:271` |
|
|
1230
|
+
|
|
1231
|
+
门禁统一插在「取到 subprocess + 解析工程目录 + 参数校验之后、调用引擎之前」:早退(工程名非法、目录不存在)比门禁更优先,否则用户会收到「缺 gcc」而不是「工程名不对」。`stm32_doctor` 与 `stm32_env_probe` 不接门禁——它们本身就是体检工具。
|
|
1232
|
+
|
|
1233
|
+
`/stm32-env` 的真实卡片(本机):
|
|
1234
|
+
|
|
1235
|
+
```
|
|
1236
|
+
工具链体检(配置:C:/Users/JingYu/.dsh-stm32/config.json)
|
|
1237
|
+
编译 ✔ gcc、CMake、Ninja 都在
|
|
1238
|
+
烧录 ✔ OpenOCD 在
|
|
1239
|
+
调试 ✔ OpenOCD、GDB 都在
|
|
1240
|
+
生成代码 ✔ CubeMX、CubeMX 内置 JRE 都在
|
|
1241
|
+
都齐了:/stm32-build 就能编译
|
|
1242
|
+
```
|
|
1243
|
+
|
|
1244
|
+
缺件那行是「编译 ✘ 缺 arm-none-eabi-gcc、CMake —— winget install …」这种形状,**缺件也算 success**:体检结果不是错误,是信息。
|
|
1245
|
+
|
|
1246
|
+
### 6. 踩坑
|
|
1247
|
+
|
|
1248
|
+
- **`stm32_env_install` 有两层 mode**:工具的返回体是宿主卡片形态 `{ mode: "report" | "job", jobId, message, report }`,引擎侧的 `plan` / `install` 在 `report.mode` 里。第一版 schema-guard 断言 `value.mode === "plan"` 直接红(`'report' !== 'plan'`)。断言必须写成 `value.mode !== "job"` + `value.report.mode === "plan"`。
|
|
1249
|
+
- **schema-guard 的假 ctx 只有 `tools.register` 和 `get("subprocess")`**:门禁如果插在参数校验之前,一大批「非法参数也能拿到完整失败报告」的既有断言会被门禁文案替代。blocked 报告还必须满足各自的 `output.schema`:`stm32_project_create` 的 `report.firmwareRoot` 不能赋 `undefined`(要干脆不赋),`stm32_debug_session` 的 `session.ok` 必须是 `false`。
|
|
1250
|
+
- **`test/run-units.mjs` 必须给子进程 `DSH_STM32_NO_CONFIG=1`**:开发机上真实存在 `~/.dsh-stm32/config.json` 时,`search-roots-units` 里「没给参数就用默认候选」的断言会红。而 `toolchain-units.test.mjs` 顶部自己 `delete process.env.DSH_STM32_NO_CONFIG`——它测的就是配置层。这是个典型的「测试互相污染」,用环境变量在进程边界切开最省事。**二次事故**:真装把 `~/.dsh-stm32/config.json` 写出来之后,`search-roots-units` 里那两条「没给参数就该吃默认候选」的断言直接红了(actual 变成 `D:/app/msys64/ucrt64/bin`)——这几条把 env 当参数**显式传** `{}`,`run-units` 给子进程设的 `DSH_STM32_NO_CONFIG=1` 传不进这个参数。现在该文件顶部有 `cleanEnv(extra)` = `{ DSH_STM32_NO_CONFIG: "1", ...extra }`,四条断言都走它:断言的是「默认层」,就不该让「本机装没装过」参与决定。
|
|
1251
|
+
- **没有 subprocess 也不能只说「没找到」**:门禁在 `subprocess` 缺失时合成 `found: false` 的探测结果,并且把 `error`(`宿主没有提供 subprocess 服务,只能做文件存在性检查`)落进 `missing[].error`。否则用户看到「缺 gcc」,实际是宿主少注入了服务。
|
|
1252
|
+
- **工具数/命令数是硬断言**:`test/commands-units.test.mjs` 里有一份命令名数组、`schema-guard` 头注释、README 的「N 个工具 / N 条命令」、`docs/development-notes.md` 的头部说明,新增一个工具要一起改,否则红的是三处不相关的地方。
|
|
1253
|
+
|
|
1254
|
+
### 7. 测试计数
|
|
1255
|
+
|
|
1256
|
+
套件 15 → 17,用例 137 → **170 pass / 0 fail**(CI 上是 168 pass + 2 skipped,跳过的仍是那两条需要真固件包的脚手架用例)。新增:
|
|
1257
|
+
|
|
1258
|
+
- `test/toolchain-units.test.mjs`(22 例):配置读写往返(`DSH_STM32_CONFIG` 指到临时目录、反斜杠与大小写重复归并、写完无 `.tmp` 残留)、坏 JSON → `config: null` + errors、`normalize` 丢非法字段、`binDirsFromConfig` 推导、`toolchainConfigPath` 三种优先级、`updateToolchainConfig` 合并、`resolveSearchConfig` 四层优先级;门禁的 `CAPABILITY_COMPONENTS` / `normalizeEnvCheck`、快路径不 spawn、缺件 block 文案与 detail、warn 前缀、off 放行、60 s 缓存 `cacheHit` 与 `resetGateCache`、`generate` 报 `[cubemx, cubemx-java]`、无 subprocess 时 `missing[0].error`;以及引擎/门禁共用的 `resolveToolIn`(显式目录命中就不问宿主、目录没有才回退 PATH、哪都没有返回 null 不抛、老式假 subprocess 不带 `resolveExecutable` 也不炸);再加大三例(§10):外来配置的告警透传到 `warnings` / `gateReportNotes`、`buildTargets` 的 pacman 建议按 `binDirs` 推导且全文不出现开发机路径、`resolveTargetDir` 拒绝「盘符都不存在」的配置 msys64。`test/search-roots-units.test.mjs` 9 → 11:内置默认候选不含任何某台机器专属路径、`searchConfigWarnings` 只报不存在的条目(含 `source: "env"` 与存在项不报)。
|
|
1259
|
+
- `test/install-units.test.mjs`(6 例,§11 那次真装事故换来的):`parsePacmanQuery` 只收「包名 版本」行;五包已装时 pacman 步 `skipped` 且一条 `pacman -S` 都没执行(断言 calls 里没有该前缀)、`ok` / `verify.ok` / `config.written` 全 true 且写出的配置 `msys64` 对得上;pacman 失败但自检全过 → 步 `done`、detail 含「已装」与 `pacman -Syu`、`ok` true;依赖解不开且自检失败 → `failed`、detail 含「无法满足依赖关系」与 `-Syu`、`ok` false;工具真装返回 `mode: "job"`、`message` 含「已在后台安装」且不含「还没动手」、`report.notes` 里没有「这只是计划」、job label 含 `stm32_env_install`。假件只实现 `spawn` 的四个成员(`done` / `collected` / `terminate` / `waitForExit`),按命令内容回答,不跑真 pacman。第 6 例盯的是**计划文案与实际执行的偏差**:计划里 pacman 步必须写出「先 `pacman -Q` 问一遍、已装跳过」,且不能再预告一条无条件 `-Sy --noconfirm && pacman -S` 的命令;计划模式除了一次只读的 `reg.exe query HKCU\Environment /v Path`(用来预告「会不会重复写 PATH」)之外不跑任何命令,尤其不跑 pacman。
|
|
1260
|
+
- `test/schema-guard.mjs` 17 → 20:`stm32_env_install` 缺开关停在计划(不写 PATH、不开 job)、门禁缺件时 `stm32_build` 返回 schema 齐全的失败报告、`envCheck: "off"` 不被门禁文案替代。
|
|
1261
|
+
|
|
1262
|
+
### 8. 还没验证的
|
|
1263
|
+
|
|
1264
|
+
- **真装只跑通了一半**(2026-10-24 在开发机真跑过一次,见 §11):复用已有 MSYS2 → `prepare` 命中、`download` / `extract` 跳过、`pacman -Q` 判已装 → `skipped`、`verify` 5/5、`config` 写入,整条链是真通的。**仍然没跑过**:真下载 43 MB、解压、真装 247 MB(这台的五个包本来就在)、`reg add` 成功路径(PATH 里早就有这条目录,走的是「已存在不重复写」)、超长 PATH 的变量展开、跨卷 rename、`pacman-key` 重试分支、`needsDecision: "msys64Dir"` 分支。
|
|
1265
|
+
- **`needsDecision: "msys64Dir"` 分支**:本机因为已有 `D:/app/msys64` 走的是 `discovered`,没有目标的机器上该返回「装哪?」而不是替用户决定。
|
|
1266
|
+
- **block 档的真机复现**:只能真在缺件机器上跑。本机 `binDirs: ["D:/__dsh_stm32_missing_bin__"]` **模拟不出来**——探测层会回退到 PATH,`D:/app/msys64/ucrt64/bin` 在用户级 PATH 里,于是门禁照样放行;本机用 `generate` 能力(CubeMX 走绝对路径候选、PATH 供不上)验过 block 生效。
|
|
1267
|
+
|
|
1268
|
+
### 9. 0.1.1 真机验证揪出的不一致:门禁看 PATH、引擎不看(已修)
|
|
1269
|
+
|
|
1270
|
+
- **现象**:真宿主上 `stm32_build({binDirs: ["D:/__dsh_missing_bin__"], envCheck: "block"})` 照样编译成功(0.9 s);`stm32_flash` / `stm32_regs_read` / `stm32_debug_session` 同参数却报引擎自己的旧文案「找不到 openocd(…);查过 D:/__dsh_missing_bin__,以及 PATH」。同一次调用里门禁说齐全、引擎说找不到,用户看到的是自相矛盾的两句话。
|
|
1271
|
+
- **根因**:门禁的探测(`probe.ts` 的 `resolveCandidate`)找不到目录就走 `subprocess.resolveExecutable`(= PATH);而 `engine/flash.ts:214`、`engine/regs.ts:150`、`engine/debug.ts:201-202`、`engine/debug-session.ts:223`/`:311` 只调 `resolveFromDirs`(只看 `config.binDirs`),文件不存在就直接返回失败——**文案里那句「以及 PATH」其实没查**。`engine/build.ts` 的 `resolveCmake` 反而有 PATH 兜底(找不到就返回裸 `cmake` 交给宿主),所以只有它跑得通。
|
|
1272
|
+
- **修法**:`src/engine/probe.ts` 新增 `resolveToolIn(subprocess, names, binDirs, signal)`:先按目录找文件(零 spawn),miss 再依次问宿主;宿主没有 `resolveExecutable`(老式假 subprocess / 离线单测)就返回 null 不抛。flash / regs / debug / debug-session 五处调用点全部换成它,门禁与引擎从此同一条规则。这也正是 `docs/development-notes.md:673` 早就写下的设计意图(scope 含「以及 PATH」)。
|
|
1273
|
+
- **决策(用户 2026-10-24 明确)**:门禁与引擎都**不**忽略 PATH。顺序固定为「配置目录(`binDirs` / `msys64` / 环境变量)→ PATH 兜底」:配置里指的那份优先,配置里没有才用系统 PATH 里的,都没有才判缺件。理由:PATH 里的工具就是真能跑的工具,忽略它反而会对着一个装好的机器说「缺工具链」;配置目录优先则保证用户点名的那份不被旧版本顶掉。**不做**严格模式(只看配置目录)。
|
|
1274
|
+
- **真机复验(2026-10-24,插件 0.1.1)**:`binDirs: ["D:/__dsh_missing_bin__"]` + `envCheck: "warn"` 逐个入口打了一遍,四个入口全部**靠 PATH 兜底跑通**:`stm32_build` 1.3 s 成功(增量,产物 656888 B)、`stm32_flash` 4.4 s「烧录成功(已校验)」(openocd 日志里有 `device id = 0x20036410`、`flash size = 64 KiB`、`** Verified OK **`)、`stm32_regs_read` 读到 3 个地址(`GPIOC_ODR=0x00000000`、`RCC_APB2ENR=0x00000035`、`ICSR=0x00000000`,pc=0x0800024c)、`stm32_debug_session` 起会话成功并在 `stm32_debug_eval` 里读到 `g_led_blink_count = 23`、`pc 0x8001178 <Reset_Handler>`,`stm32_debug_stop` 正常释放探针(之后 `stm32_doctor` 报 `processes: []`、`portBusy: false`)。**结论**:§9 那条修复在真硬件上成立,门禁与引擎不再是两套规则。
|
|
1275
|
+
- **后台 job 在真宿主的行为**:`foreground !== true` 且宿主有 `jobs` 时走 job 分支,进度靠 `handle.append`,只在单测里用假 handle 验过。
|
|
1276
|
+
|
|
1277
|
+
### 10. 插件要给别人下载:默认值去本机化 + 外来配置告警
|
|
1278
|
+
|
|
1279
|
+
- **现象**:插件是给自己写的,路径也是自己的。三处把开发机写死进了产物:`DEFAULT_BIN_DIRS` 第一项是 `D:/app/msys64/ucrt64/bin`、`DEFAULT_CUBEMX_ROOTS` 第一项是 `D:/app/STM32CubeMX`;`buildTargets` 的五条 `install` 建议直接写 `D:/app/msys64/usr/bin/pacman.exe -S …`;`xcube-catalog.ts` 的来源串带 `C:/Users/JingYu/…`。别人 `dsh plugin add` 之后:报告里「查过 D:/app/msys64/…」是一句在他机器上无意义的噪声,照抄 pacman 建议直接报「不是内部或外部命令」,而把 `~/.dsh-stm32/config.json` 从这台机器拷过去更糟——安装器会拿配置里的 `msys64` 当已装目标,往一个不存在的盘上写。
|
|
1280
|
+
- **根因**:路径不是「配置」,而是写进了常量、提示文案和数据快照;同时「配置是别的机器的」这个状态在整个链路里**没有任何表达通道**——读进来的路径既不过滤也不提示,安装器也分不清「已装」与「这台机器上根本没有这个盘」。
|
|
1281
|
+
- **修法**(四条,互相独立):
|
|
1282
|
+
1. **默认值只留通用位置**:`DEFAULT_BIN_DIRS = ["C:/msys64/ucrt64/bin", "C:/msys64/mingw64/bin"]`、`DEFAULT_CUBEMX_ROOTS = ["C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX"]`。装在别处不靠猜——自动发现(扫盘 + 注册表 + PATH)本来就兜得住,默认列表只是起点。
|
|
1283
|
+
2. **只报告,不动手**:`searchConfigWarnings(env, exists)` 检查 `STM32_BIN_DIRS` / `STM32_CUBEMX_ROOT` 与配置里的 `msys64` / `binDirs` / `cubeMxRoot`,不存在的每条给一句「配置文件里的 X 在本机不存在(配置可能是从别的机器拷来的),这一条搜不到工具;换机器后重跑 stm32_env_install,或手改 ~/.dsh-stm32/config.json」。它**不删条目也不过滤**,`resolveSearchConfig` 的输出与以前逐字一致——配置是用户的,插件没有资格替人清空。告警接进三处:`GateResult.warnings` + `buildDetail` 的「⚠ …」行、`gateReportNotes`(**放行时也带**,否则「编译成功」旁边看不到污染来源)、`stm32_env_probe.recommendations` 开头。
|
|
1284
|
+
3. **建议按实际 MSYS2 推导**:新增 `msys64RootFromBinDirs(binDirs)`(从 `<root>/ucrt64/bin` 这类路径反推 root)与 `pacmanHint(config)`,五条包建议变成 `<root>/usr/bin/pacman.exe -S …`,没有 MSYS2 证据时回落 `C:/msys64`;CubeMX 那条改成「装到 `C:/Program Files/…` 会被自动发现」。
|
|
1285
|
+
4. **安装器认盘符**:`driveUsable(path)` 先确认 `Q:/` 本身存在,再谈目录。配置里的 `msys64` 盘符都没有时 → 忽略该配置、notes 与 message 前置「⚠ 配置里的 MSYS2 根 Q:/app/msys64 在本机不存在(盘符都没有,配置大概是从别的机器拷来的),已忽略,请指定 targetDir」,然后照常回落自动发现、否则要求 `targetDir`。**绝不**往不存在的盘上 mkdir/解压。
|
|
1286
|
+
- **决策**:为什么不按原计划写「按 `env` 推导默认路径的函数」(`LOCALAPPDATA`、`scoop`、`ChocolateyToolsLocation`…)?因为那等于把「猜别人的安装位置」这件事从 3 条硬编码扩散成 8 条更隐蔽的猜测,而自动发现已经在做同一件事且证据更强(真扫盘、真查注册表)。默认值越短越好,短到「只含 Windows 上最标准的两个位置」。
|
|
1287
|
+
- **未做**:以上全部只在单测里用 `exists` 注入模拟过(假 `Q:/`、假 `E:/gone/bin`),**没有一台真正「什么都没装」的机器**跑过;PATH 写坏/超长的真机路径仍只在计划模式里看过(见 §8)。
|
|
1288
|
+
|
|
1289
|
+
### 11. 第一次真装:pacman 会顺手升级用户工具链,且"失败"不等于没装成
|
|
1290
|
+
|
|
1291
|
+
- **真跑的证据**(2026-10-24,`stm32_env_install({dryRun:false, confirm:true})`,后台 job):`prepare` 命中已有 MSYS2、`download` / `extract` 跳过、`pacman` 退出码 1「错误:无法准备事务处理 (无法满足依赖关系)」、`verify` 5/5 全过(gcc 13.3.0、gdb 16.2、openocd 0.12.0、cmake 3.31.5、ninja 1.12.1)、`config` 写入,**job 整体判 failed**。
|
|
1292
|
+
- **根因一(副作用)**:`pacman -S --noconfirm <5 个 mingw 包>` 对**已装**的包不是跳过而是"顺手升级到仓库最新"。`pacman -Sp --needed` 一跑就露馅:gcc 13.3.0 → 16.2.0、gdb 16.2 → 18.1、cmake 3.31.5 → 4.4.4、ninja 1.12.1 → 1.13.2、openocd 0.12.0 → 0.12.0-4。装个 openocd 顺手把别人的编译器升一个大版本,是任何插件都没资格做的决定。
|
|
1293
|
+
- **根因二(假失败)**:久未整体升级的 MSYS2 上,`pacman -Sy` + 局部 `-S` 会因"局部升级解不开依赖"直接失败;而这时工具链其实**全都在**(`verify` 5/5),却报"安装未完成"。
|
|
1294
|
+
- **修法**:
|
|
1295
|
+
1. 先问再装:`pacman -Q <packages>` → `parsePacmanQuery` 解析出已装集合,缺件才装。五个全在 → pacman 步直接 `skipped`,detail 写「…都已经装了,没有重复安装,也没有升级(要升级自己跑 pacman -Syu)。」
|
|
1296
|
+
2. 新命令 `pacmanInstallCommand(packages)` = `pacman -S --noconfirm --needed …`,**不带 `-Sy`**;只有整机一件都没装(`installed.size === 0`)时才走带同步的那条。
|
|
1297
|
+
3. 补包失败且不是"整机没装"时,先自动 `pacman -Sy` 重试一次并 `onProgress` 说明;仍失败且 stderr 含「无法满足依赖关系」就追加一句「这条一般是 MSYS2 太久没整体升级:先在 <msys64> 里跑 pacman -Syu,再重调本工具。」
|
|
1298
|
+
4. 成功判定加一条:`verify.ok` 且 pacman 步失败 → 该步改判 `done` 并附「但自检显示 5 个组件都能跑,按「已装」处理(插件不替你升级,要升级自己跑 pacman -Syu)。」——自检是最终裁判,pacman 的退出码只是过程信息。
|
|
1299
|
+
5. 真装卡片文案换成「已在后台安装 MSYS2 到 …:7 步依次跑,进度看 job 输出。」,并过滤掉计划模式专属的那句「这只是计划」,否则用户在 job 里读到"还没动手"会以为没装。
|
|
1300
|
+
6. **计划文案与实际执行对齐**:pacman 步原本预告的是 `bash.exe -lc "pacman -Sy --noconfirm && pacman -S …"`——真跑已经不是这条了。改成「先 `pacman -Q <5 个包>` 问一遍装没装,已装的直接跳过(不重复安装、也不升级…);只对缺的包跑 `pacman -S --noconfirm --needed <缺的包>`;整机一件都没有时才先 `pacman -Sy` 同步一次」。用户是先看计划再决定装不装,计划里的命令必须就是会跑的命令。
|
|
1301
|
+
- **验证**:`test/install-units.test.mjs` 6 例(假 `spawn`,按命令内容回答);修完后再真机跑一次 `stm32_env_install({dryRun:false, confirm:true})`(job `stm32-env-install-7d8c8295473445d7`):卡片首行「已在后台安装 MSYS2 到 D:/app/msys64(来源:配置里的 msys64):7 步依次跑,进度看 job 输出。」,job 状态 **completed**,pacman 步 `[--]` 跳过(detail 列出 5 个包与版本)、PATH 步「已经有 D:\app\msys64\ucrt64\bin,没有重复写」、自检 5/5、config 写入,结尾「现在可以编译 / 烧录 / 调试」;再用真 `subprocess` 在本机复跑一次(临时脚本、`DSH_STM32_CONFIG` 指临时文件、`writePath: false`):pacman 步 `skipped`、detail 列出 5 个包与版本、`ok` true、`verify.ok` true,**全程没有第二条 `pacman -S`**。
|
|
1302
|
+
- **教训**:安装器对"已经装好一部分"的机器最危险——很容易把"再确认一次"写成"再动一遍手"。凡是 pacman / apt / npm install 这类命令,先查状态再决定执行,且默认永不隐式升级。
|
|
1303
|
+
|
|
1304
|
+
### 12. 动手前先选路线:installability 分流 + `stm32_route_plan`
|
|
1305
|
+
|
|
1306
|
+
- **问题**(用户 2026-10-24 在阿里云 Windows 服务器上实测 0.1.1 时提出):插件默认只会「缺什么就想着装什么」。但缺件其实分两类——一类是 pacman 装得上的(gcc / cmake / ninja / openocd / gdb),另一类**根本装不了**:CubeMX 是 InstallAnywhere GUI 向导(没有官方静默参数、要 ST 账号并同意许可、装完约 1.5 GB),固件包不在安装包里且在 CubeMX 之外没有任何权威来源。旧门禁对这两类说同一句话「回一句「装」,我先跑 stm32_env_install 出计划」,用户照做只会拿到一个必然失败的 job。用户的原话要求是三条:必须用 CubeMX 的程序要有引导安装步骤;HAL 与寄存器都能做的程序要把两版的效率/可读性评估给他选;选了 HAL 又缺 CubeMX 就要引导他自己装。
|
|
1307
|
+
- **取证(为什么固件包不能靠 GitHub 下载代替)**:`STMicroelectronics/STM32CubeF1` 有 `v1.8.7` tag,但仓库挂 22 个 git 子模块,编译必需的 `Drivers/CMSIS/Device/ST/STM32F1xx` 与 `Drivers/STM32F1xx_HAL_Driver` 都是子模块——**tarball / zip 里是空目录**。本机官方包顶层的 `package.xml` 只有 7 行(`DBVersion="2.0"` + `Release="FW.F1.1.8.0"` + `Patch="FW.F1.1.8.7"`),需要自造;而 CubeMX 认不认这种手工组装的包**尚未验证**(要往真实 `Repository` 放一次再 `-q` 生成才算数,属于会动用户安装目录的操作,等授权)。所以本期只做「说清楚 + 指路」,不做自动组装。
|
|
1308
|
+
- **路由判断为什么必须绑工程**:同一个外设在不同工程里代价完全不同——USART 轮询 20 行,USART + DMA + 空闲中断收不定长帧就是另一回事。所以 `stm32_route_plan` 的 `requirement` 是必填项,不提供「通用 HAL vs 寄存器对照表」;给不出结论时宁可 `unclear` 也不瞎猜。
|
|
1309
|
+
- **实现**(三块,互不依赖):
|
|
1310
|
+
1. `src/data/install-guides.ts`:`COMPONENT_INSTALLABILITY`(前五个 `auto`,`cubemx` / `cubemx-java` / `firmware` 是 `manual`)+ `cubeMxGuide()` / `firmwareGuide({family,packageName,repositoryDir})`(字段化步骤:标题、说明、可粘贴命令、自检、`portable` 的「整目录拷过去免重装」)+ `guidesFor(components)`(`cubemx` 与 `cubemx-java` 合成一份)。
|
|
1311
|
+
2. `src/engine/toolchain-gate.ts`:`GateResult` 增 `installability: "none" | "auto" | "manual"` 与 `guides: InstallGuide[]`;`GateMissing` 每条也带 `installability`。block 档的 `nextStep` 按缺件成分分流:全 auto → 原文案「回一句「装」」;全 manual → 「插件不代装,照着 guides[].steps 走」;混合 → 两句话分开说,并把「能自动装的是哪几个」点名。`buildDetail` 每条缺件多一行「方式:自动(插件可代装)/ 手动(插件不代装,按下面的指引)」,`gateReportNotes` 在放行时也贴前两步——**用户往往是在"编译成功但可能有坑"的那一刻才需要这条指引**。
|
|
1312
|
+
3. `src/tools/route-plan.ts` + `src/engine/route-plan.ts`:`PERIPHERAL_RULES` 28 条规则(`family` + `rank` 同族只留最具体的一条:说「串口中断」就不再单列「串口轮询」),每条给 HAL 与寄存器两套 `{effort, risk, setup}`(1 最省 → 5 最费),寄存器为 `null` 的是协议栈级外设(CAN / USB / ETH / SD / FSMC / 低功耗 / RTOS),`regGap` 写清「为什么没有寄存器版」。判定:`reg.effort<=2 && reg.risk<=2` 才建议寄存器,否则建议 HAL;有 `hal-required` 就 `hal-only`,全 `register` 就 `register-ok`,其余 `both-viable`。工具把门禁的 `capability` 也跟着路线走:`register-ok` 查 `build`(gcc/cmake/ninja),否则查 `generate`(CubeMX + JRE),再叠一层 `findFirmwarePackage`(三条判据与 `scaffold.ts:113-126` 保持一致,同族多版本取字典序最大,只有半成品时 `incomplete: true` 并提示「多半是只解压了 GitHub 源码包」)。
|
|
1313
|
+
- **踩坑**:`matchText` 最初只把来源记成 `"requirement"`,`iocPeripherals` 分支又拿外设名去查规则 id,导致 `matchedBy` 永远没有 `"ioc"`(单测直接红)。改成 `matchText(text, into, source)` 三参数后,来源才如实反映「这句话是需求里说的还是 .ioc 里已使能的」。另一条:写中文文案时用 ASCII 双引号当引号会把 TS 字符串写断(tsc 一片 `TS1005`/`TS1127`),全项目统一用「」。
|
|
1314
|
+
- **验证**:`test/route-plan-units.test.mjs` 15 例(四条 verdict 判定、同族去重、`unknown` 提示、`.ioc` 证据、`familyOf`、固件包完整/半成品/无 Repository 三种、门禁 manual 与 auto 两档文案、`guidesFor` 合并规则);`test/schema-guard.mjs` 20 → 21(`stm32_route_plan` 缺 `requirement` 的早退形状 + 正常评估形状,`envCheck: "off"` 保证不 spawn)。套件 17 → 18,用例 170 → **186 pass / 0 fail**(CI 上 184 + 2 skipped)。
|
|
1315
|
+
- **顺手补的三处**:① `.ioc` 里的 `NVIC` / `RCC` / `SYS` 是 CubeMX 的虚拟系统条目,原先被当成"已使能外设的证据",于是正文写「已把 3 个外设算作证据」而表里只有 2 行——现在按 `VIRTUAL_IOC_IPS` 过滤掉;② 随插件下发的 SKILL 顶部加了「〇、先定路线」,把手写代码前先跑 `stm32_route_plan` 写成工作流第一步,否则模型会直接闷头写代码,评估工具的结论永远用不上;③ 固件包指引的 `sizeHint` 原先把「F1 一代约 293 MB」写死,真机上给 H7 看照样这么讲——现在按系列查 `FIRMWARE_SIZE_HINTS`(2026-10 在 `D:\app\STM32CubeMX\Repository` 直接量的:F1 v1.8.7 = 293.4 MB / 10,778 文件、G4 v1.6.2 = 471.3 MB / 23,089、F4 v1.28.3 = 1,674.0 MB / 43,397、L0 v1.12.4 = 258.4 MB / 17,504、C0 v1.4.1 = 380.6 MB / 21,535),没实测过的系列给 250 MB – 1.7 GB 区间而不是编数字;`cubeMxGuide()` 里的「F1 约 293 MB」也一并去掉。
|
|
1316
|
+
- **还没验证的**:CubeMX 是否接受手工组装的 `Repository` 包(见上);`stm32_route_plan` 在真机上还没跟着一条真实工程走过完整流程;寄存器模板当时仍未落地(用户 2026-10-24 决定:**不预置进插件目录**,改为首次从 GitHub 拉到可检索的缓存目录,之后复用——已由 §13 落地)。
|
|
1317
|
+
|
|
1318
|
+
### 13. 缓存目录 + 下载器 + 寄存器版模板
|
|
1319
|
+
|
|
1320
|
+
- **要求(用户 2026-10-24)**:「寄存器版本文件不能提前放进插件目录,因为后续要拓展至任意 stm32 单片机,不可能每一个都放进插件,可以设置一个缓存目录,每次从网上下载下来模板啊什么的,都放到一个可检索的目录里,这样就只第一次需要下载,后面就复用缓存区模板了。」——所以本期三块:可检索缓存、下载器、寄存器版脚手架,**模板一个字节都不进插件包**。
|
|
1321
|
+
- **取证一(下载源,本机实测 `curl.exe`)**:`raw.githubusercontent.com/.../stm32f1xx.h` **超时(curl 28)不可用**;`github.com` 206、`api.github.com` 206、`codeload.github.com/.../tar.gz` 200 / 1,086,613 B / 2.8 s;`fastly.jsdelivr.net/gh/...` 206 / 0.94 s;`ghproxy.net/https://raw.githubusercontent.com/...` 206 / 1.9 s。于是 `sourceUrls()` 固定四候选顺序:jsDelivr fastly → jsDelivr cdn → raw.githubusercontent → ghproxy。逐文件用 jsDelivr 核过 10 个文件全 200(`core_cm3.h` 109,913 B、`stm32f103xb.h` 842,883 B、`startup_stm32f103xb.s` 9,725 B 等)。
|
|
1322
|
+
- **取证二(ST 上游到底有哪几套文件,直接决定模板清单)**:F1 只有三套,`x8` / `xC` / `xD` 三种写法在 Include 与 startup 目录**全是 404**:`Include/{stm32f103x6.h 832,603 B, stm32f103xb.h 842,883 B, stm32f103xe.h 962,263 B}`、`Source/Templates/gcc/{startup_stm32f103x6.s 9,272 B, startup_stm32f103xb.s 9,725 B, startup_stm32f103xe.s 12,022 B}`。中等容量(C8/CB)归 `xB` 那一组。`F1_STARTUP_BY_DENSITY` 因此是 `{6:x6, 8:xb, B:xb, C/D/E:xe}`,每条直接带 `{startup, define, header}` 三元组,不再拼串。
|
|
1323
|
+
- **实现(六个文件)**:
|
|
1324
|
+
1. `src/engine/cache.ts`:缓存根 `DSH_STM32_CACHE`(支持 `~` 展开)> `%LOCALAPPDATA%\dsh-stm32\cache` > `%USERPROFILE%\AppData\Local\...` > `os.tmpdir()/dsh-stm32-cache`;`index.json` 可检索(`CacheEntry{id,kind,family,label,root,createdAt,totalBytes,files,sources,license}`);`writeCacheIndex` 走 `.tmp` + rename 原子替换;坏 JSON **不抛**——返回空索引 + 一句中文错误(缓存是加速手段,坏了就当没缓存)。
|
|
1325
|
+
2. `src/engine/fetch.ts`:`fetchOne(target, destRoot, {fetchImpl, timeoutMs, signal})` 按 `urls` 顺序试,HTTP 非 2xx / 字节数 < `minBytes`(默认 16)/ 内容前 512 字节像 HTML 都记为该源失败并进 `attempts`;成功走 `.part-<pid>` + rename,不留半截文件;`fetchAll` 并发 3、`onProgress(outcome, done, total)`。**只用全局 `fetch`,零运行时依赖**,测试注入 `fetchImpl`。
|
|
1326
|
+
3. `src/data/cmsis-sources.ts`:`CMSIS_FAMILIES` 目前只有 F1(`cmsis-device-f1@master` + `STM32CubeF1@master` 的 CMSIS Core 头 + `core_cm3.h`);`startupChoiceFor(mcu)` 认 `STM32F103C8T6` 与 `F1:B` 两种写法,**认不出返回 null**(宁可说"这版不支持",也不编一个文件名);`cmsisTemplatePlan(choice)` 产出 10 个 `FetchTarget`,落盘路径按 ST 固件包布局(`Drivers/CMSIS/Device/ST/STM32F1xx/...`、`Drivers/CMSIS/Include/...`),每项带自己的 `minBytes`(头 200、`stm32f103xb.h` 10,000、startup 500…)。
|
|
1327
|
+
4. `src/engine/register-template.ts`:`ensureCmsisTemplate()` 查缓存 → `checkCacheEntry` 全好即 `cacheHit` → 否则 `fetchAll` → 写 `THIRD_PARTY_NOTICES.md`(Apache-2.0 + 两个 ST 仓库地址 + 「本目录是下载缓存,不是插件源码」)→ `upsertCacheEntry`。下载失败时**把整条缓存条目删掉**(半截缓存比没有缓存更糟)。`createRegisterProject()` 复用 `templates/scaffold` 的四个公共文件(`CMakePresets.json`、`.gitignore`、`STM32F103XX_FLASH.ld`、`cmake/gcc-arm-none-eabi.cmake`),CMSIS 从缓存 `cpSync` 整棵 `Drivers`。
|
|
1328
|
+
5. `templates/register/{CMakeLists.txt,Core/Src/main.c}`:`CMakeLists.txt` 只四个占位(`__PROJECT_NAME__` / `__FAMILY_DIR__` / `__STARTUP_FILE__` / `__DEVICE_DEFINE__`);`main.c` 是纯 CMSIS 的 PC13 翻转 + `g_led_blink_count` 计数,`delay_ms` 用 `SysTick->LOAD/VAL/CTRL` + `COUNTFLAG` 轮询,**一个 HAL 符号都没有**。
|
|
1329
|
+
6. `src/tools/cache.ts`(`stm32_cache`,`action: list|verify|fetch|purge`)+ `stm32_project_create` 增 `route: "hal" | "register"`(门禁按路线分流:寄存器版查 `build`、HAL 查 `generate`)。
|
|
1330
|
+
- **两个真 bug(都是 e2e 首次运行才暴露的)**:
|
|
1331
|
+
1. **容量档拼串**:第一版把 C8 拼成 `stm32f103x8.s` / `stm32f1038.h`,四个源全 404。修法见上「取证二」。顺带在下载失败分支加了判断:所有 `attempts` 都是 `HTTP 404` 时提示「上游就是 404,多半是模板清单写错了(插件 bug)」,别让用户去换网络。
|
|
1332
|
+
2. **`system_stm32f1xx.c` 路径错**:`CMakeLists.txt` 里引用 `Core/Src/system_stm32f1xx.c`(那是 CubeMX 生成工程的布局),缓存里的模板在 `Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/system_stm32f1xx.c`,配置阶段直接 `Cannot find source file` + `No SOURCES given to target`。改成直接引用 `Drivers` 路径。
|
|
1333
|
+
- **决策与理由**:
|
|
1334
|
+
- **只比字节数、不比 sha256**:文件来自 GitHub 的 tag/branch,四个源同一份内容;sha256 对每个文件要多读一遍盘,而缓存损坏的典型形态就是"截断/缺失"——字节数足够抓住这两种。真要验完整性,`stm32_cache verify` 报告的 `missing` / `changed` 已经能让人一眼看出问题。
|
|
1335
|
+
- **不照抄 `templates/scaffold/.vscode`**:那份 `launch.json` 里 `svdPath` 是 `D:/JingYu/STM32/...`、`armToolchainPath` / `gdbPath` 是 `D:/app/msys64/ucrt64/bin`(§10 同一类毛病)。寄存器版工程跑在**别人的机器**上,宁可没有 `.vscode` 也不能带着我的路径。
|
|
1336
|
+
- **半截缓存整条删**:缓存命中判据是"文件都在且大小对",半截条目会让后续每次 `checkCacheEntry` 都判不命中却又不重下,变成永久坏状态。
|
|
1337
|
+
- **e2e 实测**:首次 `createRegisterProject` → 1,221 ms、10 个文件下载成功、`templateFiles: 6`、`driverFiles: 10`;紧接着 `cmake --preset Debug` + `cmake --build --preset Debug` → 4 步构建,`reg.elf` 431,076 B,**FLASH 760 B / 64 KB(1.16%)、RAM 1,576 B / 20 KB(7.70%)**;第二次调用 `cacheHit: true`、153 ms,注入的 `neverFetch` 一次都没被调用。
|
|
1338
|
+
- **一次事故(值得单独记)**:用 PowerShell `Add-Content` 往 `test/schema-guard.mjs` 追加中文用例。Windows PowerShell 5.1 的 `Add-Content` 默认按 ANSI(936) 编码写,把一个 UTF-8 文件写成了混合编码,`tools.read` 直接 `invalid UTF-8 text`;随后"用 GBK 读回来再写 UTF-8"的补救把原本正常的整片中文变成不可逆 mojibake。恢复手段是**不碰 git 命令**(git 由用户全权负责):用 Node + `zlib` 直接读 `.git` 对象库(`HEAD` → commit → tree → 逐层解析 `mode SP name NUL 20-byte sha`)把已提交版本 inflate 回来,再补未提交的改动。**落盘规范**:仓库里的中文文件只走 `write` / `edit` 工具,禁止 `Add-Content` / `Set-Content` / `Out-File` / `>` 写文本。
|
|
1339
|
+
- **验证**:新增 `test/cache-units.test.mjs` 10 例(缓存根四种来源与 `~` 展开、坏 JSON、`upsert` 幂等 + `checkCacheEntry` 缺文件/大小不符、`fetchOne` 首源 404 回退次源、网页/过短不算成功、`fetchAll` 并发统计、`startupChoiceFor` 六种写法、`cmsisTemplatePlan` 10 文件与四候选、离线明说 `not-cached`、下载后命中且删文件会重下、`createRegisterProject` 产物齐全 + G431 被拒);`schema-guard` 20 → 22(`stm32_route_plan` 与 `stm32_cache`);套件 18 → 19,用例 186 → **197 pass / 0 fail**(CI 上 195 + 2 skipped)。
|
|
1340
|
+
- **还没验证的**:
|
|
1341
|
+
- `stm32_cache` 与 `stm32_project_create route:"register"` 在真宿主里还没跑过(本段只做了工具级 e2e,用的假 ctx);宿主加载新 `lib/` 需要重启。
|
|
1342
|
+
- 只有 F1 在 `CMSIS_FAMILIES` 里。G4/H7 等系列缺的不是"下哪个文件"的想象力,而是**上游真实文件名**——F1 这次就因为 `x8`/`xC`/`xD` 猜错而四个源全 404,别的系列必须同样先 `curl` 核一遍再补表。
|
|
1343
|
+
- 固件包(`STM32Cube_FW_*`)当时只报告、不下载:`package.xml` 要自造,CubeMX 认不认这种手工组装的 `Repository` 包尚未实测——这一点已在 §14 实测并落地。
|
|
1344
|
+
|
|
1345
|
+
### 14. 固件包下载器(`stm32_firmware_install`)
|
|
1346
|
+
|
|
1347
|
+
- **要解决的问题**:CubeMX 装好不等于有**这一颗芯片**的固件包。安装包本身不带固件包,`<CubeMX 根>/Repository/` 是空的,用户得在包管理器里另下 200–300 MB;离线或慢网机器上这一步经常卡住整条 HAL 路线。
|
|
1348
|
+
- **先定性地问一句「CubeMX 认不认手工组装的包」**(这决定了下载器值不值得做)。取证:
|
|
1349
|
+
- UM1718(`pdftotext -layout` 抽文本)里固件仓库是**单一**路径(Help → Updater settings),没有多目录列表;但脚本命令 `project setCustomFWPath` 可以让**单个工程**指向任意目录(`.ioc` 键 `CustomFwLocation`)。
|
|
1350
|
+
- 真包 `package.xml` 只有 257 B:`<Package DBVersion="2.0"><PackDescription Release="FW.F1.1.8.0" Patch="FW.F1.1.8.7">…</PackDescription></Package>`,顶层再没有任何 manifest / 哈希 / 与下载源绑定的文件。
|
|
1351
|
+
- 对照实验:同一个 `.ioc`、同一套脚本,A 组 `setCustomFWPath` 指向真包、B 组指向自造的同构包(`Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal.c` 末尾塞了注释标记)。两组都生成成功,B 组生成的工程里那条标记**命中**(A 组不命中)→ **CubeMX 认我们组装的包,内容逐字节来自我们目录**。
|
|
1352
|
+
- 顺带挖到一个危险行为:把 `.ioc` 的 `ProjectManager.FirmwarePackage` 改成不存在的包名,CubeMX **不报错**、退出码 0、照样打印 `Code succesfully generated`,只是**不拷 HAL**(只出 Inc/Src)。所以生成成功不能当验收,必须按判据自查——这也正是 `src/engine/scaffold.ts` 的 `resolveFirmwareRoot()` 一直在做的事。
|
|
1353
|
+
- **为什么不能直接解 `STM32CubeF1` 的 tarball**:主仓挂 22 个 git 子模块,`Drivers/CMSIS/Device/ST/STM32F1xx` 与 `Drivers/STM32F1xx_HAL_Driver` 在 zip/tar 里是**空目录**,解出来编译必挂。所以下载器改为拉两个独立源仓(`stm32f1xx-hal-driver`、`cmsis-device-f1`)加 5 个 CMSIS 内核头,自己摆成固件包布局。
|
|
1354
|
+
- **取证(体积与源)**:codeload 的 `stm32f1xx-hal-driver` 818,831 B(顶层 `Inc/` 与 `Src/`)、`cmsis-device-f1` 1,086,613 B(顶层 `Include/` 与 `Source/`),加 5 个内核头,一个包约 2 MB——秒级,不需要断点续传。codeload 的 HEAD 不回 `content-length`(chunked),所以计划模式只能给约 2 MB 的估值,真实字节数装完才知道。仓库名要用规范写法 `stm32f1xx-hal-driver`(下划线旧名会 302)。
|
|
1355
|
+
- **实现(四个文件)**:
|
|
1356
|
+
1. `src/engine/tar.ts`:自写 tar.gz 解包(`extractTarGz`),支持常规文件、目录、ustar `prefix`、pax `x`(取 `path=` 与 `size=`)、GNU 长名 `L`;符号链接与设备文件只计数跳过。**两遍**:先把所有条目校验完(拒绝绝对路径、盘符、含 `..`),全部通过才建目录写文件——第一版边解析边写,踩到 `../escape.txt` 时前面的文件已经落盘,调用方会看到一个看起来解完了的假目录。另有 `maxBytes`(默认 512 MiB)防炸弹。不依赖机器上有没有 `tar`。
|
|
1357
|
+
2. `src/data/firmware-packages.ts`:`FIRMWARE_FAMILIES.F1`(包前缀、版本、HAL 目录、设备目录、内核头清单、两个源码归档的 `mapPath` 规则);`archiveUrls()` 三候选 `codeload` → `ghproxy` → `api.github.com`;`firmwareVersionTags()` 按 `FW.<族>.<x.y.z>` 规则给 `{release: FW.F1.1.8.0, patch: FW.F1.1.8.7}`;`packageXmlText()` 生成与官方同构的 6 行;`verifyFirmwarePackage()` 五项判据(内核头 5 个、HAL Inc 非空、HAL Src 非空、设备 Include 非空、`Source/Templates/gcc` 有 `startup_*.s`)。未接入的族在联网前就返回「插件还不会给 X 自动组装固件包(目前只会:F1)」。
|
|
1358
|
+
3. `src/engine/firmware-install.ts`:`decideTarget()` 三档落点——已有官方包 → `existing`(什么都不做);仓库可写 → `repository`;否则 → 缓存目录 `firmware/<包名>` 并追加「要靠工程级 `CustomFwLocation` 指过去,这个绝对路径会写进 `.ioc`」的 notes(**落点顺序已被 14.1 的真机复验推翻:现在默认落 CubeMX 目录里的 dsh-firmware**)。`firmwareInstallPlan()` 零副作用(计划模式连目录都不建),`installFirmware()` 才下载解包写 `package.xml` 与 `THIRD_PARTY_NOTICES.md` 并自检。**计划模式判可写**要沿 `dirname` 向上找最近存在的祖先再 `accessSync(W_OK)`——Repository 还没建时直接 access 会抛 ENOENT,把可写的根误判成不可写而错落缓存(这个 bug 是测试抓出来的)。
|
|
1359
|
+
4. `src/tools/firmware-install.ts`(`stm32_firmware_install`):`dryRun` 默认出计划,`dryRun: false` 加 `confirm: true` 才真装;真装走 `jobs.start` 后台 job(进度 `handle.append`),`foreground: true` 或没有 jobs 服务时同步。纯 fetch 加 fs,不需要 `subprocess`。
|
|
1360
|
+
- **决策与理由**:
|
|
1361
|
+
- ~~**优先落 Repository 而不是缓存**~~(已被 14.1 否定):`CustomFwLocation` 会把机器绝对路径写进 `.ioc`,换机器或清缓存就失效;而 Repository 是 CubeMX 与插件都直接认的位置。缓存只是仓库不可写时的退路。
|
|
1362
|
+
- **不把已装的包拷进缓存**:同族多版本并存(本机 `Repository` 里 F1 就有 V1.8.5 与 V1.8.7)会让缓存涨到数 GB,且 CubeMX 升级或删包后缓存副本立刻陈旧。缓存里只放寄存器版那套约 1 MB 的 CMSIS 模板。
|
|
1363
|
+
- **自写解包器而不是调系统 `tar`**:单测能用内存造的 tar.gz 完整覆盖(含路径穿越、坏 gzip),也不依赖用户机器上有没有 tar。
|
|
1364
|
+
- **e2e 实测(真网络加真编译)**:`installFirmware({family: F1, target: repository, mode: install})` → `ok: true`、`kind: repository`、**7 个文件 / 2,047 KB / 4,751 ms**、五项判据全过;接着 `createProjectScaffold()` 从这个组装包拷出 14 个工程文件加 **238 个固件文件**;`stm32_generate`(CubeMX 无头,154,298 ms,冷启)落位 6 个 Core 文件;`cmake --preset Debug` 加 `cmake --build --preset Debug` → 19 步构建成功,`fwe2e.elf` 654,232 B,**FLASH 4,704 B / 64 KB(7.18%)、RAM 1,584 B / 20 KB(7.73%)**。整条「下载 → 组装 → 生成 → 编译」在组装包上闭环。
|
|
1365
|
+
- **验证**:新增 `test/firmware-units.test.mjs` 12 例(自带 ustar 构造器 `makeTar` 与 `makeTarGz`;归档里塞 120 KB 随机数据才能过 `minBytes: 100_000`;覆盖解包映射与路径穿越整次失败、坏包、`firmwarePlanFor` 的版本串与文件表、未接入族与错版本、五项判据、计划零副作用、假网络整装、下载失败不许假装成功、已装时零网络、工具契约与 H7 联网前早退);`schema-guard` 22 → 23(19 个工具);套件 19 → 20,用例 197 → **215 pass / 0 fail**(`firmware-units` 后来补到 17 例,见 14.1;CI 上跑 213 加 2 skipped)。
|
|
1366
|
+
- **踩坑记录**:
|
|
1367
|
+
- `scaffold` 只出骨架,`Core/Src/main.c` 要 `stm32_generate` 才生成;拿骨架直接 `cmake --preset Debug` 会报 `target_sources: Cannot find source file: .../Core/Src/main.c`——**不是 bug**,别把它当下载器的问题查。
|
|
1368
|
+
- 手工用 `execFileSync` 跑 CubeMX 时 120 s 不够、240 s 也可能不够:冷启动一次实测 154 s,加上初始化能到 4 分钟以上。要么走插件的 `stm32_generate`(默认 600 s),要么把 `run_code` 的 `timeoutMs` 一起放宽。
|
|
1369
|
+
- 一次被 kill 的 CubeMX 会在目标目录里留下半个 `Drivers`(这次是 61–62 个 HAL 源文件),重跑会补齐;但别拿文件数对不对当成功判据——用 `verifyFirmwarePackage()`。
|
|
1370
|
+
- **还没验证的**:
|
|
1371
|
+
- 只有 F1 在 `FIRMWARE_FAMILIES` 里,别的系列要先 `curl` 核过真实仓库名与顶层目录(F1 这次就因下划线旧名 302 踩过)。
|
|
1372
|
+
- ~~`repository` 落点在**真 CubeMX 安装目录**里还没跑过~~ —— 已跑过(真 Repository 装 1.8.8),结论是**会被 CubeMX 静默忽略**,见 14.1。`cache` 落点加 `CustomFwLocation` 的全链路不做了:那条路会挂死,改用 `setCustomFWPath`。
|
|
1373
|
+
- ~~CubeMX 认组装包这一条是用 `setCustomFWPath`(工程级)验的,插件的 `stm32_generate` 目前并不发这条命令~~ —— **已补齐**:`stm32_generate` 现在按 `.ioc` 的 `ProjectManager.FirmwarePackage` 找包,并在脚本里发 `project setCustomFWPath <包目录>`(见 14.1)。
|
|
1374
|
+
|
|
1375
|
+
#### 14.1 真机复验与三处更正(2026-10-25)
|
|
1376
|
+
|
|
1377
|
+
把上文的「组装包放进真 Repository → 直接生成」这条链路拿到真机上跑,结论与设计时的假设相反,据此改了三处代码。
|
|
1378
|
+
|
|
1379
|
+
**① 落进真 Repository 的包会被 CubeMX 静默忽略。** 把组装好的 `STM32Cube_FW_F1_V1.8.8`(HAL 源文件里带标记)放进 `D:/app/STM32CubeMX/Repository`,`.ioc` 写 `ProjectManager.FirmwarePackage=STM32Cube FW_F1 V1.8.8`,再带 `LibraryCopy=1` 重跑 `stm32_generate`(173,557 ms 与 123,121 ms 两次都 `ok`):工程里 `Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal.c` 是 **20,257 B**(官方 1.8.7 的大小),我们那份带标记的是 **20,293 B**,标记一次都没出现 —— CubeMX 认不出这个版本名,无报错地退回它自己认识的 1.8.7。旁证:CubeMX 日志里 `CubeFinder database FW Pack versions=[…]` 是**线上**清单,不含自造版本;`~/.stm32cubemx` 下也没有本地包注册记录。
|
|
1380
|
+
|
|
1381
|
+
**② 只改 `.ioc` 指自定义目录会挂死。** 改 `ProjectManager.CustomerFirmwarePackage=<包目录>` 加 `DefaultFWLocation=false` 后重跑:`ok:false`、**421,600 ms「CubeMX 生成超时」**,HAL 一个都没拷(多半弹了迁移对话框,无头模式没人应答)。
|
|
1382
|
+
|
|
1383
|
+
**③ 唯一被证实有效的机制是脚本命令。** `project setCustomFWPath "<包目录>"`。现在 `buildGenerateScript()` 多一个 `firmwareDir` 参数,非空就在 `config load` 之后、`generate code` 之前插这一行(路径含空格会加引号)。找包交给 `locateFirmwarePackage()`:`<root>/Repository` 与 `<root>/dsh-firmware` 都找,包名精确匹配优先、其次版本号大的、同版本优先官方;`firmwareNeedFromIoc()` 从 `.ioc` 读 `ProjectManager.FirmwarePackage`,缺这条时退回 `Mcu.CPN` 推族加该族默认版本。
|
|
1384
|
+
|
|
1385
|
+
**落点改为 `<CubeMX>/dsh-firmware`。** `decideTarget()` 现在是:显式 `targetDir` → `existing` → `cubeMx`(插件自建,与 Repository 并列,不动官方包)→ 写不进去才退回用户缓存 `cache`。`target:"repository"` 保留,但 notes 会明说「CubeMX 不会自动认这个版本号,生成靠 setCustomFWPath」。这样生命周期跟着 CubeMX、整目录可搬、不同盘也不怕跨卷。
|
|
1386
|
+
|
|
1387
|
+
**顺带加的防线。** `parseGenerateLog()` 现在把 `Unknown command` / `Unrecognized command` / `Invalid command` 之类判为**失败** —— 万一日后 CubeMX 改命令名、`setCustomFWPath` 被忽略,也不会拿到「成功但用错固件包」的结果(这种结果比直接失败更难查)。
|
|
1388
|
+
|
|
1389
|
+
**报告与卡片。** `GenerateReport` 增 `firmwareDir` / `firmwarePackage` / `firmwareSource`(`repository` | `dsh-firmware` | 空),工具卡片多一行「固件包:…(CubeMX 仓库 / 插件的 dsh-firmware 目录)」;找不到包时 notes 里写找过哪些目录,以及可以用 `stm32_firmware_install` 装到 `dsh-firmware` 下。
|
|
1390
|
+
|
|
1391
|
+
**验证。** `test/firmware-units.test.mjs` 12 → **18 例**(选址缺陷修复后又加到 22,见 §14.2)(新增 `buildGenerateScript` 发不发那行命令与插入位置、`parseGenerateLog` 未知命令判失败、`firmwareNeedFromIoc` 两种来源、`locateFirmwarePackage` 的优先序与不完整包过滤、`firmwareInstallPlan` 三种落点且计划模式不建目录、`resolveFirmwareRoot` 在 `Repository` 缺失时回落到 `<CubeMX>/dsh-firmware`);`schema-guard` 同步改期望;套件 20、用例 210 → **216 pass / 0 fail**(§14.2 修完是 **220**)。
|
|
1392
|
+
|
|
1393
|
+
### 14.1 真机验收(2026-10-25):装到 dsh-firmware → 脚手架 → 生成 → 编译
|
|
1394
|
+
|
|
1395
|
+
**装。** `installFirmware({family:"F1", version:"1.8.8", cubeMxRoots:["D:/app/STM32CubeMX"], mode:"install"})` → `ok`、`targetKind` **cubeMx**、目录 `D:/app/STM32CubeMX/dsh-firmware/STM32Cube_FW_F1_V1.8.8`、**7 个文件 / 2047 KB**、五项判据全过。`Repository` 保持原样(9 个官方包),官方地面一点没动。
|
|
1396
|
+
|
|
1397
|
+
**脚手架。** `stm32_project_create route:"hal"` → `templateFiles` 14、`driverFiles` 238,`firmwareRoot` 指向 dsh-firmware 那份 —— 这是本段补的 `resolveFirmwareRoot()` 双层查找(先 `Repository`、再 `dsh-firmware`)在起作用;原来只查 `Repository`,装到 dsh-firmware 的包会被判「找不到固件包」。`.ioc` 里 `ProjectManager.FirmwarePackage=STM32Cube FW_F1 V1.8.8`、`LibraryCopy=1`。
|
|
1398
|
+
|
|
1399
|
+
**生成。** `runGenerate`(注入真 spawn 的 `SubprocessService`):第一次 394,518 ms,`ok` 但 **CubeMX 没把 HAL 拷回工程**(先删掉了工程里的 `stm32f1xx_hal.c` 做基线,结果没回来);第二次不删(200,194 ms)→ `ok`、`firmwareDir` 指向 dsh-firmware 目录、`firmwareSource` 为 `dsh-firmware`、`verdict.ok` true、`errors` 空,notes 写着「本次指定固件包:…(来源:插件的 dsh-firmware 目录)- 脚本里用 project setCustomFWPath 传的,不写进 .ioc。」
|
|
1400
|
+
|
|
1401
|
+
**编译。** `cd demo/.verify-fw2; cmake --preset Debug; cmake --build --preset Debug` → 配置 58.5 s、19 步构建、`fw2.elf`:**RAM 1,584 B / 20 KB(7.73%)、FLASH 4,704 B / 64 KB(7.18%)**。整条链在真机成立。
|
|
1402
|
+
|
|
1403
|
+
**新发现的限制(还没改)。** 只靠 `.ioc` 的 `ProjectManager.LibraryCopy=1` **不会**让 CubeMX 从 `setCustomFWPath` 指的自定义包把 HAL 拷进工程(上面第一次实验就是证据);§14 那次能拷,是因为脚本里另外发了 `SetCopyLibrary "copy all"`,而插件现在**不发**这条命令。对 `project_create route:hal` 够用(Drivers 由脚手架提供),对「CubeMX GUI 建的、没拷库的工程」不覆盖 —— 待定:`buildGenerateScript()` 在工程缺 `<Drivers>/<族>_HAL_Driver/Src` 时补发它,或至少在报告里提示。
|
|
1404
|
+
|
|
1405
|
+
### 14.2 修:自动选址把固件包往不存在的 Program Files 里塞(2026-10-25)
|
|
1406
|
+
|
|
1407
|
+
**现象。** 宿主里调 `stm32_firmware_install({family:"F1", version:"1.8.8"})`,计划落点是 `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/dsh-firmware/STM32Cube_FW_F1_V1.8.8`,而本机 CubeMX 实际装在 `D:/app/STM32CubeMX`(`C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` 根本不存在)。计划模式零副作用,所以没写坏东西,但真装会往一个要管理员权限的地方撞。
|
|
1408
|
+
|
|
1409
|
+
**两条根因,缺一不可。**
|
|
1410
|
+
1. **候选根顺序**:`resolveSearchConfig` 的自动发现把 `DEFAULT_CUBEMX_ROOTS` 里那些「别的机器上的默认安装位置」也追加进来,且排在本机真装的那份前面;`decideTarget()` 是按列表顺序撞第一个「可写」的根,于是先撞上 Program Files 那条。
|
|
1411
|
+
2. **可写性判据在 Windows 上不成立**:plan 模式用 `accessSync(最近一个已存在的祖先, constants.W_OK)` 探测。Windows 上 `access(W_OK)` 只看文件的**只读属性**,不看 ACL —— `C:/Program Files` 对普通用户是只读的,但它的只读属性是关的,于是被判成「可写」。install 模式没这个毛病(它是真 mkdir + 写探针文件)。
|
|
1412
|
+
|
|
1413
|
+
**修法(`src/engine/firmware-install.ts`)。**
|
|
1414
|
+
- 新增 `isProtectedSystemDir(dir, env)`:把 env 里的 `ProgramFiles` / `ProgramFiles(x86)` / `ProgramW6432` / `ProgramData` / `SystemRoot` 归一成小写正斜杠前缀,落在其下即算受保护。`dirWritable()` 的 plan 分支一旦发现最近存在的祖先受保护,直接返回不可写并说明原因,不再信 `access(W_OK)`。
|
|
1415
|
+
- **刻意不把整块系统盘 `C:/` 算进来**:`%TEMP%`、`%LOCALAPPDATA%` 都在 C: 上,算进来会把所有临时目录判成不可写(第一版加了 drive-root 逻辑,测试立刻红,这正是它该红的理由)。
|
|
1416
|
+
- 新增 `orderCubeMxRoots(roots)`:本机 `existsSync` 为真的排前面(组内保序),不存在的排后面;`decideTarget()` 改用它。这样「哪台机器的默认路径」不会再压过「真有 CubeMX 的那份」。
|
|
1417
|
+
|
|
1418
|
+
**验证。** `test/firmware-units.test.mjs` 18 → **22 例**(`isProtectedSystemDir` 的真/假两个方向、`orderCubeMxRoots` 的排序、plan 在 `[不存在的根, 真根]` 下必须选真根且不建目录、根不存在且祖先受保护时必须退回用户缓存);套件 20、用例 216 → **220 pass / 0 fail**。宿主级复验(重启后 `stm32_firmware_install` 的 targetDir 应变成 `D:/app/STM32CubeMX/dsh-firmware/...`)还没做。
|
|
1419
|
+
|
|
1420
|
+
### 15. 批 1:审计里的数据安全问题(2026-10-25)
|
|
1421
|
+
|
|
1422
|
+
按 `docs/logic-audit.md` 的四批计划,批 1 先修「会把用户文件写坏或把假成功当真」的那几条。全部改动都在离线套件里可回归:套件 20 → **21**,用例 220 → **244 pass / 0 fail**(CI 上 242 + 2 skipped)。
|
|
1423
|
+
|
|
1424
|
+
**B2 源码按 UTF-8 读写,GBK 工程被写坏。** 新增 `src/engine/text-file.ts`:BOM → `utf8-bom`,严格 UTF-8 解码成功 → `utf8`,严格 GB18030 解码成功 → `gb18030`,都不行 → `unknown`(拒绝改动)。关键取舍:Node 只有 GB18030 **解码器**、没有编码器(`TextEncoder` 只支持 UTF-8),所以 GBK 文件不做整份重编码,而是 `lineStarts()` + `replaceLineRange()` **按字节拼接** —— 没改的行原字节照抄,只把新增行按 ASCII 插进去;新增内容含非 ASCII 时直接拒绝写入。`code-patch.ts` 与 `generate.ts` 的写盘都改用它,BOM 与 CRLF 保留,`unknown` 文件一个字节都不动。
|
|
1425
|
+
|
|
1426
|
+
**A6 flash 的 SWD 守卫不再静默放行。** `findIocFile()` 只认唯一一个 `.ioc`,0 个或多个都返回 `null`;原来这条分支直接返回 `blocked:false` 加两个空数组,守卫等于不存在。现在给出两条 notes:「SWD 守卫没生效:工程里没有 .ioc / 有 N 个 .ioc 分不清」+ 手工核对 PA13/PA14 的做法;`runFlash` 也把非 blocked 时的 notes 真的带进报告(以前丢掉)。另加 `stm32_flash` 的 `iocPath` 参数,多 `.ioc` 工程可以点名。
|
|
1427
|
+
|
|
1428
|
+
**A7 readWords 的值不再错位。** gdb 失败的命令只打一行 `Cannot access memory`、不产生 `$N`,按出现顺序对齐会让后面的值整体前移、还标 `ok:true`。现在每个地址前先 `echo ===DSH:<address>===`,`parseMarkedWords()` 只在各自那一段里找值;没有标记时(极老 gdb)才回退旧解析。
|
|
1429
|
+
|
|
1430
|
+
**A5 写盘不再是未捕获异常。** `regs_read` 的 openocd 临时脚本、`generate` 的 CubeMX 脚本与产物写回全部包 `try/catch` 转成干净失败;工程只读时给「工程目录可能只读」而不是堆栈。产物读不了编码时用新动作 `skipped-encoding`(schema enum 同步),旧文件编码认不出时**不覆盖**,宁可少做一步也不毁用户的中文注释。
|
|
1431
|
+
|
|
1432
|
+
**A1 `project_create` 覆盖前先备份。** `preflightTarget()` 把「工程名 → 目录非空 → hal 且已有同名 `.ioc` 直接拒绝(指向 `stm32_ioc_plan` / `stm32_ioc_apply`)」提到门禁之前;`backupBeforeOverwrite()` 只备份**真正会被覆盖**的文件(14 个模板目标 + startup + system,register 路线是 `CMakeLists.txt` / `main.c` / 4 个公共文件),备份失败即 `ok:false` 且一个字节都不写;写盘中途失败按「本次新建」精确回收,原目录存在时只 `rmdir` 空目录,绝不递归删用户文件。
|
|
1433
|
+
|
|
1434
|
+
**A2/A12 缓存索引不再丢数据。** 索引读坏时先改名成 `index.json.broken-<ts>`(rename 失败退 copy,两者都失败才拒绝覆盖)再以空索引重建;`writeCacheIndex` 的 tmp 名带 pid + 序号 + 随机后缀,首次 rename 失败不再先删旧索引,而是把旧索引改名成 `index.json.bak-<ts>` 再搬,二次失败把备份原样放回并抛 `CacheIndexWriteError` —— 抛错时旧索引逐字节未动。
|
|
1435
|
+
|
|
1436
|
+
**A4 tar 解包只认白名单。** 条目类型只接受常规文件(0 / NUL / 空)与目录(5),x / g / L / K 作元数据前置消费,1 / 2 / 3 / 4 / 6 / 7 一律跳过并记进 `skippedPaths`(以前符号链接会被当 0 字节文件写下并计入成功);`isSafeRelative()` 补拒反斜杠、冒号、绝对路径与空段 / 点段;声明大小超出实际数据判为截断包,整次失败不留半截文件。
|
|
1437
|
+
|
|
1438
|
+
**A3 `.ioc` 引脚表保序。** 原来重写 `Mcu.PinN` 时按 `.Signal` 过滤,PB2/BOOT1 这类只有 `.Mode` 的引脚会被剔除、留下孤儿键。现在复制原顺序、只追加新引脚,且顺序没变时一个 `Mcu.Pin*` 键都不碰。
|
|
1439
|
+
|
|
1440
|
+
**B3 用户 PATH 读失败不再当成没有 Path。** `UserPathRead` 增 `readable`:读失败(spawn 出错、超时、非 0 且不像找不到、输出认不出)→ `readable:false`,此时规划阶段就失败并给手工命令,`applyUserPath()` 不写空串备份、不发 `reg add /f`;只有 reg 明确回答没有这个值才允许新建。这条以前会把整条用户 PATH 覆盖成一条目录。
|
|
1441
|
+
|
|
1442
|
+
**测试。** 新增 `test/text-encoding-units.test.mjs` 9 例(编码四态、GB18030 解码、编码器拒绝非 ASCII、字节级替换保留 GBK 注释、unknown 拒改且字节不变、BOM 保留);`session-units` +2(标记分段不错位、无标记时空结果)、`flash-units` +1(守卫不生效要说清楚)、`cache-units` +2、`firmware-units` +2、`ioc-plan-units` +2、`install-units` +2、`scaffold-patch-units` +4。
|
|
1443
|
+
|
|
1444
|
+
### 16. 批 2:只在用户机器上暴露的可用性问题(2026-10-25)
|
|
1445
|
+
|
|
1446
|
+
批 1 修的是任何机器都会错的写坏数据与假成功;批 2 修的是**在开发机上看不出来**的那一类:开发机的 msys64 同时躺在用户级与机器级 PATH 里、CubeMX 装在 `D:/app`、工程路径纯 ASCII、系统代码页恰好不影响 grep。换台干净机器或中文 Windows,这些地方就露。逐条见 `docs/logic-audit.md` 的 B1/B4–B10/B12/B13/B15;本段只记取证与取舍。
|
|
1447
|
+
|
|
1448
|
+
**B1 模板把开发机绝对路径塞进每个新工程。** `templates/scaffold/vscode/launch.json` 原来写死 `svdPath: D:/JingYu/STM32/cmsis-svd-stm32/stm32f1/STM32F103.svd`、`armToolchainPath`/`gdbPath: D:/app/msys64/ucrt64/bin`,`scaffold.ts` 原样拷进用户的 `.vscode/` —— 别人按 F5 必挂,还顺手泄露我的用户名。现在模板只留占位符(`__GDB_PATH__` / `__ARM_TOOLCHAIN_PATH__` / `__CMAKE_PATH__` / `__SVD_PATH__`),由新增的 `src/engine/vscode-config.ts` 在写盘时按**本机探测结果**填充:`detectVscodeFill(binDirs)` 在 `binDirs + PATH` 里找 gdb 与 cmake,`fillVscodeTemplate()` 有值就替换、**没值就把整行删掉**并记进 `dropped`(cortex-debug 会把空字符串当有效路径,写空串比不写更糟),`scaffold` 再把 `describeDroppedPlaceholder()` 的人话塞进 `report.warnings`。SVD 一律不填:插件没有 SVD 来源,模板里留注释教用户自己加一行。
|
|
1449
|
+
|
|
1450
|
+
**B6 模板 settings.json 绑死 ST 官方 VS Code 扩展。** 原来是 `cube-cmake`、`-DCMAKE_COMMAND=cube-cmake`、`stm32cube-ide-clangd.path=cube` 加 `${env:CUBE_BUNDLE_PATH}/gnu-tools-for-stm32/14.3.1+st.2/...` —— 没装 ST 扩展的用户在 VS Code 里配置与索引全废。现在只留通用三项:`cmake.cmakePath: __CMAKE_PATH__`(探测到的系统 cmake,探测不到就整行删)、`cmake.preferredGenerators` 为 Ninja、`cortex-debug.variableUseNaturalFormat`。
|
|
1451
|
+
|
|
1452
|
+
**B4 子进程不注入 env,只有找可执行文件用 binDirs。** 这条最阴:`stm32_env_install` 刚把工具装好、`config.json` 里的 `binDirs` 也写对了,但 DSH 宿主进程的 `PATH` 还是旧快照 —— 门禁 `locateFast` 只 `existsSync` 判齐全,紧接着 `cmake --preset Debug` 里那句裸 `arm-none-eabi-gcc` 找不到。开发机永远不暴露,因为 `ucrt64/bin` 早就在系统 PATH 里。修法:新增 `src/engine/tool-env.ts` 的 `envWithBinDirs(binDirs, base)`(去重去空、`binDirs` 用 `path.delimiter` 拼在原 `PATH` 前、Windows 上只保留一个大小写正确的 `Path` 键),`RunRequest` 加 `env?` 并透传到两处 `subprocess.spawn`,`runBuild()` 把 `envWithBinDirs(config.binDirs)` 传给 configure 与 build 两次调用。为什么不是只给 cmake 一个绝对路径:cmake 还要再调 gcc/g++/ninja/objcopy/size,它们是 cmake 的子进程,得靠 `PATH`。
|
|
1453
|
+
|
|
1454
|
+
**B13 门禁快路径只判文件存在。** 快路径(全部候选 `existsSync` 命中就放行、零 spawn)会把下载不完整/被杀毒隔离/架构不对的 exe 也当成齐全。现在命中后对**该能力的主组件**(build→gcc、flash→openocd、debug→gdb、generate→cubemx-java)跑一次轻量版本命令(`smokeTarget()`,同样 60 s 缓存,`resetGateCache()` 一起清);跑不通就按缺件处理,并在 `warnings` 里写明「文件在(路径),但版本命令没跑通:…」—— 区分没装与装了但跑不起来,这两种给用户的下一步完全不同。
|
|
1455
|
+
|
|
1456
|
+
**B15 hal 路线的门禁用了 generate 能力。** `route:"hal"` 只拷 CMake 文件与 `Drivers/`,不需要 `STM32CubeMX.exe` 与它的内置 JRE,但门禁按 `generate` 能力拦人,缺 JRE 的用户会被要求去装 CubeMX。现在 hal 路线**不挂门禁**(缺固件包由 `scaffold` 自己按三条判据报,并列出找过的路径),register 路线仍按 `build` 能力检查(它要真编译),`gate.message` 降级成 `warnings` 一行。
|
|
1457
|
+
|
|
1458
|
+
**B7 斜杠命令把带空格的路径切成两段。** `/stm32-build "C:/Program Files/My Proj"` 以前解析成 `C:/Program`,报工程目录不存在让人莫名其妙。`tokenizeCommandLine()` 改成一次扫描的引号感知切词:引号内不切、顺手剥引号、**不做反斜杠转义**(Windows 路径里反斜杠太多,当转义符会把路径吃掉),未闭合引号明确报错;`--flag` 判定加 `!token.quoted`,所以引号里的 `--clean` 是目录名不是开关。
|
|
1459
|
+
|
|
1460
|
+
**B8 斜杠命令不走门禁。** 命令是人已经决定要干的动作,所以这里用 `envCheck: "warn"`:缺件照样跑,但把 `gate.message` 放在卡片第一行(`withGateWarning()`,`kind` 原样保留 —— 命令已经执行完,改成 error 会误导)。接了 `/stm32-flash`、`/stm32-debug`(三处返回都包)、`/stm32-build`;`/stm32-stop` 只关会话、`/stm32-doctor` 本身就是体检,不接。顺序是**先门禁再掐探针**,与工具层 `stm32_flash` 相反 —— 缺件时不该先去动别人的调试会话。
|
|
1461
|
+
|
|
1462
|
+
**B9 reg.exe 的输出是 GBK,却被当 UTF-8 读。** `readUserPath()` 与 `readRegistryInstallDirs()` 都按 `utf8` 读 `reg.exe` 的管道输出。中文 Windows 上 `REG_SZ` 里的中文会变成 U+FFFD:注册表发现直接失效(`existsSync` 必失败),更糟的是把解坏的旧 PATH 用 `reg add /f` **写回**,用户整条 PATH 永久损坏。修法两条:新增 `decodeRegistryText()`(先严格 UTF-8、再严格 GB18030,都失败就 `ok:false` 且 `text` 留空;string 入参含 U+FFFD 直接拒绝),`readUserPath` 新增 `queryUserPathBytes()` —— 用 `cmd.exe /d /s /c "reg.exe query … > dump.txt 2>&1"` 把**原始字节**落盘再 `readFileSync` 成 Buffer(宿主的 `CollectedReader` 只给 string,拿不到字节),解不出来按读不到处理、拒绝写注册表。为什么不用 powershell 改 `[Console]::OutputEncoding`:多一次进程启动、多一层引号转义,而 EDR 环境下 cmd 与 powershell 的存活概率没区别。
|
|
1463
|
+
|
|
1464
|
+
**B5 安装自检走 PATH 兜底,pacman 失败被改判成功。** 自检用 `probeAll`,而 `probeTarget` 在目录里找不到时会回退 `subprocess.resolveExecutable`(≈PATH)—— 于是 PATH 上本来就有 gcc 能让 `verifyState.ok` 变 true,接着把 pacman 的 `failed` 补偿成 `done`,报告写安装完成。修法:`ProbeOptions` 加 `allowPathFallback?: boolean`(默认 true,既有调用不变),自检传 `false`;再加 `isInsideDir()` 过滤器 `strayTools` —— 只有五个工具**都落在目标 `binDir` 里**才允许那条补偿判定。`message` 相应补一句能跑的那几个不在 `<binDir>` 里、这个目录并没有装好。
|
|
1465
|
+
|
|
1466
|
+
**B12 install 分支跳过受保护目录判定。** `dirWritable()` 的 plan 分支会拒 `Program Files`(见 §14.2),但 `create=true` 的分支直接 `mkdir` 加写探针 —— 冒烟时正是这样往不存在的 `C:/Program Files/.../dsh-firmware` 里规划落点。现在 `decideTarget()` 的 `repository` 与 `cubeMx` 两支都先过新增的 `hasCubeMxExe(root)`(只判 `<root>/STM32CubeMX.exe`;比 `search-roots.looksLikeCubeMxRoot` 宽松是**故意**的 —— 那个还要 `jre/bin/java.exe`,是给无头生成用的,缺 JRE 但装了 CubeMX 的机器也该能落 `dsh-firmware`),假根跳过并写 note。
|
|
1467
|
+
|
|
1468
|
+
**B10 装到 cache 或自定义目录的包,generate 结构上看不到。** `locateFirmwarePackage()` 只扫 `<root>/Repository` 与 `<root>/dsh-firmware`,而 `stm32_firmware_install` 在 CubeMX 根写不进去时会落到 `<cacheRoot>/firmware` 或调用方指定目录,随后 `nextStep` 又让用户直接调 `stm32_generate` —— 必然找不到包。修法:`locateFirmwarePackage` 增 `extraDirs`(来源扩成 `repository | dsh-firmware | cache | custom`,`firmwareSourceLabel()` 统一中文标签),装成功时往 `<cacheRoot>/firmware/installed.json` 记一条落点,`firmwareExtraDirs(env)` 把 `<cacheRoot>/firmware` 与记录里的非 CubeMX 落点拼起来交给生成。`tools/generate.ts` 的 `firmwareSource` enum 与来源标签同步扩到五值。
|
|
1469
|
+
|
|
1470
|
+
**B10 的漏网之鱼(原条目没写到)。** `scaffold.resolveFirmwareRoot()` 同样只扫 CubeMX 根 —— 装到缓存的包在**建工程**那边也看不见。现在它和 `generate` 共用同一个 `firmwareExtraDirs()`(先写在 `generate.ts` 里,本段移到 `firmware-install.ts`,避免两处各写一份迟早对不上),并支持 `extra.dir` 本身就是包目录(显式 `targetDir` 指到包上)。三条判据抽成 `isUsableFirmwareRoot()` 共用。
|
|
1471
|
+
|
|
1472
|
+
**测试。** 新增 `test/vscode-units.test.mjs` 9 例(模板里没有 `D:/app`/`D:/JingYu`/`C:/Users`、launch 保留 gdb 与 toolchain 占位符、settings 解绑 ST 扩展且去注释后是合法 JSON、`detectVscodeFill` 的 binDirs 命中与 `Path` 兜底与都没有时三项空串、`fillVscodeTemplate` 填值/删行两态且删行后仍可解析、`describeDroppedPlaceholder` 四条人话加未知占位符、`envWithBinDirs` 前置与保留原 PATH 与不改入参、`Path` 与 `PATH` 只留一个键、空 `binDirs` 不凭空造 PATH);`commands-units` 6 → 11(引号带空格路径、引号内另一种引号、普通多参数不变、未闭合引号报错且命令拒绝执行、缺件时三条命令以工具链警告开头 —— 最后这条在 `try/finally` 里临时把 `STM32_BIN_DIRS` 指到空目录并关掉自动发现与配置,否则开发机上永远齐全,用例等于没测);`toolchain-units` 22 → 24(快路径只给主组件跑一次版本命令、文件在但跑不通不算齐全且 `missing` 只有 gcc、smoke 缓存 60 s 内只 spawn 一次);`scaffold-patch-units` 15 → 17(hal 缺 CubeMX 时报找不到固件包而不是缺 STM32CubeMX、固件包在下载缓存里也能被脚手架找到并拷出 `Drivers/`);`firmware-units` 24 → 28(`extraDirs` 找缓存落点且只给 CubeMX 根时找不到、`installed.json` 记录、假根不建 `dsh-firmware`、install 分支祖先受保护不建目录);`install-units` 8 → 10(PATH 上能跑的 gcc 不许把 pacman 失败改判成功且 `--version` 调用次数为 0、GBK 字节的中文 PATH 解得对且写回幂等);`search-roots-units` 11 → 12(`decodeRegistryText` 四态)。套件 21 → **22**,用例 244 → **269 pass / 0 fail**(CI 上 267 加 2 skipped)。
|
|
1473
|
+
|
|
1474
|
+
**还没验证的。** ① 真中文 Windows 上 `cmd.exe` 重定向落 `dump.txt` 的语义只在假 subprocess 加人工拼的 GBK 字节上验过,没在实机跑过一条真 `reg query`;EDR 拦截导致 `dump.txt` 缺失、且旧值含中文的组合没有专门用例(行为落在安全侧:不写注册表、给手工命令)。② 非中日英代码页(CP932/CP1251)的字节可能能被严格 UTF-8 解码但语义是乱码,零依赖识别不出来,与改前一致。③ `decodeRegistryText` 与 `text-file.detectEncoding` 是两套同类探测,合并要连 `text-file.ts` 一起改,留到批 4。④ 宿主级复验(重启后按 F5 看 `.vscode` 是否真能调试、`/stm32-build` 带空格路径)还没做。
|
|
1475
|
+
|
|
1476
|
+
### 17. 批 3/批 4:假成功、状态一致性与一致性清理(2026-10-25)
|
|
1477
|
+
|
|
1478
|
+
批 3(10 条)修「报告说成功但其实是假的、状态谁拥有说不清」;批 4(23 条)修剩下的文案、边界与清理问题。全部改动的可回归证据在离线套件:套件 22 → **23**,用例 269 → **296 pass / 0 fail**(CI 上 294 + 2 skipped)。逐条编号见 `docs/logic-audit.md` 的「建议修复批次」。
|
|
1479
|
+
|
|
1480
|
+
**A10 生成成功的判据。** §14 的实测已经证明:`.ioc` 里的 `FirmwarePackage` 指向一个 CubeMX 不认识的版本时,它**不报错**、照样打印 `Code succesfully generated`,只是不拷 HAL。`parseGenerateLog()` 又规定「有成功行就把 ERROR 全部降级成噪音」,两件事叠起来就是稳定的假成功。新增 `assessGenerateProducts(projectDir, appliedCount)`:没有任何产物落位 / 缺 `Core/Src/main.c` / 工程有 `Drivers/*_HAL_Driver` 但其 `Src` 下没有 `.c`(说明包没被认到)→ 直接 `fail()`,并且这步排在**写生成缓存之前**,下次不会用缓存把假成功复读一遍。`ok = successLine !== ""` 的老判据原样保留,产物判据是额外的必要条件。
|
|
1481
|
+
|
|
1482
|
+
**A25 flash 的成功判据。** `openocd` 在成功路径上也会打 `Error:` 行(无效 ACK 之类),原来任何 `Error:` 都判失败,等于成功也报错。现在先算 `succeeded = programmed && verified`:成功时命中 `Error:` 的行进 `noise`(首条写进 notes,别让用户以为没看见),失败时照旧进 `errors`。判定 `ok` 的条件没放松(`exitCode === 0` + `programmed` + `verified` + 无 errors)。
|
|
1483
|
+
|
|
1484
|
+
**A26 debug_run 的 `ok` 与 `errors` 自相矛盾。** 原来只看 `spawnError === null`、没超时、断点命中,完全无视 gdb 退出码与 `probe.errors`,于是报告写「调试快照完成」同时挂着一串 `Cannot access memory`。现在 `ok` 追加 `gdbOutcome.exitCode === 0 && probe.errors.length === 0`。
|
|
1485
|
+
|
|
1486
|
+
**A9 会话归属:turn/end 不能掐别人的调试会话。** 原来 `session/event` 收到任何 `turn/end` 就无条件 `debugSessions.stop()`。现在 `SessionStartRequest` 与 `InternalSession` 都带 `owner`(工具层填 `exec.agent.id`),`stop(reason, { requireOwner })` 在「会话有 owner 且与 requireOwner 不同」时不关并说明原因;`index.ts` 用新增的 `callerIdOf(event, session)` 依次读 `agentId` / `owner` / `agent.id` / `session.id`,**取不到就按旧行为无条件关**(宁可多关一次也别把探针留着不放 —— 单会话场景本来就没这个问题)。
|
|
1487
|
+
|
|
1488
|
+
**A27 探测被取消时不写 60 s 缓存。** 慢路径 `for (const target of wanted)` 里 `break` 之后仍然 `probeCache.set(cacheKey, ...)`,于是一次取消会让「缺 gcc」这个错误结论被缓存一分钟。现在 `signal.aborted` 时直接返回 `ok:false` 加「工具链检查被取消:这次没探完,也不缓存结果」,`cacheHit` 保持 false。
|
|
1489
|
+
|
|
1490
|
+
**A28 配置写回的 CAS。** `readToolchainConfig()` 记录 `mtimeMs`,`writeToolchainConfig(config, { expect })` 在 mtime 变了时返回 `conflict` 而不覆盖;`updateToolchainConfig()` 先读、冲突就重读重写一次(两次都冲突才失败)。tmp 文件名加 `randomBytes(4)`,两个进程同时写也不会互相踩。安装器与「写 cubeMxRoot」都走这条路。
|
|
1491
|
+
|
|
1492
|
+
**A29/A30 取消与 pacman 失败的人话。** 取消时 `exitCode` 是 `null`,原来会落进「退出码 1 失败」分支并把暂存目录删掉 —— 现在是 `ExtractOutcome.cancelled` + `EXTRACT_CANCELLED`,暂存留着方便续跑,文案写「取消≠失败」。pacman 失败时补两条对症提示:`db.lck` 存在给出 `rm -f /var/lib/pacman/db.lck`,出现 conflicting files 给出 `--overwrite`。
|
|
1493
|
+
|
|
1494
|
+
**A21 job 卡片不再是计划快照。** 真装返回的 `report` 原来是 `plan` 的副本(`mode: "install"` 但步骤全是 `pending`、`targetDir` 是计划值),看一眼以为没动。现在返回 `runningReport`:步骤 `pending`、抬头「安装进行中」,真正的结果在 job 输出里。
|
|
1495
|
+
|
|
1496
|
+
**A36 取消桥接。** `exec.signal` 的 abort 监听在 `jobs.start()` 返回后立刻 `removeEventListener` —— 工具调用一返回,取消就再也传不进 job。现在监听一直留到 job 的 `done` 结算(`.finally` 里摘),`done` 补 `.catch` 把异常转成 `failed` 而不是永远 `running`(`firmware-install` 的 job 这条也一起补了)。
|
|
1497
|
+
|
|
1498
|
+
**A14 CubeMX 单飞锁要看进程活没活。** 原来只看 `pid` 加「30 分钟内一律占用」:进程崩了要等半小时,或者用户手删 `.dsh-stm32/lock.json`。现在锁里多写 `host`,`isProcessAlive(pid)` 用 `process.kill(pid, 0)` 真探一次(`EPERM` 按活着算);同机且进程不在了就接管,并在进度里说明「接管了上次没释放的单飞锁(…进程已不在/来自另一台机器)」;另一台机器的锁仍然不抢。
|
|
1499
|
+
|
|
1500
|
+
**B11 pdsc 索引不再卡在 `.dsh-parked`。** 生成期间把第三方包索引整体 rename 走,还原依赖 `generate.ts` 的 `finally`;断电或被杀就留在停放态,而还原分支以前遇到「CubeMX 重建了非空 pdsc」只会让人手工合并。新增 `mergeDirectoryInto()` 逐项 rename 并回(目标已存在算 kept、失败计数),搬空后删停放目录,notes 写「已把停放的索引并回 N 项」。
|
|
1501
|
+
|
|
1502
|
+
**A11/A15 下载与替换的原子性。** 暂存目录改成唯一名 `.dsh-download-<pid>-<ts>` 并在下次启动时清扫陈旧目录(`sweepStaleTemps`),主流程补 `catch`;落盘改成「旧文件改名 `.old-<pid>-<seq>` → 新文件 rename → 成功删 `.old`/失败把旧文件还原」,中途失败不会留下半个文件。
|
|
1503
|
+
|
|
1504
|
+
**A22 单位。** `formatBytes()` 用 1024 进制却标 MB,41,060,000 字节显示成 39.2 MB。现在十进制(43060392 B → **43.1 MB**),与 GitHub 页面上写的大小一致。
|
|
1505
|
+
|
|
1506
|
+
**A23 「159 个包」是文件数不是条目数。** 索引目录里一个包每个版本占一个 `.pdsc`,159 个文件归并成 67 个包;原来报告写「收录 159 条」但实际只能匹配 67 条。现在 `XCUBE_CATALOG_ENTRY_COUNT = XCUBE_PACK_CATALOG.length`,`XCUBE_CATALOG_SOURCE` 由两个常量拼;`scripts/gen-xcube-catalog.mjs` 的 `render()` 同步改成同一布局(否则重跑生成器会把修复回退),并用 3 个假 pdsc 验证过输出。
|
|
1507
|
+
|
|
1508
|
+
**A24 缓存条目的 notices 也是文件。** 写进缓存条目的 `files` 列表与计数时漏了 `THIRD_PARTY_NOTICES.md`(10 个文件报成 10、磁盘上是 11);重下时上一份先改名 `.stale-<ts>` 再删,删失败不阻塞新版本落盘。
|
|
1509
|
+
|
|
1510
|
+
**A32 下载内容真校验。** 只比字节数抓不到「返回了一个 200 的漂亮错误页」。`FetchTarget` 加 `markers[]`,每个 CMSIS 目标声明自己必须含的特征串(`system_stm32f1xx.h` 的守卫是 `__SYSTEM_STM32F1XX_H`,第一版只写 `__STM32` 全挂);tar 先查 gzip 魔数 `1f 8b` 与条目数,解出 0 个条目直接判失败。
|
|
1511
|
+
|
|
1512
|
+
**A38 缓存完整性用 sha256。** `CacheFile` 加 `sha256`,`checkCacheEntry()` 不再只比字节数(大小相同但内容被改过的缓存会被继续用)。
|
|
1513
|
+
|
|
1514
|
+
**A8/A34 缓存工具的边界。** `stm32_cache` 的 `else` 兜底原来会落进 `purge`,未知 action 现在返回 `ok:false`;清空整份缓存要求 `confirm:true`(不传只报「要删什么」);`action: fetch/verify` 把 `exec.signal` 真的传下去,取消能停。
|
|
1515
|
+
|
|
1516
|
+
**A13 下一步提示按落点分档。** 装到 `cache` / 自定义目录时 `nextStep` 还写着「直接调 stm32_generate」—— 现在 `nextStepFor()` 按 `targetKind` 给不同的话(缓存落点会说明生成靠 `setCustomFWPath` 指过去)。`existing` 分支仍是旧文案,属于已知未整理项。
|
|
1517
|
+
|
|
1518
|
+
**A16 `route_plan` 的四处。** `isConcurrencySafe` 从 true 改 false(它要探工具链);`verdict === "unclear"` 时不再跑门禁(没有外设可评估时查工具链没意义),`guides` 相应为空、`toolchainCapability` 为 `"none"`;`ok` 不再被 `gate.ok` 拽住(寄存器路线不需要 CubeMX);本机没探测到 CubeMX 根时给 `fallbackRepository: ""` 并说明「固件包落位要你自己填」。
|
|
1519
|
+
|
|
1520
|
+
**A17/A18/A31 契约与参数。** skill 正文把 `plan_id` 改成 `planId`(仓库里没有 `plan_id` 这个参数名,模型照抄就会失败);`stm32_ioc_apply` 回滚时 `appliedChanges` 记 0(回滚不是应用变更)并新增 required 字段 `rolledBack`;`ioc_apply` / `ioc_plan` / `debug_session` / `debug_eval` 四处 `execute(rawArgs: X | undefined)` 加 `const args = rawArgs ?? {}`,宿主传 undefined 时不再 TypeError。
|
|
1521
|
+
|
|
1522
|
+
**A19 `regs_read` 借用会话时的参数说明。** `configFile` / `adapterSpeed` 在借用已有调试会话时**不生效**(openocd 是会话里那个),原来静默忽略;现在写进 notes 并给「先 stm32_debug_stop 再读」的做法。
|
|
1523
|
+
|
|
1524
|
+
**A20 死代码。** `debug.ts` 里 `REGISTER_NAMES` 只做 `some()` 再 `continue` 的空循环、`tools/generate.ts` 里 `report` 变量只写不读的两处全部删掉。
|
|
1525
|
+
|
|
1526
|
+
**A35 job 路径丢了 `released` 说明。** 同步路径会在 notes 里写「已释放探针」,job 路径把那句话丢了;现在 job 的 `run` 一开始就 `handle.append(released)`,`build` 与 `generate` 都补上。
|
|
1527
|
+
|
|
1528
|
+
**A37 安装指引的分支。** `install-guides.ts` 用 `in` 判族名(`"constructor"` 会命中原型链)改成 `Object.hasOwn`;`guideFor()` 原来只认 `cubemx` / `cubemx-java`,缺件矩阵里真实的第 7 个组件 `firmware` 取不到指引,现在支持它(`guidesFor` 调用不变)。
|
|
1529
|
+
|
|
1530
|
+
**B14 新装的 MSYS2 先整体升级一次。** 基包解压后立刻 `pacman -S --needed <5 包>` 在久未整体升级的镜像上会解不开依赖(实测「无法满足依赖关系」)。现在空库路径先 `pacman -Syu --noconfirm` 再装;已有一份完整 MSYS2 的机器**不**替用户升级(只 `-Q` 查、缺件才 `--needed`)。
|
|
1531
|
+
|
|
1532
|
+
**B16 缺件时不该收走别人的探针。** `releaseProbeFor()` 原来排在门禁之前:`stm32_flash` 因缺 openocd 被拦下,却顺手把别人开着的调试会话关了。现在先门禁、`block` 分支直接返回,之后才释放探针(斜杠命令侧是相反顺序,见 §16 B8)。
|
|
1533
|
+
|
|
1534
|
+
**B17 长路径复制。** `Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc/…` 这样的层级碰上深目录就超 260 字符。新增 `src/engine/fs-longpath.ts`:`toLongPath()` 给绝对路径加 `\\?\`(UNC 走 `\\?\UNC\`,非 win32 原样),`copyFileLong()` / `copyTreeLong()` 失败时给中文说明(两侧路径、`ENAMETOOLONG`、改短目录的建议);`scaffold.ts` 的整树复制与两处单文件复制全部改走它,`mkdirTracked` 变薄壳保持 `register-template` 的调用签名。
|
|
1535
|
+
|
|
1536
|
+
**B18 CubeMX 脚本里的中文路径。** 脚本是 UTF-8 写的,而 CubeMX 是 Java 程序,读脚本用平台默认字符集(中文 Windows = GBK),路径里有中文就乱码。现在启动参数加 `-Dfile.encoding=UTF-8`,不动脚本内容、也不给用户添 BOM。
|
|
1537
|
+
|
|
1538
|
+
**D1(宿主验收发现,不在审计清单里):填进 JSON 的 Windows 路径没转义。** §16 的占位符填充把 `D:\app\msys64\ucrt64\bin` 原样插进 `launch.json`,反斜杠在 JSON 字符串里是转义符 —— 生成的 `.vscode` 不是合法 JSON,VS Code 直接打不开。`fillVscodeTemplate()` 现在先把值里的反斜杠统一成正斜杠再替换(VS Code 与 CMake 都认正斜杠,且不再需要关心 JSON 转义)。引擎级复验:`createProjectScaffold` 建出的 `launch.json` / `settings.json` 剥注释后 `JSON.parse` 成功、反斜杠计数 0、`cmake.cmakePath` 是 `D:/app/msys64/ucrt64/bin/cmake.exe`。顺带一提:验证这一步的队友还确认了 GBK 文件经 `stm32_code_patch` 后中文逐字节不变(含反证:编码认不出的文件被拒且零改动)、register 覆盖前备份目录的 tag 是 `-register`、hal 且已有同名 `.ioc` 会被 preflight 拒绝且零写入、含空格目录 `demo\.accept space\reg proj` 里能正常编译出 elf。
|
|
1539
|
+
|
|
1540
|
+
**测试。** `engine-units` +1(CubeMX 说成功但 HAL 目录为空不算成功)、`flash-units` +1(成功序列齐全时 `Error:` 行进 noise)、`session-units` +2(别人的会话不关 / owner 未知照旧关)、`toolchain-units` +1(abort 后不写 60 s 缓存)、`thirdparty-units` 改写 1 例(停放索引逐项并回)、`xcube-units` +1(生成脚本重跑不会把条目数写死)、`vscode-units` +1(填进 JSON 的路径必须合法)、`scaffold-patch-units` +5(长路径三态 + 回滚 `rolledBack` + 四个工具接受 undefined)、`ioc-units` +2(`guideFor` 的 firmware 分支与 `Object.hasOwn`)、`install-units` 到 17、`cache-units` 到 16、`firmware-units` 到 30。最终 **23 套件 296 pass / 0 fail**(CI 294 + 2 skipped)。
|
|
1541
|
+
|
|
1542
|
+
**宿主级烟测(2026-10-25,重启后新 lib)。** 五项全部通过:
|
|
1543
|
+
① `stm32_firmware_install({family:"F1", version:"1.8.8"})` 的计划落点是 `D:/app/STM32CubeMX/dsh-firmware/STM32Cube_FW_F1_V1.8.8`、`targetKind: "cubeMx"` —— §14.2 那条选址缺陷在宿主里确实修好了(以前会规划到不存在的 `C:/Program Files/...`)。
|
|
1544
|
+
② `stm32_cache({action:"purge"})` 在有 1 个条目、1.0 MB 且没带 `confirm` 时 `ok:false`,message「要清空整个缓存(1 个条目、共 1.0 MB)必须带 confirm:true;只想删一个条目就给 id。什么都没删。」——A8 生效且零副作用。
|
|
1545
|
+
③ `stm32_project_create({route:"hal", firmwarePackage:"STM32Cube_FW_F1_V1.8.8"})` 建出 14 个工程文件 + 238 个固件文件,`firmwareRoot` 指向 `dsh-firmware` 那份(scaffold 双层查找在宿主里生效)。
|
|
1546
|
+
④ 该工程的 `.vscode/launch.json` 与 `settings.json` 剥注释后都是合法 JSON、反斜杠计数 0、占位符 0、不含 `D:/JingYu`(`D:/app` 会出现,那是本机探测到的工具链真路径,不是模板写死)——D1 修好。
|
|
1547
|
+
⑤ `stm32_ioc_plan`(`ProjectManager.HeapSize` 0x200 → 0x800)+ `stm32_ioc_apply` 写入 1 个键变化,再 `stm32_ioc_apply({rollbackFrom})` 回滚:`appliedChanges: 0`、`rolledBack: true`,`.ioc` 回到 0x200 —— A18 生效。
|
|
1548
|
+
|
|
1549
|
+
**还没做的。** ② `firmware-install` 的 `existing` 分支 `nextStep` 还是旧文案。③ 只有 F1 在 `FIRMWARE_FAMILIES`,其他族要 curl 核实仓库名。④ `SetCopyLibrary "copy all"` 要不要补发仍未决(见 §14.1)。
|
|
1550
|
+
|
|
1551
|
+
## 18. 设置面板:宿主 web-api + 浏览器端 bundle(2026-10-25)
|
|
1552
|
+
|
|
1553
|
+
用户要的是「别只靠命令行改配置」:把 `~/.dsh-stm32/config.json` 搬到 DSH 的 **设置** 页里,能读、能改、能探测、能一键装。结论是先做**面板**(配置 + 探测 + 安装),不做卸载与目录浏览。
|
|
1554
|
+
|
|
1555
|
+
### 18.1 先摸清宿主的两条契约(决定技术路线)
|
|
1556
|
+
|
|
1557
|
+
**客户端插件不是插件里的一段 React,而是一个"外壳直接执行的 bundle"。** 宿主读已启用 Loader 条目 `package.json` 里的 `dsh.client`(要求 `platform: "web"`)与 `exports["./client"]`,把那个文件以 `/plugins/<包名>/client.js` 提供给浏览器。所以:
|
|
1558
|
+
|
|
1559
|
+
- 不需要打包器。`dsh-skill-mcp-panel` 的构建就是 `tsc -p tsconfig.json && node scripts/strip-client-export.mjs`,产物直接是 `lib/client.js`;
|
|
1560
|
+
- 产物形状固定:`window.__ModuleLoader__.load({ id: "<包名>", factory: (require) => { var module = { exports: {} }; ...; return module.exports; } })`,`exports.apply` 是入口、`exports.inject` 是客户端服务依赖;
|
|
1561
|
+
- `factory(require)` 只认外壳种子:`react`、`react/jsx-runtime`、`@deepseek-ai/dsh-client-ui-primitives`。要用别的模块得在 `dsh.client.external` 里声明——我们只用 `react`,没碰这一层。
|
|
1562
|
+
|
|
1563
|
+
**设置页的挂载点是 slot,不是路由。** 官方账户页的写法是 `ctx.effect(() => ctx.slots.inject("settings.section", () => ctx.slots.register({ name: "settings.section", id: "account", order: -10, label: () => t("nav"), locale: "settings.account", inject: () => operations }, AccountSection)), "<label>")`。`label` / `locale` / `inject` 都是可选的:我们只给 `{ name, id: "stm32", order: 40, label: () => "STM32 工具链" }`,不传 `locale`(中文写死)也不传 `inject`(组件自己 fetch)。
|
|
1564
|
+
|
|
1565
|
+
**顺带纠正一条早期的错误判断**:profile 的 `cordis.patch.yml` 里 `ui-settings` 的 `config.enabled: false` 是「代码工作工具开关」这条偏好,**不是**把设置页关掉。设置页一直存在。
|
|
1566
|
+
|
|
1567
|
+
**为什么客户端不声明 `dsh.client.inject`**:`dshmarket` 与 `dsh-skill-mcp-panel` 都列了 `@deepseek-ai/dsh-client-ui-layout` / `-sidebar` 之类的客户端服务,因为它们要用侧栏与主题;我们只需要 `slots`,它由外壳核心提供。**也不需要往 `cordis.patch.yml` 加 client loader 行**:这两个已装好的客户端插件同样只是 `dsh.profile.bundles` 里的一项 + 包自己的 `dsh.client` 声明(对比它们的 `package.json`:`dsh.bundle.patch` + `dsh.client.platform`,patch 里没有它们的 loader 条目)。
|
|
1568
|
+
|
|
1569
|
+
### 18.2 宿主侧:HTTP 而不是 remote / configForms
|
|
1570
|
+
|
|
1571
|
+
面板要读写的配置在 `~/.dsh-stm32/config.json`,**不在**宿主 settings 命名空间里——`ctx.configForms` 只对后者有效;走 typert 的 `ctx.remote` 又要另加一层协议定义与类型生成,对三个按钮的页面不值。所以照 `dshmarket` 的做法用宿主的 `webServer` 服务:
|
|
1572
|
+
|
|
1573
|
+
`register(route: { kind: "exact" | "prefix"; path: string; handler: (IncomingMessage, ServerResponse) => void | Promise<void> }): () => void`
|
|
1574
|
+
|
|
1575
|
+
分两层落地(`src/engine/web-api.ts` + `src/engine/web-routes.ts`):
|
|
1576
|
+
|
|
1577
|
+
- **web-api.ts(纯逻辑,可离线单测)**:`configSnapshot` / `saveConfig` / `capabilitiesOf` / `summarizeProbe` / `probeTools` / `installPlan` / `installStart` / `installTaskState` / `handleWebApi` / `resetInstallTasks`,六条路由 = `GET /dsh-stm32/api/config`、`POST .../config/save`、`POST .../probe`、`POST .../install/plan`、`POST .../install/start`、`GET .../install/state`;
|
|
1578
|
+
- **web-routes.ts(薄适配)**:`ctx.inject(["webServer"], scope => ...)` 里对每条路由 `server.register({ kind: "exact", path, handler })`,只负责拼 URL、读请求体(上限 1 MB)、写 JSON(`cache-control: no-store`)。宿主没组合 `webServer`(纯 CLI)时静默跳过。
|
|
1579
|
+
- `src/types.ts` 新增 `WebServerService`,request/response 用 `any`:asar 里的宿主包**没有 .d.ts**(`node_modules/@deepseek-ai/*` 下 d.ts 数为 0),类型只能按 `dshmarket/src/routes.ts` 的用法自写。
|
|
1580
|
+
|
|
1581
|
+
**安全边界写在 web-api 里而不是面板里**(面板是浏览器代码,谁都能改):`packages` 拒绝以 `-` 开头的名字(否则等于把 `pacman` 变成任意标志注入)与含空白 / `"'|&;<>` 的名字;`binDirs` 必须是字符串数组;`saveConfig` 的空补丁直接 400(不然会写出一个"看起来保存了"的假成功);`installStart` 没有 `confirm: true` 一律拒。安装任务是进程内 `Map`(留最近 20 个、每个日志尾巴 200 行),真装复用 `planOrInstallMsys2`,与 `stm32_env_install` 同一个安装器。
|
|
1582
|
+
|
|
1583
|
+
### 18.3 浏览器端:手写纯 JS
|
|
1584
|
+
|
|
1585
|
+
`client/client.js`(674 行)三张卡:**装在哪**(读配置 / 改 `msys64` `cubeMxRoot` `binDirs` / 保存)、**缺什么**(探测 + 四项能力徽章 + 逐项路径版本与 `hint`)、**装工具链**(出计划 → 二次确认 → `install/start` → 轮询 `install/state` 到结束)。`scripts/copy-client.mjs` 把它原样复制到 `lib/client.js`;`package.json` 只加四处(`exports["./client"]`、`files += "client"`、`build` 串上复制脚本、`dsh.client.platform = "web"`),零新依赖。
|
|
1586
|
+
|
|
1587
|
+
不做 TS/JSX:这个文件的正确产物就是它自己;写成 TS 只会多一层「tsc 决定产物路径」的中间层,还要额外引入 jsx 运行时配置。
|
|
1588
|
+
|
|
1589
|
+
**队友桩测逮到一个真缺陷**:安装结果块原来用 `taskId === "" ? null : …` 判渲染,而轮询结束时组件会清掉 `taskId` 去重读配置——于是「安装成功 / 失败」连同日志整块从面板消失。改成 `(taskId !== "" || installState !== null)` 才渲染,任务号那一行单独判别。
|
|
1590
|
+
|
|
1591
|
+
### 18.4 测试与文档
|
|
1592
|
+
|
|
1593
|
+
新增 `test/web-api-units.test.mjs`(9 例):配置快照(无文件 → `ok:false`、路径仍给出)、保存后读回且 `binDirs` 由 `msys64` 推出、四类非法输入都在动手前拒掉且不创建文件、能力归纳(缺 gdb 时 `debug:false` 而 `build:true`、`missingRequired` 只收必需项)、分发层 405 / 404 / 坏 JSON 400 / 缺 `taskId` 400、`confirm` 门槛(直接调与走 HTTP 都拒、且不登记任务)、探测与安装计划的入参校验、路由表六条无重复。`test/run-units.mjs` 的 `suites` 加一行。
|
|
1594
|
+
|
|
1595
|
+
**24 套件 305 pass / 0 fail**(CI 303 + 2 skipped)。README / README_EN 的计数与新增小节「设置面板(GUI)」同步。
|
|
1596
|
+
|
|
1597
|
+
**还没验证的**:面板在真 GUI 里的渲染与三步操作(要重启 DSH 后在 **设置 → STM32 工具链** 里点),以及宿主是否自动发现 `link:` 安装包里的 `dsh.client`(按 `dshmarket` / `dsh-skill-mcp-panel` 的同形安装推断会自动,重启后看 `/plugins/dsh-stm32/client.js` 能不能取到即可)。
|
|
1598
|
+
|
|
1599
|
+
## 19. 安装计划只报缺件:计划模式也要真的看一眼本机(2026-10-25)
|
|
1600
|
+
|
|
1601
|
+
**用户的反馈**(面板上线后第一句):「我电脑已经有完整工具链了,安装计划应该只显示缺少的吧」。当时卡片写的是「把 MSYS2 装到 D:/app/msys64(来源:配置里的 msys64),再补 5 个组件;安装包 43.1 MB(需要下载)」,7 个步骤全 pending,用量估算「43.1 MB + 121 MB / 磁盘约 491 MB」——而这台机器上 5 个组件、`usr/bin/bash.exe`、用户 PATH、`config.json` 全都已经就位。
|
|
1602
|
+
|
|
1603
|
+
**根因是"计划零副作用"被理解得太宽。** 早期实现为了绝对安全,计划模式只做纯计算:不读 `pacman -Q`、不跑版本命令,于是它对"已装了什么"一无所知,只能按最坏情况(全新安装)出文案。真正的边界应该是「不写」而不是「不看」——`pacman -Q` 只看、`gcc --version` 只跑、`reg query` 只读,都不改变系统。
|
|
1604
|
+
|
|
1605
|
+
### 19.1 现在计划模式会做的只读动作
|
|
1606
|
+
|
|
1607
|
+
- `isMsys2Root(msys64)` + `usr/bin/bash.exe` 存在 → 真跑一次查询(优先 `usr/bin/pacman.exe -Q <5 包>`,没有才 `bash -lc`;与真装第 4 步同一个命令),`parsePacmanQuery` 得出 `installed` / `missing`;问不了(spawnError / 超时 / pacman 自己报错)就标 `pacmanUnknown`,**不编缺件清单**,并在 `notes` 里写明原因;
|
|
1608
|
+
- `binDir` 存在 → `probeAll(..., { binDirs: [binDir], allowPathFallback: false })` 只跑 `VERIFY_IDS` 那五个版本命令(不越过目标目录去 PATH 上找,B5 的规矩照样守);`verify.ok` 与「缺 X」直接进卡片的第 6 步,`report.verify` 不再是恒 `{ok:false, tools:[]}`;
|
|
1609
|
+
- `configMatches`:现配置的 `msys64` 与 `binDirs` 对得上、`packages` 全含 → 第 7 步标 skipped「配置已经是这个样子,不用改」;
|
|
1610
|
+
- `download`:已有 MSYS2 时恒为「`bytes: 0`」(安装包根本不会碰);
|
|
1611
|
+
- PATH 那一步复用已有的 `reg query` 读(只读一次,用于预告「会不会重复写」)。
|
|
1612
|
+
|
|
1613
|
+
### 19.2 文案按"实际要做什么"分四档
|
|
1614
|
+
|
|
1615
|
+
| 现场 | 首句 | 第 4 步(pacman) |
|
|
1616
|
+
| --- | --- | --- |
|
|
1617
|
+
| 已装齐 | **只回一句**「工具链完整,不需要装任何东西:5 个组件都能跑,PATH 与配置都已就位(D:/app/msys64/ucrt64/bin)。」——`steps: []`、`notes: []`、`nextStep: ""`,不列步骤也不贴 notes | (不出现) |
|
|
1618
|
+
| 已有 MSYS2、缺 N 个 | 「计划(还没动手):复用 … 里已有的 MSYS2,只补 N 个组件(缺 …);不用下载安装包,已装的 K 个不动、也不升级。」 | `pending`:「先 pacman -Q 问过一遍:缺 N 个(…);将跑 pacman -S --noconfirm --needed <缺的包>(已装的 K 个不动,也不升级)」 |
|
|
1619
|
+
| 已有 MSYS2、问不出装没装 | 「计划(还没动手):复用 … 里已有的 MSYS2;计划里没问出这 5 个组件装没装(pacman 超时或起不来),真装时会先 pacman -Q 问一遍,只补缺的,已装的包不动、也不升级。」 | `pending`:「计划里没问出来(pacman 超时或起不来):真装时会先 pacman -Q 问一遍,只补缺的包…」 |
|
|
1620
|
+
| 全新 | 原文案(下载安装包 + 补 5 个组件) | 原文案(整机空库时先 `pacman -Syu` 再补,不做 `-Sy` 后立刻 `-S` 的局部升级) |
|
|
1621
|
+
|
|
1622
|
+
**为什么完整时连步骤都不列**:把「没有可做的事」画成七行「已跳过」+ 三条 notes,卡片比真要装的还长,用户第一反应是「还有一堆动作在排队」。所以 `nothingToDo && verifyOk` 时直接返回紧凑结果(`steps: []` / `notes: []` / `nextStep: ""`),浏览器端 `client/client.js` 在 `steps.length === 0` 时也不再渲染「目标:… · 包:… · 下载:…」那行和步骤列表。另有一处兜底:`tools/env-install.ts` 在计划 steps 为空时用新导出的 `msys2StepSkeleton()` 补出 7 步骨架,真装 job 的「安装中」卡片照样列得出步骤(A21 的断言依赖这一点)。
|
|
1623
|
+
|
|
1624
|
+
**CubeMX 不在那 5 件里**:编译 / 烧录 / 调试都不需要它,但 HAL 路线要用它生成代码。所以紧凑卡片在 `cubemx` 与 `cubemx-java` 两项都没找到时补一句:「要写 HAL 库程序还需要从 ST 官网装 STM32CubeMX(含内置 JRE,约 1.5 GB,https://www.st.com/en/development-tools/stm32cubemx.html);纯寄存器程序不需要它。」——否则「工具链完整」会被读成「HAL 工程也能直接生成」。
|
|
1625
|
+
|
|
1626
|
+
`usageNote(facts, …)` 同步四档:已装齐 →「不用下载任何东西(MSYS2 与 5 个组件都已在本机)」;缺件 →「不用下载安装包;只补 N 个包,pacman 下载约 …」;全新 → 原公式。`nextStep` 也分档,已装齐时直接给「去看 `stm32_env_probe` 或 `stm32_build`,要换一份 MSYS2 就传 `targetDir`」,不再劝人确认安装。
|
|
1627
|
+
|
|
1628
|
+
### 19.3 现场实测又逮到一层:pacman 比版本命令慢得多
|
|
1629
|
+
|
|
1630
|
+
第一版计划问包状态用的是 `bash -lc "pacman -Q …"` 加 15 s 预算(直接照抄版本命令的 `PROBE_TIMEOUT_MS`)——在这台机器上**一律超时**,于是计划又退回「缺 5 个」,看起来和没改一样。实测:`bash.exe -lc "pacman -Q <包>"` 要 **11.0 s**(`-lc` 会起一遍 profile),直接跑 `D:/app/msys64/usr/bin/pacman.exe -Q` 要 **6.5 s**(首跑含安全软件扫描)。两条改法:
|
|
1631
|
+
|
|
1632
|
+
- 优先直接跑 `<msys64>/usr/bin/pacman.exe -Q <包…>`(存在才用),没有才退回 `bash -lc`——省掉 shell 与 profile;
|
|
1633
|
+
- 单独的 `PACMAN_QUERY_TIMEOUT_MS = 60_000`,不再挤占版本命令那份预算。
|
|
1634
|
+
|
|
1635
|
+
再加一个新事实 `pacmanUnknown`:问不出来(超时 / pacman 自己报错且一条都没解析出来)时**不再按「全部未装」编清单**——卡片改说「计划里没问出这 5 个组件装没装(pacman 超时或起不来),真装时会先 `pacman -Q` 问一遍,只补缺的,已装的包不动、也不升级」,用量估算也只说「缺几个包要等真装时才知道」。编一份看起来精确的假清单比不给清单更糟。
|
|
1636
|
+
|
|
1637
|
+
### 19.4 真机复验(2026-10-25,引擎级直调 lib)
|
|
1638
|
+
|
|
1639
|
+
同一台机器、同一份配置(`~/.dsh-stm32/config.json` → `msys64: D:/app/msys64`),`planOrInstallMsys2({ mode: "plan" })` 现在的输出:
|
|
1640
|
+
|
|
1641
|
+
- `ok = true`、`steps = []`、`notes = []`、`nextStep = ""`、`download.bytes = 0`、`verify.ok = true`(tools 5 项全 found);
|
|
1642
|
+
- 卡片全文只有一句:「工具链完整,不需要装任何东西:5 个组件都能跑,PATH 与配置都已就位(D:/app/msys64/ucrt64/bin)。」
|
|
1643
|
+
- 对照:缺件 / pacman 问不出来 / 全新安装时仍走详细卡片(步骤 + 用量 + nextStep),因为那时每一步都有信息量。
|
|
1644
|
+
|
|
1645
|
+
### 19.5 测试
|
|
1646
|
+
|
|
1647
|
+
`install-units` 17 → **21 例**,按加入顺序:①「已有完整 MSYS2 + 5 个组件 → 说『什么都不用装』、`download.bytes` 为 0」;②「只缺 1 个包 → 只说 `openocd`、不列已装的 4 个」;③「pacman 问不出来(超时 / 报错)→ 不猜缺哪个,只说真装时会先问」;④「缺 CubeMX → 紧凑卡片补一句 HAL 提示,装了就不补」。既有那例「计划里的 pacman 步骤说的是真会跑的事」跟着改了断言:计划模式允许**一条**只读查询,但绝不能出现 `pacman -S` / `-Sy`。
|
|
1648
|
+
|
|
1649
|
+
**24 套件 318 pass / 0 fail**(CI 316 + 2 skipped)。README / README_EN 的计数同步到 318。
|
|
1650
|
+
|
|
1651
|
+
**还没验证的**:重启 DSH 后在面板里点「生成安装计划」,确认卡片首句变成「什么都不用装」。
|
|
1652
|
+
|
|
1653
|
+
## 20. 发布形态三连修:mpu_armv7 的 marker、npm 吞 .gitignore、盘根 mkdir(2026-10-25)
|
|
1654
|
+
|
|
1655
|
+
用户在另一台机器(阿里云 ECS、无 CubeMX、无 USB)实测暴露的三条「作者本机测不出来」的问题,全部是发布/环境形态才炸:
|
|
1656
|
+
|
|
1657
|
+
**Q1 mpu_armv7.h 被 marker 误杀(100% 复现,与网络无关)。** `cmsis-sources.ts` 给 5 个内核头共用 `[__CMSIS,__CORE_,__MPU_]`,但上游 V5.0.4 的 `mpu_armv7.h` 是 ARM 原版,真实守卫是 `ARM_MPU_ARMV7_H`(没有前导下划线)——一个都不命中,四条下载链路全通也必失败。改为按文件各配真实守卫(`__CORE_CM3_H` / `__CMSIS_COMPILER_H` / `__CMSIS_GCC_H` / `__CMSIS_VERSION` / `ARM_MPU_ARMV7_H`)。**测试侧同一个坑**:`cache-units` 的 `markerFor()` 按文件名猜 "`#ifndef __MPU_ARMV7_H`",恰好撞上旧 markers 的 `__MPU_`,等于一直在测假世界——同步改成真实守卫表,并新增回归用例(真守卫内容必须能落盘)。
|
|
1658
|
+
|
|
1659
|
+
**Q2 npm 打包永远排除 .gitignore(所有 npm 用户 100% 复现)。** `.gitignore` 同时是 npm 的忽略过滤器,永远进不了 tarball;而 `register-template.ts` 把它列为**必需**文件,缺失即整次失败,报错还让用户"重新安装插件"——npm 用户重装是同一个包,死循环。用户决定**不改名、只做容错**:`.gitignore` 移出硬检查与复制循环,缺失时继续建工程 + 一句 warning("工程功能不受影响,git 状态会多出 build/;想干净就自己建一个内容为 build/ 的 .gitignore");scaffold 路线同样处理;"重新安装插件"文案改为指向插件版本号反馈。两条路线各加一例"缺失时 ok:true + warning + 其余文件齐全"的测试(测试里临时把真实模板的 .gitignore 改名、finally 恢复)。
|
|
1660
|
+
|
|
1661
|
+
**Q3 盘根 mkdir EPERM(插件自设的雷)。** `targetDir=C:/msys64` 是插件自己建议的默认装法,而 parent 是盘根 `C:/`,Node 的 `mkdirSync(盘根, {recursive:true})` 在 Windows 抛 EPERM。新增 `isDriveRoot(dir)`(导出,纯函数)与 `ensureParentDir(parent)`:盘根走 `existsSync` 校验、其余才 mkdir。install-units 加 isDriveRoot 单测(含"推荐默认 C:/msys64 的 parent 必须被判为盘根"的反向断言)。
|
|
1662
|
+
|
|
1663
|
+
**Q4 USB/探针形态诊断(doctor 分级)。** 云服务器物理上没有 USB 口,与"没插板/线只供电/驱动异常/被占用"是四种完全不同的回答。新增 `diagnoseUsb(pnputilText)`(纯函数,四分类:no-usb / no-dap / driver-error / ok,另有 unknown 兜底)与 `usbDiagnosis(subprocess)`(跑只读 `pnputil /enum-devices /connected`,失败不阻塞)。**编码教训**:中文系统 pnputil 字段名是 GBK("实例 ID" 读出来是乱码),任何依赖字段名的解析都会失效——最终只认行内 ASCII 本体(`USB\\VID_`、`USB\\ROOT_HUB`)。no-usb 判定进 blockers(它阻塞烧录且无解),no-dap/driver-error 进 notes,ok 也给一句"探针在线"。DoctorReport 与工具 outputSchema 新增 `usb` 字段,渲染加一行。doctor-regs-units +5 例。真机复验:本机(有 USB、无 CMSIS-DAP)正确报 no-dap 而不是 no-usb。
|
|
1664
|
+
|
|
1665
|
+
**测试。** cache-units 16 → 17(真守卫回归)、scaffold-patch-units 22 → 24(.gitignore 缺失两条路线各一例)、install-units 21 → 22(isDriveRoot)、doctor-regs-units 5 → 10(四分类 + 空文本)。**24 套件 318 pass / 0 fail**(CI 316 + 2 skipped)。
|
|
1666
|
+
|
|
1667
|
+
**发布顺序**:npm pack --dry-run 人工核对 → 版本 0.1.2(package.json + lock 两处 + 两 README 各两处)→ npm publish(盯 PUT 201/202)→ 模拟用户验收(删缓存 + 新 profile 装 tarball + register/hal 各建一次 + doctor 看 USB 话术)。
|
|
1668
|
+
|
|
1669
|
+
## 21. 阿里云实测后的五档清单:让"别人的机器"也能从零跑到烧录(2026-10-25)
|
|
1670
|
+
|
|
1671
|
+
**背景。** 用户在一台阿里云 Windows ECS(有 MSYS2、无 CubeMX、无 USB 口)上照 README 从零走了一遍,除了 §20 那三条 100% 复现的 P0,还提了五条:①发布形态没人验过——`npm pack` 出来的包里少了文件、`lib/client.js` 与 `client/client.js` 不同步,都要等用户装上才发现;②云服务器上 `stm32_doctor` 说不清"没有 USB 口"和"没插探针"的区别;③只有 `.elf`,想要 `hex` / `bin`,还希望工程自带 `openocd.cfg`;④烧录失败只有一句话,模型没法按类分支;⑤上游文件只靠 marker 判"像不像",`master` 改一行照样落盘。
|
|
1672
|
+
|
|
1673
|
+
定案时明确了两条边界:**不做**自动装 CubeMX(GUI 向导 + ST 账号,装不了);**不加**运行时依赖(zip 都自己写)。
|
|
1674
|
+
|
|
1675
|
+
### 21.1 钉死上游内容:模板每个文件带 sha256(0a)
|
|
1676
|
+
|
|
1677
|
+
marker 只能证明"拿回来的像这个文件",证明不了"还是那一份"。上游 `master` 上把 `system_stm32f1xx.c` 改一行,marker 照样命中,落盘后要到编译期才炸,而缓存还会把坏文件长期留着。
|
|
1678
|
+
|
|
1679
|
+
- `src/engine/fetch.ts` 的 `FetchTarget` 加可选 `sha256`,`fetchOne` 的校验顺序是:HTTP 状态 → 体积下限 → HTML 嗅探(代理拦截页)→ marker → **sha256**;不匹配就换下一个候选源,全失败时报「sha256 对不上(期望 `abcd…`,实际 `ef01…`)多半是上游 master 挪动了内容」,并把实际值写进 attempts 方便核对。
|
|
1680
|
+
- `src/data/cmsis-sources.ts` 新增四张表 `DEVICE_HEADER_SHA256` / `SYSTEM_C_SHA256` / `STARTUP_SHA256` / `CORE_HEADER_SHA256`,10 个下载目标全部接上。值是 2026-10-25 从本机缓存里的真实文件算出来的,关键五条:`stm32f1xx.h` `05e93fa3ddefb2e83d762b9ca4de36e3bba9cd8e9690400fe9f2c11fc0a3cef5`、`system_stm32f1xx.h` `a54dfbb3480c672f532d472a6e84bcf34df6551771d2e9966c5a3503c676b6ab`、`stm32f103xb.h` `d9c7c613d9fea74220892b4fbc3e80617493acad82a04bafadab2b4a7198399c`、`system_stm32f1xx.c` `8465bf3fe9057adecd8b4561403836d1fa2152d3cb088831623da3f91d86ec0a`、`startup_stm32f103xb.s` `a9a5fc7ed5ff617527dd98b3092830f4d17ed4bf57c99eac2c53bdb514ce138c`。
|
|
1681
|
+
- **取舍**:上游一动,新机器就装不上(旧的还能从缓存复用)。仍然选"失败"而不是"照落"——落错文件的代价是半天编译报错的排查,而对不上的提示里直接给了两个哈希,用户(或我)能在 30 秒内判断是上游改了还是网络中间人。
|
|
1682
|
+
- 测试注入点:`TemplateRequest.hashes` 与 `RegisterProjectRequest.hashes`(`src/engine/register-template.ts` 把它们映射到 targets 的 `sha256`),测试侧用 `contentHashes(override)` 按 `SAMPLE_PAYLOADS` 现算;`cache-units` 新增"哈希对不上必须拒绝并报两个哈希"。
|
|
1683
|
+
|
|
1684
|
+
### 21.2 pack-smoke:发布形态得由 CI 自己验(第 1 批)
|
|
1685
|
+
|
|
1686
|
+
`npm test` 跑的是仓库里的 `lib/`,永远发现不了"tarball 里少了 `templates/scaffold/openocd.cfg`"或"`lib/client.js` 没跟着 `client/client.js` 重新生成"。新增 `scripts/pack-smoke.mjs`:
|
|
1687
|
+
|
|
1688
|
+
1. `npm pack` 到临时目录;
|
|
1689
|
+
2. `tar -xzf` 解开(Windows 上 `execFileSync` 必须带 `shell: true`,否则找不到 `tar`);
|
|
1690
|
+
3. 断言 16 个发布必须文件都在(含 `lib/client.js`、`templates/scaffold/openocd.cfg`——`openocd.cfg` 是 2c 新加的,漏打包会让新工程烧不了而单测全绿);
|
|
1691
|
+
4. 断言 `lib/client.js` 与 `client/client.js` 逐字节一致(否则说明忘了 `npm run build`);
|
|
1692
|
+
5. **用解包出来的 `lib/` 与 `templates/` 真建一次寄存器工程**,断言产物与模板计数。
|
|
1693
|
+
|
|
1694
|
+
`package.json` 加 `test:pack`,`.github/workflows/ci.yml` 在 `npm test` 之后单独一步跑它。不并进 `npm test` 的原因:它要跑 `npm pack`(慢),而且它验的是"发布形态"而不是"逻辑",分开跑能一眼看出是哪种失败。
|
|
1695
|
+
|
|
1696
|
+
### 21.3 探针诊断下沉到烧录(2a)
|
|
1697
|
+
|
|
1698
|
+
云服务器上 `stm32_flash` 失败只会说「找不到 CMSIS-DAP 设备」,和"线只供电"、"驱动没装"、"口被占"混在一起。做法是把 §20 的 `usbDiagnosis` 复用出两层:
|
|
1699
|
+
|
|
1700
|
+
- `src/engine/doctor.ts` 的 `hasDap` 名单扩到 CMSIS-DAP / `VID_0D28` / `VID_0483`(ST-Link)/ `VID_C251` / `VID_1A86`(CH340 桥接板),另配 `usb vid_` 小写形态;
|
|
1701
|
+
- `src/engine/flash.ts` 新增导出 `probeMissingLines(errors)`(从 openocd 日志里认出"找不到设备"那几行)与 `usbNoteFor(kind, detail)`(`unknown` 返回 `null`,不乱说话),`runFlash` 只在"确实没找到设备"时把 USB 形态追加进 `notes`。
|
|
1702
|
+
|
|
1703
|
+
### 21.4 hex/bin 与 openocd.cfg(2b / 2c)
|
|
1704
|
+
|
|
1705
|
+
- `stm32_build` 的 `BuildRequest.artifacts`(`elf` / `hex` / `bin` 的子集)与 `BuildReport.converted`(`{kind, path, size}[]`)。链接成功后用 `resolveToolIn(subprocess, ["arm-none-eabi-objcopy"], config.binDirs, signal)` 跑 `-O ihex` / `-O binary` 到 `.elf` 同目录;**转换失败只写 note,不判编译失败**——编译本身已经成功,`.elf` 仍然可用。不让用户自己 `objcopy` 的理由:门禁已经知道工具链在哪,而且失败时文案能说清"缺 objcopy"还是"路径写不进"。
|
|
1706
|
+
- 新增 `templates/scaffold/openocd.cfg`(`source interface/cmsis-dap.cfg`、`transport select hla_swd`、`source target/stm32f1x.cfg`、`adapter speed 2000`),进 `SHARED_TEMPLATE_FILES`,两条路线都自带。2 MHz 是 F103 + CMSIS-DAP 上实测最稳的档位。
|
|
1707
|
+
- 顺带把 `checkNoDebugGuard` 的降级路径做完整:工程里找不到唯一 `.ioc` 时,改看 `openocd.cfg` 的 `transport` —— `swd` 放行并说明"依据是 openocd.cfg";`jtag` 提示 PA13/PA14 可能被复用;连 `transport` 都没有才继续报"守卫没生效"。计数断言随之 14 → 15(scaffold-patch)、6 → 7(cache-units)。
|
|
1708
|
+
|
|
1709
|
+
### 21.5 errorCode:让模型能按类分支(2d)
|
|
1710
|
+
|
|
1711
|
+
`stm32_flash` 新增 `FlashErrorCode`(`""` / `no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `unknown`)与 `errorCodeOfLines(lines)`;成功时为空串,`FlashLogVerdict` 与 `FlashReport` 都带上它,工具 schema 用 enum 收口并在卡片里单独一行渲染。分类按 openocd 日志的**首个**命中判定(顺序敏感:先 `no-probe` 再 `probe-busy`,避免把"被占用"读成"没插")。不把 `message` 直接给模型当分支依据——中文话术会改,错误码是契约。
|
|
1712
|
+
|
|
1713
|
+
### 21.6 `/stm32-setup`(第 3 批轻量版)
|
|
1714
|
+
|
|
1715
|
+
人已经决定要干活时,先体检再出计划比"先问他装不装"更顺手:命令一次跑完 `stm32_env_probe` + 安装计划;**命令里带「装」字**(例如 `/stm32-setup 装上缺的`)才真装,否则只回计划与下一句。真装仍然是 43 MB 下载 + 写注册表,不能靠一句 `/stm32-setup` 触发。命令数 6 → 7。
|
|
1716
|
+
|
|
1717
|
+
### 21.7 `stm32_project_export`:把工程交给别人(P1-4)
|
|
1718
|
+
|
|
1719
|
+
用户的原话是"云上建好的工程怎么拿回本地"。与其让他自己挑文件打包,不如给一个工具:
|
|
1720
|
+
|
|
1721
|
+
- `src/engine/project-export.ts`:`collectSources` 递归收集,`SKIP_DIRS` 固定跳过 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`;`includePrebuilt` 时把 `.elf` 一起带上;`readme` 默认在包里写一份开箱说明(内容用 `__inline__` 前缀表示"这是内联生成,不是文件");`outDir` 缺省落在工程同级的 `<name>-export.zip`。
|
|
1722
|
+
- `src/engine/zip.ts`:**store-only 的最小 zip 写盘器**(CRC32 + DOS 时间 + 本地头 + 中央目录),外加 `listZipEntries(buffer)` 给测试验内容。为什么不加 `archiver` / `jszip`:这个仓库的承诺是零运行时依赖、`lib/` 入库、`npm i` 不用编译任何东西,为此引一棵依赖树不划算;我们的场景也不需要压缩比(源码 + 一个 `.elf`)。
|
|
1723
|
+
- 报告字段:`ok` / `projectDir` / `zipPath` / `zipBytes` / `fileCount` / `prebuilt` / `durationMs` / `message` / `notes`;`message` 直接给"多少个文件、多大、要不要带 elf"。
|
|
1724
|
+
- 测试(`test/export-units.test.mjs` 9 例):空工程仍出合法 zip 且能被 `listZipEntries` 读回;`build/` 与 `.dsh-stm32/` 不进包;`includePrebuilt: true` 时 `.elf` 在包里、`false` 时不在;`readme: false` 不写 README;默认落点与 `outDir`;`zipBytes` 与磁盘文件大小一致;`fileCount` 与实际条目一致;CRC 能被独立实现验过。
|
|
1725
|
+
|
|
1726
|
+
### 21.8 计数与文档
|
|
1727
|
+
|
|
1728
|
+
本批新增 8 例(cache 17 → 19 的两条哈希、flash 8 → 13 的五条、doctor 10 → 11 的一条 CH340;`commands-units` 只改命令名单断言、不增例),加 export 9 例:**25 套件 335 pass / 0 fail**(CI 333 + 2 skipped)。README / README_EN 的用例数、套件数、工具数(19 → 20)、命令数(6 → 7)与新增小节一并同步;`package.json` / `package-lock.json` / 两个 README 的 badge 与"装完确认"行升到 0.1.2。
|
|
1729
|
+
|
|
1730
|
+
### 21.9 宿主级验证(2026-10-28,重启加载 0.1.2 后)
|
|
1731
|
+
|
|
1732
|
+
八项实测,全部通过(不碰板子的部分都跑了;碰板子的两条见 21.10):
|
|
1733
|
+
|
|
1734
|
+
1. **计划只报缺件(§19 的回归)**:`stm32_env_install` 默认计划 → `steps: []`、`download.bytes: 0`、`verify.ok: true`、`notes: []`、`nextStep: ""`,全文只有「工具链完整,不需要装任何东西:5 个组件都能跑,PATH 与配置都已就位(D:/app/msys64/ucrt64/bin)。」
|
|
1735
|
+
2. **`stm32_env_probe`**:四项能力全 `true`;gcc 13.3.0、gdb 16.2、openocd 0.12.0、cmake 3.31.5、ninja 1.12.1、`cubemx-java` OpenJDK 21.0.3;`cubemx` 的版本串是空的(路径在、版本没解析出来,记进 21.10)。
|
|
1736
|
+
3. **`stm32_doctor`**:`ok: true`、`usb.kind: "no-dap"`(文案把「没插探针 / 线只供电 / BOOT0=1」分开说了)、`portBusy: false`、`processes: []`、`blockers: []`。
|
|
1737
|
+
4. **2b hex/bin**:寄存器版工程(template 7 / drivers 10,缓存命中)→ 首次 `cmake --preset Debug` 21.9 s、编译 2.2 s、`elf` 431,012 B、RAM 7.7% / FLASH 1.16%;`converted` = `hex` 2,221 B + `bin` 760 B,落在 `build/Debug/` 里。
|
|
1738
|
+
5. **0a sha256 真下载**:把 `%LOCALAPPDATA%\dsh-stm32\cache` 整个挪开 → `stm32_cache fetch` → 11 个文件 / 1,071,297 B 全部过校验并落盘;新缓存与挪开的旧缓存逐文件比对 `diffCount=0`。
|
|
1739
|
+
6. **sha256 反向验证**:同一个 URL 故意喂 64 个 `0` 的哈希 → `ok: false`,attempts 原文「sha256 对不上(期望 0000000000000000…,实际 05e93fa3ddefb2e8…)。多半是上游 master 挪动了内容」;喂真值 → `ok: true`、10,110 B。说明这道门禁不是空转。
|
|
1740
|
+
7. **export**:同一个寄存器工程 `includePrebuilt: true` → zip 1,522,918 B / 21 条,包内有 `prebuilt/{p1verify.elf,hex,bin}`、`README.md`、`openocd.cfg`、`.gitignore`,**没有** `build/`、没有 `.dsh-stm32/`;notes 写明 build 不进包的原因(CMakeCache 记着本机绝对路径)。
|
|
1741
|
+
8. **2c + hal 路线**:hal 工程 template 15(比旧版多 `openocd.cfg`)、drivers 238、`firmwareRoot` = `D:\app\STM32CubeMX\dsh-firmware\STM32Cube_FW_F1_V1.8.8`;`.vscode/launch.json` 与 `settings.json` 剥注释后都 `JSON.parse` 成功、**占位符 0 个、`D:/JingYu` 0 次**,`armToolchainPath` / `gdbPath` 填的是本机探测到的 `D:/app/msys64/ucrt64/bin`;寄存器版工程没有 `.ioc` 时 `checkNoDebugGuard` 按 `openocd.cfg` 的 `transport=swd` 放行(`blocked=false`)并说明依据,不再静默通过。
|
|
1742
|
+
|
|
1743
|
+
**顺手记下的两个 API 事实**(下次写验证脚本别再踩):`src/engine/zip.ts` 的 `listZipEntries(buffer)` 返回的是**文件名数组**(`string[]`),不是对象数组;在 `demo/` 下写脚本 import 插件的 `lib/` 必须用 `file:///` 绝对 URL,相对路径会 `ERR_MODULE_NOT_FOUND`。
|
|
1744
|
+
|
|
1745
|
+
**验证用的临时工程**(`.verify-p1/` 下的 reg、hal、zip 与三个脚本)与挪开的旧缓存都已进回收站,`demo/` 下 `.verify-*` / `.tmp-*` 为 0。
|
|
1746
|
+
|
|
1747
|
+
### 21.10 还没验证的
|
|
1748
|
+
|
|
1749
|
+
- `npm run test:pack` 只在开发机跑过,CI 上首跑要看 windows-latest 的 `tar` 行为(已按经验带 `shell: true`);
|
|
1750
|
+
- 2d 的 `errorCode` 已在真板上验过 `probe-busy`(见 §21.11);`swd-locked` / `flash-protected` / `no-power` / `target-mismatch` 四种要制造锁片、写保护或拔电源,不能为了测试去毁板子,仍只有单测覆盖;
|
|
1751
|
+
- `/stm32-setup`、`/stm32-build` 等斜杠命令的人工卡片:命令只能用户自己输入,工具层结论已由上面的 1–8 覆盖;
|
|
1752
|
+
- `stm32_env_probe` 里 `cubemx` 的版本串为空是**设计如此**(`probe.ts` 的 cubemx 目标 `versionArgs: []`——启动器 exe 没有可用的 `--version`,版本靠 `cubemx-java` 那项);卡片上 `OK cubemx <路径>` 正常显示,只有直接读 JSON 的 `version` 字段才是空串。验证时一度把它当缺陷,记在这里免得下次又查一遍;
|
|
1753
|
+
- P2(多芯片 F0/F3/F4/G0/L4、HAL 外设源文件落位)与 P3(gdb MI 常驻)未开工。
|
|
1754
|
+
### 21.11 上板验证(2026-10-28,蓝丸 F103C8T6 + CMSIS-DAP)
|
|
1755
|
+
|
|
1756
|
+
用户插上板子后补的第五~九项。**这一步抓出了两个只有真硬件才会暴露的缺陷**,单测当时全是绿的。
|
|
1757
|
+
|
|
1758
|
+
**跑通的部分**
|
|
1759
|
+
|
|
1760
|
+
- `stm32_doctor`:`usb.kind` 从 `no-dap` 变成 `ok`(「能看到 CMSIS-DAP 设备且驱动正常」),`processes: []`、`portBusy: false`。
|
|
1761
|
+
- `stm32_flash` 烧 demo:`ok`、`programmed + verified`、2.5 s、`errorCode` 缺省;openocd 日志 `device id = 0x20036410`、`flash size = 64 KiB`、`clock speed 1000 kHz`(工程自带 `demo/openocd.cfg`)。
|
|
1762
|
+
- 新建寄存器工程(`route=register`,`template 7 / drivers 10`,缓存命中)→ 构建 9.0 s configure + 2.5 s 编译、`regcheck.elf` 431,052 B、RAM 7.70% / FLASH 1.16% → `stm32_flash` 走模板 `openocd.cfg`(`transport swd` + `adapter speed 2000`,日志 `clock speed 2000 kHz`)成功,notes 第一条是「SWD 守卫(openocd.cfg 版):transport 是 swd…」——2c 的两条路径(.ioc 与 openocd.cfg)都在真机上成立。
|
|
1763
|
+
- `stm32_regs_read`:`pc=0x08000210`;`0x4001100C`(GPIOC_ODR)=`0x00000000`、`0x40011004`(GPIOC_CRH)=`0x44244444`、`0x40021018`(RCC_APB2ENR)=`0x00000035`、`0xE000ED04`=`0x00000000`,全 `ok`、`errors: []`。
|
|
1764
|
+
- `stm32_debug_run`(`breakAt: main`):`ok`、`hitBreakpoint`、`main () at Core/Src/main.c:67`、`pc=0x8000f58 sp=0x20004ff8 lr=0x80011ab`、backtrace 一条。
|
|
1765
|
+
|
|
1766
|
+
**缺陷 1:模板 `openocd.cfg` 写了 `hla_swd`(2c 的模板错了)**
|
|
1767
|
+
|
|
1768
|
+
寄存器工程第一次烧录,宿主直接拒收:`tool "stm32_flash" returned invalid output: "value.report.errorCode" is not a declared property`(这才是缺陷 2 暴露的入口)。手动跑 openocd 才看到真因:`Error: Debug adapter doesn't support 'hla_swd' transport`,位置正是模板的 `transport select hla_swd`。`hla_swd` 只有 st-link 系适配器支持,CMSIS-DAP 必须 `transport select swd`。
|
|
1769
|
+
|
|
1770
|
+
修法与回归:模板改 `transport select swd`(注释里写清为什么不能用 `hla_swd`),`test/flash-units.test.mjs` 加一条读模板文件的用例——断言 `/transport\s+select\s+swd\b/u` 命中、**生效行**不含 `hla_swd`(注释允许解释)、把这份配置写进临时目录后 `checkNoDebugGuard` 报 `blocked=false` 且 notes 含「transport 是 swd」。教训:模板类文件也要有「按真实消费者跑一遍」的断言,光断言文件存在不够。
|
|
1771
|
+
|
|
1772
|
+
**缺陷 2:`stm32_flash` 的 report schema 漏声明 `errorCode`(2d 在失败路径上不可用)**
|
|
1773
|
+
|
|
1774
|
+
`src/tools/flash.ts` 的 `reportSchema` 是 `additionalProperties: false`,但没写 `errorCode`。成功路径 `errorCode` 是空串、引擎按 `...(errorCode === "" ? {} : { errorCode })` 省略,所以永远不触发;**只要失败带码,宿主就判「工具返回了非法输出」,报告拿不到**。2d 加字段时只改了 `FlashReport` 类型与卡片渲染,没同步 schema,单测也只测了空目录早退(不带码)。
|
|
1775
|
+
|
|
1776
|
+
修法与回归:schema 补 `errorCode`(enum 收到 8 个码,不进 `required`);`test/schema-guard.mjs` 加「失败报告带 errorCode 时仍符合 output schema」,用假 subprocess 返回 `exitCode 1` + `no-probe` 文本,断言 `report.errorCode === "no-probe"` 且过 schema 检查。教训:**新增可选字段必须同时进 schema**,而且要有一条「字段有值」的用例——只测缺省值等于没测。
|
|
1777
|
+
|
|
1778
|
+
**顺手补的分类:两个 openocd 抢同一个探针**
|
|
1779
|
+
|
|
1780
|
+
为了验 `probe-busy`,用 `Start-Process` 起一个常驻 openocd(`-f interface/cmsis-dap.cfg -c "transport select swd" -f target/stm32f1x.cfg -c init`,日志 `Listening on port 3333`)攥住探针,再调 `stm32_flash`。真实失败**不是**「设备忙」,而是两个进程交替收发:`CMSIS-DAP command mismatch. Sent 0x12 received 0x5`、`CMSIS-DAP command CMD_DISCONNECT failed`、满屏 `CMSIS-DAP transfer count mismatch: expected 5, got 1`、`Failed to write memory`、`clearing lockup after double fault`。原来的 `errorCodeOfLines` 一条都不认 → `unknown`。
|
|
1781
|
+
|
|
1782
|
+
修法:`errorCodeOfLines` 增加 `/cmsis-dap (transfer count mismatch|command mismatch)|cmsis-dap command cmd_\w+ failed|libusb_error_busy/` → `probe-busy`;新增 `HINT_BUSY` 并只在 `errorCode === "probe-busy"` 时进 notes(「先关掉调试会话或另一个 openocd,再烧一次」)。宿主级实测:`ok=false`、`exitCode=1`、`errorCode=probe-busy`、notes 就是 `HINT_BUSY`,工具正常返回;杀掉持锁进程后再烧 demo → `ok`、`programmed + verified`、3.1 s、`errorCode` 缺省。
|
|
1783
|
+
|
|
1784
|
+
另外记一个 PowerShell 坑:`Start-Process -ArgumentList` 不会替你加引号,`-c 'transport select swd'` 会被拆成两个参数,openocd 报 `Unexpected command line argument: select`;要写成 `-c '"transport select swd"'`。
|
|
1785
|
+
|
|
1786
|
+
**计数**:本批新增 3 例(flash 13 → 15 两条、schema-guard 23 → 24 一条)→ **25 套件 338 pass / 0 fail**(CI 336 + 2 skipped);README / README_EN 的用例数与 CI 计数已同步。
|
|
1787
|
+
|
|
1788
|
+
**清理**:`demo/.verify-board/`(一次性寄存器工程)与 `%TEMP%` 下的持锁脚本、openocd 日志、重启脚本都进了回收站,计划任务 `dsh-restart-board` 已注销;`demo/` 下 `.verify-*` / `.tmp-*` 为 0。
|
|
1789
|
+
|
|
1790
|
+
|
|
1791
|
+
|
|
1792
|
+
|
|
1793
|
+
|
|
1794
|
+
|
|
1795
|
+
|
|
1796
|
+
|
|
1797
|
+
## 22. 源码精读指南:把 2 万行拆成七站(2026-10-26)
|
|
1798
|
+
|
|
1799
|
+
新增 `docs/reading-guide.md`(约 695 行 / 4 万字符)。它不是 API 文档,而是「怎么读这份源码」的路线图:11 章、14 张 Mermaid 流程图,从宿主装配一路读到测试假件。
|
|
1800
|
+
|
|
1801
|
+
结构:0 心法(四层:L4 装配 / L3 tools 契约 / L2 engine 逻辑 / L1 data 事实表,加四条设计约定)→ 1 整体框架图 + 目录行数全景 → 2 七站阅读顺序(每站有行数、能回答的问题、建议时长)→ 3 入口层 → 4 tools 骨架与 20 工具表 → 5 engine 十个域逐文件表 → 6 data 六张事实表 → 7 十四条流程各配一张图 → 8 二十条不变量 → 9 测试三层 → 10 改东西动哪里 → 11 已知的坑。
|
|
1802
|
+
|
|
1803
|
+
**写文档时踩到的两件事**
|
|
1804
|
+
|
|
1805
|
+
1. **数字必须从磁盘重算,不能抄早先的清点。** 第一版的行数是从几轮前的一次 `grep` 清点里拿的,已经过时:engine 合计写成 11 994(实为 12 753)、`commands/register.ts` 386(实为 445)、`client/client.js` 674(实为 682)、`msys2-install.ts` 1808(实为 2038)、`types.ts` 164(实为 196)。最后用脚本按「读文件 → 按 `\n` 切 → 去掉末尾空行」重新统计,再把文档里所有 `文件名(数字)`、章节小计、目录合计、阅读站小计逐个对齐,并做了一次反向扫描(把每个「文件名 + 数字」对拿新表校验,剩 0 处不一致)。教训:文档里的数字要么别写,要么每次由产物重算——写死手抄值必然在下一批改动后变成假话。
|
|
1806
|
+
2. **Mermaid 的标签一律用双引号包住。** 节点标签里出现括号、斜杠、方括号(`probeCache.set(key, {at})`、`missing[]`)时,不引号化会直接把图解析坏;状态图的行内标签里也尽量别用括号(本轮把 `turn/end(本轮输出结束)` 改成顿号版本)。
|
|
1807
|
+
|
|
1808
|
+
**顺手发现的一处杂物**
|
|
1809
|
+
|
|
1810
|
+
`templates/scaffold/build/` 里有 4 个文件、29 459 B 的构建残留(`.cmake/api/v1/query/client-vscode/query.json`、`CMakeFiles/CMakeConfigureLog.yaml`、`CMakeFiles/3.31.5/CMakeSystem.cmake`、`CMakeFiles/3.31.5/CompilerIdC/CMakeCCompilerId.c`)。全仓库 grep 不到任何 `scaffold/build` 引用,但 `package.json` 的 `files` 含 `templates`,会把它一起打进发行包。已写进指南 §11 待清,尚未删除(等用户确认)。
|
|
1811
|
+
|
|
1812
|
+
README 与 README_EN 的 docs 索引各加一行指向新文档。
|
|
1813
|
+
|
|
1814
|
+
## 23. 可视化:用 Archify 出两张可交互图(2026-10-28)
|
|
1815
|
+
|
|
1816
|
+
精读指南里原来只有 Mermaid。Mermaid 适合贴在 Markdown 里速览,但排版、配色、缩放和导出都不受控;这一节记的是用 Archify(`@tt-a1i/archify-dsh` 技能)把它升级成两张单文件 HTML 的过程与踩坑。
|
|
1817
|
+
|
|
1818
|
+
**产物**(已复制进仓库,随 `docs` 一起发布)
|
|
1819
|
+
|
|
1820
|
+
- `docs/diagrams/dsh-stm32-architecture.html`(约 787 KB):17 个节点、1 个宿主进程边界、19 条连线、5 张卡片。主轴是「调用入口 → tools 层 → 门禁 → engine 五簇 → 子进程桥 → 外部程序(CubeMX / 工具链 / openocd+gdb / pacman)/ 上游仓库」,磁盘状态放卡片。
|
|
1821
|
+
- `docs/diagrams/dsh-stm32-journey.html`(约 771 KB):6 列 × 4 lane 的 workflow。列是时间(定路线 → 体检 → 建工程 → 生成 → 改码 → 编译 → 上板),lane 是「你与模型 / 契约层 / 门禁与失败分支(exception 配色)/ 外部程序与板子」。
|
|
1822
|
+
- 两张都带「来源 N」角标:点开是 `path` + 行号,对着 `reading-guide.md` 第 5 章能直接跳到文件。
|
|
1823
|
+
|
|
1824
|
+
**生成命令**(本机没有 Chrome,用 Edge 冒充 Chromium 通过 browser-check)
|
|
1825
|
+
|
|
1826
|
+
```powershell
|
|
1827
|
+
$env:ARCHIFY_CHROME="C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
|
|
1828
|
+
node "<skill>/bin/archify.mjs" finalize architecture `
|
|
1829
|
+
".archify/architecture-dsh-stm32-overview-20261028-152823/candidate.json" `
|
|
1830
|
+
".archify/architecture-dsh-stm32-overview-20261028-152823/dsh-stm32-architecture.html" `
|
|
1831
|
+
--quality showcase --repo-root "D:/JingYu/Desktop/c8t6_vscode_test/demo/dsh-stm32" --json
|
|
1832
|
+
```
|
|
1833
|
+
|
|
1834
|
+
candidate JSON 放在工作区 `.archify/<type>-<slug>-<时间戳>/`,不进仓库;改完重新 finalize,再把 HTML 覆盖到 `docs/diagrams/`。
|
|
1835
|
+
|
|
1836
|
+
**踩到的六个坑**
|
|
1837
|
+
|
|
1838
|
+
1. **没有 Chrome 时 browser-check 直接 skipped**(`viewer/chrome-unavailable`,整体 exit 1)。本机只有 Edge,`ARCHIFY_CHROME` 指过去就能跑——Edge 是 Chromium 内核,CDP 检查全过。
|
|
1839
|
+
2. **证据按 HEAD 的已提交字节校验,不认工作区**。`/nodes/N/sources/path` 必须在该 revision 存在:我第一次把 `install-guides.ts` 写成 `src/engine/…`(实际在 `src/data/…`),报 `repository-evidence/file-missing`。行号同理——0.1.2 尚未提交,凡是这一批新加的行都别写行号,只写 `path` 更稳。
|
|
1840
|
+
3. **showcase 要求零警告**:`composition/viewport-height` 在普通检查里只是 warning,在 showcase deliver 里算失败。判据很具体——1440×900 视口下,画布要么高度 ≤ 785(宽 1218),要么横向铺到 ≥ 1414;我最初 6 条 lane 的 workflow 是 1218×912,被判超高,删掉一条 lane(6→5→4)才合格。
|
|
1841
|
+
4. **`composition/desktop-readability` 卡字号**:画布越宽缩放越小,8px 源文字投到 930px 预算上必须 ≥ 6px。把节点宽度一口气加到 196 后 viewBox 变成 1511,投影只有 4.9px;退回 132–160 的混合宽度(viewBox 1218)才过。宽度和字号是一对矛盾,别只盯布局。
|
|
1842
|
+
5. **workflow 的 lane/col 是硬网格**:`mainPath` 必须按列单调,`entry(col1) → route(col0)` 这种回退会报 `mainPath moves backward`;同一 lane 同一 col 只能放一个节点;`route: "straight"` 在跨 lane 的边上根本不可能满足(`workflow/route-preset-conflict`),同 lane 相邻列的边又容易撞 `ambiguous-corridor`(两条边共用一段通道 ≥ 8px)。最后是靠「把失败分支从图里挪进卡片、把 patch/build 放进同一 lane」收掉的。
|
|
1843
|
+
6. **回执文件有归属校验**:artifact 变了以后旧的 `*.browser-check.json` 会被判 `viewer/evidence-path-conflict`(`ownership-artifact-mismatch`),不许覆盖。每轮改完 finalize 前,把旧回执改名(如 `stale-browser-check-*.json`)而不是删掉。
|
|
1844
|
+
|
|
1845
|
+
**经验**:Archify 的价值在「强制你把话说清楚」——节点要一句话、边要有方向、失败分支要么成节点要么进卡片。两次 finalize 卡住的都不是审美,而是「这条边到底谁指向谁」「这个失败到底属于哪个阶段」。写图的过程等于把 `reading-guide.md` 第 7 章又校对了一遍。
|
|
1846
|
+
|
|
1847
|
+
## 24. 第五批:选错 .elf、调试丢根因、安装包单源(F1–F4,2026-10-29)
|
|
1848
|
+
|
|
1849
|
+
用户点名的四个问题,顺序 F1 → F4(m00536)。F1/F2 修的是「已经在做对的事,但结果说错/做错」,F3 修的是「只在网络不好或国内访问时才暴露」,F4 是文档。
|
|
1850
|
+
|
|
1851
|
+
### 24.1 F1:`findElf` 会把旧固件当产物(P0)
|
|
1852
|
+
|
|
1853
|
+
旧规则是「构建目录同名优先」:`buildDir` 叫 `build/Debug` 时 `buildName = "Debug"`,而产物叫 `demo.elf`,两者**永不相等**,于是退化成 `readdir` 顺序——改过工程名(或换个 `project()` 重新生成)之后,中间产物和上一次的固件都在同一个 `build/` 里,谁排在前面就烧谁。这条路径被 **5 个调用点**共用:`src/engine/build.ts:414`(编译后报产物)、`flash.ts:210`(烧之前找 elf)、`debug.ts:402`、`doctor.ts:213`(体检报 elf 大小)、`project-export.ts:104`(导出 prebuilt),所以坏一次是五处一起坏。
|
|
1854
|
+
|
|
1855
|
+
新实现(`src/engine/build.ts:194-284`):
|
|
1856
|
+
|
|
1857
|
+
- `readCmakeProjectName(buildDir)`:从 `CMakeCache.txt` 里读 `CMAKE_PROJECT_NAME:<TYPE>=<名字>`,读不到返回空串(没有缓存不影响出结果)。
|
|
1858
|
+
- `elfCandidates(buildDir)`:列出全部 `.elf`,带 `size` / `mtimeMs`,按修改时间从新到旧排序;`readdir` 或 `stat` 抛错(刚被删、被独占)就跳过,不炸整条链路。
|
|
1859
|
+
- `pickElf(buildDir)`:**先按 CMakeCache 里的工程名精确匹配 `<name>.elf`**(`byProjectName: true`,最权威);匹配不到才退回"修改时间最新"(`byProjectName: false`)。
|
|
1860
|
+
- `findElf(buildDir)`:对外的老签名不变,仍返回 `ElfInfo`,所以五个调用点一行都不用改。
|
|
1861
|
+
- `elfSelectionNote(buildDir)`:构建目录里有 ≥2 个 `.elf` 时回一句人话("用了 demo.elf(18:42:03,按 CMakeCache 的工程名选);没动的 2 个:…"),只放 `notes`,只有一个 elf 时返回空串——不给报告加噪音。
|
|
1862
|
+
|
|
1863
|
+
**判据为什么不是「最新」而是 CMakeCache**:`mtime` 只能回答"谁最后被写",回答不了"谁属于当前这套构建"。`stm32_generate` 重新生成、`cmake --preset` 换 preset、用户手动 `rename` 都能让旧固件比新固件更新;而 `CMakeCache.txt` 是 CMake 自己写的、和这套构建目录一一对应的事实。**先在事实层找答案,再退回启发式**,这条经验在 `buildDir` 检测、`findProjectConfig` 里都出现过。
|
|
1864
|
+
|
|
1865
|
+
### 24.2 F2:`stm32_debug_run` 失败只说"起不来"(P0)
|
|
1866
|
+
|
|
1867
|
+
旧代码在 `waitForListening` 超时后只做两件事:把日志 `tail(15)` 塞进 `openOcdLogTail`,message 写 "没调试:openocd 起不来"。真机上 adapter init 失败的那几行(`Error: unable to find CMSIS-DAP device`、`CMSIS-DAP command mismatch`)常被后 15 行的 `Info :` 挤出去,模型和用户都拿不到根因,而且**同一套分类逻辑在 `stm32_flash` 里已经有了**(`errorCodeOfLines` / `probeMissingLines` / `usbDiagnosis`),调试路径没接上。
|
|
1868
|
+
|
|
1869
|
+
修法(两条失败路径都覆盖):
|
|
1870
|
+
|
|
1871
|
+
1. **openocd 起不来**(`src/engine/debug.ts:277-299`):`errorCodeOfLines(lines)` 归类 → `debugHintFor(code)` 给一句下一步(`no-probe`→查线/驱动、`probe-busy`→关掉另一个 openocd、`swd-locked`→`monitor reset halt`/改 BOOT、`no-power`→查 3V3/GND);只有 `no-probe` 且 `probeMissingLines` 命中时才多跑一次 `usbDiagnosis`(`usbNoteFor` 出人话,`ok` 时不打扰);`firstProblemLine(lines)` 取第一条 `Error/unable to find/no device found/couldn't bind/cannot open/invalid` 进 `errors`,message 带 `(code)`。
|
|
1872
|
+
2. **gdb 起来了但没收好**(`src/engine/debug.ts:351-362`):`ok === false` 时同样算一次 `errorCode`,只在失败时附上(成功时报告里根本不出现这个字段)。
|
|
1873
|
+
3. **日志尾巴换算法**(`keyLogTail(lines, 40)`,`debug.ts:192-203`):先用 `/error|unable to find|no device found|adapter|cmsis-dap|listening|couldn't bind|jtag|cannot/i` 从尾部往前挑"有信息量"的行,挑不满 40 行再按尾部补齐,最后按原顺序拼回去。旧的 `tail(15)` 只保证"最后",新的保证"最后 + 关键"。
|
|
1874
|
+
4. 契约同步:`src/tools/debug.ts` 的 `reportSchema` 补 `errorCode`(8 个码的 enum,不进 `required`),`formatDebugReport` 在"固件:"后加一行"错误码:";`test/schema-guard.mjs` 加一条"失败报告带 `errorCode` 时仍过 output schema + 卡片打印错误码"的用例(手搓报告对象,不跑 15 s 超时)。
|
|
1875
|
+
|
|
1876
|
+
**教训**:同一类失败在两个工具里各写一遍,就一定会有一边落队(`flash` 有 `errorCode` 时 `debug` 没有)。现在两者共用 `HINT_PROBE` / `HINT_BUSY` / `HINT_DP` / `errorCodeOfLines` / `probeMissingLines` / `usbDiagnosis`,改一处两边都变。
|
|
1877
|
+
|
|
1878
|
+
### 24.3 F3:MSYS2 安装包只有 GitHub 一个来源(P1)
|
|
1879
|
+
|
|
1880
|
+
**a) 候选链**(`resolveInstallerUrls(env)`,替换掉的旧名 `resolveInstallerUrl` 已不存在):`MSYS2_INSTALLER_URL`(单源,给了就只试它)> `MSYS2_MIRROR`(给全 `.exe` 当完整地址,否则当目录拼两个文件名)> 四个国内镜像 × 两个文件名 > GitHub × 两个文件名,共 **10 个候选**,顺序就是"国内优先、GitHub 兜底"。**为什么每个源要试两个名字**:镜像只同步 `msys2-x86_64-latest.sfx.exe`,GitHub releases 只有 `msys2-base-x86_64-latest.sfx.exe`(实测 TUNA 上 `msys2-base-…` 是 404),钉死一个名字等于把一半源排除掉。
|
|
1881
|
+
|
|
1882
|
+
**b) pacman 也走国内镜像**(`preferMirrorServers(text, servers)` + `preferChinaMirrors(msys64)`):MSYS2 自带的 `etc/pacman.d/mirrorlist.{msys,mingw}` 第一顺位是官方源,国内装 173 个包会慢到像卡死。安装成功后把国内镜像插到这两个文件**最前面**(`Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/msys/$arch/` 这类),官方条目不删、只在缺失时插入(幂等),文件不存在就跳过。**已经有 MSYS2 的机器一个字都不改**——那是用户自己的配置。
|
|
1883
|
+
|
|
1884
|
+
**c) 断点续传 + 低速判死**(`src/engine/fetch.ts`,同步用于所有下载):`streamOnce(url, part, startAt, …)` 带 `Range: bytes=N-` 流式写 `.part-<pid>-<seq>`;watchdog 每 `min(1000, max(100, stallMs/4))` ms 检查:超过 `stallMs`(默认 10 s)没有新字节,或窗口内平均速率 < `minBytesPerSec`(默认 1024),就 `slow = true` + `controller.abort()`,然后**从已落盘字节续一次**(`fetchOne` 里 `if (!streamed.ok && streamed.slow && streamed.bytes > 0 && !isCancelled())`)。`206` 才追加、`200` 一律截断重写(服务器无视 Range 时不能把两段拼起来)、`416` 直接判失败。**换源一定从零开始**(不同源的字节不保证是同一份,拼出来的 sha256 必然对不上)。安装包那边同一套逻辑用 curl 实现:`-C -` + `--speed-limit 1024 --speed-time 10`,退出码 28 单独写成"太慢(10 s 内不足 1 KB/s)",退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次。
|
|
1885
|
+
|
|
1886
|
+
**d) 缓存三道粗检**:① 命中缓存先 `cachedInstallerBytes`(MZ 魔数 + ≥ `MIN_INSTALLER_BYTES` = 40 MB 才算数)② 下载后查退出码/体量/MZ 头 ③ 解压后查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删,留证据)并让用户重跑。**为什么不能钉 sha256**:镜像与 GitHub 的文件名不同、字节数也不同(实测 TUNA/NJU/aliyun 43,117,824 B、GitHub 42,907,176 B,同步时点不同),跨源钉同一个哈希必然误杀。
|
|
1887
|
+
|
|
1888
|
+
**e) 顺序不变的部分**:CMSIS 头与 ST 固件包仍走原来的候选(raw.githubusercontent → jsdelivr → ghfast → …)。实测 codeload 4.2 s、jsdelivr 675 ms、raw 859 ms,换顺序省不下时间;真正的大头是 43 MB 安装包和 pacman 包体。
|
|
1889
|
+
|
|
1890
|
+
**测试**:`test/install-units.test.mjs` 27 例(新增候选链 / `preferMirrorServers` 幂等 / `preferChinaMirrors` 只动两个文件 / 1 KB 缓存不算数→10 个候选全试 / 已有 MSYS2 不改配置)、`test/cache-units.test.mjs` 22 例(新增"断在 1500 字节→`Range: bytes=1500-`→206 续传""服务器回 200 时截断重写""慢源试两次后换快源、不拼接")。**A29 那条测试同时被改了**:它用 1 KB 假缓存来"跳过下载、在解压步取消",`MIN_INSTALLER_BYTES` 一上就让缓存失效、取消点前移到下载步,解压步自然变 `skipped`——把假缓存改成 40 MB 的 `Buffer.alloc(40_000_002)` 才恢复原意。
|
|
1891
|
+
|
|
1892
|
+
### 24.4 F4:README 排错段补"连不上 GitHub"
|
|
1893
|
+
|
|
1894
|
+
现象:`dsh plugin add github:JingYu-er/dsh-stm32` 报 `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443`。这不是 pnpm 11 的 `allowBuilds` 拦截、不是签名问题、不是包坏了,而是**取包这一跳根本连不上 GitHub**——换个说法就没人再往 pnpm 身上查。
|
|
1895
|
+
|
|
1896
|
+
给了三条不再碰全局配置的路(README 中/英同一条):① 走 npm registry(`add dsh-stm32`,已发布时最省事)② 进程级代理:只给本次命令设 `GIT_CONFIG_COUNT=1` / `GIT_CONFIG_KEY_0=http.https://github.com.proxy` / `GIT_CONFIG_VALUE_0=…`,不写 `git config --global`(那样会影响用户所有仓库)③ 直接吃 codeload 的 tarball。装最新用 `github:JingYu-er/dsh-stm32#main`,要稳定版用 `dsh-stm32@latest`。
|
|
1897
|
+
|
|
1898
|
+
### 24.5 计数与行数
|
|
1899
|
+
|
|
1900
|
+
`npm run build` exit 0;`npm test` → **24 套件 348 pass / 0 fail**(CI 346 + 2 skipped)。行数按"文件内 `\n` 个数"重算:src 65 个 `.ts` **20,758 行**、tools 19 文件 4,832、engine 36 文件 **13,328**(`fetch.ts` 197→**341**、`msys2-install.ts` 2038→**2313**)、data 6 文件 1,803、client 682;`reading-guide.md` 的合计与两处单文件数字、第 9 章用例数已同步。
|
|
1901
|
+
|
|
1902
|
+
**顺手记一个度量坑**:PowerShell 的 `(Get-Content x.ts).Count` 和 `Measure-Object -Line` 都**不等于**行数(前者受文件尾换行影响,后者忽略空行),`wc -l` 在 Git Bash 里对 CRLF 文件也会差一。本文档与 `reading-guide.md` 统一用 Node 读文件数 `\n`:`(text.match(/\n/g) ?? []).length`——示例:`index.ts` 是 119,`Get-Content` 给 108。
|
|
1903
|
+
|
|
1904
|
+
## 25. T1 / T2 验收:sha256 负向与 .ioc 事务链(2026-10-30)
|
|
1905
|
+
|
|
1906
|
+
发布前该验的三件(T1 sha256 负向、T2 .ioc 四步链、T3 真机)里,T1/T2 完全离线,先做掉;T3 卡在探针没识别(见 25.3)。
|
|
1907
|
+
|
|
1908
|
+
### 25.1 T1:sha256 门禁负向(6 例全过,抓到一个真缺陷)
|
|
1909
|
+
|
|
1910
|
+
用注入的 `fetchImpl` 走真 `fetchOne`(一次网络都不发):正控(哈希对→落盘、字节一致、失败记录为空);负控(哈希错→拒绝、消息里有「期望」与「实际」两个前缀和「重新实测」的提示、**不落盘**);旧文件已存在时失败(旧文件原样不动,A15 语义);多源(第一个源回代理登录页 html、第二个源哈希不符→`attempts` 两条各说各的);`minBytes`(1 字节→「只有 1 字节(< 16)」);模拟上游漂移(内容变了但声明哈希还是旧的→拦下并提示去更新 `cmsis-sources`)。
|
|
1911
|
+
|
|
1912
|
+
**抓到的缺陷**:四道校验(体量 / 网页 / markers / sha256)失败后只 `continue`,**没删 `.part` 半成品**。该路径在 `streamOnce` 内部有自己的清理,但校验发生在整个文件读完之后,`.part` 已经躺在缓存目录里——43 MB 的安装包、几十 MB 的模板,几次失败能攒出几百 MB 垃圾,而且它既不参与续传(换源一律从零)也不会被任何清理逻辑回收。
|
|
1913
|
+
|
|
1914
|
+
修法:`src/engine/fetch.ts` 的校验段加局部 `reject(reason)`(`attempts.push` + `removeQuietly(part)`),四道校验改用它再 `continue`;回归沉到 `test/cache-units.test.mjs` 的「fetchOne:校验失败(sha256 / markers / 体量 / 网页)时必须连 .part 半成品一起删掉(T1)」——四道校验各跑一遍,断言目标文件不存在、目录里没有 `.part-*`(22 → 23 例)。
|
|
1915
|
+
|
|
1916
|
+
### 25.2 T2:`.ioc` 事务链(7 例全过,用仓库自带 `templates/scaffold/demo.ioc`)
|
|
1917
|
+
|
|
1918
|
+
工具层走真注册(假 `ctx`:`tools.register` 收定义、`workingDirectory.ensure` 给临时目录、`subprocess` 一律抛错证明没起进程),工程是 `templates/scaffold/demo.ioc`(4 084 B,sha `a487d32b1d3b8818…`)复制到临时目录:
|
|
1919
|
+
|
|
1920
|
+
- `stm32_ioc_inspect`:`STM32F103C8T6` / `STM32Cube FW_F1 V1.8.7` / `SWD=Serial_Wire` / 8 个引脚 / 3 个外设,**不写盘**(sha 不变)。
|
|
1921
|
+
- `stm32_ioc_plan`(加 `PA0` 输出、label `t2led`):`planId` 10 位、`sourceSha256` 等于当前文件、`candidateSha256` 变了,diff **8 条**(`Mcu.Pin8`、`Mcu.PinsNb` 与 `PA0.GPIO_*` 五项),**不写盘**。
|
|
1922
|
+
- `stm32_ioc_apply`:`shaBefore` = 原文件、`shaAfter` = 候选、备份落在 `.dsh-stm32/backups/<时间戳>-ioc/demo.ioc` 且与原文件逐字节一致;写完后反读 inspect 能看到 `PA1` / `t2btn`。
|
|
1923
|
+
- `stm32_ioc_apply({rollbackFrom})`:`rolledBack=true`,文件**逐字节**回到原 sha。
|
|
1924
|
+
- 两条守卫:plan 之后外部改过 `.ioc` → apply 拒写(消息里带两个 sha 与「请重新 plan」)、文件不动;缺 `planId` / 不存在的 `planId` → 给人话且不写盘。
|
|
1925
|
+
|
|
1926
|
+
脚本留在工作区 `.t1-t2/`(不进仓库、不进包):它们的长期价值已经分别沉到 `test/cache-units.test.mjs`(T1)与既有的 `test/e2e-a8-ioc-rollback.mjs` + `test/ioc-plan-units.test.mjs`(T2),重复收进仓库只会养一批没人跑的脚本。
|
|
1927
|
+
|
|
1928
|
+
### 25.3 T3:真机项先挂起
|
|
1929
|
+
|
|
1930
|
+
`stm32_doctor` 报 `usb.kind = "no-dap"`(「有 USB 控制器但没看到常见探针(CMSIS-DAP / ST-Link / DAPLink / CH340)」),`processes: []`、`portBusy: false`。也就是说板子/探针当前没被识别:现在跑 `stm32_flash` / `stm32_regs_read` / `stm32_debug_run` 只会得到 `no-probe` 分支——那验证的是错误路径(2026-10-28 已验过),不是 T3 要的烧录 / 读寄存器 / 断点。插上后再跑。
|
|
1931
|
+
|
|
1932
|
+
### 25.4 计数
|
|
1933
|
+
|
|
1934
|
+
`npm run build` exit 0;`npm test` → **24 套件 348 pass / 0 fail**(CI 346 + 2 skipped);`npm run test:pack` exit 0(16 个必须文件齐全)。README / README_EN / `reading-guide.md` 第 9 章的用例数已同步到 348 / 346。
|
|
1935
|
+
|
|
1936
|
+
## 26. 修掉老洞:`cmake/stm32cubemx/CMakeLists.txt` 从不跟着 .ioc 更新(2026-10-30)
|
|
1937
|
+
|
|
1938
|
+
### 26.1 洞是什么,怎么证实的
|
|
1939
|
+
|
|
1940
|
+
CubeMX 无头生成(`generate all_code_in_main` + `generate code`)只重写 `Core/` 下的代码,`cmake/stm32cubemx/CMakeLists.txt` 这份源清单它一个字都不碰——那是脚手架拷进来的快照。后果:`.ioc` 里新开了 USART1,CubeMX 会老老实实把 `HAL_UART_MODULE_ENABLED` 写进 `stm32f1xx_hal_conf.h`、把 `MX_USART1_UART_Init()` 写进 `main.c`,但源清单里没有 `stm32f1xx_hal_uart.c`,到链接阶段才炸 `undefined reference to HAL_UART_Init`,而错误信息完全指不到真正的原因。
|
|
1941
|
+
|
|
1942
|
+
证据(2026-10-30 实测):`demo/cmake/stm32cubemx/CMakeLists.txt`(3 466 B,mtime 2026/10/21 17:55:36)与 `templates/scaffold/cmake/stm32cubemx/CMakeLists.txt` 逐字节相同,而 `demo/Core/Src/main.c` 的 mtime 是 2026/10/24 15:17:33——中间跑过生成,源清单没变过。模板里三个写死的点:`set(MX_Defines_Syms ... STM32F103xB)`、`set(MX_Application_Src ...)`、`set(STM32_Drivers_Src ...)`(只有 11 个 HAL 模块)。
|
|
1943
|
+
### 26.2 修法:新增 `src/engine/cmake-sources.ts`(450 行)
|
|
1944
|
+
|
|
1945
|
+
- `deviceDefineFromStartup` / `familyTokensFromStartup`:从 `startup_stm32f103xb.s` 反推设备宏 `STM32F103xB` 与家族目录名 `STM32F1xx`(规则:upper 后把倒数第二个 X 换小写 x),不查表。
|
|
1946
|
+
- `halModulesInUse`:模块清单以 `Core/Inc/stm32f1xx_hal_conf.h` 里 CubeMX 自己写的 `HAL_xxx_MODULE_ENABLED` 为准,再并上 `Core/Src/*.c`、`Core/Inc/*.h` 里显式 `#include "stm32f1xx_hal_xxx.h"` 的(兜住手写代码)。不能扫 hal_conf 里那一圈 `#include`:那里 33 个模块全列了一遍,只是被 `#ifdef` 包住。
|
|
1947
|
+
- `collectCmakeSources`:算出启动文件、设备宏、模块清单、驱动源文件(顺序 = `system_stm32f1xx.c` → `stm32f1xx_hal.c` → 其余按模块名字母序,`_ex.c` 存在才带上)、应用源文件(`Core/Src/*.c` + 启动文件),缺 `.c` 的模块进 notes 而不是硬写。
|
|
1948
|
+
- `refreshCubemxCmakeLists(projectDir, { dryRun })`:只改上面三个 managed 块,其余行原样;清单保留原顺序、摘掉磁盘上已不存在的条目、缺的追加到末尾(对用户工程 diff 最小);内容一致时一个字节都不写。
|
|
1949
|
+
- `describeRefresh`:一句话给 notes(「已是最新 / 已更新(新增 N 条)/ 未处理 —— 原因」)。
|
|
1950
|
+
- 接线:`src/engine/generate.ts` 在两条返回路径上都调它——CubeMX 真跑完落位之后(dryRun 时只算不写),以及缓存命中直接复用产物时。只要经过 `stm32_generate`,源清单就会被对齐。
|
|
1951
|
+
### 26.3 差分构建验证(真工具链,不是单测)
|
|
1952
|
+
|
|
1953
|
+
把 `demo` 复制一份(2 935 文件 / 261 914 598 B,排除 `build`、`.dsh-stm32` 等),在副本上做最小改动:
|
|
1954
|
+
|
|
1955
|
+
1. `Core/Inc/stm32f1xx_hal_conf.h` 打开 `HAL_UART_MODULE_ENABLED`,`main.c` 的 `USER CODE BEGIN 2` 里塞 `UART_HandleTypeDef huart1; huart1.Instance = USART1; (void)HAL_UART_Init(&huart1);`。
|
|
1956
|
+
2. `cmake --preset Debug` + `cmake --build --preset Debug`(不刷新源清单)→ 复现老洞:`Core/Src/main.c:84:(.text.main+0x20): undefined reference to HAL_UART_Init`,`ninja: build stopped`。
|
|
1957
|
+
3. 跑 `refreshCubemxCmakeLists` → `added = ["Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal_uart.c"]`,`modules` 从 7 个变 8 个。
|
|
1958
|
+
4. 重新 configure + build → `[21/21] Linking C executable demo.elf`,`demo.elf` 存在。
|
|
1959
|
+
|
|
1960
|
+
先失败、后成功,两遍都是真跑了 arm-none-eabi-gcc + ninja;这是「修复确实治好了那个症状」的唯一硬证据。副本与临时脚本用完丢回收站。
|
|
1961
|
+
|
|
1962
|
+
### 26.4 验证过程里又抓到两个真缺陷
|
|
1963
|
+
|
|
1964
|
+
- 注释里的 `#define` 被当成启用:真实 `stm32f1xx_hal_conf.h` 里没用到的模块写的是 `/*#define HAL_ADC_MODULE_ENABLED */`,正则照样命中,于是第一次刷新把整个 HAL 的 30 多个 `.c` 全加进了清单(差分验证第 3 步一开始看到的是 30 条 added)。修法:匹配前先 `stripComments`(块注释 + 行注释),并补一条回归用例(三个注释形态 + 源码里被注释掉的 `#include` 都不算)。
|
|
1965
|
+
- 行尾混排导致整文件重写:`demo` 这份文件的 86 行里 6 行 CRLF、80 行 LF,而 `readTextFile` 的 `eol` 是「含 CRLF 就算 CRLF」→ 内容一个字没改,写出来却是全文件翻成 CRLF;再加上「按行切完末尾多一个空串」没摘,每跑一次多一个空行,幂等直接断掉。修法:`dominantEol` 按多数行尾决定写回值、比较时只比内容不比行尾、切完 `pop()` 掉末尾空串。现在对真实 `demo` 跑 dryRun 报「已是最新」,字节不动。
|
|
1966
|
+
### 26.5 测试与计数
|
|
1967
|
+
|
|
1968
|
+
新套件 `test/cmake-sources-units.test.mjs`(15 例):设备宏/家族反推、启动文件排序、原样工程零写入、换芯片(startup + 设备宏一起换、旧 startup 从清单摘掉)、开 UART 只加真存在的 `hal_uart.c` 且第二次幂等、hal_conf 开着但驱动包缺 `.c` 时只进 notes、hal_conf 里那一圈 `#include` 不算用到、源码手写 `#include` 也算、ADC 连 `_ex` 一起加、删掉的驱动文件从清单摘除、dryRun 不写盘、非 CMake 布局/无启动文件 `ok=false`、注释掉的 `#define` 不算启用、CRLF/LF 混排零写入,以及一条接线回归(伪造 `cubemx/jre/bin/java.exe` + 缓存命中,`runGenerate` 在 `skipped=true` 时也必须把 `hal_uart.c` 写进清单);`test/run-units.mjs` 已登记。
|
|
1969
|
+
|
|
1970
|
+
`npm run build` exit 0;`npm test` → **25 套件 363 pass / 0 fail**(CI 361 + 2 skipped);`npm run test:pack` exit 0(16 个必须文件齐全、解包产物能建寄存器工程)。README / README_EN / `reading-guide.md` 第 9 章已同步到 363 / 361。
|
|
1971
|
+
## 27. F1 全系第一步:src/data/stm32f1.ts(2026-10-30)
|
|
1972
|
+
|
|
1973
|
+
### 27.1 为什么先做这一层
|
|
1974
|
+
|
|
1975
|
+
扩 F1 全系的最小切口不是改工具,而是把「型号 → 启动文件 / 设备宏 / 容量」这条事实单独拎出来。原来这条映射散在 src/data/cmsis-sources.ts:105-123 的 startupChoiceFor(只认 STM32F103 加三个字母)和 src/data/chips.ts 的一张 C8T6 引脚表里。
|
|
1976
|
+
|
|
1977
|
+
### 27.2 数据来源(优先级)
|
|
1978
|
+
|
|
1979
|
+
1. 固件包 Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc 里真实存在的启动文件——实测 14 个:f100xb/xe、f101x6/xb/xe/xg、f102x6/xb、f103x6/xb/xe/xg、f105xc、f107xc。设备头在同级 Include/,14 个同名(没有 f106)。
|
|
1980
|
+
2. 本机 CubeMX db/mcu/*.xml(Flash/RAM/引脚数,将来做校验用)。
|
|
1981
|
+
3. 文件内置的容量字母表。
|
|
1982
|
+
### 27.3 两个真坑(都是实测暴露的)
|
|
1983
|
+
|
|
1984
|
+
- 容量字母到容量档不是全局映射:字母 C 在 F103 上是 xE(startup_stm32f103xe.s),在 F105/F107 上却是 xC(startup_stm32f105xc.s)。第一版用全局表直接映射,STM32F107VCT6 被判成「没有 xe 这一档」而返回 null。修法:chooseGroup 先试「该 line 真有 x 加字母」,不行再退回全局表。
|
|
1985
|
+
- F106 不存在:最初凭「F105/F106 共用」的旧笔记加了 code 106,结果对着固件包实测没有 startup_stm32f106xc.s,测试直接红。删掉该 line——宁可少一条,也不要编一个上游没有的文件。
|
|
1986
|
+
|
|
1987
|
+
### 27.4 接口与边界
|
|
1988
|
+
|
|
1989
|
+
resolveF1Chip(input) 支持三种输入:完整型号(STM32F103RCT6)、去掉温度后缀(STM32F103C8)、显式容量档(F103:xb)。返回 { chip, reason }:认不出时 chip=null 且 reason 是人话(「F107 没有 xb 这一容量档(上游真实档位:xc)」这种),绝不返回一个不存在的启动文件名。
|
|
1990
|
+
|
|
1991
|
+
RAM 表按「line:容量字母」而不是按容量档——xE 跨 C/D/E 三个字母,RAM 分别是 48/64/64 KiB;查不到就 ramBytes=null 并进 notes,不猜数字。
|
|
1992
|
+
### 27.5 验证
|
|
1993
|
+
|
|
1994
|
+
test/stm32f1-units.test.mjs 11 例:C8T6 与既有事实一致、RCT6 走 xE、C/D/E 三字母 RAM 不同、F107 只有 xC、不存在的档位明确拒绝、未知 line 与坏格式与空输入与坏封装后缀都给原因、无温度后缀也认、F103:xb 与完整型号同解、6 条 line 的每个档位都能反推回启动文件名、RAM 未收录只给 note,以及「本机有固件包时,14 个组合的启动文件与设备头都真实存在」(CI 上自动 skip)。
|
|
1995
|
+
|
|
1996
|
+
npm run build exit 0;npm test 26 套件 374 pass / 0 fail(CI 372 + 2 skipped)。README / README_EN / reading-guide.md 第 9 章已同步。
|
|
1997
|
+
|
|
1998
|
+
## 28. F1 全系落地:HAL/寄存器两条路 + 时钟并入 .ioc 事务 + 薄表(2026-10-30)
|
|
1999
|
+
|
|
2000
|
+
§27 把「型号 → 启动文件 / 设备宏 / 容量」抽成了一张事实表,这一批把这张表接到三条链路上(HAL 建工程、寄存器建工程、.ioc 时钟事务),再加一层一致性护栏与一份全族薄表。四件事各自独立可回退,改动没有新开工具:时钟走的是既有的 `stm32_ioc_plan`,薄表是新脚本产出的数据文件。
|
|
2001
|
+
|
|
2002
|
+
### 28.1 t1:HAL 路线不再写死 C8T6(新增 src/engine/hal-chip.ts,284 行)
|
|
2003
|
+
|
|
2004
|
+
原来的 scaffold 把三个型号相关的文件写死在代码里:`startup_stm32f103xb.s`(拷哪个启动文件)、`STM32F103XX_FLASH.ld`(链接脚本)、`demo.ioc`(工程名与 MCU 字段)。这三处现在都改成**按芯片渲染**。
|
|
2005
|
+
|
|
2006
|
+
`src/engine/hal-chip.ts` 只有两件事:派生与渲染,全是字符串函数(不起进程、不写盘),所以能在**写盘之前**把整份产物渲染完——渲染失败时一个字节都不落盘,不会留下半截工程。
|
|
2007
|
+
|
|
2008
|
+
- `resolveHalChip(input)`:型号 → 启动文件 / 设备宏 / `.ld` 名 / 包名(复用 §27 的 `resolveF1Chip`,认完整型号、去温度后缀、`F103:xb`)。
|
|
2009
|
+
- `renderStartupAndDefine`:`STM32F103RCT6 → startup_stm32f103xe.s + STM32F103xE`。
|
|
2010
|
+
- `renderLinkerScript`:把模板的 MEMORY 两行(RAM / FLASH)与注释两行换成 `STM32F103RCTx_FLASH.ld`,256 KiB / 48 KiB。
|
|
2011
|
+
- `renderIoc`:demo.ioc 的 `Mcu.CPN`、引脚与时钟键一起按型号重写。
|
|
2012
|
+
- `pointLinkerFlagAt`:工具链文件里写死的 `-T STM32F103XX_FLASH.ld` 改成指向新名。**这一步不做就完蛋**——要么链到旧脚本(容量不对),要么命令行上出现两个 `-T`(链哪个看顺序)。
|
|
2013
|
+
|
|
2014
|
+
链接脚本从这一批起按 `<DeviceId>_FLASH.ld` 命名:
|
|
2015
|
+
|
|
2016
|
+
| 型号 | 启动文件 | 设备宏 | 链接脚本 | Flash / RAM |
|
|
2017
|
+
| --- | --- | --- | --- | --- |
|
|
2018
|
+
| STM32F103C8T6 | startup_stm32f103xb.s | STM32F103xB | STM32F103C8Tx_FLASH.ld | 64 / 20 KiB |
|
|
2019
|
+
| STM32F103RCT6 | startup_stm32f103xe.s | STM32F103xE | STM32F103RCTx_FLASH.ld | 256 / 48 KiB |
|
|
2020
|
+
| STM32F107VCT6 | startup_stm32f107xc.s | STM32F107xC | STM32F107VCTx_FLASH.ld | 256 / 64 KiB |
|
|
2021
|
+
|
|
2022
|
+
旧名 `templates/scaffold/STM32F103XX_FLASH.ld` 保留为 **C8T6 的兼容副本**(`templates/` 的文件数没变,scaffold 的文件数断言仍 15),但 cmake 的 `-T` 一律指向按型号命名的那份。
|
|
2023
|
+
|
|
2024
|
+
实测(真建工程):RCT6 → `startup_stm32f103xe.s` / `STM32F103xE` / `STM32F103RCTx_FLASH.ld`(256 KiB、48 KiB);F107VCT6 → `startup_stm32f107xc.s` / `STM32F107xC` / `STM32F107VCTx_FLASH.ld`(256 KiB、64 KiB);C8T6 不回归(`templateFiles` 仍 15,链接脚本换成 `STM32F103C8Tx_FLASH.ld`)。
|
|
2025
|
+
|
|
2026
|
+
### 28.2 t2:寄存器路线泛化到 14 个容量档
|
|
2027
|
+
|
|
2028
|
+
`src/data/cmsis-sources.ts`(392 行)重写。三处要点:
|
|
2029
|
+
|
|
2030
|
+
1. `startupChoiceFor(mcu)` 不再自己认型号,改成委托 `resolveF1Chip`,并保留旧写法的兼容解析:`F1:B`、`F1:8`、`F103:xb`、`STM32F103C8T6` 四种输入同解。老工程里缓存过的条目 id(`F1:B` 那种)也能读。
|
|
2031
|
+
2. `STARTUP_SHA256` 从 1 条变 14 条,**全部是真实下载后算的**(2026-10-30 UTC)。来源:`https://fastly.jsdelivr.net/gh/STMicroelectronics/cmsis-device-f1@master/Source/Templates/gcc/<startup>.s`,备用 `cdn.jsdelivr.net` / `raw.githubusercontent.com` / `ghproxy.net`。sha256 表里连文件字节数一起记,失败信息能直接告诉你「是上游挪了内容还是网络换了页面」。
|
|
2032
|
+
3. 缓存条目 id 改成 `cmsis:F1:103xb`(族 + 容量档),`chipEntryId` / `parseCmsisEntryRef` / `cmsisEntryAliases` 三件套负责新旧 id 互认。
|
|
2033
|
+
|
|
2034
|
+
另两个新模块:
|
|
2035
|
+
|
|
2036
|
+
- `src/engine/register-clock.ts`(261 行):寄存器版的时钟代码生成。每条 line 的最高 SYSCLK 不同——**F100 24 / F101 36 / F102 48 / F103·F105·F107 72 MHz**;HSE 8 MHz 乘到上限(F101 走 HSE/2×9 才凑得出 36 MHz);FLASH latency 按频率给 0/1/2(F100 的设备头里没有 latency 字段,自动跳过);APB1 在 >36 MHz 时 ÷2;HSE 起不来就退到 HSI/2×N 并写警告。生成的 `clock_init()` 插在 main() 第一行,末尾 `SystemCoreClockUpdate()` 让 SysTick 与 delay_ms 跟着对。
|
|
2037
|
+
- `src/engine/register-linker.ts`(152 行):按型号渲 `<DeviceId>_FLASH.ld`(改 MEMORY 的 RAM/FLASH 两行 + 注释两行)。F100/F101/F102 的 RAM 不在 §27 的表里,这里用 CubeMX db 的最小值兜底**并明确警告**——宁可报小,也不要让栈跑出真 RAM。
|
|
2038
|
+
|
|
2039
|
+
于是寄存器路线对 F1 的 14 个容量档全部可用,且**不需要 CubeMX、不需要固件包**,只靠下载缓存(第二次起完全离线)。
|
|
2040
|
+
|
|
2041
|
+
### 28.3 t3:时钟配置并入 stm32_ioc_plan(不新开工具)
|
|
2042
|
+
|
|
2043
|
+
为什么不做成 `stm32_clock_plan`:时钟改动本来就是改 .ioc 键,而 .ioc 只能走「plan → 用户确认 → apply」这一条事务。新开工具等于让用户可以绕过 SHA 校验直接写时钟。
|
|
2044
|
+
|
|
2045
|
+
新增两张:`src/data/clock-f1.ts`(215 行,事实:PLL 源 HSE 8 MHz / HSI÷2 4 MHz / HSI 8 MHz、×2..×16、上限 SYSCLK 72 / APB1 36 / APB2 72 / ADC 14 / USB 48、APB1/APB2/ADC 分频表、14 条外设→总线、UART 波特率档、20 个 RCC IPParameters)与 `src/engine/clock-plan.ts`(801 行,求解)。
|
|
2046
|
+
|
|
2047
|
+
求解顺序:枚举全部可行组合 → 取 `|sysclk − target|` 最小(**同距取更高档**,所以 60 MHz 的目标落在 64 MHz,而不是 56 MHz)→ 与 .ioc 现有键做 diff → 派生键**全量重算** → 给逐外设频率表、UART 波特率整除误差、备选档位。
|
|
2048
|
+
|
|
2049
|
+
`mode` 四态:`snapshot`(只看不写,未请求时钟时的缺省)/ `nearest`(就近)/ `explicit`(钉死倍频)/ `none`。任何早退分支都必须带 `clockPlan`(`IocPlanReport.clockPlan` 是必填字段,不是 `null`),这样报告形状统一、schema 不用多态。
|
|
2050
|
+
|
|
2051
|
+
实测(真实 `test/fixtures/project/demo.ioc`,`clock: { targetHz: 60000000 }`,dry plan 未 apply):
|
|
2052
|
+
|
|
2053
|
+
- planId `b4f83c6165de72f7`,17 个键变化(新增 1、删除 0、修改 16);
|
|
2054
|
+
- 结论:目标 60 MHz **不可达**,已选 64 MHz(差 +4 MHz)。F1 的 PLL 只能整数倍频(×2..×16),HSE 8 MHz 拼不出这一档;HSI÷2 4 MHz ×15 正好 60 MHz,但 HSI 精度 ±1% 会把 UART 一起带漂,所以默认没选它(备选里能看到);
|
|
2055
|
+
- 总线:SYSCLK 64 / HCLK 64 / APB1 32(÷2,定时器 64)/ APB2 64(÷1)/ ADC 10.667 MHz(÷6,.ioc 里写成 10666667)/ USB 不可用;
|
|
2056
|
+
- 逐外设:USART1@64、SPI1@64、TIM1@64、ADC1/2@10.667;USART2/3@32、SPI2@32、I2C1/2@32、TIM2/3/4@64;
|
|
2057
|
+
- 波特率误差(16 倍过采样):USART1@64 MHz 最差 115200 −0.080%,USART2@32 MHz 最差 57600 −0.080%;
|
|
2058
|
+
- 写入 21 个 RCC 键(含 `RCC.IPParameters` 合并),源 .ioc 未被修改(`ok=true` 但 dry)。
|
|
2059
|
+
|
|
2060
|
+
错误路径是硬的:SYSCLK >72 / APB1 >36 / ADC >14 时**一个键都不写**,只报错并给最近可行档位。
|
|
2061
|
+
|
|
2062
|
+
### 28.4 t4:doctor 五项一致性 + 引脚表从本机 db 派生
|
|
2063
|
+
|
|
2064
|
+
`src/engine/doctor.ts`(665 行,+382)加了 `checkChipConsistency` / `collectChipConsistency`,比原计划的四项多拆一项:
|
|
2065
|
+
|
|
2066
|
+
1. 芯片型号 ↔ 启动文件名(例:RCT6 却只有 `startup_stm32f103xb.s` → blocker,并写出该有的名字);
|
|
2067
|
+
2. 启动文件 ↔ cmake 设备宏(`STM32F103xB` 配 xE 启动文件 → blocker,提示重跑 `stm32_generate`);
|
|
2068
|
+
3. `.ld` 的 MEMORY ↔ 芯片实际容量(小于芯片 → note「浪费了 N KiB」;大于 → blocker,RAM 同理);
|
|
2069
|
+
4. `.elf` 的 Flash 占用 ↔ Flash 容量(超了 → blocker,≥90% → note);
|
|
2070
|
+
5. .ioc 用到的引脚是否在封装里(本机 db 有封装表时才算)。
|
|
2071
|
+
|
|
2072
|
+
第四项踩了个真坑:**别用 .elf 文件大小判超 Flash**。工作区里那个正经 C8T6 工程,`.elf` 有 641.5 KiB——全是 `-g3` 的调试信息,按文件大小判会把 64 KiB 的芯片判成超容量。改成读 ELF program header,只累加 `p_paddr` 落在 `0x08000000` 起 1 MiB 的 `PT_LOAD` 的 `p_filesz`,同一工程立刻变成 0 blocker。解析不出 program header 时才退回文件大小,并在 notes 里注明「按文件大小粗算」。
|
|
2073
|
+
|
|
2074
|
+
`src/data/chips.ts`(202 行,+162):保留原 `CHIPS` / `findChip` / `isKnownPin` 的语义(未知型号一律放行,不猜、不误拦),新增 `parseMcuDbXmlPins`(`<Pin Name= Position=>`,`Position<=0` 的虚拟脚丢弃,`PC13-TAMPER-RTC → PC13`,电源脚不算)、`findMcuDbDir`(`<CubeMX>/db/mcu`)、`readMcuDbPins`、`deriveChipPinTable({cpn, mcuName, dbMcuDir})` → `kind: db / builtin / unknown`:db 命中就注明来源 XML 与引脚数,否则明说「未与本机 db 校验」,都没有就说明未知引脚一律放行。
|
|
2075
|
+
|
|
2076
|
+
### 28.5 包体三分法与护栏
|
|
2077
|
+
|
|
2078
|
+
这一批开始往仓库里加东西(薄表、图、脚本),先把「什么东西放哪」定下来,否则包体迟早失控:
|
|
2079
|
+
|
|
2080
|
+
| 类别 | 内容 | 实测 |
|
|
2081
|
+
| --- | --- | --- |
|
|
2082
|
+
| 随 npm 包 | `lib/**`(含 `lib/client.js`)、`client/client.js`、`templates/scaffold/**`、`cordis.patch.yml`、两份 README、LICENSE、`docs/*.md` | tarball 525.7 KB / 99 个文件,解包 1538.3 KB,templates/** 38.5 KB |
|
|
2083
|
+
| 进 git 不进包 | `src/**`、`test/**`、`scripts/**`、`docs/diagrams/**` | diagrams 2 MB 原始 / 891 KB gz;`package.json` 的 files 从 `docs` 收窄成 `docs/*.md` |
|
|
2084
|
+
| 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头、HAL 固件包 | 带 sha256 校验,缓存在本机 |
|
|
2085
|
+
| 现造 | `.ioc` 内容(`renderIoc`)、`.ld` MEMORY(`renderLinkerScript`)、cmake 源清单(`refreshCubemxCmakeLists`) | 不进包,按型号生成 |
|
|
2086
|
+
|
|
2087
|
+
护栏是 `scripts/pack-size.mjs`(80 行,`npm run test:size`,CI 在 `test:pack` 之后跑):tarball ≤1.2 MB、`templates/**` ≤60 KB、包内禁止 png/jpg/jpeg/gif/webp/bmp/pdf/html/zip/7z/exe/dll、必须含 README.md / README_EN.md / LICENSE / cordis.patch.yml / docs/reading-guide.md。它用 `npm pack --dry-run --json` 拿文件清单,不写盘。
|
|
2088
|
+
|
|
2089
|
+
### 28.6 芯片薄表:scripts/gen-chip-table.mjs(371 行)
|
|
2090
|
+
|
|
2091
|
+
目标是一份「不联网、不依赖 CubeMX 运行时」的芯片事实表,供将来扩族时查容量与封装,也方便人肉核对。
|
|
2092
|
+
|
|
2093
|
+
- 来源:本机 CubeMX 的 `db/mcu/*.xml`(2019 个 xml,其中 `compatibility.xml` / `families.xml` / `rules.xml` 不是 MCU,真正 2016 颗;F1 系 58 个)。
|
|
2094
|
+
- XML 里**没有 CPN 字段**,只有 `RefName` 模式(`STM32F103C(8-B)Tx` 这种带备选字母的写法),文件名 = `Mcu.Name` = `.ioc` 里的 join key,CPN 由 RefName 展开派生。
|
|
2095
|
+
- 输出 `src/data/chip-table.json`:2016 行、157546 字节(gz 后约 10 KB),字段为 CPN / 内核 / 主频 / RAM / Flash / 电压 / 引脚数。文件头写明「脚本生成,不要手改」,并注明插件当前只消费 F1 那一段、其余为将来扩族备查。
|
|
2096
|
+
- `--check` 模式:重新从 db 抽一遍,与已落盘的文件比对,不一致就 exit 1(给 CI 用)。
|
|
2097
|
+
- 安装位置不必手填:`--mcu-dir` > `--cube-mx-root` > `STM32_CUBEMX_ROOT` > `~/.dsh-stm32/config.json` 的 `cubeMxRoot` > 默认位置 > 扫盘发现(本机 CubeMX 装在 `D:/app/STM32CubeMX`,就是靠扫盘找到的——只扫目录、不读注册表,扫不到就让人用 `--cube-mx-root` 指过来)。
|
|
2098
|
+
- 读不到 db(没装 CubeMX / 路径不对)时**明确报错退出,不写半截文件**(先写临时文件再 rename,校验通过才替换)。
|
|
2099
|
+
|
|
2100
|
+
### 28.7 文档口径
|
|
2101
|
+
|
|
2102
|
+
README / README_EN / `docs/reading-guide.md` / `src/skill/stm32-workflow.ts` 里「只支持 STM32F103C8T6」的说法全部改口成 **F1 全系**(F100/101/102/103/105/107),并补了两件最容易漏的事:
|
|
2103
|
+
|
|
2104
|
+
- **链接脚本命名规则**:`<DeviceId>_FLASH.ld`(`STM32F103C8Tx_FLASH.ld` / `STM32F103RCTx_FLASH.ld` / `STM32F107VCTx_FLASH.ld`),旧名 `STM32F103XX_FLASH.ld` 只是 C8T6 的兼容副本;命令行上只能有一个 `-T`。
|
|
2105
|
+
- **时钟就近策略**:目标频率不可达时选最接近的一档并**显式标注差多少**(60 MHz → 「不可达,已选 64 MHz(+4 MHz)」),同距取更高档;派生键全量重算;超限一个键都不写。
|
|
2106
|
+
|
|
2107
|
+
skill 的 R2 现在点名「本型号的启动文件 + 本型号的 `.ld`」,R3 补了时钟走同一条事务,`§四 踩过的坑` 加了两条:裸 `cmake -S . -B build` 不读 `CMakePresets.json` 会丢工具链文件(必须 `cmake --preset default` 或显式 `-DCMAKE_TOOLCHAIN_FILE`);换芯片后别留旧链接脚本名(`-T` 两个 .ld 时链哪个看顺序,症状是「编译过、上板跑飞」)。
|
|
2108
|
+
|
|
2109
|
+
### 28.8 验证
|
|
2110
|
+
|
|
2111
|
+
- `npm run build` → exit 0。
|
|
2112
|
+
- `npm test` → **29 套件 418 pass / 0 fail**(CI 上 416 pass + 2 skipped);本批新登记 `hal-route-units`(12 例)、`clock-units`(14 例)、`doctor-chip-units`(15 例),既有套件未回归。
|
|
2113
|
+
- `node scripts/gen-chip-table.mjs --check` → exit 0(生成物与 db 一致)。
|
|
2114
|
+
- `npm run test:size` → exit 0(tarball 525.7 KB / 上限 1171.9 KB,templates 38.5 KB / 上限 60 KB)。
|
|
736
2115
|
|
|
2116
|
+
注:§27.5 里的「26 套件 374 例」是当时的数,现在是 29 套件 418 例(captain 口径里的 28 个套件少算了 `schema-guard`);§27.3 的坑、§27.4 的接口都还成立,只是 `startupChoiceFor` 现在委托给 `resolveF1Chip` 了。
|