# ABI 论文大纲

## 暂定标题

**ABI：面向隐私型智能体生物信息分析的契约编译控制层**

## 定位与主张边界

ABI 是系统/技术贡献，不是新的生物学学习算法，也不是某一个分析插件。它是一个插件化控制层，
将机器可读的生物学工作流契约编译为可检查、受权限门控制的执行与证据。YAML 配置和声明式 DAG
是重要事实源，但不能单独完成分析执行或结果解释；插件代码、工具与资源契约、运行时适配器、
输出断言、标准表、溯源、报告和限制声明共同构成完整生命周期。

论文分开提出两条实证主张：

1. **Agent 可操作性**：在重新运行、预注册的本地可部署模型 benchmark 上，ABI 相对于 shell、
   通用工具调用和信息量匹配的静态文档，提高可靠任务完成能力。
2. **生物学有效性**：在真实公开数据上，ABI 能完成可审计分析并恢复预注册生物学端点。
   Airway 与细菌 WGS 构成配对 running example，SCAPP 构成旗舰 case study。

所有既有 ABI-Bench 分数均不作为第一条主张的证据。规范指标表将相关单元标为
`pending_new_run`，直至全新的本地模型确认性实验在干净提交上通过 preflight。

## Introduction——六段式正文草稿

**第 1 段：背景与动机。** 生物学分析往往需要组合大量命令行工具、参考数据库、环境依赖与
研究特异的统计选择。AI Agent 可以帮助操作这些流程，但敏感组学数据通常不应上传到外部模型，
因此本地可部署模型是许多实验室更现实的使用场景。本文贯穿使用两个公开研究：重分析 Airway
RNA-seq 数据时，Agent 必须在比较地塞米松与 untreated 样本的同时保留 donor 配对设计；重分析
六株 ST93 MRSA 时，则需要执行另一条由质控、组装、注释、序列分型和耐药分析组成的链路。
二者所需的人机交互却相同：研究者描述生物学目标、审阅具体计划、授权真实执行，并获得可追溯
证据，而不是一串不透明的 shell 命令。

**第 2 段：现有方式的限制。** 通用 Agent 直接操作这些分析时缺少三种能力。第一，仓库文档与
shell 访问不是可执行契约，不能阻止 Agent 编造参数、路径或流程分支。第二，通用工具调用只暴露
孤立动作，没有把它们绑定到依赖顺序、资源就绪状态、权限边界和预期输出。第三，传统工作流描述
可以调度命令，但不一定向 Agent 提供紧凑统一的发现、诊断、结果检查、生物学解释和限制披露
生命周期。对小型本地模型而言，这些缺口尤其关键：只有受约束的操作仍然可靠，隐私优势才有
实际价值。

**第 3 段：问题本质与目标。** 我们的目标是让本地 AI Agent 能操作异质的生物信息分析，而无需
为每项研究重新生成一套 shell pipeline。硬约束包括：生物学选择必须保留在各插件中；计划必须
在执行前确定、可检查；真实运行必须经过明确授权；软件和数据库身份必须可恢复；执行成功绝不能
与生物学有效性混为一谈。因此，我们把分析定义为“契约编译生命周期”，而不是自由形式的命令
生成。

**第 4 段：关键挑战。** 这一目标带来三个挑战。第一，不同分析类型在样本模型、条件分支、工具、
数据库、输出和科学断言上均不同；单一硬编码规划器无法保存这种异质性，而每个流程单独设计接口
又不可扩展。第二，语法上合理的计划仍可能因可执行文件、环境、参考资源、权限或中间产物缺失而
失败；只验证 YAML 或 DAG 结构无法跨越从计划到真实执行的鸿沟。第三，运行完成并不自动意味着
科学结果正确；每个端点都需要明确的比较对象、分母、证据状态和限制，一些结论必须保留为“未评估”。

**第 5 段：方案概览。** ABI 用三个对应机制解决上述挑战。分析插件声明生物学身份、配置与样本
schema、DAG、工具和资源契约、输出断言、标准表及报告元数据；共享核心将这些声明编译为后端无关
的执行计划。统一的四阶段生命周期包括发现（`list-types`、可选 `query`）、准备（`plan`、`check`、
`dry-run`、运行前 `inspect`）、授权执行，以及验证（运行后 `inspect`、`validate-result`、`report`），
用于解析环境与资源、执行权限和步骤契约，并在 local、container、Nextflow、HPC 和服务适配器
间记录溯源。最后，ABI 发布主张范围明确的证据表、图、方法和限制。在配对 running example 中，
同一控制面既保留 Airway 的 donor-aware 设计，也保留 WGS 的 MLST/AMR 端点，而不抹平二者不同的
生物学语义。

**第 6 段：贡献。** 本文有四项贡献。(1) 提出 ABI：面向隐私型智能体生物信息分析的插件化、
契约编译控制层（第 2–4 节）。(2) 定义受权限门保护的执行与证据生命周期，将声明式计划连接到
运行时检查、标准输出、溯源和明确的主张边界（第 3–4 节）。(3) 提出面向本地可部署模型家族的
预注册评测，区分接口效应与信息量效应，并只报告全新且通过 preflight 的运行（第 5 节）。
(4) 在 Airway 与 ST93 MRSA 配对例子上验证跨插件执行和生物学端点恢复，并以 SCAPP plasmidome
作为旗舰 case study；其 headline precision、recall 和 F1 以通过门禁的 paper-method reconstruction
报告，但不称为 paper-exact reproduction（第 6–7 节）。

## 系统架构

解释 thick-core、thin-adapter 架构：插件 manifest、`pipeline_dag.yaml`、工具与资源契约、
编译计划、runtime lock、溯源写入器、CLI/MCP/HTTP 适配器、标准表、报告与 SciPlot 图。明确插件
负责生物学选择，共享核心负责通用执行控制。

## 评测设计

由于原始组学数据可能涉及隐私，主评测以本地部署模型为目标场景。确认性设计至少包含三个模型
家族，每族一个 small 和一个 medium 配置；族内精度/量化与服务栈保持匹配，冻结 runtime
attestation，并完成 G1/G2/G3/G4 对照。外推的统计单位是模型家族；重复运行只估计配置内变异。

## 结果与案例

- 只有全新 ABI-Bench 运行通过 clean-run preflight 后才报告；历史 pilot 分数不进入论文指标表。
- Airway 与 ST93 MRSA 作为跨插件执行与生物学端点恢复的配对 running example。
- SCAPP 作为旗舰 case study。可报告已完成执行、辅助质粒证据，以及通过门禁的 paper-method
  precision、recall 和 F1；明确该结果不是 paper-exact reproduction。

## 可复现性附录

根目录 `metrics.tsv` 是规范的主张级指标注册表。支持性的机器可读表与 FigureSpec 位于
`docs/paper_examples/`。每个数值主张都记录证据轨道、状态、适用时的分子/分母、来源和限制。
