aizzaua/dsh-mail-connector

简体中文 · English

dsh-mail-connector · DeepSeek Harness 邮箱连接器

通过 IMAP/SMTP 连接邮箱，支持收发邮件、搜索、附件下载。支持 163、126、yeah.net 等网易邮箱及其他标准 IMAP/SMTP 邮箱。

在 DeepSeek Harness Web 界面的输入框工具行加入一个 「邮箱」按钮，点击后填写自己的邮箱地址与 IMAP/SMTP 服务器信息即可连接；同时向模型注册一个 mail 工具，让 AI 直接读信、搜索、下载附件和发信。

plugin type deps node license

✨ 功能

| 能力 | 说明 |
| --- | --- |
| 📥 收信 | 列出任意文件夹的邮件，显示发件人 / 主题 / 时间 / 未读状态 |
| 📖 阅读 | 完整 MIME 解析：multipart、base64、quoted-printable、GBK/GB2312 中文正文、HTML 转文本 |
| 🔍 搜索 | 按主题 / 发件人 / 正文搜索，支持中文关键词（IMAP CHARSET UTF-8 字面量搜索） |
| 📎 附件 | 列出附件并一键下载到本地目录 |
| ✉️ 发信 | 纯文本 / HTML / 附件，收件人与抄送，中文主题自动 RFC 2047 编码 |
| 🗂 文件夹 | 自动识别收件箱 / 已发送 / 草稿 / 垃圾邮件 / 已删除 |
| 🤖 AI 工具 | 模型可调用 mail 工具完成上述全部操作 |
| 🔐 凭据 | 账户配置保存在本地工作区，不经过任何第三方服务 |

📦 部署指导

整个插件零依赖、无构建步骤，不需要 npm install。部署就是三步：克隆 → 配置路径 → 在 DSH 里激活。

前置条件

| 条件 | 要求 | 检查方式 |
| --- | --- | --- |
| Node.js | ≥ 18（开发环境 v24） | node --version |
| DeepSeek Harness | 0.1.0-rc.7 及以上，且能用 Cordis 动态插件 | DSH Web 界面可用 |
| 网络 | 能出站访问邮件服务器的 993 / 465（或 587）端口 | 见下方「排障」 |
| 邮箱 | 已开启 IMAP 服务并取得客户端授权码 | 见「网易邮箱设置要点」 |

第 1 步：克隆仓库

git clone https://github.com/aizzaua/dsh-mail-connector.git
cd dsh-mail-connector

放在哪个目录都可以，但路径要固定下来 —— 宿主半需要用绝对路径去启动桥接进程。建议避开中文和空格路径以减少意外（本项目本身支持中文路径，但部分第三方沙箱不支持）。

第 2 步：写入本机路径

src/host.js 顶部有一个 PROJECT_ROOT 常量，指向仓库根目录。跑一次脚本让它指向你自己的目录：

node scripts/configure-paths.mjs

输出 ✓ 已更新 src/host.js 即可。其他用法：

node scripts/configure-paths.mjs --check          # 只检查当前配置，不写入
node scripts/configure-paths.mjs /opt/dsh-mail    # 显式指定目录（例如仓库将被移动到别处）

也可以不改代码，改用环境变量 —— 启动 DSH 前设置 DSH_MAIL_ROOT 指向仓库根目录即可；两者都没有时会退回到 DSH 进程的工作目录。优先级为：PROJECT_ROOT 常量 > DSH_MAIL_ROOT 环境变量 > 进程工作目录。

第 3 步：发布前自检

node scripts/check.mjs

它会依次验证：插件两半能否作为函数体解析、是否含 import/export 等 cordis_define 不接受的语法、桥接引擎 selftest 是否通过、PROJECT_ROOT 是否指向当前仓库、以及工作区里的凭据文件是否已被 .gitignore 排除。全绿输出形如：

1) 插件两半语法
✓ src/host.js 可作为函数体解析（12474 字符）
✓ src/client.js 无 import/export/类型注解
2) 桥接引擎 selftest
✓ 引擎可用（Node v24.18.0 / win32 / 17 个域名预设）
3) PROJECT_ROOT 配置
✓ 指向当前仓库：/opt/dsh-mail-connector
4) 凭据文件
✓ 工作区内没有本地凭据文件

✓ 全部检查通过，可以发布。

第 4 步：在 DeepSeek Harness 中激活

在 Cordis 模式的会话里，把两个文件的完整内容分别作为 code.host 与 code.client 交给 cordis_define，再用 cordis_run 激活：

| 参数 | 取值 |
| --- | --- |
| name | mail-connector |
| code.host | src/host.js 的全部内容 |
| code.client | src/client.js 的全部内容 |

最省事的说法是直接让 DSH 里的模型来做：

「读取 src/host.js 和 src/client.js，用 cordis_define 定义名为 mail-connector 的插件，然后 cordis_run 激活。」

激活成功的标志：

1. 宿主日志出现 mail-connector host ready, root = … , transport = subprocess；
2. 浏览器输入框左侧出现「邮箱」按钮（首次可能需要在界面上点击授权）；
3. 模型的工具列表里出现 mail。

⚠️ 动态 Cordis 插件的定义只活在当前 DSH 进程里，重启 DSH 后需要重新 cordis_define + cordis_run。仓库里的源码就是可以直接重新提交的定义，账户配置存在磁盘上不会丢。

第 5 步：连接邮箱

1. 在输入框左侧点击 「邮箱」 按钮；
2. 填写邮箱地址 —— IMAP/SMTP 服务器会自动推断；
3. 密码栏填写 客户端授权码（网易、QQ 邮箱必须用授权码，不是登录密码）；
4. 点「测试连接」验证，再点「保存并连接」。

保存后按钮上的圆点会变成绿色，切到「收件箱」即可看到邮件。凭据写入 .dsh-mail/account.json（已被 .gitignore 排除）。

想脚本化预置账户，可参考 .dsh-mail.example.json 的字段结构。

部署到另一台机器 / 服务器

流程完全相同，只有两点要注意：

- 路径：在新机器上重新跑一次 node scripts/configure-paths.mjs，或者设置 DSH_MAIL_ROOT 环境变量，切勿把上一台机器的绝对路径带过去；
- 凭据：.dsh-mail/ 不在仓库里，新机器需要重新在界面上填一次账户信息。

服务器上的完整部署
git clone https://github.com/aizzaua/dsh-mail-connector.git /opt/dsh-mail-connector
cd /opt/dsh-mail-connector
node scripts/configure-paths.mjs
node scripts/check.mjs
然后在 DSH 会话里 cordis_define + cordis_run

升级

git pull
node scripts/configure-paths.mjs   # 拉取会覆盖 PROJECT_ROOT，重跑一次
node scripts/check.mjs
在 DSH 里重新 cordis_define + cordis_run 载入新代码

📮 网易邮箱设置要点

163 / 126 / yeah.net 邮箱需要先开启 IMAP 服务并取得授权码：

1. 登录网页版邮箱 → 设置 → POP3/SMTP/IMAP；
2. 开启 IMAP/SMTP 服务；
3. 按提示手机验证后，系统会给出一串 客户端授权码；
4. 在插件里把这串授权码填进「密码 / 客户端授权码」栏。

内置预设：

| 域名 | IMAP | SMTP | 加密 |
| --- | --- | --- | --- |
| 163.com | imap.163.com:993 | smtp.163.com:465 | SSL/TLS |
| 126.com | imap.126.com:993 | smtp.126.com:465 | SSL/TLS |
| yeah.net | imap.yeah.net:993 | smtp.yeah.net:465 | SSL/TLS |
| 188.com / vip.163.com | imap.188.com / imap.vip.163.com:993 | 对应 smtp:465 | SSL/TLS |
| qq.com / foxmail.com | imap.qq.com:993 | smtp.qq.com:465 | SSL/TLS |
| exmail.qq.com | imap.exmail.qq.com:993 | smtp.exmail.qq.com:465 | SSL/TLS |
| gmail.com | imap.gmail.com:993 | smtp.gmail.com:465 | SSL/TLS |
| outlook.com / hotmail.com | outlook.office365.com:993 | smtp.office365.com:587 | STARTTLS |
| sina / sohu / aliyun / yahoo / icloud | 见 bin/mail-bridge.mjs 中 PRESETS | | |

未列出的域名会按 imap. / smtp. 猜测，也可以手动填写。

🤖 模型工具 mail

插件激活后模型可直接调用：

{ "op": "list",     "mailbox": "INBOX", "limit": 20 }   // 列出邮件
{ "op": "search",   "query": "发票" }                     // 搜索
{ "op": "message",  "uid": 12345 }                        // 读取正文
{ "op": "download", "uid": 12345, "part": "1.2" }         // 下载附件
{ "op": "send", "to": "a@example.com", "subject": "你好", "text": "正文" }
{ "op": "mailboxes" }                                     // 文件夹列表
{ "op": "test" }                                          // 测试连接

对话示例：

「看一下我邮箱里最新的 10 封邮件」
「搜索包含『发票』的邮件并把附件下载下来」
「给 zhang@example.com 发一封主题为『周报』的邮件」

🖥 命令行独立使用

桥接引擎本身就是一个可独立运行的 CLI，不依赖 Harness：

最简单：stdin 传 JSON
echo '{"op":"test","config":{"email":"you@163.com","password":"授权码"}}' | node bin/mail-bridge.mjs

或者用请求文件（受限环境里管道不可用时更稳）
node bin/mail-bridge.mjs --file ./request.json

或者用 base64 参数（宿主半的降级路径用的就是这个）
node bin/mail-bridge.mjs --payload $(printf '%s' '{"op":"list","config":{"email":"you@163.com","password":"授权码"},"limit":10}' | base64 -w0)

结果以 >>{...}>> 标记包裹输出，便于程序提取。

支持的 op

| op | 参数 | 说明 |
| --- | --- | --- |
| selftest | — | 环境自检 |
| guess | email | 推断服务器设置 |
| test | config | 同时验证 IMAP 与 SMTP |
| mailboxes | config | 文件夹列表 |
| list | config, mailbox?, limit?, offset?, search? | 列表 / 搜索 |
| message | config, uid, mailbox?, markSeen? | 读取整封邮件 |
| download | config, uid, part, dir? | 下载附件 |
| send | config, to, cc?, bcc?, subject?, text?, html?, attachments? | 发信 |
| flag | config, uid, add?, remove?, expunge? | 修改标记 / 删除 |
| saveConfig / loadConfig / forgetConfig | config?, dir? | 账户配置持久化 |

完整的请求 / 响应示例见 docs/protocol.md。

🏗 架构

浏览器（Client 半 src/client.js）
├─ conversation.input.left  →  「邮箱」按钮
└─ shell.overlay           →  配置 / 收件箱 / 阅读 / 写信面板
│  host.call('mail', {...})   ← Package 私有 JSON RPC
▼
宿主（Host 半 src/host.js）
├─ harness.handle('mail')     →  给浏览器用
└─ harness.registerTool(mail) →  给模型用
│  ctx.subprocess.spawn(['node', 'bin/mail-bridge.mjs'])  ← 请求走 stdin
▼
桥接引擎（bin/mail-bridge.mjs · 零依赖）
├─ ImapClient  ── node:tls  ── IMAP4rev1（LOGIN/ID/LIST/EXAMINE/UID FETCH/UID SEARCH/STORE）
├─ SmtpClient  ── node:tls/net ── SMTP（EHLO/STARTTLS/AUTH LOGIN|PLAIN/DATA）
└─ MIME 解析与组包（RFC 822 / 2045 / 2047 / 2231）

为什么用独立进程？浏览器半不能开 TCP，宿主半的受限运行环境也拿不到 node:tls；把协议实现放进一个由 ctx.subprocess 启动的子进程里，既拿到完整 Node 能力，又让所有副作用随插件停止而消失。

为什么用 ctx.subprocess 而不是 ctx.shell？ctx.shell 会强制经过命令沙箱层，在沙箱后端不可用的主机上会直接拒绝执行（见「排障」）。ctx.subprocess 是更低层的进程 seam，请求通过 stdin 传入，同时避开了长参数与中文转义问题。

📁 目录结构

.
├── bin/
│   └── mail-bridge.mjs         # 零依赖 IMAP/SMTP 引擎（可独立 CLI 运行）
├── src/
│   ├── host.js                 # Cordis Host 半：RPC + mail 模型工具
│   └── client.js               # Cordis Client 半：邮箱按钮 + 浮层面板
├── scripts/
│   ├── configure-paths.mjs     # 一键把 PROJECT_ROOT 写成本机路径
│   └── check.mjs               # 部署前自检（语法 / 引擎 / 路径 / 凭据）
├── docs/
│   └── protocol.md             # 桥接协议与请求/响应示例
├── .dsh-mail.example.json      # 账户配置字段示例（无真实凭据）
├── .gitignore                  # 排除 .dsh-mail/ 等敏感路径
├── .gitattributes
├── package.json
├── LICENSE
├── README.md                   # 英文说明
└── README.zh-CN.md             # 中文说明

运行时生成、不进仓库：
├── .dsh-mail/account.json      # 你的邮箱地址与授权码
└── mail-attachments/           # 下载的附件

🔒 安全说明

- 凭据只保存在本机 .dsh-mail/account.json，密码字段做 base64 编码存放（混淆，不是加密），请确保该目录不被提交到仓库（已在 .gitignore 中排除）。
- 所有网络连接直连你填写的邮件服务器，不经过任何中间服务。
- 默认校验 TLS 证书；仅在自建服务器证书不受信任时才需要 allowInsecureTls。
- 建议始终使用「客户端授权码 / 应用专用密码」而非主密码。
- 模型工具 mail 能读你的全部邮件并以你的身份发信 —— 只在你信任的会话里激活本插件。

🛠 排障

桥接进程启动失败：no sandbox backend is usable on this host

完整报错形如：

sandbox mode "workspace-write" is requested but no sandbox backend is usable on this host;
refusing to run the command unconfined. ...
Runner failure: windows-acl-run: Windows ACL temp root must be outside the workspace

原因：宿主半若经由 ctx.shell 执行命令，会强制走命令沙箱层；当主机上沙箱后端不可用时（如 Windows ACL runner 因临时目录落在工作区内而判定失败），沙箱会拒绝执行而不是无防护地放行。

本项目的处理方式：src/host.js 优先使用 ctx.subprocess 直接 spawn 子进程 —— 这是更低层的进程 seam，不做命令封禁 —— 并把 JSON 请求通过 stdin 传入而非命令行参数（顺带避开长参数与中文转义问题）；ctx.shell 仅在 subprocess 不可用时作为降级路径。

如果你自己扩展宿主半遇到同类报错，请照此改造传输层，而不要去放宽沙箱设置。

未找到 node 可执行文件 或 桥接进程没有返回结果

绝大多数是路径没配对。依次确认：

node scripts/configure-paths.mjs --check   # PROJECT_ROOT 是否指向当前仓库
node scripts/check.mjs                     # 引擎能否独立跑通

若两条都通过而 DSH 里仍失败，让模型调用一次 host 的 paths 处理器（返回 projectRoot / bridgePath / transport），核对宿主进程看到的路径是否真实存在。

spawnSync … EPERM（自检脚本里）

受限环境（DSH 沙箱、部分 CI 容器）不允许进程打开命名管道。scripts/check.mjs 已改用临时文件承接子进程输出来规避；如果你自己写脚本调桥接引擎，请用 --file 传请求、并把 stdout 重定向到文件，而不要用管道捕获。

Login fail. Please enter authorization code

网易 / QQ 邮箱填了登录密码。改用客户端授权码。

connect ETIMEDOUT

服务商未开启 IMAP 服务，或本机网络 / 防火墙拦截了 993 / 465 端口。

SMTP 命令失败 (535)

SMTP 认证失败。检查授权码，以及加密方式与端口是否匹配：465 用 SSL/TLS，587 用 STARTTLS。

插件在 DSH 重启后消失

动态 Cordis 插件的定义只存在于当前 DSH 进程，重启后需要重新 cordis_define + cordis_run。仓库里的 src/host.js 与 src/client.js 就是可直接重新提交的源码；账户配置保存在磁盘上，不会随进程丢失。

更多错误对照见 docs/protocol.md。

🧩 兼容性

- Node.js ≥ 18（开发环境为 v24）
- Windows / macOS / Linux
- DeepSeek Harness 0.1.0-rc.7 及以上（Cordis 动态插件）

🤝 贡献

欢迎 issue 与 PR。提交前请跑一遍 node scripts/check.mjs，并确认 git status --short 里没有 .dsh-mail/。

📄 License

MIT