BrowserSkill/packages/dsh-plugin-browserskill

1.2kStars99Forks29Issues6Watchers

把 BrowserSkill (bsk) 命令行包成 DSH 原生 browser_* 工具，让 AI 在不退出你浏览器的情况下驱动真实 Chromium。

TencentTencent
·Tencent/BrowserSkill.git
Language
TypeScript
License
MIT
Branch
main
agentbrowser-usedsh-plugin

Install

$ dsh plugin --profile web add github:Tencent/BrowserSkill/packages/dsh-plugin-browserskill

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

一句话定位

把 BrowserSkill（命令行叫 bsk）的浏览器自动化能力包成 DeepSeek Harness 的原生模型工具，让 AI 在你已有的浏览器里完成任务而不打断你日常浏览。

核心能力

  • 在 DSH 进程内注册 11 个 browser_* 模型工具：会话启停 / 列表、导航、快照、语义观察、点击、填写、按键、截图、设备模拟，每个工具对应一次 bsk <cmd> --json 调用
  • 同时驱动多个浏览器会话：每次 browser_session_start 返回独立的会话 id，最多 5 个并发；不传 session 参数时落到最近一次操作过的那个会话
  • 严格的所有权边界：插件只跟踪自己启动的会话，传外部会话 id 会被直接拒绝；列表工具也只显示自己拥有的会话，卸载时只会清理自家会话，绝不误伤其他程序共享的 bsk 守护进程里的会话
  • 每会话串行执行命令：bsk 守护进程一次只接受一个未完成的命令，插件用每会话 FIFO 把模型工具调用和后台观察流量排进同一条队列
  • 渐进式披露：默认 lazyTools=true 时，11 个工具的 schema 不会出现在系统提示里，等模型真的调一次 browser-skill（或用户输入 /browser-skill）后整套工具才会在当前进程剩余生命周期里全部现身
  • 取消语义打通：DSH 的取消信号会传到 runner，SIGTERM 杀掉正在执行的 bsk 子进程（2 秒不退就 SIGKILL），模型这边可以继续下一步
  • DSH Web UI 浮窗观察：每个自有会话有一张实时缩略图、当前动作、计时，可拖动 / 缩放、可一键中断当前命令、可升级为原生画中画窗口；前端通过宿主 webServer 提供的 loopback 路由拿数据
  • 启动时做一次轻量探针：插件加载后立刻跑 bsk --version，缺失时提前打 warning，第一次工具调用会返回安装指引而不是裸的 spawn 错误

技术实现

  • 语言: TypeScript
  • 关键依赖: @deepseek-ai/cordis（^4.0.1，插件注入与配置校验）、@deepseek-ai/dsh-tools + @deepseek-ai/dsh-llm（^0.1.0-rc.6，工具注册与内容块类型）、@deepseek-ai/schemastery（^3.18.1，Config Schema）、node:child_process（spawn bsk 子进程）
  • 架构模式: 双面 Cordis 插件（dsh.bundle.patch 注入 tools 服务；dsh.client 注入 web 前端 React 工具视图），通过 Schemastery Config 校验配置；启动时建立会话注册表 + 每会话 FIFO 执行器 + 观察服务三件套，再用 ctx.inject(["webServer"], ...) 延后挂载 HTTP 路由；模型可见的工具集走"渐进式披露"，skill 调用前只挂目录项、不挂 11 个工具 schema
  • 入口文件: src/index.ts（插件 apply 入口 + Config Schema）、src/tools.ts（11 个模型工具定义）、src/runner.ts（bsk 子进程 spawn + 取消 / 超时 / 错误信封解析）、src/sessions.ts（会话所有权注册表）、src/lazy-tools.ts（技能调用的工具套揭示监听）、src/observation.ts + src/observation-http.ts（观察服务与 loopback HTTP 路由）

适用场景

当你希望 AI 在你的真实浏览器里完成需要登录态、需要看到视觉界面的任务（比如抓取需要登录的内容、跨页面表单填写、模拟移动端表现、操作你自己已有的标签），又不想为它单独再开一个测试浏览器账号时，这个插件就是桥梁。它借走的是浏览器扩展隔离出来的窗口，你日常用的标签页不受影响，AI 完成动作或你按中断后窗口会被归还。

前置依赖与兼容性

依赖最低版本说明
DeepSeek Harness0.1.0-rc.6+由 peerDependencies 中 @deepseek-ai/cordis ^4.0.1 与 @deepseek-ai/dsh-* ^0.1.0-rc.6 推导；需要在同时挂载 tools、skills 与 webServer（仅 Web 端需要）服务的宿主里运行
Node.js未声明package.json 未声明 engines；源码仅使用 node:child_process / node:fs/promises / node:os / node:http 等内置模块，无原生依赖
浏览器运行时macOS（Apple Silicon / Intel）、Linux（x64 / ARM64）、Windows x64由 bsk CLI 决定，插件本身跨平台（无 os / cpu 限制）
浏览器Chrome、Microsoft Edge其他 Chromium 内核浏览器理论可用，Firefox 暂未支持
原生模块无纯 TypeScript，零原生依赖

安装方式

dsh plugin --profile web add github:Tencent/BrowserSkill/packages/dsh-plugin-browserskill

配置项

配置类型说明默认值
bskPathstringbsk 可执行文件路径，默认从 PATH 里找 bskbsk
defaultTimeoutMsnumber每次 bsk 命令的超时（毫秒）120000
maxSessionsnumber允许同时开启的浏览器会话上限5
observationEnabledboolean是否跟踪每个会话的动作 / 链接 / 缩略图状态，用于 Web 端浮窗true
thumbnailIntervalMsnumber会话活跃时的缩略图刷新节奏（毫秒）1500
idleIntervalMsnumber会话空闲时的缩略图刷新节奏（毫秒），也是"最近活动"窗口8000
lazyToolsboolean是否启用渐进式披露——把 11 个 browser_* 工具的 schema 隐藏在系统提示里，直到 browser-skill 被调用一次再揭示true

常见问题

Q: 不装 bsk CLI 和浏览器扩展能跑这个插件吗？

A: 能加载，但所有 browser_* 工具调用都会失败。插件加载时只会打一条 warning；第一次工具调用时 runner 会捕获到 spawn 错误，并返回一条带安装链接的人话指引，而不是裸的 ENOENT。

Q: 一个会话结束后，浏览器扩展里的 Agent Window 会自动关掉吗？

A: 会。browser_session_stop 会调用 bsk session stop <id>，由浏览器扩展回收对应的 Agent Window；插件卸载（unload）时会按 owned 列表把所有还活着的会话一并关掉，释放 bsk 子进程。

Q: 插件会把浏览器会话存到哪里？跨次启动还在吗？

A: 只存内存。SessionRegistry 是一个进程内的 Map，卸载插件即丢失；下次再启动需要重新走 browser_session_start。lazyTools 在会话恢复时会扫描持久化事件日志，发现历史里已经成功调用过 browser-skill 也会自动揭示工具套，但已关闭的会话不会复活。

Q: 观察浮窗的截图会被外网访问到吗？

A: 不会。这几条路由只接受 loopback 请求（localhost / 127.0.0.0/8 / [::1]），且复制了 DSH 给自家 /api 路由加的浏览器信任栅栏：Origin 与 Host 必须一致，sec-fetch-site: cross-site 一律拒绝，POST 必须 application/json。如果把 DSH webServer 绑到 0.0.0.0 再通过 LAN 访问，栅栏会主动失败——这是设计要求，不是 bug。

Q: 我能不能绕过插件，直接 bash 调用 bsk？

A: 不要。skill 的 prelude 里明确写了：DSH 里的浏览器任务必须走注入的 browser_* 工具，绕过插件直接调 bsk 会丢失会话所有权、观察浮窗、工具卡片和卸载清理；模型视角下这种"绕过去"的调用被认为是错误行为。

Q: 浮窗里的"中断"按钮和聊天里的 Stop 按钮是一回事吗？

A: 行为等价，都是给当前正在运行的 bsk 子进程发 SIGTERM，中断这一次命令；agent 主循环不会因为一次命令被中断就停下，会按既定逻辑继续。

上手难度

进阶 — 需要先装好 bsk CLI 和浏览器扩展两件本地依赖，并理解插件只跟踪"自己启动"的会话这条边界规则，但配置项少且全部可选，开箱即可工作。

已知问题与限制

  • 长时运行类命令（如 bsk record）目前还不会通过 ctx.jobs 走后台任务通道，仍作为同步工具调用阻塞到完成，已在 README 中列为后续工作
  • bsk console 与 bsk network 这两个 CLI 动词目前还没有对应的 browser_* 工具，skill prelude 明确写了这点
  • Web UI 的画中画（Document PiP）按钮依赖浏览器原生能力，Chrome / Edge 支持但需要一次用户手势触发；不支持 Document PiP 的浏览器会直接隐藏该按钮而非降级
  • 观察浮窗相关 HTTP 路由要求宿主绑定在 loopback 地址；试图把 DSH webServer 绑到 0.0.0.0 再走 LAN 访问会被浏览器信任栅栏主动拒绝——这是预期行为，需要跨网访问必须自行在前面再加一层鉴权
  • 工具调用必须通过 browser_session_start 拿到自家会话 id 之后才能用，其他工具在"还没有任何会话"时会直接报错；browser_session_list 不会显示其他程序共享 bsk 守护进程创建的会话（这是设计而非 bug）
← Back to plugin directory