ai-ad-code-verifier

name: ai-ad-code-verifier version: "2.5" status: ready_for_production layer: skill owner: wade last_reviewed: 2025-12-24 baseline:

• MASTER.md v4.4
• STATE_MACHINE.md v2.6
• CODE_FACTORY_REFERENCE_PROJECTS.md v1.0 new_features_v2_5:
• 歧义处理流程 (AH-05) - ambiguity_handling 章节
• Phase 1 行为约束验证 (AH-04) - phase1_constraints 章节
• 7 角色白名单更新 (MASTER.md v4.4 §2.4)
• 禁止模式正则检测 new_features_v2_4:
• Phase 1/2 边界检查（PhaseConfig）
• AH-01~05 防幻觉检查（AntiHallucinationChecker）
• SoT 动态加载器（SotLoader） code_sources:
• project: HallOumi github: https://github.com/vectara/hallucination-leaderboard license: Apache-2.0 borrowed_concepts:
  • 幻觉检测理念
  • 事实验证方法论
• project: tree-sitter github: https://github.com/tree-sitter/tree-sitter license: MIT borrowed_concepts:
  • AST 解析策略
  • 多语言支持架构
• project: mypy github: https://github.com/python/mypy license: MIT borrowed_concepts:
  • 静态类型检查架构
  • 类型错误报告格式
• project: ruff github: https://github.com/astral-sh/ruff license: MIT borrowed_concepts:
  • 快速 Linting 架构
  • 规则配置系统
  • 自动修复模式
• project: Qodo Cover github: https://github.com/qodo-ai/qodo-cover license: AGPL-3.0 borrowed_concepts:
  • 测试生成策略
  • 覆盖率分析方法

```
┌─────────────────────────────────────────────────────────┐
│                  EnhancedCodeVerifier                    │
│                    (主编排器)                            │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 0: ModuleBoundaryVerifier (优先级 5) [v2.1 新增]  │
│  - 验证目标模块归属 (pitcher/finance/ad_account/project) │
│  - 检查写入表是否在该模块可写范围内                        │
│  - 阻止跨模块写入操作                                     │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 1: HallucinationDetector (优先级 10)              │
│  - 检测 AI 幻觉: 不存在的 API/函数/模块                   │
│  - 验证导入是否真实存在                                   │
│  - 检查 API 端点是否在项目中定义                          │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 2: ASTVerifier (优先级 20)                        │
│  - 语法正确性验证                                        │
│  - 代码结构完整性                                        │
│  - 括号/缩进匹配                                         │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 3: SpecComplianceVerifier (优先级 30)             │
│  - SoT 合规验证 (状态/角色/字段/错误码)                   │
│  - 日报 8 状态验证 (raw_submitted...final_locked)       │
│  - 4 技术角色验证 (admin/finance/account_manager/media_buyer) - MASTER.md v4.6 │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 3.5: FinanceRulesVerifier (优先级 35) [v2.1 新增] │
│  - Ledger 只 INSERT 验证 (禁止 UPDATE/DELETE)            │
│  - CONFIRMED 门禁 (fx_status=LOCKED)                     │
│  - 冲正链验证 (禁止冲正的冲正)                            │
│  - 金额符号验证 (AMOUNT_SIGN_RULES)                      │
│  - 期间锁检查 (period_locks)                             │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 4: IntegrationVerifier (优先级 40)                │
│  - 导入路径验证                                          │
│  - 依赖可用性检查                                        │
│  - 循环导入检测                                          │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 5: TestVerifier (优先级 50)                       │
│  - 测试文件存在性                                        │
│  - 测试覆盖率检查                                        │
│  - 测试质量验证                                          │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  Layer 6: HallucinationSuppressor (优先级 60) [v2.2 新增] │
│  - 状态值来源追溯 → STATE_MACHINE.md                     │
│  - 角色值来源追溯 → frozenset 白名单                     │
│  - 字段值来源追溯 → DATA_SCHEMA.md                       │
│  - 错误码来源追溯 → ERROR_CODES_SOT.md                   │
│  - API 调用来源追溯 → 项目代码                           │
│  - 生成 source_traceability_report                       │
│  - 任何追溯失败 → BLOCKING                               │
└─────────────────────────────────────────────────────────┘
```

实现文件位置:
- `agents/skills/verifiers/__init__.py` - 模块导出
- `agents/skills/verifiers/base.py` - 基础类型和接口
- `agents/skills/verifiers/module_boundary_verifier.py` - 模块边界验证 [v2.1 新增]
- `agents/skills/verifiers/hallucination_detector.py` - 幻觉检测
- `agents/skills/verifiers/ast_verifier.py` - AST 验证
- `agents/skills/verifiers/spec_compliance_verifier.py` - SoT 合规
- `agents/skills/verifiers/finance_rules_verifier.py` - 财务规则验证 [v2.1 新增]
- `agents/skills/verifiers/integration_verifier.py` - 集成验证
- `agents/skills/verifiers/test_verifier.py` - 测试验证
- `agents/skills/verifiers/hallucination_suppressor.py` - 幻觉抑制最终确认 [v2.2 新增]
- `agents/skills/verifiers/enhanced_verifier.py` - 主编排器

核心原则:
- 🎯 防幻觉: 检测 AI 生成的虚假 API/函数/模块
- ✅ 多维验证: 语法 + SoT 合规 + 集成 + 测试
- 🔄 自动修复: 对可自动修复的问题直接修复
- 📊 报告聚合: 统一格式的验证报告
- 🔁 迭代修复: 支持最多 3 次自动修复迭代

<error_codes> 幻觉检测 (HALL): - HALL-001: 导入不存在的模块 - HALL-002: 导入不存在的名称 - HALL-003: 调用不存在的第三方函数 - HALL-004: 调用不存在的项目函数 - HALL-005: 使用不存在的 API 端点 - HALL-006: 引用不存在的项目模块 - HALL-007: 导入不存在的项目对象

语法验证 (SYN):
- SYN-001: 语法错误
- SYN-002: 意外的 EOF
- SYN-003: 缩进错误
- SYN-004: 括号不匹配
- SYN-005: 引号不匹配
- SYN-006: 混合缩进
- SYN-007: 字符串多行未闭合
- SYN-008: TypeScript 语法错误

结构验证 (STR):
- STR-001: 函数体为空
- STR-002: 类体为空
- STR-003: 缺少函数定义
- STR-004: 缺少类定义
- STR-005: 代码被截断
- STR-006: 导入后无代码
- STR-007: 缺少返回语句

SoT 合规 (SOT):
- SOT-001: 使用未定义的状态
- SOT-002: 使用旧状态名 (如 raw_submitted)
- SOT-003: 使用非法角色
- SOT-004: 使用旧角色名 (如 media_buyer)
- SOT-005: 使用未知字段
- SOT-006: 使用非标准错误码
- SOT-007: 使用未知错误前缀
- SOT-008: 直接修改 balance
- SOT-009: 跨模块写入 (违反模块边界)

财务规则 (FIN) - DATA_SCHEMA.md v5.11 §3.4.4 + STATE_MACHINE.md v2.6:
- FIN-001: UPDATE ledger 表 (禁止)
- FIN-002: DELETE ledger 表 (禁止)
- FIN-003: CONFIRMED 时缺少 fx_status=LOCKED 检查
- FIN-004: 冲正链循环 (冲正的冲正)
- FIN-005: 期间锁绕过 (未检查 period_locks)
- FIN-006: 金额符号错误 (违反 AMOUNT_SIGN_RULES)
- FIN-007: 缺少冲正原因 (reason < 10 字符)

集成验证 (INT):
- INT-001: 未识别的模块
- INT-002: 相对导入路径不存在
- INT-003: 第三方库未安装
- INT-004: 项目模块不存在
- INT-005: 潜在循环导入
- INT-006: 导入分组缺少空行
- INT-007: 使用 star import
- INT-008: 代码位置不正确

测试验证 (TST):
- TST-001: 缺少测试文件
- TST-002: 缺少测试覆盖
- TST-003: 测试失败
- TST-004: 测试缺少断言
- TST-005: 空测试函数
- TST-006: 测试名称不够描述性
- TST-007: P0 功能缺少测试覆盖 [v2.3 新增]
- TST-008: P0 功能测试覆盖率不足 [v2.3 新增]
- TST-009: P0 功能缺少边界测试 [v2.3 新增]

幻觉抑制 (SUP) - v2.2 新增:
- SUP-001: 状态值无法追溯到 STATE_MACHINE.md
- SUP-002: 角色值无法追溯到 frozenset 白名单
- SUP-003: 字段值无法追溯到 DATA_SCHEMA.md
- SUP-004: 错误码无法追溯到 ERROR_CODES_SOT.md
- SUP-005: API 调用在项目中不存在
- SUP-006: 导入的模块/函数在项目中不存在
- SUP-007: 使用非标准来源标注格式 (应为 # SoT: {DOC}#{SECTION})

</error_codes>

<input_contract> 必填: { assembled_files: AssembledFile[], // 组装后的文件列表 requirement: string // 原始需求描述 }

可选:
{
  config: {
    enable_hallucination: boolean,   // 幻觉检测 (默认 true)
    enable_ast: boolean,             // AST 验证 (默认 true)
    enable_spec: boolean,            // SoT 合规 (默认 true)
    enable_integration: boolean,     // 集成验证 (默认 true)
    enable_test: boolean,            // 测试验证 (默认 false)
    enable_p0_test_check: boolean,   // P0 功能测试检查 (默认 true) [v2.3 新增]
    auto_fix: boolean,               // 自动修复 (默认 true)
    max_fix_iterations: number,      // 最大修复次数 (默认 3)
    strict_mode: boolean,            // 严格模式 (默认 false)
    run_tests: boolean,              // 运行测试 (默认 false)
    p0_coverage_threshold: number    // P0 功能最低覆盖率 (默认 90) [v2.3 新增]
  },
  context: {                         // 验证上下文
    valid_states: string[],          // 合法状态列表
    valid_roles: string[],           // 合法角色列表
    valid_error_codes: string[],     // 合法错误码列表
    existing_modules: string[],      // 项目现有模块
    existing_functions: string[],    // 项目现有函数
    existing_endpoints: string[]     // 项目现有 API 端点
  }
}

</input_contract>

<output_contract> { success: boolean, data: { verified_files: [ { path: string, original_content: string, verified_content: string, status: "passed" | "fixed" | "failed" | "skipped", issues: VerifyIssue[], fixes_applied: number } ], summary: { total_files: number, passed: number, fixed: number, failed: number, skipped: number }, all_issues: VerifyIssue[] }, error: string | null }

VerifyIssue:
{
  file_path: string,
  line: number,
  column: number,
  category: string,           // "hallucination" | "syntax" | ...
  severity: "error" | "warning" | "info",
  code: string,               // "HALL-001", "SOT-003", etc.
  message: string,
  suggestion: string,
  evidence: string | null,
  auto_fixable: boolean,
  fix_applied: boolean
}

</output_contract>

# 创建上下文
context = VerifyContext(
    project_root=Path("/path/to/project"),
    requirement="实现用户注册 API",
    valid_states={"pending", "active", "disabled"},
    valid_roles={"admin", "finance", "media_buyer"},
)

# 配置验证器
config = VerifierConfig(
    enable_hallucination=True,
    enable_ast=True,
    enable_spec=True,
    enable_integration=True,
    enable_test=False,
    auto_fix=True,
)

# 创建验证器
verifier = EnhancedCodeVerifier(context, config)

# 验证文件
result = verifier.verify_file("path/to/file.py", file_content)

# 检查结果
if result.status == "passed":
    print("验证通过!")
elif result.status == "fixed":
    print(f"已自动修复 {result.fixes_applied} 个问题")
    print(result.verified_content)
else:
    print("验证失败:")
    for issue in result.issues:
        print(f"  [{issue.code}] {issue.message}")
```

示例 2: 快速验证
```python
from agents.skills.verifiers import quick_verify

result = quick_verify(
    file_path="backend/services/user_service.py",
    content=code_content,
    project_root="/path/to/project",
)

if result["passed"]:
    print("验证通过")
else:
    for error in result["errors"]:
        print(f"错误: {error['message']}")
```

示例 3: 批量验证并生成报告
```python
from agents.skills.verifiers import create_verifier_from_project

# 从项目自动加载 SoT 定义
verifier = create_verifier_from_project(
    project_root="/path/to/project",
    requirement="重构用户模块",
)

# 批量验证
files = [
    ("file1.py", content1),
    ("file2.py", content2),
]
results = verifier.verify_files(files)

# 生成 Markdown 报告
report = verifier.generate_report(results, format="markdown")
print(report)
```

<sot_compliance_details> <!-- 状态值白名单 (STATE_MACHINE.md v2.6 全局状态表) -->

日报状态机 (STATE_MACHINE.md v2.6 + DATA_SCHEMA.md v5.2):
```python
# 使用 frozenset 确保不可变 (对齐 backend/models/enums.py)
REPORT_STATUS = frozenset([
    'raw_submitted',    # 投手提交原始粉数
    'trend_pending',    # 等待趋势风控检查
    'trend_ok',         # 趋势正常
    'trend_flagged',    # 趋势异常,需人工复核
    'trend_resolved',   # 运营确认异常已解决
    'final_pending',    # 等待最终粉数确认
    'final_confirmed',  # 最终粉数已确认
    'final_locked'      # 已进入计费,锁定(终态)
])

# 已废弃状态 (会触发 SOT-002):
# DRAFT, SUBMITTED, PLATFORM_MATCHED, DIFF_FLAGGED, CONFIRMED, REJECTED, REVISED
# (这些是旧版 7 状态,已弃用)
```

Ledger 状态机:
```python
LEDGER_STATUS = frozenset([
    'PENDING',    # 待处理
    'APPROVED',   # 已审批
    'EXECUTED',   # 已执行
    'CONFIRMED',  # 已确认 (需 fx_status=LOCKED)
    'REJECTED'    # 已拒绝
])

LEDGER_FX_STATUS = frozenset([
    'PENDING',    # 待锁定
    'ESTIMATED',  # 预估
    'LOCKED'      # 已锁定
])
```

账户状态机:
```python
ACCOUNT_STATUS = frozenset([
    'active',     # 活跃
    'idle',       # 闲置
    'suspended',  # 暂停
    'banned'      # 封禁
])
```

项目状态机:
```python
PROJECT_STATUS = frozenset([
    'active',     # 进行中
    'paused',     # 暂停
    'completed',  # 已完成
    'cancelled'   # 已取消
])
```

充值状态机:
```python
TOPUP_STATUS = frozenset([
    'pending',    # 待审批
    'approved',   # 已审批
    'rejected',   # 已拒绝
    'settled'     # 已结算
])
```

合法角色 (6 业务层 + 4 技术层, 来源: PRD v5.1, MASTER.md v4.6):
```python
# 业务层 6 角色 (PRD v5.1)
BUSINESS_ROLES = frozenset([
    'ceo',              # 老板 - 资金安全、公司盈亏、最终决策
    'project_owner',    # 项目负责人 - 日报审核、项目盈亏、资金使用效率
    'finance',          # 财务 - 资金出入准确、数据真实、对账
    'pitcher',          # 投手 - CPL 达标、日报准确、执行投放
    'account_manager',  # 户管 - 账户分配、账户状态监控
    'admin'             # 管理员 - 系统配置（不参与业务）
])

# 技术层 4 角色 (MASTER.md v4.6 §INV-007)
TECHNICAL_ROLES = frozenset(['admin', 'finance', 'account_manager', 'media_buyer'])

# 已废弃角色 (会触发 SOT-004):
# supervisor → project_owner (PRD v5.1)
# data_operator → project_owner/finance (PRD v5.1)
# super_admin → admin
# accountant → finance
```

错误码前缀 (ERROR_CODES_SOT.md v2.1 + P2 补充):
```python
VALID_ERROR_PREFIXES = frozenset([
    # 通用错误 (General)
    'VAL',   # 验证错误 - 输入参数校验失败
    'AUTH',  # 认证/授权错误 - 登录、权限、Token
    'BIZ',   # 业务逻辑错误 - 通用业务规则违反
    'DB',    # 数据库错误 - 连接、查询、事务
    'INT',   # 集成错误 - 外部服务调用失败
    'SYS',   # 系统错误 - 内部异常、配置错误

    # 模块专用错误 (Module-Specific)
    'FIN',   # 财务错误 - ledger/冲正/对账/期间锁
    'RPT',   # 日报错误 - 日报提交/确认/状态流转
    'ACC',   # 账户错误 - 广告账户/代理商/归属
    'PRJ',   # 项目错误 - 项目/客户/单价规则
    'PIT',   # 投手错误 - 投手信息/权限/分配
    'TOP',   # 充值错误 - 充值申请/审批/结算
    'IMP',   # 导入错误 - 数据导入/模板/格式
    'EXP',   # 导出错误 - 数据导出/Excel/PDF
    'REC',   # 对账错误 - 平台对账/差异处理
    'SET',   # 结算错误 - 结算单/付款/确认
])

# 错误码格式: {PREFIX}-{NUMBER}
# 示例: RPT-001, FIN-003, ACC-010
# NUMBER 范围: 001-999
```

</sot_compliance_details>

<ambiguity_handling> 歧义处理流程 (AH-05) - 遇到歧义必须停止并询问

**Step 1: 检测到歧义** → 立即 BLOCKING
歧义类型包括:
- 状态值不在 8 状态机白名单中
- 角色值不在 7 角色白名单中
- 字段值不在 DATA_SCHEMA.md 中
- 规则编号不在 BUSINESS_RULES.md 中
- API 端点不在 API_SOT.md 中
- 错误码前缀不在 16 前缀白名单中

**Step 2: 停止当前操作**
- 不继续生成代码
- 不尝试自动猜测
- 不假设默认值

**Step 3: 生成歧义报告**
```json
{
  "type": "STATE_AMBIGUITY | ROLE_AMBIGUITY | FIELD_AMBIGUITY | RULE_AMBIGUITY | API_AMBIGUITY | ERROR_AMBIGUITY",
  "content": "发现状态 'pending_review' 不在 8 状态机中",
  "options": [
    "使用 'trend_pending' (趋势待检查)",
    "使用 'final_pending' (最终待确认)",
    "新增状态到 STATE_MACHINE.md (需 RFC)"
  ],
  "sot_ref": "STATE_MACHINE.md v2.6 §2"
}
```

**Step 4: 等待用户确认**
- 输出歧义报告给用户
- 等待用户选择选项或提供新指示
- 不自行做决定

**Step 5: 继续执行**
- 按用户确认的方案继续
- 记录歧义解决过程

**错误码**: AH-05-AMBIGUITY (BLOCKING)

</ambiguity_handling>

<phase1_constraints> Phase 1 行为约束验证 (AH-04) - 必须遵循 Phase 1 软性原则

**允许的行为** ✅:
| 行为 | 说明 | 代码模式示例 |
|------|------|-------------|
| 记录 | 记录事件到日志 | `logger.info("CPL 超标")` |
| 提示 | 返回警告信息 | `warnings: ["CPL 超标 30%"]` |
| 高亮 | 前端显示标记 | `trend_flag: true` |
| 统计 | 数据汇总分析 | `abnormal_count: 5` |

**禁止的行为** ❌ (会触发 AH-02 违规):
| 行为 | 说明 | 检测模式 |
|------|------|---------|
| 阻断 | 拒绝请求 | `raise HTTPException(4xx, ...)` |
| 拒绝 | 返回错误 | `auto_reject`, `deny_request` |
| 暂停 | 暂停项目 | `.suspend()`, `status = 'suspended'` |
| 冻结 | 冻结账户 | `.freeze()`, `.disable()` |
| 自动拒绝 | 自动驳回 | `auto_reject = True` |
| 自动批准 | 自动通过 | `auto_approve = True` |

**检测正则模式**:
```python
FORBIDDEN_PATTERNS = [
    r'raise\s+HTTPException\s*\(\s*4\d\d',  # HTTP 4xx 错误
    r'raise\s+.*Error.*reject',              # 拒绝错误
    r'\.suspend\s*\(\s*\)',                  # 暂停方法
    r'\.freeze\s*\(\s*\)',                   # 冻结方法
    r'\.disable\s*\(\s*\)',                  # 禁用方法
    r'auto_approve\s*=\s*True',              # 自动批准
    r'auto_reject\s*=\s*True',               # 自动拒绝
    r'status\s*=\s*[\'"]suspended[\'"]',     # 设置暂停状态
    r'status\s*=\s*[\'"]frozen[\'"]',        # 设置冻结状态
]
```

**验证规则**:
1. 扫描生成的代码，检测是否包含禁止模式
2. 如检测到 → 触发 AH-02 违规 (BLOCKING)
3. 建议修改为仅记录和提示的方式

**错误码**: AH-02-PHASE1-VIOLATION (BLOCKING)

**修复建议**:
```python
# 错误做法 (会触发 AH-02)
if over_budget:
    raise HTTPException(400, "超预算，拒绝操作")

# 正确做法 (Phase 1 合规)
if over_budget:
    logger.warning(f"超预算警告: {amount}")
    return {"status": "ok", "warnings": ["超预算警告，请确认"]}
```

</phase1_constraints>

<p0_test_coverage> 核心原则: P0 级别的功能必须有测试覆盖，否则代码不可合并。

**P0 功能定义** (必须测试):
```yaml
p0_features:
  # 状态机相关
  - 状态转换函数 (transition_*)
  - 状态验证函数 (validate_status)
  - 状态守卫函数 (guard_*)

  # 财务相关
  - Ledger 写入函数 (create_ledger_entry)
  - 冲正函数 (reverse_*, create_reversal)
  - 余额计算函数 (calculate_balance)
  - 期间锁检查函数 (check_period_lock, is_period_locked)

  # 权限相关
  - 角色验证函数 (check_role, require_role)
  - 模块边界检查函数 (check_module_boundary)
  - 数据隔离函数 (filter_by_owner)

  # 业务规则相关
  - BR-XXX 规则实现函数
  - 金额计算函数 (calculate_*)
  - 日期验证函数 (validate_date_*)
```

**测试要求**:
| 功能类型 | 最低覆盖率 | 测试类型 |
|---------|-----------|---------|
| 状态转换 | 100% 路径 | 单元测试 + 边界测试 |
| 财务计算 | 100% 分支 | 单元测试 + 精度测试 |
| 权限检查 | 100% 角色 | 单元测试 + 集成测试 |
| 业务规则 | ≥90% 行 | 单元测试 + 场景测试 |

**测试命名规范**:
```python
# 正向测试
def test_{function}_success_{scenario}():
    ...

# 负向测试
def test_{function}_fails_when_{condition}():
    ...

# 边界测试
def test_{function}_boundary_{edge_case}():
    ...

# 示例
def test_transition_to_confirmed_success_with_valid_status():
    ...

def test_create_ledger_entry_fails_when_period_locked():
    ...

def test_calculate_balance_boundary_with_zero_amount():
    ...
```

**验证错误码**:
- TST-007: P0 功能缺少测试覆盖
- TST-008: P0 功能测试覆盖率不足
- TST-009: P0 功能缺少边界测试

</p0_test_coverage>

<forbidden_actions> <forbidden id="VER-001"> <action>忽略幻觉检测结果</action> <correct_action>必须修复所有 HALL-xxx 错误</correct_action> </forbidden>

<forbidden id="VER-002">
  <action>使用已废弃的状态/角色</action>
  <correct_action>使用 SoT 定义的合法值</correct_action>
</forbidden>

<forbidden id="VER-003">
  <action>自动修复超过 3 次仍失败时继续</action>
  <correct_action>返回失败报告，需要人工介入</correct_action>
</forbidden>

<forbidden id="VER-004">
  <action>修改测试以通过验证</action>
  <correct_action>修复代码，而非修改测试</correct_action>
</forbidden>

<forbidden id="VER-005">
  <action>直接修改 balance 字段</action>
  <correct_action>通过 ledger_entries 记录</correct_action>
</forbidden>

</forbidden_actions>

<VERSION_NOTES> ### v2.5 (2025-12-24) - 防幻觉规则集成版 - 新增歧义处理流程 (ambiguity_handling) - AH-05 - 新增 Phase 1 行为约束验证 (phase1_constraints) - AH-04 - 更新角色白名单为 7 角色 (MASTER.md v4.4 §2.4) - 新增禁止模式正则检测 (FORBIDDEN_PATTERNS) - 新增错误码: AH-05-AMBIGUITY, AH-02-PHASE1-VIOLATION

### v2.3 (2025-12-22) - P2 优化版
- 新增 P0 功能测试覆盖要求 (p0_test_coverage)
- 新增 TST-007~009 错误码 (P0 测试覆盖)
- 新增 SUP-007 错误码 (非标准来源标注)
- 扩展错误码前缀 (16 个: 通用 6 + 模块 10)
- 新增配置项: enable_p0_test_check, p0_coverage_threshold

### v2.2 (2025-12-22)
- 新增 Layer 6: HallucinationSuppressor (幻觉抑制最终确认)
- 新增 SUP-001~006 错误码
- 8 层验证流水线完整实现

### v2.1 (2025-12-22)
- 新增 Layer 0: ModuleBoundaryVerifier (模块边界验证)
- 新增 Layer 3.5: FinanceRulesVerifier (财务规则验证)
- 新增 FIN-001~007 错误码
- 更新角色/状态白名单为 frozenset 格式

### v2.0 (2025-12-18)
- 新增幻觉检测层 (HallucinationDetector)
  - 检测不存在的 API/函数/模块
  - 验证第三方库导入
  - 检查项目内部引用
- 增强 AST 验证
  - 支持 Python 和 TypeScript
  - 结构完整性检查
  - 括号/缩进/引号匹配
- 增强 SoT 合规检查
  - 日报 8 状态机验证
  - 充值/转账状态机验证
  - 角色/错误码验证
  - balance 直接修改检测
- 新增集成验证层
  - 导入路径验证
  - 循环导入检测
  - 第三方依赖检查
- 新增测试验证层
  - 测试文件存在性检查
  - 测试覆盖率分析
  - 测试质量检查
- 统一错误码体系
- 支持多种报告格式 (text/json/markdown)

### v1.0 (2025-12-17)
- 初始版本
- 四维验证: 类型/Lint/SoT合规/测试
- 借鉴 mypy 的类型检查架构
- 借鉴 ruff 的快速 Linting 和自动修复
- 自研 SoT 合规检查器
- 最多 3 次自动修复迭代

</VERSION_NOTES>