dsh-apk-vm 0.12.2 → 0.12.4

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 CHANGED
@@ -1,5 +1,56 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.4
4
+
5
+ ### Fixed
6
+
7
+ - **Hypervisor detection regression from 0.12.3.** A refactor of the boot-speed
8
+ bookkeeping dropped three constructor initialisers (`_accelAvailable`,
9
+ `_snapshotSave`, `_lastLaunchArgs`). `_accelAvailable` stayed `undefined`, so
10
+ `_detectAcceleration()` short-circuited on `!== null` and returned
11
+ `undefined`; every start then failed with a bogus "No usable CPU hypervisor
12
+ (AEHD/WHPX) was found" error even on hosts where `emulator -accel-check`
13
+ reported AEHD/WHPX usable. The fields are restored, and
14
+ `spike/snapshot-recovery-test.mjs` now asserts their initial values and that
15
+ `_detectAcceleration()` returns a boolean, so this regression cannot silently
16
+ ship again.
17
+
18
+ ## 0.12.3
19
+
20
+ ### Added
21
+
22
+ - **Agent playbook.** [`docs/AGENTS.md`](docs/AGENTS.md) ships with the package and is readable
23
+ at runtime with `apk_vm` action `guide` (or `GET /apk-vm/guide`); the tool description,
24
+ README and docs link to it. The guide covers the standard loop, the action map,
25
+ device-pixel vs CSS-coordinate rules, WebView/CDP usage, instances and remote sessions,
26
+ error recovery and safety boundaries.
27
+
28
+ - **Forced onboarding for new conversations.** The first `apk_vm` call in a new conversation
29
+ now returns `docs/AGENTS.md` once (`result.guideRequired: true`) and executes nothing; repeat
30
+ the call after reading it. `action=guide` stays available at any time.
31
+ - **Shared vs dedicated VM guidance.** The guide and README explain that the default instance is
32
+ a shared, short-lived device, recommend claiming a dedicated VM for long-lived debugging, and
33
+ note that entering the shared VM from another conversation resets the guest to its home screen
34
+ (`input keyevent KEYCODE_HOME` + keyguard dismissal).
35
+ - **Quick-boot snapshot self-healing.** A snapshot that crashes the emulator on restore (Windows
36
+ access violation `0xC0000005`) or that looks partially written (`snapshot.pb` much newer than
37
+ `ram.bin`) is quarantined automatically, retried once as a cold boot, and rebuilt; the
38
+ quarantine path is exposed as `status().snapshotRecovery`.
39
+ - **Named VMs and per-conversation auto-selection.** Every instance (including `default` and
40
+ remote sessions) can carry a persisted display name (`<profile>/.apk-vm/instance-names.json`);
41
+ rename with `apk_vm` action `rename_instance`, `POST /apk-vm/instances {"action":"rename",…}`
42
+ or the panel Rename button. The panel follows the current conversation and selects the VM
43
+ whose lease belongs to the active session instead of always showing the shared default.
44
+
45
+ ### Changed
46
+
47
+ - **DSH compatibility metadata.** `package.json` now declares `engines.dsh`
48
+ (`>=0.2.1-rc.3 || >=0.2.2-rc.1`) and `dsh.compatibility.dshReleases` (`0.2.1-rc.3+`,
49
+ `0.2.2-rc.1+` → `compatible`), so the plugin manager and market can verify supported DSH
50
+ releases before install/activation instead of failing at runtime. README now has a
51
+ "Supported DSH versions" section (tested: DSH Desktop 0.2.1-rc.3 and 0.2.2-rc.3) and
52
+ `docs/SUBMISSION.md` lists the same tested matrix.
53
+
3
54
  ## 0.12.2
4
55
 
5
56
  ### Fixed
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.2` · Apache-2.0 · no npm runtime dependencies · no build step.
48
+ **Status:** `0.12.4` · 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).
@@ -113,9 +113,22 @@ and Agent-facing UI automation for development workflows.
113
113
  the system image — roughly 2.5 GB on a cold machine), for manual downloads you trigger, or
114
114
  when you configure a remote adb device.
115
115
 
116
+ **Supported DSH versions**
117
+
118
+ The package declares its DSH compatibility in `package.json` so the plugin manager and market can
119
+ check it before install and activation:
120
+
121
+ - `engines.dsh`: `>=0.2.1-rc.3 || >=0.2.2-rc.1` — tested against DSH Desktop `0.2.1-rc.3`
122
+ (static bundle/plugin APIs) and DSH Desktop `0.2.2-rc.3` (current reference host: release
123
+ `0.2.2-rc.3`, Node `24.21.0`, host protocol v4). Older DSH releases are rejected by the plugin
124
+ manager as `incompatible-version`; a version exemption can still be granted manually.
125
+ - `dsh.compatibility.dshReleases`: `0.2.1-rc.3+`, `0.2.2-rc.1+` → `compatible` (market metadata).
126
+ - DSH releases newer than the tested range are expected to work through the stable static
127
+ bundle/plugin APIs, but are not claimed as verified here. See the
128
+ [DSH plugin API documentation](https://dsh-plugin.org/) for the bundle/plugin contract.
129
+
116
130
  **Compatibility**
117
131
 
118
- - Tested with DSH Desktop `0.2.1-rc.3` (static bundle/plugin APIs).
119
132
  - Windows x64 and Linux x86_64 (headless, KVM + SwiftShader) are verified end-to-end
120
133
  (boot, H.264, rooted debug, APK install, Agent tool). macOS has SDK discovery + headless CI
121
134
  coverage but no live emulator run in this repository.
@@ -485,6 +498,13 @@ or `project`), session id, workspace, and `since` / `lastSeenAt` timestamps; lea
485
498
  secrets (the SSH key path stays on this host) and is persisted under
486
499
  `<profile>/.apk-vm/remote-profile.json`, so the panel card prefills after a restart. Only the
487
500
  fixed command shape is executed; every value is validated and single-quote escaped.
501
+ - **Named VMs and per-conversation selection.** Give any VM (including `default` and remote
502
+ sessions) a display name with `apk_vm {"action":"rename_instance","instance":"default","name":"QA
503
+ phone"}` or `POST /apk-vm/instances {"action":"rename","instance":"…","name":"…"}`; the panel
504
+ has a Rename button in the Instances card. Names persist under
505
+ `<profile>/.apk-vm/instance-names.json`, and `list_instances` / `GET /apk-vm/instances`
506
+ include `name`. The panel auto-selects the VM owned by the current conversation (falling
507
+ back to `default`), so a multi-agent setup no longer always shows one fixed VM.
488
508
  - **Named AVD snapshots.** `GET /apk-vm/snapshots` lists snapshots;
489
509
  `POST /apk-vm/snapshots {"action":"save|load|delete","name":"…"}` manages them. The quick-boot
490
510
  snapshot (`snapshotName`, default `default_boot`) is handled automatically. The panel's
@@ -905,6 +925,7 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
905
925
  | POST | `/apk-vm/device` | `{"serial":"<adb-serial>"}` attach an online physical/network device; `{"serial":""}` detach and restore the managed AVD. |
906
926
  | GET/POST | `/apk-vm/remote` | Multi-session SSH-proxied VMs: `POST {"action":"connect","profile":{host,user,keyPath?,sshPort?,remotePort?,avdName?,launch?},"connectTimeoutMs"?}`, `{"action":"disconnect","id"?,"stopEmulator"?,"detachDevice"?}`, `{"action":"remove-session","id"?}`, `{"action":"status"}`, `{"action":"save-profile"}`, `{"action":"forget-profile","id"?}`; `GET` returns `{sessions,profiles,counts,…}`. |
907
927
  | GET | `/apk-vm/emulators` | Merged local + remote emulator inventory (`local`, `remotes[]`, `updatedAt`). |
928
+ | GET | `/apk-vm/guide` | Agent playbook (`docs/AGENTS.md`) as Markdown; same content as `apk_vm` action `guide`. |
908
929
  | GET/POST | `/apk-vm/camera` | Virtual camera settings: `POST {"action":"save"|"apply","camera":{back,front,posters[]},"restart"?}`. |
909
930
  | GET/POST | `/apk-vm/mic` | Virtual microphone settings: `POST {"action":"save"|"apply","mic":{mode,backend,filePath},"restart"?}`. |
910
931
  | POST | `/apk-vm/vm` | `{"action":"start"\|"stop"\|"restart"\|"snapshot"}`. |
@@ -921,8 +942,8 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
921
942
  | POST | `/apk-vm/stream/quality` | `{"preset":"low\|balanced\|high"}` — change H.264 resolution/bitrate/fps; the scrcpy session reconnects. |
922
943
  | GET (upgrade) | `/apk-vm/ws` | WebSocket H.264 stream (see above). |
923
944
  | GET/POST | `/apk-vm/ownership` | `GET` lists VM leases; `POST {"action":"claim\|release\|touch","instanceId":"default","ownerScope":"shared\|conversation\|project","sessionId"?,"workspace"?,"force"?}` manages the owner lease. |
924
- | GET | `/apk-vm/instances` | List default + extra VM instances, including `owner`, `ownerInfo` (`key`, `label`, `scope`, `sessionId`, `workspace`, `since`, `lastSeenAt`), `lastUsedAt`, `idleMs`, `idleTimeoutMs`, `videoClients`. |
925
- | POST | `/apk-vm/instances` | `{"name":"agent-a","start":true}` — create an isolated AVD/VM; every extra instance has its own H.264 stream. |
945
+ | GET | `/apk-vm/instances` | List default + extra VM instances, including `name`, `owner`, `ownerInfo` (`key`, `label`, `scope`, `sessionId`, `workspace`, `since`, `lastSeenAt`), `lastUsedAt`, `idleMs`, `idleTimeoutMs`, `videoClients`. |
946
+ | POST | `/apk-vm/instances` | `{"name":"agent-a","start":true}` — create an isolated AVD/VM; every extra instance has its own H.264 stream. `{"action":"rename","instance":"default","name":"QA phone"}` sets a display name. |
926
947
  | DELETE | `/apk-vm/instances/:id` | Stop/dispose an extra instance (the default cannot be destroyed). |
927
948
  | GET/POST | `/apk-vm/instances/:id/...` | Per-instance mirror of `state`, `frame`, `vm`, `input`, `install`, `upload`, `debug/*`. |
928
949
  | GET | `/apk-vm/activity?limit=&beforeId=&action=&instanceId=&ok=` | Agent activity journal, newest first, with `stats`; `enabled: true`. |
@@ -992,6 +1013,18 @@ plus `start` / `stop` and instance management (`list_instances`, `create_instanc
992
1013
  `destroy_instance`). It calls the same Host methods as the HTTP routes and the panel (no
993
1014
  duplicated logic).
994
1015
 
1016
+ An agent-facing playbook ships in [docs/AGENTS.md](docs/AGENTS.md) and is readable at runtime
1017
+ with `{"action":"guide"}` (or `GET /apk-vm/guide`): the standard loop, action map,
1018
+ device-pixel vs CSS-coordinate rules, WebView/CDP usage, instance and remote-session handling,
1019
+ and error recovery.
1020
+
1021
+ The **first `apk_vm` call in a new conversation** returns that guide once
1022
+ (`result.guideRequired: true`) and executes nothing: read it, then repeat the call. The default
1023
+ instance is a shared, short-lived device; when a conversation needs a long-lived debugging VM,
1024
+ claim a dedicated one with `ownerScope=conversation`/`project` (or `create_instance`) instead of
1025
+ holding the shared VM. Entering the shared VM from a different conversation resets the guest to
1026
+ its home screen.
1027
+
995
1028
  For concurrent Agents, pass `instance` to target a specific VM; when omitted, the tool resolves
996
1029
  the calling Agent's lease and assigned instance (first conversation → default VM, later
997
1030
  conversations → isolated instances created on demand until `maxInstances`). Set
@@ -1210,6 +1243,12 @@ is not expected to finish booting that way.
1210
1243
  `%USERPROFILE%\.android\avd\<avdName>.avd\snapshots\<snapshotName>`), then start cold again.
1211
1244
  - A snapshot directory with `ram.img` but no `snapshot.pb` is not a valid snapshot; the plugin
1212
1245
  ignores it. Delete it or set `quickBoot: false` once to force a clean cold boot.
1246
+ - **Corrupt snapshots heal themselves.** If restoring the quick-boot snapshot crashes the
1247
+ emulator (`emulator exited (code 3221225477…)`, Windows access violation `0xC0000005`) or the
1248
+ files look partially written (`snapshot.pb` much newer than `ram.bin`), the plugin quarantines
1249
+ the directory as `snapshots/<name>.corrupt-<timestamp>`, retries once as a cold boot and
1250
+ rebuilds a fresh snapshot. The quarantine path is reported in `status().snapshotRecovery`; the
1251
+ old directory can be deleted.
1213
1252
  - If a stale offline adb emulator is attached, `adb kill-server` (or kill the leftover
1214
1253
  `emulator`/`qemu-system-*` process) and retry.
1215
1254
 
package/client.js CHANGED
@@ -30,7 +30,7 @@ window.__ModuleLoader__.load({
30
30
  var SWIPE_THRESHOLD_PX = 24;
31
31
  var FRAME_INTERVAL_MS = 500;
32
32
  var STATE_INTERVAL_MS = 2000;
33
- var CLIENT_VERSION = '0.12.2';
33
+ var CLIENT_VERSION = '0.12.4';
34
34
 
35
35
  /* ------------------------------------------------------------------ *
36
36
  * Optional dsh-better-sidebar integration.
@@ -392,6 +392,9 @@ window.__ModuleLoader__.load({
392
392
  'instances.created': 'Created instance {id}',
393
393
  'instances.destroyed': 'Destroyed instance {id}',
394
394
  'instances.manage': 'VM instances',
395
+ 'instances.rename': 'Rename',
396
+ 'instances.renamePrompt': 'Display name for this VM',
397
+ 'instances.renamed': 'Renamed VM to {name}',
395
398
  'grid.title': 'Grid view',
396
399
  'grid.empty': 'No running instances to show.',
397
400
  'grid.close': 'Close grid',
@@ -795,6 +798,9 @@ window.__ModuleLoader__.load({
795
798
  'instances.created': '已创建实例 {id}',
796
799
  'instances.destroyed': '已销毁实例 {id}',
797
800
  'instances.manage': '虚拟机实例',
801
+ 'instances.rename': '重命名',
802
+ 'instances.renamePrompt': '为这台虚拟机设置显示名称',
803
+ 'instances.renamed': '已重命名为 {name}',
798
804
  'grid.title': '网格视图',
799
805
  'grid.empty': '没有正在运行的实例。',
800
806
  'grid.close': '关闭网格',
@@ -2184,6 +2190,24 @@ window.__ModuleLoader__.load({
2184
2190
  var tabVisible = propsSafe.visible === undefined ? true : propsSafe.visible !== false;
2185
2191
  var wideDashboard = useWideDashboard() && !embedded;
2186
2192
 
2193
+ /* `main` slot pages do not receive a Session binding, but root-scoped
2194
+ pages do get the `useSessions` hook: use it to follow the current
2195
+ conversation and auto-select the VM that conversation owns. */
2196
+ var useSessions = typeof propsSafe.useSessions === 'function' ? propsSafe.useSessions : null;
2197
+ var currentSessionId = useSessions
2198
+ ? useSessions(function (state) {
2199
+ var byId = state && isObject(state.byId) ? state.byId : {};
2200
+ var ids = Object.keys(byId);
2201
+ for (var i = 0; i < ids.length; i += 1) {
2202
+ var session = byId[ids[i]];
2203
+ if (session && isObject(session.retainedBy) && Number(session.retainedBy.mainView) > 0) {
2204
+ return session.id || ids[i];
2205
+ }
2206
+ }
2207
+ return null;
2208
+ })
2209
+ : null;
2210
+
2187
2211
  /* ---- state ---------------------------------------------------- */
2188
2212
  var snapshotState = React.useState(null);
2189
2213
  var snapshot = snapshotState[0];
@@ -2523,6 +2547,8 @@ window.__ModuleLoader__.load({
2523
2547
  var activeInstance = activeInstanceState[0];
2524
2548
  var setActiveInstance = activeInstanceState[1];
2525
2549
  var activeInstanceRef = React.useRef('default');
2550
+ var userPickedInstanceRef = React.useRef(false);
2551
+ var lastAutoSessionRef = React.useRef(null);
2526
2552
  var instancesListState = React.useState([]);
2527
2553
  var instancesList = instancesListState[0];
2528
2554
  var setInstancesList = instancesListState[1];
@@ -2905,6 +2931,28 @@ window.__ModuleLoader__.load({
2905
2931
  };
2906
2932
  }, []);
2907
2933
 
2934
+ // Follow the conversation: select the VM owned by the current session
2935
+ // (once per session, unless the user picked a VM manually).
2936
+ React.useEffect(function () {
2937
+ if (!currentSessionId) return;
2938
+ if (lastAutoSessionRef.current !== currentSessionId) {
2939
+ lastAutoSessionRef.current = currentSessionId;
2940
+ userPickedInstanceRef.current = false;
2941
+ }
2942
+ if (userPickedInstanceRef.current) return;
2943
+ var list = Array.isArray(instancesList) ? instancesList : [];
2944
+ var match = null;
2945
+ for (var i = 0; i < list.length; i += 1) {
2946
+ var entry = list[i];
2947
+ var info = entry && isObject(entry.ownerInfo) ? entry.ownerInfo : null;
2948
+ if (info && info.sessionId && String(info.sessionId) === String(currentSessionId)) {
2949
+ match = entry;
2950
+ break;
2951
+ }
2952
+ }
2953
+ if (match && match.id && match.id !== activeInstanceRef.current) setActiveInstanceId(match.id);
2954
+ }, [currentSessionId, instancesList]);
2955
+
2908
2956
  // Load network details once the VM becomes ready (the first render often
2909
2957
  // happens while the state is still loading).
2910
2958
  React.useEffect(function () {
@@ -3504,6 +3552,33 @@ window.__ModuleLoader__.load({
3504
3552
  });
3505
3553
  }
3506
3554
 
3555
+ function renameInstanceById(id) {
3556
+ if (!id || instanceBusy) return;
3557
+ var entry = null;
3558
+ for (var i = 0; i < instancesList.length; i += 1) {
3559
+ if (instancesList[i].id === id) entry = instancesList[i];
3560
+ }
3561
+ var current = entry && entry.name ? entry.name : id;
3562
+ var next = window.prompt(T('instances.renamePrompt'), current);
3563
+ if (next === null) return;
3564
+ var clean = String(next).trim();
3565
+ if (!clean || clean === current) return;
3566
+ setInstanceBusy(true);
3567
+ requestJson('/apk-vm/instances', {
3568
+ method: 'POST',
3569
+ body: JSON.stringify({ action: 'rename', instance: id, name: clean }),
3570
+ }, T).then(function (result) {
3571
+ if (!mountedRef.current) return;
3572
+ setInstanceBusy(false);
3573
+ if (!result.ok) {
3574
+ pushToast('error', (result.error || T('err.action')).slice(0, 400));
3575
+ return;
3576
+ }
3577
+ pushToast('success', T('instances.renamed', { name: clean }));
3578
+ loadInstances();
3579
+ });
3580
+ }
3581
+
3507
3582
  function destroyInstanceById(id) {
3508
3583
  if (!id || id === 'default' || instanceBusy) return;
3509
3584
  setInstanceBusy(true);
@@ -5892,7 +5967,7 @@ window.__ModuleLoader__.load({
5892
5967
  h(
5893
5968
  'div',
5894
5969
  { className: 'apkvm-instname', title: entry.id },
5895
- isDefault ? T('instances.default') : entry.id,
5970
+ isDefault ? (entry.name ? entry.name + ' (' + T('instances.default') + ')' : T('instances.default')) : entry.name || entry.id,
5896
5971
  h('span', { className: 'apkvm-dim' }, ' · ' + (entry.state || '?') + (owner ? ' · ' + owner + ownerScope : ''))
5897
5972
  ),
5898
5973
  h(
@@ -5900,12 +5975,25 @@ window.__ModuleLoader__.load({
5900
5975
  { className: 'apkvm-instmeta' },
5901
5976
  idle !== null && !isDefault ? T('instances.idle', { seconds: idle }) : ''
5902
5977
  ),
5903
- isDefault
5904
- ? null
5905
- : h(
5906
- 'div',
5907
- { className: 'apkvm-instactions' },
5908
- h(
5978
+ h(
5979
+ 'div',
5980
+ { className: 'apkvm-instactions' },
5981
+ h(
5982
+ 'button',
5983
+ {
5984
+ type: 'button',
5985
+ className: 'apkvm-mini',
5986
+ title: T('instances.rename'),
5987
+ onClick: function (event) {
5988
+ event.preventDefault();
5989
+ renameInstanceById(entry.id);
5990
+ },
5991
+ },
5992
+ T('instances.rename')
5993
+ ),
5994
+ isDefault
5995
+ ? null
5996
+ : h(
5909
5997
  'button',
5910
5998
  {
5911
5999
  type: 'button',
@@ -5918,7 +6006,9 @@ window.__ModuleLoader__.load({
5918
6006
  },
5919
6007
  T('instances.stop')
5920
6008
  ),
5921
- h(
6009
+ isDefault
6010
+ ? null
6011
+ : h(
5922
6012
  'button',
5923
6013
  {
5924
6014
  type: 'button',
@@ -5931,7 +6021,7 @@ window.__ModuleLoader__.load({
5931
6021
  },
5932
6022
  T('instances.delete')
5933
6023
  )
5934
- )
6024
+ )
5935
6025
  );
5936
6026
  })
5937
6027
  )
@@ -7527,11 +7617,14 @@ window.__ModuleLoader__.load({
7527
7617
  'aria-label': T('instances.label'),
7528
7618
  disabled: instanceBusy,
7529
7619
  onChange: function (event) {
7620
+ userPickedInstanceRef.current = true;
7530
7621
  setActiveInstanceId(event && event.target ? String(event.target.value) : 'default');
7531
7622
  },
7532
7623
  },
7533
7624
  instanceOptions.map(function (entry) {
7534
- var label = entry.id === 'default' ? T('instances.default') : entry.id;
7625
+ var label = entry.id === 'default'
7626
+ ? entry.name ? entry.name + ' (' + T('instances.default') + ')' : T('instances.default')
7627
+ : entry.name || entry.id;
7535
7628
  var owner = entry.owner ? String(entry.owner).replace(/^agent-/, '').slice(0, 10) : '';
7536
7629
  return h(
7537
7630
  'option',
package/cordis.patch.yml CHANGED
@@ -32,6 +32,10 @@
32
32
  # lives in <profile>/.apk-vm/installed-apps.json; uploaded APKs are kept
33
33
  # under <profile>/.apk-vm/apks (newest 10). Set false to opt out.
34
34
  autoReinstall: true
35
+ # The first apk_vm call in a new conversation returns the agent playbook
36
+ # once (docs/AGENTS.md) instead of executing the action. Set false to let
37
+ # new conversations act immediately.
38
+ guideOnNewSession: true
35
39
  # Multiple isolated VMs: the first Agent gets the default instance;
36
40
  # later Agents get their own AVD/port until maxInstances extra VMs.
37
41
  multiInstance: true
package/docs/AGENTS.md ADDED
@@ -0,0 +1,190 @@
1
+ # Agent guide — driving the APK VM
2
+
3
+ This is the playbook for an AI agent using the `apk_vm` tool (or the `/apk-vm/*` HTTP API).
4
+ It is shipped inside the plugin package as `docs/AGENTS.md`.
5
+
6
+ **Read it in-context:** call the tool with `{ "action": "guide" }` (returns this file's Markdown),
7
+ or `GET /apk-vm/guide`. The tool description also points here.
8
+
9
+ ## TL;DR
10
+
11
+ 1. Call `{ "action": "info" }` first; only act when the VM state is `ready`.
12
+ 2. Locate controls with `ui_dump` / `find_ui` / `assert_text`, and click them with
13
+ `tap_text` or `tap_selector`; avoid blind device-pixel coordinates.
14
+ 3. Wait with `wait_for`; verify with `assert_text`; take a `screenshot` or `record` for evidence.
15
+ 4. Pass `instance` when a task targets a specific VM; never take over another session's lease
16
+ without explicit approval.
17
+ 5. The guest is a rooted `userdebug` image — never type real credentials or private data into it.
18
+
19
+ ## Three entry points
20
+
21
+ | Entry | Audience | Notes |
22
+ | --- | --- | --- |
23
+ | `apk_vm` tool | **Agents (first choice)** | Registered globally through `ctx.tools`; every DSH agent can call it. Params: `action`, `instance`, selectors, coordinates, paths. |
24
+ | HTTP API `/apk-vm/*` | Scripts / CI | Same-origin, loopback-only by default. See the route table in `README.md`. |
25
+ | Panel UI | Humans | Environment card, APK list, H.264 preview, debug card, media card, remote sessions, activity timeline. Agents don't need to click it. |
26
+
27
+ ## Mental model
28
+
29
+ - The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`).
30
+ A VM owned by another conversation returns a `vm-busy` error; `ownerForce: true` is an
31
+ explicit takeover and should only be used when the user asked for it.
32
+ - **Only `ready` VMs accept input.** `info` returns `state`, `root`, `serial`, `size`,
33
+ `density`, `dpr` and `coordinateMap`.
34
+ - `instance` selects the VM: omit it to use the calling agent's assignment (the first
35
+ conversation gets `default`; later conversations get isolated instances, up to
36
+ `maxInstances`). Pass `instance: "<id>"` from `list_instances` to target a specific VM.
37
+ - Every call is journaled in the Agent activity log (action, args preview, ok/error, duration,
38
+ screenshots for mutating actions). It is safe to rely on it to reconstruct what happened.
39
+
40
+ ## Standard loop
41
+
42
+ ```jsonc
43
+ // 1. Status and readiness
44
+ { "action": "info" }
45
+ // 2. Start only if needed (autoStart normally already did)
46
+ { "action": "start", "timeoutMs": 300000 }
47
+ // 3. Install and launch an APK (absolute local path)
48
+ { "action": "install", "path": "D:/work/app.apk" }
49
+ // 4. Inspect the accessibility tree before touching anything
50
+ { "action": "ui_dump" }
51
+ // 5. Find and click: text/resource-id/content-desc beat coordinates
52
+ { "action": "find_ui", "text": "Sign in" }
53
+ { "action": "tap_text", "text": "Sign in" }
54
+ // Inside a WebView, click the DOM directly:
55
+ { "action": "tap_selector", "selector": "[data-testid=submit]", "webviewTarget": "0" }
56
+ // 6. Wait for a condition instead of sleeping
57
+ { "action": "wait_for", "text": "Welcome", "timeoutMs": 15000 }
58
+ // 7. Assert, then capture evidence
59
+ { "action": "assert_text", "text": "Hello from dsh-apk-vm", "timeoutMs": 5000 }
60
+ { "action": "screenshot" }
61
+ ```
62
+
63
+ ## Action map
64
+
65
+ - **Lifecycle:** `info`, `start`, `stop`, `devices`, `attach_device`, `detach_device`
66
+ - **Apps & files:** `install`, `push`, `pull` (under `/data/local/tmp`, `/sdcard`,
67
+ `/storage/emulated/0`), `apk_info` (reads APK metadata without booting), `packages`,
68
+ `force_stop`, `clear_data`, `uninstall`
69
+ - **UI automation:** `ui_dump`, `find_ui`, `assert_text`, `tap_text`, `tap`, `swipe`,
70
+ `long_press`, `key`, `text` (device coordinates), `type_text` (UTF-8, Chinese supported)
71
+ - **WebView / CDP:** `webview` (`list|eval|click|wait_for|insert_text|info`), `tap_css`,
72
+ `tap_selector`
73
+ - **Debug:** `shell`, `adb` (raw argv), `logcat`, `getprop`, `setprop`, `root`, `screenshot`
74
+ (`overlay: true` draws UIAutomator boxes), `record`, `perf`, `rotate`
75
+ - **Instances & leases:** `list_instances`, `create_instance`, `rename_instance`, `destroy_instance`,
76
+ `owner_status`, `claim_vm`, `release_vm`, `ownerScope` (`shared|conversation|project`),
77
+ `ownerForce`
78
+ - **Network / environment:** `network`, `proxy`, `env_snapshot`, `env_restore`, `install_ca`
79
+ - **Flows and skills:** `flow_*` (record/replay a journey), `skill_*` (persisted app-operation
80
+ skills with a Control Codebook), `control_*` (semantic-code tap/input, more layout-stable
81
+ than coordinates)
82
+ - **This guide:** `guide` (returns this Markdown; no device access needed)
83
+
84
+ ## Coordinates: three rules
85
+
86
+ 1. `info.coordinateMap` says `device = round(css * dpr) + offset`. Screenshots are **device
87
+ pixels** (for example 720×1280); the WebView viewport is CSS pixels (for example 360×640 at
88
+ `dpr: 2`).
89
+ 2. `tap` / `swipe` / `long_press` take **device pixels**. To click by CSS coordinates use
90
+ `tap_css` (it reads `dpr` / `offsetX` / `offsetY` from `info`) instead of doing the math
91
+ yourself.
92
+ 3. Prefer `tap_selector` (WebView DOM) > `tap_text` / `find_ui` (native UI) > `tap_css` >
93
+ raw `tap`. Raw coordinates break when layouts, keyboards or status bars change.
94
+
95
+ ## WebView specifics
96
+
97
+ - `webview` with `webviewAction: "list"` returns DevTools targets; then use `eval`, `click`,
98
+ `insert_text` or `wait_for` with `targetId` (or `webviewTarget`).
99
+ - `eval` takes a **single JavaScript expression**. Use an IIFE when you need several statements
100
+ and want a value back. Values that cannot cross JSON by value come back as a property
101
+ snapshot (`DOMRect`, `MediaQueryList`, …), so `matchMedia('(pointer: coarse)').matches` works
102
+ directly.
103
+ - Real WebView behaviour (pointer media queries, `position: fixed` clipping, virtual keyboard
104
+ reflow) can differ from headless browsers; verify it with `eval` inside this VM.
105
+
106
+ ```jsonc
107
+ { "action": "webview", "webviewAction": "eval",
108
+ "script": "(() => ({ w: innerWidth, coarse: matchMedia('(pointer: coarse)').matches }))()" }
109
+ ```
110
+
111
+ ## First call in a new conversation
112
+
113
+ The first `apk_vm` call in every new conversation returns this playbook once instead of
114
+ executing the requested action (`result.guideRequired: true`). Read it, then repeat the
115
+ call. `action=guide` is always available and never touches a VM.
116
+
117
+ ## Shared vs dedicated VMs
118
+
119
+ The default instance is a **shared** device: every conversation may use it, it is
120
+ short-lived, and entering it from a different conversation resets the guest to the home
121
+ screen (so you never inherit someone else's foreground app). Use it for one-off inspection
122
+ and short automations.
123
+
124
+ If this conversation needs a long-lived debugging device — logins, installed apps, stable
125
+ state — claim a dedicated VM instead of holding the shared one:
126
+
127
+ - `{"action":"claim_vm","instance":"default","ownerScope":"conversation"}` (or `"project"`)
128
+ reserves the default VM for this conversation/workspace, or
129
+ - `{"action":"create_instance","name":"my-debug","start":true}` starts an isolated extra VM,
130
+ - `owner_status` inspects leases; `release_vm` gives a VM back.
131
+
132
+ 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`).
134
+
135
+ ## Instances and remote VMs
136
+
137
+ - `list_instances` lists `default`, extra instances and remote sessions. Remote sessions appear
138
+ as instances named `remote-<avdName>-<adbPort>` (for example `remote-yuagent_dsh2-5557`).
139
+ - Remote sessions are created from the panel or `POST /apk-vm/remote`; an agent normally just
140
+ discovers them via `list_instances` and passes `"instance": "remote-…"`. Install, input,
141
+ screenshots, UI dumps and the H.264 stream all work the same way.
142
+ - Each instance has its own WebSocket (`/apk-vm/instances/<id>/ws`), unless the panel falls back
143
+ to PNG frames.
144
+
145
+ ## VM names and per-conversation selection
146
+
147
+ - Every VM can have a human-friendly display name; ids stay stable (`default`, `frontend`,
148
+ `remote-…`). `list_instances` entries include `name`.
149
+ - Rename from an agent: `{"action":"rename_instance","instance":"default","name":"QA phone"}`.
150
+ `create_instance`'s `name` doubles as the initial display name when it is a valid id. From
151
+ the panel, use Rename in the Instances card. Names persist in
152
+ `<profile>/.apk-vm/instance-names.json`.
153
+ - The panel follows the current conversation: it auto-selects the VM whose lease belongs to
154
+ the active session (falling back to `default`); a manual selection sticks for that session.
155
+
156
+ ## Errors and recovery
157
+
158
+ - `409 not ready` (for example `/apk-vm/instances/<id>/frame` right after attach): poll again;
159
+ readiness usually arrives within a couple of seconds.
160
+ - Screenshot or device timeouts return structured error codes (for example
161
+ `EDEVICE_UNRESPONSIVE`); if the guest is wedged, `stop` + `start` is the recovery.
162
+ - `vm-busy`: inspect with `owner_status`; `release_vm` frees a lease, `claim_vm` with
163
+ `ownerForce: true` is an explicit takeover.
164
+ - Failed calls are journaled too (`ok: false` with the error); read the activity log before
165
+ retrying the same action.
166
+
167
+ ## Suggested agent instructions
168
+
169
+ ```text
170
+ You can operate a rooted Android VM with the apk_vm tool.
171
+ 1) Call info first; act only when state is ready.
172
+ 2) Find controls with ui_dump/find_ui; click with tap_text or tap_selector (WebView DOM).
173
+ Avoid blind device-pixel taps; screenshots are device pixels and the viewport is CSS pixels.
174
+ 3) Use wait_for instead of sleeping and assert_text to verify results.
175
+ 4) Pass instance when a task targets a specific VM; never steal another session's lease
176
+ without explicit approval.
177
+ 5) Do not type secrets into the guest; it is a rooted userdebug image.
178
+ 6) On failure read the error and the activity log before retrying.
179
+ 7) Call action=guide to re-read docs/AGENTS.md.
180
+ ```
181
+
182
+ ## Boundaries
183
+
184
+ - The guest runs `userdebug` with `adb root`: treat it like a rooted device owned by the user.
185
+ - The `apk_vm` tool is available to every agent in the profile and can install apps, inject
186
+ input and run a root shell. Grant the same trust as a terminal on the guest.
187
+ - `/apk-vm/*` HTTP routes and WebSockets are same-origin and loopback-only by default;
188
+ `allowRemote: true` is an explicit opt-in for remote adb / SSH proxy setups.
189
+ - No telemetry: the plugin only talks to the guest, the local DSH server, and — when you
190
+ explicitly configure it — the user's SDK download or remote SSH host.
package/docs/README.md CHANGED
@@ -18,6 +18,13 @@ Gaussian blur:
18
18
  through the HTTP API → 60 fps animation in the guest. Reproducible from the guest-side
19
19
  screencap loop in [`../DEMO.md`](../DEMO.md); `scripts/make-demo-gif.mjs` re-encodes it.
20
20
 
21
+ ## Agent playbook
22
+
23
+ - `AGENTS.md` — the agent-facing playbook for the `apk_vm` tool: standard loop, action map,
24
+ device-pixel vs CSS-coordinate rules, WebView/CDP usage, instances and remote sessions, error
25
+ recovery and safety boundaries. Readable at runtime with `apk_vm` action `guide` or
26
+ `GET /apk-vm/guide`; the tool description points agents at it.
27
+
21
28
  The assets are not fabricated. Before adding a new screenshot, crop out or mask the DSH sidebar
22
29
  conversation names, local paths and any LAN IPs (Gaussian blur is enough; the raw panel already
23
30
  hides credentials and APK file paths are blur-friendly demo data).
@@ -37,7 +37,9 @@ DSH Desktop(`desktop` profile)通过 **Plugins → add/install local bundle*
37
37
 
38
38
  ### 兼容与运行要求
39
39
 
40
- - DSH Desktop `0.2.1-rc.3` 已实测;静态 bundle/plugin API。
40
+ - DSH Desktop `0.2.1-rc.3` 与 `0.2.2-rc.3` 已实测(静态 bundle/plugin API);`package.json`
41
+ 声明 `engines.dsh: ">=0.2.1-rc.3 || >=0.2.2-rc.1"`、`dsh.compatibility.dshReleases`,插件中心/
42
+ 插件管理器会在安装与激活前检查;更旧的 DSH 版本按 `incompatible-version` 拒绝。
41
43
  - Windows x64 与 Linux x86_64(headless,KVM + SwiftShader)为端到端验证平台(启动、
42
44
  H.264、root 调试、APK 安装、Agent tool);macOS 有 SDK 探测/headless CI 覆盖,但未做
43
45
  真实模拟器运行验证。详见 `docs/LINUX-E2E.md`。