@xrkseek/xrk-phone-bridge 0.7.25 → 0.7.26

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/README.md CHANGED
@@ -1,54 +1,99 @@
1
- # xrk-phone-bridge(远程 phone_*)
2
-
3
- > **读者**:维护者 · 在 Desktop / `xrkh serve` Host 上启用远程手机工具。
4
-
5
- **装一个目录即可。** `kind: host`;首次接线 materialize:
6
-
7
- - `xrk-phone-bridge-tools` / `xrk-phone-bridge-prompt`
8
- - `$XRK_HOME/skills/xrk-phone`(与 guest 同一份 playbook)
9
- - `web/plugins/xrk-phone-bridge/client.js` → Settings 侧栏 **远程手机桥**
10
-
11
- 不改 Host 源码。`dsh_ma_device` 的 Cookie Path 仅 `/mobile-access/auth/renew`,Settings SPA 通常看不到 deviceKey——以待批准 / 在线列表为准;App 出站请求自行转发 Cookie。
12
-
13
- ## 浏览器 Face vs 手机 App
14
-
15
- | 表面 | PIN 打开 Face | 进白名单 / 待批准 | phone_* 执行 |
16
- |------|---------------|-------------------|--------------|
17
- | 浏览器桌面 Face | 是(聊天/Settings) | **否**(不调 `register`) | 经已在线 App 执行 |
18
- | 手机 App HTTP Face | 是 | **是**(App 出站 `ticket`→`register`) | 本机无障碍 poll |
19
-
20
- 浏览器与 App 可同时连同一 Host:Face 会话互不顶替;白名单只认 App `clientDeviceId`。
21
-
22
- ## 事件链
23
-
24
- `ticket` → `register`(未白名单 → **pending**)→ Settings **允许**(`POST /whitelist`)→ `register` ok → App **`POST /poll`**(**online**)→ `invoke` / `result`
25
-
26
- | 路由 | 用途 |
27
- |------|------|
28
- | `GET /status` | Settings 列表 |
29
- | `POST /whitelist` | 允许 / 移除 |
30
- | `POST /ticket` · `/register` · `/bind-session` · `/poll` · `/result` · `/offline` | App 桥 |
31
-
32
- Ticket 只走 POST body。Host:一机一票;离线/吊销唤醒 long-poll 并失败在途 invoke;队列有上限。
33
-
34
- ## 截图回传
35
-
36
- `phone_screen`(`image:true`)经 App → `POST /result` 带 `imageBase64` + `imageMime`(`/result` 体上限 **12 MiB**;其它路由仍 1 MiB)。工具插件把字节 `saveImage` 进 AttachmentStore,模型面拿到 `type:"image"` 块。Guest 本机环(`MobileApi` JSON 信封 → `xrk-mobile` admit)同契约。
37
-
38
- ## 安装
39
-
40
- ```bash
41
- xrkh plugin add @xrkseek/xrk-phone-bridge
42
- # 或:npm pack 后解压到 $XRK_HOME/plugins/xrk-phone-bridge/
43
- xrkh restart
44
- ```
45
-
46
- npm:`@xrkseek/xrk-phone-bridge`(当前 **0.7.25**)。远程与本机 guest 同一套:`skill xrk-phone` + `phone_*`。
47
-
48
- 手机 App:**HTTP Host + PIN** 即可进待批准;**操控 + 无障碍** 后进在线。浏览器 PIN **不会**进待批准。
49
-
50
- ## 测
51
-
52
- ```bash
53
- pnpm exec vitest run extensions/xrk-phone-bridge/tests/runtime.test.mjs
54
- ```
1
+ # xrk-phone-bridge(远程 phone_*)
2
+
3
+ > **读者**:维护者 · 在 Desktop / `xrkh serve` Host 上启用远程手机工具。
4
+
5
+ **装一个目录即可。** `kind: host`;首次接线 materialize:
6
+
7
+ - `xrk-phone-bridge-tools` / `xrk-phone-bridge-prompt`
8
+ - `$XRK_HOME/skills/xrk-phone`(与 guest 同一份 playbook)
9
+ - `web/plugins/xrk-phone-bridge/client.js` → Settings 侧栏 **远程手机桥**
10
+
11
+ 不改 Host 源码。设备 Cookie 的 Path 仅 `/mobile-access/auth/renew`,Settings SPA 通常看不到 deviceKey——以待批准 / 在线列表为准;App 出站请求自行转发 Cookie。
12
+
13
+ ## 浏览器 Face vs 手机 App
14
+
15
+ | 表面 | PIN 打开 Face | 进白名单 / 待批准 | phone_* 执行 |
16
+ |------|---------------|-------------------|--------------|
17
+ | 浏览器桌面 Face | 是(聊天/Settings) | **否**(不调 `register`) | 经已在线 App 执行 |
18
+ | 手机 App HTTP Face | 是 | **是**(App 出站 `ticket`→`register`) | 本机无障碍 poll |
19
+
20
+ 浏览器与 App 可同时连同一 Host:Face 会话互不顶替;白名单只认 App `clientDeviceId`。
21
+
22
+ ## 事件链
23
+
24
+ `ticket` → `register`(未白名单 → **pending**)→ Settings **允许**(`POST /whitelist`)→ `register` ok → App **`POST /poll`**(**online**)→ `invoke` / `result`
25
+
26
+ | 路由 | 用途 |
27
+ |------|------|
28
+ | `GET /status` | Settings 列表 |
29
+ | `POST /whitelist` | 允许 / 移除 |
30
+ | `POST /ticket` · `/register` · `/bind-session` · `/poll` · `/result` · `/offline` | App 桥 |
31
+
32
+ Ticket 只走 POST body。Host:一机一票;离线/吊销唤醒 long-poll 并失败在途 invoke;队列有上限。
33
+
34
+ ## 截图回传
35
+
36
+ `phone_screen`(`image:true`)经 App → `POST /result` 带 `imageBase64` + `imageMime`(`/result` 体上限 **12 MiB**;其它路由仍 1 MiB)。工具插件把字节 `saveImage` 进 AttachmentStore,模型面拿到 `type:"image"` 块。Guest 本机环(`MobileApi` JSON 信封 → `xrk-mobile` admit)同契约。
37
+
38
+ ## 安装
39
+
40
+ ```bash
41
+ xrkh plugin add @xrkseek/xrk-phone-bridge
42
+ xrkh restart
43
+ ```
44
+
45
+ 手机 App:**HTTP Host + PIN** 即可进待批准;**操控 + 无障碍** 后进在线。浏览器 PIN **不会**进待批准。
46
+
47
+ ## 测
48
+
49
+ ```bash
50
+ pnpm exec vitest run extensions/xrk-phone-bridge/tests/runtime.test.mjs
51
+ ```
52
+
53
+ ---
54
+
55
+ # xrk-phone-bridge (remote `phone_*`)
56
+
57
+ > **Audience**: Maintainers enabling remote phone tools on Desktop / `xrkh serve`.
58
+
59
+ **One directory install.** `kind: host`; first wire materializes:
60
+
61
+ - `xrk-phone-bridge-tools` / `xrk-phone-bridge-prompt`
62
+ - `$XRK_HOME/skills/xrk-phone` (same playbook as guest)
63
+ - `web/plugins/xrk-phone-bridge/client.js` → Settings **Remote phone bridge**
64
+
65
+ No Host source edits. Device cookie Path is only `/mobile-access/auth/renew`; Settings SPA usually cannot see `deviceKey` — trust pending / online lists; the App forwards cookies on outbound calls.
66
+
67
+ ## Browser Face vs phone App
68
+
69
+ | Surface | PIN opens Face | Whitelist / pending | `phone_*` runs |
70
+ |---------|----------------|---------------------|----------------|
71
+ | Desktop browser Face | Yes | **No** (no `register`) | Via an already-online App |
72
+ | Phone App HTTP Face | Yes | **Yes** (`ticket` → `register`) | Local accessibility poll |
73
+
74
+ Browser and App may share one Host: Face sessions do not kick each other; whitelist keys on App `clientDeviceId`.
75
+
76
+ ## Event chain
77
+
78
+ `ticket` → `register` (pending if not whitelisted) → Settings **Allow** (`POST /whitelist`) → `register` ok → App **`POST /poll`** (online) → `invoke` / `result`
79
+
80
+ Ticket is POST body only. Host: one ticket per device; offline/revoke wakes long-poll and fails in-flight invokes; queues are capped.
81
+
82
+ ## Screenshots
83
+
84
+ `phone_screen` (`image:true`) returns via App `POST /result` with `imageBase64` + `imageMime` (`/result` body limit **12 MiB**). The tools plugin `saveImage`s into AttachmentStore so the model sees `type:"image"` blocks.
85
+
86
+ ## Install
87
+
88
+ ```bash
89
+ xrkh plugin add @xrkseek/xrk-phone-bridge
90
+ xrkh restart
91
+ ```
92
+
93
+ Phone App: **HTTP Host + PIN** reaches pending; **control + accessibility** reaches online. Browser PIN alone does **not** enter pending.
94
+
95
+ ## Tests
96
+
97
+ ```bash
98
+ pnpm exec vitest run extensions/xrk-phone-bridge/tests/runtime.test.mjs
99
+ ```
package/lib/runtime.mjs CHANGED
@@ -12,7 +12,9 @@
12
12
  * clients must re-ticket on `invalid-ticket`.
13
13
  */
14
14
  import { createHash, randomBytes } from "node:crypto";
15
- import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
15
+ import {
16
+ mkdirSync, readFileSync, writeFileSync, existsSync, renameSync, unlinkSync,
17
+ } from "node:fs";
16
18
  import { join } from "node:path";
17
19
 
18
20
  const KEY = Symbol.for("xrk.phoneBridge.v1");
@@ -246,8 +248,9 @@ export class PhoneBridgeRuntime {
246
248
  if (!p) return;
247
249
  ensureDir(join(this.home, "phone-bridge"));
248
250
  this.state.pending = this.listPending();
249
- writeFileSync(
250
- p,
251
+ // Atomic replace: a crash mid-write must not leave a truncated whitelist.
252
+ const tmp = `${p}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
253
+ const body =
251
254
  JSON.stringify(
252
255
  {
253
256
  whitelist: this.state.whitelist,
@@ -256,9 +259,21 @@ export class PhoneBridgeRuntime {
256
259
  },
257
260
  null,
258
261
  2,
259
- ) + "\n",
260
- "utf8",
261
- );
262
+ ) + "\n";
263
+ writeFileSync(tmp, body, "utf8");
264
+ try {
265
+ renameSync(tmp, p);
266
+ } catch {
267
+ try {
268
+ writeFileSync(p, body, "utf8");
269
+ } finally {
270
+ try {
271
+ if (existsSync(tmp)) unlinkSync(tmp);
272
+ } catch {
273
+ // ignore cleanup errors
274
+ }
275
+ }
276
+ }
262
277
  }
263
278
 
264
279
  /** Immediate persist (whitelist mutations). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xrkseek/xrk-phone-bridge",
3
- "version": "0.7.25",
3
+ "version": "0.7.26",
4
4
  "description": "Remote phone_* bridge (host HTTP + Settings whitelist + materialize tools/prompt/xrk-phone skill)",
5
5
  "type": "module",
6
6
  "files": [