Skip to content
BranchesTags

Repository files navigation

dsh-chrome

让 DeepSeek Harness 直接使用你已经登录的 Chrome。

dsh-chrome 是一个面向 DeepSeek Harness 的 Chrome 控制插件。它把 chrome_repl 工具、control-chrome Skill、通用审批和 /chrome 管理命令打包成可安装的 DSH Bundle，让 Agent 能在用户授权后复用真实 Chrome Profile 中的登录态、标签页和扩展环境。

适合这些任务：操作登录后的后台、复用当前网页、检查页面状态、点击和输入、截图、上传文件、验证 Web UI，以及读取虚拟列表或无限滚动内容。

Important

本项目是非官方社区插件，与 DeepSeek AI、DeepSeek Harness 和万卷 Work 均无官方隶属或背书关系。DeepSeek Harness 当前仍处于开发者预览阶段，可能发生破坏性变更；本项目目前适配 @deepseek-ai/dsh-* >= 0.1.0-rc.6。

为什么是 dsh-chrome

DeepSeek Harness 采用“一切皆插件”的架构。dsh-chrome 沿用这套机制，不修改 Agent Loop：

  • 通过 ctx.tools 注册原生 chrome_repl 工具；
  • 通过 ctx.skills 注册内置 control-chrome Skill；
  • 通过 tools/pre-execute 接入 DSH 通用审批；
  • 通过 ctx.commands 提供完整 /chrome 文本命令；
  • 通过 dsh.bundle.patch 安装到 web 或其他 Profile；
  • 通过 SessionId 隔离不同 Agent 的授权、REPL binding 和浏览器任务。

它控制的不是一个空白自动化浏览器，而是用户正在使用的 Chrome。Agent 可以复用现有登录态，但每次调用仍受 DSH 审批或显式限时授权约束。

功能

  • 真实 Chrome Profile：复用现有登录态、标签页和浏览器环境。
  • 受限 JavaScript REPL：持久保存变量，但不暴露 Node.js、文件系统、进程、网络全局或任意 eval。
  • 观察—操作—验证：支持 snapshot、find、inspect、click、fill、press、scroll、evaluate、screenshot、upload、console 和 network。
  • 用户标签保护：接管用户已有标签页不会移动、分组或关闭它。
  • 任务级标签清理：Agent 创建的普通研究标签页在当前 Turn 结束后自动关闭。
  • 明确交付：markHandoff() 和 markDeliverable() 可以保留需要交给用户的标签页。
  • 通用审批：默认每次 chrome_repl 调用进入 DSH 审批；也可以用 /chrome authorize 建立当前 Session 的限时授权。
  • 多 Session 隔离：同一进程内的多个 Agent 分别持有状态，共享机器级 Bridge 而不共享 REPL binding。
  • 故障恢复：Bridge owner 退出后，其他进程可以接管端口；失败的 Tab finalization 会在后续连接或调用时重试。

快速开始

1. 准备环境

DeepSeek Harness 官方 Web UI 可以直接这样启动：

npx @deepseek-ai/dsh web

2. 构建并安装本地插件

在 dsh-chrome 目录执行：

pnpm install
pnpm run build
npx @deepseek-ai/dsh plugin --profile web add .

dsh-chrome 的 package.json 声明了 dsh.bundle.patch。安装成功后，它会自动加入 web Profile 的 Bundle 层。

然后重新启动 Web UI：

npx @deepseek-ai/dsh web

3. 检查 Chrome 连接

确保 Chrome 正在运行且万卷扩展已启用，然后在 DSH 会话中执行：

/chrome doctor

看到 Chrome is connected 后即可使用。无需手写 chrome_repl：直接用自然语言描述任务，Agent 会在需要时加载 Skill 并调用工具。

打开我 Chrome 里已经登录的后台，检查今天有没有失败任务。

用 Chrome 打开本地页面，检查表单布局并截图。

找到我已经打开的文档页面，把标题改成“周报”，保存后确认结果。

授权模型

默认情况下，每次 chrome_repl 调用都会通过 DSH 通用审批询问用户。这是推荐设置，因为工具操作的是带真实登录态的浏览器。

如果一个任务需要连续调用，可以给当前 Session 一个限时授权：

/chrome authorize 15m

也支持 30m、纯分钟数和 indefinite。撤销授权：

/chrome revoke

显式授权和 background 偏好只保存在当前进程内，不写入 Session Log 或配置文件；重启后需要重新授权。

/chrome 命令

/chrome 只管理 Bridge。真正的浏览器任务应直接用自然语言交给 Agent。

命令 作用
/chrome 显示连接状态和帮助
/chrome authorize [15m|30m|分钟|indefinite] 为当前 Session 建立显式授权
/chrome revoke 撤销授权并清理当前 Agent-owned 浏览器任务
/chrome status 查看连接、授权和 background 状态
/chrome doctor 执行协议、页面脚本和连接诊断
/chrome onboard 返回配套 Chrome 扩展的商店地址
/chrome background on 后台操作，不主动抢占 Chrome 焦点
/chrome background off 操作时将 Chrome 带到前台，便于观察
/chrome background toggle 切换 background 模式
/chrome background status 查看 background 模式

chrome_repl 概览

Agent 首次使用时会初始化持久 binding：

const chrome = await browser.get("chrome")
await chrome.nameSession("🔎 检查管理后台")

使用用户已有标签页：

const openTabs = await chrome.user.openTabs({ urlIncludes: "example.com", limit: 5 })
const tab = await chrome.user.claimTab(openTabs[0])
await tab.snapshot()

创建当前 Turn 独享的标签页：

const tab = await chrome.tabs.open("https://example.com")
await tab.find("登录按钮")
await tab.click({ uid: "el-12", includeSnapshot: true })

外层 chrome_repl 是受限语法环境；完整页面 JavaScript 应放在 tab.evaluate() 中执行。更完整的操作规范位于 control-chrome Skill。

标签页生命周期

dsh-chrome 区分两种标签页：

类型 来源 Turn 结束时
用户标签页 chrome.user.claimTab() 释放控制权；不移动、不分组、不关闭
Agent-created 标签页 chrome.tabs.open/create() 默认关闭

需要保留 Agent-created 标签页时，必须显式标记：

await tab.markHandoff()       // 用户还需要继续操作
await tab.markDeliverable()   // 标签页本身就是交付物

普通搜索、资料阅读和临时验证页面不应保留。

架构

flowchart LR
    A["DeepSeek Harness Agent"] --> T["chrome_repl Tool"]
    S["control-chrome Skill"] --> A
    P["DSH Approval"] --> T
    C["/chrome Commands"] --> R["Per-Session Controller"]
    T --> R
    R --> B["127.0.0.1:17318 Bridge"]
    B --> E["WanJuan Chrome Extension"]
    E --> X["User's signed-in Chrome"]
Loading

代码分为两层：

  • src/kernel/：Bridge、协议握手、Chrome API、格式化和 Restricted REPL，不依赖 DSH UI。
  • src/adapter/：工具、Skill、审批、命令、生命周期和 per-Session Controller。

Bridge 是机器级共享连接：第一个进程监听 127.0.0.1:17318，后续进程以 client 模式转发；Agent 的授权、binding、任务 key、保留标签页和 pending finalization 则按 Session 隔离。

配置

默认 Bundle 配置：

- id: chrome-profile-bridge
  name: dsh-chrome
  config:
    host: 127.0.0.1
    port: 17318

可以在 Profile 的 cordis.patch.yml 中覆盖该行。DSH Patch 会整体替换 config，因此覆盖时请同时保留 host 和 port。

配套商店扩展固定访问 127.0.0.1:17318。除非同时维护并重新构建 Chrome 扩展，否则不要修改端口，也不要把 Bridge 绑定到非 loopback 地址。

安全边界

  • chrome_repl 能操作真实登录态，首次使用应保留 DSH 审批。
  • Restricted REPL 限制的是模型可执行语法，不是浏览器权限沙箱；tab.evaluate() 仍在目标页面内执行 JavaScript。
  • Bridge 只应监听 loopback。它信任本机进程转发，不能作为跨机器或不受信任多用户服务暴露。
  • 用户已有标签页的破坏性 close/group/ungroup 操作会被拒绝。
  • 不应读取 Cookie、密码、Profile 文件或与任务无关的标签页。
  • 写入、提交、上传等副作用操作失败后必须先检查实际页面状态，不能盲目重试。
  • 截图默认写入当前工作区的 .dsh/chrome-screenshots/。

开发与验证

pnpm run test
pnpm run typecheck
pnpm run build

连接真实 Chrome 的端到端验证：

node scripts/e2e-verify.mjs

该脚本需要已连接的配套扩展，会打开一个临时百度标签页，验证导航、页面执行、snapshot 和 Turn finalization，最后自动清理 Agent-created 标签页。

测试重点覆盖：Bridge 长轮询与多进程共享、握手兼容性、配置校验、受限 REPL、Chrome API、审批组合、多 Session 隔离、Turn 清理、finalization 重试，以及插件装载/卸载。

当前限制

  • 没有独立 Web 设置页；连接诊断、授权和 background 设置通过 /chrome 完成。
  • 授权和 background 偏好是当前 Session 的进程内状态，重启后不恢复。
  • 当前仅兼容固定 ID 和协议的万卷 Chrome 商店扩展。
  • Chrome 原生对话框、系统级文件选择器和部分 chrome:// 页面仍需要用户处理。
  • DeepSeek Harness 处于开发者预览阶段；升级 DSH 后应重新运行插件组合测试。

DeepSeek Harness 生态

如果把本项目发布到 GitHub，建议为仓库添加 dsh-plugin、deepseek-harness、chrome-extension、browser-automation 和 agent-tools Topics，方便 DeepSeek Harness 用户发现。

License

MIT

About

Chrome profile bridge for DeepSeek Harness: control an existing signed-in Chrome profile through chrome_repl.

Topics

dsh-plugin

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages