必要性代码审计

原则

优化目标是“当前是否必要”，不只是“是否零引用”。一个符号即使仍有调用，也可能只是包装层、兼容面、防御分支、陈旧公共 API 或假设性的扩展点。

核心问题是：这个代码被用了，但当前代码真的还需要它吗？

不要删除真实运行约束。必须保留代表加载、空数据、错误、权限、生命周期、浏览器、SSR、配额、外部输入或领域可空状态的分支。

不要把普通注释当作清理目标。只有注释已经过期、错误、误导，或因为代码删除而孤立时，才删除或改写注释。

不要在发现第一个明显清理点后停止。对于用户指定的目录或功能，必须先审完整个作用域，再报告“没有更多”或要求用户继续。

技能协作

本技能是三个清理技能的主入口：

• 用 necessary-code-audit 判断“已被使用的代码是否仍然必要”。
• 用 unused-code-audit 证明删除候选是否仍有消费者。
• 目标涉及页面状态、查询/变更流、权限、错误或用户可见行为时，用 page-flow-cleanup-audit。

不依赖仓库专属图工具。优先使用当前环境可用的文件列表、语言工具、构建/类型检查、manifest、导入图和文本搜索。

边界

本技能只回答“即使有人在用，这个抽象/行为/API 是否仍然必要？”。

适合本技能：

• 有调用方的 wrapper、facade、兼容别名、默认值、fallback、可选字段或配置。
• 多处调用但调用方可以直接使用更基础 primitive 的 helper。
• 公共 API 仍被 import，但只是历史兼容面或陈旧入口。
• 防御分支、try/catch、可选链、as any 或旧格式兼容是否代表真实约束。
• 两份 source of truth、重复 cache/store/query/派生计算是否需要合并。

不适合本技能单独完成：

• 只想证明某文件、导出或类型是否零消费者；改用 unused-code-audit。
• 删除没有调用方的死代码；先用 unused-code-audit 完成消费者证明。
• 页面状态、权限、查询/变更链路或用户可见流程清理；改用 page-flow-cleanup-audit。

协作规则：

• 若候选看起来零消费者，暂停必要性判断，转为 unused-code-audit 的删除证明。
• 若候选仍有消费者，再继续判断是否必要、是否能替换调用方、是否应收缩公共面。
• unused-code-audit 的结论只能说明“能否安全删除未使用项”，不能替代本技能对“已使用但不必要”的判断。

基线

开始时必须收集：

• git status --short --untracked-files=all
• git diff --name-status -- <scope>
• git diff --cached --name-status -- <scope>
• 目标作用域文件清单，优先用 rg --files <scope>。
• 当前导入、导出、公共入口和直接消费者。
• 作用域符号清单：导出的函数/类型/常量、非导出 helper、配置字段和重复字面量。
• 影响面图：同包消费者、包入口、直接 app/package import，以及 manifest 中的下游包。

不要假设 staged 或 dirty 变更是自己造成的。不要回滚无关变更。

深度门槛

编辑前和完成前都必须完成这些检查：

1. 盘点作用域内每个文件和有意义的导出/helper，而不是只看用户最先提到的文件。
2. 将候选分成“零消费者候选”和“有消费者但可能不必要候选”；零消费者候选交给 unused-code-audit 证明。
3. 对有消费者的候选，至少检查每个消费区域的一个代表调用点，再判断抽象是否必要。
4. 对可替换候选，确认调用方能否直接使用现有 primitive，以及替换后会孤立哪些 export/helper/type。
5. 对公共 API 变更，确认 package exports 以及能覆盖变更面的下游包/app typecheck。
6. 每批清理后重新搜索残留名称、旧 import path、重复字面量和新孤立 helper。
7. 只有剩余候选都已归类为真实约束、刻意保留的公共 API，或超出当前请求风险范围时，才停止。

如果这些检查发现更多工作，要在同一轮继续处理。不要要求用户说“继续深度检查”才推进。

候选分类

对目标作用域中的每个有意义文件、导出、方法、字段、选项、fallback 和分支分类：

• 当前必要：当前产品行为或平台/运行时约束需要。
• 可直接替代：调用方可以直接使用底层 primitive 的 wrapper/facade。
• 兼容面：为外部或历史消费者保留的旧导出、可选字段、默认值、别名、工厂、配置或公共类型。
• 防御分支：try/catch、fallback、可选链、空值保护、特性检测或脏数据处理。
• 假设性能力：没有当前调用方，或只有假想未来价值的 API 面。
• 重复来源：第二份 cache、store、query、invalidation 路径、状态源或派生计算。
• 疑似死代码：看起来没有真实消费者；不要在本技能内直接删除，转交 unused-code-audit 证明。
• 真实约束：SSR、浏览器存储可用性、配额、权限、加载/错误/空态生命周期、外部输入或合法领域可空状态。
• 仅文档：注释或文档。除非过期、误导或被代码变更孤立，否则保留。

必要性问题

每个候选在编辑前回答：

1. 当前代码真的需要这个行为吗？
2. 如果它有调用方，调用方需要这个抽象吗，还是能直接调用现有 primitive？
3. 它保护的是真实运行/领域状态，还是历史兼容/假设？
4. 如果无需向后兼容，公共类型、导出或配置能否删除？
5. 删除是否改变当前产品行为？如果会，这是否符合请求意图？
6. 删除后哪些方法、import、export、注释、测试或文档会变得无意义？

当用户想删的其实是真实约束而非防御代码时，要明确指出。

清理顺序

1. 先删除 wrapper、facade 和兼容层。
2. 将调用点替换为直接 primitive。
3. 删除新孤立的方法、helper、import、export 和公共类型。
4. 删除无用配置 key、默认值、可选字段、feature flag 和因代码删除而孤立的旧注释。
5. 删除只隐藏不可能或过期状态的防御分支。
6. 每次删除来源或公共 API 后重新做残留搜索。

不要为了删除旧抽象而创建新抽象。

注释清理只是代码清理的附带动作。不要把“低价值注释”纳入清理顺序，除非它错误或已孤立。

证据

结构证据：

• 目标目录或功能的文件清单。
• wrapper、方法和导出符号的 import/export 搜索。
• manifest、re-export 文件、框架约定、生成文件和类型声明。
• 可用时使用语言工具：编译诊断、测试覆盖、依赖分析或 IDE 引用。
• 每个改动过的公共 helper 至少检查每个消费包/app 的一个代表调用点。
• 根据真实导入图选择下游 package/app typecheck，而不是只检查定义包。

文本残留搜索：

• 删除的文件 stem 和 import path。
• 删除的符号名和成员名。
• 兼容相关词：legacy、deprecated、backward、compat、fallback、debug、旧格式注释、注释掉的代码。
• 防御模式：try、catch、可选字段、可选链、as any、恒定布尔参数、默认配置值。
• 重复字面量和等价本地 helper，这可能说明共享 primitive 没被复用。

自动 unused-export 或依赖分析工具只能作为候选生成器。发现零消费者候选后，进入 unused-code-audit 的证明流程；本技能继续处理“仍被使用但不必要”的候选。

验证

运行覆盖改动边界的最窄检查：

• 公共 API 变更后，先跑定义模块或库的 typecheck/build。
• 直接消费者 package 的 typecheck 或窄 eslint。
• import、公共导出或共享校验/格式化行为变更时，跑下游 app/package typecheck。
• 对删除符号和旧 import path 做残留 rg。
• git diff --check -- <scope>；若有 staged 变更，也跑 git diff --cached --check -- <scope>。

如果广义 typecheck 失败，要说明失败是否与本次清理相关。

报告

报告：

• 已删除：wrapper、兼容面、防御分支、陈旧公共 API 和直接替代。
• 已保留：真实运行/领域约束，以及为什么它不是无意义防御代码。
• 已验证：命令、结果、残留搜索、无关 dirty 文件或无关失败。

要明确说明哪些候选交给了 unused-code-audit 证明，哪些候选是“仍被使用但不再必要”并由本技能处理。