Files

HaHafeng 45c7b32dbb docs(iit): Add QC system UI and LLM format optimization plan

- Add development plan: 07-QC system UI and LLM format optimization

- Phase 1: PromptBuilder + XML clinical slice format (~5.5h)

- Phase 2: QC cockpit + stat cards + risk heatmap (~9.5h)

- Phase 3: Variable tagging system (~5h)

- Add CRA Agent design document and prototype

- Update module status: design 100%, code 45%

- Update system status: real-time QC complete + plan ready

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-08 09:59:44 +08:00

8.2 KiB

Raw Blame History

CRA Agent (临床监查) 深度设计与展现方案

文档版本： v2.0

文档目的： 针对多变量（300+）、高复杂度（入排/PD/AE/伦理）的临床研究场景，设计 CRA Agent 的数据处理逻辑与交互界面。

适用版本： IIT Manager Agent V2.9.1

创建日期： 2026-02-07

🏗️ 一、架构设计：如何处理 300+ 变量？

面对 10 个表单、300 个变量，我们不能试图一次性把所有数据塞进 Prompt。我们需要建立一个 "变量知识图谱" (Variable Metadata Graph)。

1.1 变量分组策略 (Grouping)

在 Admin 端配置 REDCap 映射时，不仅要映射字段名，还要给变量打 "语义标签"：

REDCap 变量名	语义标签 (Tag)	归属域 (Domain)	关键度
dob	#demographics	基线	High
icf_date	#consent, #ethics	伦理	Critical
visit_date	#timeline	访视	High
alt, ast	#lab, #safety	实验室	Medium
tumor_size	#efficacy	疗效	High

设计价值：

当 CRA Agent 需要核查 "是否符合入排标准" 时，它不需要读取 300 个变量，只需要请求 #demographics + #lab + #efficacy 标签下的 20 个变量。

1.2 双层质控引擎 (Hybrid QC Engine)

我们将质控分为两层，只有复杂逻辑才交给 LLM，既省钱又准确。

Layer 1: 基础清洗 (HardRuleEngine)
- 执行者：Node.js 代码
- 检查内容：空值、数据类型、数值范围 (如 BMI > 50)、逻辑跳转。
- 输出：直接生成错误日志，不消耗 Token。
Layer 2: 医学逻辑 (AI Logic Engine)
- 执行者：LLM (DeepSeek/Qwen) + RAG (Protocol)
- 检查内容：入排标准符合性、AE 判定、方案偏离 (PD)、合并用药禁忌。
- 输入：Layer 1 清洗后的数据 + 方案规则。

🤖 二、对 LLM 友好的数据格式设计 (Context Protocol)

为了让 LLM 精准判断医学逻辑，我们放弃 JSON 堆砌，采用 "临床切片 (Clinical Slice)" 模式。

2.1 场景一：入排标准核查 (Inclusion/Exclusion)

LLM Prompt 结构建议：

<task>核查该患者是否符合研究入排标准</task>

<protocol_criteria>

1. 年龄 18-75 岁。
2. 病理确诊为非小细胞肺癌。
3. 肝肾功能正常 (ALT/AST < 2.5 ULN)。
</protocol_criteria>

<patient_slice tag="screening_data">

- 出生日期：1950-05-12 (当前年龄 75 岁)
- 诊断：右肺腺癌 (2025-12-01 确诊)
- 实验室检查：ALT 150 U/L (参考值 0-40), AST 45 U/L。
</patient_slice>

<instruction>
请一步步推理，对比患者数据与标准。重点关注肝功能指标。
</instruction>

2.2 场景二：方案偏离 (Protocol Deviation) - 时间窗检查

LLM Prompt 结构建议：

<task>检查 V2 访视是否超窗</task>

<rule_context>
规则：V2 访视应在 V1 后 28 天 ± 3 天进行。
前提：V1 访视日期为基准。
</rule_context>

<timeline_slice>
- V1 访视日期：2026-01-01
- V2 实际访视日期：2026-02-05
</timeline_slice>

2.3 场景三：AE 事件侦测 (Safety Monitoring)

这是最复杂的，需要对比前后两次数据。

<task>基于实验室数据变化，判断是否发生潜在 AE</task>

<lab_comparison>
<baseline>
WBC: 5.5 (正常)
PLT: 200 (正常)
</baseline>
<current_visit>
WBC: 2.1 (低于下限 4.0) ⚠️
PLT: 180 (正常)
</current_visit>
</lab_comparison>

<question>
白细胞计数 (WBC) 出现显著下降且低于正常值，根据 CTCAE 标准，这属于几级不良事件？是否在 AE 表中记录？
</question>

🖥️ 三、后台展现形式设计 (Human UI)

Admin 端需要一个高密度的 "CRA 驾驶舱"，让 CRA 一眼看穿 300 个变量背后的风险。

3.1 宏观视图：风险热力图 (Risk Heatmap)

不要只列出 List，要用矩阵。

行：受试者 (Subject 001, 002...)
列：访视/表单 (Screening, Baseline, V1, V2, AE, CM)
单元格：颜色代表风险等级。
- 🟢 Green: Clean (无问题)
- 🟡 Yellow: Query (有疑问/空值)
- 🔴 Red: Critical (违背入排/严重 PD/SAE)
- ⚪ Gray: Not Started

交互：点击红色单元格，右侧滑出 "智能诊断报告"。

3.2 微观视图：智能诊断报告 (The "Why" Panel)

当点击某个具体的报警（例如 Subject 001 的入排标准红色警告）时，展示如下内容：

📋 诊断卡片：入排标准违规

[结论]：❌ 建议剔除

[置信度]：High (基于硬指标)

[AI 推理链]：

标准要求：ALT < 2.5倍 ULN (即 < 100 U/L)。
患者数据：当前 ALT 为 150 U/L。
判定：150 > 100，不符合入组标准第 3 条。

[原始证据]：

lab_alt: 150 (来源于 form: lab_results, field: alt)
lab_date: 2026-01-15

[CRA 操作区]：

[ ] 忽略 (医学判断无碍)
[ ] 发送 Query (询问 CRC)
[ ] 确认违规 (标记为 PD)

3.3 调试视图：LLM 视角 (Trace Viewer)

在每条质控记录的详情中，提供一个 "AI 思考过程" Tab，实现黑盒透明化。

Input (Prompt Context): 展示发送给 LLM 的 XML+Markdown 格式原始提示词（即“临床切片”）。
Process (Thinking): 展示 LLM 的思维链（Chain of Thought）。
Output (JSON): 展示最终生成的结构化结论。

⚙️ 四、配置层设计 (Rule Studio)

4.1 规则配置中心

采用 “分层配置，自动托底” 策略：

Layer 1 字段自动映射 (Auto Mapping):
- 系统读取 REDCap Metadata，自动生成 Hard Rules（空值、范围）。
- 用户仅需为变量打标签（Tagging），如 #safety, #efficacy。
Layer 2 逻辑构建器 (Logic Builder):
- 低代码配置跨表逻辑：IF [V2.Date] - [V1.Date] > 31 THEN [PD Alert]。
Layer 3 AI 监查员配置 (AI Setup):
- 上传 Protocol PDF -> AI 自动提取入排标准 -> 人工确认 -> 自动生成 Layer 2 检查 Prompt。

🛡️ 五、特殊医学逻辑设计

针对你提到的 4 个核心需求，设计如下专项 Check：

5.1 入排标准 (I/E Criteria)

设计：将 Protocol PDF 中的入排标准 OCR 化，转为结构化规则库。
展现：在 "受试者列表" 增加一列 "I/E Status"。
- Pass: ✅
- Fail: ❌ (Hover 显示具体哪一条没过，如 "I3: Age")

5.2 方案偏离 (PD)

核心：时间窗 (Time Window) 和漏做检查 (Missing Procedure)。
展现：时间轴视图 (Gantt-like)。
- 展示 "计划访视日" vs "实际访视日"。
- 如果超窗，用红色区间标出。

5.3 伦理合规 (Ethics)

核心逻辑：Date(ICF_Sign) <= Date(Any_Study_Procedure)。
逻辑：如果任何检查日期早于知情同意书签署日期，触发 最高级别警报 (Critical)。
展现：置顶 Banner 警告，因为这是合规红线。

5.4 AE 事件侦测 (Safety)

逻辑：
1. Change Check: 实验室指标从 Normal 变为 Abnormal。
2. Cross Check: 检查 AE Log 表单中是否有对应日期的记录。
3. 如果 Lab 异常但 AE 表为空 -> 提示 "潜在漏报 AE"。
展现：
- "Lab vs AE 一致性检查" 面板。
- 左侧显示异常 Lab 指标，右侧显示 AE 记录，中间用连线表示匹配关系。

📝 总结建议

不要全量喂数据：建立 VariableMetadata，按 Tag 切片。
LLM 看"病历"：将 JSON 转换为 XML 标签包裹的 Markdown 格式的“临床叙事”，不仅省 Token，还能极大提升 AI 对医学逻辑的理解力。
UI 矩阵化：CRA 需要上帝视角，热力图是最佳选择。
推理透明化：AI 报出错误时，必须展示 "标准 vs 现状" 的对比证据，方便 CRA 快速复核。

8.2 KiB Raw Blame History Unescape Escape