SoloPi AI 控制框架
SoloPi AI 是围绕支付宝 SoloPi 构建的 AI 控制框架，以 Skill 形式提供薄入口 scripts/solopi-ai，Harness 实现与内置模板随 Skill 放在 scripts/harness/ 下，默认只调用这一份实现，不依赖仓库外同级目录或已安装的 Python 包。调用方可通过 SOLOPI_HARNESS_CLI 指定另一准确 CLI，普通使用无需配置。安装时需完整复制 Skill 目录并保留脚本执行权限，运行需要 Python 3.9+ 和设备操作所需的 ADB。Laya 权重、虚拟环境、APK 和真机证据不随 Skill 打包。
用途与主要能力
框架面向 Android 真机测试与验收，核心能力包括：通过内置工作流选择支付宝模板并一条命令执行，自动完成预检、计划编译与校验、执行及截图报告；从需求/AC 编译可复现验证计划；交互录制、回放与批量回放；动态 Agent 观察与类型化动作；性能指标采集、实时监控、启动耗时测量、压力测试、独立录屏与视频差分视觉响应耗时分析；相机扫码；插件本地安装与移除；签名端侧模型安装、激活、回退、推理与基准；以及持久设备池、任务队列、矩阵调度和 CI/API 托管执行。
使用方式
全局参数必须放在子命令前。多台设备在线时，每次调用都必须添加 --serial <adb-serial>。快速使用示例：
scripts/solopi-ai --pretty workflow-list scripts/solopi-ai --serial <adb-serial> --pretty workflow-run --template alipay-more-services scripts/solopi-ai --pretty workflow-report --artifacts <上一步返回的artifacts>
默认规则模式不加载模型。只有用户明确选择 Laya 实验时，才传 --mode laya --model <本地MLX权重目录>，模型运行在电脑上。不要为这些模板安装 companion APK，也不要把模型输出当成验收结论。workflow-run 自动完成预检、计划编译与校验、执行及截图报告；前置页面不满足时保留 not_tested，不自动重跑。完成后返回 Markdown 报告路径，并说明三态结果、清理结果和截图是否齐全。
设备命令先运行 doctor；纯本地的 actions、case-template、case-validate、case-step-* 和 perf-analyze 不连接设备，可直接执行。doctor 按设备声明的执行模式检查权限：支持 executionProfiles.host 的电脑端回放只要求内部 ADB 和辅助功能；电池优化白名单仅作建议，悬浮窗不阻止执行，background 仍只是提示型状态。旧版 APK 保留原门禁并提示升级。若唯一缺失项为内部 adb，使用 adb-connect 发起 SoloPi 自身连接并等待准确 requestId 的终态，再以命令返回的完整 doctor 为门禁。存在其他缺失项时停止设备变更并报告，不得静默授权。
用例与回放的基本闭环：
scripts/solopi-ai --pretty doctor scripts/solopi-ai --pretty apps scripts/solopi-ai --pretty actions scripts/solopi-ai --pretty cases scripts/solopi-ai --pretty case-get --case "payment-smoke" --output cases/payment-smoke.json scripts/solopi-ai --pretty case-validate --file cases/payment-smoke.json --output cases/payment-smoke.import.json scripts/solopi-ai --pretty case-import --file cases/payment-smoke.import.json scripts/solopi-ai --pretty run --case "payment-smoke" --run-timeout 600 --artifacts artifacts/payment-smoke scripts/solopi-ai --pretty result --run-id '<run-id>'
只把终态 passed、至少一条回放结果且退出码为 0 视为通过。run --no-wait 的退出码 0 只表示请求受理，需继续用保存的 runId 查询。run-repeat 和 run-batch 是多个独立运行的编排，保留每个子运行的 runId 与结果，任一子运行失败时不得用汇总结果掩盖。
动态 Agent 先执行 agent-session-start 并保存 sessionId、ownerToken 和首帧 observationId。每步只从该 observation 的真实 nodeId 中选择目标，以新的 stepId 调用 agent-act；下一步使用 receipt 中 settle 后的新 observation，或显式执行 agent-observe。收到 stale_observation 时必须重新观察和决策。只使用 CLI 发布的 click、longClick、input、back、home、scroll、wait。正常完成用原身份执行 agent-end，放弃或错误路径执行 agent-cancel。
AI 验证工程要求把需求/AC 交给验证工程时先读取验证工程契约。稳定步骤必须声明为 operation 并编译成固定 SoloPi 用例；只有选择器或路径未知的工作才声明为有预算的 explore。执行前必须通过 verify-validate。JSON 字段 oracle 是 checkpoint 的确定性预期规则；Result Judge 是唯一最终裁决主体。只有统一报告中所有 required checkpoint 都有本次运行证据且 oracle 规则通过、required cleanup 也成功时，整体才可报告 passed；failed 与 not_tested 不得合并。
性能与压力测试需先运行 perf-list 获取指标。需要现场观察时使用 perf-display-start/status/stop；需要 CSV 时使用 perf-start/status/stop。两类会话共享性能服务、不能并发，均按准确 sessionId 清理。启动耗时使用安卓 Activity Manager 口径，示例：
scripts/solopi-ai --pretty startup-time
--target-package "com.example.pay"
--mode cold
--iterations 5
--interval 1
压力测试示例：
scripts/solopi-ai --pretty stress-start --cpu-count 1 --cpu-percent 50 --duration 60 scripts/solopi-ai --pretty stress-status --session-id '<session-id>' scripts/solopi-ai --pretty stress-stop --session-id '<session-id>'
适用场景
适用于需要在 Android 真机上执行验收测试、回归回放、性能与启动耗时测量、压力测试、录屏取证、扫码验证、插件扩展、端侧模型决策验证以及多设备 CI 矩阵调度的团队。内置支付宝模板适合快速跑通“连接手机跑几个案例”“运行支付宝模板”“查看带截图的结果”等场景。
限制与安全约束
只操作用户明确纳入范围的设备、应用、用例和配置；不得静默授予权限、开启辅助功能或修改设备安全设置。不提供或绕过到任意 Shell、任意 Scheme、任意 HTTP；已有用例中的高风险动作也必须先核对内容与授权。配置只允许 config-list 公布的键和值类型；敏感配置、性能/录屏上传地址、远程插件源和内部 ADB 地址只能在 App 界面处理。同类活动会话只允许一个所有者，停止操作必须携带启动返回的准确标识。业务失败和调用方中断不能跳过清理，压力负载必须优先停止。插件是动态代码，只安装用户明确指定的本地包，核对 SHA-256 和准确 pluginId，安装或移除后报告必须重启的风险。不得编造节点选择器，以 case-get 或 inspect 的真实输出为依据。用例导入、删除、配置变更、截图、日志、录屏和性能文件都可能包含敏感信息，使用新的受控路径，不得自动上传或外发。
成功与证据要求：回放完成必须同时满足 CLI 退出码为 0、状态为 passed、results 非空；请求 --artifacts 时还要确认 result.json、screen.png、logcat.txt 存在。失败时保留并报告 exceptionMessage、exceptionStep 和 exceptionStepId。变更命令必须核对返回的 requestId 或 sessionId；插件终态 completed_restart_required 只证明变更落盘，不证明新代码已加载。