dsh-stm32 0.1.1 → 0.1.3

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 (62) hide show
  1. package/README.md +98 -31
  2. package/README_EN.md +96 -29
  3. package/docs/development-notes.md +837 -4
  4. package/docs/reading-guide.md +759 -0
  5. package/lib/commands/register.js +49 -0
  6. package/lib/data/chips.js +147 -30
  7. package/lib/data/clock-f1.js +158 -0
  8. package/lib/data/cmsis-sources.js +237 -42
  9. package/lib/data/device-facts.js +201 -0
  10. package/lib/data/stm32f1.js +130 -0
  11. package/lib/data/svd.js +627 -0
  12. package/lib/engine/assets.js +924 -0
  13. package/lib/engine/breakpoints.js +242 -0
  14. package/lib/engine/build.js +115 -16
  15. package/lib/engine/cache.js +56 -0
  16. package/lib/engine/clock-plan.js +608 -0
  17. package/lib/engine/cmake-sources.js +428 -0
  18. package/lib/engine/debug-session.js +153 -5
  19. package/lib/engine/debug.js +114 -15
  20. package/lib/engine/doctor.js +395 -4
  21. package/lib/engine/fetch.js +174 -30
  22. package/lib/engine/flash.js +70 -9
  23. package/lib/engine/generate.js +11 -0
  24. package/lib/engine/hal-chip.js +230 -0
  25. package/lib/engine/ioc-plan.js +33 -7
  26. package/lib/engine/msys2-install.js +332 -61
  27. package/lib/engine/probe-error.js +212 -0
  28. package/lib/engine/probe-session.js +311 -0
  29. package/lib/engine/project-export.js +129 -0
  30. package/lib/engine/register-clock.js +132 -0
  31. package/lib/engine/register-linker.js +129 -0
  32. package/lib/engine/register-template.js +115 -20
  33. package/lib/engine/regs.js +2 -0
  34. package/lib/engine/rtt.js +600 -0
  35. package/lib/engine/scaffold.js +104 -28
  36. package/lib/engine/zip.js +142 -0
  37. package/lib/index.js +10 -0
  38. package/lib/skill/stm32-workflow.js +3 -3
  39. package/lib/tools/assets.js +341 -0
  40. package/lib/tools/build.js +12 -0
  41. package/lib/tools/cache.js +47 -8
  42. package/lib/tools/debug-session.js +40 -5
  43. package/lib/tools/debug.js +41 -4
  44. package/lib/tools/doctor.js +22 -2
  45. package/lib/tools/flash.js +15 -3
  46. package/lib/tools/generate.js +3 -0
  47. package/lib/tools/ioc-apply.js +2 -0
  48. package/lib/tools/ioc-inspect.js +2 -0
  49. package/lib/tools/ioc-plan.js +198 -4
  50. package/lib/tools/project-create.js +50 -1
  51. package/lib/tools/project-export.js +100 -0
  52. package/lib/tools/regs.js +453 -61
  53. package/lib/tools/route-plan.js +3 -0
  54. package/lib/tools/rtt.js +347 -0
  55. package/package.json +5 -3
  56. package/templates/register/CMakeLists.txt +25 -6
  57. package/templates/register/Core/Inc/rtt.h +103 -0
  58. package/templates/register/Core/Src/main.c +43 -9
  59. package/templates/register/Core/Src/rtt.c +297 -0
  60. package/templates/scaffold/RTT.md +86 -0
  61. package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
  62. package/templates/scaffold/openocd.cfg +8 -0
@@ -0,0 +1,759 @@
1
+ # dsh-stm32 源码精读指南
2
+
3
+ > 面向:第一次读这个仓库、并且要改它的人。
4
+ > 规模:75 个 TypeScript 文件约 23.2k 行,外加一个手写的浏览器 bundle(client/client.js,682 行)。**芯片事实不在仓库里**:`src/data/device-facts.ts` 只读本地资源包缓存(`~/.dsh-stm32/assets/<版本>/device/f1/chips.json`),插件不内置任何芯片表(2026-10-31 删掉了 chip-table.json / f1-ram.generated.ts / 手写容量档表 / 内置引脚表)。
5
+ > 读完这份指南你应该能回答:一次工具调用从宿主进来到 openocd 退出中间经过了谁;哪几条不变量破了一定出事;要改某个功能得动哪几个文件;哪些行为有测试兜着、哪些只能上板子验。
6
+ >
7
+ > 配套文档:docs/development-notes.md(按时间记的决策与被坑记录)、docs/logic-audit.md(历史审计条目)、README.md(用户视角)。
8
+
9
+ ## 使用前:先看两张图(浏览器直接打开,单文件、离线可用)
10
+
11
+ 文字适合查细节,图适合先建立整体形状。下面两张是本文档的可视化版本(Archify 生成,单 HTML、内联 SVG,可切深浅色、可导出 PNG/SVG):
12
+
13
+ | 图 | 文件 | 先看什么 |
14
+ | --- | --- | --- |
15
+ | 架构总览 | [docs/diagrams/dsh-stm32-architecture.html](diagrams/dsh-stm32-architecture.html) | 五层(装配 / 契约 / 引擎 / 事实表 / 客户端)怎么排;engine 五簇各自吃什么、吐什么;子进程桥为什么是唯一出口;哪些东西真在盘上。图右下「节点索引」可以逐个跳转。 |
16
+ | 主线旅程 | [docs/diagrams/dsh-stm32-journey.html](diagrams/dsh-stm32-journey.html) | 一句话需求 → 定路线 → 体检 → 建工程 → 生成 → 改 USER CODE → 编译 → 上板。六列是时间,四条 lane 是谁在做;红色 lane 是门禁与失败分支。 |
17
+
18
+ 两张图都带「来源 N」角标:点开是 `path`(架构图的多数节点还带行号),对照第 5 章的表即可跳到具体文件。静态预览:[架构总览](diagrams/dsh-stm32-architecture.png) · [主线旅程](diagrams/dsh-stm32-journey.png)。
19
+
20
+ 图的源文件(Archify candidate JSON)不随仓库发布,放在工作区的 `.archify/` 下;要改图或重新生成,见 [development-notes.md](development-notes.md) §23 里的命令与坑。下文第 1、7 章的 Mermaid 是同一套结构的速览版,方便在 Markdown 预览器里直接看。
21
+
22
+ ## 0. 心法:四个层次,一条竖线
23
+
24
+ 代码是严格分层的,而且分层方向只有一条:**上层知道下层,下层不认识上层**。读任何一段代码,先判断它属于哪一层,再判断它有没有越界。
25
+
26
+ | 层 | 目录 | 干什么 | 绝对不能干的事 |
27
+ | --- | --- | --- | --- |
28
+ | L4 装配 | src/index.ts、src/commands、src/skill | 把服务接上、把工具/命令/skill 注册进宿主 | 写业务逻辑 |
29
+ | L3 契约层 | src/tools(21 个文件:21 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
+ | L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
31
+ | L1 事实表 | src/data(10 个数据模块) | 设备事实(`device-facts.ts` 从资源包缓存读 chips.json;插件不内置芯片表)、由本机 CubeMX db 派生的引脚表、镜像 URL、固件族、F1 时钟树、安装指引、搜索路径、配置读写、SVD 寄存器表(`svd.ts`,来自资源包 `full` 档) | 起进程、写工程文件 |
32
+
33
+ 跨层的只有两样东西:**SubprocessService**(进程能力,从 ctx 一路当参数传到 engine)和 **DshContext**(宿主服务袋)。
34
+
35
+ ### 0.1 四条反复出现的设计约定
36
+
37
+ 1. **零运行时依赖。** package.json 的 dependencies 是空的,devDependencies 只有 typescript 与 @types/node。所有宿主能力都靠注入:tools / subprocess / jobs / webServer / commands / skills / workingDirectory。宿主类型不随 asar 发布(只有编译后的 JS),所以 src/types.ts 手写了本插件真正用到的那一小块契约——这是有意的,不是偷懒。
38
+ 2. **engine 全部是「纯函数 + 显式注入」。** 凡是需要起进程的地方,都把 SubprocessService 当第一个参数传进去(`runBuild(subprocess, request)`、`runFlash(subprocess, request)`、`probeAll(subprocess, ...)`)。好处是单测可以塞假件,不用真装工具链:test/harness.mjs 与各套件里的 scriptedSubprocess 就是干这个的。
39
+ 3. **tools 只做三件事:校验、门禁、渲染。** 每个工具文件的结构是固定的:`<X>_TOOL` 常量 → 参数 schema → 输出 schema(report 上 additionalProperties: false)→ execute(resolveProjectDir + validateToolArgs + ensureToolchain + 调 engine)→ render(把 report 变成中文行)。业务逻辑写在 tools 里就是放错了层。
40
+ 4. **一切写盘都可回退。** 覆盖工程文件前先备份到 `<工程>/.dsh-stm32/backups/<YYYYMMDD-HHmmss>-<tag>`;文件编码认不出来就拒绝写而不是猜;超长路径走 `\\?\` 前缀;tar 解包先做路径与类型白名单。这条约定是四批审计(docs/logic-audit.md)之后的硬要求。
41
+
42
+ ## 1. 整体框架
43
+
44
+ ```mermaid
45
+ flowchart TD
46
+ HOST["DSH 宿主 ctx<br/>tools / subprocess / jobs / webServer / commands / skills"] --> IDX["src/index.ts<br/>apply(ctx) 装配"]
47
+ IDX --> TOOLS["src/tools/*<br/>21 个工具"]
48
+ IDX --> CMDS["src/commands/register.ts<br/>7 条斜杠命令"]
49
+ IDX --> SKILL["src/skill/stm32-workflow.ts<br/>红线 skill"]
50
+ IDX --> WEB["src/engine/web-routes.ts<br/>6 条 HTTP 路由"]
51
+ IDX --> EVT["turn/end、session/disposed、dispose<br/>把探针还回去"]
52
+ TOOLS --> ENGINE["src/engine/*<br/>45 个纯逻辑模块"]
53
+ CMDS --> ENGINE
54
+ WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
55
+ API --> ENGINE
56
+ ENGINE --> DATA["src/data/*<br/>10 个数据模块(芯片事实读资源包缓存;SVD 在 full 档)"]
57
+ ENGINE --> RUN["src/engine/subprocess-runner.ts"]
58
+ RUN --> OS["宿主 subprocess 服务"]
59
+ OS --> BIN["gcc / cmake / ninja / openocd / gdb<br/>java(CubeMX) / reg.exe / pacman / objcopy"]
60
+ CLIENT["client/client.js<br/>浏览器 bundle"] -->|"fetch /dsh-stm32/api/*"| WEB
61
+ ```
62
+
63
+ 三个「入口」其实是同一件事的三种外壳:**模型调工具**(tools)、**用户打斜杠命令**(commands)、**用户在设置面板点按钮**(web-api)。三者最终都落到 engine 的同一批函数上,所以行为一致、错误文案一致、门禁一致。
64
+
65
+ ### 1.1 目录与行数全景
66
+
67
+ | 目录 | 文件数 | 行数 | 说明 |
68
+ | --- | --- | --- | --- |
69
+ | src/ | 4 | 803 | index.ts 127、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
70
+ | src/tools/ | 21 | 6623 | 21 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 regs.ts 735 行(D 阶段从 272 涨到 735),其次是 route-plan.ts 576 行 |
71
+ | src/engine/ | 46 | 18981 | 见第 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 从资源包缓存读设备事实、svd.ts 读 `full` 档的寄存器表;仓库里没有任何芯片表),见第 6 章 |
73
+ | templates/ | 20 | — | 工程脚手架与寄存器版模板(CMake、链接脚本、launch/settings、openocd.cfg、demo.ioc;C 阶段加了寄存器版的 `Core/Src/rtt.c` + `Core/Inc/rtt.h` 与 HAL 脚手架 `scaffold/RTT.md`) |
74
+ | client/ | 1 | 682 | 设置面板的前端 bundle(手写 JS,不经打包器) |
75
+ | test/ | 36 套件(run-units 登记)+ 15 个 e2e 脚本 + 4 个辅助脚本 | — | 见第 9 章 |
76
+ | scripts/ | 4 | 405 | copy-client.mjs(24)、gen-xcube-catalog.mjs(151)、pack-size.mjs(80)、pack-smoke.mjs(150)。芯片表的生成脚本 2026-10-31 已挪到资源仓库(`scripts/build-assets.mjs`) |
77
+
78
+ > 全书行数统一口径:按文件里的换行符数(`content.split("\n").length`,等价于编辑器的「块末行号」),2026-10-31(D 阶段末)重数过一遍——第 1、4.1、4.2、5、6 章都按这个口径,和本指南更早版本的数字会有几行到几十行的差异。
79
+
80
+ ## 2. 阅读顺序
81
+
82
+ 不要从 engine/msys2-install.ts(2313 行)开始读,会迷路。按下面的顺序走,每一站都有一条完整的「从宿主到硬件」的链路可以跟到底。
83
+
84
+ | 站 | 读什么 | 行数 | 读完能回答 | 建议 |
85
+ | --- | --- | --- | --- | --- |
86
+ | 1 | src/index.ts、src/types.ts | 315 | 插件怎么被加载?宿主给了我什么?工具/命令/skill/路由各自怎么注册? | 20 分钟 |
87
+ | 2 | src/tools/flash.ts → src/engine/flash.ts → src/engine/subprocess-runner.ts → src/engine/tool-env.ts | 915 | 一次工具调用从头到尾长什么样?参数怎么校验?进程怎么起、环境变量怎么注入? | 1 小时 |
88
+ | 3 | src/engine/toolchain-gate.ts → probe.ts → src/data/search-roots.ts → src/data/toolchain-config.ts | 1649 | 门禁怎么判「缺件」?为什么快路径也要跑一次版本命令?配置文件的 CAS 写是什么? | 1.5 小时 |
89
+ | 4 | src/engine/generate.ts → generate-script.ts → generate-cache.ts → layout.ts → ioc.ts → ioc-plan.ts → clock-plan.ts → code-patch.ts → text-file.ts → usercode-merge.ts | 3229 | CubeMX 怎么被驱动?产物怎么搬进 Core/?为什么改代码要按字节拼接?.ioc 事务的 SHA 校验挡的是什么?时钟怎么就近取档、目标不可达时怎么写? | 3 小时 |
90
+ | 5 | src/engine/scaffold.ts → hal-chip.ts → register-template.ts → register-clock.ts → register-linker.ts → vscode-config.ts → build.ts → project-export.ts → zip.ts → fs-longpath.ts | 2798 | 新工程怎么造出来?两条路线为什么差别这么大(HAL 碰 CubeMX / 寄存器只用缓存)?型号怎么变成启动文件、设备宏和 `<DeviceId>_FLASH.ld`?编译产物 hex/bin 怎么来? | 2.5 小时 |
91
+ | 6 | src/engine/fetch.ts → cache.ts → tar.ts → firmware-install.ts → thirdparty.ts → xcube.ts → msys2-install.ts | 4652 | sha256 门禁在哪一环?缓存怎么保证可恢复?固件包为什么装到 dsh-firmware?安装计划怎么做到只报缺件? | 3 小时 |
92
+ | 7 | src/engine/debug.ts → debug-session.ts → regs.ts → doctor.ts → route-plan.ts → web-api.ts → client/client.js → src/commands/register.ts | 4082 | 调试会话的租约与归属怎么算?扫描链/寄存器怎么读?doctor 怎么核对型号/启动文件/.ld 是否配套?路线评估的判定规则?设置面板走什么通道? | 3 小时 |
93
+
94
+ 每一站的「流程」在第 7 章都有对应的图,读到不懂的地方先跳到图上找位置。
95
+
96
+ ## 3. 入口层
97
+
98
+ ### 3.1 src/index.ts(127 行)
99
+
100
+ 三件事,只有三件:
101
+
102
+ 1. **声明身份与依赖**:`export const name = "dsh-stm32"`、`export const inject = ["tools", "subprocess", "jobs"]`。这三个是硬依赖,缺了插件不加载。
103
+ 2. **apply(ctx) 里按「先探测、再操作」的顺序注册 21 个工具**:env_probe → env_install → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → build → flash → debug_run → debug_session → regs_read → route_plan → rtt → assets → cache → doctor → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
104
+ 3. **注册可选层并挂三个事件**:commands / skills 走 `ctx.inject([...], scope => ...)`,宿主没组合这些服务时静默跳过,工具照常工作;webServer 路由在`registerWebRoutes` 里自己判断。
105
+
106
+ 三个事件是本插件唯一的「状态清理入口」,也是很容易读漏的地方:
107
+
108
+ ```ts
109
+ ctx.on("session/event", (session, event) => {
110
+ if (event?.type !== "turn/end") return;
111
+ const owner = callerIdOf(event, session); // A9:尽量挖出发起方 agent id
112
+ void debugSessions.stop("turn/end:本轮输出结束,把探针还给你",
113
+ owner === "" ? {} : { requireOwner: owner });
114
+ });
115
+ ctx.on("session/disposed", () => { void debugSessions.stop("session/disposed"); });
116
+ ctx.on("dispose", () => { void debugSessions.stop("插件卸载"); });
117
+ ```
118
+
119
+ 为什么要在 turn/end 就关会话:宿主把探针当独占资源,插件攥着它的时候用户在 VS Code 里按 F5 会失败。所以「我一输出完、等你回复」就必须松手(规格 §6.4)。`callerIdOf` 是本文件唯一的业务函数,它按「可能的位置逐个试」的方式从事件里掏 agent id——宿主没公开事件结构,掏不到就返回空串,debug-session 见到空串退回「无条件全关」的老行为,保证不漏关。
120
+
121
+ ### 3.2 src/types.ts(196 行)
122
+
123
+ 这不是「类型文件」,是**契约清单**。文件头注释写明了为什么自写:asar 里只有编译后的 JS,`@deepseek-ai/dsh-tools` 的类型装不到。所以这里只声明本项目真正用到的那部分。
124
+
125
+ 读的时候注意四个坑(都是踩过的):
126
+
127
+ | 契约 | 坑 | 后果 |
128
+ | --- | --- | --- |
129
+ | `SpawnSpec.cwd` | 宿主 subprocess 要求必填,不传直接抛 TypeError | 所有 engine 起进程都必须显式给 cwd |
130
+ | `SpawnSpec.stdio` | stdout/stderr 要写成 `{ maxBytes }` 才是收集式,否则拿不到输出 | 忘记 maxBytes 时报告里日志为空 |
131
+ | `SkillDefinition.source` | register 不校验,真正加载时才校验必须是字符串 | 漏了 source 的表现是 skill 出现在目录里,一加载就报 `loaded skill ... source must be a string` |
132
+ | `WebServerService` | 宿主没发布 IncomingMessage/ServerResponse 类型 | request/response 用 any,只在 web-routes.ts 里收口 |
133
+
134
+ ### 3.3 src/skill/stm32-workflow.ts(35 行)
135
+
136
+ 内容是一屏红线(R1–R5 + 12 条踩过的坑),运行时注册而不是打包成文件——「凡是能注册的服务就不要依赖路径约定」。口径已从「本机这块 C8T6」改成 **STM32F1 全系**(F100/101/102/103/105/107):换型号必须启动文件、设备宏、链接脚本三者一起换,外加时钟跟着 line 的上限走。
137
+
138
+ - **R1** 代码只写在 `/* USER CODE BEGIN X */` 与 `END` 之间(CubeMX 承诺原样保留的唯一区域)。
139
+ - **R2** 不许改生成区(main()、MX_*_Init()、main.h 的 Private defines、*_hal_msp.c、*_it.c、CMakeLists、.mxproject、.ioc、以及本型号的启动文件与链接脚本)——理由很具体:这些文件由 .ioc 重写,手改会被无声覆盖且编译不报错。链接脚本按 `<DeviceId>_FLASH.ld` 命名(C8T6 → `STM32F103C8Tx_FLASH.ld`、RCT6 → `STM32F103RCTx_FLASH.ld`、F107VCT6 → `STM32F107VCTx_FLASH.ld`),旧名 `STM32F103XX_FLASH.ld` 只是 C8T6 的兼容副本。
140
+ - **R3** .ioc 只能走事务:`stm32_ioc_plan` → 用户确认 → `stm32_ioc_apply`,参数名是 **planId**(不是 plan_id),源文件 SHA-256 变了就拒绝。改时钟也走同一条事务(`clock: { targetHz }` 或钉死 `pllMul`):目标频率不可达时报告写「不可达,已选 X MHz(±Y)」并把派生键(PLLMUL / SYSCLKFreq_VALUE / HCLKFrequency / APB1-APB2 prescaler)全量重算;超限(SYSCLK >72、APB1 >36、ADC >14)一个键都不写。
141
+ - **R4** 不许生成 No_Debug 的 SYS 配置(会关掉 PA13/PA14 的 SWD,烧一次就永久失联,只能 BOOT0 救)。
142
+ - **R5** 烧录与调试分开:flash 一次性 program-verify-reset-exit,debug_run 只在需要时开调试会话。
143
+
144
+ ### 3.4 src/commands/register.ts(445 行)
145
+
146
+ 七条斜杠命令:`/stm32-env`、`/stm32-setup`、`/stm32-doctor`、`/stm32-build`、`/stm32-flash`、`/stm32-debug`、`/stm32-stop`。
147
+
148
+ 文件里真正值得读的是前面四个函数,后面全是 handler:
149
+
150
+ - `tokenizeCommandLine(rawInput): CommandToken[]` —— 引号感知切词(审计 B7)。一次扫描:引号内不切、顺手剥引号、记下 `quoted` 标记,这样 `--flag` 只有在没被引号包住时才算 flag。原来是「先按空白切再剥引号」,遇到 `"C:/Users/张 三/proj"` 会把路径切两段。
151
+ - `parseInvocation(ctx, invocation)` —— 把切出来的 token 变成工程目录 + 其余选项;`needSubprocess(ctx)` 拿不到进程服务时返回一句话错误而不是抛异常。
152
+ - `commandGateWarning(ctx, capability, signal, ...)` —— 命令侧的门禁是 **warn 不是 block**(审计 B8):命令是用户手打的,缺件时应该「照常执行 + 前置一行警告」,而不是拒绝。
153
+ - `withGateWarning(warning, result)` —— 把警告行拼到 `CommandResult.text` 前面。
154
+
155
+ 7 条命令里有 6 条最终调用 engine 的同一个函数(build → runBuild,flash → runFlash …),所以它们和工具的唯一差别是:输入来自文本而不是 JSON、输出是一段中文。
156
+
157
+ ## 4. tools 层:21 个工具 + 1 个基础设施
158
+
159
+ ### 4.1 一个工具文件的固定骨架
160
+
161
+ 以 src/tools/flash.ts(203 行)为例,每个工具都是同一个模子:
162
+
163
+ ```ts
164
+ export const FLASH_TOOL = "stm32_flash"; // 1. 名字常量(测试与命令复用)
165
+ const reportSchema: JsonSchema = { ... }; // 2. 输出报告 schema(additionalProperties: false)
166
+ export const outputSchema: JsonSchema = { schema: reportSchema, render: formatFlashReport };
167
+
168
+ export function registerFlash(ctx: DshContext): void {
169
+ ctx.tools.register({
170
+ name: FLASH_TOOL,
171
+ description: "...",
172
+ parameters: { ... }, // 3. 参数 schema
173
+ output: outputSchema,
174
+ async execute(args, exec) { // 4. 校验 → 门禁 → engine → 渲染
175
+ const projectDir = await resolveProjectDir(ctx, args.projectDir, exec);
176
+ const gate = await ensureToolchain(ctx, { capability: "flash", envCheck: args.envCheck, signal: exec.signal });
177
+ if (!gate.ok) return blockedReport(projectDir, gate);
178
+ const report = await runFlash(ctx.subprocess, { ... });
179
+ return report;
180
+ },
181
+ });
182
+ }
183
+
184
+ export function formatFlashReport(report: FlashReport): string[] { ... } // 5. report → 中文行
185
+ ```
186
+
187
+ 三个细节值得记住:
188
+
189
+ 1. **输出 schema 是硬的。** 宿主会拿 `output.schema` 校验 execute 的返回值,report 上任何没声明的字段都会被判「工具返回了非法输出」——这正是 0.1.2 上板时抓到的缺陷(flash 失败时带一个故障分类字段,而 schema 漏声明它,于是失败路径直接崩;这个字段在 B2 之后叫 `probeError`,见 §5.4)。改 report 结构必须同步改 schema,test/schema-guard.mjs 就是为这条存在的。
190
+ 2. **门禁在工具层,不在 engine。** engine 假设工具链就位;`blockedReport` / `emptyReport` 是门禁拦截与早退时造「同形报告」的工厂,保证失败也是合法输出。
191
+ 3. **`resolveProjectDir` + `validateToolArgs`(tools/project-dir.ts,120 行)是所有工具的共同入口**:前者把 `projectDir` 参数 / 会话工作目录落成绝对路径,后者按 `RequiredArgSpec` 校验必填参数类型,报错文案统一。
192
+
193
+ ### 4.2 21 个工具一览
194
+
195
+ | 工具 | 文件(行) | engine 入口 | 门禁能力 |
196
+ | --- | --- | --- | --- |
197
+ | `stm32_env_probe` | env-probe.ts(284) | probe.buildTargets / probeAll + search-roots.resolveSearchConfig | 无 |
198
+ | `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
199
+ | `stm32_firmware_install` | firmware-install.ts(288) | firmware-install.planOrInstallFirmware | 无 |
200
+ | `stm32_project_create` | project-create.ts(387) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
201
+ | `stm32_project_export` | project-export.ts(122) | project-export.runExport | 无 |
202
+ | `stm32_code_patch` | code-patch.ts(130) | code-patch.patchUserCode | 无 |
203
+ | `stm32_generate` | generate.ts(311) | generate.runGenerate | generate(CubeMX 启动器 + JRE) |
204
+ | `stm32_ioc_inspect` | ioc-inspect.ts(243) | ioc.summarizeIoc | 无 |
205
+ | `stm32_ioc_plan` | ioc-plan.ts(398) | ioc-plan.planIocChanges + clock-plan.planClockChanges(引脚 / 键 / 时钟进同一个 candidate) | 无 |
206
+ | `stm32_ioc_apply` | ioc-apply.ts(137) | ioc-plan.applyIocPlan / rollbackIoc | 无 |
207
+ | `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
208
+ | `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
209
+ | `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
210
+ | `stm32_debug_session` / `_eval` / `_stop` | debug-session.ts(305,三工具同文件) | debug-session.DebugSessionManager(单例 debugSessions)+ releaseProbeFor | debug(仅 session 启动时) |
211
+ | `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
212
+ | `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
213
+ | `stm32_route_plan` | route-plan.ts(576) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
214
+ | `stm32_cache` | cache.ts(306) | engine/cache 全套 | 无 |
215
+ | `stm32_doctor` | doctor.ts(202) | doctor.runDoctor + collectChipConsistency(型号/启动文件/设备宏/.ld/Flash 五项一致性) | 无(它自己就是体检) |
216
+ | —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
217
+
218
+ 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**regs.ts 735 行**现在是 tools 层最大的(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**退居第二——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
219
+
220
+ ## 5. engine 层:45 个模块,十个域
221
+
222
+ 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。表里列 45 个;`src/engine/` 目录里实际有 46 个 `.ts`——`assets.ts`(资源包装配的小件)还没单独成行,读资源包那条链路时直接从 §5.7 与 `src/data/assets` 一起看。
223
+
224
+ ### 5.1 进程与路径(3 个,413 行)
225
+
226
+ | 模块 | 职责与关键导出 |
227
+ | --- | --- |
228
+ | subprocess-runner.ts(250) | 全插件唯一的进程入口。`runCapture(subprocess, request): Promise<RunOutcome>` 收集输出(stdout/stderr 文本、exitCode、signal、spawnError、timedOut、aborted、awaitQuiescence);`runStreaming(subprocess, request, onText)` 边跑边推。两处「注入 env」(审计 B4)就在这里:把 `envWithBinDirs` 的结果塞进 SpawnSpec,否则刚用 stm32_env_install 装好但宿主没重启时,门禁说「齐全」而 cmake 报 arm-none-eabi-gcc not found。 |
229
+ | tool-env.ts(56) | `envWithBinDirs(binDirs, base)`:binDirs 去重去空后**拼在原 PATH 前面**,Windows 上只留一个大小写正确的 `Path` 键;`toolSearchDirs(binDirs, base)` 给出「去哪找可执行文件」的有序目录表。 |
230
+ | fs-longpath.ts(107) | 长路径工具。`toLongPath` 加 `\\?\` 前缀、`existsLong`、`mkdirTrackedLong`(顺手记下新建的目录,失败时回收)、`copyFileLong`、`copyTreeLong`、`describeCopyFailure`。固件包的 Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc 这种深度在长用户名下会撞 MAX_PATH(审计 B17)。 |
231
+
232
+ ### 5.2 探测、搜索与门禁(engine 2 个 + data 2 个,1649 行)
233
+
234
+ | 模块 | 职责与关键导出 |
235
+ | --- | --- |
236
+ | probe.ts(363) | 「找一个可执行文件并问它版本」。`ProbeTarget`(id/label/candidates/versionArgs/hint/impact/install/verify/installability)、`resolveFromDirs` / `resolveToolIn`(先按 binDirs 找,再按需回退到宿主 resolveExecutable——回退由 `ProbeOptions.allowPathFallback` 控制,安装自检时关掉,防「用 PATH 里的旧工具冒充刚装好的」)、`probeTarget` / `probeAll`、`msys64RootFromBinDirs`、`buildTargets(config)`(把 SearchConfig 变成 9 个探测目标)。 |
237
+ | toolchain-gate.ts(495) | 门禁本体。`ToolchainCapability = build/flash/debug/generate`、`CAPABILITY_COMPONENTS`(build→gcc,cmake,ninja;flash→openocd;debug→openocd,gdb;generate→cubemx,cubemx-java)、`EnvCheckMode = block/warn/off`、`ensureToolchain`、`gateReportNotes`、`gateBlockedMessage`、`resetGateCache`。内部两条路:**快路径**(文件都在 → 再跑一次「主组件」的版本命令 smokeTarget,60 s 缓存);**慢路径**(全量 probeAll,结果缓存 60 s,取消时**不写缓存**——审计 A27)。 |
238
+ | data/search-roots.ts(421) | 搜索范围的事实表。DEFAULT_BIN_DIRS / DEFAULT_CUBEMX_ROOTS、discoverBinDirs / discoverCubeMxRoots(含 msys64 的 ucrt64/mingw64/clang64 变体)、`decodeRegistryText`(严格 UTF-8 不成就按 GB18030 解,审计 B9)、`readRegistryInstallDirs`、`resolveSearchConfig`(配置 > 显式 > 自动发现)、`searchConfigWarnings`、`describeSearchScope`。 |
239
+ | data/toolchain-config.ts(370) | ~/.dsh-stm32/config.json 的读写。`TOOLCHAIN_CONFIG_VERSION = 1`、`ToolchainConfig{msys64,binDirs,cubeMxRoot,packages}`、`readToolchainConfig`、`writeToolchainConfig(expect)` 与 `updateToolchainConfig`(CAS:写入前比对快照,别人改过就冲突而不是覆盖,审计 A28)、`binDirsFromConfig` / `cubeMxRootsFromConfig`、`describeToolchainConfig`。 |
240
+
241
+ ### 5.3 构建与产物(2 个,543 行)
242
+
243
+ | 模块 | 职责与关键导出 |
244
+ | --- | --- |
245
+ | build.ts(493) | `runBuild(subprocess, request)`:选 preset(`pickConfigurePreset` 优先 Debug)→ `cmake --preset` → `cmake --build` → `findElf`(= `pickElf`:CMakeCache 的 CMAKE_PROJECT_NAME 优先,否则取 mtime 最新的 .elf;`elfCandidates` 列出全部候选,`elfSelectionNote` 在候选多于 1 个时把「选了哪个、其他候选的 mtime」写进 notes)→ 解析内存占用(`parseMemoryUsage`,GNU ld 的 `RAM: 1584 B 20 KB 7.73%` 格式)→ 错误行(`parseBuildErrors`)与警告数(`countWarnings`)→ 按需跑 objcopy 出 hex/bin(`converted`,失败只写 note 不判失败)。辅助导出:`presetDirs`、`detectBuildDir`。 |
246
+ | layout.ts(50) | 生成物的落位约定:`GEN_SRC_DIR = "Src"`、`GEN_INC_DIR = "Inc"`、`PROJECT_SRC_DIR = "Core/Src"`、`PROJECT_INC_DIR = "Core/Inc"`、`mapGeneratedPath(rel)`、`listGeneratedFiles`。CubeMX 无头模式吐在 `.dsh-stm32/gen/Src|Inc`,由这里映射回工程的 Core/。 |
247
+
248
+ ### 5.4 烧录、调试与诊断(9 个,4087 行)
249
+
250
+ | 模块 | 职责与关键导出 |
251
+ | --- | --- |
252
+ | 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
+ | 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(656) | 长会话租约。`DebugSessionManager` 管「一个常驻 openocd + 多次短命 gdb -batch eval」,空闲 90 s、总时长 10 min、turn/end 立刻释放;`releaseProbeFor(reason)` 是别的工具(flash/regs/debug_run)动探针前必须调的一步(审计 B16:先释放再门禁)。三个纯函数是好单测点:`normalizeHexAddress`、`parseGdbPrintedHex`、`parseMarkedWords`(按 `echo ===DSH:<tag>===` 分段对齐,修「中间某个地址读失败导致后面值整体前移」)。 |
255
+ | 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
+ | 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
+ | 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。 |
258
+ | rtt.ts(724) | RTT 日志(C 阶段)。控制块沿用 SEGGER 约定(首 10 字节 `"SEGGER RTT"`、描述符 24 字节),传输交给 openocd 的 `rtt setup/start/server start`,本模块只管帧与状态:`startRtt`(`mdw` 三个字校验魔数 `RTT_MAGIC_WORD_0/1/2_LOW` → 发三条命令 → 起本地端口)/`dumpRtt`(连端口读 N 秒或 M 条 → `parseRttFrames` 解帧 → 按 `level` 上限过滤 → `truncated` / `dropped` 如实报)/`stopRtt` / `rttStatus`(`src/index.ts` 在 turn/end 时调 `stopRtt`)。帧是 13 字节头:4B 长度 LE(= 9 + payload)、1B 级别 1..4、8B 时间戳 ms LE、UTF-8 payload;`len < 9` 或 `> 4096` 判失步并按字节滑动重找,单帧坏掉不炸整次 dump。常量 `DEFAULT_RTT_PORT=9090`、`DEFAULT_RTT_SIZE=0x400`、`DEFAULT_DUMP_SECONDS=3`、`DEFAULT_MAX_RECORDS=200`、`RTT_FRAME_HEADER_BYTES=13`、`RTT_MIN_FRAME_BYTES=9`;八条 hint(地址写错 / 没有会话 / 控制块全 0 / 魔数不符 / 端口占用 / 连不上 / Tcl 超时 / 帧失步)只此一份。 |
259
+ | breakpoints.ts(294) | 断点预算(B4)。`BreakpointBudget{code,data}`、`F1_BREAKPOINT_BUDGET = {code:6, data:4}`、`quotaOf(used, limit)`(used 夹在 [0,limit],给出 used/limit/remaining 三元组)、`budgetFromChipFact`、`readIocCpn`、`resolveBreakpointBudget(projectDir)`(.ioc 的 Mcu.CPN → chips.json 里可选的 breakpoints/watchpoints;没 .ioc、chips.json 没这颗、或没写值都回退 F1 6/4 并说明原因)、`parseBreakpointSpec` / `breakpointFromGdbCommand`、`collectBreakpointRequests({breakAt,breakpoints,preCommands})`(preCommands 里的 break / watch 也计数,同 kind+location 去重)、`planBreakpoints` 出 detail + suggestion。超限在 spawn openocd **之前**就失败,不碰探针、也不关已有会话。 |
260
+ | doctor.ts(665) | 体检 + 配套性核对。`runDoctor`:逐组件探测 + 进程残留(`parseTasklistCsv` 认 openocd/gdb)+ 端口占用(`checkPortBusy`)+ .ioc 告警 + USB 形态(`usbDiagnosis` / `diagnoseUsb`:只认行内 ASCII 本体,因为中文系统的 pnputil 字段名是 GBK 乱码)+ elf/构建目录;最后跑 **checkChipConsistency / collectChipConsistency** 的五项一致性:① 型号 ↔ 启动文件名 ② 启动文件 ↔ cmake 设备宏 ③ `.ld` MEMORY 容量 ↔ 芯片实际容量 ④ `.elf` Flash 占用 ↔ Flash 容量 ⑤ .ioc 用到的引脚是否在封装内。配套纯函数 `parseLinkerMemory`(认 20K / 0x5000 / 65536,算式不算)、`deviceDefinesIn`、`elfFlashBytes`(读 ELF program header,只累加 `p_paddr` 落在 0x08000000 起 1 MiB 的 PT_LOAD 的 `p_filesz`)、`findLinkerScript` / `linkerScriptNames`(多个 .ld 时优先非 STM32F103XX_FLASH.ld 的那个)。 |
261
+
262
+ ### 5.5 生成、编码、.ioc 事务与时钟(10 个,3657 行)
263
+
264
+ | 模块 | 职责与关键导出 |
265
+ | --- | --- |
266
+ | generate.ts(750) | 全仓库最复杂的一个。`STATE_DIR = ".dsh-stm32"`、`findIocFile`(只认「唯一」.ioc)、`detectLayout`(coupled / per-ip)、`runGenerate`:工程锁(`acquireLock`:pid + startedAt + `isProcessAlive` 探活,30 分钟兜底)→ 固件包定位 → 生成 CubeMX 脚本(`-Dfile.encoding=UTF-8`,审计 B18)→ 跑 CubeMX → 解析日志(generate-script.parseGenerateLog,以产物判据为准)→ 把 Src/Inc 搬进 Core/(preserve USER CODE)→ `assessGenerateProducts`(产物判据:applied 数为 0 或关键文件缺失时 ok 不能为真)→ 写 generate-cache → 落位后(以及缓存命中直接返回前)再跑一次 `refreshCubemxCmakeLists`,把 `cmake/stm32cubemx/CMakeLists.txt` 对齐磁盘上的 startup 与 hal_conf。 |
267
+ | generate-script.ts(115) | `buildGenerateScript` 拼脚本(setCustomFWPath / SetCopyLibrary / ProjectManager 项)、`layoutCommand`、`parseGenerateLog`:UNKNOWN_COMMAND 先判;成功行不再「一票否决」错误(审计 A10)——CubeMX 缺包时也会打 Code successfully generated,所以 ok 由产物判据决定。 |
268
+ | generate-cache.ts(168) | 生成缓存。`CACHE_FILE = "generate-cache.json"`、`sha256Text` / `sha256File`、`cubeMxStamp`、`computeCacheKey(iocSha, stamp, layout)`、`readCache` / `writeCache`、`cacheHit(entry, key, projectDir)`(key 命中还不够,文件 hash 也得对得上)。 |
269
+ | usercode-merge.ts(142) | `parseUserCodeRegions` / `mergeUserCode` / `canMergeUserCode`:把旧文件 USER CODE 块里的内容搬进新生成的文件,保留 CRLF 风格,标出 droppedLabels。 |
270
+ | code-patch.ts(215) | `patchUserCode`:只改一个 USER CODE 块(replace / append),块内出现 `{` 或 `}` 拒绝(结构行守卫),写前备份,写回**按字节拼接**(见 text-file)。`listUserCodeLabels` 列出可用标签。 |
271
+ | text-file.ts(172) | 编码层。`detectEncoding`(BOM → utf8-bom;空 → utf8;严格 UTF-8 成 → utf8;再试 gb18030;否则 unknown)、`decodeText`、`encodeText`(gb18030 只允许纯 ASCII——Node 只有解码器没有编码器)、`readTextFile`、`lineStarts`、`replaceLineRange`(未改的行原字节照抄,只把新增行按原编码插入)。**这是「中文注释不被写坏」的唯一保障**。 |
272
+ | ioc.ts(202) | .ioc 只读解析:`parseIocEntries`、`decodeIocValue`、`summarizeIoc`(MCU、时钟树、引脚、外设、调试口、工程设置、警告)。 |
273
+ | ioc-plan.ts(612) | .ioc 事务。`planIocChanges` 算出逐键 diff + 源 SHA-256 → planId;`applyIocPlan` 校验 SHA 后原子替换(备份到 backups/<stamp>-ioc);`rollbackIoc(backupFrom)` 回滚;辅助 `renderIocText`、`compareEntries`、`sha256Hex`、`encodeIocValue`、`loadPlan`。引脚写入保序(审计 A3):只追加新增,不因缺 .Signal 删已有项。 |
274
+ | clock-plan.ts(801) | 时钟规划(t3 新增)。`planClockChanges`:枚举 PLL 源 × 倍频 × 分频的全部可行组合 → 取 `|sysclk − target|` 最小(同距取更高档,所以 60 MHz 的目标落在 64 MHz,报告里写「不可达,已选 64 MHz(+4 MHz)」)→ 与 .ioc 现有键做 diff,`PLLMUL`、`SYSCLKFreq_VALUE`、`HCLKFrequency`、`APB1/APB2Prescaler` 这些派生键**全量重算**(只改源键会让 CubeMX 按旧频率理解)→ 再给逐外设频率表与 UART 波特率整除误差。`mode` 四态:`snapshot`(只看不写)/ `nearest`(默认就近)/ `explicit`(钉死 pllMul)/ `none`。超限(SYSCLK >72、APB1 >36、ADC >14)时**一个键都不写**,只报错。参数化在 src/data/clock-f1.ts。 |
275
+ | cmake-sources.ts(480) | **老洞的补丁**:CubeMX 无头生成从不重写 `cmake/stm32cubemx/CMakeLists.txt`,那份源清单永远停在脚手架快照上。`collectCmakeSources` 从磁盘反推真相(`pickStartupFile` 选启动文件 → `deviceDefineFromStartup` 得 `STM32F103xB` → `familyTokensFromStartup` 得家族目录 `STM32F1xx` → `halModulesInUse` 由 `stm32f1xx_hal_conf.h` 的 `HAL_xxx_MODULE_ENABLED`(先 `stripComments`,注释掉的不算)∪ `Core/Src` 源码里的 `#include "stm32f1xx_hal_x.h"` 求并集),`refreshCubemxCmakeLists` 只重写三个 managed 块(设备宏 / 应用清单 / 驱动清单),保留原顺序、摘掉磁盘上已不存在的条目、缺的追加到末尾;`dominantEol` 按多数行尾写回、内容一致时一个字节都不写;`describeRefresh` 生成一句人话进 generate 的 notes。 |
276
+
277
+ ### 5.6 造工程、链接脚本与导出(8 个,2224 行)
278
+
279
+ | 模块 | 职责与关键导出 |
280
+ | --- | --- |
281
+ | scaffold.ts(518) | HAL 路线脚手架。`preflightTarget`(工程名合法 → 目录非空 → hal 且已有同名 .ioc 就拒绝,指向 ioc_plan/apply)、`backupBeforeOverwrite` + `backupWarning`(只备份真会被覆盖的文件)、`mkdirTracked` / `cleanupAfterFailure`(失败只回收本次新建)、`resolveFirmwareRoot`(Repository → dsh-firmware → extraDirs)、`createProjectScaffold`、`templateDir`、常量 `DEFAULT_FIRMWARE_PACKAGE` / `SCAFFOLD_PROJECT_NAME`。复制走 fs-longpath。型号相关的启动文件、设备宏、`<DeviceId>_FLASH.ld` 与 demo.ioc 由 hal-chip 在**写盘之前**渲染成字符串,渲染失败时一个字节都不写。 |
282
+ | hal-chip.ts(284) | HAL 路线的「型号 → 生成物」派生与纯文本渲染(t1 新增)。`resolveHalChip(input)` 复用 F1Chip,`renderStartupAndDefine`(RCT6 → startup_stm32f103xe.s + STM32F103xE)、`renderLinkerScript`(把 STM32F103XX_FLASH.ld 的 MEMORY 两行与注释两行换成 `<DeviceId>_FLASH.ld`,RCT6 是 256 KiB / 48 KiB)、`renderIoc`(demo.ioc 的 Mcu.CPN、引脚、时钟键)、`pointLinkerFlagAt`(把工具链文件里写死的 `-T STM32F103XX_FLASH.ld` 改指新名,否则命令行上会出现两个 -T)。全是字符串函数,所以能先渲染后落盘。 |
283
+ | register-template.ts(584) | 寄存器路线(不碰 CubeMX)。`resolveStartupChoice`(按型号/族选启动文件与宏)、`ensureCmsisTemplate`(从镜像下载 10 个文件到缓存并校验 sha256)、`createRegisterProject`(拷模板 → 写设备头/启动文件/链接脚本 → 生成 main.c)。模板文件缺失分「必需」与「可选」(.gitignore 是可选,缺了给 warning 不阻断)。模板里已不写死任何型号:启动文件、设备宏、设备头、`.ld`、时钟全部按 `resolveF1Chip` 的结果参数化(14 个容量档)。 |
284
+ | register-clock.ts(261) | 寄存器版的时钟初始化代码生成(不碰 CubeMX)。按 line 取最高 SYSCLK:F100 24 / F101 36 / F102 48 / F103·F105·F107 72 MHz;HSE 8 MHz ×N(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 跟着对。 |
285
+ | register-linker.ts(152) | 寄存器版的链接脚本渲染:按型号换掉 `<DeviceId>_FLASH.ld` 的 MEMORY RAM/FLASH 两行。F100/F101/F102 的 RAM 不在 src/data/stm32f1.ts 的表里,用 CubeMX db 的最小值兜底**并明确警告**(宁可小——栈必须留在真 RAM 内)。 |
286
+ | vscode-config.ts(118) | `VSCODE_PLACEHOLDERS`(gdb / toolchain / cmake / svd 四个占位符)、`detectVscodeFill`(按本机探测结果填)、`fillVscodeTemplate`(没值的整行删掉并记 dropped,绝不写空串)、`describeDroppedPlaceholder`。模板里因此不出现任何开发机绝对路径(审计 B1)。 |
287
+ | project-export.ts(155) | `runExport`:收集源文件(跳过 build / .dsh-stm32 / node_modules / .git)→ 可选带 prebuilt(elf/hex/bin)→ 可选内联 README → 打 zip。 |
288
+ | zip.ts(152) | 自写的最小 store-only zip(不压缩、不引依赖):`crc32`、`makeZip`、`listZipEntries`(测试用来验内容)。 |
289
+
290
+ ### 5.7 下载、缓存与固件包(7 个,2502 行)
291
+
292
+ | 模块 | 职责与关键导出 |
293
+ | --- | --- |
294
+ | fetch.ts(347) | `fetchOne(target, destRoot, options)`:按 URL 列表依次尝试 → 校验内容特征(markers)→ 校验 sha256(有声明时)→ 落到目标路径;`fetchAll` 汇总。失败信息带「期望 / 实际」两个哈希,方便判断是上游挪了内容。**同一源内断点续传**(F3c):`streamOnce(url, part, startAt, …)` 用 `Range: bytes=N-` 流式写 `.part-<pid>-<seq>`,watchdog 在 `stallMs`(默认 10 s)内判停滞或平均速率 < `minBytesPerSec`(默认 1024)就 abort,返回 `slow: true` 让 `fetchOne` 从已落盘字节续一次;服务器回 200(无视 Range)时截断重写,只有 206 才追加——**换源一律从零开始**(不同源的字节不保证同一份)。**校验失败必须连 `.part` 一起删**(T1 实测抓到的泄漏):体量 / 网页 / markers / sha256 四道都不通过时走局部 `reject(reason)`——它把失败原因记进 `attempts` 再 `removeQuietly(part)`,否则半成品会长期躺在缓存目录里等着占满磁盘。 |
295
+ | cache.ts(416) | 缓存索引(默认 %LOCALAPPDATA%\dsh-stm32\cache,可用 DSH_STM32_CACHE 覆盖)。`CACHE_INDEX_VERSION`、`readCacheIndex` / `writeCacheIndex`(坏索引先改名 index.json.broken-<ts>;tmp 唯一名 + rename 失败先备份旧索引再重试;`CacheIndexWriteError` 让上层知道是索引写坏了,审计 A2/A12)、`upsertCacheEntry` / `removeCacheEntry` / `findCacheEntry`、`checkCacheEntry`(按 sha256 验证,审计 A38)、`sha256OfFile`、`describeCacheBytes`。 |
296
+ | tar.ts(288) | `extractTarGz(archive, destRoot, options)`:解 gzip + tar,路径白名单(`isSafeRelative` 拒反斜杠、冒号、.. 与空段)、类型白名单(`entryKind`:0/空/5 正常,x/g/L/K 元数据,其余跳过并记名,审计 A4)、声明长度超出实际数据判截断整次失败。 |
297
+ | firmware-install.ts(760) | 固件包下载与组装。`firmwareInstallPlan` / `installFirmware` / `planOrInstallFirmware`:选址(`isProtectedSystemDir` 拒绝 Program Files 之类、`orderCubeMxRoots` 把本机存在的排前面、`hasCubeMxExe` 只对真 CubeMX 目录建 dsh-firmware)→ 下载 2 个归档 + 5 个内核头 → `extractTarGz` → `verifyFirmwarePackage` → 写 `installed.json` 记录(`FIRMWARE_RECORD_FILE`)→ `firmwareExtraDirs` 让 generate/scaffold 也能找到非标准落点。 |
298
+ | thirdparty.ts(281) | 生成期间临时停放 CubeMX 的第三方包索引(`PARKED_NAME = "pdsc.dsh-parked"`、`needsThirdpartyPacks`、`parkThirdpartyDb`),有 X-CUBE 包的工程保持原样;`cubeMxUserHome`。 |
299
+ | xcube.ts(293) | X-CUBE 包识别:`identifyPackId`、`parsePdscNames`、`listInstalledPacks`、`scanIocPacks`、`summarizePacks`。 |
300
+ | xcube-catalog.ts(117) | 由 scripts/gen-xcube-catalog.mjs 生成的包目录(159 条)。`XCUBE_CATALOG_ENTRY_COUNT = XCUBE_PACK_CATALOG.length`(审计 A23:不要把条目数写成数字常量,重跑脚本会回写旧值)。 |
301
+
302
+ ### 5.8 工具链安装(1 个,2313 行)
303
+
304
+ | 模块 | 职责与关键导出 |
305
+ | --- | --- |
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)`(**F3a 候选链**:`MSYS2_INSTALLER_URL` 单源 > `MSYS2_MIRROR` > 清华 TUNA / 中科大 USTC / 南大 NJU / 阿里云 × 两个文件名 > GitHub,共 10 个候选;`installerSourceLabel` 把 URL 变成「清华 TUNA」这样的人话)、`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、一句话收尾)。**F3d 三道粗检**:缓存要 MZ 头 + ≥ `MIN_INSTALLER_BYTES`(40 MB)才算数(`cachedInstallerBytes`);下载后查退出码/体量/MZ;解压后再查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删)。**F3c**:`curl -C -` 同源续传、`--speed-limit 1024 --speed-time 10` 低速自退(退出码 28 单独说明),退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次,换源前删 `.part`。 |
307
+
308
+ ### 5.9 设置面板的宿主侧(2 个,577 行)
309
+
310
+ | 模块 | 职责与关键导出 |
311
+ | --- | --- |
312
+ | web-api.ts(477) | 六条路由的**纯逻辑**(不碰 http 对象,所以可单测)。`WEB_API_PREFIX = "/dsh-stm32/api"`、`WEB_API_PATHS`(/config、/config/save、/probe、/install/plan、/install/start、/install/state)、`configSnapshot`、`saveConfig`、`probeTools` / `summarizeProbe` / `capabilitiesOf`、`installPlan`、`installStart` / `installTaskState`(进程内任务表,留 20 个,日志尾巴 200 行)、`handleWebApi`(分发 + 请求体 JSON 校验,1 MB 上限在 web-routes)、`resetInstallTasks`。 |
313
+ | web-routes.ts(100) | 薄适配层:`ctx.inject(["webServer"], ...)` 里 `server.register({ kind: "exact", path, handler })`,把 request/response 收成 `handleWebApi` 的输入输出,加 `cache-control: no-store`。宿主没 webServer 服务时静默跳过(面板不可用,工具照常)。 |
314
+
315
+ ### 5.10 路线评估(1 个,645 行)
316
+
317
+ | 模块 | 职责与关键导出 |
318
+ | --- | --- |
319
+ | route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
320
+
321
+ ## 6. data 层:10 个数据模块(3599 行;芯片事实来自资源包缓存,仓库里没有芯片表)
322
+
323
+ | 模块 | 行数 | 内容 |
324
+ | --- | --- | --- |
325
+ | 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
+ | 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 refresh`」提示:没缓存 / 型号不在资源包 / line 不存在 / 该 line 没有这一容量档。 |
328
+ | 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`(目前只有 F1)、`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
+ | install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
331
+ | search-roots.ts | 421 | 见 5.2。 |
332
+ | toolchain-config.ts | 370 | 见 5.2。 |
333
+ | device-facts.ts | 278 | 设备事实读取层(新增):从 `~/.dsh-stm32/assets/<版本>/device/f1/chips.json` 读(`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 refresh,或检查网络」原样交给上层。 |
334
+ | svd.ts | 837 | SVD 寄存器表(新增,D 阶段):读 `device/f1/svd/<line>.json`(`profile=full`)。常量 `SVD_REL_DIR`、`SVD_KNOWN_LINES`(100/101/102/103/105/107)、`SVD_FULL_PROFILE_HINT`(一句能照敲的 `stm32_assets refresh --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)。兼容「装好的 `<root>/<version>/`」与「直接指向资源仓库本体的 flat」两种布局,缓存键 path+size+mtimeMs,`svdCacheStats` / `resetSvdCache` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
335
+
336
+ ## 7. 关键流程
337
+
338
+ 这一章是全书重点:每个流程都给「一张图 + 几个必须知道的失败面」。看图时对照第 5 章的模块表找文件。
339
+
340
+ ### 7.1 一次工具调用的通用管线
341
+
342
+ ```mermaid
343
+ sequenceDiagram
344
+ participant U as 模型/用户
345
+ participant H as DSH 宿主
346
+ participant T as src/tools/x.ts
347
+ participant E as src/engine
348
+ participant S as 宿主 subprocess
349
+ participant B as gcc/cmake/openocd/CubeMX
350
+ U->>H: 调工具 + JSON 参数
351
+ H->>T: execute(args, exec)
352
+ T->>T: resolveProjectDir + validateToolArgs
353
+ T->>E: ensureToolchain(capability, envCheck)
354
+ E-->>T: GateResult{ok, missing[], install[]}
355
+ alt 门禁拦截
356
+ T-->>H: blockedReport 同形报告
357
+ else 门禁通过
358
+ T->>E: run*(subprocess, request)
359
+ E->>S: spawn{argv, cwd, env, stdio.maxBytes}
360
+ S->>B: 真进程
361
+ B-->>S: stdout/stderr + exitCode
362
+ S-->>E: RunOutcome
363
+ E-->>T: Report
364
+ T->>T: render(report) → 中文行
365
+ T-->>H: report(必须过 output.schema)
366
+ end
367
+ ```
368
+
369
+ 必须知道的失败面:
370
+ - **输出 schema 是硬约束**:report 多一个没声明的字段,宿主就判「非法输出」。改 report 必改 schema,并用 test/schema-guard.mjs 兜住。
371
+ - **exec.signal 一路要透传**:工具超时/用户取消 → spawn 被 abort → RunOutcome.aborted=true → report 里写「已取消」。任何一格没接 signal,取消就变成「等 30 秒超时」。
372
+ - **门禁在工具层**:engine 不知道门禁存在,所以 engine 的返回永远按「工具链就位」写文案。
373
+
374
+ ### 7.2 工具链门禁:快路径、慢路径与缓存
375
+
376
+ ```mermaid
377
+ flowchart TD
378
+ A["ensureToolchain(capability, envCheck)"] --> B{"envCheck = off?"}
379
+ B -->|是| PASS["ok=true 直接放行"]
380
+ B -->|否| C["CAPABILITY_COMPONENTS 列必需组件"]
381
+ C --> D{"快路径:binDirs 里文件都在?"}
382
+ D -->|是| E["smokeTarget:跑一次主组件的版本命令<br/>build→gcc flash→openocd debug→gdb generate→cubemx-java<br/>60 s 缓存"]
383
+ E -->|跑通| PASS
384
+ E -->|失败| F["按缺件处理,error 写「文件在但版本命令没跑通」"]
385
+ D -->|否| G["慢路径:probeAll 全量探测<br/>allowPathFallback 默认开"]
386
+ G --> H{"signal.aborted?"}
387
+ H -->|是| I["break:不写缓存(审计 A27)"]
388
+ H -->|否| J["probeCache.set(key, {at, results}) 60 s"]
389
+ J --> K{"有缺件?"}
390
+ F --> K
391
+ K -->|无| PASS
392
+ K -->|有| L{"envCheck = warn?"}
393
+ L -->|是| M["ok=true + warnings 一行"]
394
+ L -->|否| N["ok=false + missing[](含 hint/impact/install/verify)"]
395
+ ```
396
+
397
+ 为什么快路径也要跑版本命令(审计 B13):「文件存在」不等于「文件能跑」——半截下载、被杀软隔离、架构不对、0 字节,都表现为文件在而进程起不来。只对**主组件**做 smoke,是为了保住快路径「零全量 spawn」的价值;其余组件坏了慢路径照样兜住。
398
+
399
+ ### 7.3 project_create:两条完全不同的路线
400
+
401
+ ```mermaid
402
+ flowchart TD
403
+ A["stm32_project_create{targetDir, projectName, route}"] --> P["preflightTarget:<br/>1 工程名是 C 标识符<br/>2 目录非空 → 拒绝<br/>3 hal 且已有同名 .ioc → 拒绝并指向 ioc_plan/apply"]
404
+ P --> R{"route?"}
405
+ R -->|register| S1["ensureCmsisTemplate:<br/>按型号选启动文件 → 下载 10 个文件 → sha256 校验 → 落缓存"]
406
+ S1 --> S2["createRegisterProject:<br/>拷模板 7 件(含 .gitignore、openocd.cfg、链接脚本)<br/>写设备头/启动文件/system.c/main.c"]
407
+ S2 --> S3["模板缺失分流:必需 → 一次列全并拒绝<br/>可选(.gitignore) → warning 继续"]
408
+ R -->|hal| H1["resolveFirmwareRoot:Repository → dsh-firmware → extraDirs<br/>找不到就带安装指引失败"]
409
+ H1 --> H2["backupBeforeOverwrite:只备份真会被覆盖的文件<br/>备份失败 → 一字不写"]
410
+ H2 --> H3["createProjectScaffold:拷 15 个模板 + 从固件包拷 Drivers/238 件<br/>复制走 fs-longpath"]
411
+ H3 --> H4["写 .vscode/:按本机探测填占位符,没值的整行删掉并记 warning"]
412
+ S3 --> DONE["报告:templateFiles / driverFiles / firmwareRoot / warnings"]
413
+ H4 --> DONE
414
+ DONE --> FAIL{"中途失败?"}
415
+ FAIL -->|是| CL["cleanupAfterFailure:只回收本次新建<br/>原有目录只 rmdir 空目录"]
416
+ ```
417
+
418
+ 两条路线的共同点只有「先预检、再备份、失败回收」。区别是 hal 依赖 CubeMX 固件包(无网也能用整目录拷贝),register 依赖网络下载 CMSIS(但缓存命中后完全离线)。
419
+
420
+ ### 7.4 build:preset → 编译 → 产物
421
+
422
+ ```mermaid
423
+ flowchart LR
424
+ A["runBuild"] --> B["pickConfigurePreset<br/>优先 Debug"]
425
+ B --> C["cmake --preset=<name><br/>env 注入 binDirs + 原 PATH"]
426
+ C --> D["cmake --build --preset=<name>"]
427
+ D --> E["findElf → pickElf:CMakeCache 工程名优先<br/>否则取 mtime 最新的 .elf;elfSelectionNote 进 notes"]
428
+ E --> F["parseMemoryUsage / parseBuildErrors / countWarnings"]
429
+ F --> G{"artifacts 里要 hex/bin?"}
430
+ G -->|是| H["arm-none-eabi-objcopy -O ihex / binary<br/>失败只写 note,不判 build 失败"]
431
+ G -->|否| I["报告"]
432
+ H --> I
433
+ ```
434
+
435
+ 选哪个 .elf 是 0.1.2 修的坑:老的 findElf 取 readdir 的第一个,Debug 目录里积了多个 elf(改过工程名、重建过、复制过 build/)时会挑到旧的——烧进去的固件和源码不一致,却什么都不报。现在 `pickElf` 先读 CMakeCache 的 `CMAKE_PROJECT_NAME`(buildDir 目录名是 Debug,与 Debug.elf 永不相等,这条老逻辑不再被依赖),取不到再退化为 mtime 最新;候选多于 1 个时 `elfSelectionNote` 把「选了哪个 + 其余候选的 mtime」写进报告 notes,flash / debug_run / build 都会带这条说明。
436
+
437
+ 坑:**复制过的工程**(CMakeCache 里记着别的路径)会报奇怪的错,build.ts 里有显式拦截:检测到 CMakeCache 的源目录与当前工程不一致就直接给「把 build/ 删掉重配」。
438
+
439
+ ### 7.5 flash:守卫 → 烧录 → 判定 → 错误分类
440
+
441
+ ```mermaid
442
+ flowchart TD
443
+ A["stm32_flash"] --> B["releaseProbeFor:先还探针(审计 B16)"]
444
+ B --> C["checkNoDebugGuard(projectDir, allowNoDebug, iocPath)"]
445
+ C --> C1{"有唯一 .ioc?"}
446
+ C1 -->|有| C2["PA13=SYS_JTMS-SWDIO / PA14=SYS_JTCK-SWCLK / Mode=Serial_Wire?"]
447
+ C1 -->|没有或多个| C3["看 openocd.cfg 的 transport:swd 放行并说明依据<br/>jtag 提示引脚复用<br/>都没有 → notes 两条「守卫没生效」"]
448
+ C2 -->|是 No_Debug| BLOCK["blocked:拒绝,除非 allowNoDebug"]
449
+ C2 -->|是 Serial Wire| D["resolveElf(内部 findElf → pickElf,notes 说明选中的是哪个)"]
450
+ C3 --> D
451
+ D --> E["findProjectConfig:openocd.cfg 优先<br/>否则 interface/cmsis-dap.cfg + target/stm32f1x.cfg"]
452
+ E --> F["openocd -f ... -c program <elf> verify reset exit"]
453
+ F --> G["parseFlashLog:认 Programming Finished / Verified OK<br/>成功序列里的偶发 Error 行进 noise"]
454
+ G --> H{"ok?"}
455
+ H -->|是| OK["programmed + verified,probeError 缺省(成功时字段根本不出现)"]
456
+ H -->|否| I["classifyProbeFailure 分 8 类:no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / timeout / unknown"]
457
+ I --> J["notes:USB 形态(usbNoteFor)+ probe-busy 专用提示(HINT_BUSY)"]
458
+ ```
459
+
460
+ 真板子取证过的一个细节:两个进程同时访问同一个 CMSIS-DAP 时,日志不是「设备忙」,而是交替出现 CMSIS-DAP command mismatch / transfer count mismatch / Failed to write memory at 0x00000004。所以 probe-error.ts 的 MATCHERS 里专门把这几种行归到 probe-busy(`/cmsis-dap (transfer count mismatch|command mismatch)|cmsis-dap command cmd_\w+ failed|libusb_error_busy/`)。
461
+
462
+ ### 7.6 调试三件套与会话租约
463
+
464
+ ```mermaid
465
+ stateDiagram-v2
466
+ [*] --> 空闲
467
+ 空闲 --> 启动中: stm32_debug_session(start)
468
+ 启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
469
+ 启动中 --> 空闲: 端口占用 / 探针失败、带 probeError(kind / cause / hint)
470
+ 活跃 --> 活跃: stm32_debug_eval、每次新起 gdb -batch:连上 → halt → 命令 → resume → detach
471
+ 活跃 --> 空闲: stm32_debug_stop
472
+ 活跃 --> 空闲: 空闲 90 s
473
+ 活跃 --> 空闲: 总时长 10 min
474
+ 活跃 --> 空闲: turn/end、本轮输出结束
475
+ 活跃 --> 空闲: session/disposed / 插件 dispose
476
+ ```
477
+
478
+ 三条设计理由:
479
+ 1. **只有 openocd 常驻**,gdb 每次短命——gdb 崩了不会把会话带死,也避免 gdb 自己攒一堆状态。
480
+ 2. **归属(A9)**:turn/end 事件里尽量掏 agent id,只关这条会话自己开的;掏不到就全关(宁可按最短释放,也不攥着探针)。
481
+ 3. **别人要用探针先 releaseProbeFor**:flash / debug_run 在自己起 openocd 之前调它,否则就是「两个 openocd 抢一个 CMSIS-DAP」。**regs_read 是例外(B3 起)**:它反过来复用会话里的那个 openocd,连读时不再一读一起一停。
482
+
483
+ B3 的快路径不是「gdb -batch 跑快一点」,而是绕开 gdb:会话里 openocd 的 Tcl RPC 端口(`debug-session.ts` 的 `parseListeningPorts` 从启动日志的 `Listening on` 行取,`TCL_PORT_SETTLE_MS = 120` 后拿完整缓冲再解析一次,存进 `session.tclPort`;`probe-session.ts` 只消费它)上一条 TCP 连接依次发 halt → `reg pc` → `mdw`×N → resume,帧用 0x1a 分隔(`readWordsViaSession`)。假探针实测:旧的一次性路径 1493 ms/次;新路径起会话 790 ms(第一次含启动),之后 10 连读单次 13–18 ms、总计 154 ms,openocd 进程数 1。没有 tcl 端口或 RPC 失败就回退到会话里的 gdb 并把原因写进 notes。**真机计时还欠着**:现插的 WCH-Link(VID_C251&PID_F001)openocd 0.12 init 直接报 `Error: CMSIS-DAP command CMD_INFO failed`,换回 CMSIS-DAP 探针后跑 `stm32_regs_read` 连读 10 次 0x4001100C 即可复测。
484
+
485
+ B4 的断点预算在同一条 execute 里先算(`resolveBreakpointBudget` 读 .ioc 的 Mcu.CPN → chips.json 的 breakpoints/watchpoints,缺就按 F1 默认 6 硬件断点 / 4 观察点并说明原因),超限在 spawn openocd **之前**就失败——不占探针、也不关你正开着的会话;报告里 `breakpoints` / `watchpoints` 各是 `{used, limit, remaining}`。
486
+
487
+ **debug_run 失败时说什么**(0.1.2 修复):以前只回一句「openocd 起不来」外加日志最后 15 行,真正的原因(adapter init 失败、探针被占)常被后面的噪声挤掉。现在改成和 flash **同一个函数** `classifyProbeFailure`(stage "debug",同一组 kind)归类,hint 也从 probe-error.ts 那一份来,`probeMissingLines` 命中时顺手跑 `usbDiagnosis` 分清「没插 / 没认到 / 驱动异常」,日志改用 `keyLogTail` 挑有信息量的行,`firstProblemLine` 把首条根因写进 errors,kind 不是 unknown 时把 hint 也塞进 notes。
488
+
489
+ 报告里的 `probeError` 是**结构化对象**(`kind` / `cause` / `hint` / `evidence` / `retryable`),由 `PROBE_ERROR_SCHEMA` 声明(additionalProperties:false、五个字段 required)。注意一个宿主层细节:引擎在成功路径上给的是 `null`,而宿主 schema 不接受 null——所以 tools/flash.ts 与 tools/debug.ts 最后都过一遍 `flashReportForHost` / `debugReportForHost`,把 null 摘掉,让「成功时字段不出现」这件事真的成立。漏这一步就会重演 flash 那次「失败路径被判非法输出」。
490
+
491
+ ### 7.7 .ioc 事务:plan → 用户确认 → apply / rollback
492
+
493
+ ```mermaid
494
+ sequenceDiagram
495
+ participant M as 模型
496
+ participant P as stm32_ioc_plan
497
+ participant A as stm32_ioc_apply
498
+ participant F as demo.ioc
499
+ M->>P: entries / unset / pins / serialWire
500
+ P->>F: 只读解析 + 逐键 diff
501
+ P-->>M: planId + sourceSha256 + changes[](不写盘)
502
+ M->>M: 决定要不要动(用户确认)
503
+ M->>A: {planId}
504
+ A->>F: 重新算 SHA-256 并比对
505
+ alt SHA 变了
506
+ A-->>M: 拒绝:源文件已被改过,重新 plan
507
+ else SHA 一致
508
+ A->>F: 备份到 .dsh-stm32/backups/<stamp>-ioc
509
+ A->>F: 原子替换(写 tmp → rename)
510
+ A-->>M: appliedChanges + backupPath
511
+ end
512
+ M->>A: {rollbackFrom: backupPath}
513
+ A->>F: 先备份当前内容,再写回备份
514
+ A-->>M: rolledBack=true
515
+ ```
516
+
517
+ .ioc 是唯一的「配置真相」,所以它有三重保护:**不写盘的计划阶段**、**SHA 校验**、**每次写前都备份**。引脚写入保序(审计 A3)也是为这条服务的:无意义的顺序抖动会让 diff 看起来像改了很多东西。
518
+
519
+ ### 7.8 generate:CubeMX 无头模式的全流程
520
+
521
+ ```mermaid
522
+ flowchart TD
523
+ A["runGenerate"] --> B["findIocFile:只认唯一 .ioc"]
524
+ B --> C["acquireLock:lock.json{pid, startedAt, purpose}<br/>isProcessAlive 探活,30 min 兜底"]
525
+ C --> D["固件包定位:Repository → dsh-firmware → extraDirs<br/>同时算出 firmwareSource"]
526
+ D --> E["detectLayout:coupled / per-ip"]
527
+ E --> F["cacheKey = sha256(.ioc) + cubeMxStamp(java,jar) + layout"]
528
+ F --> G{"缓存命中且文件 hash 全对?"}
529
+ G -->|是| Z["直接复用上次产物(skipped=true)"]
530
+ G -->|否| H["thirdparty:无 X-CUBE 包时临时停放 pdsc 索引(省约 25 s)"]
531
+ H --> I["写 CubeMX 脚本到 .dsh-stm32/tmp/gen-<stamp>.txt<br/>-Dfile.encoding=UTF-8 + setCustomFWPath"]
532
+ I --> J["java -jar STM32CubeMX.exe -q <script>"]
533
+ J --> K["parseGenerateLog:UNKNOWN_COMMAND → commandErrors<br/>成功行不再一票否决错误"]
534
+ K --> L["恢复 pdsc 索引(finally)"]
535
+ L --> M["搬产物:.dsh-stm32/gen/Src|Inc → Core/Src|Inc<br/>旧文件先读编码 → 认不出就 skipped-encoding<br/>能读就 mergeUserCode 保 USER CODE"]
536
+ M --> N["assessGenerateProducts:产物判据决定 ok<br/>(CubeMX 缺包时也会打 successfully generated)"]
537
+ N --> O["写 generate-cache(key + 每个文件 sha256)"]
538
+ O --> P["refreshCubemxCmakeLists:源清单跟着 startup / hal_conf 走<br/>设备宏、startup、HAL 模块清单三块;内容没变不写盘"]
539
+ Z --> P2["缓存命中分支同样调一次 refresh"]
540
+ P --> R["releaseLock(rm lock.json)"]
541
+ P2 --> R
542
+ ```
543
+
544
+ 四个坑:
545
+ - **源清单不会自己长**:CubeMX 只重写 `Core/` 下的代码,`cmake/stm32cubemx/CMakeLists.txt` 它一个字都不碰。`.ioc` 里新开 USART1 后 `hal_conf.h` 会有 `HAL_UART_MODULE_ENABLED`,但清单里没有 `stm32f1xx_hal_uart.c` → 编译通过、链接报 `undefined reference to HAL_UART_Init`。所以 generate 落位之后(以及缓存命中直接返回之前)都必须跑一次 `refreshCubemxCmakeLists`(docs/development-notes.md §26,带真工具链差分验证)。
546
+ - **锁的探活**:早期只看 pid+时间,进程崩了要等 30 分钟;现在先 isProcessAlive(pid),死了立刻接管(审计 A14)。
547
+ - **成功日志不等于成功**:CubeMX 缺固件包/包版本不认时也打 Code successfully generated,所以 ok 必须有产物判据(审计 A10)。
548
+ - **中文路径**:脚本按 UTF-8 写且启动 java 时指定 -Dfile.encoding=UTF-8(审计 B18);否则中文工程路径在脚本里变乱码。
549
+
550
+ ### 7.9 code_patch:只改块内,按字节写回
551
+
552
+ ```mermaid
553
+ flowchart TD
554
+ A["patchUserCode{file, block, code, mode}"] --> B["读成 Buffer(不按 utf8 直读)"]
555
+ B --> C["detectEncoding:BOM/严格 UTF-8/GB18030<br/>unknown → 拒绝,一个字节都不动"]
556
+ C --> D["定位块:正则认 USER CODE BEGIN/END 标记"]
557
+ D --> E{"块内含 { 或 }?"}
558
+ E -->|是| X["拒绝:那是结构行,不许塞代码"]
559
+ E -->|否| F["lineStarts 算出块的起止行"]
560
+ F --> G["replaceLineRange:未改的行原字节照抄<br/>只把新增行按原编码插入,保留 CRLF/LF"]
561
+ G --> H{"结果与原文相同?"}
562
+ H -->|是| Y["回一句「内容没有变化」"]
563
+ H -->|否| I["备份到 .dsh-stm32/backups/<stamp>-patch"]
564
+ I --> J["写 tmp → rename(原子)"]
565
+ ```
566
+
567
+ 为什么要字节级拼接而不是「读成字符串再写回」:GB18030 的文件 Node 能解不能编,整份重新编码会把用户的中文注释写成问号。现在的策略是「动的只有块内那几行,其余字节原样搬运」。
568
+
569
+ ### 7.10 firmware_install:选址、下载、组装、记录
570
+
571
+ ```mermaid
572
+ flowchart TD
573
+ A["firmwarePlanFor{family, mcu, version}"] --> B["选址 decideTarget:<br/>已有包? → existing<br/>CubeMX 目录可用? → <root>/dsh-firmware<br/>否则 cache/custom"]
574
+ B --> C{"受保护目录?<br/>Program Files / ProgramData / SystemRoot"}
575
+ C -->|是| X["判不可写,给下一步建议"]
576
+ C -->|否| D["download:2 个归档 + 5 个内核头<br/>每个都过 sha256"]
577
+ D --> E["extractTarGz:路径白名单 + 类型白名单 + 截断检测"]
578
+ E --> F["补 package.xml(版本 tag)"]
579
+ F --> G["verifyFirmwarePackage:Drivers/CMSIS、startup、hal 源都在?"]
580
+ G --> H["写 installed.json 记录(targetDir + 版本 + 时间)"]
581
+ H --> I["nextStep:告诉用户接下来 stm32_project_create 还是 stm32_generate"]
582
+ ```
583
+
584
+ 为什么装到 <CubeMX>/dsh-firmware 而不是塞进官方 Repository:CubeMX 会静默忽略自造版本号的包;真正生效的是生成脚本里的 project setCustomFWPath。所以「包放哪」和「CubeMX 认不认」是两件事——这一点写在 docs/development-notes.md §14.1。
585
+
586
+ ### 7.11 env_install 的计划模式:只报缺件
587
+
588
+ ```mermaid
589
+ flowchart TD
590
+ A["stm32_env_install{mode=plan}"] --> B["isMsys2Root(msys64):有 usr/bin/bash.exe 且 pacman 在?"]
591
+ B -->|是| C["只读问 pacman:pacman -Q <5 个包><br/>超时 60 s,问不出来就不编清单"]
592
+ B -->|否| D["按全新安装估算(43.1 MB 下载)"]
593
+ C --> E["在目标 binDir 里跑 5 个版本命令<br/>allowPathFallback=false"]
594
+ E --> F{"5 个都跑通?"}
595
+ F -->|是| G["什么都不用装:steps=[]、download.bytes=0、一句话收尾"]
596
+ F -->|否| H["只列缺的包/步骤;已装的不动、也不升级"]
597
+ D --> I["完整 7 步计划:下载 → 解压 → pacman → PATH → 配置 → 自检"]
598
+ ```
599
+
600
+ 两条原则:**计划模式绝不写盘**(只读 pacman query + 只读版本命令),**已经就位的东西不列**(用户明确提过:工具链完整时卡片不该再显示 43.1 MB)。
601
+
602
+ ### 7.12 export:把工程打成 zip
603
+
604
+ ```mermaid
605
+ flowchart LR
606
+ A["runExport{projectDir, outDir, includePrebuilt}"] --> B["collectSources:递归收集<br/>跳过 build / .dsh-stm32 / node_modules / .git"]
607
+ B --> C{"includePrebuilt?"}
608
+ C -->|是| D["带上 elf/hex/bin 到 prebuilt/"]
609
+ C -->|否| E["只要源码"]
610
+ D --> F["readmeText(可选内联 README)"]
611
+ E --> F
612
+ F --> G["makeZip:store-only(不压缩,零依赖)→ <name>-export.zip"]
613
+ ```
614
+
615
+ 为什么 zip 里一定没有 build/:CMakeCache 记着本机的绝对路径,带过去只会在别人机器上报错。所以导出的是「能重新配置的源码」,不是「能直接烧的构建目录」。
616
+
617
+ ### 7.13 设置面板:浏览器 bundle 到宿主 API
618
+
619
+ ```mermaid
620
+ sequenceDiagram
621
+ participant C as client/client.js(浏览器)
622
+ participant S as 宿主 webServer
623
+ participant R as engine/web-routes.ts
624
+ participant A as engine/web-api.ts
625
+ participant E as probe / msys2-install / toolchain-config
626
+ C->>S: GET /dsh-stm32/api/config
627
+ S->>R: handler(request, response)
628
+ R->>A: handleWebApi({method, path, body})
629
+ A->>E: configSnapshot / probeTools / installPlan
630
+ E-->>A: 结果
631
+ A-->>R: {status, body}
632
+ R-->>C: JSON(cache-control: no-store)
633
+ Note over C,A: 安装是长任务:install/start 返回 taskId,前端 setTimeout 递归轮询 install/state
634
+ ```
635
+
636
+ 三个契约:**路由全是 exact**(不抢别的前缀)、**请求体上限 1 MB**、**任务表在进程内**(宿主重启就丢,前端会显示「任务不存在」并允许重新发起)。前端只 require 外壳种子(react / jsx-runtime / primitives),不经打包器,因为宿主以 /plugins/dsh-stm32/client.js 直接提供。
637
+
638
+ ### 7.14 斜杠命令:切词 → 门禁警告 → 调 engine
639
+
640
+ ```mermaid
641
+ flowchart LR
642
+ A["/stm32-flash \"C:/Users/zhang san/proj\" --no-debug"] --> B["tokenizeCommandLine<br/>引号内不切、剥引号、记 quoted"]
643
+ B --> C["parseInvocation:第一个非 flag token = 工程目录"]
644
+ C --> D["commandGateWarning(capability, warn)<br/>缺件只警告不拒绝"]
645
+ D --> E["engine(与工具同一个函数)"]
646
+ E --> F["CommandResult{kind: success|error, text}"]
647
+ ```
648
+
649
+ 命令是「用户手打的快捷方式」,所以它的门禁是 warn:用户可能就想让插件跑起来看看报什么错。工具是「模型调的」,门禁才是 block。
650
+
651
+ ## 8. 不变量与陷阱
652
+
653
+ 这些条目破一条就会出真问题,改代码前先扫一眼。
654
+
655
+ | # | 不变量 | 破了会怎样 | 在哪体现 |
656
+ | --- | --- | --- | --- |
657
+ | 1 | 代码只写在 USER CODE 块内 | 下次生成被无声覆盖,编译还不报错 | skill R1/R2、usercode-merge.ts |
658
+ | 2 | .ioc 只能 plan → apply(带 planId) | 配置被手改后与 CubeMX 理解不一致 | skill R3、ioc-plan.ts |
659
+ | 3 | 不许生成 No_Debug 的 SYS | SWD 永久失联,只能 BOOT0 救 | skill R4、flash.checkNoDebugGuard、ioc.summarizeIoc 警告 |
660
+ | 4 | 覆盖文件前必须备份 | 用户代码丢失 | scaffold.backupBeforeOverwrite、ioc-plan、code-patch |
661
+ | 5 | 编码认不出就拒绝写 | 中文注释变问号 | text-file.detectEncoding、code-patch、generate 的 skipped-encoding |
662
+ | 6 | report 结构必须与 output.schema 一致 | 宿主判「工具返回非法输出」 | 每个 tools/*.ts、test/schema-guard.mjs |
663
+ | 7 | 子进程必须显式 cwd + 注入 env | 新装的工具链找不到 | subprocess-runner.ts、tool-env.ts |
664
+ | 8 | 动探针前先 releaseProbeFor | 两个 openocd 抢一个探针 | flash / regs / debug_run 入口 |
665
+ | 9 | turn/end 必须把探针还回去 | 用户在 VS Code 里按 F5 失败 | src/index.ts |
666
+ | 10 | 取消时不得写缓存 | 取消后仍走「已探测」假象 | toolchain-gate(A27) |
667
+ | 11 | 长路径走 \\?\ 前缀 | 深目录复制 ENAMETOOLONG | fs-longpath.ts |
668
+ | 12 | 解包走路径与类型白名单 | zip-slip / 设备文件写进系统 | tar.ts |
669
+ | 13 | 缓存索引写入可恢复 | 半截索引导致缓存全废 | cache.ts(broken/bak + CacheIndexWriteError) |
670
+ | 14 | 门禁快路径也要 smoke | 「文件在但跑不起来」被判齐全 | toolchain-gate(B13) |
671
+ | 15 | 安装自检不许 PATH 兜底 | 用系统里的旧工具冒充新装 | probe 的 allowPathFallback=false |
672
+ | 16 | 计划模式绝不写盘 | 用户以为只是看一眼,结果被改了 | msys2-install / firmware-install 的 plan 分支 |
673
+ | 17 | 模板里不许出现开发机绝对路径 | 新工程 F5 直接失败 + 泄露用户名 | vscode-config.ts + templates/ |
674
+ | 18 | 生成成功以产物为准,不以日志为准 | 缺包时误报成功 | generate.assessGenerateProducts |
675
+ | 19 | 生成期间 pdsc 停放必须在 finally 还原 | 用户的第三方包索引「消失」 | thirdparty.ts + generate.ts |
676
+ | 20 | 零运行时依赖、lib/ 入库 | 装上就坏 / 用户机器没有编译器 | package.json、tsconfig |
677
+ | 21 | cmake 源清单必须跟着 startup 与 hal_conf 走 | 开了外设也链接失败(undefined reference to HAL_xxx_Init) | cmake-sources.refreshCubemxCmakeLists、generate.ts 两处调用 |
678
+ | 22 | 链接脚本按 `<DeviceId>` 命名,命令行上只能有一个 `-T` | 链接的是别人的 MEMORY:编译过、烧到小容量芯片上跑飞(.ld 说 256 KiB,实际只有 64 KiB) | hal-chip.pointLinkerFlagAt、register-linker.renderLinkerScript、doctor.checkChipConsistency ①③ |
679
+ | 23 | 寄存器名字只能来自 SVD,插件不许内置寄存器表 | 手写表必然过期:偏移错一位就解释错位域,比不给名字更糟 | data/svd.ts(严格解析 + 整份拒绝)、test/svd-units |
680
+
681
+ ## 9. 测试体系
682
+
683
+ ### 9.1 三层
684
+
685
+ | 层 | 位置 | 说明 |
686
+ | --- | --- | --- |
687
+ | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 36 个套件 562 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
688
+ | 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/** ≤60 KB、包内禁二进制、必需文件齐全)。CI 上两连跑 |
690
+
691
+ ### 9.2 36 个套件一览(test/run-units.mjs 的 suites 数组顺序)
692
+
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。
694
+
695
+ 开发机上 562 例全跑;CI 上仍是 **2 skipped**(两条用例依赖本机路径,即 560 pass + 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
+
697
+ 约定:
698
+ - 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
699
+ - run-units 用 DSH_STM32_NO_CONFIG=1 跑子进程,避免开发机上真实的 ~/.dsh-stm32/config.json 影响断言。
700
+ - 输出解析认四种结尾(node:test spec / tap / 自写 tests N / fail M / inline);解析不到用例数会标红,而不是默默算 0。
701
+ - 套件退出码非 0 一律算失败,即使它自己打印 fail=0。
702
+ - 加套件必须手改 test/run-units.mjs 的 suites 数组——没有自动发现。
703
+
704
+ ### 9.3 单测的两种假件套路
705
+
706
+ ```ts
707
+ // 套路一:假 subprocess —— 按命令内容返回脚本化输出
708
+ const fake = {
709
+ async resolveExecutable(cmd) { return cmd; },
710
+ spawn(spec) { /* 按 spec.argv 决定往 stdout 写什么 */ },
711
+ };
712
+
713
+ // 套路二:假 fs / 临时目录 —— 真写盘到 os.tmpdir(),测量真实的备份、编码、原子替换
714
+ ```
715
+
716
+ 凡是「决定行为的分支」都要有脚本化的输出样本,样本**必须是上游真实格式**(审计期间踩过:按文件名猜 CMSIS 守卫宏,测的是假世界)。
717
+
718
+ ## 10. 要改东西时动哪里
719
+
720
+ | 想做的事 | 动这些文件 | 别忘了 |
721
+ | --- | --- | --- |
722
+ | 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
723
+ | 改报告字段 | 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 派生)、设备事实(资源仓库的 device/<族>/chips.json,由它的 scripts/build-assets.mjs 生成)、再补一份 clock-f1 那样的时钟上限表(否则寄存器版只能不出 clock_init) | 仓库名不能猜;sha256 逐文件实测并把来源 URL 记进表里(F1 的 14 条就是这么来的) |
725
+ | 加芯片型号(同族容量档) | **资源仓库的 device/f1/chips.json**(`node scripts/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 | 资源仓库改完要升 manifest 版本(插件按最新已装版本读);本地 `~/.dsh-stm32/assets/` 是旧版就先 `stm32_assets refresh`。三条路都要试:HAL 建工程、寄存器建工程、doctor 一致性 |
726
+ | 改时钟树 | 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
+ | 更新设备事实(芯片表) | **资源仓库** `node scripts/build-assets.mjs` 重跑 → device/f1/chips.json + memory.json + manifest.json 一起更新;插件侧 `stm32_assets refresh` 拉新版本 | 生成物不要手改;插件已经不再内置芯片表(`scripts/gen-chip-table.mjs` 与 chip-table.json 2026-10-31 删除),没缓存时工具会明说先 refresh。测试夹具在 `test/fixtures/assets/`,与真实资源包同构 |
728
+ | 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
729
+ | 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
730
+ | 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
731
+ | 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
732
+ | 加 / 改探针错误分类 | 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
+ | 改 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,老固件会被判成帧失步 |
735
+ | 改寄存器写法的解析或位域解释 | `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 / 新资源版本) | **资源仓库** `node scripts/build-assets.mjs` 重新从 cmsis-svd-data 生成 `device/f1/svd/<line>.json`(`files[].profile` 标 full,并带 ST EULA 来源)→ 插件侧 `stm32_assets action=refresh profile="full"` | SVD 严格解析:外设/寄存器/字段有一条不合法就整份拒绝;缓存键是 path+size+mtimeMs,升级后自动失效 |
737
+ | 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
738
+
739
+ ## 11. 已知的坑与未做的事
740
+
741
+ 1. **只有 F1 在 FIRMWARE_FAMILIES**:其他族要接入必须先核实真实仓库名(stm32g4xx-hal-driver 之类),不能照 F1 改字母。
742
+ 2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
743
+ 3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
744
+ 4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
745
+ 5. **P2(多芯片 + HAL 外设源文件按需落位)与 P3(gdb MI 常驻)** 未开工。
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/** ≤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。实测包体 509.9 KB / 99 个文件。
747
+ 7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
748
+ 8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
749
+ 9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
750
+ 10. **裸 `cmake -S . -B build` 会丢工具链文件**:工具链只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不走 preset 就得自己给 `-DCMAKE_TOOLCHAIN_FILE`,否则 configure 用宿主 gcc、链接时找不到启动文件。
751
+ 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
+ 12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
753
+ 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 只有离线验证**:`rtt-units` 26 例全离线(假 subprocess + 假端口),真机上只做到「建工程 + 编译 + `nm` 取址」,**没有一次真板子 dump**(手头的 WCH-Link 与坑 13 是同一个问题)。「只有通道 0 / 无 defmt 解码 / 默认占 3 KB RAM」是设计取舍,见 development-notes §30.6。**复测方法**:换回 CMSIS-DAP 探针,烧一个取消 `USER CODE BEGIN 2` 注释的寄存器工程,`nm` 拿 `_SEGGER_RTT`,再跑 `stm32_rtt action=start addr=<addr>` + `action=dump seconds=3`。
755
+ 15. **寄存器符号名与位域解释只有离线验证**:`svd-units` 39 例全离线(真实资源包 + 假 subprocess + 假 Tcl 服务端),**没有一次「真板子 + 真探针 + `GPIOC.ODR`」**(与坑 13 同一个 WCH-Link 问题)。**复测方法**:换回 CMSIS-DAP 探针后 `stm32_regs_read addresses=["GPIOC.ODR","0x4001100C"]`,看 `samples[0].name` / `fields` 与 notes 里的 SVD line。
756
+
757
+ ---
758
+
759
+ 读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。