502 lines
14 KiB
Markdown
Executable File
502 lines
14 KiB
Markdown
Executable File
# BBAV20311 Agent工作流设计文档
|
|
|
|
> 基于荔枝SPL基因家族案例的完整多Agent协作流程
|
|
> 版本: 1.0
|
|
> 日期: 2026-04-08
|
|
|
|
---
|
|
|
|
## 一、整体架构
|
|
|
|
```
|
|
用户提问
|
|
↓
|
|
[RouterAgent] 意图识别
|
|
↓
|
|
├─ FAQ/知识查询 → [KnowledgeAgent] → RAG检索 → 回答用户
|
|
├─ 分析请求 → [PlanningAgent] → 生成方案 → 询问确认
|
|
└─ 执行指令 → [ExecutionAgent] → 执行分析 → 返回结果
|
|
|
|
执行过程中:
|
|
- 出错 → [DiagnosisAgent] → 修复 → [LearningAgent]记录
|
|
- 完成 → [ValidatorAgent]验证 → [ResultParserAgent]解析
|
|
- 报告 → [KnowledgeAgent]增强 → 生成最终报告
|
|
```
|
|
|
|
---
|
|
|
|
## 二、场景流程详解
|
|
|
|
### 场景1: SPL基因家族知识查询
|
|
|
|
**用户输入**: "总结下SPL基因家族"
|
|
|
|
**Agent协作**:
|
|
| Agent | 动作 | 输出 |
|
|
|-------|------|------|
|
|
| RouterAgent | 意图识别 | `mode: FAQ`, `confidence: 0.95` |
|
|
| KnowledgeAgent | RAG检索 | SPL家族定义、功能、研究进展 |
|
|
|
|
**RAG检索内容**:
|
|
- SPL = SQUAMOSA PROMOTER BINDING PROTEIN-LIKE
|
|
- 主要功能: 调控开花时间、植物发育
|
|
- 结构域: SBP domain (PF03110)
|
|
- 研究进展: 拟南芥15个成员，水稻19个成员...
|
|
|
|
---
|
|
|
|
### 场景2: 荔枝SPL研究现状查询
|
|
|
|
**用户输入**: "荔枝的SPL基因家族是否有发表过相关的文章"
|
|
|
|
**Agent协作**:
|
|
| Agent | 动作 | 输出 |
|
|
|-------|------|------|
|
|
| RouterAgent | 意图识别 | `mode: FAQ`, `query: 荔枝SPL文献` |
|
|
| KnowledgeAgent | RAG检索 | 检索文献库 |
|
|
|
|
**RAG检索策略**:
|
|
```python
|
|
# 检索关键词组合
|
|
queries = [
|
|
"Litchi chinensis SPL",
|
|
"荔枝 SPL基因家族",
|
|
"Litchi SQUAMOSA PROMOTER BINDING PROTEIN",
|
|
"荔枝 开花调控 SPL"
|
|
]
|
|
|
|
# 结果处理
|
|
if found_papers:
|
|
return "已发现X篇相关文献: [列表]"
|
|
else:
|
|
return "目前未发现荔枝SPL基因家族的专门研究文献，这是一个潜在的研究空白。"
|
|
```
|
|
|
|
---
|
|
|
|
### 场景3: 研究可行性分析与方案规划
|
|
|
|
**用户输入**: "如果我想开展荔枝的SPL基因家族研究，可以吗？"
|
|
|
|
**Agent协作**:
|
|
| Agent | 动作 | 输出 |
|
|
|-------|------|------|
|
|
| RouterAgent | 意图识别 | `mode: ANALYSIS`, `target: 荔枝SPL` |
|
|
| KnowledgeAgent | 数据可用性检索 | 基因组、转录组数据状态 |
|
|
| PlanningAgent | 方案生成 | 完整分析计划 |
|
|
|
|
**PlanningAgent输出示例**:
|
|
|
|
```yaml
|
|
analysis_plan:
|
|
target_species: "Litchi chinensis (荔枝)"
|
|
gene_family: "SPL"
|
|
|
|
reference_genome:
|
|
status: available
|
|
source: "NCBI / 华南农业大学"
|
|
genome_fasta: "Lchi_v1.0.genome.fasta"
|
|
gff3: "Lchi_v1.0.gff3"
|
|
cds: "Lchi_v1.0.cds.fasta"
|
|
pep: "Lchi_v1.0.pep.fasta"
|
|
download_url: "https://www.ncbi.nlm.nih.gov/genome/..."
|
|
local_path: "/data/litchi/"
|
|
|
|
comparative_species:
|
|
- species: "Arabidopsis thaliana"
|
|
reason: "模式植物，功能验证"
|
|
files: "Ath.*"
|
|
- species: "Oryza sativa"
|
|
reason: "单子叶代表"
|
|
files: "Osa.*"
|
|
- species: "Solanum lycopersicum"
|
|
reason: "果实发育"
|
|
files: "Sly.*"
|
|
|
|
transcriptome_data:
|
|
status: available
|
|
source: "NCBI SRA"
|
|
samples:
|
|
- id: "SRRxxxx"
|
|
tissue: "flower"
|
|
condition: "blooming"
|
|
- id: "SRRxxxx"
|
|
tissue: "leaf"
|
|
condition: "control"
|
|
|
|
analysis_stages:
|
|
- identify: "基因家族鉴定"
|
|
- phylogeny: "系统发育分析"
|
|
- domain: "结构域分析"
|
|
- motif: "motif分析"
|
|
- expression: "表达模式分析"
|
|
- promoter: "启动子分析"
|
|
- synteny: "共线性分析"
|
|
|
|
estimated_time: "3-5天"
|
|
estimated_cost: "$50-100 (API调用)"
|
|
|
|
next_action: "等待用户确认执行"
|
|
```
|
|
|
|
**用户确认后**:
|
|
```
|
|
系统询问: "分析方案已生成，是否立即执行？"
|
|
用户选择: [执行分析] / [修改参数] / [取消]
|
|
```
|
|
|
|
---
|
|
|
|
### 场景4: 分析执行
|
|
|
|
**用户输入**: "执行分析"
|
|
|
|
**Agent协作**:
|
|
| Agent | 动作 | 输出 |
|
|
|-------|------|------|
|
|
| RouterAgent | 意图识别 | `mode: EXECUTE` |
|
|
| ExecutionAgent | 文件检查 | 命名规范验证 |
|
|
| ExecutionAgent | 参数确认 | 弹窗/自动默认 |
|
|
| ExecutionAgent | 阶段执行 | 逐阶段执行分析 |
|
|
| DiagnosisAgent | 错误诊断 | 出错时介入 |
|
|
| LearningAgent | 学习优化 | 记录修复方案 |
|
|
|
|
**文件命名检查**:
|
|
```python
|
|
naming_rules = {
|
|
"genome": r"^\w+\.genome\.fasta$", # Lchi.genome.fasta
|
|
"gff3": r"^\w+\.gff3$", # Lchi.gff3
|
|
"cds": r"^\w+\.cds\.fasta$", # Lchi.cds.fasta
|
|
"pep": r"^\w+\.pep\.fasta$", # Lchi.pep.fasta
|
|
"hmm": r"^\w+\.hmm$", # SPL.hmm
|
|
}
|
|
|
|
# 检查用户上传的文件
|
|
for file in uploaded_files:
|
|
if not validate_naming(file, naming_rules):
|
|
return f"文件 {file} 命名不规范，请按以下格式命名: [示例]"
|
|
```
|
|
|
|
**参数确认机制**:
|
|
```python
|
|
# 默认参数
|
|
default_params = {
|
|
"prefix": "Lchi.SPL",
|
|
"cpu": 8,
|
|
"evalue": 1e-5,
|
|
"max_target_seqs": 10,
|
|
}
|
|
|
|
# 弹窗确认（30秒超时）
|
|
user_confirmed = await show_confirmation_dialog(
|
|
params=default_params,
|
|
timeout=30 # 秒
|
|
)
|
|
|
|
if user_confirmed is None: # 超时
|
|
logger.info("用户30秒内未确认，使用默认参数")
|
|
params = default_params
|
|
elif user_confirmed is True: # 用户确认
|
|
params = default_params
|
|
else: # 用户修改
|
|
params = user_confirmed
|
|
```
|
|
|
|
---
|
|
|
|
### 场景5: 错误诊断与学习
|
|
|
|
**触发条件**: 分析阶段执行失败
|
|
|
|
**DiagnosisAgent工作流程**:
|
|
```python
|
|
class DiagnosisAgent:
|
|
async def diagnose(self, error: ExecutionError) -> DiagnosisResult:
|
|
# 1. 错误分类
|
|
error_type = self.classify_error(error)
|
|
|
|
# 2. 根因分析
|
|
root_cause = await self.analyze_root_cause(error)
|
|
|
|
# 3. 生成修复方案
|
|
fix_plan = await self.generate_fix(root_cause)
|
|
|
|
# 4. 执行修复
|
|
success = await self.apply_fix(fix_plan)
|
|
|
|
# 5. 测试验证
|
|
if success:
|
|
test_result = await self.test_fix()
|
|
|
|
# 6. 记录学习
|
|
await self.learning_agent.record_fix(error, fix_plan, test_result)
|
|
|
|
return DiagnosisResult(
|
|
error_type=error_type,
|
|
root_cause=root_cause,
|
|
fix_applied=fix_plan,
|
|
test_passed=test_result.success
|
|
)
|
|
```
|
|
|
|
**LearningAgent记录**:
|
|
```python
|
|
learning_record = {
|
|
"timestamp": "2026-04-08T10:30:00",
|
|
"error_type": "FileNotFoundError",
|
|
"error_message": "genome file not found: Lchi.genome.fa",
|
|
"root_cause": "文件扩展名不匹配，期望.fasta，实际.fa",
|
|
"fix_strategy": "自动检测并适配文件扩展名变体",
|
|
"code_changes": {
|
|
"file": "run_identify.py",
|
|
"line": 45,
|
|
"change": "添加扩展名适配逻辑"
|
|
},
|
|
"test_result": "passed",
|
|
"future_prevention": "在文件检查阶段增加扩展名变体检测"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 场景6: 结果验证与报告生成
|
|
|
|
**Agent协作**:
|
|
| Agent | 动作 | 输出 |
|
|
|-------|------|------|
|
|
| ValidatorAgent | 结果验证 | 完整性/质量检查 |
|
|
| ResultParserAgent | 结果解析 | 关键发现提取 |
|
|
| KnowledgeAgent | RAG增强 | 文献对比、功能注释 |
|
|
|
|
**ValidatorAgent检查项**:
|
|
```python
|
|
validation_checks = {
|
|
"completeness": {
|
|
"required_files": [
|
|
"final/Lchi.SPL.pep.fasta",
|
|
"final/Lchi.SPL.cds.fasta",
|
|
"final/Lchi.SPL.geneID.txt",
|
|
"final/Lchi.SPL.domain.txt"
|
|
],
|
|
"required_stages": [
|
|
"identify", "phylogeny", "domain"
|
|
]
|
|
},
|
|
"quality": {
|
|
"min_genes": 10,
|
|
"max_genes": 100,
|
|
"phylogeny_bootstrap": 70,
|
|
"domain_coverage": 0.8
|
|
}
|
|
}
|
|
```
|
|
|
|
**最终报告结构**:
|
|
```markdown
|
|
# 荔枝SPL基因家族分析报告
|
|
|
|
## 执行摘要
|
|
- 鉴定到XX个SPL基因
|
|
- 分为X个亚家族
|
|
- 发现X个潜在功能基因
|
|
|
|
## 详细结果
|
|
### 1. 基因家族鉴定
|
|
- 基因列表: [表格]
|
|
- 染色体分布: [图]
|
|
|
|
### 2. 系统发育分析
|
|
- 进化树: [图]
|
|
- 与拟南芥/水稻比较
|
|
|
|
### 3. 功能预测
|
|
- 基于文献对比的功能注释
|
|
- 开花相关基因预测
|
|
|
|
## 生物学意义
|
|
- 荔枝SPL家族的扩张/收缩模式
|
|
- 与其他物种的差异
|
|
- 潜在研究方向
|
|
|
|
## 方法
|
|
- 分析工具: HMMER, MAFFT, IQTREE...
|
|
- 参数设置
|
|
- 可复现性信息
|
|
```
|
|
|
|
---
|
|
|
|
## 三、Agent状态流转
|
|
|
|
```
|
|
[RouterAgent]
|
|
↓
|
|
识别意图 → 路由到对应Agent
|
|
↓
|
|
├─ FAQ → [KnowledgeAgent] → 完成
|
|
├─ ANALYSIS → [PlanningAgent] → 等待确认
|
|
│ ↓
|
|
│ 用户确认
|
|
│ ↓
|
|
└─ EXECUTE → [ExecutionAgent] → 执行阶段
|
|
↓
|
|
阶段执行
|
|
↓
|
|
┌──────────┴──────────┐
|
|
↓ ↓
|
|
成功 失败
|
|
↓ ↓
|
|
[ValidatorAgent] [DiagnosisAgent]
|
|
↓ ↓
|
|
[ResultParserAgent] 修复代码
|
|
↓ ↓
|
|
[KnowledgeAgent] 测试修复
|
|
↓ ↓
|
|
生成报告 [LearningAgent]
|
|
↓ ↓
|
|
完成 记录并继续
|
|
```
|
|
|
|
---
|
|
|
|
## 四、关键设计决策
|
|
|
|
### 1. 30秒超时自动执行
|
|
- **目的**: 减少用户等待，提高效率
|
|
- **实现**: 前端倒计时 + 后端默认参数
|
|
- **可配置**: 用户可调整超时时间
|
|
|
|
### 2. DiagnosisAgent自动修复
|
|
- **范围**: 仅限于常见错误（文件路径、参数错误）
|
|
- **限制**: 复杂错误需人工介入
|
|
- **安全**: 修复前备份原代码
|
|
|
|
### 3. LearningAgent记录
|
|
- **存储**: 本地数据库 + 可选上传
|
|
- **隐私**: 不上传用户数据，仅上传错误模式
|
|
- **用途**: 改进系统，不用于商业
|
|
|
|
### 4. RAG知识增强
|
|
- **来源**: 已发表论文、数据库
|
|
- **更新**: 定期同步最新文献
|
|
- **引用**: 报告中标注文献来源
|
|
|
|
---
|
|
|
|
## 五、前端交互设计
|
|
|
|
### 主界面布局
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ [标题] BBAV20311 - Agent Assistant [模型选择] [状态] │
|
|
├──────────────┬──────────────────────────────┬───────────────┤
|
|
│ │ │ │
|
|
│ 文件上传 │ Agent对话区域 │ 分析结果 │
|
|
│ │ │ │
|
|
│ [上传区] │ User: 荔枝SPL基因家族... │ [结果面板] │
|
|
│ │ │ │
|
|
│ 命名规范 │ Agent: 正在检索... │ [图片预览] │
|
|
│ [示例] │ │ │
|
|
│ │ [参数确认弹窗 - 30秒倒计时] │ [下载按钮] │
|
|
│ │ │ │
|
|
├──────────────┴──────────────────────────────┴───────────────┤
|
|
│ [输入框] 请输入您的问题... [发送] [RAG/Skill] │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 参数确认弹窗
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ 参数确认 [X] │
|
|
├─────────────────────────────────────┤
|
|
│ 分析阶段: identify │
|
|
│ 物种: Litchi chinensis │
|
|
│ 基因家族: SPL │
|
|
│ CPU: 8 │
|
|
│ E-value: 1e-5 │
|
|
│ │
|
|
│ [修改参数] [确认] (29s) │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 六、API设计
|
|
|
|
### 核心端点
|
|
|
|
```python
|
|
# 1. 聊天/意图识别
|
|
POST /api/agent/chat
|
|
{
|
|
"message": "荔枝的SPL基因家族是否有发表过相关文章",
|
|
"session_id": "uuid"
|
|
}
|
|
|
|
# 2. 生成分析方案
|
|
POST /api/agent/plan
|
|
{
|
|
"species": "Litchi chinensis",
|
|
"gene_family": "SPL",
|
|
"session_id": "uuid"
|
|
}
|
|
|
|
# 3. 执行分析
|
|
POST /api/agent/execute
|
|
{
|
|
"plan_id": "plan_uuid",
|
|
"params": {...}, # 用户确认或修改的参数
|
|
"auto_confirm": false # 是否自动确认（30秒超时后）
|
|
}
|
|
|
|
# 4. 查询任务状态
|
|
GET /api/agent/status/{task_id}
|
|
|
|
# 5. 诊断错误
|
|
POST /api/agent/diagnose
|
|
{
|
|
"task_id": "task_uuid",
|
|
"error_log": "..."
|
|
}
|
|
|
|
# 6. 获取结果
|
|
GET /api/agent/results/{task_id}
|
|
```
|
|
|
|
---
|
|
|
|
## 七、待确认问题
|
|
|
|
1. **RAG知识库范围**
|
|
- 是否包含荔枝相关文献？
|
|
- 如何更新知识库？
|
|
|
|
2. **PlanningAgent数据源**
|
|
- 基因组数据从哪些数据库检索？
|
|
- 转录组数据如何查询？
|
|
|
|
3. **DiagnosisAgent权限**
|
|
- 自动修复的代码范围？
|
|
- 是否需要用户确认修复？
|
|
|
|
4. **LearningAgent数据共享**
|
|
- 是否上传错误模式到云端？
|
|
- 如何保护用户隐私？
|
|
|
|
5. **参数确认超时**
|
|
- 30秒是否合适？
|
|
- 是否可配置？
|
|
|
|
---
|
|
|
|
*文档创建: 2026-04-08*
|
|
*作者: xialab*
|
|
*状态: 待确认*
|
|
|
|
## 2026-05-26 追加：Agent 职责边界整改入口
|
|
|
|
KaKs/PPI/scope 讨论暴露出 PlanningAgent、DiagnosisAgent、ResultParserAgent 与执行层之间存在职责混杂：静态依赖、动态需求、artifact 解析、完成状态、修复策略在多个文件重复实现。
|
|
|
|
详细问题归类、非破坏迁移计划和验收矩阵见：[`docs/stage_requirements_agent_refactor_plan_2026-05-26.md`](stage_requirements_agent_refactor_plan_2026-05-26.md)。
|
|
|