ycode/docs/对话无头浏览器接入-2026-10-18.md

对话无头浏览器接入

日期：2026-10-18。范围：YCode 自身对话运行链路；本次不采集 WorkBuddy，不据此声明原版功能或视觉等价。

原因与实现

原有 browser-host.ts 仅向右侧手动浏览面板提供网页容器；对话的宿主工具列表未注册浏览器，OMP 又以 --no-tools 启动。因此移除浏览器设置项后，对话仍没有页面读取与操作入口。

现注册一个内置 browser 工具，支持 open、navigate、snapshot、click、type、press_key、scroll、wait、screenshot、list、close。使用 Electron 内置 Chromium 的隐藏离屏窗口，不需要安装扩展或额外浏览器。原有经济模式和浏览器操控设置保持移除，不新增开关。

• 浏览器归属于会话与工作目录，独立内存存储，不共享个人浏览器登录态。每个作用域最多 4 个标签，进程最多 16 个。
• 页面快照返回可见正文、可交互元素及稳定 ref；导航后旧 ref 失效。也可用唯一 CSS selector 定位。点击、输入与按键经过 Chromium 真实输入通道；不向模型开放任意 JavaScript 执行。
• 仅固定 DOM 操作在隔离世界中运行；页面禁用 Node 与 preload，阻止下载和权限请求，限制顶层 HTTP(S) 导航。页面弹窗仍留在受控窗口中。
• 服从现有模式及权限机制：规划模式不能调用；默认权限下打开、导航、点击、输入、按键请求批准，完全访问按该模式直接执行。读取、截图、等待、滚动及标签管理不额外询问。
• 支持取消、操作超时、同标签串行执行；归档、删除会话、关闭最后一个普通窗口或退出应用会清理后台浏览器。

对话及图片链路

OMP 和备用 HTTP 均调用相同宿主工具。截图压缩为不超过 500 KiB 的 JPEG，适应 OMP 单帧 1 MiB 限制；截图作为消息图片保存，文本工具记录不内嵌完整图片数据。

支持图片输入的模型收到实际截图；未启用图片输入的模型仍可读取页面快照，会话仍显示截图，但不将图片送入模型请求。备用 HTTP 在该轮所有工具结果之后插入截图，维持工具调用与结果的配对顺序；后续轮次的兼容历史会按模型能力重放截图。

主要文件：src/main/browser-automation.ts、src/main/agent/browser-dom.ts、src/main/agent/tools/browser.ts；配套更新工具注册、主进程初始化、会话清理、OMP 结果、HTTP 循环、历史重放和模型图片能力传递。

已验证

• 完整 npm run build 通过，含沙盒原生组件、TypeScript、Electron 主进程及页面构建。日志：.tmp/browser-automation-full-build.log。此前经济模式移除记录中的沙盒编译错误为当时状态，本轮构建已无该阻塞。
• npm run test:browser-automation 通过 60 项。报告：.tmp/browser-automation-3wMm3p/report.json。使用真实隐藏 Chromium 与本机回环网页，覆盖真实可信点击、替换/清空/追加输入、键盘、异步等待、滚动、截图、导航旧 ref、权限拒绝/批准、作用域隔离、取消和清理。
• 同一测试验证备用 HTTP、实际安装 OMP、二者的无图片输入模型，以及构建后正式桌面应用的 preload/IPC → 对话服务 → OMP → 宿主浏览器 → 模型续接；截图与工具记录真实写入 sessions.json，删除会话清理浏览器。模型端为可控的本机回环服务，未请求用户付费 API。
• 检查 Responses、Anthropic、Gemini 的请求转换保留截图输入；不将请求转换验证等同于三个远程供应商实测。
• npm run test:conversation、npm run test:omp、npm run test:conversation-ipc、npm run test:custom-model-native 全部通过。
• node scripts/browser-host-regression.cjs 通过，原有手动浏览器导航、隔离、尺寸与生命周期回归通过。
• 已查看 .tmp/browser-automation-3wMm3p/browser-actual.jpg：实际隐藏页面截图，输入和页面变化可见。
• 本次文件的 git diff --check 通过。保留工作区其他修改，未提交代码。

使用及限制

重启 YCode 主进程后，在支持工具调用的模型、Craft 模式下直接要求打开 URL 并操作即可。不需要恢复已移除的浏览器设置。当前用户窗口尚未重启：其本地调试端口不可连接，无法核实未发送草稿，因此保留窗口和现有用户数据。

已实现主文档操作；跨域 iframe 遍历、任意脚本执行、外部浏览器接管、文件上传/下载暂不支持。验证码或登录可能需要用户协助，目前未提供把后台标签切为手动登录窗口的入口。浏览器内存会话在应用重启后消失，已存会话截图保留。右侧手动面板与自动化标签当前独立，尚未接入同屏展示。