dsh-apk-vm 0.12.4 → 0.13.0
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 +126 -10
- package/CHANGELOG.zh-CN.md +191 -0
- package/README.md +188 -36
- package/client.js +358 -22
- package/cordis.patch.yml +56 -0
- package/docs/AGENTS.md +62 -12
- package/docs/PRIVACY.md +11 -1
- package/docs/RELEASING.md +11 -5
- package/index.js +389 -26
- package/lib/activity-log.js +22 -0
- package/lib/android.js +290 -2
- package/lib/autosetup.js +211 -13
- package/lib/http-owner.js +101 -10
- package/lib/instances.js +484 -11
- package/lib/jdk.js +90 -11
- package/lib/lease-store.js +67 -0
- package/lib/memory.js +272 -0
- package/lib/setup.js +444 -30
- package/lib/storage.js +125 -4
- package/lib/vm-ownership.js +233 -20
- package/package.json +7 -4
package/cordis.patch.yml
CHANGED
|
@@ -45,6 +45,39 @@
|
|
|
45
45
|
# quick reuse. start()/the next Agent action boots it again.
|
|
46
46
|
instanceIdleMs: 900000
|
|
47
47
|
instanceReapIntervalMs: 60000
|
|
48
|
+
# Resident shared default VM: a lease can be released, but the VM and its
|
|
49
|
+
# AVD are never released or deleted. After sharedSuspendAfterMs idle the
|
|
50
|
+
# default VM suspends into its quick-boot snapshot (state "suspended",
|
|
51
|
+
# ~6 s to resume); after sharedStopAfterMs it is marked "stopped" (the
|
|
52
|
+
# snapshot and AVD are kept). Tool calls, panel actions and video clients
|
|
53
|
+
# reset the idle timer and a later start resumes it on demand.
|
|
54
|
+
sharedResident: true
|
|
55
|
+
sharedSuspendAfterMs: 300000
|
|
56
|
+
sharedStopAfterMs: 3600000
|
|
57
|
+
# Operation locks (lock_vm / panel Lock): a locked VM rejects other
|
|
58
|
+
# agents and users until the lock owner (or a local admin) unlocks it.
|
|
59
|
+
# lockEnforcement: all = hard lock for everyone; agents = only other
|
|
60
|
+
# agents are blocked, the local panel can still operate; off = locks are
|
|
61
|
+
# advisory markers only (never block).
|
|
62
|
+
lockEnforcement: all
|
|
63
|
+
# lockControl: all = agents or the panel may lock/unlock; user = only the
|
|
64
|
+
# panel/user can lock/unlock (tool lock_vm/unlock_vm return an error).
|
|
65
|
+
lockControl: all
|
|
66
|
+
# Host memory guard: refuse to start another local VM when the machine is
|
|
67
|
+
# low on memory, and cap the effective instance count from total RAM.
|
|
68
|
+
# A local emulator costs ~2-3 GB (AVD 1.5 GB + qemu/GPU overhead), so
|
|
69
|
+
# with 4 GB reserved for the host this allows 2 VMs on 16 GB and 1 on
|
|
70
|
+
# 8 GB (clamped to 1..8). Remote sessions do not count.
|
|
71
|
+
memoryGuard: true
|
|
72
|
+
# hostReserveMb: 4096
|
|
73
|
+
# estimatedVmMb: 3072
|
|
74
|
+
# Lite mode: smaller AVD hardware profile for memory-constrained hosts
|
|
75
|
+
# (1 GB guest RAM, 2 vCPU, SwiftShader GPU, 1 fps PNG / 720p30 H.264).
|
|
76
|
+
# Applies to the default AVD and to extra instances. standard | lite.
|
|
77
|
+
vmPreset: standard
|
|
78
|
+
# When memory is tight, stop the least recently used idle local VM
|
|
79
|
+
# before creating another one (extra VMs are stopped, never destroyed).
|
|
80
|
+
memoryPressureReap: true
|
|
48
81
|
# H.264 stream: up to 60 fps via the vendored scrcpy server; 960 keeps
|
|
49
82
|
# 540x960 video (plenty for the panel) so software WebCodecs decode can
|
|
50
83
|
# sustain ~60 fps.
|
|
@@ -77,6 +110,29 @@
|
|
|
77
110
|
# Manual (user-triggered only) system-image download from the
|
|
78
111
|
# Environment card; autoSetup does not need this flag.
|
|
79
112
|
allowSetupDownloads: false
|
|
113
|
+
# Download reliability for the zero-config first run: every provisioning
|
|
114
|
+
# step retries transient network failures with exponential backoff
|
|
115
|
+
# (setupRetries, retryDelayMs), no-data stalls are detected by a 45 s
|
|
116
|
+
# no-progress watchdog on the JDK/command-line-tools downloads, and the
|
|
117
|
+
# cumulative free-disk budget is checked before provisioning starts.
|
|
118
|
+
setupRetries: 3
|
|
119
|
+
retryDelayMs: 2000
|
|
120
|
+
# minFreeDiskBytes: 6442450944
|
|
121
|
+
# Optional mirrors/proxies for the Android SDK command-line tools and
|
|
122
|
+
# sdkmanager (the JDK already has jdkMirror). sdkManagerArgs are passed
|
|
123
|
+
# verbatim to sdkmanager; networkProxy becomes --proxy_* flags and is
|
|
124
|
+
# used only by sdkmanager, never by the plugin itself. commandLineToolsUrl
|
|
125
|
+
# overrides the Google command-line-tools archive.
|
|
126
|
+
# commandLineToolsUrl: 'https://example.com/commandlinetools-win-latest.zip'
|
|
127
|
+
# commandLineToolsSha256: '...'
|
|
128
|
+
# sdkManagerArgs: ['--no_https']
|
|
129
|
+
# sdkManagerEnv:
|
|
130
|
+
# SDK_TEST_BASE_URL: 'https://mirror.example.com/android/repository/'
|
|
131
|
+
# networkProxy:
|
|
132
|
+
# host: 127.0.0.1
|
|
133
|
+
# port: 7890
|
|
134
|
+
# user: ''
|
|
135
|
+
# password: ''
|
|
80
136
|
# The VM routes accept root shell/debug actions, so they reject
|
|
81
137
|
# non-loopback clients by default even if the DSH web UI is exposed to
|
|
82
138
|
# the LAN. Set true only behind your own authenticated reverse proxy.
|
package/docs/AGENTS.md
CHANGED
|
@@ -26,9 +26,11 @@ or `GET /apk-vm/guide`. The tool description also points here.
|
|
|
26
26
|
|
|
27
27
|
## Mental model
|
|
28
28
|
|
|
29
|
-
- The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`)
|
|
30
|
-
A VM owned by another conversation returns a
|
|
31
|
-
|
|
29
|
+
- The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`) and are
|
|
30
|
+
persisted to `<profile>/.apk-vm/leases.json`. A VM owned by another conversation returns a
|
|
31
|
+
`vm-busy` error (or `vm-takeover-required` for an admin panel action); `ownerForce: true`
|
|
32
|
+
(alias `force: true`) is an explicit takeover and should only be used when the user asked for
|
|
33
|
+
it. Dedicated (`conversation`/`project`) leases stay reserved for 24 h by default.
|
|
32
34
|
- **Only `ready` VMs accept input.** `info` returns `state`, `root`, `serial`, `size`,
|
|
33
35
|
`density`, `dpr` and `coordinateMap`.
|
|
34
36
|
- `instance` selects the VM: omit it to use the calling agent's assignment (the first
|
|
@@ -74,7 +76,7 @@ or `GET /apk-vm/guide`. The tool description also points here.
|
|
|
74
76
|
(`overlay: true` draws UIAutomator boxes), `record`, `perf`, `rotate`
|
|
75
77
|
- **Instances & leases:** `list_instances`, `create_instance`, `rename_instance`, `destroy_instance`,
|
|
76
78
|
`owner_status`, `claim_vm`, `release_vm`, `ownerScope` (`shared|conversation|project`),
|
|
77
|
-
`ownerForce`
|
|
79
|
+
`ownerForce` (alias `force`)
|
|
78
80
|
- **Network / environment:** `network`, `proxy`, `env_snapshot`, `env_restore`, `install_ca`
|
|
79
81
|
- **Flows and skills:** `flow_*` (record/replay a journey), `skill_*` (persisted app-operation
|
|
80
82
|
skills with a Control Codebook), `control_*` (semantic-code tap/input, more layout-stable
|
|
@@ -116,10 +118,13 @@ call. `action=guide` is always available and never touches a VM.
|
|
|
116
118
|
|
|
117
119
|
## Shared vs dedicated VMs
|
|
118
120
|
|
|
119
|
-
The default instance is a **shared** device: every conversation may use it, it is
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
and
|
|
121
|
+
The default instance is a **shared, resident** device: every conversation may use it, and it is
|
|
122
|
+
never released or deleted. When idle for `sharedSuspendAfterMs` (5 min) it suspends into its
|
|
123
|
+
quick-boot snapshot (state `suspended`; a start resumes it in ~6 s); after `sharedStopAfterMs`
|
|
124
|
+
(1 h) suspended it is marked `stopped`. The AVD and snapshot are kept. Any `apk_vm` call, panel
|
|
125
|
+
action or video client resets the idle timer, and a later start resumes it on demand.
|
|
126
|
+
Entering it from a different conversation resets the guest to the home screen (so you never
|
|
127
|
+
inherit someone else's foreground app). Use it for one-off inspection and short automations.
|
|
123
128
|
|
|
124
129
|
If this conversation needs a long-lived debugging device — logins, installed apps, stable
|
|
125
130
|
state — claim a dedicated VM instead of holding the shared one:
|
|
@@ -130,7 +135,22 @@ state — claim a dedicated VM instead of holding the shared one:
|
|
|
130
135
|
- `owner_status` inspects leases; `release_vm` gives a VM back.
|
|
131
136
|
|
|
132
137
|
Don't keep several agents on one shared VM. Leases are visible in the panel, and a VM owned
|
|
133
|
-
by another conversation returns `vm-busy` unless you force a takeover (`ownerForce=true
|
|
138
|
+
by another conversation returns `vm-busy` unless you force a takeover (`ownerForce=true`, alias
|
|
139
|
+
`force=true`). Dedicated reservations survive plugin restarts; the panel needs an explicit takeover
|
|
140
|
+
(`x-apk-vm-takeover: 1`) for a VM held by another owner.
|
|
141
|
+
|
|
142
|
+
## VM operation locks
|
|
143
|
+
|
|
144
|
+
`lock_vm` / `unlock_vm` (or `POST /apk-vm/ownership` actions `lock`/`unlock`) make the current
|
|
145
|
+
owner's lease a hard lock. While locked, every mutating request from another agent or the panel
|
|
146
|
+
is rejected with `409 vm-locked`; `ownerForce`/takeover cannot break it. The panel owner card
|
|
147
|
+
shows the lock and offers Lock/Unlock; a local admin can force-unlock. A lock does not block
|
|
148
|
+
read-only calls (`owner_status`, `list_instances`, `info`).
|
|
149
|
+
|
|
150
|
+
The plugin configuration can relax this: `lockEnforcement: agents` blocks only other agents
|
|
151
|
+
(the local panel can still operate a locked VM) and `off` makes locks advisory only;
|
|
152
|
+
`lockControl: user` limits lock/unlock to the panel/user (`lock_vm`/`unlock_vm` return a
|
|
153
|
+
`vm-lock-restricted` error).
|
|
134
154
|
|
|
135
155
|
## Instances and remote VMs
|
|
136
156
|
|
|
@@ -142,6 +162,26 @@ by another conversation returns `vm-busy` unless you force a takeover (`ownerFor
|
|
|
142
162
|
- Each instance has its own WebSocket (`/apk-vm/instances/<id>/ws`), unless the panel falls back
|
|
143
163
|
to PNG frames.
|
|
144
164
|
|
|
165
|
+
## Host memory, Lite mode and instance caps
|
|
166
|
+
|
|
167
|
+
A local emulator costs roughly 2–3 GB of host RAM. With `memoryGuard` on (the default) the
|
|
168
|
+
effective `maxInstances` is derived from total host RAM (`hostReserveMb` 4 GB reserve,
|
|
169
|
+
`estimatedVmMb` 3 GB per VM): **8 GB → 1 VM, 16 GB → 3 with the default requested cap,
|
|
170
|
+
32 GB+ → 3**. A 16 GB desktop that also runs an IDE and a browser is happier with
|
|
171
|
+
`maxInstances: 2`, or with `vmPreset: lite` (1 GB guest RAM / 2 vCPU / SwiftShader / 720p30),
|
|
172
|
+
which can fit a third VM.
|
|
173
|
+
|
|
174
|
+
- `create_instance` / local starts can fail with a `host memory guard` error: stop an idle
|
|
175
|
+
instance, lower `maxInstances`, or pass `memoryOverride: true` when you knowingly
|
|
176
|
+
over-commit.
|
|
177
|
+
- `memoryPressureReap` (on by default) stops the least-recently-used idle local VM when free
|
|
178
|
+
host memory is low; extra VMs are only stopped, never destroyed.
|
|
179
|
+
- `list_instances`, `GET /apk-vm/state` and `/apk-vm/emulators` expose the same `memory`
|
|
180
|
+
object: `effectiveMaxInstances`, `requestedMaxInstances`, `limited`, `host.freeMb/totalMb`,
|
|
181
|
+
the active `profile` and `pressureReap`.
|
|
182
|
+
- The guard estimates from host totals: an emulator started outside the plugin, and remote
|
|
183
|
+
sessions, are not counted. Use Lite mode on 8–16 GB hosts when running several agents.
|
|
184
|
+
|
|
145
185
|
## VM names and per-conversation selection
|
|
146
186
|
|
|
147
187
|
- Every VM can have a human-friendly display name; ids stay stable (`default`, `frontend`,
|
|
@@ -159,11 +199,21 @@ by another conversation returns `vm-busy` unless you force a takeover (`ownerFor
|
|
|
159
199
|
readiness usually arrives within a couple of seconds.
|
|
160
200
|
- Screenshot or device timeouts return structured error codes (for example
|
|
161
201
|
`EDEVICE_UNRESPONSIVE`); if the guest is wedged, `stop` + `start` is the recovery.
|
|
162
|
-
- `vm-busy`: inspect with `owner_status`; `release_vm` frees a lease,
|
|
163
|
-
`ownerForce: true` is an explicit takeover.
|
|
202
|
+
- `vm-busy` / `vm-takeover-required`: inspect with `owner_status`; `release_vm` frees a lease,
|
|
203
|
+
`claim_vm` with `ownerForce: true` (alias `force: true`) is an explicit takeover. A reserved
|
|
204
|
+
lease stays reserved until `reservedUntil`, even across plugin restarts.
|
|
164
205
|
- Failed calls are journaled too (`ok: false` with the error); read the activity log before
|
|
165
206
|
retrying the same action.
|
|
166
|
-
|
|
207
|
+
- Destructive actions need explicit confirmation: `destroy_instance` requires `confirm: true`,
|
|
208
|
+
and `clean_storage` requires `confirm: true` for `snapshots`, `orphan-avds`,
|
|
209
|
+
`corrupt-snapshots` and `crash-dumps`. Never set `confirm` before checking the instance name
|
|
210
|
+
and the reported reclaimable bytes.
|
|
211
|
+
- An action that has to boot a VM now fails after about 120 s (explicit `start`: 180 s) with an
|
|
212
|
+
actionable error instead of blocking for the 20-minute boot timeout; inspect `state`/
|
|
213
|
+
`logTail`, stop a wedged VM, then retry.
|
|
214
|
+
|
|
215
|
+
- `vm-locked`: the VM is hard-locked by its owner; `ownerForce`/takeover does not override a
|
|
216
|
+
lock. The lock owner can `unlock_vm`; the local panel offers Unlock (admin can force-unlock).
|
|
167
217
|
## Suggested agent instructions
|
|
168
218
|
|
|
169
219
|
```text
|
package/docs/PRIVACY.md
CHANGED
|
@@ -30,6 +30,12 @@ reporting, advertising or a remote backend.
|
|
|
30
30
|
default) and can be cleared from the panel or with `POST /apk-vm/activity/clear`.
|
|
31
31
|
Because entries can contain screen content and command arguments (typed text is recorded
|
|
32
32
|
as a character count only), clear the journal before sharing the panel or its recordings.
|
|
33
|
+
- **Persisted VM leases.** `<profile>/.apk-vm/leases.json` stores the owner key, scope, session id,
|
|
34
|
+
workspace, display label and dedicated-reservation deadline for VM leases so that a
|
|
35
|
+
`conversation`/`project` VM stays reserved across DSH restarts. It is written only for VM
|
|
36
|
+
ownership bookkeeping, stays on this host and contains no screen content; delete the file
|
|
37
|
+
(or release the lease) to clear it. Leases record the DSH session id and workspace path, which
|
|
38
|
+
may be visible to other local conversations if the panel or activity log is shared.
|
|
33
39
|
- **Remembered installed apps.** `<profile>/.apk-vm/installed-apps.json` stores the APK path,
|
|
34
40
|
package name, label, launch activity and instance for APKs installed through the plugin, and
|
|
35
41
|
archived copies live under `<profile>/.apk-vm/apks` (newest 10). Both stay on this host and are
|
|
@@ -50,7 +56,11 @@ reporting, advertising or a remote backend.
|
|
|
50
56
|
base. Every archive is verified against Adoptium's published SHA-256 checksum; the plugin sends
|
|
51
57
|
no identifying headers, cookies or user data. It then runs the user's own `sdkmanager` for the
|
|
52
58
|
Android SDK command-line tools, build-tools, platform and system image from the official Google
|
|
53
|
-
Android SDK repository. The plugin does not proxy or collect those downloads.
|
|
59
|
+
Android SDK repository. The plugin does not proxy or collect those downloads. Optional
|
|
60
|
+
overrides (`jdkMirror`, `commandLineToolsUrl`/`commandLineToolsSha256`, `sdkManagerArgs`,
|
|
61
|
+
`sdkManagerEnv`, `networkProxy`) only redirect the plugin's own downloader and the
|
|
62
|
+
`sdkmanager` child process to a user-chosen mirror or proxy; proxy credentials passed this way
|
|
63
|
+
are used only for that child process and are never logged. Those downloads
|
|
54
64
|
are size- and time-bounded and HTTPS-only, and can be disabled with `autoSetup: false` (the
|
|
55
65
|
Environment card then offers the manual actions as before). No analytics, telemetry,
|
|
56
66
|
advertising or remote backend is involved, and no third-party endpoint other than the ones
|
package/docs/RELEASING.md
CHANGED
|
@@ -8,12 +8,13 @@ Repository: <https://github.com/yuxiaole-bili/dsh-apk-vm>.
|
|
|
8
8
|
## Publish to npm
|
|
9
9
|
|
|
10
10
|
The package is intentionally public and has no build step; publishing the repository directory is
|
|
11
|
-
enough
|
|
11
|
+
enough. **The default registry on the reference host is a mirror (`registry.npmmirror.com`);
|
|
12
|
+
publishing must target npm explicitly**, otherwise `npm publish` fails with `E404`:
|
|
12
13
|
|
|
13
14
|
```bash
|
|
14
|
-
npm
|
|
15
|
-
npm publish --access public
|
|
16
|
-
npm view dsh-apk-vm version
|
|
15
|
+
npm whoami --registry=https://registry.npmjs.org # once per machine/account
|
|
16
|
+
npm publish --access public --registry=https://registry.npmjs.org
|
|
17
|
+
npm view dsh-apk-vm version --registry=https://registry.npmjs.org # verify
|
|
17
18
|
```
|
|
18
19
|
|
|
19
20
|
The GitHub release tarball and the npm tarball are produced from the same `npm pack` output.
|
|
@@ -78,7 +79,10 @@ The in-app Plugin Manager title/description comes from `locale/en.json` and `loc
|
|
|
78
79
|
|
|
79
80
|
## Versioning
|
|
80
81
|
|
|
81
|
-
- `package.json` and `CHANGELOG.md` move together
|
|
82
|
+
- `package.json`, `CHANGELOG.md` and `CHANGELOG.zh-CN.md` move together (the Chinese file mirrors
|
|
83
|
+
the 0.12.x entries; the pre-0.12 history stays English-only in `CHANGELOG.md`).
|
|
84
|
+
- `client.js` `CLIENT_VERSION` must match `package.json`; `npm run check` runs
|
|
85
|
+
`scripts/check-version.mjs` and fails the release if they disagree.
|
|
82
86
|
- Use `0.x.y` while the plugin API/route surface may still change.
|
|
83
87
|
- Keep `SECURITY.md` supported-version table in sync.
|
|
84
88
|
- Tag the release (`git tag -a v0.3.12 -m ...`) and attach the tarball produced by
|
|
@@ -94,6 +98,8 @@ The in-app Plugin Manager title/description comes from `locale/en.json` and `loc
|
|
|
94
98
|
- [ ] Demo media (if any) recorded on a real host and listed in `docs/README.md`
|
|
95
99
|
- [ ] README install instructions use `<path-to-repo>` / user-chosen paths
|
|
96
100
|
- [ ] Release notes call out known limitations (Windows E2E only, no audio, etc.)
|
|
101
|
+
- [ ] `CHANGELOG.zh-CN.md` updated for the release (0.12.5+ promise; keep it in sync with
|
|
102
|
+
`CHANGELOG.md`)
|
|
97
103
|
|
|
98
104
|
## Known limitations to state in the release
|
|
99
105
|
|