# 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 自动对齐工具 |