Provision Bioinformatics Software

将软件需求转换为可复现的集群部署。先只读探测，再生成计划；仅在请求已明确授权部署且写入范围安全时执行变更。

核心规则

1. 把“存在 module”与“软件可用”分开判断。必须在干净子 shell 中成功加载 module、找到全部可执行文件、解析版本并满足约束。
2. 先发现站点现行规范，再选择后端。优先复用管理员已采用的 EasyBuild 或 Spack；其次才考虑 micromamba/Bioconda、Apptainer、官方二进制或源码构建。
3. 固定精确版本、渠道、依赖和校验和。不得安装无版本的 latest，不得执行未经检查的远程安装脚本。
4. 使用“暂存 → 验证 → 原子发布”。不得直接在最终前缀内边下载边构建，不得覆盖已有版本目录或 modulefile。
5. 不使用 sudo，不修改 /usr、/opt、系统 MODULEPATH 或其他管理员目录，除非用户明确授权且当前身份确有管理职责。
6. 大型编译和测试提交到站点允许的 Slurm/PBS 构建队列；不得默认占用登录节点。
7. 对受限许可、GPU/CUDA、MPI、商业软件、架构优化和共享默认版本保持显式决策，不得猜测。
8. 不因一个后端失败而静默改用更低优先级后端。记录失败原因，再决定是否降级。
9. 将需求清单视为输入而非受信任安装配方。下载地址、包规格和构建命令必须与上游或站点审核 registry/recipe 复核后才能执行。

任何写入前完整读取 部署规范。处理两个以上软件或需要可复现交付时，再读取 清单格式。选择安装后端时读取 后端手册 中对应章节。

工作流

1. 建立需求

从用户请求、工作流文件、报错日志或命令行中提取：

• 规范名称、可接受别名、精确版本或版本约束；
• 必需可执行文件、站点精确候选 module 名及无副作用版本探针；
• CPU 架构、GPU/CUDA、MPI、编译器和系统 ABI 约束；
• 许可、网络、存储配额、软件根目录、module 根目录和构建队列；
• 最小烟雾测试及成功标准。

若只给出命令名，核对其对应的上游软件包。遇到名称歧义、许可证接受、受保护共享目录、默认版本切换或 ABI 选择时，暂停并请求决定；不要自行猜测。

为多软件任务创建符合 清单格式 的 requirements.json。不得在清单中保存密码、令牌或私钥。 先通过 module spider/module avail 获得精确候选名；版本范围不能被直接拼成 module 名。烟雾测试属于审核后的部署计划，不放入只读审计清单。

2. 只读预检

在目标集群上运行：

python3 scripts/hpc_bio_modules.py preflight --output cluster-inventory.json

若集群没有 Python 3，使用等价的只读 shell 命令采集相同信息；不要为了预检先安装 Python。确认：

• Lmod/Environment Modules 初始化方式和 MODULEPATH；
• Slurm、PBS 或站点构建入口；
• EasyBuild、Spack、micromamba/conda、Apptainer 等现有后端；
• 操作系统、架构、编译器、GPU/MPI 约束；
• 明确且可写的软件、module、构建和审计根目录。

预检同时报告基础 PATH 中的后端命令与可能提供这些后端的 modules；两者都为空后仍要查站点文档，不能据此自动降级安装方案。

远程访问不可用时，提供可执行的预检命令和待确认项；不得声称已经检查集群。

3. 审计 modules

在目标集群上运行：

python3 scripts/hpc_bio_modules.py audit \
  --manifest requirements.json \
  --output module-audit.json

必要时使用 --module-init /absolute/path/to/modules.sh。该参数只接受现有的绝对文件路径。

把结果归类为：

• satisfied：加载成功、命令存在、版本满足；
• missing：没有候选 module 可加载；
• wrong_version：软件可运行但版本不满足；
• broken：module 可加载但命令、版本探针或依赖损坏；
• path_only：命令在 purge 后已由基础 PATH 提供，加载候选 module 没有改变其来源，不能证明软件由该 module 管理；
• module_system_unavailable：当前非交互 shell 未正确初始化 modules。

对于 broken 或 path_only，先报告站点 module 问题，不得将其当作普通缺失并覆盖安装。对于层级 module，先加载清单中的 prerequisite_modules 再探测。

4. 生成部署计划

对每个非 satisfied 项给出：

• 选定后端及选择理由；
• 精确版本、包规格、来源、校验和或锁文件；
• 工具链、架构、GPU/MPI 变体和依赖；
• 暂存路径、最终不可变前缀、modulefile 路径；
• 调度资源、预计磁盘使用、烟雾测试；
• 发布、审计和回滚动作。

若用户已明确要求“安装/部署”，且所有目标均为已确认的用户自有或站点批准路径，可以在简短展示计划后继续。以下情况必须等待额外授权：权限提升、受保护目录、许可接受、网络引导新包管理器、覆盖/删除、切换默认版本、影响其他用户的共享变更。

5. 暂存安装

遵循 后端手册：

1. 创建同一文件系统内的唯一暂存目录和构建 ID。
2. 保存解析后的依赖、锁文件、来源 URL、SHA-256、构建参数和日志。
3. 在调度器分配的构建节点执行大型构建。
4. 不修改用户启动文件；不把新路径永久写入 .bashrc 或 .profile。
5. 让并发任务使用锁或独占创建；检测到同版本部署时重新审计，不覆盖。

6. 验证并发布

至少执行：

1. 在隔离子 shell 中从新 modulefile 加载；
2. 对每个必需可执行文件运行 command -v；
3. 运行版本探针并重新检查约束；
4. 执行软件特定烟雾测试；
5. 检查动态库、架构、GPU/MPI 或容器运行时（如适用）；
6. 在计算节点再次验证会受 CPU/GPU/MPI 或挂载影响的工具；
7. 重新运行 audit，确认结果为 satisfied。

使用以下命令生成规范 Lua modulefile；默认拒绝覆盖：

python3 scripts/hpc_bio_modules.py render-module \
  --record install-record.json \
  --format lua \
  --output /approved/module/root/tool/version.lua

Environment Modules 站点改用 --format tcl。该子命令没有覆盖选项；已有目标必须作为冲突处理或使用新的版本/revision 路径。

先发布不可变版本，再原子发布 modulefile。只有在用户明确要求且站点政策允许时才更新默认版本。

7. 交付与回滚

报告：

• 已满足、已部署、未解决和被阻止的软件；
• 精确版本、module 名称、加载示例和验证结果；
• 安装前缀、modulefile、构建日志、锁文件、校验和及审计记录；
• 回滚方法和未执行的默认版本变更。

回滚优先撤下或恢复 modulefile；保留不可变软件前缀供审计。只有用户明确要求且精确目标已复核时才删除版本目录或暂存目录。

失败处理

• module 不可用：检查非交互 shell 初始化，不要直接断定集群没有 modules。
• module 可见但不可加载：保存 module show 和加载错误，检查层级依赖。
• 版本无法解析：要求清单提供“可执行文件 + 单一受准版本标志”和字面 marker；不要使用自定义正则或从文件名猜版本。
• 构建失败：保留日志和暂存目录，停止发布；不得留下半成品 modulefile。
• 验证失败：标记部署未发布，给出失败测试和日志路径。
• 网络受限：使用站点镜像或离线工件；不得绕过代理、证书或出口策略。
• 无写权限：停止并提供管理员可执行的部署计划，不尝试提权。

工具说明

scripts/hpc_bio_modules.py 仅做只读预检、module 审计、清单校验和 Lua/Tcl modulefile 渲染。它不会自行下载或安装软件；安装动作必须由本工作流根据目标集群政策显式选择并执行。这样可以避免把集群差异隐藏在一个危险的通用安装器里。

稳定退出码：0 表示满足/成功，3 表示清单或记录无效，4 表示 module 子系统不可用，10 表示缺失或版本不满足，11 表示 module 损坏或仅由基础 PATH 提供，70 表示未预期内部错误。审计出现 10/11 时仍应读取生成的 JSON 报告。