Mailflow

クラシック版Outlookのメールを確実にOpenCodeセッションとプロンプトにトリガーし、同時にOpenCodeエージェントに制御されたメールMCPツールセットを提供します。

Mailflowは、メール監視、ルール、セッション呼び出し、承認、UIを再び大きなプラグインに統合することはありません。初版では、独立したCore、Windows Outlookコネクタ、OpenCode HTTPアダプタ、および狭い責務の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はOpenCode HTTP APIを直接呼び出してセッションを作成し、プロンプトを非同期で送信します。

• MCPはセッション内のエージェントにのみ、メールの読み取り、添付ファイルのエクスポート、返信下書き、および承認済み送信ツールを提供します。メールボックスを監視しません。

• 管理コンソールはルール、実行、承認、および障害復旧を担当し、Outlookパネルに依存しません。

Related MCP server: Outlook MCP

Outlookプラグインか、OpenCodeプラグインか？

初版では、どちらの側にも「重いプラグイン」は作成しません。これは意図的な選択です：

つまり：設計内容はもちろんOutlook拡張パネルに表示できますが、コアをそこに配置すべきではありません。クラシックOutlookのVSTO/COMアドインは、Officeのビット数、署名、読み込み無効化、プロセスライフサイクルの影響を受けます。現在のリリース可能バージョンは、独立したトレイ型COMコネクタを使用しています。将来的に薄いVSTOパネルを追加する場合でも、Core、MCP、データベースを変更する必要はありません。OpenCodeプラグインも同様にオプションの体験レイヤーであり、セッションのトリガーは安定したHTTP APIによって既に完了しています。

v0.1.0 に含まれるもの

• Node.js 24 + 組み込みSQLiteによるゼロランタイム依存のCore。

• メールイベントのデータベース保存、ルールマッチング、ルールバージョン、runステートマシン、冪等キー、リース、バックオフリトライ、デッドレター。

• 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インポート、機能登録/ハートビート、明確なロールバックパス。

• Linux Coreテスト、Windowsコネクタビルド、タグ駆動のGitHubリリースワークフロー。

クイックスタート

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 を生成します：

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

examples/opencode-mailflow-complete.json の agent.mailflow-email と mcp.mailflow を既存のOpenCode設定にマージし、既存のprovider、model、agent、plugin、その他のMCPを保持します。ランタイムzipユーザーは、サンプルの command をローカルの絶対パスに変更します。例：

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

サンプルには秘密情報は埋め込まれていません。OpenCodeを起動するのと同じユーザー環境に MAILFLOW_MCP_TOKEN を設定する必要があり、その値は .env の MAILFLOW_API_TOKEN と同じです。これはコネクタトークンではありません：

$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. Mailflow Coreを起動する

必要に応じて .env のOpenCodeアドレスを変更し、ランタイム解凍ディレクトリで起動します：

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

リリース実行には、2つの非空で異なるトークンを設定する必要があります。認証なしの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. ヒットすると、安定した冪等キーを持つrunが作成されます。ワーカーがrunをリースし、オフライン時は指数バックオフでリトライします。

4. OpenCodeアダプタはセッションを作成または再利用し、プロンプトに mailflow_run_id 安定マーカーを追加します。

5. Coreはプロンプトを送信するたびに、ターゲットの mailflow-email エージェントが存在し、依然としてfail-closed権限であることを検証します。エージェントがメール情報を必要とする場合、許可された読み取り専用MCPツールを介してCoreにコールバックします。

6. AI応答はまずOutlook下書きとして同期され、成功した後にのみ承認が表示されます。承認時には、Coreの下書きバージョンとOutlookの件名/宛先/本文の正規化ハッシュの両方を検証します。各ステップで監査ログが書き込まれます。

セキュリティデフォルト値

• Coreはデフォルトで 127.0.0.1 のみをリッスンします。OpenCode接続はループバックHTTPまたはHTTPSのみを受け入れます。リモートの平文HTTPはデフォルトで拒否されます。

• 初回起動時は、まず node dist/src/cli.js init --output .env を実行する必要があります。CoreはAPIトークンとコネクタトークンの両方が存在し、互いに異なり、それぞれ少なくとも32 UTF-8バイトであることを強制し、サンプルの公開プレースホルダーを拒否します。MCPは MAILFLOW_MCP_TOKEN を介してAPIトークンを使用し、コネクタは別のトークンのみを使用します。

• 本文を含むすべてのCore書き込みリクエストは、JSON Content-Typeを宣言する必要があります。非JSONリクエストは直接 415 を返します。

• デフォルトのエージェントは mailflow-email です。Coreはプロンプトを送信するたびに、OpenCodeからエージェント定義を読み取ります。まずcatch-allの * deny境界が必要であり、その後、ワークスペース内の read/glob/grep/list、任意のディレクトリ階層をカバーする *.env/*.env.* deny、およびサンプルで正確に命名された読み取り専用Mailflow MCPツールのみを列挙できます。読み取り専用MCPホワイトリストは、search/get/list-attachments/get-run と純粋読み取りのレガシー search/read です。ファイルをエクスポートできる outlook_attachments はこれに含まれません。エージェントの欠落、認識できない権限応答、またはその他のallowはすべてfail closedになります。

• ルールは作成後デフォルトで無効になっており、まずプレビューしてから有効にします。

• メール本文はデータであり、指示ではありません。添付ファイルはデフォルトでメタデータのみを公開します。

• 返信は必ず人間の承認が必要です。AI応答はまずOutlook下書きの同期を完了する必要があります。承認インターフェースでの変更は、古い承認を無効にし、draft.update をキューに入れ、同期成功後に新しい承認を生成します。ユーザーは再度承認をクリックする必要があります。承認後、Outlookの件名、To/Cc/Bcc、または本文が変更された場合、正規化ハッシュが一致せず、送信が阻止されます。

• MailItem.Send() のクロスプロセス結果が不確定な場合、send_unknown 状態になります。Coreは5回の遅延ステータスチェックのみを行います。管理コンソールでは「Outlookを確認」「送信済みを確認」「未送信を確認」が可能です。未送信を確認すると、古い承認は無効になり、新しい承認が生成されます。再度クリックする必要があり、システムは絶対にreconciliationを自動再送信にしません。

• 旧データのインポートはデフォルトでdry-runです。インポートを適用するには、明示的に --apply が必要です。

現在のバージョンの読み取り専用エージェントは、選択されたワークスペースを読み取ることができ、許可されたMCPツールを介してそのCore内の他のメールをクエリできます。これはrunごとの独立したデータサンドボックスではありません。SQLiteはメール本文と元のスナップショットを永続的に保存し続け、v0.1.0には自動保存期間のクリーンアップタスクはありません。本番環境では、専用の最小権限ワークスペース/メールボックス、制御されたモデルアカウント、WindowsディレクトリACL、フルディスク暗号化、運用側のデータ保持期間を設定する必要があります。厳格なクロスプロジェクト/クロスメールボックス分離には、将来の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 登録とハートビート。

• ルール、processed receipt、キュー、チェックポイントの移行レポート。

• デフォルトのdry-run、明示的なapply、ソースファイルSHA-256、ターゲットマッピング。

• 切り替え時の二重トリガー防止手順とワンクリック論理ロールバック。

完全な項目別マッピングは docs/legacy-win-console-baseline.md を参照してください。

ドキュメントナビゲーション

• 完全設計書：ユーザーインターフェース、6つの完全なフロー、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

Outlook COMは実際のWindowsユーザープロファイルに依存するため、CIはWindowsコンパイルと非COMテストを担当します。リリース前には、ターゲットマシンのクラシックOutlookで、接続、メール取り込み、下書き同期、二次承認、送信のスモークテストを実行する必要があります。

ライセンス

MIT