Puente de depuración con IA

La IA es potente leyendo todo el código y formulando hipótesis, pero no puede observar el runtime directamente. Por eso la depuración se convierte en una lenta carrera de relevos: “la IA conjetura → la persona ejecuta → la persona copia/pega el error → la IA vuelve a conjeturar”.

El Puente de depuración con IA saca a la persona de esa carrera. Si insertas en el código una línea de depuración estructurada estándar (@BLYCK@ {json}), Blyck absorbe los flujos de salida de todos los objetivos y se los da a la IA en un formato unificado. La depuración pasa a ser “la IA diseña un experimento → ejecuta → observa directamente los resultados estructurados → corrige.” Es común para web·escritorio·móvil·consola.

Por qué es necesario

Problema de la depuración por logs tradicional	Contenido
Lento	La IA conjetura → la persona ejecuta → la persona copia/pega el error → la IA vuelve a conjeturar (la persona queda en medio del relevo)
Con pérdidas	Solo se copia/pega parte de la consola; los bugs intermitentes no se capturan en ese instante
No estructurado	La IA parsea por conjetura trazas de pila en crudo / logs mezclados
Distinto en cada plataforma	Consola web / logcat / os_log / stdout … el enfoque es distinto en cada caso

La idea clave es una sola pregunta — “¿La salida de esa app fluye hacia un flujo de texto que Blyck posee (PTY·terminal·SSH·logcat·archivo de log)?” En la mayoría de los casos la respuesta es “sí”, y para la única excepción —la consola del navegador— Blyck ya dispone de un conducto.

Formato de cable — línea de depuración estructurada

Con independencia de la plataforma, es marcador + JSON en una sola línea.

@BLYCK@ {"label":"after-add","vals":{"qty":3,"total":null},"level":"debug","loc":"cart.js:42"}

Campo	Obligatorio	Descripción
label	✅	Nombre de la sonda
vals		Valores a observar (objeto). Si no es un objeto, se envuelve en {value:…}
level		debug · info · warn · error · assert (predeterminado debug)
loc		archivo:línea (opcional)

Blyck estampa en el momento de la captura

ts (marca de tiempo) · source (terminal/preview) · sessionId no se incluyen en el cable. Blyck los añade en el instante en que captura el log (evita diferencias de reloj·entorno). Como el marcador @BLYCK@ lo distingue de los logs normales, el parser lo identifica con precisión, y aunque el JSON esté roto, se conserva con level:warn + el texto original (raw) para evitar pérdidas.

API de helpers — dos funciones que insertas en el código

Solo hay dos conceptos.

• blyckDbg(label, vals) — emite valores (sonda).
• blyckAssert(cond, label, vals) — verifica una suposición y, si se rompe, emite un evento level:"assert".

La herramienta debug_shim(lang) devuelve un thin shim (de ~5 líneas cada uno) para 11 lenguajes — js/ts · python · bash · go · rust · java · csharp · dart(flutter) · kotlin · swift · c. Todos proporcionan dbg + assert.

Desactivación automática en releases

Cada shim se mapea al mecanismo nativo exclusivo de depuración de su lenguaje (JS if (BLYCK_DEBUG) DCE, Python if __debug__:, build tags de Go, Rust cfg(debug_assertions), Swift #if DEBUG, Kotlin BuildConfig.DEBUG, etc.). En las compilaciones de release se eliminan/desactivan automáticamente, por lo que el coste en runtime es cero. → Consulta Compuerta de despliegue.

Captura — dos pipes, un buffer

Pipe A — parser común de los flujos que Blyck posee

De todos los flujos de texto que Blyck arranca o conecta —PTY del terminal · shell SSH · adb logcat, etc.— se extraen y parsean las líneas @BLYCK@ {json} y se guardan en un ring buffer estructurado (límite 1000, FIFO). La salida normal que no es de sonda fluye hacia el parsing de marcadores de error de Run & Observe (separación de roles).

Pipe B — consola del navegador

La consola del navegador atrapada dentro del webview la recibe la recolección de consola de Live Preview y se normaliza al mismo buffer. También desde el lado del navegador basta una línea console.log("@BLYCK@ …").

→ Como los dos pipes confluyen en el mismo buffer, el formato que ve la IA es idéntico sea cual sea el objetivo.

Flujos de log por plataforma

Lo que llamamos “adaptador de plataforma” en realidad es solo redirigir el log de esa plataforma hacia el terminal de Blyck. Basta con tener el flujo visible en el terminal para que los @BLYCK@ se recojan automáticamente.

Objetivo	Log al flujo de Blyck	Procesamiento
Consola / CLI / backend	stdout/stderr del terminal	Pipe A
Android	adb logcat	Pipe A
iOS	idevicesyslog / os_log	Pipe A
Flutter	flutter run o flutter logs (móvil·escritorio unificado)	Pipe A
Remoto (SSH)	Salida del shell SSH	Pipe A
Lado servidor web (SSR·servidor dev)	stdout del proceso	Pipe A
Consola del navegador web	webview console	Pipe B

Herramientas de IA (MCP) — 5

Herramienta	Permiso	Rol
debug_read(filter?)	Lectura (auto)	Lee directamente los eventos de depuración estructurados (0 copiar/pegar humano). filter: label·level·loc·source·sessionId·paneId·sinceTs·sinceSeq (sondeo incremental)·limit
debug_shim(lang)	Lectura (auto)	Devuelve el código fuente de los helpers blyckDbg/blyckAssert por lenguaje (incluye guarda no-op automática en release)
debug_probe(path, line, label, expr)	Confirmación	Inserta una línea de sonda @BLYCK@ con formato garantizado en archivo:línea (js/ts·python·dart·bash, local)
debug_release_check(path)	Lectura (auto)	Escaneo recursivo del directorio → informa de las ubicaciones de @BLYCK@ restantes (marca removable)
debug_strip(path)	Confirmación	Elimina en lote solo las sentencias de salida @BLYCK@ (local, triple red de seguridad)

El valor de debug_probe

La clave de debug_probe es la garantía de formato que evita el accidente de “la IA escapa mal a mano y debug_read no lo captura”. Inserta con precisión una sola línea para una captura rápida y puntual, incluso sin helpers.

Dos modos de funcionamiento

La recolección es completamente en tiempo real (al buffer en cuanto llega el flujo). La IA reacciona de dos maneras.

Modo A — bucle de depuración activo (durante el trabajo)

Dentro de un mismo turno: insertar sondas → ejecutar la app → debug_read en vivo → decidir → corregir → reejecutar → reobservar. La persona sale del relevo de errores y la IA hace ella sola el bucle de editar·ejecutar·observar·corregir. La clave para acabar con el ensayo y error.

Modo B — investigación automática (cuando la app se ejecuta y revienta)

Cuando llega un @BLYCK@ con level:error o assert, la IA, sin que se le pregunte, se incorpora automáticamente al chat activo e investiga la causa. Es como “un punto de interrupción que llama a la IA cuando se rompe un invariante de runtime”.

El modo B está OFF por defecto — un turno automático de IA cuesta

La investigación automática tiene un coste en tokens, por lo que está envuelta en 4 capas de seguridad y desactivada por defecto.

1. OFF por defecto (opt-in) — Solo se activa con la casilla del panel de configuración de IA o el botón 🔔 del panel de depuración en vivo (la configuración persiste)
2. Límite de tasa global — Máximo 3 por cada 60 segundos
3. Supresión de duplicados — La misma combinación label+loc tiene un cooldown de 120 segundos
4. Solo cuando está inactiva — Si la IA está respondiendo, se omite (el evento permanece en el buffer)

La IA no observa el flujo constantemente

La IA no examina los logs a cada instante. Los mira dentro del bucle de trabajo (modo A) o cuando un evento la despierta (modo B). No gastar tokens en salida ociosa es, de hecho, más eficiente.

Panel de depuración en vivo

Se alterna con Ctrl+Shift+D. Muestra el flujo estructurado @BLYCK@ en tiempo real y ofrece filtros por label · loc · level · source, pausar·limpiar y el toggle 🔔 de investigación automática (modo B).

Como la persona ve el mismo buffer que lee la IA, “qué está observando y corrigiendo la IA ahora mismo” queda expuesto de forma transparente, junto a la ventana de conversación.

Escenario — bug del total del carrito

1. Usuario: “Arregla el bug del total del carrito”
2. IA: inserta blyckDbg('after-add', {qty, total}) · blyckAssert(total > 0, 'total-positive', …) en los puntos sospechosos
3. IA: ejecuta la app (terminal o vista previa) → observa el flujo con debug_read en vivo
4. El assert se rompe → la IA ve íntegros los valores·ubicación de ese instante → corrige al momento → reejecuta
5. El usuario observa en tiempo real en el panel de depuración + la ventana de conversación
6. Listo → al desplegar, las sondas se desactivan automáticamente

Compuerta de despliegue — que no quede ni rastro de las sondas

Principio: las sondas son solo para desarrollo y, al desplegar, se convierten en no-op/se eliminan automáticamente. Sin limpieza manual.

1. Flags de release (NODE_ENV=production · python -O · eliminación de build tags · NDEBUG …) → el shim se compila al mecanismo de depuración nativo y se desactiva automáticamente. Aunque quede el marcador, no se ejecuta en release — la red de seguridad más importante.
2. debug_release_check(path) — escaneo recursivo que informa de las ubicaciones de @BLYCK@ restantes e indica en cada línea si es una sentencia de salida (objetivo de eliminación).
3. debug_strip(path) — ejecuta la limpieza. Triple red de seguridad:
   • Elimina solo las sentencias de salida — únicamente las líneas donde @BLYCK@ está dentro de una llamada print/log/console. Se conservan comentarios·constantes de cadena·documentación·llamadas a helpers
   • Conserva los archivos de definición del shim — si se borraran las líneas de salida internas del helper, el archivo se rompería, así que se omite entero
   • Guarda contra truncamiento — los archivos grandes que se cortaron al superar el tope de lectura se perderían al reescribirlos, así que se omiten

Por qué el no-op es lo predeterminado

Lo predeterminado es el no-op protegido (desactivación), no debug_strip (eliminación). Porque con solo activar el flag puedes revivir las sondas para depurar en producción.

Limitaciones

• debug_probe (inserción automática) admite actualmente solo archivos locales + js/ts·python·dart·bash. Para lenguajes compilados (go·rust·java·c#, etc.) y archivos remotos (SFTP), adjunta los helpers directamente con debug_shim.
• De los 11 shims, 8 (js·python·bash·go·rust·java·csharp·dart) se han verificado con compilación·ejecución reales; c·kotlin·swift solo pasaron una inspección de salida por falta de toolchain de compilación.
• La IA no observa el flujo de forma permanente (solo en los modos A·B). El modo B (investigación automática) está OFF por defecto; al activarlo, considera el coste en tokens.
• Para que el marcador no se rompa, emite solo JSON puro tras @BLYCK@ (por ejemplo, si en PowerShell se cuelan restos de comillas, se conserva con un aviso de malformed).

Preguntas frecuentes

P. ¿Tengo que copiar la salida de la consola y dársela a la IA? → No. Esa es la esencia de esta función. Insertas las sondas, ejecutas la app y la IA lee los valores directamente con debug_read.

P. Lo he ejecutado pero debug_read no lo captura. → La salida debe fluir hacia un flujo de terminal/vista previa que haya arrancado Blyck. La salida de rutas que no se muestran en pantalla (como la ejecución aislada) no la captura el Pipe A. Ejecútalo en el panel de terminal o, en móvil, mantén el flujo adb logcat·flutter logs visible en el terminal.

P. ¿Tengo que borrar las sondas obligatoriamente al desplegar? → Con solo activar el flag de release, el shim se desactiva automáticamente y no se ejecuta. Para limpiar también el marcador por completo, revisa con debug_release_check y luego usa debug_strip.

P. ¿La IA se incorpora por su cuenta cuando la app da un error? → Sí, si activas el modo B (investigación automática). Está OFF por defecto y se activa con la casilla del panel de configuración de IA o el botón 🔔 del panel de depuración en vivo (Ctrl+Shift+D).

P. ¿Funciona también con móvil/Flutter? → Sí. Si mantienes el flujo de logs visible en el terminal de Blyck, los @BLYCK@ de la app del dispositivo se recogen automáticamente — Android adb logcat, iOS idevicesyslog, Flutter flutter run/flutter logs. (Para objetivos web, la consola del navegador = Pipe B)