排障
本文介绍自检、修复、安装与使用中的常见问题,以及问题反馈。
自检
在工程根目录执行:
opw doctor # 检查工程和 AI 能力是否就绪
修复
升级 OPW 后,如果 opw doctor 提示工程需要修复,执行:
opw doctor --fix
命令会在你确认后创建一个修复任务,不会直接修改插件代码。然后按提示让 AI 继续完成修复。
安装问题
| 现象 | 处理方式 |
|---|---|
找不到 opw 或 node 命令 | 重启终端或 AI 工具;也可以按快速开始第 3 步加载激活文件。如果使用 nvm 等工具切换 Node.js 版本,确认当前版本满足要求 |
| 提示校验失败或文件缺失 | 重新下载完整的压缩包,解压后保持所有文件在同一目录 |
| 提示与你修改过的文件存在冲突 | 安装脚本会保留你的修改并报告冲突,不会强制覆盖。人工比对后再决定是否覆盖 |
| 依赖下载失败 | 检查网络连接。需要使用镜像时,在安装命令后加上 --registry <npm 源地址> 或 --node-mirror <Node.js 镜像地址>(Windows 为 -Registry、-NodeMirror) |
常见问题
| 现象 | 处理方式 |
|---|---|
找不到 pilot-plugin-dev | 确认 opw doctor 通过并重启 AI 工具。Claude Code 使用 /output-style pilot-plugin-dev 切换;Codex 中没有 pilot-plugin-dev,调用 opw Skill 即可 |
| 构建失败 | 让 AI 查看完整报错,检查本机构建环境并按提示补齐缺失组件 |
| 功能运行结果与预期不符 | 提供操作、预期和实际结果,让 AI 先定位原因再修改 |
反馈问题
如果以上方法都无法解决问题,可以在 Mobile-SDK-Android-V5 GitHub Issues 反馈。提交时请说明:
- 问题现象:操作步骤、预期结果和实际结果。
- 环境信息:OPW 版本(执行
opw --version查看)、操作系统和使用的 AI 工具。
Issue 内容公开可见,不要在其中粘贴 App Key 等敏感信息。