dsh-email 0.16.3 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.17.0（2026-10-17）
+
+- 设置面板顶部新增「首次使用」分步引导：一次只讲一步，支持上一步/下一步/跳过，看完记在本机不再出现。
+- 引导内容与该插件的实际用法一致；可在开发者工具里清掉 `dsh-first-run:dsh-email:v1` 重新查看。
 ## 0.16.3 (2026-10-17)
 
 - 修复未配置邮箱时，服务商示例列表被凭据脱敏器误隐藏的问题；保留真实凭据的原有脱敏规则。

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";
@@ -2857,9 +2922,10 @@ function apply(ctx) {
       return UI[lang]["nav.title"];
     },
     inject: () => ({}),
-  }, EmailSettingsSection));
+  }, __withFirstRun(EmailSettingsSection)));
 }
 
+exports.__firstRunCard = __FirstRunCard;
 exports.apply = apply;
 exports.inject = inject;
 

package/package.json

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