@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/localized/zh-CN/skills/fec-browser-storage/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-browser-storage
+description: 用于选择、实现或审查 localStorage、sessionStorage、IndexedDB、cookie、客户端持久化、离线数据、安全存储或清理策略等浏览器存储方案；中文触发词包括 浏览器存储、客户端持久化。
+---
+
+# 浏览器存储
+
+## 用途
+
+根据数据大小、安全要求和生命周期选择合适的客户端存储方案。
+
+## 流程
+
+1. 先判断数据敏感度、体积、生命周期、是否需要跨 Tab、是否需要随请求发送。
+2. 小量非敏感偏好用 localStorage；Tab 级临时数据用 sessionStorage；大量结构化数据或离线缓存用 IndexedDB；认证态优先 httpOnly cookie。
+3. 封装统一 key 前缀、JSON parse/stringify、异常处理、过期清理和 quota 兜底。
+4. 敏感数据按安全规则处理，不把明文 token、密码、信用卡信息放进可被 JS 读取的存储。
+5. 审查隐私模式、存储配额、清理策略和跨浏览器兼容性。
+
+## 详细参考
+
+涉及存储选型表、localStorage/sessionStorage 封装、IndexedDB 示例、Cookie 辅助方法和敏感数据规则时，加载 [references/storage-patterns.md](references/storage-patterns.md)。
+
+## 约束
+
+- localStorage/sessionStorage 是同步 API，大数据读写会阻塞主线程。
+- 除 httpOnly cookie 外，客户端存储都可被 XSS 读取。
+- Cookie 每次请求自动携带，不适合大数据。
+- IndexedDB 配额和隐私模式行为有浏览器差异。
+- URL 中不要传 token 或敏感数据。
+
+## 预期输出
+
+产出统一的 storage/cookie/db 封装，key 有命名空间，数据有过期或清理策略，敏感数据只进入合适的安全边界。

package/localized/zh-CN/skills/fec-browser-storage/references/storage-patterns.md

@@ -0,0 +1,65 @@
+# 浏览器存储模式
+
+## 选型表
+
+| 存储 | 容量 | API | 是否发送服务端 | 适用场景 | 安全性 |
+| --- | --- | --- | --- | --- | --- |
+| LocalStorage | ~5MB | 同步 | 否 | 用户偏好、非敏感持久数据 | XSS 可读取 |
+| SessionStorage | ~5MB | 同步 | 否 | Tab 级临时数据 | XSS 可读取 |
+| IndexedDB | 大 | 异步 | 否 | 大数据、文件、离线缓存 | XSS 可读取 |
+| Cookie | ~4KB | 同步 | 是 | 认证 Session/httpOnly token | httpOnly 可防 JS 读取 |
+
+## localStorage 封装
+
+```ts
+const STORAGE_PREFIX = "app:";
+
+export const storage = {
+  get<T>(key: string): T | null {
+    try {
+      const raw = localStorage.getItem(STORAGE_PREFIX + key);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  },
+  set<T>(key: string, value: T): void {
+    localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(value));
+  },
+  remove(key: string): void {
+    localStorage.removeItem(STORAGE_PREFIX + key);
+  },
+  clear(): void {
+    Object.keys(localStorage)
+      .filter((key) => key.startsWith(STORAGE_PREFIX))
+      .forEach((key) => localStorage.removeItem(key));
+  },
+};
+```
+
+## IndexedDB
+
+```ts
+import { openDB } from "idb";
+
+export const db = openDB("app-offline-db", 1, {
+  upgrade(database) {
+    if (!database.objectStoreNames.contains("requests")) {
+      database.createObjectStore("requests", { keyPath: "id" });
+    }
+  },
+});
+```
+
+## Cookie
+
+- httpOnly 只能由服务端设置。
+- 认证 Cookie 使用 `Secure`、`SameSite=Lax/Strict`。
+- 需要跨站点嵌入时才考虑 `SameSite=None; Secure`。
+
+## 敏感数据规则
+
+- 认证 token、刷新 token、Session ID：优先 httpOnly cookie。
+- 用户偏好：localStorage。
+- 表单草稿：sessionStorage 或 IndexedDB，避免敏感字段。
+- 离线数据：IndexedDB，但不要缓存隐私或高价值敏感数据。

package/localized/zh-CN/skills/fec-canvas-threejs/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fec-canvas-threejs
+description: 用于构建或审查 Canvas 2D、Three.js/WebGL、React Three Fiber、GLSL shader、ShaderToy 到 WebGL 适配、2D/3D 可视化、游戏渲染、动画循环、GPU 资源清理或渲染性能。不要用于标准 DOM UI、已有图表库覆盖的图表或非图形类性能工作；中文触发词包括 Canvas、Three.js、WebGL、GLSL、Shader、3D、数据可视化、游戏。
+---
+
+# Canvas 与 Three.js
+
+## 用途
+
+在浏览器中实现高性能 2D/3D 图形渲染。
+
+## 流程
+
+1. 先选渲染层：标准 UI 用 DOM；简单 2D 图形/签名/粒子用 Canvas 2D；3D 模型、空间交互和复杂粒子用 Three.js/WebGL；React 项目中的声明式 3D 用 React Three Fiber。
+2. 为渲染容器定义稳定尺寸、DPI 适配和 resize 行为；Canvas 不会自动随 CSS 清晰缩放。
+3. 动画循环使用 `requestAnimationFrame`，不可见或无变化时暂停，卸载时取消。
+4. Three.js 必须释放 geometry/material/texture/renderer，并移除事件监听和 observer。
+5. Shader/WebGL 任务先识别是 SDF、ray marching、noise、particle、post-processing、multipass 还是调试问题，再决定是否需要原生 WebGL2、Three.js ShaderMaterial 或 R3F。
+6. WebGL2 适配时检查 GLSL 版本、入口函数、varying/in-out、texture API、uniform 使用和函数声明顺序，避免白屏只留控制台错误。
+7. 对不可访问的图形内容提供 `aria-label`、替代文本或 DOM 版摘要；交互式图形要有键盘兜底。
+
+## 核心模式
+
+```ts
+const dpr = Math.min(window.devicePixelRatio || 1, 2);
+canvas.width = width * dpr;
+canvas.height = height * dpr;
+canvas.style.width = `${width}px`;
+canvas.style.height = `${height}px`;
+ctx.scale(dpr, dpr);
+```
+
+```ts
+let animationId = 0;
+function animate() {
+  animationId = requestAnimationFrame(animate);
+  renderer.render(scene, camera);
+}
+
+return () => {
+  cancelAnimationFrame(animationId);
+  geometry.dispose();
+  material.dispose();
+  renderer.dispose();
+};
+```
+
+## 详细参考
+
+涉及 Canvas 2D 绘图、动画循环、Three.js 场景搭建、React Three Fiber、InstancedMesh 和性能清理时，加载 [references/rendering-patterns.md](references/rendering-patterns.md)。
+
+涉及着色器路由、WebGL2 适配、GLSL 调试、多 pass 预算和视觉验证时，加载 [references/shader-webgl-patterns.md](references/shader-webgl-patterns.md)。
+
+## 约束
+
+- Canvas/WebGL 内容对屏幕阅读器不可见，必须提供替代语义。
+- WebGL 消耗 GPU，低端设备需限制像素比、面数和纹理大小。
+- Three.js 资源不会自动释放，遗漏 `dispose()` 会造成 GPU 内存泄漏。
+- Canvas 响应式必须同步 CSS 尺寸、绘图尺寸和相机/viewport。
+- 复杂布局/路径规划可联用后台线程 workflow，但渲染本身仍在主线程/渲染线程协调。
+- Shader 主循环、采样层数和多 pass 数量必须有预算；低端设备上要降低 DPR、步数、粒子数或禁用重后处理。
+- 交付前必须确认 canvas 非空、尺寸正确、resize 后不拉伸、控制台无 shader compile/link 错误。
+
+## 预期输出
+
+2D/3D 场景清晰、响应式、可清理，关键设备上接近 60fps；用户能通过替代文本或键盘路径理解/操作核心内容。

package/localized/zh-CN/skills/fec-canvas-threejs/references/rendering-patterns.md

@@ -0,0 +1,67 @@
+# Canvas、Three.js 与 R3F 模式
+
+## Canvas 2D
+
+```ts
+const canvas = document.getElementById("chart") as HTMLCanvasElement;
+const ctx = canvas.getContext("2d");
+if (!ctx) throw new Error("Canvas 2D is unavailable");
+
+ctx.fillStyle = "#3b82f6";
+ctx.fillRect(10, 10, 50, 50);
+ctx.beginPath();
+ctx.arc(100, 100, 30, 0, Math.PI * 2);
+ctx.fill();
+```
+
+## 动画循环
+
+```ts
+let animationId = 0;
+
+function animate() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  updateParticles();
+  drawParticles(ctx);
+  animationId = requestAnimationFrame(animate);
+}
+
+animate();
+return () => cancelAnimationFrame(animationId);
+```
+
+## Three.js 基础场景
+
+```ts
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+
+const geometry = new THREE.BoxGeometry(1, 1, 1);
+const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
+const cube = new THREE.Mesh(geometry, material);
+scene.add(cube);
+```
+
+## React Three Fiber
+
+```tsx
+<Canvas camera={{ position: [0, 0, 5], fov: 75 }} role="img" aria-label="3D 产品预览">
+  <ambientLight intensity={0.5} />
+  <directionalLight position={[5, 5, 5]} />
+  <mesh>
+    <boxGeometry />
+    <meshStandardMaterial color="hotpink" />
+  </mesh>
+  <OrbitControls />
+</Canvas>
+```
+
+## 性能与清理
+
+- 纹理尽量压缩并限制尺寸，常规上限先按 2048px 评估。
+- 重复几何体用 `InstancedMesh`。
+- 不需要持续重绘时暂停 animation loop。
+- 卸载时释放 geometry、material、texture、renderer、controls。
+- ResizeObserver 更新相机 aspect 和 renderer size。

package/localized/zh-CN/skills/fec-canvas-threejs/references/shader-webgl-patterns.md

@@ -0,0 +1,67 @@
+# Shader 与 WebGL 模式
+
+## 技术选型参考
+
+| 目标               | 推荐起点           | 注意事项                       |
+| ------------------ | ------------------ | ------------------------------ |
+| 数学几何 3D 形态   | SDF + 光线步进     | 步数上限、法线质量、软阴影开销 |
+| 有机运动效果       | 噪声 + 域扭曲      | 过度绘制、重复噪声调用         |
+| 粒子效果           | 实例化或着色器粒子 | 移动端粒子数量上限、混合开销   |
+| 泛光/故障/色彩调整 | 后处理通道         | 额外帧缓冲区显存               |
+| 持续模拟           | 乒乓帧缓冲区       | 纹理格式支持                   |
+| 白屏调试           | 编译/链接日志      | 函数顺序、被优化掉的 uniform   |
+
+## WebGL2 适配清单
+
+- 片元着色器以 `#version 300 es` 开头。
+- 添加 `precision highp float;` 和 `out vec4 fragColor;`。
+- 用 `in`/`out` 替代旧版 `varying`。
+- 用 `texture()` 替代 `texture2D()`。
+- 将 ShaderToy 风格的 `mainImage` 包装为标准 `main`。
+- 使用 `gl_FragCoord.xy` 获取片元坐标。
+- 辅助函数必须在被调用前声明。
+- 预计算常量，不要在宏定义中放函数调用。
+
+## 运行时骨架
+
+```ts
+const gl = canvas.getContext("webgl2");
+if (!gl) throw new Error("WebGL2 is unavailable");
+
+function compile(type: number, source: string) {
+  const shader = gl.createShader(type);
+  if (!shader) throw new Error("Cannot create shader");
+  gl.shaderSource(shader, source.trim());
+  gl.compileShader(shader);
+
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    throw new Error(gl.getShaderInfoLog(shader) ?? "Shader compile failed");
+  }
+
+  return shader;
+}
+```
+
+## 性能预算
+
+- 光线步进步数：从 64 起步，仅在出现伪影且证明必要时再提升。
+- 体积采样：桌面端每条射线 16-24 次，移动端酌情降低。
+- FBM 倍频：从 4 开始；避免在光线循环内嵌套 FBM。
+- DPR：桌面端上限 2，移动端重度场景上限 1.5。
+- 纹理尺寸：使用压缩或缩放资源；不要假设 4K 纹理是安全的。
+
+## 调试视图
+
+- 法线：输出归一化后的法线，映射到 0-1 范围。
+- 步数：输出当前步数除以最大步数。
+- 距离/深度：以灰度输出命中距离。
+- UV：映射后输出 `vec3(uv, 0.0)`。
+- 材质 ID：将 ID 映射到少量固定调色板。
+
+## 视觉验证
+
+- 桌面端和移动端尺寸下 Canvas 不为空白。
+- 缩放时更新绘制缓冲区、视口、相机纵横比和 uniform。
+- 低功耗模式下仍能响应，或有静态降级方案。
+- 控制台无着色器编译/链接错误。
+- 卸载或场景隐藏时停止动画。

package/localized/zh-CN/skills/fec-code-review/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: fec-code-review
+description: 用于用户要求通用前端代码评审、PR 评审、合并就绪评估、架构可维护性、类型安全、渲染/状态风险、样式一致性、可测性缺口或横向评审总结时。深度安全、无障碍、E2E 或性能问题应委托对应专项 skill；中文触发词包括 代码审查、代码评审、review。
+---
+
+# 前端代码评审
+
+## 评审模式与覆盖范围
+
+用户明确指定的范围优先于默认行为。采用以下三种审核模式：
+
+- **改动审核**：仅在明确要求或当前任务已明确最近改动、本次修改、暂存区、PR 或提交上下文时，审核这些改动及必要上下文。本地模式在请求范围内检查暂存、未暂存差异及相关未跟踪项目文件；仅要求暂存区时只审核暂存改动。无改动时说明没有可审核的改动，不自动切换到最近提交或扩大范围。
+- **指定范围审核**：用户指定文件或目录时，建立范围内文件清单，审核其中现有代码，包括未改动代码；不要求 Git 差异。
+- **全项目审核（默认）**：未指定范围或改动上下文，或明确要求审核整个项目时，建立项目自有前端代码、相关测试、配置和依赖声明的清单，再按模块分批审核，包括未改动代码；不要求 Git 差异。
+
+先选择范围，再收集差异。仅指定文件或目录表示全量审核该范围；路径与明确改动请求同时出现时，仅增量审核该路径的改动。未限定的调用即使存在 Git 改动也默认全项目审核。开始审核时说明选定模式和目标范围。修改后自动委托审核时，显式传入本次改动范围，避免无范围调用触发全项目审核。
+
+默认排除依赖目录、构建产物、缓存、生成文件和第三方代码，并记录排除项。保持前端职责边界，不宣称完成后端专项审核。目标不存在或范围内无相关文件时，明确说明，不替换为其他范围。
+
+跨批次合并同根因发现。报告记录**审核模式、目标范围、已审核文件或模块、排除项、未覆盖文件或模块、完成状态及验证命令和结果**。受上下文或执行预算限制时，标记部分完成并列出剩余模块，不宣称已完成全项目覆盖。为理解上下文而读取调用方或执行全项目 lint/类型检查，不计为完成这些文件的人工审核。
+
+改动审核保留合并建议；指定范围和全项目审核使用风险评估（低 / 中 / 高，并标明阻塞问题），不宣称合并就绪。保留严重程度、证据要求和报告文件命名。除非用户明确要求修复，否则仅输出报告。
+
+## 用途
+
+从架构、类型安全、可访问性、样式一致性、性能和可测试性等 8 个维度审查前端代码质量，输出分级评审报告。
+
+## 流程
+
+1. 先读项目事实：package scripts、框架、目录约定、最近 diff、现有测试和相关规则。
+2. 按风险找问题，而不是按个人偏好挑风格；每个发现都要能指向具体文件、行号和用户影响。
+3. 用五轴收敛结论：正确性、可维护性、类型/接口、用户体验、验证覆盖。
+4. 对安全、无障碍、E2E、性能等深水区只做初筛；需要专项调查时明确分流。
+5. 多维评审时先按职责拆分，再合并同类发现；同一文件同一根因只保留一条主发现，避免重复噪声。
+6. 报告先列阻塞问题，再列建议项；没有证据的问题不要写成确定结论。
+
+## 多维评审编排
+
+当改动跨越多个质量维度时，按“主评审 + 专项分流”组织，而不是让所有维度重复检查同一处代码。
+
+| 维度                | 触发条件                                             | 分流边界                             |
+| ------------------- | ---------------------------------------------------- | ------------------------------------ |
+| TypeScript 工程与类型契约 | DTO、泛型、公共类型、类型守卫、`any`、断言、tsconfig | 深入类型建模和 TS 配置交给 TypeScript 流程 |
+| 状态管理            | 状态归属、全局 store、URL 状态、派生状态、跨页面同步 | 状态选型与迁移交给状态管理专项流程   |
+| 安全                | 用户输入、HTML 渲染、token、上传、第三方脚本         | 漏洞级分析交给安全专项流程           |
+| 无障碍              | 弹窗、菜单、表单、键盘操作、焦点管理                 | WCAG 细查交给无障碍专项流程          |
+| 性能                | 大列表、重依赖、重复请求、长任务、包体积             | 性能证据与预算交给性能专项流程       |
+| E2E                 | 关键用户路径、登录态、支付、跨页面流程               | 浏览器用例与 trace 交给 E2E 专项流程 |
+
+发现合并规则：
+
+- 同一根因出现在多个维度时，只保留最高严重级别，并在 `Dimension` 中列出相关维度。
+- 同一文件多处重复模式，合并为一条模式级发现，列出代表性位置。
+- 置信度不足的问题放入 Open Questions，不升级为阻塞项。
+- 自动化可稳定捕获的格式问题交给 lint/format，不作为人工评审主发现。
+
+## 评审维度
+
+1. 架构
+
+- 组件边界是否清晰
+- 展示逻辑与业务逻辑是否分离
+- 是否有可复用抽象
+- 是否存在上帝组件
+
+2. 类型安全
+
+- 是否存在不必要的 `any`
+- props 类型是否明确
+- hooks/composables 返回值是否稳定
+- 在可行情况下 API 契约是否有类型约束
+
+3. 渲染与状态
+
+- 是否存在不必要的重复渲染
+- key 的使用是否稳定
+- 可推导状态是否被重复存储
+- 本地状态是否耦合过深
+- 全局 store 是否只保存真正跨边界共享的客户端状态
+- URL 状态、服务端状态、表单状态和浏览器持久化是否边界清晰
+
+4. 样式
+
+- 已有 Token 时是否还在使用 magic number
+- 类名是否与仓库约定一致
+- 响应式处理是否明确
+- 是否无必要地混用了多套样式体系
+
+5. 可访问性
+
+- 语义结构是否合理
+- 是否在需要时正确使用 label 和 aria
+- 是否支持键盘操作
+- 浮层和菜单的焦点管理是否正确
+
+6. 可维护性
+
+- 组件/页面文件规模是否合理（宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分，见共享 React / Vue 规则中的「组件文件规模」）
+- 命名质量是否良好
+- 是否有应该提取的重复逻辑
+- 是否存在死代码、过期注释或临时性 hack
+- 业务状态、类型、标识是否用裸数字/裸字符串（应对齐 `templates/shared/rules/fec-typescript.md`「禁止 Magic Number / Magic String」）
+
+7. 测试
+
+- 是否缺少关键测试覆盖
+- 是否存在脆弱的选择器或不稳定的测试模式
+
+8. 安全
+
+- 无明显 XSS 风险（dangerouslySetInnerHTML / v-html 必须审查）
+- 无敏感信息硬编码
+- 无未校验的用户输入直接渲染
+
+9. 性能与体验证据
+
+- 是否引入首屏重依赖、重复请求、大列表渲染或长任务
+- loading、empty、error、disabled、focus 等状态是否完整
+- 响应式布局是否有可验证断点和文本溢出保护
+
+10. 必检项（阻塞合并）
+
+- [ ] TypeScript 类型完整，无 `any`
+- [ ] 外部输入、DTO、公共类型边界无无守卫断言
+- [ ] 无 XSS 风险
+- [ ] 无敏感信息硬编码
+- [ ] 核心逻辑有单元测试
+
+11. 质量项（建议修改）
+
+- [ ] 组件文件规模符合约定（约 300 行内为佳；逾 500 行或高复杂度已拆子组件 / Hooks / Composables / utils）
+- [ ] 无重复代码（DRY 原则）
+- [ ] 无未使用的 import
+
+12. 规范项（风格建议）
+
+- [ ] 命名语义清晰
+- [ ] 注释覆盖复杂逻辑
+
+## 详细参考
+
+撰写代码评审报告时，加载 [references/report-template.md](references/report-template.md)。发现必须具体且可操作；不要写"优化性能"等空泛建议而不指出具体代码模式。
+
+## 约束
+
+- 不把个人风格偏好写成阻塞问题；阻塞项必须有明确用户影响、运行时风险、安全风险或维护成本证据。
+- 缺少文件位置和支持证据时，不要给出确定结论；仅改动审核要求差异。
+- 深度安全、无障碍、E2E 和性能问题只做初筛；需要证据链时分流到专项 skill。
+- 同一根因不要重复报多条；合并为一条代表性发现并列出影响范围。
+- 自动化工具稳定覆盖的格式问题交给 lint/format，不作为人工评审主发现。
+
+## 预期输出
+
+- 分级评审报告（CRITICAL / HIGH / MEDIUM / LOW）
+- 每个问题关联具体文件和行号，附修复建议
+- 阻塞项（CRITICAL）修复前不建议合并
+- 评审报告保存为 `reports/code-review-YYYY-MM-DD-HHmmss.md`
+- 多维评审要合并重复发现，并说明已分流到哪些专项能力
+- 对不确定项标注需要的验证命令或补充上下文，不把猜测写成事实
+## 重构边界
+
+通用 Review 可以发现可维护性证据，但需要系统判断结构问题时，应交给坏味道诊断；需要形成保持行为的有序变化方案时，应交给重构计划。Review 不应静默执行结构修改。

package/localized/zh-CN/skills/fec-code-review/references/report-template.md

@@ -0,0 +1,39 @@
+# 代码审查报告模板
+
+```markdown
+# 代码审查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+> 审核模式：改动审核 / 指定范围审核 / 全项目审核
+> 目标范围：路径或 PR/提交
+> 已审核：文件或模块清单
+> 排除项：路径及原因
+> 未覆盖：剩余文件或模块清单（无则注明）
+> 完成状态：完成 / 部分完成
+> 验证结果：命令、结果及未执行原因
+
+## CRITICAL / 必须修改 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## HIGH / 建议优化 (N项)
+- ...
+
+## MEDIUM / 可选优化项 (N项)
+- ...
+
+## LOW / 观察项 (N项)
+- ...
+
+## 做得好的地方
+- ...
+
+## 风险等级：低 / 中 / 高
+
+**总体评价**: 改动审核填写合并建议；指定范围或全项目审核填写低 / 中 / 高风险及阻塞问题
+```
+
+评审完成后，将报告保存到 `reports/code-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。
+
+改动审核保留合并建议；指定范围和全项目审核输出风险评估。部分完成时，结论仅适用于已审核范围，不构成全项目通过结论。

package/localized/zh-CN/skills/fec-code-smells/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: fec-code-smells
+description: 需要在不修改业务代码的前提下诊断既有前端代码的结构性可维护性问题，并要求提供证据、误判检查与候选重构方向时。
+---
+
+# 代码坏味道诊断
+
+## 概览
+基于具体证据诊断结构问题。坏味道是进一步调查的信号，不等于必须修改代码的结论。
+
+## 执行流程
+1. 明确分析范围和项目事实。
+2. 收集结构、依赖方向、职责和变化耦合证据。
+3. 对照[坏味道目录](references/smell-catalog.md)。
+4. 执行[误判检查](references/detection-guide.md)。
+5. 根据[坏味道到重构手法映射](references/smell-to-refactoring-map.md)报告置信度、影响和候选方案。
+6. 如果用户只要求诊断，不修改业务代码。
+
+## Finding 输出契约
+每项必须包含位置、证据、坏味道 ID/名称、影响、置信度（`HIGH`、`MEDIUM`、`LOW`）、候选重构、优先级和重要误判因素。`LOW` 置信度不能作为自动修改依据。
+
+## 快速索引
+| 需要 | 资料 |
+| --- | --- |
+| 24 种标准坏味道 | [坏味道目录](references/smell-catalog.md) |
+| 证据与误判保护 | [检测指南](references/detection-guide.md) |
+| 候选重构手法 | [映射指南](references/smell-to-refactoring-map.md) |
+
+## 常见错误
+- 把指标阈值当成坏味道证据。
+- 不指出文件/符号就下结论。
+- 把所有循环、switch、注释、包装层或管道都视为缺陷。
+- 用户要求只诊断时仍直接改代码。

package/localized/zh-CN/skills/fec-code-smells/references/detection-guide.md

@@ -0,0 +1,25 @@
+# 代码坏味道检测指南
+
+## 证据优先
+优先观察代码结构、依赖方向、数据所有权、重复变化模式和实际维护负担。指标只能帮助定位，不能单独证明坏味道。
+
+## 必须执行的误判保护
+- 不能仅凭代码行数认定“过长函数”或“过大的类”。
+- 单个 `switch` 不能证明“重复的 switch”。
+- 函数链或数组管道不自动等于“过长的消息链”。
+- 注释本身不是缺陷。
+- 不可变的传输数据可以合理地保持纯数据形态。
+- React/Vue 声明式组合不自动等于“中间人”。
+- `filter().map().reduce()` 管道不是消息链。
+
+## 前端证据检查
+- 核对 props、store、API DTO、Hook/Composable 与模块的数据所有权。
+- 判断 effect/watch 等生命周期语义后，再评价重复或链式耦合。
+- 推荐搬移前核对组件、路由、事件和包导出的公共契约。
+- 检查动态引用：懒加载、路由注册、Storybook、i18n key、运行时模板和动态 CSS class。
+- 区分真正的领域规则重复与仅仅外观相似的渲染代码。
+
+## 置信度
+- **HIGH：** 有直接、重复证据，且重要误判因素已排除。
+- **MEDIUM：** 证据成立，但历史、动态引用或所有权仍不完整。
+- **LOW：** 主要依据表面指标或存在重大不确定性；只报告，不自动修改。