Mailflow

让经典版 Outlook 的邮件可靠地触发 OpenCode 会话和 prompt，同时给 OpenCode agent 一组受控的邮件 MCP 工具。

Mailflow 没有把邮件监听、规则、会话调用、审批和 UI 再次揉进一个大插件。首版采用独立 Core、Windows Outlook connector、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 connector 只做 Outlook 数据适配、可靠交付和 Outlook 原生动作；具体传输机制不是 Core 的契约。

• Core 是唯一事实源，负责 SQLite、规则版本、幂等、重试、审计、审批和 connector 命令。

• Core 直接调用 OpenCode HTTP API 创建会话并异步提交 prompt。

• MCP 只为会话中的 agent 提供邮件读取、附件导出、回复草稿和受审批发送工具；它不监听邮箱。

• 管理台承担规则、运行、审批和故障恢复，不依赖 Outlook 面板。

Outlook 插件还是 OpenCode 插件？

首版两边都不做“重插件”。这是刻意选择：

所以：设计内容当然能显示在 Outlook 扩展面板上，但不应把核心放进去。经典 Outlook 的 VSTO/COM 加载项受 Office 位数、签名、加载禁用和进程生命周期影响。当前可交付版本使用独立的托盘式 COM connector；以后增加薄 VSTO 面板时不需要改 Core、MCP 或数据库。OpenCode 插件同样是可选体验层，触发会话已经由稳定的 HTTP API 完成。

v0.1.0 已包含

• Node.js 24 + 内置 SQLite 的零运行时依赖 Core。

• 邮件事件入库、规则匹配、规则版本、run 状态机、幂等键、租约、退避重试和 dead letter。

• OpenCode session 创建与 prompt_async，支持 per-message、per-conversation 和 pinned-session 策略。

• prompt 安全 envelope：邮件内容明确标为不可信数据，支持正文/附件上限。

• 标准 MCP stdio server，以及 outlook_search、outlook_read、outlook_attachments 等旧工具别名。

• Windows x64 Outlook Classic connector：邮件交付、Outlook 原生读写、命令幂等和发送对账。

• send_unknown 安全闭环：5 次有界延迟检查、管理台人工确认，以及“确认未发送后生成全新审批”；任何检查都不会自动重发。

• 回复草稿先同步 Outlook 再开放审批；主题、收件人和正文的规范化哈希共同阻止旧稿发送，自动发送默认关闭。

• 中文本地管理台、REST API 与 SSE 状态流。

• win-console 规则/状态 dry-run 导入、能力注册/心跳和明确回滚路径。

• Linux Core 测试、Windows connector 构建和 tag 驱动的 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 connector；

• aleygey-email-workflow-0.1.0.tgz：npm 格式运行包。

Core 要求 Node.js 24+；connector 要求 Windows x64 与经典版桌面 Outlook。

2. 先初始化密钥并合并 OpenCode 安全配置

不要先启动 OpenCode，也不要用示例文件覆盖现有 opencode.json/opencode.jsonc。先在 runtime 解压目录生成 .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。runtime zip 用户把示例里的 command 改为本机绝对路径，例如：

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

示例不会内嵌秘密。启动 OpenCode 的同一用户环境必须设置 MAILFLOW_MCP_TOKEN，值与 .env 中的 MAILFLOW_API_TOKEN 相同；它不是 connector token：

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

MAILFLOW_CONNECTOR_TOKEN 只给 Outlook connector 使用，并且必须与 API/MCP token 不同。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 地址，然后在 runtime 解压目录启动：

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

发布运行必须配置两个非空且不同的 token；不支持把无认证 Core 当作默认启动方式。默认 OPENCODE_MAILFLOW_AGENT=mailflow-email 与 OPENCODE_REQUIRE_SAFE_AGENT=true，不要为了“先跑起来”关闭验证。

访问 http://127.0.0.1:8798。第一次进入管理台，在“设置”保存 API token。

从源码运行：

npm ci
npm run check
npm run dev

5. 启动 Outlook connector

解压 Windows connector，把 connector.example.json 复制为：

%LOCALAPPDATA%\Mailflow\OutlookConnector\connector.json

设置与 Core 相同的 connector token，保持 coreBaseUrl 为 http://127.0.0.1:8798，然后运行：

.\mailflow-outlook-connector.exe

完整配置、密钥传递和排障步骤见运行手册。

一封邮件如何变成会话

1. connector 按稳定契约提交邮件；Core 接收后按 connector/event ID 去重，connector 的内部摄取/恢复方式不进入业务契约。

2. Core 规范化邮件，保存到 SQLite，并对已启用规则的固定版本执行匹配。

3. 命中后创建带稳定幂等键的 run；worker lease run，离线时按指数退避重试。

4. OpenCode adapter 创建或复用 session，并在 prompt 中加入 mailflow_run_id 稳定标记。

5. Core 在每次提交 prompt 前验证目标 mailflow-email agent 存在且仍为 fail-closed 权限；agent 如需邮件信息，通过获准的只读 MCP 工具回调 Core。

6. AI 回复先同步为 Outlook 草稿，成功后才出现审批。批准时同时校验 Core 草稿版本和 Outlook 的主题/收件人/正文规范化哈希；每一步都写 audit log。

安全默认值

• Core 默认仅监听 127.0.0.1；OpenCode 连接只接受 loopback HTTP 或 HTTPS。远程明文 HTTP 默认拒绝。

• 首次启动必须先执行 node dist/src/cli.js init --output .env；Core 强制 API token 和 connector token 同时存在、互不相同、各自至少 32 个 UTF-8 字节，并拒绝示例中的公开占位符。MCP 通过 MAILFLOW_MCP_TOKEN 使用 API token，connector 只使用另一套 token。

• 所有带正文的 Core 写请求必须声明 JSON Content-Type；非 JSON 请求直接返回 415。

• 默认 agent 是 mailflow-email。Core 每次发送 prompt 前都会从 OpenCode 读取 agent 定义：必须先有 catch-all * deny 边界，随后只能列举 workspace 内的 read/glob/grep/list、覆盖任意目录层级的 *.env/*.env.* deny，以及示例中精确命名的只读 Mailflow MCP 工具。只读 MCP 白名单是 search/get/list-attachments/get-run 与纯读 legacy search/read；可导出文件的 outlook_attachments 不在其中。agent 缺失、权限响应不可识别或出现其他 allow 都会 fail closed。

• 规则创建后默认关闭，先 preview 再启用。

• 邮件正文是数据，不是指令；附件默认只暴露元数据。

• 回复必须人工审批。AI 回复要先完成 Outlook 草稿同步；在审批界面修改会作废旧审批、排队执行 draft.update，同步成功后生成新审批，用户必须再次点击批准。批准后若 Outlook 中的主题、To/Cc/Bcc 或正文变化，规范化哈希不匹配会阻止发送。

• MailItem.Send() 跨进程结果不确定时进入 send_unknown。Core 只做 5 次延迟状态检查；管理台可“检查 Outlook”“确认已发送”或“确认未发送”。确认未发送后旧批准失效并产生新审批，仍需再次点击，系统绝不把 reconciliation 变成自动重发。

• 旧数据导入默认 dry-run；应用导入需显式 --apply。

当前版本的只读 agent 仍能读取所选 workspace，并可通过获准的 MCP 工具查询该 Core 中的其他邮件；它不是每个 run 独立的数据沙箱。SQLite 也会持续保存邮件正文和原始快照，v0.1.0 没有自动保留期清理任务。生产使用应配置专用最小权限 workspace/邮箱、受控模型账号、Windows 目录 ACL、全盘加密和运维侧数据保留周期；严格的跨项目/跨邮箱隔离需要后续 per-run capability。详见 SECURITY.md。

MAILFLOW_ALLOW_UNAUTHENTICATED_LOOPBACK=1、OPENCODE_ALLOW_INSECURE_REMOTE=1 和 OPENCODE_REQUIRE_SAFE_AGENT=false 仅供隔离的本地开发诊断，不是发布配置，也不能用于处理真实邮件。

不要把 Core 或 OpenCode server 直接暴露到公网。跨 Windows/WSL 或跨机器部署请使用 HTTPS、来源限制和防火墙。更多说明见 SECURITY.md。

win-console 不会消失

旧仓库不删除、不覆盖、不改历史。Mailflow 额外提供：

• 旧 MCP 工具名的兼容别名；

• external-capabilities 注册与 heartbeat；

• 规则、processed receipt、队列和 checkpoint 的迁移报告；

• 默认 dry-run、显式 apply、源文件 SHA-256 和目标映射；

• 切换时的防双触发步骤与一键逻辑回滚。

完整逐项映射见 docs/legacy-win-console-baseline.md。

文档导航

• 完整设计方案：用户界面、六个完整流程、API、数据、安全、测试和分阶段实施。

• 架构边界：为何拆成 Core、connector、adapter、MCP 和可选 UI。

• 运行手册：安装、OpenCode/MCP 配置、备份、迁移、回滚和排障。

• win-console 兼容基线：旧功能、旧数据与回退要求。

• v0.1.0 Release Notes。

开发与验证

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

Windows connector：

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

由于 Outlook COM 依赖真实 Windows 用户 profile，CI 负责 Windows 编译与非 COM 测试；发布前仍应在目标机器的经典 Outlook 上执行连接、邮件摄取、草稿同步、二次审批和发送 smoke test。

许可证

MIT