guo6x/dsh-shipcheck

· English · DeepSeek Harness 插件

前端不是因为 agent 说“看起来不错”就能交付；真实浏览器跑出证据，才算完成验收。

dsh-shipcheck 是 DeepSeek Harness 的证据优先前端交付验收插件。它调用 dsh-pilot 打开真实页面，再生成确定性的检查结果、截图、命名基线和可复现 JSON 报告。它不会修改项目，也不会替你忽略失败项。它的证据格式已经为下一阶段接入 dsh-palate 的高层设计判断留好接口。

它解决什么问题

设计库给建议，浏览器插件给双手；Shipcheck 先把事实证据闭环，后续再接入 palate 的设计判断，不让主观评分替代证据：

项目 URL → 真实浏览器 → 页面证据 → 确定性检查 → 基线对比 → 带截图报告

首版检查：

• 页面可用性、标题、可见正文和主标题
• 图片缺少替代文本、控件/链接缺少可访问名称
• 当前视口下的横向溢出
• 必须出现/禁止出现的文字、必须存在的 CSS selector
• 与明确命名基线之间的结构回归
• 浏览器运行时故障：控制台错误、未捕获异常、失败请求和 HTTP 4xx/5xx

每个失败项都会附带具体证据。只有显式调用 shipcheck_baseline 才会写入基线；普通验收不会覆盖已有基线。

工具

工具	作用
shipcheck_run	用真实浏览器检查 URL，对比基线，保存截图和 JSON 报告
shipcheck_matrix	把 1–20 个 URL 作为一次发布门禁检查，保留每个路由的截图、报告、失败证据和独立基线
shipcheck_flow	用真实浏览器执行一段用户流程，保存每一步截图、断言结果和脱敏证据
shipcheck_baseline	显式把人工确认过的页面保存为命名结构基线
shipcheck_history	查看最近报告及通过/失败摘要

Web 面板提供同样的本地闭环：侧边栏点 🚢，选择“单页”“多路由”或“流程”，查看状态、失败证据、截图路径和历史记录。

90 秒安装体验

dsh plugin --profile web add github:guo6x/dsh-pilot
dsh plugin --profile web add github:guo6x/dsh-shipcheck

重启 dsh web，打开侧边栏的 🚢 按钮，输入 http://127.0.0.1:3000 之类的本地地址。

也可以让 agent 执行：

用 shipcheck_run 检查 http://127.0.0.1:3000，项目名为 checkout，要求页面出现“Checkout”，禁止出现“Something went wrong”，告诉我是否可以继续人工验收。不要修改文件。

人工确认页面没问题后：

用 shipcheck_baseline 把当前 checkout 页面保存为 checkout 基线，再运行一次 shipcheck_run，如果有结构回归，说明变化和证据路径。

如果一次发布包含多个关键页面，可以让 agent 执行：

用 shipcheck_matrix 检查 http://127.0.0.1:3000/、http://127.0.0.1:3000/login 和 http://127.0.0.1:3000/checkout，矩阵名为 checkout-release。要求每个页面出现“Checkout”，禁止出现“Something went wrong”，并告诉我哪个路由失败以及对应的截图和 JSON 报告路径。

矩阵会在同一个真实浏览器会话中按顺序检查各路由。每个路由都有独立报告，并使用 <矩阵名>/<路由名> 形式的基线名，因此 login 页面不会覆盖 checkout 页面的基线；最后再生成一份汇总所有检查项的矩阵报告。

如果要验收真实用户流程，可以让 agent 执行：

从 http://127.0.0.1:3000/login 开始，用 shipcheck_flow 执行 checkout-login 流程：填写 Email 和 Password，点击 #submit，等待 URL 包含 /dashboard，断言页面出现“Logged in”，最后告诉我流程是否通过。不要修改文件。

流程最多支持 30 个有序步骤：navigate、click、fill、press、wait、wait_for 和 assert。每一步都会截图，失败后立即停止。填入的值只用于当前浏览器，保存到报告时会替换成 [redacted]。如果步骤点击提交按钮，仍可能改变被测应用状态，因此只对已获授权的环境提供明确提交步骤。

证据默认保存在 $DSH_HOME/shipcheck/：

shipcheck/
├── artifacts/       # 页面截图
├── baselines/       # 显式保存的命名基线
└── reports/         # 最近 JSON 报告，最多保留 100 条

因此 20 个路由最多会产生 21 条报告：每个路由一条，加一条矩阵汇总报告。

不需要 API key、云端面板、embedding 服务，也不需要自动写项目。dsh-pilot 作为同一 profile 的配套插件单独安装，这是因为 DSH 会阻止插件依赖里再嵌套 GitHub 仓库；如果缺少它，Shipcheck 会明确提示安装命令。

诚实边界

• 这是交付验收门，不是完整的跨操作系统像素级视觉回归实验室；首版基线比较稳定结构和文本漂移，不宣称不同机器上的截图像素完全一致。
• 首版还不会用 dsh-palate 原则给页面打分；当前先把供下一阶段使用的证据结构保存下来。
• 运行时证据通过浏览器 CDP 事件采集；如果配套浏览器不提供该能力，Shipcheck 会明确报告 warning，而不是假装运行时没有问题。
• 自动检查通过后，产品语义、内容质量和有意设计例外仍需要人工确认。

开发

pnpm install
pnpm test

核心测试使用伪造页面证据，不依赖浏览器；真实浏览器路径在 DSH Web profile 中调用 shipcheck_run、shipcheck_matrix 或 shipcheck_flow 时运行。

MIT 协议。