共享浏览器工作区 bloodarea/dsh-agent-team-browser

dsh-agent-team-browser

状态：架构设计 / 预发布。 本仓库正在设计与实现中。横幅是概念图，不是已发布插件的截图。下文标注为计划中的功能，并不代表已经可用。安装说明、经过测试的兼容范围、发布标签，都会在实现并通过验收测试之后公布。不要因为某个社区包名字相似，就以为它是本项目。

概述

dsh-agent-team-browser 是一个计划中的原生共享浏览器工作区，面向 DeepSeekHarness（DSH）。它要接入 DSH 官方右侧边栏，支持单个智能体、Agent Team 和真人操作者，而且不需要外部浏览器窗口抢占前台焦点。

一个常驻浏览器工作区可以容纳多个标签页。获得授权的智能体可以同时在不同标签页里干活，共用一份刻意选定的登录上下文，还能通过显式的控制租约，把同一个标签页交给另一个智能体或真人。侧边栏就像一台显示器：切换正在查看的标签页，不会切换、暂停或重建智能体在后台的浏览器任务。

设计原则：团队负责人决定该由谁做什么；插件负责约束谁可以在什么时候、对哪个浏览器资源做什么。

项目介绍

一个浏览器工作区。多个智能体。关键时刻由人接管。

本项目延续 bloodarea/dsh-agent-team-presets 开创的 dsh-agent-team-* 命名系列。名字强调的是 Agent Team 协作，并不意味着只能依赖 Agent Team：单个智能体、直接使用侧边栏的真人，同样要能用。

设计上刻意拆开了三样经常被绑在一起的东西：

| 层 | 职责 | 生命周期 |
| DSH Agent Session | 谁调用工具，包括负责人和队友 | 由 DSH 管理 |
| Browser Workspace | 浏览器上下文、标签页、权限、保留的状态 | 由本插件管理 |
| Sidebar Viewer | 用户正在查看或控制哪个标签页 | 由 DSH UI 管理 |

关闭侧边栏绝不能关闭浏览器标签页。打开队友那个独立的 DSH Session，绝不能因为 Session ID 变了就再开一个浏览器。团队干完活之后，工作区是否保留、访问权是否收回，按工作区自己的显式策略走，而不是跟着团队聊天的生命周期走。

为什么需要这个插件？

常见的浏览器 MCP、封装层和桌面自动化工具，往往只优化一种场景：一个智能体控制一个可见浏览器。本项目要补上六个缺口：
1. 宿主焦点被打断。 浏览器自动化不该抢占操作系统的前台鼠标、键盘或活动窗口。
2. 多智能体归属不清晰。 多个智能体需要同一个授权工作区，而不是意外重复，或并发导航同一个标签页。
3. 视口随侧边栏尺寸变化。 窄侧边栏不能悄悄把 1920 × 1080 的桌面测试变成移动端布局。
4. 人在环控制薄弱。 人必须能旁观、接管某个标签页、处理棘手的交互，再把控制权交还给智能体。
5. 开发者可见性不足。 网络请求、响应、控制台消息和 cookie 需要可检查、权限感知的工具。
6. 生命周期边界错误。 浏览器标签页不该因为队友的 DSH 会话被销毁，或侧边栏面板被隐藏就消失。

设计原则： 官方 DSH 侧边栏负责呈现；本插件负责浏览器资源、身份感知访问和并发安全。浏览器执行始终独立于呈现界面。

规划中的能力

以下描述的是目标规格，不是已完成的功能清单。

| 能力 | 预期行为 |
| 原生侧边栏工作区 | 在官方 DSH 右侧边栏注册新的 Browser Workspace 标签页，不替换内置浏览器。 |
| 静默浏览器运行时 | 无头 Chromium + Chrome DevTools Protocol（CDP）；自动化不操作宿主 OS 指针或前台窗口。 |
| 多智能体访问 | 不同 DSH 会话可按可信 Team/member 身份，绑定到同一个授权 Browser Workspace。 |
| 共享登录状态 | 同一个授权 BrowserContext 内的标签页共享适用的 cookie 和同源存储。 |
| 标签页级协作 | 不同标签页并发执行；某个标签页的多步写入需要独占租约。 |
| 人工接管 | 与智能体观察同一页面，请求控制权，再交还控制权，无需另开第二个页面。 |
| 独立视口 | 按标签页设置 CSS 视口、DPR、触摸/移动端模拟；侧边栏宽度只改变渲染缩放。 |
| 开发者工具 | 检查 Fetch/XHR、响应状态/正文（可选开启）、Console、运行时错误，以及受管控的 cookie 访问。 |
| 持久化工作区 | 隐藏面板、切换智能体聊天都不丢标签页；重启后恢复可恢复的状态。 |
| 单人模式 | 不装 Agent Team 或 dsh-agent-team-presets 也能运行。 |

侧边栏是查看器，不是浏览器进程

把侧边栏想成电视机，Chromium 标签页想成独立频道。切换频道只改变正在观看的标签页。其他标签页继续在后台运行；它们的页面、视口尺寸和活跃智能体都保持不变。获得许可后，人可以接管正在观看的频道。

共享状态不等于共享页面状态

一个 BrowserContext 里的多个标签页通常共享 cookie，同源时还共享 localStorage / IndexedDB。每个标签页有自己的 DOM、URL、滚动状态，通常还有自己的 sessionStorage。站点可能加额外的认证限制；共享 cookie 不保证到处都能单点登录。不同工作区/团队默认隔离，除非明确授权共享。

视口与侧边栏尺寸相互独立

比如把真实页面设为 1920 × 1080，再显示在 420px 宽的侧边栏里。浏览器报告的仍然是大约 window.innerWidth === 1920 CSS 像素（具体取决于页面和环境）。侧边栏只负责把渲染出的图像缩放或平移显示。人的点击会先映射回浏览器坐标，再交给 CDP。

计划中的预设包括 390 × 844、768 × 1024、1280 × 720、1920 × 1080；自定义视口尺寸和 DPR 是另外的控件。调整 DSH 侧边栏尺寸绝不能顺带触发 CDP 视口变更。

使用这个包

可用性与安装

目前还没有经过验证的公开安装命令，也没有已发布的版本。 拟用的仓库标识是 bloodarea/dsh-agent-team-browser；GitHub release、npm 包、插件兼容性的可用情况，等有测试过的构建之后再确认。

第一个版本发布后，本节会写明：

1. 支持的 DSH 版本/commit 或兼容范围，以及所需的 Chromium 运行时。
2. 确切的固定版本安装命令，以及该选哪个 DSH 配置档。
3. 必需的 Host/Client 插件配置、启动步骤，以及卸载/迁移步骤。
4. 如何确认已加载插件的身份、版本、侧边栏入口，以及浏览器运行时是否健康。

不要照抄 dsh-agent-team-presets 的安装命令：那是另一个插件，发布周期也独立。

预期工作流：单个智能体

1. 在官方右侧边栏打开计划中的 Browser Workspace 入口。
2. 新建或选择一个工作区，打开浏览器标签页。
3. 选一个视口预设，或输入自定义视口。拖动侧边栏尺寸，观察页面视口保持不变。
4. 让智能体去浏览和测试，你照常使用桌面。
5. 盯着标签页，必要时接管，然后把控制权交回去。

预期工作流：智能体团队

假设一个 lead 把响应式测试、登录测试、API 诊断分派出去：

| 角色 | 浏览器资源 | 任务 |
| 前端智能体 | 标签页 A，390 × 844 | 验证移动端布局 |
| 测试智能体 | 标签页 B，1920 × 1080 | 跑登录流程 |
| 后端智能体 | 标签页 C，1280 × 720 | 检查 Fetch/XHR 行为 |
| 人工操作员 | 侧边栏查看器 | 切换查看的标签页；必要时接管选中的标签页 |
三个标签页可以共用同一个已授权的 BrowserContext，复用兼容的登录状态。每个智能体有各自的 DSH 会话，但通过服务端校验的成员资格与授权，解析到同一个工作区。负责人不必批准每一次点击：它授予一段工作范围，插件负责强制执行这个范围。

要转移同一个标签页，当前租约必须先释放或撤销，其他参与者才能拿到写租约。租约覆盖一段连贯的多步操作，而不只是单次点击。

预期工作流：人工介入

如果智能体遇到 CAPTCHA、敏感确认，或浏览器不支持的交互，它会暂停受影响的任务，请求用户介入。用户在侧边栏内接管，完成允许的步骤，然后归还标签页。插件不得悄悄切换宿主窗口、向其他智能体泄露凭据，或绕过站点防护。

了解实现

高层架构

flowchart TD
Lead[Agent Team lead] --> Identity[Trusted identity & grants]
Mate[Team members / solo agents] --> Identity
Viewer[DSH official right sidebar] --> Gateway[Authorized browser gateway]
Identity --> Gateway
Gateway --> Workspace[Workspace manager]
Workspace --> Lease[Tab lease coordinator]
Lease --> Runtime[Background Chromium / CDP]
Runtime --> Context[Authorized BrowserContext]
Context --> A[Tab A]
Context --> B[Tab B]
Context --> C[Tab C]
Runtime --> Stream[Frame & event stream]
Stream --> Viewer
Gateway --> Debug[Network / Console / Cookie inspector]
Debug --> Runtime

一个浏览器资源管理器，一条权限边界。 所有浏览器控制通道——包括智能体工具、侧边栏输入、调试和接管——都必须经过同一个授权网关。这套架构不是把三个独立运行的浏览器插件拼在一起。

运行时归属与生命周期

- WorkspaceId 由插件生成，不等于 DSH 的 SessionId、TeamId 或侧边栏标签页标识符。
- DSH 团队身份把符合条件的负责人／队友会话绑定到已授权工作区；普通子代理不会自动继承访问权限。
- 一个工作区可以有多个 Chromium 标签页和多个侧边栏查看器；每个查看器各自选择要观看哪个标签页。
- 隐藏侧边栏或切换到队友的聊天，只会断开／重新绑定查看器，不会影响 Chromium 页面。
- 任务完成会撤销租约；团队关闭会撤销团队授权。这两个事件都不会自动销毁保留的个人工作区。
- DSH 重启可以恢复可恢复的状态，例如保存的 URL、视口，以及允许持久化的认证数据。它无法保证恢复任意 JavaScript 堆状态或未完成的表单输入。

并发模型

| 操作 | 协调规则 |
| 读取标签页元数据／观察帧 | 可并发，受 ACL 约束 |
| 智能体写入不同标签页 | 并发 |
| 智能体写入同一标签页 | 独占式多操作租约 |
| 人工接管某个标签页 | 撤销/暂停现有写入方，授予有期限的人工租约 |
| 更改共享 cookies / 上下文设置 | 更严格的上下文级权限；可能影响每个标签页 |
| 智能体断开 / 租约过期 | 撤销其租约，并通过 fencing/版本检查拒绝过期命令 |

智能体团队的负责人掌管策略与委派。插件提供确定性的机制：所有权检查、锁强制执行、公平性/超时、恢复，以及审计记录。

浏览器渲染与输入

- 使用 Chromium/CDP 渲染并自动化真实页面，不合成前台桌面鼠标/键盘事件。
- 把标签页专属的帧或快照发送到侧边栏；显示的图像可独立于浏览器视口调整大小。
- 按当前缩放/偏移，把侧边栏指针位置换算成 CSS 视口坐标；显式处理 DPR、letterboxing、滚动和触摸模式。
- 当查看方切换标签页、断开连接或隐藏面板时，保持后台浏览器执行不中断。
- 测试并记录各种限制，例如 Chromium 后台节流、对话框、下载，以及仅 headless 行为。

开发者调试与隐私

Network 和 Console 事件属于实际的 Chromium 标签页/工作区，而不属于当前可见的那个 DSH 聊天。调试记录与导出必须有边界、单独授权，并默认脱敏。请求/响应正文捕获必须显式启用。Cookies、authorization headers、密码、会话 token 和跨团队数据，绝不能不加区分地暴露给模型或侧边栏。

模型体验

智能体应该看到什么

实现之后，智能体应该收到小而结构化的工具，例如列出工作区/标签页、导航、检查 DOM、设置视口、监听 console/network 事件、申请租约、释放控制。这些工具名称只是示例，不是已发布的 API 契约。 身份与授权来自 DSH 运行时——而不是智能体自己提供的 agentId 或 teamId 参数。

Token 影响

浏览器帧、页面文本和 Network 响应应该按需返回，并适当设上限或做摘要，而不是持续追加到对话上下文。只在被请求时返回截图或 DOM 摘录，能减少不必要的 token，但可能遗漏相关信息；当任务需要时，智能体应能请求更详细的内容。

提示词与 KV 缓存影响

插件不应需要把不断增长的标签页历史或秘密浏览器状态注入每个系统提示词。稳定的工具 schema 有助于提示词前缀的稳定性；实际缓存行为取决于模型/服务商以及 DSH 集成方式。浏览器持久化并不等同于 LLM 对话记忆持久化。

与 dsh-agent-team-presets 的关系

| 项目 | 职责 |
| dsh-agent-team-presets | 可复用的团队、角色、模型路由、提示词和工具策略 |
| dsh-agent-team-browser | 浏览器工作区、授权标签页访问、后台运行时、人工接管和调试 |

两者共用一套命名体系，设计上互为补充，但谁都不需要依赖对方。即使团队预设允许使用浏览器工具，浏览器访问仍由浏览器侧的授权来把关。

路线图与验证

下面这份清单列出的是待实现、待验证的工作，不是已经发布的功能：

- [ ] R0： 审查上游 DSH/插件 API、版本和许可声明；验证侧边栏与无头流式传输是否可行。
- [ ] R1： 搭建工作区/上下文/标签页生命周期，以及共享的 Chromium 运行时。
- [ ] R2： 验证 Agent Team 身份、跨会话工作区绑定、ACL 和标签页租约。
- [ ] R3： 接入官方 Sidebar，切换通道，并在查看器断开时保持后台标签页存活。
- [ ] R4： 实现独立的视口/DPR 模拟、适应/1:1 显示，以及正确的输入坐标变换。
- [ ] R5： 实现人工接管，并完整覆盖不抢占焦点的浏览器工具。
- [ ] R6： 实现带权限感知的 Network、Console、响应和 cookie 检查。
- [ ] R7： 加固认证、隐私、崩溃恢复、性能，以及 Windows/Linux 上的行为。
- [ ] R8： 完成可复现构建、验收结果、第三方声明和社区发布。

发布门槛包括：三个智能体 / 三个 DSH 会话 / 一个授权工作区，后台操作期间零宿主窗口焦点抢占，共享上下文与隔离上下文测试，同标签页租约的有效性校验，侧边栏视口独立性，以及正确的人工接管。失败或未运行的测试，绝不能写成通过。

已知限制与延后工作

- 仅限预发布阶段： 目前还没有完成的可安装构建、经过验证的兼容性矩阵，也没有最终 UI 的验证截图。
- 实验性 DSH API： Agent Team 和 Sidebar 插件的集成点可能变化。动手实现前，必须先锁定并审查目标 DSH 版本。
- 站点专属认证： 共享 BrowserContext 只会共享适用的浏览器存储，并不共享每个站点绑定标签页或绑定服务端的登录状态。
- 无头兼容性： 原生文件选择器、部分权限/对话框、反自动化挑战，以及媒体/GPU 行为，可能需要专门处理或安全回退。
- 恢复能力有边界： 恢复浏览器元数据，并不能恢复每一处瞬时的 DOM/JS 状态。
- 安全隔离： 共享上下文就是有意共享凭据。不同团队、不同工作区默认必须隔离，未经明确授权不得共享 cookie。
- 在测试完成前不保证操作系统焦点： 焦点保持是一项验收要求，需要在目标桌面平台上验证，而不是已经完成验证的声明。

开发与项目参考

预期的实现策略是有选择地复用，自己掌握集成：

- wqty123/dsh-browser —— 浏览器服务、现有工具，以及会话/标签页原语，可供审计并在合适处复用。
- try-works/dsh-browser-agent —— CDP 帧流式传输与交互式 Web UI 方案，可供评估。
- stuarthu/dsh-chrome —— 网络检查与敏感数据过滤技术，可供评估。
- DeepSeekHarness right sidebar design —— 侧边栏集成参考。
- DeepSeekHarness Agent Team design —— 队友身份、名册与生命周期参考。
- Chrome DevTools Protocol —— 浏览器控制 API 参考。

这些仓库是设计与潜在代码来源，不一定是依赖项。任何复制的代码都必须保留相关许可证与版权声明，包括传递性声明。最终源码布局、构建命令与测试命令取决于上游 API 审计，等它们真正确定后再写入文档。

贡献

在第一个可用版本发布之前，有价值的贡献包括：可复现的 DSH API 兼容性发现、无头/CDP 浏览器测试用例、授权威胁模型，以及 UI/视口测试场景。提交 issue 时请附上 DSH 版本/commit、操作系统、复现步骤、预期行为与实际行为。切勿在日志或截图中发布真实 cookie 或凭据。

许可证与致谢

这个新仓库的许可证尚未选定。 不要假设它与配套的 presets 插件使用同一许可证。复用或分发代码之前，请检查每个上游许可证（包括 MIT/ISC 组件以及额外的 NOTICE 文件），保留必要的署名，并发布仓库自己的许可证与第三方声明。

感谢 DeepSeekHarness 维护者与浏览器插件社区，他们提供的基础思路与实现启发了这份设计方案。实际纳入的代码将明确保留署名。

项目： dsh-agent-team-browser · 维护者： bloodarea · 配套项目： dsh-agent-team-presets