@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/skills/fec-alchemy/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: fec-alchemy
+description: Use 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.
+---
+
+# 项目吸收与原创化融合
+
+## Purpose
+
+将一个或多个参考系统中的优秀思想、能力和工程实践，转化为当前项目中原创、可维护、符合目标项目风格的改进。
+
+适用于吸收、借鉴、对标、迁移或融合另一个代码库、产品、框架、库、服务、CLI、插件、文档体系、AI/Agent 工具链、架构或工程工作流。普通 Bug 修复、单独 API 使用问题或直接文件格式转换不应使用本 Skill，除非用户明确要求项目级吸收或适配。
+
+## Procedure
+
+1. 明确目标和参考系统：
+   - 将当前仓库视为目标系统，它的架构、命名、测试、发布模型和维护边界是事实来源。
+   - 将外部仓库、上传压缩包、文档、示例、产品描述或运行体验视为参考系统，它们只提供证据和启发。
+   - 识别吸收范围：产品能力、架构模式、领域模型、接口协议、数据流、运行时行为、开发体验、质量体系、交付流程、文档知识或生态扩展。
+   - 信息较多时可使用 [assets/intake-template.md](assets/intake-template.md) 建立简要清单。
+2. 建立目标项目基线：
+   - 先读取目标项目 README、包元数据、目录结构、配置、现有入口、扩展点、测试命令和发布说明。
+   - 找出目标项目已有类似能力，判断应增强、合并、替换、拆分、文档化还是新增。
+3. 扫描参考项目：
+   - 优先查看 README、包元数据、源码布局、项目形态相关目录、关键模块、测试、示例和发布说明。
+   - 将观察记录为能力、意图、模式和取舍，不记录为要复制的文件清单。
+4. 提炼候选能力：
+   - 对每个候选项说明它解决的问题、用户价值、适配度、依赖、风险、可验证性和与目标项目现状的关系。
+   - 对许可证、来源不清楚或实现高度绑定参考项目的候选项，只提炼思想，不复用表达。
+5. 映射到目标架构：
+   - 使用目标项目原生命名、模块边界、依赖策略、编码约定和测试方式重新设计。
+   - 避免创建与现有模块竞争的并行系统；避免因为参考项目用了某依赖就盲目引入依赖。
+   - 非平凡变更可使用 [assets/absorption-plan-template.md](assets/absorption-plan-template.md)。
+6. 原创化实现或计划：
+   - 编写新代码或新文档，不复制参考项目中的非平凡代码、提示词、配置或文档表达。
+   - 吸收生态扩展、提示词、命令、插件、自动化、Agent 或规则时，统一职责边界并删除重复指令。
+   - 大型任务先交付垂直薄切片，并记录被拒绝或延期的候选项。
+7. 验证和汇报：
+   - 运行最相关的类型检查、Lint、测试、构建、文档校验或 Skill 校验。
+   - 如果无法验证，明确说明阻塞原因、风险范围和需要用户确认的信息。
+   - 必要时使用 [assets/review-checklist.md](assets/review-checklist.md) 做人工复核。
+
+## Constraints
+
+- 不把吸收任务变成机械化 diff 合并。
+- 不整体照搬参考项目的命名体系、文件结构或实现细节。
+- 不在许可证或用户意图不明确时逐字复用参考项目中的非平凡代码、文档、提示词或配置。
+- 不为了匹配参考项目而削弱安全、隐私、权限边界、测试、可维护性或目标项目产品方向。
+- 不声称原创化，除非输出能解释目标设计为何不同、为何适配目标项目、如何验证。
+- 不把长篇参考材料塞进主说明；大型任务读取 [references/methodology.md](references/methodology.md)，许可证和原创风险读取 [references/originality-and-licensing.md](references/originality-and-licensing.md)。
+
+## Expected Output
+
+分析类任务输出：
+
+- 吸收候选项
+- 推荐目标设计
+- 实现计划
+- 风险与许可证说明
+- 验证清单
+
+实现类任务输出：
+
+- 已完成变更
+- 原创化说明
+- 验证结果
+- 剩余工作
+
+仓库级任务中，如果宿主工具支持文件编辑，应创建或更新项目本地计划文档。
+
+## 详细参考
+
+- [references/methodology.md](references/methodology.md) - 详细吸收方法论。
+- [references/originality-and-licensing.md](references/originality-and-licensing.md) - 原创性、许可证和来源风险约束。

package/skills/fec-alchemy/assets/absorption-plan-template.md

@@ -0,0 +1,47 @@
+# Alchemy 吸收计划
+
+## 目标
+
+描述需要交付的目标项目原生化改进。
+
+## 参考项目优势
+
+| 候选项 | 参考洞察 | 目标项目缺口 | 策略 | 优先级 |
+|---|---|---|---|---|
+|  |  |  | 增强 / 新增 / 拆分 / 合并 / 替换 / 文档化 / 拒绝 |  |
+
+## 目标设计
+
+- 目标架构落点：
+- 用户可见能力：
+- 公开 API / CLI / 配置 / UI 入口：
+- UI / API / 数据 / 运行时 / 工具链 / 文档影响：
+- 公开 API 或用户可见行为：
+- 内部数据流：
+- 命名和约定：
+- 依赖影响：
+- 向后兼容性：
+
+## 实现步骤
+
+1.
+2.
+3.
+
+## 验证
+
+- 类型检查：
+- Lint：
+- 单元测试：
+- 集成测试：
+- 构建：
+- 人工评审：
+
+## 风险
+
+- 许可证 / 来源：
+- 范围膨胀：
+- 架构重叠：
+- 性能：
+- 安全：
+- 维护：

package/skills/fec-alchemy/assets/intake-template.md

@@ -0,0 +1,55 @@
+# Alchemy 信息收集模板
+
+## 目标项目
+
+- 路径 / URL：
+- 项目定位：
+- 项目类型：
+- 主要用户：
+- 技术栈：
+- 当前相关模块：
+- 已有类似能力：
+- 目标项目适配边界：
+- 验证命令：
+- 约束条件：
+
+## 参考项目
+
+- 路径 / URL：
+- 项目定位：
+- 项目类型：
+- 主要用户：
+- 技术栈：
+- 重点模块：
+- 特色能力：
+- 许可证 / 来源：
+- 风险：
+
+## 能力域清单
+
+- 产品能力：
+- 架构模式：
+- 领域模型：
+- 接口协议：
+- 数据流：
+- 运行时行为：
+- 开发体验：
+- 质量体系：
+- 交付流程：
+- 文档知识：
+- 生态扩展：
+
+## 项目形态探针
+
+- 前端项目（页面 / 组件 / 路由 / 状态 / 数据请求 / 表单 / 设计系统 / 可访问性 / 性能 / 构建）：
+- 后端项目（API / 服务边界 / 数据库 / 队列 / 缓存 / 认证授权 / 任务调度 / 可观测性 / 部署）：
+- 工具或 CLI 项目（命令模型 / 配置 / 插件机制 / 错误输出 / 安装分发 / 模板）：
+- AI/Agent 项目（skills / commands / hooks / rules / agents / MCP / prompt / workflow）：
+- 库项目（公开 API / 类型 / 兼容性 / 构建产物 / 示例 / 版本策略）：
+- 文档或知识库项目（信息架构 / 导航 / 示例 / 搜索 / 版本化 / 贡献流程 / 发布节奏）：
+
+## 不吸收范围
+
+- 明确拒绝：
+- 延后观察：
+- 只作为灵感不落地：

package/skills/fec-alchemy/assets/review-checklist.md

@@ -0,0 +1,31 @@
+# Alchemy 评审检查清单
+
+## 架构
+
+- [ ] 变更属于选定的目标模块。
+- [ ] 没有重复实现已有能力、入口、抽象或用户工作流。
+- [ ] 职责清晰且不重叠。
+- [ ] 命名符合目标项目语义。
+- [ ] 目标架构落点清晰，未为了参考项目形态引入并行体系。
+- [ ] 配置、运行时流程、工具函数和文档承诺没有互相冲突。
+
+## 原创性
+
+- [ ] 不存在缺少许可证依据的非平凡复制代码或文本。
+- [ ] 实现已用目标项目原生风格表达。
+- [ ] 参考项目影响被总结为思想、模式或行为。
+- [ ] 如许可证要求，已保留必要署名。
+
+## 质量
+
+- [ ] 测试或验证步骤覆盖了被吸收的行为。
+- [ ] 错误与边界场景已处理。
+- [ ] 依赖新增有充分理由。
+- [ ] 文档和示例已更新。
+- [ ] 选用的项目形态探针与实际目标相关，没有做无关全量扫描。
+
+## 交付
+
+- [ ] 已总结面向用户的变更。
+- [ ] 已说明被拒绝的候选项。
+- [ ] 已记录风险和后续工作。

package/skills/fec-alchemy/references/methodology.md

@@ -0,0 +1,94 @@
+# 项目吸收方法论
+
+## 目标
+
+本文档用于扩展 `SKILL.md` 中的核心流程，适合更大型的“参考系统到目标项目”能力吸收任务。参考系统可以是代码库、产品、服务、框架、库、CLI、插件、文档体系或 AI/Agent 工具链。
+
+## 阶段 1：建立目标项目基线
+
+在深入研究参考项目之前，先为目标项目建立简短基线：
+
+- 目标项目声明的用途是什么？
+- 当前已有的顶层能力有哪些？
+- 已存在的入口、扩展点和用户工作流有哪些？
+- 哪些区域仍在活跃维护？
+- 哪些区域脆弱、复杂或过度设计？
+- 已有哪些测试和验证命令？
+
+在理解目标项目基线之前，不要过早形成改造建议。
+
+## 阶段 2：扫描参考项目
+
+扫描参考系统中的高信号材料：
+
+- README 和文档：项目定位、使用模型、安装、配置。
+- 包或构建元数据：技术选型、依赖范围、脚本命令。
+- 源码布局：架构、模块边界、命名约定。
+- 能力域：产品能力、架构模式、领域模型、接口协议、数据流、运行时行为、开发体验、质量体系、交付流程、文档知识、生态扩展。
+- 项目形态探针：按参考系统类型选择相关目录和行为入口，不假设所有项目都有相同结构。
+- 测试：预期行为和边界场景。
+- 示例：面向用户的工作流和上手体验质量。
+
+记录观察时，应记录为“能力”，而不是“文件”。例如写“具备带环境检查的引导式配置向导”，而不是写“复制 setup.ts”。
+
+### 项目形态探针
+
+按目标和参考系统的实际形态选择扫描视角：
+
+- 前端项目：页面、组件、路由、状态、数据请求、表单、设计系统、可访问性、性能、构建。
+- 后端项目：API、服务边界、数据库、队列、缓存、认证授权、任务调度、可观测性、部署。
+- 工具或 CLI 项目：命令模型、配置、插件机制、错误输出、安装分发、模板。
+- AI/Agent 项目：skills、commands、hooks、rules、agents、MCP、prompt、workflow。
+- 库项目：公开 API、类型、兼容性、构建产物、示例、版本策略。
+- 文档或知识库项目：信息架构、导航、示例、搜索、版本化、贡献流程、发布节奏。
+
+如果项目横跨多种形态，优先选择与用户目标直接相关的 1 到 3 个视角，避免把吸收任务扩大成全仓库审计。
+
+## 阶段 3：候选能力评分
+
+对每个候选项按 1 到 5 分评分。
+
+| 维度 | 问题 |
+|---|---|
+| 用户价值 | 是否能实质改善目标用户的工作流？ |
+| 适配度 | 是否符合目标项目的架构和路线图？ |
+| 原创化可行性 | 是否可以在不复制受保护表达的情况下重新创建？ |
+| 复杂度 | 是否可以安全交付并长期维护？ |
+| 可验证性 | 正确性是否可以通过测试或评审验证？ |
+
+优先处理高价值、高适配、低风险的候选项。
+
+## 阶段 4：吸收策略
+
+为每个候选项选择一种策略：
+
+- **增强**：改进目标项目已有能力。
+- **新增**：引入新的目标项目原生能力。
+- **拆分**：拆解过载的目标概念或参考概念。
+- **合并**：合并目标项目中重叠的概念。
+- **替换**：在更安全设计准备好后，移除较弱的目标实现。
+- **文档化**：只补充知识，不改代码。
+- **拒绝**：明确延后或放弃，并说明原因。
+
+## 阶段 5：实现顺序
+
+推荐按以下顺序推进：
+
+1. 文档和边界澄清。
+2. 测试或验证脚手架。
+3. 最小化的目标项目原生实现。
+4. 与现有工作流集成。
+5. 清理重复逻辑和废弃路径。
+6. 面向用户的文档和示例。
+
+## 阶段 6：评审问题
+
+最终完成前，回答以下问题：
+
+- 吸收后目标项目是否仍保持一致性？
+- 模块边界是否被保留或改善？
+- 每个新增能力是否可被发现？
+- 是否存在重叠的能力、入口、抽象、配置、运行时流程、工具函数、文档承诺或用户工作流？
+- 新增依赖是否有充分理由？
+- 验证命令是否已记录？
+- 是否透明说明了灵感来源，同时又没有暗示复制代码？

package/skills/fec-alchemy/references/originality-and-licensing.md

@@ -0,0 +1,57 @@
+# 原创性与许可证约束
+
+## 目标
+
+本流程用于合法、合规、伦理且可维护的适配。它应帮助使用者提炼思想，并重新创建符合目标项目风格的设计，而不是伪装复制。
+
+## 通常可以安全吸收的内容
+
+- 高层思想和产品概念。
+- 通用架构模式。
+- 公开文档化的工作流。
+- 用自己的语言表达的行为需求。
+- 标准的、不可保护的或已获得适当许可的算法和技术。
+- 为目标环境重新创建的配置概念。
+
+## 需要谨慎处理的内容
+
+- 来自其他项目的大段代码。
+- 独特文本、提示词、示例、文档、图表、名称或品牌表达。
+- 与参考项目高度绑定且非显而易见的实现结构。
+- 包含许可证头或署名要求的生成文件。
+- 带有限制性许可证的依赖。
+- 私有或专有仓库。
+
+## 安全适配流程
+
+1. 用中性语言总结参考能力。
+2. 识别它解决的问题。
+3. 独立设计目标项目原生方案。
+4. 使用目标项目约定实现新代码。
+5. 将概念命名调整为目标项目语义。
+6. 基于期望行为添加测试，而不是基于参考项目内部实现添加测试。
+7. 当许可证要求署名时，保留必要署名。
+8. 将许可证不确定性记录为风险，而不是忽略。
+
+## 风险信号
+
+- 输出在没有目标项目特定理由的情况下保留了参考项目相同的文件结构和命名。
+- 输出包含大量完全相同或近似相同的代码/文本。
+- Agent 无法解释目标设计为什么不同于参考设计。
+- 新模块与目标项目现有模块高度重叠。
+- 唯一理由只是“参考项目就是这样做的”。
+
+## 报告中的推荐表述
+
+建议使用：
+
+- “受参考项目在……方面的处理方式启发。”
+- “已重新实现为符合目标项目风格的模块，用于……”
+- “参考项目通过 X 解决该问题；本项目选择 Y，因为……”
+
+避免使用：
+
+- “复制自……”
+- “和……完全一样”
+- “隐藏式模仿……”
+- “让它看起来不相关……”

package/skills/fec-backend-requirements-handoff/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fec-backend-requirements-handoff
+description: Use when frontend work needs to communicate data, action, state, permission, validation, or business-rule needs to backend teams without dictating endpoint design, field names, database shape, or implementation details; Chinese triggers include 前后端需求交接, 后端需求, API 需求澄清, 数据需求说明.
+---
+
+# 前后端需求交接
+
+## Purpose
+
+把前端页面和交互所需的数据、动作、状态和疑问整理成后端可讨论的需求说明。
+
+## Procedure
+
+1. 明确功能上下文
+   - 说明页面、流程或组件是什么，面向哪类用户，以及用户完成任务的成功状态。
+   - 如果已有设计稿、路由、用户故事或权限角色，先把它们作为事实来源。
+
+2. 描述前端展示需求
+   - 按屏幕或组件列出需要展示的信息、信息之间的关系、排序/过滤/分页需求和可见性规则。
+   - 使用业务语言描述“需要展示什么”，不要提前规定 endpoint、字段名、DTO、数据库表或响应嵌套结构。
+
+3. 描述用户动作和结果
+   - 列出用户能执行的动作、期望结果、成功反馈、失败反馈和是否需要乐观更新。
+   - 标出幂等性、撤销、确认、危险操作、批量操作或长任务进度等对 UI 有影响的行为。
+
+4. 补齐状态和业务规则
+   - 覆盖 loading、empty、error、partial、permission denied、expired、conflict、offline 和 retrying 等状态。
+   - 记录影响 UI 的权限、生命周期、金额/时区/枚举、校验、可编辑条件和边界规则。
+
+5. 输出讨论文档
+   - 默认写到 `docs/backend-requirements/<feature-name>.md`；若仓库已有需求文档目录，沿用现有位置。
+   - 文档包含 Context、Screens/Components、Data Needs、User Actions、UI States、Business Rules、Uncertainties、Questions for Backend 和 Decision Log。
+   - 若用户只需要聊天回复，可以直接输出同样结构的 Markdown，不创建文件。
+
+## Constraints
+
+- 不替后端规定 URL、HTTP 方法、字段名、数据库 schema、缓存实现或服务拆分。
+- 不把前端猜测写成事实；不确定的业务规则必须进入 Uncertainties 或 Questions。
+- 不忽略错误、空态、权限和部分数据；这些状态决定接口协作质量。
+- 不把内部错误栈、数据库字段或敏感实现细节要求暴露给 UI。
+- 不与 API 集成流程重复：本 skill 描述需求，客户端边界、类型来源和错误映射实现应在后续实现阶段处理。
+
+## Expected Output
+
+产出一份前端视角的后端需求交接说明，清楚描述 UI 需要什么数据和行为、哪些规则仍需确认，以及后续前后端需要共同决定的问题。

package/skills/fec-browser-storage/SKILL.md

@@ -17,7 +17,7 @@ description: Use when choosing, implementing, or reviewing browser storage such
 4. 敏感数据按安全规则处理，不把明文 token、密码、信用卡信息放进可被 JS 读取的存储。
 5. 审查隐私模式、存储配额、清理策略和跨浏览器兼容性。
 
-## Detailed References
+## 详细参考
 
 涉及存储选型表、localStorage/sessionStorage 封装、IndexedDB 示例、Cookie 辅助方法和敏感数据规则时，加载 [references/storage-patterns.md](references/storage-patterns.md)。
 

package/skills/fec-canvas-threejs/SKILL.md

@@ -45,7 +45,7 @@ return () => {
 };
 ```
 
-## Detailed References
+## 详细参考
 
 涉及 Canvas 2D 绘图、动画循环、Three.js 场景搭建、React Three Fiber、InstancedMesh 和性能清理时，加载 [references/rendering-patterns.md](references/rendering-patterns.md)。
 

package/skills/fec-code-review/SKILL.md

@@ -9,7 +9,7 @@ description: Use when the user asks for general frontend code review, PR review,
 
 从架构、类型安全、可访问性、样式一致性、性能和可测试性等 8 个维度审查前端代码质量，输出分级评审报告。
 
-## Review Process
+## Procedure
 
 1. 先读项目事实：package scripts、框架、目录约定、最近 diff、现有测试和相关规则。
 2. 按风险找问题，而不是按个人偏好挑风格；每个发现都要能指向具体文件、行号和用户影响。
@@ -24,7 +24,7 @@ description: Use when the user asks for general frontend code review, PR review,
 
 | 维度                | 触发条件                                             | 分流边界                             |
 | ------------------- | ---------------------------------------------------- | ------------------------------------ |
-| TypeScript 类型安全 | DTO、泛型、公共类型、类型守卫、`any`、断言           | 深入类型建模交给类型安全专项流程     |
+| TypeScript 工程与类型契约 | DTO、泛型、公共类型、类型守卫、`any`、断言、tsconfig | 深入类型建模和 TS 配置交给 TypeScript 流程 |
 | 状态管理            | 状态归属、全局 store、URL 状态、派生状态、跨页面同步 | 状态选型与迁移交给状态管理专项流程   |
 | 安全                | 用户输入、HTML 渲染、token、上传、第三方脚本         | 漏洞级分析交给安全专项流程           |
 | 无障碍              | 弹窗、菜单、表单、键盘操作、焦点管理                 | WCAG 细查交给无障碍专项流程          |
@@ -121,10 +121,18 @@ description: Use when the user asks for general frontend code review, PR review,
 - [ ] 命名语义清晰
 - [ ] 注释覆盖复杂逻辑
 
-## Detailed References
+## 详细参考
 
 撰写代码评审报告时，加载 [references/report-template.md](references/report-template.md)。发现必须具体且可操作；不要写"优化性能"等空泛建议而不指出具体代码模式。
 
+## Constraints
+
+- 不把个人风格偏好写成阻塞问题；阻塞项必须有明确用户影响、运行时风险、安全风险或维护成本证据。
+- 不在缺少 diff、文件位置或复现线索时给确定结论。
+- 深度安全、无障碍、E2E 和性能问题只做初筛；需要证据链时分流到专项 skill。
+- 同一根因不要重复报多条；合并为一条代表性发现并列出影响范围。
+- 自动化工具稳定覆盖的格式问题交给 lint/format，不作为人工评审主发现。
+
 ## Expected Output
 
 - 分级评审报告（CRITICAL / HIGH / MEDIUM / LOW）

package/skills/fec-data-fetching/SKILL.md

@@ -1,23 +1,23 @@
 ---
 name: fec-data-fetching
-description: Use when implementing or reviewing TanStack Query/React Query server-state flows: typed queries, query keys, caching, invalidation, mutations, optimistic updates, infinite queries, prefetch, SSR hydration, or API-layer integration. Do not use for local UI state or Service Worker caching; Chinese triggers include 数据获取, 缓存, 乐观更新.
+description: Use when implementing or reviewing frontend server-state flows: typed queries, request caching, invalidation, mutations, optimistic updates, infinite queries, prefetch, SSR hydration, or API-layer integration. Do not use for local UI state or Service Worker caching; Chinese triggers include 数据获取, 缓存, 乐观更新.
 ---
 
-# TanStack Query 数据获取
+# Server State 数据获取
 
 ## Purpose
 
-用声明式 server state 管理替代手写 `useEffect + loading`。
+为前端 server state 建立清晰的数据获取、缓存、失效和提交边界，避免请求状态散落在页面组件中。
 
 ## Procedure
 
-1. 判断状态来源：来自服务端且需要缓存、去重、刷新、分页或 mutation 时使用 TanStack Query；纯本地 UI 状态用 `useState`/store。
-2. 建立 `QueryClientProvider`，按业务数据新鲜度设置 `staleTime`、`gcTime`、retry 和窗口聚焦刷新。
-3. 设计稳定 query key：数组结构包含实体、动作和所有影响结果的参数。
-4. API 函数保持纯请求函数，Query hook 负责缓存、select、loading/error/empty 状态。
-5. mutation 成功后 invalidation；需要即时反馈时使用 optimistic update 并在 `onError` 回滚。
+1. 判断状态来源：来自服务端且需要缓存、去重、刷新、分页或 mutation 时使用请求缓存方案；纯本地 UI 状态用组件 state 或 store。
+2. 先沿用项目已有数据获取库；新增依赖时 React/Vue/Solid/Svelte 可考虑 TanStack Query，也可沿用 SWR、Nuxt/Nitro 数据获取或项目封装。
+3. 设计稳定 cache key/query key：结构包含实体、动作和所有影响结果的参数。
+4. API 函数保持纯请求函数，数据 hook/composable 负责缓存、select、loading/error/empty 状态。
+5. mutation 成功后 invalidation；需要即时反馈时使用 optimistic update 并在失败时回滚。
 
-## Quick Start
+## React Quick Start
 
 ```tsx
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -45,17 +45,17 @@ export function useCreateUser() {
 }
 ```
 
-## Detailed References
+## 详细参考
 
-涉及 QueryClient 默认配置、乐观更新、无限滚动查询、预取、SSR 水合和 API 层整合时，加载 [references/query-patterns.md](references/query-patterns.md)。
+涉及是否需要查询库、QueryClient 默认配置、Vue adapter、乐观更新、无限滚动查询、预取、SSR 水合和 API 层整合时，加载 [references/query-patterns.md](references/query-patterns.md)。
 
 ## Constraints
 
-- 相同数据必须复用相同 query key；参数缺失会造成缓存串读。
+- 相同数据必须复用相同 cache key/query key；参数缺失会造成缓存串读。
 - `staleTime` 过长会显示旧数据，过短会造成频繁请求。
-- TanStack Query 不管理本地 UI 状态；不要把 modal、输入框值放进 query cache。
-- 乐观更新必须保存快照并在 `onError` 回滚。
-- Next.js App Router SSR 需要 `dehydrate` / `HydrationBoundary`。
+- 请求缓存库不管理本地 UI 状态；不要把 modal、输入框值放进 query cache。
+- 乐观更新必须保存快照并在失败时回滚。
+- SSR/SSG 场景必须使用框架支持的预取、水合或服务端数据边界。
 
 ## Expected Output
 

package/skills/fec-data-fetching/references/query-patterns.md

@@ -1,4 +1,30 @@
-# TanStack Query 进阶模式
+# Server State 数据获取模式
+
+## 先判断是否需要查询库
+
+- 简单静态请求、一次性提交或已有框架 loader 足够表达的页面，不必默认引入查询库。
+- 需要跨组件缓存、去重、后台刷新、分页、乐观更新、预取或 SSR hydration 时，再使用 TanStack Query、SWR、Nuxt 数据获取或项目既有请求缓存方案。
+- 查询库只管理 server state，不替代本地 UI 状态、表单状态、权限判断或 Service Worker 缓存。
+
+## 选型参考
+
+先沿用仓库已有请求层和缓存方案；新增依赖时再按框架与复杂度选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| React server state | TanStack Query / SWR / 项目既有封装 | TanStack Query 适合 mutation、invalidation 和无限查询；SWR 适合轻量读取缓存。 |
+| Vue server state | TanStack Query Vue adapter / VueUse / Nuxt `useFetch` / 项目既有封装 | 不要让 Vue 项目照搬 React-only hook 示例。 |
+| Solid / Svelte / 跨框架 | TanStack Query 对应 adapter 或项目既有资源层 | cache key、staleTime、mutation 回滚原则保持一致。 |
+| 简单页面请求 | 框架 loader、组件内轻量请求或 API composable | 仍要处理 loading/error/empty 和取消或过期响应。 |
+| SSR / SSG | 框架预取、水合或服务端数据边界 | 确保服务端 key 与客户端 key 一致，避免重复请求和水合错配。 |
+
+## 通用边界
+
+- API 函数只负责请求、解析和错误归一化，不包含 UI toast、loading 或缓存逻辑。
+- cache key/query key 必须包含所有影响响应的参数。
+- mutation 成功后按实体或列表失效；乐观更新必须先保存快照，失败时回滚。
+- 无限查询只处理数据分页；DOM 虚拟化由列表虚拟化流程处理。
+- 预取要有明确用户路径或首屏收益，不为所有可能数据提前请求。
 
 ## QueryClient 默认配置
 

package/skills/fec-debug-framework/SKILL.md

@@ -5,7 +5,11 @@ description: Use when diagnosing frontend build failures, runtime errors, UI ano
 
 # 前端诊断框架
 
-## 核心方法论（5 步法）
+## Purpose
+
+用证据驱动的分类、收集、假设、验证和修复流程定位前端故障，避免凭直觉扩大改动范围。
+
+## Procedure
 
 所有前端问题诊断遵循统一流程：
 
@@ -134,29 +138,20 @@ description: Use when diagnosing frontend build failures, runtime errors, UI ano
 
 ---
 
-## 报告格式
-
-保存至 `reports/debug-YYYY-MM-DD-HHmmss.md`：
-
-### 诊断报告
+## 详细参考
 
-| 项目       | 内容                       |
-| ---------- | -------------------------- |
-| 问题类型   | build / runtime / ui / api |
-| 问题描述   | 用户报告的现象             |
-| 收集的证据 | 关键日志、截图、请求记录   |
-| 假设与验证 | 每个假设的验证结果         |
-| 根因       | 最终确认的根本原因         |
-| 修复内容   | 修改的文件和具体改动       |
-| 验证结果   | 修复后的验证命令和结果     |
-| 剩余风险   | 未覆盖的边界或潜在回归     |
+撰写诊断报告时，加载 [references/report-template.md](references/report-template.md)。
 
----
-
-## 强约束
+## Constraints
 
 - 不在缺少证据时猜测根因
 - 不通过关闭规则、删除测试或降低类型安全来「修复」
 - 每次只改一个变量来验证假设
 - 不在验证前扩大改动范围
 - 同一假设连续 3 次验证失败，停止并报告阻塞
+
+## Expected Output
+
+- 诊断报告保存为 `reports/debug-YYYY-MM-DD-HHmmss.md`
+- 报告包含问题类型、关键证据、假设验证记录、根因、修复内容、验证结果和剩余风险
+- build/runtime/ui/api 问题均能说明复现路径、验证命令或下一步阻塞点

package/skills/fec-debug-framework/references/report-template.md

@@ -0,0 +1,58 @@
+# 诊断报告模板
+
+```markdown
+# 前端诊断报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 问题类型: build / runtime / ui / api
+> 影响范围: 页面、功能、用户群或环境
+
+## 问题描述
+
+- 用户报告或观察到的现象
+- 首次出现时间、环境、分支或版本
+
+## 复现路径
+
+1. 操作步骤或触发命令
+2. 期望结果
+3. 实际结果
+
+## 收集的证据
+
+- 日志 / stderr / console stack
+- 截图、DOM、样式、网络请求或 trace
+- 相关配置、依赖版本、环境变量或状态快照
+
+## 假设与验证
+
+| 假设 | 验证方法 | 结果 |
+| --- | --- | --- |
+| 因为 X，导致 Y | 通过 Z 验证 | 证实 / 证伪 / 待定 |
+
+## 根因
+
+- 最终确认的根本原因
+- 为什么已有证据能支持该结论
+
+## 修复内容
+
+- 修改的文件和行为
+- 为什么这是最小有效修复
+
+## 验证结果
+
+- 执行的命令、手工路径或浏览器验证
+- 修复后观察到的结果
+
+## 剩余风险
+
+- 未覆盖的边界
+- 可能回归的区域
+
+## 下一步
+
+- 需要用户决策、后续任务或监控项
+```
+
+诊断完成后，将报告保存到 `reports/debug-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。