dsh-kimi-webbridge 工程文档

August 14, 2026 · View on GitHub

面向 DeepSeek Harness（dsh）的第三方插件 bundle：通过 Kimi WebBridge 本地守护进程把用户真实浏览器（含登录态）开放为 15 个原生 kimi_webbridge_* 工具。适用版本：dsh v0.1.0-rc.6（已实测）；WebBridge 守护进程（Windows 实测）。

1. 项目概述

项	值
包名	`dsh-kimi-webbridge`
形态	Cordis 插件 bundle（`dsh.bundle.patch`）
运行时	纯 Node ESM，Node ≥ 18，无构建步骤
依赖	零依赖：`@deepseek-ai/dsh-tools` 运行时经 healed closure 由 dsh 安装解析（声明 peerDependencies 会诱导 pnpm 从 registry 装副本并遮蔽 closure，故不声明）
对外能力	15 个 `kimi_webbridge_*` 工具（见 `docs/api-reference.md`）
不改动	`deepseek-harness` 安装文件、`$DSH_HOME` 配置（零文件系统访问）

2. 目录结构

DSHKimiWebBridge/
├── package.json          # bundle 清单：dsh.bundle.patch → cordis.patch.yml
├── cordis.patch.yml      # 组合层：插入 {id: kimi-webbridge} 行及默认配置
├── index.js              # 插件模块：name/inject/apply + 15 工具注册 + HTTP 客户端
├── tests/
│   ├── smoke.mjs         # 冒烟测试：真实 dsh-tools 链接 + 离线校验 + 在线端到端
│   └── stub/@deepseek-ai/dsh-tools/   # 离线兜底桩（无 dsh 环境时使用，非发布物）
├── docs/                 # 本文档集
├── README.md / README.zh-CN.md
└── LICENSE / .gitignore  # node_modules/ 与 *.log 忽略

node_modules/ 仅由 tests/smoke.mjs 在运行期创建（指向真实 dsh-tools 的 junction），不提交、不参与运行时解析。

3. 架构与数据流

┌─ deepseek-harness 进程 ─────────────────────────────────────────┐
│  cordis.yml 组合 → loader 解析行 {id: kimi-webbridge}            │
│       │ Node ESM 解析包名 → index.js                              │
│       ▼                                                          │
│  apply(ctx, config)  (inject: ['tools'] 等待服务就绪)            │
│       │ ctx.tools.register(defineTool(def)) × 15                 │
│       ▼                                                          │
│  工具注册表 → system-prompt 组装 schema 注入模型请求              │
│       │                                                          │
│  模型调用工具 → validateArgs（INVALID_ARGS 拒绝）→ execute        │
│       │ exec.signal（取消）+ requestTimeoutMs 超时                │
│       ▼                                                          │
│  POST {baseUrl}/command  {action, args, session}                 │
└───────┬──────────────────────────────────────────────────────────┘
        ▼ 127.0.0.1:10086
┌─ Kimi WebBridge 守护进程 ────────────────────────────────────────┐
│  响应 {ok:true, data} | {ok:false, error:{code,message}}         │
└───────┬──────────────────────────────────────────────────────────┘
        ▼ chrome.debugger 扩展
┌─ 用户真实浏览器（含登录态）───────────────────────────────────────┘

失败路径：

守护进程不可达 → fetch failed → 报错信息附带 kimi_webbridge_start_daemon 提示与帮助 URL；
超时（仅 screenshot / save_as_pdf）→ 自动重试 1 次（新标签首次截图可能卡顿，重试即秒回）；
守护进程返回 ok:false → 原样透传 error.message。

4. 模块设计（index.js）

段	职责	说明
`DEFAULT_CONFIG` / `normalizeConfig`	配置默认值与校验	非法配置抛带操作指引的错误，符合 harness "配置错误即可操作化" 约定
`daemonBinPath`	守护进程二进制路径	Windows `%USERPROFILE%\.kimi-webbridge\bin\kimi-webbridge.exe`；POSIX `~/.kimi-webbridge/bin/kimi-webbridge`；`daemonBin` 可覆盖
`withAbort`	信号合成	`exec.signal` + `requestTimeoutMs` 超时 → 单一 AbortSignal；`timedOut()` 区分超时与取消
`requestDaemon`	HTTP 单次请求	解析 `{ok,data}/{ok:false,error}` 信封；网络错误分类（timeout / unreachable / 非法响应）
`callDaemon`	带重试的请求	`retryOnTimeout:true` 时超时后 sleep 1.5 s 重试 1 次（幂等捕获类工具专用）
`cleanArgs`	参数清洗	丢弃 `undefined`，避免把未传可选参数序列化成显式 null
`renderJson`	渲染	`[{type:'text', text}]`，超 `maxRenderText` 截断
`obj`/`req`/`opt`	schema 助手	`req`/`opt` 仅在提供描述时附加 `description`（见 `docs/solutions.md` #2）
`exec`	通用 execute 工厂	大部分工具共用；参数与 daemon action 一一对应
工具注册	15 个 `defineTool` 调用	参数即 daemon 参数名（`group_title`、`newTab`、`paper_format`…）；输出 schema 与实测信封逐键对齐
`kimi_webbridge_start_daemon`	特殊实现	spawn 二进制（`detached`+`unref`）→ 20 s 轮询就绪 → `{started}`；不走 `/command`
`kimi_webbridge_evaluate`	特殊实现	`value ?? null` 归一化（见 `docs/solutions.md` #7）

5. 生命周期

安装：dsh plugin --profile <p> add ./DSHKimiWebBridge（pnpm 在 profile 目录运行，成功后 reconcilePlugins 按"是否声明 dsh.bundle"把包加入层栈）。替代路径：--patch overlay / 手动合并 $DSH_HOME patch（见 README.zh-CN.md）。
加载：loader 组合各层 → 解析行 → ESM 解析包名（peer 依赖经 $DSH_HOME/profiles/node_modules 的 healed closure 解析到 dsh 安装内副本）。
注册：apply(ctx, config) 在 inject:['tools'] 就绪后执行；defineTool 编译并校验 schema（编译期失败会中止加载并给出 UNSUPPORTED_SCHEMA 明细）。
调用：模型按注入的 schema 调用；注册表先 validateArgs 再执行；execute 返回 canonical 值经输出 schema 校验后进入会话。
卸载：dsh plugin --profile <p> remove dsh-kimi-webbridge → 依赖移除 → 层栈摘除 → 工具随插件上下文 dispose 注销。模板 bundle 永不被触碰。

6. 配置键（行 `config:`）

键	默认	说明
`baseUrl`	`http://127.0.0.1:10086`	守护进程端点
`session`	`dsh`	WebBridge 侧标签分组名；一个 profile 一个名字
`requestTimeoutMs`	`120000`	单请求超时（截图/导航可能较慢）
`startDaemonTool`	`true`	是否暴露 `kimi_webbridge_start_daemon`
`daemonBin`	`null`	覆盖守护进程二进制路径
`maxRenderText`	`50000`	渲染文本上限（对齐 dsh spill 默认）

覆盖方式：profile patch / --patch overlay 按 id kimi-webbridge 整行重写。

7. 开发与验证工作流

# 1. 静态检查
node --check index.js

# 2. 冒烟测试（自动链接真实 dsh-tools，回退 tests/stub）
node tests/smoke.mjs
#   part 0  链接真实 @deepseek-ai/dsh-tools（healed closure → npm 全局 dsh）
#   part 1  15 工具注册 / 配置校验 / start_daemon 语义
#   part 1e 真实 defineTool 编译 + 编译产物 raw-schema 边界深遍历
#   part 2  在线端到端（守护进程可达时）：navigate→snapshot→evaluate→screenshot→list_tabs→close_session

# 3. 真实 harness 行为测试（headless profile）
dsh --profile headless "…任务…"

# 4. 主 profile 启动复核
dsh --profile web   # 20~30 s 观察日志无 kimi 相关报错

# 5. 卸载验证
dsh plugin --profile headless remove dsh-kimi-webbridge   # 可选，验证可逆

8. 分发与发布

npm 发布：package.json 已声明 files（index.js / cordis.patch.yml / README×2 / LICENSE）、dsh.bundle.patch、dsh-plugin 关键词与 GitHub topic。
git 安装：无 prepare 脚本 → 无需 allowBuilds 授权。
版本兼容：peer 依赖 *；已实测 dsh v0.1.0-rc.6 的 @deepseek-ai/dsh-tools 编译与边界规则。上游 schema DSL 变更时以 tests/smoke.mjs part 1e 作为回归闸门。

9. 相关文档索引

文档	内容
`docs/glossary.md`	标准术语表（dsh 生态 + WebBridge 域）
`docs/api-reference.md`	15 工具 API、配置 API、内部函数、WebBridge HTTP API
`docs/solutions.md`	踩坑记录、疑难问题、解决方案与方法论（含出处地址）
`README.md` / `README.zh-CN.md`	用户向安装/使用/故障排查（默认英文，可切换中文）