@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 +99 -54
- package/lib/runtime.mjs +21 -6
- package/package.json +1 -1
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
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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 {
|
|
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
|
-
|
|
250
|
-
|
|
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
|
-
|
|
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). */
|