用途
ln-721-frontend-restructure 是一个前端结构处理技能，类型为 L3 Worker，分类为 7XX Project Bootstrap。它用于搭建新的 React 项目，或将单体前端重构为基于组件的架构。该技能提供两种互斥的工作模式，根据当前项目状态选择使用。
主要能力
模式选择
| 模式 | 使用时机 | 输入 | 输出 |
|---|---|---|---|
| SCAFFOLD | CREATE 流水线——尚无前端 | 来自 ln-720 的目标技术栈配置 | 最小化的 React + Vite 项目（约 7 个文件） |
| RESTRUCTURE | TRANSFORM 流水线——已存在前端 | 单体 React 源码 | 基于组件的架构 |
作用范围
- 输入：目标技术栈配置（SCAFFOLD）或单体 React 源码（RESTRUCTURE）
- 输出：最小化项目（SCAFFOLD）或基于组件的架构（RESTRUCTURE）
- 框架：React + TypeScript + Vite
- 范围边界：
- SCAFFOLD：生成最小化起始文件，不包含业务逻辑
- RESTRUCTURE：重构现有代码，不添加新功能
- 适用于 React + TypeScript 项目
- 应用参考文件中的转换规则
使用方式
SCAFFOLD 模式（CREATE 流水线）
阶段 S1：生成起始文件
创建最小化的 React + Vite + TypeScript 项目。
| 文件 | 用途 |
|---|---|
| package.json | 依赖：react、react-dom、typescript、vite、@vitejs/plugin-react |
| vite.config.ts | Vite 配置，包含 React 插件、端口、代理设置 |
| tsconfig.json | 严格 TypeScript 配置，包含路径别名 |
| index.html | 入口 HTML，包含根 div |
| src/main.tsx | React 入口点，使用 StrictMode |
| src/App.tsx | 根 App 组件，包含路由占位符 |
| src/index.css | 基础样式（重置、变量、布局） |
阶段 S2：验证脚手架
| 检查项 | 方法 | 预期 |
|---|---|---|
| 所有文件已创建 | 文件存在性检查 | 7 个文件存在 |
| package.json 有效 | JSON 解析 | 无语法错误 |
| tsconfig.json 有效 | JSON 解析 | 无语法错误 |
| 无硬编码值 | 内容扫描 | 项目名称来自配置，而非硬编码 |
RESTRUCTURE 模式（TRANSFORM 流水线）
阶段 1：分析
扫描当前前端结构并对组件进行分类。
| 步骤 | 操作 | 参考 |
|---|---|---|
| 1.1 | 扫描源码中所有 .tsx 和 .ts 文件 | — |
| 1.2 | 测量文件复杂度（行数、hooks、类型） | transformation_rules.md |
| 1.3 | 按类别对组件进行分类 | component_patterns.md |
| 1.4 | 构建导入依赖图 | import_strategy.md |
输出：包含分类和度量的组件清单。
阶段 2：规划
基于分析生成迁移计划。
| 步骤 | 操作 | 参考 |
|---|---|---|
| 2.1 | 应用拆分阈值，识别需要重构的文件 | transformation_rules.md |
| 2.2 | 计算每个文件的目标路径 | react_folder_structure.md |
| 2.3 | 识别需要更新的导入 | import_strategy.md |
| 2.4 | 检测潜在冲突（名称冲突、循环依赖） | — |
输出：包含 Before/After 映射的迁移计划。
阶段 3：执行
按正确顺序应用转换。
| 步骤 | 操作 | 说明 |
|---|---|---|
| 3.1 | 创建目录结构 | 所有目标文件夹 |
| 3.2 | 将类型提取到 types.ts | 类型无依赖 |
| 3.3 | 将常量提取到 constants.ts | 常量仅依赖类型 |
| 3.4 | 将 hooks 提取到 hooks.ts | hooks 依赖类型、常量 |
| 3.5 | 提取子组件 | 组件使用以上所有内容 |
| 3.6 | 创建桶导出（index.ts） | 用于干净的导入 |
| 3.7 | 更新所有导入路径 | 修复引用 |
顺序至关重要：按顺序执行以避免导入中断。
阶段 4：验证
验证重构后的项目。
| 检查项 | 命令 | 预期 |
|---|---|---|
| TypeScript 编译 | npx tsc --noEmit | 无错误 |
| 构建 | npm run build | 成功 |
| 无孤立文件 | 手动检查 | 源位置为空 |
| 导入可解析 | 构建成功 | 无模块未找到错误 |
转换摘要
| 转换 | 之前状态 | 之后状态 |
|---|---|---|
| 组件拆分 | 单文件 >300 行 | 功能文件夹，文件共置 |
| 类型提取 | 内联接口 | 独立的 types.ts |
| 常量提取 | 内联魔法值 | 独立的 constants.ts |
| Hook 提取 | 内联 useState/useEffect | 独立的 hooks.ts 或共享 hooks |
| UI 组件移动 | 分散在功能中 | 集中到 components/ui/ |
| 布局组件移动 | 与功能混合 | 集中到 components/layout/ |
适用场景
- 需要从零搭建一个最小化的 React + Vite + TypeScript 项目骨架时，使用 SCAFFOLD 模式。
- 已有单体 React 前端，希望将其重构为基于组件的架构时，使用 RESTRUCTURE 模式。
- 适用于 React + TypeScript 项目的前端结构整理。
限制
- 仅处理前端结构，不涉及后端改动。
- SCAFFOLD 模式不生成业务逻辑。
- RESTRUCTURE 模式不添加新功能，仅做结构性调整，不改变行为。
- 两种模式不可混用。
- 必须验证构建通过（RESTRUCTURE：npm run build）。
- RESTRUCTURE 模式下，在验证通过前不删除源文件。
- 导入一致性：共享使用路径别名，共置使用相对路径。
关键规则
- 模式意识：SCAFFOLD 从模板创建；RESTRUCTURE 转换现有——绝不混用。
- 单一职责：仅处理前端结构，无后端更改。
- 幂等性：可重复运行而不产生重复文件或损坏。
- 构建验证：更改后必须验证构建通过（RESTRUCTURE：npm run build）。
- 保留功能：无行为更改，仅结构性（RESTRUCTURE 模式）。
- 备份策略：在验证通过前不删除源文件（RESTRUCTURE 模式）。
- 导入一致性：共享使用路径别名，共置使用相对路径。
完成定义
SCAFFOLD 模式：
- 所有 7 个起始文件已生成
- package.json 和 tsconfig.json 有效
- 无硬编码项目名称（使用配置值）
RESTRUCTURE 模式：
- 所有源文件已分析并分类
- 已生成包含 Before/After 映射的迁移计划
- 已按模板创建目录结构
- 所有提取已完成（类型、常量、hooks、组件）
- 导入路径已在项目中更新
- npm run build 成功通过
- 无孤立导入或缺失文件
- 已为共享文件夹创建桶导出
风险缓解
| 风险 | 检测 | 缓解 |
|---|---|---|
| 重构后构建失败 | npm run build 失败 | 回滚：从源恢复，调查具体错误 |
| 缺失导入 | 模块未找到错误 | 前后扫描所有导入，更新遗漏路径 |
| 循环依赖 | 构建警告或运行时错误 | 分析依赖图，通过提取共享代码打破循环 |
| 功能丢失 | 测试失败或 UI 损坏 | 转换前后运行现有测试 |
| 名称冲突 | 重复导出名称 | 移动前用功能前缀重命名 |
参考文件
| 文件 | 用途 |
|---|---|
| references/transformation_rules.md | 拆分阈值、提取规则、转换顺序 |
| references/component_patterns.md | 按类别进行组件分类 |
| references/import_strategy.md | 导入更新规则、路径别名、桶导出 |
| references/react_folder_structure.md | 目标目录结构模板 |
版本：3.0.0 最后更新：2026-02-07