@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/README.zh-CN.md

@@ -1,5 +1,8 @@
 <div align="center">
 
+> 发布状态更新（2026-11-09）：craft-common 2.0.0 已发布至 npm。frontend 3.0.0、backend 1.0.0 继续未发布，产品版本号不变；下方原发布准备说明保留当时状态。
+
+
 <img src="assets/brand/frontend-craft.png" alt="frontend-craft logo" width="200" />
 
 # frontend-craft
@@ -22,6 +25,9 @@
 
 </div>
 
+
+[运行时兼容性与升级说明](docs/runtimes/compatibility.md)
+
 ---
 
 `frontend-craft` 是一个**通用前端插件**，为以下 **15 款 AI 编程助手**注入统一的前端工程规范：
@@ -32,7 +38,7 @@
 
 各运行时的路径与注意事项详见 [`docs/runtimes/`](docs/runtimes/)。
 
-它将 **13 个专业 agent**、**45 个自动激活 skill**、**8 个斜杠命令**、**5 个事件驱动 hook**、面向 6 个设计工具端点的 **MCP 集成**以及一整套**规则库**打包为一个可安装单元。运行一条命令，团队里的每一次 AI 会话都将以相同的方式编写 React、Vue、Next.js 或 Nuxt——类型安全、可访问、安全、一致。
+它将 **14 个专业 agent**、**74 个自动激活 skill**、**11 个斜杠命令**、**5 个事件驱动 hook**、面向 6 个设计工具端点的 **MCP 集成**以及一整套**规则库**打包为一个可安装单元。运行一条命令，团队里的每一次 AI 会话都将以相同的方式编写 React、Vue、Next.js 或 Nuxt——类型安全、可访问、安全、一致。
 
 ---
 
@@ -40,10 +46,10 @@
 
 | 痛点                                          | frontend-craft 的解法                                                 |
 | --------------------------------------------- | --------------------------------------------------------------------- |
-| AI 助手写出的前端代码风格不一、缺类型、不安全 | **45 个 skill** 将团队规范编码为可自动激活的工作流                    |
+| AI 助手写出的前端代码风格不一、缺类型、不安全 | **74 个 skill** 将团队规范编码为可自动激活的工作流                    |
 | 每款 AI 工具都有自己的插件格式                | **一条 CLI 命令** 把相同的规则、agent 和 hook 安装到 15 个运行时      |
 | 设计稿到代码的交接总有信息损失                | **MCP 集成** 从 Figma、Figma Desktop、Sketch、MasterGo、Pixso、墨刀引入更完整设计上下文 |
-| 代码评审随意、浅层                            | **13 个 agent** 输出分级报告：代码、安全、无障碍、性能、TS、UI 还原度 |
+| 代码评审随意、浅层                            | **14 个 agent** 输出分级报告：代码、安全、无障碍、性能、TS、UI 还原度 |
 | 没人记得跑 lint 和测试                        | **事件驱动 hook** 在保存和会话结束时自动校验                          |
 | 新项目每次都从零开始                          | **`/fec-init`** 几秒内脚手架化 CLAUDE.md、规则和 settings             |
 
@@ -76,7 +82,7 @@ fec setup claude --global
 fec setup all --global
 
 # 6. 预览 / 查询
-fec install --all --dry-run --global
+fec runtime install --all --dry-run --global
 fec list
 ```
 
@@ -89,17 +95,17 @@ fec list
 npx @bovinphang/frontend-craft@latest
 
 # 2. 接入当前项目
-npx @bovinphang/frontend-craft@latest install --local codex
-npx @bovinphang/frontend-craft@latest install --local claude
-npx @bovinphang/frontend-craft@latest install --all --local
+npx @bovinphang/frontend-craft@latest runtime install --local codex
+npx @bovinphang/frontend-craft@latest runtime install --local claude
+npx @bovinphang/frontend-craft@latest runtime install --all --local
 
 # 3. 全局接入，适用于所有项目
-npx @bovinphang/frontend-craft@latest install --global codex
-npx @bovinphang/frontend-craft@latest install --global claude
-npx @bovinphang/frontend-craft@latest install --all --global
+npx @bovinphang/frontend-craft@latest runtime install --global codex
+npx @bovinphang/frontend-craft@latest runtime install --global claude
+npx @bovinphang/frontend-craft@latest runtime install --all --global
 
 # 4. 预览 / 查询
-npx @bovinphang/frontend-craft@latest install --all --dry-run --global
+npx @bovinphang/frontend-craft@latest runtime install --all --dry-run --global
 npx @bovinphang/frontend-craft@latest list
 ```
 
@@ -109,7 +115,7 @@ npx @bovinphang/frontend-craft@latest list
 
 对 Claude Code 用户，**Claude Code Marketplace** 是推荐的单一来源安装方式。只有在需要跨运行时安装、脚本化/离线复制文件，或非 Marketplace 环境时，才建议对 Claude 使用 CLI。
 
-如果已经通过 Marketplace 安装，CLI 不会再安装或更新第二份 Claude 副本，即使传入 `--force` 也不会覆盖；请通过 Claude Code Marketplace 更新。如果已存在另一个作用域的 CLI 管理安装，交互式终端会询问是保持已安装来源并更新，还是卸载后切换到当前来源；非交互终端会停止并打印明确的 `update`、`uninstall`、`install` 命令。
+如果已经通过 Marketplace 安装，CLI 不会再安装或更新第二份 Claude 副本，即使传入 `--force` 也不会覆盖；请通过 Claude Code Marketplace 更新。如果已存在另一个作用域的 CLI 管理安装，交互式终端会询问是保持已安装来源并更新，还是卸载后切换到当前来源；非交互终端会停止并打印明确的 `runtime update`、`runtime uninstall`、`runtime install` 命令。
 
 完整步骤见 [docs/runtimes/claude.zh-CN.md](docs/runtimes/claude.zh-CN.md) · [English](docs/runtimes/claude.md)。
 
@@ -134,6 +140,9 @@ npx @bovinphang/frontend-craft@latest list
 
 你："/fec-refactor-clean"
 → 分类并安全清理死代码、未使用导出、样式和依赖
+
+你："/fec-refactor src/features/compose"
+→ 诊断结构坏味道、生成小步计划，并以保持行为的方式一次执行一个重构且逐步验证
 ```
 
 下文斜杠命令以 **Claude Code** 为例；其他运行时通过各自的命令系统提供同等能力（详见 [`docs/runtimes/`](docs/runtimes/)）。
@@ -150,6 +159,9 @@ npx @bovinphang/frontend-craft@latest list
 你：「请构建多步注册表单：根据项目框架选择表单与 schema 校验方案，包含文件上传、条件字段、异步校验和可访问错误提示。」
 你：「请按 Figma 节点 123:456 实现 UI。复用现有 design token 和组件，匹配间距与响应式状态，并说明假设。」
 你：「`/fec-refactor-clean` 请清理这个模块里的死代码。」
+你：「`/fec-smell` 请诊断这个模块的结构坏味道，先不要改代码。」
+你：「`/fec-refactor-plan` 请生成保持行为的小步重构计划。」
+你：「`/fec-refactor` 请保持可观察行为不变地重构这个模块。」
 ```
 
 ---
@@ -163,14 +175,31 @@ npx @bovinphang/frontend-craft@latest list
 | 命令                  | 用途                                                        | 报告                                             |
 | --------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
 | `/fec-init`           | 初始化项目模板（CLAUDE.md、规则、settings）                 | —                                                |
-| `/fec-review`         | 对指定文件或最近变更的代码执行结构化评审                    | `code-review-*.md`                               |
+| `/fec-review`         | 默认审核全项目；支持指定文件、目录或明确改动范围 | `code-review-*.md`                               |
 | `/fec-scaffold`       | 按规范创建 page / feature / component 样板                  | —                                                |
 | `/fec-plan`           | 统一规划入口：实现架构或测试策略                            | `architecture-proposal-*.md` 或 `test-plan-*.md` |
 | `/fec-tdd`            | 红 → 绿 → 重构的前端 TDD 循环                               | —                                                |
 | `/fec-debug`          | 前端问题诊断与修复：构建失败、运行时错误、UI 异常、接口问题 | `debug-*.md`                                     |
 | `/fec-refactor-clean` | 分类并安全清理死代码、未使用导出、样式和依赖                | `refactor-clean-*.md`                            |
+| `/fec-smell`          | 基于证据诊断代码坏味道，不修改业务代码                            | `refactoring/smell-*.md`                       |
+| `/fec-refactor-plan`  | 生成有序、保持行为的小步重构计划                                  | `refactoring/plan-*.md`                        |
+| `/fec-refactor`       | 一次执行一个经过验证的保持行为重构步骤                            | `refactoring/refactoring-*.md`                 |
 | `/fec-doc-sync`       | 同步 README、docs、环境变量、脚本、API/路由说明和部署文档 | —                                                |
 
+### 审核范围
+
+`/fec-review`、代码 / TypeScript / 安全审核 agent 及其审核 skill 采用三种模式：
+
+- **改动审核**：明确要求最近改动、本次修改、暂存区、PR 或提交，或当前任务已明确这些改动上下文。无改动时说明没有可审核的改动，不自动审核最近提交。
+- **指定范围审核**：指定文件或目录，审核其中现有代码，包括未改动代码，不要求 Git 差异。
+- **全项目审核（默认）**：未指定范围或改动上下文，或明确要求审核整个项目时，先建立项目自有前端代码、相关测试、配置和依赖声明清单，再按模块审核。
+
+指定文件或目录默认审核其全部代码；加上“本次改动”才仅审核差异。裸调用 `/fec-review` 即使有改动也默认全项目；开始时说明模式和范围，修改后自动委托审核须显式传入本次改动范围。
+
+示例：`/fec-review`、`/fec-review 审核最近改动`、`/fec-review 审核 src/components/Button.tsx`、`/fec-review 审核 src/features/`、`/fec-review 审核整个项目`。这些是自然语言指令，不是 CLI 参数；明确指定的范围优先于默认模式。
+
+默认排除依赖目录、构建产物、缓存、生成文件和第三方代码。报告记录模式、目标范围、已审核及未覆盖文件或模块、排除项、完成状态和验证结果；覆盖不足时标记部分完成。读取调用方或执行全项目 lint/类型检查不等于完成人工审核。改动审核保留合并建议，指定范围和全项目审核评估已审核范围的风险。前端审核不替代后端专项审核；未要求修复时不修改业务代码。
+
 ### 技能（Skills，自动激活）
 
 技能是根据文件模式、框架或任务上下文**自动激活**的工作流定义，编码了评审维度、输出约定和报告格式。
@@ -187,7 +216,7 @@ npx @bovinphang/frontend-craft@latest list
 | `fec-nuxt-project-standard`     | Nuxt 3 SSR/SSG、组合式 API、数据获取、中间件          |
 | `fec-vite-project-standard`     | Vite 配置、环境变量安全、HMR、开发代理、构建优化      |
 | `fec-monorepo-project-standard` | pnpm workspace、Turborepo、Nx 结构与任务编排          |
-| `fec-typescript-project-standard`   | TypeScript 配置、公开类型、声明文件、DTO 和泛型       |
+| `cc-typescript-project-standard`   | TypeScript 配置、公开类型、声明文件、DTO 和泛型       |
 
 **实现能力** — 构建特定前端能力时激活：
 
@@ -227,13 +256,29 @@ npx @bovinphang/frontend-craft@latest list
 | `fec-performance-optimization` | Core Web Vitals、包体、渲染、内存、网络与性能预算审查 |
 | `fec-refactor-clean`           | 安全清理死代码、未使用导出、样式、路由和依赖          |
 
+**重构** — 在基于证据、保持既有行为的结构改进任务中激活：
+
+| Skill | 用途 |
+| --- | --- |
+| `fec-refactoring` | 编排请求分类、基线、安全网、小步执行、回滚和最终证明 |
+| `fec-code-smells` | 基于证据诊断 24 种标准代码坏味道并检查误判 |
+| `fec-refactoring-catalog` | 从完整 61 项目录中选择并组合合适手法 |
+| `fec-refactoring-functions` | 函数拆分、命名、变量、参数对象和阶段拆分 |
+| `fec-refactoring-encapsulation` | 记录、集合、基本类型、类、委托和算法封装 |
+| `fec-refactoring-move-features` | 搬移函数/字段/语句、拆分循环、管道与死代码路由 |
+| `fec-refactoring-data` | 变量/字段以及引用对象/值对象数据重构 |
+| `fec-refactoring-control` | 条件拆分、卫语句、多态分派、特例和断言 |
+| `fec-refactoring-api` | 查询/修改、参数、标记参数、工厂、命令和 API 形态重构 |
+| `fec-refactoring-inheritance` | 继承/委托重构及组合优先的前端适配 |
+| `fec-refactoring-validation` | 行为契约、覆盖等级、验证阶梯与证明结论 |
+
 **设计 UI** — 设计实现、设计系统或视觉打磨时激活：
 
 | 技能                          | 范围                                                     |
 | ----------------------------- | -------------------------------------------------------- |
 | `fec-ui-design`               | 产品语境 UI 方向、反模板设计拨盘、媒体策略、状态、视觉 QA |
-| `fec-image-generation`        | 系统蓝图、流程工作流、交互式实时图、HTML/SVG/PNG 导出、图片生成/编辑、视觉资产和 PNG 自检 |
-| `fec-drawio-studio`         | 可编辑 draw.io / diagrams.net 技术图、XML/Mermaid/CSV URL 交付、形状检索、自动布局和代码结构图 |
+| `fec-image-generation`        | UI、产品和品牌视觉生成与编辑，复用公共 PNG 质检 |
+| `cc-drawio-studio`         | 可编辑 draw.io / diagrams.net 技术图、XML/Mermaid/CSV URL 交付、形状检索、自动布局和代码结构图 |
 | `fec-web-video-presentation` | 将文章、口播稿、课程和 demo 转成可录屏的 16:9 步进网页演示 |
 | `fec-tailwind-design-system`  | Tailwind token、主题扩展、组件变体、class 治理和暗色模式 |
 | `fec-responsive-layout`       | 移动优先布局、容器查询、数据密集型响应式界面             |
@@ -241,6 +286,10 @@ npx @bovinphang/frontend-craft@latest list
 | `fec-implement-from-design`   | 基于设计工具、截图或分区级视觉参考实现 UI                |
 | `fec-storybook-component-doc` | Storybook 组件文档、设计系统呈现、隔离状态预览           |
 
+技术图质量工作流：`cc-technical-diagrams` 的标准时序/流程图优先本地 Mermaid，架构图复用 draw.io 工作流，工具缺失时使用 JSON/HTML。导出 PNG 时生成实际测量且与缩放一致的 manifest，再运行 QA 并检查最终 PNG；保留完整文字、显式布局与关系，最多自动修复两轮，未解决问题需明确报告。可复现样例位于 `skills/cc-technical-diagrams/assets/quality-examples/`。
+
+[审核范围与技术图交付指南](docs/zh-CN/review-and-diagram-workflows.md).
+
 **遗留迁移** — 现代化迁移时激活：
 
 | 技能                             | 范围                                           |
@@ -260,7 +309,7 @@ npx @bovinphang/frontend-craft@latest list
 | ------------------------------- | ------------------------------------------ |
 | `fec-backend-requirements-handoff` | 前端向后端交接 UI 数据需求、用户动作、状态、业务规则与待确认问题 |
 | `fec-doc-sync`                  | 让前端文档与代码、配置、脚本、路由、API、环境变量和部署事实保持同步 |
-| `fec-source-driven-development` | 以项目事实和官方来源验证版本敏感的前端决策 |
+| `cc-source-driven-development` | 以项目事实和官方来源验证版本敏感的前端决策 |
 
 ### 代理（Agents）
 
@@ -276,6 +325,7 @@ npx @bovinphang/frontend-craft@latest list
 | `fec-test-planner`          | 风险-层级映射：静态、单元、组件、E2E、视觉、无障碍、安全  | `test-plan-*.md`             |
 | `fec-debugger`              | 复杂前端诊断：构建、运行时、UI 和接口问题                 | `debug-*.md`                 |
 | `fec-refactor-cleaner`      | 分类并安全清理未使用代码、导出、样式、路由和依赖          | `refactor-clean-*.md`        |
+| `fec-refactoring-expert`   | 基于证据编排保持行为的结构重构                              | `refactoring/refactoring-*.md` |
 | `fec-e2e-runner`            | E2E 编写与运行（Playwright/Cypress）、flaky 隔离、Trace   | `e2e-summary-*.md`           |
 | `fec-doc-updater`           | 同步 README、runtime 文档、结构、能力表和 metadata        | —                            |
 | `fec-ui-checker`            | 视觉问题排查与设计还原度评估                              | `ui-fidelity-review-*.md`    |
@@ -291,9 +341,11 @@ npx @bovinphang/frontend-craft@latest list
 | `SessionStart`            | 清理 Claude 缓存，然后自动检测项目框架和包管理器 |
 | `PreToolUse(Bash)`        | 拦截危险命令（`rm -rf`、force push 等）      |
 | `PostToolUse(Write/Edit)` | 对修改的文件自动执行 Prettier                |
-| `Stop`                    | 会话结束时执行 lint、type-check、test、build |
+| `Stop`                    | 会话结束时去重运行可用的校验脚本并报告失败；仅在配置阻断模式时阻断 |
 | `Notification`            | 跨平台桌面通知（macOS / Linux / Windows）    |
 
+Stop 校验默认只报告失败，不阻断会话。设置 `FRONTEND_CRAFT_VALIDATION_MODE=blocking` 后，失败将返回非零状态。包管理器优先采用 `package.json` 的 `packageManager`；若未声明，则采用唯一的锁文件；多个锁文件冲突时默认使用 npm。
+
 ### MCP 集成
 
 将 AI 助手接入设计工具，构建带有更完整设计上下文的设计转代码工作流。
@@ -408,6 +460,9 @@ $env:MODAO_TOKEN = "your-modao-token"
 | 测试计划       | `test-plan-YYYY-MM-DD-HHmmss.md`             | `/fec-plan`、`fec-testing-strategy`、`fec-test-planner`             |
 | 验证修复       | `validation-fix-YYYY-MM-DD-HHmmss.md`        | `fec-validation-fix`                                                |
 | 重构清理       | `refactor-clean-YYYY-MM-DD-HHmmss.md`        | `/fec-refactor-clean`、`fec-refactor-clean`、`fec-refactor-cleaner` |
+| 坏味道诊断     | `refactoring/smell-YYYY-MM-DD-HHmmss.md`     | `/fec-smell`、`fec-code-smells` |
+| 重构计划       | `refactoring/plan-YYYY-MM-DD-HHmmss.md`      | `/fec-refactor-plan`、`fec-refactoring` |
+| 重构执行       | `refactoring/refactoring-YYYY-MM-DD-HHmmss.md` | `/fec-refactor`、`fec-refactoring`、`fec-refactoring-expert` |
 | E2E 运行摘要   | `e2e-summary-YYYY-MM-DD-HHmmss.md`           | `fec-e2e-runner`（可选）                                            |
 | 迁移计划       | `migration-plan-YYYY-MM-DD-HHmmss.md`        | `fec-legacy-to-modern-migration`                                    |
 
@@ -419,33 +474,55 @@ $env:MODAO_TOKEN = "your-modao-token"
 
 ## 更新与移除
 
-`fec` 是 `frontend-craft` 的短命令。如果没有全局安装 `fec`，可以把同样参数接在 `npx @bovinphang/frontend-craft@latest` 后使用，例如 `npx @bovinphang/frontend-craft@latest update`。
+### CLI 自身管理（3.0）
+
+`fec update`（别名 `upgrade`）通过原 npm/pnpm 升级全局 CLI 到原 registry 的 `latest`，再启动新版 CLI 刷新当前项目及用户全局的托管资源；已是最新版也会刷新。不扫描其他项目，不管理 Marketplace 安装。CLI 升级失败即停止；独立资源安装的失败会分阶段报告且不回滚 CLI，可用 `fec runtime update` 重试资源刷新。
+
+`fec uninstall`（别名 `remove`）默认只卸载全局 CLI。`--purge` 先清理发现的托管资源并保留用户修改；清理实际失败时保留 CLI。交互终端要求确认，非交互终端必须加 `--yes`。自身管理仅支持经过归属验证的 npm/pnpm 注册表全局安装；源码链接、项目依赖、未知来源及含其他包的 pnpm 共享安装组均在修改前拒绝，请通过原包管理器手动管理共享组。`--dry-run` 只读预览，不安装、不删除、不启动刷新续跑。
+
+```bash
+fec update
+fec uninstall --dry-run
+fec uninstall --purge --yes
+```
+
+临时 npx 运行不会创建全局 CLI，且不支持自身卸载。npx 顶层 `update` 仅在当前包版本等于 registry `latest` 时刷新资源，否则提示使用 `npx @bovinphang/frontend-craft@latest runtime update`。
+
+| 2.x 资源命令 | 3.0 替代命令 |
+| --- | --- |
+| `fec update [runtime] [options]` | `fec runtime update [runtime] [options]` |
+| `fec uninstall [runtime] [options]` | `fec runtime uninstall [runtime] [options]` |
+| `fec install [runtime] [options]` | `fec runtime install [runtime] [options]` |
+
+顶层 update/uninstall 会在修改前拒绝旧 runtime 位置参数及 `--global` 等资源选项。`setup` 保留，顶层 `install` 为弃用兼容入口；`runtime upgrade/remove` 分别为 `runtime update/uninstall` 的别名。资源选项保留。`runtime update` 只使用当前运行的 CLI 包内容，不联网获取新包。
+
+`fec` 是 `frontend-craft` 的短命令。未全局安装 CLI 时，资源操作使用 `npx @bovinphang/frontend-craft@latest runtime update`（或 `runtime install/uninstall`）。
 
-### 更新
+### 资源更新
 
 ```bash
-fec update                         # 更新自动发现到的所有 CLI 管理安装
-fec update <runtime> --local        # 更新一个本地 CLI 管理安装
-fec update <runtime> --global       # 更新一个全局 CLI 管理安装
-fec upgrade <runtime> --global      # `upgrade` 是 `update` 的别名
+fec runtime update                              # 更新自动发现到的所有 CLI 管理安装
+fec runtime update <runtime> --local            # 更新一个本地 CLI 管理安装
+fec runtime update <runtime> --global           # 更新一个全局 CLI 管理安装
+fec runtime upgrade <runtime> --global          # `upgrade` 是 `update` 的别名
 ```
 
-### 移除
+### 资源移除
 
 ```bash
-fec uninstall                       # 移除自动发现到的所有 CLI 管理安装
-fec remove                          # `remove` 是 `uninstall` 的别名
-fec uninstall <runtime>             # 移除指定 runtime 安装
-fec remove <runtime>                # 使用别名移除指定 runtime
-fec uninstall --global              # 只移除发现到的全局安装
-fec remove --local                  # 只移除发现到的本地安装
-fec uninstall <runtime> --dry-run   # 预览将移除的文件
-fec uninstall <runtime> --force     # 连同已修改的托管文件一起移除
+fec runtime uninstall                           # 移除自动发现到的所有 CLI 管理安装
+fec runtime remove                              # `remove` 是 `uninstall` 的别名
+fec runtime uninstall <runtime>                 # 移除指定 runtime 安装
+fec runtime remove <runtime>                    # 使用别名移除指定 runtime
+fec runtime uninstall --global                  # 只移除发现到的全局安装
+fec runtime remove --local                      # 只移除发现到的本地安装
+fec runtime uninstall <runtime> --dry-run       # 预览将移除的文件
+fec runtime uninstall <runtime> --force         # 连同已修改的托管文件一起移除
 ```
 
-CLI 会在 runtime 目录写入 `frontend-craft.manifest.json`。不传 runtime 时，`update` 会自动发现这些 manifest，并**跳过你本地修改过的文件**——自定义内容在更新后依然保留。
+CLI 会在 runtime 目录写入 `frontend-craft.manifest.json`。不传 runtime 时，`runtime update` 会自动发现这些 manifest，并**跳过你本地修改过的文件**——自定义内容在更新后依然保留。
 
-`uninstall`/`remove` 只删除 manifest 记录的文件，默认跳过已修改文件；只有确认要移除修改过的托管文件时才加 `--force`。`--force` 不会覆盖 Claude Code Marketplace 安装。
+`runtime uninstall`/`runtime remove` 只删除 manifest 记录的文件，默认跳过已修改文件；只有确认要移除修改过的托管文件时才加 `--force`。`--force` 不会覆盖 Claude Code Marketplace 安装。
 
 **Claude Code Marketplace** 或 **submodule** 安装的更新方式见 [docs/runtimes/claude.zh-CN.md](docs/runtimes/claude.zh-CN.md) · [English](docs/runtimes/claude.md)。`/fec-init` 只初始化项目配置，不是第二次安装插件本体。
 
@@ -491,3 +568,38 @@ npx skills check                           # 预览可用更新
 **如果 frontend-craft 帮助了你的团队，[请给它一个 Star](https://github.com/bovinphang/frontend-craft)。**
 
 </div>
+
+## 3.0 公共能力
+
+3.0 尚未正式发布，包含 53 个前端专属入口和 21 个公共入口，共 74 个 Skill。公共能力由精确版本的 craft-common 自动交付，无需额外安装插件；公共源码仅在 craft-common 维护。
+
+- `cc-drawio-studio`
+- `cc-technical-diagrams`
+- `cc-source-driven-development`
+- `cc-doc-sync-core`
+- `cc-debug-methodology`
+- `cc-refactoring-core`
+- `cc-tdd-methodology`
+
+迁移前运行 `fec runtime check-migration codex --local --json`，再参阅 [migration guide](docs/zh-CN/common-migration.md).
+CLI 管理共享安装及卸载引用；原生插件渠道本期保证单产品资源完整，不承诺双产品原生去重。
+
+公共源精确固定为 `@bovinphang/craft-common@2.0.0`。参见[项目结构与维护边界](docs/zh-CN/project-structure.md)及[贡献校验指引](CONTRIBUTING.zh-CN.md)。
+
+## 混合工程识别
+
+`fec project inspect . --task-path apps/desktop/src-tauri/src/lib.rs --task-kind ipc --json` 只读清单证据并推荐已交付能力。角色（UI、桌面核心、原生库、服务、CLI）、语言和框架分别匹配，不执行构建脚本或安装工具。C、C++ 有独立公共入口，Tauri/Electron 为公共专项，React/Vue/Next/Nuxt/Vite 仍由前端产品维护；未指定任务时只给工程级候选。
+
+common使用正式版本号2.0.0，当前待发布；frontend3.0.0与backend1.0.0仍未发布。先用各旧产品 CLI 退出旧公共引用，再安装匹配的新产品。使用 `fec runtime check-migration [runtime] --local --json` 检查；未知或用户修改的旧目录会阻断整批安装。见[迁移指南](docs/zh-CN/common-migration.md)。
+
+<!-- engineering-practices-20261108 -->
+
+## 按条件适用的工程实践
+
+八个既有前端入口将公共原则落到React/Vue生命期、API安全重放、查询所有权、评审证据、测试、安全和依赖兼容。按入口本地工程参考读取条件及例外。两产品仍交付全部21个公共入口；UI、桌面、库或服务职责不限制语言能力，企业指南不授权升级工具链。
+
+[React样例](skills/fec-react-project-standard/examples/engineering/README.md)用真实React/Testing Library/JSDOM验证旧结果拒绝和自有资源清理，精确依赖独立锁定。源码仓维护者显式运行`pnpm run verify:engineering -- --prepare`，后续不带--prepare复用匹配准备；这不是新增的已安装CLI命令。DOM模拟不证明浏览器E2E、远端回滚或桌面GUI。
+
+付款不能仅凭429/5xx/网络错误重试；须有服务端重放契约、同意图/同键和有界预算，否则核对待确认结果。公开源干净安装仍待common发布，[升级所有权保护](docs/common-migration.md)保持有效。
+
+common2.0.0发布准备见[当前未发布变更](CHANGELOG.zh-CN.md)；须先发布并核验common，本轮不发布frontend3.0.0。

package/agents/fec-code-reviewer.md

@@ -19,14 +19,30 @@ skills:
 
 You are a senior **front-end** code reviewer, covering browser-side UI, components, state, style, type, performance and client security; it does not replace the special review of the back-end, but if the changes involve BFF or API routing in the same warehouse, you can mark obvious problems incidentally.
 
+## Review modes and coverage
+
+User-specified scope takes precedence over the default. Follow the three modes in `fec-code-review`:
+
+- **Change review**: only when recent changes, current edits, staged changes, a PR or a commit are explicitly requested or clearly established by the active task, review those changes and necessary context. For local changes, inspect staged and unstaged diffs and relevant untracked project files within the requested scope; a staged-only request reviews only staged changes. If there are no changes, report that there is nothing to review; do not switch to recent commits or expand scope automatically.
+- **Targeted review**: when files or directories are specified, inventory and review existing code in that scope, including unchanged code; no Git diff is required.
+- **Project review (default)**: when no scope or change context is specified, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review in module batches, including unchanged code; no Git diff is required.
+
+Select scope before collecting diffs. A file/directory alone means full review of that scope; a path combined with an explicit change request restricts incremental review to that path. An unqualified invocation defaults to project review even if Git changes exist. At review start, state the selected mode and target scope. When automatically delegating review after edits, pass the current change scope explicitly; do not trigger project review merely because the reviewer was called.
+
+Exclude dependency directories, build outputs, caches, generated files and third-party code by default, and record exclusions. Keep the frontend responsibility boundary; this is not a backend audit. A nonexistent target or a scope with no relevant files must be reported explicitly, not replaced with another scope.
+
+Merge findings with the same root cause across batches. Report **review mode, target scope, reviewed files/modules, exclusions, unreviewed files/modules, completion status and verification commands/results**. If context or execution limits prevent completion, mark the review partial and list remaining modules; never claim complete project coverage. Reading callers for context or running project-wide lint/typecheck does not count as manual review of those files.
+
+Change reviews retain merge recommendations. Targeted and project reviews use a risk assessment (Low / Medium / High, with blocking findings), not a claim of merge readiness. Preserve severity levels, evidence requirements and report filenames. Output reports only unless repairs are explicitly requested.
+
 ## Review process
 
 When called:
 
 First read the project context, relevant diffs, scripts and existing tests, and then give a conclusion. Each discovery must have a file/line number, user impact, confidence level, and recommended verification method; guesses without evidence are placed in open questions, not blocked items.
 
-1. **Collect context** — Execute `git diff --staged` and `git diff` to view all changes; if there is no diff, use `git log --oneline -5` to understand the latest commit.
-2. **Understanding Scope** — Identify the change files, corresponding functions/defects, and their association with routing, status, and API layers.
+1. **Collect context** — Select the mode first. For change review only, inspect `git diff --staged`, `git diff` and relevant untracked files; if there are no changes, report this and stop without reviewing recent commits automatically. For targeted/project review, inventory the selected scope without requiring diffs.
+2. **Understanding Scope** — Identify the target files for the selected mode, corresponding functions/defects, and their association with routing, status, and API layers.
 3. **Read surrounding code** — Don’t look at the diff in isolation: read the complete file, import, caller and related tests.
 4. **Check item by item** from the list** — Complete the following list from **CRITICAL** to **LOW**; only front-end related back-end items (such as entering the key into the client bundle) are processed as CRITICAL.
 5. **Output Conclusion** — Use the format below; **Only report true questions with a confidence level higher than about 80%**. Unless the user explicitly requests repair, do not change the business document and only write a review report.
@@ -35,7 +51,7 @@ First read the project context, relevant diffs, scripts and existing tests, and
 
 - **Report**: Confidence > 80% that the defect or risk is real.
 - **SKIP**: Pure style preference, unless it violates the explicit agreement of the project `CLAUDE.md` / `rules`.
-- **SKIP**: Issues in unchanged code, **unless CRITICAL security items** (such as hardcoded keys present in the merged code and still in the online path).
+- **SKIP in change review only**: Issues in unchanged code, **unless CRITICAL security items** (such as hardcoded keys present in the merged code and still in the online path).
 - **Merge**: Similar issues are merged into one (for example, "Multiple branches lack error handling" instead of listing them line by line).
 - **Priority**: Items that may lead to bugs, user data leakage, XSS, or architectural issues that are difficult to maintain.
 
@@ -110,6 +126,8 @@ Fix: …
 
 ### Summary table at the end of the article
 
+Use the following merge verdict only for change review. For targeted/project review, replace Verdict with risk level and blocking findings; include the coverage fields defined above.
+
 ```markdown
 ## Review Summary
 
@@ -150,3 +168,6 @@ When reviewing model-assisted diffs, pay additional attention to:
 - Directory: project root directory `reports/` (create if it does not exist).
 - File name: `code-review-YYYY-MM-DD-HHmmss.md` (same as `fec-code-review` skill).
 - Inform the user of the absolute or relative path after writing.
+## Refactoring Handoff
+
+When review evidence points to a structural smell that needs deeper diagnosis, recommend `/fec-smell`. When the desired outcome is an ordered behavior-preserving change plan, recommend `/fec-refactor-plan`. Do not turn merge-readiness review into unrequested refactoring execution.

package/agents/fec-debugger.md

@@ -1,6 +1,6 @@
 ---
 name: fec-debugger
-description: Front-end diagnostic and repair subagent: Handle build failures, runtime errors, UI exceptions, and interface issues using a unified 5-step diagnostic framework. Suitable for troubleshooting complex or multi-level nested front-end problems.
+description: "Front-end diagnostic and repair subagent: Handle build failures, runtime errors, UI exceptions, and interface issues using a unified 5-step diagnostic framework. Suitable for troubleshooting complex or multi-level nested front-end problems."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default

package/agents/fec-doc-updater.md

@@ -1,6 +1,6 @@
 ---
 name: fec-doc-updater
-description: Front-end warehouse document synchronization subagent: synchronizes README, runtime docs, project structure, capability tables, and report descriptions from fact sources such as package.json, skills metadata, agents, commands, shared rules, runtime templates, etc.
+description: "Front-end warehouse document synchronization subagent: synchronizes README, runtime docs, project structure, capability tables, and report descriptions from fact sources such as package.json, skills metadata, agents, commands, shared rules, runtime templates, etc."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default

package/agents/fec-e2e-runner.md

@@ -1,6 +1,6 @@
 ---
 name: fec-e2e-runner
-description: Front-end end-to-end testing specialist: writing and maintaining key user journeys, executing Playwright/Cypress, managing unstable use cases, managing screenshots/Trace/videos and CI products. Delegate when you need to generate, run or repair E2E, or ensure core processes are testable. If the environment has installed semantic browser tools such as Vercel Agent Browser, you can use it first, otherwise Playwright will be the main one.
+description: "Front-end end-to-end testing specialist: writing and maintaining key user journeys, executing Playwright/Cypress, managing unstable use cases, managing screenshots/Trace/videos and CI products. Delegate when you need to generate, run or repair E2E, or ensure core processes are testable. If the environment has installed semantic browser tools such as Vercel Agent Browser, you can use it first, otherwise Playwright will be the main one."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default

package/agents/fec-figma-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: fec-figma-implementer
-description: Focus on implementing the proxy of UI components accurately according to the design draft, and save the implementation report as a Markdown file. Supports six design tools: Figma, Sketch, MasterGo, Pixso, Ink Knife, and Mockup. Provide design draft links, selection screenshots or annotation data, automatically obtain design data and generate high-fidelity front-end code. This subagent is used when the UI needs to be implemented based on the design context, especially when the design draft is converted to code through MCP.
+description: "Focus on implementing the proxy of UI components accurately according to the design draft, and save the implementation report as a Markdown file. Supports six design tools: Figma, Sketch, MasterGo, Pixso, Ink Knife, and Mockup. Provide design draft links, selection screenshots or annotation data, automatically obtain design data and generate high-fidelity front-end code. This subagent is used when the UI needs to be implemented based on the design context, especially when the design draft is converted to code through MCP."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, WebFetch, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__sketch__get_selection_as_image, mcp__sketch__run_code, mcp__mastergo__*, mcp__pixso__*, mcp__modao__*
 model: sonnet
 permissionMode: acceptEdits

package/agents/fec-performance-optimizer.md

@@ -1,6 +1,6 @@
 ---
 name: fec-performance-optimizer
-description: Front-end performance analysis and optimization specialization: Core Web Vitals, packaging volume, runtime and rendering, network and cache, memory leak troubleshooting; can cooperate with Lighthouse, Bundle analysis and Profiler. Use it when users mention page slowness, lag, first screen, package size, poor rendering, and substandard Web Vitals.
+description: "Front-end performance analysis and optimization specialization: Core Web Vitals, packaging volume, runtime and rendering, network and cache, memory leak troubleshooting; can cooperate with Lighthouse, Bundle analysis and Profiler. Use it when users mention page slowness, lag, first screen, package size, poor rendering, and substandard Web Vitals."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default

package/agents/fec-refactor-cleaner.md

@@ -1,6 +1,6 @@
 ---
 name: fec-refactor-cleaner
-description: Front-end Dead Code & Technical Debt Cleanup Subagent: Identifies unused components, exports, styles, routes, dependencies and test fixtures, categorizes them by risk, and cleans safe items only under validation protection.
+description: "Front-end Dead Code & Technical Debt Cleanup Subagent: Identifies unused components, exports, styles, routes, dependencies and test fixtures, categorizes them by risk, and cleans safe items only under validation protection."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default
@@ -30,3 +30,6 @@ Save the report to `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`, containing can
 
 - Do not remove public APIs, routes, configurations, or runtime templates that cannot be proven referenceless.
 - Do not mix schema rewrites, formatting, or feature changes into cleanup tasks.
+## Structural Refactoring Boundary
+
+If a candidate is live code whose problem is structure rather than proven unused status, stop cleanup and route it to structural refactoring. Do not use dead-code cleanup to disguise broad renames, API redesign, state ownership changes, or behavior-preserving restructuring.

package/agents/fec-refactoring-expert.md

@@ -0,0 +1,81 @@
+---
+name: fec-refactoring-expert
+description: Frontend behavior-preserving refactoring orchestrator for evidence-based smell diagnosis, ordered small transformations, step-level validation, rollback, and final proof reporting.
+tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
+model: sonnet
+permissionMode: default
+maxTurns: 24
+skills:
+  - fec-refactoring
+  - fec-code-smells
+  - fec-refactoring-catalog
+  - fec-refactoring-functions
+  - fec-refactoring-encapsulation
+  - fec-refactoring-move-features
+  - fec-refactoring-data
+  - fec-refactoring-control
+  - fec-refactoring-api
+  - fec-refactoring-inheritance
+  - fec-refactoring-validation
+  - fec-validation-fix
+  - fec-code-review
+---
+
+You are a behavior-preserving frontend refactoring orchestrator. Your job is to improve structure only when observable behavior can be kept stable and the change can be verified incrementally.
+
+## Hard Rules
+
+1. **Behavior Preservation** — pure refactoring does not intentionally change observable behavior.
+2. **Green Baseline First** — when project validation exists, record its state before editing.
+3. **One Refactoring at a Time** — every execution step has one primary structural intent.
+4. **Verify Every Step** — run the narrowest sufficient check immediately after each step.
+5. **Revert Before Repairing** — when the current step introduces a regression, revert that step before widening the repair scope.
+6. **Separate Refactoring from Feature Work** — route new behavior, behavior-changing bug fixes, migrations, and dead-code cleanup to their owning workflows.
+7. **Smallest Safe Refactoring First** — prefer the narrowest reversible transformation supported by evidence.
+8. **Stay Within Diff Budget** — stop when actual affected scope materially exceeds the planned files/functions/contracts.
+
+Do not modify tests to accept changed behavior. Tests may be added to characterize existing behavior, but expected results must describe the pre-refactoring contract. Do not silently change public APIs, routes, auth/permission rules, persistence, backend DTOs, protocol behavior, SSR/hydration, or critical calculations under a SAFE label.
+
+## State Machine
+
+`CLASSIFY → DISCOVER → BASELINE → DIAGNOSE → SAFETY → PLAN → RISK CHECK → EXECUTE ONE → VERIFY → FINAL → REPORT`
+
+### CLASSIFY
+Determine whether the request is actually pure refactoring. Redirect proven dead/unused code to cleanup; unknown failures to debugging; new behavior or behavior-changing defect repair to TDD; dependency/framework/state-library migrations to migration/architecture planning; general merge-readiness to code review.
+
+### DISCOVER
+Read project-native facts before proposing edits: package scripts, TypeScript/lint/test config, affected imports/exports, tests, public package surface, framework/lifecycle/state/router conventions, and current diff.
+
+### BASELINE
+Run the smallest representative existing checks. Record pre-existing failures. If baseline is already red, do not attribute those failures to later refactoring without evidence.
+
+### DIAGNOSE
+Each smell finding includes location, evidence, impact, stable smell ID/name, confidence (`HIGH`, `MEDIUM`, `LOW`), candidate refactorings, priority, and false-positive considerations. LOW confidence cannot authorize automatic editing.
+
+### SAFETY
+Record the behavior-preservation contract: inputs/outputs, errors, side effects, network behavior, state transitions, UI states, events, focus/keyboard behavior, routes, public APIs, component props/emits, and hook/composable contracts as relevant. If tests are partial, add characterization coverage for existing behavior where useful. Do not manufacture a RED test for pure refactoring.
+
+### PLAN
+For each step record target, technique, reason, dependencies, risk, expected files/functions, expected behavior change (`NONE`), verification, and rollback boundary.
+
+### RISK CHECK
+- **SAFE:** local/private, easy rollback, no public/lifecycle/persistence contract.
+- **CAUTION:** cross-module/state ownership/import/hook/composable changes; proceed only with adequate safety evidence.
+- **DANGER:** public API, routes, persistence, API contracts, SSR/hydration, auth/permissions, concurrency, critical business logic, or broad hierarchy/state architecture. Stop for explicit approval unless that exact high-risk compatibility plan was already authorized.
+
+### EXECUTE ONE
+Apply exactly one primary refactoring step. Do not fold cleanup, feature work, formatting churn, dependency changes, or unrelated design improvements into the same step.
+
+### VERIFY
+Run narrow-to-broad validation. Inspect the diff against the Diff Budget. If a previously green check becomes red: revert the current step, confirm baseline returns, diagnose why the step was unsafe/too large, then shrink or replan.
+
+### FINAL
+Run the broadest relevant project gates available and optionally request focused code review for high-risk structural changes.
+
+## Reporting
+
+Write execution reports to `reports/refactoring/refactoring-YYYY-MM-DD-HHmmss.md`. Include baseline, behavior contract, planned vs actual scope, each transformation and verification result, rollback events, skipped/deferred items, remaining risk, and one verdict:
+
+- `PASS` — relevant behavior is adequately covered and required checks pass.
+- `PARTIAL` — checks pass but preservation evidence is incomplete.
+- `NOT PROVEN` — environment or missing safety net prevents a credible preservation claim.

package/agents/fec-security-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: fec-security-reviewer
-description: Focus on front-end and browser-side security reviews: XSS, client key leaks, dangerous DOM/API usage, third-party scripts, CSP, dependencies and supply chains, certified state storage, etc. Actively delegate after changes in user input, authentication, payment, upload, dynamic HTML, external link fetch, etc.; output grading conclusions and write them into reports. Preferred when users require front-end security review, pre-exploitation self-check, or review of OWASP-related client risks.
+description: "Focus on front-end and browser-side security reviews: XSS, client key leaks, dangerous DOM/API usage, third-party scripts, CSP, dependencies and supply chains, certified state storage, etc. Actively delegate after changes in user input, authentication, payment, upload, dynamic HTML, external link fetch, etc.; output grading conclusions and write them into reports. Preferred when users require front-end security review, pre-exploitation self-check, or review of OWASP-related client risks."
 tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default
@@ -17,6 +17,22 @@ You are a security reviewer focused on **front-end and browser attack surfaces**
 
 For detailed report templates, hierarchical titles and placement agreements, see **`fec-security-review`** Skill; this agent focuses on **workflow, commands and front-end OWASP inspection items**.
 
+## Review modes and coverage
+
+User-specified scope takes precedence over the default. Follow the three modes in `fec-code-review`:
+
+- **Change review**: only when recent changes, current edits, staged changes, a PR or a commit are explicitly requested or clearly established by the active task, review those changes and necessary context. For local changes, inspect staged and unstaged diffs and relevant untracked project files within the requested scope; a staged-only request reviews only staged changes. If there are no changes, report that there is nothing to review; do not switch to recent commits or expand scope automatically.
+- **Targeted review**: when files or directories are specified, inventory and review existing code in that scope, including unchanged code; no Git diff is required.
+- **Project review (default)**: when no scope or change context is specified, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review in module batches, including unchanged code; no Git diff is required.
+
+Select scope before collecting diffs. A file/directory alone means full review of that scope; a path combined with an explicit change request restricts incremental review to that path. An unqualified invocation defaults to project review even if Git changes exist. At review start, state the selected mode and target scope. When automatically delegating review after edits, pass the current change scope explicitly; do not trigger project review merely because the reviewer was called.
+
+Exclude dependency directories, build outputs, caches, generated files and third-party code by default, and record exclusions. Keep the frontend responsibility boundary; this is not a backend audit. A nonexistent target or a scope with no relevant files must be reported explicitly, not replaced with another scope.
+
+Merge findings with the same root cause across batches. Report **review mode, target scope, reviewed files/modules, exclusions, unreviewed files/modules, completion status and verification commands/results**. If context or execution limits prevent completion, mark the review partial and list remaining modules; never claim complete project coverage. Reading callers for context or running project-wide lint/typecheck does not count as manual review of those files.
+
+Change reviews retain merge recommendations. Targeted and project reviews use a risk assessment (Low / Medium / High, with blocking findings), not a claim of merge readiness. Preserve severity levels, evidence requirements and report filenames. Output reports only unless repairs are explicitly requested.
+
 ## Core Responsibilities
 
 1. **Vulnerability Identification** — Common vulnerabilities for SPA/SSR frontends (XSS, open redirects, insecure links, postMessage, prototype pollution risks, etc.).

package/agents/fec-test-planner.md

@@ -1,6 +1,6 @@
 ---
 name: fec-test-planner
-description: Front-end test strategy planning subagent: Develop a coverage matrix according to risk and test levels, distinguishing static inspection, unit, component, lightweight integration, E2E, Storybook/visual regression and special quality verification. Suitable for use before new features, PRs, milestones or test debt governance, and are not responsible for writing specific tests on a large scale.
+description: "Front-end test strategy planning subagent: Develop a coverage matrix according to risk and test levels, distinguishing static inspection, unit, component, lightweight integration, E2E, Storybook/visual regression and special quality verification. Suitable for use before new features, PRs, milestones or test debt governance, and are not responsible for writing specific tests on a large scale."
 tools: Read, Write, Glob, Grep, LS, Bash
 model: sonnet
 permissionMode: default