# Linux 支持与交付计划

## 支持契约

ABI 以无需 Docker 的 Linux 原生安装和 Agent 运行为目标。核心包支持 Linux
x86_64 与 arm64；第三方生物信息工具按插件和架构逐项认证。

| 范围 | Linux 支持 |
|---|---|
| Python 包、CLI、MCP、SciPlot、规划、检查与报告 | 必须支持 x86_64 和 arm64 |
| 托管 Conda/Mamba 环境 | 声明包可求解时必须支持 |
| 外部生物信息工具 | 按插件和架构认证 |
| Docker 镜像 | 可选、手动构建的 Linux 部署产物 |

非 Linux 操作系统不属于当前开发和认证范围。“支持”是指一台干净 Linux
机器可以安装 wheel、发现或创建运行环境、解释每个已选择的工具与解释器，并完成
相应冒烟测试。

## 已实现基础

统一的 `abi.runtime_environment` 解析器现在负责 Linux 运行环境发现。
`abi.config`、质粒引擎、本地工具执行、运行时锁和 Nextflow 导出器均委托该层选择
环境前缀。

Mamba 根目录优先级为：

1. CLI/API 显式 `mamba_root`。
2. `ABI_MAMBA_ROOT`。
3. `MAMBA_ROOT_PREFIX`。
4. 兼容变量 `AUTOPLASM_MAMBA_ROOT`。
5. 已填充的仓库兼容根目录。
6. 已填充的 `${XDG_DATA_HOME:-~/.local/share}/abi/mamba`。
7. 全局 `micromamba`、`mamba` 或 `conda` 的 `<solver> info --json` 结果。
8. 空的或默认 `${XDG_DATA_HOME:-~/.local/share}/abi/mamba`。

显式路径具有权威性，缺失时直接失败。命名环境优先
`<root>/envs/<name>`，兼容 `<root>/<name>`，也可使用求解器报告的前缀。
可执行文件依次从显式路径、分配环境、registry 资源目录以及策略允许的全局
`PATH` 解析。ABI 内部 Python 使用 `sys.executable`，工具 Python 优先使用其
分配环境。

无需运行分析即可检查解析结果：

```bash
abi env discover --output-json
abi env doctor --tool fastp --tool samtools --output-json
```

报告包含 Linux 架构、ABI Python、Mamba 根目录及来源、环境前缀、请求的工具路径、
Python 路径和健康问题。

## 可移植环境安装

ABI 现在无需源码 checkout 即可创建或更新 wheel 内置的环境：

```bash
abi env install --type rnaseq_expression --dry-run --output-json
abi env install --type rnaseq_expression
abi env update --env rnaseq --output-json
```

安装器依次选择 `micromamba`、`mamba`、`conda`，也接受明确的
`--solver`/`ABI_ENV_SOLVER`。报告记录求解器路径和版本、生成规范的 SHA-256、
实际参数向量、目标前缀，以及环境是新建、更新还是保持不变。按插件选择时会对其
分配环境去重。

默认可写根目录为 `${XDG_DATA_HOME:-~/.local/share}/abi/mamba`；CLI 和环境变量
指定的根目录仍具有权威性。求解器子进程保留 Linux 动态库变量，但不会继承宿主
`PYTHONPATH`。安装具有幂等性，更新执行 prune；求解失败不会发布未应用的规范，
缺失目标环境时 `update` 会先执行创建，不含 `conda-meta/history` 完成标志的残缺
前缀不会被视为有效环境，且 `--dry-run` 不会创建目标根目录。

x86_64 与 arm64 wheel 冒烟测试都会先切换到隔离的临时目录，再通过严格测试求解器
实际执行环境创建并读取打包的 `environments.yaml`，从而证明该路径不会回退到源码
checkout 或仓库本地 `envs/*.yml`。

## 后续交付阶段

### 阶段 3——插件能力矩阵

打包的 `platform_support` 清单现在为每个插件及全部 21 个环境发布严格的
`certified | partial | unsupported` Linux x86_64/aarch64 单元格；每个单元格都包含
阻塞项、可用替代方案和证据。工具能力继承其所分配环境，避免工具与环境声明重复或
互相矛盾。被多个插件环境分配的工具必须使用 `--type` 消歧；未在矩阵中声明的 CPU
架构默认拒绝：

```bash
abi env discover --output-json
abi env doctor --type rnaseq_expression --output-json
```

x86_64 核心能力已经认证，但插件和环境单元格会保持 `partial`，直到记录发布范围内
的完整求解及代表性真实工具 smoke 证据。ViWrap 在官方多环境运行时和数据库 bundle
部署完成前，于两个架构上均为 `unsupported`；`abi env doctor` 和托管环境操作会拒绝
不支持的单元格。

带日期的 [2026-07-29 x86_64 检查点](../evidence/linux_x86_64_capability_20260729.json)
记录了 21 个规范环境中 18 个完成前缀，以及通过的代表性版本 smoke；
`autoplasm-rgi`、`autoplasm-scapp`、`autoplasm-checkm2` 缺失。远端 checkout 早于
当前矩阵，因此该检查点用于识别 blocker，不认证当前规范或任何 aarch64 单元格。

- 保持 Linux 架构约束与工具/环境元数据同步。
- 在 Linux x86_64 与 Linux arm64 上求解全部 `envs/*.yml`。
- 每个插件/架构单元标记为 `certified`、`partial` 或 `unsupported`，并列出
  阻塞项与支持的替代方案。
- 为每个已认证单元增加代表性真实工具冒烟测试。
- 让 `abi env doctor --type <plugin>` 在执行前拒绝不支持的组合。

退出标准：每个插件发布真实、机器可读的 Linux 能力状态，已认证单元通过真实工具
验证。

### 阶段 4——Linux CI 认证

必需 CI 矩阵覆盖：

- Python 3.10–3.13 editable 与 wheel 安装；
- 所有支持 Python 上的 Linux x86_64 核心测试；
- Linux arm64 wheel、CLI、MCP 与代表性环境冒烟；
- SciPlot 字体/渲染；
- 仓库本地、用户级与全局 Mamba 发现；
- 分配环境工具与全局 `PATH` 工具；
- 含空格路径和符号链接；
- 运行时锁可复现性与溯源断言。

每个 x86_64 Python 3.10–3.13 job 现在都会同时执行 editable 安装、默认
sdist→wheel 构建、wheel 重装，并在离开源码 checkout 后运行共享能力验证器。原生
arm64 wheel job 使用同一验证器。它验证每个插件/环境架构单元格、严格状态词汇与
支撑字段，以及 ViWrap fail-closed doctor 行为。release workflow 在源码 checkout
外重复验证，并把 `abi-linux-capability-v<version>.json` 附加到 GitHub Release；
PyPI publisher 仍只选择 wheel 与 sdist。

常规 CI 使用小型代表环境；大型数据库和长时间真实工具流程放入定时或人工批准
验收。Docker 镜像构建不属于必需矩阵。

退出标准：必需 Linux job 连续两个版本通过，并把能力矩阵附加到发布证据。

### 阶段 5——发布与运维

- 发布干净机器 Linux 安装与故障排查指南。
- 覆盖求解器选择、字体、R/Bioconductor、Java、原生库、架构不匹配和数据库路径。
- 在全新 x86_64 与 arm64 环境验证已发布 wheel。
- 记录 wheel 哈希、架构、Python/求解器版本、环境根目录、入口测试和代表性插件
  冒烟结果。

## Docker 手动策略

`.github/workflows/docker.yml` 仅保留 `workflow_dispatch`；PR、push、tag 和
release 均不会启动镜像构建。容器输入变化时建议手动构建，发布容器镜像前必须
手动验证；它不是 Python/插件或 PyPI 门禁。

```bash
gh workflow run docker.yml --ref master \
  -f plugin=rnaseq -f push=false -f push_to_dockerhub=false
```

发布时把已验证的 `v<version>` tag 设为 workflow ref，先记录成功的
`push=false` 运行，再在同一 tag 上以 `push=true` 重跑。workflow 会在修改
registry 前再次完成本地构建和 `abi list-types` 验证。

## 完成定义

Linux 支持完成需要：

- 干净 wheel 无需 Docker 或源码 checkout 即可安装；
- Mamba 根目录、前缀、工具和 Python 解释器可确定解析，并由
  `abi env doctor` 报告；
- x86_64 与 arm64 核心 CI 连续两个版本通过；
- 每个插件发布 Linux 能力状态；
- 已认证插件通过代表性真实工具冒烟；以及
- 运行时锁、溯源和双语文档保留所选路径、版本、限制与验证证据。
