技能介绍

大代码库里手动重构的痛点

当你接手一个几十万行的 TypeScript 项目，想要重命名一个被广泛引用的内部 API 时，find && replace 的结果往往是漏改、错改，或者把注释、字符串模板里的同名文本一并替换掉。手工重构的风险在于：你无法保证一次改动覆盖所有引用点，也无法在提交前确认没有遗漏的调用位置。extract-function 这类结构性改动更是如此——剪切粘贴代码块不会自动处理变量作用域、闭包捕获和导入依赖，人工操作很容易破坏模块边界。

核心能力与工作流程

这个技能基于 ts-morph 与 TypeScript 官方编译器 API，把重构从「文本编辑」变成「AST 变换」：

重命名：通过编译器提供的引用索引定位所有真实引用点，而不是做字符串匹配，因此字符串字面量和注释不会被误伤。
提取函数：识别选定的语句块，构造新的函数声明，并自动处理参数、返回类型推断以及作用域内的变量捕获。
死代码消除：基于可达性分析移除未被引用的声明，减少仓库中的噪音。

典型步骤是：读取项目配置、构建 TypeScript 项目模型、对目标节点执行变换、生成改动预览，最后写入文件。ts-morph 的文档（ts-morph.com）对底层 API 有详细说明，这个技能是把这套能力封装成可直接调用的流程。

适用边界与注意点

需要明确的是，自动化工具不能替代代码审查。对公开 API 的重命名，你仍然需要判断这是否属于有意的破坏性变更；在类型推断复杂、依赖大量动态特性的代码上，静态分析可能给出保守甚至错误的判断。另外，删除「死代码」之前要确认它没有被反射、字符串拼接或动态 import() 引用——这些用法在纯静态检查下是不可见的。建议先在分支上运行，配合 diff 逐项确认改动后再合并。