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）。

设计规范速查（设计侧）

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

| 设计铁律 | 要点 | 详见 | |---|---|---| | 默认 Apple 浅色风格 | 简单大方：浅灰底白卡片、三级墨色 + 单一强调色（默认蓝）、1px 细描边轻投影、大圆角（卡片 18px）+ 胶囊按钮、毛玻璃导航/吸底、系统字体栈、数值 mono + tabular-nums 等宽对齐 | apple-style-ui.md | | 主题化 = 覆盖变量 | 换肤只改 CSS 变量（accent 变量族），组件零硬编码色值；图表色与页面同源、趋势涨跌色按目标地区约定（中国大陆红涨绿跌） | apple-style-ui.md §5-6 | | 长耗时承载（复杂问数必做） | 复杂问数几十秒~数分钟是常态：超时预算按「期望步数 × 单步耗时 × 2~3 倍」核算并随模型/问题复杂度配套（曾实测三连上调 90→180→300s）；超时 ≠ 失败（繁忙/空流/退化可自动重试 ≤1 次，网络断/HTTP 错误才报错）；每次请求带 AbortController 总闸防模型真卡死挂起 UI；等待期持续反馈、禁止空白冻结 | streaming-ui.md §5.3 | | 思考面板三面板（全品类默认标准形态） | 所有 AI 产品（智能体/数据分析问答/AI 对话/多步任务，不分品类）思考过程区一律三面板一体：①固定预设步骤横向走马灯（事件驱动推进）+ ②动态工具轨迹（进行中→完成✓/失败⚠️ + 摘要截断）+ ③思考原文默认折叠（details hidden，有增量才出现、原文只留尾部）——参考骨架照抄 streaming-ui.md §1.1.3（本技能唯一落地骨架；§1.1.2 仅为方法论/可选增强）。滚动架构 + 终态压缩 + summary sticky + 走马灯诚实锚定（§1.1.3 第4-6点，同必做）：思考面板随对话流滚动（与答案同一滚动容器，禁独立固定高度面板挤压正文）；流结束自动折叠为一行摘要条（✓ N 步骤 · M 次工具调用，点击可再展开，DOM 不销毁）让正文占满版面；展开原文后 summary sticky 常驻、收起按钮永远可点（滚出视区无法收起 = 真实踩坑）；走马灯终点锚定真实事件（尾格/全绿只允许 answer/final 事件点亮，防思考"预告句"提前走完）；首节前内容（患者信息/引言）禁被小节切分丢弃 | streaming-ui.md §1.1.3 | | 内容净化（不泄漏内部细节） | 思考 token 映射为预设干净步骤（如"正在分析…"），工具名/参数原文只留开发者视图 | §1.1 | | 步骤化提炼 + 折叠展开 | 思考过程提炼为步骤卡片时间线，每步默认折叠、点击展开 | §1.1.2 | | 布局区分（防视觉重复） | 固定步骤用横向排布、动作提炼用纵向，两种布局形态不混用 | §1 | | 智能滚动三态 | 流式增量区必做：自动跟随 / 手动滚动不拉回 / 回底恢复跟随 | §2 | | 打字机增量渲染 | 文本/思考增量逐字输出，非整段闪现 | §1 | | 多轮追问追加不覆盖 | 追问回答以新卡片追加，原内容不被清空重建；回答聚焦当前问题而非重吐完整模板 | §8 | | 对话入口：点选填入、可改再发 | 示例问题/快捷提问 chip 点击 = 完整问句填入输入框、可修改后手动发送；禁止一点即发（示例问题是说明书不是命令，防误触 + 教用户改参）；chip 双字段模型：按钮只显示简短标签（≤20 字，省版面）、完整问句只存 data 属性（如 data-q）、点击填入的是 data 里的完整句不是按钮文本；示例区布局位置（发送窗口下方常驻）见配套问数技能 08「产品壳层 UI 锚点 #2」，本技能只管点击交互 | input-area-ui.md | | 数据/图表页：全宽紧凑（全品类默认） | 凡含数据或图表呈现的页面默认：内容区全宽铺满（rail 窄栏 ≈104px + 内容左右 ≤24px，无 max-width 居中、无大留白）；多资产「数据管理中心」页 = 次级页签 + pane（工具栏 + 62vh 定高表格）三段式；条目型数据一律表格化；映射/术语对照表 = 表格默认只读、点「✏️ 编辑」进编辑态（+ 新增行/取消/保存/导出 CSV，取消 = 丢弃重载） | data-screen-ui.md | | 控件小号化（版面让给数据） | 示例/快捷 chip ≈11.5px 小号胶囊（3px 10px、虚线描边、短标签一行内、flow-wrap 总高克制）；次操作按钮 btn-sm/mini ≈12px（✏️ 编辑 / ⬇️ 导出 / 展开全表）；只有主 CTA 用大号主色。禁止大按钮/大卡示例、整句铺按钮挤占数据与对话版面 | data-screen-ui.md §4 | | 对话结果表格：不拉满·居中·单表 | AI 回答里的 markdown 表格：禁 width:100%（横向拉满消息宽）、按内容自然宽 + margin auto 居中 + 圆角卡片式（th 浅底/斑马纹/12.5px）；连续表行（表头+---分隔行+数据行）合并渲染为单个 <table>，禁止一行一表；一张表行连续输出（行间禁空行/禁插话，空行即拆表信号）、表与表之间空行分隔；真机断言：单块多行=恰好 1 个 table、宽度 < 消息区且居中 | streaming-ui.md §9 | | 历史面板回放：整条可点·富内容重渲染 | 历史列表每条记录整块为点击热区（hover 整条高亮），点整条即回放，禁止行尾「回放」小按钮；删除 ✕ 独立且 stopPropagation 不触发回放；快照存可重渲染富内容（answer markdown 原文含表格 + chart option/数据），回放 = markdown 走正文渲染（表格按 §9）+ 图表可见后 init 重建 + 追问链逐轮回放——表格在、图在、多轮在，禁止只回纯文本；列表纯文本摘要仅预览用；真机断言：回放表格数/图表数 = 原会话一致 | streaming-ui.md §10 | | error 事件不中断 | 单步过程性失败（Code execution failed 等）智能体可能重试继续，前端只记录、以是否到达 final_answer 为成功标准 | §5.2 | | 图表可见后初始化 | 图表容器隐藏时不 init，可见后再初始化（防退化为默认尺寸） | §4 |

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

测试关键前提

需要 puppeteer-core（在 node_modules 中）和本机 Chrome：
- Chrome 路径：优先用环境变量 CHROME_PATH 指定；未设置时按平台默认查找（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）
- 运行需设置：NODE_PATH=<node_modules路径>
本地开发服务需已启动（如 uvicorn）。
页面有登录时需提供测试账号。

工作流程

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 <user@example.com> --login-pass <password>

# 登录后点击某个按钮, 捕获指定 API 的请求/响应, 等待 8s
# （--click-selector / --watch-api 按目标系统实际元素与接口替换）
node ui_test.js <url> \
  --login-user <user@example.com> --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 常见问题速查表：

| 现象 | 排查方向 | |---|---| | [object Object] | 看 [RESP] 状态码；若 422 → 抓 [REQ-BODY] 是否空 → 对象展开丢键 / new Error(数组) | | 排版错乱/TBLSEP | 用 Node 单独跑渲染函数 + 真实 LLM 输出断言 | | 流式闪现 | 检查 SSE 事件粒度，thinking 只显示动画 | | 部署未生效 | md5 对比 + HTTP 抓取 + 服务重启（Python 必须重启进程）| | 数据偶尔丢失/消失 | 持久化类 bug（§12）：grep localStorage 全部读写点 → 判定单例还是实体集合 → 序列推演（A存→B存→A读）→ 无 clear/removeItem 即非"被清掉"，而是单键互斥覆盖 | | 地图/图表配色不生效（一片蓝/默认色） | ECharts map+visualMap 配色陷阱（§14）：数据项设了 visualMap:false 会令其 itemStyle.areaColor 失效、fallback 默认蓝 #5470c6 → 移除 visualMap:false，让 visualMap continuous 正常映射 + 动态 min/max；必须像素级采样（getImageData）验证实际渲染，不能只看 getOption 配置 | | 图表只有坐标轴没有数据点 | AI 生成 option 数据格式问题（§18.2）：模型/工具手拼 data 用 {x,y} 对象 → 坐标全 NaN 被绘制丢弃 → 前端 normalizeChartData 按系列类型归一（scatter→[x,y]、category-value→纯数字 y、pie→{name,value}）；先像素采样证实"确实没画"，再查 option 格式 | | 图表不渲染/空白/报 CHANGABLE_METHODS 崩溃 | AI 生成 option 三类问题（§18）：① 输出截断 JSON 残缺 → 按括号实际深度配平恢复（§18.1）；② data 空 → 特定图型崩溃（sankey 空 links 是崩溃特例，其余图型空 data 不崩）→ 判无效走"输出不完整"提示（§18.4）；③ 模型走错通用出图工具 → prompt 映射查表引导专用工具（§18.3）|

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

修复代码后重跑同一测试脚本，确认：
- [REQ-BODY] 非空
- DOM 快照断言通过（无 [object Object]、table 数量正确）
- 无 console/pageerror
截图人工确认视觉效果（保存于 ui-shots/）
修复后必做举一反三（§11）：同类问题是否在代码其他位置/场景同样存在（同函数不同分支、同模式不同位置、同数据不同入口、同 UI 不同视图），一并修复或列待办

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

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

第一类（元素层）：

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

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

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

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

修复后必须逐项检查：

| 类型 | 弱断言陷阱 | 强断言方式 | |---|---|---| | 布局/尺寸 | className.includes("...") | offsetWidth/Height ≈ window.innerWidth/Height | | 结构渲染 | innerText.includes("...") | querySelectorAll("table").length >= N | | 截断边界 | 用完整输入测 | 用真实截断数据测（slice/cutoff） | | 过程态 | 只测最终态 | 流式/异步多次采样断言渐进增长 | | 可见性（内容） | 元素存在 | scrollHeight <= clientHeight 无裁剪 | | 可见性（显示/隐藏） | 只看 el.hidden 属性（假阳性，某项目漏检教训） | offsetParent === null 或 getComputedStyle().display === 'none'（.btn{display:inline-flex} 会覆盖 hidden，属性 true 但视觉仍显示；代码层用全局 [hidden]{display:none!important} 兜底） | | Markdown 标题 | 渲染器支持 ### 就认为 OK | 解析必须逐行扫描（标题后紧跟内容无空行时按块判断会吞掉标题行 → 原样输出），单测覆盖"标题+无空行内容"输入 | | 弹性布局 | 单点内容量 | 长/短内容各测，断言折叠/展开 | | 前后端契约 | 固定 mock 数据 | 真实后端输出全链路，断言新映射生效 | | 嵌套滚动 | 操作外层容器 | 监听/赋值/测试指向同一可滚动元素，先验证 scrollHeight > clientHeight | | 滚动三态（通用必测） | 只做自动跟随 / 只测"保持 0" | 实现三态（跟随/不拉回/恢复）+ 三态全测，断言真实可滚动元素 | | 图表初始化时机 | 只查 DOM 存在 | 渲染元素实际宽度 = 容器宽度（防隐藏容器内 init 退化为默认尺寸，如 ECharts 100px） | | 字体/尺寸一致性（同页图表） | 只查某卡正常 | 断言 legend/axis/label fontSize 与同页其他图一致（如统一 11）、关键卡片 offsetHeight 一致（如统一 300，不因 sm 类残留 240） | | 图表配色/视觉映射 | 只看 getOption() 配置（配置暖色 ≠ 渲染暖色，§14 教训） | canvas.getContext('2d').getImageData(x,y) 采样像素，断言是目标色而非默认蓝 #5470c6；hover 高亮用 dispatchAction({type:'highlight'}) 后采样验证 | | 可点击 | el 存在 | getBoundingClientRect() 在视口内 | | 网络成功 | resp.ok | 同时检查 Content-Type 和可解析 body |

专项测试场景

场景 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）：

不泄漏工具调用独白：无工具名/参数原文（如 analyze_image(、image_urls_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 → 后续内容到达恢复跟随到底

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

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

page.on('pageerror') + page.on('console') 收集错误
page.on('request'/'response') 按 URL 片段过滤捕获 API
page.evaluate() 执行交互与 DOM 断言
page.screenshot() 保存证据
输出结构化结果（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/ui_test.js — 通用测试模板（登录/点击/API 捕获/DOM 断言/截图，命令行参数化；--three-state <selector> 内置滚动三态验收执行器——等可滚 ≥80px → 逐态断言，配合 slow_sse.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 执行；正常使用本技能无需阅读，仅在排查/修订/复查时对照使用

智能体UI设计与验证技能（配套NEXENT集成技能）

AI 应用 UI 设计与测试

Overview

目录

设计规范速查（设计侧）

测试关键前提

工作流程

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

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

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

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

专项测试场景

场景 A: 弹窗/模态框

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

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

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

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

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

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

自定义测试脚本

Resources

智能体UI设计与验证技能（配套NEXENT集成技能）

AI 应用 UI 设计与测试

Overview

目录

设计规范速查（设计侧）

测试关键前提

工作流程

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

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

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

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

专项测试场景

场景 A: 弹窗/模态框

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

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

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

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

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

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

自定义测试脚本

Resources

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