DSH Visual Acceptance

面向 AI 生成 Web 产品和 UI 原型的本地验收与复验工作台。

English: A local-first acceptance and retest workbench for AI-generated Web products and UI prototypes.

Beta 说明： 它检查“页面是否按声明的范围真实打开、有哪些可追溯的浏览器异常、修改后是否可按原条件复验”，不替用户做最终审美判断，也不自动修改或发送项目代码。

Beta note: It verifies whether a page opens within its declared scope, records traceable browser signals, and lets people retest after a change under the original conditions. It does not make the final aesthetic decision, edit code, or send instructions to an Agent.

当前仓库已实现 0.1.1-closed-loop-beta 的最小闭环：在既有快速验收 UI 上，将确定性异常保存为 Finding Candidate；用户可明确立为项目级 Issue、追加人工 Decision、复制获批 Issue 的本地修改包，并按基线 Run 的不可变 Matrix 创建 Retest。系统只给出复验候选关系，只有人工确认才能把 Issue 写为 resolved。

它仍不等于完整 V0.1：Provider 实际推理、OCR、参考图 / Pixel Diff、自动 Agent 会话注入、Codex Skill 与真实项目试点均未完成。

功能 / What it does

当 DSH 或 Codex 生成/修改了本地网页后，用户在当前 DSH 会话中：

1. 选择本地 HTML 或 localhost 页面，并声明桌面/窄屏、主题和需要的状态；
2. 运行一次真实浏览器检查，得到 Ready、控制台、请求/HTTP、图片、字体、横向溢出与截图证据；
3. 把需要跟踪的 Finding Candidate 明确立为 Issue，记录人工 Decision；
4. 仅对已批准修改的 Issue 复制本地修改包给 Agent；
5. 修改后按同一个不可变 Matrix 复验，并由人确认是否解决、仍存在或回归。

Ready 已满足 和“0 个异常信号”不是“视觉通过”。它们只说明当前声明的浏览器事实没有发现相应异常。

After DSH or Codex generates or changes a local page, a person can:

1. declare a local HTML file or localhost target, viewports, themes, and states;
2. run a real browser check that produces Ready, console, request/HTTP, image, font, horizontal-overflow, and screenshot evidence;
3. promote a Finding Candidate to a tracked Issue and record a human Decision;
4. copy a local change package only for an approved Issue;
5. rerun the immutable original Matrix after a change, then confirm the outcome themselves.

Ready reached and 0 signals do not mean visual approval. They only mean that no corresponding deterministic browser signal was found for the declared scope.

非功能 / What it does not do

• 不访问公网 URL，不爬取或自动操作第三方网站；

• 不做参考图比较、OCR、Pixel Diff、视觉模型推理或单一质量评分；

• 不自动创建正式 Issue、修改项目文件、把修改包发送给 Agent，或自动写入 resolved；

• 不替用户声明业务状态；非默认状态必须由用户提供可验证的 Ready 条件；

• 不宣称已完成真实项目试点或 DSH Desktop 的完整兼容验证。

• It does not visit public URLs or crawl or operate third-party websites.

• It does not perform reference-image comparison, OCR, pixel diff, VLM inference, or generate a single quality score.

• It does not automatically create a formal Issue, change project files, send a change package to an Agent, or mark an Issue resolved.

• It does not infer business states for the user. Non-default states need a verifiable Ready selector or text.

• It does not claim that the five-project pilot or full DSH Desktop compatibility is complete.

当前阶段 / Current stage

• 产品定位：验收与复验工作台

• 首个入口：DeepSeek Harness 会话级工作台

• 状态范围：快速模式检查首页默认状态；其他页面和状态由用户手工声明

• 架构策略：核心中立，DSH 优先，Codex Skill 后置

• 当前版本：0.1.1-beta.1

• Positioning: acceptance and retest workbench

• First surface: a DeepSeek Harness session-level workbench

• State scope: Quick mode checks the home page's default state; people declare other pages and states manually

• Architecture: core-neutral, DSH-first, Codex Skill deferred

• Current version: 0.1.1-beta.1

兼容性 / Compatibility

• 已实测：DeepSeek Harness Web 0.1.1-rc.2、Node.js >=22.19；

• 页面对象：localhost 或当前会话工作区内 HTML；

• 入口：非空会话中的 conversation.view“视觉验收”Tab；

• 未完成 Gate：DSH Desktop 深浅色/重开、下一个 DSH 版本兼容、5 个真实项目试点。

• Verified: DeepSeek Harness Web 0.1.1-rc.2, Node.js >=22.19.

• Supported targets: localhost or HTML within the current session workspace.

• Entry: the Visual Acceptance tab in a non-empty conversation.view session.

• Remaining gates: DSH Desktop light/dark and restart, the next DSH version, and a five-real-project pilot.

安装 GitHub Beta / Install the GitHub Beta

在 DSH Web Profile 中执行：

dsh plugin --profile web add github:PolinniZhong/dsh-visual-acceptance#v0.1.1-beta.1
dsh --profile web --dump-config
dsh web

dsh plugin add 会安装 Bundle 并将其加入当前 Profile；--dump-config 中应出现 dsh-visual-acceptance 层。重启后，在任一非空会话顶部打开“视觉验收”Tab。

卸载 / Uninstall:

dsh plugin --profile web remove dsh-visual-acceptance

本地开发安装 / Local development install

dsh plugin --profile web add "link:/absolute/path/to/dsh-visual-acceptance"

DSH 空白会话不会挂载 conversation.view，因此需要先发送一条消息，Tab 才会出现。

DSH does not mount conversation.view in an empty session. Send one message first, then open the Visual Acceptance tab.

首个可用切片 / First usable slice

• Target：localhost 或当前会话工作区内的 HTML；

• Quick：默认生成桌面 1280×800、窄屏 390×844 的首页浅色打开检查，可多选主题并在运行前查看完整覆盖摘要；

• Matrix：通过“检查其他页面或业务状态”进入 1–8 个手工检查点，包含路径、状态、视口、主题和 Ready 条件；路径为 / 时保留用户选中的确切 Target 页面，只有填写 /reports.html 等显式路径才切换站内页面；

• Facts：Ready 状态、状态复现证据、console、请求失败、HTTP 错误、图片、字体、横向溢出；信号可展开查看原始值；

• Evidence：每个已执行检查点的 PNG 截图，写入前校验格式与非零尺寸；内容级空白检测后置；

• Storage：.dsh-visual-acceptance/runs/<run-id>/；

• Lifecycle：Run 可取消；插件关闭时中止任务、关闭 Chrome、撤销路由与样式。

• Target: localhost or HTML in the current session workspace.

• Quick: creates desktop 1280×800 and narrow 390×844 home-page opening checks; themes are selectable and the full coverage summary is shown before execution.

• Matrix: use Check other pages or business states to declare 1–8 checkpoints with path, state, viewport, theme, and Ready condition. A / path preserves the exact selected target page; an explicit path such as /reports.html switches page within the same origin.

• Facts: Ready state, state-reproduction evidence, console, failed requests, HTTP errors, images, fonts, and horizontal overflow. Signals can be expanded to inspect raw values.

• Evidence: a PNG screenshot for each executed checkpoint. Format and non-zero dimensions are verified before it is stored; content-level blank-image detection is deferred.

• Storage: .dsh-visual-acceptance/runs/<run-id>/.

• Lifecycle: Runs can be cancelled. Closing the plugin aborts work and releases Chrome, routes, and listeners.

闭环 Beta / Closed-loop beta

• Candidate：console、请求、HTTP、坏图、字体、横向溢出与 unreached 只生成 Finding Candidate，不自动生成正式 Issue；

• Issue：用户可从 Candidate 明确“立为 Issue”，或从检查点截图创建手工视觉 Issue；

• Decision：approved-fix / accepted-risk / dismissed / deferred 以追加历史保存，后续 Run 不覆盖；

• Change Package：只有最新 Decision 为 approved-fix 才能生成本地 Markdown/JSON，并复制给用户；不会自动发送给 Agent；

• Retest：从基线 Run 复制不可变 Matrix，显示 new-candidate / still-detected / possibly-resolved / regressed / not-verifiable / needs-human-review；

• Human Gate：系统不自动写 resolved；用户可以确认、否决、合并或拆分关系。

• Candidate: console, request, HTTP, broken-image, font, overflow, and unreached signals create Finding Candidates only—not formal Issues.

• Issue: a person can explicitly create one from a Candidate, or create a manual visual Issue from a checkpoint screenshot.

• Decision: approved-fix / accepted-risk / dismissed / deferred is append-only history and is never overwritten by a later Run.

• Change Package: only an Issue whose latest Decision is approved-fix can produce local Markdown/JSON for the user to copy. It is never automatically sent to an Agent.

• Retest: a baseline Run provides an immutable Matrix; results are shown as new-candidate / still-detected / possibly-resolved / regressed / not-verifiable / needs-human-review.

• Human gate: the system never writes resolved automatically. People can confirm, reject, merge, or split relations.

使用方法 / How to use

1. 先启动本地页面，例如 http://127.0.0.1:4173；

2. 在 DSH 非空会话中打开“视觉验收”；

3. 在“页面地址或文件”填入本机 URL，或当前工作区内的 HTML，例如 examples/acceptance-demo/index.html；

4. 保留或调整桌面/窄屏、浅色/深色，在“确认验收指令”中核对对象和范围，然后点击“检查 N 个组合”；

5. 查看右侧的 Ready、确定性异常信号和截图。运行完成不等于视觉通过；

6. 对需要跟踪的 Candidate 点击“立为 Issue”，补充影响并保存；也可从截图新增手工视觉 Issue；

7. 在“问题与决定”中追加人工 Decision；只有“批准修改”后才可点击“复制修改包”；

8. 修改完成后点击“按原条件复验”，根据候选关系作出人工确认或否决；

9. 需要空、错误、权限等状态时，选择“检查其他页面或业务状态”，并为非默认状态提供专用 Ready Selector 或 Ready Text。

10. Start a local page, for example http://127.0.0.1:4173.

11. Open Visual Acceptance in a non-empty DSH session.

12. Enter a local URL or an HTML file in the current workspace, such as examples/acceptance-demo/index.html.

13. Keep or change desktop/narrow and light/dark options. Review the target and coverage in Confirm acceptance instruction, then select Check N combinations.

14. Review Ready, deterministic signals, and screenshots. A completed Run is not visual approval.

15. Select Create Issue for a Candidate worth tracking, add its impact, and save it. You can also create a manual visual Issue from a screenshot.

16. Add a human Decision under Issues and decisions. Copy change package is available only after Approve fix.

17. After the change, select Retest under original conditions and make a human confirmation or rejection based on the candidate relation.

18. For empty, error, or permission states, select Check other pages or business states and provide a state-specific Ready selector or Ready text.

文档 / Documents

• V0.1 PRD（中文） · V0.1 PRD (English)
• Product brief（中文） · Product brief (English)
• Architecture（中文） · Architecture (English)
• Design（中文） · Design (English)
• Release acceptance（中文） · Release acceptance (English)
• Spike plan · Spike report · Project brief · Adversarial review · Closed-loop iteration plan

验证边界 / Verification boundary

仓库中的 spike 代码用于验证技术假设。只有实际运行并留下证据的项目才能标记为“已验证”；静态检查、模拟生命周期和浏览器实测必须分别记录。

当前结论是“闭环 Beta 已在 Fixture 与真实 DSH Web 中跑通”，不是“完整产品已经可交付”。Candidate → Issue → Decision → 修改包 → 原 Matrix Retest → 人工确认已经实测；Desktop 壳层深浅色重开、Provider 图片推理、主观视觉判断准确率和 5 个真实项目试点仍是后续 Gate。

The current conclusion is: the closed-loop Beta has run on fixtures and real DSH Web, not that the complete product is ready for delivery. Candidate → Issue → Decision → Change Package → original-Matrix Retest → human confirmation has been exercised. Desktop shell light/dark and restart, Provider image inference, subjective-judgement accuracy, and a five-real-project pilot remain gates.

隐私与安全 / Privacy and safety

• Run、Issue、Decision、截图和修改包默认写入目标工作区的 .dsh-visual-acceptance/，不应提交到 Git；

• 插件只检查用户提供的 localhost 或工作区内 HTML，不访问公网 URL；

• 不读取或上传 Cookie、Authorization Header、网络响应 Body 或表单输入值；

• 仅“复制修改包”，不直接修改项目，也不会发送给 Agent；

• 发现安全问题时，请勿在公开 Issue 中粘贴项目内容、截图、Token 或本地绝对路径。

• Runs, Issues, Decisions, screenshots, and change packages are written to .dsh-visual-acceptance/ in the target workspace and should not be committed to Git.

• The plugin checks only user-provided localhost targets or workspace HTML; it does not access public URLs.

• It does not read or upload cookies, authorization headers, network response bodies, or form values.

• It only copies a change package; it does not change the project or send anything to an Agent.

• Do not put project content, screenshots, tokens, or local absolute paths in a public security issue.

License

MIT