Arquitectura y Portabilidad · Ayuda de ZeroChat

1. Arquitectura Web Estática y Backend Unificado

ZeroChat está diseñado bajo una premisa fundamental: máxima simplicidad, velocidad y control sin dependencias pesadas.

La aplicación web se sirve de forma directa y estática por HTTPS desde GitHub Pages como zerochat.html, cargando sus módulos css/ y js/ sin proceso de empaquetado. El Service Worker permite reutilizar recursos disponibles sin sustituir la conexión cuando sea necesaria.

Toda la interacción con el sistema local se canaliza a través del ejecutable zerochat instalado desde PyPI o del script zerochat.py. Ambos abren la misma interfaz de GitHub Pages y autentican las sesiones mediante tokens diarios de seguridad.

Ventaja clave: Sin compiladores ni herramientas complejas de empaquetado. La aplicación web se sirve estáticamente y el backend local se ejecuta en cualquier equipo con un simple comando de terminal.

2. Modos de arranque: zerochat.html (Web) vs. zerochat.py (Backend local)

ZeroChat está concebido para ofrecer dos experiencias complementarias según el contexto de uso: una aplicación web universal y autónoma (ideal para movilidad y uso diario sin instalación) y una estación de trabajo local (para desarrollo y control directo del sistema operativo).

A. La versión Web pura (`zerochat.html`)

Disponible directamente en la web (GitHub Pages) o abriendo el archivo localmente. Es una aplicación completa y autosuficiente que no requiere Python, terminal, servidores auxiliares ni instalación.

Experiencia web universal: Diseñada como Progressive Web App (PWA) instalable desde navegadores modernos, con panel lateral táctil y composer autoexpansible. No requiere Python, root ni herramientas de terminal.
Conectividad multimodelo completa: Conexión directa desde el navegador con OpenAI, Anthropic Claude, Google Gemini y OpenRouter, así como servidores locales en red con CORS (Ollama, LM Studio).
Inferencia local privada en navegador (WebLLM / WebGPU): Descarga y ejecuta modelos de lenguaje open-source en la GPU del propio dispositivo sin enviar datos al exterior.
Motor RAG documental integrado: Indexación y búsqueda vectorial/léxica de PDFs y documentos con Orama, ejecutada en Web Workers y persistida en IndexedDB.
Modo Agente con herramientas de navegador: Ejecución de código JavaScript en sandbox aislado de 3 capas (iframe con origen opaco null, CSP restrictivo sin red y Web Worker con terminación forzada), generación de gráficas interactivas SVG, búsqueda en la web y lectura de páginas públicas.
Soberanía absoluta de datos: Historiales, ramas, adjuntos y configuraciones residen exclusivamente en el IndexedDB local de tu navegador.

B. Qué añade el Backend local (`zerochat.py`)

Diseñado para puestos de escritorio (Linux, macOS, Windows) donde el agente de IA necesita actuar como asistente de desarrollo sobre el sistema operativo. También se ha probado en Android mediante Termux:

Acceso al sistema de archivos local: Exploración de directorios, lectura de código fuente e inserción o edición atómica de archivos en el disco duro (read_file, edit_file, list_directory).
Ejecución de comandos del sistema: Lanzamiento de compilaciones, pruebas y comandos shell en la terminal local del equipo (execute_command).
Servidores MCP externos: Integración con el ecosistema Model Context Protocol (automatización de navegador con Playwright, servidores LSP de análisis estático, persistencia relacional SQLite).
Gestión automatizada de entorno: Un único directorio ~/zerochat/ contiene el token, configuración y servicios. Sus dependencias Python se aíslan en ~/zerochat/.venv/, sin modificar el Python global.

Tabla comparativa de capacidades

Capacidad / Característica	`zerochat.html` (Web / PWA)	`zerochat.py` (Backend local)
Conexión con proveedores de IA comerciales (OpenAI, Claude, Gemini, etc.)	✅ Sí	✅ Sí
Inferencia 100% local en navegador con WebLLM y WebGPU	✅ Sí	✅ Sí
Base de conocimiento RAG documental (Orama en navegador)	✅ Sí	✅ Sí
Modo Agente con sandbox JS, búsqueda web y gráficas SVG	✅ Sí	✅ Sí
Persistencia privada en IndexedDB y exportación/importación	✅ Sí	✅ Sí
Uso directo en móviles (Android / iOS) sin terminal ni Python	✅ Nativo (PWA)	⚠️ Requiere Python (Termux o escritorio)
Lectura, edición y navegación de archivos en el disco local	❌ No disponible	✅ Sí (herramientas locales)
Ejecución de comandos de terminal y shell en el host	❌ No disponible	✅ Sí (bash/shell)
Servidores MCP externos (Playwright, memoria, LSP)	❌ No disponible	✅ Sí (gestor MCP integrado)

3. Entrega Web Estática y Conexión con el Backend Local

ZeroChat se sirve de manera estática y universal a través de la web:

Servicio Web Universal (HTTPS): Servido directamente desde GitHub Pages (https://albalday.github.io/zerochat/zerochat.html). Toda la ejecución de interfaz, renderizado y llamadas a APIs de inferencia ocurre en el navegador con acceso a APIs modernas de persistencia como navigator.storage.persist() y almacenamiento seguro en IndexedDB.
Backend Local Unificado: Al ejecutar zerochat tras instalarlo desde PyPI, o python3 zerochat.py tras descargar el script, el servidor local arranca en 127.0.0.1:6388 y abre GitHub Pages. La aplicación consume el token de sesión una sola vez, lo elimina de la barra de direcciones y lo conserva en una cookie del mismo origen web.

Desarrollo y pruebas locales automáticas: Al ejecutar python3 zerochat.py directamente dentro del repositorio clonado, el script detecta automáticamente el entorno de desarrollo y sirve la interfaz local en http://127.0.0.1:6388/zerochat.html sin necesidad de servidores auxiliares ni parámetros.

Cómo lanzar las pruebas:

python3 zerochat.py: Arranca el backend y abre automáticamente la interfaz local de desarrollo en el navegador.
python3 zerochat.py --test: Ejecuta la autocomprobación interna rápida de herramientas del sistema (lectura, listado y comandos).
npm test: Ejecuta la suite completa automatizada (unitarias, integración, arquitectura, infraestructura y navegador con Playwright).
npm run test:browser: Ejecuta exclusivamente las pruebas de interfaz visual y navegador.

4. Infraestructura local, distribución y actualizaciones

La instalación con pip install zerochat distribuye únicamente el ejecutable Python. La descarga directa distribuye ese mismo ejecutable como zerochat.py. Ninguna incluye HTML, JavaScript o CSS: ambas abren la interfaz publicada en GitHub Pages, por lo que el almacenamiento web y la cookie de sesión comparten un único origen.

En el directorio personal del usuario, los dos modos crean la misma estructura:

~/zerochat/
├── .venv/       Entorno aislado para dependencias MCP Python
├── config/      Token y preferencias de servicios
└── services/    Servidores MCP y sus dependencias

El ejecutable de PyPI permanece gestionado por pip y el archivo descargado permanece donde lo guardaste. Borrar ~/zerochat/ elimina el estado local y los MCP, sin tocar ninguno de los dos ejecutables.

Las versiones usan mayor.menor.parche. El parche actualiza solo la interfaz de GitHub Pages; 7.11.0 es compatible con 7.11.x. Un salto de 7.11 a 7.12 actualiza el backend: ZeroChat avisa y muestra el comando correspondiente, python -m pip install --upgrade zerochat para PyPI o la descarga de zerochat.py para curl.

Informes técnicos

Auditoría de ZeroChat 7.11.0 (25 de septiembre de 2026), con evidencia local y límites de verificación:

Informe de funcionalidades y madurez: inventario verificado, alcance de MCP y RAG, y cobertura de pruebas.
Comparativa con herramientas similares: posicionamiento, fortalezas, límites y criterios de elección.
Informe de calidad de código e infraestructura: métricas, riesgos, seguridad local y plan de mejora.

5. Almacenamiento Local y Privacidad de Datos

La arquitectura de datos de ZeroChat sigue el principio de soberanía del usuario. La aplicación nunca envía historiales de conversación, credenciales ni documentos a ningún servidor centralizado de telemetría.

Capas de almacenamiento en el cliente:

IndexedDB (ZeroChatDB): Base de datos estructurada en el navegador donde se guardan las sesiones de chat, los mensajes, metadatos, configuraciones de perfiles de usuario y las ramas del motor RAG.
Almacenamiento aislado de adjuntos: Las imágenes Base64 y los documentos pesados se aíslan en almacenes específicos de IndexedDB para que el árbol de mensajes permanezca rápido, ligero y fluido.
Cache Storage API: Utilizada por el motor WebLLM para almacenar de forma persistente los pesos y parámetros de modelos locales de lenguaje descargados.
LocalStorage / Cookies de sesión (ChatStorage): Gestiona estados efímeros y preferencias de interfaz (como el tema oscuro o claro activo).

6. El Estado Canónico (ChatState)

Para evitar fugas de memoria o desincronizaciones entre componentes, ZeroChat utiliza un almacén de estado único y centralizado denominado ChatState.

Todo cambio en el ciclo de vida de la aplicación (cambio de sesión, inserción de un mensaje por streaming, progreso de inferencia o invocación de herramientas) se realiza mediante mutadores atómicos de dominio (como appendMessage, replaceMessages o saveSessionMetadata). De este modo, la interfaz se actualiza de manera reactiva y consistente en todo momento.

7. Reglas compartidas de conversación

Las respuestas nuevas y restauradas comparten componentes visuales de bloques y copia. El streaming conserva su cursor durante la generación. Los errores de conexión utilizan una vista común que escapa el mensaje recibido y la URL antes de incorporarlos al HTML.

La configuración activa se obtiene de ChatConfig. Las interfaces de perfiles y catálogo consultan al proveedor WebLLM para conocer los modelos completados, sin interpretar por separado sus metadatos almacenados.

El estado, el motor y las vistas reutilizan las reglas de message-turns.js para identificar turnos y reconocer mensajes iniciales de fecha. La eliminación de turnos comparte un algoritmo de saneamiento; ChatState conserva el bloqueo durante la generación y la actualización atómica del historial.