# 无障碍控制：让 AI 真正会用你的手机

> 不是"模拟点击脚本"，而是一套**能看、能判断、能验证、能自我纠错**的手机操作能力：
> 读得懂屏幕、找得到目标、点得准、知道点没点中，失败会自己换路。

## 1. 能做什么

开启无障碍服务后，Agent 获得以下能力（全部无需 Root、无需 ADB）：

| 能力 | 说明 |
|---|---|
| **读屏** | 提取屏幕上的文本、控件类型、坐标与层级；纯图形界面自动回退到 **OCR** |
| **点击** | 按文本、按控件 id、按坐标精确点击；支持点击前后断言 |
| **输入** | 写入指定输入框（按提示词/邻近标签定位），不覆盖别的文字 |
| **滑动 / 滚动** | 方向、距离、时长可控；滚动查找目标、滚动收集列表内容 |
| **长按 / 双击 / 双指缩放 / 拖拽** | 覆盖长按菜单、双击进入、地图缩放、拖拽排序等交互 |
| **按键** | 返回、Home、回车等系统按键 |
| **启动 / Intent** | 按包名启动应用；构造 Intent 直达页面 |
| **等待** | 等待界面稳定、等待文本出现、等待页面加载完成（不是死等固定秒数） |
| **组合** | 重复 N 次、重复直到条件成立、条件分支（`when`）、返回栈回退、收集数据 |

这些能力由 **21 个动作原语**表达，一次下发给本地闭环执行器执行 ——
不是"想一步、调一次云端、再想一步"。

## 2. 为什么快（实测数字）

| 环节 | 实测 | 说明 |
|---|---|---|
| **单步闭环** | **~1.45s / 步**（含决策+执行+验证） | 真机 `loop/run` 单步：`picked=设置中心 actMs=1132 verify=True verifyMs=69` |
| **验证（verify）** | **~5ms** | compact 快路径，体积约为完整 JSON dump 的 1/7 |
| **OCR 链** | **326–393ms**（原 1370–1588ms，**约 4 倍**） | 截图节流 + 内容区裁剪 + 单帧复用 |
| **界面稳定等待（settle）** | **355–1566ms**（按页面实际状态） | 加载信号分强弱；空树只走常规预算，不再每次白等 900ms |
| **帧差判断** | **p50 ~55ms**（含截图 IPC） | 64×64 降采样，一次比对 <5ms |
| **场景记忆命中** | **0ms，零云端调用** | 见过的界面直接复用上次决策 |

## 3. 为什么稳（看得见，也验得中）

**多层视觉，互为兜底**：

1. **无障碍节点树**：有标准控件的应用，直接拿到文本与坐标（最快）；
2. **OCR**：节点树拿不到文字时（如部分系统浏览器、Canvas 混合页面）自动补上；
3. **图标识别**：无文字的图标按钮（设置齿轮、返回箭头等）也能匹配；
4. **帧差**：只回答"画面变了没"，用来验证点击是否真的生效。

**每一步都验证**：点击 → 验证目标状态 → 失败则换路重试（换锚点、换动作、换路径），
并把失败证据（截图、候选列表、错误原因）交回给决策层，而不是盲目重试同一招。

**不抢你的操作**：AI 注入的手势会被识别并排除，误判"用户接管"不会发生；
截图时会临时隐藏悬浮窗，AI 看到的画面和你看到的一致。

**像人一样操作**：滑动轨迹带弧度与轻微抖动，不是机械直线；
点击坐标带微小随机偏移，避免固定点位特征。

## 4. 为什么省（不烧钱、不空转）

- **fast mode**：无障碍任务只在**第一步**思考，后续步骤不再付推理成本（长任务省下大头）；
- **一次下发、本地执行**：长序列在本地走完，不必每步一次云端往返；
- **页面状态检测**：真正加载完成才唤起下一步，不做固定 sleep 的空等；
- **daemon 兜底**：超长任务由后台规划进程接管，连续 3 轮失败自动停止，不会无限重试烧额度。

## 5. 和其他方案比

| | 传统 Appium / UIAutomator 脚本 | 云手机 + 远程 Agent | **DSH Mobile** |
|---|---|---|---|
| 部署 | 电脑 + adb + 测试框架 | 云端实例 + 网络 | **手机上装个 App** |
| 需要 Root/ADB | 需要 | 需要 | **不需要**（可选 Shizuku/Root 增强） |
| 适配新界面 | 写死选择器，界面一变就挂 | 每次截图上传云端判断 | **读屏 + OCR + 图标 + 帧差多层兜底** |
| 单步延迟 | 依赖脚本执行 | 云端往返 1–3s | **本地闭环，实测 ~1.45s/步** |
| 验证 | 靠脚本断言 | 靠模型"看图" | **每步结构化验证 + 失败换路** |
| 数据 | 本地/CI | **界面与操作上传云端** | **全部在本机，只把文本摘要交给模型** |

## 6. 安全边界

- **本机桥 token 门控**：能力桥只监听 `127.0.0.1:3083`，token 每次启动随机生成、只注入引擎环境，
  同设备第三方 App 无法调用（实测无 token 返回 `unauthorised`）；
- **权限三级**：普通（沙箱）/ Shizuku（adb 级）/ Root（全盘），能力未就绪的选项自动置灰；
- **su 闸门**：普通模式下 `engine/bin` 拦截 AI 子进程提权；
- **截图避让**：AI 截图时悬浮窗自动隐藏，不把自己的 UI 当页面内容。

## 7. 实测案例

- **打开系统设置并定位目标项**：单步闭环 1.45s（含点击 1.13s、验证 69ms）；
- **多功能页面综合任务**：7 次调用 / 64.7s 完成（含滚动查找、到底检测、二次确认）；
- **噪声测试站 7 页**（滚动列表、延迟加载、图标无文字、弹窗遮挡、长列表滚动）：全部通过；
- **跨应用任务**（浏览器 → 设置 → 返回原应用）：验证"操作完必须返回应用"的约束可被稳定执行。

## 8. 边界（请知悉）

- **纯 Canvas/游戏画面**：没有可读文本时只能靠 OCR 与视觉定位，复杂画面仍可能失手；
- **无文字且无标准图标的控件**：需要视觉模型辅助，默认不启用；
- **系统级权限弹窗**：仍需你手动点「允许」；
- **部分应用的防自动化检测**：不保证 100% 通过（我们也不做规避检测的对抗）。

> 更深入的设计与演进记录见 [LOCAL_CLOSED_LOOP.md](LOCAL_CLOSED_LOOP.md)、
> 实测记录见 [COMPLEX_SCENARIOS.md](COMPLEX_SCENARIOS.md)。