Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
303dd78c54c250ee911dc050ef1264f29df9b9f5
AIclinicalresearch/docs/03-业务模块/AIA-AI智能问答/06-开发记录/2026-01-25-Protocol_Agent_MVP完整交付.md
HaHafeng 303dd78c54 feat(aia): Protocol Agent MVP complete with one-click generation and Word export 
- Add one-click research protocol generation with streaming output

- Implement Word document export via Pandoc integration

- Add dynamic dual-panel layout with resizable split pane

- Implement collapsible content for StatePanel stages

- Add conversation history management with title auto-update

- Fix scroll behavior, markdown rendering, and UI layout issues

- Simplify conversation creation logic for reliability
2026-01-25 19:16:36 +08:00

353 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 增强
```typescript
// 新增 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](../04-开发计划/06-一键生成研究方案开发计划V2.md)
- [无编辑器技术方案](../04-开发计划/基于对话流的文档生成与导出技术方案.md)
- [UI布局比例分析](../00-系统设计/UI_Layout_Ratio_Analysis.md)
- [Protocol Agent 架构设计](../04-开发计划/04-Protocol_Agent开发计划/01-架构设计.md)
---
## 🏆 技术总结
1. **Pandoc 集成**：通过 Python 微服务实现高质量 Word 导出
2. **流式渲染**：SSE + 自定义 Markdown 组件实现打字机效果
3. **延迟创建**：类 ChatGPT 的对话管理体验
4. **Prompt 工程**：阶段约束 + 数据凝练的精细化设计
5. **响应式布局**：动态比例适配不同工作阶段
---
**MVP 已完整交付！** 🎉
下一步：进入生产测试和用户反馈收集阶段。
Reference in New Issue View Git Blame Copy Permalink