Initial commit: Email Assistant project

2026-07-19 16:19:14 +00:00
commit 004977b1f8
16 changed files with 2653 additions and 0 deletions
@@ -0,0 +1,119 @@
+---
+name: email-local-archive
+description: "Локальный архив почты: инкрементальное сохранение писем из IMAP в файловую структуру на Yandex Disk с метаданными, телом и вложениями."
+version: 1.0.0
+author: estorozhenko
+platforms: [linux]
+prerequisites:
+  commands: [himalaya, python3]
+metadata:
+  hermes:
+    tags: [email, archive, imap, backup, knowledge]
+---
+
+# Email Local Archive
+
+Этот навык позволяет агенту архивировать письма из почтового ящика
+в локальную файловую систему по пути:
+
+```
+/mnt/yandex-disk/hermes/email/<folder>/YYYY/MM/UID/
+  ├── meta.json       # envelope (from, to, subject, date, flags)
+  ├── body.md         # тело письма (plain text)
+  └── attachments/    # вложения
+```
+
+Используется клиент Himalaya CLI и Python-скрипт
+`/opt/hermes/email-assistant/scripts/mail_archive.py`.
+
+## Возможности
+
+- Инкрементальная архивация новых писем по UID
+- Поддержка любых папок (INBOX, Отправленные, Archive, Sent, подпапки)
+- Ограничение количества писем за один запуск (`--limit`)
+- Режим `--all` для архивации всех папок (основные + вложенные INBOX)
+- Состояние отслеживается в `~/.local/state/mail-archive-last-*.json`
+- Обёртка `mail-archive.sh` для systemd/cron/Hermes
+
+## Инструменты
+
+Используется `terminal` для вызова скрипта, `read_file` для чтения
+сохранённых писем, `search_files` для поиска по архиву.
+
+### Основные команды
+
+```bash
+# Архивация INBOX (первые 200 писем)
+mail-archive.sh --folder INBOX --limit 200
+
+# Архивация Отправленные (первые 50)
+mail-archive.sh --folder "Отправленные" --limit 50
+
+# Архивация всех папок (основные)
+mail-archive.sh --limit 100
+
+# Архивация всех папок включая вложенные INBOX
+mail-archive.sh --all --limit 50
+
+# Справка
+mail-archive.sh --help
+```
+
+## Поведение агента
+
+1. **"Обнови архив почты"** — выполнить `mail-archive.sh --limit 100`
+2. **"Архивируй INBOX"** — `mail-archive.sh --folder INBOX --limit 200`
+3. **"Архивируй всё"** — `mail-archive.sh --all --limit 100`
+4. **"Найди письмо про <тема>"** — `grep -ril '<тема>' /mnt/yandex-disk/hermes/email/**/body.md`
+   или `jq 'select(.subject | test("<тема>"))' /mnt/yandex-disk/hermes/email/**/meta.json`
+5. **"Проверь статус архива"** — показать содержимое `~/.local/state/mail-archive-last-*.json`
+6. **"Сколько писем в архиве"** — `find /mnt/yandex-disk/hermes/email -name meta.json | wc -l`
+
+## Правила
+
+- НЕ изменять и не удалять файлы в `/mnt/yandex-disk/hermes/email/`
+  или `~/.local/state/mail-archive-last-*.json` без явной команды
+- НЕ переписывать логику архивации сырыми командами Himalaya
+- Если скрипт падает — сообщить об ошибке пользователю
+- Пароль в `backend.auth.raw` в конфиге — не показывать в логах
+
+## Примеры
+
+**Пользователь:** "Обнови локальный архив почты из INBOX"
+
+**Агент (команда):**
+```bash
+mail-archive.sh --folder INBOX --limit 200
+```
+
+**Агент (сообщает результат):**
+```
+📁 INBOX (last_uid=11559)
+  ✓ UID 11560 (Новое письмо от Иванова)
+  ✓ UID 11561 (Счёт на оплату)
+  → last_uid обновлён до 11561, обработано 2
+```
+
+---
+
+**Пользователь:** "Архивируй все папки полностью"
+
+**Агент (команда):**
+```bash
+mail-archive.sh --all --limit 500
+```
+
+---
+
+**Пользователь:** "Найди письмо про договор с Торик"
+
+**Агент (поиск):**
+```bash
+grep -ril 'договор.*торик\|торик.*договор' /mnt/yandex-disk/hermes/email/**/body.md 2>/dev/null
+```
+
+**Агент (показывает результат):**
+```
+/mnt/yandex-disk/hermes/email/INBOX/2025/06/10234/body.md
+/mnt/yandex-disk/hermes/email/INBOX/!Торик/2026/03/11050/body.md
+```