@starhikari/koishi-plugin-group-whitelist 1.0.0

package/lib/index.d.ts

@@ -0,0 +1,66 @@
+import { Context, Schema } from 'koishi';
+export declare const name = "group-whitelist";
+/**
+ * 数据库为可选依赖：
+ * - 注册了数据库（如 database-sqlite）时，白名单存放在数据表 groupWhitelist 中，由指令动态维护；
+ * - 未注册数据库时，插件自动降级为读取配置中的白名单数组（fallbackGroups），依然可正常拦截。
+ */
+export declare const inject: {
+    required: any[];
+    optional: string[];
+};
+/** 私聊放行策略 */
+export type PrivateChatMode = 'forbidden' | 'all' | 'whitelist';
+export interface Config {
+    /** 未命中白名单时的可选提示文本，留空表示完全静默 */
+    ignoreMessage: string;
+    /** 启动后等待多少秒再初始化白名单，期间拦截全部群聊请求 */
+    startupDelay: number;
+    /** 是否记录被拦截的群聊消息，用于排查问题 */
+    enableLog: boolean;
+    /** 是否启用内置 authority 权限检查 */
+    authorityCheck: boolean;
+    /** authority 阈值 */
+    authorityLevel: number;
+    /** 是否启用管理员数组 */
+    adminCheck: boolean;
+    /** 管理员用户 ID 列表 */
+    adminList: string[];
+    /** 无数据库模式下的白名单，支持 '平台:群号' 或仅群号（匹配任意平台） */
+    fallbackGroups: string[];
+    /** 私聊策略 */
+    privateChat: PrivateChatMode;
+    /** 私聊白名单用户 ID */
+    privateWhitelist: string[];
+    /** 是否在机器人入群时发送提示 */
+    joinNoticeEnabled: boolean;
+    /** 入群提示文本（静态文本） */
+    joinNoticeText: string;
+    /** 群名自动刷新间隔（天），0 表示不自动刷新 */
+    groupNameRefreshDays: number;
+    /** 群名刷新时每次并发查询的群数量 */
+    groupNameBatch: number;
+}
+export declare const Config: Schema<Config>;
+declare module 'koishi' {
+    interface Tables {
+        groupWhitelist: GroupWhitelistEntry;
+    }
+    interface Events {
+        /** 手动刷新白名单缓存（可选传入平台名，只刷新该平台） */
+        'group-whitelist/refresh'(platform?: string): void;
+    }
+}
+export interface GroupWhitelistEntry {
+    /** 平台名，如 onebot / qq */
+    platform: string;
+    /** 群号（guildId） */
+    groupId: string;
+    /** 群名称，仅用于展示 */
+    name: string;
+    /** 由谁添加 */
+    creator: string;
+    /** 添加时间 */
+    createdAt: Date;
+}
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,773 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Config: () => Config,
+  apply: () => apply,
+  inject: () => inject,
+  name: () => name
+});
+module.exports = __toCommonJS(src_exports);
+var import_koishi = require("koishi");
+var name = "group-whitelist";
+var inject = {
+  required: [],
+  optional: ["database"]
+};
+var Config = import_koishi.Schema.intersect([
+  // ==================== 群聊白名单设置 ====================
+  import_koishi.Schema.object({
+    ignoreMessage: import_koishi.Schema.string().default("").description("未命中白名单时的提示文本，留空表示完全静默（不推荐填写，容易在陌生群刷屏）"),
+    startupDelay: import_koishi.Schema.number().min(0).max(60).default(3).description("启动后等待多少秒再初始化白名单。这段时间内会拦截全部群聊请求，用于等数据库等服务就绪（数据库可能比插件启动晚约 1 秒）"),
+    enableLog: import_koishi.Schema.boolean().default(false).description("是否在控制台记录被拦截的群聊消息（logger 名称为 group-whitelist，级别 debug）")
+  }).description("群聊白名单设置"),
+  // ==================== 管理指令权限设置 ====================
+  import_koishi.Schema.intersect([
+    import_koishi.Schema.object({
+      authorityCheck: import_koishi.Schema.boolean().default(true).description("启用内置 authority 权限检查（Koishi 用户自带的权限等级）"),
+      adminCheck: import_koishi.Schema.boolean().default(true).description("启用管理员数组检查（与内置 permission 无关，独立生效）")
+    }).description("管理指令权限设置"),
+    // 仅在启用内置权限检查时展示阈值
+    import_koishi.Schema.union([
+      import_koishi.Schema.object({
+        authorityCheck: import_koishi.Schema.const(true).required(),
+        authorityLevel: import_koishi.Schema.number().min(0).max(5).default(3).description("使用管理指令所需的最低 authority 等级。Koishi 默认用户等级为 1，所以默认只有手动提权过的人能用")
+      }),
+      import_koishi.Schema.object({})
+    ]),
+    // 仅在启用管理员数组时展示名单
+    import_koishi.Schema.union([
+      import_koishi.Schema.object({
+        adminCheck: import_koishi.Schema.const(true).required(),
+        adminList: import_koishi.Schema.array(import_koishi.Schema.string()).default([]).description("管理员用户 ID 列表，可跨平台，与 authority 满足其一即可使用管理指令")
+      }),
+      import_koishi.Schema.object({})
+    ])
+  ]),
+  // ==================== 无数据库模式白名单 ====================
+  import_koishi.Schema.object({
+    fallbackGroups: import_koishi.Schema.array(import_koishi.Schema.string()).default([]).description("未注册数据库时使用的白名单。格式为「平台:群号」或仅「群号」（仅写群号则对所有平台生效）")
+  }).description("无数据库模式白名单（仅在未注册数据库时生效）"),
+  // ==================== 私聊设置 ====================
+  import_koishi.Schema.intersect([
+    import_koishi.Schema.object({
+      privateChat: import_koishi.Schema.union([
+        import_koishi.Schema.const("all").description("放行所有私聊"),
+        import_koishi.Schema.const("whitelist").description("仅放行私聊白名单中的用户"),
+        import_koishi.Schema.const("forbidden").description("禁止一切私聊（不推荐，管理员将无法在私聊中使用管理指令）")
+      ]).role("radio").default("all").description("私聊消息的处理策略")
+    }).description("私聊设置"),
+    import_koishi.Schema.union([
+      import_koishi.Schema.object({
+        privateChat: import_koishi.Schema.const("whitelist").required(),
+        privateWhitelist: import_koishi.Schema.array(import_koishi.Schema.string()).default([]).description("允许私聊的用户 ID 列表（跨平台匹配）")
+      }),
+      import_koishi.Schema.object({})
+    ])
+  ]),
+  // ==================== 入群提示设置 ====================
+  import_koishi.Schema.intersect([
+    import_koishi.Schema.object({
+      joinNoticeEnabled: import_koishi.Schema.boolean().default(true).description("机器人被拉入新群且该群不在白名单时，在群里发送一次提示")
+    }).description("入群提示设置"),
+    import_koishi.Schema.union([
+      import_koishi.Schema.object({
+        joinNoticeEnabled: import_koishi.Schema.const(true).required(),
+        joinNoticeText: import_koishi.Schema.string().role("textarea").default("本群尚未启用机器人服务，如需启用请联系管理员。").description("入群提示文本（静态文本，不支持占位符）")
+      }),
+      import_koishi.Schema.object({})
+    ])
+  ]),
+  // ==================== 群名刷新设置 ====================
+  import_koishi.Schema.intersect([
+    import_koishi.Schema.object({
+      groupNameRefreshDays: import_koishi.Schema.number().min(0).max(365).default(7).description("每隔多少天自动刷新一次白名单群的群名称，0 表示不自动刷新（群名只用于展示，不影响拦截判定）")
+    }).description("群名刷新设置"),
+    import_koishi.Schema.union([
+      import_koishi.Schema.object({
+        groupNameRefreshDays: import_koishi.Schema.const(0)
+      }),
+      import_koishi.Schema.object({
+        groupNameBatch: import_koishi.Schema.number().min(1).max(20).default(5).description("每次并发查询的群数量。NapCat 的获取群信息接口有频率限制，数值过大可能被风控")
+      })
+    ])
+  ])
+]);
+function formatTime(date) {
+  const time = new Date(date);
+  if (Number.isNaN(time.getTime())) return "未知时间";
+  const pad = /* @__PURE__ */ __name((value) => String(value).padStart(2, "0"), "pad");
+  return `${time.getFullYear()}-${pad(time.getMonth() + 1)}-${pad(time.getDate())} ${pad(time.getHours())}:${pad(time.getMinutes())}`;
+}
+__name(formatTime, "formatTime");
+function parseGroupIds(digits) {
+  const invalid = [];
+  const valid = [];
+  for (const item of digits) {
+    for (const raw of String(item).split(/[,\uFF0C\u3001;；\s]+/)) {
+      const id = raw.trim();
+      if (!id) continue;
+      if (!/^\d{1,20}$/.test(id)) {
+        if (!invalid.includes(id)) invalid.push(id);
+        continue;
+      }
+      if (!valid.includes(id)) valid.push(id);
+    }
+  }
+  return { valid, invalid };
+}
+__name(parseGroupIds, "parseGroupIds");
+function parseFallbackItem(source) {
+  const item = source.trim();
+  if (!item) return null;
+  const colon = item.indexOf(":");
+  if (colon >= 0) {
+    const platform = item.slice(0, colon).trim();
+    const groupId = item.slice(colon + 1).trim();
+    if (platform && /^\d{1,20}$/.test(groupId)) return { platform, groupId };
+    return null;
+  }
+  return /^\d{1,20}$/.test(item) ? { groupId: item } : null;
+}
+__name(parseFallbackItem, "parseFallbackItem");
+function apply(ctx, config) {
+  const logger = ctx.logger("group-whitelist");
+  const TABLE = "groupWhitelist";
+  let db = null;
+  async function isGroupAllowed(platform, groupId) {
+    try {
+      await ensurePlatformLoaded(platform);
+    } catch (error) {
+      logger.warn("查询白名单失败，本条消息按放行处理：%s", error instanceof Error ? error.message : error);
+      return true;
+    }
+    return isGroupAllowedSync(platform, groupId);
+  }
+  __name(isGroupAllowed, "isGroupAllowed");
+  async function getAuthority(session) {
+    if (!db) return 0;
+    try {
+      const user = await session.observeUser(["authority"]);
+      return user?.authority ?? 0;
+    } catch (error) {
+      logger.warn("读取用户权限失败，按默认等级处理：%s", error instanceof Error ? error.message : error);
+      return ctx.root.config?.autoAuthorize ?? 1;
+    }
+  }
+  __name(getAuthority, "getAuthority");
+  async function isAdmin(session) {
+    if (config.authorityCheck) {
+      if (await getAuthority(session) >= config.authorityLevel) return true;
+    }
+    if (config.adminCheck && session.userId) {
+      if (config.adminList.includes(session.userId)) return true;
+    }
+    return false;
+  }
+  __name(isAdmin, "isAdmin");
+  async function ensureAdmin(session) {
+    if (await isAdmin(session)) return true;
+    const hints = [
+      config.authorityCheck ? `authority ≥ ${config.authorityLevel}` : "",
+      config.adminCheck ? "管理员数组" : ""
+    ].filter(Boolean).join(" 或 ");
+    if (!hints) {
+      logger.warn("authority 与管理员数组均已关闭，管理指令当前对所有人开放，建议至少开启其中一项");
+      return true;
+    }
+    if (session.isDirect) {
+      await session.send(`你没有权限管理白名单（需要满足：${hints}）。`);
+    }
+    return false;
+  }
+  __name(ensureAdmin, "ensureAdmin");
+  function resolvePlatform(session, given) {
+    if (given) return given;
+    if (session.platform) return session.platform;
+    const platforms = [...new Set(ctx.bots.map((bot) => bot.platform))];
+    return platforms.length === 1 ? platforms[0] : null;
+  }
+  __name(resolvePlatform, "resolvePlatform");
+  function getEventGuildName(session, groupId) {
+    if (session.guildId !== groupId) return "";
+    return session.event?.guild?.name ?? "";
+  }
+  __name(getEventGuildName, "getEventGuildName");
+  function pickBot(platform, selfId) {
+    const candidates = ctx.bots.filter((bot) => bot.platform === platform);
+    if (selfId) return candidates.find((bot) => bot.selfId === selfId) ?? null;
+    return candidates[0] ?? null;
+  }
+  __name(pickBot, "pickBot");
+  async function fetchGroupName(platform, groupId, selfId) {
+    const bot = pickBot(platform, selfId);
+    if (!bot) return "";
+    try {
+      const guild = await bot.getGuild?.(groupId);
+      return guild?.name ?? "";
+    } catch (error) {
+      logger.debug("获取群 %s/%s 的名称失败：%s", platform, groupId, error instanceof Error ? error.message : error);
+      return "";
+    }
+  }
+  __name(fetchGroupName, "fetchGroupName");
+  async function inBatches(items, size, worker) {
+    const results = [];
+    for (let index = 0; index < items.length; index += size) {
+      const slice = items.slice(index, index + size);
+      results.push(...await Promise.all(slice.map(worker)));
+    }
+    return results;
+  }
+  __name(inBatches, "inBatches");
+  async function refreshGroupNames(targets) {
+    const database = db;
+    if (!database) {
+      return { total: 0, updated: 0, failed: 0, skipped: true };
+    }
+    let rows;
+    if (targets?.length) {
+      rows = [];
+      for (const target of targets) {
+        try {
+          const found = await database.get(TABLE, target, ["name"]);
+          if (found[0]) rows.push({ ...target, name: found[0].name });
+        } catch (error) {
+          logger.warn("读取群 %s/%s 失败：%s", target.platform, target.groupId, error instanceof Error ? error.message : error);
+        }
+      }
+    } else {
+      try {
+        rows = await database.get(TABLE, {}, ["platform", "groupId", "name"]);
+      } catch (error) {
+        logger.warn("读取白名单失败：%s", error instanceof Error ? error.message : error);
+        return { total: 0, updated: 0, failed: 0, skipped: false };
+      }
+    }
+    if (!rows.length) return { total: 0, updated: 0, failed: 0, skipped: false };
+    const size = Math.max(1, Math.min(20, config.groupNameBatch ?? 5));
+    const names = await inBatches(rows, size, (row) => fetchGroupName(row.platform, row.groupId));
+    let updated = 0;
+    let failed = 0;
+    for (let index = 0; index < rows.length; ++index) {
+      const row = rows[index];
+      const name2 = names[index];
+      if (!name2) {
+        failed++;
+        continue;
+      }
+      if (name2 === row.name) continue;
+      try {
+        await database.set(TABLE, { platform: row.platform, groupId: row.groupId }, { name: name2 });
+        updated++;
+      } catch (error) {
+        logger.warn("更新群 %s/%s 的名称失败：%s", row.platform, row.groupId, error instanceof Error ? error.message : error);
+        failed++;
+      }
+    }
+    logger.info("群名刷新完成：共 %d 个群，更新 %d 个，失败/不支持 %d 个", rows.length, updated, failed);
+    return { total: rows.length, updated, failed, skipped: false };
+  }
+  __name(refreshGroupNames, "refreshGroupNames");
+  let refreshTimer = null;
+  function stopNameScheduler() {
+    refreshTimer?.();
+    refreshTimer = null;
+  }
+  __name(stopNameScheduler, "stopNameScheduler");
+  function startNameScheduler() {
+    stopNameScheduler();
+    const days = config.groupNameRefreshDays ?? 0;
+    if (!days || days <= 0) return;
+    const interval = days * 24 * 60 * 60 * 1e3;
+    refreshTimer = ctx.setTimeout(async () => {
+      try {
+        await refreshGroupNames();
+      } catch (error) {
+        logger.warn("自动刷新群名失败：%s", error instanceof Error ? error.message : error);
+      }
+      startNameScheduler();
+    }, interval);
+    logger.info("群名自动刷新已启用：每 %d 天一次", days);
+  }
+  __name(startNameScheduler, "startNameScheduler");
+  async function addGroups(platform, ids, session) {
+    const added = [];
+    const duplicated = [];
+    const failed = [];
+    const database = db;
+    if (!database) {
+      return { added, duplicated, failed: ids, readonly: true };
+    }
+    const existIds = /* @__PURE__ */ new Set();
+    try {
+      const exist = await database.get(TABLE, { platform, groupId: { $in: ids } }, ["groupId"]);
+      for (const row of exist) existIds.add(row.groupId);
+    } catch (error) {
+      logger.warn("读取白名单失败：%s", error instanceof Error ? error.message : error);
+      return { added, duplicated, failed: ids, readonly: false };
+    }
+    for (const id of ids) {
+      if (existIds.has(id)) duplicated.push(id);
+    }
+    const pending = ids.filter((id) => !existIds.has(id));
+    if (pending.length) {
+      const names = await inBatches(pending, Math.max(1, Math.min(20, config.groupNameBatch ?? 5)), async (groupId) => {
+        return getEventGuildName(session, groupId) || await fetchGroupName(platform, groupId, session.selfId);
+      });
+      for (let index = 0; index < pending.length; ++index) {
+        const groupId = pending[index];
+        try {
+          await database.create(TABLE, {
+            platform,
+            groupId,
+            name: names[index] ?? "",
+            creator: session.userId,
+            createdAt: /* @__PURE__ */ new Date()
+          });
+          added.push(groupId);
+          markAllowed(platform, groupId);
+        } catch (error) {
+          logger.warn("写入白名单失败（%s）：%s", groupId, error instanceof Error ? error.message : error);
+          failed.push(groupId);
+        }
+      }
+    }
+    return { added, duplicated, failed, readonly: false };
+  }
+  __name(addGroups, "addGroups");
+  async function removeGroups(platform, ids) {
+    const removed = [];
+    const missing = [];
+    const database = db;
+    if (!database) {
+      return { removed, missing: ids, readonly: true };
+    }
+    const existIds = /* @__PURE__ */ new Set();
+    try {
+      const exist = await database.get(TABLE, { platform, groupId: { $in: ids } }, ["groupId"]);
+      for (const row of exist) existIds.add(row.groupId);
+    } catch (error) {
+      logger.warn("读取白名单失败：%s", error instanceof Error ? error.message : error);
+      return { removed, missing: ids, readonly: false };
+    }
+    for (const id of ids) {
+      if (!existIds.has(id)) missing.push(id);
+    }
+    if (existIds.size) {
+      const targets = [...existIds];
+      try {
+        await database.remove(TABLE, { platform, groupId: { $in: targets } });
+        for (const id of targets) {
+          removed.push(id);
+          allowedGroups.delete(cacheKey(platform, id));
+        }
+      } catch (error) {
+        logger.warn("移除白名单失败：%s", error instanceof Error ? error.message : error);
+        removed.length = 0;
+        missing.push(...targets);
+      }
+    }
+    return { removed, missing, readonly: false };
+  }
+  __name(removeGroups, "removeGroups");
+  const blockedMap = /* @__PURE__ */ new WeakMap();
+  const allowedGroups = /* @__PURE__ */ new Set();
+  const cacheKey = /* @__PURE__ */ __name((platform, groupId) => `${platform}:${groupId}`, "cacheKey");
+  const platformLoaded = /* @__PURE__ */ new Set();
+  const emptyWarned = /* @__PURE__ */ new Set();
+  const configNameCache = /* @__PURE__ */ new Map();
+  let dbEverSeen = false;
+  let configSettled = false;
+  function markAllowed(platform, groupId) {
+    allowedGroups.add(cacheKey(platform, groupId));
+  }
+  __name(markAllowed, "markAllowed");
+  function clearDecisions() {
+    configNameCache.clear();
+    allowedGroups.clear();
+    platformLoaded.clear();
+    emptyWarned.clear();
+  }
+  __name(clearDecisions, "clearDecisions");
+  function resetDecisions() {
+    clearDecisions();
+    if (!initDone) return;
+    logger.debug("数据源已切换，重新载入白名单判定表");
+    initialize().catch((error) => {
+      logger.warn("按新数据源重新载入白名单失败：%s", error instanceof Error ? error.message : error);
+    });
+  }
+  __name(resetDecisions, "resetDecisions");
+  function decisionsSettled() {
+    return !!db || dbEverSeen || configSettled;
+  }
+  __name(decisionsSettled, "decisionsSettled");
+  async function ensurePlatformLoaded(platform) {
+    if (platformLoaded.has(platform)) return;
+    const database = db;
+    if (!database) {
+      if (!decisionsSettled()) return;
+      let count = 0;
+      for (const item of config.fallbackGroups) {
+        const parsed = parseFallbackItem(item);
+        if (!parsed) continue;
+        if (parsed.platform && parsed.platform !== platform) continue;
+        markAllowed(platform, parsed.groupId);
+        count++;
+      }
+      platformLoaded.add(platform);
+      if (!count) markEmpty(platform);
+      return;
+    }
+    const rows = await database.get(TABLE, { platform }, ["groupId"]);
+    for (const row of rows) markAllowed(platform, row.groupId);
+    platformLoaded.add(platform);
+    if (!rows.length) markEmpty(platform);
+    logger.debug("已载入 %s 平台白名单，共 %d 条", platform, rows.length);
+  }
+  __name(ensurePlatformLoaded, "ensurePlatformLoaded");
+  function markEmpty(platform) {
+    if (emptyWarned.has(platform)) return;
+    emptyWarned.add(platform);
+    logger.info("%s 平台白名单为空，该平台所有群聊都会被忽略；可私聊机器人执行「白名单 添加 <群号> -p %s」启用", platform, platform);
+  }
+  __name(markEmpty, "markEmpty");
+  function isGroupAllowedSync(platform, groupId) {
+    if (!platformLoaded.has(platform)) return false;
+    return allowedGroups.has(cacheKey(platform, groupId));
+  }
+  __name(isGroupAllowedSync, "isGroupAllowedSync");
+  function resolveBlockSync(session) {
+    const groupId = session.guildId;
+    if (groupId) {
+      if (isGroupAllowedSync(session.platform, groupId)) return null;
+      if (config.enableLog) {
+        logger.debug("已拦截非白名单群聊消息：%s / %s / %s", session.platform, groupId, session.userId);
+      }
+      return config.ignoreMessage;
+    }
+    if (config.privateChat === "all") return null;
+    if (config.privateChat === "whitelist") {
+      if (session.userId && config.privateWhitelist.includes(session.userId)) return null;
+      if (config.enableLog) {
+        logger.debug("已拦截非白名单私聊消息：%s / %s", session.platform, session.userId);
+      }
+      return "";
+    }
+    return "";
+  }
+  __name(resolveBlockSync, "resolveBlockSync");
+  ctx.on("ready", async () => {
+    for (const platform of new Set(ctx.bots.map((bot) => bot.platform))) {
+      await ensurePlatformLoaded(platform);
+    }
+  });
+  ctx.before("attach", (session) => {
+    if (!session.userId || !session.event) return;
+    if (!session.guildId) return;
+    ensurePlatformLoaded(session.platform).catch((error) => {
+      logger.warn("载入白名单失败：%s", error instanceof Error ? error.message : error);
+    });
+  });
+  ctx.on("message", (session) => {
+    if (!session.userId || !session.event) return;
+    const blocked = resolveBlockSync(session);
+    if (blocked === null) return;
+    blockedMap.set(session, blocked);
+    session.response = async () => blockedMap.get(session) ?? "";
+  }, { prepend: true });
+  const sample = ctx.bots[0]?.session({ type: "message" });
+  const prototype = sample ? Object.getPrototypeOf(sample) : null;
+  if (prototype && typeof prototype.execute === "function") {
+    const original = prototype.execute;
+    prototype.execute = function(...args) {
+      if (blockedMap.has(this)) return Promise.resolve(blockedMap.get(this));
+      return original.apply(this, args);
+    };
+    ctx.on("dispose", () => {
+      prototype.execute = original;
+    });
+  }
+  ctx.on("guild-added", async (session) => {
+    if (!config.joinNoticeEnabled || !config.joinNoticeText) return;
+    const platform = session.platform;
+    const groupId = session.guildId;
+    if (!groupId) return;
+    try {
+      if (await isGroupAllowed(platform, groupId)) return;
+      await session.send(config.joinNoticeText);
+    } catch (error) {
+      logger.warn("发送入群提示失败：%s", error instanceof Error ? error.message : error);
+    }
+  });
+  const base = { showWarning: false, authority: 0 };
+  const platformOption = { type: "string", authority: 0 };
+  const command = ctx.command("whitelist", "群聊白名单管理", base).alias("白名单").usage([
+    "查看与维护群聊白名单。名单按「平台 + 群号」保存，未命中白名单的群消息将被整只机器人忽略。",
+    "",
+    "子指令：",
+    "  白名单.列表      查看白名单（别名 白名单.list / 白名单.ls）",
+    "  白名单.添加      添加群聊（别名 白名单.add）",
+    "  白名单.移除      移除群聊（别名 白名单.remove / 白名单.rm）",
+    "  白名单.刷新      立刻重新拉取群名称（别名 白名单.refresh / 白名单.同步群名）",
+    "",
+    "指令选项：",
+    "  -p, --platform <name>  指定平台（默认取当前会话所在平台）",
+    "",
+    "示例：",
+    "  白名单.列表",
+    "  白名单.添加 123456 654321",
+    "  白名单.添加 -p qq 123456,654321",
+    "  白名单.移除 123456",
+    "  白名单.刷新"
+  ].join("\n"));
+  const list = command.subcommand(".列表", "查看白名单", base).alias(".list", ".ls", ".查看").option("platform", "-p <name> 指定平台", platformOption).example("白名单.列表").example("白名单.列表 -p qq");
+  const add = command.subcommand(".添加 <...digits:string>", "添加群聊到白名单（支持批量）", base).alias(".add").option("platform", "-p <name> 指定平台", platformOption).example("白名单.添加 123456 654321").example("白名单.添加 -p qq 123456,654321");
+  const remove = command.subcommand(".移除 <...digits:string>", "从白名单移除群聊（支持批量）", base).alias(".remove", ".rm", ".delete", ".删除").option("platform", "-p <name> 指定平台", platformOption).example("白名单.移除 123456");
+  const refreshNames = command.subcommand(".刷新", "立刻重新拉取白名单群的名称", base).alias(".refresh", ".sync", ".同步群名").option("platform", "-p <name> 指定平台", platformOption).example("白名单.刷新").example("白名单.刷新 -p qq");
+  const commands = [command, list, add, remove, refreshNames];
+  if (config.authorityCheck) {
+    for (const item of commands) item.userFields(["authority"]);
+  }
+  list.action(async ({ session, options }) => {
+    if (!session) return;
+    if (!await ensureAdmin(session)) return;
+    const platform = resolvePlatform(session, options.platform);
+    if (!platform) return "无法确定要查询的平台，请使用 -p <平台名> 指定。";
+    let rows = [];
+    let fromConfig = false;
+    const database = db;
+    if (database) {
+      try {
+        rows = await database.get(TABLE, { platform }, { sort: { createdAt: "asc" }, limit: 201 });
+      } catch (error) {
+        logger.warn("查询白名单失败：%s", error instanceof Error ? error.message : error);
+        return "查询白名单失败，请查看控制台日志。";
+      }
+    } else {
+      fromConfig = true;
+      for (const item of config.fallbackGroups) {
+        const parsed = parseFallbackItem(item);
+        if (!parsed) continue;
+        if (parsed.platform && parsed.platform !== platform) continue;
+        rows.push({ platform, groupId: parsed.groupId, name: "", creator: "", createdAt: /* @__PURE__ */ new Date(0) });
+      }
+      rows.sort((a, b) => a.groupId.localeCompare(b.groupId));
+    }
+    const lines = [`${platform} 平台白名单（共 ${rows.length} 条${fromConfig ? "，来自配置项" : ""}）`];
+    if (!rows.length) {
+      lines.push("（名单为空，当前该平台下所有群聊消息都会被忽略）");
+    } else {
+      if (fromConfig) {
+        await inBatches(rows, Math.max(1, Math.min(20, config.groupNameBatch ?? 5)), async (row) => {
+          const key = cacheKey(platform, row.groupId);
+          if (!configNameCache.has(key)) {
+            configNameCache.set(key, await fetchGroupName(platform, row.groupId, session.selfId));
+          }
+          row.name = configNameCache.get(key) ?? "";
+        });
+      }
+      const limit = 20;
+      for (const row of rows.slice(0, limit)) {
+        const isSelf = !!session.guildId && row.groupId === session.guildId;
+        const since = row.createdAt && row.createdAt.getTime() > 0 ? `｜${formatTime(row.createdAt)}` : "";
+        lines.push(`${isSelf ? "▶" : "·"} ${row.groupId}${row.name ? `（${row.name}）` : ""}${since}`);
+      }
+      if (rows.length > limit) lines.push(`…… 其余 ${rows.length - limit} 条已省略`);
+    }
+    if (fromConfig) {
+      lines.push("提示：当前未注册数据库，白名单来自配置项 fallbackGroups，指令增删不会生效。");
+    }
+    return lines.join("\n");
+  });
+  add.action(async ({ session, options, args }) => {
+    if (!session) return;
+    if (!await ensureAdmin(session)) return;
+    const platform = resolvePlatform(session, options.platform);
+    if (!platform) return "无法确定要操作的平台，请使用 -p <平台名> 指定。";
+    const { valid, invalid } = parseGroupIds(args);
+    if (!valid.length) {
+      return invalid.length ? `群号格式不正确：${invalid.join("、")}。群号应为纯数字，可一次填写多个（空格或逗号分隔）。` : "请提供至少一个群号，例如：白名单 添加 123456";
+    }
+    const result = await addGroups(platform, valid, session);
+    if (result.readonly) {
+      return "当前未注册数据库，白名单来自配置项 fallbackGroups，无法通过指令添加。请先在配置中维护，或安装 database-sqlite 等数据库插件。";
+    }
+    const lines = [];
+    if (result.added.length) {
+      lines.push(`已向 ${platform} 平台添加 ${result.added.length} 个群：${result.added.join("、")}`);
+    }
+    if (result.duplicated.length) {
+      const preview = result.duplicated.slice(0, 5).join("、");
+      lines.push(`${result.duplicated.length} 个群已在白名单中，已跳过：${preview}${result.duplicated.length > 5 ? " 等" : ""}`);
+    }
+    if (result.failed.length) {
+      const preview = result.failed.slice(0, 5).join("、");
+      lines.push(`${result.failed.length} 个群写入失败：${preview}${result.failed.length > 5 ? " 等" : ""}`);
+    }
+    if (!lines.length) return "没有需要添加的群。";
+    if (invalid.length) lines.push(`另有格式不正确的项已忽略：${invalid.join("、")}`);
+    return lines.join("\n");
+  });
+  remove.action(async ({ session, options, args }) => {
+    if (!session) return;
+    if (!await ensureAdmin(session)) return;
+    const platform = resolvePlatform(session, options.platform);
+    if (!platform) return "无法确定要操作的平台，请使用 -p <平台名> 指定。";
+    const { valid, invalid } = parseGroupIds(args);
+    if (!valid.length) {
+      return invalid.length ? `群号格式不正确：${invalid.join("、")}。群号应为纯数字，可一次填写多个（空格或逗号分隔）。` : "请提供至少一个群号，例如：白名单 移除 123456";
+    }
+    const result = await removeGroups(platform, valid);
+    if (result.readonly) {
+      return "当前未注册数据库，白名单来自配置项 fallbackGroups，无法通过指令移除。请直接在配置中维护。";
+    }
+    const lines = [];
+    if (result.removed.length) {
+      lines.push(`已从 ${platform} 平台移除 ${result.removed.length} 个群：${result.removed.join("、")}`);
+    }
+    if (result.missing.length) {
+      const preview = result.missing.slice(0, 5).join("、");
+      lines.push(`${result.missing.length} 个群不在白名单中，已跳过：${preview}${result.missing.length > 5 ? " 等" : ""}`);
+    }
+    if (!lines.length) return "没有需要移除的群。";
+    if (invalid.length) lines.push(`另有格式不正确的项已忽略：${invalid.join("、")}`);
+    if (result.removed.some((id) => id === session.guildId)) {
+      lines.push("注意：本群已被移出白名单，接下来本群消息将不再被处理。");
+    }
+    return lines.join("\n");
+  });
+  refreshNames.action(async ({ session, options }) => {
+    if (!session) return;
+    if (!await ensureAdmin(session)) return;
+    if (!db) {
+      return "当前未注册数据库，白名单来自配置项 fallbackGroups，没有可刷新的群名记录。";
+    }
+    const platform = options.platform ?? void 0;
+    let targets;
+    if (platform) {
+      try {
+        const rows = await db.get(TABLE, { platform }, ["groupId"]);
+        targets = rows.map((row) => ({ platform, groupId: row.groupId }));
+      } catch (error) {
+        logger.warn("读取白名单失败：%s", error instanceof Error ? error.message : error);
+        return "读取白名单失败，请查看控制台日志。";
+      }
+      if (!targets.length) return `${platform} 平台白名单为空，没有需要刷新的群。`;
+    }
+    await session.send("正在拉取群名称，请稍候…");
+    const result = await refreshGroupNames(targets);
+    const scope = platform ? `${platform} 平台` : "全部平台";
+    const lines = [`群名刷新完成（${scope}）：共 ${result.total} 个群。`];
+    if (result.updated) lines.push(`已更新 ${result.updated} 个群的名称。`);
+    if (result.failed) lines.push(`${result.failed} 个群未能取到名称，已保留原值（多为平台不支持或接口异常）。`);
+    if (!result.updated && !result.failed) lines.push("所有群名都是最新的，无需更新。");
+    return lines.join("\n");
+  });
+  ctx.inject(["database"], (ctx2) => {
+    db = ctx2.database;
+    dbEverSeen = true;
+    ctx2.model.extend("groupWhitelist", {
+      platform: "string",
+      groupId: "string",
+      name: { type: "string", initial: "" },
+      creator: { type: "string", initial: "" },
+      // 注意：minato 的 initial 只接受字面值、不接受工厂函数，时间戳在插入时显式赋值
+      createdAt: "timestamp"
+    }, {
+      primary: ["platform", "groupId"],
+      indexes: ["platform"]
+    });
+    resetDecisions();
+    logger.info("白名单存储：数据库（表 %s）", TABLE);
+    ctx2.on("dispose", () => {
+      db = null;
+      resetDecisions();
+      logger.info("数据库服务已卸载，白名单回落到配置模式（fallbackGroups）");
+    });
+  });
+  async function refresh(platform) {
+    if (platform) {
+      platformLoaded.delete(platform);
+      emptyWarned.delete(platform);
+      for (const key of [...allowedGroups]) {
+        if (key.startsWith(platform + ":")) allowedGroups.delete(key);
+      }
+      return ensurePlatformLoaded(platform);
+    }
+    clearDecisions();
+    for (const item of new Set(ctx.bots.map((bot) => bot.platform))) {
+      await ensurePlatformLoaded(item);
+    }
+  }
+  __name(refresh, "refresh");
+  ctx.on("group-whitelist/refresh", (platform) => {
+    refresh(platform).catch((error) => {
+      logger.warn("刷新白名单判定表失败：%s", error instanceof Error ? error.message : error);
+    });
+  });
+  ctx.on("dispose", () => {
+    clearDecisions();
+    initDone = false;
+    stopNameScheduler();
+  });
+  let initDone = false;
+  async function initialize() {
+    if (initDone) return;
+    configSettled = !db;
+    for (const platform of new Set(ctx.bots.map((bot) => bot.platform))) {
+      try {
+        await ensurePlatformLoaded(platform);
+      } catch (error) {
+        logger.warn("载入 %s 平台白名单失败：%s", platform, error instanceof Error ? error.message : error);
+      }
+    }
+    initDone = true;
+    logger.info(
+      "白名单已就绪：%s，%d 个平台、%d 个群",
+      db ? `数据库（表 ${TABLE}）` : `配置文件（fallbackGroups，${config.fallbackGroups.length} 项）`,
+      platformLoaded.size,
+      allowedGroups.size
+    );
+    startNameScheduler();
+  }
+  __name(initialize, "initialize");
+  ctx.on("ready", () => {
+    const delay = Math.max(0, config.startupDelay ?? 3) * 1e3;
+    if (!delay) {
+      initialize();
+      return;
+    }
+    logger.debug("启动闸门已开启：%d 秒内拦截全部群聊请求，随后初始化白名单", delay / 1e3);
+    ctx.setTimeout(() => {
+      initialize();
+    }, delay);
+  });
+}
+__name(apply, "apply");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Config,
+  apply,
+  inject,
+  name
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@starhikari/koishi-plugin-group-whitelist",
+  "description": "实现koishi全局白名单，群聊不在白名单内时bot将不再处理该群的任何消息与指令",
+  "version": "1.0.0",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Star-Hikari/group-whitelist",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Star-Hikari/group-whitelist.git"
+  },
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "whitelist",
+    "group-whitelist",
+    "群聊白名单",
+    "群白名单"
+  ],
+  "peerDependencies": {
+    "koishi": "^4.18.7"
+  },
+  "koishi": {
+    "description": {
+      "zh": "群聊白名单系统：按「平台 + 群号」维护白名单，未命中的群消息会被整只机器人静默忽略。名单可用指令批量增删，也可在没有数据库时改用配置项维护。",
+      "en": "Group chat whitelist: keep a per-platform group whitelist; messages from groups not on it are silently ignored by the whole bot. Manage it with commands, or fall back to a config list when no database is available."
+    },
+    "service": {
+      "required": [],
+      "optional": [
+        "database"
+      ]
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,190 @@
+# @starhikari/koishi-plugin-group-whitelist
+
+[![npm](https://img.shields.io/npm/v/@starhikari/koishi-plugin-group-whitelist?style=flat-square)](https://www.npmjs.com/package/@starhikari/koishi-plugin-group-whitelist)
+
+群聊白名单系统：按「平台 + 群号」维护白名单，**未命中白名单的群消息会被整只机器人静默忽略** —— 所有指令、其他插件的监听器、模糊匹配都不会触发，等同于机器人不在这个群里。
+
+## 特性
+
+- **全局总闸**：拦截发生在消息进入 Koishi 消息流水线的第一刻，不是逐个插件过滤
+- **按平台隔离**：名单主键为「平台 + 群号」，onebot（NapCat）与 qq（官方 bot）各自独立
+- **指令维护**：`白名单 添加/移除/列表`，增删均支持批量群号，数据库自动建表
+- **自动降级**：未注册数据库时改用配置项 `fallbackGroups`，无需手动切换
+- **私聊可控**：私聊默认放行（方便管理员在私聊里救急），可切换为禁止或私聊白名单
+- **入群提示**：机器人被拉入未白名单的群时发送一次可自定义的提示文本
+- **同步判定**：运行期不逐条消息查库，启动时整表载入内存判定表
+
+## 安装
+
+```text
+# 在插件市场搜索「group-whitelist」并安装，或在终端执行
+npm install @starhikari/koishi-plugin-group-whitelist
+```
+
+然后在 `koishi.yml` 中启用（行首的 `~` 表示禁用，去掉即可）：
+
+```yaml
+plugins:
+  '@starhikari/group-whitelist': {}
+```
+
+插件依赖 `database` 服务（可选）。项目里默认已有 `database-sqlite`，无需额外安装。
+
+## 快速上手
+
+首次启动时白名单为空，**该平台下所有群聊都会被忽略**（这正是白名单的语义）。启用某个群有两种方式：
+
+1. **私聊机器人**（推荐，私聊默认放行）：
+
+   ```text
+   白名单.添加 123456          # 自动使用当前会话平台
+   白名单.添加 123456 -p qq    # 跨平台管理时显式指定平台
+   ```
+
+2. **改配置文件**：在 `fallbackGroups` 里写上群号后重载插件（仅在未注册数据库时生效）。
+
+## 配置项
+
+配置在 Koishi 控制台中分组展示，不满足条件的项会自动折叠。
+
+### 群聊白名单设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `ignoreMessage` | `string` | `''` | 未命中白名单时的提示文本，留空表示完全静默 |
+| `startupDelay` | `number` | `3` | 启动后等待多少秒再初始化白名单，期间拦截全部群聊请求 |
+| `enableLog` | `boolean` | `false` | 是否在控制台以 `debug` 级别记录被拦截的群聊消息 |
+
+> **为什么要等 3 秒**：数据库服务（如 `database-sqlite`）比插件启动晚约 1 秒才就绪，
+> 插件若在那一刻就去读库，会读不到任何数据而误判「白名单为空」，甚至把整只机器人锁死。
+> 因此启动闸门期内**一律拦截群聊请求**（fail-closed），等数据源就位后再初始化判定表。
+> 私聊不受闸门影响，这段时间仍可私聊机器人执行管理指令。设为 `0` 可关闭等待。
+
+### 管理指令权限设置
+
+`authority`（内置权限等级）与管理员数组**两个开关独立生效，满足其一即可**使用管理指令。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `authorityCheck` | `boolean` | `true` | 启用内置 authority 检查 |
+| `authorityLevel` | `number` | `3` | 最低 authority 等级。Koishi 默认用户等级为 1，因此默认只有手动提权过的人能用 |
+| `adminCheck` | `boolean` | `true` | 启用管理员数组检查 |
+| `adminList` | `string[]` | `[]` | 管理员用户 ID 列表（跨平台匹配） |
+
+### 无数据库模式白名单
+
+仅在未注册 `database` 服务时生效，支持两种写法：
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `fallbackGroups` | `string[]` | `[]` | `'onebot:123456'` 限定平台；`'123456'` 对所有平台生效 |
+
+> 该模式下指令增删不会生效，管理指令会明确提示原因。
+
+### 私聊设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `privateChat` | `'all' \| 'whitelist' \| 'forbidden'` | `'all'` | 私聊策略 |
+| `privateWhitelist` | `string[]` | `[]` | 仅 `privateChat = 'whitelist'` 时展示 |
+
+> 不推荐使用 `forbidden`：那样管理员就没法在私聊里添加群了。
+
+### 入群提示设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `joinNoticeEnabled` | `boolean` | `true` | 被拉入未白名单的群时发送一次提示 |
+| `joinNoticeText` | `string` | `本群尚未启用机器人服务，如需启用请联系管理员。` | 提示文本（静态文本，不支持占位符） |
+
+### 群名刷新设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `groupNameRefreshDays` | `number` | `7` | 每隔多少天自动刷新一次群名称，`0` 表示不自动刷新 |
+| `groupNameBatch` | `number` | `5` | 每次并发查询的群数量；NapCat 的群信息接口有频率限制，数值过大会被风控 |
+
+> 群名只用于 `白名单.列表` 展示，**不参与拦截判定**，因此刷新失败不会影响白名单功能。
+
+## 指令
+
+主指令 `白名单`（英文 `whitelist`）。`authority` 与管理员数组任一满足即可使用。
+
+> **子指令必须用点号调用**：Koishi 的指令解析按 `.` 逐段匹配（`Commander._resolve` 里 `key.split('.')`），
+> 所以写法是 `白名单.添加 123456`，而不是 `白名单 添加 123456`。
+> 中文名本身就是子指令名，因此下列三种写法等价：`白名单.添加` / `whitelist.添加` / `whitelist.add`。
+
+| 子指令 | 别名 | 说明 |
+|--------|------|------|
+| `白名单.列表` | `白名单.list` / `白名单.ls` / `白名单.查看` | 列出当前平台白名单，`▶` 标记当前群 |
+| `白名单.添加 <群号...>` | `白名单.add` | 批量添加，空格或逗号分隔 |
+| `白名单.移除 <群号...>` | `白名单.remove` / `白名单.rm` / `白名单.delete` / `白名单.删除` | 批量移除 |
+| `白名单.刷新` | `白名单.refresh` / `白名单.sync` / `白名单.同步群名` | 立刻重新拉取群名称 |
+
+公共选项：
+
+- `-p, --platform <name>`：指定平台，默认取当前会话所在平台（私聊里会尝试按唯一 bot 自动推断）
+
+使用示例：
+
+```text
+白名单.列表
+白名单.列表 -p qq
+白名单.添加 123456 654321
+白名单.添加 123456,654321
+白名单.移除 123456
+白名单.刷新
+白名单.刷新 -p qq
+```
+
+批量操作会逐项回报结果：已添加 / 已存在跳过 / 写入失败 / 格式不正确的项分别统计。
+
+## 群名称
+
+OneBot 的群消息事件里**没有群名**（事件只带 `group_id`），群名必须额外调 `get_group_info`
+才能拿到 —— 适配器把它接到了 `bot.getGuild()`／`bot.getChannel()` 上，这也是 `白名单.列表`
+里群名显示的实现来源。官方 qq 适配器对此接口支持受限，取不到时会留空。
+
+群名获取的三个时机：
+
+1. **添加群时**：`白名单.添加` 会顺带抓一次群名写入数据库，列表直接读表，零额外开销；
+2. **定时刷新**：按 `groupNameRefreshDays` 周期遍历所有平台的已入库群名并更新；
+3. **手动刷新**：`白名单.刷新` 立刻执行一次，可用 `-p` 只刷新某个平台。
+
+取不到名称时**保留原有值**，不会把已有数据清空；名称相同也不会产生多余的写库操作。
+未注册数据库（配置模式）时没有可持久化的位置，群名改为列表展示时按需查询并缓存在内存中。
+
+## 权限模型
+
+管理指令的裁决**完全由插件自己完成**（`ensureAdmin`），Koishi 内置的 `authority` 权限被刻意设为 0
+（永不拦截）—— 因为内置的 `authority:N` 会先挡掉「等级不足但在管理员数组里」的用户，
+双通道设计就失效了。因此：
+
+- 开启 `authorityCheck` 时，`authority ≥ authorityLevel` 即通过；
+- 开启 `adminCheck` 时，用户 ID 在 `adminList` 中即通过；
+- 两者满足其一即放行；两者都关闭时管理指令对所有人开放（会在控制台警告）。
+
+## 外部同步
+
+判定结果常驻内存，指向由本插件维护的四个时机更新：启动载入、指令增删、事件刷新、数据库接入。
+
+如果通过控制台、数据库工具或其他插件**绕过本插件直接改库**，触发下面的事件即可让判定表立刻同步：
+
+```ts
+ctx.emit('group-whitelist/refresh')        // 刷新所有平台
+ctx.emit('group-whitelist/refresh', 'qq')  // 只刷新某个平台
+```
+
+## 行为细节
+
+- **拦截范围**：仅消息事件。入群等通知类事件不受白名单影响（否则就没法发入群提示了）。
+- **静默语义**：未命中的群不仅不回复指令，连其他插件的 `ctx.on('message')` 监听器也不会触发。
+- **判定时机**：拦截在 `Processor.attach` 收尾处完成，早于任何中间件与指令解析。
+- **异常兜底**：判定过程或数据库查询出错时按**放行**处理，避免白名单故障导致整只机器人失声。
+- **兜底防线**：`Session.prototype.execute` 会被包一层，拦截会话即便被其他插件主动调用也不会执行指令；插件卸载时自动还原。
+
+## 已知限制
+
+- 名单按平台隔离，跨平台批量管理必须用 `-p` 显式指定平台。
+- 启动瞬间（数据库模式下的极短冷启动窗口）若白名单尚未载入，该条消息会被拦截而不是放行 —— 这是刻意选择的「宁可静默也不放行」。
+- 白名单为空时该平台所有群聊都会被忽略。首次启用请用私聊管理指令添加群，或改配置后重载。