ccgui的Browser Dock内置浏览器Agent：让AI打开网页、收集只读上下文的完整用法-平芜编程栈

ccgui的Browser Dock内置浏览器Agent：让AI打开网页、收集只读上下文的完整用法

【免费下载链接】desktop-cc-guiMulti-engine AI coding desktop client (Tauri). Claude Code, Codex, Gemini, OpenCode, DeepSeek Harness and more in one GUI.项目地址: https://gitcode.com/gh_mirrors/co/desktop-cc-gui

ccgui 是一款多引擎 AI 编程桌面客户端（基于 Tauri），内置的Browser Dock 浏览器 Agent能帮你在客户端里直接打开网页，并把页面的只读上下文（URL、标题、正文、链接、按钮等）安全地交给 Claude Code、Codex、Gemini、OpenCode 等任意引擎，无需复制粘贴，也绝不把原始 DOM 或密码类内容泄露给 AI。

Browser Dock 是什么？为什么叫"Dock"

Browser Dock 是 ccgui 的客户端内置浏览器：点击顶部全局工具栏的 Browser Dock 图标，就会弹出一个独立的浏览器窗口，网页渲染在单独的 WebView 中，而不会抢占你的主对话窗口——主窗口里的会话、输入区始终可用，两个窗口可以并行工作。

它的定位很克制：先做"可信观察层"，也就是只读的网页上下文采集，而不是高风险的自动点击、自动填表。这个设计决策可以直接在行为契约中读到：

总契约（浏览器窗口、会话、快照、脱敏、只读动作门禁）：openspec/specs/vibecoding-browser-agent/spec.md
页面理解契约（快照内容、截断、隐私、陈旧状态）：openspec/specs/browser-agent-page-understanding/spec.md
跨平台降级能力矩阵（macOS / Windows / Linux 各自能力边界）：docs/browser-agent/phase3-cross-platform-degraded-capability-matrix.md

如何打开 Browser Dock 并浏览网页

打开方式很简单：

点击顶部全局工具栏上的 Browser Dock 图标，独立浏览器窗口随即打开（已打开则聚焦到它）；
在地址栏输入http或https网址即可浏览，界面会显示 URL、标题、加载与错误状态；
支持多标签页，但底层是单渲染器 + 激活标签页模型——采集上下文时永远只取"当前激活的标签页"，后台标签不会悄悄混进 AI 上下文。

一个实用细节：Browser Dock 可以直接打开file://的本地 HTML 文件（仅.html/.htm结尾允许，其他本地文件类型会被拦截并给出诊断），方便预览你项目里的静态页面。窗口默认尺寸足够大，普通网页不会因窄视口而变形。

让 AI 读懂网页：三步完成上下文采集

这是 Browser Dock 最核心的用法，三步搞定：

打开页面：在 Browser Dock 中加载你要 AI 看的网页（文档站、报错页、你自己本地 dev 服务器都行）；
附加上下文：选择"把当前页面附加到 AI 上下文"，Composer 输入区上方会出现一张预览卡片，展示即将发给 AI 的内容——URL、标题、采集时间、正文摘录、元素数量、截断与脱敏状态，而不是一个含糊的"已附加"标签；
提问发送：直接输入问题（比如"这个报错是什么意思""根据这个 API 文档帮我写调用代码"）。发送时走的是统一的BrowserContextAttachment结构，不会同一份内容既当附件又塞进提示词造成重复。

发送前你可以随时刷新或移除这张附加卡片；移除后该次 AI 请求就不会再包含这个页面快照。相关实现入口：

附加逻辑：src/features/browser-agent/hooks/useBrowserContextAttachment.ts
Composer 预览卡片：src/features/browser-agent/components/BrowserContextPreview.tsx
证据检视面板：src/features/browser-agent/components/BrowserEvidencePanel.tsx
Browser Dock 窗口本体：src/features/browser-agent/components/BrowserDock.tsx

AI 到底"看到"了什么？快照内容详解

快照不是原始 DOM 倒灌，而是有边界、有预算的结构化页面事实：

来源元数据：URL、标题、采集时间、工作区归属；
正文内容：有长度上限的可见文本摘录，超出预算会自动截断，并附截断元数据，你和 AI 都能看到"被截过"；
语义元素：标题、链接、按钮、表单控件、导航区等"地标"信息（角色、可见文本、启用状态），帮助模型理解页面结构；
诊断信息：如果某部分内容因平台或页面限制没采全，快照会带上降级诊断，模型能据此解释不确定性，而不是假装看懂了整页。

隐私脱敏：密码和令牌绝不进 AI

这是最该放心的一点：快照永远不包含原始 DOM、Cookie、请求头、存储内容、密码值、令牌、Authorization 值、隐藏域、脚本与样式内容。页面上出现密码框或类令牌字段时，只会留下"该字段已脱敏"的元数据；UI 上也有隐私状态标识，让你能区分"已脱敏的上下文"和"原始页面"。

只读原则：为什么 AI 不能替我点按钮

当前阶段的 Browser Agent 是只读的：AI 可以请求和消费页面快照，但点击、输入、提交表单等改变页面状态的动作会被明确拦截（返回 blocked 结果），不存在"AI 悄悄点了什么"的暗箱。后续若开放高风险动作，契约要求必须先展示动作预览（目标、理由、预期操作）、提供取消路径，并对每次执行/拦截/失败写入审计记录：

动作执行与拦截逻辑：src/features/browser-agent/actions/browserActionExecution.ts
动作审计轨迹界面：src/features/browser-agent/components/BrowserActionAuditTrail.tsx

URL 策略同样保守：默认阻止任意内网地址浏览，只有当前工作区显式放行的 localhost / 本地开发源才会进入"本地页面理解"通道。

实战场景：从网页到代码的最短路径

本地页面 ↔ 代码候选：当激活标签页是你工作区里的本地开发页面时，快照会基于路由、可见文本、元素地标生成页面到代码的候选映射（文件路径 + 匹配理由 + 置信度），相当于把"这个页面对应哪些源码文件"直接交给 AI；外部网站则不会乱猜代码候选。
跨引擎通用：同一份浏览器上下文契约适用于 Claude、Codex、Gemini、OpenCode 与自定义 Provider——切换引擎不用重新配置，不支持的结构化附件的引擎会走显式的降级路径，而不是静默丢上下文。
证据可回溯：快照会以有界的"证据引用"形式保留在会话/任务中，事后可检视其来源、预算、隐私状态与过期时间；证据过期会显示为过期态，绝不伪造内容。

Browser Dock 设置与常见问题

默认开启：不需要先跑进设置页，开箱即可用；如需关闭，可在设置中显式禁用，禁用后快照不会被注入 AI 请求，AI 的浏览器操作也不会再路由给内置 Browser Agent。
页面变了，附加会标"陈旧"：如果附加后你切换了标签页、URL 变了、滚动超过阈值或快照超过保鲜期，预览卡片会标记 stale 并给出刷新入口；即使你硬着头皮发送，AI 载荷里也会带上 stale 元数据，模型不会把旧快照当成当前页面。
平台不支持时明示降级：若当前平台的 WebView 能力不足，Browser Dock 会显示明确的"不支持/降级"状态，不会假装上下文可用。
文档索引：Browser Dock 相关文档集中在 docs/browser-agent/README.md，Phase 3 实施背景可参考 docs/plans/2026-06-01-browser-dock-phase3.md。