Files
Agent-Workbench/docs/PLAN-1.22.md

73 lines
9.3 KiB
Markdown

# 1.22 后续方案:工作台内置浏览器
A–E已完成本地交付,实际范围、来源与限制见[1.22验收](QA-1.22.md)和[回顾](RETROSPECTIVE-1.22.md)。以下保留起步时的方案及边界。
前置1.21工程依赖与可复现环境已完成本地交付。以下保留阶段起步方案;当前A–D已实现,开发轮实际Electron/手机观察17组通过,E正在冻结发行验证。实际结果以[验收记录](QA-1.22.md)为准,不将Codex右侧浏览器算成本产品能力。
## 现有基础与目标
1.10以来已有封存静态工程构建、独立Edge上下文、填写/选择/点击/断言、DOM/控制台/请求/PNG与Task归属;现有桌面入口也可打开所属成果。它们用于工程页面验收,不等于工作台内已有通用浏览器。Codex右侧浏览器是Codex提供的外部功能,不计入本产品能力。
让用户在工作台查看和操作所属项目预览,也能给代理一个明确的网站目标,观察页面、连续交互、核对结果;用户与代理共享可核对的标签页状态。桌面内嵌视图与受控浏览服务分层,手机伴随端先观察原结果及审批,不直接取得Windows浏览器进程控制权。
## 执行切片
| 切片 | 实际交付 | 验收 |
| --- | --- | --- |
| A 项目开发预览 | 复用1.21固定环境,所属开发服务的启动/就绪URL/日志/停止;静态和开发服务均可打开 | React实际开发服务、改动后页面更新、服务退出/端口冲突/停止;不自动复用未知进程 |
| B 桌面浏览区 | Electron独立浏览视图、标签页、地址/来源、前进后退/刷新/关闭;任务与页面归属可见 | 真正可交互页面、外站无法取得工作台宿主API或Node权限、关闭视图与停止任务行为分别验证 |
| C 代理浏览工具 | 打开明确目标、读取可见页面/DOM/截图、点击/输入/滚动/等待;保存原定位、输入、输出和截图工件 | 多步真实网站任务、失败定位、页面变更、弹窗和停止;模型建议只通过所属执行工具生效 |
| D 会话与权限 | 独立浏览配置、可选持久登录资料、域名/操作范围、可撤销授权;下载与敏感提交有可核对审批 | 登录态隔离/清除/关闭;下载绑定目录/文件/来源;站点内容不能自行授予新权限或跨任务访问 |
| E 验收与交付 | 本地测试站和真实允许目标,桌面/390px观察与手机审批;原任务/浏览进程/证据保留和本地发行 | 页面身份、可恢复状态、无自动重放敏感操作、实际任务结果、更新回退;每切片本地Git与回顾 |
支付、发消息、上传私有资料等操作按实际用户授权处理;通用操作电脑、任意浏览器登录导入、语音与视频另列后续,不从能打开网页推断全部实现。浏览器里的文字和下载文件属于任务数据。
先完成项目预览与浏览区,再接网站连续操作;开发和验收均复用现有Task/Run、审批、预算、事件与工件,避免再建一套不受任务内核管理的浏览器。
## 1.21验收期间的实施细化(仍为计划)
本节是下一阶段契约和界面方案,不表示功能已实现。代码核对:现有[主窗口](../src/desktop/main.mjs)只允许工作台来源,并明确拒绝webview、弹出窗口和页面权限;[浏览器管理器](../src/core/browser/browser-manager.mjs)处理封存静态构建与一次性页面检查。后续扩展保留这些现有边界,新增独立浏览内容和所属开发服务,不能直接取消主窗口的来源限制。
### 首条完整使用路径
打开React工程 → 为任务创建独立工作区 → 按1.21诊断并准备实际依赖 → 核对固定的开发服务命令和来源 → 启动并打开预览 → 审查应用代码后观察页面更新 → 代理读取同一标签页、操作并核对结果 → 停止所属服务并保存原页面证据。启动、页面可用、实际断言通过分别显示;服务打印一个URL不构成所属服务就绪的证明。
首批开发服务优先支持已识别的Vite React项目。固定声明/脚本、运行时、依赖、工作区及监听地址;只绑定loopback,核对真实监听进程和页面来源。端口被其它程序占用、进程退出、脚本或依赖变化、启动结果未知时保存具体状态,不接管未知端口或重放旧启动。其它框架在来源和启动契约实测后增加,不能用一个任意终端输入框冒充通用预览支持。
### 界面取舍
比较两种组成:在现有右侧检视区增加可扩展的预览区,或另开独立浏览器窗口。第一种让当前任务、改动与页面保持同屏,符合本产品的工作流,因此优先实现;第二种只作为明确的外部打开操作。
桌面预览保留地址、所属项目/任务、服务状态及停止入口,支持拖动宽度和展开。390px采用完整预览层并提供明确返回,保留原任务选择。主窗口弹窗、切换工程、最小化、缩放和不同DPI均须同步内嵌视图的可见范围,避免浏览内容遮挡审批或吞掉输入。网页版本需要区分“可观察的受控预览”和“桌面内嵌视图”的实际可用性;第三方网站不能依赖iframe一定可以嵌入。
### 所属对象与停止恢复
| 对象 | 固定来源 | 终态及恢复要求 |
| --- | --- | --- |
| 开发服务 | Task/Run、工作区、依赖输入、原命令、原进程和监听来源 | 仅停止所属树;关闭页面不等于服务已停止;未知启动先核对 |
| 浏览配置与标签页 | 项目/任务、明确URL与域名范围、浏览配置、真实视图身份 | 默认独立配置;跨任务不借用登录;关闭/撤销清楚可见 |
| 页面观察 | 标签页、实际URL、页面修订、可见DOM/控件、原截图及SHA | 标明采样时间;页面变化使旧定位失效,不用旧截图冒充当前页面 |
| 操作请求与回执 | 原观察、唯一定位、具体动作/输入、允许范围、审批和执行身份 | 敏感提交中断保存可能已执行;先核对原页面与账本,不自动重试 |
外部内容使用独立的Electron浏览内容,保持sandbox、contextIsolation、webSecurity并关闭Node能力;不加载工作台preload、不暴露工作台token或主窗口IPC。页面导航、重定向、新窗口、下载、外部协议和文件访问分别受控;普通页面不能将本地工作台/API当作自己的可访问目标。代理不取得任意JavaScript或未受限CDP入口,使用固定浏览动作和有界页面观察。
### 逐切片完成标准
A必须先有真实Vite启动、页面更新、端口冲突、退出/停止和重启unknown证据;B必须有实际Electron交互以及弹窗遮挡/视口/DPI/关闭状态证据;C必须在动态测试站完成跨页面连续操作、定位失败和停止,保存每一步原观察与结果;D验证独立登录、撤销、下载和敏感操作确认,不能导入任意其它客户端登录资料。E再执行历史回归、源码/便携/安装及保留状态升级。手机先接原页面观察、SHA和审批;新的iPhone能力需单独实机验收,不挪用1.16结论。
## 1.22 接续前的实际接口复核(仍为计划)
当前产品是中文 Windows/React 编程工作台,桌面与手机共用 Node 执行宿主。首条路径为:所属工作区准备依赖 → 核对 Vite 启动计划 → 打开页面 → 应用修改并观察更新 → 保存页面结果 → 明确停止服务。当前工作不新增浏览能力。
已核对 `src/desktop/main.mjs`、`src/desktop/preload.cjs`、`src/shared/contracts/desktop-bridge.mjs` 和安装的 Electron 45 类型:主窗口采用 sandbox/contextIsolation,关闭 Node,拒绝 webview/外站导航/新窗口;六个现有桌面入口逐字段校验并限制当前主框架。现有 `BrowserManager` 负责封存构建验收和所属一次性检查,不能当作长期标签页服务。
| 边界 | 下一实现方向 | 实际验收 |
| --- | --- | --- |
| 所属开发服务 | 在 Node 宿主增加固定 Vite 预览管理器,复用工作区、1.21环境绑定和原进程执行器;不依赖窗口存活 | 关闭窗口后仍可观察;停止核对所属树;已有端口不接管;启动中断保留unknown |
| 桌面浏览内容 | Electron 45 `WebContentsView`,通过 `contentView.addChildView/removeChildView` 管理;浏览页不加载工作台preload | 页面无 desktopWorkbench/Node 能力;弹窗和任务切换时隐藏视图;关闭内容与停止服务分别核对 |
| 主窗口布局 | 右侧任务检视与可调整预览并排,窄屏完整预览层,保留返回和原任务选择;布局变更显式通知原生视图边界 | 390px、缩放/DPI、模态审批遮挡、最小化恢复和键盘焦点 |
| 浏览所属与观察 | 项目/Task/Run、页面修订、真实URL、截图SHA、可见控件与动作回执分开持久化;只向受限工具开放固定动作 | 动态页面变化使旧观察/定位失效;未知提交不重放;不从截图推断执行成功 |
具体新模块可沿 `src/core/preview/` 与 `src/desktop/` 分层,契约放 `src/shared/contracts/`。复用现有活动控制/审批/停止/事件/工件,不能把任意URL或任意终端输入直接交给宿主。浏览登录资料、下载、外部协议及明确操作范围在独立切片验证;手机先只观察和审批,新增真实iPhone能力单独验收。