AIclinicalresearch/docs/03-业务模块/AIA-AI智能问答/06-开发记录/2026-01-25-Protocol_Agent_MVP完整交付.md

Protocol Agent MVP 完整交付记录

日期：2026-01-25
开发者：AI Assistant
状态：🎉 MVP 完整交付
里程碑：研究方案制定Agent + 一键生成研究方案 + Word导出

---

📋 开发概述

在 2026-01-24 完成 Agent 框架基础后，今天完成了一键生成研究方案功能的全部开发工作，实现了从关键要素收集到完整研究方案输出的全流程，并解决了大量测试中发现的问题。

这是一个重要的里程碑：Protocol Agent MVP 已完整可用！

---

🎯 今日完成的功能

一、一键生成研究方案（核心功能）

1. 动态双面板布局

功能	实现
ResizableSplitPane	可拖拽调整左右面板宽度
ViewSwitcher	"研究摘要" / "完整方案" 切换
DocumentPanel	A4 纸张预览效果
动态比例	收集要素 65:35，生成方案 35:65

2. 研究方案生成

功能	实现
流式生成	SSE 实时输出，打字机效果
Markdown渲染	自定义 MarkdownContent 组件
章节滚动	生成时自动滚动跟随
12章节结构	完整临床研究方案结构

3. Word 文档导出

组件	技术	状态
Python 微服务	pypandoc + Pandoc	✅
Node.js API	/export/docx 端点	✅
前端下载	Blob + download	✅

---

二、用户体验优化（大量细节）

滚动问题修复

• 🔧 添加 min-height: 0 到所有 flex 容器
• 🔧 自定义滚动条样式（更宽、更可见）
• 🔧 Firefox 兼容性处理

UI/UX 改进

问题	解决方案
关键要素 → 研究摘要	重命名更准确
顶部标题两行	CSS flex-direction: row !important
欢迎语占满屏	精简内容 + 减少间距
列表编号1,1,1	CSS list-style-type: decimal
侧边栏按钮过长	紧凑设计 + 文字精简

StatePanel 优化

阶段	优化内容
科学问题	可折叠显示，完整内容
PICO	四要素分行，可折叠
样本量	显示计算过程、参数、分组
观察指标	基线/暴露/结局/混杂完整展示

CollapsibleContent 组件：

• 默认显示预览（2-3行）
• 渐变遮罩效果
• "展开全部"按钮
• 各阶段不同预览高度

---

三、Prompt 工程优化

阶段指引 Prompt 增强

// 新增 STAGE_ORDER 常量和 getStageInstructions 方法
// 明确当前阶段任务，严禁讨论已完成或未来阶段

解决问题：模型在"观察指标"阶段误讨论"样本量计算"

数据凝练 Prompt 放宽

阶段	调整
科学问题	100-200字（原50字）
PICO	每项50-100字（原20字）
样本量	包含计算过程、参数、分组
观察指标	完整定义、测量方法、时间点

方案生成 Prompt

• 移除 LLM 开场白（"好的，作为一名资深..."）
• 12章节结构化输出
• 基于关键要素动态生成标题

---

四、对话历史管理

延迟创建模式

点击"新建对话" → 导航到 /new（不创建记录）
                    ↓
发送第一条消息 → 创建对话 + 发送消息
                    ↓
            对话出现在历史列表中

优势：避免空对话污染历史列表（类似 ChatGPT）

标题自动更新

• 首条消息前20字符作为对话标题
• PATCH API 更新数据库

API 完善

端点	功能
GET /conversations?agentId=PROTOCOL_AGENT	过滤获取
PATCH /conversations/:id	更新标题
GET /messages/:conversationId	获取历史消息

---

五、Bug 修复

问题	原因	解决方案
TypeError: .map is not a function	后端返回字符串而非数组	toArray() 辅助函数
页面无法滚动	flex 子元素未设 min-height	添加 min-height: 0
Word 导出内容不全	传递的是模板而非生成内容	修改为传递实际内容
"Table of Contents" 出现	Pandoc --toc 参数	移除 toc 参数
模型讨论错误阶段	Prompt 约束不足	增强阶段指引

---

📊 代码变更统计

新增/修改文件

类别	文件	变更
前端组件
	ResizableSplitPane.tsx	新增 ~150行
	ViewSwitcher.tsx	新增 ~50行
	DocumentPanel.tsx	新增 ~335行
	MarkdownContent.tsx	新增 ~200行
	CollapsibleContent（StageCard内）	新增 ~100行
前端 Hooks
	useProtocolGeneration.ts	新增 ~261行
	useProtocolConversations.ts	修改 +60行
前端样式
	protocol-agent.css	修改 +800行（共2500行）
后端服务
	ProtocolExportService.ts	新增 ~100行
	ProtocolAgentController.ts	修改 +200行
	ProtocolOrchestrator.ts	修改 +100行
Python 微服务
	doc_export_service.py	新增 ~80行
	main.py	修改 +30行

代码总量

模块	今日新增	累计
前端	~1,200行	~3,300行
后端	~400行	~4,700行
Python	~110行	~500行
总计	~1,700行	~8,500行

---

🧪 测试验证

功能测试

测试项	状态
5阶段对话流程	✅
数据同步到状态面板	✅
样本量可选跳过	✅
一键生成研究方案	✅
生成时滚动跟随	✅
Word 导出下载	✅
对话历史保存	✅
新建对话清空界面	✅
延迟创建（无空记录）	✅
StatePanel 折叠展开	✅

已知问题（已解决）

• ✅ 滚动条不显示
• ✅ 顶部标题两行
• ✅ 欢迎语空间过大
• ✅ 列表编号错误
• ✅ 模型阶段混乱
• ✅ 数据类型错误
• ✅ 空对话保存

---

🏗️ 架构亮点

1. 无编辑器方案（MVP）

对话中收集关键要素
       ↓
  一键生成 Markdown
       ↓
  A4 预览 + 讨论优化
       ↓
  Pandoc 转换 Word 导出

优势：

• 开发速度快（3天完成）
• Word 格式完美
• 符合用户习惯

2. 动态布局适配

收集要素阶段：Chat 65% : Context 35%
生成方案阶段：Chat 35% : Document 65%

3. 延迟创建对话

• 点击新建不创建数据库记录
• 首条消息时才真正创建
• 避免空对话污染

---

📝 文件结构

frontend-v2/src/modules/aia/protocol-agent/
├── ProtocolAgentPage.tsx          # 主页面（362行）
├── components/
│   ├── ChatArea.tsx               # 聊天区域（574行）
│   ├── StatePanel.tsx             # 状态面板（198行）
│   ├── StageCard.tsx              # 阶段卡片（450行，含折叠）
│   ├── DocumentPanel.tsx          # 文档预览（335行）
│   ├── ResizableSplitPane.tsx     # 可调整面板（150行）
│   ├── ViewSwitcher.tsx           # 视图切换（50行）
│   ├── MarkdownContent.tsx        # MD渲染（200行）
│   └── StageEditModal.tsx         # 编辑弹窗
├── hooks/
│   ├── useProtocolContext.ts      # 上下文管理
│   ├── useProtocolConversations.ts # 对话管理（194行）
│   └── useProtocolGeneration.ts   # 生成管理（261行）
├── styles/
│   └── protocol-agent.css         # 样式（2500行）
└── types.ts                       # 类型定义

backend/src/modules/agent/protocol/
├── controllers/
│   └── ProtocolAgentController.ts # 控制器（778行）
├── services/
│   ├── ProtocolOrchestrator.ts    # 编排器（475行）
│   ├── ProtocolContextService.ts  # 上下文服务（320行）
│   └── ProtocolExportService.ts   # 导出服务（100行）
├── prompts/
│   └── protocolGenerationPrompts.ts # 生成Prompt
└── routes/
    └── index.ts                   # 路由（170行）

extraction_service/
├── services/
│   └── doc_export_service.py      # Word导出（80行）
└── main.py                        # FastAPI入口

---

🎉 里程碑达成

里程碑	状态	日期
M1: Agent框架	✅	2026-01-24
M2: 5阶段流程	✅	2026-01-24
M3: 前端UI	✅	2026-01-24
M4: 一键生成	✅	2026-01-25
M5: Word导出	✅	2026-01-25
MVP 完整交付	🎉	2026-01-25

---

📋 后续计划

Phase 2: 章节讨论模式（可选）

• "讨论与优化"按钮
• 单章节重新生成
• 修改建议实时预览

Phase 3: 手动要素补充

• 右侧面板手动添加入口
• 支持跳过对话直接填写
• 拖拽比例记忆

长期优化

• EKB 知识库集成
• RAG 检索增强
• Prompt 持续调优
• 多语言支持

---

📚 相关文档

• 开发计划 V2
• 无编辑器技术方案
• UI布局比例分析
• Protocol Agent 架构设计

---

🏆 技术总结

1. Pandoc 集成：通过 Python 微服务实现高质量 Word 导出
2. 流式渲染：SSE + 自定义 Markdown 组件实现打字机效果
3. 延迟创建：类 ChatGPT 的对话管理体验
4. Prompt 工程：阶段约束 + 数据凝练的精细化设计
5. 响应式布局：动态比例适配不同工作阶段

---

MVP 已完整交付！ 🎉

下一步：进入生产测试和用户反馈收集阶段。