Arnés de evaluación

El arnés de evaluación (zeroclaw eval run, crate crates/zeroclaw-eval) ejecuta casos de evaluación del agente (fixtures de trazas en JSON) a través del bucle real del agente y califica cada ejecución según expectativas declarativas. Así es como ZeroClaw protege el comportamiento del bucle del agente (despacho de herramientas, orden de los turnos múltiples, formato de las respuestas, negativas) frente a regresiones.

Es distinto de [agent.eval], el evaluador de calidad de respuestas dentro del bucle. El harness se configura en [eval] y se invoca como subcomando de la CLI.

Modos

Taxonomía de la suite

Las suites son directorios de fixtures *.json (consulta evals/README.md):

• evals/regression/: debe mantenerse al 100 % de aprobación. Se controla en CI mediante crates/zeroclaw-eval/tests/regression_suite.rs; un fallo bloquea la fusión. Este es el valor predeterminado de [eval].suite_dir.
• evals/capability/ (previsto): tareas difíciles con una tasa de aprobación baja; se monitorizan a lo largo del tiempo y nunca se usan como requisito bloqueante.
• evals/live/ (previsto): casos ejecutados contra un proveedor real; nunca se ejecutan en CI de forma predeterminada.

Ejecutando

# Reproducir la suite de regresión predeterminada:
zeroclaw eval run

# Apunta a una suite específica y emite JSON legible por máquina:
zeroclaw eval run --suite evals/regression --format json

--suite anula [eval].suite_dir; --mode anula [eval].mode. La carga de suites no es recursiva: solo los hijos directos *.json del directorio de la suite son casos.

Contrato de códigos de salida

zeroclaw eval run sale con 0 si y solo si todos los casos pasaron, y con 1 en caso contrario (cualquier verificación fallida o error de ejecución). Esta es la puerta de CI: el código de salida del proceso es la señal. La misma decisión se expone como la función pura SuiteReport::exit_code() para que pueda probarse en su límite real.

Formato de mayúsculas

Cada fixture es un LlmTrace: un model_name, una lista de turns de conversación (cada uno con un user_input y steps de respuesta programada) y expects declarativos. Un caso es positivo (un comportamiento que debe ocurrir) o negativo (un comportamiento que NO debe ocurrir, p. ej. tools_not_used, response_not_contains, max_tool_calls: 0). Consulta evals/README.md para las reglas de redacción, incluida la prueba de los dos expertos y el requisito de privacidad según el cual los fixtures usan únicamente identidades de marcador de posición.

Las expectativas que evalúan el límite de despacho en lugar del texto programado (tool_arguments_contain, tool_results_contain y exact_tool_calls) están documentadas en crates/zeroclaw-eval/README.md. Úsalas siempre que un caso afirme que un valor pasó por una herramienta y regresó sin cambios, o que ocurrió un número específico de llamadas a herramientas. Las expectativas sobre la respuesta final por sí solas no pueden demostrar ninguna de las dos cosas, porque el proveedor de reproducción programa esa respuesta. La lista de llamadas registradas es el hecho canónico del despacho. Los nombres de las herramientas y el éxito agregado se derivan de ella en el momento de la calificación, por lo que una evidencia más rica del límite no crea un segundo resumen de llamadas a herramientas modificable de forma independiente.

La carga de fixtures falla en modo cerrado, porque una puerta obligatoria no debe certificar un caso que no puede fallar. LlmTrace::from_file() rechaza un fixture que no declara turnos de conversación (la reproducción ejecutaría al agente cero veces y evaluaría sus expectativas contra una ejecución vacía), uno cuyo bloque de expectativas se omite o está vacío, uno que contiene una entrada de longitud cero en una familia de expectativas basada en cadenas (response_contains, response_not_contains, response_matches, tools_used, tools_not_used), y uno que incluye una clave desconocida de nivel superior o de expectativa. Las familias de límites en el punto de despacho siguen el mismo principio de fallo cerrado: un tool o needle vacío, un min_tool_calls: 0 vacuo y límites de conteo que se contradicen entre sí se rechazan al cargar. Cada rechazo indica el fixture y el campo infractores.

La admisión no puede detectar una forma restante de vacuidad: una aserción que ya se cumple con una ejecución que no produce nada, como un max_tool_calls: 0 aislado. La prueba de suite con compuerta evalúa cada fixture versionado contra una ejecución vacía y exige al menos una verificación fallida, por lo que un caso que no certifica ningún comportamiento no puede formar parte de la compuerta obligatoria.