ln-647-configuration-boundary-auditor

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

配置边界审计员

类型： L3 Worker

专门审计配置访问是否具有清晰架构边界的 Worker。

目的与范围

• 审计类型化设置边界、分散的环境变量读取、跨层配置泄漏以及配置归属
• 识别架构问题：代码直接读取原始环境变量／配置，而不是依赖设置契约
• 发出 ADD_SETTINGS_BOUNDARY、STOP_SCATTERED_ENV_READS 或 TYPE_CONFIG_CONTRACT
• 计算合规评分（X/10）

范围之外：

• .env 清单、.env.example 完整性、已提交的环境变量文件或密钥卫生
• 软件包安全、构建门禁、运行时启动验证和生命周期就绪状态
• 生成环境变量文件或修改配置

输入

必须读取： 加载 references/audit_worker_core_contract.md 和 references/mcp_tool_preferences.md。 工具策略：你可能作为独立子 Agent 运行，且宿主的 AGENTS.md 不在适用范围内，因此文件读取、搜索和编辑应优先使用 hex-line MCP。仅当 MCP 行为不明确时，才加载 references/mcp_integration_patterns.md。

接收包含技术栈、代码库根目录、output_dir、domain_mode、scan_path 的 contextStore。

当符号或引用分析能实质性地改善配置边界发现时，优先使用 hex-graph。本地代码／配置读取优先使用 hex-line（若可用）。若 MCP 不可用、不受支持或未建立索引，则继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明回退情况。

工作流

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

1. 解析上下文 -- 根据领域感知范围或代码库根目录确定 scan_root
2. 检测配置访问（第 1 层）
   • 应用层／领域层／服务层中的原始环境变量读取
   • 针对同一事项存在多个设置／配置类
   • 在服务边界间传递未类型化的配置字典
   • 在深层叶子函数中读取配置值，而不是在组合／引导边界读取
3. 验证架构上下文（第 2 层）
   • 框架在引导阶段管理的配置访问 -> 跳过
   • 仅测试代码中的环境变量读取 -> 跳过
   • 没有分层架构的小型脚本／CLI -> 降级处理或跳过
   • 在边界间传递类型化设置对象 -> 跳过
4. 收集发现项，包括严重性、位置、操作、工作量和建议
5. 使用 references/audit_scoring.md 计算评分
6. 将报告写入 {output_dir}/ln-647--{identifier}.md
7. 根据 references/audit_summary_contract.md 返回摘要

审计规则

1. 分散的环境变量读取

内容： 原始环境变量／配置读取分布在多个架构层中

检测：

• JavaScript/TypeScript：process.env
• Python：os.getenv、os.environ
• Go：os.Getenv
• .NET/Java：在引导／设置模块之外直接访问环境变量／配置

严重性： 领域／业务逻辑直接读取环境变量时为 HIGH，服务中为 MEDIUM，适配器中为 LOW

操作： STOP_SCATTERED_ENV_READS

2. 缺少类型化设置边界

内容： 配置以原始字典、字符串或基本类型传递，没有类型化设置契约

检测：

• 服务构造函数中使用原始 dict、Record<string, string>、Map<String,String> 或未类型化的配置对象
• 多个服务中重复出现基本类型的配置参数
• 存在大量配置读取，却缺少设置／架构对象

严重性： 默认 MEDIUM；当安全或持久化行为依赖未类型化配置时为 HIGH

操作： TYPE_CONFIG_CONTRACT

3. 配置所有权泄漏

内容： 较低层决定部署／运行时配置，而不是从组合边界接收显式设置

检测：

• 仓库、领域服务或工具模块直接加载环境变量／配置
• 多个模块各自创建配置读取器
• 功能行为在领域逻辑深处根据部署配置进行分支

严重性： 领域／持久化所有权泄漏为 HIGH，服务层泄漏为 MEDIUM

操作： ADD_SETTINGS_BOUNDARY

评分算法

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

输出格式

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

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

将报告写入 {output_dir}/ln-647--{identifier}.md，并设置 category: "Configuration Boundary"，包含以下检查项：scattered_env_reads、typed_settings_boundary、config_ownership_leakage。

当 summaryArtifactPath 缺失时，将独立运行时摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json，并可选择在结构化输出中回显相同的摘要。

关键规则

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

• 不得自动修复： 仅报告问题，绝不修改配置或代码
• 独特范围： 仅审计配置架构边界。不要审计 .env 卫生、已提交的密钥、启动验证、包健康状况或生命周期就绪情况。
• 第 2 层强制要求： 在确认其架构层级和用途之前，不得将原始环境变量读取认定为问题。
• 必须指定操作： 每项问题都必须使用 ADD_SETTINGS_BOUNDARY、STOP_SCATTERED_ENV_READS 或 TYPE_CONFIG_CONTRACT。

完成定义

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

• contextStore 解析成功
• 已确定 scan_root
• 已检查分散的环境变量读取
• 已检查类型化设置边界
• 已检查配置所有权泄漏
• 已应用第 2 层上下文验证
• 已收集问题，并包含严重性、位置、操作、工作量和建议
• 已按照 references/audit_scoring.md 计算评分
• 已将报告写入 {output_dir}/ln-647--{identifier}.md（通过一次原子 Write 调用）
• 已按照契约写入摘要

---

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