docs: organize product design by feature
Define repository and feature-scoped documentation rules for PRDs, User Stories, logic, UI, technical design, and progress evidence. Move feature-owned documents under docs/features, add one entry point per feature, remove the redundant docs index, and update all affected cross-references. Expand the local tool environment design with explicit product, story, logic, UI, technical, and progress documents.
This commit is contained in:
mesalogo
@@ -0,0 +1,11 @@
|
||||
# 电脑控制
|
||||
|
||||
电脑控制包含 GoodBuddy 对浏览器和客户端桌面能力的产品实现与平台适配状态。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [功能进度](./progress.md) | 当前已实现能力、缺陷修复、平台限制和验证状态 |
|
||||
|
||||
当前只有进度文档；产品需求、功能逻辑、UI 和技术设计尚未从历史实现记录中独立整理。
|
||||
@@ -0,0 +1,176 @@
|
||||
# GoodBuddy 电脑控制开发进度
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档类型 | 实施进度 |
|
||||
| 状态 | 持续更新 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-18 |
|
||||
| 适用能力 | 内置浏览器与客户端电脑控制 |
|
||||
|
||||
## 范围
|
||||
|
||||
本阶段不包含 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。
|
||||
- 内置浏览器已归入“直连模型”工具，与联网搜索并列，并明确说明不会控制
|
||||
客户端已安装的浏览器；原有开关和配置 ID 保持不变，用户状态无需迁移。
|
||||
- 用户通过内置浏览器总开关决定是否向直连模型提供工具；开启后可在 Execute
|
||||
模式直接使用，不逐次询问。诊断位于同一分类。
|
||||
- 尚未实际参与浏览器执行的命名配置已从界面隐藏；底层旧数据和兼容接口继续
|
||||
保留，不删除用户已有记录。
|
||||
- “电脑控制”只显示实际操作客户端电脑的能力。能力启用、配置变更和本地
|
||||
数据清除仍会替换或清理相关 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；交互时主窗口暂时禁用，关闭时先刷新最终画面再将
|
||||
浏览器窗口最小化，页面和会话继续保留。用户也可明确关闭当前对话的浏览器会话。
|
||||
当前实现按导航、快照、点击、输入、选择、返回和截图操作刷新画面，而不是创建
|
||||
第二个预览浏览器，因此显示内容与模型受控页面一致。
|
||||
|
||||
### 已实现：浏览器工具栏
|
||||
|
||||
浏览器 Tab 顶部已增加“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”工具栏。
|
||||
它继续操作 Agent 在当前 Conversation 中使用的同一浏览器会话；用户导航会有意改变 Agent
|
||||
下一步看到的页面。前往、返回和刷新通过 `BrowserService` 与 Agent 浏览器操作串行执行，
|
||||
不会创建第二套 Renderer 导航路径。
|
||||
|
||||
工具栏状态以浏览器提交后的权威 URL、是否加载中、能否返回和会话活动状态为准；地址输入
|
||||
在用户编辑期间保留本地草稿，不被状态刷新覆盖；提交未带 HTTP(S) 协议的裸域名时会自动添加
|
||||
`http://`。创建中、Agent 操作中和完整交互窗口期间禁用其余工具栏控件，但活动导航仍可用
|
||||
“停止加载”中断。停止加载只取消页面加载，不关闭浏览器，也不释放 Runtime 上下文；原“停止
|
||||
浏览器”会话生命周期操作已统一标为“关闭浏览器”，并在视觉和文案上与停止加载清楚区分。
|
||||
|
||||
活动 Conversation 尚无浏览器会话时，可直接从地址栏输入 URL 并“前往”，通过现有浏览器
|
||||
能力检查和同一 URL 策略创建会话。实现复用现有每 Conversation 串行队列和有界状态，不引入
|
||||
恢复、版本化或第二套会话框架。
|
||||
|
||||
### 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 桌面环境的集成验证。
|
||||
Reference in New Issue
Block a user