dsh-preview

English | 中文

给你的 DeepSeek Harness agent 装上眼睛——它写的页面，它自己打开、自己看、自己修。

dsh agent 能写出一整个 Web 应用，却从没"见过"它：改完 CSS 无法确认效果，"验证"页面靠重读源码，最后还得让你打开浏览器替它描述哪里坏了。dsh-preview 补上这个闭环：六个无头浏览器工具加一个内置验证技能，agent 在宣称"做完了"之前，自己打开刚写的页面、查控制台、读渲染后的 DOM、点按钮走交互，最后给你留一张截图。

实际效果

这张截图是 agent 在验证过程中自己拍的。

一次真实、未剪辑的运行：让 dsh agent（DeepSeek-V4-Pro）验证它之前写的 Three.js 体素游戏。装上 dsh-preview 后，它全自主完成了：

1. browser_open http://localhost:8091 —— 页面加载成功，加载期零控制台错误。
2. browser_console —— 发现一条 404（/favicon.ico），正确判断为无害；其余 7 个本地资源全部 200。
3. browser_read —— 逐字确认了开始界面文案、操作说明和 HUD 文本。
4. browser_interact（点击开始按钮）—— 遮罩关闭、HUD 出现，它亲眼看着坐标从 41.0 落到 39.0、FPS 稳定在 120，据此判断物理和渲染循环正常。无新增错误。
5. browser_screenshot —— 开始前/后两张 PNG 存进工作区留档。
6. 报告里明确列出验证了什么——以及验证不了什么（真实 GPU 渲染、指针锁定手感）。

全程没有人类转述过一张截图。

安装

dsh plugin --profile web add dsh-preview

自动使用你机器上的 Chromium 内核浏览器——Google Chrome、Microsoft Edge 开箱即用；都没有的话执行一次 npx playwright install chromium 并把 browserChannels 设为 [chromium]。

需要 Node ^22.19 || >=24（与 dsh 本体一致）。

工具一览

| 工具 | 作用 | | --- | --- | | browser_open | 打开 http(s) URL 或本地文件/目录（自动经 127.0.0.1 静态服务）。返回 pageId 和加载期控制台错误。 | | browser_console | 自加载以来捕获的控制台消息 + 失败网络请求。 | | browser_read | 无需视觉的确定性读取：渲染后 text、外层 html、或指定选择器的 styles（盒模型 + 关键计算样式）。 | | browser_interact | 对选择器执行点击/输入/按键/滚动，并报告交互引发的新控制台错误。 | | browser_screenshot | 视口、全页或单元素 PNG，存入工作区。 | | browser_close | 验证完毕后关闭页面。 |

browser_read 是设计核心：纯文本模型用确定性事实（盒尺寸、颜色、display 值、渲染文案）验证布局，而不是对着像素猜。截图是给人看的。

内置技能

插件自带 frontend-verify 技能，教会 agent 完整纪律：打开 → 查控制台 → 读取 → 交互 → 截图 → 修复 → 复验；逐字报告通过了什么检查，说不清的部分明确点名而不是含糊带过。想用自己的流程可设 registerSkill: false 关闭。

配置

所有可调项都是插件配置——写进 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: []          # 允许 browser_open 访问的额外主机名
    registerSkill: true

安全模型

• localhost / 127.0.0.1 / ::1 始终放行——前端验证只需要这些。
• 其他主机默认拒绝。需要时通过 allowedHosts 精确授权；错误信息会引导模型来问你，而不是绕过限制。
• 本地路径以只读方式、限定在其所在目录内、经临时 127.0.0.1 端口服务，带路径穿越防护。
• 插件不输入任何凭证；技能明确禁止截取含密钥或个人数据的页面。

已知限制

• 无头渲染与真实桌面浏览器有差异：指针锁定、部分 GPU 路径、系统对话框行为不同。内置技能会让 agent 在相关时主动说明。
• 暂无视觉描述：截图给人看，机器验证走 browser_read/browser_console。通过你现有 dsh 模型路由做"截图→文字描述"在路线图上。
• 每个 dsh 进程共享一个浏览器进程；页面开销很低，但并行 agent 共用它。

本地开发

git clone https://github.com/Viger1/dsh-preview.git && cd dsh-preview
corepack pnpm install
corepack pnpm run build
dsh plugin --profile web add /absolute/path/to/dsh-preview   # 链接本地目录

corepack pnpm run watch 加一次配置 touch 即可快速编辑-重载。

同系插件

| 插件 | 给 agent 的能力 | | --- | --- | | dsh-preview（本仓库） | 👁 眼睛——验证自己写的页面：打开、读取、截图、自检 | | dsh-pilot | ✋ 手——按无障碍 ref 操作任意页面，带网络层域名围栏 | | dsh-review | 🔍 判断力——找出缺陷，并在报告前逐条尝试推翻它 | | dsh-design | 🎨 品味——先约束选择，再实测结果有没有守住 |

三者均可独立安装、可共存（工具前缀不同，工程规范一致）。

协议

MIT