Evo2-7B Bioinformatics MCP Server

Un servidor que envuelve la Evo2-7B Forward API alojada por NVIDIA como herramientas MCP (Model Context Protocol), para que agentes como Claude Code, Cursor, Codex, etc. puedan controlar Evo2 mediante lenguaje natural:

Agent
  ↓
MCP Tool
  ↓
Evo2 MCP Server（本项目）
  ↓
NVIDIA Evo2-7B Forward API
  ↓
forward outputs → likelihood / variant scores
  ↓
Agent

POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward
Authorization: Bearer $NVIDIA_API_KEY

1. Introducción del proyecto

Proporciona 5 herramientas MCP:

Este proyecto es un Bioinformatics MCP Tool Server, no un simple envoltorio de una API HTTP:

• Valida / normaliza automáticamente la secuencia de ADN (mayúsculas, eliminación de espacios en blanco y error claro en caracteres no válidos)

• Calcula la verosimilitud según la semántica oficial (tokenizador a nivel de byte + desplazamiento causal, ver §17)

• Diseño de salida por niveles (summary / raw / save) para evitar la explosión del contexto de MCP

• Clasificación completa de errores (400/401/403/404/408/413/422/429/5xx/timeout) + reintentos/backoff

• La clave de API solo se lee de variables de entorno; nunca se codifica ni aparece en los registros

• Scripts por lotes incluidos: scripts/score_fasta.py (puntuación de FASTA por lotes + extracción de embeddings, ver §18) y scripts/analyze_run.py (análisis posteriores de clustering/clasificación/regresión, ver §19)

Related MCP server: Evo2 MCP Server

2. Introducción a la API de Evo2

Evo2 (Arc Institute / NVIDIA) es un modelo fundacional de ADN (arquitectura StripedHyena2); la versión 7B tiene 32 capas, licencia Apache-2.0 y contexto de entrenamiento de hasta 1M pb. NVIDIA ofrece un servicio NIM alojado:

• Endpoint Forward: POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward

• Cuerpo de la solicitud (OpenAPI oficial ForwardInputs):

{ "sequence": "ACGTACGT...", "output_layers": ["output_layer"] }

output_layers admite de 1 a 100 nombres de capa (por ejemplo, output_layer, decoder.layers.24.mlp.linear_fc2, decoder.layers.3.self_attention, embedding, decoder.final_norm).

• Cuerpo de la respuesta (OpenAPI oficial ForwardOutputs): {"data": "<NPZ codificado en base64>", "elapsed_ms": <int>}; las respuestas muy grandes pueden devolverse con Content-Type: application/zip (bytes NPZ sin procesar).

• output_layer = logits finales, con forma [seq_len, batch_size, 512] (512 es el tamaño de vocabulario rellenado del tokenizador a nivel de byte).

⚠️ Aviso de obsolescencia (verificado el 2026-08-24): el endpoint arc/evo2-7b alojado en build.nvidia.com está marcado como Deprecated (la página indica "This NIM Endpoint has been deprecated"). La API descrita en la documentación oficial de NIM (docs.nvidia.com/nim/bionemo/evo2/latest/) coincide exactamente con la del endpoint alojado; si el endpoint alojado no está disponible, se puede pasar a un contenedor NIM autoalojado y apuntar EVO2_MCP_BASE_URL a http://localhost:8000/biology/arc/evo2.

Hechos oficiales verificados (base de implementación, 2026-08-24)

Diferencias entre lo probado y la documentación (verificación en vivo 2026-08-24; la tarea exige documentar la interfaz real)

Al probar el endpoint alojado health.api.nvidia.com con una clave real se observó que los nombres de capa de la documentación no se aplican en el endpoint alojado:

Medidas adoptadas (implementadas y verificado en vivo):

• Se añadió la configuración EVO2_MCP_LOGITS_LAYER (por defecto auto): las herramientas de puntuación prueban primero el nombre de la documentación output_layer; si reciben 422 has no attribute (endpoint alojado), cambian automáticamente a unembed y lo cachean, sin volver a sondear. En un contenedor NIM 2.x autoalojado funciona a la primera, sin solicitudes adicionales.

• El analizador NPZ admite tanto claves simples (output_layer) como el formato <name>.output (unembed.output), con un respaldo heurístico de "última dimensión = 512".

• El mensaje de error 422 ahora indica los nombres de atributo disponibles en el endpoint alojado.

Si el seq_len devuelto no coincide con la longitud de la secuencia de entrada (por ejemplo, si el servidor añade padding/BOS), este servidor se niega a calcular la verosimilitud y devuelve estadísticas sin procesar (raw) + una explicación clara; nunca especula sobre la alineación.

3. Cómo obtener la clave de API de NVIDIA

1. Abre https://build.nvidia.com/ y en la esquina superior derecha haz clic en Get API Key (requiere iniciar sesión con una cuenta de NVIDIA).

2. Crea una clave (con el formato nvapi-xxxxxxxx...).

3. Configúrala en una variable de entorno; no la escribas en código / configuración / Git:

export NVIDIA_API_KEY="nvapi-xxxxxxxx"

También puedes copiar .env.example a .env y rellenarlo (.env ya está ignorado por .gitignore).

4. Instalación

# 推荐：pip / uv
pip install -e ".[dev]"
# 或
uv sync --extra dev

# 推荐（本项目自带）：pixi 项目本地环境
pixi install
pixi run test

Requiere Python >= 3.10 (se recomienda 3.11 o superior). Dependencias principales: mcp>=2.0, httpx>=0.27, numpy>=1.26, pydantic>=2.6, python-dotenv>=1.0. Los scripts de análisis (scripts/analyze_run.py) requieren además dependencias de desarrollo: scikit-learn, pandas, matplotlib.

5. Variables de entorno

6. Inicio por CLI

# 三种方式等价
python -m evo2_mcp
evo2-mcp
uv run evo2-mcp      # 用 uv 管理的项目环境
# pixi 环境：
pixi run evo2-mcp

El servidor se comunica con el cliente MCP mediante stdio; tras un inicio normal no produce salida (espera el apretón de manos de MCP).

7. Configuración de MCP

Claude Code (.mcp.json)

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "NVIDIA_API_KEY": "${NVIDIA_API_KEY}"
      }
    }
  }
}

Nota: si ${NVIDIA_API_KEY} se expande o no depende de la implementación del cliente. La forma más segura es escribir directamente la clave real:

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "NVIDIA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Pero no subas nunca a Git un .mcp.json con la clave real (añade ese archivo a .gitignore, o inyecta la clave mediante variables de entorno o un gestor de secretos). También puedes omitir env y dejar que el proceso del servidor lea NVIDIA_API_KEY desde el entorno o desde .env:

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json o .cursor/mcp.json del proyecto)

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": { "NVIDIA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.evo2]
command = "uv"
args = ["run", "evo2-mcp"]
env = { "NVIDIA_API_KEY" = "YOUR_API_KEY" }

NIM autoalojado

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "EVO2_MCP_BASE_URL": "http://localhost:8000/biology/arc/evo2"
      }
    }
  }
}

8. Lista de herramientas

evo2_forward(sequence, output_layers=["output_layer"], mode="summary", save_path=None)

Realiza la inferencia forward de Evo2-7B sobre una secuencia de ADN. mode:

• "summary" (por defecto): devuelve shape / dtype / min / max / mean / std para cada capa, seguro para el contexto;

• "save": guarda el tensor original como .npz (output/evo2_forward_<marca_de_tiempo>.npz) y devuelve la ruta;

• "raw": incluye el tensor completo en línea (solo si el número total de elementos ≤ EVO2_MCP_RAW_INLINE_MAX, por defecto 4096, para evitar la explosión del contexto).

Atención al nombre de capa: el endpoint alojado health.api.nvidia.com acepta nombres de atributos del modelo (para logits, usa unembed; también hay embedding_layer, norm, blocks.N.mlp). Los nombres de la documentación output_layer/decoder.layers.N.* solo se aplican a contenedores NIM 2.x autoalojados. evo2_score/evo2_variant_score/evo2_batch_score/evo2_score_fasta detectan automáticamente, sin necesidad de especificarlos manualmente; solo al llamar directamente a evo2_forward debes elegir el nombre según el endpoint real.

evo2_score(sequence, include_per_position=False)

Calcula la verosimilitud de Evo2 para la secuencia:

{
  "sequence_length": 123,
  "total_log_likelihood": -123.45,
  "mean_log_likelihood": -1.2345,
  "scored_positions": 122,
  "per_position_log_likelihood": null,
  "method_notes": "...",
  "disclaimer": "..."
}

Semántica (coincide con la implementación oficial de Arc): logits[i] predice la base en la posición i+1; tras hacer log-softmax sobre los 512 del vocabulario completo, se toma el índice de byte de la base objetivo; la posición 0 no participa en la puntuación, por lo que scored_positions = length - 1 y mean es el promedio de esos N-1 valores. per_position_log_likelihood[k] corresponde a la posición k+1 de la secuencia en base 0 (es decir, la posición k+2 en base 1). Si el seq_len devuelto por la API no se puede alinear con la secuencia, no se inventan resultados; se devuelven estadísticas raw y una explicación clara:

Likelihood calculation is not supported until the API output format is verified.

evo2_variant_score(sequence, position, ref, alt, coordinate="1-based", include_per_position=False)

{
  "position": 100,
  "ref": "A",
  "alt": "G",
  "wildtype_log_likelihood": -500.1,
  "mutant_log_likelihood": -500.5,
  "delta_log_likelihood": -0.4,
  "interpretation": "The mutant sequence is less likely than the wildtype under Evo2-7B ... (NOT a clinical pathogenicity call)"
}

Cadena de validación: rango de position → conversión de coordinate → ref debe coincidir con la base de la secuencia → ref≠alt → la posición 1 en base 1 (0 en base 0) no se puede puntuar (un LM causal no puede asignar probabilidad al primer token) → error claro.

evo2_batch_score(sequence, variants, coordinate="1-based")

{
  "sequence_length": 300,
  "wildtype_log_likelihood": -1200.0,
  "variants": [
    { "position": 100, "ref": "A", "alt": "G", "delta_log_likelihood": -0.42 },
    { "position": 200, "ref": "C", "alt": "T", "delta_log_likelihood": 0.13 }
  ]
}

• La forward de WT solo se calcula una vez y se reutiliza para todas las variantes;

• El mutante con el mismo (position, alt) solo hace forward una vez (memoización);

• La concurrencia está limitada por EVO2_MCP_MAX_CONCURRENCY (por defecto 2, respetando el límite de tasa de NVIDIA);

• El fallo de una variante no afecta a todo el lote (cada una devuelve su error por separado).

evo2_score_fasta(fasta_path=None, fasta_text=None)

>sequence_1
ACGTACGT...
>sequence_2
TTGGCCAA...

• fasta_text: FASTA en línea (disponible por defecto, con límite de tamaño/número de registros);

• fasta_path: solo se permite leer si el archivo está dentro de EVO2_MCP_ALLOWED_DIRS; en caso contrario, se rechaza explícitamente;

• Devuelve total_log_likelihood / mean_log_likelihood para cada registro; un error en un registro no afecta al resto.

9. Ejemplos de uso

{
  "sequence": "acgtACGT acgt",           // 小写 + 空白自动处理
  "output_layers": ["output_layer"],
  "mode": "summary"
}

Devuelve:

{
  "sequence_length": 12,
  "requested_output_layers": ["output_layer"],
  "returned_layers": ["output_layer"],
  "layer_stats": [
    { "name": "output_layer", "shape": [12, 1, 512], "dtype": "float32",
      "size": 6144, "min": -3.21, "max": 4.02, "mean": 0.01, "std": 0.98 }
  ],
  "api": { "elapsed_ms": 87 }
}

Cuando el agente quiera los logits completos:

{ "sequence": "ACGT...", "mode": "save" }

{
  "saved": true,
  "path": "/abs/path/output/evo2_forward_20260824_153000.npz",
  "bytes_on_disk": 24576,
  "layer_stats": [...]
}

10. Ejemplo de FASTA

{
  "fasta_text": ">geneA\nACGTACGTACGT\n>geneB\nTTGGCCAATTGG"
}

(o "fasta_path": "/data/genomes/genes.fa", con EVO2_MCP_ALLOWED_DIRS=/data/genomes configurado)

Para puntuar FASTA en grandes cantidades (por ejemplo, enhancers/promotores de un directorio completo) y extraer embeddings, usa scripts/score_fasta.py (ver §18): cada ejecución genera una carpeta de run independiente (scores.csv + embeddings.npz).

11. Ejemplo de puntuación de variantes

{
  "sequence": "ACGTACGTACGTACGTACGT",
  "position": 10,
  "ref": "A",
  "alt": "G"
}

12. Ejemplo de puntuación por lotes

{
  "sequence": "ACGTACGTACGTACGTACGT",
  "variants": [
    { "position": 10, "ref": "A", "alt": "G" },
    { "position": 12, "ref": "T", "alt": "C" },
    { "position": 14, "ref": "A", "alt": "T" }
  ]
}

Flujo de trabajo típico de un agente (corresponde a "analizar todos los SNP de la secuencia y encontrar los 20 con mayor cambio en la puntuación de Evo2"):

读取输入 → 解析 DNA / VCF → 生成 WT / mutant → evo2_batch_score
→ 按 |delta_log_likelihood| 排序 → 取前 20 → 保存 CSV → 解释结果

13. Manejo de errores

Todos los errores se devuelven como JSON estructurado a través de MCP: {"error": "Evo2APIError", "message": "..."}. En evo2_batch_score, un fallo individual devuelve {"error": ..., "status": ...}, sin interrumpir todo el lote.

14. Límite de tasa

El NIM gestionado de NVIDIA tiene límites de tasa. Estrategias de mitigación:

• EVO2_MCP_MAX_CONCURRENCY (por defecto 2) limita la concurrencia;

• 429 → exponential backoff (1s, 2s, 4s, 8s, 16s…, con tope de 30s + jitter; si hay Retry-After, se respeta primero pero con tope de 60s);

• Límite de reintentos EVO2_MCP_MAX_RETRIES (por defecto 4), no se reintenta indefinidamente;

• En el lote, el WT se calcula solo una vez y los mutantes idénticos se deduplican, reduciendo el número de solicitudes.

15. Notas de seguridad

• Clave de API: solo se lee de la variable de entorno NVIDIA_API_KEY (o .env); no hay claves codificadas en el código; los registros solo incluyen URL, longitud de secuencia y nombre de capa, no el contenido de la secuencia ni la clave; los mensajes de error solo contienen un resumen de los primeros 500 caracteres de la respuesta.

• Privacidad de secuencias: todos los registros/errores solo contienen preview (por ejemplo, ACGT...GCTA (len=12345)).

• Sandbox de rutas:

  • La lectura de FASTA solo está permitida en EVO2_MCP_ALLOWED_DIRS; si no está configurado, se rechazan todas las rutas locales;

  • save_path en mode="save" debe estar dentro de EVO2_MCP_OUTPUT_DIR;

• .gitignore ya incluye .env, *.env, output/, *.npz.

• Bases N: se rechazan por defecto con un error explícito (el modelo Evo2 no ha sido evaluado con bases ambiguas; la documentación solo garantiza que A/C/G/T son significativos). Si realmente se necesita pasar N, se inicia con EVO2_MCP_ALLOW_AMBIGUOUS=1 — es una elección explícita, no un descarte silencioso.

• No ejecutar: este servidor no realiza ninguna ejecución de shell; el Agente solo puede desencadenar solicitudes HTTP restringidas a través de FASTA/entrada de secuencias.

16. Limitaciones de la interpretación biológica

• La puntuación de Evo2 es un cambio de verosimilitud de secuencia basado en el modelo, no evidencia experimental, y mucho menos un diagnóstico de patogenicidad clínica.

• delta_log_likelihood < 0 solo puede interpretarse como "la secuencia mutante es menos probable bajo el modelo", no como "patogénica".

• Se necesita validación posterior (experimental, frecuencias poblacionales, anotaciones ClinVar, impacto en la estructura de la proteína, etc.) para hablar de patogenicidad.

• La descripción de cada Tool incluye la siguiente declaración (visible para el cliente MCP):

This is a DNA foundation model inference tool. It does not provide clinical
diagnosis. Model scores should not be interpreted as pathogenicity labels
without additional validation.

17. Base de implementación y fuentes de validación (2026-08-24)

• NVIDIA NIM for Evo 2 — Endpoints: https://docs.nvidia.com/nim/bionemo/evo2/latest/endpoints.html

• NVIDIA NIM for Evo 2 — Quickstart: https://docs.nvidia.com/nim/bionemo/evo2/latest/quickstart-guide.html

• Referencia de la API gestionada de NVIDIA (esquema OpenAPI de arc/evo2-7b-forward): https://docs.api.nvidia.com/nim/reference/arc-evo2-7b-infer

• Pruebas reales del punto final gestionado (2026-08-24, clave real): output_layer devuelve 422 StripedHyena has no attribute 'output_layer'; unembed devuelve logits (clave NPZ unembed.output, forma (1, seq, 512), float64) — por lo tanto, la herramienta de puntuación usa por defecto EVO2_MCP_LOGITS_LAYER=auto para detección automática

• Pruebas por lotes (2026-08-25, clave real, más de 3800 secuencias de enhancer/promotor de K562):

  • Cuando la secuencia es > ~100 kb, el punto final gestionado devuelve 422 (límite de canUse32BitIndexMath de PyTorch) — para lotes grandes usar --skip-longer-than 100000;

  • Se ha corregido la condición de carrera en la detección automática del nombre de capa bajo concurrencia (forward_logits usa una variable local para registrar los nombres probados) y se ha añadido una prueba de regresión;

  • Extracción de embeddings: norm/embedding_layer/blocks.N funcionan, forma (1, seq, 4096) float64 (después de mean-pool, 4096 dimensiones).

• Repositorio de Arc Institute Evo2 (scoring.py, models.py): https://github.com/ArcInstitute/evo2

• CharLevelTokenizer de vortex (implementación oficial del tokenizador de Evo2): código fuente de PyPI vtx 1.1.0 en vortex/model/tokenizer.py

• Tarjeta del modelo Evo2: https://huggingface.co/ArcInstitute/evo2_7b

Si NVIDIA ajusta la API, consulte la documentación oficial más reciente; EVO2_MCP_BASE_URL se puede cambiar en cualquier momento.

18. Puntuación por lotes y extracción de embeddings (scripts/score_fasta.py)

Las herramientas MCP son adecuadas para llamadas interactivas del Agente; para puntuación FASTA a gran escala se usa el script complementario scripts/score_fasta.py (la API real se ha validado con más de 3800 secuencias de enhancer/promotor de K562).

Cada ejecución crea automáticamente una carpeta independiente con marca de tiempo:

output/run_20260825_104403/
├── scores.csv            # 每序列一行：id, header, length, total/mean LL, ...
│                         #   + embedding_key（与 embeddings.npz 的 record_ids 对齐）
└── embeddings.npz        # embeddings: (n, 4096) float32 mean-pooled 矩阵
                          # record_ids: 与矩阵行一一对应的键（来源__序列id）

# 小样本（指定 id）
.pixi/envs/dev/bin/python scripts/score_fasta.py \
  --fasta /path/cis/enhancers.fa /path/cis/promoters.fa \
  --ids K562_TE_629,K562_MPT_6842 --allow-ambiguous

# 全量（跳过 >100kb —— 托管端对该长度返回 422；保留原始 embedding）
.pixi/envs/dev/bin/python scripts/score_fasta.py \
  --fasta /path/cis/enhancers.fa /path/cis/promoters.fa \
         /path/trans/enhancers.fa /path/trans/promoters.fa \
  --skip-longer-than 100000 --allow-ambiguous \
  --embedding-layer norm --keep-raw-embeddings

Parámetros clave:

Diseño de eficiencia: cada secuencia envía una sola solicitud (output_layers=["unembed","norm"], logits y embeddings se obtienen juntos); el nombre de la capa de logits se detecta solo una vez durante toda la ejecución; la concurrencia se limita con un semáforo.

19. Asociación de embeddings y análisis posterior (scripts/analyze_run.py)

embeddings.npz es la representación de secuencias con mean-pool (un vector de 4096 dimensiones por secuencia), adecuado para clustering, clasificación y regresión directos. Carga y asociación:

import csv, numpy as np

run = "output/run_20260825_104403"
rows = list(csv.DictReader(open(f"{run}/scores.csv")))
d = np.load(f"{run}/embeddings.npz", allow_pickle=True)
X = d["embeddings"]                        # (n, 4096) float32
ids = [str(x) for x in d["record_ids"]]    # 与 X 行一一对应
key_to_row = {r["embedding_key"]: r for r in rows if r.get("embedding_key")}
scores = [key_to_row[k] for k in ids]      # scores[i] ↔ X[i]

Ejecutar el análisis completo con un solo comando (clustering KMeans, clasificación enhancer-vs-promotor, regresión embedding→likelihood, gráfico PCA):

.pixi/envs/dev/bin/python scripts/analyze_run.py output/run_20260825_104403 --k 3

Salida analysis_<run>.npz (X combinado + keys) y analysis_<run>.png. Puntos clave del análisis:

• Antes de calcular similitud/clustering con vectores de 4096 dimensiones, normalizar a norma unitaria (el script ya lo hace);

• Con muestras pequeñas, la clasificación/regresión se omite automáticamente (umbral de protección ≥6 secuencias); solo después de ejecutar las 3806 secuencias completas estos análisis tienen significado estadístico;

• Clave cis_enhancers__xxx → categoría enhancers, región cis; trans_* de manera similar (parse_source puede cambiar la dimensión de etiqueta para clasificación cis-vs-trans).

Desarrollo y pruebas

pixi install          # 或 pip install -e ".[dev]"
pixi run test         # 运行 pytest（全部 mock，不调用真实 API）

Pruebas fuera de línea 91 passed / 4 skipped (skip = controlado por live). Cubren: validación de secuencias, normalización de mayúsculas/minúsculas y espacios, caracteres ilegales, falta de clave de API, construcción de solicitudes forward, 401/408/429/5xx/timeout, detección automática del nombre de capa (incluida la regresión de condición de carrera), validación de variantes, corrección matemática de puntuación de variantes/lotes (recalculada de forma independiente según la semántica de Arc), decodificación NPZ (JSON base64 / zip / tensor JSON antiguo / clave <layer>.output), sandbox FASTA, integración de sesión MCP, funciones puras de scripts (pooling/nombres de claves), etc.

Pruebas de humo con API real (requieren clave real, omitidas por defecto). La clave se lee automáticamente de .env (Settings.from_env() ya la carga):

EVO2_MCP_RUN_LIVE=1 .pixi/envs/dev/bin/python -m pytest tests/test_live_api.py -v -s

Las pruebas live realizan solicitudes reales al punto final de NVIDIA, verificando: detección automática de la capa de logits (unembed), análisis NPZ real ((1, seq, 512) float64), evo2_score consistente con el recálculo manual a partir de los logits brutos, puntuación de variantes.

Estructura del proyecto

.
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/evo2_mcp/
│   ├── __main__.py      # python -m evo2_mcp 入口
│   ├── config.py        # 环境变量配置
│   ├── sequence.py      # DNA 校验/归一化
│   ├── api_client.py    # HTTP 客户端（retry/backoff/错误分类/响应解码 + layer 自动探测）
│   ├── forward_output.py# NPZ 解码 + likelihood 计算 + embedding 提取
│   ├── fasta.py         # FASTA 解析 + 读取沙箱
│   ├── tools.py         # 5 个 Tool 的实现
│   └── server.py        # MCP server（stdio）
├── scripts/
│   ├── score_fasta.py   # 批量 FASTA 评分 + embedding 提取（每次运行独立 run 文件夹）
│   └── analyze_run.py   # 下游分析：加载/关联 → 聚类/分类/回归 + PCA 图
├── tests/               # pytest（全 mock，91 用例）+ 可选 live test
└── output/              # mode="save" 的 .npz 输出 + run_*/ 运行结果（git 忽略）