dsh-email 0.5.1 → 0.6.0

package/README.en.md

@@ -0,0 +1,128 @@
+# dsh-email
+
+![dsh-email banner](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/banner.png)
+
+Email tools for DeepSeek Harness: let the agent **check the inbox, read mail, search mail, send mail on your behalf, and send/receive attachments** through standard IMAP/SMTP — with one-line presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud. Pure plugin implementation, zero core changes, works out of the box.
+
+Pure Node, **cross-platform** (one codebase for Windows / macOS / Linux), no shell, no native binaries.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `email_list` | List the newest mail in a folder (unread filter, pagination, summaries only, no body) |
+| `email_read` | Read one message's full text by uid (HTML auto-converted to plain text, oversized bodies truncated) |
+| `email_search` | Search sender/recipient/subject by keyword (server-side); with no results, falls back to a body scan of the most recent 30 messages by default |
+| `email_send` | Send mail on your behalf (attachments supported). **Prompts for confirmation before sending by default**, showing recipients, subject and attachment count; only sends after you approve |
+| `email_folders` | List the mailbox folders (INBOX/Sent/Junk/custom…); feed the `path` to other tools |
+| `email_attachment` | Download an attachment by index (saved to the session workspace by default so the model can read it directly; size capped by `maxAttachmentBytes`) |
+
+Example:
+
+> Check the 10 newest unread messages in my QQ mailbox and list the ones that need a reply.
+
+## Installation
+
+```sh
+dsh plugin --profile web add dsh-email
+```
+
+(Or install from GitHub: `dsh plugin --profile web add github:your-account/dsh-email#<commit>`, then follow the prompt to authorize the `prepare` build in the profile's `pnpm-workspace.yaml`.)
+
+After installing, restart `dsh web`. The plugin ships with an empty config and **won't crash startup**; calling any email tool before configuration returns a clear configuration hint.
+
+**Two configuration methods (pick one):**
+
+1. **Web settings (recommended)**: after restart, open **Settings → Mail (dsh-email)**, fill in the email address and authorization code, and click "Save & Apply"; a "Test connection" button is also provided. Zero YAML, zero restart.
+2. **YAML**: hand-write the cordis.patch.yml template below; the settings page's "Multiple accounts (advanced, YAML)" textbox can also hold the account map (overriding `accounts` in YAML).
+
+Values saved in the settings page live in the `dsh-email` namespace of `settings.yaml` and override the YAML default-account config; password fields are marked secret (they never appear in exports or diagnostics).
+
+## Configuration
+
+In your profile's `cordis.patch.yml` (under `$DSH_HOME/profiles/<name>/`), override the `tool-email` line, then restart:
+
+```yaml
+- id: tool-email
+  config:
+    provider: qq          # qq | 163 | 126 | sina | aliyun | gmail | outlook | icloud
+    user: you@qq.com
+    password: 你的授权码   # 强烈建议改用环境变量 DSH_EMAIL_PASSWORD，见下
+```
+
+No preset needed? Hand-write any IMAP/SMTP server:
+
+```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
+```
+
+Multiple accounts: one `tool-email` line can hold several mailboxes; select one with the `account` argument when calling a tool:
+
+```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
+```
+
+Top-level `provider`/`user`/`password`/`imap`/`smtp`/`inboxFolder` remain available as shared defaults for all accounts (the v0.1 single-account style stays fully compatible).
+
+## Presets
+
+| 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) |
+
+## Getting an authorization code
+
+Every provider requires an authorization code / app-specific password instead of your login password:
+
+- **QQ Mail**: Settings → Account → enable IMAP/SMTP → generate authorization code
+- **163/126**: Settings → POP3/SMTP/IMAP → enable → add authorization code
+- **Gmail**: enable 2-Step Verification → Security → App passwords
+- **Outlook**: Microsoft account security → App password (some accounts need 2-step verification first)
+
+## Security
+
+- **The authorization code is the key to your mailbox.** It lives on this machine (`cordis.patch.yml` or `settings.yaml` in the profile); never commit it to any Git repo; prefer the `DSH_EMAIL_PASSWORD` env var.
+- `email_send` goes through the DSH approval channel by default: every send shows "send mail to xx, subject "xx"" and only sends after you approve. Environments without an approval channel (e.g. headless with no UI) **refuse to send outright** — that is the secure default.
+- When the session is in **Full Access** mode, the harness approval policy is never (no confirmation dialogs) — `email_send` is **blocked with a clear hint**. Two ways out: ① switch the access mode back to Read Only / Write; ② turn off `sendApproval` (uncheck "Confirm before sending" in the settings page), explicitly declaring you accept the risk.
+- This plugin performs no outbound telemetry; credentials are used in memory only to connect to your mail servers.
+
+## Known limitations (v0.6)
+
+- **Connection reuse**: IMAP is pooled per account (idle connections auto-recycled); SMTP uses nodemailer's connection pool. Concurrent calls for the same account queue serially (one connection serves one operation at a time — intentional).
+- **Multiple accounts**: each account has its own connection pool; one `tool-email` line can hold any number of accounts. The settings page's "Multiple accounts (advanced, YAML)" textbox can directly edit the map (including a `defaultAccount` key), overriding `accounts` in cordis.patch.yml.
+- **Attachment download**: `email_attachment` locates attachments from `email_read`'s attachment list (matching by filename first, then type+size to the IMAP part; a failed match errors instead of downloading the wrong file); inline images aren't downloadable yet; filenames are sanitized against path traversal, existing names get a suffix, and size is capped by `maxAttachmentBytes`.
+- **No OAuth2**: enterprise environments that force OAuth (some M365/Google Workspace) aren't usable yet.
+- **Body search uses client-side fallback**: most servers (e.g. QQ) have unreliable IMAP `TEXT`/`HEADER` search, so the server side only searches subject/sender/recipient; with no results it falls back to a body scan of the most recent `bodySearchLimit` messages (slower; disable with `bodySearchFallback`).
+- **Password storage form**: the authorization code saved in the settings page is written in plaintext to the local `settings.yaml` (the schema's secret mark only keeps it out of logs/exports/diagnostics; no disk encryption). Don't hand settings.yaml to untrusted people.
+- **Settings page vs. plugin-set changes**: saving in the settings page takes effect **immediately** (live), no restart needed; but upgrading or adding/removing plugins (composition-tree changes) still requires restarting `dsh web`.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build   # tsc → lib/
+pnpm test        # 构建 + node --test（配置/解析/注册与审批门，43 个用例，无需真实邮箱）
+```
+
+## License
+
+MIT. This is a community plugin, not affiliated with DeepSeek; `@deepseek-ai/*` is an officially reserved namespace.

package/README.md

@@ -1,3 +1,5 @@
+[English](README.en.md)
+
 # dsh-email
 
 ![dsh-email banner](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/banner.png)
@@ -37,7 +39,7 @@ dsh plugin --profile web add dsh-email
 **配置方式有两种（任选其一）：**
 
 1. **网页设置（推荐）**：重启后打开 **设置 → 邮件 (dsh-email)**，表单里填邮箱地址和授权码，点「保存并应用」，还带「测试连接」按钮。零 YAML、零重启。
-2. **YAML**：按下面的 cordis.patch.yml 模板手写（多账号 accounts 映射目前只支持这种方式）。
+2. **YAML**：按下面的 cordis.patch.yml 模板手写；设置页的「多账号（高级，YAML）」文本框也能填账号映射（覆盖 YAML 里的 accounts）。
 
 设置页保存的值存在 `settings.yaml` 的 `dsh-email` 命名空间里，覆盖 YAML 的默认账号配置；密码字段标记为 secret（不会出现在任何导出/诊断里）。
 
@@ -105,6 +107,7 @@ dsh plugin --profile web add dsh-email
 | `sendApproval` | `true` | 发信前弹确认（强烈建议保留） |
 | `maxBodyChars` | `20000` | email_read 正文截断上限（1000–200000） |
 | `accounts` | 无 | 具名账号表；账号级字段覆盖顶层简写 |
+| `accountsYaml` | 无 | 设置页「多账号（高级）」文本框的 YAML 文本；非空时覆盖 accounts |
 | `defaultAccount` | 单账号时自动 | 工具省略 account 参数时使用的账号（多账号必填） |
 | `downloadDir` | 会话工作区下 .dsh-email-downloads（回退 $DSH_HOME/email-downloads） | email_attachment 的落盘目录；显式设置后固定 |
 | `maxAttachmentBytes` | 20 MiB | 单个附件与附件总大小上限（1024–512 MiB） |
@@ -131,7 +134,7 @@ dsh plugin --profile web add dsh-email
 ## 已知限制（v0.3）
 
 - **连接复用**：IMAP 按账号池化（空闲自动回收），SMTP 用 nodemailer 连接池；同一账号的并发调用会排队串行（一个连接一次只服务一个操作，这是有意的）。
-- **多账号**：每个账号独立连接池；一个 `tool-email` 行可以配任意多个账号。设置页编辑的是默认账号；`accounts` 映射仍需写 cordis.patch.yml。
+- **多账号**：每个账号独立连接池；一个 `tool-email` 行可以配任意多个账号。设置页的「多账号（高级，YAML）」文本框可直接编辑映射（可含 defaultAccount 键），覆盖 cordis.patch.yml 的 accounts。
 - **附件下载**：email_attachment 按 email_read 的附件列表定位（先按文件名、再按类型+大小匹配到 IMAP 部件，定位失败会报错而不是下载错文件）；内嵌图片暂不支持下载；文件名会被清洗防路径穿越，已有同名文件自动加后缀，大小受 maxAttachmentBytes 限制。
 - **不支持 OAuth2**：强制 OAuth 的企业环境（部分 M365/Google Workspace）暂不可用。
 - 正文搜索走客户端回退：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索不可靠，所以服务器端只搜主题/发件人/收件人；无结果时回退到最近 `bodySearchLimit` 封的正文扫描（较慢，可关 `bodySearchFallback`）。
@@ -143,9 +146,15 @@ dsh plugin --profile web add dsh-email
 ```sh
 pnpm install
 pnpm run build   # tsc → lib/
-pnpm test        # 构建 + node --test（配置/解析/注册与审批门，40 个用例，无需真实邮箱）
+pnpm test        # 构建 + node --test（配置/解析/注册与审批门，43 个用例，无需真实邮箱）
 ```
 
 ## 协议
 
 MIT。这是一个社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*` 为官方保留命名空间。
+
+## 相关插件
+
+- [dsh-slack](https://github.com/STARDUSTLC666/dsh-slack) — Slack 通知/收件箱
+- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）
+- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件六件套 + Web 设置页

package/lib/client.js

@@ -45,6 +45,7 @@ const EMPTY = {
   inboxFolder: "INBOX",
   sendApproval: true,
   downloadDir: "",
+  accountsYaml: "",
   imap: { host: "", port: 993, secure: true },
   smtp: { host: "", port: 465, secure: true },
 };
@@ -227,6 +228,18 @@ function EmailSettingsSection() {
         h("label", null, "附件下载目录（默认 $DSH_HOME/email-downloads）"),
         fieldInput("text", draft.downloadDir, (v) => update({ downloadDir: v }), "留空使用默认"),
       ]),
+      h("details", { className: "dshe-details" }, [
+        h("summary", null, "多账号（高级，YAML）"),
+        h("div", { className: "dshe-field", style: { marginTop: 10 } }, [
+          h("textarea", {
+            rows: 7,
+            value: draft.accountsYaml || "",
+            placeholder: "work: { provider: qq, user: work@qq.com, password: 授权码1 }\nhome: { provider: '163', user: home@163.com, password: 授权码2 }\ndefaultAccount: work",
+            onChange: (e) => update({ accountsYaml: e.target.value }),
+          }),
+          h("div", { className: "dshe-hint" }, "账号名 -> 配置的映射，可含 defaultAccount 键。填了这里会覆盖 cordis.patch.yml 里的 accounts 映射；工具调用时用 account 参数选账号。"),
+        ]),
+      ]),
       h("details", { className: "dshe-details" }, [
         h("summary", null, "高级：自定义服务器（选了预设可留空）"),
         h("div", { className: "dshe-grid", style: { marginTop: 10 } }, [

package/lib/config.d.ts

@@ -27,6 +27,8 @@ export interface EmailConfig extends AccountConfig {
     maxBodyChars?: number;
     /** Named accounts. Account-level fields override the top-level shorthand. */
     accounts?: Record<string, AccountConfig>;
+    /** YAML text of the accounts map, editable from the settings page. Wins over accounts when non-empty. */
+    accountsYaml?: string;
     /** Which account tools use when the call omits account. Required with 2+ accounts. */
     defaultAccount?: string;
     /** Directory email_attachment writes into. Default: the session workspace's .dsh-email-downloads (falls back to $DSH_HOME/email-downloads). */
@@ -86,6 +88,14 @@ export interface ResolvedEmailSettings {
     bodySearchLimit: number;
 }
 export declare function defaultDownloadDir(): string;
+/**
+ * Parse the settings-page accounts YAML: an object map (name -> account),
+ * optionally with a reserved string key defaultAccount that is extracted.
+ */
+export declare function parseAccountsYaml(text: string): {
+    map: Record<string, AccountConfig>;
+    defaultAccount?: 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

package/lib/config.js

@@ -1,4 +1,5 @@
 import { homedir } from 'node:os';
+import { parse as parseYaml } from 'yaml';
 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 } },
@@ -18,6 +19,33 @@ export function defaultDownloadDir() {
     const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
     return join(home, 'email-downloads');
 }
+/**
+ * Parse the settings-page accounts YAML: an object map (name -> account),
+ * optionally with a reserved string key defaultAccount that is extracted.
+ */
+export function parseAccountsYaml(text) {
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch (error) {
+        throw new Error('dsh-email：accountsYaml 不是合法的 YAML：' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new Error('dsh-email：accountsYaml 必须是一个对象映射（账号名 -> 账号配置），例如 work: { provider: qq, user: a@b.c, password: xxx }');
+    }
+    const map = {};
+    let defaultAccount;
+    for (const [key, value] of Object.entries(doc)) {
+        if (key === 'defaultAccount') {
+            if (typeof value === 'string' && value !== '')
+                defaultAccount = value;
+            continue;
+        }
+        map[key] = value;
+    }
+    return { map, defaultAccount };
+}
 /**
  * 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
@@ -33,9 +61,10 @@ export function resolveEmailSettings(config) {
         smtp: raw.smtp,
         inboxFolder: raw.inboxFolder,
     };
-    const entries = raw.accounts === undefined || Object.keys(raw.accounts).length === 0
-        ? undefined
-        : raw.accounts;
+    const parsedYaml = raw.accountsYaml?.trim() ? parseAccountsYaml(raw.accountsYaml) : undefined;
+    const entries = parsedYaml !== undefined
+        ? parsedYaml.map
+        : (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));
@@ -55,6 +84,9 @@ export function resolveEmailSettings(config) {
     else if (accounts.size === 1) {
         defaultName = [...accounts.keys()][0];
     }
+    else if (parsedYaml?.defaultAccount !== undefined && accounts.has(parsedYaml.defaultAccount)) {
+        defaultName = parsedYaml.defaultAccount;
+    }
     else if (accounts.has('default')) {
         defaultName = 'default';
     }

package/lib/index.d.ts

@@ -4,7 +4,7 @@ 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, resolveEmailSettings, clampInt, defaultDownloadDir } from './config.js';
+export { resolveEmailConfig, resolveEmailSettings, parseAccountsYaml, clampInt, defaultDownloadDir } from './config.js';
 export { stripHtml, truncateText, flattenAddresses, sanitizeFilename, parseRawMessage } from './parse.js';
 export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart, messageMatchesQuery } from './mail-client.js';
 export { SETTINGS_NAMESPACE, EmailSettingsSchema, toSettingsBase, toEmailConfig, validateSettingsValue } from './settings.js';

package/lib/index.js

@@ -393,7 +393,7 @@ export function apply(ctx, config = {}) {
     }, { prepend: true });
 }
 export { PROVIDER_NAMES, EMAIL_PASSWORD_ENV } from './config.js';
-export { resolveEmailConfig, resolveEmailSettings, clampInt, defaultDownloadDir } from './config.js';
+export { resolveEmailConfig, resolveEmailSettings, parseAccountsYaml, clampInt, defaultDownloadDir } from './config.js';
 export { stripHtml, truncateText, flattenAddresses, sanitizeFilename, parseRawMessage } from './parse.js';
 export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart, messageMatchesQuery } from './mail-client.js';
 export { SETTINGS_NAMESPACE, EmailSettingsSchema, toSettingsBase, toEmailConfig, validateSettingsValue } from './settings.js';

package/lib/settings.d.ts

@@ -15,6 +15,7 @@ export declare const EmailSettingsSchema: z<Schemastery.ObjectS<{
     sendApproval: z<boolean, boolean>;
     maxBodyChars: z<number, number>;
     downloadDir: z<string, string>;
+    accountsYaml: z<string, string>;
     imap: z<Schemastery.ObjectS<{
         host: z<string, string>;
         port: z<number, number>;
@@ -41,6 +42,7 @@ export declare const EmailSettingsSchema: z<Schemastery.ObjectS<{
     sendApproval: z<boolean, boolean>;
     maxBodyChars: z<number, number>;
     downloadDir: z<string, string>;
+    accountsYaml: z<string, string>;
     imap: z<Schemastery.ObjectS<{
         host: z<string, string>;
         port: z<number, number>;
@@ -68,6 +70,7 @@ export interface EmailSettingsValue {
     sendApproval: boolean;
     maxBodyChars: number;
     downloadDir: string;
+    accountsYaml: string;
     imap: {
         host: string;
         port: number;

package/lib/settings.js

@@ -15,6 +15,7 @@ export const EmailSettingsSchema = z.object({
     sendApproval: z.boolean().default(true),
     maxBodyChars: z.number().default(20000),
     downloadDir: z.string().default(''),
+    accountsYaml: z.string().role('secret').default(''),
     imap: z.object({
         host: z.string().default(''),
         port: z.number().default(993),
@@ -77,6 +78,8 @@ export function toEmailConfig(value, user) {
         out.maxBodyChars = value.maxBodyChars;
     if (has('downloadDir'))
         out.downloadDir = value.downloadDir;
+    if (has('accountsYaml'))
+        out.accountsYaml = value.accountsYaml;
     if (user === null || user?.imap !== undefined) {
         const fields = user === null ? value.imap : (user.imap ?? {});
         const imap = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-email",
-  "version": "0.5.1",
+  "version": "0.6.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",
@@ -60,10 +60,11 @@
     }
   },
   "dependencies": {
-    "schemastery": "^3.18.0",
     "imapflow": "^1.7.0",
     "mailparser": "^3.9.15",
-    "nodemailer": "^9.0.5"
+    "nodemailer": "^9.0.5",
+    "schemastery": "^3.18.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",