From f40dcff9b6c167d8a8ba52a935551d65fee79067 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 13 Apr 2026 05:25:09 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/concepts/qa-e2e-automation.md | 101 ++-- docs/es/help/testing.md | 772 ++++++++++++++------------ 2 files changed, 476 insertions(+), 397 deletions(-) diff --git a/docs/es/concepts/qa-e2e-automation.md b/docs/es/concepts/qa-e2e-automation.md index 5c30e1425..1a87b18c9 100644 --- a/docs/es/concepts/qa-e2e-automation.md +++ b/docs/es/concepts/qa-e2e-automation.md @@ -1,43 +1,43 @@ --- read_when: - - Ampliación de qa-lab o qa-channel + - Extender qa-lab o qa-channel - Agregar escenarios de QA respaldados por el repositorio - Crear automatización de QA de mayor realismo en torno al panel de Gateway -summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con seed y reportes de protocolo +summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con semillas e informes de protocolo title: Automatización E2E de QA x-i18n: - generated_at: "2026-04-12T23:28:19Z" + generated_at: "2026-04-13T05:22:00Z" model: gpt-5.4 provider: openai - source_hash: b9fe27dc049823d5e3eb7ae1eac6aad21ed9e917425611fb1dbcb28ab9210d5e + source_hash: a4a4f5c765163565c95c2a071f201775fd9d8d60cad4ff25d71e4710559c1570 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automatización E2E de QA -La pila privada de QA está pensada para ejercitar OpenClaw de una manera más realista y con forma de canal que la que puede cubrir una sola prueba unitaria. +La pila privada de QA está pensada para ejercitar OpenClaw de una manera más realista y con forma de canal que lo que puede lograr una sola prueba unitaria. Piezas actuales: -- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo, reacción, edición y eliminación. -- `extensions/qa-lab`: UI de depuración y bus de QA para observar la transcripción, inyectar mensajes entrantes y exportar un reporte en Markdown. -- `qa/`: recursos seed respaldados por el repositorio para la tarea inicial y los escenarios base de QA. +- `extensions/qa-channel`: canal de mensajes sintético con superficies de DM, canal, hilo, reacción, edición y eliminación. +- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción, inyectar mensajes entrantes y exportar un informe en Markdown. +- `qa/`: recursos semilla respaldados por el repositorio para la tarea inicial y los escenarios base de QA. El flujo actual del operador de QA es un sitio de QA de dos paneles: -- Izquierda: panel de Gateway (UI de Control) con el agente. -- Derecha: QA Lab, que muestra la transcripción tipo Slack y el plan del escenario. +- Izquierda: panel de Gateway (Control UI) con el agente. +- Derecha: QA Lab, que muestra la transcripción con estilo similar a Slack y el plan del escenario. -Ejecuta esto con: +Ejecútalo con: ```bash pnpm qa:lab:up ``` -Eso compila el sitio de QA, inicia la ruta de Gateway respaldada por Docker y expone la página de QA Lab donde un operador o un bucle de automatización puede darle al agente una misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o qué siguió bloqueado. +Eso compila el sitio de QA, inicia el entorno de Gateway respaldado por Docker y expone la página de QA Lab donde un operador o un bucle de automatización puede darle al agente una misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o qué siguió bloqueado. -Para iterar más rápido en la UI de QA Lab sin reconstruir la imagen de Docker cada vez, inicia la pila con un bundle de QA Lab montado con bind mount: +Para una iteración más rápida de la interfaz de QA Lab sin reconstruir la imagen de Docker cada vez, inicia la pila con un paquete de QA Lab montado por bind: ```bash pnpm openclaw qa docker-build-image @@ -46,66 +46,68 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta con bind `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash de recursos de QA Lab. +`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta por bind `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese paquete cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash de recursos de QA Lab. -Para una ruta de smoke de Matrix con transporte real, ejecuta: +Para un entorno smoke de Matrix con transporte real, ejecuta: ```bash pnpm openclaw qa matrix ``` -Esa ruta aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales de driver, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro de un proceso hijo de Gateway de QA. La ruta de transporte en vivo mantiene la configuración hija acotada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración hija. +Ese entorno aprovisiona un homeserver de Tuwunel desechable en Docker, registra usuarios temporales de controlador, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro de un proceso hijo de Gateway de QA. El entorno de transporte en vivo mantiene la configuración hija limitada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración hija. -Para una ruta de smoke de Telegram con transporte real, ejecuta: +Para un entorno smoke de Telegram con transporte real, ejecuta: ```bash pnpm openclaw qa telegram ``` -Esa ruta apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación entre bots funciona mejor cuando ambos bots tienen habilitado el modo Bot-to-Bot Communication Mode en `@BotFather`. +Ese entorno apunta a un único grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación bot a bot funciona mejor cuando ambos bots tienen habilitado el modo de comunicación bot a bot en `@BotFather`. -Las rutas de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada una invente su propia forma de lista de escenarios. +Los entornos de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada uno invente su propia forma de lista de escenarios: `qa-channel` sigue siendo la suite amplia de comportamiento sintético del producto y no forma parte de la matriz de cobertura de transporte en vivo. -| Ruta | Canary | Restricción por mención | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | -| -------- | ------ | ----------------------- | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Entorno | Canary | Restricción por menciones | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | +| ------- | ------ | ------------------------- | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Esto mantiene `qa-channel` como la suite amplia de comportamiento del producto, mientras que Matrix, Telegram y futuros transportes en vivo comparten una lista explícita de comprobaciones de contrato de transporte. +Esto mantiene `qa-channel` como la suite amplia de comportamiento del producto, mientras que Matrix, Telegram y futuros transportes en vivo comparten una lista explícita de verificación del contrato de transporte. -Para una ruta de VM Linux desechable sin incorporar Docker en la ruta de QA, ejecuta: +Para un entorno de VM Linux desechable sin incorporar Docker a la ruta de QA, ejecuta: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Esto inicia un guest nuevo de Multipass, instala dependencias, compila OpenClaw dentro del guest, ejecuta `qa suite` y luego copia el reporte y el resumen normales de QA de vuelta a `.artifacts/qa-e2e/...` en el host. +Esto inicia un guest nuevo de Multipass, instala dependencias, compila OpenClaw dentro del guest, ejecuta `qa suite` y luego copia el informe y el resumen normales de QA de vuelta a `.artifacts/qa-e2e/...` en el host. Reutiliza el mismo comportamiento de selección de escenarios que `qa suite` en el host. -Las ejecuciones de suite en host y Multipass ejecutan en paralelo varios escenarios seleccionados con workers de Gateway aislados por defecto, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para ejecución en serie. -Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el guest: claves de proveedor basadas en env, la ruta de configuración del proveedor en vivo de QA y `CODEX_HOME` cuando está presente. Mantén `--output-dir` bajo la raíz del repositorio para que el guest pueda escribir de vuelta a través del workspace montado. +Las ejecuciones de la suite en host y en Multipass ejecutan en paralelo varios escenarios seleccionados con workers de Gateway aislados de forma predeterminada, hasta 64 workers o el número de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para una ejecución en serie. +Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el guest: claves de proveedor basadas en variables de entorno, la ruta de configuración del proveedor en vivo de QA y `CODEX_HOME` cuando esté presente. Mantén `--output-dir` bajo la raíz del repositorio para que el guest pueda escribir de vuelta a través del workspace montado. -## Seeds respaldados por el repositorio +## Semillas respaldadas por el repositorio -Los recursos seed viven en `qa/`: +Los recursos semilla viven en `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Estos están intencionalmente en git para que el plan de QA sea visible tanto para humanos como para el agente. +Están intencionalmente en git para que el plan de QA sea visible tanto para humanos como para el agente. `qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es la fuente de verdad para una ejecución de prueba y debe definir: - metadatos del escenario -- referencias a documentación y código +- referencias de documentación y código - requisitos opcionales de Plugin - parche opcional de configuración de Gateway - el `qa-flow` ejecutable -La lista base debe seguir siendo lo bastante amplia para cubrir: +La superficie de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica y transversal. Por ejemplo, los escenarios en Markdown pueden combinar helpers del lado del transporte con helpers del lado del navegador que controlan la Control UI incrustada a través de la interfaz `browser.request` de Gateway sin agregar un ejecutor de casos especiales. -- chat por MD y en canal +La lista base debe seguir siendo lo bastante amplia como para cubrir: + +- chat por DM y canal - comportamiento de hilos - ciclo de vida de acciones de mensajes - callbacks de Cron @@ -117,30 +119,30 @@ La lista base debe seguir siendo lo bastante amplia para cubrir: ## Adaptadores de transporte -`qa-lab` gestiona una interfaz genérica de transporte para escenarios de QA en Markdown. -`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo del diseño es más amplio: +`qa-lab` posee una interfaz de transporte genérica para escenarios de QA en Markdown. +`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo de diseño es más amplio: los futuros canales reales o sintéticos deben conectarse al mismo ejecutor de suites en lugar de agregar un ejecutor de QA específico para cada transporte. A nivel de arquitectura, la división es: -- `qa-lab` gestiona la ejecución genérica de escenarios, la concurrencia de workers, la escritura de artefactos y los reportes. -- el adaptador de transporte gestiona la configuración de Gateway, la disponibilidad, la observación de entrada y salida, las acciones de transporte y el estado de transporte normalizado. -- los archivos Markdown de escenarios en `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de runtime reutilizable que los ejecuta. +- `qa-lab` posee la ejecución genérica de escenarios, la concurrencia de workers, la escritura de artefactos y los informes. +- el adaptador de transporte posee la configuración de Gateway, la preparación, la observación de entrada y salida, las acciones de transporte y el estado de transporte normalizado. +- los archivos de escenario en Markdown bajo `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de ejecución reutilizable que los ejecuta. -La guía de adopción orientada a maintainers para nuevos adaptadores de canal está en +La guía de adopción orientada a mantenedores para nuevos adaptadores de canal está en [Testing](/es/help/testing#adding-a-channel-to-qa). -## Reportes +## Informes -`qa-lab` exporta un reporte de protocolo en Markdown a partir de la línea de tiempo observada del bus. -El reporte debe responder: +`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea de tiempo observada del bus. +El informe debe responder: - Qué funcionó - Qué falló - Qué siguió bloqueado - Qué escenarios de seguimiento vale la pena agregar -Para comprobaciones de carácter y estilo, ejecuta el mismo escenario en múltiples refs de modelos en vivo y escribe un reporte evaluado en Markdown: +Para comprobaciones de carácter y estilo, ejecuta el mismo escenario en múltiples refs de modelos en vivo y escribe un informe evaluado en Markdown: ```bash pnpm openclaw qa character-eval \ @@ -159,11 +161,12 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter deben establecer la persona mediante `SOUL.md` y luego ejecutar turnos de usuario normales como chat, ayuda del workspace y pequeñas tareas de archivos. No se le debe decir al modelo candidato que está siendo evaluado. El comando conserva cada transcripción completa, registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo fast con razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor. -Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo cada transcripción y estado de ejecución, pero las refs candidatas se sustituyen por etiquetas neutras como `candidate-01`; el reporte vuelve a mapear las clasificaciones a las refs reales después del análisis. -Las ejecuciones de candidatos usan por defecto razonamiento `high`, con `xhigh` para los modelos de OpenAI que lo admiten. Sustituye un candidato específico en línea con `--model provider/model,thinking=`. `--thinking ` sigue estableciendo un valor de reserva global, y la forma anterior `--model-thinking ` se mantiene por compatibilidad. -Las refs candidatas de OpenAI usan por defecto el modo fast para que se utilice procesamiento prioritario cuando el proveedor lo admite. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando un solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras forzar el modo fast para todos los modelos candidatos. Las duraciones de candidatos y jueces se registran en el reporte para el análisis de benchmarks, pero los prompts de los jueces indican explícitamente que no deben clasificar por velocidad. -Las ejecuciones de candidatos y jueces usan por defecto concurrencia 16. Reduce `--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del Gateway local hagan que una ejecución sea demasiado ruidosa. +El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter deben establecer la personalidad mediante `SOUL.md`, y luego ejecutar turnos de usuario normales como chat, ayuda del workspace y pequeñas tareas sobre archivos. No se le debe decir al modelo candidato que está siendo evaluado. El comando conserva cada transcripción completa, registra estadísticas básicas de la ejecución y luego pide a los modelos jueces en modo rápido con razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor. +Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo cada transcripción y el estado de la ejecución, pero las refs candidatas se reemplazan por etiquetas neutras como `candidate-01`; el informe vuelve a mapear las clasificaciones a las refs reales después del análisis. +Las ejecuciones candidatas usan de forma predeterminada razonamiento `high`, con `xhigh` para modelos de OpenAI que lo admiten. Sustituye un candidato específico en línea con +`--model provider/model,thinking=`. `--thinking ` sigue estableciendo un valor de respaldo global, y la forma anterior `--model-thinking ` se mantiene por compatibilidad. +Las refs candidatas de OpenAI usan de forma predeterminada el modo rápido para aprovechar el procesamiento prioritario cuando el proveedor lo admite. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando un candidato o juez individual necesite una sustitución. Pasa `--fast` solo cuando quieras forzar el modo rápido para todos los modelos candidatos. Las duraciones de candidatos y jueces se registran en el informe para análisis comparativo, pero los prompts del juez indican explícitamente que no deben clasificar por velocidad. +Tanto las ejecuciones de modelos candidatos como las de modelos jueces usan por defecto concurrencia 16. Reduce `--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del Gateway local hagan que una ejecución sea demasiado ruidosa. Cuando no se pasa ningún `--model` candidato, la evaluación de carácter usa por defecto `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, diff --git a/docs/es/help/testing.md b/docs/es/help/testing.md index 022f7d1b5..d87795de3 100644 --- a/docs/es/help/testing.md +++ b/docs/es/help/testing.md @@ -2,52 +2,52 @@ read_when: - Ejecutar pruebas localmente o en CI - Agregar regresiones para errores de modelo/proveedor - - Depurar el comportamiento del gateway + agente + - Depurar el comportamiento de Gateway + agente summary: 'Kit de pruebas: suites unitarias/e2e/live, ejecutores de Docker y qué cubre cada prueba' title: Pruebas x-i18n: - generated_at: "2026-04-12T23:28:34Z" + generated_at: "2026-04-13T05:22:00Z" model: gpt-5.4 provider: openai - source_hash: a66ea672c386094ab4a8035a082c8a85d508a14301ad44b628d2a10d9cec3a52 + source_hash: 3db91b4bc36f626cd014958ec66b08b9cecd9faaa20a5746cd3a49ad4b0b1c38 source_path: help/testing.md workflow: 15 --- # Pruebas -OpenClaw tiene tres suites de Vitest (unit/integration, e2e, live) y un pequeño conjunto de ejecutores de Docker. +OpenClaw tiene tres suites de Vitest (unitarias/integración, e2e, live) y un pequeño conjunto de ejecutores de Docker. Este documento es una guía de “cómo probamos”: -- Qué cubre cada suite (y qué deliberadamente _no_ cubre) -- Qué comandos ejecutar para flujos comunes (local, antes de hacer push, depuración) -- Cómo las pruebas live descubren credenciales y seleccionan modelos/proveedores +- Qué cubre cada suite (y qué _no_ cubre deliberadamente) +- Qué comandos ejecutar para flujos de trabajo comunes (local, antes de hacer push, depuración) +- Cómo las pruebas live detectan credenciales y seleccionan modelos/proveedores - Cómo agregar regresiones para problemas reales de modelos/proveedores ## Inicio rápido La mayoría de los días: -- Compuerta completa (esperada antes de hacer push): `pnpm build && pnpm check && pnpm test` +- Puerta completa (esperada antes de hacer push): `pnpm build && pnpm check && pnpm test` - Ejecución local más rápida de la suite completa en una máquina con buenos recursos: `pnpm test:max` -- Bucle directo de vigilancia de Vitest: `pnpm test:watch` +- Bucle directo de Vitest en modo watch: `pnpm test:watch` - El direccionamiento directo a archivos ahora también enruta rutas de extensiones/canales: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Prefiere primero ejecuciones dirigidas cuando estés iterando sobre un solo fallo. -- Sitio de QA respaldado por Docker: `pnpm qa:lab:up` -- Línea de QA respaldada por VM de Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Prefiere primero ejecuciones dirigidas cuando estés iterando sobre un único fallo. +- Sitio de QA con respaldo de Docker: `pnpm qa:lab:up` +- Carril de QA con VM de Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Cuando toques pruebas o quieras más confianza: -- Compuerta de cobertura: `pnpm test:coverage` -- Suite e2e: `pnpm test:e2e` +- Puerta de cobertura: `pnpm test:coverage` +- Suite E2E: `pnpm test:e2e` Al depurar proveedores/modelos reales (requiere credenciales reales): -- Suite live (modelos + sondeos de herramientas/imágenes del gateway): `pnpm test:live` -- Dirigir un solo archivo live en silencio: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (sondeos de modelos + herramientas/imágenes de Gateway): `pnpm test:live` +- Ejecutar silenciosamente un único archivo live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de allowlist descritas abajo. +Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de lista permitida descritas más abajo. ## Ejecutores específicos de QA @@ -55,49 +55,125 @@ Estos comandos se ubican junto a las suites de prueba principales cuando necesit - `pnpm openclaw qa suite` - Ejecuta escenarios de QA respaldados por el repositorio directamente en el host. - - Ejecuta varios escenarios seleccionados en paralelo de forma predeterminada con workers de gateway aislados, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para el carril serial anterior. + - Ejecuta varios escenarios seleccionados en paralelo de forma predeterminada con workers de Gateway aislados, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para el carril serial anterior. - `pnpm openclaw qa suite --runner multipass` - Ejecuta la misma suite de QA dentro de una VM Linux desechable de Multipass. - Mantiene el mismo comportamiento de selección de escenarios que `qa suite` en el host. - Reutiliza las mismas banderas de selección de proveedor/modelo que `qa suite`. - - Las ejecuciones live reenvían las entradas de autenticación de QA compatibles que son prácticas para el invitado: - claves de proveedor basadas en env, la ruta de configuración del proveedor live de QA y `CODEX_HOME` cuando está presente. + - Las ejecuciones live reenvían las entradas de autenticación de QA admitidas que son prácticas para el invitado: + claves de proveedor basadas en entorno, la ruta de configuración del proveedor live de QA y `CODEX_HOME` cuando está presente. - Los directorios de salida deben permanecer bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado. - - Escribe el informe + resumen de QA normales, además de los registros de Multipass, en - `.artifacts/qa-e2e/...`. + - Escribe el informe + resumen normales de QA, además de los registros de Multipass, en `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia el sitio de QA respaldado por Docker para trabajo de QA estilo operador. + - Inicia el sitio de QA con respaldo de Docker para trabajo de QA estilo operador. - `pnpm openclaw qa matrix` - - Ejecuta la línea de QA live de Matrix contra un homeserver Tuwunel desechable respaldado por Docker. - - Aprovisiona tres usuarios temporales de Matrix (`driver`, `sut`, `observer`) más una sala privada, y luego inicia un proceso hijo de gateway de QA con el plugin real de Matrix como transporte SUT. - - Usa de forma predeterminada la imagen estable fijada de Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Anúlala con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` cuando necesites probar una imagen diferente. + - Ejecuta el carril de QA live de Matrix contra un homeserver Tuwunel desechable con respaldo de Docker. + - Aprovisiona tres usuarios temporales de Matrix (`driver`, `sut`, `observer`) además de una sala privada, y luego inicia un proceso hijo de Gateway de QA con el plugin real de Matrix como transporte SUT. + - Usa la imagen estable fijada de Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1` de forma predeterminada. Sustitúyela con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` cuando necesites probar una imagen distinta. + - Matrix actualmente solo admite `--credential-source env` porque el carril aprovisiona usuarios desechables localmente. - Escribe un informe de QA de Matrix, un resumen y un artefacto de eventos observados en `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Ejecuta la línea de QA live de Telegram contra un grupo privado real usando los tokens de bot del driver y del SUT desde env. + - Ejecuta el carril de QA live de Telegram contra un grupo privado real usando los tokens del bot driver y del bot SUT desde el entorno. - Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. El id del grupo debe ser el id numérico del chat de Telegram. + - Admite `--credential-source convex` para credenciales compartidas agrupadas. Usa el modo env de forma predeterminada, o configura `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases agrupados. - Requiere dos bots distintos en el mismo grupo privado, con el bot SUT exponiendo un nombre de usuario de Telegram. - - Para una observación estable entre bots, habilita el modo de comunicación bot a bot en `@BotFather` para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots del grupo. + - Para una observación estable entre bots, habilita el modo de comunicación bot a bot en `@BotFather` para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots en el grupo. - Escribe un informe de QA de Telegram, un resumen y un artefacto de mensajes observados en `.artifacts/qa-e2e/...`. -Las líneas de transporte live comparten un contrato estándar para que los nuevos transportes no se desvíen: +Los carriles de transporte live comparten un contrato estándar para que los transportes nuevos no diverjan: -`qa-channel` sigue siendo la amplia suite de QA sintética y no forma parte de la matriz de cobertura de transporte live. +`qa-channel` sigue siendo la suite amplia de QA sintética y no forma parte de la matriz de cobertura de transporte live. -| Línea | Canary | Mention gating | Allowlist block | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando help | -| -------- | ------ | -------------- | --------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Carril | Canary | Restricción por menciones | Bloqueo por lista permitida | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | +| -------- | ------ | ------------------------- | --------------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | + +### Credenciales compartidas de Telegram mediante Convex (v1) + +Cuando `--credential-source convex` (o `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para +`openclaw qa telegram`, QA lab adquiere un lease exclusivo de un grupo respaldado por Convex, envía Heartbeat +a ese lease mientras el carril está en ejecución y libera el lease al apagarse. + +Plantilla de referencia del proyecto Convex: + +- `qa/convex-credential-broker/` + +Variables de entorno requeridas: + +- `OPENCLAW_QA_CONVEX_SITE_URL` (por ejemplo `https://your-deployment.convex.site`) +- Un secreto para el rol seleccionado: + - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` + - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` +- Selección del rol de credencial: + - CLI: `--credential-role maintainer|ci` + - Valor predeterminado por entorno: `OPENCLAW_QA_CREDENTIAL_ROLE` (predeterminado: `maintainer`) + +Variables de entorno opcionales: + +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (predeterminado `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (predeterminado `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (predeterminado `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predeterminado `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predeterminado `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreo opcional) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs de Convex `http://` de loopback local solo para desarrollo local. + +`OPENCLAW_QA_CONVEX_SITE_URL` debe usar `https://` en funcionamiento normal. + +Los comandos administrativos para maintainers (agregar/quitar/listar grupos) requieren +específicamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. + +Ayudantes de CLI para maintainers: + +```bash +pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json +pnpm openclaw qa credentials list --kind telegram +pnpm openclaw qa credentials remove --credential-id +``` + +Usa `--json` para una salida legible por máquinas en scripts y utilidades de CI. + +Contrato predeterminado del endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): + +- `POST /acquire` + - Solicitud: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - Éxito: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` + - Agotado/reintentable: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` +- `POST /heartbeat` + - Solicitud: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - Éxito: `{ status: "ok" }` (o `2xx` vacío) +- `POST /release` + - Solicitud: `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - Éxito: `{ status: "ok" }` (o `2xx` vacío) +- `POST /admin/add` (solo secreto de maintainer) + - Solicitud: `{ kind, actorId, payload, note?, status? }` + - Éxito: `{ status: "ok", credential }` +- `POST /admin/remove` (solo secreto de maintainer) + - Solicitud: `{ credentialId, actorId }` + - Éxito: `{ status: "ok", changed, credential }` + - Protección de lease activo: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (solo secreto de maintainer) + - Solicitud: `{ kind?, status?, includePayload?, limit? }` + - Éxito: `{ status: "ok", credentials, count }` + +Forma de la carga útil para el tipo Telegram: + +- `{ groupId: string, driverToken: string, sutToken: string }` +- `groupId` debe ser una cadena con el id numérico del chat de Telegram. +- `admin/add` valida esta forma para `kind: "telegram"` y rechaza cargas útiles malformadas. ### Agregar un canal a QA -Agregar un canal al sistema de QA en Markdown requiere exactamente dos cosas: +Agregar un canal al sistema de QA en markdown requiere exactamente dos cosas: 1. Un adaptador de transporte para el canal. -2. Un paquete de escenarios que ejerza el contrato del canal. +2. Un paquete de escenarios que ejercite el contrato del canal. -No agregues un ejecutor de QA específico del canal cuando el ejecutor compartido `qa-lab` pueda hacerse cargo del flujo. +No agregues un ejecutor de QA específico del canal cuando el ejecutor compartido `qa-lab` pueda +gestionar el flujo. -`qa-lab` es responsable de la mecánica compartida: +`qa-lab` gestiona la mecánica compartida: - inicio y desmontaje de la suite - concurrencia de workers @@ -106,29 +182,29 @@ No agregues un ejecutor de QA específico del canal cuando el ejecutor compartid - ejecución de escenarios - alias de compatibilidad para escenarios antiguos de `qa-channel` -El adaptador del canal es responsable del contrato de transporte: +El adaptador del canal gestiona el contrato del transporte: -- cómo se configura el gateway para ese transporte +- cómo se configura Gateway para ese transporte - cómo se verifica la preparación -- cómo se inyectan los eventos entrantes +- cómo se inyectan eventos entrantes - cómo se observan los mensajes salientes -- cómo se exponen las transcripciones y el estado normalizado del transporte +- cómo se exponen las transcripciones y el estado de transporte normalizado - cómo se ejecutan las acciones respaldadas por el transporte -- cómo se maneja el restablecimiento o la limpieza específicos del transporte +- cómo se gestiona el restablecimiento o la limpieza específicos del transporte -El umbral mínimo de adopción para un nuevo canal es: +El nivel mínimo de adopción para un canal nuevo es: -1. Implementar el adaptador de transporte sobre la interfaz compartida de `qa-lab`. +1. Implementar el adaptador de transporte en la interfaz compartida de `qa-lab`. 2. Registrar el adaptador en el registro de transportes. 3. Mantener la mecánica específica del transporte dentro del adaptador o del arnés del canal. -4. Crear o adaptar escenarios en Markdown bajo `qa/scenarios/`. -5. Usar los ayudantes genéricos de escenarios para los nuevos escenarios. -6. Mantener funcionando los alias de compatibilidad existentes, a menos que el repositorio esté realizando una migración intencional. +4. Crear o adaptar escenarios markdown bajo `qa/scenarios/`. +5. Usar los ayudantes genéricos de escenarios para los escenarios nuevos. +6. Mantener funcionando los alias de compatibilidad existentes, salvo que el repositorio esté realizando una migración intencional. La regla de decisión es estricta: -- Si el comportamiento puede expresarse una sola vez en `qa-lab`, colócalo en `qa-lab`. -- Si el comportamiento depende de un transporte de canal, mantenlo en ese adaptador o arnés del plugin. +- Si el comportamiento puede expresarse una vez en `qa-lab`, colócalo en `qa-lab`. +- Si el comportamiento depende de un solo transporte de canal, mantenlo en ese adaptador o arnés del plugin. - Si un escenario necesita una nueva capacidad que más de un canal puede usar, agrega un ayudante genérico en lugar de una rama específica de canal en `suite.ts`. - Si un comportamiento solo tiene sentido para un transporte, mantén el escenario específico del transporte y hazlo explícito en el contrato del escenario. @@ -155,67 +231,67 @@ Los alias de compatibilidad siguen disponibles para escenarios existentes, inclu - `formatConversationTranscript` - `resetBus` -El trabajo en canales nuevos debe usar los nombres genéricos de ayudantes. -Los alias de compatibilidad existen para evitar una migración de golpe, no como modelo para +El trabajo de canales nuevos debe usar los nombres de ayudantes genéricos. +Los alias de compatibilidad existen para evitar una migración abrupta, no como modelo para la creación de escenarios nuevos. -## Suites de prueba (qué se ejecuta dónde) +## Suites de prueba (qué se ejecuta y dónde) Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo): -### Unit / integration +### Unitarias / integración (predeterminada) - Comando: `pnpm test` -- Configuración: diez ejecuciones secuenciales de fragmentos (`vitest.full-*.config.ts`) sobre los proyectos de Vitest acotados existentes -- Archivos: inventarios core/unit bajo `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas node de `ui` incluidas en allowlist cubiertas por `vitest.unit.config.ts` +- Configuración: diez ejecuciones secuenciales de shards (`vitest.full-*.config.ts`) sobre los proyectos de Vitest con alcance existente +- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas node permitidas de `ui` cubiertas por `vitest.unit.config.ts` - Alcance: - Pruebas unitarias puras - - Pruebas de integración en proceso (autenticación del gateway, enrutamiento, herramientas, análisis, configuración) + - Pruebas de integración en proceso (autenticación de Gateway, routing, herramientas, parsing, config) - Regresiones deterministas para errores conocidos - Expectativas: - Se ejecuta en CI - No requiere claves reales - Debe ser rápida y estable - Nota sobre proyectos: - - `pnpm test` sin objetivo ahora ejecuta once configuraciones de fragmentos más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso gigante del proyecto raíz nativo. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. - - `pnpm test --watch` sigue usando el grafo de proyectos nativo del root `vitest.config.ts`, porque un bucle de observación con múltiples fragmentos no es práctico. - - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` enrutan primero los objetivos explícitos de archivo/directorio a través de carriles acotados, así que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo de inicio completo del proyecto raíz. - - `pnpm test:changed` expande las rutas modificadas de git en esos mismos carriles acotados cuando el diff solo toca archivos enrutable de código fuente/prueba; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz. - - Las pruebas unitarias ligeras en importación de agentes, comandos, plugins, ayudantes de auto-reply, `plugin-sdk` y áreas similares de utilidades puras se enrutan por el carril `unit-fast`, que omite `test/setup-openclaw-runtime.ts`; los archivos con estado o pesados en runtime permanecen en los carriles existentes. - - Los archivos fuente de ayudantes seleccionados de `plugin-sdk` y `commands` también asignan las ejecuciones en modo changed a pruebas hermanas explícitas en esos carriles ligeros, de modo que las ediciones de ayudantes evitan volver a ejecutar la suite pesada completa para ese directorio. - - `auto-reply` ahora tiene tres grupos dedicados: ayudantes core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de respuesta fuera de las pruebas baratas de estado/fragmentos/tokens. + - `pnpm test` sin objetivo ahora ejecuta once configuraciones de shards más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso gigante del proyecto raíz nativo. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. + - `pnpm test --watch` sigue usando el grafo de proyectos nativo del root `vitest.config.ts`, porque un bucle watch con múltiples shards no es práctico. + - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` enrutan primero los objetivos explícitos de archivo/directorio a través de carriles acotados, de modo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo de arranque completo del proyecto raíz. + - `pnpm test:changed` expande las rutas git modificadas hacia esos mismos carriles acotados cuando el diff solo toca archivos de código fuente/pruebas enrutables; las ediciones de config/setup siguen recurriendo a la reejecución amplia del proyecto raíz. + - Las pruebas unitarias ligeras en importaciones de agents, commands, plugins, ayudantes de auto-reply, `plugin-sdk` y áreas similares de utilidades puras se enrutan por el carril `unit-fast`, que omite `test/setup-openclaw-runtime.ts`; los archivos con mucho estado o con runtime pesado permanecen en los carriles existentes. + - Determinados archivos fuente auxiliares de `plugin-sdk` y `commands` también asignan las ejecuciones en modo changed a pruebas hermanas explícitas en esos carriles ligeros, de modo que las ediciones de ayudantes evitan reejecutar la suite pesada completa para ese directorio. + - `auto-reply` ahora tiene tres buckets dedicados: ayudantes core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de reply fuera de las pruebas baratas de estado/chunk/token. - Nota sobre el ejecutor embebido: - Cuando cambies las entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de Compaction, mantén ambos niveles de cobertura. - - Agrega regresiones enfocadas de ayudantes para límites puros de enrutamiento/normalización. - - También mantén sanas las suites de integración del ejecutor embebido: + - Agrega regresiones enfocadas de ayudantes para límites puros de routing/normalización. + - Mantén también sanas las suites de integración del ejecutor embebido: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` y `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Esas suites verifican que los ids acotados y el comportamiento de Compaction sigan fluyendo + - Esas suites verifican que los ids con alcance y el comportamiento de Compaction sigan fluyendo por las rutas reales `run.ts` / `compact.ts`; las pruebas solo de ayudantes no son un - sustituto suficiente de esas rutas de integración. + sustituto suficiente para esas rutas de integración. - Nota sobre pool: - La configuración base de Vitest ahora usa `threads` de forma predeterminada. - - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos root, las configuraciones e2e y live. - - El carril UI raíz mantiene su configuración `jsdom` y optimizador, pero ahora también se ejecuta en el ejecutor compartido no aislado. - - Cada fragmento de `pnpm test` hereda los mismos valores predeterminados `threads` + `isolate: false` de la configuración compartida de Vitest. - - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` de forma predeterminada para los procesos Node hijo de Vitest para reducir la agitación de compilación de V8 durante ejecuciones locales grandes. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. + - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos root, e2e y live. + - El carril root de UI mantiene su configuración y optimizador de `jsdom`, pero ahora también se ejecuta en el ejecutor compartido no aislado. + - Cada shard de `pnpm test` hereda los mismos valores predeterminados `threads` + `isolate: false` de la configuración compartida de Vitest. + - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` de forma predeterminada para los procesos Node hijos de Vitest a fin de reducir el churn de compilación de V8 durante ejecuciones locales grandes. Configura `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. - Nota sobre iteración local rápida: - `pnpm test:changed` se enruta por carriles acotados cuando las rutas modificadas se asignan limpiamente a una suite más pequeña. - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de enrutamiento, solo con un límite de workers más alto. - - El autoescalado local de workers ahora es intencionalmente conservador y también reduce el ritmo cuando la carga promedio del host ya es alta, de modo que múltiples ejecuciones concurrentes de Vitest hagan menos daño de forma predeterminada. + - El autoescalado de workers locales ahora es intencionalmente conservador y también reduce la carga cuando el promedio de carga del host ya es alto, de modo que varias ejecuciones concurrentes de Vitest causan menos daño de forma predeterminada. - La configuración base de Vitest marca los archivos de proyectos/configuración como `forceRerunTriggers` para que las reejecuciones en modo changed sigan siendo correctas cuando cambie el cableado de pruebas. - - La configuración mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado en hosts compatibles; establece `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si quieres una ubicación de caché explícita para perfiles directos. -- Nota sobre depuración de rendimiento: - - `pnpm test:perf:imports` habilita los informes de duración de importación de Vitest más la salida de desglose de importaciones. - - `pnpm test:perf:imports:changed` acota esa misma vista de perfiles a los archivos modificados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado contra la ruta nativa del proyecto raíz para ese diff confirmado e imprime el tiempo total más el RSS máximo de macOS. -- `pnpm test:perf:changed:bench -- --worktree` evalúa el árbol sucio actual enrutando la lista de archivos modificados a través de `scripts/test-projects.mjs` y la configuración raíz de Vitest. + - La configuración mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado en hosts compatibles; configura `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si quieres una ubicación de caché explícita para perfilado directo. +- Nota de depuración de rendimiento: + - `pnpm test:perf:imports` habilita la generación de informes de duración de importaciones de Vitest, además de la salida del desglose de importaciones. + - `pnpm test:perf:imports:changed` limita esa misma vista de perfilado a archivos modificados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado con la ruta nativa del proyecto raíz para ese diff confirmado e imprime el tiempo total más el RSS máximo en macOS. +- `pnpm test:perf:changed:bench -- --worktree` evalúa el árbol de trabajo actual con cambios al enrutar la lista de archivos modificados a través de `scripts/test-projects.mjs` y la configuración root de Vitest. - `pnpm test:perf:profile:main` escribe un perfil de CPU del hilo principal para la sobrecarga de inicio y transformación de Vitest/Vite. - - `pnpm test:perf:profile:runner` escribe perfiles de CPU+heap del ejecutor para la suite unitaria con el paralelismo de archivos deshabilitado. + - `pnpm test:perf:profile:runner` escribe perfiles de CPU+heap del ejecutor para la suite unitaria con el paralelismo por archivo deshabilitado. -### E2E (smoke del gateway) +### E2E (prueba de humo de Gateway) - Comando: `pnpm test:e2e` - Configuración: `vitest.e2e.config.ts` @@ -224,33 +300,33 @@ Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo) - Usa `threads` de Vitest con `isolate: false`, en línea con el resto del repositorio. - Usa workers adaptativos (CI: hasta 2, local: 1 de forma predeterminada). - Se ejecuta en modo silencioso de forma predeterminada para reducir la sobrecarga de E/S de consola. -- Anulaciones útiles: - - `OPENCLAW_E2E_WORKERS=` para forzar la cantidad de workers (limitada a 16). +- Overrides útiles: + - `OPENCLAW_E2E_WORKERS=` para forzar la cantidad de workers (límite de 16). - `OPENCLAW_E2E_VERBOSE=1` para volver a habilitar la salida detallada de consola. - Alcance: - - Comportamiento end-to-end del gateway en múltiples instancias + - Comportamiento end-to-end de Gateway con múltiples instancias - Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas - Expectativas: - - Se ejecuta en CI (cuando está habilitado en el pipeline) + - Se ejecuta en CI (cuando está habilitado en la pipeline) - No requiere claves reales - - Tiene más partes móviles que las pruebas unitarias (puede ser más lenta) + - Tiene más piezas móviles que las pruebas unitarias (puede ser más lento) -### E2E: smoke del backend de OpenShell +### E2E: prueba de humo del backend OpenShell - Comando: `pnpm test:e2e:openshell` - Archivo: `test/openshell-sandbox.e2e.test.ts` - Alcance: - - Inicia un gateway aislado de OpenShell en el host mediante Docker + - Inicia un Gateway aislado de OpenShell en el host mediante Docker - Crea un sandbox a partir de un Dockerfile local temporal - - Ejercita el backend de OpenShell de OpenClaw sobre `sandbox ssh-config` + ejecución SSH reales + - Ejercita el backend OpenShell de OpenClaw mediante `sandbox ssh-config` + ejecución SSH reales - Verifica el comportamiento canónico remoto del sistema de archivos a través del puente fs del sandbox - Expectativas: - Solo opt-in; no forma parte de la ejecución predeterminada de `pnpm test:e2e` - - Requiere un CLI `openshell` local y un daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` aislados, luego destruye el gateway de prueba y el sandbox -- Anulaciones útiles: + - Requiere un CLI local de `openshell` además de un daemon Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` aislados y luego destruye el Gateway y el sandbox de prueba +- Overrides útiles: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar la prueba al ejecutar manualmente la suite e2e más amplia - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI o script wrapper no predeterminado + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI o script envoltorio no predeterminado ### Live (proveedores reales + modelos reales) @@ -260,112 +336,112 @@ Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo) - Predeterminado: **habilitado** por `pnpm test:live` (establece `OPENCLAW_LIVE_TEST=1`) - Alcance: - “¿Este proveedor/modelo realmente funciona _hoy_ con credenciales reales?” - - Detectar cambios de formato del proveedor, particularidades de llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa + - Detecta cambios de formato del proveedor, peculiaridades de llamada a herramientas, problemas de autenticación y comportamiento de límites de tasa - Expectativas: - - No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) - - Cuesta dinero / usa límites de tasa + - No es estable para CI por diseño (redes reales, políticas reales de proveedores, cuotas, interrupciones) + - Cuesta dinero / consume límites de tasa - Prefiere ejecutar subconjuntos acotados en lugar de “todo” -- Las ejecuciones live cargan `~/.profile` para recoger claves API faltantes. -- De forma predeterminada, las ejecuciones live siguen aislando `HOME` y copian el material de configuración/autenticación a un home temporal de prueba para que las fixtures unitarias no puedan mutar tu `~/.openclaw` real. -- Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando necesites intencionalmente que las pruebas live usen tu directorio home real. -- `pnpm test:live` ahora usa por defecto un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso extra de `~/.profile` y silencia los registros de arranque del gateway y el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los registros completos de inicio. -- Rotación de claves API (específica por proveedor): establece `*_API_KEYS` con formato separado por comas/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o una anulación por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas de límite de tasa. +- Las ejecuciones live cargan `~/.profile` para recoger claves de API faltantes. +- De forma predeterminada, las ejecuciones live siguen aislando `HOME` y copian el material de config/auth a un home de prueba temporal para que los fixtures unitarios no puedan mutar tu `~/.openclaw` real. +- Configura `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando necesites intencionalmente que las pruebas live usen tu directorio home real. +- `pnpm test:live` ahora usa por defecto un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso adicional de `~/.profile` y silencia los logs de arranque de Gateway/el ruido de Bonjour. Configura `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los logs completos de inicio. +- Rotación de claves API (específica del proveedor): configura `*_API_KEYS` con formato de comas/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o el override por live `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas de límite de tasa. - Salida de progreso/Heartbeat: - - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas al proveedor se vean activas incluso cuando la captura de consola de Vitest está en silencio. - - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso del proveedor/gateway se transmitan de inmediato durante las ejecuciones live. + - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas al proveedor se vean activas incluso cuando la captura de consola de Vitest está en modo silencioso. + - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/Gateway se transmitan inmediatamente durante las ejecuciones live. - Ajusta los Heartbeat de modelo directo con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajusta los Heartbeat de gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajusta los Heartbeat de Gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## ¿Qué suite debo ejecutar? +## ¿Qué suite debería ejecutar? Usa esta tabla de decisión: -- Si editas lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste mucho) -- Si tocas redes del gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` -- Si depuras “mi bot está caído” / fallos específicos de proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` acotado +- Editando lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste mucho) +- Tocando redes de Gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` +- Depurando “mi bot no funciona” / fallos específicos del proveedor / llamada a herramientas: ejecuta un `pnpm test:live` acotado -## Live: barrido de capacidades del nodo Android +## Live: barrido de capacidades del Node Android - Prueba: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **cada comando anunciado actualmente** por un nodo Android conectado y verificar el comportamiento del contrato de comandos. +- Objetivo: invocar **todos los comandos anunciados actualmente** por un Node Android conectado y afirmar el comportamiento del contrato de comandos. - Alcance: - - Configuración manual/precondicionada (la suite no instala, ejecuta ni empareja la app). - - Validación `node.invoke` del gateway comando por comando para el nodo Android seleccionado. -- Preconfiguración obligatoria: - - App Android ya conectada y emparejada con el gateway. + - Configuración previa/manual (la suite no instala/ejecuta/empareja la app). + - Validación comando por comando de Gateway `node.invoke` para el Node Android seleccionado. +- Configuración previa requerida: + - App Android ya conectada y emparejada con Gateway. - App mantenida en primer plano. - - Permisos/consentimiento de captura concedidos para las capacidades que esperas que pasen. -- Anulaciones de destino opcionales: + - Permisos/consentimiento de captura otorgados para las capacidades que esperas que pasen. +- Overrides de destino opcionales: - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Detalles completos de configuración de Android: [App Android](/es/platforms/android) -## Live: smoke de modelos (claves de perfil) +## Live: prueba de humo de modelo (claves de perfil) -Las pruebas live se dividen en dos capas para poder aislar fallos: +Las pruebas live se dividen en dos capas para que podamos aislar fallos: -- “Modelo directo” nos dice si el proveedor/modelo puede responder en absoluto con la clave dada. -- “Smoke del gateway” nos dice si funciona el pipeline completo gateway+agente para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). +- “Modelo directo” nos indica si el proveedor/modelo puede responder en absoluto con la clave dada. +- “Prueba de humo de Gateway” nos indica si funciona el pipeline completo Gateway+agente para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). -### Capa 1: finalización directa del modelo (sin gateway) +### Capa 1: finalización directa del modelo (sin Gateway) - Prueba: `src/agents/models.profiles.live.test.ts` - Objetivo: - - Enumerar los modelos descubiertos - - Usar `getApiKeyForModel` para seleccionar modelos para los que tienes credenciales + - Enumerar los modelos detectados + - Usar `getApiKeyForModel` para seleccionar los modelos para los que tienes credenciales - Ejecutar una pequeña finalización por modelo (y regresiones dirigidas cuando sea necesario) - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) -- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` centrado en el smoke del gateway +- Configura `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` enfocado en la prueba de humo de Gateway - Cómo seleccionar modelos: - - `OPENCLAW_LIVE_MODELS=modern` para ejecutar la allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` es un alias de la allowlist moderna - - o `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por comas) - - Los barridos modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. + - `OPENCLAW_LIVE_MODELS=modern` para ejecutar la lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` es un alias de la lista permitida moderna + - o `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (lista permitida separada por comas) + - Los barridos modern/all usan por defecto un límite seleccionado de alta señal; configura `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. - Cómo seleccionar proveedores: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por comas) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (lista permitida separada por comas) - De dónde vienen las claves: - - De forma predeterminada: almacén de perfiles y alternativas de env - - Establece `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para imponer **solo** el almacén de perfiles -- Por qué existe: - - Separa “la API del proveedor está rota / la clave no es válida” de “el pipeline del agente gateway está roto” - - Contiene regresiones pequeñas y aisladas (ejemplo: flujos de repetición de razonamiento y llamadas a herramientas de OpenAI Responses/Codex Responses) + - De forma predeterminada: almacén de perfiles y fallbacks del entorno + - Configura `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **solo el almacén de perfiles** +- Por qué existe esto: + - Separa “la API del proveedor está rota / la clave no es válida” de “el pipeline del agente de Gateway está roto” + - Contiene regresiones pequeñas y aisladas (ejemplo: flujos de razonamiento replay + tool-call de OpenAI Responses/Codex Responses) -### Capa 2: smoke del gateway + agente dev (lo que realmente hace "@openclaw") +### Capa 2: prueba de humo de Gateway + agente dev (lo que realmente hace "@openclaw") - Prueba: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Levantar un gateway en proceso - - Crear/parchear una sesión `agent:dev:*` (anulación de modelo por ejecución) - - Iterar modelos-con-claves y verificar: + - Iniciar un Gateway en proceso + - Crear/parchear una sesión `agent:dev:*` (override de modelo por ejecución) + - Iterar modelos-con-claves y afirmar: - respuesta “significativa” (sin herramientas) - que funcione una invocación real de herramienta (sondeo de lectura) - - sondeos opcionales de herramientas extra (sondeo exec+read) - - que sigan funcionando las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) + - sondeos opcionales de herramientas adicionales (sondeo de exec+read) + - que sigan funcionando las rutas de regresión de OpenAI (solo tool-call → seguimiento) - Detalles de los sondeos (para que puedas explicar fallos rápidamente): - Sondeo `read`: la prueba escribe un archivo nonce en el espacio de trabajo y le pide al agente que lo `read` y devuelva el nonce. - - Sondeo `exec+read`: la prueba le pide al agente que escriba mediante `exec` un nonce en un archivo temporal y luego lo lea con `read`. + - Sondeo `exec+read`: la prueba le pide al agente que escriba mediante `exec` un nonce en un archivo temporal y luego que lo lea con `read`. - Sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva `cat `. - Referencia de implementación: `src/gateway/gateway-models.profiles.live.test.ts` y `src/gateway/live-image-probe.ts`. - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - Cómo seleccionar modelos: - - Predeterminado: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias de la allowlist moderna - - O establece `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separada por comas) para acotar - - Los barridos modern/all del gateway usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. -- Cómo seleccionar proveedores (evitar “todo OpenRouter”): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por comas) + - Predeterminado: lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias para la lista permitida moderna + - O configura `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separada por comas) para acotar + - Los barridos modern/all de Gateway usan por defecto un límite seleccionado de alta señal; configura `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. +- Cómo seleccionar proveedores (evita “todo OpenRouter”): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (lista permitida separada por comas) - Los sondeos de herramientas + imagen siempre están activados en esta prueba live: - sondeo `read` + sondeo `exec+read` (estrés de herramientas) - el sondeo de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen - Flujo (alto nivel): - - La prueba genera un PNG diminuto con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) + - La prueba genera un pequeño PNG con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) - Lo envía mediante `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - El Gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - El agente embebido reenvía un mensaje de usuario multimodal al modelo - - Verificación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) + - Afirmación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) Consejo: para ver qué puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta: @@ -374,26 +450,26 @@ openclaw models list openclaw models list --json ``` -## Live: smoke del backend CLI (Claude, Codex, Gemini u otros CLI locales) +## Live: prueba de humo del backend CLI (Claude, Codex, Gemini u otros CLI locales) - Prueba: `src/gateway/gateway-cli-backend.live.test.ts` -- Objetivo: validar el pipeline del Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada. -- Los valores predeterminados de smoke específicos del backend viven con la definición `cli-backend.ts` de la extensión propietaria. +- Objetivo: validar el pipeline de Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada. +- Los valores predeterminados de la prueba de humo específicos del backend están en la definición `cli-backend.ts` de la extensión propietaria. - Habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Valores predeterminados: +- Predeterminados: - Proveedor/modelo predeterminado: `claude-cli/claude-sonnet-4-6` - El comportamiento de comando/args/imagen proviene de los metadatos del plugin propietario del backend CLI. -- Anulaciones (opcionales): +- Overrides opcionales: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar un adjunto de imagen real (las rutas se inyectan en el prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como args del CLI en lugar de inyección en el prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args de imagen cuando `IMAGE_ARG` está establecido. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivo de imagen como argumentos CLI en lugar de inyección en el prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los argumentos de imagen cuando `IMAGE_ARG` está configurado. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar un segundo turno y validar el flujo de reanudación. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desactivar el sondeo predeterminado de continuidad en la misma sesión Claude Sonnet -> Opus (establécelo en `1` para forzarlo cuando el modelo seleccionado admita un destino de cambio). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para deshabilitar el sondeo predeterminado de continuidad en la misma sesión Claude Sonnet -> Opus (configúralo en `1` para forzarlo cuando el modelo seleccionado admita un destino de cambio). Ejemplo: @@ -403,7 +479,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Receta de Docker: +Receta Docker: ```bash pnpm test:docker:live-cli-backend @@ -421,37 +497,37 @@ pnpm test:docker:live-cli-backend:gemini Notas: - El ejecutor Docker está en `scripts/test-live-cli-backend-docker.sh`. -- Ejecuta el smoke live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. -- Resuelve los metadatos de smoke del CLI desde la extensión propietaria, luego instala el paquete CLI Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible con caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portable de suscripción de Claude Code a través de `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` desde `claude setup-token`. Primero demuestra `claude -p` directo en Docker, luego ejecuta dos turnos del backend CLI de Gateway sin preservar las variables de entorno de clave API de Anthropic. Esta línea de suscripción desactiva por defecto los sondeos MCP/herramientas e imagen de Claude porque Claude actualmente enruta el uso de apps de terceros mediante facturación por uso extra en lugar de los límites normales del plan de suscripción. -- El smoke live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a herramienta `cron` de MCP verificada a través del CLI del gateway. -- El smoke predeterminado de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada todavía recuerde una nota anterior. +- Ejecuta la prueba de humo live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. +- Resuelve los metadatos de la prueba de humo CLI desde la extensión propietaria y luego instala el paquete CLI Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo grabable en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portátil de suscripción de Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` desde `claude setup-token`. Primero demuestra `claude -p` directo en Docker y luego ejecuta dos turnos de backend CLI de Gateway sin preservar las variables de entorno de clave API de Anthropic. Este carril de suscripción deshabilita por defecto los sondeos de MCP/herramientas e imagen de Claude porque Claude actualmente enruta el uso de apps de terceros mediante facturación por uso adicional en lugar de los límites normales del plan de suscripción. +- La prueba de humo live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a la herramienta MCP `cron` verificada a través del CLI de Gateway. +- La prueba de humo predeterminada de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada aún recuerde una nota anterior. -## Live: smoke de enlace ACP (`/acp spawn ... --bind here`) +## Live: prueba de humo de vinculación ACP (`/acp spawn ... --bind here`) - Prueba: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar el flujo real de conversation-bind de ACP con un agente ACP live: +- Objetivo: validar el flujo real de vinculación de conversación ACP con un agente ACP live: - enviar `/acp spawn --bind here` - - enlazar en su lugar una conversación sintética de canal de mensajes + - vincular en su lugar una conversación sintética de canal de mensajes - enviar un seguimiento normal en esa misma conversación - - verificar que el seguimiento llegue a la transcripción de la sesión ACP enlazada + - verificar que el seguimiento llegue a la transcripción de la sesión ACP vinculada - Habilitar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Valores predeterminados: +- Predeterminados: - Agentes ACP en Docker: `claude,codex,gemini` - Agente ACP para `pnpm test:live ...` directo: `claude` - Canal sintético: contexto de conversación estilo DM de Slack - Backend ACP: `acpx` -- Anulaciones: +- Overrides: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Notas: - - Esta línea usa la superficie `chat.send` del gateway con campos sintéticos de originating-route solo para administradores para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa. - - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro de agentes integrado del plugin embebido `acpx` para el agente de arnés ACP seleccionado. + - Este carril usa la superficie `chat.send` de Gateway con campos sintéticos de originating-route solo para admin, de modo que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa. + - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está configurado, la prueba usa el registro de agentes integrado del plugin `acpx` embebido para el agente del arnés ACP seleccionado. Ejemplo: @@ -461,7 +537,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Receta de Docker: +Receta Docker: ```bash pnpm test:docker:live-acp-bind @@ -478,30 +554,31 @@ pnpm test:docker:live-acp-bind:gemini Notas de Docker: - El ejecutor Docker está en `scripts/test-live-acp-bind-docker.sh`. -- De forma predeterminada, ejecuta el smoke de enlace ACP contra todos los agentes CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. +- De forma predeterminada, ejecuta la prueba de humo de vinculación ACP contra todos los agentes CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. - Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para acotar la matriz. -- Carga `~/.profile`, prepara el material de autenticación CLI correspondiente dentro del contenedor, instala `acpx` en un prefijo npm escribible y luego instala el CLI live solicitado (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. -- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que `acpx` mantenga disponibles para el CLI hijo del arnés las variables de entorno del proveedor provenientes del perfil cargado. +- Carga `~/.profile`, prepara el material de autenticación CLI correspondiente en el contenedor, instala `acpx` en un prefijo npm grabable y luego instala el CLI live solicitado (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. +- Dentro de Docker, el ejecutor configura `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para el CLI hijo del arnés las variables de entorno del proveedor procedentes del profile cargado. -## Live: smoke del arnés app-server de Codex +## Live: prueba de humo del arnés app-server de Codex -- Objetivo: validar el arnés de Codex propiedad del plugin a través del método - `agent` normal del gateway: +- Objetivo: validar el arnés de Codex propiedad del plugin mediante el método + normal `agent` de Gateway: - cargar el plugin empaquetado `codex` - seleccionar `OPENCLAW_AGENT_RUNTIME=codex` - - enviar un primer turno de agente del gateway a `codex/gpt-5.4` - - enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo del app-server - pueda reanudarse - - ejecutar `/codex status` y `/codex models` mediante la misma ruta de comando del gateway + - enviar un primer turno de agente de Gateway a `codex/gpt-5.4` + - enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo de + app-server pueda reanudarse + - ejecutar `/codex status` y `/codex models` a través de la misma ruta + de comando de Gateway - Prueba: `src/gateway/gateway-codex-harness.live.test.ts` - Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo predeterminado: `codex/gpt-5.4` - Sondeo opcional de imagen: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sondeo opcional de MCP/herramienta: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- El smoke establece `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que un arnés - de Codex roto no pueda pasar recurriendo silenciosamente a PI. -- Autenticación: `OPENAI_API_KEY` desde el shell/perfil, más `~/.codex/auth.json` y `~/.codex/config.toml` - copiados opcionalmente +- Sondeo opcional MCP/herramienta: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- La prueba de humo configura `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que un arnés de Codex roto + no pueda pasar recurriendo silenciosamente a un fallback a PI. +- Auth: `OPENAI_API_KEY` desde el shell/profile, más copia opcional de + `~/.codex/auth.json` y `~/.codex/config.toml` Receta local: @@ -514,7 +591,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Receta de Docker: +Receta Docker: ```bash source ~/.profile @@ -524,21 +601,20 @@ pnpm test:docker:live-codex-harness Notas de Docker: - El ejecutor Docker está en `scripts/test-live-codex-harness-docker.sh`. -- Carga el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia los archivos de autenticación del CLI de Codex cuando están presentes, instala `@openai/codex` en un prefijo npm montado y escribible, prepara el árbol de código fuente y luego ejecuta solo la prueba live del arnés de Codex. -- Docker habilita por defecto los sondeos de imagen y MCP/herramienta. Establece +- Carga el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia archivos de auth del CLI de Codex cuando están presentes, instala `@openai/codex` en un prefijo npm grabable montado, prepara el árbol fuente y luego ejecuta solo la prueba live del arnés de Codex. +- Docker habilita por defecto los sondeos de imagen y MCP/herramienta. Configura `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` o `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` cuando necesites una ejecución de depuración más acotada. -- Docker también exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, en línea con la - configuración de la prueba live, para que el fallback de `openai-codex/*` o PI no pueda ocultar una regresión del arnés de Codex. +- Docker también exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, en línea con la configuración de la prueba live para que el fallback a `openai-codex/*` o a PI no pueda ocultar una regresión del arnés de Codex. ### Recetas live recomendadas -Las allowlist explícitas y acotadas son las más rápidas y las menos inestables: +Las listas permitidas acotadas y explícitas son las más rápidas y menos inestables: -- Un solo modelo, directo (sin gateway): +- Modelo único, directo (sin Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Un solo modelo, smoke del gateway: +- Modelo único, prueba de humo de Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Llamada a herramientas en varios proveedores: @@ -552,33 +628,33 @@ Notas: - `google/...` usa la API de Gemini (clave API). - `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist). -- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (autenticación separada + particularidades de herramientas). +- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (autenticación separada + peculiaridades de herramientas). - API de Gemini vs CLI de Gemini: - - API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (autenticación por clave API / perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. - - CLI: OpenClaw ejecuta un binario local `gemini`; tiene su propia autenticación y puede comportarse de forma distinta (streaming/compatibilidad con herramientas/desajuste de versiones). + - API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (clave API / auth de perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. + - CLI: OpenClaw ejecuta un binario `gemini` local; tiene su propia autenticación y puede comportarse de forma diferente (streaming/compatibilidad con herramientas/desfase de versión). ## Live: matriz de modelos (qué cubrimos) No hay una “lista fija de modelos de CI” (live es opt-in), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves. -### Conjunto smoke moderno (llamada a herramientas + imagen) +### Conjunto moderno de pruebas de humo (llamada a herramientas + imagen) Esta es la ejecución de “modelos comunes” que esperamos mantener funcionando: - OpenAI (no Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`) -- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos Gemini 2.x más antiguos) +- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita los modelos Gemini 2.x más antiguos) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` y `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Ejecuta el smoke del gateway con herramientas + imagen: +Ejecuta la prueba de humo de Gateway con herramientas + imagen: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Línea base: llamada a herramientas (Read + Exec opcional) +### Base: llamada a herramientas (Read + Exec opcional) -Elige al menos uno por familia de proveedores: +Elige al menos uno por familia de proveedor: - OpenAI: `openai/gpt-5.4` (o `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`) @@ -588,53 +664,53 @@ Elige al menos uno por familia de proveedores: Cobertura adicional opcional (deseable): -- xAI: `xai/grok-4` (o la versión más reciente disponible) -- Mistral: `mistral/`… (elige un modelo con capacidad de `tools` que tengas habilitado) +- xAI: `xai/grok-4` (o la última disponible) +- Mistral: `mistral/`… (elige un modelo con capacidad de herramientas que tengas habilitado) - Cerebras: `cerebras/`… (si tienes acceso) -- LM Studio: `lmstudio/`… (local; la llamada a herramientas depende del modo API) +- LM Studio: `lmstudio/`… (local; la llamada a herramientas depende del modo de API) ### Visión: envío de imagen (adjunto → mensaje multimodal) -Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes de Claude/Gemini/OpenAI con capacidad de visión, etc.) para ejercitar el sondeo de imagen. +Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes de OpenAI con visión, etc.) para ejercitar el sondeo de imagen. ### Agregadores / gateways alternativos Si tienes claves habilitadas, también admitimos pruebas mediante: - OpenRouter: `openrouter/...` (cientos de modelos; usa `openclaw models scan` para encontrar candidatos con capacidad de herramientas+imagen) -- OpenCode: `opencode/...` para Zen y `opencode-go/...` para Go (autenticación mediante `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenCode: `opencode/...` para Zen y `opencode-go/...` para Go (auth mediante `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) Más proveedores que puedes incluir en la matriz live (si tienes credenciales/configuración): - Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Mediante `models.providers` (endpoints personalizados): `minimax` (cloud/API), más cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) +- Mediante `models.providers` (endpoints personalizados): `minimax` (cloud/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) -Consejo: no intentes codificar “todos los modelos” en la documentación. La lista autoritativa es lo que `discoverModels(...)` devuelve en tu máquina + las claves que estén disponibles. +Consejo: no intentes codificar “todos los modelos” en la documentación. La lista autorizada es la que devuelva `discoverModels(...)` en tu máquina + las claves disponibles. -## Credenciales (nunca confirmar en git) +## Credenciales (nunca las confirmes) -Las pruebas live descubren credenciales de la misma manera que la CLI. Implicaciones prácticas: +Las pruebas live detectan credenciales de la misma forma que la CLI. Implicaciones prácticas: - Si la CLI funciona, las pruebas live deberían encontrar las mismas claves. -- Si una prueba live dice “sin credenciales”, depúralo igual que depurarías `openclaw models list` / la selección de modelo. +- Si una prueba live dice “no creds”, depura del mismo modo en que depurarías `openclaw models list` / selección de modelo. -- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “claves de perfil” en las pruebas live) +- Perfiles de auth por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “profile keys” en las pruebas live) - Configuración: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`) - Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home live preparado cuando está presente, pero no es el almacén principal de claves de perfil) -- Las ejecuciones live locales copian por defecto la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de autenticación CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan las anulaciones de ruta `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. +- Las ejecuciones live locales copian por defecto la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de auth CLI externos compatibles a un home de prueba temporal; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan los overrides de rutas `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. -Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores Docker de abajo (pueden montar `~/.profile` dentro del contenedor). +Si quieres depender de claves de entorno (por ejemplo exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores Docker de abajo (pueden montar `~/.profile` dentro del contenedor). ## Live de Deepgram (transcripción de audio) - Prueba: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live del plan de codificación de BytePlus +## Live de plan de codificación de BytePlus - Prueba: `src/agents/byteplus.live.test.ts` - Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Anulación opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Override opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## Live de medios de flujo de trabajo de ComfyUI @@ -642,8 +718,8 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Alcance: - Ejercita las rutas empaquetadas de imagen, video y `music_generate` de comfy - - Omite cada capacidad salvo que `models.providers.comfy.` esté configurado - - Es útil después de cambiar el envío de flujos de trabajo de comfy, el sondeo, las descargas o el registro del plugin + - Omite cada capacidad a menos que `models.providers.comfy.` esté configurado + - Útil después de cambiar el envío de flujos de trabajo de comfy, el polling, las descargas o el registro del plugin ## Live de generación de imágenes @@ -651,24 +727,24 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Arnés: `pnpm test:live:media image` - Alcance: - - Enumera cada plugin de proveedor de generación de imágenes registrado - - Carga variables env de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/env por delante de los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no enmascaren credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizables - - Ejecuta las variantes estándar de generación de imágenes a través de la capacidad compartida de runtime: + - Enumera todos los plugins de proveedor de generación de imágenes registrados + - Carga las variables de entorno de proveedor que faltan desde tu shell de inicio de sesión (`~/.profile`) antes de realizar sondeos + - Usa por defecto claves API live/de entorno antes que los perfiles de auth almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable + - Ejecuta las variantes estándar de generación de imágenes mediante la capacidad compartida de runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Proveedores empaquetados cubiertos actualmente: +- Proveedores empaquetados actualmente cubiertos: - `openai` - `google` - Acotación opcional: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar anulaciones solo-env +- Comportamiento de auth opcional: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar auth desde el almacén de perfiles e ignorar overrides solo de entorno ## Live de generación de música @@ -676,11 +752,11 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media music` - Alcance: - - Ejercita la ruta compartida empaquetada del proveedor de generación de música + - Ejercita la ruta compartida de proveedor de generación de música empaquetado - Actualmente cubre Google y MiniMax - - Carga variables env del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/env por delante de los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no enmascaren credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizables + - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de realizar sondeos + - Usa por defecto claves API live/de entorno antes que los perfiles de auth almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - `edit` cuando el proveedor declara `capabilities.edit.enabled` @@ -691,8 +767,8 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Acotación opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar anulaciones solo-env +- Comportamiento de auth opcional: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar auth desde el almacén de perfiles e ignorar overrides solo de entorno ## Live de generación de video @@ -700,39 +776,39 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media video` - Alcance: - - Ejercita la ruta compartida empaquetada del proveedor de generación de video - - Carga variables env del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/env por delante de los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no enmascaren credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizables + - Ejercita la ruta compartida de proveedor de generación de video empaquetado + - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de realizar sondeos + - Usa por defecto claves API live/de entorno antes que los perfiles de auth almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por buffer en el barrido compartido - - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por buffer en el barrido compartido - - Proveedores `imageToVideo` actualmente declarados pero omitidos en el barrido compartido: - - `vydra` porque el `veo3` empaquetado es solo texto y el `kling` empaquetado requiere una URL remota de imagen - - Cobertura específica del proveedor Vydra: + - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por búfer en el barrido compartido + - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por búfer en el barrido compartido + - Proveedores actualmente declarados pero omitidos de `imageToVideo` en el barrido compartido: + - `vydra` porque el `veo3` empaquetado es solo texto y el `kling` empaquetado requiere una URL de imagen remota + - Cobertura específica de proveedor de Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - ese archivo ejecuta `veo3` de texto a video más un carril `kling` que usa por defecto una fixture de URL remota de imagen + - ese archivo ejecuta `veo3` de texto a video y además un carril `kling` que usa por defecto un fixture de URL de imagen remota - Cobertura live actual de `videoToVideo`: - - solo `runway` cuando el modelo seleccionado es `runway/gen4_aleph` - - Proveedores `videoToVideo` actualmente declarados pero omitidos en el barrido compartido: + - `runway` solo cuando el modelo seleccionado es `runway/gen4_aleph` + - Proveedores actualmente declarados pero omitidos de `videoToVideo` en el barrido compartido: - `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URLs de referencia remotas `http(s)` / MP4 - - `google` porque el carril compartido actual Gemini/Veo usa entrada local respaldada por buffer y esa ruta no se acepta en el barrido compartido - - `openai` porque el carril compartido actual carece de garantías de acceso por organización para inpaint/remix de video + - `google` porque el carril compartido actual de Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido + - `openai` porque el carril compartido actual carece de garantías de acceso específicas de organización para inpaint/remix de video - Acotación opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar anulaciones solo-env +- Comportamiento de auth opcional: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar auth desde el almacén de perfiles e ignorar overrides solo de entorno ## Arnés live de medios - Comando: `pnpm test:live:media` - Propósito: - Ejecuta las suites live compartidas de imagen, música y video mediante un único punto de entrada nativo del repositorio - - Carga automáticamente variables env faltantes del proveedor desde `~/.profile` - - Acota automáticamente por defecto cada suite a los proveedores que actualmente tienen autenticación utilizable - - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de Heartbeat y modo silencioso siga siendo consistente + - Carga automáticamente las variables de entorno de proveedor que faltan desde `~/.profile` + - Acota automáticamente cada suite a proveedores que actualmente tengan auth utilizable, de forma predeterminada + - Reutiliza `scripts/test-live.mjs`, de modo que el comportamiento de Heartbeat y modo silencioso siga siendo coherente - Ejemplos: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -743,144 +819,144 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), Estos ejecutores Docker se dividen en dos grupos: -- Ejecutores de modelos live: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio de configuración y espacio de trabajo locales (y cargando `~/.profile` si está montado). Los puntos de entrada locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. -- Los ejecutores live de Docker usan por defecto un límite smoke más pequeño para que un barrido Docker completo siga siendo práctico: +- Ejecutores de modelos live: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio local de config y espacio de trabajo (y cargando `~/.profile` si está montado). Los puntos de entrada locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. +- Los ejecutores Docker live usan por defecto un límite de prueba de humo más pequeño para que un barrido Docker completo siga siendo práctico: `test:docker:live-models` usa por defecto `OPENCLAW_LIVE_MAX_MODELS=12`, y `test:docker:live-gateway` usa por defecto `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` y - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Anula esas variables env cuando - explícitamente quieras el análisis exhaustivo más grande. -- `test:docker:all` construye una vez la imagen Docker live mediante `test:docker:live-build`, y luego la reutiliza para las dos líneas Docker live. -- Ejecutores smoke de contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` arrancan uno o más contenedores reales y verifican rutas de integración de nivel superior. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sustituye esas variables de entorno cuando + quieras explícitamente el escaneo exhaustivo más grande. +- `test:docker:all` construye la imagen Docker live una vez mediante `test:docker:live-build`, y luego la reutiliza para los dos carriles Docker live. +- Ejecutores de prueba de humo de contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` arrancan uno o más contenedores reales y verifican rutas de integración de nivel superior. -Los ejecutores Docker de modelos live también montan por bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), y luego los copian al home del contenedor antes de la ejecución para que el OAuth del CLI externo pueda renovar tokens sin mutar el almacén de autenticación del host: +Los ejecutores Docker de modelos live también montan por enlace solo los homes de auth CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), y luego los copian al home del contenedor antes de la ejecución para que OAuth de CLI externo pueda renovar tokens sin mutar el almacén de auth del host: - Modelos directos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke de enlace ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Smoke del backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke del arnés app-server de Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Prueba de humo de vinculación ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Prueba de humo del backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Prueba de humo del arnés app-server de Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) - Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) -- Smoke live de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) +- Prueba de humo live de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Asistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Redes del gateway (dos contenedores, autenticación WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Puente de canal MCP (Gateway precargado + puente stdio + smoke en bruto de frame de notificación de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke de instalación + alias `/plugin` + semántica de reinicio del paquete Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Red de Gateway (dos contenedores, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Puente de canal MCP (Gateway sembrado + puente stdio + prueba de humo de frame de notificación Claude sin procesar): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (prueba de humo de instalación + alias `/plugin` + semántica de reinicio del bundle de Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Los ejecutores Docker de modelos live también montan por bind la copia de trabajo actual en solo lectura y -la preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene ligera la imagen de runtime -mientras sigue ejecutando Vitest contra tu código fuente/configuración locales exactos. +Los ejecutores Docker de modelos live también montan por enlace el checkout actual en modo de solo lectura y +lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la +imagen de runtime ligera mientras sigue ejecutando Vitest contra tu código fuente/configuración locales exactos. El paso de preparación omite cachés locales grandes y salidas de compilación de apps como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios de salida locales de app `.build` o -Gradle para que las ejecuciones Docker live no pasen minutos copiando +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y los directorios locales de `.build` o +salida de Gradle, para que las ejecuciones live en Docker no pasen minutos copiando artefactos específicos de la máquina. -También establecen `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos live del gateway no inicien -workers reales de canales Telegram/Discord/etc. dentro del contenedor. -`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que pasa también +También configuran `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos live de Gateway no inicien +workers reales de canales de Telegram/Discord/etc. dentro del contenedor. +`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que transmite también `OPENCLAW_LIVE_GATEWAY_*` cuando necesites acotar o excluir la cobertura -live del gateway de esa línea Docker. -`test:docker:openwebui` es un smoke de compatibilidad de nivel superior: inicia un -contenedor de gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, -inicia un contenedor fijado de Open WebUI contra ese gateway, inicia sesión mediante -Open WebUI, verifica que `/api/models` expone `openclaw/default`, y luego envía una -solicitud de chat real a través del proxy `/api/chat/completions` de Open WebUI. -La primera ejecución puede ser notablemente más lenta porque Docker puede necesitar descargar la -imagen de Open WebUI y Open WebUI puede necesitar completar su propio arranque en frío. -Esta línea espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` -(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones dockerizadas. -Las ejecuciones exitosas imprimen un pequeño payload JSON como `{ "ok": true, "model": +live de Gateway de ese carril Docker. +`test:docker:openwebui` es una prueba de humo de compatibilidad de nivel superior: inicia un +contenedor de Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, +inicia un contenedor fijado de Open WebUI contra ese Gateway, inicia sesión mediante +Open WebUI, verifica que `/api/models` exponga `openclaw/default` y luego envía una +solicitud de chat real mediante el proxy `/api/chat/completions` de Open WebUI. +La primera ejecución puede ser notablemente más lenta porque Docker quizá necesite descargar la +imagen de Open WebUI y Open WebUI quizá necesite completar su propia configuración en frío. +Este carril espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` +(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones Docker. +Las ejecuciones exitosas imprimen una pequeña carga útil JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` es intencionalmente determinista y no necesita una -cuenta real de Telegram, Discord o iMessage. Arranca un contenedor de Gateway -precargado, inicia un segundo contenedor que ejecuta `openclaw mcp serve`, y luego -verifica el descubrimiento de conversaciones enrutadas, lecturas de transcripción, metadatos de adjuntos, -comportamiento de cola de eventos live, enrutamiento de envíos salientes y notificaciones de canal + -permisos estilo Claude sobre el puente MCP stdio real. La comprobación de notificaciones -inspecciona directamente los frames MCP stdio en bruto, de modo que el smoke valida lo que -el puente realmente emite, no solo lo que una SDK cliente específica expone casualmente. +cuenta real de Telegram, Discord o iMessage. Inicia un contenedor de Gateway +sembrado, arranca un segundo contenedor que ejecuta `openclaw mcp serve` y luego +verifica descubrimiento de conversaciones enrutadas, lecturas de transcripciones, metadatos de adjuntos, +comportamiento de la cola de eventos live, enrutamiento de envíos salientes y notificaciones de canal + +permisos de estilo Claude sobre el puente MCP stdio real. La comprobación de notificaciones +inspecciona directamente los frames MCP stdio sin procesar para que la prueba de humo valide lo que el +puente realmente emite, no solo lo que una SDK cliente específica expone casualmente. -Smoke manual de hilo ACP en lenguaje natural (no CI): +Prueba manual de hilo ACP en lenguaje natural (no CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Conserva este script para flujos de regresión/depuración. Puede volver a ser necesario para validar el enrutamiento de hilos ACP, así que no lo elimines. +- Mantén este script para flujos de trabajo de regresión/depuración. Puede volver a ser necesario para validar el enrutamiento de hilos ACP, así que no lo elimines. -Variables env útiles: +Variables de entorno útiles: - `OPENCLAW_CONFIG_DIR=...` (predeterminado: `~/.openclaw`) montado en `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (predeterminado: `~/.openclaw/workspace`) montado en `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (predeterminado: `~/.profile`) montado en `/home/node/.profile` y cargado antes de ejecutar las pruebas - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predeterminado: `~/.cache/openclaw/docker-cli-tools`) montado en `/home/node/.npm-global` para instalaciones CLI en caché dentro de Docker -- Los directorios/archivos de autenticación CLI externos bajo `$HOME` se montan en solo lectura bajo `/host-auth...`, luego se copian a `/home/node/...` antes de que comiencen las pruebas +- Los directorios/archivos de auth CLI externos bajo `$HOME` se montan en solo lectura bajo `/host-auth...`, y luego se copian a `/home/node/...` antes de que comiencen las pruebas - Directorios predeterminados: `.minimax` - Archivos predeterminados: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Las ejecuciones acotadas por proveedor montan solo los directorios/archivos necesarios inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Anúlalo manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Sustituye manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para acotar la ejecución - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar proveedores dentro del contenedor -- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar una imagen `openclaw:local-live` existente en reejecuciones que no necesiten reconstrucción -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para asegurar que las credenciales provengan del almacén de perfiles (no de env) -- `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por el gateway para el smoke de Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para anular el prompt de verificación de nonce usado por el smoke de Open WebUI -- `OPENWEBUI_IMAGE=...` para anular la etiqueta fijada de imagen de Open WebUI +- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar una imagen existente `openclaw:local-live` en reejecuciones que no necesitan reconstrucción +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para asegurar que las credenciales provengan del almacén de perfiles (no del entorno) +- `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por Gateway para la prueba de humo de Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para sustituir el prompt de verificación de nonce usado por la prueba de humo de Open WebUI +- `OPENWEBUI_IMAGE=...` para sustituir la etiqueta fijada de imagen de Open WebUI -## Verificación de documentación +## Verificación básica de la documentación -Ejecuta comprobaciones de documentación después de editar docs: `pnpm check:docs`. -Ejecuta la validación completa de anchors de Mintlify cuando también necesites comprobar encabezados dentro de la página: `pnpm docs:check-links:anchors`. +Ejecuta comprobaciones de docs tras editar documentación: `pnpm check:docs`. +Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobar encabezados dentro de la página: `pnpm docs:check-links:anchors`. -## Regresión sin conexión (segura para CI) +## Regresión offline (segura para CI) Estas son regresiones de “pipeline real” sin proveedores reales: -- Llamada a herramientas del gateway (OpenAI simulado, gateway real + bucle de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Asistente del gateway (WS `wizard.start`/`wizard.next`, escritura de configuración + autenticación aplicada): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Llamada a herramientas de Gateway (OpenAI simulado, Gateway real + bucle de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Asistente de Gateway (WS `wizard.start`/`wizard.next`, escribe config + auth exigida): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evals de fiabilidad del agente (Skills) +## Evaluaciones de confiabilidad del agente (Skills) -Ya tenemos algunas pruebas seguras para CI que se comportan como “evals de fiabilidad del agente”: +Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de confiabilidad del agente”: -- Llamada simulada a herramientas a través del gateway real + bucle de agente (`src/gateway/gateway.test.ts`). -- Flujos end-to-end del asistente que validan el cableado de sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). +- Llamada a herramientas simulada mediante el bucle real de Gateway + agente (`src/gateway/gateway.test.ts`). +- Flujos end-to-end del asistente que validan el cableado de sesión y los efectos de config (`src/gateway/gateway.test.ts`). -Qué sigue faltando para Skills (consulta [Skills](/es/tools/skills)): +Lo que aún falta para Skills (ver [Skills](/es/tools/skills)): -- **Toma de decisiones:** cuando Skills aparece en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)? +- **Toma de decisiones:** cuando Skills aparece en el prompt, ¿el agente elige la skill correcta (o evita las irrelevantes)? - **Cumplimiento:** ¿el agente lee `SKILL.md` antes de usarlo y sigue los pasos/args requeridos? -- **Contratos de flujo de trabajo:** escenarios de varios turnos que verifiquen orden de herramientas, arrastre del historial de sesión y límites del sandbox. +- **Contratos de flujo de trabajo:** escenarios de varios turnos que afirman el orden de herramientas, el arrastre del historial de sesión y los límites del sandbox. -Los evals futuros deben seguir siendo deterministas primero: +Las evaluaciones futuras deberían seguir siendo deterministas primero: -- Un ejecutor de escenarios que use proveedores simulados para verificar llamadas + orden de herramientas, lecturas de archivos de Skill y cableado de sesión. -- Una pequeña suite de escenarios centrados en Skills (usar vs evitar, compuertas, inyección de prompt). -- Evals live opcionales (opt-in, protegidos por env) solo después de que la suite segura para CI esté lista. +- Un ejecutor de escenarios que use proveedores simulados para afirmar llamadas a herramientas + orden, lecturas de archivos de skill y cableado de sesión. +- Una pequeña suite de escenarios enfocados en skills (usar vs evitar, gating, inyección de prompt). +- Evaluaciones live opcionales (opt-in, controladas por entorno) solo después de que exista la suite segura para CI. -## Pruebas de contrato (forma de Plugin y canal) +## Pruebas de contrato (forma de plugin y canal) Las pruebas de contrato verifican que cada plugin y canal registrado se ajuste a su -contrato de interfaz. Iteran sobre todos los plugins descubiertos y ejecutan una suite de -verificaciones de forma y comportamiento. El carril unitario predeterminado de `pnpm test` -omite intencionalmente estos archivos compartidos de interfaz y smoke; ejecuta los comandos de contrato explícitamente +contrato de interfaz. Iteran sobre todos los plugins detectados y ejecutan un conjunto de +afirmaciones de forma y comportamiento. El carril unitario predeterminado de `pnpm test` +omite intencionalmente estos archivos compartidos de interfaces y pruebas de humo; ejecuta los comandos de contrato de forma explícita cuando toques superficies compartidas de canal o proveedor. ### Comandos - Todos los contratos: `pnpm test:contracts` -- Solo contratos de canal: `pnpm test:contracts:channels` -- Solo contratos de proveedor: `pnpm test:contracts:plugins` +- Solo contratos de canales: `pnpm test:contracts:channels` +- Solo contratos de proveedores: `pnpm test:contracts:plugins` -### Contratos de canal +### Contratos de canales Ubicados en `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Forma básica del plugin (id, name, capabilities) - **setup** - Contrato del asistente de configuración -- **session-binding** - Comportamiento del enlace de sesión -- **outbound-payload** - Estructura del payload del mensaje -- **inbound** - Manejo de mensajes entrantes -- **actions** - Controladores de acciones del canal -- **threading** - Manejo de ids de hilo -- **directory** - API de directorio/listado -- **group-policy** - Aplicación de política de grupo +- **session-binding** - Comportamiento de vinculación de sesión +- **outbound-payload** - Estructura de la carga útil del mensaje +- **inbound** - Gestión de mensajes entrantes +- **actions** - Manejadores de acciones del canal +- **threading** - Gestión de ids de hilo +- **directory** - API de directorio/lista +- **group-policy** - Aplicación de políticas de grupo ### Contratos de estado del proveedor @@ -889,14 +965,14 @@ Ubicados en `src/plugins/contracts/*.contract.test.ts`. - **status** - Sondeos de estado del canal - **registry** - Forma del registro de plugins -### Contratos de proveedor +### Contratos de proveedores Ubicados en `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato de flujo de autenticación +- **auth** - Contrato del flujo de autenticación - **auth-choice** - Elección/selección de autenticación -- **catalog** - API del catálogo de modelos -- **discovery** - Descubrimiento de plugins +- **catalog** - API de catálogo de modelos +- **discovery** - Detección de plugins - **loader** - Carga de plugins - **runtime** - Runtime del proveedor - **shape** - Forma/interfaz del plugin @@ -906,19 +982,19 @@ Ubicados en `src/plugins/contracts/*.contract.test.ts`: - Después de cambiar exportaciones o subrutas de plugin-sdk - Después de agregar o modificar un plugin de canal o proveedor -- Después de refactorizar el registro o descubrimiento de plugins +- Después de refactorizar el registro o la detección de plugins -Las pruebas de contrato se ejecutan en CI y no requieren claves API reales. +Las pruebas de contrato se ejecutan en CI y no requieren claves de API reales. ## Agregar regresiones (guía) Cuando corrijas un problema de proveedor/modelo descubierto en live: -- Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura la transformación exacta de forma de solicitud) -- Si es inherentemente solo live (límites de tasa, políticas de autenticación), mantén la prueba live acotada y opt-in mediante variables env +- Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura de la transformación exacta de la forma de solicitud) +- Si es inherentemente solo live (límites de tasa, políticas de autenticación), mantén la prueba live acotada y opt-in mediante variables de entorno - Prefiere apuntar a la capa más pequeña que detecte el error: - - error de conversión/repetición de solicitud del proveedor → prueba de modelos directos - - error del pipeline de sesión/historial/herramientas del gateway → smoke live del gateway o prueba simulada del gateway segura para CI -- Protección de recorrido de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase de SecretRef a partir de los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego verifica que se rechacen los ids exec de segmentos de recorrido. - - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente con ids de objetivo no clasificados para que las clases nuevas no puedan omitirse silenciosamente. + - error de conversión/replay de solicitud del proveedor → prueba de modelos directos + - error del pipeline de sesión/historial/herramientas de Gateway → prueba de humo live de Gateway o prueba segura para CI con simulación de Gateway +- Barrera de protección de recorrido de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase de SecretRef a partir de los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego afirma que se rechazan los ids de exec de segmentos de recorrido. + - Si agregas una nueva familia objetivo de SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente con ids objetivo no clasificados para que las clases nuevas no puedan omitirse silenciosamente.