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 CHANGED
@@ -1,5 +1,119 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.13.0
4
+
5
+ ### Added
6
+
7
+ - **Persistent VM leases and reserved dedicated VMs.** Leases are now persisted to
8
+ `<profile>/.apk-vm/leases.json` and restored when the plugin starts, so a dedicated
9
+ `conversation`/`project` VM stays reserved for its owner across DSH restarts instead of being
10
+ handed to the first session that asks. Dedicated leases carry a `reservedUntil` deadline
11
+ (`leaseReservationTtlMs`, default 24 hours); after it expires the VM can be claimed normally
12
+ again.
13
+ - **Explicit and audited takeover.** A lease held by another owner now reports the owner short id
14
+ and reservation deadline in `409 vm-busy` / `409 vm-takeover-required` responses. The panel shows
15
+ the reservation, keeps a VM held by another owner read-only and offers a **Take over** button;
16
+ admin mutations that are not an explicit takeover are rejected with `vm-takeover-required`
17
+ (`x-apk-vm-takeover: 1`) instead of silently operating another owner's VM. Claim, release and
18
+ takeover transitions are recorded in the activity journal with the previous and incoming owner.
19
+ - **`force` alias for `ownerForce`.** `apk_vm` accepts `force: true` as a synonym for
20
+ `ownerForce: true`, so the error text and the actual parameter no longer disagree;
21
+ `claim_vm`/`release_vm` report the previous owner on takeover.
22
+ - **Owner attribution in the activity journal.** Activity entries record `owner`
23
+ (`key`, `label`, `scope`, `role`) — sanitized and redacted like every other field — so "who did
24
+ what" stays visible when several conversations and the panel drive the same machine.
25
+ - **Resident shared default VM.** The default VM is never released or deleted. After
26
+ `sharedSuspendAfterMs` idle (default 5 minutes) it suspends into its quick-boot snapshot (state
27
+ `suspended`, about 6 seconds to resume) and after `sharedStopAfterMs` (default 1 hour) it is
28
+ marked `stopped` with the snapshot and AVD kept. Tool calls, panel actions and video clients
29
+ reset the idle timer and a later start resumes it on demand.
30
+ - **Storage accounting for crash debris and orphan AVDs.** `GET /apk-vm/storage` now reports
31
+ quarantined `*.corrupt-*` snapshot backups, emulator crash dumps and a `reclaimableBytes`
32
+ total. `POST /apk-vm/storage` gained `corrupt-snapshots` and `crash-dumps` actions (both
33
+ require `confirm: true`), and the Storage card shows the reclaimable amount with cleanup
34
+ buttons.
35
+ - **Confirmations for destructive actions.** `destroy_instance` now requires `confirm: true`,
36
+ and the panel asks for a second click, so neither an agent nor a mis-click can delete an
37
+ instance AVD and its data by accident. The instance DELETE route also rejects requests
38
+ without `?confirm=1`.
39
+ - **VM operation locks.** `lock_vm` / `unlock_vm` (and `POST /apk-vm/ownership` actions
40
+ `lock`/`unlock`) turn the caller's lease into a hard lock: while locked, every mutating
41
+ request from another agent or the panel is rejected with `409 vm-locked`; `ownerForce` and
42
+ takeover do not break a lock, and only the lock owner (or a local admin unlock) can control
43
+ the VM. Locks are persisted in `leases.json` and the panel shows Lock/Unlock. Two configuration
44
+ keys tune the policy: `lockEnforcement` (`all` | `agents` | `off`) and `lockControl`
45
+ (`all` | `user`).
46
+
47
+ ### Changed
48
+
49
+ - Panel claim/release no longer forces by default: `POST /apk-vm/ownership` only forces when the
50
+ request body sets `force: true`, and every owner change is journaled.
51
+ - **Bounded tool waits.** An action that has to boot the VM fails after about 120 s (explicit
52
+ `start`: 180 s, override with `timeoutMs`) with an actionable error instead of blocking for the
53
+ 1200 s boot timeout; the VM keeps booting, so a later call can observe it ready, and
54
+ `maybeAutoStart` skips a VM that is in a crash loop.
55
+
56
+ ### Fixed
57
+
58
+ - A reserved lease could be silently taken over by another session or by the admin panel without
59
+ an explicit takeover request.
60
+ - Leases lived only in memory and disappeared on plugin reload, which let dedicated VMs be
61
+ re-assigned after a DSH restart.
62
+ - An explicit `claim_vm` could leave implicit tool calls on the previously assigned VM: claiming
63
+ the default VM now updates the session mapping for the conversation, project and shared scopes,
64
+ so the next call without an `instance` argument resolves to the VM that was just claimed.
65
+ - The activity journal recorded the requested instance id (falling back to `default` when omitted)
66
+ instead of the VM that actually served the call, which hid such mismatches from the log.
67
+
68
+ - A `ReferenceError: recordOwnershipAction is not defined` broke takeovers started from
69
+ `apk_vm` tool calls and the `/apk-vm/ownership` HTTP route (the journal helper was defined
70
+ inside the route mount scope). The helper now lives at plugin scope, so takeovers are
71
+ recorded again.
72
+ - The Windows emulator can crash (status `0xC0000005`) while writing or shortly after writing a
73
+ quick-boot snapshot. Snapshot saves are tracked now: a `start` that arrives during a save
74
+ waits for it to finish, a crash that follows a save disables further quick-boot saving, and
75
+ the partially written snapshot is quarantined and the boot retried once as a cold boot.
76
+ - An incomplete quick-boot snapshot (tiny `ram.bin` or a half-written `snapshot.pb`) is now
77
+ quarantined before launch and the plan uses `-no-snapshot-load` for a cold boot, so a broken
78
+ snapshot can no longer crash the emulator in a restart loop.
79
+ - **Crash-loop breaker.** Three non-zero emulator exits within 15 minutes pause automatic
80
+ recovery/auto-start and disable snapshot saving, with the reason written to the state error
81
+ and logTail; inspect the emulator log/crash dump, then start the VM manually.
82
+
83
+ ## 0.12.5
84
+
85
+ ### Added
86
+
87
+ - **Download reliability for zero-config provisioning.** Every provisioning step now retries
88
+ transient network/command failures (`setupRetries`, default 3, exponential backoff via
89
+ `retryDelayMs`), and a 45 s no-progress watchdog aborts stalled downloads instead of hanging.
90
+ The JDK archive resumes from a `.partial` file with HTTP Range and is re-verified against the
91
+ SHA-256 on every attempt; the command-line-tools download now streams with a stall timeout,
92
+ size bound and optional checksum (`commandLineToolsUrl` / `commandLineToolsSha256`) and can be
93
+ pointed at a mirror; `sdkmanager` accepts mirror/proxy settings (`sdkManagerArgs`,
94
+ `sdkManagerEnv`, `networkProxy`); a cumulative free-disk budget (`minFreeDiskBytes`, default
95
+ 6 GB) is checked before provisioning starts. Retries surface `attempt` and `nextDelayMs` in
96
+ `autoSetup.detail`, and the Environment card shows "retry n/m in Ns" while backing off.
97
+ - **Memory-aware instance management.** New `lib/memory.js` reads host RAM and derives the
98
+ effective instance cap (`memoryGuard`, `hostReserveMb` 4 GB, `estimatedVmMb` 3 GB, clamped to
99
+ 1–8), exposed as `memory` on `GET /apk-vm/state`, `/apk-vm/emulators` and
100
+ `GET /apk-vm/instances`, and on the `apk_vm` `list_instances` action. Creating/starting a local
101
+ VM on a low-memory host fails with an actionable error instead of swapping the machine to
102
+ death; `memoryPressureReap` (default) stops the least-recently-used idle local VM first. The VM
103
+ instances card shows host RAM, the effective cap, the preset and the per-VM RAM/vCPU profile.
104
+ - **Lite mode.** `vmPreset: lite` shrinks the default AVD and extra instances to 1 GB guest RAM,
105
+ 2 vCPU, SwiftShader GPU and a 720×1280 / 30 fps H.264 stream (1 fps PNG fallback), for 8–16 GB
106
+ hosts.
107
+ - **Wedged-guest recovery.** A device that adb still lists but whose guest shell stops responding
108
+ is detected after two consecutive boot-probe timeouts, killed through the emulator console (and
109
+ its process tree), its broken snapshot is quarantined, and the instance is cold-started once
110
+ instead of staying `booting` forever. `_refresh()` no longer flips between `starting` and
111
+ `stopped` while a boot wait is in flight, and the instances card gains a Start button for
112
+ stopped VMs.
113
+ - **Chinese changelog.** `CHANGELOG.zh-CN.md` mirrors the 0.12.x entries of the English
114
+ changelog (the pre-0.12 history stays English-only in `CHANGELOG.md`) and release notes now
115
+ carry a Chinese summary; the release checklist requires keeping it in sync.
116
+
3
117
  ## 0.12.4
4
118
 
5
119
  ### Fixed
@@ -142,12 +256,16 @@ reset, and the plugin can provision its own JDK / Android SDK / system image / A
142
256
  - `webviewAction=eval` returned `null` for `DOMRect`/`MediaQueryList` and other non-by-value
143
257
  values; it now returns a readable snapshot.
144
258
 
145
- ## 1.0.0
259
+ ### Historical: planned 1.0.0, shipped as 0.12.0
260
+
261
+ > These notes were written for a 1.0.0 cut that was renumbered to 0.12.0 before
262
+ > release. They are kept here for history, so no 1.0.0 that never shipped appears
263
+ > between the 0.12.0 and 0.11.1 sections.
146
264
 
147
265
  Observability and reliability release: a local Agent activity journal, hardened device
148
266
  interactions, and a first-class zero-config provisioning chain.
149
267
 
150
- ### Added
268
+ #### Added
151
269
 
152
270
  - **Agent activity log.** Every `apk_vm` tool call and every mutating panel/HTTP request is
153
271
  journaled locally as JSONL under `<profile>/.apk-vm/activity` (override with `activityDir`);
@@ -182,7 +300,7 @@ interactions, and a first-class zero-config provisioning chain.
182
300
  - WebView control docs and examples now point at `webview`/`tap_css`/`tap_selector`
183
301
  as the preferred path for DOM content.
184
302
 
185
- ### Changed
303
+ #### Changed
186
304
 
187
305
  - `sdkmanager` installs (`installSystemImage`, `installSdkPackages`) always pass
188
306
  `--sdk_root=<sdkRoot>`, so a `sdkmanager` found elsewhere on `PATH` cannot install into the
@@ -194,7 +312,7 @@ interactions, and a first-class zero-config provisioning chain.
194
312
  physical devices and snapshots; expanded troubleshooting for the fixes above; macOS/arm64
195
313
  image selection documented; demo media checked in.
196
314
 
197
- ### Fixed
315
+ #### Fixed
198
316
 
199
317
  - `adb` tool action failed with `Cannot access 'api' before initialization` on every call — the
200
318
  tool API is now resolved lazily per action.
@@ -229,15 +347,13 @@ interactions, and a first-class zero-config provisioning chain.
229
347
  and per-candidate timeouts plus the known-good JDK table make it fail over instead.
230
348
  - macOS arm64 provisioning selected the x86_64 image; it now defaults to `arm64-v8a`.
231
349
 
232
- ### Fixed
233
-
234
350
  - `GET/POST /apk-vm/camera` accepted poster paths that did not exist; save/apply now reject
235
351
  missing or unreadable `-virtualscene-poster` files with the offending poster name and path
236
352
  instead of failing later on the next emulator launch.
237
353
 
238
- ### Zero-config first run
354
+ ##### Zero-config first run
239
355
 
240
- ### Added
356
+ ##### Added
241
357
 
242
358
  - **Automatic environment provisioning (`autoSetup`, default `true`).** The first
243
359
  `GET /apk-vm/state` or `GET /apk-vm/setup` request — opening the panel, or an Agent's first
@@ -260,7 +376,7 @@ interactions, and a first-class zero-config provisioning chain.
260
376
  - `GET /apk-vm/setup` now reports `javaHome` / `javaPresent`; the Environment card shows a Java
261
377
  row plus live auto-setup progress with cancel/retry.
262
378
 
263
- ### Changed
379
+ ##### Changed
264
380
 
265
381
  - `findJavaHome()` also looks in the plugin-managed JDK directory and `extraJavaHomes`, so
266
382
  `sdkmanager`/`avdmanager` work without a system-wide JDK or `JAVA_HOME`.
@@ -269,7 +385,7 @@ interactions, and a first-class zero-config provisioning chain.
269
385
  `autoStart` flow — a cold install goes from zero to a running VM without extra clicks.
270
386
  - First-run documentation is now install → open the panel → automatic provisioning → VM start.
271
387
 
272
- ### Fixed
388
+ ##### Fixed
273
389
 
274
390
  - The Environment card could stay empty on exactly the machines that needed setup: a
275
391
  `GET /apk-vm/setup` payload with `ok: false` was treated as a failed request. It now renders
@@ -0,0 +1,191 @@
1
+ # 更新日志(中文)
2
+
3
+ 本文件提供 **0.12.x** 各版本的中文更新日志,与英文版 [`CHANGELOG.md`](CHANGELOG.md) 同步;
4
+ 0.12.0 之前的历史仅保留在英文文件中。发布时请在 [docs/RELEASING.md](docs/RELEASING.md)
5
+ 的检查清单里确认本文件已同步更新。
6
+
7
+ ## 0.13.0
8
+
9
+ 归属管理版本:专属虚拟机在重启后依然保留,接管必须显式确认。
10
+
11
+ - **虚拟机操作锁。** `lock_vm` / `unlock_vm`(以及 `POST /apk-vm/ownership` 的 `lock`/`unlock`)
12
+ 会把租约变成硬锁:锁定期间其他 Agent 与面板的变更请求一律返回 `409 vm-locked`,
13
+ `ownerForce` 与接管都无法绕过;只有锁所有者(或本地管理员解锁)可以继续操作。
14
+ 锁会持久化到 `leases.json`,面板提供「锁定/解锁」按钮。两个配置项可调整策略:
15
+ `lockEnforcement`(`all` | `agents` | `off`)与 `lockControl`(`all` | `user`)。
16
+ ### 新增
17
+
18
+ - **租约持久化与专属保留。** 租约写入 `<profile>/.apk-vm/leases.json`,并在插件下次启动时
19
+ 恢复。专属(`conversation`/`project`)虚拟机在 DSH 重启后仍保留给原 owner,不会再被第一个
20
+ 请求的会话拿走。专属租约带 `reservedUntil` 截止时间(`leaseReservationTtlMs`,默认 24 小时),
21
+ 过期后可正常认领。
22
+ - **接管显式化并留痕。** 被他人占用的租约会在 409 响应中携带 owner 短 id 与保留截止时间;
23
+ 面板显示保留信息、对其他 owner 保持只读,并提供「接管」按钮;非显式接管的管理员变更返回
24
+ `vm-takeover-required`(`x-apk-vm-takeover: 1`),不再静默操作他人虚拟机。claim/release/takeover
25
+ 变更会记录到活动日志(含前后 owner)。
26
+ - **`force` 作为 `ownerForce` 的别名。** `apk_vm` 接受 `force: true`,错误文案与实际参数一致;
27
+ `claim_vm`/`release_vm` 在接管时会报告前一个 owner。
28
+ - **活动日志补充 owner 维度。** 记录 `owner`(key/label/scope/role),并经过统一脱敏,便于多会话
29
+ 与面板同时操作时追溯「谁做了什么」。
30
+ - **常驻共享默认虚拟机。** 默认虚拟机永不释放、永不删除。空闲 `sharedSuspendAfterMs`(默认 5 分钟)
31
+ 后挂起到快速启动快照(状态 `suspended`,约 6 秒恢复);再空闲 `sharedStopAfterMs`(默认 1 小时)
32
+ 后标记为 `stopped`,快照与 AVD 均保留。工具调用、面板操作与视频客户端都会重置空闲计时,下次启动
33
+ 按需恢复。
34
+ - **存储统计覆盖崩溃残留与孤儿 AVD。** `GET /apk-vm/storage` 现在报告隔离的 `*.corrupt-*`
35
+ 快照备份、模拟器崩溃转储以及可回收总量 `reclaimableBytes`;`POST /apk-vm/storage` 新增
36
+ `corrupt-snapshots` 与 `crash-dumps`(均需 `confirm: true`),存储卡片显示可回收大小并可
37
+ 一键清理。
38
+ - **危险操作二次确认。** `destroy_instance` 需要 `confirm: true`,面板删除按钮需点击两次,
39
+ 避免 agent 或误点直接删除实例 AVD 与数据;实例 DELETE 路由也拒绝不带 `?confirm=1` 的请求。
40
+
41
+ ### 变更
42
+
43
+ - 面板的 claim/release 不再默认强制:`POST /apk-vm/ownership` 仅在请求体带 `force: true` 时强制,
44
+ 并且所有 owner 变更都会写入活动日志。
45
+ - **工具等待有上界。** 需要启动 VM 的设备操作约 120 秒后(显式 `start` 为 180 秒,可用
46
+ `timeoutMs` 覆盖)返回可操作错误,而不是等满 1200 秒启动超时;VM 仍在后台继续启动,稍后
47
+ 再调用可观察到 ready;另外 `maybeAutoStart` 会跳过处于崩溃循环的 VM。
48
+
49
+ ### 修复
50
+
51
+ - 保留中的租约可能被其他会话或管理面板静默抢占。
52
+ - 租约只存在内存中,插件重载后丢失,导致专属 VM 在重启后被重新分配。
53
+ - 显式 `claim_vm` 后,未指定 `instance` 的后续工具调用可能仍落在之前分配的虚拟机上:现在
54
+ 认领会同步更新该会话在 conversation/project/shared 三种范围下的实例映射,下一次调用会
55
+ 解析到刚刚认领的虚拟机。
56
+ - 活动日志记录的是「请求的实例 id」(未指定时按 `default` 记录),而不是实际执行调用的
57
+ 虚拟机,导致这类错配在日志里看不出来;现在记录实际解析到的实例。
58
+
59
+ - 修复 `recordOwnershipAction is not defined`(`ReferenceError`)导致工具与 HTTP 接管路径
60
+ 失败:日志助手改在插件作用域定义,`claim_vm`/`vm` 接管与归属活动记录恢复正常。
61
+ - Windows 模拟器在写入 quick-boot 快照时或之后可能崩溃(`0xC0000005`):现在会跟踪快照保存
62
+ 状态——保存期间到来的 `start` 会等待完成;保存后崩溃会禁用后续快照保存、隔离损坏快照并
63
+ 以冷启动重试一次。
64
+ - 不完整的 quick-boot 快照(`ram.bin` 过小或 `snapshot.pb` 写了一半)现在会在启动前被隔离,
65
+ 启动计划改用 `-no-snapshot-load` 冷启动,损坏快照不会再导致模拟器反复崩溃重启。
66
+ - **崩溃循环熔断。** 15 分钟内三次非零退出会暂停自动恢复/自动启动并禁用快照保存,原因写入
67
+ state error 与 logTail;请检查模拟器日志/崩溃转储后手动启动。
68
+
69
+ ## 0.12.5
70
+
71
+ 可靠性版本:零配置首次启动的抗网络故障能力,以及多 VM 宿主机的内存管理。
72
+
73
+ ### 新增
74
+
75
+ - **零配置供应的下载可靠性。** 每个供应步骤都会自动重试临时性的网络/命令失败
76
+ (`setupRetries`,默认 3 次;`retryDelayMs` 指数退避),45 秒无进展看门狗会中止卡死的
77
+ 下载,而不是一直挂起。JDK 压缩包从 `.partial` 文件用 HTTP Range 续传,每次尝试都重新校验
78
+ SHA-256;命令行工具下载现在带 stall 超时、大小上限和可选校验
79
+ (`commandLineToolsUrl` / `commandLineToolsSha256`),并支持镜像地址;`sdkmanager`
80
+ 支持镜像/代理配置(`sdkManagerArgs`、`sdkManagerEnv`、`networkProxy`);供应开始前先检查
81
+ 累计可用磁盘预算(`minFreeDiskBytes`,默认 6 GB)。重试会在 `autoSetup.detail` 中报告
82
+ `attempt` 与 `nextDelayMs`,环境卡片在退避期间显示「retry n/m in Ns」。
83
+ - **内存感知的实例管理。** 新增 `lib/memory.js`:读取宿主内存并推导有效实例上限
84
+ (`memoryGuard`,`hostReserveMb` 4 GB,`estimatedVmMb` 3 GB,限制在 1–8 之间),通过
85
+ `GET /apk-vm/state`、`/apk-vm/emulators`、`GET /apk-vm/instances` 和 `apk_vm`
86
+ `list_instances` 的 `memory` 对象暴露。低内存宿主上创建/启动本地 VM 会给出可操作的错误,
87
+ 而不是把整机换页致死;`memoryPressureReap`(默认开启)先停止最久未使用的空闲本地 VM。
88
+ VM 实例卡片显示宿主内存、有效上限、预设以及每个 VM 的 RAM/vCPU 配置。
89
+ - **Lite 模式。** `vmPreset: lite` 把默认 AVD 和额外实例缩小到 1 GB 客机内存、2 vCPU、
90
+ SwiftShader GPU 以及 720×1280 / 30 fps 的 H.264 流(PNG 回退 1 fps),适合 8–16 GB 的
91
+ 宿主机。
92
+ - **卡死 guest 的自动恢复。** 如果 adb 仍能列出设备但客机 shell 已无响应,插件会在连续两次
93
+ 启动探测超时后判定为 wedged:通过模拟器控制台(以及进程树)结束该模拟器、隔离损坏快照,
94
+ 并冷启动重试一次,而不是永远停在 `booting`。`_refresh()` 在启动等待进行中不再于
95
+ `starting` 与 `stopped` 之间来回切换,实例卡片也为已停止的 VM 增加了「启动」按钮。
96
+ - **中文更新日志。** `CHANGELOG.zh-CN.md` 提供 0.12.x 条目的中文版本,发布说明也带中文摘要;
97
+ 发布检查清单要求保持同步。
98
+
99
+ ## 0.12.4
100
+
101
+ ### 修复
102
+
103
+ - **0.12.3 引入的 hypervisor 检测回归。** 启动速度统计的重构丢失了三个构造器初始化字段
104
+ (`_accelAvailable`、`_snapshotSave`、`_lastLaunchArgs`),导致 `_detectAcceleration()`
105
+ 在 `!== null` 处短路并返回 `undefined`,于是每次启动都误报「找不到可用的 CPU
106
+ hypervisor(AEHD/WHPX)」,即使 `emulator -accel-check` 报告可用。本次恢复这三个字段,
107
+ 并在 `spike/snapshot-recovery-test.mjs` 中断言其初始值以及 `_detectAcceleration()` 返回
108
+ 布尔值,防止该回归再次静默发布。
109
+
110
+ ## 0.12.3
111
+
112
+ ### 新增
113
+
114
+ - **Agent 操作手册。** 包内新增 [`docs/AGENTS.md`](docs/AGENTS.md),可在运行时通过
115
+ `apk_vm` 的 `guide` 动作(或 `GET /apk-vm/guide`)读取;内容覆盖标准循环、动作地图、
116
+ 设备像素与 CSS 坐标规则、WebView/CDP、实例与远端会话、错误恢复和安全边界。
117
+ - **新会话强制引导。** 每个新会话的第一次 `apk_vm` 调用会先返回一次操作手册
118
+ (`result.guideRequired: true`)而不执行原动作;阅读后重复调用即可。`action=guide`
119
+ 始终可用。
120
+ - **共享与专用 VM 指引。** 手册和 README 说明默认实例是共享、短命的设备,长时间调试建议
121
+ claim 一个专用 VM,并说明从其它会话进入共享 VM 会把客机重置回桌面。
122
+ - **Quick-boot 快照自愈。** 恢复时会让模拟器崩溃(Windows 访问冲突 `0xC0000005`)或看起来
123
+ 只写了一半(`snapshot.pb` 远新于 `ram.bin`)的快照会被自动隔离、以冷启动重试一次并重建;
124
+ 隔离情况通过 `status().snapshotRecovery` 暴露。
125
+ - **VM 命名与按会话自动选中。** 每个实例(包括 `default` 和远端会话)都可以有持久化的显示名
126
+ (`<profile>/.apk-vm/instance-names.json`);可用 `apk_vm` 的 `rename_instance`、
127
+ `POST /apk-vm/instances {"action":"rename",…}` 或面板的 Rename 按钮重命名。面板会跟随当前
128
+ 会话,选中租约属于该会话的 VM,而不是永远显示共享的 default。
129
+
130
+ ### 变更
131
+
132
+ - **DSH 兼容性元数据。** `package.json` 现在声明 `engines.dsh`
133
+ (`>=0.2.1-rc.3 || >=0.2.2-rc.1`)和 `dsh.compatibility.dshReleases`(`0.2.1-rc.3+`、
134
+ `0.2.2-rc.1+` → `compatible`),插件管理器和市场可以在安装/启用前校验支持的 DSH 版本。
135
+ README 增加「Supported DSH versions」一节,`docs/SUBMISSION.md` 列出同样的测试矩阵。
136
+
137
+ ## 0.12.2
138
+
139
+ ### 修复
140
+
141
+ - **面板版本标签显示 `v0.11.1`。** `client.js` 里手写的 `CLIENT_VERSION` 常量在 0.11.1 之后
142
+ 没有再更新,导致 0.12.0/0.12.1 的标题栏胶囊显示错误版本。现在胶囊优先使用宿主上报的版本,
143
+ 常量更新为当前版本,并且 `npm run check` 会运行 `scripts/check-version.mjs`,在
144
+ `CLIENT_VERSION` 与 `package.json` 不一致时让构建失败。
145
+
146
+ ## 0.12.1
147
+
148
+ ### 新增
149
+
150
+ - **远端 VM 多会话。** 远端主机成为一类 VM 来源:配置文件保存在
151
+ `<profile>/.apk-vm/remote-profiles.json`(只存校验后的非敏感字段,不存密钥内容),
152
+ `RemoteSessionManager` 可并发运行多个会话(`remoteMaxSessions`,默认 4),每个会话有自己
153
+ 的 AVD、adb 隧道、H.264 流和实例 id。
154
+ - **模拟器清单。** `GET /apk-vm/emulators` 把本地 AVD/设备状态与每个已保存的远端主机合并
155
+ (`lib/emulator-inventory.js`),面板增加「Available emulators」卡片。
156
+ - **虚拟摄像头。** 支持摄像头前后置模式与 `-virtualscene-poster` 海报,由
157
+ `GET/POST /apk-vm/camera`、面板 Media 卡片或 `cfg.camera` 管理(`lib/media.js`)。
158
+ - **虚拟麦克风。** 麦克风模式 `off` / `host` / `file`;file 模式把音频循环进虚拟
159
+ PulseAudio 源(null-sink + remap-source),在 Linux 和远端主机可用;由
160
+ `GET/POST /apk-vm/mic`、面板 Media 卡片或 `cfg.mic` 管理。
161
+ - **SSH 远端虚拟机(远端 VM 主机)。** `/apk-vm/remote` 现在把一台 SSH 可达主机变成 VM
162
+ 代理:转发本地回环端口到远端模拟器的 adb 端口,执行 `adb connect` 并把设备接入正常的
163
+ 启动等待/H.264/输入/调试链路。`launch: true` 会在远端用固定命令启动无窗口模拟器
164
+ (`-no-window -no-audio -no-boot-anim -gpu swiftshader_indirect`),`disconnect` 可以停止
165
+ 它。经验证的配置(主机/用户/端口/AVD,不含密钥)持久化在
166
+ `<profile>/.apk-vm/remote-profile.json`,面板卡片会预填并每两秒轮询隧道/启动状态。
167
+
168
+ ### 变更
169
+
170
+ - 新的插件图标(`icon.svg`,36×36):柠檬/草绿与紫色分层屏幕,替换原先在深色磁贴上几乎不可见
171
+ 的细线 `currentColor` 图标。
172
+ - 使用 0.12.0 面板 UI 重新生成演示截图(主面板、Activity 卡片、客机、Environment、APK 文件
173
+ 和 Rooted debug 卡片);Windows 用户名、真实 APK 名称/路径和助手头像做了高斯模糊。
174
+
175
+ ### 移除
176
+
177
+ - `docs/screenshot-sidebar.png`:由重新拍摄的面板与卡片截图替代。
178
+
179
+ ## 0.12.0
180
+
181
+ WebView 读取、记住已装 APK 和零配置首次运行。
182
+
183
+ - `webviewAction=eval` 现在返回真实值(普通 JSON 值直接返回;`DOMRect`、`MediaQueryList`
184
+ 这类不能按值穿过 JSON 的对象返回属性快照),不再需要截图。
185
+ - 记住已安装的 APK:通过工具或面板安装的 APK 记录在
186
+ `<profile>/.apk-vm/installed-apps.json`,上传的 APK 归档在 `<profile>/.apk-vm/apks`
187
+ (最新 10 个);客机重置/AVD 重建/插件升级后会按需自动重装(`autoReinstall`,默认开)。
188
+ - 零配置首次运行:`autoSetup`(默认开)在第一次使用时自动准备 JDK 17、SDK 命令行工具、
189
+ system image 和 AVD;可在环境卡片查看进度、取消和重试,也可用 `autoSetup: false` 保持手动。
190
+ - Agent 活动日志、设备韧性/恢复、quick-boot 快照恢复、多实例隔离等 0.12.0 的完整说明见
191
+ [`CHANGELOG.md`](CHANGELOG.md) 的 0.12.0 一节(含 Historical: planned 1.0.0 的历史记录)。