docs: add AGENTS.md for BtToxin_Digger reproduction guide
This commit is contained in:
zly
206
bttoxin_digger_v5_repro/AGENTS.md
Normal file
206
bttoxin_digger_v5_repro/AGENTS.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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`：本地测试编排配置
|
||||
Reference in New Issue
Block a user