qq-bot-roost 1.0.0 → 1.0.1

package/README.md

@@ -8,9 +8,9 @@
 
 <img src="https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white" alt="Node.js 22.13+">
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
-<img src="https://img.shields.io/badge/tests-737%20passed-brightgreen" alt="测试 737 项">
+<img src="https://img.shields.io/badge/tests-771%20passed-brightgreen" alt="测试 771 项">
 <img src="https://img.shields.io/badge/plugins-JS%20%7C%20Python%20%7C%20Go%20%7C%20any-blue" alt="多语言插件">
-<img src="https://img.shields.io/badge/version-1.0.0-blueviolet" alt="版本 1.0.0">
+<img src="https://img.shields.io/badge/version-1.0.1-blueviolet" alt="版本 1.0.1">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 <a href="https://github.com/tdcq9594/qq-bot-roost/actions"><img src="https://img.shields.io/github/actions/workflow/status/tdcq9594/qq-bot-roost/ci.yml?branch=master" alt="CI"></a>
 
@@ -76,6 +76,7 @@
 - **QQ号 / 群号 ↔ openid 绑定**：换机器人（换 AppID）之后 openid 会变，而记忆是按 openid 存的。绑定之后，读记忆会把同一个号码名下的所有键一起读——**存量数据一个字节不动**
 - **面板「身份」页**：绑定、追加、改绑、停用；未识别的人也能看到
 - **群内指令（0 / 1 级）**：`/绑定群号 <群号>`、`/绑定成员 @某人 <QQ号>`。只绑当前群和当前群里被 @ 的人，冲突不强制改绑
+- **普通成员自助绑定**：`/绑定QQ <QQ号>` → 验证码发到 `<QQ号>@qq.com` → `/QQ验证码 <6位数字>` 完成绑定，**不需要管理员**；QQ 号已有绑定记录时直接拒绝。四条绑定指令在 `/help` 的「绑定」分组里，与「管理」同级（管理员看到四条，普通成员只看到自助两条）
 - **消息带四个字段**：`uin` / `groupUin` / `userAliases` / `groupAliases`。插件用 `ctx.identity` 只读视图查，绑定表由框架维护
 - 配套升级：`dsh-roost` 1.0.0（别名合并读取 + 账号迁移页）、`ai-chat` 4.4.1（透传字段）。**三个一起升**，少一个号码就传不到 DSH
 
@@ -150,6 +151,7 @@
 - 实时日志流（SSE），按级别和来源着色
 - 一个面板管多个机器人，顶栏随时切换
 - 插件卡片直接显示它自己上报的运行数据（已回复条数、在线人数…）
+- **「通知」页**（在「身份」与「关于」之间）：配任意邮箱服务商的 SMTP、一键发测试邮件到主人邮箱，普通成员自助绑定的说明也在这里
 - 日间 / 夜间主题，启动自动开浏览器，端口被占用自动顺延
 
 ---
@@ -277,6 +279,7 @@ docker compose up -d
 | 群组 | 全局主人增删、群档案（邀请人 / 群主 / 状态）、手动登记群 |
 | 权限 | 等级与作用域说明、按作用域增删管理员、已授权列表 |
 | 日志 | SSE 实时流，按级别和来源过滤，支持关键词搜索 |
+| 通知 | SMTP 服务器 / 端口 / 用户名 / 授权码 / 发件人 / 主人邮箱、测试邮件通知、普通成员自助绑定说明（位于顶栏「身份」与「关于」之间） |
 
 事件页把官方 47 个事件全列出来，灰掉的是当前 intents 没订阅的：
 
@@ -312,6 +315,8 @@ node src/main.js --mock --serve
 | `/whoami` | 查自己的 openid / 群 openid |
 | `/绑定群号 <群号>` | 把**当前群**绑到群号（仅 0 / 1 级；冲突不强制改绑） |
 | `/绑定成员 @某人 <QQ号>` | 把**当前群里被 @ 的人**绑到 QQ号（仅 0 / 1 级） |
+| `/绑定QQ <QQ号>` | **普通成员自助绑定**：验证码发到 `<QQ号>@qq.com`；需先在面板「通知」页配好 SMTP |
+| `/QQ验证码 <6位数字>` | 核对上一条的验证码，完成绑定（5 分钟有效，最多试 5 次） |
 | `/claim <认领码>` | 认领主人身份（`owners` 为空时可用） |
 | `/ping` | 连通性测试 |
 
@@ -381,6 +386,7 @@ export default {
 | `ctx.identity` | **只读**身份视图：`openidOf(uin)` / `uinOf(openid)` / `aliasesOf(uin)` / `groupOf(openid)`。绑定表由框架维护，插件不能写 |
 | `ctx.registerTool(工具)` | 注册一个 AI 可调用的工具（跨插件，0.8.6+），返回注销函数 |
 | `ctx.tools()` / `ctx.callTool(名, 参数)` | 列出 / 调用别插件注册的工具 |
+| `ctx.mail.send(收件人, 内容)` / `ctx.mail.configured` | **邮件通知**：收件人填完整邮箱（任意服务商）或 QQ 号；SMTP 在面板「通知」页配，见[插件开发规范](docs/插件开发规范.md) |
 | `msg.reply` / `push` / `replyMarkdown` / `replyImage` / … | 各种发送方式 |
 
 ---
@@ -424,6 +430,7 @@ bot/
 │   ├── webhook.js              Webhook 接收服务（多机器人共用一个端口）
 │   ├── sign.js                 Webhook 回调签名（Ed25519）
 │   ├── qq/                     扫码一键建机器人（qrlogin.js / qrsvg.js）
+│   ├── mail/                   零依赖 SMTP 客户端、邮件服务、验证码、自助绑定命令
 │   ├── tarball.js              tar.gz 下载解包（不依赖 git）
 │   ├── updater.js              框架自身检查更新与升级
 │   ├── semver.js               版本比较与范围匹配（框架更新/市场/兼容校验共用）
@@ -438,7 +445,7 @@ bot/
 │   ├── web/server.js           面板服务端（REST + SSE）
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
-│   ├── selftest.mjs            框架自检（538 项）
+│   ├── selftest.mjs            框架自检（622 项）
 │   ├── e2e.mjs                 端到端测试（243 项，起真实服务打接口）
 │   ├── qrlogin.mjs             扫码建机器人（8 项）
 │   └── deps.mjs                插件依赖安装（11 项）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,9 +29,9 @@
     "start": "node src/main.js",
     "mock": "node src/main.js --mock",
     "check": "node src/main.js --check",
-    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node --test test/identity.mjs && node --test test/identity-commands.mjs",
+    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node --test test/identity.mjs && node --test test/identity-commands.mjs && node --test test/mail.mjs",
     "test:e2e": "node test/e2e.mjs",
-    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node --test test/identity.mjs && node --test test/identity-commands.mjs && node test/e2e.mjs && node test/live-driver.mjs",
+    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node --test test/identity.mjs && node --test test/identity-commands.mjs && node --test test/mail.mjs && node test/e2e.mjs && node test/live-driver.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "create": "node scripts/create-plugin.mjs",
     "test:plugin": "node scripts/test-plugin.mjs",

package/src/config.js

@@ -4,6 +4,7 @@ import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { ROOT, DIRS, PATHS, botPaths, ensureDirs, listBotIds, rel } from './paths.js';
 import { createLogger } from './logger.js';
+import { SMTP_DEFAULTS } from './mail/defaults.js';
 
 const log = createLogger('config');
 
@@ -171,6 +172,15 @@ const GLOBAL_DEFAULTS = {
      */
     ignoreFrameworkVersion: false,
   },
+
+  /**
+   * 邮箱通知 / SMTP（全局一份，所有机器人共用这个发信通道）。
+   * 字段对齐 BetterGI「设置 → 通知」的邮件部分；面板上就是「通知」页。
+   * 走 saveGlobalConfig（排除式写入），新字段会自动落盘，不用改白名单。
+   */
+  notifications: {
+    smtp: { ...SMTP_DEFAULTS },
+  },
 };
 
 /** 机器人配置：管连接与行为，每个机器人一份 */

package/src/identity.js

@@ -486,7 +486,7 @@ export class IdentityStore {
    * 副作用要知道：给已停用的号码**补绑一条新 openid**（换 AppID 的常规操作）
    * 会顺带把这个号码重新启用，记忆又开始被读到。面板上会提示。
    */
-  async bind({ kind = 'user', uin, openid, botId = '', force = false } = {}) {
+  async bind({ kind = 'user', uin, openid, botId = '', force = false, verifiedBy = 'panel' } = {}) {
     const id = String(uin ?? '').trim();
     if (!isValidUin(id)) throw invalidError(`号码不合法：${uin}（要 5–12 位数字）`, { kind, uin: id });
     if (!isOpenid(openid)) throw invalidError('openid 不合法（空、过长或含空白）', { kind, uin: id });
@@ -558,7 +558,8 @@ export class IdentityStore {
     rec.status = 'active';
     rec.statusUpdatedAt = now;
     rec.updatedAt = now;
-    rec.verifiedBy = 'panel';
+    /** panel = 主人在面板/管理员指认；email = 成员自己用 QQ 邮箱验证码验证 */
+    rec.verifiedBy = String(verifiedBy || 'panel');
     rec.verifiedAt = now;
     if (!rec.createdAt) rec.createdAt = now;
 

package/src/mail/bind-commands.js

@@ -0,0 +1,117 @@
+/**
+ * 普通成员自助绑定 QQ 号的两条命令（纯逻辑，「消息 → 结果文本」）。
+ *
+ * 和 `identity-commands.js` 一样的规矩：永远返回 { ok, text }，不抛异常。
+ * 命令本身注册在 `main.js` 的 `core()` 里 —— 插件拿不到身份表的写权限
+ * （`ctx.identity` 是只读视图），只有内核的 `sharedIdentity()` 能 bind。
+ *
+ * ## 命令名坑
+ * `message.js:417` 会把命令名 `.toLowerCase()`，所以注册时必须用
+ * `绑定qq` / `qq验证码`（写成大写 Q 永远匹配不上）。
+ */
+
+import { isValidUin } from '../identity.js';
+import { verifyMail } from './verify.js';
+
+/** 只认 QQ 号；顺手剥掉用户可能多打的 @qq.com 后缀 */
+export function parseUinArg(args = []) {
+  for (const v of Array.isArray(args) ? args : []) {
+    const s = String(v ?? '').trim().replace(/@qq\.com$/i, '');
+    if (isValidUin(s)) return s;
+  }
+  return '';
+}
+
+export function parseCodeArg(args = []) {
+  for (const v of Array.isArray(args) ? args : []) {
+    const s = String(v ?? '').trim();
+    if (/^\d{6}$/.test(s)) return s;
+  }
+  return '';
+}
+
+const NO_MAIL = '机器人还没配好邮箱，暂时没法自助绑定。请找主人用「绑定成员 @你 QQ号」代绑。';
+
+/**
+ * 冲突检查：按需求「直接拒绝」，不做 force、不做改绑、不覆盖任何已有记录。
+ * 发验证码前和核对通过后各查一次（中间这 5 分钟里可能被人抢先绑了）。
+ */
+function conflictOf(identity, botId, openid, uin) {
+  // 这个人在这只鸟下已经绑过号了
+  const mine = identity.resolveUser?.(botId, openid);
+  if (mine?.uin && String(mine.uin) !== uin) {
+    return `你已经绑过 QQ 号 ${mine.uin} 了，自助绑定不能改绑。要换号请找主人在面板处理。`;
+  }
+  // 这个号已经属于别人
+  const owner = String(identity.openidOf?.(botId, uin) ?? '').trim();
+  if (owner && owner !== openid) {
+    return `QQ 号 ${uin} 已经绑给别人了，直接拒绝。确认是这个号请找主人在面板处理。`;
+  }
+  // 有记录但本 bot 下查不到 openid（停用 / 被解绑 / 挂在别的机器人下）：一样拒绝
+  if (!owner && identity.has?.('user', uin)) {
+    return `QQ 号 ${uin} 已有绑定记录，自助绑定不覆盖已有记录。请找主人确认。`;
+  }
+  return '';
+}
+
+/**
+ * `绑定QQ <QQ号>` → 发验证码到 `<QQ号>@qq.com`。
+ */
+export async function runBindQq({ msg, mail, verify, identity, botId = '', log = () => {} } = {}) {
+  const openid = String(msg?.userId ?? '').trim();
+  if (!openid) return { ok: false, text: '拿不到你的身份标识，稍后再发一条消息试试。' };
+
+  const uin = parseUinArg(msg?.args);
+  if (!uin) {
+    return { ok: false, text: '用法：绑定QQ 你的QQ号（5–12 位数字）。验证码会发到「QQ号@qq.com」。' };
+  }
+  if (!mail || !mail.checkConfig().ok) return { ok: false, text: NO_MAIL };
+
+  try {
+    await identity.load?.();
+    const conflict = conflictOf(identity, botId, openid, uin);
+    if (conflict) return { ok: false, text: conflict };
+
+    const issued = verify.issue({ openid, uin });
+    try {
+      await mail.send({ to: issued.to, ...verifyMail({ uin, code: issued.code }) });
+    } catch (e) {
+      // 发失败就撤销记录，别让用户白等 60 秒冷却
+      verify.cancel?.(openid);
+      return { ok: false, text: `验证码没发出去：${e.message}。稍后重试，或找主人代绑。` };
+    }
+    log(`自助绑定：${openid} 申请绑定 QQ ${uin}，验证码已发往 ${issued.to}`);
+    return {
+      ok: true,
+      text: `验证码已发到 ${issued.to}，5 分钟内有效。请回复「QQ验证码 6位数字」完成绑定。`,
+    };
+  } catch (e) {
+    return { ok: false, text: e?.message || '申请失败，请稍后再试。' };
+  }
+}
+
+/**
+ * `QQ验证码 <6位数字>` → 核对后写入 identity.json。
+ * 验证码记录绑定的是发起者 openid，拿别人邮件里的码也绑不上。
+ */
+export async function runVerifyQq({ msg, verify, identity, botId = '', log = () => {} } = {}) {
+  const openid = String(msg?.userId ?? '').trim();
+  if (!openid) return { ok: false, text: '拿不到你的身份标识，稍后再发一条消息试试。' };
+
+  const code = parseCodeArg(msg?.args);
+  if (!code) return { ok: false, text: '用法：QQ验证码 123456（6 位数字）' };
+
+  try {
+    const r = verify.consume({ openid, code });
+    await identity.load?.();
+    const conflict = conflictOf(identity, botId, openid, r.uin);
+    if (conflict) return { ok: false, text: conflict };
+
+    await identity.bind({ kind: 'user', uin: r.uin, openid, botId, verifiedBy: 'email' });
+    log(`自助绑定成功：${openid} ↔ QQ ${r.uin}（邮箱验证码）`);
+    return { ok: true, text: `绑定成功：QQ 号 ${r.uin} 已绑到你的账号。` };
+  } catch (e) {
+    if (e?.code === 'CONFLICT') return { ok: false, text: `这个 QQ 号有冲突：${e.message}。请找主人在面板处理。` };
+    return { ok: false, text: e?.message || '绑定失败，请稍后再试。' };
+  }
+}

package/src/mail/defaults.js

@@ -0,0 +1,25 @@
+/**
+ * SMTP 默认值放在一个无依赖的纯数据模块里：
+ * `config.js`（全局默认配置）和 `mail/service.js`（运行时现读）共用同一份，
+ * 免得两边各写一份、以后加字段时悄悄漂移。
+ */
+
+export const SMTP_DEFAULTS = Object.freeze({
+  enabled: false,
+  host: '',
+  port: 587,
+  /** auto = 按端口规则 + 服务商特例自动判定；也可手填 tls / starttls / none */
+  security: 'auto',
+  user: '',
+  pass: '',
+  from: '',
+  fromName: '',
+  /** 原「收件人邮箱」：只作测试邮件收件人。用户 QQ 邮箱由 QQ 号现拼，不在这里配 */
+  ownerEmail: '',
+
+  /* 高级项，面板不展示，可手改 config/bot.json */
+  timeoutMs: 15_000,
+  rejectUnauthorized: true,
+  maxPerMinute: 5,
+  dailyLimit: 50,
+});

package/src/mail/service.js

@@ -0,0 +1,275 @@
+/**
+ * MailService —— 邮件能力的唯一入口。
+ *
+ * 职责：读全局配置（热生效）、收件地址白名单、发信限频、串行发送、测试发送。
+ * 不做的事（按需求明确砍掉）：故障告警、失败重试队列、告警去重、
+ * 给主人发邮件/QQ 私聊、审计落盘。发信失败只写一行普通日志 + 把错误交给调用方展示。
+ *
+ * 三个调用方都走这里：面板「通知」页、内核自助绑定命令、`POST /api/mail/send`。
+ */
+
+import { sendSmtpMail, resolveSecurity, formatSmtpError, extractAddress, parseRecipients } from './smtp.js';
+import { isValidUin } from '../identity.js';
+import { SMTP_DEFAULTS } from './defaults.js';
+
+export { SMTP_DEFAULTS };
+
+/**
+ * 字段与 BetterGI `NotificationConfig` 的邮件部分一一对齐
+ * （SmtpServer / SmtpPort / SmtpUsername / SmtpPassword / FromEmail / FromName / ToEmail），
+ * 只是把 ToEmail 改叫 ownerEmail：它现在只作「测试邮件收件人」。
+ */
+
+export class MailError extends Error {
+  constructor(message, { code = 'EMAIL_FAILED' } = {}) {
+    super(message);
+    this.name = 'MailError';
+    this.code = code;
+  }
+}
+
+const dayKey = (d = new Date()) =>
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+
+export class MailService {
+  /**
+   * @param {{globalCfg?:object, log?:object, identity?:object}} deps
+   *   globalCfg 传引用，configWatch 热重载后这里立刻能读到新配置，不用重启。
+   *   identity 是 IdentityStore（可空），用于 openid → QQ 号。
+   */
+  constructor({ globalCfg = {}, log = null, identity = null } = {}) {
+    this.globalCfg = globalCfg;
+    this.log = log;
+    this.identity = identity;
+    /** 一次只跑一封：SMTP 连接串行，也顺带把「验证码风暴」挡在队列里 */
+    this.chain = Promise.resolve();
+    this.minuteStamps = [];
+    this.dayCount = { key: dayKey(), n: 0 };
+    this.lastResult = null;
+  }
+
+  /** 每次现读，绝不在构造时把配置快照下来 */
+  cfg() {
+    const raw = this.globalCfg?.notifications?.smtp ?? {};
+    return { ...SMTP_DEFAULTS, ...raw };
+  }
+
+  /** 面板 GET 用：密码不回显，只回一个「已设置」标志 */
+  publicConfig() {
+    const c = this.cfg();
+    return {
+      ...c,
+      pass: '',
+      passSet: Boolean(c.pass),
+      resolvedSecurity: resolveSecurity(c.host, c.port, c.security),
+      lastResult: this.lastResult,
+    };
+  }
+
+  /** 配置是否够发信。SMTP 用户名/密码允许为空（免认证内网中继） */
+  checkConfig() {
+    const c = this.cfg();
+    const missing = [];
+    if (!c.enabled) missing.push('「启用邮箱通知」开关');
+    if (!String(c.host).trim()) missing.push('SMTP 服务器');
+    const port = Number(c.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) missing.push('SMTP 端口');
+    if (!extractAddress(c.from)) missing.push('发件人邮箱');
+    return { ok: missing.length === 0, missing };
+  }
+
+  /**
+   * 把调用方给的目标解析成收件地址。
+   *
+   * 三种写法，优先级从高到低：
+   *   1. `openid`  → 查绑定表反查 QQ 号 → `<QQ号>@qq.com`
+   *   2. `target` / `uin` / `to` 是**完整邮箱地址** → 原样使用（任意服务商：163 / Outlook /
+   *      Gmail / 企业邮箱 / 自建都行），不再限制成 QQ 邮箱或主人邮箱
+   *   3. 纯数字的 QQ 号 → 自动补 `@qq.com`（保留自助绑定的简写）
+   *
+   * 仍然守着的边界：地址格式必须合法、发信走全局限频与串行队列、SMTP 凭据不下发给插件。
+   */
+  resolveRecipient({ target = '', uin = '', openid = '', to = '' } = {}) {
+    if (openid) {
+      const n = String(this.identity?.uinOf?.(openid) ?? '').trim();
+      if (!n) throw new MailError('这个用户还没绑定 QQ 号，暂时发不了邮件通知', { code: 'UNBOUND' });
+      return `${n}@qq.com`;
+    }
+    const raw = String(target || uin || to || '').trim();
+    if (!raw) throw new MailError('收件人不能为空（填完整邮箱地址，或 QQ 号）', { code: 'BAD_TO' });
+    const addr = extractAddress(raw);
+    if (addr) return addr;
+    if (isValidUin(raw)) return `${raw}@qq.com`;
+    throw new MailError('收件人要填完整邮箱地址，或 5–12 位的 QQ 号', { code: 'BAD_TO' });
+  }
+
+  #takeQuota() {
+    const c = this.cfg();
+    const now = Date.now();
+    this.minuteStamps = this.minuteStamps.filter((t) => now - t < 60_000);
+    const perMin = Math.max(1, Number(c.maxPerMinute) || SMTP_DEFAULTS.maxPerMinute);
+    const perDay = Math.max(1, Number(c.dailyLimit) || SMTP_DEFAULTS.dailyLimit);
+    if (this.minuteStamps.length >= perMin) {
+      throw new MailError(`发信太频繁（每分钟最多 ${perMin} 封），稍后再试`, { code: 'RATE_LIMIT' });
+    }
+    const key = dayKey();
+    if (this.dayCount.key !== key) this.dayCount = { key, n: 0 };
+    if (this.dayCount.n >= perDay) {
+      throw new MailError(`今天已发满 ${perDay} 封，明天再试（防邮箱被判垃圾邮件）`, { code: 'DAILY_LIMIT' });
+    }
+    this.minuteStamps.push(now);
+    this.dayCount.n += 1;
+  }
+
+  /** 前一次失败不能堵住队列；任务本身的结果照常返回给调用方 */
+  #enqueue(fn) {
+    const task = this.chain.then(fn, fn);
+    this.chain = task.catch(() => {});
+    return task;
+  }
+
+  /**
+   * 底层发送。`target` 由 resolveRecipient 得到，或内部直接给完整地址。
+   * @returns {Promise<{ok:true,to:string,messageId:string,security:string,auth:string}>}
+   */
+  async send({ to, subject, text, html = false } = {}) {
+    const check = this.checkConfig();
+    if (!check.ok) throw new MailError(`邮箱还没配好，缺：${check.missing.join('、')}`, { code: 'NOT_CONFIGURED' });
+    const list = parseRecipients(to);
+    if (!list.length) throw new MailError('收件人邮箱不合法', { code: 'BAD_TO' });
+    this.#takeQuota();
+
+    const c = this.cfg();
+    return this.#enqueue(async () => {
+      try {
+        const out = await sendSmtpMail({
+          host: c.host,
+          port: c.port,
+          security: c.security,
+          user: c.user,
+          pass: c.pass,
+          from: c.from,
+          fromName: c.fromName,
+          to: list,
+          subject: String(subject ?? '').replace(/[\r\n]+/g, ' ').slice(0, 200),
+          text: String(text ?? ''),
+          html,
+          timeoutMs: c.timeoutMs,
+          rejectUnauthorized: c.rejectUnauthorized,
+        });
+        this.lastResult = { ok: true, at: Date.now(), to: list.join(','), security: out.security };
+        this.log?.info?.(`邮件已发送 → ${list.join(',')}（${c.host}:${c.port} / ${out.security}）`);
+        return { ok: true, to: list.join(','), ...out };
+      } catch (err) {
+        const f = formatSmtpError(err, c.host, c.port);
+        this.lastResult = { ok: false, at: Date.now(), to: list.join(','), code: f.code };
+        // 普通日志，不是「故障通知」：不额外发邮件、不推 QQ、不落盘队列
+        this.log?.error?.(`邮件发送失败 → ${c.host}:${c.port} [${f.code}] ${f.message}`);
+        throw new MailError(f.message, { code: f.code });
+      }
+    });
+  }
+
+  /**
+   * 发通知的主入口：`target` 可以是完整邮箱地址（任意服务商），也可以是 QQ 号简写。
+   * 框架接口 `ctx.mail.send()` 和 HTTP `/api/mail/send` 最终都走这里。
+   */
+  sendTo(target, subject, text, opts = {}) {
+    return this.send({ to: this.resolveRecipient({ target }), subject, text, ...opts });
+  }
+
+  /** QQ 号简写的便捷别名，等价 `sendTo(QQ号, ...)` */
+  sendToUin(uin, subject, text, opts = {}) {
+    return this.sendTo(uin, subject, text, opts);
+  }
+
+  /** 给已绑定的 openid 反查 QQ 号再发 */
+  sendToOpenid(openid, subject, text, opts = {}) {
+    return this.send({ to: this.resolveRecipient({ openid }), subject, text, ...opts });
+  }
+
+  /** 面板「测试邮件通知」按钮：发到主人邮箱 */
+  async test() {
+    const c = this.cfg();
+    const owner = extractAddress(c.ownerEmail);
+    if (!owner) throw new MailError('先填「主人邮箱」，测试邮件会发到这个地址', { code: 'NO_OWNER' });
+    const when = new Date().toLocaleString('zh-CN', { hour12: false });
+    const security = resolveSecurity(c.host, c.port, c.security);
+    return this.send({
+      to: owner,
+      subject: '【栖】邮箱通知测试',
+      text: [
+        '这是一封来自 QQ 机器人框架的测试邮件。',
+        '',
+        `发送时间：${when}`,
+        `SMTP 服务器：${c.host}:${c.port}`,
+        `加密方式：${security}（auto 会自动判定）`,
+        '',
+        '能收到这封邮件，说明 SMTP 配置正确。',
+      ].join('\r\n'),
+    });
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* 框架接口：插件用的 ctx.mail                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * 进程级单例（照 `sharedIdentity()` 的写法）。
+ *
+ * 邮件通道是全进程唯一的一份：`config/bot.json` 里只有一组 SMTP 配置，
+ * 所有机器人、所有插件共用。用单例就不必把 MailService 沿着
+ * main → BotRuntime → PluginLoader → createContext 一路透传。
+ */
+let shared = null;
+export function setSharedMail(svc) {
+  shared = svc;
+  return shared;
+}
+export function sharedMail() {
+  return shared;
+}
+
+/**
+ * 生成挂到 `ctx.mail` 上的框架接口。插件只要给 **收件人 + 内容**：
+ *
+ *   await ctx.mail.send('123456', '你的任务完成了');            // QQ 号 → 123456@qq.com
+ *   await ctx.mail.send('someone@163.com', '日报已生成');        // 任意邮箱直接发
+ *   await ctx.mail.send('someone@outlook.com', '<b>完成</b>', { subject: '提醒', html: true });
+ *
+ * 完整邮箱地址（任意服务商）原样使用，纯数字 QQ 号自动补 `@qq.com`。
+ * 地址格式校验、限频、串行发送、SMTP 凭据保护全在 MailService 里。
+ *
+ * @param {(()=>MailService)|MailService} getService 延迟取服务，配置热更新后仍是同一个对象
+ */
+export function createMailApi(getService = sharedMail) {
+  const service = () => {
+    const svc = typeof getService === 'function' ? getService() : getService;
+    if (!svc) throw new MailError('邮件服务还没初始化（框架版本太旧或尚未启动完成）', { code: 'NO_MAIL' });
+    return svc;
+  };
+  return Object.freeze({
+    /** SMTP 是否配好了。没配好时 send() 会抛中文错误，插件可先判一下 */
+    get configured() {
+      try { return service().checkConfig().ok; } catch { return false; }
+    },
+    /**
+     * @param {string|number} target 完整邮箱地址，或 QQ 号（自动补 @qq.com）
+     * @param {string} content 邮件正文
+     * @param {{subject?:string, html?:boolean}} [opts] 主题默认「【栖】消息通知」
+     * @returns {Promise<{ok:true,to:string,messageId:string}>}
+     */
+    async send(target, content, opts = {}) {
+      const text = String(content ?? '').trim();
+      if (!text) throw new MailError('邮件内容不能为空', { code: 'EMPTY_CONTENT' });
+      const o = opts && typeof opts === 'object' ? opts : {};
+      return service().sendTo(
+        String(target ?? '').trim(),
+        String(o.subject ?? '').trim() || '【栖】消息通知',
+        text,
+        { html: o.html === true },
+      );
+    },
+  });
+}