mirror of
https://gitverse.ru/kpa39l/email-local-archive.git
synced 2026-09-29 09:15:11 +00:00
Initial commit: Hermes skill email-local-archive
This commit is contained in:
estorozhenko
@@ -0,0 +1,528 @@
|
|||||||
|
---
|
||||||
|
name: email-local-archive
|
||||||
|
description: "Локальный архив почты: инкрементальное сохранение писем из IMAP в файловую структуру на локальный диск с метаданными, телом, вложениями и извлечением адресной книги через LLM."
|
||||||
|
version: 1.6.0
|
||||||
|
author: estorozhenko
|
||||||
|
platforms: [linux]
|
||||||
|
prerequisites:
|
||||||
|
commands: [himalaya, python3]
|
||||||
|
metadata:
|
||||||
|
hermes:
|
||||||
|
tags: [email, archive, imap, backup, contacts]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Email Local Archive
|
||||||
|
|
||||||
|
Этот навык позволяет агенту архивировать письма из почтового ящика
|
||||||
|
в локальную файловую систему (`/opt/hermes/email/`) и извлекать адресную
|
||||||
|
книгу из подписей входящих писем через локальную LLM.
|
||||||
|
|
||||||
|
**История:** архив был перенесён с Yandex Disk (WebDAV davfs2) на локальный
|
||||||
|
диск `/opt/hermes/email/` из-за катастрофической медлительности WebDAV при
|
||||||
|
rm/find/ls на больших деревьях.
|
||||||
|
|
||||||
|
## Структура хранилища
|
||||||
|
|
||||||
|
```
|
||||||
|
/opt/hermes/email/
|
||||||
|
├── INBOX/
|
||||||
|
│ ├── YYYY/MM/UID/
|
||||||
|
│ │ ├── email.md # YAML-frontmatter + тело письма
|
||||||
|
│ │ └── attachments/ # вложения
|
||||||
|
│ └── ...
|
||||||
|
├── Отправленные/...
|
||||||
|
├── Archive/...
|
||||||
|
├── Sent/...
|
||||||
|
├── state/
|
||||||
|
│ └── mail-archive-last-*.json # last_uid per folder
|
||||||
|
└── contacts/ # адресная книга (извлечение через LLM)
|
||||||
|
├── contacts.vcf # vCard 4.0 для импорта
|
||||||
|
├── contacts.json # машинный формат
|
||||||
|
├── index.json # email → contact_id
|
||||||
|
└── last_scan.json # трекинг обработанных писем (UID + mtime)
|
||||||
|
```
|
||||||
|
|
||||||
|
Формат email.md — YAML-frontmatter:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
id: 255
|
||||||
|
folder: INBOX
|
||||||
|
subject: "Re: ..."
|
||||||
|
from: "Name <addr>"
|
||||||
|
to: "Name <addr>"
|
||||||
|
date: "2025-07-10 11:51+03:00"
|
||||||
|
flags: ["Seen"]
|
||||||
|
has_attachment: false
|
||||||
|
message_id: <...@domain.ru>
|
||||||
|
in_reply_to: <...@domain.ru>
|
||||||
|
references: <...> <...>
|
||||||
|
cc: "Name <addr>"
|
||||||
|
content_type: multipart/mixed; boundary=...
|
||||||
|
---
|
||||||
|
Body text here...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Компоненты
|
||||||
|
|
||||||
|
| Компонент | Путь | Назначение |
|
||||||
|
|-----------|------|------------|
|
||||||
|
| Архиватор | `/opt/hermes/email-assistant/scripts/mail_archive.py` | Тупой насос: himalaya → email.md. Без LLM. |
|
||||||
|
| Индексатор | `/opt/hermes/email-assistant/scripts/mail_index.py` | SQLite-индекс всех email.md для быстрого поиска |
|
||||||
|
| Поиск (FTS5) | `/opt/hermes/email-assistant/scripts/sqlite_search.py` | Полнотекстовый поиск по SQLite-индексу |
|
||||||
|
| Contacts Extractor | `/opt/hermes/email-assistant/scripts/contacts_extractor.py` | LLM-парсинг подписей через Qwen3:8b |
|
||||||
|
| Дайджест | `/opt/hermes/email-assistant/scripts/digest.py` | Еженедельный дайджест почты через Qwen3:8b |
|
||||||
|
| Shell-обёртка | `/opt/hermes/email-assistant/scripts/mail-archive.sh` | Для systemd/cron |
|
||||||
|
| Документация | `/opt/hermes/email-assistant/context/CONTACTS.md` | Архитектура, промпт, формат vCard |
|
||||||
|
|
||||||
|
## SQLite-индекс (mail_index.py + sqlite_search.py)
|
||||||
|
|
||||||
|
Быстрый поиск по архиву без grep. База: `/opt/hermes/email/mail_index.db`.
|
||||||
|
|
||||||
|
**Схема:** таблица `emails` (2073 записи) + FTS5 virtual table `email_fts` для полнотекстового поиска. Триггеры синхронизируют FTS5 при INSERT/UPDATE/DELETE. Индексы: folder, uid, contacts_extracted, date.
|
||||||
|
|
||||||
|
**Контракт с contacts_extractor:** поля `contacts_extracted` (0/1) и `contacts_skipped` (0/1) — общие. mail_index.py создаёт схему, contacts_extractor.py пишет флаги.
|
||||||
|
|
||||||
|
**Поиск:**
|
||||||
|
```bash
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/sqlite_search.py 'Стороженко'
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/sqlite_search.py 'битрикс OR контрагент'
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/sqlite_search.py 'from:example@mail'
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/sqlite_search.py --folder 'INBOX/!Отчеты'
|
||||||
|
```
|
||||||
|
|
||||||
|
Операторы FTS5: AND (по умолчанию), OR, `"точная фраза"`, `-исключить`, `prefix*`.
|
||||||
|
|
||||||
|
Подробнее: `references/sqlite-index-architecture.md`
|
||||||
|
|
||||||
|
## Дайджест почты (digest.py)
|
||||||
|
|
||||||
|
Еженедельный дайджест через Qwen3:8b. Выборка из SQLite за N дней, группировка по папкам, LLM-генерация краткого обзора на русском. Сохраняется в `/opt/hermes/email/digests/digest-YYYY-MM-DD.md`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/digest.py # 7 дней
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/digest.py --days 14
|
||||||
|
```
|
||||||
|
|
||||||
|
Подробнее: `references/digest-pipeline.md`
|
||||||
|
|
||||||
|
## Пайплайн (полный)
|
||||||
|
|
||||||
|
```
|
||||||
|
mail_archive.py ──→ INBOX/UID/email.md (тупой насос, без LLM)
|
||||||
|
↓
|
||||||
|
contacts_extractor.py (LLM через delegate_task)
|
||||||
|
↓
|
||||||
|
/opt/hermes/email/contacts/
|
||||||
|
├── contacts.vcf ← vCard 4.0, импорт в любой клиент
|
||||||
|
├── contacts.json ← машинная база (дедупликация)
|
||||||
|
├── index.json ← email → contact_id
|
||||||
|
└── last_scan.json ← трекинг обработанных
|
||||||
|
```
|
||||||
|
|
||||||
|
### Contacts Extractor: ключевые решения
|
||||||
|
|
||||||
|
| Вопрос | Решение |
|
||||||
|
|--------|---------|
|
||||||
|
| Body целиком или последние N строк? | **Целиком** — контекст для точного распознавания подписи |
|
||||||
|
| Поле department? | **Нет** — достаточно company + position |
|
||||||
|
| vCard версия? | **4.0** — соцсети, фото, расширенные поля |
|
||||||
|
| Какие папки обрабатывать? | **Только входящие** (INBOX + подпапки) |
|
||||||
|
| Как трекать обработанные? | **UID + mtime** — UID для быстрого skip, mtime для отлова запоздалых писем |
|
||||||
|
|
||||||
|
### Промпт для LLM (Qwen3:8b через Ollama)
|
||||||
|
|
||||||
|
```
|
||||||
|
Ты — экстрактор контактов. Извлеки данные отправителя из подписи письма.
|
||||||
|
|
||||||
|
Отправитель (для сверки): {from_name} <{from_email}>
|
||||||
|
|
||||||
|
Найди подпись. Она обычно:
|
||||||
|
- После "-- \n", "---\n", "Best regards,", "Kind regards,"
|
||||||
|
- После "С уважением,", "С наилучшими пожеланиями,"
|
||||||
|
- После "С ув.,", "Всего доброго,"
|
||||||
|
- Если разделителя нет — последние 5-15 строк
|
||||||
|
|
||||||
|
НЕ путай подпись с:
|
||||||
|
- Цитируемой предыдущей перепиской (строки с ">" или "On ... wrote:")
|
||||||
|
- Пересланным сообщением ("— Пересылаемое сообщение —")
|
||||||
|
- Дисклеймером/конфиденциальностью внизу письма
|
||||||
|
|
||||||
|
Верни JSON:
|
||||||
|
{
|
||||||
|
"full_name": null, // Полное имя (ФИО)
|
||||||
|
"phone": null, // Основной телефон
|
||||||
|
"phone_secondary": null, // Дополнительный телефон
|
||||||
|
"position": null, // Должность
|
||||||
|
"company": null, // Компания/организация
|
||||||
|
"address": null, // Адрес (почтовый/юридический)
|
||||||
|
"signature_found": false // Была ли подпись вообще
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Основные команды
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Архивация INBOX (10 писем за раз для bulk sync)
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/mail_archive.py --folder INBOX --limit 10
|
||||||
|
|
||||||
|
# Архивация всех папок
|
||||||
|
python3 /opt/hermes/email-assistant/scripts/mail_archive.py --all --limit 10
|
||||||
|
|
||||||
|
# Поиск по архиву (быстрый — локальный диск)
|
||||||
|
grep -ril 'тема' /opt/hermes/email/**/email.md 2>/dev/null
|
||||||
|
|
||||||
|
# Статус архива
|
||||||
|
cat /opt/hermes/email/state/mail-archive-last-*.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Проблема: хардкод подпапок INBOX (18 из 137)
|
||||||
|
|
||||||
|
**Статус:** ❌ Не решено — задача зафиксирована в STATUS.md как Фаза 1.7.
|
||||||
|
|
||||||
|
**Проблема:** `mail_archive.py` содержит захардкоженный список `INBOX_SUBFOLDERS` (18 папок),
|
||||||
|
но на IMAP-сервере реально **137 подпапок INBOX**, включая многоуровневые глубиной 2-3:
|
||||||
|
|
||||||
|
```
|
||||||
|
INBOX/!Персонал/ОТ и ТБ
|
||||||
|
INBOX/Бюджет/Винный город/CAPEX 2025
|
||||||
|
INBOX/Контрагенты/iiko/Тихая гавань
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Сервер
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
**Требуется:** динамическое обнаружение IMAP-папок через `himalaya folder list`,
|
||||||
|
рекурсивный обход всех подпапок INBOX (любой глубины), автоматическая архивация
|
||||||
|
новых подпапок при их создании.
|
||||||
|
|
||||||
|
**План исправления:**
|
||||||
|
1. Заменить хардкод `INBOX_SUBFOLDERS` на вызов `himalaya folder list` с парсингом JSON
|
||||||
|
2. Фильтровать только папки, начинающиеся с `INBOX/` (не трогать Trash, Drafts, RSS и т.д.)
|
||||||
|
3. Рекурсивно архивировать все уровни вложенности
|
||||||
|
4. `mail-archive-every-5min` cron должен обновлять список папок динамически каждый раз
|
||||||
|
5. State-файлы уже поддерживают произвольные имена папок (через хэш MD5 для не-ASCII)
|
||||||
|
|
||||||
|
Подробнее: `references/dynamic-folder-discovery.md`
|
||||||
|
|
||||||
|
## Bulk-sync cron strategy
|
||||||
|
|
||||||
|
Двухфазный подход для переноса архива:
|
||||||
|
|
||||||
|
| Фаза | Период | Лимит | Параметры cron |
|
||||||
|
|------|--------|-------|----------------|
|
||||||
|
| **Bulk sync** (слив существующего архива) | Каждые 5 мин | 10 писем на папку | `no_agent=True`, `script=` |
|
||||||
|
| **Incremental** (только новые письма) | Каждые 30 мин | 50-100 | `no_agent=True`, `script=` |
|
||||||
|
|
||||||
|
В bulk-фазе лимит маленький (10), чтобы:
|
||||||
|
- Не превышать таймаут при медленных папках
|
||||||
|
- Не перегружать IMAP-сервер
|
||||||
|
- Равномерно распределять нагрузку на все 22 папки
|
||||||
|
|
||||||
|
Когда state-файлы перестают обновляться (все письма заархивированы) — переключить на incremental.
|
||||||
|
|
||||||
|
### no_agent cron (рекомендуемый паттерн)
|
||||||
|
|
||||||
|
Для скриптовых recurring-задач без LLM:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Создать скрипт в ~/.hermes/scripts/
|
||||||
|
cat > ~/.hermes/scripts/mail-archive.sh << 'SCRIPT'
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
cd /opt/hermes/email-assistant
|
||||||
|
exec python3 scripts/mail_archive.py --all --limit 10
|
||||||
|
SCRIPT
|
||||||
|
|
||||||
|
# Создать cron
|
||||||
|
hermes cron create \
|
||||||
|
--name "mail-archive-every-5min" \
|
||||||
|
--schedule "every 5m" \
|
||||||
|
--script mail-archive.sh \
|
||||||
|
--no-agent
|
||||||
|
|
||||||
|
# Обновить для incremental
|
||||||
|
hermes cron update <id> --schedule "every 30m" --script mail-archive.sh --no-agent
|
||||||
|
```
|
||||||
|
|
||||||
|
**Важно:** `script` должен быть относительным путём в `~/.hermes/scripts/`.
|
||||||
|
Абсолютные пути не принимаются.
|
||||||
|
|
||||||
|
### Shell wrapper с per-folder timeouts
|
||||||
|
|
||||||
|
При обработке 22+ папок одна медленная папка не должна валить весь запуск.
|
||||||
|
Скрипт-обёртка обрабатывает каждую папку с отдельным `timeout`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
cd /opt/hermes/email-assistant
|
||||||
|
|
||||||
|
TIMEOUT=60
|
||||||
|
LIMIT=10
|
||||||
|
|
||||||
|
FOLDERS=(
|
||||||
|
"INBOX" "Отправленные" "Archive" "Sent"
|
||||||
|
"INBOX/!Scan" "INBOX/!Битрикс" "INBOX/!ВГ Чек листы"
|
||||||
|
"INBOX/!Документооборот" "INBOX/!Завки" "INBOX/!Материалы"
|
||||||
|
"INBOX/!Отчеты" "INBOX/!Персонал" "INBOX/!Протоколы"
|
||||||
|
"INBOX/!Реестр оплаты" "INBOX/!Торик" "INBOX/Бюджет"
|
||||||
|
"INBOX/Контрагенты" "INBOX/ЛНД" "INBOX/Организация работы"
|
||||||
|
"INBOX/Приемка и стройка" "INBOX/Системы" "INBOX/Эксплуатация"
|
||||||
|
)
|
||||||
|
|
||||||
|
for folder in "${FOLDERS[@]}"; do
|
||||||
|
echo "[$folder] start..."
|
||||||
|
out=$(timeout $TIMEOUT python3 scripts/mail_archive.py --folder "$folder" --limit $LIMIT 2>&1) || true
|
||||||
|
echo "$out"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contacts Extractor: реализация
|
||||||
|
|
||||||
|
### Инкрементальное сохранение (save_progress)
|
||||||
|
|
||||||
|
Раньше скрипт писал все файлы только в конце — при таймауте (600с на 354 письма при Qwen3:8b) весь прогресс терялся.
|
||||||
|
|
||||||
|
**Решение:** `save_progress()` вызывается после каждой обработанной папки:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_progress(contacts_db, contacts_dir, processed_uids, processed_emails):
|
||||||
|
contacts_db["contacts"].sort(key=lambda c: c.get("email", ""))
|
||||||
|
save_json(contacts_dir / "contacts.json", contacts_db)
|
||||||
|
save_json(contacts_dir / "index.json", contacts_db.get("by_email", {}))
|
||||||
|
generate_vcard(contacts_dir, contacts_db["contacts"])
|
||||||
|
last_scan = {
|
||||||
|
"last_processed": datetime.now().isoformat(timespec="seconds"),
|
||||||
|
"processed_uids": processed_uids,
|
||||||
|
"processed_emails": sorted(processed_emails),
|
||||||
|
}
|
||||||
|
save_json(contacts_dir / "last_scan.json", last_scan)
|
||||||
|
```
|
||||||
|
|
||||||
|
### --limit для batch-запусков
|
||||||
|
|
||||||
|
Для локальной Qwen3:8b на CPU (~15-20 сек на письмо) полный прогон 354 писем
|
||||||
|
занимает >1.5 часа. Добавлен `--limit`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/contacts_extractor.py --limit 15 # ~5 мин на CPU
|
||||||
|
python3 scripts/contacts_extractor.py --limit 50 # ~2 мин на GPU
|
||||||
|
```
|
||||||
|
|
||||||
|
Лимит считается на все папки суммарно. После каждой папки — `save_progress()`.
|
||||||
|
|
||||||
|
### None-safety при работе с JSON
|
||||||
|
|
||||||
|
Qwen через Ollama может вернуть JSON с `null` значениями. Python `.get(key, "")` возвращает `None` (не `""`), если ключ существует со значением `null`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# ❌ Падает с AttributeError: 'NoneType' object has no attribute 'strip'
|
||||||
|
full_name = llm_result.get("full_name", "").strip()
|
||||||
|
|
||||||
|
# ✅ Безопасно
|
||||||
|
full_name = (llm_result.get("full_name") or "").strip()
|
||||||
|
```
|
||||||
|
|
||||||
|
### Отсутствующий import hashlib
|
||||||
|
|
||||||
|
Скрипт использовал `hashlib.md5()` в `contact_id()` без импорта — падение при первом вызове. Исправлено добавлением `import hashlib`.
|
||||||
|
|
||||||
|
### Очистка тела письма перед LLM (clean_body)
|
||||||
|
|
||||||
|
Перед отправкой в LLM тело письма проходит очистку. Ключевые этапы:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def clean_body(body):
|
||||||
|
# Удаляем <#part ...> блоки
|
||||||
|
body = re.sub(r'<#part[^>]*>', '', body)
|
||||||
|
body = re.sub(r'<#/part>', '', body)
|
||||||
|
# Удаляем HTML-теги
|
||||||
|
body = re.sub(r'<[^>]+>', '', body)
|
||||||
|
# Удаляем mailto: ссылки
|
||||||
|
body = re.sub(r'\\(mailto:[^)]+\\)', '', body)
|
||||||
|
# Заменяем unicode-пробелы (NBSP, zero-width) на обычные
|
||||||
|
body = re.sub(r'[\\u00a0\\u2000-\\u200f\\u2028-\\u202f\\u2060]+', ' ', body)
|
||||||
|
# Удаляем трекинг-ссылки
|
||||||
|
body = re.sub(r'https?://tn-eoc\\.[^\\s]+', '', body)
|
||||||
|
body = re.sub(r'https?://[^\\s]+\\?utm_[^\\s]+', '', body)
|
||||||
|
# Отрезаем цитируемую переписку — ищем САМЫЙ РАННИЙ маркер цитирования
|
||||||
|
quote_patterns = [
|
||||||
|
r'^[\\s]*_{4,}\\s*$', # _____
|
||||||
|
r'От:.*\\n[\\s]*Отправлено:', # Russian Outlook (в любом месте строки)
|
||||||
|
r'^[\\s]*From:.*\\n[\\s]*Sent:', # English Outlook headers
|
||||||
|
r'——-.*Forwarded.*——-',
|
||||||
|
r'——-.*Пересылаемое.*——-',
|
||||||
|
r'——-.*Original Message.*——-',
|
||||||
|
r'>.*\\bwrote:',
|
||||||
|
]
|
||||||
|
earliest = None
|
||||||
|
earliest_pos = len(body)
|
||||||
|
for qp in quote_patterns:
|
||||||
|
for m in re.finditer(qp, body, re.MULTILINE):
|
||||||
|
if m.start() < earliest_pos:
|
||||||
|
earliest_pos = m.start()
|
||||||
|
earliest = m
|
||||||
|
if earliest:
|
||||||
|
body = body[:earliest_pos].strip()
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ключевое изменение:** вместо `re.search()` по списку (первый сработавший) — `re.finditer()` по ВСЕМ паттернам, выбор самого раннего матча. Это критично для писем с двумя фрагментами цитирования (например, ответ на forwarded message), где второй матч (`From: ... Sent:`) срабатывает раньше первого (`От: Стороженко`), потому что `От:` не в начале строки.
|
||||||
|
|
||||||
|
**Fallback:** если ни один паттерн не совпал — ищем любой Outlook-заголовок (`От:`, `Отправлено:`, `From:`, `Sent:`, `Кому:`, `Subject:`) в последних 500 символах. Это ловит подписи, где `От:` вшит в строку с телефоном: `+7 962 854 22 01 От: Стороженко`
|
||||||
|
|
||||||
|
### Парсинг JSON из ответа LLM (brace-depth)
|
||||||
|
|
||||||
|
Qwen3:8b через Ollama может обрезать JSON на лимите `num_predict` или добавить
|
||||||
|
пояснения. Вместо `re.search(r"\{.*\}", ..., re.DOTALL)` — парсинг по глубине
|
||||||
|
скобок:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Пробуем распарсить весь ответ как JSON
|
||||||
|
try:
|
||||||
|
return json.loads(response_text)
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Если не получилось — ищем { ... } внутри
|
||||||
|
brace_depth = 0
|
||||||
|
json_start = None
|
||||||
|
for i, ch in enumerate(response_text):
|
||||||
|
if ch == '{':
|
||||||
|
if brace_depth == 0:
|
||||||
|
json_start = i
|
||||||
|
brace_depth += 1
|
||||||
|
elif ch == '}':
|
||||||
|
brace_depth -= 1
|
||||||
|
if brace_depth == 0 and json_start is not None:
|
||||||
|
try:
|
||||||
|
return json.loads(response_text[json_start:i+1])
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
pass
|
||||||
|
json_start = None
|
||||||
|
```
|
||||||
|
|
||||||
|
### Retry при пустых ответах Ollama
|
||||||
|
|
||||||
|
Qwen3:8b иногда возвращает `response=""` (пустая строка) на длинных промптах.
|
||||||
|
Стандартный retry (2-3 попытки с `time.sleep(1)`) решает проблему.
|
||||||
|
|
||||||
|
### Проблема: num_predict=512 недостаточно
|
||||||
|
|
||||||
|
Телефон + должность + компания не помещаются в 512 токенов для русского текста.
|
||||||
|
Увеличено до 1024.
|
||||||
|
|
||||||
|
### Экранирование JSON в промпте
|
||||||
|
|
||||||
|
При использовании `str.format()` фигурные скобки в JSON-примере внутри промпта
|
||||||
|
конфликтуют с шаблоном. Решение — двойные скобки `{{...}}` для литеральных
|
||||||
|
`{...}` в шаблоне:
|
||||||
|
|
||||||
|
```python
|
||||||
|
PROMPT_TEMPLATE = """...Верни ТОЛЬКО JSON, без пояснений:
|
||||||
|
{{"full_name": "...", "email": null, ...}}
|
||||||
|
{body}"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Обработка reply/forward писем
|
||||||
|
|
||||||
|
В reply/forward письмах подпись может принадлежать НЕ отправителю в `From:`.
|
||||||
|
Например: Головлев пересылает письмо Елены Стороженко — её подпись в теле.
|
||||||
|
Это нормально — контакт Елены всё равно ценный. LLM не пытается сверять
|
||||||
|
отправителя с извлечёнными данными.
|
||||||
|
|
||||||
|
## Оптимизация pagination
|
||||||
|
|
||||||
|
### Проблема
|
||||||
|
`get_envelopes()` изначально тащил ВСЕ страницы INBOX (58 страниц × 200 писем = ~11559)
|
||||||
|
через SOCKS5 — это висло на 60+ секунд и никогда не доходило до архивации.
|
||||||
|
|
||||||
|
### Решение
|
||||||
|
```python
|
||||||
|
def get_envelopes(folder, limit=100, last_uid=0):
|
||||||
|
"""Ранняя остановка pagination при достижении лимита ИЛИ если все
|
||||||
|
письма на странице уже обработаны (UID <= last_uid)."""
|
||||||
|
page_size = 500 # 1 страница покрывает лимит
|
||||||
|
# ...
|
||||||
|
# Хватит — не тащим остальные страницы
|
||||||
|
if total_new >= limit:
|
||||||
|
break
|
||||||
|
# Если все письма на этой странице старые — дальше только старее
|
||||||
|
last_batch_min = min(int(e.get("uid")...) for e in batch)
|
||||||
|
if last_batch_min <= last_uid:
|
||||||
|
break
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ключевое:** одна страница `page_size=500` покрывает `limit=10` с запасом.
|
||||||
|
Искать на последующих страницах нужно только если на этой меньше лимита новых писем.
|
||||||
|
|
||||||
|
## Cron orchestration
|
||||||
|
|
||||||
|
Два независимых cron-пайплайна поверх общего хранилища — см.
|
||||||
|
`references/cron-workflows.md` для полной документации:
|
||||||
|
|
||||||
|
| Пайплайн | Расписание | Скрипт | `no_agent` | LLM |
|
||||||
|
|-----------|-----------|--------|------------|-----|
|
||||||
|
| Архивация | `every 5m` | `mail-archive.sh` | ✅ Да | ❌ Нет |
|
||||||
|
| Контакты | `every 30m` | `contacts-cron.sh` | ❌ Нет | ✅ Qwen3:8b |
|
||||||
|
|
||||||
|
**Ключевые правила для cron с LLM:**
|
||||||
|
- Контакты НЕ используют `--no-agent` — LLM-вызовы внутри Python-скрипта
|
||||||
|
работают и без агента, но без агента результат не доставляется
|
||||||
|
- `--limit` рассчитан на скорость Qwen3:8b: CPU = 15-20s/email → limit 15
|
||||||
|
- Контакты всегда остаются инкрементальными (UID-трекинг в `last_scan.json`)
|
||||||
|
|
||||||
|
## Скорость Qwen3:8b как planning-ограничение
|
||||||
|
|
||||||
|
Локальная Qwen3:8b через Ollama — бутылочное горлышко для contacts extractor:
|
||||||
|
|
||||||
|
| Окружение | Время на письмо | limit за 5 мин | limit за 30 мин |
|
||||||
|
|-----------|----------------|----------------|-----------------|
|
||||||
|
| CPU (только процессор) | 15-20 с | 15 | 90 |
|
||||||
|
| GPU (NVIDIA/AMD) | 2-3 с | 100 | 600 |
|
||||||
|
|
||||||
|
**Никогда не пытаться прогнать все 354 письма INBOX за один запуск при CPU.**
|
||||||
|
Использовать `--limit` + cron (каждые 30 мин) для инкрементальной обработки.
|
||||||
|
|
||||||
|
## Поведение агента
|
||||||
|
|
||||||
|
### Когда архив был на Yandex Disk (WebDAV davfs2)
|
||||||
|
Сейчас архив на `/opt/hermes/email/` — локальный диск, быстрый. Но код
|
||||||
|
исторически работал с `/mnt/yandex-disk/` — медленным WebDAV. Если архив
|
||||||
|
снова окажется на WebDAV:
|
||||||
|
|
||||||
|
- **Не делать** `rm -rf` на вложенных папках — шлёт HTTP DELETE на каждый файл
|
||||||
|
- **Не делать** `find` на всём архиве — таймаутится
|
||||||
|
- **Партии по 5-10 писем** за один запуск
|
||||||
|
- **Делегировать batch-операции** локальной Qwen3:8b через `delegate_task`
|
||||||
|
|
||||||
|
### Текущий архив (локальный диск)
|
||||||
|
- Батчи по 50-500 писем — диск быстрый
|
||||||
|
- `grep` работает мгновенно
|
||||||
|
- `find` / `rm` — без ограничений
|
||||||
|
|
||||||
|
## Himalaya: несколько аккаунтов
|
||||||
|
|
||||||
|
Конфиг может содержать несколько почтовых аккаунтов. Для переключения:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
himalaya envelope list --account <name> --limit 10
|
||||||
|
# или через переменную окружения:
|
||||||
|
HIMALAYA_ACCOUNT=hermes himalaya envelope list --limit 10
|
||||||
|
```
|
||||||
|
|
||||||
|
При добавлении нового аккаунта:
|
||||||
|
- Скопировать блок `[accounts.<name>]`, заменить данные
|
||||||
|
- Если нужен SMTP — добавить `[accounts.<name>.message.send]`
|
||||||
|
- Порт и шифрование подбираются под провайдера: STARTTLS (порт 143 для IMAP, 587 для SMTP) vs TLS (993/465)
|
||||||
|
- Только один аккаунт может быть `default = true`
|
||||||
|
|
||||||
|
Документированные провайдеры:
|
||||||
|
- **Jino (jino.ru):** `references/jino-server-setup.md` — порты, auth, диагностика
|
||||||
|
|
||||||
|
## Правила
|
||||||
|
|
||||||
|
- НЕ изменять файлы архива без явной команды
|
||||||
|
- НЕ переписывать логику архивации сырыми командами Himalaya
|
||||||
|
- Пароль в `backend.auth.raw` в конфиге — не показывать в логах
|
||||||
|
- **Contacts Extractor — отдельный pipeline, НЕ внутри архиватора.** Не вызывать
|
||||||
|
LLM в `mail_archive.py`. Архиватор должен оставаться тупым насосом.
|
||||||
@@ -0,0 +1,237 @@
|
|||||||
|
# Contacts Extractor — архитектура и промпт
|
||||||
|
|
||||||
|
## Концепция
|
||||||
|
|
||||||
|
**Не внутри архиватора.** Архиватор (`mail_archive.py`) — тупой насос:
|
||||||
|
забрал письмо → сохранил `email.md`. Без LLM. Иначе архивация встаёт
|
||||||
|
на каждом письме (1-3 сек на Qwen), и при перезапуске парсит заново.
|
||||||
|
|
||||||
|
## Pipeline
|
||||||
|
|
||||||
|
```
|
||||||
|
mail_archive.py ──→ INBOX/UID/email.md (тупой насос, без LLM)
|
||||||
|
↓
|
||||||
|
contacts_extractor.py (LLM через Qwen3:8b Ollama)
|
||||||
|
↓
|
||||||
|
/opt/hermes/email/contacts/
|
||||||
|
├── contacts.vcf ← vCard 4.0 для импорта
|
||||||
|
├── contacts.json ← машинная база
|
||||||
|
├── index.json ← email → contact_id
|
||||||
|
└── last_scan.json ← трекинг (UID + mtime)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Принятые решения
|
||||||
|
|
||||||
|
| Вопрос | Решение |
|
||||||
|
|--------|---------|
|
||||||
|
| Body целиком или последние N строк? | **Целиком** — контекст для точной подписи |
|
||||||
|
| Поле department? | **Нет** — company + position достаточно |
|
||||||
|
| vCard версия? | **4.0** (RFC 6350) — соцсети, фото |
|
||||||
|
| Какие папки? | **Только входящие** (INBOX + подпапки) |
|
||||||
|
| Трекинг обработанных | **Комбинированный** — UID для быстрой фильтрации + mtime для запоздалых |
|
||||||
|
|
||||||
|
## Логика extractor'a
|
||||||
|
|
||||||
|
1. Читает `last_scan.json` — какие UID уже обработаны по каждой папке
|
||||||
|
2. Сканирует `INBOX/**/email.md`. Для каждого:
|
||||||
|
- Если UID ≤ last_uid → skip
|
||||||
|
- Если email отправителя уже есть в `contacts.by_email` → skip (или обновить
|
||||||
|
если last_seen > 30 дней)
|
||||||
|
- Если mtime файла новее last_scan → обработать
|
||||||
|
3. Очищает body (clean_body), передаёт Qwen3:8b через Ollama API
|
||||||
|
4. Сохраняет результат, обновляет index.json, пересобирает contacts.vcf
|
||||||
|
|
||||||
|
## Реализация call_llm
|
||||||
|
|
||||||
|
```python
|
||||||
|
def call_llm(body_text, max_retries=2):
|
||||||
|
"""Вызвать Qwen через Ollama API, вернуть JSON."""
|
||||||
|
|
||||||
|
# Варианты API: http://localhost:11434/api/generate (generate)
|
||||||
|
# или http://localhost:11434/api/chat (chat)
|
||||||
|
# Используем generate (не chat) — ответ "response" поле
|
||||||
|
|
||||||
|
# Полный пример:
|
||||||
|
import json, urllib.request
|
||||||
|
|
||||||
|
body_text = clean_body(body_text) # очистка HTML
|
||||||
|
truncated = body_text[:MAX_BODY_CHARS] # обрезка
|
||||||
|
prompt = PROMPT_TEMPLATE.format(body=truncated)
|
||||||
|
|
||||||
|
for attempt in range(max_retries + 1):
|
||||||
|
payload = json.dumps({
|
||||||
|
"model": "qwen3:8b",
|
||||||
|
"prompt": prompt,
|
||||||
|
"stream": False,
|
||||||
|
"options": {
|
||||||
|
"temperature": 0.1,
|
||||||
|
"num_predict": 1024, # минимум 1024 — 512 не хватает
|
||||||
|
}
|
||||||
|
}).encode("utf-8")
|
||||||
|
|
||||||
|
req = urllib.request.Request(
|
||||||
|
"http://localhost:11434/api/generate",
|
||||||
|
data=payload,
|
||||||
|
headers={"Content-Type": "application/json"},
|
||||||
|
method="POST",
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
resp = urllib.request.urlopen(req, timeout=30)
|
||||||
|
data = json.loads(resp.read().decode("utf-8"))
|
||||||
|
response_text = data.get("response", "").strip()
|
||||||
|
except Exception:
|
||||||
|
if attempt < max_retries:
|
||||||
|
continue
|
||||||
|
return None
|
||||||
|
|
||||||
|
# Парсинг JSON: try полный → brace-depth → fail
|
||||||
|
try:
|
||||||
|
return json.loads(response_text)
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Brace-depth парсер (не re.DOTALL — обрезанный JSON)
|
||||||
|
brace_depth = 0
|
||||||
|
json_start = None
|
||||||
|
for i, ch in enumerate(response_text):
|
||||||
|
if ch == '{':
|
||||||
|
if brace_depth == 0:
|
||||||
|
json_start = i
|
||||||
|
brace_depth += 1
|
||||||
|
elif ch == '}':
|
||||||
|
brace_depth -= 1
|
||||||
|
if brace_depth == 0 and json_start is not None:
|
||||||
|
try:
|
||||||
|
return json.loads(response_text[json_start:i+1])
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
pass
|
||||||
|
json_start = None
|
||||||
|
|
||||||
|
if attempt < max_retries:
|
||||||
|
continue
|
||||||
|
return None
|
||||||
|
```
|
||||||
|
|
||||||
|
### Почему не re.DOTALL
|
||||||
|
|
||||||
|
`re.search(r"\{.*\}", text, re.DOTALL)` жадный — захватывает ВСЁ между первой
|
||||||
|
`{` и последней `}`. Если в ответе два JSON-блока (пояснение + результат),
|
||||||
|
или JSON обрезан на середине вложенности — re.DOTALL даёт мусор.
|
||||||
|
|
||||||
|
Brace-depth парсер корректно обрабатывает:
|
||||||
|
- Обрезанный JSON (Qwen не успела закончить `}`)
|
||||||
|
- Два JSON-блока (берёт первый валидный)
|
||||||
|
- JSON с пояснениями вокруг
|
||||||
|
|
||||||
|
## Проблема с пустыми ответами Ollama
|
||||||
|
|
||||||
|
Qwen3:8b через `/api/generate` иногда возвращает `response=""`.
|
||||||
|
Причины (гипотезы):
|
||||||
|
- Конкуренция за GPU (если другой процесс жрёт VRAM)
|
||||||
|
- Длинный контекст + маленький `num_predict`
|
||||||
|
- Сбой внутри Ollama
|
||||||
|
|
||||||
|
**Решение:** retry (2-3 попытки с `time.sleep(1)`).
|
||||||
|
|
||||||
|
**Не путать:** `/api/generate` (generate) vs `/api/chat` (chat) — разные
|
||||||
|
форматы ответов.
|
||||||
|
|
||||||
|
## Очистка тела письма
|
||||||
|
|
||||||
|
Критично для распознавания подписи. HTML-мусор забивает контекст.
|
||||||
|
|
||||||
|
```python
|
||||||
|
def clean_body(body):
|
||||||
|
# Удаляем <#part ...> блоки
|
||||||
|
body = re.sub(r'<#part[^>]*>|<#/part>', '', body)
|
||||||
|
# Удаляем HTML-теги
|
||||||
|
body = re.sub(r'<[^>]+>', '', body)
|
||||||
|
# Удаляем mailto: ссылки (mailto:estorozhenko@...)
|
||||||
|
body = re.sub(r'\(mailto:[^)]+\)', '', body)
|
||||||
|
# Заменяем unicode-пробелы (NBSP \u00a0, zero-width \u2060 и др.)
|
||||||
|
body = re.sub(r'[\u00a0\u2000-\u200f\u2028-\u202f\u2060]+', ' ', body)
|
||||||
|
# Удаляем трекинг-пиксели и UTM-ссылки
|
||||||
|
body = re.sub(r'https?://tn-eoc\.[^\s]+', '', body)
|
||||||
|
body = re.sub(r'https?://[^\s]+\?utm_[^\s]+', '', body)
|
||||||
|
# Схлопываем пустые строки
|
||||||
|
body = re.sub(r'\n{3,}', '\n\n', body)
|
||||||
|
return body.strip()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Промпт для LLM
|
||||||
|
|
||||||
|
```text
|
||||||
|
Ты — экстрактор контактных данных из писем. Твоя задача — найти подпись
|
||||||
|
отправителя в конце письма и извлечь структурированные данные.
|
||||||
|
|
||||||
|
Правила поиска подписи:
|
||||||
|
- Подпись обычно отделена от тела письма разделителями:
|
||||||
|
"-- \\n", "---\\n", "С уважением,", "С наилучшими пожеланиями,",
|
||||||
|
"Best regards,", "Kind regards,", "С ув.,", "—————"
|
||||||
|
- Если разделителя нет — последние 5-15 строк письма это подпись
|
||||||
|
- Не путай подпись с цитируемым текстом переписки
|
||||||
|
(обычно начинается с ">" или "On ... wrote:" или "— Пересылаемое сообщение —")
|
||||||
|
- Ignore boilerplate (disclaimers, confidentiality notices)
|
||||||
|
|
||||||
|
Извлеки из подписи:
|
||||||
|
1. full_name — полное имя (ФИО)
|
||||||
|
2. email — email адрес (если есть в подписи, иначе null)
|
||||||
|
3. phone — основной телефон
|
||||||
|
4. phone_secondary — дополнительный телефон (если есть)
|
||||||
|
5. position — должность
|
||||||
|
6. company — название компании/организации
|
||||||
|
7. address — почтовый/юридический адрес (если есть)
|
||||||
|
8. raw_signature — полный текст найденной подписи (для отладки)
|
||||||
|
|
||||||
|
Если никакой подписи не найдено — верни только full_name и email,
|
||||||
|
остальные поля null.
|
||||||
|
|
||||||
|
Верни ТОЛЬКО JSON, без пояснений:
|
||||||
|
{"full_name": "...", "email": null, ...}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Экранирование JSON в Python str.format()
|
||||||
|
|
||||||
|
При использовании `str.format()` фигурные скобки в JSON-примере внутри промпта
|
||||||
|
конфликтуют с шаблоном. Решение — двойные скобки `{{...}}` для литеральных
|
||||||
|
`{...}` в шаблоне:
|
||||||
|
|
||||||
|
```python
|
||||||
|
PROMPT_TEMPLATE = """...Верни ТОЛЬКО JSON, без пояснений:
|
||||||
|
{{"full_name": "...", "email": null, ...}}
|
||||||
|
...
|
||||||
|
{body}"""
|
||||||
|
```
|
||||||
|
|
||||||
|
## Формат vCard 4.0
|
||||||
|
|
||||||
|
```
|
||||||
|
BEGIN:VCARD
|
||||||
|
VERSION:4.0
|
||||||
|
FN:Иванов Иван Иванович
|
||||||
|
N:Иванов;Иван;Иванович;;;
|
||||||
|
EMAIL;TYPE=WORK:ivan@example.com
|
||||||
|
TEL;TYPE=WORK:+7-123-456-78-90
|
||||||
|
TITLE:Генеральный директор
|
||||||
|
ORG:ООО "Ромашка"
|
||||||
|
ADR;TYPE=WORK:;;ул. Ленина, д.1;Москва;;123456;Россия
|
||||||
|
NOTE:Извлечено из письма от 2026-07-16 (UID 11559, INBOX)
|
||||||
|
END:VCARD
|
||||||
|
```
|
||||||
|
|
||||||
|
## Дедупликация
|
||||||
|
|
||||||
|
1. **email — primary key.** Если контакт с таким email уже есть → обновить поля
|
||||||
|
(телефон мог поменяться, должность — повысили).
|
||||||
|
2. Если email нет, но совпадает full_name (fuzzy) — создать новый, но
|
||||||
|
зафиксировать в `note` возможный дубль.
|
||||||
|
3. Если нет ни email, ни full_name — не сохранять.
|
||||||
|
4. `first_seen` / `last_seen` в контакте для понимания актуальности.
|
||||||
|
|
||||||
|
## Обработка reply/forward писем
|
||||||
|
|
||||||
|
В reply/forward письмах подпись может принадлежать НЕ отправителю в `From:`.
|
||||||
|
Например: Головлев пересылает письмо Елены Стороженко — её подпись в теле.
|
||||||
|
Это нормально — контакт Елены всё равно ценный. LLM не пытается сверять
|
||||||
|
отправителя с извлечёнными данными.
|
||||||
@@ -0,0 +1,142 @@
|
|||||||
|
# Cron Workflows for Email Archive
|
||||||
|
|
||||||
|
## Architecture overview
|
||||||
|
|
||||||
|
Two independent cron pipelines that share the same email storage:
|
||||||
|
|
||||||
|
```
|
||||||
|
mail-archive (every 5 min, no_agent=True)
|
||||||
|
↓
|
||||||
|
INBOX/UID/email.md ←── contacts-extractor (every 30 min, script-based, LLM)
|
||||||
|
↓
|
||||||
|
contacts.vcf + contacts.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Both use **script-based cron** (the `script=` parameter) with the script in
|
||||||
|
`~/.hermes/scripts/`. The archive job is `no_agent=True` (pure shell — no LLM
|
||||||
|
tokens consumed). The contacts job uses the agent loop because it calls LLM
|
||||||
|
internally via Python.
|
||||||
|
|
||||||
|
## Mail archive cron (bulk sync)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Script: ~/.hermes/scripts/mail-archive.sh
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
cd /opt/hermes/email-assistant
|
||||||
|
exec python3 scripts/mail_archive.py --all --limit 10
|
||||||
|
```
|
||||||
|
|
||||||
|
Cron creation:
|
||||||
|
```bash
|
||||||
|
hermes cron create \
|
||||||
|
--name "mail-archive-every-5min" \
|
||||||
|
--schedule "every 5m" \
|
||||||
|
--script mail-archive.sh \
|
||||||
|
--no-agent \
|
||||||
|
--deliver local
|
||||||
|
```
|
||||||
|
|
||||||
|
Key details:
|
||||||
|
- `no_agent=True` → pure script mode, zero LLM cost per tick
|
||||||
|
- `deliver=local` → output saved, no notification (noisy at 5min intervals)
|
||||||
|
- Script path MUST be relative in `~/.hermes/scripts/` — absolute paths rejected
|
||||||
|
- `--all --limit 10` processes all 22 folders with 10 emails per folder per tick
|
||||||
|
|
||||||
|
### Shell wrapper with per-folder timeouts
|
||||||
|
|
||||||
|
When using `--all`, one slow IMAP folder can stall the entire run. The
|
||||||
|
shell-embedded approach handles this natively — each folder gets its own
|
||||||
|
`timeout`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
FOLDERS=(INBOX "Отправленные" Archive Sent ...)
|
||||||
|
TIMEOUT=60
|
||||||
|
LIMIT=10
|
||||||
|
|
||||||
|
for folder in "${FOLDERS[@]}"; do
|
||||||
|
timeout $TIMEOUT python3 scripts/mail_archive.py --folder "$folder" --limit $LIMIT 2>&1 || true
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
This is the ACTUAL approach used in `mail-archive.sh`. The `--all` flag in
|
||||||
|
`mail_archive.py` iterates folders internally but without per-folder timeouts,
|
||||||
|
so the shell wrapper is the recommended pattern when you control the cron script.
|
||||||
|
|
||||||
|
## Contacts extractor cron (LLM-based)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Script: ~/.hermes/scripts/contacts-cron.sh
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
cd /opt/hermes/email-assistant
|
||||||
|
exec python3 scripts/contacts_extractor.py --limit 15
|
||||||
|
```
|
||||||
|
|
||||||
|
Cron creation:
|
||||||
|
```bash
|
||||||
|
hermes cron create \
|
||||||
|
--name "contacts-extractor-every-30m" \
|
||||||
|
--schedule "every 30m" \
|
||||||
|
--script contacts-cron.sh \
|
||||||
|
--deliver local
|
||||||
|
```
|
||||||
|
|
||||||
|
Key differences from archive cron:
|
||||||
|
- **NO `--no-agent`** — the contacts extractor calls LLM (Qwen3:8b via Ollama)
|
||||||
|
internally. Without the agent loop, the script runs but output isn't
|
||||||
|
delivered/visible.
|
||||||
|
- **`--limit 15`** — Qwen3:8b takes ~20s per email. 15 emails × 20s = ~5 min,
|
||||||
|
well within the 30-min window. Bump to 25-30 if Qwen is on a GPU.
|
||||||
|
- **`deliver=local`** — results saved to disk, no notification. The agent
|
||||||
|
generates a summary message on each tick.
|
||||||
|
|
||||||
|
## Transition from bulk to incremental
|
||||||
|
|
||||||
|
When state files stop advancing (all emails archived):
|
||||||
|
|
||||||
|
1. Update archive cron: smaller limit or longer interval
|
||||||
|
```bash
|
||||||
|
hermes cron update <archive-id> --schedule "every 30m"
|
||||||
|
```
|
||||||
|
2. Keep contacts cron at `every 30m` — it always processes only new emails
|
||||||
|
(UID tracking in `last_scan.json`)
|
||||||
|
|
||||||
|
## Testing cron scripts
|
||||||
|
|
||||||
|
Before scheduling, verify the script works by running it once:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
timeout 120 bash ~/.hermes/scripts/contacts-cron.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Check for:
|
||||||
|
- Exit code 0 = success; 124 = timeout (reduce `--limit`)
|
||||||
|
- Stale output = script isn't finding new files (check `last_scan.json` UIDs)
|
||||||
|
- Python import errors = missing dependencies (run `pip install -r requirements.txt`)
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
1. **Script path MUST be relative.** `--script /absolute/path` is silently
|
||||||
|
rejected. Copy the script to `~/.hermes/scripts/` and pass just the filename.
|
||||||
|
|
||||||
|
2. **Contacts cron needs the agent loop.** Unlike the pure-shell archive cron,
|
||||||
|
contacts cron must NOT have `--no-agent`. Without the agent, the LLM calls
|
||||||
|
in `contacts_extractor.py` still execute (it's Python), but the job output
|
||||||
|
is never delivered — you'd see "last_status=completed, last_output=<empty>"
|
||||||
|
even though contacts.vcf was updated.
|
||||||
|
|
||||||
|
3. **Qwen3:8b speed varies.** On CPU-only Ollama it's ~20s/email. On discrete
|
||||||
|
GPU (NVIDIA, AMD ROCm) it's ~2-3s/email. Set `--limit` accordingly:
|
||||||
|
- CPU: 10-15 emails per 5-min cron window
|
||||||
|
- GPU: 50-100 emails per 5-min window
|
||||||
|
|
||||||
|
4. **Cron jobs run from the session's last state, not a fresh login.**
|
||||||
|
Environment variables (like `PATH`) may differ. Always use absolute paths or
|
||||||
|
`cd` to the project directory in the script.
|
||||||
|
|
||||||
|
5. **`deliver=local` vs `deliver=origin`.** `local` saves output to the cron
|
||||||
|
DB only (viewable via `cronjob action=list`). `origin` sends it back to the
|
||||||
|
Hermes session that created the cron. For per-5min archive runs, `local`
|
||||||
|
avoids spam. For contacts (every 30min), consider `origin` if you want
|
||||||
|
a notification.
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
# Digest Pipeline — еженедельный дайджест почты
|
||||||
|
|
||||||
|
## Назначение
|
||||||
|
|
||||||
|
Автоматическая генерация краткого дайджеста входящей почты за период (7 дней по умолчанию) через локальную LLM.
|
||||||
|
|
||||||
|
## Компонент
|
||||||
|
|
||||||
|
`/opt/hermes/email-assistant/scripts/digest.py`
|
||||||
|
|
||||||
|
## Pipeline
|
||||||
|
|
||||||
|
1. Читает SQLite-индекс (`mail_index.db`), выбирает письма за N дней
|
||||||
|
2. Группирует по папкам
|
||||||
|
3. Формирует текстовый блок для LLM: папка → список писем (дата, отправитель, тема)
|
||||||
|
4. Вызывает Qwen3:8b через Ollama с промптом на русском
|
||||||
|
5. Сохраняет дайджест в `/opt/hermes/email/digests/digest-YYYY-MM-DD.md`
|
||||||
|
6. Выводит в stdout (флаг `--output` управляет)
|
||||||
|
|
||||||
|
## Промпт
|
||||||
|
|
||||||
|
LLM получает запрос написать краткий дайджест для руководителя:
|
||||||
|
- Статистика: сколько писем, сколько папок
|
||||||
|
- По папкам — 1-3 предложения об основных темах
|
||||||
|
- Выделить важные письма (руководство, тендеры, финансы)
|
||||||
|
- На русском, ≤300 слов, без перечисления каждого письма
|
||||||
|
- Группировать по темам, игнорировать тех.мусор
|
||||||
|
|
||||||
|
## Использование
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/digest.py # 7 дней
|
||||||
|
python3 scripts/digest.py --days 14 # 2 недели
|
||||||
|
python3 scripts/digest.py --folder INBOX # только INBOX
|
||||||
|
python3 scripts/digest.py --output stdout # только в stdout без файла
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cron
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hermes cron create \
|
||||||
|
--name "email-digest-sunday" \
|
||||||
|
--schedule "0 9 * * 0" \
|
||||||
|
--prompt "Запусти digest.py за 7 дней" \
|
||||||
|
--script /opt/hermes/email-assistant/scripts/digest.py \
|
||||||
|
--no-agent
|
||||||
|
```
|
||||||
|
|
||||||
|
## Зависимости
|
||||||
|
|
||||||
|
- `mail_index.db` — должен быть проиндексирован (mail_index.py)
|
||||||
|
- Qwen3:8b через Ollama (localhost:11434)
|
||||||
|
- ~15-20 секунд на генерацию через CPU
|
||||||
|
|
||||||
|
## Важные замечания
|
||||||
|
|
||||||
|
- `body_preview` в индексе — только 500 символов, поэтому FTS5-поиск по телу ограничен
|
||||||
|
- Для дайджеста используется только subject/from/date — тело не передаётся в LLM
|
||||||
|
- Группировка по папкам — базовая. Если нужно тематическое группирование — доработать
|
||||||
@@ -0,0 +1,171 @@
|
|||||||
|
# Dynamic Folder Discovery — решение для хардкода INBOX_SUBFOLDERS
|
||||||
|
|
||||||
|
## Контекст
|
||||||
|
|
||||||
|
`mail_archive.py` содержит захардкоженный `INBOX_SUBFOLDERS` (18 папок).
|
||||||
|
На IMAP-сервере реально 137 подпапок INBOX, включая многоуровневые.
|
||||||
|
|
||||||
|
## Текущее состояние
|
||||||
|
|
||||||
|
### State-файлы (следы прошлых запусков)
|
||||||
|
|
||||||
|
```
|
||||||
|
/opt/hermes/email/state/
|
||||||
|
├── mail-archive-last-Archive.json
|
||||||
|
├── mail-archive-last-INBOX.json
|
||||||
|
├── mail-archive-last-INBOX_!Scan.json
|
||||||
|
├── mail-archive-last-Sent.json
|
||||||
|
├── mail-archive-last-folder_41a7755da018.json # хэш от не-ASCII имени
|
||||||
|
├── mail-archive-last-folder_5dd417336b45.json
|
||||||
|
├── mail-archive-last-folder_6dfd3661f092.json
|
||||||
|
├── mail-archive-last-folder_a2d2b831a004.json
|
||||||
|
├── mail-archive-last-folder_a59f0da18423.json
|
||||||
|
├── mail-archive-last-folder_b002f4b75367.json
|
||||||
|
├── mail-archive-last-folder_b8338b886347.json
|
||||||
|
├── mail-archive-last-folder_ba130b3adfda.json
|
||||||
|
├── mail-archive-last-folder_e5dd3de630eb.json
|
||||||
|
```
|
||||||
|
|
||||||
|
State-файлы уже поддерживают произвольные имена папок (через `get_state_file()` —
|
||||||
|
MD5-хэш для не-ASCII). Инфраструктура готова.
|
||||||
|
|
||||||
|
### Хардкод в mail_archive.py (строки 54-73)
|
||||||
|
|
||||||
|
```python
|
||||||
|
INBOX_SUBFOLDERS = [
|
||||||
|
"INBOX/!Scan",
|
||||||
|
"INBOX/!Битрикс",
|
||||||
|
"INBOX/!ВГ Чек листы",
|
||||||
|
"INBOX/!Документооборот",
|
||||||
|
"INBOX/!Завки",
|
||||||
|
"INBOX/!Материалы",
|
||||||
|
"INBOX/!Отчеты",
|
||||||
|
"INBOX/!Персонал",
|
||||||
|
"INBOX/!Протоколы",
|
||||||
|
"INBOX/!Реестр оплаты",
|
||||||
|
"INBOX/!Торик",
|
||||||
|
"INBOX/Бюджет",
|
||||||
|
"INBOX/Контрагенты",
|
||||||
|
"INBOX/ЛНД",
|
||||||
|
"INBOX/Организация работы",
|
||||||
|
"INBOX/Приемка и стройка",
|
||||||
|
"INBOX/Системы",
|
||||||
|
"INBOX/Эксплуатация",
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Реальные папки на сервере (137 шт.)
|
||||||
|
|
||||||
|
Полный список получен через `himalaya folder list`:
|
||||||
|
|
||||||
|
```
|
||||||
|
INBOX/!Scan
|
||||||
|
INBOX/!Битрикс
|
||||||
|
INBOX/!ВГ Чек листы
|
||||||
|
INBOX/!Документооборот
|
||||||
|
INBOX/!Завки
|
||||||
|
INBOX/!Материалы
|
||||||
|
INBOX/!Отчеты
|
||||||
|
INBOX/!Персонал
|
||||||
|
INBOX/!Персонал/ОТ и ТБ
|
||||||
|
INBOX/!Протоколы
|
||||||
|
INBOX/!Реестр оплаты
|
||||||
|
INBOX/!Реестр оплаты/Акты
|
||||||
|
INBOX/!Реестр оплаты/Закупки
|
||||||
|
INBOX/!Реестр оплаты/Закупки/10 рабочих мест
|
||||||
|
INBOX/!Реестр оплаты/Закупки/NanoCad
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Горизонт Ноутбуки
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Дооснащение ТГ
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Касперский для ВГ
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Модернизация Wi-Fi
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Оборудование горизонт
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Сервер
|
||||||
|
INBOX/!Реестр оплаты/Закупки/Цветной МФУ ТГ
|
||||||
|
INBOX/!Торик
|
||||||
|
INBOX/Бюджет
|
||||||
|
INBOX/Бюджет/Винный город
|
||||||
|
INBOX/Бюджет/Винный город/CAPEX 2025
|
||||||
|
INBOX/Бюджет/Винный город/Capex 2026
|
||||||
|
INBOX/Бюджет/Винный город/OPEX 2025
|
||||||
|
INBOX/Бюджет/Винный город/OPEX 2026
|
||||||
|
INBOX/Бюджет/Винный город/OPEX 2027
|
||||||
|
INBOX/Бюджет/Горизонт
|
||||||
|
INBOX/Бюджет/Горизонт/CAPEX 2025
|
||||||
|
INBOX/Бюджет/Горизонт/CAPEX 2026
|
||||||
|
INBOX/Бюджет/Горизонт/OPEX 2026
|
||||||
|
INBOX/Бюджет/Тихая гавань
|
||||||
|
INBOX/Бюджет/Тихая гавань/CAPEX 2025
|
||||||
|
INBOX/Бюджет/Тихая гавань/CAPEX 2026
|
||||||
|
INBOX/Бюджет/Тихая гавань/OPEX 2025
|
||||||
|
INBOX/Бюджет/Тихая гавань/OPEX 2026
|
||||||
|
INBOX/Контрагенты
|
||||||
|
INBOX/Контрагенты/iiko
|
||||||
|
INBOX/Контрагенты/iiko/Тихая гавань
|
||||||
|
INBOX/Контрагенты/АБ-Транзит
|
||||||
|
INBOX/Контрагенты/Аврора
|
||||||
|
INBOX/Контрагенты/Ассистент
|
||||||
|
INBOX/Контрагенты/Билайн
|
||||||
|
INBOX/Контрагенты/Интеллект - ilocks - замки
|
||||||
|
INBOX/Контрагенты/Интертех Лицензии Huawei
|
||||||
|
INBOX/Контрагенты/Квадротек
|
||||||
|
INBOX/Контрагенты/Кит
|
||||||
|
INBOX/Контрагенты/Компания АйТи
|
||||||
|
INBOX/Контрагенты/Кристалл
|
||||||
|
INBOX/Контрагенты/Крым-Строй-Сервис
|
||||||
|
INBOX/Контрагенты/Лимон
|
||||||
|
INBOX/Контрагенты/Медиа-Сервис
|
||||||
|
INBOX/Контрагенты/МеталлПрофиль
|
||||||
|
INBOX/Контрагенты/Ново-групп
|
||||||
|
INBOX/Контрагенты/Орт-Сервис
|
||||||
|
INBOX/Контрагенты/Партнер
|
||||||
|
INBOX/Контрагенты/Партнеры
|
||||||
|
INBOX/Контрагенты/Пиксель
|
||||||
|
INBOX/Контрагенты/Поставщики
|
||||||
|
INBOX/Контрагенты/Рубикон-С
|
||||||
|
INBOX/Контрагенты/СБСС
|
||||||
|
INBOX/Контрагенты/Самоваръ
|
||||||
|
INBOX/Контрагенты/Сервисный центр
|
||||||
|
INBOX/Контрагенты/Смарт
|
||||||
|
INBOX/Контрагенты/СпецТехМонтаж
|
||||||
|
INBOX/Контрагенты/Стрим
|
||||||
|
INBOX/Контрагенты/СтройПартнер
|
||||||
|
INBOX/Контрагенты/ТД ТрансМет
|
||||||
|
INBOX/Контрагенты/ТД Лайт
|
||||||
|
INBOX/Контрагенты/Технологии Доверия
|
||||||
|
INBOX/Контрагенты/Технополис
|
||||||
|
INBOX/Контрагенты/Типография
|
||||||
|
INBOX/Контрагенты/УралТрансПром
|
||||||
|
INBOX/Контрагенты/Физ лица
|
||||||
|
INBOX/Контрагенты/Цифровые решения
|
||||||
|
INBOX/Контрагенты/ЭнергоСпецКомплект
|
||||||
|
INBOX/Контрагенты/Энергия
|
||||||
|
INBOX/Контрагенты/Югспецодежда
|
||||||
|
INBOX/ЛНД
|
||||||
|
INBOX/Организация работы
|
||||||
|
INBOX/Приемка и стройка
|
||||||
|
INBOX/Системы
|
||||||
|
INBOX/Эксплуатация
|
||||||
|
```
|
||||||
|
|
||||||
|
## План исправления
|
||||||
|
|
||||||
|
1. В `mail_archive.py` заменить `INBOX_SUBFOLDERS` на функцию `get_all_folders()`:
|
||||||
|
- `himalaya folder list --output json`
|
||||||
|
- Фильтр: папки, начинающиеся с `INBOX/` (исключить Trash, Drafts, RSS, Archives)
|
||||||
|
- Исключить `INBOX` (корневую — она уже в `FOLDERS`)
|
||||||
|
|
||||||
|
2. `--all` должен использовать `FOLDERS + get_all_inbox_subfolders()` вместо `FOLDERS + INBOX_SUBFOLDERS`
|
||||||
|
|
||||||
|
3. `mail-archive-every-5min` cron автоматически получит новые папки без изменения конфигурации
|
||||||
|
|
||||||
|
4. State-файлы уже готовы — `get_state_file()` работает с любыми именами папок
|
||||||
|
|
||||||
|
## Edge cases
|
||||||
|
|
||||||
|
- Папки могут исчезнуть между запусками — `archive_folder()` уже обрабатывает
|
||||||
|
`No such folder` через `get_envelopes()` (возвращает `[]`)
|
||||||
|
- Новая папка без писем — `get_envelopes()` вернёт пустой список, state не создаётся
|
||||||
|
- Папки с `\HasNoChildren` и `\HasChildren` — `himalaya folder list` показывает все
|
||||||
|
(независимо от флагов), так что фильтр по `\HasNoChildren` не нужен
|
||||||
|
- Очень глубокие папки (3-4 уровня) — `get_state_file()` через MD5-хэш поддерживает
|
||||||
|
любую длину имени
|
||||||
@@ -0,0 +1,124 @@
|
|||||||
|
# Jino (jino.ru) — настройка почтового ящика в Himalaya
|
||||||
|
|
||||||
|
## Серверы
|
||||||
|
|
||||||
|
| Протокол | Сервер | Порт | Шифрование | Аутентификация |
|
||||||
|
|----------|--------|------|------------|----------------|
|
||||||
|
| IMAP | mail.jino.ru | 143 | STARTTLS | PLAIN, CRAM-MD5 |
|
||||||
|
| IMAP SSL | mail.jino.ru | 993 | TLS | PLAIN, CRAM-MD5 |
|
||||||
|
| POP3 SSL | mail.jino.ru | 995 | TLS | USER/PASS |
|
||||||
|
| SMTP | smtp.jino.ru | 587 | STARTTLS | PLAIN, LOGIN, CRAM-MD5 |
|
||||||
|
| SMTP SSL | smtp.jino.ru | 465 | TLS | PLAIN, LOGIN, CRAM-MD5 |
|
||||||
|
|
||||||
|
**Логин:** полный email `hermes@nixg.ru` (не local-part без домена — сервер вернёт "Email not valid").
|
||||||
|
|
||||||
|
## Himalaya config
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[accounts.jino-hermes]
|
||||||
|
email = "hermes@nixg.ru"
|
||||||
|
display-name = "Hermes Agent"
|
||||||
|
default = false
|
||||||
|
|
||||||
|
backend.type = "imap"
|
||||||
|
backend.host = "mail.jino.ru"
|
||||||
|
backend.port = 993
|
||||||
|
backend.encryption.type = "tls"
|
||||||
|
backend.login = "hermes@nixg.ru"
|
||||||
|
backend.auth.type = "password"
|
||||||
|
backend.auth.raw = "PASSWORD_HERE"
|
||||||
|
|
||||||
|
folder.aliases.inbox = "INBOX"
|
||||||
|
|
||||||
|
[accounts.jino-hermes.message.send]
|
||||||
|
backend.type = "smtp"
|
||||||
|
backend.host = "smtp.jino.ru"
|
||||||
|
backend.port = 465
|
||||||
|
backend.encryption.type = "tls"
|
||||||
|
backend.login = "hermes@nixg.ru"
|
||||||
|
backend.auth.type = "password"
|
||||||
|
backend.auth.raw = "PASSWORD_HERE"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Диагностика
|
||||||
|
|
||||||
|
### Быстрая проверка IMAP (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
import imaplib
|
||||||
|
M = imaplib.IMAP4_SSL('mail.jino.ru', 993)
|
||||||
|
try:
|
||||||
|
M.login('hermes@nixg.ru', 'PASSWORD')
|
||||||
|
print('OK')
|
||||||
|
M.logout()
|
||||||
|
except Exception as e:
|
||||||
|
print(f'Login failed: {e}')
|
||||||
|
```
|
||||||
|
|
||||||
|
### Быстрая проверка SMTP (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
import smtplib
|
||||||
|
S = smtplib.SMTP('smtp.jino.ru', 587, timeout=15)
|
||||||
|
S.ehlo()
|
||||||
|
S.starttls()
|
||||||
|
S.ehlo()
|
||||||
|
try:
|
||||||
|
S.login('hermes@nixg.ru', 'PASSWORD')
|
||||||
|
print('SMTP OK')
|
||||||
|
except Exception as e:
|
||||||
|
print(f'SMTP login error: {e}')
|
||||||
|
S.quit()
|
||||||
|
```
|
||||||
|
|
||||||
|
### Проверка POP3
|
||||||
|
|
||||||
|
```python
|
||||||
|
import poplib
|
||||||
|
P = poplib.POP3_SSL('mail.jino.ru', 995, timeout=15)
|
||||||
|
try:
|
||||||
|
P.user('hermes@nixg.ru')
|
||||||
|
P.pass_('PASSWORD')
|
||||||
|
msgs, _ = P.stat()
|
||||||
|
print(f'POP3 OK, {msgs} messages')
|
||||||
|
P.quit()
|
||||||
|
except Exception as e:
|
||||||
|
print(f'POP3 error: {e}')
|
||||||
|
```
|
||||||
|
|
||||||
|
### Просмотр IMAP-возможностей сервера
|
||||||
|
|
||||||
|
```python
|
||||||
|
M = imaplib.IMAP4_SSL('mail.jino.ru', 993)
|
||||||
|
M.capability()
|
||||||
|
print(M.capabilities) # выведет: IMAP4 IMAP4REV1 UIDPLUS CHILDREN NAMESPACE QUOTA IDLE AUTH=PLAIN AUTH=CRAM-MD5
|
||||||
|
M.shutdown()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Типовые проблемы
|
||||||
|
|
||||||
|
### "Login failed" на всех протоколах
|
||||||
|
|
||||||
|
1. **Ящик не активирован** — Jino (и особенно хостинг-аккаунты на nixg.ru) могут требовать первый вход через панель управления или webmail
|
||||||
|
2. **Неправильный пароль** — сбросить в cp.jino.ru → Почта → нужный ящик → Изменить пароль
|
||||||
|
3. **Доступ по протоколам отключён** — в панели Jino нужно проверить, что IMAP/POP3/SMTP включены для ящика
|
||||||
|
4. **Сервер ждёт активации** — на новых доменах почта может не работать до завершения регистрации/верификации
|
||||||
|
|
||||||
|
Если логин не проходит через `himalaya` — **проверить вручную через Python** (см. выше). Python показывает ту же ошибку, но без дополнительных слоёв (Rust-клиент himalaya может добавить свою обёртку).
|
||||||
|
|
||||||
|
### "Email not valid"
|
||||||
|
|
||||||
|
Логин передан без доменной части (только `hermes`, а не `hermes@nixg.ru`). Jino IMAP требует полный email.
|
||||||
|
|
||||||
|
## Множественные аккаунты в Himalaya
|
||||||
|
|
||||||
|
Конфиг может содержать сколько угодно аккаунтов. Для переключения:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Через --account (порядок аргументов важен):
|
||||||
|
himalaya --account hermes envelope list --limit 10
|
||||||
|
|
||||||
|
# Или временно сделать default и вернуть обратно:
|
||||||
|
vim ~/.config/himalaya/config.toml
|
||||||
|
# выставить default = true у нужного аккаунта
|
||||||
|
```
|
||||||
@@ -0,0 +1,125 @@
|
|||||||
|
# SQLite-индекс архива писем
|
||||||
|
|
||||||
|
## Назначение
|
||||||
|
|
||||||
|
Быстрый поиск и трекинг по архиву email.md без grep-а по всем папкам.
|
||||||
|
Основа для: contacts_extractor (знает какие письма обработаны), sqlite_search (FTS5), digest (выборка по дате).
|
||||||
|
|
||||||
|
## Компоненты
|
||||||
|
|
||||||
|
| Компонент | Путь | Назначение |
|
||||||
|
|-----------|------|------------|
|
||||||
|
| Индексатор | `/opt/hermes/email-assistant/scripts/mail_index.py` | Сканирует email.md → SQLite |
|
||||||
|
| Поиск | `/opt/hermes/email-assistant/scripts/sqlite_search.py` | FTS5-поиск по индексу |
|
||||||
|
| База | `/opt/hermes/email/mail_index.db` | SQLite (WAL mode) |
|
||||||
|
|
||||||
|
## Схема БД
|
||||||
|
|
||||||
|
### emails — основная таблица
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS emails (
|
||||||
|
path TEXT PRIMARY KEY, -- относительный путь от EMAIL_ROOT
|
||||||
|
uid INTEGER, -- числовой UID из пути
|
||||||
|
folder TEXT, -- INBOX, INBOX/!Scan, Sent...
|
||||||
|
date TEXT, -- дата из frontmatter (ISO)
|
||||||
|
from_addr TEXT, -- отправитель
|
||||||
|
to_addrs TEXT, -- получатели
|
||||||
|
subject TEXT, -- тема
|
||||||
|
body_preview TEXT, -- первые 500 символов тела (без HTML)
|
||||||
|
contacts_extracted INTEGER DEFAULT 0, -- 0/1 — обработано contacts_extractor
|
||||||
|
contacts_skipped INTEGER DEFAULT 0, -- 0/1 — нет подписи / LLM error
|
||||||
|
first_seen TEXT, -- когда проиндексировано
|
||||||
|
last_scanned TEXT, -- последняя проверка contacts
|
||||||
|
file_mtime REAL -- mtime файла для инкрементальной проверки
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### email_fts — FTS5 virtual table
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE VIRTUAL TABLE IF NOT EXISTS email_fts USING fts5(
|
||||||
|
subject, from_addr, to_addrs, body_preview,
|
||||||
|
content='emails',
|
||||||
|
content_rowid='rowid',
|
||||||
|
tokenize='unicode61'
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
Синхронизация через триггеры INSERT/UPDATE/DELETE + FTS5 rebuild.
|
||||||
|
|
||||||
|
### Индексы
|
||||||
|
|
||||||
|
- `idx_emails_folder` — быстрая фильтрация по папке
|
||||||
|
- `idx_emails_uid` — lookup по UID
|
||||||
|
- `idx_emails_contacts` — необработанные письма (contacts_extracted=0)
|
||||||
|
- `idx_emails_date` — сортировка по дате
|
||||||
|
|
||||||
|
## Контракт между mail_index.py и contacts_extractor.py
|
||||||
|
|
||||||
|
**mail_index.py** владеет схемой и создаёт таблицы. **contacts_extractor.py** — только читает/пишет поля `contacts_extracted`, `contacts_skipped`, `last_scanned`.
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- contacts_extractor берёт необработанные письма:
|
||||||
|
SELECT rowid, path, uid, folder, from_addr, subject
|
||||||
|
FROM emails
|
||||||
|
WHERE contacts_extracted = 0 AND contacts_skipped = 0
|
||||||
|
ORDER BY folder, uid
|
||||||
|
LIMIT ?
|
||||||
|
|
||||||
|
-- После обработки:
|
||||||
|
UPDATE emails SET contacts_extracted=1, last_scanned=? WHERE rowid=?
|
||||||
|
UPDATE emails SET contacts_skipped=1, last_scanned=? WHERE rowid=?
|
||||||
|
```
|
||||||
|
|
||||||
|
## Быстродействие
|
||||||
|
|
||||||
|
- 2073 письма → полная индексация ~9 секунд
|
||||||
|
- FTS5-поиск — мгновенно (<100ms)
|
||||||
|
- WAL mode — конкурентные чтения не блокируют запись
|
||||||
|
- Инкрементальная индексация по mtime — доли секунды
|
||||||
|
|
||||||
|
## Использование sqlite_search.py
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Простой поиск (AND по умолчанию)
|
||||||
|
python3 sqlite_search.py 'Стороженко'
|
||||||
|
python3 sqlite_search.py 'битрикс OR контрагент'
|
||||||
|
python3 sqlite_search.py '"точечная фраза"'
|
||||||
|
|
||||||
|
# Фильтры
|
||||||
|
python3 sqlite_search.py --folder 'INBOX/!Отчеты'
|
||||||
|
python3 sqlite_search.py --limit 20
|
||||||
|
|
||||||
|
# Специальные префиксы (точно в поле from_addr/subject через LIKE)
|
||||||
|
python3 sqlite_search.py 'from:example@mail'
|
||||||
|
python3 sqlite_search.py 'subject:отчёт'
|
||||||
|
|
||||||
|
# Вкл. тело письма в FTS5 (медленнее, но находит больше)
|
||||||
|
python3 sqlite_search.py --body
|
||||||
|
```
|
||||||
|
|
||||||
|
## Операторы FTS5
|
||||||
|
|
||||||
|
- `AND` — по умолчанию между словами
|
||||||
|
- `OR` — `'битрикс OR контрагент'`
|
||||||
|
- `"точная фраза"` — кавычки для точного совпадения
|
||||||
|
- `-исключить` — минус перед словом
|
||||||
|
- `prefix*` — wildcard (звёздочка на конце)
|
||||||
|
|
||||||
|
## mail_index.py — ключевые параметры
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 mail_index.py # полная переиндексация
|
||||||
|
python3 mail_index.py --incremental # только новые (по mtime)
|
||||||
|
python3 mail_index.py --search "..." # поиск (встроенный, без FTS5)
|
||||||
|
python3 mail_index.py --stats # статистика
|
||||||
|
```
|
||||||
|
|
||||||
|
## Важные детали
|
||||||
|
|
||||||
|
- **body_preview** — только первые 500 символов. Для full-text search с телом используй `sqlite_search.py --body` (FTS5 на preview).
|
||||||
|
- **contacts_extracted/contacts_skipped** — взаимоисключающие флаги. Если ни один не 1 — письмо не обработано.
|
||||||
|
- **file_mtime** — для инкрементальной индексации. Если mtime файла > last_mtime в БД — переиндексировать.
|
||||||
|
- **FTS5 rebuild** — вызывается после каждой полной индексации для согласованности.
|
||||||
|
- Исключает папки `contacts/` и `state/` из сканирования.
|
||||||
Reference in New Issue
Block a user