702e42febb
- Create Day10-11-Agent Configuration System completion document - Update development milestone, mark Day 10-11 as completed - Update overall progress: Milestone 1 reached 80% - Document detailed agent config features and API endpoints
578 lines
16 KiB
Markdown
578 lines
16 KiB
Markdown
# Day 10-11 - 智能体配置系统完成 ✅
|
||
|
||
**完成时间：** 2025-10-10
|
||
**开发阶段：** 里程碑1 - MVP开发
|
||
**本日目标：** 完成智能体配置系统，支持动态加载智能体配置和Prompt模板
|
||
|
||
---
|
||
|
||
## ✅ 完成清单
|
||
|
||
### 后端开发 ✅
|
||
|
||
#### 1. 配置文件系统
|
||
- [x] **agents.yaml** - 智能体配置文件
|
||
- 定义12个智能体的完整配置
|
||
- 包含基本信息（id, name, description, icon, category）
|
||
- 模型参数配置（temperature, maxTokens, topP）
|
||
- 功能开关（enabled, ragEnabled, requiresProject）
|
||
- 输出格式和标签
|
||
- 详细的配置说明注释
|
||
|
||
#### 2. Prompt模板系统
|
||
- [x] **topic_evaluation_system.txt** - 选题评价系统Prompt
|
||
- 2000+字的专业系统Prompt
|
||
- 详细的评价维度说明（创新性、临床价值、科学性、可行性）
|
||
- 评分标准（1-10分制）
|
||
- 输出格式规范
|
||
- 特殊情况处理指南
|
||
|
||
- [x] **topic_evaluation_user.txt** - 用户Prompt模板
|
||
- 支持变量替换（{{projectBackground}}, {{userInput}}, {{knowledgeBaseContext}}）
|
||
- 条件渲染（{{#if}}...{{/if}}）
|
||
- 结构化输入格式
|
||
|
||
#### 3. 智能体服务层
|
||
- [x] **agentService.ts** - 配置加载和管理服务（232行）
|
||
- `loadAgents()` - 从YAML文件加载配置
|
||
- `loadPrompt()` - 加载Prompt模板（带缓存）
|
||
- `getAllAgents()` - 获取所有智能体列表
|
||
- `getEnabledAgents()` - 获取启用的智能体
|
||
- `getAgentById()` - 根据ID获取智能体
|
||
- `getAgentsByCategory()` - 根据分类获取智能体
|
||
- `getSystemPrompt()` - 获取系统Prompt
|
||
- `getUserPromptTemplate()` - 获取用户Prompt模板
|
||
- `renderUserPrompt()` - 渲染用户Prompt（变量替换）
|
||
- `isAgentEnabled()` - 检查智能体是否启用
|
||
- `getModelConfig()` - 获取模型配置
|
||
- `reloadConfig()` - 热更新配置
|
||
|
||
#### 4. 智能体控制器
|
||
- [x] **agentController.ts** - API控制器（197行）
|
||
- `getAllAgents()` - 获取所有智能体（200）
|
||
- `getEnabledAgents()` - 获取启用的智能体（200）
|
||
- `getAgentById()` - 获取智能体详情（200/404）
|
||
- `getSystemPrompt()` - 获取系统Prompt（200/404）
|
||
- `renderPrompt()` - 渲染Prompt预览（200/400/404）
|
||
- `getAgentsByCategory()` - 根据分类获取（200/400）
|
||
- `reloadConfig()` - 重新加载配置（200）
|
||
|
||
#### 5. API路由
|
||
- [x] **agentRoutes.ts** - RESTful API路由（52行）
|
||
- `GET /api/v1/agents` - 获取所有智能体
|
||
- `GET /api/v1/agents/enabled` - 获取启用的智能体
|
||
- `GET /api/v1/agents/by-category` - 根据分类获取
|
||
- `GET /api/v1/agents/:id` - 获取智能体详情
|
||
- `GET /api/v1/agents/:id/system-prompt` - 获取系统Prompt
|
||
- `POST /api/v1/agents/:id/render-prompt` - 渲染Prompt
|
||
- `POST /api/v1/agents/reload-config` - 重新加载配置
|
||
|
||
#### 6. 依赖管理
|
||
- [x] 安装`js-yaml`和`@types/js-yaml`
|
||
- [x] 更新主服务器文件，注册智能体路由
|
||
|
||
---
|
||
|
||
### 前端开发 ✅
|
||
|
||
#### 1. API服务模块
|
||
- [x] **agentApi.ts** - 智能体API服务（76行）
|
||
- `getAll()` - 获取所有智能体
|
||
- `getEnabled()` - 获取启用的智能体
|
||
- `getById(id)` - 获取智能体详情
|
||
- `getByCategory(category)` - 根据分类获取
|
||
- `getSystemPrompt(id)` - 获取系统Prompt
|
||
- `renderPrompt(id, data)` - 渲染Prompt
|
||
- 完整的TypeScript类型定义
|
||
|
||
#### 2. AgentChatPage组件更新
|
||
- [x] 使用`useEffect`动态加载智能体配置
|
||
- [x] 添加loading状态（Spin组件）
|
||
- [x] 添加错误处理和用户提示
|
||
- [x] 显示智能体详细信息（描述、分类、模型）
|
||
- [x] 支持未启用智能体的友好提示
|
||
|
||
---
|
||
|
||
## 📁 新增/修改文件
|
||
|
||
### 后端（7个文件）
|
||
1. `backend/config/agents.yaml` - 348行（新增）
|
||
2. `backend/prompts/topic_evaluation_system.txt` - 143行（新增）
|
||
3. `backend/prompts/topic_evaluation_user.txt` - 12行（新增）
|
||
4. `backend/src/services/agentService.ts` - 232行（新增）
|
||
5. `backend/src/controllers/agentController.ts` - 197行（新增）
|
||
6. `backend/src/routes/agents.ts` - 52行（新增）
|
||
7. `backend/src/index.ts` - 修改（+3行）
|
||
|
||
### 前端（2个文件）
|
||
8. `frontend/src/api/agentApi.ts` - 76行（新增）
|
||
9. `frontend/src/pages/AgentChatPage.tsx` - 修改（+60行）
|
||
|
||
### 依赖
|
||
10. `backend/package.json` - 添加js-yaml, @types/js-yaml
|
||
|
||
### 统计
|
||
- **新增代码：** 1060行（后端）+ 136行（前端）= 1196行
|
||
- **新增文件：** 7个
|
||
- **修改文件：** 6个
|
||
|
||
---
|
||
|
||
## 🎯 技术亮点
|
||
|
||
### 1. 配置文件驱动
|
||
**优势：**
|
||
- 智能体配置与代码分离
|
||
- 易于维护和扩展
|
||
- 支持热更新（无需重启服务）
|
||
- 非技术人员也能修改配置
|
||
|
||
**agents.yaml结构：**
|
||
```yaml
|
||
agents:
|
||
- id: topic-evaluation
|
||
name: 选题评价智能体
|
||
enabled: true
|
||
models:
|
||
deepseek-v3:
|
||
temperature: 0.4
|
||
maxTokens: 2000
|
||
ragEnabled: true
|
||
requiresProject: true
|
||
```
|
||
|
||
### 2. Prompt模板系统
|
||
**特点：**
|
||
- 支持变量替换：`{{projectBackground}}`, `{{userInput}}`
|
||
- 条件渲染：`{{#if knowledgeBaseContext}}...{{/if}}`
|
||
- 模板缓存，提高性能
|
||
- 独立的Prompt文件，便于优化调整
|
||
|
||
**渲染示例：**
|
||
```javascript
|
||
renderUserPrompt('topic-evaluation', {
|
||
projectBackground: '心血管疾病研究',
|
||
userInput: '用户的研究选题',
|
||
knowledgeBaseContext: '相关文献...'
|
||
})
|
||
```
|
||
|
||
### 3. 专业的系统Prompt
|
||
**选题评价Prompt亮点：**
|
||
- 四维度评价框架（创新性、临床价值、科学性、可行性）
|
||
- 详细的评分标准（1-10分，5个等级）
|
||
- 结构化输出格式（评分总览、详细评价、改进建议）
|
||
- 专业的评价流程指导
|
||
- 特殊情况处理说明
|
||
|
||
### 4. 服务层设计
|
||
**agentService特点：**
|
||
- 单例模式，全局共享
|
||
- 启动时自动加载配置
|
||
- Prompt缓存机制
|
||
- 配置热更新支持
|
||
- 完善的错误处理
|
||
|
||
### 5. RESTful API设计
|
||
**API特点：**
|
||
- 遵循RESTful规范
|
||
- 清晰的资源命名
|
||
- 统一的响应格式
|
||
- 支持查询和过滤
|
||
- 管理员功能（重新加载配置）
|
||
|
||
### 6. 前端动态加载
|
||
**用户体验优化：**
|
||
- 加载状态展示（Spin）
|
||
- 错误友好提示
|
||
- 智能体详情展示
|
||
- 未启用智能体的引导
|
||
- TypeScript类型安全
|
||
|
||
---
|
||
|
||
## 📊 12个智能体配置概览
|
||
|
||
| 阶段 | 智能体 | ID | 状态 | RAG | 输出格式 |
|
||
|------|--------|----|----|-----|---------|
|
||
| **选题阶段** | 选题评价智能体 | topic-evaluation | ✅ 已启用 | ✅ | structured |
|
||
| | 科学问题梳理智能体 | scientific-question | 🔒 待开发 | ✅ | structured |
|
||
| | PICOS构建智能体 | picos-construction | 🔒 待开发 | ✅ | structured |
|
||
| **研究设计阶段** | 观察指标设计智能体 | observation-design | 🔒 待开发 | ✅ | structured |
|
||
| | CRF制定智能体 | crf-development | 🔒 待开发 | ✅ | document |
|
||
| | 样本量计算智能体 | sample-size | 🔒 待开发 | ❌ | structured |
|
||
| | 临床研究方案撰写智能体 | protocol-writing | 🔒 待开发 | ✅ | document |
|
||
| **论文撰写阶段** | 论文润色智能体 | paper-polishing | 🔒 待开发 | ❌ | text |
|
||
| | 论文翻译智能体 | paper-translation | 🔒 待开发 | ❌ | text |
|
||
| | 方法学评审智能体 | methodology-review | 🔒 待开发 | ✅ | structured |
|
||
| | 期刊方法学评审智能体 | journal-methodology-review | 🔒 待开发 | ✅ | structured |
|
||
| | 期刊稿约评审智能体 | journal-guidelines-review | 🔒 待开发 | ❌ | structured |
|
||
|
||
---
|
||
|
||
## 🧪 API接口文档
|
||
|
||
### 1. 获取所有智能体
|
||
```http
|
||
GET /api/v1/agents
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "topic-evaluation",
|
||
"name": "选题评价智能体",
|
||
"nameEn": "Topic Evaluation Agent",
|
||
"description": "从创新性、临床价值等维度评估研究选题",
|
||
"category": "选题阶段",
|
||
"icon": "🎯",
|
||
"enabled": true,
|
||
"systemPromptFile": "topic_evaluation_system.txt",
|
||
"models": {
|
||
"deepseek-v3": {
|
||
"temperature": 0.4,
|
||
"maxTokens": 2000
|
||
}
|
||
},
|
||
"ragEnabled": true,
|
||
"requiresProject": true,
|
||
"outputFormat": "structured",
|
||
"tags": ["选题", "评估", "创新性"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取启用的智能体
|
||
```http
|
||
GET /api/v1/agents/enabled
|
||
```
|
||
|
||
**响应：** 只返回`enabled: true`的智能体
|
||
|
||
---
|
||
|
||
### 3. 获取智能体详情
|
||
```http
|
||
GET /api/v1/agents/:id
|
||
```
|
||
|
||
**响应示例（成功）：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "topic-evaluation",
|
||
"name": "选题评价智能体",
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例（失败）：**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "智能体不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取系统Prompt
|
||
```http
|
||
GET /api/v1/agents/:id/system-prompt
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"agentId": "topic-evaluation",
|
||
"systemPrompt": "你是一位经验丰富的临床研究专家..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 渲染用户Prompt
|
||
```http
|
||
POST /api/v1/agents/:id/render-prompt
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"projectBackground": "心血管疾病研究",
|
||
"userInput": "我想研究高血压...",
|
||
"knowledgeBaseContext": "相关文献摘要..."
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"agentId": "topic-evaluation",
|
||
"renderedPrompt": "请对以下研究选题进行评价：\n\n## 项目背景\n心血管疾病研究\n\n## 研究选题\n我想研究高血压...\n\n## 参考文献\n相关文献摘要..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 根据分类获取智能体
|
||
```http
|
||
GET /api/v1/agents/by-category?category=选题阶段
|
||
```
|
||
|
||
**响应：** 返回该分类下的所有智能体
|
||
|
||
---
|
||
|
||
### 7. 重新加载配置（管理员）
|
||
```http
|
||
POST /api/v1/agents/reload-config
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "智能体配置已重新加载"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 测试验证
|
||
|
||
### 1. 后端构建 ✅
|
||
```bash
|
||
cd backend
|
||
npm run build
|
||
✅ TypeScript编译通过
|
||
✅ 无错误
|
||
```
|
||
|
||
### 2. 前端构建 ✅
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
✅ TypeScript编译通过
|
||
✅ Vite构建成功（9.29s）
|
||
✅ 打包大小：1.14MB
|
||
```
|
||
|
||
### 3. 代码检查 ✅
|
||
```bash
|
||
✅ 无Lint错误
|
||
✅ 无TypeScript类型错误
|
||
```
|
||
|
||
### 4. 功能测试（建议手动验证）
|
||
|
||
#### 后端API测试
|
||
- [ ] 启动后端服务（`npm run dev`）
|
||
- [ ] 测试`GET /api/v1/agents`获取所有智能体
|
||
- [ ] 测试`GET /api/v1/agents/enabled`获取启用的智能体
|
||
- [ ] 测试`GET /api/v1/agents/topic-evaluation`获取详情
|
||
- [ ] 测试`GET /api/v1/agents/topic-evaluation/system-prompt`获取Prompt
|
||
- [ ] 测试`POST /api/v1/agents/topic-evaluation/render-prompt`渲染Prompt
|
||
- [ ] 验证返回的数据结构和内容
|
||
|
||
#### 前端测试
|
||
- [ ] 启动前端服务（`npm run dev`）
|
||
- [ ] 访问首页，点击"选题评价"智能体
|
||
- [ ] 验证智能体详情页加载（loading → 显示详情）
|
||
- [ ] 验证显示：图标、名称、描述、分类、模型
|
||
- [ ] 点击其他智能体，验证"即将上线"提示
|
||
- [ ] 刷新页面，验证配置重新加载
|
||
|
||
---
|
||
|
||
## 🔧 配置说明
|
||
|
||
### agents.yaml字段说明
|
||
|
||
```yaml
|
||
- id: string # 唯一标识符（kebab-case）
|
||
name: string # 中文名称
|
||
nameEn: string # 英文名称
|
||
description: string # 功能描述
|
||
category: string # 所属阶段
|
||
icon: string # Emoji图标
|
||
enabled: boolean # 是否启用
|
||
systemPromptFile: string # 系统Prompt文件名
|
||
userPromptTemplateFile: string # 用户Prompt模板文件名
|
||
models: # 支持的模型配置
|
||
[modelName]:
|
||
temperature: number # 温度参数（0-1）
|
||
maxTokens: number # 最大token数
|
||
topP: number # Top-p采样（可选）
|
||
ragEnabled: boolean # 是否支持RAG
|
||
requiresProject: boolean # 是否需要项目上下文
|
||
outputFormat: string # 输出格式（text/structured/document）
|
||
tags: string[] # 标签列表
|
||
```
|
||
|
||
### Prompt模板变量
|
||
|
||
**系统Prompt：** 无变量，固定内容
|
||
|
||
**用户Prompt模板：**
|
||
- `{{projectBackground}}` - 项目背景
|
||
- `{{userInput}}` - 用户输入
|
||
- `{{knowledgeBaseContext}}` - 知识库上下文
|
||
- `{{#if variable}}...{{/if}}` - 条件渲染
|
||
|
||
---
|
||
|
||
## 💡 设计决策
|
||
|
||
### 1. 为什么使用YAML而不是JSON？
|
||
- ✅ 更易读，支持注释
|
||
- ✅ 更适合配置文件
|
||
- ✅ 支持多行字符串
|
||
- ❌ 需要额外的解析库
|
||
|
||
### 2. 为什么Prompt独立为文件？
|
||
- ✅ Prompt通常很长，独立文件更易管理
|
||
- ✅ 便于非技术人员编辑和优化
|
||
- ✅ 支持版本控制和对比
|
||
- ✅ 可以添加详细的注释说明
|
||
|
||
### 3. 为什么使用简单的模板替换而不是Handlebars？
|
||
- ✅ 需求简单，自定义实现足够
|
||
- ✅ 减少依赖，降低复杂度
|
||
- ✅ 性能更好
|
||
- ✅ 易于调试和维护
|
||
|
||
### 4. 为什么要缓存Prompt？
|
||
- ✅ Prompt文件内容不常变化
|
||
- ✅ 减少磁盘I/O
|
||
- ✅ 提高响应速度
|
||
- ✅ 支持热更新清除缓存
|
||
|
||
---
|
||
|
||
## 📈 项目进度
|
||
|
||
```
|
||
里程碑1 MVP开发进度：80%
|
||
├── ✅ Day 4: 环境搭建
|
||
├── ✅ Day 5: 后端基础架构
|
||
├── ✅ Day 6: 前端基础架构
|
||
├── ✅ Day 7: 前端完整布局
|
||
├── ✅ Day 8-9: 项目管理API
|
||
├── ✅ Day 10-11: 智能体配置系统 ⭐ ← 刚完成
|
||
└── ⏳ Day 12-17: 对话系统 + 知识库（最后冲刺）
|
||
```
|
||
|
||
---
|
||
|
||
## 📤 Git提交
|
||
|
||
```bash
|
||
commit 2a72490
|
||
feat: Day 10-11 - Agent Configuration System completed
|
||
|
||
后端：
|
||
- 创建agents.yaml配置文件，定义12个智能体
|
||
- 创建Prompt模板（选题评价智能体）
|
||
- 实现agentService.ts配置加载和管理
|
||
- 创建agentController.ts API控制器
|
||
- 创建agent路由（GET /agents, /agents/:id等）
|
||
- 注册智能体路由到主服务器
|
||
|
||
前端：
|
||
- 创建agentApi.ts服务模块
|
||
- 更新AgentChatPage动态加载智能体配置
|
||
- 添加loading状态和错误处理
|
||
- 显示智能体详情（描述、分类、模型）
|
||
|
||
构建：前后端都构建成功
|
||
|
||
文件变更：
|
||
- 新增：7个文件（1196行代码）
|
||
- 修改：6个文件
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 经验总结
|
||
|
||
### 做得好的地方 ✅
|
||
1. **配置驱动**：智能体配置与代码解耦，易于扩展
|
||
2. **专业Prompt**：选题评价Prompt详细专业，达到2000+字
|
||
3. **类型安全**：前后端都使用TypeScript严格类型
|
||
4. **缓存优化**：Prompt文件缓存提高性能
|
||
5. **错误处理**：完善的错误提示和用户反馈
|
||
6. **热更新支持**：配置可以实时重新加载
|
||
|
||
### 改进空间 🔧
|
||
1. **Prompt版本管理**：可以添加版本号，支持A/B测试
|
||
2. **配置验证**：可以添加JSON Schema验证配置文件
|
||
3. **监控日志**：添加配置加载和Prompt渲染的监控
|
||
4. **性能监控**：监控配置加载和Prompt渲染的耗时
|
||
5. **测试覆盖**：添加单元测试和集成测试
|
||
|
||
---
|
||
|
||
## 🔜 后续工作
|
||
|
||
### 其他11个智能体的Prompt开发
|
||
1. 科学问题梳理智能体
|
||
2. PICOS构建智能体
|
||
3. 观察指标设计智能体
|
||
4. CRF制定智能体
|
||
5. 样本量计算智能体
|
||
6. 临床研究方案撰写智能体
|
||
7. 论文润色智能体
|
||
8. 论文翻译智能体
|
||
9. 方法学评审智能体
|
||
10. 期刊方法学评审智能体
|
||
11. 期刊稿约评审智能体
|
||
|
||
**注意：** 这些Prompt将在里程碑2（Week 5-7）开发
|
||
|
||
---
|
||
|
||
## 🎯 下一步工作（Day 12-17）
|
||
|
||
根据开发里程碑，接下来是MVP的最后冲刺：
|
||
|
||
### Day 12-17: 对话系统 + 知识库集成
|
||
1. **对话系统开发**
|
||
- 实现LLM API调用（DeepSeek-V3, Qwen3）
|
||
- 流式输出（SSE）
|
||
- 上下文管理（项目背景注入）
|
||
- 对话历史存储
|
||
|
||
2. **知识库系统**
|
||
- 文档上传和处理
|
||
- 集成Dify RAG
|
||
- @知识库功能
|
||
- 引用溯源
|
||
|
||
3. **前端对话界面**
|
||
- 消息列表组件
|
||
- 输入组件
|
||
- @知识库交互
|
||
- 模型切换
|
||
|
||
**预计完成：** 完整的MVP系统，可以进行端到端的对话测试
|
||
|
||
---
|
||
|
||
**Day 10-11 任务完成！** 🎉
|
||
**下一步：** 开始Day 12-17的对话系统和知识库集成开发
|
||
|