# Agent 使用指南

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

## 入门

### 安装 ABI 技能 (Claude Code)

```bash
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：

```bash
pip install "abi-agent[mcp]"
```

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

```bash
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 插件开发验证：

```bash
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 服务器

```bash
abi-mcp                         # safe：发现、规划和结果工具
abi-mcp --profile discovery     # 只读发现与检查
abi-mcp --profile full          # 加入受确认门控的 abi_run
abi-mcp --transport streamable-http  # 127.0.0.1:8000/mcp 上的无状态 HTTP
```

ABI 对齐 MCP `2026-07-28` 协议。本地 Agent 集成仍默认使用 stdio。Streamable
HTTP 需要显式启用，采用无状态模式并默认仅绑定 `127.0.0.1`；对本机之外开放前，
必须配置认证和明确的主机安全策略。

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

手工 MCP 配置：

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

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

```python
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` |

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

```text
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 之外初始化模板：

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

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

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

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

```text
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：

```bash
abi-mcp --profile full
```

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

```text
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. 验证并解释结果

```text
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 应区分三个结论：执行已经完成、结果契约已经通过、生物学验收标准已经通过。任何一个结论都不能自动证明另外两个。

## 安全调用序列

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

## 传输方式

### CLI JSON（通用）

```bash
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 从单一真相源为所有主流大模型提供者导出工具描述符。

```bash
# 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 工具（旧版，向后兼容）

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

### MCP

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

### Python

```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` 用于自动恢复 |

## 错误恢复

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

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

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

## 合约与可复现性检查

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

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

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

## Plan 摘要化

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

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

```bash
# 流水线级元数据
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 上。检查：

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

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

### 资源缺失 (`MISSING_RESOURCE`)

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

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

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

### 合约违规 (`CONTRACT_VIOLATION`)

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

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

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

1. 验证 conda 环境已安装：`ls envs/`
2. 检查所需数据库是否已下载：`abi check-resources --type <analysis_type>`
3. 确保输入 FASTQ 文件存在且可读
4. 检查磁盘空间和内存：某些工具需要 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`：

```yaml
execution:
  parallel: true
  workers: 8
```

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

## Golden Trace

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