frontend-walkthrough

对已实现的前端页面做真实操作走查:遍历状态矩阵与交互路径、检查反馈与容错、体检加载性能,产出带证据的优化与补充清单。触发:"前端走查"、"体验一下这个页面"、"点一遍看看"、"前端页面有什么问题"。

SKILL.md

GitHub

前端体验走查(frontend-walkthrough)

概述(AI 说明层)

目的:解决"页面能打开、功能都齐全,但用户用起来到处卡手"的盲区。把"反复点前端页面、看显示效果、试交互、挑问题"这件高频工作,变成 AI 可执行的真实操作走查:像真人用户一样遍历页面与状态,逐项判断体验是否合格,产出带证据的发现清单。

功能:

  • 取证档位自适应:先探测浏览器实操能力(A 可实操 / B 半实操 / C 纯静态)并写入报告,能力不足时明确降级,不假装体验过
  • 白盒规划 + 黑盒体验:先读前端代码穷举入口、状态与分支(规划"要点什么"),再像真人一样操作观察(判据不来自代码)
  • 状态矩阵遍历:逐页覆盖默认 / 加载 / 空 / 错误 / 无权限 / 长文本 / 大数据量 / 窄屏 八态
  • 四类发现合并为一张清单:体验优化 / 实现修复 / 加载性能 / 体验增强建议
  • 双视角研判:用户视角(任务场景轴)+ 产品经理视角(Kano + 价值×成本,口径复用 product-manager)
  • 加载性能做到体检级:发现问题 + 定位方向 + 给证据;深入优化方案交 performance-analysis

使用场景:

  • 用户说"帮我走查一下前端"、"体验一下这个页面"、"点一遍看看有什么问题"
  • 产品已有前端页面,想系统性找出体验缺陷与可优化点
  • 上线前 / 改版后想知道"用户会在哪里卡住"
  • 用户说"前端体验审计"、"看看前端实现有什么问题"

定位

已有前端页面 → frontend-walkthrough(本 skill)→ 体验发现清单(一张)
                                                    ↓
                     实施:request-guard → code-review
                     产品级功能缺失:product-manager M3
                     深入性能优化:performance-analysis
  • 输入:可运行的前端应用(URL / 服务地址 / 测试账号)或源码 + 画面材料
  • 输出:一份前端走查报告(默认对话输出;用户要求落盘时写 .walkthrough/{slug}-{YYYYMMDD}.md)
  • 边界:只判断不改码;性能只到体检级;视觉只报"影响可用性"的问题

与邻接 skill 的分工(防重叠)

邻接 skill 它回答的问题 本 skill 回答的问题
product-manager M2 / M4 产品视角:下一版该做什么、界面观感好不好 前端实现视角:做出来的东西,用户用起来卡在哪
e2e-testing(动态体验验证) 功能对不对(需求规格驱动的黑盒验收,须 e2e 前置) 好不好用(用户标准驱动的体验体检,不要求 e2e 前置)
code-review 变更 diff 的代码质量(含命名 / 架构 / 设计模式) 存量前端代码的体验相关实现(不点评命名与设计模式)
performance-analysis 后端接口 / 链路性能与优化方案 前端加载性能的问题发现与定位方向
ui-designer / interaction-design 从零设计视觉方案 / 交互逻辑 审查已实现的页面体验
acceptance-verify 这一版达标没有(按验收指标逐条判) 下一版该优化什么

视觉边界(刻意的):本 skill 只报影响可用性的显示问题(状态不可见、文案溢出截断、数据格式化错误、错位导致误读、对比度不足、点击区域过小、窄屏折行错乱);纯美术观感(配色品味、精致度、动效美感)交 product-manager M4 或 ui-designer。

何时不使用本 skill:只想审一段代码变更 → code-review;只想验功能达标 → acceptance-verify;只想跑通链路 → e2e-testing;只想知道后端为什么慢 → performance-analysis;要重新设计界面 → ui-designer。


核心原则

  1. 走查是"操作",不是"看图":截图只作证据,结论必须来自真实操作路径;只截图不点,等于没走查
  2. 档位诚实:先探测取证能力再动手;拿不到画面 / 起不了服务就降级,并在报告头声明——禁止假装体验过
  3. 读代码为规划,不为判据:代码用于穷举入口与状态(防漏点),体验好坏由操作观察决定;"代码里有 loading 分支" ≠ 用户看得到(实现类"有没有做"的判定例外,见「取证档位」)
  4. 人性化必须锚定可检验场景:禁止"用户可能会困惑"这类空泛揣测;每条发现要能回答——哪类用户、在什么任务下、遇到什么现象
  5. 证据三级制:🟢 实操实测 / 代码实证 | 🟡 静态可证(结构 / 配置间接推断)| 🔴 推断。🔴 只进「待确认清单」且必须配验证方法
  6. 一张清单:体验优化 / 实现修复 / 加载性能 / 体验增强建议四类合并输出,用「来源」列区分,禁止多张打架
  7. 只判断不改码:输出清单与建议方向;实施交 request-guard → code-review
  8. 排除项也值钱:明确写"经走查排除:XX 维度无问题(依据:{证据})",避免用户重复排查
  9. 有意取舍不当缺陷:MVP 有意省略的(未做暗色、未做 i18n、未做批量导入)标"可能是有意取舍,需确认"
  10. 涉及真实副作用先确认:走查中的下单 / 删除 / 支付 / 发通知等操作,须在测试环境进行,环境不明时先问用户

取证档位(先探测,后动手)

档 条件 能做什么 证据上限
A 可实操 有浏览器工具(use_skill("agent-browser") / use_skill("playwright-cli"))且服务能起 真实点击遍历、截图、读控制台与网络、采集性能指标(须工具支持脚本求值,否则走降级链) 🟢
B 半实操 页面能打开但 AI 拿不到画面(只能开预览)或无法操作 读代码静态推演(🟡)+ 给出肉眼检查清单请用户按项提供截图 / 录屏;用户提供的画面可作 🟢 证据 🟢(用户画面)/ 🟡(静态)
C 纯静态 服务起不来 / 无浏览器 / 无任何画面 只读前端代码 实现类判定 🟢;体验类结论强制 🔴

判定类型 × 手段(决定单条结论能标多高):

判定类型 例子 代码直读 实操
符合性:有没有做 "有没有空态""提交有没有防重复""错误文案带原因吗" 🟢 首选 🟢
体验性:顺不顺、够不够 "反馈及时吗""几步能完成""能恢复吗" 🟡 只能证"分支存在" 🟢
视觉性:好不好看 对齐、层级、美观 🔴 不可用(明确色值除外) 🟢

C 档不等于没价值:实现类问题(状态缺失、错误处理缺口、无障碍属性缺失、性能反模式)代码直读即 🟢 一手证据;被禁止的只是"用代码推断体验"。 代码直读证什么:可证"写法存在 / 缺失"(有没有 loading 分支、有没有 label),不证"运行时行为正确"(分支会不会被走到、提示会不会被条件挡住)——涉及运行时行为的结论标 [需运行验证]。 能力探测是硬步骤:不得跳过探测直接宣称"我体验过了";降级声明必须写进报告头。


工作流

阶段 0 范围锁定与档位探测 → 阶段 1 前端代码直读(白盒规划 + 实现审查)
→ 阶段 2 真实操作走查(黑盒体验)→ 阶段 3 加载性能体检
→ 阶段 4 双视角研判与优先级 → 阶段 5 走查报告

页面多时分批:每批 ≤8 个页面/功能域,出一批计划 → 执行 → 小结 → 再走下一批,避免一次性铺开失控。

阶段 0:范围锁定与档位探测

  1. 锁定对象:页面 / 入口清单、角色(普通用户 / 管理员)、目标功能域;范围不清先问一句("走查整站还是某个模块?")
  2. 探测档位(A / B / C),写入报告头
  3. 备环境:服务地址、测试账号、数据准备(空态 / 大数据量 / 长文本是否需要构造)
  4. 确认副作用边界:涉及真实写操作的,先与用户确认测试环境可用

阶段 1:前端代码直读(白盒规划 + 实现审查)

两个目的:规划"要点什么"(防漏),以及直接判定实现类问题(符合性 🟢)。

  1. 入口穷举:从路由表 / 页面组件导出页面清单逐项登记(防只查首页)
    • 有索引时先查:仓库已建 .fe-index/ → use_skill("index-lookup") 读 INDEX.md 命中前端条目,直接拿 pages/*.md(页面清单 + 各页接口/组件)与 apis/*.md(接口反查),省一次全站搜索;无索引 / 未命中 / 过期 → 按原流程,不阻塞
  2. 状态矩阵盘点:每页八态在代码里的实现情况——默认 / 加载 / 空 / 错误 / 无权限 / 长文本 / 大数据量 / 窄屏
  3. 交互实现检查(体验相关,不点评命名与架构):
    • 表单:校验时机(失焦 vs 只能提交后才发现)、错误是否定位到字段、必填标识
    • 提交:loading 态、防重复提交、成功反馈、失败反馈(原因 + 下一步)
    • 危险操作:二次确认、可否撤销
    • 长任务:进度反馈、可中断
    • 列表:分页 / 虚拟滚动、批量操作、筛选与翻页状态保持
    • 中断恢复:刷新 / 返回后状态是否保留
    • 默认值与记忆:常用值是否预填、上次选择是否记住
  4. 可用性实现初筛:键盘可达(Tab 顺序 / Esc 关闭 / Enter 提交)、语义标签与 label 关联、焦点管理(弹窗开 / 关)、点击区域尺寸、对比度(有明确色值时可判)
  5. 性能反模式初筛:首屏阻塞资源、未懒加载 / 未代码分割、图片未优化、请求瀑布(串行)、重复请求与无缓存、长列表未虚拟化、输入无防抖、超大依赖
  6. 产出走查计划:要点的路径(正面 / 边界 / 负面)+ 每步的观察点 → 交阶段 2 执行

阶段 1 的实现类问题可即时成结论(🟢);但"体验好不好"的判定必须留给阶段 2。 详细检查表见 reference.md 第一、二节。

阶段 2:真实操作走查(黑盒体验)

操作纪律:像真人一样点击 / 输入 / 等待,边操作边记录;不用代码实现解释观察结果——用户看不到内部处理,只看得到结果。

  1. 按计划遍历:逐页触发状态矩阵八态(怎么造出加载 / 空 / 错误态见 reference.md 第二节)
  2. 三类路径:正面(正常用)/边界(0 条、10000 条、超长文本、特殊字符)/负面(故意误操作)
  3. 场景轴走查(用户视角的核心,替代空泛的"用户体验"):
场景轴 问句
新用户首次 找得到入口吗?知道下一步吗?空态有引导吗?术语不看文档能懂吗?
高频老用户 几步完成?重复输入多吗?有批量 / 快捷键 / 记忆吗?
误操作 能撤销吗?确认合理吗?错误提示说人话吗?
中断 / 异常 刷新能恢复吗?断网怎么办?超时怎么办?重复提交会怎样?
极端数据 超长文本怎么显示?空值 / null / undefined 怎么显示?
  1. 每条发现记录:现象 → 复现步骤 → 影响谁(哪类用户 / 哪个任务)→ 证据(截图 / file:line)→ 建议方向

阶段 3:加载性能体检(体检级)

只回答"有没有问题、在哪",不给优化方案(深入交 performance-analysis)。

  1. 有实操能力时采集:首屏时间、LCP / CLS / INP、TTFB(浏览器 Performance API / 性能面板 / Lighthouse)
  2. 资源维度:瀑布是否有串行阻塞、图片体积、重复 / 无用请求
  3. 有构建产物时:包体积与依赖构成
  4. 无实测时:只报代码层反模式(🟡),报告头声明"未实测"
  5. 产出格式:现象 + 证据 + 影响 + 定位方向(如"首屏被 X 阻塞""首屏图 3MB");优化方案与收益量化不在本 skill 范围

阶段 4:双视角研判与优先级

  1. 先过滤误报:过一遍误报过滤清单(见 reference.md 4.1)——有意取舍 / 第三方默认行为 / 纯美术观感等默认不算问题;被过滤项写入报告第 5 节并给依据
  2. 归属核对(分拣越界项):产品级功能缺失 → 交 product-manager M3;纯代码质量(命名 / 架构 / 设计模式)→ 不进本清单;后端性能 → 交 performance-analysis
  3. 用户视角:影响谁(新用户 / 老用户 / 管理员)× 影响什么任务 × 发生频率
  4. PM 视角:Kano 分类 + 价值 × 成本评分(口径见 use_skill("product-manager") 的 reference.md 第一节;未安装则按其口径自主推理,不阻塞)
  5. 优先级:P0(核心任务被卡住,或高频 + 低成本)→ P1 → P2;P0 必须写明理由;判定依据不足标 Kano 待定 并进待确认,不得默认按"期望"参与排序
  6. 合并输出:一张清单,「来源」列区分(体验优化 / 实现修复 / 加载性能 / 体验增强)

阶段 5:走查报告

模板见下;完整模板与落盘规范见 reference.md 第五节。


报告模板

# 前端走查报告:{对象}

取证档位:A / B / C(能力说明)
证据声明:本次最高证据等级 {🟢/🟡/🔴} + 取证方式(实操实测 / 用户提供画面 / 代码直读 / 静态推演)+ 降级说明

## 1. 执行摘要
{3-5 条结论,每条挂证据等级;未实操时首句声明"本次未实操"}

## 2. 范围与覆盖
- 走查对象:{页面 / 入口清单}
- 状态覆盖:{八态 × 页面 的覆盖矩阵;每个 ✅ 须可追溯证据,见约束 9}
- 明确未覆盖:{没走到的部分 + 原因}

## 3. 发现清单(唯一一张表)
| # | 优先级 | 发现 | 来源 | 影响谁 | 证据 | 建议方向 |
|---|--------|------|------|--------|------|----------|
| 1 | P0 | {现象 + 场景} | 体验优化 | 新用户首次 | 🟢 截图 / `file:line` | {方向,不写实现方案} |

## 4. 加载性能体检(仅展开第 3 节「来源=加载性能」的条目,不新增条目)
| 现象 | 证据 | 影响 | 定位方向 |

## 5. 经走查排除
{每项带依据:"XX 维度走查后无问题(依据:{证据})";含被误报过滤清单滤掉的项(设计如此 / 有意取舍)}

## 6. 待确认清单
{所有 🔴 项 + 需用户拍板的取舍;每条配验证方法}

## 7. 建议下一步
{实施 → request-guard → code-review;产品级缺失 → product-manager M3;深入性能 → performance-analysis}

约束

  1. 报告头必须声明取证档位与证据等级;无实操时禁止出现"已体验 / 操作确认"式表述
  2. 🔴 不进结论区,只进「待确认清单」且必须配验证方法
  3. 先操作后结论:没有操作路径支撑的体验结论不得标 🟢
  4. 不臆造用户心理:每条发现必须能回答"哪类用户在什么任务下遇到什么现象"
  5. 不修改产品代码;性能只到体检级;视觉只报影响可用性的
  6. 一张清单,禁止分表输出
  7. 涉及真实副作用(下单 / 删除 / 支付)的操作须在测试环境进行,环境不明先问
  8. 一次走查区间内的"排除项"必须如实写出,不得只报问题
  9. 覆盖率门禁:覆盖矩阵与「经走查排除」的每个结论必须可追溯证据(截图编号 / 发现编号 / file:line)——追溯不到的项一律标 ⚠️,禁止用裸 ✅ 充数("没查"不得写成"无问题");证据必须真实存在且可复核,编造证据按报告作废处理

反模式

  • ❌ 只截图不点,就写"体验流畅 / 存在卡点" → 走查是操作流,不是静态看图
  • ❌ 无画面假装看过:"页面层级混乱、配色不协调"(其实从未看到渲染结果)→ 必须降级声明
  • ❌ 用代码推断体验:"代码里有 loading 分支,所以加载反馈没问题" → 有分支 ≠ 用户看得到,属 🟡
  • ❌ 把 🔴 推断写进执行摘要 → 报告作废重写
  • ❌ 滑成 code-review:点评组件命名、状态管理选型、设计模式、目录结构 → 看到自己在写这类内容立即停
  • ❌ 滑成后端性能分析:去分析 SQL、接口 RT、加缓存 → 前端加载性能才是本条线
  • ❌ 滑成 product-manager M2/M3:开始规划"下一版该加什么功能" → 本 skill 只报让现有功能更好用的增强建议,产品级功能缺失交接 M3
  • ❌ 空泛的人性化断言:"用户体验不够友好""交互不够顺畅" → 必须锚定具体场景 + 可观察现象
  • ❌ 只报问题不报排除项 → 用户会重复排查已确认无问题的维度
  • ❌ 用裸 ✅ 充数:覆盖矩阵打了 ✅ 却追溯不到任何证据(截图 / 发现编号 / file:line)→ 一律改标 ⚠️,"没查"不得写成"无问题"
  • ❌ 把有意取舍当缺陷:未做暗色模式 / 未做国际化直接判为缺陷 → 标"需确认是否有意"
  • ❌ 出多张清单:体验一份、性能一份、实现一份,用户自己合并 → 违反核心原则 6
  • ❌ 给假精确:"预计提升转化 12%""约 3 人日" → 无数据支撑时只给价值 / 成本的高中低

与相关 skill 的关系

skill 关系
product-manager 双视角口径来源(Kano / 价值×成本 / 证据三级制);产品级功能缺失交其 M3;M2 / M4 与本 skill 的分工见「定位」
agent-browser / playwright-cli 取证工具(A 档实操);不可用时按 B / C 档降级
e2e-testing 其「动态体验验证」与本 skill 最近,但前置门禁(须 e2e 全 PASS)与判定对象不同(见「定位」分工表);其分批循环思想可借鉴
code-review 实施优化后的代码质量把关
request-guard 实施前刹车
performance-analysis 接收本 skill 的性能体检发现,做深入定位与优化方案
ui-designer / interaction-design 视觉 / 交互的重新设计
acceptance-verify 它判"这一版达标没有",本 skill 判"下一版该优化什么"
ui-to-ascii 需把走查画面转成文本存档时可用
expert-solution-workflow 走查前查可复用经验 / 解决方案(未安装则跳过,不阻塞)

更多资源

  • 四类检查清单(实现检查表 / 状态矩阵 / 场景轴 / 性能反模式)、误报过滤清单、B/C 档降级细则、性能体检细则、报告完整模板、常见坑,参见 reference.md
  • A 档完整走查、C 档降级走查、归属交接三类示例,参见 examples.md