@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/localized/zh-CN/skills/fec-accessibility-check/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: fec-accessibility-check
+description: 用于审查或改进前端无障碍、语义结构、键盘支持、焦点管理、ARIA 标签、屏幕阅读器行为、WCAG 2.2 问题、触控无障碍或辅助技术回归；中文触发词包括 无障碍、accessibility、a11y、WCAG、屏幕阅读器。
+---
+
+# 无障碍实现规范（WCAG 2.2 AA）
+
+## 用途
+
+确保前端 UI 对残障用户可访问，满足 WCAG 2.2 AA 的核心要求，并能被键盘、屏幕阅读器、触控和缩放用户稳定使用。
+
+## 流程
+
+1. 检查语义结构：landmark、标题层级、表单 label、按钮/链接可访问名称、表格语义和图片 alt。
+2. 检查键盘路径：Tab 顺序、Enter/Space/Esc 行为、焦点可见、关闭后焦点恢复。
+3. 检查复杂组件：对话框、菜单、标签页、树、抽屉、表格和自定义控件的 ARIA 状态。
+4. 检查动态状态：loading、empty、error、toast 和异步更新需要被屏幕阅读器感知。
+5. 检查视觉与触控可读性：文本/背景对比、focus ring、缩放到 200%、减少动效偏好、触摸目标尺寸和移动端虚拟键盘行为。
+6. 用真实键盘路径复核关键流程，必要时补充屏幕阅读器或浏览器无障碍树观察；屏幕阅读器流程见 [references/screen-reader-testing.md](references/screen-reader-testing.md)。
+7. 复核 WCAG 2.2 新增高频风险：可见焦点不被遮挡、拖拽操作有替代路径、目标尺寸过小、帮助入口和认证流程不依赖记忆负担。
+8. 输出分级报告；报告格式见 [references/report-template.md](references/report-template.md)。
+
+## 详细参考
+
+撰写无障碍审查报告时，加载 [references/report-template.md](references/report-template.md)。需要验证屏幕阅读器公告、焦点读法和动态区域时，加载 [references/screen-reader-testing.md](references/screen-reader-testing.md)。
+
+## 约束
+
+- 优先使用语义化 HTML，而不是 ARIA。
+- `role` 不应覆盖原生语义。
+- 交互元素必须可键盘访问。
+- 表单错误必须与字段关联。
+- 颜色对比度风险需要指出具体文本/背景组合。
+- 不用 ARIA 弥补可以用原生 HTML 解决的问题。
+- 不把浏览器自动可访问树当作最终结论；关键路径需要用键盘和至少一种辅助技术或等价检查验证。
+
+## 预期输出
+
+交互元素可键盘访问，语义和 ARIA 使用正确，焦点管理稳定；无障碍检查报告保存为 `reports/accessibility-review-YYYY-MM-DD-HHmmss.md`。

package/localized/zh-CN/skills/fec-accessibility-check/references/report-template.md

@@ -0,0 +1,23 @@
+# 无障碍检查报告模板
+
+```markdown
+# 无障碍检查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+> 标准: WCAG 2.2 AA
+
+## 必须修复 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## 建议改进 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## 已通过项
+- ...
+
+## 建议的代码修改
+- ...
+```
+
+检查完成后，将报告保存到 `reports/accessibility-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/localized/zh-CN/skills/fec-accessibility-check/references/screen-reader-testing.md

@@ -0,0 +1,33 @@
+# 屏幕阅读器测试
+
+## 何时测试
+
+以下场景需要使用屏幕阅读器或浏览器无障碍树进行检查：
+
+- 对话框、抽屉、菜单、标签页、组合框、树形控件和自定义控件。
+- 异步状态更新、toast 通知、校验错误和 loading 区域。
+- 表格、虚拟列表、图表、dashboard 和数据密集型控件。
+- 触摸探索、虚拟键盘或焦点顺序可能与桌面不同的移动端流程。
+
+## 最小流程
+
+1. 先只用键盘操作：Tab、Shift+Tab、Enter、Space、Esc，以及适用场景下的方向键。
+2. 在浏览器开发者工具中检查可访问名称、角色、状态和元素关系。
+3. 条件允许时至少跑一轮辅助技术验证：NVDA/Firefox、JAWS/Chrome、VoiceOver/Safari 或 TalkBack/Chrome。
+4. 验证路由变化、校验错误、加载完成和破坏性确认是否有正确公告。
+5. 记录具体用户影响、期望读法、实际读法和建议修复方式。
+
+## 动态内容
+
+- 非阻塞状态更新使用 `aria-live="polite"`。
+- 紧急错误可谨慎使用 `role="alert"`，不要滥用。
+- 只有当用户任务上下文发生变化时才移动焦点，例如打开弹窗或提交后跳转。
+- 关闭浮层后，将焦点恢复到触发控件。
+
+## 常见问题
+
+- 纯图标按钮没有可访问名称。
+- 对话框内容先于标题被朗读，或缺少模态边界。
+- 表单错误只在视觉上展示，没有用 `aria-describedby` 与字段关联。
+- Toast 消失太快，屏幕阅读器用户来不及理解。
+- 虚拟列表行丢失行位置、表格语义或键盘连续性。

package/localized/zh-CN/skills/fec-alchemy/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: fec-alchemy
+description: 用于从参考系统中吸收想法、能力、工作流、架构、质量体系、生态扩展或工程实践，并通过原创的项目内重设计转化为当前项目能力，而不是复制原实现。
+---
+
+# 项目吸收与原创化融合
+
+## 用途
+
+将一个或多个参考系统中的优秀思想、能力和工程实践，转化为当前项目中原创、可维护、符合目标项目风格的改进。
+
+适用于吸收、借鉴、对标、迁移或融合另一个代码库、产品、框架、库、服务、CLI、插件、文档体系、AI/Agent 工具链、架构或工程工作流。普通 Bug 修复、单独 API 使用问题或直接文件格式转换不应使用本 Skill，除非用户明确要求项目级吸收或适配。
+
+## 流程
+
+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) 做人工复核。
+
+## 约束
+
+- 不把吸收任务变成机械化 diff 合并。
+- 不整体照搬参考项目的命名体系、文件结构或实现细节。
+- 不在许可证或用户意图不明确时逐字复用参考项目中的非平凡代码、文档、提示词或配置。
+- 不为了匹配参考项目而削弱安全、隐私、权限边界、测试、可维护性或目标项目产品方向。
+- 不声称原创化，除非输出能解释目标设计为何不同、为何适配目标项目、如何验证。
+- 不把长篇参考材料塞进主说明；大型任务读取 [references/methodology.md](references/methodology.md)，许可证和原创风险读取 [references/originality-and-licensing.md](references/originality-and-licensing.md)。
+
+## 预期输出
+
+分析类任务输出：
+
+- 吸收候选项
+- 推荐目标设计
+- 实现计划
+- 风险与许可证说明
+- 验证清单
+
+实现类任务输出：
+
+- 已完成变更
+- 原创化说明
+- 验证结果
+- 剩余工作
+
+仓库级任务中，如果宿主工具支持文件编辑，应创建或更新项目本地计划文档。
+
+## 详细参考
+
+- [references/methodology.md](references/methodology.md) - 详细吸收方法论。
+- [references/originality-and-licensing.md](references/originality-and-licensing.md) - 原创性、许可证和来源风险约束。

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

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

package/localized/zh-CN/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/localized/zh-CN/skills/fec-alchemy/assets/review-checklist.md

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

package/localized/zh-CN/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/localized/zh-CN/skills/fec-alchemy/references/originality-and-licensing.md

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

package/localized/zh-CN/skills/fec-api-integration/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: fec-api-integration
+description: 用于设计、实现或审查前后端 API 集成、类型化 API client、REST/tRPC/OpenAPI 客户端选型、认证刷新、API 错误映射、上传流程、SSE/WebSocket/轮询选择、CORS 相关前端行为或跨边界 loading/error 状态。不要用于纯后端服务架构或仅 TanStack Query 缓存策略；中文触发词包括 API 集成、前后端联调、typed API client、接口错误处理、SSE、WebSocket。
+---
+
+# API 集成
+
+适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 [integration-patterns.md](references/integration-patterns.md)。
+
+## 用途
+
+规范前端 API 集成边界，让请求、错误、鉴权和实时数据可维护。
+
+## 流程
+
+1. 明确接口所有权
+   - 同团队 TypeScript 全栈可考虑 tRPC 或共享 schema。
+   - 多语言或多消费者 API 优先 OpenAPI/GraphQL codegen。
+   - 小型内部应用可用 typed fetch wrapper，但类型必须集中维护。
+   - 不在组件里散落 `fetch`、URL、header、错误解析和 token 逻辑。
+   - 公共接口需要明确版本、兼容窗口、废弃字段策略和调用方范围。
+
+2. 建立客户端边界
+   - 用一个 API client 处理 base URL、credentials、JSON 解析、超时、取消和统一错误。
+   - 环境变量只读取公开前缀，私密 token 不进入客户端 bundle。
+   - 组件只消费 domain 函数或 query/mutation hook，不直接拼接接口路径。
+   - 204、空响应、非 JSON 错误和网络断开要有明确行为。
+   - TypeScript contract 必须覆盖请求、响应、错误形状和分页/游标元数据。
+
+3. 映射用户可理解的错误
+   - 401：刷新失败后引导登录。
+   - 403：说明权限不足，不重复重试。
+   - 404：展示缺失状态或返回上级入口。
+   - 409：提示冲突和下一步操作。
+   - 422：映射字段级错误。
+   - 429/5xx/网络错误：允许退避重试或展示稍后再试。
+   - 未识别错误要落到统一 fallback，不把原始后端异常暴露给用户。
+   - 所有错误都应归一到用户可恢复动作：重试、重新登录、修改输入、返回上级、联系支持或稍后再试。
+   - 错误对象要保留面向日志的 trace id / request id，但 UI 不暴露内部堆栈、SQL、服务名或敏感字段。
+
+4. 管理接口演进
+   - 兼容新增字段；删除或改名字段必须走迁移期、适配层或双写/双读策略。
+   - 用 schema、类型生成物或 contract test 捕捉破坏性变更。
+   - 对前后端协作项记录状态码、错误码、幂等性、重试语义和时区/金额/枚举规则。
+
+5. 处理鉴权刷新
+   - Access token 生命周期短，refresh 优先放在 httpOnly cookie 或服务端会话。
+   - 401 后只允许单次刷新队列，避免多个请求同时刷新。
+   - 刷新失败要清理本地身份状态并跳转登录。
+   - 不把 bearer token 放在 URL、localStorage 或日志里。
+
+6. 选择上传与实时方案
+   - 小文件可用 multipart；大文件优先预签名直传或分片上传。
+   - 只需要服务端推送时用 SSE；双向协作、聊天或多人状态用 WebSocket。
+   - 简单状态刷新、低频任务进度可用 polling，并设置停止条件。
+   - 上传和实时连接都需要取消、重连、超时和错误 UI。
+
+7. 验证集成质量
+   - 检查 loading、empty、error、unauthorized、offline、retrying 状态。
+   - 用浏览器网络面板确认 base URL、credentials、CORS 和状态码行为。
+   - 用 mock 或测试服务覆盖 401、403、422、500、断网和取消请求。
+   - 确认客户端 bundle 不包含私密环境变量、服务端密钥或内部地址。
+   - 对关键 API client 行为补最小测试，证明超时、取消、错误映射和刷新队列可预期。
+   - 验证错误边界与请求层协作：渲染异常进 Error Boundary，请求失败进可恢复 UI，不互相吞掉。
+
+## 约束
+
+- 不在页面组件中直接管理 token refresh、错误格式解析或重试策略。
+- 不对 4xx 业务错误做盲目自动重试。
+- 不把后端异常栈、内部错误码或原始 SQL/服务名暴露给用户。
+- 不用 localStorage 存储高价值 token；若遗留系统无法避免，必须联动安全审查。
+- 不用 WebSocket 替代简单轮询，也不用轮询实现高频双向协作。
+- 不让上传经过 API 服务器转发大文件，除非有明确合规或扫描需求。
+- 不在公共接口里直接暴露临时字段、数据库字段名或后端内部错误结构。
+
+## 预期输出
+
+输出应包含 API client 边界、接口类型来源、错误映射、鉴权刷新策略、上传/实时方案和验证结果。完成后组件不散落请求细节，用户状态完整，失败场景可恢复，客户端不会泄露服务端密钥。

package/localized/zh-CN/skills/fec-api-integration/references/integration-patterns.md

@@ -0,0 +1,80 @@
+# API 集成实现模式
+
+## 类型化 Fetch 客户端
+
+```ts
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown,
+  ) {
+    super(`API 请求失败，状态码 ${status}`);
+  }
+}
+
+export async function requestJson<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const response = await fetch(`${import.meta.env.VITE_API_URL}${path}`, {
+    ...init,
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      ...init.headers,
+    },
+    credentials: "include",
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => null);
+    throw new ApiError(response.status, body);
+  }
+
+  if (response.status === 204) return undefined as T;
+  return response.json() as Promise<T>;
+}
+```
+
+## 用户端错误映射
+
+```ts
+export function getApiMessage(error: unknown): string {
+  if (!(error instanceof ApiError)) return "操作失败，请稍后重试。";
+
+  if (error.status === 401) return "请重新登录。";
+  if (error.status === 403) return "您没有权限执行此操作。";
+  if (error.status === 404) return "请求的资源已不存在。";
+  if (error.status === 409) return "此变更与最新数据冲突。";
+  if (error.status === 422) return "请检查标红字段。";
+  if (error.status === 429) return "请求过于频繁，请稍后再试。";
+
+  return "服务暂不可用，请稍后重试。";
+}
+```
+
+## 上传选型
+
+| 需求             | 推荐方案                      |
+| ---------------- | ----------------------------- |
+| 小头像或 CSV     | Multipart 请求                |
+| 大视频或归档文件 | 预签名直传                    |
+| 弱网环境大文件   | 分片断点续传                  |
+| 入库前合规扫描   | 经 API 中介上传（含大小限制） |
+
+## 实时通信选型
+
+| 需求                 | 推荐方案                  |
+| -------------------- | ------------------------- |
+| 任务进度或通知       | SSE（Server-Sent Events） |
+| 聊天、在线状态、协作 | WebSocket                 |
+| 数秒一次的状态轮询   | 定时轮询（Polling）       |
+| 服务端 AI Token 流   | SSE 或 fetch 流式响应     |
+
+## 审查清单
+
+- API 地址和凭证集中管理。
+- 客户端需处理 204、非 JSON 错误、取消和离线状态。
+- Token 刷新机制不能引发请求风暴。
+- 组件应消费 hooks/领域函数，而非直接调用原始 fetch。
+- 上传和实时流需暴露进度、取消、失败和重试状态。

package/localized/zh-CN/skills/fec-backend-requirements-handoff/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fec-backend-requirements-handoff
+description: 用于前端工作需要向后端团队说明数据、动作、状态、权限、校验或业务规则需求，但不指定端点设计、字段名、数据库形态或实现细节；中文触发词包括 前后端需求交接、后端需求、API 需求澄清、数据需求说明。
+---
+
+# 前后端需求交接
+
+## 用途
+
+把前端页面和交互所需的数据、动作、状态和疑问整理成后端可讨论的需求说明。
+
+## 流程
+
+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，不创建文件。
+
+## 约束
+
+- 不替后端规定 URL、HTTP 方法、字段名、数据库 schema、缓存实现或服务拆分。
+- 不把前端猜测写成事实；不确定的业务规则必须进入 Uncertainties 或 Questions。
+- 不忽略错误、空态、权限和部分数据；这些状态决定接口协作质量。
+- 不把内部错误栈、数据库字段或敏感实现细节要求暴露给 UI。
+- 不与 API 集成流程重复：本 skill 描述需求，客户端边界、类型来源和错误映射实现应在后续实现阶段处理。
+
+## 预期输出
+
+产出一份前端视角的后端需求交接说明，清楚描述 UI 需要什么数据和行为、哪些规则仍需确认，以及后续前后端需要共同决定的问题。