# BtToxin_Digger v5 Reproduction - AGENTS.md

本文档为 AI 助手和开发者提供 bttoxin_digger_v5_repro 项目的快速参考指南。

## 项目概述

BtToxin_Digger v5 Reproduction 是一个基于 Pixi 和 Docker 的 BtToxin_Digger 1.0.10 可复现运行环境，集成了最新的 BLAST v5 毒素数据库。

**核心功能：**
- 使用 `ghcr.io/prefix-dev/pixi:latest` 作为基础镜像
- 预装 BtToxin_Digger 1.0.10 和 BLAST+ 2.16.0
- 内置最新版本的 BtToxin 数据库（20251104）
- 支持 Docker 容器化部署

## 目录结构

```
bttoxin_digger_v5_repro/
├── docker/
│   └── Dockerfile              # Docker 镜像构建文件
├── docker-compose.yml          # 本地测试编排配置
├── external_dbs/               # 外部数据库源（构建时复制到镜像）
│   └── bt_toxin/
│       ├── db/                 # BLAST 索引文件 (.phr, .pin, .psq)
│       │   ├── bt_toxin.pdb    # 数据库元数据
│       │   ├── bt_toxin.phr    # 蛋白质序列头索引
│       │   ├── bt_toxin.pin    # 蛋白质序列索引
│       │   ├── bt_toxin.psq    # 蛋白质序列数据
│       │   └── old/            # 历史索引备份
│       └── seq/                # FASTA 序列源文件
│           ├── bt_toxin20251104.fas  # 最新毒素序列（2025年11月）
│           ├── bt_toxin20221208.fas
│           └── updateDB.py            # 数据库辅助脚本
├── pixi.toml                   # Pixi 环境依赖定义
├── pixi.lock                   # 依赖版本锁定文件
├── examples/                   # 测试用例
│   └── inputs/                 # 输入文件
│       └── C15.fna             # 测试基因组文件
└── README.md                   # 项目说明文档
```

## 快速开始

### 构建 Docker 镜像

```bash
cd bttoxin_digger_v5_repro
docker compose build
```

### 运行分析（本地测试）

```bash
# 查看帮助
docker compose run --rm digger-repro pixi run BtToxin_Digger --help

# 运行分析
docker compose run --rm digger-repro pixi run BtToxin_Digger \
  --SeqPath /app/jobs \
  --Scaf_suffix .fna \
  --threads 4
```

### 使用主服务中的 Digger 容器

主项目的 `docker/docker-compose.yml` 中包含一个持久运行的 `digger` 服务：

```bash
# 检查服务状态
docker ps | grep bttoxin_digger

# 执行分析任务
docker exec bttoxin_digger pixi run BtToxin_Digger \
  --SeqPath /data \
  --Scaf_suffix .fna \
  --threads 4
```

## 数据库管理

### 数据库结构说明

- **`seq/` 目录**：存放原始 FASTA 序列文件（如 `bt_toxin20251104.fas`）
- **`db/` 目录**：存放 BLAST 生成的二进制索引文件
- **对应关系**：`db/` 中的文件由 `makeblastdb` 命令从 `seq/` 中的 FASTA 文件生成

### 验证数据库版本

```bash
docker exec bttoxin_digger pixi run blastdbcmd \
  -db /app/.pixi/envs/default/bin/BTTCMP_db/bt_toxin/db/bt_toxin \
  -info
```

**预期输出：**
```text
Database: bt_toxin20251104.fas
Date: Nov 4, 2025  3:35 PM
BLASTDB Version: 5
```

### 更新数据库（未来版本）

当上游仓库发布新版本（如 2026/2027 年）时：

```bash
# 1. 下载新序列文件到 seq/ 目录
cp /path/to/new/bt_toxin20xxxxxx.fas external_dbs/bt_toxin/seq/

# 2. 重新生成索引（使用 makeblastdb）
makeblastdb \
  -in external_dbs/bt_toxin/seq/bt_toxin20xxxxxx.fas \
  -dbtype prot \
  -out external_dbs/bt_toxin/db/bt_toxin \
  -parse_seqids

# 3. 重新构建 Docker 镜像
docker compose build --no-cache

# 4. 重启服务
docker compose -f ../docker/docker-compose.yml up -d digger
```

## 常见任务

### 查看 Digger 帮助

```bash
docker exec bttoxin_digger pixi run BtToxin_Digger --help
```

### 重新构建镜像（无缓存）

```bash
cd bttoxin_digger_v5_repro
docker compose build --no-cache
```

### 查看容器日志

```bash
docker logs bttoxin_digger
```

### 进入容器交互模式

```bash
docker exec -it bttoxin_digger pixi run bash
```

## 故障排查

### 问题：数据库版本不正确

**症状**：分析结果显示使用的是旧版本数据库。

**排查步骤：**
1. 检查 `external_dbs/bt_toxin/seq/` 目录下的文件是否为最新
2. 确认 `external_dbs/bt_toxin/db/` 目录下的索引文件与 seq 文件匹配
3. 验证镜像已重建：`docker images | grep digger`
4. 重启服务：`docker compose -f ../docker/docker-compose.yml up -d digger`

### 问题：Perl 警告

**症状**：`Possible precedence issue with control flow operator`

**说明**：这是 Perl 5.26 与旧代码的兼容性问题，不影响程序运行，可忽略。

### 问题：容器启动失败

**排查步骤：**
1. 检查 Docker 是否运行
2. 查看详细日志：`docker compose logs`
3. 确认端口未被占用

## 开发说明

### 修改 Dockerfile

如需修改环境依赖：
1. 编辑 `pixi.toml`（添加/删除依赖）
2. 运行 `pixi lock` 更新 `pixi.lock`
3. 重新构建镜像

### 本地开发模式（不使用 Docker）

```bash
# 安装 Pixi 环境
cd bttoxin_digger_v5_repro
pixi install

# 链接外部数据库
ENV_BIN=.pixi/envs/default/bin
rm -rf "$ENV_BIN/BTTCMP_db/bt_toxin"
ln -sfn $(pwd)/external_dbs/bt_toxin "$ENV_BIN/BTTCMP_db/bt_toxin"

# 运行
pixi run BtToxin_Digger --help
```

## 相关文件

- `README.md`：项目完整说明（英文）
- `README_CN.md`：项目完整说明（中文）
- `docker/Dockerfile`：Docker 镜像构建配置
- `docker-compose.yml`：本地测试编排配置