用于审查或改进前端无障碍、语义结构、键盘支持、焦点管理、ARIA 标签、屏幕阅读器行为、WCAG 2.2 问题、触控无障碍或辅助技术回归；中文触发词包括 无障碍、accessibility、a11y、WCAG、屏幕阅读器。
The English summary is being prepared. Showing the original description.
bovinphang/frontend-craft22Updated Sep 26, 2026
FreePublished on GitHub
fec-debug-framework
用于诊断前端构建失败、运行时错误、UI 异常、API/数据问题、白屏、请求失败或难以解释的线上异常；中文触发词包括 调试、debug、排查、定位、报错、异常、白屏、请求失败。
The English summary is being prepared. Showing the original description.
See how to installFiles included (2)
- SKILL.md4.8 KB
- references/report-template.md1.2 KB
SKILL.md (original)
Review the instructions the agent will receive before you install.
前端诊断框架
用途
用证据驱动的分类、收集、假设、验证和修复流程定位前端故障，避免凭直觉扩大改动范围。
流程
所有前端问题诊断遵循统一流程：
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。
约束
- 不在缺少证据时猜测根因
- 不通过关闭规则、删除测试或降低类型安全来「修复」
- 每次只改一个变量来验证假设
- 不在验证前扩大改动范围
- 同一假设连续 3 次验证失败，停止并报告阻塞
预期输出
- 诊断报告保存为
reports/debug-YYYY-MM-DD-HHmmss.md - 报告包含问题类型、关键证据、假设验证记录、根因、修复内容、验证结果和剩余风险
- build/runtime/ui/api 问题均能说明复现路径、验证命令或下一步阻塞点
Reviews
No reviews yet. Tell others what you thought.
Comments
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
More skills from this repository
Use when reviewing or improving frontend accessibility, semantic structure, keyboard support, focus management, ARIA labels, screen reader behavior, WCAG 2.2 issues, touch accessibility, or assistive-technology regressions; Chinese triggers include accessibility, accessibility, a11y, WCAG, screen reader.
The English summary is being prepared. Showing the original description.
bovinphang/frontend-craft22Updated Sep 26, 2026
fec-alchemy
FreeUse when absorbing ideas, capabilities, workflows, architecture, quality systems, ecosystem extensions, or engineering practices from any reference system into the current project through original, project-native redesign rather than copying.
The English summary is being prepared. Showing the original description.
bovinphang/frontend-craft22Updated Sep 26, 2026
fec-alchemy
Free用于从参考系统中吸收想法、能力、工作流、架构、质量体系、生态扩展或工程实践，并通过原创的项目内重设计转化为当前项目能力，而不是复制原实现。
The English summary is being prepared. Showing the original description.
bovinphang/frontend-craft22Updated Sep 26, 2026
Use when designing, implementing, or reviewing frontend-to-backend API integration, typed API clients, REST/tRPC/OpenAPI client choices, auth refresh, API error mapping, upload flows, SSE/WebSocket/polling choices, CORS-facing frontend behavior, or cross-boundary loading/error states. Do not use for backend-only service architecture or TanStack Query cache policy alone; Chinese triggers include API integration, front-end and back-end joint debugging, typed API client, Interface error handling, SSE, WebSocket.
The English summary is being prepared. Showing the original description.
bovinphang/frontend-craft22Updated Sep 26, 2026
用于设计、实现或审查前后端 API 集成、类型化 API client、REST/tRPC/OpenAPI 客户端选型、认证刷新、API 错误映射、上传流程、SSE/WebSocket/轮询选择、CORS 相关前端行为或跨边界 loading/error 状态。不要用于纯后端服务架构或仅 TanStack Query 缓存策略；中文触发词包括 API 集成、前后端联调、typed API client、接口错误处理、SSE、WebSocket。
The English summary is being prepared. Showing the original description.
bovinphang/frontend-craft22Updated Sep 26, 2026