dsh-browser-cdp — El navegador del agente visible (conexión CDP)

简体中文 | Français | Deutsch | Italiano | Русский | Español

Repositorio: github.com/drscrewdriver/dsh-browser-cdp ｜ Historial de versiones: ver CHANGELOG.md

Matriz de compatibilidad de versiones

Dependencia	Versión mínima	Versión recomendada	Notas
DSH (DeepSeek Harness)	0.2.0-rc.1	≥ 0.2.0-rc.1 <0.2.1-0	Línea 0.2.0: las peer dependencies están fijadas de forma sincronizada en >=0.2.0-rc.1 <0.2.1-0; el host mantiene retrocompatibilidad con la API de plugins (el composer/forkSession de 0.2.0 es una extensión de firma, el plugin es solo llamador, sin cambios necesarios). La superficie de ajustes declarativa introducida desde 0.1.7 (campos Config .volatile() que generan automáticamente el formulario de ajustes) continúa en 0.2.0. Para DSH 0.1.2-rc.1 ~ 0.1.7 use la línea 0.17.x; para 0.1.0-rc.x / 0.1.1-rc.x use v0.8.0 o anterior
dsh-better-sidebar	0.12.2 (opcional)	≥ 0.17.1	Sin él, retroceso automático a la esfera de observación flotante; < 0.12.2 funciona pero la intercepción de enlaces externos (urlTarget) se degrada en silencio
Node.js	22	—	Incluido con el entorno del harness

Notas de adaptación a todas las versiones de DSH: esta versión (desde v0.18.0, línea 0.2.0) apunta a DSH 0.2.0-rc.1+: respecto a la línea 0.1.7 (v0.17.x) cero cambios de código, mero relevo de dependencias/metadata — el host 0.2.0 es retrocompatible con la API de plugins, y este plugin entrega las selecciones mediante la fachada ctx.get('conversation').input (sin llamar a submit(), sin override), quedando fuera del alcance de los cambios de 0.2.0. La superficie de ajustes declarativa, introducida en 0.1.7, funciona así: el plugin ya no registra ninguna sección de ajustes (la API de registro ctx.settings fue eliminada por el host); en su lugar, los campos configurables se marcan con .volatile() en el esquema Config y la página de ajustes del host genera el formulario automáticamente; los cambios en los campos volatile surten efecto en caliente mediante el evento loader/volatile-update, sin recargar el plugin. Las API esenciales del host (defineTool, ctx.tools.register, ctx.subprocess.spawn, ctx.webServer.register, ctx.inject, la fábrica CJS ModuleLoader, cordis.patch.yml) conservan su forma desde 0.1.2. Para DSH 0.1.2-rc.1 ~ 0.1.7 use la línea 0.17.x.

Notas de adaptación a dsh-better-sidebar: este plugin registra una pestaña en la barra lateral y escucha los enlaces externos mediante el servicio ctx.betterSidebar (obtenido de forma defensiva con try-catch). Versiones de introducción de las API clave:

API	Uso en este plugin	Versión de introducción en better-sidebar
registerTab() / openTab() / ctx.betterSidebar	Registro + apertura de pestaña	v0.9.0+
TabDescriptor.single	Pestaña de instancia única	v0.9.0+
TabDescriptor.urlTarget	Intercepción de enlaces externos	v0.12.2+ (por debajo, la intercepción de enlaces falla en silencio)

---

Detalles del soporte de versiones de DSH: cambios principales de v0.8.2 → v0.8.3: fusión de 6 PR comunitarios (adaptación root/xvfb/macOS headless, compatibilidad rc.1, estabilidad Windows), corrección de la vulnerabilidad de rutas /api/bcdp/* sin autenticación, del fallo de arranque del cliente en hosts sin dsh-better-sidebar (#29), de la regresión de arranque en frío en Windows (falsa detección de Xvfb introducida por #22) y la carencia de runtimeArgs/chromeArgs en la lista blanca de ajustes de la pasarela. Puntos de adaptación: renombrado del runtime cliente (@deepseek-ai/dsh-client-store), id de registro del módulo cliente y nombre de la línea de carga según el nombre del paquete declarado, dsh.client.inject que declara solo las líneas reales del grafo de módulos, webServer entregado mediante inyección anidada (servicio opcional) y sincronización con el modo pestaña de barra lateral (dsh-better-sidebar).

Soporte de barra lateral (dsh-better-sidebar): cuando el host tiene instalado dsh-better-sidebar (recomendado ≥ v0.12.2), la ventana de observación en tiempo real se registra como pestaña nativa de la barra lateral — «Navegador del agente» aparece en el menú «+» de la barra lateral, se abre con un clic y queda anclada junto al cajón de la barra lateral; la pestaña se abre automáticamente en la primera llamada del agente a una herramienta bcdp_* (desde v0.8.5 la apertura se acota a la sesión llamante — en multi-sesión ya no aparece en la sesión equivocada). Sin dsh-better-sidebar se retrocede automáticamente al modo esfera de observación flotante en la esquina inferior derecha (#dsh-ego-fab). Ambas formas comparten el mismo conjunto de capacidades: streaming SSE en tiempo real / clic / entrada / captura de descargas. La ventana de observación ofrece además un botón «Pop-out»: el navegador del agente en ejecución headless se sustituye con un clic por una ventana con interfaz del mismo Profile (se conservan las pestañas), útil para tomar el control manualmente.

Importación del estado de sesión (novedad en v0.8.5): la herramienta bcdp_login_import copia por dominio las cookies de sesión de tu Chrome/Edge/Brave cotidiano al navegador del agente (arranque headless del binario real + lectura transparente vía CDP, compatible con la App-Bound Encryption de Chrome 127+, sin descifrado offline; si el navegador de origen está en marcha se puede cerrar con elegancia antes de importar, la ventana se restaura en el siguiente arranque). Los valores de las cookies no aparecen en ningún registro ni salida; antes de importar, la base de cookies de origen se respalda automáticamente y se restaura ante un vaciado anómalo. Combinado con el Profile persistente en disco por defecto, el estado de sesión importado sobrevive a los reinicios de forma permanente.

Un proxy de navegador CDP: incorpora una runtime compatible con ego (un Chromium para agentes de IA; procedencia y licencia en THIRD_PARTY_NOTICES.md) en el DeepSeek Harness, maneja el navegador con 38 herramientas estructuradas bcdp_* y lo acompaña de un frontend de observación en tiempo real — mientras el agente opera páginas en segundo plano, ves cada página que visita como una retransmisión en directo y puedes incluso intervenir directamente.

Una particularidad propia (self-observation): el agente usa precisamente este Chromium — incluso cuando maneja el propio DSH (gestión de sesiones, tablero de tareas, ajustes), la ventana de observación lo muestra en directo y puedes tomar el control en cualquier momento. No se trata solo de «ver al agente trabajar en la web»: hasta la manipulación de la propia interfaz de DSH por parte del agente es íntegramente visible y controlable.

Listo para usar: el paquete del plugin incorpora una runtime compatible con ego (runtime/, MIT de terceros, ver THIRD_PARTY_NOTICES.md) — sin navegador adicional, sin compilar a mano; el wrapper --no-sandbox viene con el paquete: root / Docker / máquinas sin pantalla arrancan en un paso.

---

Nuestras verdaderas ventajas (no eslóganes, sino capacidades verificables en el código y frente a la competencia)

Otros plugins que conectan ego a DSH sacan de él solo 3 herramientas — un script run, una guía help, una comprobación status — y el navegador sigue siendo una caja negra en segundo plano. Este plugin sigue otro camino: abrir la caja negra y, desde el primer momento, dar plenamente las capacidades de «ver» y de «controlar».

Capacidad	Este plugin (este repositorio)	Plugin similar
Número de herramientas estructuradas	38, responsabilidad única, invocación determinista	3 (run/help/status)
Ventana de observación en tiempo real (doble backend CDP JPEG / FFmpeg H.264 + barra de pestañas + cajón de historial)	✅ Sí	❌ No
Manipulación directa con el ratón del navegador real desde la ventana de observación (clic/arrastrar/scroll devueltos al CDP)	✅ Sí	❌ No
Selección de un elemento en la ventana de observación → captura y referencia en el campo de entrada de la conversación (bloque estructurado [CDP-PICKS], señalización manual del objetivo)	✅ Sí	❌ No
Guardia de instancia única del worker + autorreparación ante cuelgues/duplicados	✅ Sí	❌ No
Captura de descargas bcdp_download / detección de captchas bcdp_captcha/bcdp_page_info	✅ Sí	❌ No
Adaptación a plataformas (detección automática Linux/macOS/Windows + retrocesos root/headless/--no-sandbox)	✅ Todas las plataformas	Solo host de vista previa Windows, configuración manual
Persistencia en disco del estado de sesión bcdp_auth_flush	✅ Sí	⚠️ Solo mención a nivel de documentación

Tres diferencias clave:

• Ver: en otros casos es una caja negra que «al terminar te cuenta el resultado»; nosotros retransmitimos en directo — ves al agente operar y detectas al instante si se atasca en un captcha o toma un mal camino.
• Controlar: en otros casos solo lectura; nuestra ventana de observación maneja directamente el mismo navegador del agente — si hace falta, tomas tú el control (zoom/arrastrar/clic), sin interrumpir al agente ni empezar de nuevo.
• Señalar con precisión: seleccionas un elemento de la página en la ventana de observación; el plugin captura su backendNodeId/tag/id y descripción semántica, y lo incorpora como bloque estructurado [CDP-PICKS] al borrador del campo de entrada de la conversación (las selecciones múltiples en una misma página se fusionan y numeran automáticamente) — el agente recibe un objetivo exacto, sin tener que adivinar «a qué botón te refieres».

La comparación anterior se basa en hechos públicos verificables: el código de este repositorio (bin/cdp-cast-worker.mjs streaming en tiempo real + devolución de entradas CDP, lib/index.js con 38 herramientas registradas, lib/cast-server.js puente hacia el host, deliverPickToConversation en lib/client.js para las referencias de selección) y el código fuente/README públicamente visible del plugin similar. Este documento no menosprecia a nadie — solo afirmamos qué capacidades hemos implementado y verificado además.

Frente a la propia runtime incorporada (un CLI headless), esto es lo que añadimos (todo verificable en el código de este repositorio):

Capacidad	Descripción (código correspondiente)
Frontend de observación	La runtime incorporada por sí sola es un CLI headless (solo scripts heredoc + salida textual); le hemos añadido streaming SSE en tiempo real + barra de pestañas + cajón de historial + manipulación directa con el ratón desde la ventana de observación + selección de elementos con referencia en el campo de entrada (bin/cdp-cast-worker.mjs, lib/cast-server.js, createPickControl/deliverPickToConversation en lib/client.js), convirtiendo «ver», «controlar» y «señalar» en capacidades de primer orden
Listo para usar + autosuficiente en todas las plataformas	resolveEgoEnv detecta automáticamente Chrome/Edge/Brave, wrapper --no-sandbox incorporado, cero configuración bajo root / Docker / sin pantalla (lib/index.js); no hace falta instalar antes un host GUI
Capa de robustez	Reintentos automáticos en el arranque en frío (solo se reintentan fallos CDP transitorios, los errores reales no se tragan), guardia de instancia única del worker + reinicio automático tras cuelgue, teardown del plugin en fire-and-forget sin bloquear la salida del host, techo del caché de fotogramas en el frontend (withWarmupRetry / makeEnsureWorker / frameCache)
Herramientas de operación	bcdp_doctor (diagnóstico del entorno), bcdp_captcha (detección de captchas), bcdp_auth_flush (persistencia de sesión), bcdp_login_import (importación de sesión desde el navegador del sistema), bcdp_http (peticiones en el contexto del navegador), etc. — una capa que los helpers CLI nativos no ofrecen
self-observation	Incluso cuando el agente maneja la propia interfaz de DSH, todo es visible en directo y se puede tomar el control

No pretendemos igualar los snapshots a nivel de kernel ni la experiencia multiwindow nativa de la app de macOS; este repositorio resuelve: «traer las mismas capacidades de navegador a DSH + Linux/WSL — y hacerlo visible».

---

Qué problema resuelve

Los navegadores genéricos no están pensados para agentes, y gran parte de las interacciones web (estados de sesión, captchas, renderizado dinámico, formularios, sitios que exigen sesión humana) solo pueden afrontarse con un navegador real — es la intención de ego: «dejar que el agente use tu navegador ya con sesión iniciada, sin molestarte», que este plugin lleva a DSH.

Este plugin lo conecta a DSH y resuelve el punto más doloroso — no ves lo que hace el agente ni puedes intervenir — con una ventana de observación:

🌐 Un clic en la bolita abre la retransmisión; 🟦 barra de pestañas para cambiar/cerrar; 🕘 cajón de historial para revisar; 🔍 zoom y desplazamiento; 🖱️ toma de control directa del navegador real desde la ventana. En una frase: el agente trabaja en el navegador, tú lo ves todo y puedes tomar el control en cualquier momento.

Algunos escenarios típicos de arranque

• Documentación / recolección de datos: pide al agente que entre en CNKI / Google Scholar y recolecte página a página; desde la ventana de observación lo ves desplazarse, pulsar «siguiente página», descargar PDFs — si se atasca por el camino, te das cuenta al momento.
• Formularios y sesiones: el agente rellena un formulario a medias, en la ventana de observación aparece un captcha — tomas el control, resuelves el captcha y devuelves el mando al agente para que continúe.
• QA / pruebas de humo: pide al agente que recorra con clics tu propio producto; la ventana de observación se convierte en una «grabación de pantalla que habla», con el añadido del repaso del historial.
• Ver al agente manejar el propio DSH (self-observation): cuando el agente gestiona sesiones / ajusta los ajustes, todo es visible en la ventana de observación y puedes intervenir.

---

---

Requisitos previos

Requisito	Notas
Node ≥ 22	Incluido con el entorno del harness
Cualquier Chrome / Chromium / Brave / Edge	Detección automática, o EGO_LINUX_CHROME para indicarlo; bajo root con el wrapper incluido
DSH + dshx	Mecanismo de carga de plugins
DSH Web con interfaz gráfica (para la ventana de observación)	Las sesiones headless siguen pudiendo usar las herramientas bcdp_*, simplemente sin ventana de observación

Instalación

Método 1: instalación directa desde GitHub (recomendado)

dsh plugin --profile web add github:drscrewdriver/dsh-browser-cdp
# También se puede fijar a un commit / tag concreto:
dsh plugin --profile web add github:drscrewdriver/dsh-browser-cdp#v0.9.0

La instalación github: recupera el tarball del repositorio mediante pnpm pasando por codeload.github.com, sin publicar nada en el registro npm; usa directamente el lib/ precompilado y versionado del repositorio (files contiene solo lib/, bin/, runtime/, cordis.patch.yml, dsh-plugin.json), por lo que no se activa ningún script de build y no hacen falta devDependencies. La entrada del host lib/index.js, el cliente lib/client.js y el worker bin/cdp-cast-worker.mjs se distribuyen todos con el repositorio.

Método 2: tarball local / URL git

dshx install dsh-browser-cdp <dsh-browser-cdp.tgz>      # tarball o URL git, ambos válidos
dshx list                                                # debe mostrar: [on] dsh-browser-cdp

Nota sobre el renombrado del paquete: el nombre del paquete de este plugin es dsh-browser-cdp (nombres anteriores: dsh-ego-browser, alias @dsh-external/ego-browser). Desde DSH Desktop 2.0.5 existe una comprobación de coherencia «nombre de dependencia del profile == nombre real del paquete»: si el profile aún referencia el nombre antiguo, el arranque cae en modo de recuperación. Tras actualizar, renombra tanto la clave de dependencia en el package.json del profile como la entrada en dsh.profile.bundles a dsh-browser-cdp:

- "dsh-ego-browser": "<fuente github anterior>",
+ "dsh-browser-cdp": "github:drscrewdriver/dsh-browser-cdp",

- "dsh-ego-browser",
+ "dsh-browser-cdp",

En los ajustes de la ventana de observación se pueden elegir captureBackend=auto|cdp|ffmpeg (por defecto auto, actualmente resuelto a CDP), los niveles de calidad, CDP FPS/calidad JPEG/anchura máxima, así como FFmpeg FPS/anchura máxima/bitrate/codificador/ruta personalizada. El plugin comprueba primero la ruta personalizada, el PATH del sistema y el caché gestionado; la descarga de GitHub puede sustituir https://github.com por githubMirror, por ejemplo https://gh-proxy.com/github.com. El bitrate de FFmpeg va de 500 a 20000 kbps, con valores por defecto 2000/4000/8000 kbps para los niveles bajo/equilibrado/alto.

Sin ninguna configuración del lado del host: resolveEgoEnv detecta automáticamente root / ausencia de pantalla y aplica los retrocesos. Las rutas del host para la ventana de observación (/api/bcdp/spaces etc.) solo se registran si existe un servidor HTTP; en headless son un no-op seguro.

Formas de conexión: endpoint CDP / CLI ego local

La lista de conexiones del panel de ajustes está ordenada — el orden es la prioridad, y el elemento activado gobierna cada llamada bcdp_*. Hay dos tipos de elementos:

Tipo	Qué hace	Restricciones
Endpoint CDP	Pasa la dirección de un navegador con puerto de depuración ya abierto al runtime incorporado (inyección de EGO_LINUX_CDP_URL), que se adhiere a él	Se permiten varios
CLI ego local	El CLI ego de la máquina maneja por sí mismo su navegador ego local — no se inyecta ningún endpoint	Solo máquina local, como máximo uno a nivel global

Por qué existe el segundo tipo: el EGO_LINUX_CDP_URL inyectado es un contrato privado de la runtime incorporada (línea Linux); el ego-browser nativo que acompaña a la app ego lite en macOS simplemente no lo lee. Si «endpoint CDP» fuese el único tipo, los usuarios de macOS no podrían aprovechar su ego ya con sesión iniciada — tendrían que conectarse a un puerto remoto o dejar que la runtime incorporada arrancara un Chromium de stock. El tipo CLI local cierra exactamente esa brecha.

Orden de resolución (con cliPath vacío): ruta explícita → ego-browser en el PATH → helper dentro del paquete de la app macOS (/Applications/ego lite.app/…/Helpers/ego-browser) → runtime incorporada del plugin.

Dos valores por defecto que conviene conocer:

• --sdk-path está desactivado por defecto: por defecto se usa el harness que trae el CLI; solo al activarlo se inyecta el paquete harness de este plugin. Si el CLI no reconoce ese flag, el plugin registra una pista y reintenta automáticamente una vez sin él — toda la cadena no queda por ello inutilizada.
• La sonda de disponibilidad pasa una vez por un heredoc real (el mismo canal usado para el trabajo real), así que no es gratuita: la sonda puede desencadenar el arranque en frío del navegador de fondo (medidos unos 1,3 s con la runtime incorporada).

Relación con otros interruptores:

• cdpMode: auto sigue al elemento activado (ambos tipos valen); remote solo acepta endpoints CDP y avisa explícitamente mode-kind-mismatch si el elemento activado es un CLI local; local va por el lanzador local gestionado.
• remoteEnabled (interruptor general remoto) solo gobierna el CDP remoto, sin efecto sobre las conexiones CLI locales.
• allowLocalFallback / localHeadless / localUserDataDir actúan solo sobre el retroceso de los endpoints CDP y los arranques gestionados.

bcdp_doctor informa del recuento de tipos de la secuencia actual, la ruta realmente resuelta del CLI y su forma, así como (si la antigua dsh-ego-browser está instalada en la misma máquina) un aviso de coexistencia.

Lista de herramientas (38, prefijo bcdp_, índice completo en bcdp_help)

Categoría	Herramientas
Espacios de tareas	bcdp_space (open/close/list/handoff/takeover) bcdp_status
Lectura de páginas	bcdp_snapshot (árbol semántico) bcdp_page_info bcdp_read_element
Navegación/espera	bcdp_navigate (reutiliza la pestaña) bcdp_wait (duration/selector/url/response/load/function/request/event)
Interacción	bcdp_click bcdp_fill bcdp_hover bcdp_drag bcdp_select bcdp_check bcdp_key bcdp_scroll
Ejecución/depuración	bcdp_js (evaluación en la página) bcdp_cdp (CDP crudo) bcdp_script (heredoc; verbatim = raw, no preamble)
Salidas	bcdp_screenshot bcdp_download bcdp_upload
Sesión/seguridad	bcdp_auth_flush (persistencia de sesión) bcdp_login_import (importación de sesión entre navegadores) bcdp_captcha bcdp_dialog
Metaherramientas	bcdp_help bcdp_doctor bcdp_http
Revisión (JEV/Laya, servicio externo de juicio opcional)	bcdp_jev_status bcdp_jev_frame bcdp_jev_ask bcdp_jev_run bcdp_jev_attempt

Cómo usar la ventana de observación

La 🌐 bolita permanente en la esquina inferior derecha → clic para abrir:

• Vista principal: retransmisión en directo de la página actual del agente; clic/arrastrar/rueda actúan directamente sobre la página, Ctrl+rueda para hacer zoom, Ctrl+arrastrar para desplazar, doble clic para restablecer. Tras un clic en la vista se puede escribir directamente con el teclado: IME chino, pegar, Tab/Intro/flechas y atajos Ctrl/Cmd admitidos.
• Selección de elemento (referencia por selección): pulsa el botón de la barra de herramientas para entrar en modo selección y luego haz clic en cualquier elemento de la vista en directo — el plugin captura su backendNodeId/tag/id y descripción semántica, y lo incorpora como bloque estructurado [CDP-PICKS] al borrador del campo de entrada de la conversación; las selecciones múltiples en la misma página se fusionan automáticamente en el mismo bloque y se numeran en secuencia, y el agente las usa con precisión por número. Funciona tanto con la bolita flotante como con la pestaña de la barra lateral.
• Barra de pestañas: fila horizontal arriba, clic para cambiar, × para cerrar.
• Cajón de historial (🕘): repasar la traza de visitas en orden cronológico.
• Durante las acciones, la línea de URL de abajo muestra los avisos en el sitio y se restaura a los 2 segundos.
• Tras cerrar el panel, ocultar la pestaña de la sidebar o desmontar el componente, la producción de imágenes se detiene al terminar la cortesía de 1,5 segundos. Que la ventana de DSH pase a segundo plano por sí sola no detiene el streaming, para evitar reconstruir WGC/FFmpeg repetidamente al volver al primer plano; un cierre anómalo queda cubierto por el plazo de gracia del lease del worker de 120 segundos.

Backends de imagen

• cdp: JPEG vía Page.startScreencast, 20 FPS por defecto. Cada fotograma fuente se acusa inmediatamente (ACK) con el ID de fotograma proporcionado por Chrome; solo se conserva el último fotograma pendiente; solo se captura la pestaña que se está viendo, y las páginas estáticas vuelven por defecto a una captura cada 3 segundos.
• ffmpeg: en Windows gfxcapture(hwnd) captura directamente la superficie D3D11 de la ventana Chrome objetivo; las demás plataformas usan un recorte de la fuente de pantalla. Después codificación H.264 fragmented MP4 → trozos binarios HTTP → MediaSource <video>, sin pasar por Base64/SSE.
• auto: por defecto se elige CDP; si la detección falla, FFmpeg no se descarga automáticamente. FFmpeg solo es seleccionable una vez instalado y superada la comprobación de capacidades; si un backend FFmpeg guardado deja de ser válido, la sesión de observación retrocede a CDP mostrando el motivo.
• En Windows FFmpeg debe incluir gfxcapture. El plugin empareja el HWND mediante el PID del navegador, el título del target y los límites de ventana CDP; la captura de la página objetivo continúa aunque la ventana se mueva o quede tapada, y está prohibido retroceder a la grabación del escritorio. Si el target es una pestaña en segundo plano de la misma ventana Chrome, se emite un error explícito en lugar de mostrar la pestaña visible o robar el foco. En macOS se necesita el permiso «Grabación de pantalla» en el primer uso; en X11 Chromium y FFmpeg deben compartir el mismo DISPLAY; en Wayland, ante la falta de entrada Portal/PipeWire, aparece un aviso para volver al CDP.

La instalación gestionada de FFmpeg va a ~/.dsh/cache/ego-browser/ffmpeg/, sin escribir nada en el directorio del plugin. Windows/Linux usan un tag de release BtbN fijo; macOS usa assets fijos del release de GitHub ffmpeg-static (sus binarios Intel/Apple Silicon proceden respectivamente de Evermeet/OSXExperts). Todas las descargas fijan el SHA-256 del recurso; solo se extrae el ejecutable principal de FFmpeg, sin instalar ffprobe ni ffplay. En Windows/Linux el desempaquetado usa el tar del sistema; si falta, aparece un error explícito antes de la descarga.

Nota sobre el estado de sesión: las cookies de los espacios de tareas están aisladas entre sí — inicia sesión en el espacio correspondiente. Tras reiniciar DSH, el estado de sesión en ejecución se borra (las cookies de ejecución de Chrome solo se escriben en disco al cerrar con elegancia), hará falta volver a iniciar sesión — escanear el código QR es rápido.

Cómo funciona

• Capa de herramientas: cada herramienta arma sus parámetros en un script JS, que se entrega por stdin a ego-browser nodejs mediante ctx.subprocess, con el host manejando el Chromium compartido vía CDP. Los resultados se analizan gracias a la línea centinela @@DSH_RESULT@@. Todos los bcdp_* se serializan con un mutex dentro del proceso, los errores se normalizan de forma uniforme.
• Ventana de observación: lib/client.js gestiona el lease del watcher, el <img> JPEG y el <video> MSE; lib/cast-server.js retransmite el SSE de metadata, la API watch y el vídeo binario con contrapresión; en el worker, CaptureManager garantiza un único backend activo y un único target actual. El plano de control CDP (pestañas, viewport, entrada, captcha) es independiente del backend de imagen.

Pipeline estilo JEV: dejar que el LLM gobierne el bucle del navegador (fase 10)

El contrato de fotograma «un fotograma ≡ captura de pantalla + DOM numerado + intención + progreso de las acciones», junto con la costura de juicio «el juez responde solo con números, jamás con selectores», se concreta en un pipeline ejecutable, testeable y archivable. El juicio lo aporta un servicio externo Laya / JEV (ver más abajo), el bucle lo gobierna este plugin.

Cuatro herramientas (defineTool del lado del host; las peticiones de juicio salen por HTTP desde el proceso del plugin, sin pasar por la sesión del agente):

Herramienta	Qué hace	Cuándo usarla
bcdp_jev_status	Ejecutarla primero: disponibilidad de la cadena de juicio + diagnóstico de configuración, no envía ninguna petición	Primer paso cuando se sospecha un problema de config/cadena
bcdp_jev_frame	Captura un fotograma (captura de pantalla + candidatos numerados + intención), para ver lo que verá el juez	Depurar el contenido de los fotogramas, comprobar la numeración de candidatos
bcdp_jev_ask	Ensambla el cuerpo de la petición; dryRun es true por defecto, round=control|chapter|pick|evaluate permite examinar por niveles antes de enviar	Ver con claridad la petición de juicio antes de enviarla
bcdp_jev_run	Ejecuta el bucle completo y devuelve la traza paso a paso (candidatos / top / presupuesto / acierto de cada paso)	Cuando de verdad quieras dejarlo actuar

La cadena por defecto es laya → rule. JEV de momento no puede registrarse, por eso no se escribe por defecto; cuando sea posible bastará con reintroducir jev en el orden de preferencia judgePrefer y rellenar jevUrl. Sin clave, bcdp_jev_status imprime por iniciativa propia cómo levantar el servicio en local (ENGINE=laya … uvicorn laya_api.main:app, puerto 8000 y no 7789, ALLOW_DEV_LOGIN=true para crear una clave). Los jueces no disponibles se saltan sin llamarlos (laya exige autenticación sin rama anónima, faltar la clave implica inevitablemente un 401); cada salto y cada fallo entran en la traza, jamás retrocesos silenciosos; refuse es un resultado, no una excepción.

Reducción en tres niveles (el LLM gobierna el proceso en vez de adivinarlo todo de una vez):

1. control — actuar o no (5 opciones fijas: pick_button / sleep / next / prev / done);
2. chapter — qué capítulo (agrupación por contenedores AX, subiendo por la cadena paternal de los childIds hacia el ancestro estructurado más próximo, como form#1 / form#2; con un solo capítulo esta ronda se salta);
3. pick — qué número elegir dentro del capítulo + un score de riesgo.

La división en capítulos no es decorativa: los umbrales se reparten en cubos según el número de candidatos, y descomponer un 20-a-1 en «unos-pocos-a-1 × unos-pocos-a-1» hace que ambas rondas caigan en cubos más estrictos (top≥0.5 y top−second≥0.15), más controlables que un 20-a-1 único (top≥0.6). El juez responde solo con números; coordenadas/selectores los remide cada vez la capa de ejecución (DOM.getBoxModel + reverificación del punto con DOM.getNodeForLocation antes del clic); los rectángulos del fotograma nunca sirven de base al clic.

El contexto de juicio está aislado: solo se admiten los cuatro segmentos INTENT / PROGRESS / FRAME / HISTORY, jamás el prefijo de sesión de la sesión del agente; cualquier segmento extra provoca un error inmediato en el ensamblado (por aserción, no por convención). PROGRESS (número de pasos / intentos y resultados por capítulo / acciones realmente logradas / presupuesto restante) lo genera mecánicamente el propio bucle, no lo escribe el modelo — el progreso escrito por un modelo es el segundo canal de alucinación más difícil de descubrir.

Interruptor de evaluación jevEvaluate (activado por defecto, se puede desactivar en el panel de ajustes): tras cada paso ejecutado, el juez reevalúa el progreso: inprogress / done / fail. Ante fail o un «done sin verificar» no se adivina el siguiente paso: se pasa a escalate — con una lista ordenada de RecoveryOption (por ejemplo, primero reload para refrescar, porque un render obsoleto puede ocultar una confirmación ya escrita), dejando al LLM decidir entre recuperarse o detenerse.

Estados terminales del bucle: done (autoverificación contra successCriteria) / blocked (detenido por el presupuesto) / exhausted (presupuesto agotado, con exhaustedKind) / stuck (mismo ancla y misma acción 3 veces seguidas sin cambios) / unavailable (sin juez) / error / escalate.

Registro honesto del estado actual: esta fase ha demostrado que protocolo, umbrales, terminación, capítulos, ensamblado y aislamiento son correctos (cubierto por los tests unitarios bcdp_jev_*), pero el recorrido de extremo a extremo sobre un navegador real aún no se ha ejecutado (T10.22 pendiente); la precisión del juicio no se ha medido en campo (los cubos de umbrales sirven para calibrar, no prueban que las elecciones sean acertadas). Los elementos operados archivados conservan los rasgos de localización como class (solo se despojan los tokens de envoltura del inspector), para devolvérselos al LLM en un escalate y facilitar la recuperación.

Desarrollo

El código fuente está en src/ (TypeScript), los artefactos de build en lib/ (bundles de host + cliente) y bin/cdp-cast-worker.mjs (bundle del worker).

pnpm typecheck   # barrera de tipos tsc (tsconfig.json principal + tsconfig.client.json cliente)
pnpm test        # tests unitarios vitest
pnpm run build   # tres bundles tsdown: lib/index.js + lib/client.js + bin/cdp-cast-worker.mjs

Edita directamente src/ (src/index.ts capa de herramientas, src/client/index.ts frontend, src/worker/cdp-cast-worker.ts worker). Añade las nuevas herramientas en registerActionTools con t({...}), completa el índice bcdp_help (src/help.ts) y ejecuta pnpm typecheck && pnpm test && pnpm run build. lib/ y bin/cdp-cast-worker.mjs son artefactos de build (precompilados y versionados), no los edites a mano.

node_modules/ solo contiene enlaces simbólicos a un checkout de DSH (resolución de tipos en compilación); en ejecución, el harness resuelve @deepseek-ai/dsh-tools.

Limitaciones conocidas (dichas con honestidad)

• Windows: adaptado a nivel de plugin desde v0.4.0; la runtime incorporada para Windows sigue siendo principalmente comunitaria — la estabilidad de flujos complejos de varios pasos puede ser inferior a macOS.
• Captura FFmpeg por plataforma: Windows ya usa gfxcapture(HWND), que exige un build reciente con ese filtro; un FFmpeg antiguo en el PATH se salta con la sugerencia de descargar una versión compatible. Linux usa x11grab, macOS avfoundation como recorte de pantalla; ScreenCaptureKit en macOS y un helper Portal para Wayland son mejoras futuras.
• Entorno de instalación: los paquetes peer de DSH de este repositorio no están todos en el registro npm público. Un pnpm install normal puede fallar al resolver los peers @deepseek-ai/*; la instalación vía profile de DSH debe aportar esos peers. CDP no depende de FFmpeg y no descarga binarios durante la instalación del plugin.
• Calidad de los snapshots: en Linux el árbol semántico se reconstruye vía CDP DOMSnapshot, no a nivel de kernel como en macOS — escenarios complejos con iframe/canvas pueden degradar.
• Fiabilidad del host (Linux): PR comunitarios sin fusionar — el estado de pestañas/espacios puede perderse entre llamadas CLI cruzadas; el plugin va defendido: los flujos simples son estables, los complejos pueden requerir reintentos.
• Persistencia del estado de sesión: las cookies de ejecución de Chrome solo se escriben en disco al cerrar con elegancia; tras un cierre forzado y reinicio hará falta volver a iniciar sesión.
• El esquema de salida es permisivo (additionalProperties: true); el cliente se guía por los valores realmente devueltos.

Licencia y atribución

El plugin en sí está bajo MIT. La runtime incorporada integra código MIT de terceros; los builds FFmpeg descargables opcionalmente conllevan obligaciones GPL-3.0-or-later. Antes de usar o redistribuir, lee las licencias de las fuentes de build y la información sobre obtención del código fuente — ver THIRD_PARTY_NOTICES.md.

Cadena de suministro y permisos

Hechos deterministas aportados para la inclusión en directorios y la revisión:

• Archivos de ejecución: lib/ (artefactos de build, generados de forma determinista desde el TypeScript de src/ con npm run build mediante tsdown), bin/ (scripts ejecutables de entrada del worker y de ffmpeg-probe), cordis.patch.yml (capa de ensamblado), dsh-plugin.json (manifiesto). Los *.map son solo sourcemaps de depuración, sin papel en ejecución, declarados excluidos.
• Artefactos nativos/ejecutables: runtime/ incorpora una runtime compatible con ego (MIT de terceros; procedencia e inventario archivo por archivo en THIRD_PARTY_NOTICES.md) — es la función central del plugin (host Chrome/CDP gestionado y autosuficiente), un artefacto ejecutable transportado a propósito, no un subproducto de build. runtime/PATCHES.md documenta todos los parches locales aplicados a la runtime incorporada.
• Dependencias: la única dependencia en ejecución es @deepseek-ai/schemastery (una implementación equivalente la aporta el host DSH); las peer dependencies son todas servicios del host @deepseek-ai/dsh-*. Los módulos externos del bundle cliente los resuelve la tabla de módulos del host, sin arrastrar dependencias npm.
• Servicios externos: sin telemetría, sin llamadas a APIs externas. El único comportamiento de red es opcional: el instalador de FFmpeg descarga un build desde GitHub (o el espejo configurado por el usuario) por instrucción del usuario; verificación de fuentes y obligaciones de licencia: ver THIRD_PARTY_NOTICES.md.
• Fronteras de fallo: sin webServer en el host (TUI/headless) las rutas watch se saltan con seguridad; si el worker no arranca, las rutas watch devuelven un JSON con ok:false en lugar de quedarse colgadas; los procesos del navegador terminan junto con el teardown del host (--stop en fire-and-forget, sin bloquear la salida del host).
• Permisos: el campo permissions del manifiesto está vacío — las lecturas/escrituras de archivos del conjunto de herramientas quedan confinadas a los directorios de espacios gestionados por ego y al área de trabajo del usuario; el acceso a red va por el navegador del agente gestionado, no por el proceso del host.

---

Enlaces amigos

También obras del ecosistema de plugins de DeepSeek Harness, nos recomendamos mutuamente: