noambrand/gmail-label-cleanup

Limpieza de etiquetas de Gmail

Ordena una gran acumulación de correos de Gmail en las etiquetas propias del usuario y haz que el correo futuro se etiquete solo.

Los conectores Gmail integrados en la mayoría de asistentes etiquetan un hilo por llamada y no tienen API de filtros. Eso es demasiado lento para miles de mensajes y no puede evitar que la acumulación vuelva a crecer. Esta skill utiliza un servidor MCP completo de Gmail, que proporciona filtros reales del lado del servidor y lotes de 50 mensajes.

Antes de la primera ejecución

1. Instala el servidor MCP. Consulta install/INSTALL.md. Necesita un cliente OAuth de escritorio de Google Cloud y un inicio de sesión en el navegador. Aproximadamente diez minutos, una vez.
2. Crea el archivo de reglas. Copia references/rules-TEMPLATE.md a un archivo privado (la plantilla sugiere my-rules.md, que .gitignore ya excluye) y complétalo con el historial de la propia cuenta. Nunca inventes las reglas. Consulta "Aprendiendo las reglas" más abajo.

La única regla que hace que esto funcione

Las reglas se aprenden del etiquetado pasado del propio usuario, nunca se inventan.

Para cada remitente o asunto, observa dónde ha archivado esa persona ese remitente anteriormente, y copia esa etiqueta. Solo cuando un remitente no aparece en ningún lugar de su historial se permite una decisión razonada, y entonces se registra en una sección "adivinada" para que pueda corregirse. Una etiqueta incorrecta es barata de arreglar; una etiqueta incorrecta aplicada silenciosamente a 300 mensajes no lo es.

La segunda regla, aprendida a la fuerza: el contenido cuenta, no solo el remitente. Un remitente es una dimensión. Un boletín sobre dinero de una editorial de bienestar merece también la etiqueta de dinero. Un hilo puede llevar más de una etiqueta.

Aprendiendo las reglas

Pregunta a la cuenta, no a la persona. Para cada etiqueta, lee lo que ya está en ella:

search_emails: label:"<nombre de la etiqueta>"

Lee entre 30 y 50 resultados y anota los remitentes. Esa lista es la regla. Repite para cada etiqueta. Luego list_email_labels para obtener los IDs de las etiquetas, que es lo que realmente toma batch_modify_emails.

Haz esto una vez, escríbelo en el archivo de reglas y sigue añadiendo en cada pasada. Cada pasada descubre remitentes que la anterior no había visto.

Realizando una pasada

Una pasada es un fragmento de trabajo acotado, registrado y reversible. Apunta a 200 o 300 mensajes. No intentes hacerlo todo en una sola ejecución.

1. Confirma que los filtros existen.

list_filters

Si faltan los filtros del archivo de reglas, créalos primero con create_filter, uno por grupo de etiquetas, usando criterios from:. Los filtros son la parte que evita que el problema vuelva.

2. Encuentra correo sin etiquetar.

Primero la bandeja de entrada:

search_emails: has:nouserlabels in:inbox

Una vez que la bandeja de entrada se reduzca a los mensajes que están deliberadamente sin etiquetar, el resto del trabajo es archivo. Navega por fecha, moviendo el límite más antiguo cada vez:

search_emails: has:nouserlabels -in:inbox -in:sent -in:draft -in:trash -in:spam -in:chats before:YYYY/MM/DD

Toma de 50 a 60 por página. Establece before: en la fecha del resultado más antiguo que acabas de manejar, y la siguiente llamada continúa donde te detuviste. Esto es más fiable que los tokens de paginación y sobrevive a interrupciones.

3. Agrupa por etiqueta, luego por lotes.

Ordena la página en una lista de IDs de mensajes por etiqueta, luego una llamada batch_modify_emails por etiqueta con addLabelIds. Nunca una llamada por mensaje.

Si un lote devuelve Too many concurrent requests for user, reintenta solo los IDs que fallaron. La llamada informa exactamente cuáles fallaron.

4. Regístralo. Añade una entrada con fecha al registro de deshacer. Consulta "El registro de deshacer" más abajo.

Nunca toques

• Códigos de inicio de sesión de un solo uso, enlaces mágicos, restablecimientos de contraseña y alertas de seguridad. Estos permanecen sin etiquetar y nunca se envían a la papelera. Si una persona necesita encontrar un código de inicio de sesión rápidamente, una etiqueta no ayuda y una regla de papelera perjudica activamente.
• Cualquier cosa en la lista de "nunca etiquetar" del propio usuario. Las personas tienen publicaciones y remitentes que quieren dejar sin etiquetar, y te lo dirán. Escribe cada uno en el archivo de reglas en el momento en que lo digan, con sus palabras.
• Correo familiar y personal, a menos que el usuario ya haya etiquetado a esa persona por sí mismo.

Enviar a la papelera

Envía a la papelera solo lo que el usuario haya autorizado explícitamente, y solo por coincidencia de asunto. El conjunto seguro predeterminado son avisos de términos de servicio y actualizaciones de política de privacidad:

subject:("términos de servicio" OR "términos y condiciones" OR "condiciones de uso"
         OR "política de privacidad" OR "acuerdo de usuario")
negatedQuery: subject:(código OR verificación OR verificar OR "alerta de seguridad" OR contraseña)

La consulta negada no es opcional. Sin ella, un correo de "Verifica tu cuenta - términos actualizados" iría a la papelera.

La papelera de Gmail es recuperable durante 30 días. Nada en esta skill elimina permanentemente.

El registro de deshacer

Cada pasada añade una entrada con fecha. Es el registro que hace que el trabajo sea reversible y revisable:

• La fecha y el número de pasada.
• Si los filtros existían, y cuáles se crearon.
• La cantidad etiquetada, y la cantidad por etiqueta.
• Decisiones razonadas, nombradas. Qué remitentes no tenían precedente, qué se decidió y por qué. Esta es la parte que se corrige después.
• Qué se confirmó como sin etiquetar y sin tocar.

Consulta examples/undo-log-EXAMPLE.md. Escríbelo incluso cuando la pasada sea aburrida. Especialmente entonces.

Los filtros no tocan el correo antiguo

Esto pilla a todo el mundo, así que dilo en voz alta al usuario:

Un filtro de Gmail solo se ejecuta en el correo que llega después de que se crea el filtro. Nunca actúa hacia atrás. Por lo tanto, las dos mitades de esta tarea son genuinamente separadas: los filtros manejan el futuro automáticamente, y el archivo acumulado debe trabajarse a mano, pasada por pasada, exactamente como se describe arriba.

Lo que significa: después de algunas pasadas que hayan descubierto los remitentes reales de alto volumen, vuelve y añade filtros también para ellos. De lo contrario, esos remitentes seguirán llegando sin etiquetar y la acumulación se reconstruirá detrás de ti.

Revirtiendo una pasada

Lee la entrada del registro de deshacer para la pasada, luego batch_modify_emails con removeLabelIds en los mismos IDs de mensaje. Para cualquier cosa enviada a la papelera, untrash funciona durante 30 días. Por eso el registro registra recuentos y razonamientos en lugar de simplemente "hecho".