HaHafeng
5db4a7064c
Summary: - Add 4 new database tables: iit_field_metadata, iit_qc_logs, iit_record_summary, iit_qc_project_stats - Implement pg-boss debounce mechanism in WebhookController - Refactor QC Worker for dual output: QC logs + record summary - Enhance HardRuleEngine to support form-based rule filtering - Create QcService for QC data queries - Optimize ChatService with new intents: query_enrollment, query_qc_status - Add admin batch operations: one-click full QC + one-click full summary - Create IIT Admin management module: project config, QC rules, user mapping Status: Code complete, pending end-to-end testing Co-authored-by: Cursor <cursoragent@cursor.com>
353 lines
19 KiB
Markdown
353 lines
19 KiB
Markdown
# IIT Manager Agent V2.6 综合开发计划
|
||
|
||
> **版本：** V2.9.1（极简架构 + SOP状态机 + 双脑路由 + 三层记忆 + 主动性增强 + 隐私合规）
|
||
> **日期：** 2026-02-05
|
||
> **团队规模：** 2人
|
||
> **预估周期：** 6周
|
||
> **核心目标：** 实现数据质控 Agent 的完整闭环 + 智能化交互 + 长期记忆 + 主动提醒 + 个性化 + **隐私合规**
|
||
|
||
---
|
||
|
||
## 📚 文档导航
|
||
|
||
本开发计划已拆分为多个专项文档，便于查阅和维护：
|
||
|
||
| 文档 | 内容 | 适用场景 |
|
||
|------|------|----------|
|
||
| **本文档** | 架构总览、设计原则、验收标准 | 项目概览、立项汇报 |
|
||
| [01-数据库设计](./01-数据库设计.md) | Prisma 模型、索引设计、初始化 SQL | 数据库开发 |
|
||
| [02-核心引擎实现指南](./02-核心引擎实现指南.md) | HardRuleEngine、SoftRuleEngine、SopEngine、ReActEngine | 引擎开发 |
|
||
| [03-服务层实现指南](./03-服务层实现指南.md) | ToolsService、ChatService、IntentService 等 | 服务开发 |
|
||
| [04-记忆系统实现指南](./04-记忆系统实现指南.md) | V2.8 三层记忆架构、MemoryService | 记忆功能开发 |
|
||
| [05-开发阶段与任务清单](./05-开发阶段与任务清单.md) | Phase 1-6 详细任务、里程碑、验收标准 | 项目管理、进度跟踪 |
|
||
|
||
---
|
||
|
||
## 0. 架构适配性评估
|
||
|
||
本架构设计充分考虑了临床研究的多种业务场景，通过 **SOP状态机 + 双引擎 + 可扩展工具层** 的设计，实现了良好的适配性和扩展性。
|
||
|
||
### 0.1 目标场景覆盖度
|
||
|
||
| 场景 | 覆盖度 | 核心支撑组件 | 备注 |
|
||
|------|--------|-------------|------|
|
||
| **1. 拍照识别 + 自动录入** | 🟡 60% | VisionService + ToolsService | 延后到 V3.0 |
|
||
| **2. 数据质控** | 🟢 95% | HardRuleEngine + SoftRuleEngine | 核心场景 |
|
||
| **3. 入排标准判断** | 🟢 90% | SopEngine + 硬规则配置 | 配置 Skill 即可 |
|
||
| **4. 方案偏离检测** | 🟢 80% | SoftRuleEngine + search_protocol | 需配置访视窗口规则 |
|
||
| **5. AE事件检测** | 🟢 80% | 硬规则触发 + 软指令评估 | 需配置AE识别规则 |
|
||
| **6. 伦理合规检测** | 🟢 80% | HardRuleEngine | 配置伦理规则即可 |
|
||
| **7. 定期报告生成** | 🟡 50% | SchedulerService + ReportService | Phase 4 实现 |
|
||
|
||
### 0.2 架构扩展性评价
|
||
|
||
| 扩展维度 | 实现方式 | 复杂度 |
|
||
|----------|----------|--------|
|
||
| **新增质控规则** | 在 `iit_skills` 表插入 JSON 配置 | ⭐ 低 |
|
||
| **新增业务场景** | 新增 Skill 类型 + 配置 SOP 流程 | ⭐⭐ 中低 |
|
||
| **新增工具能力** | 在 ToolsService 增加工具定义 | ⭐⭐ 中低 |
|
||
| **新增数据源** | 新增 Adapter（如 OdmAdapter） | ⭐⭐⭐ 中 |
|
||
|
||
---
|
||
|
||
## 1. 架构决策总结
|
||
|
||
本计划基于以下架构设计文档的综合审查：
|
||
|
||
| 文档 | 核心观点 | 状态 |
|
||
|------|----------|------|
|
||
| **架构决策白皮书** | Postgres-Only + Service-First | ✅ 认可 |
|
||
| **V2.2 实施指南** | 混合双引擎（硬规则 + 软指令） | ✅ 认可 |
|
||
| **V2.2 工具泛化** | 3-5 个通用工具替代 100 个专用工具 | ✅ 认可 |
|
||
| **V2.3 健壮性设计** | 三层防御（映射 + 重试 + 兜底） | ✅ 认可 |
|
||
| **V2.4 SOP状态机** | 粗粒度 SOP 节点 + 节点内 ReAct | ✅ 认可 |
|
||
| **V2.8 记忆系统** | 三层记忆（流水账 + 热记忆 + 历史书） | ✅ 认可 |
|
||
| **V2.9 主动性增强** | Cron Skill + 用户画像 + 反馈循环 | ✅ 认可 |
|
||
| **V2.9.1 隐私合规** | PII 脱敏中间件 + REDCap Schema 自动对齐 | ✅ 认可 |
|
||
|
||
### 1.0 V2.9.1 隐私合规增强（P0 必需）
|
||
|
||
> **⚠️ 重要**：临床数据包含大量患者隐私信息，在调用第三方 LLM 之前**必须脱敏**！
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ V2.9.1 隐私合规能力 │
|
||
├─────────────────────────────────┬───────────────────────────────────┤
|
||
│ 🔒 AnonymizerService │ 🔧 AutoMapperService │
|
||
│ PII 脱敏中间件 │ REDCap Schema 自动对齐 │
|
||
│ - 身份证号脱敏 │ - Data Dictionary 解析 │
|
||
│ - 手机号脱敏 │ - LLM 语义映射 │
|
||
│ - 中文姓名脱敏 │ - 人工确认 UI │
|
||
│ - 审计日志加密存储 │ - 效率提升 8-16x │
|
||
└─────────────────────────────────┴───────────────────────────────────┘
|
||
```
|
||
|
||
| 能力 | 实现方式 | 价值 |
|
||
|------|----------|------|
|
||
| **PII 脱敏** | `AnonymizerService.mask/unmask()` + 正则库 | 合规必需，防止隐私泄露 |
|
||
| **审计日志** | `iit_pii_audit_log` 表 + 加密存储 | 事后合规审计 |
|
||
| **Schema 自动对齐** | `AutoMapperService` + LLM 语义匹配 | 字段配置效率提升 8-16x |
|
||
|
||
### 1.1 V2.9 核心增强
|
||
|
||
> **目标**：让 Agent 从"被动应答"进化为"主动协作"，同时根据用户反馈持续优化
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ V2.9 新增能力 │
|
||
├──────────────────┬──────────────────┬───────────────────────────────┤
|
||
│ 🔔 Cron Skill │ 👤 用户画像 │ 📊 反馈循环 │
|
||
│ 主动触发 SOP │ 个性化响应 │ 持续优化 │
|
||
│ 定时访视提醒 │ 最佳通知时间 │ 偏好自动调整 │
|
||
└──────────────────┴──────────────────┴───────────────────────────────┘
|
||
```
|
||
|
||
| 能力 | 实现方式 | 价值 |
|
||
|------|----------|------|
|
||
| **Cron Skill** | `iit_skills.triggerType = 'cron'` + pg-boss 调度 | 访视提醒、周报自动发送 |
|
||
| **用户画像** | `project_memory` 中存储用户偏好 Markdown | 回复风格个性化 |
|
||
| **反馈循环** | `conversation_history.feedback` 字段 | 持续改进回复质量 |
|
||
| **多意图处理** | ReAct Prompt 优化 + Chain of Thought | 一句话多任务 |
|
||
|
||
### 1.1 双脑路由模型
|
||
|
||
> **核心理念**：左脑(SOP) 保证严谨合规，右脑(ReAct) 提供灵活智能
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 企业微信 / 前端入口 │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 🧠 意图路由层 (IntentService) │
|
||
│ 混合路由：正则快速通道 + LLM 后备 │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||
│ 📐 左脑 (SOP) │ │ 🎨 右脑 (ReAct) │ │ ❓ 追问机制 │
|
||
│ 结构化任务 │ │ 开放性查询 │ │ 信息不全 │
|
||
│ 写操作必经 │ │ 只读不写 │ │ 主动澄清 │
|
||
└──────────────────┘ └──────────────────┘ └──────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ ToolsService (工具层) │
|
||
│ 🔓 只读工具 (ReAct 可用) │ 🔒 读写工具 (仅 SOP 可用) │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**双脑对比**：
|
||
|
||
| 维度 | 左脑 (SOP 状态机) | 右脑 (ReAct Agent) |
|
||
|------|-------------------|-------------------|
|
||
| **擅长** | 执行标准流程、合规检查 | 处理模糊提问、多步查询 |
|
||
| **典型指令** | "对 P001 进行入排质控" | "帮我查下最近那个发烧的病人" |
|
||
| **数据权限** | 读写皆可 | **只读 (Read-Only)** |
|
||
|
||
### 1.2 核心设计原则
|
||
|
||
| 原则 | 描述 |
|
||
|------|------|
|
||
| **Postgres-Only** | 无 Redis，用 pg-boss 替代队列 |
|
||
| **Service-First** | 不用 MCP Server，用 Service Class |
|
||
| **混合双引擎** | 硬规则(CPU) + 软指令(LLM) |
|
||
| **SOP 状态机** | 粗粒度节点 + 节点内灵活性 |
|
||
| **主动协作 (V2.9)** | Cron Skill 主动触发 + 用户画像个性化 |
|
||
| **反馈驱动 (V2.9)** | 用户反馈自动调整偏好 |
|
||
| **三层防御** | 字段映射 + 自我修正 + 空结果兜底 |
|
||
| **三层记忆** | 流水账(L1) + 热记忆(L2) + 历史书(L3) |
|
||
|
||
### 1.3 三层记忆架构 (V2.8)
|
||
|
||
> **关键洞察**：临床研究项目持续 1-3 年，Agent 必须具备长期记忆能力
|
||
|
||
| 层级 | 名称 | 存储位置 | 生命周期 | 检索方式 |
|
||
|------|------|----------|----------|----------|
|
||
| L1 | 流水账 | conversation_history | 30天 | 按需向量检索 |
|
||
| L2 | 热记忆 | project_memory | 持久 | 每次注入 |
|
||
| L3 | 历史书 | weekly_reports | 持久 | 按意图检索 |
|
||
|
||
> 📖 详细实现请参阅 [04-记忆系统实现指南](./04-记忆系统实现指南.md)
|
||
|
||
---
|
||
|
||
## 2. 组件总览
|
||
|
||
### 2.1 已完成组件
|
||
|
||
| 组件 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| ChatService | `services/ChatService.ts` | ✅ 需扩展 |
|
||
| SessionMemory | `agents/SessionMemory.ts` | ✅ 可复用 |
|
||
| RedcapAdapter | `adapters/RedcapAdapter.ts` | ✅ 可复用 |
|
||
| WechatService | `services/WechatService.ts` | ✅ 可复用 |
|
||
| DifyClient | `common/rag/DifyClient.ts` | ✅ 可复用 |
|
||
| LLMFactory | `common/llm/adapters/LLMFactory.ts` | ✅ 可复用 |
|
||
|
||
### 2.2 待开发组件
|
||
|
||
| 组件 | 优先级 | Phase | 详细文档 |
|
||
|------|--------|-------|----------|
|
||
| `iit_skills` 表 | P0 | 1 | [01-数据库设计](./01-数据库设计.md) |
|
||
| `iit_field_mapping` 表 | P0 | 1 | [01-数据库设计](./01-数据库设计.md) |
|
||
| `ToolsService` 类 | P0 | 1 | [03-服务层实现指南](./03-服务层实现指南.md) |
|
||
| `HardRuleEngine` 类 | P0 | 1 | [02-核心引擎实现指南](./02-核心引擎实现指南.md) |
|
||
| `SoftRuleEngine` 类 | P1 | 2 | [02-核心引擎实现指南](./02-核心引擎实现指南.md) |
|
||
| `SopEngine` 类 | P1 | 2 | [02-核心引擎实现指南](./02-核心引擎实现指南.md) |
|
||
| `MemoryService` 类 | P1 | 2-3 | [04-记忆系统实现指南](./04-记忆系统实现指南.md) |
|
||
| `ReActEngine` 类 | P1 | 3 | [02-核心引擎实现指南](./02-核心引擎实现指南.md) |
|
||
| `IntentService` 类 | P1 | 5 | [03-服务层实现指南](./03-服务层实现指南.md) |
|
||
| `SchedulerService` 类 | P2 | 4 | [03-服务层实现指南](./03-服务层实现指南.md) |
|
||
|
||
---
|
||
|
||
## 3. 开发阶段总览
|
||
|
||
> 📖 详细任务清单请参阅 [05-开发阶段与任务清单](./05-开发阶段与任务清单.md)
|
||
|
||
| Phase | 名称 | 周期 | 核心交付物 |
|
||
|-------|------|------|-----------|
|
||
| **Phase 1** | 基础工具层 | Week 1 | ToolsService, HardRuleEngine, 字段映射 |
|
||
| **Phase 2** | SOP 引擎 + 热记忆 | Week 2 | SopEngine, SoftRuleEngine, L2 热记忆 |
|
||
| **Phase 3** | ReAct 引擎 + 流水账 | Week 3 | ReActEngine, L1 流水账, 向量检索 |
|
||
| **Phase 4** | 调度系统 + 历史书 | Week 4 前半 | SchedulerService, ReportService, L3 历史书 |
|
||
| **Phase 5** | 智能路由 | Week 4 后半 - Week 5 | IntentService, 混合路由, 追问机制 |
|
||
| **Phase 6** | 视觉能力 | Week 6 (延后) | VisionService (延后到 V3.0) |
|
||
|
||
```
|
||
Phase 1 Phase 2 Phase 3 Phase 4 Phase 5 Phase 6
|
||
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
|
||
│ 基础工具 │ ──▶ │SOP引擎 │ ──▶ │ReAct │ ──▶ │ 调度 │ ──▶ │智能路由 │ ──▶ │视觉能力 │
|
||
│ 层 │ │+ 热记忆 │ │+ 流水账│ │+ 历史书│ │ │ │(延后) │
|
||
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 风险与应对
|
||
|
||
### 4.1 已采纳的风险对策
|
||
|
||
| 风险 | 已采纳对策 | 状态 |
|
||
|------|------------|------|
|
||
| **意图路由延迟感** | 混合路由（正则+LLM）+ 流式反馈 | ✅ 已整合 |
|
||
| **ReAct 多嘴** | 只返回 Final Answer，Trace 存日志 | ✅ 已整合 |
|
||
| **SOP 状态机死锁** | SUSPENDED 挂起机制 + 唤醒机制 | ✅ 已整合 |
|
||
| **Phase 6 过早** | 延后到 V3.0 | ✅ 已标记 |
|
||
|
||
### 4.2 聚焦清单（P0 优先级）
|
||
|
||
| 优先级 | 功能 | 理由 |
|
||
|--------|------|------|
|
||
| **P0** | ToolsService 健壮性 | 字段映射是地基 |
|
||
| **P0** | 每日早报 (Morning Brief) | 用户感知最强 |
|
||
| **P0** | 意图路由混合模式 | 保证响应速度 + 降低成本 |
|
||
|
||
### 4.3 主要风险矩阵
|
||
|
||
| 风险类别 | 风险 | 应对措施 |
|
||
|----------|------|----------|
|
||
| **基础架构** | LLM 响应慢 | 硬规则先行 + 混合路由 |
|
||
| **双脑架构** | ReAct 死循环 | 最大迭代 5 次 + Token 预算 |
|
||
| **双脑架构** | ReAct 调用写工具 | 工具白名单（只读） |
|
||
| **SOP 状态机** | 人工复核死锁 | SUSPENDED + 唤醒机制 |
|
||
| **扩展能力** | 视觉模型识别错误 | 低置信度人工确认 |
|
||
|
||
---
|
||
|
||
## 5. 成功标准
|
||
|
||
### 5.1 核心验收标准
|
||
|
||
| 阶段 | 验收标准 |
|
||
|------|----------|
|
||
| **Phase 1-3** | 质控任务 3秒内响应；服务重启后任务可恢复；对话历史持久化 |
|
||
| **Phase 4** | 周报每周一自动生成；定时任务连续 7 天无故障 |
|
||
| **Phase 5** | 意图识别准确率 > 85%；用户只收到 Final Answer |
|
||
| **Phase 6** | 图片识别准确率 > 85%（延后到 V3.0） |
|
||
|
||
### 5.2 性能指标
|
||
|
||
| 指标 | 目标值 |
|
||
|------|--------|
|
||
| 硬规则执行时间 | < 100ms |
|
||
| 软指令执行时间 | < 3s |
|
||
| 端到端响应时间 | < 5s |
|
||
| 正则快速通道延迟 | < 50ms |
|
||
| 意图识别时间（LLM） | < 1s |
|
||
| 向量检索延迟 | < 100ms |
|
||
| ReAct 平均迭代次数 | < 3 |
|
||
|
||
---
|
||
|
||
## 6. 文件路径清单
|
||
|
||
```
|
||
backend/src/modules/iit-manager/
|
||
├── services/
|
||
│ ├── ChatService.ts # 扩展：双脑路由 + 记忆集成
|
||
│ ├── IntentService.ts # 新建：意图识别 (Phase 5)
|
||
│ ├── ToolsService.ts # 新建：统一工具管理 (Phase 1)
|
||
│ ├── MemoryService.ts # 新建：三层记忆管理 (Phase 2-3)
|
||
│ ├── SchedulerService.ts # 新建：定时任务调度 (Phase 4)
|
||
│ └── ReportService.ts # 新建：报告生成 (Phase 4)
|
||
├── engines/
|
||
│ ├── HardRuleEngine.ts # 新建：JSON Logic 执行器 (Phase 1)
|
||
│ ├── SoftRuleEngine.ts # 新建：LLM 推理引擎 (Phase 2)
|
||
│ ├── SopEngine.ts # 新建：状态机调度器 (Phase 2)
|
||
│ └── ReActEngine.ts # 新建：多步推理引擎 (Phase 3)
|
||
├── agents/
|
||
│ └── SessionMemory.ts # 扩展：实体记忆 (Phase 5)
|
||
└── adapters/
|
||
└── RedcapAdapter.ts # 扩展：writeRecord()
|
||
```
|
||
|
||
### 数据库新增表
|
||
|
||
> 📖 详细 Schema 请参阅 [01-数据库设计](./01-数据库设计.md)
|
||
|
||
| 表名 | 用途 | Phase |
|
||
|------|------|-------|
|
||
| `iit_skills` | Skill 配置存储 | 1 |
|
||
| `iit_field_mapping` | 字段名映射 | 1 |
|
||
| `iit_task_run` | SOP 任务执行记录 | 2 |
|
||
| `iit_pending_actions` | 待确认操作 | 2 |
|
||
| `iit_project_memory` | 热记忆（L2） | 2 |
|
||
| `iit_conversation_history` | 流水账（L1） | 2 |
|
||
| `iit_weekly_reports` | 历史书-周报（L3） | 4 |
|
||
| `iit_agent_trace` | ReAct 推理轨迹 | 3 |
|
||
|
||
---
|
||
|
||
## 7. 参考文档
|
||
|
||
### 架构设计文档
|
||
|
||
1. [架构决策白皮书：极简主义的胜利](../00-系统设计/IIT%20Manager%20Agent%20架构决策白皮书：极简主义的胜利.md)
|
||
2. [V2.2 落地实施指南](../00-系统设计/IIT%20Manager%20Agent%20V2.2%20落地实施指南.md)
|
||
3. [V2.3 健壮性设计与最佳实践](../00-系统设计/IIT%20Manager%20Agent%20V2.3.md)
|
||
4. [V2.4 SOP 状态机推荐](../00-系统设计/IIT%20Manager%20Agent%20V2.4.md)
|
||
5. [V2.6 双脑架构](../00-系统设计/IIT%20Manager%20Agent%20V2.6.md)
|
||
|
||
### 审核文档
|
||
|
||
1. [潜在的具体风险与问题](../05-测试文档/潜在的具体风险与问题.md)
|
||
2. [V2.8 记忆系统设计](../05-测试文档/IIT%20Manager%20Agent%20V2.8.md)
|
||
|
||
---
|
||
|
||
**文档维护人**：AI Agent
|
||
**最后更新**：2026-02-05
|
||
|
||
### 更新日志
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
|------|------|----------|
|
||
| V2.6 | 2026-02-02 | 整合双脑架构 + 三层记忆体系 |
|
||
| V2.6.1 | 2026-02-05 | 整合团队风险审查建议；拆分为多个专项文档 |
|
||
| V2.6.2 | 2026-02-05 | 简化表结构：删除 `iit_user_preferences` 和 `iit_patient_notes`（合并到 `project_memory`） |
|
||
| V2.9 | 2026-02-05 | 主动性增强：Cron Skill、用户画像、反馈循环、多意图处理 |
|
||
| V2.9.1 | 2026-02-05 | 隐私合规：PII 脱敏中间件、REDCap Schema 自动对齐工具 |
|