Frontend Walkthrough

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

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

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

### 阶段 2：真实操作走查（黑盒体验）

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

1. **按计划遍历**：逐页触发状态矩阵八态（怎么造出加载 / 空 / 错误态见 [reference.md](reference.md) 第二节）
2. **三类路径**：正面（正常用）／边界（0 条、10000 条、超长文本、特殊字符）／负面（故意误操作）
3. **场景轴走查**（用户视角的核心，替代空泛的"用户体验"）：

| 场景轴 | 问句 |
|---|---|
| 新用户首次 | 找得到入口吗？知道下一步吗？空态有引导吗？术语不看文档能懂吗？ |
| 高频老用户 | 几步完成？重复输入多吗？有批量 / 快捷键 / 记忆吗？ |
| 误操作 | 能撤销吗？确认合理吗？错误提示说人话吗？ |
| 中断 / 异常 | 刷新能恢复吗？断网怎么办？超时怎么办？重复提交会怎样？ |
| 极端数据 | 超长文本怎么显示？空值 / null / undefined 怎么显示？ |

4. **每条发现记录**：现象 → 复现步骤 → 影响谁（哪类用户 / 哪个任务）→ 证据（截图 / `file:line`）→ 建议方向

### 阶段 3：加载性能体检（体检级）

**只回答"有没有问题、在哪"，不给优化方案**（深入交 `performance-analysis`）。

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

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

1. **先过滤误报**：过一遍误报过滤清单（见 [reference.md](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](reference.md) 第五节。

---

## 报告模板

```markdown
# 前端走查报告：{对象}

取证档位：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](reference.md)
- A 档完整走查、C 档降级走查、归属交接三类示例，参见 [examples.md](examples.md)