ln-637-test-structure-auditor

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

可维护性/结构审计器（L3 工作器）

**类型：**L3 工作器

专门审计测试文件组织、孤立测试、碎片化重复项和布局偏移，以便随着测试套件不断增长，确保其可维护性。

目的与范围

• 审计测试可维护性/结构（类别 8：中优先级）
• 检测布局模式（扁平 / 镜像 / 同目录 / 混合）
• 标记超出增长阈值的扁平目录，并建议按领域分组
• 验证测试与源代码的映射一致性，检查孤立测试和碎片化重复项
• 发出 MOVE、MERGE 或 DELETE_ORPHAN
• 计算合规评分（X/10）

输入

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

接收包含以下内容的 contextStore：tech_stack、testFilesMetadata（所有类型——自动化测试和手动测试）、codebase_root、output_dir、domain_mode、all_domains。

**注意：**与接收按类型筛选的元数据的其他工作器不同，此工作器会接收所有测试文件，因为目录结构分析需要全面了解自动化测试和手动测试的放置位置。

工作流

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

1. **解析上下文：**从 contextStore 提取测试文件列表、output_dir、codebase_root 和领域信息
2. **映射源代码结构：**对源代码目录（src/、app/、`lib/）运行 Glob，以构建源代码领域/模块树
3. **映射测试结构：**按父目录对测试文件分组，统计每个目录中的文件数，并分类其位置
4. **扫描检查项（第 1 层）：**使用 Glob/Grep 模式运行 6 项审计检查（参见审计规则）
5. **上下文分析（第 2 层——必须执行）：**对每个候选发现应用第 2 层筛选条件（参见各项检查）
6. **收集发现项：**记录违规项及其严重程度、位置、工作量、操作和建议
7. **计算评分：**按严重程度统计违规项，计算合规评分（X/10）
8. **编写报告：**根据 references/templates/audit_worker_report_template.md 在内存中构建完整 Markdown 报告，并通过单次 Write 调用写入 {output_dir}/ln-637--global.md
9. **返回摘要：**向协调器返回最简摘要（参见输出格式）

审计规则

1. 布局模式检测

**内容：**检测项目使用的测试组织模式，并检查是否存在非预期的模式混用

检测：

• 对每个测试文件的位置进行分类：
  • **同目录：**测试文件与源文件位于同一目录（例如，src/users/users.test.ts）
  • **镜像：**测试文件位于平行的目录层级（例如，tests/users/users.test.ts 对应 src/users/）
  • **集中扁平：**所有测试都位于同一个目录（例如，tests/ 或 __tests__/）
  • **手动：**文件位于 tests/manual/（仅供参考，不予标记）
• 计算各模式的分布百分比
• 如果超过 70% 的文件遵循同一模式，则该模式为主导模式
• 如果没有任何模式达到 70%，则视为混合模式

第 2 层：

• 如果不同类型的测试采用不同模式，则混合模式可以接受（例如，单元测试与源代码同目录，而集成测试位于 tests/automated/integration/）。检查偏差是否与测试类型相关
• 测试文件少于 5 个的项目跳过此项（规模太小，无法确定模式）

严重程度：如果混合模式缺乏明确的类型划分规则（同类型测试中超过 30% 偏离主导模式），则为中等

**建议：**统一测试文件的放置方式——为每种测试类型选择一种模式，并在测试指南中记录 操作：MOVE

**工作量：**L

2. 测试到源文件的映射

内容： 检测孤立的测试文件（源文件已删除但测试仍存在）和路径不匹配的情况

检测：

• 对每个测试文件，提取其对应的源模块：
  • users.test.ts -> users.ts 或 users/index.ts
  • test_payments.py -> payments.py
• 检查对应的源文件是否存在于预期位置
• 如果未找到源文件 -> 列为孤立测试候选项

第 2 层：

• 跳过集成测试/e2e 测试（涉及多个模块，不存在 1:1 的源文件映射）
• 跳过集中式扁平布局中的测试（不需要按路径映射）
• 跳过导入多个源模块的测试文件（本质上属于集成测试）
• 跳过工具/辅助测试文件（test_utils.ts、test_helpers.py）

严重程度： 孤立测试为中（死代码），路径不匹配为低

建议： 删除孤立测试，或更新测试以匹配当前源代码结构
操作： 当对应源代码的行为已不存在时，使用 DELETE_ORPHAN；否则使用 MOVE

工作量： S

3. 扁平目录增长

内容： 检测文件过多、适合通过子目录分组来整理的测试目录

检测：

• 统计每个目录中的测试文件数量（排除 node_modules、dist、build）
• 阈值：
  • 一个扁平目录中有 15-20 个文件 -> 低（接近上限）
  • 一个扁平目录中有 >20 个文件 -> 中（建议重组）
• 对于中等级别的发现，通过分析文件名前缀建议按领域分组：
  • 按共同前缀分组（例如，test_auth_*.py -> auth/ 子目录）
  • 如果有源代码领域结构，则与之交叉比对

第 2 层：

• 如果目录已有子目录（已进行部分整理），则跳过
• 如果文件使用清晰的命名前缀，无需子目录也能充分整理，则跳过
• 跳过 tests/manual/（手动测试结构采用单独的约定）

严重程度： 中（>20 个文件），低（15-20 个文件）

建议： 按领域/功能将测试归入子目录。根据文件名分析建议具体的分组方式：

# Before (flat):
tests/test_auth_login.py, tests/test_auth_tokens.py, tests/test_users_crud.py, ...

# After (grouped):
tests/auth/test_login.py, tests/auth/test_tokens.py, tests/users/test_crud.py, ...

工作量： M 操作： MOVE

4. 领域分组对齐

内容： 检查测试目录的分组是否与源代码领域结构相对应

检测：

• 将源代码领域目录（来自 all_domains 或扫描的 src/）与测试目录名称进行比较
• 对于每个源代码领域，检查是否存在对应的测试分组：
  • 镜像布局：存在 tests/{domain}/ 目录
  • 同置布局：测试文件位于 src/{domain}/
• 标记没有任何对应测试分组的源代码领域

第 2 层：

• 如果项目没有清晰的领域结构（domain_mode="global" 或源代码领域少于 2 个），则跳过
• 跳过 references/common/utils 领域（这些领域横跨多个模块，可能不需要专门的测试分组）
• 如果项目采用集中式扁平布局（不需要分组），则跳过

严重程度： 对于源文件超过 5 个但没有测试分组的领域，为中；其他情况为低

建议： 为该领域创建测试目录/分组，以保持结构对齐

工作量： M 操作： MOVE

5. 同地放置一致性

内容： 检测项目采用的同地放置模式，并标记不一致之处

检测：

• 统计与源文件放在一起的测试文件，以及放在专用测试目录中的测试文件
• 计算比例：同地放置 /（同地放置 + 集中放置）
• 如果比例为 0.0-0.2 -> 集中放置模式
• 如果比例为 0.8-1.0 -> 同地放置模式
• 如果比例为 0.2-0.8 -> 混合模式（可能存在不一致）
• 对于混合模式：识别偏离主导模式的模块

第 2 层：

• 如果不同测试类型采用不同放置方式，则混合模式可以接受：
  • 单元测试与源文件放在一起 + 集成/e2e 测试集中放置 -> 有效的混合模式
  • 检查测试文件的命名/位置与测试类型之间的关联
• 测试文件少于 5 个的项目 -> 跳过

严重性： 如果同类型测试中偏离主导放置模式的比例超过 20%，则为 MEDIUM

建议： 统一测试文件的放置方式——将偏离的测试移至符合项目主导模式的位置

工作量： M-L 操作： MOVE

6. 分散的重复测试

内容： 检测散落在多个文件中的重复或近似重复测试；将它们整合为一个规范测试会更易于维护

检测：

• 按导入的源模块和测试描述关键词对测试分组
• 查找跨文件重复的设置代码块、断言和场景名称
• 比较源导入重叠且准备/断言文本相似的测试文件

第 2 层：

• 跳过有意设计的矩阵测试：每个文件分别覆盖不同环境、适配器、提供方或浏览器
• 如果断言覆盖不同的产品行为，则跳过重复名称
• 跳过已由 ln-632 报告为 E2E 浪费的重复；此工作器仅负责结构性分散问题

严重性： 重复结构增加维护成本时为 MEDIUM，少量局部重复时为 LOW

建议： 在不影响产品信号的前提下，将重复测试合并到一个规范位置或共享辅助工具中

工作量： S-M 操作： MERGE

评分算法

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

严重性映射：

• 孤立测试、过大的扁平目录（>20）、布局不一致、同地放置不一致、分散的重复测试 -> MEDIUM
• 接近扁平目录上限（15-20）、缺少领域测试分组（小型领域）、路径不匹配 -> LOW

输出格式

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

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

将报告写入 {output_dir}/ln-637--global.md，其中 category: "Test Maintainability"，并包含以下检查项：layout_pattern、test_source_mapping、flat_dir_growth、domain_grouping、colocation_consistency、fragmented_duplicates。

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

关键规则

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

• 不要自动修复： 仅报告问题，建议重构
• 合理评估工作量： S = <1h，M = 1-4h，L = >4h
• 琐碎情况跳过： 如果测试文件总数 <5，则返回 10/10 分，且不报告任何问题
• 不检查命名： 测试命名一致性（.test. 与 .spec.）不在范围内——不要重复检查
• 两种类型都检查： 分析自动化测试和手动测试文件的位置，以完整呈现目录布局
• 提出具体建议： 对于扁平目录增长问题，始终根据文件名前缀分析，建议具体的子目录分组
• 独特视角： 仅审计可维护性和结构。不要评估产品行为、E2E 流程价值、作品集价值、覆盖缺失、可信度、预期结果的可靠性或手动证据质量。
• 必须采取行动： 每项发现都使用 MOVE、MERGE 或 DELETE_ORPHAN 之一。

完成定义

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

• contextStore 已成功解析（包括 output_dir 和领域信息）
• 已梳理源代码结构（领域／模块树）
• 已梳理测试结构（按目录对文件分组并统计数量）
• 已完成全部 6 项检查
• 已应用第 2 层上下文分析（按类型混合分析，排除小型项目）
• 已检测布局模式并记录在报告中
• 已识别扁平目录增长信号，并提出具体的分组建议
• 已收集问题，并注明严重性、位置、工作量、操作和建议
• 已使用惩罚算法计算评分
• 已将报告写入 {output_dir}/ln-637--global.md（通过单次原子 Write 调用）
• 已根据约定写入摘要

---

版本： 1.0.0 最后更新： 2026-03-15