# GoodBuddy 电脑控制开发进度

最后更新：2026-08-05

## 范围

本阶段不包含 LoongArch 和厂商互认证。目标平台仍为 Windows、macOS、
Linux x64 和 Linux arm64。

## 已完成

### 直连模型与浏览器

- 已实现宿主进程拥有的隔离浏览器服务。
- 使用 Electron 自带 Chromium 和 CDP，不下载额外浏览器。
- 已实现导航、可访问性快照、点击、输入、选择、返回和有界截图工具。
- 浏览器工具只在直连模型的 Execute 模式中提供；用户选择 Execute 即授权
  本次交互运行，不再逐个弹出 GoodBuddy 工具审批。
- 支持当前设备可连接的 HTTP、HTTPS、公网、内网、本机和元数据地址，
  导航及重定向仍经过 DNS 解析和目标地址固定。
- 已实现回环过滤代理、下载和文件选择器阻止、权限拒绝、会话取消、
  空闲回收和应用退出清理。
- 直连模型工具循环已提高到适合浏览器任务的有界上限，并包含重复调用和
  无进展保护。

### MCP

- MCP 图片结果已支持 PNG、JPEG 和 WebP 的严格 Base64、文件签名和大小
  校验。
- 已支持 Anthropic Messages、OpenAI Responses 和兼容 Chat Completions
  的多模态工具结果。
- 已支持 MCP 进度续期、硬超时、Tasks、取消和关闭。
- 自定义 stdio MCP 不继承桌面会话变量。
- 已增加受审计 curated MCP 启动描述符，但在没有签名和打包的 helper
  前不启用外部桌面 helper。

### Computer Control Broker

- 已实现动作契约、风险分类、窗口租约、感知版本、过期引用、单次变更、
  审批、超时和取消核心。
- 注入开始后的不确定失败记录为 `outcome_unknown`，防止重试造成重复提交。
- 已实现 SQLite 持久审计，输入文本只保存长度和 SHA-256 摘要。

### Linux 技术预览

- 已实现 AT-SPI 语义核心、Portal 会话状态机、PipeWire 元数据校验、
  坐标映射和输入路由核心。
- DDE、Treeland、UKUI、GNOME 和 KDE 名称只用于诊断，不用于假定能力。
- 当前没有打包真实 D-Bus、PipeWire/libei 或 XTest 原生适配器，因此 Linux
  桌面控制保持不可启用，不能表述为生产可用。

### 设置与安全边界

- 能力存储已迁移到版本 2。
- 已增加电脑控制能力卡片、诊断、托管浏览器配置元数据、IPC 和 preload
  契约。
- 电脑控制能力默认关闭；启用、配置变更和本地数据清除会替换或清理相关
  Runtime 和会话。

## 本轮已修复缺陷

### P0：隔离浏览器创建失败，已修复

便携版中的两次失败都发生在浏览器导航工具进入运行状态约 15 秒后。
隔离 Electron 探针已定位到：

1. 过滤代理启动成功。
2. 隔离 Session 创建成功。
3. 隐藏 BrowserWindow 创建成功。
4. `webContents.debugger.attach('1.3')` 成功。
5. 第一个 `Page.enable` CDP 命令一直不返回，最终触发 15 秒会话创建超时。

现在会先加载并等待 `about:blank` 初始文档，再附加并启用 CDP 域，同时保留
超时后的迟到资源清理。真实 Electron 探针已确认 `Page.enable`、访问
`https://example.com/` 和有界 JPEG 画面捕获均成功。

### P0：右侧没有浏览器实时画面，已修复

浏览器窗口默认使用 `show: false`，但 BrowserService 现在从模型实际操作的同一
会话捕获页面帧，并通过受限 IPC 发送状态、当前 URL 和约 220KB 的 JPEG 画面。右侧工作栏
新增“浏览器”页签；活动对话启动浏览器时会自动打开该页签，并显示创建中、
加载中、操作中、用户交互中、就绪、失败和已停止状态。用户可点击“交互”打开
同一会话的子窗口辅助 Agent；交互时主窗口暂时禁用，关闭时先刷新最终画面再将
浏览器窗口最小化，页面和会话继续保留。用户也可立即停止当前对话的浏览器会话。

当前实现按导航、快照、点击、输入、选择、返回和截图操作刷新画面，而不是创建
第二个预览浏览器，因此显示内容与模型受控页面一致。

### P0：百度输入时元素引用失效，已修复

截图中的“浏览器元素引用已失效，请重新获取快照”来自过宽的导航监听：广告或
其他子框架开始导航、重定向时，也会清空主文档刚生成的元素引用。驱动现在只在
主框架导航和重定向时清空引用，子框架活动不再中断主页面输入和点击。

如果主页面确实已经变化，过期引用会作为“可重试”工具结果返回给直连模型，并
明确要求重新调用 `browser_snapshot`；模型可以用新引用继续操作，不再让整次
任务直接失败。页面原始可访问性树不再按字节大小拒绝；无论页面多大，驱动都会
读取页面并自动截取单次返回给模型的快照，同时用 `truncated` 明确标记，不再
显示“浏览器可访问性树超过安全限制”。

真实 Electron 探针已完成“打开百度、获取快照、输入阿里云、点击百度一下、
读取结果页”，结果页标题为“阿里云_百度搜索”，返回约 330 个节点并正确标记
为已截断。

海关总署网站使用会变化的 CDN 地址和 JavaScript 挑战。过滤代理现在会在经过
策略验证的地址间有界回退，并等待真正的主框架提交，不再把旧 `about:blank`
误报为成功；托管浏览器同时使用标准 Chromium User-Agent。真实 Electron
探针已确认 `http://www.customs.gov.cn/` 返回“中华人民共和国海关总署”标题、
约 310 个快照节点，以及约 161KB 的工具截图和右侧实时 JPEG 画面。

### P0：截图与用户附件展示，已改善

浏览器、全屏和单窗口画面统一压缩为约 220KB 的 JPEG，再送入模型或实时预览。
用户发送的文档和图片会在知识检索及 Runtime 调用前立即显示在对应用户消息中，
并随会话持久化。单窗口截图不再使用横向原生按钮，改为应用内纵向窗口列表，
避免选择器被多个长应用名称横向撑宽。

### P1：工具错误信息过度包装，已改善

浏览器会话创建错误现在包含“启动代理、创建隔离会话、配置网络代理、创建窗口、
加载初始页面、初始化浏览器协议”等有界阶段信息；实时页签也显示当前操作阶段
和截断后的错误原因。

浏览器底层错误目前被包装为“工具『浏览器导航』执行失败”，数据库和界面无法
区分代理、分区、窗口、CDP 初始化、DNS 或页面导航失败。需要增加有界、脱敏的
阶段错误码，并保留用户可执行的修复建议。

### P1：命名浏览器配置尚未用于执行

设置中的命名浏览器配置当前只保存未来托管隔离所需的元数据。实际执行仍使用
每个会话随机创建的临时分区，不复用登录状态。

## 下一步顺序

1. 在便携版真实模型流程中继续验证返回、取消和右侧画面刷新。
2. 再设计命名隔离 Profile 的持久登录态、引用和清理策略。
3. 分别实现并真机验证 Windows UIA、macOS AX 和 Linux 原生适配器。

## 最近验证

- `npm test`：591 项通过，6 项跳过。
- `npm run typecheck`：通过。
- `npm run lint`：通过。
- `npm run build`：通过。

以上自动化结果覆盖协议、安全边界和模拟驱动，不替代真实 Electron
BrowserWindow/WebContentsView、目标网站和目标 Linux 桌面环境的集成验证。
