ln-624-code-quality-auditor

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

代码质量审计员（L3 Worker）

类型： L3 Worker

专门审计代码复杂度、方法签名、算法和常量管理的工作器。

目的与范围

• 审计代码质量（类别 5+6+新增：中优先级）
• 检查复杂度指标、方法签名质量、算法效率和常量管理
• 返回包含严重程度、位置、工作量和建议的结构化发现
• 计算代码质量类别的合规评分（X/10）

输入

必须读取： 加载 references/audit_worker_core_contract.md。 必须读取： 加载 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. 扫描代码库中的违规项（第 1 层）
   • 所有 Grep/Glob 模式都使用 scan_path（而非 codebase_root）
   • 图加速（如果可用）： 如果 contextStore.graph_indexed 为真，或 .hex-skills/codegraph/index.db 存在：
     • 复杂度 + 上帝类： audit_workspace(path=scan_path, verbosity="minimal", limit=5)——使用返回的热点预先识别复杂函数和上帝类。仅在有意深入调查时提高 limit。
     • 模块指标： analyze_architecture(path=scan_path, verbosity="full")——使用返回的耦合指标分析级联深度和耦合情况。
     • 如果图不可用，则回退到下方的 grep 模式。
     • 先查看大纲： 读取大型源文件前，先调用 outline(file_path)——了解函数/类结构，以便分析复杂度。
   • 示例：使用 Grep(pattern="if.*if.*if", path=scan_path) 检测嵌套
3. 逐个候选项分析上下文（第 2 层——必须执行） 第 1 层的发现若未经过第 2 层分析，则不是有效发现。报告前先问：“此违规是有意为之，还是有设计上的合理依据？”
   • 圈复杂度：复杂度来自对枚举的 switch/case（合理）还是深度嵌套的条件判断（不合理）？枚举分派 -> 降至低优先级或跳过
   • O(n^2)：读取上下文——n 是多少？如果有界（n < 100），则降低严重程度
   • N+1：读取 ORM 配置——其他位置是否配置了预加载？仅供管理员使用的端点 -> 降低严重程度
   • 上帝类：是否为配置/模式/构建器类？-> 降低严重程度
   • 级联深度：已追踪调用（隐含第 2 层）。编排函数不适用 SEB（参见 ARCH-AI-SEB 中的冲突解决）
4. 收集发现，包含严重程度、位置、工作量和建议
   • 为每项发现添加 domain: domain_name 标签（如为领域感知模式）
5. 使用扣分算法计算评分
6. 编写报告： 根据 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-624--{domain}.md（或全局模式下的 624-quality.md）
7. 返回摘要： 向协调器返回最简摘要（参见输出格式）

审计规则（优先级：中）

1. 圈复杂度

含义： 单个函数中的决策点过多（> 10）

检测：

• 统计 if/else、switch/case、三元运算符、&&、||、for、while
• 使用工具：eslint-plugin-complexity、radon（Python）、gocyclo（Go）

严重程度：

• HIGH： 复杂度 > 20（极难测试）
• MEDIUM： 复杂度 11-20（建议重构）
• LOW： 复杂度 8-10（可以接受，但需监控）
• 降低级别的情况： 枚举/switch 分发、状态机、解析器语法 -> 降至 LOW 或跳过

建议： 拆分函数、提取辅助方法、使用提前返回

工作量： M-L（取决于复杂度）

2. 嵌套过深（> 4 层）

含义： if/for/while 块嵌套过深

检测：

• 统计缩进层级
• 模式：if { if { if { if { if { ... } } } } }

严重程度：

• HIGH： > 6 层（难以阅读）
• MEDIUM： 5-6 层
• LOW： 4 层
• 降低级别的情况： 因提前返回的守卫子句造成的嵌套（结构上层级较深，但逻辑是线性的）-> 降低级别

建议： 提取函数、使用守卫子句、反转条件

工作量： M（重构结构）

3. 方法过长（> 50 行）

含义： 函数过长，承担的工作过多

检测：

• 统计函数起始到结束之间的行数
• 排除注释和空行

严重程度：

• HIGH： > 100 行
• MEDIUM： 51-100 行
• LOW： 40-50 行（处于临界范围）
• 降低级别的情况： 依次委派任务的编排函数；数据转换流水线 -> 降低级别

建议： 拆分成更小的函数，遵循单一职责原则

工作量： M（提取逻辑）

4. 上帝类/模块（> 500 行）

含义： 文件承担的职责过多

检测：

• 统计文件行数（排除注释）
• 检查公共方法/函数的数量

严重程度：

• HIGH： > 1000 行
• MEDIUM： 501-1000 行
• LOW： 400-500 行
• 降低级别的情况： 配置/架构/迁移文件、生成的代码、barrel/index 文件 -> 跳过

建议： 拆分成多个文件，遵循关注点分离原则

工作量： L（大规模重构）

5. 参数过多（> 5）

含义： 函数的参数过多

检测：

• 统计函数参数
• 检查构造函数和方法

严重程度：

• MEDIUM： 6-8 个参数
• LOW： 5 个参数（处于临界范围）
• 降低级别的情况： 使用 Builder/options 模式的构造函数；框架要求的签名（中间件、钩子）-> 跳过

建议： 使用参数对象、Builder 模式、默认参数

工作量： S-M（重构签名及调用）

6. O(n^2) 或更差的算法

含义： 对集合进行嵌套循环，效率低下

检测：

• 嵌套 for 循环：for (i) { for (j) { ... } }
• 嵌套数组方法：arr.map(x => arr.filter(...))

严重程度：

• HIGH： 热路径中出现 O(n^2)（API 请求处理程序）
• MEDIUM： 偶尔执行的操作中出现 O(n^2)
• LOW： 小型数据集（n < 100）中的 O(n^2)
• 降低级别的情况： n 有上限（领域保证 n < 100）；一次性初始化/迁移代码 -> 降至 LOW 或跳过

建议： 使用哈希映射，通过单次遍历优化，使用更合适的数据结构

工作量： M（重新设计算法）

7. N+1 查询模式

含义： ORM 延迟加载导致 N+1 查询

检测：

• 查找循环内包含数据库查询的代码
• 检查 ORM 模式：users.forEach(u => u.getPosts())

严重程度：

• CRITICAL： API 端点中出现 N+1（性能灾难）
• HIGH： 高频操作中出现 N+1
• MEDIUM： 管理面板中出现 N+1
• 降低级别的情况： 仅供管理员使用且每天调用次数 <=1 的端点 -> 降至 LOW。ORM 在其他位置已配置预加载 -> 跳过

建议： 使用预加载、批量查询、JOIN

工作量： M（更改 ORM 查询）

8. 常量管理（新增）

内容： 魔法数字/字符串、常量分散、重复定义

检测：

问题	模式	示例
魔法数字	在条件判断/计算中硬编码数字	if (status === 2)
魔法字符串	在比较中硬编码字符串	if (role === 'admin')
常量分散	常量散落在多个文件中	在 5 个文件中定义 MAX_SIZE = 100
重复定义	同一值出现多次	在 3 处定义 STATUS_ACTIVE = 1
没有中央文件	缺少 constants.ts 或 config.py	没有统一的事实来源

严重性：

• 高： 业务逻辑中的魔法数字（支付金额、状态）
• 中： 重复的常量（同一值定义了 3 次或更多）
• 中： 没有中央常量文件
• 低： 日志记录/调试中的魔法字符串
• 降低严重性时： HTTP 状态码（200、404、500）-> 跳过。算法中的数学常量（0、1、-1）-> 跳过。测试数据 -> 跳过

建议：

• 创建中央常量文件（constants.ts、config.py、constants.go）
• 将魔法数字提取为命名常量：const STATUS_ACTIVE = 1
• 合并重复项，并从中央文件导入
• 对相关常量使用枚举

工作量： M（提取常量、更新导入、合并）

9. 方法签名质量

内容： 较差的方法契约会降低可读性和可维护性

检测：

问题	模式	示例
布尔标志参数	签名中有 >=2 个布尔参数	def process(data, is_async: bool, skip_validation: bool)
可选参数过多	有 >=3 个带默认值的可选参数	def query(db, limit=10, offset=0, sort="id", order="asc")
动词命名不一致	同一模块中，同类操作使用不同动词	get_user() 与 fetch_account() 与 load_profile()
返回类型不明确	使用 -> dict、-> Any、-> tuple，但未使用 TypedDict/NamedTuple	def get_stats() -> dict，而非 -> StatsResponse

严重性：

• 中： 布尔标志参数（应使用枚举/策略）、返回类型不明确
• 低： 可选参数过多、命名不一致

建议：

• 布尔标志：替换为枚举、策略模式或独立方法
• 可选参数：归入配置/选项数据类
• 命名：统一模块内的动词约定（同步操作使用 get_，异步操作使用 fetch_ 等）
• 返回类型：使用 TypedDict、NamedTuple 或数据类，而不是原始 dict/tuple

工作量： S-M（重构签名及调用方）

10. 副作用级联深度

内容： 函数会触发外部副作用的级联链（数据库写入 -> 通知 -> 指标 -> 限额）。

检测： 必须阅读： 加载 references/ai_ready_architecture.md，了解副作用标记、误报排除项和不透明接收端规则。

• 使用 Glob **/services/**/*.{py,ts,js,cs,java} 查找服务文件
• 对每个公共函数：检查函数体中的副作用标记（参见参考文档）
• 递归跟踪被调用的内部函数，查找其他标记
• 计算从入口点开始的最大链深度

严重性：

• 高： cascade_depth >= 4
• 中： cascade_depth = 3
• 正常：深度 <= 2
• 降低严重性时： 编排器/协调器函数（导入 3 个或更多服务并按顺序委派）-> 跳过。来自不透明接收端（日志记录、指标）的深度 -> 跳过

冲突解决： 如果函数是编排器/协调器（导入 3 个或更多服务并按顺序委派给它们）-> 不适用 ARCH-AI-SEB。编排器通常会涉及多个副作用类别。仅对叶函数标记 SEB。

建议： 重构为扁平编排——将副作用提取到独立的接收端函数中。参见参考文档。

工作量： M-L

输出： 还需按模块生成汇总的 Pipe/Sink 表：

模块	Sink（0-1）	浅层 Pipe（2）	深层 Pipe（3+）	Sink 比率

评分算法

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

输出格式

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

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

将报告写入 {output_dir}/ln-624--{domain}.md（或全局模式下的 624-quality.md），并设置 category: "Code Quality"，检查项为：cyclomatic_complexity、deep_nesting、long_methods、god_classes、too_many_params、quadratic_algorithms、n_plus_one、magic_numbers、method_signatures、cascade_depth。

根据 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-624--orders.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 字段
• 结合上下文判断： 小型函数（n < 100）中的 O(n^2) 可能可以接受
• 常量检测： 排除测试文件、配置文件和示例
• 度量工具： 在可用时使用现有工具（ESLint 复杂度插件、radon、gocyclo）

完成定义

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

• 已解析 contextStore（包括 domain_mode、current_domain、output_dir）
• 已确定 scan_path（领域路径或代码库根目录）
• 已完成全部 10 项检查（范围限定为 scan_path）：
  • 复杂度、嵌套、长度、God 类、参数、O(n^2)、N+1、常量、方法签名、级联深度
• 已收集包含严重性、位置、工作量、建议和领域的发现项
• 已计算评分
• 已将报告写入 {output_dir}/ln-624--{domain}.md（通过一次原子 Write 调用）
• 已按契约写入摘要

参考文件

• 审计输出架构： references/audit_output_schema.md

---

版本： 3.0.0 最后更新： 2025-12-23