hotcat-bot-qq 0.0.1 → 0.1.0

package/dist/botClient.d.ts

@@ -1,6 +1,7 @@
 import { NCWebsocketOptions } from 'node-napcat-ts';
 import { BotApi } from './botApi';
 import { BotEvent } from './botEvent';
+import { BotScheduler } from './botScheduler';
 /**
  * Bot 客户端，封装连接、启动流程及 bot 自身信息。
  *
@@ -23,6 +24,8 @@ export declare class BotClient {
     api: BotApi;
     /** 事件监听入口 */
     event: BotEvent;
+    /** 定时任务入口 */
+    scheduler: BotScheduler;
     /** 登录后 bot 自身昵称 */
     nickname: string | null;
     /** 登录后 bot 自身 QQ 号 */

package/dist/botClient.js

@@ -1,6 +1,7 @@
 import { BotApi } from './botApi';
 import { BotConsole } from './botConsole';
 import { BotEvent } from './botEvent';
+import { BotScheduler } from './botScheduler';
 /**
  * Bot 客户端，封装连接、启动流程及 bot 自身信息。
  *
@@ -34,6 +35,13 @@ export class BotClient {
             writable: true,
             value: void 0
         });
+        /** 定时任务入口 */
+        Object.defineProperty(this, "scheduler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /** 登录后 bot 自身昵称 */
         Object.defineProperty(this, "nickname", {
             enumerable: true,
@@ -51,6 +59,7 @@ export class BotClient {
         this.api = new BotApi(config);
         this.api.client = this;
         this.event = new BotEvent(this.api, this);
+        this.scheduler = new BotScheduler();
         this.nickname = null;
         this.id = null;
     }

package/dist/botScheduler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 定时任务调度器，支持 cron、间隔、指定时间三种模式。
+ *
+ * cron('0 8 * * *', fn)    每天 8:00
+ * every('5m', fn)          每5分钟
+ * at('08:00', fn)          每天 8:00
+ */
+export declare class BotScheduler {
+    private jobs;
+    private idCounter;
+    /**
+     * cron 表达式定时
+     * @param expr - cron 表达式，如 `'0 8 * * *'`（每天 8:00）
+     * @param fn - 回调函数
+     * @returns job id，可用于 cancel
+     */
+    cron(expr: string, fn: () => void): number;
+    /**
+     * 间隔重复执行
+     * @param time - 间隔，支持数字(ms)或字符串 `'5s'` `'10m'` `'1h'` `'2d'`
+     * @param fn - 回调函数
+     * @returns job id
+     */
+    every(time: number | string, fn: () => void): number;
+    /**
+     * 指定时间执行（一次性或每日重复）
+     * @param time - 字符串 `'08:00'`（每日）/ `'2026-08-01 12:00'`（一次性），或 Date
+     * @param fn - 回调函数
+     * @returns job id
+     */
+    at(time: string | Date, fn: () => void): number;
+    /**
+     * 取消指定任务
+     * @param id - cron/every/at 返回的 id
+     */
+    cancel(id: number): void;
+    /** 取消全部任务 */
+    cancelAll(): void;
+    private parseTime;
+    private timeToCron;
+}

package/dist/botScheduler.js

@@ -0,0 +1,146 @@
+import * as schedule from 'node-schedule';
+/**
+ * 定时任务调度器，支持 cron、间隔、指定时间三种模式。
+ *
+ * cron('0 8 * * *', fn)    每天 8:00
+ * every('5m', fn)          每5分钟
+ * at('08:00', fn)          每天 8:00
+ */
+export class BotScheduler {
+    constructor() {
+        Object.defineProperty(this, "jobs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "idCounter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+    }
+    /**
+     * cron 表达式定时
+     * @param expr - cron 表达式，如 `'0 8 * * *'`（每天 8:00）
+     * @param fn - 回调函数
+     * @returns job id，可用于 cancel
+     */
+    cron(expr, fn) {
+        const id = ++this.idCounter;
+        const job = schedule.scheduleJob(expr, () => {
+            try {
+                fn();
+            }
+            catch { }
+        });
+        if (job)
+            this.jobs.set(id, job);
+        return id;
+    }
+    /**
+     * 间隔重复执行
+     * @param time - 间隔，支持数字(ms)或字符串 `'5s'` `'10m'` `'1h'` `'2d'`
+     * @param fn - 回调函数
+     * @returns job id
+     */
+    every(time, fn) {
+        const ms = typeof time === 'number' ? time : this.parseTime(time);
+        const id = ++this.idCounter;
+        const timer = setInterval(() => {
+            try {
+                fn();
+            }
+            catch { }
+        }, ms);
+        this.jobs.set(id, timer);
+        return id;
+    }
+    /**
+     * 指定时间执行（一次性或每日重复）
+     * @param time - 字符串 `'08:00'`（每日）/ `'2026-08-01 12:00'`（一次性），或 Date
+     * @param fn - 回调函数
+     * @returns job id
+     */
+    at(time, fn) {
+        const id = ++this.idCounter;
+        if (typeof time === 'string' && time.includes('-')) {
+            const target = new Date(time);
+            if (isNaN(target.getTime()))
+                return id;
+            const ms = target.getTime() - Date.now();
+            if (ms <= 0) {
+                try {
+                    fn();
+                }
+                catch { }
+                return id;
+            }
+            const timer = setTimeout(() => { try {
+                fn();
+            }
+            catch { } }, ms);
+            this.jobs.set(id, timer);
+            return id;
+        }
+        if (typeof time === 'string') {
+            return this.cron(this.timeToCron(time), fn);
+        }
+        const ms = time.getTime() - Date.now();
+        if (ms <= 0) {
+            try {
+                fn();
+            }
+            catch { }
+            return id;
+        }
+        const timer = setTimeout(() => { try {
+            fn();
+        }
+        catch { } }, ms);
+        this.jobs.set(id, timer);
+        return id;
+    }
+    /**
+     * 取消指定任务
+     * @param id - cron/every/at 返回的 id
+     */
+    cancel(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return;
+        if ('cancel' in job) {
+            job.cancel();
+        }
+        else {
+            clearInterval(job);
+        }
+        this.jobs.delete(id);
+    }
+    /** 取消全部任务 */
+    cancelAll() {
+        for (const id of Array.from(this.jobs.keys())) {
+            this.cancel(id);
+        }
+    }
+    parseTime(t) {
+        const m = t.match(/^(\d+)\s*(s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days)$/i);
+        if (!m)
+            return 0;
+        const v = parseInt(m[1]);
+        switch (m[2][0].toLowerCase()) {
+            case 's': return v * 1000;
+            case 'm': return v * 60000;
+            case 'h': return v * 3600000;
+            case 'd': return v * 86400000;
+            default: return 0;
+        }
+    }
+    timeToCron(t) {
+        const m = t.match(/^(\d{1,2}):(\d{2})$/);
+        if (!m)
+            return '';
+        return `${m[2]} ${m[1]} * * *`;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { BotClient } from './botClient';
 export { BotApi } from './botApi';
 export { BotEvent, MessageEvent, MessageSent, RequestEvent, NoticeEvent } from './botEvent';
+export { BotScheduler } from './botScheduler';
 export { BotConsole, colors, parseCQ, formatMessage } from './botConsole';
 export type { BotConsoleType, PrivateMessage, PrivateMessageSelf, RequestGroup, NoticeEvent as NoticeEventType } from './botConsole';
 export { Message } from './message';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { BotClient } from './botClient';
 export { BotApi } from './botApi';
 export { BotEvent, MessageEvent, MessageSent, RequestEvent, NoticeEvent } from './botEvent';
+export { BotScheduler } from './botScheduler';
 export { BotConsole, colors, parseCQ, formatMessage } from './botConsole';
 export { Message } from './message';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotcat-bot-qq",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "基于 node-napcat-ts 的 TypeScript QQ 机器人框架",
   "type": "module",
   "main": "dist/index.js",
@@ -61,6 +61,7 @@
   },
   "dependencies": {
     "node-napcat-ts": "^0.4.25",
+    "node-schedule": "^2.1.1",
     "@types/node": "^26.1.2"
   },
   "devDependencies": {