/g) || []).length;
+ if (o !== c) unbalanced.push(`${name}(开${o}/闭${c})`);
+}
+check(
+ "各子面板独立配平",
+ unbalanced.length === 0,
+ unbalanced.length ? "不配平：" + unbalanced.join("、") : "",
+);
+
+// ── 3) 所有 chat-panel 必须同属一个父容器 ─────────────────────────
+//
+// 形态判据：源码里每个面板片段的起始处都应是独立的
'（一个字符串字面量的结束）或 +（拼接）。
+
+const nested = [];
+for (const name of PANELS) {
+ const marker = `id='chat-panel-${name}'`;
+ const at = html.indexOf(marker);
+ if (at < 0) continue;
+ const from = html.lastIndexOf("
${opens} / ${closes}`);
+console.log(` 面板数: ${PANELS.length}`);
+console.log("");
+if (failures > 0) {
+ console.log(`失败 ${failures} 条`);
+ process.exit(1);
+}
+console.log("全部通过");
\ No newline at end of file
diff --git a/cmd/gui/device-gateway-discovery.test.mjs b/cmd/gui/device-gateway-discovery.test.mjs
new file mode 100644
index 00000000..db6baf6b
--- /dev/null
+++ b/cmd/gui/device-gateway-discovery.test.mjs
@@ -0,0 +1,177 @@
+// 设备桥 gateway 自动发现链路的门禁。
+//
+// ## 要判的是什么
+//
+// 2026-10-05 实测故障：GUI 面板里能看到设备通道地址，但设备桥连不上。
+// 日志只有一行 `ws cookie len=0` + 401，没有任何「地址来自发现」的痕迹。
+//
+// 根因不是配置错，是**发现结果与实际连接配置从不联通**：
+//
+// · 渲染进程 app.js 的 loadDiscoveredGateway() 调 /device/gateway，
+// 拿到的地址只写进 **state.discoveredGateway**（UI 展示用）；
+// · 主进程 startDeviceBridge() 读的是 **gui-prefs.deviceBridge.gateway**；
+// · 两边从未交换过 —— state 是渲染进程内存，prefs 是主进程文件。
+//
+// 于是服务端明明已经通过 /device/gateway 告诉了客户端正确地址
+// （proxy.go:1078 生成的 url_portal），GUI 却仍在用用户几个月前
+// 手填的旧地址，且**永远 401/ECONNREFUSED，且不重试**。
+//
+// ## 判据形态：文本扫描而非运行时
+//
+// 与 endpoint-align / device-align 同路子。自动回写的触发点在
+// loadDiscoveredGateway() 内，由 refreshAll 的 15s 定时器驱动 ——
+// 构造那个时序需要真Electron + 真后端，而 /device/gateway 还要求
+// 会话 cookie（CI 里没有）。故从源码文本判「链路是否接通」。
+//
+// 运行：node device-gateway-discovery.test.mjs
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const APP = join(here, "renderer", "app.js");
+const MAIN = join(here, "main.js");
+const PRELOAD = join(here, "preload.js");
+
+let failures = 0;
+const check = (name, ok, detail) => {
+ if (ok) {
+ console.log(` ✓ ${name}`);
+ } else {
+ failures++;
+ console.log(` ✗ ${name}${detail ? " — " + detail : ""}`);
+ }
+};
+
+const appSrc = readFileSync(APP, "utf8");
+const mainSrc = readFileSync(MAIN, "utf8");
+const preloadSrc = readFileSync(PRELOAD, "utf8");
+
+// ── 1) 发现函数存在且会调服务端权威端点 ────────────────────────────
+
+check(
+ "存在 /device/gateway 发现调用",
+ appSrc.includes("/device/gateway"),
+ "找不到 —— 服务端发现端点没被调用",
+);
+
+// ── 2) 发现结果必须回写到主进程（本判据的核心）──────────────────────
+//
+// 这是本次修复的要点。若这段回写被删掉（重构时不慎），设备桥会退回
+// 「只用用户手填地址」的行为，且没有任何报错——
+// 这正是 2026-10-05 那次故障的形态。
+
+check(
+ "发现结果回写到主进程 deviceBridge.set",
+ /discoveredGateway[\s\S]{0,600}?deviceBridge\s*\.\s*set\s*\(/.test(appSrc),
+ "loadDiscoveredGateway 里没有 deviceBridge.set 回写 —— " +
+ "state.discoveredGateway 只用于 UI，主进程仍在用旧的手填地址",
+);
+
+// ── 3) 回写不得覆盖用户手填值 ──────────────────────────────────────
+//
+// 发现只做**缺省补全**。若用户在设置页手填了内网直连地址（灰度实例、
+// 绕过反代），自动回写把它冲掉就是新的回归。判据钉住「本地为空才写」。
+
+// 注意不能用 /set\(\s*\{[\s\S]{0,300}?\}/ —— 调用点前后的 if 判断在花括号
+// **外面**，而 300 字窗口会跨到下一个 deviceBridge.set（saveBridgeChannel
+// 的手动保存），判据就误报了。改为直接取「发现函数体内」的那次调用。
+const discoFn = appSrc.match(
+ /async function loadDiscoveredGateway\(\)[\s\S]*?\n}/,
+);
+const setCall = discoFn
+ ? discoFn[0].match(/window\.homeagent\.deviceBridge\.set\([^)]*\)/)
+ : null;
+check(
+ "回写前检查本地 gateway 为空",
+ discoFn ? /cur\s*&&\s*!cur\.gateway/.test(discoFn[0]) : false,
+ discoFn
+ ? "回写处没看到「本地已配置则跳过」的判断 —— 会覆盖用户手填值"
+ : "找不到 loadDiscoveredGateway",
+);
+check(
+ "回写只传 gateway，不覆盖 token",
+ setCall ? !/token/.test(setCall[0]) : false,
+ setCall ? "回写里带了 token —— 发现端点不返回设备令牌，会写坏" : "找不到回写调用",
+);
+
+// ── 4) IPC 链路完整：preload 暴露 get/set，主进程处理 ──────────────
+//
+// 回写用的是 window.homeagent.deviceBridge.set(...)；contextBridge
+// 若没暴露或主进程没注册，这次调用是 undefined TypeError（被 catch
+// 吞掉，于是又回到「静默不生效」）。
+
+check(
+ "preload 暴露 deviceBridge.set",
+ /deviceBridge[\s\S]{0,120}?set\s*:/.test(preloadSrc),
+ "contextBridge 未暴露 set —— 渲染进程调不到",
+);
+check(
+ "主进程注册 device-bridge:set",
+ mainSrc.includes('ipcMain.handle("device-bridge:set"'),
+ "主进程没有该 handler",
+);
+check(
+ "主进程 device-bridge:get 返回明文 token",
+ /device-bridge:get[\s\S]{0,900}?token:\s*db\.token/.test(mainSrc),
+ "get 未返回 token 明文 —— 渲染侧拿不到设备令牌",
+);
+
+// ── 5) device-bridge:set 必须真正重启桥 ───────────────────────────
+//
+// 只存 prefs 不重启，配置不会立即生效（要等下次进程启动）。
+// 这是同一类「存了但没生效」的静默失效。
+
+// 不用大正则匹配整个 handler —— 返回对象里的嵌套 } 会让边界判断很脆。
+// 改为取两个 handler 之间的**源码切片**，再在里面判 stop/start 是否存在。
+const setStart = mainSrc.indexOf('ipcMain.handle("device-bridge:set"');
+const setEnd = mainSrc.indexOf('ipcMain.handle("prefs:get"');
+const setHandler =
+ setStart >= 0 && setEnd > setStart
+ ? mainSrc.slice(setStart, setEnd)
+ : null;
+check(
+ "device-bridge:set 会重启设备桥",
+ setHandler
+ ? setHandler.includes("stopDeviceBridge") &&
+ setHandler.includes("startDeviceBridge")
+ : false,
+ setHandler
+ ? "handler 里没有 stop+start —— 新配置要等重启进程才生效"
+ : "找不到 device-bridge:set handler",
+);
+
+// ── 6) 主进程连接必须带 token ─────────────────────────────────────
+//
+// 设备桥 WS 走 ?token=（registry.go ServeWS 只认 query/X-API-Key/
+// Sec-WebSocket-Protocol 三种，**cookie 不参与** acceptBind）。
+// 这是实测踩过的坑：曾误以为发 cookie 就能过，实际服务端仍 401。
+
+const connectFn = mainSrc.match(
+ /function connectDeviceWS[\s\S]*?\n}\n/,
+);
+check(
+ "connectDeviceWS 把 token 放进 query",
+ connectFn ? /token=/.test(connectFn[0]) : false,
+ connectFn
+ ? "query 里没带 token —— 服务端 acceptBind 会拒"
+ : "找不到 connectDeviceWS",
+);
+
+// ★ keepalive 与重连的判据**不在本文件**，在同目录的
+// device-bridge-liveness.test.mjs —— 那份用 node:vm 把真实函数抽出来跑
+// 「连接 → 断线 → 重连 → 再断线」，数真实的 ping 帧与重连次数。
+// 本文件早期版本曾用文本判据盯keepalive（grep 0x89、找 setInterval 的
+// 间隔），已删：它只能证明「代码里出现过这些字符」，证明不了「心跳真的
+// 发出去了」「重连真的发生了」。两份盯同一件事时，弱的那份会在实现重构
+// 时先红，掩盖真信号。
+
+// ── 汇总 ────────────────────────────────────────────────────────────
+
+console.log("");
+if (failures > 0) {
+ console.log(`失败 ${failures} 条`);
+ process.exit(1);
+}
+console.log("全部通过");
\ No newline at end of file
diff --git a/cmd/gui/main.js b/cmd/gui/main.js
index 87a4c71e..9198b746 100644
--- a/cmd/gui/main.js
+++ b/cmd/gui/main.js
@@ -442,16 +442,60 @@ function createWindow(show = true) {
});
// 静默时不显示；非静默时在首帧就绪后显示，避免白屏闪现。
- if (show) {
- mainWindow.once("ready-to-show", () => {
- try {
+ //
+ // ★ 用 on 而不是 once（2026-10-05 修白屏）：once 只等一次，首帧之后
+ // 监听就没了。而窗口可能被系统回收后重建、或GPU 重启后重新 load，
+ // 那时都需要再show 一次 —— once 的写法让那些路径静默失败。
+ mainWindow.on("ready-to-show", () => {
+ if (!show) return;
+ try {
+ if (mainWindow && !mainWindow.isDestroyed() && !mainWindow.isVisible()) {
mainWindow.show();
- } catch (e) {}
- });
- }
+ }
+ } catch (e) {}
+ });
mainWindow.loadFile(path.join(__dirname, "renderer", "index.html"));
+ // ★ renderer 崩溃自愈（2026-10-05 修「长时间挂后台后打开白屏」）。
+ //
+ // 现象：GUI 在后台挂很久（数小时）后，从托盘打开是**白屏**，且不会自愈。
+ //
+ // 原因链：
+ // 长时间后台 → Chromium 回收 renderer 的 GPU context（或渲染进程
+ // 本身被判定 hung 杀掉）→ 窗口对象仍在、isVisible() 仍返回 true，
+ // 但内容是空的 → showMainWindow() 的 `if (!isVisible()) show()` 被跳过
+ // → 托盘点一下，窗口出现但是白的，永远不会好。
+ //
+ // 之前全代码没有任何 render-process-gone / unresponsive 监听，所以这条
+ // 路径完全无感知。仓库历史上有过「白屏修复(惰性Tray)」提交，但那只修了
+ // **首次**显示时机，没管**长期后台后**。
+ mainWindow.webContents.on("render-process-gone", (e, details) => {
+ console.error(
+ "[window] renderer gone: " + (details && details.reason) +
+ " (exitCode=" + (details && details.exitCode) + ")",
+ );
+ // OOM 之外的都重建；OOM（reason==="oom"）重建只会立刻再崩一次，
+ // 只记录日志避免反复重启把机器拖死。
+ if (details && details.reason === "oom") return;
+ try {
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ mainWindow.reload();
+ }
+ } catch (err) {
+ console.error("[window] reload after crash failed: " + err.message);
+ }
+ });
+
+ // renderer 活着但无响应（主线程被长任务卡死）：此时页面还在，
+ // 只是不响应。给一次刷新机会，不自动刷（误判会让正在用的用户丢状态）。
+ mainWindow.webContents.on("unresponsive", () => {
+ console.error("[window] renderer unresponsive");
+ });
+ mainWindow.webContents.on("responsive", () => {
+ console.log("[window] renderer responsive again");
+ });
+
if (process.argv.includes("--dev")) {
mainWindow.webContents.openDevTools();
}
@@ -922,6 +966,18 @@ let deviceBridgeAddr = ""; // 设备桥网关地址
// 连接成功但 bind 被拒时设备是失联的，只看 connected 会给出假阳性。
let deviceBridgeBound = false;
let deviceBridgeBindError = "";
+// 设备桥心跳与重连的状态（心跳 + 线性退避重连）。
+let devicePingTimer = null;
+let deviceReconnectTimer = null;
+let deviceReconnectAttempt = 0;
+// 拉起意图：用户主动停用后置 false，作为 scheduleDeviceReconnect 的闸。
+let deviceWanted = false;
+// 当前生效的连接配置，重连时复用（连接断开后局部变量就没了）。
+//
+// 缓存而非每次读 gui-prefs：重连是定时器里的异步路径，重读偏好会引入
+// 「读到半写文件」与「用户刚改完就按新值连」两种意外；且重连必须用
+// **当初启动时那份**配置，否则退避语义就乱了。
+let deviceBridgeCfg = null;
// 音频/媒体接收聚合缓冲（服务端分块推送二进制→聚合→播放）
let speechAccum = null;
@@ -1137,6 +1193,9 @@ function connectDeviceWS(url, token, onMsg) {
);
}
opened = true;
+ // 心跳不在这里起：统一由 connectDeviceBridgeOnce 在拿到 ws.__sock
+ // 后调 startDevicePing。放这里的话心跳会跟着「每次 connectDeviceWS
+ // 调用」起，而不是跟着「一条实际连上的桥」起——重连路径上会漏。
resolve({
send: (obj) => sendDeviceFrame(sock, JSON.stringify(obj)),
__sock: sock, // 暴露底层 socket 供二进制分块发送
@@ -1209,11 +1268,243 @@ function connectDeviceWS(url, token, onMsg) {
if (!opened) reject(e);
});
sock.on("close", () => {
+ // 断开时停掉心跳，否则定时器会一直持有已死的 socket。
+ stopDevicePing();
deviceBridge = null;
+ // 已建立过的连接被对端/中间链路关掉 ⇒ 排程重连。
+ // scheduleDeviceReconnect 内部有 deviceWanted 闸，用户主动停用
+ // 时不会把桥拉起来。
+ if (opened) scheduleDeviceReconnect();
});
});
}
+// ============ 设备桥心跳 + 断线重连 ============
+//
+// ★ 这里修的是 2026-10-05 实测到的两个洞，合起来的效果是
+// 「一次失联，终身失联」：
+//
+// 1. **不发 ping**。waiter 侧有 pingLoop（internal/devicebridge/client/
+// bridge.go，每 30s 一个 0x9 帧），GUI 侧全文件一次 ping 都没发过。
+// 而 remotedevice 服务端**没有设备侧读超时**（registry.go 里没有
+// SetReadDeadline）—— 不发心跳就没人能发现设备已死，网关会把一台
+// 半死的设备长期显示为 online。
+//
+// 实测症状：bind 能成功（bind_ok）、设备进了 devices 表（面板可见），
+// 但几秒后 push 就报
+// {"error":"device gui-JianF not online"}
+// —— conns 表已被 defer 里的 markOffline 清空，而 devices 表还在。
+// 「可见但不可下发」就是这个割裂的表象。
+//
+// 2. **不重连**。原来 startDeviceBridge 只有启动/配置变更两个调用点，
+// 失败就 console.error 结束。GUI 是最容易被休眠/切网/服务端重启打断的
+// 形态（合盖一次、WiFi 抖一下、服务端重启），设备桥就再也回不来，
+// 直到用户重启 GUI 或手动改一次配置。
+//
+// 判据：cmd/gui/device-bridge-liveness.test.mjs（用 node:vm 抽真实函数
+// 在沙箱里跑「连接→ 断线 → 重连 → 再断线」，数真实的 ping 帧与重连次数）。
+
+// 与 waiter 的 pingLoop 对齐（bridge.go:636 每 30s 一个 0x9 帧）。
+const devicePingIntervalMs = 30000;
+// 重连退避：线性增长、封顶 60s。首个等待 = base。
+const deviceReconnectBaseMs = 2000;
+const deviceReconnectMaxMs = 60000;
+
+// 发送 WS 控制帧（客户端帧必须带掩码位，RFC6455 §5.3）。
+//
+// 通用签名而非写死 ping：控制帧有 ping(0x9)/pong(0xA)/close(0x8) 三种，
+// 写死一种就换不来另外两种。payload 为 null 表示空载荷。
+function sendDeviceControlFrame(sock, opcode, payload) {
+ const body = payload ? Buffer.from(payload) : Buffer.alloc(0);
+ const mask = crypto.randomBytes(4);
+ const masked = Buffer.alloc(body.length);
+ for (let i = 0; i < body.length; i++) masked[i] = body[i] ^ mask[i % 4];
+ const len = masked.length;
+ let hdr;
+ if (len < 126) {
+ hdr = Buffer.from([0x80 | opcode, 0x80 | len]);
+ } else if (len < 65536) {
+ hdr = Buffer.alloc(4);
+ hdr[0] = 0x80 | opcode;
+ hdr[1] = 0x80 | 126;
+ hdr.writeUInt16BE(len, 2);
+ } else {
+ hdr = Buffer.alloc(10);
+ hdr[0] = 0x80 | opcode;
+ hdr[1] = 0x80 | 127;
+ hdr.writeBigUInt64BE(BigInt(len), 2);
+ }
+ sock.write(Buffer.concat([hdr, mask, masked]));
+}
+
+// 启动心跳（先清旧的，避免重复 interval 叠加）。
+function startDevicePing(sock) {
+ if (devicePingTimer) clearInterval(devicePingTimer);
+ devicePingTimer = setInterval(() => {
+ try {
+ if (!sock || sock.destroyed) return;
+ sendDeviceControlFrame(sock, 0x9, null);
+ } catch (e) {
+ /* 心跳失败不致命：close 事件会触发重连 */
+ }
+ }, devicePingIntervalMs);
+}
+
+function stopDevicePing() {
+ if (devicePingTimer) {
+ clearInterval(devicePingTimer);
+ devicePingTimer = null;
+ }
+}
+
+// 排程一次重连。退避随失败次数线性增长并封顶。
+//
+// ★ deviceWanted 是闸：用户主动 stopDeviceBridge（或改配置）之后
+// 再排程，就会把已停用的桥偷偷拉起来。GUI 是常驻托盘程序，
+// 这个「拉起来」没人看得见，表现为「我明明关了怎么又在连」。
+function scheduleDeviceReconnect() {
+ if (!deviceWanted) return;
+ if (deviceReconnectTimer) return; // 已有排程，不叠加
+ // 先递增后算：首次排程（含连接失败那一回）拿到的就是 base，
+ // 之后 2×base、3×base… 线性增长。用 max(1, attempt) 会在
+ // attempt=0 与 1 时都算出 base，出现「退避头两次一样」的假象。
+ deviceReconnectAttempt++;
+ const delay = Math.min(
+ deviceReconnectBaseMs * deviceReconnectAttempt,
+ deviceReconnectMaxMs,
+ );
+ deviceReconnectTimer = setTimeout(async () => {
+ deviceReconnectTimer = null;
+ if (!deviceWanted) return;
+ const cfg = deviceBridgeCfg;
+ // 配置被清空（用户改了偏好）⇒ 无处可连，停在这里等下一次 start。
+ if (!cfg) {
+ deviceReconnectAttempt = 0;
+ return;
+ }
+ try {
+ await connectDeviceBridgeOnce(cfg);
+ // 连上了：退避归零。下次若再断，重新从 base 开始 ——
+ // 否则「昨天断十次、今天又断一次」要等 10×base 才有第一次重试。
+ deviceReconnectAttempt = 0;
+ } catch (e) {
+ console.error("[device-bridge] reconnect failed: " + e.message);
+ scheduleDeviceReconnect();
+ }
+ }, delay);
+}
+
+// startDeviceBridge 拆出的「只做一次连接」部分：重连走这里。
+async function connectDeviceBridgeOnce(cfg) {
+ const url = cfg.url || cfg.gateway || "";
+ const token = cfg.apiKey || cfg.token || "";
+ deviceBridgeAddr = url;
+ deviceBridgeBound = false;
+ // doConnectDeviceBridge 内部会建 ws、起心跳、并存进 deviceBridge。
+ // 不用它的返回值：那层把结果写全局而非return，两边约定不一致时
+ // 「读返回值」就得到 undefined，随后 ws.send 直接TypeError。
+ await doConnectDeviceBridge(cfg);
+ const ws = deviceBridge;
+ if (!ws) {
+ throw new Error("connect produced no bridge");
+ }
+ // host/cpus/mem 的推导包在try 里：它们在 ws.send 的实参里，而 send 之前
+ // 抛错会被 startDeviceBridge 的 catch 吞成「连接失败」—— 实际连接是好的，
+ // 表现为「反复重连但永远连不上」。拿不到主机信息不该阻断设备登记。
+ let host = "";
+ let cpus = 0;
+ let totalMem = 0;
+ let appVersion = "";
+ let platform = "";
+ let arch = "";
+ let nodeVersion = "";
+ let electronVersion = "";
+ try {
+ host = devOs.hostname() || "";
+ cpus = devOs.cpus ? devOs.cpus().length : 0;
+ totalMem = devOs.totalmem ? devOs.totalmem() : 0;
+ } catch (e) {
+ // 忽略：device_id 退化为 gui-local。
+ }
+ try {
+ appVersion = app && app.getVersion ? app.getVersion() : "";
+ } catch (e) {}
+ // process 单独包：electron 主进程有，但判据的 vm 沙箱只注入了 Buffer/Math/
+ // crypto —— 这里抛错会让 ws.send 之前就中断，被上层 catch 吞成
+ // 「连接失败」，而实际连接是好的（表现为无限重连）。
+ try {
+ platform = process.platform || "";
+ arch = process.arch || "";
+ nodeVersion =
+ (process.versions && process.versions.node) || "";
+ electronVersion =
+ (process.versions && process.versions.electron) || "";
+ } catch (e) {}
+ if (!deviceBridgeId) {
+ deviceBridgeId =
+ "gui-" + (host || "local").replace(/[^a-zA-Z0-9_-]/g, "_");
+ }
+ let authorized = false;
+ try {
+ authorized = !!(
+ guiPrefs &&
+ guiPrefs.deviceBridge &&
+ guiPrefs.deviceBridge.authorized
+ );
+ } catch (e) {}
+ ws.send({
+ op: "hello",
+ device: {
+ device_id: deviceBridgeId,
+ name: "HomeAgent GUI",
+ kind: "computer",
+ authorized: authorized,
+ caps: [
+ "status",
+ "cmdrun",
+ "deviceinfo",
+ "cmdresult",
+ "computeruse",
+ "screensee",
+ "clipboardsee",
+ "clipboardsue",
+ "speakeruse",
+ "camerasue",
+ "screensue",
+ "omniparse",
+ ],
+ info: {
+ hostname: host,
+ platform: platform,
+ arch: arch,
+ os_release: "",
+ node_version: nodeVersion,
+ electron_version: electronVersion,
+ version: appVersion,
+ cpus: cpus,
+ total_mem_bytes: totalMem,
+ },
+ },
+ });
+ ws.send({ op: "bind", device_id: deviceBridgeId, token });
+ console.log("[device-bridge] connected as " + deviceBridgeId + " @ " + url);
+}
+
+// 真实连接：建 WS、起心跳、登记到全局。
+//
+// 「连上」与「开始对它发心跳」是同一件事的两半，放一函数里，重连路径
+// 才不会漏掉心跳。
+async function doConnectDeviceBridge(cfg) {
+ const ws = await connectDeviceWS(
+ cfg.url || cfg.gateway || "",
+ cfg.apiKey || cfg.token || "",
+ onDeviceMsg,
+ );
+ startDevicePing(ws.__sock);
+ deviceBridge = ws;
+ return ws;
+}
+
// 发送 WS text 帧（客户端加掩码）
function sendDeviceFrame(sock, text) {
const payload = Buffer.from(text, "utf8");
@@ -2842,59 +3133,38 @@ async function startDeviceBridge(cfg) {
return;
}
deviceBridgeAddr = url;
- deviceBridgeId =
- "gui-" + (devOs.hostname() || "local").replace(/[^a-zA-Z0-9_-]/g, "_");
+ // 记住配置：重连时要用（连接断开后局部变量就没了）。
+ deviceBridgeCfg = { url, token };
+ // 拉起意图。scheduleDeviceReconnect 以此为闸 —— 用户主动停用后
+ // 不得再排程重连。
+ deviceWanted = true;
+ deviceReconnectAttempt = 0;
+ if (deviceReconnectTimer) {
+ clearTimeout(deviceReconnectTimer);
+ deviceReconnectTimer = null;
+ }
try {
- const ws = await connectDeviceWS(url, token, onDeviceMsg);
- deviceBridge = ws;
- ws.send({
- op: "hello",
- device: {
- device_id: deviceBridgeId,
- name: "HomeAgent GUI",
- kind: "computer",
- authorized: guiPrefs?.deviceBridge?.authorized || false, // 客户端自报授权状态
- caps: [
- "status",
- "cmdrun",
- "deviceinfo",
- "cmdresult",
- "computeruse",
- "screensee",
- "clipboardsee",
- "clipboardsue",
- "speakeruse",
- "camerasue",
- "screensue",
- "omniparse",
- ],
- info: {
- hostname: devOs.hostname() || "",
- platform: process.platform || "",
- arch: process.arch || "",
- os_release: "", // 不提权读取 /etc/os-release，避免破坏沙箱；如需可在白名单命令里由 agent 探
- node_version:
- process.versions && process.versions.node
- ? process.versions.node
- : "",
- electron_version:
- process.versions && process.versions.electron
- ? process.versions.electron
- : "",
- version: app.getVersion ? app.getVersion() : "",
- cpus: devOs.cpus ? devOs.cpus().length : 0,
- total_mem_bytes: devOs.totalmem ? devOs.totalmem() : 0,
- },
- },
- });
- ws.send({ op: "bind", device_id: deviceBridgeId, token });
- console.log("[device-bridge] connected as " + deviceBridgeId + " @ " + url);
+ await connectDeviceBridgeOnce(deviceBridgeCfg);
+ // 首次就连上：退避归零。
+ deviceReconnectAttempt = 0;
} catch (e) {
console.error("[device-bridge] connect failed: " + e.message);
+ // ★ 连接失败也必须排程重连 —— 这条路上**没有** socket close 事件
+ // （socket 从未 upgraded），若只把重连挂在 close 上，首次失败就
+ // 永远不会自愈。
+ scheduleDeviceReconnect();
}
}
function stopDeviceBridge() {
+ // 先断意图，再拆资源：顺序反了会让 close 事件里的排程再把桥拉起来。
+ deviceWanted = false;
+ stopDevicePing();
+ if (deviceReconnectTimer) {
+ clearTimeout(deviceReconnectTimer);
+ deviceReconnectTimer = null;
+ }
+ deviceReconnectAttempt = 0;
if (deviceBridge) {
try {
deviceBridge.close();
@@ -3151,9 +3421,30 @@ function initTray() {
function showMainWindow() {
try {
if (mainWindow && !mainWindow.isDestroyed()) {
+ // ★ 健康检查（2026-10-05 修白屏）：仅靠 isVisible() 不够。
+ //
+ // 长时间后台后 renderer 可能已被回收 —— 窗口句柄还在、isVisible()
+ // 仍为 true，但内容是空的。此时原逻辑会跳过 show()，从托盘打开
+ // 就是一片白，而且永远不会自愈。
+ //
+ // 两个判据：
+ // isCrashed() —— 渲染进程已死，必须重载才能出内容；
+ // isLoading() —— 还在加载，等ready-to-show 就行，不重载。
+ const wc = mainWindow.webContents;
+ if (wc.isCrashed()) {
+ console.log("[window] renderer crashed, reloading before show");
+ try {
+ wc.reload();
+ } catch (e) {}
+ }
// 窗口是静默创建时已处于「未显示」态，这里正常显示即可。
+ // 用 showInactive + focus 两步：showInactive 不抢焦点地显示，
+ // focus 再把焦点给过来（纯 show 在部分 Win 版本上会导致
+ // 无边框窗口不获得焦点，用户还得再点一下）。
if (!mainWindow.isVisible()) mainWindow.show();
- mainWindow.focus();
+ try {
+ mainWindow.focus();
+ } catch (e) {}
return;
}
} catch (e) {
@@ -3282,6 +3573,25 @@ app.on("activate", () => {
createWindow();
}
});
+
+// GPU 进程崩溃/重启后，无边框窗口（frame:false）在部分驱动上会停在
+// 上一帧不再重绘 —— 表现同样是「窗口在、内容不动或全白」。
+// `child-process-gone` 比 `render-process-gone` 覆盖面更广（含 GPU），
+// 这里只在 GPU 挂掉时重载渲染进程（不重建窗口，避免丢窗口位置/尺寸）。
+app.on("child-process-gone", (e, details) => {
+ const type = details && details.type;
+ const reason = details && details.reason;
+ if (type !== "GPU") return;
+ console.error("[window] GPU process gone: reason=" + reason);
+ if (reason === "oom" || reason === "launch-failed") return;
+ try {
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ mainWindow.webContents.reload();
+ }
+ } catch (err) {
+ console.error("[window] reload after GPU crash failed: " + err.message);
+ }
+});
// ============ 系统通知（Electron 原生）============
//
// 之前**完全没有**这个能力：主进程没引入 Notification、preload 没暴露接口、
@@ -3314,10 +3624,9 @@ ipcMain.handle("notify:show", (_, payload) => {
urgency: p.urgent ? "critical" : "normal",
});
n.on("click", () => {
- if (mainWindow && !mainWindow.isDestroyed()) {
- if (!mainWindow.isVisible()) mainWindow.show();
- mainWindow.focus();
- }
+ // 走 showMainWindow 而非直接 show：它带renderer 健康检查，
+ // 直接 show 在 renderer 已被回收时会开出一个白窗口。
+ showMainWindow();
try {
mainWindow.webContents.send("notify:clicked", { id: id, msgKey: p.msgKey || "" });
} catch (e) {}
diff --git a/cmd/gui/renderer/app.js b/cmd/gui/renderer/app.js
index bf97d7b1..6b0cc5ee 100644
--- a/cmd/gui/renderer/app.js
+++ b/cmd/gui/renderer/app.js
@@ -761,6 +761,29 @@ async function loadDiscoveredGateway() {
(d && d.available && (d.url_portal || d.url)) || "";
if (state.discoveredGateway) {
console.log("[device-bridge] discovered gateway: " + state.discoveredGateway);
+ // ★ 回写到主进程，让设备桥**真的**用上发现结果。
+ //
+ // 此前发现只停在state.discoveredGateway（UI 展示用），而主进程的
+ // startDeviceBridge 读的是 gui-prefs.deviceBridge.gateway ——
+ // 两者从不联通。症状：GUI 面板里能看到设备通道地址，但设备桥连不上，
+ // 而日志只有一行 ws cookie len=0，没有任何“地址来自发现”的痕迹。
+ //
+ // 仅当本地未配置 gateway 时才写：手填的值优先（用户可能故意指向
+ // 内网直连或灰度实例），发现只做**缺省补全**。
+ if (window.homeagent && window.homeagent.deviceBridge) {
+ try {
+ var cur = await window.homeagent.deviceBridge.get();
+ if (cur && !cur.gateway && state.discoveredGateway) {
+ await window.homeagent.deviceBridge.set({ gateway: state.discoveredGateway });
+ console.log(
+ "[device-bridge] gateway auto-configured from discovery: " +
+ state.discoveredGateway,
+ );
+ }
+ } catch (e2) {
+ console.log("[device-bridge] auto-config skipped: " + e2.message);
+ }
+ }
}
} catch (e) {
state.discoveredGateway = "";
@@ -1850,7 +1873,7 @@ function buildChatLayout() {
'
' +
__("星图", "Star Map") +
"
" +
- '
';
+ '
' +
__("终端", "Terminal") +
@@ -3043,12 +3066,98 @@ function initChatStarmap() {
starmapAnimate();
}
-function buildChatStarmapGraph() {
- starmapNodeMeshes.forEach((m) => {
- starmapScene.remove(m);
+// ★ 几何体/材质共享（2026-10-05 修星图内存暴涨）
+//
+// 原实现每个节点都`new THREE.SphereGeometry(gr, 16, 12)`——因为半径
+// gr 各不相同，看起来「只能各自 new」。但 three.js 里几何体的大小应当由
+// **mesh.scale** 表达，几何体本身应当共享。
+//
+// 实测（CDP 抓生产实例，2588 个节点）：
+//
+// Mesh/SphereGeometry 2588 个 geometry 数据合计 22.67MB
+// Sprite/BufferGeometry 1294 个（label 纹理，每个 256×64 RGBA ≈ 64KB）
+//
+// 两者都不释放：buildChatStarmapGraph 只starmapScene.remove(m)，
+// **从不 dispose()** —— remove 只把对象从场景树摘下来，WebGL 侧资源
+// （buffer/texture）仍被引用，不释放。星图每次全量重建泄漏一整轮，
+// 于是进程常驻内存反复冲上GB 级、靠 GC 回收后再度暴涨，界面随之卡住。
+//
+// 修法两条：单位球共享（几何体从 2588 份降到 1 份）+ 重建时 dispose。
+// 单位球细节：SphereGeometry(1, 16, 12) 建一次，实例按 gr 缩放，
+// 因为 mesh 是父节点，缩放会叠加到子 glow 上—— 所以 glow 挂到 mesh 下时
+// 要用 gr/rad 的相对比例。
+// ★ 单位球几何体的**半径取0.5**，不是 1。
+//
+// 原因：节点缩放基准是 mesh.userData.baseScale = rad / 0.5 ——
+// 分母0.5 就是原SphereGeometry 的半径。若把共享球改成半径 1，
+// baseScale 会整体缩放一倍（大的节点变得更大、小的更小），且与
+// 脉冲结束时的复原逻辑（setScalar(baseScale)）不自洽。
+// 保持 0.5 ⇒ baseScale 公式原样成立，行为与修复前逐像素一致。
+var starmapUnitSphere = null;
+function starmapSphereGeometry() {
+ if (!starmapUnitSphere) starmapUnitSphere = new THREE.SphereGeometry(0.5, 16, 12);
+ return starmapUnitSphere;
+}
+
+// 释放一个 three.js 子树占用的 GPU 资源（geometry / material / texture）。
+//
+// 递归处理子树：节点 mesh 下挂着 glow sphere（子 mesh）与 label sprite，
+// 只 dispose 顶层会漏掉子节点的资源。
+//
+// 共享资源要防误 dispose：starmapUnitSphere 被全场景共用，
+// dispose 掉它会让仍在渲染的 mesh 变黑/报错 —— 用 seen 集合兜底。
+function disposeStarmapObject(root) {
+ var seenGeo = new Set();
+ var seenMat = new Set();
+ var seenTex = new Set();
+ if (starmapScene) starmapScene.remove(root);
+ root.traverse(function (o) {
+ var g = o.geometry;
+ if (g && g.dispose && !seenGeo.has(g) && g !== starmapUnitSphere) {
+ seenGeo.add(g);
+ g.dispose();
+ }
+ var m = o.material;
+ if (!m) return;
+ var mats = Array.isArray(m) ? m : [m];
+ mats.forEach(function (mm) {
+ if (!mm || seenMat.has(mm)) return;
+ seenMat.add(mm);
+ // 纹理在 material.map / 上多通道贴图上。
+ Object.keys(mm).forEach(function (k) {
+ var v = mm[k];
+ if (v && v.isTexture && !seenTex.has(v)) {
+ seenTex.add(v);
+ v.dispose();
+ }
+ });
+ if (mm.dispose) mm.dispose();
+ });
});
- starmapEdgeLines.forEach((l) => {
- starmapScene.remove(l);
+ if (root.geometry && root.geometry.dispose &&
+ root.geometry !== starmapUnitSphere && !seenGeo.has(root.geometry)) {
+ root.geometry.dispose();
+ }
+ var rm = root.material;
+ if (rm && !Array.isArray(rm) && !seenMat.has(rm)) {
+ Object.keys(rm).forEach(function (k) {
+ var v = rm[k];
+ if (v && v.isTexture && !seenTex.has(v)) v.dispose();
+ });
+ if (rm.dispose) rm.dispose();
+ }
+}
+
+function buildChatStarmapGraph() {
+ // ★ 先释放上一轮的 GPU 资源，再重建（2026-10-05 修内存暴涨）。
+ //
+ // 原实现只 remove 不 dispose。remove 只改场景树，geometry/material/texture
+ // 仍占着 WebGL 资源；节点数还会随记忆增长，于是泄漏只增不减。
+ starmapNodeMeshes.forEach(function (m) {
+ disposeStarmapObject(m);
+ });
+ starmapEdgeLines.forEach(function (l) {
+ disposeStarmapObject(l);
});
starmapNodeMeshes = [];
starmapEdgeLines = [];
@@ -3184,7 +3293,7 @@ function buildChatStarmapGraph() {
var rad = 0.5 + mnr * 2.0;
var col = smTypeColors[n.type] || 0xcccccc;
var ei = 0.3 + mnr * 0.7;
- var g = new THREE.SphereGeometry(rad, 16, 12);
+ var g = starmapSphereGeometry();
var mat = new THREE.MeshPhongMaterial({
color: col,
emissive: col,
@@ -3200,8 +3309,12 @@ function buildChatStarmapGraph() {
// 缩放后」的值，而不是 set(1,1,1)—— 那会把大节点缩成最小尺寸。
mesh.userData.baseScale = rad / 0.5;
// Glow sphere
+ // Glow sphere —— 共享单位球，靠 scale 表达半径（详见 starmapSphereGeometry）。
var gr = rad * 1.2 + mnr * 0.5;
- var gg = new THREE.SphereGeometry(gr, 16, 12);
+ // mesh 已按 rad/baseScale 缩放过（baseScale = rad/0.5），故 glow 用
+ // 相对比例：世界半径 gr = mesh 缩放 × 本地 scale。
+ var parentScale = mesh.scale.x || 1;
+ var gg = starmapSphereGeometry();
var gm = new THREE.MeshBasicMaterial({
color: col,
transparent: true,
@@ -3210,6 +3323,8 @@ function buildChatStarmapGraph() {
blending: THREE.AdditiveBlending,
});
var gs = new THREE.Mesh(gg, gm);
+ // 共享球半径 0.5，故要 ×2 才是单位半径的相对值。
+ gs.scale.setScalar((gr / parentScale) * 2);
mesh.add(gs);
mesh.userData.glowSphere = gs;
// Label sprite
diff --git a/cmd/gui/starmap-gpu-lifecycle.test.mjs b/cmd/gui/starmap-gpu-lifecycle.test.mjs
new file mode 100644
index 00000000..8da0e973
--- /dev/null
+++ b/cmd/gui/starmap-gpu-lifecycle.test.mjs
@@ -0,0 +1,213 @@
+// 星图 GPU 资源生命周期判据（2026-10-05）。
+//
+// ## 要判的是什么
+//
+// 实测故障：聊天页长时间挂着之后 GUI 卡死。CDP 抓生产实例（2588 节点）：
+//
+// Mesh/SphereGeometry 2588 个 geometry 数据合计 22.67MB
+// Sprite/BufferGeometry 1294 个 label 纹理，256×64 RGBA ≈ 64KB/个
+//
+// 进程常驻内存反复冲上 GB 级、被 GC 拉回后又再度暴涨，界面随之卡住。
+//
+// 两个叠加缺陷：
+//
+// 1. **几何体从不共享**。每个节点都 new THREE.SphereGeometry(r, 16, 12)
+// —— 因为半径各异，看起来「只能各自 new」。但 three.js 里大小应由
+// mesh.scale 表达，几何体应共享。2588 份独立几何体数据。
+//
+// 2. **重建时不 dispose**。buildChatStarmapGraph 只 starmapScene.remove(m)，
+// 从不 dispose()。remove 只改场景树，geometry/material/texture 仍占着
+// WebGL 资源。星图每次全量重建泄漏一整轮，节点数还随记忆增长 ——
+// 泄漏只增不减。全代码搜不到 dispose() 就是铁证。
+//
+// ## 为什么用文本扫描
+//
+// 真跑需要在 CDP 里连生产后端抓 renderer.info.memory.geometries，
+// 依赖 driver/GL 与网络，CI 不可靠。判据钉「该有的共享与释放是否在位」。
+//
+// 运行：node starmap-gpu-lifecycle.test.mjs
+
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const APP = join(here, "renderer", "app.js");
+
+let failures = 0;
+const check = (name, ok, detail) => {
+ if (ok) {
+ console.log(` ✓ ${name}`);
+ } else {
+ failures++;
+ console.log(` ✗ ${name}${detail ? " — " + detail : ""}`);
+ }
+};
+
+if (!existsSync(APP)) {
+ console.error(`找不到 ${APP}`);
+ process.exit(1);
+}
+const src = readFileSync(APP, "utf8");
+
+// 从函数声明扫到列0 的 }（嵌套闭合都有缩进）。
+function sliceFunction(name) {
+ const start = src.indexOf(`function ${name}(`);
+ if (start < 0) return null;
+ const lines = src.slice(start).split("\n");
+ const out = [lines[0]];
+ for (let i = 1; i < lines.length; i++) {
+ out.push(lines[i]);
+ if (lines[i] === "}") return out.join("\n");
+ }
+ return out.join("\n");
+}
+
+// ── 1) 球体几何体必须共享 ───────────────────────────────────────────
+//
+// 判据要盯的是「循环体内不再 new SphereGeometry(...)」——
+// 只看文件里有没有 SphereGeometry 会被starmapSphereGeometry 里的
+// 那一次正当构造骗过去。
+
+const build = sliceFunction("buildChatStarmapGraph");
+check(
+ "能抽到 buildChatStarmapGraph",
+ !!build,
+ "找不到该函数 —— 正则可能已与 app.js 漂移",
+);
+
+// 共享几何体入口：建一次、缓存、复用。
+const shared = sliceFunction("starmapSphereGeometry");
+check(
+ "存在共享球体几何体入口",
+ !!shared && /SphereGeometry/.test(shared) && /starmapUnitSphere/.test(shared),
+ "没有共享几何体入口 —— 每节点一份 SphereGeometry，2588 节点即 2588 份",
+);
+
+if (build) {
+ check(
+ "节点循环用共享几何体",
+ /starmapSphereGeometry\(\)/.test(build) &&
+ !/new THREE\.SphereGeometry\(\s*rad/.test(build),
+ "buildChatStarmapGraph 里仍在 new SphereGeometry(rad, ...) —— 未共享",
+ );
+ check(
+ "光晕球也用共享几何体",
+ !/new THREE\.SphereGeometry\(\s*gr/.test(build),
+ "光晕球仍各自 new SphereGeometry(gr, ...) —— 1294 份未共享",
+ );
+
+ // 共享球的半径必须仍是 0.5：节点缩放基准 baseScale = rad / 0.5
+ // 的分母就是它，改成 1 会让所有节点缩放翻倍。
+ const r05 = shared && /SphereGeometry\(\s*0\.5\s*,/.test(shared);
+ const baseScale05 = build && /baseScale\s*=\s*rad\s*\/\s*0\.5/.test(build);
+ check(
+ "共享球半径与 baseScale 基准一致（0.5）",
+ r05 && baseScale05,
+ r05
+ ? "baseScale 公式不是 rad/0.5 —— 两边不自洽，节点大小会错"
+ : "共享球半径不是 0.5 —— baseScale=rad/0.5 会让所有节点缩放翻倍",
+ );
+
+ // ── 2) 重建必须 dispose ──────────────────────────────────────────
+ //
+ // 只 remove 不 dispose 是泄漏的根。判据要求 remove 旁边有 dispose。
+ //
+ // ★ 先剥注释再匹配：函数上方的说明块里也写着
+ // `starmapNodeMeshes.forEach` 与 `disposeStarmapObject`（用于描述原
+ // 实现的缺陷），裸正则会从注释开始匹配、在 200 字窗口内撞上别处的
+ // disposeStarmapObject 而误判为绿。
+ const buildCode = build
+ .split("\n")
+ .filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l))
+ .join("\n");
+
+ //
+ //
+ // 窗口必须**小于**「节点 forEach 结束」到「边的 disposeStarmapObject(l)」
+ // 之间的距离。实测距离 84 字符（变异后）：
+ // starmapNodeMeshes.forEach(function (m) {\n starmapScene.remove(m);\n });\n
+ // starmapEdgeLines.forEach(function (l) {\n disposeStarmapObject(l);
+ // 窗口开到 120/200 时，节点那处换成 remove 之后，**边**的 dispose 仍在
+ // 窗口内 ⇒ 误判为绿（实测踩过两次）。
+ // 取 40：足够跨过 forEach 的函数头，又够不到下一个 forEach。
+ const NODE_WINDOW = 40;
+ check(
+ "重建时释放旧节点资源",
+ new RegExp(
+ `starmapNodeMeshes\\.forEach[\\s\\S]{0,${NODE_WINDOW}}?disposeStarmapObject\\s*\\(`,
+ ).test(buildCode),
+ "starmapNodeMeshes.forEach 里只有 remove —— GPU 资源不释放，每次重建泄漏一轮",
+ );
+ check(
+ "重建时释放旧边资源",
+ /starmapEdgeLines\.forEach[\s\S]{0,120}?disposeStarmapObject\s*\(/.test(buildCode),
+ "starmapEdgeLines 同样需要 dispose",
+ );
+}
+
+// ── 3) dispose 必须递归到子节点 ─────────────────────────────────────
+//
+// 节点 mesh 下挂着 glow sphere（子 mesh）与 label sprite，
+// 只 dispose 顶层会漏掉子节点的 geometry/material/texture。
+
+const disposeFn = sliceFunction("disposeStarmapObject");
+check(
+ "存在 disposeStarmapObject",
+ !!disposeFn,
+ "找不到释放函数",
+);
+check(
+ "递归遍历子树",
+ disposeFn ? /traverse\(/.test(disposeFn) : false,
+ "没有 traverse —— 子节点（glow sphere / label sprite）资源会漏",
+);
+check(
+ "释放纹理",
+ disposeFn ? /isTexture/.test(disposeFn) && /\.dispose\(\)/.test(disposeFn) : false,
+ disposeFn ? "没有释放 texture（label 纹理 1294 个 × 64KB）" : "",
+);
+check(
+ "共享几何体不被误 dispose",
+ disposeFn ? /starmapUnitSphere/.test(disposeFn) : false,
+ disposeFn
+ ? "没有排除共享几何体 —— 释放后仍在渲染的 mesh 会变黑或报错"
+ : "",
+);
+
+// ── 4) label 纹理数量应有上限感知的注释 ─────────────────────────────
+//
+// label 是 CanvasTexture，节点越多纹理越多；与节点同阶增长，
+// 这次不单独限流（共享/释放已解决主要泄漏），但要留下判据位置，
+// 避免将来有人再加节点类型时无人察觉。
+
+check(
+ "label 纹理有 dispose 覆盖",
+ /new THREE\.CanvasTexture/.test(src) && !!disposeFn,
+ "存在 CanvasTexture 但无释放路径",
+);
+
+// ── 汇总 ────────────────────────────────────────────────────────────
+
+console.log("");
+// 计数要排除注释：本文件在 starmapSphereGeometry 上方有一段注释
+// 引用了 `new THREE.SphereGeometry(gr, 16, 12)` 来描述**原**实现，
+// 裸grep 会把它算进去，显示 2 次而真实只有 1 次 —— 一个会误导人的摘要
+// 比没有摘要更糟。
+const codeOnly = src
+ .split("\n")
+ .filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l))
+ .join("\n");
+const nSphere = (codeOnly.match(/new THREE\.SphereGeometry/g) || []).length;
+console.log(` 代码中 new SphereGeometry ${nSphere} 次（应为 1：共享入口那一次；注释里的引用已排除）`);
+check(
+ "代码里只有一处 SphereGeometry 构造",
+ nSphere === 1,
+ `代码中出现 ${nSphere} 处 —— 某处又各自 new 了几何体`,
+);
+console.log("");
+if (failures > 0) {
+ console.log(`失败 ${failures} 条`);
+ process.exit(1);
+}
+console.log("全部通过");
\ No newline at end of file
diff --git a/cmd/gui/window-liveness.test.mjs b/cmd/gui/window-liveness.test.mjs
new file mode 100644
index 00000000..ef54fdf3
--- /dev/null
+++ b/cmd/gui/window-liveness.test.mjs
@@ -0,0 +1,192 @@
+// 窗口/renderer 存活性的行为判据（2026-10-05）。
+//
+// ## 要判的是什么
+//
+// 实测故障：GUI 在后台挂很久（数小时）后，从托盘打开是**白屏**，
+// 且不会自愈 —— 重启进程才恢复。
+//
+// 原因链（三个洞叠加）：
+//
+// 1. **没有任何崩溃监听**。全代码搜不到 render-process-gone /
+// unresponsive / child-process-gone。renderer 被 Chromium 回收
+// （GPU context lost，或渲染进程被判hung 杀掉）后，没有任何代码
+// 感知这件事。
+//
+// 2. **窗口「可见」不等于「有内容」**。renderer 挂掉后窗口句柄还在、
+// isVisible() 仍返回 true —— 而 showMainWindow() 原来只判
+// `if (!isVisible()) show()`，于是 show() 被跳过，从托盘打开就是白的。
+//
+// 3. **ready-to-show 用了 once**。once 只等第一次首帧；窗口被系统回收后
+// 重建、或 GPU 重启后重新 load，那些路径都需要再show 一次，
+// once 让它们静默失败。
+//
+// 仓库历史上有过「白屏修复(惰性Tray)」提交，但那只修了**首次**显示
+// 时机，没管**长期后台后**。本判据盯后者。
+//
+// ## 为什么用文本扫描而非真跑
+//
+// 复现需要「挂后台数小时 + renderer 被回收」，构造那个时序要真Electron
+// 且依赖驱动行为，CI 里不可靠。故从源码判「该有的监听与判据是否在位」——
+// 与 endpoint-align / device-bridge-liveness 同路子。真正需要证明
+// 「重载后能出内容」时，靠 device-bridge-liveness 那类跑真实函数的判据。
+//
+// 运行：node window-liveness.test.mjs
+
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MAIN = join(here, "main.js");
+
+let failures = 0;
+const check = (name, ok, detail) => {
+ if (ok) {
+ console.log(` ✓ ${name}`);
+ } else {
+ failures++;
+ console.log(` ✗ ${name}${detail ? " — " + detail : ""}`);
+ }
+};
+
+if (!existsSync(MAIN)) {
+ console.error(`找不到 main.js：${MAIN}`);
+ process.exit(1);
+}
+const src = readFileSync(MAIN, "utf8");
+
+// ── 1) renderer 崩溃监听必须存在 ───────────────────────────────────
+//
+// 没有它 ⇒ renderer 挂掉全程无感知，窗口留在白屏态。
+
+check(
+ "监听 render-process-gone",
+ /webContents\.on\(\s*["']render-process-gone["']/.test(src),
+ "没有 renderer 崩溃监听 —— 渲染进程挂掉时窗口会永久白屏",
+);
+
+const goneHandler = src.match(
+ /webContents\.on\(\s*["']render-process-gone["'][\s\S]{0,900}?\n {2}\}\);/,
+);
+check(
+ "renderer 崩溃后有恢复动作",
+ goneHandler ? /reload\(\)/.test(goneHandler[0]) : false,
+ goneHandler
+ ? "崩溃分支里没有 reload —— 监听到了也不自愈"
+ : "找不到 render-process-gone 处理块",
+);
+
+// OOM 时必须**不**reload：重建只会立刻再崩一次，反复重启会把机器拖死。
+check(
+ "OOM 崩溃不自动重载",
+ goneHandler ? /oom/.test(goneHandler[0]) : false,
+ "未区分 reason==='oom' —— 内存不足时反复 reload 会打爆机器",
+);
+
+// ── 2) GPU 崩溃监听 ────────────────────────────────────────────────
+//
+// 无边框窗口（frame:false）在 GPU 进程重启后，常见「停在上一帧不动」
+// 或整片白 —— 与 renderer 崩溃是不同现象，但表现重合。
+
+check(
+ "监听 child-process-gone 且覆盖 GPU",
+ /app\.on\(\s*["']child-process-gone["']/.test(src) &&
+ /type\s*!==\s*["']GPU["']\s*\)?\s*return/.test(src),
+ "没有 GPU 崩溃恢复 —— 无边框窗口在 GPU 重启后可能停在空白帧",
+);
+
+// ── 3) 显示路径必须查 renderer 健康 ───────────────────────────────
+//
+// 这是「白屏」被直接看见的地方：只判 isVisible() 会跳过 show()。
+
+// showMainWindow 的源码切片。
+//
+// ★ 不用 /function showMainWindow\(\)[\s\S]*?\n}\n/ —— 函数体内有多处
+// 嵌套闭合（try/catch/if），非贪婪匹配会在中途的 `\n}\n` 就停，
+// 切片里根本不含函数尾部那几行。实测：删掉 isCrashed 判定后，
+// 「showMainWindow 检查 isCrashed」仍显示绿 —— 切片里还有别的
+// isCrashed 残留，而真正的判定已在切片外。
+// 改为：从函数声明行扫到**列 0** 的 `}`（顶层函数结束）。
+function sliceFunction(name) {
+ const start = src.indexOf(`function ${name}(`);
+ if (start < 0) return null;
+ const lines = src.slice(start).split("\n");
+ const out = [lines[0]];
+ for (let i = 1; i < lines.length; i++) {
+ out.push(lines[i]);
+ // 列 0 的右花括号 = 顶层函数体结束（嵌套闭合都有缩进）。
+ if (lines[i] === "}") return out.join("\n");
+ }
+ return out.join("\n");
+}
+
+const showFn = sliceFunction("showMainWindow");
+// 只认**代码里的**判定（if (wc.isCrashed())），不认注释里的说明文字
+// ——注释里同样写着 isCrashed()。
+const hasCrashCheck = showFn ? /if \(\w+\.isCrashed\(\)\)/.test(showFn) : false;
+check(
+ "showMainWindow 检查 isCrashed",
+ hasCrashCheck,
+ showFn
+ ? "没有 isCrashed 判定 —— renderer 已死时仍会跳过 show，开出白窗口"
+ : "找不到 showMainWindow",
+);
+
+// 判据要钉的是「isCrashed 为真时 reload 被调用」。
+// 用 if(...) 紧跟 reload 的短窗匹配，避免 showMainWindow 之外任何
+// reload（render-process-gone 里就有一个）被误当成满足。
+// showMainWindow 现在是**字符串**（sliceFunction 的返回），不是 match 结果。
+// 早期版本这里写的是 showFn[0]，即取首字符 "f" —— 判据永远为红，
+// 而目之所及一切正常。最隐蔽的一类判据 bug：切片方式一换，取值就错。
+const crashReload = showFn
+ // 要求「if (...isCrashed()) {...reload()」的形状：
+ // 注释里也写着 isCrashed()，纯匹配 isCrashed 会命中注释。
+ ? showFn.match(/if \(\w+\.isCrashed\(\)\)\s*\{[\s\S]{0,400}?reload\(\)/)
+ : null;
+check(
+ "isCrashed 为真时重载",
+ !!crashReload,
+ "判定了崩溃但没在同一分支里 reload —— 白屏依旧",
+);
+
+// ── 4) ready-to-show 不能是 once ──────────────────────────────────
+//
+// once 只等第一次首帧；窗口重建 / GPU 重启后的再显示路径全靠它。
+
+check(
+ "ready-to-show 用 on 而非 once",
+ /mainWindow\.on\(\s*["']ready-to-show["']/.test(src) &&
+ !/mainWindow\.once\(\s*["']ready-to-show["']/.test(src),
+ "仍是 once —— 窗口重建 / GPU 重启后再显示会静默失败",
+);
+
+// ── 5) 所有「显示窗口」的入口都应走 showMainWindow ──────────────────
+//
+// 通知点击、托盘菜单若自己调 show()，就绕过了上面的健康检查。
+
+const directShows = [
+ ...src.matchAll(/mainWindow\.show\(\)/g),
+].length;
+const showMainCalls = [...src.matchAll(/showMainWindow\(\)/g)].length;
+check(
+ "无绕过健康检查的直接 show",
+ directShows <= 2, // createWindow 的 ready-to-show + showMainWindow 内部各一处
+ `发现 ${directShows} 处 mainWindow.show()；除 createWindow 与 showMainWindow 自身外，` +
+ "其余入口（如通知点击）应改走 showMainWindow()，否则会开出白窗口",
+);
+check(
+ "通知点击走 showMainWindow",
+ /n\.on\(["']click["'][\s\S]{0,300}?showMainWindow\(\)/.test(src),
+ "通知点击仍直接 show() —— 绕过 renderer 健康检查",
+);
+
+// ── 汇总 ────────────────────────────────────────────────────────────
+
+console.log("");
+console.log(` show() 调用 ${directShows} 处 / showMainWindow() 调用 ${showMainCalls} 处`);
+console.log("");
+if (failures > 0) {
+ console.log(`失败 ${failures} 条`);
+ process.exit(1);
+}
+console.log("全部通过");
\ No newline at end of file
diff --git a/internal/plugins/remotedevice/plugin.go b/internal/plugins/remotedevice/plugin.go
index fe1fc724..8f633c99 100644
--- a/internal/plugins/remotedevice/plugin.go
+++ b/internal/plugins/remotedevice/plugin.go
@@ -309,6 +309,25 @@ func (p *Plugin) handleDevicePush(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusBadRequest, map[string]interface{}{"error": "device_id required"})
return
}
+ // ★ payload 必须校验，不能让它静默通过（2026-10-05 实测踩坑）。
+ //
+ // 本端点收的是**已成型的协议帧**（{"op":"cmd",...} 等），不是
+ // “device_id + command” 这种便捷参数。以前直接PushJSON(req.Payload)，
+ // 而 PushJSON 只是把 map 序列化后写进 socket —— 于是：
+ //
+ // 客户端发 {"device_id":"gui-JianF","command":"homeagent-clipboardsee"}
+ // → command 字段被**静默丢弃**，payload 为 nil
+ // → 设备收到 {"payload":null}，op 为空，直接忽略
+ // → 而服务端这边 PushJSON 写入 socket 成功，返回 {"status":"ok"}
+ //
+ // 一次「什么也没发生」的操作，报文上是彻底的成功。排查时只能靠设备侧
+ // 日志才发现「命令没到」，极易误判成链路/鉴权/心跳问题（本次就绕了很久）。
+ if req.Payload == nil {
+ writeJSON(w, http.StatusBadRequest, map[string]interface{}{
+ "error": "payload required: 期望 {\"device_id\":\"\",\"payload\":{\"op\":\"cmd\",\"req_id\":\"\",\"cmd_type\":\"shell|homeagent\",\"command\":\"...\"}}；payload 是**协议帧本身**，不是 command 简写",
+ })
+ return
+ }
if err := p.registry.PushJSON(req.DeviceID, req.Payload); err != nil {
writeJSON(w, http.StatusNotFound, map[string]interface{}{"error": err.Error()})
return
diff --git a/internal/plugins/remotedevice/push_validation_test.go b/internal/plugins/remotedevice/push_validation_test.go
new file mode 100644
index 00000000..eb81c6f1
--- /dev/null
+++ b/internal/plugins/remotedevice/push_validation_test.go
@@ -0,0 +1,89 @@
+package remotedevice
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+// TestHandleDevicePushRequiresPayload 钉住「payload 缺失必须报错」。
+//
+// 背景（2026-10-05 实测）：本端点此前不校验 payload，于是
+//
+// POST {"device_id":"gui-JianF","command":"homeagent-clipboardsee"}
+// → command 字段被静默丢弃，payload 为 nil
+// → 设备收到 {"payload":null}，op 为空，直接忽略
+// → 服务端 PushJSON 写入 socket 成功，返回 200 {"status":"ok"}
+//
+// 一次「什么也没发生」的操作在报文上是彻底的成功：排查时只能靠设备侧
+// 日志才发现命令没到，极易误判成链路/鉴权/心跳问题。
+//
+// 本测试不依赖真设备：只验校验分支，且明确断言「非法请求不得返回 ok」。
+func TestHandleDevicePushRequiresPayload(t *testing.T) {
+ p := &Plugin{}
+ p.registry = NewRegistry()
+
+ cases := []struct {
+ name string
+ body string
+ wantCode int
+ wantOK bool // 响应里是否出现 "ok"
+ wantErr string // 期望出现在 error 里的关键词（空=默认 "payload"）
+ }{
+ {
+ name: "缺 payload（把 command 写在顶层，是最常见的误解）",
+ body: `{"device_id":"gui-JianF","command":"homeagent-clipboardsee"}`,
+ wantCode: http.StatusBadRequest,
+ wantOK: false,
+ },
+ {
+ name: "payload 为 null",
+ body: `{"device_id":"gui-JianF","payload":null}`,
+ wantCode: http.StatusBadRequest,
+ wantOK: false,
+ },
+ {
+ // device_id 先于 payload 校验（更基础的参数先报错），
+ // 所以此例报的是 device_id 缺失——行为正确，只是错因不同。
+ name: "既缺 device_id 又缺 payload：先报 device_id",
+ body: `{"command":"homeagent-clipboardsee"}`,
+ wantCode: http.StatusBadRequest,
+ wantOK: false,
+ wantErr: "device_id",
+ },
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ w := httptest.NewRecorder()
+ r := httptest.NewRequest(http.MethodPost, "/api/v1/device/push", strings.NewReader(tc.body))
+ p.handleDevicePush(w, r)
+
+ if w.Code != tc.wantCode {
+ t.Fatalf("状态码 = %d，期望 %d（body=%s）", w.Code, tc.wantCode, w.Body.String())
+ }
+ // 关键断言：绝不能报成功。上一版就是这里返回了 {"status":"ok"}。
+ if tc.wantOK == false && strings.Contains(w.Body.String(), `"ok"`) {
+ t.Fatalf("非法请求返回了成功：%s", w.Body.String())
+ }
+ var got map[string]interface{}
+ if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+ t.Fatalf("响应不是 JSON：%s", w.Body.String())
+ }
+ msg, _ := got["error"].(string)
+ if msg == "" {
+ t.Fatalf("400 响应里没有 error 字段：%s", w.Body.String())
+ }
+ // 报错文案要能自解释：使用者多半是把 command 写在了顶层。
+ want := tc.wantErr
+ if want == "" {
+ want = "payload"
+ }
+ if !strings.Contains(msg, want) {
+ t.Fatalf("报错未提及 %q，实际：%s", want, msg)
+ }
+ })
+ }
+}