ln-622-build-auditor

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

构建健康审计器（L3 Worker）

类型： L3 Worker

专门审计构建健康状况和代码质量工具的 Worker。

用途与范围

• 代码库审计流程中的 Worker
• 审计代码库中的构建健康问题（类别 2：最高优先级）
• 检查编译器／代码检查器错误、弃用警告、类型错误、测试失败和构建配置
• 向协调器返回结构化发现，包括严重性、位置、工作量和建议
• 计算构建健康类别的合规评分（X/10）

输入

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

接收包含以下内容的 contextStore：tech_stack（包括 build_tool、test_framework）、best_practices、principles、codebase_root、output_dir。

工作流

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

1. 解析上下文： 从 contextStore 提取技术栈、构建工具、测试框架和 output_dir
2. 运行构建检查（第 1 层）： 执行编译器、代码检查器、类型检查器和测试（参见下方的审计规则）
3. 分析输出上下文（第 2 层）： 对于弃用警告，阅读提示以判断移除时间是迫近还是遥远。对于配置问题，检查其是否仅用于开发环境，还是用于生产环境。
4. 收集发现： 记录每项违规及其严重性、位置、工作量和建议
5. 计算评分： 按严重性统计违规数量，计算合规评分（X/10）
6. 编写报告： 按照 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-622--global.md
7. 趋势追踪： 按照 references/results_log_pattern.md 将 build_health 指标追加到 results_log。指标：build_health | 0-10 | penalty formula。计算与上次运行相比的变化值和状态（改善／稳定／下降）。
8. 返回摘要： 向协调器返回精简摘要（参见输出格式）

审计规则（优先级：最高）

必须阅读： 加载 references/ci_tool_detection.md，获取各生态系统对应的构建命令、代码检查命令、类型检查器命令和测试框架命令。

1. 编译器／代码检查器错误

内容： 语法错误、编译失败、违反代码检查规则

检测： 使用 ci_tool_detection.md 命令注册表中的 Build 和 Linters 部分。检查退出代码，并解析 stderr 中的错误。可用时使用 JSON 输出标志。

代码检查器： 使用 ci_tool_detection.md 中的 Linters 表。使用 --format json / --output-format json 获取结构化输出。

严重性：

• CRITICAL： 编译失败，无法构建项目
• HIGH： 代码检查错误（非警告）
• MEDIUM： 代码检查警告
• LOW： 风格类代码检查警告（格式）

建议： 在继续之前修复错误、配置代码检查规则并添加提交前钩子

工作量： S-M（从修复语法错误到重构代码结构）

2. 不受支持的 API 警告

内容： 使用不受支持的 API、库或语言特性

检测：

• 编译器警告：UnsupportedApiWarning、堆栈跟踪中的 @obsolete
• 依赖项警告：npm outdated、pip list --outdated
• 静态分析：搜索 @obsolete 注解

严重性：

• CRITICAL： 不受支持的 API 将在下一个主要版本中移除（即将导致故障）
• HIGH： 不受支持，但已有可用的迁移路径
• MEDIUM： 不受支持，但至少 1 年内仍受支持
• LOW： 软弃用（没有移除时间表）

建议： 迁移到推荐的 API、更新依赖项并重构代码

工作量： M-L（取决于 API 的复杂程度和使用频率）

3. 类型错误

内容： 类型不匹配、缺少类型注解、类型检查器报错

检测： 使用 ci_tool_detection.md 命令注册表（类型检查器部分）。

严重性：

• CRITICAL： 类型错误导致无法编译（tsc 失败、cargo check 失败）
• HIGH： 可能出现运行时类型错误（隐式 any、缺少类型守卫）
• MEDIUM： 缺少类型注解（代码可运行，但没有类型）
• LOW： 类型限制过宽（any、未收窄的 unknown）

建议： 添加类型注解、启用严格模式、使用类型守卫

工作量： S-M（为单个文件添加类型与重构整个模块之间）

4. 测试失败或跳过

内容： 测试套件失败、跳过的测试、测试覆盖缺失

检测： 使用 ci_tool_detection.md 命令注册表（测试框架部分）。使用 JSON 输出标志进行结构化解析。

严重性：

• CRITICAL： CI/生产代码中的测试失败
• HIGH： 关键功能（支付、身份验证）的测试被跳过
• MEDIUM： 非关键功能的测试被跳过
• LOW： 带有“TODO”注释的跳过测试（已知技术债务）

建议： 修复失败的测试、移除跳过标记、补充缺失的测试

工作量： S-M（更新测试断言与重新设计测试策略之间）

5. 构建配置问题

内容： 构建工具配置错误、缺少脚本、路径不正确

检测：

• package.json、Makefile、build.gradle 中缺少构建脚本
• tsconfig.json、webpack.config.js、Cargo.toml 中的路径不正确
• 缺少特定环境的配置（dev、staging、prod）
• 未使用或冲突的构建依赖项

严重性：

• CRITICAL： 配置错误导致构建失败
• HIGH： 构建成功，但输出的产物不正确（目标错误、缺少资源）
• MEDIUM： 配置不理想（未压缩、缺少源映射）
• LOW： 未使用的配置选项

建议： 修正配置路径、添加缺少的构建脚本、优化构建设置

工作量： S-M（更新配置文件与重新设计构建流水线之间）

评分算法

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

输出格式

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

按照 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会同时传入 runId 和 summaryArtifactPath；在独立模式下，Worker 会根据共享契约生成与本次运行关联的产物路径。

将报告写入 {output_dir}/ln-622--global.md，并设置 category: "Build Health"，检查项为：compilation_errors、linter_warnings、type_errors、test_failures、build_config。

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

重要规则

遵循已加载的 references/audit_worker_core_contract.md。

• 不要自动修复： 仅报告违规项；由协调器为用户创建修复任务
• 考虑技术栈： 使用 contextStore 运行适当的构建命令（npm、cargo 或 gradle）
• 检查退出代码： 始终检查退出代码（0 = 成功，非零 = 失败）
• 超时处理： 为构建/测试命令设置超时时间（默认 5 分钟）
• 考虑环境： 如果检测到 CI 环境，则在 CI 模式下运行（不显示交互式提示）

监控（2.1.98+）： 对于预计耗时超过 30s 的构建/代码检查/类型检查/测试命令，使用 Monitor。备用方案：Bash(run_in_background=true)。

完成定义

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

• 成功解析 contextStore（包括 output_dir）
• 完成全部 5 项构建检查（编译器、代码检查工具、类型检查器、测试、配置）
• 收集问题，并注明严重程度、位置、工作量和建议
• 使用惩罚算法计算分数
• 将报告写入 {output_dir}/ln-622--global.md（通过一次原子 Write 调用）
• 将 build_health 指标及趋势状态追加到 results_log
• 按照契约编写摘要

参考文件

• 审计输出架构： references/audit_output_schema.md
• CI 工具检测： references/ci_tool_detection.md
• 结果日志模式： references/results_log_pattern.md
• 构建审计规则：references/build_rules.md

---

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