page-health-check

name	page-health-check
description	页面健康检查与优化 SOP。对指定 URL 执行完整体检，发现问题直接修复或列出待修复清单。当用户提到"检查页面""页面体检""优化页面""页面很慢"或给出一个 URL 要求检查时使用。

页面健康检查 SOP

给一个 URL，用 Cursor 内置浏览器完成完整体检。能修的当场修，不能修的列清单。

流程

打开页面 → 截屏 → 交互探索 → 逐项审查(数据/视觉/控制台/性能) → 修复 → 再验证

最多 3 轮修复循环。每轮修复后重新截图验证。

---

Step 1: 截屏

打开目标 URL，等待渲染完成（至少 2s），先 snapshot 获取 DOM 结构，再 fullPage 截图。内部滚动容器截不全时分段滚动截图。

---

Step 2: 交互探索

点击页面内的交互元素，暴露子视图和弹窗，确保所有可达视图都被检查到。

安全分类：

级别	举例	操作
安全	Tab 切换、折叠展开、筛选、排序、分页、查看详情、搜索	放心点
只读弹窗	新增按钮、编辑按钮	打开看布局就关闭，不提交
危险	删除、禁用开关、审批、确认提交	不点

去重：同类重复元素只点一个代表（如表格每行的编辑按钮只点第一行）。

顺序：Tab/分段器 → 筛选/搜索 → 查看/编辑弹窗 → 新增弹窗 → 展开折叠。每步截图，对新视图同样执行后续审查。

不做的事：不切换导航、不提交表单、不点删除、不做破坏性测试。

---

Step 3: 逐项审查

对主页面及交互探索中暴露的每个视图，逐一检查以下维度。不打分，只找问题。

3.1 数据正确性（P0 优先级）

乱码 — 观察截图和 DOM 文本中是否有 �、锟斤拷、â€"、???、□□□、emoji 异常等。可通过 browser_snapshot 获取 DOM 文本后检测。常见原因：charset 未声明、数据库连接字符集不匹配、utf8 应升级 utf8mb4。

模拟数据 — 疑似特征：规律姓名（张三李四）、整齐数字（100/200）、不合理时间、Lorem ipsum、占位图、虚假联系方式（13800138000）、数据量太规律。同时检查网络请求是否指向 mock 服务。

异常空数据 — 空表格、全零统计、空下拉选项、全空详情页。空数据大概率是 bug，排查路径：前端是否发请求 → API 是否正常返回 → 查询参数是否正确 → 数据库是否有数据。即使确认真无数据，也要确保空状态 UI 友好。

3.2 视觉与交互

整体视觉 — 关注：色彩是否统一、排版层次是否清晰、间距是否一致、对齐是否规整、信息密度是否适中、视觉焦点是否明确。

交互反馈 — 关注：hover 是否有反馈、状态切换是否有过渡动效、数据加载是否有 loading/skeleton、空状态 UI 是否友好、长文本是否正确 ellipsis/换行。

组件一致性 — 关注：按钮主次是否分明、表格表头是否固定且列宽合理、表单标签是否对齐、卡片圆角阴影是否统一、弹窗尺寸是否适中、图标风格是否统一。

3.3 控制台

获取控制台消息。error 判断是否为业务错误（排除 Permissions-Policy 等环境噪音），忽略 [CursorBrowser] 前缀消息。

3.4 性能与响应速度

API 响应 — 从网络请求分析耗时：< 300ms 正常，300ms-1s 记录，1-3s 需优化（应有 loading），> 3s 必须优化。慢接口用 curl 测 TTFB，TTFB > 600ms 需排查后端。

前端加载 — 通过 Performance API 获取 FCP（< 1s 优秀 / > 2.5s 需优化）、Page Load（< 3s 优秀 / > 6s 需优化）。

体感 — 首屏 1s 内应可见主要内容、切换筛选 < 500ms、翻页应有 loading、弹窗应立即弹出。

---

Step 4: 修复

优先级

1. P0 — 白屏、JS 报错不可用、乱码、模拟数据残留、异常空数据
2. P0.5 — 接口 > 3s、页面加载 > 6s、操作无响应
3. P1 — 布局错乱、文字溢出、元素重叠
4. P1.5 — 接口 1-3s、缺 loading 状态
5. P2 — 缺 hover 反馈、间距不一致、色彩不统一
6. P3 — 过渡动效、微交互美化

默认行为：直接修

发现问题就修，不要只列清单。agent 做检查的价值就是修完交付，不是当 QA 提工单。

定位源码 → 修改 → docker compose up --build -d <service> → 回到 Step 1 再验证。

什么情况不修（列入待修复清单）

只有以下情况才不当场修，而是列清单说明原因：

• 需要 DBA / 运维介入 — 如加数据库索引、调整容器资源、修改 Nginx 配置
• 需要设计确认 — 如图标风格统一方案、配色方案变更、布局大改
• 影响面太大 — 修改会影响多个页面的公共组件，需要评估连锁影响
• 缺少信息 — 不清楚业务逻辑该怎么处理，需要产品确认

除此之外，CSS 修复、前端布局调整、添加 loading/hover、修复 mock 数据对接、修复空数据 bug 等——全部直接修。

---

输出

检查完成后输出结果。已修复是主体，待修复是例外。

## 页面检查结果

**URL**: https://...
**检查时间**: YYYY-MM-DD HH:MM
**探索范围**: 主页面 + N 个 Tab + N 个弹窗

### 已修复（N 项）
| # | 优先级 | 问题 | 改动 |
|---|--------|------|------|
| 1 | P0 | 客户列表显示空数据 | 修复 API 查询参数 |
| 2 | P1 | 编辑弹窗内容贴边 | padding 0→20px |
| 3 | P2 | 按钮缺 hover 效果 | 添加 hover 样式 |

### 待修复（N 项，需人工介入）
| # | 优先级 | 问题 | 未修原因 |
|---|--------|------|----------|
| 1 | P0.5 | /api/customers 响应 2.8s | 需 DBA 加索引 |

### 检查通过项
数据正确性 ✓ | 控制台 ✓ | 前端加载 FCP 800ms ✓

---

执行方式（强制）

每个页面必须使用独立的子 agent 执行检查。 这是硬性要求，不可在主 agent 中直接执行检查流程。

• 收到多个 URL 时，为每个 URL 各启动一个子 agent，并行执行
• 即使只有一个 URL，也必须委派给子 agent 执行
• 子 agent 负责完整走完 Step 1 ~ Step 4 全流程，最终返回结构化检查结果
• 主 agent 只负责：汇总各子 agent 结果 → 输出最终报告

---

关键原则

1. 一页一 agent — 每个页面必须由独立子 agent 执行，多页面并行检查
2. 数据第一 — 乱码、模拟数据、空数据是 P0，优先于一切视觉问题
3. 空数据先当 bug 查 — 不要看到空就认为"正常无数据"
4. 交互要安全 — 只看不提交，危险操作不点，同类只点一个
5. 默认直接修 — 能修的当场修完交付，只有需要 DBA/设计/产品介入的才列清单
6. 性能要量化 — 不凭感觉说快慢，用 Performance API 和 curl 拿数字
7. 修复后必须再验证 — 不要假设改动有效
8. 视觉优化要克制 — 只修有明确问题的地方，尊重已有设计系统
9. 忽略环境噪音 — Permissions-Policy、CursorBrowser 注入消息不算错误