@lunarcache/dsh-kimi-webbridge

Readme

<h1 align="center">dsh-kimi-webbridge</h1>

<p align="center">
  <a href="README.md">English</a> · <a href="README.zh.md">简体中文</a>
</p>

<p align="center">
  <strong>让 DSH agent 通过 Kimi WebBridge 驱动你的真实浏览器</strong> —— 导航、读页、点击、填表、截图，直接复用登录会话。<br/>
  <a href="https://badgen.net/badge/license/MIT/green"><img src="https://badgen.net/badge/license/MIT/green" alt="license" /></a>
  <a href="https://badgen.net/badge/format/official%20bundle/8257D0"><img src="https://badgen.net/badge/format/official%20bundle/8257D0" alt="format" /></a>
</p>

---

[Kimi WebBridge](https://www.kimi.com/zh-cn/products/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_*`

## 安装

```sh
# 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 实时生效）：
> ```yaml
> - insert:
>     - id: dsh-kimi-webbridge
>       name: '@lunarcache/dsh-kimi-webbridge'
> ```
> 二选一，不要同时走两条路径（避免重复挂载）。

## 验证

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

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

## 卸载

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

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

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

## 更新

```sh
# 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 层中覆盖：

```yaml
- 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 未运行（连接被拒）**

```sh
# 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 中近期发布的条目（与插件本身无关，拦的是环境里其他近期发布的包）。两种官方单次绕过（不修改任何策略配置）：

```sh
# 安装：--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` 的站点（银行、验证码）会忽略合成事件，需要人工操作。

## 开发与发布

```sh
# 本地打包
npm pack                      # 产出 lunarcache-dsh-kimi-webbridge-<version>.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 浏览器扩展](https://www.kimi.com/zh-cn/products/kimi-webbridge) 并保持 daemon 运行（见[故障排查](#故障排查)）。
- 系统 PATH 中有 `curl`（Windows 10/11 自带 `C:\Windows\System32\curl.exe`；macOS / Linux 自带）。

## 许可

MIT，见 [LICENSE](./LICENSE)。