dsh-apk-vm 0.3.13 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.4.1
+
+Privacy cleanup for the published proof assets.
+
+### Changed
+
+- Cropped `docs/screenshot-sidebar.png` to the plugin panel only (removes the center session
+  area and workspace label; the APK paths were already redacted).
+- Removed host account names from `docs/LINUX-E2E.md`; the document now describes the KVM
+  group requirement without identifying accounts.
+
+## 0.4.0
+
+Substantive feature release: inspection, replay, package bundles, network debugging,
+reproducible demo, and real Linux support.
+
+### Added
+
+- **UI Inspector + selector generation.** `GET /apk-vm/debug/inspect` returns parsed
+  UIAutomator nodes with bounds, labels and copy-ready `find_ui` / `assert_text` / `tap_text`
+  commands; the panel renders a clickable overlay and the `apk_vm` tool gains `inspect_ui`.
+- **Interaction recorder / replay.** `GET|POST /apk-vm/flows` lists, starts, stops, replays
+  and deletes JSON flows of tap/swipe/key/text input; the panel has a Flow recorder card and
+  Agents get `flow_start`, `flow_stop`, `flow_list`, `flow_replay`.
+- **APKS / XAPK / split APK installation.** Upload and install `adb install-multiple` bundles;
+  `.aab` is rejected with a bundletool hint. The APK list tags bundle files.
+- **Network debugging.** Set/clear the guest global HTTP proxy and install a local PEM/DER CA
+  with the correct OpenSSL subject hash via `/apk-vm/debug/proxy` and `/apk-vm/debug/ca`
+  (plus Agent tool actions `proxy` and `install_ca`).
+- **Reproducible public demo.** `examples/` contains a committed MIT-licensed 12 KB sample
+  APK, a deterministic SDK-only build script, and `demo.mjs`, which installs it, taps the
+  button, asserts `Hello from dsh-apk-vm`, and saves a screenshot.
+- **Real Linux support.** Headless x86_64 validation on Ubuntu 22.04 with KVM and
+  SwiftShader: boot, adb root, APK install, UIAutomator input, H.264/scrcpy, proxy, CA and
+  screenshots; documented in `docs/LINUX-E2E.md`.
+
+### Fixed
+
+- **Dangerous auto-attach stop behavior.** `AndroidVm.stop()` no longer sends
+  `adb emu kill`/`adb disconnect` to a pre-existing device that this process did not spawn;
+  it leaves such devices running and reports `stopped`. A regression test covers it.
+- Headless Linux launches now request `-no-metrics` and fall back from host GPU to
+  `swiftshader_indirect` when no display is present.
+- `uiDump()` now includes UIAutomator stderr in its error instead of a generic
+  "empty hierarchy".
+- `spike/android/smoke.mjs` updated for the richer APK metadata and the current
+  package-not-found message.
+
 ## 0.3.13
 
 Open-source package identity.
@@ -13,6 +61,7 @@ Open-source package identity.
 - Removed `private: true` and added `publishConfig` for the public npm package
   **`dsh-apk-vm`**; the primary install command is now
   `dsh plugin --profile web add dsh-apk-vm` (source/GitHub install remains a fallback).
+  Published: <https://www.npmjs.com/package/dsh-apk-vm> (`0.3.13`).
 - Wrote the package/plugin descriptions (English + Chinese `meta.description`), expanded
   keywords, and added a suggested GitHub repository description/topics list to
   `docs/RELEASING.md`.

package/README.md

@@ -1,8 +1,10 @@
 # APK Virtual Machine — a DeepSeek Harness plugin
 
 [![CI](https://github.com/yuxiaole-bili/dsh-apk-vm/actions/workflows/ci.yml/badge.svg)](https://github.com/yuxiaole-bili/dsh-apk-vm/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-apk-vm.svg)](https://www.npmjs.com/package/dsh-apk-vm)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![GitHub](https://img.shields.io/badge/github-yuxiaole--bili%2Fdsh--apk--vm-181717)](https://github.com/yuxiaole-bili/dsh-apk-vm)
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/yuxiaole-bili/dsh-apk-vm)
 
 **Run a real Android APK inside a local, rooted, open-source Android VM and preview it in the DeepSeek Harness sidebar — streamed as H.264/WebCodecs video at up to 60 fps.**
 
@@ -19,13 +21,12 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
 > 点击、滑动、按键、文本输入送回虚拟机。支持拖拽 APK 上传、环境自检卡片、root 调试
 > API 与 `apk_vm` Agent 工具；多个 Agent 可各自使用独立的隔离虚拟机实例（多开）。
 > 参考机上冷启动约 29.5 s、快照快速启动约 8.4–10.5 s。
-> 当前 **Windows x64 为端到端已验证平台**；SDK/模拟器探测已覆盖 Windows / macOS / Linux。
+> 当前 **Windows x64 与 Linux x86_64（headless）为端到端已验证平台**；macOS 仅做探测/CI
+> 覆盖，详见 `docs/LINUX-E2E.md`。
 
-**Status:** `0.3.13` · Apache-2.0 · no npm runtime dependencies · no build step.
+**Status:** `0.4.1` · Apache-2.0 · no npm runtime dependencies · no build step.
 
-This is an open-source DSH plugin. The package is prepared for npm as **`dsh-apk-vm`**; the
-install command below uses that package name. If npm does not have the package yet, use the
-source fallback below. Repository:
+This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
 [github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
 Maintainer: [yuxiaole-bili](https://github.com/yuxiaole-bili/).
 Please read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md),
@@ -41,7 +42,7 @@ the session.
 ## Install
 
 Install the published npm package (the command used by the DSH plugin center and the community
-market). If the package is not yet visible in your registry, use the source fallback below.
+market):
 
 ```bash
 dsh plugin --profile web add dsh-apk-vm
@@ -90,8 +91,10 @@ and Agent-facing UI automation for development workflows.
 **Compatibility**
 
 - Tested with DSH Desktop `0.2.1-rc.3` (static bundle/plugin APIs).
-- Windows x64 is the only platform verified end-to-end (boot, H.264, rooted debug, Agent tool).
-  macOS/Linux have headless setup/CI coverage but not a live emulator run in this repository.
+- Windows x64 and Linux x86_64 (headless, KVM + SwiftShader) are verified end-to-end
+  (boot, H.264, rooted debug, APK install, Agent tool). macOS has SDK discovery + headless CI
+  coverage but no live emulator run in this repository.
+  See [docs/LINUX-E2E.md](docs/LINUX-E2E.md).
 - Optional integration with
   [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar); the plugin falls back
   cleanly when that service is absent.
@@ -155,6 +158,22 @@ key {"text":"HOME"}       -> returned to launcher
   (raw APK bytes, ≤ 500 MiB, `.apk`/ZIP magic checked), installed into the running VM and
   launched. Uploaded files live in the OS temp dir and are cleaned up when the plugin is
   disposed. Installing by absolute local path is still available (`/apk-vm/install`).
+- **APK bundles: APKS / XAPK / split APKs.** The Upload APK flow accepts `.apk`, `.apks`
+  (bundletool output) and `.xapk` files; split APKs are extracted to a temp directory and
+  installed with `adb install-multiple`. Plain `.apk` still uses `adb install -r`.
+  `.aab` is rejected with a clear "build APKs with bundletool first" message.
+- **UI Inspector + selector generation.** Toggle **Inspect UI** in the panel to overlay
+  clickable UIAutomator nodes on the live screen. Selecting a node shows its text, resource id,
+  class and bounds and gives copy-ready `tap_text` / `assert_text` commands for the `apk_vm`
+  tool. Also available to Agents as the `inspect_ui` action.
+- **Interaction recorder / replay.** Start a recording, use the panel or Agent tool normally,
+  then save the tap / swipe / key / text sequence as a JSON flow under the OS temp directory.
+  Flows can be listed, replayed with their original relative timing, downloaded or deleted.
+  Agents get `flow_start`, `flow_stop`, `flow_list` and `flow_replay`.
+- **Network debugging: proxy + CA.** The Network card sets/clears the guest global HTTP proxy
+  (`settings put global http_proxy`) and installs a local `.pem`/`.crt` CA into the rooted
+  Android user CA store with the correct OpenSSL subject-hash filename; the system CA store is
+  updated when the guest allows a remount.
 - **Installed-app management.** The panel's **Installed apps** card lists third-party packages
   for the active instance and offers force-stop, clear-data and uninstall; it uses the same
   rooted `debug/packages` + `debug/action` API as the Agent tool.
@@ -194,8 +213,8 @@ key {"text":"HOME"}       -> returned to launcher
   8.4–10.5 s** on the reference host ([details](#fast-start-four-layers)).
 - **Cross-platform SDK discovery.** `lib/setup.js` and `lib/android.js` discover Android SDK,
   `adb`, the emulator and AVDs across Windows, macOS and Linux layouts (including `.exe`
-  suffixes and per-OS fallback locations). Windows x64 is the only platform verified end-to-end
-  so far.
+  suffixes and per-OS fallback locations). Windows x64 and **Linux x86_64 headless** are
+  verified end-to-end; see [docs/LINUX-E2E.md](docs/LINUX-E2E.md).
 - **Same-origin only.** Every `/apk-vm/*` HTTP route and the `/apk-vm/ws` upgrade rejects
   cross-origin requests; request bodies and command output are bounded, and host processes are
   spawned with argv arrays (never a shell string).
@@ -206,6 +225,33 @@ key {"text":"HOME"}       -> returned to launcher
 
 ---
 
+## UI Inspector and flow recorder
+
+- `GET /apk-vm/debug/inspect` (and `/apk-vm/instances/<id>/debug/inspect`) returns the parsed
+  UIAutomator nodes with bounds, labels, and generated `find_ui` / `assert_text` / `tap_text`
+  commands. The panel's **Inspect UI** button renders the same data as an overlay.
+- `GET|POST /apk-vm/flows` (and `/apk-vm/instances/<id>/flows`) lists, starts, stops, replays
+  and deletes recorded flows. The panel has a **Flow recorder** card with the same actions.
+- `apk_vm` actions: `inspect_ui`, `flow_start`, `flow_stop`, `flow_list`, `flow_replay`.
+- `POST /apk-vm/debug/proxy` sets the guest HTTP proxy; `DELETE` clears it.
+- `POST /apk-vm/debug/ca` accepts a host `.pem`/`.crt` path and installs it under the guest's
+  user CA directory with the correct subject hash.
+
+## Reproducible demo
+
+A public, dependency-free demo lives in [examples](examples/README.md):
+
+```bash
+node examples/demo.mjs
+```
+
+It installs the committed MIT-licensed 12 KB sample APK (`dev.dsh.sample`), reads the
+UIAutomator tree, taps **Say hello**, asserts that the screen now says
+`Hello from dsh-apk-vm`, and saves a 720×1280 screenshot to `examples/demo-out/`. No personal
+APK, private key or host-specific path is required.
+
+---
+
 ## Quickstart
 
 ### 1. Prerequisites
@@ -804,9 +850,12 @@ before pointing the DSH Web UI at an untrusted network.
 
 - **The plugin manages processes on your machine.** It spawns the Android emulator, `adb`,
   `sdkmanager` and `avdmanager` with `child_process.spawn(exe, argv)` — never through a shell —
-  so user-supplied strings are not shell-interpreted. Paths are validated (APK paths must exist
-  and end in `.apk`; push/pull paths are restricted to `/data/local/tmp`, `/sdcard`,
-  `/storage/emulated/0` and allowed local roots).
+  so user-supplied strings are not shell-interpreted. Paths are validated (APK/bundle paths must
+  exist and end in `.apk`/`.apks`/`.xapk`; push/pull paths are restricted to `/data/local/tmp`,
+  `/sdcard`, `/storage/emulated/0` and allowed local roots).
+- **Only emulators spawned by this plugin are stopped.** `stop()` sends `adb emu kill` only when
+  this process owns the emulator; a pre-existing/attached device (physical, remote adb or a
+  manually started emulator) is detached and left running.
 - **The guest is deliberately rooted and debuggable.** `adb root`, `ro.debuggable=1` and
   `ro.adb.secure=0` mean anything you install inside the VM is not sandboxed from root. Do not
   put real secrets or personal data in the AVD.
@@ -858,9 +907,9 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
 
 ## Known limitations
 
-- **Windows x64 is the only end-to-end verified platform.** SDK/adb/emulator/AVD discovery is
-  implemented for Windows, macOS and Linux, but emulator + H.264 behavior on macOS/Linux (and
-  `arm64-v8a` images on Apple Silicon) is unverified.
+- **Windows x64 and Linux x86_64 are the end-to-end verified platforms.** macOS SDK/adb/
+  emulator/AVD discovery and headless checks are implemented, but emulator + H.264 behavior on
+  macOS (and `arm64-v8a` images on Apple Silicon) is unverified.
 - **Hardware virtualization is mandatory** for the x86_64 AOSP image; pure TCG fails by design.
 - **Quick boot is snapshot-based.** Changing AVD configuration invalidates the snapshot; recreate
   it as described in [Troubleshooting](#quick-boot-fails-different-avd-configuration-black-screen-or-no-snapshot).