ln-624-code-maintainability-hotspot-auditor

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

代码可维护性热点审计器（L3 Worker）

**类型：**L3 Worker

专门审计难以阅读、修改或理解的本地代码热点。

目的与范围

• 审计代码可维护性热点（优先级：中）
• 检查复杂度指标、方法签名质量、本地算法效率、常量管理以及跨层标识符一致性
• 输出 REFACTOR_HOTSPOT、SIMPLIFY_SIGNATURE、EXTRACT_CONSTANT 或 UNIFY_IDENTIFIER
• 返回包含严重程度、位置、工作量和建议的结构化发现
• 计算 Code Quality 类别的合规评分（X/10）

输入

**必须读取：**加载 references/audit_worker_core_contract.md 和 references/mcp_tool_preferences.md。 工具策略：你可能以独立子代理的形式运行，宿主 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）。

工作流

检测策略：使用两层检测（候选项扫描，然后上下文验证）；仅在验证方法不明确时加载 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），则降低严重程度
   • 上帝类：是否为配置/模式/构建器类？-> 降低严重程度
   • 标识符漂移：重命名是否通过显式序列化器别名（@JsonProperty、alias_generator、@SerializedName）或 ORM 列映射（@Column(name=...)）处理？如果是，则降低严重程度或跳过
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）

严重程度：

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

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

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

2. 嵌套过深（> 4 层）

内容： if/for/while 块嵌套过深

检测：

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

严重程度：

• 高： > 6 层（难以阅读）
• 中： 5-6 层
• 低： 4 层
• 降低严重程度的情况： 因提前返回的守卫子句导致嵌套（结构上层级较深，但逻辑是线性的）-> 降低严重程度

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

工作量： M（重构结构）

3. 方法过长（> 50 行）

内容： 函数过长、承担过多工作

检测：

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

严重程度：

• 高： > 100 行
• 中： 51-100 行
• 低： 40-50 行（临界范围）
• 降低严重程度的情况： 按顺序委派工作的编排函数；数据转换流水线 -> 降低严重程度

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

工作量： M（提取逻辑）

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

内容： 文件承担过多职责

检测：

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

严重程度：

• 高： > 1000 行
• 中： 501-1000 行
• 低： 400-500 行
• 降低严重程度的情况： 配置/架构/迁移文件、生成的代码、barrel/index 文件 -> 跳过

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

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

5. 参数过多（> 5）

内容： 函数参数过多

检测：

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

严重程度：

• 中： 6-8 个参数
• 低： 5 个参数（临界范围）
• 降低严重程度的情况： Builder/options 模式的构造函数；框架要求的签名（中间件、钩子）-> 跳过

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

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

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

内容： 对集合使用低效的嵌套循环

检测：

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

严重程度：

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

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

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

7. 常量管理

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

检测：

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

严重程度：

• HIGH： 业务逻辑中的魔法数字（支付金额、状态）
• MEDIUM： 重复的常量（同一个值定义了 3 次或更多）
• MEDIUM： 没有集中管理常量的文件
• LOW： 日志记录/调试中的魔法字符串
• 降低严重程度的情况： HTTP 状态码（200、404、500）→ 跳过。算法中的数学常量（0、1、-1）→ 跳过。测试数据 → 跳过

建议：

• 创建集中管理常量的文件（constants.ts、config.py、constants.go）
• 将魔法数字提取为具名常量：const STATUS_ACTIVE = 1
• 合并重复定义，并从集中管理的文件导入
• 使用枚举表示相关常量

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

8. 方法签名质量

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

检测：

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

严重程度：

• MEDIUM： 布尔标志参数（改用枚举/策略模式）、返回类型不明确
• LOW： 可选参数过多、命名不一致

建议：

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

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

9. 各层之间的标识符一致性

内容： 同一概念在 API 契约、DTO、服务、仓库、数据库列或内部模块中使用不同的标识符

检测：

问题	模式	示例
外部契约漂移	API/OpenAPI/外部架构中的字段名与 DTO/服务/仓库/数据库列中的字段名不同	OpenAPI 中为 user_id，DTO 中为 uid，服务中为 userId，数据库中为 user 列
同义词漂移（内部）	同一实体在不同模块中使用不同名称	同一概念使用 customer、client、account 或 user
未显式处理中大小写/翻译	snake/camel/kebab 格式互换，但未显式声明序列化别名	API 字段 created_at 被赋值给 creationTime，但未声明别名
缩写漂移	同一概念同时使用完整形式和缩写形式	organization、org、orgId 和 organizationId

严重性：

• 高： 外部契约字段在代码中被重命名，且没有显式序列化别名——上游契约变更时存在静默故障风险
• 中： 同一实体在 3 个或更多模块中存在同义词漂移（customer / client / account）
• 中： 大小写转换未显式配置别名映射
• 低： 单个限定模块内存在两种形式的漂移；仅内部代码中存在缩写漂移
• 降低严重性条件： 通过 ORM 映射且显式配置了列别名；框架要求进行转换（例如通过代码生成将 GraphQL 转为 camelCase）；根据契约生成 DTO；因语言关键字冲突而必须重命名 → 降低严重性或跳过

第 2 层要求： 同义词漂移检测依赖经过整理的项目术语表或对使用上下文的审查。仅靠 grep 不足以得出结论——报告前务必确认这两个标识符指的是同一概念。

建议：

• 外部契约情况： 在 DTO / 服务 / 仓库 / 数据库列中始终沿用外部 API 名称。如果大小写或语言规范存在冲突，应在边界处配置一次序列化别名（@JsonProperty、alias_generator、@SerializedName），而不是在代码中重命名字段
• 仅限内部的情况： 选择语义上最精准的形式，通过查找替换统一各模块中的名称，并在共享术语表或共享常量/枚举模块中记录规范术语。在可行的情况下，添加 lint 规则或代码生成步骤，防止问题再次出现
• 单个模块内的动词命名请参阅规则 #8（方法签名质量）

工作量： S-M（重命名 + 序列化配置）。需要重命名数据库列并进行迁移时为 L

评分算法

必须阅读： 加载 references/audit_scoring.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 Maintainability Hotspots"，检查项为：cyclomatic_complexity、deep_nesting、long_methods、god_classes、too_many_params、quadratic_algorithms、magic_numbers、method_signatures、identifier_consistency。

如果未提供 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 字段
• 指标工具： 有可用的现有工具时使用这些工具（ESLint complexity plugin、radon、gocyclo）
• 独特侧重点： 仅审计本地可维护性热点。不要审计重复、软件包健康状况、架构边界、N+1 持久化行为或编排归属。标识符一致性发现项涵盖同一概念在不同层之间的命名连续性；这不同于 ln-623（代码重复）和 ln-643（签名中的 DTO 存在性／层泄漏）。
• 必须执行的操作： 每项发现都使用 REFACTOR_HOTSPOT、SIMPLIFY_SIGNATURE、EXTRACT_CONSTANT 或 UNIFY_IDENTIFIER。

完成定义

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

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

参考文件

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

---

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