feat(iit): Initialize IIT Manager Agent MVP - Day 1 complete
- Add iit_schema with 5 tables - Create module structure and types (223 lines) - WeChat integration verified (Access Token success) - Update system docs to v2.4 - Add REDCap source folders to .gitignore - Day 1/14 complete (11/11 tasks)
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
# **IIT Manager Agent V4 完整产品需求文档 (全量集成版)**
|
||||
|
||||
## **1\. 引言**
|
||||
|
||||
### **1.1 项目背景**
|
||||
|
||||
在研究者发起的临床试验（IIT）中，数据质量的核心痛点在于“过程失控”。传统的 EDC 系统（如 REDCap）是静态的记录工具。IIT Manager Agent V4 旨在通过“自研逻辑编排 \+ Dify 知识库赋能”，构建一个具有主动意识、实时质控、多端协同的数字科研团队。
|
||||
|
||||
### **1.2 核心目标**
|
||||
|
||||
* **主动任务化**：将 Protocol（方案）转化为主动驱动的任务流，而非被动的数据填报。
|
||||
* **医疗级合规**：通过“影子状态”机制，确保 AI 建议在进入真理源（REDCap）前经过人类确权。
|
||||
* **规模化品牌**：通过“企微中枢 \+ 小程序落地”解决 100+ 项目同时运行时的品牌归属感与触达效率。
|
||||
|
||||
## **2\. 产品总体架构：原生编排 \+ 外部认知**
|
||||
|
||||
系统放弃了黑盒 Agent 框架，采用\*\*“大脑与图书馆”\*\*分离的架构：
|
||||
|
||||
* **逻辑大脑 (Node.js \+ pg-boss)**：位于后端，负责状态机流转、影子数据处理、权限校验及异构系统调度。
|
||||
* **知识图书馆 (Dify RAG)**：负责非结构化文档（方案、指南、手册）的解析与向量检索，作为 AI 的认知增强。
|
||||
|
||||
## **3\. 终端与角色矩阵 (Endpoint & Role Matrix)**
|
||||
|
||||
系统通过“基础角色 \+ 扩展权限”模式，实现跨终端的紧密协作。
|
||||
|
||||
| 角色 | 核心诉求 | 推荐终端 | 核心交互逻辑 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **项目负责人 (PI)** | 宏观进度、合规审批、学术报表 | **企业微信 (通知) \+ 微信小程序 (查看)** | 接收企微通知，在小程序查看品牌化报表并审批 |
|
||||
| **协调员 (CRC)** | 录入数据、复核建议、管理随访 | **REDCap (录入) \+ PC Workbench (复核)** | 尊重 REDCap 录入习惯，在工作站处理 AI 质疑 |
|
||||
| **患者 (受试者)** | 访视提醒、依从性引导、医学咨询 | **个人微信 (H5/小程序)** | 接收由 Agent 以 CRC 名义发送的企微消息 |
|
||||
| **系统管理员** | 项目初始化、规则配置、RAG 维护 | **PC 端 (Admin Portal)** | 数字化方案、配置字段映射、管理多租户 |
|
||||
|
||||
## **4\. 核心功能模块与 Agent 矩阵**
|
||||
|
||||
### **4.1 数据质控 Agent (严谨的监察员)**
|
||||
|
||||
* **逻辑**：通过 Webhook 监听 REDCap 录入 \-\> 调用 Dify 检索方案规则 \-\> 发现逻辑冲突 \-\> 生成影子质疑 (Pending Action)。
|
||||
* **参数**：Temperature \= 0，追求极致确定性。
|
||||
|
||||
### **4.2 任务驱动引擎 (数字指挥官)**
|
||||
|
||||
* **逻辑**：根据项目初始化定义的 Visit Schedule 计算访视窗 \-\> 触发 pg-boss 延时任务 \-\> 自动发送微信提醒。
|
||||
|
||||
### **4.3 患者随访 Agent (温暖的协调员)**
|
||||
|
||||
* **逻辑**：基于 RAG 知识库回复患者咨询 \-\> 识别 SAE 风险 \-\> 自动提醒 CRC 介入接管。
|
||||
* **参数**：Temperature \= 0.7，保持医学严谨的同时具有亲和力。
|
||||
|
||||
### **4.4 汇报 Agent (智能汇报者)**
|
||||
|
||||
* **逻辑**：自动汇总 REDCap 进度数据 \-\> 生成智能报表草稿 \-\> 推送至 PI 微信确认。
|
||||
|
||||
## **5\. 操作边界：双轨并行原则**
|
||||
|
||||
为了降低推广阻力，系统明确划分了 REDCap 与 Workbench 的操作边界：
|
||||
|
||||
* **REDCap 原生录入**：
|
||||
* **场景**：手动、少量、常规的临床数据录入。
|
||||
* **AI 表现**：后台静默质控，仅通过 EM 插件在页面顶端显示微提醒。
|
||||
* **AI Workbench**：
|
||||
* **场景**：化验单 OCR 批量采集、AI 建议的深度复核（同屏对比证据链）、多中心映射配置。
|
||||
* **AI 表现**：作为主要处理界面，展示推理过程与原文引用。
|
||||
|
||||
## **6\. 核心机制：影子状态机 (Shadow State)**
|
||||
|
||||
所有 AI 建议必须经过以下生命周期，严禁 AI 直接修改 REDCap 数据：
|
||||
|
||||
1. **PROPOSED (影子建议)**：Agent 发现问题，记录于 pending\_actions 表，包含引用页码及推理逻辑。
|
||||
2. **APPROVED (人类确权)**：CRC 在 Workbench 点击“确认”或 PI 在小程序点击“审批”。
|
||||
3. **EXECUTED (正式执行)**：系统通过 EDC Adapter 调用 API 回写至 REDCap，并生成审计日志。
|
||||
|
||||
## **7\. 规模化部署与微信集成方案**
|
||||
|
||||
针对“100 个项目、47 家医院”的规模化场景：
|
||||
|
||||
### **7.1 通知中枢 (企业微信)**
|
||||
|
||||
* 使用壹证循统一认证的企微主体作为“推送管道”。
|
||||
* 针对每个研究项目创建“自建应用”，应用名可设置为“XX 项目研究组”，降低商业感。
|
||||
|
||||
### **7.2 品牌落地 (小程序)**
|
||||
|
||||
* PI/CRC 从企微卡片跳转至微信小程序。
|
||||
* **动态渲染**：小程序根据 project\_id 自动加载对应医院的 Logo、主题色和项目名称，给足 PI“学术归属感”。
|
||||
|
||||
## **8\. 技术底座与安全合规**
|
||||
|
||||
### **8.1 基础设施**
|
||||
|
||||
* **数据库**：Postgres-Only 架构，利用 iit\_schema 实现物理隔离。
|
||||
* **集成层**：REDCap External Module (EM) 侧挂插件 \+ Node.js REST API 适配器。
|
||||
|
||||
### **8.2 安全与 GxP**
|
||||
|
||||
* **Token 安全**：所有 REDCap API Token 使用 AES-256-GCM 高强度加密存储。
|
||||
* **脱敏引擎**：上下文进入 LLM 前，本地网关执行 PII（个人身份信息）自动脱敏。
|
||||
* **审计链**：记录从 AI 推理原文到人类点击确权的全链路 TraceID。
|
||||
|
||||
## **9\. 实施阶段计划**
|
||||
|
||||
* **Phase 1 (连接)**：打通 REDCap Webhook 与 Node.js，上线微信周报确认功能。
|
||||
* **Phase 2 (协同)**：上线 PC Workbench 核心组件，实现质控影子建议的闭环。
|
||||
* **Phase 3 (增强)**：集成 Python 微服务的 OCR/DC 模块，开启智能化数据采集。
|
||||
* **Phase 4 (生态)**：完成 100+ 项目规模化配置方案，预研 AI 原生 SmartEDC。
|
||||
|
||||
**文档版本**：V4.0 Final | **更新日期**：2025-12-30 | **作者**：产品架构团队
|
||||
@@ -0,0 +1,83 @@
|
||||
# **IIT Manager Agent 技术架构白皮书 (V3.0 生产级架构版)**
|
||||
|
||||
## **1\. 架构愿景：逻辑回归中心，知识驱动未来**
|
||||
|
||||
本架构旨在解决临床研究中 AI 落地最核心的三个矛盾：**“AI 的不可控性”与“医疗的严谨性”**、**“异构系统的碎片化”与“管理的一体化”**、**“数据隐私”与“模型效能”**。
|
||||
|
||||
* **原生编排 (Native Orchestration)**：将核心逻辑与状态机（State Machine）保留在 **Node.js (Fastify) \+ pg-boss** 中。不迷信外部 Agent 框架，确保 SOP 流程在代码级可定义、可测试、可审计。
|
||||
* **薄认知、厚逻辑**：将 **Dify** 定位于高性能的 **RAG Service**。利用其成熟的文档解析与召回管线，而将决策权、权限控制和事务一致性收回到自研后端。
|
||||
|
||||
## **2\. “四层三中心”架构设计**
|
||||
|
||||
### **2.1 架构分层 (Layered Architecture)**
|
||||
|
||||
1. **交互层 (Interaction Layer)**：
|
||||
* **微信/企微终端**：PI 接收周报、患者 AI 咨询及任务提醒。
|
||||
* **Agent Workbench (基于 Ant Design X)**：CRC 处理 AI 建议、执行质控确认的“驾驶舱”。
|
||||
2. **逻辑与智能体层 (Logic & Agent Layer)**：
|
||||
* **Agent Orchestrator**：基于 Node.js 的中央编排器，驱动 pg-boss 任务流。
|
||||
* **Shadow State 机制**：AI 建议在被人类确认前，仅以“影子数据”形式存在。
|
||||
3. **连接适配层 (Connectivity Layer)**：
|
||||
* **EDC Adapter**：非侵入式对接 REDCap (REST API / Webhooks)。
|
||||
* **Dify RAG Adapter**：封装多知识库检索 API，执行向量检索。
|
||||
* **Python Execution Service**：执行 OCR、医学 NER 及复杂统计算法（如 MICE）。
|
||||
4. **基础设施层 (Infrastructure)**：
|
||||
* **Postgres-Only 中枢**：统一管理任务队列、应用缓存及业务数据（iit\_schema）。
|
||||
|
||||
### **2.2 三大中心 (System Centers)**
|
||||
|
||||
* **真理中心 (REDCap)**：临床数据的唯一合法来源。
|
||||
* **状态中心 (RDS Postgres)**：管理 Agent 状态、审计日志、用户映射。
|
||||
* **知识中心 (Dify / PGVector)**：存储数字化方案及医学知识库。
|
||||
|
||||
## **3\. 核心技术机制深度解析**
|
||||
|
||||
### **3.1 影子状态 (Shadow State) 与人机闭环**
|
||||
|
||||
为规避 AI 幻觉带来的数据错误，引入“影子状态”：
|
||||
|
||||
1. **AI 生成建议**：Agent 产生的结果存入 iit\_schema.pending\_actions。
|
||||
2. **证据链溯源**：在 Workbench 中，AI 建议必须与 Dify 返回的原文片段（页码/坐标）强绑定。
|
||||
3. **人类确权**：CRC/PI 确认后，触发事务。
|
||||
4. **正式写入**：调用 EDC Adapter 将数据写入 REDCap，并记录“AI-ID \+ Human-ID”的双重签名。
|
||||
|
||||
### **3.2 基于 Dify 的多知识库 RAG 管线**
|
||||
|
||||
* **多源检索**：针对同一决策，Agent 同时检索“研究方案”、“临床指南”和“历史质控记录”。
|
||||
* **混合召回**：利用 Dify 的向量检索 \+ 全文检索 \+ Rerank 机制，确保上下文（Context）的极端准确。
|
||||
* **脱敏安全**：在 Node.js 调用 Dify 接口前，利用 LLM Gateway 执行 PII (个人身份信息) 的本地化扫描与屏蔽。
|
||||
|
||||
### **3.3 跨体系身份映射 (Identity Mapping)**
|
||||
|
||||
* 建立加密存储的 User-EDC-Credential 体系。
|
||||
* Agent 的每一个动作都通过 API 代理模拟真实用户的 REDCap 权限，确保数据访问的合规性（Audit Trail 符合 21 CFR Part 11）。
|
||||
|
||||
## **4\. 部署与性能优化策略**
|
||||
|
||||
### **4.1 混合云部署蓝图**
|
||||
|
||||
* **AI 控制平面 (SAE)**：Node.js 后端与 Python 微服务运行在 Serverless 环境，根据任务负载弹性伸缩。
|
||||
* **数据底座 (ECS \+ RDS)**：REDCap 运行在 ECS，通过阿里云 VPC 内网与 SAE 通信，降低延迟且数据不出内网。
|
||||
* **Dify 节点**：独立容器部署，仅作为 RAG 接口对内提供服务。
|
||||
|
||||
### **4.2 任务可靠性**
|
||||
|
||||
* 利用 pg-boss 的指数退避重试机制处理 Webhook 丢失或 REDCap 接口超时。
|
||||
* 支持长达 24 小时的长任务监控（如患者体征趋势分析）。
|
||||
|
||||
## **5\. 风险评估与对冲**
|
||||
|
||||
| 潜在风险 | 应对策略 |
|
||||
| :---- | :---- |
|
||||
| **逻辑代码膨胀** | 采用“微引擎化”设计，将质控规则参数化并存储在 JSONB 字段中。 |
|
||||
| **Dify 接口延迟** | 对常用 RAG 背景信息在 app\_cache 中进行短时缓存。 |
|
||||
| **未来扩展性需求** | 预留状态机接口，逻辑同构设计支持未来向 LangGraph 的平滑迁移。 |
|
||||
|
||||
## **6\. 实施路线图 (Milestones)**
|
||||
|
||||
1. **Phase 1: 连接与感知**：打通 REDCap 读写适配器，上线微信端智能周报。
|
||||
2. **Phase 2: 工作站与协同**：完成 Agent Workbench 开发，实现“质控建议-人类确认”的影子闭环。
|
||||
3. **Phase 3: 全自动采集**：开启多模态 OCR 提取，结合 RAG 知识库实现数据的一键同步。
|
||||
4. **Phase 4: 智能化演进**：探索基于多智能体对抗（Critic Loop）的深度质控，并预研 SmartEDC 原型。
|
||||
|
||||
**文档版本**：V3.0 | **最后更新**：2025-12-30 | **维护者**：架构组
|
||||
@@ -0,0 +1,72 @@
|
||||
# **IIT Manager Agent 项目实施战略与 MVP 路线图**
|
||||
|
||||
## **1\. 核心战略：以“感知”驱动“信任”**
|
||||
|
||||
在 Phase 1，我们不急于实现“全自动数据搬运”，因为“写”的合规风险和技术门槛最高。我们应优先实现\*\*“智能感知与主动预警”\*\*。
|
||||
|
||||
**MVP 的定义：**
|
||||
|
||||
能够实时监听 REDCap 录入，利用 Dify RAG 发现逻辑偏差，并推送到 PI 的微信端进行预警。
|
||||
|
||||
## **2\. 三大里程碑 (Milestones)**
|
||||
|
||||
### **里程碑 1：通路搭建（“路要通”）**
|
||||
|
||||
* **目标**：建立 REDCap \-\> Node.js \-\> 微信的闭环。
|
||||
* **关键任务**：
|
||||
* **环境初始化**：SAE 部署后端，RDS 初始化 iit\_schema。
|
||||
* **EDC 适配器**：完成 REDCap External Module (EM) 基础开发，实现保存记录时的 Webhook 触发。
|
||||
* **微信联通**：完成企业微信应用创建与消息推送接口对接。
|
||||
|
||||
### **里程碑 2：智能注入（“脑要灵”）**
|
||||
|
||||
* **目标**：实现 AI 对临床方案的深度理解。
|
||||
* **关键任务**：
|
||||
* **Dify 知识库**：上传 1-2 份标准临床协议，调试 RAG 检索参数。
|
||||
* **Prompt 调优**：编写并测试“数据质控 Agent”提示词，确保其输出符合我们的 JSON 协议。
|
||||
* **影子生成**：实现后端自动生成 PendingAction 记录。
|
||||
|
||||
### **里程碑 3：闭环协同（“活要细”）**
|
||||
|
||||
* **目标**：上线 PC Workbench 和 PI 小程序，实现人机确认。
|
||||
* **关键任务**：
|
||||
* **Workbench 骨架**：基于 Ant Design X 实现任务列表与证据对比区。
|
||||
* **PI 小程序**：实现品牌化报表展示与移动端一键审批。
|
||||
* **回写闭环**：实现 APPROVED 状态后的 REDCap API 自动回写。
|
||||
|
||||
## **3\. 当前最重要的技术攻坚点 (Technical Hard Rocks)**
|
||||
|
||||
### **3.1 REDCap EM 的非侵入式“侧挂” (P0)**
|
||||
|
||||
* **挑战**：如何在不破坏医院既有 REDCap 环境的前提下，稳定地把数据“钩”出来。
|
||||
* **对策**：利用 REDCap 官方的 External Module 框架，只做数据转发，不做业务处理。
|
||||
|
||||
### **3.2 证据链的“精准定位” (P0)**
|
||||
|
||||
* **挑战**：Dify 返回的文字片段如何转化成前端 PDF 预览的高亮坐标。
|
||||
* **对策**：在 Dify 侧配置支持返回 metadata（含页码），前端实现一个轻量级的 PDF.js 高亮层。
|
||||
|
||||
### **3.3 任务引擎的“长周期调度” (P1)**
|
||||
|
||||
* **挑战**：临床研究持续数月甚至数年，如何保证任务不丢失、不重复。
|
||||
* **对策**：利用 pg-boss 的持久化队列，结合 Postgres 事务保证状态一致性。
|
||||
|
||||
## **4\. MVP 版本功能清单 (Scope for MVP)**
|
||||
|
||||
为了让用户快速见到东西，MVP 建议仅包含以下功能：
|
||||
|
||||
1. **项目初始化**：手动输入 5 个关键变量映射（暂不做全量自动映射）。
|
||||
2. **实时质控预警**：针对“年龄、性别、核心入排标准”进行 AI 检查。
|
||||
3. **微信消息推送**：当录入违背方案时，PI 收到企微卡片。
|
||||
4. **PC 简易工作站**：查看违背详情和 AI 给出的证据片段。
|
||||
|
||||
## **5\. 建议的行动顺序 (Next Steps)**
|
||||
|
||||
1. **立刻执行 (Day 1-3)**：
|
||||
* 注册并认证企业微信开发者主体。
|
||||
* 在阿里云 SAE 搭建第一个 Node.js Hello World，并调通企业微信推送 API。
|
||||
2. **同步推进 (Day 1-7)**：
|
||||
* 由一位前端工程师基于我们的 HTML 原生开始搭建 React 版本的 Workbench 骨架。
|
||||
* 由一位后端工程师开始编写 REDCap EM 插件的 PHP 代码。
|
||||
|
||||
**当前阶段**：Ready to Code | **目标日期**：2 周内完成 MVP 演示闭环
|
||||
Reference in New Issue
Block a user