dsh-email 0.17.2 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 [历史英文记录](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 封正文窗口限制；信封命中时不下载正文或附件。
+- 新增 `headerScanLimit`（最多 20000）与 `headerScanOffset`，返回检索来源、扫描数量、覆盖状态及下一窗口，零命中不再被描述为完整邮箱无匹配。
+- 信封与服务端候选均核对接收日期；明确 UID 到达序与发件 Date 头排序不同，正文兜底仍保持原有小窗口。
+
 ## 0.17.2（2026-10-20）
 
 - 移动邮件前核对 IMAP 的 MOVE / UIDPLUS 能力；两者均不支持时明确拒绝，不再触发可能清除其他已标记删除邮件的全局 EXPUNGE（#23）。

package/README.en.md

@@ -4,19 +4,22 @@
 
 ![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.
 - Turn new-mail popups off in settings; the preference survives restarts.
 - Prepare and edit local drafts, review To/Cc, content and attachment bytes, then confirm sending.
@@ -34,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,19 +4,22 @@
 
 ![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 登录令牌加密和发信审批。
 - 新邮件弹窗可在设置中关闭，保存后重启仍生效。
 - 准备和编辑本地草稿，核对发件人、To/Cc、正文与附件预览后再确认发送。
@@ -34,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.
@@ -16,7 +18,7 @@ See the [draft workbench](DRAFTS.en.md) for editable drafts and per-account trus
 |---|---|
 | `email_list` | List the newest mail in a folder (unread filter, pagination, summaries only, no body) |
 | `email_read` | Read one message's full text by uid (HTML auto-converted to plain text, oversized bodies truncated) |
-| `email_search` | Search subject/sender/recipient/CC by keyword (server-side subject/from/to/cc; hits are re-checked against the envelopes, so "match-everything" servers such as QQ are rejected); when nothing believable is returned, it falls back to a body scan of the most recent 30 messages by default (including to/cc) |
+| `email_search` | Search subject/sender/recipient/CC by keyword, verify server candidates and fall back to a batched header scan (default 5000 messages). Returns coverage and an older-window cursor; optional body search remains limited to recent messages. |
 | `email_send` | Send mail on your behalf (attachments supported). **Prompts for confirmation before sending by default**, showing recipients, subject and attachment count; only sends after you approve |
 | `email_draft` | Prepare a local draft without sending; edit, save, inspect the preview and manually confirm in Settings → Email → Drafts |
 | `email_folders` | List the mailbox folders (INBOX/Sent/Junk/custom…); feed the `path` to other tools |
@@ -26,6 +28,16 @@ See the [draft workbench](DRAFTS.en.md) for editable drafts and per-account trus
 | `email_mark` | Mark messages as read/unread, add/remove stars, or move messages to another folder |
 | `email_reply` | Reply, reply-all or forward with thread headers and quoted content; uses the same send-approval gate |
 
+### Search coverage and older messages
+
+When server SEARCH returns no verified matches or fails, `email_search` checks local subject, From, To and Cc headers in batches of 500. The default window is the newest 5000 messages; `headerScanLimit` accepts 1–20000. Header matches do not download message bodies or attachments. This handles empty SEARCH responses without relying on the small body-search window, including mail pushed back by imported messages.
+
+Inspect `searchSource`, `serverMatchCount`, `serverSearchFailed`, `headerScan` and `bodyScan`. `headerScan` reports the mailbox size, headers actually scanned, matches in that window and whether the scan covered the folder. Continue with its `nextScanOffset` as `headerScanOffset`, keeping the same query, folder, date filters and window size. `offset` separately pages matching rows within a window; reset it to 0 when moving to another window. These are live mailbox windows, not a frozen snapshot: restart from offset 0 after arrivals or deletions if consistency matters.
+
+If headers do not match, the optional body fallback still scans only the recent `bodySearchLimit` window (default 30). Disabling `bodySearchFallback` disables body scans only; header fallback stays available. An explicit older header window skips body fallback. A zero-result page does not establish that the whole mailbox, especially all message bodies, has no match.
+
+Results follow descending mailbox UID (arrival order), not the sender's Date header or sorted INTERNALDATE. Imported old messages can appear first. `since`/`until` filter the server's received date (INTERNALDATE), falling back to the envelope Date only if unavailable.
+
 ### New-mail notifications (web UI)
 
 Once an account is configured, a "whale-girl courier" popup lives in the bottom-right corner of the main UI: it checks for new mail every 30 seconds and shows a card (sender + subject) when something arrives, auto-dismissing after 12 seconds. The popup shares the cursor logic with `email_watch` but keeps its own counter, so they never consume each other's mail.

package/docs/USAGE.md

@@ -4,6 +4,16 @@
 
 ## 本次改进
 
+新增「收发邮件」页，可直接浏览和搜索收件箱/已发送、读正文、下载附件、标记已读与星标，并把回复保存到草稿后核对发送。支持普通 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` 只关闭正文扫描；部分扫描或正文窗口零命中不能断言邮箱里不存在目标邮件。
+
+切换到下一信封窗口时保留查询词、文件夹、日期条件与窗口大小，并把匹配 `offset` 归零。窗口对应实时邮箱，不是冻结快照；期间新增或删除邮件后，需要严格一致结果时请从 `headerScanOffset:0` 重新开始。
+
+结果按 UID 到达序倒排，不按发件 Date 头或 INTERNALDATE 排序；批量导入的旧邮件可能排在前面。`since` / `until` 使用接收 INTERNALDATE 过滤，缺失时退到 Date 头。
+
 `email_mark(action:"move")` 要求服务器支持 MOVE 或 UIDPLUS；两者均无时会拒绝移动，保持源邮件不变，避免全局 EXPUNGE 误删其他已标记删除的邮件。请改用邮箱原生客户端或升级服务器。
 
 `email_send` 和 `email_draft` 的相对附件路径以当前会话工作区为基准，避免切换工作区后误读 DSH 启动目录的同名文件；绝对路径保持原样，没有会话上下文时仍使用启动目录。
@@ -18,7 +28,7 @@
 |---|---|
 | `email_list` | 列出文件夹里最新的邮件（未读过滤、分页、只看摘要不带正文） |
 | `email_read` | 按 uid 读取一封邮件的全文（HTML 邮件自动转纯文本，超长截断） |
-| `email_search` | 按关键词搜索主题/发件人/收件人/抄送（服务器端 subject/from/to/cc；命中会先用信封复核，QQ 这种"什么都匹配"的响应会被判无效）；复核或服务器都没给出可信结果时，默认回退到最近 30 封的正文扫描（含 to/cc） |
+| `email_search` | 按关键词搜索主题/发件人/收件人/抄送，复核服务端候选，无可信结果时分批扫描信封（默认 5000 封）；返回覆盖范围和更早窗口游标，可选正文兜底仍限于最近的小窗口 |
 | `email_send` | 代发邮件（支持带附件）。**默认发信前会弹确认**，显示收件人、主题和附件数，由你批准后才发出 |
 | `email_draft` | 准备本地草稿，不发送；用户在「设置 → 邮件 → 草稿」编辑、保存、检查预览后手动确认发送 |
 | `email_folders` | 列出邮箱的文件夹（INBOX/已发送/垃圾邮件/自定义…），拿 path 喂给其他工具 |

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;
+}