dsh-email 0.9.1 → 0.10.0

package/README.md

@@ -29,6 +29,7 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 | `email_folders` | 列出邮箱的文件夹（INBOX/已发送/垃圾邮件/自定义…），拿 path 喂给其他工具 |
 | `email_attachment` | 按序号下载邮件附件（默认存到会话工作区，模型可直接读取；大小受 maxAttachmentBytes 限制） |
 | `email_watch` | 增量检查新邮件：首次调用建立基线，之后每次只报告比上次多出来的未读邮件，适合定时任务做新邮件提醒 |
+| `email_mark` | 修改邮件状态：标记已读/未读、加/取消星标，或移动到别的文件夹（归档、丢回收站），收发闭环的「收完之后」那一半 |
 
 ### 新邮件提醒（Web 端）
 
@@ -42,6 +43,7 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 
 ### 版本记录
 
+- **0.10.0**：新增 `email_mark` 工具——标记已读/未读、加/取消星标、移动文件夹（归档/整理），补齐收发闭环；连接池按读/写模式分别管理邮箱打开状态。
 - **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 理解。

package/lib/index.js

@@ -137,6 +137,21 @@ const attachmentSchema = {
     },
     additionalProperties: true,
 };
+const markSchema = {
+    type: 'object',
+    properties: {
+        account: { type: 'string' },
+        uid: { type: 'integer' },
+        folder: { type: 'string' },
+        action: { type: 'string' },
+        seen: { type: 'boolean' },
+        flagged: { type: 'boolean' },
+        movedTo: { type: 'string' },
+        movedUid: { type: 'integer' },
+    },
+    additionalProperties: true,
+};
+const MARK_ACTIONS = ['read', 'unread', 'star', 'unstar', 'move'];
 function oneText(text) {
     return [{ type: 'text', text }];
 }
@@ -194,6 +209,23 @@ function renderFolders(value) {
 function renderAttachment(value) {
     return oneText('账号 ' + value.account + ' 已下载附件 "' + value.filename + '"（' + value.contentType + '，' + value.size + ' 字节）到：\n' + value.path + '\n可用 read 工具读取该文件。');
 }
+const MARK_LABELS = {
+    read: '标记为已读',
+    unread: '标记为未读',
+    star: '加星标',
+    unstar: '取消星标',
+    move: '移动',
+};
+function renderMark(value) {
+    let text = '账号 ' + value.account + '：文件夹 "' + value.folder + '" 中 uid=' + value.uid + ' 已' + (MARK_LABELS[value.action] ?? value.action);
+    if (value.action === 'move') {
+        text += '到 "' + (value.movedTo ?? '') + '"' + (typeof value.movedUid === 'number' ? '（新 uid=' + value.movedUid + '）' : '');
+    }
+    else {
+        text += '（当前：' + (value.seen ? '已读' : '未读') + (value.flagged ? '、已标星' : '') + '）';
+    }
+    return oneText(text);
+}
 function fingerprintSettings(settings) {
     return JSON.stringify({
         accounts: [...settings.accounts.entries()].map(([name, account]) => [name, account]),
@@ -293,6 +325,35 @@ export function apply(ctx, config = {}) {
             return await getPool().read(args.account, args.uid, args.folder?.trim() || '');
         },
     });
+    ctx.tools.register({
+        name: 'email_mark',
+        description: '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.',
+        parameters: compileParameters({
+            uid: { type: 'integer', required: true, description: 'Message uid from email_list or email_search' },
+            action: { type: 'string', required: true, description: 'What to do: read, unread, star, unstar, or move' },
+            toFolder: { type: 'string', description: 'Destination folder path for action=move (see email_folders for valid paths)' },
+            folder: { type: 'string', description: 'IMAP folder the uid belongs to; defaults to the account inboxFolder' },
+            account: { type: 'string', description: ACCOUNT_HINT },
+        }),
+        output: {
+            schema: markSchema,
+            render: (_args, value) => renderMark(value),
+        },
+        async execute(rawArgs) {
+            const args = rawArgs;
+            if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
+                throw new Error('uid 必须是正整数（用 email_list 获取）');
+            }
+            const action = (typeof args.action === 'string' ? args.action.trim().toLowerCase() : '');
+            if (!MARK_ACTIONS.includes(action)) {
+                throw new Error('action 必须是 ' + MARK_ACTIONS.join('、') + ' 之一');
+            }
+            if (action === 'move' && (typeof args.toFolder !== 'string' || args.toFolder.trim() === '')) {
+                throw new Error('action=move 时需要 toFolder 参数（用 email_folders 查看可用文件夹）');
+            }
+            return await getPool().mark(args.account, args.folder?.trim() || '', args.uid, action, args.toFolder);
+        },
+    });
     ctx.tools.register({
         name: 'email_search',
         description: 'Search emails by a keyword matched against sender, recipient and subject (server-side IMAP SEARCH). Body search is not supported by every server and is not attempted; returns the same compact rows as email_list.',

package/lib/mail-client.d.ts

@@ -1,6 +1,6 @@
 import { ImapFlow } from 'imapflow';
 import type { ResolvedEmailConfig, ResolvedEmailSettings } from './config.js';
-import type { EmailAttachmentMeta, EmailAttachmentResult, EmailFoldersResult, EmailListResult, EmailReadResult, EmailSearchResult, EmailSendResult } from './types.js';
+import type { EmailAttachmentMeta, EmailAttachmentResult, EmailFoldersResult, EmailListResult, EmailMarkAction, EmailMarkResult, EmailReadResult, EmailSearchResult, EmailSendResult } from './types.js';
 export declare class MailError extends Error {
     constructor(message: string);
 }
@@ -35,7 +35,7 @@ export declare class EmailPool {
     resolveName(name?: string): string;
     /** Serialize operations per account: one IMAP connection serves one op at a time. */
     private enqueue;
-    withImap<T>(accountName: string | undefined, folder: string | null, run: (client: ImapFlow) => Promise<T>): Promise<T>;
+    withImap<T>(accountName: string | undefined, folder: string | null, run: (client: ImapFlow) => Promise<T>, readOnly?: boolean): Promise<T>;
     private createImap;
     private imapRun;
     private normalizeImapError;
@@ -50,6 +50,7 @@ export declare class EmailPool {
     private searchBodies;
     private fetchListed;
     read(accountName: string | undefined, uid: number, folder: string): Promise<EmailReadResult>;
+    mark(accountName: string | undefined, folder: string, uid: number, action: EmailMarkAction, toFolder?: string): Promise<EmailMarkResult>;
     folders(accountName: string | undefined, subscribedOnly: boolean): Promise<EmailFoldersResult>;
     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>;

package/lib/mail-client.js

@@ -114,10 +114,10 @@ export class EmailPool {
         this.queues.set(name, next.then(() => undefined, () => undefined));
         return next;
     }
-    async withImap(accountName, folder, run) {
+    async withImap(accountName, folder, run, readOnly = true) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
-        return this.enqueue(name, () => this.imapRun(name, cfg, folder, run));
+        return this.enqueue(name, () => this.imapRun(name, cfg, folder, readOnly, run));
     }
     createImap(cfg) {
         const client = new ImapFlow({
@@ -144,7 +144,7 @@ export class EmailPool {
         });
         return client;
     }
-    async imapRun(name, cfg, folder, run) {
+    async imapRun(name, cfg, folder, readOnly, run) {
         let entry = this.imaps.get(name);
         try {
             if (entry === undefined || !entry.client.usable) {
@@ -152,14 +152,17 @@ export class EmailPool {
                     await this.evictImap(name);
                 const client = this.createImap(cfg);
                 await client.connect();
-                entry = { client, selected: null, lastUsed: Date.now(), inUse: 0 };
+                entry = { client, selected: null, selectedReadOnly: true, lastUsed: Date.now(), inUse: 0 };
                 this.imaps.set(name, entry);
             }
             entry.lastUsed = Date.now();
             entry.inUse += 1;
-            if (folder !== null && entry.selected !== folder) {
-                await entry.client.mailboxOpen(folder, { readOnly: true });
+            // Reopen when the folder changes or when the caller needs a different
+            // access mode (email_mark writes flags / moves messages).
+            if (folder !== null && (entry.selected !== folder || entry.selectedReadOnly !== readOnly)) {
+                await entry.client.mailboxOpen(folder, { readOnly });
                 entry.selected = folder;
+                entry.selectedReadOnly = readOnly;
             }
             const result = await run(entry.client);
             entry.lastUsed = Date.now();
@@ -355,6 +358,55 @@ export class EmailPool {
             return { account: name, uid, folder: folderName, ...body };
         });
     }
+    async mark(accountName, folder, uid, action, toFolder) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        const folderName = folder || cfg.inboxFolder;
+        return this.withImap(name, folderName, async (client) => {
+            const before = await client.fetchOne(uid, { uid: true, flags: true }, { uid: true });
+            if (before === false) {
+                throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
+            }
+            let seen = before.flags?.has('\\Seen') === true;
+            let flagged = before.flags?.has('\\Flagged') === true;
+            if (action === 'read' && !seen) {
+                await client.messageFlagsAdd(uid, ['\\Seen'], { uid: true });
+                seen = true;
+            }
+            else if (action === 'unread' && seen) {
+                await client.messageFlagsRemove(uid, ['\\Seen'], { uid: true });
+                seen = false;
+            }
+            else if (action === 'star' && !flagged) {
+                await client.messageFlagsAdd(uid, ['\\Flagged'], { uid: true });
+                flagged = true;
+            }
+            else if (action === 'unstar' && flagged) {
+                await client.messageFlagsRemove(uid, ['\\Flagged'], { uid: true });
+                flagged = false;
+            }
+            else if (action === 'move') {
+                const target = (toFolder ?? '').trim();
+                if (target === '')
+                    throw new MailError('move 操作需要 toFolder 参数（用 email_folders 查看可用文件夹）');
+                if (target === folderName)
+                    throw new MailError('邮件已在文件夹 "' + folderName + '" 中，无需移动');
+                const folders = await client.list();
+                if (!folders.some(row => row.path === target)) {
+                    throw new MailError('找不到目标文件夹 "' + target + '"，可用：' + folders.map(row => row.path).join('、'));
+                }
+                const moved = await client.messageMove(uid, target, { uid: true });
+                if (moved === false)
+                    throw new MailError('移动 uid=' + uid + ' 到 "' + target + '" 失败（服务器拒绝了 MOVE/COPY）');
+                const result = { account: name, uid, folder: folderName, action, seen, flagged, movedTo: target };
+                const destUid = moved?.destinationUid;
+                if (typeof destUid === 'number')
+                    result.movedUid = destUid;
+                return result;
+            }
+            return { account: name, uid, folder: folderName, action, seen, flagged };
+        }, false);
+    }
     async folders(accountName, subscribedOnly) {
         const name = this.resolveName(accountName);
         return this.withImap(name, null, async (client) => {

package/lib/types.d.ts

@@ -124,6 +124,26 @@ export interface EmailWatchArgs extends AccountArg {
     /** Max number of new messages to return per call, default 20. */
     limit?: number;
 }
+export type EmailMarkAction = 'read' | 'unread' | 'star' | 'unstar' | 'move';
+export interface EmailMarkArgs extends AccountArg {
+    uid: number;
+    action: EmailMarkAction;
+    /** Target folder path; only used (and required) when action is 'move'. */
+    toFolder?: string;
+    folder?: string;
+}
+export interface EmailMarkResult {
+    account: string;
+    uid: number;
+    folder: string;
+    action: EmailMarkAction;
+    seen: boolean;
+    flagged: boolean;
+    /** Set after a successful move: the destination folder path. */
+    movedTo?: string;
+    /** Set after a successful move: uid in the destination when the server reports it. */
+    movedUid?: number;
+}
 export interface EmailWatchResult {
     account: string;
     folder: string;

package/package.json

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