倒立摆控制调参与验证

这个项目对应媒体平台上“调倒立摆 PID”的演示。视频里能看到倒立摆从不稳定到逐渐站稳，但真正复现时，关键是让 Agent 先理解控制结构和验证方式，而不是直接让它猜一组 PID 参数。

这个项目在解决什么问题？

目标是让两轮倒立摆在真实硬件上稳定站立，并在轻微扰动后恢复平衡。

常见问题包括：

一上电就快速倒下
能站起但持续高频抖动
低频来回摆动，最后失稳
速度环拖着小车持续漂移
电机输出饱和，参数越调越乱

这个项目的重点不是追求一次性给出“神奇参数”，而是把调参过程拆成可以记录、复盘和回滚的小实验。

当前硬件、软件与连接方式

典型现场包含：

部分	作用
倒立摆车体	被控对象
IMU	提供角度或角速度估计
编码器	提供轮速、位移或速度环反馈
电机驱动	执行控制输出
控制板	运行姿态估计和 PID 控制代码
串口或调试接口	输出角度、速度、PWM、状态等日志

硬件接线关系可以先按下图理解：

倒立摆车体、控制板、IMU、电机驱动和调试接口的接线指引 — GPT 生成的接线指引，用于帮助理解连接关系。图片中的接口名称、线序和器件外观可能与您的实际元器件不完全一致，接线时请以实际板卡、传感器、电机驱动和厂商资料为准。

开发者可以先用自然语言告诉 Agent 当前控制周期、传感器方向和失败现象等现场背景。工程代码、串口日志和调试变量不需要单独粘贴到对话里，Probes 会在可访问的工作区和工具环境中自行读取。

开发者需要提供什么？

下面信息可以直接用自然语言在对话中输入，不是所有情况都需要全部提供。请根据您自己的开发需求，从以下参考中选择最有帮助的部分说明即可：

IMU、编码器、电机驱动的连接和方向说明
控制周期、PID 参数和输出限幅
每次修改后是否能站立、是否抖动、是否漂移
允许 Agent 修改的文件范围和验证命令

如果您已经知道某次修改前后的关键现象，也可以直接描述给 Agent；更细的日志和调试变量由 Probes 结合工程环境继续读取和分析。

智能体可以完成什么？

Agent 可以完成：

阅读控制代码并梳理角度环、速度环、位置环
检查传感器方向、零点、单位和输出限幅假设
设计分轮调参计划
根据日志和现象建议小步参数修改
生成每轮验证清单和回滚建议
总结哪些现象支持当前判断，哪些还需要补采

Agent 不能替代真实硬件安全判断。车体上电、轮子悬空测试、地面测试、急停和供电安全仍然由开发者确认。

最终如何判断结果正确？

一个可靠的调参结果至少应满足：

倒立摆能从安全初始角度进入平衡状态
静止站立时没有持续高频抖动
受到轻微扰动后能恢复平衡
电机输出没有长期饱和
速度或位置漂移在可接受范围内
参数修改过程有记录，可回滚到上一组稳定参数
日志中的角度、速度、PWM 和状态与现场现象一致

如果只是在某一次视频里短暂站住，但没有日志、重复验证和回滚记录，就不应该视为稳定完成。

可复制的提示词模板

视频里不是一次性让 Agent 给出完整双环参数，而是分成两轮：先把角度单环调到可用，再在这组参数基础上引入位置外环。下面是两轮提示词的整理版。

第一轮：调好角度单环

现在 apps/inverted_pendulum_auto_start 目录下是一个双环 PID 倒立摆项目，
但双环的 PID 参数还是全 0。

我想请你接下来帮我调好角度单环的 PID。
请你在了解清楚它的架构、状态机流转逻辑后，按照规范的工作流帮我确定一组能较好平衡、
可以用于进入双环的单环参数。

硬件和项目约束：
1. 角度传感器在摆杆倒下，也就是状态 0 时进入底部会有盲区，
   且由于电路作用数据会漂移到中点角度，不可信。
   只能触发起摆，不能直接进入状态 4。
2. 需要调动参数以处理代码设定中心角度与实际偏差 0 的误差。
   p 和 d 在 1 以内，i 在 0.2 以内是安全的。PID 符号均为正。
3. 每一轮窗口采集大概 6 秒即可。
4. 收到的日志和有关解析产物都放到 pid-data-logs 的规范子目录里，
   你写的脚本可以放 tools 中。

第二轮：引入位置外环

请你现在以单环角度环最好的那组为基础，接下来引入位置环，
按照规范的工作流帮我迭代出一版效果较好，
要求位置控制能快速闭环不来回振荡，
至少能在 3 秒内让位置稳定在目标值周围的双环参数。

安全范围：
- p、d：5 以内；
- i：1 以内；
- 在范围内的值均被允许。

位置环的各个参数是否需要没有硬性要求，自行分析判断。

如果后续分析觉得不够或太长，你可以调一组比较好的角度内环参数，
这时候位置外环参数还是全 0。

这两段提示词的关键是把“调参”变成有边界的迭代：

第一轮只追求角度单环可平衡；
第二轮才引入位置环；
每轮日志窗口控制在约 6 秒；
所有日志和解析产物落到固定目录；
参数范围和符号约束提前写清楚，避免 Agent 做危险的大步试探。