ln-623-code-principles-auditor

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

代码原则审计员（L3 Worker）

类型： L3 Worker

专门审计代码原则（DRY、KISS、YAGNI）和设计模式的工作器。

目的与范围

• 审计代码原则（DRY/KISS/YAGNI、错误处理、DI）
• 返回包含严重性、位置、工作量、pattern_signature 和建议的结构化发现
• 计算代码原则类别的合规评分（X/10）

输入

必须读取： 加载 references/audit_worker_core_contract.md。 工具策略：遵循宿主 AGENTS.md 中的 MCP 偏好；仅当宿主策略缺失或 MCP 行为不明确时，才加载 references/mcp_tool_preferences.md 和 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，以供 ln-620 进行跨领域匹配
7. 使用惩罚算法计算分数
8. **撰写报告：**根据 references/templates/audit_worker_report_template.md 在内存中构建完整的 markdown 报告，然后通过单次 Write 调用写入 {output_dir}/ln-623--{domain}.md（或全局模式下的 623-principles.md）。包含带有 pattern_signature 字段的 JSON 块，以支持跨领域 DRY 分析
9. **返回摘要：**向协调器返回最简摘要（参见输出格式）

两层检测

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

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

发现类型	第 2 层降级示例
DRY	生命周期/所有权不同的模块 -> 跳过。为实现解耦而有意进行的重复 -> 跳过
KISS	框架要求的抽象（例如 Spring 中的 DI）-> 降级。当前只有一个实现，但接口用于测试 -> 跳过
YAGNI	用于 A/B 测试的功能标志 -> 跳过。运维团队使用的配置选项 -> 跳过
错误处理	50 行脚本中没有集中式处理器 -> 降级为 LOW
DI	可通过参数/闭包替换依赖 -> 跳过 ARCH-DI

审计规则

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 -> 统计子类数量	高：阻碍理解核心逻辑	用于依赖注入/测试的接口 -> 跳过。框架要求（Spring、ASP.NET）-> 跳过	移除抽象，内联实现	L
少于 3 种类型的工厂	搜索工厂模式 -> 统计分支数量	中：不必要的模式	用于依赖注入/测试替换的工厂 -> 降级	改为直接构造	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 个实现的接口	搜索接口 -> 统计实现者数量	中：过早抽象	用于依赖注入/测试模拟的接口 -> 跳过	移除接口，直接使用类	M
过早使用泛型（只用于 1 种类型）	搜索泛型用法 -> 统计类型参数数量	低：过度设计	面向使用者设计的公共库 API -> 跳过	将泛型替换为具体类型	S

4. 缺少错误处理

• 查找没有 try-catch 的异步函数
• 检查没有错误处理中间件的 API 路由
• 确认数据库调用包含错误处理

严重程度	标准
严重	支付/身份验证缺少错误处理
高	面向用户的操作缺少错误处理
中	内部操作缺少错误处理

工作量： M

5. 集中式错误处理

• 搜索集中式错误处理器：ErrorHandler、errorHandler、error-handler.*
• 检查中间件是否将处理委托给错误处理器
• 确认异步路由使用 promise/async-await
• 反模式： 使用 process.on("uncaughtException")

严重程度	标准
高	没有集中式错误处理器
高	使用 uncaughtException 监听器（Express 反模式）
中	中间件直接处理错误（未委托处理）
中	异步路由缺少适当的错误处理
低	在生产环境中暴露堆栈跟踪

目标结果： 所有错误都会连同上下文一起记录，并返回清晰、面向用户的消息。不会静默吞掉任何错误。堆栈跟踪绝不会泄露到生产环境响应中。具体实现方式（ErrorHandler 类、中间件、装饰器）取决于项目所用的技术栈和规模。

工作量： M-L

6. 依赖注入 / 集中初始化

• 检查是否有 DI 容器：inversify、awilix、tsyringe（Node）、dependency_injector（Python）、Spring @Autowired（Java）、ASP.NET IServiceCollection（C#）
• 搜索业务逻辑中的 new SomeService()（直接实例化）
• 检查引导模块：bootstrap.ts、init.py、Startup.cs、app.module.ts

严重程度	标准
MEDIUM	没有 DI 容器（耦合紧密）
MEDIUM	在业务逻辑中直接实例化
LOW	混合使用 DI 和直接导入

目标结果： 无需修改生产代码即可替换依赖以进行测试。服务实例化与业务逻辑之间没有紧密耦合。具体实现方式（DI 容器、工厂函数、参数注入、闭包）取决于项目规模和技术栈。

工作量： L

7. 缺少最佳实践指南

• 检查是否存在：docs/architecture.md、docs/best-practices.md、ARCHITECTURE.md、CONTRIBUTING.md

严重程度	标准
LOW	没有架构 / 最佳实践指南

建议： 创建 docs/architecture.md，说明分层规则、错误处理模式、DI 用法和编码规范。

工作量： S

评分算法

必须阅读： 加载 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: "Architecture & Design"。

FINDINGS-EXTENDED 块（此工作器必需）： 在 Findings 表之后，添加一个 `` JSON 块，其中包含所有带有 pattern_signature 的 DRY 发现，以便 ln-620 协调器进行跨域匹配。请遵循 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 小时
• 排除项： 跳过生成的代码、vendor、迁移文件（参见 detection_patterns.md#exclusions）

完成定义

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

• 已解析 contextStore（包括 domain_mode、current_domain、output_dir）
• 已确定 scan_path（领域路径或代码库根目录）
• 已从 references/detection_patterns.md 加载检测模式
• 已完成全部 7 项检查（范围限定为 scan_path）：
  • DRY（10 个子类别：1.1-1.10）、KISS、YAGNI、错误处理、集中式错误处理、DI/初始化、最佳实践指南
• 已通过 references/refactoring_decision_tree.md 选定建议
• 已收集包含 severity、location、effort、pattern_id、pattern_signature、recommendation、domain 的发现项
• 已根据 references/audit_scoring.md 计算评分
• 已将报告写入 {output_dir}/ln-623--{domain}.md，其中包含 FINDINGS-EXTENDED 块（通过单次 Write 调用原子写入）
• 已根据契约写入摘要

参考文件

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

---

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