fec-debug-framework · diff
git:20260607.5e55862 to git:20260611.9d7f5e4
95 added, 95 removed. Audit A to A.
---
name: fec-debug-framework
- description: 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, 排查, 定位, 报错, 异常, 白屏, 请求失败.
+ description: Use when diagnosing frontend build failures, runtime errors, UI anomalies, API/data problems, white screens, request failures, or unexplained production exceptions; Chinese triggers include debugging, debug, troubleshooting, positioning, error reporting, exceptions, white screens, request failures.
---
- # 前端诊断框架
+ # Front-end diagnostic framework
## Purpose
- 用证据驱动的分类、收集、假设、验证和修复流程定位前端故障，避免凭直觉扩大改动范围。
+ Use an evidence-driven triage, collection, hypothesis, verification, and remediation process to locate front-end faults and avoid relying on intuition to expand the scope of changes.
## Procedure
- 所有前端问题诊断遵循统一流程：
+ All front-end problem diagnosis follows a unified process:
- ### Step 1: 分类（Classify）
+ ### Step 1: Classify
- 识别问题类型和影响范围：
+ Identify problem type and scope of impact:
- | 类型 | 判断依据 | 诊断入口 |
+ | Type | Judgment basis | Diagnosis entrance |
| ------- | ---------------------------- | -------------- |
- | build | 命令退出非零、stderr 有错误 | → Build 模块 |
- | runtime | 控制台异常、白屏、功能不可用 | → Runtime 模块 |
- | ui | 视觉偏差、交互不符预期 | → UI 模块 |
- | api | 请求状态码异常、数据不一致 | → API 模块 |
+ | build | Command exit is non-zero, stderr has error | → Build module |
+ | runtime | Console exception, white screen, function unavailable | → Runtime module |
+ | ui | Visual deviation, interaction not as expected | → UI module |
+ | api | Request status code exception, data inconsistency | → API module |
- 跨类型问题（如 API 失败导致 UI 异常）从最表层症状入手，逐层深入。
+ Cross-type problems (such as API failure leading to UI exceptions) start with the most superficial symptoms and drill down layer by layer.
- ### Step 2: 收集（Collect）
+ ### Step 2: Collect
- 按类型收集证据（各模块有具体策略，见下方）。
+ Collect evidence by type (specific strategies for each module, see below).
- ### Step 3: 假设（Hypothesize）
+ ### Step 3: Hypothesize
- 基于证据提出可能根因，按可能性排序：
+ Propose possible root causes based on evidence, ranked by likelihood:
- - 每个假设必须可测试（有明确的验证方法）
- - 最多保留 3 个假设，避免发散
- - 格式：「因为 X，导致 Y，可通过 Z 验证」
+ - Every hypothesis must be testable (have clear verification methods)
+ - Keep at most 3 hypotheses to avoid divergence
+ - Format: "Because X leads to Y, which can be verified by Z"
- ### Step 4: 验证（Verify）
+ ### Step 4: Verify
- 逐一测试假设：
+ Test the hypotheses one by one:
- - 从最可能的假设开始
- - 每次只改一个变量
- - 验证结果记录：证实 / 证伪 / 待定
- - 假设全部证伪时回到 Step 2 重新收集
+ - Start with the most likely hypothesis
+ - Only change one variable at a time
+ - Verification result record: confirmed / falsified / pending
+ - If all assumptions are falsified, return to Step 2 and collect again.
- ### Step 5: 修复与确认（Fix & Validate）
+ ### Step 5: Fix & Validate
- - 应用最小修复
- - 运行受影响验证命令
- - 确认无回归
- - 输出修复报告
+ - Apply minimal fixes
+ - Run affected verification commands
+ - Confirmed no regression
+ - Output repair report
---
- ## 诊断模块
+ ## Diagnostic module
- ### Build 模块
+ ### Build module
- **收集**：运行最小失败命令，捕获完整 stderr/stdout
- **假设**：按错误类型分组（类型错误、导入失败、配置解析、依赖缺失），匹配已知模式
- **验证**：修一类根因 → 重跑命令 → 确认错误减少
- **特殊处理**：
+ **Collect**: Run minimal failing commands, capture full stderr/stdout
+ **Assumptions**: Grouped by error type (type error, import failure, configuration resolution, missing dependency), match known patterns
+ **Verification**: Fix a type of root cause → rerun the command → confirm that errors are reduced
+ **Special handling**:
- - 依赖版本、peer dependency、ESM/CJS、lockfile 相关失败先作为 build 兼容性问题收集证据
- - 记录 package manager、Node 版本、lockfile diff、相关包版本和完整错误日志
- - 不在缺少证据时升级依赖、手工编辑 lockfile，或把依赖迁移与普通调试修复混在同一批改动
- - 若任务目标本身是版本升级、CVE 修复或 lockfile 风险评审，应转入依赖升级工作流
- - CI 专属失败检查 Node 版本、包管理器、环境变量差异
+ - Collect evidence for dependency version, peer dependency, ESM/CJS, and lockfile related failures first as build compatibility issues
+ - Log package manager, Node version, lockfile diff, related package version and full error log
+ - No longer upgrade dependencies, manually edit lockfiles when evidence is lacking, or mix dependency migrations with normal debug fixes in the same batch of changes
+ - If the task goal itself is version upgrade, CVE repair or lockfile risk review, it should be transferred to the dependency upgrade workflow
+ - CI exclusive failure check Node version, package manager, environment variable differences
- ### Runtime 模块
+ ### Runtime module
- **收集**：
+ **Collect**:
- - 复现路径（用户操作序列）
- - 控制台错误和堆栈
- - 组件渲染树状态（检查关键组件是否正确挂载）
- - 相关 store/state 快照
+ - Recurrence path (sequence of user operations)
+ - Console errors and stack
+ - Component rendering tree status (check whether key components are mounted correctly)
+ - Relevant store/state snapshot
- **假设**：
+ **Assumptions**:
- - 堆栈反向追踪：从异常位置回溯到触发源
- - 状态流分析：检查 state 变化是否符合预期
- - 生命周期分析：是否在错误的时机访问了未初始化的数据
+ - Stack reverse tracing: trace back from the exception location to the trigger source
+ - State flow analysis: Check whether state changes are as expected
+ - Life cycle analysis: whether uninitialized data is accessed at the wrong time
- **验证**：
+ **Verification**:
- - 添加临时日志确认状态值
- - 在可疑路径添加断言
- - 复现路径验证修复
+ - Add temporary log confirmation status value
+ - Add assertions on suspicious paths
+ - Recurrence path verification fix
- ### UI 模块
+ ### UI module
- **收集**：
+ **Collect**:
- - 当前截图 vs 期望效果
- - DOM 结构检查（元素是否存在、层级是否正确）
- - 计算样式检查（实际应用的 CSS 值）
- - 响应式断点测试
+ - Current screenshot vs desired effect
+ - DOM structure check (whether the element exists and whether the level is correct)
+ - Computed style checks (actual applied CSS values)
+ - Responsive breakpoint testing
- **假设**：
+ **Assumptions**:
- - CSS 特异性冲突（选择器权重不够被覆盖）
- - 组件状态不匹配（props/state 未正确传递）
- - 布局模型问题（flex/grid 配置错误）
- - 响应式断点遗漏
+ - CSS specificity conflict (selector weight is not enough to be overridden)
+ - Component state mismatch (props/state not passed correctly)
+ - Layout model problem (flex/grid configuration error)
+ - Missing responsive breakpoints
- **验证**：
+ **Verification**:
- - 浏览器 DevTools 实时调整验证
- - 隔离组件测试（排除外部样式干扰）
- - 多断点逐一验证
+ - Browser DevTools real-time adjustment verification
+ - Isolated component testing (excluding external style interference)
+ - Multiple breakpoints to verify one by one
- ### API 模块
+ ### API module
- **收集**：
+ **Collect**:
- - 请求 URL、method、headers、body
- - 响应 status、headers、body
- - 网络瀑布时序
- - 相关 store/state 中的缓存数据
+ - Request URL, method, headers, body
+ - Respond to status, headers, body
+ - Network waterfall timing
+ - Cache data in related store/state
- **假设**：
+ **Assumptions**:
- - 请求链路逐跳检查（URL → 中间件 → 拦截器 → 服务端）
- - 数据转换检查（响应解析、类型映射）
- - 缓存策略检查（过期、失效、竞态）
- - 并发请求竞态（race condition）
+ - Request link hop-by-hop inspection (URL → Middleware → Interceptor → Server)
+ - Data conversion checks (response parsing, type mapping)
+ - Cache policy check (expiration, invalidation, race condition)
+ - Concurrent request race condition (race condition)
- **验证**：
+ **Verification**:
- - curl 独立复现（排除前端干扰）
- - 逐层 mock 定位问题层级
- - 端到端请求验证修复
+ - curl independent reproduction (excluding front-end interference)
+ - Mock layer by layer to locate the problem level
+ - End-to-end request validation fixes
---
- ## 详细参考
+ ## Detailed reference
- 撰写诊断报告时，加载 [references/report-template.md](references/report-template.md)。
+ When writing a diagnostic report, load [references/report-template.md](references/report-template.md).
## Constraints
- - 不在缺少证据时猜测根因
- - 不通过关闭规则、删除测试或降低类型安全来「修复」
- - 每次只改一个变量来验证假设
- - 不在验证前扩大改动范围
- - 同一假设连续 3 次验证失败，停止并报告阻塞
+ - Don't guess at root cause when evidence is lacking
+ - Not "fixed" by turning off rules, removing tests, or reducing type safety
+ - Change only one variable at a time to test your hypothesis
+ - Do not expand the scope of changes before verification
+ - The same hypothesis fails verification 3 times in a row, stops and reports blocking
## Expected Output
- - 诊断报告保存为 `reports/debug-YYYY-MM-DD-HHmmss.md`
- - 报告包含问题类型、关键证据、假设验证记录、根因、修复内容、验证结果和剩余风险
- - build/runtime/ui/api 问题均能说明复现路径、验证命令或下一步阻塞点
+ - The diagnostic report is saved as `reports/debug-YYYY-MM-DD-HHmmss.md`
+ - The report includes issue type, key evidence, hypothesis verification records, root cause, fix content, verification results and remaining risk
+ - Build/runtime/ui/api problems can explain the reproduction path, verification command or next blocking point