From 3ed9558bac5545d9e85a1242977ac19dfd90502b Mon Sep 17 00:00:00 2001
From: zly <644706215@qq.com>
Date: Sat, 17 Jan 2026 12:38:24 +0800
Subject: [PATCH] docs: add AGENTS.md for BtToxin_Digger reproduction guide

---
 bttoxin_digger_v5_repro/AGENTS.md | 206 ++++++++++++++++++++++++++++++
 1 file changed, 206 insertions(+)
 create mode 100644 bttoxin_digger_v5_repro/AGENTS.md

diff --git a/bttoxin_digger_v5_repro/AGENTS.md b/bttoxin_digger_v5_repro/AGENTS.md
new file mode 100644
index 0000000..517ef2f
--- /dev/null
+++ b/bttoxin_digger_v5_repro/AGENTS.md
@@ -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`：本地测试编排配置