dsh-email 0.15.2 → 0.15.3

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.15.3 (2026-10-04)
+
+- 完成 [#21](https://github.com/STARDUSTLC666/dsh-email/issues/21)：邮箱账号页新增「显示新邮件弹窗」开关，自动保存、重启后保留。关闭时隐藏当前卡片并停止自动邮件检查，不影响手动邮件工具。
+- 重新开启建立新基线，不补弹关闭期间的旧邮件；跨页面保存的开关在下一次本地设置刷新时生效。关闭或卸载后，迟到的网络响应不能重新显示弹窗。
+- 验收范围见 [0.15.3 通知开关检查](docs/validation/0.15.3.md)。
+
 ## 0.15.2 (2026-10-03)
 
 - 修复语言切换后设置菜单滞后一轮；英文草稿、账号、发送失败引导不再回退中文，保留结果不明时禁止盲目重发的提示。

package/README.en.md

@@ -2,6 +2,8 @@
 
 [中文](README.md)
 
+![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.
 
 [![npm](https://img.shields.io/npm/v/dsh-email)](https://www.npmjs.com/package/dsh-email) [![downloads](https://img.shields.io/npm/dm/dsh-email)](https://www.npmjs.com/package/dsh-email)
@@ -11,6 +13,7 @@ Read, send, search and organize email from DSH with multiple accounts.
 - Read, send, reply and forward using IMAP and SMTP.
 - Manage attachments, search results and mailbox organization.
 - Configure multiple accounts, Outlook OAuth2 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.
 - Manage trusted recipients per account and preview address, group and Cc matches.
 

package/README.md

@@ -2,6 +2,8 @@
 
 [English](README.en.md)
 
+![dsh-email 鲸鱼娘插件封面](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/cover-whale-girl.png)
+
 在 DSH 中收发、搜索和整理邮件，支持多个邮箱账号。
 
 [![npm](https://img.shields.io/npm/v/dsh-email)](https://www.npmjs.com/package/dsh-email) [![downloads](https://img.shields.io/npm/dm/dsh-email)](https://www.npmjs.com/package/dsh-email)
@@ -11,6 +13,7 @@
 - 通过 IMAP / SMTP 收发、回复和转发邮件。
 - 管理附件、搜索结果与邮箱整理操作。
 - 多账号设置，支持 Outlook OAuth2 和发信审批。
+- 新邮件弹窗可在设置中关闭，保存后重启仍生效。
 - 准备和编辑本地草稿，核对发件人、To/Cc、正文与附件预览后再确认发送。
 - 按账号管理可信收件人，预览规则如何匹配地址、地址组和抄送。
 

package/docs/USAGE.en.md

@@ -24,6 +24,8 @@ See the [draft workbench](DRAFTS.en.md) for editable drafts and per-account trus
 
 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.
 
+In Settings → Email → Accounts, turn off **Show new-mail popups** to hide the current popup and stop automatic mail checks. This setting saves automatically and survives a restart; it defaults to on. Re-enabling first seeds a fresh baseline, without replaying mail from the disabled period. Checks pause while the page is hidden. A change saved in another page takes effect on the next local-settings refresh. Conversation tools, including `email_watch`, remain available.
+
 The popup artwork prefers the locally installed [dsh-deep-whale](https://github.com/Small-tailqwq/dsh-deep-whale) whale-girl skin assets (**never bundled** — read at runtime from your own installation): the artwork is a derivative of the original whale-girl character by [上善](https://www.pixiv.net/users/62155430) (skin by Small-tailqwq), published under CC BY-NC-SA 4.0 (Attribution-NonCommercial-ShareAlike); the popup shows the full attribution chain. Without the skin, a bundled community whale-girl artwork is used (copyright stays with the original author, personal non-commercial use only; removed on request via issue).
 
 Example:

package/docs/USAGE.md

@@ -24,6 +24,8 @@
 
 配置好账号后，主界面右下角会出现「鲸鱼娘递信」小弹窗：每 30 秒检查一次新邮件，有新邮件时弹出卡片（发件人 + 主题），12 秒自动消失。弹窗与 `email_watch` 工具共用同一套游标逻辑但各自独立计数，互不抢占。
 
+在「设置 → 邮件 → 邮箱账号」取消勾选「显示新邮件弹窗」，立即隐藏当前弹窗并停止自动检查；设置会自动保存，重启后仍生效。默认开启。再次开启时先建立新的基线，不补弹关闭期间的旧邮件。页面隐藏时暂停检查；另一个页面保存的开关在下一次本地设置刷新时生效。对话中的 `email_watch` 等邮件工具照常可用。
+
 弹窗形象优先使用本地安装的 [dsh-deep-whale](https://github.com/Small-tailqwq/dsh-deep-whale) 鲸鱼娘皮肤素材（**不打包分发**，运行时从你自己的安装目录读取）：该素材为一创 [上善](https://www.pixiv.net/users/62155430) 鲸鱼娘形象的衍生创作（二创 Small-tailqwq），以 CC BY-NC-SA 4.0（署名-非商业性使用-相同方式共享）发布，弹窗内附完整署名链。未安装皮肤时使用内置的社区鲸鱼娘形象（版权归原作者，仅供个人非商业使用；如有异议请提 Issue，会立即移除）。
 
 示例对话：

package/docs/VALIDATION.md

@@ -1,5 +1,7 @@
 # dsh-email 验证记录
 
+[0.15.3 通知开关验收](validation/0.15.3.md)。
+
 [0.15.2 中英文界面验收](validation-language-2026-10-03.md)。
 
 ## 0.15.1（2026-10-03）

package/docs/validation/0.15.3.md

@@ -0,0 +1,7 @@
+# 0.15.3 通知开关验收 · 2026-10-04
+
+Windows / Node 24.16.0：334 项测试全部通过。新增回归覆盖默认开启、持久化、不重建连接池、关闭时停止自动检查、跨页面重新开启、静默基线，以及忽略取消信号的迟到响应在关闭或卸载后不能复活弹窗。
+
+在官方源码构建的 DSH 0.2.0-rc.2（639ed01539）独立 profile 中操作了中文和英文设置页，关闭开关、自动保存、键盘 Space 重新开启及页面重新加载。主界面实际显示了合成新邮件弹窗，再从邮件设置关闭开关，卡片被移除。设置写入独立配置文件，测试账号和合成新邮件不含真实邮箱凭据。
+
+网络和通知测试不发送邮件，也不改变对话中的邮件工具权限。真实邮箱登录、SMTP 投递及原生桌面窗口未在本轮验收；网页通过不能替代原生桌面验收。

package/lib/client.js

@@ -32,7 +32,7 @@ function emailError(error) {
 /** 「编辑即保存」的防抖窗口：连续打字只落一次盘。 */
 const SAVE_DEBOUNCE_MS = 800;
 
-async function api(action, payload) {
+async function api(action, payload, signal) {
   const init = action === undefined
     ? { credentials: "same-origin" }
     : {
@@ -41,7 +41,7 @@ async function api(action, payload) {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(Object.assign({ action }, payload)),
       };
-  const res = await fetch(ROUTE, init);
+  const res = await fetch(ROUTE, { ...init, signal });
   const body = await res.json();
   if (!res.ok || !body.ok) {
     const error = new Error((body && body.error && body.error.message) || ("request failed " + res.status));
@@ -138,6 +138,7 @@ const EMPTY = {
   password: "",
   inboxFolder: "INBOX",
   sendApproval: true,
+  newMailPopup: true,
   downloadDir: "",
   accountsYaml: "",
   serverPresets: "",
@@ -290,7 +291,7 @@ var UI = {
     "global.sendApproval": "发信前弹确认（强烈建议保留；Full Access 模式下会被自动拒绝）",
     "global.downloadDirLabel": "附件下载目录（默认保存在当前工作区）",
     "global.downloadDirPlaceholder": "留空使用默认",
-    "global.hint": "以上两项对所有账号统一生效。",
+    "global.hint": "以上设置对所有账号统一生效。",
 
     // 自动保存状态条
     "status.saved": "已保存",
@@ -471,7 +472,7 @@ var UI = {
     "global.sendApproval": "Ask for confirmation before sending (strongly recommended; auto-denied under Full Access)",
     "global.downloadDirLabel": "Attachment download directory (defaults to the current workspace)",
     "global.downloadDirPlaceholder": "Leave empty for the default",
-    "global.hint": "These two settings apply to every account.",
+    "global.hint": "These settings apply to every account.",
 
     // 自动保存状态条
     "status.saved": "Saved",
@@ -2300,6 +2301,11 @@ function EmailSettingsSection() {
   const [tab, setTab] = useState(emailActiveTab);
   useEffect(() => { emailActiveTab = tab; }, [tab]);
   const [draft, setDraft] = useState(null);
+  useEffect(() => {
+    if (draft === null) return undefined;
+    updateWhalePreference?.(draft.newMailPopup !== false);
+    return () => updateWhalePreference?.(null);
+  }, [draft?.newMailPopup]);
   const [snapshot, setSnapshot] = useState(undefined);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState("");
@@ -2592,6 +2598,16 @@ function EmailSettingsSection() {
       // 全局设置：发信确认和下载目录对所有账号一视同仁，不属于任何一张卡片，
       // 所以摆在卡片列表上方，而不是塞进某一张卡里。
       h("div", { className: "dshe-global" }, [
+        h("label", { className: "dshe-check" }, [
+          h("input", {
+            type: "checkbox",
+            checked: draft.newMailPopup !== false,
+            disabled: snapshot?.writable === false,
+            onChange: (e) => update({ newMailPopup: e.target.checked }),
+          }),
+          dt("显示新邮件弹窗", "Show new-mail popups"),
+        ]),
+        h("div", { className: "dshe-hint" }, dt("关闭后立即隐藏弹窗并停止自动检查，不影响对话中手动查看邮件。重新开启时从当前邮件开始提醒。", "Turning this off hides the popup and stops automatic mail checks. You can still check mail in a conversation. Turning it back on starts with a fresh baseline.")),
         h("label", { className: "dshe-check" }, [
           h("input", {
             type: "checkbox",
@@ -2641,6 +2657,7 @@ function EmailSettingsSection() {
 // when newCount > 0. The artwork URL/credit come from the settings snapshot
 // (skin artwork is served from the user's local dsh-deep-whale install with
 // its CC BY-NC-SA attribution chain; otherwise a built-in fallback is used).
+let updateWhalePreference = null;
 function startWhaleWidget() {
   if (document.querySelector("#dsh-email-whale-root")) return () => {};
   const root = document.createElement("div");
@@ -2651,17 +2668,26 @@ function startWhaleWidget() {
   let hideTimer = 0;
   let whaleUrl = "";
   let whaleCredit = "";
+  let enabled = true;
+  let localPreference = null;
+  let disposed = false;
+  let running = false;
+  let generation = 0;
+  let seedBaseline = true;
+  let watchAbort = null;
   /** 当前弹窗的数据。语言切了就靠它原样重画一遍，无需再拉一次接口。 */
   let current = null;
 
   const closePopup = () => {
     if (hideTimer) { clearTimeout(hideTimer); hideTimer = 0; }
     root.replaceChildren();
+    current = null;
   };
 
   const showPopup = (value) => {
-    current = value;
     closePopup();
+    if (disposed || !enabled) return;
+    current = value;
     const card = document.createElement("div");
     card.className = "dshe-whale-card";
     if (whaleUrl) {
@@ -2709,46 +2735,63 @@ function startWhaleWidget() {
   };
 
   // 轮询策略：页面不可见时完全不打扰邮箱服务器；失败指数退避（上限 10 分钟），
-  // 成功立刻回到 30s；快照（皮肤 / 账号列表）变化很慢，最多 10 分钟刷新一次。
+  // 成功立刻回到 30s；本地设置快照同样刷新，以便跨页面的通知开关生效。
   const POLL_MS = 30000;
-  const SNAPSHOT_MS = 600000;
   const MAX_BACKOFF_MS = 600000;
   let failures = 0;
-  let lastSnapshot = 0;
-  let hasAccounts = true;
+  const setEnabled = (value) => {
+    if (value === enabled) return;
+    enabled = value;
+    generation++;
+    seedBaseline = true;
+    watchAbort?.abort();
+    if (!enabled) closePopup();
+  };
+  updateWhalePreference = value => {
+    localPreference = value;
+    if (value !== null) setEnabled(value);
+  };
 
   const tick = async () => {
-    if (document.hidden) return;
+    if (disposed || document.hidden || running) return;
+    running = true;
     try {
-      if (!hasAccounts || Date.now() - lastSnapshot > SNAPSHOT_MS) {
-        const snap = await api();
-        lastSnapshot = Date.now();
-        if (snap && snap.whale) {
-          whaleUrl = (snap.whale.url || "").replace(/^\/_dsh\//, "_dsh/");
-          whaleCredit = snap.whale.credit || "";
-        }
-        hasAccounts = !!(snap && snap.accounts && snap.accounts.length > 0);
+      // Refresh the small local snapshot even when disabled so another tab's
+      // saved preference takes effect. This does not contact the mail server.
+      const snap = await api();
+      if (disposed) return;
+      setEnabled(localPreference ?? (snap?.settings?.value?.newMailPopup !== false));
+      if (snap && snap.whale) {
+        whaleUrl = (snap.whale.url || "").replace(/^\/_dsh\//, "_dsh/");
+        whaleCredit = snap.whale.credit || "";
       }
-      if (!hasAccounts) return;
-      const value = await api("watch", { limit: 5 });
-      if (value && value.newCount > 0) showPopup(value);
+      if (!enabled || !snap?.accounts?.length || document.hidden) { failures = 0; return; }
+      const version = generation;
+      watchAbort = new AbortController();
+      const value = await api("watch", { limit: 5 }, watchAbort.signal);
+      if (disposed || !enabled || version !== generation || document.hidden) return;
+      if (!seedBaseline && value && value.newCount > 0) showPopup(value);
+      seedBaseline = false;
       failures = 0;
     } catch (e) {
       // Not configured or transient error: stay silent and back off.
       failures = Math.min(failures + 1, 8);
+    } finally {
+      running = false;
+      watchAbort = null;
     }
   };
 
   const schedule = () => {
     clearTimeout(pollTimer);
-    if (document.hidden) return; // 回到前台时 onVisibility 会立刻补一次
+    if (disposed || document.hidden) return;
     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;
+    if (disposed || document.hidden) { watchAbort?.abort(); closePopup(); return; }
     failures = 0;
     void tick().then(schedule);
   };
@@ -2757,10 +2800,14 @@ function startWhaleWidget() {
   // 弹窗是命令式 DOM，没有 React 那层重渲染：语言切换后自己重画一次（开着的才重画）。
   relocalize = () => { if (current !== null && root.childElementCount > 0) showPopup(current); };
   return () => {
+    disposed = true;
+    generation++;
+    watchAbort?.abort();
     clearTimeout(pollTimer);
     document.removeEventListener("visibilitychange", onVisibility);
     if (hideTimer) clearTimeout(hideTimer);
     relocalize = null;
+    updateWhalePreference = null;
     root.remove();
   };
 }

package/lib/config.d.ts

@@ -108,6 +108,8 @@ export interface AccountConfig {
     inboxFolder?: string;
 }
 export interface EmailConfig extends AccountConfig {
+    /** Show browser new-mail notifications. UI policy only; default true. */
+    newMailPopup?: boolean;
     /** Per-account recipient rules, independent of IMAP/SMTP connection settings. */
     trustedRecipientsYaml?: string;
     /** Ask the user for approval before email_send. Default true. */

package/lib/host-config.js

@@ -12,6 +12,7 @@ export const Config = z.object({
     clientId: z.string().volatile(), authKind: z.union(['password', 'oauth2']).volatile(),
     imap: endpoint().volatile(), smtp: endpoint().volatile(),
     inboxFolder: z.string().volatile(), sendApproval: z.boolean().volatile(),
+    newMailPopup: z.boolean().volatile(),
     maxBodyChars: z.number().volatile(), downloadDir: z.string().volatile(),
     accounts: z.dict(z.any()).role('secret').volatile(), defaultAccount: z.string().volatile(),
     accountsYaml: z.string().role('secret').volatile(), serverPresets: z.string().volatile(),

package/lib/settings.d.ts

@@ -12,6 +12,7 @@ export declare const EmailSettingsSchema: import("@deepseek-ai/schemastery").def
     password: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     inboxFolder: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     sendApproval: import("@deepseek-ai/schemastery").default<boolean, boolean, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
+    newMailPopup: import("@deepseek-ai/schemastery").default<boolean, boolean, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     trustedRecipientsYaml: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     maxBodyChars: import("@deepseek-ai/schemastery").default<number, number, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     downloadDir: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
@@ -41,6 +42,7 @@ export declare const EmailSettingsSchema: import("@deepseek-ai/schemastery").def
     password: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     inboxFolder: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     sendApproval: import("@deepseek-ai/schemastery").default<boolean, boolean, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
+    newMailPopup: import("@deepseek-ai/schemastery").default<boolean, boolean, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     trustedRecipientsYaml: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     maxBodyChars: import("@deepseek-ai/schemastery").default<number, number, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
     downloadDir: import("@deepseek-ai/schemastery").default<string, string, Mode extends "volatile" | "volatile-defined" ? "volatile-defined" : "defined">;
@@ -71,6 +73,7 @@ export interface EmailSettingsValue {
     password: string;
     inboxFolder: string;
     sendApproval: boolean;
+    newMailPopup?: boolean;
     trustedRecipientsYaml?: string;
     maxBodyChars: number;
     downloadDir: string;

package/lib/settings.js

@@ -14,6 +14,7 @@ export const EmailSettingsSchema = z.object({
     password: z.string().role('secret').default(''),
     inboxFolder: z.string().default('INBOX'),
     sendApproval: z.boolean().default(true),
+    newMailPopup: z.boolean().default(true),
     trustedRecipientsYaml: z.string().default(''),
     maxBodyChars: z.number().default(20000),
     downloadDir: z.string().default(''),
@@ -41,6 +42,7 @@ export function toSettingsBase(config) {
         ...(config.password !== undefined && config.password !== '' ? { password: config.password } : {}),
         ...(config.inboxFolder !== undefined && config.inboxFolder !== '' ? { inboxFolder: config.inboxFolder } : {}),
         ...(config.sendApproval !== undefined ? { sendApproval: config.sendApproval } : {}),
+        ...(config.newMailPopup !== undefined ? { newMailPopup: config.newMailPopup } : {}),
         ...(config.trustedRecipientsYaml !== undefined ? { trustedRecipientsYaml: config.trustedRecipientsYaml } : {}),
         ...(config.maxBodyChars !== undefined ? { maxBodyChars: config.maxBodyChars } : {}),
         ...(config.downloadDir !== undefined && config.downloadDir !== '' ? { downloadDir: config.downloadDir } : {}),
@@ -203,6 +205,9 @@ function describeValue(value) {
  */
 export function validateSettingsValue(value, extraProviders = []) {
     const draft = (value ?? {});
+    if (draft.newMailPopup !== undefined && typeof draft.newMailPopup !== 'boolean') {
+        throw new Error('新邮件弹窗开关必须为布尔值');
+    }
     if (draft.trustedRecipientsYaml !== undefined) {
         if (typeof draft.trustedRecipientsYaml !== 'string')
             throw new Error('可信收件人规则必须为文本');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-email",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "在 DSH 中收发、搜索和整理邮件，支持多个邮箱账号。",
   "type": "module",
   "main": "lib/index.js",