refactor-clean

代码清理重构

采用保守的清理循环。对于用途不确定的代码，宁可保留，也不要删除可能存在隐藏运行时依赖或外部使用方的内容。

工作流程

1. 建立基线。
2. 使用适合该语言的工具检测死代码。
3. 将发现项归类为 SAFE、CAUTION 或 DANGER。
4. 每次只删除一项 SAFE 内容。
5. 每次删除后都重新运行验证。
6. 处理 CAUTION 项目前先进行调查。
7. 除非用户明确希望深入调查，否则跳过 DANGER 项目。
8. 只有在死代码清理稳定后，才合并明显重复的内容。

建立基线

• 先运行范围最小且有意义的基线检查，再运行仓库要求的更全面项目检查。
• 记录清理开始前测试套件是否已经失败。
• 不要将新发现的既有故障归因于清理操作。
• 如果目标区域的基线检查未通过，请暂停并告知用户，然后再删除代码。

检测死代码

根据生态系统选择工具。尽可能优先使用项目的包管理器和现有脚本。

工具	检测内容	命令
knip	未使用的导出、文件和依赖项	npx knip
depcheck	未使用的 npm 依赖项	npx depcheck
ts-prune	未使用的 TypeScript 导出	npx ts-prune
vulture	未使用的 Python 代码	vulture src/
deadcode	未使用的 Go 代码	deadcode ./...
cargo-udeps	未使用的 Rust 依赖项	cargo +nightly udeps

如果无法使用专用工具，请改用有针对性的搜索：

• 查找导出的符号和文件。
• 搜索导入、require、动态导入、路由引用、配置引用和基于字符串的查找。
• 将“没有明显引用”视为线索，而非证据。

对发现项进行分类

编辑前，先将每个发现项归入一个安全等级。

等级	典型示例	默认操作
SAFE	未使用的内部工具函数、私有辅助函数、未使用的测试/辅助函数、没有调用方的包装函数	删除并验证
CAUTION	组件、钩子、API 路由、中间件、服务端操作、任务、CLI 命令	先调查运行时和间接使用情况
DANGER	配置文件、入口点、导出类型、架构文件、生成边界、公共 API	跳过，除非用户要求深入处理

出现以下任一情况时，升级到风险更高的等级：

• 动态导入路径
• 反射或注册表查找
• 基于字符串的路由或命令分发
• 框架自动发现
• 包的公共导出
• 外部使用方或跨仓库使用

安全删除循环

对每个 SAFE 项目：

1. 运行基线验证。
2. 通过精确修改，只删除一项内容。
3. 立即重新运行相关测试。
4. 如果测试失败，恢复此次删除并跳过该项目。
5. 如果测试通过，继续处理下一项。

保持每次删除都是原子操作。不要将多个互不相关的删除合并到同一轮验证中。

如果需要还原：

• 只恢复正在测试的项目。
• 优先使用非破坏性还原方法，避免影响用户的其他未提交更改。
• 在摘要中记录失败情况，然后继续处理其他项目。

处理注意事项项目

删除 CAUTION 项目前，请明确检查以下内容：

• import() 或 require() 的使用情况
• 配置、路由、注册表、功能标志和测试中的字符串引用
• 从包或应用入口点重新导出的情况
• 如果模块属于已发布或共享的接口面，检查是否有外部使用方
• 框架是否会根据文件名或位置自动加载文件

只有在排除间接使用且验证仍然通过后，才能删除 CAUTION 项目。

合并重复项

死代码清理通过后，查找低风险的合并机会：

• 行为相同的近似重复函数
• 冗余的类型定义
• 不增加策略或易用性的直通包装器
• 不提升可发现性或兼容性的重新导出

将此阶段与死代码删除分开。如果合并会改变行为，就不要再将其视为清理，并明确说明。

报告

最后提供一份简短的清理报告，其中包括：

• 已删除的函数、文件和依赖项
• 跳过的项目及原因
• 删除代码行数的大致估算
• 已运行的验证命令
• 最终通过／未通过状态

必要时使用此格式：

Dead Code Cleanup
----------------------------
Deleted:   12 unused functions
           3 unused files
           5 unused dependencies
Skipped:   2 items (verification failed)
Saved:     ~450 lines removed
----------------------------
All tests passing

规则

• 运行基线验证步骤之前，绝不删除代码。
• 每次只删除一项。
• 对不确定的发现予以跳过，不要猜测。
• 不要在删除过程中夹杂大范围重构。
• 恢复失败的删除时，保留与之无关的用户更改。
• 如果仍有 CAUTION 或 DANGER 项，明确说明残余风险。