dsh-apk-vm 0.0.0-stage → 0.3.13

package/cordis.patch.yml

@@ -0,0 +1,56 @@
+# Bundle patch: the Host half (index.js) mounts the local Android VM bridge and
+# its same-origin HTTP routes; the `dsh.client` manifest entry in package.json
+# loads ./client.js as the Web UI half that renders the sidebar panel.
+- insert:
+    - id: dsh-apk-vm
+      name: 'dsh-apk-vm'
+      config:
+        # Open-source AOSP Android Emulator. Paths are auto-detected from
+        # ANDROID_HOME / ANDROID_SDK_ROOT / common locations; set sdkRoot or
+        # emulatorPath explicitly only for non-standard installs.
+        # sdkRoot: 'D:/Android/sdk'
+        # emulatorPath: 'D:/Android/sdk/emulator/emulator.exe'
+        systemImage: 'system-images;android-34;default;x86_64'
+        avdName: dsh_apk
+        bootTimeoutMs: 1200000
+        gpuMode: host
+        accel: auto
+        requireAccel: true
+        quickBoot: true
+        snapshotName: default_boot
+        saveSnapshotAfterBoot: true
+        # PNG fallback target frame rate (1-10); the H.264 stream below is 60.
+        frameFps: 2
+        # Warm start after plugin activation (opt-in; consumes CPU while the
+        # plugin is loaded). Auto-start on the first panel open is on by default.
+        prewarm: false
+        prewarmDelayMs: 3000
+        autoStart: true
+        # Multiple isolated VMs: the first Agent gets the default instance;
+        # later Agents get their own AVD/port until maxInstances extra VMs.
+        multiInstance: true
+        maxInstances: 3
+        # Extra instances idle for this long (ms) with no panel frame / stream
+        # client / Agent command are stopped automatically; the AVD is kept for
+        # quick reuse. start()/the next Agent action boots it again.
+        instanceIdleMs: 900000
+        instanceReapIntervalMs: 60000
+        # H.264 stream: up to 60 fps via the vendored scrcpy server; 960 keeps
+        # 540x960 video (plenty for the panel) so software WebCodecs decode can
+        # sustain ~60 fps.
+        scrcpy: true
+        scrcpyMaxSize: 960
+        scrcpyMaxFps: 60
+        scrcpyBitrate: 6000000
+        # System-image downloads (~1 GB) are never automatic; the Environment
+        # card shows the exact missing pieces and the create-avd action works
+        # once the image is present.
+        allowSetupDownloads: false
+        # The VM routes accept root shell/debug actions, so they reject
+        # non-loopback clients by default even if the DSH web UI is exposed to
+        # the LAN. Set true only behind your own authenticated reverse proxy.
+        allowRemote: false
+        # APK discovery roots. The current workspace is always included; add
+        # platform-specific directories here (omit for a portable default).
+        # roots:
+        #   - 'D:/projects'

package/docs/PRIVACY.md

@@ -0,0 +1,36 @@
+# Privacy
+
+This plugin is a local development tool. It does not include analytics, telemetry, crash
+reporting, advertising or a remote backend.
+
+## Data the plugin handles
+
+- **APKs you select or upload** are copied into the OS temp directory and installed into the
+  local Android emulator. They are not uploaded anywhere by the plugin.
+- **VM data** (AVD images, snapshots, installed apps, guest files) stays on the host under the
+  Android SDK/AVD locations. The guest is a local emulator; do not put real secrets or personal
+  data inside it.
+- **Screenshots, recordings and logcat** are written to the OS temp directory or returned to the
+  panel. They are not sent off the machine. The artifact-download route is loopback-only and
+  whitelists files created by the plugin.
+- **Client diagnostics** (`POST /apk-vm/client-report`) contain a user agent and WebCodecs
+  capability information, stored in the local Host process memory for troubleshooting. They are
+  not persisted to disk or transmitted externally.
+- **Configuration** (`cordis.patch.yml`) may contain local paths (`sdkRoot`, `emulatorPath`,
+  `roots`). Do not commit a personal configuration to a public repository.
+
+## Network activity
+
+- The plugin talks to the local DSH Web server and local `adb`/emulator processes.
+- The optional SDK bootstrap / install actions use the user's own `sdkmanager` and the official
+  Google Android SDK repository, only when explicitly enabled with
+  `allowSetupDownloads: true`. This plugin does not proxy or collect those downloads.
+- No third-party endpoints are contacted by the plugin itself.
+
+## Public repository hygiene
+
+The repository ships `scripts/privacy-scan.mjs` and CI runs it on every push. It checks the
+tracked tree for personal paths, private-network IPs, agent instance IDs, credential patterns and
+emails. The development history may contain older local paths; publish the clean `open-source`
+branch (single initial commit) instead of the full development history. See
+[RELEASING](docs/RELEASING.md).

package/docs/README.md

@@ -0,0 +1,16 @@
+# Demo and screenshot assets
+
+Real assets captured from the reference host:
+
+- `screenshot-panel.png` — the main APK VM panel: Environment card, Android guest (H.264
+  11.7 fps in this capture), input controls and debug surface.
+- `screenshot-sidebar.png` — the plugin open in the DSH right sidebar next to a session, with
+  the host's APK paths redacted.
+
+Still optional:
+
+- `demo.gif` — 20–30 s recording: open panel → Environment check → VM boot → upload APK → 60 fps
+  interaction. Record on a real host and keep it under ~8 MiB.
+
+The assets are not fabricated. Before adding a new screenshot, crop out or redact the DSH
+sidebar conversation names, local paths and any LAN IPs.

package/docs/RELEASING.md

@@ -0,0 +1,104 @@
+# Releasing and publishing
+
+This project is distributed as a **DSH plugin bundle** and an **npm package** named
+`dsh-apk-vm`, following the DSH plugin naming convention. The primary install command is
+`dsh plugin --profile web add dsh-apk-vm`; the bundle patch installs from the npm package.
+Repository: <https://github.com/yuxiaole-bili/dsh-apk-vm>.
+
+## Publish to npm
+
+The package is intentionally public and has no build step; publishing the repository directory is
+enough:
+
+```bash
+npm login                      # once per machine, as the npm account that owns dsh-apk-vm
+npm publish --access public    # prepublish uses the packed file list
+npm view dsh-apk-vm version    # verify the published version
+```
+
+The GitHub release tarball and the npm tarball are produced from the same `npm pack` output.
+If the version already exists on npm, bump `version` and `CHANGELOG.md` together before publishing.
+For a manual GitHub Actions path, add an `NPM_TOKEN` repository secret (npm automation token that
+can publish `dsh-apk-vm`) and run the **Publish to npm** workflow
+([.github/workflows/npm-publish.yml](../.github/workflows/npm-publish.yml)).
+
+## Suggested GitHub repository description
+
+> Preview and debug Android APKs inside DeepSeek Harness: a local rooted AOSP VM with up to 60 fps
+> H.264/WebCodecs streaming, drag-and-drop install, UIAutomator automation, and isolated VMs per
+> Agent.
+
+Suggested topics:
+
+```text
+dsh, deepseek-harness, android, android-emulator, apk, scrcpy, webcodecs, ai-agents, ui-automation
+```
+
+The in-app Plugin Manager title/description comes from `locale/en.json` and `locale/zh.json`
+(`meta.title` / `meta.description`); keep those in sync with this description.
+
+## Before the first public push
+
+0. **Publish a clean history if the development history contains local paths.** This repository
+   may include an `open-source` branch with a single initial commit and no local development
+   history; push that branch (or create your own orphan branch) instead of the full dev history:
+
+   ```bash
+   git push -u origin open-source:main
+   ```
+
+1. Repository metadata is already configured in `package.json` (`repository`, `homepage`,
+   `bugs`) and the README has the matching badges. Update these only if the project moves or is
+   forked.
+2. Check the tree for personal paths, screenshots, recordings, emulator logs and AVD dumps:
+
+   ```bash
+   git grep -n -I -E 'D:\\\\|C:\\\\Users|/Users/|/home/[^ ]+/.android'
+   git status --ignored --short
+   ```
+
+   Also scan for your own hostname, private-network IPs and usernames. The repository ships a
+   tracked-tree scanner: `npm run privacy` (use `node scripts/privacy-scan.mjs --all` only to
+   inspect development history locally; the full history is not part of the clean release
+   branch).
+
+3. Run the full headless suite:
+
+   ```bash
+   npm ci --ignore-scripts   # or: npm install --ignore-scripts
+   npm run check
+   npm test
+   ```
+
+4. Re-test the live paths on a real host and update the verification notes:
+   boot/quick boot, H.264 60 fps, input mapping, multi-instance, physical-device attach,
+   APK upload/install, APK icon/info, clipboard (optional), pinch.
+
+## Versioning
+
+- `package.json` and `CHANGELOG.md` move together.
+- Use `0.x.y` while the plugin API/route surface may still change.
+- Keep `SECURITY.md` supported-version table in sync.
+- Tag the release (`git tag -a v0.3.12 -m ...`) and attach the tarball produced by
+  `npm pack --pack-destination dist`.
+
+## GitHub release checklist
+
+- [ ] LICENSE and NOTICE present and accurate (no unbundled upstream sources claimed)
+- [ ] CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md present
+- [ ] Issue templates and PR template present
+- [ ] CI green (headless suite; Windows cross-platform job is optional)
+- [ ] No secrets, tokens, personal paths, AVDs, logs, recordings or `dist/` committed
+- [ ] Demo media (if any) recorded on a real host and listed in `docs/README.md`
+- [ ] README install instructions use `<path-to-repo>` / user-chosen paths
+- [ ] Release notes call out known limitations (Windows E2E only, no audio, etc.)
+
+## Known limitations to state in the release
+
+- Windows x64 is the only platform verified end-to-end for boot/stream/debug; macOS/Linux are
+  covered by headless detection/CI but have not been live-verified.
+- No audio forwarding.
+- Physical-device attach is implemented; a real USB phone was not available for validation in
+  the reference environment.
+- Clipboard support is optional and uses scrcpy control messages; it requires a running H.264
+  stream.

package/docs/SUBMISSION.md

@@ -0,0 +1,75 @@
+# Community market submission
+
+Prepared for the [dsh-plugin.org submission checklist](https://dsh-plugin.org/zh/submit) and the
+DSH plugin hub issue template.
+
+## Filled issue template
+
+### 仓库地址
+
+<https://github.com/yuxiaole-bili/dsh-apk-vm>
+
+### 一句话价值
+
+在 DeepSeek Harness 的侧边栏里直接运行和调试 rooted Android APK 虚拟机，提供最高 60 fps 预览、UIAutomator/Agent 自动化与多 Agent 隔离实例。
+
+### 能力分类
+
+开发与运维
+
+### 安装命令
+
+npm 包安装（插件中心/社区市场推荐命令）：
+
+```bash
+dsh plugin --profile web add dsh-apk-vm
+```
+
+源码 fallback：
+
+```bash
+dsh plugin --profile web add github:yuxiaole-bili/dsh-apk-vm
+```
+
+DSH Desktop（`desktop` profile）通过 **Plugins → add/install local bundle** 安装同一目录。
+
+### 兼容与运行要求
+
+- DSH Desktop `0.2.1-rc.3` 已实测；静态 bundle/plugin API。
+- Windows x64 为唯一端到端验证平台（启动、H.264、root 调试、Agent tool）；macOS/Linux 有
+  headless setup/CI 覆盖，但未做真实模拟器运行验证。
+- 需要 Android SDK/emulator/platform-tools、Android 14 x86_64 system image、AVD，以及
+  AEHD/WHPX（Windows）、KVM（Linux）或 HVF（macOS）硬件虚拟化。
+- 每个运行中的 VM 约占 2.5 GB 内存；默认最多 3 个额外实例。
+- 可选兼容 [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar)。
+
+### 许可证
+
+Apache-2.0
+
+### 截图 / 演示
+
+- 主面板 + H.264 预览：<https://github.com/yuxiaole-bili/dsh-apk-vm/blob/main/docs/screenshot-panel.png>
+- 右侧栏布局：<https://github.com/yuxiaole-bili/dsh-apk-vm/blob/main/docs/screenshot-sidebar.png>
+- 真实 `apk_vm` 输出见 README 的 Demo/Verification 章节。
+
+### 补充说明
+
+- guest 是刻意 root/debuggable 的 `userdebug` 镜像；不要放真实凭据或隐私数据。
+- `apk_vm` Agent tool 对所有 Agent 开放 guest root shell/安装/UI 自动化，按“给 Agent 一台
+  rooted Android 设备”的权限级别对待。
+- `/apk-vm/*` API 与 WebSocket 默认仅 loopback；`allowRemote` 是显式远程代理 opt-in。
+- 无遥测；只有用户显式启用 SDK 下载或配置远程 adb 时才产生网络访问。
+- 更多风险/权限/兼容信息见 README 的 “Risks, permissions and compatibility” 与
+  [PRIVACY](PRIVACY.md)、[SECURITY](../SECURITY.md)。
+
+### 提交前自查
+
+- [x] 仓库已公开
+- [x] 已添加 GitHub topic：`dsh-plugin`
+- [x] README 包含安装命令
+- [x] 插件导出 `apply(ctx)` 模块
+- [x] 仓库根目录包含 `package.json`
+- [x] README 声明 Apache-2.0
+- [x] 截图/真实输出已附
+- [x] 能力分类选定：开发与运维

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" role="img" aria-label="APK virtual machine">
+  <rect x="6.25" y="2.25" width="11.5" height="19.5" rx="2.75"/>
+  <path d="M10.25 4.9h3.5"/>
+  <circle cx="9.9" cy="9.8" r="0.85" fill="currentColor" stroke="none"/>
+  <circle cx="14.1" cy="9.8" r="0.85" fill="currentColor" stroke="none"/>
+  <path d="M9.6 13.1c.55.9 1.4 1.35 2.4 1.35s1.85-.45 2.4-1.35"/>
+  <path d="M9.4 19.2h5.2"/>
+</svg>