Mailflow

Обеспечьте надежное срабатывание сессий и промптов OpenCode из писем классического Outlook, предоставляя агенту OpenCode набор контролируемых инструментов MCP для работы с почтой.

Mailflow не встраивает мониторинг почты, правила, вызовы сессий, утверждение и UI снова в один большой плагин. Первая версия использует независимое ядро (Core), коннектор Windows Outlook, HTTP-адаптер OpenCode и узконаправленные MCP; оригинальный win-console остается без изменений, с совместимыми инструментами и путем миграции с приоритетом dry-run.

Итоговая форма

flowchart LR
  O["Outlook Classic<br/>Windows 用户会话"] -->|"标准化邮件 / Outlook 命令"| C["Mailflow Core<br/>SQLite · 规则 · 队列 · 审批"]
  C -->|"创建 session + prompt_async"| OC["OpenCode Server"]
  OC --> A["OpenCode 会话 / Agent"]
  A -->|"stdio MCP"| M["Mailflow MCP"]
  M -->|"受 token 保护的 API"| C
  C -->|"草稿 / 导出 / 经审批发送"| O
  UI["本地中文管理台"] --> C
  WC["原 win-console"] -. "兼容工具 / 能力注册 / 可回滚迁移" .-> C

Границы четкие:

• Коннектор Outlook занимается только адаптацией данных Outlook, надежной доставкой и нативными действиями Outlook; конкретный механизм передачи не является контрактом Core.

• Core — единственный источник истины, отвечающий за SQLite, версионирование правил, идемпотентность, повторные попытки, аудит, утверждение и команды коннектора.

• Core напрямую вызывает HTTP API OpenCode для создания сессий и асинхронной отправки промптов.

• MCP предоставляет агенту в сессии только инструменты для чтения писем, экспорта вложений, создания черновиков ответов и отправки с утверждением; он не прослушивает почтовый ящик.

• Панель управления отвечает за правила, выполнение, утверждение и восстановление после сбоев, не полагаясь на панель Outlook.

Плагин Outlook или плагин OpenCode?

Первая версия не делает «тяжелых плагинов» ни для одной из сторон. Это осознанный выбор:

Итак: элементы дизайна, конечно, могут отображаться на панели расширения Outlook, но ядро не должно быть встроено туда. Надстройки VSTO/COM для классического Outlook подвержены влиянию разрядности Office, подписей, отключения загрузки и жизненного цикла процесса. Текущая поставляемая версия использует отдельный коннектор COM в виде трея; при добавлении тонкой панели VSTO в будущем не потребуется изменять Core, MCP или базу данных. Плагин OpenCode также является опциональным уровнем представления; запуск сессий уже выполняется через стабильный HTTP API.

Что уже включено в v0.1.0

• Node.js 24 + встроенный SQLite, ядро без зависимостей времени выполнения.

• Сохранение событий почты в БД, сопоставление правил, версионирование правил, конечный автомат выполнения, идемпотентные ключи, аренда, повторные попытки с экспоненциальной задержкой и dead letter.

• Создание сессии OpenCode и prompt_async с поддержкой стратегий per-message, per-conversation и pinned-session.

• Безопасная оболочка промпта: содержимое письма явно помечено как ненадежные данные, с ограничениями на тело/вложения.

• Стандартный MCP stdio-сервер, а также псевдонимы старых инструментов, такие как outlook_search, outlook_read, outlook_attachments.

• Коннектор Windows x64 Outlook Classic: доставка писем, нативное чтение/запись Outlook, идемпотентность команд и сверка отправки.

• Защитный цикл send_unknown: 5 ограниченных по времени проверок с задержкой, ручное подтверждение в панели управления и «создание нового утверждения после подтверждения неотправки»; ни одна проверка не приводит к автоматической повторной отправке.

• Черновики ответов сначала синхронизируются с Outlook, затем открываются для утверждения; хэш темы, получателей и тела предотвращает отправку старого черновика, автоматическая отправка по умолчанию отключена.

• Панель управления на китайском языке, REST API и поток состояния SSE.

• Импорт правил/состояния win-console в режиме dry-run, регистрация возможностей/heartbeat и четкий путь отката.

• Тестирование Core на Linux, сборка коннектора Windows и рабочий процесс GitHub Release, управляемый тегами.

Быстрый старт

1. Загрузка

Получите из GitHub Releases:

• email-workflow-0.1.0-runtime.zip: Core, MCP, панель управления, документация и исходный код коннектора;

• email-workflow-0.1.0-outlook-classic-win-x64.zip: автономный коннектор Windows x64;

• aleygey-email-workflow-0.1.0.tgz: пакет для запуска в формате npm.

Core требует Node.js 24+; коннектор требует Windows x64 и классический настольный Outlook.

2. Сначала инициализируйте ключи и объедините конфигурацию безопасности OpenCode

Не запускайте OpenCode первым и не перезаписывайте существующий opencode.json/opencode.jsonc файлами примеров. Сначала сгенерируйте .env в каталоге распакованного runtime:

node dist/src/cli.js init --output .env

Объедините agent.mailflow-email и mcp.mailflow из examples/opencode-mailflow-complete.json в существующую конфигурацию OpenCode, сохранив существующие provider, model, agent, plugin и другие MCP. Пользователи runtime zip должны изменить command в примере на абсолютный путь к своей машине, например:

"command": ["node", "C:\\Mailflow\\email-workflow\\dist\\src\\mcp\\cli.js"]

Пример не содержит встроенных секретов. В среде, где запускается OpenCode, должна быть установлена переменная MAILFLOW_MCP_TOKEN со значением, совпадающим с MAILFLOW_API_TOKEN в .env; это не токен коннектора:

$env:MAILFLOW_MCP_TOKEN = "<复制 .env 中 MAILFLOW_API_TOKEN 的值>"

MAILFLOW_CONNECTOR_TOKEN используется только коннектором Outlook и должен отличаться от токена API/MCP. init по умолчанию отказывается перезаписывать существующий .env.

3. Запустите OpenCode

opencode serve --hostname 127.0.0.1 --port 4096

OpenCode должен быть запущен из среды, где только что была установлена MAILFLOW_MCP_TOKEN, чтобы разрешить {env:MAILFLOW_MCP_TOKEN} в примере.

4. Запустите Core Mailflow

При необходимости измените адрес OpenCode в .env, затем запустите в каталоге распакованного runtime:

node --env-file=.env dist/src/cli.js serve

Для рабочего запуска необходимо настроить два непустых и разных токена; запуск Core без аутентификации не поддерживается как способ по умолчанию. По умолчанию OPENCODE_MAILFLOW_AGENT=mailflow-email и OPENCODE_REQUIRE_SAFE_AGENT=true; не отключайте проверку, чтобы «просто запустить».

Откройте http://127.0.0.1:8798. При первом входе в панель управления сохраните API-токен в настройках.

Запуск из исходного кода:

npm ci
npm run check
npm run dev

5. Запустите коннектор Outlook

Распакуйте коннектор Windows, скопируйте connector.example.json как:

%LOCALAPPDATA%\Mailflow\OutlookConnector\connector.json

Установите тот же токен коннектора, что и в Core, оставьте coreBaseUrl как http://127.0.0.1:8798, затем запустите:

.\mailflow-outlook-connector.exe

Полные инструкции по настройке, передаче ключей и устранению неполадок см. в руководстве по эксплуатации.

Как письмо становится сессией

1. Коннектор отправляет письмо по стабильному контракту; Core получает его, дедуплицирует по ID коннектора/события; внутренний способ приема/восстановления коннектора не входит в бизнес-контракт.

2. Core нормализует письмо, сохраняет в SQLite и выполняет сопоставление с фиксированной версией включенных правил.

3. При совпадении создается выполнение с стабильным идемпотентным ключом; worker арендует выполнение, при отключении повторяет попытки с экспоненциальной задержкой.

4. Адаптер OpenCode создает или повторно использует сессию и добавляет в промпт стабильную метку mailflow_run_id.

5. Core перед каждой отправкой промпта проверяет, что целевой агент mailflow-email существует и все еще имеет права fail-closed; если агенту нужна информация о письме, он вызывает Core через разрешенные инструменты MCP только для чтения.

6. Ответ AI сначала синхронизируется как черновик Outlook, и только после успеха появляется утверждение. При утверждении одновременно проверяются версия черновика Core и нормализованные хэши темы/получателей/тела Outlook; каждый шаг записывается в журнал аудита.

Безопасные значения по умолчанию

• Core по умолчанию прослушивает только 127.0.0.1; соединение с OpenCode принимается только через loopback HTTP или HTTPS. Удаленный открытый HTTP по умолчанию отклоняется.

• При первом запуске необходимо выполнить node dist/src/cli.js init --output .env; Core требует одновременного существования API-токена и токена коннектора, их различия и длины не менее 32 байт UTF-8 каждый, а также отклоняет публичные заполнители из примеров. MCP использует API-токен через MAILFLOW_MCP_TOKEN, коннектор использует только другой токен.

• Все запросы на запись к Core с телом должны объявлять Content-Type JSON; не-JSON запросы сразу возвращают 415.

• Агент по умолчанию — mailflow-email. Core перед каждой отправкой промпта читает определение агента из OpenCode: сначала должна быть граница deny * catch-all, затем только перечисленные разрешения read/glob/grep/list в рабочем пространстве, deny для *.env/*.env.* на любом уровне каталогов, а также точно именованные инструменты MCP Mailflow только для чтения из примера. Белый список MCP только для чтения: search/get/list-attachments/get-run и чисто читаемые legacy search/read; outlook_attachments, который может экспортировать файлы, не входит в него. Отсутствие агента, нераспознаваемый ответ о разрешениях или появление других allow приводят к fail-closed.

• Правила после создания по умолчанию отключены; сначала preview, затем включение.

• Тело письма — это данные, а не инструкции; вложения по умолчанию раскрывают только метаданные.

• Ответы требуют ручного утверждения. Ответ AI сначала должен завершить синхронизацию черновика Outlook; изменение в интерфейсе утверждения аннулирует старое утверждение, ставит в очередь draft.update, после успешной синхронизации создает новое утверждение, и пользователь должен снова нажать «Утвердить». Если после утверждения тема, To/Cc/Bcc или тело в Outlook изменились, несовпадение нормализованных хэшей предотвращает отправку.

• При неопределенном результате MailItem.Send() между процессами выполнение переходит в send_unknown. Core выполняет только 5 проверок состояния с задержкой; панель управления может «Проверить Outlook», «Подтвердить отправку» или «Подтвердить неотправку». После подтверждения неотправки старое утверждение становится недействительным и создается новое утверждение, которое снова требует нажатия; система никогда не превращает сверку в автоматическую повторную отправку.

• Импорт старых данных по умолчанию в режиме dry-run; для применения импорта требуется явный --apply.

Агент только для чтения в текущей версии все еще может читать выбранное рабочее пространство и через разрешенные инструменты MCP запрашивать другие письма в этом Core; это не изолированная песочница данных для каждого выполнения. SQLite также постоянно хранит тела писем и исходные снимки; в v0.1.0 нет автоматической задачи очистки с периодом хранения. Для производственного использования следует настроить выделенное рабочее пространство/почтовый ящик с минимальными правами, контролируемые учетные записи моделей, ACL каталогов Windows, полное шифрование диска и операционный период хранения данных; строгая изоляция между проектами/почтовыми ящиками требует последующих per-run capability. Подробнее см. SECURITY.md.

MAILFLOW_ALLOW_UNAUTHENTICATED_LOOPBACK=1, OPENCODE_ALLOW_INSECURE_REMOTE=1 и OPENCODE_REQUIRE_SAFE_AGENT=false предназначены только для изолированной локальной отладки разработки, не являются рабочей конфигурацией и не могут использоваться для обработки реальных писем.

Не выставляйте Core или сервер OpenCode напрямую в публичную сеть. При развертывании через Windows/WSL или между машинами используйте HTTPS, ограничение источника и брандмауэр. Дополнительные сведения см. в SECURITY.md.

win-console не исчезнет

Старый репозиторий не удаляется, не перезаписывается, история не изменяется. Mailflow дополнительно предоставляет:

• Совместимые псевдонимы для старых имен инструментов MCP;

• Регистрацию external-capabilities и heartbeat;

• Отчеты о миграции для правил, processed receipt, очередей и контрольных точек;

• По умолчанию dry-run, явный apply, SHA-256 исходных файлов и целевое отображение;

• Шаги предотвращения двойного срабатывания при переключении и однокнопочный логический откат.

Полное пошаговое отображение см. в docs/legacy-win-console-baseline.md.

Навигация по документации

• Полный дизайн: пользовательский интерфейс, шесть полных потоков, API, данные, безопасность, тестирование и поэтапное внедрение.

• Архитектурные границы: почему разбито на Core, коннектор, адаптер, MCP и опциональный UI.

• Руководство по эксплуатации: установка, настройка OpenCode/MCP, резервное копирование, миграция, откат и устранение неполадок.

• Базовый уровень совместимости win-console: старые функции, старые данные и требования к откату.

• Примечания к выпуску v0.1.0.

Разработка и проверка

npm ci
npm run typecheck
npm test
npm run pack:release

Коннектор Windows:

dotnet build connector/Mailflow.OutlookConnector/Mailflow.OutlookConnector.csproj -c Release

Поскольку COM Outlook зависит от реального профиля пользователя Windows, CI отвечает за компиляцию Windows и не-COM тесты; перед выпуском все равно следует выполнить smoke-тест на целевом компьютере с классическим Outlook: подключение, прием писем, синхронизация черновиков, двойное утверждение и отправка.

Лицензия

MIT