# Protocol Agent 分阶段实施计划

> 版本：v1.0  
> 创建日期：2026-01-24

---

## 一、总体规划

### 1.1 阶段划分

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Protocol Agent 开发路线图                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Phase 1: MVP完整功能 (4周)                                                  │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                                                                      │   │
│  │  Sprint 1 (W1)      Sprint 2 (W2)      Sprint 3 (W3)     Sprint 4 (W4) │
│  │  ┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────┐  │   │
│  │  │ 框架搭建 │  →   │ 核心对话 │  →   │ 前端UI  │  →   │ 一键生成 │  │   │
│  │  │ 数据库   │      │ 5阶段流程│      │ State   │      │ Word导出 │  │   │
│  │  │ 类型定义 │      │ Prompt   │      │ Panel   │      │ Prompt   │  │   │
│  │  │          │      │ Context  │      │ 同步按钮│      │ 调优测试 │  │   │
│  │  └──────────┘      └──────────┘      └──────────┘      └──────────┘  │   │
│  │                                                                      │   │
│  │  交付物：完整MVP，用户可通过对话完成5阶段，一键生成研究方案并下载Word │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ─────────────────────────────────────────────────────────────────────────  │
│                                                                             │
│  Phase 2: 知识增强 (3周)             Phase 3: 平台化 (2周)                   │
│  ┌─────────────────────────┐        ┌─────────────────────────┐            │
│  │ □ EKB知识库建设         │        │ □ 后台配置管理          │            │
│  │ □ RAG检索集成           │   →    │ □ Prompt在线调试        │            │
│  │ □ Function Calling      │        │ □ 完整Trace分析         │            │
│  │ □ 高级Reflexion         │        │ □ 多Agent支持           │            │
│  └─────────────────────────┘        └─────────────────────────┘            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 1.2 里程碑定义

| 里程碑 | 时间 | 交付物 | 验收标准 |
|--------|------|--------|----------|
| M1 | Week 2 | Agent框架 + 基础对话 | 能完成单阶段对话，Context正确存储 |
| **M2** | **Week 4** | **MVP完整功能** | **5阶段对话 + 一键生成 + Word下载** |
| M3 | Week 7 | 知识增强版本 | RAG检索集成可用 |
| M4 | Week 9 | 平台化版本 | 后台配置管理可用 |

---

## 二、Phase 1 详细计划（4周）

### Sprint 1: 基础框架搭建（Week 1）

**目标**：建立可复用的Agent框架骨架

#### 任务列表

| ID | 任务 | 优先级 | 预估 | 负责人 | 状态 |
|----|------|--------|------|--------|------|
| 1.1 | 创建agent_schema数据库迁移 | P0 | 4h | - | ⬜ |
| 1.2 | 创建protocol_schema数据库迁移 | P0 | 2h | - | ⬜ |
| 1.3 | 定义核心类型（types/*.ts） | P0 | 3h | - | ⬜ |
| 1.4 | 实现ConfigLoader | P0 | 2h | - | ⬜ |
| 1.5 | 实现BaseAgentOrchestrator抽象类 | P0 | 4h | - | ⬜ |
| 1.6 | 实现QueryAnalyzer | P0 | 3h | - | ⬜ |
| 1.7 | 实现Planner + StageManager | P0 | 3h | - | ⬜ |
| 1.8 | 实现TraceLogger | P1 | 2h | - | ⬜ |
| 1.9 | 创建Protocol Agent初始配置数据 | P0 | 2h | - | ⬜ |

**Sprint 1 产出**：
- [ ] 数据库Schema创建完成
- [ ] 核心框架代码结构建立
- [ ] Agent配置可从数据库加载

#### 详细任务说明

**1.1 创建agent_schema数据库迁移**

```bash
# 执行步骤
1. 更新 schema.prisma，添加 agent_schema 到 schemas 列表
2. 添加所有 agent_schema 表定义
3. 运行 npx prisma migrate dev --name add_agent_framework
4. 验证表创建成功
```

**1.5 实现BaseAgentOrchestrator抽象类**

```typescript
// 核心方法清单
- constructor(dependencies)
- abstract getAgentId(): string
- abstract getContextSchema(): TContext
- async handleMessage(conversationId, userMessage, messageId): Promise<AgentResponse>
- async handleStageComplete(conversationId): Promise<StageTransitionResult>
- protected getSession(conversationId): Promise<AgentSessionState>
- protected buildResponse(...): AgentResponse
```

---

### Sprint 2: Protocol Agent核心实现（Week 2）

**目标**：实现Protocol Agent的完整对话流程

#### 任务列表

| ID | 任务 | 优先级 | 预估 | 负责人 | 状态 |
|----|------|--------|------|--------|------|
| 2.1 | 实现ProtocolOrchestrator | P0 | 4h | - | ⬜ |
| 2.2 | 实现ProtocolContextService | P0 | 3h | - | ⬜ |
| 2.3 | 实现PromptBuilder | P0 | 3h | - | ⬜ |
| 2.4 | 实现Executor（LLM调用） | P0 | 4h | - | ⬜ |
| 2.5 | 实现ProtocolExtractor（数据提取） | P0 | 4h | - | ⬜ |
| 2.6 | 实现MemoryManager | P1 | 2h | - | ⬜ |
| 2.7 | 编写5个阶段的Prompt配置 | P0 | 4h | - | ⬜ |
| 2.8 | 实现API路由 | P0 | 2h | - | ⬜ |
| 2.9 | 单元测试 | P1 | 3h | - | ⬜ |

**Sprint 2 产出**：
- [ ] Protocol Agent后端完整实现
- [ ] 能通过API完成对话
- [ ] Context正确保存和更新

#### 核心交互模式：对话驱动 + 同步确认

```
【不需要显式的"确认完成"按钮】

用户通过两种方式推进阶段：

1. 同步按钮：AI在对话中显示"同步到方案"按钮，用户点击后数据同步
2. 口头确认：用户说"继续"/"下一步"，AI识别意图后自动进入下一阶段

示例流程：
┌─────────────────────────────────────────────────────┐
│ AI: 我已整理出您的科学问题：                         │
│     "阿司匹林预防老年高血压患者中风的疗效研究"       │
│                                                     │
│     ┌──────────────────┐                            │
│     │ ✅ 同步到方案     │  ← 内嵌在AI回复中         │
│     └──────────────────┘                            │
│                                                     │
│     确认后，我们可以继续进行PICO梳理。               │
├─────────────────────────────────────────────────────┤
│ User: 好的，继续吧                                  │
├─────────────────────────────────────────────────────┤
│ AI: 好的，让我们进入PICO梳理阶段...                 │
└─────────────────────────────────────────────────────┘
```

#### 详细Prompt配置

**科学问题阶段 Prompt**：

```
你正在帮助研究者明确研究的核心科学问题。

引导要点：
1. 询问想解决什么临床问题
2. 了解目标人群是谁
3. 明确期望达成的目标
4. 探讨研究的临床意义

当前已知信息：
{{contextSummary}}

对话策略：
- 用温和专业的语气引导用户
- 当收集到足够信息后，整理出科学问题，并提供"同步到方案"选项
- 同步后，询问用户是否继续进行PICO梳理

如果用户提供了信息，在回复末尾提取：
<extracted_data>
{
  "content": "科学问题表述",
  "clinicalBackground": "临床背景",
  "researchGap": "研究空白",
  "readyToSync": true  // 是否可以同步
}
</extracted_data>
```

**PICO阶段 Prompt**：

```
基于已确定的科学问题，现在需要明确PICO四要素。

科学问题：{{scientificQuestion.content}}

请引导用户确定：
- P (Population): 研究人群的特征和入选标准
- I (Intervention): 干预措施的具体内容
- C (Comparison): 对照组的设置
- O (Outcome): 主要和次要结局指标

对话策略：
- 可以分多轮逐步收集各要素
- 当四要素都明确后，提供"同步到方案"选项
- 同步后，询问用户是否继续进行研究设计

提取格式：
<extracted_data>
{
  "P": {"value": "", "details": ""},
  "I": {"value": "", "details": ""},
  "C": {"value": "", "details": ""},
  "O": {"value": "", "details": ""},
  "readyToSync": true
}
</extracted_data>
```

**观察指标阶段 Prompt**（新增）：

```
基于PICO中的结局指标(O)，现在需要详细设计观察指标。

已确定的PICO：{{pico}}
研究设计：{{studyDesign}}

请引导用户明确：
1. 主要结局指标（Primary Endpoint）
   - 指标名称、定义、测量方法、评价时点
2. 次要结局指标（Secondary Endpoints）
3. 安全性指标（Safety Endpoints）
4. 探索性指标（Exploratory Endpoints，可选）

对话策略：
- 首先确认主要结局指标，这是最重要的
- 然后引导设置次要和安全性指标
- 当指标体系完整后，提供"同步到方案"选项

提取格式：
<extracted_data>
{
  "primary": [{"name": "", "definition": "", "method": "", "timePoint": ""}],
  "secondary": [...],
  "safety": [...],
  "readyToSync": true
}
</extracted_data>
```

---

### Sprint 3: 前端实现（Week 3）

**目标**：完成State Panel、同步按钮和Action Card UI

#### 任务列表

| ID | 任务 | 优先级 | 预估 | 负责人 | 状态 |
|----|------|--------|------|--------|------|
| 3.1 | Protocol Agent入口页面 | P0 | 2h | - | ⬜ |
| 3.2 | 实现useProtocolAgent Hook | P0 | 3h | - | ⬜ |
| 3.3 | 实现protocolAgentStore | P1 | 2h | - | ⬜ |
| 3.4 | 实现StatePanel组件 | P0 | 4h | - | ⬜ |
| 3.5 | 实现StageProgress组件（5阶段） | P0 | 2h | - | ⬜ |
| 3.6 | 实现ContextDisplay组件 | P0 | 3h | - | ⬜ |
| 3.7 | **实现SyncButton组件（内嵌AI回复）** | P0 | 3h | - | ⬜ |
| 3.8 | 实现ActionCard组件 | P0 | 2h | - | ⬜ |
| 3.9 | 与现有AIStreamChat集成 | P0 | 3h | - | ⬜ |
| 3.10 | 样式调整和响应式 | P1 | 2h | - | ⬜ |

**Sprint 3 产出**：
- [ ] 完整的Protocol Agent界面
- [ ] State Panel实时显示5阶段Context
- [ ] **"同步到方案"按钮内嵌在AI回复中**
- [ ] Action Card交互

#### 核心组件：SyncButton（同步按钮）

```typescript
// SyncButton - 内嵌在AI回复中的同步按钮
interface SyncButtonProps {
  stageId: string;           // 当前阶段
  extractedData: any;        // 要同步的数据
  onSync: () => void;        // 同步回调
  synced: boolean;           // 是否已同步
}

// 在AI回复中的展示效果：
// ┌─────────────────────────────────────────────┐
// │ AI: 我已整理出您的科学问题：                 │
// │     "阿司匹林预防老年高血压患者中风研究"     │
// │                                             │
// │     ┌──────────────────┐                    │
// │     │ ✅ 同步到方案     │  ← SyncButton     │
// │     └──────────────────┘                    │
// │                                             │
// │     同步后我们可以继续下一阶段。             │
// └─────────────────────────────────────────────┘
```

#### 页面布局设计

```
┌─────────────────────────────────────────────────────────────────┐
│  Header: 研究方案制定 Agent      当前阶段: Step 3: 研究设计      │
├───────────────────────────────────┬─────────────────────────────┤
│                                   │                             │
│   Chat Area                       │   State Panel              │
│   ┌─────────────────────────────┐ │   ┌───────────────────────┐│
│   │                             │ │   │ 📋 方案状态 (Context) ││
│   │   AI: 您好！我是研究方案...  │ │   │                       ││
│   │                             │ │   │ 01 科学问题      ✓    ││
│   │   User: 我想做一个糖尿病... │ │   │ 阿司匹林预防老年...    ││
│   │                             │ │   │                       ││
│   │   AI: 好的，我已整理出...   │ │   │ 02 PICO          ✓    ││
│   │       ┌────────────────┐    │ │   │ P: ≥65岁高血压患者    ││
│   │       │ ✅ 同步到方案   │    │ │   │ I: 阿司匹林100mg/d   ││
│   │       └────────────────┘    │ │   │ C: 安慰剂             ││
│   │                             │ │   │ O: 脑卒中发生率       ││
│   │   User: 继续吧              │ │   │                       ││
│   │                             │ │   │ 03 研究设计    (当前) ││
│   │   AI: 好的，进入研究设计... │ │   │ RCT | 双盲 | 多中心   ││
│   │                             │ │   │                       ││
│   │                             │ │   │ 04 样本量       ○     ││
│   │                             │ │   │ 待计算...             ││
│   │                             │ │   │                       ││
│   │                             │ │   │ 05 观察指标     ○     ││
│   │                             │ │   │ 待定义...             ││
│   └─────────────────────────────┘ │   ├───────────────────────┤│
│   ┌─────────────────────────────┐ │   │ 进度: ████░░░░ 40%   ││
│   │ [输入您的指令...]     [发送]│ │   │                       ││
│   └─────────────────────────────┘ │   │ [🚀 一键生成研究方案] ││
│                                   │   │ (5阶段完成后可用)     ││
│                                   │   └───────────────────────┘│
│                                   │                             │
└───────────────────────────────────┴─────────────────────────────┘
```

---

### Sprint 4: 一键生成 + 集成测试（Week 4）

**目标**：实现一键生成研究方案、Prompt调优、端到端测试

#### 任务列表

| ID | 任务 | 优先级 | 预估 | 负责人 | 状态 |
|----|------|--------|------|--------|------|
| 4.1 | **设计研究方案生成Prompt** | P0 | 4h | - | ⬜ |
| 4.2 | **实现ProtocolGenerationService** | P0 | 3h | - | ⬜ |
| 4.3 | **实现生成API端点** | P0 | 2h | - | ⬜ |
| 4.4 | **实现Word文档导出（docx库）** | P0 | 4h | - | ⬜ |
| 4.5 | **前端：一键生成按钮与预览页** | P0 | 4h | - | ⬜ |
| 4.6 | 实现样本量计算器Action Card | P1 | 2h | - | ⬜ |
| 4.7 | Prompt调优（5个阶段） | P0 | 6h | - | ⬜ |
| 4.8 | 端到端测试 | P0 | 4h | - | ⬜ |
| 4.9 | Bug修复和优化 | P0 | 4h | - | ⬜ |
| 4.10 | 文档更新 | P1 | 2h | - | ⬜ |

**Sprint 4 产出**：
- [ ] **一键生成研究方案功能**
- [ ] **Word文档下载**
- [ ] 所有Prompt调优完成
- [ ] 端到端测试通过
- [ ] **MVP可交付**

#### 一键生成研究方案

**触发条件**：5个阶段（科学问题、PICO、研究设计、样本量、观察指标）全部完成

**生成Prompt**：

```markdown
你是一位资深的临床研究方法学专家，请基于以下核心要素生成一份完整、规范的临床研究方案。

## 核心要素

### 科学问题
{{scientificQuestion.content}}

### PICO要素
- **研究人群(P)**: {{pico.P.value}} - {{pico.P.details}}
- **干预措施(I)**: {{pico.I.value}} - {{pico.I.details}}
- **对照措施(C)**: {{pico.C.value}} - {{pico.C.details}}
- **结局指标(O)**: {{pico.O.value}} - {{pico.O.details}}

### 研究设计
- 研究类型: {{studyDesign.type}}
- 盲法: {{studyDesign.blinding}}
- 随机化: {{studyDesign.randomization}}
- 研究周期: {{studyDesign.duration}}

### 样本量
- 总样本量: {{sampleSize.total}}
- 每组: {{sampleSize.perGroup}}
- 计算依据: {{sampleSize.justification}}

### 观察指标
**主要结局指标**: {{endpoints.primary}}
**次要结局指标**: {{endpoints.secondary}}
**安全性指标**: {{endpoints.safety}}

---

请生成包含以下章节的完整研究方案：

1. 研究背景与立题依据
2. 研究目的
3. 研究方法（研究类型、设计、干预、对照）
4. 受试者选择（入选标准、排除标准）
5. 观察指标与评价标准
6. 统计分析计划
7. 质量控制
8. 伦理考虑
9. 研究进度安排

请使用专业规范的学术语言，确保内容完整、逻辑清晰。
```

**Word导出**：

```typescript
// 使用 docx 库生成Word文档
import { Document, Paragraph, TextRun, HeadingLevel, Packer } from 'docx';

async function generateProtocolWord(content: string, metadata: any): Promise<Buffer> {
  const doc = new Document({
    sections: [{
      children: [
        // 封面
        new Paragraph({
          children: [new TextRun({ text: '临床研究方案', bold: true, size: 48 })],
          heading: HeadingLevel.TITLE,
        }),
        // ... 正文（Markdown转docx）
      ]
    }]
  });
  return await Packer.toBuffer(doc);
}
```

#### Reflexion（P2优先级，可延后）

MVP阶段简化处理：
- 在同步前由AI在对话中进行基础检查
- 完整的ReflexionEngine放到Phase 2实现

```
AI回复示例：
"我已整理出您的PICO要素。在同步前，让我确认一下：
 ✓ P: 研究人群已明确
 ✓ I: 干预措施已定义  
 ✓ C: 对照组已设置
 ✓ O: 结局指标已确定
 
 [✅ 同步到方案]"
```

---

## 三、Phase 2 计划概要（3周）

### Sprint 5-6: 知识库建设（Week 5-6）

| ID | 任务 | 优先级 | 预估 |
|----|------|--------|------|
| 6.1 | 创建knowledge_schema数据库迁移 | P0 | 2h |
| 6.2 | 实现KnowledgeDocService | P0 | 4h |
| 6.3 | 实现KnowledgeChunkService | P0 | 3h |
| 6.4 | 集成现有RAG引擎 | P0 | 4h |
| 6.5 | 实现RAGTool | P0 | 3h |
| 6.6 | 准备临床研究方法学知识文档 | P0 | 8h |
| 6.7 | 知识文档分块和向量化 | P0 | 4h |
| 6.8 | RAG检索测试和调优 | P0 | 4h |

### Sprint 7: 高级功能（Week 7）

| ID | 任务 | 优先级 | 预估 |
|----|------|--------|------|
| 7.1 | 实现Function Calling支持 | P1 | 4h |
| 7.2 | 实现ToolRegistry完整功能 | P1 | 3h |
| 7.3 | 添加文献检索工具 | P2 | 4h |
| 7.4 | 实现高级Reflexion（一致性校验） | P1 | 4h |
| 7.5 | 更多Action Card场景 | P1 | 4h |
| 7.6 | Phase 2集成测试 | P0 | 4h |

---

## 四、Phase 3 计划概要（2周）

### Sprint 8-9: 平台化（Week 8-9）

| ID | 任务 | 优先级 | 预估 |
|----|------|--------|------|
| 8.1 | Agent配置管理后台 | P1 | 8h |
| 8.2 | Prompt在线编辑和调试 | P1 | 6h |
| 8.3 | Trace分析可视化 | P2 | 6h |
| 8.4 | 配置热更新支持 | P2 | 4h |
| 8.5 | 多Agent路由支持 | P1 | 4h |
| 8.6 | 统计分析Agent接入准备 | P1 | 4h |
| 8.7 | 最终测试和文档 | P0 | 4h |

---

## 五、风险管理

### 5.1 已识别风险

| 风险 | 可能性 | 影响 | 缓解措施 | 负责人 |
|------|--------|------|----------|--------|
| LLM输出不稳定 | 高 | 中 | 多次测试，调优Prompt | - |
| 数据提取准确率低 | 中 | 高 | 增加验证逻辑，用户确认 | - |
| 前端集成复杂度 | 中 | 中 | 复用现有组件 | - |
| Prompt调优耗时 | 高 | 中 | 预留充足时间 | - |
| 知识库内容准备 | 中 | 高 | 提前准备，分批导入 | - |

### 5.2 应急预案

**如果Phase 1延期**：
1. 优先保证核心流程（对话+提取）
2. Reflexion可简化为基础规则检查
3. Action Card可延后到Phase 2

**如果数据提取准确率不达标**：
1. 增加用户确认环节
2. 使用更强的模型（GPT-4）
3. 简化提取Schema

---

## 六、质量保证

### 6.1 测试策略

| 测试类型 | 覆盖范围 | 执行时机 |
|----------|----------|----------|
| 单元测试 | 核心Service、工具函数 | 每次提交 |
| 集成测试 | API端点、数据库操作 | 每个Sprint |
| E2E测试 | 完整用户流程 | 里程碑交付 |
| Prompt测试 | 各阶段Prompt效果 | 持续调优 |

### 6.2 验收标准

**Phase 1 验收标准**：
- [ ] 用户可完成5阶段研究方案要素制定
- [ ] Context数据正确保存和展示
- [ ] 阶段流转逻辑正确
- [ ] Reflexion能阻止不完整的阶段提交
- [ ] Action Card正确触发和展示
- [ ] API响应时间 < 3s（不含LLM）
- [ ] 无P0级Bug

### 6.3 Code Review检查点

- [ ] 类型定义完整
- [ ] 错误处理完善
- [ ] 日志记录规范
- [ ] 代码风格一致
- [ ] 无硬编码配置
- [ ] 有必要的注释

---

## 七、资源需求

### 7.1 人力资源

| 角色 | 人数 | Phase 1 | Phase 2 | Phase 3 |
|------|------|---------|---------|---------|
| 后端开发 | 1 | 100% | 80% | 60% |
| 前端开发 | 1 | 60% | 40% | 40% |
| 产品/测试 | 1 | 30% | 30% | 40% |

### 7.2 技术资源

| 资源 | 用途 | 预估费用 |
|------|------|----------|
| DeepSeek API | LLM调用 | ￥500/月 |
| 开发服务器 | 测试环境 | 现有 |
| 数据库 | PostgreSQL | 现有 |

---

## 八、沟通计划

### 8.1 会议安排

| 会议 | 频率 | 参与者 | 目的 |
|------|------|--------|------|
| 每日站会 | 每日 | 开发团队 | 同步进度，解决阻塞 |
| Sprint评审 | 每周 | 全员 | 演示成果，收集反馈 |
| 技术讨论 | 按需 | 相关开发 | 解决技术难题 |

### 8.2 文档更新

| 文档 | 更新频率 | 负责人 |
|------|----------|--------|
| 开发计划 | 每Sprint | PM |
| 技术文档 | 实时 | 开发者 |
| API文档 | 代码变更时 | 后端 |
| 用户手册 | Phase完成时 | 产品 |

---

## 九、检查清单

### Phase 1 启动前检查

- [ ] 需求文档已确认
- [ ] 技术方案已评审
- [ ] 数据库设计已确认
- [ ] 开发环境已就绪
- [ ] 相关人员已到位

### 每Sprint完成检查

- [ ] 所有任务已完成或明确延期原因
- [ ] 代码已Code Review
- [ ] 测试已通过
- [ ] 文档已更新
- [ ] 下Sprint计划已明确

### Phase 1 交付检查

- [ ] 所有功能已实现
- [ ] 验收标准全部达成
- [ ] 无遗留P0/P1 Bug
- [ ] 文档完整
- [ ] 演示准备就绪