SoloPi AI Control

SoloPi AI 控制框架

将本文件所在目录作为 Skill 根目录。只使用 Skill 的薄入口：

scripts/solopi-ai --pretty <命令>

执行时把 scripts/solopi-ai 解析为绝对路径，并保持调用者当前工作目录不变。该入口调用同级 solopi-harness-cli 的核心实现；独立安装时可通过 SOLOPI_HARNESS_CLI 指向准确 CLI。不得调用仓库根目录下的兼容脚本，也不得自行拼接 HTTP、Scheme 或 Shell 命令代替类型化 CLI。

全局参数必须放在子命令前。多台设备在线时，每次调用都必须添加 --serial <adb-serial>。

能力路由

需要判断某项 App 能力是直接 CLI、用例间接、用户交互还是暂不可安全自动化时，先读取 能力矩阵。需要证明页面、设置和动作是否已纳入覆盖时，再读取 App 功能覆盖清单。

actions、case-template、case-validate、case-step-*、perf-analyze、verify-normalize、verify-compile 和 verify-validate 是纯本地操作。verify-run 与其他 SoloPi 协议设备操作首次执行前先运行 doctor；startup-time、screenshot 和 logs 只要求 ADB 设备，不要求 SoloPi 控制协议或内部权限就绪。

通用执行规则

1. 设备命令先运行 doctor；纯本地的 actions、case-template、case-validate、case-step-* 和 perf-analyze 不连接设备，可直接执行。doctor 必须核对内部 ADB、悬浮窗、电池优化白名单和辅助功能；background 只是 App 的提示型状态。若唯一缺失项为内部 adb，使用 adb-connect 发起 SoloPi 自身连接并等待准确 requestId 的终态，再以命令返回的完整 doctor 为门禁。存在其他缺失项时停止设备变更并报告，不得静默授权。
2. 运行 capabilities，只调用设备声明支持的 SoloPi 协议命令；startup-time 是当前 Skill CLI 内置的固定 ADB 能力，不属于设备控制协议。
3. 查询真实数据：应用用 apps，内置动作契约用 actions，用例用 cases，性能指标用 perf-list。actions 不访问设备，也不会发现插件额外注册的入口或 Provider；不得猜测包名、动作、用例名或指标键。
4. 保存每次变更和回放启动使用的 requestId，以及回放的 runId、性能/录制/压力/独立录屏操作的 sessionId、历史记录的不透明 id 和插件的稳定 pluginId。后续查询、停止或删除必须使用原标识；标识不匹配时停止归因。
5. 只有对应状态机的成功终态和退出码同时满足要求，才能报告完成。ADB 已接受、请求已受理或会话仍活动都不是业务成功。
6. 超时或中断后，先查询准确标识对应的状态，再停止属于本任务的活动会话；未确认清理完成前不得启动同类新会话。

SoloPi 设备状态变更经受 android.permission.DUMP 保护的显式 ADB Activity 发送；普通 App、网页深链和 ADB 转发后的 HTTP 不能进入该变更通道。HTTP 只用于查询。adb-connect 只调用 SoloPi 既有的内部连接流程，不接受 RSA 弹窗、不修改内部地址、不执行 adb tcpip 5555。startup-time 只允许内部固定的 Launcher 解析和 am start -W 命令。CLI 不提供任意 Shell、任意 Scheme、任意 HTTP 或 Wi-Fi 直连设备端口的后门。

动态 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。动态协议不接受任意 Shell、Provider、枚举名、清数据或进程控制。正常完成用原身份执行 agent-end，放弃或错误路径执行 agent-cancel；暂停期间可 observe 和查询，但不能 act。最终用 agent-timeline 核对每个输入观察、typed action、receipt、settled observation、终态和租约释放事件。

AI 验证工程

把需求/AC 交给验证工程时必须先读取验证工程契约。稳定步骤必须声明为 operation 并编译成固定 SoloPi 用例；只有选择器或路径未知的工作才声明为有预算的 explore。模型输出 done 只停止探索，不能写入 checkpoint 状态或最终结果。

执行前必须通过 verify-validate。JSON 字段 oracle 是 checkpoint 的确定性预期规则； Result Judge 是唯一最终裁决主体。只有统一报告中所有 required checkpoint 都有本次运行 证据且 oracle 规则通过、required cleanup 也成功时，整体才可报告 passed；failed 与 not_tested 不得合并。复现性比较使用 planFingerprint + outcomeFingerprint，不比较 时间、run ID 或本机路径；outcomeFingerprint 只比较语义裁决，不代替同次运行证据身份。

托管执行

无人值守或多设备任务必须先读取托管执行与设备池。 提交后同时保存 taskId 和首次返回的 ownerToken；重复提交使用相同 idempotencyKey + ownerToken，取消也只允许原 owner。worker 只能执行控制面 返回的准确 serial 和 assignment，不能自行挑选设备或改写计划。

任务成功以 managed-report 的终态、稳定退出码和逐 shard 证据为准。 queued/running、单个 shard 通过或 worker 进程正常退出都不代表矩阵通过。 发生服务重启或网络中断时先恢复过期 generation；旧 assignment 的迟到结果 必须被拒绝，不能手工写回。

端侧模型

端侧决策前必须读取端侧 Agent 模型部署。模型包先 执行 model-verify，再按 install、benchmark、release-check、activate 顺序保存 每个 typed receipt。签名、摘要、兼容性或发布门禁失败时停止，不能换任意 key、 backend 或绕过 companion。模型 done 仍只能结束探索，最终结果只看 Result Judge 基于 checkpoint oracle、required cleanup 和本次运行证据形成的统一报告。

用例与回放

创建或修改用例前读取 用例编写；涉及动作时再读取 动作目录。基本闭环：

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 与结果；任一子运行失败时不得用汇总结果掩盖。
• run、run-repeat 和 run-batch 可用 --target-package 覆盖本次运行目标，用 --restart-app 或 --no-restart-app 覆盖本次重启策略；覆盖只作用于本次运行，不写回用例或全局设置。目标必须是已安装、具有 Launcher 且不能是 SoloPi 自身。
• case-validate、case-import 和所有 run* 命令会对整份用例应用相同安全策略：始终拒绝历史 EXECUTE_SHELL、内部 HANDLE_PERMISSION_ALERT、HIDE_INPUT_METHOD 和 Provider 上传 URL；CLEAR_DATA、KILL_PROCESS、JUMP_TO_PAGE 必须显式使用 --confirm-high-risk。前三项只能通过 case-step-list 查看，不能由 CLI 导入或回放。
• 回放前保存设备返回的准确 caseId 与 caseFingerprint；指纹覆盖从外部步骤文件实际加载、解密并内联后的完整内容，启动请求必须同时携带两者和新的 requestId。App 只执行该不可变快照；同名用例在预检后被替换、修改或原地改写步骤文件时必须失败，其他客户端的同名回放也不能被本次请求认领。
• 图片对比和用例内录屏动作只在所需插件已通过本地文件安装、重启并处于已加载状态时回放；缺失时停止并报告，不触发远程下载。
• 取消回放必须使用启动命令保存的 runId：cancel --run-id '<run-id>'。当前活动运行不匹配时停止，不能取消其他调用方的任务。
• 多参数用例不是 run-batch。先用 case-get 导出用例，再用 case-validate --running-params-file <文件> 写入并校验 SEPARATE 或 UNION 参数集合，最后通过 case-import --replace 更新准确用例；清除配置时使用 --clear-running-params。
• case-delete 是不可逆设备变更。先用 case-get 保存需要的副本，并获得用户对准确用例名的删除意图。
• 默认 run 会设置回放自动启动配置；不允许修改时使用 --no-auto-start，并先确认设备已启用该配置。