danhuaxiansheng 必要性代码审计
原则
优化目标是“当前是否必要”，不只是“是否零引用”。一个符号即使仍有调用，也可能只是包装层、兼容面、防御分支、陈旧公共 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=allgit diff --name-status -- <scope>git diff --cached --name-status -- <scope>- 目标作用域文件清单，优先用
rg --files <scope>。 - 当前导入、导出、公共入口和直接消费者。
- 作用域符号清单：导出的函数/类型/常量、非导出 helper、配置字段和重复字面量。
- 影响面图：同包消费者、包入口、直接 app/package import，以及 manifest 中的下游包。
不要假设 staged 或 dirty 变更是自己造成的。不要回滚无关变更。
深度门槛
编辑前和完成前都必须完成这些检查：
- 盘点作用域内每个文件和有意义的导出/helper，而不是只看用户最先提到的文件。
- 将候选分成“零消费者候选”和“有消费者但可能不必要候选”；零消费者候选交给
unused-code-audit证明。 - 对有消费者的候选，至少检查每个消费区域的一个代表调用点，再判断抽象是否必要。
- 对可替换候选，确认调用方能否直接使用现有 primitive，以及替换后会孤立哪些 export/helper/type。
- 对公共 API 变更，确认 package exports 以及能覆盖变更面的下游包/app typecheck。
- 每批清理后重新搜索残留名称、旧 import path、重复字面量和新孤立 helper。
- 只有剩余候选都已归类为真实约束、刻意保留的公共 API，或超出当前请求风险范围时，才停止。
如果这些检查发现更多工作，要在同一轮继续处理。不要要求用户说“继续深度检查”才推进。
候选分类
对目标作用域中的每个有意义文件、导出、方法、字段、选项、fallback 和分支分类：
当前必要：当前产品行为或平台/运行时约束需要。可直接替代：调用方可以直接使用底层 primitive 的 wrapper/facade。兼容面：为外部或历史消费者保留的旧导出、可选字段、默认值、别名、工厂、配置或公共类型。防御分支：try/catch、fallback、可选链、空值保护、特性检测或脏数据处理。假设性能力：没有当前调用方，或只有假想未来价值的 API 面。重复来源：第二份 cache、store、query、invalidation 路径、状态源或派生计算。疑似死代码：看起来没有真实消费者；不要在本技能内直接删除，转交unused-code-audit证明。真实约束：SSR、浏览器存储可用性、配额、权限、加载/错误/空态生命周期、外部输入或合法领域可空状态。仅文档：注释或文档。除非过期、误导或被代码变更孤立，否则保留。
必要性问题
每个候选在编辑前回答：
- 当前代码真的需要这个行为吗？
- 如果它有调用方，调用方需要这个抽象吗，还是能直接调用现有 primitive？
- 它保护的是真实运行/领域状态，还是历史兼容/假设？
- 如果无需向后兼容，公共类型、导出或配置能否删除？
- 删除是否改变当前产品行为？如果会，这是否符合请求意图？
- 删除后哪些方法、import、export、注释、测试或文档会变得无意义？
当用户想删的其实是真实约束而非防御代码时，要明确指出。
清理顺序
- 先删除 wrapper、facade 和兼容层。
- 将调用点替换为直接 primitive。
- 删除新孤立的方法、helper、import、export 和公共类型。
- 删除无用配置 key、默认值、可选字段、feature flag 和因代码删除而孤立的旧注释。
- 删除只隐藏不可能或过期状态的防御分支。
- 每次删除来源或公共 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 证明，哪些候选是“仍被使用但不再必要”并由本技能处理。