jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-15 12:15:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
57bf94247463fa3060076b20c273747f4b140da3
HomeAgent/GUI-PLAN.md
JianFeeeee 57bf942474 feat(gui): 注入改 SendInput（默认）+ 用户操作时暂缓；拆解 Coopanion 桌宠动作系统 
## 拆解 Coopanion（用户指出的参考项目）
新增 DESKTOP-PET-NOTES.md，记录 Pal-AI-Lab/Coopanion 的桌宠动作系统
（packages/cortico-world-desktop-pet）：

  · 4 个工具：pet_say(气泡说话,可夹带动作标记) / pet_ask(提问,异步回答) /
    pet_walk_to(走到 0-1 比例或 left/center/right/cursor,含走到鼠标位置) /
    pet_act(只做动作; sit/sleep 是持续态)
  · 动作词表 VOCAB：10 个表情 + 13 个动作，每个词多个中文别名，
    英文 id 与中文别名进同一张 Map；未知词丢弃而非报错
  · 脚本标记：【词,词】= 先做动作再换新气泡；<词> = 打字到那里时做、不换气泡。
    让文字与动作在时间轴上对齐 —— 实现成本低但表现力强
  · 设计要点：身体是 agent 唯一可见输出通道（用户看不见消息正文）；
    互动事件不单独唤醒模型，跟着下批事件到

可借鉴（已写入文档待办）：姿态表达状态、动作与文字对齐、持续态、
动作解析容错、待机自主行为。不建议照搬：桌宠承载全部对话输出、ASR、戳摸甩。

## 注入层改 SendInput（参考它的实现）
原 PostMessage 路径只能操作原生 Win32 程序 —— Chromium/Electron 自绘界面
与游戏会忽略合成消息。这不是「平台硬限制」，是所选 API 的限制。
Coopanion 用 SendInput 注入系统输入队列，可靠性高得多。

新增三档模式 gui-prefs.deviceBridge.agentCursor：
  sendinput（默认） SendInput，可靠；会动真光标，故先等用户停手
  overlay           PostMessage，不动用户鼠标；只能操作原生程序
  real              保留旧代码路径
另有 deferMs：用户活动时最多等多久（默认 3000，上限 10000）

★ SendInput 绝对坐标是 0–65535 归一化值，不是像素。按虚拟桌面归一化
  并带 MOUSEEVENTV_VIRTUALDESK，多屏下也正确（Coopanion 只按主屏归一化）。
★ 文本用 KEYEVENTF.UNICODE 逐字符发，不受键盘布局与输入法影响（比 WM_CHAR 可靠）。

## 修「用户活动感知」把自己也算进去的 bug
GetLastInputInfo 是**全局**的 —— agent 自己的 SendInput 也被算作「用户输入」。
实测：deferMs 设 0 仍被暂缓，回执写「开始时空闲仅 0ms」，即上一条命令的
注入刚把 idleMs 清零。若不排除自身注入，会永远处于「用户正在操作」状态。

按 Coopanion 的三重判定修正：
  1. ownTick   自己最后一次注入时刻，之后 40ms 内的输入忽略
  2. ownCursor 自己放下的光标位置，偏离 >2px 说明是用户动的
  3. 无符号差值  GetTickCount 每 2^32ms 回绕，必须按无符号比较

## 修同一条命令被执行两遍
sendinput 分支把逻辑包进 runAction 箭头函数，里面的 return 只退出它自己，
于是执行完继续 fall through 到旧 real 路径。实测 8 条命令回了 16 个
cmd_result，且真光标被额外抢一次。补上外层 return。

## 判据
computeruse.test.mjs 47 条（npm test 共 131 条全绿），新增 4 条钉住本轮
踩过的坑，均做变异验证：
  · 三档模式存在（overlay/real 只在条件里，不能要求赋值形式）
  · 用户活动排除自身注入；且盯 send() 里的**调用点** —— 只查函数名时
    删掉调用仍会误报绿（已实测并改正）
  · SendInput 坐标归一化 + VIRTUALDESK
  · sendinput 分支必须 return（防双执行）

## 待办（已写入 GUI-PLAN.md）
  · loadGuiPrefs 不透传 agentCursor，导致 deferMs 配置读取不生效（实测）
  · 显式调 SetProcessDpiAwarenessContext(-4)，不依赖 Electron 默认值
  · mascot 姿态：思考/等待/出错
  · 真实点击效果仍未验证（当前环境无可注入的可见窗口）
2026-10-02 15:27:33 +08:00

320 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 已验证（端到端，8/8 有正确响应）
用假网关（自实现 WS 服务端）下发 computeruse 命令，GUI 执行并回执：
```
[error] agent-overlay: 该坐标下没有窗口（WindowFromPoint 返回空）...
[error] agent-overlay: type 需要先有点击类操作确定目标窗口
[ok] displays: [{...}] | coordinateSpace: physical-pixel (Win32 与截图像素一致, 无需换算)
[error] agent-overlay: unknown action __nope__
```
**结论：代码路径已接通，错误处理正确 —— 失败时明确报错，不静默回退到真实鼠标。**
### 3.5 ⚠️ 未完成：真实点击效果未验证
上面 7 个动作都报「该坐标下没有窗口」。原因是**当时的执行环境没有可供
注入的可见目标窗口**（`WindowFromPoint` 对所有坐标返回 null）。
**因此：「点击真的落到目标窗口上」这一步尚未被证明。** 需要在有交互桌面的
会话里跑一个端到端测试：
> 打开记事本 → agent 点它 → 输入文字 → 截图回读验证
同时验证「用户鼠标位置在全过程未变」。
### 3.6 设计取舍（明确的边界）
- **只对「接受窗口消息的程序」可靠。** 原生 Win32 程序（记事本、Excel、Office）
可靠；Chromium/Electron 自绘界面、多数游戏、DirectX 程序会忽略合成消息。
这是 Windows 消息模型的硬限制，**不是实现缺陷**。
- **不做真实鼠标降级。** 用户既然选择「不抢鼠标」，就不该偷偷改成操作真实鼠标。
失败即 `status=error` 并说明原因。
- **键盘类动作依赖先前的鼠标操作。** `keypress`/`hotkey`/`type` 不带坐标，
且后台注入不移动真实光标，所以 `GetCursorPos` 拿到的是**用户自己**的
光标位置。因此设备端记录「上次鼠标操作命中的 hwnd」，键盘动作投递到那里。
从未点过则报错。
### 3.7 跨平台状态
| 平台 | 状态 |
|---|---|
| Windows | 模式 A 已实现（效果待验证） |
| Linux | waiter 侧仍是 `xdotool`，**会动真鼠标**。未做模式 A |
| 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.3 设置页
- [ ] `agentCursor.mode` 的 UI（目前只能手改 `gui-prefs.json`）
### 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 合成的是真实设备事件）
---
## 五、坐标空间：实测结论与踩坑记录 ⚠️
**结论：截图给模型的像素、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` / 真实光标相关行为
**无法在此验证**，需在有桌面的会话实测。
Reference in New Issue View Git Blame Copy Permalink