AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/08-对外输出报告/CRA智能质控Agent-四大工具工作原理说明.md

# CRA 智能质控 Agent — 四大工具工作原理说明

> **文档用途**：面向临床专家、PI（主要研究者）及项目管理人员，说明 CRA 智能质控 Agent 背后的四个核心工具是如何工作的。  
> **最后更新**：2026-02-25

---

## 一、整体工作方式

CRA 智能质控 Agent 是一个基于大语言模型（LLM）的 AI 助手，专门用于 IIT 临床研究项目的质量监控。当用户在对话框中提问时，AI **不是凭空回答**，而是通过调用 4 个专用工具获取真实数据后，再基于数据生成回答。

### 工作流程

```
用户提问（如："当前通过率是多少？"）
     ↓
AI 分析问题，自动选择合适的工具
     ↓
工具执行，获取真实数据
     ↓
AI 基于工具返回的数据，生成自然语言回答
     ↓
用户看到回答（如："当前整体通过率为 92.9%，14 条记录中 13 条通过..."）
```

### 核心原则

- **所有回答必须基于真实数据**，AI 不会编造临床数据
- **只读不写**：AI 不会修改任何临床数据，如果被要求修改数据会拒绝
- **优先使用报告**：80% 的问题通过预计算的质控报告直接回答，保证速度和一致性

---

## 二、四个工具详解

### 工具 1：`read_report` — 质控报告查阅

**一句话说明**：查阅预先生成好的质控报告，是最常用的工具。

#### 什么时候使用？

用户问以下类型的问题时，AI 会调用此工具：
- "目前通过率是多少？"
- "有哪些严重问题？"
- "3 号受试者有什么质控问题？"
- "哪个表单通过率最低？"
- "最近质控发现了什么趋势？"

#### 报告包含哪些内容？

| 报告章节 | 包含信息 |
|---------|---------|
| **概览（summary）** | 总记录数、已完成记录数、通过率、严重问题数、警告数、最后质控时间 |
| **严重问题（critical_issues）** | 每个有问题的受试者具体违反了哪条规则、实际值是什么、标准应该是什么 |
| **警告（warning_issues）** | 非致命性的数据异常提醒 |
| **表单统计（form_stats）** | 每张 CRF 表单的通过率 |
| **问题排名（trend）** | 哪些规则被违反最多，影响了多少人 |

#### 报告示例

以下是 AI 实际读取的报告格式（修复后的真实报告）：

```xml
<qc_context project_id="xxx" project_name="test0207" generated="2026-02-25T...">

  <summary>
    - 状态: 1/14 记录存在严重违规 (7% Fail)
    - 通过率: 92.9%
    - 严重问题: 1 | 警告: 0
    - Top 1 问题:
      1. 排除标准检查 (1人)
  </summary>

  <critical_issues record_count="1" issue_count="1">
    <record id="3">
      **严重违规 (1项)**:
      1. [exc_001] **排除标准检查**: 当前值 **1** (标准: 应为0)
    </record>
  </critical_issues>

</qc_context>
```

#### 报告数据从哪里来？

```
质控报告 ← 数据库中的质控日志（qc_logs 表）
            ↓
        每个受试者 × 每个访视事件，取最新一条质控记录
            ↓
        按受试者+规则去重，避免重复计数
            ↓
        通过率 = 按受试者级别计算（每个受试者取所有访视中最严重的状态）
```

#### 缓存机制

报告生成后会缓存 **24 小时**。在缓存有效期内，多次提问不会重复计算，保证了响应速度。执行"一键全量质控"后会自动刷新报告缓存。

#### 常见问题

**Q：报告里只有质控问题，不包含录入的原始数据吗？**  
A：对。`read_report` 只包含质控结论（通过/不通过、违规详情）。如果要看具体患者的原始录入数据（如年龄、实验室指标），AI 会自动调用下面的 `look_up_data` 工具。

---

### 工具 2：`look_up_data` — 查询原始临床数据

**一句话说明**：从 REDCap 系统实时拉取患者的原始录入数据。

#### 什么时候使用？

用户问以下类型的问题时，AI 会调用此工具：
- "3 号受试者的年龄是多少？"
- "帮我查一下 5 号患者的实验室检查结果"
- "这个患者的知情同意日期是什么时候？"

#### 工作流程

```
AI 调用 look_up_data（受试者编号=3, 查询字段=[年龄, 性别]）
     ↓
系统将中文字段名翻译为 REDCap 内部字段名（如：年龄 → age）
     ↓
通过 REDCap API 实时查询该患者数据
     ↓
如果是纵向研究（多次访视），自动合并所有访视的数据
     ↓
返回给 AI：{ record_id: "3", age: "28", gender: "1" }
     ↓
AI 组织成自然语言回答用户
```

#### 关键特性

- **实时查询**：每次调用都从 REDCap 获取最新数据，不使用缓存
- **支持中文查询**：用户可以说"帮我查年龄"，系统会自动翻译为 REDCap 字段名 `age`
- **纵向数据自动合并**：同一患者在不同访视（筛选期、基线、随访等）中录入的数据会自动合并为一条完整记录
- **只读操作**：只查询数据，绝不修改

#### 数据来源

直接通过 REDCap REST API 从 REDCap 数据库实时获取，数据路径为：

```
AI → REDCap API（http://REDCap服务器/api/）→ REDCap 数据库 → 返回记录
```

---

### 工具 3：`check_quality` — 即时质控检查

**一句话说明**：对患者数据立即执行质控规则检查，可以检查单个患者或全部患者。

#### 什么时候使用？

用户**明确要求重新检查**时，AI 才会调用此工具：
- "帮我重新检查一下 3 号受试者"
- "现在执行一次全量质控"
- "数据刚更新了，帮我跑一下质控"

> **注意**：如果用户只是问"通过率是多少"这样的查询性问题，AI 会使用 `read_report` 而不是 `check_quality`，因为报告中已有预计算的结果。

#### 两种检查模式

##### 模式 A：单患者检查

```
AI 调用 check_quality(record_id="3")
     ↓
从 REDCap 拉取 3 号患者的最新数据
     ↓
加载项目配置的所有质控规则（如：年龄范围检查、排除标准检查等）
     ↓
逐条规则执行：
  - 字段缺失？→ 跳过该规则（不算失败）
  - 字段有值？→ 用 JSON Logic 规则引擎判定通过/失败
     ↓
返回结果：
  整体状态: FAIL
  通过 8 / 9 条规则
  违规: 排除标准检查 — 当前值为 1（应为 0）
```

##### 模式 B：全量批量检查

```
AI 调用 check_quality()（不传受试者编号）
     ↓
从 REDCap 拉取所有患者的所有访视数据
     ↓
基线数据合并：将基线访视的数据（如年龄、性别）合并到后续访视中
     ↓
逐个 受试者 × 访视 执行规则引擎
     ↓
结果写入数据库（追加新记录，不覆盖历史）
     ↓
返回汇总：
  总计: 42 条检查
  通过: 39 条
  未通过: 3 条
  通过率: 92.9%
  问题受试者: [3号 - 排除标准检查违规]
```

#### 质控规则引擎说明

系统使用 **JSON Logic 规则引擎** 执行质控检查。目前配置的规则包括：

| 规则类别 | 示例规则 | 说明 |
|---------|---------|------|
| **纳入标准** | 年龄范围检查（16-35岁） | 不在范围内则标记为严重问题 |
| **纳入标准** | 知情同意检查 | 必须已签署知情同意 |
| **排除标准** | 排除标准符合性检查 | 符合任何排除标准则标记为严重问题 |

**缺失数据处理策略**（V3.2 修复后）：
- 如果某个字段在当前访视中没有录入（如随访期没有"年龄"字段），该规则**自动跳过**，不算失败
- 只有字段有值但不符合规则时，才判定为失败

---

### 工具 4：`search_knowledge` — 知识库检索

**一句话说明**：在项目文档（研究方案、CRF、伦理批件等）中搜索信息。

#### 什么时候使用？

用户问以下类型的问题时，AI 会调用此工具：
- "纳入标准是什么？"
- "研究方案中对随访间隔是怎么规定的？"
- "主要疗效指标是什么？"
- "知情同意的要求有哪些？"

#### 工作流程

```
AI 调用 search_knowledge(query="纳入标准是什么")
     ↓
查找该项目关联的知识库
     ↓
将用户问题转化为向量（语义表示）
     ↓
在知识库中进行语义相似度搜索（不是简单的关键词匹配）
     ↓
返回最相关的 5 个文档片段：
  1. 研究方案V2.0.pdf（相关度 87.3%）
     内容："纳入标准：1. 年龄16-35岁 2. 确诊为..."
  2. ICF知情同意书.pdf（相关度 72.1%）
     内容："..."
     ↓
AI 综合这些文档片段，生成回答
```

#### 关键特性

- **语义搜索**：不是简单的关键词匹配，而是理解问题含义后搜索。比如问"入组条件"也能找到"纳入标准"的内容
- **文档来源标注**：每个搜索结果都标注来自哪个文档，方便追溯
- **相关度评分**：只返回相关度 ≥ 30% 的结果，过滤无关内容
- **支持多种文档**：研究方案、CRF 说明、伦理批件、操作手册等上传到知识库的文档均可搜索

#### 知识库管理

知识库中的文档需要通过项目管理界面上传。上传后，系统会自动：
1. 解析文档内容（支持 PDF、Word 等格式）
2. 将文档分块（每块约 500-1000 字）
3. 为每个文档块生成向量嵌入（用于语义搜索）
4. 存入向量数据库

---

## 三、工具协作示例

以下是一个典型的多工具协作场景：

### 场景：用户问"3 号受试者有什么问题？详细说明一下"

```
第 1 轮：AI 调用 read_report(section="critical_issues", record_id="3")
         → 获取质控报告中 3 号受试者的问题列表
         → 发现：排除标准检查失败，实际值为 1

第 2 轮：AI 调用 look_up_data(record_id="3", fields=["exclusion_criteria"])
         → 从 REDCap 获取原始数据确认
         → 确认 exclusion_criteria 字段值确实为 1

AI 最终回答：
"3 号受试者存在 1 项严重违规：排除标准检查未通过。
 该受试者的排除标准字段值为 1（应为 0，即不符合任何排除标准）。
 建议核实该受试者是否确实符合入组条件。"
```

### 场景：用户问"纳入标准中年龄范围是多少？有没有超龄的患者？"

```
第 1 轮：AI 调用 search_knowledge(query="纳入标准年龄范围")
         → 从研究方案中找到："纳入标准第1条：年龄16-35岁"

第 2 轮：AI 调用 read_report(section="critical_issues")
         → 检查是否有年龄相关的质控问题
         → 当前无年龄违规记录

AI 最终回答：
"根据研究方案，纳入标准规定年龄范围为 16-35 岁。
 当前质控报告显示，所有已录入受试者的年龄均在合规范围内，
 未发现超龄问题。"
```

---

## 四、总结对比

| 工具 | 核心用途 | 数据来源 | 实时性 | 使用频率 |
|------|---------|---------|--------|---------|
| **read_report** | 查阅质控报告 | 数据库（预计算报告） | 缓存 24 小时 | ~80% |
| **look_up_data** | 查询原始数据 | REDCap 实时 API | 实时 | ~10% |
| **check_quality** | 执行质控检查 | REDCap + 规则引擎 | 实时执行 | ~5% |
| **search_knowledge** | 搜索文档知识 | 项目知识库（向量搜索） | 准实时 | ~5% |

### 设计理念

**报告优先，工具兜底**（Report-first, Tools-fallback）

- 绝大多数质控问题通过预计算的报告直接回答，保证响应速度（秒级）
- 只在需要查看具体原始数据或重新执行质控时，才调用其他工具
- AI 会根据问题类型自动选择最合适的工具，无需用户干预

---

## 附录：技术架构简图

```
┌──────────────────────────────────────────────────────────────────┐
│                        用户对话界面                               │
│                    （Web / 微信公众号）                            │
└──────────────────────┬───────────────────────────────────────────┘
                       │ 用户提问
                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                   ChatOrchestrator（对话编排器）                   │
│                                                                  │
│  System Prompt（角色定义 + 工具选择策略）                          │
│       ↓                                                          │
│  LLM（DeepSeek-V3）← Function Calling 循环（最多 3 轮）          │
│       ↓                                                          │
│  ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌───────────┐ │
│  │ read_report │ │look_up_data │ │check_quality │ │search_    │ │
│  │             │ │             │ │              │ │knowledge  │ │
│  └──────┬──────┘ └──────┬──────┘ └──────┬───────┘ └─────┬─────┘ │
└─────────┼───────────────┼───────────────┼───────────────┼────────┘
          │               │               │               │
          ▼               ▼               ▼               ▼
   ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
   │ QcReport   │  │  REDCap    │  │  REDCap    │  │  pgvector  │
   │ Service    │  │  REST API  │  │  REST API  │  │  向量搜索   │
   │ (数据库)   │  │  (实时)    │  │  + 规则引擎 │  │  (知识库)  │
   └────────────┘  └────────────┘  └────────────┘  └────────────┘
```