dsh-apk-vm 0.12.4 → 0.12.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +46 -10
- package/CHANGELOG.zh-CN.md +129 -0
- package/README.md +108 -9
- package/client.js +109 -16
- package/cordis.patch.yml +38 -0
- package/docs/AGENTS.md +20 -0
- package/docs/PRIVACY.md +5 -1
- package/docs/RELEASING.md +11 -5
- package/index.js +106 -3
- package/lib/android.js +132 -0
- package/lib/autosetup.js +211 -13
- package/lib/instances.js +274 -6
- package/lib/jdk.js +90 -11
- package/lib/memory.js +272 -0
- package/lib/setup.js +444 -30
- package/package.json +6 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,39 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.12.5
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **Download reliability for zero-config provisioning.** Every provisioning step now retries
|
|
8
|
+
transient network/command failures (`setupRetries`, default 3, exponential backoff via
|
|
9
|
+
`retryDelayMs`), and a 45 s no-progress watchdog aborts stalled downloads instead of hanging.
|
|
10
|
+
The JDK archive resumes from a `.partial` file with HTTP Range and is re-verified against the
|
|
11
|
+
SHA-256 on every attempt; the command-line-tools download now streams with a stall timeout,
|
|
12
|
+
size bound and optional checksum (`commandLineToolsUrl` / `commandLineToolsSha256`) and can be
|
|
13
|
+
pointed at a mirror; `sdkmanager` accepts mirror/proxy settings (`sdkManagerArgs`,
|
|
14
|
+
`sdkManagerEnv`, `networkProxy`); a cumulative free-disk budget (`minFreeDiskBytes`, default
|
|
15
|
+
6 GB) is checked before provisioning starts. Retries surface `attempt` and `nextDelayMs` in
|
|
16
|
+
`autoSetup.detail`, and the Environment card shows "retry n/m in Ns" while backing off.
|
|
17
|
+
- **Memory-aware instance management.** New `lib/memory.js` reads host RAM and derives the
|
|
18
|
+
effective instance cap (`memoryGuard`, `hostReserveMb` 4 GB, `estimatedVmMb` 3 GB, clamped to
|
|
19
|
+
1–8), exposed as `memory` on `GET /apk-vm/state`, `/apk-vm/emulators` and
|
|
20
|
+
`GET /apk-vm/instances`, and on the `apk_vm` `list_instances` action. Creating/starting a local
|
|
21
|
+
VM on a low-memory host fails with an actionable error instead of swapping the machine to
|
|
22
|
+
death; `memoryPressureReap` (default) stops the least-recently-used idle local VM first. The VM
|
|
23
|
+
instances card shows host RAM, the effective cap, the preset and the per-VM RAM/vCPU profile.
|
|
24
|
+
- **Lite mode.** `vmPreset: lite` shrinks the default AVD and extra instances to 1 GB guest RAM,
|
|
25
|
+
2 vCPU, SwiftShader GPU and a 720×1280 / 30 fps H.264 stream (1 fps PNG fallback), for 8–16 GB
|
|
26
|
+
hosts.
|
|
27
|
+
- **Wedged-guest recovery.** A device that adb still lists but whose guest shell stops responding
|
|
28
|
+
is detected after two consecutive boot-probe timeouts, killed through the emulator console (and
|
|
29
|
+
its process tree), its broken snapshot is quarantined, and the instance is cold-started once
|
|
30
|
+
instead of staying `booting` forever. `_refresh()` no longer flips between `starting` and
|
|
31
|
+
`stopped` while a boot wait is in flight, and the instances card gains a Start button for
|
|
32
|
+
stopped VMs.
|
|
33
|
+
- **Chinese changelog.** `CHANGELOG.zh-CN.md` mirrors the 0.12.x entries of the English
|
|
34
|
+
changelog (the pre-0.12 history stays English-only in `CHANGELOG.md`) and release notes now
|
|
35
|
+
carry a Chinese summary; the release checklist requires keeping it in sync.
|
|
36
|
+
|
|
3
37
|
## 0.12.4
|
|
4
38
|
|
|
5
39
|
### Fixed
|
|
@@ -142,12 +176,16 @@ reset, and the plugin can provision its own JDK / Android SDK / system image / A
|
|
|
142
176
|
- `webviewAction=eval` returned `null` for `DOMRect`/`MediaQueryList` and other non-by-value
|
|
143
177
|
values; it now returns a readable snapshot.
|
|
144
178
|
|
|
145
|
-
|
|
179
|
+
### Historical: planned 1.0.0, shipped as 0.12.0
|
|
180
|
+
|
|
181
|
+
> These notes were written for a 1.0.0 cut that was renumbered to 0.12.0 before
|
|
182
|
+
> release. They are kept here for history, so no 1.0.0 that never shipped appears
|
|
183
|
+
> between the 0.12.0 and 0.11.1 sections.
|
|
146
184
|
|
|
147
185
|
Observability and reliability release: a local Agent activity journal, hardened device
|
|
148
186
|
interactions, and a first-class zero-config provisioning chain.
|
|
149
187
|
|
|
150
|
-
|
|
188
|
+
#### Added
|
|
151
189
|
|
|
152
190
|
- **Agent activity log.** Every `apk_vm` tool call and every mutating panel/HTTP request is
|
|
153
191
|
journaled locally as JSONL under `<profile>/.apk-vm/activity` (override with `activityDir`);
|
|
@@ -182,7 +220,7 @@ interactions, and a first-class zero-config provisioning chain.
|
|
|
182
220
|
- WebView control docs and examples now point at `webview`/`tap_css`/`tap_selector`
|
|
183
221
|
as the preferred path for DOM content.
|
|
184
222
|
|
|
185
|
-
|
|
223
|
+
#### Changed
|
|
186
224
|
|
|
187
225
|
- `sdkmanager` installs (`installSystemImage`, `installSdkPackages`) always pass
|
|
188
226
|
`--sdk_root=<sdkRoot>`, so a `sdkmanager` found elsewhere on `PATH` cannot install into the
|
|
@@ -194,7 +232,7 @@ interactions, and a first-class zero-config provisioning chain.
|
|
|
194
232
|
physical devices and snapshots; expanded troubleshooting for the fixes above; macOS/arm64
|
|
195
233
|
image selection documented; demo media checked in.
|
|
196
234
|
|
|
197
|
-
|
|
235
|
+
#### Fixed
|
|
198
236
|
|
|
199
237
|
- `adb` tool action failed with `Cannot access 'api' before initialization` on every call — the
|
|
200
238
|
tool API is now resolved lazily per action.
|
|
@@ -229,15 +267,13 @@ interactions, and a first-class zero-config provisioning chain.
|
|
|
229
267
|
and per-candidate timeouts plus the known-good JDK table make it fail over instead.
|
|
230
268
|
- macOS arm64 provisioning selected the x86_64 image; it now defaults to `arm64-v8a`.
|
|
231
269
|
|
|
232
|
-
### Fixed
|
|
233
|
-
|
|
234
270
|
- `GET/POST /apk-vm/camera` accepted poster paths that did not exist; save/apply now reject
|
|
235
271
|
missing or unreadable `-virtualscene-poster` files with the offending poster name and path
|
|
236
272
|
instead of failing later on the next emulator launch.
|
|
237
273
|
|
|
238
|
-
|
|
274
|
+
##### Zero-config first run
|
|
239
275
|
|
|
240
|
-
|
|
276
|
+
##### Added
|
|
241
277
|
|
|
242
278
|
- **Automatic environment provisioning (`autoSetup`, default `true`).** The first
|
|
243
279
|
`GET /apk-vm/state` or `GET /apk-vm/setup` request — opening the panel, or an Agent's first
|
|
@@ -260,7 +296,7 @@ interactions, and a first-class zero-config provisioning chain.
|
|
|
260
296
|
- `GET /apk-vm/setup` now reports `javaHome` / `javaPresent`; the Environment card shows a Java
|
|
261
297
|
row plus live auto-setup progress with cancel/retry.
|
|
262
298
|
|
|
263
|
-
|
|
299
|
+
##### Changed
|
|
264
300
|
|
|
265
301
|
- `findJavaHome()` also looks in the plugin-managed JDK directory and `extraJavaHomes`, so
|
|
266
302
|
`sdkmanager`/`avdmanager` work without a system-wide JDK or `JAVA_HOME`.
|
|
@@ -269,7 +305,7 @@ interactions, and a first-class zero-config provisioning chain.
|
|
|
269
305
|
`autoStart` flow — a cold install goes from zero to a running VM without extra clicks.
|
|
270
306
|
- First-run documentation is now install → open the panel → automatic provisioning → VM start.
|
|
271
307
|
|
|
272
|
-
|
|
308
|
+
##### Fixed
|
|
273
309
|
|
|
274
310
|
- The Environment card could stay empty on exactly the machines that needed setup: a
|
|
275
311
|
`GET /apk-vm/setup` payload with `ok: false` was treated as a failed request. It now renders
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# 更新日志(中文)
|
|
2
|
+
|
|
3
|
+
本文件提供 **0.12.x** 各版本的中文更新日志,与英文版 [`CHANGELOG.md`](CHANGELOG.md) 同步;
|
|
4
|
+
0.12.0 之前的历史仅保留在英文文件中。发布时请在 [docs/RELEASING.md](docs/RELEASING.md)
|
|
5
|
+
的检查清单里确认本文件已同步更新。
|
|
6
|
+
|
|
7
|
+
## 0.12.5
|
|
8
|
+
|
|
9
|
+
可靠性版本:零配置首次启动的抗网络故障能力,以及多 VM 宿主机的内存管理。
|
|
10
|
+
|
|
11
|
+
### 新增
|
|
12
|
+
|
|
13
|
+
- **零配置供应的下载可靠性。** 每个供应步骤都会自动重试临时性的网络/命令失败
|
|
14
|
+
(`setupRetries`,默认 3 次;`retryDelayMs` 指数退避),45 秒无进展看门狗会中止卡死的
|
|
15
|
+
下载,而不是一直挂起。JDK 压缩包从 `.partial` 文件用 HTTP Range 续传,每次尝试都重新校验
|
|
16
|
+
SHA-256;命令行工具下载现在带 stall 超时、大小上限和可选校验
|
|
17
|
+
(`commandLineToolsUrl` / `commandLineToolsSha256`),并支持镜像地址;`sdkmanager`
|
|
18
|
+
支持镜像/代理配置(`sdkManagerArgs`、`sdkManagerEnv`、`networkProxy`);供应开始前先检查
|
|
19
|
+
累计可用磁盘预算(`minFreeDiskBytes`,默认 6 GB)。重试会在 `autoSetup.detail` 中报告
|
|
20
|
+
`attempt` 与 `nextDelayMs`,环境卡片在退避期间显示「retry n/m in Ns」。
|
|
21
|
+
- **内存感知的实例管理。** 新增 `lib/memory.js`:读取宿主内存并推导有效实例上限
|
|
22
|
+
(`memoryGuard`,`hostReserveMb` 4 GB,`estimatedVmMb` 3 GB,限制在 1–8 之间),通过
|
|
23
|
+
`GET /apk-vm/state`、`/apk-vm/emulators`、`GET /apk-vm/instances` 和 `apk_vm`
|
|
24
|
+
`list_instances` 的 `memory` 对象暴露。低内存宿主上创建/启动本地 VM 会给出可操作的错误,
|
|
25
|
+
而不是把整机换页致死;`memoryPressureReap`(默认开启)先停止最久未使用的空闲本地 VM。
|
|
26
|
+
VM 实例卡片显示宿主内存、有效上限、预设以及每个 VM 的 RAM/vCPU 配置。
|
|
27
|
+
- **Lite 模式。** `vmPreset: lite` 把默认 AVD 和额外实例缩小到 1 GB 客机内存、2 vCPU、
|
|
28
|
+
SwiftShader GPU 以及 720×1280 / 30 fps 的 H.264 流(PNG 回退 1 fps),适合 8–16 GB 的
|
|
29
|
+
宿主机。
|
|
30
|
+
- **卡死 guest 的自动恢复。** 如果 adb 仍能列出设备但客机 shell 已无响应,插件会在连续两次
|
|
31
|
+
启动探测超时后判定为 wedged:通过模拟器控制台(以及进程树)结束该模拟器、隔离损坏快照,
|
|
32
|
+
并冷启动重试一次,而不是永远停在 `booting`。`_refresh()` 在启动等待进行中不再于
|
|
33
|
+
`starting` 与 `stopped` 之间来回切换,实例卡片也为已停止的 VM 增加了「启动」按钮。
|
|
34
|
+
- **中文更新日志。** `CHANGELOG.zh-CN.md` 提供 0.12.x 条目的中文版本,发布说明也带中文摘要;
|
|
35
|
+
发布检查清单要求保持同步。
|
|
36
|
+
|
|
37
|
+
## 0.12.4
|
|
38
|
+
|
|
39
|
+
### 修复
|
|
40
|
+
|
|
41
|
+
- **0.12.3 引入的 hypervisor 检测回归。** 启动速度统计的重构丢失了三个构造器初始化字段
|
|
42
|
+
(`_accelAvailable`、`_snapshotSave`、`_lastLaunchArgs`),导致 `_detectAcceleration()`
|
|
43
|
+
在 `!== null` 处短路并返回 `undefined`,于是每次启动都误报「找不到可用的 CPU
|
|
44
|
+
hypervisor(AEHD/WHPX)」,即使 `emulator -accel-check` 报告可用。本次恢复这三个字段,
|
|
45
|
+
并在 `spike/snapshot-recovery-test.mjs` 中断言其初始值以及 `_detectAcceleration()` 返回
|
|
46
|
+
布尔值,防止该回归再次静默发布。
|
|
47
|
+
|
|
48
|
+
## 0.12.3
|
|
49
|
+
|
|
50
|
+
### 新增
|
|
51
|
+
|
|
52
|
+
- **Agent 操作手册。** 包内新增 [`docs/AGENTS.md`](docs/AGENTS.md),可在运行时通过
|
|
53
|
+
`apk_vm` 的 `guide` 动作(或 `GET /apk-vm/guide`)读取;内容覆盖标准循环、动作地图、
|
|
54
|
+
设备像素与 CSS 坐标规则、WebView/CDP、实例与远端会话、错误恢复和安全边界。
|
|
55
|
+
- **新会话强制引导。** 每个新会话的第一次 `apk_vm` 调用会先返回一次操作手册
|
|
56
|
+
(`result.guideRequired: true`)而不执行原动作;阅读后重复调用即可。`action=guide`
|
|
57
|
+
始终可用。
|
|
58
|
+
- **共享与专用 VM 指引。** 手册和 README 说明默认实例是共享、短命的设备,长时间调试建议
|
|
59
|
+
claim 一个专用 VM,并说明从其它会话进入共享 VM 会把客机重置回桌面。
|
|
60
|
+
- **Quick-boot 快照自愈。** 恢复时会让模拟器崩溃(Windows 访问冲突 `0xC0000005`)或看起来
|
|
61
|
+
只写了一半(`snapshot.pb` 远新于 `ram.bin`)的快照会被自动隔离、以冷启动重试一次并重建;
|
|
62
|
+
隔离情况通过 `status().snapshotRecovery` 暴露。
|
|
63
|
+
- **VM 命名与按会话自动选中。** 每个实例(包括 `default` 和远端会话)都可以有持久化的显示名
|
|
64
|
+
(`<profile>/.apk-vm/instance-names.json`);可用 `apk_vm` 的 `rename_instance`、
|
|
65
|
+
`POST /apk-vm/instances {"action":"rename",…}` 或面板的 Rename 按钮重命名。面板会跟随当前
|
|
66
|
+
会话,选中租约属于该会话的 VM,而不是永远显示共享的 default。
|
|
67
|
+
|
|
68
|
+
### 变更
|
|
69
|
+
|
|
70
|
+
- **DSH 兼容性元数据。** `package.json` 现在声明 `engines.dsh`
|
|
71
|
+
(`>=0.2.1-rc.3 || >=0.2.2-rc.1`)和 `dsh.compatibility.dshReleases`(`0.2.1-rc.3+`、
|
|
72
|
+
`0.2.2-rc.1+` → `compatible`),插件管理器和市场可以在安装/启用前校验支持的 DSH 版本。
|
|
73
|
+
README 增加「Supported DSH versions」一节,`docs/SUBMISSION.md` 列出同样的测试矩阵。
|
|
74
|
+
|
|
75
|
+
## 0.12.2
|
|
76
|
+
|
|
77
|
+
### 修复
|
|
78
|
+
|
|
79
|
+
- **面板版本标签显示 `v0.11.1`。** `client.js` 里手写的 `CLIENT_VERSION` 常量在 0.11.1 之后
|
|
80
|
+
没有再更新,导致 0.12.0/0.12.1 的标题栏胶囊显示错误版本。现在胶囊优先使用宿主上报的版本,
|
|
81
|
+
常量更新为当前版本,并且 `npm run check` 会运行 `scripts/check-version.mjs`,在
|
|
82
|
+
`CLIENT_VERSION` 与 `package.json` 不一致时让构建失败。
|
|
83
|
+
|
|
84
|
+
## 0.12.1
|
|
85
|
+
|
|
86
|
+
### 新增
|
|
87
|
+
|
|
88
|
+
- **远端 VM 多会话。** 远端主机成为一类 VM 来源:配置文件保存在
|
|
89
|
+
`<profile>/.apk-vm/remote-profiles.json`(只存校验后的非敏感字段,不存密钥内容),
|
|
90
|
+
`RemoteSessionManager` 可并发运行多个会话(`remoteMaxSessions`,默认 4),每个会话有自己
|
|
91
|
+
的 AVD、adb 隧道、H.264 流和实例 id。
|
|
92
|
+
- **模拟器清单。** `GET /apk-vm/emulators` 把本地 AVD/设备状态与每个已保存的远端主机合并
|
|
93
|
+
(`lib/emulator-inventory.js`),面板增加「Available emulators」卡片。
|
|
94
|
+
- **虚拟摄像头。** 支持摄像头前后置模式与 `-virtualscene-poster` 海报,由
|
|
95
|
+
`GET/POST /apk-vm/camera`、面板 Media 卡片或 `cfg.camera` 管理(`lib/media.js`)。
|
|
96
|
+
- **虚拟麦克风。** 麦克风模式 `off` / `host` / `file`;file 模式把音频循环进虚拟
|
|
97
|
+
PulseAudio 源(null-sink + remap-source),在 Linux 和远端主机可用;由
|
|
98
|
+
`GET/POST /apk-vm/mic`、面板 Media 卡片或 `cfg.mic` 管理。
|
|
99
|
+
- **SSH 远端虚拟机(远端 VM 主机)。** `/apk-vm/remote` 现在把一台 SSH 可达主机变成 VM
|
|
100
|
+
代理:转发本地回环端口到远端模拟器的 adb 端口,执行 `adb connect` 并把设备接入正常的
|
|
101
|
+
启动等待/H.264/输入/调试链路。`launch: true` 会在远端用固定命令启动无窗口模拟器
|
|
102
|
+
(`-no-window -no-audio -no-boot-anim -gpu swiftshader_indirect`),`disconnect` 可以停止
|
|
103
|
+
它。经验证的配置(主机/用户/端口/AVD,不含密钥)持久化在
|
|
104
|
+
`<profile>/.apk-vm/remote-profile.json`,面板卡片会预填并每两秒轮询隧道/启动状态。
|
|
105
|
+
|
|
106
|
+
### 变更
|
|
107
|
+
|
|
108
|
+
- 新的插件图标(`icon.svg`,36×36):柠檬/草绿与紫色分层屏幕,替换原先在深色磁贴上几乎不可见
|
|
109
|
+
的细线 `currentColor` 图标。
|
|
110
|
+
- 使用 0.12.0 面板 UI 重新生成演示截图(主面板、Activity 卡片、客机、Environment、APK 文件
|
|
111
|
+
和 Rooted debug 卡片);Windows 用户名、真实 APK 名称/路径和助手头像做了高斯模糊。
|
|
112
|
+
|
|
113
|
+
### 移除
|
|
114
|
+
|
|
115
|
+
- `docs/screenshot-sidebar.png`:由重新拍摄的面板与卡片截图替代。
|
|
116
|
+
|
|
117
|
+
## 0.12.0
|
|
118
|
+
|
|
119
|
+
WebView 读取、记住已装 APK 和零配置首次运行。
|
|
120
|
+
|
|
121
|
+
- `webviewAction=eval` 现在返回真实值(普通 JSON 值直接返回;`DOMRect`、`MediaQueryList`
|
|
122
|
+
这类不能按值穿过 JSON 的对象返回属性快照),不再需要截图。
|
|
123
|
+
- 记住已安装的 APK:通过工具或面板安装的 APK 记录在
|
|
124
|
+
`<profile>/.apk-vm/installed-apps.json`,上传的 APK 归档在 `<profile>/.apk-vm/apks`
|
|
125
|
+
(最新 10 个);客机重置/AVD 重建/插件升级后会按需自动重装(`autoReinstall`,默认开)。
|
|
126
|
+
- 零配置首次运行:`autoSetup`(默认开)在第一次使用时自动准备 JDK 17、SDK 命令行工具、
|
|
127
|
+
system image 和 AVD;可在环境卡片查看进度、取消和重试,也可用 `autoSetup: false` 保持手动。
|
|
128
|
+
- Agent 活动日志、设备韧性/恢复、quick-boot 快照恢复、多实例隔离等 0.12.0 的完整说明见
|
|
129
|
+
[`CHANGELOG.md`](CHANGELOG.md) 的 0.12.0 一节(含 Historical: planned 1.0.0 的历史记录)。
|
package/README.md
CHANGED
|
@@ -45,7 +45,7 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
|
|
|
45
45
|
> 当前 **Windows x64 与 Linux x86_64(headless)为端到端已验证平台**;macOS 仅做探测/CI
|
|
46
46
|
> 覆盖,详见 `docs/LINUX-E2E.md`。
|
|
47
47
|
|
|
48
|
-
**Status:** `0.12.
|
|
48
|
+
**Status:** `0.12.5` · Apache-2.0 · no npm runtime dependencies · no build step.
|
|
49
49
|
|
|
50
50
|
This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
|
|
51
51
|
[github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
|
|
@@ -96,7 +96,10 @@ and Agent-facing UI automation for development workflows.
|
|
|
96
96
|
- Hardware virtualization: AEHD/WHPX on Windows, KVM on Linux, or HVF on macOS.
|
|
97
97
|
- Node.js ≥ 20 only for the repository's headless checks; the plugin itself has no npm
|
|
98
98
|
dependencies or build step.
|
|
99
|
-
- Each running VM costs roughly 2
|
|
99
|
+
- Each running VM costs roughly 2–3 GB of host RAM (`hw.ramSize` 1.5 GB default plus
|
|
100
|
+
emulator/GPU overhead); `maxInstances` defaults to 3 extra VMs. The `memoryGuard` (default on)
|
|
101
|
+
caps the effective count from total host RAM and the `vmPreset: lite` preset shrinks the guest
|
|
102
|
+
to 1 GB / 2 vCPU for 8–16 GB machines.
|
|
100
103
|
|
|
101
104
|
**Permissions / risk**
|
|
102
105
|
|
|
@@ -197,6 +200,26 @@ key {"text":"HOME"} -> returned to launcher
|
|
|
197
200
|
configured system image and the AVD, with live progress plus cancel/retry in the Environment
|
|
198
201
|
card (`autoSetup` on `GET/POST /apk-vm/setup`). The normal `autoStart` flow then boots the VM;
|
|
199
202
|
set `autoSetup: false` to keep setup manual.
|
|
203
|
+
- **Download resilience for the zero-config first run.** Every provisioning step retries
|
|
204
|
+
transient network failures with exponential backoff (`setupRetries: 3`, `retryDelayMs: 2000`)
|
|
205
|
+
and no-data stalls are detected by a 45 s no-progress watchdog, so a link that dies at 10 %
|
|
206
|
+
resumes instead of hanging. The JDK archive resumes from a `.partial` file with HTTP Range and
|
|
207
|
+
is re-verified against the SHA-256 checksum on each attempt; a configurable mirror
|
|
208
|
+
(`jdkMirror`) bypasses unreachable GitHub assets. The command-line-tools archive can point at
|
|
209
|
+
a mirror or proxy (`commandLineToolsUrl`, `commandLineToolsSha256`, `sdkManagerArgs`,
|
|
210
|
+
`sdkManagerEnv`, `networkProxy`), and the cumulative free-disk budget
|
|
211
|
+
(`minFreeDiskBytes`, default 6 GB) is checked before provisioning starts.
|
|
212
|
+
- **Memory guard, Lite mode and instance management.** A local emulator costs ~2–3 GB of host
|
|
213
|
+
RAM, so with `memoryGuard` on (default) the effective `maxInstances` is derived from total
|
|
214
|
+
host RAM (8 GB → 1; 16 GB → 3 with the default requested cap; clamped to 1–8), free host RAM
|
|
215
|
+
is checked at start, and a low-memory machine refuses to start another VM with a clear error
|
|
216
|
+
instead of swapping itself to death. On a 16 GB desktop that also runs an IDE and a browser,
|
|
217
|
+
keep `maxInstances` at 2 or switch to `vmPreset: lite`, which
|
|
218
|
+
shrinks the AVD to 1 GB RAM / 2 vCPU / SwiftShader with a 720p30 H.264 stream, and
|
|
219
|
+
`memoryPressureReap` (default on) stops the least-recently-used idle local VM when memory is
|
|
220
|
+
tight (extra VMs are stopped, never destroyed). The VM instances card shows host RAM, the
|
|
221
|
+
effective cap, the preset and the per-VM RAM/vCPU profile; `GET /apk-vm/state` and
|
|
222
|
+
`GET /apk-vm/emulators` expose the same `memory` object.
|
|
200
223
|
- **Multi-agent isolation / multi-instance.** Several DSH Agents can drive separate VMs at the
|
|
201
224
|
same time: each conversation owns a renewable lease on the VM it uses, so a second
|
|
202
225
|
conversation never silently steals the first one's emulator. The first conversation gets the
|
|
@@ -732,14 +755,27 @@ config:
|
|
|
732
755
|
maxInstances: 3 # extra VMs (default VM is always available)
|
|
733
756
|
instanceIdleMs: 900000 # stop idle extra VMs after 15 min (AVD kept)
|
|
734
757
|
instanceReapIntervalMs: 60000
|
|
758
|
+
memoryGuard: true # cap instances from host RAM; refuse low-memory starts
|
|
759
|
+
# hostReserveMb: 4096 # RAM kept for the host/other apps
|
|
760
|
+
# estimatedVmMb: 3072 # estimated cost of one local emulator
|
|
761
|
+
vmPreset: standard # standard | lite (1 GB / 2 vCPU / SwiftShader / 720p30)
|
|
762
|
+
memoryPressureReap: true # stop LRU idle VMs before creating another one
|
|
735
763
|
leaseTtlMs: 1800000 # VM owner lease lifetime; renewed by apk_vm calls
|
|
736
764
|
allowRemote: false # reject non-loopback VM API clients
|
|
737
765
|
autoSetup: true # zero-config first run: auto-provision JDK 17 + SDK + image + AVD
|
|
766
|
+
setupRetries: 3 # retries per provisioning step (exponential backoff)
|
|
767
|
+
retryDelayMs: 2000
|
|
768
|
+
# minFreeDiskBytes: 6442450944 # cumulative free-disk budget before provisioning
|
|
738
769
|
# jdkRoot: 'C:/tools/dsh-jdk' # where the auto-downloaded JDK 17 lives
|
|
739
770
|
# jdkVersion: 17 # Temurin major version to provision (known-good table covers 17.0.21+9)
|
|
740
771
|
# jdkMirror: 'https://mirrors.tuna.tsinghua.edu.cn/Adoptium' # override the JDK mirror fallback
|
|
741
772
|
# activityDir: 'C:/tools/apk-vm-activity' # journal + screenshot storage (default <profile>/.apk-vm/activity)
|
|
742
773
|
allowSetupDownloads: false # gate the optional manual system-image download action
|
|
774
|
+
# commandLineToolsUrl: 'https://example.com/commandlinetools-win-latest.zip' # mirror for the tools archive
|
|
775
|
+
# commandLineToolsSha256: '...' # checksum for the custom archive
|
|
776
|
+
# sdkManagerArgs: ['--no_https'] # passed verbatim to sdkmanager (mirrors / flags)
|
|
777
|
+
# sdkManagerEnv: { SDK_TEST_BASE_URL: 'https://mirror.example.com/android/repository/' }
|
|
778
|
+
# networkProxy: { host: 127.0.0.1, port: 7890 } # --proxy_* flags for sdkmanager only
|
|
743
779
|
scrcpy: true
|
|
744
780
|
scrcpyMaxSize: 960
|
|
745
781
|
scrcpyMaxFps: 60
|
|
@@ -804,6 +840,11 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
804
840
|
| `mic` | `{ mode: "off" }` | Guest microphone: `off` / `host` (host input passthrough) / `file` (loop an audio file into a virtual source; Linux and remote hosts). Optional `backend`, `filePath`. |
|
|
805
841
|
| `multiInstance` | `true` | Allow isolated extra VMs for concurrent Agents. |
|
|
806
842
|
| `maxInstances` | `3` | Maximum number of extra instances (in addition to the default VM). Each running instance costs guest RAM/CPU. |
|
|
843
|
+
| `memoryGuard` | `true` | Cap the effective instance count from host RAM and refuse to start a local VM when free memory is below the reserve. Remote sessions are not counted. |
|
|
844
|
+
| `hostReserveMb` | `4096` | Host RAM kept free when computing the effective cap / deciding whether a new VM fits. |
|
|
845
|
+
| `estimatedVmMb` | `3072` | Estimated host RAM used by one local emulator (AVD RAM + qemu/GPU overhead) for the guard and the panel estimate. |
|
|
846
|
+
| `vmPreset` | `standard` | `standard` or `lite` (1 GB guest RAM, 2 vCPU, SwiftShader GPU, 1 fps PNG / 720p30 H.264). Applies to the default AVD (rewritten on activation) and to extra instances. |
|
|
847
|
+
| `memoryPressureReap` | `true` | When memory is tight, stop the least-recently-used idle local VM before creating another one. Extra VMs are stopped, never destroyed. |
|
|
807
848
|
| `instanceIdleMs` | `900000` | Stop an extra instance after this long without panel frames, a video client, or an Agent command (AVD is kept). |
|
|
808
849
|
| `instanceReapIntervalMs` | `60000` | How often the idle reaper checks extra instances. |
|
|
809
850
|
| `leaseTtlMs` | `1800000` | Lifetime of a VM owner lease. Every `apk_vm` call that routes to the VM renews it; set `0` to disable expiry. |
|
|
@@ -813,6 +854,14 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
813
854
|
| `jdkRoot` | `~/.dsh/apk-vm/jdk` | Where the auto-downloaded Temurin JDK 17 is installed. A system JDK / `JAVA_HOME` is preferred when present. |
|
|
814
855
|
| `jdkVersion` | `17` | Temurin major version to provision when `autoSetup` needs a JDK. |
|
|
815
856
|
| `jdkMirror` | built-in Tsinghua mirror | Mirror base URL (or array of bases) used for the Temurin JDK archive when the GitHub-hosted Adoptium download is unreachable, verified with the same SHA-256 checksum. Env: `DSH_APK_VM_JDK_MIRROR`; an empty value disables the fallback. |
|
|
857
|
+
| `setupRetries` | `3` | Automatic retries per provisioning step after a transient network/command failure (exponential backoff). |
|
|
858
|
+
| `retryDelayMs` | `2000` | Base delay between provisioning retries; doubled each attempt. |
|
|
859
|
+
| `minFreeDiskBytes` | `6442450944` (6 GB) | Cumulative free-disk budget checked before provisioning starts (JDK + tools + image + AVD). |
|
|
860
|
+
| `commandLineToolsUrl` | Google archive | Optional mirror URL for the command-line-tools archive (checksum option below). |
|
|
861
|
+
| `commandLineToolsSha256` | — | Optional SHA-256 for `commandLineToolsUrl`; the download is verified like the JDK. |
|
|
862
|
+
| `sdkManagerArgs` | `[]` | Extra arguments passed verbatim to `sdkmanager` (for example `["--no_https"]` for a mirror). |
|
|
863
|
+
| `sdkManagerEnv` | `{}` | Extra environment variables for `sdkmanager` (for example `SDK_TEST_BASE_URL` for an SDK mirror). |
|
|
864
|
+
| `networkProxy` | — | `{host, port, user, password}` translated into `--proxy_*` flags for `sdkmanager` only; the plugin itself never proxies its own requests. |
|
|
816
865
|
| `activityDir` | `<profile>/.apk-vm/activity` | Where the Agent activity journal (`activity.jsonl`) and its screenshots are stored. |
|
|
817
866
|
| `frameFps` | `2` | PNG fallback target frame rate, 1–10 (the H.264 path is not affected). |
|
|
818
867
|
| `scrcpy` | `true` | Enable the H.264/WebCodecs transport. |
|
|
@@ -831,6 +880,15 @@ per-action availability. It also carries the auto-setup state: `autoSetupEnabled
|
|
|
831
880
|
finishedAt }`; `POST /apk-vm/setup` with `{ action: "auto-setup" }` starts/retries provisioning
|
|
832
881
|
and `{ action: "cancel-auto-setup" }` cancels it.
|
|
833
882
|
|
|
883
|
+
`GET /apk-vm/state`, `GET /apk-vm/emulators`, `GET /apk-vm/instances` and the
|
|
884
|
+
`apk_vm` `list_instances` action also expose a `memory` object:
|
|
885
|
+
`{ available, totalMb, freeMb, reserveMb, estimatedVmMb, guard, pressureReap,
|
|
886
|
+
requestedMaxInstances, effectiveMaxInstances, preset: { name, ramSizeMb, cores, ... },
|
|
887
|
+
limited, reason }`. It is the same object the panel uses for the host-memory line and the
|
|
888
|
+
instance cap. `POST /apk-vm/instances` (create) and `create_instance` honour it: when a local VM
|
|
889
|
+
does not fit, the request fails with an actionable error, or `memoryPressureReap` stops an idle
|
|
890
|
+
VM first.
|
|
891
|
+
|
|
834
892
|
---
|
|
835
893
|
|
|
836
894
|
## Architecture
|
|
@@ -865,6 +923,7 @@ and `{ action: "cancel-auto-setup" }` cancels it.
|
|
|
865
923
|
| Setup | [lib/setup.js](lib/setup.js), [lib/jdk.js](lib/jdk.js), [lib/autosetup.js](lib/autosetup.js) | Dependency-free SDK / adb / emulator / AVD / acceleration detection plus one-click `create-avd` and optional `install-image`; `lib/jdk.js` provisions a managed Temurin JDK 17 and `lib/autosetup.js` runs the first-use auto-provisioning chain. |
|
|
866
924
|
| Journal | [lib/activity-log.js](lib/activity-log.js) | Records every `apk_vm` tool call and every mutating panel/HTTP request (`source: tool|http|system`; action, argument preview, result/error, duration, instance, screenshot for mutating actions) as local JSONL + PNGs; backs the panel timeline and the `/apk-vm/activity` routes. |
|
|
867
925
|
| Installed apps | [lib/installed-apps.js](lib/installed-apps.js) | Persists APKs installed through the plugin (`<profile>/.apk-vm/installed-apps.json`, archived copies under `<profile>/.apk-vm/apks`) and re-installs missing packages on the next boot (`autoReinstall`). |
|
|
926
|
+
| Memory | [lib/memory.js](lib/memory.js) | Host RAM snapshot, effective instance cap derived from RAM, `standard` / `lite` preset resolution and the low-memory start checks used by `lib/instances.js`; exposed as `memory` on `GET /apk-vm/state`, `/apk-vm/emulators` and `/apk-vm/instances`. |
|
|
868
927
|
| Streaming | scrcpy 5.0.1 server (`lib/vendor/scrcpy-server-v5.0.1.jar`, pushed to `/data/local/tmp/scrcpy-server.jar`) + [lib/scrcpy.js](lib/scrcpy.js) | H.264 screen capture and the scrcpy control protocol, without the desktop scrcpy client. |
|
|
869
928
|
| Device bridge | `adb` from Android SDK platform-tools | install / launch / screencap / input / logcat / file push-pull. |
|
|
870
929
|
| Plugin runtime | DSH plugin APIs (`slots`, `locale`, `webServer`, `tools`, `dsh.client`) | Sidebar entry, main panel, same-origin HTTP/WebSocket control plane, agent tool. |
|
|
@@ -1095,6 +1154,13 @@ screen legitimately shows a low FPS. The 60 Hz animation test sustains ~59 fps o
|
|
|
1095
1154
|
The `Target FPS` selector applies only to the PNG fallback; the H.264 path is capped by
|
|
1096
1155
|
`scrcpyMaxFps`.
|
|
1097
1156
|
|
|
1157
|
+
Host memory is the other cost driver: each local emulator costs roughly 2–3 GB (1.5 GB AVD RAM
|
|
1158
|
+
plus qemu/GPU overhead). With `memoryGuard: true` the effective instance cap is derived from
|
|
1159
|
+
total RAM minus `hostReserveMb` (4 GB) divided by `estimatedVmMb` (3 GB), then clamped by
|
|
1160
|
+
`maxInstances`: 8 GB → 1 VM, 16 GB → 3 (the default requested cap), 32 GB+ → 3. A 16 GB desktop
|
|
1161
|
+
that also runs an IDE and a browser is happier with `maxInstances: 2`; `vmPreset: lite` lowers
|
|
1162
|
+
the guest to 1 GB / 2 vCPU / SwiftShader and a 720p30 stream when you need a third.
|
|
1163
|
+
|
|
1098
1164
|
---
|
|
1099
1165
|
|
|
1100
1166
|
## Verification
|
|
@@ -1188,16 +1254,33 @@ card starts provisioning automatically; while it runs you see the current step p
|
|
|
1188
1254
|
|
|
1189
1255
|
### Auto-setup fails or is stuck
|
|
1190
1256
|
|
|
1191
|
-
The card shows the last step and the error (`autoSetup.error` in `GET /apk-vm/setup`).
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1257
|
+
The card shows the last step and the error (`autoSetup.error` in `GET /apk-vm/setup`). Each
|
|
1258
|
+
provisioning step is retried automatically (`setupRetries`, default 3, exponential backoff) and
|
|
1259
|
+
downloads that stop transferring data are aborted by a 45 s no-progress watchdog, so a link that
|
|
1260
|
+
dies mid-download recovers instead of hanging. Common causes: no network access to
|
|
1261
|
+
`api.adoptium.net` / `dl.google.com` (or to `github.com`, where Adoptium hosts the JDK archive —
|
|
1262
|
+
the built-in Tsinghua mirror is tried automatically), a proxy or firewall, an antivirus locking
|
|
1263
|
+
freshly extracted files, or less than the required free disk space (`minFreeDiskBytes`, default
|
|
1264
|
+
6 GB, is checked before provisioning). Press **Retry**: the JDK archive is reused when its
|
|
1265
|
+
SHA-256 checksum matches and resumes from a `.partial` file with HTTP Range otherwise; a mirror
|
|
1266
|
+
can be pinned with `jdkMirror` (or `DSH_APK_VM_JDK_MIRROR`). For proxies and mirrors behind the
|
|
1267
|
+
SDK downloads set `networkProxy` (translated to `sdkmanager --proxy_*` flags), `sdkManagerArgs`,
|
|
1268
|
+
`sdkManagerEnv`, or point `commandLineToolsUrl` / `commandLineToolsSha256` at your own tools
|
|
1269
|
+
archive. You can also set `autoSetup: false` and provision manually (see
|
|
1198
1270
|
[step 3](#3-provide-an-android-sdk-system-image-and-avd-automatic-by-default)); parts that already
|
|
1199
1271
|
succeeded are skipped on the next attempt.
|
|
1200
1272
|
|
|
1273
|
+
### The VM refuses to start because the host is low on memory
|
|
1274
|
+
|
|
1275
|
+
With `memoryGuard: true` (default) a local emulator is only started when the host has room for
|
|
1276
|
+
it: total RAM minus `hostReserveMb` (4 GB) divided by `estimatedVmMb` (~3 GB) gives the
|
|
1277
|
+
effective instance cap (`GET /apk-vm/state` → `memory.effectiveMaxInstances`; the panel shows it
|
|
1278
|
+
on the VM instances card). Close other emulators/apps, raise `hostReserveMb`/`estimatedVmMb` only
|
|
1279
|
+
after measuring, set `vmPreset: lite` to shrink new guests to 1 GB / 2 vCPU, enable
|
|
1280
|
+
`memoryPressureReap` (default) so idle VMs are stopped first, or move work to a remote VM
|
|
1281
|
+
(`/apk-vm/remote`, see [Remote VM host over SSH](#remote-vm-host-over-ssh)). `memoryGuard: false`
|
|
1282
|
+
disables the check.
|
|
1283
|
+
|
|
1201
1284
|
### "No usable CPU hypervisor (AEHD/WHPX) was found"
|
|
1202
1285
|
|
|
1203
1286
|
The plugin fails fast (`requireAccel: true` by default) because an x86_64 system image cannot
|
|
@@ -1423,6 +1506,11 @@ before pointing the DSH Web UI at an untrusted network.
|
|
|
1423
1506
|
services; network activity is limited to `autoSetup` provisioning (Temurin JDK from
|
|
1424
1507
|
`api.adoptium.net` or its mirror, then the SDK packages/image through the user's own
|
|
1425
1508
|
`sdkmanager`, which contacts Google's SDK repository) and the same-origin DSH Web server.
|
|
1509
|
+
- **Provisioning proxy/mirror settings stay with the child process.** `networkProxy` is translated
|
|
1510
|
+
into `sdkmanager --proxy_*` flags only, and `sdkManagerArgs` / `sdkManagerEnv` are passed to the
|
|
1511
|
+
child `sdkmanager` invocation only. The plugin never proxies its own requests, and none of these
|
|
1512
|
+
values (including a proxy password) is written to the activity journal or exposed on HTTP
|
|
1513
|
+
routes.
|
|
1426
1514
|
- **The Agent activity log is local-only.** Tool-call journal entries and screenshots are written
|
|
1427
1515
|
under `<profile>/.apk-vm/activity` on this host and are never sent anywhere. They can contain
|
|
1428
1516
|
screen content and command arguments, so clear the journal before sharing a recording of the
|
|
@@ -1464,6 +1552,17 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
|
|
|
1464
1552
|
- **The virtual microphone `file` mode needs a Linux/PulseAudio host.** On Windows only `host`
|
|
1465
1553
|
passthrough is available, and camera/mic changes apply to a running default VM only after it is
|
|
1466
1554
|
restarted.
|
|
1555
|
+
- **The memory guard is an estimate, not a hard limit.** It reads host totals (`os` APIs), assumes
|
|
1556
|
+
`estimatedVmMb` per local VM and refuses/clamps new local VMs, but it cannot stop an externally
|
|
1557
|
+
started emulator and it counts remote sessions as zero host RAM. Set `memoryGuard: false` if the
|
|
1558
|
+
estimate is too conservative for your machine.
|
|
1559
|
+
- **`vmPreset: lite` resizes hardware profiles, not a running guest.** The default AVD's
|
|
1560
|
+
`hw.ramSize`/`hw.cpu.ncore` are rewritten on activation and extra instances get them at create
|
|
1561
|
+
time; an already running VM must be restarted to pick them up.
|
|
1562
|
+
- **Download resume is partial.** The JDK archive resumes from `.partial` with HTTP Range and is
|
|
1563
|
+
checksum-verified on every retry; the command-line-tools archive, SDK packages and system image
|
|
1564
|
+
are retried per step (whole-file), and `sdkmanager` owns its own retry/proxy behaviour. The 45 s
|
|
1565
|
+
no-progress watchdog applies to the JDK and command-line-tools downloads.
|
|
1467
1566
|
|
|
1468
1567
|
- **Windows x64 and Linux x86_64 are the end-to-end verified platforms.** macOS SDK/adb/
|
|
1469
1568
|
emulator/AVD discovery is implemented and `arm64` hosts automatically select the
|