Skip to content

Depuración de Ultrafast: qué hacer si no conecta, no hace clic o se desvía ​

Si algo sale mal al ejecutar Jev Ultrafast, lo más probable es que se atasque en una de cuatro capas: el servicio local no arrancó, Chrome no conectó, la llamada al modelo fue rechazada, o la ejecución de la decisión chocó con un muro. Esta lección repasa los errores comunes de jev-ultrafast uno por uno según su «texto original», con causa y solución: primero una verificación rápida de 60 segundos, y luego identifica el tuyo.

Todos los textos originales de los errores provienen del código fuente del repositorio (jev_ultrafast/model.py, agent.py, browser.py, demo.py y la interfaz del inspector), se pueden buscar palabra por palabra y copiar para preguntar. No importa si te atascaste en un curso previo: si algo falló en instalación y ejecución, puedes volver aquí a consultarlo.

Qué podrás hacer al terminar ​

  • Localizar en 60 segundos, con 4 comandos, cuál eslabón falló: directorio, Key, Chrome o capa de ejecución del navegador
  • Identificar cada error de jev-ultrafast: texto original → causa → pasos de reparación
  • Distinguir el tratamiento de tres tipos de errores: tipo stale (autocorrección en modo automático), tipo reintento (retroceso automático del código) y tipo manual (requiere que cambies la configuración o el objetivo)
  • Entender las 6 visualizaciones de la barra de estado del inspector y saber qué hacer a continuación con done y blocked
  • Recordar la lista de no soportados: shadow DOM, frames, canvas, subidas, ventanas emergentes nuevas, scroll anidado y componentes de teclado arbitrarios
  • Usar Export trace para exportar la evidencia de decisiones y preguntar con la información mínima

Tu situación actual ​

  • Pulsas Start demo y no pasa nada; no sabes si el servicio no arrancó, Chrome no conectó o falta la Key
  • El error en inglés del recuadro rojo aparece un instante y desaparece; no sabes qué frase buscar y, si encuentras algo, no entiendes de qué capa es la culpa
  • El estado del agent cambia a done / blocked, pero la página no muestra el resultado esperado: ¿el objetivo está mal escrito o esta página simplemente no se puede ejecutar?

Cuándo usar esta técnica ​

Cuando necesitas:

Y no quieres:

  • Borrar el repositorio y reinstalar al primer error, repitiendo todo el proceso de instalación desde cero
  • No distinguir entre «la página cambió, hay que reintentar» y «la configuración está rota, hay que repararla», y perder medio día cambiando cosas sin sentido

🎒 Preparativos antes de empezar ​

  • Haber completado Instalación y ejecución de Ultrafast (no importa si te atascaste, esta lección es justamente para desatascarte)
  • Tener el repositorio clonado localmente y poder ejecutar comandos en el directorio raíz jev-ultrafast/ desde la terminal
  • (Opcional) Haber hecho Escribe tus propias tareas de navegador: los errores que surjan al usar la librería Agent también se pueden identificar aquí

Idea central ​

Primero determina la capa, luego mira el error. Una tarea Ultrafast atraviesa cuatro capas, y los errores de cada capa se ven distintos:

CapaQué se compruebaError típico / síntoma
1. Servicio localSi uv run jev arrancó, si el directorio es correcto, si la dirección es 127.0.0.1Cannot reach local demo server / Forbidden
2. Conexión de ChromeBrowser Harness, autorización de depuración remotaEl panel no se mueve
3. Llamada al modeloLas dos Key, la red, la cuotaTYPE_TEXT needs TEXT_MODEL_API_KEY / Model provider returned HTTP 401
4. Decisión y ejecuciónCambios de página, presupuesto de acciones, límites de controles de la páginaTarget changed or is covered / el estado cambia a blocked

Tres tipos de errores, tres tratamientos. Al ver un error, clasifícalo primero; no te apresures a actuar:

TipoEjemploLo que debes hacer
De autocuración (stale, la página cambió)Page changed since the decision / Target changed or is coveredNo hay que hacer nada: la ejecución automática volverá a observar y decidir; en modo manual, pulsa una vez Choose next
De reintento (el servidor rechaza temporalmente)429 / 529 / 503 → el código lo intenta en total 3 veces (reintenta 2 veces) y, si sigue fallando, reporta Model provider returned HTTP 429/529/503Espera un poco y vuelve a ejecutar; revisa la cuota
Que requieren acción (configuración / presupuesto / límites)Falta la Key, HTTP 401, 60 acciones de presupuesto, shadow DOM no soportadoCambia la configuración, el objetivo o la página según los puntos siguientes

💡 Tabla de referencia de la barra de estado del inspector (texto original de app.js)

Muestra la barra de estadoSignificadoQué debes hacer
Ready to exploreTodavía no has pulsado Start demoRellena el objetivo y pulsa Start demo
Page observed · ready for a decisionPágina observada, esperando decisiónPulsa Choose next o Run automatically
Choice ready · inspect or executeDecisión lista, pendiente de ejecutarRevisa las probabilidades y pulsa Execute choice
Jev reports complete · inspect the pageEl modelo eligió DONEVerifica la página personalmente—DONE no es prueba de éxito
Stopped · no supported next actionblocked: acciones inválidas consecutivas o el modelo eligió BLOCKEDMira los últimos pasos del Decision trail y compáralos con la lista de no soportados
Paused · needs attentionPausado por errorMira el texto del error en el recuadro rojo y encuéntrale su caso

Primera revisión: verificación rápida en 60 segundos ​

Cuatro comandos que se ejecutan en orden, verificando sucesivamente el directorio, la Key, la conexión con Chrome y la capa de ejecución del navegador. Requisito previo: la terminal donde corre uv run jev sigue imprimiendo Jev Ultrafast: http://127.0.0.1:8766, y el navegador se abrió con 127.0.0.1:8766 (no localhost; el motivo está en la entrada de depuración Forbidden más abajo).

bash
# 1. 当前目录对吗?——.env 从「当前目录」读取,必须在仓库根目录跑
pwd
# 应以 jev-ultrafast 结尾;不在就先 cd jev-ultrafast

# 2. 两个 Key 都配了吗?——应看到两行(值非空才算数)
grep -E "^(TYPESAFE_API_KEY|TEXT_MODEL_API_KEY)=." .env
# 顺手 echo $TYPESAFE_API_KEY 确认 shell 里没有旧值抢先——.env 不会覆盖已 export 的变量

# 3. Chrome 连得上吗?——官方诊断命令
uv run browser-harness --doctor
# 按提示在 Chrome 里允许远程调试

# 4. 浏览器执行层正常吗?——官方开发命令,不调用模型、不花 API 费
uv run python scripts/check_guards.py
# 在本地浏览器里跑执行守卫回归;脚本自己的说明:No model calls or external websites

Deberías ver: la 1 termina con jev-ultrafast; la 2 produce dos líneas; la 3 completa el diagnóstico de conexión; la 4 termina imprimiendo PASS: N browser guard checks; no model calls. Arregla por donde se rompa; si las cuatro pasan y sigue habiendo errores, el problema está casi seguro en la llamada al modelo o en la capa de decisión—sigue abajo para encontrar tu caso.

Resolución de problemas frecuentes ​

Arranque y conexión con Chrome (no conecta) ​

"Cannot reach local demo server" ​

Causa: la página del inspector no logra conectar con el servicio local—uv run jev no está corriendo, el puerto se cambió, o la página es una pestaña antigua. Esta frase aparece en la barra de estado (la rama de fetch fallido de app.js).

Solución:

  1. Reinicia en el directorio raíz del repositorio; la terminal debería imprimir:
bash
uv run jev
# Jev Ultrafast: http://127.0.0.1:8766
  1. Abre http://127.0.0.1:8766 en el navegador. Si cambiaste el puerto: TYPESAFE_DEMO_PORT debe configurarse antes del arranque (demo.py lee el puerto fijo al importar el módulo); consulta las técnicas avanzadas de la lección de instalación y ejecución.

Al abrir la página solo se muestra "Forbidden" ​

Causa: se usó localhost:8766 en lugar de 127.0.0.1:8766. El servicio demo valida el encabezado Host y solo acepta 127.0.0.1:8766—este servicio escucha únicamente en la dirección de loopback local (demo.py se autodenomina Loopback-only inspector), y las peticiones POST reciben además {"error": "Local demo requests only"}.

Solución: cambia la barra de direcciones a http://127.0.0.1:8766 y actualiza.

Chrome no conecta, el panel no se mueve ​

Causa: Browser Harness necesita que Chrome permita la depuración remota; Chrome muestra el aviso en la primera conexión; si lo pierdes o lo rechazas, ya no conecta. Texto literal del README: Allow remote debugging in Chrome when prompted.

Solución:

  1. Ejecuta el comando oficial de diagnóstico, en el directorio raíz del repositorio:
bash
uv run browser-harness --doctor
  1. Cuando Chrome vuelva a mostrar el aviso de «permitir depuración remota», pulsa permitir.
  2. Si el diagnóstico pasa pero sigue sin moverse: ejecuta primero el uv run python scripts/check_guards.py de arriba—no llama al modelo y permite verificar la capa de ejecución del navegador por separado.

"A browser step is already running" ​

Causa: el paso anterior todavía se está ejecutando. El servicio demo usa un bloqueo global para garantizar que solo corra un paso de navegador a la vez; las peticiones que chocan con el bloqueo devuelven 409 y esta frase.

Solución: espera a que termine el paso actual; si quieres detener Run automatically mientras está en curso, pulsa Pause.

"Local demo failed; no automatic retry. Reset to recover." ​

Causa: el servicio demo envuelve cualquier excepción no capturada específicamente en este mensaje genérico 500 de respaldo. El desencadenante más común: TYPESAFE_API_KEY no está configurado en absoluto—model.py lee directamente os.environ["TYPESAFE_API_KEY"]; si falta, lanza KeyError, no se muestra el texto original y solo cae en este mensaje de respaldo.

Solución:

  1. Comprueba las dos Keys de .env (el punto 2 de la verificación rápida de 60 segundos).
  2. Haz Reset como indica el aviso: pulsa Start demo para reiniciar una vez.
  3. Quienes usan la biblioteca Agent verán directamente el traceback original (por ejemplo KeyError: 'TYPESAFE_API_KEY'); corrige lo que falte según corresponda.

"Start a demo first" ​

Causa: en el inspector se pulsó Choose next / Execute choice / Run automatically sin haber hecho Start demo antes—el servicio demo rechaza estos comandos cuando todavía no se ha creado el agente.

Solución: primero escribe el objetivo, pulsa Start demo y luego ejecuta los botones de control.

"Enter 1–2,000 characters" ​

Causa: el objetivo está vacío o supera los 2000 caracteres (validación reset de demo.py).

Solución: escribe el objetivo en 1–2000 caracteres o menos. Pasar un objetivo vacío con la librería Agent da Supply a task (agent.py), con el mismo significado.

Key y llamadas al modelo (zona de errores frecuentes de TEXT_MODEL) ​

"TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor." ​

Causa: a .env le falta TEXT_MODEL_API_KEY. Esta comprobación solo se activa cuando la acción es TYPE_TEXT (field_text() de model.py), así que la demo puede arrancar y la página puede observarse, y solo se detiene al llegar a «escribir en un campo de texto» — la demo Flights necesita generar nombres de ciudades, no hay forma de evitarlo.

Solución:

  1. Añade en .env la Key del modelo de texto (dónde conseguirla, ver la forma A/B/C del paso 3 de la lección de instalación y ejecución).
  2. Ten en cuenta la regla de lectura: .env se lee desde el directorio actual y no sobrescribe las variables homónimas ya exportadas en la shell — si ya lo rellenaste y sigue dando error, haz cd jev-ultrafast y vuelve a ejecutar, y comprueba echo $TEXT_MODEL_API_KEY.

"Model provider returned HTTP 401; no action executed." ​

Causa: el endpoint del modelo devolvió un código de estado de error, que se inserta en esta plantilla (el código fuente es f"Model provider returned HTTP {response.status_code}; no action executed."). 401 = Key no válida. Este mensaje TypeSafe se comparte con el modelo de texto, así que primero distingue de qué lado proviene:

Cuándo se reportaDe qué lado esQué comprobar
Se reporta ya en la primera decisiónTypeSafe (la decisión se llama en cada ciclo)TYPESAFE_API_KEY
Solo se reporta al llegar al paso de escribir textoModelo de texto (solo lo usa TYPE_TEXT)Si TEXT_MODEL_API_KEY y TEXT_MODEL_BASE_URL coinciden

Solución:

  1. Por el lado de TypeSafe: vuelve a la página Keys de la consola y copia de nuevo la Key; puedes verificarla con curl (resolución de problemas inicial tiene el comando completo).
  2. Por el lado del modelo de texto: confirma que la Key sea del endpoint que configuraste (una Key de OpenRouter configurada con el endpoint de DeepSeek es 401).
  3. El significado de otros códigos de estado (400/413/415/422, etc.) está en la tabla de códigos de estado de API de consulta rápida — 429/529/503 no se reportan de inmediato, ver más abajo "Model provider returned HTTP 429/529/503".

"Model connection failed; no action executed." ​

Causa: el cliente HTTP lanzó una excepción a nivel de red — no se puede conectar al endpoint, fallo de resolución DNS y similares; la solicitud ni siquiera llegó a enviarse (model.py captura httpx.HTTPError y luego lanza este mensaje).

Solución:

  1. Comprueba si la red puede acceder a api.typesafe.ai y a tu TEXT_MODEL_BASE_URL.
  2. Comprueba la ortografía del endpoint: en TEXT_MODEL_BASE_URL el error habitual es que falte o sobre un /v1 (valor de ejemplo https://openrouter.ai/api/v1, DeepSeek usa por defecto https://api.deepseek.com/v1).

"Model provider returned HTTP 429/529/503; no action executed." (limitación de tasa y sobrecarga) ​

Causa: el endpoint del modelo devolvió 429 (limitación de tasa) / 529 (sobrecarga) / 503. Estos códigos de estado no se reportan de inmediato: el código intenta en total 3 veces (reintenta 2 veces, con intervalos de 0.5s y 1s); solo si el intento 3 sigue fallando se inserta en la plantilla de códigos de estado anterior y se reporta Model provider returned HTTP 429; no action executed. (529 y 503 con la misma estructura).

En el código fuente hay además un mensaje de respaldo "Model unavailable" (model.py L27), pero según el flujo de control actual es inalcanzable — agotados los reintentos de 429/529/503 se usa la plantilla de códigos de estado, y este mensaje no aparece en la interfaz; si lo encuentras buscando en el código fuente, asígnalo a esta entrada.

Solución: espera un momento y vuelve a ejecutar; si aparece con frecuencia, revisa la cuota — por el lado de TypeSafe en la página rate-limits de la consola, y por el lado del modelo de texto en la página de facturación de tu proveedor.

"Invalid TypeSafe response; no action executed." ​

Causa: la respuesta de decisión no pasó la validación local (model.py de validate_choice(): la opción elegida debe estar entre las candidatas, cada opción debe tener probabilidad, los valores deben estar en 0–1 y la suma de probabilidades debe ser aproximadamente 1). Es un guardián de «la respuesta no cumple el contrato», no un problema de tu configuración.

Solución: primero vuelve a ejecutar tal cual (es algo ocasional); si persiste, exporta el trace (ver «¿Sigue sin funcionar?») y llévalo como retroalimentación.

"Text helper returned no valid field value; nothing typed." ​

Causa: la salida del modelo de texto no cumple el contrato — debe ser un JSON con solo la clave text, cuyo valor es una cadena no vacía de no más de 2000 caracteres (reglas de análisis de model.py). Dos disparadores habituales:

DisparadorMecanismo
Falta un valor obligatorio en el objetivoLas instrucciones del modelo establecen explícitamente: si falta un valor, devolver {"text": null} y nunca inventar datos personales (el TEXT_VALUE de questions.py) — el null falla al analizarse y no se escribe nada
El modelo no sigue las reglasDevolvió un párrafo de texto explicativo en lugar de JSON — el informe de rendimiento oficial menciona justamente que durante el sondeo se rechazó a un modelo de este tipo

Solución:

  1. Escribe en el objetivo los valores que la tarea necesita (fechas, nombres de ciudades y similares, no dejes que el modelo los adivine).
  2. Si aún no funciona, cambia de modelo de texto y mantén TEXT_MODEL_REASONING=none (los modelos sin razonamiento improvisan menos).
  3. Un valor escrito con errores (no el hecho de no escribir) se maneja igual: la prueba oficial incluso rechazó a un modelo que intercambió el origen y el destino; antes de cambiar de modelo, pruébalo con tareas pequeñas.

Interrupciones de ejecución y presupuesto (no avanza) ​

"Target changed or is covered. Observe again." ​

Causa: la revisión de seguridad previa a la ejecución detectó que el objetivo cambió: quedó cubierto, oculto, deshabilitado, fuera del viewport, o ya no es el nodo que era al observar. Es el guardián haciendo su trabajo, no un bug: la salida del modelo siempre referencia solo elementos reales observados, y antes de ejecutar se vuelve a verificar su posición geométrica.

Solución: volver a observar y decidir de nuevo. En ejecución automática (sin Slow motion) cada paso avanza por tick, y estos errores de stale se descartan automáticamente con una nueva observación, así que ni los ves; en modo manual paso a paso o con cámara lenta se pausa mostrando el texto original, y basta con pulsar una vez Choose next para decidir de nuevo.

"Page changed since the decision. Choose again." ​

Causa: la familia stale: la página cambió después de tomarse la decisión, y la decisión anterior queda anulada. Variantes de la misma familia: Page changed before text generation. Choose again. (la página cambió antes de escribir), Page changed since this decision. Observe again. (revisión previa a la ejecución), Document changed during evaluation / Document is navigating (la página estaba cambiando durante la observación).

Solución: igual que antes, volver a observar. Dos detalles:

  1. El valor escrito no se genera en vano: solo cuando la entrada del helper de texto permanece exactamente igual, el reintento reutiliza el último valor generado (Reuse an interrupted text request en el README).
  2. Si aparece con frecuencia, significa que la página tiene muchas animaciones o cargas; espera un momento antes de ejecutar o cambia a una página más estable.

"Page did not settle" ​

Causa: en 10 observaciones consecutivas (con intervalos de 20 ms) la página no se estabilizó: las animaciones no paran o sigue cargando.

Solución: espera a que la página se calme antes de ejecutar; algunas páginas pesadas (animaciones al hacer scroll, skeleton screens permanentes) pueden simplemente no ser adecuadas.

Causa: el resultado de ejecutar un <select> nativo no fue confirmado, o la ejecución fue interrumpida (variante del texto original: Dropdown execution was interrupted; inspect before retrying.). El código opta aquí por detenerse de forma conservadora en lugar de reintentar a ciegas: reintentar podría causar una selección duplicada.

Solución: volver a observar (Choose next / reejecutar), para que el agente decida de nuevo basándose en la página nueva.

"Observe and choose before acting" ​

Causa: en modo manual se pulsó Execute choice sin una decisión, o tras obtener la decisión cambió la huella de la página y la decisión ya fue consumida.

Solución: pulsa una vez Choose next para obtener una decisión nueva, y luego Execute choice.

"Stopped at the 60-action demo budget" ​

Causa: se agotó el presupuesto estricto de una sola ejecución: como máximo 60 acciones ejecutadas (MAX_STEPS = 60). Las llamadas de decisión tienen otro límite, 120 (MAX_STEPS × 2); al alcanzarlo se reporta Reached the demo's model-call budget.

Solución: si la tarea es demasiado grande, divídela en partes más pequeñas: el parámetro del ejemplo oficial de examples/run.py se llama precisamente 'A narrow goal', y escribir un objetivo acotado es la recomendación oficial. Si no terminó dentro del presupuesto, normalmente indica que el objetivo era demasiado amplio o que la página no es adecuada (ver el grupo siguiente).

"This run has stopped. Start a fresh demo." ​

Causa: el estado ya es done o blocked y se sigue pidiendo una decisión nueva: esa ejecución ya terminó.

Solución: pulsa Start demo para iniciar una ejecución nueva.

La barra de estado muestra "Stopped · no supported next action" (blocked) ​

Causa: dos orígenes posibles: el modelo eligió activamente BLOCKED (definición de las instrucciones: no hay operaciones compatibles que hagan avanzar la tarea), o durante 3 acciones ejecutadas consecutivas (ninguna de ellas WAIT) la página no cambió en absoluto: el código determina que está atascado y pasa automáticamente a blocked.

Solución:

  1. Mira los últimos 3 pasos del Decision trail: qué se pulsó y por qué la página no cambió.
  2. Contrasta con el grupo siguiente, la «lista de no soportados»: la causa raíz más común de blocked es que la página contiene controles que no se pueden ejecutar.
  3. Acota y concretiza el objetivo, y reinicia el demo.

Resultados incorrectos y límites de página (se desvió) ​

La barra de estado muestra "Jev reports complete · inspect the page", pero la página no es la deseada ​

Causa: el modelo eligió DONE, pero DONE nunca es prueba de éxito: en Evidence and limits lo oficial lo dice sin rodeos: aunque se elija DONE, hay que verificar el resultado de forma independiente. La segunda parte de la barra de estado (inspect the page) es justamente el recordatorio de que lo compruebes personalmente.

Solución:

  1. Para tareas importantes, añade verificación independiente. El ejemplo oficial es examples/flights.py de verify(): verifica en la página de resultados, punto por punto, el trayecto de ida, el origen, el destino, la fecha y la visibilidad de los resultados: no confía en el DONE del modelo; si la verificación falla, sale y reporta Final page did not satisfy the route/date checks.
  2. Escribe con claridad la condición de parada en el objetivo. El objetivo del ejemplo oficial de Flights termina con Stop when …; escribe siguiendo esa fórmula.
  3. Los objetivos del tipo «abrir cierto resultado» requieren especial atención: las instrucciones del modelo establecen explícitamente que «solo encontrar el enlace coincidente no cuenta como completado».

El control no responde al pulsarlo / no aparece en la tabla de elementos (shadow DOM, canvas, subida de archivos…) ​

Causa: te topaste con los límites del MVP. El DOM reader solo reconoce controles HTML y ARIA comunes y no implementa el algoritmo completo de accessible-name. Según la lista oficial de Limits, lo siguiente no está soportado en ningún caso:

No soportadoEjemplos
shadow roots / framescontroles internos renderizados por frameworks de componentes
canvasinteracciones de mapas y lienzos
subida de archivos<input type="file">
apertura de nuevas pestañasenlaces que abren un tab nuevo al pulsarlos
scroll anidadocontenedores con scroll interno
componentes de teclado arbitrariosatajos de teclado, editores de texto enriquecido

Solución: antes de empezar la tarea, coteja la lista y filtra; por ahora no intentes forzar páginas que involucren estos controles (el paso 4 de la lección de principios incluye la misma lista de límites); cambia a una página o tarea que solo contenga controles convencionales. Ten en cuenta además: la pestaña del agente comparte tu perfil de Chrome existente: el estado de sesión afecta al contenido de la página, así que piensa en esto al diagnosticar un «la página no es lo que esperaba».

El texto escrito es incorrecto, o no se escribió el texto que debía ​

Causa: la cadena la infiere el helper de texto a partir del objetivo, no la escribe Jev. Texto incorrecto = el modelo del helper entendió mal el objetivo; si no escribe nada = devolvió {"text": null} según las reglas (cuando el objetivo carece de un valor obligatorio, se niega a inventarlo; véase arriba la entrada nothing typed).

Solución: escribe el valor obligatorio tal cual en el objetivo («September 20, 2026» en lugar de «el mes que viene»); si aún falla, cambia el modelo de texto, sondeando primero con una tarea pequeña — oficialmente fue precisamente con seis llamadas de sondeo como se descartaron los modelos que invertían ciudades y que emitían comentarios (véase interpretación de rendimiento).

Rellena todo pero no envía, escribe texto pero no elige la sugerencia ​

Causa: en las instrucciones del modelo estas reglas están literalmente fijadas: tras rellenar los campos obligatorios hay que enviar («los campos rellenados no equivalen a una búsqueda ya aplicada»), y tras escribir la consulta hay que elegir la sugerencia de autocompletado que coincida. Si no lo hace, casi siempre es un problema de sincronización — tras escribir, el código espera como máximo 200 ms a que aparezca la sugerencia, y en sitios donde las sugerencias cargan lento puede que no llegue a la siguiente observación.

Solución: volver a ejecutar tal cual suele bastar; si sigue atascado en el mismo punto, escribe el objetivo con más precisión (qué enviar, dónde detenerse) o cambia a una página cuyas sugerencias carguen rápido.

¿Sigue sin funcionar? ​

Primero aísla, luego recopila evidencia y, por último, pregunta llevando la evidencia.

La herramienta de aislamiento son los dos scripts incluidos en el repositorio (ambos en scripts/, de la sección Development del README):

bash
# 只测浏览器执行层:本地页面、不调用模型、不花钱
uv run python scripts/check_guards.py

# 测完整链路:浏览器只开本地 fixture 页面,但会发起真实模型调用(产生付费 API 费用)
uv run python scripts/smoke.py

check_guards.py pasa, smoke.py también pasa, pero el sitio web real falla — el problema probablemente esté en ese sitio en sí (límites de controles, tiempos de carga); consulta la lista de no soportados.

Recopila evidencia, con tres cosas basta:

EvidenciaCómo obtenerlaQué contiene
Trace de decisionesEn la parte inferior del inspector, el botón Export trace ↓Descarga typesafe-browser-trace.json: historial completo de decisiones, probabilidades, objetivo, URL de la página y texto visible (sin capturas)
Qué vio el modeloSección plegable de la página What the model seesEl cuerpo completo de la petición enviada al modelo, consultable campo por campo
Texto original del errorLa frase del recuadro rojoTodos los H4 de esta página coinciden

⚠️ Revísalo antes de enviar

El trace contiene la URL de la página y el texto visible, que puede incluir información de tu cuenta; ten en cuenta además: el ejemplo live y los scripts de grabación generan llamadas de API de pago (palabras textuales del README), así que sé consciente de ello antes de reproducirlo repetidamente.

Dónde preguntar:

CanalCuándo acudir
Esta lección + instalación y ejecuciónAutocompruébalo dos veces primero; la mayoría de los problemas no llegan a este punto
resolución de problemas iniciales / referencia rápida de APIproblemas de códigos de estado del lado de la API de TypeSafe
GitHub IssuesDefectos de Ultrafast en sí: incluye trace + texto del error + objetivo y URL
TypeSafe DiscordProblemas del lado de la API de decisiones (Jev); los oficiales dicen que si está roto, repórtalo directamente
Browser Use CloudProblemas al usar la versión alojada de BU Ultrafast (model: "bu-ultrafast")

Punto de control ✅ ​

  • 60 segundos: he ejecutado los cuatro comandos de verificación rápida y sé en qué capa se atasca
  • Distingo tres tipos de errores: los stale se autocuran, 429/529/503 se reintentan automáticamente, y configuración/presupuesto/límites requieren intervención manual
  • Con estado done no doy por terminado sin más — a las tareas importantes les añado una verificación independiente (el verify() de flights.py es el modelo a seguir)
  • He repasado la lista de no soportados: shadow DOM, frames, canvas, subidas, pestañas nuevas, scroll anidado, componentes de teclado
  • Al preguntar incluyo typesafe-browser-trace.json, el texto del error, el objetivo y la URL

Resumen de la lección ​

✅ Para depurar, primero determina la capa: servicio local → conexión de Chrome → llamada al modelo → ejecución de decisiones; los errores de cada capa tienen aspecto distinto.

✅ Todos los textos de error de jev-ultrafast provienen del código fuente del repositorio y se pueden buscar palabra por palabra; los títulos H4 son el texto literal del error: cópialos para buscar o preguntar.

✅ Tres tratamientos: los de tipo stale se dejan a la reobservación automática, 429/529/503 se dejan al reintento del código, y solo los de configuración/presupuesto/límites requieren que actúes.

✅ DONE no es prueba de éxito, con blocked consulta primero la lista de no soportados, y las 60 acciones son un presupuesto estricto — con estas tres reglas en mente, la mitad de los «descarrilamientos» se pueden evitar por adelantado.

Referencia rápida de señales clave:

SeñalEn qué capaPrimer paso
Cannot reach local demo server / ForbiddenServicio localVuelve a ejecutar uv run jev; abre 127.0.0.1:8766
El panel no se mueveConexión de Chromeuv run browser-harness --doctor, permite la depuración remota
TYPE_TEXT needs TEXT_MODEL_API_KEYLlamada al modelo (lado de texto)Completa la Key en .env; atención a cwd y setdefault
Model provider returned HTTP 401Llamada al modelo (Key no válida)Primero distingue si es TypeSafe o el modelo de texto, y luego vuelve a copiar la Key
Model provider returned HTTP 429/529/503Llamada al modelo (limitación/sobrecarga)Espera un poco y vuelve a ejecutar; comprueba la cuota
Target changed or is coveredEjecución de decisiones (stale)Reobserva; en modo automático se autocura
Stopped at the 60-action demo budgetEjecución de decisiones (presupuesto)Escribe objetivos más acotados y divide las tareas en partes pequeñas
Estado done pero el resultado es incorrectoVerificación del resultadoComprobar personalmente; añadir una verificación independiente al estilo de flights.py
Estado blockedLímites de la páginaConsultar la lista de no soportados, cambiar de página o modificar el objetivo

Vista previa de la próxima lección ​

Con esto termina la parte sobre navegadores. La próxima lección Jev 1.13 Manual de trampas: 9 modos de fallo y enfoques alternativos vuelve al modelo Jev en sí; fuera de Ultrafast, es aplicable a todas las aplicaciones Jev. Aprenderás:

  • Los 9 modos de fallo de la documentación oficial de jaggedness: interpretación literal, conteo aritmético, comparación de fechas, referencia indirecta…
  • El enfoque alternativo para cada modo de fallo: la aritmética al código, extraer componentes de las fechas, filtrar primero los state grandes
  • Cómo estos hábitos de formular preguntas retroalimentan tus objetivos al escribir en Ultrafast y otras aplicaciones Jev

Tutoriales relacionados ​

Apéndice: referencia del código fuente ​

Haz clic para expandir y ver las ubicaciones del código fuente

Última actualización: 2026-11-04 (repositorio github.com/browser-use/jev-ultrafast, fuente de información local sources/jev/repo-ultrafast/)

FunciónRuta del archivoUbicaciones clave
Texto original del error: conexión/HTTP/reintentosjev_ultrafast/model.pyL15–27 post_json (L20 fallo de conexión, L21–23 reintento automático ante 429/529/503, en total 3 intentos, L25 plantilla de código de estado HTTP, L27 texto de respaldo «Model unavailable», inalcanzable con el flujo de control actual); L12 timeout=25 del cliente
Texto original del error: validación de la respuesta de decisiónjev_ultrafast/model.pyL30–45 validate_choice (L44 Invalid TypeSafe response)
Texto original del error: helper de textojev_ultrafast/model.pyL160–198 field_text (L163 texto original de Key faltante, L187–193 validación del contrato JSON, L193 nothing typed)
Solicitud TypeSafe y lectura de Keyjev_ultrafast/model.pyL119 (api.typesafe.ai/v1/systemone + os.environ["TYPESAFE_API_KEY"], lanza KeyError si falta)
Texto original del error: presupuesto y máquina de estadosjev_ultrafast/agent.pyL74 detenido, L75–76 presupuesto de llamadas al modelo (MAX_STEPS×2=120), L88–89 observar antes de ejecutar, L96/L107–108 texto original de stale, L102–104 presupuesto de acciones 60, L153–158 3 veces consecutivas sin cambios→blocked
Texto original del error: stale y guardas de ejecuciónjev_ultrafast/browser.pyL86 Page did not settle, L102 la página cambió antes de la ejecución, L130–131/L162–163 desplegable sin confirmar o interrumpido, L164 objetivo sobrescrito; L16 StalePage(ValueError)
Texto original del error: servicio demojev_ultrafast/demo.pyL16 puerto (configurar TYPESAFE_DEMO_PORT antes de iniciar), L23–29 lectura de .env (cwd + setdefault), L48–52 escenarios y caracteres 1–2000, L64–65 Start a demo first, L111–112 bloqueo de paso único 409, L122–123 respaldo 500
Barra de estado del inspector y visualización de erroresjev_ultrafast/static/app.jsL63 Paused · needs attention, L82–88 cinco textos de estado, L173–183 bucle automático (auto-sanación por tick vs pasos lentos), L217–235 exportación de trace (sin capturas), L243 Cannot reach local demo server
Botones de la interfaz y secciones plegablesjev_ultrafast/static/index.htmlL56–59 Choose next / Execute choice / Run automatically / Pause, L126 Export trace ↓, L133 What the model sees
Instrucciones del modelo (DONE/BLOCKED/envío/reglas de sugerencias)jev_ultrafast/questions.pyL3–14 NEXT_ACTION, L21–24 TEXT_VALUE (devuelve null si falta un valor, no inventa datos personales), L26 MAX_STEPS = 60
Instalación, --doctor, depuración remota, lista de limitacionesREADME.mdL53–68 Try it (incluye uv run browser-harness --doctor), L118–126 Evidence and limits (DONE requiere verificación independiente; shadow roots/frames/canvas/subida de archivos/nueva pestaña/scroll anidado/componentes de teclado no compatibles; la pestaña usa el perfil de Chrome existente), L128–138 Development (check_guards, aviso de pago)
Lista de limitaciones (texto original de Limits)docs/performance.mdL53–55; L49 detectar modelos rechazados (escribir ciudades al revés / generar comentarios de salida)
Ejemplo de verificación independienteexamples/flights.pyL18–38 verify() verificación punto por punto, L63–64 Final page did not satisfy the route/date checks
Script local de regresión de guardasscripts/check_guards.pyL1 docstring (No model calls or external websites), L133 impresión al final PASS: N browser guard checks; no model calls
Script local de prueba de humo con fixturesscripts/smoke.pyL1 docstring (API de pago), L19 --max-actions (por defecto 15), L25 imprime el directorio de trace
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.