使用
按快速开始安装 OPW 后,在 AI 工具中打开项目、选择插件开发智能体即可开始。本文介绍日常使用的完整流程。
开始一个项目
准备工程
根据你的场景完成对应的准备。
新建 Pilot 开放插件
准备一个空目录,不需要执行命令。在 AI 工具中描述创建需求,AI 会完成工程初始化。
已有 Pilot 开放插件工程
如果工程由 OPW 生成,不需要执行命令。否则在工程根目录执行:
opw setup # 为当前工程初始化 OPW,写入 AI 开发所需的配置
已有 MSDK 应用需要迁移为 Pilot 开放插件
在原工程根目录执行:
opw setup # 为当前工程初始化 OPW,写入 AI 开发所需的配置
如需确认 OPW 的工程配置、Skills 和知识库是否就绪,可以在工程根目录执行 opw doctor。该命令只做检查,不会修改工程。
注意: 执行
opw setup前,先确认当前目录是工程根目录,不要把资料文件夹当成工程根目录。OPW 会拒绝非空且不是 Android 工程的目录。
选择插件开发智能体
在 AI 工具中打开项目目录。
切换到
pilot-plugin-dev智能体,方式因 AI 工具而异:AI 工具 切换方式 OpenCode 按 Tab 切换,或在消息中使用 @pilot-plugin-devClaude Code 执行 /output-style pilot-plugin-dev;执行/output-style default切回默认模式Codex 不需要切换,调用 opwSkill 即可或者直接调用
opwSkill 或任务 Skill(如opw-plugin-create)。确认已经生效,再描述你的目标。
切换到 pilot-plugin-dev 或调用 opw Skill 时,AI 会先识别工程类型,再选择对应的任务 Skill;直接调用任务 Skill 时,由你指定任务类型。无论哪种方式,AI 都会先确认工程状态和需求,再给出方案等待你批准,不会直接开始改代码。
如果找不到 pilot-plugin-dev,见排障。
在其他 AI 工具中使用
OPW 直接适配 OpenCode、Claude Code 和 Codex。如果你使用 CodeBuddy、Trae 等其他 AI 工具,可以先按快速开始完成 OPW 安装,再让该工具中的 AI 参照 OPW 的安装内容自行完成适配。
在该工具中新建会话,输入:
请帮我把本机已安装的 Open Pilot Wizard(OPW)适配到当前 AI 工具,要求如下:
1. 执行 `opw --version` 确认 OPW 已安装。根据 `opw` 命令的实际位置或 `npm root -g` 的输出,找到 `@open-pilot/wizard/assets/` 目录。其中 `agents/pilot-plugin-dev.md` 是路由提示词,`skills/` 下的每个子目录是一个 Skill。
2. 按当前工具的官方规范安装这些内容:把 `skills/` 下的全部 Skills 安装到当前工具的用户级 Skill 目录;如果当前工具支持自定义智能体,用 `pilot-plugin-dev.md` 的正文创建名为 `pilot-plugin-dev` 的智能体,否则以 `opw` Skill 作为入口。
3. 写入前,把文件中的 `{{OPW_GLOBAL_HOME}}` 替换为我的用户主目录绝对路径(使用正斜杠,末尾不带斜杠),把 `{{OPW_HOST}}` 替换为 `unknown`。
4. 知识库、脚本和模板已安装在用户主目录的 `.open-pilot-wizard/` 中,直接引用,不要复制或修改。
5. 不要修改 OPW 的安装目录,也不要修改 Claude Code、OpenCode 和 Codex 的配置目录。
6. 遇到需要我在几个选项中做选择的场景,优先使用当前工具自带的提问功能,没有时改用文字提问。
7. 完成后列出写入的全部文件,并告诉我如何在当前工具中开始使用。
适配完成后,按 AI 给出的方式进入 pilot-plugin-dev 智能体或调用 opw Skill,再描述你的目标。
注意: 自行适配的内容不受 OPW 管理。升级 OPW 后,需要重新执行一次适配,让 AI 用新版内容覆盖旧的副本;卸载 OPW 时,也需要手动删除这些文件。适配效果取决于该工具对 Skills 和自定义智能体的支持程度,暂未对这些工具做过验证。
与 AI 协作的五个步骤
典型任务:以航线助手为例
本节用一个完整案例串起 OPW 的各类典型任务:新建插件、开发功能、继续迭代、调试问题、能力咨询和迁移已有应用。
案例目标是在插件中选择本地 KMZ 航线并上传飞行器,再通过执行控制和 Pilot 悬浮窗查看任务进度:
- 选择本地 KMZ,显示文件名和航点数。
- 上传飞行器,显示进度、结果和失败原因。
- 上传成功后显示「待执行」,不自动开始执行。
- 支持开始、暂停、恢复、停止,并显示航点进度。
- 在 Pilot 中显示悬浮窗,展示任务状态和进度,点击可回到插件页面。
新建插件
按快速开始第 4 步创建「航线助手」插件,确认基础页面可以在 Pilot 中打开。
开发功能
给已有插件增加功能、调整 UI、修复问题或重构时,说清目标和预期,并要求 AI 先给方案:
请为航线助手加入 KMZ 航线的选择与上传:
1. 选择本地 KMZ 后,显示文件名和航点数
2. 上传时显示进度,失败时说明原因并支持重试
3. 上传成功后显示「待执行」,不要自动开始执行
先给出方案和验证步骤,等我确认后再改代码。
实现后按下面的顺序验收:
- 选择一个 KMZ,确认文件名和航点数正确。
- 触发一次失败,确认有失败原因和重试入口。
- 重新上传,确认成功后状态为「待执行」。
- 让 AI 分别报告构建、安装和运行结果。
继续迭代
在已有功能的基础上继续提出需求:
继续为航线助手加入执行控制:
- 支持开始、暂停、恢复和停止
- 显示当前航点进度
- 在 Pilot 中显示一个悬浮窗,展示任务状态和进度,点击可以回到插件页面
先说明命令和状态如何同步,等我确认后再实现。
调试问题
遇到问题时,把操作、预期和实际结果一起告诉 AI,并要求先定位原因:
问题:点击「开始」后,界面立即显示任务完成,但飞行器没有执行。
操作:选择一个 KMZ,上传成功后点击「开始」。
预期:任务进入执行中,并按航点更新进度。
实际:状态直接变成已完成。
请先定位状态来源,说明原因和修复方案,不要直接改代码。
确认原因后再修复,并用同一组操作复验。
能力咨询
只想知道 API 怎么用、错误码是什么意思时,直接提问即可。AI 只基于插件开发资料回答,不会改动你的代码:
请使用 OPW 回答:Pilot 开放插件如何获取当前飞行器的连接状态?
请给出可运行的代码片段和错误处理方式。
迁移已有 MSDK 应用
如果你已有一个 MSDK 航线应用,但还没有做成插件,可以让 AI 先评估迁移:
请评估把现有 MSDK 航线应用迁移为 Pilot 开放插件:
先说明哪些功能可以保留、哪些需要调整、哪些不能直接迁移。
我确认后再开始。
验收
构建通过不代表安装成功,安装成功也不代表业务运行通过。三个阶段要分别确认:
| 阶段 | 检查内容 |
|---|---|
| 构建 | Gradle 构建通过,产出 APK |
| 安装 | APK 安装到目标设备成功 |
| 运行(仅遥控器) | 页面打开、KMZ 选择、上传流程和悬浮窗交互正常 |
| 运行(连接飞行器) | 真实上传、执行控制和状态回报正常 |
中断与继续
会话中断或需要下次继续时,回到同一个项目,直接说明要继续:
请继续上次的航线助手开发,先说明当前进度和下一步。
不要重新创建工程。
常用命令
| 命令 | 作用 |
|---|---|
opw doctor | 检查工程和 AI 能力是否就绪 |
opw update | 把已安装的 OPW 版本同步到当前工程,详见升级与卸载 |