ln-626-dead-code-pruning-auditor

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

死代码清理审计员（L3 Worker）

类型： L3 Worker

专门识别可安全删除项的 Worker。

目的与范围

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

输入

必须读取： 加载 references/audit_worker_core_contract.md 和 references/mcp_tool_preferences.md。 工具策略：你可能以独立子 Agent 的形式运行，且宿主 AGENTS.md 不在适用范围内，因此读取、搜索和编辑文件时，默认优先使用 hex-line MCP。仅当 MCP 行为不明确时，才加载 references/mcp_integration_patterns.md。

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

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

工作流

检测策略：使用两层检测（候选项扫描，然后进行上下文验证）；仅当验证方法不明确时，才加载 references/two_layer_detection.md。

1. 解析 context + 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 之后的代码

严重性： MEDIUM

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

检测：

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

严重性：

• MEDIUM： 未使用的函数（增加无用负担）
• LOW： 未使用的导入（需要清理）

3. 注释掉的代码

检测：

• 搜索符合 //.*{ 或 /*.*function 模式的内容
• 包含代码语法的大段注释（超过 10 行）

严重性： LOW

建议： 删除（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

严重程度：

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

建议：

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

工作量：

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

评分算法

必须阅读： 加载 references/audit_scoring.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 Pruning"，检查项为：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 个月的旧版垫片 = MEDIUM，少于 3 个月 = LOW
• 合理评估工作量： S = <1 小时，M = 1-4 小时，L = >4 小时
• 排除项： 跳过生成代码、供应商代码、迁移文件、测试夹具
• 结合 Git 判断： 可放心建议删除——Git 历史会保留旧代码
• 独特侧重点： 仅审计可安全删除的候选项。不要重构活动代码、重组模块或评估依赖／软件包健康状况。
• 必须采取行动： 每项发现都使用 DELETE_DEAD_CODE、REMOVE_OBSOLETE_COMPAT 或 DELETE_COMMENTED_CODE。

完成定义

应用已加载的 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