Kimi 真实浏览器驱动LunarCache/dsh-kimi-webbridge

dsh-kimi-webbridge

English · 简体中文

让 DSH agent 通过 Kimi WebBridge 驱动你的真实浏览器 —— 导航、读页、点击、填表、截图，直接复用登录会话。

Kimi WebBridge（浏览器插件 + 本地 daemon，默认 http://127.0.0.1:10086）把你的真实浏览器（含全部登录会话）暴露为本地 API。本插件把 daemon 的每个动作注册为原生模型工具（webbridge_），让 DSH agent 能驱动你的真实浏览器——包括已登录的会话（淘宝、邮箱、后台等无需重新登录）。

特性

- 官方 bundle 形态：声明 dsh.bundle，dsh plugin --profile web add 一键安装进层栈
- 纯 ESM、零运行时依赖：只用宿主已提供的 tools + subprocess 服务，调用系统自带 curl
- 跨平台：Windows / macOS / Linux（系统需自带 curl）
- 全局生效：作为宿主行注册到全局工具层，所有会话的 agent 都能看到 webbridge_

安装

1) 本地 tarball / 目录
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-0.3.0.tgz

2) git 源（发布到 GitHub 后）
dsh plugin --profile web add github:LunarCache/dsh-kimi-webbridge#main

3) npm（发布后）
dsh plugin --profile web add @lunarcache/dsh-kimi-webbridge

装完后重启 web（bundle 进层栈生效，见下方验证）。

纯 cordis 手动挂载（不声明 bundle 时的替代路径）：dsh plugin --profile web add  后，在 $DSH_HOME/profiles/web/cordis.patch.yml 加 insert 行（配置 HMR 实时生效）：
- insert:
- id: dsh-kimi-webbridge
name: '@lunarcache/dsh-kimi-webbridge'

二选一，不要同时走两条路径（避免重复挂载）。

验证

1) 组合层确认（安装后、重启前即可查）
dsh --profile web --dump-config
输出中应出现：
== @lunarcache/dsh-kimi-webbridge
- id: dsh-kimi-webbridge
name: @lunarcache/dsh-kimi-webbridge

2) 重启 web 后，新会话的工具列表应包含 14 个 webbridge_* 工具

卸载

dsh plugin --profile web remove @lunarcache/dsh-kimi-webbridge

一步完成：删除依赖 + 自动把 @lunarcache/dsh-kimi-webbridge 从 dsh.profile.bundles 层栈移除。装完/卸完都要重启 web 生效。

⚠️ 若 pnpm 报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION（供应链校验，见故障排查），加上单次覆盖参数：
dsh plugin --profile web remove @lunarcache/dsh-kimi-webbridge --config.minimumReleaseAge=0

更新

1) 修改源码后提升版本号（package.json），重新打包
npm pack

2) 用新 tarball 覆盖安装（会替换依赖与层栈），然后重启 web
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-.tgz

不要手改 profile 的 package.json/cordis.patch.yml 来升级——dsh plugin 会按已安装状态自动 reconcile 层栈。

配置

| 字段 | 默认值 | 说明 |
|---|---|---|
| daemonUrl | http://127.0.0.1:10086/command | WebBridge daemon 的命令端点 |
| defaultSession | dsh-webbridge | 调用未指定 session 时使用的标签分组名 |
| timeoutMs | 40000 | 单次 daemon 调用预算（毫秒），同时驱动 curl --max-time |

在 profile 的 cordis.patch.yml 或 bundle 层中覆盖：

- insert:
- id: dsh-kimi-webbridge
name: '@lunarcache/dsh-kimi-webbridge'
config:
defaultSession: my-task
timeoutMs: 60000

工具

| 工具 | 说明 |
|---|---|
| webbridge_navigate | 打开 URL（可选新标签页 + 用户语言的分组标题） |
| webbridge_find_tab / webbridge_list_tabs | 找回 / 列出标签页 |
| webbridge_snapshot | 读取页面无障碍树（带 @e 元素引用） |
| webbridge_click / webbridge_fill | 点击元素 / 填充输入框与富文本编辑器 |
| webbridge_evaluate | 在页面内执行 JS |
| webbridge_screenshot / webbridge_save_as_pdf | 截图 / 页面存 PDF（截图返回本地文件路径） |
| webbridge_upload / webbridge_network / webbridge_cdp | 上传文件 / 抓网络请求 / 底层 CDP 透传 |
| webbridge_close_tab / webbridge_close_session | 关闭当前标签页 / 关闭整个会话组 |

每个工具都接受可选的 session 参数（默认 dsh-webbridge）。一个任务 = 一个 session = 一个浏览器标签分组；关闭标签页永远由用户发起。

工作原理

1. 工具 execute 通过注入的 subprocess 服务 spawn 系统 curl。
2. JSON 请求体经子进程 stdin 写入（curl --data-binary @-），避免 shell 转义与中文乱码。
3. 解析 daemon 返回的 { ok, data }，把 data 作为工具结果返回给模型。
4. 支持取消：工具调用被中止时，exec.signal 传递到子进程使其终止。

注意：插件不要在 package.json 里声明 @deepseek-ai/* / cordis 依赖——由 dsh 运行时经 profile pnpm 闭包注入（profile 的 pnpm-workspace.yaml 为 nodeLinker: hoisted + autoInstallPeers: false）。声明为 dependencies 会让 pnpm 尝试从公共 npm 拉取版本不一致的包。

故障排查

daemon 未运行（连接被拒）

Windows
& "$env:USERPROFILE\.kimi-webbridge\bin\kimi-webbridge.exe" start
macOS / Linux
~/.kimi-webbridge/bin/kimi-webbridge start

扩展提示版本过旧（错误信息含 "Please update the Kimi WebBridge extension"）：去浏览器扩展商店更新扩展后重试，不要尝试手动修复版本。

pnpm 供应链校验拦截安装/卸载（ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION）

pnpm 11 的 minimumReleaseAge 策略会校验 lockfile 中近期发布的条目（与插件本身无关，拦的是环境里其他近期发布的包）。两种官方单次绕过（不修改任何策略配置）：

安装：--trust-lockfile 或 --config.minimumReleaseAge=0
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-0.3.0.tgz --trust-lockfile
dsh plugin --profile web add ./lunarcache-dsh-kimi-webbridge-0.3.0.tgz --config.minimumReleaseAge=0

卸载：remove 不认 --trust-lockfile，用 --config.minimumReleaseAge=0
dsh plugin --profile web remove @lunarcache/dsh-kimi-webbridge --config.minimumReleaseAge=0

pnpm 首次绕过后会自动把被拦条目写入 profile pnpm-workspace.yaml 的 minimumReleaseAgeExclude，后续通常不再需要该参数。

页面上点击/填表无响应：部分严格校验 event.isTrusted 的站点（银行、验证码）会忽略合成事件，需要人工操作。

开发与发布

本地打包
npm pack                      # 产出 lunarcache-dsh-kimi-webbridge-.tgz

发布到 GitHub（建议）：
- 仓库 description 格式：DSH plugin: ; official bundle, install via dsh plugin --profile web add github:LunarCache/dsh-kimi-webbridge#main
- topics 打标：dsh / dsh-bundle / deepseek-harness + 功能词（如 browser / automation）

发布前检查清单：main/exports 指向 index.js；dsh.bundle.patch → cordis.patch.yml；README 安装命令可直接复制；安装冒烟通过（装 → 挂载 → 重启 → 工具可见）。

前置条件

- 已安装 Kimi WebBridge 浏览器扩展 并保持 daemon 运行（见故障排查）。
- 系统 PATH 中有 curl（Windows 10/11 自带 C:\Windows\System32\curl.exe；macOS / Linux 自带）。

许可

MIT，见 LICENSE。