@onebots/core 0.5.0 → 1.0.0

package/lib/logger.js

@@ -0,0 +1,156 @@
+/**
+ * 增强的日志系统
+ * 提供结构化日志、错误追踪和上下文信息
+ */
+import log4js from 'log4js';
+import { ErrorHandler } from './errors.js';
+const { getLogger } = log4js;
+/**
+ * 增强的 Logger 类
+ */
+export class Logger {
+    logger;
+    context = {};
+    constructor(name, level) {
+        this.logger = getLogger(name);
+        if (level) {
+            this.logger.level = level;
+        }
+    }
+    /**
+     * 设置日志级别
+     */
+    setLevel(level) {
+        this.logger.level = level;
+    }
+    /**
+     * 添加上下文信息
+     */
+    withContext(context) {
+        const newLogger = new Logger(this.logger.category, this.logger.level);
+        newLogger.context = { ...this.context, ...context };
+        return newLogger;
+    }
+    /**
+     * Trace 级别日志
+     */
+    trace(message, context) {
+        this.log('trace', message, context);
+    }
+    /**
+     * Debug 级别日志
+     */
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    /**
+     * Info 级别日志
+     */
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    /**
+     * Warn 级别日志
+     */
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    /**
+     * Error 级别日志
+     */
+    error(message, context) {
+        if (typeof message === 'object' && message !== null) {
+            if (message instanceof Error || message.category !== undefined) {
+                const error = ErrorHandler.wrap(message, context);
+                this.log('error', error.message, {
+                    ...context,
+                    error: error.toJSON(),
+                });
+                return;
+            }
+        }
+        this.log('error', message, context);
+    }
+    /**
+     * Fatal 级别日志
+     */
+    fatal(message, context) {
+        if (typeof message === 'object' && message !== null) {
+            if (message instanceof Error || message.category !== undefined) {
+                const error = ErrorHandler.wrap(message, context);
+                this.log('fatal', error.message, {
+                    ...context,
+                    error: error.toJSON(),
+                });
+                return;
+            }
+        }
+        this.log('fatal', message, context);
+    }
+    /**
+     * Mark 级别日志
+     */
+    mark(message, context) {
+        this.log('mark', message, context);
+    }
+    /**
+     * 记录性能指标
+     */
+    performance(operation, duration, context) {
+        this.info(`Performance: ${operation} took ${duration}ms`, {
+            ...context,
+            operation,
+            duration,
+            type: 'performance',
+        });
+    }
+    /**
+     * 记录操作开始
+     */
+    start(operation, context) {
+        const startTime = Date.now();
+        this.debug(`Starting: ${operation}`, context);
+        return () => {
+            const duration = Date.now() - startTime;
+            this.performance(operation, duration, context);
+        };
+    }
+    /**
+     * 内部日志方法
+     */
+    log(level, message, context) {
+        const mergedContext = { ...this.context, ...context };
+        const logMessage = mergedContext && Object.keys(mergedContext).length > 0
+            ? `${message} ${JSON.stringify(mergedContext)}`
+            : message;
+        switch (level) {
+            case 'trace':
+                this.logger.trace(logMessage);
+                break;
+            case 'debug':
+                this.logger.debug(logMessage);
+                break;
+            case 'info':
+                this.logger.info(logMessage);
+                break;
+            case 'warn':
+                this.logger.warn(logMessage);
+                break;
+            case 'error':
+                this.logger.error(logMessage);
+                break;
+            case 'fatal':
+                this.logger.fatal(logMessage);
+                break;
+            case 'mark':
+                this.logger.mark(logMessage);
+                break;
+        }
+    }
+}
+/**
+ * 创建 Logger 实例
+ */
+export function createLogger(name, level) {
+    return new Logger(name, level);
+}

package/lib/protocol.d.ts

@@ -3,7 +3,6 @@ import { Account } from "./account.js";
 import { Adapter } from "./adapter.js";
 import { Dict } from "./types.js";
 import { Router } from "./router.js";
-import { BaseApp } from "./base-app.js";
 /**
  * Base Protocol class
  * Represents a communication protocol (e.g., OneBot, Milky, Satori)
@@ -14,7 +13,7 @@ export declare abstract class Protocol<V extends string = string, C = any> exten
     config: Protocol.FullConfig<C>;
     abstract readonly name: string;
     abstract readonly version: V;
-    get app(): BaseApp;
+    get app(): import("./base-app.js").BaseApp;
     get router(): Router;
     get logger(): import("log4js").Logger;
     constructor(adapter: Adapter, account: Account, config: Protocol.FullConfig<C>);
@@ -95,6 +94,6 @@ export declare namespace Protocol {
      */
     export type Factory<T extends Protocol = Protocol> = Creator<T> | Construct<T>;
     export function isClassFactory<T extends Protocol = Protocol>(factory: Factory<T>): factory is Construct<T>;
-    export function createFilter(filters: Filters): (event: Dict) => any;
+    export function createFilter(filters?: Filters): any;
     export {};
 }

package/lib/protocol.js

@@ -41,6 +41,10 @@ export class Protocol extends EventEmitter {
     }
     Protocol.isClassFactory = isClassFactory;
     function createFilter(filters) {
+        // 如果没有 filters，返回始终为 true 的过滤器
+        if (!filters || Object.keys(filters).length === 0) {
+            return () => true;
+        }
         const isLogicKey = (key) => {
             return [
                 "$and",

package/lib/rate-limiter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * API 速率限制器
+ * 防止触发平台的速率限制
+ */
+export interface RateLimiterOptions {
+    /** 时间窗口内允许的最大请求数 */
+    maxRequests: number;
+    /** 时间窗口大小（毫秒） */
+    windowMs: number;
+    /** 请求之间的最小间隔（毫秒） */
+    minInterval?: number;
+    /** 超出限制时是否排队等待 */
+    queueExcess?: boolean;
+    /** 队列最大长度 */
+    maxQueueSize?: number;
+}
+/**
+ * 令牌桶速率限制器
+ */
+export declare class RateLimiter {
+    private tokens;
+    private lastRefill;
+    private queue;
+    private processing;
+    private lastRequest;
+    private readonly maxRequests;
+    private readonly windowMs;
+    private readonly minInterval;
+    private readonly queueExcess;
+    private readonly maxQueueSize;
+    constructor(options: RateLimiterOptions);
+    /**
+     * 补充令牌
+     */
+    private refillTokens;
+    /**
+     * 尝试获取令牌
+     */
+    private tryAcquire;
+    /**
+     * 计算需要等待的时间
+     */
+    private getWaitTime;
+    /**
+     * 执行受限函数
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 处理队列
+     */
+    private processQueue;
+    /**
+     * 获取当前状态
+     */
+    getStatus(): {
+        availableTokens: number;
+        queueLength: number;
+        isProcessing: boolean;
+    };
+    /**
+     * 清空队列
+     */
+    clearQueue(): void;
+    private sleep;
+}
+/**
+ * 速率限制错误
+ */
+export declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+/**
+ * 平台速率限制预设
+ */
+export declare const RateLimitPresets: {
+    /** Discord - 50 请求/秒 */
+    discord: RateLimiterOptions;
+    /** Telegram - 30 消息/秒（群组 20/分钟） */
+    telegram: RateLimiterOptions;
+    /** QQ - 5 消息/秒 */
+    qq: RateLimiterOptions;
+    /** 通用 - 10 请求/秒 */
+    default: RateLimiterOptions;
+};
+/**
+ * 创建带速率限制的函数包装器
+ */
+export declare function withRateLimit<T extends (...args: any[]) => Promise<any>>(fn: T, limiter: RateLimiter): T;

package/lib/rate-limiter.js

@@ -0,0 +1,196 @@
+/**
+ * API 速率限制器
+ * 防止触发平台的速率限制
+ */
+/**
+ * 令牌桶速率限制器
+ */
+export class RateLimiter {
+    tokens;
+    lastRefill;
+    queue = [];
+    processing = false;
+    lastRequest = 0;
+    maxRequests;
+    windowMs;
+    minInterval;
+    queueExcess;
+    maxQueueSize;
+    constructor(options) {
+        this.maxRequests = options.maxRequests;
+        this.windowMs = options.windowMs;
+        this.minInterval = options.minInterval ?? 0;
+        this.queueExcess = options.queueExcess ?? true;
+        this.maxQueueSize = options.maxQueueSize ?? 100;
+        this.tokens = this.maxRequests;
+        this.lastRefill = Date.now();
+    }
+    /**
+     * 补充令牌
+     */
+    refillTokens() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        const tokensToAdd = (elapsed / this.windowMs) * this.maxRequests;
+        this.tokens = Math.min(this.maxRequests, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+    }
+    /**
+     * 尝试获取令牌
+     */
+    tryAcquire() {
+        this.refillTokens();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 计算需要等待的时间
+     */
+    getWaitTime() {
+        this.refillTokens();
+        if (this.tokens >= 1) {
+            return 0;
+        }
+        // 计算获得一个令牌需要的时间
+        const tokensNeeded = 1 - this.tokens;
+        return (tokensNeeded / this.maxRequests) * this.windowMs;
+    }
+    /**
+     * 执行受限函数
+     */
+    async execute(fn) {
+        // 检查最小间隔
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequest;
+        if (timeSinceLastRequest < this.minInterval) {
+            await this.sleep(this.minInterval - timeSinceLastRequest);
+        }
+        // 尝试获取令牌
+        if (this.tryAcquire()) {
+            this.lastRequest = Date.now();
+            return fn();
+        }
+        // 如果不排队，直接抛出错误
+        if (!this.queueExcess) {
+            throw new RateLimitError('Rate limit exceeded');
+        }
+        // 检查队列大小
+        if (this.queue.length >= this.maxQueueSize) {
+            throw new RateLimitError('Rate limit queue is full');
+        }
+        // 加入队列
+        return new Promise((resolve, reject) => {
+            this.queue.push({ execute: fn, resolve, reject });
+            this.processQueue();
+        });
+    }
+    /**
+     * 处理队列
+     */
+    async processQueue() {
+        if (this.processing || this.queue.length === 0) {
+            return;
+        }
+        this.processing = true;
+        while (this.queue.length > 0) {
+            const waitTime = this.getWaitTime();
+            if (waitTime > 0) {
+                await this.sleep(waitTime);
+            }
+            // 检查最小间隔
+            const timeSinceLastRequest = Date.now() - this.lastRequest;
+            if (timeSinceLastRequest < this.minInterval) {
+                await this.sleep(this.minInterval - timeSinceLastRequest);
+            }
+            if (this.tryAcquire()) {
+                const request = this.queue.shift();
+                if (request) {
+                    this.lastRequest = Date.now();
+                    try {
+                        const result = await request.execute();
+                        request.resolve(result);
+                    }
+                    catch (error) {
+                        request.reject(error instanceof Error ? error : new Error(String(error)));
+                    }
+                }
+            }
+        }
+        this.processing = false;
+    }
+    /**
+     * 获取当前状态
+     */
+    getStatus() {
+        this.refillTokens();
+        return {
+            availableTokens: Math.floor(this.tokens),
+            queueLength: this.queue.length,
+            isProcessing: this.processing,
+        };
+    }
+    /**
+     * 清空队列
+     */
+    clearQueue() {
+        const error = new RateLimitError('Queue cleared');
+        this.queue.forEach(request => request.reject(error));
+        this.queue = [];
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+/**
+ * 速率限制错误
+ */
+export class RateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RateLimitError';
+    }
+}
+/**
+ * 平台速率限制预设
+ */
+export const RateLimitPresets = {
+    /** Discord - 50 请求/秒 */
+    discord: {
+        maxRequests: 50,
+        windowMs: 1000,
+        minInterval: 50,
+        queueExcess: true,
+    },
+    /** Telegram - 30 消息/秒（群组 20/分钟） */
+    telegram: {
+        maxRequests: 30,
+        windowMs: 1000,
+        minInterval: 50,
+        queueExcess: true,
+    },
+    /** QQ - 5 消息/秒 */
+    qq: {
+        maxRequests: 5,
+        windowMs: 1000,
+        minInterval: 200,
+        queueExcess: true,
+    },
+    /** 通用 - 10 请求/秒 */
+    default: {
+        maxRequests: 10,
+        windowMs: 1000,
+        minInterval: 100,
+        queueExcess: true,
+    },
+};
+/**
+ * 创建带速率限制的函数包装器
+ */
+export function withRateLimit(fn, limiter) {
+    return ((...args) => {
+        return limiter.execute(() => fn(...args));
+    });
+}

package/lib/registry.js

@@ -83,11 +83,6 @@ export class ProtocolRegistry {
      */
     static create(name, version, adapter, account, config) {
         const factory = this.get(name, version);
-        console.log({
-            name,
-            version,
-            account: account.account_id
-        });
         if (!factory) {
             throw new Error(`Protocol ${name}/${version} not registered`);
         }

package/lib/retry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 重试策略和网络请求重试机制
+ * 提供统一的重试逻辑，支持指数退避
+ */
+export interface RetryOptions {
+    /** 最大重试次数 */
+    maxRetries?: number;
+    /** 初始延迟时间（毫秒） */
+    initialDelay?: number;
+    /** 最大延迟时间（毫秒） */
+    maxDelay?: number;
+    /** 退避倍数 */
+    backoffMultiplier?: number;
+    /** 是否添加随机抖动 */
+    jitter?: boolean;
+    /** 判断是否应该重试的函数 */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    /** 重试前的回调 */
+    onRetry?: (error: Error, attempt: number, delay: number) => void;
+}
+/**
+ * 带重试的异步函数执行器
+ *
+ * @example
+ * ```typescript
+ * const result = await retry(
+ *     () => fetch('https://api.example.com/data'),
+ *     { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * 创建一个带重试功能的函数包装器
+ *
+ * @example
+ * ```typescript
+ * const fetchWithRetry = withRetry(fetch, { maxRetries: 3 });
+ * const response = await fetchWithRetry('https://api.example.com/data');
+ * ```
+ */
+export declare function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+/**
+ * 重试策略预设
+ */
+export declare const RetryPresets: {
+    /** 快速重试：3次，1秒起始 */
+    fast: RetryOptions;
+    /** 标准重试：5次，2秒起始 */
+    standard: RetryOptions;
+    /** 持久重试：10次，5秒起始 */
+    persistent: RetryOptions;
+    /** WebSocket 重连：无限重试 */
+    websocket: RetryOptions;
+};
+/**
+ * 连接管理器 - 用于 WebSocket 等长连接的重连管理
+ */
+export declare class ConnectionManager {
+    private connect;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private isConnecting;
+    private options;
+    constructor(connect: () => Promise<void>, options?: RetryOptions);
+    /**
+     * 开始连接
+     */
+    start(): Promise<void>;
+    /**
+     * 停止连接和重连
+     */
+    stop(): void;
+    /**
+     * 触发重连
+     */
+    scheduleReconnect(error?: Error): void;
+    /**
+     * 重置重连计数（连接成功时调用）
+     */
+    resetAttempts(): void;
+    /**
+     * 获取当前重连次数
+     */
+    getAttempts(): number;
+    private tryConnect;
+}