dsh-email 0.17.3 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.18.0（2026-10-21）
+
+- 实现 #24 的 AgentMail US / EU 邮箱地址 + API Key 账号，支持列表、服务端搜索、阅读、附件、状态、发送、回复和新邮件轮询；与 IMAP 数字 UID 分开处理 API 字符串 ID。
+- 新增中英文「收发邮件」工作台：切换账号/文件夹、收件箱/已发送、分页搜索、正文、附件下载与已读/星标；回复进入本地草稿，保留原线程，预览后明确确认发送。
+- 为 AgentMail 明确发送附件合计 4 MiB、下载 20 MiB 的插件上限；预览前拦截超限，回执只表示服务接受提交，不代表投递成功。沿用禁止收件人和不自动重发规则。
+- 在官方 DSH 0.2.1-rc.2 中完成真实浏览器操作与模拟 HTTP / IMAP 协议验收；未使用真实 AgentMail 账号，未验证真实远端投递。见[验收记录](docs/validation/0.18.0.md)。
+
 ## 0.17.3（2026-10-21）
 
 - 修复 #25 的搜索兜底窗口问题：服务端无可信命中或 SEARCH 失败时，先按每批 500 封扫描信封，默认最多 5000 封，不受最近 30 封正文窗口限制；信封命中时不下载正文或附件。

package/README.en.md

@@ -4,18 +4,20 @@
 
 ![dsh-email whale girl plugin cover](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/cover-whale-girl.png)
 
-Read, send, search and organize email from DSH with multiple accounts.
+Browse, send, search and organize email from DSH with IMAP/SMTP and AgentMail accounts.
 
 [![npm](https://img.shields.io/npm/v/dsh-email)](https://www.npmjs.com/package/dsh-email) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-email-downloads.svg)](https://www.npmjs.com/package/dsh-email)
 
 Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/dsh-email/issues) or submit [pull requests](https://github.com/STARDUSTLC666/dsh-email/pulls).
 
 
-See the [0.16.3 validation record](docs/validation/0.16.3.md) for DSH `0.2.1-alpha.5` browser checks and the remaining limits.
+See the [0.18.0 validation record](docs/validation/0.18.0.md) for browser and simulated mailbox protocol checks on official DSH `0.2.1-rc.2` and the remaining limits.
 
 ## What it does
 
 - Read, send, reply and forward using IMAP and SMTP.
+- Add AgentMail US/EU inboxes with an email address and API key, without IMAP/SMTP setup.
+- Browse Inbox/Sent, page/search messages, read plain text, download attachments and set read/star flags in Mailbox.
 - Manage attachments, search results and mailbox organization.
 - Scan headers in batches when server search is unreliable, report coverage and continue into older mail.
 - Configure multiple accounts, Outlook OAuth2, encrypted Windows login tokens and send approval.
@@ -35,13 +37,13 @@ For the web version, replace `desktop` with `web`. Restart DSH after installatio
 
 ## Start using it
 
-Add an account and test it in Settings → Email. Ask to list recent unread messages or prepare a reply; review recipients and content before sending.
+Add and test an account in Settings → Email, then open Mailbox. Ask to list unread messages or prepare a reply. Reply buttons create drafts for review before sending.
 
 To edit before sending, ask: “Prepare a message with email_draft; do not send yet.” Open Drafts to save edits, inspect attachments and confirm. See [drafts and recipient rules](docs/DRAFTS.en.md).
 
 ## Requirements and configuration
 
-Requires mail credentials, an app password or provider OAuth authorization. Mail authentication is separate from the DSH model API key.
+IMAP accounts require mail credentials, an app password or provider OAuth authorization. AgentMail requires its regional inbox address and API key; see [AgentMail setup](docs/AGENTMAIL.en.md). Mail authentication is separate from the DSH model API key.
 
 Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
 

package/README.md

@@ -4,18 +4,20 @@
 
 ![dsh-email 鲸鱼娘插件封面](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/cover-whale-girl.png)
 
-在 DSH 中收发、搜索和整理邮件，支持多个邮箱账号。
+在 DSH 中收发、搜索和整理邮件，支持普通邮箱与 AgentMail 多账号。
 
 [![npm](https://img.shields.io/npm/v/dsh-email)](https://www.npmjs.com/package/dsh-email) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-email-downloads.svg)](https://www.npmjs.com/package/dsh-email)
 
 欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-email/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-email/pulls)。
 
 
-DSH `0.2.1-alpha.5` 的本轮检查与未验收范围见 [0.16.3 验收记录](docs/validation/0.16.3.md)。
+本版在官方 DSH `0.2.1-rc.2` 中完成浏览器操作与模拟邮箱协议验收，范围见 [0.18.0 验收记录](docs/validation/0.18.0.md)。
 
 ## 功能
 
 - 通过 IMAP / SMTP 收发、回复和转发邮件。
+- 通过邮箱地址与 API Key 添加 AgentMail US / EU 账号，无需配置 IMAP / SMTP。
+- 在「收发邮件」页浏览收件箱与已发送，搜索、翻页、阅读正文、下载附件、标记已读和星标。
 - 管理附件、搜索结果与邮箱整理操作。
 - 搜索无可信服务端结果时，分批检查邮件信封，并说明覆盖范围；可继续查更早邮件。
 - 多账号设置，支持 Outlook OAuth2、Windows 登录令牌加密和发信审批。
@@ -35,13 +37,13 @@ dsh plugin --profile desktop add dsh-email
 
 ## 开始使用
 
-打开「设置 → 邮件」添加账号并测试连接。可说：“列出最近未读邮件，给这封邮件准备回复。”发送前核对收件人与内容。
+打开「设置 → 邮件」添加账号并测试连接，再到「收发邮件」浏览。可说：“列出最近未读邮件，给这封邮件准备回复。”页面上的回复会先存为草稿，核对后才发送。
 
 要先编辑再发送，可说：“用 email_draft 准备一封邮件，先别发送。”在「草稿」页保存编辑、检查附件并确认。详见[草稿与收件人规则](docs/DRAFTS.md)。
 
 ## 依赖与配置
 
-需要邮箱授权码、应用专用密码或对应 OAuth 授权。DSH 的模型 API Key 与邮箱登录是分别配置的。
+普通邮箱需要授权码、应用专用密码或对应 OAuth 授权；AgentMail 需要对应区域的邮箱与 API Key，见 [AgentMail 配置](docs/AGENTMAIL.md)。DSH 的模型 API Key 与邮箱登录分别配置。
 
 详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
 

package/docs/AGENTMAIL.en.md

@@ -0,0 +1,37 @@
+# AgentMail and the mailbox workbench
+
+[Overview](../README.en.md) · [中文](AGENTMAIL.md) · [Validation](validation/0.18.0.md)
+
+## Setup
+
+Create or select an inbox and obtain its regional API key in AgentMail. In Settings → Email → Accounts, select **AgentMail (US API)** or **AgentMail (EU API)**, enter the email address and API key, and run **Test connection**. The test reads the selected inbox without sending mail.
+
+US uses `https://api.agentmail.to`; EU uses `https://api.agentmail.eu`. Custom API endpoints are not accepted. Keys are stored in local account configuration, separately from model and IMAP credentials. A blank key in the card retains the saved key. Switching between an API and an IMAP provider clears the previous authentication data.
+
+```yaml
+bot:
+  provider: agentmail
+  user: assistant@agentmail.to
+  apiKey: YOUR_AGENTMAIL_API_KEY
+defaultAccount: bot
+```
+
+Single-account setup may use `DSH_AGENTMAIL_API_KEY`. Named accounts do not inherit that environment fallback. Existing IMAP/SMTP accounts retain numeric UIDs; AgentMail uses opaque string `message_id` values returned as `uid`. Pass them unchanged. AgentMail manages the sender display name on the inbox itself.
+
+## Read and send
+
+Mailbox provides account/folder selection, Inbox/Sent shortcuts, paging, search, plain-text reading, read/star flags, and attachment downloads. Views are INBOX, Sent, Starred, Archive and All. HTML/scripts are never executed as mail content. UI downloads go to the browser; `email_attachment` still returns a local file path to tools.
+
+Compose and reply buttons create local drafts. Save, inspect the preview, check recipients/content/attachments, then explicitly confirm. Reply drafts retain their account, subject and thread; create a new message to change account or subject. Cancelling review never submits. Submitted drafts never retry automatically. Tool sending retains existing approval rules, host permissions and recipient deny rules.
+
+## Limits
+
+- API search ranks by relevance and excludes spam, trash, blocked and unauthenticated mail. There is no IMAP header/body fallback. Use `offset`, not `headerScanOffset`. `count` is not the full mailbox size: inspect `hasMore` and `countExact`.
+- List/search is bounded at 201 API pages; narrow the query/date range when exceeded. Mailbox changes can affect paging.
+- Sending permits at most 10 files / 4 MiB of raw attachments, or a smaller configured limit; the full JSON request cap is 6 MB. Downloads are capped at 20 MiB per file or a smaller configured limit. Upload/review rejects oversized attachments before confirmation.
+- Archive maps only INBOX → Archive using labels, not arbitrary IMAP move/delete/EXPUNGE operations.
+- New-mail checks seed a silent baseline, drain backlogs without repeats and keep tool/browser cursors independent. Checks inspect at most 5000 arrivals. A missing baseline is an actionable error; verify the mailbox and reset notifications. `totalUnreadExact:false` reports a lower bound from the scanned window.
+- A receipt confirms submission, not final delivery. Check Sent before retrying an uncertain send.
+- This release has simulated HTTP/IMAP and real-host browser acceptance, as requested without a real AgentMail account. Regional access, quotas, actual delivery and remote attachment service remain unverified.
+
+References: official [inboxes](https://docs.agentmail.to/inboxes), [messages](https://docs.agentmail.to/messages), [search](https://docs.agentmail.to/api-reference/inboxes/messages/search), [reply](https://docs.agentmail.to/api-reference/inboxes/messages/reply), and [attachments](https://docs.agentmail.to/api-reference/inboxes/messages/get-attachment).

package/docs/AGENTMAIL.md

@@ -0,0 +1,41 @@
+# AgentMail 账号与收发邮件
+
+[简介](../README.md) · [English](AGENTMAIL.en.md) · [验收范围](validation/0.18.0.md)
+
+## 添加账号
+
+1. 在 AgentMail 控制台创建或选择邮箱，取得该区域的 API Key。
+2. 打开 DSH「设置 → 邮件 → 邮箱账号」，选择 `AgentMail (US API)` 或 `AgentMail (EU API)`，填写邮箱地址与 API Key。
+3. 点击「测试连接」。通过后在「收发邮件」选择账号，浏览 INBOX 与 Sent。测试只读取该邮箱，不发送邮件。
+
+US 固定使用 `https://api.agentmail.to`，EU 固定使用 `https://api.agentmail.eu`。不能自填代理 API 地址；区域与账号不匹配时请修正服务商选择。API Key 保存在本机账号配置中，与模型密钥、其他邮箱密码相互独立。账号卡片留空密钥表示保留已存值；切换普通邮箱与 API 服务商会清除旧认证信息，需要重新填写。
+
+也可在账号 YAML 中使用：
+
+```yaml
+bot:
+  provider: agentmail
+  user: assistant@agentmail.to
+  apiKey: YOUR_AGENTMAIL_API_KEY
+defaultAccount: bot
+```
+
+单账号的环境变量回退为 `DSH_AGENTMAIL_API_KEY`，命名多账号不共享此回退。普通 IMAP / SMTP 账号保留原配置与数字 UID；AgentMail 的 `uid` 是 API 返回的字符串 `message_id`，请原样传递，不要转成数字。发件显示名由 AgentMail 邮箱自身管理。
+
+## 浏览、回复与发送
+
+工作台提供 INBOX、Sent、Starred、Archive、All 视图，正文按纯文本显示，不执行邮件 HTML / 脚本。下载附件会保存到浏览器选择的位置；模型工具 `email_attachment` 仍返回本地文件路径。
+
+「写邮件」「回复到草稿」「回复全部到草稿」只创建本地草稿。保存编辑、检查发送预览、核对全部收件人与附件后，再点击「确认发送」。回复草稿固定原账号和主题以保留线程；需要改主题或发件账号时请新建邮件。取消预览不提交，已保存服务端回执的草稿不会再次发送。模型的发送工具仍遵守现有审批规则与宿主权限；禁止收件人始终生效。
+
+## 已知边界
+
+- AgentMail 搜索由 API 按相关性返回，不执行 IMAP 本地信封/正文兜底；API 搜索排除垃圾、回收站、被阻止及未认证邮件。使用 `offset` 翻页，不使用 `headerScanOffset`。页数和 `count` 不能当成整个邮箱总量，查看 `hasMore` / `countExact`。
+- 列表与搜索最多扫描 201 个 API 页；过大范围会明确报错，请缩小日期/查询。实时邮箱变化可能改变分页内容。
+- 本插件发送最多 10 个附件，原始附件合计不超过 4 MiB，且受更小的用户上限约束；完整 API JSON 请求上限 6 MB。下载单附件最多 20 MiB，且不超过用户配置。超限应在上传或预览时处理。
+- API 归档仅支持 `INBOX → Archive`，通过标签实现；不映射任意 IMAP 移动、删除或 EXPUNGE。
+- 提醒第一次调用只建立基线；积压按批报告，独立工具/网页游标互不抢占。一次最多向前检查 5000 封；基线丢失会明确报错，需核对邮箱并重新启用提醒。`totalUnreadExact:false` 只表示扫描范围内的未读数下界。
+- 超时或丢失回执不自动重发，请先在 Sent 核对。接受提交与收件方投递成功不同。
+- 本版按用户确认完成实现与模拟验收，尚无真实 AgentMail 账号；实际区域权限、额度、投递与远端附件服务仍需真实账号验收。
+
+实现对照 AgentMail 官方[收件箱](https://docs.agentmail.to/inboxes)、[消息](https://docs.agentmail.to/messages)、[搜索](https://docs.agentmail.to/api-reference/inboxes/messages/search)、[回复](https://docs.agentmail.to/api-reference/inboxes/messages/reply)和[附件](https://docs.agentmail.to/api-reference/inboxes/messages/get-attachment)文档。

package/docs/USAGE.en.md

@@ -4,6 +4,8 @@
 
 ## Current improvements
 
+Mailbox now provides Inbox/Sent browsing, paging/search, plain-text reading, attachment downloads, read/star flags and replies saved to drafts for review. Both IMAP/SMTP and AgentMail US/EU accounts are supported. See [AgentMail setup and limits](AGENTMAIL.en.md) for opaque message IDs, API relevance search, attachment caps and simulated acceptance. The header fallback and numeric UID descriptions below apply to IMAP.
+
 Relative attachment paths in `email_send` and `email_draft` resolve against the current session workspace, avoiding a same-name file in the DSH startup directory after switching workspaces. Absolute paths remain exact; calls without session context retain startup-directory fallback.
 
 Set blocked addresses and domains per account in the Recipient Rules tab; the text configuration fields are `denyAddresses` / `denyDomains`. Rules cover To and Cc and remain active with send approval off. Domains match exactly, excluding subdomains unless listed. Remove blocked recipients and preview again before sending. Trust skips `email_send` plugin confirmation only when every To/Cc address matches and skipping has been explicitly enabled; host permissions still apply.

package/docs/USAGE.md

@@ -4,6 +4,8 @@
 
 ## 本次改进
 
+新增「收发邮件」页，可直接浏览和搜索收件箱/已发送、读正文、下载附件、标记已读与星标，并把回复保存到草稿后核对发送。支持普通 IMAP / SMTP 与 AgentMail US / EU 多账号；[AgentMail 配置与边界](AGENTMAIL.md)单独说明 API 字符串 UID、相关性搜索、附件上限与模拟验收范围。下文的信封扫描与数字 UID 说明适用于 IMAP。
+
 `email_search` 先复核服务端候选；QQ 等服务器返回空集、报错或无可信命中时，分批扫描信封（From / To / Cc / Subject），默认最近 5000 封、每批 500 封，不下载正文或附件。可用 `headerScanLimit` 调整到 1–20000；按 `headerScan.nextScanOffset` 设置 `headerScanOffset` 继续查更早的信封。`offset` 仍是当前结果窗口内跳过的匹配数，两种 offset 不同。
 
 返回 `searchSource`、`serverMatchCount`、`serverSearchFailed`、`headerScan`（实际扫描数、文件夹总数、命中数、是否完整、下一窗口）和可选 `bodyScan`。信封无匹配且从最新窗口开始时，才按 `bodySearchFallback` / `bodySearchLimit` 检查最近正文。`bodySearchFallback:false` 只关闭正文扫描；部分扫描或正文窗口零命中不能断言邮箱里不存在目标邮件。

package/docs/VALIDATION.md

@@ -1,5 +1,7 @@
 # dsh-email 验证记录
 
+[0.18.0 AgentMail 与收发邮件工作台验收](validation/0.18.0.md)。
+
 [0.17.1 发信策略与设置保存验收](validation/0.17.1.md)。
 
 [0.16.3 · DSH 0.2.1-alpha.5 浏览器操作验收](validation/0.16.3.md)。

package/docs/validation/0.18.0.md

@@ -0,0 +1,23 @@
+# 0.18.0 · AgentMail 与收发邮件工作台
+
+日期：2026-10-21。Windows，官方 npm DSH **0.2.1-rc.2**；隔离 profile、合成邮箱和凭据，不使用用户真实邮箱或模型密钥。
+
+## 已验证
+
+- Windows / Node 24.16.0 下 **372 项测试通过，无失败、无跳过**。构建产物与源码同步，手写网页端 JavaScript 语法检查通过。
+
+- 自动回归覆盖固定区域 API 与账号隔离、HTTP 错误脱敏、数字/字符串 UID、分页/相关性搜索、未读标签、取消不消耗提醒积压、直接跟随 API 游标、新邮件基线、附件大小/公网 HTTPS 限制、跨源请求拒绝、回复草稿持久化、禁止收件人和手动确认。
+- 官方 DSH 宿主内安装同一生产应用装配，用依赖注入把 AgentMail 网络请求送到本机真实 HTTP 协议端点；普通邮箱连接本机真实 IMAP 协议端点。没有用前端假数据替代邮箱路由。
+- 后台 Chrome 实际点击：收件箱、已发送、翻页、搜索、纯文本正文、已读/星标、附件下载、回复进入草稿、编辑保存、预览取消、核对确认发送。取消前后 HTTP POST 发送次数均为 0；确认后为 1，调用原 `message_id` 的 `/reply`，保留线程。
+- IMAP 账号通过生产 EmailService / EmailPool 列表及正文读取；API/IMAP 切换不会串入迟到的其他账号结果。合成 503 错误、空文件夹与恢复操作可见。
+- IMAP 回复草稿记录 UIDVALIDITY；提交前重新核对并提取 Message-ID/References。自动回归确认原线程头与已审核正文保留，邮箱重新编号时不提交 SMTP。
+- 中英文、1440px 与 390px、浅色与深色检查；390px 设置弹窗 scrollWidth/clientWidth 均为 390，没有横向溢出。页面脚本无未捕获异常，邮件中的 `<script>` 按文字显示。
+- 模拟附件 `quote.txt` 下载内容为 `quote`；真实公网 DNS/HTTPS 防护另有自动回归。
+
+## 未验证与限制
+
+- 无真实 AgentMail 账号/API Key，未验证真实服务权限、套餐、投递、远端签名附件或实际收件；模拟回执不能证明真实投递。
+- 本轮是官方 Web 宿主的浏览器操作验收，不宣称完成原生桌面窗口、系统文件对话框或 18 个插件逐项验收。
+- 没有重新登录用户真实普通邮箱，也没有向任何真实收件人发信。生产网络出口、代理/VPN 与邮件服务差异需要相应环境复核。
+
+临时协议服务、合成邮箱、测试下载、隔离进程与 profile 在验收和发布检查后清理；源码回归用例保留。

package/lib/agentmail.d.ts

@@ -0,0 +1,33 @@
+import { downloadPublicBytes } from './public-download.js';
+import type { ResolvedEmailSettings } from './config.js';
+import type { EmailListResult, EmailReadResult, EmailSearchResult, EmailSendResult, EmailMarkAction, EmailMarkResult, EmailAttachmentResult, EmailWatchResult } from './types.js';
+export type MessageRef = number | string;
+/** API transport. Endpoint hosts are fixed; redirects never carry credentials elsewhere. */
+export declare class AgentMailClient {
+    private settings;
+    private fetcher;
+    private downloader;
+    private watches;
+    constructor(settings: ResolvedEmailSettings, fetcher?: typeof fetch, downloader?: typeof downloadPublicBytes);
+    private account;
+    private request;
+    test(name: string, signal?: AbortSignal): Promise<any>;
+    private folderLabel;
+    list(name: string, folder: string, limit: number, offset: number, unread: boolean, since?: Date, until?: Date, signal?: AbortSignal, query?: string): Promise<EmailListResult>;
+    search(name: string, query: string, folder: string, limit: number, offset: number, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailSearchResult>;
+    private id;
+    private original;
+    read(name: string, uid: MessageRef, folder: string, signal?: AbortSignal): Promise<EmailReadResult>;
+    mark(name: string, folder: string, uid: MessageRef, action: EmailMarkAction, target?: string, signal?: AbortSignal): Promise<EmailMarkResult>;
+    send(name: string, to: string, subject: string, text: string, cc: string, attachments: Array<{
+        filename: string;
+        content: Buffer;
+    }>, signal?: AbortSignal, reply?: {
+        uid: MessageRef;
+        folder: string;
+    }): Promise<EmailSendResult>;
+    downloadAttachment(name: string, folder: string, uid: MessageRef, index: number, workspace?: string, signal?: AbortSignal): Promise<EmailAttachmentResult>;
+    sendPaths(name: string, to: string, subject: string, text: string, cc: string, paths: string[], signal?: AbortSignal): Promise<EmailSendResult>;
+    watch(name: string, folder: string, limit: number, scope: string, signal?: AbortSignal): Promise<EmailWatchResult>;
+    clear(): void;
+}