ln-627-observability-auditor

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

可观测性审计员（L3 Worker）

类型： L3 Worker

负责审计日志记录、监控和可观测性的专项 Worker。

目的与范围

• 审计可观测性（类别 10：中优先级）
• 检查日志记录、运行状况检查、指标和追踪
• 计算合规评分（X/10）

输入

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

接收包含技术栈、框架、代码库根目录和 output_dir 的 contextStore。

如果追踪、调用路径或跨文件引用能显著提升审计质量，请优先使用 hex-graph。如果可用，请优先使用 hex-line 读取局部代码。如果 MCP 不可用、不受支持或未建立索引，请继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明所用的回退方式。

工作流

必须读取： 加载 references/two_layer_detection.md 了解检测方法。

1. 解析 context + output_dir
2. 确定项目类型（第 2 层预检查）： 项目是 Web 服务（所有检查均适用）、CLI 工具（运行状况检查/探测不适用），还是库（大多数检查可选）？据此调整适用的检查项。
3. 检查可观测性模式（第 1 层：grep）
4. 根据候选项分析上下文（第 2 层）：
   • 结构化日志记录：如果是库（不记录日志也可以），还是服务（必须记录日志）？
   • 运行状况端点：Web 服务 -> 必须具备。CLI/库 -> 跳过
   • 请求追踪：单体架构 -> 需求较低。微服务 -> 至关重要
5. 收集已确认的发现
6. 计算评分
7. 编写报告： 按照 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-627--global.md
8. 返回摘要： 向协调器返回最简摘要

审计规则

1. 结构化日志记录

检测：

• Grep 查找 console.log（非结构化）
• 检查是否使用合适的 logger：winston、pino、logrus、zap

严重性：

• 中： 生产代码使用 console.log
• 低： 开发代码使用 console.log

建议： 使用结构化 logger（winston、pino）

工作量： M（添加 logger，替换调用）

2. 运行状况检查端点

检测：

• Grep 查找 /health、/ready、/live 路由
• 检查 API 路由定义

严重性：

• 高： 没有运行状况检查端点（形成监控盲区）

建议： 添加 /health 端点

工作量： S（添加简单路由）

3. 指标收集

检测：

• 检查是否使用 Prometheus 客户端、StatsD、CloudWatch
• Grep 查找指标记录代码：histogram、counter

严重性：

• 中： 未对指标进行埋点

建议： 添加 Prometheus 指标

工作量： M（对代码进行埋点）

4. 请求追踪

检测：

• 检查日志中是否包含关联 ID
• 验证追踪传播（OpenTelemetry、Zipkin）

严重性：

• 中： 没有关联 ID（难以调试分布式系统）

建议： 添加请求 ID 中间件

工作量： M（添加中间件并传播 ID）

5. 日志级别

检测：

• 检查 logger 是否支持级别（info、warn、error、debug）
• 验证是否正确使用日志级别

严重性：

• 低： 仅记录错误日志（可见性不足）

建议： 添加 info/debug 日志

工作量： S（添加日志语句）

评分算法

必须读取： 加载 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-627--global.md，设置 category: "Observability"，并包含以下检查项：structured_logging、health_endpoints、metrics_collection、request_tracing、log_levels。

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

参考文件

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

关键规则

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

• 不要自动修复： 只报告问题，绝不注入日志或端点
• 根据框架进行检测： 根据项目的技术栈调整匹配模式（Node 使用 winston/pino，Go 使用 logrus/zap 等）
• 合理评估工作量： S = <1h，M = 1-4h，L = >4h
• 排除项： 检测 console.log 时跳过测试文件，跳过仅供开发使用的脚本
• 根据上下文确定严重程度： 生产代码中的 console.log = MEDIUM，开发工具中的 = LOW

完成定义

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

• 已解析 contextStore（技术栈、框架、output_dir）
• 已完成全部 5 项检查（结构化日志、健康检查端点、指标、请求跟踪、日志级别）
• 已收集包含严重程度、位置、工作量和建议的问题
• 已按照 references/audit_scoring.md 计算分数
• 已将报告写入 {output_dir}/ln-627--global.md（通过单次原子 Write 调用）
• 已按照契约写入摘要

---

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