AIBit-Descubre proyectos de código abierto AIBit-Descubre proyectos de código abierto

WeChat Local Viewer: búsqueda y análisis local de historiales de chats de WeChat

WeChat Local Viewer utiliza FastAPI, Vue y SQLite FTS5 para explorar, buscar y exportar historiales de chats de WeChat en el equipo local, con la opción de conectarse a un LLM compatible con OpenAI.

WeChat Local Viewer: búsqueda y análisis local de historiales de chats de WeChat

Cuando los historiales de chats de WeChat acumulan cientos de miles o incluso millones de mensajes, las formas de consulta integradas en el sistema suelen resultar insuficientes para las necesidades de búsqueda, archivado y análisis. ops120/wechat-local-viewer ofrece una solución local: una vez que el usuario prepara su propia base de datos de chats, puede ver conversaciones en el navegador, explorar mensajes, realizar búsquedas de texto completo y exportar datos. También puede conectarse opcionalmente a un LLM para generar resúmenes o responder preguntas.

Un límite importante del proyecto es que no es una herramienta de descifrado. El repositorio no incluye código para extraer claves, descifrar bases de datos ni eludir mecanismos de seguridad. El usuario debe preparar los datos de chat por su cuenta y colocarlos en el directorio establecido por el proyecto; el visor solo se encarga de analizar y mostrar datos que ya puedan leerse.

Por qué merece atención

El valor principal de este proyecto no está en “mostrar los historiales de chat”, sino en organizar una cadena completa de procesamiento de datos local:

  1. Lee las bases de datos de contactos, conversaciones y mensajes desde el directorio proporcionado por el usuario.
  2. Organiza los datos mediante un flujo ETL en una base de datos SQLite intermedia.
  3. Crea un índice de texto completo FTS5 para los mensajes.
  4. Proporciona mediante FastAPI interfaces de paginación, búsqueda, estadísticas y LLM.
  5. Utiliza un frontend Vue para explorar conversaciones, consultar el contexto de los mensajes y exportar datos.

Esta arquitectura evita que el frontend lea directamente grandes bases de datos originales y facilita las actualizaciones incrementales, la reconstrucción de índices y la optimización de consultas. El proyecto ha probado la importación de 640.000 mensajes, manteniendo una navegación fluida; la búsqueda de texto completo se basa en SQLite FTS5 y tiene como objetivo devolver resultados en segundos, normalmente en menos de 1 segundo.

Funciones principales

  • Lista de conversaciones: muestra conversaciones individuales, grupales y de cuentas oficiales ordenadas de forma descendente por la hora del último mensaje.
  • Exploración de mensajes: renderiza los mensajes en orden cronológico ascendente y admite paginación y contexto de mensajes.
  • Búsqueda de texto completo: utiliza SQLite FTS5 para buscar en el contenido de los mensajes y ofrece sugerencias de búsqueda.
  • Exportación en varios formatos: organiza los registros locales en datos de exportación fáciles de conservar y procesar posteriormente.
  • Resúmenes y preguntas mediante LLM: se conecta mediante el protocolo compatible con OpenAI a servicios como DeepSeek, OpenAI, SiliconFlow y Ollama.
  • Enfoque local: aparte del servicio LLM configurado por el usuario, no depende de servicios HTTP externos.
  • Procesamiento incremental: ETL determina mediante huellas de datos si debe realizar un procesamiento completo, una actualización incremental o no hacer nada.

Requisitos del entorno

El proyecto está dirigido a Windows 10/11 y requiere:

  • Python 3.10 o superior
  • Node.js ^22.19.0 o >=24.0.0
  • Windows 10/11

De forma predeterminada, el backend escucha en el puerto 18787 y el servidor de desarrollo del frontend en el puerto 15713. El proyecto evita deliberadamente el puerto 8765, que puede causar problemas en Windows, así como el puerto predeterminado 5173 de Vite, que suele entrar en conflicto.

Preparar el directorio de datos

Coloca los datos de chat ya preparados en el directorio raíz del proyecto. El proyecto detectará automáticamente decrypted/ o .decrypted/; basta con utilizar uno de los dos:

wechat-local-viewer/
├── decrypted/
│   ├── contact/      # Datos de contactos
│   ├── session/      # Datos de conversaciones
│   ├── message/      # Bases de datos de mensajes, por ejemplo message_*.db
│   └── hardlink/     # Índice de imágenes, opcional
└── start.bat

El directorio hardlink/ es opcional y normalmente se utiliza para el índice de imágenes. Incluso sin disponer de todos los archivos multimedia, los mensajes de texto y algunas imágenes ya restauradas pueden visualizarse con normalidad.

Inicio con un clic

En Windows, la forma más sencilla es hacer doble clic en start.bat, situado en el directorio raíz del proyecto. El script comprobará si los puertos están ocupados y abrirá automáticamente, una vez iniciado:

http://127.0.0.1:18787/

El backend sirve directamente los archivos compilados del frontend, por lo que no es necesario iniciar un servidor de desarrollo del frontend para utilizar el proyecto en producción.

Si necesitas modificar los puertos, establece las variables de entorno antes de iniciar:

set WCVIEWER_PORT=28888
set WCVIEWER_FRONT_PORT=25813
start.bat

La comprobación de puertos resulta muy práctica: frente a los errores de vinculación que solo se muestran después de iniciar el servicio, el script puede ofrecer un aviso claro con antelación, algo especialmente útil cuando se ejecutan varios servicios de desarrollo locales en Windows.

Inicio manual y modo de desarrollo

El backend utiliza FastAPI y Uvicorn:

cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 18787

El frontend utiliza Vue y Vite:

cd frontend
npm install
npm run dev

Para compilar la versión de producción:

npm run build

Una vez completada la compilación, el backend servirá automáticamente frontend/dist. En redes restringidas o cuando se desea mejorar la estabilidad de la instalación de npm, la documentación del proyecto recomienda utilizar un espejo y limitar la concurrencia:

npm config set registry https://registry.npmmirror.com
npm config set maxsockets 4
npm config set audit false
npm install

ETL y base de datos de caché

El proyecto no escanea directamente la base de datos original de WeChat en cada solicitud de página. En su lugar, convierte los datos de origen en una base de datos de ejecución mediante backend/app/etl.py:

.cache/app.db
├── sessions
├── contacts
├── messages
└── Índice FTS5

El proceso ETL incluye aproximadamente las siguientes etapas:

  • parse_sessions: analiza las conversaciones y las escribe en la tabla sessions.
  • parse_contacts: analiza los contactos y los escribe en la tabla contacts.
  • parse_messages: lee archivos como message_*.db, escribe los datos en la tabla messages y crea el índice de texto completo.
  • _update_session_stats: agrega las estadísticas de las conversaciones.

Las huellas de datos se utilizan para determinar si es necesario volver a procesar la información. Si no hay cambios, el proceso puede omitirse; si hay datos nuevos o modificados, se realiza una actualización incremental; cuando es necesario, también se puede forzar ETL mediante la interfaz de administración. Este diseño es especialmente importante para decenas de miles de mensajes, ya que realizar una importación completa cada vez que se abre la aplicación ralentizaría considerablemente el inicio.

Durante la ejecución también se generan los siguientes directorios, que no forman parte del repositorio de código fuente:

.cache/   # Base de datos intermedia app.db
.export/  # Archivos exportados
.tmp/     # Registros y archivos temporales

Estos directorios están excluidos mediante .gitignore y no deben enviarse al repositorio.

Diseño de la API

El backend proporciona una API REST relativamente clara, útil para depurar o ampliar el proyecto con otros clientes:

Endpoint Método Uso
/api/sessions GET Obtiene las conversaciones ordenadas de forma descendente por last_time
/api/sessions/{username} GET Obtiene los detalles de una conversación
/api/messages?session=X GET Obtiene mensajes paginados
/api/messages/{id} GET Obtiene un mensaje individual
/api/messages/{id}/context GET Obtiene el contexto de un mensaje
/api/search?q=X GET Realiza una búsqueda de texto completo mediante FTS5
/api/search/suggest?q=X GET Obtiene sugerencias de búsqueda
/api/admin/etl POST Activa ETL; puede recibir {"force": true}
/api/admin/status GET Consulta el estado de ETL
/api/admin/logs GET Consulta el final de los registros
/api/admin/rebuild-fts POST Reconstruye el índice de texto completo
/api/admin/stats/daily GET Obtiene las estadísticas diarias
/api/llm/config GET / POST Lee o guarda la configuración del LLM
/api/llm/chat POST Devuelve respuestas de chat en streaming mediante SSE
/media/... GET Sirve archivos multimedia ya restaurados

El endpoint /api/llm/chat utiliza salida en streaming mediante SSE, por lo que la interfaz puede mostrar progresivamente el contenido mientras el modelo lo genera, sin esperar a que termine la respuesta completa.

Integración opcional con LLM

El LLM no es una dependencia necesaria del visor. En la sección “Configuración”, situada en la esquina superior derecha de la página, el usuario puede introducir un servicio compatible con OpenAI:

DeepSeek:   https://api.deepseek.com/v1
OpenAI:     https://api.openai.com/v1
Ollama:     http://localhost:11434/v1
SiliconFlow: https://api.siliconflow.cn/v1

Algunos ejemplos de modelos habituales:

deepseek-chat
gpt-4o-mini
qwen2.5:7b

Las opciones de configuración incluyen Base URL, API Key y Model. La clave de API solo se guarda en localStorage del navegador y se envía al backend con cada solicitud de preguntas; también se pueden proporcionar valores predeterminados mediante variables de entorno:

set LLM_BASE_URL=https://api.deepseek.com/v1
set LLM_API_KEY=your-api-key
set LLM_MODEL=deepseek-chat

Sin un LLM configurado, la exploración básica de conversaciones, la búsqueda y la exportación siguen estando disponibles. Al hacer clic en la función de resumen, la interfaz indicará claramente que aún no se ha configurado, en lugar de fallar silenciosamente.

Ten en cuenta que “ejecutarse localmente” no significa que las solicitudes al LLM también se ejecuten por completo en local. Si utilizas DeepSeek, OpenAI u otro servicio remoto compatible, el contenido enviado a ese servicio saldrá del equipo. Para mantener un límite de datos más estricto, puedes utilizar Ollama ejecutado en el propio equipo y establecer Base URL en http://localhost:11434/v1.

Privacidad y límites de seguridad

El proyecto prioriza el funcionamiento local:

  • No realiza solicitudes HTTP externas, aparte del base_url del LLM configurado por el usuario.
  • La ruta estática /media/ no muestra el contenido de los directorios.
  • La clave de API del LLM solo se guarda en localStorage del navegador.
  • Los datos originales, la base de datos de caché, los archivos exportados y los registros temporales permanecen en el equipo local.

Sin embargo, los historiales de chats suelen contener información personal sensible. Al utilizar un LLM remoto, conviene revisar las políticas de retención de datos y entrenamiento del proveedor, y considerar enviar únicamente los fragmentos de conversación necesarios. Para datos altamente sensibles, un modelo local suele ser más apropiado que una API remota.

Rendimiento y verificación

El presupuesto de rendimiento indicado por el proyecto incluye:

  • Inicio hasta la primera pantalla: varios segundos, según una base de datos de 640.000 mensajes, aunque la documentación no proporciona un tiempo exacto medido.
  • Apertura de conversaciones: carga inicial de 30 mensajes mediante consultas indexadas, con buen rendimiento.
  • Búsqueda de texto completo: utiliza FTS5 y tiene como objetivo devolver resultados en segundos.
  • Primer token del streaming del LLM: depende principalmente del servicio del modelo y de la latencia de red; no se proporciona un valor medido fijo.

Al realizar una implementación o investigar problemas, puedes comprobar primero la estructura de directorios del frontend:

cd <directorio raíz del repositorio>
tree /F frontend

Si aún no se han instalado las dependencias del frontend, entra en frontend y ejecuta la instalación. Si los resultados de búsqueda son anómalos, puedes llamar a /api/admin/rebuild-fts para reconstruir el índice. Si el estado de ETL no está claro, consulta /api/admin/status y /api/admin/logs.

Para qué escenarios es adecuado

WeChat Local Viewer es adecuado para desarrolladores y usuarios avanzados que necesiten conservar, buscar o estudiar sus conversaciones personales a largo plazo, por ejemplo:

  • Buscar una palabra clave o una decisión entre una gran cantidad de mensajes históricos.
  • Explorar conversaciones de proyectos prolongados.
  • Exportar historiales de chats para archivarlos personalmente.
  • Utilizar un modelo local o compatible con OpenAI para resumir conversaciones extensas.
  • Crear una herramienta de búsqueda local sin subir la base de datos completa.

El proyecto utiliza la licencia MIT. Su código está compuesto principalmente por Python, Vue y TypeScript, con una distribución aproximada de Python 64,8 %, Vue 24,2 %, TypeScript 7,7 %, Batchfile 2,4 %, JavaScript 0,5 % y HTML/CSS 0,2 % cada uno. Según la información registrada en la página, el repositorio cuenta con 143 estrellas y 94 forks, y todavía no ha publicado una versión oficial.

En conjunto, este proyecto convierte la “lectura de una base de datos local de chats” en una aplicación local ampliable: SQLite FTS5 resuelve el problema de la búsqueda, ETL y la caché resuelven el problema de la escala, FastAPI y Vue proporcionan límites claros entre componentes, y la integración opcional con LLM añade capacidades de resumen y preguntas. Lo más importante es que el usuario puede realizar las tareas principales de exploración y búsqueda sin depender de servicios en la nube, y decidir si activa las funciones del modelo según sus necesidades de privacidad.

Fuente

ops120/wechat-local-viewer: visor local de historiales de chats de WeChat — exploración de conversaciones/búsqueda de texto completo/exportación en varios formatos/resúmenes inteligentes opcionales mediante LLM, todo ejecutado localmente y sin dependencias externas.