---
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
```