# 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)。