Desktop Op 桌面操作模块

Desktop Op 是 2026-05-14 新增的通用桌面 GUI Agent 模块。它把本机窗口定位、截图、键鼠输入、VLM 验证、队列互斥和审计日志封装成后端模块，当前 MVP 只注册 WeixinAdapter，服务于 agent-channel 的 weixin-db 群聊自动回复。

目录结构

desktop_op/
├── config.ts
├── controller/admin/        # action_log 与 config 管理 API
├── entity/                  # desktop_op_config / desktop_op_action_log
├── runtime/                 # 核心运行时、输入、截图、VLM、安全护栏、适配器
└── service/                 # DesktopOpService 与配置 bootstrap

运行时拓扑

DesktopOpRuntime.runTask() 是核心执行入口：

DesktopTask
  -> SafetyGuard 校验 task/app/action
  -> AdapterRegistry 选择 AppAdapter
  -> WindowLocator 定位并激活窗口
  -> adapter.preFlightCheck()
  -> adapter.buildSteps()
  -> ActionExecutor 逐步执行 clipboard / hotkey / wait 等动作
  -> adapter.verifyResult()
  -> TaskResult

所有任务都接收 AbortSignal。运行时在开始、激活窗口后、preflight 后、每个动作前和 verify 前检查中止状态，因此 agent-channel 删除频道、关闭 weixinReply 或任务超时时可以级联取消。

服务层队列与互斥

DesktopOpService 提供两个入口：

runAndWait(task, timeoutMs)：同步等待结果，当前由 tool-system 的 weixin_send_text 调用。
enqueue(task)：fire-and-forget 留口，后续可用于异步桌面任务。

队列按 appId + adapter.queueKey(target) 分组，同一个微信会话串行执行；真正执行前还会获取全局 DesktopMutex，避免多个任务同时争用键鼠。每个 queue key 最多保留 20 个任务，溢出时写 queue-overflow 审计日志。

WeixinAdapter

runtime/adapters/weixin_adapter.ts 是当前唯一适配器：

appId = "weixin"，支持 send-text。
通过 WindowLocator.findByAppName("Weixin") 找到未最小化的最大微信窗口。
preflight 截图并用 VLM 宽松判断当前顶部对话名是否匹配目标群。
buildSteps() 固定生成 clipboard-write -> ctrl+v -> wait -> enter -> wait。
verify 再次截图并用 VLM 检查最新己方消息，但 MVP 中为避免 VLM 误判导致重复发送，build steps 成功后默认按成功处理。

这意味着 Desktop Op 当前不是完整自主 GUI 探索 Agent，而是“适配器主导的确定性动作序列 + VLM 状态验证”。

数据模型

表名	Entity	用途
`desktop_op_config`	`entity/desktop_op_config.ts`	全局白名单、危险按键、频率上限和默认水印
`desktop_op_action_log`	`entity/desktop_op_action_log.ts`	每个桌面任务的终态审计，包括 channelId、roomName、modelChannel、状态、耗时和错误

desktop_op_config 不再保存默认模型渠道；v4 约定模型来自桌面操作 Agent 自己的 modelChannelId。

与微信双 Agent 的关系

weixin-db 群聊自动回复采用双 Agent：

reply agent 读取群消息、决定是否回复，并通过 delegate_task 委托。
desktop agent 持有 weixin_desktop toolset 和 weixin_send_text 工具。
weixin_send_text 从 _netaRuntime.bizContext.channelId 和 currentAgent.modelChannelId 读取运行时上下文。
工具创建 DesktopTask(appId="weixin", actionType="send-text")，交给 DesktopOpService.runAndWait()。
Desktop Op 激活微信窗口、粘贴、发送并记录 desktop_op_action_log。

保存 weixin-db 渠道配置时，后端会自动为 desktop agent 补齐 weixin_desktop toolset，并把 weixin_send_text 配置为可在子 Agent 中使用且强制走主进程代理。

4.4 KiB Raw Blame History Unescape Escape