前言¶
DSH 的理念是“一切皆插件”。在让智能体处理网页任务时，常见的卡点不只是“能不能点”或“能不能填”，还包括登录、凭据边界、登录态保留，以及页面视觉状态是否可被理解。已有做法如果只是调用一个无头浏览器，往往看不到窗口、不能人工接管登录，登录态也容易丢失。
dsh-browser-companion 针对这些问题，为 DSH 提供一个浏览器插件：它让智能体获得一个持久 profile、可见窗口、人工登录通道，以及一组相对安全的浏览器操作工具。
这是什么¶
dsh-browser-companion 是一个个人 DSH 浏览器插件。它给智能体一个专用、持久、可见的浏览器环境，核心目标是：
- 智能体可以打开页面、点击、输入、滚动、管理标签页等；
- 用户可以在真实窗口中完成登录、输入密码或完成 OAuth；
- 密码和 OAuth secret 不经过智能体；
- cookie、localStorage 和登录状态保存在同一 profile 中，重启后可继续保留。
许可证为 MIT。GitHub 仓库地址为：
https://github.com/Tianyu209/dsh-browser-companion
核心功能¶
持久浏览器 profile¶
插件会保留浏览器 profile 中的登录态。已核实的能力包括：
- 持久化 cookie；
- 持久化 localStorage；
- 持久化登录状态。
这意味着一些站点登录一次后，后续任务可以复用同一 profile，而不是每次都重新登录。
可见窗口¶
插件提供可见窗口模式，默认配置为：
headless: false
也就是说，智能体操作浏览器时，用户可以看到真实的浏览器窗口。这对观察智能体动作、人工接管登录比较重要。
人工登录¶
插件提供 browser_login 和 browser_wait_login：
browser_login打开一个可见登录窗口，由用户自己输入密码或完成 OAuth；browser_wait_login等待登录完成，判断依据包括 cookie / URL。
密码和 OAuth secret 由用户在浏览器窗口中处理，不经过智能体。
浏览器操作工具¶
已核实的 agent tools 包括：
open, snapshot, click, type, press, screenshot, see, select, check, upload, hover, scroll, tabs, status
其中几个常用工具：
open：打开页面；snapshot：获取 accessibility snapshot / refs；click/type/press：基础交互；select/check：表单控件操作；upload/hover/scroll/tabs/status：更细粒度的页面操作。
安全边界¶
插件对敏感输入做了限制：
browser_type拒绝填写密码字段；- 智能体被要求不要填写密码字段；
- 密码和 OAuth secret 由用户在可见浏览器窗口中输入。
视觉理解¶
browser_see 使用本地视觉模型（OpenAI-compatible）来辅助智能体理解图片、视觉布局或复杂界面。默认应优先使用 browser_snapshot，因为它更快、成本更低，并带有 refs；只有需要视觉判断时再使用 browser_see。
如果 browser_see 未配置，它会返回友好消息，而不是中断智能体。
安装与启用¶
先安装依赖：
npm install -g agent-browser
agent-browser install
然后在 web profile 中添加插件：
dsh plugin --profile web add dsh-browser-companion
最后启动或重启 DSH：
dsh web
如果使用 pnpm，并且从 GitHub 安装时遇到 agent-browser build script 被阻止，可以在 profile 的 pnpm-workspace.yaml 中加入：
allowBuilds:
agent-browser: true
然后重新安装。
典型用法¶
下面是一个登录流程：
1、智能体需要进入某个站点，但需要先登录。
2、智能体调用 browser_login 打开可见登录窗口。
3、用户在窗口中完成登录、输入密码或 OAuth 授权。
4、用户告知智能体已完成。
5、智能体调用 browser_wait_login 等待登录状态确认。
6、智能体在同一 profile 的 cookie 状态下继续后续操作。
页面读取也有一个简单原则：
1、默认使用 browser_snapshot，获取快速、免费的 accessibility tree 与 refs。
2、只有遇到图片、视觉布局或复杂 UI 时，再使用 browser_see。
3、如果本地视觉模型未配置，browser_see 会给出友好提示。
可选配置¶
可以在 DSH WebUI 的插件设置中修改这些配置项：
executablePath：指定浏览器可执行文件；visionBaseUrl/visionModel：配置本地视觉模型，用于browser_see；profilePath：指定浏览器 profile 路径。
需要自定义浏览器、视觉模型或 profile 位置时再修改即可。
适用场景与注意¶
适合以下场景：
- 需要 DSH 智能体完成网页操作，但登录必须人工完成；
- 需要保持浏览器登录态，避免每次任务都重新登录；
- 需要看到浏览器窗口，便于人工观察和接管；
- 需要智能体理解图片、视觉布局或复杂 UI。
使用前注意：
- 插件会运行在本机，并以当前 dsh 进程权限执行；安装前应检查源码和许可证。
- 不要提交真实路径、token 或个人 profile 数据；使用示例配置并本地替换值。
- 密码和 OAuth secret 始终由用户在可见浏览器窗口中处理，不应作为普通文本交给智能体。
browser_see依赖本地视觉模型配置；未配置时不会中断智能体，但也不会提供视觉理解结果。
结尾¶
dsh-browser-companion 的价值比较具体：它把“智能体操作浏览器”和“人工登录 / 凭据边界”拆开了，同时保留可见窗口和持久 profile。对于希望 DSH 能处理真实网页任务、又不想把密码交给智能体的场景，它是一个比较直接的插件。
GitHub 仓库：
https://github.com/Tianyu209/dsh-browser-companion
DSH 社区目录：可按插件名 dsh-browser-companion 在 DSH 社区目录中查找；本文不给出未核实的目录页 URL。
