组件与架构¶

本文说明 ABI 由哪些组件组成、一次请求如何流经系统，以及不同类型的行为分别由哪一层负责。

架构概览¶

科研人员或 AI Agent
        |
        v
CLI / JSON / MCP / HTTP / 模型工具描述
        |
        v
ABIAgentInterface
        |
        v
核心生命周期：
  发现：list-types -> query（可选）
  准备：plan -> check -> dry-run -> inspect
  执行：请求授权 -> run
  验证：inspect -> validate-result -> report
        |
        v
分析插件 + 声明式 DAG + 工具注册表
        |
        v
本地 / Conda / Docker / Nextflow / Snakemake / HPC / 云端 worker
        |
        v
执行计划 + 溯源 + 标准表格 + 报告 + 科研图形

所有传输方式都调用同一个核心接口。因此，CLI 请求和 MCP 请求使用相同的规划、权限、诊断、执行确认和结果契约。

组件地图¶

组件	职责	主要位置
入口与传输适配器	把用户或机器请求转换为 ABI 操作	`src/abi/cli.py`、`src/abi/mcp/`、`src/abi/jobs/`、`src/abi/tool_descriptors.py`
Agent 接口	稳定、与传输无关的 API 和 JSON 信封	`src/abi/agent/`
工作流核心	Schema、规划、权限、诊断、契约、溯源、表格和报告	`src/abi/`
分析插件	负责生物学选择、工作流配置、解析和结果解释	`src/abi/plugins/`
声明式工作流定义	定义 DAG 节点、工具、Schema、表格和报告元数据	`plugins/<analysis_type>/`
工具与资源层	解析可执行程序、Conda 环境、数据库、索引和模型	`src/abi/tools.py`、`src/abi/resources.py`、`environments.yaml`
运行时适配器	本地执行，或把任务转换到 Nextflow、Snakemake 和 HPC 后端	`src/abi/runtimes/`、`src/abi/exporters/`
结果与图形层	验证产物、标准化 TSV、生成报告和科研图形	`src/abi/results.py`、`src/abi/report/`、`src/abi/sciplot/`

一次请求如何执行¶

发现。 abi list-types 和 abi query 读取插件元数据，不构建或运行工作流。
解析。 ABI 合并插件、配置、样本表、运行时参数和资源覆盖项。
规划。 声明式 DAG 生成 ExecutionPlan，其中包含有序步骤、命令、输入、输出、依赖和契约。计划同时被编译为经过不变量校验、与后端无关的 CompiledPlan；两者分别持久化为 execution_plan.json 和 compiled_plan.json，违反计划不变量时规划以结构化的 invalid_config 错误失败。
检查。 ABI 以只读方式检查输入路径、可执行程序、资源和运行时假设。
试运行。 dry-run 写入计划、溯源骨架、标准表格和报告预览。
授权。 执行需要明确传入 --confirm-execution 或对应的传输字段。
执行。 运行时调用已注册工具，并强制验证步骤输出契约。
发布结果。 ABI 记录校验和、溯源、表格、摘要、报告和可选的 SciPlot 图形。

核心设计边界¶

核心层要厚¶

可复用机制属于核心层：生命周期操作、权限级别、Schema、诊断、溯源、契约执行、标准表格和报告组装。

传输层要薄¶

CLI、MCP、模型工具描述、dispatch 和 HTTP Job 只负责转换请求，不应包含工作流或生物学逻辑。

插件要干净¶

插件负责分析特有的决策：工具、参数、DAG 分支、输入规则、输出解析、生物学断言和报告解释。

Agent 调用契约，不依赖源码¶

Agent 发现有类型约束的操作并接收结构化响应，不需要导入 ABI 内部模块，也不需要为每次运行重新生成 Shell 流程。

契约与数据流¶

边界	输入	输出
用户到 ABI	分析类型、YAML 配置、TSV 样本表、运行时参数	已验证请求或结构化诊断
规划器到执行器	`ExecutionPlan` 和步骤契约	有序且已授权的工作
工具到插件	文件、目录、JSON、TSV 或日志	已解析的工作流特有数据
插件到 ABI 结果层	已发布产物和标准表格行	稳定的结果目录和报告输入
ABI 到用户或 Agent	人类文本或 JSON 信封	计划、诊断、产物、报告或恢复建议

声明式 DAG 是依赖关系和步骤输出契约的单一事实来源；environments.yaml 是工具到环境映射的单一事实来源。

部署方式¶

方式	适合场景	入口
本地 CLI	探索、开发和单机运行	`abi`
Docker	隔离插件运行环境和可重复部署	`docker/Dockerfile.*`
Nextflow 或 HPC	调度器支持和可恢复计算	`abi export-nextflow`、`abi run --engine hpc`
Snakemake	基于标记文件、绑定 Conda 环境的可恢复计算	`abi export-snakemake`、`abi run --engine snakemake`
MCP	使用 stdio 工具的交互式 Agent 平台	`abi-mcp`
HTTP Job Service	排队、异步或远程管理的任务	`abi job-service`、`abi job ...`
无头 dispatch	子进程 worker 和传输适配器	`abi dispatch`

修改代码时如何选择边界¶

变更	所属边界
新增工作流步骤或生物学断言	插件 DAG 和插件测试
新增通用验证或溯源机制	核心模块和核心测试
新增 CLI、MCP 或 HTTP 表达	调用 `ABIAgentInterface` 的传输适配器
新增或迁移工具环境	`environments.yaml` 和生成的 `envs/*.yml`
修改标准结果布局	结果核心、插件映射、兼容性测试和文档
新增图形类型	`abi.sciplot` Schema、渲染器、质检规则和图形测试

继续阅读使用 ABI了解标准操作流程；修改代码前，请先阅读开发规范。