pi-wechat-session-hub 0.1.0 → 0.1.2
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 +95 -0
- package/README.md +420 -365
- package/docs/handoff-next-session.md +4 -4
- package/docs/implementation-spec.md +150 -147
- package/extensions/daemon-entry.mjs +31 -0
- package/extensions/wechat-session-hub.ts +12 -12
- package/package.json +72 -67
- package/scripts/probe-wt-capability.mjs +26 -5
- package/scripts/release-preflight.mjs +229 -0
- package/src/gateway/command-parser.ts +25 -9
- package/src/gateway/command-router.ts +1790 -1449
- package/src/gateway/durable-message-queue.ts +1154 -1043
- package/src/gateway/gateway-control-ipc.ts +705 -687
- package/src/gateway/turn-health.ts +305 -0
- package/src/gateway/ui-worker-extension-bridge.ts +1092 -1070
- package/src/gateway/ui-worker-ipc.ts +1517 -1483
- package/src/gateway/wechat-ilink/api-client.ts +386 -390
- package/src/runtime/gateway-lifecycle-operation.ts +67 -2
- package/src/runtime/gateway-service-controller.ts +341 -339
- package/src/runtime/ui-worker-manager.ts +1216 -1186
- package/src/runtime/windows-logon-autostart-manager.ts +401 -0
- package/src/runtime/windows-logon-task-manager.ts +0 -212
|
@@ -1,339 +1,341 @@
|
|
|
1
|
-
import { randomUUID } from "node:crypto";
|
|
2
|
-
import { spawn } from "node:child_process";
|
|
3
|
-
import type { PiCliInvocation } from "./pi-cli.ts";
|
|
4
|
-
import { GatewayControlClient, GatewayControlError } from "../gateway/gateway-control-ipc.ts";
|
|
5
|
-
import {
|
|
6
|
-
watchGatewayLifecycleOperation,
|
|
7
|
-
writeGatewayLifecycleOperationReceipt,
|
|
8
|
-
} from "./gateway-lifecycle-operation.ts";
|
|
9
|
-
|
|
10
|
-
const LIFECYCLE_RESPONSE_TIMEOUT_MS = 300000;
|
|
11
|
-
|
|
12
|
-
export type GatewayServiceState = "offline" | "starting" | "online" | "auth_required" | "stopping";
|
|
13
|
-
|
|
14
|
-
export interface GatewayServiceStatus {
|
|
15
|
-
state: GatewayServiceState;
|
|
16
|
-
pid?: number;
|
|
17
|
-
startedAt?: string;
|
|
18
|
-
foregroundSessionCount?: number;
|
|
19
|
-
backgroundSessionCount?: number;
|
|
20
|
-
routeCount?: number;
|
|
21
|
-
error?: string;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
|
-
export interface GatewayDaemonLaunchSpec {
|
|
25
|
-
managerDirectory: string;
|
|
26
|
-
extensionPath: string;
|
|
27
|
-
daemonEntry: string;
|
|
28
|
-
piInvocation: PiCliInvocation;
|
|
29
|
-
}
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
* 控制一个独立于当前 Pi TUI 生命周期的 Gateway daemon。
|
|
33
|
-
*/
|
|
34
|
-
export class GatewayServiceController {
|
|
35
|
-
private readonly controlClient: GatewayControlClient;
|
|
36
|
-
private readonly launchDaemon: (spec: GatewayDaemonLaunchSpec) => Promise<void>;
|
|
37
|
-
|
|
38
|
-
/**
|
|
39
|
-
* 创建后台 Gateway 控制器。
|
|
40
|
-
*
|
|
41
|
-
* @param managerDirectory Hub 私有数据目录。
|
|
42
|
-
* @param launchSpec daemon 启动时需要的固定运行参数。
|
|
43
|
-
* @param options 可注入控制客户端和进程启动边界。
|
|
44
|
-
*/
|
|
45
|
-
constructor(
|
|
46
|
-
private readonly managerDirectory: string,
|
|
47
|
-
private readonly launchSpec: GatewayDaemonLaunchSpec,
|
|
48
|
-
options: {
|
|
49
|
-
controlClient?: GatewayControlClient;
|
|
50
|
-
launchDaemon?: (spec: GatewayDaemonLaunchSpec) => Promise<void>;
|
|
51
|
-
} = {},
|
|
52
|
-
) {
|
|
53
|
-
this.controlClient = options.controlClient ?? new GatewayControlClient(managerDirectory);
|
|
54
|
-
this.launchDaemon = options.launchDaemon ?? launchDetachedGatewayDaemon;
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* 查询真实后台进程和 Gateway 状态。
|
|
59
|
-
*
|
|
60
|
-
* @returns IPC 服务提供的活动状态; 控制通道离线时返回 offline。
|
|
61
|
-
* @throws {GatewayControlError} 身份校验或状态协议不可信时抛出。
|
|
62
|
-
*/
|
|
63
|
-
async status(): Promise<GatewayServiceStatus> {
|
|
64
|
-
try {
|
|
65
|
-
const response = await this.controlClient.request("status");
|
|
66
|
-
return parseServiceStatus(response);
|
|
67
|
-
} catch (error) {
|
|
68
|
-
if (error instanceof GatewayControlError && error.code === "not_running") {
|
|
69
|
-
return { state: "offline" };
|
|
70
|
-
}
|
|
71
|
-
throw error;
|
|
72
|
-
}
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
/**
|
|
76
|
-
* 幂等启动后台 Gateway daemon。
|
|
77
|
-
*
|
|
78
|
-
* @returns 已存在或新启动服务的状态。
|
|
79
|
-
* @throws {Error} daemon 启动失败且没有可用的现有服务时抛出。
|
|
80
|
-
*/
|
|
81
|
-
async start(): Promise<GatewayServiceStatus> {
|
|
82
|
-
const current = await this.status();
|
|
83
|
-
if (current.state !== "offline") {
|
|
84
|
-
return current;
|
|
85
|
-
}
|
|
86
|
-
try {
|
|
87
|
-
await this.launchDaemon(this.launchSpec);
|
|
88
|
-
} catch (error) {
|
|
89
|
-
const concurrentlyStarted = await this.status().catch(() => ({ state: "offline" as const }));
|
|
90
|
-
if (concurrentlyStarted.state !== "offline") {
|
|
91
|
-
return concurrentlyStarted;
|
|
92
|
-
}
|
|
93
|
-
throw error instanceof GatewayControlError
|
|
94
|
-
? error
|
|
95
|
-
: new GatewayControlError(
|
|
96
|
-
"request_failed",
|
|
97
|
-
error instanceof Error ? error.message : "后台 Gateway 启动失败, 请检查配置和微信授权。",
|
|
98
|
-
);
|
|
99
|
-
}
|
|
100
|
-
return this.status();
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
/**
|
|
104
|
-
* 请求后台 Gateway 在安全停止窗口内优雅退出。
|
|
105
|
-
*
|
|
106
|
-
* @returns Gateway 停止并释放控制租约后的最终状态。
|
|
107
|
-
* @throws {GatewayControlError} Gateway 离线或无法认证时抛出。
|
|
108
|
-
*/
|
|
109
|
-
async stop(): Promise<GatewayServiceStatus> {
|
|
110
|
-
const current = await this.status();
|
|
111
|
-
if (current.state === "offline") {
|
|
112
|
-
return current;
|
|
113
|
-
}
|
|
114
|
-
return parseServiceStatus(await this.controlClient.request("stop", {
|
|
115
|
-
responseTimeoutMs: LIFECYCLE_RESPONSE_TIMEOUT_MS,
|
|
116
|
-
}));
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
/**
|
|
120
|
-
* 请求后台 Gateway 安全停止当前 daemon 并启动新 daemon, 等待新服务就绪。
|
|
121
|
-
*
|
|
122
|
-
* @returns 新 Gateway 启动就绪后的最终状态。
|
|
123
|
-
* @throws {GatewayControlError} Gateway 离线或无法认证时抛出。
|
|
124
|
-
*/
|
|
125
|
-
async restart(): Promise<GatewayServiceStatus> {
|
|
126
|
-
const current = await this.status();
|
|
127
|
-
if (current.state === "offline") {
|
|
128
|
-
return this.start();
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
const operationId = randomUUID();
|
|
132
|
-
const watcher = await watchGatewayLifecycleOperation(this.managerDirectory, operationId);
|
|
133
|
-
let operationAccepted = false;
|
|
134
|
-
let receiptRead = false;
|
|
135
|
-
try {
|
|
136
|
-
await writeGatewayLifecycleOperationReceipt(this.managerDirectory, {
|
|
137
|
-
action: "restart",
|
|
138
|
-
operationId,
|
|
139
|
-
state: "pending",
|
|
140
|
-
});
|
|
141
|
-
const accepted = await this.controlClient.request("restart", { operationId });
|
|
142
|
-
if (
|
|
143
|
-
!isRecord(accepted) ||
|
|
144
|
-
accepted.state !== "stopping" ||
|
|
145
|
-
(accepted.operationId !== undefined && accepted.operationId !== operationId)
|
|
146
|
-
) {
|
|
147
|
-
throw new GatewayControlError("protocol_error", "后台 Gateway 未确认重启操作。 ");
|
|
148
|
-
}
|
|
149
|
-
operationAccepted = true;
|
|
150
|
-
const receipt = await watcher.wait(LIFECYCLE_RESPONSE_TIMEOUT_MS).catch((error: unknown) => {
|
|
151
|
-
throw new GatewayControlError(
|
|
152
|
-
"timeout",
|
|
153
|
-
error instanceof Error ? error.message : "等待后台 Gateway 重启结果超时。",
|
|
154
|
-
);
|
|
155
|
-
});
|
|
156
|
-
receiptRead = true;
|
|
157
|
-
if (receipt.state === "failed") {
|
|
158
|
-
throw new GatewayControlError(
|
|
159
|
-
"request_failed",
|
|
160
|
-
receipt.message ?? "后台 Gateway 重启失败; 请执行 /wx status 查看当前状态。",
|
|
161
|
-
);
|
|
162
|
-
}
|
|
163
|
-
if (!receipt.serviceStatus) {
|
|
164
|
-
throw new GatewayControlError("protocol_error", "后台 Gateway 重启结果缺少最终状态。 ");
|
|
165
|
-
}
|
|
166
|
-
return parseServiceStatus(receipt.serviceStatus);
|
|
167
|
-
} finally {
|
|
168
|
-
watcher.close();
|
|
169
|
-
if (receiptRead || !operationAccepted) {
|
|
170
|
-
await watcher.removeReceipt().catch(() => undefined);
|
|
171
|
-
}
|
|
172
|
-
}
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
|
|
176
|
-
/**
|
|
177
|
-
* 将已验证的 daemon 启动参数编码为 Node CLI payload。
|
|
178
|
-
*
|
|
179
|
-
* @param spec daemon 启动参数。
|
|
180
|
-
* @returns 不含 shell 解释的 base64url JSON。
|
|
181
|
-
*/
|
|
182
|
-
export function encodeGatewayDaemonLaunchSpec(spec: GatewayDaemonLaunchSpec): string {
|
|
183
|
-
return Buffer.from(JSON.stringify(spec), "utf8").toString("base64url");
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
/**
|
|
187
|
-
* 解码并验证 daemon 启动 payload。
|
|
188
|
-
*
|
|
189
|
-
* @param encoded base64url JSON 字符串。
|
|
190
|
-
* @returns 已验证启动参数。
|
|
191
|
-
* @throws {Error} payload 格式或路径字段无效时抛出。
|
|
192
|
-
*/
|
|
193
|
-
export function decodeGatewayDaemonLaunchSpec(encoded: string): GatewayDaemonLaunchSpec {
|
|
194
|
-
let parsed: unknown;
|
|
195
|
-
try {
|
|
196
|
-
parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as unknown;
|
|
197
|
-
} catch {
|
|
198
|
-
throw new Error("后台 Gateway 启动参数编码无效。");
|
|
199
|
-
}
|
|
200
|
-
if (!isRecord(parsed) || !isAbsolutePath(parsed.managerDirectory) ||
|
|
201
|
-
!isAbsolutePath(parsed.extensionPath) || !isAbsolutePath(parsed.daemonEntry) ||
|
|
202
|
-
!isRecord(parsed.piInvocation) || !isAbsolutePath(parsed.piInvocation.command) ||
|
|
203
|
-
!Array.isArray(parsed.piInvocation.args) ||
|
|
204
|
-
!parsed.piInvocation.args.every((argument) => typeof argument === "string")) {
|
|
205
|
-
throw new Error("后台 Gateway 启动参数字段无效。");
|
|
206
|
-
}
|
|
207
|
-
return parsed as unknown as GatewayDaemonLaunchSpec;
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
/**
|
|
211
|
-
* 通过独立进程启动 Gateway daemon, 并等待本机控制 endpoint ready。
|
|
212
|
-
*
|
|
213
|
-
* @param spec daemon 启动参数。
|
|
214
|
-
* @returns daemon 已开始持有服务进程时正常结束。
|
|
215
|
-
* @throws {Error} 子进程无法创建、提前退出或未能及时 ready 时抛出。
|
|
216
|
-
*/
|
|
217
|
-
export async function launchDetachedGatewayDaemon(spec: GatewayDaemonLaunchSpec): Promise<void> {
|
|
218
|
-
const encoded = encodeGatewayDaemonLaunchSpec(spec);
|
|
219
|
-
const args = [
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
"--
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
const
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
child.off("
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
}
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
child.
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
*
|
|
288
|
-
*
|
|
289
|
-
* @
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
}
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
*
|
|
314
|
-
*
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
*
|
|
325
|
-
*
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
*
|
|
335
|
-
*
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { spawn } from "node:child_process";
|
|
3
|
+
import type { PiCliInvocation } from "./pi-cli.ts";
|
|
4
|
+
import { GatewayControlClient, GatewayControlError } from "../gateway/gateway-control-ipc.ts";
|
|
5
|
+
import {
|
|
6
|
+
watchGatewayLifecycleOperation,
|
|
7
|
+
writeGatewayLifecycleOperationReceipt,
|
|
8
|
+
} from "./gateway-lifecycle-operation.ts";
|
|
9
|
+
|
|
10
|
+
const LIFECYCLE_RESPONSE_TIMEOUT_MS = 300000;
|
|
11
|
+
|
|
12
|
+
export type GatewayServiceState = "offline" | "starting" | "online" | "auth_required" | "stopping";
|
|
13
|
+
|
|
14
|
+
export interface GatewayServiceStatus {
|
|
15
|
+
state: GatewayServiceState;
|
|
16
|
+
pid?: number;
|
|
17
|
+
startedAt?: string;
|
|
18
|
+
foregroundSessionCount?: number;
|
|
19
|
+
backgroundSessionCount?: number;
|
|
20
|
+
routeCount?: number;
|
|
21
|
+
error?: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface GatewayDaemonLaunchSpec {
|
|
25
|
+
managerDirectory: string;
|
|
26
|
+
extensionPath: string;
|
|
27
|
+
daemonEntry: string;
|
|
28
|
+
piInvocation: PiCliInvocation;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* 控制一个独立于当前 Pi TUI 生命周期的 Gateway daemon。
|
|
33
|
+
*/
|
|
34
|
+
export class GatewayServiceController {
|
|
35
|
+
private readonly controlClient: GatewayControlClient;
|
|
36
|
+
private readonly launchDaemon: (spec: GatewayDaemonLaunchSpec) => Promise<void>;
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* 创建后台 Gateway 控制器。
|
|
40
|
+
*
|
|
41
|
+
* @param managerDirectory Hub 私有数据目录。
|
|
42
|
+
* @param launchSpec daemon 启动时需要的固定运行参数。
|
|
43
|
+
* @param options 可注入控制客户端和进程启动边界。
|
|
44
|
+
*/
|
|
45
|
+
constructor(
|
|
46
|
+
private readonly managerDirectory: string,
|
|
47
|
+
private readonly launchSpec: GatewayDaemonLaunchSpec,
|
|
48
|
+
options: {
|
|
49
|
+
controlClient?: GatewayControlClient;
|
|
50
|
+
launchDaemon?: (spec: GatewayDaemonLaunchSpec) => Promise<void>;
|
|
51
|
+
} = {},
|
|
52
|
+
) {
|
|
53
|
+
this.controlClient = options.controlClient ?? new GatewayControlClient(managerDirectory);
|
|
54
|
+
this.launchDaemon = options.launchDaemon ?? launchDetachedGatewayDaemon;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* 查询真实后台进程和 Gateway 状态。
|
|
59
|
+
*
|
|
60
|
+
* @returns IPC 服务提供的活动状态; 控制通道离线时返回 offline。
|
|
61
|
+
* @throws {GatewayControlError} 身份校验或状态协议不可信时抛出。
|
|
62
|
+
*/
|
|
63
|
+
async status(): Promise<GatewayServiceStatus> {
|
|
64
|
+
try {
|
|
65
|
+
const response = await this.controlClient.request("status");
|
|
66
|
+
return parseServiceStatus(response);
|
|
67
|
+
} catch (error) {
|
|
68
|
+
if (error instanceof GatewayControlError && error.code === "not_running") {
|
|
69
|
+
return { state: "offline" };
|
|
70
|
+
}
|
|
71
|
+
throw error;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* 幂等启动后台 Gateway daemon。
|
|
77
|
+
*
|
|
78
|
+
* @returns 已存在或新启动服务的状态。
|
|
79
|
+
* @throws {Error} daemon 启动失败且没有可用的现有服务时抛出。
|
|
80
|
+
*/
|
|
81
|
+
async start(): Promise<GatewayServiceStatus> {
|
|
82
|
+
const current = await this.status();
|
|
83
|
+
if (current.state !== "offline") {
|
|
84
|
+
return current;
|
|
85
|
+
}
|
|
86
|
+
try {
|
|
87
|
+
await this.launchDaemon(this.launchSpec);
|
|
88
|
+
} catch (error) {
|
|
89
|
+
const concurrentlyStarted = await this.status().catch(() => ({ state: "offline" as const }));
|
|
90
|
+
if (concurrentlyStarted.state !== "offline") {
|
|
91
|
+
return concurrentlyStarted;
|
|
92
|
+
}
|
|
93
|
+
throw error instanceof GatewayControlError
|
|
94
|
+
? error
|
|
95
|
+
: new GatewayControlError(
|
|
96
|
+
"request_failed",
|
|
97
|
+
error instanceof Error ? error.message : "后台 Gateway 启动失败, 请检查配置和微信授权。",
|
|
98
|
+
);
|
|
99
|
+
}
|
|
100
|
+
return this.status();
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* 请求后台 Gateway 在安全停止窗口内优雅退出。
|
|
105
|
+
*
|
|
106
|
+
* @returns Gateway 停止并释放控制租约后的最终状态。
|
|
107
|
+
* @throws {GatewayControlError} Gateway 离线或无法认证时抛出。
|
|
108
|
+
*/
|
|
109
|
+
async stop(): Promise<GatewayServiceStatus> {
|
|
110
|
+
const current = await this.status();
|
|
111
|
+
if (current.state === "offline") {
|
|
112
|
+
return current;
|
|
113
|
+
}
|
|
114
|
+
return parseServiceStatus(await this.controlClient.request("stop", {
|
|
115
|
+
responseTimeoutMs: LIFECYCLE_RESPONSE_TIMEOUT_MS,
|
|
116
|
+
}));
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* 请求后台 Gateway 安全停止当前 daemon 并启动新 daemon, 等待新服务就绪。
|
|
121
|
+
*
|
|
122
|
+
* @returns 新 Gateway 启动就绪后的最终状态。
|
|
123
|
+
* @throws {GatewayControlError} Gateway 离线或无法认证时抛出。
|
|
124
|
+
*/
|
|
125
|
+
async restart(): Promise<GatewayServiceStatus> {
|
|
126
|
+
const current = await this.status();
|
|
127
|
+
if (current.state === "offline") {
|
|
128
|
+
return this.start();
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
const operationId = randomUUID();
|
|
132
|
+
const watcher = await watchGatewayLifecycleOperation(this.managerDirectory, operationId);
|
|
133
|
+
let operationAccepted = false;
|
|
134
|
+
let receiptRead = false;
|
|
135
|
+
try {
|
|
136
|
+
await writeGatewayLifecycleOperationReceipt(this.managerDirectory, {
|
|
137
|
+
action: "restart",
|
|
138
|
+
operationId,
|
|
139
|
+
state: "pending",
|
|
140
|
+
});
|
|
141
|
+
const accepted = await this.controlClient.request("restart", { operationId });
|
|
142
|
+
if (
|
|
143
|
+
!isRecord(accepted) ||
|
|
144
|
+
accepted.state !== "stopping" ||
|
|
145
|
+
(accepted.operationId !== undefined && accepted.operationId !== operationId)
|
|
146
|
+
) {
|
|
147
|
+
throw new GatewayControlError("protocol_error", "后台 Gateway 未确认重启操作。 ");
|
|
148
|
+
}
|
|
149
|
+
operationAccepted = true;
|
|
150
|
+
const receipt = await watcher.wait(LIFECYCLE_RESPONSE_TIMEOUT_MS).catch((error: unknown) => {
|
|
151
|
+
throw new GatewayControlError(
|
|
152
|
+
"timeout",
|
|
153
|
+
error instanceof Error ? error.message : "等待后台 Gateway 重启结果超时。",
|
|
154
|
+
);
|
|
155
|
+
});
|
|
156
|
+
receiptRead = true;
|
|
157
|
+
if (receipt.state === "failed") {
|
|
158
|
+
throw new GatewayControlError(
|
|
159
|
+
"request_failed",
|
|
160
|
+
receipt.message ?? "后台 Gateway 重启失败; 请执行 /wx status 查看当前状态。",
|
|
161
|
+
);
|
|
162
|
+
}
|
|
163
|
+
if (!receipt.serviceStatus) {
|
|
164
|
+
throw new GatewayControlError("protocol_error", "后台 Gateway 重启结果缺少最终状态。 ");
|
|
165
|
+
}
|
|
166
|
+
return parseServiceStatus(receipt.serviceStatus);
|
|
167
|
+
} finally {
|
|
168
|
+
watcher.close();
|
|
169
|
+
if (receiptRead || !operationAccepted) {
|
|
170
|
+
await watcher.removeReceipt().catch(() => undefined);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* 将已验证的 daemon 启动参数编码为 Node CLI payload。
|
|
178
|
+
*
|
|
179
|
+
* @param spec daemon 启动参数。
|
|
180
|
+
* @returns 不含 shell 解释的 base64url JSON。
|
|
181
|
+
*/
|
|
182
|
+
export function encodeGatewayDaemonLaunchSpec(spec: GatewayDaemonLaunchSpec): string {
|
|
183
|
+
return Buffer.from(JSON.stringify(spec), "utf8").toString("base64url");
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* 解码并验证 daemon 启动 payload。
|
|
188
|
+
*
|
|
189
|
+
* @param encoded base64url JSON 字符串。
|
|
190
|
+
* @returns 已验证启动参数。
|
|
191
|
+
* @throws {Error} payload 格式或路径字段无效时抛出。
|
|
192
|
+
*/
|
|
193
|
+
export function decodeGatewayDaemonLaunchSpec(encoded: string): GatewayDaemonLaunchSpec {
|
|
194
|
+
let parsed: unknown;
|
|
195
|
+
try {
|
|
196
|
+
parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as unknown;
|
|
197
|
+
} catch {
|
|
198
|
+
throw new Error("后台 Gateway 启动参数编码无效。");
|
|
199
|
+
}
|
|
200
|
+
if (!isRecord(parsed) || !isAbsolutePath(parsed.managerDirectory) ||
|
|
201
|
+
!isAbsolutePath(parsed.extensionPath) || !isAbsolutePath(parsed.daemonEntry) ||
|
|
202
|
+
!isRecord(parsed.piInvocation) || !isAbsolutePath(parsed.piInvocation.command) ||
|
|
203
|
+
!Array.isArray(parsed.piInvocation.args) ||
|
|
204
|
+
!parsed.piInvocation.args.every((argument) => typeof argument === "string")) {
|
|
205
|
+
throw new Error("后台 Gateway 启动参数字段无效。");
|
|
206
|
+
}
|
|
207
|
+
return parsed as unknown as GatewayDaemonLaunchSpec;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* 通过独立进程启动 Gateway daemon, 并等待本机控制 endpoint ready。
|
|
212
|
+
*
|
|
213
|
+
* @param spec daemon 启动参数。
|
|
214
|
+
* @returns daemon 已开始持有服务进程时正常结束。
|
|
215
|
+
* @throws {Error} 子进程无法创建、提前退出或未能及时 ready 时抛出。
|
|
216
|
+
*/
|
|
217
|
+
export async function launchDetachedGatewayDaemon(spec: GatewayDaemonLaunchSpec): Promise<void> {
|
|
218
|
+
const encoded = encodeGatewayDaemonLaunchSpec(spec);
|
|
219
|
+
const args = [
|
|
220
|
+
// 当前入口是 daemon-entry.mjs,不需要任何 TypeScript flag。
|
|
221
|
+
// 仍保留对 .ts 入口的条件分支:测试与自定义入口可能直接 spawn 未编译的 .ts。
|
|
222
|
+
...(spec.daemonEntry.endsWith(".ts") ? ["--experimental-transform-types"] : []),
|
|
223
|
+
spec.daemonEntry,
|
|
224
|
+
"--launch-payload",
|
|
225
|
+
encoded,
|
|
226
|
+
];
|
|
227
|
+
const child = spawn(spec.piInvocation.command, args, {
|
|
228
|
+
detached: true,
|
|
229
|
+
stdio: ["ignore", "ignore", "ignore", "ipc"],
|
|
230
|
+
windowsHide: true,
|
|
231
|
+
env: {
|
|
232
|
+
...process.env,
|
|
233
|
+
PI_WECHAT_HUB_DAEMON: "1",
|
|
234
|
+
},
|
|
235
|
+
});
|
|
236
|
+
child.unref();
|
|
237
|
+
|
|
238
|
+
await new Promise<void>((resolveLaunch, rejectLaunch) => {
|
|
239
|
+
let settled = false;
|
|
240
|
+
const timeout = setTimeout(() => finish(new Error("后台 Gateway 启动超时, 请使用 /wx status 检查。")), 30000);
|
|
241
|
+
timeout.unref();
|
|
242
|
+
const cleanup = (): void => {
|
|
243
|
+
clearTimeout(timeout);
|
|
244
|
+
child.off("message", onMessage);
|
|
245
|
+
child.off("error", onError);
|
|
246
|
+
child.off("exit", onExit);
|
|
247
|
+
};
|
|
248
|
+
const finish = (error?: Error): void => {
|
|
249
|
+
if (settled) {
|
|
250
|
+
return;
|
|
251
|
+
}
|
|
252
|
+
settled = true;
|
|
253
|
+
cleanup();
|
|
254
|
+
if (child.connected) {
|
|
255
|
+
child.disconnect();
|
|
256
|
+
}
|
|
257
|
+
if (error) {
|
|
258
|
+
rejectLaunch(error);
|
|
259
|
+
} else {
|
|
260
|
+
resolveLaunch();
|
|
261
|
+
}
|
|
262
|
+
};
|
|
263
|
+
const onMessage = (message: unknown): void => {
|
|
264
|
+
if (!isRecord(message)) {
|
|
265
|
+
finish(new Error("后台 Gateway 启动握手响应无效。"));
|
|
266
|
+
return;
|
|
267
|
+
}
|
|
268
|
+
if (message.kind === "ready") {
|
|
269
|
+
finish();
|
|
270
|
+
return;
|
|
271
|
+
}
|
|
272
|
+
if (message.kind === "failed") {
|
|
273
|
+
finish(new Error(typeof message.message === "string" ? message.message : "后台 Gateway 启动失败。"));
|
|
274
|
+
}
|
|
275
|
+
};
|
|
276
|
+
const onError = (): void => finish(new Error("无法创建后台 Gateway 进程。"));
|
|
277
|
+
const onExit = (code: number | null): void => {
|
|
278
|
+
finish(new Error(`后台 Gateway 在 ready 前退出 (code ${code ?? "unknown"})。`));
|
|
279
|
+
};
|
|
280
|
+
child.on("message", onMessage);
|
|
281
|
+
child.once("error", onError);
|
|
282
|
+
child.once("exit", onExit);
|
|
283
|
+
});
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/**
|
|
287
|
+
* 解析并校验 daemon 返回的状态对象。
|
|
288
|
+
*
|
|
289
|
+
* @param value 未知 IPC response payload。
|
|
290
|
+
* @returns Gateway service 状态。
|
|
291
|
+
* @throws {GatewayControlError} 状态字段不受支持时抛出。
|
|
292
|
+
*/
|
|
293
|
+
function parseServiceStatus(value: unknown): GatewayServiceStatus {
|
|
294
|
+
if (!isRecord(value) || !isGatewayServiceState(value.state)) {
|
|
295
|
+
throw new GatewayControlError("protocol_error", "后台 Gateway 状态响应字段无效。");
|
|
296
|
+
}
|
|
297
|
+
const numericFields = ["pid", "foregroundSessionCount", "backgroundSessionCount", "routeCount"] as const;
|
|
298
|
+
for (const field of numericFields) {
|
|
299
|
+
if (value[field] !== undefined && (!Number.isSafeInteger(value[field]) || (value[field] as number) < 0)) {
|
|
300
|
+
throw new GatewayControlError("protocol_error", "后台 Gateway 状态计数字段无效。");
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
if (value.startedAt !== undefined && typeof value.startedAt !== "string") {
|
|
304
|
+
throw new GatewayControlError("protocol_error", "后台 Gateway 启动时间字段无效。");
|
|
305
|
+
}
|
|
306
|
+
if (value.error !== undefined && typeof value.error !== "string") {
|
|
307
|
+
throw new GatewayControlError("protocol_error", "后台 Gateway 状态错误字段无效。");
|
|
308
|
+
}
|
|
309
|
+
return value as unknown as GatewayServiceStatus;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/**
|
|
313
|
+
* 判断状态值是否为受支持的 Gateway lifecycle state。
|
|
314
|
+
*
|
|
315
|
+
* @param value 未知状态字段。
|
|
316
|
+
* @returns 状态受支持时返回 true。
|
|
317
|
+
*/
|
|
318
|
+
function isGatewayServiceState(value: unknown): value is GatewayServiceState {
|
|
319
|
+
return value === "offline" || value === "starting" || value === "online" ||
|
|
320
|
+
value === "auth_required" || value === "stopping";
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* 判断值是否为普通对象。
|
|
325
|
+
*
|
|
326
|
+
* @param value 待校验值。
|
|
327
|
+
* @returns 普通对象时返回 true。
|
|
328
|
+
*/
|
|
329
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
330
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/**
|
|
334
|
+
* 判断路径是否为绝对路径。
|
|
335
|
+
*
|
|
336
|
+
* @param value 待校验字段。
|
|
337
|
+
* @returns 绝对路径字符串时返回 true。
|
|
338
|
+
*/
|
|
339
|
+
function isAbsolutePath(value: unknown): value is string {
|
|
340
|
+
return typeof value === "string" && (value.startsWith("/") || /^[a-z]:[\\/]/i.test(value));
|
|
341
|
+
}
|