ln-626-dead-code-auditor

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

死代码审计员（L3 Worker）

类型： L3 Worker

专门审计未使用和不可达代码的工作者。

目的与范围

• 审计死代码（类别 9：低优先级）
• 查找未使用的导入、变量、函数和注释掉的代码
• 计算合规评分（X/10）

输入

必须阅读： 加载 references/audit_worker_core_contract.md。 必须阅读： 加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md

接收包含技术栈、代码库根目录和 output_dir 的 contextStore。

当导出项活跃性或工作区热点能显著提升审计效果时，优先使用 hex-graph。本地读取代码时，若可用，优先使用 hex-line。如果 MCP 不可用、不受支持或未建立索引，则继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明所用回退方案。

工作流

必须阅读： 加载 references/two_layer_detection.md 了解检测方法。

1. 解析上下文和 output_dir
2. 运行死代码检测（第 1 层：代码检查工具、grep）
   • 支持图分析的项目： 对于 JavaScript、TypeScript/TSX、Python、C# 和 PHP，在图索引可用时，使用 index_project，然后执行受限的 audit_workspace(verbosity="minimal", limit=5)，作为检测未使用导出项的主要方式。只有在需要有针对性地深入分析时，才提高 limit。
   • 对于不受支持的语言、图分析不可用的运行，以及导出项活跃性之外的检查，继续使用 grep/代码检查工具作为回退方案。
3. 根据上下文分析每个候选项（第 2 层）：
   • 未使用的函数：是否通过动态导入/反射调用？是否导出到公共 API？是否在其他包中使用（单体仓库）？
   • 注释掉的代码：有上下文或算法说明的 TODO → 误报。确实无用的代码块 → 确认
   • 旧版兼容垫片：查看 git blame —— 年限？是否有跟踪移除工作的 issue/PR？
4. 收集已确认的发现
5. 计算评分
6. 编写报告： 按照 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-626--global.md
7. 返回摘要： 向协调器返回最精简的摘要

审计规则

必须阅读： 加载 references/clean_code_checklist.md，了解通用死代码模式和严重性定义。

1. 不可达代码

检测：

• 代码检查规则：no-unreachable（ESLint）
• 检查 return、throw、break 之后的代码

严重性： 中

2. 未使用的导入/变量/函数

检测：

• ESLint：no-unused-vars
• TypeScript：noUnusedLocals、noUnusedParameters
• Python：使用 F401、F841 规则的 flake8

严重性：

• 中： 未使用的函数（冗余代码）
• 低： 未使用的导入（需要清理）

3. 注释掉的代码

检测：

• 使用 grep 搜索 //.*{ 或 /*.*function 模式
• 包含代码语法的大型注释块（>10 行）

严重性： 低

建议： 删除（git 会保留历史记录）

4. 旧代码与向后兼容

内容： 向后兼容垫片、不受支持的模式、应移除的旧代码

检测：

• 使用旧别名的重命名变量/函数：
  • 模式：const oldName = newName 或 export { newModule as oldModule }
  • 模式：function oldFunc() { return newFunc(); }（用于向后兼容的包装器）
• 不受支持的导出/重新导出：
  • 搜索 // DEPRECATED、@obsolete JSDoc 标签
  • 模式：export.*as.*old.* 或 export.*legacy.*
• 针对旧版本的条件代码：
  • 模式：if.*legacy.* 或 if.*old.*version.* 或 isOldVersion ? oldFunc() : newFunc()
• 迁移垫片和适配器：
  • 模式：migrate.*、Legacy.*Adapter、.*Shim、.*Compat
• 注释标记：
  • 搜索 // backward compatibility、// legacy support、// TODO: remove in v
  • 搜索 // old implementation、// unsupported、// kept for backward

严重程度：

• 高： 关键路径（身份验证、支付、核心功能）中的向后兼容垫片
• 中： 仍在使用的不受支持的导出、超过 6 个月的迁移代码
• 低： 最近的迁移代码（不到 3 个月）、有明确移除时间表的计划弃用

建议：

• 移除向后兼容垫片——只要正确进行版本管理，破坏性变更是可以接受的
• 删除旧实现——仅保留正确/新版
• 移除不受支持的导出——更新使用方以改用新 API
• 在宽限期（3-6 个月）后删除迁移代码
• 清理旧代码支持注释——Git 历史会保留旧实现

工作量：

• S： 移除简单别名、删除不受支持的导出
• M： 将使用旧 API 的代码重构为使用新 API
• L： 移除影响多个模块的复杂向后兼容层

评分算法

必须阅读： 加载 references/audit_worker_core_contract.md 和 references/audit_scoring.md。

输出格式

必须阅读： 加载 references/audit_worker_core_contract.md 和 references/templates/audit_worker_report_template.md。

根据 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会同时传入 runId 和 summaryArtifactPath；在独立模式下，工作器根据共享契约生成自己的、作用域限定于本次运行的产物路径。

将报告写入 {output_dir}/ln-626--global.md，其中 category: "Dead Code"，检查项为：unreachable_code、unused_exports、commented_code、legacy_shims。

根据 references/audit_summary_contract.md 返回摘要。

当 summaryArtifactPath 缺失时，将独立运行时摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json，并可选择在结构化输出中回显相同的摘要。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-626--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

参考文件

• 整洁代码检查清单： references/clean_code_checklist.md
• 审计输出架构： references/audit_output_schema.md

关键规则

必须阅读： 加载 references/audit_worker_core_contract.md。

• 不要自动修复： 仅报告，绝不删除代码
• 考虑代码年龄的严重程度： 超过 6 个月的旧代码垫片 = 中；不到 3 个月 = 低
• 工作量评估应切合实际： S = <1h，M = 1-4h，L = >4h
• 排除项： 跳过生成代码、供应商代码、迁移代码、测试夹具
• 考虑 Git 历史： 可放心建议删除——Git 历史会保留旧代码

完成定义

必须阅读： 加载 references/audit_worker_core_contract.md。

• 已解析 contextStore（包括 output_dir）
• 已完成全部 4 项检查（不可达代码、未使用的导入/变量/函数、已注释掉的代码、旧代码垫片）
• 已从 references/clean_code_checklist.md 加载整洁代码检查清单
• 已收集包含严重程度、位置、工作量、建议的发现项
• 已根据 references/audit_scoring.md 计算分数
• 已将报告写入 {output_dir}/ln-626--global.md（使用一次原子 Write 调用）
• 已根据契约写入摘要

---

版本： 3.0.0 最后更新： 2025-12-23