dsh-stm32 0.1.2 → 0.1.4
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 +92 -40
- package/README_EN.md +85 -36
- package/assets/README.md +85 -0
- package/assets/VERSION +1 -0
- package/assets/device/c0/chips.json +1108 -0
- package/assets/device/f0/chips.json +1570 -0
- package/assets/device/f1/chips.json +1238 -0
- package/assets/device/f1/svd/100.json +943 -0
- package/assets/device/f1/svd/101.json +901 -0
- package/assets/device/f1/svd/102.json +522 -0
- package/assets/device/f1/svd/103.json +1139 -0
- package/assets/device/f1/svd/105.json +1117 -0
- package/assets/device/f1/svd/107.json +1195 -0
- package/assets/device/f2/chips.json +674 -0
- package/assets/device/f3/chips.json +1318 -0
- package/assets/device/f4/chips.json +2942 -0
- package/assets/device/f7/chips.json +1710 -0
- package/assets/device/g0/chips.json +2102 -0
- package/assets/device/g4/chips.json +2494 -0
- package/assets/device/h5/chips.json +898 -0
- package/assets/device/h7/chips.json +1948 -0
- package/assets/device/l0/chips.json +2494 -0
- package/assets/device/l1/chips.json +1234 -0
- package/assets/device/l4/chips.json +2130 -0
- package/assets/device/l4+/chips.json +856 -0
- package/assets/device/l5/chips.json +226 -0
- package/assets/device/u0/chips.json +688 -0
- package/assets/device/u3/chips.json +310 -0
- package/assets/device/u5/chips.json +884 -0
- package/assets/device/wba/chips.json +506 -0
- package/assets/device/wl/chips.json +184 -0
- package/assets/headers/f1/stm32f100xb.h +5972 -0
- package/assets/headers/f1/stm32f100xe.h +6587 -0
- package/assets/headers/f1/stm32f101x6.h +5315 -0
- package/assets/headers/f1/stm32f101xb.h +5446 -0
- package/assets/headers/f1/stm32f101xe.h +6503 -0
- package/assets/headers/f1/stm32f101xg.h +6713 -0
- package/assets/headers/f1/stm32f102x6.h +6448 -0
- package/assets/headers/f1/stm32f102xb.h +6570 -0
- package/assets/headers/f1/stm32f103x6.h +10109 -0
- package/assets/headers/f1/stm32f103xb.h +10240 -0
- package/assets/headers/f1/stm32f103xe.h +11767 -0
- package/assets/headers/f1/stm32f103xg.h +11951 -0
- package/assets/headers/f1/stm32f105xc.h +14340 -0
- package/assets/headers/f1/stm32f107xc.h +15253 -0
- package/assets/headers/f1/stm32f1xx.h +273 -0
- package/assets/headers/f1/system_stm32f1xx.h +96 -0
- package/assets/ioc/family/C0.ioc +82 -0
- package/assets/ioc/family/F0.ioc +71 -0
- package/assets/ioc/family/F2.ioc +91 -0
- package/assets/ioc/family/F3.ioc +94 -0
- package/assets/ioc/family/F4.ioc +91 -0
- package/assets/ioc/family/F7.ioc +102 -0
- package/assets/ioc/family/G0.ioc +90 -0
- package/assets/ioc/family/G4.ioc +110 -0
- package/assets/ioc/family/H5.ioc +116 -0
- package/assets/ioc/family/H7.ioc +133 -0
- package/assets/ioc/family/L0.ioc +92 -0
- package/assets/ioc/family/L1.ioc +87 -0
- package/assets/ioc/family/L4+.ioc +92 -0
- package/assets/ioc/family/L4.ioc +93 -0
- package/assets/ioc/family/L5.ioc +91 -0
- package/assets/ioc/family/U0.ioc +103 -0
- package/assets/ioc/family/U3.ioc +113 -0
- package/assets/ioc/family/U5.ioc +102 -0
- package/assets/ioc/family/WBA.ioc +100 -0
- package/assets/ioc/family/WL.ioc +93 -0
- package/assets/ioc/minimal/STM32F100C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F100RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101RFTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F102C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F102C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103RFTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F105RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F107RCTx.ioc +113 -0
- package/assets/ld/f1/STM32F100C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F100RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101RFTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F102C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F102C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103RFTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F105RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F107RCTx_FLASH.ld +249 -0
- package/assets/manifest.json +1130 -0
- package/assets/startup/f1/startup_stm32f100xb.s +407 -0
- package/assets/startup/f1/startup_stm32f100xe.s +449 -0
- package/assets/startup/f1/startup_stm32f101x6.s +322 -0
- package/assets/startup/f1/startup_stm32f101xb.s +338 -0
- package/assets/startup/f1/startup_stm32f101xe.s +423 -0
- package/assets/startup/f1/startup_stm32f101xg.s +439 -0
- package/assets/startup/f1/startup_stm32f102x6.s +330 -0
- package/assets/startup/f1/startup_stm32f102xb.s +346 -0
- package/assets/startup/f1/startup_stm32f103x6.s +348 -0
- package/assets/startup/f1/startup_stm32f103xb.s +364 -0
- package/assets/startup/f1/startup_stm32f103xe.s +470 -0
- package/assets/startup/f1/startup_stm32f103xg.s +466 -0
- package/assets/startup/f1/startup_stm32f105xc.s +463 -0
- package/assets/startup/f1/startup_stm32f107xc.s +472 -0
- package/assets/templates/family/C0.ioc +82 -0
- package/assets/templates/family/F0.ioc +71 -0
- package/assets/templates/family/F2.ioc +91 -0
- package/assets/templates/family/F3.ioc +94 -0
- package/assets/templates/family/F4.ioc +91 -0
- package/assets/templates/family/F7.ioc +102 -0
- package/assets/templates/family/G0.ioc +90 -0
- package/assets/templates/family/G4.ioc +110 -0
- package/assets/templates/family/H5.ioc +116 -0
- package/assets/templates/family/H7.ioc +133 -0
- package/assets/templates/family/L0.ioc +92 -0
- package/assets/templates/family/L1.ioc +87 -0
- package/assets/templates/family/L4+.ioc +92 -0
- package/assets/templates/family/L4.ioc +93 -0
- package/assets/templates/family/L5.ioc +91 -0
- package/assets/templates/family/U0.ioc +103 -0
- package/assets/templates/family/U3.ioc +113 -0
- package/assets/templates/family/U5.ioc +102 -0
- package/assets/templates/family/WB.ioc +81 -0
- package/assets/templates/family/WBA.ioc +100 -0
- package/assets/templates/family/WL.ioc +93 -0
- package/docs/reading-guide.md +94 -71
- package/lib/data/chips.js +38 -51
- package/lib/data/clock-db.js +830 -0
- package/lib/data/clock-f1.js +12 -45
- package/lib/data/cmsis-sources.js +264 -17
- package/lib/data/db-presets.js +252 -0
- package/lib/data/device-facts.js +274 -0
- package/lib/data/family.js +515 -0
- package/lib/data/firmware-packages.js +562 -0
- package/lib/data/install-guides.js +2 -2
- package/lib/data/ioc-presets.js +248 -0
- package/lib/data/ioc-schema.js +1058 -0
- package/lib/data/rm-topics/stm32c0.json +227 -0
- package/lib/data/rm-topics.js +103 -0
- package/lib/data/search-roots.js +42 -1
- package/lib/data/stm32f1.js +95 -150
- package/lib/data/svd.js +643 -0
- package/lib/data/toolchain-config.js +0 -14
- package/lib/engine/assets.js +659 -0
- package/lib/engine/breakpoints.js +297 -0
- package/lib/engine/clock-derived.js +101 -0
- package/lib/engine/clock-direct.js +313 -0
- package/lib/engine/clock-plan.js +96 -52
- package/lib/engine/clock-pllmn.js +319 -0
- package/lib/engine/cmake-sources.js +67 -13
- package/lib/engine/cube-mx-guard.js +44 -0
- package/lib/engine/cube-programmer.js +137 -0
- package/lib/engine/cubemx-db.js +273 -0
- package/lib/engine/debug-session.js +576 -22
- package/lib/engine/debug.js +99 -46
- package/lib/engine/doctor.js +162 -19
- package/lib/engine/facts-acquire.js +416 -0
- package/lib/engine/facts.js +134 -0
- package/lib/engine/firmware-install.js +176 -5
- package/lib/engine/firmware-official.js +451 -0
- package/lib/engine/flash.js +317 -76
- package/lib/engine/gdb-mi.js +476 -0
- package/lib/engine/generate.js +9 -2
- package/lib/engine/hal-chip.js +124 -41
- package/lib/engine/ioc-plan.js +1247 -63
- package/lib/engine/ioc-rules.js +698 -0
- package/lib/engine/ioc-verify.js +706 -0
- package/lib/engine/ioc.js +43 -4
- package/lib/engine/msys2-install.js +4 -4
- package/lib/engine/probe-error.js +231 -0
- package/lib/engine/probe-session.js +347 -0
- package/lib/engine/probe.js +18 -3
- package/lib/engine/register-clock.js +41 -0
- package/lib/engine/register-gpio.js +115 -0
- package/lib/engine/register-linker.js +12 -7
- package/lib/engine/register-template.js +130 -45
- package/lib/engine/regs.js +43 -8
- package/lib/engine/rm-extract.js +144 -0
- package/lib/engine/rm-sources.js +360 -0
- package/lib/engine/rm-text.js +56 -0
- package/lib/engine/rtt.js +758 -0
- package/lib/engine/scaffold.js +185 -18
- package/lib/engine/toolchain-gate.js +0 -4
- package/lib/engine/watch.js +227 -0
- package/lib/index.js +12 -2
- package/lib/skill/stm32-workflow.js +2 -2
- package/lib/tools/assets.js +272 -0
- package/lib/tools/cache.js +8 -0
- package/lib/tools/debug-session.js +41 -6
- package/lib/tools/debug.js +41 -11
- package/lib/tools/doctor.js +65 -4
- package/lib/tools/firmware-install.js +31 -6
- package/lib/tools/flash.js +47 -10
- package/lib/tools/generate.js +25 -0
- package/lib/tools/ioc-apply.js +2 -0
- package/lib/tools/ioc-inspect.js +2 -0
- package/lib/tools/ioc-plan.js +59 -2
- package/lib/tools/ioc-verify.js +237 -0
- package/lib/tools/project-create.js +63 -3
- package/lib/tools/regs.js +453 -61
- package/lib/tools/route-plan.js +3 -0
- package/lib/tools/rtt.js +470 -0
- package/lib/tools/watch.js +256 -0
- package/package.json +5 -4
- package/templates/openocd/stm32c0x.cfg +83 -0
- package/templates/openocd/stm32u0x.cfg +64 -0
- package/templates/register/CMakeLists.txt +8 -2
- package/templates/register/Core/Inc/rtt.h +138 -0
- package/templates/register/Core/Src/main.c +42 -25
- package/templates/register/Core/Src/rtt.c +373 -0
- package/templates/scaffold/RTT.md +90 -0
- package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
- package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
- package/templates/scaffold/openocd.cfg +5 -3
- package/templates/scaffold/vscode/launch.json +8 -4
- package/docs/development-notes.md +0 -2116
- package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
- package/docs/logic-audit.md +0 -607
- package/lib/data/f1-ram.generated.js +0 -34
|
@@ -1,673 +0,0 @@
|
|
|
1
|
-
# DSH STM32 插件 · 规格书 v0.2
|
|
2
|
-
|
|
3
|
-
> 状态:需求已定稿,未开始实现。全部结论都有实测证据(见 §8、§12)。
|
|
4
|
-
> 上一版 `dsh-stm32-plugin-需求-v0.1.md` 已合并进本文,不再维护(v0.1 的 18 章有大量重复,且其中 D3/D4 两项假设已被实验推翻)。
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## 1. 定位与范围
|
|
9
|
-
|
|
10
|
-
**一句话**:给 STM32 工程提供"可编程的确定性执行层"——人/agent 负责意图,插件负责每一步的原子性、可验证性与回滚。
|
|
11
|
-
|
|
12
|
-
覆盖链路:建工程 → 改 `.ioc` → 生成代码 → 写 USER CODE → 编译 → 只烧录 / 烧录并调试 → 寄存器级验证。
|
|
13
|
-
|
|
14
|
-
**明确不做(v1)**:
|
|
15
|
-
|
|
16
|
-
| 项 | 原因 |
|
|
17
|
-
|---|---|
|
|
18
|
-
| 驱动 CubeMX GUI(UI 自动化) | 不稳定,且已有无头路径 |
|
|
19
|
-
| 时钟树可视化编辑 | 只读写 `.ioc` 的 RCC 键 |
|
|
20
|
-
| 接管 CubeMX2 / `.ioc2` | 格式不同,会把现有工程搞乱 |
|
|
21
|
-
| 升级固件包、HAL 迁移 | 只透传 `.ioc` 里的版本键 |
|
|
22
|
-
| FreeRTOS/LwIP 图形化配置 | 只透传键,不做语义理解 |
|
|
23
|
-
| 编码风格规范(MISRA 等) | 留给后续 skill,v1 只保证"只写 USER CODE 块" |
|
|
24
|
-
|
|
25
|
-
## 2. 痛点(全部来自实测,不是设想)
|
|
26
|
-
|
|
27
|
-
| # | 痛点 | 证据 |
|
|
28
|
-
|---|---|---|
|
|
29
|
-
| P1 | F5 和 Ctrl+F5 都进调试会话,"只烧录"做不到 | cortex-debug 的 `noDebug` 分支也会 `sendContinue`;CHANGELOG 记 ^F5 = Run Without Debugging(Experimental) |
|
|
30
|
-
| P2 | 配引脚/时钟必须开 GUI 手点 | CubeMX 无引脚级脚本 API |
|
|
31
|
-
| P3 | CubeMX 脚本模式有假成功 | `STM32CubeMX.exe` 是 launcher,detach 出 javaw 后立刻 exit 0;`load <mcu> + generate` 输出 "succesfully" 但无 `MX_GPIO_Init` |
|
|
32
|
-
| P4 | 默认 `No_Debug` → 生成 `__HAL_AFIO_REMAP_SWJ_DISABLE()` → 烧完 SWD 永久失联 | `_scratch/Src/stm32f1xx_hal_msp.c:77`,需 BOOT0 抢救 |
|
|
33
|
-
| P5 | 脚本模式只产 C 源,不产 startup / `.ld` / Drivers / CMake | E1/E2 实测(§8.3) |
|
|
34
|
-
| P6 | 验证只能"看灯闪不闪" | 最终靠 `AFIO_MAPR(0x40010004)` + `GPIOC_ODR` 采样才敢确认 |
|
|
35
|
-
|
|
36
|
-
## 3. 核心原则(不变量,实现时不许破)
|
|
37
|
-
|
|
38
|
-
| # | 原则 | 落地方式 |
|
|
39
|
-
|---|---|---|
|
|
40
|
-
| I1 | `.ioc` 是唯一真源 | 配置改动只改 `.ioc`,不改生成物 |
|
|
41
|
-
| I2 | USER CODE 块之外不许手写 | `code_patch` 只做锚点插入,锚点缺失则拒绝并列出可用锚点 |
|
|
42
|
-
| I3 | 改 `.ioc` 永远 plan → 确认 → apply | 无静默写盘;apply 必须带 `plan_id` 且源 SHA-256 与 plan 时一致 |
|
|
43
|
-
| I4 | 复刻不发明 | 布局复刻 CubeMX 产物(§7);脚手架复制或模板快照,不手写 |
|
|
44
|
-
| I5 | 外部工具单飞 | 同一时刻只允许一个 CubeMX / openocd / ninja 进程 |
|
|
45
|
-
| I6 | 探针默认释放 | 调试默认在一次调用内开关;退出/取消必杀进程树 |
|
|
46
|
-
| I7 | 先 build 再 flash | 构建失败绝不烧录 |
|
|
47
|
-
| I8 | 每次交付都要可自证 | 寄存器值 / 断点命中 / 计数变量,而不是"看起来对" |
|
|
48
|
-
|
|
49
|
-
## 4. 工具清单(13 个)
|
|
50
|
-
|
|
51
|
-
| 工具 | 作用 | 副作用 | 耗时 | 形态 |
|
|
52
|
-
|---|---|---|---|---|
|
|
53
|
-
| `stm32_env_probe` | 探测 CubeMX、固件包、gcc/gdb/openocd/cmake/ninja、探针 | 只读 | <3 s | 阻塞 |
|
|
54
|
-
| `stm32_project_create` | 从 MCU 型号建工程骨架(`.ioc` + CMake 工程文件 + 固件包 Drivers) | 建目录 | ~2 s | 阻塞 |
|
|
55
|
-
| `stm32_ioc_inspect` | `.ioc` → 结构化 JSON(引脚/信号/标签/时钟/项目设置) | 只读 | <1 s | 阻塞 |
|
|
56
|
-
| `stm32_ioc_plan` | 变更计划:改哪些键、diff、源 SHA-256、`plan_id` | 只读 | <1 s | 阻塞 |
|
|
57
|
-
| `stm32_ioc_apply` | 校验暂存副本 → 备份 → 替换 `.ioc` | 改 1 文件 | 90–150 s | **job** |
|
|
58
|
-
| `stm32_generate` | CubeMX + 布局映射 + USER CODE 合并 + 补脚手架 | 改多文件 | 3–4 min | **job** |
|
|
59
|
-
| `stm32_code_patch` | 只在 USER CODE 块内写 C 代码 | 改 1 文件 | <1 s | 阻塞 |
|
|
60
|
-
| `stm32_build` | cmake + ninja,返回 flash/ram 占用与错误定位 | 改 `build/` | 20–60 s | **job** |
|
|
61
|
-
| `stm32_flash` | **只烧录**:program + verify + reset,不启 gdb | 改芯片 | 5–15 s | 阻塞 |
|
|
62
|
-
| `stm32_debug_run` | 一次调用内烧录 + 断点 + 取 bt/regs + 关闭 | 改芯片 | 5–20 s | 阻塞 |
|
|
63
|
-
| `stm32_debug_session` / `_stop` | 显式申请长会话(租约,§6) | 占用探针 | — | 阻塞 |
|
|
64
|
-
| `stm32_regs_read` | 直连 openocd 读任意地址(不启 gdb) | 只读 | 3–5 s | 阻塞 |
|
|
65
|
-
| `stm32_doctor` | 自检:SWD 是否启用、时钟、栈指针、向量表、USER CODE 完整性、探针被谁占 | 只读 | 5–20 s | 阻塞 |
|
|
66
|
-
|
|
67
|
-
**斜杠命令**(人直接触发):`/stm32-flash`(只烧录)、`/stm32-debug`(烧录并调试)、`/stm32-build`、`/stm32-doctor`。这是 P1 的正面解法——烧录与调试点两下,互不干扰。
|
|
68
|
-
|
|
69
|
-
**随插件下发的 SKILL**:`stm32-workflow`,固化红线(I1–I8)与本次踩过的坑(SWJ_DISABLE、沙箱卡死、假成功)。
|
|
70
|
-
|
|
71
|
-
## 5. 工作流状态机
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
[0] env_probe -> [1] project_create -> [2] ioc_inspect/plan/apply -> [3] generate
|
|
75
|
-
|
|
|
76
|
-
+------------------------------------------+
|
|
77
|
-
v
|
|
78
|
-
[4] code_patch (USER CODE 内) -> [5] build -> [6] flash(只烧录)
|
|
79
|
-
| +-> [6q] debug_run(烧录并调试)
|
|
80
|
-
+- 失败回 [4] / [2]
|
|
81
|
-
|
|
|
82
|
-
v
|
|
83
|
-
[7] doctor / regs_read 自证
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
每阶段契约:**输入(前置产物)→ 输出(结构化 JSON)→ 失败回退点**。任何阶段失败不许"猜着继续"——generate 后必须做空壳检测(P3)。
|
|
87
|
-
## 6. 调试会话模型(租约式,默认用完就关)
|
|
88
|
-
|
|
89
|
-
### 6.1 硬约束
|
|
90
|
-
|
|
91
|
-
CMSIS-DAP 同一时刻只能被一个进程占用。「插件常驻 gdb」与「你在 VS Code 按 F5」互斥;冲突表现是 `Error: Error connecting DP: cannot read IDR`,**看不出被谁占**。
|
|
92
|
-
|
|
93
|
-
### 6.2 三种形态
|
|
94
|
-
|
|
95
|
-
| 形态 | 生命周期 | 适合 | 代价 |
|
|
96
|
-
|---|---|---|---|
|
|
97
|
-
| `debug_run`(默认) | 单次调用内 open→load→break→continue→取 bt/regs→close | 验证型调试(有没有到 main、卡在哪、变量值) | 不能交互 |
|
|
98
|
-
| `debug_session`(显式申请) | 空闲 60–90 s 自动关,操作续租,10 min 硬上限 | 交互式单步、反复读变量 | 期间占用探针 |
|
|
99
|
-
| 常驻 gdb | 直到手关 | 长时间连续调试 | **会挡住 VS Code**,不采用 |
|
|
100
|
-
|
|
101
|
-
### 6.3 关闭规则
|
|
102
|
-
|
|
103
|
-
1. 默认走 `debug_run`:一次调用把该看的都看回来,**天然用完就关**。
|
|
104
|
-
2. `debug_session` 必须显式申请,返回 `session_id` + 剩余租约;每次 `debug_eval` 续租。
|
|
105
|
-
3. `build` / `flash` / `generate` 开始前若存在会话,**先关闭并说明**(避免"烧录时探针被自己占着")。
|
|
106
|
-
4. 插件进程退出 / job 取消 → 强制关闭,openocd 进程树 `taskkill /T /F`。
|
|
107
|
-
5. `doctor` 能回答"探针现在被谁占着",冲突时给可操作提示而非裸错误。
|
|
108
|
-
|
|
109
|
-
### 6.4 T1 已确认:`turn/end` 钩子存在,按精确方式实现
|
|
110
|
-
|
|
111
|
-
用户要求:"agent 工作时会话可留;**agent 输出完、等下一次回复期间必须关闭**"。
|
|
112
|
-
|
|
113
|
-
**已定论(2026-10-22 查 dsh 实现)**:插件能精确知道轮次结束,不需要降级 TTL。
|
|
114
|
-
|
|
115
|
-
```ts
|
|
116
|
-
// 会话事件流:turn/start、turn/end、tool/result ...
|
|
117
|
-
ctx.on("session/event", (session, event) => {
|
|
118
|
-
if (event.type === "turn/end") closeDebugSession(session) // event.data = { turn, reason }
|
|
119
|
-
})
|
|
120
|
-
ctx.on("session/disposed", (session) => closeDebugSession(session))
|
|
121
|
-
ctx.on("agent/turn-stopping", async ({ agent, turn }) => { /* 轮内提前收尾,可选 */ })
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
证据(本机 asar 内实现):
|
|
125
|
-
|
|
126
|
-
| 位置 | 内容 |
|
|
127
|
-
|---|---|
|
|
128
|
-
| `dsh-agent-loop/lib/index.js:1029` | `this.session.append("turn/end", { turn, reason: turnEnds })` —— 每轮工具循环结束时追加,等于"我说完了" |
|
|
129
|
-
| `dsh-workspace-changes/lib/index.js:1055-1062` | 消费者写法:`ctx.on("session/event", (session, event) => { … event.type === "turn/end" … })` |
|
|
130
|
-
| `dsh-workspace-changes/lib/index.js:1064-1069` | 兜底 `session/disposed`,以及轮内钩子 `agent/turn-stopping`(`{ agent, turn }`) |
|
|
131
|
-
| `dsh-agent/lib/index.js:105-108` | `turn/end` 的 `data` 含 `{ turn, reason }` |
|
|
132
|
-
|
|
133
|
-
**实现约定(已在 M4 落地,见 §8.10)**:
|
|
134
|
-
|
|
135
|
-
1. `debug_session` 打开时向插件注册 `turn/end` 监听;事件到达 → 关闭会话并 `taskkill /T /F` openocd 进程树。
|
|
136
|
-
2. `session/disposed` 与插件 `dispose` 同路径清理,防进程泄漏。
|
|
137
|
-
3. 保留 TTL(60–90 s)+ 10 min 硬上限作为**安全网**,不是主路径:万一事件没到,探针也不会被永久占用。
|
|
138
|
-
4. `debug_run` 形态照旧(一次调用内开关),不依赖任何事件。
|
|
139
|
-
5. `build` / `flash` / `debug_run` / `generate` 开跑前先 `releaseProbeFor()`:会话开着就先关,避免"自己的会话占着探针"。
|
|
140
|
-
|
|
141
|
-
实际代码(`dsh-stm32/src/index.ts`):
|
|
142
|
-
|
|
143
|
-
```ts
|
|
144
|
-
if (typeof ctx.on === "function") {
|
|
145
|
-
ctx.on("session/event", (_session, event) => {
|
|
146
|
-
if (event?.type !== "turn/end") return;
|
|
147
|
-
void debugSessions.stop("turn/end:本轮输出结束,把探针还给你");
|
|
148
|
-
});
|
|
149
|
-
ctx.on("session/disposed", () => void debugSessions.closeAll("session/disposed"));
|
|
150
|
-
ctx.on("dispose", () => void debugSessions.closeAll("dispose"));
|
|
151
|
-
}
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
## 7. 工程结构契约
|
|
155
|
-
|
|
156
|
-
### 7.1 目标布局(= 当前 `demo/` 的真实布局)
|
|
157
|
-
|
|
158
|
-
```
|
|
159
|
-
demo.ioc <- 配置源,唯一真源
|
|
160
|
-
.mxproject <- CubeMX 生成记录(增量生成依据)
|
|
161
|
-
CMakeLists.txt
|
|
162
|
-
CMakePresets.json <- generator=Ninja, binaryDir=build/<preset>
|
|
163
|
-
cmake/{gcc-arm-none-eabi.cmake, starm-clang.cmake, stm32cubemx/CMakeLists.txt, user/CMakeLists.txt}
|
|
164
|
-
startup_stm32f103xb.s <- 根目录
|
|
165
|
-
STM32F103XX_FLASH.ld <- 根目录
|
|
166
|
-
Core/Inc/{main.h, stm32f1xx_hal_conf.h, stm32f1xx_it.h}
|
|
167
|
-
Core/Src/{main.c, stm32f1xx_hal_msp.c, stm32f1xx_it.c, syscalls.c, sysmem.c, system_stm32f1xx.c}
|
|
168
|
-
Drivers/{STM32F1xx_HAL_Driver, CMSIS}
|
|
169
|
-
.vscode/{launch.json, settings.json, c_cpp_properties.json}
|
|
170
|
-
build/<preset>/<ProjectName>.elf
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
### 7.2 契约
|
|
174
|
-
|
|
175
|
-
| ID | 要求 | 理由 |
|
|
176
|
-
|---|---|---|
|
|
177
|
-
| C1 | 新工程逐项复刻上表,不自创 `src/`、不重排 | `cmake/stm32cubemx/CMakeLists.txt` 的源文件清单是**写死**的(`Core/Src/main.c` 等,21–28 行),布局一变就"改了不生效且不报错" |
|
|
178
|
-
| C2 | 生成物必须落 `Core/Src`、`Core/Inc` | CLI 固定写 `Src`/`Inc`(§8.3 E2),插件必须做搬运 + 合并 |
|
|
179
|
-
| C3 | `.elf` 路径与名字一致(`build/<preset>/<ProjectName>.elf`) | 否则 VS Code F5 找不到可执行文件 |
|
|
180
|
-
| C4 | `launch.json` 只**新增**配置 | 保留已有的「① 只烧录 / ② 烧录并调试」两条 |
|
|
181
|
-
| C5 | 写入边界:只有 `Core/**` 的 USER CODE 区 + `.dsh-stm32/**` 可写,其余只读 | 防止"调试时项目文件被搞乱" |
|
|
182
|
-
| C6 | 脚手架(startup/`.ld`/CMake/Drivers)只许"复制项目自身"或"模板快照(记录来源版本)",**禁止手写** | 手写必然与 CubeMX 版本漂移 |
|
|
183
|
-
| C7 | 任何非 USER CODE 区的写入必须 plan + 确认 + 备份 | 与 I3 一致 |
|
|
184
|
-
## 8. CubeMX 集成:实测事实与能力边界
|
|
185
|
-
|
|
186
|
-
### 8.1 调用方式(唯一可用)
|
|
187
|
-
|
|
188
|
-
```
|
|
189
|
-
& "<CubeMX>\jre\bin\java.exe" -jar "<CubeMX>\STM32CubeMX.exe" -q <script>
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
- **不能**直接跑 `STM32CubeMX.exe`:它是 launcher,detach 出 javaw 后立刻 exit 0(P3 的根源)。
|
|
193
|
-
- 输出**不在 stdout**,必须重定向到日志文件。
|
|
194
|
-
- 脚本命令:`config load <ioc>` / `generate code <dir>` / `exit`;`load <mcu>` 只选芯片、生成空壳,不可用于工程。
|
|
195
|
-
|
|
196
|
-
### 8.2 能力矩阵
|
|
197
|
-
|
|
198
|
-
| 能力 | 脚本模式 | GUI | 结论 |
|
|
199
|
-
|---|---|---|---|
|
|
200
|
-
| 生成 `Core/Src`、`Core/Inc` 的 `.c/.h` | 是(但落 `Src/`、`Inc/`) | 是 | 需搬运 |
|
|
201
|
-
| 按 `.ioc` 改变非 USER CODE 区内容 | 是 | 是 | **等价**(§8.4) |
|
|
202
|
-
| USER CODE 块保活 | 是(同一文件被重写时) | 是 | **等价** |
|
|
203
|
-
| `CMakeLists.txt` / `cmake/**` / `startup_*.s` / `*.ld` / `Drivers/` | 否 | 是 | 插件自补 |
|
|
204
|
-
| `.mxproject` 更新 | 否 | 是 | 插件自补 |
|
|
205
|
-
| 删除不再需要的旧生成文件 | 否 | 是(`DeletePrevious=true`) | 插件自补 |
|
|
206
|
-
| 按 `MainLocation` / `CoupleFile` 决定落点与拆文件 | 否(固定 `Src/Inc` + 按外设拆) | 是 | 需映射 |
|
|
207
|
-
|
|
208
|
-
### 8.3 四个决定性实验(2026-10-22,CubeMX 6.15.0)
|
|
209
|
-
|
|
210
|
-
| # | 做法 | 结果 |
|
|
211
|
-
|---|---|---|
|
|
212
|
-
| E1 | 空目录(只有 `demo.ioc`)生成 | 只产 `Inc/{gpio.h,main.h,stm32f1xx_hal_conf.h,stm32f1xx_it.h}` + `Src/{gpio.c,main.c,stm32f1xx_hal_msp.c,stm32f1xx_it.c}`;**无** CMake/startup/`.ld`/Drivers/`.mxproject`/`.vscode` |
|
|
213
|
-
| E2 | 完整工程副本(923 文件,含 `.mxproject`、`Core/Src`、`CMakeLists.txt`)原地重生成 | 仍写 `副本/Src`、`副本/Inc`;`Core/**`、`cmake/**`、`.mxproject` 零字节变化(22 项 SHA-256 全同);日志只有 `Code succesfully generated under <dir>`,无 ProjectBuilder |
|
|
214
|
-
| E3 | `generate code` 参数换成 `.ioc` 文件路径 | 静默无操作(exit 0,无文件变化)→ 参数必须是目录 |
|
|
215
|
-
| E4 | 往 `e1/Src/main.c` 的 `USER CODE BEGIN 3` 插 `// MARKER_E4_USERCODE`,再对同目录重生成 | **标记存活**(第 100 行)→ 脚本模式同样遵守 USER CODE 块语义 |
|
|
216
|
-
|
|
217
|
-
**结论**:脚本模式只跑 CodeEngine、不跑 ProjectBuilder。所以"插件调 CubeMX 就能出完整工程"不成立——插件必须自己做**布局映射 + USER CODE 合并 + 脚手架**。
|
|
218
|
-
|
|
219
|
-
### 8.4 "配置变了,非 USER CODE 区跟着变"的证据
|
|
220
|
-
|
|
221
|
-
同一生成器、仅 `.ioc` 不同(`mxverify` 副本里手工加了 PA0=key/上拉输入、PA5=led2/输出):
|
|
222
|
-
|
|
223
|
-
- `mxverify/Inc/main.h:62-65` → 新增 `#define key_Pin GPIO_PIN_0`、`key_GPIO_Port GPIOA`、`led2_Pin GPIO_PIN_5`、`led2_GPIO_Port GPIOA`
|
|
224
|
-
- `mxverify/Src/main.c:179-190` → 新增 `/*Configure GPIO pin : key_Pin */`、`GPIO_InitStruct.Pull = GPIO_PULLUP`、`HAL_GPIO_Init(key_GPIO_Port, ...)`、`HAL_GPIO_WritePin(led2_GPIO_Port, led2_Pin, ...)`
|
|
225
|
-
- 这些全在 USER CODE 之外,即**生成器按配置重写了非用户区**
|
|
226
|
-
|
|
227
|
-
时钟侧同样等价(`m0/e1/Src/main.c`):`PLLMUL = RCC_PLL_MUL9`(122 行)、`APB1CLKDivider = RCC_HCLK_DIV2`(134 行)、`HAL_RCC_ClockConfig(..., FLASH_LATENCY_2)`(137 行)。
|
|
228
|
-
|
|
229
|
-
**但**:GUI 还会顺带更新 `CMakeLists.txt` 的源文件清单、`.mxproject`,并删除废弃文件;脚本模式不会。所以"效果相同"只在 `.c/.h` 内容层面成立,工程级文件由插件补齐(C6 / A13)。
|
|
230
|
-
|
|
231
|
-
### 8.5 运行成本与噪音
|
|
232
|
-
|
|
233
|
-
- 单次生成 **4–8 分钟**(实测一次成功 238.5 s;并发/排队时单次可跑到 8 分钟以上)→ 必须走 job + 进度流,插件默认超时 600 s。
|
|
234
|
-
- 插件侧**不需要** `danger-full-access`:`ctx.subprocess` 起的进程不受会话文件沙箱限制(实测 env_probe 7/7 正常)。
|
|
235
|
-
- 日志噪音:成功前有成批 `PDSC version is not supported` ERROR 与 `OptionalMessage_ERROR`(`Pin8 (VP_RIF_VS_RIF1) cannot be retrieved`、RCC 的 `ADCFreqValue/FamilyName/MCOFreq_Value/USBFreq_Value invalid`)。与本芯片无关,`doctor` 必须能区分"成功但有 warnings"。
|
|
236
|
-
- `workspace-write` 下卡死:进程停在 `IntegrityCheckThread` 之后,java CPU 冻结在 ~58 s。
|
|
237
|
-
### 8.6 插件端到端实测(2026-10-22,`dsh-stm32/test/e2e-generate.mjs`)
|
|
238
|
-
|
|
239
|
-
在 `demo` 的 12 文件精简副本(`.ioc` + `.mxproject` + `CMakeLists.txt` + `Core/**`)上跑真实生成:
|
|
240
|
-
|
|
241
|
-
- 耗时 **238.5 s**,`ok=true`,6 个文件落位(全部 `overwritten` + 备份)。
|
|
242
|
-
- `Core/Src/main.c` 保活 USER CODE 标签 `Header,PV,WHILE,3,Error_Handler_Debug,6`,`USER CODE 3` 里的
|
|
243
|
-
`HAL_GPIO_TogglePin` / `g_led_blink_count++` / `HAL_Delay(500)` 全部存活。
|
|
244
|
-
- `coupled` 布局生效:`MX_GPIO_Init` 在 `main.c` 内,没有生成 `gpio.c`(`generate all_code_in_main` 确实被 CLI 执行)。
|
|
245
|
-
- 备份落 `.dsh-stm32/backups/<时间戳>/Core/{Src,Inc}/*`;生成用的 `Src/`、`Inc/` 已清理。
|
|
246
|
-
- 坑:Windows 上目录 `rm` 后可能处于 **delete pending**(`existsSync` 仍为 true,但枚举已看不到),e2e 断言必须轮询,否则假阴性。
|
|
247
|
-
- 坑:诊断长任务别用 PowerShell 管道(`| Out-File`)或 node 的管道 stdout,缓冲会让日志长时间为空;用 `cmd /c "… > file 2>&1"`。
|
|
248
|
-
|
|
249
|
-
## 9. 技术栈与分层
|
|
250
|
-
|
|
251
|
-
### 9.1 结论
|
|
252
|
-
|
|
253
|
-
**单语言 TypeScript,零运行时依赖,`tsc` 直出,`engines.node >= 20`。**
|
|
254
|
-
|
|
255
|
-
| 项 | 决定 | 依据 |
|
|
256
|
-
|---|---|---|
|
|
257
|
-
| 语言 | TypeScript | dsh 插件本身必须是 node 模块;`.ioc` 是纯 `key=value`,不需要 Python 生态 |
|
|
258
|
-
| 构建 | `tsc`(不用 tsup) | 零额外依赖、产物可读、直接对应 dsh 插件的 `main: dist/index.js`;本地插件不需要单文件打包 |
|
|
259
|
-
| Node 下限 | `>= 20` | 本机 node 为 v24.14.0;18 已 EOL,写 20 可用较新 API |
|
|
260
|
-
| 运行时依赖 | 0(只用 `node:child_process`/`fs`/`crypto`/`path`) | 参考 `dsh-git-graph` 的 `dependencies: []` |
|
|
261
|
-
| 宿主依赖 | `@deepseek-ai/dsh-tools`(`defineTool`)、`@deepseek-ai/cordis`(`Context`) | 官方 cookbook |
|
|
262
|
-
|
|
263
|
-
### 9.2 四层
|
|
264
|
-
|
|
265
|
-
```
|
|
266
|
-
L3 tools/ defineTool 适配器、job 注册表(依赖 L2)
|
|
267
|
-
L2 workflows/ generate / build / flash / debug / doctor(依赖 L1)
|
|
268
|
-
L1 domain/ ioc、plan、scaffold、diagnostics、chip/probe 数据(依赖 L0)
|
|
269
|
-
L0 transport/ spawn、log、timeout、kill-tree、lock、原子写(只依赖 node 标准库)
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
**规则 1**:只能向下依赖(L0 不 import L1,任何层不 import L3)。
|
|
273
|
-
**规则 2**:外部工具走端口接口,业务代码里不许硬编码 `D:\app\msys64` 或 `stm32f1x.cfg`。
|
|
274
|
-
|
|
275
|
-
只对"已知会变"的四样做抽象:
|
|
276
|
-
|
|
277
|
-
| 未来要加 | 只改 |
|
|
278
|
-
|---|---|
|
|
279
|
-
| STM32F401 等型号 | `data/chips/*.json` |
|
|
280
|
-
| ST-Link / J-Link | probe 适配器(L1) |
|
|
281
|
-
| CubeMX2 / `.ioc2` | generator 适配器(L1) |
|
|
282
|
-
| UI 面板 | 新 client 包调 L2 |
|
|
283
|
-
|
|
284
|
-
**反面警告**:不为分层而分层,其余保持直白函数。
|
|
285
|
-
|
|
286
|
-
### 9.3 目录草案
|
|
287
|
-
|
|
288
|
-
```
|
|
289
|
-
dsh-stm32/
|
|
290
|
-
package.json # main: dist/index.js, dsh.bundle.patch, engines.node >=20, deps: []
|
|
291
|
-
cordis.patch.yml
|
|
292
|
-
src/
|
|
293
|
-
index.ts
|
|
294
|
-
engine/ # L0 + L1
|
|
295
|
-
ioc.ts plan.ts backup.ts spawn.ts cubemx.ts scaffold.ts
|
|
296
|
-
build.ts flash.ts debug.ts doctor.ts
|
|
297
|
-
workflows/ # L2
|
|
298
|
-
tools/ # L3:13 个 defineTool 适配器
|
|
299
|
-
data/chips/stm32f103c8t6.json
|
|
300
|
-
data/probes/cmsis-dap.json
|
|
301
|
-
test/ # fixture: demo/ 与 _scratch/ 的真实产物
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
### 9.4 数据结构
|
|
305
|
-
|
|
306
|
-
inspect 输出:
|
|
307
|
-
|
|
308
|
-
```json
|
|
309
|
-
{ "mcu": {"cpn":"STM32F103C8T6","name":"STM32F103C(8-B)Tx","package":"LQFP48"},
|
|
310
|
-
"clock": {"hse":"8MHz","sysclk_hz":72000000,"pll":{"mul":9,"source":"HSE"}},
|
|
311
|
-
"debug": {"mode":"Serial_Wire","pins":["PA13","PA14"]},
|
|
312
|
-
"pins": [{"pin":"PC13","signal":"GPIO_Output","label":"led","locked":true}],
|
|
313
|
-
"project": {"name":"demo","toolchain":"CMake","main_location":"Core/Src","fw":"STM32Cube FW_F1 V1.8.7"},
|
|
314
|
-
"sha256": "..." }
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
插件状态文件 `.dsh-stm32.json`(可提交):
|
|
318
|
-
|
|
319
|
-
```json
|
|
320
|
-
{ "version": 1, "ioc": "demo.ioc", "elf": "build/Debug/demo.elf",
|
|
321
|
-
"toolchain": {"gcc":"...","gdb":"gdb-multiarch","openocd":"openocd","cmake":"...","ninja":"..."},
|
|
322
|
-
"probe": {"type":"cmsis-dap","speed_khz":1000},
|
|
323
|
-
"openocd": {"interface":"interface/cmsis-dap.cfg","target":"target/stm32f1x.cfg","reset_config":"none"},
|
|
324
|
-
"build": {"generator":"Ninja","preset":"Debug"} }
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
统一返回:
|
|
328
|
-
|
|
329
|
-
```json
|
|
330
|
-
{ "ok": true, "stage": "generate",
|
|
331
|
-
"artifacts": [{"path":"Core/Src/main.c","sha256":"...","bytes":2711}],
|
|
332
|
-
"diagnostics": [{"severity":"warning","code":"SWJ_DISABLE","message":"...","file":"...","line":77}],
|
|
333
|
-
"duration_ms": 142000 }
|
|
334
|
-
```
|
|
335
|
-
### 9.5 插件 API 在哪(实测索引,写代码时直接照这个查)
|
|
336
|
-
|
|
337
|
-
插件 API 不是一个网站,而是**随 dsh 一起装在 checkout 里的一组 npm 包**,每个包自带一份 `README.zh.md`(front-matter 标 `kind: package-reference`)作为官方文档。位置:
|
|
338
|
-
|
|
339
|
-
```
|
|
340
|
-
D:\app\DeepSeek Harness\resources\app.asar\dsh\node_modules\@deepseek-ai\
|
|
341
|
-
dsh-tools/README.zh.md <- defineTool、ctx.tools.register/restrict/guard/schemas、PTC
|
|
342
|
-
cordis/README.md <- Context、inject、ctx.on、Service、fiber 生命周期
|
|
343
|
-
dsh-session/README.zh.md <- Session、append、事件流
|
|
344
|
-
dsh-agent/README.zh.md <- agent 事件(agent/status 等)
|
|
345
|
-
dsh-jobs/README.zh.md <- 后台 job(M1 之后要用)
|
|
346
|
-
dsh-tool-todo/lib/index.js <- 最小工具插件的完整范例(name/inject/Config/apply)
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
**是写插件时要调用的东西**——插件就是一个 cordis 插件模块,四个导出:
|
|
350
|
-
|
|
351
|
-
```ts
|
|
352
|
-
import type { Context } from "@deepseek-ai/cordis"
|
|
353
|
-
import { defineTool } from "@deepseek-ai/dsh-tools"
|
|
354
|
-
|
|
355
|
-
export const name = "stm32"
|
|
356
|
-
export const inject = ["tools", "subprocess"] // 需要的服务(缺了不启动)
|
|
357
|
-
export const Config = /* schemastery */ undefined // 可选配置 schema
|
|
358
|
-
|
|
359
|
-
export function apply(ctx: Context, config) {
|
|
360
|
-
ctx.tools.register(defineTool({
|
|
361
|
-
name: "stm32_flash",
|
|
362
|
-
description: "只烧录,不进入调试会话",
|
|
363
|
-
parameters: { /* string/number/boolean/array/object/oneOf */ },
|
|
364
|
-
output: { schema: { /* ... */ }, render: (_args, value) => [{ type: "text", text: "..." }] },
|
|
365
|
-
async execute(args, exec) { /* exec.signal 可取消 */ },
|
|
366
|
-
}))
|
|
367
|
-
ctx.on("session/event", (session, event) => { /* turn/end 关调试会话 */ })
|
|
368
|
-
ctx.on("dispose", () => { /* 杀 openocd 进程树 */ })
|
|
369
|
-
return () => { /* 卸载清理 */ }
|
|
370
|
-
})
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
**一个坑要先知道**:asar 里只发布了 `lib/**/*.js`,`package.json` 的 `types` 指向的 `lib/types/index.d.ts` **并不存在**。所以要么 `npm i -D @deepseek-ai/dsh-tools @deepseek-ai/cordis` 拿类型,要么按 README + 源码里的 JSDoc 写、用 `any` 兜底。M1 实验里会先确认哪一种可行。
|
|
374
|
-
|
|
375
|
-
**证据**:`dsh-tool-todo/lib/index.js:11-12`(`const name`/`const inject = ["tools", "sessionProjections"]`)、`:1097` 导出 `{ Config, apply, inject, name }`;`dsh-workspace-changes/lib/index.js:947-949`(`inject = ["subprocess", "fs"]`)。
|
|
376
|
-
|
|
377
|
-
#### 9.5.1 实测确认的宿主契约(M1 已跑通)
|
|
378
|
-
|
|
379
|
-
- **插件不需要 `defineTool`**:直接 `ctx.tools.register({ name, description, parameters:<JSON Schema>, timeoutMs, isConcurrencySafe, output:{ schema, render }, execute })` 即可,`defineTool` 只是同一个对象的轻量包装。已验证对象能通过 `assertSupportedJsonSchema` / `validateJsonSchemaValue`。
|
|
380
|
-
- **`ctx.subprocess.spawn(spec)`**:`spec = { argv: string[], cwd: string, stdio: { stdin:"ignore", stdout:{maxBytes}, stderr:{maxBytes} }, graceMs: 3000, signal }`,返回 `{ done: Promise<{exitCode, signal}>, collected: { stdout?: { readFrom(offset) }, stderr? }, terminate(), waitForExit() }`。`readFrom` 是偏移读取、不消费。
|
|
381
|
-
- **坑(已踩)**:`spec.cwd` 缺省不是"默认当前目录",而是直接在 `targetEnvironment()` 里 `spec.cwd.includes("\0")` → `TypeError: Cannot read properties of undefined (reading 'includes')`(`dsh-subprocess-local/lib/runner-launch-B2zsQ1Dz.js:1520`)。所以 L0 封装一律填 `cwd = request.cwd ?? process.cwd()`,本地假宿主也复刻这条严格性。
|
|
382
|
-
- **输出校验**:`execute` 的返回值会被宿主的 ptc runtime 按工具的 `output.schema` 严格校验——未声明键直接拒(`additionalProperties: false`)、声明为 `string`/`number`/`object` 的字段不收 `null`。asar 的 `validateJsonSchemaValue` 宽松,不能当 oracle(§8.8 两个真实 bug)。
|
|
383
|
-
- **安装生效方式**:用 `link:` 而不是 `file:`(`nodeLinker: hoisted` 下 `file:` 是复制,改完 `lib/` 不生效)。`pnpm add link:<绝对路径>` 到 `~/.dsh/profiles/desktop` + 在 profile `package.json` 的 `dsh.profile.bundles` 登记包名;bundle 层**只在 dsh 进程启动时加载**,改完代码必须重启 dsh。
|
|
384
|
-
## 10. 安全、权限与清理
|
|
385
|
-
|
|
386
|
-
### 10.1 权限(硬约束)
|
|
387
|
-
|
|
388
|
-
| 场景 | 要求 | 证据 |
|
|
389
|
-
|---|---|---|
|
|
390
|
-
| CubeMX 生成 / 校验 | **全权限** | `workspace-write` 下卡死(§8.5);且要写 `%USERPROFILE%\.stm32cubemx` 与注册表 |
|
|
391
|
-
| `ninja` 构建 | **全权限** | `workspace-write` 下挂死在启动第一个构建步骤前(最小 `build.ninja` 也挂);全权限下 exit 0 |
|
|
392
|
-
| 其余(inspect / regs_read / doctor / flash) | 普通权限即可 | 只读或只碰探针;实测插件经 `ctx.subprocess` 起的进程**不受会话文件沙箱限制**(workspace-write 下 7/7 探测正常),所以插件内不需要升权限 |
|
|
393
|
-
|
|
394
|
-
不可控项:CubeMX 在全权限下会自行写 `%USERPROFILE%\.stm32cubemx` 与注册表,插件只能声明、不能约束。
|
|
395
|
-
|
|
396
|
-
### 10.2 风险与对策
|
|
397
|
-
|
|
398
|
-
| # | 风险 | 对策 |
|
|
399
|
-
|---|---|---|
|
|
400
|
-
| R1 | 残留进程占调试器 | 记录 PID + 启动时间 + 命令行;退出/取消 `taskkill /T /F`;`doctor` 可查 |
|
|
401
|
-
| R2 | 端口冲突(gdb 默认 3333) | 探测 3333+ 顺延 |
|
|
402
|
-
| R3 | 多 CubeMX 并发写全局库 | 单飞锁(同时只 1 个 CubeMX / openocd / build) |
|
|
403
|
-
| R4 | 磁盘膨胀 | 日志 5 MB 截断;备份保留最近 10 份 |
|
|
404
|
-
| R5 | PID 复用误杀 | 杀前比对启动时间与命令行 |
|
|
405
|
-
|
|
406
|
-
### 10.3 非功能要求
|
|
407
|
-
|
|
408
|
-
幂等(重复 flash 安全、重复 generate 不毁 USER CODE);可观测(外部命令全部落 `.dsh-stm32/logs/<ts>-<stage>.log`,含 argv / exit code / 原始 stderr);不留残留;诊断质量(编译错误解析成 `file:line:col`,openocd 错误分类);Windows 优先,路径用原生分隔符。
|
|
409
|
-
|
|
410
|
-
## 11. 验收标准
|
|
411
|
-
|
|
412
|
-
| ID | 场景 | 判据 |
|
|
413
|
-
|---|---|---|
|
|
414
|
-
| A1 | 空目录 → 一条命令出工程 | F103C8T6 + PC13 输出,build exit 0,占用合理 |
|
|
415
|
-
| A2 | 改 `.ioc` 加 PA5(led2) | inspect 能看到;plan diff 正确;generate 后 `MX_GPIO_Init` 含 led2;**USER CODE 闪烁代码不丢** |
|
|
416
|
-
| A3 | 只烧录 | Verified OK,且**全程无 gdb 进程** |
|
|
417
|
-
| A4 | 烧录并调试 | gdb 命中 `main`,`bt` 正确,可 continue |
|
|
418
|
-
| A5 | 注入 `No_Debug` | **拒绝烧录**,报 SWJ_DISABLE 并给修复命令 |
|
|
419
|
-
| A6 | 注入语法错 | build 返回 `file:line:col` |
|
|
420
|
-
| A7 | 无探针 / 断线 | 明确错误,无残留进程,芯片可恢复 |
|
|
421
|
-
| A8 | apply 中途失败 | `.ioc` 字节级还原(SHA-256 一致) |
|
|
422
|
-
| A9 | 取消长任务 | CubeMX / build 被取消,进程树全灭 |
|
|
423
|
-
| **A10** | 同 `.ioc`,GUI 产物 vs 插件产物(`Core/Src`、`Core/Inc`) | ~~除 USER CODE 区外逐字节一致~~ → **语义等价**(实测 CLI 与 GUI 的空行数不同,逐字节不可达,见 §8.9 发现 1) |
|
|
424
|
-
| **A10q** | 插件产物 vs CLI 原始产物(`Src/`、`Inc/`) | 去掉 USER CODE 区后逐字节一致(证明未夹带风格) |
|
|
425
|
-
| A11 | 插件生成后 VS Code F5 | 命中 `main`,无红波浪线 |
|
|
426
|
-
| A12 | 插件运行中用户在 VS Code 烧录 | 能检测探针被占并提示,不损坏 |
|
|
427
|
-
| **A13** | 脚手架文件(`CMakeLists.txt`、`cmake/**`、`startup_*.s`、`*.ld`、`Drivers/**`、`.mxproject`、`.vscode/**`) | 与"同版本 CubeMX GUI 新工程"逐字节一致;来源只能是项目自身复制或模板快照 |
|
|
428
|
-
|
|
429
|
-
**逐条结论见 §8.12**(2026-10-22 M6 总验收:A1–A13 全部通过,其中 A11 为间接证据)。
|
|
430
|
-
|
|
431
|
-
### 8.7 M3 实测:build / flash / debug_run(2026-10-22,同一台机器同一块蓝丸)
|
|
432
|
-
|
|
433
|
-
| 场景 | 结果 | 证据 |
|
|
434
|
-
|---|---|---|
|
|
435
|
-
| `stm32_build` clean 全量 | ok,56.0 s,RAM 1584 B/20 KB (7.73%)、FLASH 4716 B/64 KB (7.20%),0 错误 | `test/e2e-build.mjs` 5/5 PASS |
|
|
436
|
-
| `stm32_build` 增量 | ok,2.3 s;无链接就没有内存表 → 报告写"本次是增量构建…",不报错 | 同上第一轮 |
|
|
437
|
-
| `stm32_flash` | ok,2.2 s,`** Programming Finished **` + `** Verified OK **`,用工程的 `openocd.cfg`,跑完 `Resetting Target` 退出 | `test/e2e-flash.mjs` 5/5 PASS |
|
|
438
|
-
| `stm32_debug_run` | ok,2.6 s,停在 `main () at demo/Core/Src/main.c:74`,pc=0x8000f58 / sp=0x20004ff8 / lr=0x80011ab,收尾 reset run + detach | `test/e2e-debug.mjs` 5/5 PASS |
|
|
439
|
-
| 调试后探针是否真的放掉 | 另起一次 openocd 连上读到 `g_led_blink_count=41065`(芯片一直在跑),说明 detach 后目标自由运行 | `dsh-stm32/verify-run.log` |
|
|
440
|
-
|
|
441
|
-
踩到的两个实现坑(都已修,写进 README/代码注释):
|
|
442
|
-
|
|
443
|
-
1. **openocd 的日志走 stderr**。`debug_run` 起初只轮询 `collected.stdout` 等 `Listening on port`,永远等不到,15 s 判失败;
|
|
444
|
-
两路都读之后立刻正常。
|
|
445
|
-
2. **删空目录必须用 `rmdirSync`**。`rmSync(dir, { recursive: false })` 对目录直接抛 `ERR_FS_EISDIR`,
|
|
446
|
-
表现为"生成用的 Src/、Inc/ 删不掉",连续三轮 e2e 都 FAIL——不是文件被占用,是 API 用错。
|
|
447
|
-
3. 附带发现:CubeMX 生成过程中可能出现 `[ERROR] WebUtils:398 - Updater is busy`,但同一次仍打印
|
|
448
|
-
`Code succesfully generated under …`。判定规则改为**有成功行就以成功行为准**,过程 ERROR 降级为告警
|
|
449
|
-
(否则会把成功的一次判成失败、一个字节都不落位)。
|
|
450
|
-
|
|
451
|
-
### 8.8 M2 剩余工具实测 + 宿主输出契约(2026-10-22)
|
|
452
|
-
|
|
453
|
-
| 场景 | 结果 | 证据 |
|
|
454
|
-
|---|---|---|
|
|
455
|
-
| `stm32_doctor` | ok,3.5 s:工具链 7/7(gcc 13.3.0 / gdb 16.2 / openocd 0.12.0 / cmake 3.31.5 / ninja 1.12.1 / CubeMX / JRE 21.0.3)、无残留 openocd/gdb 进程、3333 空闲、elf=demo\build\Debug\demo.elf、.ioc 告警 0 | `test/e2e-doctor-regs.mjs` 10/10 PASS |
|
|
456
|
-
| `stm32_regs_read` | ok,0.9 s,pc=0x0800020c;AFIO_MAPR=0x02000000(SWJ_CFG=2,Serial Wire 正常)、GPIOC_ODR=0x00002000(PC13 高电平)、g_led_blink_count=0x00013168 | 同上 |
|
|
457
|
-
| 探针是否释放 | 同一调用结束后再连一次 openocd 正常,计数器持续增长(芯片在跑) | 同上第二次读 |
|
|
458
|
-
|
|
459
|
-
**宿主输出校验的两条硬规则**(都真实翻过车,已用 `test/schema-guard.mjs` 6/6 固化成离线守卫):
|
|
460
|
-
|
|
461
|
-
1. `additionalProperties: false` 必须严格遵守。`stm32_flash` 返回了 schema 未声明的 `args`,**烧录副作用已经发生**,调用却报 `"value.report.args" is not a declared property`。
|
|
462
|
-
2. 声明为 `string` / `number` / `object` 的字段不接受 `null`。`build` / `flash` 的失败路径写 `exitCode: null`、`elf: null` 会被拒:`"value.report.exitCode" must be a number`。改用可选字段 + 条件展开。
|
|
463
|
-
|
|
464
|
-
结论:**asar 里的 `validateJsonSchemaValue` 不是宿主校验的 oracle**(它对 null、多余键都放过),唯一 oracle 是 ptc runtime;所以断言要按 schema 自己离线走一遍。
|
|
465
|
-
|
|
466
|
-
### 8.9 宿主侧整体复验 + generate 端到端(2026-10-22,重启 dsh 后真实调用)
|
|
467
|
-
|
|
468
|
-
重启 dsh 后,8 个工具在真实宿主环境里逐个跑过(此前 §8.6 的 generate 只在本机脚本里验过):
|
|
469
|
-
|
|
470
|
-
| 工具 | 结果 | 备注 |
|
|
471
|
-
|---|---|---|
|
|
472
|
-
| `stm32_doctor` | ok,工具链 7/7,无残留 openocd/gdb,3333 空闲,.ioc 告警 0 | — |
|
|
473
|
-
| `stm32_regs_read` | ok,1.3 s,pc=0x08000244;AFIO_MAPR=0x02000000、GPIOC_ODR 读到 PC13 电平 | — |
|
|
474
|
-
| `stm32_flash` | ok,2.1 s,编程 + 校验 + 复位运行,**修复后再无 `value.report.args` 报错** | 见 §8.8 硬规则 1 |
|
|
475
|
-
| `stm32_debug_run` | ok,2.4 s,停在 `main () at demo/Core/Src/main.c:74`,pc=0x8000f58 sp=0x20004ff8 lr=0x80011ab,收尾 reset run + detach | — |
|
|
476
|
-
| `stm32_generate`(job 形态) | job `stm32-generate-ae31921d2a554928` → completed,64.6 s,**6 个文件落位全部 overwritten,保活 USER CODE 标签 12 个** | 首次在真宿主验证 `ctx.jobs.start` + 进度流 |
|
|
477
|
-
|
|
478
|
-
generate 端到端带来的连锁验证(全部通过):
|
|
479
|
-
|
|
480
|
-
- 备份:`.dsh-stm32/backups/20261022-175732/Core/{Src,Inc}/*`;
|
|
481
|
-
- 临时目录:生成用的 `Src/`、`Inc/`、`MXTmpFiles/` 全部消失,`.dsh-stm32/lock.json` 已释放;
|
|
482
|
-
- USER CODE 3 里的 `HAL_GPIO_TogglePin(led_GPIO_Port, led_Pin);` / `g_led_blink_count++;` / `HAL_Delay(500);` 原样保留;
|
|
483
|
-
- 重新编译:ok,4.2 s,0 错误 0 警告,RAM 1584 B (7.73%)、FLASH 4716 B (7.20%),产物 656888 B;
|
|
484
|
-
- 重新烧录 + 读寄存器:计数器单调增长,固件照常闪灯。
|
|
485
|
-
|
|
486
|
-
**三条新发现(都已落到代码或本文档)**:
|
|
487
|
-
|
|
488
|
-
1. **CLI 产物与 GUI 产物在空行数量上不一致**。重新生成前后 `Core/Inc/main.h` 是 72 行 → 66 行,差异全是空行(`#define led_Pin`、`Error_Handler` 等语义内容完全一致)。
|
|
489
|
-
→ **A10"除 USER CODE 区外逐字节一致"在本机不可达**,验收改按 A10q 的精神执行:结构、路径、语义一致,允许空行/排版差异。这条把 §7.2 C1 的"逐字节"要求正式降级为"语义等价"。
|
|
490
|
-
2. **`stm32_regs_read` 原来的收尾 `reset run` 有副作用**:它会把芯片复位,固件里的计数器从头开始,"只读一眼"变成"重启一次"。第一次宿主复验里就看到计数器 917 → 1926(读到的是 `uwTick`)以及随后 29 → 4 → 4 → 4 的归零。
|
|
491
|
-
→ 收尾改为 `resume` + `shutdown`(halt 只是暂停,resume 原样继续跑)。`test/e2e-doctor-regs.mjs` 增加两条断言(计数器单调增长、两次读之间不归零),现在 **12/12 PASS**。
|
|
492
|
-
3. **符号地址会随重新生成/链接漂移**:`g_led_blink_count` 从 0x20000028 移到 0x2000002C,原地址 0x20000028 变成 `uwTick`(1 kHz 自增,一眼能看出异常)。
|
|
493
|
-
→ `stm32_regs_read` 只接受物理地址,不猜符号。后续可在 M5 加"按 `.elf` 符号名解析地址"(`arm-none-eabi-nm`),列入 §14 未定项。
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
**regs 解析的真实格式**(openocd 0.12.0):`mdw` 打印 `0x4001100c: 00000000`(值是 8 位裸 hex),`[reg pc]` 打印 `pc (/32): 0x…`。脚本改为 `[lindex [mdw <addr>] 1]` / `[lindex [reg pc] 1]`,且 pc 仍优先取 halt 横幅 `xPSR: … pc: 0x…`——实测 `[lindex [reg pc] 1]` 会得到空值。
|
|
497
|
-
|
|
498
|
-
### 8.10 M4 实测:配置事务 + 调试会话租约(2026-10-22,同一台机器同一块蓝丸)
|
|
499
|
-
|
|
500
|
-
六个新工具:`stm32_ioc_plan`、`stm32_ioc_apply`、`stm32_debug_session`、`stm32_debug_eval`、`stm32_debug_stop`,
|
|
501
|
-
加上插件入口里的 `turn/end` 清理与四个既有工具的"先让出探针"。
|
|
502
|
-
|
|
503
|
-
| 验证 | 方式 | 结果 |
|
|
504
|
-
|---|---|---|
|
|
505
|
-
| 事务离线 | `node test\ioc-plan-units.test.mjs` | **9/9 PASS**(plan 不写源文件、apply 核 SHA、引脚校验、serialWire 补 PA13/PA14、rollback 只认 backups 下路径) |
|
|
506
|
-
| 会话离线 | `node test\session-units.test.mjs` | **8/8 PASS**(租约续租、空闲/硬上限自动关、重复 start、无会话时 eval 拒绝且不 spawn) |
|
|
507
|
-
| 输出契约 | `node test\schema-guard.mjs` | **12/12 PASS**(含新增的 plan/apply **成功路径**形状检查:kind ∈ added/removed/changed、before/after 一定是字符串、不出现 null) |
|
|
508
|
-
| 真板长会话 | `node test\e2e-session.mjs` | **9/9 PASS**:起会话 0.3 s、自动解析到 `build/Debug/demo.elf`、隔 1.2 s 读两次 `g_led_blink_count` 递增(芯片在跑)、读到 pc、关会话后探针释放且 3333 空闲 |
|
|
509
|
-
| 事务闭环 | `node test\e2e-plan-generate.mjs` | **9/9 PASS**:副本上 plan 加 PA5/`led2`(8 条键变更)→ apply(备份 `.dsh-stm32/backups/<时间戳>-ioc/demo.ioc`)→ 真 CubeMX 生成 91.4 s、6 个文件落位、保活 12 个 USER CODE 标签 → `main.h` 出现 `led2_Pin GPIO_PIN_5`/`led2_GPIO_Port GPIOA` 且 `led_Pin GPIO_PIN_13` 仍在 → 生成用的 `Src/``Inc/` 清干净 → rollback 后 `led2` 消失 |
|
|
510
|
-
|
|
511
|
-
**宿主侧复验(重启 dsh 后真实调用,2026-10-22)**:
|
|
512
|
-
|
|
513
|
-
| 工具 | 结果 |
|
|
514
|
-
|---|---|
|
|
515
|
-
| `stm32_ioc_plan` | ok、planId `c6e252e6877afd50`、8 条 diff、`kind`/`before`/`after` 符合 schema、无 warning |
|
|
516
|
-
| `stm32_ioc_apply` | ok、appliedChanges 8、`shaAfter === candidateSha256`、备份 `.dsh-stm32/backups/<时间戳>-ioc/demo.ioc`;写后 `.ioc` 真的多了 `Mcu.PinsNb=9`/`Mcu.Pin8=PA5`/`PA5.Signal=GPIO_Output` 等 8 行 |
|
|
517
|
-
| `stm32_debug_session` | ok、active、port 3333、自动解析到 `build/Debug/demo.elf` |
|
|
518
|
-
| `stm32_debug_eval` | 两次读 `g_led_blink_count` 得 2127 → 2136(隔 1.3 s,芯片在跑);`info registers pc sp` → `pc=0x8000214 <HAL_GetTick+12>`、`sp=0x20004fdc` |
|
|
519
|
-
| `stm32_debug_stop` | stopped=true,探针释放 |
|
|
520
|
-
| `stm32_doctor` | ok、残留进程 `[]`、3333 空闲 |
|
|
521
|
-
|
|
522
|
-
事务验证在临时副本 `.tmp-host-apply` 上做(只放一份 `demo.ioc`),验完删除,真实工程 `demo.ioc` 未改动。
|
|
523
|
-
|
|
524
|
-
**`turn/end` 自动释放探针的实验**(刻意排除超时兜底):用 `idleTtlMs=600000`、`hardTtlMs=600000` 开会话并**故意不关**,
|
|
525
|
-
结束本轮输出、用户回一句话后立刻检查 → `stm32_debug_eval` 报"没有调试会话(先 stm32_debug_session…)"、
|
|
526
|
-
`stm32_doctor` 残留进程 `[]`、3333 空闲、`stm32_debug_stop` 返回"本来就没有会话"。
|
|
527
|
-
租约 10 分钟、实际只过了几十秒,所以只可能是 `session/event` 的 `turn/end` 分支关的(实现见 `src/index.ts`)。
|
|
528
|
-
于是"agent 输出结束就把探针交还用户"这条要求(§6)成立。
|
|
529
|
-
|
|
530
|
-
**两个新踩到的坑**:
|
|
531
|
-
|
|
532
|
-
1. **ELF 解析必须在引擎里做,不能只放在工具层**。`e2e-session` 直接调 `DebugSessionManager.start()` 时没传 `elfPath`,
|
|
533
|
-
gdb 于是报 `No symbol table is loaded. Use the "file" command.`,会话起来了但什么都读不到。
|
|
534
|
-
→ `start()` 内部改为 `resolveElfPath(projectDir, {}) ?? ""`(调用方给就用自己的),工具层不再重复解析。
|
|
535
|
-
教训:任何"工具层做了一半、引擎层没做"的默认值,在绕过工具层的测试里都会露馅。
|
|
536
|
-
2. **`IocPlanChange` 只有 `before`/`after`,没有 `kind`**(`kind` 是工具层按"before 为 null → added"派生的)。
|
|
537
|
-
e2e 打印 `change.kind` 得到 `undefined`,看着像 bug 其实是打印错了位置。→ 已在 e2e 里改正,并在
|
|
538
|
-
`schema-guard` 的成功路径用例里**断言 kind 一定是三个枚举之一**,以后工具层派生写错会被抓住。
|
|
539
|
-
|
|
540
|
-
### 8.11 M5 实测:斜杠命令 + SKILL(2026-10-22,真板)
|
|
541
|
-
|
|
542
|
-
命令层的宿主契约(`dsh-commands/lib/index.js` 实测):`ctx.commands.register({ name, description, input?, handler })`;
|
|
543
|
-
名字必须匹配 `/^[a-z][a-z0-9_-]*$/u`;handler 收到 `{ commandId, agent, rawInput, attachments, signal }`,
|
|
544
|
-
返回 `{ kind: "success" | "error", text? }`——**抛异常不算正常返回**,五条命令都在 handler 内 try/catch。
|
|
545
|
-
SKILL 走 `ctx.skills.register({ name, description, content, invocation })`,名字匹配 `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`。
|
|
546
|
-
两者都通过 `ctx.inject([...], scope => ...)` 挂载:服务不存在就不注册,不会让整个插件加载失败。
|
|
547
|
-
|
|
548
|
-
| 命令 | 真实结果(`test/e2e-commands.mjs`) |
|
|
549
|
-
|---|---|
|
|
550
|
-
| `/stm32-doctor` | 1.5 s,success,文本含「体检通过」「工具链」 |
|
|
551
|
-
| `/stm32-build` | 0.5 s,success,文本含「编译成功」 |
|
|
552
|
-
| `/stm32-debug` | 2.1 s,success:先烧录,再停在 `main`,文本含「烧录成功」「调试:停在」 |
|
|
553
|
-
| `/stm32-stop` | success,「会话已关闭(你敲了 /stm32-stop),探针已释放」 |
|
|
554
|
-
| `/stm32-flash` | 1.6 s,success,「写入=是,校验=是」 |
|
|
555
|
-
|
|
556
|
-
断言 14/14 全过。首次跑时 `/stm32-debug` 报「调试会话起不来:没开会话:插件未就绪」——
|
|
557
|
-
根因是 `DebugSessionManager` 原先只在 `tools/debug-session.ts` 的 execute 里 `configure()`。
|
|
558
|
-
修法:命令层在 `start()` 之前也调 `debugSessions.configure(subprocess, [])`,
|
|
559
|
-
让「只注册命令、不注册工具」的组合同样能起会话(e2e 与真实宿主都因此变健壮)。
|
|
560
|
-
|
|
561
|
-
SKILL(`stm32-workflow`)把用户 m02472 的要求写成硬规范:R1 代码只准落在 USER CODE 块之间;
|
|
562
|
-
R2 不许改 CubeMX 生成区(逐条列出 `main()` / `SystemClock_Config()` / `MX_*_Init()` / `main.h` 的 defines 段 /
|
|
563
|
-
`stm32f1xx_hal_msp.c` / `stm32f1xx_it.c` / `stm32f1xx_hal_conf.h` / startup / `.ld` / `CMakeLists.txt` /
|
|
564
|
-
`cmake/stm32cubemx/CMakeLists.txt` / `.mxproject` / `demo.ioc`,理由是源清单写死且重新生成会覆盖);
|
|
565
|
-
R3 `.ioc` 只走 plan → 确认 → apply;R4 禁止 `No_Debug`(SWJ_DISABLE → SWD 失联);
|
|
566
|
-
R5 烧录与调试分开、成功看 `** Programming Finished **` + `** Verified OK **`;R6 探针唯一;R7 先 build 再 flash;
|
|
567
|
-
R8 结论必须带寄存器证据。另附标准流程 8 步、命令对照表、10 条实测坑、自检清单。
|
|
568
|
-
|
|
569
|
-
离线套件 10 个全绿(含新增 `commands-units` 6/6);`schema-guard` 对当时已注册的 13 个工具的输出做契约校验(M6 之后补齐到全部 15 个,见 §8.12)。
|
|
570
|
-
### 8.12 M6 实测:补缺口 + A1–A13 总验收(2026-10-22,同一台机器同一块蓝丸)
|
|
571
|
-
|
|
572
|
-
M5 收尾时对着规格自查,发现两个规格里的工具**从未实现**(`stm32_project_create`、`stm32_code_patch`),
|
|
573
|
-
以及 A5(`No_Debug` 时拒绝烧录)没有守卫。M6 补上,并把 §11 的验收逐条真跑。
|
|
574
|
-
|
|
575
|
-
| 新增/改动 | 位置 | 结果 |
|
|
576
|
-
|---|---|---|
|
|
577
|
-
| `stm32_project_create` | `src/engine/scaffold.ts` + `src/tools/project-create.ts` + `templates/scaffold/`(14 个工程文件) | 空目录 → 可编译工程 **2095 ms**(14 个模板文件 + 629 个固件文件) |
|
|
578
|
-
| `stm32_code_patch` | `src/engine/code-patch.ts` + `src/tools/code-patch.ts` | 只写 USER CODE 块;CRLF 原样;备份 + 原子写;四种拒绝情形 |
|
|
579
|
-
| A5 烧录守卫 | `checkNoDebugGuard()`(`src/engine/flash.ts`) | `.ioc` 没启用 Serial Wire → 烧录前拒绝,附修法与 `allowNoDebug` 逃生门 |
|
|
580
|
-
| 首次构建自动配置 | `pickConfigurePreset()`(`src/engine/build.ts`) | 没有 `CMakeCache.txt` 时先 `cmake --preset <Debug>`,不再"新工程一上来就 build 失败" |
|
|
581
|
-
|
|
582
|
-
**验收结论(§11 逐条)**
|
|
583
|
-
|
|
584
|
-
| ID | 结论 | 证据 |
|
|
585
|
-
|---|---|---|
|
|
586
|
-
| A1 | **通过** | `test/e2e-scaffold.mjs`:空目录 → 骨架 2095 ms/14 文件/629 固件文件 → CubeMX 生成 ~77 s(6 文件)→ build #1 5.2 s(含自动 `cmake --preset Debug`)→ 补丁 → build #2 1.8 s → flash 2.1 s(已校验)→ `g_e2e_count` **17 → 39** |
|
|
587
|
-
| A2 | **通过** | 同一轮:`code_patch` 写 `USER CODE Private variables` + `3`,CubeMX 生成时 USER CODE 内容不丢(e2e 里打补丁后再 build 仍在) |
|
|
588
|
-
| A3 | **通过** | 同一轮的 `stm32_flash`:`programmed=true / verified=true`,2.1 s,全程无 gdb(引擎只拼 openocd) |
|
|
589
|
-
| A4 | **通过** | §8.7 的 `stm32_debug_run`:停在 `main () at demo/Core/Src/main.c:74`,pc/sp/lr 正确,收尾 detach |
|
|
590
|
-
| A5 | **通过** | `test/e2e-a5-flash-guard.mjs`:拦下时报「没有启用 Serial Wire 调试口(缺 SYS_JTMS-SWDIO/SYS_JTCK-SWCLK)… `__HAL_AFIO_REMAP_SWJ_DISABLE()` …只能靠 BOOT0 救回来」,`guard="no-debug"`、未执行 openocd;`allowNoDebug=true` 时才放行(2.1 s 烧成功) |
|
|
591
|
-
| A6 | **通过** | `test/e2e-a6-build-error.mjs`:`.../Core/Src/main.c:102:15: error: expected expression before ';' token`;改回后 1.4 s 重新编译成功 |
|
|
592
|
-
| A7 | **通过** | `test/e2e-a7-a12-probe.mjs`:探针配置指向 J-Link → 「烧录失败:Error: No J-Link device found」,残留 openocd 进程 **0 → 0**,随后用正确配置能连上芯片(pc=0x08000fea) |
|
|
593
|
-
| A8 | **通过** | `test/e2e-a8-ioc-rollback.mjs`:apply 后 SHA `9d4e8d8e8073 → 5fde2c05f6e5`,rollback 回到 `9d4e8d8e8073`;plan 后手改源文件 → 拒写;手改候选文件 → 拒写;两种拒绝都不动文件 |
|
|
594
|
-
| A9 | **通过** | `test/e2e-a9-cancel.mjs`:预取消的 build 5 ms 返回;跑了 8 s 的 CubeMX 被取消后 8.4 s 内返回,`Src/``Inc/` 无残留、`.dsh-stm32/lock.json` 已释放、`STM32CubeMX.exe` 进程 0 → 0 |
|
|
595
|
-
| A10 | **通过(语义等价)** | §8.9 发现 1:GUI 与 CLI 的空行数不同,逐字节不可达;本轮用 A10q 证明插件没有夹带自己的风格 |
|
|
596
|
-
| A10q | **通过** | `test/e2e-a10q-product-parity.mjs`:同一个 `.ioc` 让 CubeMX 直接生成到独立目录 → 6 个文件去掉 USER CODE 后与插件 `Core/Src``Core/Inc` **逐字节一致**;插件只多出 `syscalls.c``sysmem.c``system_stm32f1xx.c`(模板/固件包补,GUI 工程同样放在 `Core/Src`) |
|
|
597
|
-
| A11 | **间接通过** | 需人在 VS Code 里按 F5,本轮没有自动化;依据是模板 `.vscode/launch.json` 与 `demo/` 的逐字节一致(仅工程名占位替换),而用户在 `demo/` 里已实际用过 F5 / Ctrl+F5 |
|
|
598
|
-
| A12 | **通过** | 同 `test/e2e-a7-a12-probe.mjs`:另起 openocd 占住探针 → 烧录失败(`Error: CMSIS-DAP transfer count mismatch: expected 3, got 2`),放掉占用后 1.6 s 烧录成功且已校验 |
|
|
599
|
-
| A13 | **通过** | 脚手架产物与同版本 GUI 工程:`CMakeLists.txt`、`CMakePresets.json`、`cmake/gcc-arm-none-eabi.cmake`、`cmake/starm-clang.cmake`、`cmake/stm32cubemx/CMakeLists.txt`、`STM32F103XX_FLASH.ld`、`.gitignore`、`.vscode/{settings,c_cpp_properties,launch}.json`、`*.ioc`、`startup_stm32f103xb.s`、`Core/Src/system_stm32f1xx.c` **逐字节一致**;唯一有意差异是 `cmake/user/CMakeLists.txt`(`demo/` 里那条 `test/test.c` 是脏数据,模板留空清单);Drivers 共同文件 596 个内容 sha256 全等 |
|
|
600
|
-
|
|
601
|
-
**M6 修掉的 8 个真问题**(每条都是"先测出来、再改代码"):
|
|
602
|
-
|
|
603
|
-
1. `code_patch` 的 append 落在 `while(1)` 收尾括号**之后** → 代码在 `main()` 外、不可达,链接器 `gc-sections` 把变量和自增一起丢掉(elf 里根本没有 `g_e2e_count`)。改成"退到最后一个纯括号行之前"。
|
|
604
|
-
2. `code_patch` 的 replace 会删掉块内的 `{`/`}`(CubeMX 的 `USER CODE 3` 之间就夹着 `while(1)` 的收尾括号)→ 现在直接拒绝并建议用 append。
|
|
605
|
-
3. 改写块内容时把整文件行尾统一成 LF,破坏"块外字节原样保留" → 按原文判定 `\r\n`/`\n` 再拼接。
|
|
606
|
-
4. 新工程第一次 build 必失败(没有 `CMakeCache.txt`,`runBuild` 只做 `cmake --build`)→ 自动先 `cmake --preset`。
|
|
607
|
-
5. **假成功**:把含 `build/` 的工程复制/改名后,cmake 打印 `CMake Error: The current CMakeCache.txt directory … is different`,但 ninja 仍旧 `no work to do`、退出码 **0** → 现在显式判失败("build 目录是从别处复制或移动过来的")。
|
|
608
|
-
6. 早先版本的脚手架把固件包 `Drivers/` 全量复制(5 392 文件、31 s),其中 4 493 个是 `CMSIS/docs/**`、DSP/NN 示例、`BSP/` → 加跳过清单后 629 文件、**~2 s**。
|
|
609
|
-
7. CLI 生成不产出 `sysmem.c`/`syscalls.c`,而 `cmake/stm32cubemx/CMakeLists.txt` 写死了引用 → 模板补进 `Core/Src/`(模板文件 12 → 14)。
|
|
610
|
-
8. 取消语义缺失:被中断的 build/generate 只会报"超时/失败" → 现在明确报"已取消",且 generate 会清掉半成品 `Src/``Inc/`、释放锁。
|
|
611
|
-
|
|
612
|
-
**离线套件(11 个,90 个用例,0 失败)**:`build-units` 5、`commands-units` 6、`doctor-regs-units` 5、`engine-units` 8、`flash-units` 6、`ioc-plan-units` 9、`ioc-units` 6、`scaffold-patch-units` 11、`search-roots-units` 9、`session-units` 8、`schema-guard` 17(覆盖全部 15 个工具的输出契约;M6 补了 `stm32_env_probe` 与 `stm32_ioc_inspect` 两个此前漏掉的工具,并用假 subprocess 让 `env_probe` 的成功路径也能离线断言)。
|
|
613
|
-
|
|
614
|
-
**宿主侧复核(重启 dsh 后,真进程注册的工具)**:`stm32_project_create` 空目录 **1690 ms**(14 个模板文件 + 629 个固件文件)
|
|
615
|
-
→ `stm32_generate` **61.0 s** / 6 文件 → `stm32_code_patch`(`PV` 声明 + `3` 自增)→ `stm32_build` 首次自动 `cmake --preset Debug` 5.4 s、编译 3.0 s、
|
|
616
|
-
RAM 7.73% / FLASH 7.21% → `stm32_flash` 2.5 s 校验通过 → `stm32_regs_read` 读 `g_host_check`(`0x2000000C`)`0x03f99ddd → 0x0484cfac`;
|
|
617
|
-
A5 在宿主侧同样拦下(`guard="no-debug"`、`args=[]`,未拼 openocd 参数)。宿主实跑另暴露一个使用细节:CLI 产出的 `main.c` 私有变量块标签是 `PV`,
|
|
618
|
-
把文档里的长名字 `Private variables` 当块名会被拒(工具列出 19 个真标签)——这是有意不猜同义词。
|
|
619
|
-
|
|
620
|
-
## 12. 分期
|
|
621
|
-
|
|
622
|
-
| 里程碑 | 内容 | 状态 |
|
|
623
|
-
|---|---|---|
|
|
624
|
-
| **M0** | 实验:D3(生成落点)、D4(USER CODE 保活)、A10 可行性 | **已完成**(§8.3;证据在 `demo/m0/`) |
|
|
625
|
-
| **M1** | 确认 T1;engine 层 `generate`(CLI 调用 → 布局映射 → USER CODE 合并)+ fixture 测试 | **已完成**(8 个单测 + 真实 e2e 6/6,§8.6) |
|
|
626
|
-
| **M2** | 只读层:`env_probe` / `ioc_inspect` / `regs_read` / `doctor` | **已完成**(单测 5,真实 e2e 10/10,§8.8) |
|
|
627
|
-
| **M3** | 构建与烧录:`build` / `flash` / `debug_run` | **已完成**(单测 5+6,真实 e2e 5/5 与 5/5,§8.7)——解决 P1"只想烧录不进调试" |
|
|
628
|
-
| **M4** | 事务层:`plan` / `apply` / 备份 / 回滚 / 会话租约 | **已完成**:单测 9+8、契约 12/12、真板会话 9/9、事务闭环 9/9、宿主复验全过;`turn/end` 自动释放探针已实测(§8.10) |
|
|
629
|
-
| **M5** | 打磨:斜杠命令、SKILL、日志、A1–A13 全绿 | **已完成**:五条斜杠命令 + `stm32-workflow` SKILL,单测 6/6、真板 e2e 14/14(§8.11) |
|
|
630
|
-
| **M6** | 补缺口:`project_create` / `code_patch` / 烧录守卫(A5)/ 首次构建自动配置;A1–A13 总验收 | **已完成**:A1–A13 全绿(A11 为间接证据),离线 80 个用例 0 失败、契约 16/16(覆盖全部 15 个工具),A1 真机端到端计数器 17 → 39(§8.12) |
|
|
631
|
-
|
|
632
|
-
## 13. 已定决策总表(单一真相源)
|
|
633
|
-
|
|
634
|
-
| # | 决定 | 备注 |
|
|
635
|
-
|---|---|---|
|
|
636
|
-
| 1 | 芯片只 STM32F103C8T6,型号表驱动(后续加 JSON 不改代码) | 引脚名、时钟、容量、链接脚本、openocd target 全从表取 |
|
|
637
|
-
| 2 | 代码只写 USER CODE 块;锚点缺失则拒绝并列出可用锚点 | 编码规范留给后续 skill |
|
|
638
|
-
| 3 | 工具链 msys64 优先(`D:\app\msys64\ucrt64\bin`),ST bundle fallback | gcc 13.3.0 / gdb-multiarch 16.2 / openocd 0.12.0 / cmake 3.31.5 / ninja 1.12.1 |
|
|
639
|
-
| 4 | 探针只 CMSIS-DAP | interface / target / reset_config 走型号表 + 探针表 |
|
|
640
|
-
| 5 | 不做 UI,v1 纯工具层 + 斜杠命令 | 无 client 侧代码 |
|
|
641
|
-
| 6 | 接受部分调用需全权限 | generate / apply / build / flash;README 明示原因 |
|
|
642
|
-
| 7 | `.ioc` 修改永远 plan → 确认 → apply;apply 带 `plan_id` + 源 SHA-256 校验 | 无静默写盘 |
|
|
643
|
-
| 8 | 长任务走 job(>20 s:apply / generate / build),其余阻塞 | generate 实测 3–4 min |
|
|
644
|
-
| 9 | 调试默认 `debug_run`(用完就关);`debug_session` 显式申请,由 **`turn/end` 钩子**精确关闭(TTL 60–90 s 仅作安全网) | T1 已确认,见 §6.4 |
|
|
645
|
-
| 10 | 生成 = CLI 调用 + 布局映射 + USER CODE 合并 + 脚手架模板(四件事) | §8 实测结论 |
|
|
646
|
-
| 11 | 脚手架来源:项目自身复制 或 模板快照(记版本),禁止手写 | 建议以现有 `demo/` 作模板基线 |
|
|
647
|
-
| 12 | TypeScript + `tsc` + `engines.node >= 20` + 零运行时依赖 | §9.1 |
|
|
648
|
-
| 13 | 验收 A10 / A10q / A13 替代原"逐文件哈希全一致" | 用户已确认 |
|
|
649
|
-
|
|
650
|
-
## 14. 未定 / 待观察
|
|
651
|
-
|
|
652
|
-
| # | 项 | 什么时候定 |
|
|
653
|
-
|---|---|---|
|
|
654
|
-
| T2 | 是否需要"GUI 生成一次作为金标准基线"的回归测试流程 | M1 结束后 |
|
|
655
|
-
| T3 | 模板快照取自 `demo/` 还是另建一个最简工程 | M1 设计时 |
|
|
656
|
-
| T4 | CubeMX2 是否值得以后做 generator 适配器(`.ioc2`) | v2 视需求 |
|
|
657
|
-
| T5 | `regs_read` 是否支持"传符号名,内部用 `arm-none-eabi-nm` 解析成地址"(重新生成后符号地址会漂移,实测 `g_led_blink_count` 0x20000028 → 0x2000002C) | M5 |
|
|
658
|
-
| T6 | A10 已降级为"语义等价"(§8.9 发现 1:CLI 与 GUI 的空行数不同);是否需要"归一化后比对"的自动回归脚本 | M5 |
|
|
659
|
-
|
|
660
|
-
## 15. 术语表
|
|
661
|
-
|
|
662
|
-
| 术语 | 含义 |
|
|
663
|
-
|---|---|
|
|
664
|
-
| 单飞锁 | 同一时刻只允许一个同类外部进程(CubeMX / openocd / ninja) |
|
|
665
|
-
| USER CODE 块 | `/* USER CODE BEGIN X */ ... /* USER CODE END X */`,CubeMX 重新生成时唯一保留的区域 |
|
|
666
|
-
| 空壳检测 | 生成后检查是否真产出 `MX_GPIO_Init` 等内容(防 P3 假成功) |
|
|
667
|
-
| 布局映射 | CLI 的 `Src/`、`Inc/` → 工程的 `Core/Src`、`Core/Inc`,并按 `CoupleFile` 决定是否合并进 `main.c` |
|
|
668
|
-
| 租约 | 调试会话的存活凭证,过期自动释放探针 |
|
|
669
|
-
| 金标准基线 | 用 GUI 生成一次的结果,作为逐字节对比基准 |
|
|
670
|
-
|
|
671
|
-
---
|
|
672
|
-
|
|
673
|
-
**证据索引**:`demo/m0/`(E1–E4 日志 e1–e4.log、清单 e2-before.txt / e2-after.txt)、`demo/.dsh-stm32/backups/20261022-175732/`(generate 落位前的备份,用于 A10 比对)、`demo/mxverify/`(配置变更 → 非 USER CODE 区变化)、`demo/_scratch/`(纯命令行建工程模板:build.ps1 / flash.ps1 / debug.ps1 / README.md)、`demo/.vscode/launch.json`(只烧录 / 烧录并调试两条)。
|