# bbav5 项目记忆 - 决策与踩坑

> 创建时间：2026-03-18 | 最后更新：2026-04-15
> 
> 本文件记录**设计决策**和**踩坑经验**，运行时配置见 AGENTS.md

---

## 1. 架构设计决策

### 1.1 三层架构

```
Frontend (Vue3 + FastAPI)
    ↓
Core Framework (Contracts + Reproducibility + API)
    ↓
Analysis Execution (CLI Scripts + Skills)
```

**决策理由**: 解耦前端展示与后端执行，契约层保证阶段间数据流转可靠

### 1.2 目录结构规范

```
workspace/{job_id}/
├── final/              # 最终产物（只读，下游依赖）
├── {stage}/analysis/   # 中间文件（可追溯）
├── logs/               # 执行日志
└── input/              # 输入文件（只读）
```

**踩坑**: 早期版本输出到 `{stage}/final/`，下游阶段找不到文件 → 统一为 `final/`

### 1.3 契约化设计

每个阶段契约文件 (`*_contract_v1.md`) 定义：
- **输入契约**: 文件类型、来源
- **输出契约**: final/ 必须产物
- **Manifest 契约**: artifacts 字段最小集

---

## 2. 重大踩坑记录

### 2.1 RNA-seq 环境问题 (2026-03-19)

**问题**: RNA-seq 阶段执行失败，工具找不到

**原因**: 用错了 conda 环境，应该用 `rnaseq` 而非 `test4py311`

**修复**: 
- rnaseq_qc/align/quant/de/enrich → `conda activate rnaseq`
- expression 绘图 → `conda activate rnaR`

### 2.2 Manifest 路径问题 (2026-03-27)

**问题**: 前端读取 manifest 失败

**原因**: 返回路径是相对路径，前端无法解析

**修复**: Manifest 必须包含 `full_path` 绝对路径

### 2.3 Agent 意图识别慢 (2026-04-05)

**问题**: RNA-seq 意图识别耗时 16 分钟

**原因**: LLM 调用过多

**修复**: 添加 `fast_intent` 关键词匹配，降至 <5 秒

### 2.4 循环迭代未实现 (2026-04-15)

**问题**: Discovery → Learning 是固定边，无法循环

**原因**: Orchestrator 没有条件边设计

**修复**: 
- `langgraph_orchestrator.py` 新增 `iteration_count`, `max_iterations`
- `_discovery_decision()` 决策函数
- 循环逻辑: should_continue → replan → Planning

---

## 3. 关键修复索引

| 日期 | 文件 | 详情 |
|------|------|------|
| 2026-03-27 | memory/2026-03-27.md | RNASEQ_QC 修复 |
| 2026-03-28 | memory/2026-03-28.md | RNASEQ_ALIGN 修复 |
| 2026-03-29 | memory/2026-03-29.md | RNASEQ_QUANT 修复 |
| 2026-03-30 | memory/2026-03-30.md | RNASEQ_DE 修复 |
| 2026-04-03 | memory/2026-04-03.md | Celery 集成 |
| 2026-04-05 | memory/2026-04-05.md | 意图识别优化 |
| 2026-04-06 | memory/2026-04-06.md | PEP/PPI 技能化 |
| 2026-04-07 | memory/2026-04-07.md | 其他修复 |
| 2026-04-15 | 全局 MEMORY | 循环迭代修复 |

---

## 4. 已知问题

| 问题 | 状态 | 备注 |
|------|------|------|
| RouterAgent 第74行 `prompt` 变量 | 待修复 | 应为 `full_prompt` |
| 两个 Orchestrator 并存 | 待重构 | orchestrator.py (2656行) + langgraph_orchestrator.py (638行) |
| _route_query 关键词过多 | 待优化 | 约100个关键词，维护困难 |

---

## 5. 技能化状态

全部 16 个核心阶段已技能化，见 `skills/` 目录

---

## 6. 修订检查清单

- [ ] 是否遵循契约文档 (`*_contract_v1.md`)
- [ ] 输出是否在 `final/` 目录
- [ ] Manifest 是否包含 `full_path`, `size`, `sha256`
- [ ] 是否使用正确的 Conda 环境
- [ ] 是否更新 MEMORY.md 或 memory/*.md

---

*详细日志见 `memory/` 目录*