# Context7 MCP Anti-Hallucination Integration

## Overview

Context7 MCP 提供两个工具，用于拉取第三方库的最新官方文档，消除 LLM 训练数据时效性导致的代码审核幻觉。

## Tools

### resolve-library-id

```
输入: libraryName (如 "gin", "gorm", "react", "express")
输出: Context7 兼容的 library ID (如 "/gin-gonic/gin")
```

- 必须在 `get-library-docs` 之前调用
- 用户已提供 `/org/project` 格式 ID 时可跳过
- 解析失败则记录到 `c7_failures`，跳过该库

### get-library-docs

```
输入:
  - context7CompatibleLibraryID: 从 resolve-library-id 获取
  - topic (可选): 聚焦主题 (如 "middleware", "hooks", "query")
  - tokens (可选): 最大返回 token 数 (默认 5000)
```

- 每个库每次审核最多调用 **3 次**
- 优先用 `topic` 缩小范围
- 缓存首次查询结果，后续复用

## Three-Layer Verification

### Layer 1: Pre-Review Warm-up (Phase 0.5)

在审核开始前预热文档缓存：

1. **扫描依赖清单**：
   ```bash
   for f in go.mod package.json requirements.txt Pipfile pyproject.toml \
            Cargo.toml Gemfile pom.xml build.gradle composer.json mix.exs \
            pubspec.yaml *.csproj; do
     [ -f "$f" ] && echo "FOUND: $f"
   done
   ```

2. **提取直接依赖**（按语言）：
   - Go: `go.mod` require 块（排除 `// indirect`）
   - Node: `package.json` 的 `dependencies`
   - Python: `requirements.txt` 或 `pyproject.toml` 的 `[project.dependencies]`
   - Rust: `Cargo.toml` 的 `[dependencies]`
   - Java: `pom.xml` 或 `build.gradle` 的 implementation 依赖

3. **优先级筛选**（最多 10 个库）：
   - P0 框架核心：Web 框架、ORM、核心运行时
   - P1 安全相关：认证库、加密库、JWT 库
   - P2 高频使用：import 次数最多的库
   - P3 其余依赖

4. **批量查询 Context7**：
   ```
   对每个库:
     id = resolve-library-id(libraryName)
     如果失败 → 记录到 c7_failures, 跳过
     docs = get-library-docs(id, topic="核心 API 概览", tokens=5000)
     缓存到 C7 知识缓存
     queries_remaining[库名] = 2
   ```

5. **构建缓存 JSON**：
   ```json
   {
     "session_id": "cr-20260207-143000-a1b2c3d4",
     "libraries": {
       "gin": {
         "context7_id": "/gin-gonic/gin",
         "docs_summary": "...(API 摘要)...",
         "key_apis": ["gin.Context", "gin.Engine"],
         "tokens_used": 5000
       }
     },
     "queries_remaining": { "gin": 2 },
     "c7_failures": []
   }
   ```

> 多个 `resolve-library-id` 可并行调用。

### Layer 2: In-Review Realtime Verification (Phase 2)

子 Agent 审核代码时的实时验证规则：

**必须验证的场景**：
1. 认为某个 API 调用方式错误 → 查 C7 确认当前版本签名
2. 认为某个 API 已废弃 → 查 C7 确认 deprecated 状态
3. 认为代码缺少某库提供的安全/性能特性 → 查 C7 确认该特性存在
4. 认为代码写法不兼容某版本 → 查 C7 拉取对应版本文档

**查询优先级**：
1. 先查 C7 知识缓存（Phase 0.5 预热结果）
2. 缓存未命中 → 调用 `get-library-docs(id, topic="{具体 API 名}")`
3. 遵守每库 3 次查询上限

**标注字段**：
```json
{
  "c7_verified": true,
  "c7_source": "gin.Context.JSON() accepts int status code and any interface{}",
  "verification_method": "c7_cache"
}
```

`verification_method` 取值：
- `c7_cache` — 从预热缓存验证
- `c7_realtime` — 实时调用 Context7 验证
- `model_knowledge` — 未使用 Context7（置信度自动降一级）

### Layer 3: Post-Review Cross-Validation (Phase 3)

主 Agent 汇总时的最终验证：

```
对于每个 finding:
  如果 c7_verified == false 且 severity in [critical, high]:
    如果涉及第三方库 API:
      docs = get-library-docs(libraryID, topic="{相关 API}")
      如果文档支持 Agent 判断 → c7_verified = true, 保留
      如果文档与 Agent 矛盾 → 降级为 info 或删除, 标记 c7_invalidated
      如果 Context7 无数据 → 保留, 标注 unverifiable
    否则 (纯逻辑问题):
      跳过 C7 验证, 保持原判断
```

**强制规则**：`verification_method == "model_knowledge"` 的 critical/high API 相关发现，未完成交叉验证则自动降级为 medium。

## Degradation Strategy

| 场景 | 行为 |
|------|------|
| Context7 MCP 未配置 | 跳过所有 C7 阶段，报告标注 NONE 覆盖度 |
| 网络超时 | 重试 1 次，仍失败则跳过该库 |
| `resolve-library-id` 失败 | 记录到 `c7_failures`，跳过该库 |
| 查询配额耗尽 | 使用已缓存的最佳信息 |
| 子 Agent 中 C7 调用失败 | 标注 `verification_method: "model_knowledge"`，降低置信度 |

## Report Section: Verification Statistics

审核报告中包含的 Context7 统计节：

| 指标 | 说明 |
|------|------|
| 检测到的依赖库总数 | 项目直接依赖数 |
| C7 成功解析的库 | resolve-library-id 成功数 |
| C7 解析失败的库 | 失败列表 |
| Pre-Review 查询次数 | Phase 0.5 的 get-library-docs 调用数 |
| In-Review 查询次数 | Phase 2 子 Agent 的实时查询总数 |
| Post-Review 查询次数 | Phase 3 交叉验证查询数 |
| C7 验证通过的发现数 | c7_verified == true |
| C7 纠正的误判数 | c7_invalidated 标记数 |
| 验证覆盖度评级 | FULL / PARTIAL / LIMITED / NONE |

## Anti-Hallucination Corrections Table

报告中记录被 Context7 纠正的误判：

| # | Agent | 原 Severity | 原 Title | 纠正原因 | C7 Source |
|---|-------|------------|---------|---------|-----------|
| 1 | Security | high | API deprecated | C7 文档显示该 API 在 v2.x 中仍为 stable | /lib/docs... |