dsh-email 0.8.2 → 0.9.1

package/README.en.md

@@ -20,6 +20,13 @@ Pure Node, **cross-platform** (one codebase for Windows / macOS / Linux), no she
 | `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_folders` | List the mailbox folders (INBOX/Sent/Junk/custom…); feed the `path` to other tools |
 | `email_attachment` | Download an attachment by index (saved to the session workspace by default so the model can read it directly; size capped by `maxAttachmentBytes`) |
+| `email_watch` | Incremental new-mail check: the first call seeds a baseline, every later call reports only unread mail newer than the last check — ideal for scheduled new-mail notifications |
+
+### 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.
+
+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:
 
@@ -27,6 +34,7 @@ Example:
 
 ### Changelog
 
+- **0.9.0**: new `email_watch` incremental new-mail tool (cursor-based, ideal for scheduled notifications); new "whale-girl courier" new-mail popup in the web UI (local skin artwork read at runtime + built-in fallback).
 - **0.8.2**: `since` / `until` parameter descriptions unified to English, consistent with the other parameters, so multilingual agents read them correctly.
 - **0.8.0/0.8.1**: `email_list` / `email_search` gained `since` / `until` date-range filters; new `email_health` self-check (account/connection/config in one call); adapted to harness 0.1.2 (removed the deleted client-injection declaration).
 - **0.6.2**: server-side search covers `cc` (subject / sender / recipients / CC); the body fallback scan also matches `to` / `cc` and one malformed message no longer aborts the batch; lists are UID-descending (newest first); `email_send` strictly validates attachment paths.
@@ -34,7 +42,7 @@ Example:
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.2-alpha.2` on 2026-08-31. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified against `@deepseek-ai/dsh@0.1.2-alpha.3` on 2026-09-01 (settings page / asset route / email_watch fully regression-tested). Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 

package/README.md

@@ -28,6 +28,13 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 | `email_send` | 代发邮件（支持带附件）。**默认发信前会弹确认**，显示收件人、主题和附件数，由你批准后才发出 |
 | `email_folders` | 列出邮箱的文件夹（INBOX/已发送/垃圾邮件/自定义…），拿 path 喂给其他工具 |
 | `email_attachment` | 按序号下载邮件附件（默认存到会话工作区，模型可直接读取；大小受 maxAttachmentBytes 限制） |
+| `email_watch` | 增量检查新邮件：首次调用建立基线，之后每次只报告比上次多出来的未读邮件，适合定时任务做新邮件提醒 |
+
+### 新邮件提醒（Web 端）
+
+配置好账号后，主界面右下角会出现「鲸鱼娘递信」小弹窗：每 30 秒检查一次新邮件，有新邮件时弹出卡片（发件人 + 主题），12 秒自动消失。弹窗与 `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，会立即移除）。
 
 示例对话：
 
@@ -35,6 +42,8 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 
 ### 版本记录
 
+- **0.9.1**：修复设置页空主机遮蔽 provider 预设（#3/#6）；IMAP 连接超时不再杀死整个 DSH 进程（#4）；暗色模式输入控件可见（#2）；密码栏提示环境变量 `DSH_EMAIL_PASSWORD` 免明文方案（#5）。
+- **0.9.0**：新增 `email_watch` 增量新邮件检查工具（游标式，适合定时提醒）；Web 端新增「鲸鱼娘递信」新邮件弹窗（本地皮肤素材运行时读取 + 内置回退图）。
 - **0.8.2**：`since` / `until` 参数描述与其余参数统一为英文，方便多语言 agent 理解。
 - **0.8.0/0.8.1**：`email_list` / `email_search` 新增 `since` / `until` 日期范围过滤；新增 `email_health` 自检（账号/连接/配置一键体检）；适配 harness 0.1.2（清理已删除的客户端注入声明）。
 - **0.6.2**：服务器端搜索补齐 `cc`，搜索范围真正覆盖主题 / 发件人 / 收件人 / 抄送；正文回退扫描也匹配 `to` / `cc`，单封解析失败不中断整批；列表强制 UID 降序「最新在前」；`email_send` 附件参数严格校验。
@@ -42,7 +51,7 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+在 `@deepseek-ai/dsh@0.1.2-alpha.3` 上实测通过（2026-09-01，设置页/素材路由/email_watch 全回归）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -181,4 +190,4 @@ MIT。这是一个社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*`
 
 - [dsh-slack](https://github.com/STARDUSTLC666/dsh-slack) — Slack 通知/收件箱
 - [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）
-- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件六件套 + Web 设置页
+- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件八件套 + Web 设置页 + 新邮件弹窗

package/lib/client.js

@@ -51,7 +51,7 @@ const EMPTY = {
 };
 
 const CSS = [
-  ".dshe-settings{display:grid;gap:14px;max-width:900px;padding:8px 2px 32px;color:var(--dsw-alias-fg-primary,#26231f)}",
+  ".dshe-settings{display:grid;gap:14px;max-width:900px;padding:8px 2px 32px;color:var(--dsw-alias-fg-primary,#26231f);color-scheme:light dark}",
   ".dshe-header{display:grid;gap:4px;padding:8px 2px}",
   ".dshe-header h2{font-size:22px;letter-spacing:-.02em;margin:0}",
   ".dshe-header p{max-width:640px;margin:4px 0 0;color:var(--dsw-alias-fg-muted,#77736d);font-size:13px;line-height:1.55}",
@@ -60,7 +60,8 @@ const CSS = [
   ".dshe-grid{display:grid;grid-template-columns:1fr 1fr;gap:12px}",
   ".dshe-field{display:grid;gap:6px}",
   ".dshe-field label{font-size:12px;font-weight:600;color:var(--dsw-alias-fg-primary,#26231f)}",
-  ".dshe-field input[type=text],.dshe-field input[type=password],.dshe-field input[type=number],.dshe-field select{width:100%;box-sizing:border-box;padding:8px 10px;border:1px solid var(--dsw-alias-border-subtle,#dedbd5);border-radius:9px;background:var(--dsw-alias-bg-layer-1,#fff);color:inherit;font:inherit;font-size:13px}",
+  ".dshe-field input[type=text],.dshe-field input[type=password],.dshe-field input[type=number],.dshe-field select,.dshe-field textarea{width:100%;box-sizing:border-box;padding:8px 10px;border:1px solid var(--dsw-alias-border-subtle,#dedbd5);border-radius:9px;background:var(--dsw-alias-bg-layer-1,#fff);color:var(--dsw-alias-fg-primary,#26231f);font:inherit;font-size:13px}",
+  ".dshe-field select option{background:var(--dsw-alias-bg-layer-1,#fff);color:var(--dsw-alias-fg-primary,#26231f)}",
   ".dshe-check{display:flex;gap:8px;align-items:center;font-size:13px}",
   ".dshe-actions{display:flex;gap:8px;flex-wrap:wrap}",
   ".dshe-btn{display:inline-flex;align-items:center;height:32px;padding:0 14px;border-radius:999px;border:1px solid var(--dsw-alias-border-subtle,#dedbd5);background:var(--dsw-alias-bg-layer-1,#fff);color:inherit;font-size:13px;font-weight:600;cursor:pointer}",
@@ -72,6 +73,15 @@ const CSS = [
   ".dshe-alert.info{background:rgba(11,108,159,.08);color:#0b5c86}",
   ".dshe-details summary{font-size:12px;font-weight:600;cursor:pointer;color:var(--dsw-alias-fg-muted,#77736d)}",
   ".dshe-hint{font-size:12px;color:var(--dsw-alias-fg-muted,#77736d);line-height:1.5}",
+  ".dshe-whale-root{position:fixed;right:20px;bottom:20px;z-index:2147483000;pointer-events:none}",
+  ".dshe-whale-card{pointer-events:auto;position:relative;width:300px;border:1px solid var(--dsw-alias-border-subtle,#dedbd5);border-radius:14px;background:var(--dsw-alias-bg-layer-1,#fff);box-shadow:0 10px 30px rgba(0,0,0,.18);overflow:hidden;animation:dshe-whale-in .35s ease-out;font-size:13px;color:var(--dsw-alias-fg-primary,#26231f);color-scheme:light dark}",
+  "@keyframes dshe-whale-in{from{opacity:0;transform:translateY(14px)}to{opacity:1;transform:translateY(0)}}",
+  ".dshe-whale-img{display:block;width:100%;height:120px;object-fit:cover;object-position:center top;background:#eaf3f8}",
+  ".dshe-whale-body{padding:10px 12px 12px;display:grid;gap:6px}",
+  ".dshe-whale-title{font-weight:700;font-size:13px}",
+  ".dshe-whale-item{color:var(--dsw-alias-fg-muted,#77736d);font-size:12px;line-height:1.45;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}",
+  ".dshe-whale-credit{font-size:10px;color:var(--dsw-alias-fg-muted,#77736d);opacity:.8;line-height:1.4}",
+  ".dshe-whale-close{position:absolute;top:6px;right:6px;width:22px;height:22px;border-radius:50%;border:none;background:rgba(0,0,0,.35);color:#fff;cursor:pointer;font-size:12px;line-height:1}",
 ].join("\n");
 
 function fieldInput(type, value, onChange, placeholder) {
@@ -210,6 +220,7 @@ function EmailSettingsSection() {
             placeholder: "不是登录密码；QQ/163 在邮箱设置里生成授权码",
             onChange: (e) => update({ password: e.target.value }),
           }),
+          h("div", { className: "dshe-hint" }, "不想明文保存？此栏留空，改用环境变量 DSH_EMAIL_PASSWORD（仅单账号时生效）。"),
         ]),
         h("div", { className: "dshe-field" }, [
           h("label", null, "收件文件夹（默认 INBOX）"),
@@ -296,6 +307,99 @@ function EmailSettingsSection() {
   ]);
 }
 
+// Whale-girl courier popup: polls the same-origin watch route every 30s.
+// The first poll seeds the baseline silently; later polls pop a card only
+// 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).
+function startWhaleWidget() {
+  if (document.querySelector("#dsh-email-whale-root")) return () => {};
+  const root = document.createElement("div");
+  root.id = "dsh-email-whale-root";
+  root.className = "dshe-whale-root";
+  document.body.appendChild(root);
+  let pollTimer = 0;
+  let hideTimer = 0;
+  let whaleUrl = "";
+  let whaleCredit = "";
+
+  const closePopup = () => {
+    if (hideTimer) { clearTimeout(hideTimer); hideTimer = 0; }
+    root.replaceChildren();
+  };
+
+  const showPopup = (value) => {
+    closePopup();
+    const card = document.createElement("div");
+    card.className = "dshe-whale-card";
+    if (whaleUrl) {
+      const img = document.createElement("img");
+      img.className = "dshe-whale-img";
+      img.src = whaleUrl;
+      img.alt = "";
+      img.onerror = () => { img.remove(); };
+      card.appendChild(img);
+    }
+    const body = document.createElement("div");
+    body.className = "dshe-whale-body";
+    const title = document.createElement("div");
+    title.className = "dshe-whale-title";
+    title.textContent = "鲸鱼娘递信：有 " + value.newCount + " 封新邮件";
+    body.appendChild(title);
+    (value.messages || []).slice(0, 3).forEach((m) => {
+      const row = document.createElement("div");
+      row.className = "dshe-whale-item";
+      const who = (m.from || []).map((a) => a.name || a.address).filter(Boolean).join(", ") || "(未知)";
+      row.textContent = who + " · " + (m.subject || "(无主题)");
+      body.appendChild(row);
+    });
+    if (value.newCount > 3) {
+      const more = document.createElement("div");
+      more.className = "dshe-whale-item";
+      more.textContent = "…其余 " + (value.newCount - 3) + " 封，用 email_watch / email_read 查看";
+      body.appendChild(more);
+    }
+    if (whaleCredit) {
+      const credit = document.createElement("div");
+      credit.className = "dshe-whale-credit";
+      credit.textContent = whaleCredit;
+      body.appendChild(credit);
+    }
+    card.appendChild(body);
+    const closeBtn = document.createElement("button");
+    closeBtn.className = "dshe-whale-close";
+    closeBtn.textContent = "\u2715";
+    closeBtn.setAttribute("aria-label", "关闭");
+    closeBtn.onclick = closePopup;
+    card.appendChild(closeBtn);
+    root.appendChild(card);
+    hideTimer = setTimeout(closePopup, 12000);
+  };
+
+  const tick = async () => {
+    try {
+      const snap = await api();
+      if (snap && snap.whale) {
+        whaleUrl = snap.whale.url || "";
+        whaleCredit = snap.whale.credit || "";
+      }
+      if (!snap || !snap.accounts || snap.accounts.length === 0) return;
+      const value = await api("watch", { limit: 5 });
+      if (value && value.newCount > 0) showPopup(value);
+    } catch (e) {
+      // Not configured or transient error: stay silent, retry next tick.
+    }
+  };
+
+  tick();
+  pollTimer = setInterval(tick, 30000);
+  return () => {
+    clearInterval(pollTimer);
+    if (hideTimer) clearTimeout(hideTimer);
+    root.remove();
+  };
+}
+
 const inject = ["slots"];
 
 function apply(ctx) {
@@ -310,6 +414,8 @@ function apply(ctx) {
     return () => { style.remove(); };
   }, "dsh-email: styles");
 
+  ctx.effect(() => startWhaleWidget(), "dsh-email: whale courier");
+
   ctx.slots.inject("settings.section", () => ctx.slots.register({
     name: "settings.section",
     id: "dsh-email",

package/lib/index.js

@@ -246,7 +246,8 @@ export function apply(ctx, config = {}) {
         pool?.dispose();
         pool = null;
     });
-    installEmailSettingsWeb(ctx, new EmailSettingsBackend(ctx, settingsScope, config));
+    const backend = new EmailSettingsBackend(ctx, settingsScope, config);
+    installEmailSettingsWeb(ctx, backend);
     ctx.tools.register({
         name: 'email_list',
         description: '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.',
@@ -417,6 +418,75 @@ export function apply(ctx, config = {}) {
             return await getPool().downloadAttachment(args.account, args.folder?.trim() || '', args.uid, index, workspaceHint);
         },
     });
+    // Incremental watch: per scope+account+folder we remember the highest uid
+    // already reported. The first call seeds the baseline (firstRun=true,
+    // nothing counts as new), later calls report only unseen unread messages.
+    // The 'tool' and 'web' scopes keep independent cursors, so the browser
+    // popup and the email_watch tool never consume each other's new mail. The
+    // same core is exposed to the browser widget via action: watch.
+    const watchCursors = new Map();
+    const watchCore = async (account, folder, limit, scope) => {
+        const capped = clampInt(limit, 20, 1, MAX_LIMIT);
+        const result = await getPool().list(account, folder, MAX_LIMIT, 0, true);
+        const key = scope + '\u0000' + result.account + '\u0000' + result.folder;
+        const isFirst = !watchCursors.has(key);
+        const cursor = watchCursors.get(key) ?? 0;
+        const fresh = result.messages.filter(m => m.uid > cursor);
+        if (result.messages.length > 0) {
+            watchCursors.set(key, Math.max(cursor, ...result.messages.map(m => m.uid)));
+        }
+        else if (isFirst) {
+            watchCursors.set(key, 0);
+        }
+        return {
+            account: result.account,
+            folder: result.folder,
+            firstRun: isFirst,
+            newCount: isFirst ? 0 : fresh.length,
+            messages: (isFirst ? [] : fresh).slice(0, capped),
+            totalUnread: result.count,
+        };
+    };
+    backend.watchImpl = watchCore;
+    function renderWatch(value) {
+        if (value.firstRun) {
+            return oneText('账号 ' + value.account + '：已建立新邮件监视基线（当前未读 ' + value.totalUnread + ' 封）。之后调用 email_watch 只会报告新到的邮件。');
+        }
+        if (value.newCount === 0) {
+            return oneText('账号 ' + value.account + '：没有新邮件（当前未读 ' + value.totalUnread + ' 封）。');
+        }
+        const lines = value.messages.map((m, i) => '#' + (i + 1) + ' ' + describeMessage(m));
+        return oneText('账号 ' + value.account + ' 有 ' + value.newCount + ' 封新邮件：\n\n' + lines.join('\n') + '\n\n用 email_read 配合 uid 阅读全文。');
+    }
+    ctx.tools.register({
+        name: 'email_watch',
+        description: 'Check for NEW unread emails since the last check (cursor-based). The first call per account+folder sets the baseline and reports nothing as new; every later call returns only unseen unread messages. Call this periodically (e.g. via a scheduled task) to notify the user about new mail. Returns newCount, the new messages, and totalUnread.',
+        parameters: compileParameters({
+            folder: { type: 'string', description: 'IMAP folder path (see email_folders); defaults to the account inboxFolder' },
+            limit: { type: 'integer', description: 'Max number of new messages to return, 1-100, default 20' },
+            account: { type: 'string', description: ACCOUNT_HINT },
+        }),
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    account: { type: 'string' },
+                    folder: { type: 'string' },
+                    firstRun: { type: 'boolean' },
+                    newCount: { type: 'integer' },
+                    totalUnread: { type: 'integer' },
+                    messages: { type: 'array', items: { type: 'object', properties: messageShape, additionalProperties: true } },
+                },
+                additionalProperties: true,
+            },
+            render: (_args, value) => renderWatch(value),
+        },
+        async execute(rawArgs) {
+            const args = rawArgs;
+            const limit = clampInt(args.limit, 20, 1, MAX_LIMIT);
+            return await watchCore(args.account?.trim() || '', args.folder?.trim() || '', limit, 'tool');
+        },
+    });
     // Approval gate: the user must confirm every send (recipient + subject).
     // Runs before other listeners; degrades to the tool-time failure only
     // when the account itself is not configured yet.

package/lib/mail-client.js

@@ -120,7 +120,7 @@ export class EmailPool {
         return this.enqueue(name, () => this.imapRun(name, cfg, folder, run));
     }
     createImap(cfg) {
-        return new ImapFlow({
+        const client = new ImapFlow({
             host: cfg.imap.host,
             port: cfg.imap.port,
             secure: cfg.imap.secure,
@@ -130,6 +130,19 @@ export class EmailPool {
             greetingTimeout: 30000,
             socketTimeout: cfg.imap.socketTimeoutMs ?? 60000,
         });
+        // ImapFlow emits 'error' on socket timeouts/drops; without a listener Node
+        // escalates it to an uncaught exception and kills the whole DSH process
+        // (issue #4). Swallow it here and reap the dead connection when idle —
+        // in-flight calls fail through their own promise paths instead.
+        client.on('error', () => {
+            for (const [name, entry] of this.imaps) {
+                if (entry.client === client && entry.inUse === 0) {
+                    void this.evictImap(name);
+                    return;
+                }
+            }
+        });
+        return client;
     }
     async imapRun(name, cfg, folder, run) {
         let entry = this.imaps.get(name);

package/lib/settings.js

@@ -83,7 +83,9 @@ export function toEmailConfig(value, user) {
     if (user === null || user?.imap !== undefined) {
         const fields = user === null ? value.imap : (user.imap ?? {});
         const imap = {};
-        if (fields.host !== undefined)
+        // Empty host means "use the provider preset" — never project it, or the
+        // preset gets shadowed by '' (issues #3 / #6).
+        if (fields.host !== undefined && value.imap.host !== '')
             imap.host = value.imap.host;
         if (fields.port !== undefined)
             imap.port = value.imap.port;
@@ -94,7 +96,7 @@ export function toEmailConfig(value, user) {
     if (user === null || user?.smtp !== undefined) {
         const fields = user === null ? value.smtp : (user.smtp ?? {});
         const smtp = {};
-        if (fields.host !== undefined)
+        if (fields.host !== undefined && value.smtp.host !== '')
             smtp.host = value.smtp.host;
         if (fields.port !== undefined)
             smtp.port = value.smtp.port;

package/lib/types.d.ts

@@ -119,3 +119,19 @@ export interface EmailAttachmentArgs extends AccountArg {
     index?: number;
     folder?: string;
 }
+export interface EmailWatchArgs extends AccountArg {
+    folder?: string;
+    /** Max number of new messages to return per call, default 20. */
+    limit?: number;
+}
+export interface EmailWatchResult {
+    account: string;
+    folder: string;
+    /** True on the first call for this account+folder: it sets the baseline. */
+    firstRun: boolean;
+    /** Unread messages never reported before (empty on firstRun). */
+    newCount: number;
+    messages: ListedMessage[];
+    /** Total unread in the folder right now. */
+    totalUnread: number;
+}

package/lib/web.d.ts

@@ -1,7 +1,10 @@
 import { type EmailSettingsValue } from './settings.js';
 import { type EmailConfig } from './config.js';
+import type { EmailWatchResult } from './types.js';
 /** Same-origin route the browser settings section talks to. */
 export declare const SETTINGS_ROUTE = "/_dsh/dsh-email/settings";
+/** Same-origin route serving the whale-girl courier image to the widget. */
+export declare const WHALE_ASSET_ROUTE = "/_dsh/dsh-email/assets/whale";
 /**
  * Browser-facing backend: snapshot the settings namespace, save it with
  * optimistic concurrency, and test a draft account over a live IMAP login.
@@ -11,6 +14,8 @@ export declare class EmailSettingsBackend {
     private readonly scope;
     private readonly rowConfig;
     constructor(ctx: any, scope: any, rowConfig: EmailConfig);
+    /** Wired by apply(): the email_watch core; 'web' keeps its own cursor scope. */
+    watchImpl?: (account: string, folder: string, limit: number, scope: string) => Promise<EmailWatchResult>;
     private userSection;
     /** Effective config for the stored value (row + user-set fields only). */
     private effectiveStored;
@@ -22,6 +27,11 @@ export declare class EmailSettingsBackend {
         };
         writable: boolean;
         accounts: string[];
+        whale: {
+            url: string;
+            skin: boolean;
+            credit: string;
+        };
     }>;
     private effectiveAccounts;
     save(value: EmailSettingsValue, expectedRevision: number): Promise<{
@@ -32,6 +42,11 @@ export declare class EmailSettingsBackend {
         };
         writable: boolean;
         accounts: string[];
+        whale: {
+            url: string;
+            skin: boolean;
+            credit: string;
+        };
     }>;
     test(value: EmailSettingsValue): Promise<{
         ok: boolean;
@@ -39,6 +54,8 @@ export declare class EmailSettingsBackend {
     }>;
     responseJson(res: any, status: number, body: unknown): void;
     handle(req: any, res: any): Promise<void>;
+    /** GET-only localhost route serving the whale-girl courier image. */
+    handleAsset(req: any, res: any): void;
 }
-/** Mount the same-origin route when a webServer service is present. */
+/** Mount the same-origin routes when a webServer service is present. */
 export declare function installEmailSettingsWeb(ctx: any, backend: EmailSettingsBackend): void;

package/lib/web.js

@@ -1,8 +1,74 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { SETTINGS_NAMESPACE, toEmailConfig, validateSettingsValue } from './settings.js';
 import { resolveEmailSettings } from './config.js';
 import { EmailPool, messageOf } from './mail-client.js';
 /** Same-origin route the browser settings section talks to. */
 export const SETTINGS_ROUTE = '/_dsh/dsh-email/settings';
+/** Same-origin route serving the whale-girl courier image to the widget. */
+export const WHALE_ASSET_ROUTE = '/_dsh/dsh-email/assets/whale';
+const SKIN_PACKAGES = [
+    '@dsh-external/dsh-client-ui-skin-orca-link',
+    '@dsh-external/dsh-client-ui-skin-maid-atelier',
+];
+const WHALE_CREDIT = '鲸鱼娘：一创 上善（pixiv 62155430）· 二创 Small-tailqwq / dsh-deep-whale · CC BY-NC-SA 4.0（非商业）';
+/** Credit shown with the bundled fallback artwork (community fan character). */
+const FALLBACK_CREDIT = '鲸鱼娘：社区同人形象，版权归原作者，仅供个人非商业使用；如有异议请提 Issue 移除';
+let whaleCache;
+function pickFromDir(dir) {
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const images = names.filter(name => /\.(webp|png|jpe?g)$/i.test(name));
+    if (images.length === 0)
+        return null;
+    const preferred = images.find(name => /^light-hero/i.test(name)) ?? images.find(name => /^light-active/i.test(name));
+    return join(dir, preferred ?? images[0]);
+}
+function contentTypeOf(file) {
+    if (/\.webp$/i.test(file))
+        return 'image/webp';
+    if (/\.jpe?g$/i.test(file))
+        return 'image/jpeg';
+    return 'image/png';
+}
+/**
+ * Locate the whale-girl artwork at runtime. Skin art is never bundled: it is
+ * CC BY-NC-SA 4.0, so dsh-email only serves it from the user's own installed
+ * dsh-deep-whale skin package (with the attribution chain shown in the
+ * widget). Without the skin, a bundled community whale-girl artwork is
+ * served with its own credit line (copyright stays with the original author;
+ * personal non-commercial use, removed on request via issue).
+ */
+function findWhaleAsset() {
+    if (whaleCache !== undefined)
+        return whaleCache;
+    whaleCache = null;
+    const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const roots = [process.cwd(), dirname(packageDir)];
+    for (const root of roots) {
+        for (const pkg of SKIN_PACKAGES) {
+            for (const base of [join(root, 'node_modules', pkg, 'assets'), join(root, pkg, 'assets')]) {
+                const file = pickFromDir(base);
+                if (file !== null) {
+                    whaleCache = { file, contentType: contentTypeOf(file), skin: true, credit: WHALE_CREDIT };
+                    return whaleCache;
+                }
+            }
+        }
+    }
+    const fallback = join(packageDir, 'assets', 'whale-fallback.png');
+    if (existsSync(fallback)) {
+        whaleCache = { file: fallback, contentType: 'image/png', skin: false, credit: FALLBACK_CREDIT };
+        return whaleCache;
+    }
+    return whaleCache;
+}
 /**
  * Browser-facing backend: snapshot the settings namespace, save it with
  * optimistic concurrency, and test a draft account over a live IMAP login.
@@ -16,6 +82,8 @@ export class EmailSettingsBackend {
         this.scope = scope;
         this.rowConfig = rowConfig;
     }
+    /** Wired by apply(): the email_watch core; 'web' keeps its own cursor scope. */
+    watchImpl;
     userSection() {
         const descriptor = (this.ctx.settings.describe?.() ?? []).find((row) => row.ns === SETTINGS_NAMESPACE);
         return descriptor?.user;
@@ -27,6 +95,7 @@ export class EmailSettingsBackend {
     async snapshot() {
         const descriptor = (this.ctx.settings.describe?.() ?? []).find((row) => row.ns === SETTINGS_NAMESPACE);
         const value = this.scope.get();
+        const whale = findWhaleAsset();
         return {
             settings: {
                 value,
@@ -35,6 +104,9 @@ export class EmailSettingsBackend {
             },
             writable: this.ctx.settings.writable !== false,
             accounts: [...(this.effectiveAccounts().keys())],
+            whale: whale === null
+                ? { url: '', skin: false, credit: '' }
+                : { url: WHALE_ASSET_ROUTE, skin: whale.skin, credit: whale.credit },
         };
     }
     effectiveAccounts() {
@@ -62,6 +134,16 @@ export class EmailSettingsBackend {
             await pool.withImap(settings.defaultAccount, null, async () => 'connected');
             return { ok: true, ms: Date.now() - started };
         }
+        catch (error) {
+            // imapflow reports failed LOGIN as a bare "Command failed"; surface an
+            // actionable hint instead of the opaque message.
+            const raw = messageOf(error, 'unknown error');
+            const lower = raw.toLowerCase();
+            if (lower.includes('command failed') || lower.includes('authentication') || lower.includes('login')) {
+                throw new Error('邮箱登录失败：请检查邮箱地址与授权码（' + raw + '）');
+            }
+            throw error;
+        }
         finally {
             pool.dispose();
         }
@@ -121,6 +203,14 @@ export class EmailSettingsBackend {
             else if (body?.action === 'test') {
                 this.responseJson(res, 200, { ok: true, value: await this.test(body.value) });
             }
+            else if (body?.action === 'watch') {
+                if (typeof this.watchImpl !== 'function')
+                    throw new Error('email_watch 未就绪');
+                const account = typeof body.account === 'string' ? body.account : '';
+                const folder = typeof body.folder === 'string' ? body.folder : '';
+                const limit = Number.isSafeInteger(body.limit) ? body.limit : 5;
+                this.responseJson(res, 200, { ok: true, value: await this.watchImpl(account, folder, limit, 'web') });
+            }
             else {
                 this.responseJson(res, 400, { ok: false, error: { code: 'invalid-request', message: 'unsupported action' } });
             }
@@ -133,8 +223,39 @@ export class EmailSettingsBackend {
             });
         }
     }
+    /** GET-only localhost route serving the whale-girl courier image. */
+    handleAsset(req, res) {
+        const remote = String(req.socket?.remoteAddress ?? '');
+        if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') {
+            this.responseJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'dsh-email asset route is localhost-only' } });
+            return;
+        }
+        if (req.method !== 'GET') {
+            res.setHeader('Allow', 'GET');
+            this.responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET' } });
+            return;
+        }
+        const asset = findWhaleAsset();
+        if (asset === null) {
+            this.responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'no whale asset available' } });
+            return;
+        }
+        try {
+            const bytes = readFileSync(asset.file);
+            res.setHeader('Content-Type', asset.contentType);
+            res.setHeader('Content-Length', String(bytes.length));
+            res.setHeader('Cache-Control', 'no-store');
+            // No credit header: HTTP header values must be latin-1, and the widget
+            // already shows the credit from the snapshot JSON.
+            res.writeHead(200);
+            res.end(bytes);
+        }
+        catch (error) {
+            this.responseJson(res, 503, { ok: false, error: { code: 'unavailable', message: messageOf(error, 'unknown error') } });
+        }
+    }
 }
-/** Mount the same-origin route when a webServer service is present. */
+/** Mount the same-origin routes when a webServer service is present. */
 export function installEmailSettingsWeb(ctx, backend) {
     ctx.inject(['webServer'], (webCtx) => {
         webCtx.effect(() => {
@@ -143,7 +264,15 @@ export function installEmailSettingsWeb(ctx, backend) {
                 path: SETTINGS_ROUTE,
                 handler: (req, res) => backend.handle(req, res),
             });
-            return () => dispose();
-        }, 'dsh-email: web route');
+            const disposeAsset = webCtx.webServer.register({
+                kind: 'exact',
+                path: WHALE_ASSET_ROUTE,
+                handler: (req, res) => backend.handleAsset(req, res),
+            });
+            return () => {
+                dispose();
+                disposeAsset();
+            };
+        }, 'dsh-email: web routes');
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-email",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "IMAP/SMTP email tools for DeepSeek Harness: list, read, search and send mail, with QQ/163/126/Sina/Aliyun/Gmail/Outlook/iCloud presets.",
   "type": "module",
   "main": "lib/index.js",
@@ -16,6 +16,7 @@
   },
   "files": [
     "lib",
+    "assets/whale-fallback.png",
     "cordis.patch.yml",
     "README.md"
   ],