# AGENTS.md - bbav5 基因家族分析执行系统

## 项目定位

**执行型 Agent** - 运行基因家族分析流程，调用 run_*.py 脚本

## 分析阶段速查

### 核心阶段 (13个)

| 阶段 | 脚本 | 功能 | 环境 |
|------|------|------|------|
| identify | run_identify.py | 基因鉴定 | test4py311 |
| phylogeny | run_phylogeny.py | 系统发育树 | test4py311 |
| motif | run_motif.py | MEME motif | test4py311 |
| domain | run_domain.py | Pfam结构域 | test4py311 |
| structure | run_structure.py | 基因结构 | test4py311 |
| promoter | run_promoter.py | 启动子分析 | test4py311 |
| synteny | run_synteny.py | 种内共线性 | test4py311 |
| interspecies_synteny | run_interspecies_synteny.py | 种间共线性 | test4py311 |
| karyotype | run_karyotype.py | 核型图 | test4py311 |
| combo | run_combo.py | 组合图 | test4py311 |
| ppi | run_ppi.py | 蛋白互作 | test4py311 |
| expression | run_expression.py | 表达分析 | **rnaR** |
| pep | run_pep.py | PEP分析 | test4py311 |

### RNA-seq 流水线 (5个)

| 阶段 | 脚本 | 功能 | 环境 |
|------|------|------|------|
| rnaseq_qc | run_rnaseq_qc.py | 质控 | **rnaseq** |
| rnaseq_align | run_rnaseq_align.py | 比对 | **rnaseq** |
| rnaseq_quant | run_rnaseq_quant.py | 定量 | **rnaseq** |
| rnaseq_de | run_rnaseq_de.py | 差异表达 | **rnaseq** |
| rnaseq_enrich | run_rnaseq_enrich_v2.py | 富集分析 | **rnaseq** |

### 辅助阶段 (9个，无契约)

genome_prepare_v2, kaks_v2, ortholog, cis_element_http, fetch_expression, tree_plot, ppi_v2, ppi_v2_with_repro, summary

## 执行流程

1. **识别意图** → 确定目标阶段
2. **检查输入** → 验证契约文件存在 (input/ 或 final/)
3. **执行脚本** → `python apps/cli/run_*.py` 或调用 Skills
4. **验证输出** → 检查 final/ 目录产物 + Manifest
5. **报告结果** → artifacts 列表 + metrics 摘要

## Conda 环境 [关键]

| 环境名 | 用途 | 激活命令 |
|--------|------|----------|
| test4py311 | 标准分析 | `conda activate test4py311` |
| rnaseq | RNA-seq流程 | `conda activate rnaseq` |
| rnaR | 表达绘图 | `conda activate rnaR` |

**注意**: expression阶段用rnaR，其他绘图用test4py311

## 关键目录

| 目录 | 内容 |
|------|------|
| `apps/cli/` | 27个 run_*.py 脚本 |
| `gfa_core/schemas/stages/` | 18个契约文件 *_contract_v1.md |
| `skills/` | 技能封装 |
| `scripts/` | R绘图脚本 |

## Manifest 结构

```json
{
  "manifest_version": "1.0",
  "stage": "identify",
  "status": "success",
  "prefix": "Ft.SPL",
  "artifacts": { "key": {"path": "final/...", "type": "fasta"} },
  "metrics": { ... }
}
```

## 工作原则

- **契约优先**: 有契约的阶段执行前检查输入，执行后验证输出
- **Manifest记录**: 每次执行生成完整 Manifest
- **可复现性**: reproducibility_v2.py 确保分析可追溯
- **错误诊断**: 失败时读错误日志，给具体修复建议

## 常用命令

```bash
# 运行鉴定阶段
python apps/cli/run_identify.py --prefix Ft.SPL --workspace ~/test_workspace

# 启动前端服务
python apps/web/vue3/main.py
```