界面验收双轨:能断言的写脚本,不能断言的先量基线
模块:前端 · 验收面(doc/48 / doc/49 / doc/51,缺口感见 doc/45)|状态:双轨已落地(2026-10-23 行为层、2026-10-24 视觉层);场景级 Eval 未施工|证据:
doc/48-前端可用性欠账.md、doc/49-走查缺陷修复.md、doc/51-UI视觉重做.md、doc/45-场景化Eval框架.md、yk-tako-eino/web/{playwright.config.ts,package.json,e2e/,test/}
1. 场景与病灶
改完前端,问「这次改好了吗」。答案通常只有一句:「我看着还行」。这句话既不能重跑,也不能在下次改动时报警——写它的人和读它的人之间没有任何可对质的东西。
真实的失败有三种,都不靠「读代码」能发现:
病灶一:过了类型检查,界面是空的。 ProjectsView.vue 里写了 p.x ?? (p.x = {...}),TypeScript 编译通过,npm run typecheck 退出码 0,但页面上的文件列表永远是空白。原因是 Vue 3 里赋值表达式的值是 raw 对象(不是 reactive proxy),后续再往这个 raw 对象写字段会绕过响应式拦截;触发条件是「赋值与改值之间隔着一次 await」——赋值标脏 → await 期间渲染一次(读当时的空值)→ 之后的写不再标脏 → 界面停在 await 那一瞬。这类 bug 只有在真浏览器里看 DOM 才抓得到,单测和类型检查都是绿的(doc/48 落地时 10 条自审问题第 1 条)。
病灶二:markdown 每个 token 重解析一遍。 模板里写 v-html="renderSafe(b.text)",流式输出时每来一个 token,所有气泡的 parse + sanitize 全部重跑一次。功能完全正常,表现只是「越跑越卡」。没有时间/次数这类数值,这个缺陷永远不会被提出来(doc/48 第 6 条,修法是 v-memo)。
病灶三:「统一风格」没有共同标尺。 改版前 8 个组件里散着 150 处硬编码颜色(App.vue 99、Configure.vue 16、ProjectsView.vue 12、MembersView.vue 8、ConfirmDialog.vue 6、InviteLanding.vue 5、PlanDoc.vue 3、PendingInvites.vue 1),同时存在 999/22/18/14/10/5px 六种圆角、六档字号。两个人各自「调好看」,改完谁也没法说清哪里变了、是变好还是变坏;下次再换方向,逐页找颜色必然漏(doc/51 §2)。
这三种病灶的共同结构是:「页面上的结果」不是一个可以断言的字节,而验收动作却只有一句口头结论。项目在字节面上已经有两台机器(快闸 + 活体,见 AGENTS.md「验收:两台机器」),界面面此前没有对应物。
还有一个反过来的教训(doc/45):字节面全绿,场景仍可能是坏的。PII 打码最初挂在 prepareInput,单测断言的是「挂载点被调用」——绿;但折叠发生在这之后,历史摘要把原文重新带回来,模型看到的是明文本。测试断言的是装配位置,不是用户场景的结果。这说明「有测试」不等于「场景被守住」,也是界面层必须按真实路径驱动的原因。
2. 候选与代价
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 人眼走查(改版前的现状) | 打开四个页面、两种宽度看一遍,写「看着没问题」 | 零成本;能发现明显丑/断 | 不可重跑、不留回归网;只在有人愿意看时成立;「好看」无共同标尺 |
| B 只补单测 | node --test 覆盖逻辑函数 |
快、无浏览器依赖 | 测不到 DOM、布局、响应式、真实浏览器里的 XSS;病灶一/二都漏 |
| C 双轨(选定):能断言的写脚本,不能断言的先量基线+截图 | 行为层用 Playwright 驱动真浏览器;视觉层先跑基线量出数值、按判据断言,再留截图 | 改动能重跑、回归能判红;观感也有一条可对质的线 | 多一套 Node 工具链与 chromium 约 150MB;视觉判据要人先定义;截图有维护成本 |
| D 直接用场景级 Eval 替换所有验收 | 每个功能写成「准备/执行/断言」的场景 | 最贴近真实用户 | 今天还没有这一层(doc/45 未施工);它管「agent 有没有把事办成」,管不了 CSS 对比度与 DOM 响应式,替换不了前两层 |
选 C。关键区分不是「机器 vs 人」,而是这件事有没有一个可判定的结果:
- 有(文本被当文字显示、保存不冲掉别的卡片、390px 下聊天区高度、对比度比值、横向溢出)→ 写成脚本断言,进回归网;
- 没有(「层级更清楚」「不像两块贴纸」)→ 先把它翻译成可量的指标(字号档数、圆角集合、气泡最大宽度、留白值),量一遍改前,再量改后;数值与截图一起留档。原文的观感词只是方向,判据必须是数。
3. 轨道一:行为与契约,写死成命令
3.1 界面行为(Playwright,Node 版)
放在 yk-tako-eino/web/e2e/,四个 spec:smoke.spec.ts(登录/发消息/停止)、files.spec.ts(项目文件区)、ui.spec.ts(保存独立、抽屉、窄屏、跨卡不冲掉编辑)、markdown.spec.ts(渲染与 XSS:发一条含 <script> 的消息,断言页面把它当文字显示且 window.alert 未被调用——DOMPurify 的真实运行环境是浏览器,node 里没有它,所以这条只能在 Playwright 里跑)。
配置的三个要点(web/playwright.config.ts):
| 项 | 取值 | 为什么 |
|---|---|---|
| 驱动对象 | baseURL 指向 Vite dev server(默认 5173),引擎由 Vite 代理 |
这层只驱动浏览器;要断 HTTP 字节走 scripts/acceptance/,两层不互相冒充 |
| 是否自己起 Vite | 默认不起(复用 ./scripts/dev.sh),TAKO_E2E_START_VITE=1 才自己拉 |
开发时复用已起的前端,免得端口打架;CI 无前端时才自起 |
| 服务器地址 | TAKO_WEB_BASE 可覆盖 |
同 AGENTS.md「活体脚本要参数化,不许写死端口」 |
失败时留 trace 与 screenshot(only-on-failure),成功不留——截图是排查材料,不是版本库内容。
跑法:
cd yk-tako-eino/web
npm run test:e2e # 前置:./scripts/dev.sh 已起 8901 + 5173,且已登录用的账号在库
npm run typecheck # vue-tsc -b
npm test # node --experimental-strip-types --test test/*.test.ts纯逻辑的单测放 web/test/(markdown.test.ts、reactive-trap.test.ts),不引 jsdom:renderMarkdown 不碰 DOM,node --test 直接跑;reactive-trap.test.ts 把「哪种写法会坏」钉死(含一条对照:赋值后紧接着改不坏、隔着 await 才坏),防止后人把防御式写法改回去。
3.2 契约字节(不重复,指路)
触碰信封、帧、端点字节的改动,界面脚本管不了,仍归 AGENTS.md 的两台机器:
- 快闸:
yk-tako-eino/internal/runengine/contract_test.go(不打模型、不依赖 PG/Redis); - 活体:
scripts/acceptance/expected.json+assert_contract.py(真起引擎、真跑一轮)。
doc/48 的 B1(新增 GET /api/workspaces/:id/files)就是两头都做:快闸加字节断言、活体加「用例 12」9 步,界面侧再加一条 Playwright。新增端点不许只加浏览器断言——浏览器看到的形状不是契约。
3.3 已知缺口:场景级 Eval(doc/45,未施工)
前两轨断言的是「这个请求/这个页面」;它们回答不了「让 agent 做一件事,它有没有真办成」。doc/45 的失败故事正是这个空洞:任务看板的行为(模型该不该建任务、该不该升级描述)今天没有任何护栏,只有人工抽验。方案已给出场景 = 准备 / 执行 / 断言 三层与 scripts/eval/ 落点,状态是未施工——本文件只记录它属于同一张验收图,不当成已覆盖。
4. 轨道二:观感,先量基线再断言
4.1 顺序:先跑基线,再改
doc/51 的做法是这条轨道的样子:改版前先用 Playwright 无头在 1440×900 与 390×844 两档实拍,量出四个具体失败(侧栏底部盖住最下面那行会话;手机端项目树占约 560px、聊天正文只剩约 120px;圆角六种、字号六档;用户气泡 474px / 助手 232px 宽度跳动)。「现在挺差的」由此变成四条可复现的数字/现象,改完可以逐条对账。
4.2 判据:六条,全部脚本可断言
四档视口:1440×900 / 1024×768 / 700×900 / 390×844。判据(doc/51 §7):
- 侧栏不重叠:900px 高、10 条会话时
rail-foot.top ≥ tree.bottom,且.tree的scrollHeight === clientHeight; - 手机可用:390×844 时聊天列表可视高度 ≥ 560px;抽屉能由遮罩 /
Esc/ 打开会话三种方式关闭; - 对比度:正文对背景 ≥ 7:1,次要文字 ≥ 4.5:1(按相对亮度脚本计算);
- 无横向溢出:四档
document.documentElement.scrollWidth === clientWidth; - 一致性:控件高只有 28/32 两档、列表行 30/34;圆角只出现 4 / 8 / 12 / 14 / 16 / 999 / 50%;
- 回归:
npm run typecheck、npm test、scripts/check-master-plan.sh。
4.3 实测(2026-10-24 U7 收口)
| 档位 | 横向溢出 | 正文对比度 | 次要文字对比度 | 圆角集合 | 控件高 / 行高 |
|---|---|---|---|---|---|
| 1440×900 | 0 | 16.88:1 | 4.51:1 | 4/8/14/16/50% | 28/32 · 30/34 |
| 1024×768 | 0 | 同上 | 同上 | 同上 | 同上 |
| 700×900 | 0 | 同上 | 同上 | 同上 | 同上 |
| 390×844 | 0 | 同上 | 同上 | 同上 | 32 · — |
390×844:顶栏 52px、聊天列表可视 699px、抽屉 280px;三种关闭方式均回到关闭态,焦点按「抽屉第一项 ↔︎ 菜单按钮」往返。单拍回归:all 28/28、tokens 12/12、rail 4/4、sidebar 5/5、pages 29/29、bubbles 16/16、invite 1/1、mobile 12/12;typecheck 退出码 0、npm test 14/14、check-master-plan.sh OK。
截图不入库:原图在 /tmp/tako-ui/、脚本在 tmp/51-UI重做/。它们是一次性的对账材料;进入版本库的是判据与数值,不是 150 张图。
5. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| Playwright 用 Node 版还是 Python 版 | Node 版 @playwright/test,装 web/ 下 |
界面断言要驱动浏览器并共享 TS 配置;契约字节层仍用 python,两层各管一段 |
| 单测要不要引 jsdom | 不引 | renderMarkdown 不碰 DOM;DOM 断言放 Playwright(真浏览器才是 DOMPurify 的运行环境) |
| 视觉验收放哪 | 脚本进 tmp/,只把判据与数值写进 doc |
与「台账不入库」一致;判据要能被下一轮照着重跑 |
| 截图/视频进不进库 | 不进(失败时的 trace/screenshot 也不进) | 体积大、且截图像素随字体/DPI 漂移,不是稳定真源 |
| 新端点的验收顺序 | 先 curl 字节(快闸+活体),再补界面断言 | 浏览器看到的形状不是契约;反过来会漏字节 |
| Playwright 会不会污染开发库 | 会,断言自己收尾删掉 | doc/48 第 9 条踩过:测试发的消息在开发库留下会话 |
| 一次验收覆盖多少档视口 | 四档(1440/1024/700/390) | 只测桌面会漏抽屉;只测手机看不出侧栏重叠 |
| 对比度阈值 | 正文 7:1、次要 4.5:1 | 比 WCAG AA(4.5/3)严;实测 16.88 / 4.51,边界很薄(次要文字只高 0.01) |
| 动画/过渡的验收 | 不断言 | 属观感且不稳;必要的信息只以「关闭后回到关闭态」这类终态断言 |
| 两屏未实测怎么办 | 如实登记,不假装覆盖 | doc/51 未量 PendingInvites / PlanDoc;沿用 AGENTS.md declared_not_asserted 的精神 |
6. 证据
方案:doc/48-前端可用性欠账.md(17 现象 → 14 修复;§6 为什么引 Playwright、两层验收表;10 条落地自审);doc/49-走查缺陷修复.md(第二次走查 12 项,P0 = 子代理名带空格导致全租户 tools[25].function.name 400);doc/51-UI视觉重做.md §0 四病灶 / §2 token 层 / §7 四档判据与实测 / §7.1 数值表;doc/45-场景化Eval框架.md §0 三层缺口与两个失败故事(PII 在折叠后复活、任务看板行为无护栏),状态未施工。
台账:tmp/48-前端可用性欠账/、tmp/49-走查缺陷修复/、tmp/51-UI重做/(本地,不入库)。
代码符号:
| 位置 | 是什么 |
|---|---|
yk-tako-eino/web/playwright.config.ts:10 |
TAKO_E2E_START_VITE 开关(默认不起 Vite) |
yk-tako-eino/web/playwright.config.ts:21 |
baseURL = TAKO_WEB_BASE ?? http://127.0.0.1:5173 |
yk-tako-eino/web/playwright.config.ts:23 |
trace: 'retain-on-failure' / 截图只在失败时留 |
yk-tako-eino/web/playwright.config.ts:34 |
自起 Vite 时 reuseExistingServer: true |
yk-tako-eino/web/package.json:10 |
npm test = node --experimental-strip-types --test test/*.test.ts |
yk-tako-eino/web/package.json:11 |
npm run test:e2e = playwright test |
yk-tako-eino/web/e2e/ui.spec.ts |
保存不冲掉别卡编辑、抽屉、窄屏 |
yk-tako-eino/web/e2e/markdown.spec.ts |
浏览器内 XSS 断言(<script> 不执行) |
yk-tako-eino/web/test/reactive-trap.test.ts |
Vue 3 raw object 陷阱的回归网(含对照形态) |
复核命令:
cd yk-tako-eino/web
npm run typecheck && npm test
npm run test:e2e # 前置:./scripts/dev.sh 已起
grep -n "TAKO_E2E_START_VITE\|baseURL\|retain-on-failure" playwright.config.ts
grep -rn "documentElement.scrollWidth\|contrast" ../../tmp/51-UI重做/ 2>/dev/null | head活体验收:2026-10-23 doc/48 两层全绿(快闸 3 条、活体 core 27 步、前端单测 7 条、Playwright 11 条);2026-10-24 doc/51 U7 四档实测全过(数值见 §4.3),单拍回归 28/28 等八组全绿;2026-10-23 doc/49 在隔离引擎 8944 + 浏览器 5173/8901 逐条手验 12 项。
7. 现状
- 仍有效:「能断言的写脚本,不能断言的先量基线」;界面层 = Playwright(
web/e2e/)+ 纯逻辑单测(web/test/)+ 四档数值判据;契约字节仍归快闸/活体,不重复;截图与视觉脚本不入库。 - 已知缺口:doc/45 场景级 Eval 未施工——「agent 有没有把事办成」今天没有机器护栏;doc/51 的
PendingInvites/PlanDoc两屏未纳入实测。 - 已翻转:2026-10-24 之前「界面只靠人眼走查」作废;「统一风格」不再靠逐页改颜色,先落 token 层(doc/51 §2/§3)。
- 同族问题:界面变更为什么需要事件通道 → 变更同步用事件通道;走查中暴露的 P0(子代理名合法性)→ 子代理规格与工具边界;侧栏树的呈现与验收 → 前端可用性欠账。