Viewwright

English · 简体中文

让 Codex 交付真正能用的产品界面。

Viewwright 是一个 Codex skill，适合后台、工作台、运营工具、表单流程、数据编辑器、任务中心、开发者工具这类真实产品界面。

它不是让页面“看起来更像 AI 生成的高级稿”。它要解决的是更难、也更常见的问题：页面能跑，截图也没明显问题，但字段放错了、状态离主流程太远、低频配置抢了主路径的注意力，用户第一眼不知道该怎么完成任务。

Codex 会写代码。Viewwright 让它先把产品问题想清楚：

• 用户到底要完成什么？
• 页面里的核心对象是什么？
• 每个字段属于哪个父级决策？
• 哪些字段是主路径，哪些只是可选配置？
• 校验、错误、结果、日志应该贴在哪里？
• 哪些业务逻辑、数据流和组件体系不能被顺手改坏？

截图不是核心。截图只是收据。真正的产品是任务路径、字段层级、对象分组、被保住的业务行为，以及用户能顺着完成工作的界面。

为什么需要它

AI agent 做前端时，最容易犯的错不是“按钮不够漂亮”。更真实的问题是：

• 还没理解主任务，就开始换样式；
• 把内部工作台做成通用 SaaS 模板；
• 低频可选字段被做成首屏大模块；
• 校验结果离触发它的操作太远；
• 一个 craft pass 把错误结构打磨得更高级；
• 为了页面整齐，把字段按栅格摆开，却破坏了业务分组；
• 新造一堆 ModernButton、FancyCard，项目里多出一套平行组件；
• 没打开真实页面，就说已经验证过。

Viewwright 给 Codex 加的是一套产品 UI 交付协议：先定边界，再建 Decision Map，再复用现有组件，再保业务实现，再看真实页面，最后用语义 readback 和 validator 收口。

用户目标
→ 可见范围判断
→ 产品模型和 Decision Map
→ 组件清点
→ 保业务实现
→ 真实页面检查
→ 语义 readback
→ validator / 可选 guard
→ 交付说明

它能抓住什么

| 常见问题 | Viewwright 会追问什么 | | --- | --- | | 孤儿字段 | 这个字段属于哪个业务对象？服务哪个父级决策？ | | 可选配置抢主路径 | 这个字段是低频的吗？应该 inline、折叠，还是降权？ | | 按栅格硬摆 | 控件是按业务含义分组，还是只是放在有空间的地方？ | | 模板化后台 | 页面更漂亮了，但任务更清楚了吗？ | | 状态离主流程太远 | loading、empty、error、success、日志是否贴着用户动作？ | | 外部设计工具带偏 | 参考和 craft 有没有覆盖 Viewwright 的产品语义判断？ | | 想象中的 QA | 真实页面到底有没有打开、读回、验证？ |

举个很典型的例子：

“名称后缀”是目标命名规则的可选字段，不应该变成首屏独立大模块。 它应该靠近目标名预览、重名校验和命名规则，而不是抢走主路径注意力。

这类问题不是截图 hash 能解决的。它需要产品语义判断。

它怎么工作

Viewwright 把一次 UI 改动拆成几层：

明确范围
→ 建立产品决策图
→ 复用现有组件体系
→ 在不漂移业务逻辑的前提下实现
→ 检查真实渲染页面
→ 完成语义 readback
→ 验证交付证据

最重要的是 Decision Map。

每个可见控件都应该能回答：

我属于哪个父对象？
我服务哪个用户决策？
我是 primary、secondary、optional、advanced，还是 risky？
我的视觉权重和使用频率匹配吗？

Viewwright 把两种质量分开看：

Mechanical QA
  页面有没有真实渲染？截图和 audit 是否自洽？证据是否新鲜？

Product layout judgment
  字段、状态、操作和结果是否出现在正确的位置？视觉权重是否匹配任务？

页面“能跑”不等于产品 UI “正确”。

快速开始

环境要求：

• Node.js 18 或更新版本；
• 支持 skills 的 Codex；
• 只有通过 viewwright-qa 做浏览器捕获时才需要 Playwright。

安装 npm 包：

npm install -g viewwright

安装 Codex skill 目录：

mkdir -p ~/.agents/skills
rm -rf ~/.agents/skills/viewwright
cp -R "$(npm root -g)/viewwright/viewwright" ~/.agents/skills/viewwright

如果 Codex 里没有出现这个 skill，重启 Codex。

然后直接对 Codex 说目标：

Use $viewwright to improve this table area. Preserve API, data flow, and business logic.

Use $viewwright to redesign this dashboard into a real production console. Do not make it a generic SaaS template.

Use $viewwright to review this page first. Do not change code yet.

一次正常的 Viewwright 任务，应该先出现一句范围判断：

I will handle this as a local improvement: I will only change the table area, preserve API/data flow/business logic, run available checks, and verify the rendered page if a runnable route exists.

这句话不是客套。它让 Codex 在改文件前先把自动判断亮出来。

和设计工具怎么配合

Viewwright 可以独立使用。

awesome-design-md、DESIGN.md、Impeccable、Figma、axe-core、Storybook、Chromatic、Percy、Applitools 都是可选增强，不是安装前提。

| 工具 | 在 Viewwright 工作流里的角色 | | --- | --- | | awesome-design-md | 视觉参考库。借密度、节奏、表单结构、命令区、状态表达和 token 思路，不复制皮肤。 | | DESIGN.md | 项目长期视觉契约。管理字体、间距、组件、状态和语气。 | | Impeccable | 语义结构不失败之后的 craft pass。用于打磨字体、节奏、间距和 anti-AI-slop。 | | frontend-design | 更适合纯营销页、showcase、greenfield 或大胆视觉探索。 | | Figma / Code Connect | 当项目已有真实设计系统时，提供设计到代码的上下文。 | | Playwright | 真实页面证据和关键流程检查。 | | axe-core | 无障碍基线检查。 | | Storybook / Chromatic / Percy / Applitools | 组件或视觉回归证据。 |

顺序很重要：

Viewwright 判断 UI 应该表达什么。
参考库提供它可以是什么气质。
DESIGN.md 定义它必须如何保持一致。
craft 工具把它打磨得专业。
evidence 工具证明它被检查过。
Viewwright 给最终 product layout verdict。

如果外部工具被请求、提到、检查、调用、不可用、跳过，或者只是用了它的原则，最终交付里都必须说明 provenance。不能把“只应用了原则”说成“实际用了工具”。

不适合什么

Viewwright 不是：

• 截图转 UI demo；
• 设计系统生成器；
• Figma、Playwright、axe 或视觉回归工具的替代品；
• 纯营销页设计 skill；
• 把每个页面都做得更花的美化器；
• QA artifact 的安全防伪系统。

适合用 Viewwright 的前提是：页面涉及产品工作流、业务行为保护、字段语义、交互质量，或需要可验证的交付。

如果只是纯品牌页、插画页、营销页视觉探索，直接用视觉/设计型 skill 更合适。

主要命令

| 命令 | 作用 | | --- | --- | | viewwright-qa | 打开 URL，采集真实页面 evidence，记录 DOM audit，并写入 .ui-review artifacts。 | | viewwright-validate | 验证截图 evidence、raw audit、derived summary、findings、verdict、readback 和 freshness。 | | viewwright-guard | Codex handoff 的可选 soft Stop-hook guard。 |

viewwright-validate 和 viewwright-guard 不需要 Playwright。只有通过 viewwright-qa 做浏览器捕获时才需要 Playwright。

如果目标项目还没有 Playwright：

npm install -D playwright
npx playwright install chromium

真实页面验证

一次典型 capture：

viewwright-qa \
  --url http://localhost:5173 \
  --out .ui-review \
  --expect-text "Product name" \
  --phase after

然后填写生成的 readback，再验证：

viewwright-validate --out .ui-review

如果只是 capture-only 的中间态：

viewwright-validate --out .ui-review --allow-pending

.ui-review/ 是本地证据，默认不要提交到仓库。

语义 readback 门禁

完成态的 Viewwright run 需要语义 readback。

readback 必须包含：

• Decision Map：核心对象、父对象、父决策、每个决策下的可见控件；
• Semantic Layout：主路径、风险状态、分组、字段层级、低频控件降级、父决策不清晰的控件、被过度抬高的可选字段，以及一个具体批评；
• Product layout verdict：pass、warn 或 fail，并写清楚具体原因。

ok、good、pass、n/a、none 这种泛泛 readback 会被拒绝。它不能证明 Codex 真的检查了产品结构。

可选 Stop-hook guard

viewwright-guard 是给 Codex Stop hook 用的 soft guard。当前端文件发生变化时，它会检查 QA evidence 是否缺失、过期、无效、失败或仍在 pending。

手动运行：

viewwright-guard --out .ui-review

默认 warning 不阻断。更严格的环境可以用 --strict，CI 或审查脚本可以用 --exit-code。

评测

docs/evaluation.md 里有建议的评测方案。

推荐对比：

• 裸 Codex；
• Codex + 通用设计 skill；
• Codex + 视觉参考；
• Viewwright 单独使用；
• Viewwright + 可选参考 / craft 工具。

核心指标不是“截图好不好看”，而是：语义 bug 检出率、false-pass rate、修订轮数、任务成功率、first-click accuracy、视觉工艺评分，以及 craft pass 后是否仍保留 product layout verdict。

License

MIT. See LICENSE.