@zaofan/dsh-qqbot 0.6.0

package/dist/features/scheduler.js

@@ -0,0 +1,146 @@
+/**
+ * scheduler.ts — 定时唤醒（M3, 2026-09-03 新增, v3 改造）
+ *
+ * 对应设计文档 M3「定时+互动召回」。
+ *
+ * 机制（v3，主人指正后重构）：
+ *  - 配置按"目标分组"：config.schedule.targets[] = {id,name?,scope(group|c2c),
+ *    targetId, tasks:[{id,time "HH:MM",enabled,prompt?}]} —— 号码只填一次, 下面挂多条时刻。
+ *  - 每 30s 检查；当前本地时刻 HH:MM 命中某 target 下某条 enabled 任务且今天没触发 → 触发。
+ *  - **触发 = 伪造一条"定时任务发来"的入站消息，直接喂 handleInbound**——
+ *    与真实 QQ 消息走完全同一条链路：getOrCreate 用同 peerKey → 命中/resume 该聊天
+ *    的**原 dsh 会话**（有群历史记忆/人格/工具上下文），mention 标记 (@you)；
+ *    AI 的正常回复经既有 outbound 链路以 bot 身份主动推送到目标聊天。
+ *    ✅ 不再另起游离对话、上下文连续、群/私聊都能看到。
+ *  - 平台主动消息限制：群需开通"主动消息"权限(已开通, 有频控)；私聊需近 48h
+ *    互动窗，窗外拒收 → bootstrap sendMarkdown 三级降级(markdown→text→wakeup)。
+ *  - lastRun 落盘 {cwd}/schedule-state.json，触发瞬间乐观记账，每天至多一次；
+ *    错过的时刻不补发(等明天)。lastError 留痕最近失败。
+ *
+ * ⚠️ 本地手改功能（fork 新增）：维护清单见工作区根《插件改动维护注意事项.md》。
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { handleInbound } from '../transport/inbound.js';
+/** 轮询间隔: 30s(分钟级精度足够, 不会跳整分钟) */
+const TICK_MS = 30_000;
+/** 本地 HH:MM */
+function nowHHMM(d = new Date()) {
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+function todayKey(d = new Date()) {
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${d.getFullYear()}-${m}-${day}`;
+}
+/**
+ * 启动定时调度器。返回 stop()：停止轮询并落盘。
+ * config 为 live 对象引用(schedule.targets 现读, Web 设置热更新即时生效)。
+ */
+export function startScheduler(manager, config, logger) {
+    const stateFile = join(config.cwd || process.cwd(), 'schedule-state.json');
+    const state = { lastRun: {} };
+    try {
+        const raw = readFileSync(stateFile, 'utf8');
+        const parsed = JSON.parse(raw);
+        state.lastRun = parsed?.lastRun ?? {};
+        state.lastError = parsed?.lastError;
+    }
+    catch {
+        state.lastRun = {};
+    }
+    const inFlight = new Set();
+    function persist() {
+        try {
+            writeFileSync(stateFile, JSON.stringify(state, null, 1), 'utf8');
+        }
+        catch (err) {
+            logger.warn?.(`[scheduler] state 落盘失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** 触发 = 伪造一条"主人发来"的入站消息, 走与真实 QQ 消息完全相同的链路 */
+    async function fireTask(target, task) {
+        const scope = target.scope === 'c2c' ? 'c2c' : 'group';
+        const key = `${scope}:${target.targetId}`;
+        logger.info(`[scheduler] fire task=${task.id} (${target.name || target.id}) → ${key} @ ${task.time}`);
+        try {
+            // 伪造入站消息(与 SDK 消息同形; 无 messageId → 出站自动走主动推送)
+            // - 本质仍是"伪造一条消息唤醒 AI 回合"(定时任务必须触发回合), 但内容自报家门:
+            //   前缀带 [定时任务 + 系统日期时间], senderName 用中性名, 不打假 (@you) —— AI 干活照干,
+            //   但不会把定时触发记成"主人真人发言/被真人点名"(防污染主人交互记忆)。
+            // - group: peerId 取 groupOpenid(=target.targetId)
+            // - c2c:   peerId 取 senderId —— 必须等于 target.targetId(该用户 openid), 才能命中原会话
+            const now = new Date();
+            const pad = (n) => String(n).padStart(2, '0');
+            const ts = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+            const rawPrompt = task.prompt?.trim() || '在吗~ 出来说说话吧';
+            const trigger = `[定时任务 ${ts}] ${rawPrompt}`;
+            const fakeMsg = {
+                kind: scope,
+                senderId: scope === 'c2c' ? target.targetId : 'master',
+                senderName: '定时任务',
+                content: trigger,
+                messageId: '',
+                timestamp: now.toISOString(),
+                groupOpenid: scope === 'group' ? target.targetId : undefined,
+                msgType: 0,
+                attachments: undefined,
+            };
+            await handleInbound(fakeMsg, manager, config, logger, undefined);
+            logger.info(`[scheduler] injected inbound → handleInbound: task=${task.id} key=${key}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            state.lastError = { taskId: task.id, at: new Date().toISOString(), message: msg };
+            persist();
+            logger.error(`[scheduler] fire failed: task=${task.id} ${msg}`);
+        }
+    }
+    function tick() {
+        let targets = [];
+        try {
+            targets = config.schedule?.targets ?? [];
+        }
+        catch { /* config 未就绪 */ }
+        const tasksNow = [];
+        for (const target of targets) {
+            if (!target?.id || !target.targetId)
+                continue;
+            for (const task of target.tasks ?? []) {
+                if (!task?.id || !task.enabled)
+                    continue;
+                tasksNow.push({ target, task });
+            }
+        }
+        if (tasksNow.length === 0)
+            return;
+        const hhmm = nowHHMM();
+        const today = todayKey();
+        for (const { target, task } of tasksNow) {
+            if ((task.time ?? '') !== hhmm)
+                continue;
+            if (state.lastRun[task.id] === today)
+                continue; // 今天已触发
+            if (inFlight.has(task.id))
+                continue; // 同分钟并发防重
+            inFlight.add(task.id);
+            // 触发瞬间即记账(乐观) —— 宁可漏发也不重复打扰
+            state.lastRun[task.id] = today;
+            persist();
+            void fireTask(target, task).finally(() => inFlight.delete(task.id));
+        }
+    }
+    const timer = setInterval(tick, TICK_MS);
+    timer.unref?.();
+    // 启动后先跑一次: 若此刻正好命中某任务且今天没发过则触发;
+    // 错过的时刻不补发(准点触发, 避免新设任务被立即补发打扰), 等明天同一时刻。
+    tick();
+    const targetCount = (config.schedule?.targets ?? []).length;
+    logger.info(`[scheduler] started (${targetCount} targets, state=${stateFile})`);
+    return () => {
+        clearInterval(timer);
+        persist();
+        logger.info('[scheduler] stopped');
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/features/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/features/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/features/sticker-gate.d.ts

@@ -0,0 +1,90 @@
+import type { StickerGatesConfig } from '../config.js';
+import type { Logger } from '../types.js';
+import type { MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
+import type { MediaKind } from '../transport/rich-media.js';
+/** 闸门拒绝信号: sender.sendMedia 抛此错; send_media 工具 catch 转 ok:false, [MEDIA] 通道记日志 */
+export declare class StickerGateDenied extends Error {
+    constructor(reason: string);
+}
+export declare function isStickerGateDenied(err: unknown): err is StickerGateDenied;
+/** 单条媒体发送的判定上下文 */
+export interface MediaGateCtx {
+    /** group openid; 私聊(null/undefined)不闸 */
+    groupId?: string;
+    kind: MediaKind;
+    /** 本地绝对路径(已 resolve); URL 发送不算 sticker, 不闸 */
+    localPath?: string;
+}
+export interface MediaGateVerdict {
+    allowed: boolean;
+    /** 该发送是否属于"库内表情包图"(即便 allowed, 也用于调用方决定是否记录流水) */
+    isSticker: boolean;
+    /** 拒绝原因(中文, 给工具回执/日志) */
+    reason?: string;
+}
+/** 是否库内表情包路径: roots = [dataDir/lib] + gates.libRoots(追加前缀) */
+export declare function isStickerPath(p: string | undefined, dataDir: string, libRoots?: string[]): boolean;
+export declare function bindStickerGates(getter: () => StickerGatesConfig): void;
+/**
+ * 闸门状态(跨重启持久: used 去重 / budget 日预算)。
+ * 窗口频率 ring / 活性 ring 为内存态(窗口短, 重启重计可接受, 与定稿一致)。
+ */
+declare class StickerGate {
+    readonly dataDir: string;
+    private readonly logger?;
+    /** 每群活性 RingBuffer: groupId -> 群消息时间戳(ms) */
+    private readonly activity;
+    /** 每群我方发送窗口 ring: groupId -> 放行表情包时间戳(ms) */
+    private readonly sentTimes;
+    /** 同图去重: 本地路径 -> 最近发送 ts(惰性按 dupTTL 清理) */
+    private used;
+    /** 日预算: groupId -> {YYYY-MM-DD: 张数} */
+    private budget;
+    private saveTimer;
+    private dirty;
+    constructor(dataDir: string, logger?: Logger | undefined);
+    private usedPath;
+    private budgetPath;
+    private sendlogPath;
+    private load;
+    /** 防抖落盘(发送低频, 1s 合并足够); 进程退出兜底走 flush() */
+    private save;
+    /** 立即落盘(退出兜底) */
+    flush(): void;
+    recordActivity(groupId: string, ts?: number): void;
+    /** 近 windowSec 秒内的群消息条数 */
+    countActivity(groupId: string, windowSec: number): number;
+    private countSentInWindow;
+    /**
+     * 单张媒体发送判定(配置现读)。规则顺序:
+     *   非库内 image(URL/非库路径/非图)→放行; 总开关关→放行; 私聊→放行;
+     *   禁发群 → 活性下限 → 窗口频率 → 日预算 → 同图去重。
+     * 放行后发送成功再调 noteSent 记录(发送失败不占预算)。
+     */
+    checkMedia(ctx: MediaGateCtx): MediaGateVerdict;
+    /** 放行且发送成功后才调: 记发送窗口/日预算/同图去重 + 追加发送流水 */
+    noteSent(groupId: string | undefined, localPath: string | undefined): void;
+    /** 把媒体段原文 source 归一到本地绝对路径; URL 返回 undefined */
+    resolveLocalPath(rawSource: string, cwd: string | undefined): string | undefined;
+    /** 某媒体段是否属于库内表情包图(perTurn 计数用; 不发只判) */
+    isStickerMediaSegment(kind: MediaKind, rawSource: string, cwd: string | undefined): boolean;
+}
+/** 启动早期按 config.cwd 解析的 dataDir 预初始化(防目录分裂, 与 configureStickerStore 同款纪律) */
+export declare function initStickerGate(dataDir: string, logger?: Logger): StickerGate;
+/** primary 是否已初始化(未初始化时不应无参调用以免误建目录) */
+export declare function hasStickerGate(): boolean;
+/** 获取闸门实例。带 dataDir → 按目录取; 无参 → primary(主账号)。 */
+export declare function getStickerGate(dataDir?: string, logger?: Logger): StickerGate;
+/** 出站侧把待落盘状态写盘(进程退出兜底; 全部实例都 flush) */
+export declare function flushStickerGate(): void;
+/**
+ * sendRichOutbound 用: 组一个 perTurn(每轮张数)判定上下文。
+ * 未初始化闸门(如单测/无 bot 场景) → perTurnMax=0 不限制, isSticker 恒 false, 不误建目录。
+ */
+export declare function stickerPerTurnCtx(cwd?: string): {
+    perTurnMax: number;
+    isSticker(kind: MediaKind, rawSource: string): boolean;
+};
+export declare function stickerActivityRecorder(dataDir?: string): (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+export {};
+//# sourceMappingURL=sticker-gate.d.ts.map

package/dist/features/sticker-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sticker-gate.d.ts","sourceRoot":"","sources":["../../src/features/sticker-gate.ts"],"names":[],"mappings":"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"}

package/dist/features/sticker-gate.js

@@ -0,0 +1,391 @@
+/**
+ * sticker-gate.ts — 表情包主动发送闸门执行器（P1，2026-09-03 新增）
+ *
+ * 对应《表情包功能_设计v2_分模块定稿.md》模块C「触发信号与闸门(插件侧,出站收口)」。
+ * 把 Web 设置里 sticker.gates 那排开关变成真正的"刹车线"：
+ *   总开关 enabled / 禁发群 / 活性下限(热闹才发) / 窗口频率 / 每群日预算 /
+ *   24h 同图去重 / 路径白名单(仅表情包库内图算 sticker)。
+ *
+ * 设计要点：
+ *  - 配置现读: 单例绑定 live config getter(bindStickerGates), 每次判定现取,
+ *    Web 设置热更新即时生效, 无需重启(与 behavior 冷却同款纪律)。
+ *  - 判定咽喉: bootstrap 的 sender.sendMedia 一处调 checkMedia —— [MEDIA] 标记
+ *    与 send_media 工具两条通道都汇于此, 天然全覆盖。被拒抛 StickerGateDenied:
+ *    工具通道转 ok:false 给 LLM(不回执), [MEDIA] 通道记日志且不影响正文。
+ *  - perTurnMax(每轮最多张数): "轮"只在整段回复文本(一次 sendRichOutbound)内存在,
+ *    由 sendRichOutbound 循环内计数实现; 工具通道单次调用天然=1张不受限。
+ *  - 活性计数: 中间件 stickerActivityRecorder 挂在 mentionGate 之前, 未@消息也流经,
+ *    每群 RingBuffer<ts> 记群消息; 发送窗口频率用我方放行时间戳 ring(内存)。
+ *
+ * ⚠️ 本地手改功能（fork 新增）：维护清单见工作区根《插件改动维护注意事项.md》。
+ * 运行数据与 sticker-store 共用 dataDir(默认 {agent cwd}/表情包)：
+ *   state/used.json(同图去重,重启不丢) state/budget.json(日预算,重启不丢)
+ *   log/sendlog.jsonl(发送流水,append-only)
+ * 单例必须在启动早期按 config.cwd 解析的 dataDir 预初始化(防 C 盘幽灵库同款坑)。
+ */
+import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+/** 活性 RingBuffer 单群保留上限(超限裁剪, 防群轰炸撑爆内存) */
+const ACTIVITY_RING_MAX = 2000;
+/** 我方发送窗口 ring 单群上限 */
+const SENT_RING_MAX = 500;
+/** 未绑定配置时的回落(全部默认=不限制) */
+const FALLBACK_GATES = {
+    enabled: false,
+    perTurnMax: 0,
+    perWindowSec: 600,
+    maxPerWindow: 0,
+    dailyBudgetPerGroup: 0,
+    dupTTLHours: 0,
+    activityWindowSec: 3600,
+    activityMinMsgs: 0,
+    bannedGroups: [],
+    libRoots: [],
+};
+/** 闸门拒绝信号: sender.sendMedia 抛此错; send_media 工具 catch 转 ok:false, [MEDIA] 通道记日志 */
+export class StickerGateDenied extends Error {
+    constructor(reason) {
+        super(`[sticker-gate] ${reason}`);
+        this.name = 'StickerGateDenied';
+    }
+}
+export function isStickerGateDenied(err) {
+    return err instanceof StickerGateDenied;
+}
+/** 判断路径是否位于 root 目录内(Windows 大小写不敏感) */
+function isChildOf(p, root) {
+    const pp = resolve(p).toLowerCase();
+    const rr = resolve(root).toLowerCase();
+    return pp === rr || pp.startsWith(rr.endsWith(sep) ? rr : rr + sep);
+}
+/** 是否库内表情包路径: roots = [dataDir/lib] + gates.libRoots(追加前缀) */
+export function isStickerPath(p, dataDir, libRoots) {
+    if (!p)
+        return false;
+    const roots = [join(dataDir, 'lib')];
+    for (const r of libRoots ?? []) {
+        if (r.trim())
+            roots.push(r.trim());
+    }
+    return roots.some((r) => isChildOf(p, r));
+}
+/** 今日日期键(本地时区 YYYY-MM-DD) */
+function todayKey(now = Date.now()) {
+    const d = new Date(now);
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${d.getFullYear()}-${m}-${day}`;
+}
+/** 当前 live gates(getter 由 bootstrap 绑定到 config.sticker.gates, 每次现读) */
+let _gatesGetter = null;
+export function bindStickerGates(getter) {
+    _gatesGetter = getter;
+}
+function liveGates() {
+    try {
+        return _gatesGetter?.() ?? FALLBACK_GATES;
+    }
+    catch {
+        return FALLBACK_GATES;
+    }
+}
+/**
+ * 闸门状态(跨重启持久: used 去重 / budget 日预算)。
+ * 窗口频率 ring / 活性 ring 为内存态(窗口短, 重启重计可接受, 与定稿一致)。
+ */
+class StickerGate {
+    dataDir;
+    logger;
+    /** 每群活性 RingBuffer: groupId -> 群消息时间戳(ms) */
+    activity = new Map();
+    /** 每群我方发送窗口 ring: groupId -> 放行表情包时间戳(ms) */
+    sentTimes = new Map();
+    /** 同图去重: 本地路径 -> 最近发送 ts(惰性按 dupTTL 清理) */
+    used = new Map();
+    /** 日预算: groupId -> {YYYY-MM-DD: 张数} */
+    budget = new Map();
+    saveTimer = null;
+    dirty = false;
+    constructor(dataDir, logger) {
+        this.dataDir = dataDir;
+        this.logger = logger;
+        mkdirSync(join(dataDir, 'state'), { recursive: true });
+        mkdirSync(join(dataDir, 'log'), { recursive: true });
+        this.load();
+    }
+    // ── 落盘 ──
+    usedPath() {
+        return join(this.dataDir, 'state', 'used.json');
+    }
+    budgetPath() {
+        return join(this.dataDir, 'state', 'budget.json');
+    }
+    sendlogPath() {
+        return join(this.dataDir, 'log', 'sendlog.jsonl');
+    }
+    load() {
+        try {
+            const raw = readFileSync(this.usedPath(), 'utf8');
+            this.used = new Map(Object.entries(JSON.parse(raw)));
+        }
+        catch {
+            this.used = new Map();
+        }
+        try {
+            const raw = readFileSync(this.budgetPath(), 'utf8');
+            const obj = JSON.parse(raw);
+            this.budget = new Map(Object.entries(obj).map(([g, days]) => [g, new Map(Object.entries(days))]));
+        }
+        catch {
+            this.budget = new Map();
+        }
+    }
+    /** 防抖落盘(发送低频, 1s 合并足够); 进程退出兜底走 flush() */
+    save() {
+        this.dirty = true;
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            this.flush();
+        }, 1000);
+        this.saveTimer.unref?.();
+    }
+    /** 立即落盘(退出兜底) */
+    flush() {
+        if (!this.dirty)
+            return;
+        this.dirty = false;
+        try {
+            writeFileSync(this.usedPath(), JSON.stringify(Object.fromEntries(this.used), null, 1), 'utf8');
+        }
+        catch (err) {
+            this.logger?.warn?.(`[sticker-gate] used.json 写盘失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            const obj = {};
+            for (const [g, days] of this.budget)
+                obj[g] = Object.fromEntries(days);
+            writeFileSync(this.budgetPath(), JSON.stringify(obj, null, 1), 'utf8');
+        }
+        catch (err) {
+            this.logger?.warn?.(`[sticker-gate] budget.json 写盘失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── 活性(入站群消息计数; 中间件在 mentionGate 之前喂) ──
+    recordActivity(groupId, ts = Date.now()) {
+        let arr = this.activity.get(groupId);
+        if (!arr) {
+            arr = [];
+            this.activity.set(groupId, arr);
+        }
+        arr.push(ts);
+        // 裁剪: 只留最近 2h 的, 超上限截尾(防群轰炸撑爆)
+        const cutoff = ts - 2 * 3600 * 1000;
+        let i = 0;
+        while (i < arr.length && (arr[i] ?? 0) < cutoff)
+            i += 1;
+        if (i > 0)
+            arr.splice(0, i);
+        if (arr.length > ACTIVITY_RING_MAX)
+            arr.splice(0, arr.length - ACTIVITY_RING_MAX);
+    }
+    /** 近 windowSec 秒内的群消息条数 */
+    countActivity(groupId, windowSec) {
+        const arr = this.activity.get(groupId);
+        if (!arr?.length)
+            return 0;
+        const cutoff = Date.now() - windowSec * 1000;
+        let n = 0;
+        for (const ts of arr)
+            if (ts >= cutoff)
+                n += 1;
+        return n;
+    }
+    // ── 我方发送窗口频率(内存) ──
+    countSentInWindow(groupId, windowSec) {
+        const arr = this.sentTimes.get(groupId);
+        if (!arr?.length)
+            return 0;
+        const cutoff = Date.now() - windowSec * 1000;
+        return arr.filter((ts) => ts >= cutoff).length;
+    }
+    /**
+     * 单张媒体发送判定(配置现读)。规则顺序:
+     *   非库内 image(URL/非库路径/非图)→放行; 总开关关→放行; 私聊→放行;
+     *   禁发群 → 活性下限 → 窗口频率 → 日预算 → 同图去重。
+     * 放行后发送成功再调 noteSent 记录(发送失败不占预算)。
+     */
+    checkMedia(ctx) {
+        const gates = liveGates();
+        const isSticker = ctx.kind === 'image'
+            && !!ctx.localPath
+            && isStickerPath(ctx.localPath, this.dataDir, gates.libRoots);
+        if (!isSticker)
+            return { allowed: true, isSticker: false };
+        if (gates.enabled !== true)
+            return { allowed: true, isSticker: true };
+        if (!ctx.groupId)
+            return { allowed: true, isSticker: true };
+        if ((gates.bannedGroups ?? []).includes(ctx.groupId)) {
+            return { allowed: false, isSticker: true, reason: '此群已列入表情包禁发名单' };
+        }
+        if ((gates.activityMinMsgs ?? 0) > 0) {
+            const win = (gates.activityWindowSec ?? 3600) > 0 ? gates.activityWindowSec : 3600;
+            const n = this.countActivity(ctx.groupId, win);
+            if (n < gates.activityMinMsgs) {
+                return { allowed: false, isSticker: true, reason: `群活跃度不足(近${Math.round(win / 60)}分钟仅${n}条, 需≥${gates.activityMinMsgs}条才许主动发)` };
+            }
+        }
+        if ((gates.maxPerWindow ?? 0) > 0 && (gates.perWindowSec ?? 0) > 0) {
+            const n = this.countSentInWindow(ctx.groupId, gates.perWindowSec);
+            if (n >= gates.maxPerWindow) {
+                return { allowed: false, isSticker: true, reason: `发送频率超限(每${Math.round(gates.perWindowSec / 60)}分钟≤${gates.maxPerWindow}张, 窗口内已${n}张)` };
+            }
+        }
+        if ((gates.dailyBudgetPerGroup ?? 0) > 0) {
+            const days = this.budget.get(ctx.groupId);
+            const usedToday = days?.get(todayKey()) ?? 0;
+            if (usedToday >= gates.dailyBudgetPerGroup) {
+                return { allowed: false, isSticker: true, reason: `今日此群预算已用完(${usedToday}/${gates.dailyBudgetPerGroup}张)` };
+            }
+        }
+        if ((gates.dupTTLHours ?? 0) > 0) {
+            const last = this.used.get(ctx.localPath);
+            if (last && Date.now() - last < gates.dupTTLHours * 3600 * 1000) {
+                return { allowed: false, isSticker: true, reason: `同图去重(${gates.dupTTLHours}h 内已发过这张)` };
+            }
+        }
+        return { allowed: true, isSticker: true };
+    }
+    /** 放行且发送成功后才调: 记发送窗口/日预算/同图去重 + 追加发送流水 */
+    noteSent(groupId, localPath) {
+        if (!groupId || !localPath)
+            return;
+        const now = Date.now();
+        let arr = this.sentTimes.get(groupId);
+        if (!arr) {
+            arr = [];
+            this.sentTimes.set(groupId, arr);
+        }
+        arr.push(now);
+        if (arr.length > SENT_RING_MAX)
+            arr.splice(0, arr.length - SENT_RING_MAX);
+        let days = this.budget.get(groupId);
+        if (!days) {
+            days = new Map();
+            this.budget.set(groupId, days);
+        }
+        const tk = todayKey(now);
+        days.set(tk, (days.get(tk) ?? 0) + 1);
+        this.used.set(localPath, now);
+        this.save();
+        try {
+            appendFileSync(this.sendlogPath(), JSON.stringify({ ts: now, group: groupId, path: localPath, day: tk }) + '\n', 'utf8');
+        }
+        catch { /* 流水失败不影响 */ }
+    }
+    // ── 每轮计数辅助(供 sendRichOutbound 判断该段是否算"本轮的库内表情包图") ──
+    /** 把媒体段原文 source 归一到本地绝对路径; URL 返回 undefined */
+    resolveLocalPath(rawSource, cwd) {
+        const s = (rawSource ?? '').trim();
+        if (!s || /^https?:\/\//i.test(s))
+            return undefined;
+        if (s.startsWith('file://'))
+            return s.replace(/^file:\/\//, '');
+        if (/^[a-zA-Z]:[\\/]/.test(s) || s.startsWith('/'))
+            return s;
+        return cwd ? join(cwd, s) : s;
+    }
+    /** 某媒体段是否属于库内表情包图(perTurn 计数用; 不发只判) */
+    isStickerMediaSegment(kind, rawSource, cwd) {
+        if (kind !== 'image')
+            return false;
+        const p = this.resolveLocalPath(rawSource, cwd);
+        if (!p)
+            return false;
+        return isStickerPath(p, this.dataDir, liveGates().libRoots);
+    }
+}
+// ── 多例注册表(多账号支持, 2026-09-03): 每账号实例一个 dataDir → 各自闸门状态/预算/日志。
+const _gates = new Map();
+let _primaryGateDir;
+/** 启动早期按 config.cwd 解析的 dataDir 预初始化(防目录分裂, 与 configureStickerStore 同款纪律) */
+export function initStickerGate(dataDir, logger) {
+    const key = resolve(dataDir);
+    let g = _gates.get(key);
+    if (!g) {
+        g = new StickerGate(dataDir, logger);
+        _gates.set(key, g);
+    }
+    if (!_primaryGateDir)
+        _primaryGateDir = key;
+    return g;
+}
+/** primary 是否已初始化(未初始化时不应无参调用以免误建目录) */
+export function hasStickerGate() {
+    return _primaryGateDir !== undefined && _gates.has(_primaryGateDir);
+}
+/** 获取闸门实例。带 dataDir → 按目录取; 无参 → primary(主账号)。 */
+export function getStickerGate(dataDir, logger) {
+    if (dataDir) {
+        const key = resolve(dataDir);
+        let g = _gates.get(key);
+        if (!g) {
+            g = new StickerGate(dataDir, logger);
+            _gates.set(key, g);
+        }
+        if (!_primaryGateDir)
+            _primaryGateDir = key;
+        return g;
+    }
+    if (_primaryGateDir) {
+        const g = _gates.get(_primaryGateDir);
+        if (g)
+            return g;
+    }
+    if (_gates.size === 1)
+        return _gates.values().next().value;
+    const dir = join(process.cwd(), '表情包');
+    const g = new StickerGate(dir, logger);
+    _gates.set(resolve(dir), g);
+    if (!_primaryGateDir)
+        _primaryGateDir = resolve(dir);
+    return g;
+}
+/** 出站侧把待落盘状态写盘(进程退出兜底; 全部实例都 flush) */
+export function flushStickerGate() {
+    for (const g of _gates.values()) {
+        try {
+            g.flush();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * sendRichOutbound 用: 组一个 perTurn(每轮张数)判定上下文。
+ * 未初始化闸门(如单测/无 bot 场景) → perTurnMax=0 不限制, isSticker 恒 false, 不误建目录。
+ */
+export function stickerPerTurnCtx(cwd) {
+    if (!hasStickerGate())
+        return { perTurnMax: 0, isSticker: () => false };
+    const gate = getStickerGate();
+    return {
+        perTurnMax: liveGates().perTurnMax ?? 0,
+        isSticker: (kind, raw) => gate.isStickerMediaSegment(kind, raw, cwd),
+    };
+}
+// ── 中间件: 群消息活性记录(必须在 mentionGate 之前, 未@消息也流经; 由 setup 挂接) ──
+// dataDir: 每账号实例传自己目录; 缺省走 primary(兼容旧调用)
+export function stickerActivityRecorder(dataDir) {
+    return async (ctx, next) => {
+        if (ctx.message.kind === 'group' && ctx.message.groupOpenid) {
+            try {
+                getStickerGate(dataDir).recordActivity(ctx.message.groupOpenid);
+            }
+            catch { /* 记录失败不影响主链 */ }
+        }
+        await next();
+    };
+}
+//# sourceMappingURL=sticker-gate.js.map