ln-643-api-contract-auditor

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

API 契约审计员（L3 Worker）

类型： L3 Worker

专门审计 API 契约、服务边界处的方法签名，以及 DTO 使用模式的工作者。

目的与范围

• 在架构层面审计 API 契约（服务边界、层级分离）
• 检查层级泄漏、DTO 模式、错误契约一致性
• 返回包含 4 项评分的结构化分析（合规性、完整性、质量、实现情况）

范围之外：

• 代码重复（重复出现相同的 DTO 结构、相同的映射逻辑、相同的验证）
• 仅报告架构边界问题（层级错误、缺少契约）

输入

- pattern: "API Contracts"     # Pattern name
- locations: string[]          # Service/API directories
- adr_reference: string        # Path to related ADR
- bestPractices: object        # Best practices from MCP Ref/Context7
- output_dir: string           # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"

# Domain-aware (optional)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

工作流

阶段 0：加载参考资料

必须阅读： 加载 references/detection_patterns.md 和 references/mcp_tool_preferences.md。

检测策略：采用两层检测（候选扫描，然后进行上下文验证）；只有在验证方法存在歧义时才加载 references/two_layer_detection.md。 工具策略：你可能作为独立子 Agent 运行，此时宿主的 AGENTS.md 不在适用范围内，因此文件读取、搜索和编辑默认优先使用 hex-line MCP。只有在 MCP 行为不明确时才加载 references/mcp_integration_patterns.md。

如果符号或引用分析能显著改善契约问题发现效果，优先使用 hex-graph。如果 hex-line 可用，本地代码读取优先使用 hex-line。如果 MCP 不可用、不受支持或未建立索引，则使用内置的 Read/Grep/Glob/Bash 继续，并在报告中说明回退情况。

阶段 1：发现服务边界

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

1. Find API layer: Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. Find service layer: Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. Find domain layer: Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. Map: which services are called by which API endpoints

阶段 2：分析契约（5 条规则）

必须阅读： 加载 references/detection_patterns.md，获取每条规则对应的语言特定 Grep 模式。

#	规则	严重程度	检查内容
1	层级泄漏	HIGH/MEDIUM	服务/领域层接受 HTTP 类型（Request、parsed_body、headers）
2	缺少 DTO	MEDIUM/LOW	2 个以上方法中重复出现 4 个以上参数，但未使用 DTO 分组
3	实体泄漏	HIGH/MEDIUM	API 返回 ORM 实体，且没有响应 DTO。以下情况降级：无外部使用者的内部 API -> LOW
4	错误契约	MEDIUM/LOW	同一服务中混用错误模式（raise + return None）
5	冗余重载	LOW/MEDIUM	方法对带有 _with_/_and_ 后缀，且参数相差 1-2 个
6	架构名实不符	HIGH/MEDIUM	名称表示读取的函数（get_/find_/check_/validate_/is_/has_）包含写入副作用。例外情况见 references/ai_ready_architecture.md

范围边界： 跳过重复问题。仅报告架构边界问题。

阶段 3：计算 4 项评分

合规性评分（0-100）：

标准	分值
无层级泄漏（服务中没有 HTTP 类型）	+35
错误处理模式一致	+25
遵循项目命名约定	+10
以读取命名的函数中没有隐藏副作用	+10
没有实体泄漏到 API	+20

完整性评分（0-100）：

标准	分值
所有服务方法都有类型化参数	+30
所有服务方法都有类型化返回值	+30
为复杂数据定义 DTO	+20
错误类型有文档说明或类型定义	+20

质量评分（0-100）：

标准	分值
服务方法中没有布尔标志参数	+15
没有隐藏写入操作的不透明返回类型	+10
方法超过 5 个参数时均使用 DTO	+25
模块中的命名保持一致	+25
没有冗余重载	+25

实现情况评分（0-100）：

标准	分值
存在 DTO/模式并实际使用	+30
存在类型注解	+25
在边界处进行验证（Pydantic、Zod）	+25
API 响应 DTO 与领域层分离	+20

第 3.5 阶段：计算分数

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

主要分数 使用扣分公式（与所有工作器相同）：

penalty = (critical x 2.0) + (high x 1.0) + (medium x 0.5) + (low x 0.2)
score = max(0, 10 - penalty)

诊断子分数（各为 0-100 分）单独计算，并仅用于诊断目的，报告在 AUDIT-META 中。

第 4 阶段：编写报告

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

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

# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: issues array with principle + domain fields (for cross-domain aggregation)

IF domain_mode == "domain-aware":
  Write to {output_dir}/643-api-contract-{current_domain}.md
ELSE:
  Write to {output_dir}/643-api-contract.md

第 5 阶段：返回摘要

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/643-api-contract-users.md
Score: 6.75/10 (C:65 K:70 Q:55 I:80) | Issues: 4 (H:2 M:1 L:1)

关键规则

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

• 仅限架构层面： 聚焦服务边界，而非内部实现
• 先阅读再评分： 未阅读实际服务代码时，绝不评分
• 范围边界： 跳过重复代码问题
• 检测模式： 使用 detection_patterns.md 中针对特定语言的 Grep
• 领域感知： 当 domain_mode="domain-aware" 时，仅扫描 scan_path，并为发现的问题添加 domain 标签
• 独特职责： 仅审计服务/API 边界契约。不要审计代码重复、包健康状况、依赖拓扑或运行时操作。
• 需要采取行动： 每个问题都使用 ADD_DTO、STOP_ENTITY_LEAK 或 STANDARDIZE_ERROR_CONTRACT。

完成定义

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

• 已发现服务边界（API、服务、领域层）
• 已提取并分析方法签名
• 已使用 detection_patterns.md 检查全部 5 条规则
• 已应用范围边界（不报告重复代码问题）
• 已计算 4 项分数并提供理由
• 已识别问题，并注明严重性、位置、建议和工作量
• 如果启用领域感知：已为发现的问题添加 domain 字段标签
• 已将报告写入 {output_dir}/643-api-contract[-{domain}].md（通过单次 Write 调用原子写入）
• 已按照契约写入摘要

参考文件

• 检测模式：references/detection_patterns.md
• 评分规则：references/audit_scoring.md

---

版本： 2.0.0 最后更新： 2026-02-08