前言¶

在 DeepSeek Harness（DSH）的工作流中，智能体负责编写代码并声称任务完成。常见的问题是，智能体往往只依据源代码读取来判定工作结束，却不会主动打开浏览器验证实际渲染效果。这导致前端可能存在报错、布局异常或交互失效，最终需要人工介入。

简介¶

dsh-preview 是一个工作流插件，由 Viger1 维护。它为 DSH 智能体提供了一双“眼睛”：一套无头浏览器验证工具和一个捆绑的 frontend-verify 技能。

与单纯的浏览器工具不同，它的核心价值在于流程。它强制智能体执行一个闭环验证流程，在智能体宣称工作完成前，先完成打开页面、检查控制台、读取布局、交互测试、截图记录和修复错误的动作。

核心功能¶

插件提供 6 个浏览器工具和 1 个自检技能。

浏览器工具¶

• browser_open：打开 http(s) URL 或本地文件/目录（自动通过 127.0.0.1 服务）。返回页面 ID 及加载时的控制台错误。
• browser_console：捕获自页面加载后的控制台消息和失败的网络请求。
• browser_read：确定性无视觉读取。读取文本、HTML 或特定选择器的样式（包含边界框和关键计算样式）。
• browser_interact：对选择器执行点击、输入、按键或滚动操作，并报告交互引起的错误。
• browser_screenshot：保存视口、全页面或单元素 PNG 到工作区。
• browser_close：在验证完成后关闭页面。

frontend-verify 技能¶

这是一个自动化验证循环，将上述工具串联起来：
1. 打开页面
2. 检查控制台
3. 读取布局事实
4. 执行交互
5. 截图记录
6. 修复问题
7. 重新验证

该技能会如实报告验证通过的内容，以及明确指出无法验证的部分（例如 GPU 渲染精度或指针锁定手感），而不是笼统地声称完成。

安装¶

在终端执行以下命令即可安装：

dsh plugin --profile web add dsh-preview

配置¶

插件配置位于 profile 的 cordis.patch.yml 中。以下是默认配置示例：

- id: preview
  name: dsh-preview
  config:
    headless: true
    browserChannels: [chrome, msedge, chromium]
    viewportWidth: 1280
    viewportHeight: 800
    navigationTimeoutMs: 15000
    actionTimeoutMs: 5000
    screenshotDir: .dsh-preview
    maxReadChars: 20000
    maxConsoleMessages: 100
    allowedHosts: []          # 允许访问的额外主机名
    registerSkill: true       # 启用内置的 frontend-verify 技能

安全模型规定：
* localhost / 127.0.0.1 / ::1 永远被允许。
* 其他主机默认拒绝，需在 allowedHosts 中显式授权。
* 本地路径以只读方式在临时 127.0.0.1 端口提供服务。

注意事项¶

1. 运行环境：需要安装 Node.js，版本要求为 ^22.19 || >=24。
2. 浏览器支持：插件使用 Playwright，支持你机器上的任意 Chromium（Chrome 和 Edge 会自动检测，否则需运行 npx playwright install chromium 并配置 browserChannels）。
3. 渲染差异：无头渲染与真实桌面浏览器存在差异。指针锁定、部分 GPU 代码路径和 OS 对话框的行为可能不同。内置技能会提示智能体注意这些差异。
4. 视觉能力：目前没有视觉描述能力。机器验证通过 browser_read 和 browser_console 进行，截图仅用于人类查看。
5. 进程模型：每个 dsh 进程共享一个浏览器进程。页面是轻量的，但并行运行的智能体会共享该进程。

总结¶

dsh-preview 将“验证”从人工任务转化为智能体的内置能力。它不提供额外的“超能力”，而是建立了一套严谨的验证纪律，让智能体在完成代码构建后，能自主完成前端验收闭环。