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
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
* 但凡是能注册的服务就不要依赖路径约定(规格 §9)。
|
|
6
6
|
*/
|
|
7
7
|
export const STM32_SKILL_NAME = "stm32-workflow";
|
|
8
|
-
const DESCRIPTION = "
|
|
9
|
-
export const SKILL_CONTENT = "# STM32 工作流(dsh-stm32)\n\n适用:**STM32F1 全系**(F100/101/102/103/105/107)+ 本工程按型号生成的 CMake 工程。本机的验证板是蓝丸 STM32F103C8T6(64 KiB Flash / 20 KiB RAM,CMSIS-DAP 探针);换型号不是\"换块板子\",是一起换启动文件、设备宏与链接脚本——`stm32_project_create` / `stm32_generate` 按型号渲染(STM32F103RCT6 → `startup_stm32f103xe.s` + `STM32F103xE` + `STM32F103RCTx_FLASH.ld`),别手工替换这三样。\n\n## 〇、先定路线(每个新功能都先做这一步)\n\n动手写代码前先调 `stm32_route_plan`(`requirement` 一句话,可再给 `peripherals`):它按这台芯片与这句需求逐外设给出 HAL 与寄存器两版的代价/风险,并判出 `register-ok` / `both-viable` / `hal-only` / `unclear`。\n\n- `register-ok`:不建 `.ioc`,走寄存器版(启动文件与设备头从缓存目录取,不预置进插件)。\n- 要 HAL:先看工具链与固件包就位没有。`gcc` / `cmake` / `ninja` / `openocd` / `gdb` 可以让 `stm32_env_install` 代装;**CubeMX 与固件包插件不代装**(GUI 向导 + 要 ST 账号),照 `guides[].steps` 自己做,离线机器可以整目录拷过来。\n- `unclear`:别猜,先把需求说具体(外设、数据量、要不要中断/DMA),再重调一次。\n\n## 一、硬规范(红线)\n\n**R1 代码只准写在 USER CODE 块之间。**\n`/* USER CODE BEGIN X */` 与 `/* USER CODE END X */` 之间是 CubeMX 承诺\"重新生成时原样保留\"的唯一区域。\n想加的功能(GPIO 操作、状态机、自己的 .c 逻辑)全部写在块内。块外的任何一行都不属于你。\n\n**R2 不许改 CubeMX 生成区。** 具体包括(不是举例,是清单):\n- `Core/Src/main.c` 的 `main()`、`SystemClock_Config()`、`MX_GPIO_Init()` 等 `MX_*_Init()` 函数体;\n- `Core/Inc/main.h` 里 `/* Private defines */` 段的 `_Pin`/`_GPIO_Port` 宏;\n- `Core/Src/stm32f1xx_hal_msp.c`、`Core/Src/stm32f1xx_it.c`(中断服务函数内部若要加内容,只能加在它自带的 USER CODE 块里);\n- `Core/Inc/stm32f1xx_hal_conf.h`、`Core/Src/system_stm32f1xx.c`、本型号的启动文件(C8T6 是 `startup_stm32f103xb.s`,RCT6 是 `startup_stm32f103xe.s`,F107 是 `startup_stm32f107xc.s`)、本型号的链接脚本 `<DeviceId>_FLASH.ld`(`STM32F103C8Tx_FLASH.ld`、`STM32F103RCTx_FLASH.ld`、`STM32F107VCTx_FLASH.ld`;模板里的旧名 `STM32F103XX_FLASH.ld` 只是 C8T6 兼容副本);\n- `CMakeLists.txt`、`cmake/stm32cubemx/CMakeLists.txt`、`.mxproject`、`demo.ioc`(.ioc 只能通过事务改,见 R3)。\n理由:这些文件由 CubeMX 按 .ioc 重写;手改会被无声覆盖,而且覆盖后编译不报错(源清单写死在 `cmake/stm32cubemx/CMakeLists.txt:21-28`),故障会以\"改了不生效\"的形式出现。\n\n**R3 配置只准走 .ioc 事务:`stm32_ioc_plan` → 用户确认 → `stm32_ioc_apply`。**\n不要手改 .ioc 文本,不要开 CubeMX GUI,不要\"顺手\"改引脚/时钟。改时钟走同一条事务:`stm32_ioc_plan` 的 `clock: { targetHz }` 枚举可行的 PLL 组合、取最接近目标的那一档(不可达时显式标注「不可达,已选 X MHz(±Y)」),并把 `PLLMUL` / `SYSCLKFreq_VALUE` / `HCLKFre` 这些派生键全量重算;超限(SYSCLK > 72 MHz、APB1 > 36 MHz、ADC > 14 MHz 等)时它一个键都不写。apply 必须带 `planId`(`stm32_ioc_plan` 返回的那个计划 ID,参数名就是 planId),源文件 SHA-256 变了就拒绝。\n\n**R4 不许生成 `No_Debug` 的 SYS 配置。** 那会生成 `__HAL_AFIO_REMAP_SWJ_DISABLE()`,烧进去以后固件一上电就关掉 PA13/PA14 的 SWD 功能,**调试口永久失联**,只能靠 BOOT0 进系统 bootloader 抢救。\n.ioc 里必须有 `PA13.Signal=SYS_JTMS-SWDIO`、`PA14.Signal=SYS_JTCK-SWCLK`、`*.Mode=Serial_Wire`。ioc_inspect 报这条警告时必须先修。\n\n**R5 烧录与调试分开。**\n只烧录:`stm32_flash` 或 `/stm32-flash`(openocd `program ... verify reset exit`,烧完就跑,不进调试会话)。\n调试:`stm32_debug_run`(一次性停 main、取 pc/栈后释放)或 `/stm32-debug` + `stm32_debug_eval`(保持会话)。\n永远不要用\"能不能断下来\"来判断烧录成功——烧录成功的证据是 `** Programming Finished **` 与 `** Verified OK **`。\n\n**R6 探针只有一块。** build / flash / generate 之前先让出调试会话;我输出结束(turn/end)时插件会自动关会话,所以别在输出中途把探针攥着不说。\n\n**R7 先 build 再 flash。** 改完代码不编译就烧,烧的是旧 elf;烧完看现象会得出错误结论。\n\n**R8 结论必须带证据。** 说\"闪了\"要给寄存器/计数器证据(例如 `GPIOC_ODR` 在 0x2000/0x0000 之间翻转、`g_led_blink_count` 单调增长),不要只说\"看起来好了\"。\n\n## 二、标准流程\n\n1. `stm32_env_probe` —— 工具链齐不齐(gcc/gdb/openocd/cmake/ninja + CubeMX)。缺哪个就照它给的 `install` 装(第一条最省事,带可粘贴的 pacman / winget 命令),装完按 `verify` 自检;它还会问要不要我代装。CubeMX 是可选的:只影响建工程与重新生成,不影响编译/烧录/调试。\n2. `stm32_ioc_inspect` —— 看清引脚/时钟/调试口;有 `warnings` 先处理(尤其 Serial Wire)。\n3. 需要改引脚/时钟:`stm32_ioc_plan` → 给用户看 diff → `stm32_ioc_apply`(自动备份到 `.dsh-stm32/backups/<时间戳>-ioc/`)。时钟给 `clock: { targetHz }`(要钉死倍频就 `clock: { pllMul }`),报告里带逐外设频率与 UART 波特率误差。\n4. `stm32_generate` —— 无头重新生成(3–4 分钟,走 job)。产物 `Src/`/`Inc/` 会被搬到 `Core/Src`/`Core/Inc`,USER CODE 按标签保活,生成用的临时目录会被删掉。\n5. 写代码:**只在 USER CODE 块内**。\n6. `stm32_build`(clean 才有内存占用表)→ 0 错再往下。\n7. `stm32_flash` —— 只烧录;或 `stm32_debug_run` —— 烧录并停在 main。\n8. 验证:`stm32_regs_read`(读 GPIOC_ODR / AFIO_MAPR / 全局变量)或 `stm32_debug_eval`。\n\n## 三、命令对照\n\n| 想要 | 工具 | 斜杠命令 |\n|---|---|---|\n| 只烧录 | `stm32_flash` | `/stm32-flash` |\n| 烧录 + 调试 | `stm32_debug_run`(一次性)/ `stm32_debug_session`(保持) | `/stm32-debug` |\n| 编译 | `stm32_build` | `/stm32-build` |\n| 体检 | `stm32_doctor` | `/stm32-doctor` |\n| 释放探针 | `stm32_debug_stop` | `/stm32-stop` |\n\n## 四、踩过的坑(本机实测,别重复)\n\n1. **CubeMX 的\"假成功\"**:直接 `STM32CubeMX.exe -q script` 会 detach 出 javaw 并立刻 exit 0,stdout 是空的。必须 `jre\\bin\\java.exe -jar STM32CubeMX.exe -q <脚本>` 并重定向日志,成功标志是日志里的 `Code succesfully generated under`(CubeMX 自己把 successfully 拼错了)。启动要 90–150 s。\n2. **CLI 生成忽略工程设置**:.ioc 写着 `MainLocation=Core/Src`、`CoupleFile=false`,CLI 依然固定写 `Src/`/`Inc/` 并按外设拆文件。所以必须落地映射 + USER CODE 合并,否则核心代码会被搬丢。\n3. **USER CODE 按标签保活**:同标签用旧正文覆盖新正文;旧有新无的标签直接丢;标签不配对则那对放弃。\n4. **`mdw` 输出是 8 位裸 hex**:`0x4001100c: 00000000`;`[reg pc]` 返回 `pc (/32): 0x...`,要 `lindex 1`。\n5. **openocd 的日志走 stderr**:等 \"Listening on port\" 必须同时 drain stdout 和 stderr,否则永远等不到。\n6. **读寄存器的收尾用 `resume` 不要 `reset run`**:后者会复位芯片,计数器归零,看起来像\"变量丢了\"。\n7. **符号地址会随重链接漂移**:`g_led_blink_count` 曾在 `0x20000028`,改一行后变成 `0x2000002C`,老地址变成 `uwTick`。读符号前用 `nm` 确认,或直接读物理地址。\n8. **装插件用一条命令**:`dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main`(`lib/` 已入库,pnpm 不替 git 依赖构建也能直接用)。只有要改插件源码时才用 `link:`,且升级前先删掉 `node_modules/dsh-stm32` 这个 junction,否则 pnpm 覆盖时报 `EPERM`。\n9. **宿主输出契约**:工具返回的对象在 `additionalProperties: false` 下不能有多余键;声明为 number/object 的字段不接受 `null`(用可选字段 + 条件展开)。\n10. **ninja / piped stdio 在受限沙箱里会挂或 EPERM**:那是工具侧沙箱,不是工程问题;插件里经 `ctx.subprocess` 起的进程不受会话文件沙箱限制。\n11. **裸 `cmake -S . -B build` 会丢工具链文件**:交叉编译器只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不读 preset 就退回主机编译器,报一串找不到 `arm-none-eabi-gcc`。要么 `cmake --preset default`,要么显式 `-DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake`。\n12. **换芯片别留下旧链接脚本名**:`-T` 必须指向按型号渲染的 `<DeviceId>_FLASH.ld`(工具里的 `pointLinkerFlagAt` 会把工具链中的旧名改指到新名,手改反而绕开它);留着 `STM32F103XX_FLASH.ld` 烧到 256 KiB 的 RCT6 上就是「编译过、跑飞」。\n\n## 五、自检清单(每次交付前)\n\n- [ ] 改动全部落在 USER CODE 块内(`git diff` 里没有生成区的行)\n- [ ] .ioc 改动走过 plan → apply(有备份)\n- [ ] Serial Wire 仍在(`stm32_ioc_inspect` 的 `warnings` 为空)\n- [ ] `stm32_build` 0 error、0 unexpected warning\n- [ ] 烧录有 `** Verified OK **`\n- [ ] 行为验证有寄存器/计数器证据\n- [ ] 探针已释放(`stm32_doctor` 无残留进程)\n- [ ] 芯片型号 / 启动文件 / 设备宏 / `.ld` 四者配套(`stm32_doctor` 的芯片一致性检查无 blocker)";
|
|
8
|
+
const DESCRIPTION = "STM32 多族(HAL 建工程 22 族+WB 双核 M4;寄存器建工程 13 族)+ dsh-stm32 标准工作流:红线(自有三层文件外只写 USER CODE、.ioc 事务、烧录调试分开、Serial Wire 不能关)+ 三层工程规范(Driver/Service/App,新文件只登记 cmake/user/CMakeLists.txt)";
|
|
9
|
+
export const SKILL_CONTENT = "# STM32 工作流(dsh-stm32)\n\n适用:插件当前支持的族——**HAL 建工程 22 个单核族**(C0/F0/F1/F2/F3/F4/F7/G0/G4/H5/H7/L0/L1/L4/L4+/L5/U0/U3/U5/WBA/WL)+ 双核 WB(只建 M4 核);**寄存器版建工程覆盖内置资源 chips.json 里的 13 族**(C0/F0/F1/F2/F3/F4/F7/G0/G4/L0/L1/L4/U0;时钟留复位默认、LED/GPIO 按族生成),其余族仍只有 HAL。各族能力由族画像诚实降级,拿不准先 `stm32_route_plan`。本工程的验证板仍是蓝丸。本机的验证板是蓝丸 STM32F103C8T6(64 KiB Flash / 20 KiB RAM);探针 ST-Link / DAPLink(CMSIS-DAP)/ J-Link 都支持——`stm32_flash` / `stm32_debug_run` 先按 USB 实见结果选 interface(ST-Link → `interface/stlink-dap.cfg`,DAPLink/CMSIS-DAP → `interface/cmsis-dap.cfg`,J-Link → `interface/jlink.cfg` 且必须再跟一条 `-c \"transport select swd\"`,它默认选 jtag),装了 STM32CubeProgrammer 时 ST-Link 还有 CLI 后端(`stm32_flash` 的 backend 参数:auto / openocd / cubeprogrammer);`stm32_project_create` 建的工程自带 `.vscode/launch.json`(① 只烧录 / ② 烧录并调试),直接按 F5/Ctrl+F5 即可;换型号不是'换块板子',是一起换启动文件、设备宏与链接脚本——`stm32_project_create` / `stm32_generate` 按型号渲染(STM32F103RCT6 → `startup_stm32f103xe.s` + `STM32F103xE` + `STM32F103RCTx_FLASH.ld`),别手工替换这三样。\n\n## 〇、先定路线(每个新功能都先做这一步)\n\n动手写代码前先调 `stm32_route_plan`(`requirement` 一句话,可再给 `peripherals`):它按这台芯片与这句需求逐外设给出 HAL 与寄存器两版的代价/风险,并判出 `register-ok` / `both-viable` / `hal-only` / `unclear`。\n\n- `register-ok`:不建 `.ioc`,走寄存器版(启动文件与设备头从缓存目录取,不预置进插件)。**寄存器版建工程覆盖 13 族**(内置资源 chips.json 收了的族),不在这 13 族里的芯片会被判 `hal-only`。\n- 要 HAL:先看工具链与固件包就位没有。`gcc` / `cmake` / `ninja` / `openocd` / `gdb` 可以让 `stm32_env_install` 代装;**CubeMX 与固件包插件不代装**(GUI 向导 + 要 ST 账号),照 `guides[].steps` 自己做,离线机器可以整目录拷过来。\n- `unclear`:别猜,先把需求说具体(外设、数据量、要不要中断/DMA),再重调一次。\n\n## 一、硬规范(红线)\n\n**R1 HAL 工程里,只有自己的三层文件(App/Service/Driver)可自由修改;其余文件只准写在 USER CODE 块内。**\n自己的 `App/`、`Service/`、`Driver/` 下的 .c/.h(见第三节)随便建、随便改,业务逻辑只往那里长。\n除它们之外的一切 CubeMX 产物(`Core/Src/main.c`、各 `*_it.c`、HAL 配置头等)只准在 `/* USER CODE BEGIN X */` 与 `/* USER CODE END X */` 之间写——那是 CubeMX 承诺'重新生成时原样保留'的唯一区域,块外任何一行都不属于你。\n\n**R2 不许改 CubeMX 生成区。** 具体包括(不是举例,是清单):\n- `Core/Src/main.c` 的 `main()`、`SystemClock_Config()`、`MX_GPIO_Init()` 等 `MX_*_Init()` 函数体;\n- `Core/Inc/main.h` 里 `/* Private defines */` 段的 `_Pin`/`_GPIO_Port` 宏;\n- `Core/Src/stm32f1xx_hal_msp.c`、`Core/Src/stm32f1xx_it.c`(中断服务函数内部若要加内容,只能加在它自带的 USER CODE 块里;文件名前缀随族变化,F4 是 `stm32f4xx_*`);\n- `Core/Inc/stm32f1xx_hal_conf.h`、`Core/Src/system_stm32f1xx.c`、本型号的启动文件(C8T6 是 `startup_stm32f103xb.s`,RCT6 是 `startup_stm32f103xe.s`,F107 是 `startup_stm32f107xc.s`)、本型号的链接脚本 `<DeviceId>_FLASH.ld`(`STM32F103C8Tx_FLASH.ld`、`STM32F103RCTx_FLASH.ld`、`STM32F107VCTx_FLASH.ld`;模板里的旧名 `STM32F103XX_FLASH.ld` 只是 C8T6 兼容副本);\n- 根 `CMakeLists.txt`、`cmake/stm32cubemx/CMakeLists.txt`、`.mxproject`、`demo.ioc`(.ioc 只能通过事务改,见 R3)。**唯一例外:`cmake/user/CMakeLists.txt` 是用户源注册钩子,新模块登记只准改它(见 W3)。**\n理由:这些文件由 CubeMX 按 .ioc 重写;手改会被无声覆盖,而且覆盖后编译不报错(源清单写死在 `cmake/stm32cubemx/CMakeLists.txt:21-28`),故障会以'改了不生效'的形式出现。\n\n**R3 配置只准走 .ioc 事务:`stm32_ioc_plan` → 用户确认 → `stm32_ioc_apply`。**\n不要手改 .ioc 文本,不要开 CubeMX GUI,不要'顺手'改引脚/时钟。改时钟走同一条事务:`stm32_ioc_plan` 的 `clock: { targetHz }` 枚举可行的 PLL 组合、取最接近目标的那一档(不可达时显式标注「不可达,已选 X MHz(±Y)」),并把 `PLLMUL` / `SYSCLKFreq_VALUE` / `HCLKFre` 这些派生键全量重算;超限(SYSCLK > 72 MHz、APB1 > 36 MHz、ADC > 14 MHz 等)时它一个键都不写。apply 必须带 `planId`(`stm32_ioc_plan` 返回的那个计划 ID,参数名就是 planId),源文件 SHA-256 变了就拒绝。GPIO 引脚用 `pins` 的字段直接表达:`outputType: od` 写开漏(`pp` 是默认值、不写键)、`initial: high` 写初始电平(`low` 不写键)、`interrupt: rising|falling|both` 一次写全 EXTI 链路(`Signal=GPXTI<line>` + `GPIO_ModeDefaultEXTI` + `GPIOParameters` + `SH.GPXTI<line>` + 按线号自动选中的 `NVIC.EXTI*_IRQn`);外设中断用 `interrupts: [USART1:2:0]`(`2:0` 是 preempt:sub,名字按本机 db 实例 / SVD 中断表校验)。\n\n**R4 不许生成 `No_Debug` 的 SYS 配置。** 那会生成 `__HAL_AFIO_REMAP_SWJ_DISABLE()`,烧进去以后固件一上电就关掉 PA13/PA14 的 SWD 功能,**调试口永久失联**,只能靠 BOOT0 进系统 bootloader 抢救。\n.ioc 里必须有 `PA13.Signal=SYS_JTMS-SWDIO`、`PA14.Signal=SYS_JTCK-SWCLK`、`*.Mode=Serial_Wire`。ioc_inspect 报这条警告时必须先修。\n\n**R5 烧录与调试分开。**\n只烧录:`stm32_flash` 或 `/stm32-flash`(openocd `program ... verify reset exit`,烧完就跑,不进调试会话)。\n调试:`stm32_debug_run`(一次性停 main、取 pc/栈后释放)或 `/stm32-debug` + `stm32_debug_eval`(保持会话)。\n永远不要用'能不能断下来'来判断烧录成功——openocd 的证据是 `** Programming Finished **` 与 `** Verified OK **`,CubeProgrammer CLI 是 `Data downloaded successfully` 与 `Download verified successfully`。H5/WBA/WB0/WL3 这类 openocd 根本没有 flash 驱动的族,用 `stm32_flash` 的 `backend: \"cubeprogrammer\"`(只认 ST-Link;auto 也会在 openocd 失败后兜底)。\n\n**R6 探针只有一块,型号不必手选。** build / flash / generate 之前先让出调试会话(RTT / debug_session 会占着探针,先 `stm32_debug_stop` / `stm32_rtt stop`);我输出结束(turn/end)时插件会自动关会话,所以别在输出中途把探针攥着不说。interface 由工具按 USB 实见结果决定(ST-Link 走 stlink,DAPLink 走 cmsis-dap),报驱动不匹配时它会自动换一次;**只有工程里手写了 `openocd.cfg` 才以它为准**,那时你负责改它,插件不替你换。\n\n**R7 先 build 再 flash。** 改完代码不编译就烧,烧的是旧 elf;烧完看现象会得出错误结论。\n\n**R8 结论必须带证据。** 说'闪了'要给寄存器/计数器证据(例如 `GPIOC_ODR` 在 0x2000/0x0000 之间翻转、`g_led_blink_count` 单调增长),不要只说'看起来好了'。\n\n## 二、标准流程\n\n1. `stm32_doctor` —— 工具链齐不齐(gcc/gdb/openocd/cmake/ninja + CubeMX)。缺哪个就照它给的 `install` 装(第一条最省事,带可粘贴的 pacman / winget 命令),装完按 `verify` 自检;它还会问要不要我代装。CubeMX 是可选的:只影响建工程与重新生成,不影响编译/烧录/调试。\n2. `stm32_ioc_inspect` —— 看清引脚/时钟/调试口;有 `warnings` 先处理(尤其 Serial Wire)。\n3. 需要改引脚/时钟:`stm32_ioc_plan` → 给用户看 diff → `stm32_ioc_apply`(自动备份到 `.dsh-stm32/backups/<时间戳>-ioc/`)。时钟给 `clock: { targetHz }`(要钉死倍频就 `clock: { pllMul }`),报告里带逐外设频率与 UART 波特率误差。\n4. `stm32_generate` —— 无头重新生成(3–4 分钟,走 job)。产物 `Src/`/`Inc/` 会被搬到 `Core/Src`/`Core/Inc`,USER CODE 按标签保活,生成用的临时目录会被删掉。\n5. 写代码:业务逻辑按第三节三层结构写进自己的 .c/.h;`main.c` 的 USER CODE 块只留 `app_init()` / `app_run()` 两个插头(W1/W2),块外一行都不碰(R1)。\n6. `stm32_build`(clean 才有内存占用表)→ 0 错再往下。\n7. `stm32_flash` —— 只烧录;或 `stm32_debug_run` —— 烧录并停在 main。\n8. 验证:`stm32_regs_read`(读 GPIOC_ODR / AFIO_MAPR / 全局变量)或 `stm32_debug_eval`。\n\n## 三、工程写作规范(三层结构与文件组织;针对 HAL 路线工程)\n\n**W1 程序分三层,目录即架构。新模块必须按此;存量代码渐进迁移,不要求一次到位。**\n- `Driver/`(下层):板级外设封装(led、key、uart…),全工程**唯一允许直接调 HAL** 的一层;一个模块一对文件:`Driver/led/led.c` + `led.h`。\n- `Service/`(中层):协议解析、调度、环形缓冲、参数存储;可调 Driver,禁止绕过它直接碰寄存器。\n- `App/`(上层):业务状态机与流程编排;只调 Service/Driver 的 API,**禁止 include HAL 头**。\n`Core/`、`Drivers/` 是 CubeMX 与固件包区,按 R1/R2 处理,不属于这三层。函数以模块名为前缀(`led_init()`、`ring_push()`),同一工程不混用命名风格。\n\n**W2 上层入口只留插头。** `Core/Src/main.c` 的 USER CODE 块里只放两个调用:`app_init()`(BEGIN 2)与 `app_run()`(WHILE 块)。业务逻辑一律写进 App/ 的文件;块内不写状态机、不写外设操作。\n\n**W3 新文件登记只准改 `cmake/user/CMakeLists.txt`(全工程唯一可编辑的 CMake 文件)。** 只动两个变量:`USER_Include_Dirs` 追加各模块目录、`USER_Application_Src` 追加各 .c(相对路径写法照抄现有条目)。根 `CMakeLists.txt` 与 `cmake/stm32cubemx/CMakeLists.txt` 都不许动——后者会被 CubeMX 重写覆盖(R2 的无声故障就出在这),前者 ST 名义上可改但本项目一律不动。\n\n**W4 中断纪律。** ISR(`stm32f1xx_it.c` 自带 USER CODE 块内)只置 `volatile` 标志或入环形缓冲,微秒级出中断;消费逻辑放 App/Service。ISR 上下文禁止 printf、Flash 写、长循环。\n\n**W5 时间与阻塞。** 计时统一 `HAL_GetTick()`;超时判断用回绕安全写法 `(uint32_t)(HAL_GetTick() - t0) < ms`。App/Service 禁止新增 `HAL_Delay` 与无超时 `while` 等待;Driver 初始化里的短等待必须带超时与失败返回。\n\n**W6 资源与错误。** 禁 `malloc`(静态分配 + 编译期尺寸);模块对外返回 `enum <mod>_err`(0 = OK),不返回裸 bool 掩盖失败原因;头文件只暴露类型与 API,实现细节 `static`;include guard 风格全工程统一。\n\n**W7 写完的验收顺序。** `stm32_build`(0 error)→ `stm32_flash`(看 Verified OK)→ 按 R8 读回寄存器/计数器证据。只改代码没动 .ioc 时**不要**跑 `stm32_generate`(省 3–4 分钟,也不引入回归面)。\n\n## 四、命令对照\n\n| 想要 | 工具 | 斜杠命令 |\n|---|---|---|\n| 只烧录 | `stm32_flash` | `/stm32-flash` |\n| 烧录 + 调试 | `stm32_debug_run`(一次性)/ `stm32_debug_session`(保持) | `/stm32-debug` |\n| 编译 | `stm32_build` | `/stm32-build` |\n| 体检 | `stm32_doctor` | `/stm32-doctor` |\n| 释放探针 | `stm32_debug_stop` | `/stm32-stop` |\n\n## 五、踩过的坑(本机实测,别重复)\n\n1. **CubeMX 的'假成功'**:直接 `STM32CubeMX.exe -q script` 会 detach 出 javaw 并立刻 exit 0,stdout 是空的。必须 `jre\\bin\\java.exe -jar STM32CubeMX.exe -q <脚本>` 并重定向日志,成功标志是日志里的 `Code succesfully generated under`(CubeMX 自己把 successfully 拼错了)。启动要 90–150 s。\n2. **CLI 生成忽略工程设置**:.ioc 写着 `MainLocation=Core/Src`、`CoupleFile=false`,CLI 依然固定写 `Src/`/`Inc/` 并按外设拆文件。所以必须落地映射 + USER CODE 合并,否则核心代码会被搬丢。\n3. **USER CODE 按标签保活**:同标签用旧正文覆盖新正文;旧有新无的标签直接丢;标签不配对则那对放弃。\n4. **`mdw` 输出是 8 位裸 hex**:`0x4001100c: 00000000`;`[reg pc]` 返回 `pc (/32): 0x...`,要 `lindex 1`。\n5. **openocd 的日志走 stderr**:等 'Listening on port' 必须同时 drain stdout 和 stderr,否则永远等不到。\n6. **读寄存器的收尾用 `resume` 不要 `reset run`**:后者会复位芯片,计数器归零,看起来像'变量丢了'。\n7. **符号地址会随重链接漂移**:`g_led_blink_count` 曾在 `0x20000028`,改一行后变成 `0x2000002C`,老地址变成 `uwTick`。读符号前用 `nm` 确认,或直接读物理地址。\n8. **装插件用一条命令**:`dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main`(`lib/` 已入库,pnpm 不替 git 依赖构建也能直接用)。只有要改插件源码时才用 `link:`,且升级前先删掉 `node_modules/dsh-stm32` 这个 junction,否则 pnpm 覆盖时报 `EPERM`。\n9. **宿主输出契约**:工具返回的对象在 `additionalProperties: false` 下不能有多余键;声明为 number/object 的字段不接受 `null`(用可选字段 + 条件展开)。\n10. **ninja / piped stdio 在受限沙箱里会挂或 EPERM**:那是工具侧沙箱,不是工程问题;插件里经 `ctx.subprocess` 起的进程不受会话文件沙箱限制。\n11. **裸 `cmake -S . -B build` 会丢工具链文件**:交叉编译器只由 `CMakePresets.json` 注入(`cmake/gcc-arm-none-eabi.cmake`),不读 preset 就退回主机编译器,报一串找不到 `arm-none-eabi-gcc`。要么 `cmake --preset default`,要么显式 `-DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake`。\n12. **换芯片别留下旧链接脚本名**:`-T` 必须指向按型号渲染的 `<DeviceId>_FLASH.ld`(工具里的 `pointLinkerFlagAt` 会把工具链中的旧名改指到新名,手改反而绕开它);留着 `STM32F103XX_FLASH.ld` 烧到 256 KiB 的 RCT6 上就是「编译过、跑飞」。\n\n## 六、自检清单(每次交付前)\n\n- [ ] 自有三层文件之外,改动全部落在 USER CODE 块内(`git diff` 里没有生成区的行)\n- [ ] 新增 .c/.h 已登记进 `cmake/user/CMakeLists.txt`(另外两份 CMakeLists 没动)\n- [ ] .ioc 改动走过 plan → apply(有备份)\n- [ ] Serial Wire 仍在(`stm32_ioc_inspect` 的 `warnings` 为空)\n- [ ] `stm32_build` 0 error、0 unexpected warning\n- [ ] 烧录有 `** Verified OK **`\n- [ ] 行为验证有寄存器/计数器证据\n- [ ] 探针已释放(`stm32_doctor` 无残留进程)\n- [ ] 芯片型号 / 启动文件 / 设备宏 / `.ld` 四者配套(`stm32_doctor` 的芯片一致性检查无 blocker)\n\n## 七、外设写了却没生效?先让它自己说(oracle 诊断)\n\n症状:`stm32_generate` 报成功、`Code succesfully generated`,但 `Core/Src/main.c` 里没有 `MX_TIM2_Init` / `MX_ADC1_Init`,`stm32f1xx_hal_conf.h` 的 `HAL_TIM_MODULE_ENABLED` 仍是注释,日志里**一个 ERROR 都没有**。CubeMX 对不认识的键就是这么处理的:静默丢弃。\n\n**第一步:调 `stm32_ioc_verify`**(约 25–40 s,把 .ioc 复制到 `.dsh-stm32/verify/<stamp>/` 后用 `config load` + `config save` 让 CubeMX 写回“它理解的结果”,工程里的 .ioc 一个字节都不动)。看这几个字段:\n\n- `droppedPeripherals`:写了但 CubeMX 没认的外设;\n- `plannedFunctions`:它计划生成的 `MX_*_Init`(等于不生成代码就预览结果);\n- `signalRewrites`:引脚信号被规范化的地方(`TIM2_CH1` → `S_TIM2_CH1_ETR`、`ADC1_IN1` → `ADCx_IN1`);\n- `sharedSignals`:它自己补出来的 `SH.<信号>.0=<IP 信号>,<IP 模式>`;\n- `autoAddedFunctions`:CubeMX 保存时自己往 `ProjectManager.functionlistsort` 追加的 `MX_*_Init` 条目(我们故意不写,它按既有编号自己补;不影响生成正确性,所以单独列出来而不算 diff);\n- `removedKeys` / `addedKeys`:被 CubeMX 删掉 / 它自己补出来的键(各截 60 条;拼错的键一定出现在 removedKeys 里);\n- `changedValues`:键还在、值被改写的(零 diff 不能只看键在不在);\n- `attribution`:把差异归因分桶——`orderOnly`(值相同、行序不同)、`valueNormalized`(值只是成员顺序/空白被规范化,语义不变)、`valueChanged`(值真被改)、`missingKeys` / `addedKeys` / `droppedPeripherals` / `autoAddedFunctions`,以及 `benign`;\n- `hints`:针对每个被丢外设的“缺什么”。\n\n**判“零实质差异”只看 `attribution.benign`**:`true` 表示只剩行序/成员序的规范化或它自己补的初始化清单,可以放心 generate;`false` 就按各桶逐条修(`removedKeys` 里的 `NVIC.<IP>_IRQn` 通常是“外设没启用就开中断”,`hints` 会直说)。\n\n**三条已知原因(按 hints 对号入座)**:\n\n1. 引脚没列进 `Mcu.PinN`(`Mcu.PinsNb` 也要跟着改)——只写 `PA5.Signal=…` 不列进引脚表,CubeMX 根本不应用这根脚。\n2. 普通外设(USART/SPI…)缺 `<pin>.Mode`:如 `PA9.Mode=Asynchronous`。\n3. 定时器/ADC 走**共享信号**,引脚不能写 `.Mode`,要写块:\n `PA0-WKUP.Signal=S_TIM2_CH1_ETR`(PA0 的定时器信号与 `TIM2_ETR` 合并,必须用合并名)+ `SH.S_TIM2_CH1_ETR.0=TIM2_CH1,PWM Generation1 CH1` + `SH.S_TIM2_CH1_ETR.ConfNb=1`;ADC 是 `PA1.Signal=ADCx_IN1` + `SH.ADCx_IN1.0=ADC1_IN1,IN1`。\n\n**修法**:优先用 `stm32_ioc_plan` 的 `peripherals:[{name:'TIM2', parameters:{Prescaler:'71',Period:'999'}}]` 预设(内置 USART1/2/3、TIM2/3/4 CH1 PWM、ADC1/2),它已经按上面三条写全;预设有缺口时再 `entries` 逐键补,改完**再跑一次 `stm32_ioc_verify` 确认 `droppedPeripherals` 为空**,最后才 `stm32_generate`。\n\n**读告警的口径**:`stm32_ioc_plan` 输出里带 `[R1]`…`[R23]` 前缀的告警/错误来自反编译 CubeMX 导入器 + 真机回写实验得到的离线规则(docs §35、§60):R1 = 有 Dma.* 但 Mcu.IPn 里缺 DMA;R2 = ADC Rank/Channel/NbrOfConversion 不自洽;R3 = NVIC 值不是 9 段;R5 = F1 的 ADC 预分频不是除 6;R7 = 某参数没列进 `<IP>.IPParameters` 白名单(会被静默忽略);R18 = 主频超过 db 里芯片上限;R20 = 中断名不在 SVD 中断表里;R21 = DMA 三件套缺件;R22 = 引脚上的 GPIO_* 属性没列进 `GPIOParameters`(CubeMX 会静默删掉,写了等于没写);R23 = EXTI 链路断了(缺 `GPIO_ModeDefaultEXTI` / `SH.GPXTI<line>` / `NVIC.EXTI*_IRQn`,或线号与引脚不符)。看到就先修,再去生成。另有 `[SCHEMA]` 前缀的告警(不是规则编号):生成器写出了不在 .ioc 真值表(`src/data/ioc-schema.ts`)里的键,多半是键名拼错或被 CubeMX 静默忽略的形状——先确认,确属新键再补进真值表。\n\n**别做**:不要手改工程里的 .ioc(走 plan → 用户确认 → apply);不要把 verify 的副本覆盖回工程(副本里被丢的键是真被删了);不要同时跑两个 CubeMX(有单飞锁,会提示占用)。verify 需要本机有可无头调用的 CubeMX(`stm32_ioc_verify` 的 `errors` 会说明去哪配)。";
|
|
10
10
|
/** 注册 skill;宿主没组合 skills 服务时直接返回。 */
|
|
11
11
|
export function registerStm32Skill(ctx) {
|
|
12
12
|
const skills = ctx.get("skills");
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* L3:stm32_assets —— 查看 / 校验插件内置资源(assets/)。
|
|
3
|
+
*
|
|
4
|
+
* 2026-11 起资源不再放独立仓库、也不再按需下载:device 事实层(chips.json / svd)、ioc 模板、
|
|
5
|
+
* 链接脚本、启动文件、设备头全部随 npm 包发布,装好插件就能离线用。这个工具因此从「下载器」
|
|
6
|
+
* 变成「体检器」:
|
|
7
|
+
* · list 内置资源版本、profile=core/full 的文件清单、本地在不在、占多大;
|
|
8
|
+
* · refresh 旧名字,保留兼容:等价于 verify(资源和插件同版本,没有「刷新」这回事);
|
|
9
|
+
* · verify 逐文件 sha256 复核(怀疑装坏 / 被杀软改过 / 手工动过 assets/ 就跑它);
|
|
10
|
+
* · prune 只清 DSH_STM32_ASSETS 覆盖目录下的历史版本,内置资源永不删除。
|
|
11
|
+
*
|
|
12
|
+
* 失败不抛:都返回 ok:false + 人话原因;缺文件只可能是插件安装不完整,提示重装插件,
|
|
13
|
+
* 而不是让用户去「联网 refresh」——已经没有那个通道了。
|
|
14
|
+
*/
|
|
15
|
+
import fs from "node:fs";
|
|
16
|
+
import path from "node:path";
|
|
17
|
+
import { assetsRootInfo, listInstalledVersions, normalizeProfile, profileFiles, pruneOldVersions, readLocalManifest, verifyInstalled, } from "../engine/assets.js";
|
|
18
|
+
export const ASSETS_TOOL = "stm32_assets";
|
|
19
|
+
const BUILTIN_NOTE = "资源随插件内置(assets/),不需要联网下载;文件缺失说明插件安装不完整,重装插件即可恢复。";
|
|
20
|
+
const fileSchema = {
|
|
21
|
+
type: "object",
|
|
22
|
+
additionalProperties: false,
|
|
23
|
+
properties: {
|
|
24
|
+
path: { type: "string" },
|
|
25
|
+
bytes: { type: "number" },
|
|
26
|
+
sha256: { type: "string" },
|
|
27
|
+
status: { type: "string" },
|
|
28
|
+
detail: { type: "string" },
|
|
29
|
+
},
|
|
30
|
+
required: ["path", "bytes", "sha256", "status", "detail"],
|
|
31
|
+
};
|
|
32
|
+
const versionSchema = {
|
|
33
|
+
type: "object",
|
|
34
|
+
additionalProperties: false,
|
|
35
|
+
properties: {
|
|
36
|
+
version: { type: "string" },
|
|
37
|
+
files: { type: "number" },
|
|
38
|
+
bytes: { type: "number" },
|
|
39
|
+
profiles: { type: "array", items: { type: "string" } },
|
|
40
|
+
installedAt: { type: "string" },
|
|
41
|
+
current: { type: "boolean" },
|
|
42
|
+
},
|
|
43
|
+
required: ["version", "files", "bytes", "profiles", "installedAt", "current"],
|
|
44
|
+
};
|
|
45
|
+
export const outputSchema = {
|
|
46
|
+
type: "object",
|
|
47
|
+
additionalProperties: false,
|
|
48
|
+
properties: {
|
|
49
|
+
action: { type: "string" },
|
|
50
|
+
ok: { type: "boolean" },
|
|
51
|
+
root: { type: "string" },
|
|
52
|
+
origin: { type: "string" },
|
|
53
|
+
version: { type: "string" },
|
|
54
|
+
profile: { type: "string" },
|
|
55
|
+
source: { type: "string" },
|
|
56
|
+
fileCount: { type: "number" },
|
|
57
|
+
totalBytes: { type: "number" },
|
|
58
|
+
files: { type: "array", items: fileSchema },
|
|
59
|
+
versions: { type: "array", items: versionSchema },
|
|
60
|
+
attempts: { type: "array", items: { type: "string" } },
|
|
61
|
+
offlineFallback: { type: "string" },
|
|
62
|
+
message: { type: "string" },
|
|
63
|
+
},
|
|
64
|
+
required: [
|
|
65
|
+
"action",
|
|
66
|
+
"ok",
|
|
67
|
+
"root",
|
|
68
|
+
"origin",
|
|
69
|
+
"version",
|
|
70
|
+
"profile",
|
|
71
|
+
"source",
|
|
72
|
+
"fileCount",
|
|
73
|
+
"totalBytes",
|
|
74
|
+
"files",
|
|
75
|
+
"versions",
|
|
76
|
+
"attempts",
|
|
77
|
+
"offlineFallback",
|
|
78
|
+
"message",
|
|
79
|
+
],
|
|
80
|
+
};
|
|
81
|
+
function toVersionView(item) {
|
|
82
|
+
return {
|
|
83
|
+
version: item.version,
|
|
84
|
+
files: item.fileCount,
|
|
85
|
+
bytes: item.totalBytes,
|
|
86
|
+
profiles: item.profiles,
|
|
87
|
+
installedAt: item.installedAt,
|
|
88
|
+
current: item.current,
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
function describeBytes(bytes) {
|
|
92
|
+
if (bytes < 1024)
|
|
93
|
+
return String(bytes) + " B";
|
|
94
|
+
if (bytes < 1024 * 1024)
|
|
95
|
+
return (bytes / 1024).toFixed(1) + " KB";
|
|
96
|
+
return (bytes / 1024 / 1024).toFixed(2) + " MB";
|
|
97
|
+
}
|
|
98
|
+
export function registerAssets(ctx, options = {}) {
|
|
99
|
+
ctx.tools.register({
|
|
100
|
+
name: ASSETS_TOOL,
|
|
101
|
+
description: "查看 / 校验插件内置的 STM32 资源(随包发布,在 assets/:device 事实层 device/<族>/chips.json 与 device/f1/svd、ioc 模板、链接脚本;profile=full 另含 startup/ 与 headers/)。" +
|
|
102
|
+
"不需要联网下载:action=list 看当前版本、文件清单、在不在、占多大;refresh 是 verify 的旧名(等价,保留兼容);verify 逐文件复核 manifest 的 sha256(怀疑装坏时用);prune 只清 DSH_STM32_ASSETS 覆盖目录下的历史版本,内置资源永不删除。" +
|
|
103
|
+
"缺文件说明插件安装不完整:返回 ok=false + 人话原因,建议重装插件,而不是去联网刷新——下载通道已经移除。",
|
|
104
|
+
parameters: {
|
|
105
|
+
type: "object",
|
|
106
|
+
additionalProperties: false,
|
|
107
|
+
properties: {
|
|
108
|
+
action: {
|
|
109
|
+
type: "string",
|
|
110
|
+
enum: ["list", "refresh", "verify", "prune"],
|
|
111
|
+
description: "list(默认,看内置版本/清单/占用)/ refresh(= verify,旧名保留)/ verify(逐文件 sha256 复核)/ prune(只清 DSH_STM32_ASSETS 下历史版本)。",
|
|
112
|
+
},
|
|
113
|
+
profile: {
|
|
114
|
+
type: "string",
|
|
115
|
+
enum: ["core", "full"],
|
|
116
|
+
description: "core(默认:device/ + ioc/ + ld/,建工程够用)/ full(再加 startup/ + headers/ + svd/)。",
|
|
117
|
+
},
|
|
118
|
+
version: {
|
|
119
|
+
type: "string",
|
|
120
|
+
description: "list / verify 指定版本;不填用内置版本(或 DSH_STM32_ASSETS 下最新历史版本)。",
|
|
121
|
+
},
|
|
122
|
+
keep: {
|
|
123
|
+
type: "number",
|
|
124
|
+
minimum: 1,
|
|
125
|
+
description: "prune 保留几个历史版本,默认 2(内置资源不受影响)。",
|
|
126
|
+
},
|
|
127
|
+
},
|
|
128
|
+
required: [],
|
|
129
|
+
},
|
|
130
|
+
timeoutMs: 5 * 60_000,
|
|
131
|
+
isConcurrencySafe: () => false,
|
|
132
|
+
output: {
|
|
133
|
+
schema: outputSchema,
|
|
134
|
+
render: (_args, value) => {
|
|
135
|
+
const typed = value;
|
|
136
|
+
const lines = [typed.message];
|
|
137
|
+
lines.push("资源目录:" + typed.root + "(来源:" + typed.origin + ");profile=" + typed.profile);
|
|
138
|
+
if (typed.source !== "")
|
|
139
|
+
lines.push("资源来源:" + typed.source);
|
|
140
|
+
if (typed.versions.length > 0) {
|
|
141
|
+
const items = typed.versions.map((item) => item.version +
|
|
142
|
+
(item.current ? "(当前)" : "") +
|
|
143
|
+
":" + String(item.files) + " 个文件、" + describeBytes(item.bytes) +
|
|
144
|
+
",profile=" + item.profiles.join("+"));
|
|
145
|
+
lines.push("本地资源:" + items.join(";"));
|
|
146
|
+
}
|
|
147
|
+
if (typed.files.length > 0) {
|
|
148
|
+
const head = typed.files.slice(0, 10);
|
|
149
|
+
for (const file of head) {
|
|
150
|
+
lines.push("· " + file.path + "(" + describeBytes(file.bytes) + ")→ " + file.status + (file.detail === "" ? "" : ":" + file.detail));
|
|
151
|
+
}
|
|
152
|
+
if (typed.files.length > head.length)
|
|
153
|
+
lines.push("… 还有 " + String(typed.files.length - head.length) + " 个文件(action=list 看全量)");
|
|
154
|
+
lines.push("合计 " + String(typed.fileCount) + " 个文件、" + describeBytes(typed.totalBytes));
|
|
155
|
+
}
|
|
156
|
+
if (typed.attempts.length > 0)
|
|
157
|
+
lines.push("尝试记录:" + typed.attempts.join(" | "));
|
|
158
|
+
if (typed.offlineFallback !== "")
|
|
159
|
+
lines.push("提示:" + typed.offlineFallback);
|
|
160
|
+
return [{ type: "text", text: lines.join("\n") }];
|
|
161
|
+
},
|
|
162
|
+
},
|
|
163
|
+
async execute(rawArgs, _exec) {
|
|
164
|
+
const args = rawArgs ?? {};
|
|
165
|
+
const action = (args.action ?? "list").trim().toLowerCase();
|
|
166
|
+
const env = options.env ?? process.env;
|
|
167
|
+
const info = assetsRootInfo(env);
|
|
168
|
+
const profile = normalizeProfile(args.profile);
|
|
169
|
+
const versionsOf = () => listInstalledVersions(env).map(toVersionView);
|
|
170
|
+
const base = () => ({
|
|
171
|
+
action,
|
|
172
|
+
ok: false,
|
|
173
|
+
root: info.root,
|
|
174
|
+
origin: info.origin,
|
|
175
|
+
version: "",
|
|
176
|
+
profile: profile ?? (args.profile ?? "").trim(),
|
|
177
|
+
source: "",
|
|
178
|
+
fileCount: 0,
|
|
179
|
+
totalBytes: 0,
|
|
180
|
+
files: [],
|
|
181
|
+
versions: versionsOf(),
|
|
182
|
+
attempts: [],
|
|
183
|
+
offlineFallback: "",
|
|
184
|
+
message: "",
|
|
185
|
+
});
|
|
186
|
+
if (profile === null) {
|
|
187
|
+
return {
|
|
188
|
+
...base(),
|
|
189
|
+
message: "不认识的 profile:" + String(args.profile) + "(只有 core / full)。什么都没做。",
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
/* ---------------------------- list ---------------------------- */
|
|
193
|
+
if (action === "list") {
|
|
194
|
+
const value = base();
|
|
195
|
+
const state = readLocalManifest(env, args.version);
|
|
196
|
+
if (state.manifest === null) {
|
|
197
|
+
value.offlineFallback = BUILTIN_NOTE;
|
|
198
|
+
value.message = "找不到内置资源(" + info.root + "):" + state.error;
|
|
199
|
+
return value;
|
|
200
|
+
}
|
|
201
|
+
value.ok = true;
|
|
202
|
+
value.version = state.version;
|
|
203
|
+
value.source = state.bundled ? "bundled(插件内置)" : "cache(DSH_STM32_ASSETS)";
|
|
204
|
+
for (const target of profileFiles(state.manifest, profile)) {
|
|
205
|
+
const localPath = path.join(state.versionDir, target.path);
|
|
206
|
+
let present = false;
|
|
207
|
+
try {
|
|
208
|
+
present = fs.statSync(localPath).isFile();
|
|
209
|
+
}
|
|
210
|
+
catch {
|
|
211
|
+
present = false;
|
|
212
|
+
}
|
|
213
|
+
value.files.push({
|
|
214
|
+
path: target.path,
|
|
215
|
+
bytes: target.bytes,
|
|
216
|
+
sha256: target.sha256,
|
|
217
|
+
status: present ? "present" : "missing",
|
|
218
|
+
detail: present ? "在磁盘上(未校验;action=verify 逐文件复核 sha256)" : "manifest 里列了,但本地没有这个文件(重装插件修复)",
|
|
219
|
+
});
|
|
220
|
+
}
|
|
221
|
+
value.fileCount = value.files.length;
|
|
222
|
+
value.totalBytes = value.files.reduce((sum, file) => sum + file.bytes, 0);
|
|
223
|
+
value.message =
|
|
224
|
+
"内置资源 " + state.version + "(profile=" + profile + "):" + String(value.fileCount) + " 个文件、约 " +
|
|
225
|
+
describeBytes(value.totalBytes) + ";目录 " + state.versionDir + "。";
|
|
226
|
+
return value;
|
|
227
|
+
}
|
|
228
|
+
/* ------------------------ refresh / verify ------------------------ */
|
|
229
|
+
if (action === "refresh" || action === "verify") {
|
|
230
|
+
const value = base();
|
|
231
|
+
const result = verifyInstalled({
|
|
232
|
+
profile,
|
|
233
|
+
env,
|
|
234
|
+
...(args.version === undefined ? {} : { version: args.version }),
|
|
235
|
+
});
|
|
236
|
+
value.ok = result.ok;
|
|
237
|
+
value.version = result.version;
|
|
238
|
+
value.source = readLocalManifest(env, args.version).bundled ? "bundled(插件内置)" : "cache(DSH_STM32_ASSETS)";
|
|
239
|
+
value.fileCount = result.fileCount;
|
|
240
|
+
value.totalBytes = result.totalBytes;
|
|
241
|
+
value.files = result.files.map((file) => ({
|
|
242
|
+
path: file.path,
|
|
243
|
+
bytes: file.bytes,
|
|
244
|
+
sha256: file.sha256,
|
|
245
|
+
status: file.status,
|
|
246
|
+
detail: file.detail,
|
|
247
|
+
}));
|
|
248
|
+
value.message =
|
|
249
|
+
(action === "refresh" ? "资源随插件内置,不需要下载;这次做了一次完整性校验。" : "") +
|
|
250
|
+
result.message;
|
|
251
|
+
if (!result.ok)
|
|
252
|
+
value.offlineFallback = BUILTIN_NOTE;
|
|
253
|
+
return value;
|
|
254
|
+
}
|
|
255
|
+
/* ---------------------------- prune ---------------------------- */
|
|
256
|
+
if (action === "prune") {
|
|
257
|
+
const value = base();
|
|
258
|
+
const keep = typeof args.keep === "number" && Number.isFinite(args.keep) ? Math.floor(args.keep) : 2;
|
|
259
|
+
const pruned = pruneOldVersions(env, keep);
|
|
260
|
+
value.ok = true;
|
|
261
|
+
value.versions = versionsOf();
|
|
262
|
+
value.version = pruned.kept[0] ?? (readLocalManifest(env).version);
|
|
263
|
+
value.totalBytes = pruned.reclaimedBytes;
|
|
264
|
+
value.message = pruned.message;
|
|
265
|
+
return value;
|
|
266
|
+
}
|
|
267
|
+
const value = base();
|
|
268
|
+
value.message = "不认识的 action:" + action + "(只有 list / refresh / verify / prune)。什么都没做。";
|
|
269
|
+
return value;
|
|
270
|
+
},
|
|
271
|
+
});
|
|
272
|
+
}
|
package/lib/tools/cache.js
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
* 而不是藏在 error 信息里。
|
|
7
7
|
*/
|
|
8
8
|
import { cacheRootInfo, checkCacheEntry, describeCacheBytes, pruneLegacyEntries, readCacheIndex, removeCacheEntry, resolveCacheEntry, } from "../engine/cache.js";
|
|
9
|
+
import { ensureAssets } from "../engine/assets.js";
|
|
9
10
|
import { ensureCmsisTemplate } from "../engine/register-template.js";
|
|
10
11
|
export const CACHE_TOOL = "stm32_cache";
|
|
11
12
|
const entrySchema = {
|
|
@@ -145,6 +146,13 @@ export function registerCache(ctx) {
|
|
|
145
146
|
if ((args.mcu ?? "") === "" && (args.family ?? "") === "") {
|
|
146
147
|
return empty("fetch 至少给一个 mcu(例如 STM32F103C8T6)或 family(例如 F1)。");
|
|
147
148
|
}
|
|
149
|
+
// cmsis 条目 id 里带着启动文件与设备宏(cmsis:F1:103xb),那要靠设备事实算:
|
|
150
|
+
// 插件不再内置芯片表,所以先把内置资源准备好;拿不到就明说,别让它报"认不出这颗芯片"
|
|
151
|
+
// (那个文案会让人以为型号写错了)。
|
|
152
|
+
const assets = await ensureAssets({ signal: exec.signal });
|
|
153
|
+
if (!assets.ok) {
|
|
154
|
+
return empty("认芯片型号需要设备事实,但内置资源还没就绪:" + assets.message + " 装好后重试 action=fetch。");
|
|
155
|
+
}
|
|
148
156
|
const result = await ensureCmsisTemplate({
|
|
149
157
|
...(args.mcu === undefined ? {} : { mcu: args.mcu }),
|
|
150
158
|
...(args.family === undefined ? {} : { family: args.family }),
|
|
@@ -2,18 +2,30 @@
|
|
|
2
2
|
* L3:长调试会话三件套(规格 §6)。
|
|
3
3
|
*
|
|
4
4
|
* - stm32_debug_session:显式申请会话(租约:空闲 90 s / 总 10 min),常驻的只有 openocd;
|
|
5
|
-
* - stm32_debug_eval:在会话里跑 gdb
|
|
5
|
+
* - stm32_debug_eval:在会话里跑 gdb 命令(P3 起优先用常驻 gdb MI 会话;连不上才退回临时 `gdb -batch`);
|
|
6
6
|
* - stm32_debug_stop:立刻释放探针。
|
|
7
7
|
*
|
|
8
8
|
* 会话在 `turn/end`(agent 输出完、等你回复)时由 index.ts 自动关掉,所以你想在 VS Code 里按 F5 时
|
|
9
9
|
* 探针一定是空闲的。build / flash / generate 动手前也会先让会话让出探针。
|
|
10
10
|
*/
|
|
11
|
+
import { F1_BREAKPOINT_BUDGET, quotaOf } from "../engine/breakpoints.js";
|
|
11
12
|
import { debugSessions } from "../engine/debug-session.js";
|
|
12
13
|
import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
|
|
13
14
|
import { resolveProjectDir } from "./project-dir.js";
|
|
14
15
|
export const DEBUG_SESSION_TOOL = "stm32_debug_session";
|
|
15
16
|
export const DEBUG_EVAL_TOOL = "stm32_debug_eval";
|
|
16
17
|
export const DEBUG_STOP_TOOL = "stm32_debug_stop";
|
|
18
|
+
/** 断点预算三元组(B4):与 stm32_debug_run 的报告同一个形状。 */
|
|
19
|
+
const quotaSchema = {
|
|
20
|
+
type: "object",
|
|
21
|
+
additionalProperties: false,
|
|
22
|
+
properties: {
|
|
23
|
+
used: { type: "number" },
|
|
24
|
+
limit: { type: "number" },
|
|
25
|
+
remaining: { type: "number" },
|
|
26
|
+
},
|
|
27
|
+
required: ["used", "limit", "remaining"],
|
|
28
|
+
};
|
|
17
29
|
export const sessionSchema = {
|
|
18
30
|
type: "object",
|
|
19
31
|
additionalProperties: false,
|
|
@@ -22,18 +34,23 @@ export const sessionSchema = {
|
|
|
22
34
|
active: { type: "boolean" },
|
|
23
35
|
sessionId: { type: "string" },
|
|
24
36
|
port: { type: "number" },
|
|
37
|
+
tclPort: { type: "number" },
|
|
25
38
|
projectDir: { type: "string" },
|
|
39
|
+
configFile: { type: "string" },
|
|
26
40
|
elfPath: { type: "string" },
|
|
27
41
|
startedAt: { type: "number" },
|
|
28
42
|
idleTtlMs: { type: "number" },
|
|
29
43
|
hardTtlMs: { type: "number" },
|
|
30
44
|
remainingMs: { type: "number" },
|
|
45
|
+
// B4:这次会话登记的断点数量与芯片上限(会话不跨 gdb 进程保存断点,但预算先校验)。
|
|
46
|
+
breakpoints: quotaSchema,
|
|
47
|
+
watchpoints: quotaSchema,
|
|
31
48
|
errors: { type: "array", items: { type: "string" } },
|
|
32
49
|
message: { type: "string" },
|
|
33
50
|
},
|
|
34
51
|
required: [
|
|
35
|
-
"ok", "active", "sessionId", "port", "projectDir", "elfPath", "startedAt",
|
|
36
|
-
"idleTtlMs", "hardTtlMs", "remainingMs", "errors", "message",
|
|
52
|
+
"ok", "active", "sessionId", "port", "tclPort", "projectDir", "configFile", "elfPath", "startedAt",
|
|
53
|
+
"idleTtlMs", "hardTtlMs", "remainingMs", "breakpoints", "watchpoints", "errors", "message",
|
|
37
54
|
],
|
|
38
55
|
};
|
|
39
56
|
export const outputSchema = {
|
|
@@ -83,7 +100,10 @@ const ENV_CHECK_SCHEMA = {
|
|
|
83
100
|
function describeSession(report) {
|
|
84
101
|
const lines = [report.message];
|
|
85
102
|
if (report.active) {
|
|
86
|
-
|
|
103
|
+
const tclNote = report.tclPort > 0
|
|
104
|
+
? "(Tcl " + String(report.tclPort) + ",regs_read 走快路径)"
|
|
105
|
+
: "(没有 Tcl 口,regs_read 走 gdb)";
|
|
106
|
+
lines.push("会话 " + report.sessionId + ":端口 " + String(report.port) + tclNote + ",剩余租约 " + String(Math.ceil(report.remainingMs / 1000)) + " s(空闲 " + String(Math.round(report.idleTtlMs / 1000)) + " s / 总上限 " + String(Math.round(report.hardTtlMs / 1000)) + " s)");
|
|
87
107
|
if (report.elfPath !== "")
|
|
88
108
|
lines.push("符号:" + report.elfPath);
|
|
89
109
|
lines.push("→ 用 stm32_debug_eval 执行 gdb 命令;用完 stm32_debug_stop 立刻还探针(turn 结束也会自动关)");
|
|
@@ -99,11 +119,17 @@ function describeSession(report) {
|
|
|
99
119
|
*/
|
|
100
120
|
function blockedSession(projectDir, gate) {
|
|
101
121
|
return {
|
|
102
|
-
ok: false, active: false, sessionId: "", port: 0, projectDir, elfPath: "",
|
|
122
|
+
ok: false, active: false, sessionId: "", port: 0, tclPort: 0, projectDir, configFile: "", elfPath: "",
|
|
103
123
|
startedAt: 0, idleTtlMs: 0, hardTtlMs: 0, remainingMs: 0,
|
|
124
|
+
breakpoints: quotaOf(0, F1_BREAKPOINT_BUDGET.code),
|
|
125
|
+
watchpoints: quotaOf(0, F1_BREAKPOINT_BUDGET.data),
|
|
104
126
|
errors: gateReportNotes(gate).slice(1), message: gate.message,
|
|
105
127
|
};
|
|
106
128
|
}
|
|
129
|
+
/** eval 没跑起来(多半是起会话失败)时的干净报告:字段一个不少,宿主 schema 才吃。 */
|
|
130
|
+
function failEvalReport(message, errors) {
|
|
131
|
+
return { ok: false, output: "", command: "", durationMs: 0, remainingMs: debugSessions.status().remainingMs, errors, message };
|
|
132
|
+
}
|
|
107
133
|
export function registerDebugSession(ctx) {
|
|
108
134
|
ctx.tools.register({
|
|
109
135
|
name: DEBUG_SESSION_TOOL,
|
|
@@ -120,6 +146,7 @@ export function registerDebugSession(ctx) {
|
|
|
120
146
|
idleTtlMs: { type: "number", description: "空闲超时毫秒数,默认 90000。" },
|
|
121
147
|
hardTtlMs: { type: "number", description: "总时长上限毫秒数,默认 600000。" },
|
|
122
148
|
reset: { type: "string", enum: ["none", "halt", "run"], description: "起会话时对目标做什么,默认 none(不动芯片)。" },
|
|
149
|
+
breakpoints: { type: "array", items: { type: "string" }, description: "这次会话打算用的断点(\"main\"、\"watch:g_count\"):起会话之前先按芯片预算校验,F1 上限 6 个硬件断点 / 4 个观察点,超了不占探针直接失败。" },
|
|
123
150
|
binDirs: { type: "array", items: { type: "string" }, description: "工具链目录候选。" },
|
|
124
151
|
envCheck: ENV_CHECK_SCHEMA,
|
|
125
152
|
},
|
|
@@ -158,6 +185,7 @@ export function registerDebugSession(ctx) {
|
|
|
158
185
|
...(args.idleTtlMs === undefined ? {} : { idleTtlMs: args.idleTtlMs }),
|
|
159
186
|
...(args.hardTtlMs === undefined ? {} : { hardTtlMs: args.hardTtlMs }),
|
|
160
187
|
...(args.reset === undefined ? {} : { reset: args.reset }),
|
|
188
|
+
...(args.breakpoints === undefined ? {} : { breakpoints: args.breakpoints }),
|
|
161
189
|
...(args.binDirs === undefined ? {} : { binDirs: args.binDirs }),
|
|
162
190
|
// A9:记下是谁开的会话,turn/end 只关自己的那个。
|
|
163
191
|
...(exec.agent?.id === undefined ? {} : { owner: exec.agent.id }),
|
|
@@ -172,7 +200,7 @@ export function registerDebugSession(ctx) {
|
|
|
172
200
|
});
|
|
173
201
|
ctx.tools.register({
|
|
174
202
|
name: DEBUG_EVAL_TOOL,
|
|
175
|
-
description: "
|
|
203
|
+
description: "在调试会话里执行 gdb 命令(例如 \"print g_led_blink_count\"、\"info registers pc\"、\"bt\"、\"x/4xb 0x20000000\")。B3 起没有会话时会先起一个(空闲 90 s 自动关、turn 结束也关)并复用它的 gdb server,不重复起 openocd。P3 起首次 eval 会挂一个常驻的 gdb MI 进程(--interpreter=mi2):断点/变量/栈跨调用保留,单条命令约 20–70 ms;MI 连不上(比如 VS Code 正连着)才退回每次 gdb -batch 的老路径(约 1.5 s)。continue/next/step/si/ni 走 MI 的 -exec-*(si/ni 是单指令步进),会等 *stopped 报「停在哪」(3 s 窗口);目标在跑时下条命令先 -exec-interrupt 停下,不写 keepHalted 的命令结束会 monitor resume。",
|
|
176
204
|
parameters: {
|
|
177
205
|
type: "object",
|
|
178
206
|
additionalProperties: false,
|
|
@@ -198,6 +226,13 @@ export function registerDebugSession(ctx) {
|
|
|
198
226
|
async execute(rawArgs, exec) {
|
|
199
227
|
// 同 A31:无参数调用兜成 {}。没带 commands/expression 时引擎会给出"没执行"的报告,不是崩溃。
|
|
200
228
|
const args = rawArgs ?? {};
|
|
229
|
+
// B3:eval 只复用会话里那个 gdb server,不另起 openocd(会话是唯一握着探针的进程)。
|
|
230
|
+
// 没有会话时不偷偷起一个:探针是共享资源,起会话要显式(stm32_debug_session 或 stm32_regs_read)。
|
|
231
|
+
const active = debugSessions.status();
|
|
232
|
+
if (!active.active) {
|
|
233
|
+
const message = "没有会话:先 stm32_debug_session 开一个(或用 stm32_debug_run 一次性跑)";
|
|
234
|
+
return { message, report: failEvalReport(message, ["没有调试会话(eval 只复用会话里的 gdb server,不自己起 openocd)"]) };
|
|
235
|
+
}
|
|
201
236
|
const report = await debugSessions.eval({
|
|
202
237
|
...(args.commands === undefined ? {} : { commands: args.commands }),
|
|
203
238
|
...(args.expression === undefined ? {} : { expression: args.expression }),
|