0033 原型审查页和不靠看图的界面检查

• 状态：已采纳（1.13.0-beta.2）

背景

内网的使用者有三个限制：

• 只能用 Paseo 网页端（桌面端有安装限制），所以 Paseo 内置浏览器和它的 browser_* 工具用不了，1.8 起的"浏览器验证"实际上从不运行。
• 内网模型看图能力弱：截图交给它判断界面对不对，效果差，每张图还要消耗不少 token。
• 需求方多数不是开发者，确认方案时看得出"不对"，但说不清哪里不对、要改成什么；插件里只有一个文本框写修改意见。插件页面也不能显示 HTML，原型只能在功能目录里自己找文件打开。

决定

• 原型审查页：一个本机网页（engine/src/review.ts），插件和 req review 打开它。需求方在原型上点选、选改法、补一句话，页面记下被点元素的文字、颜色、字号、大小、所在区域和对应的 AC；双击可以直接改文字。提交时整理成一份带位置信息的清单，经已有的 req reply 转给需求会话，确认方案经 req approve：不增加新的流程分支。
  • 原型由 agent 生成，内容可能来自卡片等外部文字，和提交接口同源。所以原型以 script-src 'none' 返回，里面的脚本不运行，审查页从外面读写它的 DOM。
  • 服务只监听 127.0.0.1，地址带随机令牌；另有一个只读令牌。远程访问要显式设置环境变量。
  • 每次打开时保存原型的版本，改过后用文字差异标出变化，需求方不用自己找改了哪里。
  • 方案设计的提示词规定原型的写法（data-ac、data-label、data-state、真实文字），审查页和界面检查都依赖它。
• 界面检查 req ui-check：用 playwright-core 驱动本机的 Edge 或 Chrome（不下载浏览器，驱动在第一次使用时从 npm 源装到 ~/.req-kit/tools），在页面里运行一段固定的脚本，用文字报告看得出的版面问题，并拿原型里的标题、按钮、字段名、表头和页面对文字。结果是确定的，不依赖模型看图。截图只存文件给人看。验证类步骤总是附上它；有 Paseo 浏览器时，同一段脚本也可以用 browser_evaluate 运行。
• 对比度只报明显看不清的（低于 3:1，大字 2.5:1），不报 WCAG 4.5:1 的边缘情况：常见组件库的主按钮正好在这个边缘，全报会淹没真正的问题。

影响

• 需求方确认方案的方式从"写一段话"变成"在原型上点"，修改意见能直接定位到元素。效果要看原型是否按约定标了区域。
• 验证不再依赖桌面端和模型的视觉能力；需要本机有 Edge 或 Chrome（Windows 自带 Edge）。
• req ui-check 第一次运行要能从 npm 源取到 playwright-core，内网走镜像。
• 只检查"看得出的"问题，不判断设计是否好看；"和原型对文字"只比较标签类文字，原型中的示例数据不比较。

本页由仓库中的 docs/adr/0033-prototype-review-and-ui-check.md 生成。在 GitHub 上编辑