281 lines
12 KiB
Markdown
281 lines
12 KiB
Markdown
# Local Email Agent
|
||
|
||
Минимальный локальный агент для macOS: читает письма из Apple Mail и Microsoft Outlook через AppleScript, считает письма, экспортирует их и готовит безопасные черновики ответов. Автоматически письма не отправляет.
|
||
|
||
## Быстрый старт
|
||
|
||
Запуск интерфейса под macOS:
|
||
|
||
```bash
|
||
python3 web_app.py
|
||
```
|
||
|
||
Или двойной клик по файлу:
|
||
|
||
```text
|
||
Launch Email Agent UI.command
|
||
```
|
||
|
||
Откроется локальный интерфейс:
|
||
|
||
```text
|
||
http://127.0.0.1:8787
|
||
```
|
||
|
||
Интерфейс работает локально на ноутбуке, подходит для Apple Silicon/Mac и ничего не отправляет автоматически.
|
||
|
||
CLI-запуск:
|
||
|
||
```bash
|
||
python3 email_agent.py doctor
|
||
python3 email_agent.py run --source all --mode unread-mailboxes --limit 200 --draft-limit 10
|
||
```
|
||
|
||
При первом запуске macOS может спросить разрешение на управление `Mail` или `Microsoft Outlook`. Разрешение нужно дать для приложения, из которого запускается скрипт: Terminal, iTerm, VS Code или другой shell.
|
||
|
||
## Команды
|
||
|
||
## Интерфейс
|
||
|
||
В `web_app.py` есть первый UI для Mac:
|
||
|
||
- `Daily Run` - полный сценарий: learn, summary, digest, drafts, report.
|
||
- `Summary` - пересчитать непрочитанные.
|
||
- `Learn` - обновить профиль стиля из отправленных писем.
|
||
- `Digest` - создать digest за день.
|
||
- `Drafts` - создать черновики в `drafts/YYYY-MM-DD/`.
|
||
- `Письма` - список реально распарсенных писем из `data/messages/YYYY-MM-DD.jsonl`.
|
||
- `Подготовленные ответы` - отдельное поле с темой, приоритетом, метками и текстом `Suggested Reply` из черновиков.
|
||
- `Критерии важности` - расшифровка P1-P5 и labels.
|
||
- `Структура` - дерево рабочих файлов `data/` и `drafts/`.
|
||
|
||
Правая панель показывает `Digest`, `Report`, `Profile`, выбранное письмо или выбранный черновик. Нижняя панель показывает лог последней операции.
|
||
|
||
Интерфейс сделан как современный desktop app-shell:
|
||
|
||
- Левый sidebar с навигацией и счетчиками писем/ответов.
|
||
- Верхняя command bar с быстрыми действиями `Daily Run`, `Summary`, `Learn`, `Digest`, `Drafts`.
|
||
- Широкие master-detail экраны для чтения писем и ответов.
|
||
- Отдельные reader-панели с полным телом письма или markdown-черновиком.
|
||
|
||
Разделы интерфейса:
|
||
|
||
- `Обзор` - метрики и критерии важности.
|
||
- `Письма` - список писем слева и широкий просмотр выбранного письма справа.
|
||
- `Ответы` - список подготовленных ответов слева и широкий просмотр выбранного ответа справа.
|
||
- `Файлы` - структура `data/` и `drafts/`, digest, report, profile.
|
||
- `Лог` - вывод последней операции.
|
||
|
||
Критерии важности:
|
||
|
||
- `P5` - срочно, deadline, critical, высокий риск.
|
||
- `P4` - нужно ответить, согласовать, approve/confirm.
|
||
- `P3` - встреча, созвон, календарь, рабочее обсуждение.
|
||
- `P2` - низкий приоритет, полезно посмотреть позже.
|
||
- `P1` - FYI, рассылки, уведомления без действия.
|
||
|
||
Обучение по умолчанию фильтрует отправленные письма по identity:
|
||
|
||
```text
|
||
s.tomashev@a1.by
|
||
```
|
||
|
||
Если нужно поменять адрес:
|
||
|
||
```bash
|
||
python3 email_agent.py run --identity another.email@example.com
|
||
python3 email_agent.py learn --identity another.email@example.com
|
||
```
|
||
|
||
Черновики текущего дня по умолчанию очищаются перед новой генерацией, чтобы UI не показывал старые ответы вперемешку с новыми. Чтобы сохранить старые файлы, используй `--no-clean`.
|
||
|
||
Запуск:
|
||
|
||
```bash
|
||
python3 web_app.py
|
||
```
|
||
|
||
Остановка: `Ctrl+C` в терминале, где запущен интерфейс.
|
||
|
||
```bash
|
||
python3 email_agent.py run --source all --mode unread-mailboxes --limit 200 --draft-limit 10 --identity s.tomashev@a1.by
|
||
```
|
||
|
||
Запускает ежедневный сценарий целиком: обучение на отправленных письмах, summary, digest, черновики и daily report.
|
||
|
||
По умолчанию агент читает `unread-mailboxes`: сначала `Входящие/INBOX`, затем остальные папки правил. Это нужно для Exchange, где часть писем лежит не в главном inbox, а в `Monitoring`, `Deeplog`, `HybrisSync`, `svc1cDocflow` и других mailbox.
|
||
|
||
Диагностика mailbox:
|
||
|
||
```bash
|
||
python3 email_agent.py mailboxes --source all
|
||
```
|
||
|
||
Режимы чтения:
|
||
|
||
- `unread` - только системный inbox клиента.
|
||
- `unread-all` - inbox всех аккаунтов.
|
||
- `unread-mailboxes` - inbox плюс рабочие папки правил, без архивов/удаленных/отправленных/спама.
|
||
- `all-mailboxes` - все рабочие папки с прочитанными и непрочитанными, кроме исключенных системных.
|
||
|
||
Файлы раскладываются так:
|
||
|
||
```text
|
||
data/profiles/style_profile.json
|
||
data/messages/YYYY-MM-DD.jsonl
|
||
data/contacts/contacts.json
|
||
data/calendar/YYYY-MM-DD.md
|
||
data/digests/YYYY-MM-DD.md
|
||
data/reports/YYYY-MM-DD-summary.json
|
||
data/reports/YYYY-MM-DD.md
|
||
drafts/YYYY-MM-DD/*.md
|
||
```
|
||
|
||
```bash
|
||
python3 email_agent.py summary
|
||
```
|
||
|
||
Показывает количество писем, разбивку по источникам, отправителям и доменам.
|
||
|
||
```bash
|
||
python3 email_agent.py learn --source all --limit 100
|
||
```
|
||
|
||
Читает последние отправленные письма и сохраняет локальный профиль твоего стиля в `data/profiles/style_profile.json`. Агент фильтрует пересланные цепочки, календарные инвайты, служебные подписи и рассылки, чтобы не учиться на мусоре.
|
||
|
||
```bash
|
||
python3 email_agent.py digest --source all --mode unread --limit 50
|
||
```
|
||
|
||
Классифицирует письма по приоритету и меткам: `urgent`, `needs_reply`, `meeting`, `finance_or_contract`, `newsletter`, `fyi`.
|
||
|
||
По умолчанию сохраняет digest в `data/digests/YYYY-MM-DD.md`. Для вывода в консоль используй `--output -`.
|
||
|
||
```bash
|
||
python3 email_agent.py export --output data/exports/messages.jsonl
|
||
```
|
||
|
||
Экспортирует письма в JSONL для дальнейшего анализа.
|
||
|
||
```bash
|
||
python3 email_agent.py drafts
|
||
```
|
||
|
||
Создает Markdown-черновики ответов в папке `drafts/YYYY-MM-DD/`.
|
||
|
||
По умолчанию использует профиль из `data/profiles/style_profile.json`, если он уже создан командой `learn` или `run`.
|
||
|
||
Создать черновики прямо в Apple Mail без отправки:
|
||
|
||
```bash
|
||
python3 email_agent.py publish-drafts --client apple-mail --input-dir drafts/YYYY-MM-DD --limit 5
|
||
```
|
||
|
||
Для Outlook:
|
||
|
||
```bash
|
||
python3 email_agent.py publish-drafts --client outlook --input-dir drafts/YYYY-MM-DD --limit 5
|
||
```
|
||
|
||
Команда создает draft messages в почтовом клиенте, но не отправляет их.
|
||
|
||
## Календарь, Контакты, Feedback
|
||
|
||
Календарные предложения для писем про встречи:
|
||
|
||
```bash
|
||
python3 email_agent.py calendar --source all --mode unread --limit 50
|
||
```
|
||
|
||
Файл сохраняется в `data/calendar/YYYY-MM-DD.md`. Если нужно создать локальные события в Calendar без отправки приглашений:
|
||
|
||
```bash
|
||
python3 email_agent.py calendar --source all --mode unread --limit 50 --create-events
|
||
```
|
||
|
||
Память по контактам:
|
||
|
||
```bash
|
||
python3 email_agent.py contacts --source all --mode unread --limit 100
|
||
```
|
||
|
||
Файл сохраняется в `data/contacts/contacts.json`. Там хранится частота контакта, важность, последний subject и базовый `reply_style`.
|
||
|
||
Approved-feedback:
|
||
|
||
```bash
|
||
python3 email_agent.py feedback
|
||
```
|
||
|
||
Чтобы агент учился на исправленных ответах, положи markdown-файлы в `feedback/approved/`. Лучше использовать секцию:
|
||
|
||
```markdown
|
||
## Approved Reply
|
||
|
||
Финальная версия ответа, которую реально отправил.
|
||
```
|
||
|
||
`run` автоматически подхватывает approved-feedback и смешивает его с профилем отправленных писем.
|
||
|
||
## Источники
|
||
|
||
Можно выбрать конкретный источник:
|
||
|
||
```bash
|
||
python3 email_agent.py summary --source apple-mail
|
||
python3 email_agent.py summary --source outlook
|
||
python3 email_agent.py summary --source all
|
||
```
|
||
|
||
Режимы чтения:
|
||
|
||
```bash
|
||
--mode unread
|
||
--mode inbox
|
||
--mode sent
|
||
--mode unread-all
|
||
--mode unread-mailboxes
|
||
--mode all-mailboxes
|
||
```
|
||
|
||
`unread` читает непрочитанные письма из системного inbox. `inbox` читает письма из входящих. `sent` читает отправленные письма и используется для обучения стилю. `unread-mailboxes` читает непрочитанные из inbox и рабочих папок правил.
|
||
|
||
## AI-ответы
|
||
|
||
По умолчанию агент делает осторожные шаблонные ответы. Если задать OpenAI-compatible API, он будет готовить более осмысленные черновики:
|
||
|
||
```bash
|
||
export OPENAI_API_KEY="your-key"
|
||
export OPENAI_MODEL="gpt-4o-mini"
|
||
export OPENAI_BASE_URL="https://api.openai.com/v1"
|
||
python3 email_agent.py drafts --limit 10
|
||
```
|
||
|
||
Если профиль стиля уже создан, он автоматически добавляется в LLM-промпт:
|
||
|
||
```bash
|
||
python3 email_agent.py drafts --style learned --language auto --limit 10
|
||
```
|
||
|
||
Отключить профиль можно так:
|
||
|
||
```bash
|
||
python3 email_agent.py drafts --no-profile --style neutral --language ru
|
||
```
|
||
|
||
Для подписи можно задать:
|
||
|
||
```bash
|
||
export EMAIL_AGENT_SIGNATURE="Ваше имя"
|
||
```
|
||
|
||
## Безопасность
|
||
|
||
Агент не отправляет письма и не меняет статус прочтения намеренно. Он читает доступные письма, создает локальные файлы с черновиками и может создавать draft messages в Mail/Outlook без отправки.
|
||
|
||
## Частые проблемы
|
||
|
||
Если видите ошибку доступа AppleScript, откройте `System Settings -> Privacy & Security -> Automation` и разрешите вашему терминалу управлять `Mail` или `Microsoft Outlook`.
|
||
|
||
Если Outlook не отвечает на AppleScript, проверьте, что приложение установлено, запущено и использует классический режим с AppleScript-поддержкой. В некоторых версиях нового Outlook для macOS AppleScript ограничен.
|