docs: plan android emulator support

Author: linhay

docs-linhay/memory/2026-06-05.md

@@ -62,3 +62,9 @@
 - 决策：外部用户默认安装整个 `TritonKit.skills/` 文件夹到对应 agent skills 目录下，不再把三个 public skills 作为顶层目录分别复制进去。
 - 处理：`tritonkit-skills.tar.gz` 包结构改为顶层 `TritonKit.skills/`，`BUILD_INFO.json` 放在 `TritonKit.skills/BUILD_INFO.json`；README / release 文档说明旧安装升级时先删除 `tritonkit-dev-feedback`、`tritonkit-emulator-cli-takeover`、`tritonkit-real-project-regression` 三个旧顶层目录。
 - 脚本：新增 `docs-linhay/scripts/install-public-skills.sh <agent-skills-dir> [--from-tar tritonkit-skills.tar.gz]`，自动删除旧三个独立目录并安装整个 `TritonKit.skills/` bundle。
+# Android Emulator 支持规划
+
+- 新建 `docs-linhay/spaces/20260605-android-emulator-support/`，定义 Android Emulator 支持的 feature space。
+- 范围收敛为本机 CLI + 本机 Android Emulator，底层通过 `adb` / `emulator` / `uiautomator`，不做真机、远端 agent、设备云、Web/Wails UI 或内置 VLM loop。
+- P0 先把 Android 接进统一 `triton device --platform android`：doctor/list/use/wait-ready/screenshot；P1 再补 `triton app --platform android` 的 APK install、launch、terminate、open-url；P1.5/P2 再做 UIAutomator layout、host input、smoke、evidence 和 replay。
+- 计划要求 fake adb 测试先红后绿，真实 emulator smoke 覆盖 list、wait-ready、screenshot、install、open-url、wait/assert/evidence，并同步 README、`ai-cli-readable-control.md`、public emulator skill 与 memory。

docs-linhay/spaces/20260605-android-emulator-support/README.md

@@ -0,0 +1,114 @@
+# 20260605 Android Emulator Support
+
+## 背景
+
+TritonKit 当前 emulator takeover 的产品边界是本机 CLI + 本机模拟器/仿真器。iOS Simulator 与 HarmonyOS / DevEco Emulator 已经有统一 `triton device` 入口，Android Emulator 仍只停留在规划 slot。
+
+本 space 用于定义 Android Emulator 支持计划，目标是把 Android 接入同一套 agent-facing CLI 契约，而不是新增 Web/Wails UI、远端 agent、设备云或真机控制链路。
+
+## 目标
+
+1. 通过 `triton device --platform android` 发现、选择、等待和截图本机 Android Emulator。
+2. 通过 `triton app --platform android` 覆盖 Debug APK 的安装、卸载、启动、终止、deep link / intent 打开。
+3. 通过 host-side Android adapter 输出机器可读 JSON / JSONL、稳定 error code、source command、artifact path 和 recovery nextAction。
+4. 在 evidence / smoke / replay 中保留 Android artifact 与 command ledger，且明确区分 host 命令成功和业务状态通过。
+5. 为后续 Android embedded runtime 预留 Debug-only 接入边界，但首期不依赖 embedded runtime 才能完成 host-side smoke。
+
+## 非目标
+
+1. 不支持 Android 真机、USB 授权、设备农场、远端 adb server 或多机 agent。
+2. 不做 Web/Wails UI、设备大盘、队列、权限系统、多租户或中心服务。
+3. 不内置 VLM loop，不把截图理解能力放进 TritonKit core。
+4. 不承诺系统安全绕过、root-only 能力、Play Protect 绕过或生产环境采集。
+5. 不在 P0 引入 Android embedded SDK；如需 Android App 内 runtime，另行拆分 Debug-only runtime space。
+
+## 产品边界
+
+Android 首期只接本机 Android Emulator，底层工具是 Android SDK / platform-tools：
+
+| 能力域 | 底层工具 | Triton 入口 |
+| --- | --- | --- |
+| 工具诊断 | `adb version`, `emulator -version` | `triton device doctor --platform android --json` |
+| target 发现 | `adb devices -l` | `triton device list --platform android --json` |
+| ready 等待 | `adb shell getprop sys.boot_completed`, `pm path android` | `triton device wait-ready --platform android --jsonl` |
+| 截图 | `adb exec-out screencap -p` | `triton device screenshot --platform android --output <path.png> --json` |
+| app 生命周期 | `adb install`, `pm list packages`, `am start`, `am force-stop`, `pm uninstall` | `triton app ... --platform android --json` |
+| UI tree / text | `uiautomator dump`, `adb pull/cat` | `triton ax/wait/tap --platform android --json` |
+| 日志 | bounded `adb logcat` | P2 `triton logs/capture --platform android --json` |
+
+## BDD 验收
+
+### 场景一：agent 可以发现 Android Emulator
+
+- Given 本机安装 Android SDK platform-tools
+- And 至少一个 Android Emulator 通过 `adb devices -l` 可见
+- When 执行 `triton device list --platform android --json`
+- Then 输出 `ok=true`
+- And `targets[]` 使用统一 `HostDeviceTarget` envelope
+- And target id 使用 `android:<adb-serial>`
+- And 每个 target 至少包含 `platform/id/target/state/ready/source`
+
+### 场景二：没有 emulator 时返回可恢复诊断
+
+- Given 本机可执行 `adb`
+- And `adb devices -l` 没有 emulator target
+- When 执行 `triton device list --platform android --json`
+- Then 输出合法 JSON
+- And `targets=[]`
+- And `defaultTarget=null`
+- And `nextAction` 指向 `triton device doctor --platform android --json` 或启动 emulator 的文档化恢复步骤
+
+### 场景三：agent 可以等待 Android ready
+
+- Given 一个 Android Emulator 已启动但可能仍在 booting
+- When 执行 `triton device wait-ready --platform android --target <adb-serial> --timeout 60 --jsonl`
+- Then JSONL 事件持续报告 boot 状态
+- And ready 判定至少要求 `sys.boot_completed=1`
+- And timeout 时返回 `device_not_ready`，不吞掉底层 adb 错误
+
+### 场景四：agent 可以采集截图证据
+
+- Given Android Emulator 已 ready
+- When 执行 `triton device screenshot --platform android --target <adb-serial> --output <path.png> --json`
+- Then 写出 PNG artifact
+- And 输出包含 `target/sourceCommands/artifact/path/format`
+- And artifact 失败时返回 `artifact_write_failed` 或 `android_screenshot_failed`
+
+### 场景五：agent 可以安装并启动 Debug APK
+
+- Given 一个本地 Debug APK
+- And Android Emulator 已 ready
+- When 执行 `triton app install --platform android --apk <path.apk> --json`
+- Then Triton 调用 `adb install -r`
+- And 输出不把安装成功误判为业务状态成功
+
+- When 执行 `triton app open-url --platform android <url> --bundle <package> --json`
+- Then Triton 调用 `adb shell am start -a android.intent.action.VIEW -d <url> <package>`
+- And 后续必须通过 `wait/assert/screenshot/evidence` 验证业务状态
+
+### 场景六：平台能力差异稳定表达
+
+- Given Android 首期不支持某个 iOS/Harmony 专属能力
+- When agent 调用对应 CLI
+- Then 返回 `unsupported_capability`
+- And `nextAction.category=plan`
+- And 不回退到裸 `adb` 人读输出
+
+## 分期
+
+详细实施计划见 [20260605-android-emulator-support-plan-v01.md](plans/20260605-android-emulator-support-plan-v01.md)。
+
+## 交付物
+
+1. Android host adapter runtime / model / command 分层。
+2. `device`、`app`、`ax/wait/tap/screenshot` 的 schema、capabilities 和 failure code 更新。
+3. fake adb fixture 与单元测试。
+4. 至少一轮真实 Android Emulator smoke 证据。
+5. README、`docs-linhay/dev/ai-cli-readable-control.md`、public skill 与 memory 写回。
+
+## 风险
+
+1. Android SDK 安装路径差异较大，P0 必须支持显式 `--adb <path>`，同时在 doctor 中暴露 PATH 探测结果。
+2. `adb devices -l` 对 offline / unauthorized / booting 的表达不一致，parser 要先用 fake fixture 锁住。
+3. `uiautomator dump` 可能无法覆盖 Compose 语义或 WebView DOM，P1/P2 必须把 host layout 与 app 业务语义区分清楚。
+4. Android action 的坐标、密度、导航栏和软键盘会影响 replay 稳定性，首期只承诺明确 selector 或坐标，不承诺智能重定位。

docs-linhay/spaces/20260605-android-emulator-support/plans/20260605-android-emulator-support-plan-v01.md

@@ -0,0 +1,118 @@
+# 20260605 Android Emulator Support Plan v01
+
+## 成功标准
+
+1. Android Emulator 进入 `triton device --platform android` 的统一 host device contract。
+2. Android Debug APK 可通过 `triton app --platform android` 完成安装、启动、终止和 deep link smoke。
+3. 所有新能力都可被 `triton schema --json`、`triton capabilities --json`、`triton doctor --json` 发现。
+4. fake adb 测试先红后绿，真实 emulator smoke 至少覆盖 list、wait-ready、screenshot、install、open-url、evidence。
+5. 不新增 Web/Wails UI，不支持真机或远端 agent。
+
+## M0. 契约设计和红灯测试
+
+- 定义 `HostDevicePlatform.android`、`android:<serial>` target id、Android 附加字段和统一 error code。
+- 新增 fake adb fixture，覆盖 `adb devices -l`、`getprop sys.boot_completed`、`screencap`、`install`、`am start`、`uiautomator dump`。
+- 先补测试：
+  - `DeviceCrossPlatformTests` 覆盖 `doctor/list/use/wait-ready/screenshot --platform android` schema。
+  - `TKHostAdapterModelsTests` 覆盖 adb devices parser、boot completed parser、package / activity parser。
+  - `AppOpenURLFlowTests` 覆盖 Android deep link source command 与 unverified warning。
+- 红灯预期：schema 不认识 android、platform enum 不接受 android、fake adb parser 不存在。
+
+## M1. Device P0
+
+- 实现 `AndroidHostDeviceAdapter`：
+  - `doctor`: 探测 `adb`、可选 `emulator`、Android SDK 路径提示。
+  - `list`: 解析 `adb devices -l`，过滤/表达 `device/offline/unauthorized`。
+  - `use/current/resolve`: 复用统一 selector resolver，支持 alias、`android:<serial>`、raw serial、`current`。
+  - `wait-ready`: 轮询 `sys.boot_completed=1`，必要时验证 package manager 可响应。
+  - `screenshot`: `adb exec-out screencap -p` 写本地 PNG。
+- 输出统一 `HostDeviceTarget` / `HostDeviceArtifactOutput`，平台差异放进 Android-specific metadata。
+- 错误码：`android_adb_not_found`、`android_target_offline`、`android_target_unauthorized`、`device_not_ready`、`android_screenshot_failed`、`host_command_timeout`。
+
+## M2. App P1
+
+- `triton app list/info/install/uninstall/launch/terminate/open-url --platform android`：
+  - install: `adb install -r <apk>`
+  - uninstall: `adb uninstall <package>`
+  - launch: `monkey -p <package> 1` 或 schema 明确要求 package/activity 时用 `am start`
+  - terminate: `am force-stop <package>`
+  - open-url: `am start -a android.intent.action.VIEW -d <url> <package>`
+  - info/list: `pm list packages`、`dumpsys package <package>` 的 bounded summary
+- app action 返回 host action envelope，不能把 adb 成功当作业务 pass。
+- 补 `triton plan open-url --platform android` 或在现有 open-url plan 中支持 `--device <android-alias>` 的推荐链路。
+
+## M3. Observe / Action P1.5
+
+- `triton ax --platform android --output <path.json>`：
+  - 执行 `uiautomator dump /sdcard/window.xml`
+  - `adb exec-out cat /sdcard/window.xml` 或 `adb pull`
+  - 转为轻量 JSON artifact，不内联敏感完整 UI 到 stdout
+- `triton wait --platform android --text <text>` 轮询 UIAutomator tree。
+- `triton tap --platform android <text>` 从 bounds 取中心点后 `adb shell input tap x y`。
+- `triton type/paste/press/swipe --platform android` 只接稳定 host input，所有输入动作标记 `runtimeScope=host-android`。
+
+## M4. Smoke / Evidence P2
+
+- 新增 `triton smoke android`：
+  - device wait-ready
+  - app install 可选
+  - app open-url 或 launch
+  - wait text
+  - 可选 tap text
+  - screenshot
+  - evidence manifest
+- evidence artifact taxonomy 新增或复用：
+  - `android.screenshot`
+  - `android.layout`
+  - `android.logcat`
+  - `host.android-action`
+  - `host.android-device-list`
+- `triton capture/evidence/replay` 读取 Android command ledger，保留 source command、elapsed、target、artifact path、redaction hint。
+
+## M5. 真实 Emulator 验收
+
+- 准备一个最小 Android Debug APK fixture 或使用现有可公开示例 APK。
+- 真实命令链：
+
+```bash
+triton device doctor --platform android --json
+triton device list --platform android --json
+triton device alias set android-a --platform android --target <adb-serial> --json
+triton device wait-ready --device android-a --timeout 60 --jsonl
+triton device screenshot --device android-a --output /tmp/triton-android-smoke.png --json
+triton app install --platform android --device android-a --apk <path.apk> --json
+triton app open-url --platform android --device android-a "example://smoke" --bundle <package> --json
+triton wait --platform android --device android-a --text "<expected-text>" --timeout 20 --json
+triton smoke android --device android-a --bundle <package> --open-url "example://smoke" --wait-text "<expected-text>" --screenshot /tmp/triton-android-smoke.png --evidence /tmp/triton-android.tritonevidence --json
+```
+
+- 截图按规范归档到 `docs-linhay/spaces/20260605-android-emulator-support/screenshots/<YYYYMMDD>/android/`。
+
+## M6. 文档、public skill 和门禁
+
+- 更新：
+  - `README.md`
+  - `docs-linhay/dev/ai-cli-readable-control.md`
+  - `docs-linhay/dev/20260520-simulator-takeover-architecture.md`
+  - `TritonKit.skills/tritonkit-emulator-cli-takeover/SKILL.md`
+  - `docs-linhay/memory/YYYY-MM-DD.md`
+- 门禁：
+
+```bash
+swift test --package-path CLI --scratch-path .build/cli --filter DeviceCrossPlatformTests
+swift test --package-path CLI --scratch-path .build/cli --filter TKHostAdapterModelsTests
+swift test --package-path CLI --scratch-path .build/cli --filter AppOpenURLFlowTests
+docs-linhay/scripts/check-docs.sh
+docs-linhay/scripts/verify.sh --local
+```
+
+## 拆分建议
+
+1. 第一 PR：M0 + M1，只做 device P0 和 fake adb。
+2. 第二 PR：M2，app lifecycle 与 deep link。
+3. 第三 PR：M3 + M4，UIAutomator observe/action、smoke、evidence。
+4. 第四 PR：真实 emulator fixture、README / public skill 对外使用口径、release 门禁补齐。
+
+## 暂不沉淀为 AGENTS 规则
+
+本计划是 Android adapter 的 feature-level 规划，不新增 repo-wide 长期规则。当前 AGENTS 已包含 emulator takeover 边界和 Android Emulator 范围，暂不需要修改。