README

SoloPi



English · 反馈问题 · 参与贡献

面向移动设备的开源自动化测试工具：从真机操作到可复核的测试结论。

SoloPi 提供 Android 录制回放与性能工具，也提供桌面工作台和面向 AI Agent 的 Skill / Harness。你可以在电脑上观察设备、录制并回放用例，或让 Agent 在明确的动作范围内协助执行；最终结果由预先定义的检查条件和本次运行证据决定。

被测应用通常无需接入 SoloPi SDK。不同系统、设备与页面的能力和限制，请先查看下方平台支持。

 你可以用 SoloPi 做什么

- 录制与回放：在 Android 上记录操作并重复执行；也可以通过桌面节点控制录制、编辑和回放固定用例。
- 观察与验证：查看当前页面、选择可定位节点、设置固定检查点，并保留动作回执、截图及测试结果。
- 性能诊断：按设备能力采集 CPU、内存、帧率、电池、温度等指标，结合日志、录屏和启动耗时排查问题。
- Agent 协作：使用 Skill 和 Harness，将自然语言任务转化为受约束的观察与执行步骤；Agent 的完成声明不替代验收。
- 自动化集成：通过 CLI 执行用例、读取结构化报告；托管执行支持单主机设备队列、租约与有界重试。

 从设备操作到测试结论

text
桌面操作 / Agent 任务 / CLI
             │
             ▼
     SoloPi Skill + Harness
   计划、设备会话、回执与证据
             │
             ▼
 Android SoloPi / iOS WDA / NEXT 驱动
             │
             ▼
      页面观察 → 受约束动作
             │
             ▼
   固定检查点 + 独立结果判定
             │
             ▼
     passed / failed / not_tested


passed 表示必需检查点和清理条件通过；failed 表示已确认结果不符合预期；not_tested 表示证据不足，无法判定。动作结果不明时不应盲目重发。

 仓库结构

| 目录 | 内容 | 适合谁 |
| --- | --- | --- |
| solopi-app/ | Android 应用、录制回放、性能工具及设备执行能力 | 直接使用或开发手机端能力 |
| solopi-desktop/ | Electron 桌面工作台、设备控制、用例编排与报告 | 希望通过图形界面操作设备和管理测试 |
| solopi-skill/ | Agent 使用规则和内置 Harness（scripts/harness） | 希望从 Agent、CLI 或自动化任务调用 |

Skill、Harness 和 Android APK 各司其职：Skill 提供 Agent 使用规则，Harness 编排任务和验收，APK 在 Android 设备上采集与执行。使用 Skill 不要求把 Python 或模型打进 APK。

 平台支持

| 平台 | 当前入口与已验证范围 | 主要前提与限制 |
| --- | --- | --- |
| Android | SoloPi App、Desktop 和 Harness；真机已验证录制回放及特定真实 App 只读流程 | ADB、配套 SoloPi、设备辅助功能；设备和应用兼容性需分别验证 |
| iOS | Desktop / Harness 通过 WebDriverAgent 控制；已验证 iPhone 上的原生测试应用与特定真实 App 只读流程 | 需要匹配设备的 WDA、Xcode 签名和设备信任；返回和节点定位有平台限制 |
| HarmonyOS NEXT | Desktop / Harness 通过 HDC 和 uitest 控制；已验证模拟器上的受控原生应用流程 | 当前以模拟器为限，真机尚未验收；输入等操作有明确限制 |

三端共用部分控制入口和结果语义，不代表 Android 的性能插件、录屏或全部设备能力已移植到 iOS / NEXT。平台准备、动作限制和验证范围见三端设备控制指南及原生回归指南。

 快速开始

 方式一：使用桌面工作台

推荐从完整仓库启动。以 macOS Apple Silicon 和 Android 设备为例：

1. 安装 Node.js、npm、Python 3.9+ 和 Android SDK Platform-Tools，确保终端可以执行 adb。桌面文档使用 Node.js 22.14.0 验证，其他版本请自行核对兼容性。
2. 在 Android 设备上开启 USB 调试并授权当前电脑，安装与当前 Harness 协议匹配的 SoloPi App；首次使用时按设备提示完成初始化和辅助功能设置。
3. 在仓库根目录执行：

bash
adb devices -l
cd solopi-desktop
npm ci
npm run dev


设备状态应为 device。桌面启动后，选择设备；需要节点录制和固定回放时，打开左侧的「三端设备控制」。桌面同时需要相邻的 solopi-skill 和所选平台的设备工具，不能只复制 solopi-desktop/ 使用该入口。

首次连接、iOS WDA / NEXT HDC 准备、录制和回放步骤见桌面三端指南。桌面的其他用例编排和 CLI 用法见 Desktop README。

 方式二：使用 Skill / Harness

适合从终端或支持 Skill 的 Agent 发起任务。以下命令在仓库根目录运行：

bash
 查看本地内置工作流，不需要连接设备
./solopi-skill/scripts/solopi-ai --pretty workflow-list

 连接已初始化的 Android 设备后，检查配套 App 和权限
./solopi-skill/scripts/solopi-ai --serial  --pretty doctor

 查询设备声明的能力
./solopi-skill/scripts/solopi-ai --serial  --pretty capabilities


需要作为独立 Skill 安装时，请完整复制 solopi-skill/ 目录到使用的 Agent 所支持的 Skill 目录，保留脚本执行权限；不要只复制 SKILL.md。运行前阅读 Skill 说明和内置工作流。

仓库提供需要特定初始页面的只读示例。确认测试账号、应用和初态符合要求后，可以从 workflow-list 选择模板；运行结束后，使用输出中的 artifacts 查看同一次运行报告。默认使用规则，不需要模型权重。

 方式三：构建 Android App

需要 Android SDK 和项目兼容的 JDK。下面使用项目 Gradle Wrapper 构建调试包：

bas