jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-15 12:15:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4 from JianFeeeee/feature/multimodal-and-device-tools

Browse Source 
多模态工具插件化 + 设备能力结构化工具 + get_plugin_tools 收编
This commit is contained in:
JianFeeeee
2026-10-06 22:53:50 +08:00
committed by GitHub
parent 7e4f1058ea a25ba4b794
commit 91b490d823
31 changed files with 4507 additions and 572 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
cmd/gui/chat-panel-dom.test.mjs Normal file
View File

@ -0,0 +1,149 @@
// chat 子面板 DOM 结构判据（2026-10-05）。
//
// ## 要判的是什么
//
// 实测故障：对话页里「终端 / 运行中命令 / 记忆 / 上下文 / 知识」五个页签
// 点进去全是空白，只有「对话」和「星图」正常。
//
// 根因是 **HTML 少一个 </div>**：构造星图面板的那段 HTML 里有 4 个
// <div> 开、只有 3 个 </div> 闭，于是它没闭合 —— 后面拼接的所有
// 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(
`'<div class="chat-panel active" id="chat-panel-chat">`,
);
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(/<div\b/g) || []).length;
const closes = (html.match(/<\/div>/g) || []).length;
check(
"chat 面板段落 div 标签配平",
opens === closes,
`开 ${opens} / 闭 ${closes}，差 ${opens - closes} —— ` +
"少一个 </div> 会让后面所有面板被塞进前一个面板内部（表现为空白）",
);
// ── 2) 每个 chat-panel 自身也必须配平 ─────────────────────────────
//
// 总数配平还不够：某处多一个 </div>、另一处少一个，总数仍为 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;
}
// 从该面板的 <div class="chat-panel 开始算（marker 之前最近的那个）
const from = html.lastIndexOf("<div", at);
// 到下一个 chat-panel 之前为止
const nextAt = html.indexOf("id='chat-panel-", at + marker.length);
const to = nextAt < 0 ? html.length : html.lastIndexOf("<div", nextAt);
const piece = html.slice(from, to);
const o = (piece.match(/<div\b/g) || []).length;
const c = (piece.match(/<\/div>/g) || []).length;
if (o !== c) unbalanced.push(`${name}(开${o}/闭${c})`);
}
check(
"各子面板独立配平",
unbalanced.length === 0,
unbalanced.length ? "不配平：" + unbalanced.join("、") : "",
);
// ── 3) 所有 chat-panel 必须同属一个父容器 ─────────────────────────
//
// 形态判据：源码里每个面板片段的起始处都应是独立的 <div class="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("<div", at);
const before = html.slice(Math.max(0, from - 24), from);
// 合法前缀：以 ' 结尾（字符串结束）或 '+ 结尾（仍在拼接）
if (!/'[+]?$/.test(before.trimEnd()) && !/\+\s*$/.test(before)) {
nested.push(`${name}(前缀=${JSON.stringify(before.slice(-12))})`);
}
}
check(
"各面板顶层不被嵌套进前一面板",
nested.length === 0,
nested.length
? "这些面板疑似接在未闭合结构里：" + nested.join("、")
: "",
);
// ── 汇总 ────────────────────────────────────────────────────────────
console.log("");
console.log(` chat 面板段落: <div> ${opens} / </div> ${closes}`);
console.log(` 面板数: ${PANELS.length}`);
console.log("");
if (failures > 0) {
console.log(`失败 ${failures} 条`);
process.exit(1);
}
console.log("全部通过");

177
cmd/gui/device-gateway-discovery.test.mjs Normal file
View File

@ -0,0 +1,177 @@
// 设备桥 gateway 自动发现链路的门禁。
//
// ## 要判的是什么
//
// 2026-10-05 实测故障：GUI 面板里能看到设备通道地址，但设备桥连不上。
// 日志只有一行 `ws cookie len=0` + 401，没有任何「地址来自发现」的痕迹。
//
// 根因不是配置错，是**发现结果与实际连接配置从不联通**：
//
// · 渲染进程 app.js 的 loadDiscoveredGateway() 调 /device/gateway，
// 拿到的地址只写进 **state.discoveredGateway**（UI 展示用）；
// · 主进程 startDeviceBridge() 读的是 **gui-prefs.deviceBridge.gateway**；
// · 两边从未交换过 —— state 是渲染进程内存，prefs 是主进程文件。
//
// 于是服务端明明已经通过 /device/gateway 告诉了客户端正确地址
// （proxy.go:1078 生成的 url_portal），GUI 却仍在用用户几个月前
// 手填的旧地址，且**永远 401/ECONNREFUSED，且不重试**。
//
// ## 判据形态：文本扫描而非运行时
//
// 与 endpoint-align / device-align 同路子。自动回写的触发点在
// loadDiscoveredGateway() 内，由 refreshAll 的 15s 定时器驱动 ——
// 构造那个时序需要真Electron + 真后端，而 /device/gateway 还要求
// 会话 cookie（CI 里没有）。故从源码文本判「链路是否接通」。
//
// 运行：node device-gateway-discovery.test.mjs
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";
const here = dirname(fileURLToPath(import.meta.url));
const APP = join(here, "renderer", "app.js");
const MAIN = join(here, "main.js");
const PRELOAD = join(here, "preload.js");
let failures = 0;
const check = (name, ok, detail) => {
if (ok) {
console.log(` ✓ ${name}`);
} else {
failures++;
console.log(` ✗ ${name}${detail ? " — " + detail : ""}`);
}
};
const appSrc = readFileSync(APP, "utf8");
const mainSrc = readFileSync(MAIN, "utf8");
const preloadSrc = readFileSync(PRELOAD, "utf8");
// ── 1) 发现函数存在且会调服务端权威端点 ────────────────────────────
check(
"存在 /device/gateway 发现调用",
appSrc.includes("/device/gateway"),
"找不到 —— 服务端发现端点没被调用",
);
// ── 2) 发现结果必须回写到主进程（本判据的核心）──────────────────────
//
// 这是本次修复的要点。若这段回写被删掉（重构时不慎），设备桥会退回
// 「只用用户手填地址」的行为，且没有任何报错——
// 这正是 2026-10-05 那次故障的形态。
check(
"发现结果回写到主进程 deviceBridge.set",
/discoveredGateway[\s\S]{0,600}?deviceBridge\s*\.\s*set\s*\(/.test(appSrc),
"loadDiscoveredGateway 里没有 deviceBridge.set 回写 —— " +
"state.discoveredGateway 只用于 UI，主进程仍在用旧的手填地址",
);
// ── 3) 回写不得覆盖用户手填值 ──────────────────────────────────────
//
// 发现只做**缺省补全**。若用户在设置页手填了内网直连地址（灰度实例、
// 绕过反代），自动回写把它冲掉就是新的回归。判据钉住「本地为空才写」。
// 注意不能用 /set\(\s*\{[\s\S]{0,300}?\}/ —— 调用点前后的 if 判断在花括号
// **外面**，而 300 字窗口会跨到下一个 deviceBridge.set（saveBridgeChannel
// 的手动保存），判据就误报了。改为直接取「发现函数体内」的那次调用。
const discoFn = appSrc.match(
/async function loadDiscoveredGateway\(\)[\s\S]*?\n}/,
);
const setCall = discoFn
? discoFn[0].match(/window\.homeagent\.deviceBridge\.set\([^)]*\)/)
: null;
check(
"回写前检查本地 gateway 为空",
discoFn ? /cur\s*&&\s*!cur\.gateway/.test(discoFn[0]) : false,
discoFn
? "回写处没看到「本地已配置则跳过」的判断 —— 会覆盖用户手填值"
: "找不到 loadDiscoveredGateway",
);
check(
"回写只传 gateway，不覆盖 token",
setCall ? !/token/.test(setCall[0]) : false,
setCall ? "回写里带了 token —— 发现端点不返回设备令牌，会写坏" : "找不到回写调用",
);
// ── 4) IPC 链路完整：preload 暴露 get/set，主进程处理 ──────────────
//
// 回写用的是 window.homeagent.deviceBridge.set(...)；contextBridge
// 若没暴露或主进程没注册，这次调用是 undefined TypeError（被 catch
// 吞掉，于是又回到「静默不生效」）。
check(
"preload 暴露 deviceBridge.set",
/deviceBridge[\s\S]{0,120}?set\s*:/.test(preloadSrc),
"contextBridge 未暴露 set —— 渲染进程调不到",
);
check(
"主进程注册 device-bridge:set",
mainSrc.includes('ipcMain.handle("device-bridge:set"'),
"主进程没有该 handler",
);
check(
"主进程 device-bridge:get 返回明文 token",
/device-bridge:get[\s\S]{0,900}?token:\s*db\.token/.test(mainSrc),
"get 未返回 token 明文 —— 渲染侧拿不到设备令牌",
);
// ── 5) device-bridge:set 必须真正重启桥 ───────────────────────────
//
// 只存 prefs 不重启，配置不会立即生效（要等下次进程启动）。
// 这是同一类「存了但没生效」的静默失效。
// 不用大正则匹配整个 handler —— 返回对象里的嵌套 } 会让边界判断很脆。
// 改为取两个 handler 之间的**源码切片**，再在里面判 stop/start 是否存在。
const setStart = mainSrc.indexOf('ipcMain.handle("device-bridge:set"');
const setEnd = mainSrc.indexOf('ipcMain.handle("prefs:get"');
const setHandler =
setStart >= 0 && setEnd > setStart
? mainSrc.slice(setStart, setEnd)
: null;
check(
"device-bridge:set 会重启设备桥",
setHandler
? setHandler.includes("stopDeviceBridge") &&
setHandler.includes("startDeviceBridge")
: false,
setHandler
? "handler 里没有 stop+start —— 新配置要等重启进程才生效"
: "找不到 device-bridge:set handler",
);
// ── 6) 主进程连接必须带 token ─────────────────────────────────────
//
// 设备桥 WS 走 ?token=（registry.go ServeWS 只认 query/X-API-Key/
// Sec-WebSocket-Protocol 三种，**cookie 不参与** acceptBind）。
// 这是实测踩过的坑：曾误以为发 cookie 就能过，实际服务端仍 401。
const connectFn = mainSrc.match(
/function connectDeviceWS[\s\S]*?\n}\n/,
);
check(
"connectDeviceWS 把 token 放进 query",
connectFn ? /token=/.test(connectFn[0]) : false,
connectFn
? "query 里没带 token —— 服务端 acceptBind 会拒"
: "找不到 connectDeviceWS",
);
// ★ keepalive 与重连的判据**不在本文件**，在同目录的
// device-bridge-liveness.test.mjs —— 那份用 node:vm 把真实函数抽出来跑
// 「连接 → 断线 → 重连 → 再断线」，数真实的 ping 帧与重连次数。
// 本文件早期版本曾用文本判据盯keepalive（grep 0x89、找 setInterval 的
// 间隔），已删：它只能证明「代码里出现过这些字符」，证明不了「心跳真的
// 发出去了」「重连真的发生了」。两份盯同一件事时，弱的那份会在实现重构
// 时先红，掩盖真信号。
// ── 汇总 ────────────────────────────────────────────────────────────
console.log("");
if (failures > 0) {
console.log(`失败 ${failures} 条`);
process.exit(1);
}
console.log("全部通过");

423
cmd/gui/main.js
View File

@ -442,16 +442,60 @@ function createWindow(show = true) {
});
// 静默时不显示；非静默时在首帧就绪后显示，避免白屏闪现。
if (show) {
mainWindow.once("ready-to-show", () => {
try {
//
// ★ 用 on 而不是 once（2026-10-05 修白屏）：once 只等一次，首帧之后
// 监听就没了。而窗口可能被系统回收后重建、或GPU 重启后重新 load，
// 那时都需要再show 一次 —— once 的写法让那些路径静默失败。
mainWindow.on("ready-to-show", () => {
if (!show) return;
try {
if (mainWindow && !mainWindow.isDestroyed() && !mainWindow.isVisible()) {
mainWindow.show();
} catch (e) {}
});
}
}
} catch (e) {}
});
mainWindow.loadFile(path.join(__dirname, "renderer", "index.html"));
// ★ renderer 崩溃自愈（2026-10-05 修「长时间挂后台后打开白屏」）。
//
// 现象：GUI 在后台挂很久（数小时）后，从托盘打开是**白屏**，且不会自愈。
//
// 原因链：
// 长时间后台 → Chromium 回收 renderer 的 GPU context（或渲染进程
// 本身被判定 hung 杀掉）→ 窗口对象仍在、isVisible() 仍返回 true，
// 但内容是空的 → showMainWindow() 的 `if (!isVisible()) show()` 被跳过
// → 托盘点一下，窗口出现但是白的，永远不会好。
//
// 之前全代码没有任何 render-process-gone / unresponsive 监听，所以这条
// 路径完全无感知。仓库历史上有过「白屏修复(惰性Tray)」提交，但那只修了
// **首次**显示时机，没管**长期后台后**。
mainWindow.webContents.on("render-process-gone", (e, details) => {
console.error(
"[window] renderer gone: " + (details && details.reason) +
" (exitCode=" + (details && details.exitCode) + ")",
);
// OOM 之外的都重建；OOM（reason==="oom"）重建只会立刻再崩一次，
// 只记录日志避免反复重启把机器拖死。
if (details && details.reason === "oom") return;
try {
if (mainWindow && !mainWindow.isDestroyed()) {
mainWindow.reload();
}
} catch (err) {
console.error("[window] reload after crash failed: " + err.message);
}
});
// renderer 活着但无响应（主线程被长任务卡死）：此时页面还在，
// 只是不响应。给一次刷新机会，不自动刷（误判会让正在用的用户丢状态）。
mainWindow.webContents.on("unresponsive", () => {
console.error("[window] renderer unresponsive");
});
mainWindow.webContents.on("responsive", () => {
console.log("[window] renderer responsive again");
});
if (process.argv.includes("--dev")) {
mainWindow.webContents.openDevTools();
}
@ -922,6 +966,18 @@ let deviceBridgeAddr = ""; // 设备桥网关地址
// 连接成功但 bind 被拒时设备是失联的，只看 connected 会给出假阳性。
let deviceBridgeBound = false;
let deviceBridgeBindError = "";
// 设备桥心跳与重连的状态（心跳 + 线性退避重连）。
let devicePingTimer = null;
let deviceReconnectTimer = null;
let deviceReconnectAttempt = 0;
// 拉起意图：用户主动停用后置 false，作为 scheduleDeviceReconnect 的闸。
let deviceWanted = false;
// 当前生效的连接配置，重连时复用（连接断开后局部变量就没了）。
//
// 缓存而非每次读 gui-prefs：重连是定时器里的异步路径，重读偏好会引入
// 「读到半写文件」与「用户刚改完就按新值连」两种意外；且重连必须用
// **当初启动时那份**配置，否则退避语义就乱了。
let deviceBridgeCfg = null;
// 音频/媒体接收聚合缓冲（服务端分块推送二进制→聚合→播放）
let speechAccum = null;
@ -1137,6 +1193,9 @@ function connectDeviceWS(url, token, onMsg) {
);
}
opened = true;
// 心跳不在这里起：统一由 connectDeviceBridgeOnce 在拿到 ws.__sock
// 后调 startDevicePing。放这里的话心跳会跟着「每次 connectDeviceWS
// 调用」起，而不是跟着「一条实际连上的桥」起——重连路径上会漏。
resolve({
send: (obj) => sendDeviceFrame(sock, JSON.stringify(obj)),
__sock: sock, // 暴露底层 socket 供二进制分块发送
@ -1209,11 +1268,243 @@ function connectDeviceWS(url, token, onMsg) {
if (!opened) reject(e);
});
sock.on("close", () => {
// 断开时停掉心跳，否则定时器会一直持有已死的 socket。
stopDevicePing();
deviceBridge = null;
// 已建立过的连接被对端/中间链路关掉 ⇒ 排程重连。
// scheduleDeviceReconnect 内部有 deviceWanted 闸，用户主动停用
// 时不会把桥拉起来。
if (opened) scheduleDeviceReconnect();
});
});
}
// ============ 设备桥心跳 + 断线重连 ============
//
// ★ 这里修的是 2026-10-05 实测到的两个洞，合起来的效果是
// 「一次失联，终身失联」：
//
// 1. **不发 ping**。waiter 侧有 pingLoop（internal/devicebridge/client/
// bridge.go，每 30s 一个 0x9 帧），GUI 侧全文件一次 ping 都没发过。
// 而 remotedevice 服务端**没有设备侧读超时**（registry.go 里没有
// SetReadDeadline）—— 不发心跳就没人能发现设备已死，网关会把一台
// 半死的设备长期显示为 online。
//
// 实测症状：bind 能成功（bind_ok）、设备进了 devices 表（面板可见），
// 但几秒后 push 就报
// {"error":"device gui-JianF not online"}
// —— conns 表已被 defer 里的 markOffline 清空，而 devices 表还在。
// 「可见但不可下发」就是这个割裂的表象。
//
// 2. **不重连**。原来 startDeviceBridge 只有启动/配置变更两个调用点，
// 失败就 console.error 结束。GUI 是最容易被休眠/切网/服务端重启打断的
// 形态（合盖一次、WiFi 抖一下、服务端重启），设备桥就再也回不来，
// 直到用户重启 GUI 或手动改一次配置。
//
// 判据：cmd/gui/device-bridge-liveness.test.mjs（用 node:vm 抽真实函数
// 在沙箱里跑「连接→ 断线 → 重连 → 再断线」，数真实的 ping 帧与重连次数）。
// 与 waiter 的 pingLoop 对齐（bridge.go:636 每 30s 一个 0x9 帧）。
const devicePingIntervalMs = 30000;
// 重连退避：线性增长、封顶 60s。首个等待 = base。
const deviceReconnectBaseMs = 2000;
const deviceReconnectMaxMs = 60000;
// 发送 WS 控制帧（客户端帧必须带掩码位，RFC6455 §5.3）。
//
// 通用签名而非写死 ping：控制帧有 ping(0x9)/pong(0xA)/close(0x8) 三种，
// 写死一种就换不来另外两种。payload 为 null 表示空载荷。
function sendDeviceControlFrame(sock, opcode, payload) {
const body = payload ? Buffer.from(payload) : Buffer.alloc(0);
const mask = crypto.randomBytes(4);
const masked = Buffer.alloc(body.length);
for (let i = 0; i < body.length; i++) masked[i] = body[i] ^ mask[i % 4];
const len = masked.length;
let hdr;
if (len < 126) {
hdr = Buffer.from([0x80 | opcode, 0x80 | len]);
} else if (len < 65536) {
hdr = Buffer.alloc(4);
hdr[0] = 0x80 | opcode;
hdr[1] = 0x80 | 126;
hdr.writeUInt16BE(len, 2);
} else {
hdr = Buffer.alloc(10);
hdr[0] = 0x80 | opcode;
hdr[1] = 0x80 | 127;
hdr.writeBigUInt64BE(BigInt(len), 2);
}
sock.write(Buffer.concat([hdr, mask, masked]));
}
// 启动心跳（先清旧的，避免重复 interval 叠加）。
function startDevicePing(sock) {
if (devicePingTimer) clearInterval(devicePingTimer);
devicePingTimer = setInterval(() => {
try {
if (!sock || sock.destroyed) return;
sendDeviceControlFrame(sock, 0x9, null);
} catch (e) {
/* 心跳失败不致命：close 事件会触发重连 */
}
}, devicePingIntervalMs);
}
function stopDevicePing() {
if (devicePingTimer) {
clearInterval(devicePingTimer);
devicePingTimer = null;
}
}
// 排程一次重连。退避随失败次数线性增长并封顶。
//
// ★ deviceWanted 是闸：用户主动 stopDeviceBridge（或改配置）之后
// 再排程，就会把已停用的桥偷偷拉起来。GUI 是常驻托盘程序，
// 这个「拉起来」没人看得见，表现为「我明明关了怎么又在连」。
function scheduleDeviceReconnect() {
if (!deviceWanted) return;
if (deviceReconnectTimer) return; // 已有排程，不叠加
// 先递增后算：首次排程（含连接失败那一回）拿到的就是 base，
// 之后 2×base、3×base… 线性增长。用 max(1, attempt) 会在
// attempt=0 与 1 时都算出 base，出现「退避头两次一样」的假象。
deviceReconnectAttempt++;
const delay = Math.min(
deviceReconnectBaseMs * deviceReconnectAttempt,
deviceReconnectMaxMs,
);
deviceReconnectTimer = setTimeout(async () => {
deviceReconnectTimer = null;
if (!deviceWanted) return;
const cfg = deviceBridgeCfg;
// 配置被清空（用户改了偏好）⇒ 无处可连，停在这里等下一次 start。
if (!cfg) {
deviceReconnectAttempt = 0;
return;
}
try {
await connectDeviceBridgeOnce(cfg);
// 连上了：退避归零。下次若再断，重新从 base 开始 ——
// 否则「昨天断十次、今天又断一次」要等 10×base 才有第一次重试。
deviceReconnectAttempt = 0;
} catch (e) {
console.error("[device-bridge] reconnect failed: " + e.message);
scheduleDeviceReconnect();
}
}, delay);
}
// startDeviceBridge 拆出的「只做一次连接」部分：重连走这里。
async function connectDeviceBridgeOnce(cfg) {
const url = cfg.url || cfg.gateway || "";
const token = cfg.apiKey || cfg.token || "";
deviceBridgeAddr = url;
deviceBridgeBound = false;
// doConnectDeviceBridge 内部会建 ws、起心跳、并存进 deviceBridge。
// 不用它的返回值：那层把结果写全局而非return，两边约定不一致时
// 「读返回值」就得到 undefined，随后 ws.send 直接TypeError。
await doConnectDeviceBridge(cfg);
const ws = deviceBridge;
if (!ws) {
throw new Error("connect produced no bridge");
}
// host/cpus/mem 的推导包在try 里：它们在 ws.send 的实参里，而 send 之前
// 抛错会被 startDeviceBridge 的 catch 吞成「连接失败」—— 实际连接是好的，
// 表现为「反复重连但永远连不上」。拿不到主机信息不该阻断设备登记。
let host = "";
let cpus = 0;
let totalMem = 0;
let appVersion = "";
let platform = "";
let arch = "";
let nodeVersion = "";
let electronVersion = "";
try {
host = devOs.hostname() || "";
cpus = devOs.cpus ? devOs.cpus().length : 0;
totalMem = devOs.totalmem ? devOs.totalmem() : 0;
} catch (e) {
// 忽略：device_id 退化为 gui-local。
}
try {
appVersion = app && app.getVersion ? app.getVersion() : "";
} catch (e) {}
// process 单独包：electron 主进程有，但判据的 vm 沙箱只注入了 Buffer/Math/
// crypto —— 这里抛错会让 ws.send 之前就中断，被上层 catch 吞成
// 「连接失败」，而实际连接是好的（表现为无限重连）。
try {
platform = process.platform || "";
arch = process.arch || "";
nodeVersion =
(process.versions && process.versions.node) || "";
electronVersion =
(process.versions && process.versions.electron) || "";
} catch (e) {}
if (!deviceBridgeId) {
deviceBridgeId =
"gui-" + (host || "local").replace(/[^a-zA-Z0-9_-]/g, "_");
}
let authorized = false;
try {
authorized = !!(
guiPrefs &&
guiPrefs.deviceBridge &&
guiPrefs.deviceBridge.authorized
);
} catch (e) {}
ws.send({
op: "hello",
device: {
device_id: deviceBridgeId,
name: "HomeAgent GUI",
kind: "computer",
authorized: authorized,
caps: [
"status",
"cmdrun",
"deviceinfo",
"cmdresult",
"computeruse",
"screensee",
"clipboardsee",
"clipboardsue",
"speakeruse",
"camerasue",
"screensue",
"omniparse",
],
info: {
hostname: host,
platform: platform,
arch: arch,
os_release: "",
node_version: nodeVersion,
electron_version: electronVersion,
version: appVersion,
cpus: cpus,
total_mem_bytes: totalMem,
},
},
});
ws.send({ op: "bind", device_id: deviceBridgeId, token });
console.log("[device-bridge] connected as " + deviceBridgeId + " @ " + url);
}
// 真实连接：建 WS、起心跳、登记到全局。
//
// 「连上」与「开始对它发心跳」是同一件事的两半，放一函数里，重连路径
// 才不会漏掉心跳。
async function doConnectDeviceBridge(cfg) {
const ws = await connectDeviceWS(
cfg.url || cfg.gateway || "",
cfg.apiKey || cfg.token || "",
onDeviceMsg,
);
startDevicePing(ws.__sock);
deviceBridge = ws;
return ws;
}
// 发送 WS text 帧（客户端加掩码）
function sendDeviceFrame(sock, text) {
const payload = Buffer.from(text, "utf8");
@ -2842,59 +3133,38 @@ async function startDeviceBridge(cfg) {
return;
}
deviceBridgeAddr = url;
deviceBridgeId =
"gui-" + (devOs.hostname() || "local").replace(/[^a-zA-Z0-9_-]/g, "_");
// 记住配置：重连时要用（连接断开后局部变量就没了）。
deviceBridgeCfg = { url, token };
// 拉起意图。scheduleDeviceReconnect 以此为闸 —— 用户主动停用后
// 不得再排程重连。
deviceWanted = true;
deviceReconnectAttempt = 0;
if (deviceReconnectTimer) {
clearTimeout(deviceReconnectTimer);
deviceReconnectTimer = null;
}
try {
const ws = await connectDeviceWS(url, token, onDeviceMsg);
deviceBridge = ws;
ws.send({
op: "hello",
device: {
device_id: deviceBridgeId,
name: "HomeAgent GUI",
kind: "computer",
authorized: guiPrefs?.deviceBridge?.authorized || false, // 客户端自报授权状态
caps: [
"status",
"cmdrun",
"deviceinfo",
"cmdresult",
"computeruse",
"screensee",
"clipboardsee",
"clipboardsue",
"speakeruse",
"camerasue",
"screensue",
"omniparse",
],
info: {
hostname: devOs.hostname() || "",
platform: process.platform || "",
arch: process.arch || "",
os_release: "", // 不提权读取 /etc/os-release，避免破坏沙箱；如需可在白名单命令里由 agent 探
node_version:
process.versions && process.versions.node
? process.versions.node
: "",
electron_version:
process.versions && process.versions.electron
? process.versions.electron
: "",
version: app.getVersion ? app.getVersion() : "",
cpus: devOs.cpus ? devOs.cpus().length : 0,
total_mem_bytes: devOs.totalmem ? devOs.totalmem() : 0,
},
},
});
ws.send({ op: "bind", device_id: deviceBridgeId, token });
console.log("[device-bridge] connected as " + deviceBridgeId + " @ " + url);
await connectDeviceBridgeOnce(deviceBridgeCfg);
// 首次就连上：退避归零。
deviceReconnectAttempt = 0;
} catch (e) {
console.error("[device-bridge] connect failed: " + e.message);
// ★ 连接失败也必须排程重连 —— 这条路上**没有** socket close 事件
// （socket 从未 upgraded），若只把重连挂在 close 上，首次失败就
// 永远不会自愈。
scheduleDeviceReconnect();
}
}
function stopDeviceBridge() {
// 先断意图，再拆资源：顺序反了会让 close 事件里的排程再把桥拉起来。
deviceWanted = false;
stopDevicePing();
if (deviceReconnectTimer) {
clearTimeout(deviceReconnectTimer);
deviceReconnectTimer = null;
}
deviceReconnectAttempt = 0;
if (deviceBridge) {
try {
deviceBridge.close();
@ -3151,9 +3421,30 @@ function initTray() {
function showMainWindow() {
try {
if (mainWindow && !mainWindow.isDestroyed()) {
// ★ 健康检查（2026-10-05 修白屏）：仅靠 isVisible() 不够。
//
// 长时间后台后 renderer 可能已被回收 —— 窗口句柄还在、isVisible()
// 仍为 true，但内容是空的。此时原逻辑会跳过 show()，从托盘打开
// 就是一片白，而且永远不会自愈。
//
// 两个判据：
// isCrashed() —— 渲染进程已死，必须重载才能出内容；
// isLoading() —— 还在加载，等ready-to-show 就行，不重载。
const wc = mainWindow.webContents;
if (wc.isCrashed()) {
console.log("[window] renderer crashed, reloading before show");
try {
wc.reload();
} catch (e) {}
}
// 窗口是静默创建时已处于「未显示」态，这里正常显示即可。
// 用 showInactive + focus 两步：showInactive 不抢焦点地显示，
// focus 再把焦点给过来（纯 show 在部分 Win 版本上会导致
// 无边框窗口不获得焦点，用户还得再点一下）。
if (!mainWindow.isVisible()) mainWindow.show();
mainWindow.focus();
try {
mainWindow.focus();
} catch (e) {}
return;
}
} catch (e) {
@ -3282,6 +3573,25 @@ app.on("activate", () => {
createWindow();
}
});
// GPU 进程崩溃/重启后，无边框窗口（frame:false）在部分驱动上会停在
// 上一帧不再重绘 —— 表现同样是「窗口在、内容不动或全白」。
// `child-process-gone` 比 `render-process-gone` 覆盖面更广（含 GPU），
// 这里只在 GPU 挂掉时重载渲染进程（不重建窗口，避免丢窗口位置/尺寸）。
app.on("child-process-gone", (e, details) => {
const type = details && details.type;
const reason = details && details.reason;
if (type !== "GPU") return;
console.error("[window] GPU process gone: reason=" + reason);
if (reason === "oom" || reason === "launch-failed") return;
try {
if (mainWindow && !mainWindow.isDestroyed()) {
mainWindow.webContents.reload();
}
} catch (err) {
console.error("[window] reload after GPU crash failed: " + err.message);
}
});
// ============ 系统通知（Electron 原生）============
//
// 之前**完全没有**这个能力：主进程没引入 Notification、preload 没暴露接口、
@ -3314,10 +3624,9 @@ ipcMain.handle("notify:show", (_, payload) => {
urgency: p.urgent ? "critical" : "normal",
});
n.on("click", () => {
if (mainWindow && !mainWindow.isDestroyed()) {
if (!mainWindow.isVisible()) mainWindow.show();
mainWindow.focus();
}
// 走 showMainWindow 而非直接 show：它带renderer 健康检查，
// 直接 show 在 renderer 已被回收时会开出一个白窗口。
showMainWindow();
try {
mainWindow.webContents.send("notify:clicked", { id: id, msgKey: p.msgKey || "" });
} catch (e) {}

131
cmd/gui/renderer/app.js
View File

@ -761,6 +761,29 @@ async function loadDiscoveredGateway() {
(d && d.available && (d.url_portal || d.url)) || "";
if (state.discoveredGateway) {
console.log("[device-bridge] discovered gateway: " + state.discoveredGateway);
// ★ 回写到主进程，让设备桥**真的**用上发现结果。
//
// 此前发现只停在state.discoveredGateway（UI 展示用），而主进程的
// startDeviceBridge 读的是 gui-prefs.deviceBridge.gateway ——
// 两者从不联通。症状：GUI 面板里能看到设备通道地址，但设备桥连不上，
// 而日志只有一行 ws cookie len=0，没有任何“地址来自发现”的痕迹。
//
// 仅当本地未配置 gateway 时才写：手填的值优先（用户可能故意指向
// 内网直连或灰度实例），发现只做**缺省补全**。
if (window.homeagent && window.homeagent.deviceBridge) {
try {
var cur = await window.homeagent.deviceBridge.get();
if (cur && !cur.gateway && state.discoveredGateway) {
await window.homeagent.deviceBridge.set({ gateway: state.discoveredGateway });
console.log(
"[device-bridge] gateway auto-configured from discovery: " +
state.discoveredGateway,
);
}
} catch (e2) {
console.log("[device-bridge] auto-config skipped: " + e2.message);
}
}
}
} catch (e) {
state.discoveredGateway = "";
@ -1850,7 +1873,7 @@ function buildChatLayout() {
'<div class="chat-panel" id="chat-panel-starmap"><div class="card"><h2>' +
__("星图", "Star Map") +
"</h2>" +
'<div id="sm-container-chat" style="display:flex;align-items:center;justify-content:center;min-height:480px"><div class="ha-dots-panel"><span class="ha-dots ha-dots-lg"><i></i><i></i><i></i></span></div></div></div>';
'<div id="sm-container-chat" style="display:flex;align-items:center;justify-content:center;min-height:480px"><div class="ha-dots-panel"><span class="ha-dots ha-dots-lg"><i></i><i></i><i></i></span></div></div></div></div>';
html +=
'<div class="chat-panel" id="chat-panel-terminal"><div class="card"><h2>' +
__("终端", "Terminal") +
@ -3043,12 +3066,98 @@ function initChatStarmap() {
starmapAnimate();
}
function buildChatStarmapGraph() {
starmapNodeMeshes.forEach((m) => {
starmapScene.remove(m);
// ★ 几何体/材质共享（2026-10-05 修星图内存暴涨）
//
// 原实现每个节点都`new THREE.SphereGeometry(gr, 16, 12)`——因为半径
// gr 各不相同，看起来「只能各自 new」。但 three.js 里几何体的大小应当由
// **mesh.scale** 表达，几何体本身应当共享。
//
// 实测（CDP 抓生产实例，2588 个节点）：
//
// Mesh/SphereGeometry 2588 个 geometry 数据合计 22.67MB
// Sprite/BufferGeometry 1294 个（label 纹理，每个 256×64 RGBA ≈ 64KB）
//
// 两者都不释放：buildChatStarmapGraph 只starmapScene.remove(m)，
// **从不 dispose()** —— remove 只把对象从场景树摘下来，WebGL 侧资源
// （buffer/texture）仍被引用，不释放。星图每次全量重建泄漏一整轮，
// 于是进程常驻内存反复冲上GB 级、靠 GC 回收后再度暴涨，界面随之卡住。
//
// 修法两条：单位球共享（几何体从 2588 份降到 1 份）+ 重建时 dispose。
// 单位球细节：SphereGeometry(1, 16, 12) 建一次，实例按 gr 缩放，
// 因为 mesh 是父节点，缩放会叠加到子 glow 上—— 所以 glow 挂到 mesh 下时
// 要用 gr/rad 的相对比例。
// ★ 单位球几何体的**半径取0.5**，不是 1。
//
// 原因：节点缩放基准是 mesh.userData.baseScale = rad / 0.5 ——
// 分母0.5 就是原SphereGeometry 的半径。若把共享球改成半径 1，
// baseScale 会整体缩放一倍（大的节点变得更大、小的更小），且与
// 脉冲结束时的复原逻辑（setScalar(baseScale)）不自洽。
// 保持 0.5 ⇒ baseScale 公式原样成立，行为与修复前逐像素一致。
var starmapUnitSphere = null;
function starmapSphereGeometry() {
if (!starmapUnitSphere) starmapUnitSphere = new THREE.SphereGeometry(0.5, 16, 12);
return starmapUnitSphere;
}
// 释放一个 three.js 子树占用的 GPU 资源（geometry / material / texture）。
//
// 递归处理子树：节点 mesh 下挂着 glow sphere（子 mesh）与 label sprite，
// 只 dispose 顶层会漏掉子节点的资源。
//
// 共享资源要防误 dispose：starmapUnitSphere 被全场景共用，
// dispose 掉它会让仍在渲染的 mesh 变黑/报错 —— 用 seen 集合兜底。
function disposeStarmapObject(root) {
var seenGeo = new Set();
var seenMat = new Set();
var seenTex = new Set();
if (starmapScene) starmapScene.remove(root);
root.traverse(function (o) {
var g = o.geometry;
if (g && g.dispose && !seenGeo.has(g) && g !== starmapUnitSphere) {
seenGeo.add(g);
g.dispose();
}
var m = o.material;
if (!m) return;
var mats = Array.isArray(m) ? m : [m];
mats.forEach(function (mm) {
if (!mm || seenMat.has(mm)) return;
seenMat.add(mm);
// 纹理在 material.map / 上多通道贴图上。
Object.keys(mm).forEach(function (k) {
var v = mm[k];
if (v && v.isTexture && !seenTex.has(v)) {
seenTex.add(v);
v.dispose();
}
});
if (mm.dispose) mm.dispose();
});
});
starmapEdgeLines.forEach((l) => {
starmapScene.remove(l);
if (root.geometry && root.geometry.dispose &&
root.geometry !== starmapUnitSphere && !seenGeo.has(root.geometry)) {
root.geometry.dispose();
}
var rm = root.material;
if (rm && !Array.isArray(rm) && !seenMat.has(rm)) {
Object.keys(rm).forEach(function (k) {
var v = rm[k];
if (v && v.isTexture && !seenTex.has(v)) v.dispose();
});
if (rm.dispose) rm.dispose();
}
}
function buildChatStarmapGraph() {
// ★ 先释放上一轮的 GPU 资源，再重建（2026-10-05 修内存暴涨）。
//
// 原实现只 remove 不 dispose。remove 只改场景树，geometry/material/texture
// 仍占着 WebGL 资源；节点数还会随记忆增长，于是泄漏只增不减。
starmapNodeMeshes.forEach(function (m) {
disposeStarmapObject(m);
});
starmapEdgeLines.forEach(function (l) {
disposeStarmapObject(l);
});
starmapNodeMeshes = [];
starmapEdgeLines = [];
@ -3184,7 +3293,7 @@ function buildChatStarmapGraph() {
var rad = 0.5 + mnr * 2.0;
var col = smTypeColors[n.type] || 0xcccccc;
var ei = 0.3 + mnr * 0.7;
var g = new THREE.SphereGeometry(rad, 16, 12);
var g = starmapSphereGeometry();
var mat = new THREE.MeshPhongMaterial({
color: col,
emissive: col,
@ -3200,8 +3309,12 @@ function buildChatStarmapGraph() {
// 缩放后」的值，而不是 set(1,1,1)—— 那会把大节点缩成最小尺寸。
mesh.userData.baseScale = rad / 0.5;
// Glow sphere
// Glow sphere —— 共享单位球，靠 scale 表达半径（详见 starmapSphereGeometry）。
var gr = rad * 1.2 + mnr * 0.5;
var gg = new THREE.SphereGeometry(gr, 16, 12);
// mesh 已按 rad/baseScale 缩放过（baseScale = rad/0.5），故 glow 用
// 相对比例：世界半径 gr = mesh 缩放 × 本地 scale。
var parentScale = mesh.scale.x || 1;
var gg = starmapSphereGeometry();
var gm = new THREE.MeshBasicMaterial({
color: col,
transparent: true,
@ -3210,6 +3323,8 @@ function buildChatStarmapGraph() {
blending: THREE.AdditiveBlending,
});
var gs = new THREE.Mesh(gg, gm);
// 共享球半径 0.5，故要 ×2 才是单位半径的相对值。
gs.scale.setScalar((gr / parentScale) * 2);
mesh.add(gs);
mesh.userData.glowSphere = gs;
// Label sprite

14
cmd/gui/silent-start.test.mjs
View File

@ -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(

213
cmd/gui/starmap-gpu-lifecycle.test.mjs Normal file
View File

@ -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("全部通过");

192
cmd/gui/window-liveness.test.mjs Normal file
View File

@ -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("全部通过");

16
internal/agent/core/agent.go
View File

@ -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 自建

13
internal/agent/core/eventloop.go
View File

@ -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})

95
internal/agent/core/media.go
View File

@ -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")
}

138
internal/agent/core/multimodal_departed_test.go Normal file
View File

@ -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()
}

47
internal/agent/core/offload_test.go
View File

@ -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
}

224
internal/agent/core/plugin_tools_service_test.go Normal file
View File

@ -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 确认没把真插件的归属也打死。
//
// 前缀规则对「确实是 <plugin>_<tool>」有意义（外部插件如 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(),
})
}

131
internal/agent/core/plugins.go
View File

@ -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
}
// 前缀规则只对「确实是 <plugin>_<tool>」形态的名字有意义
// （例如外部插件的 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）。
//
// 原实<E58E9F><E5AE9E><EFBFBD>只收 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
}

169
internal/agent/core/queue_access_test.go Normal file
View File

@ -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)
}
}

28
internal/agent/core/scheduler.go
View File

@ -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 —— 刚抢占成功的中断（抢占必须立即生效）

6
internal/agent/core/scheduler_test.go
View File

@ -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 任务不得同时留在就绪队列")
}

11
internal/agent/core/toolcall.go
View File

@ -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 {

40
internal/agent/core/tooldefs.go
View File

@ -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 那套权限梯度要防的事。
//
// 留在这里的是**待<><E5BE85>退场**的部分：下面这一大块 pendingMedia 只服务于
// 那三个工具的工具面。input 通路（processInput 直接把 media block
// 拼进本轮请求）**不依赖它**，所以可安全移除。
// 退场顺序见 docs 或本次提交的说明；先确保插件侧能力等价。
//
// ⇒ describe_image / transcribe_audio / ocr_image 现在由插件注册，
// 不再出现在这里。pendingMedia 的清理在本次一并处理。
return tools
}

129
internal/plugins/mcp/calltool_error_test.go Normal file
View File

@ -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 应报错")
}
}

61
internal/plugins/mcp/client.go
View File

@ -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
}

621
internal/plugins/multimodal/plugin.go
View File

@ -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 ""
}

120
internal/plugins/multimodal/plugin_test.go Normal file
View File

@ -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)
}
}

21
internal/plugins/remotedevice/binary_test.go
View File

@ -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 命名会把同内容存成多份、
// 不同内容却可能覆盖 —— 摘要后缀两<E7BC80><E4B8A4><EFBFBD>都避免。
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_<digest>.mp4，实际 %s", base)
}
got, err := os.ReadFile(fp)
if err != nil {
@ -402,14 +409,15 @@ 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 })
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))
@ -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：默认走落盘 + 回路径；旧的自<E79A84><E887AA><EFBFBD>描述路径用 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)
}

373
internal/plugins/remotedevice/capability_tools_test.go Normal file
View File

@ -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
// <!DOCTYPE html>…<meta charset=\\\"utf-8\\\">…
// 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)
}
// 协议形状：<capability> <秒数> <内容>（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 := `<meta charset="utf-8"><div style="color:red">A B C</div>`
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 := "<h1>看板</h1>" + strings.Repeat("<p>x</p>", 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)
}
}

592
internal/plugins/remotedevice/device.go
View File

@ -1,9 +1,14 @@
package remotedevice
import (
"crypto/sha256"
"encoding/base64"
"encoding/json"
"fmt"
"log"
"os"
"sort"
"strconv"
"strings"
"time"
@ -18,7 +23,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" }
@ -60,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秒> — 录像 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 查询结果。" +
"若设备未授权或离线，返回错误信息。",
@ -77,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"},
},
@ -94,17 +106,91 @@ 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: "查看一台已授权设备的屏幕当前画面（截屏回传）。" +
"与 screensue（向用户屏幕显示内容）配对：screensue 是给用户看，screensee 是你看。" +
"返回屏幕截图的自动视觉描述；如需读取屏上文字可接着用 ocr_image。" +
Description: "截取一台已授权设备的当前屏幕画面。\n" +
"与 screensue（向用户屏幕显示内容）配对：screensue 是给用户看，screensee 是你看。\n" +
"★★ 返回的是截图的**落盘路径**与元信息（file/mime/size/sha256/width/height），" +
"**不含画面内容**。要看画面或读屏上文字，必须接着调用：" +
"describe_image(path=<file>) 看画面，或 ocr_image(path=<file>) 读文字。" +
"两步缺一不可——本工具不会自动描述任何东西。\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"},
},
@ -159,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"},
},
},
{
@ -193,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":
@ -361,12 +459,16 @@ 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
}
// 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)
@ -401,16 +503,79 @@ func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, e
return nil, fmt.Errorf("设备截屏失败: %s", errMsg)
}
output, _ := res["output"].(string)
// 设备端回传 data URL（data:image/jpeg;base64,...）或裸 base64
if !strings.HasPrefix(output, "data:") {
output = "data:image/jpeg;base64," + output
// ★ 2026-10-05：把回传内容**量化后记进服务端日志**。
//
// 起因：2026-10-05 生产日志里有两次 screensee 回了
// 「我目前没有收到或无法查看这张屏幕截图」
// 而服务端**没有任何记录**能回答「设备到底回传了什么」——
// GUI 侧那行 console.log 只打在它自己的控制台，服务端留不下痕迹。
// 于是排查只能靠猜（截屏为空？data URL 被截断？缩略图未就绪？）。
//
// 只记**元信息 + 极短内容指纹**，不记图片本身（日志会膨胀且含用户屏幕内容）：
// · 字节数、解出来的像素尺寸（jpeg/png 头部可解）、是否非空
// · 前若干字节的 base64 片段 + SHA256 前 16 hex
// ⇒ 「回传的是不是同一张图」「是不是被截断了」一眼可判。
logScreenseePayload(id, 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
meta, err := d.reg.SaveInlineMedia("screensee_"+reqID, output, "image/jpeg")
if err != nil {
d.reg.SaveResult(reqID, map[string]interface{}{
"error": err.Error(),
"device": id,
"has_image": true, // 图确实拿到了，只是没落盘
})
return nil, fmt.Errorf("截图已回传但落盘失败（无法交付给多模态工具）: %w", err)
}
desc := d.seeHandler(output, provider)
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：向设备下发鼠标/键盘控制命令。
@ -543,12 +708,34 @@ 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) == 0 {
return nil, fmt.Errorf("content 文件为空: %s", content)
}
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 +770,348 @@ 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
}
// ---- 三个结构化能力工具（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
// <!DOCTYPE html>…<meta charset=\\\"utf-8\\\">…
// 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 三个工具都是
// 「拼 <capability> <args> → 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) + " "
}
// 协议：<capability> <可选的秒数> <内容>（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
}

194
internal/plugins/remotedevice/inline_media_test.go Normal file
View File

@ -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[:])
}

128
internal/plugins/remotedevice/plugin.go
View File

@ -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\":\"<id>\",\"payload\":{\"op\":\"cmd\",\"req_id\":\"<rid>\",\"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
@ -318,9 +337,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 +375,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 +446,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)
}

89
internal/plugins/remotedevice/push_validation_test.go Normal file
View File

@ -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)
}
})
}
}

165
internal/plugins/remotedevice/registry.go
View File

@ -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:[<mime>][;base64],<payload>
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
// 媒体落盘模式：写入 <mediaDir>/<reqID>.<ext>，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)
}

369
internal/plugins/remotedevice/screensee_truth_test.go Normal file
View File

@ -0,0 +1,369 @@
package remotedevice
import (
"bytes"
"encoding/base64"
"encoding/json"
"errors"
"image"
"image/color"
"image/jpeg"
"image/png"
"net/http"
"net/http/httptest"
"os"
"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 })
// auto_describe 需要落盘目录先存在（默认路径也会落盘）
reg.SetMediaDir(t.TempDir())
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", "auto_describe": true})
// ★ 必须报错
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,
}))
}
}
}()
// ★★ 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)
}
m, ok := res.(map[string]interface{})
if !ok {
t.Fatalf("返回类型变了: %T", res)
}
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("auto_describe 下 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 不应被判为模型名问题")
}
}