From 2bbbb6b830dd5e1b12a4d7c6a506208380f334d4 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 29 Jul 2026 15:31:09 +0800 Subject: [PATCH 01/13] gitignore: exclude third_party/homeagent-sdk/example/ from core repo From bca791a14b3137f816546a252e08827ccdbc19fa Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Mon, 5 Oct 2026 13:05:18 +0800 Subject: [PATCH 02/13] =?UTF-8?q?fix(gui):=20=E8=AE=BE=E5=A4=87=E6=A1=A5?= =?UTF-8?q?=20gateway=20=E8=87=AA=E5=8A=A8=E5=8F=91=E7=8E=B0=E5=9B=9E?= =?UTF-8?q?=E5=86=99=E4=B8=BB=E8=BF=9B=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 要判的是什么 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、不重试。 ## 修复 发现成功后回写 deviceBridge.set({gateway})，让主进程真正用上。 两个刻意的约束： 1. **仅当本地 gateway 为空才写**（!cur.gateway）—— 手填值优先。 用户可能故意指向内网直连或灰度实例，发现只做缺省补全。 2. **只传 gateway，不传 token** —— /device/gateway 不返回设备令牌 （ws_token），写了反而会写坏已有的正确 token。 deviceBridge.set 会 stop+start 桥，改完立即生效，无需重启进程。 ## 顺带记下一个实测坑（已写进门禁） 设备桥 WS 的认证**不走 cookie**。registry.go ServeWS 只认三种来源： ?token= / X-API-Key / Sec-WebSocket-Protocol: homeagent.， cookie 完全不参与 acceptBind。 排查时曾误以为「发 cookie 就能过」—— 实测服务端仍 401。 cookie 那条路是错的，已还原 connections.json。 ## 门禁（cmd/gui/device-gateway-discovery.test.mjs） 9 条判据，文本扫描（自动回写由 refreshAll 的 15s 定时器驱动， 构造那个时序需真 Electron + 真后端 + 会话 cookie，CI 里没有）。 覆盖：发现调用存在、回写接通、本地非空则不覆盖、只传 gateway、 preload 暴露 set、主进程注册 handler、get 返回明文 token、 set 会重启桥、connectDeviceWS 把 token 放进 query。 变异测试验证非假红： - 删掉回写块（复现本次故障形态）⇒ 第 2、3、4 条转红； - 去掉「本地为空才写」改成无条件覆盖 ⇒ 第 3 条转红。 排障过程中判据自身报过 3 次假红（正则窗口不足、字符串切片后仍按 match 数组用 setHandler[0]），均已修正并记在注释里。 --- cmd/gui/device-gateway-discovery.test.mjs | 169 ++++++++++++++++++++++ cmd/gui/renderer/app.js | 23 +++ 2 files changed, 192 insertions(+) create mode 100644 cmd/gui/device-gateway-discovery.test.mjs diff --git a/cmd/gui/device-gateway-discovery.test.mjs b/cmd/gui/device-gateway-discovery.test.mjs new file mode 100644 index 00000000..4240dba5 --- /dev/null +++ b/cmd/gui/device-gateway-discovery.test.mjs @@ -0,0 +1,169 @@ +// 设备桥 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", +); + +// ── 汇总 ──────────────────────────────────────────────────────────── + +console.log(""); +if (failures > 0) { + console.log(`失败 ${failures} 条`); + process.exit(1); +} +console.log("全部通过"); \ No newline at end of file diff --git a/cmd/gui/renderer/app.js b/cmd/gui/renderer/app.js index bf97d7b1..c56a298a 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 = ""; From 3988c19880d20cc6d837adb811fd14a4c2a26f8a Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Mon, 5 Oct 2026 13:45:30 +0800 Subject: [PATCH 03/13] =?UTF-8?q?fix(gui):=20=E8=AE=BE=E5=A4=87=E6=A1=A5?= =?UTF-8?q?=E8=A1=A5=20WebSocket=20keepalive=EF=BC=8C=E4=BF=AE=E3=80=8C?= =?UTF-8?q?=E8=AE=BE=E5=A4=87=E5=8F=AF=E8=A7=81=E4=BD=86=E5=91=BD=E4=BB=A4?= =?UTF-8?q?=E4=B8=8B=E5=8F=91=E4=B8=8D=E5=88=B0=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 实测故障（2026-10-05） 设备能力全部调用失败，但设备**在面板里能看到**。服务端实测： POST /api/v1/device/push {"device_id":"gui-JianF","command":"..."} → {"error":"device gui-JianF not online"} 同一时刻 NAS 上的 waiter 完全正常（last_seen 持续刷新、push 返回 ok）。 ## 根因 GUI **从不发WebSocket ping**。全文件搜不到，是唯一没有 keepalive 的设备端。 链路中间是 frp + TLS 反代，空闲超时（常见 30~60s）会静默关掉连接 —— 没有 close 事件、没有错误日志，只是数据不再流动。 服务端 handleWS 的 defer 于是执行 markOffline(curID) → 从 conns 删除。 于是形成这个割裂状态： · devices 表里有gui-JianF ⇒ webui 面板显示在线 · conns 表里没有 ⇒ PushCmd 报 not online 「可见但不可用」正是这个割裂的表象。registry.go:735 那段 ping/pong 注释修的是「**回** pong 不能因未 bind 而失败」，与「客户端有没有发」 是两个方向的坑 —— 那段代码一直在，却从未被 GUI 用上。 ## 修复 connectDeviceWS 在 opened 后启动 25s 周期的 ping（0x89 控制帧，客户端 必须加掩码）。25s 压在常见 30s 空闲阈值之下。 两条清理路径都 clearInterval：close() 与 sock.on("close")。缺任一条都会 泄漏定时器并向已销毁 socket 写入（进程不退出）。 ## 验证 修复前：gui-JianF 不在 devices 列表，push → not online 修复后：90 秒后仍在列表且 online:true，push → {"status":"ok"} （同一时刻不再掉线，keepalive 生效） 门禁新增 6 条 keepalive 判据（共 15 条）： 存在 sendDevicePing / 0x89 控制帧 / opened 后启动定时器 / 间隔 ≤30s / close 清理 / close 事件清理。 变异测试：删掉 setInterval（复现故障形态）⇒ 定时器与间隔两条转红。 --- cmd/gui/device-gateway-discovery.test.mjs | 58 ++++++++++++++++++++++ cmd/gui/main.js | 59 ++++++++++++++++++++++- 2 files changed, 116 insertions(+), 1 deletion(-) diff --git a/cmd/gui/device-gateway-discovery.test.mjs b/cmd/gui/device-gateway-discovery.test.mjs index 4240dba5..4dae59f3 100644 --- a/cmd/gui/device-gateway-discovery.test.mjs +++ b/cmd/gui/device-gateway-discovery.test.mjs @@ -159,6 +159,64 @@ check( : "找不到 connectDeviceWS", ); +// ── 6) keepalive：设备桥必须有主动 ping ────────────────────────────── +// +// 2026-10-05 实测故障：GUI bind 成功、设备进了 devices 表（面板可见）， +// 但几秒后能力调用全失败： +// POST /api/v1/device/push {"device_id":"gui-JianF"} +// → {"error":"device gui-JianF not online"} +// 同时 waiter/NAS 完全正常（last_seen 持续刷新）。 +// +// 根因：GUI **从不发 ping**。链路是 frp + TLS 反代，空闲超时（30~60s） +// 静默关连接 → 服务端 handleWS 的 defer 走 markOffline → conns 删除 +// ⇒ 「设备可见但命令下发不到」。 +// +// 服务端 registry.go:735 那段 ping/pong 注释修的是「**回** pong 不能因 +// 未bind 而失败」，不是「客户端有没有发」—— 那是另一个方向的坑。 + +const pingFn = mainSrc.match(/function sendDevicePing[\s\S]*?\n}\n/); +check( + "存在 sendDevicePing", + !!pingFn, + "找不到 sendDevicePing —— 设备桥没有 keepalive 能力", +); +check( + "ping 用 WebSocket 控制帧 0x89", + pingFn ? /0x89/.test(pingFn[0]) : false, + pingFn ? "ping 帧构造不对（应为 0x89 = FIN|ping 且置掩码位）" : "", +); + +// ping 必须被定时器驱动，且间隔要压在常见空闲阈值之下。 +const openBlock = mainSrc.slice( + mainSrc.indexOf("opened = true"), + mainSrc.indexOf("opened = true") + 2000, +); +check( + "连接建立后启动 ping 定时器", + /setInterval/.test(openBlock) && /sendDevicePing/.test(openBlock), + "opened 之后没有启动 keepalive 定时器 —— 连接仍会因空闲超时断开", +); +const intervalMatch = openBlock.match(/setInterval\([^,]*,\s*(\d+)\)/); +check( + "keepalive 间隔 ≤ 30s", + intervalMatch ? parseInt(intervalMatch[1], 10) <= 30000 : false, + intervalMatch + ? `间隔 ${intervalMatch[1]}ms 太长，压不住常见 30s 空闲超时` + : "找不到 setInterval 的间隔参数", +); + +// 关闭路径必须清定时器，否则进程不退出 / 往死 socket 写。 +check( + "close 时清理 ping 定时器", + /close:[\s\S]{0,200}?clearInterval/.test(mainSrc), + "close() 里没有 clearInterval —— 定时器泄漏且会向已销毁 socket 写入", +); +check( + "socket close 事件也清理定时器", + /on\("close"[\s\S]{0,300}?clearInterval/.test(mainSrc), + 'sock.on("close") 里没有 clearInterval —— 异常断开后定时器泄漏', +); + // ── 汇总 ──────────────────────────────────────────────────────────── console.log(""); diff --git a/cmd/gui/main.js b/cmd/gui/main.js index 87a4c71e..01604774 100644 --- a/cmd/gui/main.js +++ b/cmd/gui/main.js @@ -1137,10 +1137,26 @@ function connectDeviceWS(url, token, onMsg) { ); } opened = true; + // ★ keepalive：绑定成功后必须周期性发 ping，否则链路空闲超时会 + // 静默断连，导致「设备可见但命令下发不到」（详见 sendDevicePing + // 上方注释）。间隔 25s：压在常见的 30s 空闲阈值之下。 + const pingTimer = setInterval(() => { + try { + sendDevicePing(sock); + } catch (e) { + /* ping 失败不致命，下一轮或 close 事件会处理 */ + } + }, 25000); + sock.__bridgePingTimer = pingTimer; resolve({ send: (obj) => sendDeviceFrame(sock, JSON.stringify(obj)), __sock: sock, // 暴露底层 socket 供二进制分块发送 - close: () => sock.destroy(), + close: () => { + // 关闭前必须清掉 ping，否则定时器会继续往已销毁的 socket 写， + // 抛 unhandled error（且进程不会退出）。 + clearInterval(sock.__bridgePingTimer); + sock.destroy(); + }, }); } while (buf.length >= 2) { @@ -1209,11 +1225,52 @@ function connectDeviceWS(url, token, onMsg) { if (!opened) reject(e); }); sock.on("close", () => { + // 断开时停掉 keepalive，否则定时器会一直持有已死的 socket。 + if (sock.__bridgePingTimer) { + clearInterval(sock.__bridgePingTimer); + sock.__bridgePingTimer = null; + } deviceBridge = null; }); }); } +// 发送 WS ping 控制帧（客户端必须加掩码）。 +// +// ★ 为什么必须主动 ping（2026-10-05 实测故障）： +// +// GUI 的 bind 能成功（日志有 bind_ok），设备也确实进了服务端 devices 表 +// （webui 面板里能看到），但**几秒后所有设备能力调用全部失败**： +// +// POST /api/v1/device/push {"device_id":"gui-JianF",...} +// → {"error":"device gui-JianF not online"} +// +// 而同一时刻 NAS 上的 waiter 完全正常（last_seen 持续刷新）。 +// +// 根因：GUI **没有任何 keepalive**。全文件搜不到发ping 的地方，而 +// waiter / 嵌入式客户端都有。链路中间是 frp + TLS 反代，它们的空闲超 +// 时（常见 30~60s）会静默关掉这条连接。 +// +// 服务端 handleWS 虽有 ping/pong 处理（registry.go:735，且那段注释 +// 记录了「回 pong 不能因未 bind 而失败」的修复），但那解决的是**服务端 +// 回** pong；连接能不能活下去，取决于**客户端有没有主动发**。 +// 连接一断，handleWS 的 defer 走 markOffline(curID) → conns 里删除， +// 于是「设备可见（devices 表）但不可下发（conns 表）」—— +// 正是本故障的表象。 +// +// 对照组说明这不是服务端能力缺失：同一 registry 下waiter 一直好好的。 +const deviceBridgePingTimerKey = "__bridgePingTimer"; + +function sendDevicePing(sock) { + try { + // 控制帧：FIN + opcode 0x9 (ping)，payload 为空；客户端帧必须掩码。 + const mask = crypto.randomBytes(4); + sock.write(Buffer.concat([Buffer.from([0x89, 0x80]), mask])); + } catch (e) { + console.log("[device-bridge] ping failed: " + e.message); + } +} + // 发送 WS text 帧（客户端加掩码） function sendDeviceFrame(sock, text) { const payload = Buffer.from(text, "utf8"); From 85d76ad4959dcaa3f883ebcce85384ddc689a1d2 Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Mon, 5 Oct 2026 14:37:43 +0800 Subject: [PATCH 04/13] =?UTF-8?q?fix(gui):=20=E8=AE=BE=E5=A4=87=E6=A1=A5?= =?UTF-8?q?=E8=A1=A5=E5=BF=83=E8=B7=B3=E4=B8=8E=E6=96=AD=E7=BA=BF=E9=87=8D?= =?UTF-8?q?=E8=BF=9E=EF=BC=8C=E5=85=91=E7=8E=B0=20liveness=20=E9=97=A8?= =?UTF-8?q?=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 背景 `device-bridge-liveness.test.mjs`（判据）已在 main 上，但它要求的实现 一直缺席，跑起来是： Error: cannot find function sendDeviceControlFrame in main.js 判据注释描述了两个洞，合起来的效果是「一次失联，终身失联」： 1. 不发 ping —— waiter 侧有 pingLoop，GUI 侧一次都没发过； 2. 不重连 —— startDeviceBridge 失败就 console.error 结束。 我先前只补了 ping 且命名为 sendDevicePing，判据仍红；本次按判据契约补全。 ## 本次实现 **通用控制帧** `sendDeviceControlFrame(sock, opcode, payload)` 控制帧有 ping(0x9)/pong(0xA)/close(0x8) 三种，签名写死一种就换不来另外两种。 **心跳** 每 30s 一个 0x9 帧（与 waiter 的 pingLoop 对齐）。 起在 doConnectDeviceBridge 而非 connectDeviceWS —— 跟着「一条实际连上的 桥」而不是「某次调用」，后者在重连路径上会漏。 **重连** `scheduleDeviceReconnect`：线性退避 base×n、封顶 60s， 成功即归零（否则「昨天断十次、今天断一次」要等 10×base 才有第一次重试）。 退避先递增后算：head 用 max(1,attempt) 会让 attempt 0 与 1 都算出 base， 出现「退避头两次一样」的假象。 三条排程路径，缺一条就终身失联： - socket close（已连上后被关） - connectDeviceWS reject（**没有** close 事件，最易漏） - deviceWanted闸：用户主动停用后不得再排程，否则把已关的桥偷偷拉起来 ## 顺带修掉的隐性故障 `connectDeviceBridgeOnce` 里 host/cpus/process/app 等推导原先裸调。 它们在 ws.send 的实参里，抛错会被上层 catch 吞成「连接失败」—— 而实际 连接是好的，表现为「反复重连但永远连不上」。现已逐项 try 包裹。 ## 判据分工（避免两个门禁互相打架） 删掉 device-gateway-discovery.test.mjs 里 6 条 keepalive 文本判据 （grep 0x89、找 setInterval 间隔…）。它们只能证明「代码里出现过这些 字符」，证明不了「心跳真发出去了」。liveness 那份用 node:vm 跑真实函数， 是强判据；弱的那份会在实现重构时先红、掩盖真信号。 ## 验证 device-bridge-liveness 14 条全绿（改前是 0 条可跑）。 另外 7 个门禁全绿：device-gateway-discovery / device-align / endpoint-align / connections-io / retry-guard / sse-backoff / package-config。 对齐过程中判据自身报过 3 次假红（process 未注入、doConnectDeviceBridge 无 return、ws 为 undefined），根因都已写进代码注释。 --- cmd/gui/device-gateway-discovery.test.mjs | 64 +--- cmd/gui/main.js | 359 ++++++++++++++++------ 2 files changed, 271 insertions(+), 152 deletions(-) diff --git a/cmd/gui/device-gateway-discovery.test.mjs b/cmd/gui/device-gateway-discovery.test.mjs index 4dae59f3..db6baf6b 100644 --- a/cmd/gui/device-gateway-discovery.test.mjs +++ b/cmd/gui/device-gateway-discovery.test.mjs @@ -159,63 +159,13 @@ check( : "找不到 connectDeviceWS", ); -// ── 6) keepalive：设备桥必须有主动 ping ────────────────────────────── -// -// 2026-10-05 实测故障：GUI bind 成功、设备进了 devices 表（面板可见）， -// 但几秒后能力调用全失败： -// POST /api/v1/device/push {"device_id":"gui-JianF"} -// → {"error":"device gui-JianF not online"} -// 同时 waiter/NAS 完全正常（last_seen 持续刷新）。 -// -// 根因：GUI **从不发 ping**。链路是 frp + TLS 反代，空闲超时（30~60s） -// 静默关连接 → 服务端 handleWS 的 defer 走 markOffline → conns 删除 -// ⇒ 「设备可见但命令下发不到」。 -// -// 服务端 registry.go:735 那段 ping/pong 注释修的是「**回** pong 不能因 -// 未bind 而失败」，不是「客户端有没有发」—— 那是另一个方向的坑。 - -const pingFn = mainSrc.match(/function sendDevicePing[\s\S]*?\n}\n/); -check( - "存在 sendDevicePing", - !!pingFn, - "找不到 sendDevicePing —— 设备桥没有 keepalive 能力", -); -check( - "ping 用 WebSocket 控制帧 0x89", - pingFn ? /0x89/.test(pingFn[0]) : false, - pingFn ? "ping 帧构造不对（应为 0x89 = FIN|ping 且置掩码位）" : "", -); - -// ping 必须被定时器驱动，且间隔要压在常见空闲阈值之下。 -const openBlock = mainSrc.slice( - mainSrc.indexOf("opened = true"), - mainSrc.indexOf("opened = true") + 2000, -); -check( - "连接建立后启动 ping 定时器", - /setInterval/.test(openBlock) && /sendDevicePing/.test(openBlock), - "opened 之后没有启动 keepalive 定时器 —— 连接仍会因空闲超时断开", -); -const intervalMatch = openBlock.match(/setInterval\([^,]*,\s*(\d+)\)/); -check( - "keepalive 间隔 ≤ 30s", - intervalMatch ? parseInt(intervalMatch[1], 10) <= 30000 : false, - intervalMatch - ? `间隔 ${intervalMatch[1]}ms 太长，压不住常见 30s 空闲超时` - : "找不到 setInterval 的间隔参数", -); - -// 关闭路径必须清定时器，否则进程不退出 / 往死 socket 写。 -check( - "close 时清理 ping 定时器", - /close:[\s\S]{0,200}?clearInterval/.test(mainSrc), - "close() 里没有 clearInterval —— 定时器泄漏且会向已销毁 socket 写入", -); -check( - "socket close 事件也清理定时器", - /on\("close"[\s\S]{0,300}?clearInterval/.test(mainSrc), - 'sock.on("close") 里没有 clearInterval —— 异常断开后定时器泄漏', -); +// ★ keepalive 与重连的判据**不在本文件**，在同目录的 +// device-bridge-liveness.test.mjs —— 那份用 node:vm 把真实函数抽出来跑 +// 「连接 → 断线 → 重连 → 再断线」，数真实的 ping 帧与重连次数。 +// 本文件早期版本曾用文本判据盯keepalive（grep 0x89、找 setInterval 的 +// 间隔），已删：它只能证明「代码里出现过这些字符」，证明不了「心跳真的 +// 发出去了」「重连真的发生了」。两份盯同一件事时，弱的那份会在实现重构 +// 时先红，掩盖真信号。 // ── 汇总 ──────────────────────────────────────────────────────────── diff --git a/cmd/gui/main.js b/cmd/gui/main.js index 01604774..7f691f3e 100644 --- a/cmd/gui/main.js +++ b/cmd/gui/main.js @@ -922,6 +922,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,26 +1149,13 @@ function connectDeviceWS(url, token, onMsg) { ); } opened = true; - // ★ keepalive：绑定成功后必须周期性发 ping，否则链路空闲超时会 - // 静默断连，导致「设备可见但命令下发不到」（详见 sendDevicePing - // 上方注释）。间隔 25s：压在常见的 30s 空闲阈值之下。 - const pingTimer = setInterval(() => { - try { - sendDevicePing(sock); - } catch (e) { - /* ping 失败不致命，下一轮或 close 事件会处理 */ - } - }, 25000); - sock.__bridgePingTimer = pingTimer; + // 心跳不在这里起：统一由 connectDeviceBridgeOnce 在拿到 ws.__sock + // 后调 startDevicePing。放这里的话心跳会跟着「每次 connectDeviceWS + // 调用」起，而不是跟着「一条实际连上的桥」起——重连路径上会漏。 resolve({ send: (obj) => sendDeviceFrame(sock, JSON.stringify(obj)), __sock: sock, // 暴露底层 socket 供二进制分块发送 - close: () => { - // 关闭前必须清掉 ping，否则定时器会继续往已销毁的 socket 写， - // 抛 unhandled error（且进程不会退出）。 - clearInterval(sock.__bridgePingTimer); - sock.destroy(); - }, + close: () => sock.destroy(), }); } while (buf.length >= 2) { @@ -1225,50 +1224,241 @@ function connectDeviceWS(url, token, onMsg) { if (!opened) reject(e); }); sock.on("close", () => { - // 断开时停掉 keepalive，否则定时器会一直持有已死的 socket。 - if (sock.__bridgePingTimer) { - clearInterval(sock.__bridgePingTimer); - sock.__bridgePingTimer = null; - } + // 断开时停掉心跳，否则定时器会一直持有已死的 socket。 + stopDevicePing(); deviceBridge = null; + // 已建立过的连接被对端/中间链路关掉 ⇒ 排程重连。 + // scheduleDeviceReconnect 内部有 deviceWanted 闸，用户主动停用 + // 时不会把桥拉起来。 + if (opened) scheduleDeviceReconnect(); }); }); } -// 发送 WS ping 控制帧（客户端必须加掩码）。 +// ============ 设备桥心跳 + 断线重连 ============ // -// ★ 为什么必须主动 ping（2026-10-05 实测故障）： +// ★ 这里修的是 2026-10-05 实测到的两个洞，合起来的效果是 +// 「一次失联，终身失联」： // -// GUI 的 bind 能成功（日志有 bind_ok），设备也确实进了服务端 devices 表 -// （webui 面板里能看到），但**几秒后所有设备能力调用全部失败**： +// 1. **不发 ping**。waiter 侧有 pingLoop（internal/devicebridge/client/ +// bridge.go，每 30s 一个 0x9 帧），GUI 侧全文件一次 ping 都没发过。 +// 而 remotedevice 服务端**没有设备侧读超时**（registry.go 里没有 +// SetReadDeadline）—— 不发心跳就没人能发现设备已死，网关会把一台 +// 半死的设备长期显示为 online。 // -// POST /api/v1/device/push {"device_id":"gui-JianF",...} -// → {"error":"device gui-JianF not online"} +// 实测症状：bind 能成功（bind_ok）、设备进了 devices 表（面板可见）， +// 但几秒后 push 就报 +// {"error":"device gui-JianF not online"} +// —— conns 表已被 defer 里的 markOffline 清空，而 devices 表还在。 +// 「可见但不可下发」就是这个割裂的表象。 // -// 而同一时刻 NAS 上的 waiter 完全正常（last_seen 持续刷新）。 +// 2. **不重连**。原来 startDeviceBridge 只有启动/配置变更两个调用点， +// 失败就 console.error 结束。GUI 是最容易被休眠/切网/服务端重启打断的 +// 形态（合盖一次、WiFi 抖一下、服务端重启），设备桥就再也回不来， +// 直到用户重启 GUI 或手动改一次配置。 // -// 根因：GUI **没有任何 keepalive**。全文件搜不到发ping 的地方，而 -// waiter / 嵌入式客户端都有。链路中间是 frp + TLS 反代，它们的空闲超 -// 时（常见 30~60s）会静默关掉这条连接。 -// -// 服务端 handleWS 虽有 ping/pong 处理（registry.go:735，且那段注释 -// 记录了「回 pong 不能因未 bind 而失败」的修复），但那解决的是**服务端 -// 回** pong；连接能不能活下去，取决于**客户端有没有主动发**。 -// 连接一断，handleWS 的 defer 走 markOffline(curID) → conns 里删除， -// 于是「设备可见（devices 表）但不可下发（conns 表）」—— -// 正是本故障的表象。 -// -// 对照组说明这不是服务端能力缺失：同一 registry 下waiter 一直好好的。 -const deviceBridgePingTimerKey = "__bridgePingTimer"; +// 判据：cmd/gui/device-bridge-liveness.test.mjs（用 node:vm 抽真实函数 +// 在沙箱里跑「连接→ 断线 → 重连 → 再断线」，数真实的 ping 帧与重连次数）。 -function sendDevicePing(sock) { - try { - // 控制帧：FIN + opcode 0x9 (ping)，payload 为空；客户端帧必须掩码。 - const mask = crypto.randomBytes(4); - sock.write(Buffer.concat([Buffer.from([0x89, 0x80]), mask])); - } catch (e) { - console.log("[device-bridge] ping failed: " + e.message); +// 与 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 帧（客户端加掩码） @@ -2899,59 +3089,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(); From 878fd770bc7520f402784b6299c8cc82fff19ad4 Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Mon, 5 Oct 2026 21:18:49 +0800 Subject: [PATCH 05/13] =?UTF-8?q?fix(remotedevice):=20device/push=20?= =?UTF-8?q?=E6=A0=A1=E9=AA=8C=20payload=EF=BC=8C=E6=9D=9C=E7=BB=9D?= =?UTF-8?q?=E3=80=8C=E5=81=87=E6=88=90=E5=8A=9F=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 实测坑（2026-10-05） 排查「设备能力全部调用失败」时发现：POST /api/v1/device/push 返回 `{"status":"ok"}`，设备侧却什么都没发生，日志里连一条 recv 都没有。 根因是**调用方把参数写错了**，而服务端把这个错误藏了起来： {"device_id":"gui-JianF","command":"homeagent-clipboardsee"} → command 字段被静默丢弃（端点只认 payload） → req.Payload 为 nil → PushJSON 序列化后写进 socket，**成功** → 设备收到 {"payload":null}，op 为空，直接忽略 → 服务端返回 200 {"status":"ok"} 一次「什么也没发生」的操作，在报文上是彻底的成功。排查只能靠设备侧 日志发现「命令没到」，极易误判成链路/鉴权/心跳问题—— 本次就先后误 判为「frp 转发丢帧」「命令送达有问题」，绕了很久。 补上 payload 校验，并把正确格式写进报错文案（使用者最可能犯的就是 把 command 写在顶层）。 ## 不动 device_id 的校验顺序 device_id 仍先于 payload 校验：更基础的参数先报错。三条非法输入现在 分别报 device_id 缺失 / payload 缺失 / payload 为 null。 ## 判据 新增 push_validation_test.go，三个 case： - command 写在顶层（最常见的误解） - payload 为 null - 既缺 device_id 又缺 payload（断言先报 device_id） 关键断言是「非法请求绝不返回 ok」—— 正是上一版的漏洞。 ## 验证 - go test -run TestHandleDevicePushRequiresPayload ⇒ 3/3 PASS - gofmt 干净 ⚠ 本包的 go test ./... 跑不通：clipboardsue_content_test.go 引用了只在 GUI 侧定义的 clipboardsueMaxBytes（来自远端 7901651「根目录清理」）， 编译失败。已确认与本次改动无关，未动该文件；上面那条是用 -run 精确跑通的。 --- internal/plugins/remotedevice/plugin.go | 19 ++++ .../remotedevice/push_validation_test.go | 89 +++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 internal/plugins/remotedevice/push_validation_test.go diff --git a/internal/plugins/remotedevice/plugin.go b/internal/plugins/remotedevice/plugin.go index 2501ea46..3b77cfc4 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) + } + }) + } +} From 7bd569eccd8bf7bf64a64da9c6a5f7f3df723b1e Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Mon, 5 Oct 2026 21:56:14 +0800 Subject: [PATCH 06/13] =?UTF-8?q?fix(gui):=20=E4=BF=AE=E3=80=8C=E9=95=BF?= =?UTF-8?q?=E6=97=B6=E9=97=B4=E6=8C=82=E5=90=8E=E5=8F=B0=E5=90=8E=E6=89=93?= =?UTF-8?q?=E5=BC=80=E7=99=BD=E5=B1=8F=E3=80=8D=E2=80=94=E2=80=94=20?= =?UTF-8?q?=E8=A1=A5=20renderer/GPU=20=E5=B4=A9=E6=BA=83=E8=87=AA=E6=84=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 实测故障 GUI 在后台挂很久（数小时）后，从托盘打开是**白屏**，且不会自愈 —— 重启进程才恢复。 本机现场证据：GPU 进程启动于 20:27:56，而主进程是 16:03:29 —— GPU 进程在主进程运行 4 小时后重启过一次，正是长时间后台后 GPU context 被回收的实证。 ## 原因链（三个洞叠加） 1. **没有任何崩溃监听**。全代码搜不到 render-process-gone / unresponsive / child-process-gone。renderer 被回收后全程无感知。 2. **窗口「可见」不等于「有内容」**。renderer 挂掉后窗口句柄仍在、 isVisible() 返回 true，而 showMainWindow() 只判 `if (!isVisible()) show()` ⇒ show() 被跳过 ⇒ 托盘点一下开出白窗口， 永远不会好。 3. **ready-to-show 用了 once**。once 只等第一次首帧；窗口被系统回收后 重建、或 GPU 重启后重新 load，那些路径都需要再 show 一次， once 让它们静默失败。 仓库历史上有过「白屏修复(惰性Tray)」提交，但那只修了**首次**显示时机， 没管**长期后台后**。 ## 修复 - render-process-gone → reload 自愈；reason==='oom' 时**不** reload （内存不足时反复重载只会立刻再崩一次，把机器拖死） - child-process-gone 且 type==='GPU' → reload 渲染进程 （无边框窗口在GPU 重启后常停在上一帧/全白，与 renderer 崩溃表现重合 但成因不同；不重建窗口，避免丢窗口位置与尺寸） - showMainWindow() 加 webContents.isCrashed() 判定，为真则先 reload - ready-to-show: once → on - 通知点击路径改走 showMainWindow()，不再自己调 show() （原来的直接 show() 绕过健康检查，同样能开出白窗口） ## 判据（cmd/gui/window-liveness.test.mjs） 9 条，文本扫描（复现需「挂后台数小时 + renderer 被回收」，依赖驱动行为， CI 不可靠）。覆盖：render-process-gone 监听、崩溃后有 reload、 OOM 不重载、GPU 崩溃监听、isCrashed 判定、判定后重载、 ready-to-show 用 on、无绕过健康检查的直接 show、通知点击走 showMainWindow。 变异测试验证非假红：删掉 isCrashed 分支 ⇒ 对应两条转红。 排障中判据自身报过 2 次假红，根因都写进注释： - sliceFunction 从 match 结果换成字符串后，残留的 showFn[0] 取到首字符 - 注释里也写着 isCrashed()，纯字符串匹配命中注释而非代码 --- cmd/gui/main.js | 105 +++++++++++++++-- cmd/gui/window-liveness.test.mjs | 192 +++++++++++++++++++++++++++++++ 2 files changed, 286 insertions(+), 11 deletions(-) create mode 100644 cmd/gui/window-liveness.test.mjs diff --git a/cmd/gui/main.js b/cmd/gui/main.js index 7f691f3e..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(); } @@ -3377,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) { @@ -3508,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 没暴露接口、 @@ -3540,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/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 From a02d8b00a5886c60d9b70ba6e1ff078ca3b74e00 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 6 Oct 2026 09:07:18 +0800 Subject: [PATCH 07/13] =?UTF-8?q?feat(multimodal):=20=E5=A4=9A=E6=A8=A1?= =?UTF-8?q?=E6=80=81=E5=B7=A5=E5=85=B7=E7=A7=BB=E5=87=BA=E5=86=85=E6=A0=B8?= =?UTF-8?q?=E4=B8=BA=E5=86=85=E7=BD=AE=E6=8F=92=E4=BB=B6=20+=20get=5Fplugi?= =?UTF-8?q?n=5Ftools=20=E6=94=B6=E7=BC=96=E4=B8=BA=E5=86=85=E6=A0=B8?= =?UTF-8?q?=E6=9C=8D=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 背景 README 第一原则：「内核职责限定在 LLM 编排、记忆管理与知识检索； 所有 IO 能力由插件实现」，而「文件读取」正在 IO 列表里。 describe_image / ocr_image / transcribe_audio 读本地文件却住在内核进程内 ——无沙箱、无能力面、无审计，正是 capability.go 那套权限梯度要防的事。 ## 本次改动 ### 1. 多模态工具移出内核（internal/plugins/multimodal） - 新增内置插件，注册 describe_image / transcribe_audio / ocr_image - 媒体来源支持 path（设备/工具回传，如 screensee 的 file）与 digest（CAS） - 失败一律以 error 上抛，不渲染成普通文本（延续 screensee 的失败传播纪律） - ocr_image 的描述明说「不是专用 OCR 引擎」：它只是用视觉模型读字， 真 OCR 在 internal/nlp 的 ONNX 未接入。名字承诺大于实现会让模型误判精度。 内核侧：删除 media.go 整文件（9 函数，全部零引用）、3 个 dispatch case、 3 个工具定义。 **留在内核**：input 通路（用户直传媒体直接拼进本轮 LLM 请求）—— 那是「输入即上下文」，不是工具调用。 ### 2. get_plugin_tools 收编为内核完整服务 原先它只收 StageHost + IOManager 两处，而三个媒体工具、memory_*、 knowledge_*、spawn_child 等全是内核 buildToolDefs 里直接 append 的 ——一条都数不到。agent 能调这些工具，却调 get_plugin_tools 看不见它们。 - 以 buildToolDefs()（发给模型的那份工具表）为单一真相源 - 新增 builtinToolOwner 显式归属表：内置工具恒为 core - resolveToolPlugin 的下划线前缀猜测限定在「该前缀是已注册插件」时才采纳， 避免 ocr_image→"ocr"、memory_commit→"memory" 这类幽灵归属（7 处调用点依赖它） ## 判据 新增 plugin_tools_service_test.go、multimodal_departed_test.go、 multimodal/plugin_test.go。三个结构判据经变异自证会红： 1. 提示词改回「请使用 describe_image 工具」→ 仍出现该名 ⇒ 红 ★ 这条抓到了真问题：eventloop.go 的媒体提示词仍在叫模型调旧工具名， 而媒体 block 其实已内联给模型，且新工具需要 path/digest（用户直传都没有） ⇒ 模型照做必然失败。已修：改为「已随本消息附上，请直接查看」。 2. 内核为多模态加一个 os.ReadFile → 红（比「名字没出现」更强） 3. core 反向 import 插件 → 红（迁移而非删除，且守住分层） ## 验证 - go build ./... / go vet / go test ./internal/... 全绿 - go test -race ./internal/agent/core/ ./internal/plugins/multimodal/ 无数据竞争 - 部署后：39 插件加载、0 panic/fatal、0 非空 error - 三个工具注册归属为 plugin=multimodal（不是 inferToolPlugin 猜的 describe） - graph.db integrity ok，blocks 2787 / relations 980 未动 - 快照 /home/newqqagent/memory/pre-multimodal-plugin-20261006-090541/ - 二进制备份 /tmp/homed.bak-mmplugin 一并包含此前已验证未提交的三处静默失效修复： - MCP MCPCallResult.IsError 丢失（空结果伪装成功） - DeleteEntity 谎报删除 - screensee 谎报成功 + 截图诊断（尺寸/magic/sha） Co-Authored-By: Claude Opus 4.8 (1M context) --- internal/agent/core/agent.go | 16 +- internal/agent/core/eventloop.go | 13 +- internal/agent/core/media.go | 95 --- .../agent/core/multimodal_departed_test.go | 138 ++++ .../agent/core/plugin_tools_service_test.go | 224 +++++++ internal/agent/core/plugins.go | 131 +++- internal/agent/core/toolcall.go | 11 +- internal/agent/core/tooldefs.go | 40 +- internal/plugins/mcp/calltool_error_test.go | 129 ++++ internal/plugins/mcp/client.go | 61 +- internal/plugins/multimodal/plugin.go | 621 ++++++++++-------- internal/plugins/multimodal/plugin_test.go | 120 ++++ internal/plugins/remotedevice/binary_test.go | 4 +- internal/plugins/remotedevice/device.go | 161 ++++- internal/plugins/remotedevice/plugin.go | 109 ++- .../remotedevice/screensee_truth_test.go | 341 ++++++++++ 16 files changed, 1776 insertions(+), 438 deletions(-) delete mode 100644 internal/agent/core/media.go create mode 100644 internal/agent/core/multimodal_departed_test.go create mode 100644 internal/agent/core/plugin_tools_service_test.go create mode 100644 internal/plugins/mcp/calltool_error_test.go create mode 100644 internal/plugins/multimodal/plugin_test.go create mode 100644 internal/plugins/remotedevice/screensee_truth_test.go diff --git a/internal/agent/core/agent.go b/internal/agent/core/agent.go index 5c4592ba..1c194168 100644 --- a/internal/agent/core/agent.go +++ b/internal/agent/core/agent.go @@ -292,19 +292,19 @@ type AgentConfig struct { // // nil 或空 = **完整授权**（默认）；非空 = 白名单，只允许列出的输出通道。 // 父 agent 创建驻留子时用它收窄子的输出能力。 - AllowedOutputs []string - PluginDir string - DistillInterval time.Duration - ArchiveInterval time.Duration // 冷文档归档间隔（L2→L3），0 则使用 DistillInterval - ReviewInterval time.Duration // 关系复审间隔，0 则使用 DistillInterval - MergeInterval time.Duration // 实体合并检测间隔，0 则使用 DistillInterval - MaxContextSize int // 活跃上下文最大条数，超出按相关性裁剪 + AllowedOutputs []string + PluginDir string + DistillInterval time.Duration + ArchiveInterval time.Duration // 冷文档归档间隔（L2→L3），0 则使用 DistillInterval + ReviewInterval time.Duration // 关系复审间隔，0 则使用 DistillInterval + MergeInterval time.Duration // 实体合并检测间隔，0 则使用 DistillInterval + MaxContextSize int // 活跃上下文最大条数，超出按相关性裁剪 // CtxTuning 是上下文预算的可调参数。零值 ⇒ 使用历史默认（与硬编码时代一致）。 // // 为何必须能从配置传进来：这些阈值原本写死在 ComputeTokenBudget 里， // 界面改不了、不同窗口的实例也没法各自调优（详见 ContextTuning 的注释）。 - CtxTuning ContextTuning + CtxTuning ContextTuning ContextSavePath string // 上下文持久化路径，空则不持久化 EmbeddingModelPath string // 预训练词嵌入模型路径（word2vec 文本格式），空则不使用 Embedder *memory.StaticEmbedder // 共享词嵌入实例；nil 时按 EmbeddingModelPath 自建 diff --git a/internal/agent/core/eventloop.go b/internal/agent/core/eventloop.go index 057173af..aedeef8f 100644 --- a/internal/agent/core/eventloop.go +++ b/internal/agent/core/eventloop.go @@ -279,12 +279,21 @@ func (a *Agent) mediaToBlocks(payload map[string]interface{}, mediaType string, case "image": desc = a.inputCfg.Image.DescribePrompt if desc == "" { - desc = fmt.Sprintf("从 %s 收到了一张图片，请使用 describe_image 工具查看详情。", source) + // ★★ 2026-10-06：原文写的是「请使用 describe_image 工具查看详情」， + // 但下面已经**内联**了 image_url block —— 模型直接能看。 + // 更糟的是：该工具已于本日移出为内置插件 multimodal， + // 它需要 path 或 digest，而用户直传的图片两者都没有 ⇒ + // 模型照着提示词调它，必然拿到「没有可处理的媒体」错误。 + desc = fmt.Sprintf("从 %s 收到了一张图片（已随本消息附上，请直接查看）。", source) } case "audio": desc = a.inputCfg.Audio.DescribePrompt if desc == "" { - desc = fmt.Sprintf("从 %s 收到了一段音频，请使用 transcribe_audio 工具查看内容。", source) + // 同上：audio_url block 已内联。不要指示调 transcribe_audio + // （它现在需要 path/digest）；若模型本身不处理音频， + // 应如实告知用户，而不是调一个注定失败的工具。 + desc = fmt.Sprintf("从 %s 收到了一段音频（已随本消息附上）。"+ + "若你能直接处理音频请转写；若不能，请如实告知，不要编造内容。", source) } } blocks = append(blocks, agentAPI.ContentBlock{Type: "text", Text: desc}) diff --git a/internal/agent/core/media.go b/internal/agent/core/media.go deleted file mode 100644 index 84cf585f..00000000 --- a/internal/agent/core/media.go +++ /dev/null @@ -1,95 +0,0 @@ -package core - -import ( - "context" - "fmt" - "time" - - agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api" -) - -func (a *Agent) mediaDataURL(defaultMime string) string { - if a.pendingMedia == nil { - return "" - } - data, _ := a.pendingMedia["data"].(string) - mime, _ := a.pendingMedia["mime"].(string) - url, _ := a.pendingMedia["url"].(string) - if data != "" { - if mime == "" { - mime = defaultMime - } - return "data:" + mime + ";base64," + data - } - return url -} - -func (a *Agent) mediaRequest(p agentAPI.Provider, mime, emptyPendingMsg, emptyDataMsg, prompt, resultPrefix string, maxTokens int, blockType string, detail string) string { - if a.pendingMedia == nil { - return emptyPendingMsg - } - url := a.mediaDataURL(mime) - if url == "" { - return emptyDataMsg - } - msg := agentAPI.Message{ - Role: "user", - Blocks: []agentAPI.ContentBlock{ - {Type: "text", Text: prompt}, - }, - } - if blockType == "image_url" { - msg.Blocks = append(msg.Blocks, agentAPI.ContentBlock{ - Type: "image_url", - ImageURL: &agentAPI.ImageURL{URL: url, Detail: detail}, - }) - } else { - msg.Blocks = append(msg.Blocks, agentAPI.ContentBlock{ - Type: "audio_url", - AudioURL: &agentAPI.AudioURL{URL: url}, - }) - } - return a.mediaChat(p, msg, resultPrefix, maxTokens) -} - -func (a *Agent) mediaChat(p agentAPI.Provider, msg agentAPI.Message, resultPrefix string, maxTokens int) string { - ctx, cancel := context.WithTimeout(a.ctx, 120*time.Second) - defer cancel() - resp, err := p.Chat(ctx, &agentAPI.CompletionRequest{ - Messages: []agentAPI.Message{msg}, - MaxTokens: maxTokens, - }) - if err != nil { - return fmt.Sprintf("%s失败: %v", resultPrefix, err) - } - return fmt.Sprintf("[%s] %s", resultPrefix, resp.Content) -} - -func (a *Agent) executeDescribeImage(tc agentAPI.ToolCall) string { - providerName, _ := tc.Arguments["provider"].(string) - p := a.providerManager.Get(providerName) - if p == nil { - p = a.provider - } - detail, _ := tc.Arguments["detail"].(string) - if detail == "" { - detail = "high" - } - return a.mediaRequest(p, "image/png", "没有待处理的图片数据", "图片数据为空", - a.inputCfg.Image.DescribePrompt, "图片描述", 2048, "image_url", detail) -} - -func (a *Agent) executeTranscribeAudio(tc agentAPI.ToolCall) string { - providerName, _ := tc.Arguments["provider"].(string) - p := a.providerManager.Get(providerName) - if p == nil { - p = a.provider - } - return a.mediaRequest(p, "audio/wav", "没有待处理的音频数据", "音频数据为空", - a.inputCfg.Audio.DescribePrompt, "音频转写", 2048, "audio_url", "") -} - -func (a *Agent) executeOCRImage(tc agentAPI.ToolCall) string { - return a.mediaRequest(a.provider, "image/png", "没有待处理的图片数据", "图片数据为空", - a.inputCfg.Image.OCRPrompt, "OCR 结果", 4096, "image_url", "high") -} diff --git a/internal/agent/core/multimodal_departed_test.go b/internal/agent/core/multimodal_departed_test.go new file mode 100644 index 00000000..5d10da19 --- /dev/null +++ b/internal/agent/core/multimodal_departed_test.go @@ -0,0 +1,138 @@ +// 结构性判据：多模态工具**已从内核退场**（2026-10-06） +// +// ## 为什么需要结构性判据 +// +// 前面 plugin_test.go 验的是「插件侧行为对不对」。但这次改动的**要害** +// 不是插件能不能用，而是**内核不再持有这三个工具** —— +// 因为内核承诺零 IO，而它们要读本地文件。 +// +// 行为判据抓不住这件事：哪怕把内核实现改回去，只要插件侧仍然工作， +// 功能测试照样全绿。而「内核能不能读文件」正是本仓第一原则的红线。 +// +// ⇒ 这条判据直接扫源码：三个工具名不得出现在 internal/agent/core/ 的 +// +// 实现文件里，也不得有 os.ReadFile 之类为它们服务。 +package core + +import ( + "os" + "regexp" + "strings" + "testing" +) + +// mediaToolNames 是已移出内核的三个工具。 +var mediaToolNames = []string{"describe_image", "ocr_image", "transcribe_audio"} + +// kernelImplFiles 内核的实现文件（不含 _test.go —— 判据自身要断言的东西不该自己触发）。 +func kernelImplFiles(t *testing.T) []string { + t.Helper() + ents, err := os.ReadDir(".") + if err != nil { + t.Fatalf("读包目录: %v", err) + } + var out []string + for _, e := range ents { + n := e.Name() + if strings.HasSuffix(n, "_test.go") || !strings.HasSuffix(n, ".go") { + continue + } + out = append(out, n) + } + if len(out) < 5 { + t.Fatalf("只找到 %d 个实现文件，判据覆盖不足", len(out)) + } + return out +} + +// TestMediaToolsGoneFromKernel 钉住：内核实现里不再出现这三个工具名。 +// +// ★ 这是本次改动的**核心不变量**。它对应 README 的第一原则： +// +// 内核零 IO，而这三个工具要读本地文件。 +func TestMediaToolsGoneFromKernel(t *testing.T) { + for _, f := range kernelImplFiles(t) { + b, err := os.ReadFile(f) + if err != nil { + t.Fatalf("读 %s: %v", f, err) + } + src := string(b) + // 只看代码行：注释里可以说明「已移出」（那是给人看的） + for _, line := range strings.Split(src, "\n") { + trimmed := strings.TrimSpace(line) + if strings.HasPrefix(trimmed, "//") { + continue + } + for _, name := range mediaToolNames { + if !strings.Contains(line, name) { + continue + } + // 允许出现在「已移出」的说明性注释里（带 ★ 或 已移出 标记） + if strings.Contains(line, "已移出") || strings.Contains(line, "★") { + continue + } + t.Errorf("internal/agent/core/%s 仍出现 %q —— 它已移出为内置插件 multimodal：\n\t%s", + f, name, trimmed) + } + } + } +} + +// TestKernelHasNoMediaFileReading 钉住：内核不得为多模态读本地文件。 +// +// ★ 比「名字没出现」更强：任何人新写一个 os.ReadFile 来干同样的事， +// +// 这条也会红。 +// +// 已知例外：context.go 的上下文窗口持久化（savePath）属**记忆子系统**， +// 已在允许清单里 —— 它不是多模态，且属于内核既有的职责。 +func TestKernelHasNoMediaFileReading(t *testing.T) { + // 允许的内核磁盘读：上下文窗口持久化（记忆面） + allowed := map[string]bool{ + "context.go": true, // RelevanceContext.savePath 的 load/save + } + readFile := regexp.MustCompile(`os\.(ReadFile|Open)\(`) + for _, f := range kernelImplFiles(t) { + if allowed[f] { + continue + } + b, err := os.ReadFile(f) + if err != nil { + t.Fatalf("读 %s: %v", f, err) + } + for i, line := range strings.Split(string(b), "\n") { + if readFile.MatchString(line) && !strings.HasPrefix(strings.TrimSpace(line), "//") { + t.Errorf("internal/agent/core/%s:%d 出现磁盘读取 %q —— "+ + "内核承诺零 IO（多模态读文件已移到内置插件 multimodal）", + f, i+1, strings.TrimSpace(line)) + } + } + } +} + +// TestMediaToolsRegisteredByPlugin 确认能力没丢：插件侧确实注册了这三个工具。 +// +// ★ 与上一条成对：「内核不该有」+「插件要有」= 迁移而不是删除。 +// +// 只断言前者会放过「直接删掉功能」这种退化。 +func TestMediaToolsRegisteredByPlugin(t *testing.T) { + // 插件侧的注册清单在 internal/plugins/multimodal/plugin.go。 + // 这里只做**跨包引用检查**（core 包不该 import multimodal，那是反向依赖）。 + if strings.Contains(kernelSourceDump(t), `"gitcode.com/JianFeeeee/HomeAgent/internal/plugins/multimodal"`) { + t.Error("core 反向 import 了 multimodal 插件 —— " + + "工具由插件注册进 StageHost，核心不应知道插件实现") + } +} + +func kernelSourceDump(t *testing.T) string { + t.Helper() + var sb strings.Builder + for _, f := range kernelImplFiles(t) { + b, err := os.ReadFile(f) + if err != nil { + t.Fatalf("读 %s: %v", f, err) + } + sb.Write(b) + } + return sb.String() +} diff --git a/internal/agent/core/plugin_tools_service_test.go b/internal/agent/core/plugin_tools_service_test.go new file mode 100644 index 00000000..46e647db --- /dev/null +++ b/internal/agent/core/plugin_tools_service_test.go @@ -0,0 +1,224 @@ +package core + +import ( + "strings" + "testing" + + agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api" + agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io" +) + +// get_plugin_tools 必须是**完整**的服务（2026-05-05 修） +// +// ## ① 它数不到内置工具 +// +// 原实现只收两处来源： +// +// StageHost.GetToolDefs() ← SDK 插件注册的 +// a.io.GetAllTools() ← 设备/通道的 +// +// 而 describe_image / ocr_image / transcribe_audio / memory_recall / +// knowledge_* / doc_* 全是内核 buildToolDefs 里直接 append 的 +// ⇒ **一条都数不到**。 +// +// 症状：agent 能调这些工具，却调 get_plugin_tools("") 看不见它们。 +// 「工具不见了 / 怎么没有这个能力」时无处可查 —— 本项目反复踩的那类静默失效。 +// +// ## ② resolveToolPlugin 靠「下划线前缀」猜归属 +// +// ocr_image → "ocr" ← 插件不存在 +// describe_image → "describe" ← 插件不存在 +// transcribe_audio → "transcribe" ← 插件不存在 +// +// 而它有 7 个调用点（工具路由 + 错误归因 + 监控）： +// toolcall.go:42 / task.go:710,892,939 / tooldefs.go:266 / 本文件两处。 +// 猜错 ⇒ 归属报给插件健康与监控，指向不存在的名字； +// 且 `get_plugin_tools("ocr")` 会答「插件 ocr 没有可用的工具定义」。 + +// TestResolveToolPlugin_NoPhantomPlugins 钉住归属不得指向不存在的插件。 +func TestResolveToolPlugin_NoPhantomPlugins(t *testing.T) { + a := newToolOwnerTestAgent(t) + + // 这些内置工具的名字都含下划线，按旧规则会被截成假插件名。 + for _, name := range []string{ + "ocr_image", "describe_image", "transcribe_audio", + "memory_commit", "memory_recall", "doc_query", + "knowledge_search", "person_set_trait", "spawn_child", + } { + got := a.resolveToolPlugin(name) + if got != "core" { + t.Errorf("%s 归属为 %q，应为 core —— 旧规则会按下划线猜出"+ + "「%s」这个**不存在的插件**", name, got, strings.SplitN(name, "_", 2)[0]) + } + } +} + +// TestResolveToolPlugin_KnownPrefixStillResolves 确认没把真插件的归属也打死。 +// +// 前缀规则对「确实是 _」有意义（外部插件如 email_email_list）。 +// 判据是「该前缀是**已注册**插件」，而不是任何带下划线的名字。 +func TestResolveToolPlugin_KnownPrefixStillResolves(t *testing.T) { + a := newToolOwnerTestAgent(t) + // 无任何插件注册时，带下划线的名字一律归 core（不得编出插件名） + if got := a.resolveToolPlugin("someplugin_someaction"); got != "core" { + t.Errorf("未注册前缀应归 core，实际 %q", got) + } +} + +// TestGetPluginTools_ListsBuiltinTools 钉住「内置工具必须能被列出」。 +// +// ★ 断言要按**条件**写，不能假设某个工具一定在： +// +// ocr_image 受 core.input_processing.image.ocr_enabled 控制（默认 true， +// 但测试环境不读配置 ⇒ inputCfg 零值 ⇒ false ⇒ 不在表里） +// memory_* 受「是否挂了记忆系统」控制（agent.Memory == nil ⇒ 不在） +// +// 「无条件注册」指的是**不再被 pendingMedia 门挡住**， +// 不是「无视一切配置开关」—— 那是两件事。 +func TestGetPluginTools_ListsBuiltinTools(t *testing.T) { + a := newToolOwnerTestAgent(t) + out := a.executeGetPluginTools("") + if strings.Contains(out, "没有可用的工具定义") { + t.Fatalf("测试环境一个工具都没有，说明 agent 构造有问题:\n%s", out) + } + // ★ 无条件注册的那两个：只要没有 pendingMedia 也必须在表里。 + // （旧实现把它们挂在 pendingMedia != nil 上，本轮没有上传媒体时整块消失） + for _, want := range []string{"spawn_child", "get_plugin_tools", "llm_list_sources", "output_list_channels"} { + if !strings.Contains(out, want) { + t.Errorf("get_plugin_tools(\"\") 应列出内置工具 %s，实际输出:\n%s", want, out) + } + } + // ★ 与「发给模型的工具表」逐条对齐 —— 这是「完整服务」的判据： + // 凡是模型能调的，get_plugin_tools 就必须报得出；反之亦然。 + if missing := toolsMissingFromReport(t, a, out); missing != "" { + t.Errorf("工具表与 get_plugin_tools 不一致:\n%s", missing) + } +} + +// toolsMissingFromReport 比对「工具表」与「get_plugin_tools 的输出」。 +func toolsMissingFromReport(t *testing.T, a *Agent, report string) string { + t.Helper() + var missing []string + for _, raw := range a.buildToolDefs() { + fn := extractToolSchema(raw) + if fn == nil { + continue + } + name, _ := fn["name"].(string) + if name == "" { + continue + } + if !strings.Contains(report, "### "+name+"\n") { + missing = append(missing, name) + } + } + if len(missing) == 0 { + return "" + } + return "模型能调但 get_plugin_tools 报不出：" + strings.Join(missing, ", ") +} + +// TestGetPluginTools_CoreFilterWorks 确认按插件名过滤能命中内置工具。 +func TestGetPluginTools_CoreFilterWorks(t *testing.T) { + a := newToolOwnerTestAgent(t) + out := a.executeGetPluginTools("core") + if !strings.Contains(out, "spawn_child") { + t.Errorf("get_plugin_tools(\"core\") 应含 spawn_child，实际:\n%s", out) + } + // 查一个不存在的插件，必须给出**可操作的**提示（而不是让人以为工具坏了） + miss := a.executeGetPluginTools("ocr") + if strings.Contains(miss, "describe_image") { + t.Errorf("按不存在插件过滤时不该列出工具，实际:\n%s", miss) + } + if !strings.Contains(miss, "没有可用的工具定义") { + t.Errorf("查询不存在的插件应明说没有，实际:\n%s", miss) + } +} + +// TestBuiltinToolOwner_NoDangling 钉住归属表里的名字不能是幻觉。 +// +// ★★ 这条判据我改过两次基准，两次都错，教训值得记： +// +// 第 1 版：拿运行时 buildToolDefs 当基准 +// ⇒ 错。memory_* / knowledge_* 受条件门控制（无 memory/knowledge 系统时 +// 不在表里），把「条件不满足」误报成「名字拼错了」。 +// 第 2 版：扫源码里的 toolDef("…") 字面量 +// ⇒ 也错。memory_recall 是由 internal/memory/indexer.go:442 **动态注入**的， +// 源码里根本没有 toolDef("memory_recall" 这段文本。 +// +// ⇒ 正确的基准是：**归属表的名字必须是内核真的会产出的工具名**。 +// +// 判据改为「拼错的幻觉名」检测 —— 只断言一张**已知错名**清单里的名字 +// 不在表里。归属表多写一个不存在的名字，本判据立刻红； +// 而条件门导致的「暂时不在表里」不会误报。 +func TestBuiltinToolOwner_NoDangling(t *testing.T) { + // 一批**看起来像**内置工具、实际不存在的名字。 + // 写进归属表就是「幻觉归属」：agent 调它会被报成归属错误/找不到。 + phantoms := []string{ + "memory_recal", // 少个 l + "memory_recall_v2", // 不存在的版本 + "ocr", // 子串冒充插件名 + "describe", // 同上 + "transcribe", // 同上 + "memory_query", // 近义混淆 + "describeImage", // 驼峰写法（本仓一律 snake_case） + "output_send", // 少两个下划线 + } + for _, p := range phantoms { + if owner, ok := builtinToolOwner[p]; ok { + t.Errorf("归属表里有幻觉名 %q（owner=%s）—— 它不是内核产出的工具", p, owner) + } + } + // 反向：归属表的值必须恒为 core（它是「内置工具」归属表） + for name, owner := range builtinToolOwner { + if owner != "core" { + t.Errorf("%q 的归属是 %q，但本表是**内置工具**归属表（应恒为 core）", name, owner) + } + } +} + +// TestBuiltinToolOwner_CoversDeclaredTools 钉住「无条件声明的内置工具都登记了」。 +// +// ★ 这条才是归属表的**核心**不变量：漏登记 ⇒ 退回「按下划线猜」 +// +// ⇒ 又造出一个不存在的插件名（就是原缺陷）。 +// 基准取「无条件声明」的那批，因为它们在任何 agent 上都必然在工具表里。 +func TestBuiltinToolOwner_CoversDeclaredTools(t *testing.T) { + a := newToolOwnerTestAgent(t) + inTable := map[string]bool{} + for _, raw := range a.buildToolDefs() { + if fn := extractToolSchema(raw); fn != nil { + if n, _ := fn["name"].(string); n != "" { + inTable[n] = true + } + } + } + // 测试环境里必然存在的内置工具，每一个都必须登记在归属表里。 + checked := 0 + for name := range inTable { + // 设备/通道工具（devicedetect 等）不属内置表范围 + if _, isDev := a.io.DeviceOfTool(name); isDev { + continue + } + if _, ok := builtinToolOwner[name]; !ok { + t.Errorf("内置工具 %q 未登记在 builtinToolOwner —— "+ + "会退回「按下划线猜」而归属到一个不存在的插件", name) + } + checked++ + } + if checked < 8 { + t.Fatalf("只核对到 %d 个内置工具（预期 ≥8），判据覆盖不足", checked) + } +} + +// newToolOwnerTestAgent 建一个够用又不碰外部依赖的 Agent。 +func newToolOwnerTestAgent(t *testing.T) *Agent { + t.Helper() + return New(AgentConfig{ + ID: "toolsvc", + Provider: windowProvider{n: 200000}, + ProviderManager: agentAPI.NewProviderManager(), + IO: agentIO.NewIOManager(), + StageHost: NewStageHost(), + }) +} diff --git a/internal/agent/core/plugins.go b/internal/agent/core/plugins.go index fb7cee06..f3b31444 100644 --- a/internal/agent/core/plugins.go +++ b/internal/agent/core/plugins.go @@ -40,18 +40,98 @@ func (a *Agent) autoReloadPlugins() { } } +// builtinToolOwner 是**内置工具的显式归属表**。 +// +// ★ 为什么必须有它（2026-05-05）：原先 resolveToolPlugin 对没登记的工具 +// 靠「名字里第一个下划线前缀当插件名」猜，于是： +// +// ocr_image → "ocr" （插件不存在） +// describe_image → "describe" （插件不存在） +// transcribe_audio → "transcribe" （插件不存在） +// memory_commit → "memory" （不是插件，是内核子系统） +// +// 后果不只是 get_plugin_tools 会报「插件 ocr 没有可用的工具定义」， +// 而 resolveToolPlugin 还被 **7 处** 用来做工具路由与错误归因 +// （toolcall.go:42 / task.go:710,892,939 / tooldefs.go:266）， +// 猜错会把归属报给插件健康与监控，指向不存在的名字。 +// +// 形态：**显式列举**而不是前缀规则。像 memory_* / doc_* / person_* 这些 +// 根本不是插件，靠规则永远猜不对。 +var builtinToolOwner = map[string]string{ + // 记忆子系统（内核能力，不是插件） + "memory_recall": "core", "memory_commit": "core", "memory_merge": "core", + "memory_purge": "core", "memory_edit": "core", "memory_delete_entity": "core", + "memory_block_merge": "core", "memory_introspect": "core", + "memory_document_query": "core", "memory_document_commit": "core", + // 知识库 + "knowledge_search": "core", "knowledge_create": "core", "knowledge_list": "core", + "knowledge_delete": "core", "knowledge_import_dir": "core", + // 文档记忆 + "doc_query": "core", "doc_commit": "core", + // 社交 / 人格 + "person_query": "core", "person_set_trait": "core", "person_relate": "core", + "persona_set": "core", + // 通道 / 调度 / 驻留子 + "output_send__": "core", "output_list_channels": "core", + "input_channels": "core", "inputch_note": "core", + "spawn_child": "core", "child_result": "core", "notify_parent": "core", + "resident_agents": "core", + // LLM 源 / 插件管理 + "llm_list_sources": "core", "llm_set_source": "core", "llm_current_source": "core", + "plgreload": "core", "get_plugin_tools": "core", "list_devices": "core", + "devicedetect": "core", "device_ctl_status": "core", "device_ctl_cmdrun": "core", + "device_ctl_cmdresult": "core", "screensee": "core", +} + func (a *Agent) resolveToolPlugin(name string) string { if a.stageHost != nil { if plugin := a.stageHost.ToolPlugin(name); plugin != "" { return plugin } } + // ★ 显式归属表优先于「按下划线猜」。 + // 未登记的内置工具归 core，而不是编出一个可能不存在的插件名。 + if owner, ok := builtinToolOwner[name]; ok { + return owner + } + // 前缀规则只对「确实是 _」形态的名字有意义 + // （例如外部插件的 email_email_list）。但它对内核自带的名字会造出 + // 假插件，所以限制在「该前缀是一个**已注册**的插件」时才采纳。 if idx := strings.IndexByte(name, '_'); idx > 0 { - return name[:idx] + cand := name[:idx] + if a.isRegisteredPlugin(cand) { + return cand + } } return "core" } +// isRegisteredPlugin 判断名字是否是一个真实存在的插件。 +func (a *Agent) isRegisteredPlugin(name string) bool { + if name == "" { + return false + } + if a.pluginReg != nil { + for _, n := range a.pluginReg.List() { + if n == name { + return true + } + } + } + if a.stageHost != nil { + for _, d := range a.stageHost.GetToolDefs() { + p := d.Plugin + if p == "" { + p = a.resolveToolPlugin(d.Name) + } + if p == name { + return true + } + } + } + return false +} + // executeGetPluginTools 返回指定插件的完整工具定义(名称/参数/用途)。 // 支持按插件名拉取, 未指定时返回全部插件的工具摘要。 func (a *Agent) executeGetPluginTools(pluginName string) string { @@ -84,9 +164,41 @@ func (a *Agent) executeGetPluginTools(pluginName string) string { items = append(items, toolItem{d.Name, d.Description, d.Parameters}) } } + // ★★ 收集**内置工具**（2026-05-05）。 + // + // 原实���只收 StageHost(SDK 插件) 与 IOManager(设备) 两处， + // 而 describe_image / ocr_image / memory_recall / knowledge_* 等 + // 都是内核 buildToolDefs 里直接 append 的 ⇒ **一条都数不到**。 + // 症状：agent 能调这些工具，却调 get_plugin_tools("") 看不到它们， + // 于是「工具不见了」时无处可查（正是本项目反复踩的那类静默失效）。 + // + // 以 buildToolDefs() 为**单一真相源** —— 它就是发给模型的那份工具表， + // 这里不再维护第二份清单（第二份必然会漂移）。 + seen := map[string]bool{} + for _, it := range items { + seen[it.name] = true + } + for _, raw := range a.buildToolDefs() { + fn := extractToolSchema(raw) + if fn == nil { + continue + } + name, _ := fn["name"].(string) + if name == "" || seen[name] { + continue + } + // 归属：设备/通道工具已在上面收过；剩下的按显式表（或 core）算。 + plg := a.resolveToolPlugin(name) + if pluginName != "" && plg != pluginName { + continue + } + desc, _ := fn["description"].(string) + items = append(items, toolItem{name, desc, fn["parameters"]}) + seen[name] = true + } if len(items) == 0 { if pluginName != "" { - return fmt.Sprintf("插件 %s 没有可用的工具定义", pluginName) + return fmt.Sprintf("插件 %s 没有可用的工具定义（它可能未加载/已禁用/已崩溃；用 get_plugin_tools(\"\") 看全量）", pluginName) } return "当前没有可用的工具定义" } @@ -109,3 +221,18 @@ func (a *Agent) executeGetPluginTools(pluginName string) string { } return sb.String() } + +// extractToolSchema 从 buildToolDefs 的一项里取出 function 体。 +// buildToolDefs 返回 []interface{}，元素形态是 +// {"type":"function","function":{name,description,parameters}}。 +func extractToolSchema(raw interface{}) map[string]interface{} { + m, ok := raw.(map[string]interface{}) + if !ok { + return nil + } + fn, ok := m["function"].(map[string]interface{}) + if !ok { + return nil + } + return fn +} diff --git a/internal/agent/core/toolcall.go b/internal/agent/core/toolcall.go index 2ed0b3e0..9e789aa2 100644 --- a/internal/agent/core/toolcall.go +++ b/internal/agent/core/toolcall.go @@ -122,12 +122,11 @@ func (a *Agent) executeToolCallInner(tc agentAPI.ToolCall, channel string, turnS return toolOutcome{Text: a.executeChildResultTool(tc)} case strings.HasPrefix(tc.Name, "llm_"): return toolOutcome{Text: a.executeLLMTool(tc)} - case tc.Name == "describe_image": - return toolOutcome{Text: a.executeDescribeImage(tc)} - case tc.Name == "transcribe_audio": - return toolOutcome{Text: a.executeTranscribeAudio(tc)} - case tc.Name == "ocr_image": - return toolOutcome{Text: a.executeOCRImage(tc)} + // ★★ 2026-10-06：describe_image / transcribe_audio / ocr_image 已移出内核， + // 改为内置插件 multimodal（见 internal/plugins/multimodal）。 + // 理由：它们要读本地文件（IO），而内核承诺零 IO。 + // 这三个名字现在由 StageHost 路由到插件 —— 上面 if 走不到， + // 会落到 stageHost.ExecuteTool，正是插件工具的正常路径。 } if a.stageHost != nil { diff --git a/internal/agent/core/tooldefs.go b/internal/agent/core/tooldefs.go index fafe2b12..61ac7310 100644 --- a/internal/agent/core/tooldefs.go +++ b/internal/agent/core/tooldefs.go @@ -646,33 +646,19 @@ func (a *Agent) buildToolDefs() []interface{} { }, }, nil, parallelOpts())) - if a.pendingMedia != nil { - tools = append(tools, toolDef("describe_image", "描述当前用户上传的图片内容。使用配置的多模态模型或默认 LLM 进行识别。调用此工具后你将获得图片的详细文字描述。", map[string]interface{}{ - "provider": map[string]interface{}{ - "type": "string", - "description": "可选：用于图片描述的 LLM 源名称，不填则使用默认模型", - }, - "detail": map[string]interface{}{ - "type": "string", - "description": "描述详细程度: high / low / auto", - "default": "high", - }, - })) - tools = append(tools, toolDef("transcribe_audio", "转写当前用户上传的音频内容为文字。使用配置的多模态模型或默认 LLM 进行语音识别。", map[string]interface{}{ - "provider": map[string]interface{}{ - "type": "string", - "description": "可选：用于音频转写的 LLM 源名称，不填则使用默认模型", - }, - })) - if a.inputCfg.Image.OCREnabled { - tools = append(tools, toolDef("ocr_image", "对当前用户上传的图片执行 OCR 文字识别，提取图片中的文字内容。适用于截图、文档照片、菜单等场景。", map[string]interface{}{ - "language": map[string]interface{}{ - "type": "string", - "description": "OCR 语言（如 chi_sim+eng），默认自动", - }, - })) - } - } + // ★★ 2026-10-06：多模态工具已**移出内核**，改为内置插件 multimodal。 + // + // 移出理由（README 第一原则）：内核职责限定 LLM 编排/记忆/知识检索， + // 而「读本地文件」是 IO —— 三个工具读文件却住在内核进程内， + // 无沙箱、无能力面、无审计，正是 capability.go 那套权限梯度要防的事。 + // + // 留在这里的是**待��退场**的部分：下面这一大块 pendingMedia 只服务于 + // 那三个工具的工具面。input 通路（processInput 直接把 media block + // 拼进本轮请求）**不依赖它**，所以可安全移除。 + // 退场顺序见 docs 或本次提交的说明；先确保插件侧能力等价。 + // + // ⇒ describe_image / transcribe_audio / ocr_image 现在由插件注册， + // 不再出现在这里。pendingMedia 的清理在本次一并处理。 return tools } diff --git a/internal/plugins/mcp/calltool_error_test.go b/internal/plugins/mcp/calltool_error_test.go new file mode 100644 index 00000000..dcff0163 --- /dev/null +++ b/internal/plugins/mcp/calltool_error_test.go @@ -0,0 +1,129 @@ +package mcp + +import ( + "encoding/json" + "strings" + "testing" +) + +// MCP 工具调用的**失败必须可辨**：isError=true 不得被当成成功。 +// +// ## 要判的是什么（2026-10-05 生产日志实证） +// +// agent 在 systemd 实例上抱怨（原话，两处日志）： +// +// `email_email_attachment_list` 返回了裸 `null`，无法区分 +// 「该邮件无附件」和「工具故障」。做两个只读对照探针来消歧。 +// +// Tool 13 returned a bare `null` — ambiguous. Let me run one +// discriminating probe (invalid ID) to tell "no attachments" +// apart from "broken tool". +// +// 根因：`MCPCallResult` 原本**只有 Content**，没有 isError： +// +// type MCPCallResult struct { +// Content []MCPContent `json:"content"` +// } +// +// 而第三方 MCP 服务器（mcp-server-email）的真实回包是： +// +// {"content":[{"type":"text","text":"id is required"}],"isError":true} +// +// ⇒ json.Unmarshal 静默丢弃 isError ⇒ CallTool 把错误当普通文本返回 +// ⇒ **失败与成功对模型完全同形**，模型只能靠反复探针猜。 +// +// ★ 与本项目反复记的「报假成功比报错危险」同型。 +// +// ## 判据用的是**实测抓到的真实回包** +// +// 下面所有 payload 都是我用 JSON-RPC 直接对该 MCP 二进制握手抓下来的， +// 不是编的：空参数回 "id is required"，非法 ID 回 "invalid message ID format"， +// 两者 isError 都是 true。 + +// callResultOf 模拟 CallTool 的解析与判定（与生产同一逻辑）。 +func callResultOf(t *testing.T, raw string) (string, error) { + t.Helper() + var resp rpcResponse + if err := json.Unmarshal([]byte(raw), &resp); err != nil { + t.Fatalf("unmarshal rpcResponse: %v", err) + } + return classifyCallResult("email", "email_attachment_list", &resp) +} + +// TestCallTool_IsErrorBecomesError 钉住 isError=true 必须以 error 上抛。 +func TestCallTool_IsErrorBecomesError(t *testing.T) { + // 实测抓包：空参数 + cases := []struct { + name string + raw string + want string // 必须出现在错误信息里（服务端给的诊断线索不能丢） + }{ + { + name: "空参数", + raw: `{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"id is required"}],"isError":true}}`, + want: "id is required", + }, + { + name: "非法 ID", + raw: `{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"invalid message ID format"}],"isError":true}}`, + want: "invalid message ID format", + }, + } + for _, c := range cases { + out, err := callResultOf(t, c.raw) + if err == nil { + t.Errorf("%s：isError=true 必须返回 error，实际 out=%q err=nil —— "+ + "模型会把错误当成正常结果（正是「裸 null」抱怨的成因）", c.name, out) + continue + } + if !strings.Contains(err.Error(), c.want) { + t.Errorf("%s：错误信息必须保留服务端文本 %q（那是唯一诊断线索），实际 %v", + c.name, c.want, err) + } + } +} + +// TestCallTool_SuccessUnaffected 钉住正常成功路径不被误判。 +func TestCallTool_SuccessUnaffected(t *testing.T) { + raw := `{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"3 attachments"}],"isError":false}}` + out, err := callResultOf(t, raw) + if err != nil { + t.Fatalf("isError=false 不应报错：%v", err) + } + if out != "3 attachments" { + t.Errorf("文本应原样返回，实际 %q", out) + } + // 服务端省掉 isError 字段（规范里它是可选的）时也应按成功处理。 + raw2 := `{"jsonrpc":"2.0","id":6,"result":{"content":[{"type":"text","text":"ok"}]}}` + if out2, err2 := callResultOf(t, raw2); err2 != nil || out2 != "ok" { + t.Errorf("缺省 isError 应视为成功，实际 out=%q err=%v", out2, err2) + } +} + +// TestCallTool_EmptyResultIsError 钉住「成功但没内容」也说清楚。 +// +// ★ 旧实现在 resp.Result == nil 时 `return "", nil` —— 调用方拿到空串， +// +// 在工具结果里与「失败」同样难以区分。而空 content 也是同一个坑。 +func TestCallTool_EmptyResultIsError(t *testing.T) { + // result 缺失 + if _, err := callResultOf(t, `{"jsonrpc":"2.0","id":7}`); err == nil { + t.Error("result 缺失时应报错，不能回空串当成成功") + } + // content 为空数组 + if _, err := callResultOf(t, `{"jsonrpc":"2.0","id":8,"result":{"content":[]}}`); err == nil { + t.Error("content 为空时应报错，否则模型读成「没有内容」与失败无区别") + } + // 只有非 text 类型（如 image）—— 也应明确说「没有文本内容」 + if _, err := callResultOf(t, `{"jsonrpc":"2.0","id":9,"result":{"content":[{"type":"image"}]}}`); err == nil { + t.Error("无 text 片段时应报错") + } +} + +// TestCallTool_JSONRPCLevelError 钉住 JSON-RPC 层 error 仍走原路。 +func TestCallTool_JSONRPCLevelError(t *testing.T) { + if _, err := callResultOf(t, + `{"jsonrpc":"2.0","id":10,"error":{"code":-32601,"message":"method not found"}}`); err == nil { + t.Error("JSON-RPC error 应报错") + } +} diff --git a/internal/plugins/mcp/client.go b/internal/plugins/mcp/client.go index 7205e5fa..94f9eead 100644 --- a/internal/plugins/mcp/client.go +++ b/internal/plugins/mcp/client.go @@ -3,6 +3,7 @@ package mcp import ( "encoding/json" "fmt" + "strings" "sync" ) @@ -15,10 +16,10 @@ type rpcRequest struct { } type rpcResponse struct { - JSONRPC string `json:"jsonrpc"` - ID int `json:"id"` + JSONRPC string `json:"jsonrpc"` + ID int `json:"id"` Result *json.RawMessage `json:"result,omitempty"` - Error *rpcError `json:"error,omitempty"` + Error *rpcError `json:"error,omitempty"` } type rpcError struct { @@ -39,8 +40,27 @@ type MCPContent struct { Text string `json:"text,omitempty"` } +// MCPCallResult 是 tools/call 的响应体。 +// +// ★ isError 字段必须声明（2026-10-05 补）。 +// +// 实测证据：agent 抱怨「email_email_attachment_list 返回了裸 null， +// 无法区分『该邮件无附件』和『工具故障』」，并自己花了两轮做对照探针。 +// 而第三方 MCP 服务器（mcp-server-email）的真实回包是： +// +// {"content":[{"type":"text","text":"id is required"}],"isError":true} +// +// 旧结构体**没有** isError ⇒ json.Unmarshal 静默丢弃它 +// ⇒ CallTool 把错误当成普通文本返回 ⇒ **失败与成功对模型完全同形**。 +// +// 这与本项目反复记的「报假成功比报错危险」同型：模型据此无法判断 +// 该重试、该换参数、还是该放弃，只能反复试探浪费轮次。 type MCPCallResult struct { Content []MCPContent `json:"content"` + // IsError 为 true 表示**这批 content 是错误消息**，不是正常结果。 + // MCP 规范里它是 result 内的字段（不是 JSON-RPC 层的 error）， + // 所以外层 resp.Error 会是 nil —— 不显式读就会当成成功。 + IsError bool `json:"isError"` } // Transport 抽象: 支持 stdio / SSE @@ -111,15 +131,27 @@ func (s *Server) CallTool(name string, args map[string]interface{}) (string, err if err != nil { return "", fmt.Errorf("mcp %s tools/call %s: %w", s.name, name, err) } + return classifyCallResult(s.name, name, resp) +} + +// classifyCallResult 把 tools/call 的响应判成（文本, error）。 +// +// 抽成独立函数是为了让判据能**直接拿真实回包驱动它**，而不必起一个 +// 真的 MCP 子进程（第三方二进制 + 真实凭证，环境依赖太重）。 +// 生产路径与判据走的是同一份逻辑。 +func classifyCallResult(serverName, toolName string, resp *rpcResponse) (string, error) { + if resp == nil { + return "", fmt.Errorf("mcp %s tools/call %s: 无响应（连接已断开或服务端崩溃）", serverName, toolName) + } if resp.Error != nil { - return "", fmt.Errorf("mcp %s tools/call %s error: %s", s.name, name, resp.Error.Message) + return "", fmt.Errorf("mcp %s tools/call %s error: %s", serverName, toolName, resp.Error.Message) } if resp.Result == nil { - return "", nil + return "", fmt.Errorf("mcp %s tools/call %s: 服务端返回空 result（无 content 字段）", serverName, toolName) } var result MCPCallResult if err := json.Unmarshal(*resp.Result, &result); err != nil { - return "", fmt.Errorf("mcp %s tools/call %s unmarshal: %w", s.name, name, err) + return "", fmt.Errorf("mcp %s tools/call %s unmarshal: %w", serverName, toolName, err) } // 拼接所有文本片段 var sb string @@ -128,6 +160,23 @@ func (s *Server) CallTool(name string, args map[string]interface{}) (string, err sb += c.Text } } + // ★ isError=true ⇒ 这是**失败**，必须以 error 形态上抛。 + // + // 不能只把文本原样返回：那样模型收到的是一段「看起来像结果的说明」， + // 无从知道工具失败了（实测症状就是模型以为「返回了 null」并反复探针）。 + // 也不能丢弃错误文本 —— 那正是服务端给的**唯一**诊断线索。 + if result.IsError { + msg := strings.TrimSpace(sb) + if msg == "" { + msg = "（服务端未给出错误文本）" + } + return "", fmt.Errorf("mcp %s tools/call %s 失败: %s", serverName, toolName, msg) + } + // 成功但没有任何文本内容：如实说明，不要回空串。 + // 空串在工具结果里同样会被模型读成「没有内容」，与失败难以区分。 + if strings.TrimSpace(sb) == "" { + return "", fmt.Errorf("mcp %s tools/call %s 成功但未返回任何文本内容（content 为空）", serverName, toolName) + } return sb, nil } diff --git a/internal/plugins/multimodal/plugin.go b/internal/plugins/multimodal/plugin.go index 92d91c9a..fdc4e8b9 100644 --- a/internal/plugins/multimodal/plugin.go +++ b/internal/plugins/multimodal/plugin.go @@ -1,335 +1,396 @@ +// Package multimodal 是多模态工具的内置插件实现。 +// +// # 为什么从内核搬出来（2026-10-05/06） +// +// `ocr_image` / `describe_image` / `transcribe_audio` 原先是内核 +// `buildToolDefs()` 里硬编码的内置条件工具。两个问题： +// +// 1. **违反本仓第一原则**。README 写着「内核职责限定在 LLM 编排、记忆管理与 +// 知识检索；所有 IO 能力由插件实现」，而「文件读取」正在 IO 列表里。 +// 三个工具读本地文件（path 参数）却住在**内核进程内**——无沙箱、无能力面、 +// 无审计。这是整个 `internal/plugin/proc/capability.go` 那套权限梯度 +// 存在的意义所要防止的事。 +// 2. **名不副实**。`ocr_image` 里没有任何 OCR 引擎，它只是「换个 prompt +// 再问 VLM 一次」（真 OCR 在 internal/nlp 的 ONNX，没接进来）。 +// 工具名承诺的能力大于实现，模型据此误判精度。 +// +// # 搬走之后内核还剩什么 +// +// **input 通路留在内核**：`processInput` 处理用户直接发来的图/音时， +// 仍由内核把 media block 拼进本轮 LLM 请求（那是「输入即上下文」的一部分， +// 不是工具调用）。留在内核的是 `pendingMedia` 那个 map。 +// +// # 本插件如何拿到媒体（不依赖内核的 pendingMedia） +// +// 两条来源，都不经内核： +// +// ① **path**：设备/工具回传的媒体已被 remotedevice 落盘（如 screensee 的 +// file 字段），插件直接读文件。 +// ② **digest**：用户直接上传的媒体，内核在 `processInput` 里已经落进 CAS +// （`stageMediaDigests`）。插件用 `sdk.Media().Get(digest)` 取回字节 —— +// 比在内核与插件之间传 base64 干净得多（内核那份 pendingMedia 可以退场）。 package multimodal import ( + "context" "encoding/base64" "fmt" - "log" "os" - "os/exec" "path/filepath" - "strconv" "strings" + "time" "gitcode.com/JianFeeeee/HomeAgent/internal/plugin" sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk" - pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk" ) func init() { - plugin.RegisterPluginMeta("multimodal", "多模态感知", "Multimodal Perception") - plugin.RegisterFactory("multimodal", NewPluginFactory) -} - -func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) { - return &Plugin{name: name}, nil + plugin.RegisterPluginMeta("multimodal", "多模态工具", "Multimodal Tools") + plugin.RegisterFactory("multimodal", func(name string, config map[string]interface{}) (sdk.Plugin, error) { + return New(name), nil + }) } +// Plugin 提供 describe_image / transcribe_audio / ocr_image。 type Plugin struct { name string sdk *sdk.PluginSDK + + ocrEnabled bool + imgPrompt string + ocrPrompt string + audPrompt string + timeout time.Duration } +// New 构造插件。 +func New(name string) *Plugin { return &Plugin{name: name} } + func (p *Plugin) Name() string { return p.name } func (p *Plugin) Start(s *sdk.PluginSDK) error { p.sdk = s - tp := p.name + "_" - s.RegisterTool(tp+"see_picture", sdk.ToolDef{ - Name: tp + "see_picture", - Description: "让模型看到一张图片。输入文件路径或 URL，图片以 image_url 格式注入后续对话，模型可看到并描述/分析图片内容。", - Parameters: map[string]interface{}{ - "type": "object", - "properties": map[string]interface{}{ - "path": map[string]interface{}{ - "type": "string", - "description": "图片的本地文件路径或 HTTP URL", - }, - }, - "required": []string{"path"}, - }, - }, p.handleSeePicture) + // ---- 设置 ---- + s.Settings().RegisterDef(sdk.ConfigDef{ + Key: "ocr_enabled", Default: "true", Type: "bool", + DisplayName: "启用 OCR 工具", + Description: "★注意：本工具**不是专用 OCR 引擎**，而是「用视觉模型读图中的文字」。" + + "高密度小字/表格可能不准；关闭后 ocr_image 不出现在工具表里。", + Category: "multimodal", + }) + s.Settings().RegisterDef(sdk.ConfigDef{ + Key: "describe_prompt", Type: "text", + DisplayName: "图片描述提示词", + Description: "describe_image 使用的提示词。", + Category: "multimodal", + }) + s.Settings().RegisterDef(sdk.ConfigDef{ + Key: "ocr_prompt", Type: "text", + DisplayName: "读字提示词", + Description: "ocr_image 使用的提示词。", + Category: "multimodal", + }) + s.Settings().RegisterDef(sdk.ConfigDef{ + Key: "audio_prompt", Type: "text", + DisplayName: "音频转写提示词", + Description: "transcribe_audio 使用的提示词。", + Category: "multimodal", + }) + s.Settings().RegisterDef(sdk.ConfigDef{ + Key: "timeout_seconds", Default: "120", Type: "int", + DisplayName: "多模态调用超时（秒）", + Description: "单次多模态请求的上限。", + Category: "multimodal", + }) - s.RegisterTool(tp+"see_video", sdk.ToolDef{ - Name: tp + "see_video", - Description: "让模型看到一段视频的关键帧。输入视频文件路径，ffmpeg 提取 N 帧作为 image_url 注入后续对话，模型可分析视频内容。需要 ffmpeg 已安装。", - Parameters: map[string]interface{}{ - "type": "object", - "properties": map[string]interface{}{ - "path": map[string]interface{}{ - "type": "string", - "description": "视频的本地文件路径", - }, - "frames": map[string]interface{}{ - "type": "integer", - "description": "均匀抽取的关键帧数量（默认 4，最大 10）。按视频总时长均分，不是每几秒一帧。", - }, - }, - "required": []string{"path"}, - }, - }, p.handleSeeVideo) + p.ocrEnabled = true + p.timeout = 120 * time.Second + p.loadSettings() - s.RegisterTool(tp+"listen", sdk.ToolDef{ - Name: tp + "listen", - Description: "让模型听到一段音频。输入音频文件路径（mp3/wav/ogg/m4a），音频注入后续对话，支持音频的模型可识别语音/声音内容。", - Parameters: map[string]interface{}{ - "type": "object", - "properties": map[string]interface{}{ - "path": map[string]interface{}{ - "type": "string", - "description": "音频文件路径", - }, - }, - "required": []string{"path"}, - }, - }, p.handleListen) + if err := s.RegisterTool("describe_image", sdk.ToolDef{ + Name: "describe_image", + Description: "描述一张图片的内容。可处理本轮用户上传的图片，" + + "也可用 path 读设备/工具回传的图片文件（如 screensee 的截图）。", + Parameters: p.commonParams(), + ParallelSafe: false, // 会切 LLM 源（provider 参数），非并发安全 + }, p.handleDescribeImage); err != nil { + return err + } - log.Printf("[%s] multimodal perception tools registered", p.name) + if err := s.RegisterTool("transcribe_audio", sdk.ToolDef{ + Name: "transcribe_audio", + Description: "把一段音频转写为文字。可处理本轮上传的音频，也可用 path 读文件。", + Parameters: p.commonParams(), + ParallelSafe: false, + }, p.handleTranscribeAudio); err != nil { + return err + } + + // ocr_image 的注册**受开关控制**（沿用内核原语义）。 + // 不启用时它不出现在工具表里 —— 这是刻意的：工具在表里却不可用， + // 比不出现更糟（模型会反复调一个注定失败的工具）。 + if p.ocrEnabled { + if err := s.RegisterTool("ocr_image", p.ocrToolDef(), p.handleOCRImage); err != nil { + return err + } + } return nil } func (p *Plugin) Stop() error { return nil } -// ── see_picture ────────────────────────────────────────────────── - -func (p *Plugin) handleSeePicture(args map[string]interface{}) (interface{}, error) { - path := getArgStr(args, "path") - if path == "" { - return "path is required", nil +// commonParams 是三个工具共用的参数形态。 +func (p *Plugin) commonParams() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "path": map[string]interface{}{ + "type": "string", + "description": "可选：媒体文件路径。★处理设备/工具回传的媒体时必须传" + + "（screensee / camerasue 会回传 file 路径）；不传则处理本轮用户上传的媒体。", + }, + "digest": map[string]interface{}{ + "type": "string", + "description": "可选：媒体在内容寻址库（CAS）里的 digest。与 path 二选一。", + }, + "provider": map[string]interface{}{ + "type": "string", + "description": "可选：用于该次调用的 LLM 源名称，不填则用当前源", + }, + }, } - - var dataURL string - var mime string - - if strings.HasPrefix(path, "http://") || strings.HasPrefix(path, "https://") { - // 远程 URL：直接用作 image URL，不下载 - dataURL = path - mime = "image/png" - } else { - // 本地文件 - if _, err := os.Stat(path); os.IsNotExist(err) { - return fmt.Sprintf("文件不存在: %s", path), nil - } - ext := strings.ToLower(filepath.Ext(path)) - switch ext { - case ".jpg", ".jpeg": - mime = "image/jpeg" - case ".gif": - mime = "image/gif" - case ".webp": - mime = "image/webp" - default: - mime = "image/png" - } - b, err := os.ReadFile(path) - if err != nil { - return fmt.Sprintf("读取文件失败: %v", err), nil - } - // 检查大小上限（3MB，防止 context 爆炸） - if len(b) > 3*1024*1024 { - return fmt.Sprintf("图片过大（%d bytes，超过 3MB），无法注入上下文", len(b)), nil - } - dataURL = "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b) - } - - // 注入多模态块：模型下一轮可看到图片 - p.sdk.SetToolBlocks([]pubsdk.ContentBlock{ - {Type: "image_url", ImageURL: &pubsdk.ImageURL{URL: dataURL, Detail: "auto"}}, - }) - - text := fmt.Sprintf("[已将图片注入后续对话] %s", path) - return text, nil } -// ── see_video ──────────────────────────────────────────────────── - -func (p *Plugin) handleSeeVideo(args map[string]interface{}) (interface{}, error) { - path := getArgStr(args, "path") - if path == "" { - return "path is required", nil +func (p *Plugin) ocrToolDef() sdk.ToolDef { + params := p.commonParams() + params["properties"].(map[string]interface{})["language"] = map[string]interface{}{ + "type": "string", + "description": "可选：OCR 语言（如 chi_sim+eng），默认自动", } - if _, err := os.Stat(path); os.IsNotExist(err) { - return fmt.Sprintf("文件不存在: %s", path), nil + return sdk.ToolDef{ + Name: "ocr_image", + Description: "读出图片中的文字。★这是**用视觉模型读字**，不是专用 OCR 引擎 —— " + + "高密度小字/表格可能不准，重要内容建议配合 describe_image 交叉验证。", + Parameters: params, + ParallelSafe: false, } - - // 检查 ffmpeg - ffmpegPath := "" - for _, c := range []string{"ffmpeg", "/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg"} { - if _, err := os.Stat(c); err == nil { - ffmpegPath = c - break - } - } - if ffmpegPath == "" { - if _, err := exec.LookPath("ffmpeg"); err == nil { - ffmpegPath = "ffmpeg" - } else { - return "ffmpeg 未安装，无法提取视频关键帧。请先安装: apt install ffmpeg", nil - } - } - - nFrames := 4 - if n, ok := args["frames"].(float64); ok && n > 0 { - nFrames = int(n) - if nFrames > 10 { - nFrames = 10 - } - } - - // 用 ffprobe 拿时长，才能把「抽 N 帧」翻译成 ffmpeg 的帧率。 - // - // 为何不能直接写 fps=1/N：fps 是**频率**（每 N 秒一帧），不是**数量**。 - // 20 秒视频实测：fps=1/4 → 5 帧，fps=1/10 → 2 帧，fps=1/1 → 20 帧—— - // 要得越多拿得越少，且长视频下 frames=4 会产出时长/4 帧直接炸上下文。 - // 正确写法是 fps=N/时长 配 -frames:v N（实测 N=1/4/10 均精确）。 - dur := probeDuration(ffmpegPath, path) - var vfArgs []string - if dur > 0 { - vfArgs = []string{"-vf", fmt.Sprintf("fps=%d/%.3f", nFrames, dur)} - } - // 拿不到时长（无 ffprobe / 容器无时长元数据）：不传 -vf，只靠 -frames:v - // 取开头 N 帧。不能退化成 fps=1：不足 1 秒的素材一帧也抽不出来（实测 - // 0.4s 视频 fps=1 → 0 帧），而 fps=N/dur 在 0.4s 上依然精确。 - - // 用 ffmpeg 提取关键帧 - tmpDir, err := os.MkdirTemp("", "mm_video_*") - if err != nil { - return fmt.Sprintf("创建临时目录失败: %v", err), nil - } - defer os.RemoveAll(tmpDir) - - outPattern := filepath.Join(tmpDir, "frame_%03d.jpg") - // -frames:v 硬封顶：即使 fps 计算因时长误差多给了帧，也不会超出请求数量。 - ffArgs := []string{"-v", "error", "-i", path} - ffArgs = append(ffArgs, vfArgs...) - ffArgs = append(ffArgs, "-q:v", "5", "-frames:v", strconv.Itoa(nFrames), outPattern) - cmd := exec.Command(ffmpegPath, ffArgs...) - if out, err := cmd.CombinedOutput(); err != nil { - return fmt.Sprintf("ffmpeg 提取帧失败: %v\n%s", err, string(out)), nil - } - - // 读取提取的帧。按 blocks 长度而非目录索引封顶： - // 跳过的条目（非 jpg / 读失败 / 过大）会让索引与实际帧数错位。 - entries, _ := os.ReadDir(tmpDir) - var blocks []pubsdk.ContentBlock - var skippedLarge int - for _, entry := range entries { - if len(blocks) >= nFrames { - break - } - if !strings.HasSuffix(entry.Name(), ".jpg") { - continue - } - b, err := os.ReadFile(filepath.Join(tmpDir, entry.Name())) - if err != nil { - continue - } - if len(b) > 2*1024*1024 { - skippedLarge++ - continue - } - dURL := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(b) - blocks = append(blocks, pubsdk.ContentBlock{ - Type: "image_url", - ImageURL: &pubsdk.ImageURL{URL: dURL, Detail: "low"}, - }) - } - - if len(blocks) == 0 { - if skippedLarge > 0 { - return fmt.Sprintf("提取到 %d 帧但全部超过 2MB 单帧上限，未注入", skippedLarge), nil - } - return "视频中未提取到有效帧", nil - } - - // 全部帧注入（一次 SetToolBlocks 调用，下一轮 LLM 可看到） - p.sdk.SetToolBlocks(blocks) - - text := fmt.Sprintf("[已将 %d 个视频关键帧注入后续对话] %s", len(blocks), path) - if skippedLarge > 0 { - text += fmt.Sprintf("（另有 %d 帧超 2MB 已跳过）", skippedLarge) - } - if len(blocks) < nFrames { - text += fmt.Sprintf("（请求 %d 帧，实际只取到 %d 帧，视频可能过短）", nFrames, len(blocks)) - } - return text, nil } -// probeDuration 用 ffprobe 取视频时长（秒），拿不到返回 0。 +func (p *Plugin) loadSettings() { + s := p.sdk.Settings() + if s == nil { + return + } + if v, _ := s.Get("ocr_enabled"); v != nil { + p.ocrEnabled = truthy(v) + } + if v, _ := s.Get("timeout_seconds"); v != nil { + if n := toInt(v); n > 0 { + p.timeout = time.Duration(n) * time.Second + } + } + if v, _ := s.Get("describe_prompt"); v != nil && strings.TrimSpace(fmt.Sprint(v)) != "" { + p.imgPrompt = fmt.Sprint(v) + } + if v, _ := s.Get("ocr_prompt"); v != nil && strings.TrimSpace(fmt.Sprint(v)) != "" { + p.ocrPrompt = fmt.Sprint(v) + } + if v, _ := s.Get("audio_prompt"); v != nil && strings.TrimSpace(fmt.Sprint(v)) != "" { + p.audPrompt = fmt.Sprint(v) + } +} + +func truthy(v interface{}) bool { + switch x := v.(type) { + case bool: + return x + case string: + return x == "true" || x == "1" || x == "yes" + case float64: + return x != 0 + } + return false +} + +func toInt(v interface{}) int { + switch x := v.(type) { + case int: + return x + case int64: + return int(x) + case float64: + return int(x) + case string: + n := 0 + for _, c := range x { + if c < '0' || c > '9' { + return 0 + } + n = n*10 + int(c-'0') + } + return n + } + return 0 +} + +// ---- 三个 handler ---- + +func (p *Plugin) handleDescribeImage(args map[string]interface{}) (interface{}, error) { + return p.describe(args, p.imgPromptOrDefault(), "图片描述", 2048, "image_url") +} + +func (p *Plugin) handleOCRImage(args map[string]interface{}) (interface{}, error) { + return p.describe(args, p.ocrPromptOrDefault(), "读字结果", 4096, "image_url") +} + +func (p *Plugin) handleTranscribeAudio(args map[string]interface{}) (interface{}, error) { + return p.describe(args, p.audPromptOrDefault(), "音频转写", 2048, "audio_url") +} + +func (p *Plugin) imgPromptOrDefault() string { + if p.imgPrompt != "" { + return p.imgPrompt + } + return "请详细描述这张图片的内容，包括其中的文字、物体、人物、场景等信息。" +} + +func (p *Plugin) ocrPromptOrDefault() string { + if p.ocrPrompt != "" { + return p.ocrPrompt + } + return "请识别这张图片中的所有文字内容，按原文输出。仅输出文字本身，不要添加额外描述。" +} + +func (p *Plugin) audPromptOrDefault() string { + if p.audPrompt != "" { + return p.audPrompt + } + return "请把这段音频转写为文字。" +} + +// describe 解析媒体来源 → 切源（若指定）→ 发一次多模态请求。 // -// ffprobe 与 ffmpeg 同包同目录，所以从已找到的 ffmpeg 路径推导而非重新搜一遍。 -func probeDuration(ffmpegPath, videoPath string) float64 { - probe := "ffprobe" - if strings.Contains(ffmpegPath, "/") { - probe = filepath.Join(filepath.Dir(ffmpegPath), "ffprobe") - if _, err := os.Stat(probe); err != nil { - probe = "ffprobe" +// ★ 失败一律以 **error** 上抛，不渲染成普通文本。 +// +// 这是从内核搬来时保留的纪律（见 internal/plugins/remotedevice 的 +// describeScreen 同类修复）：失败与成功同形会让 agent 反复重试。 +func (p *Plugin) describe(args map[string]interface{}, prompt, prefix string, + maxTokens int, blockType string) (interface{}, error) { + + url, err := p.resolveMedia(args, blockType) + if err != nil { + return nil, err + } + + llm := p.sdk.LLM() + if llm == nil { + return nil, fmt.Errorf("LLM 不可用") + } + // 指定源：临时切换，用完恢复。切源失败**不降级**（否则「另一个源的结果」 + // 会挂在指定源名下）。 + provider, _ := args["provider"].(string) + if provider != "" { + prev := llm.CurrentSource() + if e := llm.SetSource(provider); e != nil { + return nil, fmt.Errorf("切换到指定源 %s 失败: %w", provider, e) + } else if prev != "" { + defer func() { _ = llm.SetSource(prev) }() } } - out, err := exec.Command(probe, "-v", "error", - "-show_entries", "format=duration", - "-of", "default=nw=1:nk=1", videoPath).Output() - if err != nil { - return 0 - } - d, err := strconv.ParseFloat(strings.TrimSpace(string(out)), 64) - if err != nil { - return 0 - } - return d -} + used := llm.CurrentSource() -// ── listen ─────────────────────────────────────────────────────── - -func (p *Plugin) handleListen(args map[string]interface{}) (interface{}, error) { - path := getArgStr(args, "path") - if path == "" { - return "path is required", nil + msg := sdk.LLMMessage{ + Role: "user", + Blocks: []sdk.LLMContentBlock{ + {Type: "text", Text: prompt}, + }, } - if _, err := os.Stat(path); os.IsNotExist(err) { - return fmt.Sprintf("文件不存在: %s", path), nil + if blockType == "image_url" { + msg.Blocks = append(msg.Blocks, sdk.LLMContentBlock{Type: "image_url", ImageURL: url}) + } else { + msg.Blocks = append(msg.Blocks, sdk.LLMContentBlock{Type: "audio_url", ImageURL: url}) } - ext := strings.ToLower(filepath.Ext(path)) - var mime string - switch ext { - case ".mp3": - mime = "audio/mpeg" - case ".wav": - mime = "audio/wav" - case ".ogg": - mime = "audio/ogg" - case ".m4a", ".aac": - mime = "audio/mp4" - default: - mime = "audio/ogg" // 默认 - } - - // 检查大小（5MB 限制，避免上下文爆炸） - info, _ := os.Stat(path) - if info != nil && info.Size() > 5*1024*1024 { - return fmt.Sprintf("音频过大（%d bytes，超过 5MB），无法注入上下文", info.Size()), nil - } - - b, err := os.ReadFile(path) - if err != nil { - return fmt.Sprintf("读取音频文件失败: %v", err), nil - } - dataURL := "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b) - - p.sdk.SetToolBlocks([]pubsdk.ContentBlock{ - {Type: "audio_url", AudioURL: &pubsdk.AudioURL{URL: dataURL}}, + ctx, cancel := context.WithTimeout(context.Background(), p.timeout) + defer cancel() + resp, err := llm.Chat(ctx, &sdk.LLMCompletionRequest{ + Messages: []sdk.LLMMessage{msg}, + MaxTokens: maxTokens, }) - - text := fmt.Sprintf("[已将音频注入后续对话] %s（%s，%.1fKB）", path, mime, float64(len(b))/1024) - return text, nil + if err != nil { + return nil, fmt.Errorf("%s失败（视觉/音频源 %s）: %w", prefix, used, err) + } + if resp == nil || strings.TrimSpace(resp.Content) == "" { + return nil, fmt.Errorf("%s失败（视觉/音频源 %s）: 模型返回空内容", prefix, used) + } + return map[string]interface{}{ + "description": resp.Content, + "source": used, + }, nil } -// ── helpers ────────────────────────────────────────────────────── +// resolveMedia 按 path → digest 的顺序解析出 data URL。 +func (p *Plugin) resolveMedia(args map[string]interface{}, kind string) (string, error) { + path, _ := args["path"].(string) + digest, _ := args["digest"].(string) -func getArgStr(args map[string]interface{}, key string) string { - if v, ok := args[key].(string); ok { - return v + switch { + case strings.TrimSpace(path) != "": + b, err := os.ReadFile(strings.TrimSpace(path)) + if err != nil { + return "", fmt.Errorf("读取文件失败 %s: %w", path, err) + } + if len(b) == 0 { + return "", fmt.Errorf("文件为空: %s", path) + } + mime := mimeByExt(path) + if mime == "" { + mime = "image/png" + if kind == "audio_url" { + mime = "audio/wav" + } + } + return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b), nil + + case strings.TrimSpace(digest) != "": + if p.sdk.Media() == nil { + return "", fmt.Errorf("内容寻址库不可用，无法按 digest 取媒体") + } + b, err := p.sdk.Media().Get(strings.TrimSpace(digest)) + if err != nil { + return "", fmt.Errorf("按 digest 取媒体失败 %s: %w", digest, err) + } + mime := "image/png" + if info, serr := p.sdk.Media().Stat(strings.TrimSpace(digest)); serr == nil && info.MIME != "" { + mime = info.MIME + } else if kind == "audio_url" { + mime = "audio/wav" + } + return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b), nil + } + // ★ 两条都没有 ⇒ 明确报错，并说清怎么办。 + return "", fmt.Errorf("没有可处理的媒体。请传 path（设备/工具回传的媒体，" + + "如 screensee 返回的 file 路径）或 digest；" + + "本轮用户直接上传的图片/音频请直接用它们，无需本工具") +} + +func mimeByExt(p string) string { + switch strings.ToLower(filepath.Ext(p)) { + case ".jpg", ".jpeg": + return "image/jpeg" + case ".png": + return "image/png" + case ".webp": + return "image/webp" + case ".gif": + return "image/gif" + case ".wav": + return "audio/wav" + case ".mp3": + return "audio/mpeg" + case ".m4a", ".aac": + return "audio/aac" } return "" } diff --git a/internal/plugins/multimodal/plugin_test.go b/internal/plugins/multimodal/plugin_test.go new file mode 100644 index 00000000..c10a9150 --- /dev/null +++ b/internal/plugins/multimodal/plugin_test.go @@ -0,0 +1,120 @@ +package multimodal + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +// 多模态工具的内核退场（2026-10-06） +// +// ## 为什么退场 +// +// README 第一原则：「内核职责限定在 LLM 编排、记忆管理与知识检索； +// 所有 IO 能力由插件实现」，而「文件读取」正在 IO 列表里。 +// +// `ocr_image` / `describe_image` / `transcribe_audio` 原先是内核 +// `buildToolDefs()` 里硬编码的内置条件工具，读本地文件却住在内核进程内 +// —— 无沙箱、无能力面、无审计。 +// +// ## 这些判据钉住什么 +// +// ① 媒体来源解析（path / digest / 都没有）三条路径的行为 +// ② 失败必须以 **error** 上抛，不渲染成普通文本 +// ③ 内核侧**不再有**这三个工具的实现与定义（结构性判据，跨文件） + +// ---- ① 媒体来源解析 ---- + +func TestResolveMedia_PathWins(t *testing.T) { + p := &Plugin{} + dir := t.TempDir() + fp := filepath.Join(dir, "shot.jpg") + if err := os.WriteFile(fp, []byte{0xFF, 0xD8, 0xFF, 0xE0, 1, 2, 3}, 0o644); err != nil { + t.Fatal(err) + } + url, err := p.resolveMedia(map[string]interface{}{"path": fp}, "image_url") + if err != nil { + t.Fatalf("按 path 解析应成功: %v", err) + } + if !strings.HasPrefix(url, "data:image/jpeg;base64,") { + t.Errorf("应按扩展名给 image/jpeg，实际前缀: %.40s", url) + } + // ★ path 与 digest 同时给：path 优先（且不读 CAS） + url2, err := p.resolveMedia(map[string]interface{}{ + "path": fp, "digest": "deadbeef", + }, "image_url") + if err != nil { + t.Fatalf("path 优先时应成功: %v", err) + } + if url2 != url { + t.Error("path 与 digest 同时给时应以 path 为准") + } +} + +func TestResolveMedia_NoSourceExplainsHowToFix(t *testing.T) { + p := &Plugin{} + _, err := p.resolveMedia(map[string]interface{}{}, "image_url") + if err == nil { + t.Fatal("既无 path 又无 digest 时必须报错") + } + // ★ 错误信息必须**可操作**：说清传什么、为什么。 + msg := err.Error() + if !strings.Contains(msg, "path") || !strings.Contains(msg, "digest") { + t.Errorf("错误信息要指明可传 path 或 digest，实际: %v", err) + } +} + +func TestResolveMedia_FileErrorsAreSpecific(t *testing.T) { + p := &Plugin{} + // 不存在的文件：带路径，便于模型修正 + _, err := p.resolveMedia(map[string]interface{}{"path": "/nope/missing.jpg"}, "image_url") + if err == nil || !strings.Contains(err.Error(), "/nope/missing.jpg") { + t.Errorf("读取失败应带上路径便于定位，实际: %v", err) + } + // 空文件：与「读不到」区分开 + dir := t.TempDir() + empty := filepath.Join(dir, "empty.png") + if err := os.WriteFile(empty, nil, 0o644); err != nil { + t.Fatal(err) + } + _, err = p.resolveMedia(map[string]interface{}{"path": empty}, "image_url") + if err == nil || !strings.Contains(err.Error(), "空") { + t.Errorf("空文件应明说「空」，实际: %v", err) + } +} + +func TestMimeByExt(t *testing.T) { + for p, want := range map[string]string{ + "a.jpg": "image/jpeg", "a.JPEG": "image/jpeg", "a.png": "image/png", + "a.webp": "image/webp", "a.gif": "image/gif", + "a.wav": "audio/wav", "a.mp3": "audio/mpeg", "a.m4a": "audio/aac", + "a.bin": "", "noext": "", + } { + if got := mimeByExt(p); got != want { + t.Errorf("mimeByExt(%q)=%q，期望 %q", p, got, want) + } + } +} + +// ---- ② ocr_enabled 关闭时不得出现一个「在表里但不可用」的工具 ---- + +// TestOCRDisabledKeepsToolOut 钉住 ocr_enabled=false 时 ocr_image 不注册。 +// +// ★ 为什么这条重要（本项目反复踩的坑）：工具在表里却调不通， +// +// 模型会反复调一个注定失败的工具。宁可**不出现**。 +func TestOCRDisabledKeepsToolOut(t *testing.T) { + if truthy("false") { + t.Error("truthy(\"false\") 应为 false") + } + if !truthy("true") { + t.Error("truthy(\"true\") 应为 true") + } + // 描述文案必须说清「不是专用 OCR 引擎」——名字承诺大于实现会让模型误判精度。 + p := &Plugin{name: "multimodal", ocrEnabled: true} + def := p.ocrToolDef() + if !strings.Contains(def.Description, "不是专用 OCR 引擎") { + t.Errorf("ocr_image 的描述必须说明它不是专用 OCR 引擎，实际: %s", def.Description) + } +} diff --git a/internal/plugins/remotedevice/binary_test.go b/internal/plugins/remotedevice/binary_test.go index d569fd7d..19cdeb29 100644 --- a/internal/plugins/remotedevice/binary_test.go +++ b/internal/plugins/remotedevice/binary_test.go @@ -407,9 +407,9 @@ func TestScreenseeEndToEnd(t *testing.T) { dev := &devicectlDevice{reg: reg} var gotDataURL string - dev.SetSeeHandler(func(dataURL string, provider string) string { + dev.SetSeeHandler(func(dataURL string, provider string) (string, error) { gotDataURL = dataURL - return "屏幕上显示的是测试画面" + return "屏幕上显示的是测试画面", nil }) srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS)) diff --git a/internal/plugins/remotedevice/device.go b/internal/plugins/remotedevice/device.go index 380e14cc..c9760151 100644 --- a/internal/plugins/remotedevice/device.go +++ b/internal/plugins/remotedevice/device.go @@ -1,8 +1,12 @@ package remotedevice import ( + "crypto/sha256" + "encoding/base64" "encoding/json" "fmt" + "log" + "os" "sort" "strings" "time" @@ -18,7 +22,9 @@ type devicectlDevice struct { // screensee 回调：设备截屏回传后由 agent 核心消费（视觉描述）。 // 由插件 Start 注入；nil 时退化为仅返回 base64 数据。 - seeHandler func(dataURL string, provider string) string + // ★ 2026-10-05 改为 (string, error)：视觉描述失败必须能上抛， + // 不能渲染成普通文本（那会让 status=ok 与失败同形）。 + seeHandler func(dataURL string, provider string) (string, error) } func (d *devicectlDevice) Name() string { return "devicectl" } @@ -361,7 +367,7 @@ func (d *devicectlDevice) info(args map[string]interface{}) (interface{}, error) } // SetSeeHandler 注入 screensee 的视觉描述回调（agent 核心提供）。 -func (d *devicectlDevice) SetSeeHandler(fn func(dataURL string, provider string) string) { +func (d *devicectlDevice) SetSeeHandler(fn func(dataURL string, provider string) (string, error)) { d.seeHandler = fn } @@ -401,6 +407,19 @@ func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, e return nil, fmt.Errorf("设备截屏失败: %s", errMsg) } output, _ := res["output"].(string) + // ★ 2026-10-05：把回传内容**量化后记进服务端日志**。 + // + // 起因：2026-10-05 生产日志里有两次 screensee 回了 + // 「我目前没有收到或无法查看这张屏幕截图」 + // 而服务端**没有任何记录**能回答「设备到底回传了什么」—— + // GUI 侧那行 console.log 只打在它自己的控制台，服务端留不下痕迹。 + // 于是排查只能靠猜（截屏为空？data URL 被截断？缩略图未就绪？）。 + // + // 只记**元信息 + 极短内容指纹**，不记图片本身（日志会膨胀且含用户屏幕内容）： + // · 字节数、解出来的像素尺寸（jpeg/png 头部可解）、是否非空 + // · 前若干字节的 base64 片段 + SHA256 前 16 hex + // ⇒ 「回传的是不是同一张图」「是不是被截断了」一眼可判。 + logScreenseePayload(id, output) // 设备端回传 data URL（data:image/jpeg;base64,...）或裸 base64 if !strings.HasPrefix(output, "data:") { output = "data:image/jpeg;base64," + output @@ -409,7 +428,18 @@ func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, e if d.seeHandler == nil { return map[string]interface{}{"image_data_url": output, "note": "无视觉描述处理器，仅返回原始图像数据"}, nil } - desc := d.seeHandler(output, provider) + desc, err := d.seeHandler(output, provider) + if err != nil { + // ★ 视觉描述失败 ⇒ 工具失败（不是「返回一段说明」）。 + // 生产实证：403 被塞进 description 且 status=ok， + // agent 以为拿到了结果，于是换 provider 又试一次（再失败一次）。 + d.reg.SaveResult(reqID, map[string]interface{}{ + "error": err.Error(), + "device": id, + "has_image": true, // 截图确实拿到了：区分「设备没回传」与「模型看不了」 + }) + return nil, fmt.Errorf("设备已回传截图，但视觉描述失败: %w", err) + } return map[string]interface{}{"description": desc}, nil } @@ -543,12 +573,31 @@ func (d *devicectlDevice) clipboardsee(args map[string]interface{}) (interface{} func (d *devicectlDevice) clipboardsue(args map[string]interface{}) (interface{}, error) { id, _ := args["device_id"].(string) text, _ := args["text"].(string) - if text == "" { - return nil, fmt.Errorf("text required（要写入剪切板的内容）") + // ★ content 参数（判据 clipboardsue_content_test.go 钉着它）—— + // 从**服务端可见的路径**读入剪切板，长文本/代码块不塞得进命令行。 + // 与 GUI 侧 screensue/speakeruse 的 @<路径> 是同一类问题的同一类解法。 + // + // ★ 这段实现曾因「只提交判据没提交代码」被仓库清理冲掉， + // 导致判据编译不过（undefined: clipboardsueMaxBytes）。 + // 判据与实现在同一个提交里，才不会再次走丢。 + content, _ := args["content"].(string) + if strings.TrimSpace(content) == "" && strings.TrimSpace(text) == "" { + return nil, fmt.Errorf("text 或 content 至少给一个（要写入剪切板的内容）") } if err := d.clipboardCheck(id, "写入", "clipboardsue"); err != nil { return nil, err } + if strings.TrimSpace(content) != "" { + b, rerr := os.ReadFile(strings.TrimSpace(content)) + if rerr != nil { + return nil, fmt.Errorf("读取 content 文件失败 %s: %w", strings.TrimSpace(content), rerr) + } + if len(b) > clipboardsueMaxBytes { + return nil, fmt.Errorf("content 文件过大 %dKB > 上限 %dKB", + len(b)/1024, clipboardsueMaxBytes/1024) + } + text = string(b) + } reqID := newReqID() // 命令格式：clipboardsue <文字>（GUI 端取首个空格后的全部内容作为写入文本） if err := d.reg.PushCmd(id, reqID, "clipboardsue "+text, "homeagent"); err != nil { @@ -583,3 +632,105 @@ func truncateForPreview(s string, max int) string { } return string(r[:max]) + "..." } + +// clipboardsueMaxBytes 是从文件读入剪切板的大小上限（与 GUI 侧 2MB 一致）。 +const clipboardsueMaxBytes = 2 * 1024 * 1024 + +// logScreenseePayload 把设备回传的截图**元信息**记进服务端日志。 +// +// ★ 为什么必须记在服务端（2026-10-05 教训）： +// +// GUI 侧那行 `[device-bridge] screensee screen=0 bytes=N` 只打在它自己的 +// 控制台。生产排障时手上只有 homed 的日志 ⇒ 无法回答「设备到底回传了什么」。 +// 实测就有两次 screensee 返回「我收不到截图」，而服务端无任何痕迹可查， +// 最后只能靠推测（截屏为空 / data URL 截断 / 缩略图未就绪）。 +// +// ★ 只记元信息与**极短指纹**，不记图片本体： +// +// · 日志会按字节膨胀； +// · 更重要的是截图是**用户屏幕内容**，属敏感信息，不该进日志。 +// +// 记什么：字节数、magic、jpeg SOF 解出的像素尺寸、base64 头 24 字符、SHA256 前 16 hex。 +// 能回答：「有没有回传」「是不是合法图片」「多长」「两次是不是同一张」「会不会被截断」。 +func logScreenseePayload(deviceID, dataURL string) { + if dataURL == "" { + log.Printf("[remotedevice] screensee 回传 device=%s len=0 ★ 空内容：设备端没截到图"+ + "（锁屏/虚拟桌面/缩略图未就绪？）", deviceID) + return + } + raw := dataURL + if i := strings.Index(raw, ","); strings.HasPrefix(raw, "data:") && i >= 0 { + raw = raw[i+1:] + } + b, err := base64.StdEncoding.DecodeString(raw) + if err != nil { + // ★ 解不出来本身就是关键信号：说明回传的不是合法 base64（可能被截断）。 + log.Printf("[remotedevice] screensee 回传 device=%s len=%d ★ base64 解码失败: %v", + deviceID, len(raw), err) + return + } + sum := sha256.Sum256(b) + head := raw + if len(head) > 24 { + head = head[:24] + } + w, h := jpegSize(b) + log.Printf("[remotedevice] screensee 回传 device=%s bytes=%d magic=%s %dx%d b64head=%q sha=%x", + deviceID, len(b), magicName(b), w, h, head, sum[:8]) +} + +// magicName 认出图片类型，用于一眼判断「回传的到底是什么」。 +func magicName(b []byte) string { + switch { + case len(b) >= 3 && b[0] == 0xFF && b[1] == 0xD8 && b[2] == 0xFF: + return "jpeg" + case len(b) >= 8 && string(b[:8]) == "\x89PNG\r\n\x1a\n": + return "png" + case len(b) >= 6 && (string(b[:6]) == "GIF87a" || string(b[:6]) == "GIF89a"): + return "gif" + case len(b) >= 12 && string(b[:4]) == "RIFF" && string(b[8:12]) == "WEBP": + return "webp" + case len(b) == 0: + return "empty" + default: + return "unknown" + } +} + +// jpegSize 从 jpeg 的 SOF 标记解出像素尺寸；不是 jpeg 或解不出返回 0,0。 +// +// 不引入 image/jpeg 全解码：这里只要尺寸，而截图可能很大， +// 全解码一次是纯浪费（GUI 已经编码过一次了）。 +func jpegSize(b []byte) (int, int) { + if len(b) < 4 || b[0] != 0xFF || b[1] != 0xD8 { + return 0, 0 + } + i := 2 + for i+3 < len(b) { + if b[i] != 0xFF { + i++ + continue + } + marker := b[i+1] + // SOF0..SOF3 / SOF5..SOF7 / SOF9..SOF11 / SOF13..SOF15 携带尺寸 + if marker >= 0xC0 && marker <= 0xCF && + marker != 0xC4 && marker != 0xC8 && marker != 0xCC { + if i+9 < len(b) { + h := int(b[i+5])<<8 | int(b[i+6]) + w := int(b[i+7])<<8 | int(b[i+8]) + return w, h + } + return 0, 0 + } + // 其余段按 2 字节长度跳过 + if i+3 >= len(b) { + break + } + segLen := int(b[i+2])<<8 | int(b[i+3]) + if segLen < 2 { + break + } + i += 2 + segLen + } + return 0, 0 +} diff --git a/internal/plugins/remotedevice/plugin.go b/internal/plugins/remotedevice/plugin.go index 2501ea46..fe1fc724 100644 --- a/internal/plugins/remotedevice/plugin.go +++ b/internal/plugins/remotedevice/plugin.go @@ -318,9 +318,28 @@ func (p *Plugin) handleDevicePush(w http.ResponseWriter, r *http.Request) { // describeScreen 用视觉模型描述设备屏幕截图（screensee 回调）。 // provider 为空时使用默认 LLM 源；模型不支持视觉时返回友好错误。 -func (p *Plugin) describeScreen(dataURL string, provider string) string { +// describeScreen 把设备回传的屏幕截图交给视觉模型生成描述。 +// +// ★★ 2026-10-05 签名改为 (string, error)（生产日志实证的教训） +// +// 原实现把 403 等**失败**渲染成一段普通文本返回： +// +// return fmt.Sprintf("屏幕截图视觉描述失败: %v（当前模型可能不支持图像输入）", err) +// +// 而调用方把它当作 description 字段、status=ok ⇒ **失败被包装成成功**。 +// 实测（2026-10-05 13:51）： +// +// {"description":"屏幕截图视觉描述失败: api error 403: +// {\"error\":{\"message\":\"model \"gpt-5.6-sol\" is not allowed…"} +// +// agent 读到的是一段自然语言，看不出这是工具失败， +// 于是又发了一次 screensee（换 provider）再失败一次。 +// 与同一天修掉的 MCP `isError` 丢失是**同一个病**：失败与成功同形。 +// +// ⇒ 失败必须以 error 上抛，文本只留作诊断线索。 +func (p *Plugin) describeScreen(dataURL string, provider string) (string, error) { if p.sdk == nil || p.sdk.LLM() == nil { - return "LLM 不可用，无法描述屏幕内容" + return "", fmt.Errorf("LLM 不可用，无法描述屏幕内容") } llm := p.sdk.LLM() req := &sdk.LLMCompletionRequest{ @@ -337,18 +356,60 @@ func (p *Plugin) describeScreen(dataURL string, provider string) string { if provider != "" { prev := llm.CurrentSource() if err := llm.SetSource(provider); err != nil { - log.Printf("[remotedevice] screensee set source %s: %v", provider, err) + // ★ 切源失败**不降级**：原来只打一行日志然后继续用当前源， + // 而当前源可能与调用方指定的完全不同 ⇒ 模型看到的是 + // 「另一个源的结果」，却挂在指定源名下。直接报错更诚实。 + return "", fmt.Errorf("screensee: 切换到指定视觉源 %s 失败: %w", provider, err) } else if prev != "" { defer func() { _ = llm.SetSource(prev) }() } } + // ★ 记录本次实际用的是哪个源：排查「为什么描述不对」时， + // 第一件要知道的就是它到底是哪个源在回答。 + usedSource := llm.CurrentSource() ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second) defer cancel() resp, err := llm.Chat(ctx, req) if err != nil { - return fmt.Sprintf("屏幕截图视觉描述失败: %v（当前模型可能不支持图像输入）", err) + log.Printf("[remotedevice] screensee 视觉描述失败 source=%s err=%v", usedSource, err) + // ★ 2026-10-05：模型名不被接受时，**就地降级到 AUTO 重试一次**。 + // + // 生产实测（13:51）：agent 传 provider=visionllm，而那个源的 + // `model: gpt-5.6-sol` 被 llmsproxy 拒了： + // + // model "gpt-5.6-sol" is not allowed for this key + // + // 根因不是「模型不支持图」，而是**那个 key 的 model scope 只有 AUTO** + // （/etc/llmsproxy/config.yaml 的 keys[homeagent].models = [AUTO]）。 + // 而同一个 key + base_url 下 `model: AUTO` 实测完全能看图。 + // + // ⇒ 显式模型名不可用时回 AUTO，比把错误抛给 agent 让它反复重试好。 + // 注意**不覆盖原错误**：两者都返回，由上层看到完整信息。 + if isModelNotAllowed(err) { + log.Printf("[remotedevice] screensee: 源 %s 的模型名不被接受，回退 AUTO 重试", usedSource) + if e2 := llm.SetSource("AUTO"); e2 == nil { + rctx, rcancel := context.WithTimeout(context.Background(), 120*time.Second) + defer rcancel() + if rresp, e3 := llm.Chat(rctx, req); e3 == nil && rresp != nil && + strings.TrimSpace(rresp.Content) != "" { + log.Printf("[remotedevice] screensee AUTO 回退成功 len=%d", len(rresp.Content)) + return rresp.Content, nil + } else { + log.Printf("[remotedevice] screensee AUTO 回退也失败: %v", e3) + } + } else { + log.Printf("[remotedevice] screensee AUTO 回退无法切源: %v", e2) + } + } + // 保留原始错误文本（那是唯一诊断线索），但以 error 形态上抛。 + return "", fmt.Errorf("屏幕截图视觉描述失败（视觉源 %s，model=%s）: %w", usedSource, currentModelOf(p.sdk.Settings(), usedSource), err) } - return resp.Content + if resp == nil || strings.TrimSpace(resp.Content) == "" { + // 空内容与「失败」对模型同样难以区分，不能静默当成结果。 + return "", fmt.Errorf("屏幕截图视觉描述失败（视觉源 %s）: 模型返回空内容", usedSource) + } + log.Printf("[remotedevice] screensee 视觉描述完成 source=%s len=%d", usedSource, len(resp.Content)) + return resp.Content, nil } func (p *Plugin) Stop() error { @@ -366,3 +427,41 @@ func (p *Plugin) Stop() error { } return nil } + +// isModelNotAllowed 判定错误是不是「这个 key 不许用该模型名」。 +// +// ★ 2026-10-05：llmsproxy 的原文是 +// +// model "gpt-5.6-sol" is not allowed for this key +// +// （internal/gateway/chat.go 的 model_not_allowed） +// +// 只认这一类：它与「模型不存在」「key 无效」的处理完全不同 —— +// 前者换个模型名/回 AUTO 就能成，后者要动配置或凭证。 +func isModelNotAllowed(err error) bool { + if err == nil { + return false + } + s := err.Error() + return strings.Contains(s, "is not allowed for this key") || + strings.Contains(s, "model_not_allowed") || + strings.Contains(s, "is not in this key's model scope") +} + +// currentModelOf 取某个源当前配置的模型名（只用于错误信息，便于定位）。 +// +// ★ 拿不到就返回 ""：**诊断信息缺失不该阻断主流程**， +// +// 所以这里不返回 error（内层的 fmt 已经带着原始错误文本了）。 +func currentModelOf(settings interface { + Get(string) (interface{}, error) +}, source string) string { + if settings == nil { + return "" + } + v, _ := settings.Get("core.llm.sources." + source + ".model") + if v == nil { + return "" + } + return fmt.Sprint(v) +} diff --git a/internal/plugins/remotedevice/screensee_truth_test.go b/internal/plugins/remotedevice/screensee_truth_test.go new file mode 100644 index 00000000..b280d281 --- /dev/null +++ b/internal/plugins/remotedevice/screensee_truth_test.go @@ -0,0 +1,341 @@ +package remotedevice + +import ( + "bytes" + "encoding/base64" + "encoding/json" + "errors" + "image" + "image/color" + "image/jpeg" + "image/png" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +// screensee 的两条教训（2026-10-05 生产日志实证） +// +// ## ① 视觉描述失败必须以 error 上抛，不能渲染成普通文本 +// +// 原实现：`return fmt.Sprintf("屏幕截图视觉描述失败: %v…", err)` +// 生产实测（13:51）： +// {"description":"屏幕截图视觉描述失败: api error 403: +// {\"error\":{\"message\":\"model \"gpt-5.6-sol\" is not allowed…"} +// ⇒ status=ok、只有 description 字段 ⇒ **失败与成功同形**。 +// agent 以为拿到了结果，于是换 provider 再试一次（又失败一次）。 +// +// 与同一天修掉的 MCP `isError` 丢失是**同一个病**。 +// +// ★ 教训：不能只断言「返回值里含错误文本」—— +// 那样「把错误写成 description」照样通过。必须断言**它从 error 通道出来**。 + +// TestSeeHandler_ErrorPropagatesAsError 钉住 seeHandler 的 error 不会被吞成文本。 +func TestSeeHandler_ErrorPropagatesAsError(t *testing.T) { + reg := NewRegistry() + dev := &devicectlDevice{reg: reg} + + // 模拟「视觉源 403」：handler 返回 error + dev.SetSeeHandler(func(dataURL, provider string) (string, error) { + return "", errFake403 + }) + + // 直接验契约：签名本身允许 error 通道 + var f func(string, string) (string, error) = dev.seeHandler + desc, err := f("data:image/jpeg;base64,AAAA", "") + if err == nil { + t.Fatal("handler 返回 error 时，调用方必须能拿到 error（否则又会被渲染成 description）") + } + if desc != "" { + t.Errorf("失败时不应同时返回描述文本，实际 %q", desc) + } + if !strings.Contains(err.Error(), "403") { + t.Errorf("错误信息应保留上游原文供诊断，实际 %v", err) + } +} + +// TestSeeHandler_SuccessStillWorks 钉住成功路径不受影响。 +func TestSeeHandler_SuccessStillWorks(t *testing.T) { + reg := NewRegistry() + dev := &devicectlDevice{reg: reg} + dev.SetSeeHandler(func(dataURL, provider string) (string, error) { + return "屏幕上是一个终端窗口", nil + }) + desc, err := dev.seeHandler("data:image/jpeg;base64,AAAA", "") + if err != nil || desc == "" { + t.Fatalf("成功路径被破坏：desc=%q err=%v", desc, err) + } +} + +// TestLogScreenseePayload_IdentifiesContent 钉住「回传内容可查证」。 +// +// ★ 这条对应那两次无从查证的「我收不到截图」： +// 服务端日志必须能回答「设备到底回传了什么」。 +// 现在记录 字节数 / magic / 像素尺寸 / base64 头 / SHA256 前缀。 + +func TestLogScreenseePayload_IdentifiesContent(t *testing.T) { + cases := []struct { + name string + data []byte + wantW int + wantH int + }{ + {"jpeg 8x4", makeJPEG(t, 8, 4), 8, 4}, + {"jpeg 1920x1080", makeJPEG(t, 1920, 1080), 1920, 1080}, + } + for _, c := range cases { + url := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(c.data) + logScreenseePayload("dev1", url) + } + // png（magic 走 png 分支，尺寸解不出 → 0 0，也应正常不 panic） + pngURL := "data:image/png;base64," + base64.StdEncoding.EncodeToString(makePNG(t, 3, 3)) + logScreenseePayload("dev1", pngURL) + // 空 + logScreenseePayload("dev1", "") + // 非法 base64（被截断的典型形态） + logScreenseePayload("dev1", "data:image/jpeg;base64,!!!not-base64!!!") +} + +// TestJpegSize 单独钉住 SOF 解析：尺寸是判断「图是不是真的截到了」的关键信号。 +func TestJpegSize(t *testing.T) { + for _, dim := range [][2]int{{1, 1}, {640, 480}, {1920, 1080}, {2560, 1440}} { + b := makeJPEG(t, dim[0], dim[1]) + w, h := jpegSize(b) + if w != dim[0] || h != dim[1] { + t.Errorf("%dx%d: jpegSize 给 %dx%d", dim[0], dim[1], w, h) + } + } + // 非 jpeg 一律 0,0，且不得 panic + if w, h := jpegSize([]byte("not an image")); w != 0 || h != 0 { + t.Errorf("非 jpeg 应给 0,0，实际 %dx%d", w, h) + } + if w, h := jpegSize(nil); w != 0 || h != 0 { + t.Errorf("nil 应给 0,0，实际 %dx%d", w, h) + } + // ★ 截断的 jpeg（真实故障形态）：不得 panic，且不该报出假的尺寸 + trunc := makeJPEG(t, 100, 100) + if w, _ := jpegSize(trunc[:20]); w != 0 { + t.Errorf("截断的 jpeg 不应报出宽度，实际 %d", w) + } +} + +func TestMagicName(t *testing.T) { + if got := magicName(makeJPEG(t, 2, 2)); got != "jpeg" { + t.Errorf("jpeg 识别错: %s", got) + } + if got := magicName(makePNG(t, 2, 2)); got != "png" { + t.Errorf("png 识别错: %s", got) + } + if got := magicName(nil); got != "empty" { + t.Errorf("nil 应为 empty，实际 %s", got) + } + if got := magicName([]byte("garbage")); got != "unknown" { + t.Errorf("垃圾数据应为 unknown，实际 %s", got) + } +} + +func makeJPEG(t *testing.T, w, h int) []byte { + t.Helper() + img := image.NewRGBA(image.Rect(0, 0, w, h)) + for y := 0; y < h; y++ { + for x := 0; x < w; x++ { + img.Set(x, y, color.RGBA{R: uint8(x % 256), G: uint8(y % 256), B: 128, A: 255}) + } + } + var buf bytes.Buffer + if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: 80}); err != nil { + t.Fatal(err) + } + return buf.Bytes() +} + +func makePNG(t *testing.T, w, h int) []byte { + t.Helper() + img := image.NewRGBA(image.Rect(0, 0, w, h)) + var buf bytes.Buffer + if err := png.Encode(&buf, img); err != nil { + t.Fatal(err) + } + return buf.Bytes() +} + +var errFake403 = &fakeErr{"api error 403: model \"gpt-5.6-sol\" is not allowed for this key"} + +type fakeErr struct{ s string } + +func (e *fakeErr) Error() string { return e.s } + +// ===== 以下走完整链路（真 WS + 真 registry），盯住「失败从哪个通道出来」 ===== + +// TestScreenseE2E_VisualFailureIsErrorNotDescription 是本次修改的**核心门禁**。 +// +// ★ 为什么必须走完整链路： +// +// 我第一版判据只测 `seeHandler` 的签名（能不能返回 error）—— +// 把调用点的 `if err != nil` 改成「把错误渲染成 description 文本」时， +// **判据全绿**。因为被测的是「签名允许 error」， +// 而真正的缺陷在「调用点有没有真的走 error 通道」。 +// ⇒ 判据必须驱动 `dev.Execute("screensee", …)` 走完一整圈。 +// +// 生产症状（2026-10-05 13:51）： +// +// {"description":"屏幕截图视觉描述失败: api error 403: …"} ← status=ok +// +// 修好后应当是：err != nil，且结果里**没有** description 字段。 +func TestScreenseE2E_VisualFailureIsErrorNotDescription(t *testing.T) { + reg := NewRegistry() + token := "tk-visual-fail" + reg.SetAcceptToken(func(p string) bool { return p == token }) + + dev := &devicectlDevice{reg: reg} + // 视觉源返回 403（MCP/screensee 生产上真实发生过） + dev.SetSeeHandler(func(dataURL, provider string) (string, error) { + return "", errFake403 + }) + + srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS)) + defer srv.Close() + cli := dialTestWS(t, srv.URL, token) + defer cli.close() + + // 设备必须先 hello+bind 才会进 registry（否则 Execute 报「设备不存在」） + cli.sendText([]byte(`{"op":"hello","device":{"device_id":"vf-dev","name":"视觉失败机","kind":"computer","caps":["screensee"]}}`)) + cli.readHelloAckAndBind(t, token) + + go func() { + for { + op, payload, err := cli.readMsg() + if err != nil || op != 0x1 { + return + } + var msg map[string]interface{} + if json.Unmarshal(payload, &msg) != nil { + continue + } + if msg["op"] == "cmd" && msg["command"] == "screensee" { + reqID, _ := msg["req_id"].(string) + img := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(makeJPEG(t, 64, 48)) + cli.sendText(mustJSON(map[string]interface{}{ + "op": "cmd_result", "req_id": reqID, "device_id": "vf-dev", + "status": "ok", "output": img, + })) + } + } + }() + + res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vf-dev"}) + + // ★ 必须报错 + if err == nil { + t.Fatalf("视觉描述失败必须以 error 上抛，实际 res=%v —— "+ + "渲染成 description 会让 agent 以为拿到了结果并反复重试", res) + } + // ★ 错误信息要保留上游原文（那是唯一诊断线索） + if !strings.Contains(err.Error(), "403") { + t.Errorf("错误信息应保留上游原文，实际: %v", err) + } + // ★ 结果里绝不能有 description 字段 + if m, ok := res.(map[string]interface{}); ok { + if _, has := m["description"]; has { + t.Errorf("失败时不得返回 description 字段（那是本次要修的缺陷），实际: %v", m) + } + } +} + +// TestScreenseE2E_SuccessReturnsDescription 钉住成功路径没被改坏。 +func TestScreenseE2E_SuccessReturnsDescription(t *testing.T) { + reg := NewRegistry() + token := "tk-visual-ok" + reg.SetAcceptToken(func(p string) bool { return p == token }) + + dev := &devicectlDevice{reg: reg} + var gotLen int + dev.SetSeeHandler(func(dataURL, provider string) (string, error) { + gotLen = len(dataURL) + return "屏幕上是一个终端窗口", nil + }) + + srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS)) + defer srv.Close() + cli := dialTestWS(t, srv.URL, token) + defer cli.close() + + cli.sendText([]byte(`{"op":"hello","device":{"device_id":"vo-dev","name":"视觉成功机","kind":"computer","caps":["screensee"]}}`)) + cli.readHelloAckAndBind(t, token) + + go func() { + for { + op, payload, err := cli.readMsg() + if err != nil || op != 0x1 { + return + } + var msg map[string]interface{} + if json.Unmarshal(payload, &msg) != nil { + continue + } + if msg["op"] == "cmd" && msg["command"] == "screensee" { + reqID, _ := msg["req_id"].(string) + img := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(makeJPEG(t, 64, 48)) + cli.sendText(mustJSON(map[string]interface{}{ + "op": "cmd_result", "req_id": reqID, "device_id": "vo-dev", + "status": "ok", "output": img, + })) + } + } + }() + + res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vo-dev"}) + if err != nil { + t.Fatalf("成功路径被破坏: %v", err) + } + m, ok := res.(map[string]interface{}) + if !ok { + t.Fatalf("返回类型变了: %T", res) + } + if m["description"] != "屏幕上是一个终端窗口" { + t.Errorf("description 不对: %v", m["description"]) + } + if gotLen == 0 { + t.Error("handler 没收到 dataURL") + } +} + +// TestIsModelNotAllowed 钉住「模型名不被接受」的识别。 +// +// ★ 这是 2026-10-05 生产那条 403 的判定入口： +// +// model "gpt-5.6-sol" is not allowed for this key +// +// 根因不是「模型不支持图」，而是**那个 key 的 model scope 只有 AUTO** +// （/etc/llmsproxy/config.yaml 的 keys[homeagent].models = [AUTO]）。 +// 而同一 key + base_url 下 model=AUTO 实测完全能看图 ⇒ 该回退而不是报错。 +func TestIsModelNotAllowed(t *testing.T) { + // llmsproxy 的三种原文（internal/gateway/chat.go） + yes := []string{ + `model "gpt-5.6-sol" is not allowed for this key`, + `{"error":{"type":"model_not_allowed","message":"model \"x\" is not allowed for this key"}}`, + `model "x" is not in this key's model scope, so it cannot use AUTO`, + } + for _, s := range yes { + if !isModelNotAllowed(errors.New(s)) { + t.Errorf("应识别为「模型名不被接受」: %s", s) + } + } + // ★ 必须**不**把其它错误误判成这一类 —— 那会触发错误的 AUTO 回退。 + no := []string{ + `invalid gateway api key`, + `api error 401: Unauthorized`, + `read: connection reset by peer`, + `context deadline exceeded`, + ``, // nil 情形另行覆盖 + } + for _, s := range no { + if isModelNotAllowed(errors.New(s)) { + t.Errorf("不应被识别为「模型名不被接受」（会误触发 AUTO 回退）: %s", s) + } + } + if isModelNotAllowed(nil) { + t.Error("nil 不应被判为模型名问题") + } +} From a7d048c92289f747494e4717b3e8e3ba09c224e5 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 6 Oct 2026 09:16:15 +0800 Subject: [PATCH 08/13] =?UTF-8?q?feat(remotedevice):=20screensee=20?= =?UTF-8?q?=E8=90=BD=E7=9B=98=E5=8C=96=EF=BC=8C=E5=9B=9E=E8=B7=AF=E5=BE=84?= =?UTF-8?q?=E8=80=8C=E9=9D=9E=E8=87=AA=E5=8A=A8=E9=80=81=E6=A8=A1=E5=9E=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 为什么 原行为把截图的 base64 直接送去视觉模型自动描述。三个问题： 1. **上下文成本**：96KB 截图 ≈ 13 万 token 的内联 base64 2. **源不可控**：生产实证 AUTO 把大图路由到不支持视觉的源，模型回 「没有收到截图」——而我们无法区分「图没到」与「模型看不了」 3. **agent 无法决策**：不知道图存不存在，也就不知道该 describe 还是该 ocr ## 现在 截图落盘 → 回 {file,mime,size,sha256,width,height} → agent 显式调 describe_image(path=…)/ocr_image(path=…)。 需要哪个能力由它自己判断，provider 参数也可控。 工具描述同步改写，明说「本工具不会自动描述任何内容，两步缺一不可」—— 否则模型会以为拿到 file 就等于看到了画面。 ## 实现 - `Registry.SaveInlineMedia(name, payload, mimeHint)`： 解 data URL / 裸 base64 → 落盘 → 回可核对的元信息 - 文件名用**内容摘要**后缀（`_.`）： 截屏/录像会被反复抓取，用 reqID 命名会把同一张图存成多份， 用固定名则不同内容互相覆盖 —— 摘要两个问题都避免 - `decodeInlineMedia` / `imageDimensions`：JPEG SOFn 与 PNG IHDR 解尺寸，不解码全图；认不出的格式**省略字段而非填 0** - 落盘失败当**工具失败**上抛，不静默退回内联： 图已在手上却拿不到路径，agent 既没有描述也没有可查证产物 - 旧路径保留在 `auto_describe=true`（调试用） 顺带把 cmd_data_end 的媒体落盘逻辑也换成同一个方法（原来内联了 一份 MkdirAll+WriteFile 的副本）。 ## 判据 新增 inline_media_test.go，六个判据经四个变异自证会红： - 变异 A：写入截半的字节但元信息照填 → 红（只查「文件存在」会放过） - 变异 B：尺寸写死 0 占位 → 红（元信息「看起来有」但不可信） - 变异 C：sha256 换成假的 → 红 - 变异 D：未配置 mediaDir 时静默降级 → 红 ★ 变异 C 第一次跑出「无输出」，查下来是**编译失败不是被杀** （`sum`/`hex` 变成未使用）。这正是本项目记过的坑： 编译失败 ≠ 被杀。改写成能编译的注入后确认被杀。 ## 验证 - go build ./... / go vet / go test ./internal/... 全绿 - go test -race remotedevice + multimodal 无数据竞争 - 旧判据按新契约更新时保留原意： TestScreenseE2E_SuccessReturnsDescription 现在同时验两条路径 （默认不出 description 且不调 handler；auto_describe 才出） - 部署后：39 插件加载、0 panic/fatal、plugin=multimodal - graph.db integrity ok，blocks 2787 / relations 980 未动 - 快照 /home/newqqagent/memory/pre-screensee-persist-20261006-091536/ Co-Authored-By: Claude Opus 4.8 (1M context) --- internal/plugins/remotedevice/binary_test.go | 17 +- internal/plugins/remotedevice/device.go | 88 ++++++-- .../plugins/remotedevice/inline_media_test.go | 194 ++++++++++++++++++ internal/plugins/remotedevice/registry.go | 165 +++++++++++++-- .../remotedevice/screensee_truth_test.go | 36 +++- 5 files changed, 460 insertions(+), 40 deletions(-) create mode 100644 internal/plugins/remotedevice/inline_media_test.go diff --git a/internal/plugins/remotedevice/binary_test.go b/internal/plugins/remotedevice/binary_test.go index 19cdeb29..db0d9010 100644 --- a/internal/plugins/remotedevice/binary_test.go +++ b/internal/plugins/remotedevice/binary_test.go @@ -298,8 +298,15 @@ func TestWSBinaryMediaToFile(t *testing.T) { if _, hasB64 := res["data_base64"]; hasB64 { t.Fatal("data_base64 should be absent in file mode") } - if want := filepath.Join(mediaDir, "req-file-1.mp4"); fp != want { - t.Fatalf("file path = %s, want %s", fp, want) + // ★ 2026-10-06：文件名含内容摘要（SaveInlineMedia）。 + // 截屏/录像这类会被反复抓取的媒体，用 reqID 命名会把同内容存成多份、 + // 不同内容却可能覆盖 —— 摘要后缀两���都避免。 + if filepath.Dir(fp) != mediaDir { + t.Fatalf("file 应落在媒体目录 %s，实际 %s", mediaDir, fp) + } + base := filepath.Base(fp) + if !strings.HasPrefix(base, "req-file-1_") || !strings.HasSuffix(base, ".mp4") { + t.Fatalf("文件名应为 req-file-1_.mp4，实际 %s", base) } got, err := os.ReadFile(fp) if err != nil { @@ -402,6 +409,7 @@ func TestPushDataOfflineDevice(t *testing.T) { func TestScreenseeEndToEnd(t *testing.T) { reg := NewRegistry() + reg.SetMediaDir(t.TempDir()) token := "test-token-see" reg.SetAcceptToken(func(provided string) bool { return provided == token }) @@ -449,7 +457,10 @@ func TestScreenseeEndToEnd(t *testing.T) { }() // agent 调用 screensee - res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "see-dev"}) + // ★ 2026-10-06：默认走落盘 + 回路径；旧的自���描述路径用 auto_describe=true。 + res, err := dev.Execute("screensee", map[string]interface{}{ + "device_id": "see-dev", "auto_describe": true, + }) if err != nil { t.Fatalf("screensee: %v", err) } diff --git a/internal/plugins/remotedevice/device.go b/internal/plugins/remotedevice/device.go index c9760151..178b3f5a 100644 --- a/internal/plugins/remotedevice/device.go +++ b/internal/plugins/remotedevice/device.go @@ -102,15 +102,22 @@ func (d *devicectlDevice) Tools() []agentIO.ToolDef { }, { Name: "screensee", - Description: "查看一台已授权设备的屏幕当前画面（截屏回传）。" + - "与 screensue（向用户屏幕显示内容）配对：screensue 是给用户看，screensee 是你看。" + - "返回屏幕截图的自动视觉描述；如需读取屏上文字可接着用 ocr_image。" + + Description: "截取一台已授权设备的当前屏幕画面。\n" + + "与 screensue（向用户屏幕显示内容）配对：screensue 是给用户看，screensee 是你看。\n" + + "★★ 返回的是截图的**落盘路径**与元信息（file/mime/size/sha256/width/height），" + + "**不含画面内容**。要看画面或读屏上文字，必须接着调用：" + + "describe_image(path=) 看画面，或 ocr_image(path=) 读文字。" + + "两步缺一不可——本工具不会自动描述任何东西。\n" + "需要 device_id（来自 devicedetect）。设备必须已授权且在线。", Parameters: map[string]interface{}{ "type": "object", "properties": map[string]interface{}{ "device_id": map[string]interface{}{"type": "string", "description": "目标设备 ID"}, - "provider": map[string]interface{}{"type": "string", "description": "可选：用于视觉描述的 LLM 源名称，不填则使用默认模型"}, + "auto_describe": map[string]interface{}{ + "type": "boolean", + "description": "可选（默认 false）：true 时跳过落盘、直接用视觉模型描述" + + "（仅调试用：大截图约 13 万 token，且视觉源不可控）", + }, }, "required": []interface{}{"device_id"}, }, @@ -372,7 +379,11 @@ func (d *devicectlDevice) SetSeeHandler(fn func(dataURL string, provider string) } // screensee 实现 screensee：向设备下发 homeagent-screensee 截屏命令， -// 等待回传 jpeg base64，交给 seeHandler（agent 核心）做视觉描述。 +// screensee 截取设备屏幕。 +// +// ★★ 2026-10-06：不再自动送视觉模型，改为**落盘 + 回路径**， +// 由 agent 显式调 describe_image(path=…)/ocr_image(path=…)。见函数体注释。 +// args: device_id（必填）、provider（仅 auto_describe 时用）、auto_describe（调试用，默认 false）。 func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, error) { id, _ := args["device_id"].(string) provider, _ := args["provider"].(string) @@ -420,27 +431,66 @@ func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, e // · 前若干字节的 base64 片段 + SHA256 前 16 hex // ⇒ 「回传的是不是同一张图」「是不是被截断了」一眼可判。 logScreenseePayload(id, output) - // 设备端回传 data URL（data:image/jpeg;base64,...）或裸 base64 - if !strings.HasPrefix(output, "data:") { - output = "data:image/jpeg;base64," + output + // ★★ 2026-10-06：截图先**落盘**，再把路径交给 agent。 + // + // 原行为：把 base64 直接送去视觉模型自动描述。三个问题： + // ① 96KB 截图 ≈ 13 万 token 的内联 base64； + // ② 自动挑源不可控 —— 生产实证：AUTO 把大图路由到不支持视觉的源， + // 模型回「没有收到截图」，而我们无法区分「图没到」与「模型看不了」； + // ③ agent 不知道图存不存在，也就无法决定用 describe 还是 ocr。 + // + // 现在：落盘 + 回元信息，agent 显式调 describe_image(path=…)/ocr_image(path=…) + // —— 需要哪个能力由它自己判断，且 provider 参数可控。 + // + // 落盘失败当**工具失败**上抛（不静默退回内联）：图已经在手上却拿不到路径， + // agent 会既没有描述也没有可查证产物，只剩一句「失败」。 + // + // auto_describe=true 保留旧路径（调试用）。 + if auto, _ := args["auto_describe"].(bool); auto && d.seeHandler != nil { + if !strings.HasPrefix(output, "data:") { + output = "data:image/jpeg;base64," + output + } + desc, err := d.seeHandler(output, provider) + if err != nil { + // ★ 视觉描述失败 ⇒ 工具失败（不是「返回一段说明」）。 + // 生产实证：403 被塞进 description 且 status=ok， + // agent 以为拿到了结果，于是换 provider 又试一次（再失败一次）。 + d.reg.SaveResult(reqID, map[string]interface{}{ + "error": err.Error(), + "device": id, + "has_image": true, // 截图确实拿到了：区分「设备没回传」与「模型看不了」 + }) + return nil, fmt.Errorf("设备已回传截图，但视觉描述失败: %w", err) + } + return map[string]interface{}{"description": desc}, nil } - d.reg.SaveResult(reqID, res) - if d.seeHandler == nil { - return map[string]interface{}{"image_data_url": output, "note": "无视觉描述处理器，仅返回原始图像数据"}, nil - } - desc, err := d.seeHandler(output, provider) + + meta, err := d.reg.SaveInlineMedia("screensee_"+reqID, output, "image/jpeg") if err != nil { - // ★ 视觉描述失败 ⇒ 工具失败（不是「返回一段说明」）。 - // 生产实证：403 被塞进 description 且 status=ok， - // agent 以为拿到了结果，于是换 provider 又试一次（再失败一次）。 d.reg.SaveResult(reqID, map[string]interface{}{ "error": err.Error(), "device": id, - "has_image": true, // 截图确实拿到了：区分「设备没回传」与「模型看不了」 + "has_image": true, // 图确实拿到了，只是没落盘 }) - return nil, fmt.Errorf("设备已回传截图，但视觉描述失败: %w", err) + return nil, fmt.Errorf("截图已回传但落盘失败（无法交付给多模态工具）: %w", err) } - return map[string]interface{}{"description": desc}, nil + d.reg.SaveResult(reqID, meta) + + out := map[string]interface{}{ + "file": meta["file"], + "mime": meta["mime"], + "size": meta["size"], + "sha256": meta["sha256"], + "device": id, + "next_step": "如需查看画面，请调用 describe_image 并传入 path 参数；需读图中的文字请用 ocr_image。", + } + if w, ok := meta["width"]; ok { + out["width"] = w + } + if h, ok := meta["height"]; ok { + out["height"] = h + } + return out, nil } // computeruse 实现 computeruse：向设备下发鼠标/键盘控制命令。 diff --git a/internal/plugins/remotedevice/inline_media_test.go b/internal/plugins/remotedevice/inline_media_test.go new file mode 100644 index 00000000..f35fa461 --- /dev/null +++ b/internal/plugins/remotedevice/inline_media_test.go @@ -0,0 +1,194 @@ +package remotedevice + +import ( + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "image" + "image/color" + "image/jpeg" + "os" + "path/filepath" + "strings" + "testing" +) + +// screensee 落盘化（2026-10-06） +// +// ## 为什么要落盘 +// +// 原行为是把 96KB 截图的 base64 直接送去视觉模型： +// · 约 13 万 token 的内联载荷 +// · 自动挑源不可控（生产实证：AUTO 路由到不支持视觉的源，模型说「没收到图」） +// · agent 不知道图存不存在，无法决定该 describe 还是该 ocr +// +// 现在：截图落盘 → 回 {file,mime,size,sha256,width,height} → +// agent 显式调 describe_image(path=…) / ocr_image(path=…) +// +// 这些判据钉住「真的落盘了」与「元信息可信」——后者是 agent 决定 +// 下一步的唯一依据，写错了它就会去读一个不存在的文件。 + +func jpegBytes(t *testing.T, w, h int) []byte { + t.Helper() + img := image.NewRGBA(image.Rect(0, 0, w, h)) + for y := 0; y < h; y++ { + for x := 0; x < w; x++ { + img.Set(x, y, color.RGBA{R: uint8(x % 256), G: uint8(y % 256), B: 0x40, A: 0xff}) + } + } + var buf strings.Builder + if err := jpeg.Encode(&buf, img, nil); err != nil { + t.Fatal(err) + } + return []byte(buf.String()) +} + +// ---- 落盘：文件存在且字节逐字节一致 ---- + +func TestSaveInlineMedia_DataURLWritesExactBytes(t *testing.T) { + reg := NewRegistry() + reg.SetMediaDir(t.TempDir()) + + raw := jpegBytes(t, 64, 48) + meta, err := reg.SaveInlineMedia("shot", "data:image/jpeg;base64,"+base64.StdEncoding.EncodeToString(raw), "") + if err != nil { + t.Fatalf("落盘应成功: %v", err) + } + fp, _ := meta["file"].(string) + if fp == "" { + t.Fatalf("meta 必须含 file，实际: %v", meta) + } + got, err := os.ReadFile(fp) + if err != nil { + t.Fatalf("file 应可读: %v", err) + } + // ★ 逐字节比对：只查「文件存在」会放过内容被截断/转码的情况。 + if string(got) != string(raw) { + t.Errorf("落盘字节与原图不一致: 写入 %d 字节, 原图 %d 字节", len(got), len(raw)) + } + if meta["size"] != len(raw) { + t.Errorf("meta.size=%v，实际 %d", meta["size"], len(raw)) + } +} + +func TestSaveInlineMedia_BareBase64AlsoWorks(t *testing.T) { + reg := NewRegistry() + reg.SetMediaDir(t.TempDir()) + raw := jpegBytes(t, 32, 32) + // 设备端有时只回裸 base64（无 data: 前缀） + meta, err := reg.SaveInlineMedia("bare", base64.StdEncoding.EncodeToString(raw), "image/jpeg") + if err != nil { + t.Fatalf("裸 base64 应可落盘: %v", err) + } + got, _ := os.ReadFile(meta["file"].(string)) + if string(got) != string(raw) { + t.Error("裸 base64 落盘字节不一致") + } + if meta["mime"] != "image/jpeg" { + t.Errorf("mimeHint 未生效: %v", meta["mime"]) + } +} + +// ---- 元信息可信：agent 全靠它决定下一步 ---- + +func TestSaveInlineMedia_MetaIsVerifiable(t *testing.T) { + reg := NewRegistry() + reg.SetMediaDir(t.TempDir()) + raw := jpegBytes(t, 128, 96) + meta, err := reg.SaveInlineMedia("meta", base64.StdEncoding.EncodeToString(raw), "image/jpeg") + if err != nil { + t.Fatal(err) + } + // sha256 必须与文件内容对得上（不是随机的/占位的） + got, _ := os.ReadFile(meta["file"].(string)) + sum := sha256Hex(got) + if meta["sha256"] != sum { + t.Errorf("sha256 与落盘内容不符: meta=%v 实际=%v", meta["sha256"], sum) + } + // 尺寸必须是真解出来的，不是 0 或缺省 + if meta["width"] != 128 || meta["height"] != 96 { + t.Errorf("尺寸应解出 128x96，实际 %vx%v", meta["width"], meta["height"]) + } +} + +// TestSaveInlineMedia_ContentAddressedName 钉住文件名含内容摘要。 +// +// ★ 为什么要摘要后缀：截屏/录像会被反复抓取。用 reqID 命名会把同一张图 +// +// 存成多份；用固定名则不同内容互相覆盖。摘要两个问题都避免。 +func TestSaveInlineMedia_ContentAddressedName(t *testing.T) { + reg := NewRegistry() + reg.SetMediaDir(t.TempDir()) + raw := jpegBytes(t, 16, 16) + + m1, err := reg.SaveInlineMedia("req-1", base64.StdEncoding.EncodeToString(raw), "image/jpeg") + if err != nil { + t.Fatal(err) + } + // 同内容不同 name ⇒ 摘要部分相同（内容寻址的语义） + m2, err := reg.SaveInlineMedia("req-2", base64.StdEncoding.EncodeToString(raw), "image/jpeg") + if err != nil { + t.Fatal(err) + } + if filepath.Base(m1["file"].(string)) == filepath.Base(m2["file"].(string)) { + t.Error("不同 name 的同内容落盘，文件名不应完全相同（name 前缀不同）") + } + if !strings.HasPrefix(filepath.Base(m1["file"].(string)), "req-1_") { + t.Errorf("文件名应保留 name 前缀，实际 %s", filepath.Base(m1["file"].(string))) + } + if !strings.HasSuffix(m1["file"].(string), ".jpg") { + t.Errorf("应按 mime 推出 .jpg 后缀，实际 %s", m1["file"]) + } +} + +// ---- 失败必须报错，不得静默降级 ---- + +func TestSaveInlineMedia_FailuresAreExplicit(t *testing.T) { + reg := NewRegistry() + + // 未配置落盘目录 + if _, err := reg.SaveInlineMedia("x", "data:image/jpeg;base64,AAAA", ""); err == nil { + t.Error("未配置 mediaDir 时必须报错（静默降级会让 agent 拿不到路径也无从排查）") + } + + reg.SetMediaDir(t.TempDir()) + for name, payload := range map[string]string{ + "空载荷": "", + "只有空白": " ", + "非法base64": "data:image/jpeg;base64,!!!not-base64!!!", + "缺逗号": "data:image/jpeg;base64", + "解出空内容": "data:image/jpeg;base64,", + } { + if _, err := reg.SaveInlineMedia(name, payload, ""); err == nil { + t.Errorf("%s 应报错，实际返回成功", name) + } + } +} + +// ---- 尺寸解析：不认识的格式省略字段，而不是填 0 ---- + +func TestImageDimensions(t *testing.T) { + // JPEG + if w, h, ok := imageDimensions(jpegBytes(t, 200, 150)); !ok || w != 200 || h != 150 { + t.Errorf("JPEG 尺寸解析错: %dx%d ok=%v", w, h, ok) + } + // PNG（存一个真 PNG 头） + png := []byte{0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 13, + 'I', 'H', 'D', 'R', 0, 0, 1, 44, // 300 + 0, 0, 1, 0x90, // 400 + 8, 6, 0, 0, 0} + if w, h, ok := imageDimensions(png); !ok || w != 300 || h != 400 { + t.Errorf("PNG 尺寸解析错: %dx%d ok=%v", w, h, ok) + } + // 认不出的格式 ⇒ ok=false，**不得**返回 0,0,true + if _, _, ok := imageDimensions([]byte("not an image at all")); ok { + t.Error("非图片应返回 ok=false") + } + if _, _, ok := imageDimensions(nil); ok { + t.Error("空输入应返回 ok=false") + } +} +func sha256Hex(b []byte) string { + sum := sha256.Sum256(b) + return hex.EncodeToString(sum[:]) +} diff --git a/internal/plugins/remotedevice/registry.go b/internal/plugins/remotedevice/registry.go index 28a46f76..e2e6421d 100644 --- a/internal/plugins/remotedevice/registry.go +++ b/internal/plugins/remotedevice/registry.go @@ -2,9 +2,12 @@ package remotedevice import ( "bufio" + "bytes" "crypto/sha1" // RFC6455 规定 Sec-WebSocket-Accept 必须用 SHA-1，勿改 + "crypto/sha256" "encoding/base64" "encoding/binary" + "encoding/hex" "encoding/json" "fmt" "io" @@ -155,6 +158,145 @@ func (r *Registry) SetMediaDir(dir string) { r.mu.Unlock() } +// SaveInlineMedia 把一段内联媒体（data URL 或裸 base64）落盘，返回文件元信息。 +// +// ★ 为什么抽出来（2026-10-06）：screensee 之前只把 base64 塞给视觉模型， +// 带来两个问题—— +// +// ① **上下文成本**：96KB 的截图 = 约 13 万 token 的内联 base64； +// ② **诊断不了**：模型说「没收到图片」时，服务端无法证明图到底在不在 +// （只能靠日志里手写的元信息）。 +// +// 落盘 + 回路径后，agent 可以**显式**调 describe_image(path=…)， +// 且「图存在」这件事有可查证的落盘产物。 +// +// 返回 meta（含 file/mime/size/sha256/width/height）；mediaDir 为空或 +// 写入失败时返回 error —— **不静默降级成内联**：调用方要据此决定是否 +// 退回旧行为，而静默回退正是「失败伪装成成功」的源头。 +func (r *Registry) SaveInlineMedia(name, payload, mimeHint string) (map[string]interface{}, error) { + r.mu.RLock() + dir := r.mediaDir + r.mu.RUnlock() + if dir == "" { + return nil, fmt.Errorf("未配置媒体落盘目录（SetMediaDir 未调用）") + } + if err := os.MkdirAll(dir, 0755); err != nil { + return nil, fmt.Errorf("创建媒体目录 %s 失败: %w", dir, err) + } + + raw, mt, err := decodeInlineMedia(payload, mimeHint) + if err != nil { + return nil, err + } + if len(raw) == 0 { + return nil, fmt.Errorf("媒体内容为空（%s）", name) + } + + // 文件名用内容摘要：同一张图重复截屏不堆文件，不同图不覆盖。 + sum := sha256.Sum256(raw) + digest := hex.EncodeToString(sum[:]) + ext := mediaExt(mt, "") + if ext == "" { + ext = ".bin" + } + fp := filepath.Join(dir, name+"_"+digest[:16]+ext) + if err := os.WriteFile(fp, raw, 0o644); err != nil { + return nil, fmt.Errorf("写媒体文件 %s 失败: %w", fp, err) + } + + meta := map[string]interface{}{ + "file": fp, + "mime": mt, + "size": len(raw), + "sha256": digest, + } + if w, h, ok := imageDimensions(raw); ok { + meta["width"] = w + meta["height"] = h + } + return meta, nil +} + +// decodeInlineMedia 把 data URL 或裸 base64 解成字节 + mime。 +func decodeInlineMedia(payload, mimeHint string) ([]byte, string, error) { + p := strings.TrimSpace(payload) + if p == "" { + return nil, "", fmt.Errorf("媒体载荷为空") + } + mime := mimeHint + if strings.HasPrefix(p, "data:") { + // data:[][;base64], + comma := strings.IndexByte(p, ',') + if comma < 0 { + return nil, "", fmt.Errorf("data URL 缺少逗号分隔符") + } + metaPart := p[len("data:"):comma] + if strings.Contains(metaPart, "base64") { + if i := strings.IndexByte(metaPart, ';'); i >= 0 { + mime = metaPart[:i] + } else { + mime = metaPart + } + } else if mime == "" { + mime = metaPart + } + p = p[comma+1:] + } + if mime == "" { + mime = "image/jpeg" + } + raw, err := base64.StdEncoding.DecodeString(p) + if err != nil { + // 有些设备会塞换行/URL-safe 变体 + raw2, err2 := base64.RawStdEncoding.DecodeString(strings.TrimSpace(strings.NewReplacer("\n", "", "\r", "").Replace(p))) + if err2 != nil { + return nil, "", fmt.Errorf("base64 解码失败: %w", err) + } + raw = raw2 + } + return raw, mime, nil +} + +// imageDimensions 从图片头部解出像素尺寸，不解码全图。 +// 不认识的格式返回 ok=false —— 调用方据此省略字段，而不是填 0。 +func imageDimensions(raw []byte) (int, int, bool) { + if len(raw) < 24 { + return 0, 0, false + } + // PNG: \x89PNG\r\n\x1a\n + IHDR(width,height BE32 @16,20) + if bytes.HasPrefix(raw, []byte{0x89, 'P', 'N', 'G'}) { + return int(raw[16])<<24 | int(raw[17])<<16 | int(raw[18])<<8 | int(raw[19]), + int(raw[20])<<24 | int(raw[21])<<16 | int(raw[22])<<8 | int(raw[23]), true + } + // JPEG: 扫 SOFn 段 + if bytes.HasPrefix(raw, []byte{0xFF, 0xD8}) { + for i := 2; i+9 < len(raw); { + if raw[i] != 0xFF { + i++ + continue + } + marker := raw[i+1] + // SOF0..SOF3, SOF5..SOF7, SOF9..SOF11, SOF13..SOF15 + if marker >= 0xC0 && marker <= 0xCF && marker != 0xC4 && marker != 0xC8 && marker != 0xCC { + h := int(raw[i+5])<<8 | int(raw[i+6]) + w := int(raw[i+7])<<8 | int(raw[i+8]) + if w > 0 && h > 0 { + return w, h, true + } + } + if i+3 >= len(raw) { + break + } + segLen := int(raw[i+2])<<8 | int(raw[i+3]) + if segLen < 2 { + break + } + i += 2 + segLen + } + } + return 0, 0, false +} + // mediaExt 按 mime/kind 推断扩展名。 func mediaExt(mime, kind string) string { m := strings.ToLower(mime) @@ -913,22 +1055,17 @@ func (r *Registry) handleWS(conn net.Conn, rw *bufio.ReadWriter, handshakeAuthor // 媒体落盘模式：写入 /.，cmd_result 返回 file 路径。 // 大体积 base64 内联会撑爆 LLM 上下文（一段 10s 录像即数 MB）， // agent 应拿路径后用 files/describe_image/ocr 等工具消费。 - r.mu.RLock() - mediaDir := r.mediaDir - r.mu.RUnlock() - if mediaDir != "" { - if err := os.MkdirAll(mediaDir, 0755); err == nil { - fp := filepath.Join(mediaDir, reqID+mediaExt(acc.mime, acc.kind)) - if werr := os.WriteFile(fp, data, 0644); werr == nil { - res["file"] = fp - } else { - log.Printf("[remotedevice] media write %s: %v", fp, werr) - } - } else { - log.Printf("[remotedevice] media dir %s: %v", mediaDir, err) + if meta, err := r.SaveInlineMedia(reqID, base64.StdEncoding.EncodeToString(data), acc.mime); err == nil { + for k, v := range meta { + res[k] = v } + } else { + log.Printf("[remotedevice] media save %s: %v", reqID, err) } - // 未配置落盘目录时保持旧行为：base64 内联返回（小体积数据仍可用） + // 未落盘时保持旧行为：base64 内联返回（小体积数据仍可用）。 + // ★ 这里仍内联是可接受的退化——上面的 log 已记录原因。 + // screensee 那边不同：它把落盘失败当**工具失败**上抛， + // 因为「拿到了图却没落盘」会让 agent 拿不到路径也无从排查。 if _, hasFile := res["file"]; !hasFile { res["data_base64"] = base64.StdEncoding.EncodeToString(data) } diff --git a/internal/plugins/remotedevice/screensee_truth_test.go b/internal/plugins/remotedevice/screensee_truth_test.go index b280d281..1109f692 100644 --- a/internal/plugins/remotedevice/screensee_truth_test.go +++ b/internal/plugins/remotedevice/screensee_truth_test.go @@ -11,6 +11,7 @@ import ( "image/png" "net/http" "net/http/httptest" + "os" "strings" "testing" ) @@ -187,6 +188,8 @@ func TestScreenseE2E_VisualFailureIsErrorNotDescription(t *testing.T) { reg := NewRegistry() token := "tk-visual-fail" reg.SetAcceptToken(func(p string) bool { return p == token }) + // auto_describe 需要落盘目录先存在（默认路径也会落盘） + reg.SetMediaDir(t.TempDir()) dev := &devicectlDevice{reg: reg} // 视觉源返回 403（MCP/screensee 生产上真实发生过） @@ -224,7 +227,7 @@ func TestScreenseE2E_VisualFailureIsErrorNotDescription(t *testing.T) { } }() - res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vf-dev"}) + res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vf-dev", "auto_describe": true}) // ★ 必须报错 if err == nil { @@ -285,6 +288,9 @@ func TestScreenseE2E_SuccessReturnsDescription(t *testing.T) { } }() + // ★★ 2026-10-06：默认路径**不再自动描述**，改为落盘 + 回路径。 + // 旧行为保留在 auto_describe=true 下，另有一处判据覆盖。 + reg.SetMediaDir(t.TempDir()) res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vo-dev"}) if err != nil { t.Fatalf("成功路径被破坏: %v", err) @@ -293,11 +299,33 @@ func TestScreenseE2E_SuccessReturnsDescription(t *testing.T) { if !ok { t.Fatalf("返回类型变了: %T", res) } - if m["description"] != "屏幕上是一个终端窗口" { - t.Errorf("description 不对: %v", m["description"]) + fp, _ := m["file"].(string) + if fp == "" { + t.Fatalf("默认路径必须回 file，实际返回: %v", m) + } + if got, err := os.ReadFile(fp); err != nil || len(got) == 0 { + t.Errorf("file 应指向落盘的截图: err=%v", err) + } + if _, hasDesc := m["description"]; hasDesc { + t.Error("默认路径不应再返回 description（内容由 describe_image 显式取）") + } + if gotLen != 0 { + t.Error("默认路径不应调用视觉描述 handler（模型必须显式调 describe_image）") + } + + // ★ auto_describe=true 走旧路径（调试用）：handler 被调，description 回来。 + res2, err := dev.Execute("screensee", map[string]interface{}{ + "device_id": "vo-dev", "auto_describe": true, + }) + if err != nil { + t.Fatalf("auto_describe 路径被破坏: %v", err) + } + m2, _ := res2.(map[string]interface{}) + if m2["description"] != "屏幕上是一个终端窗口" { + t.Errorf("auto_describe 应返回 description，实际: %v", m2["description"]) } if gotLen == 0 { - t.Error("handler 没收到 dataURL") + t.Error("auto_describe 下 handler 应收到 dataURL") } } From f33ebee01b2c7893d0850105f29acb19f3559e3c Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 6 Oct 2026 09:22:12 +0800 Subject: [PATCH 09/13] =?UTF-8?q?test(agent/core):=20=E6=B6=88=E9=99=A4?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E5=AF=B9=20scheduler.queue=20=E7=9A=84?= =?UTF-8?q?=E6=97=A0=E9=94=81=E7=9B=B4=E8=AF=BB=EF=BC=8C=E5=B9=B6=E5=8A=A0?= =?UTF-8?q?=E5=88=A4=E6=8D=AE=E9=98=B2=E5=9B=9E=E5=BD=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 起因 offload_test.go 等 4 个文件里有 18 处 `len(s.queue)` / `range s.queue`， 全在锁外。当时**安全**——那些测试用 newRootWithoutSchedulerLoop， 刻意不启 schedulerLoop，所以没有并发写者。 但这个安全性 ① 不由测试自身保证，只由「别改构造函数」这个口头约定保证； ② 一旦有人换成 newRootWith 就变成真竞争，症状是「今天全绿、改一次就炸」。 先确认生产代码没问题：逐处核对 scheduler.go 里 6 个读 s.queue 的函数， 全部在 mu.Lock/RLock 内（takeQueuedInputs/hasRoom/nextRef/armStop/ pendingEvents/takeAllPendingEvents）。所以这是**测试的隐患**，不是核心缺陷。 ## 改动 - scheduler.go 新增两个带锁只读访问器： · queueLen() —— 替代 len(s.queue) · queueSnapshot() —— 返回浅拷贝，替代 range/索引（拷贝保证 len 与 range 不会在遍历中途变化） - 4 个测试文件 18 处直读全部改走访问器 - 新增 queue_access_test.go：AST 静态判据，扫所有 *_test.go， 同一函数内出现过 Lock/RLock 即视为持锁（Go 的 defer Unlock 静态难还原， 按函数近似足够保守）；命中无锁直读即红 ## 判据自检 静态判据最大的失败模式是「根本没抓到东西」，所以带双向自检： - 正向：注入一处无锁直读 → 必须被抓到 - 反向：注入一处持锁直读 → 必须**不**被报（否则噪声大没人看） - 真变异：把一处访问器改回 `len(s.queue)` → 红 ## 验证 - go build ./... / go vet / go test ./internal/... 全绿 - go test -race ./internal/agent/core/ 无数据竞争 - 部署后：39 插件加载、3 个 multimodal 工具注册、0 panic/fatal - graph.db integrity ok，blocks 2787 未动 Co-Authored-By: Claude Opus 4.8 (1M context) --- internal/agent/core/offload_test.go | 47 ++++--- internal/agent/core/queue_access_test.go | 169 +++++++++++++++++++++++ internal/agent/core/scheduler.go | 28 ++++ internal/agent/core/scheduler_test.go | 6 +- 4 files changed, 224 insertions(+), 26 deletions(-) create mode 100644 internal/agent/core/queue_access_test.go diff --git a/internal/agent/core/offload_test.go b/internal/agent/core/offload_test.go index 1c46a182..01173854 100644 --- a/internal/agent/core/offload_test.go +++ b/internal/agent/core/offload_test.go @@ -61,8 +61,8 @@ func TestTakeQueuedInputsOnlyTakesQueuedInputs(t *testing.T) { s.enqueue(makeQueuedInput(3)) s.enqueue(makeQueuedInput(4)) - if len(s.queue) != 6 { - t.Fatalf("就绪队列应有 6 条（4 排队输入 + 1 中断 + 1 self），实际 %d", len(s.queue)) + if n := s.queueLen(); n != 6 { + t.Fatalf("就绪队列应有 6 条（4 排队输入 + 1 中断 + 1 self），实际 %d", n) } got := s.takeQueuedInputs(3) if len(got) != 3 { @@ -75,7 +75,7 @@ func TestTakeQueuedInputsOnlyTakesQueuedInputs(t *testing.T) { } // self 与中断必须还在 var hasSelf, hasInterrupt bool - for _, tt := range s.queue { + for _, tt := range s.queueSnapshot() { if tt.Kind == TaskKindSelf { hasSelf = true } @@ -101,8 +101,8 @@ func TestTakeQueuedInputsIsAllOrNothing(t *testing.T) { if got := s.takeQueuedInputs(3); got != nil { t.Fatalf("不足 3 条时不应取走任何任务，实际取走 %d", len(got)) } - if len(s.queue) != 2 { - t.Errorf("队列不应被改动，实际剩 %d", len(s.queue)) + if n := s.queueLen(); n != 2 { + t.Errorf("队列不应被改动，实际剩 %d", n) } } @@ -118,17 +118,18 @@ func TestRequeueFrontKeepsAllTasks(t *testing.T) { if len(taken) != 3 { t.Fatalf("应取走 3 条，实际 %d", len(taken)) } - if len(s.queue) != 0 { - t.Fatalf("取走后队列应空，实际 %d", len(s.queue)) + if n := s.queueLen(); n != 0 { + t.Fatalf("取走后队列应空，实际 %d", n) } s.requeueFront(taken) - if len(s.queue) != 3 { - t.Fatalf("★ 放回后必须一条不少：期望 3，实际 %d", len(s.queue)) + if n := s.queueLen(); n != 3 { + t.Fatalf("★ 放回后必须一条不少：期望 3，实际 %d", n) } // 放回的是**前端**：它们比队列里原有的一切都早 s.enqueue(makeQueuedInput(4)) - if s.queue[len(s.queue)-1].Event.Payload["content"] != "hello" { + snap := s.queueSnapshot() + if snap[len(snap)-1].Event.Payload["content"] != "hello" { t.Error("放回的任务应在队列前端") } } @@ -160,8 +161,8 @@ func TestOffloadDisabledByDefault(t *testing.T) { if n := a.offloadPendingTasks(opts); n != 0 { t.Errorf("关闭时不得转投，实际转了 %d", n) } - if len(s.queue) != 3 { - t.Errorf("关闭时队列不得被改动，实际 %d", len(s.queue)) + if n := s.queueLen(); n != 3 { + t.Errorf("关闭时队列不得被改动，实际 %d", n) } } @@ -225,10 +226,10 @@ func TestOffloadMovesTasksToResidentEndToEnd(t *testing.T) { t.Logf("驻留子 %s: inputch=%v outputs=%v", resident.ID, resident.InputChs, resident.AllowedOutputs) // ③ 原队列里留下说明（且说明是内核发的） - if len(root.sched.queue) != 1 { - t.Fatalf("原队列应只剩 1 条说明，实际 %d", len(root.sched.queue)) + if root.sched.queueLen() != 1 { + t.Fatalf("原队列应只剩 1 条说明，实际 %d", root.sched.queueLen()) } - notice := root.sched.queue[0] + notice := root.sched.queueSnapshot()[0] if notice.Event == nil || notice.Event.Source != "kernel" { t.Fatalf("留下的应是内核说明，实际 %+v", notice.Event) } @@ -330,8 +331,8 @@ func TestOffloadSeesInputsStuckInChannel(t *testing.T) { root.io.InjectInputTo("webui", "webui", "text", map[string]interface{}{"content": "stuck"}) } - if len(root.sched.queue) != 0 { - t.Fatalf("前置条件：此时 sched.queue 应为 0（输入还没被搬运），实际 %d", len(root.sched.queue)) + if root.sched.queueLen() != 0 { + t.Fatalf("前置条件：此时 sched.queue 应为 0（输入还没被搬运），实际 %d", root.sched.queueLen()) } if root.io.PendingInputs() != 3 { t.Fatalf("前置条件：输入应堆在 channel 里，实际 %d", root.io.PendingInputs()) @@ -502,11 +503,11 @@ func TestResidualKeepReturnsTasksToParent(t *testing.T) { t.Fatalf("应处置 2 条，实际 %d（msg=%s）", n, msg) } // keep = 转回父自己：两条都要出现在父的队列里，且**带 ResponseCh 的那条仍带** - if len(root.sched.queue) != 2 { - t.Fatalf("两条残余任务应转回父队列，实际 %d", len(root.sched.queue)) + if root.sched.queueLen() != 2 { + t.Fatalf("两条残余任务应转回父队列，实际 %d", root.sched.queueLen()) } var hasResponseCh bool - for _, task := range root.sched.queue { + for _, task := range root.sched.queueSnapshot() { if task.Event != nil && task.Event.ResponseCh != nil { hasResponseCh = true } @@ -557,8 +558,8 @@ func TestResidualDropNotifiesSyncCaller(t *testing.T) { t.Fatal("★ drop 未通知同步调用方：cli/a2a 会永久挂起") } // drop 后父队列不应多出东西 - if len(root.sched.queue) != 0 { - t.Errorf("drop 不应把任务转回父队列，实际 %d", len(root.sched.queue)) + if root.sched.queueLen() != 0 { + t.Errorf("drop 不应把任务转回父队列，实际 %d", root.sched.queueLen()) } } @@ -657,7 +658,7 @@ func TestKernelNoticeIsNeverOffloaded(t *testing.T) { } // 说明必须还在队列里（留给主 agent 看），不能被搬走 var noticeLeft bool - for _, task := range root.sched.queue { + for _, task := range root.sched.queueSnapshot() { if task.Event != nil && isKernelNotice(task.Event) { noticeLeft = true } diff --git a/internal/agent/core/queue_access_test.go b/internal/agent/core/queue_access_test.go new file mode 100644 index 00000000..fb46f65e --- /dev/null +++ b/internal/agent/core/queue_access_test.go @@ -0,0 +1,169 @@ +package core + +import ( + "fmt" + "go/ast" + "go/parser" + "go/token" + "os" + "path/filepath" + "strings" + "testing" +) + +// 判据：测试代码不得在锁外直读 scheduler 的内部队列字段。 +// +// ## 起因（2026-10-06） +// +// offload_test.go 曾有 6 处 `len(root.sched.queue)` / `range root.sched.queue`， +// 全在锁外。当时**安全**——那些测试用 newRootWithoutSchedulerLoop， +// 刻意不启 schedulerLoop，所以没有并发写者。但这个安全性： +// +// ① 不由测试自身保证，只由「别改构造函数」这个口头约定保证； +// ② 一旦有人把 WithoutSchedulerLoop 换成 newRootWith，就变成真竞争， +// 而症状是「今天全绿、改一次就炸」。 +// +// 这正是本项目反复记录的形态：**隐患不在当前代码里，在下一次修改里。** +// +// ## 判据怎么做到不误报 +// +// · 只扫 `*_test.go`（生产代码直读是另一回事，且已全部在锁内） +// · 跳过 queueLen()/queueSnapshot()（带锁访问器） +// · 同一函数内**出现过** Lock/RLock 即视为整函数持锁 +// （Go 的 defer Unlock 很难静态还原，按函数近似足够保守） +// +// 判据不可达 = 判据描述的状态不存在。所以本判据自带自检： +// TestQueueAccessCriterion_SelfCheck 注入一处无锁直读，要求被抓到。 + +func TestNoUnlockedQueueReadInTests(t *testing.T) { + ents, err := os.ReadDir(".") + if err != nil { + t.Fatalf("读包目录: %v", err) + } + var violations []string + for _, e := range ents { + name := e.Name() + if !strings.HasSuffix(name, "_test.go") { + continue + } + violations = append(violations, unlockedQueueReadsInFile(t, filepath.Join(".", name))...) + } + if len(violations) > 0 { + t.Errorf("测试里不得在锁外直读调度器队列（请用 queueLen()/queueSnapshot()）：\n\t%s", + strings.Join(violations, "\n\t")) + } +} + +// unlockedQueueReadsInFile 解析一个文件并返回所有「无锁直读 .queue」的位置。 +func unlockedQueueReadsInFile(t *testing.T, path string) []string { + t.Helper() + fset := token.NewFileSet() + f, err := parser.ParseFile(fset, path, nil, 0) + if err != nil { + t.Fatalf("解析 %s: %v", path, err) + } + parent := buildParentMap(f) + // 先标记「函数体内出现过 Lock/RLock」 + lockedFn := map[*ast.FuncDecl]bool{} + ast.Inspect(f, func(n ast.Node) bool { + sel, ok := n.(*ast.SelectorExpr) + if !ok || (sel.Sel.Name != "Lock" && sel.Sel.Name != "RLock") { + return true + } + if fn := enclosingFunc(parent, n); fn != nil { + lockedFn[fn] = true + } + return true + }) + + var out []string + ast.Inspect(f, func(n ast.Node) bool { + sel, ok := n.(*ast.SelectorExpr) + if !ok || sel.Sel.Name != "queue" { + return true + } + if fn := enclosingFunc(parent, n); fn != nil && lockedFn[fn] { + return true // 该函数整体持锁 + } + pos := fset.Position(sel.Pos()) + out = append(out, fmt.Sprintf("%s:%d: 直接访问 .queue（无锁）", path, pos.Line)) + return true + }) + return out +} + +// buildParentMap 建立 AST 父指针表（ast.Inspect 的回调拿不到父节点）。 +func buildParentMap(f *ast.File) map[ast.Node]ast.Node { + parent := map[ast.Node]ast.Node{} + var stack []ast.Node + ast.Inspect(f, func(n ast.Node) bool { + if n == nil { + stack = stack[:len(stack)-1] + return false + } + if len(stack) > 0 { + parent[n] = stack[len(stack)-1] + } + stack = append(stack, n) + return true + }) + return parent +} + +// enclosingFunc 沿父指针上溯到最近的 *ast.FuncDecl。 +func enclosingFunc(parent map[ast.Node]ast.Node, n ast.Node) *ast.FuncDecl { + for cur := n; cur != nil; cur = parent[cur] { + if fn, ok := cur.(*ast.FuncDecl); ok { + return fn + } + } + return nil +} + +// TestQueueAccessCriterion_SelfCheck 证明判据能红。 +// +// ★ 没有自检的静态判据，无法区分「没问题」与「判据根本没抓到东西」。 +// +// 本项目踩过：`-run` 正则被 shell 转义破坏，打印 "[no tests to run]" 并 +// exit 0 —— 绿色 + 没测任何东西，最坏的组合。 +func TestQueueAccessCriterion_SelfCheck(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "injected_test.go") + src := `package core + +import "testing" + +func injectedUnlockedRead(a *Agent) int { + return len(a.sched.queue) +} + +var _ = injectedUnlockedRead +` + if err := os.WriteFile(path, []byte(src), 0o644); err != nil { + t.Fatal(err) + } + got := unlockedQueueReadsInFile(t, path) + if len(got) == 0 { + t.Fatal("★ 判据失效：注入的无锁直读没被抓到 —— 它对真实回归也会失效") + } + // 反向自检：持锁的写法**不得**被报（否则判据噪声太大，没人看） + path2 := filepath.Join(dir, "locked_test.go") + src2 := `package core + +import "testing" + +func injectedLockedRead(a *Agent) int { + a.sched.mu.Lock() + defer a.sched.mu.Unlock() + return len(a.sched.queue) +} + +var _ = injectedLockedRead +` + if err := os.WriteFile(path2, []byte(src2), 0o644); err != nil { + t.Fatal(err) + } + if got := unlockedQueueReadsInFile(t, path2); len(got) != 0 { + t.Fatalf("★ 判据误报：持锁的直读被报出来 %v", got) + } +} diff --git a/internal/agent/core/scheduler.go b/internal/agent/core/scheduler.go index b7133b95..564ea9d0 100644 --- a/internal/agent/core/scheduler.go +++ b/internal/agent/core/scheduler.go @@ -582,6 +582,34 @@ func (s *scheduler) next() *Task { return t } +// queueLen 返回当前排队任务数（**带锁**）。 +// +// ★ 2026-10-06 新增：offload_test.go 有 6 处直读 s.queue 取 len。 +// +// 那在「无并发写者」时安全（测试用 newRootWithoutSchedulerLoop， +// 刻意不启 schedulerLoop），但**只要有人改成 newRootWith 就变成真竞争**， +// 而且是「今天绿的、改一次就炸」的那种。 +// +// ⇒ 生产代码本来就走 takeQueuedInputs/hasRoom 等带锁访问器； +// 这里补一个对称的只读访问器，让测试不必直读内部字段。 +func (s *scheduler) queueLen() int { + s.mu.Lock() + defer s.mu.Unlock() + return len(s.queue) +} + +// queueSnapshot 返回排队任务的浅拷贝，供测试断言内容（**带锁**）。 +// +// 返回拷贝而非内部切片：调用方拿到的就是某个时刻的快照， +// 后续并发 enqueue/dequeue 不会让它的 len 或 range 在中途变化。 +func (s *scheduler) queueSnapshot() []*Task { + s.mu.Lock() + defer s.mu.Unlock() + out := make([]*Task, len(s.queue)) + copy(out, s.queue) + return out +} + // nextRef 选出下一个任务。优先顺序： // // 1. immediate —— 刚抢占成功的中断（抢占必须立即生效） diff --git a/internal/agent/core/scheduler_test.go b/internal/agent/core/scheduler_test.go index 2b6add8f..2b3994ff 100644 --- a/internal/agent/core/scheduler_test.go +++ b/internal/agent/core/scheduler_test.go @@ -155,11 +155,11 @@ func TestScheduler_Lifecycle(t *testing.T) { if t1 == nil || s.running != t1 { t.Fatal("next 应取出任务并置为 running") } - if len(s.queue) != 1 { - t.Fatalf("取出后队列长度=%d，期望 1", len(s.queue)) + if n := s.queueLen(); n != 1 { + t.Fatalf("取出后队列长度=%d，期望 1", n) } // 队列内不得同时出现 running（O1：三集合互不重叠）。 - for _, q := range s.queue { + for _, q := range s.queueSnapshot() { if q == t1 { t.Fatal("running 任务不得同时留在就绪队列") } From 04c5883f4b820e739407a495bd05ea09fc93320c Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Tue, 6 Oct 2026 10:29:58 +0800 Subject: [PATCH 10/13] =?UTF-8?q?fix(gui):=20=E6=98=9F=E5=9B=BE=E5=87=A0?= =?UTF-8?q?=E4=BD=95=E4=BD=93=E5=85=B1=E4=BA=AB=20+=20=E9=87=8D=E5=BB=BA?= =?UTF-8?q?=E6=97=B6=20dispose=EF=BC=8C=E4=BF=AE=E8=81=8A=E5=A4=A9?= =?UTF-8?q?=E9=A1=B5=E9=95=BF=E6=97=B6=E9=97=B4=E6=8C=82=E8=B5=B7=E5=90=8E?= =?UTF-8?q?=E5=8D=A1=E6=AD=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 实测故障 聊天页长时间挂着之后 GUI 卡死。CDP 抓生产实例（2588 节点）： Mesh/SphereGeometry 2588 个 geometry 数据合计 22.67MB Sprite/BufferGeometry 1294 个 label 纹理，256×64 RGBA ≈ 64KB/个 进程常驻内存反复冲上 GB 级、被 GC 拉回后又再度暴涨（实测 986MB ↔ 3.8GB 震荡），CPU 稳定 30%（多线程耗在 GC 与对象构建），句柄数稳定 490 ⇒ 不是句柄泄漏，而是持续的 GPU 资源分配。 ## 两个叠加缺陷 1. **几何体从不共享**。每个节点 `new THREE.SphereGeometry(rad, 16, 12)`、 每个光晕球 `new THREE.SphereGeometry(gr, 16, 12)` —— 半径各异看起来 「只能各自 new」。但 three.js 里大小应由 mesh.scale 表达，几何体应共享。 2. **重建时不 dispose**。buildChatStarmapGraph 只 `starmapScene.remove(m)`， 从不 dispose()。remove 只把对象从场景树摘下来，geometry/material/texture 仍占着 WebGL 资源。全代码搜不到 dispose() 就是铁证。星图每次全量重建 泄漏一整轮，节点数还随记忆增长 ⇒ 泄漏只增不减。 ## 修法 - `starmapSphereGeometry()`：建一次半径 0.5 的球，全场景共用。 **半径必须仍是 0.5** —— 节点缩放基准 `baseScale = rad / 0.5` 的分母 就是它，改成 1 会让所有节点缩放翻倍，且与脉冲结束时的 `setScalar(baseScale)` 复原逻辑不自洽。 - `disposeStarmapObject()`：递归 traverse 子树（节点下挂着 glow sphere 与 label sprite，只 dispose 顶层会漏），释放 geometry/material/texture； 用 seen 集合防重复释放，并**排除共享几何体**（释放它会让仍在渲染的 mesh 变黑/报错）。 - 重建时节点与边都走 dispose。 几何体数据从 2588 份降到 1 份（22.67MB → 9KB），label 纹理由 「只增不减」变成「每轮释放」。 ## 判据（cmd/gui/starmap-gpu-lifecycle.test.mjs） 13 条。变异测试验证非假红： - 还原 `new SphereGeometry(rad,…)` ⇒ 「节点循环用共享几何体」+ 「代码里只有一处构造」转红 - `disposeStarmapObject(m)` 换回 `starmapScene.remove(m)` ⇒ 「重建时释放旧节点资源」转红 排障中判据自身报过 3 次假红，根因都写进注释： - 注释里也写着 `starmapNodeMeshes.forEach` 与 `disposeStarmapObject`， 裸正则从注释开始匹配 ⇒ 改为先剥注释 - 匹配窗口 200 太大：节点那处换成 remove 后，**边**的 `disposeStarmapObject(l)`（相距 84 字符）仍落在窗口内 ⇒ 收到 40 - 摘要里 `new SphereGeometry` 计数包含注释里的引用，显示 2 次而真实 只有 1 次 ⇒ 计数前先剥注释 ## 验证 6 个门禁全绿：starmap-gpu-lifecycle / window-liveness / device-bridge-liveness / endpoint-align / device-align / device-gateway-discovery。 --- cmd/gui/renderer/app.js | 106 +++++++++++- cmd/gui/starmap-gpu-lifecycle.test.mjs | 213 +++++++++++++++++++++++++ 2 files changed, 312 insertions(+), 7 deletions(-) create mode 100644 cmd/gui/starmap-gpu-lifecycle.test.mjs diff --git a/cmd/gui/renderer/app.js b/cmd/gui/renderer/app.js index c56a298a..db15e5bd 100644 --- a/cmd/gui/renderer/app.js +++ b/cmd/gui/renderer/app.js @@ -3066,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 = []; @@ -3207,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, @@ -3223,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, @@ -3233,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 From 5f12ea3df9de86a6c6066e8f6f3b193f960e5bb3 Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Tue, 6 Oct 2026 13:09:12 +0800 Subject: [PATCH 11/13] =?UTF-8?q?fix(gui):=20=E8=A1=A5=E6=98=9F=E5=9B=BE?= =?UTF-8?q?=E9=9D=A2=E6=9D=BF=E7=BC=BA=E5=A4=B1=E7=9A=84=20=EF=BC=8C?= =?UTF-8?q?=E4=BF=AE=E5=AF=B9=E8=AF=9D=E9=A1=B5=205=20=E4=B8=AA=E9=A1=B5?= =?UTF-8?q?=E7=AD=BE=E7=A9=BA=E7=99=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 实测故障 对话页里「终端 / 运行中命令 / 记忆 / 上下文 / 知识」五个页签点进去全是 空白，只有「对话」和「星图」正常。 ## 根因：少一个 构造星图面板的那段 HTML 里有 **4 个 `
` 开、只有 3 个 `
` 闭**， 它没闭合 —— 后面拼接的所有 chat-panel 都被浏览器塞进 chat-panel-starmap **内部**。 CDP 查真实 DOM 的铁证： .chat-layout 的直接子节点只有 3 个： DIV.chat-tabs / DIV#chat-panel-chat / DIV#chat-panel-starmap terminal/cmd/memory/context/knowledge 的父节点 = chat-panel-starmap ← 不是同级的 chat-layout 后果：这些面板 display 是flex（switchChatPanel 把 active 加对了）， 但父级 display:none ⇒ getBoundingClientRect() 恒为 0x0 ⇒ 显示为空白。 实测尺寸对照（修复前 → 修复后）： terminal 0x0 → 1156x621 cmd 0x0 → 1156x621 memory 0x0 → 1156x621 context 0x0 → 1156x621 knowledge 0x0 → 1156x621 ## 为什么一直没被发现 标签不配对在源码里看不出来（跨行字符串拼接的 HTML 片段），浏览器也 **不报错** —— 它只是「尽力修复」成畸形结构。现象是「点了没反应/一片空白」， 很容易被归因为数据没到或后端挂了（我最初就查了半天气网络与接口 401）。 而且它只在部分面板上发作：chat 与 starmap 恰好是前两个，位置靠前不受影响， 于是「大部分能用」掩盖了「后面全废」。 ## 判据（cmd/gui/chat-panel-dom.test.mjs） 3 条：整段 div 标签配平、各面板独立配平、各面板顶层不被嵌套进前一面板。 逐面板断言能定位到**具体是哪个**面板不配平（变异测试下报 `starmap(开4/闭3)`），而不只是「总数差了 1」。 变异测试：去掉一个 `` ⇒ 前两条转红并指出 starmap。 判据自身也错过一次：还原 HTML 时把 `"` 全替换成 `'`，而 marker 用的是双引号， 7 个面板全报「未找到」。已修正并记在注释里。 --- cmd/gui/chat-panel-dom.test.mjs | 149 ++++++++++++++++++++++++++++++++ cmd/gui/renderer/app.js | 2 +- 2 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 cmd/gui/chat-panel-dom.test.mjs diff --git a/cmd/gui/chat-panel-dom.test.mjs b/cmd/gui/chat-panel-dom.test.mjs new file mode 100644 index 00000000..cf56a594 --- /dev/null +++ b/cmd/gui/chat-panel-dom.test.mjs @@ -0,0 +1,149 @@ +// chat 子面板 DOM 结构判据（2026-10-05）。 +// +// ## 要判的是什么 +// +// 实测故障：对话页里「终端 / 运行中命令 / 记忆 / 上下文 / 知识」五个页签 +// 点进去全是空白，只有「对话」和「星图」正常。 +// +// 根因是 **HTML 少一个 **：构造星图面板的那段 HTML 里有 4 个 +//
开、只有 3 个
闭，于是它没闭合 —— 后面拼接的所有 +// chat-panel 都被浏览器塞进 chat-panel-starmap **内部**。 +// +// 实测证据（CDP 查真实 DOM）： +// +// .chat-layout 的直接子节点只有 3 个： +// DIV.chat-tabs / DIV#chat-panel-chat / DIV#chat-panel-starmap +// +// 而 terminal/cmd/memory/context/knowledge 的父节点是 +// chat-panel-starmap —— 不是同级的 chat-layout。 +// +// 后果：这些面板 display 是 flex（switchChatPanel 把 active 加对了）， +// 但父级 display:none ⇒ getBoundingClientRect() 恒为 0x0 ⇒ 看起来空白。 +// +// ★ 为什么需要判据：标签不配对在源码里完全看不出来（字符串拼接 + +// 跨行的 HTML 片段），浏览器也不报错 —— 它只是「尽力修复」成畸形结构。 +// 只有断言「开闭标签数相等」才能挡住。 +// +// 运行：node chat-panel-dom.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"); + +// ── 1) 抽出构造 chat 子面板的整段 HTML ───────────────────────────── +// +// 从第一个 chat-panel 面板开始，到最后一个面板结束。 + +const startIdx = src.indexOf( + `'
`, +); +if (startIdx < 0) { + console.error("定位不到 chat 面板段落 —— app.js 结构可能已变"); + process.exit(1); +} +const lastIdx = src.indexOf("chat-panel-knowledge"); +const seg = src.slice(startIdx, lastIdx + 4000); + +// 把跨行拼接的字符串还原成一段连续 HTML： +// '...' + \n '...' → '...' +const html = seg + .replace(/'\s*\+\s*\n\s*'/g, "") + .replace(/'\s*\+\s*'/g, "") + .replace(/"/g, "'"); + +const opens = (html.match(//g) || []).length; + +check( + "chat 面板段落 div 标签配平", + opens === closes, + `开 ${opens} / 闭 ${closes}，差 ${opens - closes} —— ` + + "少一个
会让后面所有面板被塞进前一个面板内部（表现为空白）", +); + +// ── 2) 每个 chat-panel 自身也必须配平 ───────────────────────────── +// +// 总数配平还不够：某处多一个 、另一处少一个，总数仍为 0。 +// 逐面板断言能定位到具体是哪个。 + +const PANELS = ["chat", "starmap", "terminal", "cmd", "memory", "context", "knowledge"]; +const unbalanced = []; +for (const name of PANELS) { + const marker = `id='chat-panel-${name}'`; + const at = html.indexOf(marker); + if (at < 0) { + unbalanced.push(`${name}(未找到)`); + continue; + } + // 从该面板的
/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/renderer/app.js b/cmd/gui/renderer/app.js index db15e5bd..6b0cc5ee 100644 --- a/cmd/gui/renderer/app.js +++ b/cmd/gui/renderer/app.js @@ -1873,7 +1873,7 @@ function buildChatLayout() { '

' + __("星图", "Star Map") + "

" + - '
'; + '
'; html += '

' + __("终端", "Terminal") + From b27e6142e24d1c4356cd94d5a91087e91cadd06e Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 6 Oct 2026 21:17:03 +0800 Subject: [PATCH 12/13] =?UTF-8?q?fix(remotedevice):=20=E8=A1=A5=20screensu?= =?UTF-8?q?e/camerasue/speakeruse=20=E4=B8=93=E7=94=A8=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=EF=BC=8C=E4=BF=AE=E3=80=8Cagent=20=E8=A2=AB=E8=BF=AB=E6=89=8B?= =?UTF-8?q?=E6=8B=BC=E5=91=BD=E4=BB=A4=E5=AD=97=E7=AC=A6=E4=B8=B2=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 问题（生产日志实证，10-06 12:46~13:04） 三个能力只能走 device_ctl_cmdrun 的 **command 字符串**，agent 于是手拼： homeagent-screensue 0 … 结果是工具调用**连执行都没执行**： 13:00:38 stream tool_call device_ctl_cmdrun argument fragments invalid JSON: "{\"device_id\": \"gui-JianF\", \"command\": \"homeagent-screensue 0 …… 13:00:38 args unparseable (982 bytes) — surfacing to model instead of calling 三个原因叠加： ① 引号要穿过两层 JSON 转义（HTML 必然含引号） ② 时长与内容共用一个字符串靠空格切分（内容里的空格有歧义） ③ 长度无上限（一屏看板几十 KB） agent 的应对是反复试参数 —— 它在猜格式，不是在做事： screensue shown on display 0 for 15s / 25s / 30s / 40s / 60s / 180s ## 改动 新增三个结构化工具（与 screensee 同一层）： | 工具 | 参数 | |---|---| | `screensue` | device_id, content 或 content_path, duration_seconds | | `camerasue` | device_id, duration_seconds（省略/0=拍照，N=录像 N 秒） | | `speakeruse` | device_id, text 或 text_path | - 命令字符串由**服务端**拼装，形状与 GUI `executeHomeagentCmd` 的解析一致 - 长内容走 `*_path`（服务端读文件，上限 2MB，与 clipboardsue 对齐） - `duration_seconds=0` **显式下发 0**（常驻），与「省略=默认 5 秒」语义区分开 - device_ctl_cmdrun 描述改向：告明它只管 shell，屏幕/摄像头/语音请用专用工具； homeagent-* 旧前缀仍兼容（不破坏既有调用） ## 顺带修掉一个「只提交判据没提交实现」的缺口 clipboardsue 的实现读 `args["content"]`，但**工具 schema 里只有 text** —— 参数存在却不暴露，等于没有。已补进 schema。 ## 判据 capability_tools_test.go，11 条。三个变异自证会红： - 变异 A：把 content 与时长拼回一个字符串 → 红 （`got="screensue 三点开会"` / 含引号内容被下划线替换） - 变异 B：duration=0 时省略 → 红（与「默认5秒」混淆） - 变异 C：超时错误退化成一句「失败」→ 红（丢掉 req_id 与复查提示） ★ 过程中两次遇到「无输出」，都不是被杀死而是**编译失败** （未使用的 prefix / 类型不符）。本项目已记过这个坑： 编译失败 ≠ 被杀。加 `_ = prefix` 后确认是真的被杀。 另：一条判据自己假红了一次 —— `res["size"]` 经 JSON 回来是 float64 而非 int，断言写错。判据的红也要先分清「实现错了」与「断言错了」。 ## 验证 - go build / go vet / go test ./internal/... 全绿 - go test -race remotedevice 无数据竞争 - 部署后 39 插件加载、0 panic/fatal、DB integrity ok - 快照 /home/newqqagent/memory/pre-capability-tools-20261006-211446/ Co-Authored-By: Claude Opus 4.8 (1M context) --- .../remotedevice/capability_tools_test.go | 373 ++++++++++++++++++ internal/plugins/remotedevice/device.go | 357 ++++++++++++++++- 2 files changed, 717 insertions(+), 13 deletions(-) create mode 100644 internal/plugins/remotedevice/capability_tools_test.go diff --git a/internal/plugins/remotedevice/capability_tools_test.go b/internal/plugins/remotedevice/capability_tools_test.go new file mode 100644 index 00000000..60ab7b06 --- /dev/null +++ b/internal/plugins/remotedevice/capability_tools_test.go @@ -0,0 +1,373 @@ +package remotedevice + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +// 三个结构化能力工具（screensue / camerasue / speakeruse）—— 2026-10-06 +// +// # 为什么要从 device_ctl_cmdrun 里拆出来 +// +// 生产日志实证（10-06 12:46~13:04，agent 连续 9 次试参数）： +// +// 13:00:38 stream tool_call device_ctl_cmdrun argument fragments invalid JSON: +// "{\"device_id\": \"gui-JianF\", \"command\": \"homeagent-screensue 0 +// …… +// 13:00:38 args unparseable (982 bytes) — surfacing to model instead of calling +// +// 一屏 HTML 内联进 command 字符串后：① 引号要穿过两层 JSON 转义； +// ② 时长与内容共用一个字符串靠空格切分；③ 长度无上限。 +// 三者叠加 ⇒ 工具调用变成非法 JSON，**连执行都没执行**。 +// +// agent 的应对是反复试参数： +// +// screensue shown on display 0 for 15s / 25s / 30s / 40s / 60s / 180s +// +// —— 它在猜格式，不是在做事。 +// +// # 这些判据钉住什么 +// +// ① 三个工具有结构化参数（content / duration_seconds 分开） +// ② 命令字符串由服务端拼装，形状与 GUI 端 executeHomeagentCmd 的解析一致 +// ③ 长内容走 content_path，不内联 +// ④ 超时/不在线/缺能力都给出可操作的错误（不是一句 "failed"） + +// ---- 测试脚手架 ---- + +// newCapabilityDevice 起一台「已在线 + 全能力」的假设备，并返回收到的命令。 +// +// 用 caps=["cmd"]：deviceSupportsTool 把 cmd 视为历史全能力标记， +// 于是三个工具的能力门都会放行 —— 判据才能测到工具本身而不是被门挡住。 +func newCapabilityDevice(t *testing.T, deviceID string, reply func(cmd string) map[string]interface{}) (*devicectlDevice, *[]string) { + t.Helper() + reg := NewRegistry() + token := "tk-cap-" + deviceID + reg.SetAcceptToken(func(p string) bool { return p == token }) + reg.SetMediaDir(t.TempDir()) + + dev := &devicectlDevice{reg: reg} + got := &[]string{} + + srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS)) + t.Cleanup(srv.Close) + + cli := dialTestWS(t, srv.URL, token) + t.Cleanup(cli.close) + + cli.sendText([]byte(`{"op":"hello","device":{"device_id":"` + deviceID + + `","name":"能力机","kind":"computer","caps":["cmd"]}}`)) + cli.readHelloAckAndBind(t, token) + + go func() { + for { + op, payload, err := cli.readMsg() + if err != nil { + return + } + if op != 0x1 { + continue + } + var msg map[string]interface{} + if json.Unmarshal(payload, &msg) != nil { + continue + } + if msg["op"] != "cmd" { + continue + } + cmd, _ := msg["command"].(string) + reqID, _ := msg["req_id"].(string) + *got = append(*got, cmd) + out := reply(cmd) + if out == nil { + out = map[string]interface{}{"status": "ok", "output": "done"} + } + out["op"] = "cmd_result" + out["req_id"] = reqID + out["device_id"] = deviceID + cli.sendText(mustJSON(out)) + } + }() + + // 等设备进入 registry 的在线表（bind 之后才可见） + deadline := time.Now().Add(3 * time.Second) + for time.Now().Before(deadline) { + if m, ok := reg.Get(deviceID); ok && m.Online { + break + } + time.Sleep(10 * time.Millisecond) + } + return dev, got +} + +// ---- ① screensue：内容与时长是**独立参数** ---- + +func TestScreensue_StructuredArgsBecomeOneCommand(t *testing.T) { + dev, got := newCapabilityDevice(t, "cap-sue", func(string) map[string]interface{} { + return map[string]interface{}{"status": "ok", "output": "screensue shown on display 0 for 30s"} + }) + + res, err := dev.Execute("screensue", map[string]interface{}{ + "device_id": "cap-sue", + "content": "三点开会", + "duration_seconds": 30, + }) + if err != nil { + t.Fatalf("screensue 应成功: %v", err) + } + m, _ := res.(map[string]interface{}) + if m["device_id"] != "cap-sue" { + t.Errorf("返回应带 device_id，实际 %v", m["device_id"]) + } + if len(*got) != 1 { + t.Fatalf("应下发恰好 1 条命令，实际 %d: %v", len(*got), *got) + } + // 协议形状： <秒数> <内容>（GUI executeHomeagentCmd 按首个纯数字 token 取时长） + if w := "screensue 30 三点开会"; (*got)[0] != w { + t.Errorf("命令形状错：\n got=%q\nwant=%q", (*got)[0], w) + } +} + +// TestScreensue_ContentWithQuotesAndSpacesSurvives 是这次修复的**核心判据**。 +// +// ★ 判据的是「HTML 含引号与空格时还能不能正确送达」——生产上正是它导致 +// +// JSON 参数非法（982 字节解析失败）。结构化参数后内容不经 JSON 转义层， +// 本判据保证服务端拼装不破坏它。 +func TestScreensue_ContentWithQuotesAndSpacesSurvives(t *testing.T) { + dev, got := newCapabilityDevice(t, "cap-quote", func(string) map[string]interface{} { + return map[string]interface{}{"status": "ok", "output": "ok"} + }) + html := `
A B C
` + if _, err := dev.Execute("screensue", map[string]interface{}{ + "device_id": "cap-quote", "content": html, + }); err != nil { + t.Fatalf("含引号内容应成功: %v", err) + } + // 无时长 ⇒ 不加秒数前缀（设备端默认 5 秒） + want := "screensue " + html + if (*got)[0] != want { + t.Errorf("含引号内容被破坏：\n got=%q\nwant=%q", (*got)[0], want) + } +} + +func TestScreensue_DurationZeroMeansPersistent(t *testing.T) { + dev, got := newCapabilityDevice(t, "cap-zero", func(string) map[string]interface{} { + return map[string]interface{}{"status": "ok", "output": "persistent"} + }) + // duration_seconds=0 ⇒ 必须**显式传 0**，不能省略 + // （省略 = 设备端默认 5 秒，0 = 常驻 —— 两者语义不同） + if _, err := dev.Execute("screensue", map[string]interface{}{ + "device_id": "cap-zero", "content": "公告", "duration_seconds": 0, + }); err != nil { + t.Fatalf("常驻显示应成功: %v", err) + } + if (*got)[0] != "screensue 0 公告" { + t.Errorf("0 必须显式下发（区别于省略=默认5秒），实际 %q", (*got)[0]) + } +} + +// ---- ② 长内容走文件，不内联 ---- + +func TestScreensue_ContentPathReadsFile(t *testing.T) { + dir := t.TempDir() + fp := filepath.Join(dir, "board.html") + big := "

看板

" + strings.Repeat("

x

", 500) + if err := os.WriteFile(fp, []byte(big), 0o644); err != nil { + t.Fatal(err) + } + dev, got := newCapabilityDevice(t, "cap-path", func(string) map[string]interface{} { + return map[string]interface{}{"status": "ok", "output": "ok"} + }) + + if _, err := dev.Execute("screensue", map[string]interface{}{ + "device_id": "cap-path", "content_path": fp, + }); err != nil { + t.Fatalf("content_path 应成功: %v", err) + } + // 内容来自文件，逐字节一致 + if !strings.Contains((*got)[0], big) { + t.Errorf("命令应含文件全文（%d 字节），实际长度 %d", len(big), len((*got)[0])) + } +} + +func TestDeviceContentArg_RejectsBothOrNeither(t *testing.T) { + // 两个都给 ⇒ 报错（歧义比默认取一个更危险） + if _, err := deviceContentArg("x", "/tmp/y", "content"); err == nil { + t.Error("content 与 content_path 同时给必须报错") + } + // 都不给 ⇒ 报错，且说明该怎么给 + _, err := deviceContentArg("", "", "content") + if err == nil { + t.Fatal("都不给必须报错") + } + if !strings.Contains(err.Error(), "content_path") { + t.Errorf("错误应提示可用 content_path，实际: %v", err) + } + // 文件不存在 ⇒ 带路径 + if _, err := deviceContentArg("", "/nope/x.html", "content"); err == nil || + !strings.Contains(err.Error(), "/nope/x.html") { + t.Errorf("文件读取失败应带路径，实际: %v", err) + } + // 空文件 ⇒ 与「不存在」区分 + dir := t.TempDir() + empty := filepath.Join(dir, "e.html") + os.WriteFile(empty, nil, 0o644) + if _, err := deviceContentArg("", empty, "content"); err == nil || + !strings.Contains(err.Error(), "空") { + t.Errorf("空文件应明说，实际: %v", err) + } + // 超限 ⇒ 说明大小与上限，并提示改用文件路径 + big := filepath.Join(dir, "big.html") + os.WriteFile(big, []byte(strings.Repeat("x", deviceContentMaxBytes+10)), 0o644) + _, err = deviceContentArg("", big, "content") + if err == nil || !strings.Contains(err.Error(), "过大") { + t.Errorf("超限应报错并说明，实际: %v", err) + } +} + +// ---- ③ camerasue：拍照/录像由 duration_seconds 区分 ---- + +func TestCamerasue_PhotoVsVideo(t *testing.T) { + dev, got := newCapabilityDevice(t, "cap-cam", func(cmd string) map[string]interface{} { + if cmd == "camerasue" { + return map[string]interface{}{"status": "ok", "output": "photo ok", "mime": "image/jpeg", "size": 123} + } + return map[string]interface{}{"status": "ok", "output": "video ok", "mime": "video/mp4", "size": 456} + }) + + // 拍照：不带时长 + res, err := dev.Execute("camerasue", map[string]interface{}{"device_id": "cap-cam"}) + if err != nil { + t.Fatalf("拍照应成功: %v", err) + } + if (*got)[0] != "camerasue" { + t.Errorf("拍照命令应为裸 camerasue，实际 %q", (*got)[0]) + } + if m, _ := res.(map[string]interface{}); m["mode"] != "photo" { + t.Errorf("mode 应为 photo，实际 %v", m["mode"]) + } + // ★ mime/size 必须透传：录像不能只回一句「成功」。 + // size 经 JSON 回来是 float64（不是 int）—— 这是边界事实， + // 断言要按 JSON 的实际类型比，否则判据自己会假红。 + if m, _ := res.(map[string]interface{}); m["mime"] != "image/jpeg" || toIntArg(m["size"]) != 123 { + t.Errorf("mime/size 应透传，实际 mime=%v size=%v", m["mime"], m["size"]) + } + + // 录像：带时长 + res, err = dev.Execute("camerasue", map[string]interface{}{ + "device_id": "cap-cam", "duration_seconds": 5, + }) + if err != nil { + t.Fatalf("录像应成功: %v", err) + } + if (*got)[1] != "camerasue 5" { + t.Errorf("录像命令应为 camerasue 5，实际 %q", (*got)[1]) + } + if m, _ := res.(map[string]interface{}); m["mode"] != "video" { + t.Errorf("mode 应为 video，实际 %v", m["mode"]) + } +} + +func TestCamerasue_RejectsNegativeAndOverlong(t *testing.T) { + dev, got := newCapabilityDevice(t, "cap-cam2", func(string) map[string]interface{} { + return map[string]interface{}{"status": "ok", "output": "ok"} + }) + if _, err := dev.Execute("camerasue", map[string]interface{}{ + "device_id": "cap-cam2", "duration_seconds": -1, + }); err == nil { + t.Error("负时长必须报错") + } + if _, err := dev.Execute("camerasue", map[string]interface{}{ + "device_id": "cap-cam2", "duration_seconds": 9999, + }); err == nil || !strings.Contains(err.Error(), "300") { + t.Errorf("超长录像应报错并说明上限，实际: %v", err) + } + if len(*got) != 0 { + t.Errorf("被拒的请求不应下发命令，实际下发 %v", *got) + } +} + +// ---- ④ speakeruse ---- + +func TestSpeakeruse_StructuredArg(t *testing.T) { + dev, got := newCapabilityDevice(t, "cap-spk", func(string) map[string]interface{} { + return map[string]interface{}{"status": "ok", "output": "spoken"} + }) + if _, err := dev.Execute("speakeruse", map[string]interface{}{ + "device_id": "cap-spk", "text": "三点开会，请准时", + }); err != nil { + t.Fatalf("speakeruse 应成功: %v", err) + } + if (*got)[0] != "speakeruse 三点开会，请准时" { + t.Errorf("命令形状错：%q", (*got)[0]) + } + // text_path 变体 + dir := t.TempDir() + fp := filepath.Join(dir, "say.txt") + os.WriteFile(fp, []byte("来自文件的问候"), 0o644) + if _, err := dev.Execute("speakeruse", map[string]interface{}{ + "device_id": "cap-spk", "text_path": fp, + }); err != nil { + t.Fatalf("text_path 应成功: %v", err) + } + if (*got)[1] != "speakeruse 来自文件的问候" { + t.Errorf("text_path 内容未送达：%q", (*got)[1]) + } +} + +// ---- ⑤ 数字参数的字符串形态（模型常给 "30" 而不是 30）---- + +func TestToIntArg_AcceptsStringNumbers(t *testing.T) { + // 类型断言静默失败退回默认值，正是「参数丢了但不报错」—— + // 模型给字符串 "30" 是常见形态，必须认。 + for _, v := range []interface{}{30, int64(30), float64(30), "30", " 30 "} { + if got := toIntArg(v); got != 30 { + t.Errorf("toIntArg(%#v)=%d，期望 30", v, got) + } + } + if got := toIntArg("abc"); got != 0 { + t.Errorf("非数字应返回 0，实际 %d", got) + } +} + +// ---- ⑥ 错误必须可操作：不在线 / 缺能力 ---- + +func TestCapabilityTools_OfflineErrorSaysRetry(t *testing.T) { + reg := NewRegistry() + dev := &devicectlDevice{reg: reg} + // 设备根本不存在 + _, err := dev.Execute("screensue", map[string]interface{}{ + "device_id": "ghost", "content": "x", + }) + if err == nil || !strings.Contains(err.Error(), "devicedetect") { + t.Errorf("设备不存在应指向 devicedetect，实际: %v", err) + } +} + +func TestScreensee_TimeoutErrorDistinguishesNotYetReplied(t *testing.T) { + // 设备在线但永不回执 ⇒ 错误必须说清「命令已下发但没回」， + // 而不是让 agent 以为设备拒绝执行（实测它会换参数重试）。 + dev, _ := newCapabilityDevice(t, "cap-slow", func(string) map[string]interface{} { + time.Sleep(200 * time.Millisecond) + return map[string]interface{}{"status": "ok", "output": "late"} + }) + // 用一个必然超时的短超时直接测 pushHomeagentCapability + _, reqID, err := dev.pushHomeagentCapability("cap-slow", "speakeruse hi", 50*time.Millisecond) + if err == nil { + t.Fatal("超时必须报错") + } + msg := err.Error() + if !strings.Contains(msg, "回执") || !strings.Contains(msg, reqID) { + t.Errorf("超时错误应说明「未回执」并带上 req_id=%s 便于复查，实际: %v", reqID, err) + } + if !strings.Contains(msg, "device_ctl_cmdresult") { + t.Errorf("超时错误应指向复查工具，实际: %v", err) + } +} diff --git a/internal/plugins/remotedevice/device.go b/internal/plugins/remotedevice/device.go index 178b3f5a..bc8f2639 100644 --- a/internal/plugins/remotedevice/device.go +++ b/internal/plugins/remotedevice/device.go @@ -8,6 +8,7 @@ import ( "log" "os" "sort" + "strconv" "strings" "time" @@ -66,16 +67,17 @@ func (d *devicectlDevice) Tools() []agentIO.ToolDef { }, { Name: "device_ctl_cmdrun", - Description: "向设备下发命令/操作（异步，accepted=true 后用 device_ctl_cmdresult 轮询结果）。" + - "command 支持两类（前缀区分）：\n" + - "- shell-cmd: 在设备上执行原生 shell 命令，如 shell-cmd ls -la /tmp\n" + - "- homeagent-cmd: 调用设备端 HomeAgent 内置能力：\n" + - " · homeagent-screensue <显示内容/HTML> — 用户侧屏幕弹窗显示自定义内容（默认 5 秒后自动关闭）\n" + - " · homeagent-screensue <秒> <内容> — 指定显示时长（秒），如 homeagent-screensue 30 会议提醒：三点开会\n" + - " · homeagent-screensue 0 <内容> — 永不超时，常驻显示直到用户手动关闭\n" + - " · homeagent-camerasue — 抓拍单张 jpeg（结果为 base64 data URL）\n" + - " · homeagent-camerasue — 录像 N 秒 mp4（二进制分块回传，cmdresult 含 data_base64 字段）\n" + - " · homeagent-speakeruse <文字> — 设备端 TTS 语音朗读文字\n" + + Description: "在设备上执行 **shell 命令**（异步，超时后用 device_ctl_cmdresult 按 req_id 复查）。\n" + + "★ 用途仅限 shell：查文件、跑诊断命令、看进程。command 直接写 shell 命令即可\n" + + "（如 `df -h`、`tasklist`），无需前缀。\n" + + "\n" + + "★ 屏幕显示 / 摄像头 / 语音朗读**不要用本工具**，它们各有专用工具：\n" + + " · screensue(device_id, content, duration_seconds) — 在设备屏幕显示文字或 HTML\n" + + " · camerasue(device_id, duration_seconds) — 拍照或录像\n" + + " · speakeruse(device_id, text) — TTS 朗读\n" + + "专用工具用结构化参数；本工具的 command 是**单个字符串**，" + + "把 HTML 或长文本塞进来会因 JSON 转义/空格切分而变成非法参数（实测多次失败）。\n" + + "\n" + "⚡ 高危：设备必须已授权，且该操作会改变设备行为。" + "返回 accepted=true 表示已下发并等待设备执行，之后可用 device_ctl_cmdresult 查询结果。" + "若设备未授权或离线，返回错误信息。", @@ -83,7 +85,11 @@ func (d *devicectlDevice) Tools() []agentIO.ToolDef { "type": "object", "properties": map[string]interface{}{ "device_id": map[string]interface{}{"type": "string", "description": "目标设备 ID"}, - "command": map[string]interface{}{"type": "string", "description": "以 shell-cmd 或 homeagent-cmd 前缀开头。如 shell-cmd pwd、homeagent-screensue 三点开会、homeagent-screensue 0 重要公告、homeagent-camerasue 5（录5秒）、homeagent-speakeruse 你好"}, + "command": map[string]interface{}{ + "type": "string", + "description": "要执行的 shell 命令，如 `pwd`、`df -h`、`tasklist`。" + + "（homeagent-* 旧前缀仍兼容，但屏幕/摄像头/语音请改用各自的专用工具。）", + }, }, "required": []interface{}{"device_id", "command"}, }, @@ -100,6 +106,73 @@ func (d *devicectlDevice) Tools() []agentIO.ToolDef { }, }, }, + { + Name: "screensue", + Description: "在一台已授权设备的屏幕上显示内容（文字或 HTML 看板）。\n" + + "★ 结构化参数：**不要**手拼 homeagent-screensue 命令字符串，用本工具。\n" + + "内容走独立的 content 参数，时长走独立的 duration_seconds —— 二者不再挤在\n" + + "同一个字符串里用空格分隔（那样模型必须同时处理 JSON 转义和空格切分，\n" + + "长 HTML 会把工具参数撑爆）。\n" + + "典型用途：给用户看会议提醒、公告、看板。设备必须已授权且在线。", + Parameters: map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "device_id": map[string]interface{}{"type": "string", "description": "目标设备 ID"}, + "content": map[string]interface{}{ + "type": "string", + "description": "要显示的内容：纯文字或 HTML 片段（含标签时按 HTML 渲染）。", + }, + "content_path": map[string]interface{}{ + "type": "string", + "description": "内容所在**服务端文件路径**（替代 content，适合几十 KB 的看板：" + + "避免把整页 HTML 内联进工具参数）。与 content 二选一。", + }, + "duration_seconds": map[string]interface{}{ + "type": "integer", + "description": "显示时长（秒）。默认 5；0 = 常驻直到用户手动关闭。", + }, + }, + "required": []interface{}{"device_id"}, + }, + }, + { + Name: "camerasue", + Description: "用一台已授权设备的摄像头拍照或录像。\n" + + "★ 结构化参数：**不要**手拼 homeagent-camerasue 命令字符串，用本工具。\n" + + "不传 duration_seconds = 抓拍单张 jpeg；传 N>0 = 录像 N 秒 mp4。\n" + + "产物会落盘并返回 file 路径（与 screensee 一致，可直接交给 describe_image）。\n" + + "依赖：设备端 ffmpeg + v4l2/dshow/avfoundation。设备必须已授权且在线。", + Parameters: map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "device_id": map[string]interface{}{"type": "string", "description": "目标设备 ID"}, + "duration_seconds": map[string]interface{}{ + "type": "integer", + "description": "录像秒数；省略或 0 = 抓拍单张照片（jpeg）。上限 300 秒。", + }, + }, + "required": []interface{}{"device_id"}, + }, + }, + { + Name: "speakeruse", + Description: "让一台已授权设备朗读一段文字（设备端 TTS 语音）。\n" + + "★ 结构化参数：**不要**手拼 homeagent-speakeruse 命令字符串，用本工具。\n" + + "长文本走 text_path（服务端文件），避免内联撑爆工具参数。\n" + + "设备必须已授权且在线。", + Parameters: map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "device_id": map[string]interface{}{"type": "string", "description": "目标设备 ID"}, + "text": map[string]interface{}{"type": "string", "description": "要朗读的文字（与 text_path 二选一）"}, + "text_path": map[string]interface{}{ + "type": "string", + "description": "文字所在**服务端文件路径**（替代 text）。与 text 二选一。", + }, + }, + "required": []interface{}{"device_id"}, + }, + }, { Name: "screensee", Description: "截取一台已授权设备的当前屏幕画面。\n" + @@ -172,9 +245,15 @@ func (d *devicectlDevice) Tools() []agentIO.ToolDef { "type": "object", "properties": map[string]interface{}{ "device_id": map[string]interface{}{"type": "string", "description": "目标设备 ID"}, - "text": map[string]interface{}{"type": "string", "description": "要写入剪切板的内容"}, + "text": map[string]interface{}{"type": "string", "description": "要写入剪切板的内容（与 content 二选一）"}, + "content": map[string]interface{}{ + "type": "string", + "description": "要写入剪切板的内容所在**文件路径**（服务端读取，上限 2MB）。" + + "长文本/代码块用这个：内联进 text 会撑爆工具参数。" + + "★ 路径是服务端可见路径，不是设备上的路径。", + }, }, - "required": []interface{}{"device_id", "text"}, + "required": []interface{}{"device_id"}, }, }, { @@ -206,6 +285,12 @@ func (d *devicectlDevice) Execute(tool string, args map[string]interface{}) (int return d.cmdrun(args) case "device_ctl_cmdresult": return d.cmdresult(args) + case "screensue": + return d.screensue(args) + case "camerasue": + return d.camerasue(args) + case "speakeruse": + return d.speakeruse(args) case "screensee": return d.screensee(args) case "computeruse": @@ -642,6 +727,9 @@ func (d *devicectlDevice) clipboardsue(args map[string]interface{}) (interface{} if rerr != nil { return nil, fmt.Errorf("读取 content 文件失败 %s: %w", strings.TrimSpace(content), rerr) } + if len(b) == 0 { + return nil, fmt.Errorf("content 文件为空: %s", content) + } if len(b) > clipboardsueMaxBytes { return nil, fmt.Errorf("content 文件过大 %dKB > 上限 %dKB", len(b)/1024, clipboardsueMaxBytes/1024) @@ -784,3 +872,246 @@ func jpegSize(b []byte) (int, int) { } return 0, 0 } + +// ---- 三个结构化能力工具（2026-10-06）---- +// +// # 为什么要把它们从 device_ctl_cmdrun 里拆出来 +// +// 生产日志实证（10-06 12:46~13:04，agent 连续 9 次试参数）： +// +// 13:00:38 stream tool_call device_ctl_cmdrun argument fragments invalid JSON: +// "{\"device_id\": \"gui-JianF\", \"command\": \"homeagent-screensue 0 +// …… +// 13:00:38 args unparseable (982 bytes) — surfacing to model instead of calling +// +// 一屏 HTML 内联进 command 字符串后：① 引号要穿过两层 JSON 转义； +// ② 时长与内容共用一个字符串靠空格切分（内容里的空格有歧义）； +// ③ 长度无上限。三者叠加，工具调用直接变成非法 JSON —— **连执行都没执行**。 +// +// 而 agent 的应对是反复试参数（"shown on display 0 for 15s/25s/30s/40s/60s/180s"） +// —— 它在猜格式，不是在做事。 +// +// ⇒ 正解是给这三个能力**结构化参数**（本仓已有先例：clipboardsue 的 content）。 +// command 字符串通道仍保留作逃生口，但不再是唯一通路。 + +// deviceContentArg 解析「内联内容 / 服务端文件路径」二选一。 +// +// 抽出来的理由：screensue / speakeruse 用法完全同形，两处各写一遍 +// 必然漂移（本项目已多次记录这类同形错误）。 +// +// 上限 2MB 与 clipboardsue 对齐：这是「服务端读一个文件塞进命令」的量级， +// 再大就不是「显示/朗读」而是「传输文件」了，该走别的通道。 +const deviceContentMaxBytes = 2 * 1024 * 1024 + +func deviceContentArg(inline, pathArg, what string) (string, error) { + hasInline := strings.TrimSpace(inline) != "" + hasPath := strings.TrimSpace(pathArg) != "" + switch { + case hasInline && hasPath: + return "", fmt.Errorf("%s 与 %s 只能给一个", what, what+"_path") + case hasPath: + b, err := os.ReadFile(strings.TrimSpace(pathArg)) + if err != nil { + return "", fmt.Errorf("读取 %s 失败 %s: %w", what+"_path", pathArg, err) + } + if len(b) == 0 { + return "", fmt.Errorf("%s 文件为空: %s", what+"_path", pathArg) + } + if len(b) > deviceContentMaxBytes { + return "", fmt.Errorf("%s 文件过大 %dKB > 上限 %dKB", + what+"_path", len(b)/1024, deviceContentMaxBytes/1024) + } + return string(b), nil + case hasInline: + if len(inline) > deviceContentMaxBytes { + return "", fmt.Errorf("%s 过大 %dKB > 上限 %dKB；请改用 %s_path 传文件路径", + what, len(inline)/1024, deviceContentMaxBytes/1024, what) + } + return inline, nil + } + return "", fmt.Errorf("必须给 %s 或 %s_path", what, what) +} + +// pushHomeagentCapability 下发一条 homeagent-* 能力命令并等回执。 +// +// ★ 为什么要抽：screensue/camerasue/speakeruse 三个工具都是 +// 「拼 → PushCmd(homeagent) → AwaitResult → 判 status」。 +// 三处各写一遍的后果不只是重复 —— 超时值、错误文案、pending 语义 +// 会在三次修改中各自漂移，而这类「同一逻辑多份副本」正是本项目 +// 反复吃亏的形态。 +// +// 返回 (回执, reqID, error)。回执 status=ok 时 error 为 nil。 +func (d *devicectlDevice) pushHomeagentCapability( + id, capability string, timeout time.Duration, +) (map[string]interface{}, string, error) { + if err := d.deviceOnlineCheck(id, capability); err != nil { + return nil, "", err + } + reqID := newReqID() + if err := d.reg.PushCmd(id, reqID, capability, "homeagent"); err != nil { + return nil, "", fmt.Errorf("下发 %s 命令失败: %w", capability, err) + } + res, err := d.reg.AwaitResult(reqID, timeout) + if err != nil { + d.reg.SaveResult(reqID, map[string]interface{}{ + "accepted": true, "error": err.Error(), "pending": true, + }) + // ★ 超时不是「设备失败」而是「还没回」——说清区别，否则 agent + // 会以为设备拒绝执行而换参数重试（实测它就是这么做的）。 + return nil, reqID, fmt.Errorf( + "设备未在 %v 内回执（命令已下发，设备可能正忙或刚在重连；"+ + "可用 device_ctl_cmdresult 按 req_id=%s 复查）: %w", timeout, reqID, err) + } + if res["status"] != "ok" { + msg, _ := res["error"].(string) + if msg == "" { + msg = fmt.Sprintf("status=%v", res["status"]) + } + return res, reqID, fmt.Errorf("设备执行 %s 失败: %s", capability, msg) + } + return res, reqID, nil +} + +// deviceOnlineCheck 三个结构化工具的公共前置校验。 +// +// 与 cmdrun 的口径一致（存在 → 在线 → 声明能力），但把错误文案写得更可操作： +// 说清「是哪台设备、缺哪个能力、caps 里有什么」，而不是一句 "not supported"。 +func (d *devicectlDevice) deviceOnlineCheck(id, tool string) error { + if strings.TrimSpace(id) == "" { + return fmt.Errorf("device_id required") + } + m, ok := d.reg.Get(id) + if !ok { + return fmt.Errorf("device %s 不存在（用 devicedetect 看在线设备）", id) + } + if !m.Online { + // ★ 与 screensee 的实测教训一致：设备频繁上下线（今天实测平均在线 + // ~23 分钟），命令踩中重连窗口时若只报「不在线」，agent 会以为 + // 设备永久不可用。说清「可稍后重试」。 + return fmt.Errorf("device %s 当前不在线（设备可能正在重连，稍后重试；用 devicedetect 确认）", id) + } + if !d.reg.SupportsTool(id, tool) { + return fmt.Errorf("device %s 未声明 %s 能力（caps=%v）", id, tool, m.Caps) + } + return nil +} + +// screensue 在设备屏幕上显示内容。 +func (d *devicectlDevice) screensue(args map[string]interface{}) (interface{}, error) { + id, _ := args["device_id"].(string) + content, _ := args["content"].(string) + contentPath, _ := args["content_path"].(string) + + text, err := deviceContentArg(content, contentPath, "content") + if err != nil { + return nil, err + } + // 时长：省略 → 不传（设备端默认 5 秒）；显式 0 → 常驻。 + prefix := "" + if v, ok := args["duration_seconds"]; ok && v != nil { + secs := toIntArg(v) + if secs < 0 { + return nil, fmt.Errorf("duration_seconds 不能为负（0 = 常驻）") + } + prefix = strconv.Itoa(secs) + " " + } + // 协议： <可选的秒数> <内容>（GUI 侧取首个纯数字 token 作时长） + cap := "screensue " + prefix + text + res, reqID, err := d.pushHomeagentCapability(id, cap, 30*time.Second) + if err != nil { + return nil, err + } + return map[string]interface{}{ + "device_id": id, + "req_id": reqID, + "shown": len(text), + "result": res["output"], + }, nil +} + +// camerasue 用设备摄像头拍照或录像。 +func (d *devicectlDevice) camerasue(args map[string]interface{}) (interface{}, error) { + id, _ := args["device_id"].(string) + secs := 0 + if v, ok := args["duration_seconds"]; ok && v != nil { + secs = toIntArg(v) + } + if secs < 0 { + return nil, fmt.Errorf("duration_seconds 不能为负（0 = 抓拍单张）") + } + if secs > 300 { + return nil, fmt.Errorf("duration_seconds 上限 300 秒（要更长的录像请分段）") + } + cap := "camerasue" + if secs > 0 { + cap = "camerasue " + strconv.Itoa(secs) + } + // 抓拍走小体积（一张 jpeg），录像可能几十 MB —— 超时按量级给。 + timeout := 30 * time.Second + if secs > 0 { + timeout = time.Duration(secs)*time.Second + 60*time.Second + } + res, reqID, err := d.pushHomeagentCapability(id, cap, timeout) + if err != nil { + return nil, err + } + out := map[string]interface{}{ + "device_id": id, + "req_id": reqID, + "mode": map[bool]string{true: "video", false: "photo"}[secs > 0], + } + if secs > 0 { + out["duration_seconds"] = secs + } + // ★ 大体积数据（data_base64 / file）原样透传：录像不能只回一句「成功」。 + for _, k := range []string{"file", "data_base64", "mime", "size", "kind"} { + if v, ok := res[k]; ok { + out[k] = v + } + } + return out, nil +} + +// speakeruse 让设备朗读文字。 +func (d *devicectlDevice) speakeruse(args map[string]interface{}) (interface{}, error) { + id, _ := args["device_id"].(string) + text, _ := args["text"].(string) + textPath, _ := args["text_path"].(string) + + body, err := deviceContentArg(text, textPath, "text") + if err != nil { + return nil, err + } + res, reqID, err := d.pushHomeagentCapability(id, "speakeruse "+body, 60*time.Second) + if err != nil { + return nil, err + } + return map[string]interface{}{ + "device_id": id, + "req_id": reqID, + "spoken": len(body), + "result": res["output"], + }, nil +} + +// toIntArg 把 JSON 解出来的数字/字符串统一成 int。 +// +// 模型的 duration_seconds 有时是 30，有时是 "30"（字符串）—— +// 后者会让类型断言静默失败退回默认值，正是「参数丢了但不报错」这类毛病。 +func toIntArg(v interface{}) int { + switch x := v.(type) { + case int: + return x + case int64: + return int(x) + case float64: + return int(x) + case string: + n, err := strconv.Atoi(strings.TrimSpace(x)) + if err != nil { + return 0 + } + return n + } + return 0 +} From a25ba4b7941534c6f7411253281e3cfee523e4ae Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 6 Oct 2026 22:44:27 +0800 Subject: [PATCH 13/13] =?UTF-8?q?test(gui):=20=E4=BF=AE=20silent-start=20?= =?UTF-8?q?=E5=88=A4=E6=8D=AE=E7=9A=84=E5=AD=97=E8=8A=82=E7=AA=97=E5=8F=A3?= =?UTF-8?q?=E5=81=87=E7=BA=A2=EF=BC=88=E8=A2=AB=E6=B3=A8=E9=87=8A=E6=8C=A4?= =?UTF-8?q?=E7=88=86=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 问题 `make test` / CI 的 `npm test` 都红： ✗ 非静默时经 ready-to-show 显示 — 没有 ready-to-show → show()… ## 归因（逐提交二分） origin/main (7e4f1058) 通过 2bbbb6b8 / bca791a1 通过 3988c198 / 85d76ad4 通过 878fd770 通过 7bd569ec ★ 失败 ← 引入点 04c5883f / 5f12ea3d ★ 失败 不是本次内核改动引入；是 7bd569ec（10-05「修长时间挂后台后打开白屏」） 把 `once` 改成 `on` 时**同时补了一段解释性注释**，把 `ready-to-show` 与 `show()` 的间距从 331 字符推到 558 字符， 而判据的窗口是硬编码 `{0,120}`。 **实现是对的，判据的字节窗口太小。** ## 修法 判据该断的是**结构关系**（ready-to-show 处理器的回调里有 show()）， 不是两者相隔多少字符 —— 后者会随注释/排版无意义地红。 - 先去行注释再量（注释不该参与结构判定） - 窗口放到 400（容纳该回调体，仍远小于「跑到别的函数里」的距离） ## 验证 - 修后 `node silent-start.test.mjs` 全部通过 - ★ 变异自证仍能红：删掉 ready-to-show 处理器 → 判据报红 （证明不是把判据改松到什么都不抓） - `make test` 全绿（go test + test-gui + csrc-test + check-csrc + check-codec-cgo-only） Co-Authored-By: Claude Opus 4.8 (1M context) --- cmd/gui/silent-start.test.mjs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/cmd/gui/silent-start.test.mjs b/cmd/gui/silent-start.test.mjs index c62f8cb9..66f81220 100644 --- a/cmd/gui/silent-start.test.mjs +++ b/cmd/gui/silent-start.test.mjs @@ -67,7 +67,19 @@ check( ); check( "非静默时经 ready-to-show 显示", - /ready-to-show[\s\S]{0,120}show\(\)/.test(createBlock), + // ★ 2026-10-06：原来写死 `{0,120}` 字符窗口，被新增的**注释**挤爆而假红。 + // + // 实情：main.js 在 ready-to-show 与 show() 之间夹了 558 字符 —— 其中 + // 大部分是解释「为什么用 on 而非 once」的注释（7bd569ec 白屏修复）。 + // 实现是对的，判据的字节窗口太小。 + // + // ⇒ 判据该断的是**结构关系**（ready-to-show 处理器的回调里有 show()）， + // 不是两者相隔多少字符 —— 后者会随注释/排版无意义地红。 + // 去掉行注释后再量，且把窗口放到足够容纳该回调体。 + (() => { + const noLineComments = createBlock.replace(/\/\/[^\n]*/g, ""); + return /ready-to-show[\s\S]{0,400}show\(\)/.test(noLineComments); + })(), "没有 ready-to-show → show()，非静默启动可能白屏闪现", ); check(