@yunzai-ng/core 0.1.0

package/dist/message/target.js

@@ -0,0 +1,34 @@
+/**
+ * 算出发送目标的会话键
+ *
+ * 私聊**刻意忽略** `gid`：群临时会话与直接私聊是同一个人的同一个聊天窗口，
+ * 分成两个键会让"从群里发起的对话"与"私聊里的对话"各排一条队。
+ * @param target 发送目标
+ * @returns 会话键
+ */
+export function targetKey(target) {
+    switch (target.scene) {
+        case "group":
+            return `g:${target.gid}`;
+        case "guild":
+            return `c:${target.guildId}/${target.channelId}`;
+        case "private":
+            return `p:${target.uid}`;
+    }
+}
+/**
+ * 将发送目标渲染为一段可读描述
+ * @param target 发送目标
+ * @returns 描述文本，如 `群 123456`
+ */
+export function describeTarget(target) {
+    switch (target.scene) {
+        case "group":
+            return `群 ${target.gid}`;
+        case "guild":
+            return `频道 ${target.guildId}/${target.channelId}`;
+        case "private":
+            return target.gid === undefined ? `私聊 ${target.uid}` : `临时会话 ${target.uid}（来自群 ${target.gid}）`;
+    }
+}
+//# sourceMappingURL=target.js.map

package/dist/message/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../src/message/target.ts"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,MAAkB;IAC1C,QAAQ,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,OAAO;YACV,OAAO,KAAK,MAAM,CAAC,GAAG,EAAE,CAAA;QAC1B,KAAK,OAAO;YACV,OAAO,KAAK,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,CAAA;QAClD,KAAK,SAAS;YACZ,OAAO,KAAK,MAAM,CAAC,GAAG,EAAE,CAAA;IAC5B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,QAAQ,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,OAAO;YACV,OAAO,KAAK,MAAM,CAAC,GAAG,EAAE,CAAA;QAC1B,KAAK,OAAO;YACV,OAAO,MAAM,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,CAAA;QACnD,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,MAAM,CAAC,GAAG,QAAQ,MAAM,CAAC,GAAG,GAAG,CAAA;IAClG,CAAC;AACH,CAAC"}

package/dist/pipeline/cooldown.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 模块职责：命令冷却（CD）的判定与计费
+ * 依赖方向：依赖类型包与 util/lru、util/duration
+ * 生命周期：随内核创建；纯内存，不落盘
+ * 注意事项：**刻意不落盘、不进 Redis**。把 CD 写成 Redis key 会带来两个问题：
+ *          没装 Redis 就起不来，且每条命令都要一次网络往返。
+ *
+ *          CD 的本质是"几秒到几分钟内别重复触发"，重启后清零完全无害
+ *          （甚至是用户期望的）。因此用有界的 LRU + TTL 存在内存里：
+ *          热路径上零 I/O，且条目数有硬上限，不会像裸 Map 那样无限增长。
+ *
+ *          主人不受 CD 限制：调试时被自己设的 5 分钟 CD 锁在门外是最没必要的
+ *          挫败感。这条是内核的既定行为，不是插件可配项。
+ */
+import type { CooldownScope, MessageEvent } from "@yunzai-ng/types";
+/** 冷却判定结果 */
+export type CooldownDecision = {
+    /** 可以执行 */
+    readonly ok: true;
+} | {
+    /** 处于冷却中 */
+    readonly ok: false;
+    /** 剩余毫秒 */
+    readonly remaining: number;
+};
+/** 冷却存储构造参数 */
+export interface CooldownStoreOptions {
+    /** 条目上限，缺省 20000 */
+    readonly max?: number;
+}
+/**
+ * 按作用域构造冷却键
+ *
+ * `group` 作用域在私聊中退化为 `user`：否则私聊消息不具备 gid，全部私聊用户
+ * 将共享同一把锁，成为事实上的全局冷却 —— 该缺陷静默存在，且仅在生产环境暴露。
+ * @param plugin 插件名
+ * @param command 命令名
+ * @param scope 作用域
+ * @param e 消息事件
+ * @returns 冷却键
+ */
+export declare function cooldownKey(plugin: string, command: string, scope: CooldownScope, e: MessageEvent): string;
+/**
+ * 命令冷却存储
+ *
+ * 判定与计费是**同一个动作**（`hit`）：分成 `check` + `mark` 两步的话，
+ * 两次调用之间同一用户的第二条消息就能挤进来，CD 形同虚设。
+ */
+export declare class CooldownStore {
+    #private;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts?: CooldownStoreOptions);
+    /** 当前跟踪的冷却条目数 */
+    get size(): number;
+    /**
+     * 判定冷却，未冷却则立即占用
+     * @param key 冷却键
+     * @param ms 冷却毫秒；`<= 0` 视为不设冷却
+     * @returns 判定结果
+     */
+    hit(key: string, ms: number): CooldownDecision;
+    /**
+     * 提前解除某条冷却
+     *
+     * 给"命令执行失败了，不该占用用户的 CD"这种场景用 —— 让用户为一次
+     * 接口超时等 5 分钟是不合理的。
+     * @param key 冷却键
+     */
+    reset(key: string): void;
+    /** 清空全部冷却 */
+    clear(): void;
+}
+/**
+ * 生成冷却提示语
+ *
+ * 支持 `{time}` 占位符，插件写 `cooldownTip: "冷静一下，还有 {time}"` 即可。
+ * @param template 插件配置的提示语模板
+ * @param remaining 剩余毫秒
+ * @returns 提示文本
+ */
+export declare function renderCooldownTip(template: string, remaining: number): string;
+//# sourceMappingURL=cooldown.d.ts.map

package/dist/pipeline/cooldown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown.d.ts","sourceRoot":"","sources":["../../src/pipeline/cooldown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAOnE,aAAa;AACb,MAAM,MAAM,gBAAgB,GACxB;IACE,WAAW;IACX,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAClB,GACD;IACE,YAAY;IACZ,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,WAAW;IACX,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAA;AAEL,eAAe;AACf,MAAM,WAAW,oBAAoB;IACnC,oBAAoB;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAa1G;AAED;;;;;GAKG;AACH,qBAAa,aAAa;;IAIxB;;OAEG;gBACS,IAAI,GAAE,oBAAyB;IAM3C,iBAAiB;IACjB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,gBAAgB;IAW9C;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB,aAAa;IACb,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7E"}

package/dist/pipeline/cooldown.js

@@ -0,0 +1,94 @@
+import { LruCache } from "../util/lru.js";
+import { formatDuration } from "../util/duration.js";
+/** 默认最多同时跟踪多少条冷却记录 */
+const DEFAULT_MAX = 20_000;
+/**
+ * 按作用域构造冷却键
+ *
+ * `group` 作用域在私聊中退化为 `user`：否则私聊消息不具备 gid，全部私聊用户
+ * 将共享同一把锁，成为事实上的全局冷却 —— 该缺陷静默存在，且仅在生产环境暴露。
+ * @param plugin 插件名
+ * @param command 命令名
+ * @param scope 作用域
+ * @param e 消息事件
+ * @returns 冷却键
+ */
+export function cooldownKey(plugin, command, scope, e) {
+    const head = `${plugin}/${command}`;
+    const gid = e.group?.gid;
+    switch (scope) {
+        case "global":
+            return `${head}|*`;
+        case "group":
+            return gid === undefined ? `${head}|u:${e.sender.uid}` : `${head}|g:${gid}`;
+        case "groupUser":
+            return gid === undefined ? `${head}|u:${e.sender.uid}` : `${head}|g:${gid}:u:${e.sender.uid}`;
+        case "user":
+            return `${head}|u:${e.sender.uid}`;
+    }
+}
+/**
+ * 命令冷却存储
+ *
+ * 判定与计费是**同一个动作**（`hit`）：分成 `check` + `mark` 两步的话，
+ * 两次调用之间同一用户的第二条消息就能挤进来，CD 形同虚设。
+ */
+export class CooldownStore {
+    /** 键 → 冷却结束时间点（毫秒） */
+    #cache;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts = {}) {
+        // ttl 设 0（不过期）：每个条目在写入时带上自己的 ms，
+        // 各命令的 CD 长度不同，用统一 TTL 会算错剩余时间
+        this.#cache = new LruCache({ max: opts.max ?? DEFAULT_MAX, ttl: 0 });
+    }
+    /** 当前跟踪的冷却条目数 */
+    get size() {
+        return this.#cache.size;
+    }
+    /**
+     * 判定冷却，未冷却则立即占用
+     * @param key 冷却键
+     * @param ms 冷却毫秒；`<= 0` 视为不设冷却
+     * @returns 判定结果
+     */
+    hit(key, ms) {
+        if (ms <= 0)
+            return { ok: true };
+        const now = Date.now();
+        const until = this.#cache.get(key);
+        if (until !== undefined && until > now)
+            return { ok: false, remaining: until - now };
+        this.#cache.set(key, now + ms, ms);
+        return { ok: true };
+    }
+    /**
+     * 提前解除某条冷却
+     *
+     * 给"命令执行失败了，不该占用用户的 CD"这种场景用 —— 让用户为一次
+     * 接口超时等 5 分钟是不合理的。
+     * @param key 冷却键
+     */
+    reset(key) {
+        this.#cache.delete(key);
+    }
+    /** 清空全部冷却 */
+    clear() {
+        this.#cache.clear();
+    }
+}
+/**
+ * 生成冷却提示语
+ *
+ * 支持 `{time}` 占位符，插件写 `cooldownTip: "冷静一下，还有 {time}"` 即可。
+ * @param template 插件配置的提示语模板
+ * @param remaining 剩余毫秒
+ * @returns 提示文本
+ */
+export function renderCooldownTip(template, remaining) {
+    const time = formatDuration(remaining);
+    return template.includes("{time}") ? template.replaceAll("{time}", time) : template;
+}
+//# sourceMappingURL=cooldown.js.map

package/dist/pipeline/cooldown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown.js","sourceRoot":"","sources":["../../src/pipeline/cooldown.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,sBAAsB;AACtB,MAAM,WAAW,GAAG,MAAM,CAAA;AAqB1B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,OAAe,EAAE,KAAoB,EAAE,CAAe;IAChG,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,OAAO,EAAE,CAAA;IACnC,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,CAAA;IACxB,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,GAAG,IAAI,IAAI,CAAA;QACpB,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,GAAG,EAAE,CAAA;QAC7E,KAAK,WAAW;YACd,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,CAAA;QAC/F,KAAK,MAAM;YACT,OAAO,GAAG,IAAI,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,CAAA;IACtC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACxB,sBAAsB;IACb,MAAM,CAAkB;IAEjC;;OAEG;IACH,YAAY,OAA6B,EAAE;QACzC,iCAAiC;QACjC,+BAA+B;QAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,CAAS,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,WAAW,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAC9E,CAAC;IAED,iBAAiB;IACjB,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;IACzB,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAW,EAAE,EAAU;QACzB,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;QAEhC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,GAAG;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,GAAG,EAAE,CAAA;QAEpF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,EAAE,CAAC,CAAA;QAClC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;IACrB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAW;QACf,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACzB,CAAC;IAED,aAAa;IACb,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,SAAiB;IACnE,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,CAAA;IACtC,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;AACrF,CAAC"}

package/dist/pipeline/dispatch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 模块职责：事件分发编排 —— 把一条 `IncomingEvent` 走完"策略 → 中间件 → 等待 → 路由 → 冷却 → 处理"
+ * 依赖方向：依赖管线内各子模块与事件总线；不依赖适配器实现，也不被适配器 import
+ * 生命周期：随内核创建；无跨事件状态（冷却与等待都在各自的模块里）
+ * 注意事项：这是**唯一**决定"一条消息会发生什么"的地方，顺序即语义：
+ *
+ *          1. 维护模式 / 忽略自身 —— 在构造事件对象**之前**判掉，省掉全部派生计算
+ *          2. 中间件 —— 可改写 `message`、可注入字段、可 `stop()`
+ *          3. `e.prompt()` 等待者 —— 放在中间件之后（让改写生效）、路由之前
+ *             （用户正在回答问题时不该同时触发命令，否则会收到两条回复）
+ *          4. 命令路由 —— 只做纯查询与零成本静态过滤
+ *          5. 冷却 —— 命中之后才计费，且主人豁免
+ *          6. 处理函数 —— 返回 `false` 继续找下一条，`block !== false` 则命中即止
+ *
+ *          `submit()` **永不抛出**。适配器在 socket 回调里调它，一个未捕获的
+ *          rejection 会变成 `unhandledRejection` 进而带崩整个进程。
+ */
+import type { BotApi, IncomingEvent, Logger } from "@yunzai-ng/types";
+import type { CoreEventBus } from "../plugin/events.js";
+import type { CooldownStore } from "./cooldown.js";
+import type { EventFactory, PluginRuntimeView } from "./event.js";
+import type { MiddlewarePipeline } from "./middleware.js";
+import type { PromptRegistry } from "./prompt.js";
+import type { CommandRouter } from "./router.js";
+/**
+ * 分发器需要的策略视图
+ *
+ * 仅取两项：**维护模式的判定仅在此一处**，管线下游不再重复判定，
+ * 否则"消息在哪一层被丢弃"将成为无法回答的问题。
+ */
+export interface DispatchPolicyView {
+    /** 是否忽略机器人自己发出的消息 */
+    readonly ignoreSelf: boolean;
+    /**
+     * 该用户当前是否应被响应
+     * @param uid 用户 id
+     * @returns 是否响应
+     */
+    canRespond(uid: string): boolean;
+}
+/** 分发器构造参数 */
+export interface EventDispatcherOptions {
+    /** 日志器 */
+    readonly logger: Logger;
+    /** 策略视图 */
+    readonly policy: DispatchPolicyView;
+    /** 内核事件总线 */
+    readonly events: CoreEventBus;
+    /** 事件工厂 */
+    readonly factory: EventFactory;
+    /** 中间件管线 */
+    readonly middlewares: MiddlewarePipeline;
+    /** 命令路由 */
+    readonly router: CommandRouter;
+    /** 冷却存储 */
+    readonly cooldown: CooldownStore;
+    /** `prompt` 等待者登记表 */
+    readonly prompts: PromptRegistry;
+    /**
+     * 按插件名取运行时视图
+     *
+     * 由插件宿主注入。`e.render()` 要靠它定位"当前插件"的模板根，
+     * `e.prompt()` 要靠它拿卸载信号。分发器自己不认识 PluginHost，
+     * 否则 host → context → hooks → dispatch → host 就绕成环了。
+     * @param name 插件名
+     * @returns 插件运行时视图；插件已卸载时 undefined
+     */
+    readonly plugins: (name: string) => PluginRuntimeView | undefined;
+    /**
+     * 命令处理的并发上限，对应配置项 `message.concurrency`
+     *
+     * 省略或 `<= 0` 表示不限制，此时连信号量都不创建（零开销）。
+     * 闸门的位置有讲究，见 `#route` 的注释。
+     */
+    readonly concurrency?: number;
+}
+/** 事件分发器 */
+export declare class EventDispatcher {
+    #private;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts: EventDispatcherOptions);
+    /** 累计处理的事件数 */
+    get handled(): number;
+    /** 当前因并发上限而排队等待的命令数；未配置上限时恒为 0 */
+    get queued(): number;
+    /**
+     * 投递一条事件并处理完毕
+     *
+     * 适配器唯一的入口。**永不抛出**：任何错误都在这里落日志并转成
+     * `pipeline/error` 事件，适配器不需要 try/catch。
+     * @param incoming 适配器产出的事件
+     * @param bot 接收该事件的 Bot
+     */
+    submit(incoming: IncomingEvent, bot: BotApi): Promise<void>;
+}
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/pipeline/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/pipeline/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAEV,MAAM,EAEN,aAAa,EAGb,MAAM,EAIP,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAKvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAuB,MAAM,YAAY,CAAA;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,qBAAqB;IACrB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACjC;AAED,cAAc;AACd,MAAM,WAAW,sBAAsB;IACrC,UAAU;IACV,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,WAAW;IACX,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,aAAa;IACb,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,YAAY;IACZ,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAA;IACxC,WAAW;IACX,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,WAAW;IACX,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAA;IACjE;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAWD,YAAY;AACZ,qBAAa,eAAe;;IA6B1B;;OAEG;gBACS,IAAI,EAAE,sBAAsB;IAkBxC,eAAe;IACf,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,kCAAkC;IAClC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;OAOG;IACG,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqPlE"}

package/dist/pipeline/dispatch.js

@@ -0,0 +1,323 @@
+import { describeMessage } from "../message/segment.js";
+import { parseDuration } from "../util/duration.js";
+import { Semaphore } from "../util/queue.js";
+import { cooldownKey, renderCooldownTip } from "./cooldown.js";
+/**
+ * 取错误的可读描述
+ * @param err 任意抛出物
+ * @returns 描述文本
+ */
+function errText(err) {
+    return err instanceof Error ? (err.stack ?? err.message) : String(err);
+}
+/** 事件分发器 */
+export class EventDispatcher {
+    /** 日志器 */
+    #logger;
+    /** 策略视图 */
+    #policy;
+    /** 事件总线 */
+    #events;
+    /** 事件工厂 */
+    #factory;
+    /** 中间件管线 */
+    #middlewares;
+    /** 命令路由 */
+    #router;
+    /** 冷却存储 */
+    #cooldown;
+    /** 等待者登记表 */
+    #prompts;
+    /** 插件运行时视图查询 */
+    #plugins;
+    /** 命令执行闸门；未配置并发上限时 undefined */
+    #gate;
+    /** 闸门积压到多少条开始告警 */
+    #backlogWarnAt;
+    /** 累计处理的事件数，用于 WebUI 的运行状态 */
+    #handled = 0;
+    /** 已就积压告警过的次数，用于降频 */
+    #backlogWarns = 0;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts) {
+        this.#logger = opts.logger;
+        this.#policy = opts.policy;
+        this.#events = opts.events;
+        this.#factory = opts.factory;
+        this.#middlewares = opts.middlewares;
+        this.#router = opts.router;
+        this.#cooldown = opts.cooldown;
+        this.#prompts = opts.prompts;
+        this.#plugins = opts.plugins;
+        const limit = opts.concurrency ?? 0;
+        this.#gate = limit > 0 ? new Semaphore(limit) : undefined;
+        // 阈值取"上限的十倍"：并发 1 的时候 10 条积压就值得说一句，
+        // 并发 16 的时候 10 条只是正常波峰。下限 50 免得小上限下刷屏
+        this.#backlogWarnAt = Math.max(limit * 10, 50);
+    }
+    /** 累计处理的事件数 */
+    get handled() {
+        return this.#handled;
+    }
+    /** 当前因并发上限而排队等待的命令数；未配置上限时恒为 0 */
+    get queued() {
+        return this.#gate?.pending ?? 0;
+    }
+    /**
+     * 投递一条事件并处理完毕
+     *
+     * 适配器唯一的入口。**永不抛出**：任何错误都在这里落日志并转成
+     * `pipeline/error` 事件，适配器不需要 try/catch。
+     * @param incoming 适配器产出的事件
+     * @param bot 接收该事件的 Bot
+     */
+    async submit(incoming, bot) {
+        let event;
+        try {
+            if (incoming.kind === "message") {
+                if (!this.#acceptMessage(incoming, bot))
+                    return;
+                const e = this.#factory.createMessage(incoming, bot);
+                event = e;
+                this.#handled++;
+                await this.#processMessage(e);
+                return;
+            }
+            // 请求事件同样受维护模式约束：同意加群也是一种"对普通用户的响应"。
+            // 通知与元事件不受约束 —— "有人退群就清理他的数据"这类插件在维护模式下
+            // 也必须继续工作，否则维护结束后数据就对不上了。
+            if (incoming.kind === "request" && !this.#acceptRequest(incoming))
+                return;
+            const other = this.#factory.create(incoming, bot);
+            event = other;
+            this.#handled++;
+            await this.#processOther(other);
+        }
+        catch (err) {
+            if (event === undefined) {
+                // 连事件对象都没构造出来，说明适配器交上来的报文不合规
+                this.#logger.error(`构造事件失败（适配器 ${bot.adapterId}）：${errText(err)}`);
+                return;
+            }
+            this.#logger.error(`处理事件 ${event.id} 时抛出未捕获错误：${errText(err)}`);
+            // 用 detached：错误处理插件自己再抛错也不该影响这条调用链
+            this.#events.emitDetached("pipeline/error", event, err);
+        }
+    }
+    /**
+     * 消息事件的准入判定
+     * @param incoming 适配器产出的消息事件
+     * @param bot 接收该事件的 Bot
+     * @returns 是否继续处理
+     */
+    #acceptMessage(incoming, bot) {
+        if (this.#policy.ignoreSelf && incoming.sender.uid === bot.selfId)
+            return false;
+        if (!this.#policy.canRespond(incoming.sender.uid)) {
+            if (this.#logger.isLevelEnabled("trace")) {
+                this.#logger.trace(`维护模式：忽略 ${incoming.sender.uid} 的消息`);
+            }
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 请求事件的准入判定
+     * @param incoming 适配器产出的请求事件
+     * @returns 是否继续处理
+     */
+    #acceptRequest(incoming) {
+        return this.#policy.canRespond(incoming.uid);
+    }
+    /**
+     * 处理消息事件
+     * @param e 运行时消息事件
+     */
+    async #processMessage(e) {
+        this.#logIncoming(e);
+        // core 里先路由再广播：`message` 总线事件的契约是"命令路由之后触发"，
+        // 统计类插件因此能看到 e.command 是否有值
+        await this.#middlewares.run(e, async () => {
+            await this.#route(e);
+            await this.#events.emit("message", e);
+        });
+    }
+    /**
+     * 处理通知 / 请求 / 元事件
+     *
+     * 这三类不存在"核心处理"—— 内核不代替插件决定是否同意入群请求。广播本身即为核心，
+     * 因此置于 `run` 的 core 位置：中间件调用 `stop()` 后自然不会广播，
+     * 无须在外层再判定一次 `stopped`。
+     * @param event 运行时事件
+     */
+    async #processOther(event) {
+        await this.#middlewares.run(event, async () => {
+            switch (event.kind) {
+                case "notice":
+                    await this.#events.emit("notice", event);
+                    return;
+                case "request":
+                    await this.#events.emit("request", event);
+                    return;
+                case "meta":
+                    await this.#events.emit("meta", event);
+                    return;
+            }
+        });
+    }
+    /**
+     * 等待者投递 + 命令路由
+     *
+     * 并发闸门刻意开在**这里**而不是 `submit()` 入口，原因是 `e.prompt()`：
+     * 一个正在等用户回话的命令会一直占着许可，而"能结束这次等待"的下一条消息
+     * 必须先取得许可方能被处理 —— 闸门置于入口即构成死锁。等待者投递不需要
+     * 许可（它仅是唤醒一个已在执行中的处理函数），因此在 `offer()` 之后再取许可
+     * 既拦住了昂贵的命令处理，又不会将交互式流程锁死。
+     *
+     * 代价是中间件与 `message` 总线事件不受限制。它们本应是轻量的，
+     * 真正可能同时开启大量浏览器页面的是命令处理函数。
+     * @param e 运行时消息事件
+     */
+    async #route(e) {
+        // 命中等待者即消费掉这条消息，不再进路由
+        if (this.#prompts.offer(e))
+            return;
+        const candidates = this.#router.match(e);
+        if (candidates.length === 0)
+            return;
+        const gate = this.#gate;
+        if (gate === undefined)
+            return this.#invokeAll(e, candidates);
+        // 不丢弃积压，只告警：事件对象在这一步之前就已经构造出来了，
+        // 丢掉它省不下多少内存，却会让用户的命令无声消失
+        if (gate.pending >= this.#backlogWarnAt) {
+            this.#backlogWarns++;
+            if (this.#backlogWarns === 1 || this.#backlogWarns % 100 === 0) {
+                this.#logger.warn(`命令处理积压 ${gate.pending} 条（并发上限 ${gate.active} 已满）。` +
+                    `若非突发流量，请调大配置项 message.concurrency 或排查耗时过长的命令`);
+            }
+        }
+        return gate.use(() => this.#invokeAll(e, candidates));
+    }
+    /**
+     * 依次尝试候选命令，直到有一条命中并阻断
+     * @param e 运行时消息事件
+     * @param candidates 候选命令
+     */
+    async #invokeAll(e, candidates) {
+        for (const candidate of candidates) {
+            if (e.stopped)
+                break;
+            const handled = await this.#invoke(e, candidate.reg, candidate.match);
+            if (!handled)
+                continue;
+            // 缺省阻断：一条消息通常只该有一个功能响应。声明 block: false 的
+            // 命令（如日志、统计类）才会让后面的命令继续匹配。
+            if (candidate.reg.options.block !== false)
+                break;
+        }
+    }
+    /**
+     * 执行一条命令（含冷却计费）
+     * @param e 运行时消息事件
+     * @param reg 命令登记
+     * @param match 匹配结果
+     * @returns 是否算作"已处理"
+     */
+    async #invoke(e, reg, match) {
+        const handler = reg.handler;
+        if (handler === undefined)
+            return false;
+        // 冷却判定放在这里而不是路由里：路由是纯查询，WebUI 要能反复调用它做预览，
+        // 而 hit() 会真的占用配额。只有确定要执行才计费。
+        const ms = parseDuration(reg.options.cooldown, 0);
+        let cdKey;
+        if (ms > 0 && !e.isMaster) {
+            cdKey = cooldownKey(reg.plugin, match.name, reg.options.cooldownScope ?? "user", e);
+            const decision = this.#cooldown.hit(cdKey, ms);
+            if (!decision.ok) {
+                const tip = reg.options.cooldownTip;
+                if (tip !== undefined && tip !== "")
+                    await e.reply(renderCooldownTip(tip, decision.remaining));
+                // 冷却中也算"已处理"：继续往下匹配的话，用户会看到"刷太快反而
+                // 触发了另一个功能"，比什么都不回更费解
+                return true;
+            }
+        }
+        e.command = match;
+        e.bind(this.#plugins(reg.plugin));
+        const started = Date.now();
+        // 命中即记：这行与「处理完毕」成对出现，缺了它则一条命令耗时很长时，
+        // 使用者只看到消息进来了而不知道正在跑哪个命令
+        this.#logger.info(`命令命中 ${reg.plugin}:${match.name}`);
+        try {
+            const result = await handler(e);
+            if (result === false) {
+                // 插件显式表示"我不处理这条"，把刚占用的 CD 退回去。
+                // 不发 command/done：这条命令并未处理该消息，计入调用统计会虚高
+                if (cdKey !== undefined)
+                    this.#cooldown.reset(cdKey);
+                return false;
+            }
+            const cost = Date.now() - started;
+            // 级别由 debug 提到 info：默认级别是 info，包在 debug 里等于这行永不出现，
+            // 使用者看到的是「消息进来了，然后没有下文」
+            this.#logger.info(`命令 ${reg.plugin}:${match.name} 处理完毕，耗时 ${cost}ms`);
+            this.#events.emitDetached("command/done", e, { plugin: reg.plugin, command: match.name, cost, ok: true });
+            return true;
+        }
+        catch (err) {
+            // 执行失败不该让用户为此等一个完整的 CD
+            if (cdKey !== undefined)
+                this.#cooldown.reset(cdKey);
+            const cost = Date.now() - started;
+            this.#logger.error(`插件 ${reg.plugin} 的命令 ${match.name} 执行出错（耗时 ${cost}ms）：${errText(err)}`);
+            this.#events.emitDetached("pipeline/error", e, err);
+            // 失败同样发 command/done：统计要算成功率，只在成功时发则分母永远等于分子
+            this.#events.emitDetached("command/done", e, {
+                plugin: reg.plugin,
+                command: match.name,
+                cost,
+                ok: false,
+                error: err instanceof Error ? err.message : String(err)
+            });
+            // 出错也算已处理：继续匹配只会让用户收到一条不相关的回复
+            return true;
+        }
+        finally {
+            // 解绑：脱离处理函数后 e.render() 应当明确报错而不是渲染到上一个插件的
+            // 模板目录里去。异步回调里要渲染请用 ctx.render()。
+            e.bind(undefined);
+        }
+    }
+    /**
+     * 记录收到的消息
+     *
+     * **必带协议与账号。** 同一进程可同时挂多个平台的多个账号，只记
+     * 「[群 X] 某人: 内容」在排障时答不出「这条是哪个号收到的」——
+     * 而 `bot` 对象本就在手边。格式取 `platform:selfId`：平台名说明是哪个协议，
+     * selfId 说明是哪个号，二者都取自 `e.bot` 的 getter，不缓存。
+     * @param e 运行时消息事件
+     */
+    #logIncoming(e) {
+        if (!this.#logger.isLevelEnabled("info"))
+            return;
+        const who = `${e.sender.name ?? ""}(${e.sender.uid})`;
+        const body = describeMessage(e.message);
+        const via = `${e.bot.platform}:${e.bot.selfId}`;
+        switch (e.scene) {
+            case "group":
+                this.#logger.info(`[${via}][群 ${e.group?.name ?? e.group?.gid ?? "?"}] ${who}: ${body}`);
+                return;
+            case "guild":
+                this.#logger.info(`[${via}][频道 ${e.channel?.name ?? e.channel?.channelId ?? "?"}] ${who}: ${body}`);
+                return;
+            case "private":
+                this.#logger.info(`[${via}][私聊] ${who}: ${body}`);
+                return;
+        }
+    }
+}
+//# sourceMappingURL=dispatch.js.map