Predictor Agent 邮件插件

可独立安装的 MCP 与本地 SMTP 执行器。用户通过邮箱验证码确认开通，自助档默认日发 50、名录日申领 100、邮箱池最多 3 个；邀请制租户沿用原配额。平台负责已核验业务名录、模板审核、全局抑制、回执及反馈；SMTP 授权码只由本机 transport 读取。公开安装入口为 https://www.xhnova.com/outreach/install.md。

安装与连接

需要 Node.js 24 或更新版本。优先安装 npm 包：

npm install --global [email protected]
predictor-outreach connect

registry 安装不可用时使用同版本 HTTPS tarball：

npm install --global https://www.xhnova.com/outreach/predictor-outreach-0.3.1.tgz

connect 输出固定提示“请点击或复制以下链接在浏览器中完成开通：”。agent 须立即把平台下发的 verificationUrl 原样放进代码块，URL 视为 opaque string，不改写、不重拼。用户打开链接，以邮箱验证码登录并确认；已有租户接入现有，没有租户自动建立自助租户。会话 10 分钟过期。授权失败或过期时停止并报告脱敏错误，不自动重试。

令牌通过一次性 poll 直达 CLI，自动写入 OUTREACH_STATE_DIR/config.json（默认 ~/.predictor-outreach），POSIX 0600、Windows 当前用户私有 ACL。页面、邮件、标准输出和 MCP JSON 均不显示令牌。连接具有 outreach:read / outreach:write / outreach:send 范围，限期并可在 Predictor 连接管理撤销；申领/建批次/配置通知需要 write，逐封授权需要 send。所有后续命令自动读取私有配置。

开通后自动自检平台、本地 SMTP 和 IMAP。仅当租户 active 且邮箱池的发信、收信均可用，输出“邮箱池已接入，可以开始申领名录发送邮件了”。缺少 SMTP 或 IMAP 时如实提示本机设置，连接仍保存，不输出成功话术。授权码只通过本机私有环境配置，不放进 config.json，不上传平台。

由 agent 自动配置 MCP stdio：

{
  "mcpServers": {
    "predictor-outreach": {
      "command": "predictor-outreach",
      "args": ["mcp"]
    }
  }
}

predictor-outreach self-check
predictor-outreach send <batchId>
predictor-outreach flush-receipts
predictor-outreach sync-bounces
predictor-outreach watch-bounces

高级与 CI 场景

优先使用 connect 私有配置。自动化测试或受控 CI 可通过本地 env 覆盖平台地址与令牌；用户无需复制令牌、手配 MCP JSON。SMTP 配置始终只在本机私有环境，agent 可让进程继承已有配置，不回显其值。

| 本地环境变量 | 用途 | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | OUTREACH_PLATFORM_URL | 可选覆盖平台 HTTPS 地址，默认 https://www.xhnova.com；保留部署前缀，测试可用 loopback HTTP | | OUTREACH_TOKEN | 高级场景覆盖限范围连接令牌；通常自动读取 connect 私有配置 | | OUTREACH_SMTP_1、OUTREACH_SMTP_2… | host:port:user:pass，冒号出现在 pass 中仍可解析；user 必须是真实自有团队邮箱 | | OUTREACH_IMAP_1、OUTREACH_IMAP_2… | host:993:user，编号、user 对应同号 SMTP；默认复用本机 SMTP 授权码，163/QQ 可自动推断收信主机 | | OUTREACH_IMAP_PASS_1、OUTREACH_IMAP_PASS_2… | 仅 IMAP 凭据与 SMTP 不同时设置；只由本机 IMAP transport 读取 | | OUTREACH_STATE_DIR | 默认用户目录 .predictor-outreach，所有插件实例必须共享同一持久目录；不要放进仓库、临时目录或删除日志后重发 | | OUTREACH_HTTP_PORT | 可选本机 MCP 端口，默认 3457 | | OUTREACH_LOCAL_HTTP_TOKEN | 可选本机 HTTP MCP 的独立 >=32 字符令牌；不得复用平台令牌 |

命令继承操作系统本地环境。授权码不上传服务器、不进聊天、不进日志、不进 git。保存在本地用户私有环境时，确保文件在仓库之外并限制文件权限。自检返回邮箱标识和可用状态，不返回 host 或授权码。公网 SMTP 必须使用 465 TLS 或 STARTTLS；证书校验不能关闭。loopback SMTP 仅用于本机演示。

批量发送路径

1. outreach_status 读取权限、配额、熔断及本地邮箱可用状态。
2. directory_request 按地区和 business 用途申领，每次 <=500，重试沿用原 idempotencyKey。
3. templates_list / template_get 选择人工审核上架的模板并阅读落款规则。
4. campaign_create 将模板和申领批次绑定，获得 batchId、反馈 Reply-To 和发送规则。
5. 用户要求发送后明确调用 campaign_send（或本地 send CLI）。创建批次本身不发送。
6. campaign_status / replies_list 观察回执与回复。真人线索默认邮件提醒用户（机构名、摘要、看板链接），由用户跟进。飞书/企微是可选附加通道，没有配置 webhook 时跳过，不阻塞批量发送与邮件提醒。

本地执行器只用平台下发快照，不接收任意地址或自写邮件正文。每封 SMTP 前向平台申请授权，平台重新检查抑制、模板上架、配额、熔断、令牌及租户权限。插件按邮箱轮发、单账号上海日 <=50、失败/未知率 >5% 停用，并遵守更严格的平台下发规则。HTML 变量转义，主题和地址拒绝 CRLF。

SMTP 调用前 fsync intent；成功后先 fsync sent，再提交平台回执。网络中断后 flush-receipts 补报，不再次发送。SMTP 异常或崩溃遗留 intent 视为 unknown，自动发送会跳过该地址，需要人工查询邮箱服务商记录。幂等维度是 campaign + address，持久日志覆盖跨重启、每日计数和多进程排他；平台逐封授权同时阻止不同机器重复申请。

本机发件邮箱退信回收

业务邮件的 Reply-To 由平台 inb 收信入口归批；SMTP 退信通常返回原发件邮箱。本插件通过本机 IMAP 只读检查该邮箱的 INBOX，使用发送日志中的原邮件编号、平台授权、发件账号和失败地址匹配永久退信。延迟通知、自动回复以及缺少或矛盾的发送依据不会自动记为永久退信。不会设置已读、移动或删除邮件。

sync-bounces 单次同步；watch-bounces 前台持续运行，每 5 分钟同步一次。MCP 提供空参数 bounce_sync 与 bounce_status。发送前后主动同步；发送前收信健康失败则停止新发送，修复后再执行同步。平台核对当前租户与每封授权，退信写入现有全局抑制并执行既有熔断；重复同步幂等，不重新 SMTP 发送。

163/QQ 的 IMAP 默认主机由同号 SMTP 账号推断；其他邮箱在本机设置 OUTREACH_IMAP_N。只在使用不同凭据时设置 OUTREACH_IMAP_PASS_N。所有凭据仍留本机私有环境，不写入平台或 config.json。只上报匹配退信的原始 MIME 作为验证依据，不同步普通收件箱邮件。

持久游标和处理状态保存到同一个 OUTREACH_STATE_DIR/bounce-state.json，断网后保留待处理记录，下次恢复同步。bounce_status 包含每个邮箱的 pending、rejected 和 checkedAt：外部未匹配 DSN 保留待核查，本插件报告被 API 永久拒绝或退信畸形需人工核验时停止新发送。API 400/403/409 不由常驻轮询反复提交；核查并修复拒绝原因后才可使用高级命令 sync-bounces --retry-reviewed。不得改 UID、原 Message-ID 或证据绕过拒绝。

使用旧 0.2.0 发送的日志如无原邮件编号，先核查邮箱服务商投递记录，不伪造匹配或重新发送。用户电脑和 watch-bounces 进程必须运行且能连网；电脑关闭时不能回收。开始持续拓客前保持该命令运行，查看 bounce_status 的上次同步和健康状态，失败时暂停发送并及时修复。

SMTP 无法提供跨远程服务的原子提交。 插件选择遇到不确定结果时保留未知，避免重复发送。不要清空、移动、复制或手工改写日志来恢复发送。日志损坏和无法确认的锁持有者会停止执行，需要用户先核查投递记录。

本机 Streamable HTTP

predictor-outreach http

仅监听 127.0.0.1。连接 http://127.0.0.1:3457/mcp，设置 Authorization: Bearer <本机HTTP令牌>；限制 Host/Origin、请求大小，使用无会话 Streamable HTTP。平台令牌自动读取本机私有配置，高级场景可用 env。远程 agent 请在自己的机器运行 stdio 插件，或通过自己管理的安全连接接入自己的本机实例。平台 REST 文档见 openapi.json，操作说明见 SKILL.md。

开发与验收

pnpm --filter predictor-outreach build
pnpm --filter predictor-outreach test
npm pack --dry-run

包只分发 dist、说明与 OpenAPI，不含 workspace runtime 引用、源代码测试、.env 或本地状态。测试启动 loopback SMTP server 并发送 50 封合成机构演示邮件，核对回执与恢复零重复；不访问真实机构地址。插件不修改 SMTP 密码、不开放整库导出，不采集信访、监督、信息公开渠道，不自动确认真人线索。