开发指南¶

ABI 以核心发行版 abi-agent 加每个官方分析插件各一个发行版 abi-agent-plugin-<id> 发布（WP11B：核心 wheel 不含插件）。本文主要说明代码放在哪里、各层如何分工。具体的开发和检查顺序见 development_workflow.md。

源代码树¶

src/abi/
  agent/              ABIAgentInterface、JSON 信封、Agent 上下文导出
  agent_integrations.py  Claude Code、OpenCode 与 Codex 集成安装和诊断
  report/             write_full_report、write_plugin_report、write_methods、
                      citations、limitations、html — 通用报告系统
  workflow/           ResourceManifest、工作流验证、figure_specs 加载
  plugin_registry.py  核心所有的插件发现/选择层（WP11B 步骤 1）——
                      仅元数据发现、选定加载、数据根解析
  plugin_validation.py  插件结构校验（不依赖插件实现）
  plugins/            内置分析插件——每个都是自包含包，声明数据同址
                      （abi-plugin.yaml、DAG、工具注册表、limitations）；
                      不进入核心 wheel，作为 abi-agent-plugin-<id> 发行版发布
    metagenomic_plasmid/   自包含插件包（支持库在 lib/ 中，64 工具，90 节点 DAG）
    easymetagenome/        猎枪宏基因组适配器（10 工具，25 节点 DAG）
    viral_viwrap/          托管外部 CLI 适配器（1 工具，7 节点 DAG）
    rnaseq_expression/     批量 RNA-seq（5 工具，5 节点 DAG）
    wgs_bacteria/          细菌 WGS（5 工具）
    amplicon_16s/          16S 微生物组（10 工具）
    metatranscriptomics/   宏转录组（3 工具）
    wgs_bacannot/          托管外部 Bacannot 工作流（WP8/11A）
  dag_planner.py      UniversalDAG — 从 pipeline_dag.yaml 声明式生成执行计划
  tsv_mapping.py      声明式 TSV 列映射器 — YAML 驱动的输出解析，3 种源类型
  _shared.py          共享工具：_read_tsv、_display_command、_plan_dict、_common_overrides
  provenance.py       RunLogger、PipelineProgressRecorder、TSV 溯源写入器
  tools.py            ToolRegistry、ToolSkill、GenericCommandSkill、SafeFormatDict、RunResult
  schemas.py          规范类型：SampleInput、ExecutionPlan、PlanStep、SampleContext
  executor.py         GenericABIExecutor — 步骤迭代、工具调用、合约执行、溯源。
                      支持样本级并行执行（ThreadPoolExecutor），
                      通过 config.execution.parallel + config.execution.workers 配置。
  dag.py              DAG 推断引擎 — L1（文献）/ L2（路径）/ L3（验证）
  contracts/          WorkflowSpec、步骤合约执行、校验和链式追踪、断言评估
  permissions.py      read_only / planning_write / execution 级别
  diagnostics.py      错误分类 + DiagnosticHint + classify_exception
  interfaces.py       ABIPlugin、ABIDryRunPlugin、ABIInitializablePlugin 协议
  json_utils.py       带 ABIJSONError 封装的 JSON 文件/负载加载
  timeouts.py         超时解析：parse_timeout_seconds、timeout_from_env_or_value
  resources.py        只读资源检查与就绪报告：check_resources、setup_resources
                      （仅报告/计划/mock——下载与安装属于外部系统）
  tables.py           StandardTableManager
  tool_descriptors.py 统一工具描述符单点真相（3 格式家族、7+ LLM 提供商）
  jobs/               HTTP Job Service（服务端、客户端，force-kill 支持）
  runtimes/           local、Nextflow、Snakemake、HPC 运行时
  exporters/          Nextflow DSL2 与 Snakemake 导出器
  mcp/                可选 MCP stdio 服务器（通过 ``abi-mcp`` 暴露）
  skills/             Agent 技能文件 → 通过 ``abi install-skills`` 安装
  cli.py              Typer CLI（abi、abi-mcp 入口点）

质粒引擎位于插件包内（abi.plugins.metagenomic_plasmid.lib）；已退役的 abi.autoplasm 兼容垫片命名空间在 WP2 中删除，不得重新引入。内部代码应从插件包导入引擎，从 ABI 核心模块导入共享基础设施。

公开 SDK¶

模块	用途
`abi.interfaces`	`ABIPlugin`、`ABIDryRunPlugin`、`ABIInitializablePlugin` 协议类
`abi.schemas`	`SampleInput`、`SampleContext`、`PlanStep`、`ExecutionPlan`
`abi.tools`	`ToolRegistry`、`ToolSkill`、`GenericCommandSkill`、`RunResult`
`abi.provenance`	`RunLogger`、`PipelineProgressRecorder`、TSV 溯源写入器
`abi.contracts.step_contract`	`ContractViolationError`、`validate_output_contract`、`evaluate_assertions`、校验和链式追踪
`abi.contracts`	`WorkflowSpec`、`WorkflowStepSpec`、`load_workflow_spec` — L1/L2/L3 工作流验证
`abi.dag`	`infer_dag`、`ABIDAG`、`StepBinding` — DAG 推断，支持文献 + 路径 + 验证三层模型
`abi.dag_planner`	`UniversalDAG`、`build_plan_from_dag`、`PathTemplateContext` — 声明式计划生成，所有 7 个插件共用
`abi.tsv_mapping`	`TSVMapper`、`generate_rows` — YAML 驱动 TSV/JSON/日志解析，3 种源类型
`abi.errors`	`ABIError`、`ConfigError`、`SampleSheetError`、`ToolError`
`abi.diagnostics`	错误分类 + `DiagnosticHint` + `classify_exception`
`abi.json_utils`	带 `ABIJSONError` 的 JSON 文件/负载加载
`abi.timeouts`	`parse_timeout_seconds`、`timeout_from_env_or_value`
`abi.tool_descriptors`	`ABI_AGENT_TOOLS`、`TOOL_ALIASES`、`export_openai_compatible`、`export_anthropic`、`export_gemini`、`PROVIDER_PROFILES`
`abi.testing`	`assert_plugin_contract`

本地设置¶

pip install -e ".[dev]"

常用检查：

ruff check src/ tests/
ruff format --check src/ tests/
mypy src/abi/ --ignore-missing-imports
pytest tests/ -v --tb=short

mypy 有意限定在 src/abi/ 范围内；捆绑管线首先由运行时测试和 ruff 覆盖，更严格的类型检查留待后续加固。

Agent 集成开发¶

以 integrations/<platform>/abi/ 作为各平台原生资产的单一事实来源。 abi agent install 将这些资产复制到项目或用户配置中，abi agent doctor 只读校验已安装的技能、MCP 配置、命令可用性和 safe server 初始化，不修改文件。

修改集成时：

除非平台有已记录的约束，保持 Claude Code、OpenCode 和 Codex 行为一致。
对三个平台分别在临时项目目录运行 abi agent install <platform> --scope project 以及对应的 abi agent doctor。
已安装客户端提供原生校验器时应运行它；Claude Code 当前使用 claude plugin validate。若 Codex 版本没有本地 plugin validate 子命令，则依靠 manifest 与资产回归测试验证。
运行 python -m build，使用 [mcp] extra 安装 wheel，并在干净 wheel 环境中重复 install/doctor；仅源码树成功不能证明资产或 MCP runtime 已正确打包。
保持 .claude-plugin/plugin.json 和 .codex-plugin/plugin.json 的版本等于 project.version；scripts/check_release_identity.py 会强制检查。

integrations/ 同时属于包和 Docker 构建输入，必须进入 sdist、wheel 和每个 Docker /app 上下文。该目录变化时，建议在容器发布前手动运行 Docker workflow 验证，但不会自动触发镜像构建。

运行时合约执行¶

通用执行器强制执行嵌入在每个 PlanStep.params["_contract"] 中的步骤级合约。DAG 驱动的规划器从 pipeline_dag.yaml 复制此块，因此 DAG 是输出和运行时断言的唯一真相来源。

执行时的合约处理按以下顺序进行：

根据 provenance/checksums.json 验证上游输入校验和。
运行外部工具。
当规划路径为抽象路径时，从 output_dir 解析实际输出文件。
验证输出合约并记录输出校验和。
根据解析后的输出评估断言。

输出验证支持文件/目录存在性、min_size、extensions、目录 contains、目录/文件 min_files、FASTA min_contigs、JSON required_keys 以及点分 JSON schema 约束。

执行器有两个有意的设计细节，应予以保留：

output_dir 本身不会被预创建。某些组装器和工作流工具在其输出目录已存在时会失败。执行器仅创建其父目录和任何不相关的文件输出父目录。
实际输出解析是确定性的且能感知双端测序。如果工具写入 S1_R1.clean.fastq.gz 和 S1_R2.clean.fastq.gz，而计划中包含 S1.fastp.clean_read1 等抽象路径，合约检查将使用实际的 R1/R2 文件。

回归测试覆盖位于 tests/unit/test_executor.py 和 tests/unit/test_step_contract.py 中。

测试数量和覆盖率会频繁变化；当前结果以最新 CI 为准。持续门禁与本地命令见测试指南。

运行时资产¶

小型源资产被跟踪：

config/
envs/ — 由 environments.yaml 通过 scripts/emit_env_yamls.py 生成
skills/（位于 src/abi/skills/ — 随包捆绑，通过 abi install-skills 安装）
src/abi/plugins/<id>/ — 插件同址数据（DAG、工具注册表、limitations）；随 abi-agent-plugin-<id> 发行版发布
integrations/ — Claude Code、OpenCode 和 Codex 的平台原生集成包
examples/
scripts/

大型或生成的运行时状态被忽略：

.mamba/
resources/
results/
logs/
Nextflow 与 Snakemake 工作目录

工具执行通过 abi.config.resolved_mamba_root() 解析环境，优先级如下：

CLI/API 显式根目录
ABI_MAMBA_ROOT 和 MAMBA_ROOT_PREFIX
AUTOPLASM_MAMBA_ROOT（旧版兼容）
已填充的仓库兼容根目录
全局 Micromamba/Mamba/Conda 元数据
Linux 用户数据根目录

每个工具的 env_name 在运行时从 environments.yaml 解析。当前清单声明 21 个 Conda 环境和 99 个工具→环境映射；代码和文档应从清单派生这些清单，不要复制一份独立维护。

并行执行¶

GenericABIExecutor 通过 ThreadPoolExecutor 支持样本级并行执行，通过设置 config.execution.parallel: true 和 config.execution.workers 启用：

execution:
  parallel: true
  workers: 8
  batch_size: 8  # 可选的严格样本批次屏障

使用 local 引擎时，样本间并行运行；每个样本内的步骤保持 DAG 拓扑顺序串行执行。设置 batch_size 后，本地执行器会等待该批全部样本完成分析阶段，再执行标记为批次清理的步骤；清理完成后才启动下一批。不设置时，仍按 workers 持续调度样本。其他执行引擎目前不实现该批次屏障。通过 threading.Lock 保证 StandardTableManager、PipelineProgressRecorder 和 RunLogger 的线程安全。

Agent 接口¶

ABIAgentInterface 是与传输无关的边界。保持 CLI JSON（--output-json）、MCP（abi-mcp）、OpenAI 描述符（abi export-openai-tools）、技能（abi install-skills）、abi dispatch 和 Job Service 行为与之对齐。

插件通过发现机制和共享的 analysis_type 参数加入该接口，不新增传输特有的生命周期工具。Agent 上下文、安全、结果和测试契约详见插件开发指南。

执行必须保持门控：abi run、abi_run 和 Job Service 执行提交应返回 confirmation_required，除非显式传入确认。

面向 Agent 的命令¶

命令	用途
`abi list-types --output-json`	发现已安装插件
`abi query --type <plugin> --what stages`	轻量级流水线元数据查询（~50ms）
`abi export-agent-context --type <plugin>`	机器可读的操作上下文
`abi doctor-agent --type <plugin>`	人类可读的操作指南
`abi check-resources --type <plugin>`	检查资源/数据库可用性
`abi setup-resources --type <plugin> --confirm`	资源设置（需要确认）
`abi install-skills`	将 SKILL.md 文件安装到 `~/.claude/skills/abi/`
`abi agent install <platform>`	安装 Claude Code、OpenCode 或 Codex 集成
`abi agent doctor <platform>`	只读校验已安装的 Agent 集成
`abi export-openai-tools --type <plugin>`	OpenAI 函数调用描述符
`abi-mcp`	启动 MCP stdio 服务器

Python Agent API¶

import abi
abi.get_agent_guide()          # 返回紧凑操作指南（str）
abi.list_plugins_summary()     # 返回 list[dict]，包含 (analysis_type, name, description)

MCP 兼容性¶

ABI 通过 MCP Python SDK 2.x 对齐 MCP 2026-07-28 协议。适配器使用 MCPServer，返回结构化 JSON envelope，提供标准工具行为注解，并支持 stdio 以及可选的无状态 Streamable HTTP。