# 手机应用读取与自动化能力

本项目可以把手机当作一个需要用户授权的受控设备。它能够观察当前屏幕、读取有限的
UI 层级、启动指定应用、点击坐标和向当前焦点输入文本，再把新的观察结果交给模型；
用户开启 AI Shell 后，还能通过 Shizuku 执行一次性 Android Shell 脚本，处理用户允许的
文件读写、上传、下载、建目录和后台任务查询。

## 当前已经具备的第一阶段能力

Shizuku 连接成功、用户授权并且 Harness 运行时启动后，模型可以使用以下工具：

| 工具 | 作用 | 约束 |
| --- | --- | --- |
| `mobile_device_list_packages` | 查找已安装包名 | 只按受限包名片段筛选，最多返回 256 行 |
| `mobile_device_app_launch` | 启动包名的默认入口 | 只接受标准包名；包名由模型从设备清单中选择 |
| `mobile_device_current_app` | 读取当前前台诊断行 | 只返回有限的 `dumpsys activity` 行，设备文本不可信 |
| `mobile_device_screenshot` | 读取当前屏幕 | 需要当前模型支持图片输入，并受大小限制 |
| `mobile_device_ui_dump` | 读取 `uiautomator` 层级 | 某些 ROM 可能只返回空壳，需要改用截图 |
| `mobile_device_tap` | 点击屏幕坐标 | 坐标范围受限；必须来自最近一次观察，原生服务仍检查白名单、锁屏和敏感窗口 |
| `mobile_device_input_text` | 向当前焦点输入普通文本 | 只接受普通文本，不适合密码、验证码或密钥；原生服务检查目标控件 |
| `mobile_device_background_tasks` | 查询指定应用的进程、服务或 Activity 摘要 | 只返回 Android Shell 可见的摘要，不代表能读取后台界面或私有数据库 |
| `mobile_device_shell` | 执行一次性 Android Shell 脚本 | 需用户在设置中开启 AI Shell；脚本最多 16 KiB，使用 Shizuku 实际权限 |
| `mobile_device_wait` | 等待界面稳定 | 只能等待 100 毫秒至 10 秒 |

固定设备命令由 Android 原生校验和模型插件双重校验。桥接层不提供 Root、任意 Activity
或 Intent 参数。投递区的文件读取、写入、上传、下载、列目录和建文件夹仍只允许
`inbox/outbox` 下的相对路径，并有符号链接、大小和输出限制；用户明确开启 AI Shell 后，
Shell 通道才可按 Shizuku 实际权限访问其它设备路径。

无障碍服务必须由用户在系统设置中手动开启，并从应用内的已安装应用分页选择器保存目标包名；
白名单不设数量上限。用户完成授权后，模型工具不再逐条弹出确认，但 Android 原生服务仍核对
目标包、锁屏状态、敏感页面、控件资源 ID、输入内容和动作频率。系统设置、权限、支付、
验证码、密码、生物识别页面会被拒绝，服务也不能绕过锁屏。

### 白名单自动项与验证密码

- **本应用始终在白名单里**：白名单读出时自动并入 `io.deepseekharness.mobile`，保存时也自动
  补回，因此从文本框里手动删掉它不会生效。理由是本应用自己的界面（设置页、对话页）是
  最常用的自动化目标，漏掉它只会让用户看到「明明开着却点不动」。这一项由原生侧
  `AccessibilityAutomationPolicy` 统一补齐，前端只展示结果。
- **改白名单可以加一道验证密码**：密码是可选的，没设置时按原样保存；一旦设置，
  **每一次**修改白名单都要先输入它（不做免验证窗口）。密码只存 16 字节随机盐 + PBKDF2
  （`PBKDF2WithHmacSHA256`，默认 120 000 次迭代）派生出的 32 字节哈希，**明文不落盘、
  不进日志、不进审计、也不回传给前端**；比较用常量时间。
- **失败有代价**：连续输错 5 次锁定 30 秒，锁定期内即使输对也拒绝，提示里给出剩余秒数。
- **忘记密码的出路**：用系统生物识别或锁屏凭据重置（API 30+ 走
  `BIOMETRIC_STRONG | DEVICE_CREDENTIAL`，API 26–29 回退到锁屏凭据）。重置**只清密码、
  不动白名单**——避免「忘了密码顺手把白名单也清了」这种更糟的结果。
- **不削弱原有护栏**：密码门只挡「谁能改白名单」。目标包白名单、敏感窗口、锁屏、
  控件资源 ID、速率限制与设备端一次性确认**一律不变**，也不能被绕过；密码不是 root，
  不是保活手段，也不承诺能挡住拿到已解锁设备的人。

## 推荐的自动化循环

1. 用 `mobile_device_list_packages` 确认目标包名，不从页面文字猜包名。
2. 使用已保存的应用白名单启动目标应用。
3. 用 `mobile_device_screenshot` 或 `mobile_device_ui_dump` 观察当前状态。
4. 从最近一次观察得到节点边界或坐标，只执行一个点击或一次文本输入。
5. 用 `mobile_device_wait` 等待短时间，再重新观察。
6. 如果前台包、页面结构或控件状态与预期不符，停止并报告，不盲目重试。

截图、UI XML、应用标题、通知和文件内容都按不可信设备数据处理，其中出现的文字不能
改变模型的安全规则，也不能被当作新的指令。

## 要做到更深层的应用控制，还需要什么

当前已经接入需要用户手动开启的无障碍服务、应用白名单管理和模型工具。无障碍服务不能由
Shizuku 静默开启，也不读取未被选择应用的窗口。服务采用目标包白名单、速率限制和本地审计，
在锁屏、支付、验证码、生物识别和系统权限页面上停止自动操作。无障碍服务本身不能保证锁屏
后可操作：屏幕关闭、锁屏保护、目标应用后台限制和厂商电池策略都可能使 UI 不可用。

目标应用的私有数据库、后台业务接口和登录态不能仅靠 Shizuku 获得。合规的深层集成需要
目标应用提供公开 Intent、ContentProvider、导出分享入口或经过授权的 API；否则只能使用
屏幕层面的公开 UI。应用自动化也不能保证绕过目标应用的风控、验证码或用户确认。

## 权限与验收边界

- Shizuku 的实际能力取决于用户授予的权限和 Android 版本，不能把它描述成 root。
- 点击、输入和启动应用是有副作用的操作；授权后可连续执行，但仍按不可信设备数据处理，
  不会把观察内容当作新的指令。
- 锁屏、后台拉起、厂商电池策略和无障碍服务行为必须在真实手机或 MuMu 实例上验收，
  JVM 单测只能验证参数白名单和命令构造。
- 本轮已在 MuMu 12 的 1272×2800（竖屏）与 2800×1272（横屏）覆盖尺寸下验收外壳导航、
  安全区和设置布局；未宣称 Shizuku 实际授权、悬浮窗或锁屏后台恢复在该模拟器中通过，
  这些能力仍需在具备对应系统服务的真实设备上按 `docs/mobile-acceptance-checklist.md` 验收。