dsh-email 0.11.0 → 0.13.0

package/lib/tool-contract.js

@@ -195,11 +195,24 @@ export function renderRead(value) {
     return oneText('账号 ' + value.account + '，主题：' + (value.subject || '(无主题)') + '\n来自：' + from + '\n时间：' + (value.date || '(未知)') + attach + '\n\n' + value.text);
 }
 export function renderSearch(value) {
+    const scanned = value.countKind === 'scanned';
+    // 回退扫描只看了最近 scannedLimit 封，不知道全文件夹匹配数：不能把本页条数说成「共 N 条」。
+    const scannedNote = '仅扫描最近 ' + (value.scannedLimit ?? 0) + ' 封，未统计全文件夹匹配数';
     if (value.messages.length === 0) {
+        if (scanned) {
+            return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：本页没有匹配（' + scannedNote + '）。');
+        }
         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 + ' 条';
+    const summary = scanned
+        ? '本页 ' + value.messages.length + ' 条（' + scannedNote + '）' + (offset > 0 ? '，已被 offset 跳过最新 ' + offset + ' 条' : '')
+        : '共 ' + value.count + ' 条匹配，' + window;
+    return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：' + summary + '：\n\n' + lines.join('\n'));
 }
 export function renderSend(value) {
     const rejected = value.rejected.length > 0 ? '；被拒：' + value.rejected.join(', ') : '';
@@ -229,6 +242,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 +285,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 +296,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 +330,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.d.ts

@@ -9,5 +9,6 @@ export interface EmailToolDefinition {
         render(args: unknown, value: unknown): TextBlock[];
     };
     execute(args: unknown, exec?: unknown): Promise<unknown>;
+    timeoutMs?: number;
 }
 export declare function buildEmailTools(runtime: Pick<EmailRuntime, 'getPool' | 'getEffectiveSettings' | 'watch'>): EmailToolDefinition[];

package/lib/tools.js

@@ -2,6 +2,9 @@ import { clampInt, PROVIDER_PRESETS } from './config.js';
 import { messageOf } from './mail-client.js';
 import { NOT_LOGGED_IN_MESSAGE, oauth2StateOf } from './oauth2.js';
 import { descriptions, parameters, MAX_LIMIT, MARK_ACTIONS, REPLY_MODES, executionSignal, normalizeAttachmentPaths, parseEmailDay, attachmentSchema, foldersSchema, listSchema, markSchema, readSchema, replySchema, sendSchema, watchSchema, renderAttachment, renderFolders, renderHealth, renderList, renderMark, renderRead, renderReply, renderSearch, renderSend, renderWatch, } from './tool-contract.js';
+/** 单次工具调用的 deadline：普通查询 60s，正文扫描/watch 这类整批操作 120s。 */
+const QUERY_TIMEOUT_MS = 60000;
+const BATCH_TIMEOUT_MS = 120000;
 export function buildEmailTools(runtime) {
     const { getPool, getEffectiveSettings, watch: watchCore } = runtime;
     return [
@@ -13,6 +16,7 @@ export function buildEmailTools(runtime) {
                 schema: listSchema,
                 render: (_args, value) => renderList(value),
             },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 const limit = clampInt(args.limit, 20, 1, MAX_LIMIT);
@@ -30,6 +34,7 @@ export function buildEmailTools(runtime) {
                 schema: readSchema,
                 render: (_args, value) => renderRead(value),
             },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
@@ -46,6 +51,7 @@ export function buildEmailTools(runtime) {
                 schema: markSchema,
                 render: (_args, value) => renderMark(value),
             },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
@@ -69,14 +75,16 @@ export function buildEmailTools(runtime) {
                 schema: listSchema,
                 render: (_args, value) => renderSearch(value),
             },
+            timeoutMs: BATCH_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 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));
             }
         },
         {
@@ -87,6 +95,7 @@ export function buildEmailTools(runtime) {
                 schema: sendSchema,
                 render: (_args, value) => renderSend(value),
             },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 if (typeof args.to !== 'string' || args.to.trim() === '')
@@ -101,6 +110,7 @@ export function buildEmailTools(runtime) {
             description: descriptions.email_reply,
             parameters: parameters.email_reply,
             output: { schema: replySchema, render: (_args, value) => renderReply(value) },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
@@ -127,6 +137,7 @@ export function buildEmailTools(runtime) {
                 schema: foldersSchema,
                 render: (_args, value) => renderFolders(value),
             },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 return await getPool().folders(args.account, args.subscribedOnly === true, executionSignal(exec));
@@ -137,6 +148,7 @@ export function buildEmailTools(runtime) {
             description: descriptions.email_health,
             parameters: parameters.email_health,
             output: { schema: { type: 'object', additionalProperties: true }, render: renderHealth },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(_rawArgs, exec) {
                 executionSignal(exec)?.throwIfAborted();
                 const checks = [];
@@ -181,6 +193,7 @@ export function buildEmailTools(runtime) {
                 schema: attachmentSchema,
                 render: (_args, value) => renderAttachment(value),
             },
+            timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
@@ -196,6 +209,7 @@ export function buildEmailTools(runtime) {
             description: descriptions.email_watch,
             parameters: parameters.email_watch,
             output: { schema: watchSchema, render: (_args, value) => renderWatch(value) },
+            timeoutMs: BATCH_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
                 const limit = clampInt(args.limit, 20, 1, MAX_LIMIT);

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 {
@@ -49,9 +51,16 @@ export interface EmailReadResult extends ReadMessageBody {
 export interface EmailSearchResult {
     account: string;
     query: string;
+    /** Server path: the server's match count. Fallback scan: this page's row count (see countKind). */
     count: number;
     folder: string;
+    /** How many newest matches the caller skipped (0 on the first page). */
+    offset: number;
     messages: ListedMessage[];
+    /** Set to 'scanned' when the local body scan produced this page, so count is not a total. */
+    countKind?: 'scanned';
+    /** How many newest messages the fallback scan looked at (set with countKind='scanned'). */
+    scannedLimit?: number;
 }
 export interface EmailSendResult {
     account: string;
@@ -99,6 +108,7 @@ export interface EmailSearchArgs extends AccountArg {
     query: string;
     folder?: string;
     limit?: number;
+    offset?: number;
     since?: string;
     until?: string;
 }
@@ -175,6 +185,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,7 +1,7 @@
 {
   "name": "dsh-email",
-  "version": "0.11.0",
-  "description": "DeepSeek Harness 邮件插件：IMAP/SMTP 收发、搜索、回复转发、邮件整理与增量收件，支持多邮箱预设、发信审批及 Web 设置与新邮件通知。",
+  "version": "0.13.0",
+  "description": "DSH 邮件插件：IMAP/SMTP 收发搜索、回复转发、附件与整理，多账号卡片设置页 + Outlook OAuth2 + 发信审批。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -19,7 +19,8 @@
     "assets/whale-fallback.png",
     "cordis.patch.yml",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",