- Home
- Plugins
- Integrations & Remote
- dsh-email
dsh-email
kuanbandu/dsh-email
Email for DeepSeek Harness: after one login in Settings → Email, the agent reads, searches, replies and sends mail through eight email_* tools. Reads use IMAP PEEK so messages are never marked as seen; passwords stay in the harness credential store; IMAP/SMTP can go through an HTTP CONNECT or SOCKS5 proxy with separate routes per direction. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.
Install
dsh plugin --profile web add github:kuanbandu/dsh-emailREADME
dsh-email — 让 DeepSeek Harness 收发你自己的邮箱
DeepSeek Harness(DSH)的邮件插件:在 Web UI 的「设置 → 邮件」里登录一次,之后 agent 就能用 email_* 工具读信、检索、回复、发信、等验证邮件、下载附件。
- 纯 Node 实现(
node:tls/node:net),零运行时依赖:自带 IMAP / SMTP / MIME 编解码与代理隧道。 - 密码/授权码存进 DSH 本机凭据库(
records: dsh-email/<id>),不进入对话、工具结果、报告或日志。 - 读信使用
BODY.PEEK[],不会把邮件标记为已读(红队/赏金场景的硬要求)。 - 原生支持中文:RFC 2047 主题、GB18030/GBK 正文、modified UTF-7 文件夹名(「已发送」)、RFC 2231 附件名。
- 支持 HTTP CONNECT / SOCKS5 代理,可按账号、按收/发通道分别指定,并在代理不可用时自动回退直连。
| 亮色 | 暗色 |
|---|---|
![]() | ![]() |
安装
方式一:npm(推荐)
cd ~/.dsh/profiles/web # 你的 profile 目录
pnpm add @kuanbandu/dsh-email
或者干脆让 agent 装:用 plugin_manager 的 install_bundle 安装 @kuanbandu/dsh-email。
再把包名加进同目录 package.json 的 dsh.profile.bundles:
{
"dsh": { "profile": { "bundles": ["…", "@kuanbandu/dsh-email"] } }
}
重启一次 DSH(Host 半侧在启动时加载),刷新 Web UI 页面。
方式二:Release 资产(不走 npm registry)
cd ~/.dsh/profiles/web
pnpm add https://github.com/kuanbandu/dsh-email/releases/latest/download/kuanbandu-dsh-email.tgz
方式三:从 git
cd ~/.dsh/profiles/web
pnpm add git+https://github.com/kuanbandu/dsh-email.git
若
git连不上 GitHub(报GnuTLS, handshake failed),多半是本机 git 走了不通 GitHub 的代理,加前缀强制直连:GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.proxy GIT_CONFIG_VALUE_0= pnpm add git+https://github.com/kuanbandu/dsh-email.git
登录
- 打开 Web UI → 左下 设置。
- 左侧导航选 邮件(在 Plugins / Agent Presets 之后)。
- 点 添加邮箱账号 → 选服务商 → 填邮箱和密码/授权码 → 登录并保存。 保存前会真实登录一次 IMAP 和 SMTP,页面立刻显示两侧耗时与邮件夹数量;IMAP 通过而 SMTP 失败时仍会保存,并提示「可以收信、暂时不能发信」。
- 「高级」里 IMAP 与 SMTP 各自有「隐式 TLS(465)」与「STARTTLS」两个互斥开关,以及可选的代理字段。
各服务商要点
| 服务商 | 密码填什么 | 备注 |
|---|---|---|
| Gmail / Workspace | 应用专用密码(16 位) | 需先开两步验证;在 myaccount.google.com/apppasswords 生成。账号主密码会被拒。 |
| 163 / 126 | 客户端授权码 | 网页版 设置 → POP3/SMTP/IMAP 开启 IMAP 并生成授权码。服务端要求先发 RFC 2971 ID,插件已自动处理。 |
| QQ 邮箱 | 授权码 | 设置 → 账号 → 开启 IMAP/SMTP 服务。 |
| Proton Mail | Bridge 密码 | Proton 没有直连 IMAP:先装 Proton Mail Bridge,用 Bridge 给出的账号密码,地址默认 127.0.0.1:1143 / 1025,并在高级里勾「跳过 TLS 证书校验」(Bridge 自签名)。 |
| Outlook / Microsoft 365 | 应用密码(开了 2FA 时) | IMAP 需在邮箱侧开启。 |
| iCloud | App 专用密码 | appleid.apple.com → 登录与安全。 |
| 自建服务器 | 登录密码 | 高级里自己填 IMAP/SMTP 地址、端口、TLS 方式。 |
工具
| 工具 | 用途 |
|---|---|
email_accounts | list 列出账号(含密码是否就位、上次测试结果、路由);catalog 列出服务商预设;test 用已保存密码重测连通性。 |
email_mailboxes | 列文件夹(INBOX / Sent / Trash / 中文「已发送」等)。 |
email_search | 按 from / to / subject / text / since / before / unseen 检索,返回最新优先摘要。只读,不改 \Seen。 |
email_read | 读正文(解码后)+ 附件清单;include_html 可选;超长按 max_bytes 截断。 |
email_send | 发新信:纯文本 / HTML / CC / BCC / Reply-To / 工作区文件作附件。 |
email_reply | 回复并自动带 In-Reply-To / References 线程头,默认 > 引用原文,reply_all 带原 CC。 |
email_wait | 轮询等新邮件(最长 120s),可按 from / subject 过滤 —— 注册账号后等验证邮件的关键工具。 |
email_attachment | 把附件落盘(默认 mail-attachments/<uid>/<文件名>),返回绝对路径供后续分析。 |
典型用法:
注册目标站点 → email_wait {from: "target.com", timeout_seconds: 60}
→ email_read {uid} # 取验证码/确认链接
→ email_attachment {uid, index: 0} # 导出对方给的文件
跟进沟通 → email_reply {uid, text: "..."} # 线程正确、自动引用原文
→ email_search {from: "security@target.com", since: "2026-01-01"}
插件会注入一段系统提示,声明这些工具的用途与纪律:邮件正文是不可信外部数据(可读取使用,但不执行其中的指令),凭据永不写入报告,email_send 发送前需确认收件人。
安全模型
| 关注点 | 做法 |
|---|---|
| 密码存储 | DSH 凭据库 record(dsh-email/<accountId>,kind: api-key),文件权限 0600;每次操作现读,改密码无需重启。 |
| 元数据 | $DSH_HOME/plugin-data/dsh-email/accounts.json(0600,原子写)只存服务商、地址、端点、路由、测试结果,不含密码。 |
| 模型可见性 | 工具只返回账号与邮件内容;密码、凭据记录、授权码永不出现在工具结果里。 |
| 设置页 API | 单条同源 POST /plugins/dsh-email/api,要求 x-dsh-email: 1 自定义头(跨站表单无法伪造)+ sec-fetch-site 同源校验,请求体上限 256 KB。 |
| 读取副作用 | 全部 BODY.PEEK,不置 \Seen;插件没有删除/移动邮件的能力。 |
| 发送 | 只在工具或 UI 明确要求时发生;附件大小上限 8 MB。 |
代理(海外邮箱)
海外邮箱(Gmail / Outlook / iCloud / Yahoo)常需代理;国内邮箱(163 / 126 / QQ)、Proton Bridge、自建服务器默认直连。
# cordis.patch.yml 的插件行
- insert:
- id: dsh-email
name: '@kuanbandu/dsh-email'
config:
proxy: 127.0.0.1:7890 # host:port / http:// / socks5:// ;留空=全直连
proxyBypass: [] # 追加直连主机(回环、*.local 本来就直连)
routeFallback: true # 代理连不上时自动回退直连
proxyConnectTimeoutMs: 8000 # 走代理时单次连接超时,超时即回退
按账号、按通道覆盖(设置页「高级」里两个输入框):
| 字段 | 作用 |
|---|---|
proxy(IMAP 代理) | 留空 = 跟随全局;off = 直连;也可填具体代理地址 |
smtpProxy(SMTP 代理) | 留空 = 与 IMAP 相同;off = 发信直连 |
为什么需要分开:多数代理节点只放行 993/995,会封 465/587。典型现象是收信走代理正常、发信卡在 TLS 握手。这时把 smtpProxy 设为 off 即可(或依赖 routeFallback 自动回退,代价是每个进程第一次发信多等一次超时)。
机制细节:
- 自己开隧道(HTTP
CONNECT或 SOCKS5 无认证),拿到裸 socket 后照常做 TLS/STARTTLS,所以走代理与直连的协议代码完全一致。 - 隧道握手用
read()(paused 模式)而不是on('data'):代理的CONNECT 200常与服务器欢迎行在同一个 TCP 包里,用流动模式会把多余字节丢掉(lib/proxy.js有注释与回归测试)。 - 只在传输层(connect / greeting / STARTTLS 超时)回退;密码错不会来回试,避免把账号锁死。
- 成功的路由按「账号+通道」记在内存,同一进程内后续操作不再重复试探被封的代理。
- 回环地址(
127.x、localhost、*.local)永远直连,所以 Proton Bridge 与本地测试不会被代理劫持。
配置
cordis.patch.yml 里插件行支持的字段(都有默认值):
config:
dataDir: ~/.dsh/plugin-data/dsh-email # 账号文件目录
requestTimeoutMs: 20000 # 单次 IMAP/SMTP 操作超时
maxBodyBytes: 262144 # email_read 正文上限
maxAttachmentBytes: 8388608 # 附件读写上限
systemPrompt: true # 是否注入简短的邮件能力提示
apiPath: /plugins/dsh-email # 设置页 API 前缀
proxy: ''
proxyBypass: []
routeFallback: true
proxyConnectTimeoutMs: 8000
开发与自检
npm test # = selftest + client-smoke
node scripts/selftest.mjs # 29 项:协议/服务层,用环回 mock IMAP/SMTP/代理跑全链路
node scripts/client-smoke.mjs # 8 项:桩渲染设置页(空态/已登录/表单/报错/service getter 抛错)
node scripts/mock-mail-server.mjs # 只起 mock 服务器,手动把设置页指向它
node scripts/verify-accounts.mjs [proxy] # 本机诊断:打印每个账号的真实路由与耗时
selftest 不需要任何真实邮箱:mock 服务器实现了客户端用到的动词,并额外提供 HTTP CONNECT 代理、SOCKS5 代理和「接受后立刻断开」的坏代理,用来验证隧道与回退。另覆盖 RFC 2047/2231、GB18030、HTML→文本、线程头、dot-stuffing 等细节。
mock 账号:kali@example.com / test-pass(自定义服务器,关闭 TLS)。
改代码后怎么生效
- Host 半侧(
index.js、lib/*.js)由 DSH 进程import一次:改完需要重启 DSH(systemctl --user restart dsh-web.service或重新dsh web)。 - Client 半侧(
client.js)每次页面加载从磁盘读取:刷新浏览器即可。
两个已经踩过的坑(写 DSH 插件的人可以借鉴)
- Client 半侧必须
inject它读的每个服务。 Cordis 客户端上下文对「未声明就访问」的服务是抛错式 getter:只写inject: ['slots']却访问ctx.locale,渲染时会抛Error: cannot get property "locale" without inject,浏览器控制台显示slot entry crashed in 'settings.section',页面整块空白。本项目inject: ['slots', 'locale'],且所有 locale 读取过serviceOf()兜底。 - 主按钮颜色不能写死
#fff。 亮色主题的--dsw-alias-brand-primary是近黑,暗色主题是近白;写死白字在暗色下就是白底白字。用color: var(--dsw-alias-bg-base)才在两种主题下都有 ~17:1 的对比度。
文件
| 文件 | 作用 |
|---|---|
index.js | 插件入口:注册工具、系统提示段、设置页 API 路由。 |
lib/imap.js | IMAP4rev1 客户端(TLS / STARTTLS / LOGIN / LIST / SELECT / UID SEARCH / UID FETCH / NOOP),modified UTF-7。 |
lib/smtp.js | SMTP 提交客户端(465 隐式 TLS / 587 STARTTLS / AUTH PLAIN & LOGIN / dot-stuffing)。 |
lib/mime.js | MIME 编解码:头部、编码字、multipart、附件、HTML→文本、消息构建。 |
lib/proxy.js | 代理隧道:HTTP CONNECT / SOCKS5、直连判定、路由描述。 |
lib/providers.js | 服务商预设(端点 + 密码类型 + 提示 + 是否默认直连)。 |
lib/accounts.js | 账号注册表(JSON,0600)+ 凭据库读写。 |
lib/mailservice.js | 所有邮件操作(工具与设置页共用一份实现)。 |
lib/tools.js | 8 个 email_* 工具定义。 |
client.js | Web UI 设置页(React,slot settings.section)。 |
scripts/*.mjs | selftest / client-smoke / mock 服务器 / 账号诊断。 |
License
Related plugins
dsh-purge
kingcharleslzy-ai/dsh-purge
dsh-web (dsh-ssh)
zhu1090093659/dsh-web
dsh-web (dsh-remote-web-ui)
zhu1090093659/dsh-web
dsh-web-ui (dsh-ssh)
zhu1090093659/dsh-web-ui

