前言¶
在 DSH 里做 STM32 开发，常见做法是：智能体靠 shell 或手写 HTTP 去调 Keil、OpenOCD、串口工具，界面和 agent 各走一条路，状态容易对不上。dsh-plugin-stm32-workbench 把「单片机工作台」做成 DSH 插件：选工作区、进入「单片机模式」会话后，工作台挂在会话视图里，编译、烧录、引脚与串口与 mcu 工具共用同一套后端 API。下面介绍它是什么、能做什么、如何安装与使用。
这是什么¶
dsh-plugin-stm32-workbench（仓库 Airls-bubble/dsh-plugin-stm32-workbench）由维护者 Airls-bubble 发布，在 SkillHub 目录中归类为工作流。当前插件版本 0.4.0，README 写明适配 DSH 0.2.1-rc.2（2026-10-19/20）。
定位一句话：DSH 内建的 STM32 工作台——Keil AC5 编译、ST-Link/OpenOCD 烧录、引脚规划、串口与功能契约，面向在 Harness 里写固件、又要让 agent 直接调用同一套能力的场景。
在 DSH 里怎么挂载¶
第一版把面板注册进 conversation.input.dock，会导致每个对话下面都出现工作台；当前实现参考 dsh-openwrite 的模式：
- 侧栏底部入口「STM32 工作台」（插槽 id
stm32.launch）。 - 点击后选工程目录 → 建工作区与会话，并通过
agentPresets选中预设 idmcu（「单片机模式」由插件ctx.agentPresets.register()注册，不依赖手写 profile 补丁）。 - 工作台注册为
conversation.view，由watchScope门控：仅当主视图会话的projectionValues.agentPreset为mcu时才挂载。
半边职责划分如下：
| 半边 | 文件 | 职责 |
|---|---|---|
| 宿主 | index.js |
注册「单片机模式」预设；拉起/停止 MCU 后端；注册 /mcu/state、/mcu/start、/mcu/stop 及 /mcu/api/* 代理 |
| 客户端 | client.js |
侧栏入口、选工作区对话框；门控下的工作台（引脚图、构建台、串口、计算器等） |
| 后端 | backend/ |
Keil AC5 编译、OpenOCD + ST-Link 烧录、串口桥；自带测试固件与 BSP；便携 OpenOCD 由脚本按需下载 |
会话一旦处于单片机模式，agent 可通过宿主注册的 mcu 工具（README 记载 18 个 action）直接编译、烧录与读串口，与界面共用 /mcu 下的路由。
核心功能¶
构建与烧录¶
- 后端使用 Keil AC5 工具链（
armcc→armasm→armlink→fromelf），并支持打开用户自己的.uvprojx工程；README 记载产物可与 Keil UV4 逐字节一致（含真实毕设工程验证示例）。 - 烧录路径为 OpenOCD + ST-Link；便携 OpenOCD 不随仓库分发，需本地准备。
- 仓库自带
firmware/projects等测试工程，也可只编插件包内工程做冒烟。
Keil 工程接入（HTTP API）¶
用户工程接入后，后端提供例如（路径经 /mcu 代理到后端 /api）：
POST /api/keil/open— 打开工程并在进程内保持状态GET /api/keil/state— 当前工程摘要GET /api/keil/pins— 静态解析引脚配置POST /api/keil/registers— 寄存器与「源码分析 vs 芯片实际」对照POST /api/keil/build— 按工程编译，NDJSON 流式日志
配套模块包括 uvprojx.js（解析工程）、keil-build.js（驱动工具链）、pinmap.js（引脚静态分析）、regread.js（SWD 读寄存器）等。
智能体工具 mcu¶
宿主在 index.js 注册一个工具、多个 action，README 列出的能力包括：status、open、scan、files、read、write、build、flash、size、pins、regs、chip、reset、spec、symbols、readmem、gfx、watch 等。0.3.0 起增加 symbols / readmem / gfx；0.4.0 增加 watch 并面向「AI 省 token」收紧输出形态（如 status 一次拿全貌、gfx 基线差异等）。
界面与 agent 统一走同一套 API，避免「面板数字与脚本结果不一致」的双轨问题。
工作台 UI¶
客户端提供引脚图、构建台、串口等面板；设计约束包括：禁止 iframe、须用 DSH 主题令牌、禁止 import Harness 客户端 primitives 包，资源注册需用 effect 管理生命周期（详见仓库 README）。
安装与启用¶
插件本体约 1.8 MB 代码（不含便携 OpenOCD）。从 GitHub 取得源码后，先准备 OpenOCD（仓库不提交约 7.6 MB 的第三方二进制）：
powershell -ExecutionPolicy Bypass -File backend\scripts\fetch-openocd.ps1
脚本从官方 xPack release 下载并校验 sha256，一般只需执行一次。
安装到 DSH 使用插件管理器命令（路径换成你本机放置插件的绝对路径）：
plugin_manager: install_bundle target=<你放本插件的绝对路径>
README 强调：改动插件代码后必须重启 DSH；装载器不会热替换已装载包代代，客户端资源也可能需要刷新页面。
生效后预期现象：
- 侧栏底部出现「STM32 工作台」；
- 模式选择器中出现「单片机模式」（由插件注册）。
环境要求：package.json 中 engines.node 为 >=22。换机安装、前置条件与数据目录说明见仓库 PORTING.md。
禁用/回滚：
plugin_manager: set_bundle enabled=false target=dsh-plugin-stm32-workbench
典型用法¶
从入口进入单片机会话¶
- 点击侧栏底部「STM32 工作台」。
- 选择 Keil 工程所在目录（或插件自带测试工程目录）作为工作区。
- 进入新会话后确认 agent 预设为「单片机模式」（
mcu）。 - 在会话视图中的工作台进行构建、烧录、串口观测；或在对话中让 agent 调用
mcu工具的build、flash、status等 action。
验证 Keil 构建一致性（仓库给出的可复现思路）¶
README 建议用 Keil UV4 在临时副本上做参照构建，再与插件产出比对 hex：仅 Keil 有 / 仅插件有 / 公共地址字节差异均为 0 即表示内容一致。差异定位可借助仓库内 scripts/keil-param-experiment.js、scripts/keil-symdiff.js。
数据落在哪里¶
运行期数据不写入插件安装目录（设计目标：拷走插件目录应为干净副本）：
- 工程相关：
<Keil 工程目录>/.dsh-mcu/（构建缓存、日志、备份等；工程只读时会退到~/.dsh/mcu/projects/<路径哈希>/）。 - 跨工程记忆：
~/.dsh/mcu/recent.json（默认DSH_HOME为~/.dsh）。
适用场景与注意¶
适合谁：已在用 DSH 做嵌入式或课程/毕设类 STM32（README 以 STM32F103 生态为主）开发，希望工作台、串口与 agent 工具链合一，且愿意在本机安装 Keil AC5、ST-Link 与按需下载的 OpenOCD。
权限与安全：插件以当前 DSH 进程权限运行后端（编译、写工程旁路目录、访问调试器）。安装前应阅读仓库源码、MIT 许可证 与 THIRD_PARTY_NOTICES.md（含 CMSIS、ST 标准外设库、GPLv2 的 xPack OpenOCD 等）。
实测限制（README「待验证」如实记录）：无 ST-Link 时界面会显示未检测到设备；烧录与串口需实物验证。若侧栏无入口或工作台未挂载，可查浏览器控制台是否有 conversation.view 插槽崩溃或 [stm32-workbench] 警告。
生态说明：DSH 社区插件目录在 SkillHub，与 DeepSeek / 幻方无官方从属关系；本文事实以仓库 README 与 package.json 为准。
结尾¶
dsh-plugin-stm32-workbench 把 STM32 的编译、烧录、引脚与串口收进 DSH 会话与 mcu 工具，减少「界面一套、agent 另一套」的割裂。目录页：SkillHub - dsh-plugin-stm32-workbench；源码与完整说明：GitHub - Airls-bubble/dsh-plugin-stm32-workbench。
