dsh-browser-harness

简体中文 | English

DeepSeek Harness（DSH）原生浏览器工具。 零依赖 CDP 内核 + 13 个 browser_* 工具，直连专用、已登录的 Chromium 内核浏览器，提供 e1/e2 引用快照，并按任务给自建标签页分组。

工具

browser_status      端点 / 浏览器版本 / 标签页 / 当前标签页
browser_wait        出现/消失、URL/文本变化、response、network_idle、delay
browser_navigate    打开 URL，或 back / forward / reload
browser_snapshot    紧凑引用（e1…）；frameId、offset/limit 完整分页、checked/selected/expanded
browser_act         click / hover / highlight / drag / type / fill / selectOption / check / uncheck / press / scroll / dialog；可选 expectUrl/expectText/expectSelector 断言
browser_extract     text / html / JS / network / console / frames
browser_screenshot  整页或元素级 PNG 路径
browser_pdf         页面 PDF 路径
browser_diagnose    截图 + console + 网络失败 + 活动请求诊断包
browser_upload      文件输入上传，路径限制在 uploadDir
browser_download    触发并等待下载，文件落在 downloadDir
browser_task        status / pause / resume / close / start，任务生命周期
browser_tabs        list / use / new / close

亮点

• 运行时零依赖 + 全量 TypeScript：构建产物只用 Node 内置的 fetch / WebSocket，不下载浏览器；源码、测试、脚本、扩展全部是 TypeScript，分别由 tsc 编译到 dist/、dist-tests/、dist-scripts/、extension/sw.js；插件入口仅用宿主提供的 @deepseek-ai/dsh-tools peer。
• 真实登录态：接自己起好的专用 Chromium 实例，登录一次长期有效；不碰日常浏览器。
• 文本优先：无障碍树 + ref 比“截图喂视觉模型”更准更省，截图只是补充。
• 按任务标签组：插件自建的标签页自动按 DSH 会话分组，工作标签页不受影响；headless 自动跳过。
• 操作可靠性：快照按页串行、attach 并发去重；click 默认做遮挡/命中检查（E_CLICK_INTERCEPTED）；load 等 complete；首次导航前开启网络抓取；网络空闲基于活动请求集合与最后活动时间。
• 自动失败诊断：页面工具失败时自动写入 <stateDir>/diagnostics/<lane>/，含脱敏 URL、截图、console/network 尾部、task/lock/context 摘要；错误信息附诊断路径，不记录输入值。
• 只读模式：readOnly: true 时工具层阻止 click/fill/type、JS、上传/下载、tabs new/close 和 task 变更；导航/快照/提取/截图仍可用于检查页面。
• 任务生命周期与标签页锁：每个 DSH session 是一个 Task；页面操作持有 target 独占 lease，跨任务冲突返回 E_TAB_LOCKED/E_LOCK_TIMEOUT；支持 browser_task 的 status/pause/resume/close。v1.8 起 lease 默认写入 <stateDir>/locks，跨 manager 进程通过文件租约/心跳互斥；可选 isolation: "context" 为每个任务隔离 cookie/storage（不共享登录态）。
• 可验证：202 单测（fake CDP）+ 64 集成场景（真实 headless/headful Chromium）= 266 条，CI 覆盖三平台。
• 收紧的边界：browser_tabs use 只接受 page + http(s)/about:blank；非自建 tab 需显式 {borrow:true}，其他 Task 自建 tab 返回 E_TAB_OWNER_CONFLICT；截图/PDF 限定 screenshotDir 且不覆盖；上传限定 uploadDir、下载限定 downloadDir 并拒绝 symlink 逃逸；fill 不回显输入值；JS 模式标非并发；工具输出对 token 类 URL/headers 尽力脱敏；宽泛端口回退改为显式 auto；标签组不再临时改写页面标题。

环境要求

要求	说明
DSH	>=0.2.1-rc.5（不设上限）
Node	>=22
浏览器	任一 Chromium 内核 + remote debugging（默认 9331，见 配置）
平台	Windows / Linux 已验证；macOS 单测 CI 通过，真实 Chromium 端到端未实测

安装

插件发布于 GitHub Packages：@xumi0920/dsh-browser-harness（npmjs 同名包是别人的项目）。三种方式任选，详见 docs/install.md：

1. 插件页（推荐）：DSH Web → 插件页 → 添加插件 → 安装第三方插件，支持 npm 包名 / Git 仓库 / 本地目录；或在「发现」标签页安装市场条目。
2. 一句话交给 DSH（创造模式会话）：把 @xumi0920/dsh-browser-harness 安装到当前 profile。
3. 手动安装（GitHub Packages，classic PAT）：

npm config set "@xumi0920:registry" "https://npm.pkg.github.com"
npm config set "//npm.pkg.github.com/:_authToken" "<YOUR_GITHUB_TOKEN>"
& "$env:LOCALAPPDATA\\Programs\\DeepSeek Harness\\resources\\runtime\\cli\\bin\\dsh.cmd" `
  plugin --profile desktop add "@xumi0920/dsh-browser-harness"

GitHub Packages npm registry 只支持 classic PAT（scope read:packages），不支持 fine-grained token。手动 npm config set 会把 token 持久化到 ~/.npmrc：建议优先用一键脚本（临时配置，装完即删）；手动安装后请执行 npm config delete "//npm.pkg.github.com/:_authToken" 并撤销该 token。本地目录安装前先 npm install && npm run build；CLI 改 profile 前先退出 DSH。热插拔：application: applied 已生效，restart-required 才需重启（替换已安装包通常需要重启加载新的 JS 模块，原因见返回的 restartReason）。

快速开始

安装生效后，先启动专用 Chromium 浏览器（默认 9331），然后在任意 DSH 会话里让模型调用（所有预设可用，创造模式只影响 plugin_manager 安装）：

browser_status → browser_navigate {url} → browser_snapshot → browser_act {action:"click", ref}
browser_extract {mode:"text" | "html" | "js" | "network" | "console" | "frames"}

首调 connected:false？确认专用浏览器已启动且 http://127.0.0.1:9331/json/version 可访问（见 docs/configuration.md）。

适用场景

场景	建议
登录态页面、点击/填表、上传下载、多标签、截图	用本插件
公开页面纯读取	优先 web_fetch（更快，不占浏览器）
headless 环境	标签组自动跳过；其它工具正常
日常浏览器	不要指向它；使用专用 profile 实例

文档

文档	内容
安装与验证	插件页 / 一句话 / GitHub Packages / 本地 / Linux / 卸载 / 升级 / FAQ
配置	浏览器发现、端口约定、registry、profile patch 配置键
按任务标签组	行为边界、配置、排查、实现方式
使用	DSH 工作流、独立库、CLI
架构	分层、关键流程、错误模型、安全边界
扩展与语言	原生 JS/TS 插件、热插拔/HMR、MCP 接 Python 等
仓库结构	目录约定、维护与发布流程
安全策略	漏洞私密报告、支持版本、数据处理说明

扩展与语言

• 原生插件：Node 22+ ESM 包（JS/TS，TS 需构建），bundle patch 注册，HMR 协调热插拔。
• 其它语言：写 MCP server（stdio / Streamable HTTP，Python / Go / Rust / Node 均可），profile 里加 @deepseek-ai/dsh-mcp-client，工具以 mcp__<serverName>__<tool> 暴露。
• 技能：Markdown（SKILL.md）；UI 插件：JS/TS。细节见 docs/extending.md。

测试与 CI

npm install                 # 开发依赖（TypeScript），运行时零依赖
npm run test:all            # 构建 + 202 单测 + 64 集成场景 = 266 条

CI：单测跑 ubuntu / windows / macOS（另有 Node 24 任务）；集成场景跑 ubuntu + xvfb（门禁 64 条，S15/S16 必须实跑）。测试与脚本同样由 tsc 编译（dist-tests/ / dist-scripts/），与运行时源码共用 NodeNext 配置。

安全边界

• 只关闭本 harness 创建的标签页；force 关闭需要用户明确同意。
• browser_tabs use 只接受 page target + http(s)/about:blank；非自建页必须精确 targetId，URL 子串只匹配自建页；file:/chrome:/扩展 worker 会被拒绝。
• 截图只写 screenshotDir（默认 <stateDir>/screenshots），拒绝目录外路径、symlink 逃逸和覆盖已有文件。
• browser_act fill 只返回 {ok, length, verified}，不回显输入；JS 模式可修改页面状态，已标非并发。
• Cookie 默认脱敏；network URL/headers、status/tabs URL 对 token 类字段尽力脱敏：查询参数名按驼峰/下划线/连字符归一化匹配，Location / Content-Location 整值脱敏。页面正文、HTML、截图仍可能含敏感数据，不要把工具输出当完整 DLP。
• browser_status 的端点诊断不返回完整 CDP URL；连接错误只保留稳定错误码和安全提示。
• 状态文件只保存去掉 query/fragment 与 userinfo 的 URL；宽泛 CDP 端口回退需显式 browser: "auto" / BH_ALLOW_FALLBACK=1。
• 不要把 cdpUrl 指向日常浏览器；全部后台操作，不抢前台；遇到登录墙停手问人。

许可

MIT © 2026 Xumi0920 · 当前版本 v1.10.0 · 全量 TypeScript（源码/测试/脚本/扩展）· 更新日志见 Releases