Debug Framework

Use when diagnosing frontend build failures, runtime errors, UI anomalies, API/data problems, white screens, request failures, or unexplained production exceptions; Chinese triggers include 调试, debug, 排查, 定位, 报错, 异常, 白屏, 请求失败.

前端诊断框架

Purpose

用证据驱动的分类、收集、假设、验证和修复流程定位前端故障，避免凭直觉扩大改动范围。

Procedure

所有前端问题诊断遵循统一流程：

Step 1: 分类（Classify）

识别问题类型和影响范围：

类型	判断依据	诊断入口
build	命令退出非零、stderr 有错误	→ Build 模块
runtime	控制台异常、白屏、功能不可用	→ Runtime 模块
ui	视觉偏差、交互不符预期	→ UI 模块
api	请求状态码异常、数据不一致	→ API 模块

跨类型问题（如 API 失败导致 UI 异常）从最表层症状入手，逐层深入。

Step 2: 收集（Collect）

按类型收集证据（各模块有具体策略，见下方）。

Step 3: 假设（Hypothesize）

基于证据提出可能根因，按可能性排序：

• 每个假设必须可测试（有明确的验证方法）
• 最多保留 3 个假设，避免发散
• 格式：「因为 X，导致 Y，可通过 Z 验证」

Step 4: 验证（Verify）

逐一测试假设：

• 从最可能的假设开始
• 每次只改一个变量
• 验证结果记录：证实 / 证伪 / 待定
• 假设全部证伪时回到 Step 2 重新收集

Step 5: 修复与确认（Fix & Validate）

• 应用最小修复
• 运行受影响验证命令
• 确认无回归
• 输出修复报告

---

诊断模块

Build 模块

收集：运行最小失败命令，捕获完整 stderr/stdout 假设：按错误类型分组（类型错误、导入失败、配置解析、依赖缺失），匹配已知模式 验证：修一类根因 → 重跑命令 → 确认错误减少 特殊处理：

• 依赖版本、peer dependency、ESM/CJS、lockfile 相关失败先作为 build 兼容性问题收集证据
• 记录 package manager、Node 版本、lockfile diff、相关包版本和完整错误日志
• 不在缺少证据时升级依赖、手工编辑 lockfile，或把依赖迁移与普通调试修复混在同一批改动
• 若任务目标本身是版本升级、CVE 修复或 lockfile 风险评审，应转入依赖升级工作流
• CI 专属失败检查 Node 版本、包管理器、环境变量差异

Runtime 模块

收集：

• 复现路径（用户操作序列）
• 控制台错误和堆栈
• 组件渲染树状态（检查关键组件是否正确挂载）
• 相关 store/state 快照

假设：

• 堆栈反向追踪：从异常位置回溯到触发源
• 状态流分析：检查 state 变化是否符合预期
• 生命周期分析：是否在错误的时机访问了未初始化的数据

验证：

• 添加临时日志确认状态值
• 在可疑路径添加断言
• 复现路径验证修复

UI 模块

收集：

• 当前截图 vs 期望效果
• DOM 结构检查（元素是否存在、层级是否正确）
• 计算样式检查（实际应用的 CSS 值）
• 响应式断点测试

假设：

• CSS 特异性冲突（选择器权重不够被覆盖）
• 组件状态不匹配（props/state 未正确传递）
• 布局模型问题（flex/grid 配置错误）
• 响应式断点遗漏

验证：

• 浏览器 DevTools 实时调整验证
• 隔离组件测试（排除外部样式干扰）
• 多断点逐一验证

API 模块

收集：

• 请求 URL、method、headers、body
• 响应 status、headers、body
• 网络瀑布时序
• 相关 store/state 中的缓存数据

假设：

• 请求链路逐跳检查（URL → 中间件 → 拦截器 → 服务端）
• 数据转换检查（响应解析、类型映射）
• 缓存策略检查（过期、失效、竞态）
• 并发请求竞态（race condition）

验证：

• curl 独立复现（排除前端干扰）
• 逐层 mock 定位问题层级
• 端到端请求验证修复

---

详细参考

撰写诊断报告时，加载 references/report-template.md。

Constraints

• 不在缺少证据时猜测根因
• 不通过关闭规则、删除测试或降低类型安全来「修复」
• 每次只改一个变量来验证假设
• 不在验证前扩大改动范围
• 同一假设连续 3 次验证失败，停止并报告阻塞

Expected Output

• 诊断报告保存为 reports/debug-YYYY-MM-DD-HHmmss.md
• 报告包含问题类型、关键证据、假设验证记录、根因、修复内容、验证结果和剩余风险
• build/runtime/ui/api 问题均能说明复现路径、验证命令或下一步阻塞点