Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Controles del harness y evaluación verificada

Estado: Activo

Alcance: estado actual

Última revisión: 2026-09-14

Responsable: entorno de ejecución de ax-code

Para el esfuerzo específico del modelo, los interruptores de thinking y la reproducción del razonamiento, consulta controles actuales de razonamiento del modelo.

Controles opcionales de contexto y herramientas

Activa cada experimento de forma independiente en tu configuración de AX Code:

{
  "experimental": {
    "context_recovery": true,
    "mcp_tool_discovery": true,
    "tail_reminders": true,
    "read_only_recipes": true
  }
}

Las cuatro opciones están desactivadas de forma predeterminada. Mide el éxito de la tarea y el tiempo transcurrido con tu modelo antes de adoptarlas juntas. Conservan los permisos de herramientas y los ajustes de aislamiento existentes. Consulta diagnósticos de rendimiento.

context_recovery expone context_recover y añade punteros de código fuente a los resúmenes de compactación exitosos. La herramienta acepta una palabra clave, un ID de mensaje, un ID de parte opcional y un límite de resultados. Solo lee la sesión actual, incluido el historial previo a la compactación, y excluye el material revertido, el razonamiento oculto y el texto ignorado o sintético. Devuelve los ID originales de mensaje y parte y extractos acotados. La búsqueda examina como máximo 100 partes por página y los primeros 16.000 caracteres de cada parte; before continúa hacia partes más antiguas. Una coincidencia ausente no prueba que todo el historial carezca de ese texto. Las bifurcaciones usan su historial copiado y ID nuevos. Las asignaciones de credenciales se redactan de los extractos.

mcp_tool_discovery mantiene disponibles las herramientas integradas e introduce tool_search para las herramientas MCP conectadas. Una búsqueda devuelve hasta cinco esquemas coincidentes y pone esas herramientas a disposición en la siguiente solicitud al modelo. No las ejecuta. Las selecciones se limitan a la sesión, se acotan a 32 herramientas y se intersecan con la admisión actual en cada solicitud. Los esquemas grandes pueden omitirse del resultado de la búsqueda y cargarse en la siguiente solicitud. Si se deniega tool_search, el catálogo MCP admitido ordinario sigue disponible. Una herramienta existente en conflicto llamada tool_search produce un error.

tail_reminders mueve solo los recordatorios dinámicos de turno generados por AX Code al final de la solicitud al proveedor. Los mensajes de usuario almacenados, el razonamiento del asistente, el historial de herramientas y las instrucciones estáticas permanecen sin cambios. Esto puede cambiar el comportamiento del modelo y el uso de la caché; no establece por sí solo una mejora de velocidad.

read_only_recipes expone read_recipe. Ejecuta hasta ocho llamadas dependientes de read, glob o grep a través del despachador normal de herramientas. Cada hija tiene sus propias comprobaciones de permiso, hooks, cancelación y evidencia de sesión. Una receta no puede evaluar código, ejecutar comandos de shell, escribir archivos, llamar a herramientas MCP ni anidar otra receta.

{
  "steps": [
    { "id": "files", "tool": "glob", "parameters": { "pattern": "src/**/*.ts" } },
    {
      "id": "source",
      "tool": "read",
      "parameters": { "filePath": { "$ref": { "step": "files", "path": ["paths", 0] } } }
    }
  ],
  "select": [{ "step": "source", "path": ["text"] }]
}

Los resultados canónicos de glob contienen paths y truncated; los resultados de grep contienen matches con path, line y text; los resultados de read contienen kind, text renderizado y truncated. Selecciona un resultado anterior por su paso y la ruta de propiedad propia. Las selecciones de array admiten un filtro contains literal y limit. Comprueba el estado devuelto y el truncamiento. La receta tiene un plazo de cancelación de 60 segundos, un presupuesto de argumentos de 32 KB, un presupuesto intermedio de 192 KB y una salida final acotada. La cancelación espera a que la herramienta propia se asiente. Instrucciones o medios nuevos del repositorio pausan la ejecución y conservan la salida hija normal para que el modelo los vea antes de continuar. Las selecciones exitosas sustituyen las salidas intermedias solo en la solicitud al modelo; los registros hijos originales permanecen en el historial. Los padres interrumpidos conservan la salida hija.

Corregir una generación en curso

GET /session/{sessionID}/steering devuelve el UUID de la generación activa y los recibos recientes. Incluye el parámetro de consulta directory existente al seleccionar un proyecto a través del servidor HTTP.

Envía POST /session/{sessionID}/steering con:

{
  "expectedGeneration": "00000000-0000-4000-8000-000000000001",
  "clientID": "correction_1",
  "text": "Preserve the existing public function signature."
}

Usa el UUID de GET, no el UUID de ejemplo. accepted significa que la corrección está pendiente. applied significa que se escribió como mensaje de usuario en un límite de bucle e incluye su ID de mensaje; no garantiza la finalización del proveedor. rejected significa que no se aplicó. Los hooks de ciclo de vida pueden vetar la admisión. Una corrección aceptada prolonga una generación que estaba a punto de completarse en una iteración más, así que una corrección enviada en la línea de meta se aplica en lugar de rechazarse; la cancelación y los errores siguen rechazando las correcciones pendientes, y una generación antigua no puede admitir texto en su sucesora. Los reintentos idénticos devuelven el mismo recibo retenido; un contenido distinto bajo un ID de cliente existente devuelve HTTP 409. El gesto de envío inmediato ctrl+s de la TUI usa este endpoint.

Llamadas a herramientas en paralelo en un paso

Cuando el modelo emite varias llamadas a herramientas en un mensaje del asistente, el entorno de ejecución las ejecuta de forma concurrente a través de una compuerta de lector y escritor limitada a la sesión. Las herramientas de solo lectura comparten el carril y se solapan; las ediciones de archivos, bash, bash_input, las ediciones de notebooks, ops_apply, las herramientas MCP y cualquier batch que contenga una hija no segura para la concurrencia toman el carril exclusivo y se ejecutan solas en orden de llegada. Una llamada abortada mientras espera nunca se ejecuta. El lote conserva su propia barrera de orden para las llamadas que despacha, y las sesiones hijas tienen su propia compuerta.

Los recibos son locales al proceso, con como máximo 256 por sesión y 32 solicitudes pendientes. Los recibos terminales y las entradas de sesión inactiva pueden desalojarse. Tras un reinicio, obtén la generación nueva y reconcilia los mensajes guardados; esta API no promete una búsqueda durable de recibos entre reinicios. El SDK generado expone session.steering y session.steer.

Dirigir un seguimiento guardado hacia el turno en curso

POST /task-queue/{taskID}/steer admite el texto de un seguimiento en cola en la generación en curso de la sesión en su siguiente límite de paso — el mismo punto de entrega que POST /session/{sessionID}/steering — y cancela la fila de la cola en la misma solicitud, registrando steeredInto (el UUID de la generación) y steeredAt en la carga de la fila para auditoría. Los seguimientos de solo texto de hasta 16.000 caracteres se pueden dirigir; el texto dirigido aplica el agente, el modelo y las herramientas del turno en curso. Los adjuntos, los tipos que no son seguimiento, las filas asentadas y el texto sobredimensionado se rechazan con HTTP 400, y una fila que cambia a otro estado a mitad de la solicitud devuelve HTTP 409.

La respuesta lleva el elemento más reciente de la cola y un recibo que puede ser nulo. Cuando no hay una generación activa, la fila se deja intacta y la respuesta informa generation_not_active con un recibo nulo; los llamadores pueden entonces recurrir a POST /task-queue/{taskID}/send-now, que solo mueve la fila al frente de la cola y sigue esperando a que termine el turno. Una fila dirigida no se puede deshacer, pero permanece visible como cancelled en el historial /queue con sus campos de auditoría.

En la TUI, el atajo input_submit_steer (predeterminado ctrl+s) dirige el borrador escrito cuando existe uno; con un compositor vacío sobre una sesión ocupada, en cambio promueve el prefijo dirigible de la cola guardada en orden FIFO, deteniéndose en la primera fila no dirigible para que los seguimientos posteriores nunca se adelanten. La sección Seguimientos de la barra lateral y el diálogo /queue ofrecen la misma acción de dirigir ahora por fila, y una pista junto a los seguimientos en cola muestra la tecla asignada. El SDK generado expone taskQueue.steer.

Proponer una habilidad a partir de trabajo verificado

Las candidatas a habilidad son registros explícitos en el almacenamiento local existente de AX Code. No entran en el descubrimiento de habilidades hasta que las promueves, y nunca disparan una llamada automática al modelo ni una reescritura de instrucciones.

Crea un archivo JSON de propuesta con name, description, applicability, procedure y evidence que contenga sessionID, messageID y partID. La evidencia debe identificar un resultado verify_project original y exitoso con sobres de prueba o de comprobación de tipos ejecutados contra la revisión limpia actual de Git. Una frase de éxito o una salida arbitraria del shell no bastan. La validación debe citar la verificación exitosa de otra sesión en la misma revisión.

ax-code skill candidate propose --proposal proposal.json
ax-code skill candidate show verified-procedure
ax-code skill candidate validate verified-procedure --proposal independent-evidence.json
ax-code skill candidate promote verified-procedure
ax-code skill candidate retire verified-procedure

Mantén el JSON de entrada fuera del worktree o en un directorio local ignorado para que la comprobación de revisión limpia siga siendo significativa. La promoción crea .ax-code/skill/{name}/SKILL.md sin sobrescribir una habilidad existente. La evidencia de origen se vuelve a comprobar antes de la promoción. Los directorios enlazados simbólicamente se rechazan. La retirada elimina solo el archivo propio sin cambios de la candidata; las ediciones manuales provocan un conflicto. Reinicia una instancia existente del entorno de ejecución para refrescar su descubrimiento de habilidades en caché. Las comprobaciones que aprueban establecen evidencia para esas comprobaciones; revisa la aplicabilidad del procedimiento antes de la promoción.

Capturar un experimento emparejado

Desde un checkout del código fuente, usa:

pnpm --dir packages/ax-code exec tsx script/harness-eval.ts run /path/to/manifest.json > /path/to/runs.ndjson
pnpm --dir packages/ax-code exec tsx script/harness-eval.ts compare /path/to/runs.ndjson baseline candidate

El manifiesto de operador de confianza contiene un provider/model explícito, runtimeRevision, un argv de CLI command opcional, repetitions, timeoutMs, exactamente dos arms con nombre y tasks. Cada brazo tiene features opcional (las marcas experimentales anteriores) y toolProfile. Cada tarea aporta id, prompt, files en línea (path/content) y un oracle. El oráculo es JavaScript de confianza ejecutado por Node después de que sale el proceso de programación; process.argv[1] identifica el fixture temporal. Su código permanece fuera del espacio de trabajo del agente y nunca procede de la respuesta del modelo.

Cada intento obtiene un fixture de Git nuevo. El oráculo debe fallar con salida 1 en el fixture inicial. El ejecutor usa una invocación fija de la CLI headless, alterna el orden de los brazos entre repeticiones, aplica un tiempo de espera y vuelve a ejecutar el oráculo después de un intento completado. elapsedMs incluye el proceso de programación y la verificación posterior a la ejecución; verificationMs identifica esta última por separado. La preparación del fixture y la comprobación inicial que falla quedan excluidas. El flujo registra cada intento completado, fallido, agotado o cancelado a medida que termina. Los prompts en bruto, la salida de subprocesos y las credenciales no se emiten en los registros de evaluación. Una cohorte interrumpida permanece incompleta y no puede producir una comparación emparejada.

La comparación rechaza duplicados y pares de tarea, modelo, cohorte o repetición ausentes o no coincidentes. Los intentos fallidos y no verificados permanecen en los denominadores de la tasa de éxito. Las medianas de latencia y las razones emparejadas se condicionan de forma explícita al éxito verificado. El P95 exige 20 observaciones exitosas dentro de una celda de tarea, modelo, cohorte y brazo; los agregados de celdas mixtas lo omiten. La cohorte hashea el manifiesto, pero la revisión del entorno de ejecución y las condiciones externas de proveedor, configuración y caché siguen exigiendo control del operador. Una ejecución pequeña de humo no puede establecer una superioridad general de velocidad ni justificar cambiar los valores predeterminados.

Diagnósticos de selección de capacidad y de recuperación

Las solicitudes autónomas pueden incluir un paquete de contexto de agente largo cuando el modelo tiene al menos 64.000 tokens de contexto, soporte de razonamiento y soporte de herramientas. Para los modelos sin una entrada de registro, los tres deben declararse en los metadatos resueltos del modelo. El paquete suplementario tiene un tope de estimación de caracteres de 2.048 tokens; no es la ventana de conversación. Las declaraciones negativas explícitas y las restricciones registradas impiden la admisión. Esta optimización del texto del prompt no establece compatibilidad de caché ni de pensamiento preservado, ni cambia los plazos automáticos de Super-Long ni el ritmo. Esos conservan sus reglas existentes de cualificación y de anulación.

Dos fallos consecutivos de herramientas estructuradas después del último mensaje de usuario (contados antes de los recordatorios sintéticos de cola) solicitan un razonamiento más profundo en la siguiente llamada al modelo cuando existe una variante de esfuerzo utilizable. Un resultado exitoso de herramienta reinicia el recuento. El esfuerzo explícito del usuario y las opciones de razonamiento configuradas conservan la precedencia. Esto cambia la selección de esfuerzo, no los límites de reintento ni los permisos de herramientas.

Los eventos de reproducción locales de llm.request incluyen capabilityResolution: protocolo, ventana de contexto, si se seleccionó un paquete de contexto o el modo Super-Long, fallos consecutivos de herramientas y la selección de razonamiento o un motivo no aplicado. boundary: "policy-selection" describe la decisión de AX Code; los plugins y los SDK de proveedor aún pueden alterar la solicitud final. Los valores explícitos de esfuerzo de GPT-6 se conservan; la API exige low o superior en lugar de none o minimal. El evento conserva hashes de la solicitud en lugar de cuerpos de prompt o de credenciales. Una variante de esfuerzo ausente no implica que el thinking predeterminado del proveedor esté desactivado.

La captura emparejada del harness lee los eventos JSON step_finish y tool_use de la CLI para tokens de entrada, salida, razonamiento y lectura de caché, llamadas a herramientas completadas y errores de herramientas. Los ID de parte duplicados se cuentan una vez. metricsStatus es observed, partial o unavailable; los flujos truncados o mal formados y los intentos interrumpidos retienen los totales. Las comparaciones informan, para cada métrica, los recuentos de ejecuciones observadas y ausentes y la mediana, incluidos los intentos fallidos donde existen observaciones. Los valores ausentes permanecen ausentes. Estos contadores describen eventos emitidos por el entorno de ejecución, no la facturación del proveedor, el uso de sesiones hijas ni las herramientas internas nativas de la CLI. Un flujo observado completo sin eventos terminales de herramienta informa cero llamadas a herramientas. La verificación del oráculo sigue siendo la fuente del éxito de la tarea; el uso por sí solo no establece una recuperación exitosa ni una mejor calidad.