Yy Frontend Refactor Scaffold

yy-frontend-refactor-scaffold

描述

为前端项目（Vue2 / Vue3 / React）的重构任务生成「方案 + 骨架」两件套：

1. PLAN.md —— 结构化重构方案，记录原始布局分析、组件逻辑/交互规则分析、组件依赖图、路由表、状态流转图、文件映射表。
2. 占位骨架文件 —— 按文件映射表，在重构目标文件夹下生成「空骨架 + 头部注释」的占位文件，每个占位文件标注它对应的原始文件路径与 TODO 标记。

skill 全程只读原始文件夹、只写重构目标文件夹与 PLAN.md，绝不修改原始代码。

使用场景

• 用户想把某个前端模块重构成新模块，并要先规划再动手
• 用户基于既有目录的布局，在另一个目录铺一套空骨架
• 用户为重构任务要"方案 + 占位文件"两件套

不应触发：

• 直接迁移/翻译/复制源码（如 Vue2 升 Vue3 的实际代码翻译） ← 同一对象的不同操作
• 修改原始文件夹内的任何代码 ← 同一对象的不同操作
• 后端代码重构（Java/Go/Python 等） ← 同一动词的不同对象
• 为既有代码补充行内注释 / 业务说明 ← 功能相邻
• 代码精炼、import 整理、格式化 ← 功能相邻

核心原则

1. 只读源端、只写目标端：原始文件夹只读不写；PLAN.md 与占位文件统一写到重构目标文件夹。
2. PLAN 是占位的唯一依据：占位文件清单必须严格来自 PLAN.md 中已确认的「文件映射表」，禁止在生成阶段临时增删文件。
3. 极简骨架：占位文件只包含「让框架能识别的最小骨架 + 头部注释」，不预留任何业务逻辑、状态、接口、组件导入。
4. 保持原结构：占位文件的目录层级与文件名默认与原始文件夹一一对应；如用户在确认环节要求调整，按用户意图调整。

指令

步骤 1. 收集与校验路径

skill 启动时收集两个路径：

• 原始参考文件夹（source）：被分析对象，必须存在且非空。
• 重构目标文件夹（target）：写 PLAN.md 与占位文件的目标位置。

决策分支：

• 用户已提供两个路径：直接进入校验。
• 只提供一个或未提供：用 question 工具一次性询问缺失路径。
• 提供的是文件而非文件夹：默认改用其所在目录，向用户说明。

路径校验（按顺序，命中即处理）：

1. 原始文件夹不存在 → 用 question 工具询问重新指定，禁止继续。
2. 原始文件夹为空或不包含前端文件（无 .vue / .jsx / .tsx / .js / .ts）→ 用 question 工具询问是否选错目录。
3. 目标文件夹是原始文件夹本身或其子目录 → 直接报错终止，要求用户重新指定（避免分析时把目标也扫进去）。
4. 目标文件夹已存在且非空 → 默认追加（不覆盖既有文件），仅在生成汇总中标注；不阻塞流程。

跨项目场景：若原始与目标分属不同项目（不同代码库 / 不同代际），在 PLAN.md 元信息中标注「跨项目重构」，并在「待确认清单」提醒别名、状态管理、UI 库等差异；不阻塞流程。

步骤 2. 框架识别

按 resources/framework-detect.md 判定原始文件夹使用的前端框架（Vue3 / Vue2 / React / JS-TS）。

决策分支：

• 单一框架识别成功：直接采用。
• 混合框架（如 Vue2 + Vue3 共存）→ 用 question 工具询问以哪个框架为准，列出识别到的所有候选。
• 跨代际重构（如源端 Vue2 而目标侧 Vue3）→ 在 PLAN.md 元信息中同时记录两边框架，并在「待确认清单」显式提醒差异。
• 无法识别（不属于上述任一框架，如 Svelte / Solid / Alpine 等）→ 按兜底策略，用 question 工具询问用户手动指定框架。

步骤 3. 分析原始布局

按 resources/layout-analysis.md 执行，产出：

1. 目录结构树：以 text 代码块呈现原始文件夹的目录树，标注每个文件/文件夹的简要职责。
2. 文件清单表：路径 / 类型（Vue/JS/TS/样式/测试）/ 推测职责（1 句话）/ 入口标识。
3. 入口文件识别：main.js / main.ts / App.vue / index.html / index.js 等。
4. 路由表（若检测到 router 配置文件）：提取 path / name / component / meta 列表。
5. 组件依赖关系图：用 Mermaid graph 表达组件父子关系（仅当组件数 ≥ 3 时生成，否则用列表替代）。

异常降级：

• 路由文件存在但解析失败 → 在 PLAN.md 中标注"路由表自动解析失败，请在确认环节补充"，不阻塞流程。
• 组件依赖关系复杂（> 30 个节点）→ 只画顶层组件与一级子组件，深层组件用列表呈现。

步骤 4. 分析逻辑与交互规则

按 resources/logic-analysis.md 执行，按框架差异化分析每个组件：

• Vue2：Props、Events（this.$emit）、关键事件、data 状态、Vuex 调用、路由跳转。
• Vue3：Props（defineProps）、Emits（defineEmits）、关键事件、ref / reactive 状态、Pinia / Vuex 调用、路由跳转。
• React：Props（解构）、回调（onXxx）、useState / useReducer 状态、Context、路由跳转。

输出项（每个组件统一产出，缺项标 —）：

• 职责概述：1 句话。
• Props 清单：名称 / 类型 / 是否必填 / 默认值。
• Emits/Events 清单：事件名 / 触发条件 / 载荷。
• 关键事件：模板/JSX 中绑定的事件。
• 数据流：调用的接口（API 函数名）、状态管理（store action / mutation / setState）。
• 状态流转：若组件含显著状态机（审批流、向导步骤、对话框开关链），用 Mermaid stateDiagram 表达；简单组件跳过。

步骤 5. 生成 PLAN.md

按 resources/plan-template.md 的标准模板生成 PLAN.md，写入重构目标文件夹根目录。

PLAN.md 必须包含的章节：

1. 元信息（原始路径 / 目标路径 / 框架识别结果 / 生成时间戳）
2. 原始布局分析（步骤 3 产出）
3. 逻辑与交互规则分析（步骤 4 产出，按文件分组）
4. 组件依赖关系图（Mermaid graph，若适用）
5. 路由表（若适用）
6. 状态流转图（Mermaid stateDiagram，若适用）
7. 文件映射表（核心章节）：原始路径 → 重构路径 / 文件类型 / 推测职责 / 备注
8. 待确认清单（明确列出需要用户拍板的开放问题）

生成时间戳（写入「元信息」表的「生成时间」字段前必须执行）：

date "+%Y-%m-%d %H:%M:%S"

禁止 AI 推算时间——AI 不具备系统时钟感知能力。

步骤 6. 与用户确认

PLAN.md 生成后，立即停止后续动作，用 question 工具向用户发起一次性确认。

必问项（合并为单次询问）：

1. 文件映射表是否准确：是否有遗漏 / 多余 / 路径错误。
2. 目录结构是否调整：默认保持原结构；如需扁平化 / 合并目录 / 改名，由用户指出。

用户的回复路径：

• 「全部确认」 → 进入步骤 7。
• 「需要调整」 → 按用户指示修改 PLAN.md 后再次确认。
• 「终止」 → 不生成占位文件，保留 PLAN.md 供用户参考。

此步骤是 skill 的关键检查点。禁止跳过确认直接生成占位文件——占位文件一旦铺开，回滚成本随文件数线性上升。

步骤 7. 生成占位文件

用户确认后，按 PLAN.md 中已确认的文件映射表，在重构目标文件夹下逐个生成占位文件。

占位文件形态（详见 resources/scaffold-templates.md）：

• 空骨架 + 头部注释：仅包含让框架能识别的最小结构（如 Vue3 的 <template>/<script setup>/<style lang="scss"> 空壳），头部加注释指向原始文件 + TODO 标记。
• 不预留业务逻辑：禁止预填 props 默认值、状态初值、API 调用、组件导入、样式类名等。
• 文件命名保持一致：默认与原始文件同名（含大小写）。如用户在确认环节要求改名，按用户指示。
• 目录结构按 PLAN.md：严格按文件映射表的「重构路径」列创建目录与文件。

生成顺序：

1. 按 PLAN.md 文件映射表自顶向下生成（先建目录，再建文件）。
2. 每生成一个文件打印一行 ✅ <相对路径>。
3. 失败时打印 ❌ <相对路径> - <失败原因>，继续后续文件，不中断。
4. 全部完成后统计成功 / 跳过 / 失败数，交回步骤 8 输出。

已存在文件处理（默认跳过，不阻塞）：

• 默认跳过并警告（不覆盖），在生成汇总中列出。
• 路径不存在时自动创建所需目录（mkdir -p 语义）。
• 占位文件不预填任何 import 路径（骨架本来就是空的），跨项目别名差异仅在 PLAN.md 中提醒用户。

步骤 8. 输出结果

按以下格式输出（不省略失败项）：

## 重构脚手架生成汇总

- 📁 原始文件夹：<source>
- 📁 重构文件夹：<target>
- 🧩 框架识别：<Vue3 / Vue2 / React / JS-TS>
- 📄 PLAN.md：<target>/PLAN.md

### 文件生成统计

- ✅ 成功：X 个
- ⏭️ 跳过：Y 个（已存在 / 用户选择跳过）
- ❌ 失败：Z 个

### 文件清单

#### ✅ 成功生成

- <target>/src/views/user-center/index.vue
- <target>/src/views/user-center/components/UserCard.vue
- ...

#### ⏭️ 跳过

- <target>/src/router/index.js（已存在）

#### ❌ 失败

- <target>/xxx - <失败原因>

### 后续建议

- 用户需手动在重构文件夹内补充业务逻辑（占位文件已标注 TODO）
- 跨项目场景需检查别名、状态管理、路由配置差异

安全边界

禁止：

• 修改原始文件夹的任何文件（即使是格式化、加注释也不行）
• 在原始文件夹内执行 git 操作（commit / push / checkout）
• 未经确认覆盖目标文件夹内已存在的同名文件
• 在占位文件中预填业务逻辑、状态、API 调用、组件导入、样式

允许：

• 在目标文件夹内创建目录、写入占位文件、写入 PLAN.md
• 读取原始文件夹与目标项目的配置（package.json / tsconfig.json / vite.config._ / vue.config._）用于框架识别与别名检测
• 目标文件夹已存在时，跳过同名文件（默认不覆盖）

边界条件

• 原始文件夹过大（> 200 个文件）：提示用户「文件数较多，分析耗时较长」，建议缩小范围或分批处理。
• 原始文件夹是项目根目录：警告「建议细化到具体模块目录，避免扫描整个项目」。
• 目标文件夹与原始文件夹相同或为其子目录：直接报错终止（步骤 1 已拦截）。
• 无路由配置：PLAN.md 中路由表章节标注「未检测到路由配置」并跳过。
• 无显著状态流转：PLAN.md 中状态流转图标注「无显著状态机」并跳过。

相关资源

按当前任务读对应文件，不要一次性全部加载：

• resources/framework-detect.md：步骤 2 框架识别时读，了解 Vue2/Vue3/React 的识别特征与失败兜底
• resources/layout-analysis.md：步骤 3 原始布局分析时读，了解目录树、文件清单、入口识别、路由提取、依赖图的具体规则
• resources/logic-analysis.md：步骤 4 逻辑/交互分析时读，按当前框架读对应章节（Vue2 / Vue3 / React）
• resources/plan-template.md：步骤 5 生成 PLAN.md 时读，了解章节结构与 Mermaid 图写法
• resources/scaffold-templates.md：步骤 7 生成占位文件时读，按当前框架读对应骨架模板