dsh-email 0.11.0 → 0.12.0

package/README.en.md

@@ -37,6 +37,7 @@ Example:
 
 ### Changelog
 
+- **0.12.0 (2026-09-18)**: **send-as alias** (`senderName` / `authUser` / `authPassword`): `user` is now only the From address and the mailbox identity, while the login user and password can differ — Gmail / Workspace aliases and SMTP relays where the login is not the From address no longer fail with `535 Username and Password not accepted`, and the From header can carry a display name. The account card gained three fields (same three-state contract as the authorization code: empty keeps the stored value, clearing deletes the key). **New**: `offset` for `email_search`, so results beyond the first page are reachable. **Fixes and optimisations**: a changed folder UIDVALIDITY re-seeds the `email_watch` / popup baseline instead of reporting the renumbered mailbox as new; search verification and the result rows share one FETCH; `email_attachment` reuses the MIME index `email_read` already parsed instead of downloading the whole message again; `email_folders` is cached for 60s; the web new-mail popup pauses while the tab is hidden, backs off on failures and refreshes its skin snapshot less often. **Engineering**: CI now rejects `lib/` drift against `src/` and syntax-checks the hand-written client bundle. Tests 237 → 252. The send-as direction came from [@TianLanDaoRen](https://github.com/TianLanDaoRen)'s [PR #8](https://github.com/STARDUSTLC666/dsh-email/pull/8) (this implementation is a rewrite on top of 0.11.0).
 - **0.11.0 (2026-09-18)**: merge gurio-wine's four settings-page PRs ([#11](https://github.com/STARDUSTLC666/dsh-email/pull/11)–[#14](https://github.com/STARDUSTLC666/dsh-email/pull/14)) with post-review fixes. **Added**: ① visual multi-account card editor (add/edit/delete, rename, set-default, per-account connection test — edits auto-save; no "Save & Apply" button) and server-preset management (`serverPresets`, custom provider endpoints, no credentials); ② OAuth2 device-code login for Outlook / Exchange Online (IMAP and SMTP share one token; automatic refresh; password-auth accounts unaffected); ③ bilingual settings-panel copy that follows the host's Settings → General language in real time; ④ accounts can pin `authKind` (auto / oauth2 / password), giving hybrid or on-premises tenants that still accept app passwords an escape hatch. **Review fixes**: SMTP OAuth2 could never send (nodemailer's `XOAuth2` reads only `accessToken`, never `pass` — confirmed `EAUTH`); saving no longer unconditionally wipes account-level hand-written imap/smtp endpoints (runtime prefers the account's own host; the old behavior silently re-pointed custom-server accounts to presets, and accounts without a provider lost connection info entirely); rename preserves stored auth codes and advanced keys and refuses to overwrite an existing account name; settings routes now enforce Host / Origin / Content-Type same-origin checks (previously any web page could cross-origin-write settings; DNS rebinding could read snapshots containing plaintext auth codes); responses no longer echo the resolved account map (a plaintext-password copy the front end never reads); raw server errors are credential-scrubbed before display (IMAP/SMTP echo rejected auth strings containing access tokens); deleting an account cleans its tokens (uncommitted saves do not); version conflicts auto-rebase instead of retrying with a stale revision. **No third-party OAuth2 app registration is bundled**: OAuth2 accounts must supply their own `clientId` — see "Outlook OAuth2" below. Tests: 81 → 237. **`email_search` fix**: servers like QQ answer any keyword with the same unrelated uid list; hits are now re-verified against the envelopes (subject/from/to/cc) and fall back to the local body scan when none survive, so an impossible keyword no longer "matches" 40 messages ([#15](https://github.com/STARDUSTLC666/dsh-email/issues/15)).
 - **0.10.8 (2026-09-16)**: integrate GUODnuli's [PR #9](https://github.com/STARDUSTLC666/dsh-email/pull/9), replacing nonexistent text and border variables in settings and notifications with official theme tokens; revalidate Harness 0.1.5-rc.2 and 0.1.6-alpha.1.
 - **0.10.7 (2026-09-11)**: revalidate official Harness 0.1.5-rc.1 and refresh suite co-load and live-service evidence; runtime code is unchanged.
@@ -161,6 +162,9 @@ The settings page's "Server presets" fold-out edits these presets visually, and
 | `provider` | — | Preset name; auto-fills imap/smtp addresses. Explicitly written host/port/secure take precedence |
 | `user` | required | Login email address |
 | `password` | required* | Authorization code / app-specific password; *can also use the env var `DSH_EMAIL_PASSWORD` |
+| `senderName` | — | Display name for the From header; the address itself stays `user` |
+| `authUser` | = `user` | Login account. Alias / SMTP-relay setups: `user` is the address mail is sent from, this is the account IMAP/SMTP authenticates with |
+| `authPassword` | = `password` | Password for `authUser`; only needed when the login account differs from `user` and has its own password |
 | `imap.host/port/secure` | per preset | Incoming server (also `connectionTimeoutMs` / `socketTimeoutMs` for timeouts) |
 | `smtp.host/port/secure` | per preset | Outgoing server |
 | `inboxFolder` | `INBOX` | Default folder for read/send tools |
@@ -222,6 +226,7 @@ Microsoft has disabled username+password basic auth for Exchange Online: persona
 ## Known limitations
 
 - **OAuth2 covers Outlook / Exchange Online only, and requires your own app ID**: device-code login supports both IMAP and SMTP, but the plugin **bundles no third-party app registration** — OAuth2 accounts must supply their own `clientId` (free to register; see "Outlook OAuth2" above). Other environments that mandate OAuth (e.g. Google Workspace) remain unusable; use the provider's app-specific password / authorization code instead.
+- **Search match counts**: server hits are re-checked against the envelopes (see `email_search` above); when they hold up, "N matches" is the count the server reported while every listed row really carries the keyword.
 - **Body search**: the server side only searches subject / from / to / cc. Most servers (e.g. QQ) have unreliable IMAP `TEXT` / `HEADER` search, so with no results it falls back to a body scan of the most recent `bodySearchLimit` messages (slower; disable with `bodySearchFallback`).
 - **Attachments**: inline images aren't downloadable separately yet; a failed attachment match errors instead of downloading the wrong file (safe default).
 - **Password storage**: the authorization code saved in the settings page is written in plaintext to the local `settings.yaml` (the secret mark only keeps it out of logs / exports / diagnostics; no disk encryption). Don't hand `settings.yaml` to untrusted people.

package/README.md

@@ -45,6 +45,7 @@ IMAP/SMTP email tools for DeepSeek Harness, with replies, forwarding, mailbox or
 
 ### 版本记录
 
+- **0.12.0（2026-09-18）**：**新增发送别名**（`senderName` / `authUser` / `authPassword`）：`user` 只作为发件地址与信箱身份，登录名与登录密码可以另填——Gmail / Workspace 的别名发信、以及「登录账号 ≠ From 地址」的 SMTP 中继不再被 `535 Username and Password not accepted` 拒绝，From 也能带显示名。设置页账号卡片新增「发件显示名 / 登录账号 / 登录账号的密码」三栏（与授权码同一套三态：留空保留已存值、清空即删除）。**新增** `email_search` 的 `offset`，命中多于一页时可翻页。**修复与优化**：文件夹 UIDVALIDITY 变化时重建 `email_watch` / 弹窗的增量基线（不再把重编号后的整箱当成新邮件）；搜索的命中复核与结果列表合并为一次 FETCH；`email_attachment` 复用 `email_read` 已解析的 MIME 索引，不再把整封邮件（含附件）重下一遍；`email_folders` 结果缓存 60 秒；网页端新邮件弹窗在标签页不可见时暂停轮询、失败指数退避、皮肤快照降频。**工程**：CI 增加「`lib/` 与 `src/` 不允许漂移」和客户端 bundle 语法检查。测试 237 → 252 项。发送别名的方向来自 [@TianLanDaoRen](https://github.com/TianLanDaoRen) 的 [PR #8](https://github.com/STARDUSTLC666/dsh-email/pull/8)（本实现按 0.11.0 之后的代码重写）。
 - **0.11.0（2026-09-18）**：合入 gurio-wine 的设置页四连（[PR #11](https://github.com/STARDUSTLC666/dsh-email/pull/11)–[#14](https://github.com/STARDUSTLC666/dsh-email/pull/14)），并在评审后修掉其中若干问题。**新增**：①多账号卡片编辑器（增删改 / 改名 / 设默认 / 按账号单独测试连接，编辑即保存，不再需要点「保存并应用」）与服务器预设管理（`serverPresets`，自定义服务商端点，不含凭证）；②Outlook / Exchange Online 的 OAuth2 设备码登录（IMAP 与 SMTP 双端，access token 自动刷新，密码认证账号完全不受影响）；③设置面板文案中英双语，跟随宿主 Settings → General 的语言实时切换；④账号可显式钉住 `authKind`（自动 / oauth2 / password），给仍能用应用密码连 Exchange Online 的混合或本地租户留退路。**评审修复**：SMTP 的 OAuth2 认证形状原本一封也发不出去（nodemailer 的 `XOAuth2` 只读 `accessToken`、从不读 `pass`，实测报 `EAUTH`）；保存面板不再无条件抹掉账号手写的 imap/smtp 端点（运行时解析以账号自己的值优先，原行为会把自建服务器账号静默改指预设，无 provider 的账号则直接失去连接信息）；改名保留授权码与高级键，且不允许顶掉同名账号；设置路由增加 Host / Origin / Content-Type 同源校验（此前任意网页都能跨源改设置，DNS rebinding 还能读走含明文授权码的快照）；响应不再回显解析后的账号映射（那是一份含明文密码、前端从不读取的副本）；服务器原始报错经凭据脱敏后才展示（IMAP/SMTP 会回显被拒的认证串，其中含 access token）；删除账号即清理其 token，未提交的保存不清；版本冲突自动重基，而不是拿旧 revision 反复重试。**不内置任何第三方 OAuth2 应用注册**：OAuth2 账号需自带 `clientId`，见下文「Outlook OAuth2」。测试 81 → 237 项。**修复 `email_search`**：QQ 这类服务器会对任意关键词返回同一批无关 UID，现在服务器命中会先用 envelope 复核（subject/from/to/cc），核实不到就回退本地正文扫描，不会再出现「不存在的关键词也匹配 40 条」（[#15](https://github.com/STARDUSTLC666/dsh-email/issues/15)）。
 - **0.10.8（2026-09-16）**：合入 GUODnuli 的 [PR #9](https://github.com/STARDUSTLC666/dsh-email/pull/9)，将设置页及新邮件弹窗的文字、边框引用改为官方主题变量，修复深色主题文字不可读；复验官方 Harness 0.1.5-rc.2 和 0.1.6-alpha.1。
 - **0.10.7（2026-09-11）**：复验官方 Harness 0.1.5-rc.1，更新整套同载与真实服务验证记录；运行时代码未变。
@@ -172,6 +173,9 @@ dsh plugin --profile web remove dsh-email
 | `provider` | 无 | 预设名，自动填 imap/smtp 地址；显式写的 host/port/secure 优先 |
 | `user` | 必填 | 登录邮箱地址 |
 | `password` | 必填* | 授权码/应用专用密码；*也可用环境变量 `DSH_EMAIL_PASSWORD` |
+| `senderName` | 无 | 发件显示名：只改收件人看到的名称，发件地址仍是 `user` |
+| `authUser` | = `user` | 登录账号。别名 / SMTP 中继场景：`user` 是发件地址，这里填真正用于 IMAP/SMTP 认证的账号 |
+| `authPassword` | = `password` | `authUser` 对应的密码；只有登录账号与 `user` 不同、且密码也不一样时才需要 |
 | `imap.host/port/secure` | 按预设 | 收信服务器（另有 connectionTimeoutMs/socketTimeoutMs 可调超时） |
 | `smtp.host/port/secure` | 按预设 | 发信服务器 |
 | `inboxFolder` | `INBOX` | 收发工具默认使用的文件夹 |
@@ -233,6 +237,7 @@ dsh plugin --profile web remove dsh-email
 ## 已知限制
 
 - **OAuth2 仅覆盖 Outlook / Exchange Online，且需自带应用 ID**：设备码登录已支持 IMAP 与 SMTP 双端，但插件**不内置任何第三方应用注册**，OAuth2 账号必须填自己的 `clientId`（免费注册，见上文「Outlook OAuth2」）。Google Workspace 等其它强制 OAuth 的环境仍不可用，只能用服务商的应用专用密码 / 授权码。
+- **搜索的匹配数**：服务器命中会先用信封复核（见上文 `email_search`）；复核通过时「共 N 条匹配」沿用服务器给出的条数，而列出的每一行都保证真的带关键词。
 - **正文搜索**：服务器端只搜 subject / from / to / cc；多数服务器（如 QQ）的 IMAP `TEXT` / `HEADER` 搜索不可靠，无结果时回退到最近 `bodySearchLimit` 封的正文扫描（较慢，可用 `bodySearchFallback` 关闭）。
 - **附件**：内嵌图片暂不支持单独下载；附件定位失败会直接报错而不是下载错误文件（安全默认）。
 - **密码落盘**：设置页保存的授权码以明文写在本机 `settings.yaml`（secret 标记只保证它不进日志 / 导出 / 诊断，不做磁盘加密）。请勿把 `settings.yaml` 交给不信任的人。

package/lib/client.js

@@ -1,3 +1,6 @@
+// NOTE（维护者请看这里）：这个文件就是插件网页端的**源码**，不经过 tsc —— 仓库里没有
+// src/client.ts，`pnpm run build` 也不会重写它。改设置面板 / 鲸鱼娘弹窗请直接改这里，
+// 改完用 `node --check lib/client.js` 自检（CI 里也会跑这一步）。
 window.__ModuleLoader__.load({ id: "dsh-email", factory: (require) => {
 var module = { exports: {} }; var exports = module.exports;
 "use strict";
@@ -311,6 +314,15 @@ var UI = {
     "card.passwordPlaceholder": "留空保持不变",
     "card.passwordSaved": "已存有授权码：留空保持不变，清空后填内容即覆盖。",
     "card.passwordHint": "留空即不写入 password 键。",
+  "card.senderNameLabel": "发件显示名（可选）",
+  "card.senderNamePlaceholder": "只影响收件人看到的名称",
+  "card.senderNameHint": "只改收件人看到的显示名，发件地址仍是上面的邮箱地址。",
+  "card.authUserLabel": "登录账号（与邮箱地址不同时填）",
+  "card.authUserPlaceholder": "留空 = 用上面的邮箱地址登录",
+  "card.authUserHint": "别名或中继场景：上面填信件发出的地址，这里填真正用于 IMAP/SMTP 登录的账号。留空即与邮箱地址相同。",
+  "card.authPasswordLabel": "登录账号的密码（可选）",
+  "card.authPasswordSaved": "已存有登录密码：留空保持不变，清空后填内容即覆盖。",
+  "card.authPasswordHint": "留空即沿用上面那栏的授权码 / 应用专用密码；只有登录账号与邮箱地址不同、且密码也不一样时才需要单独填。",
     "card.inboxLabel": "收件文件夹（默认 INBOX）",
     "card.autoSaveHint": "改动会自动保存。",
     "card.autoSaveHintNoDefault": " 现在有多个账号但没有默认账号，必须先指定一个。",
@@ -480,6 +492,15 @@ var UI = {
     "card.passwordPlaceholder": "Leave empty to keep it",
     "card.passwordSaved": "A password is already stored: leave empty to keep it, or clear the field and type to overwrite.",
     "card.passwordHint": "Leave it empty and the password key is not written.",
+  "card.senderNameLabel": "Sender display name (optional)",
+  "card.senderNamePlaceholder": "Only the name recipients see",
+  "card.senderNameHint": "Changes only the name recipients see; the address stays the one above.",
+  "card.authUserLabel": "Login user (when it differs from the address)",
+  "card.authUserPlaceholder": "Empty = log in with the address above",
+  "card.authUserHint": "Alias or relay: the address above is what mail is sent from, this is the account IMAP/SMTP authenticates. Empty means they are the same.",
+  "card.authPasswordLabel": "Password for the login user (optional)",
+  "card.authPasswordSaved": "A login password is stored: leave it empty to keep it, or type to replace it.",
+  "card.authPasswordHint": "Leave empty to reuse the authorization code / app password above; only needed when the login user has a password of its own.",
     "card.inboxLabel": "Inbox folder (default INBOX)",
     "card.autoSaveHint": "Changes save automatically.",
     "card.autoSaveHintNoDefault": " There are several accounts but no default account yet; you must pick one first.",
@@ -737,6 +758,11 @@ function draftFromCard(card) {
     provider: card.provider === undefined || card.provider === null ? "" : String(card.provider),
     user: card.user === undefined || card.user === null ? "" : String(card.user),
     password: "",
+    // 登录密码与 password 同一套三态契约：卡片永远拿不到明文，只有"是否已存"。
+    authPassword: "",
+    hasAuthPassword: card.hasAuthPassword === true,
+    senderName: card.senderName === undefined || card.senderName === null ? "" : String(card.senderName),
+    authUser: card.authUser === undefined || card.authUser === null ? "" : String(card.authUser),
     clientId: card.clientId === undefined || card.clientId === null ? "" : String(card.clientId),
     // authKind 是生效裁决（决定显示登录区还是密码框），authKindSetting 是用户钉住
     // 了什么（'' = 自动）。两者必须分开：都从裁决读的话，「自动」与「显式密码」在
@@ -834,6 +860,10 @@ function draftToInput(draft) {
   };
   if (draft.provider) input.provider = draft.provider;
   if (!isOauthDraft(draft) && draft.password) input.password = draft.password;
+  // 显示名/登录名是普通三态字段（留空 = 清掉该键），密码与 password 同规：只有真打了字才写。
+  if (draft.senderName !== undefined) input.senderName = String(draft.senderName || "").trim();
+  if (!isOauthDraft(draft) && draft.authUser !== undefined) input.authUser = String(draft.authUser || "").trim();
+  if (!isOauthDraft(draft) && draft.authPassword) input.authPassword = draft.authPassword;
   // Only an OAuth2 card models the application id; for any other account the
   // field stays undefined, which the backend reads as「没说」and leaves the
   // stored key alone. An empty string here is the user clearing it on purpose.
@@ -1699,6 +1729,11 @@ function AccountCardsEditor(props) {
                   h("label", null, t("card.addressLabel")),
                   fieldInput("text", draft.user, (v) => patchDraft(name, { user: v }), "you@example.com"),
                 ]),
+                h("div", { className: "dshe-field" }, [
+                  h("label", null, t("card.senderNameLabel")),
+                  fieldInput("text", draft.senderName, (v) => patchDraft(name, { senderName: v }), t("card.senderNamePlaceholder")),
+                  h("div", { className: "dshe-hint" }, t("card.senderNameHint")),
+                ]),
                 // 认证方式只在「可能是 OAuth2」的账号上出现：给 QQ/163 用户多一个
                 // 下拉框只是噪音。它是那条逃生舱的唯一面板入口——仍能用应用密码连
                 // Exchange Online 的租户（混合/本地部署、SMTP AUTH 未关）靠它才不用
@@ -1738,19 +1773,41 @@ function AccountCardsEditor(props) {
                       onCancel: () => cancelOauth(name),
                       onClientId: (v) => patchDraft(name, { clientId: v }),
                     })
-                  : h("div", { className: "dshe-field" }, [
-                      h("label", null, t("card.passwordLabel")),
-                      h("input", {
-                        type: "password",
-                        value: draft.password,
-                        disabled: busy !== "",
-                        placeholder: t("card.passwordPlaceholder"),
-                        onChange: (e) => patchDraft(name, { password: e.target.value }),
-                      }),
-                      h("div", { className: "dshe-hint" },
-                        view.hasPassword
-                          ? t("card.passwordSaved")
-                          : t("card.passwordHint")),
+                  : h(React.Fragment, null, [
+                      h("div", { className: "dshe-field" }, [
+                        h("label", null, t("card.passwordLabel")),
+                        h("input", {
+                          type: "password",
+                          value: draft.password,
+                          disabled: busy !== "",
+                          placeholder: t("card.passwordPlaceholder"),
+                          onChange: (e) => patchDraft(name, { password: e.target.value }),
+                        }),
+                        h("div", { className: "dshe-hint" },
+                          view.hasPassword
+                            ? t("card.passwordSaved")
+                            : t("card.passwordHint")),
+                      ]),
+                      // 别名/中继：登录名与登录密码都只在密码类账号上有意义（OAuth2 用 token 登录）。
+                      h("div", { className: "dshe-field" }, [
+                        h("label", null, t("card.authUserLabel")),
+                        fieldInput("text", draft.authUser, (v) => patchDraft(name, { authUser: v }), t("card.authUserPlaceholder")),
+                        h("div", { className: "dshe-hint" }, t("card.authUserHint")),
+                      ]),
+                      h("div", { className: "dshe-field" }, [
+                        h("label", null, t("card.authPasswordLabel")),
+                        h("input", {
+                          type: "password",
+                          value: draft.authPassword,
+                          disabled: busy !== "",
+                          placeholder: t("card.passwordPlaceholder"),
+                          onChange: (e) => patchDraft(name, { authPassword: e.target.value }),
+                        }),
+                        h("div", { className: "dshe-hint" },
+                          view.hasAuthPassword
+                            ? t("card.authPasswordSaved")
+                            : t("card.authPasswordHint")),
+                      ]),
                     ]),
                 h("div", { className: "dshe-field" }, [
                   h("label", null, t("card.inboxLabel")),
@@ -2428,27 +2485,57 @@ function startWhaleWidget() {
     hideTimer = setTimeout(closePopup, 12000);
   };
 
+  // 轮询策略：页面不可见时完全不打扰邮箱服务器；失败指数退避（上限 10 分钟），
+  // 成功立刻回到 30s；快照（皮肤 / 账号列表）变化很慢，最多 10 分钟刷新一次。
+  const POLL_MS = 30000;
+  const SNAPSHOT_MS = 600000;
+  const MAX_BACKOFF_MS = 600000;
+  let failures = 0;
+  let lastSnapshot = 0;
+  let hasAccounts = true;
+
   const tick = async () => {
+    if (document.hidden) return;
     try {
-      const snap = await api();
-      if (snap && snap.whale) {
-        whaleUrl = snap.whale.url || "";
-        whaleCredit = snap.whale.credit || "";
+      if (!hasAccounts || Date.now() - lastSnapshot > SNAPSHOT_MS) {
+        const snap = await api();
+        lastSnapshot = Date.now();
+        if (snap && snap.whale) {
+          whaleUrl = snap.whale.url || "";
+          whaleCredit = snap.whale.credit || "";
+        }
+        hasAccounts = !!(snap && snap.accounts && snap.accounts.length > 0);
       }
-      if (!snap || !snap.accounts || snap.accounts.length === 0) return;
+      if (!hasAccounts) return;
       const value = await api("watch", { limit: 5 });
       if (value && value.newCount > 0) showPopup(value);
+      failures = 0;
     } catch (e) {
-      // Not configured or transient error: stay silent, retry next tick.
+      // Not configured or transient error: stay silent and back off.
+      failures = Math.min(failures + 1, 8);
     }
   };
 
-  tick();
-  pollTimer = setInterval(tick, 30000);
+  const schedule = () => {
+    clearTimeout(pollTimer);
+    if (document.hidden) return; // 回到前台时 onVisibility 会立刻补一次
+    const delay = failures === 0 ? POLL_MS : Math.min(POLL_MS * Math.pow(2, failures - 1), MAX_BACKOFF_MS);
+    pollTimer = setTimeout(() => { void tick().then(schedule); }, delay);
+  };
+
+  const onVisibility = () => {
+    clearTimeout(pollTimer);
+    if (document.hidden) return;
+    failures = 0;
+    void tick().then(schedule);
+  };
+  document.addEventListener("visibilitychange", onVisibility);
+  void tick().then(schedule);
   // 弹窗是命令式 DOM，没有 React 那层重渲染：语言切换后自己重画一次（开着的才重画）。
   relocalize = () => { if (current !== null && root.childElementCount > 0) showPopup(current); };
   return () => {
-    clearInterval(pollTimer);
+    clearTimeout(pollTimer);
+    document.removeEventListener("visibilitychange", onVisibility);
     if (hideTimer) clearTimeout(hideTimer);
     relocalize = null;
     root.remove();

package/lib/config.d.ts

@@ -58,6 +58,20 @@ export interface AccountConfig {
     provider?: ProviderRef;
     user?: string;
     password?: string;
+    /**
+     * Display name for the From header. The address stays `user` — recipients
+     * must see the mailbox that owns the mail, not the login.
+     */
+    senderName?: string;
+    /**
+     * Login handed to IMAP/SMTP when it differs from `user`: the alias case,
+     * where `user` is the address mail is sent *from* and the server only
+     * authenticates the real account, or a relay whose login is not a mailbox
+     * at all. Defaults to `user`.
+     */
+    authUser?: string;
+    /** Password that goes with `authUser`. Defaults to `password`. */
+    authPassword?: string;
     /**
      * Public-client id used by the OAuth2 device-code flow. Only read for an
      * OAuth2 account, where it overrides OUTLOOK_OAUTH2_CLIENT_ID.
@@ -141,6 +155,12 @@ export declare const EMAIL_PASSWORD_ENV = "DSH_EMAIL_PASSWORD";
 /** Fully resolved, validated configuration for one account. */
 export interface ResolvedEmailConfig {
     user: string;
+    /** Display name for the From header, '' when the account does not set one. */
+    senderName: string;
+    /** Login actually handed to IMAP/SMTP (== user unless authUser is set). */
+    authUser: string;
+    /** Password for authUser (== password unless authPassword is set). */
+    authPassword: string;
     /**
      * The app password / 授权码. Empty for an OAuth2 account — that is the point:
      * nothing is stored, the token store holds the credential instead.

package/lib/config.js

@@ -319,6 +319,12 @@ function resolveAccount(name, common, acc, allowEnvPassword, providers, known) {
     // The settings form uses '' for an empty password. In single-account mode
     // that explicitly selects the environment fallback; named accounts stay isolated.
     const password = (acc.password ?? common.password) || (allowEnvPassword ? process.env[EMAIL_PASSWORD_ENV] ?? '' : '');
+    // An alias account sends from `user` but authenticates as somebody else, and a
+    // relay may use a different password than the mailbox it delivers for. Both
+    // default to the single-account pair so nothing changes for existing setups.
+    const authUser = (acc.authUser ?? common.authUser ?? '').trim() || user;
+    const authPassword = (acc.authPassword ?? common.authPassword) || password;
+    const senderName = (acc.senderName ?? common.senderName ?? '').trim();
     const imap = {
         host: acc.imap?.host ?? common.imap?.host ?? preset?.imap.host,
         port: acc.imap?.port ?? common.imap?.port ?? preset?.imap.port,
@@ -347,8 +353,9 @@ function resolveAccount(name, common, acc, allowEnvPassword, providers, known) {
     // An OAuth2 account has no password on purpose: its credential is the token
     // in the OAuth2 store, and requiring a password would demand a secret
     // Microsoft no longer accepts for Exchange Online.
-    if (!oauth2 && password === '')
-        problems.push(`账号 "${name}" 的 password 未填写（单账号可用环境变量 ${EMAIL_PASSWORD_ENV}）`);
+    if (!oauth2 && authPassword === '') {
+        problems.push(`账号 "${name}" 的 ${authUser === user ? 'password' : 'authPassword'} 未填写（单账号可用环境变量 ${EMAIL_PASSWORD_ENV}）`);
+    }
     if (imap.host === undefined || imap.host === '')
         problems.push(`账号 "${name}" 的 imap.host 未填写（可填 provider 预设：${known.join('/')}）`);
     if (smtp.host === undefined || smtp.host === '')
@@ -359,8 +366,13 @@ function resolveAccount(name, common, acc, allowEnvPassword, providers, known) {
     const clientId = (acc.clientId ?? common.clientId ?? '').trim();
     return {
         user,
-        // An OAuth2 account never carries a password: a stale one left in the YAML
-        // from before the provider changed must not travel into the pool.
+        senderName,
+        // OAuth2 logs in with the token's own account, so the alias login pair only
+        // exists for password accounts; and an OAuth2 account never carries a
+        // password at all — a stale one left in the YAML from before the provider
+        // changed must not travel into the pool.
+        authUser: oauth2 ? user : authUser,
+        authPassword: oauth2 ? '' : authPassword,
         password: oauth2 ? '' : password,
         authKind: oauth2 ? 'oauth2' : 'password',
         ...(clientId !== '' ? { clientId } : {}),

package/lib/mail-client.d.ts

@@ -46,12 +46,12 @@ export type SmtpAuth = {
  * `accessToken` (imapflow then runs AUTHENTICATE XOAUTH2) and a password
  * account with `pass`, exactly as before.
  */
-export declare function imapAuthOf(cfg: Pick<ResolvedEmailConfig, 'user' | 'password' | 'authKind'>, accessToken?: string): ImapAuth;
+export declare function imapAuthOf(cfg: Pick<ResolvedEmailConfig, 'authUser' | 'authPassword' | 'authKind'>, accessToken?: string): ImapAuth;
 /**
  * Nodemailer consumes an OAuth2 token through accessToken, not pass.
  * Refresh remains owned by this plugin; no refresh credentials leave here.
  */
-export declare function smtpAuthOf(cfg: Pick<ResolvedEmailConfig, 'user' | 'password' | 'authKind'>, accessToken?: string): SmtpAuth;
+export declare function smtpAuthOf(cfg: Pick<ResolvedEmailConfig, 'authUser' | 'authPassword' | 'authKind'>, accessToken?: string): SmtpAuth;
 /** The message an OAuth2 account gets when the mailbox has to be logged into again. */
 export declare const OAUTH2_RELOGIN_MESSAGE = "\u90AE\u7BB1\u767B\u5F55\u5931\u8D25\uFF1A\u8BF7\u5230\u8BBE\u7F6E\u9875\u91CD\u65B0\u767B\u5F55\uFF08Microsoft \u8D26\u53F7\u4F7F\u7528\u8BBE\u5907\u7801\u767B\u5F55\uFF0C\u4E0D\u4F7F\u7528\u6388\u6743\u7801\uFF09";
 /**
@@ -106,7 +106,7 @@ export declare function extractMessageIds(source: Buffer): {
  * be tested without a connection: recipients exclude the sending account,
  * subject prefixes never stack, the original text is quoted underneath.
  */
-export declare function buildReplyMessage(original: OriginalDigest, mode: EmailReplyMode, selfAddress: string, text: string, forwardTo?: string): BuiltReply;
+export declare function buildReplyMessage(original: OriginalDigest, mode: EmailReplyMode, selfAddress: string | readonly string[], text: string, forwardTo?: string): BuiltReply;
 /**
  * One mailbox pool for the whole plugin: pooled IMAP connections per
  * account plus pooled SMTP transporters, with idle sweep and error eviction.
@@ -122,6 +122,16 @@ export declare class EmailPool {
     resolveName(name?: string): string;
     /** Serialize operations per account: one IMAP connection serves one op at a time. */
     private enqueue;
+    private readonly readCache;
+    private readonly folderCache;
+    /** Remember a parsed attachment index so email_attachment can skip the refetch. */
+    private rememberRead;
+    /**
+     * The attachment index for one message: the cached one when email_read already
+     * produced it, otherwise a fresh parse of the full source plus its bodyStructure.
+     */
+    private attachmentIndexOf;
+    private recallRead;
     withImap<T>(accountName: string | undefined, folder: string | null, run: (client: ImapFlow) => Promise<T>, readOnly?: boolean, signal?: AbortSignal): Promise<T>;
     private createImap;
     /**
@@ -159,7 +169,7 @@ export declare class EmailPool {
      */
     private sendMail;
     list(accountName: string | undefined, folder: string, limit: number, offset: number, unreadOnly: boolean, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailListResult>;
-    search(accountName: string | undefined, query: string, folder: string, limit: number, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailSearchResult>;
+    search(accountName: string | undefined, query: string, folder: string, limit: number, offset: number, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailSearchResult>;
     /**
      * Confirm server-side hits against the mailbox itself: fetch the envelopes
      * of the newest candidates — the same window the body-scan fallback looks at

package/lib/mail-client.js

@@ -41,8 +41,8 @@ export function redactCredentials(text) {
  */
 export function imapAuthOf(cfg, accessToken) {
     return cfg.authKind === 'oauth2'
-        ? { user: cfg.user, accessToken: accessToken ?? '' }
-        : { user: cfg.user, pass: cfg.password };
+        ? { user: cfg.authUser, accessToken: accessToken ?? '' }
+        : { user: cfg.authUser, pass: cfg.authPassword };
 }
 /**
  * Nodemailer consumes an OAuth2 token through accessToken, not pass.
@@ -50,8 +50,8 @@ export function imapAuthOf(cfg, accessToken) {
  */
 export function smtpAuthOf(cfg, accessToken) {
     return cfg.authKind === 'oauth2'
-        ? { type: 'OAuth2', user: cfg.user, accessToken: accessToken ?? '' }
-        : { user: cfg.user, pass: cfg.password };
+        ? { type: 'OAuth2', user: cfg.authUser, accessToken: accessToken ?? '' }
+        : { user: cfg.authUser, pass: cfg.authPassword };
 }
 /** The message an OAuth2 account gets when the mailbox has to be logged into again. */
 export const OAUTH2_RELOGIN_MESSAGE = '邮箱登录失败：请到设置页重新登录（Microsoft 账号使用设备码登录，不使用授权码）';
@@ -118,6 +118,10 @@ export function selectAttachmentPart(readAttachments, parts, index) {
     const byTypeAndSize = parts.find(part => part.contentType === meta.contentType && Math.abs(part.size - meta.size) <= tolerance);
     return byTypeAndSize;
 }
+/** The From header: `user` is the visible address, `senderName` only labels it. */
+function senderOf(cfg) {
+    return cfg.senderName === '' ? cfg.user : { name: cfg.senderName, address: cfg.user };
+}
 /** Case-insensitive match of a query against subject/from/body text. */
 export function messageMatchesQuery(subject, fromText, body, query) {
     const q = query.toLowerCase();
@@ -142,10 +146,11 @@ function formatAddress(entry) {
 }
 function dedupeAddresses(entries, exclude) {
     const seen = new Set();
+    const excluded = new Set((Array.isArray(exclude) ? exclude : [exclude]).map(a => a.trim().toLowerCase()).filter(a => a !== ''));
     const out = [];
     for (const entry of entries) {
         const addr = (entry.address ?? '').toLowerCase();
-        if (addr === '' || addr === exclude || seen.has(addr))
+        if (addr === '' || excluded.has(addr) || seen.has(addr))
             continue;
         seen.add(addr);
         out.push(entry);
@@ -164,7 +169,7 @@ const FORWARD_MAX_CHARS = 4000;
  */
 export function buildReplyMessage(original, mode, selfAddress, text, forwardTo = '') {
     const fromText = original.from.map(a => a.name ?? a.address).filter(Boolean).join(', ') || '(未知发件人)';
-    const self = selfAddress.toLowerCase();
+    const self = (Array.isArray(selfAddress) ? selfAddress : [selfAddress]).filter(a => a.trim() !== '');
     if (mode === 'forward') {
         const to = forwardTo.trim();
         if (to === '')
@@ -231,6 +236,11 @@ function listedFrom(envelope, size, hasAttachments) {
         hasAttachments,
     };
 }
+/** email_attachment reuses the MIME index email_read already parsed; keep a few. */
+const READ_CACHE_MAX = 16;
+const READ_CACHE_TTL_MS = 10 * 60 * 1000;
+/** Folder names change rarely; a short TTL keeps email_folders off the wire. */
+const FOLDER_CACHE_TTL_MS = 60 * 1000;
 /**
  * One mailbox pool for the whole plugin: pooled IMAP connections per
  * account plus pooled SMTP transporters, with idle sweep and error eviction.
@@ -265,6 +275,49 @@ export class EmailPool {
         this.queues.set(name, next.then(() => undefined, () => undefined));
         return next;
     }
+    readCache = new Map();
+    folderCache = new Map();
+    /** Remember a parsed attachment index so email_attachment can skip the refetch. */
+    rememberRead(account, folder, uid, parsed) {
+        const key = account + '\u0000' + folder + '\u0000' + uid;
+        this.readCache.delete(key);
+        this.readCache.set(key, { ...parsed, at: Date.now() });
+        while (this.readCache.size > READ_CACHE_MAX) {
+            const oldest = this.readCache.keys().next();
+            if (oldest.done === true)
+                break;
+            this.readCache.delete(oldest.value);
+        }
+    }
+    /**
+     * The attachment index for one message: the cached one when email_read already
+     * produced it, otherwise a fresh parse of the full source plus its bodyStructure.
+     */
+    async attachmentIndexOf(client, account, folder, uid, signal) {
+        const cached = this.recallRead(account, folder, uid);
+        if (cached !== undefined)
+            return cached;
+        const message = await client.fetchOne(uid, { uid: true, bodyStructure: true, source: true }, { uid: true });
+        if (message === false || message.source === undefined) {
+            throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folder + '"）');
+        }
+        const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
+        signal?.throwIfAborted();
+        const parsed = { attachments: body.attachments, parts: collectAttachmentParts(message.bodyStructure) };
+        this.rememberRead(account, folder, uid, parsed);
+        return parsed;
+    }
+    recallRead(account, folder, uid) {
+        const key = account + '\u0000' + folder + '\u0000' + uid;
+        const hit = this.readCache.get(key);
+        if (hit === undefined)
+            return undefined;
+        if (Date.now() - hit.at > READ_CACHE_TTL_MS) {
+            this.readCache.delete(key);
+            return undefined;
+        }
+        return hit;
+    }
     async withImap(accountName, folder, run, readOnly = true, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
@@ -532,6 +585,8 @@ export class EmailPool {
         return this.withImap(name, folderName, async (client) => {
             const mailbox = client.mailbox;
             const total = mailbox === false ? 0 : mailbox.exists;
+            // imapflow types uidValidity as number | bigint; the wire format is 32-bit.
+            const uidValidity = mailbox === false ? 0 : Number(mailbox.uidValidity ?? 0);
             let scopeCount = total;
             let uids = [];
             const hasDateFilter = since !== undefined || until !== undefined;
@@ -557,10 +612,10 @@ export class EmailPool {
             uids.reverse();
             const window = uids.slice(offset, offset + limit);
             const messages = await this.fetchListed(client, window, signal);
-            return { account: name, count: scopeCount, folder: folderName, messages };
+            return { account: name, count: scopeCount, folder: folderName, uidValidity, messages };
         }, true, signal);
     }
-    async search(accountName, query, folder, limit, since, until, signal) {
+    async search(accountName, query, folder, limit, offset, since, until, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -586,20 +641,23 @@ export class EmailPool {
             signal?.throwIfAborted();
             const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => b - a);
             if (uids.length > 0) {
-                const confirmed = await this.searchHits(client, uids, query, limit, signal);
+                // The sample has to cover the requested page (offset + limit) — the same
+                // window the fallback scan looks at — so one FETCH serves both the
+                // verification and the rows that are handed out.
+                const confirmed = await this.searchHits(client, uids, query, offset + limit, signal);
                 if (confirmed.length > 0) {
                     // The server's list holds up, so its size is reported as the match
                     // count; only rows that were confirmed are ever handed out.
-                    return { account: name, query, count: uids.length, folder: folderName, messages: confirmed.slice(0, limit) };
+                    return { account: name, query, count: uids.length, folder: folderName, offset, messages: confirmed.slice(offset, offset + limit) };
                 }
             }
             // Nothing believable came back (empty answer, or hits that did not
             // survive verification): scan the newest messages locally instead.
             if (this.settings.bodySearchFallback) {
-                const messages = await this.searchBodies(client, query, folderName, limit, since, until, signal);
-                return { account: name, query, count: messages.length, folder: folderName, messages };
+                const messages = await this.searchBodies(client, query, folderName, limit, offset, since, until, signal);
+                return { account: name, query, count: messages.length, folder: folderName, offset, messages };
             }
-            return { account: name, query, count: 0, folder: folderName, messages: [] };
+            return { account: name, query, count: 0, folder: folderName, offset, messages: [] };
         }, true, signal);
     }
     /**
@@ -609,8 +667,8 @@ export class EmailPool {
      * the four fields the server was asked about. No body is downloaded here,
      * and uids the server made up simply return nothing.
      */
-    async searchHits(client, uids, query, limit, signal) {
-        const sample = uids.slice(0, Math.min(uids.length, Math.max(this.settings.bodySearchLimit, limit)));
+    async searchHits(client, uids, query, need, signal) {
+        const sample = uids.slice(0, Math.min(uids.length, Math.max(this.settings.bodySearchLimit, need)));
         signal?.throwIfAborted();
         const fetched = await client.fetchAll(sample, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true }, { uid: true });
         signal?.throwIfAborted();
@@ -624,7 +682,7 @@ export class EmailPool {
             .sort((a, b) => b.uid - a.uid);
     }
     /** Client-side scan of the tail of the mailbox, newest first. */
-    async searchBodies(client, query, folder, limit, since, until, signal) {
+    async searchBodies(client, query, folder, limit, offset, since, until, signal) {
         signal?.throwIfAborted();
         const mailbox = client.mailbox;
         const total = mailbox === false ? 0 : mailbox.exists;
@@ -635,7 +693,7 @@ export class EmailPool {
         const out = [];
         for (const message of [...fetched].reverse()) {
             signal?.throwIfAborted();
-            if (out.length >= limit)
+            if (out.length >= offset + limit)
                 break;
             const receivedAt = message.internalDate ?? message.envelope?.date;
             if (since !== undefined && (receivedAt === undefined || receivedAt < since))
@@ -661,7 +719,7 @@ export class EmailPool {
                 out.push(listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)));
             }
         }
-        return out;
+        return out.slice(offset, offset + limit);
     }
     async fetchListed(client, uids, signal) {
         signal?.throwIfAborted();
@@ -678,12 +736,13 @@ export class EmailPool {
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
         return this.withImap(name, folderName, async (client) => {
-            const message = await client.fetchOne(uid, { uid: true, source: true }, { uid: true });
+            const message = await client.fetchOne(uid, { uid: true, source: true, bodyStructure: true }, { uid: true });
             if (message === false || message.source === undefined) {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
             const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
             signal?.throwIfAborted();
+            this.rememberRead(name, folderName, uid, { attachments: body.attachments, parts: collectAttachmentParts(message.bodyStructure) });
             return { account: name, uid, folder: folderName, ...body };
         }, true, signal);
     }
@@ -746,17 +805,23 @@ export class EmailPool {
     async folders(accountName, subscribedOnly, signal) {
         const name = this.resolveName(accountName);
         return this.withImap(name, null, async (client) => {
-            const list = await client.list();
-            signal?.throwIfAborted();
-            const folders = list
-                .filter(row => !subscribedOnly || row.subscribed !== false)
-                .map(row => ({
-                name: row.name ?? row.path,
-                path: row.path,
-                specialUse: row.specialUse ?? '',
-                subscribed: row.subscribed !== false,
-            }));
-            return { account: name, folders };
+            const cached = this.folderCache.get(name);
+            let rows;
+            if (cached !== undefined && Date.now() - cached.at < FOLDER_CACHE_TTL_MS) {
+                rows = cached.folders;
+            }
+            else {
+                const list = await client.list();
+                signal?.throwIfAborted();
+                rows = list.map(row => ({
+                    name: row.name ?? row.path,
+                    path: row.path,
+                    specialUse: row.specialUse ?? '',
+                    subscribed: row.subscribed !== false,
+                }));
+                this.folderCache.set(name, { at: Date.now(), folders: rows });
+            }
+            return { account: name, folders: rows.filter(row => !subscribedOnly || row.subscribed !== false) };
         }, true, signal);
     }
     async downloadAttachment(accountName, folder, uid, index, workspaceHint, signal) {
@@ -764,23 +829,19 @@ export class EmailPool {
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
         return this.withImap(name, folderName, async (client) => {
-            const message = await client.fetchOne(uid, { uid: true, bodyStructure: true, source: true }, { uid: true });
-            if (message === false || message.source === undefined) {
-                throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"）');
-            }
-            // The mailparser list is authoritative for the index email_read showed;
-            // the bodyStructure walk supplies the IMAP part to download.
-            const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
-            signal?.throwIfAborted();
-            const parts = collectAttachmentParts(message.bodyStructure);
-            if (body.attachments.length === 0)
+            // The mailparser list is authoritative for the index email_read showed and
+            // the bodyStructure walk supplies the IMAP part to download. email_read
+            // already produced both in the usual read-then-download flow, so reuse that
+            // instead of pulling the whole message — attachments included — again.
+            const { attachments, parts } = await this.attachmentIndexOf(client, name, folderName, uid, signal);
+            if (attachments.length === 0)
                 throw new MailError('该邮件没有附件');
-            if (body.attachments[index] === undefined) {
-                throw new MailError('附件序号 ' + index + ' 越界：共 ' + body.attachments.length + ' 个附件（序号从 0 开始，与 email_read 返回的 attachments 顺序一致）');
+            if (attachments[index] === undefined) {
+                throw new MailError('附件序号 ' + index + ' 越界：共 ' + attachments.length + ' 个附件（序号从 0 开始，与 email_read 返回的 attachments 顺序一致）');
             }
-            const att = selectAttachmentPart(body.attachments, parts, index);
+            const att = selectAttachmentPart(attachments, parts, index);
             if (att === undefined) {
-                throw new MailError('附件 #' + index + '（' + body.attachments[index].filename + '）无法在邮件结构中定位（可能是内嵌图片，暂不支持下载）');
+                throw new MailError('附件 #' + index + '（' + attachments[index].filename + '）无法在邮件结构中定位（可能是内嵌图片，暂不支持下载）');
             }
             if (att.size > this.settings.maxAttachmentBytes) {
                 throw new MailError('附件 "' + att.filename + '" 大小 ' + att.size + ' 字节，超过上限 maxAttachmentBytes=' + this.settings.maxAttachmentBytes);
@@ -788,7 +849,7 @@ export class EmailPool {
             const dl = await client.download(uid, att.part, { uid: true, maxBytes: this.settings.maxAttachmentBytes });
             signal?.throwIfAborted();
             const buf = await collectStream(dl.content, this.settings.maxAttachmentBytes, signal);
-            const safeName = sanitizeFilename(dl.meta.filename ?? att.filename ?? body.attachments[index].filename);
+            const safeName = sanitizeFilename(dl.meta.filename ?? att.filename ?? attachments[index].filename);
             // Default the destination to the session workspace so the model can
             // read the file back; an explicit downloadDir always wins.
             const dir = this.settings.downloadDirExplicit
@@ -809,7 +870,7 @@ export class EmailPool {
         const cfg = this.account(name);
         const attachments = await validateAttachmentPaths(attachmentPaths ?? [], this.settings.maxAttachmentBytes, signal);
         const info = await this.sendMail(name, cfg, {
-            from: cfg.user,
+            from: senderOf(cfg),
             to,
             cc,
             subject,
@@ -838,10 +899,13 @@ export class EmailPool {
             const ids = extractMessageIds(message.source);
             const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
             signal?.throwIfAborted();
-            return buildReplyMessage({ from: body.from, to: body.to, cc: body.cc, subject: body.subject, date: body.date, text: body.text, messageId: ids.messageId, references: ids.references }, mode, cfg.user, text, forwardTo);
+            return buildReplyMessage({ from: body.from, to: body.to, cc: body.cc, subject: body.subject, date: body.date, text: body.text, messageId: ids.messageId, references: ids.references }, mode, 
+            // Both the visible address and the login are "me": a reply-all that
+            // keeps either of them would mail the sender his own message.
+            cfg.authUser === cfg.user ? cfg.user : [cfg.user, cfg.authUser], text, forwardTo);
         }, true, signal);
         const info = await this.sendMail(name, cfg, {
-            from: cfg.user,
+            from: senderOf(cfg),
             to: built.to,
             cc,
             subject: built.subject,

package/lib/runtime.js

@@ -65,19 +65,26 @@ export function createEmailRuntime(ctx, config, createPool = settings => new Ema
         const capped = clampInt(limit, 20, 1, 100);
         const result = await getPool().list(account, folder, 100, 0, true, undefined, undefined, signal);
         const key = scope + '\u0000' + result.account + '\u0000' + result.folder;
-        const isFirst = !watchCursors.has(key);
-        const cursor = watchCursors.get(key) ?? 0;
+        const stored = watchCursors.get(key);
+        const uidValidity = typeof result.uidValidity === 'number' ? result.uidValidity : 0;
+        // A UIDVALIDITY change renumbers every message in the mailbox: keeping the
+        // old cursor would either report the whole folder as new or miss everything
+        // that renumbered below it. Re-seed the baseline instead and say so.
+        const reset = stored !== undefined && stored.uidValidity !== 0 && uidValidity !== 0 && stored.uidValidity !== uidValidity;
+        const isFirst = stored === undefined || reset;
+        const cursor = stored === undefined || reset ? 0 : stored.uid;
         const fresh = result.messages.filter(message => message.uid > cursor);
         if (result.messages.length > 0) {
-            watchCursors.set(key, Math.max(cursor, ...result.messages.map(message => message.uid)));
+            watchCursors.set(key, { uid: Math.max(cursor, ...result.messages.map(message => message.uid)), uidValidity });
         }
         else if (isFirst) {
-            watchCursors.set(key, 0);
+            watchCursors.set(key, { uid: 0, uidValidity });
         }
         return {
             account: result.account,
             folder: result.folder,
-            firstRun: isFirst,
+            firstRun: stored === undefined,
+            ...(reset ? { reset: true } : {}),
             newCount: isFirst ? 0 : fresh.length,
             messages: (isFirst ? [] : fresh).slice(0, capped),
             totalUnread: result.count,

package/lib/tool-contract.d.ts

@@ -350,6 +350,9 @@ export declare const watchSchema: {
         firstRun: {
             type: string;
         };
+        reset: {
+            type: string;
+        };
         newCount: {
             type: string;
         };

package/lib/tool-contract.js

@@ -199,7 +199,11 @@ export function renderSearch(value) {
         return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：共 ' + value.count + ' 条匹配，本次没有列出。');
     }
     const lines = value.messages.map((m, i) => '#' + (i + 1) + ' ' + describeMessage(m));
-    return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：共 ' + value.count + ' 条匹配，展示最新 ' + value.messages.length + ' 条：\n\n' + lines.join('\n'));
+    const offset = value.offset ?? 0;
+    const window = offset > 0
+        ? '跳过最新 ' + offset + ' 条后展示 ' + value.messages.length + ' 条'
+        : '展示最新 ' + value.messages.length + ' 条';
+    return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：共 ' + value.count + ' 条匹配，' + window + '：\n\n' + lines.join('\n'));
 }
 export function renderSend(value) {
     const rejected = value.rejected.length > 0 ? '；被拒：' + value.rejected.join(', ') : '';
@@ -229,6 +233,9 @@ export function renderReply(value) {
     return oneText('账号 ' + value.account + ' 已' + REPLY_LABELS[value.mode] + ' uid=' + value.originalUid + ' 的邮件：收件人 ' + value.to.join(', ') + '，主题「' + value.subject + '」，messageId: ' + value.messageId + rejected);
 }
 export function renderWatch(value) {
+    if (value.reset === true) {
+        return oneText('账号 ' + value.account + '：文件夹 "' + value.folder + '" 的 UIDVALIDITY 已变化（服务器重新编号了邮件），已重新建立基线（当前未读 ' + value.totalUnread + ' 封）。这次不报告新邮件，之后照常。');
+    }
     if (value.firstRun) {
         return oneText('账号 ' + value.account + '：已建立新邮件监视基线（当前未读 ' + value.totalUnread + ' 封）。之后调用 email_watch 只会报告新到的邮件。');
     }
@@ -269,6 +276,7 @@ export const watchSchema = {
         account: { type: 'string' },
         folder: { type: 'string' },
         firstRun: { type: 'boolean' },
+        reset: { type: 'boolean' },
         newCount: { type: 'integer' },
         totalUnread: { type: 'integer' },
         messages: { type: 'array', items: { type: 'object', properties: messageShape, additionalProperties: true } },
@@ -279,7 +287,7 @@ export const descriptions = {
     "email_list": 'List recent emails in a mailbox folder (newest first). Returns uid, date, sender, subject and flags without message bodies; use email_read with a uid to fetch the full text. Optional since/until (dates like 2026-08-01) filter by received date.',
     "email_read": 'Read one full email message by its uid (from email_list or email_search). Returns the plain-text body (HTML mail is converted; oversized bodies are truncated) plus attachment metadata; use email_attachment to download one.',
     "email_mark": 'Change an existing message: mark it read/unread, star/unstar it, or move it to another folder. Use after email_list/email_search when the user wants to tidy the mailbox (archive, clear unread, flag important mail). Moving uses the server MOVE/COPY so the uid changes; the new uid is reported when the server provides it.',
-    "email_search": 'Search emails by a keyword. The server first searches sender, recipients and subject; those hits are re-verified against the envelopes and, when none of them really carries the keyword (some servers answer every search with the same uids), recent messages are scanned locally including their body while bodySearchFallback is enabled. since/until still constrain both paths. Returns the same compact rows as email_list.',
+    "email_search": 'Search emails by a keyword. The server first searches sender, recipients and subject; those hits are re-verified against the envelopes and, when none of them really carries the keyword (some servers answer every search with the same uids), recent messages are scanned locally including their body while bodySearchFallback is enabled. offset skips the newest matches for paging; since/until still constrain both paths. Returns the same compact rows as email_list.',
     "email_send": 'Send an email from a configured account, optionally with file attachments (absolute paths, or relative to the dsh process cwd). Sending asks the user for approval (recipient, subject and attachment count are shown) unless sendApproval is disabled; in Full Access mode the approval policy never asks, so the send is refused with an explanation instead. Never invent recipients or content without the user\'s instruction.',
     "email_reply": 'Reply to, reply-all to, or forward an existing message (mode: reply | reply-all | forward). Recipients come from the original message (your own address is excluded automatically), the subject gets a single Re:/Fwd: prefix, the original text is quoted underneath, and In-Reply-To/References headers keep mail clients threading correctly. mode=forward needs the to parameter. Like email_send, this asks the user for approval before sending. Never invent recipients or content without the user\'s instruction.',
     "email_folders": 'List the mailbox folders of an account (INBOX, Sent, Trash, custom folders, ...). Use the returned path values as the folder argument of the other email tools.',
@@ -313,6 +321,7 @@ export const parameters = {
         query: { type: 'string', required: true, description: 'Keyword to search for' },
         folder: { type: 'string', description: 'IMAP folder to search in; defaults to the account inboxFolder' },
         limit: { type: 'integer', description: 'How many matches to return, 1-100, default 10' },
+        offset: { type: 'integer', description: 'Skip this many newest matches first, default 0' },
         since: { type: 'string', description: 'Only search messages received on or after this date, e.g. 2026-08-01 (optional)' },
         until: { type: 'string', description: 'Only search messages received on or before this date, e.g. 2026-08-26 (optional)' },
         account: { type: 'string', description: ACCOUNT_HINT },

package/lib/tools.js

@@ -74,9 +74,10 @@ export function buildEmailTools(runtime) {
                 if (typeof args.query !== 'string' || args.query.trim() === '')
                     throw new Error('query 不能为空');
                 const limit = clampInt(args.limit, 10, 1, MAX_LIMIT);
+                const offset = clampInt(args.offset, 0, 0, 10000);
                 const since = args.since?.trim() ? parseEmailDay(args.since, 'since') : undefined;
                 const until = args.until?.trim() ? parseEmailDay(args.until, 'until', true) : undefined;
-                return await getPool().search(args.account, args.query.trim(), args.folder?.trim() || '', limit, since, until, executionSignal(exec));
+                return await getPool().search(args.account, args.query.trim(), args.folder?.trim() || '', limit, offset, since, until, executionSignal(exec));
             }
         },
         {

package/lib/types.d.ts

@@ -39,6 +39,8 @@ export interface EmailListResult {
     account: string;
     count: number;
     folder: string;
+    /** The mailbox's UIDVALIDITY; 0 when the server did not report one. */
+    uidValidity: number;
     messages: ListedMessage[];
 }
 export interface EmailReadResult extends ReadMessageBody {
@@ -51,6 +53,8 @@ export interface EmailSearchResult {
     query: string;
     count: number;
     folder: string;
+    /** How many newest matches the caller skipped (0 on the first page). */
+    offset: number;
     messages: ListedMessage[];
 }
 export interface EmailSendResult {
@@ -99,6 +103,7 @@ export interface EmailSearchArgs extends AccountArg {
     query: string;
     folder?: string;
     limit?: number;
+    offset?: number;
     since?: string;
     until?: string;
 }
@@ -175,6 +180,8 @@ export interface EmailWatchResult {
     /** Unread messages never reported before (empty on firstRun). */
     newCount: number;
     messages: ListedMessage[];
+    /** True when a server-side UIDVALIDITY change forced a fresh baseline. */
+    reset?: boolean;
     /** Total unread in the folder right now. */
     totalUnread: number;
 }

package/lib/web.d.ts

@@ -40,6 +40,12 @@ export interface AccountCardData {
      * exactly the state that has to be fixed before login can start.
      */
     clientId?: string;
+    /** Display name for the From header, when the account sets one. */
+    senderName?: string;
+    /** Login user when it differs from the visible address (`user`). */
+    authUser?: string;
+    /** Whether a login password separate from `password` is stored. */
+    hasAuthPassword?: boolean;
     /** Login state of an OAuth2 account: none / a device code in flight / logged in. */
     oauthState: OAuth2State;
     /** The mailbox address the stored token belongs to (OAuth2 accounts only). */
@@ -77,6 +83,23 @@ export interface AccountCardInput {
      * 第三方应用注册，所以这是 OAuth2 账号的必填项，而设置面板是用户唯一的常规入口。
      */
     clientId?: string;
+    /**
+     * 发件显示名，三态契约同 clientId：undefined = 本卡片没提供（保留已存的
+     * senderName 键），'' = 明确清除，非空 = 写入。只改收件人看到的名称，发件地址
+     * 始终是 user。
+     */
+    senderName?: string;
+    /**
+     * 登录账号（IMAP/SMTP 认证用），三态契约同上：undefined = 保留，'' = 清除（回到
+     * 用 user 登录），非空 = 写入。别名/中继场景下 user 是发件地址，它才是登录名。
+     */
+    authUser?: string;
+    /**
+     * 登录账号自己的密码，三态契约与 password 完全相同（undefined = 保留已存的值，
+     * '' = 明确清除，非空 = 写入）。只有 authUser 与 user 不同、且密码也不一样时
+     * 才需要。
+     */
+    authPassword?: string;
     /**
      * 认证方式覆盖，三态契约同上：undefined = 本卡片没提供（保留已存的 authKind 键），
      * '' = 明确恢复「自动」（删掉该键，回到按 provider/主机派生），非空 = 钉住。

package/lib/web.js

@@ -87,6 +87,11 @@ function buildAccountCards(raw, defaultAccount, presets, tokens = () => ({ state
         // back for the editor to prefill: an OAuth2 account without one cannot
         // start a device-code login, and the card is where that gets fixed.
         const clientId = typeof account.clientId === 'string' ? account.clientId.trim() : '';
+        // The display name and the login user are not secrets, so — like clientId —
+        // the card hands them back for the editor to prefill. A separate login
+        // password is a secret and only ever reported as a boolean.
+        const senderName = typeof account.senderName === 'string' ? account.senderName.trim() : '';
+        const authUser = typeof account.authUser === 'string' ? account.authUser.trim() : '';
         const oauth = authKind === 'oauth2' ? tokens(name, user) : { state: 'none' };
         list.push({
             name,
@@ -97,6 +102,9 @@ function buildAccountCards(raw, defaultAccount, presets, tokens = () => ({ state
             authKind,
             ...(pinned === 'oauth2' || pinned === 'password' ? { authKindDeclared: pinned } : {}),
             ...(clientId !== '' ? { clientId } : {}),
+            ...(senderName !== '' ? { senderName } : {}),
+            ...(authUser !== '' ? { authUser } : {}),
+            ...(typeof account.authPassword === 'string' && account.authPassword !== '' ? { hasAuthPassword: true } : {}),
             oauthState: oauth.state,
             ...(oauth.user !== undefined ? { oauthUser: oauth.user } : {}),
             imap,
@@ -318,7 +326,7 @@ function persistedProvider(provider, customNames) {
  * contract on AccountCardInput: the card omits the field whenever the editor has
  * nothing to say about it, which must leave the stored secret untouched.
  */
-function normalizeCardForYaml(card, customNames, inheritedPassword) {
+function normalizeCardForYaml(card, customNames, inheritedPassword, inheritedAuthPassword) {
     const out = {};
     const provider = persistedProvider(card.provider, customNames);
     if (provider !== undefined)
@@ -355,16 +363,40 @@ function normalizeCardForYaml(card, customNames, inheritedPassword) {
     }
     if (card.inboxFolder !== undefined)
         out.inboxFolder = card.inboxFolder;
+    if (card.senderName !== undefined) {
+        const senderName = String(card.senderName).trim();
+        if (senderName !== '')
+            out.senderName = senderName;
+    }
+    if (card.authUser !== undefined) {
+        const authUser = String(card.authUser).trim();
+        if (authUser !== '')
+            out.authUser = authUser;
+    }
+    if (card.authPassword === undefined) {
+        // Same contract as password: a card that says nothing must not delete it.
+        if (inheritedAuthPassword !== undefined)
+            out.authPassword = inheritedAuthPassword;
+    }
+    else if (card.authPassword !== '') {
+        out.authPassword = String(card.authPassword);
+    }
     return out;
 }
-/** The `password` stored in the source YAML for one account, if the key is there. */
-function storedPasswordOf(raw, name) {
+/** One secret key stored in the source YAML for one account, if it is there. */
+function storedSecretOf(raw, name, key) {
     const account = raw[name];
     if (account === null || typeof account !== 'object' || Array.isArray(account))
         return { present: false, value: undefined };
-    if (!Object.prototype.hasOwnProperty.call(account, 'password'))
+    if (!Object.prototype.hasOwnProperty.call(account, key))
         return { present: false, value: undefined };
-    return { present: true, value: account.password };
+    return { present: true, value: account[key] };
+}
+function storedPasswordOf(raw, name) {
+    return storedSecretOf(raw, name, 'password');
+}
+function storedAuthPasswordOf(raw, name) {
+    return storedSecretOf(raw, name, 'authPassword');
 }
 /**
  * Fallback writer: loses comments but keeps the semantics the cards describe.
@@ -390,6 +422,7 @@ function fallbackSerialize(cards, defaultAccount, source, customNames) {
     for (const card of cards) {
         const name = card.name;
         let inherited;
+        let inheritedAuthPassword;
         if (stored === undefined) {
             // Nothing could be read back: a silent card may be losing a real secret.
             if (card.password === undefined)
@@ -399,8 +432,11 @@ function fallbackSerialize(cards, defaultAccount, source, customNames) {
             const { present, value } = storedPasswordOf(stored, name);
             if (present)
                 inherited = value;
+            const auth = storedAuthPasswordOf(stored, name);
+            if (auth.present)
+                inheritedAuthPassword = auth.value;
         }
-        raw[name] = normalizeCardForYaml(card, customNames, inherited);
+        raw[name] = normalizeCardForYaml(card, customNames, inherited, inheritedAuthPassword);
     }
     return {
         accountsYaml: serializeAccountsYaml(raw, defaultAccount),
@@ -485,6 +521,26 @@ function serializeAccountsDraft(source, cards, defaultAccount, customNames) {
         const nextProvider = persistedProvider(card.provider, customNames);
         writeField(account, 'provider', nextProvider);
         writeField(account, 'user', card.user);
+        // senderName / authUser are plain three-state fields (undefined = 保持原样,
+        // '' = 清除, 非空 = 写入) — writeField already implements exactly that.
+        // An undefined field means "this card says nothing" — writeField would read
+        // that as「delete」, so the guard has to live here, not inside it.
+        if (card.senderName !== undefined)
+            writeField(account, 'senderName', String(card.senderName).trim());
+        if (card.authUser !== undefined)
+            writeField(account, 'authUser', String(card.authUser).trim());
+        // authPassword is a secret and follows the password contract verbatim: the
+        // card never carries the plaintext, so an omitted field must leave the
+        // stored key — value, position and comment — untouched.
+        if (card.authPassword === undefined) {
+            // 未提供 = 保持原样：什么都不写。
+        }
+        else if (card.authPassword === '') {
+            account.delete('authPassword');
+        }
+        else {
+            account.set('authPassword', String(card.authPassword));
+        }
         // Password is three-state, unlike every other field: the card is never given
         // the plaintext (snapshot exposes hasPassword only), so an omitted password
         // means "the editor has nothing to say" and the stored key must survive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-email",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "DeepSeek Harness 邮件插件：IMAP/SMTP 收发、搜索、回复转发、邮件整理与增量收件，支持多邮箱预设、发信审批及 Web 设置与新邮件通知。",
   "type": "module",
   "main": "lib/index.js",