dsh-email 0.4.0 → 0.5.0

package/README.md

@@ -12,10 +12,10 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 |---|---|
 | `email_list` | 列出文件夹里最新的邮件（未读过滤、分页、只看摘要不带正文） |
 | `email_read` | 按 uid 读取一封邮件的全文（HTML 邮件自动转纯文本，超长截断） |
-| `email_search` | 按关键词搜索发件人/收件人/主题（服务器端 IMAP SEARCH，不搜正文） |
+| `email_search` | 按关键词搜索发件人/收件人/主题（服务器端）；无结果时默认回退到最近 30 封的正文扫描 |
 | `email_send` | 代发邮件（支持带附件）。**默认发信前会弹确认**，显示收件人、主题和附件数，由你批准后才发出 |
 | `email_folders` | 列出邮箱的文件夹（INBOX/已发送/垃圾邮件/自定义…），拿 path 喂给其他工具 |
-| `email_attachment` | 按序号下载邮件附件到本地文件（大小受 maxAttachmentBytes 限制） |
+| `email_attachment` | 按序号下载邮件附件（默认存到会话工作区，模型可直接读取；大小受 maxAttachmentBytes 限制） |
 
 示例对话：
 
@@ -103,9 +103,11 @@ dsh plugin --profile web add dsh-email
 | `maxBodyChars` | `20000` | email_read 正文截断上限（1000–200000） |
 | `accounts` | 无 | 具名账号表；账号级字段覆盖顶层简写 |
 | `defaultAccount` | 单账号时自动 | 工具省略 account 参数时使用的账号（多账号必填） |
-| `downloadDir` | `$DSH_HOME/email-downloads` | email_attachment 的落盘目录 |
+| `downloadDir` | 会话工作区下 .dsh-email-downloads（回退 $DSH_HOME/email-downloads） | email_attachment 的落盘目录；显式设置后固定 |
 | `maxAttachmentBytes` | 20 MiB | 单个附件与附件总大小上限（1024–512 MiB） |
-| `idleTimeoutMs` | `60000` | IMAP 空闲连接回收时间（连接复用，连续操作更快） |
+| `idleTimeoutMs` | `60000` | IMAP 空闲连接回收时间（连接复用，连续操作更快） |
+| `bodySearchFallback` | `true` | 服务器搜索无结果时，回退到客户端扫描最近邮件的正文 |
+| `bodySearchLimit` | `30` | 正文回退扫描的邮件数量（5-200） |
 
 ## 第一步：拿到授权码
 
@@ -129,7 +131,7 @@ dsh plugin --profile web add dsh-email
 - **多账号**：每个账号独立连接池；一个 `tool-email` 行可以配任意多个账号。设置页编辑的是默认账号；`accounts` 映射仍需写 cordis.patch.yml。
 - **附件下载**：email_attachment 按 email_read 的附件列表定位（先按文件名、再按类型+大小匹配到 IMAP 部件，定位失败会报错而不是下载错文件）；内嵌图片暂不支持下载；文件名会被清洗防路径穿越，已有同名文件自动加后缀，大小受 maxAttachmentBytes 限制。
 - **不支持 OAuth2**：强制 OAuth 的企业环境（部分 M365/Google Workspace）暂不可用。
-- 正文搜索不提供：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索要么全量匹配要么不支持，所以只搜主题/发件人/收件人；正文搜索列入后续版本（需客户端下载解析，较慢）。
+- 正文搜索走客户端回退：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索不可靠，所以服务器端只搜主题/发件人/收件人；无结果时回退到最近 `bodySearchLimit` 封的正文扫描（较慢，可关 `bodySearchFallback`）。
 - **密码落盘形式**：设置页保存的授权码以明文写在本机 `settings.yaml`（schema 标记 secret 只是保证它不进日志/导出/诊断，不做磁盘加密）。请勿把 settings.yaml 交给不信任的人。
 - **设置页与插件集变更**：设置页保存后工具**立即生效**（live），无需重启；但升级/增删插件（组合树变化）仍需重启 `dsh web`。
 
@@ -138,7 +140,7 @@ dsh plugin --profile web add dsh-email
 ```sh
 pnpm install
 pnpm run build   # tsc → lib/
-pnpm test        # 构建 + node --test（配置/解析/注册与审批门，37 个用例，无需真实邮箱）
+pnpm test        # 构建 + node --test（配置/解析/注册与审批门，40 个用例，无需真实邮箱）
 ```
 
 ## 协议

package/lib/config.d.ts

@@ -29,8 +29,12 @@ export interface EmailConfig extends AccountConfig {
     accounts?: Record<string, AccountConfig>;
     /** Which account tools use when the call omits account. Required with 2+ accounts. */
     defaultAccount?: string;
-    /** Directory email_attachment writes into. Default $DSH_HOME/email-downloads. */
+    /** Directory email_attachment writes into. Default: the session workspace's .dsh-email-downloads (falls back to $DSH_HOME/email-downloads). */
     downloadDir?: string;
+    /** Client-side body scan when server search finds nothing. Default true. */
+    bodySearchFallback?: boolean;
+    /** How many recent messages the body-search fallback parses. Default 30. */
+    bodySearchLimit?: number;
     /** Per-attachment and total-attachment byte cap. Default 20 MiB. */
     maxAttachmentBytes?: number;
     /** Unused IMAP connections close after this many ms. Default 60000. */
@@ -74,8 +78,12 @@ export interface ResolvedEmailSettings {
     sendApproval: boolean;
     maxBodyChars: number;
     downloadDir: string;
+    /** Whether downloadDir was set explicitly (vs. the default). */
+    downloadDirExplicit: boolean;
     maxAttachmentBytes: number;
     idleTimeoutMs: number;
+    bodySearchFallback: boolean;
+    bodySearchLimit: number;
 }
 export declare function defaultDownloadDir(): string;
 /**

package/lib/config.js

@@ -67,8 +67,11 @@ export function resolveEmailSettings(config) {
         sendApproval: raw.sendApproval !== false,
         maxBodyChars: clampInt(raw.maxBodyChars, 20000, 1000, 200000),
         downloadDir: raw.downloadDir?.trim() || defaultDownloadDir(),
+        downloadDirExplicit: (raw.downloadDir?.trim() ?? '') !== '',
         maxAttachmentBytes: clampInt(raw.maxAttachmentBytes, DEFAULT_MAX_ATTACHMENT_BYTES, 1024, 512 * 1024 * 1024),
         idleTimeoutMs: clampInt(raw.idleTimeoutMs, DEFAULT_IDLE_TIMEOUT_MS, 5000, 600000),
+        bodySearchFallback: raw.bodySearchFallback !== false,
+        bodySearchLimit: clampInt(raw.bodySearchLimit, 30, 5, 200),
     };
 }
 /** Merge one account over the shared shorthand and validate it. */

package/lib/index.d.ts

@@ -6,6 +6,6 @@ export declare function apply(ctx: any, config?: Config): void;
 export { PROVIDER_NAMES, EMAIL_PASSWORD_ENV } from './config.js';
 export { resolveEmailConfig, resolveEmailSettings, clampInt, defaultDownloadDir } from './config.js';
 export { stripHtml, truncateText, flattenAddresses, sanitizeFilename, parseRawMessage } from './parse.js';
-export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart } from './mail-client.js';
+export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart, messageMatchesQuery } from './mail-client.js';
 export { SETTINGS_NAMESPACE, EmailSettingsSchema, toSettingsBase, toEmailConfig, validateSettingsValue } from './settings.js';
 export { SETTINGS_ROUTE, EmailSettingsBackend, installEmailSettingsWeb } from './web.js';

package/lib/index.js

@@ -164,20 +164,6 @@ function renderFolders(value) {
 function renderAttachment(value) {
     return oneText('账号 ' + value.account + ' 已下载附件 "' + value.filename + '"（' + value.contentType + '，' + value.size + ' 字节）到：\n' + value.path + '\n可用 read 工具读取该文件。');
 }
-/**
- * Best-effort read of the session's effective approval policy. Duck-typed on
- * the permission-presets seam; any drift or absence yields undefined and the
- * gate falls back to the plain ask flow.
- */
-function effectiveApprovalPolicy(ctx, exec) {
-    try {
-        const preset = ctx.get?.('permissionPresets')?.current?.(exec?.agent?.session?.events);
-        return typeof preset?.approval === 'string' ? preset.approval : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 function fingerprintSettings(settings) {
     return JSON.stringify({
         accounts: [...settings.accounts.entries()].map(([name, account]) => [name, account]),
@@ -185,7 +171,10 @@ function fingerprintSettings(settings) {
         sendApproval: settings.sendApproval,
         maxBodyChars: settings.maxBodyChars,
         downloadDir: settings.downloadDir,
+        downloadDirExplicit: settings.downloadDirExplicit,
         maxAttachmentBytes: settings.maxAttachmentBytes,
+        bodySearchFallback: settings.bodySearchFallback,
+        bodySearchLimit: settings.bodySearchLimit,
         idleTimeoutMs: settings.idleTimeoutMs,
     });
 }
@@ -343,13 +332,14 @@ export function apply(ctx, config = {}) {
             schema: attachmentSchema,
             render: (_args, value) => renderAttachment(value),
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = rawArgs;
             if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
                 throw new Error('uid 必须是正整数（用 email_list 获取）');
             }
             const index = clampInt(args.index, 0, 0, 999);
-            return await getPool().downloadAttachment(args.account, args.folder?.trim() || '', args.uid, index);
+            const workspaceHint = typeof exec?.agent?.session?.header?.cwd === 'string' ? exec.agent.session.header.cwd : undefined;
+            return await getPool().downloadAttachment(args.account, args.folder?.trim() || '', args.uid, index, workspaceHint);
         },
     });
     // Approval gate: the user must confirm every send (recipient + subject).
@@ -372,21 +362,39 @@ export function apply(ctx, config = {}) {
         const args = (exec.args ?? {});
         const attachCount = Array.isArray(args.attachments) ? args.attachments.length : 0;
         const reason = '发送邮件给 ' + args.to + '，主题「' + args.subject + '」' + (attachCount > 0 ? '，附件 ' + attachCount + ' 个' : '');
-        // Full Access (approval policy 'never') rejects asks before any answerer
-        // runs, so surface the actionable explanation instead of a misleading
-        // "the user rejected" failure.
-        if (effectiveApprovalPolicy(ctx, exec) === 'never') {
+        // Gate-owned approval: we run the approval round-trip ourselves so the
+        // denial reason is always honest and actionable — including the Full
+        // Access case where the harness policy answers 'rejected' without ever
+        // showing a dialog.
+        const approval = ctx.get('approval');
+        if (approval === undefined) {
             return {
                 kind: 'deny',
-                reason: 'email_send 需要确认，但当前会话处于 Full Access（审批策略 never），不会弹出确认框。两条路：① 把访问模式切回 Read Only 或 Write 再发；② 在设置页关闭「发信前确认」（sendApproval: false），自行承担风险。',
+                reason: 'email_send 需要确认，但当前环境没有审批通道（如 headless）。如确定安全，可在配置中设置 sendApproval: false 后直接发送。',
             };
         }
-        return { kind: 'ask', reason };
+        const outcome = await approval.request({
+            agent: exec.agent,
+            toolName: exec.name,
+            callId: exec.callId,
+            reason,
+            signal: exec.signal,
+        });
+        if (outcome === 'allowed-once')
+            return next();
+        if (outcome === 'cancelled')
+            return { kind: 'deny', reason: '发信确认被取消，邮件未发送。' };
+        if (outcome === 'unavailable')
+            return { kind: 'deny', reason: '发信确认不可用（没有可用的审批界面），邮件未发送。' };
+        return {
+            kind: 'deny',
+            reason: '发信未获批准：要么你拒绝了，要么当前会话处于 Full Access（审批策略 never，不会弹框）。若在 Full Access：切到 Read Only / Write 再发，或关闭 sendApproval（自行承担风险）。',
+        };
     }, { prepend: true });
 }
 export { PROVIDER_NAMES, EMAIL_PASSWORD_ENV } from './config.js';
 export { resolveEmailConfig, resolveEmailSettings, clampInt, defaultDownloadDir } from './config.js';
 export { stripHtml, truncateText, flattenAddresses, sanitizeFilename, parseRawMessage } from './parse.js';
-export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart } from './mail-client.js';
+export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart, messageMatchesQuery } from './mail-client.js';
 export { SETTINGS_NAMESPACE, EmailSettingsSchema, toSettingsBase, toEmailConfig, validateSettingsValue } from './settings.js';
 export { SETTINGS_ROUTE, EmailSettingsBackend, installEmailSettingsWeb } from './web.js';

package/lib/mail-client.d.ts

@@ -18,6 +18,8 @@ interface AttachmentPart {
  * the wrong part.
  */
 export declare function selectAttachmentPart(readAttachments: EmailAttachmentMeta[], parts: AttachmentPart[], index: number): AttachmentPart | undefined;
+/** Case-insensitive match of a query against subject/from/body text. */
+export declare function messageMatchesQuery(subject: string, fromText: string, body: string, query: string): boolean;
 /**
  * One mailbox pool for the whole plugin: pooled IMAP connections per
  * account plus pooled SMTP transporters, with idle sweep and error eviction.
@@ -44,10 +46,12 @@ export declare class EmailPool {
     private transporter;
     list(accountName: string | undefined, folder: string, limit: number, offset: number, unreadOnly: boolean): Promise<EmailListResult>;
     search(accountName: string | undefined, query: string, folder: string, limit: number): Promise<EmailSearchResult>;
+    /** Client-side scan of the tail of the mailbox, newest first. */
+    private searchBodies;
     private fetchListed;
     read(accountName: string | undefined, uid: number, folder: string): Promise<EmailReadResult>;
     folders(accountName: string | undefined, subscribedOnly: boolean): Promise<EmailFoldersResult>;
-    downloadAttachment(accountName: string | undefined, folder: string, uid: number, index: number): Promise<EmailAttachmentResult>;
+    downloadAttachment(accountName: string | undefined, folder: string, uid: number, index: number, workspaceHint?: string): Promise<EmailAttachmentResult>;
     send(accountName: string | undefined, to: string, subject: string, text: string | undefined, cc: string | undefined, attachmentPaths: string[] | undefined): Promise<EmailSendResult>;
 }
 /** Stat every attachment path up front; total size must stay under the cap. */

package/lib/mail-client.js

@@ -57,6 +57,13 @@ export function selectAttachmentPart(readAttachments, parts, index) {
     const byTypeAndSize = parts.find(part => part.contentType === meta.contentType && Math.abs(part.size - meta.size) <= tolerance);
     return byTypeAndSize;
 }
+/** Case-insensitive match of a query against subject/from/body text. */
+export function messageMatchesQuery(subject, fromText, body, query) {
+    const q = query.toLowerCase();
+    return subject.toLowerCase().includes(q)
+        || fromText.toLowerCase().includes(q)
+        || body.toLowerCase().includes(q);
+}
 function toIso(date) {
     return date instanceof Date ? date.toISOString() : '';
 }
@@ -254,10 +261,41 @@ export class EmailPool {
             ]);
             const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => a - b);
             uids.reverse();
+            if (uids.length === 0 && this.settings.bodySearchFallback) {
+                // Server-side search found nothing: fall back to a client-side scan of
+                // the most recent messages (subject/from/body), capped for time.
+                const messages = await this.searchBodies(client, query, folderName, limit);
+                return { account: name, query, count: messages.length, folder: folderName, messages };
+            }
             const messages = await this.fetchListed(client, uids.slice(0, limit));
             return { account: name, query, count: uids.length, folder: folderName, messages };
         });
     }
+    /** Client-side scan of the tail of the mailbox, newest first. */
+    async searchBodies(client, query, folder, limit) {
+        const mailbox = client.mailbox;
+        const total = mailbox === false ? 0 : mailbox.exists;
+        if (total === 0)
+            return [];
+        const start = Math.max(1, total - this.settings.bodySearchLimit + 1);
+        const fetched = await client.fetchAll(start + ':*', { uid: true, envelope: true, flags: true, size: true, bodyStructure: true, source: true }, { uid: true });
+        const out = [];
+        for (const message of [...fetched].reverse()) {
+            if (out.length >= limit)
+                break;
+            const subject = message.envelope?.subject ?? '';
+            const fromText = flattenAddresses(message.envelope?.from).map(a => (a.name ?? '') + ' ' + (a.address ?? '')).join(' ');
+            let body = '';
+            if (message.source !== undefined) {
+                const parsed = await parseRawMessage(message.source, 4096);
+                body = parsed.text;
+            }
+            if (messageMatchesQuery(subject, fromText, body, query)) {
+                out.push(listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)));
+            }
+        }
+        return out;
+    }
     async fetchListed(client, uids) {
         if (uids.length === 0)
             return [];
@@ -292,7 +330,7 @@ export class EmailPool {
             return { account: name, folders };
         });
     }
-    async downloadAttachment(accountName, folder, uid, index) {
+    async downloadAttachment(accountName, folder, uid, index, workspaceHint) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -320,7 +358,13 @@ export class EmailPool {
             const dl = await client.download(uid, att.part, { uid: true, maxBytes: this.settings.maxAttachmentBytes });
             const buf = await collectStream(dl.content, this.settings.maxAttachmentBytes);
             const safeName = sanitizeFilename(dl.meta.filename ?? att.filename ?? body.attachments[index].filename);
-            const dir = this.settings.downloadDir;
+            // 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
+                ? this.settings.downloadDir
+                : (typeof workspaceHint === 'string' && workspaceHint !== ''
+                    ? join(workspaceHint, '.dsh-email-downloads')
+                    : this.settings.downloadDir);
             await mkdir(dir, { recursive: true });
             const dest = await uniquePath(join(dir, safeName));
             await writeFile(dest, buf);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-email",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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",