DSH 嵌入式开发工作台
面向 STM32 / Keil MDK 的 DSH 固件工作台。它帮助你在同一个 agent 会话里评审固件、查询芯片资源、定位 map 问题，并调用带防呆保护的 MDK 构建或烧录。
它不替代参考手册，也不替你猜硬件配置；项目代码、.ioc、链接脚本、实测结果和厂商资料始终优先。
适合的任务
| 你正在做的事 | 工作台提供什么 |
|---|---|
| 评审 SPI/ADC/UART + DMA | 检查 DMA 缓冲所有权、ISR 边界、Cache 一致性与 RTOS 优先级。 |
| 接手陌生 STM32 | 用 stm32cli 查询芯片、外设、DMA、引脚、时钟与中断。 |
| 定位 HardFault / 内存异常 | 用 map-parser 从 Keil .map 定位 PC、符号、内存区域和 MPU 对齐问题。 |
| 给固件补验证 | 规划主机单测、测试接缝、数据回放回归、容差与 HIL。 |
| 设计 UART / RS-485 / CAN 协议 | 约束帧格式、状态门控、超时重试与兼容性。 |
| 构建或烧录 MDK 工程 | 用 /build 统一执行编译和受防呆保护的烧录。 |
它不做什么
- 不取代项目代码、
.ioc、链接脚本、实测结果或厂商资料；它们优先级更高。 - 不做 PCB、器件选型、电气参数或 EMC 设计。
- 不默认修改 HAL、RTOS、LwIP 等中间件内部；优先使用配置、回调、hook、weak override 与项目自有适配层。
- 不在多个工程或镜像之间猜测烧录目标；需要显式选择。
5 分钟上手
安装
双击 install.bat，或在终端运行：
git clone <本仓库>
cd <仓库目录>
.\install.ps1 # 安装/更新到 $DSH_HOME\.agent-presets\embedded\
.\install.ps1 -Symlink # 开发模式：改仓库即生效脚本会探测 UV4.exe，并从会话工作区向下搜索唯一的 .uvprojx。自动探测不满足时，编辑 scripts\mdk\mdk.config.ps1；多工程与后端配置见 MDK 编译/烧录 SOP。
启用与第一条指令
在 DSH 新建会话，选择「嵌入式开发工作台」preset。随后直接描述工程问题，例如：
- “评审这段 SPI + DMA 接收代码的缓存一致性。”
- “STM32H723 的 SPI1 RX 可以用哪个 DMA？”
- “HardFault 的 PC 是
0x0800b455，帮我从 map 定位。”
/build # 编译（默认增量；多工程仓库可带工程昵称）
/build -r # 全量重编译
/build sensor # 编译昵称为 sensor 的工程
/flash # 烧录
/flash main # 烧录指定工程工作方式与安全护栏
工作台遵循“最简单的充分方案”：能用裸机就不上 RTOS，IRQ 足够就不上 DMA，单缓冲足够就不上环形队列；升级复杂度必须有项目证据或明确需求。
但 ISR/RTOS 优先级合规、DMA 缓冲所有权、M7/H7 Cache 一致性与 DMA 可访问内存、长度/索引边界检查，以及超时、溢出、DMA 错误的可观测性不是可选优化。完整规则见 通用准则。
组件关系、能力如何集成、边界与扩展方式见 架构说明。
环境与支持范围
| 组件 | 必需性 | 用途 |
|---|---|---|
| DSH | 必需 | preset 宿主。 |
| Python 3.8+ | 工具调用 | stm32cli 与 map-parser。 |
| STM32CubeMX 数据库 | 可选 | 仅 stm32cli 使用；通过 --db-path 或 STM32CUBEMX_DB_PATH 指定。 |
| Keil MDK / UV4 | 可选 | 仅构建与烧录使用。 |
| ST-Link / pyOCD / J-Link | 按后端需要 | 相应烧录后端。 |
当前重点支持 Windows、DSH、Cortex-M / STM32 与 Keil MDK。其他 IDE、芯片族和 DSH 版本不应被视为已验证支持。
文档导航
| 想了解什么 | 阅读位置 |
|---|---|
| 安装后的 preset、技能放置、更新与卸载 | 日常使用手册 |
| 工程、镜像与四种烧录后端 | MDK 编译/烧录 SOP |
| 四层架构、边界与扩展点 | 架构说明 |
| host / isolate realm 与 preset 维护 | DSH 集成说明 |
| 每项技能的完整契约 | 各技能目录的 SKILL.md 与 references/ |
| English README | README.en.md |
仓库结构
firmware-forge/
├── arm-cortex-expert/ # 固件设计/评审技能 + stm32cli、map-parser
├── embedded-test-engineer/ # 验证策略技能
├── embedded-protocol-designer/ # 通信协议设计技能
├── preset/ # DSH 元数据与 agent 组合
├── plugins/mdk/ # /build 插件
├── scripts/mdk/ # MDK 与烧录后端脚本
├── docs/ # 使用者与维护者文档
├── install.bat / install.ps1 # Windows 安装入口
└── LICENSE # MIT许可
本项目以 MIT License 开源发布。