본문으로 건너뛰기
K

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.

설치

dsh plugin --profile web add github:kuanbandu/dsh-email

README

dsh-email — 让 DeepSeek Harness 收发你自己的邮箱

npm license 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

登录

  1. 打开 Web UI → 左下 设置。
  2. 左侧导航选 邮件(在 Plugins / Agent Presets 之后)。
  3. 点 添加邮箱账号 → 选服务商 → 填邮箱和密码/授权码 → 登录并保存。 保存前会真实登录一次 IMAP 和 SMTP,页面立刻显示两侧耗时与邮件夹数量;IMAP 通过而 SMTP 失败时仍会保存,并提示「可以收信、暂时不能发信」。
  4. 「高级」里 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 MailBridge 密码Proton 没有直连 IMAP:先装 Proton Mail Bridge,用 Bridge 给出的账号密码,地址默认 127.0.0.1:1143 / 1025,并在高级里勾「跳过 TLS 证书校验」(Bridge 自签名)。
Outlook / Microsoft 365应用密码(开了 2FA 时)IMAP 需在邮箱侧开启。
iCloudApp 专用密码appleid.apple.com → 登录与安全。
自建服务器登录密码高级里自己填 IMAP/SMTP 地址、端口、TLS 方式。

工具

工具用途
email_accountslist 列出账号(含密码是否就位、上次测试结果、路由);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 插件的人可以借鉴)

  1. 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() 兜底。
  2. 主按钮颜色不能写死 #fff。 亮色主题的 --dsw-alias-brand-primary 是近黑,暗色主题是近白;写死白字在暗色下就是白底白字。用 color: var(--dsw-alias-bg-base) 才在两种主题下都有 ~17:1 的对比度。

文件

文件作用
index.js插件入口:注册工具、系统提示段、设置页 API 路由。
lib/imap.jsIMAP4rev1 客户端(TLS / STARTTLS / LOGIN / LIST / SELECT / UID SEARCH / UID FETCH / NOOP),modified UTF-7。
lib/smtp.jsSMTP 提交客户端(465 隐式 TLS / 587 STARTTLS / AUTH PLAIN & LOGIN / dot-stuffing)。
lib/mime.jsMIME 编解码:头部、编码字、multipart、附件、HTML→文本、消息构建。
lib/proxy.js代理隧道:HTTP CONNECT / SOCKS5、直连判定、路由描述。
lib/providers.js服务商预设(端点 + 密码类型 + 提示 + 是否默认直连)。
lib/accounts.js账号注册表(JSON,0600)+ 凭据库读写。
lib/mailservice.js所有邮件操作(工具与设置页共用一份实现)。
lib/tools.js8 个 email_* 工具定义。
client.jsWeb UI 设置页(React,slot settings.section)。
scripts/*.mjsselftest / client-smoke / mock 服务器 / 账号诊断。

License

MIT

관련 플러그인