dsh-apk-vm 0.0.0-stage → 0.3.13

package/DEMO.md

@@ -0,0 +1,85 @@
+# Demo & verification script
+
+This file is the reproducible demo script behind `docs/demo.gif` and the screenshots referenced
+in [README.md](README.md). No media is checked in yet; the commands below produce the real
+artifacts on a Windows reference host (AEHD + AOSP Android 14). Do not invent numbers — copy them
+from the outputs.
+
+## Install (local link)
+
+```powershell
+# from the DSH profile that can use plugin_manager
+plugin_manager install_bundle target=<path-to-repo>
+# or, if the bundle is already linked:
+plugin_manager set_plugin target=include:dsh-apk-vm enabled=true
+```
+
+Refresh the DSH page after installing the client half.
+
+## 30-second demo flow
+
+1. Open **APK Virtual Machine** in the sidebar.
+2. Expand **Environment** — show SDK/adb/emulator/system image/AVD/acceleration all green.
+   The "Create AVD" action is offered when the image exists but the AVD does not.
+3. Press **Start VM** (or just open the panel with `autoStart` on). Show the measured boot label
+   (`quick N s` / `cold N s`).
+4. **Upload APK** or drag a file onto the panel. The app installs and launches; the phone frame
+   switches to the H.264 canvas.
+5. Expand **Rooted debug**: run `id -u; getprop ro.build.version.release`; click **UI tree**,
+   **Perf**, **Record 5s**, **Rotate**, **Screenshot**.
+6. Interact with the phone frame, then note the live `FPS` reading in the header. A static home
+   screen has a low frame rate because scrcpy only emits frames on change; use an animated app or
+   a scroll gesture for the 60 fps path.
+
+Useful companion commands (same origin, local only):
+
+```powershell
+$base = 'http://127.0.0.1:<dsh-port>'
+Invoke-RestMethod "$base/apk-vm/setup" | ConvertTo-Json -Depth 6
+Invoke-RestMethod "$base/apk-vm/avds"
+Invoke-RestMethod "$base/apk-vm/debug/info"
+Invoke-RestMethod "$base/apk-vm/debug/perf"
+Invoke-RestMethod "$base/apk-vm/debug/ui" | Select-Object nodes,bytes,rotation
+```
+
+Raw APK upload (500 MiB limit, ZIP magic checked, same-origin route):
+
+```powershell
+curl.exe -sS -X POST -H "x-apk-name: anim60.apk" `
+  --data-binary "@apk-vm-preview\spike\android\anim60.apk" `
+  "$base/apk-vm/upload"
+```
+
+60 fps stream smoke test (no browser needed; counts H.264 packets):
+
+```powershell
+cd apk-vm-preview
+node spike/android/ws-stream-test.mjs
+```
+
+Expected on the reference host with the 60 Hz test app in the foreground: ~59 fps raw packets,
+first `init` in about 1 s, `width`/`height` matching the current orientation.
+
+## Recording the media
+
+- `docs/demo.gif`: record the flow above at ~1280 px width; trim to 20–30 s; keep file < 8 MiB.
+- `docs/screenshot-panel.png`: main panel with the Environment + APK cards and the phone frame.
+- `docs/screenshot-setup.png`: expanded Environment card on a green host.
+- `docs/screenshot-debug.png`: expanded Rooted debug card with `ui_dump` / `perf` / record output.
+
+## Acceptance checklist
+
+- [ ] Environment card reports Ready on a host with SDK + image + AVD + acceleration.
+- [ ] Upload and drag-drop both install and launch an APK.
+- [ ] Phone frame uses `<canvas>` (H.264) when WebCodecs is available; PNG fallback otherwise.
+- [ ] Header FPS changes when the guest screen animates.
+- [ ] Rooted debug shell returns `uid=0(root)`; rotate/ui_dump/perf/record/screenshot work.
+- [ ] Cross-origin request to `/apk-vm/*` is rejected (`403`).
+- [ ] Quick boot measured under 30 s after the snapshot exists.
+
+## Notes
+
+- Windows x64 is the only end-to-end verified host so far. macOS/Linux SDK discovery is covered by
+  `spike/setup-smoke.mjs` but the emulator path is not end-to-end tested upstream.
+- Emulator integration tests require nested virtualization; keep them on a local Windows machine
+  (see `.github/workflows/ci.yml` for the headless CI checks).

package/DESIGN.md

@@ -0,0 +1,335 @@
+# 设计方案：DSH 侧边栏 APK 虚拟机预览插件
+
+> 目标：在 DeepSeek Harness 的侧边栏里，以「打开一台虚拟机」的方式预览 APK ——
+> 启动开源 Android 虚拟机、安装 APK、把 VM 画面流进侧边栏面板、把鼠标/键盘输入送回 VM。
+
+## 1. 需求与约束
+
+| 项 | 内容 |
+| --- | --- |
+| 入口 | 侧边栏（`sidebar.panellist`）新增「APK 虚拟机」图标；点击后主区（`main`，key `apk-vm`）渲染完整面板 |
+| 体验 | 像虚拟机控制台：开机/关机、状态、屏幕、输入、安装 APK、日志 |
+| 运行环境 | Windows 10/11 x64；无管理员权限；**不允许使用 MuMu Player**；需从 GitHub 选择开源模拟器 |
+| 宿主能力 | 无 Hyper-V/WHPX/AEHD/KVM 驱动；只有用户态虚拟化（QEMU TCG）可用 |
+| 插件规范 | DSH 静态插件：Host 半 `apply(ctx)` + `dsh.client` 声明的浏览器 bundle；UI 只用主题 token、locale、slot |
+
+## 2. 开源框架选型（GitHub / AOSP）
+
+通过 GitHub/AOSP 调研了以下候选：
+
+| 候选 | 许可证 | 结论 |
+| --- | --- | --- |
+| **AOSP Android Emulator**（`aosp-mirror/platform_external_qemu` + official `emulator` / `system-images`） | Apache-2.0 | **主选 VM**。官方开源模拟器，adb 生态完整，可无窗口、可指定 AVD |
+| **Genymobile/scrcpy** v5.0.1（仅 scrcpy-server，自研 headless relay） | Apache-2.0 | **主选串流/控制框架**。H.264 低延迟、触摸/按键/滚轮/文本控制协议完善，可无桌面客户端 |
+| Android-x86 / Bliss OS + QEMU | GPL/Apache-2.0 | 备选：无硬件虚拟化时的 QEMU TCG 路径；本机无法从网络取得 ISO（SourceForge/OSDN/Archive.org 均被阻断） |
+| LineageOS-TV-x86（GitHub Releases） | Apache-2.0 | 备选：GitHub 上可下载的 x86_64 Android 21 OTA，但需要 payload2iso/recovery，不能直接 boot |
+| ws-scrcpy | MIT | 备选：开箱即用的 web 串流，但需要独立 Node 服务 + iframe，和 DSH 主题/插件规范不符 |
+| Waydroid / redroid / Anbox | GPL/Apache-2.0 | 仅 Linux；Windows 无内核 binder/ashmem，排除 |
+| Genymotion / Appetize / Corellium | 商业 | 非开源，排除 |
+| ARChon | 旧版 Apache-2.0 | Android 4.4 Chrome runtime，APK 兼容性差，排除 |
+
+**最终栈**：AOSP Android Emulator（VM） + scrcpy-server（画面/控制协议） + adb（安装/启动/截图/输入）。
+无 npm 运行时依赖；Host 半只使用 Node 内置模块。
+
+## 3. 总体架构
+
+```
+┌──────────────────────────── DSH Web UI ─────────────────────────────┐
+│ sidebar.panellist [apk-vm]  ──click──▶  main[apk-vm]                │
+│                                            │                        │
+│                                  Client half (client.js)            │
+│                 ┌──────────────────────────┼──────────────────┐      │
+│                 │ 工具栏 / APK 列表 / 手机框 │ 2s state, 500ms frame │
+│                 └──────────────────────────┼──────────────────┘      │
+└────────────────────────────────────────────┼────────────────────────┘
+                                             │ same-origin HTTP (fetch)
+┌────────────────────────────────────────────┼────────────────────────┐
+│ DSH Host (desktop process)                 ▼                        │
+│  index.js  ── /apk-vm/{state,apks,vm,install,frame,input}           │
+│     │                                                               │
+│     ├─ lib/android.js   AndroidVm: AVD lifecycle / adb / aapt2      │
+│     │      • spawn emulator (open-source AOSP) or attach serial     │
+│     │      • install -r, am start, wm size, screencap -p            │
+│     │      • input tap/swipe/keyevent/text                          │
+│     │                                                               │
+│     └─ lib/scrcpy.js    ScrcpySession (可选 H.264 快通道)            │
+│            • push scrcpy-server 5.0.1, adb forward, app_process      │
+│            • video demux + SPS/PPS → avcC + control messages         │
+└─────────────────────────────────────────────────────────────────────┘
+                                             │ adb
+                                   ┌─────────▼─────────┐
+                                   │ Android VM (AVD)   │
+                                   │  system.img + APK  │
+                                   └───────────────────┘
+```
+
+### 状态机（Host 侧 AndroidVm）
+
+`stopped → starting → booting → ready → stopped`
+失败进入 `error`（附带 `error` 与有界 `logTail`）；`start()` 幂等，先 attach 已在线 adb
+设备，再考虑 `adb connect <serial>`，最后才按配置 spawn AVD；`stop()` 只杀自己 spawn 的
+子进程，并清理 adb 连接。
+
+## 4. DSH 插件落点
+
+- **Host 半**（`index.js`）：`export function apply(ctx, config)`；`ctx.inject(['webServer'], host => host.effect(() => mountRoutes(host.webServer)))`。
+  路由注册在 `webServer.register({ kind: 'exact', path })`；返回 disposer，插件卸载时清理
+  route 与 `AndroidVm`。不使用任何未公开 API。
+- **Client 半**（`client.js`）：`window.__ModuleLoader__.load({ id, factory(require) })`，
+  只 `require('react')`，`React.createElement` 手写。`apply(ctx)` 中：
+  - `ctx.locale.register('apk-vm', { en, zh })` + `bind`；
+  - `ctx.slots.inject('main', () => ctx.slots.register({ name:'main', key:'apk-vm', locale:'apk-vm' }, ApkVmPage))`；
+  - `ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({ name:'sidebar.panellist', id:'apk-vm', order:30, label:()=>t('nav.label'), locale:'apk-vm' }, PhoneIcon))`。
+- **显示元数据**：`locale/en.json`、`locale/zh.json` 提供 `meta.title/meta.description`，
+  `icon.svg` 为原创 currentColor 手机图标；`exports` 暴露 `./locale/*.json` 与 `./icon`。
+- **主题**：仅使用 `--dsw-alias-bg-* / border-* / label-* / brand-primary / state-*` token；
+  手机框等“内容物”允许多一点自由色，但面板容器/按钮全部走 token。
+
+## 4.5 与 dsh-better-sidebar 的兼容层
+
+`dsh-better-sidebar`（MIT，GitHub）是社区侧栏工作台，它在**客户端**提供 `ctx.betterSidebar`
+服务（`registerTab` / `registerFileViewer` / `openTab` / `getSnapshot`），并把这些 tab
+类型投影到 DSH 原生右侧栏（`sidebar.right.pane.tab`）与它自己的底部 workbench。
+
+兼容策略（不 fork、不硬依赖、不操作其 DOM）：
+
+1. **可选注入**：在 `apply(ctx)` 末尾使用 `ctx.inject(['betterSidebar'], sub => …)`，
+   等到服务出现才注册；没有该插件的 DSH 上行为完全不变（`main` 面板 + 左侧图标照常）。
+2. **注册 tab**：`sub.betterSidebar.registerTab({ id:'apk-vm:preview', title, description,
+   icon, order:60, single:true, component })`；component 复用同一 `ApkVmPage`，标记
+   `embedded:true` 以切换窄栏布局（列表在上、手机框更小）。
+3. **打开入口**：主面板 header 增加「在侧栏打开」（仅服务存在时显示），调用
+   `openTab({ type:'apk-vm:preview', target:'right' })`；无活动会话时给出明确提示，
+   因为 better-sidebar 的右侧栏按会话隔离。
+4. **生命周期**：注册放入 `sub.effect(...)`，服务卸载/HMR 时自动反注册；组件通过
+   `visible` prop 暂停不可见 tab 的帧轮询，避免后台开销。
+5. **验证**：本机 live slot tree 中 `sidebar.right.pane.tab` 出现 occupant
+   `dsh-better-sidebar:apk-vm:preview`（active）；另有 `spike/ui-better-sidebar-smoke.cjs`
+   覆盖描述符、本地化、dispose、服务已存在路径、服务缺失容错。
+
+## 4.6 开机加速设计（目标 <30s）
+
+冷启动 Android 的时间由 CPU 虚拟化决定，因此按“硬件加速 → GPU → 快照 → 预热”四层解决：
+
+1. **CPU 加速探测**：`lib/android.js` 调用 SDK 的 `emulator-check accel`，AEHD/WHPX/KVM/
+   HAXM/HVF 可用时不传 `-accel off`（emulator 自动使用硬件加速）；仅在确实没有 hypervisor
+   时才退回 `-accel off`（此路径 x86_64 不可用，会显式报错而不是静默卡住）。
+2. **GPU host**：默认 `-gpu host`（RTX 5070 Ti），替代 SwiftShader 软件渲染；无 GPU 的
+   headless 主机可用 `gpuMode: swiftshader_indirect` 回退。
+3. **Quick-boot 快照**：首次成功冷启动后执行 `adb emu avd snapshot save default_boot`；
+   之后的启动传 `-snapshot default_boot`，直接恢复内存态（通常数秒）。快照有效性以
+   `snapshot.pb` 为准，失败 TCG 运行留下的 `ram.img` 不会被误当快照；同时修复了“残留
+   offline adb 设备把启动卡在 attach 路径”的问题。
+4. **预热/自动启动**：`prewarm: true` 在插件激活 3s 后后台启动 VM；`autoStart: true`
+   在第一次 `state/frame` 请求时启动。用户打开面板时 VM 通常已就绪，主观“打开即可见”。
+5. **可观测性**：`/apk-vm/state.vm` 暴露 `bootKind`（cold/snapshot/attach）、`bootMs`、
+   `accel`、`gpuMode`、`snapshotAvailable`；面板状态 pill 显示 `cold Ns` / `quick Ns`，
+   后续验收可直接读取实测值。
+6. **帧率（双路径）**：默认走 **scrcpy H.264 + WebCodecs**（见 4.8），最高 **60 fps**；
+   PNG 回退由 `/apk-vm/stream {fps:1..10}` 控制，`/apk-vm/state.stream` 同时返回
+   `fps / hostFps / h264 {active, fps, clients, maxFps, width, height}`；header 显示实测 FPS。
+
+本机实测：重启释放 AMD-V 后 AEHD 生效；修复 AVD 的 `fastboot.forceColdBoot/forceFastBoot`
+与 `snapshot.present` 后，快照真正参与启动。首次冷启动 **29.5s**（含重建 AVD 配置后的
+新快照），快照重存后再启动 **8.4s**（日志 `Loading snapshot 'default_boot'`、
+`Boot completed in 8371 ms`、`bootKind: snapshot`），已达标。
+
+## 4.7 Root / ADB / 调试接口设计
+
+目标：模拟器默认 root、adb 直接可用，并向 DSH 暴露底层调试能力。
+
+1. **默认 root**：镜像本身是 `userdebug`（`ro.debuggable=1`、`ro.adb.secure=0`，无 adb 授权
+   弹窗）。每次启动 ready 后 Host 自动执行 `adb root`，等待 adbd 重启并校验
+   `uid=0(root)`；`--prop` 只接受 `qemu.*`，因此不用命令行属性伪造 root，而是启动后应用
+   并写入 quick-boot 快照，后续快照启动再幂等补一次 `adb root`。
+2. **调试友好配置**：启用 adb/开发者设置，关闭安装校验（`verifier_verify_adb_installs`、
+   `package_verifier_enable`），`persist.sys.usb.config=adb`、`persist.sys.root_access=3`。
+3. **机内工具包**：`/data/local/tmp/dsh/debug.sh` + README（755）：
+   `info / logs / prop / pkgs / install / help`，用户可在 root shell 里直接用。
+4. **DSH 调试接口**：
+   - HTTP：`/apk-vm/debug/{info,shell,logcat,prop,packages,root,push,pull,reboot,action,rotate,ui,record,perf,screenshot}`，
+     参数/输出有上限，push/pull 路径受限；
+   - Agent Tool：`apk_vm`（`ctx.tools.register`，全局可见），动作覆盖 info/shell/logcat/
+     getprop/setprop/packages/install/push/pull/reboot/root/force_stop/clear_data/uninstall/
+     rotate/ui_dump/record/perf/screenshot，与 HTTP/面板共用同一 Host 方法；
+   - UI：面板新增「Root 调试」卡（root/shell 徽章、Android/API/ABI、命令输入、Logcat/
+     Props/Root/UI 树/性能/录屏/旋转按钮、输出控制台），并支持截图下载。
+5. **错误可见性**：无硬件加速时 fail-fast 报错，不再 20 分钟“启动中”；工具注册 schema
+   错误会显式抛出（本次已修正为严格 JSON Schema）。
+
+## 4.8 60fps H.264 串流设计
+
+目标：把 PNG 轮询（~1 fps）替换为可用的 60fps 实时画面，同时保留无 WebCodecs 环境的回退。
+
+1. **链路**：浏览器 `<canvas>` ← `VideoDecoder` ← `/apk-vm/ws`（无依赖 RFC6455 服务端，
+   `lib/ws.js`）← `annexbToAvcc` 分片 ← `ScrcpyVideoDemuxer` ← scrcpy-server 5.0.1（
+   `lib/vendor/scrcpy-server-v5.0.1.jar`，启动时 adb push + forward + `app_process`）。
+2. **参数**：`maxSize=960`（540×960，面板足够清晰且软件解码可达 ~60fps）、
+   `videoBitRate=6_000_000`、`maxFps=60`；scrcpy 只在屏幕变化时出帧，静态桌面 FPS 低
+   是正常语义，不等于串流故障。
+3. **协议**：文本 `init` 一次（`codec/codecString/description(avcC base64)/width/height/
+   maxFps/bitrate`），随后二进制帧 `[0]=1, [1]=keyFlag, [2..9]=pts(LE int64), [10..]=AVCC`。
+4. **关键帧**：客户端配置解码器后先丢 delta，等首个 keyframe；已运行的会话接到新客户端时
+   发送 `RESET_VIDEO`（scrcpy control type 17）请求新 keyframe，避免二次打开面板黑屏。
+5. **会话管理**：一个 scrcpy 会话广播给多个 WS 客户端；客户端断开后 15s 无连接自动停止
+   会话（释放编码/端口），VM 不停止；VM stop/restart/插件 dispose 时主动停流。
+6. **回退**：无 `WebSocket`/`VideoDecoder`/`EncodedVideoChunk`、初始化失败、连续 3 次连接
+   失败、或面板不可见时，自动退回 PNG 轮询；输入仍走 `/apk-vm/input`（不受串流影响）。
+7. **旋转/编码器重置**：scrcpy `session` 包更新宽高时 Host 重发 `init`，客户端重建
+   `VideoDecoder`、更新画布尺寸与输入坐标映射，避免横竖屏拉伸/错位。
+8. **实测**（本机 60Hz 动画测试 APK `test.dshanim`）：
+   - `/apk-vm/ws` 原始包速率 **59.3fps**（425–474 包/8s；首 init 6–1000ms）；
+   - headless Edge 软件 WebCodecs 解码 **318 帧/6.32s = 50.3fps**（扣除启动约 57fps），
+     0 协议错误；
+   - 第二个客户端在 4s 内收到 234 包（~58.5fps）+ 1 个 keyframe（RESET_VIDEO 生效）；
+   - 视觉 GPU 加速的 DSH 窗口预期更接近 60fps；headless 软件解码是下限。
+
+
+## 4.9 开源化 / 环境自检 / 上传与安全
+
+为“别人能装得上、敢用、可维护”补齐的工程能力：
+
+1. **环境自检（lib/setup.js）**：跨平台探测 SDK 根目录、`adb`、`emulator`、
+   `sdkmanager`/`avdmanager`（Windows 下 `.bat` 通过 argv-only `cmd.exe` trampoline）、
+   system image、AVD、`emulator-check accel`（AEHD/WHPX/KVM/HAXM/HVF）以及 JDK
+   （`JAVA_HOME` 未设置时自动寻找并仅注入子进程环境）。只读，不自动下载。
+   `GET /apk-vm/setup` 返回 `ok/missing/actions/hypervisorNotes`；`POST /apk-vm/setup`
+   支持 `refresh`、`create-avd`，以及仅在 `allowSetupDownloads: true` 时允许的
+   `install-image`（~1 GB，显式动作）。
+2. **上传 APK**：`POST /apk-vm/upload` 接收 raw APK，`x-apk-name` 传文件名，500 MiB 上限，
+   检查 ZIP/APK magic，写入 OS 临时目录后走与路径安装相同的 `installApk`；面板提供上传
+   按钮与拖放覆盖层，插件卸载时清理临时目录。
+3. **安全边界**：所有 `/apk-vm/*` HTTP 路由与 `/apk-vm/ws` 升级校验 `Origin`/`Host` 与
+   `Sec-Fetch-Site`，跨站请求 403/destroy；JSON body ≤64 KiB；上传 ≤500 MiB；调试输出/命令
+   长度有界；push/pull 路径限制；所有子进程 argv 数组，不拼接 shell 字符串。
+4. **多 AVD**：`GET /apk-vm/avds` 列出 emulator 可见 AVD；`POST /apk-vm/avd` 停止当前 VM、
+   切换 `AndroidVm.avdName`、清空快照探测并自动重启。环境卡在多于一个 AVD 时显示切换器。
+5. **调试接口扩展**：`rotate`（锁定 user_rotation）、`uiDump`（UIAutomator XML）、
+   `screenRecord`（5s MP4 拉回 Host 临时目录）、`perfSnapshot`（loadavg/meminfo/cpuinfo）、
+   `screenshot`（PNG 附件）；Agent `apk_vm` 同步新增 action。
+6. **开源工程**：README（含中文简介/Quickstart/故障排查/安全说明）、Apache-2.0 LICENSE、
+   NOTICE（scrcpy/AOSP 归属）、CONTRIBUTING/SECURITY、GitHub Actions（Node 24，headless
+   检查 + mock 测试）、Issue/PR 模板；二进制 scrcpy JAR 随包，系统镜像不随包分发。
+7. **跨平台**：`candidateSdkRoots` 增加 Linux/macOS 常见路径；`resolveEmulatorPath` 支持
+   SDK 目录与 PATH；加速错误提示按 win32/darwin/linux 区分。Windows x64 为当前端到端验证平台。
+
+
+## 4.10 多 Agent / 多虚拟机实例
+
+问题：DSH 同一 profile 下多个 Agent 会共享一个插件进程，但 `apk_vm` 工具、面板、adb 端口、
+AVD、快照、scrcpy 会话原本都是单例；两个 Agent 同时 install/input 会互相踩状态。
+
+设计：
+1. **实例模型**：默认实例继续由 `index.js` 持有（UI/兼容路径不变）；额外实例由
+   `lib/instances.js` 的 `InstanceManager` 管理。每个 `ExtraVmInstance` 拥有独立：
+   AVD（`<base>_<id>`）、emulator console port（基准 5558 + 2*序号，自动找空闲）、
+   独立 userdata/snapshot（每个 AVD 自己的 `default_boot`）、`AndroidVm`、PNG frame 缓存、
+   lastApk/install 锁。
+2. **AVD 创建**：首次创建实例时用 `lib/setup.js` 的 `avdmanager create avd` 建 AVD，并
+   写入 `fastboot.forceColdBoot=no / forceFastBoot=yes / snapshot.present=true`；首次冷启动
+   后保存该实例自己的 quick-boot 快照，后续 6–8s 启动。
+3. **Agent 归属**：`apk_vm` 在 `exec.agent.session` 上取稳定 key；第一个 Agent 使用默认
+   实例，后续 Agent 自动创建隔离实例（受 `maxInstances` 限制）并在首次真实操作时启动。
+   也支持显式 `instance` 参数、`list_instances/create_instance/destroy_instance/start/stop`。
+4. **HTTP 命名空间**：`GET/POST /apk-vm/instances` + 每实例
+   `/apk-vm/instances/<id>/{state,frame,vm,input,install,upload,debug/*}`；额外实例的
+   debug 路径与默认实例同构（shell/logcat/prop/packages/root/rotate/ui/record/perf/
+   screenshot/push/pull/reboot/action）。精确路由在实例创建时注册、销毁时释放。
+5. **视频**：默认实例与每个额外实例各有独立 H.264/WebCodecs 流（`lib/video-stream.js` 的
+   `ScrcpyStream`）：独立 scrcpy server、空闲端口、init/AVCC/关键帧、旋转重发、15s 无客户端
+   自动停流。额外 AVD 固定 720×1280 预览分辨率，避免 pixel_5 1080×2340 + 第二路编码器导致的
+   GPU 卡顿；WebCodecs 不可用时回退各自 PNG frame。
+6. **面板**：header 增加实例选择器，环境卡/实例列表；支持 New VM / Destroy VM；切换实例时
+   重置 frame/解码器并重载该实例 state。
+7. **实测**：默认 `emulator-5558` 与额外 `emulator-5560` 同时 ready/root；额外实例冷启动
+   约 27.5s、快照后 quick boot ~6.5s；额外实例 PNG frame（~1.29MB）和 root shell 验证成功，
+   默认实例保持 ready。
+
+
+## 5. 关键接口契约
+
+`GET /apk-vm/state` →
+```json
+{ "ok": true,
+  "vm": { "state": "ready", "serial": "emulator-5558", "avd": "dsh_apk",
+          "bootMs": 95000, "error": null, "logTail": ["..."] },
+  "screen": { "width": 720, "height": 1280 },
+  "apk": { "path": "...", "packageName": "com.example.app", "label": "Demo", "launched": true },
+  "installing": false, "roots": ["<workspace>"] }
+```
+`GET /apk-vm/frame?t=<ms>` → `image/png`（`Cache-Control: no-store`；VM 未 ready 时 409 + JSON）；
+`POST /apk-vm/input` 支持 `tap {x,y}` / `swipe {x1,y1,x2,y2,duration}` /
+`key {key:'home'|'back'|'recents'|'power'|'enter'}` / `text {text}`；
+`POST /apk-vm/install {path}` 先 `aapt2 dump badging` 解析 package/launcher，再
+`adb install -r` + `am start`，返回安装/启动结果。
+
+## 6. 安全与稳健性
+
+- **无 shell 字符串拼接**：所有 adb/emulator 调用用 `child_process.spawn(exe, argv[])`；
+  文件路径仅通过参数传递，避免命令注入。
+- **输入边界**：JSON body ≤ 64 KiB；上传 ≤ 500 MiB 且校验 ZIP/APK magic；坐标/时长做数值校验；
+  text ≤ 4096 字符；APK 路径必须存在且以 `.apk` 结尾，相对路径只在配置 roots 下解析；
+  debug push/pull 限制远程路径，pull 本地限制在 roots+临时目录。
+- **同源边界**：所有 `/apk-vm/*` 路由和 `/apk-vm/ws` 升级校验 Origin/Host 与 Sec-Fetch-Site，
+  跨站请求返回 403（WS 直接断 socket）。
+- **资源回收**：所有路由注册在 `ctx.effect` 中；插件卸载时 dispose `AndroidVm`，
+  杀自己 spawn 的 emulator 进程树，清理 frame 缓存、scrcpy 会话与上传临时目录。
+- **失败可见**：VM 启动/安装/输入失败返回结构化 `{ok:false,error}`；面板展示
+  `logTail`（有界 200 行）而不是吞错。
+- **本地路由面**：DTO 只服务同源 Web UI，绑定在本机 DSH web 端口；不监听公网。
+
+## 7. 验证与已知限制
+
+已验证（本机）：
+- 插件安装 `application: applied`；`sidebar.panellist` 与 `main` 两个 slot 均 active；
+- Host 路由真实 HTTP 调通（state/apks/frame 409/stop/start 集成路径）；
+- APK 发现可用（发现工作区 sample.apk 与 Downloads 下 APK）；`aapt2` 解析通过；
+- 新功能实测：`GET /apk-vm/setup`（ok/sdk/accel）、`GET /apk-vm/avds`（dsh_apk/dsh_apk_arm/ss_test）、
+  `POST /apk-vm/upload`（anim60.apk 安装启动成功）、`debug/rotate`（rotation 1/0）、
+  `debug/ui`（节点数）、`debug/perf`（loadavg/mem）、`debug/record`（2s MP4 ~0.5–1MB）、
+  `debug/screenshot`（PNG 附件）、跨站请求 403、非法 upload 400、install-image 未授权 403；
+- 多实例实测：默认 `emulator-5558` + 额外 `emulator-5560`（`dsh_apk_test1`）同时 ready/root；
+  额外实例独立上传安装 anim60.apk、H.264 init `540×960`（412 包/10s，60Hz 动画）、PNG frame
+  与 root shell 正常，默认实例保持 ready；额外实例 quick boot 约 10.6s，销毁后仅剩 default。
+- 环境模块 `lib/setup.js`：`spike/setup-smoke.mjs` 30/30；真实探测 294ms，AEHD 可用；
+- 开源工程：Apache-2.0 LICENSE/NOTICE、CONTRIBUTING/SECURITY、GitHub Actions（Node 24 +
+  headless 测试）、Issue/PR 模板；README/DEMO 为 UTF-8。
+- Client bundle 136/136 沙箱断言通过；Host/backend 模块 `node --check` 通过；
+- scrcpy relay 160 条协议断言（含假设备端到端）通过；并已真实接入 `/apk-vm/ws`：
+  60Hz 动画 APK 下原始包速率 **59.3fps**（425–474 包/8s），headless Edge WebCodecs
+  解码 **318 帧/6.32s = 50.3fps**（扣除启动 ~57fps、0 错误）；晚加入的第二个客户端
+  4s 收到 234 包（~58.5fps）+ RESET_VIDEO keyframe。
+- Fast-boot 启动计划单测通过：有快照时 argv 含 `-snapshot default_boot -gpu host` 且不含
+  `-accel off`；无 hypervisor 的冷启动计划才加 `-accel off`；关闭 quickBoot 时含
+  `-no-snapshot`；安装后的 profile 配置 live 生效（`bootKind/accel/gpu/snapshotAvailable`
+  可在 `/apk-vm/state` 读到，prewarm 已按新计划拉起 host 侧 emulator）。
+- 开机实测：AEHD 重启后生效；修复 AVD `fastboot.forceColdBoot/forceFastBoot` 与
+  `snapshot.present` 后，首次冷启动 **29.5s**、快照重存后的 quick boot **8.4s**
+  （`bootKind: snapshot`、`Boot completed in 8371 ms`），30s 目标达成。
+- Root/调试实测：`adb shell id` = `uid=0(root)`；`root:true/prepared:true`；工具包
+  `/data/local/tmp/dsh/debug.sh` 已安装；`/debug/info|shell|logcat|prop|packages` 与
+  snapshot save 全部实测 `ok`；Agent Tool `apk_vm` 已注册（DSH 推送了更新后的 Tool schema）。
+- 一个 AVD 配置修正：快照首次加载报 “different AVD configuration” 后，重存 snapshot 即恢复
+  秒级 quick boot；快照有效性仍以 `snapshot.pb` 判断。
+
+本机限制 / 备注：
+- Windows 组件存储损坏（DISM 14098）导致 WHPX 备选路径不可用，当前 AEHD 为唯一加速路径；
+- 为使 AEHD 获得 AMD-V，MuMuVMMDrv 已改为 Manual 并停止（MuMu 数据未动；恢复需改回
+  system 并重启）；
+- 模拟器 `-prop` 只接受 `qemu.*`，因此 root 属性不走命令行，而是启动后 `adb root` +
+  机内配置并写入快照；若要真正修改 build.prop，需要 `-writable-system` 冷启动后 remount，
+  当前未启用（会改变快照配置）。
+
+
+## 8. 演进路线
+
+1. 已落地：scrcpy H.264 → `/apk-vm/ws` → `VideoDecoder` canvas（60fps）、多客户端 keyframe、
+   旋转重配；后续可加 scrcpy 控制通道（触摸/键盘直连）进一步降低输入延迟；
+2. 物理 adb 设备的运行时切换（当前支持配置 `serial` 附加；UI/路由切换待补）；
+3. 音频转发（scrcpy audio socket + WebAudio）与录屏回放/自动断言；
+4. 预置 ATD/更小镜像与冷启动压测（当前以 cold boot → snapshot → quick-boot 为主，目标是
+   首次冷启动也压到 30s 内；ATD 镜像可作为可选 `avdName`）；
+5. 用 `-writable-system` + `adb remount` 真正修改 `/system/build.prop`（把 adbd 默认 root、
+   `persist.sys.usb.config` 写进镜像），并重新生成基准快照；
+6. QEMU + Android-x86 后端适配器（无硬件虚拟化的 Windows/Linux 通用方案）与静态 APK
+   预览（不启 VM 先看图标/manifest/权限）。

package/LICENSE

@@ -0,0 +1,204 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (C) 2018 Genymobile
+   Copyright (C) 2018-2026 Romain Vimont
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+