@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/docs/zh-CN/common-migration.md

@@ -0,0 +1,57 @@
+# frontend-craft3.0公共能力迁移
+
+当前精确公共依赖为`@bovinphang/craft-common@2.0.0`，正式版本号已准备，尚未发布。frontend3.0.0与backend1.0.0继续未发布且版本号不变。路径、规划会话、所有权、锁和可恢复事务复用common；产品保留内容转换与自身CLI/原生渠道策略。
+
+3.0交付53个前端和21个公共入口，共74项。公共1.0.1的事务恢复修复保留在2.0.0中；1.x或开发快照不能与2.0.0混用。先用各旧产品CLI退出全部旧公共引用并处理保留编辑，再安装匹配产品；不强制覆盖共享资源。公开安装须等待common及相应产品实际发布与源策略允许。
+
+| 原入口 | 3.0 用法 |
+| --- | --- |
+| fec-drawio-studio | 改用 cc-drawio-studio |
+| fec-source-driven-development | 改用 cc-source-driven-development；前端领域规则文件仍保留 fec 命名 |
+| fec-image-generation | 技术图表改用 cc-technical-diagrams；UI/产品视觉生成和编辑仍使用原入口 |
+| fec-doc-sync | 前端文档同步仍使用原入口；跨栈方法使用 cc-doc-sync-core |
+| fec-debug-framework | 前端诊断仍使用原入口；通用诊断方法使用 cc-debug-methodology |
+| fec-refactoring | 前端重构及其子系统保留；通用行为保持方法使用 cc-refactoring-core |
+| fec-tdd-workflow | 前端测试选型保留；通用红绿重构方法使用 cc-tdd-methodology |
+
+先只读检查当前项目及所选 Runtime 的本地安装：
+
+```sh
+fec runtime check-migration codex --local
+fec runtime check-migration codex --local --json
+fec runtime check-migration codex --global --json
+```
+
+省略 Runtime 时检查全部已支持 Runtime。退出码：0 无待处理项；1 有旧引用或旧安装；2 参数、读取或清单错误。检查不重写项目文件，不输出匹配行的完整内容。敏感文件、依赖、构建产物、二进制和符号链接不扫描；大于 2 MiB 的文本跳过。全局模式只检查托管文件和旧公共 Skill 目录，不递归扫描整个用户主目录。
+
+文本扫描仅提示候选项：迁移表、历史记录、同名领域规则文件可能合理包含旧名称，需人工甄别。保留的前端入口不会被一概要求改名；拆分建议根据同一行的任务上下文给出，不替代人工判断。
+
+处理引用后安装或更新：
+
+```sh
+fec runtime install codex --local
+fec runtime update codex --local
+```
+
+安装前检查旧公共 Skill。由旧 frontend-craft 清单托管且逐文件哈希一致的入口，随事务退役，再部署新入口；修改过、未知来源、带符号链接或无法确认所有权的旧目录会阻断迁移。检查报告不会替你删除这些文件。先备份并审阅自定义内容，再手动迁出、整合或移除旧入口后重试；不要直接清空整个 Runtime 目录。
+
+同一实际 Skill 目录中的公共版本、内容摘要和语言必须一致。发现不兼容消费者会在写入前失败；不要用后安装的产品覆盖现有公共内容。卸载前端会保留其他消费者的公共资源；部分卸载留下修改过的前端文件时，也会保留公共依赖引用。最后消费者退出才清理未修改的公共文件，用户修改及所有权记录会保留。
+
+事务中断后，用相同产品、安装范围和目录重跑。系统会恢复可确认的本地事务；无法确认锁或路径边界时保留现场并报错，不盲目删除锁文件。
+
+同一产品清单路径不能切换 Runtime、local/global 作用域或公共目标；需要切换时先卸载原安装。全局旧配置目录迁入也先检查旧公共文件，用户修改会阻断，原目录保留。事务恢复针对本地主机进程中断，不承诺断电或跨主机共享文件系统协调。
+
+CLI 共享安装已纳入双消费者验收。Claude/OpenClaw 原生插件渠道交付完整公共快照，本期不承诺两个原生产品同时启用时的去重。公开 registry 的公共包发布是独立发布步骤，本次开发不自动执行发布。
+
+## 2026-11-08 coordinated2.0.0 upgrade / 当前协调升级
+
+Current source: common2.0.0 (release prepared, unpublished), frontend3.0.0/backend1.0.0 (unchanged, unreleased). 2.0.0同样要求版本、语言和摘要一致；不自动升级另一个产品。
+
+1. Back up user edits and inspect local/global/runtime identity. 备份修改，确认安装范围。
+2. With each OLD product CLI, uninstall its runtime resources and resolve preserved edits until both old common consumers exit. 使用各旧 CLI 退出旧公共引用，不用新 CLI 越权接管。
+3. Install both matching product builds using verified artifacts; public clean install must wait for common publication. 安装新匹配产品前执行 runtime check-migration。
+4. Managed unchanged legacy language entries retire in the same transaction as new cc deployment. Unknown files, edits, links or invalid ownership block the whole install; dry-run writes nothing. 原领域入口不建立假别名。
+
+Rename: fec-typescript-project-standard → cc-typescript-project-standard; bec-{rust,go,java,python,c,cpp}-project-standard → cc-*-project-standard; bec-{rust-async,go-concurrency,python-async,java-runtime,native-memory-safety} → cc-* equivalents. Frontend retains its earlier drawio/source-driven rename policy.
+
+Checks return 0 (nothing found), 1 (reviewable references/owned retired entries), 2 (invalid arguments, scan failure or retirement conflict). Reports show paths, IDs and line numbers, never full source lines. No-Skill hosts receive reference material rather than a fabricated native Skill alias. 双原生产品去重仍不在保证范围。

package/docs/zh-CN/example-prompts.md

@@ -23,10 +23,14 @@
 
 | 场景                | 提示词                                                                                                                           | 适用能力                                                    | 预期产物                                               | 补充说明                                     |
 | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------- |
+| 默认全项目审核 | 「`/fec-review`」 | cmd: `/fec-review` | 全项目风险评估，记录覆盖范围、排除项及剩余模块。 | 即使存在 Git 改动也默认全项目审核。 |
 | 评审最近改动        | 「合并前请评审我最近的改动。重点看架构、类型安全、渲染行为、样式、无障碍和缺失测试；先列问题。」                                 | skill: `fec-code-review` · agent: `fec-code-reviewer` · cmd: `/fec-review`       | 按严重级别排序的评审，带文件引用和测试缺口。           | 可补充分支名或 diff 范围。                   |
-| PR 合并准备         | 「请把 `src/features/checkout/` 当作 PR 评审，指出阻塞项、风险假设，以及合并前必须补的测试。」                                   | agent: `fec-code-reviewer`                                         | 合并准备度判断和结构化报告。                           | 若运行时可访问 PR，可贴 PR 链接。            |
+| PR 合并准备 | 「请评审这个 PR 的改动，指出阻塞项、风险假设，以及合并前必须补的测试。」 | agent: `fec-code-reviewer` | 合并准备度判断和结构化报告。 | 提供 PR 链接或明确差异范围。 |
+| 指定文件审核 | 「审核 `src/components/Button.tsx`，包括未改动代码；只报告，不修复。」 | cmd: `/fec-review` · skill: `fec-code-review` | 文件风险评估及覆盖范围。 | 不要求 Git 差异。 |
+| 指定目录审核 | 「审核 `src/features/checkout/` 的全部现有前端代码，包括未改动代码。」 | agent: `fec-code-reviewer` | 目录风险评估及未覆盖清单。 | 明确范围优先于默认全项目模式。 |
+| 全项目审核 | 「审核整个项目的自有前端代码、相关测试、配置和依赖声明。先建立清单，按模块审核，报告排除项和未覆盖范围；未完成时标记部分完成，只报告不修复。」 | skill: `fec-code-review` · cmd: `/fec-review` | 全项目风险评估及覆盖清单。 | 无改动也可执行；不替代后端审核。 |
 | TypeScript 专项评审 | 「请审计本次改动中的 `.ts` 和 `.tsx`：不安全类型、异步问题、过宽接口、陈旧派生状态、React/TypeScript 惯用法。」                  | agent: `fec-typescript-reviewer`                                   | TypeScript 专项问题清单，通常只报告不修改。            | JS/TS 改动占主要部分时最适合。               |
-| 类型契约评审        | 「请评审 `src/features/billing/` 的 API DTO、组件 props、泛型工具和类型守卫，找出不安全断言、过宽类型和缺失的运行时收窄。」      | skill: `fec-typescript-project-standard` · agent: `fec-typescript-reviewer`     | 类型边界问题、更安全的建模建议和类型测试建议。         | 适合 SDK、设计系统或 API 密集改动。          |
+| 类型契约评审        | 「请评审 `src/features/billing/` 的 API DTO、组件 props、泛型工具和类型守卫，找出不安全断言、过宽类型和缺失的运行时收窄。」      | skill: `cc-typescript-project-standard` · agent: `fec-typescript-reviewer`     | 类型边界问题、更安全的建模建议和类型测试建议。         | 适合 SDK、设计系统或 API 密集改动。          |
 | 安全审查            | 「请审计 `src/lib/auth.ts`、API client 和所有渲染用户 HTML 的代码，关注 XSS、token 泄露、不安全存储、CSRF 假设和危险 DOM API。」 | skill: `fec-security-review` · agent: `fec-security-reviewer`              | 按严重程度排序的安全问题和修复建议。                   | 补充鉴权模型和存储约束。                     |
 | 无障碍检查          | 「请检查 `src/components/ConfirmDialog.tsx` 的焦点陷阱、键盘流程、标签、ARIA、读屏行为、触摸目标和 WCAG 2.2 AA 问题。」          | skill: `fec-accessibility-check`                                   | 无障碍问题和可落地修改建议。                           | 视觉焦点问题最好附截图。                     |
 | 性能审查            | 「请基于证据分析 dashboard 性能：Core Web Vitals、包体积、渲染热点、数据瀑布流、内存泄漏和合理性能预算。」                       | skill: `fec-performance-optimization` · agent: `fec-performance-optimizer` | 性能报告，包含基线证据、优先级、验证命令和针对性修复。 | 有 Lighthouse、trace、profile 或慢路径更好。 |
@@ -39,7 +43,7 @@
 | 功能规划     | 「先不要写代码，请规划账号账单功能：路由结构、组件边界、数据流、状态归属、校验流程和上线风险。」                         | cmd: `/fec-plan` · agent: `fec-architect`                            | 架构方案和实施计划。                                         | 补充验收标准和限制。              |
 | 拆分复杂页面 | 「请先在方案层面重构 `src/pages/Dashboard.tsx`：组件边界、hooks、状态归属和安全迁移步骤。」                              | agent: `fec-architect` · skill: `fec-refactor-clean`                   | 重构计划和风险控制。                                         | 如果只要计划，请明确不要改代码。  |
 | 测试策略     | 「针对 checkout 重写，请把风险映射到静态检查、单元测试、组件测试、E2E、视觉检查、无障碍和安全覆盖。」                    | cmd: `/fec-plan` · skill: `fec-testing-strategy` · agent: `fec-test-planner` | 测试矩阵和优先级。                                           | 大改动前很适合。                  |
-| 来源驱动决策 | 「修改 Next.js 缓存方案前，请先核对当前项目代码和官方文档，总结版本假设、推荐模式、迁移影响和需要补的测试。」            | skill: `fec-source-driven-development`                         | 基于来源的决策摘要，包含项目事实、官方依据、假设和验证步骤。 | 适合可能随版本变化的框架/库行为。 |
+| 来源驱动决策 | 「修改 Next.js 缓存方案前，请先核对当前项目代码和官方文档，总结版本假设、推荐模式、迁移影响和需要补的测试。」            | skill: `cc-source-driven-development`                         | 基于来源的决策摘要，包含项目事实、官方依据、假设和验证步骤。 | 适合可能随版本变化的框架/库行为。 |
 | 遗留迁移     | 「我们有一个 jQuery 多页应用在 `public/js/legacy/`。请制定分阶段迁移到 React + TypeScript 的方案，同时不阻塞日常需求。」 | skill: `fec-legacy-to-modern-migration`                        | 迁移计划、风险、里程碑和兼容策略。                           | 补充发布节奏和遗留约束。          |
 
 ## 功能实现
@@ -51,9 +55,9 @@
 | Next.js App Router | 「请评审并改进 `app/(dashboard)/reports/page.tsx`：App Router 数据获取、metadata、loading/error 状态、server/client 边界和 actions。」      | skill: `fec-nextjs-project-standard`                                | Next.js 专项问题或代码修改。                       | 补充路由分组行为。                    |
 | Nuxt 3 页面        | 「请在 Nuxt 3 中构建 admin reports 页面，处理 SSR 行为、`useFetch`/composables、中间件和类型化 server routes。」                            | skill: `fec-nuxt-project-standard`                                  | 符合 Nuxt 约定的实现。                             | 说明该路由是 SSR、SSG 还是 SPA。      |
 | Vite 配置          | 「请审计 `vite.config.ts`：HMR、环境变量暴露、开发代理、构建产物、依赖预构建和插件顺序。」                                                  | skill: `fec-vite-project-standard`                                  | Vite 配置问题和安全修改。                          | 补充构建或 dev server 症状。          |
-| 官方文档核对       | 「请确认当前 Vite 版本是否还需要这个依赖预构建 workaround。先看项目配置和官方文档，再建议是否删除。」                                       | skill: `fec-source-driven-development` · skill: `fec-vite-project-standard` | 版本感知的建议，包含来源说明、回退和验证计划。     | 适合删除兼容代码前使用。              |
+| 官方文档核对       | 「请确认当前 Vite 版本是否还需要这个依赖预构建 workaround。先看项目配置和官方文档，再建议是否删除。」                                       | skill: `cc-source-driven-development` · skill: `fec-vite-project-standard` | 版本感知的建议，包含来源说明、回退和验证计划。     | 适合删除兼容代码前使用。              |
 | Monorepo 边界      | 「请检查 `apps/web` 和 `packages/ui` 的包边界、workspace 依赖、构建脚本和 Turborepo/Nx 任务图。」                                           | skill: `fec-monorepo-project-standard`                              | 边界与任务编排评审。                               | 补充包管理器和 workspace 文件。       |
-| 依赖升级           | 「为这个仓库规划 Vite 和 Storybook 升级：查 release notes，识别 breaking changes，评审 lockfile 与 peer dependency 风险，并提出验证矩阵。」 | skill: `fec-dependency-upgrade` · skill: `fec-source-driven-development`    | 升级批次、来源依据、影响范围、验证命令和回滚说明。 | 大版本升级不要和无关重构混在一起。    |
+| 依赖升级           | 「为这个仓库规划 Vite 和 Storybook 升级：查 release notes，识别 breaking changes，评审 lockfile 与 peer dependency 风险，并提出验证矩阵。」 | skill: `fec-dependency-upgrade` · skill: `cc-source-driven-development`    | 升级批次、来源依据、影响范围、验证命令和回滚说明。 | 大版本升级不要和无关重构混在一起。    |
 | 服务端状态         | 「请评审 `src/queries/useReports.ts`：query key、缓存时间、失效策略、乐观更新、错误状态和 suspense/loading 行为。」                         | skill: `fec-data-fetching`                                          | TanStack Query / 服务端状态建议或实现。            | 补充 API 变化频率和 UX 预期。         |
 | 状态归属           | 「请审计 dashboard 的状态归属：哪些属于 URL 参数、TanStack Query、本地组件 state、浏览器持久化或全局 store，并给出安全迁移方案。」          | skill: `fec-state-management`                                       | 状态清单、归属决策、store 边界和验证步骤。         | 适合 store 重构或清理重复状态前使用。 |
 | 后端需求交接       | 「请为订单详情页写一份前端到后端的需求交接：需要展示的数据、用户动作、UI 状态、权限规则、不确定点和后端问题清单。」                       | skill: `fec-backend-requirements-handoff`                           | 面向后端的需求说明，聚焦 UI 需要什么和待确认问题。 | 后端拥有实现方案、接口形状前使用。    |
@@ -67,7 +71,7 @@
 | Canvas / Three.js  | 「请添加 WebGL shader 背景或 Three.js 产品展示器：响应式尺寸、WebGL2/shader 错误检查、可访问降级、性能保护，并验证 canvas 确实渲染。」      | skill: `fec-canvas-threejs`                                         | 3D/canvas/shader 实现和视觉验证。                  | 补充资源、shader 要求和交互约束。     |
 | SVG 动效           | 「请用项目已有动画库为 hero SVG 添加微交互，并为 reduced-motion 用户提供静态降级。」                                                        | skill: `fec-svg-animation`                                          | SVG 动效和降级行为。                               | 补充动效约束和目标浏览器。            |
 | 跨能力吸收         | 「请把这个参考仓库的测试策略吸收到本项目：保留能用的部分，按本仓库约定重写，并写 1 页可复用模式清单和迁移路径的方案。」                  | skill: `fec-alchemy`                                                | 可复用模式清单、改造建议和迁移路径。              | 附上参考仓库 URL 或本地路径；说明技术栈和项目约束。        |
-| 可编辑技术图       | 「请为 auth 流程生成可编辑的 draw.io 架构图：产出 `.drawio` 源、跑 lint、给出 viewer URL、导出 PNG。复用现有 shape 和 brand symbol 查找。」 | skill: `fec-drawio-studio`                                          | `.drawio` 源、lint 报告、viewer/editor URL、PNG 导出。 | 数据驻留敏感时请改用自托管 base URL 或本地 CLI 导出。      |
+| 可编辑技术图       | 「请为 auth 流程生成可编辑的 draw.io 架构图：产出 `.drawio` 源、跑 lint、给出 viewer URL、导出 PNG。复用现有 shape 和 brand symbol 查找。」 | skill: `cc-drawio-studio`                                          | `.drawio` 源、lint 报告、viewer/editor URL、PNG 导出。 | 数据驻留敏感时请改用自托管 base URL 或本地 CLI 导出。      |
 
 ## UI 与设计
 
@@ -75,10 +79,10 @@
 | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |
 | 设计稿实现            | 「请按 Figma 节点 `123:456` 实现 UI。复用现有 design token 和组件，匹配间距与响应式状态，并说明假设。」                                                  | skill: `fec-implement-from-design` · agent: `fec-figma-implementer` | UI 代码和设计实现说明/报告。                         | 配好 MCP 凭据效果最好。                              |
 | 截图到 UI 打磨        | 「请打磨这个 dashboard，让它像生产级 SaaS 工具：信息密度、层级、空/加载/错误状态、响应式布局和交互状态。」                                               | skill: `fec-ui-design`                                      | UI 改进和视觉 QA 说明。                              | 可提供截图或本地 URL。                               |
-| 图片与图表生成        | 「请生成可编辑技术架构图和 PNG，然后自检重叠、标签截断、连线堆叠，并最多修复两轮源文件。」                                                          | skill: `fec-image-generation` · skill: `fec-ui-design`              | 可编辑源、导出 PNG、QA 报告和修复说明。               | 渲染器能暴露布局框时附带 manifest 坐标。             |
-| 系统蓝图图表 | 「请为我们的 checkout 平台创建适合演示的系统蓝图。保留 JSON 和生成的 HTML 作为源文件，然后导出 SVG 和 PNG 交付物。」 | skill: `fec-image-generation` | JSON/HTML 源文件、导出的 SVG/PNG，以及源文件/资产交接说明。 | 适合架构、部署拓扑、agent runtime、memory 和 before/after 系统图。 |
-| 流程工作流图 | 「请把这个审批和自动化流程转成清晰的流程工作流图：包含 lanes、顺序步骤、决策、异常路径、循环回退和 waypoint 路由连线。」 | skill: `fec-image-generation` | Workflow JSON/HTML 源文件、导出图片，以及 lanes、nodes、edges、waypoints 说明。 | 当归属和分支比精确基础设施拓扑更重要时使用。 |
-| 交互式实时图 | 「请为 onboarding flow 启动本地交互式图表会话。逐步添加节点和连线，让我可以拖拽、改名、删除、缩放，最后导出交付物。」 | skill: `fec-image-generation` | 浏览器实时预览，以及保存的 JSON/SVG/PNG，或切换到 HTML/draw.io 源文件交付。 | 适合协作草图；需要长期维护源文件时切换到 HTML 技术图或 draw.io。 |
+| 图片与图表生成        | 「请生成可编辑技术架构图和 PNG，然后自检重叠、标签截断、连线堆叠，并最多修复两轮源文件。」                                                          | skill: `cc-technical-diagrams` · skill: `fec-ui-design`              | 可编辑源、导出 PNG、QA 报告和修复说明。               | 渲染器能暴露布局框时附带 manifest 坐标。             |
+| 系统蓝图图表 | 「请为我们的 checkout 平台创建适合演示的系统蓝图。保留 JSON 和生成的 HTML 作为源文件，然后导出 SVG 和 PNG 交付物。」 | skill: `cc-technical-diagrams` | JSON/HTML 源文件、导出的 SVG/PNG，以及源文件/资产交接说明。 | 适合架构、部署拓扑、agent runtime、memory 和 before/after 系统图。 |
+| 流程工作流图 | 「请把这个审批和自动化流程转成清晰的流程工作流图：包含 lanes、顺序步骤、决策、异常路径、循环回退和 waypoint 路由连线。」 | skill: `cc-technical-diagrams` | Workflow JSON/HTML 源文件、导出图片，以及 lanes、nodes、edges、waypoints 说明。 | 当归属和分支比精确基础设施拓扑更重要时使用。 |
+| 交互式实时图 | 「请为 onboarding flow 启动本地交互式图表会话。逐步添加节点和连线，让我可以拖拽、改名、删除、缩放，最后导出交付物。」 | skill: `cc-technical-diagrams` | 浏览器实时预览，以及保存的 JSON/SVG/PNG，或切换到 HTML/draw.io 源文件交付。 | 适合协作草图；需要长期维护源文件时切换到 HTML 技术图或 draw.io。 |
 | 网页视频演示 | 「把这篇文章转成可录屏的 16:9 网页视频演示：生成口播稿和 outline，创建 Vite/React 舞台，并定义章节 step 方便录屏。」 | skill: `fec-web-video-presentation` · skill: `fec-ui-design` | 口播稿/outline、步进演示脚手架、主题说明和录屏清单。 | 适合技术分享、课程、产品 demo 和口播讲解。 |
 | 响应式布局            | 「修复这个后台表格在 375px、768px、1440px 下的问题：决定移动端列优先级、容器查询、触摸目标、安全区域和溢出规则。」                                       | skill: `fec-responsive-layout` · agent: `fec-ui-checker`            | 响应式策略、布局修改、视口检查和剩余风险。           | 最好提供截图或本地路由。                             |
 | Tailwind 设计系统     | 「把这些 Tailwind 组件重构成语义 token 和 variants：theme 扩展、暗色模式、class 组合、动态 class 安全和 Storybook 状态覆盖。」                           | skill: `fec-tailwind-design-system` · skill: `fec-ui-design`        | token/variant 方案或实现、class 治理和暗色模式检查。 | 适合共享 UI 包变复杂前使用。                         |
@@ -105,6 +109,14 @@
 | E2E 冒烟测试   | 「请为登录和 checkout 添加 Playwright 冒烟测试。使用 Page Object、稳定选择器、CI 友好的重试，并在失败时保留 trace。」 | skill: `fec-e2e-testing` · agent: `fec-e2e-runner` | E2E 测试、运行说明和摘要报告。 | 补充测试账号或 mock 策略。      |
 | flaky E2E 排查 | 「checkout E2E 在 CI 中不稳定。请分析 timing、网络、存储和选择器问题，然后稳定它，不要隐藏真实失败。」                | skill: `fec-e2e-testing` · agent: `fec-e2e-runner` | 根因分析和针对性修复。         | 提供 CI 日志或 trace。          |
 
+## 重构
+
+| 场景 | 提示词 | 适用能力 | 预期产物 | 补充说明 |
+| --- | --- | --- | --- | --- |
+| 只诊断坏味道 | 「对 `src/features/compose/` 使用 `/fec-smell`：给出证据、置信度、误判检查和候选手法，先不要修改业务代码。」 | cmd: `/fec-smell` · skill: `fec-code-smells` | 按优先级排序的坏味道报告。 | 适合先判断是否值得重构。 |
+| 只做重构计划 | 「使用 `/fec-refactor-plan`，把当前写信模块的坏味道整理成有顺序的小步计划，写明风险、差异预算、验证和回滚边界，保持行为不变。」 | cmd: `/fec-refactor-plan` · skill: `fec-refactoring` | 重构计划。 | 只规划，不改源码。 |
+| 保持行为执行 | 「使用 `/fec-refactor` 重构这个同时处理校验、请求和状态更新的函数。保持可观察行为不变，每次只做一个主要变换，每步验证；出现回归先回滚当前步骤。」 | cmd: `/fec-refactor` · agent: `fec-refactoring-expert` | 已验证的重构及报告。 | 纯重构遵循 GREEN → REFACTOR → GREEN。 |
+
 ## 调试
 
 | 场景               | 提示词                                                                                                                                      | 适用能力                              | 预期产物                                            | 补充说明                                          |
@@ -120,7 +132,7 @@
 | 清理死代码   | 「请查找并安全移除未使用导出、死路由、过期样式和未使用依赖。保持 public API，并写报告。」                                 | cmd: `/fec-refactor-clean` · skill: `fec-refactor-clean` · agent: `fec-refactor-cleaner`       | 清理计划/变更和报告。                        | 发布前很适合。                     |
 | 文档同步     | 「请更新 README 和 docs，让安装步骤、脚本、环境变量、API 路由、UI 路由和部署说明与当前前端代码和配置一致。」             | cmd: `/fec-doc-sync` · skill: `fec-doc-sync` · agent: `fec-doc-updater`                        | 同步后的文档和验证说明。                     | 不要把临时报告复制进公开文档。     |
 | 能力文档同步 | 「这个仓库发布 skills 和 commands。请同步能力表、metadata、runtime docs 和 package 文件，使其匹配已安装内容。」          | cmd: `/fec-doc-sync` · skill: `fec-doc-sync` · agent: `fec-doc-updater`                        | 基于已安装文件的分发文档。                   | 用于 skill/agent/command 仓库。     |
-| 来源驱动升级 | 「请规划 React Router/TanStack Query/Vite 的安全升级。核对官方迁移说明、当前项目用法、破坏性变更，并给出验证步骤。」      | skill: `fec-dependency-upgrade` · skill: `fec-source-driven-development` · cmd: `/fec-doc-sync` | 升级决策说明、影响文件、迁移风险和验证清单。 | 如果公开指南变化，再配合文档同步。 |
+| 来源驱动升级 | 「请规划 React Router/TanStack Query/Vite 的安全升级。核对官方迁移说明、当前项目用法、破坏性变更，并给出验证步骤。」      | skill: `fec-dependency-upgrade` · skill: `cc-source-driven-development` · cmd: `/fec-doc-sync` | 升级决策说明、影响文件、迁移风险和验证清单。 | 如果公开指南变化，再配合文档同步。 |
 | 遗留项目维护 | 「请改进 `public/js/legacy/cart.js`，保持当前 jQuery/MPA 技术栈，降低风险、改善结构，但暂时不要重写成 React。」           | skill: `fec-legacy-web-standard`                                                 | 安全的遗留维护变更或建议。                   | 补充浏览器兼容限制。               |
 
 ## 高级用户提示词
@@ -137,4 +149,9 @@
 | 斜杠命令构建修复 | 「`/fec-debug` 请根据这段日志修复验证失败：<粘贴日志>。」                                         | cmd: `/fec-debug`      | 增量验证修复。                  | 粘贴准确日志。                        |
 | 斜杠命令清理     | 「`/fec-refactor-clean` 请安全移除这个包里的未使用导出和依赖。」                                      | cmd: `/fec-refactor-clean` | 清理报告和安全修改。            | 修改后运行测试。                      |
 | 斜杠命令文档同步 | 「`/fec-doc-sync` 请同步 README、docs、env examples、脚本、API/路由说明和部署文档，使其匹配当前项目。」 | cmd: `/fec-doc-sync`       | 文档更新和验证说明。            | 发布前使用。                          |
-| 显式代理         | 「请委托 `fec-code-reviewer` 对 `src/features/payments/` 做 PR 风格评审，然后先总结阻塞项。」         | agent: `fec-code-reviewer`        | 专项代理报告和摘要。            | 适合专家评审。                        |
+| 显式代理 | 「请委托 `fec-code-reviewer` 审核 `src/features/payments/` 的现有代码，包括未改动代码，然后先总结阻塞项。」 | agent: `fec-code-reviewer` | 指定范围风险评估及专项报告。 | 不要求 Git 差异。 |
+
+
+技术图质量工作流：`cc-technical-diagrams` 的标准时序/流程图优先本地 Mermaid，架构图复用 draw.io 工作流，工具缺失时使用 JSON/HTML。导出 PNG 时生成实际测量且与缩放一致的 manifest，再运行 QA 并检查最终 PNG；保留完整文字、显式布局与关系，最多自动修复两轮，未解决问题需明确报告。可复现样例位于 `skills/cc-technical-diagrams/assets/quality-examples/`。
+
+[审核范围与技术图交付](review-and-diagram-workflows.md) — 范围规则、工具前提、导出命令与 QA 边界。

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

@@ -1,6 +1,6 @@
 # 项目结构
 
-`frontend-craft` 的详细目录布局。
+`frontend-craft` 的目录布局。当前版本 3.0.0，使用 TypeScript、ESM 和 esbuild，测试使用 Node.js `node:test`。分发 14 个 Agent、74 个 Skill（53 个前端 + 21 个公共）和 11 个命令。
 
 ## 仓库布局
 
@@ -17,6 +17,7 @@ frontend-craft/
 |   |-- 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 类型安全、异步、报告式评审
@@ -34,14 +35,25 @@ frontend-craft/
 |   |-- 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 和泛型
+|   |-- cc-source-driven-development/ # 官方来源、项目事实、版本敏感决策
+|   |-- cc-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 的策略和工作流
@@ -65,21 +77,29 @@ frontend-craft/
 |   |-- 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-image-generation/           # UI/产品/品牌视觉生成、编辑与公共 PNG 质检
+|   |-- cc-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/                    # 项目吸收工作流——抽取参考系统能力并原创化重写
+|   |-- cc-technical-diagrams/ # 技术图、导出及 PNG QA
+|   |-- cc-doc-sync-core/ # 公共文档事实同步方法
+|   |-- cc-debug-methodology/ # 公共循证诊断方法
+|   |-- cc-refactoring-core/ # 公共行为保持重构方法
+|   |-- cc-tdd-methodology/ # 公共 TDD 方法
 |
 |-- commands/         # 快速执行的斜杠命令
 |   |-- fec-init.md     # /fec-init - 初始化项目模板
-|   |-- fec-review.md   # /fec-review - 代码评审
+|   |-- 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/            # 事件驱动自动化
@@ -87,14 +107,23 @@ frontend-craft/
 |
 |-- src/              # 发布运行时代码的 TypeScript 源码
 |   |-- hooks/         # 打包到 dist/hooks 的运行时 hook 脚本
-|   |-- security-check.ts      # 拦截危险命令
-|   |-- format-changed-file.ts # 自动执行 Prettier 格式化
-|   |-- run-tests.ts           # 会话结束时运行检查
-|   |-- session-start.ts       # 会话开始时检测框架
-|   |-- notify.ts              # 跨平台桌面通知
+|   |   |-- security-check.ts      # 拦截危险命令
+|   |   |-- format-changed-file.ts # 自动执行 Prettier 格式化
+|   |   |-- run-tests.ts           # 会话结束时运行检查
+|   |   |-- session-start.ts       # 会话开始时检测框架
+|   |   |-- notify.ts              # 跨平台桌面通知
 |   |-- install/       # 安装器核心（CLI、交互向导、运行时转换器）
+|   |   |-- cli-lifecycle.ts # CLI 自升级/自卸载与资源刷新
+|   |   |-- migration.ts # 只读旧入口迁移检查
+|   |   |-- shared/ # 公共快照、所有权与产品事务协调
 |   |-- openclaw/      # OpenClaw 运行时 TypeScript 源码
 |
+|-- bin/              # TypeScript CLI 入口，构建到 dist/bin/
+|-- localized/zh-CN/  # 中文 agents、commands、skills 和 templates
+|-- common-content.lock.json # 固定公共版本、来源与文件摘要
+|-- tests/            # 内容、安装、迁移、公共事务与 CLI 生命周期测试
+|-- dist/             # 生成的 CLI、hooks 和 OpenClaw bundle，不手改
+|
 |-- scripts/          # 仓库维护脚本源码，不发布到 npm runtime
 |
 |-- templates/        # 运行时专用项目模板
@@ -126,3 +155,12 @@ frontend-craft/
 | `src/openclaw/` | OpenClaw 运行时 TypeScript 源码                                                    |
 | `templates/`    | 运行时专用项目模板（Claude/Codex/Cursor/Gemini/OpenClaw/Windsurf 配置 + shared rules） |
 | `tests/`        | 测试套件（转换器测试、安装器测试）                                                 |
+
+
+技术图质量工作流：`cc-technical-diagrams` 的标准时序/流程图优先本地 Mermaid，架构图复用 draw.io 工作流，工具缺失时使用 JSON/HTML。导出 PNG 时生成实际测量且与缩放一致的 manifest，再运行 QA 并检查最终 PNG；保留完整文字、显式布局与关系，最多自动修复两轮，未解决问题需明确报告。可复现样例位于 `skills/cc-technical-diagrams/assets/quality-examples/`。
+
+[审核范围与技术图交付](review-and-diagram-workflows.md) — 范围规则、工具前提、导出命令与 QA 边界。
+
+公共 `cc-*` 与领域方法副本由 `craft-common@2.0.0` 生成；修改上游后运行 `pnpm run sync:common`，使用 `pnpm run check:common` 只读检查。不要手工编辑公共分发副本。领域内容的权威源在本仓库，中文镜像位于 `localized/zh-CN/`。
+
+`src/project/` keeps product framework declarations and inspect integration. Bounded discovery and task recommendation live in craft-common; backend retains the six-language validation projection. 产品不复制扫描器或公共安装算法。

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`」「仅审核最近改动」。修改后的自动审核必须明确传入本次改动范围。
+
+## 技术图
+
+时序图和流程图通过 `cc-technical-diagrams` 优先使用本地 Mermaid；可编辑架构图使用 `cc-drawio-studio`。工具缺失时使用 JSON/HTML 渲染器。需要准确结构的技术关系与标签应保存在可编辑源文件中。
+
+Mermaid 适配器仅使用已安装 CLI，不自动下载依赖。PNG 导出需要本地 Chromium 浏览器，可通过 `FEC_BROWSER_PATH` 指定可执行文件。缺少工具时明确报告，不宣称导出成功。
+
+JSON/HTML 路线先渲染源文件，导出 PNG 与同比例的浏览器实测 manifest，再运行 QA 并检查最终图片：
+
+```bash
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input skills/cc-technical-diagrams/assets/quality-examples/workflow.json --type workflow --output workflow.html --manifest workflow.layout.json
+node skills/cc-technical-diagrams/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/cc-technical-diagrams/scripts/png-qa.mjs --png workflow.png --manifest workflow.actual.json --format json
+```
+
+保留完整 Unicode 标签、显式几何布局、连线方向、时序顺序与自调用；独立 SVG 应包含自身样式。几何 QA 和浏览器测量辅助视觉检查，不证明语义正确，也不等同于完成人工视觉审核。缺少测量或仅部分覆盖时必须说明。最多自动修复源文件两轮，之后报告未解决缺陷。
+
+交付可编辑源文件、请求的导出文件和 QA/覆盖结果。参见[可复现样例](../../localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/README.md)、[图表工作流](../../localized/zh-CN/skills/cc-technical-diagrams/references/diagram-workflows.md)及 [PNG QA](../../localized/zh-CN/skills/cc-technical-diagrams/references/png-qa-autofix.md)。
+
+[English](../review-and-diagram-workflows.md)