Mailflow

Ermöglicht es, E-Mails aus klassischem Outlook zuverlässig OpenCode-Sitzungen und -Prompts auslösen zu lassen, während OpenCode-Agenten eine kontrollierte Reihe von E-Mail-MCP-Tools zur Verfügung gestellt wird.

Mailflow integriert E-Mail-Überwachung, Regeln, Sitzungsaufrufe, Genehmigungen und UI nicht erneut in ein großes Plugin. Die erste Version verwendet einen unabhängigen Core, einen Windows Outlook Connector, einen OpenCode HTTP Adapter und ein MCP mit enger Zuständigkeit; das ursprüngliche win-console bleibt unverändert und bietet Kompatibilitätstools sowie einen Migrationspfad mit Dry-Run-Priorität.

Endgültige Form

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

Die Grenzen sind klar:

• Der Outlook Connector übernimmt nur die Outlook-Datenanpassung, zuverlässige Zustellung und native Outlook-Aktionen; der konkrete Übertragungsmechanismus ist kein Vertrag des Cores.

• Der Core ist die einzige Quelle der Wahrheit und verantwortlich für SQLite, Regelversionen, Idempotenz, Wiederholungen, Audit, Genehmigungen und Connector-Befehle.

• Der Core ruft direkt die OpenCode HTTP API auf, um Sitzungen zu erstellen und Prompts asynchron zu übermitteln.

• Das MCP stellt nur den Agenten in der Sitzung Tools zum Lesen von E-Mails, Exportieren von Anhängen, Erstellen von Antwortentwürfen und genehmigtem Senden zur Verfügung; es überwacht kein Postfach.

• Die Verwaltungskonsole übernimmt Regeln, Ausführungen, Genehmigungen und Fehlerbehebung, ohne auf das Outlook-Panel angewiesen zu sein.

Outlook-Plugin oder OpenCode-Plugin?

Die erste Version macht auf beiden Seiten kein 'schweres Plugin'. Dies ist eine bewusste Entscheidung:

Also: Designinhalte können natürlich im Outlook-Erweiterungspanel angezeigt werden, aber der Kern sollte nicht darin platziert werden. Die VSTO/COM-Add-Ins von klassischem Outlook sind von Office-Bitanzahl, Signierung, Deaktivierung beim Laden und Prozesslebenszyklus betroffen. Die aktuelle auslieferbare Version verwendet einen eigenständigen COM-Connector im Tray-Stil; später kann ein dünnes VSTO-Panel hinzugefügt werden, ohne Core, MCP oder Datenbank zu ändern. Das OpenCode-Plugin ist ebenfalls eine optionale Erlebensebene; das Auslösen von Sitzungen erfolgt bereits über die stabile HTTP-API.

v0.1.0 enthält bereits

• Node.js 24 + Core mit integriertem SQLite und null Laufzeitabhängigkeiten.

• E-Mail-Ereignisse in Datenbank, Regelabgleich, Regelversionen, Run-Zustandsmaschine, Idempotenzschlüssel, Leases, Backoff-Wiederholungen und Dead Letter.

• OpenCode-Sitzungserstellung und prompt_async, Unterstützung für Per-Message-, Per-Conversation- und Pinned-Session-Strategien.

• Prompt-Sicherheits-Envelope: E-Mail-Inhalte werden explizit als nicht vertrauenswürdige Daten gekennzeichnet, mit Unterstützung für Text-/Anhangslimits.

• Standard-MCP-stdio-Server sowie Aliasse für alte Tools wie outlook_search, outlook_read, outlook_attachments.

• Windows x64 Outlook Classic Connector: E-Mail-Zustellung, natives Outlook-Lesen/Schreiben, Befehlsidempotenz und Sendungsabgleich.

• send_unknown Sicherheitsschleife: 5 begrenzte Verzögerungsprüfungen, manuelle Bestätigung in der Verwaltungskonsole und „Erzeugen einer neuen Genehmigung nach Bestätigung des Nichtgesendetseins“; keine Prüfung löst automatisch einen erneuten Versand aus.

• Antwortentwürfe werden zuerst mit Outlook synchronisiert, bevor die Genehmigung freigegeben wird; normalisierte Hashes von Betreff, Empfängern und Text verhindern gemeinsam das Senden alter Entwürfe, automatisches Senden ist standardmäßig deaktiviert.

• Lokale Verwaltungskonsole auf Chinesisch, REST-API und SSE-Statusstream.

• win-console Regel-/Status-Dry-Run-Import, Fähigkeitsregistrierung/Heartbeat und klarer Rollback-Pfad.

• Linux-Core-Tests, Windows-Connector-Build und tag-gesteuerter GitHub-Release-Workflow.

Schnellstart

1. Herunterladen

Von GitHub Releases herunterladen:

• email-workflow-0.1.0-runtime.zip: Core, MCP, Verwaltungskonsole, Dokumentation und Connector-Quellcode;

• email-workflow-0.1.0-outlook-classic-win-x64.zip: Eigenständiger Windows x64 Connector;

• aleygey-email-workflow-0.1.0.tgz: Laufzeitpaket im npm-Format.

Core erfordert Node.js 24+; Connector erfordert Windows x64 und klassisches Desktop-Outlook.

2. Zuerst Schlüssel initialisieren und OpenCode-Sicherheitskonfiguration zusammenführen

Starten Sie OpenCode nicht zuerst und überschreiben Sie keine vorhandenen opencode.json/opencode.jsonc mit Beispieldateien. Generieren Sie zuerst .env im entpackten Runtime-Verzeichnis:

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

Führen Sie agent.mailflow-email und mcp.mailflow aus examples/opencode-mailflow-complete.json zusammen in die vorhandene OpenCode-Konfiguration, wobei vorhandene Provider, Modelle, Agenten, Plugins und andere MCPs erhalten bleiben. Benutzer des Runtime-ZIPs ändern command im Beispiel in den absoluten Pfad auf dem eigenen Rechner, z.B.:

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

Die Beispiele enthalten keine Geheimnisse. Die Umgebung des Benutzers, der OpenCode startet, muss MAILFLOW_MCP_TOKEN setzen, mit dem gleichen Wert wie MAILFLOW_API_TOKEN in .env; es ist kein Connector-Token:

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

MAILFLOW_CONNECTOR_TOKEN wird nur vom Outlook Connector verwendet und muss sich vom API/MCP-Token unterscheiden. init lehnt standardmäßig das Überschreiben einer vorhandenen .env ab.

3. OpenCode starten

opencode serve --hostname 127.0.0.1 --port 4096

OpenCode muss aus der Umgebung gestartet werden, in der MAILFLOW_MCP_TOKEN gesetzt wurde, damit {env:MAILFLOW_MCP_TOKEN} im Beispiel aufgelöst werden kann.

4. Mailflow Core starten

Ändern Sie bei Bedarf die OpenCode-Adresse in .env und starten Sie dann im entpackten Runtime-Verzeichnis:

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

Für den Produktionsbetrieb müssen zwei nicht leere und unterschiedliche Token konfiguriert werden; ein Core ohne Authentifizierung wird nicht als Standardstart unterstützt. Standardmäßig sind OPENCODE_MAILFLOW_AGENT=mailflow-email und OPENCODE_REQUIRE_SAFE_AGENT=true gesetzt. Deaktivieren Sie die Validierung nicht nur, um es 'zum Laufen zu bringen'.

Rufen Sie http://127.0.0.1:8798 auf. Beim ersten Betreten der Verwaltungskonsole speichern Sie das API-Token unter 'Einstellungen'.

Aus dem Quellcode ausführen:

npm ci
npm run check
npm run dev

5. Outlook Connector starten

Entpacken Sie den Windows Connector und kopieren Sie connector.example.json als:

%LOCALAPPDATA%\Mailflow\OutlookConnector\connector.json

Setzen Sie das gleiche Connector-Token wie im Core, behalten Sie coreBaseUrl als http://127.0.0.1:8798 bei und führen Sie dann aus:

.\mailflow-outlook-connector.exe

Vollständige Konfiguration, Schlüsselübergabe und Fehlerbehebung finden Sie im Betriebshandbuch.

Wie eine E-Mail zu einer Sitzung wird

1. Der Connector übermittelt E-Mails gemäß einem stabilen Vertrag; der Core dedupliziert nach Connector-/Ereignis-ID, die interne Erfassungs-/Wiederherstellungsmethode des Connectors geht nicht in den Geschäftsvertrag ein.

2. Der Core normalisiert die E-Mail, speichert sie in SQLite und führt einen Abgleich mit der festen Version der aktivierten Regeln durch.

3. Bei einem Treffer wird ein Run mit stabilem Idempotenzschlüssel erstellt; Worker leasen den Run, bei Offline-Zustand erfolgt eine Wiederholung mit exponentiellem Backoff.

4. Der OpenCode-Adapter erstellt oder wiederverwendet eine Sitzung und fügt dem Prompt den stabilen Marker mailflow_run_id hinzu.

5. Der Core überprüft vor jeder Prompt-Übermittlung, ob der Ziel-Agent mailflow-email existiert und noch Fail-Closed-Berechtigungen hat; wenn der Agent E-Mail-Informationen benötigt, ruft er den Core über die genehmigten schreibgeschützten MCP-Tools zurück.

6. Die KI-Antwort wird zuerst als Outlook-Entwurf synchronisiert, erst nach Erfolg erscheint die Genehmigung. Bei der Genehmigung werden sowohl die Core-Entwurfsversion als auch die normalisierten Hashes von Betreff/Empfänger/Text in Outlook überprüft; jeder Schritt wird im Audit-Log protokolliert.

Sicherheitsstandardeinstellungen

• Der Core hört standardmäßig nur auf 127.0.0.1; OpenCode-Verbindungen akzeptieren nur Loopback-HTTP oder HTTPS. Remote-Klartext-HTTP wird standardmäßig abgelehnt.

• Beim ersten Start muss zuerst node dist/src/cli.js init --output .env ausgeführt werden; der Core erzwingt, dass API-Token und Connector-Token beide vorhanden, unterschiedlich und jeweils mindestens 32 UTF-8-Bytes lang sind, und lehnt öffentliche Platzhalter aus Beispielen ab. Das MCP verwendet das API-Token über MAILFLOW_MCP_TOKEN, der Connector verwendet nur das andere Token.

• Alle Core-Schreibanfragen mit Body müssen JSON Content-Type deklarieren; Nicht-JSON-Anfragen geben direkt 415 zurück.

• Der Standard-Agent ist mailflow-email. Der Core liest vor jeder Prompt-Übermittlung die Agent-Definition von OpenCode: Es muss zuerst eine Catch-All-*-Deny-Grenze geben, danach dürfen nur read/glob/grep/list innerhalb des Workspace, *.env/*.env.*-Deny über beliebige Verzeichnisebenen sowie die im Beispiel genau benannten schreibgeschützten Mailflow-MCP-Tools aufgelistet werden. Die schreibgeschützte MCP-Whitelist ist search/get/list-attachments/get-run und reine Lese-Legacy search/read; outlook_attachments, das Dateien exportieren kann, ist nicht enthalten. Fehlender Agent, nicht erkennbare Berechtigungsantwort oder andere Allow führen zu Fail-Closed.

• Regeln werden nach Erstellung standardmäßig deaktiviert, zuerst preview, dann aktivieren.

• E-Mail-Text ist Daten, keine Anweisungen; Anhänge geben standardmäßig nur Metadaten preis.

• Antworten müssen manuell genehmigt werden. Die KI-Antwort muss zuerst die Outlook-Entwurfssynchronisation abschließen; Änderungen in der Genehmigungsoberfläche machen die alte Genehmigung ungültig, stellen draft.update in die Warteschlange, und nach erfolgreicher Synchronisation wird eine neue Genehmigung erstellt, die der Benutzer erneut genehmigen muss. Wenn sich nach der Genehmigung Betreff, An (To/Cc/Bcc) oder Text in Outlook ändern, verhindert eine nicht übereinstimmende normalisierte Hash das Senden.

• Wenn das Ergebnis von MailItem.Send() prozessübergreifend unsicher ist, wird send_unknown aktiviert. Der Core führt nur 5 verzögerte Statusprüfungen durch; die Verwaltungskonsole kann 'Outlook prüfen', 'Als gesendet bestätigen' oder 'Als nicht gesendet bestätigen'. Nach Bestätigung des Nichtgesendetseins wird die alte Genehmigung ungültig und eine neue Genehmigung erstellt, die erneut angeklickt werden muss; das System macht Reconciliation niemals zu einem automatischen erneuten Senden.

• Der Import alter Daten erfolgt standardmäßig als Dry-Run; zum Anwenden des Imports ist explizit --apply erforderlich.

Die aktuelle Version des schreibgeschützten Agenten kann weiterhin den ausgewählten Workspace lesen und über die genehmigten MCP-Tools andere E-Mails in diesem Core abfragen; es ist keine pro-Run unabhängige Datensandbox. SQLite speichert auch weiterhin E-Mail-Text und Roh-Snapshots, v0.1.0 hat keine automatische Aufbewahrungsfrist-Bereinigung. Für die Produktion sollten ein dedizierter Workspace/Postfach mit minimalen Berechtigungen, kontrollierte Modellkonten, Windows-Verzeichnis-ACLs, vollständige Festplattenverschlüsselung und betriebliche Datenaufbewahrungsfristen konfiguriert werden; strenge projekt-/postfachübergreifende Isolation erfordert eine spätere Per-Run-Fähigkeit. Siehe SECURITY.md.

MAILFLOW_ALLOW_UNAUTHENTICATED_LOOPBACK=1, OPENCODE_ALLOW_INSECURE_REMOTE=1 und OPENCODE_REQUIRE_SAFE_AGENT=false sind nur für isolierte lokale Entwicklungsdiagnosen gedacht, keine Release-Konfiguration und dürfen nicht für die Verarbeitung echter E-Mails verwendet werden.

Setzen Sie Core oder OpenCode-Server nicht direkt dem öffentlichen Netz aus. Verwenden Sie bei Bereitstellungen über Windows/WSL oder zwischen Maschinen HTTPS, Quellbeschränkungen und Firewalls. Weitere Informationen finden Sie in SECURITY.md.

win-console wird nicht verschwinden

Das alte Repository wird nicht gelöscht, überschrieben oder in der Historie geändert. Mailflow bietet zusätzlich:

• Kompatibilitäts-Aliasse für alte MCP-Toolnamen;

• external-capabilities-Registrierung und Heartbeat;

• Migrationsbericht für Regeln, processed Receipts, Warteschlangen und Checkpoints;

• Standardmäßig Dry-Run, explizites Apply, SHA-256 der Quelldatei und Zielzuordnung;

• Schritte zur Vermeidung von Doppelauslösung beim Wechsel und Ein-Klick-Logik-Rollback.

Die vollständige detaillierte Zuordnung finden Sie in docs/legacy-win-console-baseline.md.

Dokumentationsnavigation

• Vollständiges Design: Benutzeroberfläche, sechs vollständige Abläufe, API, Daten, Sicherheit, Tests und schrittweise Implementierung.

• Architekturgrenzen: Warum in Core, Connector, Adapter, MCP und optionale UI aufgeteilt.

• Betriebshandbuch: Installation, OpenCode/MCP-Konfiguration, Backup, Migration, Rollback und Fehlerbehebung.

• win-console Kompatibilitätsbasis: Alte Funktionen, alte Daten und Rollback-Anforderungen.

• v0.1.0 Release Notes.

Entwicklung und Validierung

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

Windows Connector:

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

Da Outlook COM von einem echten Windows-Benutzerprofil abhängt, ist CI für Windows-Kompilierung und Nicht-COM-Tests zuständig; vor der Veröffentlichung sollten dennoch Smoke-Tests für Verbindung, E-Mail-Erfassung, Entwurfssynchronisation, doppelte Genehmigung und Senden auf dem klassischen Outlook der Zielmaschine durchgeführt werden.

Lizenz

MIT