ln-636-manual-test-auditor

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

手动证据审计员（L3 Worker）

类型： L3 Worker

专门审计手动测试脚本是否能生成可复现且有用的证据。

目的与范围

• 审计手动证据（类别 7：中优先级）
• 根据质量维度评估 tests/manual/ 中的 bash 测试脚本
• 输出 REWRITE_MANUAL_EVIDENCE 或 KEEP_MANUAL_EVIDENCE
• 计算合规评分（X/10）

输入

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

接收包含以下内容的 contextStore：tech_stack、testFilesMetadata（筛选为 type: "manual"）、codebase_root、output_dir。

手动测试元数据包括：suite_dir、has_expected_dir、harness_sourced。

工作流

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

1. 解析上下文： 从 contextStore 提取手动测试文件列表、output_dir、codebase_root
2. 发现基础设施： 检测共享基础设施文件：
   • tests/manual/config.sh -- 共享配置
   • tests/manual/test_harness.sh -- 共享测试框架（如果存在）
   • tests/manual/test-all.sh -- 主运行器
   • tests/manual/TEMPLATE-*.sh -- 测试模板（如果存在）
   • tests/manual/regenerate-golden.sh -- 黄金文件再生成脚本（如果存在）
3. 扫描脚本（第 1 层）： 对每个手动测试脚本检查 7 个质量维度（见审计规则） 3b) 上下文分析（第 2 层——必须执行）： 对每个候选发现项，确认：
   • 这是设置/实用工具脚本（例如 00-setup/*.sh、tools/*.sh）吗？设置脚本的要求不同——跳过框架/黄金文件检查
   • 这是主运行器（test-all.sh）吗？主运行器负责编排，而非测试——除 fail-fast 外跳过所有检查
   • 项目完全没有使用共享框架吗？如果不存在 test_harness.sh，则框架采用检查不适用
4. 收集发现项： 记录违规项及其严重性、位置（文件:行）、工作量、操作和建议
5. 计算评分： 按严重性统计违规项，计算合规评分（X/10）
6. 编写报告： 按照 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-636--global.md
7. 返回摘要： 向协调器返回最简摘要（见输出格式）

审计规则

1. 框架采用情况

检查内容： 测试脚本使用共享框架（run_test、init_test_state），而非自定义断言逻辑

检测方式：

• 在脚本中搜索 run_test、init_test_state
• 如果不存在，且脚本包含自定义测试循环/断言 -> 使用了自定义逻辑
• 如果项目中不存在 test_harness.sh -> 完全跳过此项检查

严重性： 高（自定义逻辑 = 增加维护负担、报告不一致）

建议： 重构为使用来自 test_harness.sh 的共享 run_test 操作： REWRITE_MANUAL_EVIDENCE

工作量： M

2. 黄金文件完整性

检查内容： 测试套件是否有 expected/ 目录，其中包含与测试场景对应的参考文件

检测方式：

• 检查套件目录是否有 expected/ 子目录
• 比较：测试场景数量（grep run_test 调用）与预期文件数量
• 如果测试使用 diff 与预期文件比较，但缺少 expected 目录 -> 记录发现项

第 2 层： 并非所有测试都需要黄金文件。验证 HTTP 状态码、耗时或动态数据的测试可以合理地跳过黄金文件比较 -> 如果测试不包含 diff 或与文件比较，则跳过

严重性： 高（没有黄金文件 = 无法检测输出正确性的回归）

建议： 添加包含参考输出文件的 expected/ 目录 操作： REWRITE_MANUAL_EVIDENCE

工作量： M

3. 配置来源

内容： 脚本通过引入共享的 config.sh 来统一配置

检测方式：

• 搜索 source.*config.sh 或 . .*config.sh
• 如果未找到 -> 脚本自行管理 BASE_URL、令牌等

第 2 层： 如果脚本是自包含的实用工具（例如 tools/*.sh）-> 跳过

**严重性：**中

建议： 添加 source "$THIS_DIR/../config.sh" 以使用共享配置 操作： REWRITE_MANUAL_EVIDENCE

工作量： S

4. 快速失败合规性

内容： 脚本使用 set -e，并在失败时返回退出码 1

检测方式：

• 搜索 set -e（或 set -eo pipefail）
• 检查失败路径是否会导致非零退出（而不是处处用 || true 吞掉错误）

**严重性：**高（静默失败会掩盖测试故障）

建议： 在脚本开头添加 set -e，确保测试失败能够向上传递 操作： REWRITE_MANUAL_EVIDENCE

工作量： S

5. 模板合规性

内容： 脚本遵循项目测试模板（TEMPLATE-api-endpoint.sh、TEMPLATE-document-format.sh）

检测方式：

• 如果 tests/manual/ 中存在 TEMPLATE 文件，检查结构是否一致：
  • 包含说明、测试的 AC 和前置条件的头部注释块
  • 标准变量命名（THIS_DIR、EXPECTED_DIR）
  • 标准设置模式（source config.sh、check_jq、setup_auth）
• 如果项目中不存在模板文件 -> 完全跳过此项检查

第 2 层： 在模板编写之前创建的旧脚本可能会有所不同。标记为中，而不是高

**严重性：**中

建议： 使脚本结构与项目 TEMPLATE 文件保持一致 操作： REWRITE_MANUAL_EVIDENCE

工作量： M

6. 幂等性

内容： 脚本可以安全地重复运行，不受之前运行的副作用影响

检测方式：

• 搜索清理模式：trap.*EXIT、rm -f、cleanup 函数
• 检查创建临时文件后是否未进行清理
• 检查是否存在重复运行时会冲突的硬编码资源名称（例如，未检查是否已存在便使用固定邮箱创建用户）

第 2 层： 只读取数据的脚本（GET 请求、查询）本质上具有幂等性 -> 跳过

**严重性：**中

建议： 添加清理 trap，或在每次运行时使用唯一标识符 操作： REWRITE_MANUAL_EVIDENCE

工作量： S-M

7. 文档

内容： 测试套件目录包含说明用途和前置条件的 README.md

检测方式：

• 检查套件目录（NN-feature/）是否包含 README.md
• 如果缺少 -> 记为发现项

第 2 层： 设置目录（00-setup/）和实用工具目录（tools/）可能不需要 README -> 跳过

**严重性：**低

建议： 添加 README.md，说明测试目的、前置条件和用法 操作： REWRITE_MANUAL_EVIDENCE

工作量： S

评分算法

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

严重性映射：

• 未采用现有的测试框架（当框架存在时）、缺少黄金文件（基于预期结果时）、未快速失败 -> 高
• 未引入配置、模板不一致、无幂等性 -> 中
• 缺少 README -> 低

输出格式

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

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

将报告写入 {output_dir}/ln-636--global.md，其中 category: "Manual Evidence"，检查项包括：harness_adoption、golden_file_completeness、config_sourcing、fail_fast_compliance、template_compliance、idempotency、documentation。

按照 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-636--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
• 目录为空时跳过： 如果不存在 tests/manual/ 目录，则返回 10/10 分，且问题数为 0
• 排除非测试文件： 跳过 config.sh、test_harness.sh、test-all.sh、regenerate-golden.sh、TEMPLATE-*.sh，以及 tools/、results/、test-runs/ 中的文件
• 结合上下文判断： 设置脚本（00-setup/）的要求较宽松（无需黄金文件，也无需测试框架）
• 独特关注点： 仅审查手动测试证据。不要评判自动化测试的价值、E2E 优先级、产品行为、覆盖缺失、可信度、预期结果的可靠性或结构。
• 必须采取行动： 对问题使用 REWRITE_MANUAL_EVIDENCE。在报告摘要中将符合要求的脚本总结为 KEEP_MANUAL_EVIDENCE，不要将其列为问题。

完成标准

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

• contextStore 解析成功（包括 output_dir）
• 已发现手动测试基础设施（配置文件、测试框架、模板）
• 已对每个测试脚本完成全部 7 项检查
• 已应用第 2 层上下文分析（设置/实用工具排除项）
• 已收集问题，并记录严重性、位置、工作量、操作和建议
• 已使用惩罚算法计算分数
• 已将报告写入 {output_dir}/ln-636--global.md（通过单次原子写入完成）
• 已按约定撰写摘要

参考文件

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

---

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