frontend-refactor-workflow

name	frontend-refactor-workflow
description	用于 `desktop-electron/` 中的大型前端重构。适合处理超大 TS/TSX 文件拆分、React 模式迁移、测试先行的安全重构，以及需要用 ast-grep、dependency-cruiser、knip、Playwright 做分析与自动验证的场景。

前端重构工作流

当 D:\AI\SA-AIAPP\desktop-electron 里出现超大组件、职责混杂的 hook、难以维护的 TS/TSX 文件，或者需要安全迁移 React 模式时，使用这个 skill。

这个 skill 的目标不是“把文件拆漂亮”，而是“在功能不回归的前提下完成重构”。

使用原则

• 把“功能保护”放在“结构优雅”前面。
• 先盘功能和风险，再补测试，再改代码。
• 一次只做一个小步重构，每一步都要自动验证。
• 不把人工手测当成中间环节。除非用户明确要求，否则用户只在全部完成后做最终验收。
• 如果用户提到 /frontend-refactor-analyze、/frontend-refactor-apply、/frontend-refactor-verify，把它们映射到下方对应阶段直接执行。
• codemod 的 registry 只在确认存在现成 transform 时使用。不要臆造包名。

阶段 1：功能盘点

在真正编辑前，先把“这个文件现在承担了哪些用户可见功能”盘清楚。

• 确认目标文件、主要职责块、调用入口和现有测试。
• 优先梳理用户可感知行为：
  • 按钮和面板
  • 快捷键
  • 选择态切换
  • 成功/失败状态
  • 异步结果回流
  • 下载、导出、分享这类输出动作
• 用 ast-grep 做结构搜索，辅助找重复 JSX、hook 聚集区、事件处理器和 props 形状。
• 用 dependency-cruiser 看边界、循环依赖、跨层引用。
• 爆炸半径不清楚时，一律先用 dry-run 或只读报告模式。
• 命令模板看 references/commands.md。
• 在本仓库里，不要默认假设已有 sgconfig.yml 或 .dependency-cruiser.*。ast-grep 先用临时命令；dependency-cruiser 若仓库无配置则用 --no-config。

这一阶段的产物应该是：

• 一份功能清单
• 一份高风险行为清单
• 一份候选拆分边界清单

阶段 2：测试护栏

在开始重构前，先用自动化测试把关键行为钉住。

• 优先补“特征测试”而不是内部实现测试。
• 测试重点是外部行为，不是 hook 内部变量。
• 至少覆盖：
  • 核心按钮链路
  • 关键快捷键
  • 高风险状态切换
  • 成功/失败分支
  • 容易回归的下载、导出、分享、异步生成结果
• 能用现有 Vitest 单测解决的，优先单测。
• 交互路径复杂、静态分析不可信时，再加 Playwright。
• 不把“让用户中途手测”当默认方案。用户只在全部完成后做最终确认。

如果当前文件完全没有测试，不要直接开拆。先补最小可用护栏。

阶段 3：小步重构

只有在功能清单和测试护栏都具备后，才开始改代码。

• 一次只做一种提取：
  • 抽一个 hook
  • 抽一个 panel
  • 抽一个 utils
  • 抽一组 output actions
• 先保留对外行为，再优化内部结构。
• 能复用现成 React 迁移或 codemod 时优先复用；否则做小范围人工修改。
• 不做大面积正则替换，不做“顺手一起改很多东西”的重构。
• 每次改动后，及时整理 import、类型和对外 API。

阶段 4：自动验证

每做完一个小步，就立即验证，不要堆积到最后一起跑。

• 先跑受影响的定向测试。
• 再跑必要的前端测试，默认是 npm test 或更小范围的等价命令。
• 改动涉及复杂交互时，补跑 Playwright。
• 文件移动或删除较多时，跑 knip。
• 涉及依赖边界或目录职责时，跑 dependency-cruiser。
• 把无关 warning、历史失败和本次重构引入的问题分开汇报。

阶段 5：最终验收

所有自动化验证通过后，再把结果交给用户做最后一步确认。

• 只在这一步建议用户介入。
• 汇总：
  • 本次保护了哪些功能
  • 新增了哪些测试
  • 还剩哪些残余风险
• 如果用户不想手测，中间阶段不要默认把测试工作转嫁给用户。

规则

• 默认只在 desktop-electron/ 内工作，除非用户明确扩 scope。
• 结构分析必须服务于功能保护，不能反过来。
• 优先官方 React 迁移方案，再考虑自定义 transform。
• ast-grep 模式必须是合法 TS/TSX 语法。优先使用 useEffect($FN, $DEPS)、const $NAME = useCallback($FN, $DEPS) 这类可解析模式。
• 如果不存在已提交的 codemod workflow 文件，就把流程当作 skill 指导过程执行，不要硬造 workflow 文件。
• 当重构变成长期治理事项时，建议落库 dependency-cruiser 配置；只有在要沉淀结构规则时再考虑 sgconfig.yml。
• 调命令前，优先查看 references/commands.md。