PawSift 🐾 for Android Logcat

PawSift 🐾

PawSift es un servidor de Protocolo de Contexto de Modelo (MCP) de alto rendimiento que conecta Android Logcat con LLMs. Proporciona una interfaz eficiente en tokens y consciente de sesiones para el análisis de registros en tiempo real, utilizando un ingestor SQLite basado en sondeo para filtrar la salida cruda y mostrar solo lo que importa.

Características

• Procesamiento de Alto Rendimiento: Analizador de cadenas manual sin expresiones regulares y deduplicación basada en hash (usando hash/maphash) para el procesamiento de registros en la ruta crítica a más de 5,000 registros/segundo.
• Seguimiento de Sesiones Sin Intervención: Detecta automáticamente reinicios de aplicaciones mediante ActivityManager y rota las sesiones.
• Eficiencia de Tokens: Pre-agrega errores, pliega registros consecutivos repetitivos y utiliza Mapeo Jerárquico para agrupar mensajes idénticos bajo sub-encabezados.
• Consultas Quirúrgicas: Filtra registros por nivel, etiqueta y términos de búsqueda con límites estrictos de líneas para proteger la ventana de contexto.
• Descubrimiento de Etiquetas: Lista rápidamente todas las etiquetas activas en la sesión actual.
• Ventanas Contextuales: Obtiene registros alrededor de un evento específico para depuración precisa.
• Búsqueda Global: Busca en todo el historial de registros a través de todas las sesiones con un solo comando.
• Panel de Estado: Una herramienta especializada de latido para monitorear la salud del observador, IDs de sesión y acumulación de registros.
• Política de Retención Automática: Aplica límites máximos de registros (por defecto 10k registros, 3 sesiones) con limpieza continua durante el sondeo—previene el crecimiento ilimitado de la base de datos.
• Limpieza Configurable: Ajusta los límites de retención sobre la marcha mediante set_retention_policy() sin reiniciar.
• SQLite en Modo WAL: Registro de Escritura Anticipada para acceso concurrente de lectura/escritura sin errores de database is locked.
• Consultas Optimizadas: Índices de base de datos en etiqueta, mensaje, marca de tiempo y filtros compuestos para búsquedas rápidas incluso con grandes volúmenes de registros.
• Mantenimiento: Herramientas integradas para limpiar tanto los buffers de registros locales como los del dispositivo.
• Basado en Go: Distribución rápida de un solo binario sin dependencias CGO.

Instalación

Binario precompilado (recomendado)

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/dolphprefect/pawsift-mcp/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/dolphprefect/pawsift-mcp/main/install.ps1 | iex

Descarga el binario correcto para tu sistema operativo y arquitectura, lo instala en ~/.local/bin/pawsift (o %USERPROFILE%\.local\bin\pawsift.exe en Windows), y registra automáticamente el servidor en tus archivos de configuración de Gemini CLI y Claude Code (CLI).

Soporta: Linux amd64/arm64, macOS amd64/arm64, Windows amd64.

Desde el código fuente

make deploy

Compila desde el código fuente y realiza la misma instalación y registro que el método anterior.

Desinstalación

make uninstall

Herramientas

Herramienta	Descripción
pawsift_set_target_package	Configura el observador para monitorear una aplicación Android específica. Cuando este paquete se inicia, el ID de sesión se rota automáticamente para aislar nuevos registros.
pawsift_get_status	Devuelve el panel de estado actual: paquete objetivo, ID de sesión, actividad del observador, dispositivo conectado y recuento actual de registros.
pawsift_get_error_summary	Devuelve una lista Markdown con recuento primero de registros únicos de ERROR y FATAL con su [ID] más reciente. Usa el ID para recuperación quirúrgica de contexto.
pawsift_get_tag_summary	Devuelve una lista Markdown con recuento primero de todas las etiquetas de registro únicas en la sesión actual.
pawsift_query_logs	Recupera registros filtrados (por nivel y/o etiqueta) usando Mapeo Jerárquico. Soporta plegado de mensajes idénticos consecutivos.
pawsift_get_log_context	Recupera líneas alrededor de un ID de registro específico. Esencial para ver qué condujo a un fallo o evento.
pawsift_search_logs	Realiza una búsqueda global en todo el historial de registros usando Mapeo Jerárquico.
pawsift_clear_logs	Elimina permanentemente todos los registros de la base de datos y limpia el buffer logcat del dispositivo Android.
pawsift_set_retention_policy	Configura los límites de retención: máximo total de registros, máximo de sesiones a conservar e intervalo de limpieza en segundos.

Eficiencia de Tokens

Los registros de Android son extremadamente verbosos. Un solo lanzamiento de aplicación puede producir miles de líneas, la mayoría ruido repetitivo. Alimentar logcat crudo al contexto de un LLM es un desperdicio y a menudo alcanza los límites. PawSift aborda esto en dos niveles.

Plegado

Cuando fold=true (el valor predeterminado en pawsift_query_logs y pawsift_search_logs), los mensajes de registro idénticos consecutivos se colapsan en una sola entrada anotada con un recuento y un rango de tiempo:

- [1042-1089] **D** 09:14.201 - 09:14.812 Choreographer: Skipped 48 frames (48x)

Sin plegado, ese mismo tramo emitiría 48 líneas separadas. Una aplicación ocupada con sondas WiFi repetidas, sondeo de sensores o devoluciones de llamada de animación puede comprimir más de 200 líneas crudas en un puñado de entradas plegadas—una reducción de 10–50× en tokens para esos tramos.

Mapeo Jerárquico

Más allá del plegado, los resultados se estructuran usando Mapeo Jerárquico: los registros se agrupan primero por etiqueta y PID (### Tag (PID)), luego por mensaje único (#### Message), con ocurrencias individuales listadas debajo. Esto significa que el LLM recibe un resumen estructurado en lugar de un flujo plano:

### MyApp (12345)
#### Failed to load resource
- [301] **E** 09:15.001
- [318] **E** 09:15.430

### NetworkManager (987)
#### Socket timeout
- [412] **W** 09:15.102

Los mensajes repetidos de la misma fuente aparecen una vez como encabezado con sus ocurrencias listadas debajo, en lugar de duplicar el texto del mensaje en cada línea.

Acceso Quirúrgico Basado en ID

Cada entrada de registro lleva un [ID] estable. Las herramientas de resumen (pawsift_get_error_summary, pawsift_get_tag_summary) devuelven solo recuentos e IDs—no el cuerpo completo del registro. Una vez que tienes un ID de interés, pawsift_get_log_context obtiene solo la ventana circundante. Este patrón de dos pasos (resumir → acercar) evita cargar todo el historial de registros en el contexto.

Flujo de Trabajo de Depuración

PawSift proporciona una capa de abstracción inteligente sobre los registros crudos de Android, optimizada para depuración asistida por IA. Sigue este flujo de trabajo para obtener los mejores resultados:

1. Configurar el Objetivo

Antes de comenzar las pruebas, dile a PawSift en qué aplicación te estás enfocando:

Usuario al LLM: "Establece el paquete objetivo a com.your.app.package y observa los registros." Acción del LLM: Llama a pawsift_set_target_package(package="com.your.app.package").

2. Verificar el Estado

Orientate antes de comenzar una inmersión profunda:

Acción del LLM: Llama a pawsift_get_status(). Salida: Muestra si el observador está activo, el serial del dispositivo conectado y el recuento actual de registros.

3. Desencadenar el Problema

Ejecuta tu aplicación en tu dispositivo o emulador. PawSift detectará automáticamente el evento "Proceso Iniciado" y comenzará una nueva sesión.

4. Identificar el Fallo (La "Vista de Pájaro")

Si la aplicación falla o se comporta inesperadamente, comienza con un resumen de alto nivel para ahorrar tokens:

Usuario al LLM: "¿Qué acaba de pasar? ¿Algún fallo?" Acción del LLM: Llama a pawsift_get_error_summary(). Salida: Devuelve firmas de error únicas, recuentos y su [ID] más reciente.

5. Investigar los Registros (Seguimiento Quirúrgico)

No consultes todos los registros. Usa el [ID] del resumen para saltar directamente al contexto relevante:

Acción del LLM: Llama a pawsift_get_log_context(log_id=1234, lines=20). Salida: Devuelve 20 líneas antes y después del fallo, dándote visibilidad sobre cambios de estado, respuestas de red o eventos de interfaz de usuario.

Consejo Profesional: Supresión y Búsqueda

• Si ves demasiado ruido del sistema (por ejemplo, WifiHAL, AOC), dile al LLM: "Ignora las etiquetas del sistema y concéntrate en los registros de mi aplicación."
• Usa pawsift_search_logs(query="FATAL EXCEPTION") para encontrar eventos específicos en todo el historial si el resumen de la sesión actual es demasiado amplio.

Gestión de la Política de Retención

PawSift gestiona automáticamente el crecimiento de la base de datos con una política de retención configurable. Por defecto:

• Se mantienen un máximo de 10,000 registros en todas las sesiones
• Se conservan las últimas 3 sesiones; las más antiguas se eliminan
• La limpieza se ejecuta cada 30 segundos durante el sondeo para aplicar los límites

Ajuste de Límites Sobre la Marcha

Usa pawsift_set_retention_policy() para ajustar los límites sin reiniciar:

pawsift_set_retention_policy(max_logs=5000, max_sessions=2, cleanup_interval=15)

Casos de uso:

• Sesión de depuración larga: Reduce los límites (5k registros, 2 sesiones, limpieza de 15s) para mantener la base de datos ágil
• Reproducción rápida: Aumenta los límites (50k registros, 5 sesiones, limpieza de 60s) si necesitas más contexto histórico
• Restricciones estrictas: Modo mínimo (1k registros, 1 sesión, limpieza de 10s) para entornos con recursos limitados

Después de cada ciclo de limpieza, el espacio en disco se recupera mediante VACUUM.

Pruebas

PawSift tiene una cobertura de pruebas integral que incluye pruebas unitarias, casos límite de análisis, pruebas de estrés de concurrencia y detección de carreras de datos.

Ejecución de Pruebas

make test        # Standard test suite
make test-race   # With Go race detector (recommended before releases)

Cobertura de Pruebas

Capa	Pruebas
Casos Límite del Analizador	13 subpruebas: entrada vacía, líneas truncadas, dos puntos faltantes, dos puntos múltiples, espaciado variable, caracteres de nivel inválidos, valores de desbordamiento
Deduplicación por Hash	Rechazo de líneas idénticas, aceptación de diferencias de un solo carácter, reinicio en límites de marca de tiempo
fastAtoi	Límites: cadena vacía, cero, valores normales, desbordamiento (devuelve 0 de forma segura)
Modo WAL	Verifica PRAGMA journal_mode=wal y PRAGMA synchronous=1 en bases de datos respaldadas por archivos
Carga Concurrente	10,000 líneas de registro bombeadas a través de processLine en una goroutine con lectores de base de datos concurrentes—verificado bajo el detector de carreras
Transmisión	Cancelación de contexto, lógica de reintento, detección de reinicio de sesión
Fundamentos de BD	Operaciones CRUD, limpieza, plegado, aplicación de política de retención
Manejadores de Herramientas	Prueba de integración completa de todos los endpoints de herramientas MCP
Renderizado/Formato	Renderizado de entradas de registro, sangría, salida de plegado

19 funciones de prueba en 6 archivos (21 funciones de nivel superior incluyendo subpruebas), todas pasando limpiamente bajo -race.

Detector de Carreras

Todas las pruebas se verifican con go test -race para garantizar que no haya carreras de datos en el pipeline de transmisión, el mapa de deduplicación y los patrones de acceso concurrente a la base de datos.

Configuración para Clientes MCP

make deploy maneja esto automáticamente para Gemini CLI y Claude Code (CLI). Para configuración manual u otros clientes, usa lo siguiente:

{
  "mcpServers": {
    "pawsift": {
      "command": "/home/YOUR_USER/.local/bin/pawsift"
    }
  }
}

Mantenimiento

• Ubicación del Binario: build/pawsift
• Base de Datos: .pawsift/logcat.db (creada automáticamente, SQLite con modo WAL e índices para consultas rápidas)
• Tasa de Sondeo: 1 segundo (configurable en logcat.go)
• Buffer del Canal: 10,000 líneas (previene la contrapresión del escáner durante la contención de escritura en la base de datos)
• Estrategia de Deduplicación: Hash uint64 mediante hash/maphash (sin asignación, evita almacenar cadenas de registro completas)
• Analizador: Segmentación manual de cadenas sin expresiones regulares (processLine usa strings.IndexByte / strings.Cut)
• Valores Predeterminados de Retención: 10,000 registros máximos, 3 sesiones máximas, intervalo de limpieza de 30 segundos (configurable mediante set_retention_policy())
• Versión: Consulta mediante pawsift -version