docs(iit): Add CRA Agent V3.0 development plan and update module status guide

V3.0 Plan: - Finalize CRA Agent V3.0 development plan (replace CRA positioning) - Add unified CRA QC platform PRD - Add HTML UI prototype (dashboard, AI stream, eQuery, reports) - Architecture: report-driven + LLM Tool Use + 4 semantic tools Module Status Update: - Update architecture from dual-brain V2.9.1 to V3.0 Tool Use - Update DB schema inventory (5 tables -> 18 tables) - Update code stats (577 lines -> 15,000+ lines / 61 files) - Update next steps to V3.0 P0 roadmap - Archive old phase plans (ReAct engine, IntentService) - Add V3.0 document references (plan, PRD, prototype) Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-25 22:04:00 +08:00
parent f0736dbca1
commit 31b0433195
5 changed files with 1689 additions and 251 deletions
--- a/Agent/04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md
+++ b/Agent/04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md
@@ -0,0 +1,664 @@
+# IIT CRA Agent V3.0 — 最终开发计划
+
+> **版本：** V3.0-Final  
+> **日期：** 2026-02-25  
+> **核心定位：** 替代 CRA 岗位的自主 AI Agent，而非辅助 CRA 的工具  
+> **主要用户：** PI（主要研究者）/ 研究团队  
+> **预估周期：** P0 约 9.5 天，P0+P1 约 13.5 天（1 人）  
+> **关联文档：**  
+> - 产品需求文档：[统一数字 CRA 质控平台 PRD](./统一数字%20CRA%20质控平台产品需求文档(PRD).md)  
+> - UI 原型：[Final CRA 质控平台 V3 原型](./Final%20CRA质控平台V3.html)（HTML，浏览器打开即可预览）
+
+---
+
+## 1. 产品定位
+
+### 1.1 CRA Agent 不是给 CRA 用的——是来替代 CRA 的
+
+传统 IIT 项目中，CRA（临床监查员）负责数据质控、方案偏离识别、AE 监测、Query 管理和监查报告撰写。CRA Agent 的目标是用 AI 替代这个岗位的 70-80% 工作量，让 IIT 项目在无专职 CRA 的情况下也能达到合规的质控水平。
+
+| 维度 | 传统模式 | CRA Agent 模式 |
+|------|---------|---------------|
+| 谁干活 | 人类 CRA | AI Agent 自主执行 |
+| 工作方式 | 周期性现场监查，抽查 20% | 7×24 全量自动质控 |
+| 输出物 | 监查报告、Query 单 | 质控报告、Query 清单、风险预警 |
+| 响应速度 | 下次访视时发现问题 | 数据录入后秒级发现 |
+| 用户界面 | CRA 自己看 Excel | PI / 研究团队看驾驶舱 + 对话 |
+| 成本 | 人力费用高，IIT 常省略 | 接近零边际成本 |
+
+### 1.2 能替代与不能替代
+
+**可替代的工作（70-80%）：**
+
+| CRA 工作 | 替代程度 | 实现方式 |
+|----------|---------|---------|
+| 数据质量监控（逐字段核查） | 100% | HardRuleEngine + SoftRuleEngine，全量检查 |
+| 入排标准核查 | 95% | 规则编码，LLM 辅助生成 |
+| 方案偏离识别 | 90% | 访视窗口、用药剂量等规则 |
+| AE/SAE 监测 | 85% | 时限规则 + 因果关系初判 |
+| Query 生成与跟踪 | 90% | AI 生成标准化 Query |
+| 监查报告撰写 | 95% | QcReportService 自动生成 |
+| 入组趋势分析 | 100% | 纯数据统计 |
+
+**暂不替代的工作（20-30%）：**
+
+| CRA 工作 | 原因 | 未来可能 |
+|----------|------|---------|
+| 原始数据核查（SDV） | 需对比医院病历，无 EMR 接口 | 接入 EMR 后可部分替代 |
+| 实地设施检查 | 需人到现场 | 不可替代 |
+| 复杂医学判断 | 需临床经验 | LLM 辅助，PI 确认 |
+| 人际沟通协调 | 催促中心、培训等 | 部分可用消息推送替代 |
+
+> **关键洞察**：大部分 IIT 项目因预算限制根本没有 CRA 在做监查。AI 做到 70% 是从 0 到 70%，而非从 100% 降到 70%。
+
+### 1.3 产品三原则
+
+1. **AI 替代，不是辅助**：Agent 自主巡查、出报告、发 Query，无需人驱动。
+2. **AI 白盒化（Trust Building）**：AI 的每一步推理和操作对全员透明——实时工作流水（AI Stream）让人看到 Agent 在做什么、为什么这么做，建立对 AI 的信任。
+3. **统一视角，去角色化**：废除传统的 PI 视角 / CRC 视角隔离。全员登录同一平台，按数据粒度（概览 → 过程 → 细节）自由穿透，实现"单一真相（Single Source of Truth）"。
+
+### 1.4 两层架构
+
+```mermaid
+graph TB
+    subgraph autonomous [自驱动层: Agent 的日常工作]
+        Cron[定时调度 pg-boss cron] --> QC[全量质控 SkillRunner]
+        Webhook[REDCap DET 实时触发] --> QC
+        QC --> Report[生成质控报告 QcReportService]
+        QC --> Trace[写入 Agent Trace 日志]
+        Report --> Push[企微推送摘要 + Query 清单]
+        Report --> Dashboard[驾驶舱数据更新]
+        Report --> eQuery[eQuery 派发]
+    end
+
+    subgraph dashboard [统一驾驶舱: 四级穿透]
+        L1["概览: 项目健康度大盘"]
+        L2["过程: AI 工作流水 Timeline"]
+        L3["细节: 问题列表 + Query 管理"]
+        L4["资产: 报告归档 + 重大事件库"]
+        L1 --> L2 --> L3 --> L4
+    end
+
+    subgraph dialogue [对话层: 全局 AI Copilot]
+        User[任意用户提问] --> Orchestrator[ChatOrchestrator]
+        Orchestrator --> LLM["LLM + 4 Tools"]
+        LLM --> Answer[结构化回答]
+    end
+
+    Report -.->|read_report| LLM
+    Trace -.-> L2
+    Dashboard -.-> L1
+    eQuery -.-> L3
+```
+
+**自驱动层是核心**——Agent 不等人问，它自己干活。统一驾驶舱是全员查看 Agent 工作成果的窗口。对话层（AI Copilot）悬浮于所有页面之上，任何人随时可问。
+
+---
+
+## 2. 现状盘点（代码实测）
+
+| 组件 | 状态 | 行数 | 说明 |
+|------|------|------|------|
+| 管理端项目配置页面 | 有 | - | 项目列表 + 详情 + REDCap 连接 + 知识库关联 |
+| 质控规则管理 UI | 有 | - | CRUD 规则，在项目详情内 |
+| HardRuleEngine | 有 | 478 | JSON 硬规则执行，成熟 |
+| SoftRuleEngine | 有 | 488 | LLM 软规则质控，可用 |
+| SkillRunner | 有 | 756 | 按 record+event 编排质控 |
+| RedcapAdapter | 有 | 1363 | 数据拉取/元数据/事件，功能完整 |
+| QcReportService | 有 | 980 | 报告生成基础，需增强定时触发和推送 |
+| ToolsService | 有 | 731 | 6 个细粒度工具，**需重构为 4 个语义化工具** |
+| 实时质控（Webhook） | 有 | - | REDCap DET → pg-boss → 质控 Worker |
+| 质控驾驶舱 UI | 有 | - | 统计卡片 + 热力图 + 详情抽屉 |
+| WechatService | 有 | - | 企微推送，运行正常 |
+| 18 张数据库表 | 有 | - | iit_schema，结构合理 |
+| **定时质控** | **缺** | - | 无 cron 调度，只有手动触发和实时 Webhook |
+| **完整报告推送** | **缺** | - | QcReportService 有但无定时触发和企微推送 |
+| **Query 清单生成** | **缺** | - | 无自动生成 Query 并推送的能力 |
+| **REDCap 变量清单可视化** | **半成品** | - | RedcapAdapter.exportMetadata() 存在但未串通到 UI |
+| **AI 辅助规则生成** | **缺** | - | 规则需手动配置，无 LLM 建议 |
+| **eQuery 闭环** | **缺** | - | Query 清单已有雏形，但无状态机（派发→回复→复核→关闭） |
+| **AI 工作流水（AI Stream）** | **半成品** | - | `iit_agent_trace` + `iit_qc_logs` 表已有，但无前端 Timeline 展示 |
+| **重大事件归档** | **缺** | - | SAE/PD 无永久归档和审计轨迹 |
+| **ChatService（对话）** | **需重构** | 1442 | 上帝类，关键词路由，需用 ChatOrchestrator 替代 |
+| **对话历史持久化** | **缺** | - | 只有内存 SessionMemory |
+
+---
+
+## 3. 工具语义化设计（4 工具方案）
+
+### 3.1 设计原则
+
+- **LLM 做粗分类**（选工具），**代码做细路由**（执行逻辑）
+- 工具数量控制在 4 个，语义正交，LLM 不会选错
+- 每个工具内部通过参数区分子场景，对 LLM 透明
+
+### 3.2 工具定义
+
+#### Tool 1: `look_up_data`
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "look_up_data",
+    "description": "查询临床研究数据。可查单个患者详情、患者列表、入组统计、项目基本信息。所有关于'数据是什么'的问题用此工具。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "query_type": {
+          "type": "string",
+          "enum": ["patient_detail", "patient_list", "enrollment_stats", "project_info"],
+          "description": "查询类型：patient_detail=单个患者详情, patient_list=患者列表, enrollment_stats=入组统计, project_info=项目信息"
+        },
+        "record_id": {
+          "type": "string",
+          "description": "患者记录ID（仅 patient_detail 需要）"
+        },
+        "fields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "需要查询的字段列表（可选，不填返回全部）"
+        }
+      },
+      "required": ["query_type"]
+    }
+  }
+}
+```
+
+**内部路由**：
+- `patient_detail` → `RedcapAdapter.exportRecords({ records: [record_id] })`
+- `patient_list` → `RedcapAdapter.exportRecords()` + 格式化
+- `enrollment_stats` → 查 `iit_record_summary` 汇总表
+- `project_info` → 查 `iit_projects` 表
+
+**合并原工具**：`read_clinical_data` + `count_records` + `get_project_info`
+
+---
+
+#### Tool 2: `check_quality`
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "check_quality",
+    "description": "对临床数据执行质控检查。可对单个患者、全部患者、或指定规则类型执行质控。所有关于'帮我检查/质控一下'的请求用此工具。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["single", "all"],
+          "description": "质控范围：single=单个患者, all=全部患者"
+        },
+        "record_id": {
+          "type": "string",
+          "description": "患者记录ID（仅 scope=single 时需要）"
+        },
+        "rule_types": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["variable", "inclusion_exclusion", "protocol_deviation", "adverse_event"] },
+          "description": "限定规则类型（可选，不填执行全部规则）"
+        }
+      },
+      "required": ["scope"]
+    }
+  }
+}
+```
+
+**内部路由**：
+- `scope=single` → `SkillRunner.runByTrigger('manual', { recordId })`
+- `scope=all` → `SkillRunner.runByTrigger('manual')` 全量执行
+- `rule_types` 过滤 → 传给 `filterApplicableRules()`
+
+**合并原工具**：`run_quality_check` + `batch_quality_check`
+
+---
+
+#### Tool 3: `read_report`
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "read_report",
+    "description": "读取质控报告。可查看最新报告概览、问题列表、趋势对比、指定患者的问题详情。80%的质控相关问题都应该先用此工具。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "view": {
+          "type": "string",
+          "enum": ["summary", "issues", "trend", "patient_issues"],
+          "description": "视图类型：summary=报告概览, issues=问题列表, trend=趋势对比, patient_issues=指定患者的问题"
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["critical", "warning", "all"],
+          "description": "按严重程度过滤（可选，默认 all）"
+        },
+        "record_id": {
+          "type": "string",
+          "description": "患者记录ID（仅 patient_issues 时需要）"
+        },
+        "limit": {
+          "type": "integer",
+          "description": "返回条数限制（可选，默认 10）"
+        }
+      },
+      "required": ["view"]
+    }
+  }
+}
+```
+
+**内部路由**：
+- `summary` → `QcReportService.getLatestReport()` 返回概览
+- `issues` → `QcReportService.getIssueList({ severity, limit })` 按严重度排序
+- `trend` → `QcReportService.getTrendComparison()` 对比近两次报告
+- `patient_issues` → `QcReportService.getPatientIssues(record_id)`
+
+**新增工具**：基于已有的 `QcReportService`（980 行）封装
+
+---
+
+#### Tool 4: `search_knowledge`
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "search_knowledge",
+    "description": "在项目知识库中搜索信息，包括研究方案、CRF表、知情同意书等文档。所有关于'方案怎么规定的/CRF里有什么'的问题用此工具。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "question": {
+          "type": "string",
+          "description": "要搜索的问题，用自然语言描述"
+        },
+        "doc_type": {
+          "type": "string",
+          "enum": ["protocol", "crf", "icf", "all"],
+          "description": "限定文档类型（可选，默认 all）"
+        }
+      },
+      "required": ["question"]
+    }
+  }
+}
+```
+
+**内部路由**：
+- 调用平台 RAG 引擎（pgvector 语义检索）
+- `doc_type` 过滤 → 在 RAG 查询时加 metadata filter
+
+**对应原工具**：`search_protocol`（扩展为覆盖全部知识库文档）
+
+### 3.3 对照映射表
+
+| 新工具 | 对应现有工具 | 变化 |
+|-------|------------|------|
+| `look_up_data` | `read_clinical_data` + `count_records` + `get_project_info` | 3 合 1，query_type 参数内部路由 |
+| `check_quality` | `run_quality_check` + `batch_quality_check` | 2 合 1，scope 参数内部路由 |
+| `read_report` | 新增 | 基于 QcReportService 封装，核心工具 |
+| `search_knowledge` | `search_protocol` | 扩展为全知识库 |
+
+---
+
+## 4. P0：自驱动质控流水线（9.5 天）
+
+> P0 的目标：**让 Agent 能独立"上班"** ——定时巡查所有数据、发现问题、生成报告、派发 eQuery、推送告警，无需任何人操作。全员通过统一驾驶舱查看 Agent 的工作成果。
+
+### P0-1：REDCap 变量清单导入 + 可视化（1.5 天）
+
+**目标**：管理端一键拉取 REDCap 的变量清单（Data Dictionary），展示变量名、类型、逻辑关系，作为规则配置的基础。
+
+**后端**：
+- 新增 API：`POST /api/v1/admin/iit-projects/:id/sync-metadata`
+- 调用 `RedcapAdapter.exportMetadata()` 拉取 Data Dictionary
+- 调用 `RedcapAdapter.getFormEventMapping()` 拉取表单-事件映射
+- 写入 `iit_field_metadata` 表（已存在）
+
+**前端**：
+- 在项目详情页新增"变量清单"Tab
+- 表格展示：变量名 | 标签 | 类型 | 所属表单 | 验证规则 | 分支逻辑
+- 支持搜索和按表单筛选
+
+**验收**：点击"同步变量"按钮，表格展示全部 REDCap 变量及其逻辑关系。
+
+---
+
+### P0-2：规则配置增强（2 天）
+
+**目标**：基于变量清单，配置 4 类质控规则（变量级 / 入排标准 / 方案偏离 / AE 事件）。
+
+#### P0-2a：规则配置 UI 改造（1 天）
+
+当前规则管理 UI 存在，需增强：
+
+- **变量级规则**：选择变量 → 配置范围/必填/格式（下拉选变量，自动带出类型）
+- **入排标准**：标记为入排规则类型，选择关联变量
+- **方案偏离**：配置访视窗口、时间约束等规则
+- **AE 事件**：配置 AE 识别触发条件
+
+每类规则的 JSON Schema 已被 HardRuleEngine 支持，重点是让 UI **对接变量清单**（从 `iit_field_metadata` 读取），而不是手敲变量名。
+
+#### P0-2b：AI 辅助规则建议（1 天）
+
+上传研究方案 PDF → LLM 提取关键规则 → 生成规则 JSON 建议 → 人工确认后保存。
+
+实现方式：
+- 前端：规则配置页新增"AI 生成建议"按钮
+- 后端：读取项目知识库中的方案文档（RAG 引擎） + 读取变量清单 → 组合 Prompt → LLM → 返回结构化规则 JSON
+- 前端：展示 LLM 建议的规则列表，用户逐条确认/编辑/删除后批量保存
+- **人在回路**：AI 建议，人来确认，确认后才写入 `iit_skills` 表
+
+**验收**：点击"AI 生成建议"，LLM 基于方案和变量清单生成 5-10 条规则建议，用户确认后保存。
+
+---
+
+### P0-3：定时质控 + 报告生成 + eQuery 闭环（3.5 天）
+
+**目标**：Agent 的核心"日常工作"——定时全量质控、生成完整报告、派发 eQuery、推送摘要。这是 Agent "替代 CRA"最关键的一步。
+
+#### P0-3a：定时质控调度（0.5 天）
+
+- 使用 pg-boss cron 注册定时任务（如每天 8:00 执行全量质控）
+- 在项目配置中新增"定时质控"开关 + cron 表达式
+- 复用已有的 `SkillRunner.runByTrigger('cron')` 执行
+
+#### P0-3b：质控报告生成增强（1.5 天）
+
+当前 `QcReportService`（980 行）有基础，需增强为 Agent 的完整"监查报告"：
+
+```
+SkillRunner 执行全量质控
+    |
+    v
+汇总结果写入 iit_qc_reports 表
+    |
+    v
+报告内容：
+  - 项目概览（入组数 / 完成率 / 质控通过率）
+  - 按受试者的问题分布
+  - 按规则类型统计（入排 / 偏离 / AE / 变量）
+  - 严重问题列表（TOP 10）
+  - 与上次报告的对比（新增 / 已解决）
+  - eQuery 清单（需跟进的问题，含建议 Query 文本）
+  - 重大事件摘要（本期新增 SAE / PD 事件）
+    |
+    v
+存储为结构化 JSON + 可读 Markdown 双格式
+```
+
+eQuery 清单：对每个严重/警告级别的问题，LLM 生成一条标准化 Query 文本（字段 + 问题描述 + 期望操作），汇总为 eQuery 清单。
+
+重大事件归档：被 AI 识别为 SAE 或重大方案偏离的事件，自动写入 `iit_critical_events` 归档表，记录发现时间、处理状态、上报轨迹，作为长期临床资产备查（审计追踪）。
+
+#### P0-3c：eQuery 闭环状态机（1 天）
+
+eQuery 不是一次性的清单，而是有完整生命周期的闭环：
+
+```
+AI 发现问题
+    |
+    v
+自动派发 eQuery（状态: pending）
+    |
+    v
+推送通知到 CRC 企微（含问题描述 + 期望操作）
+    |
+    v
+CRC 通过驾驶舱链接回复（修正数据 / 上传说明）
+    |
+    v
+AI 自动二次复核（状态: reviewing）
+    |
+    v
+复核通过 → 自动关闭（status: closed）
+复核不通过 → 重新打开（status: reopened）
+```
+
+**后端实现**：
+- 新增 `iit_equery` 表（或扩展 `iit_qc_logs` 增加 eQuery 状态字段）
+- eQuery 状态机：`pending` → `responded` → `reviewing` → `closed` / `reopened`
+- CRC 回复后触发 AI 二次质控（复用 SkillRunner 单条质控）
+- 自动关闭逻辑：二次质控通过则自动关闭
+
+**前端实现**：在驾驶舱的 eQuery 管理面板中展示（见 P0-4）。
+
+#### P0-3d：报告推送（0.5 天）
+
+- 定时质控完成后 → 自动推送摘要到企业微信
+- 推送格式：Markdown 卡片（严重问题数 + 通过率 + 待处理 eQuery 数 + "查看详情"链接）
+- 如有严重问题或新增 SAE → 单独推送告警消息
+- 链接指向统一驾驶舱页面
+
+**验收**：配置每天 8:00 定时质控，Agent 自动执行全量质控，生成含 eQuery 清单的报告，推送摘要到企微。CRC 收到 eQuery 通知后可回复，AI 自动复核并关闭。
+
+---
+
+### P0-4：统一质控驾驶舱（2.5 天）
+
+**目标**：驾驶舱是全员（PI / DM / CRC）查看 Agent 工作成果的统一平台。去角色化设计，按数据深度四级穿透。
+
+当前驾驶舱已有统计卡片 + 热力图 + 详情抽屉，需重构为四级穿透架构：
+
+#### 第一级 — 概览：项目健康度大盘（已有基础，增强）
+
+- **健康度评分**：首屏一个综合分数（基于通过率 + 待处理 eQuery + 重大事件），一眼看出项目状况
+- **核心数据卡片**：整体合规率 | 待处理 eQuery 数 | AI 已审查表单数 | 累计重大事件数
+- **高亮事件预警**：近期 SAE / 重大方案偏离，支持直接下钻
+- **趋势图**：质控通过率随时间的变化折线图
+
+#### 第二级 — 过程：AI 工作流水 Timeline（0.5 天，新增）
+
+这是 AI 白盒化的核心展示——让全员看到 Agent 在做什么。
+
+- **实时 Timeline**：动态滚动的瀑布流，展示 Agent 每次质控的完整动作链
+  - 示例："10:24 监听 EDC 保存 → 扫描 P005 实验室表 → 执行 12 条硬规则 (0.2s) → 发现 ALT 异常 → 关联不良事件表 → 派发 eQuery-1029"
+- **数据来源**：`iit_agent_trace` 表（已存在） + `iit_qc_logs` 表（已存在），前端渲染为 Timeline 组件
+- **自动闭环展示**：CRC 修正数据后 Agent 二次复核并自动关闭 eQuery 的全过程
+
+#### 第三级 — 细节：问题列表 + eQuery 管理（已有基础，增强）
+
+- **问题跟踪**：问题状态（新发现 / 已确认 / 已解决），可标记
+- **eQuery 管理面板**：
+  - 展示全部 eQuery，按状态分组（pending / responded / closed）
+  - 每条 eQuery 含：问题描述、AI 监查意见、关联规则溯源、CRC 回复内容
+  - PI 可确认/修改 eQuery 文本后发送
+  - CRC 可在此回复 eQuery（修正数据 / 上传说明）
+- **受试者级问题穿透**：点击任意受试者可查看其全部问题 + eQuery 历史
+
+#### 第四级 — 资产：报告归档 + 重大事件库（0.5 天，新增）
+
+- **报告历史列表**：展示历次质控报告（日期 + 摘要），可点击查看详情
+- **重大事件归档库**：所有 SAE / 重大 PD 的永久归档，含处理和上报全生命周期轨迹
+- **报告导出**：一键导出 Word/PDF 质控报告（复用平台 Pandoc 能力）
+
+**统一视角设计要点**：
+- 全员看同一个界面，不做角色隔离
+- 按数据粒度逐层穿透（概览 → 过程 → 细节 → 资产），而非按角色分页
+- 红色数字高亮严重问题
+- 简化专业 CRA 术语，用研究团队能理解的语言
+
+**验收**：任意用户打开驾驶舱，一眼看到健康度评分；切到 AI Stream 看到 Agent 实时工作记录；切到问题列表管理 eQuery；切到资产库查看历史报告和重大事件归档。
+
+---
+
+## 5. P1：对话层 Tool Use 改造（4 天）
+
+> **前置条件**：P0 完成后再做。P0 产出的质控报告是对话层 `read_report` 工具的数据源。
+
+### P1-1：ChatOrchestrator + 4 工具重构（2 天）
+
+**核心改造**：用 LLM 原生 Tool Use 替代 1442 行关键词路由。
+
+**新建 `ChatOrchestrator`**（~250 行），职责：
+1. 从 `ConversationStore` 加载对话历史（最近 N 轮）
+2. 组装 System Prompt（角色设定 + 项目上下文 + 安全约束）
+3. 组装 4 个工具定义（从重构后的 ToolsService 获取）
+4. 调 LLM（带 Function Calling）
+5. 如果 LLM 返回 tool_calls → 执行工具 → 结果喂回 LLM → 最终回答
+6. 保存对话历史到数据库
+
+**重构 `ToolsService`**：
+- 删除现有 6 个工具注册
+- 注册 4 个语义化工具（`look_up_data` / `check_quality` / `read_report` / `search_knowledge`）
+- 每个工具的 `execute` 方法内部实现路由逻辑
+
+**新建 `ConversationStore`**（~120 行）：
+- 对话历史持久化到 `iit_conversation_history` 表（已存在）
+- 按 userId + projectId 隔离
+- 支持最近 N 轮裁剪
+
+**废弃 `ChatService.ts`**：不再使用关键词路由。
+
+**System Prompt 核心内容**：
+
+```
+你是一个 AI 临床研究监查员（CRA Agent），负责监控 IIT 研究项目的数据质量。
+你的用户是 PI（主要研究者）和研究团队。
+
+你有 4 个工具可用：
+1. read_report — 查看质控报告（优先使用，80% 的问题用这个工具回答）
+2. look_up_data — 查询临床数据
+3. check_quality — 执行质控检查
+4. search_knowledge — 查询研究方案/CRF 等文档
+
+回答规则：
+- 所有数据必须来自工具返回，不要编造
+- 如果报告中已有答案，直接引用报告数据
+- 如果用户问的内容超出你的能力范围，诚实说明
+- 回答简洁，突出关键数字和结论
+```
+
+**验收**：用户自然语言提问（如"003 有什么问题""严重违规有几项""入排标准是什么"），LLM 自动选择正确工具回答。
+
+### P1-2：对话体验优化 + 测试（2 天）
+
+- System Prompt 精调（追问机制、长度控制、防幻觉指令）
+- 企微消息格式优化（Markdown 卡片，含关键数字和快捷操作）
+- 安全护栏（单次对话 5 轮上限、Token 预算、工具调用次数上限、异常兜底）
+- 8 个场景端到端测试：
+
+| 场景 | 示例问题 | 预期工具 | 验收标准 |
+|------|---------|---------|---------|
+| 报告概览 | "最新质控报告怎么样" | read_report(summary) | 返回概览数据 |
+| 问题查询 | "有几条严重违规" | read_report(issues, critical) | 返回精确数字 |
+| 患者详情 | "003 的数据" | look_up_data(patient_detail) | 返回患者数据 |
+| 趋势分析 | "通过率比上周好了吗" | read_report(trend) | 返回趋势对比 |
+| 手动质控 | "帮我查一下 005 的质量" | check_quality(single) | 执行质控返回结果 |
+| 方案查询 | "入排标准是什么" | search_knowledge | 返回方案内容 |
+| 模糊查询 | "项目整体情况怎么样" | read_report(summary) | 返回综合信息 |
+| 越界拒绝 | "帮我修改 003 的数据" | 无（拒绝） | 礼貌拒绝并说明 |
+
+---
+
+## 6. P2：可选（不排期）
+
+| 功能 | 说明 | 何时做 |
+|------|------|--------|
+| SDV 凭证上传 + AI 视觉核对 | CRC 上传原始医疗凭证（化验单等），VisionService 多模态比对 EDC 数据，阅后即焚保隐私 | 待 VisionService 就绪 |
+| 原始数据匹配（SDV via EMR） | AI 对比 EMR 病历 vs EDC 数据，需先定义数据源 | 待 EMR 接口 |
+| 微信小程序前端 | PI 移动端操作界面 | 核心流程跑通后 |
+| PII 隐私脱敏 | 调第三方 LLM 前脱敏患者信息 | 上线前必做 |
+| 周报自动生成 | 每周一自动汇总推送 | 定时质控跑通后 |
+| REDCap 回写 | 质控结果、eQuery 状态写回 REDCap | 根据需求决定 |
+| REDCap 嵌入伴随端 | 浏览器插件在 REDCap 录入界面植入 AI Inline 报错气泡 | 核心流程跑通后 |
+| AutoMapperService | REDCap 乱码变量自动映射为中文医学语义 | 锦上添花 |
+| 数据响应质量评级 | 以"平均响应时长"衡量 CRC 配合质量 | eQuery 闭环跑通后 |
+| eQuery 自动发送 | Agent 生成的 eQuery 自动发给 CRC（无需 PI 确认） | PI 确认流程跑通后 |
+
+---
+
+## 7. 时间线
+
+```
+     P0：自驱动质控流水线（9.5 天）                                P1：对话层（4 天）
+┌──────────┬──────────┬───────────────┬───────────┐  ┌──────────┬──────────┐
+│ P0-1     │ P0-2     │ P0-3          │ P0-4      │  │ P1-1     │ P1-2     │
+│ 变量导入  │ 规则配置  │ 定时质控+报告  │ 统一驾驶舱 │  │Orchestr- │ 体验优化  │
+│          │          │ +eQuery闭环   │ +AI Stream │  │ator 2天  │ 2天      │
+│ 1.5天    │ 2天      │ 3.5天         │ 2.5天     │  │          │          │
+└──────────┴──────────┴───────────────┴───────────┘  └──────────┴──────────┘
+ Day 1-2     Day 3-4    Day 5-8         Day 9-11      Day 12-13   Day 14
+```
+
+P0 完成后 Agent 已能独立运行（自动质控 + 报告 + eQuery 闭环 + 推送 + 透明驾驶舱），P1 补上对话交互能力。
+
+---
+
+## 8. 保留什么（不动的部分）
+
+| 组件 | 行数 | 理由 |
+|------|------|------|
+| HardRuleEngine | 478 | 核心质控引擎，成熟 |
+| SoftRuleEngine | 488 | LLM 质控，有价值 |
+| SkillRunner | 756 | 事件级质控编排，运行正常 |
+| RedcapAdapter | 1363 | 数据源核心，功能完整 |
+| QcReportService | 980 | 报告生成基础，P0 在此基础上增强 |
+| WebhookController | - | 实时触发，运行正常 |
+| WechatService | - | 企微推送，运行正常 |
+| 管理端 3 页面 + 驾驶舱 | - | 在此基础上增强 |
+| 18 张数据库表 | - | Schema 合理，按需新增字段 |
+
+---
+
+## 9. 不做什么
+
+| 砍掉 | 理由 |
+|------|------|
+| 双脑架构（SOP + ReAct 分离） | LLM Tool Use 已是更优方案 |
+| 三层记忆系统（流水账/热记忆/历史书） | 简化为：对话历史 DB + 项目级报告 |
+| 手写 ReAct 引擎 | LLM 原生 Function Calling 包含此能力 |
+| IntentService 关键词意图路由 | LLM 自己就是最好的路由器 |
+| 自建 SchedulerService 类 | pg-boss cron 直接实现 |
+| 微信小程序 | P0/P1 之后考虑 |
+| VisionService | 明确延后 |
+
+---
+
+## 10. 关键决策记录
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 产品定位 | 替代 CRA 岗位（非辅助工具） | IIT 场景 AI 可替代 70-80% CRA 工作 |
+| 主要用户 | 全员（PI / DM / CRC），去角色化 | 统一视角比角色隔离更透明高效 |
+| 驾驶舱设计 | 统一四级穿透（概览→过程→细节→资产） | 废除角色隔离，单一真相 |
+| AI 白盒化 | AI Stream 实时工作流水 | 向全员展示 AI 工作过程，建立信任 |
+| eQuery 模式 | 闭环状态机（派发→回复→复核→关闭） | 替代人工 CRA 的 Query 管理流程 |
+| 对话层架构 | LLM Tool Use + 4 语义化工具 | 比关键词路由准确，比 10+ 细粒度工具好选 |
+| 工具粒度 | 4 个粗粒度语义工具 | LLM 选择准确率高，上下文消耗低 |
+| 核心工具 | `read_report` | 80% 的 Q&A 通过读报告回答 |
+| 定时调度 | pg-boss cron | 复用平台能力，零额外代码 |
+| 规则配置 | UI 对接变量清单 + AI 建议 + 人工确认 | 效率和安全的平衡 |
+| 质控报告 | 结构化 JSON + Markdown 双格式 | JSON 供 LLM 读，Markdown 供人读 |
+| 报告推送 | 企微 Markdown 卡片 | 当前最快的用户触达渠道 |
+| 重大事件 | 永久归档 + 审计轨迹 | 合规刚需，临床长期数字资产 |
+
+---
+
+## 11. 成功标准
+
+| 指标 | P0 目标 | P1 目标 |
+|------|---------|---------|
+| Agent 自主运行 | 每天自动执行全量质控，无需人工触发 | - |
+| 质控报告 | 包含概览/分布/TOP10/趋势/eQuery 清单/重大事件 | - |
+| eQuery 闭环 | 自动派发 → CRC 回复 → AI 复核 → 自动关闭 | - |
+| AI 白盒化 | AI Stream Timeline 展示 Agent 每次质控动作链 | - |
+| 变量导入 | 一键同步 REDCap 变量清单 | - |
+| 规则配置 | UI 可视化配置 4 类规则 | - |
+| AI 建议 | LLM 生成 5-10 条规则建议，人确认后保存 | - |
+| 报告推送 | 定时推送摘要到企微 + 严重问题告警 | - |
+| 统一驾驶舱 | 四级穿透（概览→过程→细节→资产）全员可用 | - |
+| 对话准确率 | - | 工具选择准确率 > 90% |
+| 对话响应 | - | < 5 秒 |
+| 幻觉率 | - | 趋近 0（数据来自工具） |
+| 用户满意度 | 全员能看到项目质控全貌 + AI 工作透明 | 能自然语言问任何质控问题 |
+
+---
+
+> **一句话总结**：CRA Agent 不是给 CRA 用的工具——它就是 CRA。P0 让它能自主"上班"（质控 + 报告 + eQuery 闭环 + 透明驾驶舱），P1 让全员能跟它"对话"（Tool Use + 4 语义化工具）。先让 Agent 干活，再让人能问它。