# Yy Frontend Refactor Scaffold

> 分析前端项目（Vue2/Vue3/React）原始文件夹的目录布局与组件交互规则，生成结构化重构方案（PLAN.md）并在目标文件夹下按方案生成占位骨架文件。 仅用于"基于既有目录铺新骨架"的规划与脚手架生成，不用于直接翻译/迁移源码、修改原始文件夹、后端代码重构或为既有代码补充注释。

- Skill: `bulls-cows/yy-frontend-refactor-scaffold` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-frontend-refactor-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-frontend-refactor-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/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. 待确认清单（明确列出需要用户拍板的开放问题）

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

```bash
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. 输出结果

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

```markdown
## 重构脚手架生成汇总

- 📁 原始文件夹：<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 生成占位文件时读，按当前框架读对应骨架模板