dsh-stm32 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -23
- package/README_EN.md +50 -21
- package/docs/development-notes.md +466 -4
- package/docs/reading-guide.md +738 -0
- package/lib/commands/register.js +49 -0
- package/lib/data/chips.js +134 -4
- package/lib/data/clock-f1.js +158 -0
- package/lib/data/cmsis-sources.js +211 -42
- package/lib/data/f1-ram.generated.js +34 -0
- package/lib/data/stm32f1.js +186 -0
- package/lib/engine/build.js +115 -16
- package/lib/engine/cache.js +56 -0
- package/lib/engine/clock-plan.js +608 -0
- package/lib/engine/cmake-sources.js +428 -0
- package/lib/engine/debug.js +75 -10
- package/lib/engine/doctor.js +395 -4
- package/lib/engine/fetch.js +174 -30
- package/lib/engine/flash.js +95 -6
- package/lib/engine/generate.js +11 -0
- package/lib/engine/hal-chip.js +230 -0
- package/lib/engine/ioc-plan.js +28 -2
- package/lib/engine/msys2-install.js +332 -61
- package/lib/engine/project-export.js +129 -0
- package/lib/engine/register-clock.js +132 -0
- package/lib/engine/register-linker.js +129 -0
- package/lib/engine/register-template.js +88 -17
- package/lib/engine/scaffold.js +104 -28
- package/lib/engine/zip.js +142 -0
- package/lib/index.js +2 -0
- package/lib/skill/stm32-workflow.js +3 -3
- package/lib/tools/build.js +12 -0
- package/lib/tools/cache.js +39 -8
- package/lib/tools/debug.js +7 -0
- package/lib/tools/doctor.js +11 -2
- package/lib/tools/flash.js +3 -0
- package/lib/tools/ioc-plan.js +195 -4
- package/lib/tools/project-create.js +26 -1
- package/lib/tools/project-export.js +100 -0
- package/package.json +5 -3
- package/templates/register/CMakeLists.txt +19 -6
- package/templates/register/Core/Src/main.c +18 -9
- package/templates/scaffold/openocd.cfg +8 -0
|
@@ -0,0 +1,738 @@
|
|
|
1
|
+
# dsh-stm32 源码精读指南
|
|
2
|
+
|
|
3
|
+
> 面向:第一次读这个仓库、并且要改它的人。
|
|
4
|
+
> 规模:72 个 TypeScript 文件约 24.3k 行(另有脚本生成的 src/data/chip-table.json 2044 行),外加一个手写的浏览器 bundle(client/client.js,682 行)。
|
|
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(19 个文件:20 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
|
|
30
|
+
| L2 逻辑层 | src/engine(41 个模块) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
|
|
31
|
+
| L1 事实表 | src/data(8 张事实表 + 1 份生成的芯片薄表) | 芯片表(含由 CubeMX db 派生的引脚表与 chip-table.json)、镜像 URL、固件族、F1 容量档、F1 时钟树、安装指引、搜索路径、配置读写 | 起进程、写工程文件 |
|
|
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/>20 个工具"]
|
|
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/>41 个纯逻辑模块"]
|
|
53
|
+
CMDS --> ENGINE
|
|
54
|
+
WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
|
|
55
|
+
API --> ENGINE
|
|
56
|
+
ENGINE --> DATA["src/data/*<br/>8 张事实表"]
|
|
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 | 795 | index.ts 119、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
|
|
70
|
+
| src/tools/ | 19 | 5078 | 20 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 route-plan.ts 573 行 |
|
|
71
|
+
| src/engine/ | 41 | 15919 | 见第 5 章;最大的是 msys2-install.ts 2313 行,其次是 clock-plan.ts 801 行 |
|
|
72
|
+
| src/data/ | 9 | 4592 | 8 张 .ts 事实表共 2548 行 + 脚本生成的 chip-table.json(2044 行 / 2016 颗芯片),见第 6 章 |
|
|
73
|
+
| templates/ | 17 | — | 工程脚手架与寄存器版模板(CMake、链接脚本、launch/settings、openocd.cfg、demo.ioc) |
|
|
74
|
+
| client/ | 1 | 682 | 设置面板的前端 bundle(手写 JS,不经打包器) |
|
|
75
|
+
| test/ | 29 套件 + 15 个 e2e 脚本 + 4 个辅助脚本 | — | 见第 9 章 |
|
|
76
|
+
| scripts/ | 5 | 776 | copy-client.mjs(24)、gen-chip-table.mjs(371)、gen-xcube-catalog.mjs(151)、pack-size.mjs(80)、pack-smoke.mjs(150) |
|
|
77
|
+
|
|
78
|
+
## 2. 阅读顺序
|
|
79
|
+
|
|
80
|
+
不要从 engine/msys2-install.ts(2313 行)开始读,会迷路。按下面的顺序走,每一站都有一条完整的「从宿主到硬件」的链路可以跟到底。
|
|
81
|
+
|
|
82
|
+
| 站 | 读什么 | 行数 | 读完能回答 | 建议 |
|
|
83
|
+
| --- | --- | --- | --- | --- |
|
|
84
|
+
| 1 | src/index.ts、src/types.ts | 315 | 插件怎么被加载?宿主给了我什么?工具/命令/skill/路由各自怎么注册? | 20 分钟 |
|
|
85
|
+
| 2 | src/tools/flash.ts → src/engine/flash.ts → src/engine/subprocess-runner.ts → src/engine/tool-env.ts | 915 | 一次工具调用从头到尾长什么样?参数怎么校验?进程怎么起、环境变量怎么注入? | 1 小时 |
|
|
86
|
+
| 3 | src/engine/toolchain-gate.ts → probe.ts → src/data/search-roots.ts → src/data/toolchain-config.ts | 1649 | 门禁怎么判「缺件」?为什么快路径也要跑一次版本命令?配置文件的 CAS 写是什么? | 1.5 小时 |
|
|
87
|
+
| 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 小时 |
|
|
88
|
+
| 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 小时 |
|
|
89
|
+
| 6 | src/engine/fetch.ts → cache.ts → tar.ts → firmware-install.ts → thirdparty.ts → xcube.ts → msys2-install.ts | 4652 | sha256 门禁在哪一环?缓存怎么保证可恢复?固件包为什么装到 dsh-firmware?安装计划怎么做到只报缺件? | 3 小时 |
|
|
90
|
+
| 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 小时 |
|
|
91
|
+
|
|
92
|
+
每一站的「流程」在第 7 章都有对应的图,读到不懂的地方先跳到图上找位置。
|
|
93
|
+
|
|
94
|
+
## 3. 入口层
|
|
95
|
+
|
|
96
|
+
### 3.1 src/index.ts(119 行)
|
|
97
|
+
|
|
98
|
+
三件事,只有三件:
|
|
99
|
+
|
|
100
|
+
1. **声明身份与依赖**:`export const name = "dsh-stm32"`、`export const inject = ["tools", "subprocess", "jobs"]`。这三个是硬依赖,缺了插件不加载。
|
|
101
|
+
2. **apply(ctx) 里按「先探测、再操作」的顺序注册 20 个工具**:env_probe → env_install → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → build → flash → debug_run → debug_session → regs_read → route_plan → cache → doctor → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
|
|
102
|
+
3. **注册可选层并挂三个事件**:commands / skills 走 `ctx.inject([...], scope => ...)`,宿主没组合这些服务时静默跳过,工具照常工作;webServer 路由在`registerWebRoutes` 里自己判断。
|
|
103
|
+
|
|
104
|
+
三个事件是本插件唯一的「状态清理入口」,也是很容易读漏的地方:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
ctx.on("session/event", (session, event) => {
|
|
108
|
+
if (event?.type !== "turn/end") return;
|
|
109
|
+
const owner = callerIdOf(event, session); // A9:尽量挖出发起方 agent id
|
|
110
|
+
void debugSessions.stop("turn/end:本轮输出结束,把探针还给你",
|
|
111
|
+
owner === "" ? {} : { requireOwner: owner });
|
|
112
|
+
});
|
|
113
|
+
ctx.on("session/disposed", () => { void debugSessions.stop("session/disposed"); });
|
|
114
|
+
ctx.on("dispose", () => { void debugSessions.stop("插件卸载"); });
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
为什么要在 turn/end 就关会话:宿主把探针当独占资源,插件攥着它的时候用户在 VS Code 里按 F5 会失败。所以「我一输出完、等你回复」就必须松手(规格 §6.4)。`callerIdOf` 是本文件唯一的业务函数,它按「可能的位置逐个试」的方式从事件里掏 agent id——宿主没公开事件结构,掏不到就返回空串,debug-session 见到空串退回「无条件全关」的老行为,保证不漏关。
|
|
118
|
+
|
|
119
|
+
### 3.2 src/types.ts(196 行)
|
|
120
|
+
|
|
121
|
+
这不是「类型文件」,是**契约清单**。文件头注释写明了为什么自写:asar 里只有编译后的 JS,`@deepseek-ai/dsh-tools` 的类型装不到。所以这里只声明本项目真正用到的那部分。
|
|
122
|
+
|
|
123
|
+
读的时候注意四个坑(都是踩过的):
|
|
124
|
+
|
|
125
|
+
| 契约 | 坑 | 后果 |
|
|
126
|
+
| --- | --- | --- |
|
|
127
|
+
| `SpawnSpec.cwd` | 宿主 subprocess 要求必填,不传直接抛 TypeError | 所有 engine 起进程都必须显式给 cwd |
|
|
128
|
+
| `SpawnSpec.stdio` | stdout/stderr 要写成 `{ maxBytes }` 才是收集式,否则拿不到输出 | 忘记 maxBytes 时报告里日志为空 |
|
|
129
|
+
| `SkillDefinition.source` | register 不校验,真正加载时才校验必须是字符串 | 漏了 source 的表现是 skill 出现在目录里,一加载就报 `loaded skill ... source must be a string` |
|
|
130
|
+
| `WebServerService` | 宿主没发布 IncomingMessage/ServerResponse 类型 | request/response 用 any,只在 web-routes.ts 里收口 |
|
|
131
|
+
|
|
132
|
+
### 3.3 src/skill/stm32-workflow.ts(35 行)
|
|
133
|
+
|
|
134
|
+
内容是一屏红线(R1–R5 + 12 条踩过的坑),运行时注册而不是打包成文件——「凡是能注册的服务就不要依赖路径约定」。口径已从「本机这块 C8T6」改成 **STM32F1 全系**(F100/101/102/103/105/107):换型号必须启动文件、设备宏、链接脚本三者一起换,外加时钟跟着 line 的上限走。
|
|
135
|
+
|
|
136
|
+
- **R1** 代码只写在 `/* USER CODE BEGIN X */` 与 `END` 之间(CubeMX 承诺原样保留的唯一区域)。
|
|
137
|
+
- **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 的兼容副本。
|
|
138
|
+
- **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)一个键都不写。
|
|
139
|
+
- **R4** 不许生成 No_Debug 的 SYS 配置(会关掉 PA13/PA14 的 SWD,烧一次就永久失联,只能 BOOT0 救)。
|
|
140
|
+
- **R5** 烧录与调试分开:flash 一次性 program-verify-reset-exit,debug_run 只在需要时开调试会话。
|
|
141
|
+
|
|
142
|
+
### 3.4 src/commands/register.ts(445 行)
|
|
143
|
+
|
|
144
|
+
七条斜杠命令:`/stm32-env`、`/stm32-setup`、`/stm32-doctor`、`/stm32-build`、`/stm32-flash`、`/stm32-debug`、`/stm32-stop`。
|
|
145
|
+
|
|
146
|
+
文件里真正值得读的是前面四个函数,后面全是 handler:
|
|
147
|
+
|
|
148
|
+
- `tokenizeCommandLine(rawInput): CommandToken[]` —— 引号感知切词(审计 B7)。一次扫描:引号内不切、顺手剥引号、记下 `quoted` 标记,这样 `--flag` 只有在没被引号包住时才算 flag。原来是「先按空白切再剥引号」,遇到 `"C:/Users/张 三/proj"` 会把路径切两段。
|
|
149
|
+
- `parseInvocation(ctx, invocation)` —— 把切出来的 token 变成工程目录 + 其余选项;`needSubprocess(ctx)` 拿不到进程服务时返回一句话错误而不是抛异常。
|
|
150
|
+
- `commandGateWarning(ctx, capability, signal, ...)` —— 命令侧的门禁是 **warn 不是 block**(审计 B8):命令是用户手打的,缺件时应该「照常执行 + 前置一行警告」,而不是拒绝。
|
|
151
|
+
- `withGateWarning(warning, result)` —— 把警告行拼到 `CommandResult.text` 前面。
|
|
152
|
+
|
|
153
|
+
7 条命令里有 6 条最终调用 engine 的同一个函数(build → runBuild,flash → runFlash …),所以它们和工具的唯一差别是:输入来自文本而不是 JSON、输出是一段中文。
|
|
154
|
+
|
|
155
|
+
## 4. tools 层:20 个工具 + 1 个基础设施
|
|
156
|
+
|
|
157
|
+
### 4.1 一个工具文件的固定骨架
|
|
158
|
+
|
|
159
|
+
以 src/tools/flash.ts(185 行)为例,每个工具都是同一个模子:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
export const FLASH_TOOL = "stm32_flash"; // 1. 名字常量(测试与命令复用)
|
|
163
|
+
const reportSchema: JsonSchema = { ... }; // 2. 输出报告 schema(additionalProperties: false)
|
|
164
|
+
export const outputSchema: JsonSchema = { schema: reportSchema, render: formatFlashReport };
|
|
165
|
+
|
|
166
|
+
export function registerFlash(ctx: DshContext): void {
|
|
167
|
+
ctx.tools.register({
|
|
168
|
+
name: FLASH_TOOL,
|
|
169
|
+
description: "...",
|
|
170
|
+
parameters: { ... }, // 3. 参数 schema
|
|
171
|
+
output: outputSchema,
|
|
172
|
+
async execute(args, exec) { // 4. 校验 → 门禁 → engine → 渲染
|
|
173
|
+
const projectDir = await resolveProjectDir(ctx, args.projectDir, exec);
|
|
174
|
+
const gate = await ensureToolchain(ctx, { capability: "flash", envCheck: args.envCheck, signal: exec.signal });
|
|
175
|
+
if (!gate.ok) return blockedReport(projectDir, gate);
|
|
176
|
+
const report = await runFlash(ctx.subprocess, { ... });
|
|
177
|
+
return report;
|
|
178
|
+
},
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function formatFlashReport(report: FlashReport): string[] { ... } // 5. report → 中文行
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
三个细节值得记住:
|
|
186
|
+
|
|
187
|
+
1. **输出 schema 是硬的。** 宿主会拿 `output.schema` 校验 execute 的返回值,report 上任何没声明的字段都会被判「工具返回了非法输出」——这正是 0.1.2 上板时抓到的缺陷(flash 失败带 errorCode,而 schema 漏声明它,于是失败路径直接崩)。改 report 结构必须同步改 schema,test/schema-guard.mjs 就是为这条存在的。
|
|
188
|
+
2. **门禁在工具层,不在 engine。** engine 假设工具链就位;`blockedReport` / `emptyReport` 是门禁拦截与早退时造「同形报告」的工厂,保证失败也是合法输出。
|
|
189
|
+
3. **`resolveProjectDir` + `validateToolArgs`(tools/project-dir.ts,120 行)是所有工具的共同入口**:前者把 `projectDir` 参数 / 会话工作目录落成绝对路径,后者按 `RequiredArgSpec` 校验必填参数类型,报错文案统一。
|
|
190
|
+
|
|
191
|
+
### 4.2 20 个工具一览
|
|
192
|
+
|
|
193
|
+
| 工具 | 文件(行) | engine 入口 | 门禁能力 |
|
|
194
|
+
| --- | --- | --- | --- |
|
|
195
|
+
| `stm32_env_probe` | env-probe.ts(284) | probe.buildTargets / probeAll + search-roots.resolveSearchConfig | 无 |
|
|
196
|
+
| `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
|
|
197
|
+
| `stm32_firmware_install` | firmware-install.ts(288) | firmware-install.planOrInstallFirmware | 无 |
|
|
198
|
+
| `stm32_project_create` | project-create.ts(344) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
|
|
199
|
+
| `stm32_project_export` | project-export.ts(122) | project-export.runExport | 无 |
|
|
200
|
+
| `stm32_code_patch` | code-patch.ts(130) | code-patch.patchUserCode | 无 |
|
|
201
|
+
| `stm32_generate` | generate.ts(308) | generate.runGenerate | generate(CubeMX 启动器 + JRE) |
|
|
202
|
+
| `stm32_ioc_inspect` | ioc-inspect.ts(241) | ioc.summarizeIoc | 无 |
|
|
203
|
+
| `stm32_ioc_plan` | ioc-plan.ts(395) | ioc-plan.planIocChanges + clock-plan.planClockChanges(引脚 / 键 / 时钟进同一个 candidate) | 无 |
|
|
204
|
+
| `stm32_ioc_apply` | ioc-apply.ts(135) | ioc-plan.applyIocPlan / rollbackIoc | 无 |
|
|
205
|
+
| `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
|
|
206
|
+
| `stm32_flash` | flash.ts(185) | flash.runFlash | flash(openocd) |
|
|
207
|
+
| `stm32_debug_run` | debug.ts(211) | debug.runDebugRun | debug(openocd + gdb) |
|
|
208
|
+
| `stm32_debug_session` / `_eval` / `_stop` | debug-session.ts(265,三工具同文件) | debug-session.DebugSessionManager(单例 debugSessions)+ releaseProbeFor | debug(仅 session 启动时) |
|
|
209
|
+
| `stm32_regs_read` | regs.ts(218) | regs.runRegsRead | debug |
|
|
210
|
+
| `stm32_route_plan` | route-plan.ts(573) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
|
|
211
|
+
| `stm32_cache` | cache.ts(274) | engine/cache 全套 | 无 |
|
|
212
|
+
| `stm32_doctor` | doctor.ts(192) | doctor.runDoctor + collectChipConsistency(型号/启动文件/设备宏/.ld/Flash 五项一致性) | 无(它自己就是体检) |
|
|
213
|
+
| —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
|
|
214
|
+
|
|
215
|
+
两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**route-plan.ts 573 行**是 tools 层里最大的,因为它的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
|
|
216
|
+
|
|
217
|
+
## 5. engine 层:41 个模块,十个域
|
|
218
|
+
|
|
219
|
+
下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。
|
|
220
|
+
|
|
221
|
+
### 5.1 进程与路径(3 个,413 行)
|
|
222
|
+
|
|
223
|
+
| 模块 | 职责与关键导出 |
|
|
224
|
+
| --- | --- |
|
|
225
|
+
| 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。 |
|
|
226
|
+
| tool-env.ts(56) | `envWithBinDirs(binDirs, base)`:binDirs 去重去空后**拼在原 PATH 前面**,Windows 上只留一个大小写正确的 `Path` 键;`toolSearchDirs(binDirs, base)` 给出「去哪找可执行文件」的有序目录表。 |
|
|
227
|
+
| fs-longpath.ts(107) | 长路径工具。`toLongPath` 加 `\\?\` 前缀、`existsLong`、`mkdirTrackedLong`(顺手记下新建的目录,失败时回收)、`copyFileLong`、`copyTreeLong`、`describeCopyFailure`。固件包的 Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc 这种深度在长用户名下会撞 MAX_PATH(审计 B17)。 |
|
|
228
|
+
|
|
229
|
+
### 5.2 探测、搜索与门禁(engine 2 个 + data 2 个,1649 行)
|
|
230
|
+
|
|
231
|
+
| 模块 | 职责与关键导出 |
|
|
232
|
+
| --- | --- |
|
|
233
|
+
| 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 个探测目标)。 |
|
|
234
|
+
| 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)。 |
|
|
235
|
+
| 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`。 |
|
|
236
|
+
| 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`。 |
|
|
237
|
+
|
|
238
|
+
### 5.3 构建与产物(2 个,543 行)
|
|
239
|
+
|
|
240
|
+
| 模块 | 职责与关键导出 |
|
|
241
|
+
| --- | --- |
|
|
242
|
+
| 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`。 |
|
|
243
|
+
| 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/。 |
|
|
244
|
+
|
|
245
|
+
### 5.4 烧录、调试与诊断(5 个,2257 行)
|
|
246
|
+
|
|
247
|
+
| 模块 | 职责与关键导出 |
|
|
248
|
+
| --- | --- |
|
|
249
|
+
| flash.ts(424) | `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` 认 ** Programming Finished ** / ** Verified OK **,成功序列里的偶发 Error 行进 noise)→ 失败时分类(`errorCodeOfLines` → no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / unknown)→ 追加 USB 形态提示(`usbNoteFor` / `probeMissingLines`)。`toOpenOcdPath` 只把反斜杠换成正斜杠。`HINT_PROBE` / `HINT_DP` / `HINT_BUSY` 三个提示常量是 export 的,debug.ts 复用同一套文案。 |
|
|
250
|
+
| debug.ts(406) | 一次性调试快照 `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)。失败时:`errorCodeOfLines` 归类(与 flash 同一枚举)、`debugHintFor` 给下一步、`probeMissingLines` 命中就跑 `usbDiagnosis`、日志用 `keyLogTail(lines, 40)`(优先留 adapter/Error 行,而不是「最后 15 行」)、`firstProblemLine` 把首条根因塞进 errors。 |
|
|
251
|
+
| debug-session.ts(516) | 长会话租约。`DebugSessionManager` 管「一个常驻 openocd + 多次短命 gdb -batch eval」,空闲 90 s、总时长 10 min、turn/end 立刻释放;`releaseProbeFor(reason)` 是别的工具(flash/regs/debug_run)动探针前必须调的一步(审计 B16:先释放再门禁)。三个纯函数是好单测点:`normalizeHexAddress`、`parseGdbPrintedHex`、`parseMarkedWords`(按 `echo ===DSH:<tag>===` 分段对齐,修「中间某个地址读失败导致后面值整体前移」)。 |
|
|
252
|
+
| regs.ts(246) | 读内存映射寄存器。`normalizeAddress`(0x 可省)、`buildRegsScript`(生成 openocd 脚本:init → halt → mdw)、`parseRegsLog` → `runRegsRead`。与 debug-session 的区别是「一次性、不复位」,起完就关。 |
|
|
253
|
+
| 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 的那个)。 |
|
|
254
|
+
|
|
255
|
+
### 5.5 生成、编码、.ioc 事务与时钟(10 个,3659 行)
|
|
256
|
+
|
|
257
|
+
| 模块 | 职责与关键导出 |
|
|
258
|
+
| --- | --- |
|
|
259
|
+
| 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。 |
|
|
260
|
+
| generate-script.ts(115) | `buildGenerateScript` 拼脚本(setCustomFWPath / SetCopyLibrary / ProjectManager 项)、`layoutCommand`、`parseGenerateLog`:UNKNOWN_COMMAND 先判;成功行不再「一票否决」错误(审计 A10)——CubeMX 缺包时也会打 Code successfully generated,所以 ok 由产物判据决定。 |
|
|
261
|
+
| generate-cache.ts(168) | 生成缓存。`CACHE_FILE = "generate-cache.json"`、`sha256Text` / `sha256File`、`cubeMxStamp`、`computeCacheKey(iocSha, stamp, layout)`、`readCache` / `writeCache`、`cacheHit(entry, key, projectDir)`(key 命中还不够,文件 hash 也得对得上)。 |
|
|
262
|
+
| usercode-merge.ts(142) | `parseUserCodeRegions` / `mergeUserCode` / `canMergeUserCode`:把旧文件 USER CODE 块里的内容搬进新生成的文件,保留 CRLF 风格,标出 droppedLabels。 |
|
|
263
|
+
| code-patch.ts(215) | `patchUserCode`:只改一个 USER CODE 块(replace / append),块内出现 `{` 或 `}` 拒绝(结构行守卫),写前备份,写回**按字节拼接**(见 text-file)。`listUserCodeLabels` 列出可用标签。 |
|
|
264
|
+
| text-file.ts(172) | 编码层。`detectEncoding`(BOM → utf8-bom;空 → utf8;严格 UTF-8 成 → utf8;再试 gb18030;否则 unknown)、`decodeText`、`encodeText`(gb18030 只允许纯 ASCII——Node 只有解码器没有编码器)、`readTextFile`、`lineStarts`、`replaceLineRange`(未改的行原字节照抄,只把新增行按原编码插入)。**这是「中文注释不被写坏」的唯一保障**。 |
|
|
265
|
+
| ioc.ts(202) | .ioc 只读解析:`parseIocEntries`、`decodeIocValue`、`summarizeIoc`(MCU、时钟树、引脚、外设、调试口、工程设置、警告)。 |
|
|
266
|
+
| ioc-plan.ts(614) | .ioc 事务。`planIocChanges` 算出逐键 diff + 源 SHA-256 → planId;`applyIocPlan` 校验 SHA 后原子替换(备份到 backups/<stamp>-ioc);`rollbackIoc(backupFrom)` 回滚;辅助 `renderIocText`、`compareEntries`、`sha256Hex`、`encodeIocValue`、`loadPlan`。引脚写入保序(审计 A3):只追加新增,不因缺 .Signal 删已有项。 |
|
|
267
|
+
| 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。 |
|
|
268
|
+
| 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。 |
|
|
269
|
+
|
|
270
|
+
### 5.6 造工程、链接脚本与导出(8 个,2198 行)
|
|
271
|
+
|
|
272
|
+
| 模块 | 职责与关键导出 |
|
|
273
|
+
| --- | --- |
|
|
274
|
+
| 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 在**写盘之前**渲染成字符串,渲染失败时一个字节都不写。 |
|
|
275
|
+
| 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)。全是字符串函数,所以能先渲染后落盘。 |
|
|
276
|
+
| register-template.ts(558) | 寄存器路线(不碰 CubeMX)。`resolveStartupChoice`(按型号/族选启动文件与宏)、`ensureCmsisTemplate`(从镜像下载 10 个文件到缓存并校验 sha256)、`createRegisterProject`(拷模板 → 写设备头/启动文件/链接脚本 → 生成 main.c)。模板文件缺失分「必需」与「可选」(.gitignore 是可选,缺了给 warning 不阻断)。模板里已不写死任何型号:启动文件、设备宏、设备头、`.ld`、时钟全部按 `resolveF1Chip` 的结果参数化(14 个容量档)。 |
|
|
277
|
+
| 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 跟着对。 |
|
|
278
|
+
| register-linker.ts(152) | 寄存器版的链接脚本渲染:按型号换掉 `<DeviceId>_FLASH.ld` 的 MEMORY RAM/FLASH 两行。F100/F101/F102 的 RAM 不在 src/data/stm32f1.ts 的表里,用 CubeMX db 的最小值兜底**并明确警告**(宁可小——栈必须留在真 RAM 内)。 |
|
|
279
|
+
| vscode-config.ts(118) | `VSCODE_PLACEHOLDERS`(gdb / toolchain / cmake / svd 四个占位符)、`detectVscodeFill`(按本机探测结果填)、`fillVscodeTemplate`(没值的整行删掉并记 dropped,绝不写空串)、`describeDroppedPlaceholder`。模板里因此不出现任何开发机绝对路径(审计 B1)。 |
|
|
280
|
+
| project-export.ts(155) | `runExport`:收集源文件(跳过 build / .dsh-stm32 / node_modules / .git)→ 可选带 prebuilt(elf/hex/bin)→ 可选内联 README → 打 zip。 |
|
|
281
|
+
| zip.ts(152) | 自写的最小 store-only zip(不压缩、不引依赖):`crc32`、`makeZip`、`listZipEntries`(测试用来验内容)。 |
|
|
282
|
+
|
|
283
|
+
### 5.7 下载、缓存与固件包(7 个,2456 行)
|
|
284
|
+
|
|
285
|
+
| 模块 | 职责与关键导出 |
|
|
286
|
+
| --- | --- |
|
|
287
|
+
| 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)`,否则半成品会长期躺在缓存目录里等着占满磁盘。 |
|
|
288
|
+
| cache.ts(370) | 缓存索引(默认 %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`。 |
|
|
289
|
+
| tar.ts(288) | `extractTarGz(archive, destRoot, options)`:解 gzip + tar,路径白名单(`isSafeRelative` 拒反斜杠、冒号、.. 与空段)、类型白名单(`entryKind`:0/空/5 正常,x/g/L/K 元数据,其余跳过并记名,审计 A4)、声明长度超出实际数据判截断整次失败。 |
|
|
290
|
+
| 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 也能找到非标准落点。 |
|
|
291
|
+
| thirdparty.ts(281) | 生成期间临时停放 CubeMX 的第三方包索引(`PARKED_NAME = "pdsc.dsh-parked"`、`needsThirdpartyPacks`、`parkThirdpartyDb`),有 X-CUBE 包的工程保持原样;`cubeMxUserHome`。 |
|
|
292
|
+
| xcube.ts(293) | X-CUBE 包识别:`identifyPackId`、`parsePdscNames`、`listInstalledPacks`、`scanIocPacks`、`summarizePacks`。 |
|
|
293
|
+
| xcube-catalog.ts(117) | 由 scripts/gen-xcube-catalog.mjs 生成的包目录(159 条)。`XCUBE_CATALOG_ENTRY_COUNT = XCUBE_PACK_CATALOG.length`(审计 A23:不要把条目数写成数字常量,重跑脚本会回写旧值)。 |
|
|
294
|
+
|
|
295
|
+
### 5.8 工具链安装(1 个,2313 行)
|
|
296
|
+
|
|
297
|
+
| 模块 | 职责与关键导出 |
|
|
298
|
+
| --- | --- |
|
|
299
|
+
| msys2-install.ts(2313) | 最大也最脏的一块:下载 MSYS2 安装包 → 静默安装 → pacman 装 5 个组件 → 写用户级 PATH → 写配置 → 自检。关键导出:`MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_BYTES`、`DEFAULT_MSYS2_PACKAGES`、`MSYS2_SUGGESTED_ROOT`、`planOrInstallMsys2(subprocess, request)`(plan / install 两条路)、`msys2StepSkeleton`、`parsePacmanQuery`、`resolveInstallerUrls(env)`(**F3a 候选链**:`MSYS2_INSTALLER_URL` 单源 > `MSYS2_MIRROR` > 清华 TUNA / 中科大 USTC / 南大 NJU / 阿里云 × 两个文件名 > GitHub,共 10 个候选;`installerSourceLabel` 把 URL 变成「清华 TUNA」这样的人话)、`installerSourceLabel`、`preferMirrorServers(text, servers)` / `preferChinaMirrors(msys64)`(**F3b**:只把国内镜像插到 `etc/pacman.d/mirrorlist.msys` 与 `mirrorlist.mingw` 最前,官方条目不删,幂等,已有 MSYS2 一个字都不改)、`resolveTargetDir` / `viaLabel`、`formatBytes`、`isDriveRoot` / `ensureParentDir`(盘根不能 mkdir,审计 ③)、`usageNote` / `planMessage`(**计划模式只报缺件**:已装齐时 steps 为空、download.bytes 0、一句话收尾)。**F3d 三道粗检**:缓存要 MZ 头 + ≥ `MIN_INSTALLER_BYTES`(40 MB)才算数(`cachedInstallerBytes`);下载后查退出码/体量/MZ;解压后再查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删)。**F3c**:`curl -C -` 同源续传、`--speed-limit 1024 --speed-time 10` 低速自退(退出码 28 单独说明),退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次,换源前删 `.part`。 |
|
|
300
|
+
|
|
301
|
+
### 5.9 设置面板的宿主侧(2 个,577 行)
|
|
302
|
+
|
|
303
|
+
| 模块 | 职责与关键导出 |
|
|
304
|
+
| --- | --- |
|
|
305
|
+
| 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`。 |
|
|
306
|
+
| web-routes.ts(100) | 薄适配层:`ctx.inject(["webServer"], ...)` 里 `server.register({ kind: "exact", path, handler })`,把 request/response 收成 `handleWebApi` 的输入输出,加 `cache-control: no-store`。宿主没 webServer 服务时静默跳过(面板不可用,工具照常)。 |
|
|
307
|
+
|
|
308
|
+
### 5.10 路线评估(1 个,645 行)
|
|
309
|
+
|
|
310
|
+
| 模块 | 职责与关键导出 |
|
|
311
|
+
| --- | --- |
|
|
312
|
+
| route-plan.ts(645) | 「这笔功能该走 HAL 还是寄存器」。`PERIPHERAL_RULES`(外设规则表:关键词 → HAL/寄存器各自的代价与风险)、`assessRoute(input)` → `RouteAssessment`(verdict:hal-only / both-viable / register-ok / unclear)、`familyOf`、`findFirmwarePackage`、`VERDICT_LABEL`。工具层再把它和门禁、安装指引拼成一份输出。 |
|
|
313
|
+
|
|
314
|
+
## 6. data 层:8 张事实表(2548 行)+ 1 份生成的芯片薄表
|
|
315
|
+
|
|
316
|
+
| 模块 | 行数 | 内容 |
|
|
317
|
+
| --- | --- | --- |
|
|
318
|
+
| chips.ts | 202 | 内置 `CHIPS` 芯片表(F103C8T6 等)、`findChip`、`isKnownPin`(未知型号一律放行,不猜),外加**由本机 CubeMX db 派生引脚表**的一整套:`parseMcuDbXmlPins`(`<Pin Name= Position=>`,`Position<=0` 的虚拟脚丢弃,`PC13-TAMPER-RTC → PC13`,电源脚不算)、`findMcuDbDir`(`<CubeMX>/db/mcu`)、`readMcuDbPins`、`deriveChipPinTable({cpn, mcuName, dbMcuDir})` → `kind: db / builtin / unknown`(db 命中就注明来源 XML 与引脚数,否则明说「未与本机 db 校验」)。引脚合法性由它兜底。 |
|
|
319
|
+
| cmsis-sources.ts | 392 | 寄存器路线的下载源与型号映射:四个镜像(jsdelivr fastly/cdn、raw.githubusercontent、ghproxy)、`CMSIS_FAMILIES`、`startupChoiceFor(mcu)`(委托 resolveF1Chip,兼容 `F1:B` / `F1:8` / `F103:xb` / `STM32F103C8T6` 四种写法)、`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 真实下载实测的。 |
|
|
320
|
+
| stm32f1.ts | 234 | F1 的容量档事实表(两条路线共用的唯一型号来源)。`F1_LINES`(6 条 line:100 xb/xe、101 x6/xb/xe/xg、102 x6/xb、103 x6/xb/xe/xg、105 xc、107 xc)、`GROUP_BY_LETTER`、`FLASH_BY_LETTER`、`RAM_BY_LINE_LETTER`(同字母在不同 line 差很多:字母 C 在 F103 是 256 KiB Flash / 48 KiB RAM,在 F105/F107 是 64 KiB RAM)、`PINS_BY_PACKAGE`(T36 / C48 / R64 / V100 / Z144)、`resolveF1Chip(input)` → `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`。 |
|
|
321
|
+
| 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 名单。 |
|
|
322
|
+
| firmware-packages.ts | 463 | 固件包事实表:`FIRMWARE_FAMILIES`(目前只有 F1)、`firmwareFamilyOf`、`firmwareVersionTags`、`packageXmlText`、`firmwarePlanFor`、`verifyFirmwarePackage`、`DSH_FIRMWARE_DIR_NAME = "dsh-firmware"`、`dshFirmwareDir`、`firmwareNeedFromIoc`(从 .ioc 的包名推族与版本)、`looksLikeFirmwarePackage`、`locateFirmwarePackage(root, packageName, extraDirs)` → `FirmwareLocation`(source:repository / dsh-firmware / cache / custom)、`firmwareSourceLabel`、`FirmwareExtraDir`。 |
|
|
323
|
+
| install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
|
|
324
|
+
| search-roots.ts | 421 | 见 5.2。 |
|
|
325
|
+
| toolchain-config.ts | 370 | 见 5.2。 |
|
|
326
|
+
| chip-table.json | 2044 | **脚本生成的薄表**(`node scripts/gen-chip-table.mjs` 产出,不要手改):2016 颗芯片的 CPN / 内核 / 主频 / RAM / Flash / 电压 / 引脚数,来源是本机 CubeMX 的 `db/mcu/*.xml`。插件当前只消费 F1 那一段,其余为将来扩族备查;`--check` 模式给 CI 用(生成物与 db 不一致就红)。 |
|
|
327
|
+
|
|
328
|
+
## 7. 关键流程
|
|
329
|
+
|
|
330
|
+
这一章是全书重点:每个流程都给「一张图 + 几个必须知道的失败面」。看图时对照第 5 章的模块表找文件。
|
|
331
|
+
|
|
332
|
+
### 7.1 一次工具调用的通用管线
|
|
333
|
+
|
|
334
|
+
```mermaid
|
|
335
|
+
sequenceDiagram
|
|
336
|
+
participant U as 模型/用户
|
|
337
|
+
participant H as DSH 宿主
|
|
338
|
+
participant T as src/tools/x.ts
|
|
339
|
+
participant E as src/engine
|
|
340
|
+
participant S as 宿主 subprocess
|
|
341
|
+
participant B as gcc/cmake/openocd/CubeMX
|
|
342
|
+
U->>H: 调工具 + JSON 参数
|
|
343
|
+
H->>T: execute(args, exec)
|
|
344
|
+
T->>T: resolveProjectDir + validateToolArgs
|
|
345
|
+
T->>E: ensureToolchain(capability, envCheck)
|
|
346
|
+
E-->>T: GateResult{ok, missing[], install[]}
|
|
347
|
+
alt 门禁拦截
|
|
348
|
+
T-->>H: blockedReport 同形报告
|
|
349
|
+
else 门禁通过
|
|
350
|
+
T->>E: run*(subprocess, request)
|
|
351
|
+
E->>S: spawn{argv, cwd, env, stdio.maxBytes}
|
|
352
|
+
S->>B: 真进程
|
|
353
|
+
B-->>S: stdout/stderr + exitCode
|
|
354
|
+
S-->>E: RunOutcome
|
|
355
|
+
E-->>T: Report
|
|
356
|
+
T->>T: render(report) → 中文行
|
|
357
|
+
T-->>H: report(必须过 output.schema)
|
|
358
|
+
end
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
必须知道的失败面:
|
|
362
|
+
- **输出 schema 是硬约束**:report 多一个没声明的字段,宿主就判「非法输出」。改 report 必改 schema,并用 test/schema-guard.mjs 兜住。
|
|
363
|
+
- **exec.signal 一路要透传**:工具超时/用户取消 → spawn 被 abort → RunOutcome.aborted=true → report 里写「已取消」。任何一格没接 signal,取消就变成「等 30 秒超时」。
|
|
364
|
+
- **门禁在工具层**:engine 不知道门禁存在,所以 engine 的返回永远按「工具链就位」写文案。
|
|
365
|
+
|
|
366
|
+
### 7.2 工具链门禁:快路径、慢路径与缓存
|
|
367
|
+
|
|
368
|
+
```mermaid
|
|
369
|
+
flowchart TD
|
|
370
|
+
A["ensureToolchain(capability, envCheck)"] --> B{"envCheck = off?"}
|
|
371
|
+
B -->|是| PASS["ok=true 直接放行"]
|
|
372
|
+
B -->|否| C["CAPABILITY_COMPONENTS 列必需组件"]
|
|
373
|
+
C --> D{"快路径:binDirs 里文件都在?"}
|
|
374
|
+
D -->|是| E["smokeTarget:跑一次主组件的版本命令<br/>build→gcc flash→openocd debug→gdb generate→cubemx-java<br/>60 s 缓存"]
|
|
375
|
+
E -->|跑通| PASS
|
|
376
|
+
E -->|失败| F["按缺件处理,error 写「文件在但版本命令没跑通」"]
|
|
377
|
+
D -->|否| G["慢路径:probeAll 全量探测<br/>allowPathFallback 默认开"]
|
|
378
|
+
G --> H{"signal.aborted?"}
|
|
379
|
+
H -->|是| I["break:不写缓存(审计 A27)"]
|
|
380
|
+
H -->|否| J["probeCache.set(key, {at, results}) 60 s"]
|
|
381
|
+
J --> K{"有缺件?"}
|
|
382
|
+
F --> K
|
|
383
|
+
K -->|无| PASS
|
|
384
|
+
K -->|有| L{"envCheck = warn?"}
|
|
385
|
+
L -->|是| M["ok=true + warnings 一行"]
|
|
386
|
+
L -->|否| N["ok=false + missing[](含 hint/impact/install/verify)"]
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
为什么快路径也要跑版本命令(审计 B13):「文件存在」不等于「文件能跑」——半截下载、被杀软隔离、架构不对、0 字节,都表现为文件在而进程起不来。只对**主组件**做 smoke,是为了保住快路径「零全量 spawn」的价值;其余组件坏了慢路径照样兜住。
|
|
390
|
+
|
|
391
|
+
### 7.3 project_create:两条完全不同的路线
|
|
392
|
+
|
|
393
|
+
```mermaid
|
|
394
|
+
flowchart TD
|
|
395
|
+
A["stm32_project_create{targetDir, projectName, route}"] --> P["preflightTarget:<br/>1 工程名是 C 标识符<br/>2 目录非空 → 拒绝<br/>3 hal 且已有同名 .ioc → 拒绝并指向 ioc_plan/apply"]
|
|
396
|
+
P --> R{"route?"}
|
|
397
|
+
R -->|register| S1["ensureCmsisTemplate:<br/>按型号选启动文件 → 下载 10 个文件 → sha256 校验 → 落缓存"]
|
|
398
|
+
S1 --> S2["createRegisterProject:<br/>拷模板 7 件(含 .gitignore、openocd.cfg、链接脚本)<br/>写设备头/启动文件/system.c/main.c"]
|
|
399
|
+
S2 --> S3["模板缺失分流:必需 → 一次列全并拒绝<br/>可选(.gitignore) → warning 继续"]
|
|
400
|
+
R -->|hal| H1["resolveFirmwareRoot:Repository → dsh-firmware → extraDirs<br/>找不到就带安装指引失败"]
|
|
401
|
+
H1 --> H2["backupBeforeOverwrite:只备份真会被覆盖的文件<br/>备份失败 → 一字不写"]
|
|
402
|
+
H2 --> H3["createProjectScaffold:拷 15 个模板 + 从固件包拷 Drivers/238 件<br/>复制走 fs-longpath"]
|
|
403
|
+
H3 --> H4["写 .vscode/:按本机探测填占位符,没值的整行删掉并记 warning"]
|
|
404
|
+
S3 --> DONE["报告:templateFiles / driverFiles / firmwareRoot / warnings"]
|
|
405
|
+
H4 --> DONE
|
|
406
|
+
DONE --> FAIL{"中途失败?"}
|
|
407
|
+
FAIL -->|是| CL["cleanupAfterFailure:只回收本次新建<br/>原有目录只 rmdir 空目录"]
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
两条路线的共同点只有「先预检、再备份、失败回收」。区别是 hal 依赖 CubeMX 固件包(无网也能用整目录拷贝),register 依赖网络下载 CMSIS(但缓存命中后完全离线)。
|
|
411
|
+
|
|
412
|
+
### 7.4 build:preset → 编译 → 产物
|
|
413
|
+
|
|
414
|
+
```mermaid
|
|
415
|
+
flowchart LR
|
|
416
|
+
A["runBuild"] --> B["pickConfigurePreset<br/>优先 Debug"]
|
|
417
|
+
B --> C["cmake --preset=<name><br/>env 注入 binDirs + 原 PATH"]
|
|
418
|
+
C --> D["cmake --build --preset=<name>"]
|
|
419
|
+
D --> E["findElf → pickElf:CMakeCache 工程名优先<br/>否则取 mtime 最新的 .elf;elfSelectionNote 进 notes"]
|
|
420
|
+
E --> F["parseMemoryUsage / parseBuildErrors / countWarnings"]
|
|
421
|
+
F --> G{"artifacts 里要 hex/bin?"}
|
|
422
|
+
G -->|是| H["arm-none-eabi-objcopy -O ihex / binary<br/>失败只写 note,不判 build 失败"]
|
|
423
|
+
G -->|否| I["报告"]
|
|
424
|
+
H --> I
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
选哪个 .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 都会带这条说明。
|
|
428
|
+
|
|
429
|
+
坑:**复制过的工程**(CMakeCache 里记着别的路径)会报奇怪的错,build.ts 里有显式拦截:检测到 CMakeCache 的源目录与当前工程不一致就直接给「把 build/ 删掉重配」。
|
|
430
|
+
|
|
431
|
+
### 7.5 flash:守卫 → 烧录 → 判定 → 错误分类
|
|
432
|
+
|
|
433
|
+
```mermaid
|
|
434
|
+
flowchart TD
|
|
435
|
+
A["stm32_flash"] --> B["releaseProbeFor:先还探针(审计 B16)"]
|
|
436
|
+
B --> C["checkNoDebugGuard(projectDir, allowNoDebug, iocPath)"]
|
|
437
|
+
C --> C1{"有唯一 .ioc?"}
|
|
438
|
+
C1 -->|有| C2["PA13=SYS_JTMS-SWDIO / PA14=SYS_JTCK-SWCLK / Mode=Serial_Wire?"]
|
|
439
|
+
C1 -->|没有或多个| C3["看 openocd.cfg 的 transport:swd 放行并说明依据<br/>jtag 提示引脚复用<br/>都没有 → notes 两条「守卫没生效」"]
|
|
440
|
+
C2 -->|是 No_Debug| BLOCK["blocked:拒绝,除非 allowNoDebug"]
|
|
441
|
+
C2 -->|是 Serial Wire| D["resolveElf(内部 findElf → pickElf,notes 说明选中的是哪个)"]
|
|
442
|
+
C3 --> D
|
|
443
|
+
D --> E["findProjectConfig:openocd.cfg 优先<br/>否则 interface/cmsis-dap.cfg + target/stm32f1x.cfg"]
|
|
444
|
+
E --> F["openocd -f ... -c program <elf> verify reset exit"]
|
|
445
|
+
F --> G["parseFlashLog:认 Programming Finished / Verified OK<br/>成功序列里的偶发 Error 行进 noise"]
|
|
446
|
+
G --> H{"ok?"}
|
|
447
|
+
H -->|是| OK["programmed + verified,errorCode 缺省"]
|
|
448
|
+
H -->|否| I["errorCodeOfLines 分类:no-probe / probe-busy / swd-locked / flash-protected / no-power / target-mismatch / unknown"]
|
|
449
|
+
I --> J["notes:USB 形态(usbNoteFor)+ probe-busy 专用提示(HINT_BUSY)"]
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
真板子取证过的一个细节:两个进程同时访问同一个 CMSIS-DAP 时,日志不是「设备忙」,而是交替出现 CMSIS-DAP command mismatch / transfer count mismatch / Failed to write memory at 0x00000004。所以 errorCodeOfLines 里专门把这几种行归到 probe-busy。
|
|
453
|
+
|
|
454
|
+
### 7.6 调试三件套与会话租约
|
|
455
|
+
|
|
456
|
+
```mermaid
|
|
457
|
+
stateDiagram-v2
|
|
458
|
+
[*] --> 空闲
|
|
459
|
+
空闲 --> 启动中: stm32_debug_session(start)
|
|
460
|
+
启动中 --> 活跃: openocd 常驻 + 首次 gdb -batch 连上
|
|
461
|
+
启动中 --> 空闲: 端口占用 / 探针失败、带 errorCode 提示
|
|
462
|
+
活跃 --> 活跃: stm32_debug_eval、每次新起 gdb -batch:连上 → halt → 命令 → resume → detach
|
|
463
|
+
活跃 --> 空闲: stm32_debug_stop
|
|
464
|
+
活跃 --> 空闲: 空闲 90 s
|
|
465
|
+
活跃 --> 空闲: 总时长 10 min
|
|
466
|
+
活跃 --> 空闲: turn/end、本轮输出结束
|
|
467
|
+
活跃 --> 空闲: session/disposed / 插件 dispose
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
三条设计理由:
|
|
471
|
+
1. **只有 openocd 常驻**,gdb 每次短命——gdb 崩了不会把会话带死,也避免 gdb 自己攒一堆状态。
|
|
472
|
+
2. **归属(A9)**:turn/end 事件里尽量掏 agent id,只关这条会话自己开的;掏不到就全关(宁可按最短释放,也不攥着探针)。
|
|
473
|
+
3. **别人要用探针先 releaseProbeFor**:flash / regs_read / debug_run 都在自己起 openocd 之前调它,否则就是「两个 openocd 抢一个 CMSIS-DAP」。
|
|
474
|
+
|
|
475
|
+
**debug_run 失败时说什么**(0.1.2 修复):以前只回一句「openocd 起不来」外加日志最后 15 行,真正的原因(adapter init 失败、探针被占)常被后面的噪声挤掉。现在先按 flash 同一套 `errorCodeOfLines` 归类,再用 `debugHintFor` 给一条可执行提示,`probeMissingLines` 命中时顺手跑 `usbDiagnosis` 分清「没插 / 没认到 / 驱动异常」,日志改用 `keyLogTail` 挑有信息量的行,`firstProblemLine` 把首条根因写进 errors。报告里的 `errorCode` 是**可选字段**(成功时不出现),且必须在 tools/debug.ts 的 reportSchema 里声明——漏声明就会重演 flash 那次「失败路径被判非法输出」。
|
|
476
|
+
|
|
477
|
+
### 7.7 .ioc 事务:plan → 用户确认 → apply / rollback
|
|
478
|
+
|
|
479
|
+
```mermaid
|
|
480
|
+
sequenceDiagram
|
|
481
|
+
participant M as 模型
|
|
482
|
+
participant P as stm32_ioc_plan
|
|
483
|
+
participant A as stm32_ioc_apply
|
|
484
|
+
participant F as demo.ioc
|
|
485
|
+
M->>P: entries / unset / pins / serialWire
|
|
486
|
+
P->>F: 只读解析 + 逐键 diff
|
|
487
|
+
P-->>M: planId + sourceSha256 + changes[](不写盘)
|
|
488
|
+
M->>M: 决定要不要动(用户确认)
|
|
489
|
+
M->>A: {planId}
|
|
490
|
+
A->>F: 重新算 SHA-256 并比对
|
|
491
|
+
alt SHA 变了
|
|
492
|
+
A-->>M: 拒绝:源文件已被改过,重新 plan
|
|
493
|
+
else SHA 一致
|
|
494
|
+
A->>F: 备份到 .dsh-stm32/backups/<stamp>-ioc
|
|
495
|
+
A->>F: 原子替换(写 tmp → rename)
|
|
496
|
+
A-->>M: appliedChanges + backupPath
|
|
497
|
+
end
|
|
498
|
+
M->>A: {rollbackFrom: backupPath}
|
|
499
|
+
A->>F: 先备份当前内容,再写回备份
|
|
500
|
+
A-->>M: rolledBack=true
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
.ioc 是唯一的「配置真相」,所以它有三重保护:**不写盘的计划阶段**、**SHA 校验**、**每次写前都备份**。引脚写入保序(审计 A3)也是为这条服务的:无意义的顺序抖动会让 diff 看起来像改了很多东西。
|
|
504
|
+
|
|
505
|
+
### 7.8 generate:CubeMX 无头模式的全流程
|
|
506
|
+
|
|
507
|
+
```mermaid
|
|
508
|
+
flowchart TD
|
|
509
|
+
A["runGenerate"] --> B["findIocFile:只认唯一 .ioc"]
|
|
510
|
+
B --> C["acquireLock:lock.json{pid, startedAt, purpose}<br/>isProcessAlive 探活,30 min 兜底"]
|
|
511
|
+
C --> D["固件包定位:Repository → dsh-firmware → extraDirs<br/>同时算出 firmwareSource"]
|
|
512
|
+
D --> E["detectLayout:coupled / per-ip"]
|
|
513
|
+
E --> F["cacheKey = sha256(.ioc) + cubeMxStamp(java,jar) + layout"]
|
|
514
|
+
F --> G{"缓存命中且文件 hash 全对?"}
|
|
515
|
+
G -->|是| Z["直接复用上次产物(skipped=true)"]
|
|
516
|
+
G -->|否| H["thirdparty:无 X-CUBE 包时临时停放 pdsc 索引(省约 25 s)"]
|
|
517
|
+
H --> I["写 CubeMX 脚本到 .dsh-stm32/tmp/gen-<stamp>.txt<br/>-Dfile.encoding=UTF-8 + setCustomFWPath"]
|
|
518
|
+
I --> J["java -jar STM32CubeMX.exe -q <script>"]
|
|
519
|
+
J --> K["parseGenerateLog:UNKNOWN_COMMAND → commandErrors<br/>成功行不再一票否决错误"]
|
|
520
|
+
K --> L["恢复 pdsc 索引(finally)"]
|
|
521
|
+
L --> M["搬产物:.dsh-stm32/gen/Src|Inc → Core/Src|Inc<br/>旧文件先读编码 → 认不出就 skipped-encoding<br/>能读就 mergeUserCode 保 USER CODE"]
|
|
522
|
+
M --> N["assessGenerateProducts:产物判据决定 ok<br/>(CubeMX 缺包时也会打 successfully generated)"]
|
|
523
|
+
N --> O["写 generate-cache(key + 每个文件 sha256)"]
|
|
524
|
+
O --> P["refreshCubemxCmakeLists:源清单跟着 startup / hal_conf 走<br/>设备宏、startup、HAL 模块清单三块;内容没变不写盘"]
|
|
525
|
+
Z --> P2["缓存命中分支同样调一次 refresh"]
|
|
526
|
+
P --> R["releaseLock(rm lock.json)"]
|
|
527
|
+
P2 --> R
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
四个坑:
|
|
531
|
+
- **源清单不会自己长**: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,带真工具链差分验证)。
|
|
532
|
+
- **锁的探活**:早期只看 pid+时间,进程崩了要等 30 分钟;现在先 isProcessAlive(pid),死了立刻接管(审计 A14)。
|
|
533
|
+
- **成功日志不等于成功**:CubeMX 缺固件包/包版本不认时也打 Code successfully generated,所以 ok 必须有产物判据(审计 A10)。
|
|
534
|
+
- **中文路径**:脚本按 UTF-8 写且启动 java 时指定 -Dfile.encoding=UTF-8(审计 B18);否则中文工程路径在脚本里变乱码。
|
|
535
|
+
|
|
536
|
+
### 7.9 code_patch:只改块内,按字节写回
|
|
537
|
+
|
|
538
|
+
```mermaid
|
|
539
|
+
flowchart TD
|
|
540
|
+
A["patchUserCode{file, block, code, mode}"] --> B["读成 Buffer(不按 utf8 直读)"]
|
|
541
|
+
B --> C["detectEncoding:BOM/严格 UTF-8/GB18030<br/>unknown → 拒绝,一个字节都不动"]
|
|
542
|
+
C --> D["定位块:正则认 USER CODE BEGIN/END 标记"]
|
|
543
|
+
D --> E{"块内含 { 或 }?"}
|
|
544
|
+
E -->|是| X["拒绝:那是结构行,不许塞代码"]
|
|
545
|
+
E -->|否| F["lineStarts 算出块的起止行"]
|
|
546
|
+
F --> G["replaceLineRange:未改的行原字节照抄<br/>只把新增行按原编码插入,保留 CRLF/LF"]
|
|
547
|
+
G --> H{"结果与原文相同?"}
|
|
548
|
+
H -->|是| Y["回一句「内容没有变化」"]
|
|
549
|
+
H -->|否| I["备份到 .dsh-stm32/backups/<stamp>-patch"]
|
|
550
|
+
I --> J["写 tmp → rename(原子)"]
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
为什么要字节级拼接而不是「读成字符串再写回」:GB18030 的文件 Node 能解不能编,整份重新编码会把用户的中文注释写成问号。现在的策略是「动的只有块内那几行,其余字节原样搬运」。
|
|
554
|
+
|
|
555
|
+
### 7.10 firmware_install:选址、下载、组装、记录
|
|
556
|
+
|
|
557
|
+
```mermaid
|
|
558
|
+
flowchart TD
|
|
559
|
+
A["firmwarePlanFor{family, mcu, version}"] --> B["选址 decideTarget:<br/>已有包? → existing<br/>CubeMX 目录可用? → <root>/dsh-firmware<br/>否则 cache/custom"]
|
|
560
|
+
B --> C{"受保护目录?<br/>Program Files / ProgramData / SystemRoot"}
|
|
561
|
+
C -->|是| X["判不可写,给下一步建议"]
|
|
562
|
+
C -->|否| D["download:2 个归档 + 5 个内核头<br/>每个都过 sha256"]
|
|
563
|
+
D --> E["extractTarGz:路径白名单 + 类型白名单 + 截断检测"]
|
|
564
|
+
E --> F["补 package.xml(版本 tag)"]
|
|
565
|
+
F --> G["verifyFirmwarePackage:Drivers/CMSIS、startup、hal 源都在?"]
|
|
566
|
+
G --> H["写 installed.json 记录(targetDir + 版本 + 时间)"]
|
|
567
|
+
H --> I["nextStep:告诉用户接下来 stm32_project_create 还是 stm32_generate"]
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
为什么装到 <CubeMX>/dsh-firmware 而不是塞进官方 Repository:CubeMX 会静默忽略自造版本号的包;真正生效的是生成脚本里的 project setCustomFWPath。所以「包放哪」和「CubeMX 认不认」是两件事——这一点写在 docs/development-notes.md §14.1。
|
|
571
|
+
|
|
572
|
+
### 7.11 env_install 的计划模式:只报缺件
|
|
573
|
+
|
|
574
|
+
```mermaid
|
|
575
|
+
flowchart TD
|
|
576
|
+
A["stm32_env_install{mode=plan}"] --> B["isMsys2Root(msys64):有 usr/bin/bash.exe 且 pacman 在?"]
|
|
577
|
+
B -->|是| C["只读问 pacman:pacman -Q <5 个包><br/>超时 60 s,问不出来就不编清单"]
|
|
578
|
+
B -->|否| D["按全新安装估算(43.1 MB 下载)"]
|
|
579
|
+
C --> E["在目标 binDir 里跑 5 个版本命令<br/>allowPathFallback=false"]
|
|
580
|
+
E --> F{"5 个都跑通?"}
|
|
581
|
+
F -->|是| G["什么都不用装:steps=[]、download.bytes=0、一句话收尾"]
|
|
582
|
+
F -->|否| H["只列缺的包/步骤;已装的不动、也不升级"]
|
|
583
|
+
D --> I["完整 7 步计划:下载 → 解压 → pacman → PATH → 配置 → 自检"]
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
两条原则:**计划模式绝不写盘**(只读 pacman query + 只读版本命令),**已经就位的东西不列**(用户明确提过:工具链完整时卡片不该再显示 43.1 MB)。
|
|
587
|
+
|
|
588
|
+
### 7.12 export:把工程打成 zip
|
|
589
|
+
|
|
590
|
+
```mermaid
|
|
591
|
+
flowchart LR
|
|
592
|
+
A["runExport{projectDir, outDir, includePrebuilt}"] --> B["collectSources:递归收集<br/>跳过 build / .dsh-stm32 / node_modules / .git"]
|
|
593
|
+
B --> C{"includePrebuilt?"}
|
|
594
|
+
C -->|是| D["带上 elf/hex/bin 到 prebuilt/"]
|
|
595
|
+
C -->|否| E["只要源码"]
|
|
596
|
+
D --> F["readmeText(可选内联 README)"]
|
|
597
|
+
E --> F
|
|
598
|
+
F --> G["makeZip:store-only(不压缩,零依赖)→ <name>-export.zip"]
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
为什么 zip 里一定没有 build/:CMakeCache 记着本机的绝对路径,带过去只会在别人机器上报错。所以导出的是「能重新配置的源码」,不是「能直接烧的构建目录」。
|
|
602
|
+
|
|
603
|
+
### 7.13 设置面板:浏览器 bundle 到宿主 API
|
|
604
|
+
|
|
605
|
+
```mermaid
|
|
606
|
+
sequenceDiagram
|
|
607
|
+
participant C as client/client.js(浏览器)
|
|
608
|
+
participant S as 宿主 webServer
|
|
609
|
+
participant R as engine/web-routes.ts
|
|
610
|
+
participant A as engine/web-api.ts
|
|
611
|
+
participant E as probe / msys2-install / toolchain-config
|
|
612
|
+
C->>S: GET /dsh-stm32/api/config
|
|
613
|
+
S->>R: handler(request, response)
|
|
614
|
+
R->>A: handleWebApi({method, path, body})
|
|
615
|
+
A->>E: configSnapshot / probeTools / installPlan
|
|
616
|
+
E-->>A: 结果
|
|
617
|
+
A-->>R: {status, body}
|
|
618
|
+
R-->>C: JSON(cache-control: no-store)
|
|
619
|
+
Note over C,A: 安装是长任务:install/start 返回 taskId,前端 setTimeout 递归轮询 install/state
|
|
620
|
+
```
|
|
621
|
+
|
|
622
|
+
三个契约:**路由全是 exact**(不抢别的前缀)、**请求体上限 1 MB**、**任务表在进程内**(宿主重启就丢,前端会显示「任务不存在」并允许重新发起)。前端只 require 外壳种子(react / jsx-runtime / primitives),不经打包器,因为宿主以 /plugins/dsh-stm32/client.js 直接提供。
|
|
623
|
+
|
|
624
|
+
### 7.14 斜杠命令:切词 → 门禁警告 → 调 engine
|
|
625
|
+
|
|
626
|
+
```mermaid
|
|
627
|
+
flowchart LR
|
|
628
|
+
A["/stm32-flash \"C:/Users/zhang san/proj\" --no-debug"] --> B["tokenizeCommandLine<br/>引号内不切、剥引号、记 quoted"]
|
|
629
|
+
B --> C["parseInvocation:第一个非 flag token = 工程目录"]
|
|
630
|
+
C --> D["commandGateWarning(capability, warn)<br/>缺件只警告不拒绝"]
|
|
631
|
+
D --> E["engine(与工具同一个函数)"]
|
|
632
|
+
E --> F["CommandResult{kind: success|error, text}"]
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
命令是「用户手打的快捷方式」,所以它的门禁是 warn:用户可能就想让插件跑起来看看报什么错。工具是「模型调的」,门禁才是 block。
|
|
636
|
+
|
|
637
|
+
## 8. 不变量与陷阱
|
|
638
|
+
|
|
639
|
+
这些条目破一条就会出真问题,改代码前先扫一眼。
|
|
640
|
+
|
|
641
|
+
| # | 不变量 | 破了会怎样 | 在哪体现 |
|
|
642
|
+
| --- | --- | --- | --- |
|
|
643
|
+
| 1 | 代码只写在 USER CODE 块内 | 下次生成被无声覆盖,编译还不报错 | skill R1/R2、usercode-merge.ts |
|
|
644
|
+
| 2 | .ioc 只能 plan → apply(带 planId) | 配置被手改后与 CubeMX 理解不一致 | skill R3、ioc-plan.ts |
|
|
645
|
+
| 3 | 不许生成 No_Debug 的 SYS | SWD 永久失联,只能 BOOT0 救 | skill R4、flash.checkNoDebugGuard、ioc.summarizeIoc 警告 |
|
|
646
|
+
| 4 | 覆盖文件前必须备份 | 用户代码丢失 | scaffold.backupBeforeOverwrite、ioc-plan、code-patch |
|
|
647
|
+
| 5 | 编码认不出就拒绝写 | 中文注释变问号 | text-file.detectEncoding、code-patch、generate 的 skipped-encoding |
|
|
648
|
+
| 6 | report 结构必须与 output.schema 一致 | 宿主判「工具返回非法输出」 | 每个 tools/*.ts、test/schema-guard.mjs |
|
|
649
|
+
| 7 | 子进程必须显式 cwd + 注入 env | 新装的工具链找不到 | subprocess-runner.ts、tool-env.ts |
|
|
650
|
+
| 8 | 动探针前先 releaseProbeFor | 两个 openocd 抢一个探针 | flash / regs / debug_run 入口 |
|
|
651
|
+
| 9 | turn/end 必须把探针还回去 | 用户在 VS Code 里按 F5 失败 | src/index.ts |
|
|
652
|
+
| 10 | 取消时不得写缓存 | 取消后仍走「已探测」假象 | toolchain-gate(A27) |
|
|
653
|
+
| 11 | 长路径走 \\?\ 前缀 | 深目录复制 ENAMETOOLONG | fs-longpath.ts |
|
|
654
|
+
| 12 | 解包走路径与类型白名单 | zip-slip / 设备文件写进系统 | tar.ts |
|
|
655
|
+
| 13 | 缓存索引写入可恢复 | 半截索引导致缓存全废 | cache.ts(broken/bak + CacheIndexWriteError) |
|
|
656
|
+
| 14 | 门禁快路径也要 smoke | 「文件在但跑不起来」被判齐全 | toolchain-gate(B13) |
|
|
657
|
+
| 15 | 安装自检不许 PATH 兜底 | 用系统里的旧工具冒充新装 | probe 的 allowPathFallback=false |
|
|
658
|
+
| 16 | 计划模式绝不写盘 | 用户以为只是看一眼,结果被改了 | msys2-install / firmware-install 的 plan 分支 |
|
|
659
|
+
| 17 | 模板里不许出现开发机绝对路径 | 新工程 F5 直接失败 + 泄露用户名 | vscode-config.ts + templates/ |
|
|
660
|
+
| 18 | 生成成功以产物为准,不以日志为准 | 缺包时误报成功 | generate.assessGenerateProducts |
|
|
661
|
+
| 19 | 生成期间 pdsc 停放必须在 finally 还原 | 用户的第三方包索引「消失」 | thirdparty.ts + generate.ts |
|
|
662
|
+
| 20 | 零运行时依赖、lib/ 入库 | 装上就坏 / 用户机器没有编译器 | package.json、tsconfig |
|
|
663
|
+
| 21 | cmake 源清单必须跟着 startup 与 hal_conf 走 | 开了外设也链接失败(undefined reference to HAL_xxx_Init) | cmake-sources.refreshCubemxCmakeLists、generate.ts 两处调用 |
|
|
664
|
+
| 22 | 链接脚本按 `<DeviceId>` 命名,命令行上只能有一个 `-T` | 链接的是别人的 MEMORY:编译过、烧到小容量芯片上跑飞(.ld 说 256 KiB,实际只有 64 KiB) | hal-chip.pointLinkerFlagAt、register-linker.renderLinkerScript、doctor.checkChipConsistency ①③ |
|
|
665
|
+
|
|
666
|
+
## 9. 测试体系
|
|
667
|
+
|
|
668
|
+
### 9.1 三层
|
|
669
|
+
|
|
670
|
+
| 层 | 位置 | 说明 |
|
|
671
|
+
| --- | --- | --- |
|
|
672
|
+
| 单元/契约 | test/*.test.mjs + test/schema-guard.mjs | 29 个套件 418 例(schema-guard 25 例),全部离线:假 subprocess、假 fs、固定夹具。**这是回归的主力** |
|
|
673
|
+
| e2e 脚本 | test/e2e-*.mjs(15 个) | 开发期手动跑的端到端(真 CubeMX / 真 openocd / 真工具链),不进 npm test |
|
|
674
|
+
| 发布形态 | scripts/pack-smoke.mjs(npm run test:pack)+ scripts/pack-size.mjs(npm run test:size) | npm pack → 解包 → 断言 16 个必须文件 → 用解包出来的 lib 真建一个寄存器工程;pack-size 再守包体(tarball ≤1.2 MB、templates/** ≤60 KB、包内禁二进制、必需文件齐全)。CI 上两连跑 |
|
|
675
|
+
|
|
676
|
+
### 9.2 29 个套件一览(test/run-units.mjs 的 suites 数组顺序)
|
|
677
|
+
|
|
678
|
+
build-units、cache-units、stm32f1-units、hal-route-units、clock-units、doctor-chip-units、cmake-sources-units、commands-units、doctor-regs-units、engine-units、export-units、firmware-units、flash-units、generate-cache-units、ioc-plan-units、install-units、ioc-units、route-plan-units、scaffold-patch-units、search-roots-units、session-units、text-encoding-units、thirdparty-units、tool-contract-units、toolchain-units、vscode-units、web-api-units、xcube-units、schema-guard。
|
|
679
|
+
|
|
680
|
+
开发机上 418 例全跑;CI 上是 **416 pass + 2 skipped**(两条用例依赖本机路径)。
|
|
681
|
+
|
|
682
|
+
约定:
|
|
683
|
+
- 测试 import ../lib/,所以**改 src 必须先 npm run build**(否则测的是旧代码,最容易自欺的地方)。
|
|
684
|
+
- run-units 用 DSH_STM32_NO_CONFIG=1 跑子进程,避免开发机上真实的 ~/.dsh-stm32/config.json 影响断言。
|
|
685
|
+
- 输出解析认四种结尾(node:test spec / tap / 自写 tests N / fail M / inline);解析不到用例数会标红,而不是默默算 0。
|
|
686
|
+
- 套件退出码非 0 一律算失败,即使它自己打印 fail=0。
|
|
687
|
+
- 加套件必须手改 test/run-units.mjs 的 suites 数组——没有自动发现。
|
|
688
|
+
|
|
689
|
+
### 9.3 单测的两种假件套路
|
|
690
|
+
|
|
691
|
+
```ts
|
|
692
|
+
// 套路一:假 subprocess —— 按命令内容返回脚本化输出
|
|
693
|
+
const fake = {
|
|
694
|
+
async resolveExecutable(cmd) { return cmd; },
|
|
695
|
+
spawn(spec) { /* 按 spec.argv 决定往 stdout 写什么 */ },
|
|
696
|
+
};
|
|
697
|
+
|
|
698
|
+
// 套路二:假 fs / 临时目录 —— 真写盘到 os.tmpdir(),测量真实的备份、编码、原子替换
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
凡是「决定行为的分支」都要有脚本化的输出样本,样本**必须是上游真实格式**(审计期间踩过:按文件名猜 CMSIS 守卫宏,测的是假世界)。
|
|
702
|
+
|
|
703
|
+
## 10. 要改东西时动哪里
|
|
704
|
+
|
|
705
|
+
| 想做的事 | 动这些文件 | 别忘了 |
|
|
706
|
+
| --- | --- | --- |
|
|
707
|
+
| 加一个工具 | src/engine/<域>.ts(逻辑)→ src/tools/<x>.ts(schema + 渲染)→ src/index.ts 注册 | output schema、formatXReport、test/tool-contract-units、schema-guard |
|
|
708
|
+
| 改报告字段 | src/tools/<x>.ts 的 reportSchema + 渲染 | schema-guard 必须有对应断言 |
|
|
709
|
+
| 加芯片族(F4/G0…) | src/data/cmsis-sources.ts(启动文件与宏)、firmware-packages.ts(FIRMWARE_FAMILIES 的仓库名要 curl 核实)、data/chips.ts(引脚表可交给 deriveChipPinTable 从 db 派生)、再补一份 clock-f1 那样的时钟上限表(否则寄存器版只能不出 clock_init) | 仓库名不能猜;sha256 逐文件实测并把来源 URL 记进表里(F1 的 14 条就是这么来的) |
|
|
710
|
+
| 加芯片型号(同族容量档) | src/data/stm32f1.ts(容量档与引脚数)→ src/engine/hal-chip.ts(渲染启动文件/宏/.ld/.ioc)→ register-template.ts / register-linker.ts / register-clock.ts | 三条路都要试:HAL 建工程、寄存器建工程、doctor 一致性;stm32f1-units / hal-route-units / doctor-chip-units 会红 |
|
|
711
|
+
| 改时钟树 | 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」「超限一个键都不写」;派生键必须全量重算 |
|
|
712
|
+
| 更新芯片薄表 | `node scripts/gen-chip-table.mjs` 重跑 → src/data/chip-table.json 更新 | 生成物不要手改;`--check` 给 CI;读不到 CubeMX db 时必须报错退出而不是写半截文件 |
|
|
713
|
+
| 改工程模板 | templates/scaffold/*,若新增文件同步 scaffold.ts 的 SHARED_TEMPLATE_FILES | scaffold-patch-units 的文件数断言会红 |
|
|
714
|
+
| 改设置面板 | client/client.js(前端)+ engine/web-api.ts(逻辑)+ web-api-units | 前端不经打包器,语法要保守 |
|
|
715
|
+
| 改编码行为 | engine/text-file.ts 一处改,code-patch / generate 自动跟随 | text-encoding-units 9 例兜底 |
|
|
716
|
+
| 改 .elf 选择规则 | engine/build.ts 的 `pickElf` / `elfCandidates` / `elfSelectionNote`(flash、debug_run、doctor、export 全都间接用它) | build-units 里要同时断言「工程名优先」和「退化到最新」两条路 |
|
|
717
|
+
| 给工具加错误码 | engine/flash.ts 的 `errorCodeOfLines` 与 `FlashErrorCode`(debug_run 复用同一枚举) | 三个地方同改:engine 归类、reportSchema 声明、schema-guard 用例 |
|
|
718
|
+
| 改 cmake 源清单的认法(设备宏、startup、HAL 模块) | engine/cmake-sources.ts 的 `collectCmakeSources` / `halModulesInUse` | 注释掉的 `#define` 与 `#include` 不能算启用;内容没变必须零写入(cmake-sources-units 15 例兜这两条) |
|
|
719
|
+
| 加一条不变量 | 先写测试,再改代码 | 本文件第 8 章同步补一行 |
|
|
720
|
+
|
|
721
|
+
## 11. 已知的坑与未做的事
|
|
722
|
+
|
|
723
|
+
1. **只有 F1 在 FIRMWARE_FAMILIES**:其他族要接入必须先核实真实仓库名(stm32g4xx-hal-driver 之类),不能照 F1 改字母。
|
|
724
|
+
2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
|
|
725
|
+
3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
|
|
726
|
+
4. **四种 errorCode 只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验。
|
|
727
|
+
5. **P2(多芯片 + HAL 外设源文件按需落位)与 P3(gdb MI 常驻)** 未开工。
|
|
728
|
+
6. **docs/diagrams/** 那两张 HTML 图有 2 MB 原始 / 891 KB gz,已经不进 npm 包**(package.json 的 files 从 docs 收窄成 docs/*.md)。这事现在由 `scripts/pack-size.mjs`(npm run test:size)守着:tarball ≤1.2 MB、templates/** ≤60 KB、包内禁 png/jpg/jpeg/gif/webp/bmp/pdf/html/zip/7z/exe/dll、必须含 README.md / README_EN.md / LICENSE / cordis.patch.yml / docs/reading-guide.md。实测包体 509.9 KB / 99 个文件。
|
|
729
|
+
7. **CI 上的 test:pack** 只在本机跑过;第一次在 GitHub Actions 上跑还没有记录。
|
|
730
|
+
8. 斜杠命令的卡片渲染只有用户手输能验,工具层测不到。
|
|
731
|
+
9. **.elf 的选择依赖 CMakeCache**:工程名优先来自 `CMAKE_PROJECT_NAME`,手工删了 CMakeCache 或换了构建目录后只能退化为「mtime 最新」,此时以报告 notes 里的候选列表为准。
|
|
732
|
+
10. **裸 `cmake -S . -B build` 会丢工具链文件**:工具链只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不走 preset 就得自己给 `-DCMAKE_TOOLCHAIN_FILE`,否则 configure 用宿主 gcc、链接时找不到启动文件。
|
|
733
|
+
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 时才退回文件大小并注明是粗算。
|
|
734
|
+
12. **换芯片后别留旧链接脚本名**:`-T` 出现两个 .ld 时链哪个取决于顺序,症状是「编译过、上板跑飞」。hal-chip.pointLinkerFlagAt 会把工具链里的旧名改指新名,doctor 的 ①③ 两项检查也会先报 blocker。
|
|
735
|
+
|
|
736
|
+
---
|
|
737
|
+
|
|
738
|
+
读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
|