Initial commit: Email Assistant project

STATUS.md

@@ -0,0 +1,215 @@
+# Email Assistant — локальный архив и ассистент почты
+
+**Дата:** 2026-07-19
+**Фаза:** 1.5 — Индексация, поиск, дайджесты + Адресная книга (в работе)
+
+**Стек:** Himalaya CLI → Python → SQLite → Ollama (Qwen3:8b) → Yandex Disk
+
+---
+
+## Архитектура проекта
+
+```
+/opt/hermes/email-assistant/
+├── STATUS.md                              # этот файл
+├── config/
+│   ├── himalaya-config.toml              # Himalaya IMAP-конфиг
+│   └── contacts-cron.sh                  # обёртка для cron контактов
+├── scripts/
+│   ├── mail_archive.py                   # инкрементальный архиватор писем с IMAP
+│   ├── mail-archive.sh                   # shell-обёртка для systemd/cron
+│   ├── migrate_to_email_md.py            # конвертер meta.json→email.md (deprecated)
+│   ├── mail_index.py                     # SQLite FTS5-индекс всех писем
+│   ├── contacts_extractor.py             # извлечение контактов через LLM
+│   ├── sqlite_search.py                  # FTS5-поиск по архиву
+│   ├── digest.py                         # еженедельный дайджест почты
+│   └── mail_archive.py                   # основной архиватор
+│
+├── context/
+│   ├── CONTEXT.md                        # архитектура и план развития
+│   ├── SKILL.md                          # навык для Hermes (email-local-archive)
+│   └── CONTACTS.md                       # описание contacts extractor
+
+/opt/hermes/email/                          # архив писем (локальный диск)
+├── INBOX/
+│   └── YYYY/MM/UID/email.md              # YAML-frontmatter + тело
+├── Sent/
+├── Отправленные/
+├── Archive/
+├── state/                                 # mail-archive-last-*.json (last_uid per folder)
+├── contacts/                              # адресная книга
+│   ├── contacts.json                      # полная база контактов
+│   ├── index.json                         # email → contact_id
+│   ├── contacts.vcf                       # vCard 4.0 для импорта
+│   └── last_scan.json                     # трекинг обработанных
+├── digests/                               # еженедельные дайджесты
+│   └── digest-YYYY-MM-DD.md
+└── mail_index.db                          # SQLite + FTS5 (~5.4 MB)
+
+Hermes cron:
+  - mail-archive-every-5min   (no-agent, скрипт)
+  - contacts-extractor-every-30m (скрипт, --limit 15)
+  - digest: пока не поставлен
+  - mail_index --incremental: пока не поставлен
+```
+
+---
+
+## Статус задач
+
+### Фаза 0.5: Рефакторинг формата хранения ✅
+- [x] Перейти с meta.json + body.md на один `email.md` с YAML-frontmatter
+- [x] Полные заголовки в frontmatter (Message-ID, References, In-Reply-To, CC, Content-Type)
+- [x] State файлы в `/opt/hermes/email/state/`
+
+### Фаза 1: Локальный архив ✅
+- [x] Структура `/opt/hermes/email-assistant/`
+- [x] Himalaya (IMAP mail.corpoffice.tech:143 STARTTLS)
+- [x] `mail_archive.py` — инкрементальный архиватор
+- [x] Первый запуск: INBOX 585, Sent 515, Отправленные 510, Archive 373
+- [x] systemd user timer + Hermes cron (every 5m)
+
+### Фаза 1.5: Индексация, поиск и дайджесты ✅⬜
+- [x] `mail_index.py` — SQLite-индекс всех email.md (FTS5 + трекинг контактов)
+- [x] `sqlite_search.py` — CLI-поиск по FTS5 (поддержка фильтров from:/subject:/folder)
+- [x] `digest.py` — еженедельный дайджест через LLM (Qwen3:8b)
+- [ ] Поставить cron на `mail_index.py --incremental` (раз в 5-10 мин)
+- [ ] Поставить cron на `digest.py` (раз в неделю)
+
+### Фаза 1.7: Динамическое обнаружение всех подпапок INBOX ❌
+- [ ] `mail_archive.py` — список вложенных папок INBOX захардкожен (18 шт.), но на сервере их **137** (включая многоуровневые: INBOX/!Персонал/ОТ и ТБ, INBOX/Бюджет/Винный город/CAPEX 2025, INBOX/Контрагенты/iiko/Тихая гавань и т.д.)
+- [ ] `--all` сейчас использует тот же хардкод — не архивирует ~120 подпапок
+- [ ] Требуется: динамическое обнаружение IMAP-папок через `himalaya folder list`, рекурсивный обход всех подпапок INBOX (любой глубины), автоматическая архивация новых подпапок при их создании
+- [ ] `mail-archive-every-5min` cron должен обновлять список папок динамически, а не из хардкода
+
+### Фаза 1.6: Адресная книга (Contacts Extractor) ✅⬜
+- [x] `contacts_extractor.py` — извлечение контактов из подписей через LLM
+- [x] clean_body — удаление цитируемой переписки (Outlook/forwards/>)
+- [x] SQLite-трекинг обработанных писем (contacts_extracted / contacts_skipped)
+- [x] Инкрементальное сохранение каждые 5 писем
+- [x] `--limit N` для дозированной обработки
+- [x] vCard 4.0 генерация
+- [x] Cron already set: `contacts-extractor-every-30m` (--limit 15)
+- [ ] Проверить качество извлечения: сейчас 5 контактов найдено, 5 skipped
+- [ ] Доделать парсинг темы письма (некоторые темы содержат вшитые заголовки)
+
+### Фаза 2: Векторизация и поиск ⬜
+- [ ] Выбор векторизатора (bge-m3 через Ollama — уже есть в Memory OS)
+- [ ] Индексация body в Qdrant
+- [ ] Поиск по письмам через агента
+
+### Фаза 3: Граф знаний ⬜
+- [ ] Извлечение связанных сущностей (отправители, темы, проекты)
+
+---
+
+## Решения и проблемы скриптов
+
+### `mail_archive.py` — Инкрементальный архиватор
+**Задача:** Качать письма с IMAP, сохранять в `email.md` с YAML-frontmatter.
+
+**Решение:**
+- Для каждой папки хранится `last_uid` в `/opt/hermes/email/state/mail-archive-last-<folder>.json`
+- Himalaya читает envelope (from, to, subject, date, message-id) → YAML frontmatter
+- `himalaya envelope --page-size 500` для быстрой загрузки списка писем
+- Каждое письмо: `himalaya get <uid> | email-to-md.py` → `email.md`
+- Инкрементально: добавляет все uid > last_uid, обновляет last_uid
+- Проблема: Himalaya v1.2.0 не поддерживает `danger_accept_invalid_certs` — используем `mail.corpoffice.tech` (валидный сертификат)
+
+### `mail_index.py` — SQLite-индекс
+**Задача:** Быстрый полнотекстовый поиск по архиву, трекинг обработки контактов.
+
+**Решение:**
+- SQLite с FTS5 (unicode61 tokenizer) — 4 таблицы: `emails`, `email_fts`, триггеры синхронизации
+- Индексирует: path, uid, folder, date, from, to, subject, body_preview (первые 500 символов)
+- Поля `contacts_extracted` / `contacts_skipped` для совместной работы с contacts_extractor
+- Режимы: полная переиндексация (`--incremental` игнорирует mtime), поиск (`--search`), статистика (`--stats`)
+- Инкрементальный режим: проверяет `file_mtime` — пропускает неизменённые файлы
+
+### `contacts_extractor.py` — Извлечение контактов
+**Задача:** Найти в подписи письма имя, должность, телефон, компанию отправителя.
+
+**Решение:**
+- Берёт необработанные письма из SQLite (WHERE contacts_extracted=0 AND contacts_skipped=0)
+- `clean_body()`: удаляет HTML-теги, трекинг-ссылки, цитируемую переписку (Outlook-заголовки `От:`, `From:`, `Sent:`; forwarded; `>` quotes)
+- Отдаёт очищенный текст Qwen3:8b (Ollama, temperature=0.1)
+- LLM возвращает JSON: full_name, email, phone, position, company, address, raw_signature
+- Дедупликация по email: при повторной встрече обновляет поля
+- Инкрементальное сохранение: каждые 5 писем пишет contacts.json + contacts.vcf
+- **Текущая проблема:** clean_body может вырезать подпись вместе с цитатами (см. ниже)
+
+### `sqlite_search.py` — FTS5-поиск
+**Задача:** Быстрый поиск по архиву писем из консоли.
+
+**Решение:**
+- FTS5-запрос к mail_index.db через SQL MATCH
+- Поддержка синтаксиса: `"точная фраза"`, `OR`, `-исключение`, `префикс*`
+- Пользовательские префиксы: `from:user@mail`, `subject:отчёт` → LIKE-фильтр в WHERE
+- `--folder INBOX/!Отчеты` — фильтр по папке
+- `--body` — включает тело письма в поиск (медленнее, но полнее)
+- Вывод: дата, папка, отправитель, тема, полный путь к файлу
+
+### `digest.py` — Еженедельный дайджест
+**Задача:** Сгенерировать краткое резюме всех писем за N дней для руководителя.
+
+**Решение:**
+- SQLite-запрос: письма за последние N дней (по дате из frontmatter)
+- Группировка по папкам (INBOX/!ВГ Чек листы → "ВГ Чек листы")
+- Вызов Qwen3:8b с промптом: "напиши краткий дайджест на русском для руководителя"
+- LLM выделяет: общую статистику, темы по папкам, важные отправители
+- Сохраняет в `/opt/hermes/email/digests/digest-YYYY-MM-DD.md`
+- Режимы: `stdout`, `file`, `both`
+
+---
+
+## Проблема: clean_body вырезает подпись вместе с цитатой
+
+**Корень:** В письмах с цепочкой ответов (Outlook forwarding) подпись отправителя часто находится **после** маркера `От: Стороженко... Отправлено:...`, но до конца цитаты. clean_body отрезает всё от первого найденного маркера, теряя подпись.
+
+**Текущее решение (итерация):**
+1. Ищем самый ранний маркер цитирования среди всех паттернов (не первый совпавший)
+2. Fallback: если ни один маркер не сработал — ищем `От: / From: / Subject:` в последних 500 символах
+
+**Что ещё можно сделать:**
+- Двухпроходная очистка: сначала отрезать цепочки forward-заголовков, потом отделять подпись от тела
+- Определять границу подписи по паттернам `С уважением,` / `Best regards,` / `—` — она ближе к концу
+- Использовать LLM не только для извлечения, но и для нахождения подписи
+
+---
+
+## Текущие метрики
+
+| Папка | Писем | Контакты извл. |
+|-------|-------|-----------------|
+| INBOX | 585 | — |
+| INBOX подпапки (18 хардкодных) | ~180 | — |
+| **Неархивируемые подпапки INBOX** | **~120 папок не синхронизируются** | **—** |
+| Sent | 515 | — |
+| Отправленные | 510 | — |
+| Archive | 373 | — |
+| **Всего** | **2073** | **5** |
+
+Индекс: 2073 письма, 5.4 MB SQLite.
+Контакты: 5 найдено (clean_body отрезает подпись в большинстве forwarded-писем).
+
+---
+
+## Cron-задачи (Hermes)
+
+| ID | Имя | Расписание | Тип | Статус |
+|----|-----|-----------|-----|--------|
+| 22c5beb891cc | mail-archive-every-5min | every 5m | no-agent (скрипт) | ✅ |
+| 8e181a988392 | contacts-extractor-every-30m | every 30m | скрипт (--limit 15) | ✅ |
+| — | mail-index-incremental | not set | — | ❌ |
+| — | digest-weekly | not set | — | ❌ |
+
+---
+
+## Конфигурация
+
+- **Himalaya:** `~/.config/himalaya/config.toml`
+- **Аккаунт:** `vinogorod`, IMAP `mail.corpoffice.tech:143` (STARTTLS)
+- **Почта:** `e.storozhenko@vinogorod.ru`
+- **LLM:** Qwen3:8b (Ollama localhost:11434)
+- **SMTP:** не настроен
+- **Файлы state:** `/opt/hermes/email/state/`