dsh-visual-acceptance

Readme

# 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.2-responsive-acceptance` 候选：保留 `0.1.1` 的人工闭环，并新增版本化覆盖计划、CSS 断点发现、响应式证据总览、基础确定性质量信号、原 Matrix 截图 Diff，以及受控状态复现步骤。系统仍只给出 Candidate；只有人工确认才能创建 Issue 或把 Issue 写为 `resolved`。

它仍不等于完整 V0.1：参考图比较、Provider 实际推理、OCR、自动 Agent 会话注入、Codex Skill 与真实项目 Gate 均未完成。当前 Pixel Diff 只比较同一 Retest Matrix 的基线与当前截图，不是参考设计验收。

## 功能 / What it does

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

1. 选择本地 HTML 或 localhost 页面，并选择快速、标准、页面断点或自定义覆盖计划；
2. 运行真实浏览器检查，得到 Ready、运行异常、响应式质量信号、截图和跨视口总览；
3. 把需要跟踪的 Finding Candidate 明确立为 Issue，记录人工 Decision；
4. 仅对已批准修改的 Issue 复制本地修改包给 Agent；
5. 修改后按同一个不可变 Matrix 复验，查看基线/当前/Diff，并由人确认是否解决、仍存在或回归。

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

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

1. select a local HTML or localhost target and choose Quick, Standard, Page-breakpoint, or Custom coverage;
2. run real browser checks that produce Ready, runtime failures, responsive quality signals, screenshots, and a cross-viewport overview;
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, inspect Baseline/Current/Diff, 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、视觉模型推理、真实设备兼容声明或单一质量评分；
- 不自动创建正式 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, VLM inference, real-device compatibility certification, 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 会话级工作台
- 覆盖范围：快速 2 项、标准 8 项、页面 CSS 断点与 1–8 项自定义 Matrix
- 架构策略：核心中立，DSH 优先，Codex Skill 后置
- 当前 GitHub Pre-release：`0.1.2-beta.1`

- Positioning: acceptance and retest workbench
- First surface: a DeepSeek Harness session-level workbench
- Coverage: two-checkpoint Quick, eight-checkpoint Standard, readable CSS breakpoints, and one-to-eight Custom Matrix
- Architecture: core-neutral, DSH-first, Codex Skill deferred
- Current GitHub Pre-release: `0.1.2-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 中执行：

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

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

卸载 / Uninstall:

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

### 本地开发安装 / Local development install

```bash
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；
- Coverage：Quick 为 `390×844 + 1280×800`，Standard 为 6 个布局视口加 2 个主题锚点；Page-breakpoint 和 Custom 最多 8 项；
- Matrix：自定义检查点包含路径、状态、视口、主题、受控动作和 Ready 条件；路径为 `/` 时保留用户选中的确切 Target 页面；
- Facts：Ready、状态复现、运行失败、响应式质量、基础无障碍/可达性和横向溢出；信号可展开查看原始值；
- Evidence：内容有效性校验后的 PNG；同尺寸 Retest 增加基线/当前/Diff；
- Storage：`.dsh-visual-acceptance/runs/<run-id>/`；
- Lifecycle：Run 可取消；插件关闭时中止任务、关闭 Chrome、撤销路由与样式。

- **Target:** localhost or HTML in the current session workspace.
- **Coverage:** Quick uses `390×844 + 1280×800`; Standard uses six layout viewports plus two theme anchors; Page-breakpoint and Custom remain capped at eight.
- **Matrix:** Custom Checkpoints include path, state, viewport, theme, controlled actions, and Ready. `/` preserves the exact selected Target page.
- **Facts:** Ready state, controlled state-reproduction evidence, runtime failures, responsive quality, basic accessibility/reachability, and horizontal overflow. Signals can be expanded to inspect raw values.
- **Evidence:** a content-validated PNG for each checkpoint; Retest also records Baseline/Current/Diff when dimensions match.
- **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. 选择快速、标准、页面断点或自定义计划，在“确认验收指令”中核对生成的 Matrix，然后点击“检查 N”；
5. 查看右侧的 Ready、确定性异常信号和截图。运行完成不等于视觉通过；
6. 对需要跟踪的 Candidate 点击“立为 Issue”，补充影响并保存；也可从截图新增手工视觉 Issue；
7. 在“问题与决定”中追加人工 Decision；只有“批准修改”后才可点击“复制修改包”；
8. 修改完成后点击“按原条件复验”，根据候选关系作出人工确认或否决；
9. 需要空、错误、权限等状态时，进入“自定义”，可增加受控状态步骤，并提供专用 Ready Selector、Ready Text 或 `assert-ready`。

1. Start a local page, for example `http://127.0.0.1:4173`.
2. Open **Visual Acceptance** in a non-empty DSH session.
3. Enter a local URL or an HTML file in the current workspace, such as `examples/acceptance-demo/index.html`.
4. Choose Quick, Standard, Page-breakpoint, or Custom. Review the generated Matrix, then select **Check N**.
5. Review Ready, deterministic signals, and screenshots. A completed Run is not visual approval.
6. 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.
7. Add a human Decision under **Issues and decisions**. **Copy change package** is available only after **Approve fix**.
8. After the change, select **Retest under original conditions** and make a human confirmation or rejection based on the candidate relation.
9. For empty, error, or permission states, use **Custom**, optionally add controlled state actions, and provide a state-specific Ready selector, text, or `assert-ready`.

## 文档 / Documents

- [V0.1 PRD（中文）](docs/prd-v0.1.md) · [V0.1 PRD (English)](docs/prd-v0.1.en.md)
- [Product brief（中文）](PRODUCT.md) · [Product brief (English)](PRODUCT.en.md)
- [Architecture（中文）](docs/architecture.md) · [Architecture (English)](docs/architecture.en.md)
- [Design（中文）](DESIGN.md) · [Design (English)](DESIGN.en.md)
- [Release acceptance（中文）](docs/first-slice-acceptance.md) · [Release acceptance (English)](docs/first-slice-acceptance.en.md)
- [Spike plan](docs/spike-plan.md) · [Spike report](docs/spike-report.md) · [Project brief](docs/project-brief.md) · [Adversarial review](docs/adversarial-review.md) · [Closed-loop plan](docs/iteration-plan-v0.1.md) · [Responsive plan](docs/iteration-plan-v0.1.2.md)

## 验证边界 / Verification boundary

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

当前结论是“`0.1.2-beta.1` 已作为 GitHub Pre-release 提供安装试用，并通过自动测试、本地 Chrome Spike 与 DSH Web 源码链接验收”，不是“稳定版或 DSH 插件市场已完成验收”。Desktop 壳层与后续 DSH 版本兼容、Provider 图片推理、参考图判断和 5 个真实项目试点仍是稳定版 Gate。

`0.1.2-beta.1` is available as a GitHub Pre-release for installation and usage feedback. It has passed automated tests, a local Chrome Spike, and linked-source DSH Web acceptance; this is not stable or marketplace-release approval. DSH Desktop/future-version compatibility, Provider inference, reference-design judgement, and the five-project pilot remain stable-release gates.

## 隐私与安全 / Privacy and safety

- Run、Issue、Decision、截图和修改包默认写入目标工作区的 `.dsh-visual-acceptance/`，不应提交到 Git；
- 插件只检查用户提供的 localhost 或工作区内 HTML，不访问公网 URL；
- 不读取或上传 Cookie、Authorization Header、网络响应 Body 或页面现有表单值；用户在状态配方中明确填写的值会随 Matrix 保存在本地，但不进入公开动作证据或修改包，因此不得用于密码、Token 等凭据；
- 仅“复制修改包”，不直接修改项目，也不会发送给 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, response bodies, or existing form values. A value explicitly declared in a state recipe is stored locally in the Matrix, but omitted from public action evidence and change packages; therefore recipes must not contain passwords or tokens.
- 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](LICENSE)