前言¶
在 DeepSeek Harness（DSH）里做智能体或工作流时，经常需要读网页：查文档、跟链接、把页面内容交给模型。常见做法是直接 HTTP 抓 HTML，或在本机装浏览器自动化。前者不执行 JavaScript，动态页往往拿到的是壳；后者能渲染，但「等加载完」有多种含义，选错会把加载动画当正文。更麻烦的是静默退回：浏览器失败后悄悄用静态抓取，调用方会以为拿到的是渲染后的内容。
下面介绍社区插件 dsh-tool-browser（维护者 yuehancn，GitHub：yuehancn/dsh-tool-browser）。它在 DSH 里提供四个浏览器相关工具：先说明当前有没有真浏览器，再取 HTML、抽可读正文或截 PNG；装了 Playwright 用真浏览器，没装则退回静态抓取，并在返回里用 engine 和 engineNote 明确说明，避免把「JavaScript 从没跑过」的页面当成空页或完整页。
这是什么¶
dsh-tool-browser 是面向 DeepSeek Harness 的浏览器工具插件，npm 包名 @yuehancn/dsh-tool-browser，当前版本 1.0.0，MIT 许可证。在 SkillHub 目录中归类为「模型推理」，简介为 DeepSeek Harness plugin。
插件解决的是「打开页面 → 按页面真正需要的方式等待 → 抽出正文 → 必要时截图」这一整条链路，而不是只提供一个裸 fetch。
四个工具¶
README 中列出的能力如下：
| 工具 | 作用 |
|---|---|
browser_status |
说明是否有真浏览器、默认引擎、四种等待策略、输出目录与默认值；不发起请求、不启动浏览器 |
browser_fetch |
获取页面 HTML，可选存盘 |
browser_extract |
只取可读正文，纯文本或 Markdown |
browser_screenshot |
用真浏览器截 PNG；无 Playwright 时明确报错，不提供静态兜底 |
Playwright 为可选依赖。未安装时，browser_fetch 与 browser_extract 仍可用（静态引擎）；browser_screenshot 会失败而不是返回无渲染意义的空图。
每次调用都会在结果里带上 engine 与 engineNote，例如浏览器超时退回静态时，会说明下方内容是「未执行 JavaScript 时服务器返回的内容」。
等待策略与正文抽取¶
四种「等加载完」¶
插件支持四种等待策略，含义不同：
| 策略 | 等的是什么 |
|---|---|
domcontentloaded |
DOM 树建好 |
load |
所有资源（图片、样式等）到齐 |
networkidle |
网络安静（500ms 无请求） |
selector |
某一 CSS 元素出现 |
使用 selector 时，导航会用 domcontentloaded，再用 waitForSelector 等待目标元素，避免与 networkidle 组合时在带轮询请求的页面上永远等不到「网络安静」。
正文怎么选¶
抽取器不按「谁文字最多」选节点（那样几乎总是 <body>），而是对候选子树按正文密度打分：正文比例（非链接文字）、分段程度、标点密度等。打分前会先去掉 <nav>、<footer>、<aside>、<script>、<style> 等；类名匹配支持常见复数形式（如 comments）。浏览器引擎与静态引擎对同一份文档应抽出相同正文，README 中测试对此有专门断言。
HTML 转 Markdown 时处理了反引号围栏宽度、代码与强调的嵌套顺序、链接内强调保留、空链接写成 [](url) 等细节。
安装与配置¶
安装插件（命令来自 README）：
dsh plugin add dsh-tool-browser
需要真浏览器时，再安装 Playwright：
npm install playwright
npx playwright install chromium
建议先调用 browser_status 确认当前环境。可在 cordis.patch.yml 中配置插件，例如：
# cordis.patch.yml
plugins:
dsh-tool-browser:
workDir: "."
outputDir: "browser-output"
waitStrategy: domcontentloaded
插件要求 DSH >=0.2.0-rc.2，peer 依赖 @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools。
典型用法¶
先看状态¶
调用 browser_status，确认 Playwright 是否可用、默认等待策略与 outputDir，再决定用 mode=auto 还是强制 browser / static。
取 HTML：browser_fetch¶
| 参数 | 说明 |
|---|---|
url |
必填，绝对 http(s) URL |
mode |
auto（默认，浏览器优先、失败可退回）/ browser（必须真浏览器）/ static（仅静态） |
waitStrategy |
四种策略之一 |
waitForSelector |
CSS 选择器，隐含 waitStrategy=selector |
saveAs |
存到 outputDir 下的文件名 |
maxChars |
返回 HTML 截断长度 |
mode 是承诺而非偏好：browser 模式下没有真浏览器会报错，不会静默退回。配置项 requireBrowser 可让 auto 也不允许退回。若指定 saveAs，磁盘写入的是完整页面，即使返回体被 maxChars 截断。
只要正文：browser_extract¶
| 参数 | 说明 |
|---|---|
url |
必填 |
format |
text（默认）或 markdown |
keepLinks |
Markdown 是否保留链接语法，默认 true |
includeLinks |
是否附带整页链接表，默认 false |
maxChars |
正文截断长度 |
返回中包含 selector（选中的子树）与 score（密度得分），便于诊断抽取结果是否异常。
截图：browser_screenshot¶
| 参数 | 说明 |
|---|---|
url |
必填 |
filename |
存到 outputDir，默认带时间戳 |
fullPage |
整页或视口，默认 false |
width / height |
视口尺寸 |
文件名只取最后一段路径，防止通过绝对路径或 ../ 写到 outputDir 之外。
适用场景与注意¶
适合谁： 需要在 DSH 智能体或脚本里稳定读网页、抽文章正文、在具备 Playwright 的环境里截图的开发者；希望区分「静态 HTML」与「浏览器渲染结果」的场景。
权限与安全： 插件以当前 DSH 进程的权限运行，会访问你传入的 URL 并可能写入 outputDir。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认来源与行为符合你的环境策略。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，DSH 生态理念是「一切皆插件」，目录为独立社区站点。
依赖： 不装 Playwright 仍可使用 fetch 与 extract；动态渲染、截图依赖 Playwright。网络超时或浏览器失败时，请关注返回中的 engine / engineNote，不要假设一定是渲染后的 DOM。
结尾¶
dsh-tool-browser 把「状态说明、抓取、正文抽取、截图」拆成四个工具，并在引擎切换时写清楚；等待策略与密度抽取针对真实网页里的常见坑做了显式处理。若你在 DSH 里需要可核对来源的网页能力，可从目录页或 GitHub 安装并按 README 配置 Playwright 与 cordis.patch.yml。
