frontend-debug

name	frontend-debug
description	CrabCode 前端调试闭环：采集性能基线→改码→回验 Web Vitals/视觉/样式。当用户要求排查前端性能、优化 Core Web Vitals、样式一致性检查、组件视觉回归或样式 token 提取时使用。
tools	browser
metadata	{"category":"operations","emoji":"🧪","tree_id":"ui/browser","tree_group":"ui","enabled_when":"BrowserController != nil","intent_keywords":{"zh":["性能审计","性能分析","前端性能","Web Vitals","lighthouse","卡顿排查","样式提取","设计令牌","design token","CSS 提取","视觉回归","截图对比","视觉验证","HAR 导出","内存泄漏","DOM 数量","前端调试","页面性能"],"en":["performance audit","web vitals","lighthouse","frontend perf","style extraction","design tokens","computed styles","visual regression","screenshot diff","har export","memory leak","dom count","frontend debug"]},"intent_priority":15,"related_tools":["browser","bash"],"scene_hint":"前端调试 → perf_audit → extract_styles → 改码 → reload → perf_audit + visual_diff 验证","summary":"Frontend-debug loop for CrabCode: collect perf + style baseline, modify, re-verify","title":"Frontend Debug Workflow","verb":"Debug","sort_order":41,"policy_groups":["group:ui"],"profiles":["coding","full"],"wizard_group":"web"}

CrabCode 前端调试闭环技能

CrabCode 编码智能体的标准前端调试 SOP。所有 action 都通过 browser 工具完成，配合 bash 修改源码。

触发信号

场景	典型请求
Core Web Vitals 优化	"页面加载慢，查一下 LCP/FCP"、"audit 性能"
设计一致性	"这个按钮为什么没用主题色"、"提取设计 token"
视觉回归	"改完样式看下其他页面没破坏"、"对比截图"
内存/DOM 排查	"页面卡顿"、"DOM 节点是不是太多了"
网络请求审计	"导出这个页面的 HAR"、"看下请求列表"

五阶段回环

①     ②             ③                ④                ⑤
基线 → 定位 → 改码（bash/edit） → 刷新 → 回验（同一套指标对比）

① 基线采集（action 组合）

browser(action="navigate", url="<target>")
browser(action="perf_audit")           # Core Web Vitals + navigation + resources + score
browser(action="memory_snapshot")      # DOM / JS heap 快照（可选）
browser(action="visual_diff", baseline_id="<feature>-home")  # 首次调用自动保存基线

要点：

• perf_audit 返回 simple_score.performance_0_100 + notes 列表，直接看 notes 就能定位问题项
• visual_diff 首次调用必然返回 saved_as_baseline=true + similarity=1.0，这是预期行为
• DOM>1500 或 JS heap>70% 会在 memory_snapshot.notes 里告警

② 样式与组件定位

browser(action="observe")                                   # 获取 refs
browser(action="extract_styles", ref="e12", max_depth=2)    # 按 ref 抓组件样式树
browser(action="extract_styles", max_depth=1)               # 全局 design_tokens 汇总
browser(action="element_screenshot", ref="e12", padding=8)  # 单元素截图

extract_styles 返回要点：

• nodes[] — 每个元素的 48 项 design-token 属性
• design_tokens — 跨元素去重+频次排序的 colors/fonts/spacings/radii/shadows
• 若只关心特定属性，传 properties=["color","font-size"] 覆盖预设

③ 改码（脱离 browser 工具）

使用 bash、workspace-file-edit 或 CrabCode 编码工具修改源码。这一阶段 browser 不参与。

④ 刷新

browser(action="navigate", url="<target>")   # 或 go_back/go_forward 视情况

⑤ 回验（重复 ① 的指标）

browser(action="perf_audit")                                  # Δ 对比 ①
browser(action="visual_diff", baseline_id="<feature>-home")   # similarity < 1.0 → 解读差异区域

判读标准：

• simple_score.performance 提升 ≥ 5 分，关键指标（LCP/CLS/TBT）进入 good 区间 → 合格
• visual_diff.similarity < 0.98 且改动点未在预期 diff_regions 内 → 可能破坏其他区域

深度诊断

诉求	action 组合
请求清单 / 接口统计	har_export(filter="<domain>", max_count=100)
控制台错误	get_console（只读历史）
网络失败	get_network（只读历史）
接口体积分析	har_export → 本地脚本解析 response size
组件命中数	在 extract_styles.nodes[] 里自行统计 tag 分布

速度技巧

• 首次 perf_audit 会在页面上注入 PerformanceObserver，至少保持页面存活 3 秒后再次调用才能拿到稳定 LCP/CLS。改动后 reload 同理。
• visual_diff 默认 sample_step=2 已足够日常用；若追查 1 像素级变化可设为 1，速度会慢 4 倍。
• extract_styles 在大页面务必设 max_nodes ≤ 100（默认就是）。

与其他技能协作

场景	搭配
需要边改边看	与 bash 并行；每次改动后走 ④⑤
页面需要登录态	先 session_load(id=<某账号>)（参见 media-publish 技能的 session 介绍）
跨环境回归	har_export 两个环境分别导出，本地 diff
基线管理	visual_diff 的 baseline 当前是 in-process 存储，进程重启即失效；长期基线需要 bash 写文件

常见错误

报错	解读	恢复
baseline_id is required	调用 visual_diff 没传	选一个有意义的 ID（如 home_hero_v1）
element has zero size	目标元素隐藏 / display:none	先 scroll / observe 确认 ref 有效
this capability requires the CDP browser backend	当前使用非 CDP 后端	重启或切换到 CDP profile
perf_audit 返回全零	页面刚打开 observer 还没观测到事件	等 2-3 秒后再次调用

安全边界

• extract_styles 不会修改页面，但注入了读取脚本到隔离世界 — 对反检测敏感站点，先 stealth_profile=standard。
• har_export 可能泄露 Bearer token 到对话；避免把 HAR 贴给外部 LLM。
• visual_diff 的 baseline 包含页面原始像素，存在内存中，进程结束即释放；不要依赖它做长期审计。