| name | check-duplication-cmd |
| version | 1.1.0 |
| description | 当用户提到'重复代码'、'重复检查'、'代码重复'、'check-duplication'、'重复检测'、'提取共享库'、'DRY检查'、'代码复用检查'、'脚本重复'时，必须使用此技能。提供跨文件重复代码自动检测能力：扫描.agents/scripts/目录下的Python脚本，使用N元语法指纹识别跨文件重复代码块（默认≥10行），输出重复位置、行数和建议提取到共享库的位置。新增.agents/scripts/脚本前必须运行此检查，禁止重复实现已有功能。不要手动凭肉眼找重复——本工具通过归一化代码指纹精确识别，连变量名不同但逻辑相同的'变形重复'也能检测到。 |
| argument-hint | [--threshold N] [--path <dir>] [--json] |
| user-invocable | true |
| paths | [".agents/scripts/check-duplication.py",".agents/scripts/lib/",".agents/scripts/lib/README.md"] |
| title | 跨文件重复代码检查命令 Skill |
| x-toml-ref | ../../../.meta/toml/.agents/skills/check-duplication-cmd/SKILL.toml |
跨文件重复代码检查命令 Skill
⚠️ 本Skill是脚本命令门面（L1索引层），遵循渐进式披露三层架构：
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输出 | 集成到其他工具/CI | python .agents/scripts/check-duplication.py --json |
5. 核心执行步骤
5.1 常规检查（提交新脚本前必跑）
python .agents/scripts/check-duplication.py
结果解读：
- ✅ 输出
PASS（无重复或重复<阈值）→ 可以提交
- ⚠️ 输出WARN并列出重复块 → 按§5.3处理
5.2 精细检查（重构优化时）
python .agents/scripts/check-duplication.py --threshold 5
为什么默认阈值是10行？ 实践中5-9行的重复大多是模板代码（参数解析、错误处理样板），强行提取反而增加抽象成本、降低可读性。10行以上的重复才有提取价值——既保证复用收益，又避免过度抽象。
5.3 处理重复代码的标准流程
- 阅读检测报告：定位重复块涉及的文件和行号
- 查阅共享库索引：先读 .agents/scripts/lib/README.md，确认是否已有可直接复用的函数
- 提取到共享库：如果lib/中没有对应函数，将重复逻辑提取到lib/下合适的模块：
- 路径解析、frontmatter解析 →
lib/markdown.py
- CLI输出、参数解析 →
lib/cli.py
- 项目根目录解析 →
lib/project.py
- 规则加载、误报过滤 →
lib/rules.py
- 修改原文件：替换重复代码为共享库函数调用
- 重新验证：再次运行check-duplication确认重复已消除
- 跑全量CI：用ci-check-cmd确认没有引入其他问题
为什么提取到lib/而非新建util文件？ 集中式共享库目录（lib/）配合README.md索引，可以让后续开发者快速找到可复用函数。分散的util文件容易导致"util本身的重复"——多个util文件又包含相似的辅助函数。
6. 自动排除规则
工具自动跳过以下目录和文件，避免误报：
| 排除对象 | 原因 |
|---|
lib/ 目录 | 共享库本身是"被复用"的，不应检测内部重复 |
tests/ 目录 | 测试代码的重复是有意的（每个测试独立） |
config/ 目录 | 配置文件通常是声明性数据，非逻辑代码 |
| 规则定义的排除行 | 如shebang行、编码声明行等模板代码 |
7. 安全检查清单（执行前确认）
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-cmd | ci-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，支持跨文件重复代码检测。
