finding-duplicate-functions

查找意图重复的函数

概述

由 LLM 生成的代码库会不断积累语义重复：多个函数用途相同，却是独立实现的。传统的复制粘贴检测工具（jscpd）可以找到语法重复，但无法发现“意图相同、实现不同”的情况。

此技能采用两阶段方法：先进行传统提取，再通过 LLM 对意图进行聚类。

适用场景

• 代码库经过多个贡献者（人类或 LLM）的持续开发而逐渐扩展
• 怀疑实用函数被重复实现多次
• 在重大重构前，寻找整合机会
• 已运行 jscpd 并处理完语法重复之后

快速参考

阶段	工具	模型	输出
1. 提取	scripts/extract-functions.sh	-	catalog.json
2. 分类	scripts/categorize-prompt.md	haiku	categorized.json
3. 拆分	scripts/prepare-category-analysis.sh	-	categories/*.json
4. 检测	scripts/find-duplicates-prompt.md	opus	duplicates/*.json
5. 报告	scripts/generate-report.sh	-	report.md

流程

digraph duplicate_detection {
  rankdir=TB;
  node [shape=box];

  extract [label="1. Extract function catalog\n./scripts/extract-functions.sh"];
  categorize [label="2. Categorize by domain\n(haiku subagent)"];
  split [label="3. Split into categories\n./scripts/prepare-category-analysis.sh"];
  detect [label="4. Find duplicates per category\n(opus subagent per category)"];
  report [label="5. Generate report\n./scripts/generate-report.sh"];
  review [label="6. Human review & consolidate"];

  extract -> categorize -> split -> detect -> report -> review;
}

阶段 1：提取函数目录

./scripts/extract-functions.sh src/ -o catalog.json

选项：

• -o FILE：输出文件（默认：标准输出）
• -c N：要捕获的上下文行数（默认：15）
• -t GLOB：文件类型（默认：*.ts,*.tsx,*.js,*.jsx）
• --include-tests：包含测试文件（默认排除）

默认排除测试文件（*.test.*、*.spec.*、__tests__/**），因为测试工具函数不太可能成为整合对象。

阶段 2：按领域分类

使用 scripts/categorize-prompt.md 中的提示词，调度一个 haiku 子 Agent。

将 catalog.json 的内容插入提示词模板中指定的位置。将输出保存为 categorized.json。

阶段 3：拆分为类别

./scripts/prepare-category-analysis.sh categorized.json ./categories

每个类别会生成一个 JSON 文件。只有包含 3 个或更多函数的类别才值得分析。

阶段 4：查找重复项（按类别）

对 ./categories/ 中的每个类别文件，使用 scripts/find-duplicates-prompt.md 中的提示词，调度一个 opus 子 Agent。

将每个输出保存为 ./duplicates/{category}.json。

阶段 5：生成报告

./scripts/generate-report.sh ./duplicates ./duplicates-report.md

生成一份按置信度分组、按优先级排序的 Markdown 报告。

阶段 6：人工审核

审核报告。对于置信度为 HIGH 的重复项：

1. 确认建议保留的函数已有测试
2. 更新调用方，使其使用保留的函数
3. 删除重复函数
4. 运行测试

高风险重复区域

优先从以下区域开始提取，这些区域最容易快速积累重复项：

区域	常见重复项
utils/、helpers/、lib/	重复实现通用实用函数
验证代码	以不同方式编写的相同检查
错误格式化	错误到字符串的转换
路径操作	拼接、解析、规范化路径
字符串格式化	大小写转换、截断、转义
日期格式化	反复实现相同的格式
API 响应整形	针对不同端点进行相似转换

常见错误

提取过多：重点关注导出函数和公共方法。内部辅助函数不太可能在多个文件中重复。

跳过分类步骤：直接对完整目录进行重复检测会产生大量噪声。按类别划分可以聚焦比较范围。

使用 haiku 检测重复项：Haiku 适合以较低成本进行分类，但会漏掉细微的语义重复。实际的重复分析请使用 Opus。

在没有测试的情况下进行整合：删除重复函数前，请确保保留的函数有测试覆盖已删除函数的所有用例。