一句话定位

dsh-reef 是 DeepSeek Harness 的五合一插件包：装一次同时获得浏览器自动化、MCP Server、GitHub 与 GitLab 只读+自动评审、以及一个原生嵌入面板，让 agent 能"开网页、操作表单、看画面、跑评审、被外部 MCP 客户端反向调用"。

核心能力

• 提供 21 个共享浏览器工具（browser_open、browser_click、browser_type、browser_screenshot、browser_form、browser_profile 等），agent 可在 headless 浏览器里打开页面、点按钮、填表、抓文本、截图，多标签 + 多 profile 隔离登录态
• 把 DSH 反向暴露为 MCP Server（Streamable HTTP，路径 /reef/mcp），让 Claude Desktop、Cursor、Cline 等客户端调用 dsh_list_sessions / dsh_run_agent 等 5 个工具来操作本地 agent
• 提供 GitHub 4 个只读工具（仓库元信息、issue 列表、PR 列表、PR 详情）+ webhook 自动 PR 评审 + issue 自动修复闭环（agent 自动建分支修复并开 PR）
• 提供 GitLab 3 个只读工具（项目信息、issue 列表、MR 列表）+ webhook 自动 MR 评审（结果以 note 形式发布到 MR）
• 在 DSH Web 界面右下角注入原生浮动面板：实时显示三模块状态、浏览器缩略图（点开大屏实时画面 + 访问历史）、GitHub 事件看板、五模块统一设置区（凭据、浏览器通道、截图清理、评审模型等即时生效）

技术实现

• 语言: TypeScript（ESM）
• 关键依赖: playwright-core（浏览器自动化，运行时唯一第三方依赖）；@deepseek-ai/cordis（仅 devDependencies,作为编译期类型参考）
• 架构模式: Cordis bundle 插件,通过 cordis.patch.yml 在宿主页面上 insert 五个独立插件行(reef-browser / reef-mcp / reef-github / reef-gitlab / reef-console),每行 inject 自己需要的服务(tools / webServer);模块通过 ctx.get("tools").register 注册工具,通过 ctx.get("webServer").register 注册 HTTP 路由,通过 ctx.get("webServer").tapIndex 注入浏览器端脚本
• 入口文件: src/browser/index.ts(reef-browser) / src/mcp/index.ts(reef-mcp) / src/github/index.ts(reef-github) / src/gitlab/index.ts(reef-gitlab) / src/console.ts(reef-console);src/index.ts 仅作包元信息

适用场景

希望 agent 能"看见并操作真实网页"的场景：自动登录后台抓数据、跑回归测试截图比对、批量填表、爬取登录后内容；同时需要把本地 DSH 暴露给其他 MCP 客户端,做"DSH 当主控、Claude Desktop 当前端"的双端协作;有 GitHub/GitLab 仓库的开发者,想要 PR/MR 打开时自动评审、新 issue 自动派给 agent 修复。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:huey1in/reef

配置项

上述配置可三处覆盖:插件内置默认(cordis.patch.yml)→ 用户 profile 的 cordis.patch.yml(启动时覆盖)→ 面板 ⚙ 设置区(运行时即时生效,仅标 ⟳ 的路径类需重启)。

常见问题

Q: 安装后必须重启 DSH 才能生效吗?

A: 是的,cordis.patch.yml 中注册的五个插件行(reef-browser/reef-mcp/reef-github/reef-gitlab/reef-console)需要重启 DSH 才会加载;面板 ⚙ 设置区的改动无需重启即可热生效(仅标 ⟳ 的路径类字段除外)。

Q: 浏览器工具是否需要下载 Chromium?

A: 默认不需要。配置项 channel='auto' 时会按平台优先探测系统已装的 Edge/Chrome/Chromium(Windows 顺序 msedge→chrome→chromium,macOS/Linux 顺序 chrome→msedge→chromium),都不存在才用 playwright 自带 Chromium 或提示 npx playwright install chromium。

Q: GitHub 只读工具需要 token 吗?

A: 公共仓库可选:未配置 GITHUB_TOKEN 时走匿名访问(每 IP 60 次/小时),命中限流会返回 403 并附带提示;配置后无此限制且可访问私有仓库。写操作(建 issue/PR、评论、合并)一律需要 token,由 agent 用 bash 调 gh CLI 完成。

Q: MCP Server 怎么鉴权?支持 OAuth 吗?

A: 三种方式可叠加或单独使用:面板 ⚙ → MCP 直接填静态 Bearer token(写入凭据库或插件自有 tokens.json);通过 authTokenEnv 指定环境变量;启用 oauthEnabled=true 并配置 MCP_CLIENT_ID/MCP_CLIENT_SECRET 后走 OAuth 2.0 client_credentials。

Q: GitHub webhook 自动评审会重复评同一个 PR 吗?

A: 默认不会。reviewDedupe=true 时同一 PR 同一 head commit 只评一次(src/github/review.ts:51 用 headSha 做 key 缓存);评审模型可在面板设置 reviewModelProvider/reviewModelModel,空则用 DSH 默认模型。

Q: 不想用某个模块怎么办?

A: 在 $DSH_HOME/profiles/web/cordis.patch.yml 中删除对应行,或者保留行但在 config 下加 enabled: false 即可关闭,重启生效。

上手难度

进阶 — 配置面广(五模块共 30+ 配置项)、依赖外部 token(可选)、对宿主页面 CSS 变量(--dsw-alias-*)有耦合,但默认开箱可用,基础安装无需任何额外配置。

已知问题与限制

• Windows PowerShell 中文编码坑:用 Invoke-RestMethod / Invoke-WebRequest 发含中文的 JSON body 会按 ISO-8859-1 编码变乱码,必须用 [System.Text.Encoding]::UTF8.GetBytes() 传字节流,或改用 gh / glab CLI;发布中文内容后必须回读一次校验(src/github/index.ts:132、src/gitlab/index.ts:107、README.md:130-133)
• GitHub 自动修复 agent 不能强制中止:源码注释承认 AbortSignal 无法直接中断 agent,autoFixTimeoutMs 超时后只能记录日志继续等待清理,实际等待时长可能超过配置(src/github/autofix.ts:74-76)
• MCP Server 无状态实现:客户端 DELETE 断开会话时,服务端直接返回 200,不维护 session 映射;同时连接复用依赖 MCP 客户端自身实现(src/mcp/index.ts:98-103)
• OAuth token 内存存储:src/mcp/oauth.ts:8 中 oauthTokens 是 Map,DSH 重启后所有未过期 token 全部失效,客户端需重新获取
• 匿名 GitHub 速率限制:未配置 GITHUB_TOKEN 时公共仓库匿名访问 60 次/小时,触发限流后 403 错误信息附带提示,需配置 token 提升(CHANGELOG.md:80-81)

dsh-reef

DeepSeek Harness 全家桶:浏览器自动化 · MCP Server · GitHub/GitLab 集成 · 原生嵌入面板

---

dsh-reef 是一个 DSH 插件 bundle,一次安装提供五个模块:

设计原则:能做的一次性操作交给 agent 用 bash 完成(如 GitHub 写操作配 gh CLI),插件只做 bash 做不到的常驻自动化与集成。唯一第三方运行时依赖是 playwright-core(复用系统已装的 Edge/Chrome,无需下载 Chromium),不依赖任何 @deepseek-ai 运行时包。

---

安装

dsh plugin --profile web add dsh-reef

重启 DSH 生效。不需要某个模块?在 $DSH_HOME/profiles/web/cordis.patch.yml 里删掉对应行 (reef-browser / reef-mcp / reef-github / reef-gitlab / reef-console)或给对应行加 config: { enabled: false }。

---

🐋 原生嵌入面板

安装后自动注入 DSH 界面(基于官方 --dsw-alias-* 设计变量,自适应亮/暗主题,零 DOM 依赖):

• 悬浮按钮:右下角圆形按钮显示鲸鱼图标——透明底标志,跟随 DSH 主题自动切换 (暗色主题 → 白色鲸鱼,亮色主题 → 墨黑鲸鱼);
• 状态行:浏览器(开关/标签数/当前 URL)、MCP(在线状态)、GitHub(webhook 在线 + 事件数);
• 实时画面:浏览器打开时显示缩略图,点击弹出大屏模态框——2 秒轮询实时画面, 下方列出访问历史(最近 50 条,按 profile 隔离,点击可在新标签打开);
• GitHub 事件看板:最近 3 条 webhook 事件(时间/事件/仓库/编号/处理结果);
• ⚙ 设置区:五个模块的配置都可在面板里修改,详见 配置。

---

🧭 浏览器自动化

给 agent 一个共享浏览器会话(多标签页,默认 headless,channel: auto 自动探测 msedge → chrome → chromium,也可 executablePath 指定):

截图自动清理:browser_screenshot 保存的 .png 自动修剪——每次截图后即时清理 + 每小时定时清扫;默认保留最近 7 天、最多 200 张(screenshotMaxAgeDays / screenshotMaxCount,设为 0 关闭对应规则),只清理截图目录直属文件。

首次调用浏览器工具时自动启动浏览器;启动失败会提示安装 Chromium (npx playwright install chromium)或配置 executablePath。

---

🔌 MCP Server

把 DSH 变成一台 MCP 服务器。任何支持 Streamable HTTP 的 MCP 客户端都能接:

{
  "mcpServers": {
    "dsh": { "url": "http://127.0.0.1:3080/reef/mcp" }
  }
}

5 个工具:dsh_list_sessions(列出本机会话)、dsh_read_session(读事件摘要)、 dsh_search_sessions(全文搜索)、dsh_run_agent(用默认模型跑一次性 agent, 长任务流式输出 + 进度通知)、dsh_agents_status(当前运行中的 agent)。

鉴权(三选一或并存):

• 静态 Bearer token:面板 ⚙ → MCP 模块直接填 token,保存即时生效;客户端请求带 Authorization: Bearer <token>;
• 环境变量引用:authTokenEnv 指向环境变量名;
• OAuth 2.0 client_credentials:oauthEnabled: true + MCP_CLIENT_ID / MCP_CLIENT_SECRET,token 端点 /reef/mcp/oauth/token,RFC 8414 发现端点 /.well-known/oauth-authorization-server。

---

🐙 GitHub 集成

只读工具 × 4(公共仓库无需 token,匿名 60 次/小时;配置 GITHUB_TOKEN 后 无此限制且可访问私有仓库):

写操作让 agent 用 bash 跑 gh CLI(优先,UTF-8 安全)或 curl + GITHUB_TOKEN 完成,与工具层功能等价且更灵活。注意:Windows PowerShell 发 中文 JSON body 必须用 [System.Text.Encoding]::UTF8.GetBytes() 传字节流, 否则会按 ISO-8859-1 编码变乱码;发布后回读校验。

Webhook 自动 PR 评审:仓库 Settings → Webhooks 添加 http://<机器>:3080/reef/github/webhook(Content type: application/json, Secret 与 GITHUB_WEBHOOK_SECRET 一致,事件勾选 Pull requests)。PR 打开/更新时 自动拉取 diff → 调用评审模型 → 以 COMMENT 评审提交。同一 PR 同一 head commit 只评审一次(reviewDedupe,默认开启)。评审模型默认用 DSH 默认模型,可在面板 设置区指定 provider/model。

Issue 自动修复闭环:配置 autoFixRepos(仓库 → 本地路径映射)后,新 issue 自动触发一个 DSH agent 在本地仓库修复:fetch → 建 fix/issue-N 分支 → 修复 + 测试 → push → 自动开 PR。autoFixLabels 可限定只处理带特定标签的 issue。

事件看板:面板 GitHub 行实时显示最近 webhook 事件,数据端点 GET /reef/github/events。

---

🦊 GitLab 集成

只读工具 × 3(需要 GITLAB_TOKEN):

写操作(建 issue/MR、评论)用 bash 跑 glab CLI 或 curl + GITLAB_TOKEN。

Webhook 自动 MR 评审:仓库 Settings → Webhooks 添加 http://<机器>:3080/reef/gitlab/webhook(Secret Token 与 GITLAB_WEBHOOK_SECRET 一致,事件勾选 Merge Request)。MR 打开/更新时自动评审并以 note 发布(带 🤖 前缀)。 自建 GitLab 实例:改 apiBase(如 https://gitlab.example.com/api/v4)。

---

⚙ 配置

三个层级:插件内置默认(cordis.patch.yml)→ 面板设置区(运行时)→ 用户 profile 的 cordis.patch.yml(启动时覆盖)。

1. 面板设置区(推荐日常使用)

DSH 界面右下角 ⚙,五个模块的配置全在面板里:

• 凭据类(GitHub/GitLab token、webhook 密钥、MCP 访问 token):优先写入 DSH 凭据库($DSH_HOME/.credentials.yaml,0600),部署未挂载凭据服务时回退到插件 自有存储($DSH_HOME/.dsh-reef/tokens.json,0600)。凭据值永不回传页面; 环境变量已提供时输入框自动禁用(环境变量优先级更高)。
• 普通配置(headless、浏览器通道、截图目录/保留策略、操作超时、评审模型、 自动评审事件等):写入 $DSH_HOME/.dsh-reef/settings.json(0600,字段白名单 校验),使用时点读取即时生效;输入框留空 = 恢复默认。
• 路径类(标 ⟳):liveViewPath、webhookPath、MCP path、面板基路径——路由 注册时生效,改动需重启 DSH。
• 每个模块标题栏右侧有保存按钮:有未保存改动时变绿高亮,保存后熄灭。

2. cordis.patch.yml(启动配置)

# $DSH_HOME/profiles/web/cordis.patch.yml
- insert:
    - id: reef-browser
      name: dsh-reef/browser
      config:
        channel: auto        # auto | msedge | chrome | chromium | ""(playwright 默认)
        executablePath: ""   # 显式指定浏览器可执行文件(优先于 channel)
        headless: true
        userDataDir: ""      # 设置后登录态跨 DSH 重启保留
        screenshotDir: .dsh-reef/screenshots
        screenshotMaxAgeDays: 7   # 截图保留天数(0 = 不按时间清理)
        screenshotMaxCount: 200   # 截图保留数量上限(0 = 不按数量清理)
        downloadDir: .dsh-reef/downloads
        liveViewPath: /reef/browser
        maxTextChars: 20000
        maxLinks: 50
        timeoutMs: 30000

    - id: reef-mcp
      name: dsh-reef/mcp
      config:
        path: /reef/mcp
        authTokenEnv: ""            # 静态 Bearer token 环境变量名
        oauthEnabled: false
        oauthClientIdEnv: MCP_CLIENT_ID
        oauthClientSecretEnv: MCP_CLIENT_SECRET
        runAgentTimeoutMs: 300000
        runAgentMaxOutputChars: 120000
        listSessionsLimit: 50

    - id: reef-github
      name: dsh-reef/github
      config:
        tokenEnv: GITHUB_TOKEN
        apiBase: https://api.github.com
        webhookPath: /reef/github/webhook
        webhookSecretEnv: GITHUB_WEBHOOK_SECRET
        reviewModel: {}             # { provider, model },空则用默认模型
        reviewMaxDiffChars: 60000
        autoReviewEvents: [opened, synchronize, reopened]
        reviewDedupe: true          # 同一 PR 同一 head sha 只评审一次
        autoFixRepos: {}            # 例: { "owner/repo": "C:/path/to/repo" }
        autoFixLabels: []           # 非空时只处理带这些标签之一的 issue
        autoFixTimeoutMs: 600000

    - id: reef-console
      name: dsh-reef/console
      config:
        path: /reef                 # 面板/embed 基路径

    - id: reef-gitlab
      name: dsh-reef/gitlab
      config:
        tokenEnv: GITLAB_TOKEN
        apiBase: https://gitlab.com/api/v4
        webhookPath: /reef/gitlab/webhook
        webhookSecretEnv: GITLAB_WEBHOOK_SECRET
        reviewModel: {}
        reviewMaxDiffChars: 60000
        autoReviewEvents: [open, update, reopen]

---

目录结构

src/
├── index.ts            # bundle 入口
├── console.ts          # 原生面板:embed.js 注入、状态探测、设置区、大屏模态框
├── browser/            # Playwright 共享会话:工具注册/实现、多 profile、实时画面 API、截图清理
├── mcp/                # Streamable HTTP 服务器:协议分发、会话投影、run_agent、OAuth
├── github/             # 只读工具、webhook 评审、issue 自动修复、事件看板、设置字段
├── gitlab/             # 只读工具、webhook MR 评审、设置字段
└── lib/                # 共享:配置校验、HTTP 助手、LLM 调用、凭据/设置存储
assets/icons/           # 面板图标(128px 透明标志 + 1024px 原图)

---

开发

npm install          # 安装开发依赖
npm test             # 单元测试(vitest)
npm run verify       # typecheck + test + build
node test/browser-launch.mjs   # 验证本机浏览器通道可启动

本地热加载调试(无需安装到 profile):

dsh --profile web --patch ./e2e.patch.yml --port 3111

---

License

MIT