Skip to content

xinetzone/SpecWeave / .agents/skills/check-duplication-cmd

check-duplication-cmd

Verified

当用户提到'重复代码'、'重复检查'、'代码重复'、'check-duplication'、'重复检测'、'提取共享库'、'DRY检查'、'代码复用检查'、'脚本重复'时,必须使用此技能。提供跨文件重复代码自动检测能力:扫描.agents/scripts/目录下的Python脚本,使用N元语法指纹识别跨文件重复代码块(默认≥10行),输出重复位置、行数和建议提取到共享库的位置。新增.agents/scripts/脚本前必须运行此检查,禁止重复实现已有功能。不要手动凭肉眼找重复——本工具通过归一化代码指纹精确识别,连变量名不同但逻辑相同的'变形重复'也能检测到。

跨文件重复代码检查命令 Skill

⚠️ 本Skill是脚本命令门面(L1索引层),遵循渐进式披露三层架构:

  • L0:.agents/ONBOARDING.md(入口速查)
  • L1:本文件(<500行,触发词+核心步骤+安全清单)
  • L2:脚本源码 --help 输出完整参数说明 + lib/README.md(共享库索引)

1. Skill ID

check-duplication-cmd

2. 功能描述

跨文件重复代码自动化检测工具,用于维护 .agents/scripts/ 目录的DRY原则(Don't Repeat Yourself):

特性说明
扫描范围.agents/scripts/ 下所有 .py 文件(自动排除 lib/、tests/、config/ 目录)
检测算法归一化代码(去注释/空行、标准化空白)→ 滑动窗口N元语法 → SHA256指纹比对
默认阈值≥10行重复才报告(避免误报短片段如import语句)
"变形重复"检测归一化后变量名差异不影响指纹计算,能识别逻辑相同但命名不同的重复
输出内容重复块位置(文件+行号)、重复行数、归一化预览、建议提取位置
操作性质🔒 纯只读检查,不修改任何文件,幂等(多次运行结果一致)

为什么用本Skill而非肉眼审查? 肉眼找重复代码有三个盲区:一是"变形重复"看不出来(两个脚本写了相同逻辑但变量名/缩进不同);二是新增脚本时很难记得lib/里哪些函数已经存在;三是逐文件比对效率极低。本工具通过代码指纹技术精确识别跨文件重复,默认阈值10行过滤了import语句等模板代码的误报,输出结果直接指向应提取到lib/的具体位置。

3. 何时使用本技能

必用场景

  • 新增 .agents/scripts/ Python脚本后:提交前必须运行,确认未重复实现已有功能
  • 修改脚本时:重构后检查是否引入了新的重复
  • CI流水线步骤6:ci-check-cmd全量检查时自动调用
  • 考虑提取共享函数前:先用本工具确认重复范围和涉及文件

触发词

  • "重复代码"、"重复检查"、"代码重复"、"check-duplication"
  • "重复检测"、"提取共享库"、"DRY检查"
  • "代码复用检查"、"脚本重复"

4. 方案选择决策树

需要检查重复代码?
├─ 新增脚本后常规检查 → 默认模式(阈值10行)
├─ 想找更细粒度的重复 → --threshold 5(5行以上即报告)
├─ 检查其他目录(非scripts/) → --path <dir>
└─ 需要JSON输出供其他工具消费 → --json

⚠️ 强制:触发时记录输入参数日志

决策前输出CMD_START日志(session前缀 dup-YYYYMMDD-<topic>):

[CMD-LOG] | level=INFO | cmd=check-duplication | step=S0 | event=CMD_START | session=dup-... | msg=开始重复代码检测:<简述> | ctx={"target_dir":"...","threshold":10}

为什么决策前必须记录日志? 重复代码检测可能误报或漏报,CMD_START记录扫描目录和阈值便于排查检测结果问题。

方案适用场景命令
常规检查 ⭐新增/修改脚本后标准检查python .agents/scripts/check-duplication.py
精细检查重构时找可提取的短重复片段python .agents/scripts/check-duplication.py --threshold 5
自定义路径检查scripts以外的目录python .agents/scripts/check-duplication.py --path <目录路径>
JSON输出集成到其他工具/CIpython .agents/scripts/check-duplication.py --json

5. 核心执行步骤

5.1 常规检查(提交新脚本前必跑)

python .agents/scripts/check-duplication.py

结果解读:

  • ✅ 输出 PASS(无重复或重复<阈值)→ 可以提交
  • ⚠️ 输出WARN并列出重复块 → 按§5.3处理

5.2 精细检查(重构优化时)

# 阈值5行,捕获更小的可复用片段
python .agents/scripts/check-duplication.py --threshold 5

为什么默认阈值是10行? 实践中5-9行的重复大多是模板代码(参数解析、错误处理样板),强行提取反而增加抽象成本、降低可读性。10行以上的重复才有提取价值——既保证复用收益,又避免过度抽象。

5.3 处理重复代码的标准流程

  1. 阅读检测报告:定位重复块涉及的文件和行号
  2. 查阅共享库索引:先读 .agents/scripts/lib/README.md,确认是否已有可直接复用的函数
  3. 提取到共享库:如果lib/中没有对应函数,将重复逻辑提取到lib/下合适的模块:
    • 路径解析、frontmatter解析 → lib/markdown.py
    • CLI输出、参数解析 → lib/cli.py
    • 项目根目录解析 → lib/project.py
    • 规则加载、误报过滤 → lib/rules.py
  4. 修改原文件:替换重复代码为共享库函数调用
  5. 重新验证:再次运行check-duplication确认重复已消除
  6. 跑全量CI:用ci-check-cmd确认没有引入其他问题

为什么提取到lib/而非新建util文件? 集中式共享库目录(lib/)配合README.md索引,可以让后续开发者快速找到可复用函数。分散的util文件容易导致"util本身的重复"——多个util文件又包含相似的辅助函数。

6. 自动排除规则

工具自动跳过以下目录和文件,避免误报:

排除对象原因
lib/ 目录共享库本身是"被复用"的,不应检测内部重复
tests/ 目录测试代码的重复是有意的(每个测试独立)
config/ 目录配置文件通常是声明性数据,非逻辑代码
规则定义的排除行如shebang行、编码声明行等模板代码

7. 安全检查清单(执行前确认)

  • 明确检查目标:是新增脚本后常规检查,还是重构时找可提取片段?
  • 常规检查使用默认阈值10行,不要随意降低到<5行(会产生大量模板代码误报)
  • 处理重复前先查阅 lib/README.md,避免重复提取已有函数
  • 提取到共享库的函数必须有清晰的docstring说明用途、参数、返回值
  • 消除重复后重新运行检查确认通过,再跑ci-check-cmd全量验证
  • 🔒 本工具是只读检查,不会修改文件,可安全重复执行

8. 常见错误处理

场景说明处理方式
报告import语句重复多个文件有相同的import块正常现象,低于阈值不报告;如≥10行import重复,检查是否有不必要的import
误报相似但不同的逻辑算法把相似但不同的代码判为重复查看normalized_preview,确认是否真的是逻辑重复;如果只是结构相似但语义不同,可在lib/rules.py添加排除规则
检测到lib/外已有可复用函数新脚本重复实现了lib/中的功能直接import使用lib/中的函数,删除重复实现
共享库中没有对应函数确实是新的重复模式在lib/下合适模块添加共享函数,更新lib/README.md索引

9. Gotchas(陷阱与反直觉行为)

为什么需要Gotchas? 错误处理记录"已知错误码及修复方式",Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。

  • 重复检测基于N元语法指纹:检测算法会先对代码进行归一化处理(去除注释、空行、标准化空白),然后计算滑动窗口的SHA256指纹。这意味着即使变量名不同、注释不同,只要逻辑结构相同("变形重复")也能被检测到——不要以为改变量名就能绕过检测。
  • 默认阈值≥10行:短于10行的代码片段重复不会报警,这是有意设计——5-9行的重复大多是import语句、参数解析样板等模板代码,强行提取反而增加抽象成本。不要为了追求"零重复"而把阈值降到5以下,会产生大量误报。
  • 检测范围仅限.agents/scripts/目录:本工具只扫描.agents/scripts/下的Python脚本,不检测业务代码、文档、其他Skill目录下的文件。不要用它来检查业务项目中的重复代码,需要检测其他目录时用--path参数指定。
  • 新增脚本前必须运行此检查:在.agents/scripts/下新增Python脚本后,提交前必须运行check-duplication,禁止重复实现已有功能。如果lib/中已有相同逻辑,直接import复用;如果确实需要新函数,先提取到lib/再使用。
  • 归一化处理会忽略注释和空行:纯注释差异、空行位置差异不会影响指纹计算——不要以为加了不同注释就不算重复。判断是否重复的唯一标准是归一化后的代码逻辑是否相同,注释和空行只是排版,不影响重复判定。

10. 与其他Skill的协作

协作场景配合Skill协作方式
CI全量检查ci-check-cmdci-check步骤6自动调用check-duplication
新增脚本开发开发者角色写脚本时随时查lib/README.md,写完先跑本检查
原子化收尾atomization-finalize-cmd原子化后如果新增了脚本,需跑本检查验证无重复

11. Changelog

  • v1.1.0 (2026-07-01): 在§4决策树后添加S0 CMD_START强制日志规范,记录触发时的输入参数(target_dir/threshold)便于排查检测结果问题。
  • v1.0.0 (2026-06-30): 初始版本,基于check-duplication.py脚本封装为命令门面Skill,支持跨文件重复代码检测。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall