dsh-email 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-email contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# dsh-email
+
+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_list` | 列出文件夹里最新的邮件（未读过滤、分页、只看摘要不带正文） |
+| `email_read` | 按 uid 读取一封邮件的全文（HTML 邮件自动转纯文本，超长截断） |
+| `email_search` | 按关键词搜索发件人/收件人/主题（服务器端 IMAP SEARCH，不搜正文） |
+| `email_send` | 代发邮件。**默认发信前会弹确认**，显示收件人和主题，由你批准后才发出 |
+
+示例对话：
+
+> 帮我看下 QQ 邮箱最新的 10 封未读，把要回复的列出来。
+
+## 安装
+
+```sh
+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 工具都会返回明确的配置提示。
+
+## 配置
+
+在你 profile 的 `cordis.patch.yml` 里覆盖 `tool-email` 行（在 `$DSH_HOME/profiles/<name>/` 下），然后重启：
+
+```yaml
+- id: tool-email
+  config:
+    provider: qq          # qq | 163 | 126 | sina | aliyun | gmail | outlook | icloud
+    user: you@qq.com
+    password: 你的授权码   # 强烈建议改用环境变量 DSH_EMAIL_PASSWORD，见下
+```
+
+不需要预设？手填任意 IMAP/SMTP 服务器即可：
+
+```yaml
+- id: tool-email
+  config:
+    user: you@corp.example
+    password: 你的授权码
+    imap: { host: imap.corp.example, port: 993, secure: true }
+    smtp: { host: smtp.corp.example, port: 465, secure: true }
+    inboxFolder: INBOX
+```
+
+### 常用邮箱预设
+
+| provider | IMAP | SMTP |
+|---|---|---|
+| `qq` | imap.qq.com:993 (SSL) | smtp.qq.com:465 (SSL) |
+| `163` | imap.163.com:993 | smtp.163.com:465 |
+| `126` | imap.126.com:993 | smtp.126.com:465 |
+| `sina` | imap.sina.com:993 | smtp.sina.com:465 |
+| `aliyun` | imap.aliyun.com:993 | smtp.aliyun.com:465 |
+| `gmail` | imap.gmail.com:993 | smtp.gmail.com:465 |
+| `outlook` | outlook.office365.com:993 | smtp.office365.com:587 (STARTTLS) |
+| `icloud` | imap.mail.me.com:993 | smtp.mail.me.com:587 (STARTTLS) |
+
+### 完整配置项
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `provider` | 无 | 预设名，自动填 imap/smtp 地址；显式写的 host/port/secure 优先 |
+| `user` | 必填 | 登录邮箱地址 |
+| `password` | 必填* | 授权码/应用专用密码；*也可用环境变量 `DSH_EMAIL_PASSWORD` |
+| `imap.host/port/secure` | 按预设 | 收信服务器 |
+| `smtp.host/port/secure` | 按预设 | 发信服务器 |
+| `inboxFolder` | `INBOX` | 收发工具默认使用的文件夹 |
+| `sendApproval` | `true` | 发信前弹确认（强烈建议保留） |
+| `maxBodyChars` | `20000` | email_read 正文截断上限（1000–200000） |
+
+## 第一步：拿到授权码
+
+各邮箱都要求用「授权码/应用专用密码」而不是登录密码：
+
+- **QQ 邮箱**：设置 → 账户 → 开启 IMAP/SMTP 服务 → 生成授权码
+- **163/126**：设置 → POP3/SMTP/IMAP → 开启 → 新增授权码
+- **Gmail**：开启两步验证 → 安全 → 应用专用密码
+- **Outlook**：Microsoft 账户安全 → 应用密码（部分账号需先开两步验证）
+
+## 安全须知
+
+- **授权码就是你的邮箱钥匙**。它写在 profile 的 `cordis.patch.yml` 里，请勿把它提交到任何 Git 仓库；更推荐用环境变量 `DSH_EMAIL_PASSWORD`。
+- `email_send` 默认走 DSH 审批通道：每次发信都显示「发送邮件给 xx，主题「xx」」，你批准才发出。没有审批通道的环境（如无 UI 的 headless）会**直接拒绝发信**，这是安全默认。
+- 注意：会话处于 **Full Access（完全访问）** 模式时，harness 会把审批策略置为 never，`email_send` 会被**静默拒绝**（不弹框）。想发信请把访问模式切回 Read Only 或 Write。
+- 本插件不做任何联网上报，凭证只在内存中用于连接你的邮箱服务器。
+
+## 已知限制（v0.1）
+
+- **每个工具调用独立建立/关闭连接**：正确、无状态，但连续读多封会比常驻连接慢一点。
+- **单账号**：一个 `tool-email` 行对应一个邮箱；多账号可复制多行（改 id 即可）。
+- **附件只给元数据**（文件名/类型/大小），不下载内容；下载附件列入后续版本。
+- **不支持 OAuth2**：强制 OAuth 的企业环境（部分 M365/Google Workspace）暂不可用。
+- 正文搜索不提供：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索要么全量匹配要么不支持，所以 v0.1 只搜主题/发件人/收件人；正文搜索列入后续版本（需客户端下载解析，较慢）。
+
+## 开发
+
+```sh
+pnpm install
+pnpm run build   # tsc → lib/
+pnpm test        # 构建 + node --test（配置/解析/注册与审批门，19 个用例，无需真实邮箱）
+```
+
+## 协议
+
+MIT。这是一个社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*` 为官方保留命名空间。

package/cordis.patch.yml

@@ -0,0 +1,26 @@
+# dsh-email: IMAP/SMTP email tools for DeepSeek Harness.
+#
+# The row ships with an EMPTY config so installing the bundle never breaks
+# boot; each email_* tool reports a configuration hint until you fill the
+# account. Configure it in your profile's cordis.patch.yml by overriding this
+# row (later layers win), for example:
+#
+#   - id: tool-email
+#     config:
+#       provider: qq          # qq | 163 | 126 | sina | aliyun | gmail | outlook | icloud
+#       user: you@qq.com
+#       password: 你的授权码   # 或改用环境变量 DSH_EMAIL_PASSWORD
+#       # sendApproval: true  # 发信前弹确认（默认开启，强烈建议保留）
+#
+# Or skip the preset and spell out any IMAP/SMTP server:
+#
+#   - id: tool-email
+#     config:
+#       user: you@corp.example
+#       password: 你的授权码
+#       imap: { host: imap.corp.example, port: 993, secure: true }
+#       smtp: { host: smtp.corp.example, port: 465, secure: true }
+- insert:
+    - id: tool-email
+      name: dsh-email
+      config: {}

package/lib/config.d.ts

@@ -0,0 +1,69 @@
+export interface ImapConfig {
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    connectionTimeoutMs?: number;
+    socketTimeoutMs?: number;
+}
+export interface SmtpConfig {
+    host?: string;
+    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. */
+    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;
+    /** Ask the user for approval before email_send. Default true. */
+    sendApproval?: boolean;
+    /** Plain-text body cap for email_read. Default 20000. */
+    maxBodyChars?: number;
+}
+export interface ProviderPreset {
+    imap: {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+}
+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. */
+export interface ResolvedEmailConfig {
+    user: string;
+    password: string;
+    imap: ImapConfig & {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+    smtp: SmtpConfig & {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+    inboxFolder: string;
+    sendApproval: boolean;
+    maxBodyChars: number;
+    providerName: string | null;
+}
+/**
+ * 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 resolveEmailConfig(config: EmailConfig | undefined): ResolvedEmailConfig;
+export declare function clampInt(value: unknown, fallback: number, min: number, max: number): number;

package/lib/config.js

@@ -0,0 +1,66 @@
+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 } },
+    '126': { imap: { host: 'imap.126.com', port: 993, secure: true }, smtp: { host: 'smtp.126.com', port: 465, secure: true } },
+    sina: { imap: { host: 'imap.sina.com', port: 993, secure: true }, smtp: { host: 'smtp.sina.com', port: 465, secure: true } },
+    aliyun: { imap: { host: 'imap.aliyun.com', port: 993, secure: true }, smtp: { host: 'smtp.aliyun.com', port: 465, secure: true } },
+    gmail: { imap: { host: 'imap.gmail.com', port: 993, secure: true }, smtp: { host: 'smtp.gmail.com', port: 465, secure: true } },
+    outlook: { imap: { host: 'outlook.office365.com', port: 993, secure: true }, smtp: { host: 'smtp.office365.com', port: 587, secure: false } },
+    icloud: { imap: { host: 'imap.mail.me.com', port: 993, secure: true }, smtp: { host: 'smtp.mail.me.com', port: 587, secure: false } },
+};
+export const PROVIDER_NAMES = Object.keys(PROVIDER_PRESETS);
+export const EMAIL_PASSWORD_ENV = 'DSH_EMAIL_PASSWORD';
+/**
+ * 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) {
+    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 user = raw.user?.trim() ?? '';
+    const password = raw.password ?? 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,
+    };
+    const smtp = {
+        host: raw.smtp?.host ?? preset?.smtp.host,
+        port: raw.smtp?.port ?? preset?.smtp.port,
+        secure: raw.smtp?.secure ?? preset?.smtp.secure,
+    };
+    const problems = [];
+    if (user === '')
+        problems.push('user（邮箱地址）未填写');
+    if (password === '')
+        problems.push(`password 未填写（或用环境变量 ${EMAIL_PASSWORD_ENV}）`);
+    if (imap.host === undefined || imap.host === '')
+        problems.push(`imap.host 未填写（可填 provider 预设：${PROVIDER_NAMES.join('/')}）`);
+    if (smtp.host === undefined || smtp.host === '')
+        problems.push('smtp.host 未填写（同上）');
+    if (problems.length > 0) {
+        throw new Error(`dsh-email 未配置：${problems.join('；')}。请在 profile 的 cordis.patch.yml 中覆盖 tool-email 行并重启（见插件 README）`);
+    }
+    return {
+        user,
+        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,
+    };
+}
+export function clampInt(value, fallback, min, max) {
+    const n = typeof value === 'number' ? Math.trunc(value) : fallback;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(min, n));
+}

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+import { type EmailConfig } from './config.js';
+export declare const name = "tool-email";
+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';

package/lib/index.js

@@ -0,0 +1,216 @@
+import { clampInt, resolveEmailConfig } from './config.js';
+import { MailClient, messageOf } from './mail-client.js';
+export const name = 'tool-email';
+export const inject = ['tools'];
+const MAX_LIMIT = 100;
+/** Loose-but-typed output schema; values below carry every declared field. */
+const listSchema = {
+    type: 'object',
+    properties: {
+        count: { type: 'integer' },
+        folder: { type: 'string' },
+        messages: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    uid: { type: 'integer' },
+                    date: { type: 'string' },
+                    from: { type: 'array', items: { type: 'object', additionalProperties: true } },
+                    subject: { type: 'string' },
+                    seen: { type: 'boolean' },
+                    flagged: { type: 'boolean' },
+                    size: { type: 'integer' },
+                    hasAttachments: { type: 'boolean' },
+                },
+                additionalProperties: true,
+            },
+        },
+    },
+    additionalProperties: true,
+};
+const readSchema = {
+    type: 'object',
+    properties: {
+        uid: { type: 'integer' },
+        folder: { type: 'string' },
+        date: { type: 'string' },
+        from: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        to: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        cc: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        subject: { type: 'string' },
+        text: { type: 'string' },
+        attachments: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        truncated: { type: 'boolean' },
+    },
+    additionalProperties: true,
+};
+const sendSchema = {
+    type: 'object',
+    properties: {
+        messageId: { type: 'string' },
+        accepted: { type: 'array', items: { type: 'string' } },
+        rejected: { type: 'array', items: { type: 'string' } },
+        response: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+function oneText(text) {
+    return [{ type: 'text', text }];
+}
+function describeMessage(message) {
+    const from = message.from.map(a => a.name ?? a.address).filter(Boolean).join(', ') || '(未知)';
+    const flags = [
+        message.seen ? '' : '未读',
+        message.flagged ? '已标星' : '',
+        message.hasAttachments ? '含附件' : '',
+    ].filter(Boolean);
+    const parts = [`uid=${message.uid}`, from, message.date];
+    if (flags.length > 0)
+        parts.push(flags.join('、'));
+    return `${message.subject || '(无主题)'} [${parts.join(' | ')}]`;
+}
+function renderList(value) {
+    if (value.messages.length === 0) {
+        return oneText(`文件夹 "${value.folder}" 共 ${value.count} 封邮件，本次没有要列出的邮件。`);
+    }
+    const lines = value.messages.map((m, i) => `#${i + 1} ${describeMessage(m)}`);
+    return oneText(`文件夹 "${value.folder}" 共 ${value.count} 封邮件，最新 ${value.messages.length} 封：\n\n${lines.join('\n')}\n\n用 email_read 配合 uid 阅读全文。`);
+}
+function renderRead(value) {
+    const from = value.from.map(a => a.name ?? a.address).filter(Boolean).join(', ') || '(未知)';
+    const attach = value.attachments.length > 0
+        ? `\n附件：${value.attachments.map(a => `${a.filename}（${a.contentType}，${a.size} 字节）`).join('；')}`
+        : '';
+    return oneText(`主题：${value.subject || '(无主题)'}\n来自：${from}\n时间：${value.date || '(未知)'}${attach}\n\n${value.text}`);
+}
+function renderSearch(value) {
+    if (value.messages.length === 0) {
+        return oneText(`在文件夹 "${value.folder}" 中搜索 "${value.query}"：共 ${value.count} 条匹配，本次没有列出。`);
+    }
+    const lines = value.messages.map((m, i) => `#${i + 1} ${describeMessage(m)}`);
+    return oneText(`在文件夹 "${value.folder}" 中搜索 "${value.query}"：共 ${value.count} 条匹配，展示最新 ${value.messages.length} 条：\n\n${lines.join('\n')}`);
+}
+function renderSend(value) {
+    const rejected = value.rejected.length > 0 ? `；被拒：${value.rejected.join(', ')}` : '';
+    return oneText(`邮件已发送，messageId: ${value.messageId}；成功送达：${value.accepted.join(', ')}${rejected}；服务器响应：${value.response}`);
+}
+export function apply(ctx, config = {}) {
+    // Load-time nudge only: never break boot, tools report the details instead.
+    try {
+        resolveEmailConfig(config);
+    }
+    catch (error) {
+        ctx.logger?.warn?.(`[dsh-email] ${messageOf(error, '未配置邮箱账号')}`);
+    }
+    const resolve = () => resolveEmailConfig(config);
+    ctx.tools.register({
+        name: 'email_list',
+        description: '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.',
+        parameters: {
+            folder: { type: 'string', description: `IMAP folder name, default "${resolveSafeFolder(config)}" (the configured inboxFolder)` },
+            limit: { type: 'integer', description: 'How many messages to return, 1-100, default 20' },
+            offset: { type: 'integer', description: 'Skip this many newest messages first, default 0' },
+            unreadOnly: { type: 'boolean', description: 'Only list unread messages, default false' },
+        },
+        output: {
+            schema: listSchema,
+            render: (_args, value) => renderList(value),
+        },
+        async execute(rawArgs) {
+            const args = rawArgs;
+            const cfg = resolve();
+            const limit = clampInt(args.limit, 20, 1, MAX_LIMIT);
+            const offset = clampInt(args.offset, 0, 0, 10000);
+            return await new MailClient(cfg).list(args.folder?.trim() || cfg.inboxFolder, limit, offset, args.unreadOnly === true);
+        },
+    });
+    ctx.tools.register({
+        name: 'email_read',
+        description: '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.',
+        parameters: {
+            uid: { type: 'integer', required: true, description: 'Message uid from email_list or email_search' },
+            folder: { type: 'string', description: 'IMAP folder the uid belongs to; defaults to the configured inboxFolder' },
+        },
+        output: {
+            schema: readSchema,
+            render: (_args, value) => renderRead(value),
+        },
+        async execute(rawArgs) {
+            const args = rawArgs;
+            const cfg = resolve();
+            if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
+                throw new Error('uid 必须是正整数（用 email_list 获取）');
+            }
+            return await new MailClient(cfg).read(args.uid, args.folder?.trim() || cfg.inboxFolder);
+        },
+    });
+    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.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'Keyword to search for' },
+            folder: { type: 'string', description: 'IMAP folder to search in; defaults to the configured inboxFolder' },
+            limit: { type: 'integer', description: 'How many matches to return, 1-100, default 10' },
+        },
+        output: {
+            schema: listSchema,
+            render: (_args, value) => renderSearch(value),
+        },
+        async execute(rawArgs) {
+            const args = rawArgs;
+            const cfg = resolve();
+            if (typeof args.query !== 'string' || args.query.trim() === '')
+                throw new Error('query 不能为空');
+            const limit = clampInt(args.limit, 10, 1, MAX_LIMIT);
+            return await new MailClient(cfg).search(args.query.trim(), args.folder?.trim() || cfg.inboxFolder, limit);
+        },
+    });
+    ctx.tools.register({
+        name: 'email_send',
+        description: 'Send an email from the configured account. Sending first asks the user for approval (recipient and subject are shown) unless sendApproval is disabled; never invent recipients or content without the user\'s instruction.',
+        parameters: {
+            to: { type: 'string', required: true, description: 'Recipient(s), comma-separated' },
+            subject: { type: 'string', required: true, description: 'Email subject' },
+            text: { type: 'string', description: 'Plain-text body' },
+            cc: { type: 'string', description: 'CC recipient(s), comma-separated' },
+        },
+        output: {
+            schema: sendSchema,
+            render: (_args, value) => renderSend(value),
+        },
+        async execute(rawArgs) {
+            const args = rawArgs;
+            const cfg = resolve();
+            if (typeof args.to !== 'string' || args.to.trim() === '')
+                throw new Error('to 不能为空');
+            if (typeof args.subject !== 'string' || args.subject.trim() === '')
+                throw new Error('subject 不能为空');
+            return await new MailClient(cfg).send(args.to.trim(), args.subject.trim(), typeof args.text === 'string' ? args.text : undefined, typeof args.cc === 'string' && args.cc.trim() !== '' ? args.cc.trim() : undefined);
+        },
+    });
+    // Approval gate: the user must confirm every send (recipient + subject).
+    // Runs before other listeners; degrades to "the tool fails at send time"
+    // only when the account itself is not configured yet.
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        if (exec?.name !== 'email_send')
+            return next();
+        if (config.sendApproval === false)
+            return next();
+        try {
+            resolve();
+        }
+        catch {
+            return next();
+        }
+        const args = (exec.args ?? {});
+        return { kind: 'ask', reason: `发送邮件给 ${args.to}，主题「${args.subject}」` };
+    }, { prepend: true });
+}
+function resolveSafeFolder(config) {
+    return config.inboxFolder?.trim() || 'INBOX';
+}
+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';

package/lib/mail-client.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedEmailConfig } from './config.js';
+import type { EmailListResult, EmailReadResult, EmailSearchResult, EmailSendResult } from './types.js';
+export declare class MailError extends Error {
+    constructor(message: string);
+}
+export declare function messageOf(error: unknown, fallback: string): string;
+/** One IMAP account; every operation opens its own short-lived connection. */
+export declare class MailClient {
+    private readonly config;
+    constructor(config: ResolvedEmailConfig);
+    private createImap;
+    /** Open the mailbox read-only, run the operation, always close. */
+    private withImap;
+    private static fetchQuery;
+    list(folder: string, limit: number, offset: number, unreadOnly: boolean): Promise<EmailListResult>;
+    search(query: string, folder: string, limit: number): Promise<EmailSearchResult>;
+    private fetchListed;
+    read(uid: number, folder: string): Promise<EmailReadResult>;
+    send(to: string, subject: string, text: string | undefined, cc: string | undefined): Promise<EmailSendResult>;
+}

package/lib/mail-client.js

@@ -0,0 +1,170 @@
+import { ImapFlow } from 'imapflow';
+import nodemailer from 'nodemailer';
+import { flattenAddresses } from './parse.js';
+import { parseRawMessage } from './parse.js';
+export class MailError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MailError';
+    }
+}
+export function messageOf(error, fallback) {
+    return error instanceof Error && error.message !== '' ? error.message : fallback;
+}
+/** True when any bodyStructure node declares an attachment disposition. */
+function structureHasAttachment(node) {
+    if (node === null || node === undefined || typeof node !== 'object')
+        return false;
+    if (node.disposition === 'attachment')
+        return true;
+    const children = Array.isArray(node.childNodes) ? node.childNodes : [];
+    return children.some(structureHasAttachment);
+}
+function toIso(date) {
+    return date instanceof Date ? date.toISOString() : '';
+}
+function listedFrom(envelope, size, hasAttachments) {
+    return {
+        uid: envelope.uid,
+        date: toIso(envelope.envelope?.date),
+        from: flattenAddresses(envelope.envelope?.from),
+        subject: envelope.envelope?.subject ?? '',
+        seen: envelope.flags?.has('\\Seen') === true,
+        flagged: envelope.flags?.has('\\Flagged') === true,
+        size: size ?? 0,
+        hasAttachments,
+    };
+}
+/** One IMAP account; every operation opens its own short-lived connection. */
+export class MailClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    createImap() {
+        return new ImapFlow({
+            host: this.config.imap.host,
+            port: this.config.imap.port,
+            secure: this.config.imap.secure,
+            auth: { user: this.config.user, pass: this.config.password },
+            logger: false,
+            connectionTimeout: this.config.imap.connectionTimeoutMs ?? 30000,
+            greetingTimeout: 30000,
+            socketTimeout: this.config.imap.socketTimeoutMs ?? 60000,
+        });
+    }
+    /** Open the mailbox read-only, run the operation, always close. */
+    async withImap(folder, run) {
+        const client = this.createImap();
+        try {
+            await client.connect();
+            await client.mailboxOpen(folder, { readOnly: true });
+            return await run(client);
+        }
+        catch (error) {
+            const raw = messageOf(error, 'IMAP 操作失败');
+            if (raw.toLowerCase().includes('authentication') || raw.toLowerCase().includes('login')) {
+                throw new MailError(`邮箱登录失败：${raw}（请检查 user 与授权码）`);
+            }
+            if (raw.toLowerCase().includes('nonselect') || raw.toLowerCase().includes('does not exist')) {
+                throw new MailError(`找不到邮箱文件夹 "${folder}"：${raw}`);
+            }
+            throw new MailError(raw);
+        }
+        finally {
+            try {
+                await client.logout();
+            }
+            catch { /* already closed */ }
+        }
+    }
+    static fetchQuery = { uid: true, envelope: true, flags: true, size: true, bodyStructure: true };
+    async list(folder, limit, offset, unreadOnly) {
+        return this.withImap(folder, async (client) => {
+            const mailbox = client.mailbox;
+            const total = mailbox === false ? 0 : mailbox.exists;
+            let scopeCount = total;
+            let uids = [];
+            if (unreadOnly) {
+                const found = await client.search({ seen: false }, { uid: true });
+                uids = found === false ? [] : found;
+                scopeCount = uids.length;
+            }
+            else if (total > 0) {
+                const start = Math.max(1, total - (limit + offset) + 1);
+                const fetched = await client.fetchAll(`${start}:*`, { uid: true }, { uid: true });
+                uids = fetched.map(message => message.uid);
+            }
+            // newest first, then the requested window
+            uids.reverse();
+            const window = uids.slice(offset, offset + limit);
+            const messages = await this.fetchListed(client, window);
+            return { count: scopeCount, folder, messages };
+        });
+    }
+    async search(query, folder, limit) {
+        return this.withImap(folder, async (client) => {
+            // No nested OR and no TEXT search: several servers (QQ among them)
+            // silently answer those with empty or match-everything results. Three
+            // independent searches unioned client-side behave well everywhere.
+            const found = await Promise.all([
+                client.search({ subject: query }, { uid: true }),
+                client.search({ from: query }, { uid: true }),
+                client.search({ to: query }, { uid: true }),
+            ]);
+            const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => a - b);
+            uids.reverse();
+            const messages = await this.fetchListed(client, uids.slice(0, limit));
+            return { query, count: uids.length, folder, messages };
+        });
+    }
+    async fetchListed(client, uids) {
+        if (uids.length === 0)
+            return [];
+        const fetched = await client.fetchAll(uids, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true }, { uid: true });
+        return fetched.map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)));
+    }
+    async read(uid, folder) {
+        return this.withImap(folder, async (client) => {
+            const message = await client.fetchOne(uid, { uid: true, source: true }, { uid: true });
+            if (message === false || message.source === undefined) {
+                throw new MailError(`找不到 uid=${uid} 的邮件（可能已被删除，或不在文件夹 "${folder}"；可用 email_list 重新获取 uid）`);
+            }
+            const body = await parseRawMessage(message.source, this.config.maxBodyChars);
+            return { uid, folder, ...body };
+        });
+    }
+    async send(to, subject, text, cc) {
+        const transporter = nodemailer.createTransport({
+            host: this.config.smtp.host,
+            port: this.config.smtp.port,
+            secure: this.config.smtp.secure,
+            auth: { user: this.config.user, pass: this.config.password },
+            connectionTimeout: 30000,
+            greetingTimeout: 10000,
+            socketTimeout: 60000,
+        });
+        try {
+            const info = await transporter.sendMail({
+                from: this.config.user,
+                to,
+                cc,
+                subject,
+                text: text ?? '',
+            });
+            return {
+                messageId: info.messageId,
+                accepted: info.accepted.map(String),
+                rejected: info.rejected.map(String),
+                response: info.response,
+            };
+        }
+        catch (error) {
+            const raw = messageOf(error, 'SMTP 发送失败');
+            throw new MailError(raw.toLowerCase().includes('auth') ? `SMTP 登录失败：${raw}（请检查 user 与授权码）` : raw);
+        }
+        finally {
+            transporter.close();
+        }
+    }
+}

package/lib/parse.d.ts

@@ -0,0 +1,10 @@
+import type { AddressEntry, ReadMessageBody } from './types.js';
+export declare function flattenAddresses(input: unknown): AddressEntry[];
+/** Minimal, dependency-free HTML-to-text: block tags become newlines, tags are dropped, common entities decoded. */
+export declare function stripHtml(html: string): string;
+export declare function truncateText(text: string, maxChars: number): {
+    text: string;
+    truncated: boolean;
+};
+/** Parse a raw RFC822 message source into the read-result body. */
+export declare function parseRawMessage(source: Buffer, maxBodyChars: number): Promise<ReadMessageBody>;

package/lib/parse.js

@@ -0,0 +1,66 @@
+import { simpleParser } from 'mailparser';
+export function flattenAddresses(input) {
+    if (input === null || input === undefined)
+        return [];
+    const list = Array.isArray(input) ? input : input.value;
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .filter(entry => entry !== null && typeof entry === 'object')
+        .map(entry => {
+        const { name, address } = entry;
+        const out = {};
+        if (typeof name === 'string' && name !== '')
+            out.name = name;
+        if (typeof address === 'string' && address !== '')
+            out.address = address;
+        return out;
+    })
+        .filter(entry => entry.address !== undefined || entry.name !== undefined);
+}
+/** Minimal, dependency-free HTML-to-text: block tags become newlines, tags are dropped, common entities decoded. */
+export function stripHtml(html) {
+    let out = html
+        .replace(/<(script|style|head|title)[\s\S]*?<\/\1\s*>/gi, ' ')
+        .replace(/<\/(p|div|tr|li|h[1-6]|table|blockquote|ul|ol|section|article|header|footer)[^>]*>/gi, '\n')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'");
+    out = out.replace(/[ \t]+/g, ' ').replace(/ *\n */g, '\n').replace(/\n{3,}/g, '\n\n');
+    return out.trim();
+}
+export function truncateText(text, maxChars) {
+    if (text.length <= maxChars)
+        return { text, truncated: false };
+    const cut = text.slice(0, maxChars);
+    const lastBreak = Math.max(cut.lastIndexOf('\n'), cut.lastIndexOf(' '), 0);
+    return { text: cut.slice(0, lastBreak) + `\n\n…[正文过长，已截断，共 ${text.length} 字符]`, truncated: true };
+}
+/** Parse a raw RFC822 message source into the read-result body. */
+export async function parseRawMessage(source, maxBodyChars) {
+    const parsed = await simpleParser(source);
+    let text = parsed.text ?? '';
+    if (text.trim() === '' && typeof parsed.html === 'string' && parsed.html.trim() !== '') {
+        text = stripHtml(parsed.html);
+    }
+    const limited = truncateText(text, maxBodyChars);
+    return {
+        date: parsed.date instanceof Date ? parsed.date.toISOString() : '',
+        from: flattenAddresses(parsed.from),
+        to: flattenAddresses(parsed.to),
+        cc: flattenAddresses(parsed.cc),
+        subject: parsed.subject ?? '',
+        text: limited.text,
+        attachments: (parsed.attachments ?? []).map(att => ({
+            filename: att.filename ?? '(unnamed)',
+            contentType: att.contentType,
+            size: att.size,
+        })),
+        truncated: limited.truncated,
+    };
+}

package/lib/types.d.ts

@@ -0,0 +1,75 @@
+/** One address entry as IMAP/MIME expose it. */
+export interface AddressEntry {
+    name?: string;
+    address?: string;
+}
+/** One listed message: everything cheap to fetch without the body. */
+export interface ListedMessage {
+    uid: number;
+    /** ISO 8601 string, or '' when unknown. */
+    date: string;
+    from: AddressEntry[];
+    subject: string;
+    seen: boolean;
+    flagged: boolean;
+    size: number;
+    hasAttachments: boolean;
+}
+/** One fully read message body. */
+export interface ReadMessageBody {
+    date: string;
+    from: AddressEntry[];
+    to: AddressEntry[];
+    cc: AddressEntry[];
+    subject: string;
+    /** Plain-text body; HTML mail is converted. Truncated at maxBodyChars. */
+    text: string;
+    attachments: Array<{
+        filename: string;
+        contentType: string;
+        size: number;
+    }>;
+    truncated: boolean;
+}
+export interface EmailListResult {
+    count: number;
+    folder: string;
+    messages: ListedMessage[];
+}
+export interface EmailReadResult extends ReadMessageBody {
+    uid: number;
+    folder: string;
+}
+export interface EmailSearchResult {
+    query: string;
+    count: number;
+    folder: string;
+    messages: ListedMessage[];
+}
+export interface EmailSendResult {
+    messageId: string;
+    accepted: string[];
+    rejected: string[];
+    response: string;
+}
+export interface EmailListArgs {
+    folder?: string;
+    limit?: number;
+    offset?: number;
+    unreadOnly?: boolean;
+}
+export interface EmailReadArgs {
+    uid: number;
+    folder?: string;
+}
+export interface EmailSearchArgs {
+    query: string;
+    folder?: string;
+    limit?: number;
+}
+export interface EmailSendArgs {
+    to: string;
+    subject: string;
+    text?: string;
+    cc?: string;
+}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "dsh-email",
+  "version": "0.1.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",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "prepublishOnly": "pnpm run build",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\""
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "email",
+    "imap",
+    "smtp"
+  ],
+  "author": "stardustlc",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "imapflow": "^1.7.0",
+    "mailparser": "^3.9.15",
+    "nodemailer": "^9.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/nodemailer": "^8.0.1",
+    "typescript": "^5.7.3"
+  }
+}