tako 文档 GitHub

界面验收双轨:能断言的写脚本,不能断言的先量基线

模块:前端 · 验收面(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 人」,而是这件事有没有一个可判定的结果:

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 的两台机器:

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):

  1. 侧栏不重叠:900px 高、10 条会话时 rail-foot.top ≥ tree.bottom,且 .tree 的 scrollHeight === clientHeight;
  2. 手机可用:390×844 时聊天列表可视高度 ≥ 560px;抽屉能由遮罩 / Esc / 打开会话三种方式关闭;
  3. 对比度:正文对背景 ≥ 7:1,次要文字 ≥ 4.5:1(按相对亮度脚本计算);
  4. 无横向溢出:四档 document.documentElement.scrollWidth === clientWidth;
  5. 一致性:控件高只有 28/32 两档、列表行 30/34;圆角只出现 4 / 8 / 12 / 14 / 16 / 999 / 50%;
  6. 回归: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. 现状