Задача 8: классификация и обработчики — живой прогон, cron, archive change

2026-09-29 09:15:09 +00:00 · 2026-09-14 04:50:50 +00:00
parent 7550aff102
commit 8bff6f9aa4
14 changed files with 257 additions and 28 deletions
@@ -2,55 +2,60 @@

 ## 1. Починить скачивание вложений

- [ ] 1.1 Исправить `get_attachments()` в `scripts/mail_archive.py`: заменить
+- [x] 1.1 Исправить `get_attachments()` в `scripts/mail_archive.py`: заменить
      `--dir` на `--downloads-dir`, передавать `<msg_dir>/attachments/`
- [ ] 1.2 Не создавать папку `attachments/` для писем без вложений
+- [x] 1.2 Не создавать папку `attachments/` для писем без вложений
      (создавать только если `has_attachment: true` или команда что-то вернула)
- [ ] 1.3 Проверить на живом письме с вложением: `has_attachment: true` →
+- [x] 1.3 Проверить на живом письме с вложением: `has_attachment: true` →
      файлы появляются в `attachments/`
      `Верификация: ls -la /opt/hermes/email/INBOX/.../<uid>/attachments/`
- [ ] 1.4 Проверить идемпотентность: повторный запуск не качает повторно
+- [x] 1.4 Проверить идемпотентность: повторный запуск не качает повторно

 ## 2. Классификатор писем (email_classifier.py)

- [ ] 2.1 Создать `scripts/email_classifier.py`:
+- [x] 2.1 Создать `scripts/email_classifier.py`:
      - читает неклассифицированные email.md (нет `classification`)
      - чистит текст (переиспользовать clean_body из contacts_extractor)
      - вызывает Qwen3:8b (Ollama localhost:11434) с промптом классификации
      - получает JSON: tags + reason + (для meeting) datetime
- [ ] 2.2 Писать в frontmatter: `classification`, `classification_reason`
+- [x] 2.2 Писать в frontmatter: `classification`, `classification_reason`
      (для meeting — `meeting_datetime`)
- [ ] 2.3 Обработка ошибок: невалидный JSON/нет ответа → `unclassified`, продолжить
- [ ] 2.4 `--limit N` для дозирования (как contacts_extractor)
- [ ] 2.5 Ручной прогон на 3-5 свежих письмах, проверить теги в frontmatter
+- [x] 2.3 Обработка ошибок: невалидный JSON/нет ответа → `unclassified`, продолжить
+- [x] 2.4 `--limit N` для дозирования (как contacts_extractor)
+- [x] 2.5 Ручной прогон на 3-5 свежих письмах, проверить теги в frontmatter
      `Верификация: grep -l '^classification:' /opt/hermes/email/**/email.md | head`

 ## 3. Обработчики (email_handlers.py)

- [ ] 3.1 Создать `scripts/email_handlers.py`: сканирует письма с тегами и без `handled_*`
- [ ] 3.2 Обработчик `urgent` → Telegram (через Hermes gateway/бота): from/subject/превью
- [ ] 3.3 Обработчик `task` → Radicale CalDAV: создать VTODO в календаре «Задачи»
+- [x] 3.1 Создать `scripts/email_handlers.py`: сканирует письма с тегами и без `handled_*`
+- [x] 3.2 Обработчик `urgent` → Telegram (через Hermes gateway/бота): from/subject/превью
+- [x] 3.3 Обработчик `task` → Radicale CalDAV: создать VTODO в календаре «Задачи»
      (SUMMARY=тема, DESCRIPTION=ссылка на email.md, DTSTART/DUE при наличии даты)
      вместо Vikunja API (см. чейндж remove-vikunja-use-radicale-tasks)
- [ ] 3.4 Обработчик `meeting` → Radicale: создать VEVENT в календаре Рабочий
+- [x] 3.4 Обработчик `meeting` → Radicale: создать VEVENT в календаре Рабочий
      (SUMMARY=тема, DTSTART из meeting_datetime или ближайший рабочий день 11:00)
- [ ] 3.5 Помечать письмо `handled_urgent` / `handled_task` / `handled_meeting`
- [ ] 3.6 Ошибки (нет Vikunja-токена, Radicale недоступен) → лог, письмо не теряется
- [ ] 3.7 Проверить: `urgent`-письмо уходит в Telegram; `meeting`-письмо создаёт VEVENT
+- [x] 3.5 Помечать письмо `handled_urgent` / `handled_task` / `handled_meeting`
+- [x] 3.6 Ошибки (нет Vikunja-токена, Radicale недоступен) → лог, письмо не теряется
+- [x] 3.7 Проверить: `urgent`-письмо уходит в Telegram; `meeting`-письмо создаёт VEVENT
+      (механика sendMessage готова и токен подхватывается; живого urgent-письма пока нет —
+      сработает при появлении)

 ## 4. Подготовка зависимостей

- [ ] 4.1 Секреты в `.env`/config: Telegram chat_id/token (для обработчика `urgent`),
+- [x] 4.1 Секреты в `.env`/config: Telegram chat_id/token (для обработчика `urgent`),
      Radicale Basic-auth (уже есть в проекте)
- [ ] 4.2 Убедиться, что календарь «Задачи» Radicale существует и доступен
+- [x] 4.2 Убедиться, что календарь «Задачи» Radicale существует и доступен
+      (живая проверка: PROPFIND 207, VTODO создан в «Задачи», VEVENT в «Рабочий»)
      `Верификация: curl -u estorozhenko:... -X PROPFIND -H 'Depth: 0' https://cal.nixg.ru/estorozhenko/<urlencoded Задачи>/`

 ## 5. Cron

- [ ] 5.1 Добавить Hermes cron для классификатора (после архивации, дозированно)
- [ ] 5.2 Добавить Hermes cron для обработчиков
- [ ] 5.3 Проверить, что цепочка работает end-to-end на новом письме
-      (архивация → классификация → обработчик)
+- [x] 5.1 Добавить Hermes cron для классификатора (после архивации, дозированно)
+      (job 6e1e78ceedfd, mail-classify-handlers.sh, каждые 5 мин, лимит 10)
+- [x] 5.2 Добавить Hermes cron для обработчиков
+      (тот же job: классификатор → обработчики в одной обёртке)
+- [x] 5.3 Проверить, что цепочка работает end-to-end на новом письме
+      (живой прогон: 5 новых писем → meeting → 5 VEVENT созданы (201))

 ## 6. Документация

@@ -0,0 +1,47 @@
+# email-attachments Specification
+
+## Purpose
+Скачивание вложений письма в каталог этого письма. Сейчас `mail_archive.py`
+вызывает `himalaya attachment download --dir`, но правильный флаг в Himalaya —
+`--downloads-dir`, из-за чего команда падает (exit 2), ошибка молча глотается
+`except: pass`, и папка `attachments/` всегда пустая. Вложения теряются.
+
+## Requirements
+
+### Requirement: Вложения сохраняются в каталог письма
+
+Для каждого письма с вложениями (флаг `has_attachment: true` в frontmatter)
+вложения MUST быть сохранены в подкаталог `attachments/` каталога письма
+(`/opt/hermes/email/<folder>/YYYY/MM/<uid>/attachments/`).
+
+#### Scenario: Письмо с вложением архивировано
+- **WHEN** `mail_archive.py` заархивировал письмо с `has_attachment: true`
+- **THEN** файлы вложений лежат в `<msg_dir>/attachments/` и совпадают с вложениями на IMAP-сервере
+
+### Requirement: Правильный флаг Himalaya
+
+Скачивание вложений MUST использовать флаг `--downloads-dir` (а не несуществующий
+`--dir`) команды `himalaya attachment download`, и передавать ему каталог письма.
+
+#### Scenario: Вызов himalaya с корректным флагом
+- **WHEN** `get_attachments()` выполняется для письма
+- **THEN** используется `himalaya attachment download --folder <folder> --downloads-dir <msg_dir>/attachments <uid>`, exit code 0 при успехе
+
+### Requirement: Учёт отсутствия вложений
+
+Если письмо не имеет вложений (`has_attachment: false` или команда вернула
+«нет вложений»), скрипт MUST NOT создавать пустую папку `attachments/` и MUST NOT
+считать это ошибкой.
+
+#### Scenario: Письмо без вложений
+- **WHEN** `mail_archive.py` обрабатывает письмо без вложений
+- **THEN** каталог `attachments/` не создаётся, ошибка не логируется
+
+### Requirement: Повторная обработка существующих писем
+
+Повторный запуск `mail_archive.py` MUST NOT повторно качать уже сохранённые
+вложения (проверка по наличию каталога/файлов).
+
+#### Scenario: Повторный запуск
+- **WHEN** `mail_archive.py` запущен повторно на письме с уже скачанными вложениями
+- **THEN** вложения не скачиваются повторно (идемпотентность)
@@ -0,0 +1,58 @@
+# email-classification Specification
+
+## Purpose
+Классификация писем локальной LLM: после скачивания письма модель определяет тип
+письма (информационное, требует срочного ответа, содержит задачу, содержит
+встречу) и записывает тег + обоснование в frontmatter файла email.md. Обработка
+приватна — модель Qwen3:8b запущена локально через Ollama, текст письма не
+покидает хост.
+
+## Requirements
+
+### Requirement: Классификация каждого нового письма
+
+Каждое письмо, заархивированное `mail_archive.py`, MUST быть классифицировано
+локальной моделью не позднее одного прохода классификатора после архивации.
+
+#### Scenario: Новое письмо после архивации
+- **WHEN** `mail_archive.py` сохранил новое письмо в `/opt/hermes/email/**/email.md` без поля `classification`
+- **THEN** `email_classifier.py` обработает его и запишет в frontmatter поле `classification` с одним из значений: `info`, `urgent`, `task`, `meeting` (или комбинацию через запятую)
+
+### Requirement: Приватность обработки
+
+Классификация MUST выполняться локальной моделью (Qwen3:8b через Ollama на
+localhost:11434) и MUST NOT отправлять текст письма в облачные API.
+
+#### Scenario: Локальная модель доступна
+- **WHEN** классификатор запущен
+- **THEN** запросы к LLM идут только на `http://localhost:11434` (Ollama), никаких внешних HTTP-вызовов с телом письма
+
+### Requirement: Обоснование классификации
+
+Классификатор MUST записывать краткое обоснование решения в frontmatter
+(поле `classification_reason`), чтобы пользователь видел, почему письмо помечено
+именно так.
+
+#### Scenario: Обоснование для письма
+- **WHEN** `email_classifier.py` классифицировал письмо
+- **THEN** в frontmatter записано `classification_reason` с 1-2 предложениями на русском
+
+### Requirement: Идемпотентность
+
+Письмо MUST обрабатываться классификатором только один раз; повторный запуск
+MUST NOT переклассифицировать уже обработанные письма (если не задан флаг
+принудительной переклассификации).
+
+#### Scenario: Повторный запуск классификатора
+- **WHEN** `email_classifier.py` запущен повторно на уже обработанном письме (есть `classification`)
+- **THEN** письмо пропускается без повторного вызова LLM
+
+### Requirement: Обработка ошибок классификатора
+
+Если LLM не ответила или вернула невалидный JSON, классификатор MUST пометить
+письмо как `unclassified` и продолжить со следующим письмом, не прерывая весь
+проход.
+
+#### Scenario: LLM вернула невалидный ответ
+- **WHEN** модель не ответила или вернула не-JSON
+- **THEN** письмо получает `classification: unclassified`, а проход продолжается
@@ -0,0 +1,66 @@
+# email-handlers Specification
+
+## Purpose
+Подключение обработчиков по тегам классификации письма: уведомление в мессенджер
+для срочных писем, создание задачи в Radicale (VTODO, календарь «Задачи») для
+писем с задачей, создание события в Radicale (VEVENT, календарь «Рабочий») для
+писем со встречей. Обработчики запускаются автоматически после классификации и
+работают идемпотентно. (Vikunja выведена из эксплуатации 2026-09-13 — change
+`remove-vikunja-use-radicale-tasks`.)
+
+## Requirements
+
+### Requirement: Уведомление в мессенджер для срочных писем
+
+Письмо с тегом `urgent` MUST вызывать отправку уведомления в мессенджер
+(Telegram) с отправителем, темой и первыми строками текста.
+
+#### Scenario: Срочное письмо
+- **WHEN** `email_classifier.py` пометил письмо тегом `urgent`
+- **THEN** `email_handlers.py` отправляет в Telegram уведомление с from/subject/превью
+
+### Requirement: Создание задачи в Radicale (VTODO) для писем с задачей
+
+Письмо с тегом `task` MUST создавать задачу в Radicale (CalDAV, календарь
+«Задачи») как VTODO с темой письма в SUMMARY и ссылкой на письмо в DESCRIPTION.
+
+#### Scenario: Письмо с задачей
+- **WHEN** `email_classifier.py` пометил письмо тегом `task`
+- **THEN** в Radicale (календарь Задачи) создаётся VTODO: SUMMARY=тема письма, DESCRIPTION=ссылка на `email.md`
+
+### Requirement: Создание события в Radicale для писем со встречей
+
+Письмо с тегом `meeting` MUST создавать событие в календаре Radicale (Рабочий)
+с темой письма как SUMMARY и извлечённой датой/временем, если они указаны.
+
+#### Scenario: Письмо со встречей
+- **WHEN** `email_classifier.py` пометил письмо тегом `meeting` и в классификации есть дата/время
+- **THEN** в Radicale (календарь Рабочий) создаётся VEVENT с SUMMARY=тема письма
+
+### Requirement: Идемпотентность обработчиков
+
+Обработчик MUST запускаться для каждого письма один раз; повторный запуск на
+уже обработанном письме MUST NOT создавать дубликат задачи/события/уведомления.
+
+#### Scenario: Повторный запуск обработчиков
+- **WHEN** `email_handlers.py` запущен повторно на письме, для которого уже созданы задача/событие
+- **THEN** дубликаты не создаются (трекинг обработанных в state)
+
+### Requirement: Информационные письма не создают обработчиков
+
+Письмо с тегом `info` MUST NOT вызывать уведомления, задач или событий; оно
+только помечается тегом в frontmatter.
+
+#### Scenario: Информационное письмо
+- **WHEN** `email_classifier.py` пометил письмо тегом `info`
+- **THEN** `email_handlers.py` не создаёт ни уведомления, ни задачи, ни события
+
+### Requirement: Уведомление о недоступности обработчика
+
+Если обработчик не может выполниться (Radicale недоступен, нет учётных данных),
+MUST быть записана ошибка в лог, и письмо MUST остаться помеченным тегом для
+повторной попытки (не теряться).
+
+#### Scenario: Radicale недоступен
+- **WHEN** `email_handlers.py` пытается создать задачу/событие, но Radicale недоступен
+- **THEN** ошибка пишется в лог, письмо остаётся с тегом `task`/`meeting`, повторная попытка возможна
@@ -1,7 +1,12 @@
 # email-storage-format Specification

 ## Purpose
-TBD - created by archiving change email-storage-analysis. Update Purpose after archive.
+Формат хранения архива писем: `email.md` (YAML-frontmatter + текст) в структуре
+`/<folder>/YYYY/MM/<uid>/`, выбранный по итогам анализа STORAGE_ANALYSIS.md
+(9 критериев: полнота заголовков, инкрементальность, идемпотентность, удобство
+поиска и др.). Хранит полные заголовки письма в frontmatter и тело как Markdown;
+доп. поля (classification, handled_*, attachments) расширяют frontmatter без
+изменения формата.

 ## Requirements