dsh-stm32 0.1.1 → 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.
Files changed (42) hide show
  1. package/README.md +52 -23
  2. package/README_EN.md +50 -21
  3. package/docs/development-notes.md +466 -4
  4. package/docs/reading-guide.md +738 -0
  5. package/lib/commands/register.js +49 -0
  6. package/lib/data/chips.js +134 -4
  7. package/lib/data/clock-f1.js +158 -0
  8. package/lib/data/cmsis-sources.js +211 -42
  9. package/lib/data/f1-ram.generated.js +34 -0
  10. package/lib/data/stm32f1.js +186 -0
  11. package/lib/engine/build.js +115 -16
  12. package/lib/engine/cache.js +56 -0
  13. package/lib/engine/clock-plan.js +608 -0
  14. package/lib/engine/cmake-sources.js +428 -0
  15. package/lib/engine/debug.js +75 -10
  16. package/lib/engine/doctor.js +395 -4
  17. package/lib/engine/fetch.js +174 -30
  18. package/lib/engine/flash.js +95 -6
  19. package/lib/engine/generate.js +11 -0
  20. package/lib/engine/hal-chip.js +230 -0
  21. package/lib/engine/ioc-plan.js +28 -2
  22. package/lib/engine/msys2-install.js +332 -61
  23. package/lib/engine/project-export.js +129 -0
  24. package/lib/engine/register-clock.js +132 -0
  25. package/lib/engine/register-linker.js +129 -0
  26. package/lib/engine/register-template.js +88 -17
  27. package/lib/engine/scaffold.js +104 -28
  28. package/lib/engine/zip.js +142 -0
  29. package/lib/index.js +2 -0
  30. package/lib/skill/stm32-workflow.js +3 -3
  31. package/lib/tools/build.js +12 -0
  32. package/lib/tools/cache.js +39 -8
  33. package/lib/tools/debug.js +7 -0
  34. package/lib/tools/doctor.js +11 -2
  35. package/lib/tools/flash.js +3 -0
  36. package/lib/tools/ioc-plan.js +195 -4
  37. package/lib/tools/project-create.js +26 -1
  38. package/lib/tools/project-export.js +100 -0
  39. package/package.json +5 -3
  40. package/templates/register/CMakeLists.txt +19 -6
  41. package/templates/register/Core/Src/main.c +18 -9
  42. package/templates/scaffold/openocd.cfg +8 -0
@@ -4,7 +4,9 @@
4
4
  > 面向使用者的说明已移到仓库根目录的 [README.md](../README.md)。
5
5
  # dsh-stm32
6
6
 
7
- DSH 插件(宿主侧,无 UI):把 STM32(当前只支持 STM32F103C8T6)的 **环境探测 → .ioc 事务 → 生成工程 → 编译 → 烧录 → 调试** 变成一组可被模型调用的工具。
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 # 可选:80 个离线用例
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` 覆盖。当前只支持 **STM32F103C8T6**(引脚表见 [`src/data/chips.ts`](src/data/chips.ts))。
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
@@ -1644,11 +1646,471 @@ blocked 时的 `message` 是一句人话,不是字段堆砌:
1644
1646
 
1645
1647
  `install-units` 17 → **21 例**,按加入顺序:①「已有完整 MSYS2 + 5 个组件 → 说『什么都不用装』、`download.bytes` 为 0」;②「只缺 1 个包 → 只说 `openocd`、不列已装的 4 个」;③「pacman 问不出来(超时 / 报错)→ 不猜缺哪个,只说真装时会先问」;④「缺 CubeMX → 紧凑卡片补一句 HAL 提示,装了就不补」。既有那例「计划里的 pacman 步骤说的是真会跑的事」跟着改了断言:计划模式允许**一条**只读查询,但绝不能出现 `pacman -S` / `-Sy`。
1646
1648
 
1647
- **24 套件 309 pass / 0 fail**(CI 307 + 2 skipped)。README / README_EN 的计数同步到 309。
1649
+ **24 套件 318 pass / 0 fail**(CI 316 + 2 skipped)。README / README_EN 的计数同步到 318。
1648
1650
 
1649
1651
  **还没验证的**:重启 DSH 后在面板里点「生成安装计划」,确认卡片首句变成「什么都不用装」。
1650
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)」),同距取更高档;派生键全量重算;超限一个键都不写。
1651
2106
 
2107
+ skill 的 R2 现在点名「本型号的启动文件 + 本型号的 `.ld`」,R3 补了时钟走同一条事务,`§四 踩过的坑` 加了两条:裸 `cmake -S . -B build` 不读 `CMakePresets.json` 会丢工具链文件(必须 `cmake --preset default` 或显式 `-DCMAKE_TOOLCHAIN_FILE`);换芯片后别留旧链接脚本名(`-T` 两个 .ld 时链哪个看顺序,症状是「编译过、上板跑飞」)。
1652
2108
 
2109
+ ### 28.8 验证
1653
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)。
1654
2115
 
2116
+ 注:§27.5 里的「26 套件 374 例」是当时的数,现在是 29 套件 418 例(captain 口径里的 28 个套件少算了 `schema-guard`);§27.3 的坑、§27.4 的接口都还成立,只是 `startupChoiceFor` 现在委托给 `resolveF1Chip` 了。