dsh-email 0.2.0 → 0.3.0

package/README.md

@@ -29,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（不会出现在任何导出/诊断里）。
 
 ## 配置
 
@@ -119,7 +126,7 @@ dsh plugin --profile web add dsh-email
 ## 已知限制（v0.2）
 
 - **连接复用**：IMAP 按账号池化（空闲自动回收），SMTP 用 nodemailer 连接池；同一账号的并发调用会排队串行（一个连接一次只服务一个操作，这是有意的）。
-- **多账号**：每个账号独立连接池；一个 `tool-email` 行可以配任意多个账号。
+- **多账号**：每个账号独立连接池；一个 `tool-email` 行可以配任意多个账号。设置页编辑的是默认账号；`accounts` 映射仍需写 cordis.patch.yml。
 - **附件下载**：email_attachment 按序号下载（与 email_read 的 attachments 顺序一致）；文件名会被清洗防路径穿越，已有同名文件自动加后缀，大小受 maxAttachmentBytes 限制。
 - **不支持 OAuth2**：强制 OAuth 的企业环境（部分 M365/Google Workspace）暂不可用。
 - 正文搜索不提供：多数服务器（如 QQ）的 IMAP `TEXT`/`HEADER` 搜索要么全量匹配要么不支持，所以只搜主题/发件人/收件人；正文搜索列入后续版本（需客户端下载解析，较慢）。
@@ -129,7 +136,7 @@ dsh plugin --profile web add dsh-email
 ```sh
 pnpm install
 pnpm run build   # tsc → lib/
-pnpm test        # 构建 + node --test（配置/解析/注册与审批门，27 个用例，无需真实邮箱）
+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/index.js

@@ -1,9 +1,38 @@
 import { clampInt, resolveEmailSettings } from './config.js';
 import { EmailPool, messageOf } from './mail-client.js';
+import { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
+import { EmailSettingsBackend, installEmailSettingsWeb } from './web.js';
 export const name = 'tool-email';
-export const inject = ['tools'];
+export const inject = ['settings', 'tools'];
 const MAX_LIMIT = 100;
 const ACCOUNT_HINT = '账号名（配置了 accounts 多个账号时选择），省略时用 defaultAccount。可用账号见 email_folders 的报错或插件 README';
+/**
+ * Compile the author DSL map into a raw JSON Schema object, exactly what
+ * defineTool stores as definition.parameters. The native wire request sends
+ * this value verbatim, so a raw DSL here would be rejected by the model API
+ * ("schema must be a JSON Schema of 'type: object'").
+ */
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        if (prop?.type === 'array' && prop.items !== null && typeof prop.items === 'object') {
+            const items = { type: 'string' };
+            if (prop.items.type === 'object')
+                items.additionalProperties = true;
+            node.items = items;
+        }
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
 const strArray = { type: 'array', items: { type: 'string' } };
 const addrArray = { type: 'array', items: { type: 'object', additionalProperties: true } };
 const messageShape = {
@@ -135,40 +164,62 @@ function renderFolders(value) {
 function renderAttachment(value) {
     return oneText('账号 ' + value.account + ' 已下载附件 "' + value.filename + '"（' + value.contentType + '，' + value.size + ' 字节）到：\n' + value.path + '\n可用 read 工具读取该文件。');
 }
+function fingerprintSettings(settings) {
+    return JSON.stringify({
+        accounts: [...settings.accounts.entries()].map(([name, account]) => [name, account]),
+        defaultAccount: settings.defaultAccount,
+        sendApproval: settings.sendApproval,
+        maxBodyChars: settings.maxBodyChars,
+        downloadDir: settings.downloadDir,
+        maxAttachmentBytes: settings.maxAttachmentBytes,
+        idleTimeoutMs: settings.idleTimeoutMs,
+    });
+}
 export function apply(ctx, config = {}) {
-    let settingsError = '';
-    let settings = null;
-    try {
-        settings = resolveEmailSettings(config);
-    }
-    catch (error) {
-        settingsError = messageOf(error, 'dsh-email 配置无效');
-        ctx.logger?.warn?.('[dsh-email] ' + settingsError);
-    }
+    // The settings namespace is the single source for the default account: the
+    // row config (cordis.patch.yml) is its base layer, the Web settings page
+    // writes the user layer, and resolveEmailSettings merges both at use time.
+    const settingsScope = ctx.settings.register(SETTINGS_NAMESPACE, EmailSettingsSchema, {
+        base: toSettingsBase(config),
+        applies: 'live',
+        validate: (value) => validateSettingsValue(value),
+    });
     let pool = null;
+    let poolFingerprint = '';
     const getPool = () => {
-        if (settingsError !== '')
-            throw new Error(settingsError);
-        if (pool === null) {
-            pool = new EmailPool(settings);
+        const value = settingsScope.get();
+        const effective = resolveEmailSettings({ ...config, ...toEmailConfig(value) });
+        const fp = fingerprintSettings(effective);
+        if (pool === null || fp !== poolFingerprint) {
+            pool?.dispose();
+            pool = new EmailPool(effective);
             pool.startIdleSweep();
+            poolFingerprint = fp;
         }
         return pool;
     };
+    // Load-time nudge only: never break boot, tools report the details instead.
+    try {
+        getPool();
+    }
+    catch (error) {
+        ctx.logger?.warn?.('[dsh-email] ' + messageOf(error, '未配置邮箱账号'));
+    }
     ctx.effect(() => () => {
         pool?.dispose();
         pool = null;
     });
+    installEmailSettingsWeb(ctx, new EmailSettingsBackend(ctx, settingsScope, 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: {
+        parameters: compileParameters({
             folder: { type: 'string', description: 'IMAP folder path (see email_folders); defaults to the account 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' },
             account: { type: 'string', description: ACCOUNT_HINT },
-        },
+        }),
         output: {
             schema: listSchema,
             render: (_args, value) => renderList(value),
@@ -183,11 +234,11 @@ export function apply(ctx, config = {}) {
     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; use email_attachment to download one.',
-        parameters: {
+        parameters: compileParameters({
             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 account inboxFolder' },
             account: { type: 'string', description: ACCOUNT_HINT },
-        },
+        }),
         output: {
             schema: readSchema,
             render: (_args, value) => renderRead(value),
@@ -203,12 +254,12 @@ export function apply(ctx, config = {}) {
     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: {
+        parameters: compileParameters({
             query: { type: 'string', required: true, description: 'Keyword to search for' },
             folder: { type: 'string', description: 'IMAP folder to search in; defaults to the account inboxFolder' },
             limit: { type: 'integer', description: 'How many matches to return, 1-100, default 10' },
             account: { type: 'string', description: ACCOUNT_HINT },
-        },
+        }),
         output: {
             schema: listSchema,
             render: (_args, value) => renderSearch(value),
@@ -224,14 +275,14 @@ export function apply(ctx, config = {}) {
     ctx.tools.register({
         name: 'email_send',
         description: 'Send an email from a configured account, optionally with file attachments (absolute paths, or relative to the dsh process cwd). Sending first asks the user for approval (recipient, subject and attachment count are shown) unless sendApproval is disabled; never invent recipients or content without the user\'s instruction.',
-        parameters: {
+        parameters: compileParameters({
             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' },
             attachments: { type: 'array', items: { type: 'string' }, description: 'File paths to attach (absolute, or relative to the dsh process cwd)' },
             account: { type: 'string', description: ACCOUNT_HINT },
-        },
+        }),
         output: {
             schema: sendSchema,
             render: (_args, value) => renderSend(value),
@@ -248,10 +299,10 @@ export function apply(ctx, config = {}) {
     ctx.tools.register({
         name: 'email_folders',
         description: 'List the mailbox folders of an account (INBOX, Sent, Trash, custom folders, ...). Use the returned path values as the folder argument of the other email tools.',
-        parameters: {
+        parameters: compileParameters({
             subscribedOnly: { type: 'boolean', description: 'Only subscribed folders, default false' },
             account: { type: 'string', description: ACCOUNT_HINT },
-        },
+        }),
         output: {
             schema: foldersSchema,
             render: (_args, value) => renderFolders(value),
@@ -264,12 +315,12 @@ export function apply(ctx, config = {}) {
     ctx.tools.register({
         name: 'email_attachment',
         description: 'Download one attachment of a message to a local file (size capped by maxAttachmentBytes). The index matches the attachments array of email_read. Returns the absolute path of the written file.',
-        parameters: {
+        parameters: compileParameters({
             uid: { type: 'integer', required: true, description: 'Message uid from email_list or email_search' },
             index: { type: 'integer', description: '0-based attachment index, as listed by email_read; default 0' },
             folder: { type: 'string', description: 'IMAP folder the uid belongs to; defaults to the account inboxFolder' },
             account: { type: 'string', description: ACCOUNT_HINT },
-        },
+        }),
         output: {
             schema: attachmentSchema,
             render: (_args, value) => renderAttachment(value),
@@ -289,10 +340,15 @@ export function apply(ctx, config = {}) {
     ctx.on('tools/pre-execute', async (exec, next) => {
         if (exec?.name !== 'email_send')
             return next();
-        if (config.sendApproval === false)
-            return next();
-        if (settingsError !== '')
+        const value = settingsScope.get();
+        if (value.sendApproval === false)
             return next();
+        try {
+            resolveEmailSettings({ ...config, ...toEmailConfig(value) });
+        }
+        catch {
+            return next(); // unconfigured: let the tool report the actionable hint
+        }
         const args = (exec.args ?? {});
         const attachCount = Array.isArray(args.attachments) ? args.attachments.length : 0;
         const reason = '发送邮件给 ' + args.to + '，主题「' + args.subject + '」' + (attachCount > 0 ? '，附件 ' + attachCount + ' 个' : '');

package/lib/settings.d.ts

@@ -0,0 +1,91 @@
+import z from 'schemastery';
+import { type EmailConfig } from './config.js';
+/** Settings-document namespace this plugin owns (editable from the Web settings page). */
+export declare const SETTINGS_NAMESPACE = "dsh-email";
+/**
+ * The settings-page shape: the single default account plus shared policy.
+ * Multi-account (`accounts` map) stays YAML-only; the page edits the
+ * default/shorthand account.
+ */
+export declare const EmailSettingsSchema: z<Schemastery.ObjectS<{
+    provider: z<string, string>;
+    user: z<string, string>;
+    password: z<string, string>;
+    inboxFolder: z<string, string>;
+    sendApproval: z<boolean, boolean>;
+    maxBodyChars: z<number, number>;
+    downloadDir: z<string, string>;
+    imap: z<Schemastery.ObjectS<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>>;
+    smtp: z<Schemastery.ObjectS<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>>;
+}>, Schemastery.ObjectT<{
+    provider: z<string, string>;
+    user: z<string, string>;
+    password: z<string, string>;
+    inboxFolder: z<string, string>;
+    sendApproval: z<boolean, boolean>;
+    maxBodyChars: z<number, number>;
+    downloadDir: z<string, string>;
+    imap: z<Schemastery.ObjectS<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>>;
+    smtp: z<Schemastery.ObjectS<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        host: z<string, string>;
+        port: z<number, number>;
+        secure: z<boolean, boolean>;
+    }>>;
+}>>;
+export interface EmailSettingsValue {
+    provider: string;
+    user: string;
+    password: string;
+    inboxFolder: string;
+    sendApproval: boolean;
+    maxBodyChars: number;
+    downloadDir: string;
+    imap: {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+}
+/** Project the row config (cordis.patch.yml) into the settings-schema base shape. */
+export declare function toSettingsBase(config: EmailConfig): Partial<EmailSettingsValue>;
+/** Project a settings value back into EmailConfig shape ('' becomes unset). */
+export declare function toEmailConfig(value: EmailSettingsValue): EmailConfig;
+/**
+ * Gentle write-path validation: structural mistakes fail loudly, but an
+ * incomplete account is allowed (tools report the actionable hint at call
+ * time, so an unconfigured install never breaks boot).
+ */
+export declare function validateSettingsValue(value: EmailSettingsValue): void;

package/lib/settings.js

@@ -0,0 +1,92 @@
+import z from 'schemastery';
+import { PROVIDER_NAMES } from './config.js';
+/** Settings-document namespace this plugin owns (editable from the Web settings page). */
+export const SETTINGS_NAMESPACE = 'dsh-email';
+/**
+ * The settings-page shape: the single default account plus shared policy.
+ * Multi-account (`accounts` map) stays YAML-only; the page edits the
+ * default/shorthand account.
+ */
+export const EmailSettingsSchema = z.object({
+    provider: z.string().default(''),
+    user: z.string().default(''),
+    password: z.string().role('secret').default(''),
+    inboxFolder: z.string().default('INBOX'),
+    sendApproval: z.boolean().default(true),
+    maxBodyChars: z.number().default(20000),
+    downloadDir: z.string().default(''),
+    imap: z.object({
+        host: z.string().default(''),
+        port: z.number().default(993),
+        secure: z.boolean().default(true),
+    }),
+    smtp: z.object({
+        host: z.string().default(''),
+        port: z.number().default(465),
+        secure: z.boolean().default(true),
+    }),
+});
+/** Project the row config (cordis.patch.yml) into the settings-schema base shape. */
+export function toSettingsBase(config) {
+    return {
+        ...(config.provider !== undefined ? { provider: config.provider } : {}),
+        ...(config.user !== undefined && config.user !== '' ? { user: config.user } : {}),
+        ...(config.password !== undefined && config.password !== '' ? { password: config.password } : {}),
+        ...(config.inboxFolder !== undefined && config.inboxFolder !== '' ? { inboxFolder: config.inboxFolder } : {}),
+        ...(config.sendApproval !== undefined ? { sendApproval: config.sendApproval } : {}),
+        ...(config.maxBodyChars !== undefined ? { maxBodyChars: config.maxBodyChars } : {}),
+        ...(config.downloadDir !== undefined && config.downloadDir !== '' ? { downloadDir: config.downloadDir } : {}),
+        ...(config.imap !== undefined ? {
+            imap: {
+                host: config.imap.host ?? '',
+                port: config.imap.port ?? 993,
+                secure: config.imap.secure ?? true,
+            },
+        } : {}),
+        ...(config.smtp !== undefined ? {
+            smtp: {
+                host: config.smtp.host ?? '',
+                port: config.smtp.port ?? 465,
+                secure: config.smtp.secure ?? true,
+            },
+        } : {}),
+    };
+}
+/** Project a settings value back into EmailConfig shape ('' becomes unset). */
+export function toEmailConfig(value) {
+    return {
+        ...(value.provider !== '' ? { provider: value.provider } : {}),
+        ...(value.user !== '' ? { user: value.user } : {}),
+        ...(value.password !== '' ? { password: value.password } : {}),
+        ...(value.inboxFolder !== '' && value.inboxFolder !== 'INBOX' ? { inboxFolder: value.inboxFolder } : {}),
+        sendApproval: value.sendApproval,
+        maxBodyChars: value.maxBodyChars,
+        ...(value.downloadDir !== '' ? { downloadDir: value.downloadDir } : {}),
+        imap: {
+            ...(value.imap.host !== '' ? { host: value.imap.host } : {}),
+            port: value.imap.port,
+            secure: value.imap.secure,
+        },
+        smtp: {
+            ...(value.smtp.host !== '' ? { host: value.smtp.host } : {}),
+            port: value.smtp.port,
+            secure: value.smtp.secure,
+        },
+    };
+}
+/**
+ * Gentle write-path validation: structural mistakes fail loudly, but an
+ * incomplete account is allowed (tools report the actionable hint at call
+ * time, so an unconfigured install never breaks boot).
+ */
+export function validateSettingsValue(value) {
+    if (value.provider !== '' && !PROVIDER_NAMES.includes(value.provider)) {
+        throw new Error('未知的邮箱服务商 "' + value.provider + '"，可选：' + PROVIDER_NAMES.join('/') + '（或留空手填 IMAP/SMTP 主机）');
+    }
+    if (value.imap.port < 1 || value.imap.port > 65535)
+        throw new Error('IMAP 端口必须在 1-65535 之间');
+    if (value.smtp.port < 1 || value.smtp.port > 65535)
+        throw new Error('SMTP 端口必须在 1-65535 之间');
+    if (value.maxBodyChars < 1000 || value.maxBodyChars > 200000)
+        throw new Error('正文截断上限必须在 1000-200000 之间');
+}

package/lib/web.d.ts

@@ -0,0 +1,42 @@
+import { type EmailSettingsValue } from './settings.js';
+import { type EmailConfig } from './config.js';
+/** Same-origin route the browser settings section talks to. */
+export declare const SETTINGS_ROUTE = "/_dsh/dsh-email/settings";
+/**
+ * Browser-facing backend: snapshot the settings namespace, save it with
+ * optimistic concurrency, and test a draft account over a live IMAP login.
+ */
+export declare class EmailSettingsBackend {
+    private readonly ctx;
+    private readonly scope;
+    private readonly rowConfig;
+    constructor(ctx: any, scope: any, rowConfig: EmailConfig);
+    private effective;
+    snapshot(): Promise<{
+        settings: {
+            value: EmailSettingsValue;
+            revision: any;
+            applies: any;
+        };
+        writable: boolean;
+        accounts: string[];
+    }>;
+    private effectiveAccounts;
+    save(value: EmailSettingsValue, expectedRevision: number): Promise<{
+        settings: {
+            value: EmailSettingsValue;
+            revision: any;
+            applies: any;
+        };
+        writable: boolean;
+        accounts: string[];
+    }>;
+    test(value: EmailSettingsValue): Promise<{
+        ok: boolean;
+        ms: number;
+    }>;
+    responseJson(res: any, status: number, body: unknown): void;
+    handle(req: any, res: any): Promise<void>;
+}
+/** Mount the same-origin route when a webServer service is present. */
+export declare function installEmailSettingsWeb(ctx: any, backend: EmailSettingsBackend): void;

package/lib/web.js

@@ -0,0 +1,138 @@
+import { SETTINGS_NAMESPACE, toEmailConfig, validateSettingsValue } from './settings.js';
+import { resolveEmailSettings } from './config.js';
+import { EmailPool } from './mail-client.js';
+/** Same-origin route the browser settings section talks to. */
+export const SETTINGS_ROUTE = '/_dsh/dsh-email/settings';
+function messageOf2(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Browser-facing backend: snapshot the settings namespace, save it with
+ * optimistic concurrency, and test a draft account over a live IMAP login.
+ */
+export class EmailSettingsBackend {
+    ctx;
+    scope;
+    rowConfig;
+    constructor(ctx, scope, rowConfig) {
+        this.ctx = ctx;
+        this.scope = scope;
+        this.rowConfig = rowConfig;
+    }
+    effective(value) {
+        return { ...this.rowConfig, ...toEmailConfig(value) };
+    }
+    async snapshot() {
+        const descriptor = (this.ctx.settings.describe?.() ?? []).find((row) => row.ns === SETTINGS_NAMESPACE);
+        const value = this.scope.get();
+        return {
+            settings: {
+                value,
+                revision: descriptor?.revision ?? 0,
+                applies: descriptor?.applies ?? 'live',
+            },
+            writable: this.ctx.settings.writable !== false,
+            accounts: [...(this.effectiveAccounts().keys())],
+        };
+    }
+    effectiveAccounts() {
+        try {
+            return resolveEmailSettings(this.effective(this.scope.get())).accounts;
+        }
+        catch {
+            return new Map();
+        }
+    }
+    async save(value, expectedRevision) {
+        if (this.ctx.settings.writable === false)
+            throw new Error('settings provider is read-only');
+        validateSettingsValue(value);
+        await this.ctx.settings.replace(SETTINGS_NAMESPACE, value, expectedRevision);
+        return this.snapshot();
+    }
+    async test(value) {
+        validateSettingsValue(value);
+        const settings = resolveEmailSettings(this.effective(value));
+        const pool = new EmailPool(settings);
+        try {
+            const started = Date.now();
+            await pool.withImap(settings.defaultAccount, null, async () => 'connected');
+            return { ok: true, ms: Date.now() - started };
+        }
+        finally {
+            pool.dispose();
+        }
+    }
+    responseJson(res, status, body) {
+        const bytes = Buffer.from(JSON.stringify(body));
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.setHeader('Content-Length', String(bytes.length));
+        res.setHeader('Cache-Control', 'no-store');
+        res.writeHead(status);
+        res.end(bytes);
+    }
+    async handle(req, res) {
+        if (req.method === 'GET') {
+            try {
+                this.responseJson(res, 200, { ok: true, value: await this.snapshot() });
+            }
+            catch (error) {
+                this.responseJson(res, 503, { ok: false, error: { code: 'unavailable', message: messageOf2(error) } });
+            }
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.setHeader('Allow', 'GET, POST');
+            this.responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET or POST' } });
+            return;
+        }
+        let body;
+        try {
+            const chunks = [];
+            for await (const chunk of req) {
+                const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                if (chunks.reduce((n, c) => n + c.length, 0) + part.length > 256 * 1024)
+                    throw new RangeError('request body too large');
+                chunks.push(part);
+            }
+            body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch (error) {
+            this.responseJson(res, 400, { ok: false, error: { code: 'invalid-request', message: messageOf2(error) } });
+            return;
+        }
+        try {
+            if (body?.action === 'save') {
+                if (!Number.isSafeInteger(body.expectedRevision))
+                    throw new Error('expectedRevision must be a non-negative integer');
+                this.responseJson(res, 200, { ok: true, value: await this.save(body.value, body.expectedRevision) });
+            }
+            else if (body?.action === 'test') {
+                this.responseJson(res, 200, { ok: true, value: await this.test(body.value) });
+            }
+            else {
+                this.responseJson(res, 400, { ok: false, error: { code: 'invalid-request', message: 'unsupported action' } });
+            }
+        }
+        catch (error) {
+            const conflict = error?.code === 'SETTINGS_CONFLICT';
+            this.responseJson(res, conflict ? 409 : 400, {
+                ok: false,
+                error: { code: conflict ? 'settings-conflict' : 'rejected', message: messageOf2(error) },
+            });
+        }
+    }
+}
+/** Mount the same-origin route when a webServer service is present. */
+export function installEmailSettingsWeb(ctx, backend) {
+    ctx.inject(['webServer'], (webCtx) => {
+        webCtx.effect(() => {
+            const dispose = webCtx.webServer.register({
+                kind: 'exact',
+                path: SETTINGS_ROUTE,
+                handler: (req, res) => backend.handle(req, res),
+            });
+            return () => dispose();
+        }, 'dsh-email: web route');
+    });
+}

package/package.json

@@ -1,62 +1,66 @@
-{
-  "name": "dsh-email",
-  "version": "0.2.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",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/STARDUSTLC666/dsh-email"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-email/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-email#readme",
-  "license": "MIT",
-  "packageManager": "pnpm@11.7.0",
-  "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"
-  }
-}
+{
+  "name": "dsh-email",
+  "version": "0.3.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"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/STARDUSTLC666/dsh-email"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-email/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-email#readme",
+  "license": "MIT",
+  "packageManager": "pnpm@11.7.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0",
+    "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"
+  }
+}