368 lines
10 KiB
Markdown
368 lines
10 KiB
Markdown
# Plan de desarrollo - Browser Tool para OpenCode
|
|
|
|
## Proyecto
|
|
|
|
Nombre del proyecto: `opencode-browser-tool`
|
|
|
|
Objetivo general:
|
|
|
|
Construir una herramienta browser externa a OpenCode que permita a un agente navegar, inspeccionar e interactuar con aplicaciones web de forma visible por defecto, con soporte posterior para ejecucion headless y capacidades avanzadas de diagnostico.
|
|
|
|
La herramienta debe quedar desacoplada del nucleo de OpenCode para que futuras actualizaciones de OpenCode no rompan ni obliguen a rehacer la solucion.
|
|
|
|
---
|
|
|
|
## Resultado esperado
|
|
|
|
Al terminar el proyecto, OpenCode debe poder usar la herramienta como una tool externa para:
|
|
|
|
- abrir un navegador controlado por la herramienta
|
|
- entrar en aplicaciones locales o webs externas autorizadas
|
|
- interactuar con la interfaz como un usuario real
|
|
- inspeccionar DOM, consola y red
|
|
- recoger evidencia de ejecucion
|
|
- devolver resultados estructurados al agente
|
|
|
|
---
|
|
|
|
## Criterios estructurales fijados
|
|
|
|
- La solucion debe ser externa a OpenCode.
|
|
- El browser y su logica no deben vivir dentro del core de OpenCode.
|
|
- La integracion con OpenCode debe hacerse por `MCP`.
|
|
- La primera version debe priorizar `visible` como modo por defecto.
|
|
- `headless` quedara disponible para escenarios tecnicos donde la UI visible no sea el foco principal.
|
|
- La base tecnologica inicial sera `Playwright + Chromium`.
|
|
- `CDP` se considerara como capacidad complementaria y progresiva, no como dependencia central de la v1.
|
|
|
|
---
|
|
|
|
## Arquitectura objetivo por fases
|
|
|
|
### Fase 1 - Arquitectura simple funcional
|
|
|
|
Flujo:
|
|
|
|
`OpenCode -> MCP server externo -> Playwright -> Chromium`
|
|
|
|
Caracteristicas:
|
|
|
|
- MCP server externo ejecutado fuera del core de OpenCode
|
|
- Playwright como motor principal de automatizacion
|
|
- Chromium como navegador base
|
|
- gestion simple de sesiones de browser
|
|
- artefactos locales: screenshots, logs, traces y video cuando aplique
|
|
|
|
Ventaja principal:
|
|
|
|
Permite llegar rapido a una version util sin comprometer la evolucion futura.
|
|
|
|
### Fase 2 - Arquitectura modular
|
|
|
|
Flujo previsto:
|
|
|
|
`OpenCode -> MCP server externo -> backend/orquestador interno -> runner browser`
|
|
|
|
Caracteristicas previstas:
|
|
|
|
- separacion entre capa MCP y capa operativa del navegador
|
|
- gestion mas fuerte de sesiones, colas, perfiles y artefactos
|
|
- posibilidad de varios runners o modos de ejecucion
|
|
- mejor punto de extension para seguridad, politicas y control de uso
|
|
|
|
### Fase 3 - Diagnostico avanzado
|
|
|
|
Capacidades previstas:
|
|
|
|
- ganchos `CDP` para inspeccion avanzada de Chromium
|
|
- mas telemetria y diagnostico de red, runtime y rendimiento
|
|
- capacidades de analisis fino de estados del navegador durante pruebas complejas
|
|
|
|
---
|
|
|
|
## Alcance funcional de la v1
|
|
|
|
La v1 debe resolver correctamente la interaccion efectiva entre OpenCode y el browser.
|
|
|
|
### Lo que debe incluir
|
|
|
|
- integracion por `MCP`
|
|
- ejecucion visible por defecto
|
|
- soporte para abrir navegador e ir a una URL
|
|
- acciones basicas: `click`, `type`, `press`, `select`, `scroll`, `hover`
|
|
- esperas utiles: selector, texto, URL, carga de pagina
|
|
- lectura de informacion de pantalla y DOM
|
|
- ejecucion de JavaScript en pagina cuando haga falta
|
|
- logica nativa de estabilizacion tras acciones de navegacion/interaccion para reducir esperas manuales
|
|
- captura de screenshot
|
|
- captura de consola y errores del runtime de la pagina
|
|
- soporte para video o tracing si el coste operativo es razonable desde la v1
|
|
- respuesta estructurada al agente con estado, error y evidencia
|
|
|
|
### Lo que puede quedar fuera de la v1 si retrasa demasiado
|
|
|
|
- backend intermedio separado
|
|
- politicas completas para webs externas
|
|
- soporte fuerte de perfiles persistentes complejos
|
|
- capacidades avanzadas de `CDP`
|
|
- compatibilidad cross-browser real con `WebKit` o `Firefox`
|
|
|
|
---
|
|
|
|
## Herramientas y componentes previstos
|
|
|
|
### Base principal
|
|
|
|
- `Playwright`
|
|
- `Chromium`
|
|
- `Node.js 20+`
|
|
- `TypeScript`
|
|
|
|
### Integracion
|
|
|
|
- `MCP server` externo como interfaz con OpenCode
|
|
|
|
### Diagnostico progresivo
|
|
|
|
- `CDP` en puntos concretos cuando `Playwright` no cubra suficientemente el caso
|
|
|
|
### Artefactos
|
|
|
|
- screenshots
|
|
- logs de consola
|
|
- resultados estructurados
|
|
- video o trace cuando convenga
|
|
|
|
---
|
|
|
|
## Contratos que deben quedar bien definidos desde el inicio
|
|
|
|
Aunque la v1 use arquitectura simple, el diseno debe dejar estables estos contratos:
|
|
|
|
- contrato de sesion de browser
|
|
- contrato de acciones del navegador
|
|
- contrato de artefactos generados
|
|
- contrato de respuesta al agente
|
|
|
|
Esto permitira pasar a una arquitectura con backend/orquestador sin rehacer el modelo base.
|
|
|
|
---
|
|
|
|
## Stack fijado para la v1
|
|
|
|
Queda fijado para la v1:
|
|
|
|
- `Node.js 20+`
|
|
- `TypeScript`
|
|
- `Playwright`
|
|
- `Chromium`
|
|
- `@modelcontextprotocol/sdk`
|
|
- `MCP` por `stdio`
|
|
|
|
Decision de navegador para v1:
|
|
|
|
- usar `Chromium managed by Playwright` como modo por defecto y recomendado
|
|
- ejecutar instalacion de Chromium durante `install.sh` mediante `npx playwright install chromium`
|
|
- no depender del `Chromium` del sistema en la v1 para evitar variaciones de compatibilidad
|
|
|
|
Evolucion prevista:
|
|
|
|
- habilitar en fase posterior un modo opcional `system browser` por `executablePath` para quienes prefieran reutilizar un navegador ya instalado
|
|
|
|
Queda descartado por ahora:
|
|
|
|
- usar `Puppeteer` en paralelo a `Playwright`
|
|
- introducir `WebKit` en la v1 como motor principal
|
|
- construir desde el inicio un backend intermedio obligatorio
|
|
|
|
---
|
|
|
|
## Tools MCP minimas de la v1
|
|
|
|
La v1 se implementara con un conjunto pequeno y suficiente de tools MCP.
|
|
|
|
Lista inicial fijada:
|
|
|
|
- `browser_open`
|
|
- `browser_close`
|
|
- `browser_navigate`
|
|
- `browser_click`
|
|
- `browser_type`
|
|
- `browser_press`
|
|
- `browser_scroll`
|
|
- `browser_wait`
|
|
- `browser_snapshot`
|
|
- `browser_evaluate`
|
|
|
|
Capacidad cubierta por este conjunto:
|
|
|
|
- apertura y cierre de sesion de browser
|
|
- navegacion a URL objetivo
|
|
- interaccion base con la interfaz
|
|
- esperas para estabilizar ejecuciones
|
|
- captura de evidencia visual inicial
|
|
- lectura o evaluacion de estado en pagina mediante JavaScript
|
|
|
|
Capacidades previstas para ampliacion posterior sin romper estos contratos:
|
|
|
|
- logs de consola como tool separada o adjunta a respuestas
|
|
- tracing o video
|
|
- lectura estructurada de red
|
|
- gestion avanzada de perfiles y sesiones
|
|
|
|
---
|
|
|
|
## Estructura inicial fijada del proyecto
|
|
|
|
La estructura inicial del proyecto queda fijada asi:
|
|
|
|
```text
|
|
opencode-browser-tool/
|
|
artifacts/
|
|
docs/
|
|
PLAN_DE_DESARROLLO.md
|
|
TODO.md
|
|
scripts/
|
|
src/
|
|
browser/
|
|
tools/
|
|
types/
|
|
server.ts
|
|
.gitignore
|
|
check.sh
|
|
install.sh
|
|
opencode.mcp.example.json
|
|
package.json
|
|
README.md
|
|
tsconfig.json
|
|
```
|
|
|
|
Objetivo de esta estructura:
|
|
|
|
- separar claramente documentacion, codigo, scripts y artefactos
|
|
- dejar lista la base para evolucionar a una arquitectura modular
|
|
- mantener el paquete autocontenido para instalarlo en otros equipos con OpenCode
|
|
|
|
---
|
|
|
|
## Comunicacion interna prevista
|
|
|
|
### En la v1
|
|
|
|
`OpenCode` actuara como cliente `MCP`.
|
|
|
|
La herramienta expondra un `MCP server` externo que OpenCode podra arrancar y usar.
|
|
|
|
Ese servidor traducira las tools pedidas por OpenCode a operaciones sobre `Playwright`.
|
|
|
|
### En la v2
|
|
|
|
El `MCP server` podra seguir siendo la cara publica, pero delegando ya en un backend intermedio propio.
|
|
|
|
Esto permite mantener estable la integracion con OpenCode mientras evoluciona el interior del sistema.
|
|
|
|
---
|
|
|
|
## Instalacion y distribucion esperadas
|
|
|
|
La herramienta debe poder distribuirse como carpeta autocontenida del proyecto.
|
|
|
|
Estructura objetivo aproximada:
|
|
|
|
```text
|
|
opencode-browser-tool/
|
|
docs/
|
|
src/
|
|
scripts/
|
|
artifacts/
|
|
package.json
|
|
README.md
|
|
install.sh
|
|
check.sh
|
|
opencode.mcp.example.json
|
|
```
|
|
|
|
### Objetivo de instalacion
|
|
|
|
En un PC con OpenCode, debe ser posible dejar la herramienta lista con uno de estos caminos:
|
|
|
|
- ejecutar un script de instalacion rapida
|
|
- seguir instrucciones claras en un `.md`
|
|
- pedir a un agente de OpenCode que ejecute esas instrucciones y deje todo listo
|
|
|
|
### Lo que debe dejar listo la instalacion
|
|
|
|
- dependencias del proyecto instaladas
|
|
- Playwright y Chromium preparados
|
|
- scripts de verificacion funcional
|
|
- plantilla de configuracion de OpenCode para conectar el `MCP server`
|
|
- rutas de artefactos creadas
|
|
- instrucciones claras para primer uso
|
|
|
|
---
|
|
|
|
## Funcionamiento operativo esperado de la v1
|
|
|
|
### Configuracion inicial
|
|
|
|
- el usuario instala el proyecto en una carpeta del sistema
|
|
- el usuario ejecuta el script o sigue el `.md` de instalacion
|
|
- OpenCode queda configurado para conocer el `MCP server` del browser tool
|
|
|
|
### Uso normal
|
|
|
|
- el agente decide usar la herramienta o el usuario se lo ordena
|
|
- OpenCode lanza el `MCP server` externo si la integracion se hace por `stdio`
|
|
- el `MCP server` llama a `Playwright`
|
|
- `Playwright` controla `Chromium`
|
|
- la herramienta devuelve al agente resultados y evidencia
|
|
|
|
### Modos de arranque del MCP server
|
|
|
|
Se prioriza para la v1:
|
|
|
|
- `stdio` autolanzado por OpenCode
|
|
|
|
Queda prevista mas adelante la opcion:
|
|
|
|
- servicio persistente separado si el crecimiento del sistema lo requiere
|
|
|
|
---
|
|
|
|
## V2 prevista
|
|
|
|
La v2 debe apoyarse en una v1 ya funcional y estable.
|
|
|
|
Capacidades previstas:
|
|
|
|
- backend/orquestador intermedio
|
|
- gestion mas rica de sesiones y perfiles
|
|
- configuracion de seguridad y permisos de uso
|
|
- control mas fino de navegacion externa
|
|
- artefactos y observabilidad mas avanzados
|
|
- puntos de extension para diagnostico con `CDP`
|
|
- posible evaluacion futura de `WebKit` para compatibilidad, sin desplazar a Chromium como base inicial
|
|
|
|
---
|
|
|
|
## Por definir mas adelante
|
|
|
|
- politica exacta de uso sobre webs externas
|
|
- allowlist de dominios
|
|
- confirmacion para acciones sensibles
|
|
- gestion de `CAPTCHA` y `2FA`
|
|
- necesidad real de soporte `WebKit`
|
|
- nivel de persistencia de sesiones entre ejecuciones
|
|
- politica final de seleccion entre `managed chromium` y `system browser`
|
|
|
|
---
|
|
|
|
## Criterio de exito de la v1
|
|
|
|
La v1 se considerara lograda cuando:
|
|
|
|
- OpenCode pueda usar la herramienta browser como tool externa por `MCP`
|
|
- el browser se abra en modo visible y responda a acciones reales
|
|
- el agente pueda navegar e interactuar con una app local
|
|
- la herramienta pueda devolver evidencia suficiente para diagnosticar fallos
|
|
- la estructura creada permita evolucionar a v2 sin rehacer la integracion con OpenCode
|