使用本地 Agent 开发¶

本地 AI Agent 可以帮助阅读源码、梳理调用链、诊断仿真问题、编写算法示例和维护文档。为了让结果可复查，建议每次任务都明确范围、约束和验收条件，并要求 Agent 区分“代码推断”“静态检查”和“实际仿真验证”。

本页提供可以直接复制的任务提示词。把其中的方括号内容替换为自己的任务即可。

开始之前¶

建议让 Agent 同时访问：

SwiftWing 仿真源码；
与任务相关的本手册页面；
当前使用的 launch、配置和实验日志；
如果源码根目录存在 AGENTS.md，先完整阅读该文件。

首次提问时至少说明：

信息	示例
任务类型	理解、诊断、修改或新增功能
目标机型	固定翼、垂起固定翼或多旋翼
运行规模	单机或多机，具体数量
允许修改范围	只读、指定文件、指定功能包
验证要求	静态检查、构建、单机或多机仿真
Git 要求	是否允许提交、推送或部署

默认安全边界

本手册中的 Agent 提示词只面向 PX4 SITL。除非已经建立独立的实机流程，否则应明确要求 Agent 不连接、不解锁、不控制真实飞控。

通用任务提示词¶

下面的模板适合大多数开发任务：

请先阅读 SwiftWing 仿真项目中与任务相关的源码、launch 文件和开发手册，
不要只根据函数名或通用 PX4/ROS 知识推测当前实现。

任务：
[描述需要理解、诊断或修改的内容]

目标环境：
- 机型：[固定翼 / 垂起固定翼 / 多旋翼]
- 规模：[单机 / N 机]
- 环境：Ubuntu 20.04、ROS Noetic、PX4 v1.15.0、Gazebo Classic

允许范围：
- 可以读取：[目录或文件]
- 可以修改：[目录或文件；如果只分析，写“禁止修改”]
- 不要修改无关文件
- 不连接或操作真实飞控
- 不提交、不推送，除非我另行确认

开始修改前：
1. 检查 Git 状态和当前源码版本；
2. 列出相关节点、类、函数、话题、服务和 launch；
3. 说明准备修改的文件及理由；
4. 如果存在多种实现方式，先给出方案和取舍。

验收要求：
- 说明完整调用链；
- 标明坐标系、单位、数组形状和控制频率；
- 检查零速度、零模长、NaN、限幅和异常时间步；
- 完成约定的检查或仿真；
- 区分已验证内容和未验证内容；
- 更新受影响的使用文档；
- 最后列出修改文件和验证结果。

理解源码，不修改代码¶

适合第一次阅读控制器或算法：

请只分析，不修改任何文件。

请从 [入口节点或函数] 开始，梳理到 PX4/MAVROS 输出的完整调用链。
对每一步说明：
1. 源码文件和函数；
2. 输入、输出及对象状态变化；
3. ROS 话题、消息或服务；
4. 坐标系、单位和更新频率；
5. 使用的算法公式；
6. 限幅、状态机和数值边界；
7. 哪些结论来自源码，哪些属于推断。

最后给出一条从上层指令到飞控设定值的数据流摘要。

推荐结合阅读：平台架构、坐标系与接口以及API 参考。

诊断仿真问题¶

当仿真无法启动、无法进入 OFFBOARD 或飞机不跟踪轨迹时使用：

请诊断以下 SwiftWing 仿真问题，当前阶段只定位原因，不修改代码：

现象：
[描述看到的现象]

启动命令：
[按终端顺序粘贴完整命令]

第一条报错及其上下文：
[粘贴日志]

环境：
[ROS、PX4、Ubuntu、Docker/原生环境、单机/多机]

请按以下顺序检查：
1. 环境变量和 ROS 功能包；
2. PX4、Gazebo 与 MAVROS 是否启动；
3. /mavros/state 的 connected、armed 和 mode；
4. 控制话题是否持续发布；
5. uav_id、uav_amount、命名空间、模型名和 UDP 端口；
6. Python 依赖和第一处异常；
7. 数值错误或状态机未满足。

输出最可能的根因、支持证据、验证命令和修复建议。
没有实际验证的结论请明确标记为“待验证”。

新增单机轨迹示例¶

请为 SwiftWing 仿真平台新增一个 [轨迹名称] 单机示例。

要求：
- 参考 single_demo/scripts 中最接近的现有示例；
- 使用 single_demo/scripts/uav_lib/spawn_uav.py 读取状态；
- 优先通过 control_send(command, "vel") 发送三维期望速度；
- 支持 [固定翼 / 垂起固定翼 / 多旋翼]；
- 增加对应 launch 文件；
- 保持现有话题和节点命名兼容；
- 对所有向量归一化、反三角函数和时间步增加边界检查；
- 把速度、高度、轨迹尺度和增益集中写在脚本开头并加注释。

开始编码前，先给出：
1. 轨迹数学定义；
2. 导航或跟踪算法；
3. 预计修改文件；
4. 验证方案。

完成后进行 Python 静态检查和 Catkin 构建；
具备环境时再运行单机 SITL，并更新快速上手、算法说明和 API 文档。
不要提交或推送。

修改固定翼或垂起控制算法¶

控制器修改风险较高，建议要求 Agent 先给方案：

请分析并改进 [FW_class.py / VTOL_class.py] 中的 [函数名]。

目标：
[描述期望改善的行为]

开始修改前必须：
1. 找到所有调用位置和最终 MAVROS 输出；
2. 写出当前实际执行的公式，而不是只解释函数名称；
3. 指出源码中计算后被覆盖或未参与输出的变量；
4. 检查零速度、除零、acos/asin 输入、NaN 和 dt；
5. 给出最小修改方案、参数变化和兼容性影响；
6. 等我确认方案后再改代码。

修改时保留原 ROS 话题、服务和公共函数签名，除非我明确批准接口变化。
保留滚转、俯仰、速度、加速度和纵向控制量限幅。

验收至少包括：
- Python 静态检查；
- 直线、定常转弯和爬升三个工况的输入输出检查；
- 具备环境时进行单机 SITL；
- 对比修改前后的关键参数和行为；
- 更新对应控制器手册。

修改或扩展多机编队¶

请把当前 SwiftWing [领航—跟随 / 一致性] 示例扩展到 [N] 架无人机，
或把编队改为 [队形描述]。

请先检查并列出：
- PX4 实例和实例 ID；
- Gazebo 模型名称；
- MAVROS UDP 端口；
- /uavN 命名空间；
- uav_id 与 uav_amount；
- 编队偏移矩阵；
- 图拉普拉斯矩阵及其连通性；
- 算法 launch 与 px4_launch 的对应关系。

不能只修改 Python 中的成员数量。

开始修改前给出文件清单、端口/编号映射表、通信拓扑和资源预估。
完成后先做配置一致性检查，再根据计算机资源决定是否启动多机仿真。

让 Agent 同步更新手册¶

请根据本次源码修改更新 SwiftWing 仿真开发手册。

要求：
- 面向平台用户和开发者，不写成内部审阅记录；
- 保留已有页面地址和导航兼容性；
- 只描述当前源码实际提供的功能；
- 未运行验证的行为明确写为“未验证”或“使用前需确认”；
- 如果函数、类或签名发生变化，重新生成 API 参考；
- 检查所有内部链接并执行 MkDocs 严格构建；
- 检查桌面和移动端的代码块、表格和导航。

最后报告修改页面、构建结果和仍需人工确认的内容。

验证等级¶

Agent 报告“已验证”时，应说明具体达到哪一级：

等级	含义	可以证明什么
L0 源码核对	阅读定义、调用和配置	解释与当前代码一致
L1 静态检查	Python 语法、配置和链接检查	文件可解析，明显错误已排除
L2 工程构建	`catkin_make` 或 MkDocs 严格构建	工程能够完成构建
L3 基础 SITL	PX4、Gazebo、MAVROS 正常连接	仿真基础链路可运行
L4 单机任务	完成指定轨迹或控制工况	单机场景行为得到验证
L5 多机任务	完成指定编队场景	当前规模和配置下多机链路可运行

高等级包含更完整的运行验证，但仍不等于实机验证。仅完成 L1 时，不能写成“仿真测试通过”。

用户验收清单¶

收到 Agent 结果后，建议逐项检查：

修改范围¶

是否只改了批准的文件；
是否保留了原有页面、话题和 launch 兼容性；
是否误改 Git remote、身份或无关配置；
是否保留了用户已有的未提交修改。

技术内容¶

算法公式是否来自当前源码；
坐标系、单位、角度顺序和数组形状是否明确；
单机与多机命名空间是否正确；
是否检查除零、NaN、零向量和异常时间步；
控制量是否保留合理限幅。

验证证据¶

是否写明执行了哪些命令；
是否区分构建成功与仿真运行成功；
是否提供第一处失败和未验证内容；
是否说明测试机型、数量、轨迹和参数；
是否更新相关文档。