dsh-stm32 0.1.7 → 0.1.9

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 (153) hide show
  1. package/README.md +567 -516
  2. package/README_EN.md +544 -510
  3. package/client/client.js +7033 -682
  4. package/docs/reading-guide.md +921 -859
  5. package/lib/client.js +7033 -682
  6. package/lib/commands/register.js +2 -0
  7. package/lib/data/firmware-packages.js +35 -0
  8. package/lib/data/firmware-pins.js +7 -0
  9. package/lib/data/install-guides.js +110 -0
  10. package/lib/data/ioc-presets.js +118 -0
  11. package/lib/engine/artifacts.js +123 -0
  12. package/lib/engine/breakpoint-hits.js +73 -0
  13. package/lib/engine/build.js +161 -5
  14. package/lib/engine/channel-tap.js +227 -0
  15. package/lib/engine/channels.js +48 -0
  16. package/lib/engine/clocks.js +192 -0
  17. package/lib/engine/datasheet/auto.js +74 -0
  18. package/lib/engine/datasheet/digest.js +74 -0
  19. package/lib/engine/datasheet/lcsc.js +60 -0
  20. package/lib/engine/datasheet/pinout.js +119 -0
  21. package/lib/engine/datasheet/price.js +152 -0
  22. package/lib/engine/datasheet/search.js +147 -0
  23. package/lib/engine/datasheet/store.js +371 -0
  24. package/lib/engine/debug-session.js +48 -2
  25. package/lib/engine/ecad/autobuild.js +156 -0
  26. package/lib/engine/ecad/bom.js +238 -0
  27. package/lib/engine/ecad/brief.js +205 -0
  28. package/lib/engine/ecad/checks.js +239 -0
  29. package/lib/engine/ecad/design.js +177 -0
  30. package/lib/engine/ecad/dfm.js +314 -0
  31. package/lib/engine/ecad/easyeda.js +454 -0
  32. package/lib/engine/ecad/fabrication.js +104 -0
  33. package/lib/engine/ecad/gen/footprint.js +159 -0
  34. package/lib/engine/ecad/gen/symbol.js +103 -0
  35. package/lib/engine/ecad/import.js +372 -0
  36. package/lib/engine/ecad/jlcpcb.js +141 -0
  37. package/lib/engine/ecad/libs.js +316 -0
  38. package/lib/engine/ecad/models3d.js +89 -0
  39. package/lib/engine/ecad/netgate.js +286 -0
  40. package/lib/engine/ecad/normalize.js +182 -0
  41. package/lib/engine/ecad/package.js +126 -0
  42. package/lib/engine/ecad/padmerge.js +128 -0
  43. package/lib/engine/ecad/padprecheck.js +123 -0
  44. package/lib/engine/ecad/part-import.js +257 -0
  45. package/lib/engine/ecad/pcb/apply.js +53 -0
  46. package/lib/engine/ecad/pcb/emc-deep.js +396 -0
  47. package/lib/engine/ecad/pcb/emc.js +275 -0
  48. package/lib/engine/ecad/pcb/geometry.js +63 -0
  49. package/lib/engine/ecad/pcb/gerber.js +499 -0
  50. package/lib/engine/ecad/pcb/hand-sync.js +242 -0
  51. package/lib/engine/ecad/pcb/impedance.js +119 -0
  52. package/lib/engine/ecad/pcb/ipc-open.js +78 -0
  53. package/lib/engine/ecad/pcb/ipc-script.js +276 -0
  54. package/lib/engine/ecad/pcb/ipc.js +129 -0
  55. package/lib/engine/ecad/pcb/krt.js +182 -0
  56. package/lib/engine/ecad/pcb/links.js +393 -0
  57. package/lib/engine/ecad/pcb/mech.js +201 -0
  58. package/lib/engine/ecad/pcb/model-fix.js +178 -0
  59. package/lib/engine/ecad/pcb/netlist.js +146 -0
  60. package/lib/engine/ecad/pcb/pcb-svg.js +199 -0
  61. package/lib/engine/ecad/pcb/placement.js +140 -0
  62. package/lib/engine/ecad/pcb/power.js +203 -0
  63. package/lib/engine/ecad/pcb/render3d.js +208 -0
  64. package/lib/engine/ecad/pcb/route.js +167 -0
  65. package/lib/engine/ecad/pcb/router.js +469 -0
  66. package/lib/engine/ecad/pcb/rules.js +122 -0
  67. package/lib/engine/ecad/pcb/scene.js +513 -0
  68. package/lib/engine/ecad/pcb/stackup.js +154 -0
  69. package/lib/engine/ecad/pcb/swap.js +222 -0
  70. package/lib/engine/ecad/pcb/tracks.js +70 -0
  71. package/lib/engine/ecad/runtime.js +227 -0
  72. package/lib/engine/ecad/toolchain.js +146 -0
  73. package/lib/engine/ecad/tsci.js +362 -0
  74. package/lib/engine/ecad/zip.js +98 -0
  75. package/lib/engine/event-bus.js +158 -0
  76. package/lib/engine/event-log.js +335 -0
  77. package/lib/engine/fault-hints.js +146 -0
  78. package/lib/engine/generate-script.js +4 -1
  79. package/lib/engine/generate.js +145 -5
  80. package/lib/engine/interrupts.js +247 -0
  81. package/lib/engine/ioc-diff.js +369 -0
  82. package/lib/engine/ioc-plan.js +12 -2
  83. package/lib/engine/ioc-sync.js +58 -0
  84. package/lib/engine/mcu-info.js +134 -0
  85. package/lib/engine/msys2-install.js +31 -6
  86. package/lib/engine/panel-actions.js +103 -0
  87. package/lib/engine/pdf/curve.js +321 -0
  88. package/lib/engine/pdf/png.js +83 -0
  89. package/lib/engine/pdf/reader.js +336 -0
  90. package/lib/engine/pdf/schematic.js +93 -0
  91. package/lib/engine/pdf/tables.js +249 -0
  92. package/lib/engine/pdf/toolchain.js +50 -0
  93. package/lib/engine/pinout.js +140 -0
  94. package/lib/engine/probe-info.js +95 -0
  95. package/lib/engine/probe.js +45 -0
  96. package/lib/engine/progress.js +99 -0
  97. package/lib/engine/project-conf.js +254 -0
  98. package/lib/engine/project-layout.js +198 -0
  99. package/lib/engine/project-repair.js +205 -0
  100. package/lib/engine/schematic/checks.js +153 -0
  101. package/lib/engine/schematic/draw.js +390 -0
  102. package/lib/engine/schematic/edit.js +229 -0
  103. package/lib/engine/schematic/kicad-sch.js +225 -0
  104. package/lib/engine/schematic/model.js +442 -0
  105. package/lib/engine/schematic/nets.js +219 -0
  106. package/lib/engine/schematic/pcb.js +144 -0
  107. package/lib/engine/schematic/review.js +134 -0
  108. package/lib/engine/schematic/sexpr.js +134 -0
  109. package/lib/engine/schematic/to-ioc.js +197 -0
  110. package/lib/engine/schematic/transform.js +25 -0
  111. package/lib/engine/session-context.js +106 -0
  112. package/lib/engine/source-slice.js +59 -0
  113. package/lib/engine/tool-events.js +119 -0
  114. package/lib/engine/toolchain-gate.js +8 -0
  115. package/lib/engine/watch-admin.js +101 -0
  116. package/lib/engine/watch-record.js +39 -0
  117. package/lib/engine/watch-recorder.js +116 -0
  118. package/lib/engine/web-api.js +1123 -4
  119. package/lib/engine/web-routes.js +18 -1
  120. package/lib/engine/workspace-memo.js +41 -0
  121. package/lib/index.js +118 -24
  122. package/lib/skill/stm32-workflow.js +1 -1
  123. package/lib/tools/build.js +10 -2
  124. package/lib/tools/code-patch.js +2 -2
  125. package/lib/tools/datasheet.js +447 -0
  126. package/lib/tools/debug-session.js +9 -4
  127. package/lib/tools/debug.js +2 -2
  128. package/lib/tools/doctor.js +2 -2
  129. package/lib/tools/ecad.js +903 -0
  130. package/lib/tools/flash.js +2 -2
  131. package/lib/tools/gen.js +166 -0
  132. package/lib/tools/generate.js +7 -5
  133. package/lib/tools/import-circuit.js +146 -0
  134. package/lib/tools/ioc-apply.js +11 -2
  135. package/lib/tools/ioc-inspect.js +2 -2
  136. package/lib/tools/ioc-plan.js +2 -2
  137. package/lib/tools/ioc-verify.js +2 -2
  138. package/lib/tools/layout.js +92 -0
  139. package/lib/tools/mcu-info.js +163 -0
  140. package/lib/tools/part-import.js +182 -0
  141. package/lib/tools/pcb.js +2316 -0
  142. package/lib/tools/pdf.js +423 -0
  143. package/lib/tools/project-create.js +28 -0
  144. package/lib/tools/project-dir.js +25 -1
  145. package/lib/tools/regs.js +2 -2
  146. package/lib/tools/route-plan.js +2 -2
  147. package/lib/tools/rtt.js +10 -2
  148. package/lib/tools/sch-draw.js +433 -0
  149. package/lib/tools/sch-edit.js +145 -0
  150. package/lib/tools/schematic.js +817 -0
  151. package/lib/tools/serial.js +22 -0
  152. package/lib/tools/watch.js +24 -2
  153. package/package.json +1 -1
@@ -1,859 +1,921 @@
1
- # dsh-stm32 源码精读指南
2
-
3
- > 面向:第一次读这个仓库、并且要改它的人。
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
- > 读完这份指南你应该能回答:一次工具调用从宿主进来到 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(24 个文件:25 个工具 + 1 个基础设施;一个文件可注册多个工具) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
- | L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
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
-
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/>25 个工具"]
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/>65 个纯逻辑模块"]
53
- CMDS --> ENGINE
54
- WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
55
- API --> ENGINE
56
- ENGINE --> DATA["src/data/*<br/>10 个数据模块(芯片事实读包内 assets/;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/ | 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
- | 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/ | 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
-
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) 里按「先探测、再操作」的顺序注册 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
- 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 层:25 个工具 + 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 25 个工具一览
194
-
195
- | 工具 | 文件(行) | engine 入口 | 门禁能力 |
196
- | --- | --- | --- | --- |
197
- | `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
198
- | `stm32_download` | download.ts(300) | download.planDownload / downloadUrlToFile / sha256File / inspectInstallerFile | 无(只下载与校验,绝不执行安装器) |
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_ioc_verify` | ioc-verify.ts(246) | ioc-verify.runIocVerify(CubeMX 无头 load→save 回读对比) | generate(CubeMX + JRE) |
208
- | `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
209
- | `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
210
- | `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
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 需要会话) |
213
- | `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
214
- | `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
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) | 无 |
217
- | `stm32_cache` | cache.ts(306) | engine/cache 全套 | 无 |
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`,不起桥) |
220
- | —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
221
-
222
- 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**serial.ts 829 行**现在是 tools 层最大的,**regs.ts 735 行**次之(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**第三——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
223
-
224
- ## 5. engine 层:D 阶段的 45 个模块,十个域(现 65 个 .ts)
225
-
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` 一起看。
227
-
228
- ### 5.1 进程与路径(3 个,413 行)
229
-
230
- | 模块 | 职责与关键导出 |
231
- | --- | --- |
232
- | 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。 |
233
- | tool-env.ts(56) | `envWithBinDirs(binDirs, base)`:binDirs 去重去空后**拼在原 PATH 前面**,Windows 上只留一个大小写正确的 `Path` 键;`toolSearchDirs(binDirs, base)` 给出「去哪找可执行文件」的有序目录表。 |
234
- | fs-longpath.ts(107) | 长路径工具。`toLongPath` 加 `\\?\` 前缀、`existsLong`、`mkdirTrackedLong`(顺手记下新建的目录,失败时回收)、`copyFileLong`、`copyTreeLong`、`describeCopyFailure`。固件包的 Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc 这种深度在长用户名下会撞 MAX_PATH(审计 B17)。 |
235
-
236
- ### 5.2 探测、搜索与门禁(engine 2 个 + data 2 个,1649 行)
237
-
238
- | 模块 | 职责与关键导出 |
239
- | --- | --- |
240
- | 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 个探测目标)。 |
241
- | 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)。 |
242
- | 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`。 |
243
- | 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`。 |
244
-
245
- ### 5.3 构建与产物(2 个,543 行)
246
-
247
- | 模块 | 职责与关键导出 |
248
- | --- | --- |
249
- | 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`。 |
250
- | 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/。 |
251
-
252
- ### 5.4 烧录、调试与诊断(9 个,4087 行)
253
-
254
- | 模块 | 职责与关键导出 |
255
- | --- | --- |
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 不会再各写一套漂移。 |
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 三元组。 |
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(...)`。 |
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` 是什么。 |
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 三条路径共用同一份规则。 |
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。 |
263
- | 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 超时 / 帧失步)只此一份。 |
264
- | 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 **之前**就失败,不碰探针、也不关已有会话。 |
265
- | 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 的那个)。 |
266
-
267
- ### 5.5 生成、编码、.ioc 事务与时钟(10 个,3657 行)
268
-
269
- | 模块 | 职责与关键导出 |
270
- | --- | --- |
271
- | 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。 |
272
- | generate-script.ts(115) | `buildGenerateScript` 拼脚本(setCustomFWPath / SetCopyLibrary / ProjectManager 项)、`layoutCommand`、`parseGenerateLog`:UNKNOWN_COMMAND 先判;成功行不再「一票否决」错误(审计 A10)——CubeMX 缺包时也会打 Code successfully generated,所以 ok 由产物判据决定。 |
273
- | generate-cache.ts(168) | 生成缓存。`CACHE_FILE = "generate-cache.json"`、`sha256Text` / `sha256File`、`cubeMxStamp`、`computeCacheKey(iocSha, stamp, layout)`、`readCache` / `writeCache`、`cacheHit(entry, key, projectDir)`(key 命中还不够,文件 hash 也得对得上)。 |
274
- | usercode-merge.ts(142) | `parseUserCodeRegions` / `mergeUserCode` / `canMergeUserCode`:把旧文件 USER CODE 块里的内容搬进新生成的文件,保留 CRLF 风格,标出 droppedLabels。 |
275
- | code-patch.ts(215) | `patchUserCode`:只改一个 USER CODE 块(replace / append),块内出现 `{` 或 `}` 拒绝(结构行守卫),写前备份,写回**按字节拼接**(见 text-file)。`listUserCodeLabels` 列出可用标签。 |
276
- | text-file.ts(172) | 编码层。`detectEncoding`(BOM → utf8-bom;空 → utf8;严格 UTF-8 成 → utf8;再试 gb18030;否则 unknown)、`decodeText`、`encodeText`(gb18030 只允许纯 ASCII——Node 只有解码器没有编码器)、`readTextFile`、`lineStarts`、`replaceLineRange`(未改的行原字节照抄,只把新增行按原编码插入)。**这是「中文注释不被写坏」的唯一保障**。 |
277
- | ioc.ts(202) | .ioc 只读解析:`parseIocEntries`、`decodeIocValue`、`summarizeIoc`(MCU、时钟树、引脚、外设、调试口、工程设置、警告)。 |
278
- | ioc-plan.ts(612) | .ioc 事务。`planIocChanges` 算出逐键 diff + 源 SHA-256 → planId;`applyIocPlan` 校验 SHA 后原子替换(备份到 backups/<stamp>-ioc);`rollbackIoc(backupFrom)` 回滚;辅助 `renderIocText`、`compareEntries`、`sha256Hex`、`encodeIocValue`、`loadPlan`。引脚写入保序(审计 A3):只追加新增,不因缺 .Signal 删已有项。 |
279
- | 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。 |
280
- | 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。 |
281
-
282
- ### 5.6 造工程、链接脚本与导出(8 个,2224 行)
283
-
284
- | 模块 | 职责与关键导出 |
285
- | --- | --- |
286
- | 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 在**写盘之前**渲染成字符串,渲染失败时一个字节都不写。 |
287
- | 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)。全是字符串函数,所以能先渲染后落盘。 |
288
- | register-template.ts(584) | 寄存器路线(不碰 CubeMX)。`resolveStartupChoice`(按型号/族选启动文件与宏)、`ensureCmsisTemplate`(从镜像下载 10 个文件到缓存并校验 sha256)、`createRegisterProject`(拷模板 → 写设备头/启动文件/链接脚本 → 生成 main.c)。模板文件缺失分「必需」与「可选」(.gitignore 是可选,缺了给 warning 不阻断)。模板里已不写死任何型号:启动文件、设备宏、设备头、`.ld`、时钟全部按 `resolveF1Chip` 的结果参数化(14 个容量档)。 |
289
- | 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 跟着对。 |
290
- | register-linker.ts(152) | 寄存器版的链接脚本渲染:按型号换掉 `<DeviceId>_FLASH.ld` 的 MEMORY RAM/FLASH 两行。F100/F101/F102 的 RAM 不在 src/data/stm32f1.ts 的表里,用 CubeMX db 的最小值兜底**并明确警告**(宁可小——栈必须留在真 RAM 内)。 |
291
- | vscode-config.ts(118) | `VSCODE_PLACEHOLDERS`(gdb / toolchain / cmake / svd 四个占位符)、`detectVscodeFill`(按本机探测结果填)、`fillVscodeTemplate`(没值的整行删掉并记 dropped,绝不写空串)、`describeDroppedPlaceholder`。模板里因此不出现任何开发机绝对路径(审计 B1)。 |
292
- | project-export.ts(155) | `runExport`:收集源文件(跳过 build / .dsh-stm32 / node_modules / .git)→ 可选带 prebuilt(elf/hex/bin)→ 可选内联 README → 打 zip。 |
293
- | zip.ts(152) | 自写的最小 store-only zip(不压缩、不引依赖):`crc32`、`makeZip`、`listZipEntries`(测试用来验内容)。 |
294
-
295
- ### 5.7 下载、缓存与固件包(7 个,2502 行)
296
-
297
- | 模块 | 职责与关键导出 |
298
- | --- | --- |
299
- | 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)`,否则半成品会长期躺在缓存目录里等着占满磁盘。 |
300
- | 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`。 |
301
- | tar.ts(288) | `extractTarGz(archive, destRoot, options)`:解 gzip + tar,路径白名单(`isSafeRelative` 拒反斜杠、冒号、.. 与空段)、类型白名单(`entryKind`:0/空/5 正常,x/g/L/K 元数据,其余跳过并记名,审计 A4)、声明长度超出实际数据判截断整次失败。 |
302
- | 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 也能找到非标准落点。 |
303
- | thirdparty.ts(281) | 生成期间临时停放 CubeMX 的第三方包索引(`PARKED_NAME = "pdsc.dsh-parked"`、`needsThirdpartyPacks`、`parkThirdpartyDb`),有 X-CUBE 包的工程保持原样;`cubeMxUserHome`。 |
304
- | xcube.ts(293) | X-CUBE 包识别:`identifyPackId`、`parsePdscNames`、`listInstalledPacks`、`scanIocPacks`、`summarizePacks`。 |
305
- | xcube-catalog.ts(117) | 由 scripts/gen-xcube-catalog.mjs 生成的包目录(159 条)。`XCUBE_CATALOG_ENTRY_COUNT = XCUBE_PACK_CATALOG.length`(审计 A23:不要把条目数写成数字常量,重跑脚本会回写旧值)。 |
306
-
307
- ### 5.8 工具链安装(1 个,2313 行)
308
-
309
- | 模块 | 职责与关键导出 |
310
- | --- | --- |
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`。 |
312
-
313
- ### 5.9 设置面板的宿主侧(2 个,577 行)
314
-
315
- | 模块 | 职责与关键导出 |
316
- | --- | --- |
317
- | 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`。 |
318
- | web-routes.ts(100) | 薄适配层:`ctx.inject(["webServer"], ...)` 里 `server.register({ kind: "exact", path, handler })`,把 request/response 收成 `handleWebApi` 的输入输出,加 `cache-control: no-store`。宿主没 webServer 服务时静默跳过(面板不可用,工具照常)。 |
319
-
320
- ### 5.10 路线评估(1 个,645 行)
321
-
322
- | 模块 | 职责与关键导出 |
323
- | --- | --- |
324
- | route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
325
-
326
- ## 6. data 层:10 个数据模块(3599 行;芯片事实来自包内 assets/)
327
-
328
- | 模块 | 行数 | 内容 |
329
- | --- | --- | --- |
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 就明说「引脚存在性不校验」,绝不拿内置表冒充)。 |
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 真实下载实测的。 |
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 没有这一容量档。 |
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 名单。 |
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`。 |
335
- | install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
336
- | search-roots.ts | 421 | 见 5.2。 |
337
- | toolchain-config.ts | 370 | 见 5.2。 |
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` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
340
-
341
- ## 7. 关键流程
342
-
343
- 这一章是全书重点:每个流程都给「一张图 + 几个必须知道的失败面」。看图时对照第 5 章的模块表找文件。
344
-
345
- ### 7.1 一次工具调用的通用管线
346
-
347
- ```mermaid
348
- sequenceDiagram
349
- participant U as 模型/用户
350
- participant H as DSH 宿主
351
- participant T as src/tools/x.ts
352
- participant E as src/engine
353
- participant S as 宿主 subprocess
354
- participant B as gcc/cmake/openocd/CubeMX
355
- U->>H: 调工具 + JSON 参数
356
- H->>T: execute(args, exec)
357
- T->>T: resolveProjectDir + validateToolArgs
358
- T->>E: ensureToolchain(capability, envCheck)
359
- E-->>T: GateResult{ok, missing[], install[]}
360
- alt 门禁拦截
361
- T-->>H: blockedReport 同形报告
362
- else 门禁通过
363
- T->>E: run*(subprocess, request)
364
- E->>S: spawn{argv, cwd, env, stdio.maxBytes}
365
- S->>B: 真进程
366
- B-->>S: stdout/stderr + exitCode
367
- S-->>E: RunOutcome
368
- E-->>T: Report
369
- T->>T: render(report) → 中文行
370
- T-->>H: report(必须过 output.schema)
371
- end
372
- ```
373
-
374
- 必须知道的失败面:
375
- - **输出 schema 是硬约束**:report 多一个没声明的字段,宿主就判「非法输出」。改 report 必改 schema,并用 test/schema-guard.mjs 兜住。
376
- - **exec.signal 一路要透传**:工具超时/用户取消 → spawn 被 abort → RunOutcome.aborted=true → report 里写「已取消」。任何一格没接 signal,取消就变成「等 30 秒超时」。
377
- - **门禁在工具层**:engine 不知道门禁存在,所以 engine 的返回永远按「工具链就位」写文案。
378
-
379
- ### 7.2 工具链门禁:快路径、慢路径与缓存
380
-
381
- ```mermaid
382
- flowchart TD
383
- A["ensureToolchain(capability, envCheck)"] --> B{"envCheck = off?"}
384
- B -->|是| PASS["ok=true 直接放行"]
385
- B -->|否| C["CAPABILITY_COMPONENTS 列必需组件"]
386
- C --> D{"快路径:binDirs 里文件都在?"}
387
- D -->|是| E["smokeTarget:跑一次主组件的版本命令<br/>build→gcc flash→openocd debug→gdb generate→cubemx-java<br/>60 s 缓存"]
388
- E -->|跑通| PASS
389
- E -->|失败| F["按缺件处理,error 写「文件在但版本命令没跑通」"]
390
- D -->|否| G["慢路径:probeAll 全量探测<br/>allowPathFallback 默认开"]
391
- G --> H{"signal.aborted?"}
392
- H -->|是| I["break:不写缓存(审计 A27)"]
393
- H -->|否| J["probeCache.set(key, {at, results}) 60 s"]
394
- J --> K{"有缺件?"}
395
- F --> K
396
- K -->|无| PASS
397
- K -->|有| L{"envCheck = warn?"}
398
- L -->|是| M["ok=true + warnings 一行"]
399
- L -->|否| N["ok=false + missing[](含 hint/impact/install/verify)"]
400
- ```
401
-
402
- 为什么快路径也要跑版本命令(审计 B13):「文件存在」不等于「文件能跑」——半截下载、被杀软隔离、架构不对、0 字节,都表现为文件在而进程起不来。只对**主组件**做 smoke,是为了保住快路径「零全量 spawn」的价值;其余组件坏了慢路径照样兜住。
403
-
404
- ### 7.3 project_create:两条完全不同的路线
405
-
406
- ```mermaid
407
- flowchart TD
408
- A["stm32_project_create{targetDir, projectName, route}"] --> P["preflightTarget:<br/>1 工程名是 C 标识符<br/>2 目录非空 → 拒绝<br/>3 hal 且已有同名 .ioc → 拒绝并指向 ioc_plan/apply"]
409
- P --> R{"route?"}
410
- R -->|register| S1["ensureCmsisTemplate:<br/>按型号选启动文件 → 下载 10 个文件 → sha256 校验 → 落缓存"]
411
- S1 --> S2["createRegisterProject:<br/>拷模板 7 件(含 .gitignore、openocd.cfg、链接脚本)<br/>写设备头/启动文件/system.c/main.c"]
412
- S2 --> S3["模板缺失分流:必需 → 一次列全并拒绝<br/>可选(.gitignore) → warning 继续"]
413
- R -->|hal| H1["resolveFirmwareRoot:Repository → dsh-firmware → extraDirs<br/>找不到就带安装指引失败"]
414
- H1 --> H2["backupBeforeOverwrite:只备份真会被覆盖的文件<br/>备份失败 → 一字不写"]
415
- H2 --> H3["createProjectScaffold:拷 15 个模板 + 从固件包拷 Drivers/238 件<br/>复制走 fs-longpath"]
416
- H3 --> H4["写 .vscode/:按本机探测填占位符,没值的整行删掉并记 warning"]
417
- S3 --> DONE["报告:templateFiles / driverFiles / firmwareRoot / warnings"]
418
- H4 --> DONE
419
- DONE --> FAIL{"中途失败?"}
420
- FAIL -->|是| CL["cleanupAfterFailure:只回收本次新建<br/>原有目录只 rmdir 空目录"]
421
- ```
422
-
423
- 两条路线的共同点只有「先预检、再备份、失败回收」。区别是 hal 依赖 CubeMX 固件包(无网也能用整目录拷贝),register 依赖网络下载 CMSIS(但缓存命中后完全离线)。
424
-
425
- ### 7.4 build:preset → 编译 → 产物
426
-
427
- ```mermaid
428
- flowchart LR
429
- A["runBuild"] --> B["pickConfigurePreset<br/>优先 Debug"]
430
- B --> C["cmake --preset=<name><br/>env 注入 binDirs + 原 PATH"]
431
- C --> D["cmake --build --preset=<name>"]
432
- D --> E["findElf → pickElf:CMakeCache 工程名优先<br/>否则取 mtime 最新的 .elf;elfSelectionNote 进 notes"]
433
- E --> F["parseMemoryUsage / parseBuildErrors / countWarnings"]
434
- F --> G{"artifacts 里要 hex/bin?"}
435
- G -->|是| H["arm-none-eabi-objcopy -O ihex / binary<br/>失败只写 note,不判 build 失败"]
436
- G -->|否| I["报告"]
437
- H --> I
438
- ```
439
-
440
- 选哪个 .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 都会带这条说明。
441
-
442
- 坑:**复制过的工程**(CMakeCache 里记着别的路径)会报奇怪的错,build.ts 里有显式拦截:检测到 CMakeCache 的源目录与当前工程不一致就直接给「把 build/ 删掉重配」。
443
-
444
- ### 7.5 flash:守卫 → 烧录 → 判定 → 错误分类
445
-
446
- ```mermaid
447
- flowchart TD
448
- A["stm32_flash"] --> B["releaseProbeFor:先还探针(审计 B16)"]
449
- B --> C["checkNoDebugGuard(projectDir, allowNoDebug, iocPath)"]
450
- C --> C1{"有唯一 .ioc?"}
451
- C1 -->|有| C2["PA13=SYS_JTMS-SWDIO / PA14=SYS_JTCK-SWCLK / Mode=Serial_Wire?"]
452
- C1 -->|没有或多个| C3["看 openocd.cfg 的 transport:swd 放行并说明依据<br/>jtag 提示引脚复用<br/>都没有 → notes 两条「守卫没生效」"]
453
- C2 -->|是 No_Debug| BLOCK["blocked:拒绝,除非 allowNoDebug"]
454
- C2 -->|是 Serial Wire| D["resolveElf(内部 findElf → pickElf,notes 说明选中的是哪个)"]
455
- C3 --> D
456
- D --> E["findProjectConfig:openocd.cfg 优先<br/>否则 interface/cmsis-dap.cfg + target/stm32f1x.cfg"]
457
- E --> F["openocd -f ... -c program <elf> verify reset exit"]
458
- F --> G["parseFlashLog:认 Programming Finished / Verified OK<br/>成功序列里的偶发 Error 行进 noise"]
459
- G --> H{"ok?"}
460
- H -->|是| OK["programmed + verified,probeError 缺省(成功时字段根本不出现)"]
461
- H -->|否| I["classifyProbeFailure 分 8 类:no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / timeout / unknown"]
462
- I --> J["notes:USB 形态(usbNoteFor)+ probe-busy 专用提示(HINT_BUSY)"]
463
- ```
464
-
465
- 真板子取证过的一个细节:两个进程同时访问同一个 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/`)。
466
-
467
- ### 7.6 调试三件套与会话租约
468
-
469
- ```mermaid
470
- stateDiagram-v2
471
- [*] --> 空闲
472
- 空闲 --> 启动中: stm32_debug_session(start)
473
- 启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
474
- 启动中 --> 空闲: 端口占用 / 探针失败、带 probeError(kind / cause / hint)
475
- 活跃 --> 活跃: stm32_debug_eval、优先常驻 MI(连不上才每次新起 gdb -batch:连上 → halt → 命令 → resume → detach)
476
- 活跃 --> 空闲: stm32_debug_stop
477
- 活跃 --> 空闲: 空闲 90 s
478
- 活跃 --> 空闲: 总时长 10 min
479
- 活跃 --> 空闲: turn/end、本轮输出结束
480
- 活跃 --> 空闲: session/disposed / 插件 dispose
481
- ```
482
-
483
- 三条设计理由:
484
- 1. **只有 openocd 常驻**,gdb 每次短命——gdb 崩了不会把会话带死,也避免 gdb 自己攒一堆状态。
485
- 2. **归属(A9)**:turn/end 事件里尽量掏 agent id,只关这条会话自己开的;掏不到就全关(宁可按最短释放,也不攥着探针)。
486
- 3. **别人要用探针先 releaseProbeFor**:flash / debug_run 在自己起 openocd 之前调它,否则就是「两个 openocd 抢一个 CMSIS-DAP」。**regs_read 是例外(B3 起)**:它反过来复用会话里的那个 openocd,连读时不再一读一起一停。
487
-
488
- 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 即可复测。
489
-
490
- B4 的断点预算在同一条 execute 里先算(`resolveBreakpointBudget` 读 .ioc 的 Mcu.CPN → chips.json 的 breakpoints/watchpoints,缺就按 F1 默认 6 硬件断点 / 4 观察点并说明原因),超限在 spawn openocd **之前**就失败——不占探针、也不关你正开着的会话;报告里 `breakpoints` / `watchpoints` 各是 `{used, limit, remaining}`。
491
-
492
- **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。
493
-
494
- 报告里的 `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 那次「失败路径被判非法输出」。
495
-
496
- ### 7.7 .ioc 事务:plan → 用户确认 → apply / rollback
497
-
498
- ```mermaid
499
- sequenceDiagram
500
- participant M as 模型
501
- participant P as stm32_ioc_plan
502
- participant A as stm32_ioc_apply
503
- participant F as demo.ioc
504
- M->>P: entries / unset / pins / serialWire
505
- P->>F: 只读解析 + 逐键 diff
506
- P-->>M: planId + sourceSha256 + changes[](不写盘)
507
- M->>M: 决定要不要动(用户确认)
508
- M->>A: {planId}
509
- A->>F: 重新算 SHA-256 并比对
510
- alt SHA 变了
511
- A-->>M: 拒绝:源文件已被改过,重新 plan
512
- else SHA 一致
513
- A->>F: 备份到 .dsh-stm32/backups/<stamp>-ioc
514
- A->>F: 原子替换(写 tmp → rename)
515
- A-->>M: appliedChanges + backupPath
516
- end
517
- M->>A: {rollbackFrom: backupPath}
518
- A->>F: 先备份当前内容,再写回备份
519
- A-->>M: rolledBack=true
520
- ```
521
-
522
- .ioc 是唯一的「配置真相」,所以它有三重保护:**不写盘的计划阶段**、**SHA 校验**、**每次写前都备份**。引脚写入保序(审计 A3)也是为这条服务的:无意义的顺序抖动会让 diff 看起来像改了很多东西。
523
-
524
- ### 7.8 generate:CubeMX 无头模式的全流程
525
-
526
- ```mermaid
527
- flowchart TD
528
- A["runGenerate"] --> B["findIocFile:只认唯一 .ioc"]
529
- B --> C["acquireLock:lock.json{pid, startedAt, purpose}<br/>isProcessAlive 探活,30 min 兜底"]
530
- C --> D["固件包定位:Repository → dsh-firmware → extraDirs<br/>同时算出 firmwareSource"]
531
- D --> E["detectLayout:coupled / per-ip"]
532
- E --> F["cacheKey = sha256(.ioc) + cubeMxStamp(java,jar) + layout"]
533
- F --> G{"缓存命中且文件 hash 全对?"}
534
- G -->|是| Z["直接复用上次产物(skipped=true)"]
535
- G -->|否| H["thirdparty:无 X-CUBE 包时临时停放 pdsc 索引(省约 25 s)"]
536
- H --> I["写 CubeMX 脚本到 .dsh-stm32/tmp/gen-<stamp>.txt<br/>-Dfile.encoding=UTF-8 + setCustomFWPath"]
537
- I --> J["java -jar STM32CubeMX.exe -q <script>"]
538
- J --> K["parseGenerateLog:UNKNOWN_COMMAND → commandErrors<br/>成功行不再一票否决错误"]
539
- K --> L["恢复 pdsc 索引(finally)"]
540
- L --> M["搬产物:.dsh-stm32/gen/Src|Inc → Core/Src|Inc<br/>旧文件先读编码 → 认不出就 skipped-encoding<br/>能读就 mergeUserCode 保 USER CODE"]
541
- M --> N["assessGenerateProducts:产物判据决定 ok<br/>(CubeMX 缺包时也会打 successfully generated)"]
542
- N --> O["写 generate-cache(key + 每个文件 sha256)"]
543
- O --> P["refreshCubemxCmakeLists:源清单跟着 startup / hal_conf 走<br/>设备宏、startup、HAL 模块清单三块;内容没变不写盘"]
544
- Z --> P2["缓存命中分支同样调一次 refresh"]
545
- P --> R["releaseLock(rm lock.json)"]
546
- P2 --> R
547
- ```
548
-
549
- 四个坑:
550
- - **源清单不会自己长**: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,带真工具链差分验证)。
551
- - **锁的探活**:早期只看 pid+时间,进程崩了要等 30 分钟;现在先 isProcessAlive(pid),死了立刻接管(审计 A14)。
552
- - **成功日志不等于成功**:CubeMX 缺固件包/包版本不认时也打 Code successfully generated,所以 ok 必须有产物判据(审计 A10)。
553
- - **中文路径**:脚本按 UTF-8 写且启动 java 时指定 -Dfile.encoding=UTF-8(审计 B18);否则中文工程路径在脚本里变乱码。
554
-
555
- ### 7.9 code_patch:只改块内,按字节写回
556
-
557
- ```mermaid
558
- flowchart TD
559
- A["patchUserCode{file, block, code, mode}"] --> B["读成 Buffer(不按 utf8 直读)"]
560
- B --> C["detectEncoding:BOM/严格 UTF-8/GB18030<br/>unknown → 拒绝,一个字节都不动"]
561
- C --> D["定位块:正则认 USER CODE BEGIN/END 标记"]
562
- D --> E{"块内含 { 或 }?"}
563
- E -->|是| X["拒绝:那是结构行,不许塞代码"]
564
- E -->|否| F["lineStarts 算出块的起止行"]
565
- F --> G["replaceLineRange:未改的行原字节照抄<br/>只把新增行按原编码插入,保留 CRLF/LF"]
566
- G --> H{"结果与原文相同?"}
567
- H -->|是| Y["回一句「内容没有变化」"]
568
- H -->|否| I["备份到 .dsh-stm32/backups/<stamp>-patch"]
569
- I --> J["写 tmp → rename(原子)"]
570
- ```
571
-
572
- 为什么要字节级拼接而不是「读成字符串再写回」:GB18030 的文件 Node 能解不能编,整份重新编码会把用户的中文注释写成问号。现在的策略是「动的只有块内那几行,其余字节原样搬运」。
573
-
574
- ### 7.10 firmware_install:选址、下载、组装、记录
575
-
576
- ```mermaid
577
- flowchart TD
578
- A["firmwarePlanFor{family, mcu, version}"] --> B["选址 decideTarget:<br/>已有包? → existing<br/>CubeMX 目录可用? → <root>/dsh-firmware<br/>否则 cache/custom"]
579
- B --> C{"受保护目录?<br/>Program Files / ProgramData / SystemRoot"}
580
- C -->|是| X["判不可写,给下一步建议"]
581
- C -->|否| D["download:2 个归档 + 5 个内核头<br/>每个都过 sha256"]
582
- D --> E["extractTarGz:路径白名单 + 类型白名单 + 截断检测"]
583
- E --> F["补 package.xml(版本 tag)"]
584
- F --> G["verifyFirmwarePackage:Drivers/CMSIS、startup、hal 源都在?"]
585
- G --> H["写 installed.json 记录(targetDir + 版本 + 时间)"]
586
- H --> I["nextStep:告诉用户接下来 stm32_project_create 还是 stm32_generate"]
587
- ```
588
-
589
- 为什么装到 <CubeMX>/dsh-firmware 而不是塞进官方 Repository:CubeMX 会静默忽略自造版本号的包;真正生效的是生成脚本里的 project setCustomFWPath。所以「包放哪」和「CubeMX 认不认」是两件事——这一点写在 docs/development-notes.md §14.1。
590
-
591
- ### 7.11 env_install 的计划模式:只报缺件
592
-
593
- ```mermaid
594
- flowchart TD
595
- A["stm32_env_install{mode=plan}"] --> B["isMsys2Root(msys64):有 usr/bin/bash.exe 且 pacman 在?"]
596
- B -->|是| C["只读问 pacman:pacman -Q <5 个包><br/>超时 60 s,问不出来就不编清单"]
597
- B -->|否| D["按全新安装估算(43.1 MB 下载)"]
598
- C --> E["在目标 binDir 里跑 5 个版本命令<br/>allowPathFallback=false"]
599
- E --> F{"5 个都跑通?"}
600
- F -->|是| G["什么都不用装:steps=[]、download.bytes=0、一句话收尾"]
601
- F -->|否| H["只列缺的包/步骤;已装的不动、也不升级"]
602
- D --> I["完整 7 步计划:下载 → 解压 → pacman → PATH → 配置 → 自检"]
603
- ```
604
-
605
- 两条原则:**计划模式绝不写盘**(只读 pacman query + 只读版本命令),**已经就位的东西不列**(用户明确提过:工具链完整时卡片不该再显示 43.1 MB)。
606
-
607
- ### 7.12 export:把工程打成 zip
608
-
609
- ```mermaid
610
- flowchart LR
611
- A["runExport{projectDir, outDir, includePrebuilt}"] --> B["collectSources:递归收集<br/>跳过 build / .dsh-stm32 / node_modules / .git"]
612
- B --> C{"includePrebuilt?"}
613
- C -->|是| D["带上 elf/hex/bin 到 prebuilt/"]
614
- C -->|否| E["只要源码"]
615
- D --> F["readmeText(可选内联 README)"]
616
- E --> F
617
- F --> G["makeZip:store-only(不压缩,零依赖)→ <name>-export.zip"]
618
- ```
619
-
620
- 为什么 zip 里一定没有 build/:CMakeCache 记着本机的绝对路径,带过去只会在别人机器上报错。所以导出的是「能重新配置的源码」,不是「能直接烧的构建目录」。
621
-
622
- ### 7.13 设置面板:浏览器 bundle 到宿主 API
623
-
624
- ```mermaid
625
- sequenceDiagram
626
- participant C as client/client.js(浏览器)
627
- participant S as 宿主 webServer
628
- participant R as engine/web-routes.ts
629
- participant A as engine/web-api.ts
630
- participant E as probe / msys2-install / toolchain-config
631
- C->>S: GET /dsh-stm32/api/config
632
- S->>R: handler(request, response)
633
- R->>A: handleWebApi({method, path, body})
634
- A->>E: configSnapshot / probeTools / installPlan
635
- E-->>A: 结果
636
- A-->>R: {status, body}
637
- R-->>C: JSON(cache-control: no-store)
638
- Note over C,A: 安装是长任务:install/start 返回 taskId,前端 setTimeout 递归轮询 install/state
639
- ```
640
-
641
- 三个契约:**路由全是 exact**(不抢别的前缀)、**请求体上限 1 MB**、**任务表在进程内**(宿主重启就丢,前端会显示「任务不存在」并允许重新发起)。前端只 require 外壳种子(react / jsx-runtime / primitives),不经打包器,因为宿主以 /plugins/dsh-stm32/client.js 直接提供。
642
-
643
- ### 7.14 斜杠命令:切词 → 门禁警告 → 调 engine
644
-
645
- ```mermaid
646
- flowchart LR
647
- A["/stm32-flash \"C:/Users/zhang san/proj\" --no-debug"] --> B["tokenizeCommandLine<br/>引号内不切、剥引号、记 quoted"]
648
- B --> C["parseInvocation:第一个非 flag token = 工程目录"]
649
- C --> D["commandGateWarning(capability, warn)<br/>缺件只警告不拒绝"]
650
- D --> E["engine(与工具同一个函数)"]
651
- E --> F["CommandResult{kind: success|error, text}"]
652
- ```
653
-
654
- 命令是「用户手打的快捷方式」,所以它的门禁是 warn:用户可能就想让插件跑起来看看报什么错。工具是「模型调的」,门禁才是 block。
655
-
656
- ## 8. 不变量与陷阱
657
-
658
- 这些条目破一条就会出真问题,改代码前先扫一眼。
659
-
660
- | # | 不变量 | 破了会怎样 | 在哪体现 |
661
- | --- | --- | --- | --- |
662
- | 1 | 代码只写在 USER CODE 块内 | 下次生成被无声覆盖,编译还不报错 | skill R1/R2、usercode-merge.ts |
663
- | 2 | .ioc 只能 plan → apply(带 planId) | 配置被手改后与 CubeMX 理解不一致 | skill R3、ioc-plan.ts |
664
- | 3 | 不许生成 No_Debug 的 SYS | SWD 永久失联,只能 BOOT0 救 | skill R4、flash.checkNoDebugGuard、ioc.summarizeIoc 警告 |
665
- | 4 | 覆盖文件前必须备份 | 用户代码丢失 | scaffold.backupBeforeOverwrite、ioc-plan、code-patch |
666
- | 5 | 编码认不出就拒绝写 | 中文注释变问号 | text-file.detectEncoding、code-patch、generate 的 skipped-encoding |
667
- | 6 | report 结构必须与 output.schema 一致 | 宿主判「工具返回非法输出」 | 每个 tools/*.ts、test/schema-guard.mjs |
668
- | 7 | 子进程必须显式 cwd + 注入 env | 新装的工具链找不到 | subprocess-runner.ts、tool-env.ts |
669
- | 8 | 动探针前先 releaseProbeFor | 两个 openocd 抢一个探针 | flash / regs / debug_run 入口 |
670
- | 9 | turn/end 必须把探针还回去 | 用户在 VS Code 里按 F5 失败 | src/index.ts |
671
- | 10 | 取消时不得写缓存 | 取消后仍走「已探测」假象 | toolchain-gate(A27) |
672
- | 11 | 长路径走 \\?\ 前缀 | 深目录复制 ENAMETOOLONG | fs-longpath.ts |
673
- | 12 | 解包走路径与类型白名单 | zip-slip / 设备文件写进系统 | tar.ts |
674
- | 13 | 缓存索引写入可恢复 | 半截索引导致缓存全废 | cache.ts(broken/bak + CacheIndexWriteError) |
675
- | 14 | 门禁快路径也要 smoke | 「文件在但跑不起来」被判齐全 | toolchain-gate(B13) |
676
- | 15 | 安装自检不许 PATH 兜底 | 用系统里的旧工具冒充新装 | probe 的 allowPathFallback=false |
677
- | 16 | 计划模式绝不写盘 | 用户以为只是看一眼,结果被改了 | msys2-install / firmware-install 的 plan 分支 |
678
- | 17 | 模板里不许出现开发机绝对路径 | 新工程 F5 直接失败 + 泄露用户名 | vscode-config.ts + templates/ |
679
- | 18 | 生成成功以产物为准,不以日志为准 | 缺包时误报成功 | generate.assessGenerateProducts |
680
- | 19 | 生成期间 pdsc 停放必须在 finally 还原 | 用户的第三方包索引「消失」 | thirdparty.ts + generate.ts |
681
- | 20 | 零运行时依赖、lib/ 入库 | 装上就坏 / 用户机器没有编译器 | package.json、tsconfig |
682
- | 21 | cmake 源清单必须跟着 startup 与 hal_conf 走 | 开了外设也链接失败(undefined reference to HAL_xxx_Init) | cmake-sources.refreshCubemxCmakeLists、generate.ts 两处调用 |
683
- | 22 | 链接脚本按 `<DeviceId>` 命名,命令行上只能有一个 `-T` | 链接的是别人的 MEMORY:编译过、烧到小容量芯片上跑飞(.ld 说 256 KiB,实际只有 64 KiB) | hal-chip.pointLinkerFlagAt、register-linker.renderLinkerScript、doctor.checkChipConsistency ①③ |
684
- | 23 | 寄存器名字只能来自 SVD,插件不许内置寄存器表 | 手写表必然过期:偏移错一位就解释错位域,比不给名字更糟 | data/svd.ts(严格解析 + 整份拒绝)、test/svd-units |
685
-
686
- ## 9. 测试体系
687
-
688
- ### 9.1 三层
689
-
690
- | 层 | 位置 | 说明 |
691
- | --- | --- | --- |
692
- | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 41 个套件 654 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
693
- | e2e 脚本 | test/e2e-*.mjs(15 个) | 开发期手动跑的端到端(真 CubeMX / 真 openocd / 真工具链),不进 npm test |
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 上两连跑 |
695
-
696
- ### 9.2 41 个套件一览(test/run-units.mjs 的 suites 数组顺序)
697
-
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。
699
-
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。
701
-
702
- 约定:
703
- - 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
704
- - run-units 用 DSH_STM32_NO_CONFIG=1 跑子进程,避免开发机上真实的 ~/.dsh-stm32/config.json 影响断言。
705
- - 输出解析认四种结尾(node:test spec / tap / 自写 tests N / fail M / inline);解析不到用例数会标红,而不是默默算 0。
706
- - 套件退出码非 0 一律算失败,即使它自己打印 fail=0。
707
- - 加套件必须手改 test/run-units.mjs 的 suites 数组——没有自动发现。
708
-
709
- ### 9.3 单测的两种假件套路
710
-
711
- ```ts
712
- // 套路一:假 subprocess —— 按命令内容返回脚本化输出
713
- const fake = {
714
- async resolveExecutable(cmd) { return cmd; },
715
- spawn(spec) { /* 按 spec.argv 决定往 stdout 写什么 */ },
716
- };
717
-
718
- // 套路二:假 fs / 临时目录 —— 真写盘到 os.tmpdir(),测量真实的备份、编码、原子替换
719
- ```
720
-
721
- 凡是「决定行为的分支」都要有脚本化的输出样本,样本**必须是上游真实格式**(审计期间踩过:按文件名猜 CMSIS 守卫宏,测的是假世界)。
722
-
723
- ## 10. 要改东西时动哪里
724
-
725
- | 想做的事 | 动这些文件 | 别忘了 |
726
- | --- | --- | --- |
727
- | 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
728
- | 改报告字段 | src/tools/<x>.ts 的 reportSchema + 渲染 | schema-guard 必须有对应断言 |
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 一致性 |
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」「超限一个键都不写」;派生键必须全量重算 |
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/`,与内置资源同构 |
733
- | 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
734
- | 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
735
- | 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
736
- | 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
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 |
738
- | 改 cmake 源清单的认法(设备宏、startup、HAL 模块) | engine/cmake-sources.ts 的 `collectCmakeSources` / `halModulesInUse` | 注释掉的 `#define` 与 `#include` 不能算启用;内容没变必须零写入(cmake-sources-units 15 例兜这两条) |
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) |
740
- | 改寄存器写法的解析或位域解释 | `src/data/svd.ts`(符号解析 / 反向查 / 解码)+ `src/tools/regs.ts`(五种写法、去重、dump、渲染、建议文案) | `svd-units` 39 例兜着;夹具在 `test/fixtures/svd/`(flat / versioned / badline 三种布局);改渲染要同步两份 README 与 development-notes §31 |
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,升级后自动失效 |
742
- | 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
743
-
744
- ## 11. 已知的坑与未做的事
745
-
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 改字母。
747
- 2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
748
- 3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
749
- 4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
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 个文件。
752
- 7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
753
- 8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
754
- 9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
755
- 10. **裸 `cmake -S . -B build` 会丢工具链文件**:工具链只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不走 preset 就得自己给 `-DCMAKE_TOOLCHAIN_FILE`,否则 configure 用宿主 gcc、链接时找不到启动文件。
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 时才退回文件大小并注明是粗算。
757
- 12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
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`。
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
- | TypeScript | 110 个文件、42,261 行(`src/`,不含 client) |
823
- | `src/tools/` | 24 个文件 / 25 个注册工具 / 7,583 行 |
824
- | `src/engine/` | 65 个 `.ts` / 26,358 行 |
825
- | `src/data/` | 17 个 `.ts` / 7,625 行 |
826
- | 单测 | 61 个套件 / 923 pass / 0 fail(`node test/run-units.mjs`,本机实测) |
827
-
828
- 第 1–11 章的目录表与模块计数保留 D 阶段原样(45 个 engine 模块、23 个 tools 文件),读旧章节时以本节为准。
829
-
830
- ## 14. 0.1.6 增补:宿主 schema 子集与 `pins` / `parameters` 数组化
831
-
832
- > 接续 §13,同属 0.1.6。这一节不改业务行为,只让 25 个工具的 schema 落进 DSH 0.2.2-rc.1 允许的子集。
833
-
834
- ### 14.1 先读哪里
835
-
836
- - `src/types.ts` 的 `JsonSchema`:现在就是宿主子集本身——`type` / `oneOf` / `properties` / `required` / `additionalProperties`(仅 boolean)/ `items` / `enum` / `const` + 注解 `description` / `title` / `default` / `examples`。`minimum` / `maximum` 已删除,看到需要范围时去 `description` 和执行期校验里找。
837
- - `src/tools/ioc-plan.ts` 的 `parameters`:`peripherals[].pins` / `parameters` 是 `type:"array"` + `items:{key,value}`,`pllMul` 是 `integer` + `enum[2..16]`。
838
- - `src/engine/ioc-plan.ts` 的 `KeyValuePair` 与 `keyValueMap()`:数组 → `Map` 的唯一入口,空 key / 重复 key 在这里记 `errors`。
839
- - `src/engine/serial.ts` 的 `SERIAL_SETTINGS_PROPERTIES`:参数 schema 与输出 `settings` schema 复用同一片段,范围只在 `description` 里;真正的越界判定在 `src/data/serial-config.ts` 的 `normalizeSerialSettings`。
840
- - `test/schema-subset-units.test.mjs`:镜像校验器 + 从 `app.asar` 抽真校验器做真值对齐。改任何工具的 schema 后先跑它。
841
-
842
- ### 14.2 三条不变量
843
-
844
- 1. 任何 schema 节点只出现子集关键字;`additionalProperties` 只能是 boolean,`items` 只在数组上,`properties`/`required` 只在对象上。
845
- 2. 数值范围**不进 schema**:写 `description`,并在执行期校验(`keep`:非法即 `ok=false` 且不动文件;串口:`normalizeSerialSettings` 记 errors 并保持默认值)。
846
- 3. 「任意键 → 值」的映射不允许再写成 `additionalProperties: {…}`;要么换成 `[{key,value}]` 数组,要么用 `additionalProperties: true` 兜底。
847
-
848
- ### 14.3 计数口径(0.1.6 起)
849
-
850
- | 项 | 当前值 |
851
- | --- | --- |
852
- | 注册工具 | 25 个(25/25 schema 合规) |
853
- | 单测 | 61 个套件 / 923 pass / 0 fail |
854
-
855
- 本机同基线实测为 921,加 2 条新用例后 923;§13.5 表里原有的 937 是另一台机器的发布记录。
856
-
857
- ---
858
-
859
- 读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
1
+ # dsh-stm32 源码精读指南
2
+
3
+ > 面向:第一次读这个仓库、并且要改它的人。
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
+ > 读完这份指南你应该能回答:一次工具调用从宿主进来到 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(26 个文件:34 个工具 + 1 个基础设施;一个文件可注册多个工具) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
+ | L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
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
+
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/>28 个工具"]
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/>65 个纯逻辑模块"]
53
+ CMDS --> ENGINE
54
+ WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
55
+ API --> ENGINE
56
+ ENGINE --> DATA["src/data/*<br/>10 个数据模块(芯片事实读包内 assets/;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/ | 25 | 9027 | 28 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 serial.ts 868 行,其次是 regs.ts 735 行、schematic.ts 630 行、route-plan.ts 576 行 |
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
+ | 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/ | 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
+
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) 里按「先探测、再操作」的顺序注册 28 个工具**: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 → schematic → rtt → watch → assets → cache → doctor → serial → 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 层:28 个工具 + 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 28 个工具一览
194
+
195
+ | 工具 | 文件(行) | engine 入口 | 门禁能力 |
196
+ | --- | --- | --- | --- |
197
+ | `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
198
+ | `stm32_download` | download.ts(300) | download.planDownload / downloadUrlToFile / sha256File / inspectInstallerFile | 无(只下载与校验,绝不执行安装器) |
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_ioc_verify` | ioc-verify.ts(246) | ioc-verify.runIocVerify(CubeMX 无头 load→save 回读对比) | generate(CubeMX + JRE) |
208
+ | `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
209
+ | `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
210
+ | `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
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 需要会话) |
213
+ | `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
214
+ | `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
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) | 无 |
217
+ | `stm32_cache` | cache.ts(306) | engine/cache 全套 | 无 |
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`,不起桥) |
220
+ | —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
221
+
222
+ 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**serial.ts 829 行**现在是 tools 层最大的,**regs.ts 735 行**次之(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**第三——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
223
+
224
+ ## 5. engine 层:D 阶段的 45 个模块,十个域(现 65 个 .ts)
225
+
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` 一起看。
227
+
228
+ ### 5.1 进程与路径(3 个,413 行)
229
+
230
+ | 模块 | 职责与关键导出 |
231
+ | --- | --- |
232
+ | 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。 |
233
+ | tool-env.ts(56) | `envWithBinDirs(binDirs, base)`:binDirs 去重去空后**拼在原 PATH 前面**,Windows 上只留一个大小写正确的 `Path` 键;`toolSearchDirs(binDirs, base)` 给出「去哪找可执行文件」的有序目录表。 |
234
+ | fs-longpath.ts(107) | 长路径工具。`toLongPath` 加 `\\?\` 前缀、`existsLong`、`mkdirTrackedLong`(顺手记下新建的目录,失败时回收)、`copyFileLong`、`copyTreeLong`、`describeCopyFailure`。固件包的 Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc 这种深度在长用户名下会撞 MAX_PATH(审计 B17)。 |
235
+
236
+ ### 5.2 探测、搜索与门禁(engine 2 个 + data 2 个,1649 行)
237
+
238
+ | 模块 | 职责与关键导出 |
239
+ | --- | --- |
240
+ | 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 个探测目标)。 |
241
+ | 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)。 |
242
+ | 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`。 |
243
+ | 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`。 |
244
+
245
+ ### 5.3 构建与产物(2 个,543 行)
246
+
247
+ | 模块 | 职责与关键导出 |
248
+ | --- | --- |
249
+ | 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`。 |
250
+ | 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/。 |
251
+
252
+ ### 5.4 烧录、调试与诊断(9 个,4087 行)
253
+
254
+ | 模块 | 职责与关键导出 |
255
+ | --- | --- |
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 不会再各写一套漂移。 |
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 三元组。 |
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(...)`。 |
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` 是什么。 |
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 三条路径共用同一份规则。 |
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。 |
263
+ | 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 超时 / 帧失步)只此一份。 |
264
+ | 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 **之前**就失败,不碰探针、也不关已有会话。 |
265
+ | 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 的那个)。 |
266
+
267
+ ### 5.5 生成、编码、.ioc 事务与时钟(10 个,3657 行)
268
+
269
+ | 模块 | 职责与关键导出 |
270
+ | --- | --- |
271
+ | 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。 |
272
+ | generate-script.ts(115) | `buildGenerateScript` 拼脚本(setCustomFWPath / SetCopyLibrary / ProjectManager 项)、`layoutCommand`、`parseGenerateLog`:UNKNOWN_COMMAND 先判;成功行不再「一票否决」错误(审计 A10)——CubeMX 缺包时也会打 Code successfully generated,所以 ok 由产物判据决定。 |
273
+ | generate-cache.ts(168) | 生成缓存。`CACHE_FILE = "generate-cache.json"`、`sha256Text` / `sha256File`、`cubeMxStamp`、`computeCacheKey(iocSha, stamp, layout)`、`readCache` / `writeCache`、`cacheHit(entry, key, projectDir)`(key 命中还不够,文件 hash 也得对得上)。 |
274
+ | usercode-merge.ts(142) | `parseUserCodeRegions` / `mergeUserCode` / `canMergeUserCode`:把旧文件 USER CODE 块里的内容搬进新生成的文件,保留 CRLF 风格,标出 droppedLabels。 |
275
+ | code-patch.ts(215) | `patchUserCode`:只改一个 USER CODE 块(replace / append),块内出现 `{` 或 `}` 拒绝(结构行守卫),写前备份,写回**按字节拼接**(见 text-file)。`listUserCodeLabels` 列出可用标签。 |
276
+ | text-file.ts(172) | 编码层。`detectEncoding`(BOM → utf8-bom;空 → utf8;严格 UTF-8 成 → utf8;再试 gb18030;否则 unknown)、`decodeText`、`encodeText`(gb18030 只允许纯 ASCII——Node 只有解码器没有编码器)、`readTextFile`、`lineStarts`、`replaceLineRange`(未改的行原字节照抄,只把新增行按原编码插入)。**这是「中文注释不被写坏」的唯一保障**。 |
277
+ | ioc.ts(202) | .ioc 只读解析:`parseIocEntries`、`decodeIocValue`、`summarizeIoc`(MCU、时钟树、引脚、外设、调试口、工程设置、警告)。 |
278
+ | ioc-plan.ts(612) | .ioc 事务。`planIocChanges` 算出逐键 diff + 源 SHA-256 → planId;`applyIocPlan` 校验 SHA 后原子替换(备份到 backups/<stamp>-ioc);`rollbackIoc(backupFrom)` 回滚;辅助 `renderIocText`、`compareEntries`、`sha256Hex`、`encodeIocValue`、`loadPlan`。引脚写入保序(审计 A3):只追加新增,不因缺 .Signal 删已有项。 |
279
+ | 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。 |
280
+ | 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。 |
281
+
282
+ ### 5.6 造工程、链接脚本与导出(8 个,2224 行)
283
+
284
+ | 模块 | 职责与关键导出 |
285
+ | --- | --- |
286
+ | 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 在**写盘之前**渲染成字符串,渲染失败时一个字节都不写。 |
287
+ | 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)。全是字符串函数,所以能先渲染后落盘。 |
288
+ | register-template.ts(584) | 寄存器路线(不碰 CubeMX)。`resolveStartupChoice`(按型号/族选启动文件与宏)、`ensureCmsisTemplate`(从镜像下载 10 个文件到缓存并校验 sha256)、`createRegisterProject`(拷模板 → 写设备头/启动文件/链接脚本 → 生成 main.c)。模板文件缺失分「必需」与「可选」(.gitignore 是可选,缺了给 warning 不阻断)。模板里已不写死任何型号:启动文件、设备宏、设备头、`.ld`、时钟全部按 `resolveF1Chip` 的结果参数化(14 个容量档)。 |
289
+ | 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 跟着对。 |
290
+ | register-linker.ts(152) | 寄存器版的链接脚本渲染:按型号换掉 `<DeviceId>_FLASH.ld` 的 MEMORY RAM/FLASH 两行。F100/F101/F102 的 RAM 不在 src/data/stm32f1.ts 的表里,用 CubeMX db 的最小值兜底**并明确警告**(宁可小——栈必须留在真 RAM 内)。 |
291
+ | vscode-config.ts(118) | `VSCODE_PLACEHOLDERS`(gdb / toolchain / cmake / svd 四个占位符)、`detectVscodeFill`(按本机探测结果填)、`fillVscodeTemplate`(没值的整行删掉并记 dropped,绝不写空串)、`describeDroppedPlaceholder`。模板里因此不出现任何开发机绝对路径(审计 B1)。 |
292
+ | project-export.ts(155) | `runExport`:收集源文件(跳过 build / .dsh-stm32 / node_modules / .git)→ 可选带 prebuilt(elf/hex/bin)→ 可选内联 README → 打 zip。 |
293
+ | zip.ts(152) | 自写的最小 store-only zip(不压缩、不引依赖):`crc32`、`makeZip`、`listZipEntries`(测试用来验内容)。 |
294
+
295
+ ### 5.7 下载、缓存与固件包(7 个,2502 行)
296
+
297
+ | 模块 | 职责与关键导出 |
298
+ | --- | --- |
299
+ | 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)`,否则半成品会长期躺在缓存目录里等着占满磁盘。 |
300
+ | 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`。 |
301
+ | tar.ts(288) | `extractTarGz(archive, destRoot, options)`:解 gzip + tar,路径白名单(`isSafeRelative` 拒反斜杠、冒号、.. 与空段)、类型白名单(`entryKind`:0/空/5 正常,x/g/L/K 元数据,其余跳过并记名,审计 A4)、声明长度超出实际数据判截断整次失败。 |
302
+ | 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 也能找到非标准落点。 |
303
+ | thirdparty.ts(281) | 生成期间临时停放 CubeMX 的第三方包索引(`PARKED_NAME = "pdsc.dsh-parked"`、`needsThirdpartyPacks`、`parkThirdpartyDb`),有 X-CUBE 包的工程保持原样;`cubeMxUserHome`。 |
304
+ | xcube.ts(293) | X-CUBE 包识别:`identifyPackId`、`parsePdscNames`、`listInstalledPacks`、`scanIocPacks`、`summarizePacks`。 |
305
+ | xcube-catalog.ts(117) | 由 scripts/gen-xcube-catalog.mjs 生成的包目录(159 条)。`XCUBE_CATALOG_ENTRY_COUNT = XCUBE_PACK_CATALOG.length`(审计 A23:不要把条目数写成数字常量,重跑脚本会回写旧值)。 |
306
+
307
+ ### 5.8 工具链安装(1 个,2313 行)
308
+
309
+ | 模块 | 职责与关键导出 |
310
+ | --- | --- |
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`。 |
312
+
313
+ ### 5.9 设置面板的宿主侧(2 个,577 行)
314
+
315
+ | 模块 | 职责与关键导出 |
316
+ | --- | --- |
317
+ | 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`。 |
318
+ | web-routes.ts(100) | 薄适配层:`ctx.inject(["webServer"], ...)` 里 `server.register({ kind: "exact", path, handler })`,把 request/response 收成 `handleWebApi` 的输入输出,加 `cache-control: no-store`。宿主没 webServer 服务时静默跳过(面板不可用,工具照常)。 |
319
+
320
+ ### 5.10 路线评估(1 个,645 行)
321
+
322
+ | 模块 | 职责与关键导出 |
323
+ | --- | --- |
324
+ | route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
325
+
326
+ ## 6. data 层:10 个数据模块(3599 行;芯片事实来自包内 assets/)
327
+
328
+ | 模块 | 行数 | 内容 |
329
+ | --- | --- | --- |
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 就明说「引脚存在性不校验」,绝不拿内置表冒充)。 |
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 真实下载实测的。 |
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 没有这一容量档。 |
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 名单。 |
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`。 |
335
+ | install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
336
+ | search-roots.ts | 421 | 见 5.2。 |
337
+ | toolchain-config.ts | 370 | 见 5.2。 |
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` 给单测证明命中不重复读盘。只读:不写盘、不联网、不起进程。 |
340
+
341
+ ## 7. 关键流程
342
+
343
+ 这一章是全书重点:每个流程都给「一张图 + 几个必须知道的失败面」。看图时对照第 5 章的模块表找文件。
344
+
345
+ ### 7.1 一次工具调用的通用管线
346
+
347
+ ```mermaid
348
+ sequenceDiagram
349
+ participant U as 模型/用户
350
+ participant H as DSH 宿主
351
+ participant T as src/tools/x.ts
352
+ participant E as src/engine
353
+ participant S as 宿主 subprocess
354
+ participant B as gcc/cmake/openocd/CubeMX
355
+ U->>H: 调工具 + JSON 参数
356
+ H->>T: execute(args, exec)
357
+ T->>T: resolveProjectDir + validateToolArgs
358
+ T->>E: ensureToolchain(capability, envCheck)
359
+ E-->>T: GateResult{ok, missing[], install[]}
360
+ alt 门禁拦截
361
+ T-->>H: blockedReport 同形报告
362
+ else 门禁通过
363
+ T->>E: run*(subprocess, request)
364
+ E->>S: spawn{argv, cwd, env, stdio.maxBytes}
365
+ S->>B: 真进程
366
+ B-->>S: stdout/stderr + exitCode
367
+ S-->>E: RunOutcome
368
+ E-->>T: Report
369
+ T->>T: render(report) → 中文行
370
+ T-->>H: report(必须过 output.schema)
371
+ end
372
+ ```
373
+
374
+ 必须知道的失败面:
375
+ - **输出 schema 是硬约束**:report 多一个没声明的字段,宿主就判「非法输出」。改 report 必改 schema,并用 test/schema-guard.mjs 兜住。
376
+ - **exec.signal 一路要透传**:工具超时/用户取消 → spawn 被 abort → RunOutcome.aborted=true → report 里写「已取消」。任何一格没接 signal,取消就变成「等 30 秒超时」。
377
+ - **门禁在工具层**:engine 不知道门禁存在,所以 engine 的返回永远按「工具链就位」写文案。
378
+
379
+ ### 7.2 工具链门禁:快路径、慢路径与缓存
380
+
381
+ ```mermaid
382
+ flowchart TD
383
+ A["ensureToolchain(capability, envCheck)"] --> B{"envCheck = off?"}
384
+ B -->|是| PASS["ok=true 直接放行"]
385
+ B -->|否| C["CAPABILITY_COMPONENTS 列必需组件"]
386
+ C --> D{"快路径:binDirs 里文件都在?"}
387
+ D -->|是| E["smokeTarget:跑一次主组件的版本命令<br/>build→gcc flash→openocd debug→gdb generate→cubemx-java<br/>60 s 缓存"]
388
+ E -->|跑通| PASS
389
+ E -->|失败| F["按缺件处理,error 写「文件在但版本命令没跑通」"]
390
+ D -->|否| G["慢路径:probeAll 全量探测<br/>allowPathFallback 默认开"]
391
+ G --> H{"signal.aborted?"}
392
+ H -->|是| I["break:不写缓存(审计 A27)"]
393
+ H -->|否| J["probeCache.set(key, {at, results}) 60 s"]
394
+ J --> K{"有缺件?"}
395
+ F --> K
396
+ K -->|无| PASS
397
+ K -->|有| L{"envCheck = warn?"}
398
+ L -->|是| M["ok=true + warnings 一行"]
399
+ L -->|否| N["ok=false + missing[](含 hint/impact/install/verify)"]
400
+ ```
401
+
402
+ 为什么快路径也要跑版本命令(审计 B13):「文件存在」不等于「文件能跑」——半截下载、被杀软隔离、架构不对、0 字节,都表现为文件在而进程起不来。只对**主组件**做 smoke,是为了保住快路径「零全量 spawn」的价值;其余组件坏了慢路径照样兜住。
403
+
404
+ ### 7.3 project_create:两条完全不同的路线
405
+
406
+ ```mermaid
407
+ flowchart TD
408
+ A["stm32_project_create{targetDir, projectName, route}"] --> P["preflightTarget:<br/>1 工程名是 C 标识符<br/>2 目录非空 → 拒绝<br/>3 hal 且已有同名 .ioc → 拒绝并指向 ioc_plan/apply"]
409
+ P --> R{"route?"}
410
+ R -->|register| S1["ensureCmsisTemplate:<br/>按型号选启动文件 → 下载 10 个文件 → sha256 校验 → 落缓存"]
411
+ S1 --> S2["createRegisterProject:<br/>拷模板 7 件(含 .gitignore、openocd.cfg、链接脚本)<br/>写设备头/启动文件/system.c/main.c"]
412
+ S2 --> S3["模板缺失分流:必需 → 一次列全并拒绝<br/>可选(.gitignore) → warning 继续"]
413
+ R -->|hal| H1["resolveFirmwareRoot:Repository → dsh-firmware → extraDirs<br/>找不到就带安装指引失败"]
414
+ H1 --> H2["backupBeforeOverwrite:只备份真会被覆盖的文件<br/>备份失败 → 一字不写"]
415
+ H2 --> H3["createProjectScaffold:拷 15 个模板 + 从固件包拷 Drivers/238 件<br/>复制走 fs-longpath"]
416
+ H3 --> H4["写 .vscode/:按本机探测填占位符,没值的整行删掉并记 warning"]
417
+ S3 --> DONE["报告:templateFiles / driverFiles / firmwareRoot / warnings"]
418
+ H4 --> DONE
419
+ DONE --> FAIL{"中途失败?"}
420
+ FAIL -->|是| CL["cleanupAfterFailure:只回收本次新建<br/>原有目录只 rmdir 空目录"]
421
+ ```
422
+
423
+ 两条路线的共同点只有「先预检、再备份、失败回收」。区别是 hal 依赖 CubeMX 固件包(无网也能用整目录拷贝),register 依赖网络下载 CMSIS(但缓存命中后完全离线)。
424
+
425
+ ### 7.4 build:preset → 编译 → 产物
426
+
427
+ ```mermaid
428
+ flowchart LR
429
+ A["runBuild"] --> B["pickConfigurePreset<br/>优先 Debug"]
430
+ B --> C["cmake --preset=<name><br/>env 注入 binDirs + 原 PATH"]
431
+ C --> D["cmake --build --preset=<name>"]
432
+ D --> E["findElf → pickElf:CMakeCache 工程名优先<br/>否则取 mtime 最新的 .elf;elfSelectionNote 进 notes"]
433
+ E --> F["parseMemoryUsage / parseBuildErrors / countWarnings"]
434
+ F --> G{"artifacts 里要 hex/bin?"}
435
+ G -->|是| H["arm-none-eabi-objcopy -O ihex / binary<br/>失败只写 note,不判 build 失败"]
436
+ G -->|否| I["报告"]
437
+ H --> I
438
+ ```
439
+
440
+ 选哪个 .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 都会带这条说明。
441
+
442
+ 坑:**复制过的工程**(CMakeCache 里记着别的路径)会报奇怪的错,build.ts 里有显式拦截:检测到 CMakeCache 的源目录与当前工程不一致就直接给「把 build/ 删掉重配」。
443
+
444
+ ### 7.5 flash:守卫 → 烧录 → 判定 → 错误分类
445
+
446
+ ```mermaid
447
+ flowchart TD
448
+ A["stm32_flash"] --> B["releaseProbeFor:先还探针(审计 B16)"]
449
+ B --> C["checkNoDebugGuard(projectDir, allowNoDebug, iocPath)"]
450
+ C --> C1{"有唯一 .ioc?"}
451
+ C1 -->|有| C2["PA13=SYS_JTMS-SWDIO / PA14=SYS_JTCK-SWCLK / Mode=Serial_Wire?"]
452
+ C1 -->|没有或多个| C3["看 openocd.cfg 的 transport:swd 放行并说明依据<br/>jtag 提示引脚复用<br/>都没有 → notes 两条「守卫没生效」"]
453
+ C2 -->|是 No_Debug| BLOCK["blocked:拒绝,除非 allowNoDebug"]
454
+ C2 -->|是 Serial Wire| D["resolveElf(内部 findElf → pickElf,notes 说明选中的是哪个)"]
455
+ C3 --> D
456
+ D --> E["findProjectConfig:openocd.cfg 优先<br/>否则 interface/cmsis-dap.cfg + target/stm32f1x.cfg"]
457
+ E --> F["openocd -f ... -c program <elf> verify reset exit"]
458
+ F --> G["parseFlashLog:认 Programming Finished / Verified OK<br/>成功序列里的偶发 Error 行进 noise"]
459
+ G --> H{"ok?"}
460
+ H -->|是| OK["programmed + verified,probeError 缺省(成功时字段根本不出现)"]
461
+ H -->|否| I["classifyProbeFailure 分 8 类:no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / timeout / unknown"]
462
+ I --> J["notes:USB 形态(usbNoteFor)+ probe-busy 专用提示(HINT_BUSY)"]
463
+ ```
464
+
465
+ 真板子取证过的一个细节:两个进程同时访问同一个 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/`)。
466
+
467
+ ### 7.6 调试三件套与会话租约
468
+
469
+ ```mermaid
470
+ stateDiagram-v2
471
+ [*] --> 空闲
472
+ 空闲 --> 启动中: stm32_debug_session(start)
473
+ 启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
474
+ 启动中 --> 空闲: 端口占用 / 探针失败、带 probeError(kind / cause / hint)
475
+ 活跃 --> 活跃: stm32_debug_eval、优先常驻 MI(连不上才每次新起 gdb -batch:连上 → halt → 命令 → resume → detach)
476
+ 活跃 --> 空闲: stm32_debug_stop
477
+ 活跃 --> 空闲: 空闲 90 s
478
+ 活跃 --> 空闲: 总时长 10 min
479
+ 活跃 --> 空闲: turn/end、本轮输出结束
480
+ 活跃 --> 空闲: session/disposed / 插件 dispose
481
+ ```
482
+
483
+ 三条设计理由:
484
+ 1. **只有 openocd 常驻**,gdb 每次短命——gdb 崩了不会把会话带死,也避免 gdb 自己攒一堆状态。
485
+ 2. **归属(A9)**:turn/end 事件里尽量掏 agent id,只关这条会话自己开的;掏不到就全关(宁可按最短释放,也不攥着探针)。
486
+ 3. **别人要用探针先 releaseProbeFor**:flash / debug_run 在自己起 openocd 之前调它,否则就是「两个 openocd 抢一个 CMSIS-DAP」。**regs_read 是例外(B3 起)**:它反过来复用会话里的那个 openocd,连读时不再一读一起一停。
487
+
488
+ 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 即可复测。
489
+
490
+ B4 的断点预算在同一条 execute 里先算(`resolveBreakpointBudget` 读 .ioc 的 Mcu.CPN → chips.json 的 breakpoints/watchpoints,缺就按 F1 默认 6 硬件断点 / 4 观察点并说明原因),超限在 spawn openocd **之前**就失败——不占探针、也不关你正开着的会话;报告里 `breakpoints` / `watchpoints` 各是 `{used, limit, remaining}`。
491
+
492
+ **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。
493
+
494
+ 报告里的 `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 那次「失败路径被判非法输出」。
495
+
496
+ ### 7.7 .ioc 事务:plan → 用户确认 → apply / rollback
497
+
498
+ ```mermaid
499
+ sequenceDiagram
500
+ participant M as 模型
501
+ participant P as stm32_ioc_plan
502
+ participant A as stm32_ioc_apply
503
+ participant F as demo.ioc
504
+ M->>P: entries / unset / pins / serialWire
505
+ P->>F: 只读解析 + 逐键 diff
506
+ P-->>M: planId + sourceSha256 + changes[](不写盘)
507
+ M->>M: 决定要不要动(用户确认)
508
+ M->>A: {planId}
509
+ A->>F: 重新算 SHA-256 并比对
510
+ alt SHA 变了
511
+ A-->>M: 拒绝:源文件已被改过,重新 plan
512
+ else SHA 一致
513
+ A->>F: 备份到 .dsh-stm32/backups/<stamp>-ioc
514
+ A->>F: 原子替换(写 tmp → rename)
515
+ A-->>M: appliedChanges + backupPath
516
+ end
517
+ M->>A: {rollbackFrom: backupPath}
518
+ A->>F: 先备份当前内容,再写回备份
519
+ A-->>M: rolledBack=true
520
+ ```
521
+
522
+ .ioc 是唯一的「配置真相」,所以它有三重保护:**不写盘的计划阶段**、**SHA 校验**、**每次写前都备份**。引脚写入保序(审计 A3)也是为这条服务的:无意义的顺序抖动会让 diff 看起来像改了很多东西。
523
+
524
+ ### 7.8 generate:CubeMX 无头模式的全流程
525
+
526
+ ```mermaid
527
+ flowchart TD
528
+ A["runGenerate"] --> B["findIocFile:只认唯一 .ioc"]
529
+ B --> C["acquireLock:lock.json{pid, startedAt, purpose}<br/>isProcessAlive 探活,30 min 兜底"]
530
+ C --> D["固件包定位:Repository → dsh-firmware → extraDirs<br/>同时算出 firmwareSource"]
531
+ D --> E["detectLayout:coupled / per-ip"]
532
+ E --> F["cacheKey = sha256(.ioc) + cubeMxStamp(java,jar) + layout"]
533
+ F --> G{"缓存命中且文件 hash 全对?"}
534
+ G -->|是| Z["直接复用上次产物(skipped=true)"]
535
+ G -->|否| H["thirdparty:无 X-CUBE 包时临时停放 pdsc 索引(省约 25 s)"]
536
+ H --> I["写 CubeMX 脚本到 .dsh-stm32/tmp/gen-<stamp>.txt<br/>-Dfile.encoding=UTF-8 + setCustomFWPath"]
537
+ I --> J["java -jar STM32CubeMX.exe -q <script>"]
538
+ J --> K["parseGenerateLog:UNKNOWN_COMMAND → commandErrors<br/>成功行不再一票否决错误"]
539
+ K --> L["恢复 pdsc 索引(finally)"]
540
+ L --> M["搬产物:.dsh-stm32/gen/Src|Inc → Core/Src|Inc<br/>旧文件先读编码 → 认不出就 skipped-encoding<br/>能读就 mergeUserCode 保 USER CODE"]
541
+ M --> N["assessGenerateProducts:产物判据决定 ok<br/>(CubeMX 缺包时也会打 successfully generated)"]
542
+ N --> O["写 generate-cache(key + 每个文件 sha256)"]
543
+ O --> P["refreshCubemxCmakeLists:源清单跟着 startup / hal_conf 走<br/>设备宏、startup、HAL 模块清单三块;内容没变不写盘"]
544
+ Z --> P2["缓存命中分支同样调一次 refresh"]
545
+ P --> R["releaseLock(rm lock.json)"]
546
+ P2 --> R
547
+ ```
548
+
549
+ 四个坑:
550
+ - **源清单不会自己长**: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,带真工具链差分验证)。
551
+ - **锁的探活**:早期只看 pid+时间,进程崩了要等 30 分钟;现在先 isProcessAlive(pid),死了立刻接管(审计 A14)。
552
+ - **成功日志不等于成功**:CubeMX 缺固件包/包版本不认时也打 Code successfully generated,所以 ok 必须有产物判据(审计 A10)。
553
+ - **中文路径**:脚本按 UTF-8 写且启动 java 时指定 -Dfile.encoding=UTF-8(审计 B18);否则中文工程路径在脚本里变乱码。
554
+
555
+ ### 7.9 code_patch:只改块内,按字节写回
556
+
557
+ ```mermaid
558
+ flowchart TD
559
+ A["patchUserCode{file, block, code, mode}"] --> B["读成 Buffer(不按 utf8 直读)"]
560
+ B --> C["detectEncoding:BOM/严格 UTF-8/GB18030<br/>unknown → 拒绝,一个字节都不动"]
561
+ C --> D["定位块:正则认 USER CODE BEGIN/END 标记"]
562
+ D --> E{"块内含 { 或 }?"}
563
+ E -->|是| X["拒绝:那是结构行,不许塞代码"]
564
+ E -->|否| F["lineStarts 算出块的起止行"]
565
+ F --> G["replaceLineRange:未改的行原字节照抄<br/>只把新增行按原编码插入,保留 CRLF/LF"]
566
+ G --> H{"结果与原文相同?"}
567
+ H -->|是| Y["回一句「内容没有变化」"]
568
+ H -->|否| I["备份到 .dsh-stm32/backups/<stamp>-patch"]
569
+ I --> J["写 tmp → rename(原子)"]
570
+ ```
571
+
572
+ 为什么要字节级拼接而不是「读成字符串再写回」:GB18030 的文件 Node 能解不能编,整份重新编码会把用户的中文注释写成问号。现在的策略是「动的只有块内那几行,其余字节原样搬运」。
573
+
574
+ ### 7.10 firmware_install:选址、下载、组装、记录
575
+
576
+ ```mermaid
577
+ flowchart TD
578
+ A["firmwarePlanFor{family, mcu, version}"] --> B["选址 decideTarget:<br/>已有包? → existing<br/>CubeMX 目录可用? → <root>/dsh-firmware<br/>否则 cache/custom"]
579
+ B --> C{"受保护目录?<br/>Program Files / ProgramData / SystemRoot"}
580
+ C -->|是| X["判不可写,给下一步建议"]
581
+ C -->|否| D["download:2 个归档 + 5 个内核头<br/>每个都过 sha256"]
582
+ D --> E["extractTarGz:路径白名单 + 类型白名单 + 截断检测"]
583
+ E --> F["补 package.xml(版本 tag)"]
584
+ F --> G["verifyFirmwarePackage:Drivers/CMSIS、startup、hal 源都在?"]
585
+ G --> H["写 installed.json 记录(targetDir + 版本 + 时间)"]
586
+ H --> I["nextStep:告诉用户接下来 stm32_project_create 还是 stm32_generate"]
587
+ ```
588
+
589
+ 为什么装到 <CubeMX>/dsh-firmware 而不是塞进官方 Repository:CubeMX 会静默忽略自造版本号的包;真正生效的是生成脚本里的 project setCustomFWPath。所以「包放哪」和「CubeMX 认不认」是两件事——这一点写在 docs/development-notes.md §14.1。
590
+
591
+ ### 7.11 env_install 的计划模式:只报缺件
592
+
593
+ ```mermaid
594
+ flowchart TD
595
+ A["stm32_env_install{mode=plan}"] --> B["isMsys2Root(msys64):有 usr/bin/bash.exe 且 pacman 在?"]
596
+ B -->|是| C["只读问 pacman:pacman -Q <5 个包><br/>超时 60 s,问不出来就不编清单"]
597
+ B -->|否| D["按全新安装估算(43.1 MB 下载)"]
598
+ C --> E["在目标 binDir 里跑 5 个版本命令<br/>allowPathFallback=false"]
599
+ E --> F{"5 个都跑通?"}
600
+ F -->|是| G["什么都不用装:steps=[]、download.bytes=0、一句话收尾"]
601
+ F -->|否| H["只列缺的包/步骤;已装的不动、也不升级"]
602
+ D --> I["完整 7 步计划:下载 → 解压 → pacman → PATH → 配置 → 自检"]
603
+ ```
604
+
605
+ 两条原则:**计划模式绝不写盘**(只读 pacman query + 只读版本命令),**已经就位的东西不列**(用户明确提过:工具链完整时卡片不该再显示 43.1 MB)。
606
+
607
+ ### 7.12 export:把工程打成 zip
608
+
609
+ ```mermaid
610
+ flowchart LR
611
+ A["runExport{projectDir, outDir, includePrebuilt}"] --> B["collectSources:递归收集<br/>跳过 build / .dsh-stm32 / node_modules / .git"]
612
+ B --> C{"includePrebuilt?"}
613
+ C -->|是| D["带上 elf/hex/bin 到 prebuilt/"]
614
+ C -->|否| E["只要源码"]
615
+ D --> F["readmeText(可选内联 README)"]
616
+ E --> F
617
+ F --> G["makeZip:store-only(不压缩,零依赖)→ <name>-export.zip"]
618
+ ```
619
+
620
+ 为什么 zip 里一定没有 build/:CMakeCache 记着本机的绝对路径,带过去只会在别人机器上报错。所以导出的是「能重新配置的源码」,不是「能直接烧的构建目录」。
621
+
622
+ ### 7.13 设置面板:浏览器 bundle 到宿主 API
623
+
624
+ ```mermaid
625
+ sequenceDiagram
626
+ participant C as client/client.js(浏览器)
627
+ participant S as 宿主 webServer
628
+ participant R as engine/web-routes.ts
629
+ participant A as engine/web-api.ts
630
+ participant E as probe / msys2-install / toolchain-config
631
+ C->>S: GET /dsh-stm32/api/config
632
+ S->>R: handler(request, response)
633
+ R->>A: handleWebApi({method, path, body})
634
+ A->>E: configSnapshot / probeTools / installPlan
635
+ E-->>A: 结果
636
+ A-->>R: {status, body}
637
+ R-->>C: JSON(cache-control: no-store)
638
+ Note over C,A: 安装是长任务:install/start 返回 taskId,前端 setTimeout 递归轮询 install/state
639
+ ```
640
+
641
+ 三个契约:**路由全是 exact**(不抢别的前缀)、**请求体上限 1 MB**、**任务表在进程内**(宿主重启就丢,前端会显示「任务不存在」并允许重新发起)。前端只 require 外壳种子(react / jsx-runtime / primitives),不经打包器,因为宿主以 /plugins/dsh-stm32/client.js 直接提供。
642
+
643
+ ### 7.14 斜杠命令:切词 → 门禁警告 → 调 engine
644
+
645
+ ```mermaid
646
+ flowchart LR
647
+ A["/stm32-flash \"C:/Users/zhang san/proj\" --no-debug"] --> B["tokenizeCommandLine<br/>引号内不切、剥引号、记 quoted"]
648
+ B --> C["parseInvocation:第一个非 flag token = 工程目录"]
649
+ C --> D["commandGateWarning(capability, warn)<br/>缺件只警告不拒绝"]
650
+ D --> E["engine(与工具同一个函数)"]
651
+ E --> F["CommandResult{kind: success|error, text}"]
652
+ ```
653
+
654
+ 命令是「用户手打的快捷方式」,所以它的门禁是 warn:用户可能就想让插件跑起来看看报什么错。工具是「模型调的」,门禁才是 block。
655
+
656
+ ## 8. 不变量与陷阱
657
+
658
+ 这些条目破一条就会出真问题,改代码前先扫一眼。
659
+
660
+ | # | 不变量 | 破了会怎样 | 在哪体现 |
661
+ | --- | --- | --- | --- |
662
+ | 1 | 代码只写在 USER CODE 块内 | 下次生成被无声覆盖,编译还不报错 | skill R1/R2、usercode-merge.ts |
663
+ | 2 | .ioc 只能 plan → apply(带 planId) | 配置被手改后与 CubeMX 理解不一致 | skill R3、ioc-plan.ts |
664
+ | 3 | 不许生成 No_Debug 的 SYS | SWD 永久失联,只能 BOOT0 救 | skill R4、flash.checkNoDebugGuard、ioc.summarizeIoc 警告 |
665
+ | 4 | 覆盖文件前必须备份 | 用户代码丢失 | scaffold.backupBeforeOverwrite、ioc-plan、code-patch |
666
+ | 5 | 编码认不出就拒绝写 | 中文注释变问号 | text-file.detectEncoding、code-patch、generate 的 skipped-encoding |
667
+ | 6 | report 结构必须与 output.schema 一致 | 宿主判「工具返回非法输出」 | 每个 tools/*.ts、test/schema-guard.mjs |
668
+ | 7 | 子进程必须显式 cwd + 注入 env | 新装的工具链找不到 | subprocess-runner.ts、tool-env.ts |
669
+ | 8 | 动探针前先 releaseProbeFor | 两个 openocd 抢一个探针 | flash / regs / debug_run 入口 |
670
+ | 9 | turn/end 必须把探针还回去 | 用户在 VS Code 里按 F5 失败 | src/index.ts |
671
+ | 10 | 取消时不得写缓存 | 取消后仍走「已探测」假象 | toolchain-gate(A27) |
672
+ | 11 | 长路径走 \\?\ 前缀 | 深目录复制 ENAMETOOLONG | fs-longpath.ts |
673
+ | 12 | 解包走路径与类型白名单 | zip-slip / 设备文件写进系统 | tar.ts |
674
+ | 13 | 缓存索引写入可恢复 | 半截索引导致缓存全废 | cache.ts(broken/bak + CacheIndexWriteError) |
675
+ | 14 | 门禁快路径也要 smoke | 「文件在但跑不起来」被判齐全 | toolchain-gate(B13) |
676
+ | 15 | 安装自检不许 PATH 兜底 | 用系统里的旧工具冒充新装 | probe 的 allowPathFallback=false |
677
+ | 16 | 计划模式绝不写盘 | 用户以为只是看一眼,结果被改了 | msys2-install / firmware-install 的 plan 分支 |
678
+ | 17 | 模板里不许出现开发机绝对路径 | 新工程 F5 直接失败 + 泄露用户名 | vscode-config.ts + templates/ |
679
+ | 18 | 生成成功以产物为准,不以日志为准 | 缺包时误报成功 | generate.assessGenerateProducts |
680
+ | 19 | 生成期间 pdsc 停放必须在 finally 还原 | 用户的第三方包索引「消失」 | thirdparty.ts + generate.ts |
681
+ | 20 | 零运行时依赖、lib/ 入库 | 装上就坏 / 用户机器没有编译器 | package.json、tsconfig |
682
+ | 21 | cmake 源清单必须跟着 startup 与 hal_conf 走 | 开了外设也链接失败(undefined reference to HAL_xxx_Init) | cmake-sources.refreshCubemxCmakeLists、generate.ts 两处调用 |
683
+ | 22 | 链接脚本按 `<DeviceId>` 命名,命令行上只能有一个 `-T` | 链接的是别人的 MEMORY:编译过、烧到小容量芯片上跑飞(.ld 说 256 KiB,实际只有 64 KiB) | hal-chip.pointLinkerFlagAt、register-linker.renderLinkerScript、doctor.checkChipConsistency ①③ |
684
+ | 23 | 寄存器名字只能来自 SVD,插件不许内置寄存器表 | 手写表必然过期:偏移错一位就解释错位域,比不给名字更糟 | data/svd.ts(严格解析 + 整份拒绝)、test/svd-units |
685
+
686
+ ## 9. 测试体系
687
+
688
+ ### 9.1 三层
689
+
690
+ | 层 | 位置 | 说明 |
691
+ | --- | --- | --- |
692
+ | 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 41 个套件 654 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
693
+ | e2e 脚本 | test/e2e-*.mjs(15 个) | 开发期手动跑的端到端(真 CubeMX / 真 openocd / 真工具链),不进 npm test |
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 上两连跑 |
695
+
696
+ ### 9.2 41 个套件一览(test/run-units.mjs 的 suites 数组顺序)
697
+
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。
699
+
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。
701
+
702
+ 约定:
703
+ - 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
704
+ - run-units 用 DSH_STM32_NO_CONFIG=1 跑子进程,避免开发机上真实的 ~/.dsh-stm32/config.json 影响断言。
705
+ - 输出解析认四种结尾(node:test spec / tap / 自写 tests N / fail M / inline);解析不到用例数会标红,而不是默默算 0。
706
+ - 套件退出码非 0 一律算失败,即使它自己打印 fail=0。
707
+ - 加套件必须手改 test/run-units.mjs 的 suites 数组——没有自动发现。
708
+
709
+ ### 9.3 单测的两种假件套路
710
+
711
+ ```ts
712
+ // 套路一:假 subprocess —— 按命令内容返回脚本化输出
713
+ const fake = {
714
+ async resolveExecutable(cmd) { return cmd; },
715
+ spawn(spec) { /* 按 spec.argv 决定往 stdout 写什么 */ },
716
+ };
717
+
718
+ // 套路二:假 fs / 临时目录 —— 真写盘到 os.tmpdir(),测量真实的备份、编码、原子替换
719
+ ```
720
+
721
+ 凡是「决定行为的分支」都要有脚本化的输出样本,样本**必须是上游真实格式**(审计期间踩过:按文件名猜 CMSIS 守卫宏,测的是假世界)。
722
+
723
+ ## 10. 要改东西时动哪里
724
+
725
+ | 想做的事 | 动这些文件 | 别忘了 |
726
+ | --- | --- | --- |
727
+ | 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
728
+ | 改报告字段 | src/tools/<x>.ts 的 reportSchema + 渲染 | schema-guard 必须有对应断言 |
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 一致性 |
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」「超限一个键都不写」;派生键必须全量重算 |
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/`,与内置资源同构 |
733
+ | 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
734
+ | 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
735
+ | 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
736
+ | 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
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 |
738
+ | 改 cmake 源清单的认法(设备宏、startup、HAL 模块) | engine/cmake-sources.ts 的 `collectCmakeSources` / `halModulesInUse` | 注释掉的 `#define` 与 `#include` 不能算启用;内容没变必须零写入(cmake-sources-units 15 例兜这两条) |
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) |
740
+ | 改寄存器写法的解析或位域解释 | `src/data/svd.ts`(符号解析 / 反向查 / 解码)+ `src/tools/regs.ts`(五种写法、去重、dump、渲染、建议文案) | `svd-units` 39 例兜着;夹具在 `test/fixtures/svd/`(flat / versioned / badline 三种布局);改渲染要同步两份 README 与 development-notes §31 |
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,升级后自动失效 |
742
+ | 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
743
+
744
+ ## 11. 已知的坑与未做的事
745
+
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 改字母。
747
+ 2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
748
+ 3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
749
+ 4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
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 个文件。
752
+ 7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
753
+ 8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
754
+ 9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
755
+ 10. **裸 `cmake -S . -B build` 会丢工具链文件**:工具链只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不走 preset 就得自己给 `-DCMAKE_TOOLCHAIN_FILE`,否则 configure 用宿主 gcc、链接时找不到启动文件。
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 时才退回文件大小并注明是粗算。
757
+ 12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
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`。
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/` | 25 个文件 / 28 个注册工具 / 9,027 行 |
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
+ | TypeScript | 110 个文件、42,261 行(`src/`,不含 client) |
823
+ | `src/tools/` | 25 个文件 / 28 个注册工具 / 9,027 行 |
824
+ | `src/engine/` | 65 个 `.ts` / 26,358 行 |
825
+ | `src/data/` | 17 个 `.ts` / 7,625 行 |
826
+ | 单测 | 61 个套件 / 923 pass / 0 fail(`node test/run-units.mjs`,本机实测) |
827
+
828
+ 第 1–11 章的目录表与模块计数保留 D 阶段原样(45 个 engine 模块、23 个 tools 文件),读旧章节时以本节为准。
829
+
830
+ ## 14. 0.1.6 增补:宿主 schema 子集与 `pins` / `parameters` 数组化
831
+
832
+ > 接续 §13,同属 0.1.6。这一节不改业务行为,只让 25 个工具的 schema 落进 DSH 0.2.2-rc.1 允许的子集。
833
+
834
+ ### 14.1 先读哪里
835
+
836
+ - `src/types.ts` 的 `JsonSchema`:现在就是宿主子集本身——`type` / `oneOf` / `properties` / `required` / `additionalProperties`(仅 boolean)/ `items` / `enum` / `const` + 注解 `description` / `title` / `default` / `examples`。`minimum` / `maximum` 已删除,看到需要范围时去 `description` 和执行期校验里找。
837
+ - `src/tools/ioc-plan.ts` 的 `parameters`:`peripherals[].pins` / `parameters` 是 `type:"array"` + `items:{key,value}`,`pllMul` 是 `integer` + `enum[2..16]`。
838
+ - `src/engine/ioc-plan.ts` 的 `KeyValuePair` 与 `keyValueMap()`:数组 → `Map` 的唯一入口,空 key / 重复 key 在这里记 `errors`。
839
+ - `src/engine/serial.ts` 的 `SERIAL_SETTINGS_PROPERTIES`:参数 schema 与输出 `settings` schema 复用同一片段,范围只在 `description` 里;真正的越界判定在 `src/data/serial-config.ts` 的 `normalizeSerialSettings`。
840
+ - `test/schema-subset-units.test.mjs`:镜像校验器 + 从 `app.asar` 抽真校验器做真值对齐。改任何工具的 schema 后先跑它。
841
+
842
+ ### 14.2 三条不变量
843
+
844
+ 1. 任何 schema 节点只出现子集关键字;`additionalProperties` 只能是 boolean,`items` 只在数组上,`properties`/`required` 只在对象上。
845
+ 2. 数值范围**不进 schema**:写 `description`,并在执行期校验(`keep`:非法即 `ok=false` 且不动文件;串口:`normalizeSerialSettings` 记 errors 并保持默认值)。
846
+ 3. 「任意键 → 值」的映射不允许再写成 `additionalProperties: {…}`;要么换成 `[{key,value}]` 数组,要么用 `additionalProperties: true` 兜底。
847
+
848
+ ### 14.3 计数口径(0.1.6 起)
849
+
850
+ | 项 | 当前值 |
851
+ | --- | --- |
852
+ | 注册工具 | 25 个(25/25 schema 合规) |
853
+ | 单测 | 61 个套件 / 923 pass / 0 fail |
854
+
855
+ 本机同基线实测为 921,加 2 条新用例后 923;§13.5 表里原有的 937 是另一台机器的发布记录。
856
+
857
+ ---
858
+
859
+ 读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
860
+
861
+ ## 15. 调试台:事件流与停靠网格(0.1.7 增补,S1–S91)
862
+
863
+ > 接续 §14。这一节新增的是一个主窗口标签(`conversation.view`)和它背后的只读事件流,不改任何工具的行为与契约。
864
+
865
+ ### 15.1 先读哪里
866
+
867
+ - `src/engine/event-bus.ts`:环形缓冲与序号。`EVENT_RING_LIMIT = 5000`、`EVENT_PAYLOAD_LIMIT = 8192`、`EVENT_PENDING_LIMIT = 2000`;`emitEvent` 是唯一写入入口。
868
+ - `src/engine/event-log.ts`:被挤出的事件按 30 秒一批写到 `<证据根>/<日期>/<会话键>/events-<HHmmss>.jsonl`;缺口先写一条 `kind:"log"` 的事件。
869
+ - `src/engine/tool-events.ts`:装配期 Proxy 只包 `tools.register`,给 `stm32_*` 工具加 start / ok / fail。
870
+ - `src/engine/channels.ts`:串口 / RTT / 监视的输出编成 `channel:<名字>` 事件(单行 ≤400 字符、单次 ≤400 行)。
871
+ - `src/engine/web-api.ts` 的 `openEventStream` 与 `EVENT_STREAM_PATH`(`/dsh-stm32/api/events`,SSE,`?since=` 续播、`&session=` 按会话过滤);`/status` 返回计数与证据目录,`?session=` 只数本会话。`self` 带版本、`libMtimeMs`、`startedAt`、`routeCount`——状态条据此提示「有新构建」。
872
+ - `src/engine/web-routes.ts`:事件流单独分支,直接写原始 `response`,不进 JSON 分发器。
873
+ - `GET /dsh-stm32/api/debug` 与客户端会话卡:只读调试会话摘要(端口、剩余租约、断点与观察点配额),5 秒轮询。
874
+ - `POST /dsh-stm32/api/debug/breakpoints`:断点面板的三个动作(list / add / remove),位置与编号白名单,不做任意 gdb 命令转发。
875
+ - `src/engine/progress.ts` 与 `POST /dsh-stm32/api/abort`:在途调用登记表与中止;派生 AbortController 把宿主的 abort 转发进来,面板只掐自己这一支,工具仍把信号透传给子进程。`/status` 的 `running` 与事件流里的 `callId` 是同一份事实的两种读法。
876
+ - `src/engine/pinout.ts` 与 `/pinout`:引脚面板。`readPinout(projectDir, env)` 复用 `summarizeIoc`,`groupOfPin` / `groupPins` 决定分组与顺序(外设自然序在前,GPIO/调试口/时钟/虚拟引脚在后);同一份报告里的 `physical` 来自 `readPhysicalLayout`(读 CubeMX `db/mcu/<Mcu.Name>.xml` 的 `Position`,`pinCount` 取最大脚号而不是去重后的名字数),客户端「方框」视图由 `pinBoxSides` 摊到四边、`PinBox` 渲染,没有 db 时只显示 `reason`。
877
+ - `src/engine/fault-hints.ts` 与 `/faults`:故障页。`decodeFault` 是纯函数规则表,按最具体优先;没命中就返回空提示,不猜原因。`groupFaults` 按规则合并计数给面板显示,不改事件本身。
878
+ - `/evidence` 与 `/replay`:列证据文件(`groupEvidenceFiles` 按会话分组,路径仍是唯一标识)、按路径还原事件;回放入口在时间线工具栏,不与实时事件混流。
879
+ - `src/engine/ioc-diff.ts` 与 `/ioc-diff`、`/ioc-diff/save`、`/ioc-diff/restore`:当前 .ioc 与用户目录里基线的逐键差异;基线覆盖式保存,不依赖 git;`restoreIocKey` 把某个键写回基线值,写前备份到 `<工程>/.dsh-stm32/backups`。
880
+ - `readIocKeysForPin` 与 `/ioc-keys`:引脚页「ioc」按钮查看该脚在 `.ioc` 里占的键(前缀匹配,退一步取第一段)。
881
+ - `src/engine/breakpoint-hits.ts`:从 gdb 输出解析断点/观察点停点,`HitHistory` 环形 50 条;`/debug` 的 `hits` 给断点面板底部列表。
882
+ - `DebugSessionManager` 的 `EvalTrace` 与 `recentTraces()`:`/debug` 的 `outputs` 给会话卡显示最近几次 gdb 原始输出(环形 20 条、每条留尾部 2000 字符)。
883
+ - `src/engine/watch-recorder.ts` 与 `watch-record.ts`:监视自动采样。定时器夹在 500–60000 ms、一次最多 10 分钟,`sample` 复用 `debugSessions.sampleWatches`,结果仍走 `channel:watch`,面板不换数据源。
884
+ - `POST /serial/send`:面板在串口通道里发一行,参数校验后调 `sendSerial`,与工具入口共用桥命令;无会话时 409。
885
+ - 引脚行点击复制引用(`PA9 USART1_TX`),`PinRow` 里内联实现,没有服务端接口。
886
+ - `ChannelBlock` 的关键字过滤与 RTT 级别按钮:纯展示层,只作用于当前暂停/清空窗口。
887
+ - `POST /debug/touch` 与 `DebugSessionManager.touch()`:会话续期只重置空闲计时,总时长上限不变。
888
+ - 时间线工具栏:状态筛选(全部 / 只看失败)与「导出 JSONL」,纯客户端,导出的是当前视图。
889
+ - 客户端 `toolDurations`:按 `callId` 配对 start 与 ok/fail 算耗时,超过 `TOOL_SLOW_MS`(5 秒)标黄;工具栏可切「按时间 / 按耗时」。
890
+ - 时间线勾选与「复制已选(N)」:`eventRefBlock` 把多条事件拼成一段引用,顺序按时间线而不是勾选顺序;纯客户端。
891
+ - `src/engine/artifacts.ts` 与 `/artifacts`:产物页。`readArtifacts` 只读构建目录里的 elf/hex/bin 文件属性,容量取 `findChipFact` 的芯片事实;Flash/RAM 占用不在这里算,面板从 `stm32_build` 的 ok 事件里取 `memoryUsage`,保证只有一份数字。
892
+ - 客户端 `OverviewPanel` 的工具链一行:`useProbeSummary(60000)` 读 `GET /probe`,能力四项只认 `capabilities`,缺件直接列名。
893
+ - 客户端 `OverviewPanel`:概览页,纯拼装 `usePinout` / `useClockTree` / `useArtifacts` / `useDebugStatus` 与事件流里的构建、烧录时间戳,没有对应的服务端接口。
894
+ - `src/engine/clocks.ts` 与 `/clocks`:时钟页。只读 `.ioc` 的 `RCC.*Freq_Value`,不复算;`dividerLabel` / `mulLabel` 只做展示翻译。`familyOfCpn` / `limitForNode` 按芯片族给出 APB1/APB2/ADC 上限并判超限,`suggestFix` 只对这三路枚举分频档给出「改成 ÷N」的建议(不写 `.ioc`,改配置仍走 `stm32_ioc_plan`);客户端 `ClockPanel` 的表/图两种模式共用同一份节点数据,图模式由 `ClockFlow` 用 `clockFlowRows` 摊平层级后渲染。
895
+ - `src/engine/event-log.ts` 的 `pruneEvidence`:证据保留(7 天 / 20 会话)与 `/evidence/prune`。
896
+ - `src/engine/tool-events.ts` 的 `resultDigest`:白名单决定面板能看见哪些结果字段(`errors` 截 20 条、`projectDir` 用于跳源码)。
897
+ - `src/engine/source-slice.ts` 与 `/source`:停点与编译错误跳源码。
898
+ - `src/engine/serial.ts` 的 `openSerial`/`closeSerial`/`serialStatus`/`listPorts` 与 `/serial*`:面板上的串口卡片,与工具同源。`resolveSourceFile` 要求目标落在工程目录内,`readSourceSlice` 把行号夹到文件范围、上下文封顶 20 行。
899
+ - `src/engine/panel-actions.ts` 与 `/build`、`/flash`:人在面板点构建/烧录,直接调 `runBuild` / `runFlash`,结果以 `source: "user"` 的同形事件进时间线。
900
+ - `src/engine/watch-admin.ts` 与 `/watch`:面板编辑监视登记表,与 `stm32_watch` 共用 `watchState`;删项交给 `debugSessions.removeWatchpoints`,顺带清 gdb 比较器。
901
+ - `src/engine/ioc-sync.ts` 与 `/ioc-sync`:只比 `.ioc` 与 `Core/Src/main.c` 的修改时间,判断「配置改了还没重新生成」;没有 `main.c` 时不下结论。
902
+ - `src/engine/interrupts.ts` 与 `/interrupts`、`/interrupts/priority`:中断页。读 `.ioc` 的 `NVIC.*`(值里的冒号是转义的),优先级排序按抢占→子→名字;段数不足给 -1,不冒充 0;`setInterruptPriority` 只改第二、三段并先备份。
903
+ - `src/engine/channel-tap.ts` 与 `/channels`、`/channels/start`、`/channels/stop`:常驻通道。串口 700 ms 读一次 `rx.ndjson` 的增量、RTT 2 000 ms `dump` 一次,都写回同一套 `channel:*` 事件;偏移靠「尾部指纹」而不是长度判断,桥重写文件也不会错位,`p: true` 的残行跨记录拼接。
904
+ - `client/client.js`:`DebugConsole`(时间线 / 详情 / 通道 / 控制台 / 抽屉)、`SessionCard`、`WatchCurves`(按表达式画最近 120 点)、`BreakpointPanel`;`conversation.view` 的 `inject(sessionId)` 把宿主会话键交给面板,事件与状态都按它过滤;布局存 `dsh-stm32.debug.layout.v1`。
905
+ - `test/event-bus-units.test.mjs`、`test/client-debug-units.test.mjs`:改事件层或客户端结构后先跑这两个。
906
+
907
+ ### 15.2 三条不变量
908
+
909
+ 1. **单一事实源**:面板不缓存第二份数据,只按 `seq` 增量续播;重连从 `lastSeq` 开始,不重放全量。
910
+ 2. **落盘可表达缺口**:缓冲区溢出或写入失败时,证据目录里必须有痕迹(缺口事件或整批回队),不能静默丢。
911
+ 3. **埋点与工具解耦**:工具实现不感知事件系统;`stm32_*` 前缀决定是否被包装,其它插件的工具原样注册。
912
+
913
+ ### 15.3 计数口径(0.1.7 起)
914
+
915
+ | 项 | 当前值 |
916
+ | --- | --- |
917
+ | 注册工具 | 37 个(HTTP 路由 49 条;硬件侧已拆到 dsh-ecad,见 S185/S187) |
918
+ | 源码 | `src/**/*.ts` 124 个文件 |
919
+ | 单测 | 26 个套件 / 1174 pass / 0 fail(含外设预设 4 条、原理图 24 条、PDF 17 条、数据手册 10 条、固件包 52 条、会话隔离 6 条、工程目录 10 条、结构归位 3 条) |
920
+ | 客户端 | `client/client.js` 7033 行(手写,不经 tsc) |
921
+ | 包体 | 2294.3 KB / 384 文件 / 解包 16982.3 KB(护栏上限 3906.3 KB) |