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 Classic connector	当前 profile、邮件读取、草稿、附件、已审批发送	规则引擎、任务队列、OpenCode 会话状态
Mailflow Core	可靠工作流、SQLite、策略、审批、审计	Outlook UI/COM 生命周期
OpenCode	普通会话和 agent；通过 MCP 使用邮件工具	后台邮箱监听、长期 checkpoint
可选 Outlook VSTO 面板	“处理当前邮件”、状态和审批快捷入口	任何必须持续运行的核心逻辑

所以：设计内容当然能显示在 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

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

一封邮件如何变成会话

connector 按稳定契约提交邮件；Core 接收后按 connector/event ID 去重，connector 的内部摄取/恢复方式不进入业务契约。
Core 规范化邮件，保存到 SQLite，并对已启用规则的固定版本执行匹配。
命中后创建带稳定幂等键的 run；worker lease run，离线时按指数退避重试。
OpenCode adapter 创建或复用 session，并在 prompt 中加入 mailflow_run_id 稳定标记。
Core 在每次提交 prompt 前验证目标 mailflow-email agent 存在且仍为 fail-closed 权限；agent 如需邮件信息，通过获准的只读 MCP 工具回调 Core。
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

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
connector		connector
docs		docs
examples		examples
migrations		migrations
public		public
scripts		scripts
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
config.example.json		config.example.json
global.json		global.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Mailflow

最终形态

Outlook 插件还是 OpenCode 插件？

v0.1.0 已包含

快速开始

1. 下载

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

3. 启动 OpenCode

4. 启动 Mailflow Core

5. 启动 Outlook connector

一封邮件如何变成会话

安全默认值

`win-console` 不会消失

文档导航

开发与验证

许可证

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Mailflow

最终形态

Outlook 插件还是 OpenCode 插件？

v0.1.0 已包含

快速开始

1. 下载

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

3. 启动 OpenCode

4. 启动 Mailflow Core

5. 启动 Outlook connector

一封邮件如何变成会话

安全默认值

win-console 不会消失

文档导航

开发与验证

许可证

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`win-console` 不会消失