# Predictor 邮件外联插件 · 01 / 02 / 03

用户只需把下面一句话发给自己的 agent：

> 请阅读 https://www.xhnova.com/outreach/install.md，为我安装并配置邮件外联插件。

本文件面向执行安装的 agent。插件提供 Predictor MCP 与本地 SMTP 执行器，使用平台已核验的业务名录和已审核邮件模板。需要 Node.js 24 或更新版本；SMTP 授权码只留在用户本机。不要在聊天、命令输出、日志、git 或平台请求中展示授权码与连接令牌。

## 01 · 安装

检查 Node.js 版本，优先从 npm registry 安装固定版本：

```sh
npm install --global predictor-outreach@0.4.3
```

只有 registry 安装不可用时，使用官方 HTTPS tarball 兜底：

```sh
npm install --global https://www.xhnova.com/outreach/predictor-outreach-0.4.3.tgz
```

安装后按用户 agent 的 MCP 配置格式自动写入以下 stdio server；无需用户手写 JSON，连接令牌不写入 MCP JSON。

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

如果 agent 不支持修改 MCP 配置，保留 CLI 安装并如实报告该限制。安装和开通不会发送业务邮件。

## 02 · 开通

在用户本机启动下面命令，保持进程运行，让它继续轮询：

```sh
predictor-outreach connect
```

CLI 创建 10 分钟开通会话，输出一条 verificationUrl。**该 URL 是不可修改的 opaque string。** 不重新拼接、不改域名、路径、编码或参数，不自行添加 agent 的回调地址。拿到输出后立即向用户展示下列固定文案，再把 CLI 输出的整条 URL 原样放进代码块：

> 请点击或复制以下链接在浏览器中完成开通：

用户打开页面后，以邮箱验证码登录并点击“确认开通”。已有租户接入现有租户，没有租户时自动建立自助租户。页面说明能力范围、期限和配额；页面和邮件不显示连接令牌。

CLI 在后台每 3 秒轮询。成功签发的令牌只通过 poll 直达该 CLI，并自动保存到用户本机 `OUTREACH_STATE_DIR/config.json`；默认目录为 `~/.predictor-outreach`。文件只含平台地址与连接令牌，POSIX 权限为 0600；Windows 使用当前用户私有 ACL。不要读取或打印该文件，不要让用户复制令牌，不把配置加入仓库。所有插件实例应共享同一持久状态目录。

**授权失败、HTTP 拒绝、会话过期或已消费时停止并报告脱敏错误，不自动重新创建会话或重试授权。** 一次成功签发后 poll 再次调用返回 410；用户可在 Predictor 的连接管理中查看、撤销该连接。不要清空原有发送日志。

## 03 · 自检与完成

`connect` 自动检查租户状态和本机邮箱池的 SMTP、IMAP 连通。若用户已经在本机私有环境配置 SMTP，agent 只让 CLI 继承这些变量，不读取或输出其值。SMTP 变量为 `OUTREACH_SMTP_N=host:port:user:pass`，公网连接需要 TLS/STARTTLS 和有效证书。自助档默认日发 50、名录日申领 100、邮箱池最多 3 个；配额提升由运营人工处理。

若本机还没有 SMTP 配置，平台连接仍会安全保存；如实报告“平台已连接，邮箱池尚未配置”，指导用户在本机私有环境中完成邮箱提供商设置。授权码不得发到聊天、不得自动上传、不得写进 `config.json`。随后运行：

```sh
predictor-outreach self-check
```

自检只返回租户状态、邮箱标识和可用状态。只有平台状态 active、邮箱池非空且 SMTP/IMAP 全部可用时，输出下列固定完成话术：

> 邮箱池已接入，可以开始申领名录发送邮件了

自检未通过时不输出该话术；修复本机配置后再检查。真实发送前，先调用 `outreach_status`，按地区和业务用途小批申领名录，选择已审核上架模板，再创建批次。创建批次不发送；只有用户授权发送后调用 `campaign_send`。全局抑制、审核、配额、熔断和封禁始终生效。

## 发件邮箱退信回收

`0.3.1` 增加本机 IMAP 退信同步。163/QQ 使用同号 SMTP 账号及本机授权码推断收信配置；其他邮箱在本机私有环境配置 `OUTREACH_IMAP_N=host:993:user`，编号和 user 匹配 SMTP_N。仅 IMAP 凭据不同时设置 `OUTREACH_IMAP_PASS_N`，不在聊天或 MCP JSON 中展示。

开始发送前执行 `predictor-outreach sync-bounces`。持续拓客时保持下面进程运行，每 5 分钟检查一次发件邮箱 INBOX：

```sh
predictor-outreach watch-bounces
```

插件只读收件箱、按原投递依据上报匹配的永久退信；不会改已读、删除或移动邮件。发送前收信失败时停止新发送，恢复后先同步。MCP 的 `bounce_sync` / `bounce_status` 可执行单次同步和查看健康。电脑、进程必须运行并能连网；电脑关闭时无法回收。保留原 `OUTREACH_STATE_DIR` 的发送日志与退信游标，升级不重新发送旧批次。

接口文档：[OpenAPI](https://www.xhnova.com/outreach/openapi.json)。完整操作约束：[SKILL.md](https://www.xhnova.com/outreach/SKILL.md)。安装和升级验收只使用演示名录与自有邮箱；是否开始真实业务发送，以用户的明确发送请求及平台审核、抑制、配额和熔断状态为准。