@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/docs/zh-TW/README.md

@@ -1,534 +1,588 @@
-<div align="center">
-
-<img src="../../assets/brand/frontend-craft.png" alt="frontend-craft logo" width="200" />
-
-# frontend-craft
-
-### 一套工具，適配所有 AI 程式設計助手，落地生產級前端規範。
-
-[![Stars](https://img.shields.io/github/stars/bovinphang/frontend-craft?style=flat)](https://github.com/bovinphang/frontend-craft/stargazers)
-[![CI](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml/badge.svg)](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@bovinphang/frontend-craft)](https://www.npmjs.com/package/@bovinphang/frontend-craft)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
-![Node](https://img.shields.io/badge/Node.js-22+-5FA04E?logo=node.js&logoColor=white)
-![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
-![React](https://img.shields.io/badge/-React-61DAFB?logo=react&logoColor=black)
-![Vue](https://img.shields.io/badge/-Vue-4FC08D?logo=vue.js&logoColor=white)
-![Figma](https://img.shields.io/badge/-Figma-F24E1E?logo=figma&logoColor=white)
-
-**🌐 Language / 语言 / 語言 / 言語 / 언어**
-
-[English](../../README.md) · [简体中文](../../README.zh-CN.md) · [**繁體中文**](README.md) · [日本語](../ja-JP/README.md) · [한국어](../ko-KR/README.md)
-
-</div>
-
-
-[執行環境相容性與升級說明](../runtimes/compatibility.md)
-
----
-
-`frontend-craft` 是一個**通用前端插件**，為以下 **15 款 AI 程式設計助手**注入統一的前端工程規範：
-
-`claude` `codex` `cursor` `windsurf` `opencode`
-`kilo` `gemini` `copilot` `antigravity` `augment`
-`trae` `codebuddy` `cline` `openclaw` `qoder`
-
-各執行時的路徑與注意事項詳見 [`docs/runtimes/`](../runtimes/)。
-
-它將 **14 個專業 agent**、**56 個自動啟用 skill**、**11 個斜線指令**、**5 個事件驅動 hook**、面向 6 個設計工具端點的 **MCP 整合**以及一整套**規則庫**打包為一個可安裝單元。執行一條指令，團隊裡的每一次 AI 會話都將以相同的方式編寫 React、Vue、Next.js 或 Nuxt——型別安全、可存取、安全、一致。
-
----
-
-## 為什麼選擇 frontend-craft？
-
-| 痛點                                            | frontend-craft 的解法                                                                   |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
-| AI 助手寫出的前端程式碼風格不一、缺型別、不安全 | **56 個 skill** 將團隊規範編碼為可自動啟用的工作流                                      |
-| 每款 AI 工具都有自己的插件格式                  | **一條 CLI 指令** 把相同的規則、agent 和 hook 安裝到 15 個執行時                        |
-| 設計稿到程式碼的交接總有資訊損失                | **MCP 整合** 從 Figma、Figma Desktop、Sketch、MasterGo、Pixso、墨刀引入更完整設計上下文 |
-| 程式碼審查隨意、淺層                            | **14 個 agent** 輸出分級報告：程式碼、安全、無障礙、效能、TS、UI 還原度                 |
-| 沒人記得跑 lint 和測試                          | **事件驅動 hook** 在儲存和會話結束時自動校驗                                            |
-| 新專案每次都從零開始                            | **`/fec-init`** 幾秒內腳手架化 CLAUDE.md、規則和 settings                               |
-
----
-
-## 安裝
-
-需要 **Node.js 22+**。完整支援 **Windows、macOS 和 Linux**（所有鉤子和腳本均使用 Node.js 實作）。
-
-### 方式一：全域安裝 fec CLI（推薦）
-
-```bash
-# 1. 全域安裝 fec 指令
-npm install -g @bovinphang/frontend-craft@latest
-
-# 2. 進入你的前端專案
-cd your-project
-
-# 3. 互動選擇要接入的 AI 執行時
-fec setup
-
-# 4. 接入目前專案
-fec setup codex
-fec setup claude
-fec setup all
-
-# 5. 全域接入，適用於所有專案
-fec setup codex --global
-fec setup claude --global
-fec setup all --global
-
-# 6. 預覽 / 查詢
-fec install --all --dry-run --global
-fec list
-```
-
-`npm install -g` 只是安裝 `fec` 終端機指令。`fec setup` 是終端機中的 CLI 專案接入指令，不是 AI 助手內的 `/fec-init` 斜線指令。在互動式終端機中，不帶參數的 `fec setup` 會先讓你選擇 runtime；`fec setup <runtime>` 和 `fec setup all` 會預設接入目前專案。只有傳入 `--global` 時，才會接入對應 AI 工具的全域設定目錄，適用於所有專案。
-
-### 方式二：用 npx 臨時執行（免全域安裝 fec）
-
-```bash
-# 1. 互動精靈
-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
-
-# 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
-
-# 4. 預覽 / 查詢
-npx @bovinphang/frontend-craft@latest install --all --dry-run --global
-npx @bovinphang/frontend-craft@latest list
-```
-
-不想全域安裝 `fec` 指令時使用 `npx`。不帶參數會進入互動精靈：先選擇一個或多個執行時，再決定接入全域還是目前專案。腳本化安裝全部 runtime 時使用 `install --all --local` 或 `install --all --global`，不要寫成 `install all`。CI / 腳本場景請務必帶上 `--global` / `-g` 或 `--local` / `-l`；非 TTY 且未指定時，CLI 預設安裝到 `claude --global`。
-
-### 方式三：Claude Code Marketplace
-
-對 Claude Code 用戶，**Claude Code Marketplace** 是推薦的單一來源安裝方式。只有在需要跨執行時安裝、腳本化/離線複製檔案，或非 Marketplace 環境時，才建議對 Claude 使用 CLI。
-
-如果已經透過 Marketplace 安裝，CLI 不會再安裝或更新第二份 Claude 副本，即使傳入 `--force` 也不會覆蓋；請透過 Claude Code Marketplace 更新。如果已存在另一個作用域的 CLI 管理安裝，互動式終端會詢問是保持已安裝來源並更新，還是解除安裝後切換至當前來源；非互動式終端會停止並列印明確的 `update`、`uninstall`、`install` 命令。
-
-完整步驟見 [docs/runtimes/claude.zh-CN.md](../runtimes/claude.zh-CN.md) · [English](../runtimes/claude.md)。
-
----
-
-## 快速開始
-
-安裝完成後，你在每一次 AI 會話中都擁有一套完整的前端工程工具箱：
-
-```text
-你："Review my recent changes"
-→ fec-code-reviewer agent 被調度，輸出 reports/code-review-*.md
-
-你："/fec-review"
-→ 按架構、型別、渲染、樣式、可存取性等維度執行結構化審查
-
-你："根據這個 Figma 連結實現結算頁"
-→ fec-figma-implementer agent 透過 MCP 讀取設計稿，輸出元件和報告
-
-你："/fec-scaffold dashboard feature"
-→ 依專案約定建立 page / feature / component 標準目錄結構
-
-你："/fec-refactor-clean"
-→ 分類並安全清理死程式碼、未使用匯出、樣式和依賴
-```
-
-下文斜線指令以 **Claude Code** 為例；其他執行時透過各自的指令系統提供同等能力（詳見 [`docs/runtimes/`](../runtimes/)）。
-
----
-
-## 範例提示詞
-
-完整的按場景組織提示詞庫請參考 [docs/example-prompts.md](../example-prompts.md)。
-
-```text
-你：「合併前請審查我最近的改動。重點看架構、型別安全、渲染行為、樣式、可存取性和缺失測試。」
-你：「先不要寫程式碼，請規劃帳號帳單功能：路由結構、元件邊界、資料流、狀態歸屬、驗證流程和上線風險。」
-你：「請建構多步註冊表單：依專案框架選擇表單與 schema 驗證方案，包含檔案上傳、條件欄位、非同步驗證和可存取錯誤提示。」
-你：「請按 Figma 節點 123:456 實作 UI。複用現有 design token 和元件，匹配間距與響應式狀態，並說明假設。」
-你：「`/fec-refactor-clean` 請清理這個模組裡的死程式碼。」
-```
-
----
-
-## 裡面有什麼
-
-### 指令（Commands）
-
-斜線指令是結構化工作流的主入口，多數會輸出帶時間戳記的 Markdown 報告到 `reports/`。
-
-| 指令                  | 用途                                                        | 報告                                             |
-| --------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
-| `/fec-init`           | 初始化專案範本（CLAUDE.md、規則、settings）                 | —                                                |
-| `/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` | Diagnose code smells without editing | `refactoring/smell-*.md` |
-| `/fec-refactor-plan` | Plan behavior-preserving refactoring | `refactoring/plan-*.md` |
-| `/fec-refactor` | Execute validated behavior-preserving refactoring | `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，自動啟用）
-
-技能是根據檔案模式、框架或任務上下文**自動啟用**的工作流定義，編碼了審查維度、輸出約定和報告格式。
-
-下方按使用場景分組列出全部自動啟用的技能，便於快速找到專案規範、實作、測試、審查、設計、遷移、專案演進和文件維護能力。
-
-**專案規範** — 偵測到對應框架時自動生效：
-
-| 技能                              | 範圍                                                  |
-| --------------------------------- | ----------------------------------------------------- |
-| `fec-react-project-standard`      | React + TypeScript（結構、元件、路由、狀態、API 層）  |
-| `fec-vue3-project-standard`       | Vue 3 + TypeScript（結構、元件、路由、Pinia、API 層） |
-| `fec-nextjs-project-standard`     | Next.js 14+ App Router、SSR/SSG、流式渲染、元資料     |
-| `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 和泛型         |
-
-**實作能力** — 建構特定前端能力時啟用：
-
-| 技能                      | 範圍                                                       |
-| ------------------------- | ---------------------------------------------------------- |
-| `fec-data-fetching`       | 服務端狀態獲取、快取、失效、SSR、無限載入                  |
-| `fec-api-integration`     | 型別化 API client、鑑權刷新、上傳、即時整合                |
-| `fec-state-management`    | 狀態歸屬、store 選型、URL 狀態、伺服器/表單/本地狀態邊界   |
-| `fec-form-handling`       | 跨框架表單選型、schema 驗證、動態欄位、上傳                |
-| `fec-browser-storage`     | localStorage / sessionStorage / IndexedDB / Cookies 選型   |
-| `fec-route-protection`    | React Router、Next.js、Vue Router、Nuxt 的登入態與權限路由 |
-| `fec-pwa-implementation`  | manifest、Service Worker、離線快取、安裝提示               |
-| `fec-web-workers`         | Web Worker、Transferable、Comlink、Worker 池               |
-| `fec-canvas-threejs`      | Canvas 2D、Three.js、React Three Fiber、WebGL              |
-| `fec-svg-animation`       | CSS / Framer Motion / GSAP SVG 動畫與 reduced-motion       |
-| `fec-list-virtualization` | 依框架選型的大清單虛擬滾動、測量、網格和無限滾動           |
-
-**測試** — 規劃或撰寫前端測試覆蓋時啟用：
-
-| 技能                    | 範圍                                                      |
-| ----------------------- | --------------------------------------------------------- |
-| `fec-testing-strategy`  | 靜態檢查、單元、元件、整合、E2E、視覺測試分層             |
-| `fec-component-testing` | React Testing Library / Vue Test Utils 元件測試與回歸用例 |
-| `fec-e2e-testing`       | Playwright / Cypress E2E 與 Page Object 和 CI 整合        |
-| `fec-tdd-workflow`      | 測試先行的前端實作，紅綠重構循環                          |
-
-**審查與品質** — 程式碼審查、驗證或清理時啟用：
-
-| 技能                           | 範圍                                                    |
-| ------------------------------ | ------------------------------------------------------- |
-| `fec-code-review`              | 架構、型別、渲染、樣式、可存取性審查                    |
-| `fec-debug-framework`          | 系統化診斷建置、執行時、UI 和 API/資料問題              |
-| `fec-security-review`          | XSS、CSRF、敏感資料外洩、輸入驗證                       |
-| `fec-accessibility-check`      | WCAG 2.2、鍵盤、焦點、觸控和螢幕閱讀器行為              |
-| `fec-dependency-upgrade`       | 依賴升級、lockfile 審查、CVE 修復和遷移驗證             |
-| `fec-validation-fix`           | 一次性執行並修復 lint、type-check、test、build          |
-| `fec-performance-optimization` | Core Web Vitals、包體、渲染、記憶體、網路與效能預算審查 |
-| `fec-refactor-clean`           | 安全清理死程式碼、未使用匯出、樣式、路由和依賴          |
-
-**Refactoring**
-
-| Skill | Scope |
-| --- | --- |
-| `fec-refactoring` | Behavior-preserving refactoring capability |
-| `fec-code-smells` | Behavior-preserving refactoring capability |
-| `fec-refactoring-catalog` | Behavior-preserving refactoring capability |
-| `fec-refactoring-functions` | Behavior-preserving refactoring capability |
-| `fec-refactoring-encapsulation` | Behavior-preserving refactoring capability |
-| `fec-refactoring-move-features` | Behavior-preserving refactoring capability |
-| `fec-refactoring-data` | Behavior-preserving refactoring capability |
-| `fec-refactoring-control` | Behavior-preserving refactoring capability |
-| `fec-refactoring-api` | Behavior-preserving refactoring capability |
-| `fec-refactoring-inheritance` | Behavior-preserving refactoring capability |
-| `fec-refactoring-validation` | Behavior-preserving refactoring capability |
-
-**設計 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-web-video-presentation`  | 將文章、口播稿、課程和 demo 轉成可錄屏的 16:9 步進網頁演示                                       |
-| `fec-tailwind-design-system`  | Tailwind token、主題擴展、元件變體、class 治理和暗色模式                                         |
-| `fec-responsive-layout`       | 移動優先布局、容器查詢、資料密集型響應式界面                                                     |
-| `fec-motion-interaction`      | 場景化動效強度、頁面轉場、滾動動畫、reduced-motion                                               |
-| `fec-implement-from-design`   | 基於設計工具、截圖或分區級視覺參考實現 UI                                                        |
-| `fec-storybook-component-doc` | Storybook 元件文件、設計系統呈現、隔離狀態預覽                                                   |
-
-技術圖品質：標準時序圖、流程圖優先本機 Mermaid，可編輯架構圖優先 draw.io；工具缺少時使用 JSON/HTML。以符合 PNG 比例的實測 manifest 執行 QA，並檢視最終圖片。預設最多修復兩輪，未解決問題必須明確回報。
-
-[審查範圍與技術圖交付指南](../zh-CN/review-and-diagram-workflows.md).
-
-**遺留遷移** — 現代化遷移時啟用：
-
-| 技能                             | 範圍                                           |
-| -------------------------------- | ---------------------------------------------- |
-| `fec-legacy-web-standard`        | JS + jQuery + HTML 傳統專案的開發與維護規範    |
-| `fec-legacy-to-modern-migration` | 遺留前端現代化、目標技術棧識別與分階段遷移流程 |
-
-**專案演進** — 吸收參考系統並原創化落到目前專案時啟用：
-
-| 技能          | 範圍                                       |
-| ------------- | ------------------------------------------ |
-| `fec-alchemy` | 將參考系統能力原創化吸收到目前專案原生體系 |
-
-**文件維護** — 文件維護時啟用：
-
-| 技能                               | 範圍                                                                  |
-| ---------------------------------- | --------------------------------------------------------------------- |
-| `fec-backend-requirements-handoff` | 前端向後端交接 UI 資料需求、使用者動作、狀態、業務規則與待確認問題    |
-| `fec-doc-sync`                     | 讓前端文件與程式碼、設定、腳本、路由、API、環境變數和部署事實保持同步 |
-| `fec-source-driven-development`    | 以專案事實和官方來源驗證版本敏感的前端決策                            |
-
-### 代理（Agents）
-
-代理是由主助手調度的專業子代理，專注處理單一任務並返回結構化報告。
-
-| 代理                        | 聚焦領域                                                  | 報告                         |
-| --------------------------- | --------------------------------------------------------- | ---------------------------- |
-| `fec-code-reviewer`         | React/Vue/Next/Nuxt、TS、樣式、用戶端安全（按置信度降噪） | `code-review-*.md`           |
-| `fec-typescript-reviewer`   | 型別安全、非同步正確性、慣用模式（只報告不修改）          | `typescript-review-*.md`     |
-| `fec-security-reviewer`     | XSS、用戶端金鑰、危險 DOM/API、CSP、依賴稽核              | `security-review-*.md`       |
-| `fec-performance-optimizer` | 打包體積、渲染效能、網路瓶頸                              | `performance-review-*.md`    |
-| `fec-architect`             | 頁面拆分、元件架構、狀態流、目錄規劃                      | `architecture-proposal-*.md` |
-| `fec-test-planner`          | 風險-層級映射：靜態、單元、元件、E2E、視覺、無障礙、安全  | `test-plan-*.md`             |
-| `fec-debugger`              | 複雜前端診斷：建置、執行時、UI 和介面問題                 | `debug-*.md`                 |
-| `fec-refactor-cleaner`      | 分類並安全清理未使用程式碼、匯出、樣式、路由和依賴        | `refactor-clean-*.md`        |
-| `fec-refactoring-expert` | Behavior-preserving refactoring orchestration | `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`    |
-| `fec-figma-implementer`     | 依 Figma/Sketch/MasterGo/Pixso/墨刀設計稿精確實作 UI      | `design-implementation-*.md` |
-| `fec-design-token-mapper`   | 將設計變數對應至專案 Design Token                         | `token-mapping-*.md`         |
-
-### 鉤子（Hooks，事件驅動）
-
-鉤子在 AI 助手事件觸發時**自動執行**，無需手動呼叫。
-
-| 事件                      | 行為                                                 |
-| ------------------------- | ---------------------------------------------------- |
-| `SessionStart`            | 清理 Claude 快取，然後自動偵測專案框架與套件管理工具 |
-| `PreToolUse(Bash)`        | 攔截危險指令（`rm -rf`、force push 等）              |
-| `PostToolUse(Write/Edit)` | 對修改的檔案自動執行 Prettier                        |
-| `Stop`                    | 會話結束時執行 lint、type-check、test、build         |
-| `Notification`            | 跨平台桌面通知（macOS / Linux / Windows）            |
-
-### MCP 整合
-
-將 AI 助手接入設計工具，建構帶有更完整設計上下文的設計轉程式碼工作流。
-
-| 服務              | 能力                                   |
-| ----------------- | -------------------------------------- |
-| **Figma**         | 讀取設計上下文與變數定義               |
-| **Figma Desktop** | Figma 桌面端整合                       |
-| **Sketch**        | 讀取設計選區截圖                       |
-| **MasterGo**      | 讀取 DSL 結構、元件層級與樣式          |
-| **Pixso**         | 本地 MCP：幀資料、程式碼片段、圖片資源 |
-| **墨刀**          | 原型資料、設計描述、HTML 匯入          |
-| **摹客**          | 截圖／標註／匯出 CSS 工作流（無 MCP）  |
-
-### 專案範本（`/fec-init`）
-
-執行 `/fec-init` 即可將一套開箱即用的規則庫和專案設定腳手架化到 `.claude/`：
-
-<details>
-<summary>查看全部 20 個範本檔案</summary>
-
-| 檔案                                     | 用途                                                                  |
-| ---------------------------------------- | --------------------------------------------------------------------- |
-| `CLAUDE.md`                              | 專案說明、常用指令、工作原則、安全要求                                |
-| `settings.json`                          | 權限白名單／黑名單、環境變數                                          |
-| `rules/fec-vue.md`                       | Vue 3 元件規範與反模式                                                |
-| `rules/fec-react.md`                     | React 元件規範與反模式                                                |
-| `rules/fec-design-system.md`             | 設計系統、Token、可存取性規則                                         |
-| `rules/fec-testing.md`                   | 測試與校驗規則                                                        |
-| `rules/fec-git-conventions.md`           | Conventional Commits 提交規範                                         |
-| `rules/fec-i18n.md`                      | 國際化文案規範                                                        |
-| `rules/fec-performance.md`               | 前端效能最佳化規則                                                    |
-| `rules/fec-rendering-patterns.md`        | 渲染生命週期、hydration、SSR/CSR 與更新模式                           |
-| `rules/fec-responsive-design.md`         | 響應式佈局、斷點、觸控目標與視口行為                                  |
-| `rules/fec-source-driven-development.md` | Source-driven decisions, official docs, version-sensitive assumptions |
-| `rules/fec-api-layer.md`                 | API 層型別化與錯誤處理規範                                            |
-| `rules/fec-state-management.md`          | 狀態分類、管理策略與反模式                                            |
-| `rules/fec-error-handling.md`            | 錯誤分層、Error Boundary、降級 UI、上報規範                           |
-| `rules/fec-naming-conventions.md`        | 檔案、元件、變數、路由、API、CSS 統一命名                             |
-| `rules/fec-code-comments.md`             | 何時以及如何寫前端註釋                                                |
-| `rules/fec-ci-cd.md`                     | CI/CD 流水線階段、GitHub Actions / GitLab CI、金鑰管理                |
-| `rules/fec-refactoring.md`               | 重構約束與功能等價要求                                                |
-| `rules/fec-agent-workflow.md`            | 子代理協作邊界與委託規則                                              |
-| `rules/fec-working-modes.md`             | 調研、計畫、開發、評審、收尾模式指引                                  |
-
-</details>
-
----
-
-## 設定
-
-### 前置條件
-
-- **Node.js 22+**
-- **npm、pnpm 或 yarn**
-- **Git Bash 或相容 shell**（僅 Windows，當 AI 執行時需要呼叫 shell 指令時）
-
-### MCP 設計工具令牌
-
-根據團隊使用的設計工具設定對應環境變數：
-
-| 環境變數         | 工具                  | 取得方式                                  |
-| ---------------- | --------------------- | ----------------------------------------- |
-| `FIGMA_API_KEY`  | Figma / Figma Desktop | Figma 帳戶設定 → Personal Access Tokens   |
-| `SKETCH_API_KEY` | Sketch                | Sketch 開發者設定                         |
-| `MG_MCP_TOKEN`   | MasterGo              | MasterGo 帳戶設定 → 安全設定 → 產生 Token |
-| `MODAO_TOKEN`    | 墨刀                  | 墨刀 AI 功能頁面 → 存取權杖               |
-
-> **Pixso** 使用本地 MCP 服務 — 在 Pixso 用戶端中啟用即可，無需額外環境變數。
-> **摹客** 暫無 MCP 整合 — 透過截圖和匯出 CSS 方式工作。
-
-加入 shell 設定檔以持久化：
-
-```bash
-# macOS / Linux — 追加到 ~/.bashrc 或 ~/.zshrc
-export FIGMA_API_KEY="your-figma-api-key"
-export SKETCH_API_KEY="your-sketch-api-key"
-export MG_MCP_TOKEN="your-mastergo-token"
-export MODAO_TOKEN="your-modao-token"
-```
-
-```powershell
-# Windows — 設為系統環境變數，或在 PowerShell 中臨時設定：
-$env:FIGMA_API_KEY = "your-figma-api-key"
-$env:SKETCH_API_KEY = "your-sketch-api-key"
-$env:MG_MCP_TOKEN = "your-mastergo-token"
-$env:MODAO_TOKEN = "your-modao-token"
-```
-
----
-
-## 報告輸出
-
-每一次審查、分析和評估都會輸出帶時間戳記的 Markdown 報告到 `reports/`，可作為稽核記錄和 PR 交付物。
-
-<details>
-<summary>查看全部 16 種報告類型</summary>
-
-| 報告類型       | 檔名模式                                     | 來源                                                                |
-| -------------- | -------------------------------------------- | ------------------------------------------------------------------- |
-| 程式碼審查     | `code-review-YYYY-MM-DD-HHmmss.md`           | `/fec-review`、`fec-code-review`、`fec-code-reviewer`               |
-| 除錯診斷       | `debug-YYYY-MM-DD-HHmmss.md`                 | `/fec-debug`、`fec-debug-framework`、`fec-debugger`                 |
-| TS/JS 專項審查 | `typescript-review-YYYY-MM-DD-HHmmss.md`     | `fec-typescript-reviewer`                                           |
-| 安全審查       | `security-review-YYYY-MM-DD-HHmmss.md`       | `fec-security-review`、`fec-security-reviewer`                      |
-| 無障礙檢查     | `accessibility-review-YYYY-MM-DD-HHmmss.md`  | `fec-accessibility-check`                                           |
-| 效能分析       | `performance-review-YYYY-MM-DD-HHmmss.md`    | `fec-performance-optimizer`                                         |
-| 架構方案       | `architecture-proposal-YYYY-MM-DD-HHmmss.md` | `fec-architect`                                                     |
-| 設計還原度     | `ui-fidelity-review-YYYY-MM-DD-HHmmss.md`    | `fec-ui-checker`                                                    |
-| 設計實現       | `design-implementation-YYYY-MM-DD-HHmmss.md` | `fec-figma-implementer`                                             |
-| Token 對應     | `token-mapping-YYYY-MM-DD-HHmmss.md`         | `fec-design-token-mapper`                                           |
-| 設計計畫       | `design-plan-YYYY-MM-DD-HHmmss.md`           | `fec-implement-from-design`                                         |
-| 測試計畫       | `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` |
-| E2E 執行摘要   | `e2e-summary-YYYY-MM-DD-HHmmss.md`           | `fec-e2e-runner`（可選）                                            |
-| 遷移計畫       | `migration-plan-YYYY-MM-DD-HHmmss.md`        | `fec-legacy-to-modern-migration`                                    |
-
-</details>
-
-> **建議：** 在 `.gitignore` 中加入 `reports/` 以避免將自動產生的報告提交至程式碼倉庫，或保留提交以便團隊檢視歷史審查記錄。
-
----
-
-## 更新與移除
-
-`fec` 是 `frontend-craft` 的短命令。如果沒有全域安裝 `fec`，可以把同樣參數接在 `npx @bovinphang/frontend-craft@latest` 後使用，例如 `npx @bovinphang/frontend-craft@latest update`。
-
-### 更新
-
-```bash
-fec update                         # 更新自動發現到的所有 CLI 管理安裝
-fec update <runtime> --local        # 更新一個本地 CLI 管理安裝
-fec update <runtime> --global       # 更新一個全域 CLI 管理安裝
-fec 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     # 連同已修改的託管檔案一起移除
-```
-
-CLI 會在 runtime 目錄寫入 `frontend-craft.manifest.json`。不傳 runtime 時，`update` 會自動發現這些 manifest，並**跳過你本地修改過的檔案**——自訂內容在更新後依然保留。
-
-`uninstall`/`remove` 只刪除 manifest 記錄的檔案，預設跳過已修改檔案；只有確認要移除修改過的託管檔案時才加 `--force`。`--force` 不會覆蓋 Claude Code Marketplace 安裝。
-
-**Claude Code Marketplace** 或 **submodule** 安裝的更新方式見 [docs/runtimes/claude.zh-CN.md](../runtimes/claude.zh-CN.md) · [English](../runtimes/claude.md)。`/fec-init` 只初始化專案設定，不是第二次安裝插件本體。
-
----
-
-## 舊版 Skills CLI
-
-如果團隊已在使用獨立的 [Skills CLI](https://skills.sh/docs/cli)，它仍然可以只安裝 [`skills/`](../../skills/) 下的工作流技能包：
-
-```bash
-npx skills add bovinphang/frontend-craft   # 按提示操作，加 -g 可全域安裝
-npx skills update                          # 更新至最新版本
-npx skills check                           # 預覽可用更新
-```
-
-| CLI                              | 安裝內容                                      |
-| -------------------------------- | --------------------------------------------- |
-| `npx @bovinphang/frontend-craft` | 技能 + 執行時專屬代理、指令、鉤子、規則、範本 |
-| `npx skills`                     | 僅技能（適用於已有 Skills CLI 工作流）        |
-
-關閉遙測：`DISABLE_TELEMETRY=1`。詳見 [skills.sh CLI 文件](https://skills.sh/docs/cli)。
-
----
-
-## 社群
-
-- [貢獻指南](../../CONTRIBUTING.md) — 開發環境、PR 檢查清單與多語言同步規則（[简体中文](../../CONTRIBUTING.zh-CN.md)）
-- [安全政策](../../SECURITY.md) — 私密漏洞回報方式與支援範圍（[简体中文](../../SECURITY.zh-CN.md)）
-- [行為準則](../../CODE_OF_CONDUCT.md) — 社群參與規範（[简体中文](../../CODE_OF_CONDUCT.zh-CN.md)）
-- [變更日誌](../../CHANGELOG.md) — 版本說明（[简体中文](../../CHANGELOG.zh-CN.md)）
-- [專案結構](../project-structure.md) — 完整目錄佈局與檔案職責
-
----
-
-## 授權條款
-
-[MIT](../../LICENSE) — 自由使用、依需求修改，歡迎回饋。
-
----
-
-<div align="center">
-
-**如果 frontend-craft 幫助了你的團隊，[請給它一個 Star](https://github.com/bovinphang/frontend-craft)。**
-
-</div>
+<div align="center">
+
+<img src="../../assets/brand/frontend-craft.png" alt="frontend-craft logo" width="200" />
+
+# frontend-craft
+
+### 一套工具，適配所有 AI 程式設計助手，落地生產級前端規範。
+
+[![Stars](https://img.shields.io/github/stars/bovinphang/frontend-craft?style=flat)](https://github.com/bovinphang/frontend-craft/stargazers)
+[![CI](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml/badge.svg)](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@bovinphang/frontend-craft)](https://www.npmjs.com/package/@bovinphang/frontend-craft)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+![Node](https://img.shields.io/badge/Node.js-22+-5FA04E?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
+![React](https://img.shields.io/badge/-React-61DAFB?logo=react&logoColor=black)
+![Vue](https://img.shields.io/badge/-Vue-4FC08D?logo=vue.js&logoColor=white)
+![Figma](https://img.shields.io/badge/-Figma-F24E1E?logo=figma&logoColor=white)
+
+**🌐 Language / 语言 / 語言 / 言語 / 언어**
+
+[English](../../README.md) · [简体中文](../../README.zh-CN.md) · [**繁體中文**](README.md) · [日本語](../ja-JP/README.md) · [한국어](../ko-KR/README.md)
+
+</div>
+
+
+[執行環境相容性與升級說明](../runtimes/compatibility.md)
+
+---
+
+`frontend-craft` 是一個**通用前端插件**，為以下 **15 款 AI 程式設計助手**注入統一的前端工程規範：
+
+`claude` `codex` `cursor` `windsurf` `opencode`
+`kilo` `gemini` `copilot` `antigravity` `augment`
+`trae` `codebuddy` `cline` `openclaw` `qoder`
+
+各執行時的路徑與注意事項詳見 [`docs/runtimes/`](../runtimes/)。
+
+它將 **14 個專業 agent**、**61 個自動啟用 skill**、**11 個斜線指令**、**5 個事件驅動 hook**、面向 6 個設計工具端點的 **MCP 整合**以及一整套**規則庫**打包為一個可安裝單元。執行一條指令，團隊裡的每一次 AI 會話都將以相同的方式編寫 React、Vue、Next.js 或 Nuxt——型別安全、可存取、安全、一致。
+
+---
+
+## 為什麼選擇 frontend-craft？
+
+| 痛點                                            | frontend-craft 的解法                                                                   |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| AI 助手寫出的前端程式碼風格不一、缺型別、不安全 | **61 個 skill** 將團隊規範編碼為可自動啟用的工作流                                      |
+| 每款 AI 工具都有自己的插件格式                  | **一條 CLI 指令** 把相同的規則、agent 和 hook 安裝到 15 個執行時                        |
+| 設計稿到程式碼的交接總有資訊損失                | **MCP 整合** 從 Figma、Figma Desktop、Sketch、MasterGo、Pixso、墨刀引入更完整設計上下文 |
+| 程式碼審查隨意、淺層                            | **14 個 agent** 輸出分級報告：程式碼、安全、無障礙、效能、TS、UI 還原度                 |
+| 沒人記得跑 lint 和測試                          | **事件驅動 hook** 在儲存和會話結束時自動校驗                                            |
+| 新專案每次都從零開始                            | **`/fec-init`** 幾秒內腳手架化 CLAUDE.md、規則和 settings                               |
+
+---
+
+## 安裝
+
+需要 **Node.js 22+**。完整支援 **Windows、macOS 和 Linux**（所有鉤子和腳本均使用 Node.js 實作）。
+
+### 方式一：全域安裝 fec CLI（推薦）
+
+```bash
+# 1. 全域安裝 fec 指令
+npm install -g @bovinphang/frontend-craft@latest
+
+# 2. 進入你的前端專案
+cd your-project
+
+# 3. 互動選擇要接入的 AI 執行時
+fec setup
+
+# 4. 接入目前專案
+fec setup codex
+fec setup claude
+fec setup all
+
+# 5. 全域接入，適用於所有專案
+fec setup codex --global
+fec setup claude --global
+fec setup all --global
+
+# 6. 預覽 / 查詢
+fec runtime install --all --dry-run --global
+fec list
+```
+
+`npm install -g` 只是安裝 `fec` 終端機指令。`fec setup` 是終端機中的 CLI 專案接入指令，不是 AI 助手內的 `/fec-init` 斜線指令。在互動式終端機中，不帶參數的 `fec setup` 會先讓你選擇 runtime；`fec setup <runtime>` 和 `fec setup all` 會預設接入目前專案。只有傳入 `--global` 時，才會接入對應 AI 工具的全域設定目錄，適用於所有專案。
+
+### 方式二：用 npx 臨時執行（免全域安裝 fec）
+
+```bash
+# 1. 互動精靈
+npx @bovinphang/frontend-craft@latest
+
+# 2. 接入目前專案
+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 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 runtime install --all --dry-run --global
+npx @bovinphang/frontend-craft@latest list
+```
+
+不想全域安裝 `fec` 指令時使用 `npx`。不帶參數會進入互動精靈：先選擇一個或多個執行時，再決定接入全域還是目前專案。腳本化安裝全部 runtime 時使用 `install --all --local` 或 `install --all --global`，不要寫成 `install all`。CI / 腳本場景請務必帶上 `--global` / `-g` 或 `--local` / `-l`；非 TTY 且未指定時，CLI 預設安裝到 `claude --global`。
+
+### 方式三：Claude Code Marketplace
+
+對 Claude Code 用戶，**Claude Code Marketplace** 是推薦的單一來源安裝方式。只有在需要跨執行時安裝、腳本化/離線複製檔案，或非 Marketplace 環境時，才建議對 Claude 使用 CLI。
+
+如果已經透過 Marketplace 安裝，CLI 不會再安裝或更新第二份 Claude 副本，即使傳入 `--force` 也不會覆蓋；請透過 Claude Code Marketplace 更新。如果已存在另一個作用域的 CLI 管理安裝，互動式終端會詢問是保持已安裝來源並更新，還是解除安裝後切換至當前來源；非互動式終端會停止並列印明確的 `runtime update`、`runtime uninstall`、`runtime install` 命令。
+
+完整步驟見 [docs/runtimes/claude.zh-CN.md](../runtimes/claude.zh-CN.md) · [English](../runtimes/claude.md)。
+
+---
+
+## 快速開始
+
+安裝完成後，你在每一次 AI 會話中都擁有一套完整的前端工程工具箱：
+
+```text
+你："Review my recent changes"
+→ fec-code-reviewer agent 被調度，輸出 reports/code-review-*.md
+
+你："/fec-review"
+→ 按架構、型別、渲染、樣式、可存取性等維度執行結構化審查
+
+你："根據這個 Figma 連結實現結算頁"
+→ fec-figma-implementer agent 透過 MCP 讀取設計稿，輸出元件和報告
+
+你："/fec-scaffold dashboard feature"
+→ 依專案約定建立 page / feature / component 標準目錄結構
+
+你："/fec-refactor-clean"
+→ 分類並安全清理死程式碼、未使用匯出、樣式和依賴
+```
+
+下文斜線指令以 **Claude Code** 為例；其他執行時透過各自的指令系統提供同等能力（詳見 [`docs/runtimes/`](../runtimes/)）。
+
+---
+
+## 範例提示詞
+
+完整的按場景組織提示詞庫請參考 [docs/example-prompts.md](../example-prompts.md)。
+
+```text
+你：「合併前請審查我最近的改動。重點看架構、型別安全、渲染行為、樣式、可存取性和缺失測試。」
+你：「先不要寫程式碼，請規劃帳號帳單功能：路由結構、元件邊界、資料流、狀態歸屬、驗證流程和上線風險。」
+你：「請建構多步註冊表單：依專案框架選擇表單與 schema 驗證方案，包含檔案上傳、條件欄位、非同步驗證和可存取錯誤提示。」
+你：「請按 Figma 節點 123:456 實作 UI。複用現有 design token 和元件，匹配間距與響應式狀態，並說明假設。」
+你：「`/fec-refactor-clean` 請清理這個模組裡的死程式碼。」
+```
+
+---
+
+## 裡面有什麼
+
+### 指令（Commands）
+
+斜線指令是結構化工作流的主入口，多數會輸出帶時間戳記的 Markdown 報告到 `reports/`。
+
+| 指令                  | 用途                                                        | 報告                                             |
+| --------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
+| `/fec-init`           | 初始化專案範本（CLAUDE.md、規則、settings）                 | —                                                |
+| `/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` | Diagnose code smells without editing | `refactoring/smell-*.md` |
+| `/fec-refactor-plan` | Plan behavior-preserving refactoring | `refactoring/plan-*.md` |
+| `/fec-refactor` | Execute validated behavior-preserving refactoring | `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，自動啟用）
+
+技能是根據檔案模式、框架或任務上下文**自動啟用**的工作流定義，編碼了審查維度、輸出約定和報告格式。
+
+下方按使用場景分組列出全部自動啟用的技能，便於快速找到專案規範、實作、測試、審查、設計、遷移、專案演進和文件維護能力。
+
+**專案規範** — 偵測到對應框架時自動生效：
+
+| 技能                              | 範圍                                                  |
+| --------------------------------- | ----------------------------------------------------- |
+| `fec-react-project-standard`      | React + TypeScript（結構、元件、路由、狀態、API 層）  |
+| `fec-vue3-project-standard`       | Vue 3 + TypeScript（結構、元件、路由、Pinia、API 層） |
+| `fec-nextjs-project-standard`     | Next.js 14+ App Router、SSR/SSG、流式渲染、元資料     |
+| `fec-nuxt-project-standard`       | Nuxt 3 SSR/SSG、組合式 API、資料獲取、中介軟體        |
+| `fec-vite-project-standard`       | Vite 設定、環境變數安全、HMR、開發代理、建置最佳化    |
+| `fec-monorepo-project-standard`   | pnpm workspace、Turborepo、Nx 結構與任務編排          |
+| `cc-typescript-project-standard` | TypeScript 設定、公開型別、宣告檔、DTO 和泛型         |
+
+**實作能力** — 建構特定前端能力時啟用：
+
+| 技能                      | 範圍                                                       |
+| ------------------------- | ---------------------------------------------------------- |
+| `fec-data-fetching`       | 服務端狀態獲取、快取、失效、SSR、無限載入                  |
+| `fec-api-integration`     | 型別化 API client、鑑權刷新、上傳、即時整合                |
+| `fec-state-management`    | 狀態歸屬、store 選型、URL 狀態、伺服器/表單/本地狀態邊界   |
+| `fec-form-handling`       | 跨框架表單選型、schema 驗證、動態欄位、上傳                |
+| `fec-browser-storage`     | localStorage / sessionStorage / IndexedDB / Cookies 選型   |
+| `fec-route-protection`    | React Router、Next.js、Vue Router、Nuxt 的登入態與權限路由 |
+| `fec-pwa-implementation`  | manifest、Service Worker、離線快取、安裝提示               |
+| `fec-web-workers`         | Web Worker、Transferable、Comlink、Worker 池               |
+| `fec-canvas-threejs`      | Canvas 2D、Three.js、React Three Fiber、WebGL              |
+| `fec-svg-animation`       | CSS / Framer Motion / GSAP SVG 動畫與 reduced-motion       |
+| `fec-list-virtualization` | 依框架選型的大清單虛擬滾動、測量、網格和無限滾動           |
+
+**測試** — 規劃或撰寫前端測試覆蓋時啟用：
+
+| 技能                    | 範圍                                                      |
+| ----------------------- | --------------------------------------------------------- |
+| `fec-testing-strategy`  | 靜態檢查、單元、元件、整合、E2E、視覺測試分層             |
+| `fec-component-testing` | React Testing Library / Vue Test Utils 元件測試與回歸用例 |
+| `fec-e2e-testing`       | Playwright / Cypress E2E 與 Page Object 和 CI 整合        |
+| `fec-tdd-workflow`      | 測試先行的前端實作，紅綠重構循環                          |
+
+**審查與品質** — 程式碼審查、驗證或清理時啟用：
+
+| 技能                           | 範圍                                                    |
+| ------------------------------ | ------------------------------------------------------- |
+| `fec-code-review`              | 架構、型別、渲染、樣式、可存取性審查                    |
+| `fec-debug-framework`          | 系統化診斷建置、執行時、UI 和 API/資料問題              |
+| `fec-security-review`          | XSS、CSRF、敏感資料外洩、輸入驗證                       |
+| `fec-accessibility-check`      | WCAG 2.2、鍵盤、焦點、觸控和螢幕閱讀器行為              |
+| `fec-dependency-upgrade`       | 依賴升級、lockfile 審查、CVE 修復和遷移驗證             |
+| `fec-validation-fix`           | 一次性執行並修復 lint、type-check、test、build          |
+| `fec-performance-optimization` | Core Web Vitals、包體、渲染、記憶體、網路與效能預算審查 |
+| `fec-refactor-clean`           | 安全清理死程式碼、未使用匯出、樣式、路由和依賴          |
+
+**Refactoring**
+
+| Skill | Scope |
+| --- | --- |
+| `fec-refactoring` | Behavior-preserving refactoring capability |
+| `fec-code-smells` | Behavior-preserving refactoring capability |
+| `fec-refactoring-catalog` | Behavior-preserving refactoring capability |
+| `fec-refactoring-functions` | Behavior-preserving refactoring capability |
+| `fec-refactoring-encapsulation` | Behavior-preserving refactoring capability |
+| `fec-refactoring-move-features` | Behavior-preserving refactoring capability |
+| `fec-refactoring-data` | Behavior-preserving refactoring capability |
+| `fec-refactoring-control` | Behavior-preserving refactoring capability |
+| `fec-refactoring-api` | Behavior-preserving refactoring capability |
+| `fec-refactoring-inheritance` | Behavior-preserving refactoring capability |
+| `fec-refactoring-validation` | Behavior-preserving refactoring capability |
+
+**設計 UI** — 設計實作、設計系統或視覺打磨時啟用：
+
+| 技能                          | 範圍                                                                                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `fec-ui-design`               | 產品語境 UI 方向、反模板設計撥盤、媒體策略、狀態、視覺 QA                                        |
+| `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`       | 移動優先布局、容器查詢、資料密集型響應式界面                                                     |
+| `fec-motion-interaction`      | 場景化動效強度、頁面轉場、滾動動畫、reduced-motion                                               |
+| `fec-implement-from-design`   | 基於設計工具、截圖或分區級視覺參考實現 UI                                                        |
+| `fec-storybook-component-doc` | Storybook 元件文件、設計系統呈現、隔離狀態預覽                                                   |
+
+技術圖品質：標準時序圖、流程圖優先本機 Mermaid，可編輯架構圖優先 draw.io；工具缺少時使用 JSON/HTML。以符合 PNG 比例的實測 manifest 執行 QA，並檢視最終圖片。預設最多修復兩輪，未解決問題必須明確回報。
+
+[審查範圍與技術圖交付指南](../zh-CN/review-and-diagram-workflows.md).
+
+**遺留遷移** — 現代化遷移時啟用：
+
+| 技能                             | 範圍                                           |
+| -------------------------------- | ---------------------------------------------- |
+| `fec-legacy-web-standard`        | JS + jQuery + HTML 傳統專案的開發與維護規範    |
+| `fec-legacy-to-modern-migration` | 遺留前端現代化、目標技術棧識別與分階段遷移流程 |
+
+**專案演進** — 吸收參考系統並原創化落到目前專案時啟用：
+
+| 技能          | 範圍                                       |
+| ------------- | ------------------------------------------ |
+| `fec-alchemy` | 將參考系統能力原創化吸收到目前專案原生體系 |
+
+**文件維護** — 文件維護時啟用：
+
+| 技能                               | 範圍                                                                  |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `fec-backend-requirements-handoff` | 前端向後端交接 UI 資料需求、使用者動作、狀態、業務規則與待確認問題    |
+| `fec-doc-sync`                     | 讓前端文件與程式碼、設定、腳本、路由、API、環境變數和部署事實保持同步 |
+| `cc-source-driven-development`    | 以專案事實和官方來源驗證版本敏感的前端決策                            |
+
+### 代理（Agents）
+
+代理是由主助手調度的專業子代理，專注處理單一任務並返回結構化報告。
+
+| 代理                        | 聚焦領域                                                  | 報告                         |
+| --------------------------- | --------------------------------------------------------- | ---------------------------- |
+| `fec-code-reviewer`         | React/Vue/Next/Nuxt、TS、樣式、用戶端安全（按置信度降噪） | `code-review-*.md`           |
+| `fec-typescript-reviewer`   | 型別安全、非同步正確性、慣用模式（只報告不修改）          | `typescript-review-*.md`     |
+| `fec-security-reviewer`     | XSS、用戶端金鑰、危險 DOM/API、CSP、依賴稽核              | `security-review-*.md`       |
+| `fec-performance-optimizer` | 打包體積、渲染效能、網路瓶頸                              | `performance-review-*.md`    |
+| `fec-architect`             | 頁面拆分、元件架構、狀態流、目錄規劃                      | `architecture-proposal-*.md` |
+| `fec-test-planner`          | 風險-層級映射：靜態、單元、元件、E2E、視覺、無障礙、安全  | `test-plan-*.md`             |
+| `fec-debugger`              | 複雜前端診斷：建置、執行時、UI 和介面問題                 | `debug-*.md`                 |
+| `fec-refactor-cleaner`      | 分類並安全清理未使用程式碼、匯出、樣式、路由和依賴        | `refactor-clean-*.md`        |
+| `fec-refactoring-expert` | Behavior-preserving refactoring orchestration | `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`    |
+| `fec-figma-implementer`     | 依 Figma/Sketch/MasterGo/Pixso/墨刀設計稿精確實作 UI      | `design-implementation-*.md` |
+| `fec-design-token-mapper`   | 將設計變數對應至專案 Design Token                         | `token-mapping-*.md`         |
+
+### 鉤子（Hooks，事件驅動）
+
+鉤子在 AI 助手事件觸發時**自動執行**，無需手動呼叫。
+
+| 事件                      | 行為                                                 |
+| ------------------------- | ---------------------------------------------------- |
+| `SessionStart`            | 清理 Claude 快取，然後自動偵測專案框架與套件管理工具 |
+| `PreToolUse(Bash)`        | 攔截危險指令（`rm -rf`、force push 等）              |
+| `PostToolUse(Write/Edit)` | 對修改的檔案自動執行 Prettier                        |
+| `Stop`                    | 會話結束時執行 lint、type-check、test、build         |
+| `Notification`            | 跨平台桌面通知（macOS / Linux / Windows）            |
+
+### MCP 整合
+
+將 AI 助手接入設計工具，建構帶有更完整設計上下文的設計轉程式碼工作流。
+
+| 服務              | 能力                                   |
+| ----------------- | -------------------------------------- |
+| **Figma**         | 讀取設計上下文與變數定義               |
+| **Figma Desktop** | Figma 桌面端整合                       |
+| **Sketch**        | 讀取設計選區截圖                       |
+| **MasterGo**      | 讀取 DSL 結構、元件層級與樣式          |
+| **Pixso**         | 本地 MCP：幀資料、程式碼片段、圖片資源 |
+| **墨刀**          | 原型資料、設計描述、HTML 匯入          |
+| **摹客**          | 截圖／標註／匯出 CSS 工作流（無 MCP）  |
+
+### 專案範本（`/fec-init`）
+
+執行 `/fec-init` 即可將一套開箱即用的規則庫和專案設定腳手架化到 `.claude/`：
+
+<details>
+<summary>查看全部 20 個範本檔案</summary>
+
+| 檔案                                     | 用途                                                                  |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| `CLAUDE.md`                              | 專案說明、常用指令、工作原則、安全要求                                |
+| `settings.json`                          | 權限白名單／黑名單、環境變數                                          |
+| `rules/fec-vue.md`                       | Vue 3 元件規範與反模式                                                |
+| `rules/fec-react.md`                     | React 元件規範與反模式                                                |
+| `rules/fec-design-system.md`             | 設計系統、Token、可存取性規則                                         |
+| `rules/fec-testing.md`                   | 測試與校驗規則                                                        |
+| `rules/fec-git-conventions.md`           | Conventional Commits 提交規範                                         |
+| `rules/fec-i18n.md`                      | 國際化文案規範                                                        |
+| `rules/fec-performance.md`               | 前端效能最佳化規則                                                    |
+| `rules/fec-rendering-patterns.md`        | 渲染生命週期、hydration、SSR/CSR 與更新模式                           |
+| `rules/fec-responsive-design.md`         | 響應式佈局、斷點、觸控目標與視口行為                                  |
+| `rules/fec-source-driven-development.md` | Source-driven decisions, official docs, version-sensitive assumptions |
+| `rules/fec-api-layer.md`                 | API 層型別化與錯誤處理規範                                            |
+| `rules/fec-state-management.md`          | 狀態分類、管理策略與反模式                                            |
+| `rules/fec-error-handling.md`            | 錯誤分層、Error Boundary、降級 UI、上報規範                           |
+| `rules/fec-naming-conventions.md`        | 檔案、元件、變數、路由、API、CSS 統一命名                             |
+| `rules/fec-code-comments.md`             | 何時以及如何寫前端註釋                                                |
+| `rules/fec-ci-cd.md`                     | CI/CD 流水線階段、GitHub Actions / GitLab CI、金鑰管理                |
+| `rules/fec-refactoring.md`               | 重構約束與功能等價要求                                                |
+| `rules/fec-agent-workflow.md`            | 子代理協作邊界與委託規則                                              |
+| `rules/fec-working-modes.md`             | 調研、計畫、開發、評審、收尾模式指引                                  |
+
+</details>
+
+---
+
+## 設定
+
+### 前置條件
+
+- **Node.js 22+**
+- **npm、pnpm 或 yarn**
+- **Git Bash 或相容 shell**（僅 Windows，當 AI 執行時需要呼叫 shell 指令時）
+
+### MCP 設計工具令牌
+
+根據團隊使用的設計工具設定對應環境變數：
+
+| 環境變數         | 工具                  | 取得方式                                  |
+| ---------------- | --------------------- | ----------------------------------------- |
+| `FIGMA_API_KEY`  | Figma / Figma Desktop | Figma 帳戶設定 → Personal Access Tokens   |
+| `SKETCH_API_KEY` | Sketch                | Sketch 開發者設定                         |
+| `MG_MCP_TOKEN`   | MasterGo              | MasterGo 帳戶設定 → 安全設定 → 產生 Token |
+| `MODAO_TOKEN`    | 墨刀                  | 墨刀 AI 功能頁面 → 存取權杖               |
+
+> **Pixso** 使用本地 MCP 服務 — 在 Pixso 用戶端中啟用即可，無需額外環境變數。
+> **摹客** 暫無 MCP 整合 — 透過截圖和匯出 CSS 方式工作。
+
+加入 shell 設定檔以持久化：
+
+```bash
+# macOS / Linux — 追加到 ~/.bashrc 或 ~/.zshrc
+export FIGMA_API_KEY="your-figma-api-key"
+export SKETCH_API_KEY="your-sketch-api-key"
+export MG_MCP_TOKEN="your-mastergo-token"
+export MODAO_TOKEN="your-modao-token"
+```
+
+```powershell
+# Windows — 設為系統環境變數，或在 PowerShell 中臨時設定：
+$env:FIGMA_API_KEY = "your-figma-api-key"
+$env:SKETCH_API_KEY = "your-sketch-api-key"
+$env:MG_MCP_TOKEN = "your-mastergo-token"
+$env:MODAO_TOKEN = "your-modao-token"
+```
+
+---
+
+## 報告輸出
+
+每一次審查、分析和評估都會輸出帶時間戳記的 Markdown 報告到 `reports/`，可作為稽核記錄和 PR 交付物。
+
+<details>
+<summary>查看全部 16 種報告類型</summary>
+
+| 報告類型       | 檔名模式                                     | 來源                                                                |
+| -------------- | -------------------------------------------- | ------------------------------------------------------------------- |
+| 程式碼審查     | `code-review-YYYY-MM-DD-HHmmss.md`           | `/fec-review`、`fec-code-review`、`fec-code-reviewer`               |
+| 除錯診斷       | `debug-YYYY-MM-DD-HHmmss.md`                 | `/fec-debug`、`fec-debug-framework`、`fec-debugger`                 |
+| TS/JS 專項審查 | `typescript-review-YYYY-MM-DD-HHmmss.md`     | `fec-typescript-reviewer`                                           |
+| 安全審查       | `security-review-YYYY-MM-DD-HHmmss.md`       | `fec-security-review`、`fec-security-reviewer`                      |
+| 無障礙檢查     | `accessibility-review-YYYY-MM-DD-HHmmss.md`  | `fec-accessibility-check`                                           |
+| 效能分析       | `performance-review-YYYY-MM-DD-HHmmss.md`    | `fec-performance-optimizer`                                         |
+| 架構方案       | `architecture-proposal-YYYY-MM-DD-HHmmss.md` | `fec-architect`                                                     |
+| 設計還原度     | `ui-fidelity-review-YYYY-MM-DD-HHmmss.md`    | `fec-ui-checker`                                                    |
+| 設計實現       | `design-implementation-YYYY-MM-DD-HHmmss.md` | `fec-figma-implementer`                                             |
+| Token 對應     | `token-mapping-YYYY-MM-DD-HHmmss.md`         | `fec-design-token-mapper`                                           |
+| 設計計畫       | `design-plan-YYYY-MM-DD-HHmmss.md`           | `fec-implement-from-design`                                         |
+| 測試計畫       | `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` |
+| E2E 執行摘要   | `e2e-summary-YYYY-MM-DD-HHmmss.md`           | `fec-e2e-runner`（可選）                                            |
+| 遷移計畫       | `migration-plan-YYYY-MM-DD-HHmmss.md`        | `fec-legacy-to-modern-migration`                                    |
+
+</details>
+
+> **建議：** 在 `.gitignore` 中加入 `reports/` 以避免將自動產生的報告提交至程式碼倉庫，或保留提交以便團隊檢視歷史審查記錄。
+
+---
+
+## 更新與移除
+
+### 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 registry 全域安裝；原始碼連結、專案依賴、未知來源及含其他套件的 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` 僅使用目前 CLI 套件內容，不連網取得新套件。
+
+`fec` 是 `frontend-craft` 的短命令。未全域安裝 CLI 時，資源操作使用 `npx @bovinphang/frontend-craft@latest runtime update`（或 `runtime install/uninstall`）。
+
+### 資源更新
+
+```bash
+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 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 時，`runtime update` 會自動發現這些 manifest，並**跳過你本地修改過的檔案**——自訂內容在更新後依然保留。
+
+`runtime uninstall`/`runtime remove` 只刪除 manifest 記錄的檔案，預設跳過已修改檔案；只有確認要移除修改過的託管檔案時才加 `--force`。`--force` 不會覆蓋 Claude Code Marketplace 安裝。
+
+**Claude Code Marketplace** 或 **submodule** 安裝的更新方式見 [docs/runtimes/claude.zh-CN.md](../runtimes/claude.zh-CN.md) · [English](../runtimes/claude.md)。`/fec-init` 只初始化專案設定，不是第二次安裝插件本體。
+
+---
+
+## 舊版 Skills CLI
+
+如果團隊已在使用獨立的 [Skills CLI](https://skills.sh/docs/cli)，它仍然可以只安裝 [`skills/`](../../skills/) 下的工作流技能包：
+
+```bash
+npx skills add bovinphang/frontend-craft   # 按提示操作，加 -g 可全域安裝
+npx skills update                          # 更新至最新版本
+npx skills check                           # 預覽可用更新
+```
+
+| CLI                              | 安裝內容                                      |
+| -------------------------------- | --------------------------------------------- |
+| `npx @bovinphang/frontend-craft` | 技能 + 執行時專屬代理、指令、鉤子、規則、範本 |
+| `npx skills`                     | 僅技能（適用於已有 Skills CLI 工作流）        |
+
+關閉遙測：`DISABLE_TELEMETRY=1`。詳見 [skills.sh CLI 文件](https://skills.sh/docs/cli)。
+
+---
+
+## 社群
+
+- [貢獻指南](../../CONTRIBUTING.md) — 開發環境、PR 檢查清單與多語言同步規則（[简体中文](../../CONTRIBUTING.zh-CN.md)）
+- [安全政策](../../SECURITY.md) — 私密漏洞回報方式與支援範圍（[简体中文](../../SECURITY.zh-CN.md)）
+- [行為準則](../../CODE_OF_CONDUCT.md) — 社群參與規範（[简体中文](../../CODE_OF_CONDUCT.zh-CN.md)）
+- [變更日誌](../../CHANGELOG.md) — 版本說明（[简体中文](../../CHANGELOG.zh-CN.md)）
+- [專案結構](../project-structure.md) — 完整目錄佈局與檔案職責
+
+---
+
+## 授權條款
+
+[MIT](../../LICENSE) — 自由使用、依需求修改，歡迎回饋。
+
+---
+
+<div align="center">
+
+**如果 frontend-craft 幫助了你的團隊，[請給它一個 Star](https://github.com/bovinphang/frontend-craft)。**
+
+</div>
+
+## 3.0 共用能力
+
+3.0.0仍未發布，包含53個前端專屬入口與21個共用入口，共74個Skill。公共來源精確固定為`@bovinphang/craft-common@2.0.0`；2.0.0為待發布的正式版本號，backend1.0.0也仍未發布。公共包先行發布並核驗，產品版本不變，不自動發布。
+
+語言、角色與框架分開選擇；C/C++有獨立入口，Tauri/Electron為共用桌面專項，不以產品前後端名稱限制語言。
+
+- `cc-c-project-standard`
+- `cc-cpp-project-standard`
+- `cc-debug-methodology`
+- `cc-doc-sync-core`
+- `cc-drawio-studio`
+- `cc-electron-project-standard`
+- `cc-go-concurrency`
+- `cc-go-project-standard`
+- `cc-java-project-standard`
+- `cc-java-runtime`
+- `cc-native-memory-safety`
+- `cc-python-async`
+- `cc-python-project-standard`
+- `cc-refactoring-core`
+- `cc-rust-async`
+- `cc-rust-project-standard`
+- `cc-source-driven-development`
+- `cc-tauri-project-standard`
+- `cc-tdd-methodology`
+- `cc-technical-diagrams`
+- `cc-typescript-project-standard`
+
+執行`fec runtime check-migration codex --local --json`，先以舊CLI退出舊公共引用並處理保留編輯，再安裝匹配產品；不強制覆蓋另一消費者或未知檔案。CLI與原生渠道互斥，雙原生產品去重仍不在保證範圍。
+
+[遷移指南](../zh-CN/common-migration.md) · [變更日誌](../../CHANGELOG.zh-CN.md) · [專案結構](../zh-CN/project-structure.md)