hotcat-bot-qq 0.0.1 → 0.1.1

package/README.md

@@ -19,7 +19,8 @@ bun add hotcat-bot-qq
 ## 快速开始
 
 ```ts
-import { BotClient, Message } from 'hotcat-bot-qq'
+import { BotClient } from './botClient'
+import { Message } from './message'
 
 const bot = new BotClient({
     baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
@@ -39,14 +40,13 @@ bot.event.message.onGroupMessage(async (bot, event) => {
 
 - **类型安全** — 完整的 TypeScript 类型推导，封装 napcat 全部 API
 - **消息段构建** — `Message` 类支持文本、图片、表情、文件等所有消息类型
-- **彩色日志** — 内置 `BotConsole` 控制台日志，自动解析 CQ 码
 - **事件系统** — `BotEvent` 按类别分组暴露 message/messageSent/request/notice 事件
+- **定时任务** — `BotScheduler` 支持 cron 表达式、固定间隔、指定时间
+- **插件系统** — 继承 `PluginBase` 即可开发插件，支持热重载、目录监听自动加载，`scan` + `watch` 零配置接入
 
 ## 文档
 
-完整文档 → [hotcat-bot-qq.docs.chcat1320.top](https://hotcat-bot-qq.docs.chcat1320.top)
-
-快速开始 → [docs/guide/getting-started.md](docs/guide/getting-started.md)
+完整文档 → [框架开发文档](https://hotcat-bot-qq.docs.chcat1320.top)
 
 ## 协议
 

package/dist/botClient.d.ts

@@ -1,33 +1,35 @@
-import { NCWebsocketOptions } from 'node-napcat-ts';
 import { BotApi } from './botApi';
 import { BotEvent } from './botEvent';
+import { BotScheduler } from './botScheduler';
+/** Bot 配置 */
+export interface BotConfig {
+    baseUrl: string;
+    accessToken?: string;
+    reconnection?: {
+        enable?: boolean;
+        attempts?: number;
+        delay?: number;
+    };
+    apiTimeout?: number;
+}
 /**
  * Bot 客户端，封装连接、启动流程及 bot 自身信息。
  *
  * @example
- * ```ts
  * const bot = new BotClient({
-    baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
-    accessToken: 'yourAccessToken',
-    reconnection: {
-        enable: true,
-        attempts: 10,
-        delay: 5000,
-    },
-   });
- * await bot.start();
- * ```
+ *     baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
+ *     accessToken: 'yourAccessToken',
+ * })
+ * await bot.start()
  */
 export declare class BotClient {
-    /** API 调用入口 */
     api: BotApi;
-    /** 事件监听入口 */
     event: BotEvent;
-    /** 登录后 bot 自身昵称 */
+    scheduler: BotScheduler;
+    plugin: import('./botPlugin').BotPluginSystem;
     nickname: string | null;
-    /** 登录后 bot 自身 QQ 号 */
     id: number | null;
-    constructor(config: NCWebsocketOptions);
+    constructor(config: BotConfig);
     /**
      * 连接 napcat 并初始化事件监听，启动成功后自动填充 {@link nickname} 和 {@link id}。
      */

package/dist/botClient.js

@@ -1,47 +1,49 @@
 import { BotApi } from './botApi';
 import { BotConsole } from './botConsole';
 import { BotEvent } from './botEvent';
+import { BotScheduler } from './botScheduler';
 /**
  * Bot 客户端，封装连接、启动流程及 bot 自身信息。
  *
  * @example
- * ```ts
  * const bot = new BotClient({
-    baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
-    accessToken: 'yourAccessToken',
-    reconnection: {
-        enable: true,
-        attempts: 10,
-        delay: 5000,
-    },
-   });
- * await bot.start();
- * ```
+ *     baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
+ *     accessToken: 'yourAccessToken',
+ * })
+ * await bot.start()
  */
 export class BotClient {
     constructor(config) {
-        /** API 调用入口 */
         Object.defineProperty(this, "api", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** 事件监听入口 */
         Object.defineProperty(this, "event", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** 登录后 bot 自身昵称 */
+        Object.defineProperty(this, "scheduler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "plugin", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "nickname", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** 登录后 bot 自身 QQ 号 */
         Object.defineProperty(this, "id", {
             enumerable: true,
             configurable: true,
@@ -51,6 +53,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;
     }
@@ -59,6 +62,8 @@ export class BotClient {
      */
     async start() {
         await this.api.connect();
+        const { BotPluginSystem } = await import('./botPlugin');
+        this.plugin = new BotPluginSystem(this.api, this);
         this.api.napcat.on('meta_event.lifecycle.connect', () => {
             new BotConsole('system', 'napcat服务器连接成功').log();
         });
@@ -71,5 +76,7 @@ export class BotClient {
         catch (e) {
             new BotConsole('error', e instanceof Error ? e.message : JSON.stringify(e)).log();
         }
+        await this.plugin.scan('./plugins');
+        this.plugin.watch('./plugins');
     }
 }

package/dist/botPlugin.d.ts

@@ -0,0 +1,68 @@
+import type { BotApi } from './botApi';
+import type { BotClient } from './botClient';
+import { PluginBase, PluginConstructor, PluginMeta } from './plugin';
+/**
+ * 插件管理器，通过 `bot.plugin.xxx()` 访问。
+ *
+ * @example
+ * bot.plugin.register('test', TestPlugin, { name: 'test', version: '1.0.0' })
+ * await bot.plugin.load('test')
+ *
+ * // 自动扫描并监视
+ * await bot.plugin.scan('./plugins')
+ * bot.plugin.watch('./plugins')
+ */
+export declare class BotPluginSystem {
+    private api;
+    private client;
+    private registry;
+    private instances;
+    private watcher;
+    private watchDir;
+    private watched;
+    constructor(api: BotApi, client: BotClient);
+    /**
+     * 注册插件（不加载）
+     * @param name - 唯一标识，重复注册抛错
+     * @param ctor - 插件类，必须实现 static create()
+     * @param meta - 插件元数据
+     */
+    register(name: string, ctor: PluginConstructor, meta: PluginMeta): void;
+    /**
+     * 加载插件
+     * @param name - 已注册的插件名
+     */
+    load(name: string): Promise<void>;
+    /**
+     * 卸载插件
+     * @param name - 已加载的插件名
+     */
+    unload(name: string): Promise<void>;
+    /**
+     * 热重载：先卸载再加载
+     * @param name - 已加载的插件名
+     */
+    reload(name: string): Promise<void>;
+    /** 获取已加载的插件实例 */
+    get(name: string): PluginBase | undefined;
+    /** 返回所有已注册的插件名列表 */
+    list(): string[];
+    /** 返回所有已加载的插件名列表 */
+    loaded(): string[];
+    /**
+     * 扫描目录，自动注册并加载所有插件
+     * @param dir - 插件目录路径
+     * @param autoLoad - 是否自动加载，默认 true
+     * @returns 加载成功的插件名列表
+     */
+    scan(dir: string, autoLoad?: boolean): Promise<string[]>;
+    /**
+     * 开始监听目录，自动加载新增插件、卸载已删除插件
+     * @param dir - 插件目录路径
+     * @param interval - 轮询间隔(ms)，默认 5000
+     */
+    watch(dir: string, interval?: number): void;
+    /** 停止目录监听 */
+    unwatch(): void;
+    private scanOne;
+}

package/dist/botPlugin.js

@@ -0,0 +1,243 @@
+import { BotConsole } from './botConsole';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * 插件管理器，通过 `bot.plugin.xxx()` 访问。
+ *
+ * @example
+ * bot.plugin.register('test', TestPlugin, { name: 'test', version: '1.0.0' })
+ * await bot.plugin.load('test')
+ *
+ * // 自动扫描并监视
+ * await bot.plugin.scan('./plugins')
+ * bot.plugin.watch('./plugins')
+ */
+export class BotPluginSystem {
+    constructor(api, client) {
+        Object.defineProperty(this, "api", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "client", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "registry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "instances", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "watcher", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "watchDir", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "watched", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        this.api = api;
+        this.client = client;
+    }
+    /**
+     * 注册插件（不加载）
+     * @param name - 唯一标识，重复注册抛错
+     * @param ctor - 插件类，必须实现 static create()
+     * @param meta - 插件元数据
+     */
+    register(name, ctor, meta) {
+        if (this.registry.has(name)) {
+            throw new Error(`插件 "${name}" 已注册`);
+        }
+        this.registry.set(name, { ctor, meta });
+        new BotConsole('system', `插件 "${meta.name}" 已注册`).log();
+    }
+    /**
+     * 加载插件
+     * @param name - 已注册的插件名
+     */
+    async load(name) {
+        if (this.instances.has(name)) {
+            throw new Error(`插件 "${name}" 已加载`);
+        }
+        const record = this.registry.get(name);
+        if (!record) {
+            throw new Error(`插件 "${name}" 未注册`);
+        }
+        const instance = record.ctor.create(this.api, this.client, record.meta);
+        await instance.load();
+        this.instances.set(name, instance);
+        new BotConsole('system', `插件 "${record.meta.name}" 已加载`).log();
+    }
+    /**
+     * 卸载插件
+     * @param name - 已加载的插件名
+     */
+    async unload(name) {
+        const instance = this.instances.get(name);
+        if (!instance) {
+            throw new Error(`插件 "${name}" 未加载`);
+        }
+        await instance.unload();
+        this.instances.delete(name);
+        new BotConsole('system', `插件 "${name}" 已卸载`).log();
+    }
+    /**
+     * 热重载：先卸载再加载
+     * @param name - 已加载的插件名
+     */
+    async reload(name) {
+        await this.unload(name);
+        await this.load(name);
+    }
+    /** 获取已加载的插件实例 */
+    get(name) {
+        return this.instances.get(name);
+    }
+    /** 返回所有已注册的插件名列表 */
+    list() {
+        return Array.from(this.registry.keys());
+    }
+    /** 返回所有已加载的插件名列表 */
+    loaded() {
+        return Array.from(this.instances.keys());
+    }
+    /**
+     * 扫描目录，自动注册并加载所有插件
+     * @param dir - 插件目录路径
+     * @param autoLoad - 是否自动加载，默认 true
+     * @returns 加载成功的插件名列表
+     */
+    async scan(dir, autoLoad = true) {
+        const loaded = [];
+        if (!fs.existsSync(dir))
+            return loaded;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const name = entry.name;
+            const indexPath = path.join(dir, name, 'index.ts');
+            if (!fs.existsSync(indexPath))
+                continue;
+            try {
+                const mod = await import(path.resolve(indexPath));
+                const ctor = mod[name.charAt(0).toUpperCase() + name.slice(1) + 'Plugin'] || mod.default || Object.values(mod).find((v) => typeof v === 'function' && v.create);
+                if (!ctor || typeof ctor.create !== 'function') {
+                    new BotConsole('error', `插件目录 "${name}" 未导出符合规范的插件类`).log();
+                    continue;
+                }
+                const meta = ctor.meta || {
+                    name,
+                    version: '0.0.0',
+                };
+                this.register(name, ctor, meta);
+                if (autoLoad) {
+                    await this.load(name);
+                    loaded.push(name);
+                }
+            }
+            catch (e) {
+                new BotConsole('error', `加载插件 "${name}" 失败: ${e.message || e}`).log();
+            }
+        }
+        return loaded;
+    }
+    /**
+     * 开始监听目录，自动加载新增插件、卸载已删除插件
+     * @param dir - 插件目录路径
+     * @param interval - 轮询间隔(ms)，默认 5000
+     */
+    watch(dir, interval = 5000) {
+        if (this.watcher) {
+            new BotConsole('error', '已在监听中，请先调用 unwatch()').log();
+            return;
+        }
+        this.watchDir = path.resolve(dir);
+        if (!fs.existsSync(this.watchDir)) {
+            new BotConsole('error', `目录不存在: ${this.watchDir}`).log();
+            return;
+        }
+        this.watched = new Set(this.list());
+        new BotConsole('system', `开始监听插件目录: ${this.watchDir}`).log();
+        this.watcher = setInterval(async () => {
+            if (!fs.existsSync(this.watchDir))
+                return;
+            const entries = fs.readdirSync(this.watchDir, { withFileTypes: true });
+            const current = new Set();
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const name = entry.name;
+                const indexPath = path.join(this.watchDir, name, 'index.ts');
+                if (!fs.existsSync(indexPath))
+                    continue;
+                current.add(name);
+                if (!this.watched.has(name)) {
+                    await this.scanOne(this.watchDir, name);
+                }
+            }
+            for (const name of Array.from(this.watched)) {
+                if (!current.has(name) && this.registry.has(name)) {
+                    try {
+                        if (this.instances.has(name)) {
+                            await this.unload(name);
+                        }
+                        this.registry.delete(name);
+                        new BotConsole('system', `插件 "${name}" 目录已删除，已移除`).log();
+                    }
+                    catch { }
+                }
+            }
+            this.watched = current;
+        }, interval);
+    }
+    /** 停止目录监听 */
+    unwatch() {
+        if (this.watcher) {
+            clearInterval(this.watcher);
+            this.watcher = null;
+            this.watchDir = null;
+            new BotConsole('system', '已停止插件目录监听').log();
+        }
+    }
+    async scanOne(dir, name) {
+        const indexPath = path.join(dir, name, 'index.ts');
+        try {
+            const mod = await import(indexPath);
+            const ctor = mod[name.charAt(0).toUpperCase() + name.slice(1) + 'Plugin'] || mod.default || Object.values(mod).find((v) => typeof v === 'function' && v.create);
+            if (!ctor || typeof ctor.create !== 'function')
+                return;
+            const meta = ctor.meta || {
+                name,
+                version: '0.0.0',
+            };
+            this.register(name, ctor, meta);
+            await this.load(name);
+            new BotConsole('system', `检测到新插件 "${name}"，已自动加载`).log();
+        }
+        catch (e) {
+            new BotConsole('error', `自动加载插件 "${name}" 失败: ${e.message || e}`).log();
+        }
+    }
+}

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,11 @@
 export { BotClient } from './botClient';
+export type { BotConfig } from './botClient';
 export { BotApi } from './botApi';
 export { BotEvent, MessageEvent, MessageSent, RequestEvent, NoticeEvent } from './botEvent';
+export { BotScheduler } from './botScheduler';
+export { BotPluginSystem } from './botPlugin';
 export { BotConsole, colors, parseCQ, formatMessage } from './botConsole';
 export type { BotConsoleType, PrivateMessage, PrivateMessageSelf, RequestGroup, NoticeEvent as NoticeEventType } from './botConsole';
 export { Message } from './message';
+export { PluginBase } from './plugin';
+export type { PluginMeta, PluginConstructor } from './plugin';

package/dist/index.js

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

package/dist/plugin.d.ts

@@ -0,0 +1,27 @@
+import type { BotApi } from './botApi';
+import type { BotClient } from './botClient';
+/** 插件元数据 */
+export interface PluginMeta {
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+}
+/** 所有插件必须继承此类 */
+export declare abstract class PluginBase {
+    protected api: BotApi;
+    protected bot: BotClient;
+    protected meta: PluginMeta;
+    /** 子类重写：声明插件元数据 */
+    static meta: PluginMeta;
+    constructor(api: BotApi, bot: BotClient, meta?: PluginMeta);
+    /** 插件加载时调用：注册事件、启动定时任务、初始化资源 */
+    abstract load(): Promise<void>;
+    /** 插件卸载时调用：移除事件监听、取消定时任务、释放资源 */
+    abstract unload(): Promise<void>;
+}
+/** 插件模块必须导出的构造函数签名 */
+export type PluginConstructor = {
+    create(api: BotApi, bot: BotClient, meta?: PluginMeta): PluginBase;
+    meta?: PluginMeta;
+};

package/dist/plugin.js

@@ -0,0 +1,34 @@
+/** 所有插件必须继承此类 */
+export class PluginBase {
+    constructor(api, bot, meta) {
+        Object.defineProperty(this, "api", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "bot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "meta", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.api = api;
+        this.bot = bot;
+        const Ctor = this.constructor;
+        this.meta = meta || Ctor.meta;
+    }
+}
+/** 子类重写：声明插件元数据 */
+Object.defineProperty(PluginBase, "meta", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: { name: '', version: '0.0.0' }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotcat-bot-qq",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "基于 node-napcat-ts 的 TypeScript QQ 机器人框架",
   "type": "module",
   "main": "dist/index.js",
@@ -29,10 +29,24 @@
     "./botEvent": {
       "types": "./dist/botEvent.d.ts",
       "default": "./dist/botEvent.js"
+    },
+    "./botScheduler": {
+      "types": "./dist/botScheduler.d.ts",
+      "default": "./dist/botScheduler.js"
+    },
+    "./botPlugin": {
+      "types": "./dist/botPlugin.d.ts",
+      "default": "./dist/botPlugin.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
     }
   },
   "files": [
     "dist",
+    "plugins/hotCatPlugin",
+    "scripts/postinstall.mjs",
     "LICENSE",
     "README.md",
     "logo.png"
@@ -40,6 +54,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "echo \"Error: no test specified\" && exit 1",
+    "postinstall": "node scripts/postinstall.mjs || bun scripts/postinstall.mjs || echo skip",
     "prepublishOnly": "bun run build",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
@@ -61,6 +76,7 @@
   },
   "dependencies": {
     "node-napcat-ts": "^0.4.25",
+    "node-schedule": "^2.1.1",
     "@types/node": "^26.1.2"
   },
   "devDependencies": {

package/plugins/hotCatPlugin/index.ts

@@ -0,0 +1,64 @@
+import { PluginBase } from 'hotcat-bot-qq/plugin'
+import { BotApi } from 'hotcat-bot-qq/botApi'
+import { BotClient } from 'hotcat-bot-qq/botClient'
+import { Message } from 'hotcat-bot-qq/message'
+import * as os from 'os'
+
+export class HotCatPlugin extends PluginBase {
+    static meta = {
+        name: 'hotCatPlugin',
+        version: '0.1.1',
+        description: 'HotCat 默认插件（#hotCat 指令查询 bot 状态）',
+        author: 'CHCAT1320',
+    }
+
+    private startTime = 0
+    private enabled = false
+
+    static create(api: BotApi, bot: BotClient) {
+        return new HotCatPlugin(api, bot)
+    }
+
+    async load() {
+        this.startTime = Date.now()
+        this.enabled = true
+        this.bot.event.message.onGroupMessage(this.onGroupMsg)
+    }
+
+    async unload() {
+        this.enabled = false
+    }
+
+    private onGroupMsg = async (_bot: BotClient, event: any) => {
+        if (!this.enabled) return
+        const msg = event.raw_message.trim()
+
+        if (msg === '#hotCat' || msg === '#hotcat') {
+            const uptime = this.formatUptime(Date.now() - this.startTime)
+            const platform = os.platform()
+            const arch = os.arch()
+
+            await this.api.sendGroupMessage(event.group_id,
+                Message.reply(event.message_id),
+                Message.text(
+                    `HotCat 信息\n` +
+                    `版本：${this.meta.version}\n` +
+                    `平台：${platform} ${arch}\n` +
+                    `运行时间：${uptime}`
+                )
+            )
+        }
+    }
+
+    private formatUptime(ms: number): string {
+        const s = Math.floor(ms / 1000)
+        const d = Math.floor(s / 86400)
+        const h = Math.floor((s % 86400) / 3600)
+        const m = Math.floor((s % 3600) / 60)
+        const parts: string[] = []
+        if (d > 0) parts.push(`${d}天`)
+        if (h > 0) parts.push(`${h}小时`)
+        if (m > 0) parts.push(`${m}分钟`)
+        return parts.length > 0 ? parts.join(' ') : '小于1分钟'
+    }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,19 @@
+import { existsSync, mkdirSync, cpSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const src = join(__dirname, '..', 'plugins', 'hotCatPlugin')
+const dest = join(process.cwd(), 'plugins', 'hotCatPlugin')
+
+if (existsSync(dest)) {
+    console.log('[hotCatBot] 插件 hotCatPlugin 已存在，跳过复制')
+    process.exit(0)
+}
+
+if (!existsSync(join(process.cwd(), 'plugins'))) {
+    mkdirSync(join(process.cwd(), 'plugins'), { recursive: true })
+}
+
+cpSync(src, dest, { recursive: true })
+console.log('[hotCatBot] 默认插件 hotCatPlugin 已复制到 ./plugins/hotCatPlugin/')