hotcat-bot-qq 0.1.9 → 0.1.11

package/README.md

@@ -1,53 +1,55 @@
-# HotCat Bot
-
-基于 [node-napcat-ts](https://github.com/HkTeamX/node-napcat-ts) 的 TypeScript QQ 机器人框架。
-
-<p align="center">
-  <img src="logo.png" width="120" alt="HotCat Bot Logo">
-</p>
-
-## 安装
-
-```bash
-npm add hotcat-bot-qq
-# or
-pnpm add hotcat-bot-qq
-# or
-bun add hotcat-bot-qq
-```
-
-## 快速开始
-
-```ts
-import { BotClient } from './botClient'
-import { Message } from './message'
-
-const bot = new BotClient({
-    baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
-    accessToken: 'your-access-token',
-})
-await bot.start()
-
-bot.event.message.onGroupMessage(async (bot, event) => {
-    await bot.api.sendGroupMessage(event.group_id,
-        Message.reply(event.message_id),
-        Message.text('pong!')
-    )
-})
-```
-
-## 特性
-
-- **类型安全** — 完整的 TypeScript 类型推导，封装 napcat 全部 API
-- **消息段构建** — `Message` 类支持文本、图片、表情、文件等所有消息类型
-- **事件系统** — `BotEvent` 按类别分组暴露 message/messageSent/request/notice 事件
-- **定时任务** — `BotScheduler` 支持 cron 表达式、固定间隔、指定时间
-- **插件系统** — 继承 `PluginBase` 即可开发插件，支持热重载、目录监听自动加载，`scan` + `watch` 零配置接入
-
-## 文档
-
-完整文档 → [框架开发文档](https://hotcat-bot-qq.docs.chcat1320.top)
-
-## 协议
-
-MIT © CHCAT1320
+# HotCat Bot
+
+基于 [node-napcat-ts](https://github.com/HkTeamX/node-napcat-ts) 的 TypeScript QQ 机器人框架。
+
+<p align="center">
+  <img src="logo.png" width="120" alt="HotCat Bot Logo">
+</p>
+
+## 安装
+
+```bash
+npm add hotcat-bot-qq
+# or
+pnpm add hotcat-bot-qq
+# or
+bun add hotcat-bot-qq
+```
+
+## 快速开始
+
+```ts
+import { BotClient } from './botClient'
+import { Message } from './message'
+
+const bot = new BotClient({
+    baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
+    accessToken: 'your-access-token',
+    owner: 123456789, // 必填：bot 主人（管理员）QQ 号
+})
+await bot.start()
+
+bot.event.message.onGroupMessage(async (bot, event) => {
+    await bot.api.sendGroupMessage(event.group_id,
+        Message.reply(event.message_id),
+        Message.text('pong!')
+    )
+})
+```
+
+## 特性
+
+- **类型安全** — 完整的 TypeScript 类型推导，封装 napcat 全部 API
+- **消息段构建** — `Message` 类支持文本、图片、表情、文件等所有消息类型
+- **事件系统** — `BotEvent` 按类别分组暴露 message/messageSent/request/notice 事件
+- **定时任务** — `BotScheduler` 支持 cron 表达式、固定间隔、指定时间
+- **插件系统** — 继承 `PluginBase` 即可开发插件，支持热重载、目录监听自动加载，`scan` + `watch` 零配置接入
+
+## 文档
+
+完整文档 → [框架开发文档](https://hotcat-bot-qq.docs.chcat1320.top)
+
+交流群638144340
+## 协议
+
+MIT © CHCAT1320

package/dist/botApi.js

@@ -1,5 +1,5 @@
 import { NCWebsocket } from 'node-napcat-ts';
-import { BotConsole } from './botConsole';
+import { BotConsole } from './botConsole.js';
 export class BotApi {
     get client() { return this._client; }
     set client(c) { this._client = c; }

package/dist/botClient.d.ts

@@ -5,6 +5,8 @@ import { BotScheduler } from './botScheduler';
 export interface BotConfig {
     baseUrl: string;
     accessToken?: string;
+    /** Bot 主人（管理员）QQ 号，必填，未配置将拒绝启动 */
+    owner: number;
     reconnection?: {
         enable?: boolean;
         attempts?: number;
@@ -19,6 +21,7 @@ export interface BotConfig {
  * const bot = new BotClient({
  *     baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
  *     accessToken: 'yourAccessToken',
+ *     owner: 123456789,
  * })
  * await bot.start()
  */
@@ -29,7 +32,14 @@ export declare class BotClient {
     plugin: import('./botPlugin').BotPluginSystem;
     nickname: string | null;
     id: number | null;
+    /** Bot 主人（管理员）QQ 号，来自配置项 `owner` */
+    owner: number;
     constructor(config: BotConfig);
+    /**
+     * 判断指定 QQ 号是否为 bot 主人
+     * @param qq - 待判断的 QQ 号
+     */
+    isOwner(qq: number | string): boolean;
     /**
      * 连接 napcat 并初始化事件监听，启动成功后自动填充 {@link nickname} 和 {@link id}。
      */

package/dist/botClient.js

@@ -1,7 +1,7 @@
-import { BotApi } from './botApi';
-import { BotConsole } from './botConsole';
-import { BotEvent } from './botEvent';
-import { BotScheduler } from './botScheduler';
+import { BotApi } from './botApi.js';
+import { BotConsole } from './botConsole.js';
+import { BotEvent } from './botEvent.js';
+import { BotScheduler } from './botScheduler.js';
 import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync, statSync, lstatSync } from 'fs';
 import { join, dirname, relative } from 'path';
 import { fileURLToPath } from 'url';
@@ -12,6 +12,7 @@ import { fileURLToPath } from 'url';
  * const bot = new BotClient({
  *     baseUrl: 'ws://localhost:8082/onebot/v11/ws/',
  *     accessToken: 'yourAccessToken',
+ *     owner: 123456789,
  * })
  * await bot.start()
  */
@@ -53,19 +54,45 @@ export class BotClient {
             writable: true,
             value: void 0
         });
-        this.api = new BotApi(config);
+        /** Bot 主人（管理员）QQ 号，来自配置项 `owner` */
+        Object.defineProperty(this, "owner", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const owner = Number(config?.owner);
+        if (!Number.isInteger(owner) || owner <= 0) {
+            throw new Error('未配置 bot 主人 QQ 号：请在 BotClient 配置中填写 owner 字段，例如 owner: 123456789，未配置前无法启动');
+        }
+        const baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl.trim() : '';
+        if (!baseUrl) {
+            throw new Error('未配置 NapCat WebSocket 地址：请在 BotClient 配置中填写 baseUrl 字段，例如 baseUrl: "ws://localhost:8082/onebot/v11/ws/"，未配置前无法启动');
+        }
+        if (!/^wss?:\/\/\S+$/i.test(baseUrl)) {
+            throw new Error('baseUrl 格式错误：必须以 ws:// 或 wss:// 开头，例如 ws://localhost:8082/onebot/v11/ws/');
+        }
+        this.owner = owner;
+        this.api = new BotApi({ ...config, baseUrl });
         this.api.client = this;
         this.event = new BotEvent(this.api, this);
         this.scheduler = new BotScheduler();
         this.nickname = null;
         this.id = null;
     }
+    /**
+     * 判断指定 QQ 号是否为 bot 主人
+     * @param qq - 待判断的 QQ 号
+     */
+    isOwner(qq) {
+        return Number(qq) === this.owner;
+    }
     /**
      * 连接 napcat 并初始化事件监听，启动成功后自动填充 {@link nickname} 和 {@link id}。
      */
     async start() {
         await this.api.connect();
-        const { BotPluginSystem } = await import('./botPlugin');
+        const { BotPluginSystem } = await import('./botPlugin.js');
         this.plugin = new BotPluginSystem(this.api, this);
         this.api.napcat.on('meta_event.lifecycle.connect', () => {
             new BotConsole('system', 'napcat服务器连接成功').log();

package/dist/botEvent.js

@@ -1,4 +1,4 @@
-import { BotConsole } from './botConsole';
+import { BotConsole } from './botConsole.js';
 /**
  * 接收到的事件处理（别人发的消息）。
  */

package/dist/botPlugin.js

@@ -1,6 +1,7 @@
-import { BotConsole } from './botConsole';
+import { BotConsole } from './botConsole.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { pathToFileURL } from 'url';
 /**
  * 插件管理器，通过 `bot.plugin.xxx()` 访问。
  *
@@ -150,7 +151,9 @@ export class BotPluginSystem {
             if (!indexPath)
                 continue;
             try {
-                const mod = await import(path.resolve(indexPath));
+                // Node 的 ESM 加载器不接受裸 Windows 绝对路径（ERR_UNSUPPORTED_ESM_URL_SCHEME），
+                // 必须转成 file:// URL；Bun 两者都接受。
+                const mod = await import(pathToFileURL(path.resolve(indexPath)).href);
                 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();
@@ -236,7 +239,7 @@ export class BotPluginSystem {
         if (!indexPath)
             return;
         try {
-            const mod = await import(indexPath);
+            const mod = await import(pathToFileURL(path.resolve(indexPath)).href);
             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;

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotcat-bot-qq",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "基于 node-napcat-ts 的 TypeScript QQ 机器人框架",
   "type": "module",
   "main": "dist/index.js",
@@ -51,9 +51,9 @@
     "logo.png"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "build:plugin": "tsc --outDir plugins/hotCatPlugin --rootDir plugins/hotCatPlugin --module ESNext --target ES2020 --moduleResolution bundler --declaration --skipLibCheck plugins/hotCatPlugin/index.ts",
-    "prepublishOnly": "bun run build && bun run build:plugin",
+    "build": "tsc -p tsconfig.build.json && node scripts/fix-dist-extensions.mjs",
+    "build:plugin": "bun run build && tsc --outDir plugins/hotCatPlugin --rootDir plugins/hotCatPlugin --module ESNext --target ES2020 --moduleResolution bundler --declaration --skipLibCheck plugins/hotCatPlugin/index.ts",
+    "prepublishOnly": "bun run build:plugin",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"

package/plugins/hotCatPlugin/index.d.ts

@@ -12,6 +12,9 @@ export declare class HotCatPlugin extends PluginBase {
     static create(api: BotApi, bot: BotClient): HotCatPlugin;
     load(): Promise<void>;
     unload(): Promise<void>;
+    private isInfoCommand;
+    private buildInfo;
     private onGroupMsg;
+    private onPrivateMsg;
     private formatUptime;
 }

package/plugins/hotCatPlugin/index.js

@@ -7,20 +7,15 @@ export class HotCatPlugin extends PluginBase {
         this.startTime = 0;
         this.onGroupMsg = async (_bot, event) => {
             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}\n` +
-                    `Github: https://github.com/CHCAT1320/hotCat-bot-qq\n` +
-                    `开发文档: https://hotcat-bot-qq.docs.chcat1320.top\n` +
-                    `交流群: 638144340\n` +
-                    `管理员QQ: 1095216448\n` +
-                    `基于 MIT 许可发布 版权所有 © 2026 CHCAT1320`));
-            }
+            if (!this.isInfoCommand(msg))
+                return;
+            await this.api.sendGroupMessage(event.group_id, Message.reply(event.message_id), Message.text(this.buildInfo()));
+        };
+        this.onPrivateMsg = async (_bot, event) => {
+            const msg = event.raw_message.trim();
+            if (!this.isInfoCommand(msg))
+                return;
+            await this.api.sendPrivateMessage(event.user_id, Message.text(this.buildInfo()));
         };
     }
     static create(api, bot) {
@@ -29,9 +24,28 @@ export class HotCatPlugin extends PluginBase {
     async load() {
         this.startTime = Date.now();
         this.bot.event.message.onGroupMessage(this.onGroupMsg);
+        this.bot.event.message.onPrivateMessage(this.onPrivateMsg);
     }
     async unload() {
         this.bot.event.message.offGroupMessage(this.onGroupMsg);
+        this.bot.event.message.offPrivateMessage(this.onPrivateMsg);
+    }
+    isInfoCommand(msg) {
+        return msg === '#hotCat' || msg === '#hotcat';
+    }
+    buildInfo() {
+        const uptime = this.formatUptime(Date.now() - this.startTime);
+        const platform = os.platform();
+        const arch = os.arch();
+        return `HotCat 信息\n` +
+            `版本：${this.meta.version}\n` +
+            `平台：${platform} ${arch}\n` +
+            `运行时间：${uptime}\n` +
+            `管理员QQ: ${this.bot.owner}\n` +
+            `Github: https://github.com/CHCAT1320/hotCat-bot-qq\n` +
+            `开发文档: https://hotcat-bot-qq.docs.chcat1320.top\n` +
+            `交流群: 638144340\n` +
+            `基于 MIT 许可发布 版权所有 © 2026 CHCAT1320`;
     }
     formatUptime(ms) {
         const s = Math.floor(ms / 1000);
@@ -50,7 +64,7 @@ export class HotCatPlugin extends PluginBase {
 }
 HotCatPlugin.meta = {
     name: 'hotCatPlugin',
-    version: '0.1.9',
-    description: 'HotCat 默认插件（#hotCat 指令查询 bot 状态）',
+    version: '0.1.11',
+    description: 'HotCat 默认插件（群聊/私聊 #hotCat 指令查询 bot 状态）',
     author: 'CHCAT1320',
 };

package/plugins/hotCatPlugin/index.ts

@@ -7,8 +7,8 @@ import * as os from 'os'
 export class HotCatPlugin extends PluginBase {
     static meta = {
         name: 'hotCatPlugin',
-        version: '0.1.9',
-        description: 'HotCat 默认插件（#hotCat 指令查询 bot 状态）',
+        version: '0.1.11',
+        description: 'HotCat 默认插件（群聊/私聊 #hotCat 指令查询 bot 状态）',
         author: 'CHCAT1320',
     }
 
@@ -21,35 +21,51 @@ export class HotCatPlugin extends PluginBase {
     async load() {
         this.startTime = Date.now()
         this.bot.event.message.onGroupMessage(this.onGroupMsg)
+        this.bot.event.message.onPrivateMessage(this.onPrivateMsg)
     }
 
     async unload() {
         this.bot.event.message.offGroupMessage(this.onGroupMsg)
+        this.bot.event.message.offPrivateMessage(this.onPrivateMsg)
+    }
+
+    private isInfoCommand(msg: string): boolean {
+        return msg === '#hotCat' || msg === '#hotcat'
+    }
+
+    private buildInfo(): string {
+        const uptime = this.formatUptime(Date.now() - this.startTime)
+        const platform = os.platform()
+        const arch = os.arch()
+
+        return `HotCat 信息\n` +
+            `版本：${this.meta.version}\n` +
+            `平台：${platform} ${arch}\n` +
+            `运行时间：${uptime}\n` +
+            `管理员QQ: ${this.bot.owner}\n` +
+            `Github: https://github.com/CHCAT1320/hotCat-bot-qq\n` +
+            `开发文档: https://hotcat-bot-qq.docs.chcat1320.top\n` +
+            `交流群: 638144340\n` +
+            `基于 MIT 许可发布 版权所有 © 2026 CHCAT1320`
     }
 
     private onGroupMsg = async (_bot: BotClient, event: any) => {
         const msg = event.raw_message.trim()
+        if (!this.isInfoCommand(msg)) return
+
+        await this.api.sendGroupMessage(event.group_id,
+            Message.reply(event.message_id),
+            Message.text(this.buildInfo())
+        )
+    }
 
-        if (msg === '#hotCat' || msg === '#hotcat') {
-            const uptime = this.formatUptime(Date.now() - this.startTime)
-            const platform = os.platform()
-            const arch = os.arch()
+    private onPrivateMsg = async (_bot: BotClient, event: any) => {
+        const msg = event.raw_message.trim()
+        if (!this.isInfoCommand(msg)) return
 
-            await this.api.sendGroupMessage(event.group_id,
-                Message.reply(event.message_id),
-                Message.text(
-                    `HotCat 信息\n` +
-                    `版本：${this.meta.version}\n` +
-                    `平台：${platform} ${arch}\n` +
-                    `运行时间：${uptime}\n` + 
-                    `Github: https://github.com/CHCAT1320/hotCat-bot-qq\n` + 
-                    `开发文档: https://hotcat-bot-qq.docs.chcat1320.top\n` + 
-                    `交流群: 638144340\n` + 
-                    `管理员QQ: 1095216448\n` + 
-                    `基于 MIT 许可发布 版权所有 © 2026 CHCAT1320`
-                )
-            )
-        }
+        await this.api.sendPrivateMessage(event.user_id,
+            Message.text(this.buildInfo())
+        )
     }
 
     private formatUptime(ms: number): string {