dsh-email 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,10 @@
 # dsh-email
 
-DeepSeek Harness 邮件工具插件：让 agent 能**查收件箱、读邮件、搜邮件、代发邮件**。纯插件实现，零核心改动，安装即可用。
+DeepSeek Harness 邮件工具插件：让 agent 能**查收件箱、读邮件、搜邮件、代发邮件、收发附件**。纯插件实现，零核心改动，安装即可用。
 
-Email tools for DeepSeek Harness: list, read, search and send mail through standard IMAP/SMTP — with one-line presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud.
+Email tools for DeepSeek Harness: list, read, search and send mail through standard IMAP/SMTP — with one-line presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud.
+
+纯 Node 实现，**全平台通用**（Windows / macOS / Linux 同一份代码），不依赖 shell、无原生二进制。
 
 ## 工具一览
 
@@ -11,7 +13,9 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 | `email_list` | 列出文件夹里最新的邮件（未读过滤、分页、只看摘要不带正文） |
 | `email_read` | 按 uid 读取一封邮件的全文（HTML 邮件自动转纯文本，超长截断） |
 | `email_search` | 按关键词搜索发件人/收件人/主题（服务器端 IMAP SEARCH，不搜正文） |
-| `email_send` | 代发邮件。**默认发信前会弹确认**，显示收件人和主题，由你批准后才发出 |
+| `email_send` | 代发邮件（支持带附件）。**默认发信前会弹确认**，显示收件人、主题和附件数，由你批准后才发出 |
+| `email_folders` | 列出邮箱的文件夹（INBOX/已发送/垃圾邮件/自定义…），拿 path 喂给其他工具 |
+| `email_attachment` | 按序号下载邮件附件到本地文件（大小受 maxAttachmentBytes 限制） |
 
 示例对话：
 
@@ -51,6 +55,20 @@ dsh plugin --profile web add dsh-email
     inboxFolder: INBOX
 ```
 
+多账号：一个 `tool-email` 行可以配多个邮箱，工具调用时用 `account` 参数选择：
+
+```yaml
+- id: tool-email
+  config:
+    accounts:
+      work: { provider: qq, user: work@qq.com, password: 授权码1 }
+      home: { provider: '163', user: home@163.com, password: 授权码2 }
+    defaultAccount: work        # 省略 account 参数时用这个
+    downloadDir: E:/attachments # 可选，默认 $DSH_HOME/email-downloads
+```
+
+顶层的 `provider`/`user`/`password`/`imap`/`smtp`/`inboxFolder` 仍然可用，作为各账号的共享默认值（v0.1 单账号写法完全兼容）。
+
 ### 常用邮箱预设
 
 | provider | IMAP | SMTP |
@@ -75,7 +93,12 @@ dsh plugin --profile web add dsh-email
 | `smtp.host/port/secure` | 按预设 | 发信服务器 |
 | `inboxFolder` | `INBOX` | 收发工具默认使用的文件夹 |
 | `sendApproval` | `true` | 发信前弹确认（强烈建议保留） |
-| `maxBodyChars` | `20000` | email_read 正文截断上限（1000–200000） |
+| `maxBodyChars` | `20000` | email_read 正文截断上限（1000–200000） |
+| `accounts` | 无 | 具名账号表；账号级字段覆盖顶层简写 |
+| `defaultAccount` | 单账号时自动 | 工具省略 account 参数时使用的账号（多账号必填） |
+| `downloadDir` | `$DSH_HOME/email-downloads` | email_attachment 的落盘目录 |
+| `maxAttachmentBytes` | 20 MiB | 单个附件与附件总大小上限（1024–512 MiB） |
+| `idleTimeoutMs` | `60000` | IMAP 空闲连接回收时间（连接复用，连续操作更快） |
 
 ## 第一步：拿到授权码
 
@@ -93,20 +116,20 @@ dsh plugin --profile web add dsh-email
 - 注意：会话处于 **Full Access（完全访问）** 模式时，harness 会把审批策略置为 never，`email_send` 会被**静默拒绝**（不弹框）。想发信请把访问模式切回 Read Only 或 Write。
 - 本插件不做任何联网上报，凭证只在内存中用于连接你的邮箱服务器。
 
-## 已知限制（v0.1）
+## 已知限制（v0.2）
 
-- **每个工具调用独立建立/关闭连接**：正确、无状态，但连续读多封会比常驻连接慢一点。
-- **单账号**：一个 `tool-email` 行对应一个邮箱；多账号可复制多行（改 id 即可）。
-- **附件只给元数据**（文件名/类型/大小），不下载内容；下载附件列入后续版本。
+- **连接复用**：IMAP 按账号池化（空闲自动回收），SMTP 用 nodemailer 连接池；同一账号的并发调用会排队串行（一个连接一次只服务一个操作，这是有意的）。
+- **多账号**：每个账号独立连接池；一个 `tool-email` 行可以配任意多个账号。
+- **附件下载**：email_attachment 按序号下载（与 email_read 的 attachments 顺序一致）；文件名会被清洗防路径穿越，已有同名文件自动加后缀，大小受 maxAttachmentBytes 限制。
 - **不支持 OAuth2**：强制 OAuth 的企业环境（部分 M365/Google Workspace）暂不可用。
-- 正文搜索不提供：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索要么全量匹配要么不支持，所以 v0.1 只搜主题/发件人/收件人；正文搜索列入后续版本（需客户端下载解析，较慢）。
+- 正文搜索不提供：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索要么全量匹配要么不支持，所以只搜主题/发件人/收件人；正文搜索列入后续版本（需客户端下载解析，较慢）。
 
 ## 开发
 
 ```sh
 pnpm install
 pnpm run build   # tsc → lib/
-pnpm test        # 构建 + node --test（配置/解析/注册与审批门，19 个用例，无需真实邮箱）
+pnpm test        # 构建 + node --test（配置/解析/注册与审批门，27 个用例，无需真实邮箱）
 ```
 
 ## 协议

package/lib/config.d.ts

@@ -1,3 +1,4 @@
+export type ProviderName = 'qq' | '163' | '126' | 'sina' | 'aliyun' | 'gmail' | 'outlook' | 'icloud';
 export interface ImapConfig {
     host?: string;
     port?: number;
@@ -10,21 +11,30 @@ export interface SmtpConfig {
     port?: number;
     secure?: boolean;
 }
-export interface EmailConfig {
-    /** Built-in preset that fills imap/smtp host+port+secure. */
-    provider?: 'qq' | '163' | '126' | 'sina' | 'aliyun' | 'gmail' | 'outlook' | 'icloud';
-    /** Login address, e.g. you@qq.com. */
+/** One mailbox account. Top-level shorthand fields act as shared defaults. */
+export interface AccountConfig {
+    provider?: ProviderName;
     user?: string;
-    /** App password / authorization code. Falls back to $DSH_EMAIL_PASSWORD. */
     password?: string;
     imap?: ImapConfig;
     smtp?: SmtpConfig;
-    /** Mailbox used by the read/search/list tools. Default 'INBOX'. */
     inboxFolder?: string;
+}
+export interface EmailConfig extends AccountConfig {
     /** Ask the user for approval before email_send. Default true. */
     sendApproval?: boolean;
     /** Plain-text body cap for email_read. Default 20000. */
     maxBodyChars?: number;
+    /** Named accounts. Account-level fields override the top-level shorthand. */
+    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. */
+    downloadDir?: string;
+    /** Per-attachment and total-attachment byte cap. Default 20 MiB. */
+    maxAttachmentBytes?: number;
+    /** Unused IMAP connections close after this many ms. Default 60000. */
+    idleTimeoutMs?: number;
 }
 export interface ProviderPreset {
     imap: {
@@ -41,7 +51,7 @@ export interface ProviderPreset {
 export declare const PROVIDER_PRESETS: Record<string, ProviderPreset>;
 export declare const PROVIDER_NAMES: string[];
 export declare const EMAIL_PASSWORD_ENV = "DSH_EMAIL_PASSWORD";
-/** Fully resolved, validated configuration. */
+/** Fully resolved, validated configuration for one account. */
 export interface ResolvedEmailConfig {
     user: string;
     password: string;
@@ -56,14 +66,24 @@ export interface ResolvedEmailConfig {
         secure: boolean;
     };
     inboxFolder: string;
+}
+/** Fully resolved plugin settings: the account map plus shared policy. */
+export interface ResolvedEmailSettings {
+    accounts: Map<string, ResolvedEmailConfig>;
+    defaultAccount: string;
     sendApproval: boolean;
     maxBodyChars: number;
-    providerName: string | null;
+    downloadDir: string;
+    maxAttachmentBytes: number;
+    idleTimeoutMs: number;
 }
+export declare function defaultDownloadDir(): string;
 /**
  * Resolve and validate the raw row config. Throws with an actionable message
  * (in Chinese, since it is what the user and the model both read) when the
  * account is not fully specified.
  */
+export declare function resolveEmailSettings(config: EmailConfig | undefined): ResolvedEmailSettings;
+/** v0.1-compatible wrapper: resolve the single (or default) account. */
 export declare function resolveEmailConfig(config: EmailConfig | undefined): ResolvedEmailConfig;
 export declare function clampInt(value: unknown, fallback: number, min: number, max: number): number;

package/lib/config.js

@@ -1,3 +1,5 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 export const PROVIDER_PRESETS = {
     qq: { imap: { host: 'imap.qq.com', port: 993, secure: true }, smtp: { host: 'smtp.qq.com', port: 465, secure: true } },
     '163': { imap: { host: 'imap.163.com', port: 993, secure: true }, smtp: { host: 'smtp.163.com', port: 465, secure: true } },
@@ -10,40 +12,94 @@ export const PROVIDER_PRESETS = {
 };
 export const PROVIDER_NAMES = Object.keys(PROVIDER_PRESETS);
 export const EMAIL_PASSWORD_ENV = 'DSH_EMAIL_PASSWORD';
+const DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+const DEFAULT_IDLE_TIMEOUT_MS = 60000;
+export function defaultDownloadDir() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'email-downloads');
+}
 /**
  * Resolve and validate the raw row config. Throws with an actionable message
  * (in Chinese, since it is what the user and the model both read) when the
  * account is not fully specified.
  */
-export function resolveEmailConfig(config) {
+export function resolveEmailSettings(config) {
     const raw = config ?? {};
-    const preset = raw.provider === undefined ? undefined : PROVIDER_PRESETS[raw.provider];
-    if (raw.provider !== undefined && preset === undefined) {
-        throw new Error(`dsh-email：未知的邮箱服务商 "${raw.provider}"，可选：${PROVIDER_NAMES.join('/')}；或省略 provider，直接填写 imap.host 与 smtp.host`);
+    const common = {
+        provider: raw.provider,
+        user: raw.user,
+        password: raw.password,
+        imap: raw.imap,
+        smtp: raw.smtp,
+        inboxFolder: raw.inboxFolder,
+    };
+    const entries = raw.accounts === undefined || Object.keys(raw.accounts).length === 0
+        ? undefined
+        : raw.accounts;
+    const accounts = new Map();
+    if (entries === undefined) {
+        accounts.set('default', resolveAccount('default', common, {}, true));
+    }
+    else {
+        for (const [name, acc] of Object.entries(entries)) {
+            accounts.set(name, resolveAccount(name, common, acc ?? {}, false));
+        }
+    }
+    let defaultName;
+    if (raw.defaultAccount !== undefined && raw.defaultAccount !== '') {
+        if (!accounts.has(raw.defaultAccount)) {
+            throw new Error(`dsh-email：defaultAccount "${raw.defaultAccount}" 不存在，可用账号：${[...accounts.keys()].join('、')}`);
+        }
+        defaultName = raw.defaultAccount;
+    }
+    else if (accounts.size === 1) {
+        defaultName = [...accounts.keys()][0];
+    }
+    else if (accounts.has('default')) {
+        defaultName = 'default';
+    }
+    else {
+        throw new Error(`dsh-email：配置了多个账号（${[...accounts.keys()].join('、')}），请设置 defaultAccount 指定默认账号`);
+    }
+    return {
+        accounts,
+        defaultAccount: defaultName,
+        sendApproval: raw.sendApproval !== false,
+        maxBodyChars: clampInt(raw.maxBodyChars, 20000, 1000, 200000),
+        downloadDir: raw.downloadDir?.trim() || defaultDownloadDir(),
+        maxAttachmentBytes: clampInt(raw.maxAttachmentBytes, DEFAULT_MAX_ATTACHMENT_BYTES, 1024, 512 * 1024 * 1024),
+        idleTimeoutMs: clampInt(raw.idleTimeoutMs, DEFAULT_IDLE_TIMEOUT_MS, 5000, 600000),
+    };
+}
+/** Merge one account over the shared shorthand and validate it. */
+function resolveAccount(name, common, acc, allowEnvPassword) {
+    const preset = acc.provider === undefined ? PROVIDER_PRESETS[common.provider ?? ''] : PROVIDER_PRESETS[acc.provider];
+    if ((acc.provider ?? common.provider) !== undefined && preset === undefined) {
+        throw new Error(`dsh-email：账号 "${name}" 的 provider "${acc.provider ?? common.provider}" 未知，可选：${PROVIDER_NAMES.join('/')}；或省略 provider 直接填 imap.host 与 smtp.host`);
     }
-    const user = raw.user?.trim() ?? '';
-    const password = raw.password ?? process.env[EMAIL_PASSWORD_ENV] ?? '';
+    const user = (acc.user ?? common.user ?? '').trim();
+    const password = acc.password ?? common.password ?? (allowEnvPassword ? process.env[EMAIL_PASSWORD_ENV] ?? '' : '');
     const imap = {
-        host: raw.imap?.host ?? preset?.imap.host,
-        port: raw.imap?.port ?? preset?.imap.port,
-        secure: raw.imap?.secure ?? preset?.imap.secure,
-        connectionTimeoutMs: raw.imap?.connectionTimeoutMs,
-        socketTimeoutMs: raw.imap?.socketTimeoutMs,
+        host: acc.imap?.host ?? common.imap?.host ?? preset?.imap.host,
+        port: acc.imap?.port ?? common.imap?.port ?? preset?.imap.port,
+        secure: acc.imap?.secure ?? common.imap?.secure ?? preset?.imap.secure,
+        connectionTimeoutMs: acc.imap?.connectionTimeoutMs ?? common.imap?.connectionTimeoutMs,
+        socketTimeoutMs: acc.imap?.socketTimeoutMs ?? common.imap?.socketTimeoutMs,
     };
     const smtp = {
-        host: raw.smtp?.host ?? preset?.smtp.host,
-        port: raw.smtp?.port ?? preset?.smtp.port,
-        secure: raw.smtp?.secure ?? preset?.smtp.secure,
+        host: acc.smtp?.host ?? common.smtp?.host ?? preset?.smtp.host,
+        port: acc.smtp?.port ?? common.smtp?.port ?? preset?.smtp.port,
+        secure: acc.smtp?.secure ?? common.smtp?.secure ?? preset?.smtp.secure,
     };
     const problems = [];
     if (user === '')
-        problems.push('user（邮箱地址）未填写');
+        problems.push(`账号 "${name}" 的 user（邮箱地址）未填写`);
     if (password === '')
-        problems.push(`password 未填写（或用环境变量 ${EMAIL_PASSWORD_ENV}）`);
+        problems.push(`账号 "${name}" 的 password 未填写（单账号可用环境变量 ${EMAIL_PASSWORD_ENV}）`);
     if (imap.host === undefined || imap.host === '')
-        problems.push(`imap.host 未填写（可填 provider 预设：${PROVIDER_NAMES.join('/')}）`);
+        problems.push(`账号 "${name}" 的 imap.host 未填写（可填 provider 预设：${PROVIDER_NAMES.join('/')}）`);
     if (smtp.host === undefined || smtp.host === '')
-        problems.push('smtp.host 未填写（同上）');
+        problems.push(`账号 "${name}" 的 smtp.host 未填写（同上）`);
     if (problems.length > 0) {
         throw new Error(`dsh-email 未配置：${problems.join('；')}。请在 profile 的 cordis.patch.yml 中覆盖 tool-email 行并重启（见插件 README）`);
     }
@@ -52,12 +108,14 @@ export function resolveEmailConfig(config) {
         password,
         imap: { ...imap, host: imap.host, port: imap.port, secure: imap.secure },
         smtp: { ...smtp, host: smtp.host, port: smtp.port, secure: smtp.secure },
-        inboxFolder: raw.inboxFolder?.trim() || 'INBOX',
-        sendApproval: raw.sendApproval !== false,
-        maxBodyChars: clampInt(raw.maxBodyChars, 20000, 1000, 200000),
-        providerName: raw.provider ?? null,
+        inboxFolder: (acc.inboxFolder ?? common.inboxFolder ?? '').trim() || 'INBOX',
     };
 }
+/** v0.1-compatible wrapper: resolve the single (or default) account. */
+export function resolveEmailConfig(config) {
+    const settings = resolveEmailSettings(config);
+    return settings.accounts.get(settings.defaultAccount);
+}
 export function clampInt(value, fallback, min, max) {
     const n = typeof value === 'number' ? Math.trunc(value) : fallback;
     if (!Number.isFinite(n))

package/lib/index.d.ts

@@ -4,6 +4,6 @@ export declare const inject: string[];
 export type Config = EmailConfig;
 export declare function apply(ctx: any, config?: Config): void;
 export { PROVIDER_NAMES, EMAIL_PASSWORD_ENV } from './config.js';
-export { resolveEmailConfig, clampInt } from './config.js';
-export { stripHtml, truncateText, flattenAddresses, parseRawMessage } from './parse.js';
-export { MailClient, MailError, messageOf } from './mail-client.js';
+export { resolveEmailConfig, resolveEmailSettings, clampInt, defaultDownloadDir } from './config.js';
+export { stripHtml, truncateText, flattenAddresses, sanitizeFilename, parseRawMessage } from './parse.js';
+export { EmailPool, MailError, messageOf, validateAttachmentPaths } from './mail-client.js';