ln-512-tech-debt-cleaner

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

技术债务清理器（L3 Worker）

**类型：**L3 Worker

自动清理代码库审计中发现的安全、低风险技术债务。

目的与范围

• 使用来自 docs/project/codebase_audit.md（ln-620 输出）或 ln-511 代码质量输出的审计发现
• 筛选置信度 >=90% 且可自动修复的发现
• 应用安全修复：移除未使用的导入、删除无用代码、清理已注释掉的代码块、移除不受支持的别名
• 绝不触碰业务逻辑、复杂重构或架构变更
• 创建单个提交，并以结构化摘要汇总所有更改
• 可由 ln-510 质量协调器流水线调用，也可独立运行

可自动修复的类别

类别	来源前缀	风险	自动修复操作
未使用的导入	MNT-DC-	LOW	删除导入行
未使用的变量	MNT-DC-	LOW	删除声明
未使用的函数（未导出）	MNT-DC-	LOW	删除函数代码块
已注释掉的代码（>5 行）	MNT-DC-	LOW	删除注释块
向后兼容垫片（>6 个月）	MNT-DC-	MEDIUM	删除垫片 + 更新重新导出项
不受支持的别名	MNT-DC-	LOW	删除别名行
行尾空格 / 空行	MNT-	LOW	删除空格 / 合并空行

不可自动修复（始终跳过）

类别	原因
DRY 违规（MNT-DRY-）	需要对提取位置做出架构决策
巨型类（MNT-GOD-）	拆分类需要领域知识
安全问题（SEC-）	需要结合具体上下文修复
架构违规（ARCH-*）	需要做出设计决策
性能问题（PERF-*）	需要进行基准测试
任何工作量为 M 或 L 的发现	过于复杂，不适合自动修复

适用场景

• 代码质量分析后，可应用安全、低风险的清理时使用
• 独立运行：ln-620 代码库审计完成后（由用户手动触发）
• **定期运行：**作为代码库卫生维护的周期性“垃圾回收”

输入

• **流水线模式（ln-510）：**来自 ln-511 代码质量输出的发现（通过协调器上下文传入）
• 独立模式：docs/project/codebase_audit.md（ln-620 输出）

**必须读取：**加载 references/mcp_tool_preferences.md——有可用的 hex-line MCP 时，始终用它处理代码文件。除非 hex-line 不可用，否则不得回退到标准 Read/Edit。

**必须读取：**加载 references/mcp_integration_patterns.md。

使用 hex-line 作为处理代码文件的首选方式，使用 hex-graph 作为检查无用代码引用的首选方式。只有在相关 MCP 不可用时，才将内置 Read/Edit/Grep 作为后备方式。

工作流

1. 加载发现结果： 读取 docs/project/codebase_audit.md。从 Dead Code 部分（ln-626 结果）和 Code Quality 部分（ln-624 结果）解析发现的问题。

2. 筛选可自动修复的问题：

   • 类别必须属于上方的 Auto-Fixable 表格
   • 严重程度必须为 LOW 或 MEDIUM（不包括 HIGH/CRITICAL）
   • 工作量必须为 S（小）
   • 跳过以下文件：node_modules/、vendor/、dist/、build/、*.min.*、生成的代码、测试夹具

3. 验证每项发现（置信度检查）： 必须读取： 加载 references/clean_code_checklist.md 对每项候选修复： a) 读取指定位置的目标文件 b) 确认问题仍然存在（审计后文件可能已更改） c) 确认删除是安全的：

   • 对于未使用的导入：在代码库中 grep 使用情况（必须有 0 个引用）
   • 对于未使用的函数：grep 函数名（必须有 0 个调用点）
   • 对于注释掉的代码：确认该代码块是代码，而非文档
   • 对于不受支持的别名：确认已无使用方 d) 评定置信度（0-100）。仅当置信度 >=90 时继续

   Hex-line 加速（如可用）： 如果 Hex-line MCP 服务可用：

   • 手动清理编辑前，使用 outline(file_path) 和优先发现的 read_file()。仅在需要为 edit_file 获取修订信息/校验和时，才使用 edit_ready=true, verbosity="full" 重新读取。
   • 批量清理： 使用相同模式修复 >3 个文件时（例如，删除未使用的导入），先用 bulk_replace(dry_run=true) 预览，再用 bulk_replace() 应用。
   • 已验证的编辑： 每次修复后，运行 verify(file_path, checksums) 确认状态未过期。
   • 语义死代码检查： 删除导出项、包装器、别名或垫片前，使用 find_references()。
   • 只有在相关 MCP 不可用时，才回退到逐文件使用 Edit 或 Grep。

4. 应用修复，并逐项决定保留或丢弃（autoresearch 模式）： 必须读取： 加载 references/ci_tool_detection.md，了解工具发现层级。检测 lint 和 typecheck 命令一次，并在所有修复中复用。

   按文件对已验证的修复分组。逐个文件处理（每个文件独立处理）：

   • 按行号降序排列该文件中的修复（从底部向上，避免行号偏移）
   • 使用 Edit 工具应用该文件的所有修复
   • 对修改后的文件运行 lint/typecheck
   • 如果通过 → git add {file}（状态：保留）
   • 如果失败 → git checkout -- {file}（状态：丢弃），记录丢弃的修复
   • 逐项跟踪：文件、删除的行、类别、发现 ID、状态（保留/丢弃）

   如果未检测到 lint/type 命令：应用所有修复，跳过逐文件验证并给出警告，使用 git add 添加所有已修改文件。

5. 创建提交（仅包含保留的修复）：

   • 第 4 步中已通过 git add暂存所有保留的文件
   • 如果保留的文件数为 0（全部丢弃）：跳过提交，报告所有失败项
   • 提交消息格式：

     chore: automated tech debt cleanup
     
     Removed {N} auto-fixable findings from codebase audit:
     - {count} unused imports
     - {count} dead functions
     - {count} commented-out code blocks
     - {count} unsupported aliases
     
     Source: docs/project/codebase_audit.md
     Confidence threshold: >=90%
     

6. 更新审计报告：

   • 在 docs/project/codebase_audit.md 中添加 "Last Cleanup" 部分：

     ## Last Automated Cleanup
     **Date:** YYYY-MM-DD
     **Findings fixed:** N of M auto-fixable
     **Skipped:** K (confidence <90% or verification failed)
     **Build check:** PASSED / SKIPPED
     

输出格式

verdict: CLEANED | NOTHING_TO_CLEAN | ALL_DISCARDED
stats:
  total_findings: {from audit}
  auto_fixable: {filtered count}
  kept: {files that passed lint/typecheck}
  discarded: {files that failed lint/typecheck}
  skipped: {confidence <90 or stale}
fixes:
  - file: "src/utils/helpers.ts"
    line: 45
    category: "unused_function"
    removed: "formatDate()"
    finding_id: "MNT-DC-003"
    status: "keep"
  - file: "src/api/v1/auth.ts"
    line: 12
    category: "unsupported_alias"
    removed: "export { newAuth as oldAuth }"
    finding_id: "MNT-DC-007"
    status: "discard"
    discard_reason: "typecheck failed: Type error in auth.ts:15"
commit_sha: "abc1234" | null

关键规则

• 安全第一： 置信度低于 90% 时绝不修复。如有疑问，请跳过。
• 自底向上编辑： 始终从文件底部向上应用修复，避免行号偏移。
• 逐文件保留或还原： 如果某个文件未通过代码检查器或类型检查器，仅还原该文件（git checkout -- {file}），保留其他成功修改的文件。
• 不涉及业务逻辑： 绝不修改函数体、条件语句或控制流。
• 明确暂存： 按文件名暂存文件，绝不使用 git add . 或 git add -A。
• 幂等： 如果审核报告未更改，运行两次不会产生任何改动。
• 感知 Git： 仅操作已跟踪文件。跳过未跟踪或已忽略的文件。
• 排除项： 跳过生成的代码、供应商目录、压缩文件和测试夹具。

运行时摘要产物

必须读取： 加载 references/quality_summary_contract.md、references/quality_worker_runtime_contract.md

运行时配置：

• 系列：quality-worker
• 工作器：ln-512
• 摘要类型：quality-worker
• 协调器使用的载荷字段：worker、status、verdict、issues、warnings、artifact_path

调用规则：

• 独立运行：省略 runId 和 summaryArtifactPath
• 受管运行：传入 runId 和确切的 summaryArtifactPath
• 始终在最终结果前写入已验证的摘要

完成定义

• 已加载并解析审核报告
• 已筛选出可自动修复类别中的问题
• 已确认每个问题的置信度 >=90%
• 已按文件自底向上应用修复
• 已验证构建完整性（代码检查 + 类型检查），或跳过并附上警告
• 已创建单个提交，并使用结构化消息（或在构建失败时全部还原）
• 已在审核报告中更新“上次自动清理”部分
• 已向调用方返回 YAML 输出

参考文件

• 整洁代码检查清单： references/clean_code_checklist.md
• 审核输出架构： references/audit_output_schema.md
• 审核报告模板： references/templates/codebase_audit_template.md

---

版本： 1.0.0 最后更新： 2026-02-15