14 KiB
Executable File
14 KiB
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检索策略:
# 检索关键词组合
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输出示例:
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 | 学习优化 | 记录修复方案 |
文件命名检查:
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} 命名不规范，请按以下格式命名: [示例]"
参数确认机制:
# 默认参数
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工作流程:
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记录:
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检查项:
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
}
}
最终报告结构:
# 荔枝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设计
核心端点
# 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}
七、待确认问题
-
RAG知识库范围
- 是否包含荔枝相关文献？
- 如何更新知识库？
-
PlanningAgent数据源
- 基因组数据从哪些数据库检索？
- 转录组数据如何查询？
-
DiagnosisAgent权限
- 自动修复的代码范围？
- 是否需要用户确认修复？
-
LearningAgent数据共享
- 是否上传错误模式到云端？
- 如何保护用户隐私？
-
参数确认超时
- 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。