# dm02_developments_skills **Repository Path**: lrein/dm02_developments_skills ## Basic Information - **Project Name**: dm02_developments_skills - **Description**: 用于开发dm-mc02开发板的板级skills,包含设备层驱动自动开发与检验,任务层编写的功能。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-08-31 - **Last Updated**: 2026-09-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DM02 Development Skills 面向 DM-MC02 / RoboWalker 同源 STM32 固件工程的 Codex Skill 套件。它把设备与电机驱动开发、任务层状态机、双通道上板验证,以及常用的构建、烧录、调试和分析工具整理成可复用工作流。 > 本仓库保存的是 Skill 源码和离线安装器。克隆仓库不会自动安装 Skill,也不会安装编译器、OpenOCD、探针驱动或 Python 依赖。 ## 能完成什么 ### 三个 DM02 核心 Skill | Skill | 负责的工作 | 不负责的工作 | | --- | --- | --- | | `$dm02-device-development` | 根据说明书和厂商例程开发 UART、RS485、CAN 普通设备或电机驱动;生成独立协议规格、主机测试和默认关闭的板上检验任务 | 普通业务任务、整机验收、无依据猜测协议 | | `$dm02-task-development` | 使用现有传感器和执行器实现非阻塞任务、控制逻辑与状态机;为纯算法建立主机测试和板级场景表 | 新增设备协议、伪造完整硬件仿真、设备驱动双通道验证 | | `$dm02-verification` | 运行主机测试,构建新鲜 ARM 固件,通过 OpenOCD 烧录,同步采集原始总线和 USB-C NDJSON,并独立判定设备驱动 | 普通任务验收、SPI/I2C 验证、无硬件证据的“模拟通过” | ### 配套工具 Skill | Skill | 用途 | | --- | --- | | `$build-cmake` | 配置和构建 CMake 嵌入式工程,定位 ELF/HEX/BIN/map | | `$flash-openocd` | 使用 OpenOCD 安全烧录明确的固件产物 | | `$debug-gdb-openocd` | 启动 OpenOCD/GDB 在线调试或检查崩溃现场 | | `$static-analysis` | 运行 cppcheck、clang-tidy、GCC analyzer 和辅助 MISRA 检查 | | `$memory-analysis` | 分析 ELF/map 的 Flash、RAM 和符号占用 | | `$serial-monitor` | 识别串口、采集日志并分析运行状态 | | `$can-debug` | 监听、发送 CAN 帧并扫描节点 | | `$logic-analyzer` | 使用 Saleae Logic 2 采集并解码 I2C、SPI、UART、CAN | | `$em` | 管理跨会话工程状态、计划、HVR、验证结果、归档和迁移,并编排上述工具 | ## 仓库结构 ```text dm02_skills/ ├─ README.md 中文主文档 ├─ README.en.md 英文简要入口 ├─ .gitignore 缓存与本地构建产物忽略规则 └─ skills/ ├─ README.md 套件安装和技术细节 ├─ UPSTREAMS.md 上游来源、固定提交和筛选说明 ├─ skill-pack.json 唯一安装清单和上游内容哈希 ├─ manage_skills.py 离线查看、检查和安装入口 ├─ dm02-device-development/ 设备/电机开发 Skill ├─ dm02-task-development/ 任务逻辑开发 Skill ├─ dm02-verification/ 双通道硬件验证 Skill ├─ upstream/ 固定版本的精选上游 Skill 快照 └─ tests/ 套件回归测试 ``` `skills/upstream/` 是按明确提交固定的普通文件快照,不是 Git 子模块。不要把其中目录当作临时文件清理,也不要在未更新 `skill-pack.json`、来源说明和哈希的情况下随意替换。 ## 环境要求 - Python 3.10 或更高版本。 - DM02 自研 Skill 目标工程应为 STM32H7 + ARM GCC + CMake/Ninja 的 DM02/RoboWalker 同源结构。 - 完整闭环验证使用 CMake 3.28+、Ninja、ARM GNU Toolchain、OpenOCD,以及 ST-Link 或 CMSIS-DAP/DAPLink。 - UART/RS485 采集通常需要 `pyserial` 和对应 USB 适配器驱动。 - CAN 采集通常需要 `python-can`、对应 CAN 后端及适配器驱动。 - 逻辑分析仪工作流需要 Saleae Logic 2 和可用的自动化服务。 安装器只复制 Skill 文件,不安装上述工具、Python 包或硬件驱动。 ## 查看与安装 在仓库根目录执行。安装器无参数时只显示帮助,不写文件: ```powershell python skills/manage_skills.py python skills/manage_skills.py list python skills/manage_skills.py status --scope user ``` Windows 没有 `python` 命令时,可以使用已安装的 Python Launcher: ```powershell py -3.10 skills/manage_skills.py list ``` ### 安装到当前用户 先预览,再安装到用户级 Codex Skill 目录: ```powershell python skills/manage_skills.py install --scope user --dry-run python skills/manage_skills.py install --scope user ``` ### 安装到指定项目 把 Skill 安装到派生工程的 `.agents/skills`: ```powershell python skills/manage_skills.py install --scope project --project D:\firmware\next_project --dry-run python skills/manage_skills.py install --scope project --project D:\firmware\next_project ``` 目标中已有同名 Skill 时,安装器会停止而不是覆盖。确认要用本仓库版本替换时才增加 `--force`。安装或更新后,在新的 Codex 回合中调用 Skill。 ## 已固化到 Skill 的工作流程 以下规则已经写入 Skill,不需要在每次请求中重复提醒。 ### 1. 工程识别和参考优先级 - 开始前读取当前工程的 `.ioc`、CMake、任务入口、Middleware、Device/Motor 和定时器回调。 - 工程匹配分为 `full`、`partial`、`no_match`;不匹配时不会强行套用 DM02 目录和接口。 - 不照抄参考基线中的句柄、IRQ、DMA、定时器或设备实例。 - 电机优先参考当前工程的 `Motor_DJI`、`Motor_DM`,只统一生命周期和物理语义,不复制协议常量。 ### 2. 设备与电机开发 - 从说明书和厂商例程建立可追溯的协议事实表,记录文件哈希、页码、章节或代码位置。 - 驱动、独立主机测试和板上验证资产作为一组交付。 - 主机测试编译真实驱动;黄金帧来自手册或例程,不能由被测驱动生成。 - UART/RS485 自动考虑拆包、粘包、回显、噪声和重新同步;CAN 自动检查 ID 类型、DLC 和反馈路由。 - 电机默认零输出或失能,包含限幅、掉线、超时、停止和故障恢复。 - `DM02_DEVICE_VALIDATION_ENABLE` 默认保持为 `0`。 ### 3. 非阻塞任务开发 - 把目标转换为输入、状态、动作、退出条件、超时、故障和可观察证据。 - ISR 只搬运数据、计数和置标志;通信、状态迁移、日志和复杂计算放在前台。 - 多阶段任务拆成独立 `tsk_*.cpp/.h`,纯算法拆成可主机编译的函数。 - 自动生成板级场景表,覆盖正常完成、启动失败、传感器掉线、电机掉线、超时、用户中止和重新启动。 - 没有板级证据时不会声称物理任务已经完成。 ### 4. 双通道上板验证 - 第一通道采集线路上的真实 UART、RS485 或 CAN 帧。 - 第二通道通过 USB-C NDJSON 报告高层调用意图、MCU 原始 RX、解码值、在线状态和错误码。 - 每轮都在新的临时目录构建 ELF,不使用历史 build 产物。 - 烧录命令固定为 `program verify reset exit`。 - 自动拒绝 mass erase、unlock、Option Bytes、保护位、校准区和任意附加 Flash 命令。 - UART 允许把 RX 证据标记为 `internal_relay`;CAN/RS485 必须提供双向物理总线证据。 - 验证结束自动关闭检验入口、重新构建并烧录安全固件。 ### 5. 四类驱动故障自动返修 分析器会输出 `driver_fault_categories` 和 `automatic_repair_allowed`。标准驱动故障为: - `driver_encoding`:线上 TX 与独立预期帧不符。 - `driver_decoding`:原始 RX 正确,但 decoded 字段缺失、畸形或无法形成一致事件。 - `unit_conversion`:数值超出容差或物理单位错误。 - `driver_state`:在线状态或设备错误码错误。 只有失败完全属于这些驱动问题,且不存在硬件、接线、日志结构、独立时序、USB/总线冲突、故障事件或安全清理失败时,才允许自动返修: ```text $dm02-verification 判定驱动故障 ↓ 重新应用 $dm02-device-development 的协议事实和测试约束 ↓ 最小修改驱动并补充主机回归测试 ↓ 返回同一验证 session,生成新的 ELF ↓ 自动烧录、双通道采集和重新判定 ``` 一次会话最多三个验证迭代,即初次验证加最多两次自动返修,不执行第 4 轮。第一次真实烧录授权可以在目标、探针、接口、画像、接线、cfg 哈希和 Flash 范围均未变化时覆盖后续返修轮次;这些轮次不会重复询问烧录批准。 硬件、供电、接线、终端电阻、设备 ID、波特率、端口或探针故障不会触发盲目改代码。 ## 仍需要你提供或确认的内容 Skill 可以检查和追问,但不能替你决定以下事实。 | 阶段 | 需要人工提供或确认 | | --- | --- | | 选择工程 | 明确目标工程目录;如果同时存在多个派生工程,需要指出要修改哪一个 | | 开发设备 | 器件准确型号、说明书、厂商例程、协议版本、需要公开的能力 | | 处理冲突 | 手册与例程冲突、单位不明确、设备能力缺失时,需要你选择真实目标行为 | | 开发任务 | 描述物理目标、启动条件、完成条件、执行器限制、故障后的安全状态 | | 准备硬件 | 确认供电、电平、共地、终端电阻、设备 ID/波特率、机械限位和急停手段 | | 选择双通道 | 首次确认哪个端口是 USB-C 报告口、哪个是 UART/RS485 监听口,或选择 CAN 后端和通道 | | 选择探针 | OpenOCD cfg 有多个候选时,确认目标 MCU、探针和正确 cfg | | 首次烧录 | 在展示目标、探针、固件、端口、接线、cfg 哈希和 Flash 范围后,明确授权第一次真实烧录 | | 允许运动 | 电机运动需要单独确认低限幅、空载/架空条件和急停方式 | | 危险操作 | 校准、回零、改 ID、改波特率和一般危险命令需要单独确认 | | 非易失写入 | 写设备 ROM/Flash 必须单独确认;普通烧录授权不包含这项权限 | | 整机验收 | 普通任务的完整物理效果、机械负载和最终验收仍需人工观察或仪器证据 | ### 建议主动写进首次请求的信息 为了减少来回确认,建议首次请求直接给出: ```text 目标工程:D:\firmware\my_dm02_project 器件/任务:具体型号或物理任务 资料:说明书路径、厂商例程路径、协议版本 总线:UART / RS485 / CAN,设备 ID 和波特率 目标能力:需要的位置、速度、力矩、状态或数据字段 安全限制:最大速度/力矩/持续时间,是否允许运动和非易失写入 硬件状态:是否已经接线、供电,使用的探针和总线适配器 ``` 你不需要重复提醒“不要使用旧 ELF”“黄金帧不能由驱动生成”“最多三轮”“结束恢复安全固件”或“禁止 mass erase”;这些已经固化在 Skill 中。 ## 常用调用示例 ### 开发 CAN 电机驱动 ```text $dm02-device-development 在 D:\firmware\my_project 中根据 manual.pdf 和 vendor_example/ 开发 Motor_X CAN 驱动。 需要位置、速度和在线状态;暂不允许运动、校准或写设备 Flash。 完成真实驱动、主机协议测试、hardware_validation.json 和默认关闭的板上检验任务。 ``` ### 开发非阻塞任务 ```text $dm02-task-development 使用当前工程已有 IMU 和两台电机实现非阻塞循迹任务。 传感器掉线或状态超时后立即停止电机,并给出板级场景表。 ``` ### 只检查验证环境,不烧录 ```text $dm02-verification 检查 Motor_X 的规格、画像、USB-C、CAN 适配器、ARM 工具链和 OpenOCD;只运行 doctor 和 dry-run,不烧录。 ``` ### 开始真实双通道验证 ```text $dm02-verification 目标板、探针、CAN 适配器和接线已经确认。显示本次目标、cfg 哈希、端口和新鲜 ELF,取得首次烧录授权后运行双通道验证。 若只出现允许自动返修的四类驱动故障,在同一会话内自动修正并复测,最多三个验证迭代。 ``` ### 管理跨会话进度 ```text $em 恢复当前工程状态并显示未完成的验证步骤。 $em 记录本轮 Motor_X 双通道验证结果和原始日志路径。 ``` 安装全部 Skill 不意味着每次请求都会运行全部工具。需要单独的静态分析、内存报告、GDB 调试、串口监控、CAN 扫描或逻辑分析仪采集时,最好在请求中明确点名对应 Skill;`$em` 也可以根据工程计划进行编排。 ## 派生工程中的产物 设备开发通常生成: ```text User_File/2_Device// Tests/2_Device// Tests/2_Device//hardware_validation.json User_File/4_Task/Device_Validation// ``` 任务开发的纯算法测试通常生成: ```text Tests/4_Task// ``` 验证日志默认写入系统临时目录,不写进固件工程。验证结果会记录主机测试、构建、烧录、TX/RX/decoded/cleanup 判定、失败分类和原始日志路径。 ## 支持边界 - DM02 双通道验证当前只支持 UART、RS485、CAN,不支持 SPI/I2C。 - `dm02-verification` 验证设备驱动协议闭环,不代替普通任务或整机验收。 - 精选上游工具仅包含安装清单列出的能力;未列入的构建、调试或通信工具不会自动可用。 - 缺少工具、端口、探针、适配器或真实设备时,流程应返回 `blocked`,不会用模拟结果冒充硬件证据。 精确安装清单见 [skills/skill-pack.json](skills/skill-pack.json);具体包含/排除能力以上游说明为准。 ## 回归测试 测试不会连接探针或烧录硬件,生成物保存在系统临时目录: ```powershell python -m unittest skills/tests/test_skill_pack.py -v ``` 测试覆盖工程识别、安装源清单、Markdown 引用、测试脚手架、硬件规格与画像、四类驱动故障、双通道日志分析、OpenOCD 安全检查,以及可用环境下的 CMake/Ninja/CTest 构建。环境要求和可选夹具见 [skills/tests/README.md](skills/tests/README.md)。 ## 上游来源与维护 上游固定提交、筛选结果、排除能力、许可证现状和更新步骤只在 [skills/UPSTREAMS.md](skills/UPSTREAMS.md) 维护;`skills/upstream/` 的目录约束见 [skills/upstream/README.md](skills/upstream/README.md)。