关于 appium-troubleshooting
appium-troubleshooting 是面向使用 UiAutomator2 或 XCUITest 的 Appium 项目的故障排查技能。它收集诊断证据、依据驱动选择参考流程，并将更改限制为可验证的定向可逆修复。
主要功能
- 01按驱动和症状分流
- 02收集命令、日志与 capabilities
- 03衔接驱动专属设置流程
- 04实施定向可逆更改
- 05通过最小复检查验修复
适用场景
- 01诊断 UiAutomator2 会话启动故障
- 02排查 XCUITest 定位器或 WDA 问题
- 03不更改设备状态地隔离原因
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/appium-troubleshooting确认已加载。
详细介绍
Appium 故障排查工作流
故障排查路由与交接
每次运行都固定使用 UiAutomator2 或 XCUITest。如果驱动未知，请先收集 capabilities，或记录能够识别驱动的 Appium 日志行，再继续操作。对于其他驱动，请停止并说明此代码库尚未为其实现故障排查路由。
如果证据表明存在前置条件、安装或 doctor 检查失败，请完成当前故障排查交接，并继续使用对应的设置 Skill：
- UiAutomator2：
skills/setup-uiautomator2/SKILL.md - XCUITest：
skills/setup-xcuitest/SKILL.md
对于真实设备的签名、配置文件或 WDA 部署，XCUITest 设置 Skill 是唯一允许继续进入 skills/xcuitest-real-device-config/SKILL.md 的途径。
必需输入
确认确切的失败命令和错误、驱动、目标平台、全局 appium 或明确请求的本地 npx appium 模式、主机 OS、设备或模拟器状态、相关 capabilities、近期服务器或设备日志、最小复现，以及重新运行检查所需的权限。
决策逻辑
- UiAutomator2 会话启动、Activity 错误、过早断开、
socket hang up、辅助服务器或 adb 传输症状，使用指定的 UiAutomator2 会话启动参考资料。 - UiAutomator2 原生或混合定位器症状，使用指定的 UiAutomator2 定位器参考资料。
- XCUITest WDA 启动、安装、可访问性、应用启动或设备／模拟器状态症状，使用指定的 XCUITest 故障排查参考资料。
- XCUITest 元素查找或定位器症状，同时使用指定的 XCUITest 元素查找和定位器参考资料。
- 只有当 capabilities 值属于疑似原因时，才加载共享的 capabilities Context。
- 只有在匹配的官方参考资料无法解释确切症状时，才使用社区搜索 Context。
工作流概要
- 确定命令模式后不再更改。默认使用全局
appium；对于明确选择的本地模式，从项目根目录运行，并将 Appium 命令替换为npx --no-install appium。 - 更改任何内容之前，记录确切错误、平台、驱动、相关 capabilities 和最小复现。
- 记录提供的 Appium 和驱动版本。只有在缺少必要证据或症状需要时，才运行版本、已安装列表、连通性或 doctor 检查。
- 加载匹配的驱动配置文件，以及选定的症状参考资料。仅当匹配示例有助于说明复现过程时，才加载该示例。
- 如果前置条件或 doctor 检查失败，请先使用对应驱动的确切设置 Skill，再进行深入故障排查。
- 对于修复请求，应用一项有针对性且可撤销的更改，然后重新运行最小失败命令、会话启动、WDA 检查或定位器查找。对于仅诊断请求，在基于证据隔离原因后停止，并将有针对性的更改作为下一步操作提出。
- 优先使用 Appium 和驱动的官方文档，仅在经过验证的情况下将社区指南作为后备。
故障排查安全与审批限制
- 从有针对性的证据收集和最小可撤销更改开始。
- 在执行全面重置、重新安装、抹除设备、更改签名、更改信任设置或更改无关 capability 之前，请先征求批准。
- 除非明确请求本地模式，否则保持全局命令模式。
- 将全局和本地命令模式分开。如果本地缺少 Appium，请报告此阻碍，不要让
npx下载软件包。 - 在进行安装、特权操作、签名、信任设置或配置文件更改之前，先通过设置或真实设备审批关卡。
- 只有复现症状或重新检查通过，才能判定成功。如果证据仍不完整，请报告假设并给出下一项有区分力的检查。
完成标准
修复后，若失败的检查通过，则将修复请求报告为 passed。否则，报告为 blocked，并提供命令证据和具体的后续操作；隔离出需要人工处理的阻碍因素，并不代表故障已修复。对于仅诊断请求，若匹配的证据已确定原因，并报告了最小化的建议修复方案或可区分原因的下一项检查，且未更改状态，则视为完成。
证据边界
报告所选驱动和症状路径、命令及结果、所做的任何更改、最小化的复查，以及任何特定于驱动的后续设置。将可选的 doctor 警告视为非阻断项，并将设置或真实设备的后续操作作为交接事项报告；后续仍需选择工作流。
自我改进提示词
在最终回复之前，报告任何缺失、含糊、过时或会导致重试的故障排除说明，并注明其资源路径及建议措辞。不要修改无关资源。
证据
示例输入：Diagnose why my UiAutomator2 session fails during startup with this server log and desired capabilities. 在建议修复方案之前，请根据日志、功能配置、设备状态和特定于驱动的检查，验证所怀疑的故障类别。