Vulture 未使用代码检测

问题：重构前没人告诉你哪些代码可以删

Python 仓库在长期演进后通常会积累一批"历史遗留物"：某个重构周期里被替换掉的辅助函数、仅在某次实验分支里被引用过一次的 import、为旧接口配套的类方法。这些代码之所以危险，不是因为它们占用了多少内存，而是因为它们让阅读者无法判断当前代码的真实使用情况。当你准备做一次清理式重构时，面对几千个符号，逐个确认调用关系的成本高到多数人会选择"先不动它"，于是仓库越积越重。

问题在于：在真正开始删除之前，你缺少一份"哪些符号没有任何地方引用"的清单。

这个技能做了什么

这个技能的核心思路是：在动手清理之前，先跑一次 dead-code 扫描。它调用 Vulture 静态分析 Python 代码，把仓库中未被引用的函数、类、导入和变量标记出来，交给 agent 作为判断依据，而不是凭感觉直接删除。

工作流大致是：

• 准备阶段：确认环境具备 Python 3、pip 以及 Vulture CLI 工具。
• 扫描阶段：对目标脚本或整个仓库运行分析命令，例如 vulture myscript.py，或通过模块方式调用 python3 -m vulture myscript.py。
• 判断阶段：agent 拿到未使用符号列表后，逐项决定是删除、保留还是补上测试。

这样做的收益是清理行为从"盲目删除"变成"有证据地删"：每一处移除都对应一个静态分析的阴性结果，而不是一次猜测。

适用边界与注意点

先搞清楚 Vulture 是什么。 它是一款针对 Python 程序的静态分析工具，长处是清理大型代码库、在重构过程中发现潜在错误。但它检测的是静态可达性，不是运行时行为。

因为 Python 是动态语言，静态分析器的能力天然受限。以下场景里，"被标记为未使用"不等于"真的可以删"：

• 动态调用：通过 getattr、globals() 或字符串拼接方式触发的函数，静态分析看不到引用。
• 约定式入口：例如被框架按名字反射调用的方法（钩子、插件协议）。
• 入口文件局部引用：直接运行的脚本自身引用的符号，可能被判定为未使用。

所以结论是：这份列表应该当作"需要人工复核的清单"来用，而不是一份自动删除指令。对于仓库中确实无用的符号，它是可靠的裁判；对于边界情况，它给出的只是线索。

把这一步放在重构之前，能让你在改动面最大的那个动作上拥有数据支撑。