# dsh-webbridge — 通过 Kimi WebBridge 驱动你真实浏览器的模型工具

[![Release v0.0.3](https://img.shields.io/badge/release-v0.0.3-5B4CF0?style=flat-square)](https://github.com/omdsh-dev/dsh-webbridge/releases/tag/v0.0.3)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-0B7285?style=flat-square)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%5E20%20%7C%20%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
[![DSH profiles](https://img.shields.io/badge/DSH-Web-5B4CF0?style=flat-square)](cordis.patch.yml)

**安装：** `dsh plugin --profile web add github:omdsh-dev/dsh-webbridge`

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

[English](README.md) | 中文

## 为什么需要它

当模型任务要接触真实网站——一个需要你登录、带着你的会话和已打开标签页的页面——无头浏览器帮不上忙：它没有你的任何状态，还会要求你重新认证一遍。`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 官方页面：
链接如下：
[功能页](https://www.kimi.com/zh-cn/features/webbridge) /
[帮助中心](https://www.kimi.com/zh-cn/help/kimi-webbridge/kimi-webbridge-introduction)。
摘要如下：

```bash
# 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**：

```sh
dsh plugin --profile web add github:omdsh-dev/dsh-webbridge
```

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

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

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

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

### 升级

```sh
dsh plugin --profile web update github:omdsh-dev/dsh-webbridge
```

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

### 卸载

```sh
dsh plugin --profile web remove 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`）。
本仓库是独立开源版，分发名为 `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 工具查看图片
- **守护进程生命周期** —— 标签组由守护进程维护，重启守护进程
  会清空

## 开发与验证

```sh
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](https://github.com/omdsh-dev/dsh-webbridge/issues)。
- 提变更前先读 [CONTRIBUTING.md](CONTRIBUTING.md)；安全问题
  通过 [SECURITY.md](SECURITY.md) 私有上报。
- 版本与兼容性说明见 [CHANGELOG.md](CHANGELOG.md)。
- **致谢与商标**：本插件的协议层与 [Kimi WebBridge](https://www.kimi.com/)
  兼容。Kimi WebBridge 是月之暗面（Moonshot AI）的产品与商标；
  其守护进程、浏览器扩展及代码均归月之暗面所有，
  需按 Kimi 自身的条款单独安装使用。
  本插件仅做 HTTP 协议适配，
  不含上述任何代码。

## License

BSD-3-Clause。见 [LICENSE](LICENSE)。