Agent 使用指南¶

Agent 应将 ABI 用作生命周期控制层，而非直接编写生物信息学管线代码。

入门¶

安装 ABI 技能 (Claude Code)¶

abi install-skills

这会将 40 个捆绑的 SKILL.md 文件复制到 ~/.claude/skills/abi/。安装完成后，Claude Code 会自动加载这些技能并知晓如何使用 abi CLI 及其生物信息学工具。

使用 --force 覆盖已有文件，或使用 --target 自定义目标目录。

Claude Code、OpenCode 与 Codex 集成¶

仓库在 integrations/claude-code/abi/ 提供 Claude Code 插件，在 integrations/opencode/ 提供 OpenCode 配置和 Agent Skill，并在 integrations/codex/abi/ 提供 Codex 插件。三者调用同一个传输无关 ABI interface，并默认使用 MCP 的 safe profile。

加载集成前先安装带 MCP 支持的 ABI：

pip install "abi-agent[mcp]"

使用统一命令安装用户级或项目级集成：

abi agent install claude-code --scope project
abi agent install opencode --scope project
abi agent install codex --scope project
abi agent doctor codex --scope project

安装器会保留 OpenCode JSON 和 Codex TOML 中无关的配置；如果已有不同的 abi MCP 项，默认拒绝覆盖，只有显式传入 --force 才会替换。自动化场景可使用 --output-json。

各平台使用其原生安装位置：

平台	项目级 Skill	项目级 MCP 配置	用户级 Skill / 配置
Claude Code	`.claude/skills/abi/SKILL.md`	`.mcp.json`	`~/.claude/skills/abi`、`~/.claude.json`
OpenCode	`.opencode/skills/abi/SKILL.md`	`opencode.json`	`~/.config/opencode/skills/abi`、`~/.config/opencode/opencode.json`
Codex	`.agents/skills/abi/SKILL.md`	`.codex/config.toml`	`~/.agents/skills/abi`、`~/.codex/config.toml`

doctor 只读检查 abi-mcp、MCP runtime、Skill 和 MCP 配置；任一缺失时以非零状态退出。它会初始化 safe server 但不启动 stdio，因此能在 Agent 启动前发现未安装 mcp extra。安装插件后，或客户端没有自动发现新增 Skill 时，应开启新的 Agent 会话。

Claude Code 插件开发验证：

claude plugin validate integrations/claude-code/abi --strict
claude --plugin-dir integrations/claude-code/abi

Codex 插件开发时，可使用 plugin-creator 提供的校验器验证 integrations/codex/abi/。直接安装时，项目级技能位于 .agents/skills/abi，用户级技能位于 ~/.agents/skills/abi，MCP 配置写入对应范围的 .codex/config.toml。

MCP 服务器¶

abi-mcp                         # safe：发现、规划和结果工具
abi-mcp --profile discovery     # 只读发现与检查
abi-mcp --profile full          # 加入受确认门控的 abi_run

management profile 保留完整兼容表面，只用于管理，不建议普通 Agent 会话使用。

手工 MCP 配置：

{
  "mcpServers": {
    "abi": {
      "command": "abi-mcp",
      "args": ["--profile", "safe"]
    }
  }
}

Python API（用于自定义 Agent 代码）¶

import abi

# 用于系统提示注入的紧凑操作指南
print(abi.get_agent_guide())

# 列出所有已安装的分析插件
for p in abi.list_plugins_summary():
    print(f"{p['analysis_type']}: {p['name']}")

通过插件执行生物学分析¶

ABI 不会为每个插件创建独立的 MCP 函数。Agent 调用 abi_plan、abi_dry_run 等共享生命周期工具，并通过 analysis_type 参数选择插件。

1. 把生物学问题转换为分析请求¶

选择插件前，先明确：

生物学问题和预期结果；
输入数据类型和测序平台；
样本 ID、分组、比较关系或双端关系；
可用的参考基因组、注释、数据库和索引；
运行环境、计算限制和输出目录。

缺失信息会改变插件、工作流分支、参考资源或生物学解释时，应向用户确认。不得猜测参考基因组、样本分组或数据库配置。

2. 发现并选择插件¶

生物学目标	`analysis_type`
分析 16S 微生物群落	`amplicon_16s`
比较 bulk RNA-seq 表达差异	`rnaseq_expression`
分析细菌分离株基因组	`wgs_bacteria`
定量宏转录组表达	`metatranscriptomics`
分析 shotgun 宏基因组 reads	`easymetagenome`
识别并表征宏基因组病毒	`viral_viwrap`
重建并表征宏基因组质粒	`metagenomic_plasmid`

以当前安装环境为权威来源：

abi_list_types({})
abi_export_agent_context({"analysis_type": "rnaseq_expression"})
abi_query({"analysis_type": "rnaseq_expression", "what": "stages"})
abi_query({"analysis_type": "rnaseq_expression", "what": "tools"})

abi_export_agent_context 会返回插件说明、标准表格、重要产物、权限、错误码和恢复规则。构建计划前应先读取这些信息。

其中的 canonical_lifecycle 是规范的分阶段契约；safe_sequence 是将同一生命周期展开为 ABI 工具调用的兼容表示，授权动作则由 execution_requires_confirmation 表示。

3. 准备配置与样本元数据¶

Agent 生命周期工具接收文件路径，但不会编造生物学元数据。使用已经审查的配置和样本表，或在 MCP 之外初始化模板：

abi init --type rnaseq_expression --outdir my-analysis

用户或 Agent 必须替换占位路径并核对样本元数据。源数据保持只读，每次尝试使用新的结果目录。

4. 规划、检查与 dry-run¶

每次调用都使用相同的 analysis_type、配置、样本表和输出假设：

abi_plan({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "outdir": "my-analysis/results/plan"
})

abi_check({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "engine": "local",
  "check_runtime": true
})

abi_dry_run({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "outdir": "my-analysis/results/dry-run"
})

预检报告输入、工具或资源缺失时，应在执行前停止。dry-run 成功只证明规划和命令渲染有效，不能证明生物学有效性。

5. 展示执行审批摘要¶

请求用户授权前，应总结：

所选插件和生物学目的；
样本、平台、分组和比较关系；
计划阶段和关键工具；
参考资源、数据库和未解决警告；
运行后端、输出目录和预期资源需求；
即将跨越执行边界的准确操作。

不得编造运行时间或存储需求。只报告计划、配置、调度器或用户提供的估计。

6. 仅在明确授权后执行¶

默认 MCP safe profile 不会暴露 abi_run。只有需要执行时才启动 full profile：

abi-mcp --profile full

首次调用 abi_run 时传入 confirm_execution: false，保留审批边界。用户明确批准摘要中的计划后，再用完全相同的请求传入 confirm_execution: true。

abi_run({
  "analysis_type": "rnaseq_expression",
  "config_path": "my-analysis/config/rnaseq_expression.yaml",
  "sample_sheet": "my-analysis/samples.tsv",
  "outdir": "my-analysis/results/run-001",
  "engine": "local",
  "confirm_execution": true
})

授权只适用于已展示的插件、输入、配置、输出路径和运行时。任一内容发生实质变化时，都应重新规划并再次请求授权。

7. 验证并解释结果¶

abi_inspect({"result_dir": "my-analysis/results/run-001"})
abi_validate_result({"result_dir": "my-analysis/results/run-001"})
abi_report({
  "analysis_type": "rnaseq_expression",
  "result_dir": "my-analysis/results/run-001"
})

从插件声明的标准表格读取生物学数值，不要临时解析原始日志。使用溯源文件说明方法和可复现性，使用插件报告了解解释范围和局限性。

Agent 应区分三个结论：执行已经完成、结果契约已经通过、生物学验收标准已经通过。任何一个结论都不能自动证明另外两个。

安全调用序列¶

abi_list_types — 发现已安装的分析插件
abi_export_agent_context 或 abi_doctor_agent — 获取操作上下文
abi_query — 轻量级元数据查询（阶段、工具、平台、步骤 I/O）
abi_plan — 构建执行计划并检查 summary
abi_check — 预检输入、资源、可执行程序和运行时
abi_dry_run — 写入命令、溯源、表格骨架和报告预览
abi_inspect 或 abi_validate_result — 验证 dry-run 产物
展示插件、输入、资源、运行时、输出路径和警告
abi_run — 仅在用户明确批准后执行
abi_inspect、abi_validate_result 和 abi_report — 验证并解释结果

传输方式¶

CLI JSON（通用）¶

abi list-types --output-json
abi query --type metatranscriptomics --what stages --output-json
abi plan --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --outdir results/agent-plan --output-json
abi check --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --no-check-runtime --output-json
abi dry-run --type metatranscriptomics \
  --config examples/metatranscriptomics/config_demo.yaml \
  --sample-sheet examples/sample_sheet_transcriptomics.tsv \
  --outdir results/agent-dry-run --output-json
abi inspect --result-dir results/agent-dry-run --output-json
abi validate-result --result-dir results/agent-dry-run --allow-empty-tables --output-json
abi report --type metatranscriptomics --result-dir results/agent-dry-run --output-json

所有命令返回带有 success、confirmation_required 或 error 状态的 JSON 信封。

对于 abi check，传输层信封可能为 success，但预检发现缺失输入或资源时，内部 result.status 为 "fail"，CLI 也会非零退出。Agent 必须同时检查两层状态。

内置示例包含参考资源占位路径，只用于规划和 dry-run。进行生物学执行前必须配置真实参考资源。

多 LLM 工具描述符¶

ABI 从单一真相源为所有主流大模型提供者导出工具描述符。

# OpenAI 兼容提供商（Chat Completions API）
abi export-tools --type metagenomic_plasmid --format openai --provider openai
abi export-tools --type metagenomic_plasmid --format openai --provider deepseek
abi export-tools --type metagenomic_plasmid --format openai --provider zhipu   # 智谱 GLM
abi export-tools --type metagenomic_plasmid --format openai --provider kimi     # Moonshot
abi export-tools --type metagenomic_plasmid --format openai --provider qwen     # 通义千问
abi export-tools --type metagenomic_plasmid --format openai --provider minimax  # MiniMax

# Anthropic Claude（tool_use 格式）
abi export-tools --type metagenomic_plasmid --format anthropic

# Google Gemini（function_declarations 格式）
abi export-tools --type metagenomic_plasmid --format gemini

# 包含执行工具
abi export-tools --type metagenomic_plasmid --format openai --include-execution

OpenAI 工具（旧版，向后兼容）¶

abi export-openai-tools --type metagenomic_plasmid --format responses

MCP¶

abi-mcp                  # safe profile（默认）
abi-mcp --profile full   # 包含 abi_run

Python¶

from abi.agent import ABIAgentInterface

# 默认：紧凑错误信封（不含 error_type，节省 token）
agent = ABIAgentInterface()
result = agent.list_types()
plan_json = agent.plan(analysis_type="metatranscriptomics", outdir="results/")

# 调试模式：错误信封包含 error_type
agent_debug = ABIAgentInterface(verbose_errors=True)

JSON 信封合约¶

每个 ABIAgentInterface 方法返回一个 JSON 字符串，具有以下三种状态之一：

状态	含义	关键字段
`success`	操作完成	`result` 持有负载数据
`confirmation_required`	用户必须批准（仅 run）	退出码 2，以 `confirm_execution=true` 重新调用
`error`	操作失败	`error_code` + `diagnostic_hints` 用于自动恢复

错误恢复¶

遇到错误时，按以下顺序检查：

JSON 信封中的 error_code 和 diagnostic_hints — 每条 hint 携带结构化的 recovery 块（action、api_call、params）；可直接据此行动，绝不可自动重试 action 为 do_not_retry 的提示
result_dir/provenance/commands.tsv — 查找 failed 行
result_dir/provenance/resolved_inputs.tsv — 检查缺失/占位输入
result_dir/provenance/step_logs/<step_id>.stderr.log — 原始工具错误输出

不要首先解析原始工具输出。优先使用 tables/ 下的标准表。

合约与可复现性检查¶

当被问及工作流是否受约束、可验证或可复现时，检查产物而非仅依赖 dry-run：

execution_plan.json 包含预期的分析类型、样本、步骤和输出路径。
provenance/commands.tsv 没有失败或意外跳过的步骤。
provenance/resolved_inputs.tsv 没有缺失的必需输入。
provenance/checksums.json 在启用合约的真实执行后存在。
provenance/tool_versions.tsv 和 provenance/resources.json 标识所使用的可执行文件和资源。
tables/*.tsv 包含报告所使用的生物学结果行。
工作流路线和解释限制对照 docs/workflow_validation_zh.md 进行检查。

不要声称 dry-run 能证明生物学有效性。Dry-run 验证的是规划和命令渲染。科学声明需要真实工具输出、已配置的数据库、版本/资源清单以及基准验收检查。

Plan 摘要化¶

abi plan 信封现在包含 summary 字段（流水线阶段、关键工具、平台）。Agent 无需读取完整 execution_plan.json 即可理解工作流结构 — 复杂流水线 plan 输出可节省 78-95% token。

如需无需完整 plan 开销的轻量级元数据查询，使用 abi query：

# 流水线级元数据
abi query --type metagenomic_plasmid --what stages
abi query --type metagenomic_plasmid --what tools
abi query --type metagenomic_plasmid --what platforms

# 步骤级 I/O 详情
abi query --type metagenomic_plasmid --step qc_fastp --what inputs
abi query --type metagenomic_plasmid --step qc_fastp --what outputs

所有 abi query 命令均支持 --output-json 供 Agent 使用。

`run` vs `dispatch`¶

两者都执行真实工具，但调用模型不同：

方面	`run`	`dispatch`
调用方式	CLI 命令	HTTP 端点 (Job Service)
阻塞	是（同步）	立即返回（异步）
确认	`--confirm-execution` 标志	作业队列 + payload 中的 `confirm_execution`
进度	内联进度条/日志	`GET /jobs/{id}` 轮询
取消	Ctrl+C (SIGINT, 尽力而为)	`POST /jobs/{id}/cancel` (SIGTERM → SIGKILL)
适用场景	交互式 Agent 调用	长时间运行的批处理作业、远程执行

交互式会话优先使用 run。当执行时间超过 Agent 超时或在远程机器上运行时使用 dispatch。

常见故障排查¶

工具未找到 (`TOOL_NOT_FOUND`)¶

工具可执行文件不在 PATH 上。检查：

# 验证 conda 环境已激活
conda activate <env_name>

# 或列出哪些工具可用
abi check-resources --type <analysis_type>

资源缺失 (`MISSING_RESOURCE`)¶

缺少必需的数据库或参考文件：

# 查看缺失项
abi check-resources --type <analysis_type>

# 安装缺失的资源
abi setup-resources --type <analysis_type> --confirm

合约违规 (`CONTRACT_VIOLATION`)¶

工具输出与预期合约不匹配：

检查 provenance/step_logs/<step_id>.stderr.log 获取工具错误
验证输入文件存在且非空
检查工具版本是否变更 — 输出格式可能不同
如果合约过于严格，调整工具合约中的 min_size 或 assertions

Dry-run 成功但真实执行失败¶

验证 conda 环境已安装：ls envs/
检查所需数据库是否已下载：abi check-resources --type <analysis_type>
确保输入 FASTQ 文件存在且可读
检查磁盘空间和内存：某些工具需要 16GB+ RAM

权限拒绝¶

ABI 实施三级权限模型：

read_only 操作 (list_types、query、inspect) — 始终允许
planning_write 操作 (plan、dry_run、report) — 仅写入计划/溯源
execution (run) — 需要 confirm_execution=true

如果 run 返回 confirmation_required，使用 --confirm-execution 重新调用。

并行执行未加速¶

检查配置中的 config.execution.parallel 和 config.execution.workers：

execution:
  parallel: true
  workers: 8

并行执行是样本级别的。步骤较少的单样本管线不会受益。多样本管线将达到 worker 数量以内的近线性加速。

Golden Trace¶

已知良好的 Agent 调用序列存储在 golden_traces/ 中，由 tests/integration/test_golden_traces.py 回放。