@bovinphang/frontend-craft 2.5.0 → 2.6.0

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-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. 按风险找问题，而不是按个人偏好挑风格；每个发现都要能指向具体文件、行号和用户影响。
@@ -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`，并告知用户报告路径。

package/skills/fec-doc-sync/SKILL.md

@@ -1,37 +1,39 @@
 ---
 name: fec-doc-sync
-description: Use when synchronizing frontend project documentation with source-of-truth files such as package.json, runtime templates, CLI commands, public skills, agents, reports, environment examples, or repository structure. Do not use for general prose polishing only; Chinese triggers include 文档同步, 更新 README, docs sync, 命令清单, 能力表同步.
+description: Use when synchronizing frontend project documentation with source-of-truth files such as package.json, lockfiles, config, env examples, routes, API clients or server routes, schemas, components, tests, CI, build/deploy config, ADRs, changelogs, or migration notes. Do not use for general prose polishing only; Chinese triggers include 文档同步, 更新 README, docs sync, 环境变量文档, 命令清单, API 文档同步.
 ---
 
 # 文档同步
 
 ## Purpose
 
-从代码、模板和元数据同步公开文档，避免 README、runtime 文档、能力表和报告说明与实际安装内容漂移。
+从代码、配置、测试、类型、脚本和运行时模板同步前端项目文档，避免 README、docs、环境变量说明、API/路由说明、架构决策和迁移说明与实际项目行为漂移。
 
 ## Procedure
 
-1. 找到事实来源：
-   - `package.json`：版本、脚本、bin、files。
-   - `skills/metadata.json`、`skills/eval_queries.json`：公开 skill 清单。
-   - `agents/`、`commands/`、`templates/shared/rules/`：安装内容。
-   - `docs/project-structure.md` 和 runtime docs：分发说明。
-2. 比对文档中的数量、名称、命令、报告文件名和运行时支持矩阵。
-3. 更新所有受影响语言版本；若仓库有多语言 README，保持信息一致。
-4. 对生成型报告或示例，只更新稳定约定，不把临时报告内容写入公开文档。
-5. 若变更来自依赖升级、架构决策或公共能力调整，同步轻量 ADR、变更说明、示例 prompt 和迁移注意事项。
-6. 运行文档/元数据一致性测试或相关打包检查。
+1. 识别项目栈、文档入口和本次需要同步的范围；README 同步必须扫描根目录 `README*`、`docs/*/README*`、包、应用、部署或运行时相关 README，并排除 `node_modules`、构建产物和第三方依赖目录。
+2. 收集事实来源：`package.json`、lockfile、框架和构建配置、`.env.example`、路由、API clients 或 server routes、types/schemas、组件、测试、CI、build/deploy config。
+3. 比对 README、docs、ADR、changelog、example prompts、setup/deploy/env docs 中的命令、环境变量、路由、API 行为、部署步骤和支持矩阵。
+4. 只更新稳定的公共约定；不要把临时调试结论、一次性报告或未落地设计写入长期文档。
+5. 若仓库已有多语言文档或国际化 README，主 README 的公共事实更新后必须检查其它语言 README 是否需要同步；功能名称、命令名、脚本名、包名、组件/API 名称、报告文件名、路径、环境变量、路由/API 名称、版本约束和支持矩阵必须跨语言一致。
+6. 产品文案可保持本地化表达，但不得保留旧事实、旧默认推荐或过期示例；无法高质量翻译时，至少同步关键事实，并在输出中标出人工翻译风险。
+7. 当项目暴露插件、SDK、CLI、组件库、模板或集成能力时，同步对应的功能清单、集成说明、命令/脚本说明、公开 metadata、示例提示词或示例用法。
+8. 运行相关文档一致性、旧口径搜索、报告格式一致性、类型检查、测试、构建或打包检查。
 
 ## Constraints
 
 - 不把 README 变成完整实现细节；公开文档保留高信号摘要。
-- 不引入与事实来源不一致的命令、路径或能力名称。
+- 不引入与事实来源不一致的命令、路径、环境变量、API 行为或能力名称。
+- 不把未确认的 TODO、草案或实验能力写成已支持行为。
 - 不修改用户项目私有文档，除非用户明确指定。
-- 多语言文档若无法完整翻译，至少保持数量、命令名、skill id、agent id 和报告格式一致。
+- 多语言文档若无法完整翻译，至少保持命令名、环境变量、路由/API 名称、版本约束和报告格式一致。
+- 不把国际化 README 同步简化成只改主 README；公共事实、功能清单、报告清单、命令/脚本说明和示例用法必须检查所有语言入口。
 - 不把 ADR 当作长篇复盘；只记录背景、决策、取舍、影响范围、验证和回滚线索。
 
 ## Expected Output
 
-- README、runtime docs、项目结构和 changelog 中的公开能力清单与代码一致。
-- 相关 metadata、marketplace 描述和测试期望同步。
-- 总结事实来源、更新范围、验证命令和仍需人工校对的翻译风险。
+- 列出已同步的 README/docs/ADR/changelog/env/setup/deploy 文档。
+- 列出已检查的 README/docs 入口，并说明哪些语言文件已同步、哪些无需同步、哪些需要人工确认。
+- 总结使用的事实来源、更新范围、验证命令和未覆盖风险。
+- 汇总旧口径搜索、报告文件名/路径/命令一致性和多语言关键事实一致性验证结果。
+- 标出仍需人工确认的产品文案、翻译、外部服务配置或发布说明。

package/skills/fec-e2e-testing/SKILL.md

@@ -20,10 +20,10 @@ description: Use when creating, maintaining, debugging, or reviewing real-browse
 7. 对关键浏览器能力、支付、权限、上传和实时通信流程，记录测试环境、种子数据和清理策略。
 8. 测试数据必须可重复：优先使用 API seed、数据库 fixture、测试账号或 mock 服务；随机数据需带唯一前缀并在 teardown 清理。
 
-## Detailed References
+## 详细参考
 
-- Load [references/playwright-patterns.md](references/playwright-patterns.md) for directory layout, Page Object, spec structure, config, flaky debugging, and artifact examples.
-- Load [references/e2e-advanced.md](references/e2e-advanced.md) when the task needs CI examples, Markdown report templates, Web3/wallet flows, high-risk financial flows, or visual regression setup.
+- 需要目录结构、Page Object、spec 组织、配置、flaky 调试和产物示例时，加载 [references/playwright-patterns.md](references/playwright-patterns.md)。
+- 需要 CI 示例、Markdown 报告模板、Web3/钱包流程、高风险金融流程或视觉回归配置时，加载 [references/e2e-advanced.md](references/e2e-advanced.md)。
 
 ## Constraints
 

package/skills/fec-form-handling/SKILL.md

@@ -11,13 +11,13 @@ description: Use when building or reviewing substantial forms with React Hook Fo
 
 ## Procedure
 
-1. 先判断复杂度：10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时使用 React Hook Form + Zod；极简表单可用原生受控组件。
-2. 用 Zod 定义运行时 schema，并用 `z.infer` 推导 TypeScript 类型；schema 是外部输入边界，不要只写 TS 类型。
-3. `useForm` 必须提供 `defaultValues`，通过 `zodResolver` 统一校验；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
-4. 第三方受控组件用 `Controller`，原生 input 优先 `register`；不要混用两套状态源。
+1. 先识别框架、项目既有表单库、schema 校验库、组件库和复杂度；10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时再引入专门表单方案。
+2. 按项目栈选型：React 可考虑 React Hook Form + Zod；Vue 可考虑 vee-validate / FormKit + Zod、Yup 或 Valibot；简单表单可用框架原生状态和基础校验。
+3. 用运行时 schema 或明确校验函数守住外部输入边界；TypeScript 类型可从 schema 推导，但不要只写 TS 类型。
+4. 明确默认值、字段注册、受控/非受控边界和组件库适配；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
 5. 提交时处理 loading、服务端错误、重复提交和 reset；大型表单用局部订阅和子组件隔离控制重渲染。
 
-## Quick Start
+## React Quick Start
 
 ```tsx
 import { zodResolver } from "@hookform/resolvers/zod";
@@ -59,17 +59,17 @@ export function LoginFormView() {
 }
 ```
 
-## Detailed References
+## 详细参考
 
-涉及 `Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
+涉及是否需要表单库、框架选型、`Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
 
 ## Constraints
 
-- React Hook Form 默认非受控；只有第三方受控组件才用 `Controller`。
-- `defaultValues` 必须完整，避免 undefined 触发受控/非受控警告。
-- `reset()` 应传服务器返回或明确的完整默认对象。
+- 沿用仓库既有表单库、schema 库和组件库适配方式，不为单个表单引入第二套体系。
+- 默认值必须完整，避免 undefined 触发受控/非受控警告或初始化抖动。
+- reset 应传服务器返回或明确的完整默认对象。
 - 异步校验必须 debounce 或放到提交边界，避免每次键入请求。
-- Zod `refine` / `superRefine` 的 `path` 必须指向实际字段。
+- schema 级联动校验的错误 path 必须指向实际字段。
 
 ## Expected Output