dsh-ava-bridge

DeepSeek Harness 插件：通过 ava-chrome-extension（已安装到 Chrome 的浏览器桥接扩展）控制浏览器。

插件在 Harness 内部启动一个与扩展配套的本地 daemon（HTTP + WebSocket，端口默认 19826），并注册一组 browser_* 模型工具。扩展通过 CDP 执行命令，结果回传后由工具渲染给模型。

模型 → browser_* 工具 → dsh-ava-bridge daemon (WS /ext) → Ava Chrome 扩展 (chrome.debugger/CDP) → 浏览器

前置条件

1. Chrome 中已安装 ava-chrome-extension（浏览器桥接扩展），通过「加载已解压的扩展程序」安装。
2. 一个可运行的 DeepSeek Harness profile（例如 dsh web）。

扩展默认探测 http://127.0.0.1:19826/ping 并连接 ws://127.0.0.1:19826/ext。本插件端口默认即 19826，无需改扩展配置。

安装 ava-chrome-extension

扩展的打包产物随本插件分发，位于 extension/ 目录：

extension/ava-chrome-extension-v1.0.0.zip

安装步骤：

1. 解压 extension/ava-chrome-extension-v1.0.0.zip 到本地目录（例如 ava-chrome-extension/）。
2. 打开 Chrome → chrome://extensions → 开启右上角「开发者模式」。
3. 点击「加载已解压的扩展程序」，选择解压出的目录。
4. 扩展加载后会自动探测并连接插件 daemon（ws://127.0.0.1:19826/ext）。

若扩展源码有更新，也可自行构建后在 extension/ 下替换新的 zip。

安装

方式 A：tarball（推荐）

dsh plugin --profile web add ./dsh-ava-bridge-0.1.0.tgz

方式 B：本地目录

dsh plugin --profile web add <本目录绝对路径>

安装后验证层生效（无需启动）：

dsh --profile web --dump-config

重启 dsh web 即生效。插件加载时会打印：

[ava-browser-bridge] loaded (daemon on 127.0.0.1:19826)
[ava-bridge] daemon listening on http://127.0.0.1:19826 (ws://127.0.0.1:19826/ext)

打开 http://127.0.0.1:3080，在对话里用自然语言让模型调用浏览器工具即可（例如「打开 example.com 并截图」）。

提供的工具

工具	作用	对应扩展 action
browser_status	查询 daemon/扩展连接状态	ping / 本地状态
browser_list_tabs	列出所有标签页	tabs (list)
browser_navigate	导航到 URL	navigate
browser_new_tab	新建标签页	tabs (create)
browser_activate_tab	激活标签页	tabs (activate)
browser_close_tab	关闭标签页	tabs (close)
browser_exec	在页面执行 JS	exec
browser_get_text	读取页面可见文本	exec
browser_click	按 CSS 选择器点击	exec
browser_type	向输入框输入文本	exec
browser_screenshot	截图（返回 base64）	screenshot
browser_cdp	发送原始 CDP 命令	cdp

配置项

在 profile 的 cordis.patch.yml（或 home 级 $DSH_HOME/cordis.patch.yml）覆盖：

- id: ava-browser-bridge
  name: dsh-ava-bridge
  config:
    host: 127.0.0.1      # daemon 绑定地址（默认 127.0.0.1）
    port: 19826          # daemon 端口（默认 19826，须与扩展一致）
    commandTimeout: 120000  # 单条命令超时 ms（默认 120000）
    autoStart: true      # 是否在加载时启动 daemon（默认 true）

注意：patch 覆盖是整行替换 config，覆盖时需重述所有键。

兼容性

• 本插件实现的 HTTP/WS 表面与 ava-chrome-extension 的 daemon/src/server.ts 完全一致：
  • GET /ping、GET /status、POST /command、WS /ext。
  • 扩展握手 hello、结果 result、日志 log，daemon→扩展 {id, action, params}。
• 因此既可作为 Harness 插件使用，也可被其他客户端复用 /command 端点。

开发与测试

pnpm install        # 安装 ws / schemastery 及 peer 依赖
node test/smoke.mjs # daemon 冒烟测试（模拟扩展，验证命令往返/错误/超时/HTTP）
node test/load.mjs  # 插件契约测试（验证 name/inject/Config/apply 与 12 个工具注册）

lib/daemon.js 不依赖任何 @deepseek-ai/*，可独立单测。

发布

一条命令完成「测试 → 打包 → 提交 → 打 tag → 推送 → 创建 GitHub Release 并上传 tgz」：

npm run release              # 自动 bump patch（如 0.1.0 → 0.1.1）
npm run release -- 0.2.0     # 指定版本
npm run release -- --dry-run # 只打印计划，不执行

前置要求：git（SSH remote，如 git@github.com:...）、已认证的 gh CLI、干净的 git 工作区。脚本逻辑见 scripts/release.mjs。

目录结构

dsh-ava-bridge/
├── package.json        # dsh.bundle 声明
├── cordis.patch.yml    # 插入插件行
├── index.js            # 插件入口（Config / apply / 生命周期）
├── lib/
│   ├── daemon.js       # AvaBridge：WS+HTTP daemon、命令往返
│   └── tools.js        # 12 个 browser_* 工具（defineTool）
├── extension/
│   └── ava-chrome-extension-v1.0.0.zip  # 浏览器扩展打包产物
├── scripts/
│   └── release.mjs     # 自动化发布脚本（npm run release）
├── test/
│   ├── smoke.mjs       # daemon 冒烟测试
│   └── load.mjs        # 插件契约测试
└── README.md