生信圈有一个默认的坏习惯：每次分析都现写脚本。README 上跑一次，交给别人跑就报错，重跑一遍结果还不一样。很多人把这归咎于”环境问题”，但根子是每次都在从零生成代码，而不是复用经过测试的实现。Linxira Bio SDK 的出发点就是反着来的一句定位：让常规分析用经过测试的实现，而不是每次运行生成一个新脚本。我翻了它的仓库，把它的结构拆一遍。

本系列共三篇：第一篇（概览与观点，即本篇）· 第二篇（执行链路：一条命令从 JSON 任务到结果图表） · 第三篇（约束机制：schema 门禁、只读的环境计划与许可证发版门禁）。

执行模型：默认本地，资源不够才往上走

Bio SDK 的执行模型在文档里写得很明确：本地执行是默认，只有当实测的 CPU 时间、内存、GPU、数据库或存储需求超过本地执行包络时，才把工作移去本地 GPU、机构调度器或经批准的云端。”浏览器在线服务只是连接器，不是计算内核”——需要显式用户操作门、人工控制的认证，并且绝不存储或自动填充账号凭据。

这句话信息量很大。它把”本地优先”从口号变成了规则：不是”我们拒绝云”，而是”先测，超了再迁移”——迁移理由必须是可测量的指标，不是感觉。这也解释了为什么结构查看器要把解压后的 PDB/mmCIF 限制在 128 MiB、10 万个原子以内——本地渲染的物理边界是设计过的，不是撞运气。

仓库结构：六块各管一摊

1
2
3
4
5
6
7
8
9
apps/linxira-bio-ui   原生 Rust 桌面应用（无 WebView）
capabilities/         机器可读的能力目录（带版本）
engine/               Rust 运行时（未来会有 benchmark 支撑的 C++ 内核）
runtimes/             Python/R/Java 运行时编排
schemas/              能力与结果的 JSON Schema
skills/               绑定到版本化能力的 agent 指令
workflows/            一方的 Python/R 工作流脚本（带 schema、测试、锁文件）
sdk/python             Python SDK（CLI 合约稳定后发布）
profiles/ packaging/ tests/ tools/ scripts/

产品面总共四个：linxira-bio CLI、skills/（agent 指令）、linxira-bio-ui（原生 Rust GUI，无 WebView）、skill-pack.json（给 agent 运行时和 linxira-skills 的导入边界）。注意没有 MCP server 和 Python SDK 的正式版——README 明说”Python SDK 待 CLI 合约稳定后发布，MCP server 待能力和结果 schema 稳定后发布”。合约没稳定，就不急着加接口，这个克制在现在的工具圈很难得。

CLI 是干的，不是演示

仓库里能直接跑的是一堆真实命令。当前能力覆盖：环境审计、文件识别与预览、FASTA/FASTQ/SAM/VCF/BED 交集/表达矩阵/PDB 的确定性指标计算，结果导出 CSV/TSV/JSON/JSONL/XLSX。举几个：

1
2
3
4
5
6
7
8
9
10
linxira-bio environment audit --json
linxira-bio dataset inspect variants.vcf --json
linxira-bio sequence stats tiny.fa --json
linxira-bio fastq qc valid.fastq --json
linxira-bio alignment qc valid.sam --json
linxira-bio variant stats mixed.vcf --json
linxira-bio interval intersect left.bed right.bed --json
linxira-bio expression matrix-qc counts.tsv --json
linxira-bio structure pdb alphafold-style.pdb --alphafold-plddt --json
linxira-bio export table result.json result.xlsx

值得注意的细节：环境计划（environment plan）支持 local-core、scripting、managed-runtimes、containers、sequence-search、genomics-cli、full-local 七档，规划模式有 use-existing、managed-user、project-isolated、system-missing-only 四种，且每个计划都带 dry-run 事务边界——environment.apply.v1 仍是计划中的能力，当前版本只能预览，不能执行安装。一个 SDK 把”规划环境”和”安装环境”分开、让前者只读，这是对”会破坏用户系统”这件事的敬畏。

能力版本化 + CI 里的 schema 门禁

能力全部带版本号：sequence.stats.v1、fastq.qc.v1、variant.stats.v1、structure.pdb.summary.v1…… 结果输出统一结构化 JSON，可直接喂下游。schema 用 JSON Schema Draft 2020-12，CI 用固定版本的校验器跑：scripts/validate-repository.py 校验整个仓库的合约，scripts/generate_third_party_notices.py --check-config 校验第三方许可配置。

这就是”能力数量多了不失控”的机制：每个能力有 schema、有版本、有 CI 校验、有中英文文档。功能多到五十几个，靠人记是不行的，靠约定才行。

依赖治理：发版时许可证错了，构建直接失败

Bio SDK 对第三方依赖的态度是：不只是声明，而是机器可验证。仓库里有 deny.toml（cargo-deny 配置），发版走 scripts/stage-release.py：解析锁定的目标相关发布图，生成 THIRD_PARTY_DEPENDENCIES.json 和 .txt——缺失、歧义、过期或被修改的许可证文本，直接让发版失败。

再配上前文提过的门禁：记录 SPDX 标识符和源仓库 → 确认与 AGPL-3.0-or-later 的兼容性 → 优先 MIT/Apache/BSD/ISC/Zlib → LGPL/MPL/GPL/模型权重/数据库条款单独审查 → 拒绝专有、源码可用、使用领域限制或模糊条款。在这个”把开源组件拼起来就声称开源”的时代，这套流程把合规做成了发版流程的一部分，而不是免责声明。

工作流：一方脚本 + 锁文件 + 许可声明

workflows/ 下的 Python/R 工作流脚本（比如跑 DESeq2 这类）带着自己的 schema、测试、锁文件和许可声明发布。linxira-bio workflow run 在直接调用批准的本地解释器之前，先验证每个 pack。关键约束在 README 里写得很清楚：发行版不捆绑第三方解释器、包、数据库或模型；已编目的 pack 不意味着已安装的运行时或可用的分析能力。R 的 DESeq2、Python 的 Biopython/NumPy 都只是”已编目、未再分发”的依赖。

平台策略：Windows 优先，别的明确说出来

平台支持也值得看：Windows 是主要桌面和入门平台，Debian 和 Arch 是工作站/服务器/HPC 的受支持 Linux 家族，macOS 明确”不是当前测试或打包目标”。Windows 上靠 WSL Debian 提供老生信组件的兼容，WSL Arch 是当前平台提供方和未来 Linxira WSL 基础。该支持什么、不该支持什么，都是写死公开的——对用户来说，”明确不支持”比”承诺了做不到”好一百倍。

收束

Bio SDK 拆完，印象最深的是它的自我约束：能力合约没稳定不发布 SDK 和 MCP；环境规划只读、安装另算；不捆绑第三方运行时；许可证错了发版失败；平台支持范围白纸黑字。生信工具不缺算法，缺的是把”测过、锁过、审计过”变成默认的工程纪律。这个纪律，比它 50+ 的能力列表更值得抄。执行链路和约束机制各有一篇专门拆：第二篇跟着一条命令从 JSON 任务走到结果图表，第三篇拆 schema 门禁、只读环境计划与许可证发版门禁。