@dsh-external/dsh-webbridge

DeepSeek Harness(DSH)宿主插件:让模型通过 Kimi WebBridge 驱动你的 真实浏览器——导航、快照、点击、填写、求值、截图、网络检查、标签页管理。

English | 中文

这是什么

dsh-webbridge 是 DeepSeek Harness(DSH) 的宿主插件。它把 Kimi WebBridge 的本地守护进程桥接成 11 个 webbridge_* 模型工具,让模型可以操作用户自己的浏览器——登录态、Cookie、已打开的 标签页全保留——而不是无头浏览器。浏览器状态留在用户浏览器里,绝不进入 模型请求。

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

工作原理

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

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

特性

• 真实浏览器,不是无头浏览器:登录态、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。

安装

# 装进官方 web profile(建议 pin 到 tag/commit 保证稳定):
dsh plugin --profile web add github:dsh-external/dsh-webbridge#v0.0.1

本包声明了 dsh.bundle,dsh plugin add 会把它追加为 profile 的 bundle 层并自动注册插件——不需要手写任何 patch。装完重启 dsh web(production 模式没有热更新,必须重启),刷新页面后模型即可看到 webbridge_* 工具。

与 DSH 内置版的关系

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

模型体验

工具一览

工具	用途
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 接缝为测试保留。

已知限制

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

开发

# 构建(peer 依赖与工具链来自 DSH:设 DSH_CHECKOUT 指向源码 checkout,
# 或确保 PATH 里有 dsh 且跑过一次):
DSH_CHECKOUT=/path/to/dsh pnpm build     # tsc → lib/types,tsdown → lib/index.js

lib/ 已提交到仓库,git 安装直接拿到构建产物,无需构建。单元测试 (tests/client.spec.ts)用 mock HTTP 守护进程,无需真装 Kimi;在带 vitest 的环境(如 DSH checkout)里运行,设 KIMI_WEBBRIDGE_IT=1 可跑真实守护进程 的集成测试。

致谢与商标

本插件的协议层与 Kimi WebBridge 兼容。Kimi WebBridge 是月之暗面(Moonshot AI)的产品与商标;其守护进程、浏览器扩展及 代码均归月之暗面所有,需按 Kimi 自身的条款单独安装使用。本插件仅做 HTTP 协议适配,不含上述任何代码。

License

BSD-3-Clause。见 LICENSE。