@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/docs/superpowers/specs/2026-05-29-fec-debug-design.md

@@ -0,0 +1,340 @@
+# fec-debug 设计文档
+
+> 将 `fec-build-fix` 升级为 `fec-debug`：从构建失败修复工具扩展为前端全类型问题诊断与修复框架。
+
+## 背景与动机
+
+当前 `fec-build-fix` 体系只覆盖 lint、type-check、test、build、CI 等验证命令的失败修复。实际开发中，构建失败只是前端调试的一小部分，更多时间花在运行时错误、UI 异常、接口问题等场景。
+
+本次升级目标：
+
+1. **扩大覆盖面**：从构建失败扩展到运行时错误、UI/视觉异常、接口与数据问题
+2. **引入系统化诊断方法论**：从"跑命令看报错"升级为"分类→收集→假设→验证→修复"的 5 步科学方法
+3. **按类型分流**：构建失败走现有快速路径，其他类型走假设-验证流程
+
+## 架构概览
+
+### 统一诊断框架（5 步法）
+
+所有前端问题诊断遵循统一流程骨架：
+
+```
+1. 分类（Classify）— 识别问题类型 + 影响范围
+2. 收集（Collect）— 按类型收集证据
+3. 假设（Hypothesize）— 基于证据模式提出可能根因
+4. 验证（Verify）— 逐一测试假设，排除法缩小范围
+5. 修复与确认（Fix & Validate）— 最小修复 + 回归验证
+```
+
+### 诊断模块（按问题类型适配）
+
+每个模块定义该类型下步骤 2-4 的具体策略：
+
+| 模块        | 收集策略                            | 假设策略                           | 验证策略                        |
+| ----------- | ----------------------------------- | ---------------------------------- | ------------------------------- |
+| **build**   | 运行失败命令，捕获 stderr           | 按错误类型分组匹配已知模式         | 修一类 → 重跑命令               |
+| **runtime** | 复现路径 + 控制台/堆栈 + 组件树     | 异常堆栈反向追踪 + 状态流分析      | 断点/日志验证 → 修复 → 复现     |
+| **ui**      | 截图/布局快照 + DOM 检查 + 计算样式 | CSS 特异性 + 组件状态 + 响应式断点 | DevTools 验证 → 修复 → 视觉对比 |
+| **api**     | 请求/响应日志 + 网络瀑布 + 状态快照 | 请求链路逐跳检查                   | curl 复现 → 修复 → 端到端验证   |
+
+### 文件结构
+
+```
+commands/fec-debug.md                # 入口命令（路由 + 调度）
+skills/fec-debug-framework/SKILL.md  # 核心框架（5 步法 + 四个诊断模块）
+agents/fec-debugger.md               # 子代理（执行复杂诊断）
+```
+
+### 与现有组件的关系
+
+- `fec-validation-fix` — 保留，作为 Build 模块的核心逻辑引用
+- `fec-build-fix` / `fec-build-fixer` — 废弃，由 `fec-debug` / `fec-debugger` 替代
+- `gsd-debug` — 独立共存，`fec-debug` 专注前端领域
+
+## 详细设计
+
+### Command: `fec-debug`
+
+入口命令，负责问题分类和调度。
+
+```markdown
+---
+name: fec-debug
+description: 前端问题诊断与修复：覆盖构建失败、运行时错误、UI 异常、接口问题，使用统一诊断框架按类型分流。
+---
+
+# 前端 Debug
+
+使用 `fec-debug-framework` 统一诊断框架，按问题类型分流诊断。
+
+## 使用方式
+
+用户描述问题后，自动进入诊断框架：
+
+1. **分类**：识别问题类型（build / runtime / ui / api）
+2. 按类型进入对应诊断模块
+3. 复杂或跨类型问题可委托 `fec-debugger` 子代理
+
+## 问题类型速查
+
+| 类型    | 典型场景                                        |
+| ------- | ----------------------------------------------- |
+| build   | lint/type-check/test/build/CI 失败              |
+| runtime | JS 异常、白屏、组件渲染错误、路由异常、状态丢失 |
+| ui      | 样式错位、交互异常、动画卡顿、响应式问题        |
+| api     | 请求失败、超时、数据不一致、CORS、缓存问题      |
+
+## 强约束
+
+- 不通过关闭规则、删除测试或降低类型安全来"修复"问题
+- 不顺手重构无关代码
+- 不在缺少证据时猜测根因
+- 修复后必须验证，不能只改不测
+```
+
+### Skill: `fec-debug-framework`
+
+核心框架 skill，定义统一诊断方法论和四个诊断模块。
+
+```markdown
+---
+name: fec-debug-framework
+description: Use when diagnosing and fixing frontend issues including build failures, runtime errors, UI anomalies, and API/data problems. Provides a unified 5-step diagnostic methodology with type-specific modules. Chinese triggers: 调试, debug, 排查, 定位, 报错, 异常, 白屏, 请求失败.
+---
+
+# 前端诊断框架
+
+## 核心方法论（5 步法）
+
+所有前端问题诊断遵循统一流程：
+
+### 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 问题同时参考 `fec-dependency-upgrade`
+- 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 定位问题层级
+- 端到端请求验证修复
+
+---
+
+## 报告格式
+
+保存至 `reports/debug-YYYY-MM-DD-HHmmss.md`：
+
+### 诊断报告
+
+| 项目       | 内容                       |
+| ---------- | -------------------------- |
+| 问题类型   | build / runtime / ui / api |
+| 问题描述   | 用户报告的现象             |
+| 收集的证据 | 关键日志、截图、请求记录   |
+| 假设与验证 | 每个假设的验证结果         |
+| 根因       | 最终确认的根本原因         |
+| 修复内容   | 修改的文件和具体改动       |
+| 验证结果   | 修复后的验证命令和结果     |
+| 剩余风险   | 未覆盖的边界或潜在回归     |
+
+---
+
+## 强约束
+
+- 不在缺少证据时猜测根因
+- 不通过关闭规则、删除测试或降低类型安全来「修复」
+- 每次只改一个变量来验证假设
+- 不在验证前扩大改动范围
+- 同一假设连续 3 次验证失败，停止并报告阻塞
+```
+
+### Agent: `fec-debugger`
+
+子代理，处理复杂或多层嵌套的诊断场景。
+
+```markdown
+---
+name: fec-debugger
+description: 前端诊断与修复子代理：使用统一 5 步诊断框架处理构建失败、运行时错误、UI 异常、接口问题。适合复杂或多层嵌套的前端问题排查。
+tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
+model: sonnet
+permissionMode: default
+maxTurns: 16
+skills:
+  - fec-debug-framework
+  - fec-validation-fix
+  - fec-vite-project-standard
+  - fec-react-project-standard
+  - fec-vue3-project-standard
+  - fec-testing-strategy
+  - fec-dependency-upgrade
+  - fec-security-review
+---
+
+你是一名前端诊断专家，使用统一 5 步诊断框架（分类→收集→假设→验证→修复）定位和修复前端问题。
+
+## 工作流
+
+1. 读取问题描述，按 `fec-debug-framework` 的 Step 1 分类问题类型。
+2. 进入对应诊断模块，执行 Step 2 收集证据。
+3. 基于证据提出假设（Step 3），每个假设必须可测试。
+4. 逐一验证假设（Step 4），每次只改一个变量，记录证实/证伪。
+5. 确认根因后执行最小修复（Step 5），运行受影响验证命令。
+6. 输出诊断报告到 `reports/debug-YYYY-MM-DD-HHmmss.md`。
+
+## 跨类型问题
+
+当问题涉及多个类型（如 API 失败导致 UI 异常）：
+
+- 从最表层症状入手
+- 逐层深入，每层确认后再进入下一层
+- 在报告中标注问题链路
+
+## 强约束
+
+- 不在缺少证据时猜测根因
+- 不通过关闭规则、删除测试或降低类型安全来"修复"
+- 不在验证前扩大改动范围
+- 同一假设连续 3 次验证失败，停止并报告阻塞
+- 不顺手重构无关代码
+```
+
+## 迁移方案
+
+### 文件变更清单
+
+| 操作 | 文件                                              | 说明                                              |
+| ---- | ------------------------------------------------- | ------------------------------------------------- |
+| 新建 | `commands/fec-debug.md`                           | 新入口命令                                        |
+| 新建 | `skills/fec-debug-framework/SKILL.md`             | 核心框架 skill                                    |
+| 新建 | `agents/fec-debugger.md`                          | 新子代理                                          |
+| 删除 | `commands/fec-build-fix.md`                       | 被 fec-debug 替代                                 |
+| 删除 | `agents/fec-build-fixer.md`                       | 被 fec-debugger 替代                              |
+| 保留 | `skills/fec-validation-fix/SKILL.md`              | 作为 Build 模块参考逻辑                           |
+| 同步 | `npm-packages/openclaw/commands/fec-build-fix.md` | 重命名为 fec-debug 并更新内容                     |
+| 同步 | `npm-packages/openclaw/agents/` 下对应文件        | 新增 fec-debugger，删除 fec-build-fixer（若存在） |
+
+### 向后兼容策略
+
+- `fec-validation-fix` skill 保留不动，`fec-debug-framework` 的 Build 模块引用它
+- 旧命令 `fec-build-fix` 和 `fec-build-fixer` agent 删除（避免命名混乱）
+- npm 包同步更新
+
+### 验证步骤
+
+迁移完成后：
+
+1. 确认 `/fec-debug` 命令可正常调用
+2. 确认 `fec-debug-framework` skill 被正确加载
+3. 确认 `fec-debugger` agent 可被委托
+4. 确认旧命令 `fec-build-fix` 不再出现在可用列表中