883 lines
38 KiB
Markdown
883 lines
38 KiB
Markdown
# GUI Agent MCP Server — Plan 计划文档
|
||
|
||
> **文档类型**: Plan（计划文档）— 描述"如何实现"，定义技术方案与架构设计
|
||
>
|
||
> **基于**: `specs/gui-agent/gui-agent.md` Spec 规范文档
|
||
>
|
||
> **模块路径**: `crates/agent-gui-server/`
|
||
>
|
||
> **日期**: 2026-03-18
|
||
|
||
---
|
||
|
||
## 1. 技术架构
|
||
|
||
### 1.1 模块划分
|
||
|
||
```
|
||
crates/agent-gui-server/
|
||
├── src/
|
||
│ ├── index.ts # CLI 入口: 参数解析 + 启动 MCP Server
|
||
│ ├── lib.ts # SDK 入口: 导出 createGuiAgentMcpServer()
|
||
│ ├── config.ts # 统一配置: 环境变量解析、校验、Fail Fast
|
||
│ │
|
||
│ ├── mcp/ # MCP 协议层（外部接口）
|
||
│ │ ├── server.ts # MCP Server 实例 (stdio + HTTP 双模式)
|
||
│ │ ├── atomicTools.ts # 13 个原子操作 tool handler
|
||
│ │ ├── taskTools.ts # gui_execute_task 互斥执行 + 进度通知
|
||
│ │ └── resources.ts # MCP Resources (status/permissions/audit)
|
||
│ │
|
||
│ ├── agent/ # Agent 循环引擎（gui_execute_task 内部）
|
||
│ │ ├── taskRunner.ts # 循环核心: pi-mono session + 截图→LLM→操作
|
||
│ │ ├── systemPrompt.ts # GUI Agent system prompt 模板
|
||
│ │ ├── memoryManager.ts # 三层记忆管理 (Summary/Recent/Pending) + LLM 摘要压缩
|
||
│ │ └── stuckDetector.ts # 卡死检测: 连续截图相似度比对
|
||
│ │
|
||
│ ├── desktop/ # 桌面操作层（底层能力封装）
|
||
│ │ ├── screenshot.ts # 截图管线: capture → scale → JPEG → base64
|
||
│ │ ├── mouse.ts # 鼠标: click/doubleClick/move/drag/scroll
|
||
│ │ ├── keyboard.ts # 键盘: type/pressKey/hotkey
|
||
│ │ ├── clipboard.ts # 剪贴板: CJK粘贴、备份恢复
|
||
│ │ ├── display.ts # 显示器: 列表、scaleFactor、全局偏移
|
||
│ │ └── imageSearch.ts # 图像查找 (nut.js template matcher)
|
||
│ │
|
||
│ ├── coordinates/ # 坐标系统（核心难点，独立目录）
|
||
│ │ ├── resolver.ts # CoordinateResolver: 模型坐标 → 逻辑坐标 → 全局坐标
|
||
│ │ └── modelProfiles.ts # 模型配置表: 坐标模式、坐标顺序
|
||
│ │
|
||
│ ├── safety/ # 安全层
|
||
│ │ ├── hotkeys.ts # 危险热键黑名单拦截
|
||
│ │ └── auditLog.ts # 环形缓冲审计日志
|
||
│ │
|
||
│ └── utils/
|
||
│ ├── logger.ts # 日志: stderr + 可选文件
|
||
│ ├── platform.ts # 平台检测、权限检查
|
||
│ └── errors.ts # 结构化错误类型
|
||
│
|
||
├── tests/ # Vitest 测试
|
||
├── package.json
|
||
├── tsconfig.json
|
||
└── vitest.config.ts
|
||
```
|
||
|
||
**关键设计决策**：
|
||
|
||
- **`desktop/` vs `tools/`**: Spec 用了 `tools/` 但会与 MCP 的 "tool" 概念冲突。底层桌面操作命名为 `desktop/`，与 MCP 工具层 (`mcp/`) 明确分离。MCP handler 调 desktop 层，desktop 层不知道 MCP 存在（依赖反转）
|
||
- **`coordinates/` 独立目录**: 坐标转换是核心难点（7+ 模型配置 + 三步转换 + 多屏偏移），独立提升可维护性和可测试性
|
||
|
||
### 1.2 模块依赖关系
|
||
|
||
```
|
||
index.ts → config.ts → mcp/server.ts
|
||
│
|
||
┌───────────┴───────────┐
|
||
▼ ▼
|
||
mcp/atomicTools.ts mcp/taskTools.ts
|
||
│ │
|
||
▼ ▼
|
||
safety/* (前置检查) agent/taskRunner.ts
|
||
│ │
|
||
▼ ├── agent/systemPrompt.ts
|
||
desktop/* ├── agent/memoryManager.ts (三层记忆 + LLM 摘要)
|
||
│ ├── agent/stuckDetector.ts
|
||
▼ └── pi-mono (LLM + tool calling)
|
||
coordinates/resolver.ts │
|
||
│ ▼
|
||
▼ desktop/* (复用)
|
||
coordinates/modelProfiles.ts
|
||
```
|
||
|
||
**数据流 — 原子操作** (`gui_click`):
|
||
```
|
||
MCP tool call → atomicTools → hotkeys.validate()
|
||
→ resolver.resolve(x, y, mode, meta) → display.getGlobalOffset()
|
||
→ mouse.click(globalX, globalY) → auditLog.record() → MCP response
|
||
```
|
||
|
||
**数据流 — 完整任务** (`gui_execute_task`):
|
||
```
|
||
MCP tool call → taskTools.executeTask(taskText, extra)
|
||
→ mutex.acquire()（确保同时只有一个 GUI 任务）
|
||
→ taskRunner.run(taskText, extra.signal) → Agent 循环 {
|
||
screenshot.capture() → agent.prompt(taskText + screenshot)
|
||
→ Agent 内部自动循环:
|
||
transformContext(messages) → 截图裁剪 + 记忆注入
|
||
→ convertToLlm(messages)
|
||
→ LLM 调用 → 返回 tool call
|
||
→ beforeToolCall → hotkeys.validate() 安全检查
|
||
→ tool.execute() → resolver + desktop 操作 → delay(stepDelayMs)
|
||
→ afterToolCall → auditLog.record()
|
||
→ turn_end 事件 → memory.finalizeStep() + stuckDetector.check()
|
||
每步通过 extra.sendNotification() 推送进度
|
||
监听 extra.signal.aborted 处理取消 → agent.abort()
|
||
} → mutex.release() → MCP response (steps + finalScreenshot + result)
|
||
|
||
连接断开 → AbortSignal 自动触发 → Agent 循环终止 → mutex 释放
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 关键技术决策
|
||
|
||
### 2.1 pi-mono 的使用边界
|
||
|
||
| 场景 | 使用哪个包 | 具体 API |
|
||
|------|:---:|------|
|
||
| 原子操作 (gui_click 等) | 不使用 pi-mono | 纯工具执行，无需 LLM |
|
||
| gui_execute_task 的 Agent 循环 | `@mariozechner/pi-agent-core` | `Agent` 类：内置循环、工具执行、事件流、abort |
|
||
| gui_execute_task 的 LLM 调用 | `@mariozechner/pi-ai` | `getModel(provider, modelId)` 获取模型实例，Agent 内部自动调用 |
|
||
| gui_execute_task 的工具注册 | `@mariozechner/pi-agent-core` | `AgentTool` 接口 + TypeBox schema + `execute` 函数 |
|
||
| 上下文压缩 | `@mariozechner/pi-agent-core` | Agent 构造参数 `transformContext` hook |
|
||
| 安全层（热键拦截 + 审计） | `@mariozechner/pi-agent-core` | Agent 构造参数 `beforeToolCall` / `afterToolCall` hook |
|
||
| 记忆摘要的 LLM 调用 | `@mariozechner/pi-ai` | 独立 `complete(memoryModel, context)` 调用（不走 Agent 循环） |
|
||
| 进度通知 | `@mariozechner/pi-agent-core` | `agent.subscribe(event)` 事件系统 |
|
||
|
||
**关键认识**：pi-mono 的 `Agent` 类已经内置了完整的 Agent 循环（LLM 调用 → 解析 tool call → 执行工具 → 再次调 LLM），**我们不需要手写循环**。taskRunner 的职责是配置 Agent 实例、注册工具、接入钩子。
|
||
|
||
MCP Server 和 pi-mono Agent 是**两个独立的框架**，各司其职：
|
||
- MCP Server 负责外部协议（文本 Agent 调用）
|
||
- pi-mono Agent 负责内部 Agent 循环（LLM + tool calling）
|
||
|
||
### 2.2 nut.js 而非 robotjs
|
||
|
||
robotjs 已停止维护（2018），不支持 Apple Silicon 和 Node 22。nut.js 活跃维护，跨平台，async API，逻辑坐标空间与我们的坐标转换链路契合。
|
||
|
||
### 2.3 gui_execute_task 同步执行 + 互斥锁
|
||
|
||
**同步阻塞**：
|
||
- `gui_execute_task` 是标准的 MCP tool call，handler 内部 await Agent 循环完成后返回结果
|
||
- MCP SDK 的 tool handler 支持长时间 `Promise<Result>` 返回，无需异步队列
|
||
|
||
**互斥锁**：
|
||
- 桌面同一时间只能有一个 GUI 操作者，通过 `Mutex` 确保同时只有一个 `gui_execute_task` 在执行
|
||
- 第二个调用会等待锁释放后再执行（不拒绝，排队等待）
|
||
|
||
**进度通知**（MCP SDK 原生）：
|
||
- 客户端在 `_meta.progressToken` 中传入 token
|
||
- handler 通过 `extra.sendNotification({ method: 'notifications/progress', params: { progressToken, progress, total, message } })` 推送每步进度
|
||
|
||
**取消**（MCP SDK 原生）：
|
||
- handler 中 `extra.signal`（AbortSignal）由 SDK 自动注入
|
||
- 客户端取消请求或连接断开时，signal 自动触发
|
||
- handler 监听 signal → 调用 pi-mono `agent.abort()` 终止循环
|
||
- 无需手动管理 session 或自定义 abort 工具
|
||
|
||
### 2.4 截图管线: nut.js + sharp
|
||
|
||
- nut.js `screen.capture(region)` 获取原始 RGBA Buffer（物理分辨率）
|
||
- sharp 做 resize（`kernel: 'lanczos3'`）+ JPEG 编码（`quality: 75`）
|
||
- sharp 已在 monorepo 中验证可用
|
||
|
||
### 2.5 SDK 嵌入模式
|
||
|
||
`lib.ts` 导出 `createGuiAgentMcpServer(config)` 工厂函数，供 Electron 客户端未来直接 import 集成。package.json 中 `"main": "./dist/lib.js"` 导出 SDK，`"bin"` 导出 CLI。
|
||
|
||
---
|
||
|
||
## 3. 各模块详细设计
|
||
|
||
### 3.1 config.ts — 统一配置
|
||
|
||
- 解析所有 `GUI_AGENT_*` 环境变量，返回类型安全的 `GuiAgentConfig` 对象
|
||
- 必填字段（如 `API_KEY`）缺失时直接 throw，进程退出（Fail Fast）
|
||
- 数值参数做范围校验（jpegQuality 1-100，maxSteps 1-200）
|
||
- `coordinateMode` 为空时表示自动匹配（由 modelProfiles 决定）
|
||
|
||
### 3.2 coordinates/modelProfiles.ts — 模型配置表
|
||
|
||
**内置模型配置表**：
|
||
|
||
| 模型名匹配规则 | 坐标模式 | 坐标顺序 | 说明 |
|
||
|---------------|---------|---------|------|
|
||
| `claude-*` | `image-absolute` | `xy` | Anthropic Computer Use API 标准格式 |
|
||
| `gpt-4o*`, `gpt-5*` | `image-absolute` | `xy` | OpenAI CUA |
|
||
| `gemini*` | `normalized-999` | **`yx`** | Google Gemini，坐标顺序是 `[y, x]` 而非 `[x, y]`，这是 Google 训练数据的固有格式 |
|
||
| `ui-tars*` | `normalized-1000` | `xy` | UI-TARS |
|
||
| `qwen2.5-vl*`, `qwen-vl*` | `image-absolute` | `xy` | 通义千问 VL |
|
||
| `cogagent*` | `image-absolute` | `xy` | CogAgent |
|
||
| `seeclick*`, `showui*` | `normalized-0-1` | `xy` | SeeClick/ShowUI |
|
||
| **未匹配（fallback）** | `image-absolute` | `xy` | 保守策略 |
|
||
|
||
**截图分辨率策略（统一，不按模型区分）**：
|
||
|
||
不同模型的坐标转换都会经过归一化步骤（`modelX / imageWidth` 或 `modelX / 1000` 等），数学上与截图发送的分辨率无关。因此**不需要按模型匹配不同截图分辨率**，也**不做 28/32 等倍数对齐**（云端 API 服务端内部会处理 padding，本地部署场景暂不考虑）。
|
||
|
||
采用统一的分级缩放策略（参考 TuriX-CUA）：
|
||
|
||
1. 物理截图必须缩放到**逻辑分辨率**（吸收 scaleFactor），否则坐标会偏移 scaleFactor 倍
|
||
2. 逻辑分辨率仍然过大时，按最长边分级等比缩放：
|
||
|
||
| 逻辑分辨率最长边 | 缩放策略 | 示例 |
|
||
|----------------|---------|------|
|
||
| ≤ 1920 | 不缩放 | 1440×900 → 1440×900 |
|
||
| 1921 ~ 2560 | 等比缩放到最长边 1920 | 2560×1440 → 1920×1080 |
|
||
| > 2560 | 等比缩放到最长边 1920 | 3840×2160 → 1920×1080 |
|
||
|
||
3. 转 JPEG quality=75 进一步压缩
|
||
|
||
**Gemini 坐标顺序特殊处理**：
|
||
|
||
Gemini 模型输出坐标格式为 `[y_min, x_min, y_max, x_max]`（点坐标为 `[y, x]`），与其他所有模型的 `[x, y]` 相反。这是 Google 训练数据的固有格式，**切换为 `[x, y]` 会导致性能显著下降**。CoordinateResolver 必须在归一化前根据 `coordinateOrder` 做 swap。
|
||
|
||
**实现逻辑**：
|
||
- `getModelProfile(modelName)` → `ModelProfile { coordinateMode, coordinateOrder }`
|
||
- `coordinateOrder` 默认 `xy`，Gemini 为 `yx`
|
||
- 环境变量 `GUI_AGENT_COORDINATE_MODE` 可覆盖坐标模式
|
||
- 未匹配 fallback: `image-absolute` + `xy`
|
||
- 扩展新模型只需在数组中加一条正则规则
|
||
|
||
### 3.3 coordinates/resolver.ts — CoordinateResolver
|
||
|
||
**核心四步转换**（纯函数，零 I/O，高可测试性）：
|
||
|
||
1. **坐标顺序修正**: 根据 `coordinateOrder` 处理
|
||
- `xy`（默认）: 不变，`rawX = modelX, rawY = modelY`
|
||
- `yx`（Gemini）: swap，`rawX = modelY, rawY = modelX`
|
||
2. **归一化** (0~1): 根据 coordinateMode 处理
|
||
- image-absolute: `normX = rawX / imageWidth`
|
||
- normalized-1000: `normX = rawX / 1000`
|
||
- normalized-999: `normX = rawX / 999`
|
||
- normalized-0-1: `normX = rawX`（直接用）
|
||
3. **逻辑坐标**: `localX = normX × logicalWidth`
|
||
4. **全局偏移**: `globalX = localX + display.origin.x`
|
||
|
||
边界校验：结果 clamp 到目标显示器范围内，超出记 warning。
|
||
|
||
### 3.4 desktop/screenshot.ts — 截图管线
|
||
|
||
1. 获取目标显示器信息（bounds、scaleFactor）
|
||
2. nut.js `screen.capture(region)` 截取目标显示器区域（物理分辨率）
|
||
3. 缩放到逻辑分辨率（吸收 scaleFactor）；若逻辑分辨率最长边 > 1920，等比缩放到最长边 1920
|
||
4. sharp resize（`kernel: 'lanczos3'`）+ JPEG encode（`quality: 75`）
|
||
5. 检查字节数是否超限，超限则降 quality 重试
|
||
6. 返回 `ScreenshotResult`（base64 + 完整元数据）
|
||
|
||
### 3.5 desktop/keyboard.ts + clipboard.ts — 文本输入
|
||
|
||
**typeText 智能路由**:
|
||
- 包含非 ASCII (`/[^\x00-\x7F]/`) 或长度 > 50 → clipboard.pasteText()
|
||
- 否则 → nut.js keyboard.type()
|
||
|
||
**clipboard.pasteText 流程**:
|
||
1. 读取当前剪贴板（通过 `clipboardy` 库，跨平台）
|
||
2. 写入目标文本
|
||
3. 模拟 Cmd+V (macOS) / Ctrl+V (Win/Linux)
|
||
4. 等待 100ms
|
||
5. 恢复原剪贴板（try-catch 包裹，失败不阻断主流程）
|
||
|
||
### 3.6 agent/taskRunner.ts — Agent 循环引擎
|
||
|
||
**核心认识**：pi-mono 的 `Agent` 类已经内置完整的 Agent 循环（LLM 调用 → 解析 tool call → 执行工具 → 再次调 LLM）。taskRunner **不需要手写循环**，职责是：配置 Agent 实例、注册工具、接入钩子、管理生命周期。
|
||
|
||
> TuriX-CUA 使用独立的 Brain + Actor 两个角色。我们 v1 简化为单角色：一个 LLM 同时分析截图 + 输出操作，但**记忆管理参考 TuriX-CUA 的三层架构**。
|
||
|
||
**Agent 实例创建**：
|
||
|
||
```typescript
|
||
import { Agent } from '@mariozechner/pi-agent-core';
|
||
import { getModel, complete } from '@mariozechner/pi-ai';
|
||
import { Type } from '@sinclair/typebox';
|
||
|
||
// getModel() 是强类型泛型 API，动态配置需使用 as any 绕过编译期检查
|
||
// pi-mono 内部会校验 provider+model 组合是否有效，无效时 throw
|
||
const model = getModel(config.provider as any, config.model as any);
|
||
const memoryModel = getModel(
|
||
(config.memoryProvider ?? config.provider) as any,
|
||
(config.memoryModel ?? config.model) as any,
|
||
);
|
||
const memoryManager = new MemoryManager(memoryModel);
|
||
|
||
const agent = new Agent({
|
||
initialState: {
|
||
systemPrompt: buildSystemPrompt(taskText, memoryManager.compose()),
|
||
model,
|
||
thinkingLevel: 'off',
|
||
tools: guiTools, // AgentTool[] — 见下方工具定义
|
||
messages: [],
|
||
},
|
||
|
||
// 工具串行执行（GUI 操作同一屏幕不能并行）
|
||
toolExecution: 'sequential',
|
||
|
||
// 上下文转换：截图丢弃（注意：记忆文本通过 systemPrompt 注入，不在这里）
|
||
transformContext: async (messages, signal) => {
|
||
return memoryManager.pruneScreenshots(messages);
|
||
},
|
||
|
||
// 消息格式转换：AgentMessage[] → LLM Message[]
|
||
convertToLlm: (messages) =>
|
||
messages.filter(m => ['user', 'assistant', 'toolResult'].includes(m.role)),
|
||
|
||
// 安全层：工具执行前拦截危险热键
|
||
beforeToolCall: async ({ toolCall, args }) => {
|
||
if (toolCall.name === 'computer_hotkey') {
|
||
const blocked = hotkeys.validate(args.keys);
|
||
if (blocked) return { block: true, reason: `Blocked dangerous hotkey: ${args.keys}` };
|
||
}
|
||
},
|
||
|
||
// 审计层：工具执行后记录日志
|
||
// 注意：isError 是独立字段，不是 result.isError
|
||
afterToolCall: async ({ toolCall, args, result, isError }) => {
|
||
auditLog.record({ tool: toolCall.name, args, success: !isError });
|
||
},
|
||
});
|
||
```
|
||
|
||
**运行任务**：
|
||
|
||
```typescript
|
||
async function runTask(taskText: string, signal: AbortSignal): Promise<TaskResult> {
|
||
// 1. 截取初始截图
|
||
const screenshot = await desktop.screenshot.capture(displayIndex);
|
||
|
||
// 2. 订阅事件 → 推送 MCP 进度通知 + 记忆管理
|
||
// 注意：subscribe 回调是同步的，异步操作不能在回调中 await
|
||
agent.subscribe((event) => {
|
||
switch (event.type) {
|
||
case 'turn_end':
|
||
stepCount++;
|
||
// finalizeStep 是异步的（可能触发 LLM 摘要），放入 Promise 队列
|
||
pendingMemoryWork = memoryManager.finalizeStep(stepCount, evaluateStep(event))
|
||
.then(() => {
|
||
// 记忆更新后，刷新 systemPrompt（包含最新的 compose() 文本）
|
||
agent.state.systemPrompt = buildSystemPrompt(taskText, memoryManager.compose());
|
||
});
|
||
stuckDetector.check(latestScreenshot);
|
||
onProgress({ step: stepCount, status: 'running' });
|
||
// maxSteps 限制
|
||
if (stepCount >= config.maxSteps) agent.abort();
|
||
break;
|
||
}
|
||
});
|
||
|
||
// 3. 发起 prompt — Agent 内部自动循环
|
||
// 循环终止条件：LLM 返回纯文本（无 tool call）→ stopReason: "stop"
|
||
// 或 agent.abort() → stopReason: "aborted"
|
||
await agent.prompt(taskText, [
|
||
{ type: 'image', data: screenshot.image, mimeType: screenshot.mimeType }
|
||
]);
|
||
|
||
// 4. 等待最后一次记忆压缩完成
|
||
await pendingMemoryWork;
|
||
|
||
// 5. 返回结果
|
||
return buildTaskResult(agent.state.messages);
|
||
}
|
||
|
||
// 外部 abort → agent.abort()
|
||
function abort() { agent.abort(); }
|
||
```
|
||
|
||
**内部工具定义**（`AgentTool` 接口）：
|
||
|
||
```typescript
|
||
const guiTools: AgentTool[] = [
|
||
{
|
||
name: 'computer_screenshot',
|
||
label: 'Screenshot',
|
||
description: '截取当前屏幕',
|
||
parameters: Type.Object({}),
|
||
execute: async (toolCallId, params, signal) => {
|
||
const shot = await desktop.screenshot.capture(displayIndex);
|
||
latestScreenshot = shot;
|
||
return {
|
||
content: [{ type: 'image', data: shot.image, mimeType: shot.mimeType }],
|
||
details: { imageWidth: shot.imageWidth, imageHeight: shot.imageHeight },
|
||
};
|
||
},
|
||
},
|
||
{
|
||
name: 'computer_click',
|
||
label: 'Click',
|
||
description: '鼠标点击指定坐标',
|
||
parameters: Type.Object({
|
||
x: Type.Number(),
|
||
y: Type.Number(),
|
||
button: Type.Optional(Type.String()),
|
||
}),
|
||
execute: async (toolCallId, params, signal) => {
|
||
const { globalX, globalY } = resolver.resolve(params.x, params.y, profile, screenshotMeta);
|
||
await desktop.mouse.click(globalX, globalY, params.button);
|
||
// 操作后等待 UI 渲染（延迟放在工具内部，而非 subscribe 回调）
|
||
await delay(config.stepDelayMs);
|
||
return { content: [{ type: 'text', text: `Clicked (${globalX}, ${globalY})` }], details: {} };
|
||
},
|
||
},
|
||
// computer_type, computer_scroll, computer_hotkey, computer_wait 同理...
|
||
// 每个操作类工具的 execute 末尾都包含 await delay(config.stepDelayMs)
|
||
{
|
||
name: 'computer_done',
|
||
label: 'Done',
|
||
description: '任务完成，调用此工具表示任务已完成',
|
||
parameters: Type.Object({
|
||
result: Type.String({ description: '任务完成的结果描述' }),
|
||
}),
|
||
execute: async (toolCallId, params, signal) => {
|
||
// computer_done 的 tool result 返回给 LLM 后，
|
||
// LLM 应输出纯文本总结（无 tool call），Agent 循环自然终止（stopReason: "stop"）。
|
||
// system prompt 中明确指导：调用 computer_done 后不要再调其他工具。
|
||
return { content: [{ type: 'text', text: params.result }], details: { done: true } };
|
||
},
|
||
},
|
||
];
|
||
```
|
||
|
||
**Agent 循环终止机制**：
|
||
|
||
pi-mono Agent 的循环在以下条件终止：
|
||
1. **LLM 返回纯文本**（无 tool call）→ `stopReason: "stop"` — `computer_done` 走这条路：工具返回结果后，LLM 看到 "任务完成" 的 tool result，输出纯文本总结，循环自然结束
|
||
2. **`agent.abort()`** → `stopReason: "aborted"` — maxSteps 超限或外部 abort 走这条路
|
||
3. **context overflow** → `stopReason: "error"` — 可通过 `isContextOverflow()` 检测
|
||
|
||
**记忆文本注入方式**：
|
||
|
||
记忆文本（`compose()` 输出）通过 **systemPrompt 动态更新**注入，而非通过 `transformContext` 注入消息。原因：
|
||
- `transformContext` 操作的是 `AgentMessage[]`，注入合成消息会干扰 Agent 内部的消息追踪
|
||
- `agent.state.systemPrompt` 可直接赋值更新，在下一次 LLM 调用时生效
|
||
- 在 `turn_end` 事件回调中更新 systemPrompt，时机正确（当前轮结束、下一轮开始之前）
|
||
|
||
**pi-mono Agent 事件流（单轮示例）**：
|
||
|
||
```
|
||
agent.prompt(taskText + screenshot)
|
||
├─ agent_start
|
||
├─ turn_start
|
||
│ ├─ message_start { userMessage }
|
||
│ ├─ message_end { userMessage }
|
||
│ ├─ message_start { assistantMessage }
|
||
│ ├─ message_update { toolcall_delta: "computer_click..." }
|
||
│ ├─ message_end { assistantMessage with toolCall }
|
||
│ ├─ tool_execution_start { computer_click, args }
|
||
│ ├─ tool_execution_end { result }
|
||
│ ├─ message_start { toolResultMessage }
|
||
│ └─ message_end { toolResultMessage }
|
||
├─ turn_end { message, toolResults }
|
||
├─ turn_start ← 自动下一轮（因为有 tool call）
|
||
│ └─ ... (LLM 看到 tool result → 继续决策)
|
||
└─ agent_end { messages }
|
||
```
|
||
|
||
### 3.7 agent/memoryManager.ts — 三层记忆管理
|
||
|
||
**参考 TuriX-CUA 的三层记忆架构**，实现 LLM 驱动的上下文压缩。
|
||
|
||
#### 3.7.1 三层记忆结构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ summaryMemory（摘要记忆） │
|
||
│ 预算: summaryBudget = 2000 字符 │
|
||
│ 内容: 更早步骤的高度压缩摘要 │
|
||
│ 超限时: 调 memory_model 做"摘要的摘要" │
|
||
├──────────────────────────────────────────────────────┤
|
||
│ recentMemory（近期记忆） │
|
||
│ 预算: recentBudget = 500 字符 │
|
||
│ 内容: 最近完成的步骤记录 + 评估结果 │
|
||
│ 超限时: 调 memory_model 总结 → 移入 summaryMemory │
|
||
├──────────────────────────────────────────────────────┤
|
||
│ pendingMemory（进行中） │
|
||
│ 不计入预算 │
|
||
│ 内容: 当前正在执行的步骤 │
|
||
│ 完成后: 移入 recentMemory │
|
||
└──────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 3.7.2 核心 API
|
||
|
||
```typescript
|
||
class MemoryManager {
|
||
// 三层记忆
|
||
private summaryMemory: string = '';
|
||
private recentMemory: string = '';
|
||
private pendingMemory: string = '';
|
||
|
||
// 预算配置
|
||
private recentBudget: number = 500; // 字符数
|
||
private summaryBudget: number = 2000; // 字符数 (4x recentBudget)
|
||
private screenshotKeepCount: number = 3; // 保留最近 N 步的完整截图
|
||
|
||
// 记忆模型（用于 LLM 摘要，独立于主 Agent）
|
||
private memoryModel: Model;
|
||
|
||
/** 当前步骤开始 — 记录到 pendingMemory */
|
||
addPendingStep(stepId: number, goal: string): void;
|
||
|
||
/** 当前步骤完成 — 从 pending 移入 recent，触发压缩检查 */
|
||
async finalizeStep(stepId: number, evaluation: 'success' | 'failed'): Promise<void>;
|
||
|
||
/** 组合三层记忆为文本，用于注入 systemPrompt */
|
||
compose(): string;
|
||
|
||
/**
|
||
* 接入 Agent 的 transformContext hook
|
||
* 职责：仅处理截图 base64 裁剪（记忆文本通过 systemPrompt 注入，不在这里）
|
||
* 1. 丢弃超过 screenshotKeepCount 步的截图 base64
|
||
* 2. token 硬限制兜底（从最旧消息开始强制移除图片）
|
||
*/
|
||
pruneScreenshots(messages: AgentMessage[]): AgentMessage[];
|
||
}
|
||
```
|
||
|
||
**与 pi-mono 的集成方式**：
|
||
|
||
- `pruneScreenshots` 作为 `transformContext` hook 传入 Agent，每次 LLM 调用前自动执行，只负责截图裁剪
|
||
- **记忆文本通过 `agent.state.systemPrompt` 注入**：在 `turn_end` 事件回调中调用 `buildSystemPrompt(taskText, memoryManager.compose())` 更新 systemPrompt，下一轮 LLM 调用时生效
|
||
- `finalizeStep` 在 `turn_end` 事件回调中调用（异步，可能触发 LLM 摘要）
|
||
- 记忆摘要使用独立的 `complete(memoryModel, context)` 调用，不走 Agent 循环
|
||
- pi-mono 的 `Usage` 对象提供了 provider 返回的实际 token 数（`usage.input`），可用于更准确的 token 预算判断（替代 `text.length / 3` 估算）
|
||
|
||
#### 3.7.3 压缩触发流程（参考 TuriX-CUA）
|
||
|
||
```
|
||
finalizeStep(stepId, evaluation)
|
||
│
|
||
│ 将 pending 行移入 recentMemory:
|
||
│ "Step {stepId} | Eval: {evaluation} | Goal: {goal}"
|
||
│
|
||
│ 检查: recentMemory.length > recentBudget (500)?
|
||
│ ├── 否 → 返回
|
||
│ └── 是 ↓
|
||
│
|
||
│ 调 memory_model 生成摘要:
|
||
│ 输入: recentMemory 全文
|
||
│ 输出: { summary: string } ← 结构化 JSON
|
||
│ │
|
||
│ summaryMemory += summary
|
||
│ recentMemory = '' ← 清空
|
||
│ │
|
||
│ 检查: summaryMemory.length > summaryBudget (2000)?
|
||
│ ├── 否 → 返回
|
||
│ └── 是 ↓
|
||
│
|
||
│ 调 memory_model 做二次压缩:
|
||
│ 输入: summaryMemory 全文
|
||
│ 输出: { summary: string } ← 更高层摘要
|
||
│ │
|
||
│ summaryMemory = summary ← 替换
|
||
```
|
||
|
||
#### 3.7.4 compose() — 组合输出
|
||
|
||
```typescript
|
||
compose(): string {
|
||
const parts: string[] = [];
|
||
if (this.summaryMemory) {
|
||
parts.push(`[Summarized history]\n${this.summaryMemory}`);
|
||
}
|
||
if (this.recentMemory) {
|
||
parts.push(`[Recent steps]\n${this.recentMemory}`);
|
||
}
|
||
if (this.pendingMemory) {
|
||
parts.push(`[Current step]\n${this.pendingMemory}`);
|
||
}
|
||
return parts.join('\n\n');
|
||
}
|
||
```
|
||
|
||
#### 3.7.5 截图 base64 的管理（pruneScreenshots，在 transformContext 中执行）
|
||
|
||
记忆压缩管理的是**文字上下文**（通过 systemPrompt 注入）。截图 base64 在 `pruneScreenshots` 中单独管理：
|
||
|
||
```
|
||
pruneScreenshots(messages: AgentMessage[])
|
||
│
|
||
│ 1. 遍历消息，识别包含 ImageContent 的 toolResultMessage
|
||
│ 2. 按时间排序，保留最近 screenshotKeepCount (默认 3) 步的截图
|
||
│ 3. 更早步骤：移除 ImageContent，替换为文字描述
|
||
│ { type: 'text', text: '[Screenshot removed - Step 5: browser opened]' }
|
||
│ 4. token 硬限制兜底：
|
||
│ 估算总 token（文字 text.length/3 + 图片 ~800/张）
|
||
│ 超过 model.contextWindow * 0.9 时，从最旧消息强制移除图片
|
||
│
|
||
返回裁剪后的 AgentMessage[]
|
||
```
|
||
|
||
pi-mono 的 `transformContext` 在 `convertToLlm` **之前**执行，操作的是 `AgentMessage[]`，裁剪结果只影响当次 LLM 调用的输入，不修改 Agent 内部存储的完整消息历史。
|
||
|
||
#### 3.7.6 memory_model 配置
|
||
|
||
```
|
||
GUI_AGENT_MEMORY_MODEL — 记忆摘要用的模型（可选，默认复用 GUI_AGENT_MODEL）
|
||
GUI_AGENT_MEMORY_PROVIDER — 记忆模型 Provider（可选，默认复用 GUI_AGENT_PROVIDER）
|
||
```
|
||
|
||
记忆摘要是纯文本输入/输出，不需要视觉能力，可以用更便宜的模型（如 haiku / gpt-4o-mini）降低成本。
|
||
|
||
#### 3.7.7 记忆摘要 system prompt
|
||
|
||
```
|
||
You are a memory summarization assistant for a GUI automation agent.
|
||
Your task is to condense step-by-step action records into concise memory entries.
|
||
|
||
Output JSON:
|
||
{
|
||
"summary": "Concise summary of the actions taken and their outcomes..."
|
||
}
|
||
|
||
Guidelines:
|
||
- Preserve key information: what was done, what succeeded/failed, current state
|
||
- Remove redundant details and repetitive patterns
|
||
- Keep the summary actionable — the agent needs to know what happened to plan next steps
|
||
```
|
||
|
||
### 3.8 agent/stuckDetector.ts — 卡死检测
|
||
|
||
- 将截图缩放到 32×32 → 计算与前 N 步（默认 3）的像素均值差异
|
||
- 连续 N 步差异 < 阈值（5%）→ 判定卡死，自动终止
|
||
- 简化方案，不需要 SSIM 或感知哈希
|
||
|
||
### 3.9 safety — 安全层
|
||
|
||
| 模块 | 实现 | 接入方式 |
|
||
|------|------|---------|
|
||
| **hotkeys** | 组合键黑名单匹配，按平台区分（macOS: Cmd+Q, Win: Alt+F4 等） | 原子操作：atomicTools 中直接调用；Agent 循环：通过 `beforeToolCall` hook 拦截 |
|
||
| **auditLog** | 固定大小数组 (1000)，环形写入，通过 MCP Resource 暴露 | 原子操作：atomicTools 执行后记录；Agent 循环：通过 `afterToolCall` hook 记录 |
|
||
|
||
### 3.10 mcp/server.ts — MCP Server
|
||
|
||
**Streamable HTTP 模式（主模式）**：
|
||
|
||
参考 `qiming-mcp-stdio-proxy` 的 `PersistentMcpBridge` 模式：
|
||
|
||
- `http.createServer()` 监听 `127.0.0.1:<port>`（默认 60008），长期运行
|
||
- 请求路由：`/mcp` 路径处理 MCP 协议请求
|
||
- 每个客户端连接创建独立的 `StreamableHTTPServerTransport` + `Server` 实例
|
||
- Session 通过 `mcp-session-id` HTTP header 跟踪
|
||
- Session 管理：`Map<sessionId, { server, transport }>`，定期清理过期 session
|
||
- 每个 session 的 Server 注册相同的 tool handler（atomicTools / taskTools）
|
||
- DELETE 请求关闭指定 session
|
||
|
||
**stdio 模式（备选）**：
|
||
|
||
- `new Server()` + `StdioServerTransport`，单客户端，适合简单场景
|
||
|
||
**通用**：
|
||
|
||
- 注册 `ListToolsRequestSchema` 和 `CallToolRequestSchema` handler
|
||
- CallTool handler 内部路由到 atomicTools / taskTools
|
||
- 连接断开：Transport 关闭时 AbortSignal 自动触发，正在执行的 `gui_execute_task` 会收到 abort 信号并终止 Agent 循环
|
||
|
||
### 3.11 mcp/taskTools.ts — gui_execute_task 处理
|
||
|
||
- `executeTask(taskText, extra)` 函数：MCP tool handler 的核心逻辑
|
||
- `Mutex` 互斥锁：确保同时只有一个 GUI 任务在执行
|
||
- 流程：
|
||
1. `mutex.acquire()` — 获取锁（如已有任务在执行则等待）
|
||
2. `taskRunner.run(taskText, extra.signal)` — 启动 Agent 循环
|
||
3. 循环中通过 `extra.sendNotification()` 推送 progress
|
||
4. 监听 `extra.signal` 处理取消（AbortSignal → `agent.abort()`）
|
||
5. `mutex.release()` — 释放锁（finally 块中确保释放）
|
||
6. 返回 `{ success, result, finalScreenshot, steps }` 给 MCP 调用方
|
||
|
||
---
|
||
|
||
## 4. Electron 客户端改造
|
||
|
||
### 4.1 改造范围
|
||
|
||
| 操作 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| 修改 | `src/main/services/computerServer.ts` | 新增 4 个 `/computer/gui-agent/*` 路由 |
|
||
| 修改 | `src/shared/types/computerTypes.ts` | 新增 `GuiVisionModelConfig` 类型 |
|
||
| 新增 | `src/renderer/components/GUIAgentSettings.tsx` | 显示器选择 + 视觉模型配置 UI |
|
||
| 修改 | `src/renderer/components/SettingsPage.tsx` | 集成 GUIAgentSettings 标签页 |
|
||
|
||
### 4.2 computerServer.ts 新增路由
|
||
|
||
在 `handleRequest` 中新增 4 个路由（复用现有的 JSON envelope 响应格式）：
|
||
|
||
| 路径 | 方法 | 逻辑 |
|
||
|------|------|------|
|
||
| `/computer/gui-agent/vision-model` | POST | 验证 body → 存 SQLite |
|
||
| `/computer/gui-agent/vision-model` | GET | 读 SQLite → 附加推断参数 |
|
||
| `/computer/gui-agent/displays` | GET | `screen.getAllDisplays()` |
|
||
| `/computer/gui-agent/display` | POST | 校验 displayIndex → 存 SQLite |
|
||
|
||
### 4.3 配置传递
|
||
|
||
启动 GUI Agent MCP Server 子进程时，从 SQLite 读取配置，注入为环境变量：
|
||
`GUI_AGENT_PROVIDER`, `GUI_AGENT_MODEL`, `GUI_AGENT_API_KEY`, `GUI_AGENT_BASE_URL`, `GUI_AGENT_DISPLAY_INDEX`, `GUI_AGENT_COORDINATE_MODE`
|
||
|
||
---
|
||
|
||
## 5. 实现阶段
|
||
|
||
### Phase 1: 项目脚手架 + 原子操作
|
||
|
||
**目标**: MCP Server 启动（Streamable HTTP），13 个原子操作可调用。
|
||
|
||
1. 创建 `crates/agent-gui-server/`，配置 package.json / tsconfig / vitest（参考 qiming-mcp-stdio-proxy 约定）
|
||
2. config.ts — 环境变量解析
|
||
3. utils/ — logger, platform, errors
|
||
4. coordinates/ — modelProfiles + resolver
|
||
5. desktop/ — display, screenshot, mouse, keyboard, clipboard, imageSearch
|
||
6. safety/ — hotkeys, auditLog
|
||
7. mcp/ — atomicTools, resources, server（Streamable HTTP 主模式 + stdio 备选，参考 qiming-mcp-stdio-proxy 的 HTTP server + session 管理模式）
|
||
8. index.ts — CLI 入口（`--port`、`--transport stdio`）
|
||
|
||
**验收**: `tools/list` 返回 13 个工具；`gui_screenshot` 返回正确截图和元数据；多个 MCP 客户端可同时连接。
|
||
|
||
### Phase 2: 坐标转换验证 + 多屏
|
||
|
||
**目标**: 坐标转换准确，多屏正确。
|
||
|
||
1. CoordinateResolver 单元测试：覆盖所有 7 种模型 + Retina/HiDPI + 多屏偏移
|
||
2. 截图管线单元测试：不同分辨率缩放后 metadata 正确
|
||
3. 端到端：MCP 调 `gui_screenshot` + `gui_click`，验证点击位置
|
||
|
||
### Phase 3: Agent 循环 (gui_execute_task)
|
||
|
||
**目标**: gui_execute_task 能执行自然语言 GUI 任务。
|
||
|
||
1. 安装 pi-mono 依赖（`@mariozechner/pi-ai`, `@mariozechner/pi-agent-core`, `@sinclair/typebox`）
|
||
2. agent/systemPrompt.ts — 专用 system prompt
|
||
3. agent/taskRunner.ts — 创建 pi-mono `Agent` 实例，注册 `AgentTool[]`，接入 hooks：
|
||
- `transformContext` → memoryManager 截图裁剪 + 记忆注入
|
||
- `beforeToolCall` → hotkeys 安全拦截
|
||
- `afterToolCall` → auditLog 审计记录
|
||
- `convertToLlm` → 消息格式过滤
|
||
- `toolExecution: 'sequential'`（GUI 操作串行）
|
||
4. agent/memoryManager.ts — 三层记忆 + LLM 摘要压缩（独立 `complete()` 调用）
|
||
5. agent/stuckDetector.ts — 卡死检测
|
||
6. mcp/taskTools.ts — 注册 gui_execute_task（同步阻塞 + Mutex + AbortSignal + progress notification）
|
||
7. 进度通知：`agent.subscribe()` 事件 → `extra.sendNotification({ method: 'notifications/progress', params: { progressToken, progress, total, message } })`
|
||
|
||
**验收**: `gui_execute_task("打开 Finder")` 自动完成，返回步骤日志。
|
||
|
||
### Phase 4: SDK 导出
|
||
|
||
**目标**: 提供 SDK 入口。
|
||
|
||
1. lib.ts — SDK 工厂函数导出
|
||
|
||
### Phase 5: Electron 客户端改造
|
||
|
||
**目标**: 显示器选择 + 视觉模型配置接口。
|
||
|
||
按第 4 节执行。
|
||
|
||
### Phase 6: 集成测试 + 文档
|
||
|
||
1. 与 claude-code / qimingcode 的 MCP 集成验证
|
||
2. 跨平台基本验证
|
||
3. README.md
|
||
|
||
---
|
||
|
||
## 6. 测试策略
|
||
|
||
### 重点单元测试
|
||
|
||
| 模块 | 覆盖重点 |
|
||
|------|---------|
|
||
| coordinates/resolver | 所有坐标家族转换、Gemini yx 坐标顺序 swap、Retina/HiDPI、多屏偏移、边界 clamp |
|
||
| coordinates/modelProfiles | 模型名匹配、coordinateOrder 区分、fallback、环境变量覆盖 |
|
||
| desktop/screenshot | 统一缩放策略（逻辑分辨率 + 最长边 1920 上限）、JPEG quality 降级、metadata 完整性 |
|
||
| desktop/clipboard | CJK 检测、长文本路由、剪贴板备份恢复 |
|
||
| safety/* | 黑名单匹配、环形缓冲 |
|
||
| agent/memoryManager | 三层记忆预算触发、LLM 摘要调用、compose() 输出、截图丢弃策略 |
|
||
| agent/stuckDetector | 相同/不同截图判定 |
|
||
| config | 必填校验、默认值 |
|
||
|
||
### Mock 策略
|
||
|
||
- **nut.js**: mock 避免实际操作桌面
|
||
- **sharp**: mock resize/jpeg/toBuffer 链，验证调用参数
|
||
- **pi-mono**: mock `Agent` 类（subscribe 发预设事件序列）、mock `getModel`、mock `complete`（记忆摘要调用）
|
||
- 框架: Vitest，配置参考 qiming-mcp-stdio-proxy
|
||
|
||
---
|
||
|
||
## 7. 风险与应对
|
||
|
||
| 风险 | 应对 |
|
||
|------|------|
|
||
| nut.js prebuilt binary 某平台不可用 | CI 验证三平台；备选: platform-specific CLI (screencapture, cliclick) |
|
||
| pi-mono 某 Provider 的 tool calling 不兼容 | Anthropic + OpenAI 是核心场景，其他验证后再加入 modelProfiles |
|
||
| macOS 权限弹窗阻塞首次使用 | `gui://permissions` Resource 报告状态；README 提供授权步骤 |
|
||
| Agent 循环 token 消耗过快 | 三层记忆 memoryManager + LLM 摘要压缩；截图保留最近 3 步；maxSteps=50；JPEG quality=75 |
|
||
| Linux Wayland 不支持 | v1 仅支持 X11，Wayland 为 v2 |
|
||
| sharp 与 Electron 版本冲突 (SDK 嵌入模式) | MCP Server 独立进程无此问题；嵌入模式需 electron-rebuild |
|
||
|
||
---
|
||
|
||
## 8. 依赖清单
|
||
|
||
| 依赖 | 用途 |
|
||
|------|------|
|
||
| `@modelcontextprotocol/sdk` ^1.27.1 | MCP Server |
|
||
| `@nut-tree-fork/nut-js` ^4.2.6 | 桌面自动化（社区 fork，`@nut-tree/nut-js` 需要付费订阅） |
|
||
| `@mariozechner/pi-ai` | 多 Provider LLM 调用 |
|
||
| `@mariozechner/pi-agent-core` | Agent 循环 + tool calling |
|
||
| `@sinclair/typebox` | AgentTool 参数 schema 定义 |
|
||
| `sharp` ^0.33.0 | 截图 resize + JPEG 编码 |
|
||
| `clipboardy` ^4.0.0 | 跨平台剪贴板读写 |
|
||
|
||
---
|
||
|
||
## 9. 工作空间集成
|
||
|
||
### 9.1 pnpm-workspace 配置
|
||
|
||
项目根目录 `pnpm-workspace.yaml` 已配置 `crates/*` 为工作空间：
|
||
|
||
```yaml
|
||
packages:
|
||
- 'crates/*'
|
||
```
|
||
|
||
`crates/agent-gui-server/` 创建后自动成为工作空间成员。
|
||
|
||
### 9.2 Electron 客户端依赖集成
|
||
|
||
在 `crates/agent-electron-client/package.json` 中添加依赖：
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"qiming-mcp-stdio-proxy": "workspace:*",
|
||
"agent-gui-server": "workspace:*" // 新增
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9.3 打包资源配置
|
||
|
||
在 `crates/agent-electron-client/package.json` 的 `electron-builder.extraResources` 中添加：
|
||
|
||
```json
|
||
{
|
||
"extraResources": [
|
||
{
|
||
"from": "resources/qiming-mcp-stdio-proxy",
|
||
"to": "qiming-mcp-stdio-proxy"
|
||
},
|
||
{
|
||
"from": "resources/agent-gui-server", // 新增
|
||
"to": "agent-gui-server"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 9.4 集成方式参考
|
||
|
||
与 `qiming-mcp-stdio-proxy` 相同：
|
||
- 工作空间依赖：`workspace:*`
|
||
- 打包时复制到 `resources/` 目录
|
||
- 运行时通过子进程方式启动 MCP Server
|
||
|
||
---
|
||
|
||
## 参考文件
|
||
|
||
| 文件 | 参考内容 |
|
||
|------|---------|
|
||
| `specs/gui-agent/gui-agent.md` | Spec 规范文档（权威需求来源） |
|
||
| `crates/qiming-mcp-stdio-proxy/package.json` | 工程约定: ES modules、依赖版本、build/test scripts |
|
||
| `crates/qiming-mcp-stdio-proxy/src/index.ts` | CLI 入口模式 |
|
||
| `crates/qiming-mcp-stdio-proxy/src/shared/proxy-server.ts` | MCP Server 创建模式 |
|
||
| `crates/agent-electron-client/src/main/services/computerServer.ts` | Electron 改造目标（新增路由） |
|
||
| `crates/agent-electron-client/src/shared/types/computerTypes.ts` | 类型扩展（新增 GuiVisionModelConfig） |
|