AI 应用 UI 设计与测试

配套技能：Nexent 智能体平台集成（北向 API / SSE / MCP）→ nexent-integration；技能质量检查 → skill-qc。

Overview

本技能覆盖 AI 应用（智能体/数据分析问答/AI 对话）的前端 UI 设计规范与真实浏览器测试两个维度：

• 设计侧：AI 应用界面四类设计规范——①默认视觉基线：简单大方的 Apple 浅色风格 design token（灰底白卡、胶囊按钮、毛玻璃、系统字体栈、三级墨色 + 单一强调色，主题化走 CSS 变量覆盖，详见 references/apple-style-ui.md）；②流式输出呈现：思考面板三面板呈现（全品类默认，照抄骨架 §1.1.3）、内容净化、步骤化提炼 + 折叠展开、布局区分、智能滚动三态、打字机、多轮追问追加不覆盖（详见 references/streaming-ui.md）；③对话入口交互：示例问题/快捷提问 chip 双字段模型（按钮短标签 + 完整句存 data 属性）、点选填入输入框、可改后发送，禁止一点即发（详见 references/input-area-ui.md）；④数据与图表呈现界面（全品类默认，凡含数据/图表的页面）：内容全宽不留白、数据管理多资产页 = 次级页签 + 工具栏 + 定高表格、条目型数据一律表格化、映射/术语对照表默认只读点编辑、示例与次操作按钮小号化把版面让给数据与对话（详见 references/data-screen-ui.md）。
• 测试侧：用 puppeteer-core 启动本机 Chrome 无头浏览器，真实打开页面复现 UI 问题。不依赖用户描述猜测根因，而是捕获真实请求/响应/控制台/DOM 数据后定位问题，修复后同一脚本复测验证（详见 bug 根因速查 references/bug-patterns.md）。

目录

• [设计规范速查（设计侧）](#设计规范速查设计侧)
• [测试关键前提](#测试关键前提)
• [工作流程](#工作流程)

- [Step 1: 用模板脚本快速复现](#step-1-用模板脚本快速复现) - [Step 2: 分析捕获数据定位根因](#step-2-分析捕获数据定位根因) - [Step 3: 修复 + 同一脚本复测](#step-3-修复--同一脚本复测) - [Step 4: 强断言检查清单（防假阳性）](#step-4-强断言检查清单防假阳性)

• [专项测试场景](#专项测试场景)
• [自定义测试脚本](#自定义测试脚本)
• [Resources](#resources)

设计规范速查（设计侧）

设计侧四类规范速查：① 默认视觉基线（Apple 浅色风格）、② 流式输出呈现、③ 对话入口交互、④ 数据与图表呈现界面（全品类默认）。完整规范见对应 references。视觉基线铁律：

设计侧是"呈现规范"：先按上表设计/评审界面，再用下方测试流程真实浏览器验证。

测试关键前提

1. 需要 puppeteer-core（在 node_modules 中）和本机 Chrome：

- Chrome 路径：优先用环境变量 CHROMEPATH 指定；未设置时按平台默认查找 （Windows C:/Program Files/Google/Chrome/Application/chrome.exe 或 Program Files (x86) 下同名路径； macOS /Applications/Google Chrome.app/Contents/MacOS/Google Chrome；Linux /usr/bin/google-chrome） - 运行需设置：NODEPATH=<node_modules路径>

1. 本地开发服务需已启动（如 uvicorn）。
2. 页面有登录时需提供测试账号。

工作流程

Step 1: 用模板脚本快速复现

scripts/ui_test.js 是通用模板，覆盖核心捕获能力（console/pageerror、API 请求体与响应、DOM 快照、截图）：

# 基础: 打开页面, 等待 5s, 截图（<url> 换成你的本地服务地址）
NODE_PATH=.../node_modules node ui_test.js <url> --wait-ms 5000

# 带登录（凭据用测试账号，可通过参数传入）
node ui_test.js <url> --login-user <[email protected]> --login-pass <password>

# 登录后点击某个按钮, 捕获指定 API 的请求/响应, 等待 8s
# （--click-selector / --watch-api 按目标系统实际元素与接口替换）
node ui_test.js <url> \
  --login-user <[email protected]> --login-pass <password> \
  --click-selector "<打开弹窗的按钮选择器>" \
  --watch-api "<要监听的接口路径片段>" \
  --wait-ms 8000

模板会输出：[REQ-BODY]（重点看 postData 是否为空！）、[RESP] 状态码、DOM 快照（tables/modals/是否含 [object Object]）、截图路径、控制台错误。

Step 2: 分析捕获数据定位根因

对照 references/bug-patterns.md 常见问题速查表：

Step 3: 修复 + 同一脚本复测

• 修复代码后重跑同一测试脚本，确认：

- [REQ-BODY] 非空 - DOM 快照断言通过（无 [object Object]、table 数量正确） - 无 console/pageerror

• 截图人工确认视觉效果（保存于 ui-shots/）
• 修复后必做举一反三（§11）：同类问题是否在代码其他位置/场景同样存在（同函数不同分支、同模式不同位置、同数据不同入口、同 UI 不同视图），一并修复或列待办

Step 4: 强断言检查清单（防假阳性）

测试通过 ≠ 功能正确。三类陷阱（详见 references/bug-patterns.md §8、§9、§10）：

第一类（元素层）：

1. className ≠ 布局：断言 offsetWidth/Height 真实尺寸，不只断言 className
2. innerText ≠ DOM 结构：断言 querySelectorAll("table").length >= 1，不只断言"innerText 包含"
3. 测试场景 ≠ 真实路径：用"实际传递给被测代码"的输入（如 slice(0,8) 截断后的文本），不只测完整数据

第二类（体验层，更隐蔽）：

1. 只测最终态漏测过程态：流式/异步/动画功能必须多次采样断言渐进变化（15s × 6），不能只等 100s 测最终
2. 元素存在 ≠ 用户看得到：断言 scrollHeight <= clientHeight（无 overflow 裁剪），关键结论在视口内
3. 弹性布局只测单点：用长/短两种内容量各测一遍，断言折叠/展开行为
4. 前后端契约不同步：改后端提示词后必须用真实输出全链路验证，断言新小节映射生效

第三类（滚动/交互层）：

1. 嵌套滚动容器错位：监听、赋值、测试必须都指向真正可滚动的元素（CSS 有 overflow-y:auto 且内容溢出）；外层 overflow:hidden 的 scrollTop 恒为 0，赋值无效
2. 测试操作了错误的元素：若被测元素 scrollTop 恒 0，任何"保持 0"断言都是假阳性——断言前先验证 scrollHeight > clientHeight（元素确实可滚动、内容确实溢出）
3. 滚动三态（通用必测项）：流式增量渲染区（思考区/日志区/聊天流/流式正文）只要做了自动跟随，实现必做三态——自动跟随 / 手动滚动后不拉回 / 滚回底部恢复跟随；只做自动跟随视为未完成，三态都要测（详见 streaming-ui.md §2）

通用铁律：断言目标必须是用户实际感知的体验（看、点、读、确认结果），而非"代码做了什么"。

修复后必须逐项检查：

专项测试场景

场景 A: 弹窗/模态框

node ui_test.js <url> --login-user U --login-pass P \
  --click-selector "#btn-open-modal" --wait-ms 3000
# 断言: modals >= 1, 弹窗内无 [object Object], 截图

场景 B: SSE 流式渲染（AI 对话等）

node ui_test.js <url> --login-user U --login-pass P \
  --click-selector "<触发流式的按钮>" --watch-api "<流式接口路径片段>" --wait-ms 100000
# 断言: REQ-BODY 非空(关键!); 完成后表格数>0; 无 TBLSEP/###/[object Object]
# 注: 流式接口响应体无法用 resp.text() 读取(已消费), 依赖截图+DOM 验证

场景 C: 页面功能回归（列表/表单/跳转）

node ui_test.js <url> --click-selector "nav a" --click-selector "#search-input" --wait-ms 3000

场景 D: 多轮追问/对话（追加不覆盖，防"问 A 答整份报告"）

首轮完成后，在追问框发新问题，断言（详见 streaming-ui.md §8）：

• 原报告卡片数不变（未被清空重建）
• 追问回复以新卡片追加，且非完整模板（卡片数/小节数/长度显著小于首轮）
• 用户气泡包含问题文本；本轮状态条结束态正常

// 追问前记录 → 追问后断言（示例，以你的实现为准）
const before = await page.$$eval('#cardsWrap .card', els => els.length);   // 首轮卡片数
await page.type('#followInput', '你的追问');
await page.click('#followBtn');
// 等待本轮状态完成 → 断言 before 不变、新增卡片 < 首轮、气泡文本匹配

场景 E: 思考面板内容净化（用户 facing 界面，防工具独白泄漏）

触发流式后，mid_stream 阶段断言思考区（用户视图）DOM（详见 streaming-ui.md §1.1.1）：

• 不泄漏工具调用独白：无工具名/参数原文（如 analyzeimage(、imageurls_list=、S3 URL，以你对接的平台/工具为准）
• 只显示预设干净步骤文案（如"正在分析…""正在检索…"）；未知片段显示通用兜底文案而非原文
• 若实现了开发者视图开关：切到原始视图应能看到 thinking 原文累积（对照确认净化仅在用户视图生效）

// 示例断言：思考区文本不含技术细节原文（以你的实现为准）
const thinkText = await page.$eval('#think-body', el => el.textContent);
if (thinkText.includes('analyze_image(') || thinkText.includes('image_urls_list=')) {
  throw new Error('思考面板泄漏工具调用独白');
}

场景 F: 流式滚动三态（通用必测项，适用所有流式增量渲染区）

任何"内容持续增长、自动跟随底部"的滚动区（思考区/日志区/聊天消息流/流式正文）都必须实现并验证三态，缺一不可（实现骨架与断言详见 streaming-ui.md §2）：

• 自动跟随：内容溢出后 scrollTop 接近底部（scrollHeight > clientHeight 且距底 < 动态阈值 min(40,max(8,总量×0.08))——阈值相对化，禁止无条件常量，短容器固定阈值会误判中段为近底把用户拉回，2026-09 实证）
• 手动不拉回：滚到离底部足够远（中间位须距底 > 2×阈值）+ dispatch scroll → 后续内容到达 scrollTop 保持不动（不被拽回）
• 回底恢复：滚回底部 + dispatch scroll → 后续内容到达恢复跟随到底

受控验收工具链（一次成功的关键——先练习台、再产品页、真实流冒烟）：

1. node scripts/slowsse.js 8129 → 起受控慢流源：/sse?events=N&interval=MS&tool=1&text=120（thinking 条数与节奏可控，可中段插 tool/executionlogs）；/demo 为三态练习台（渲染写法 = streaming-ui §2 骨架，可直接照抄）
2. node ui_test.js <练习台或产品页URL> --three-state <可滚动容器selector> → 模板内置三态验收执行器：等可滚距离 ≥80px → 逐态断言（不足自动等待/报内容不足，勿在短内容上硬测）
3. 真实模型流只做最终冒烟——thinking 量随机导致可滚总量忽大忽小，过程态验收必须在受控流上做（内容量/节奏可控、可重复）

// 手写三态断言骨架（以你的实现为准；先验证可滚距离 ≥80px，防"保持 0"假阳性；中间位远离阈值带）
await page.waitForFunction(() => {
  const c = document.querySelector('#stream-area');   // 换成你的流式区容器
  return c.scrollHeight - c.clientHeight >= 80;       // 可滚距离足够才测（不足先注入/等待更多内容）
});
// 态1 自动跟随 → 态2 手动不拉回 → 态3 回底恢复：逐态断言（断言式见 streaming-ui.md §2 表）

场景 G: 数据分析问答/AI 对话 重试兜底与图表渲染（覆盖"模型退化 final_answer"假阳性）

数据分析问答类流式功能，除场景 B 的"最终出图表"断言外，还须验证重试兜底不会无限循环且退化场景被兜底：

• 重试有上限（防无限循环铁律）：连续制造"流结束无 final_answer 也无 error"的退化响应（mock 或弱模型触发），断言 askCalls <= 2（首次 + 至多 1 次重试）；第 2 次仍失败即停止显示"未获得有效回答"，不再发起第 3 次请求——调用方传入 retryLeft 逐次递减，retryLeft=0 停，绝不递归 / while 无限重试
• 图表真实渲染：断言生成 <canvas>（ECharts/Chart.js）或 <svg>（D3）存在 + 实际宽度 = 容器宽度（防隐藏容器 init 退化）；散点/柱状/堆叠等图类型按数据正确出图
• legend 居中/明亮 + 字体一致：断言图例 left:"center"（居中）且色值非灰暗；图表 legend/axis/label 的 fontSize 与同页其他图表一致（如统一 11，避免某卡因 sm 类被压成 240px 高度、fontSize 10 显小）
• 卡片尺寸一致性：断言关键卡片 offsetHeight 与同页其他卡片一致（如统一 300px，不因历史 sm 类残留 240px）

// 伪代码：退化重试上限断言（以你的实现为准）
const calls = await page.evaluate(() => window.__askCalls);
if (calls > 2) throw new Error('重试超过上限，疑似无限循环');

自定义测试脚本

模板不满足时（如需要多步交互、断言特定 DOM），直接写一次性 puppeteer 脚本（参考 scripts/ui_test.js 结构）：

1. page.on('pageerror') + page.on('console') 收集错误
2. page.on('request'/'response') 按 URL 片段过滤捕获 API
3. page.evaluate() 执行交互与 DOM 断言
4. page.screenshot() 保存证据
5. 输出结构化结果（JSON 格式便于解析）

关键 API 速记：

• page.type(sel, text) 输入
• page.click(sel) / page.evaluate(s => document.querySelector(s).click()) 点击
• page.$eval(sel, el => el.outerHTML) 抓 HTML
• page.evaluate(() => document.body.innerText) 抓文本
• page.screenshot({path}) 截图

Resources

• scripts/uitest.js — 通用测试模板（登录/点击/API 捕获/DOM 断言/截图，命令行参数化；--three-state <selector> 内置滚动三态验收执行器——等可滚 ≥80px → 逐态断言，配合 slowsse.js 受控慢流使用）
• scripts/slow_sse.js — 受控慢流 SSE 源（零依赖）：/sse?events=N&interval=MS&tool=1&text=120 提供内容量与节奏可控的 thinking/tool/final 事件流，/demo 三态练习台（渲染写法 = streaming-ui §2 骨架）；三态等过程态功能验收的受控测试源——真实模型流 thinking 量随机不可控，过程态验收勿直接在真实流上碰运气（streaming-ui.md §2 / bug-patterns §10.4）
• references/apple-style-ui.md — 默认视觉基线：Apple 浅色风格 design token（简单大方）（取向三纪律：内容优先 + 单一强调色 + 质感统一；:root 变量全表：灰底/白卡/三级墨色/细线轻投影/默认蓝强调/语义色/圆角系/系统字体栈与 mono；排版层级表；组件速查：卡片 18px、按钮 980px 胶囊、毛玻璃导航与吸底、弹窗蒙层 blur、表格 sticky 表头、输入框 focus 光环、对话气泡、状态徽标、细滚动条、顶部加载条；数据可视化同源配色 + 趋势涨跌色按地区约定（中国大陆红涨绿跌）；主题化=只覆盖 accent 变量族换肤、组件零硬编码色值、图表与页面同源；验收走像素采样（配置≠渲染）；反模式清单与自检清单；范本为某运营数据看板实际落地 style.css 的通用化提炼）
• references/streaming-ui.md — SSE 流式输出前端呈现与验证（三层呈现架构 + 打字机 / 智能滚动三态（流式区通用必测：实现必做+验收必测） / 关闭弹窗不中断与重开恢复（DOM 解耦）/ 图表容器可见后初始化 / 思考面板净化双视图（用户净化 + 开发者原始开关，§1.1） / 思考过程步骤化 + 折叠展开（提炼呈现：步骤卡片时间线 + 每步详情默认折叠、点击展开，§1.1.2） / 布局区分（固定预设步骤走马灯横向进度条 + 动作提炼纵向时间线，防视觉重复，§1.1.2 第5点） / §1.1.3 三面板全品类标准形态（照抄骨架：固定步骤横向走马灯 + 动态工具轨迹 + 思考原文默认折叠 details hidden——所有 AI 产品思考过程区默认即此形态，本技能唯一落地骨架；配套问数技能 08 壳层锚点 #3 引用；第4-5点+第6点 滚动架构铁律=随对话流滚动禁固定面板、终态自动压缩=摘要条省版面、summary sticky=收起常驻可点、走马灯终点锚定 answer 事件（answer 前禁全绿）、首节前内容禁丢弃——真实踩坑） / 防超长 DOM（原文只留尾部 N 字符、工具结果摘要截断 + 失败⚠️前缀，§1.1.2 第6-7点） / error 事件不中断（§5.2：error 可能是过程性失败、智能体重试后继续，前端只记录不中断、以是否到达 final_answer 为成功标准，禁止一收 error 就中断——真实踩坑） / 多轮追问追加不覆盖（§8） / 对话结果表格渲染（§9：不拉满 width:100%、内容宽居中、连续表行合并单 table、禁一行一表、行连续输出协议） / 历史面板与回放（§10：整条可点即回放无行内小按钮、快照存可重渲染富内容含表格 markdown 与图表配置、回放富渲染表格图在多轮在、删除 ✕ 独立） / 多会话 Tab 页面内并行会话（§11：per-session 状态隔离互不占锁、切走=隐藏不销毁、iframe 内"新会话"禁弹窗开新 Tab、历史回放=新开 Tab、真机逐条验收断言清单） / 真实浏览器渲染验证铁律 / 联调期前端资源缓存失效（?v= + no-cache，§5.1） / 验证清单；本文件只覆盖"流到了前端怎么渲染、怎么验证"，接口/协议层（事件类型、会话 id、请求体构造）见你所对接平台的集成技能或接口文档；供对接任意 SSE 流式接口复用）
• references/input-area-ui.md — 对话入口交互：示例问题/快捷提问「点选填入」范式（chip 双字段模型：按钮只显短标签 ≤20 字、完整问句存 data-q，禁止完整句铺上按钮——示例区是入口不是读题区；点击 → 完整问句填入输入框、可修改后手动发送，填入的是 data 完整句不是按钮文本，禁止一点即发——示例问题是说明书不是命令；受控组件赋值坑：须走框架受控路径 + 触发 input 事件，否则发送按钮 disabled 不解除/提交旧值；光标置文末便于追加限定；输入框已有内容再点 = 覆盖不拼接；真机断言三连：input 有值 / 无新网络请求 / 请求体 = 编辑后文本；与问数历史「回放 + 可追问」同属「点击不直接执行、给编辑机会」交互原则家族；内容组织（10 问覆盖/验收基线）归问数技能 08 引导 A，本文件只管交互行为）
• references/data-screen-ui.md — 数据与图表呈现界面（全品类默认：凡含数据/图表的页面）：① 内容区全宽铺满（rail 窄栏 + 左右 ≤24px，禁居中窄卡/大留白）；② 多资产「数据管理中心」页 = 次级页签 + 工具栏 + 62vh 定高表格三段式（版面给数据本体）；③ 条目型数据一律表格化，映射/术语/对照表默认只读、点「✏️ 编辑」进编辑态（+ 新增行/取消/保存/导出 CSV，取消 = 丢弃未保存）；④ 控件小号化：示例 chip ≈11.5px 小胶囊、次操作 btn-sm/mini ≈12px、主 CTA 才大号；⑤ 图表卡片紧凑 grid + card-tag 小字说明 + 同源配色。范本为运营数据平台数据管理区/看板区/问数区实际落地 style.css/index.html 通用化提炼（含实测数值）；问数对话区专属锚点归配套问数技能 08，本文件只管"数据与图表页"通用骨架
• references/bug-patterns.md — UI 常见问题根因速查 + 反思沉淀（§1-7 速查：[object Object]/TBLSEP/###（§3：标题后紧跟无空行内容时必须逐行扫描，块级判断会吞标题行）/流式闪现/部署未生效/排查命令/方法论核心；§8-12 反思：三类假阳性、四类隐蔽假阳性（§9.2.1 hidden 属性≠视觉隐藏，须用 offsetParent/getComputedStyle 断言，禁止只看 el.hidden——真实漏检教训）、嵌套滚动容器错位、举一反三同类排查、持久化类 bug 单键互斥覆盖；§13 图表隐藏容器内 init 退化为默认尺寸（与 streaming-ui.md §4 同源）；§14 ECharts map+visualMap 配色陷阱：数据项 visualMap:false 令 itemStyle.areaColor 失效、fallback 默认蓝 #5470c6（配置≠渲染，必须像素级采样验证，不能只看 getOption）；§15 ECharts map 交互禁用三层：silent 只禁事件、emphasis 高亮需单独 disabled、系列级会误伤须数据项级；§16 百分比尺寸图表：多图对齐依赖容器等宽（复用不对称 grid 类致图大小不一）；§17 CSS transition 阻塞卡中间态：元素"空白/消失"假象；§18 AI 生成可视化（图表 option）数据层兜底：截断 JSON 按括号实际深度配平恢复（固定补 N 个括号只恢复少数用例）+ {x,y} 对象按系列类型归一（scatter→[x,y]、category-value→纯数字 y 非 [y] 数组、pie→{name,value}，8 用例真浏览器回归）+ sankey 空 links 崩溃特例防御（其余图型空 data 不崩）+ 模型选错通用出图工具排查（先查 tools[].description 误导 → prompt 映射查表引导专用工具，枚举清单必然漏）+ 像素采样验证"有轴无点"（配置≠渲染）；§19 会话状态重构静默 ReferenceError（函数签名加 per-session 参数、调用处未传参 + catch(e){} 吞异常 → 首轮全"未获得有效回答"且 console 零报错——排查先全项目扫静默 catch + 签名/调用点对表）；§20 多会话下测试全局选择器误导（.card[data-role=done] 命中他 Tab 旧卡 → 等待提前返回/误判产品丢数据，完成等待必须限定"当前可见 pane 新增卡"））
• references/90-qc-ground-truth.md — 【质控专用，非使用教程】：领域事实清单/复查清单（19 条核心结论 + 已发现问题记录），本技能逻辑复查的领域锚点；质控方法论详见独立技能 skill-qc（L0~L4），质控时加载 skill-qc 执行；正常使用本技能无需阅读，仅在排查/修订/复查时对照使用