dsh-email 0.1.0 → 0.3.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 限制） |
 
 示例对话：
 
@@ -25,7 +29,14 @@ dsh plugin --profile web add dsh-email
 
 （或从 GitHub 安装：`dsh plugin --profile web add github:你的账号/dsh-email#<commit>`，随后按提示在 profile 的 `pnpm-workspace.yaml` 里授权 `prepare` 构建。）
 
-装好后重启 `dsh web`。插件自带空配置，**不会弄崩启动**；配置前调用任何 email 工具都会返回明确的配置提示。
+装好后重启 `dsh web`。插件自带空配置，**不会弄崩启动**；配置前调用任何 email 工具都会返回明确的配置提示。
+
+**配置方式有两种（任选其一）：**
+
+1. **网页设置（推荐）**：重启后打开 **设置 → 邮件 (dsh-email)**，表单里填邮箱地址和授权码，点「保存并应用」，还带「测试连接」按钮。零 YAML、零重启。
+2. **YAML**：按下面的 cordis.patch.yml 模板手写（多账号 accounts 映射目前只支持这种方式）。
+
+设置页保存的值存在 `settings.yaml` 的 `dsh-email` 命名空间里，覆盖 YAML 的默认账号配置；密码字段标记为 secret（不会出现在任何导出/诊断里）。
 
 ## 配置
 
@@ -51,6 +62,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 +100,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 +123,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` 行可以配任意多个账号。设置页编辑的是默认账号；`accounts` 映射仍需写 cordis.patch.yml。
+- **附件下载**：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（配置/解析/注册与审批门，31 个用例，无需真实邮箱）
 ```
 
 ## 协议

package/lib/client.js

@@ -0,0 +1,295 @@
+window.__ModuleLoader__.load({ id: "dsh-email/client", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+
+const React = require("react");
+const { useState, useEffect, useCallback } = React;
+const h = React.createElement;
+
+const ROUTE = "/_dsh/dsh-email/settings";
+
+async function api(action, payload) {
+  const init = action === undefined
+    ? { credentials: "same-origin" }
+    : {
+        credentials: "same-origin",
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(Object.assign({ action }, payload)),
+      };
+  const res = await fetch(ROUTE, init);
+  const body = await res.json();
+  if (!res.ok || !body.ok) {
+    throw new Error((body && body.error && body.error.message) || ("request failed " + res.status));
+  }
+  return body.value;
+}
+
+const PROVIDERS = [
+  ["qq", "QQ 邮箱"],
+  ["163", "163 邮箱"],
+  ["126", "126 邮箱"],
+  ["sina", "新浪邮箱"],
+  ["aliyun", "阿里邮箱"],
+  ["gmail", "Gmail"],
+  ["outlook", "Outlook"],
+  ["icloud", "iCloud"],
+  ["", "自定义（手填 IMAP/SMTP）"],
+];
+
+const EMPTY = {
+  provider: "",
+  user: "",
+  password: "",
+  inboxFolder: "INBOX",
+  sendApproval: true,
+  downloadDir: "",
+  imap: { host: "", port: 993, secure: true },
+  smtp: { host: "", port: 465, secure: true },
+};
+
+const CSS = [
+  ".dshe-settings{display:grid;gap:14px;max-width:900px;padding:8px 2px 32px;color:var(--dsw-alias-fg-primary,#26231f)}",
+  ".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}",
+  ".dshe-kicker{font-size:10px;text-transform:uppercase;letter-spacing:.1em;color:#0b6c9f;font-weight:700}",
+  ".dshe-panel{display:grid;gap:12px;padding:15px;border:1px solid var(--dsw-alias-border-subtle,#dedbd5);border-radius:14px;background:var(--dsw-alias-bg-layer-1,#fff);box-shadow:0 1px 1px rgba(0,0,0,.02)}",
+  ".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-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}",
+  ".dshe-btn.primary{background:#0b6c9f;border-color:#0b6c9f;color:#fff}",
+  ".dshe-btn:disabled{opacity:.55;cursor:default}",
+  ".dshe-alert{padding:10px 12px;border-radius:10px;font-size:12px;line-height:1.5}",
+  ".dshe-alert.error{background:rgba(205,72,72,.1);color:#aa3939}",
+  ".dshe-alert.success{background:rgba(48,154,100,.1);color:#267d52}",
+  ".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}",
+].join("\n");
+
+function fieldInput(type, value, onChange, placeholder) {
+  return h("input", {
+    type,
+    value: value === undefined || value === null ? "" : String(value),
+    placeholder,
+    onChange: (e) => onChange(e.target.value),
+  });
+}
+
+function EmailSettingsSection() {
+  const [draft, setDraft] = useState(null);
+  const [snapshot, setSnapshot] = useState(undefined);
+  const [busy, setBusy] = useState(false);
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState(undefined);
+  const [error, setError] = useState("");
+  const [message, setMessage] = useState("");
+
+  const load = useCallback(async () => {
+    setBusy(true); setError("");
+    try {
+      const snap = await api();
+      setSnapshot(snap);
+      const value = (snap && snap.settings && snap.settings.value) || EMPTY;
+      setDraft({
+        ...EMPTY,
+        ...value,
+        imap: { ...EMPTY.imap, ...(value.imap || {}) },
+        smtp: { ...EMPTY.smtp, ...(value.smtp || {}) },
+      });
+    } catch (e) {
+      setError(e && e.message ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  useEffect(() => { load(); }, [load]);
+
+  const update = (patch) => setDraft((cur) => Object.assign({}, cur, patch));
+  const updateImap = (patch) => setDraft((cur) => Object.assign({}, cur, { imap: Object.assign({}, cur.imap, patch) }));
+  const updateSmtp = (patch) => setDraft((cur) => Object.assign({}, cur, { smtp: Object.assign({}, cur.smtp, patch) }));
+
+  const doSave = async () => {
+    setBusy(true); setError(""); setMessage(""); setTestResult(undefined);
+    try {
+      const rev = snapshot && snapshot.settings ? snapshot.settings.revision : 0;
+      const value = {
+        ...draft,
+        maxBodyChars: typeof draft.maxBodyChars === "number" ? draft.maxBodyChars : 20000,
+        imap: { ...draft.imap, port: Number(draft.imap.port) || 993 },
+        smtp: { ...draft.smtp, port: Number(draft.smtp.port) || 465 },
+      };
+      const snap = await api("save", { value, expectedRevision: rev });
+      setSnapshot(snap);
+      setMessage(draft.user && draft.user.trim()
+        ? "已保存并生效（下次请求即用新账号）。"
+        : "已保存。注意：尚未填写邮箱地址，email_* 工具调用时会提示配置。");
+    } catch (e) {
+      setError(e && e.message ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const doTest = async () => {
+    setTesting(true); setError(""); setMessage(""); setTestResult(undefined);
+    try {
+      const value = {
+        ...draft,
+        maxBodyChars: typeof draft.maxBodyChars === "number" ? draft.maxBodyChars : 20000,
+        imap: { ...draft.imap, port: Number(draft.imap.port) || 993 },
+        smtp: { ...draft.smtp, port: Number(draft.smtp.port) || 465 },
+      };
+      const result = await api("test", { value });
+      setTestResult({ ok: true, text: "连接成功，IMAP 登录通过（" + result.ms + " ms）。" });
+    } catch (e) {
+      setTestResult({ ok: false, text: "连接失败：" + (e && e.message ? e.message : String(e)) });
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  if (draft === null) {
+    return h("div", { className: "dshe-settings" }, [
+      h("div", { className: "dshe-alert info" }, busy ? "加载中…" : (error || "加载中…")),
+    ]);
+  }
+
+  const accounts = snapshot && snapshot.accounts ? snapshot.accounts : [];
+
+  return h("div", { className: "dshe-settings" }, [
+    h("header", { className: "dshe-header" }, [
+      h("span", { className: "dshe-kicker" }, "dsh-email · IMAP/SMTP"),
+      h("h2", null, "邮件"),
+      h("p", null, "在这里填写邮箱账号，六个 email_* 工具立即生效，无需手写 YAML。密码字段标记为 secret，不会出现在任何导出里。"),
+    ]),
+    h("section", { className: "dshe-panel" }, [
+      h("div", { className: "dshe-grid" }, [
+        h("div", { className: "dshe-field" }, [
+          h("label", null, "邮箱服务商"),
+          h("select", { value: draft.provider, onChange: (e) => update({ provider: e.target.value }) },
+            PROVIDERS.map(([value, label]) => h("option", { key: value, value }, label))),
+        ]),
+        h("div", { className: "dshe-field" }, [
+          h("label", null, "邮箱地址"),
+          fieldInput("text", draft.user, (v) => update({ user: v }), "you@example.com"),
+        ]),
+      ]),
+      h("div", { className: "dshe-grid" }, [
+        h("div", { className: "dshe-field" }, [
+          h("label", null, "授权码 / 应用专用密码"),
+          h("input", {
+            type: "password",
+            value: draft.password,
+            placeholder: "不是登录密码；QQ/163 在邮箱设置里生成授权码",
+            onChange: (e) => update({ password: e.target.value }),
+          }),
+        ]),
+        h("div", { className: "dshe-field" }, [
+          h("label", null, "收件文件夹（默认 INBOX）"),
+          fieldInput("text", draft.inboxFolder, (v) => update({ inboxFolder: v }), "INBOX"),
+        ]),
+      ]),
+      h("label", { className: "dshe-check" }, [
+        h("input", {
+          type: "checkbox",
+          checked: draft.sendApproval === true,
+          onChange: (e) => update({ sendApproval: e.target.checked }),
+        }),
+        "发信前弹确认（强烈建议保留；Full Access 模式下会被自动拒绝）",
+      ]),
+      h("div", { className: "dshe-field" }, [
+        h("label", null, "附件下载目录（默认 $DSH_HOME/email-downloads）"),
+        fieldInput("text", draft.downloadDir, (v) => update({ downloadDir: v }), "留空使用默认"),
+      ]),
+      h("details", { className: "dshe-details" }, [
+        h("summary", null, "高级：自定义服务器（选了预设可留空）"),
+        h("div", { className: "dshe-grid", style: { marginTop: 10 } }, [
+          h("div", { className: "dshe-field" }, [
+            h("label", null, "IMAP 主机"),
+            fieldInput("text", draft.imap.host, (v) => updateImap({ host: v }), "imap.qq.com"),
+          ]),
+          h("div", { className: "dshe-field" }, [
+            h("label", null, "IMAP 端口"),
+            fieldInput("number", draft.imap.port, (v) => updateImap({ port: Number(v) }), "993"),
+          ]),
+          h("label", { className: "dshe-check" }, [
+            h("input", {
+              type: "checkbox",
+              checked: draft.imap.secure === true,
+              onChange: (e) => updateImap({ secure: e.target.checked }),
+            }),
+            "IMAP SSL",
+          ]),
+          h("div", { className: "dshe-field" }, [
+            h("label", null, "SMTP 主机"),
+            fieldInput("text", draft.smtp.host, (v) => updateSmtp({ host: v }), "smtp.qq.com"),
+          ]),
+          h("div", { className: "dshe-field" }, [
+            h("label", null, "SMTP 端口"),
+            fieldInput("number", draft.smtp.port, (v) => updateSmtp({ port: Number(v) }), "465"),
+          ]),
+          h("label", { className: "dshe-check" }, [
+            h("input", {
+              type: "checkbox",
+              checked: draft.smtp.secure === true,
+              onChange: (e) => updateSmtp({ secure: e.target.checked }),
+            }),
+            "SMTP SSL（Outlook/iCloud 587 端口请取消勾选）",
+          ]),
+        ]),
+      ]),
+      h("div", { className: "dshe-actions" }, [
+        h("button", { className: "dshe-btn primary", disabled: busy || testing, onClick: doSave }, busy ? "处理中…" : "保存并应用"),
+        h("button", { className: "dshe-btn", disabled: busy || testing, onClick: doTest }, testing ? "测试中…" : "测试连接"),
+      ]),
+      snapshot && snapshot.writable === false
+        ? h("div", { className: "dshe-alert info" }, "当前 settings 存储是只读的，只能查看不能保存。")
+        : null,
+    ]),
+    error ? h("div", { className: "dshe-alert error" }, error) : null,
+    message ? h("div", { className: "dshe-alert success" }, message) : null,
+    testResult
+      ? h("div", { className: testResult.ok ? "dshe-alert success" : "dshe-alert error" }, testResult.text)
+      : null,
+    accounts.length > 0
+      ? h("div", { className: "dshe-hint" }, "当前生效账号：" + accounts.join("、") + "（多账号 accounts 映射仍走 cordis.patch.yml）")
+      : null,
+  ]);
+}
+
+const inject = ["slots"];
+
+function apply(ctx) {
+  ctx.effect(() => {
+    const id = "dsh-email/client";
+    if (document.querySelector('style[data-plugin-css="' + id + '"]')) return () => {};
+    const style = document.createElement("style");
+    style.dataset.plugin = "dsh-email";
+    style.dataset.pluginCss = id;
+    style.textContent = CSS;
+    document.head.appendChild(style);
+    return () => { style.remove(); };
+  }, "dsh-email: styles");
+
+  ctx.slots.inject("settings.section", () => ctx.slots.register({
+    name: "settings.section",
+    id: "dsh-email",
+    order: 45,
+    label: () => "邮件 (dsh-email)",
+    inject: () => ({}),
+  }, EmailSettingsSection));
+}
+
+exports.apply = apply;
+exports.inject = inject;
+
+return module.exports;
+}});

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';