bttoxin-pipeline/tools/reproduction/bttoxin_digger/AGENTS.md

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 镜像

cd bttoxin_digger_v5_repro
docker compose build

运行分析（本地测试）

# 查看帮助
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 服务：

# 检查服务状态
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 文件生成

验证数据库版本

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

预期输出：

Database: bt_toxin20251104.fas
Date: Nov 4, 2025  3:35 PM
BLASTDB Version: 5

更新数据库（未来版本）

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

# 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 帮助

docker exec bttoxin_digger pixi run BtToxin_Digger --help

重新构建镜像（无缓存）

cd bttoxin_digger_v5_repro
docker compose build --no-cache

查看容器日志

docker logs bttoxin_digger

进入容器交互模式

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）

# 安装 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：本地测试编排配置