dsh-email 0.16.3 → 0.17.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.17.1（2026-10-18）
+
+- 完成 [#19](https://github.com/STARDUSTLC666/dsh-email/issues/19) 的发信策略说明：全局确认开关关闭时，账号页显示中英文影响范围，明确所有账号的模型发信、回复和转发都不再逐次确认；只读设置不能编辑该开关。
+- 区分按账号的可信名单与全局关闭确认，说明禁止名单、宿主权限和草稿手动确认继续生效；增加可信名单和全局关闭确认均保留宿主拒绝结果的回归。
+- 修复新版宿主中切换全局设置后，空服务商字段使手填服务器账号报 `provider "" 未知` 的问题；单账号、多账号与 YAML 账号均保留原服务器和凭据。
+
+## 0.17.0（2026-10-17）
+
+- 设置面板顶部新增「首次使用」分步引导：一次只讲一步，支持上一步/下一步/跳过，看完记在本机不再出现。
+- 引导内容与该插件的实际用法一致；可在开发者工具里清掉 `dsh-first-run:dsh-email:v1` 重新查看。
 ## 0.16.3 (2026-10-17)
 
 - 修复未配置邮箱时，服务商示例列表被凭据脱敏器误隐藏的问题；保留真实凭据的原有脱敏规则。

package/docs/DRAFTS.en.md

@@ -43,6 +43,14 @@ trustedRecipientsYaml: |
 
 Renaming an account does not transfer old rules. Rule changes do not reconnect the mailbox.
 
+## Global send confirmation
+
+At the top of Settings → Email → Accounts, use “Confirm model-initiated sends.” It is on by default. Turning it off saves automatically and displays the scope of the change.
+
+This is the global `sendApproval` setting and affects every account. With it off, model calls to `email_send` and `email_reply` (including reply-all and forward) skip the plugin's individual confirmation, including recipients outside the trusted list. Account trust rules only skip confirmation for `email_send` when every To/Cc recipient matches; they do not mean unrestricted sending.
+
+Blocked addresses and domains still stop delivery before an SMTP connection. Host permissions still apply, and the Drafts tab still requires human review and explicit send confirmation. Keep global confirmation on and configure account trust rules to allow only selected recipients.
+
 ## Storage and limits
 
 Drafts live at `DSH_HOME/data/dsh-email/drafts-v1.json`, with uploads under `draft-uploads`. Without DSH_HOME the default is `~/.dsh`. Profiles sharing DSH_HOME share drafts; accounts resolve against the current profile and the actual identity appears in review.

package/docs/DRAFTS.md

@@ -43,6 +43,14 @@ trustedRecipientsYaml: |
 
 账号改名后旧规则不会自动作用于新账号。规则变化不会重建邮箱连接。
 
+## 全局发信确认
+
+在「设置 → 邮件 → 邮箱账号」顶部，可切换「模型发信前确认」。默认开启；关闭会自动保存，并显示影响范围提示。
+
+这个开关对应全局 `sendApproval`，对所有账号生效。关闭后，模型调用 `email_send` 或 `email_reply`（含回复全部、转发）不再经过插件逐次确认，即使收件人不在可信名单中。按账号的可信名单仍只对全部 To/Cc 均匹配的 `email_send` 跳过确认，不能等同于完全开放。
+
+禁止地址和禁止域名继续在 SMTP 连接前拦截；宿主权限仍生效，草稿页仍需人工核对并确认发送。只想放行特定收件人时，保留全局确认并配置账号的可信规则即可。
+
 ## 存储与范围
 
 草稿保存于 `DSH_HOME/data/dsh-email/drafts-v1.json`，上传副本位于其下 `draft-uploads`。未指定 DSH_HOME 时使用 `~/.dsh`。同一 DSH_HOME 共用草稿，发件账号以当前 profile 配置为准，预览会显示实际身份。

package/docs/VALIDATION.md

@@ -1,5 +1,7 @@
 # dsh-email 验证记录
 
+[0.17.1 发信策略与设置保存验收](validation/0.17.1.md)。
+
 [0.16.3 · DSH 0.2.1-alpha.5 浏览器操作验收](validation/0.16.3.md)。
 
 [0.16.2 Windows 令牌加密与迁移验收](validation/0.16.2.md)。

package/docs/validation/0.17.1.md

@@ -0,0 +1,29 @@
+# 0.17.1 发信策略与设置保存验收
+
+日期：2026-10-18。对应 [Issue #19](https://github.com/STARDUSTLC666/dsh-email/issues/19)。
+
+环境：Windows x64、Node 24.16.0、官方 npm `@deepseek-ai/dsh@0.2.1-rc.2`，独立 `DSH_HOME`。实际安装候选 tarball；两个账号的 SMTP 均指向 `127.0.0.1` 测试服务，地址使用 `.invalid`。
+
+## 改动
+
+- 账号页已有全局 `sendApproval` 开关；关闭后新增中英文影响范围提示，只读设置不能编辑该开关。可信名单仍是按账号、所有 To/Cc 均匹配才跳过 `email_send` 确认。
+- 修复新版宿主直接保存空服务商后，自定义 IMAP/SMTP 账号报 `provider "" 未知`。空选择与旧设置投影、YAML 序列化一致地按未设置处理，未知的非空服务商仍报错。
+
+## 验证结果
+
+| 检查 | 结果 |
+| :-- | :-- |
+| 空服务商回归 | 修复前新增测试失败；修复后单账号、账号映射、YAML、账号级空值均保留服务器与凭据 |
+| 本地全套测试 | 349 项通过，0 失败、0 跳过 |
+| 真实宿主允许分支 | 可信 To/Cc 实际提交到本机 SMTP；全局关闭确认后两个账号均可向未列入可信名单的地址提交 |
+| 拒绝优先与宿主权限 | 被禁止的 Cc 覆盖可信规则；全局关闭确认时，禁止地址和真实 `tools.guard()` 拒绝仍阻止 SMTP 提交 |
+| 实际页面保存后发送 | 浏览器切换开关并自动保存后，两张自定义账号卡片仍可解析，后续工具发信获得本机 SMTP 回执 |
+| 页面与持久化 | 中文提示可见；重载保留开关与提示；切换英文正常；重新开启后提示消失并保存 |
+| 页面布局与可访问性 | 提示由复选框的 `aria-describedby` 关联；检查时内容宽度与滚动宽度均为 605px，无控制台错误 |
+| 草稿确认 | 在真实宿主中关闭全局确认后，草稿预览成功，未明确确认的发送仍返回 400 |
+
+## 未验证范围
+
+本轮没有运行真实模型回合中的逐次审批弹框。宿主工具 API 在缺少活跃模型回合时不能完成该交互；默认确认、混合名单、其他账号、子域名与回复策略另有自动契约测试，不把非回合调用的失败算成交互审批验收。
+
+未连接个人邮箱、真实 IMAP 或外部 SMTP，也未验证 OAuth 登录、实际收件箱投递或原生 Desktop 窗口操作。

package/lib/client.js

@@ -9,6 +9,71 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const React = require("react");
 const { useState, useEffect, useCallback, useRef } = React;
 const h = React.createElement;
+const __FR_KEY = 'dsh-first-run:dsh-email:v1';
+const __FR_TITLE = '邮件 · 首次使用（4 步）';
+const __FR_STEPS = [
+  { title: '先把账号填上', body: '下面填 IMAP / SMTP 地址与授权码（QQ 邮箱用「授权码」，不是登录密码）。保存后这里会显示连接状态。' },
+  { title: '看一眼收件箱', body: '连接成功后，下方会列出最近邮件的标题与发件人；点开任意一封可读正文。' },
+  { title: '让它替你整理', body: '在对话里直接说你要做的事，比在页面里逐个点更快。', tryIt: '把今天的未读邮件按主题归纳一下' },
+  { title: '发信前一定先看草稿', body: '涉及发信时默认先生成草稿给你确认，确认后才真正发送；收件人规则在下方「发信规则」里配。' },
+];
+
+// ---- first-run guide (shared snippet, keep in sync across plugins) ----
+const __FR_STYLE_ID = 'dsh-first-run-css';
+const __FR_CSS = [
+  '.fr-card{border:1px solid var(--dsw-border,rgba(0,0,0,.10));border-radius:12px;padding:14px 16px;margin:0 0 14px;background:linear-gradient(180deg,rgba(59,130,246,.06),rgba(59,130,246,.02))}',
+  '.fr-head{display:flex;align-items:center;gap:8px;margin-bottom:6px}',
+  '.fr-dot{width:6px;height:6px;border-radius:50%;background:var(--dsw-accent,#3b82f6)}',
+  '.fr-title{font-weight:650;font-size:13.5px}',
+  '.fr-count{margin-left:auto;font-size:11px;color:var(--dsw-text-weak,#6b7280);font-variant-numeric:tabular-nums}',
+  '.fr-step{font-weight:600;font-size:13px;margin:2px 0 4px}',
+  '.fr-body{color:var(--dsw-text-weak,#4b5563);font-size:12.5px;line-height:1.65}',
+  '.fr-try{margin-top:8px;padding:7px 9px;border-radius:8px;background:rgba(59,130,246,.09);font-size:12px;display:flex;gap:8px}',
+  '.fr-try code{font-family:ui-monospace,monospace;white-space:pre-wrap;word-break:break-word}',
+  '.fr-bar{display:flex;gap:8px;align-items:center;margin-top:12px}',
+  '.fr-progress{display:flex;gap:4px;margin-right:auto}',
+  '.fr-seg{width:16px;height:3px;border-radius:2px;background:var(--dsw-border,rgba(0,0,0,.12))}',
+  '.fr-seg.on{background:var(--dsw-accent,#3b82f6)}',
+  '.fr-btn{border:1px solid var(--dsw-border,rgba(0,0,0,.14));background:transparent;color:inherit;border-radius:8px;padding:4px 10px;font-size:12px;cursor:pointer}',
+  '.fr-btn:hover{background:rgba(0,0,0,.04)}',
+  '.fr-btn.primary{background:var(--dsw-accent,#3b82f6);border-color:transparent;color:#fff}',
+  '.fr-btn.ghost{border-color:transparent;color:var(--dsw-text-weak,#6b7280)}',
+].join('\n');
+function __frEnsureCss() {
+  if (document.getElementById(__FR_STYLE_ID)) return;
+  const el = document.createElement('style');
+  el.id = __FR_STYLE_ID;
+  el.textContent = __FR_CSS;
+  document.head.appendChild(el);
+}
+function __frRead() { try { return localStorage.getItem(__FR_KEY) === 'done'; } catch { return false; } }
+function __frWrite() { try { localStorage.setItem(__FR_KEY, 'done'); } catch {} }
+function __FirstRunCard() {
+  const [done, setDone] = React.useState(__frRead);
+  const [index, setIndex] = React.useState(0);
+  React.useEffect(() => { __frEnsureCss(); }, []);
+  if (done) return null;
+  const step = __FR_STEPS[index];
+  const last = index >= __FR_STEPS.length - 1;
+  const close = () => { __frWrite(); setDone(true); };
+  return h('div', { className: 'fr-card' },
+    h('div', { className: 'fr-head' }, h('span', { className: 'fr-dot' }), h('span', { className: 'fr-title' }, __FR_TITLE), h('span', { className: 'fr-count' }, (index + 1) + ' / ' + __FR_STEPS.length)),
+    h('div', { className: 'fr-step' }, step.title),
+    h('div', { className: 'fr-body' }, step.body),
+    step.tryIt ? h('div', { className: 'fr-try' }, h('span', null, '可以直接说'), h('code', null, '「' + step.tryIt + '」')) : null,
+    h('div', { className: 'fr-bar' },
+      h('div', { className: 'fr-progress' }, __FR_STEPS.map((_, i) => h('span', { key: i, className: 'fr-seg' + (i <= index ? ' on' : '') }))),
+      h('button', { className: 'fr-btn ghost', type: 'button', onClick: close }, '跳过'),
+      index > 0 ? h('button', { className: 'fr-btn', type: 'button', onClick: () => setIndex(index - 1) }, '上一步') : null,
+      h('button', { className: 'fr-btn primary', type: 'button', onClick: () => { if (last) close(); else setIndex(index + 1); } }, last ? '开始使用' : '下一步')));
+}
+function __withFirstRun(Component) {
+  return function FirstRunWrapped(props) {
+    return h(React.Fragment, null, h(__FirstRunCard, null), h(Component, props));
+  };
+}
+// ---- end first-run guide ----
+
 
 // Harness supplies document.baseURI for reverse-proxy mounts and in-page navigation.
 const ROUTE = "_dsh/dsh-email/settings";
@@ -293,6 +358,7 @@ var UI = {
 
     // 全局设置
     "global.sendApproval": "模型发信前确认（建议保留；可信规则可按账号跳过）",
+    "global.sendApprovalRisk": "关闭后，所有账号的模型发信、回复和转发将不再逐次询问，未列入可信名单的收件人也可能直接收到邮件。禁止收件人规则和宿主权限继续生效；草稿页仍需手动确认发送。",
     "global.downloadDirLabel": "附件下载目录（默认保存在当前工作区）",
     "global.downloadDirPlaceholder": "留空使用默认",
     "global.hint": "以上设置对所有账号统一生效。需要插件确认的工具发信在 Full Access 下不会弹框；可改用草稿页手动核对并确认。禁止收件人规则始终生效。",
@@ -474,6 +540,7 @@ var UI = {
 
     // 全局设置
     "global.sendApproval": "Confirm model-initiated sends (recommended; saved trust can skip per account)",
+    "global.sendApprovalRisk": "With this off, model-initiated sends, replies and forwards skip this plugin's confirmation for every account, including recipients outside the trusted list. Blocked-recipient rules and host permissions still apply. Drafts still require manual send confirmation.",
     "global.downloadDirLabel": "Attachment download directory (defaults to the current workspace)",
     "global.downloadDirPlaceholder": "Leave empty for the default",
     "global.hint": "These settings apply to every account. Tool sends that still require plugin confirmation cannot show a dialog under Full Access; use the Drafts tab to review and confirm manually. Blocked-recipient rules always apply.",
@@ -2620,10 +2687,15 @@ function EmailSettingsSection() {
           h("input", {
             type: "checkbox",
             checked: draft.sendApproval === true,
+            disabled: snapshot?.writable === false,
+            "aria-describedby": draft.sendApproval === false ? "dshe-send-approval-risk" : undefined,
             onChange: (e) => update({ sendApproval: e.target.checked }),
           }),
           t("global.sendApproval"),
         ]),
+        draft.sendApproval === false
+          ? h("div", { id: "dshe-send-approval-risk", className: "dshe-alert info", role: "status" }, t("global.sendApprovalRisk"))
+          : null,
         h("div", { className: "dshe-field" }, [
           h("label", null, t("global.downloadDirLabel")),
           fieldInput("text", draft.downloadDir, (v) => update({ downloadDir: v }), t("global.downloadDirPlaceholder")),
@@ -2857,9 +2929,10 @@ function apply(ctx) {
       return UI[lang]["nav.title"];
     },
     inject: () => ({}),
-  }, EmailSettingsSection));
+  }, __withFirstRun(EmailSettingsSection)));
 }
 
+exports.__firstRunCard = __FirstRunCard;
 exports.apply = apply;
 exports.inject = inject;
 

package/lib/config.js

@@ -365,7 +365,9 @@ export function mergeAccountDefaults(common, account = {}) {
 }
 /** Merge one account over shared defaults and its selected provider, then validate it. */
 function resolveAccount(name, common, acc, allowEnvPassword, providers, known) {
-    const requested = acc.provider ?? common.provider;
+    // Public settings persist the form's empty custom-server selection directly.
+    // Normalize it like the legacy projection and YAML writer before preset lookup.
+    const requested = (acc.provider === '' ? undefined : acc.provider) ?? (common.provider === '' ? undefined : common.provider);
     const preset = requested === undefined ? undefined : providers[requested];
     if (requested !== undefined && preset === undefined) {
         throw new Error(`dsh-email：账号 "${name}" 的 provider "${requested}" 未知，可选：${known.join('/')}；或省略 provider 直接填 imap.host 与 smtp.host`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-email",
-  "version": "0.16.3",
+  "version": "0.17.1",
   "description": "在 DSH 中收发、搜索和整理邮件，支持多个邮箱账号。",
   "type": "module",
   "main": "lib/index.js",