noambrand/gmail-label-cleanup

Gmail 라벨 정리

소유자의 Gmail 백로그를 소유자 자신의 라벨로 정리하고, 앞으로 오는 메일도 자동으로 라벨링되도록 합니다.

대부분의 어시스턴트에 내장된 Gmail 커넥터는 호출당 하나의 스레드만 라벨링하고 필터 API가 없습니다. 수천 개의 메시지에는 너무 느리고, 다시 쌓이는 것을 막을 수 없습니다. 이 스킬은 대신 완전한 Gmail MCP 서버를 사용하여 실제 서버 측 필터와 50개 메시지 배치 처리를 제공합니다.

첫 실행 전

1. MCP 서버를 설치합니다. install/INSTALL.md를 참조하세요. Google Cloud OAuth 데스크톱 클라이언트와 한 번의 브라우저 로그인이 필요합니다. 대략 10분 정도 소요되며, 한 번만 하면 됩니다.
2. 규칙 파일을 생성합니다. references/rules-TEMPLATE.md를 비공개 파일(템플릿은 .gitignore에 이미 제외된 my-rules.md를 제안합니다)로 복사하고, 계정의 과거 기록을 바탕으로 작성합니다. 규칙을 절대 임의로 만들지 마세요. 아래 '규칙 학습'을 참조하세요.

이 작업을 가능하게 하는 한 가지 규칙

규칙은 소유자의 과거 라벨링에서 학습되며, 절대 임의로 만들어지지 않습니다.

각 발신자 또는 제목에 대해, 해당 사람이 이미 그 발신자를 어디에 분류했는지 확인하고 그대로 복사합니다. 발신자가 과거 기록에 전혀 없는 경우에만 판단이 허용되며, 그때도 '추정' 섹션에 기록하여 수정할 수 있도록 합니다. 잘못된 라벨은 수정하기 쉽지만, 잘못된 라벨이 300개의 메시지에 조용히 적용되는 것은 그렇지 않습니다.

두 번째 규칙은 어렵게 배운 교훈입니다: 발신자뿐만 아니라 내용도 중요합니다. 발신자는 한 가지 차원일 뿐입니다. 웰빙 출판사에서 온 금전 관련 뉴스레터는 금융 라벨도 받아야 합니다. 하나의 스레드가 여러 라벨을 가질 수 있습니다.

규칙 학습

사람에게 묻지 말고 계정에 물어보세요. 각 라벨에 대해 이미 무엇이 들어 있는지 읽습니다:

search_emails: label:"<label name>"

30~50개의 결과를 읽고 발신자를 기록합니다. 그 목록이 규칙입니다. 모든 라벨에 대해 반복합니다. 그런 다음 list_email_labels로 라벨 ID를 가져옵니다. 이 ID가 batch_modify_emails에서 실제로 사용하는 값입니다.

한 번 수행하여 규칙 파일에 작성하고, 각 패스(pass)마다 계속 추가합니다. 각 패스는 이전 패스에서 보지 못했던 발신자를 발견합니다.

패스 실행

패스는 하나의 경계가 있고, 기록되며, 되돌릴 수 있는 작업 덩어리입니다. 200~300개의 메시지를 목표로 하세요. 한 번에 모든 것을 처리하려고 하지 마십시오.

1. 필터가 존재하는지 확인합니다.

list_filters

규칙 파일의 필터가 없으면 먼저 create_filter를 사용하여 라벨 그룹당 하나씩 from: 기준으로 생성합니다. 필터는 문제가 다시 발생하는 것을 막는 부분입니다.

2. 라벨이 없는 메일을 찾습니다.

먼저 받은편지함:

search_emails: has:nouserlabels in:inbox

받은편지함이 의도적으로 라벨이 없는 메시지만 남을 때까지 줄어들면, 나머지 작업은 보관입니다. 날짜별로 페이지를 이동하며, 각각 가장 오래된 경계를 이동합니다:

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

페이지당 50~60개를 가져옵니다. 방금 처리한 가장 오래된 결과의 날짜로 before:를 설정하면 다음 호출이 중단된 지점에서 계속됩니다. 이는 페이징 토큰보다 더 안정적이며 중단에도 견딥니다.

3. 라벨별로 그룹화한 다음 배치 처리합니다.

페이지를 라벨당 하나의 메시지 ID 목록으로 정렬한 다음, 라벨당 한 번 batch_modify_emails를 addLabelIds와 함께 호출합니다. 메시지당 한 번 호출하지 마세요.

배치가 '사용자에 대한 동시 요청이 너무 많습니다'를 반환하면 실패한 ID만 다시 시도하세요. 호출은 정확히 어떤 ID가 실패했는지 보고합니다.

4. 기록합니다. 실행 취소 로그에 날짜가 있는 항목을 추가합니다. 아래 '실행 취소 로그'를 참조하세요.

절대 건드리지 말 것

• 일회용 로그인 코드, 매직 링크, 비밀번호 재설정 및 보안 알림. 이러한 메시지는 라벨이 없고 절대 휴지통으로 보내지지 않습니다. 사람이 로그인 코드를 빨리 찾아야 할 때 라벨은 도움이 되지 않으며 휴지통 규칙은 적극적으로 해를 끼칩니다.
• 소유자의 '절대 라벨 안 함' 목록에 있는 모든 것. 사람들은 라벨을 붙이지 않고 남겨두고 싶은 출판물과 발신자가 있으며, 그들이 말해줄 것입니다. 그들이 말하는 순간 즉시 규칙 파일에 그들의 표현 그대로 작성하세요.
• 가족 및 개인 메일. 소유자가 이미 그 사람에게 직접 라벨을 붙이지 않은 경우.

휴지통으로 보내기

소유자가 명시적으로 승인한 항목만, 그리고 제목 일치로만 휴지통으로 보냅니다. 안전한 기본 집합은 서비스 약관 및 개인정보 보호정책 업데이트 알림입니다:

subject:("terms of service" OR "terms and conditions" OR "terms of use"
         OR "privacy policy" OR "user agreement")
negatedQuery: subject:(code OR verification OR verify OR "security alert" OR password)

부정 쿼리는 선택 사항이 아닙니다. 없으면 '계정 확인 - 업데이트된 약관' 메일이 휴지통으로 이동합니다.

Gmail의 휴지통은 30일 동안 복구 가능합니다. 이 스킬에서는 어떤 것도 영구 삭제하지 않습니다.

실행 취소 로그

각 패스는 하나의 날짜가 있는 항목을 추가합니다. 이 기록은 작업을 되돌릴 수 있고 검토 가능하게 만듭니다:

• 날짜와 패스 번호
• 필터가 존재했는지 여부와 생성된 필터
• 라벨이 지정된 개수와 라벨별 개수
• 판단 호출, 이름이 명시됨. 어떤 발신자가 선례가 없었고, 무엇이 결정되었으며, 그 이유는 무엇인지. 이 부분은 나중에 수정됩니다.
• 확인된 라벨 없음 및 건드리지 않은 항목

examples/undo-log-EXAMPLE.md를 참조하세요. 패스가 지루할 때도 기록하세요. 특히 그럴 때 더욱 그렇습니다.

필터는 기존 메일에는 적용되지 않습니다

이 점은 모두를 당황하게 하므로 소유자에게 큰 소리로 말하세요:

Gmail 필터는 필터가 생성된 후에 도착하는 메일에만 적용됩니다. 절대 이전으로 거슬러 올라가지 않습니다. 따라서 이 작업의 두 부분은 실제로 분리되어 있습니다. 필터는 미래를 자동으로 처리하고, 보관된 백로그는 위에서 설명한 대로 패스별로 수동으로 작업해야 합니다.

즉, 몇 번의 패스 후에 실제 대량 발신자를 발견했다면, 다시 돌아가서 그들을 위한 필터도 추가하세요. 그렇지 않으면 해당 발신자들이 계속 라벨 없이 도착하고 백로그가 뒤에서 다시 쌓입니다.

패스 되돌리기

해당 패스의 실행 취소 로그 항목을 읽은 다음, 동일한 메시지 ID로 batch_modify_emails를 removeLabelIds와 함께 호출합니다. 휴지통으로 보낸 항목의 경우 untrash가 30일 동안 작동합니다. 이것이 로그가 '완료'만 기록하지 않고 개수와 추론을 기록하는 이유입니다.