@yunzai-ng/core 0.1.0

package/dist/render/registry.js

@@ -0,0 +1,306 @@
+import { SubsystemUnavailableError } from "../plugin/hooks.js";
+import { TimeoutError, withTimeout } from "../util/defer.js";
+import { formatBytes } from "../util/duration.js";
+/** 可用状态的缓存时长（毫秒） */
+const AVAILABLE_TTL_OK = 60_000;
+/** 不可用状态的缓存时长（毫秒）：比可用短，见文件头第 2 点 */
+const AVAILABLE_TTL_FAIL = 10_000;
+/** 渲染的兜底超时（毫秒），仅当配置读不到时使用 */
+const FALLBACK_TIMEOUT = 60_000;
+/**
+ * 取错误的可读描述
+ * @param err 任意抛出物
+ * @returns 描述文本
+ */
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 渲染注册表
+ *
+ * 既是 `ctx.registerRenderer()` 的落点，也是 `ctx.render()` / `e.render()` 的执行处。
+ */
+export class RenderRegistry {
+    /** 日志器 */
+    #logger;
+    /** 取配置 */
+    #policy;
+    /** 渲染器 id → 条目，按注册顺序 */
+    #entries = new Map();
+    /** 正在进行的渲染器关闭操作，`stop()` 要等它们结束 */
+    #closing = new Set();
+    /** 渲染结束通知，见构造参数的说明 */
+    #onDone;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts) {
+        this.#logger = opts.logger.child({ scope: "render" });
+        this.#policy = opts.policy;
+        this.#onDone = opts.onDone;
+    }
+    /** 已注册的渲染器数量 */
+    get size() {
+        return this.#entries.size;
+    }
+    /**
+     * 注册一个渲染器
+     * @param provider 渲染器实现
+     * @param owner 提供方插件名
+     * @returns 注销句柄
+     * @throws 该 id 已被别的插件占用时
+     */
+    register(provider, owner) {
+        const existing = this.#entries.get(provider.id);
+        if (existing !== undefined) {
+            // 与适配器注册表同样的理由：id 是配置项 render.default 引用实现的凭据，
+            // 悄悄覆盖会让用户以为自己用的是另一个渲染器
+            throw new Error(`渲染器 id ${provider.id} 已被插件 ${existing.owner} 注册，插件 ${owner} 不能重复注册；请改用不同的 id`);
+        }
+        const entry = {
+            provider,
+            owner,
+            ok: undefined,
+            checkedAt: 0,
+            probing: undefined,
+            lastError: undefined,
+            succeeded: 0,
+            failed: 0
+        };
+        this.#entries.set(provider.id, entry);
+        this.#logger.info(`渲染器就绪：${provider.name ?? provider.id}（${provider.id}，来自插件 ${owner}）`);
+        return () => this.#remove(provider.id, entry);
+    }
+    /**
+     * 执行一次渲染
+     * @param req 渲染请求（模板根等已由插件上下文补全）
+     * @returns 渲染结果
+     * @throws 没有任何渲染器、没有可用渲染器、或全部渲染器都失败时
+     */
+    async render(req) {
+        if (this.#entries.size === 0) {
+            throw new SubsystemUnavailableError("渲染", "没有安装任何渲染器插件，建议安装 renderer-puppeteer");
+        }
+        const policy = this.#policy();
+        const full = this.#applyDefaults(req, policy);
+        const timeout = policy.timeout > 0 ? policy.timeout : FALLBACK_TIMEOUT;
+        const attempts = Math.max(0, policy.retry) + 1;
+        /**
+         * 整个 `render()` 的起点
+         *
+         * 全灭时上报的耗时取这一档，而非最后一次尝试的耗时：使用者等的是「这次渲染
+         * 花了多久才失败」，那包含全部渲染器的全部重试。成功路径不用它 ——
+         * 那里取渲染器自报的 `result.cost`，与「出图快慢」对得上。
+         */
+        const startedAll = Date.now();
+        /** 每个渲染器的失败原因，全灭时一起抛出 */
+        const reasons = [];
+        for (const entry of this.#candidates(policy.default)) {
+            const id = entry.provider.id;
+            if (!(await this.#available(entry))) {
+                reasons.push(`${id}：不可用（${entry.lastError ?? "available() 返回 false"}）`);
+                continue;
+            }
+            for (let attempt = 1; attempt <= attempts; attempt++) {
+                const started = Date.now();
+                try {
+                    const result = await withTimeout(entry.provider.render(full), timeout, `渲染器 ${id} 超时（${timeout}ms）`);
+                    entry.succeeded++;
+                    entry.lastError = undefined;
+                    const bytes = result.images.reduce((sum, img) => sum + img.byteLength, 0);
+                    // 级别由 debug 提到 info：渲染是最耗时的一环（数百毫秒到数秒），
+                    // 「消息进来了、图还没出」这段空白期正需要这行来说明进展。
+                    // 附上字节数 —— 出图异常大往往是模板里漏了尺寸约束，只看张数看不出来
+                    this.#logger.info(`渲染完成：${req.template} 由 ${id} 出图 ${result.images.length} 张（${formatBytes(bytes)}），耗时 ${result.cost}ms`);
+                    this.#onDone?.({
+                        renderer: id,
+                        template: req.template,
+                        images: result.images.length,
+                        bytes,
+                        cost: result.cost,
+                        ok: true
+                    });
+                    return result;
+                }
+                catch (err) {
+                    entry.failed++;
+                    entry.lastError = errText(err);
+                    // 令可用性缓存作废：浏览器崩溃须能在下一次渲染时被发现，见文件头第 2 点
+                    this.#invalidate(entry);
+                    const cost = Date.now() - started;
+                    const kind = err instanceof TimeoutError ? "超时" : "失败";
+                    if (attempt < attempts) {
+                        this.#logger.warn(`渲染${kind}（${id}，${req.template}，${cost}ms），第 ${attempt}/${attempts} 次重试`);
+                        continue;
+                    }
+                    reasons.push(`${id}：${entry.lastError}`);
+                    this.#logger.warn(`渲染器 ${id} 已重试 ${attempts} 次仍${kind}（${req.template}）`);
+                }
+            }
+        }
+        // 逐条汇总而不是只报最后一个：见文件头第 3 点
+        const summary = `模板 ${req.template} 渲染失败，已尝试 ${this.#entries.size} 个渲染器：\n  ${reasons.join("\n  ")}`;
+        // 全灭也报一次：统计要算成功率，只在成功时报则分母恒等于分子。
+        // `renderer` 取空串 —— 这一次没有任何渲染器出图，填谁都是错的
+        this.#onDone?.({
+            renderer: "",
+            template: req.template,
+            images: 0,
+            bytes: 0,
+            cost: Date.now() - startedAll,
+            ok: false,
+            error: summary
+        });
+        throw new Error(summary);
+    }
+    /**
+     * 列出已注册的渲染器
+     * @returns 渲染器描述数组，首选排在最前
+     */
+    list() {
+        const preferred = this.#policy().default;
+        return [...this.#candidates(preferred)].map(entry => ({
+            id: entry.provider.id,
+            name: entry.provider.name ?? entry.provider.id,
+            owner: entry.owner,
+            preferred: entry.provider.id === preferred,
+            available: entry.ok,
+            lastError: entry.lastError,
+            succeeded: entry.succeeded,
+            failed: entry.failed
+        }));
+    }
+    /**
+     * 摘除某插件注册的全部渲染器
+     *
+     * 兜底路径：插件上下文正常会逐条调用 Disposer，但插件 setup 中途抛错时
+     * 可能存在未经 ctx 的登记。
+     * @param owner 插件名
+     * @returns 摘除的条数
+     */
+    removePlugin(owner) {
+        let n = 0;
+        for (const [id, entry] of [...this.#entries]) {
+            if (entry.owner === owner) {
+                this.#remove(id, entry);
+                n++;
+            }
+        }
+        return n;
+    }
+    /**
+     * 关闭全部渲染器（停机时调用）
+     *
+     * 会等待插件卸载时那些"发出去就不管"的 `dispose()` 收尾 —— 否则进程退出时
+     * 可能留下没杀掉的 Chromium 子进程。
+     */
+    async stop() {
+        for (const [id, entry] of [...this.#entries])
+            this.#remove(id, entry);
+        if (this.#closing.size > 0)
+            await Promise.allSettled([...this.#closing]);
+        this.#closing.clear();
+    }
+    /**
+     * 按优先级排出候选渲染器
+     *
+     * 首选（`render.default`）排在第一位，其余按注册顺序。首选未注册时不报错 ——
+     * 使用者可能仅是尚未安装该插件，"能够产出图片"比"由指定渲染器产出图片"更为重要，
+     * 但选中其他渲染器时会留下一条日志。
+     * @param preferred 首选渲染器 id
+     * @returns 候选条目，按尝试顺序
+     */
+    *#candidates(preferred) {
+        const first = this.#entries.get(preferred);
+        if (first !== undefined)
+            yield first;
+        for (const entry of this.#entries.values()) {
+            if (entry !== first)
+                yield entry;
+        }
+    }
+    /**
+     * 判断渲染器当前可用
+     *
+     * 带 TTL 缓存 + 单例探测，见文件头第 1 点。
+     * @param entry 条目
+     * @returns 是否可用
+     */
+    async #available(entry) {
+        const now = Date.now();
+        if (entry.ok !== undefined) {
+            const ttl = entry.ok ? AVAILABLE_TTL_OK : AVAILABLE_TTL_FAIL;
+            if (now - entry.checkedAt < ttl)
+                return entry.ok;
+        }
+        // 已有探测在跑就搭它的车：十条消息同时出图不该触发十次 Chromium 探测
+        if (entry.probing !== undefined)
+            return entry.probing;
+        const probing = (async () => {
+            try {
+                return await entry.provider.available();
+            }
+            catch (err) {
+                // available() 自己抛错等同于不可用：一个探测都做不成的渲染器不能拿来出图
+                entry.lastError = `available() 抛出异常：${errText(err)}`;
+                return false;
+            }
+        })().then(ok => {
+            entry.ok = ok;
+            entry.checkedAt = Date.now();
+            entry.probing = undefined;
+            return ok;
+        });
+        entry.probing = probing;
+        return probing;
+    }
+    /**
+     * 让可用性缓存作废
+     * @param entry 条目
+     */
+    #invalidate(entry) {
+        entry.ok = undefined;
+        entry.checkedAt = 0;
+    }
+    /**
+     * 补齐全局缺省值
+     *
+     * 仅填充插件未指定的项：插件中硬编码的 `quality: 100` 表明其有相应理由，
+     * 全局配置不应覆盖它。
+     * @param req 原始请求
+     * @param policy 当前配置
+     * @returns 补全后的请求
+     */
+    #applyDefaults(req, policy) {
+        return {
+            ...req,
+            quality: req.quality ?? policy.quality,
+            timeout: req.timeout ?? policy.timeout,
+            viewport: { ...req.viewport, scale: req.viewport?.scale ?? policy.scale }
+        };
+    }
+    /**
+     * 摘除一条注册并关闭渲染器
+     *
+     * 比对 entry 而不是只看 id：插件 A 卸载得晚、插件 B 已经用同一个 id 注册了
+     * 新实现时，A 的 Disposer 不应将 B 的实现摘除。
+     * @param id 渲染器 id
+     * @param entry 注册时的条目
+     */
+    #remove(id, entry) {
+        if (this.#entries.get(id) !== entry)
+            return;
+        this.#entries.delete(id);
+        const dispose = entry.provider.dispose;
+        if (dispose === undefined) {
+            this.#logger.info(`渲染器 ${id} 已摘除（插件 ${entry.owner}）`);
+            return;
+        }
+        // Disposer 是同步的，而关浏览器是异步的：把 promise 记下来交给 stop() 等，
+        // 不能就这么丢掉 —— 丢掉的后果是一个残留的 Chromium 进程
+        const closing = Promise.resolve(dispose.call(entry.provider)).then(() => void this.#logger.info(`渲染器 ${id} 已摘除并关闭（插件 ${entry.owner}）`), (err) => void this.#logger.error(`关闭渲染器 ${id} 时出错：${errText(err)}`, err));
+        this.#closing.add(closing);
+        void closing.finally(() => void this.#closing.delete(closing));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/render/registry.js.map

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

package/dist/scheduler/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 模块职责：定时任务调度器 —— 实现 `TaskSink`，兼作 WebUI 的任务查询表
+ * 依赖方向：依赖类型包、plugin/hooks 的接缝定义、util/*、croner；**不认识任何插件实现**
+ * 生命周期：随内核创建；每个任务随注册插件卸载而注销；`stop()` 停机时清空
+ * 注意事项：每个任务都是注册表里的一行：`list()` 可查、Disposer 可注销、`stop()` 一次清空 ——
+ *          插件各自 `setInterval` 的话，热重载后会残留无人回收的定时器。四项刻意的选择：
+ *
+ *          **重叠策略自己实现，不用 croner 的 `protect`。** 那个只对 cron 生效，而 `interval`
+ *          走 `setInterval`；两条路各用一套判定会让 `overlap` 的语义随 `kind` 漂移。
+ *
+ *          **`queue` 策略有积压上限。** 一个每分钟触发、每次跑十分钟的任务会排出无限长的队列，
+ *          超过 `MAX_QUEUE` 者丢弃并计入 `skipped`。
+ *
+ *          **超时后不再无限等待。** 先 abort 让守约定的任务自行收尾，但任务可能不响应 signal
+ *          （同步死循环、不收 signal 的第三方调用）。只 abort 而不停止等待会让 `running` 永久为
+ *          true，此后每轮都被跳过 —— 看着还在跑，实则再也不会触发。故宽限 `ABORT_GRACE` 后
+ *          停止等待，并记 error。
+ *
+ *          **执行出错同样计为已执行。** `lastRun` 在开始时就写，不等成功 —— 隐去失败的那次会让
+ *          人误认为调度器没工作。
+ */
+import type { Disposer, Logger, TaskInfo } from "@yunzai-ng/types";
+import type { TaskRegistration, TaskSink } from "../plugin/hooks.js";
+/** 调度器构造参数 */
+export interface SchedulerOptions {
+    /** 基础日志器 */
+    readonly logger: Logger;
+}
+/**
+ * 定时任务调度器
+ *
+ * 既是 `ctx.cron()` / `ctx.interval()` 的落点（`TaskSink`），也是 WebUI
+ * "定时任务"页面的数据来源（`list()`）。
+ */
+export declare class Scheduler implements TaskSink {
+    #private;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts: SchedulerOptions);
+    /** 当前登记的任务数 */
+    get size(): number;
+    /**
+     * 登记一个任务
+     * @param reg 登记内容
+     * @returns 注销句柄
+     * @throws cron 表达式非法、或 interval 间隔非法时
+     */
+    register(reg: TaskRegistration): Disposer;
+    /**
+     * 列出全部任务
+     * @returns 任务信息数组，按登记顺序
+     */
+    list(): TaskInfo[];
+    /**
+     * 注销某插件的全部任务
+     *
+     * 兜底路径：插件上下文正常会逐条调 Disposer，但插件 setup 抛在半路时
+     * 可能有登记没走 ctx。
+     * @param plugin 插件名
+     * @returns 注销的任务数
+     */
+    removePlugin(plugin: string): number;
+    /** 停止全部任务（停机时调用） */
+    stop(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAU,QAAQ,EAAe,MAAM,kBAAkB,CAAA;AAEvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAiDpE,cAAc;AACd,MAAM,WAAW,gBAAgB;IAC/B,YAAY;IACZ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAWD;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,QAAQ;;IAQxC;;OAEG;gBACS,IAAI,EAAE,gBAAgB;IAIlC,eAAe;IACf,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,gBAAgB,GAAG,QAAQ;IAqDzC;;;OAGG;IACH,IAAI,IAAI,QAAQ,EAAE;IAalB;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAepC,oBAAoB;IACpB,IAAI,IAAI,IAAI;CAkGb"}

package/dist/scheduler/index.js

@@ -0,0 +1,279 @@
+import { Cron } from "croner";
+import { TimeoutError, withTimeout } from "../util/defer.js";
+import { formatDuration, parseDuration } from "../util/duration.js";
+/** `queue` 策略下的积压上限，见文件头第 2 点 */
+const MAX_QUEUE = 3;
+/** 超时 abort 之后再宽限多久才放弃等待（毫秒），见文件头第 3 点 */
+const ABORT_GRACE = 5_000;
+/**
+ * 取错误的可读描述
+ * @param err 任意抛出物
+ * @returns 描述文本
+ */
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 定时任务调度器
+ *
+ * 既是 `ctx.cron()` / `ctx.interval()` 的落点（`TaskSink`），也是 WebUI
+ * "定时任务"页面的数据来源（`list()`）。
+ */
+export class Scheduler {
+    /** 日志器 */
+    #logger;
+    /** 全部任务，按登记顺序 */
+    #entries = [];
+    /** 是否已停机：停机后不再接受新任务 */
+    #stopped = false;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts) {
+        this.#logger = opts.logger.child({ scope: "scheduler" });
+    }
+    /** 当前登记的任务数 */
+    get size() {
+        return this.#entries.length;
+    }
+    /**
+     * 登记一个任务
+     * @param reg 登记内容
+     * @returns 注销句柄
+     * @throws cron 表达式非法、或 interval 间隔非法时
+     */
+    register(reg) {
+        const options = reg.options;
+        const state = { lastRun: undefined, lastCost: undefined, running: false, skipped: 0, queued: 0 };
+        // 间隔任务允许写 "5m" 这类字符串：插件作者不该为了 ctx.interval 去手算毫秒
+        const intervalMs = reg.kind === "interval" ? parseDuration(reg.schedule, 0) : 0;
+        const schedule = reg.kind === "interval" ? `每 ${formatDuration(intervalMs)}` : String(reg.schedule);
+        const name = options.name ?? schedule;
+        const logger = this.#logger.child({ task: name, plugin: reg.plugin });
+        const runner = this.#createRunner(name, reg.fn, options, state, logger);
+        let job;
+        if (reg.kind === "interval") {
+            // 上界是 setInterval 的 32 位溢出点：超过它 Node 会立刻、反复触发，
+            // 与"每 25 天跑一次"的意图正好相反
+            if (!Number.isFinite(intervalMs) || intervalMs <= 0 || intervalMs > 2_147_483_647) {
+                throw new Error(`任务 ${name} 的间隔非法（${String(reg.schedule)}）：必须是 1 毫秒到 24.8 天之间的时长`);
+            }
+            if (intervalMs < 1_000)
+                logger.warn(`任务 ${name} 的间隔只有 ${intervalMs}ms，请确认这是有意的`);
+            job = createIntervalJob(intervalMs, runner);
+        }
+        else {
+            job = createCronJob(String(reg.schedule), options.timezone, runner, name);
+        }
+        const entry = { plugin: reg.plugin, name, schedule, state, job };
+        // 停机之后仍有插件在登记任务：不能默默持有一个永不回收的定时器，
+        // 直接停掉并返回空 Disposer，与 DisposalRegistry 的同类处理保持一致
+        if (this.#stopped) {
+            job.stop();
+            logger.debug(`调度器已停止，任务 ${name} 不再启动`);
+            return () => { };
+        }
+        this.#entries.push(entry);
+        this.#logger.info(`任务已登记：${name}（${schedule}，来自插件 ${reg.plugin}）`);
+        // 立即执行一次也走 runner：它内部不 await，所以不会拖慢插件 setup
+        if (options.immediate === true)
+            runner();
+        return () => {
+            const at = this.#entries.indexOf(entry);
+            if (at < 0)
+                return;
+            this.#entries.splice(at, 1);
+            job.stop();
+            // 已在跑的那一轮不会被打断（没有安全的中断手段），但积压一律作废：
+            // 插件都卸载了，再补跑几轮只会去操作已经回收掉的资源
+            state.queued = 0;
+            logger.debug(`任务已注销：${name}`);
+        };
+    }
+    /**
+     * 列出全部任务
+     * @returns 任务信息数组，按登记顺序
+     */
+    list() {
+        return this.#entries.map(entry => ({
+            name: entry.name,
+            schedule: entry.schedule,
+            plugin: entry.plugin,
+            nextRun: entry.job.nextRun(),
+            lastRun: entry.state.lastRun,
+            lastCost: entry.state.lastCost,
+            running: entry.state.running,
+            skipped: entry.state.skipped
+        }));
+    }
+    /**
+     * 注销某插件的全部任务
+     *
+     * 兜底路径：插件上下文正常会逐条调 Disposer，但插件 setup 抛在半路时
+     * 可能有登记没走 ctx。
+     * @param plugin 插件名
+     * @returns 注销的任务数
+     */
+    removePlugin(plugin) {
+        let n = 0;
+        // 自后向前删除：正序遍历会因 splice 改变下标而遗漏相邻的同名任务
+        for (let i = this.#entries.length - 1; i >= 0; i--) {
+            const entry = this.#entries[i];
+            if (entry === undefined || entry.plugin !== plugin)
+                continue;
+            this.#entries.splice(i, 1);
+            entry.job.stop();
+            entry.state.queued = 0;
+            n++;
+        }
+        if (n > 0)
+            this.#logger.debug(`已注销插件 ${plugin} 的 ${n} 个任务`);
+        return n;
+    }
+    /** 停止全部任务（停机时调用） */
+    stop() {
+        this.#stopped = true;
+        for (const entry of this.#entries) {
+            entry.job.stop();
+            entry.state.queued = 0;
+        }
+        this.#entries.length = 0;
+    }
+    /**
+     * 造出任务的触发回调
+     *
+     * 重叠策略、超时、错误处理全在这里，因此 cron 与 interval 两种触发器
+     * 的行为完全一致，见文件头第 1 点。
+     * @param name 任务名
+     * @param fn 任务体
+     * @param options 任务选项
+     * @param state 运行时状态
+     * @param logger 任务日志器
+     * @returns 触发回调（同步返回，不会向触发器抛错）
+     */
+    #createRunner(name, fn, options, state, logger) {
+        const timeoutMs = parseDuration(options.timeout, 0);
+        const queueing = options.overlap === "queue";
+        /** 跑一轮，永不 reject */
+        const once = async () => {
+            const controller = new AbortController();
+            const started = Date.now();
+            state.lastRun = started;
+            let timer;
+            if (timeoutMs > 0) {
+                // unref：任务卡住不该让进程无法退出
+                timer = setTimeout(() => controller.abort(), timeoutMs);
+                timer.unref?.();
+            }
+            try {
+                const task = Promise.resolve(fn(controller.signal));
+                if (timeoutMs > 0) {
+                    // 此处已接住 task 的 rejection：宽限期过后调度器不再等待它，
+                    // 但其延迟到达的失败不得转为 unhandledRejection 而终止进程
+                    task.catch(() => { });
+                    await withTimeout(task, timeoutMs + ABORT_GRACE, `任务 ${name} 超时 ${timeoutMs}ms 后仍未结束`);
+                }
+                else {
+                    await task;
+                }
+            }
+            catch (err) {
+                if (err instanceof TimeoutError) {
+                    // 见文件头第 3 点：任务无视了 abort 信号，只能放弃等待
+                    logger.error(`任务 ${name} 超时后未响应中止信号，已放弃等待（任务可能仍在后台运行）：${errText(err)}`);
+                }
+                else if (controller.signal.aborted) {
+                    logger.warn(`任务 ${name} 因超时被中止（${timeoutMs}ms）`);
+                }
+                else {
+                    logger.error(`任务 ${name} 执行失败：${errText(err)}`, err);
+                }
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                state.lastCost = Date.now() - started;
+            }
+        };
+        /** 连跑：先跑一轮，再把积压清空 */
+        const drain = async () => {
+            state.running = true;
+            try {
+                await once();
+                while (state.queued > 0) {
+                    state.queued--;
+                    await once();
+                }
+            }
+            finally {
+                state.running = false;
+            }
+        };
+        return () => {
+            if (!state.running) {
+                void drain();
+                return;
+            }
+            if (queueing && state.queued < MAX_QUEUE) {
+                state.queued++;
+                logger.debug(`任务 ${name} 上一轮未结束，本轮排队（积压 ${state.queued}）`);
+                return;
+            }
+            state.skipped++;
+            const why = queueing ? `积压已达上限 ${MAX_QUEUE}` : "上一轮未结束";
+            // 第一次与每 10 次一报：一个长期重叠的任务不该把日志刷满，
+            // 但也不能一声不响 —— skipped 会一直涨，WebUI 上看得见
+            if (state.skipped === 1 || state.skipped % 10 === 0) {
+                logger.warn(`任务 ${name} ${why}，跳过本轮（累计跳过 ${state.skipped} 次）`);
+            }
+            else {
+                logger.debug(`任务 ${name} ${why}，跳过本轮`);
+            }
+        };
+    }
+}
+/**
+ * 造一个 cron 触发器
+ * @param pattern cron 表达式
+ * @param timezone 时区，缺省系统时区
+ * @param tick 触发回调
+ * @param name 任务名，仅用于报错
+ * @returns 触发器
+ * @throws 表达式非法时
+ */
+function createCronJob(pattern, timezone, tick, name) {
+    let cron;
+    try {
+        // 三个参数写全：croner 的签名是 (pattern, fnOrOptions1, fnOrOptions2)，
+        // 只传两个时选项会被当成回调
+        cron = new Cron(pattern, tick, { timezone, unref: true });
+    }
+    catch (err) {
+        // croner 的原始报错只说"哪个字段不认识"，补上任务名与表达式才够排查
+        throw new Error(`任务 ${name} 的 cron 表达式非法（${pattern}）：${errText(err)}`);
+    }
+    return {
+        nextRun: () => cron.nextRun()?.getTime(),
+        stop: () => void cron.stop()
+    };
+}
+/**
+ * 造一个固定间隔触发器
+ * @param ms 间隔毫秒
+ * @param tick 触发回调
+ * @returns 触发器
+ */
+function createIntervalJob(ms, tick) {
+    let nextAt = Date.now() + ms;
+    const timer = setInterval(() => {
+        nextAt = Date.now() + ms;
+        tick();
+    }, ms);
+    // unref：只有定时任务在等的时候，进程应该可以正常退出
+    timer.unref?.();
+    return {
+        nextRun: () => nextAt,
+        stop: () => clearInterval(timer)
+    };
+}
+//# sourceMappingURL=index.js.map