@onebots/core 0.5.0 → 1.0.4

package/lib/__tests__/lifecycle.test.js

@@ -0,0 +1,163 @@
+/**
+ * 生命周期管理测试
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LifecycleManager } from '../lifecycle.js';
+describe('Lifecycle Manager', () => {
+    let lifecycle;
+    beforeEach(() => {
+        lifecycle = new LifecycleManager();
+    });
+    describe('Resource Management', () => {
+        it('should register and cleanup resources', async () => {
+            let cleaned = false;
+            lifecycle.register('test-resource', () => {
+                cleaned = true;
+            });
+            expect(lifecycle.getResourceCount()).toBe(1);
+            expect(lifecycle.getResourceNames()).toContain('test-resource');
+            await lifecycle.cleanup();
+            expect(cleaned).toBe(true);
+            expect(lifecycle.getResourceCount()).toBe(0);
+        });
+        it('should handle multiple resources', async () => {
+            const cleaned = [];
+            lifecycle.register('resource1', () => {
+                cleaned.push('resource1');
+            });
+            lifecycle.register('resource2', () => {
+                cleaned.push('resource2');
+            });
+            await lifecycle.cleanup();
+            expect(cleaned).toContain('resource1');
+            expect(cleaned).toContain('resource2');
+        });
+        it('should handle resource cleanup errors', async () => {
+            const errorHandler = vi.fn();
+            lifecycle.on('cleanupError', errorHandler);
+            lifecycle.register('error-resource', () => {
+                throw new Error('Cleanup failed');
+            });
+            // 清理不应该抛出错误，应该触发事件
+            await expect(lifecycle.cleanup()).resolves.not.toThrow();
+            expect(errorHandler).toHaveBeenCalled();
+        });
+        it('should unregister resource', () => {
+            lifecycle.register('resource1', () => { });
+            lifecycle.register('resource2', () => { });
+            expect(lifecycle.unregister('resource1')).toBe(true);
+            expect(lifecycle.getResourceCount()).toBe(1);
+            expect(lifecycle.getResourceNames()).not.toContain('resource1');
+        });
+    });
+    describe('Lifecycle Hooks', () => {
+        it('should execute init hooks', async () => {
+            const initHook = vi.fn();
+            lifecycle.addHook({ onInit: initHook });
+            await lifecycle.init();
+            expect(initHook).toHaveBeenCalled();
+        });
+        it('should execute start hooks', async () => {
+            const startHook = vi.fn();
+            lifecycle.addHook({ onStart: startHook });
+            await lifecycle.start();
+            expect(startHook).toHaveBeenCalled();
+        });
+        it('should execute stop hooks', async () => {
+            const stopHook = vi.fn();
+            lifecycle.addHook({ onStop: stopHook });
+            await lifecycle.stop();
+            expect(stopHook).toHaveBeenCalled();
+        });
+        it('should execute cleanup hooks', async () => {
+            const cleanupHook = vi.fn();
+            lifecycle.addHook({ onCleanup: cleanupHook });
+            await lifecycle.cleanup();
+            expect(cleanupHook).toHaveBeenCalled();
+        });
+        it('should execute all hooks in order', async () => {
+            const order = [];
+            lifecycle.addHook({
+                onInit: () => {
+                    order.push('init');
+                },
+                onStart: () => {
+                    order.push('start');
+                },
+                onStop: () => {
+                    order.push('stop');
+                },
+                onCleanup: () => {
+                    order.push('cleanup');
+                },
+            });
+            await lifecycle.init();
+            await lifecycle.start();
+            await lifecycle.stop();
+            await lifecycle.cleanup();
+            expect(order).toEqual(['init', 'start', 'stop', 'cleanup']);
+        });
+    });
+    describe('Graceful Shutdown', () => {
+        it('should perform graceful shutdown', async () => {
+            const stopHook = vi.fn();
+            const cleanupHook = vi.fn();
+            lifecycle.addHook({
+                onStop: stopHook,
+                onCleanup: cleanupHook,
+            });
+            await lifecycle.gracefulShutdown('SIGTERM');
+            expect(stopHook).toHaveBeenCalled();
+            expect(cleanupHook).toHaveBeenCalled();
+        });
+        it('should emit shutdown events', async () => {
+            const shutdownHandler = vi.fn();
+            const shutdownCompleteHandler = vi.fn();
+            lifecycle.on('shutdown', shutdownHandler);
+            lifecycle.on('shutdownComplete', shutdownCompleteHandler);
+            await lifecycle.gracefulShutdown('SIGTERM');
+            expect(shutdownHandler).toHaveBeenCalledWith('SIGTERM');
+            expect(shutdownCompleteHandler).toHaveBeenCalled();
+        });
+        it('should handle shutdown timeout', async () => {
+            lifecycle.setShutdownTimeout(100);
+            const timeoutHandler = vi.fn();
+            lifecycle.on('shutdownTimeout', timeoutHandler);
+            // 添加一个永远不会完成的钩子
+            lifecycle.addHook({
+                onStop: () => new Promise(() => { }), // 永远pending
+            });
+            // 使用 vi.useFakeTimers 来测试超时
+            vi.useFakeTimers();
+            // 启动关闭流程
+            const shutdownPromise = lifecycle.gracefulShutdown(undefined, { exitOnTimeout: false });
+            // 等待超时事件触发
+            const timeoutPromise = new Promise((resolve) => {
+                lifecycle.once('shutdownTimeout', () => {
+                    timeoutHandler();
+                    resolve();
+                });
+            });
+            // 推进时间
+            vi.advanceTimersByTime(150);
+            // 等待超时事件
+            await timeoutPromise;
+            expect(timeoutHandler).toHaveBeenCalled();
+            // 清理
+            vi.useRealTimers();
+            // 取消关闭流程（避免测试挂起）
+            lifecycle.removeHook(lifecycle['hooks'][0]);
+        });
+    });
+    describe('Event Emission', () => {
+        it('should emit lifecycle events', async () => {
+            const beforeInit = vi.fn();
+            const afterInit = vi.fn();
+            lifecycle.on('beforeInit', beforeInit);
+            lifecycle.on('afterInit', afterInit);
+            await lifecycle.init();
+            expect(beforeInit).toHaveBeenCalled();
+            expect(afterInit).toHaveBeenCalled();
+        });
+    });
+});

package/lib/account.d.ts

@@ -36,7 +36,10 @@ export declare class Account<P extends keyof Adapter.Configs = keyof Adapter.Con
     stop(force?: boolean): Promise<void>;
     getGroupList(): Promise<Adapter.GroupInfo[]>;
     getFriendList(): Promise<Adapter.FriendInfo[]>;
-    dispatch(commonEvent: CommonEvent.Base): Promise<void>;
+    /**
+     * 将通用事件同步派发到本账号绑定的各协议（协议内自行 catch，避免一次失败阻断其它协议）
+     */
+    dispatch(commonEvent: CommonEvent.Base): void;
 }
 export declare enum AccountStatus {
     Pending = "pending",// 上线中

package/lib/account.js

@@ -85,10 +85,13 @@ export class Account extends EventEmitter {
     getFriendList() {
         return this.adapter.getFriendList(this.account_id);
     }
-    async dispatch(commonEvent) {
-        this.logger.debug(`Dispatching event: ${commonEvent.type}`);
-        // Each protocol instance formats the common event to its own standard
+    /**
+     * 将通用事件同步派发到本账号绑定的各协议（协议内自行 catch，避免一次失败阻断其它协议）
+     */
+    dispatch(commonEvent) {
+        this.logger.debug(`Dispatching event: ${commonEvent.type} to ${this.protocols.length} protocol(s)`);
         for (const protocol of this.protocols) {
+            this.logger.debug(`Dispatching to protocol: ${protocol.name}/${protocol.version}`);
             protocol.dispatch(commonEvent);
         }
     }

package/lib/adapter.d.ts

@@ -24,7 +24,18 @@ export declare abstract class Adapter<C = any, T extends keyof Adapter.Configs =
     get tableName(): string;
     protected constructor(app: I, platform: T);
     createId(id: string | number): CommonTypes.Id;
-    resolveId(id: string | number): CommonTypes.Id;
+    /**
+     * 将 string / number / 已是框架层的 Id 归一到当前适配器的 Id。
+     * - 已带有 string+number 的 Id：原样返回（避免被当成 string 键查错）。
+     * - string / number：查 id_map，无则 createId。
+     */
+    resolveId(id: string | number | CommonTypes.Id): CommonTypes.Id;
+    /**
+     * 将协议传入的 scene_id / user_id 归一为 CommonTypes.Id。
+     * - 事件侧经 createId 上报的 Id：直接可用，.string / .source 存平台原始标识。
+     * - Milky 等若传入 JSON 原始 string/number：需 resolveId 查表或建档，才能与 passiveReply 等场景用的 openid 一致。
+     */
+    protected coerceId(value: CommonTypes.Id | string | number): CommonTypes.Id;
     /**
      * 1. 发送消息
      * OneBot V11: send_private_msg, send_group_msg, send_msg
@@ -493,6 +504,15 @@ export declare abstract class Adapter<C = any, T extends keyof Adapter.Configs =
     };
     setOnline(uin: string): Promise<void>;
     setOffline(uin: string): Promise<void>;
+    /**
+     * Web 验证提交 - 可选实现。支持 Web 端完成登录验证的适配器实现此方法，
+     * 根据 type 将 data 转交给平台 Bot（如 submitSlider / submitSmsCode）。
+     */
+    submitVerification?(accountId: string, type: string, data: Record<string, unknown>): void | Promise<void>;
+    /**
+     * 请求发送短信验证码 - 可选实现。设备锁带手机号时，用户选择短信验证前需先调用此方法。
+     */
+    requestSmsCode?(accountId: string): void | Promise<void>;
     /**
      * 创建账号 - 必须由平台适配器实现
      */
@@ -508,6 +528,51 @@ export type AdapterClient<T extends Adapter = Adapter> = T extends Adapter<infer
 export declare namespace Adapter {
     interface Configs extends Record<string, any> {
     }
+    /**
+     * 验证请求的展示块（Web 按 type 通用渲染，适配器按需组合）
+     */
+    type VerificationBlock = {
+        type: 'image';
+        base64: string;
+        alt?: string;
+    } | {
+        type: 'link';
+        url: string;
+        label?: string;
+    } | {
+        type: 'text';
+        content: string;
+    } | {
+        type: 'input';
+        key: string;
+        placeholder?: string;
+        maxLength?: number;
+        secret?: boolean;
+    };
+    /**
+     * 验证请求的展示配置（全平台通用，由适配器提供）
+     */
+    interface VerificationRequestOptions {
+        blocks?: VerificationBlock[];
+    }
+    /**
+     * 统一登录验证请求（适配器 emit('verification:request', payload) 时使用）
+     * hint、options 由适配器提供，Web 仅做通用展示；onApprove/onReject 由前端绑定。
+     */
+    interface VerificationRequest {
+        platform: string;
+        account_id: string;
+        type: string;
+        /** 说明文案，由适配器提供，适用于全平台 */
+        hint: string;
+        /** 展示配置（链接、图片、输入框等），由适配器提供 */
+        options?: VerificationRequestOptions;
+        /** 为 true 时 Web 显示「发送验证码」按钮，需配合 requestSmsCode 使用 */
+        requestSmsAvailable?: boolean;
+        /** 扩展数据，可选 */
+        data?: Record<string, unknown>;
+        request_id?: string;
+    }
     interface SendMessageParams {
         scene_type: CommonTypes.Scene;
         scene_id: CommonTypes.Id;
@@ -552,6 +617,7 @@ export declare namespace Adapter {
         sender_name: string;
         scene_name: string;
     }
+    /** 单条消息详情（getMessage 等）；time 为 **Unix 秒**，与 OneBot 等协议常见约定一致 */
     interface MessageInfo {
         message_id: CommonTypes.Id;
         time: number;

package/lib/adapter.js

@@ -36,6 +36,9 @@ export class Adapter extends EventEmitter {
     // ID 管理方法
     // ============================================
     createId(id) {
+        if (id === undefined || id === null) {
+            throw new Error('createId: id 不能为 undefined 或 null');
+        }
         if (typeof id === "number")
             return { string: id.toString(), number: id, source: id };
         const [existData] = this.db.select('*').from(this.tableName).where({
@@ -57,13 +60,37 @@ export class Adapter extends EventEmitter {
         this.db.insert(this.tableName).values(newId).run();
         return newId;
     }
+    /**
+     * 将 string / number / 已是框架层的 Id 归一到当前适配器的 Id。
+     * - 已带有 string+number 的 Id：原样返回（避免被当成 string 键查错）。
+     * - string / number：查 id_map，无则 createId。
+     */
     resolveId(id) {
-        const [dbRecord] = this.db.select('*').from(this.tableName).where({
-            [typeof id === "number" ? "number" : "string"]: id
-        }).run();
+        if (typeof id === "object" &&
+            id !== null &&
+            typeof id.string === "string" &&
+            typeof id.number === "number") {
+            return id;
+        }
+        const primitive = id;
+        const [dbRecord] = this.db
+            .select("*")
+            .from(this.tableName)
+            .where({
+            [typeof primitive === "number" ? "number" : "string"]: primitive,
+        })
+            .run();
         if (dbRecord)
             return dbRecord;
-        return this.createId(id);
+        return this.createId(primitive);
+    }
+    /**
+     * 将协议传入的 scene_id / user_id 归一为 CommonTypes.Id。
+     * - 事件侧经 createId 上报的 Id：直接可用，.string / .source 存平台原始标识。
+     * - Milky 等若传入 JSON 原始 string/number：需 resolveId 查表或建档，才能与 passiveReply 等场景用的 openid 一致。
+     */
+    coerceId(value) {
+        return this.resolveId(value);
     }
     // ============================================
     // 消息相关方法 (Message - 7个)

package/lib/base-app.d.ts

@@ -6,12 +6,14 @@ import type { Logger } from "log4js";
 import { Server } from "http";
 import yaml from "js-yaml";
 declare const configure: typeof log4js.configure, connectLogger: typeof log4js.connectLogger;
-import { Router, WsServer } from "./router.js";
+import { Router } from "./router.js";
 import { LogLevel } from "./types.js";
 import { Adapter } from "./adapter.js";
 import { Protocol } from "./protocol.js";
 import { Account } from "./account.js";
 import { SqliteDB } from "./db.js";
+import { LifecycleManager } from "./lifecycle.js";
+import { Logger as EnhancedLogger } from "./logger.js";
 export { configure, yaml, connectLogger };
 export interface KoaOptions {
     env?: string;
@@ -26,12 +28,13 @@ export declare class BaseApp extends Koa {
     httpServer: Server;
     isStarted: boolean;
     logger: Logger;
+    enhancedLogger: EnhancedLogger;
+    lifecycle: LifecycleManager;
     static get configPath(): string;
     static get dataDir(): string;
     static get logFile(): string;
     db: SqliteDB;
     adapters: Map<keyof Adapter.Configs, Adapter>;
-    ws: WsServer;
     router: Router;
     get info(): {
         system_platform: NodeJS.Platform;
@@ -47,12 +50,28 @@ export declare class BaseApp extends Koa {
         process_cwd: string;
         process_use_memory: number;
         node_version: string;
-        sdk_version: any;
+        sdk_version: string;
         uptime: number;
     };
     constructor(config?: BaseApp.Config);
     init(): void;
     getLogger(patform: string): log4js.Logger;
+    /**
+     * 获取增强的 Logger 实例
+     */
+    getEnhancedLogger(name: string): EnhancedLogger;
+    /**
+     * 设置健康检查端点
+     */
+    private setupHealthEndpoints;
+    /**
+     * 解析 public_static_dir：相对路径基于配置文件目录（configDir），禁止相对路径穿越出 configDir；绝对路径按原样使用
+     */
+    private resolvePublicStaticDirectory;
+    /**
+     * 管理端 API：当前解析后的站点根静态目录（未配置或无效时为 null）
+     */
+    getPublicStaticRoot(): string | null;
     get adapterConfigs(): Map<string, Account.Config[]>;
     private initAdapters;
     addAccount<P extends keyof Adapter.Configs>(config: Account.Config<P>): void;
@@ -60,6 +79,10 @@ export declare class BaseApp extends Koa {
     removeAccount(p: string, uin: string, force?: boolean): void;
     get accounts(): Account<string | number, any>[];
     findOrCreateAdapter<P extends keyof Adapter.Configs>(platform: P): Adapter<any, string | number, BaseApp>;
+    /**
+     * 适配器首次创建后的钩子，子类可覆写以订阅该适配器事件（如 verification:request）
+     */
+    protected onAdapterCreated(_adapter: Adapter): void;
     start(): Promise<void>;
     reload(config: BaseApp.Config): Promise<void>;
     stop(): Promise<void>;
@@ -75,7 +98,11 @@ export declare namespace BaseApp {
         timeout?: number;
         username?: string;
         password?: string;
+        /** 管理端 Bearer 鉴权码，配置后可使用 Authorization: Bearer <access_token> 访问 API，无需用户名密码 */
+        access_token?: string;
         log_level?: LogLevel;
+        /** 站点根静态目录，相对配置文件所在目录（configDir）或绝对路径；用于企业微信等可信域名校验文件 */
+        public_static_dir?: string;
         general?: Protocol.Configs;
     } & KoaOptions & AdapterConfig;
     const defaultConfig: Config;