absolute-prune

✂️

Absolute Prune

清除仓库中的无用内容：未使用的依赖、未被引用的导出、不可达代码或孤立文件。以证据为依据——每项删除都有工具证明没有任何引用——分批安全执行，并确保每批完成后测试均通过。

运行 references/health-engine.md 中的共享引擎——请阅读其中的 DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT 循环和安全约定。本文件仅介绍修剪特有的内容。

---

适用场景

• “移除无用代码”“清理未使用的依赖”“有什么可以删掉？”。
• 不再被任何内容导入的包导致构建产物或安装包膨胀。
• 重构后的孤立内容：功能改道后遗留的文件和导出。

prune 与 simplify 的区别：simplify 润色当前工作区的 git 差异。prune 会扫描整个已提交的仓库，找出仓库范围内无用的内容。变更过程中使用 simplify；在测试通过的 main 上进行常规清理时使用 prune。

---

扫描内容

无用依赖——已声明但从未导入的依赖（以及已导入但未声明的缺失依赖）：

生态系统	工具
JS/TS	depcheck 或 knip（knip 也涵盖导出和文件）
Python	deptry
Go	go mod tidy（差异），未使用模块检测

无用代码——未被引用的导出、不可达分支、孤立文件：

生态系统	工具
JS/TS	knip（导出/文件）、ts-prune、eslint no-unused-vars
Python	vulture、ruff 未使用规则
Go	deadcode ./...、staticcheck（U1000）

优先使用项目中已有的工具。将结果视为候选项——删除前，确认它们不会通过动态导入、反射、DI、公共 API 或配置字符串被访问。

---

风险排序（TRIAGE）

批次	删除内容	默认处理
1	未使用的 devDeps、未被引用的本地导出/函数	立即修复——风险最低
2	未使用的运行时依赖、孤立的内部文件	确认不存在动态引用后，在本轮修复
3	任何可通过公共 API、插件系统、动态 require、反射或配置访问的内容	需审批 / 通常暂缓——误报风险高

静态工具会漏掉动态引用。对于第三批中的任何内容，或任何被工具标记但你无法证明确实无用的内容，都要向用户确认或暂缓处理——绝不自动删除。

---

修复与验证

• 分小批次、可回退地移除。每批只处理一种类别（例如“未使用的 devDeps”，然后是“孤立文件”）。
• 每批完成后：运行完整测试、构建和类型检查。类型检查/构建通过，就能证明已移除的符号确实没有被引用。如果有任何一项失败，说明该符号并非无用——回退并重新分类。
• 删除依赖时：从清单中移除，重新生成锁文件，然后重新构建。
• 不要删除：生成文件、供应商代码、公共 API 表面，或任何无法追溯的配置/插件关键内容。将这些报告为“疑似无用，需人工判断”。将配置中的 preferences.health.protectedPaths 视为永不删除的 glob——即使工具标记了匹配项，也不在处理范围内。

---

注意事项

1. 盲目信任工具。 动态导入、DI 容器、反射和字符串键查找都会绕过静态分析。删除前请确认。
2. 移除公共 API。 库中未在内部使用的导出，可能正是它的核心用途。检查包入口点 / exports 映射。
3. 删除生成文件或供应商文件。 它们看似孤立，但可能是有意重新生成或提交到版本库的。
4. 一次性大规模修剪。 在一个提交中删除所有被标记的内容，会导致回归问题难以二分定位。分批进行。
5. 范围蔓延到重构。 prune 只移除无用内容；它不会重构仍在使用的代码。重构 → 使用 simplify 或 work。

---

配套命令

• /absolute simplify — 用于重构差异中的现有代码，使其更清晰。
• /absolute upgrade — 可与之搭配使用：先清理未使用的依赖，再升级剩余依赖。
• /absolute debt — 清理代码通常也能一并消除一批 lint/未使用变量警告。