@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/localized/zh-CN/skills/fec-react-project-standard/references/common/engineering-practices.sources.json

@@ -0,0 +1,377 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "google-review",
+      "publisher": "Google",
+      "title": "Code review standard",
+      "url": "https://google.github.io/eng-practices/review/reviewer/standard.html",
+      "section": "Engineering principles and code health",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guidance; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Use evidence and project standards; personal preference alone is not a blocker."
+    },
+    {
+      "id": "ms-playbook",
+      "publisher": "Microsoft ISE",
+      "title": "Test planning",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/",
+      "section": "Risk, test scope and responsibilities",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Team practice, not a company-wide mandate; retain existing tools."
+    },
+    {
+      "id": "ms-faults",
+      "publisher": "Microsoft ISE",
+      "title": "Fault injection testing",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/",
+      "section": "Controlled failure and observations",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Run scoped, controlled failures; do not infer production reliability from a small example."
+    },
+    {
+      "id": "google-ts",
+      "publisher": "Google",
+      "title": "TS/JS style guide",
+      "url": "https://google.github.io/styleguide/tsguide.html",
+      "section": "Environment caveat; types and exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Google explicitly notes internal constraints differ; no blanket ban overriding a justified project convention."
+    },
+    {
+      "id": "typescript-publishing",
+      "publisher": "TypeScript",
+      "title": "Publishing declaration files",
+      "url": "https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html",
+      "section": "Types and declaration dependencies",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living handbook; check installed compiler/module resolution",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Validate the actual packed consumer; do not upgrade compiler or module mode on this basis."
+    },
+    {
+      "id": "rust-api",
+      "publisher": "Rust library team",
+      "title": "Rust API Guidelines",
+      "url": "https://rust-lang.github.io/api-guidelines/",
+      "section": "Type safety, dependability and future proofing",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living recommendations; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Guidance rather than language law; preserve edition and MSRV."
+    },
+    {
+      "id": "tokio-join",
+      "publisher": "Tokio project",
+      "title": "JoinHandle",
+      "url": "https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html",
+      "section": "Drop, abort and completion",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 1.54.1; project runtime/version determines applicability",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Tokio-specific mechanics only when Tokio is already used; no new runtime dependency."
+    },
+    {
+      "id": "uber-go",
+      "publisher": "Uber",
+      "title": "Go Style Guide",
+      "url": "https://github.com/uber-go/guide/blob/master/style.md",
+      "section": "Errors, interfaces and goroutine lifetime",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living master; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not import Uber dependencies or turn buffer-size style into a correctness theorem."
+    },
+    {
+      "id": "go-context",
+      "publisher": "Go project",
+      "title": "context package",
+      "url": "https://pkg.go.dev/context",
+      "section": "Cancellation propagation and ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Standard library; check owning go.mod/toolchain",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A cancellation signal alone does not confirm worker exit."
+    },
+    {
+      "id": "google-java",
+      "publisher": "Google",
+      "title": "Java Style Guide",
+      "url": "https://google.github.io/styleguide/javaguide.html",
+      "section": "Source structure and exception handling",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public style; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Naming/layout follows local standard; style is distinct from runtime correctness."
+    },
+    {
+      "id": "oracle-resources",
+      "publisher": "Oracle",
+      "title": "Try-with-resources",
+      "url": "https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html",
+      "section": "Closing resources and suppressed exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "JDK8 tutorial; not a source for newer runtime features",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Preserve primary cause and borrowed-resource ownership; check actual API contract."
+    },
+    {
+      "id": "java-executor",
+      "publisher": "Oracle",
+      "title": "ExecutorService",
+      "url": "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ExecutorService.html",
+      "section": "Shutdown, termination and awaitTermination",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Java SE17 documentation",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Check target JDK; no automatic virtual-thread or JDK migration."
+    },
+    {
+      "id": "google-python",
+      "publisher": "Google",
+      "title": "Python Style Guide",
+      "url": "https://google.github.io/styleguide/pyguide.html",
+      "section": "Imports, exceptions and mutable state",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Keep current formatter/type checker and library responsibilities."
+    },
+    {
+      "id": "python-asyncio",
+      "publisher": "Python project",
+      "title": "Coroutines and tasks",
+      "url": "https://docs.python.org/3/library/asyncio-task.html",
+      "section": "Cancellation and task ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 3.15.2; feature availability follows project Python",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Newer TaskGroup/timeout features require a supported project version; no upgrade implied."
+    },
+    {
+      "id": "cert-c",
+      "publisher": "CMU SEI",
+      "title": "MEM00-C allocation and release",
+      "url": "https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/",
+      "section": "MEM00-C memory responsibility",
+      "checkedAt": "2026-11-08",
+      "versionScope": "2016-edition standard family; MEM00-C is a recommendation",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not label recommendations as mandatory CERT rules or apply C++ ownership machinery to pure C."
+    },
+    {
+      "id": "cpp-core",
+      "publisher": "C++ Core Guidelines editors",
+      "title": "C++ Core Guidelines",
+      "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines",
+      "section": "Resource and lifetime interfaces",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page dated 2026-06-14, living release0.8",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Adapt to existing exception policy and compiler; borrowing does not imply ownership."
+    },
+    {
+      "id": "google-cpp",
+      "publisher": "Google",
+      "title": "C++ Style Guide",
+      "url": "https://google.github.io/styleguide/cppguide.html",
+      "section": "Exceptions and project consistency",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Its exception/standard policy is not universal; preserve the owning project policy and C ABI."
+    },
+    {
+      "id": "ms-sal",
+      "publisher": "Microsoft",
+      "title": "Understanding SAL",
+      "url": "https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?view=msvc-170",
+      "section": "Parameter preconditions and output guarantees",
+      "checkedAt": "2026-11-08",
+      "versionScope": "MSVC170 documentation view",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "SAL is an optional toolchain-specific expression, not a portable mandatory annotation."
+    },
+    {
+      "id": "aws-retry",
+      "publisher": "AWS",
+      "title": "Timeouts, retries and backoff with jitter",
+      "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
+      "section": "Timeouts, bounded retries and retry amplification",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Article dated 2019-12-05; official Builder Center redirect",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Retry only semantically safe operations within a total budget; failure classes alone do not grant write replay."
+    },
+    {
+      "id": "aws-idempotency",
+      "publisher": "AWS",
+      "title": "Making retries safe with idempotent APIs",
+      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/",
+      "section": "Caller intent, duplicate requests and atomic recording",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Builders Library; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A process-local example does not establish database/multi-process exactly-once."
+    },
+    {
+      "id": "react-effects",
+      "publisher": "React project",
+      "title": "useEffect",
+      "url": "https://react.dev/reference/react/useEffect",
+      "section": "Cleanup and fetching race conditions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; use installed project API",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Abort and stale-result checks complement each other; no React upgrade implied."
+    },
+    {
+      "id": "react-act",
+      "publisher": "React project",
+      "title": "act",
+      "url": "https://react.dev/reference/react/act",
+      "section": "Applying updates before assertions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; verify sample versions",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "DOM simulation is not browser E2E or native desktop execution."
+    },
+    {
+      "id": "vue-watchers",
+      "publisher": "Vue project",
+      "title": "Watchers",
+      "url": "https://vuejs.org/guide/essentials/watchers.html",
+      "section": "Side-effect cleanup",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Vue3; onWatcherCleanup requires3.5+ and synchronous registration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use supported callback cleanup on older Vue3; no framework migration."
+    },
+    {
+      "id": "tauri-permissions",
+      "publisher": "Tauri project",
+      "title": "Permissions",
+      "url": "https://v2.tauri.app/security/permissions/",
+      "section": "Command allow/deny and capability scope",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Tauri2 docs; check installed version/configuration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Rust command-unit tests do not activate webview permissions or prove packaged GUI security."
+    },
+    {
+      "id": "electron-security",
+      "publisher": "Electron project",
+      "title": "Security",
+      "url": "https://www.electronjs.org/docs/latest/tutorial/security",
+      "section": "IPC sender checks and renderer trust",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living docs; match installed Electron",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Handler tests do not prove sandbox/context isolation is active in a packaged app."
+    },
+    {
+      "id": "spring-tests",
+      "publisher": "Spring project",
+      "title": "Testing Spring Boot applications",
+      "url": "https://docs.spring.io/spring-boot/3.5/reference/testing/spring-boot-applications.html",
+      "section": "Test slices and application tests",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Boot3.5 docs observed3.5.16; preserve sample/project versions",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Test scope matters; MVC tests do not establish live DB/transaction or deployment behavior."
+    },
+    {
+      "id": "fastapi-lifespan",
+      "publisher": "FastAPI project",
+      "title": "Lifespan events",
+      "url": "https://fastapi.tiangolo.com/advanced/events/",
+      "section": "Acquire and release application resources",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living FastAPI documentation; match pinned dependencies",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use actual lifespan execution in tests; import does not own a live connection."
+    },
+    {
+      "id": "gin-binding",
+      "publisher": "Gin project",
+      "title": "Binding",
+      "url": "https://gin-gonic.com/en/docs/binding/",
+      "section": "Binding errors and validation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living Gin documentation; match pinned module",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Writing/aborting a response does not replace explicit control-flow return in the current handler."
+    },
+    {
+      "id": "axum-extractors",
+      "publisher": "Axum project",
+      "title": "Extractors",
+      "url": "https://docs.rs/axum/latest/axum/extract/",
+      "section": "Extractor order and rejections",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Latest route observed0.8.9; fixed0.8.9 route unavailable via browser tool",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Pinned existing example is authoritative for compilation; do not assume source signatures across releases."
+    },
+    {
+      "id": "drogon-filters",
+      "publisher": "Drogon project",
+      "title": "Middleware and Filter",
+      "url": "https://github.com/drogonframework/drogon/wiki/ENG-05-Middleware-and-Filter",
+      "section": "Filter callbacks and continuation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living wiki; match compiled example version",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Synthetic role headers are not authentication; callback lifetime must follow actual ownership."
+    },
+    {
+      "id": "node-typescript",
+      "publisher": "Node.js project",
+      "title": "Modules: TypeScript",
+      "url": "https://nodejs.org/api/typescript.html",
+      "section": "Type-stripping history, enabling, and separate type checking",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed26.13.0; sample>=22.18, actual24.14.1 tested; product Node>=22 unchanged",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Native stripping is not type checking and ignores tsconfig. Missing sample capability is MISSING, not a product runtime upgrade."
+    }
+  ]
+}

package/localized/zh-CN/skills/fec-react-project-standard/references/engineering-practices.md

@@ -0,0 +1,73 @@
+---
+practiceCards:
+  - id: "fec-react-project-standard:effect-cleanup"
+    level: "required"
+    sourceIds: ["react-effects","react-act"]
+    caseIds: ["EP-UI-01"]
+    evidence: "case"
+  - id: "fec-react-project-standard:stale-results"
+    level: "conditional"
+    sourceIds: ["react-effects","react-act"]
+    caseIds: ["EP-UI-01"]
+    evidence: "case"
+---
+
+# 本入口工程决策
+
+先定位项目角色、工具链及已有约定，再按需读取[公共原则](common/engineering-practices.md)。下列条件仅约束当前语言/场景；结构检查不证明全部语义或实际运行。
+
+<a id="fec-react-project-standard:effect-cleanup"></a>
+## Effect清理自己真实拥有的资源
+
+级别: required
+
+### 风险
+组件移除后，请求、监听或定时器可能继续活动。
+
+### 适用
+组件自己启动effect时适用；共享缓存/客户端任务保留原拥有者，取消订阅不授权取消全部消费者。
+
+### 决策
+setup与cleanup配对，向所属任务传播取消，清理可重复；使用已安装React API及已有组件/query边界。
+
+### 例外
+开发环境setup/cleanup循环不自动等于生产缺陷；Abort表示结束关注，不能撤销已提交服务端写。
+
+### 正反示意
+正例：清理取消本组件load并移除监听。反例：卸载时清空其他组件仍使用的全局客户端。
+
+### 验证
+运行本地真实React/DOM卸载测试；变更组件实际拥有订阅/定时器或Strict Mode行为时补对应检查。
+
+### 来源
+react-effects, react-act — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-UI-01; case. [本入口可运行案例](../examples/engineering/README.md)。 执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。
+
+<a id="fec-react-project-standard:stale-results"></a>
+## 仅当前视图请求可发布结果
+
+级别: conditional
+
+### 风险
+迟到的A成功、错误或finally可能覆盖B当前状态。
+
+### 适用
+适用于只展示最新结果的视图；各有独立结果的排队命令需自己的意图契约。
+
+### 决策
+按所属视图/query key限定请求身份及寿命，成功、错误和loading等所有状态发布都检查；取消与身份校验互补。
+
+### 例外
+不使用使无关组件失效的全局计数；取消已提交mutation不证明回滚，也不授权重放。
+
+### 正反示意
+正例：A迟到仍展示B。反例：只保护成功回调，旧finally却清掉B的loading。
+
+### 验证
+本地可控A/B Promise测试实际渲染React；实际拥有者再补迟到错误/loading及共享缓存，不把DOM模拟称浏览器E2E。
+
+### 来源
+react-effects, react-act — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-UI-01; case. [本入口可运行案例](../examples/engineering/README.md)。 执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。

package/localized/zh-CN/skills/fec-react-project-standard/references/generic-component-types.md

@@ -0,0 +1,37 @@
+## 更安全的泛型组件模式
+
+```tsx
+interface Entity {
+  id: string;
+}
+
+interface EntityPickerProps<TEntity extends Entity> {
+  items: TEntity[];
+  selectedId: string | null;
+  getLabel: (item: TEntity) => string;
+  onSelect: (item: TEntity) => void;
+}
+
+export function EntityPicker<TEntity extends Entity>({
+  items,
+  selectedId,
+  getLabel,
+  onSelect,
+}: EntityPickerProps<TEntity>) {
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>
+          <button
+            aria-pressed={item.id === selectedId}
+            type="button"
+            onClick={() => onSelect(item)}
+          >
+            {getLabel(item)}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```

package/localized/zh-CN/skills/fec-react-project-standard/references/react-quality-patterns.md

@@ -27,9 +27,9 @@
 
 ## TypeScript 规范
 
-通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
+通用 TypeScript 工程规则由 `cc-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
 
-React 规范只补充组件、Props、事件和 TSX 泛型写法；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。
+React 规范只补充组件、Props、事件和 TSX 泛型写法；复杂类型建模或跨框架类型契约先分流到 `cc-typescript-project-standard`。
 
 ### React 项目补充约定
 
@@ -119,7 +119,7 @@ describe("UserForm", () => {
 - [ ] 可复用逻辑是否已提取为 hooks
 - [ ] loading / error / empty / data 状态是否齐全
 - [ ] API 层是否具备类型约束和统一错误处理
-- [ ] 复杂 DTO、外部数据收窄、公共类型或 `tsconfig` 问题是否已分流到 `fec-typescript-project-standard`
+- [ ] 复杂 DTO、外部数据收窄、公共类型或 `tsconfig` 问题是否已分流到 `cc-typescript-project-standard`
 - [ ] 状态管理是否符合就近原则
 - [ ] 路由级或重型模块是否考虑懒加载
 - [ ] 样式方案是否与仓库保持一致

package/localized/zh-CN/skills/fec-react-project-standard/references/react-runtime-patterns.md

@@ -28,7 +28,7 @@
 
 ### 表单
 
-- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**，复杂表单值、DTO 和校验类型契约分流到 `fec-typescript-project-standard`。
+- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**，复杂表单值、DTO 和校验类型契约分流到 `cc-typescript-project-standard`。
 - 避免单组件内巨型 `useState` 表单对象与重复校验逻辑，可拆字段子组件或抽 `useFormSchema`。
 
 ### Error Boundary

package/localized/zh-CN/skills/fec-refactor-clean/SKILL.md

@@ -49,3 +49,6 @@ description: 用于安全移除前端死代码、未使用导出、陈旧组件
 
 - 清理报告保存为 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`。
 - 代码清理后相关验证命令通过，或明确说明阻塞原因。
+## 结构重构边界
+
+本工作流只负责已经证明无用/未使用的内容。如果代码仍在运行，问题属于过长函数、职责所有权、可变/派生数据、条件逻辑、API 形态或继承设计等结构重构，应分流到保持行为的结构重构，而不是以“清理”名义删除或重写。

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

@@ -0,0 +1,25 @@
+---
+name: fec-refactoring
+description: 用于在不改变可观察行为的前提下重组既有前端代码，包括职责提炼、模块搬移、条件逻辑简化、API 整理和数据组织。不要用于新增功能、改变行为的缺陷修复、依赖或框架迁移，以及已经证实的死代码清理。
+---
+
+# 前端行为保持重构
+
+执行[公共重构方法](references/common/refactoring.md)，保持 GREEN → REFACTOR → GREEN。公共方法规定行为保持、绿色基线、单步变换、立即验证、回归时只撤回当前步骤，以及差异预算。
+
+## 前端观察边界
+
+明确 props/emits/slots、hooks/composables、DOM、loading/error/empty、焦点和键盘、路由与 URL、状态归属和对象身份、请求、缓存、生命周期、SSR/hydration、导出及动态注册。
+
+## 前端风险与范围
+
+认证、权限、路由、存储、SSR/hydration、网络协议和全局状态搬移按实际影响评估。不要把重构手法名称当作 SAFE 的证明。
+
+## 专业参考
+
+- [领域证据和观察契约](references/principles.md)
+- [前端验证阶梯](references/workflow.md)
+- [何时重构](references/when-to-refactor.md)
+- [与行为变更的边界](references/refactoring-vs-feature-change.md)
+
+交付公共方法定义的 PASS、PARTIAL 或 NOT PROVEN、每步差异预算、实际校验和剩余风险。

package/localized/zh-CN/skills/fec-refactoring/references/common/refactoring.md

@@ -0,0 +1,16 @@
+# 保持行为的重构
+
+重构改变内部组织并保持可观察契约，使用 GREEN → REFACTOR → GREEN，不为结构变换制造失败的行为需求。
+
+1. 区分结构调整、新行为、缺陷修复和依赖迁移；行为变化进入独立流程。
+2. 阅读实现、调用方、导出、注册、持久化与测试；改动前定义结果、错误、副作用及顺序、状态变换、公共名称和协议。
+3. 建立绿色基线，或记录已有失败。关键行为缺少覆盖时补充描述当前行为的特征测试，可以从绿色开始。
+4. 诊断结构证据并排除误判。行数或复杂度指标本身不足以证明应当重写；优先选择最小安全、可回退的变换。
+5. 规划前置步骤；每步记录目标、结构意图、手法、风险、预计文件/函数、公共 API/行为变化（纯重构为零）、验证和回退边界。
+6. 一次只改一个主要结构问题，立即运行最近的有效校验并检查差异；实际范围超出预算时停止并重新评估。
+7. 新回归使当前步骤失效：只撤回当前结构步骤，验证前一基线，再缩小或调整顺序；不撤销无关用户改动，不跨无关模块扩散修复。
+8. 按受影响契约扩展验证：本地/静态、单元/集成、完整 lint/类型/测试、构建和相关专项。使用现有工具，不强制引入框架。
+
+风险依上下文判断：SAFE 为证据充分的局部私有变换，CAUTION 为跨模块/共享状态/生命周期变换，DANGER 为公共 API、schema、持久化、鉴权、权限、协议或架构级变化。手法名称不自动决定安全等级。
+
+给出证明结论：PASS 表示相关行为充分覆盖且校验通过；PARTIAL 表示已执行检查通过但仍有重要覆盖缺口；NOT PROVEN 表示证据或环境不足以证明行为保持。附实际命令、回退决定和剩余风险。

package/localized/zh-CN/skills/fec-refactoring/references/principles.md

@@ -0,0 +1,13 @@
+# 前端重构观察契约
+
+通用行为保持原则、基线、风险和差异预算遵循[公共方法](common/refactoring.md)。
+
+前端需要额外确认：
+
+- props、emits、slots、hooks/composables 的返回值、身份及生命周期。
+- DOM、loading/error/empty 状态、焦点、键盘与可访问性。
+- 路由、URL、懒加载、SSR/hydration、动态注册。
+- 请求、认证、取消、重试、缓存标识、乐观更新和状态归属。
+- 导出、i18n 键、Storybook、生成模板及 Tailwind 动态 class。
+
+从调用点、依赖方向、数据所有权和实际验证取得证据，不用代码行数独自证明结构问题。

package/localized/zh-CN/skills/fec-refactoring/references/refactoring-vs-feature-change.md

@@ -0,0 +1,25 @@
+# 重构与相邻工作的边界
+
+## 纯重构
+
+目标是改善职责、命名、封装、位置、条件逻辑、API 形状或数据组织，并明确要求不改变调用方/用户可观察行为时，属于纯重构。验证模型是 **GREEN → REFACTOR → GREEN**。
+
+## 功能或改变行为的缺陷修复
+
+新增能力、改变业务规则、改变接受输入、改变可见输出、改变错误结果或主动改变副作用，都不是纯重构。应先用失败行为测试表达新期望，再实现。
+
+## 调试
+
+故障原因未知时，应先找到根因。后续修复可能包含重构，但不能用“重构一下”代替故障证据。
+
+## 死代码清理
+
+已证实未使用的代码、导出、依赖、路由等需要专门检查动态 import、配置、模板、Storybook、CSS、i18n 和生成内容，不能与活代码的大范围结构改写混做。
+
+## 迁移
+
+框架、依赖、路由、构建系统、状态库或整体架构迁移会主动跨越兼容边界，即使设计因此更好，也应按迁移规划处理。
+
+## 普通评审
+
+合并前评审可以指出结构问题，但默认先输出报告；若要诊断或执行重构，应作为明确的后续动作，而不是评审过程中静默改写源码。

package/localized/zh-CN/skills/fec-refactoring/references/when-to-refactor.md

@@ -0,0 +1,17 @@
+# 何时进行重构
+
+## 现在就重构
+
+当结构问题直接增加当前工作的修改成本或风险，并且能够保持行为稳定时值得立即处理，例如职责纠缠让一个小改动波及多处、同一概念重复编辑且已开始漂移、状态/数据所有权混乱、测试难以隔离目标行为等。
+
+## 记录后延后
+
+坏味道真实存在但与当前目标无关、安全网不足以支撑高风险变换、兼容工作量明显超过即时收益时，记录证据和候选顺序，不进行顺手的大范围重新设计。
+
+## 停止重构
+
+出现以下情况应停止：结构目标已经达成；下一步会改变可观察行为；下一步跨越公开契约但没有兼容方案；差异预算持续扩大；验证无法区分基线与新回归；剩余动机只来自个人审美而非修改成本或正确性风险。
+
+## 实用判断
+
+好的重构应让下一个真实需求更容易理解、局部化、验证或回滚。如果没有改善这些属性，应要求更强证据再继续。

package/localized/zh-CN/skills/fec-refactoring/references/workflow.md

@@ -0,0 +1,7 @@
+# 前端重构验证
+
+执行顺序、失败回退和证明等级见[公共方法](common/refactoring.md)。
+
+按风险逐步选择：局部类型/静态检查 → utils/hooks/组件测试 → Router/Provider/Store 轻量集成 → 全量 lint、类型和测试 → 构建与受影响的 SSR、E2E、无障碍、视觉或性能验证。
+
+记录实际项目命令、UI/状态/网络观察、基线失败、每步变更和回退边界。不为纯结构重构制造新行为红灯，不撤销无关用户改动。