dsh-stm32 0.1.3 → 0.1.5
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 +115 -43
- package/README_EN.md +106 -38
- package/assets/README.md +85 -0
- package/assets/VERSION +1 -0
- package/assets/device/c0/chips.json +1108 -0
- package/assets/device/f0/chips.json +1570 -0
- package/assets/device/f1/chips.json +1238 -0
- package/assets/device/f1/svd/100.json +943 -0
- package/assets/device/f1/svd/101.json +901 -0
- package/assets/device/f1/svd/102.json +522 -0
- package/assets/device/f1/svd/103.json +1139 -0
- package/assets/device/f1/svd/105.json +1117 -0
- package/assets/device/f1/svd/107.json +1195 -0
- package/assets/device/f2/chips.json +674 -0
- package/assets/device/f3/chips.json +1318 -0
- package/assets/device/f4/chips.json +2942 -0
- package/assets/device/f7/chips.json +1710 -0
- package/assets/device/g0/chips.json +2102 -0
- package/assets/device/g4/chips.json +2494 -0
- package/assets/device/h5/chips.json +898 -0
- package/assets/device/h7/chips.json +2639 -0
- package/assets/device/l0/chips.json +2494 -0
- package/assets/device/l1/chips.json +1234 -0
- package/assets/device/l4/chips.json +2130 -0
- package/assets/device/l4+/chips.json +856 -0
- package/assets/device/l5/chips.json +226 -0
- package/assets/device/u0/chips.json +688 -0
- package/assets/device/u3/chips.json +310 -0
- package/assets/device/u5/chips.json +1195 -0
- package/assets/device/wba/chips.json +506 -0
- package/assets/device/wl/chips.json +184 -0
- package/assets/headers/f1/stm32f100xb.h +5972 -0
- package/assets/headers/f1/stm32f100xe.h +6587 -0
- package/assets/headers/f1/stm32f101x6.h +5315 -0
- package/assets/headers/f1/stm32f101xb.h +5446 -0
- package/assets/headers/f1/stm32f101xe.h +6503 -0
- package/assets/headers/f1/stm32f101xg.h +6713 -0
- package/assets/headers/f1/stm32f102x6.h +6448 -0
- package/assets/headers/f1/stm32f102xb.h +6570 -0
- package/assets/headers/f1/stm32f103x6.h +10109 -0
- package/assets/headers/f1/stm32f103xb.h +10240 -0
- package/assets/headers/f1/stm32f103xe.h +11767 -0
- package/assets/headers/f1/stm32f103xg.h +11951 -0
- package/assets/headers/f1/stm32f105xc.h +14340 -0
- package/assets/headers/f1/stm32f107xc.h +15253 -0
- package/assets/headers/f1/stm32f1xx.h +273 -0
- package/assets/headers/f1/system_stm32f1xx.h +96 -0
- package/assets/ioc/family/C0.ioc +82 -0
- package/assets/ioc/family/F0.ioc +71 -0
- package/assets/ioc/family/F2.ioc +91 -0
- package/assets/ioc/family/F3.ioc +94 -0
- package/assets/ioc/family/F4.ioc +91 -0
- package/assets/ioc/family/F7.ioc +102 -0
- package/assets/ioc/family/G0.ioc +90 -0
- package/assets/ioc/family/G4.ioc +110 -0
- package/assets/ioc/family/H5.ioc +116 -0
- package/assets/ioc/family/H7.ioc +133 -0
- package/assets/ioc/family/L0.ioc +92 -0
- package/assets/ioc/family/L1.ioc +87 -0
- package/assets/ioc/family/L4+.ioc +92 -0
- package/assets/ioc/family/L4.ioc +93 -0
- package/assets/ioc/family/L5.ioc +91 -0
- package/assets/ioc/family/U0.ioc +103 -0
- package/assets/ioc/family/U3.ioc +113 -0
- package/assets/ioc/family/U5.ioc +102 -0
- package/assets/ioc/family/WBA.ioc +100 -0
- package/assets/ioc/family/WL.ioc +93 -0
- package/assets/ioc/minimal/STM32F100C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F100RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101RFTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F102C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F102C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103RFTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F105RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F107RCTx.ioc +113 -0
- package/assets/ld/f1/STM32F100C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F100RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101RFTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F102C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F102C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103RFTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F105RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F107RCTx_FLASH.ld +249 -0
- package/assets/manifest.json +1130 -0
- package/assets/startup/f1/startup_stm32f100xb.s +407 -0
- package/assets/startup/f1/startup_stm32f100xe.s +449 -0
- package/assets/startup/f1/startup_stm32f101x6.s +322 -0
- package/assets/startup/f1/startup_stm32f101xb.s +338 -0
- package/assets/startup/f1/startup_stm32f101xe.s +423 -0
- package/assets/startup/f1/startup_stm32f101xg.s +439 -0
- package/assets/startup/f1/startup_stm32f102x6.s +330 -0
- package/assets/startup/f1/startup_stm32f102xb.s +346 -0
- package/assets/startup/f1/startup_stm32f103x6.s +348 -0
- package/assets/startup/f1/startup_stm32f103xb.s +364 -0
- package/assets/startup/f1/startup_stm32f103xe.s +470 -0
- package/assets/startup/f1/startup_stm32f103xg.s +466 -0
- package/assets/startup/f1/startup_stm32f105xc.s +463 -0
- package/assets/startup/f1/startup_stm32f107xc.s +472 -0
- package/assets/templates/family/C0.ioc +82 -0
- package/assets/templates/family/F0.ioc +71 -0
- package/assets/templates/family/F2.ioc +91 -0
- package/assets/templates/family/F3.ioc +94 -0
- package/assets/templates/family/F4.ioc +91 -0
- package/assets/templates/family/F7.ioc +102 -0
- package/assets/templates/family/G0.ioc +90 -0
- package/assets/templates/family/G4.ioc +110 -0
- package/assets/templates/family/H5.ioc +116 -0
- package/assets/templates/family/H7.ioc +133 -0
- package/assets/templates/family/L0.ioc +92 -0
- package/assets/templates/family/L1.ioc +87 -0
- package/assets/templates/family/L4+.ioc +92 -0
- package/assets/templates/family/L4.ioc +93 -0
- package/assets/templates/family/L5.ioc +91 -0
- package/assets/templates/family/U0.ioc +103 -0
- package/assets/templates/family/U3.ioc +113 -0
- package/assets/templates/family/U5.ioc +102 -0
- package/assets/templates/family/WB.ioc +81 -0
- package/assets/templates/family/WBA.ioc +100 -0
- package/assets/templates/family/WL.ioc +93 -0
- package/docs/reading-guide.md +110 -42
- package/lib/commands/register.js +1 -1
- package/lib/data/chips.js +3 -3
- package/lib/data/clock-db.js +830 -0
- package/lib/data/clock-f1.js +12 -45
- package/lib/data/cmsis-sources.js +371 -18
- package/lib/data/db-presets.js +252 -0
- package/lib/data/device-facts.js +113 -26
- package/lib/data/family.js +515 -0
- package/lib/data/firmware-packages.js +595 -12
- package/lib/data/firmware-pins.js +128 -0
- package/lib/data/install-guides.js +2 -2
- package/lib/data/ioc-presets.js +248 -0
- package/lib/data/ioc-schema.js +1058 -0
- package/lib/data/rm-topics/stm32c0.json +227 -0
- package/lib/data/rm-topics.js +103 -0
- package/lib/data/search-roots.js +59 -4
- package/lib/data/serial-config.js +430 -0
- package/lib/data/stm32f1.js +15 -14
- package/lib/data/svd.js +32 -16
- package/lib/data/toolchain-config.js +0 -14
- package/lib/engine/assets.js +191 -456
- package/lib/engine/breakpoints.js +66 -11
- package/lib/engine/clock-derived.js +101 -0
- package/lib/engine/clock-direct.js +313 -0
- package/lib/engine/clock-plan.js +96 -52
- package/lib/engine/clock-pllmn.js +319 -0
- package/lib/engine/cmake-sources.js +67 -13
- package/lib/engine/cube-mx-guard.js +44 -0
- package/lib/engine/cube-programmer.js +137 -0
- package/lib/engine/cubemx-db.js +273 -0
- package/lib/engine/debug-session.js +423 -17
- package/lib/engine/debug.js +25 -6
- package/lib/engine/doctor.js +239 -19
- package/lib/engine/download.js +242 -0
- package/lib/engine/facts-acquire.js +416 -0
- package/lib/engine/facts.js +134 -0
- package/lib/engine/fetch.js +1 -1
- package/lib/engine/firmware-install.js +333 -39
- package/lib/engine/firmware-official.js +499 -0
- package/lib/engine/flash.js +290 -21
- package/lib/engine/gdb-mi.js +476 -0
- package/lib/engine/generate.js +9 -2
- package/lib/engine/hal-chip.js +124 -41
- package/lib/engine/ioc-plan.js +1244 -60
- package/lib/engine/ioc-rules.js +698 -0
- package/lib/engine/ioc-verify.js +706 -0
- package/lib/engine/ioc.js +43 -4
- package/lib/engine/msys2-install.js +241 -92
- package/lib/engine/probe-error.js +25 -6
- package/lib/engine/probe-session.js +50 -14
- package/lib/engine/probe.js +22 -5
- package/lib/engine/register-clock.js +41 -0
- package/lib/engine/register-gpio.js +132 -0
- package/lib/engine/register-linker.js +37 -13
- package/lib/engine/register-template.js +125 -40
- package/lib/engine/regs.js +41 -8
- package/lib/engine/rm-extract.js +144 -0
- package/lib/engine/rm-sources.js +360 -0
- package/lib/engine/rm-text.js +56 -0
- package/lib/engine/rtt.js +188 -30
- package/lib/engine/scaffold.js +185 -18
- package/lib/engine/serial.js +1692 -0
- package/lib/engine/tar.js +235 -3
- package/lib/engine/toolchain-gate.js +0 -4
- package/lib/engine/watch.js +227 -0
- package/lib/index.js +16 -2
- package/lib/skill/stm32-workflow.js +2 -2
- package/lib/tools/assets.js +39 -108
- package/lib/tools/cache.js +2 -2
- package/lib/tools/debug-session.js +2 -2
- package/lib/tools/doctor.js +61 -5
- package/lib/tools/download.js +303 -0
- package/lib/tools/firmware-install.js +31 -6
- package/lib/tools/flash.js +32 -4
- package/lib/tools/generate.js +22 -0
- package/lib/tools/ioc-inspect.js +1 -1
- package/lib/tools/ioc-plan.js +56 -2
- package/lib/tools/ioc-verify.js +237 -0
- package/lib/tools/project-create.js +41 -5
- package/lib/tools/regs.js +8 -8
- package/lib/tools/route-plan.js +1 -1
- package/lib/tools/rtt.js +157 -34
- package/lib/tools/serial.js +737 -0
- package/lib/tools/watch.js +256 -0
- package/package.json +5 -4
- package/templates/openocd/stm32c0x.cfg +83 -0
- package/templates/openocd/stm32u0x.cfg +64 -0
- package/templates/register/CMakeLists.txt +2 -2
- package/templates/register/Core/Inc/rtt.h +37 -2
- package/templates/register/Core/Src/main.c +17 -25
- package/templates/register/Core/Src/rtt.c +85 -9
- package/templates/scaffold/RTT.md +6 -2
- package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
- package/templates/scaffold/openocd.cfg +5 -3
- package/templates/scaffold/vscode/launch.json +8 -4
- package/templates/serial/bridge.ps1 +477 -0
- package/docs/development-notes.md +0 -2487
- package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
- package/docs/logic-audit.md +0 -607
package/docs/reading-guide.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# dsh-stm32 源码精读指南
|
|
2
2
|
|
|
3
3
|
> 面向:第一次读这个仓库、并且要改它的人。
|
|
4
|
-
> 规模:
|
|
4
|
+
> 规模:110 个 TypeScript 文件约 42.3k 行,外加一个手写的浏览器 bundle(client/client.js,618 行);第 1–11 章的表与行数保留 D 阶段口径,当前计数见 §13.5。**芯片事实随包内置**:`src/data/device-facts.ts` 读插件包内 `assets/device/f1/chips.json`(`DSH_STM32_ASSETS` 可覆盖;2026-11 从独立资源仓并入插件),2026-10-31 已删掉手写 chip-table.json / f1-ram.generated.ts / 手写容量档表 / 内置引脚表。
|
|
5
5
|
> 读完这份指南你应该能回答:一次工具调用从宿主进来到 openocd 退出中间经过了谁;哪几条不变量破了一定出事;要改某个功能得动哪几个文件;哪些行为有测试兜着、哪些只能上板子验。
|
|
6
6
|
>
|
|
7
7
|
> 配套文档:docs/development-notes.md(按时间记的决策与被坑记录)、docs/logic-audit.md(历史审计条目)、README.md(用户视角)。
|
|
@@ -26,9 +26,9 @@
|
|
|
26
26
|
| 层 | 目录 | 干什么 | 绝对不能干的事 |
|
|
27
27
|
| --- | --- | --- | --- |
|
|
28
28
|
| L4 装配 | src/index.ts、src/commands、src/skill | 把服务接上、把工具/命令/skill 注册进宿主 | 写业务逻辑 |
|
|
29
|
-
| L3 契约层 | src/tools(
|
|
29
|
+
| L3 契约层 | src/tools(24 个文件:25 个工具 + 1 个基础设施;一个文件可注册多个工具) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
|
|
30
30
|
| L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
|
|
31
|
-
| L1 事实表 | src/data(10 个数据模块) | 设备事实(`device-facts.ts`
|
|
31
|
+
| L1 事实表 | src/data(10 个数据模块) | 设备事实(`device-facts.ts` 读包内 `assets/device/f1/chips.json`)、由本机 CubeMX db 派生的引脚表、镜像 URL、固件族、F1 时钟树、安装指引、搜索路径、配置读写、SVD 寄存器表(`svd.ts`,来自内置 `assets/device/f1/svd/`,full 逻辑层) | 起进程、写工程文件 |
|
|
32
32
|
|
|
33
33
|
跨层的只有两样东西:**SubprocessService**(进程能力,从 ctx 一路当参数传到 engine)和 **DshContext**(宿主服务袋)。
|
|
34
34
|
|
|
@@ -44,16 +44,16 @@
|
|
|
44
44
|
```mermaid
|
|
45
45
|
flowchart TD
|
|
46
46
|
HOST["DSH 宿主 ctx<br/>tools / subprocess / jobs / webServer / commands / skills"] --> IDX["src/index.ts<br/>apply(ctx) 装配"]
|
|
47
|
-
IDX --> TOOLS["src/tools/*<br/>
|
|
47
|
+
IDX --> TOOLS["src/tools/*<br/>25 个工具"]
|
|
48
48
|
IDX --> CMDS["src/commands/register.ts<br/>7 条斜杠命令"]
|
|
49
49
|
IDX --> SKILL["src/skill/stm32-workflow.ts<br/>红线 skill"]
|
|
50
50
|
IDX --> WEB["src/engine/web-routes.ts<br/>6 条 HTTP 路由"]
|
|
51
51
|
IDX --> EVT["turn/end、session/disposed、dispose<br/>把探针还回去"]
|
|
52
|
-
TOOLS --> ENGINE["src/engine/*<br/>
|
|
52
|
+
TOOLS --> ENGINE["src/engine/*<br/>65 个纯逻辑模块"]
|
|
53
53
|
CMDS --> ENGINE
|
|
54
54
|
WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
|
|
55
55
|
API --> ENGINE
|
|
56
|
-
ENGINE --> DATA["src/data/*<br/>10
|
|
56
|
+
ENGINE --> DATA["src/data/*<br/>10 个数据模块(芯片事实读包内 assets/;SVD 在 full 层)"]
|
|
57
57
|
ENGINE --> RUN["src/engine/subprocess-runner.ts"]
|
|
58
58
|
RUN --> OS["宿主 subprocess 服务"]
|
|
59
59
|
OS --> BIN["gcc / cmake / ninja / openocd / gdb<br/>java(CubeMX) / reg.exe / pacman / objcopy"]
|
|
@@ -67,13 +67,13 @@ flowchart TD
|
|
|
67
67
|
| 目录 | 文件数 | 行数 | 说明 |
|
|
68
68
|
| --- | --- | --- | --- |
|
|
69
69
|
| src/ | 4 | 803 | index.ts 127、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
|
|
70
|
-
| src/tools/ |
|
|
71
|
-
| src/engine/ |
|
|
72
|
-
| src/data/ | 10 | 3599 | 10 个 .ts 数据模块(device-facts.ts
|
|
70
|
+
| src/tools/ | 24 | 7583 | 25 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 serial.ts 829 行,其次是 regs.ts 735 行、route-plan.ts 576 行、rtt.ts 408 行 |
|
|
71
|
+
| src/engine/ | 51 | 21712 | 见第 5 章(第 5 章表格化了 45 个模块,另有 assets.ts 1162 行没单列);最大的是 msys2-install.ts 2313 行,其次是 assets.ts 1162 行、clock-plan.ts 801 行 |
|
|
72
|
+
| src/data/ | 10 | 3599 | 10 个 .ts 数据模块(device-facts.ts 读包内 assets/、svd.ts 读 full 层的寄存器表),见第 6 章 |
|
|
73
73
|
| templates/ | 20 | — | 工程脚手架与寄存器版模板(CMake、链接脚本、launch/settings、openocd.cfg、demo.ioc;C 阶段加了寄存器版的 `Core/Src/rtt.c` + `Core/Inc/rtt.h` 与 HAL 脚手架 `scaffold/RTT.md`) |
|
|
74
74
|
| client/ | 1 | 682 | 设置面板的前端 bundle(手写 JS,不经打包器) |
|
|
75
|
-
| test/ |
|
|
76
|
-
| scripts/ |
|
|
75
|
+
| test/ | 41 套件(run-units 登记)+ 15 个 e2e 脚本 + 4 个辅助脚本 | — | 见第 9 章 |
|
|
76
|
+
| scripts/ | 8 | 2115 | copy-client.mjs(24)、copy-data.mjs(20)、gen-xcube-catalog.mjs(151)、pack-size.mjs(105)、pack-smoke.mjs(157)、assets/build-assets.mjs(1042)、assets/family-assets.mjs(238)、assets/svd-f1.mjs(378)。芯片表与 SVD 的生成脚本 2026-11 起随插件放在 `scripts/assets/` |
|
|
77
77
|
|
|
78
78
|
> 全书行数统一口径:按文件里的换行符数(`content.split("\n").length`,等价于编辑器的「块末行号」),2026-10-31(D 阶段末)重数过一遍——第 1、4.1、4.2、5、6 章都按这个口径,和本指南更早版本的数字会有几行到几十行的差异。
|
|
79
79
|
|
|
@@ -100,7 +100,7 @@ flowchart TD
|
|
|
100
100
|
三件事,只有三件:
|
|
101
101
|
|
|
102
102
|
1. **声明身份与依赖**:`export const name = "dsh-stm32"`、`export const inject = ["tools", "subprocess", "jobs"]`。这三个是硬依赖,缺了插件不加载。
|
|
103
|
-
2. **apply(ctx) 里按「先探测、再操作」的顺序注册
|
|
103
|
+
2. **apply(ctx) 里按「先探测、再操作」的顺序注册 25 个工具**:env_install → download → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → ioc_verify → build → flash → debug_run → debug_session → regs_read → route_plan → rtt → watch → assets → cache → doctor → serial → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
|
|
104
104
|
3. **注册可选层并挂三个事件**:commands / skills 走 `ctx.inject([...], scope => ...)`,宿主没组合这些服务时静默跳过,工具照常工作;webServer 路由在`registerWebRoutes` 里自己判断。
|
|
105
105
|
|
|
106
106
|
三个事件是本插件唯一的「状态清理入口」,也是很容易读漏的地方:
|
|
@@ -154,7 +154,7 @@ ctx.on("dispose", () => { void debugSessions.stop("插件卸载"); });
|
|
|
154
154
|
|
|
155
155
|
7 条命令里有 6 条最终调用 engine 的同一个函数(build → runBuild,flash → runFlash …),所以它们和工具的唯一差别是:输入来自文本而不是 JSON、输出是一段中文。
|
|
156
156
|
|
|
157
|
-
## 4. tools 层:
|
|
157
|
+
## 4. tools 层:25 个工具 + 1 个基础设施
|
|
158
158
|
|
|
159
159
|
### 4.1 一个工具文件的固定骨架
|
|
160
160
|
|
|
@@ -190,12 +190,12 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
|
|
|
190
190
|
2. **门禁在工具层,不在 engine。** engine 假设工具链就位;`blockedReport` / `emptyReport` 是门禁拦截与早退时造「同形报告」的工厂,保证失败也是合法输出。
|
|
191
191
|
3. **`resolveProjectDir` + `validateToolArgs`(tools/project-dir.ts,120 行)是所有工具的共同入口**:前者把 `projectDir` 参数 / 会话工作目录落成绝对路径,后者按 `RequiredArgSpec` 校验必填参数类型,报错文案统一。
|
|
192
192
|
|
|
193
|
-
### 4.2
|
|
193
|
+
### 4.2 25 个工具一览
|
|
194
194
|
|
|
195
195
|
| 工具 | 文件(行) | engine 入口 | 门禁能力 |
|
|
196
196
|
| --- | --- | --- | --- |
|
|
197
|
-
| `stm32_env_probe` | env-probe.ts(284) | probe.buildTargets / probeAll + search-roots.resolveSearchConfig | 无 |
|
|
198
197
|
| `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
|
|
198
|
+
| `stm32_download` | download.ts(300) | download.planDownload / downloadUrlToFile / sha256File / inspectInstallerFile | 无(只下载与校验,绝不执行安装器) |
|
|
199
199
|
| `stm32_firmware_install` | firmware-install.ts(288) | firmware-install.planOrInstallFirmware | 无 |
|
|
200
200
|
| `stm32_project_create` | project-create.ts(387) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
|
|
201
201
|
| `stm32_project_export` | project-export.ts(122) | project-export.runExport | 无 |
|
|
@@ -204,22 +204,26 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
|
|
|
204
204
|
| `stm32_ioc_inspect` | ioc-inspect.ts(243) | ioc.summarizeIoc | 无 |
|
|
205
205
|
| `stm32_ioc_plan` | ioc-plan.ts(398) | ioc-plan.planIocChanges + clock-plan.planClockChanges(引脚 / 键 / 时钟进同一个 candidate) | 无 |
|
|
206
206
|
| `stm32_ioc_apply` | ioc-apply.ts(137) | ioc-plan.applyIocPlan / rollbackIoc | 无 |
|
|
207
|
+
| `stm32_ioc_verify` | ioc-verify.ts(246) | ioc-verify.runIocVerify(CubeMX 无头 load→save 回读对比) | generate(CubeMX + JRE) |
|
|
207
208
|
| `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
|
|
208
209
|
| `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
|
|
209
210
|
| `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
|
|
210
211
|
| `stm32_debug_session` / `_eval` / `_stop` | debug-session.ts(305,三工具同文件) | debug-session.DebugSessionManager(单例 debugSessions)+ releaseProbeFor | debug(仅 session 启动时) |
|
|
212
|
+
| `stm32_watch` | watch.ts(305) | engine/watch 的登记表(纯函数)+ debug-session.sampleWatches / addWatchpoints / removeWatchpoints(复用常驻 MI) | debug(add kind=write/read/access 与 sample 需要会话) |
|
|
211
213
|
| `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
|
|
212
214
|
| `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
|
|
213
215
|
| `stm32_route_plan` | route-plan.ts(576) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
|
|
216
|
+
| `stm32_assets` | assets.ts(314) | engine/assets 全套(内置资源定位、manifest 校验、ensureAssets) | 无 |
|
|
214
217
|
| `stm32_cache` | cache.ts(306) | engine/cache 全套 | 无 |
|
|
215
218
|
| `stm32_doctor` | doctor.ts(202) | doctor.runDoctor + collectChipConsistency(型号/启动文件/设备宏/.ld/Flash 五项一致性) | 无(它自己就是体检) |
|
|
219
|
+
| `stm32_serial` | serial.ts(829,0.1.5 新增) | 无独立 engine 入口:engine/serial.ts 直接管 PowerShell 桥(文件 IPC:cmd/ done/ rx.ndjson tx.ndjson status.json)与端口记忆(`~/.dsh-stm32/serial.json`) | 无(P1 仅 Windows;非 Windows / 缺 PowerShell 在工具层返回 `unsupported-platform`,不起桥) |
|
|
216
220
|
| —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
|
|
217
221
|
|
|
218
|
-
两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**
|
|
222
|
+
两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**serial.ts 829 行**现在是 tools 层最大的,**regs.ts 735 行**次之(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**第三——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
|
|
219
223
|
|
|
220
|
-
## 5. engine 层:45
|
|
224
|
+
## 5. engine 层:D 阶段的 45 个模块,十个域(现 65 个 .ts)
|
|
221
225
|
|
|
222
|
-
|
|
226
|
+
下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。这里保留 D 阶段的 45 个模块表;`src/engine/` 现在有 65 个 `.ts`,0.1.5 的 `serial.ts`、`download.ts` 与 `assets.ts`(内置资源装配与完整性校验,flat 布局)等后续模块见 §12、§13 与目录本身;读内置资源链路时从 §5.7 与 `src/data/device-facts.ts` 一起看。
|
|
223
227
|
|
|
224
228
|
### 5.1 进程与路径(3 个,413 行)
|
|
225
229
|
|
|
@@ -251,7 +255,8 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
|
|
|
251
255
|
| --- | --- |
|
|
252
256
|
| flash.ts(388) | `runFlash`:SWD 守卫(`checkNoDebugGuard`:唯一 .ioc 看 PA13/PA14,没有 .ioc 就看 openocd.cfg 的 transport,找不到依据时给 notes 而不是静默放行)→ `resolveElf` → 找 openocd 配置(`findProjectConfig` 认 openocd.cfg/openocd/…;否则 `defaultConfigs` 用 interface/cmsis-dap.cfg + target/stm32f1x.cfg)→ 拼 `program <elf> verify reset exit`(`buildProgramCommand`)→ 解析日志(`parseFlashLog` 只回答 programmed / verified / errors / noise,**不再归类**)→ 失败时只调一次 `classifyProbeFailure`(stage "flash"),产物是 `probeError: ProbeError | null`(成功路径保持 null,由工具层摘掉)→ USB 形态提示(`usbNoteFor` / `probeMissingLines`)。`toOpenOcdPath` 只把反斜杠换成正斜杠。B2 之后分类规则与 hint 常量只在 probe-error.ts 一份,flash 与 debug 不会再各写一套漂移。 |
|
|
253
257
|
| debug.ts(435) | 一次性调试快照 `runDebugRun`:挑端口(`pickPort`,默认 3333,占用则顺延)→ 起 openocd(`waitForListening` 等 "Listening on port")→ 起 gdb 跑一串 -ex(file / break / info registers / bt / info locals / monitor reset run / detach)→ `parseGdbOutput` 提取断点命中、寄存器、调用栈、locals → ok 判据看 exitCode + probe.errors + hitBreakpoint(审计 A26)。失败时:`classifyProbeFailure` 归类(与 flash 同一个函数、同一组 kind,stage "debug")→ `probeMissingLines` 命中就跑 `usbDiagnosis`、日志用 `keyLogTail(lines, 40)`(优先留 adapter/Error 行,而不是「最后 15 行」)、`firstProblemLine` 把首条根因塞进 errors、kind 不是 unknown 时把 hint 写进 notes。B4 的断点预算(`resolveBreakpointBudget` / `collectBreakpointRequests` / `planBreakpoints`)也在同一条 execute 里先算完,报告带 `breakpoints` / `watchpoints` 两个 used/limit/remaining 三元组。 |
|
|
254
|
-
| debug-session.ts(
|
|
258
|
+
| debug-session.ts(1101) | 长会话租约。`DebugSessionManager` 管「一个常驻 openocd + 多次短命 gdb -batch eval」,空闲 90 s、总时长 10 min、turn/end 立刻释放;`releaseProbeFor(reason)` 是别的工具(flash/regs/debug_run)动探针前必须调的一步(审计 B16:先释放再门禁)。三个纯函数是好单测点:`normalizeHexAddress`、`parseGdbPrintedHex`、`parseMarkedWords`(按 `echo ===DSH:<tag>===` 分段对齐,修「中间某个地址读失败导致后面值整体前移」)。 |
|
|
259
|
+
| watch.ts(266) | 变量监视与硬件观察点(P3 续)。**纯状态层,不碰进程**:`WatchKind`(value/write/read/access)、`watchState` 单例(`entries` + `nextId`)、`registerWatch` / `removeWatchByIds` / `removeAllWatches` / `resetWatchState` / `sampledWatches` / `hardwareWatchpoints` / `markWatchpointsStale`、`recordWatchSample` + `formatWatchDelta`;纯函数还有 `normalizeWatchExpression`(拒空/超 200 字符/含换行或 NUL)、`numericWatchValue`、`formatWatchEntry` / `formatWatchLines`、`parseWatchMarkers`(旧 gdb 兜底路径按 `===DSH:W<id>===` 分段)、`parseWatchpointNumber`、`isHardwareWatchpoint`。真正下达 gdb 的三个动作在 debug-session.ts(`sampleWatches` / `addWatchpoints` / `removeWatchpoints`):值监视要「在跑就先 `-exec-interrupt` → 逐项 `evaluate` → 原本在跑就 `monitor resume`」;观察点要过 `resolveBreakpointBudget` 的 data 预算(F1 只有 4 个)并识别「装成了软件观察点」并告警。生命周期:`stop()` 里 `resetWatchState()`(观察点住在 gdb 进程里,会话一关全没了);`ensureMi` 重建 MI 时 `markWatchpointsStale(...)`。 |
|
|
255
260
|
| regs.ts(250) | 读内存映射寄存器。`normalizeAddress`(0x 可省)、`buildRegsScript`(生成 openocd 脚本:init → halt → mdw)、`parseRegsLog` → `runRegsRead`。本身只负责脚本生成与日志解析(`buildRegsScript` / `parseRegsLog`,不复位芯片);B3 起工具层换成「复用常驻会话 + Tcl RPC 直读」(`ensureSession` + `readWordsViaSession`,RPC 失败回退到会话里的 gdb),没有会话时才起一个并保留 90 s。D 阶段的符号名解析、位域解释与外设 dump 全在工具层(`src/tools/regs.ts`,735 行)与 data 层(`src/data/svd.ts`):本模块仍然只认地址,不知道 `GPIOC.ODR` 是什么。 |
|
|
256
261
|
| probe-error.ts(280) | 探针故障的**唯一分类入口**(B2)。`ProbeErrorKind` 8 类(no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / timeout / unknown)、运行期枚举 `PROBE_ERROR_KINDS`、`ProbeError{kind,cause,hint,evidence,retryable}`;`classifyProbeFailure({lines,exitCode,stage,timedOut,spawnError})` 的判定顺序是 **MATCHERS 首个命中 → timedOut(timeout) → spawnError → unknown**,所以 MATCHERS 的顺序是敏感的。hint 常量(`HINT_PROBE` / `HINT_BUSY` / `HINT_DP` / `HINT_FLASH_PROTECTED` / `HINT_NO_POWER` / `HINT_TARGET_MISMATCH` / `HINT_TIMEOUT` / `HINT_UNKNOWN`)只此一份;`firstProblemLine` / `probeMissingLines` / `usbNoteFor` 从 flash.ts 迁过来;`formatProbeError` 出「错误:<kind> — <cause>;建议:<hint>」;`PROBE_ERROR_SCHEMA`(additionalProperties:false,五个字段全 required)。不做兼容别名:`errorCode` 字段已删除,flash / debug / session 三条路径共用同一份规则。 |
|
|
257
262
|
| probe-session.ts(395) | 会话复用的快路径(B3)。`sessionInfo` / `touch` / `release(reason)` / `ensureSession(projectDir, opts)` / `withSession` / `readWordsViaSession({addresses})`,以及纯函数 `normalizeWordAddress` / `parseMdwReply` / `parsePcReply` / `tclRoundTrip`。会话的唯一真相仍是 debug-session.ts 的 `debugSessions` 单例——这里不自己存句柄、也不自己算租约;并发靠模块级 starting Promise 去重(同时两次调用只起一个进程);端口被占直接报 `probe-busy`,不让 openocd 顺延端口去抢探针。读值走 openocd 的 Tcl RPC、一条 TCP 连接(halt → `reg pc` → `mdw`×N → resume,用 0x1a 分帧),tcl 端口没拿到或 RPC 失败就回退到会话里的 gdb 并写 notes。 |
|
|
@@ -303,7 +308,7 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
|
|
|
303
308
|
|
|
304
309
|
| 模块 | 职责与关键导出 |
|
|
305
310
|
| --- | --- |
|
|
306
|
-
| msys2-install.ts(2313) | 最大也最脏的一块:下载 MSYS2 安装包 → 静默安装 → pacman 装 5 个组件 → 写用户级 PATH → 写配置 → 自检。关键导出:`MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_BYTES`、`DEFAULT_MSYS2_PACKAGES`、`MSYS2_SUGGESTED_ROOT`、`planOrInstallMsys2(subprocess, request)`(plan / install 两条路)、`msys2StepSkeleton`、`parsePacmanQuery`、`resolveInstallerUrls(env)`(**
|
|
311
|
+
| msys2-install.ts(2313) | 最大也最脏的一块:下载 MSYS2 安装包 → 静默安装 → pacman 装 5 个组件 → 写用户级 PATH → 写配置 → 自检。关键导出:`MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_BYTES`、`DEFAULT_MSYS2_PACKAGES`、`MSYS2_SUGGESTED_ROOT`、`planOrInstallMsys2(subprocess, request)`(plan / install 两条路)、`msys2StepSkeleton`、`parsePacmanQuery`、`resolveInstallerUrls(env)`(**P0-1 固定版本**:稳定 release `2026-09-27` 的官方 exe 单源;`MSYS2_INSTALLER_URL` 或 `MSYS2_MIRROR` 可覆盖,但必须同时给 `MSYS2_INSTALLER_SHA256`,否则直接拒绝、不退回官方源;`installerSourceLabel` 只认官方 release 与自定义源)、`installerSourceLabel`、`preferMirrorServers(text, servers)` / `preferChinaMirrors(msys64)`(**F3b**:只把国内镜像插到 `etc/pacman.d/mirrorlist.msys` 与 `mirrorlist.mingw` 最前,官方条目不删,幂等,已有 MSYS2 一个字都不改)、`resolveTargetDir` / `viaLabel`、`formatBytes`、`isDriveRoot` / `ensureParentDir`(盘根不能 mkdir,审计 ③)、`usageNote` / `planMessage`(**计划模式只报缺件**:已装齐时 steps 为空、download.bytes 0、一句话收尾)。**P0-1 四道闸**:`checkInstallerFile` 统一查体量 ≥40 MB、MZ 头、sha256(错误带期望/实际值);缓存复用、下载完成、**解压执行前**各校验一次,哈希不符的下载删 `.part`、哈希不符的缓存保留原文件但重下;缓存名带版本 `msys2-2026-09-27.sfx.exe`。解压后再查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删)。**F3c**:`curl -C -` 同源续传、`--speed-limit 1024 --speed-time 10` 低速自退(退出码 28 单独说明),退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次,换源前删 `.part`。 |
|
|
307
312
|
|
|
308
313
|
### 5.9 设置面板的宿主侧(2 个,577 行)
|
|
309
314
|
|
|
@@ -318,20 +323,20 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
|
|
|
318
323
|
| --- | --- |
|
|
319
324
|
| route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
|
|
320
325
|
|
|
321
|
-
## 6. data 层:10 个数据模块(3599
|
|
326
|
+
## 6. data 层:10 个数据模块(3599 行;芯片事实来自包内 assets/)
|
|
322
327
|
|
|
323
328
|
| 模块 | 行数 | 内容 |
|
|
324
329
|
| --- | --- | --- |
|
|
325
330
|
| chips.ts | 177 | **不再有内置引脚表**(`CHIPS` / `KNOWN_CHIPS` / `findChip` 2026-10-31 删除)。`isKnownPin(pin)` 只查**引脚名是否合法**(`PA0..PG15`、`VP_*` 虚拟脚放行;顺序不影响——`PA0-WKUP` / `PC13-TAMPER-RTC` 先归一化);这不是「这个封装有没有这根脚」,那条事实只能来自本机 CubeMX db:`parseMcuDbXmlPins`(`<Pin Name= Position=>`,`Position<=0` 的虚拟脚丢弃,电源脚不算)、`findMcuDbDir`(`<CubeMX>/db/mcu`)、`readMcuDbPins`、`deriveChipPinTable({cpn, mcuName, dbMcuDir})` → `kind: db / unknown`(db 命中注明来源 XML 与引脚数;没有 db 就明说「引脚存在性不校验」,绝不拿内置表冒充)。 |
|
|
326
331
|
| cmsis-sources.ts | 416 | 寄存器路线的下载源与型号映射:四个镜像(jsdelivr fastly/cdn、raw.githubusercontent、ghproxy)、`CMSIS_FAMILIES`、`startupChoiceFor(mcu)`(委托 resolveF1Chip,兼容 `F1:B` / `F1:8` / `F103:xb` / `STM32F103C8T6` 四种写法;只给容量字母的老写法现在从设备事实里挑一颗同档芯片当代表,优先 F103——原来的「字母 → 档位」常量表已删,没缓存就返回 null 让上层提示 refresh)、`cmsisTemplatePlan(choice)`(10 个文件的目标路径)、四个 sha256 表(DEVICE_HEADER / SYSTEM_C / **STARTUP 14 条** / CORE_HEADER)、缓存条目 id 与解析(`chipOf`、`cmsisGroupKey`、`cmsisEntryId` → `cmsis:F1:103xb`、`chipEntryId`、`parseCmsisEntryRef`、`cmsisEntryAliases`)。**改这里等于改「离线可复现」的边界**:F1 的 14 个容量档 sha256 全部是 2026-10-30 真实下载实测的。 |
|
|
327
|
-
| stm32f1.ts | 171 | 两条路线共用的**型号解析器**,本身不再存任何事实:`resolveF1Chip(input)` 先做格式/封装/温度档校验,再查 `device-facts.ts`(完整型号按 CPN 精确匹配、无温度后缀按前缀归一化、`F103:xb` 按 line+档取代表芯片),返回 `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`(签名与结构 0.2 不变);`f1GroupsFor(code)` 从事实聚合该 line 的容量档。错误分四类且都带「先跑 `stm32_assets
|
|
332
|
+
| stm32f1.ts | 171 | 两条路线共用的**型号解析器**,本身不再存任何事实:`resolveF1Chip(input)` 先做格式/封装/温度档校验,再查 `device-facts.ts`(完整型号按 CPN 精确匹配、无温度后缀按前缀归一化、`F103:xb` 按 line+档取代表芯片),返回 `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`(签名与结构 0.2 不变);`f1GroupsFor(code)` 从事实聚合该 line 的容量档。错误分四类且都带「先跑 `stm32_assets verify`」提示:内置资源缺失 / 型号不在内置资源 / line 不存在 / 该 line 没有这一容量档。 |
|
|
328
333
|
| clock-f1.ts | 215 | F1 时钟树的事实表:PLL 源(HSE 8 MHz / HSI÷2 4 MHz / HSI 8 MHz,后者 `selectable=false`)、倍频 ×2..×16、上限(SYSCLK 72 / APB1 36 / APB2 72 / ADC 14 / USB 48 且必须 PLLCLK=72÷1.5)、APB1/APB2/ADC 分频表、14 条外设→总线、UART 波特率档、20 个 RCC IPParameters 名单。 |
|
|
329
|
-
| firmware-packages.ts | 463 | 固件包事实表:`FIRMWARE_FAMILIES
|
|
334
|
+
| firmware-packages.ts | 463 | 固件包事实表:`FIRMWARE_FAMILIES`(17 族:F1/F2/F3/F7/G0/L1/L4/U0/C0/H5/U5/WBA/L5/WB/WL/H7/U3)、`firmwareFamilyOf`、`firmwareVersionTags`、`packageXmlText`、`firmwarePlanFor`、`verifyFirmwarePackage`、`DSH_FIRMWARE_DIR_NAME = "dsh-firmware"`、`dshFirmwareDir`、`firmwareNeedFromIoc`(从 .ioc 的包名推族与版本)、`looksLikeFirmwarePackage`、`locateFirmwarePackage(root, packageName, extraDirs)` → `FirmwareLocation`(source:repository / dsh-firmware / cache / custom)、`firmwareSourceLabel`、`FirmwareExtraDir`。 |
|
|
330
335
|
| install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
|
|
331
336
|
| search-roots.ts | 421 | 见 5.2。 |
|
|
332
337
|
| toolchain-config.ts | 370 | 见 5.2。 |
|
|
333
|
-
| device-facts.ts | 278 |
|
|
334
|
-
| svd.ts | 837 | SVD 寄存器表(新增,D
|
|
338
|
+
| device-facts.ts | 278 | 设备事实读取层(新增):从插件包内 `assets/device/f1/chips.json` 读(`lib/engine/assets.js` 从包根解析;`DSH_STM32_ASSETS` 可换根目录,外部旧版本仍兼容),按 path+size+mtime 缓存一次。`loadDeviceFacts(env?)` → `{ok,path,version,chips,byCpn,byLineGroup,lines,groupsByLine,error}`、`findChipFact(cpn,env?)`(缺失返回 null)、`requireChipFact(cpn,env?)`(抛 `DeviceFactError`,`code: facts-missing / chip-unknown`)、`deviceFactsSource(env?)`(缓存路径或 `"none"`)。**不抛异常、不退回内置表**:找不到内置文件就把「安装不完整:stm32_assets verify 定位,重装插件」原样交给上层。 |
|
|
339
|
+
| svd.ts | 837 | SVD 寄存器表(新增,D 阶段):读插件包内 `assets/device/f1/svd/<line>.json`(`profile=full`)。常量 `SVD_REL_DIR`、`SVD_KNOWN_LINES`(100/101/102/103/105/107)、`SVD_FULL_PROFILE_HINT`(一句能照做的「SVD 只在 profile=full:重装插件」提示)。`loadSvd`(返回 `{device,failure}`,不抛)/ `loadSvdForLine` / `requireSvd` / `svdLineForChip(cpn, env)`(走 device-facts 的 line)、`resolveRegisterRef(ref, line, env)`(`GPIOC.ODR` / `GPIOC->ODR` / `0x4001100C` 三种写法等价,返回 base+offset 之后的地址、size、fields)、`describeAddress`(地址 → 寄存器 + 寄存器内偏移,`exact:false` 表示落在寄存器中间)、`decodeRegisterValue`(置位字段 / 清位 / 未覆盖位)、`formatDecodedFields` / `formatAddress` / `formatOffset`;出错抛 `SvdError`(9 类 code)。兼容「包内 flat `assets/`」与旧的外部 `<root>/<version>/` 两种布局,缓存键 path+size+mtimeMs,`svdCacheStats` / `resetSvdCache` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
|
|
335
340
|
|
|
336
341
|
## 7. 关键流程
|
|
337
342
|
|
|
@@ -467,7 +472,7 @@ stateDiagram-v2
|
|
|
467
472
|
空闲 --> 启动中: stm32_debug_session(start)
|
|
468
473
|
启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
|
|
469
474
|
启动中 --> 空闲: 端口占用 / 探针失败、带 probeError(kind / cause / hint)
|
|
470
|
-
活跃 --> 活跃: stm32_debug_eval
|
|
475
|
+
活跃 --> 活跃: stm32_debug_eval、优先常驻 MI(连不上才每次新起 gdb -batch:连上 → halt → 命令 → resume → detach)
|
|
471
476
|
活跃 --> 空闲: stm32_debug_stop
|
|
472
477
|
活跃 --> 空闲: 空闲 90 s
|
|
473
478
|
活跃 --> 空闲: 总时长 10 min
|
|
@@ -684,15 +689,15 @@ flowchart LR
|
|
|
684
689
|
|
|
685
690
|
| 层 | 位置 | 说明 |
|
|
686
691
|
| --- | --- | --- |
|
|
687
|
-
| 单元/契约 | test/*.test.mjs + test/schema-guard.mjs |
|
|
692
|
+
| 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 41 个套件 654 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
|
|
688
693
|
| e2e 脚本 | test/e2e-*.mjs(15 个) | 开发期手动跑的端到端(真 CubeMX / 真 openocd / 真工具链),不进 npm test |
|
|
689
|
-
| 发布形态 | scripts/pack-smoke.mjs(npm run test:pack)+ scripts/pack-size.mjs(npm run test:size) | npm pack → 解包 → 断言 16 个必须文件 → 用解包出来的 lib 真建一个寄存器工程;pack-size 再守包体(tarball ≤1.2 MB、templates/** ≤
|
|
694
|
+
| 发布形态 | scripts/pack-smoke.mjs(npm run test:pack)+ scripts/pack-size.mjs(npm run test:size) | npm pack → 解包 → 断言 16 个必须文件 → 用解包出来的 lib 真建一个寄存器工程;pack-size 再守包体(tarball ≤1.2 MB、templates/** 里的运行时资产 ≤40 KB 且单文件 ≤24 KB、包内禁二进制、必需文件齐全)。CI 上两连跑 |
|
|
690
695
|
|
|
691
|
-
### 9.2
|
|
696
|
+
### 9.2 41 个套件一览(test/run-units.mjs 的 suites 数组顺序)
|
|
692
697
|
|
|
693
|
-
build-units、cache-units、cache-gc-units、assets-units、probe-error-units(23 例)、probe-session-units(16 例)、breakpoints-units(17 例)、stm32f1-units、hal-route-units、clock-units、doctor-chip-units、cmake-sources-units、commands-units、doctor-regs-units、engine-units、export-units、firmware-units、flash-units、generate-cache-units、ioc-plan-units、install-units、ioc-units、route-plan-units、scaffold-patch-units、search-roots-units、session-units、text-encoding-units、thirdparty-units、tool-contract-units、toolchain-units、vscode-units、web-api-units、xcube-units、rtt-units、svd-units(39 例)、schema-guard。
|
|
698
|
+
build-units、cache-units、cache-gc-units、assets-units、probe-error-units(23 例)、probe-session-units(16 例)、breakpoints-units(17 例)、stm32f1-units、hal-route-units、clock-units、doctor-chip-units、cmake-sources-units、commands-units、doctor-regs-units、engine-units、export-units、firmware-units、flash-units、generate-cache-units、ioc-plan-units、install-units、ioc-units、route-plan-units、scaffold-patch-units、search-roots-units、session-units、text-encoding-units、thirdparty-units、tool-contract-units、toolchain-units、vscode-units、watch-units(16 例)、web-api-units、xcube-units、rtt-units、svd-units(39 例)、schema-guard。
|
|
694
699
|
|
|
695
|
-
开发机上
|
|
700
|
+
开发机上 654 例全跑(`node test/run-units.mjs` → TOTAL pass=654 fail=0,41 个套件);CI 上仍是 **2 skipped**(两条用例依赖本机路径,本轮没在 CI 上重跑)。D 阶段加了 `svd-units`(39 例:26 例符号解析与位域解码 + 13 例工具层端到端,含假 subprocess 与假 Tcl 服务端),工具数不变(仍 21),改的是 `stm32_regs_read` 的 `addresses` 语义与报告字段。B 阶段一次加了三个套件:`probe-error-units`(23 例,8 类 kind 与判定顺序)、`probe-session-units`(16 例,会话复用与 Tcl 分帧)、`breakpoints-units`(17 例,6/4 预算与超限文案)。C 阶段(RTT)加了 `rtt-units`(26 例:20 例帧 / 命令编码 + 6 条模板静态断言),工具数同时从 20 增至 21、engine 模块从 44 增至 45。
|
|
696
701
|
|
|
697
702
|
约定:
|
|
698
703
|
- 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
|
|
@@ -721,29 +726,29 @@ const fake = {
|
|
|
721
726
|
| --- | --- | --- |
|
|
722
727
|
| 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
|
|
723
728
|
| 改报告字段 | src/tools/<x>.ts 的 reportSchema + 渲染 | schema-guard 必须有对应断言 |
|
|
724
|
-
| 加芯片族(F4/G0…) | src/data/cmsis-sources.ts(启动文件与宏)、firmware-packages.ts(FIRMWARE_FAMILIES 的仓库名要 curl 核实)、data/chips.ts(引脚存在性交给 deriveChipPinTable 从本机 db
|
|
725
|
-
| 加芯片型号(同族容量档) |
|
|
729
|
+
| 加芯片族(F4/G0…) | src/data/cmsis-sources.ts(启动文件与宏)、firmware-packages.ts(FIRMWARE_FAMILIES 的仓库名要 curl 核实)、data/chips.ts(引脚存在性交给 deriveChipPinTable 从本机 db 派生)、设备事实(包内 assets/device/<族>/chips.json,由 scripts/assets/build-assets.mjs 生成)、再补一份 clock-f1 那样的时钟上限表(否则寄存器版只能不出 clock_init) | 仓库名不能猜;sha256 逐文件实测并把来源 URL 记进表里(F1 的 14 条就是这么来的) |
|
|
730
|
+
| 加芯片型号(同族容量档) | **插件内置 `assets/device/f1/chips.json`**(`node scripts/assets/build-assets.mjs` 从本机 CubeMX `db/mcu` 展开 CPN 并逐字段对账,manifest 里会列 skipped)→ 插件的 src/data/device-facts.ts 自动读到;再对照 src/engine/hal-chip.ts(渲染启动文件/宏/.ld/.ioc)→ register-template.ts / register-linker.ts / register-clock.ts | 改完随插件发版;若用 `DSH_STM32_ASSETS` 指到外部旧版,以外部为准。三条路都要试:HAL 建工程、寄存器建工程、doctor 一致性 |
|
|
726
731
|
| 改时钟树 | src/data/clock-f1.ts(PLL 源/分频/外设→总线)→ src/engine/clock-plan.ts(枚举/就近/diff)→ src/tools/ioc-plan.ts(参数与渲染)→ src/engine/register-clock.ts(寄存器版) | clock-units 14 例兜「60→64」「超限一个键都不写」;派生键必须全量重算 |
|
|
727
|
-
| 更新设备事实(芯片表) |
|
|
732
|
+
| 更新设备事实(芯片表) | **插件内置资源** `node scripts/assets/build-assets.mjs` 重跑 → device/f1/chips.json + manifest.json 一起更新(chipdb 与 memory.json 2026-10-31 已删:前者与 CubeMX 的 db/mcu 重复,后者字段全由 chips.json 派生);随插件发版一起分发 | 生成物不要手改;插件已经不再内置芯片表(`scripts/gen-chip-table.mjs` 与 chip-table.json 2026-10-31 删除),缺文件时工具会明说重装插件。测试夹具在 `test/fixtures/assets/`,与内置资源同构 |
|
|
728
733
|
| 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
|
|
729
734
|
| 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
|
|
730
735
|
| 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
|
|
731
736
|
| 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
|
|
732
737
|
| 加 / 改探针错误分类 | engine/probe-error.ts 的 `classifyProbeFailure` 与 `PROBE_ERROR_KINDS`(MATCHERS 顺序敏感;flash / debug / session 三条路径共用同一份) | 三处同改:probe-error 的 MATCHERS 与 hint、tools 层的 `PROBE_ERROR_SCHEMA` 声明、test/probe-error-units 与 schema-guard |
|
|
733
738
|
| 改 cmake 源清单的认法(设备宏、startup、HAL 模块) | engine/cmake-sources.ts 的 `collectCmakeSources` / `halModulesInUse` | 注释掉的 `#define` 与 `#include` 不能算启用;内容没变必须零写入(cmake-sources-units 15 例兜这两条) |
|
|
734
|
-
| 改 RTT 帧格式(头长、级别含义、长度字段) | engine/rtt.ts 的 `RTT_FRAME_HEADER_BYTES` / `RTT_MIN_FRAME_BYTES` / `parseRttFrames` + templates/register/Core/Src/rtt.c 的 `RTT_FRAME_OVERHEAD` / `RTT_FRAME_MIN_BYTES` / `rtt_ring_write` | 两侧常量必须一致(rtt-units 有一条反算断言),还要同步 templates/scaffold/RTT.md 与两份 README 的三行示例;改帧头等于改 ABI
|
|
739
|
+
| 改 RTT 帧格式(头长、级别含义、长度字段) | engine/rtt.ts 的 `RTT_FRAME_HEADER_BYTES` / `RTT_MIN_FRAME_BYTES` / `parseRttFrames` + templates/register/Core/Src/rtt.c 的 `RTT_FRAME_OVERHEAD` / `RTT_FRAME_MIN_BYTES` / `rtt_ring_write` | 两侧常量必须一致(rtt-units 有一条反算断言),还要同步 templates/scaffold/RTT.md 与两份 README 的三行示例;改帧头等于改 ABI,老固件会被判成帧失步;dump 侧另有 `resyncRttFrames` 负责把环缓冲首字节/中段对齐到帧边界,并按「时间戳+级别+文本」去重(严格解析器不动,见 development-notes §39、§40) |
|
|
735
740
|
| 改寄存器写法的解析或位域解释 | `src/data/svd.ts`(符号解析 / 反向查 / 解码)+ `src/tools/regs.ts`(五种写法、去重、dump、渲染、建议文案) | `svd-units` 39 例兜着;夹具在 `test/fixtures/svd/`(flat / versioned / badline 三种布局);改渲染要同步两份 README 与 development-notes §31 |
|
|
736
|
-
| 更新 SVD 事实表(新 line / 新资源版本) |
|
|
741
|
+
| 更新 SVD 事实表(新 line / 新资源版本) | 插件仓内 `node scripts/assets/build-assets.mjs --svd` 重新从 cmsis-svd-data 生成 `assets/device/f1/svd/<line>.json`(`files[].profile` 标 full,并带 ST EULA 来源)→ 再跑 `node scripts/assets/build-assets.mjs` 重写 manifest → `stm32_assets verify` 校验完整性 | SVD 严格解析:外设/寄存器/字段有一条不合法就整份拒绝;缓存键是 path+size+mtimeMs,升级后自动失效 |
|
|
737
742
|
| 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
|
|
738
743
|
|
|
739
744
|
## 11. 已知的坑与未做的事
|
|
740
745
|
|
|
741
|
-
1.
|
|
746
|
+
1. **`FIRMWARE_FAMILIES` 目前收 17 族**(F1/F2/F3/F7/G0/L1/L4/U0/C0/H5/U5/WBA/L5/WB/WL/H7/U3):新增族要接入必须先核实真实仓库名(stm32g4xx-hal-driver 之类),不能照 F1 改字母。
|
|
742
747
|
2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
|
|
743
748
|
3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
|
|
744
749
|
4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
|
|
745
|
-
5. **P2(多芯片 + HAL
|
|
746
|
-
6. **docs/diagrams/** 那两张 HTML 图有 2 MB 原始 / 891 KB gz,已经不进 npm 包**(package.json 的 files 从 docs 收窄成 docs/*.md)。这事现在由 `scripts/pack-size.mjs`(npm run test:size)守着:tarball ≤1.2 MB、templates/** ≤
|
|
750
|
+
5. **P2(多芯片 + HAL 外设源文件按需落位)** 未开工;P3(gdb MI 常驻会话)**已完成**,见 `docs/development-notes.md` §37 —— `stm32_debug_eval` 优先走常驻 MI(单条命令 20–70 ms),MI 连不上才退回每次 `gdb -batch`;`continue`/`next`/`step` 会在 3 s 窗口里等 `*stopped` 并报停点(`formatStopLocation`,见 §40),`si`/`stepi`/`ni`/`nexti` 走单指令步进(`steppingCommandFor`,见 §43.1);`stm32_watch` 的采样提示会区分「目标本来就在停着」(§43.2);RTT dump 尾部失步不再提前收尾,且帧头对齐改在 `parsed.rest` 上做(§43.3);RTT 写侧由弱符号 `rtt_lock`/`rtt_unlock` 兜临界区(裸机存/恢复 PRIMASK,RTOS 覆盖成 mutex,§44.1),周期日志打 `drop=%u` 让丢帧可见(环满期间表现为内容冻结,§44.2),连接被拒/被重置不再误报「目标里没有控制块」(`sessionGoneHint`,§44.4)。
|
|
751
|
+
6. **docs/diagrams/** 那两张 HTML 图有 2 MB 原始 / 891 KB gz,已经不进 npm 包**(package.json 的 files 从 docs 收窄成 docs/*.md)。这事现在由 `scripts/pack-size.mjs`(npm run test:size)守着:tarball ≤1.2 MB、templates/** 里的运行时资产(.ioc/.xml/.ld/.json/.cfg/.svd/.csv)≤40 KB 且单文件 ≤24 KB(.md 文档与源码不计入资产,见 development-notes §46.4)、包内禁 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。实测包体 509.9 KB / 99 个文件。
|
|
747
752
|
7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
|
|
748
753
|
8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
|
|
749
754
|
9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
|
|
@@ -751,9 +756,72 @@ const fake = {
|
|
|
751
756
|
11. **别用 .elf 文件大小判「超 Flash」**:带 `-g3` 的 20 KiB 固件,.elf 里有 600 KB 调试信息,按文件大小判会把正经 C8T6 工程误报成超容量。doctor 因此读 ELF program header,只累加 `p_paddr` 落在 0x08000000 起 1 MiB 的 `PT_LOAD` 的 `p_filesz`;解析不出 program header 时才退回文件大小并注明是粗算。
|
|
752
757
|
12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
|
|
753
758
|
13. **B3 的真机计时还欠着**:会话复用快路径只有假探针(假 subprocess + 本地假 Tcl 服务端)的数字,真机 10 连读没测成——当时插的是 WCH-Link(`USB\VID_C251&PID_F001`),openocd 0.12 init 直接报 `Error: CMSIS-DAP command CMD_INFO failed.`,hid / bulk 后端与 `adapter speed 1000` 都试过;同一句在 B3 之前的旧版一次性路径上也复现,所以不是这次改动引入的。**复测方法**:换回 CMSIS-DAP 探针后跑 `stm32_regs_read` 连读 10 次 `0x4001100C`,看报告里的 `durationMs` 与 `reusedSession`。
|
|
754
|
-
14. **RTT
|
|
755
|
-
15. **寄存器符号名与位域解释只有离线验证**:`svd-units` 39
|
|
759
|
+
14. **RTT 已真机验证(2026-11-01)**:`rtt-units` 33 例仍全离线(假 subprocess + 假端口),但真板上跑通了 start → dump(1 kHz 固件打印、`dma` 与 `t` 1:1)→ stop(openocd 一并退出、探针归还)→ flash 的完整链路,见 development-notes §10.2/§39/§40。剩下的设计取舍(只有通道 0 / 无 defmt 解码 / 默认占 3 KB RAM)见 development-notes §30.6。**复现命令**(`_rich_hal` 上验过):`stm32_rtt action=start projectDir=<工程> addr=0x20000f88` → `action=dump seconds=3` → `action=stop`。
|
|
760
|
+
15. **寄存器符号名与位域解释只有离线验证**:`svd-units` 39 例全离线(真实内置 SVD + 假 subprocess + 假 Tcl 服务端),**没有一次「真板子 + 真探针 + `GPIOC.ODR`」**(与坑 13 同一个 WCH-Link 问题)。**复测方法**:换回 CMSIS-DAP 探针后 `stm32_regs_read addresses=["GPIOC.ODR","0x4001100C"]`,看 `samples[0].name` / `fields` 与 notes 里的 SVD line。
|
|
761
|
+
|
|
762
|
+
## 12. 0.1.5 增补:串口 P1 与寄存器 21 族
|
|
763
|
+
|
|
764
|
+
> 接续第 11 章。上面 1–15 条是 0.1.4 及更早的记录,其中的数字不动;这里只补 0.1.5 新增的两条阅读线。
|
|
765
|
+
|
|
766
|
+
### 12.1 串口(`stm32_serial`,Windows P1)
|
|
767
|
+
|
|
768
|
+
- 新增文件:`src/engine/serial.ts`(文件 IPC 客户端 + 会话表 + 端口记忆)、`src/tools/serial.ts`(7 个动作的 schema / 渲染 / 错误 hint)、`src/data/serial-config.ts`(默认值与 `serial.json` 读写)、`templates/serial/bridge.ps1`(约 18 KB,纯 ASCII,真正持有 COM 口)、`test/serial-units.test.mjs` 与 `test/fixtures/serial-fake-bridge.mjs`。
|
|
769
|
+
- 阅读顺序:`tools/serial.ts` 的参数 schema 与 `ACTIONS` → `engine/serial.ts` 的 `openSerial` / `sendSerial` / `readSerial` / `transactSerial` / `closeSerial` / `serialStatus` → `templates/serial/bridge.ps1` 的 `Main` 循环(20 ms 轮询串口 / 100 ms 扫 cmd / 1 s 心跳 / 5 s 查父进程)。**契约不是 RPC,而是目录里的文件**:`cmd/<id>.json` 进、`done/<id>.json` 回,流水在 `rx.ndjson` / `tx.ndjson`,状态在 `status.json`。
|
|
770
|
+
- 不要踩的:`spawn` 不能用 `detached`(Windows 上会翻成 `DETACHED_PROCESS`,powershell.exe 5.1 直接 exit 0);`bridge.ps1` 必须保持 ASCII(PS 5.1 按 ANSI 解码无 BOM 脚本);重复 `open` 由引擎的 `openChain` 串行化并返回 `already-open`;`read` 的 `cursor` 是 `rx.ndjson` 的字节偏移(`nextCursor`),跨轮不重贴历史靠它。
|
|
771
|
+
- 边界:P1 只做 Windows;不含 UI 面板 / SSE / 自动重连 / 多会话。真机缺口见 development-notes §86(真桥只验过失败路径)。
|
|
772
|
+
- 计数口径(0.1.5 起):`src/tools/` 共 24 个文件(23 个工具文件 + `project-dir.ts`),注册工具 **25 个**(`debug-session.ts` 一个文件注册 `_session` / `_eval` / `_stop` 三个)。第 4 章已按这个口径更新。
|
|
773
|
+
|
|
774
|
+
### 12.2 寄存器路线:13 → 21 族
|
|
775
|
+
|
|
776
|
+
- 事实层:`assets/device/<族>/chips.json` 现在有 21 族;`src/data/cmsis-sources.ts` 的 `CMSIS_FAMILIES` 也是 21 项(新增 H5 / H7 / L4+ / L5 / U3 / U5 / WBA / WL)。F1 仍走 `src/data/stm32f1.ts` 的 `resolveF1Chip()`,其余族走 `CMSIS_FAMILIES` + `DeviceFactsChip`。
|
|
777
|
+
- GPIO 使能位分四种:`moder`(原 F1 口径)、`moder-ahb4`(H7,GPIO 在 AHB4ENR)、`moder-ahb2enr1`(U3 / U5,GPIO 在 AHB2ENR1)、`moder-ahb2`(其余)。读 `src/data/register-gpio.ts` 时先看芯片记录选的是哪一种。
|
|
778
|
+
- 链接脚本:`DeviceFactsChip` 新增可选 `linkerRam`(origin / sizeBytes / region),H7 的 138 颗都带 DTCM 128 KiB,U5 按 line 给 256 / 768 / 2496 KiB 窗口;`planRegisterLinker` 优先用它。L4+ 与 L5 是连续单块,不需要 `linkerRam`。
|
|
779
|
+
- 8 族矩阵已跑完(t6):`create→build` 8/8 通过、warning 0 / error 0,逐族 FLASH/RAM 与两处模板修复(按族 `-mcpu`、H7 的 `cachel1_armv7.h`)见 development-notes §87.5;别把「已下载 CMSIS + 生成 .ld」当成「已编译验收」。
|
|
780
|
+
|
|
781
|
+
## 13. 0.1.5 增补:安装包下载(`stm32_download`)
|
|
782
|
+
|
|
783
|
+
> 接续 §12。只做「拿到安装包」,不做「安装」:插件负责下载与 SHA256 校验,双击安装器、接受许可、过 UAC 都由用户完成。
|
|
784
|
+
|
|
785
|
+
### 13.1 四种模式
|
|
786
|
+
|
|
787
|
+
| 模式 | 触发 | 行为 |
|
|
788
|
+
| --- | --- | --- |
|
|
789
|
+
| `plan` | `dryRun: true`(默认) | 只返回 URL、文件名、版本、SHA256、下载目录与安装提示,不联网 |
|
|
790
|
+
| `direct` | `dryRun: false` + `confirm: true`,组件是 J-Link | 下载到下载根目录;边写边算哈希,校验通过才原子改名;已有同哈希文件直接复用(`cached: true`) |
|
|
791
|
+
| `manual` | `dryRun: false` + `confirm: true`,组件是 CubeMX / CubeProgrammer | 打开 ST 官方下载页(需要 myST 登录与许可),不猜直链 |
|
|
792
|
+
| `file` | 传了 `file` | 只校验本地安装包的 SHA256(有官方哈希就对比),不执行、不复制 |
|
|
793
|
+
|
|
794
|
+
### 13.2 阅读顺序
|
|
795
|
+
|
|
796
|
+
- `src/tools/download.ts`:`stm32_download` 的参数 schema(`component` / `dryRun` / `confirm` / `file` / `outDir` / `openPage` / `timeoutMs`)→ `execute` 的模式判定 → 21 个必填字段的 report → `render` 的中文行。`confirm` 只对 `direct` / `manual` 生效;`file` 只读。
|
|
797
|
+
- `src/engine/download.ts`:`planDownload`(URL 与目标路径)→ `downloadUrlToFile`(fetch + `getReader` + `.part-<pid>-<ts>` + 边写边算哈希 + 校验后 rename)→ `sha256File` → `inspectInstallerFile`。下载根目录的优先级是 `DSH_STM32_DOWNLOADS` > `%LOCALAPPDATA%\dsh-stm32\downloads` > `%USERPROFILE%\AppData\Local\...` > 临时目录。
|
|
798
|
+
- `test/download-units.test.mjs`:5 条离线用例——两种计划、下载目录覆盖、本地文件校验、本地 HTTP 直链的下载/缓存/哈希不符清理、工具层三种模式。
|
|
799
|
+
|
|
800
|
+
### 13.3 安全边界
|
|
801
|
+
|
|
802
|
+
- **不执行安装器**:不 spawn 安装包、不传 `/S` 之类的静默参数;`manual` 只 spawn `cmd /c start` 打开官方页面。
|
|
803
|
+
- **不写注册表、不改 PATH、不请求管理员**。J-Link 的 USB 驱动由安装器自己处理:`-InstAllUsers=1` + UAC;现代探针默认 WinUSB,只有停产老探针才需要 legacy 驱动。
|
|
804
|
+
- **URL 白名单**:只有 SEGGER 官方直链与 ST 的两个官方页面;J-Link 版本与 SHA256 写死在 `JLINK_DOWNLOAD`,升级要同时改 URL 与哈希。
|
|
805
|
+
- **失败清理**:网络中断、超时(默认 10 分钟,下限 5 秒)、超过 `maxBytes`(默认 300 MB)或哈希不符时删除临时文件;目标文件只在哈希通过后出现。
|
|
806
|
+
|
|
807
|
+
### 13.4 验证边界
|
|
808
|
+
|
|
809
|
+
- J-Link 直链只做了 `HEAD`:HTTP 200、`content-length: 59,012,800`;**没有真的下载 59 MB**,也没有运行安装器(按设计永远不运行)。
|
|
810
|
+
- 下载/校验/缓存/失败清理由本地 HTTP 服务覆盖;ST 的两个页面只验证了 URL 与计划输出,没有打开浏览器。
|
|
811
|
+
- 真机安装、驱动加载、CubeMX/CubeProgrammer 的 myST 下载仍未验。
|
|
812
|
+
|
|
813
|
+
### 13.5 计数口径(0.1.5 起)
|
|
814
|
+
|
|
815
|
+
| 项 | 当前值 |
|
|
816
|
+
| --- | --- |
|
|
817
|
+
| TypeScript | 111 个文件、43,057 行(`src/`,不含 client) |
|
|
818
|
+
| `src/tools/` | 24 个文件 / 25 个注册工具 / 7,616 行 |
|
|
819
|
+
| `src/engine/` | 65 个 `.ts` / 26,961 行 |
|
|
820
|
+
| `src/data/` | 18 个 `.ts` / 7,785 行 |
|
|
821
|
+
| 单测 | 60 个套件 / 947 pass / 0 fail(`node test/run-units.mjs`) |
|
|
822
|
+
|
|
823
|
+
第 1–11 章的目录表与模块计数保留 D 阶段原样(45 个 engine 模块、23 个 tools 文件),读旧章节时以本节为准。
|
|
756
824
|
|
|
757
825
|
---
|
|
758
826
|
|
|
759
|
-
读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
|
|
827
|
+
读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
|
package/lib/commands/register.js
CHANGED
|
@@ -222,7 +222,7 @@ function envText(rows, configPath) {
|
|
|
222
222
|
lines.push(anyMissing ? "要装:回「装」,我跑 stm32_env_install 出计划(先不下载)" : "都齐了:/stm32-build 就能编译");
|
|
223
223
|
return { kind: "success", text: lines.join("\n") };
|
|
224
224
|
}
|
|
225
|
-
/**
|
|
225
|
+
/** 注册七条斜杠命令;宿主没组合 commands 服务时直接返回(工具不受影响)。 */
|
|
226
226
|
export function registerCommands(ctx) {
|
|
227
227
|
const commands = ctx.commands;
|
|
228
228
|
if (commands === undefined)
|
package/lib/data/chips.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* L1:引脚名合法性 + 由本机 CubeMX db 派生的引脚表。
|
|
3
3
|
*
|
|
4
4
|
* 用户 2026-10-31「内置表删了吧」之后,这里**不再有任何内置芯片/引脚表**(原来的 CHIPS / KNOWN_CHIPS /
|
|
5
|
-
* findChip
|
|
5
|
+
* findChip 已删)。原因:芯片事实的唯一来源是内置资源 device/f1/chips.json,而那份文件只有 pinCount
|
|
6
6
|
* (封装上有多少根脚),没有「这个封装有哪几根 GPIO」的清单——拿 pinCount 去猜 PA0-PB15… 等于又造一张表。
|
|
7
7
|
*
|
|
8
8
|
* 于是分工变成:
|
|
@@ -23,7 +23,7 @@ const MAX_PIN_NUMBER = 15;
|
|
|
23
23
|
/**
|
|
24
24
|
* 引脚名是否合法(未知/虚拟引脚一律放行)。
|
|
25
25
|
*
|
|
26
|
-
* 为什么不再按型号判「有没有这根脚」:那需要「封装 →
|
|
26
|
+
* 为什么不再按型号判「有没有这根脚」:那需要「封装 → 引脚清单」的事实,而内置资源只给了 pinCount。
|
|
27
27
|
* 真正的引脚存在性请用 deriveChipPinTable(本机 CubeMX db)——它给的是实测清单,不是符号表。
|
|
28
28
|
*/
|
|
29
29
|
export function isKnownPin(pin) {
|
|
@@ -147,7 +147,7 @@ export function deriveChipPinTable(input) {
|
|
|
147
147
|
pins: [],
|
|
148
148
|
notes: [
|
|
149
149
|
"引脚表:没有本机 CubeMX db(" + why + "),引脚存在性不校验(isKnownPin 只查引脚名是否合法);" +
|
|
150
|
-
"
|
|
150
|
+
"插件不内置引脚表(内置资源里也不再有 db 副本),需要逐脚校验就装 CubeMX —— 插件直接读它的 db/mcu",
|
|
151
151
|
],
|
|
152
152
|
};
|
|
153
153
|
}
|