@bovinphang/frontend-craft 2.8.0 → 3.0.0

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

@@ -1,340 +0,0 @@
-# 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` 不再出现在可用列表中

package/localized/zh-CN/skills/fec-source-driven-development/SKILL.md

@@ -1,87 +0,0 @@
----
-name: fec-source-driven-development
-description: 用于前端决策依赖可能变化的框架、库、浏览器、运行时、包、API 或平台行为时，包括官方文档核验、版本敏感模式、迁移选择或公共接口假设；中文触发词包括 查官方文档、以源码为准、source-driven、版本差异。
----
-
-# 来源驱动开发
-
-## 用途
-
-在前端实现、评审和架构决策中优先依据项目内事实、官方文档和当前版本行为，避免沿用过时经验或未经验证的假设。
-
-## 流程
-
-1. 判断是否需要查源
-   - 涉及框架新版本、路由、渲染模式、缓存、构建工具、浏览器 API、包发布格式、鉴权协议或公共接口时必须查源。
-   - 涉及项目约定时先读本仓库 README、配置、模板、已有实现、测试和迁移记录。
-   - 只是稳定语言语法或明显局部重构时，可使用项目现有模式作为事实来源。
-
-2. 收集权威材料
-   - 首选官方文档、规范、源码、release notes、migration guide、类型定义和项目内测试。
-   - 第三方文章只能作为线索，不能作为最终依据。
-   - 对快速变化的库记录包名、版本、文档日期或页面标题。
-   - 当用户要求从本地知识库、项目资料库或 `knowledge/` 目录回答问题时，先走本地知识检索，不使用网络搜索补事实。
-
-3. 提炼决策
-   - 写清当前版本推荐做法、弃用做法、限制条件和迁移注意事项。
-   - 对多个可行方案说明选择理由、兼容性、维护成本和回退方式。
-   - 若文档和项目现状冲突，优先解释冲突并给出渐进调整，不直接推翻已运行系统。
-   - 对依赖升级、框架迁移和公共 API 变化，记录 release notes、migration guide、版本范围、破坏性变更和回滚方案。
-
-4. 落到实现
-   - 将外部行为隔离在适配层、配置层或小型工具函数中，避免在组件里散落版本假设。
-   - 公共接口变化要保持命名、错误形状、默认值和兼容策略清晰。
-   - 代码注释只记录非显而易见的来源约束，不粘贴大段文档。
-
-5. 验证假设
-   - 用类型检查、最小复现、单元测试、组件测试、E2E、构建或浏览器验证证明关键假设。
-   - 如果无法验证，报告不确定性、风险范围和需要用户或团队确认的信息。
-6. 留下轻量决策记录
-   - 当结论会影响公共接口、依赖版本、目录规范或团队工作流时，补充 ADR/变更记录或交给文档同步流程。
-
-## 本地知识检索
-
-当用户指定本地知识库路径，或默认 `knowledge/` 目录存在时，可用本流程回答资料库问题、抽取证据或辅助决策。
-
-1. 定位根目录
-   - 用户明确指定路径时使用该路径。
-   - 否则检查当前项目下 `knowledge/` 是否存在；不存在时说明未找到默认知识库并请求路径。
-   - 不用文件 glob 判断目录是否存在。
-
-2. 分层导航
-   - 优先读取根目录和子目录中的 `data_structure.md`。
-   - 根据目录说明选择最相关的少量分支，不一次性遍历整个知识库。
-   - 记录候选文件、主题、时间/版本范围和为什么相关。
-
-3. 渐进检索
-   - Markdown、文本、日志：先用关键词搜索，再局部读取命中上下文。
-   - PDF：处理前先确认可用工具和提取路线，优先提取到临时文本后再检索，避免把整份 PDF 打进上下文。
-   - Excel：处理前先确认读取/分析路线，先看工作表、列名和少量样例，再按字段过滤或聚合。
-   - 默认最多 5 轮关键词迭代；每轮根据已找到证据调整同义词、缩写和范围。
-
-4. 回答与溯源
-   - 先给结论，再列文件路径、章节、页码、工作表或行号附近作为依据。
-   - 证据不足时说明查过哪些路径、缺什么信息，以及用户如何缩小范围。
-   - 不把知识库外的网络信息混入答案，除非用户另行要求查外部来源。
-
-## 事实源优先级
-
-| 优先级 | 来源 | 用途 |
-| ------ | ---- | ---- |
-| 1 | 项目内配置、测试、已有实现 | 判断本仓库真实约定 |
-| 2 | 官方文档、源码、类型定义 | 判断当前推荐行为 |
-| 3 | 标准规范、浏览器兼容数据 | 判断平台能力和兼容边界 |
-| 4 | Issue、讨论、第三方文章 | 辅助排查，不能单独定案 |
-
-## 约束
-
-- 不凭记忆给版本敏感结论。
-- 不把过时教程当作当前最佳实践。
-- 不引用无法复核的来源作为关键依据。
-- 不为追新而改动稳定项目约定；必须说明收益和迁移成本。
-- 不在交付中复制长篇外部文档；只保留必要结论和链接或文件路径。
-- 不把“查过文档”停留在口头；版本敏感决策需要能追溯到具体版本、路径或官方页面。
-
-## 预期输出
-
-输出来源清单、版本或项目事实、决策结论、实现影响、验证命令和未决风险。若修改代码，关键行为应有测试或构建验证支撑。

package/skills/fec-source-driven-development/SKILL.md

@@ -1,87 +0,0 @@
----
-name: fec-source-driven-development
-description: Use when frontend decisions depend on framework, library, browser, runtime, package, API, or platform behavior that may have changed, including official documentation checks, version-sensitive patterns, migration choices, or public interface assumptions; Chinese triggers include Check official documentation, source code shall prevail, source-driven, version differences.
----
-
-# Source driven development
-
-## Purpose
-
-Prioritize the use of in-project facts, official documentation, and current version behavior in front-end implementation, review, and architecture decisions, and avoid relying on outdated experience or unverified assumptions.
-
-## Procedure
-
-1. Determine whether it is necessary to check the source
-   - Source checking is required when new versions of frameworks, routing, rendering modes, caches, build tools, browser APIs, package publishing formats, authentication protocols, or public interfaces are involved.
-   - When it comes to project commitments, read the README, configuration, templates, existing implementations, testing and migration records of this warehouse first.
-   - Use the project's existing schema as a source of truth when simply stabilizing the language syntax or significantly partial refactoring.
-
-2. Collect authoritative materials
-   - Preferred official documentation, specifications, source code, release notes, migration guide, type definitions and in-project testing.
-   - Third-party articles can only be used as clues and cannot be used as the final basis.
-   - Record package name, version, document date or page title for rapidly changing libraries.
-   - When a user asks to answer a question from a local knowledge base, project repository or `knowledge/` directory, perform local knowledge retrieval first and do not use network search to fill in the facts.
-
-3. Refine decisions
-   - Write down recommended practices, deprecated practices, limitations and migration considerations for the current version.
-   - Explain the reasons for selection, compatibility, maintenance costs and fallback methods for multiple feasible options.
-   - If there is a conflict between the document and the current status of the project, priority will be given to explaining the conflict and making incremental adjustments instead of directly overturning the running system.
-   - Record release notes, migration guide, version scope, breaking changes and rollback plans for dependency upgrades, framework migrations and public API changes.
-
-4. Fall to implementation
-- Isolate external behavior in the adaptation layer, configuration layer or small utility functions to avoid spreading version assumptions throughout the component.
-   - Public interface changes should keep naming, error shapes, default values, and compatibility policies clear.
-   - Code comments only record non-obvious source constraints and do not paste large sections of documentation.
-
-5. Test your hypothesis
-   - Prove key assumptions with type checking, minimal reproduction, unit testing, component testing, E2E, build or browser validation.
-   - If verification is not possible, report uncertainty, risk range, and information that requires confirmation by the user or team.
-6. Leave a lightweight record of decisions
-   - Supplement ADR/change records or hand off to the document sync process when conclusions impact public interfaces, dependency versions, catalog specifications or team workflows.
-
-## Local Knowledge Retrieval
-
-When the user specifies the local knowledge base path, or the default `knowledge/` directory exists, this process can be used to answer database questions, extract evidence, or assist decision-making.
-
-1. Locate the root directory
-   - Use this path when the user explicitly specifies the path.
-   - Otherwise, check whether `knowledge/` under the current project exists; if it does not exist, it means that the default knowledge base is not found and the path is requested.
-   - No need to use file glob to determine whether the directory exists.
-
-2. Hierarchical navigation
-   - Read `data_structure.md` in the root directory and subdirectories first.
-   - Select the most relevant few branches according to the directory description, without traversing the entire knowledge base at once.
-   - Document candidate files, topics, time/version range and why they are relevant.
-
-3. Progressive search
-   - Markdown, text, log: first search with keywords, and then partially read the hit context.
-   - PDF: Confirm the available tools and extraction routes before processing, and prioritize extraction of temporary text before retrieval to avoid putting the entire PDF into context.
-   - Excel: Confirm the read/analysis route before processing, first look at the worksheet, column names and a few samples, and then filter or aggregate by field.
-   - Default to up to 5 rounds of keyword iteration; each round adjusts synonyms, abbreviations, and scope based on found evidence.
-
-4. Answer and traceability
-   - Give the conclusion first, and then list the file path, chapter, page number, worksheet or line number as a basis.
-   - If there is insufficient evidence, explain which paths have been checked, what information is missing, and how the user can narrow down the scope.
-   - Do not mix online information from outside the knowledge base into answers unless the user requests otherwise to check external sources.
-
-## Source Priority
-
-| Priority | Source | Use |
-| -------- | ------ | --- |
-| 1 | Configuration, testing, and implementation within the project | Determine the true agreement of this warehouse |
-| 2 | Official documents, source code, type definitions | Determine current recommended behavior |
-| 3 | Standard specifications, browser compatibility data | Determine platform capabilities and compatibility boundaries |
-| 4 | Issues, discussions, third-party articles | Auxiliary investigation, cannot be finalized alone |
-
-## Constraints
-
-- Don't give version-sensitive conclusions from memory.
-- Do not treat outdated tutorials as current best practices.
-- Do not cite sources that cannot be reviewed as critical evidence.
-- Do not change the stable project agreement to pursue new developments; the benefits and migration costs must be explained.
-- Do not copy long external documents in the delivery; keep only necessary conclusions and links or file paths.
-- Don't just say "checked the documentation"; version-sensitive decisions need to be traceable to a specific version, path or official page.
-
-## Expected Output
-
-Output source lists, version or project facts, decision conclusions, implementation impacts, validation orders, and open risks. If code is modified, key behaviors should be supported by tests or build verification.