给 AI 配上锤子和螺丝刀：嵌入式 AI 辅助开发的 Harness Engineering 实践
让 AI 写代码并不难，难的是让 AI 自己验证代码。这篇文章以 STM32F103C8T6 + WS2812 项目为载体，记录了如何通过搭建 Harness（工具+资料+权限），让 AI 从"代码生成器"变成"自主开发者"。
关联文章：
- STM32命令行工具链手册-编译烧录调试自动化指南
- WS2812驱动开发与调试经验总结
一、理念转变：从"AI 帮我写代码"到"给 AI 配工具"
1.1 两种开发模式对比
传统模式：AI 作为代码生成器
用户描述需求 → AI 生成代码 → 人工复制 → 手动编译 → 发现错误 → 再次询问 AI → ...问题：
- AI 无法验证代码是否正确
- 编译错误需要人工反馈
- 调试信息 AI 看不到
- 每次沟通都从零开始
Harness 模式：AI 作为自主开发者
搭建环境 → 提供 Harness（工具+资料+权限）→ AI 自主完成：编码 → 编译 → 调试 → 修复 → 验证优势：
- AI 可以自主验证代码
- 编译错误 AI 自己读取并修复
- 调试信息 AI 可以自主获取
- 形成闭环，快速迭代
1.2 本项目的选择
本项目采用了Harness 模式。整个开发过程的核心不是"让 AI 写代码"，而是先搭建一套让 AI 能自主工作的环境。
二、Harness Engineering 实践
2.1 什么是 Harness
Harness（工具套件）是 AI 自主工作的基础设施，包含三个要素：
| 要素 | 内容 | 作用 |
|---|---|---|
| 工具 | 编译器、烧录器、调试器、串口监视器 | AI 可以执行操作、获取反馈 |
| 资料 | 数据手册、参考工程、协议文档 | AI 基于权威信息工作，而非凭空猜测 |
| 权限 | 文件读写、命令执行、网络访问 | AI 可以自主操作，无需人工介入 |
2.2 实践一：编译烧录工具链
为什么先做这个：让 AI 能自主验证代码
搭建过程：
分析项目结构：发现 EIDE 扩展自带命令行工具
探索工具可用性：
检查 ~/.eide/tools/ ├── gcc_arm/ ✓ ARM GCC 工具链 ├── jlink/ ✓ J-Link V8.50 └── openocd/ ✓ OpenOCD 备选解决环境兼容性问题：
问题 解决方案 Batch 脚本在 Bash 中失败 编写原生 .sh脚本J-Link 不识别 Unix 路径 sed 路径转换 Glob 搜索超时 缩小范围 + Bash 循环 脚本移动后路径错误 修正相对路径层级 封装为 Skill：
.claude/skills/eide-stm32-dev/ ├── SKILL.md # Skill 定义 └── scripts/ ├── build-flash.sh # 编译 + 烧录 ├── clean.sh # 清理 └── debug.sh # 调试
效果：AI 可以自己编译 → 看报错 → 修复 → 重试，无需人工介入
实际案例：光效系统开发中，AI 在 3 次编译迭代内完成：
- 修复按键宏未定义错误
- 修复枚举类型混用警告
- 修复正弦表初始化警告
最终达成零警告、零错误。
2.3 实践二：参考资料供给
为什么重要：AI 基于资料理解协议，而非凭空生成
供给方式：
| 资料类型 | 内容 | 作用 |
|---|---|---|
| 协议文档 | WS2812相关信息.md | 理解 NRZ 协议、时序参数 |
| 参考工程 | WS2812参考工程分析.md | 对比配置差异 |
| PCB 连接表 | PCB连接关系表.md | 确认引脚映射 |
实际效果：
- 驱动开发少走弯路：AI 知道 GRB 顺序、800kHz 频率
- 问题定位更精准：对比参考工程发现 DMA 触发方式差异
- 避免硬件踩坑：PCB 连接表防止引脚配置错误
反面案例：
最初未提供 PCB 连接表时，AI 根据"常规配置"猜测引脚，结果：
- LED 引脚猜错 3/4
- OLED I2C 引脚配置错误
- 蜂鸣器引脚不对
教训：硬件相关的信息必须明确提供，AI 无法猜对 PCB 设计。
2.4 实践三：调试能力扩展
串口监视器：
python tools/serial_monitor.py COM8115200-rAI 可以：
- 实时读取设备输出
- 看到调试打印信息
- 验证程序运行状态
GDB 调试：
AI 可以：
- 设置断点
- 读取寄存器
- 查看调用栈
- 分析内存内容
实际案例：WS2812 渐变色问题排查中，AI 通过串口打印 PWM 缓冲区，确认编码正确，定位到传输层问题。
三、Superpowers 工作流实践
Superpowers是 Claude Code 的一套结构化技能系统（skill），提供 brainstorming、writing-plans、code-review 等工作流模板。它不是本项目专用的工具，而是 Claude Code 生态中的通用能力。这里记录的是它在嵌入式场景下的实际应用效果。
3.1 工作流概览
Superpowers 是一套结构化的开发工作流，确保"想清楚再做"：
| 阶段 | 工作流 | 作用 |
|---|---|---|
| 设计 | brainstorming | 逐层澄清需求，避免返工 |
| 规划 | writing-plans | 分解任务，识别风险 |
| 执行 | executing-plans | 按计划实施，质量可控 |
| 审查 | code-review | 捕获问题，保证质量 |
3.2 游戏设计：brainstorming 实践
场景：设计消消乐游戏
过程：
brainstorming 工作流通过一次一个问题的方式，逐步澄清：
布局方案：单向布局 vs 双向布局？
- 选择：单向布局（玩家区 0-2，轨道 3-56，敌方区 57-59）
炮弹设计：单灯还是多灯？
- 选择：多灯带拖尾效果
碰撞规则：颜色不匹配怎么处理？
- 选择：不扣命，只消耗玩家炮弹
按键映射：游戏中按键功能？
- 选择：KEY1/2/3 发射，KEY4 暂停
难度系统：如何递进？
- 选择：波次递进 + 动态平衡
效果：从模糊想法到精确设计，避免后期返工
对比：如果没有 brainstorming，可能的问题：
- 做到一半发现布局不合理
- 碰撞规则需要推翻重来
- 按键功能冲突
3.3 光效系统：planner + code-review 实践
planner 使用：
AI 自动生成实现计划：
- 模块化设计：分离颜色工具和光效逻辑
- 文件架构：
WS2812_ColorUtils+WS2812_Effects - 实现步骤：按优先级分阶段
code-review 使用：
每次代码变更后，AI 自动审查：
- 类型安全
- 代码规范
- 潜在问题
实际捕获的问题：
- volatile 遗漏（中断共享变量）
- 缓冲区溢出风险（
vsprintf→vsnprintf） - 枚举类型混用警告
3.4 驱动调试：investigate + 自主迭代
WS2812 渐变色问题：
现象：设置全红，显示渐变色
investigate 排查：
- 数据层：打印颜色缓冲区 ✓ 正确
- 编码层：打印 PWM 缓冲区 ✓ 正确
- 传输层：检查 DMA 配置 →发现 CC2 触发问题
自主迭代：
尝试 1：内存对齐 → 无效 尝试 2：增加复位周期 → 无效 尝试 3：修改 DMA 触发方式 → 解决！验证：编译 → 烧录 → 串口确认 → 成功
整个过程 AI 自主完成，无需人工介入。
四、效率对比
以下对比仅衡量"单次操作耗时"，不包含 AI 思考和生成代码的时间。AI 生成代码的时间取决于任务复杂度，通常在数秒到数十秒之间。
4.1 传统嵌入式开发
| 操作 | 方式 | 耗时 |
|---|---|---|
| 编译 | 手动点击按钮 | ~10s（含操作） |
| 烧录 | 手动操作 J-Link | ~30s |
| 查看输出 | 眼睛盯着串口助手 | 持续 |
| 定位问题 | 人工分析 | 分钟级 |
| 修复验证 | 重新编译烧录 | ~1min |
一个问题的典型周期：2-5 分钟
4.2 AI + Harness 开发
| 操作 | 方式 | 耗时 |
|---|---|---|
| 编译 | AI 自主调用脚本 | ~2s |
| 烧录 | AI 自主执行 | ~0.5s |
| 查看输出 | AI 读取串口数据 | 即时 |
| 定位问题 | AI 分析错误信息 | 秒级 |
| 修复验证 | AI 自动重试 | ~3s |
一个问题的典型周期：5-10 秒
4.3 量化收益
| 指标 | 传统方式 | AI + Harness | 提升 |
|---|---|---|---|
| 编译周期 | ~10s | ~2s | 5x |
| 问题定位 | 分钟级 | 秒级 | 10x+ |
| 迭代速度 | 分钟/次 | 秒/次 | 10x+ |
| 人工介入 | 必须 | 可选 | - |
实际案例：光效系统开发，3 次编译迭代完成，总耗时 < 1 分钟
五、方法论沉淀
5.1 Harness 三要素
Harness = 工具 + 资料 + 权限| 要素 | 检查项 |
|---|---|
| 工具 | 编译器、烧录器、调试器、监视器是否可用？ |
| 资料 | 数据手册、参考代码、硬件文档是否提供？ |
| 权限 | 文件读写、命令执行、网络访问是否开放？ |
5.2 工作流选择指南
| 场景 | 推荐工作流 |
|---|---|
| 新功能设计 | brainstorming → writing-plans → executing-plans |
| Bug 修复 | investigate → fix → verify |
| 代码变更 | code-review 质量保障 |
| 复杂重构 | writing-plans 先规划 |
5.3 可迁移到其他项目的经验
1. 先搭环境，再写代码
不要急着让 AI 生成代码。先问：
- AI 能编译吗？
- AI 能烧录吗？
- AI 能调试吗？
如果答案是否定的，先把这些问题解决。
2. 提供权威资料
不要让 AI 凭记忆或猜测。提供：
- 数据手册（协议、时序、寄存器）
- 参考工程（可直接对比）
- 硬件文档（引脚映射、连接关系）
3. 封装可复用能力
把工具链封装为 Skill，下次项目直接复用：
eide-stm32-devSkill 可用于其他 STM32 项目- 脚本稍作修改即可适配
4. 让 AI 闭环验证
AI 写完代码后，让它自己：
- 编译验证
- 烧录测试
- 读取输出
- 分析问题
- 修复重试
不要人工介入这个循环。
六、局限性
Harness 模式并非万能。以下是实践中发现的边界：
AI 无法处理的问题：
- 硬件层面：虚焊、电源不稳、信号干扰——AI 只能分析软件和配置，物理问题需要示波器和万用表
- 环境层面：USB 连接断开、驱动安装失败、操作系统兼容性——这些需要人工介入
- 设计层面：PCB 引脚分配、电源拓扑——AI 只能按提供的文档工作，无法替代硬件设计决策
首次搭建成本：
- 工具链脚本编写、Skill 封装、参考资料整理需要额外投入
- 对于一次性小项目，手动开发可能更快
- Harness 的价值在重复迭代中体现：搭建一次，后续项目复用
AI 的常见偏差：
- 倾向于使用熟悉的库/方案，可能忽略目标平台的特殊约束
- 对实时性要求高的场景（中断延迟、DMA 时序），AI 可能需要多次试错才能收敛
- 参考资料的质量直接影响 AI 的输出质量——"垃圾进，垃圾出"仍然成立
七、总结
核心观点
AI 是执行者，不是魔法：它需要工具、资料、权限才能自主工作
Harness 决定 AI 的能力边界：没有编译工具链，AI 无法验证代码；没有调试能力，AI 无法定位问题
工作流保证质量：brainstorming 避免返工，code-review 保证质量
闭环是关键：AI 能自主验证 → 快速迭代 → 高效开发
本项目成果
| 成果 | 说明 |
|---|---|
| 工具链 Skill | eide-stm32-dev可复用于其他 STM32 项目 |
| WS2812 驱动 | PWM+DMA 方案，稳定驱动 60 颗 LED |
| 消消乐游戏 | 完整游戏逻辑 + 光效系统 |
| 方法论 | 这篇文章，可迁移到其他项目 |
适用范围
本文的方法论适用于：
- 嵌入式开发：需要编译、烧录、调试工具链
- 硬件相关项目：需要提供硬件文档和引脚映射
- AI 辅助开发：希望 AI 自主工作而非仅生成代码
