@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/docs/zh-CN/project-structure.md

@@ -1,123 +1,148 @@
-# 项目结构
-
-`frontend-craft` 的详细目录布局。
-
-## 仓库布局
-
-```text
-frontend-craft/
-|-- .claude-plugin/   # Claude Code 插件与 marketplace 清单
-|   |-- plugin.json         # 插件元数据
-|   |-- marketplace.json    # Marketplace 目录元数据
-|
-|-- agents/           # 用于委托的专业子代理
-|   |-- fec-architect.md    # 页面拆分、组件架构、状态流
-|   |-- fec-code-reviewer.md # 前端专项代码评审（质量、安全、无障碍）
-|   |-- fec-security-reviewer.md # 前端攻击面：XSS、密钥、CSP、依赖
-|   |-- fec-test-planner.md # 测试策略、风险矩阵、覆盖规划
-|   |-- fec-debugger.md # 复杂构建/运行时/UI/API 问题诊断
-|   |-- fec-refactor-cleaner.md # 死代码和未使用依赖清理
-|   |-- fec-doc-updater.md # README/runtime 文档/能力表同步
-|   |-- fec-e2e-runner.md     # E2E 编写、执行、flaky 治理、产物、CI
-|   |-- fec-typescript-reviewer.md    # TS/JS 类型安全、异步、报告式评审
-|   |-- fec-performance-optimizer.md # 性能瓶颈分析与优化
-|   |-- fec-ui-checker.md            # UI 视觉问题与设计还原度评估
-|   |-- fec-figma-implementer.md     # 从设计稿精确实现 UI
-|   |-- fec-design-token-mapper.md   # 将设计变量映射到 Design Tokens
-|
-|-- skills/           # 工作流定义和领域知识
-|   |-- fec-code-review/    # 架构、类型、渲染、样式、无障碍
-|   |-- fec-security-review/     # XSS、CSRF、敏感数据、输入校验
-|   |-- fec-accessibility-check/     # WCAG 2.2、键盘、焦点和屏幕阅读器无障碍检查
-|   |-- fec-react-project-standard/  # React + TypeScript 项目规范
-|   |-- fec-vue3-project-standard/   # Vue 3 + TypeScript 项目规范
-|   |-- fec-implement-from-design/   # 基于设计工具、截图和视觉参考实现 UI
-|   |-- fec-validation-fix/            # lint、type-check、test、build 与修复
-|   |-- fec-performance-optimization/  # Core Web Vitals、包体、渲染、网络、内存
-|   |-- fec-source-driven-development/ # 官方来源、项目事实、版本敏感决策
-|   |-- fec-typescript-project-standard/   # TypeScript 配置、公开类型、声明文件、DTO 和泛型
-|   |-- fec-state-management/         # 状态归属、store 选型、URL/服务端/表单/本地边界
-|   |-- fec-tailwind-design-system/   # Tailwind token、组件变体、暗色模式和 class 治理
-|   |-- fec-responsive-layout/        # 移动优先布局、容器查询和触摸友好的响应式 UI
-|   |-- fec-dependency-upgrade/       # 依赖升级、lockfile 风险和 CVE 修复
-|   |-- fec-tdd-workflow/              # 测试先行的前端实现工作流
-|   |-- fec-refactor-clean/            # 安全清理死代码和未使用依赖
-|   |-- fec-doc-sync/                  # 公开文档和 metadata 同步
-|   |-- fec-legacy-web-standard/     # JS + jQuery + HTML 遗留项目规范
-|   |-- fec-legacy-to-modern-migration/ # jQuery/MPA 迁移到 React/Vue 的策略和工作流
-|   |-- fec-testing-strategy/          # 测试分层选择和覆盖矩阵
-|   |-- fec-e2e-testing/                # Playwright/Cypress E2E 测试规范
-|   |-- fec-nextjs-project-standard/    # Next.js 14+ App Router、SSR/SSG 规范
-|   |-- fec-nuxt-project-standard/      # Nuxt 3 SSR/SSG、composables 规范
-|   |-- fec-monorepo-project-standard/  # pnpm workspace、Turborepo、Nx 规范
-|   |-- fec-data-fetching/              # TanStack Query 和服务端状态工作流
-|   |-- fec-api-integration/            # 类型化 API client、鉴权刷新、上传、实时集成
-|   |-- fec-backend-requirements-handoff/ # 前后端 UI 数据与状态需求交接
-|   |-- fec-form-handling/              # React Hook Form + Zod 表单工作流
-|   |-- fec-route-protection/           # 鉴权路由和权限路由
-|   |-- fec-component-testing/          # RTL / Vue Test Utils 组件测试
-|   |-- fec-pwa-implementation/         # PWA manifest、service worker、离线能力
-|   |-- fec-web-workers/                # Worker 集成和后台计算
-|   |-- fec-canvas-threejs/             # Canvas、Three.js、React Three Fiber
-|   |-- fec-svg-animation/              # SVG 动效和 reduced-motion 降级
-|   |-- fec-browser-storage/            # localStorage/sessionStorage/IndexedDB/Cookies 选型与安全客户端持久化
-|   |-- fec-list-virtualization/        # react-window / TanStack Virtual 大列表窗口化与测量策略
-|   |-- fec-storybook-component-doc/    # Storybook 组件文档、addon、MDX、交互和视觉测试集成
-|   |-- fec-ui-design/                  # 产品语境 UI 方向、设计拨盘、媒体策略、视觉 QA
-|   |-- fec-image-generation/           # 图表/图片生成、编辑工作流、PNG 自检和修复循环
-|   |-- fec-drawio-studio/             # 可编辑 draw.io 技术图、形状检索、自动布局、代码结构图
-|   |-- fec-web-video-presentation/    # 可录屏的 16:9 步进网页视频演示
-|   |-- fec-motion-interaction/         # 场景化动效强度、页面转场、滚动动画、reduced motion
-|   |-- fec-vite-project-standard/      # Vite 配置、环境变量安全、HMR、代理、构建与 library mode
-|
-|-- commands/         # 快速执行的斜杠命令
-|   |-- fec-init.md     # /fec-init - 初始化项目模板
-|   |-- fec-review.md   # /fec-review - 代码评审
-|   |-- fec-scaffold.md # /fec-scaffold - 创建 page/feature/component
-|   |-- fec-plan.md     # /fec-plan - 前端变更前的实施规划
-|   |-- fec-tdd.md      # /fec-tdd - 测试驱动的前端实现
-|   |-- fec-debug.md    # /fec-debug - 诊断并修复前端问题
-|   |-- fec-refactor-clean.md # /fec-refactor-clean - 安全清理死代码
-|   |-- fec-doc-sync.md # /fec-doc-sync - 公开文档和 metadata 同步
-|
-|-- hooks/            # 事件驱动自动化
-|   |-- hooks.json     # PreToolUse、PostToolUse、Stop、Notification 等
-|
-|-- src/              # 发布运行时代码的 TypeScript 源码
-|   |-- hooks/         # 打包到 dist/hooks 的运行时 hook 脚本
-|   |-- security-check.ts      # 拦截危险命令
-|   |-- format-changed-file.ts # 自动执行 Prettier 格式化
-|   |-- run-tests.ts           # 会话结束时运行检查
-|   |-- session-start.ts       # 会话开始时检测框架
-|   |-- notify.ts              # 跨平台桌面通知
-|   |-- install/       # 安装器核心（CLI、交互向导、运行时转换器）
-|   |-- openclaw/      # OpenClaw 运行时 TypeScript 源码
-|
-|-- scripts/          # 仓库维护脚本源码，不发布到 npm runtime
-|
-|-- templates/        # 运行时专用项目模板
-|   |-- claude/        # CLAUDE.md 和 settings.json
-|   |-- codex/         # AGENTS.md 和 config.toml
-|   |-- openclaw/      # AGENTS.md 和 OPENCLAW-CONFIG.md
-|   |-- shared/rules/  # 20 个规则文件：vue、react、rendering patterns、responsive design、testing、source-driven development 等
-|
-|-- .mcp.json         # MCP server 配置（Figma、Figma Desktop、Sketch、MasterGo、Pixso、墨刀）
-└-- README.md
-```
-
-## 目录职责
-
-| 目录            | 职责                                                                               |
-| --------------- | ---------------------------------------------------------------------------------- |
-| `agents/`       | 专业子代理定义（Markdown + YAML frontmatter）                                      |
-| `bin/`          | CLI 入口（`frontend-craft.ts`）                                                    |
-| `commands/`     | 自定义斜杠命令（`fec-init`、`fec-review`、`fec-scaffold` 和工作流命令）            |
-| `docs/`         | 运行时安装文档和本地化 README                                                      |
-| `hooks/`        | Hook 配置（`hooks.json`）                                                          |
-| `scripts/`      | 仓库维护脚本源码（构建、打包、发布检查、metadata 同步），不包含在 npm 运行时输出中 |
-| `skills/`       | Skill 定义（`SKILL.md`、`metadata.json`）                                          |
-| `src/hooks/`    | 打包到 `dist/hooks/` 的运行时 hook 源码，供 Claude/Qoder 执行                      |
-| `src/install/`  | 安装器核心（CLI、交互向导、运行时转换器）                                          |
-| `src/openclaw/` | OpenClaw 运行时 TypeScript 源码                                                    |
-| `templates/`    | 运行时专用项目模板（Claude/Codex/OpenClaw 配置 + shared rules）                    |
-| `tests/`        | 测试套件（转换器测试、安装器测试）                                                 |
+# 项目结构
+
+`frontend-craft` 的详细目录布局。
+
+## 仓库布局
+
+```text
+frontend-craft/
+|-- .claude-plugin/   # Claude Code 插件与 marketplace 清单
+|   |-- plugin.json         # 插件元数据
+|   |-- marketplace.json    # Marketplace 目录元数据
+|
+|-- agents/           # 用于委托的专业子代理
+|   |-- fec-architect.md    # 页面拆分、组件架构、状态流
+|   |-- fec-code-reviewer.md # 前端专项代码评审（质量、安全、无障碍）
+|   |-- fec-security-reviewer.md # 前端攻击面：XSS、密钥、CSP、依赖
+|   |-- fec-test-planner.md # 测试策略、风险矩阵、覆盖规划
+|   |-- fec-debugger.md # 复杂构建/运行时/UI/API 问题诊断
+|   |-- fec-refactor-cleaner.md # 死代码和未使用依赖清理
+|   |-- fec-refactoring-expert.md # 保持行为的坏味道诊断、规划、执行与验证
+|   |-- fec-doc-updater.md # README/runtime 文档/能力表同步
+|   |-- fec-e2e-runner.md     # E2E 编写、执行、flaky 治理、产物、CI
+|   |-- fec-typescript-reviewer.md    # TS/JS 类型安全、异步、报告式评审
+|   |-- fec-performance-optimizer.md # 性能瓶颈分析与优化
+|   |-- fec-ui-checker.md            # UI 视觉问题与设计还原度评估
+|   |-- fec-figma-implementer.md     # 从设计稿精确实现 UI
+|   |-- fec-design-token-mapper.md   # 将设计变量映射到 Design Tokens
+|
+|-- skills/           # 工作流定义和领域知识
+|   |-- fec-code-review/    # 架构、类型、渲染、样式、无障碍
+|   |-- fec-security-review/     # XSS、CSRF、敏感数据、输入校验
+|   |-- fec-accessibility-check/     # WCAG 2.2、键盘、焦点和屏幕阅读器无障碍检查
+|   |-- fec-react-project-standard/  # React + TypeScript 项目规范
+|   |-- fec-vue3-project-standard/   # Vue 3 + TypeScript 项目规范
+|   |-- fec-implement-from-design/   # 基于设计工具、截图和视觉参考实现 UI
+|   |-- fec-validation-fix/            # lint、type-check、test、build 与修复
+|   |-- fec-performance-optimization/  # Core Web Vitals、包体、渲染、网络、内存
+|   |-- fec-source-driven-development/ # 官方来源、项目事实、版本敏感决策
+|   |-- fec-typescript-project-standard/   # TypeScript 配置、公开类型、声明文件、DTO 和泛型
+|   |-- fec-state-management/         # 状态归属、store 选型、URL/服务端/表单/本地边界
+|   |-- fec-tailwind-design-system/   # Tailwind token、组件变体、暗色模式和 class 治理
+|   |-- fec-responsive-layout/        # 移动优先布局、容器查询和触摸友好的响应式 UI
+|   |-- fec-dependency-upgrade/       # 依赖升级、lockfile 风险和 CVE 修复
+|   |-- fec-tdd-workflow/              # 测试先行的前端实现工作流
+|   |-- fec-refactor-clean/            # 安全清理死代码和未使用依赖
+|   |-- 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/    # 行为保持验证与证明等级
+|   |-- fec-doc-sync/                  # 公开文档和 metadata 同步
+|   |-- fec-legacy-web-standard/     # JS + jQuery + HTML 遗留项目规范
+|   |-- fec-legacy-to-modern-migration/ # jQuery/MPA 迁移到 React/Vue 的策略和工作流
+|   |-- fec-testing-strategy/          # 测试分层选择和覆盖矩阵
+|   |-- fec-e2e-testing/                # Playwright/Cypress E2E 测试规范
+|   |-- fec-debug-framework/            # 统一 5 步诊断框架：构建/运行时/UI/API 失败
+|   |-- fec-nextjs-project-standard/    # Next.js 14+ App Router、SSR/SSG 规范
+|   |-- fec-nuxt-project-standard/      # Nuxt 3 SSR/SSG、composables 规范
+|   |-- fec-monorepo-project-standard/  # pnpm workspace、Turborepo、Nx 规范
+|   |-- fec-data-fetching/              # TanStack Query 和服务端状态工作流
+|   |-- fec-api-integration/            # 类型化 API client、鉴权刷新、上传、实时集成
+|   |-- fec-backend-requirements-handoff/ # 前后端 UI 数据与状态需求交接
+|   |-- fec-form-handling/              # React Hook Form + Zod 表单工作流
+|   |-- fec-route-protection/           # 鉴权路由和权限路由
+|   |-- fec-component-testing/          # RTL / Vue Test Utils 组件测试
+|   |-- fec-pwa-implementation/         # PWA manifest、service worker、离线能力
+|   |-- fec-web-workers/                # Worker 集成和后台计算
+|   |-- fec-canvas-threejs/             # Canvas、Three.js、React Three Fiber
+|   |-- fec-svg-animation/              # SVG 动效和 reduced-motion 降级
+|   |-- fec-browser-storage/            # localStorage/sessionStorage/IndexedDB/Cookies 选型与安全客户端持久化
+|   |-- fec-list-virtualization/        # react-window / TanStack Virtual 大列表窗口化与测量策略
+|   |-- fec-storybook-component-doc/    # Storybook 组件文档、addon、MDX、交互和视觉测试集成
+|   |-- fec-ui-design/                  # 产品语境 UI 方向、设计拨盘、媒体策略、视觉 QA
+|   |-- fec-image-generation/           # 图表/图片生成、编辑工作流、PNG 自检和修复循环
+|   |-- fec-drawio-studio/             # 可编辑 draw.io 技术图、形状检索、自动布局、代码结构图
+|   |-- fec-web-video-presentation/    # 可录屏的 16:9 步进网页视频演示
+|   |-- fec-motion-interaction/         # 场景化动效强度、页面转场、滚动动画、reduced motion
+|   |-- fec-vite-project-standard/      # Vite 配置、环境变量安全、HMR、代理、构建与 library mode
+|   |-- fec-alchemy/                    # 项目吸收工作流——抽取参考系统能力并原创化重写
+|
+|-- commands/         # 快速执行的斜杠命令
+|   |-- fec-init.md     # /fec-init - 初始化项目模板
+|   |-- fec-review.md   # /fec-review - 默认全项目；指定范围或明确改动审核
+|   |-- fec-scaffold.md # /fec-scaffold - 创建 page/feature/component
+|   |-- fec-plan.md     # /fec-plan - 前端变更前的实施规划
+|   |-- fec-tdd.md      # /fec-tdd - 测试驱动的前端实现
+|   |-- fec-debug.md    # /fec-debug - 诊断并修复前端问题
+|   |-- fec-refactor-clean.md # /fec-refactor-clean - 安全清理死代码
+|   |-- fec-smell.md          # /fec-smell - 只读代码坏味道诊断
+|   |-- fec-refactor-plan.md  # /fec-refactor-plan - 只读小步重构计划
+|   |-- fec-refactor.md       # /fec-refactor - 受控的保持行为重构执行
+|   |-- fec-doc-sync.md # /fec-doc-sync - 公开文档和 metadata 同步
+|
+|-- hooks/            # 事件驱动自动化
+|   |-- hooks.json     # PreToolUse、PostToolUse、Stop、Notification 等
+|
+|-- src/              # 发布运行时代码的 TypeScript 源码
+|   |-- hooks/         # 打包到 dist/hooks 的运行时 hook 脚本
+|   |-- security-check.ts      # 拦截危险命令
+|   |-- format-changed-file.ts # 自动执行 Prettier 格式化
+|   |-- run-tests.ts           # 会话结束时运行检查
+|   |-- session-start.ts       # 会话开始时检测框架
+|   |-- notify.ts              # 跨平台桌面通知
+|   |-- install/       # 安装器核心（CLI、交互向导、运行时转换器）
+|   |-- openclaw/      # OpenClaw 运行时 TypeScript 源码
+|
+|-- scripts/          # 仓库维护脚本源码，不发布到 npm runtime
+|
+|-- templates/        # 运行时专用项目模板
+|   |-- claude/        # CLAUDE.md 和 settings.json
+|   |-- codex/         # AGENTS.md 和 config.toml
+|   |-- cursor/        # Cursor 运行时项目存根
+|   |-- gemini/        # Gemini CLI 运行时项目存根
+|   |-- openclaw/      # AGENTS.md 和 OPENCLAW-CONFIG.md
+|   |-- windsurf/      # Windsurf 运行时项目存根
+|   |-- shared/rules/  # 20 个规则文件：vue、react、rendering patterns、responsive design、testing、source-driven development 等
+|
+|-- .mcp.json         # MCP server 配置（Figma、Figma Desktop、Sketch、MasterGo、Pixso、墨刀）
+└-- README.md
+```
+
+## 目录职责
+
+| 目录            | 职责                                                                               |
+| --------------- | ---------------------------------------------------------------------------------- |
+| `agents/`       | 专业子代理定义（Markdown + YAML frontmatter）                                      |
+| `bin/`          | CLI 入口（`frontend-craft.ts`）                                                    |
+| `commands/`     | 自定义斜杠命令（`fec-init`、`fec-review`、`fec-scaffold` 和工作流命令）            |
+| `docs/`         | 运行时安装文档和本地化 README                                                      |
+| `hooks/`        | Hook 配置（`hooks.json`）                                                          |
+| `scripts/`      | 仓库维护脚本源码（构建、打包、发布检查、metadata 同步），不包含在 npm 运行时输出中 |
+| `skills/`       | Skill 定义（`SKILL.md`、`metadata.json`）                                          |
+| `src/hooks/`    | 打包到 `dist/hooks/` 的运行时 hook 源码，供 Claude/Qoder 执行                      |
+| `src/install/`  | 安装器核心（CLI、交互向导、运行时转换器）                                          |
+| `src/openclaw/` | OpenClaw 运行时 TypeScript 源码                                                    |
+| `templates/`    | 运行时专用项目模板（Claude/Codex/Cursor/Gemini/OpenClaw/Windsurf 配置 + shared rules） |
+| `tests/`        | 测试套件（转换器测试、安装器测试）                                                 |
+
+
+技术图质量工作流：`fec-image-generation` 的标准时序/流程图优先本地 Mermaid，架构图复用 draw.io 工作流，工具缺失时使用 JSON/HTML。导出 PNG 时生成实际测量且与缩放一致的 manifest，再运行 QA 并检查最终 PNG；保留完整文字、显式布局与关系，最多自动修复两轮，未解决问题需明确报告。可复现样例位于 `skills/fec-image-generation/assets/quality-examples/`。
+
+[审核范围与技术图交付](review-and-diagram-workflows.md) — 范围规则、工具前提、导出命令与 QA 边界。

package/docs/zh-CN/review-and-diagram-workflows.md

@@ -0,0 +1,39 @@
+# 审核范围与技术图交付
+
+以下约定适用于各运行时安装的能力。通过自然语言选择审核模式，不使用安装器 CLI 参数选择模式。
+
+## 审核范围
+
+`fec-code-reviewer`、`fec-typescript-reviewer`、`fec-security-reviewer`、`fec-code-review`、`fec-security-review` 与 `/fec-review` 采用相同范围规则：
+
+| 请求 | 审核范围 | 报告结论 |
+| --- | --- | --- |
+| 未指定范围，包括单独调用 `/fec-review` | 全项目，即使存在 Git 改动 | 风险评估 |
+| 指定文件或目录 | 范围内全部现有代码，包括未改动代码 | 指定范围风险评估 |
+| 明确要求最近改动、PR 或提交 | 指定差异及必要上下文 | 合并建议 |
+
+全项目和指定范围审核不要求 Git 差异。明确增量审核但没有改动时，说明情况，不自动扩大范围。审核者保留前端、TypeScript 或安全专项职责，不宣称完成后端安全专项审核。
+
+全项目先建立自有前端代码、相关测试、配置和依赖声明清单，再按模块分批审核。默认排除依赖、生成文件、构建产物、缓存与第三方代码。报告记录模式、目标范围、已审核范围、排除项、未覆盖模块及验证结果。未完成时标记部分完成，合并同根因发现。读取调用方或运行静态检查不计为相应文件的人工审核。默认只输出报告，明确要求修复时才修改代码。
+
+示例：「审核整个项目」「审核 `src/features/` 的全部代码」「审核 `src/components/Button.tsx`」「仅审核最近改动」。修改后的自动审核必须明确传入本次改动范围。
+
+## 技术图
+
+时序图和流程图通过 `fec-image-generation` 优先使用本地 Mermaid；可编辑架构图使用 `fec-drawio-studio`。工具缺失时使用 JSON/HTML 渲染器。需要准确结构的技术关系与标签应保存在可编辑源文件中。
+
+Mermaid 适配器仅使用已安装 CLI，不自动下载依赖。PNG 导出需要本地 Chromium 浏览器，可通过 `FEC_BROWSER_PATH` 指定可执行文件。缺少工具时明确报告，不宣称导出成功。
+
+JSON/HTML 路线先渲染源文件，导出 PNG 与同比例的浏览器实测 manifest，再运行 QA 并检查最终图片：
+
+```bash
+node skills/fec-image-generation/scripts/tech-diagram-render.mjs --input skills/fec-image-generation/assets/quality-examples/workflow.json --type workflow --output workflow.html --manifest workflow.layout.json
+node skills/fec-image-generation/scripts/export-diagram.mjs --input workflow.html --format png --output workflow.png --theme light --scale 2 --manifest workflow.layout.json --output-manifest workflow.actual.json
+node skills/fec-image-generation/scripts/png-qa.mjs --png workflow.png --manifest workflow.actual.json --format json
+```
+
+保留完整 Unicode 标签、显式几何布局、连线方向、时序顺序与自调用；独立 SVG 应包含自身样式。几何 QA 和浏览器测量辅助视觉检查，不证明语义正确，也不等同于完成人工视觉审核。缺少测量或仅部分覆盖时必须说明。最多自动修复源文件两轮，之后报告未解决缺陷。
+
+交付可编辑源文件、请求的导出文件和 QA/覆盖结果。参见[可复现样例](../../localized/zh-CN/skills/fec-image-generation/assets/quality-examples/README.md)、[图表工作流](../../localized/zh-CN/skills/fec-image-generation/references/diagram-workflows.md)及 [PNG QA](../../localized/zh-CN/skills/fec-image-generation/references/png-qa-autofix.md)。
+
+[English](../review-and-diagram-workflows.md)