ln-623-duplication-overabstraction-auditor

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

重复与过度抽象审计器（L3 Worker）

类型： L3 Worker

专门审计重复、过度抽象和未使用的可扩展性。

目的与范围

• 审计重复与过度抽象（DRY/KISS/YAGNI）
• 返回包含严重程度、位置、工作量、pattern_signature 和建议的结构化发现
• 发出 MERGE_DUPLICATION、REMOVE_ABSTRACTION 或 REMOVE_YAGNI
• 计算“重复与过度抽象”类别的合规评分（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。

接收包含以下内容的 contextStore：tech_stack、best_practices、principles、codebase_root、output_dir。

领域感知： 支持 domain_mode + current_domain（参见 audit_output_schema.md#domain-aware-worker-output）。

当克隆组、实现或语义关系能显著提升审计效果时，优先使用 hex-graph。在本地代码读取方面，若 hex-line 可用，则优先使用。若 MCP 不可用、不受支持或未建立索引，则继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明回退情况。

工作流

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

1. 解析上下文 -- 提取字段，确定 scan_path（如指定，则根据领域确定），提取 output_dir
2. 加载检测模式
   • 必须阅读： 加载 references/detection_patterns.md，获取特定语言的 Grep/Glob 模式
   • 选择与项目 tech_stack 匹配的模式
3. 扫描代码库以查找违规项（第 1 层）
   • 所有 Grep/Glob 模式都使用 scan_path（而不是 codebase_root）
   • 图加速（如可用）： 如果 contextStore.graph_indexed 或 .hex-skills/codegraph/index.db 存在：
     • DRY（1.1-1.10）： audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3) -- 每个返回的克隆组都是一个 DRY 候选项。仅在有意深入调查时提高限制。使用克隆类型和热点上下文进行严重性分级。如不可用，则回退到 grep 模式。
     • KISS 继承： 对抽象类使用 find_implementations(symbol) -- 统计实现数量（1 个 = KISS 候选项）。通过图追踪继承深度。
     • 复杂度： audit_workspace(path=scan_path, verbosity="minimal", limit=5) -- 使用返回的热点，预先识别用于 KISS/质量分析的复杂函数。仅在有意深入调查时提高 limit。
     • 先查看大纲再阅读： 阅读大型源文件之前先运行 outline(file_path) -- 先了解结构，再分析原则。
   • 按照 detection_patterns.md 中的分步检测流程操作
   • 应用 detection_patterns.md#exclusions 中的排除规则
4. 按候选项分析上下文（第 2 层）
   • DRY：阅读两处代码块，确认确实重复（而非仅命名相似或共享接口）
   • KISS：检查抽象是否用于 DI 模式（有效的单实现接口），还是过早抽象
   • YAGNI：检查功能标志是最近添加的（有意为之），还是已闲置数月
5. 生成建议
   • 必须阅读： 加载 references/refactoring_decision_tree.md 以选择模式
   • 通过决策树，将每条发现与适当的重构模式匹配
6. 收集发现项及其严重性、位置、工作量、pattern_id、pattern_signature 和建议
   • 如果采用领域感知模式，为每条发现添加 domain: domain_name 标签
   • 为每条发现分配 pattern_signature，用于受管理的聚合
7. 使用惩罚算法计算分数
8. 编写报告： 根据 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-623--{domain}.md（或全局模式下的 623-principles.md）。包含 `` JSON 块，其中带有用于跨领域 DRY 分析的 pattern_signature 字段
9. 返回摘要： 返回最简摘要（参见输出格式）

两层检测

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

所有发现项都必须经过第 2 层上下文分析。仅有第 1 层发现而没有第 2 层分析 = 无效发现。报告之前，请先问：“此违规是有意为之，还是有设计上的合理依据？”

发现类型	第 2 层降级示例
DRY	生命周期/所有权不同的模块 -> 跳过。为实现解耦而有意重复 -> 跳过
KISS	框架要求的抽象（例如 Spring 中的 DI）-> 降级。目前只有一种实现，但接口用于测试 -> 跳过
YAGNI	用于 A/B 测试的功能标志 -> 跳过。运维团队使用的配置选项 -> 跳过

审计规则

1. DRY 违规（不要重复自己）

必须阅读： 加载 references/detection_patterns.md，了解各类型的检测步骤。

类型	内容	严重程度	例外（跳过/降低级别）	默认建议	工作量
1.1 相同代码	在多个文件中重复相同的函数/常量/代码块（>10 行）	高：业务关键代码（身份验证、支付）。中：实用工具。低：简单常量，少于 5 处	生命周期/所有权不同的模块 -> 跳过。刻意解耦 -> 跳过	提取函数 -> 根据重复范围决定放置位置	M
1.2 重复的校验逻辑	在多个文件中重复相同的校验模式（电子邮件、密码、电话、URL）	高：身份验证/支付。中：用户输入，3 处以上。低：格式检查，少于 3 处	安全上下文不同（身份验证与公开场景） -> 跳过	提取到共享校验器模块	M
1.3 重复的错误消息	使用硬编码错误字符串，而非集中管理的目录	中：关键消息采用硬编码或没有错误目录。低：少于 3 处	需要根据上下文调整措辞的面向用户的字符串 -> 降低级别	创建常量/错误消息文件	M
1.4 相似模式	调用顺序/控制流相同，但名称/实体不同的函数	中：关键路径中的业务逻辑。低：少于 3 处的实用工具	预期会独立演进的模块 -> 跳过	提取共用逻辑（根据模式参见决策树）	M
1.5 重复的 SQL/ORM	不同服务中存在相同查询	高：支付/身份验证查询。中：常见查询，3 处以上。低：简单查询，少于 3 处	有界上下文不同；共享数据库比重复更糟 -> 跳过	提取到 Repository 层	M
1.6 复制粘贴的测试	不同测试文件中存在相同的设置/清理/固定数据	中：在 5 个以上文件中设置。低：少于 5 个文件	为了清晰/独立而刻意隔离的测试 -> 降低级别	提取到测试辅助工具	M
1.7 重复的 API 响应	没有 DTO 时，响应对象具有相同的结构	中：在 5 个以上端点中。低：少于 5 个端点	版本演进周期不同的响应 -> 跳过	创建 DTO/Response 类	M
1.8 重复的中间件链	多个路由使用相同的中间件/装饰器堆栈	中：5 个以上路由使用相同链。低：少于 5 个路由	身份验证/速率限制要求不同的路由 -> 跳过	创建命名中间件组，并在路由器层应用	M
1.9 重复的类型定义	字段有 80% 以上相同的接口/结构体/类型	中：在 5 个以上文件中。低：2–4 个文件	所有权/演进路径不同的类型 -> 跳过	创建共享基类型，并在需要时扩展	M
1.10 重复的映射逻辑	多个位置存在相同的实体->DTO / DTO->实体转换	中：在 3 个以上位置。低：2 个位置	校验/丰富规则不同的映射 -> 跳过	创建专用的 Mapper 类/函数	M

选择建议： 使用 references/refactoring_decision_tree.md，根据重复代码的位置（第 1 层）和逻辑类型（第 2 层）选择合适的重构模式。

2. KISS 违规（保持简单，傻瓜）

违规项	检测方法	严重性	例外（跳过／降级）	建议	工作量
抽象类只有 1 个实现	搜索 abstract class -> 统计子类	高：妨碍理解核心逻辑	用于 DI／测试的接口 -> 跳过。框架要求（Spring、ASP.NET） -> 跳过	移除抽象，内联实现	L
少于 3 种类型却使用工厂	搜索工厂模式 -> 统计分支	中：不必要的模式	用于 DI／测试切换的工厂 -> 降级	改为直接实例化	M
继承层级超过 3 层	追踪 extends 链	高：层级脆弱	框架要求的层级（UI 小部件、ORM 模型） -> 降级	用组合扁平化	L
泛型约束过多	搜索 <T extends ... & ...>	低：可接受的权衡	公共 API 边界的类型安全 -> 跳过	简化约束	M
仅作包装的类	阅读：所有方法都委托给内部对象	中：不必要的间接层	用于隔离外部 API 的适配器模式 -> 跳过	移除包装类，直接使用内部对象	M

3. YAGNI 违规（你不会需要它）

违规项	检测方法	严重性	例外（跳过／降级）	建议	工作量
无效功能标志（始终为 true／false）	搜索标志 -> 确认它们从未切换	低：需要清理	A/B 测试标志 -> 跳过。由运维控制的开关 -> 跳过	移除标志，保留当前生效的代码路径	M
从未被重写的抽象方法	搜索 abstract -> 查找实现	中：未使用的可扩展性	公共库中的插件／扩展点 -> 降级	移除 abstract，改为具体实现	M
未使用的配置选项	搜索配置键 -> 引用数为 0	低：无效配置	特定环境的配置（staging／prod）-> 标记前先确认	移除选项	S
接口只有 1 个实现	搜索接口 -> 统计实现类	中：过早抽象	用于 DI／测试模拟的接口 -> 跳过	移除接口，直接使用类	M
过早使用泛型（仅用于 1 种类型）	搜索泛型用法 -> 统计类型参数	低：过度设计	面向使用者设计的公共库 API -> 跳过	将泛型替换为具体类型	S

4. 证据门槛

不要报告审美偏好。只有当执行者能够展示重复代码、没有实际变化点的抽象，或会增加维护成本的未使用扩展机制时，发现的问题才有效。

问题	所需证据	操作
重复	匹配的代码块、重复的验证／查询／映射，或在多个文件中重复的 pattern_signature	MERGE_DUPLICATION
过度抽象	只有一个实际实现且没有框架／测试需求的抽象层	REMOVE_ABSTRACTION
YAGNI	当前未使用的功能标志、配置选项、泛型或扩展点	REMOVE_YAGNI

评分算法

必须阅读： 加载 references/audit_scoring.md。

输出格式

必须阅读： 加载 references/templates/audit_worker_report_template.md。

按照 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会传入 runId 和 summaryArtifactPath；在独立模式下，工作器会按照共享契约生成自己的运行级产物路径。

将报告写入 {output_dir}/ln-623--{domain}.md（或全局模式下的 623-principles.md），并设置 category: "Duplication & Over-Abstraction"。

FINDINGS-EXTENDED 块（此工作器必需）： 在 Findings 表格之后，加入一个 `` JSON 块，其中包含所有带有 pattern_signature 的 DRY 发现，以供托管聚合。遵循 references/templates/audit_worker_report_template.md。

pattern_id： DRY 类型标识符（dry_1.1 至 dry_1.10）。非 DRY 发现请省略。

pattern_signature： 检测到的模式的规范化键（例如，validation_email、sql_users_findByEmail、middleware_auth_validate_ratelimit）。多个域中出现相同签名会触发跨域 DRY 发现。格式定义见 references/detection_patterns.md。

按照 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-623--users.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

关键规则

应用已加载的 references/audit_worker_core_contract.md。

• 不要自动修复： 仅报告
• 按域扫描： 如果 domain_mode="domain-aware"，则仅扫描 scan_path
• 标记发现： 按域感知模式下，在每条发现中包含 domain 字段
• 模式签名： 每条 DRY 发现都包含 pattern_id 和 pattern_signature
• 结合上下文： 使用项目的 principles.md 确定哪些做法可接受
• 合理评估工作量： S = <1 小时，M = 1-4 小时，L = >4 小时
• 排除项： 跳过生成代码、供应商代码和迁移文件（参见 detection_patterns.md#exclusions）
• 独特审计范围： 仅审计重复、过度抽象和未使用的可扩展性。不要审计交付门禁、安全、包健康度、局部复杂度指标、架构边界或运行时生命周期。
• 必须执行操作： 每条发现都使用 MERGE_DUPLICATION、REMOVE_ABSTRACTION 或 REMOVE_YAGNI。

完成定义

应用已加载的 references/audit_worker_core_contract.md。

• 已解析 contextStore（包括 domain_mode、current_domain、output_dir）
• 已确定 scan_path（域路径或代码库根目录）
• 已从 references/detection_patterns.md 加载检测模式
• 已完成全部 3 项检查（范围限定为 scan_path）：
  • DRY（10 个子类别：1.1-1.10）、KISS、YAGNI
• 已通过 references/refactoring_decision_tree.md 选择建议
• 已收集发现及其严重程度、位置、工作量、操作、pattern_id、pattern_signature、建议和 domain
• 已按照 references/audit_scoring.md 计算评分
• 已通过单次原子 Write 调用，将带有 FINDINGS-EXTENDED 块的报告写入 {output_dir}/ln-623--{domain}.md
• 已按照契约写入摘要

参考文件

• 检测模式： references/detection_patterns.md
• 重构决策树： references/refactoring_decision_tree.md

---

版本： 5.0.0 最后更新： 2026-02-08