# bbav5 修订记录 - 2026-04-14

## 今日修订概览

### 1. 修复 completed_stages 追踪问题
**问题**: 系统重复执行已完成的阶段（identify/phylogeny），不识别已完成的 pep 分析

**修复文件**: `gfa_core/mas/core/langgraph_orchestrator.py`
- 添加 `import json` 修复 manifest 解析
- 在 `_router_node` 中设置 `state["next_node"]` 确保正确路由
- 修改 `_route_decision` 优先使用 `next_node`
- 添加 `_query_completed_stages_from_manifest()` 方法从 manifest 文件查询已完成阶段

### 2. 统一 MAS 与 Pipeline 执行层
**问题**: MAS 的 Stage Registry 缺少 pep 阶段，导致多智能体无法执行 pep 分析

**修复文件**: `gfa_core/mas/tools/stage_tools.py`
- 重写 `StageToolExecutor.execute()` 调用 `pipeline_backend.run_stage()`
- 添加 `pep` stage 到 Stage Registry
- 处理异步执行（`asyncio.to_thread`）
- 添加工作目录切换（`os.chdir(self.project_root)`）

### 3. 修复 LangGraph 工作流循环问题
**问题**: Validator 反复验证导致无限循环

**修复文件**: `gfa_core/mas/agents/execution.py`
- 当 `stages_to_run` 为空时直接返回成功，跳过执行

**修复文件**: `gfa_core/mas/core/langgraph_orchestrator.py`
- `_validator_node`: 当 `execution_result` 为空列表时跳过验证
- `_to_agent_state`: 处理 `execution_result` 列表类型

### 4. 修复前端 API 响应
**修复文件**: `apps/web/vue3/main.py`
- 处理 `final_output.get("execution")` 返回列表的情况
- `/api/execute` 端点检查 manifest，返回 `already_completed: true`

### 5. 完善 Validator 支持
**修复文件**: `gfa_core/mas/agents/validator.py`
- 在 `EXPECTED_OUTPUTS` 中添加 `pep` 阶段预期输出文件

### 6. 修复 PlanningAgentV2 和 IntentAgentV2
**修复文件**: `gfa_core/mas/agents/planning_v2.py`
- 添加 `_check_stage_status_from_manifest()` 方法
- 修改 `_generate_plan_with_llm` 基于 manifest 状态过滤阶段
- 接收 `job_id` 和 `workspace` 参数

**修复文件**: `gfa_core/mas/agents/intent_v2.py`
- 添加 pep 强制规则匹配
- 修改 LLM 提示词，不过滤 completed stages
- 传递 `job_id` 和 `workspace` 到 intent 结果

## 验证结果

```bash
# 测试命令
curl -s http://localhost:7868/api/agent/chat \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"帮我执行pep分析","session_id":"test_pep","job_id":"job_1776101584377"}'

# 返回结果
{"success": true, ...}
```

**PEP 分析成功执行，生成文件**:
- `Ft.SPL.pep.manifest.json`
- `Ft.SPL.pep_properties.tsv`
- `Ft.SPL.pep_report.md`
- `Ft.SPL.pep_properties.pdf`
- `Ft.SPL.pep_properties.png`

## 关键架构改进

### 执行路径统一
```
旧路径: MAS → StageToolExecutor → 直接运行脚本 ❌ 缺少 pep 支持
新路径: MAS → StageToolExecutor → pipeline_backend.run_stage() ✅ 统一调用
```

### 状态管理优化
- `completed_stages` 从 manifest 文件实时查询
- 空阶段列表时跳过执行和验证
- 正确处理列表/字典类型转换

## 多智能体架构设计与功能增强（讨论记录）

### 当前架构问题分析

**12个 Agent 架构存在的问题：**
1. **Validator vs SelfCritique** - 功能高度冗余，都在检查执行结果
2. **Knowledge Agent 功能浪费** - 只用于 FAQ，未充分利用 RAG 能力
3. **缺少 Pre-flight 验证** - 执行前不验证输入文件和依赖
4. **缺少迭代机制** - 单次执行，失败时直接报错

### 优化后的 9个 Agent 架构

```
Router → IntentV2 → PlanningV2 → PreFlight → Execution → QualityValidator
                                                          │
                                    ┌─────────────────────┼─────────────────────┐
                                    ▼                     ▼                     ▼
                              ResultParser          Diagnosis(+迭代)      Discovery
                                    │                     │                     │
                                    └─────────────────────┴─────────────────────┘
                                                          │
                                                          ▼
                                                    Learning → Knowledge
```

**合并优化：**
- **Validator + SelfCritique** → **QualityValidator**（质量验证器）
- 删除冗余 Agent，保留核心功能

### Knowledge Agent 完整功能定位（4个）

| 功能 | 描述 | 当前状态 | 计划 |
|------|------|----------|------|
| **1. 知识检索与事实回答** | RAG 问答 | ✅ 已实现 | 保持 |
| **2. 文献存在性判断** | 判断是否有相关文献 | ⚠️ 部分实现 | 增强 |
| **3. 分析方案生成** | 生成完整分析方案（数据来源、比对物种等） | ❌ 未实现 | **新增** |
| **4. 报告增强** | 为 Discovery 提供生物学背景支撑 | ❌ 未实现 | **新增** |

### 新增 Agent 设计

#### 1. PreFlight Agent（执行前验证）
**职责：**
- 输入文件存在性检查
- 依赖阶段状态检查（manifest）
- 资源可用性检查（CPU/内存/磁盘）
- 参数合法性检查

**输出：**
```python
{
    "valid": True/False,
    "issues": ["输入文件不存在: xxx.fa"],
    "suggested_fix": "请先运行 identify 阶段",
    "stage_status": {...}
}
```

#### 2. QualityValidator Agent（质量验证器）
**合并：** Validator + SelfCritique

**职责：**
- 原 Validator：检查输出文件存在性、manifest 完整性
- 新增 SelfCritique：检查结果合理性、质量评分

**输出：**
```python
{
    "passed": True/False,
    "score": 85,
    "completeness": {...},  # 原 Validator
    "quality": {...},        # 原 SelfCritique
    "issues": [...]
}
```

#### 3. 增强 Diagnosis Agent
**新增功能：**
- 分析失败根因（输入/代码/资源）
- 建议具体修复方案
- 记录修复历史，避免重复错误
- 支持迭代重试（max_iterations）

### 迭代执行机制

```python
max_iterations = 3  # 最大迭代次数
current_iteration = 0

while current_iteration < max_iterations:
    result = await execute()
    
    # QualityValidator 检查
    quality = await quality_validate(result)
    if quality["passed"]:
        break  # 成功，退出
    
    # Diagnosis 诊断
    diagnosis = await diagnose(quality["issues"])
    if not diagnosis["fixable"]:
        break  # 不可修复，退出
    
    # 修复并重试
    await apply_fix(diagnosis["fix"])
    current_iteration += 1
```

### State 扩展字段

```python
{
    # 新增字段
    "pre_flight_result": {...},      # PreFlight 输出
    "quality_validation_result": {...},  # QualityValidator 输出
    "iteration_count": 0,             # 当前迭代次数
    "max_iterations": 3,              # 最大迭代次数
    "fix_history": [...],             # 修复历史
}
```

### 架构债务（紧急）

| 步骤 | 任务 | 文件 | 优先级 | 说明 |
|------|------|------|--------|------|
| 0 | **复用 `_parse_intent_from_query`** | `intent_v2.py` / 公共模块 | **P0** | 替代当前重复实现的强制规则 |

**问题：**
- `intent_v2.py` 重新实现了 pep/karyotype/synteny 等强制规则
- `orchestrator.py` 已有成熟的 `_parse_intent_from_query`
- 重复代码，维护困难

**方案：**
```python
# 推荐：提取到公共模块
from gfa_core.mas.utils.intent_parser import parse_intent_from_query

# IntentAgentV2 使用：
base_intent = parse_intent_from_query(query)  # 硬编码规则
refined_intent = await llm_refine(base_intent)  # LLM 细化
```

### 实施计划

| 步骤 | 任务 | 文件 | 优先级 |
|------|------|------|--------|
| 1 | **复用 `_parse_intent_from_query`** | 公共模块 / `intent_v2.py` | **P0** |
| 2 | 创建 PreFlight Agent | `agents/preflight.py` | P1 |
| 3 | 创建 QualityValidator | `agents/quality_validator.py` | P1 |
| 4 | 增强 Diagnosis Agent | `agents/diagnosis.py` | P1 |
| 5 | 修改 LangGraph 工作流 | `langgraph_orchestrator.py` | P1 |
| 6 | 增强 Knowledge Agent（功能3、4） | `agents/knowledge.py` | P2 |
| 7 | 添加迭代状态管理 | `core/state.py` | P2 |
| 8 | 测试验证 | - | P1 |

## 待办事项

### 明日计划
1. [ ] 测试其他分析阶段（structure/promoter/synteny）
2. [ ] 验证多阶段串联执行（identify → phylogeny → motif）
3. [ ] 检查前端状态显示是否与后端一致

### 中期计划（功能增强）
1. [ ] 创建 PreFlight Agent
2. [ ] 创建 QualityValidator（合并 Validator + SelfCritique）
3. [ ] 增强 Diagnosis Agent（添加迭代支持）
4. [ ] 增强 Knowledge Agent（功能3：分析方案生成）
5. [ ] 增强 Knowledge Agent（功能4：报告增强）

### 总体计划
1. **Phase 1**: 修复核心执行流程 ✅（今日完成）
2. **Phase 2**: 完善所有分析阶段支持 ⏳
3. **Phase 3**: 优化前端状态同步 ⏳
4. **Phase 4**: Agent 架构增强（PreFlight/QualityValidator/迭代机制）⏳
5. **Phase 5**: Knowledge Agent 功能完善（方案生成/报告增强）⏳
6. **Phase 6**: 集成测试和性能优化 ⏳

## 今日任务完成度

| 任务 | 状态 | 备注 |
|------|------|------|
| 修复 completed_stages 追踪 | ✅ | 核心问题已解决 |
| 统一 MAS 与 Pipeline 执行 | ✅ | 现在支持 pep 分析 |
| 修复 LangGraph 循环问题 | ✅ | 无无限循环 |
| 修复前端 API 响应 | ✅ | Success: true |
| 真实数据测试 | ✅ | PEP 分析成功执行 |

**完成度: 5/5 (100%)**

---
记录时间: 2026-04-14 19:50
记录者: xialab的幸运星