bill9109/dsh-webbridge

安装： dsh plugin --profile web add github:bill9109/dsh-webbridge

DeepSeek Harness 宿主插件：把 Kimi WebBridge 的本地守护进程桥接成 11 个 webbridge_* 模型工具，让模型操作你自己的浏览器——登录态、Cookie、已打开的标签页全保留——而不是无头浏览器。

English | 中文

为什么需要它

当模型任务要接触真实网站——一个需要你登录、带着你的会话和已打开标签页的页面——无头浏览器帮不上忙：它没有你的任何状态，还会要求你重新认证一遍。dsh-webbridge 的存在就是为了把你的真实浏览器交给模型控制，同时让浏览器状态严格留在你的机器上，绝不进入模型请求。

它不包含任何浏览器驱动代码：真正的活由 Kimi WebBridge 守护进程和浏览器扩展完成，本插件只在 DSH 一侧把能力翻译成模型工具。

实现能力

• 真实浏览器，不是无头浏览器：登录态、Cookie、活动会话全保留
• 11 个模型工具：navigate / find_tab / snapshot / click / fill / evaluate / screenshot / list_tabs / network / close_tab / close_session
• 一个任务 = 一个标签组：session 名分组标签页，任务之间 干净隔离
• 本地优先：守护进程跑在本机，浏览器状态不出你的机器
• 无 KV Cache 负担：浏览器状态存在于模型请求之外

使用

前置依赖（必装！）

本插件只是适配层——不装下面的东西，浏览器控制不成立。必须单独安装 Kimi WebBridge（月之暗面的独立产品，本插件不含其任何代码）。安装与浏览器 扩展的完整配置步骤见 Kimi 官方页面： 链接如下： 功能页 / 帮助中心。 摘要如下：

# 1. 安装守护进程：
curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash

# 2. 安装 Kimi WebBridge 浏览器扩展并连接守护进程（Chrome 应用商店搜索
#    "Kimi WebBridge"），然后检查就绪：
kimi-webbridge status   # 期望看到 "extension_connected": true

守护进程未运行时，工具会以 daemon_unreachable 错误响亮失败，并提示你运行 ~/.kimi-webbridge/bin/kimi-webbridge start。

模型体验

工具	用途
webbridge_navigate	打开 URL（新标签或当前标签），设置标签组标签
webbridge_find_tab	重新选择本任务打开的标签，或借用用户当前活动标签
webbridge_snapshot	读取页面的无障碍树（文本 + @e 引用）
webbridge_click	按 @e 引用或 CSS 选择器点击元素
webbridge_fill	在输入框 / 文本域 / contenteditable 编辑器中输入
webbridge_evaluate	在页面中运行 JS（支持 async）
webbridge_screenshot	截取页面或单个元素，输出到文件路径
webbridge_list_tabs	列出会话中打开的标签页
webbridge_network	检查网络活动（start/stop/list/detail）
webbridge_close_tab	关闭会话的当前标签页
webbridge_close_session	关闭会话的所有标签页（清空整个标签组）

会话与关闭规则（模型契约）

以下规则来自 Kimi WebBridge 上游 skill， 是模型必须遵守的契约：

• 一个任务 = 一个 session = 一个标签组。 任务开始时选定一个 session 名，并在每次调用中保持不变——切勿中途切换。
• 以任务命名，而非站点（如 camping-research，而不是 kimi.com）。
• group_title 是标签组的人类可读标签，在任务第一次 navigate 时设置，用用户的语言书写。
• 关闭永远是用户发起的。 仅在用户明确要求关闭/清理标签时 调用 webbridge_close_session；任务结束 绝不自动关闭。

配置

守护进程地址默认为 http://127.0.0.1:10086。插件目前不接受配置； baseUrl 接缝为测试保留。

安装

插件是 DSH bundle（package.json 声明 dsh.bundle，cordis.patch.yml 携带 patch）。通过标准的 dsh plugin 机制安装到 web profile—— 无需修改 DSH 源码、无需手写 patch：

dsh plugin --profile web add github:bill9109/dsh-webbridge

需要稳定版本时 pin 到 tag： dsh plugin --profile web add github:bill9109/dsh-webbridge#v0.0.2。

命令内部 = 在 profile 目录执行 pnpm add <spec>， 自动把声明了 dsh.bundle 的包追加进 dsh.profile.bundles。 也可以先 clone 再用本地路径安装 （开发调试）：

dsh plugin --profile web add /path/to/dsh-webbridge

仓库里带了构建产物（lib/），装完直接可用， 不需要另外构建。安装后重启 Web UI （production 模式没有热更新）并刷新页面， 模型即可看到 webbridge_* 工具。

升级

dsh plugin --profile web update github:bill9109/dsh-webbridge

本地路径安装则对替换后的 checkout 重新执行 add， 然后重启 Web UI 并刷新。

卸载

dsh plugin --profile web remove @bill9109/dsh-webbridge

命令内部 = 在 profile 目录执行 pnpm remove <pkg> + 自动把它从 dsh.profile.bundles 移除。卸载后重启 web 并刷新——DSH 内置插件（同一行 id webbridge）会重新接管。

与 DSH 内置版的关系

DSH 官方的 dsh-web-app bundle 也内置了同名插件 （@deepseek-ai/dsh-webbridge，行 id webbridge）。 本仓库是独立开源版，分发名为 @bill9109/dsh-webbridge： 安装后以同 id 覆盖内置版， 使用本仓库的代码；不装则以内置版为准。 两者工具行为一致， 协议层相同——差异只在包的维护方。

故障排查

症状	解决
工具报 daemon_unreachable	Kimi WebBridge 守护进程没在运行——执行 ~/.kimi-webbridge/bin/kimi-webbridge start 启动，再用 kimi-webbridge status 确认
kimi-webbridge status 显示 "extension_connected": false	安装 Kimi WebBridge 浏览器扩展（Chrome 应用商店）并让它连接守护进程；仍显示未连接就重启浏览器
安装后模型看不到 webbridge_* 工具	Web UI 必须重启并刷新页面（production 模式没有热更新）；用 dsh --profile web --dump-config | grep webbridge 确认 bundle 行在 profile 里
部分站点点击/输入没反应	严格检查 event.isTrusted 的站点（银行门户、验证码）会忽略合成事件；守护进程的 cdp 逃生口暂未暴露为工具
snapshot/click/fill/evaluate 对 iframe 无效	不支持跨域 iframe——这些工具只作用于顶层 frame
截图返回了路径但看不到图片	守护进程写入临时路径并返回路径，模型需用 Read 工具查看图片
标签组突然空了	标签组由守护进程维护，重启守护进程会清空——重建会话即可

仓库说明

工作原理

模型 ── webbridge_* 工具 ──▶ dsh-webbridge 插件
                                  │ POST /command
                                  ▼
                        kimi-webbridge 守护进程 (127.0.0.1:10086)
                                  │
                                  ▼
                        WebBridge 浏览器扩展
                                  │
                                  ▼
                        用户真实浏览器（含登录态）

每次工具调用就是一次到本机守护进程的 HTTP 往返；返回载荷被压缩成一行 summary + 原始 detail。

目录结构

dsh-webbridge/
├── src/               # 插件源码：index.ts（注册）、tools.ts（11 个
│                      #   webbridge_* 工具）、client.ts（HTTP 客户端）、invariant.ts
├── lib/               # 已提交的构建产物（tsc 类型 + tsdown bundle）——git
│                      #   安装直接消费
├── tests/             # client.spec.ts —— 针对 mock HTTP 守护进程的单元测试
├── scripts/           # build.mjs（构建）、verify-i18n.mjs（双语一致性检查）
├── cordis.patch.yml   # DSH bundle patch —— 行 id `webbridge`（覆盖内置版）
├── README.md          # 英文主 README
├── README.zh.md       # 中文 README
└── package.json

已知限制

• event.isTrusted —— 严格检查可信输入的部分站点（银行门户、 验证码）会忽略合成的 click/fill；守护进程的 cdp 逃生口 暂未暴露为工具
• 跨域 iframe —— snapshot/click/fill/evaluate 仅作用于 顶层 frame
• 截图 —— 守护进程写入临时路径并返回路径，模型需用 Read 工具查看图片
• 守护进程生命周期 —— 标签组由守护进程维护，重启守护进程 会清空

开发与验证

pnpm install
DSH_CHECKOUT=/path/to/dsh pnpm run build   # tsc → lib/types, tsdown → lib/index.js

peer 依赖与工具链来自 DSH：设 DSH_CHECKOUT 指向源码 checkout，或确保 PATH 里有 dsh 且跑过一次。 lib/ 已提交到仓库，git 安装直接拿到构建产物， 无需构建。单元测试（tests/client.spec.ts）用 mock HTTP 守护进程，无需真装 Kimi；在带 vitest 的环境（如 DSH checkout）里运行，设 KIMI_WEBBRIDGE_IT=1 可跑真实 守护进程的集成测试。

保持双语 README 同步：改完 README.md 和 README.zh.md 后运行 node scripts/verify-i18n.mjs --write。

社区与关于

• 可复现的 bug、聚焦的功能请求和使用问题，走 GitHub Issues。
• 提变更前先读 CONTRIBUTING.md；安全问题 通过 SECURITY.md 私有上报。
• 版本与兼容性说明见 CHANGELOG.md。
• 致谢与商标：本插件的协议层与 Kimi WebBridge 兼容。Kimi WebBridge 是月之暗面（Moonshot AI）的产品与商标； 其守护进程、浏览器扩展及代码均归月之暗面所有， 需按 Kimi 自身的条款单独安装使用。 本插件仅做 HTTP 协议适配， 不含上述任何代码。

License

BSD-3-Clause。见 LICENSE。