@zhin.js/core 1.0.0 → 1.0.1

package/src/errors.ts

@@ -0,0 +1,365 @@
+// ============================================================================
+// 错误处理系统
+// ============================================================================
+
+/**
+ * 基础错误类，所有自定义错误都应该继承此类
+ */
+export class ZhinError extends Error {
+    public readonly code: string
+    public readonly timestamp: Date
+    public readonly context?: Record<string, any>
+
+    constructor(message: string, code: string = 'ZHIN_ERROR', context?: Record<string, any>) {
+        super(message)
+        this.name = this.constructor.name
+        this.code = code
+        this.timestamp = new Date()
+        this.context = context
+        
+        // 确保错误堆栈正确显示
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor)
+        }
+    }
+
+    /**
+     * 转换为JSON格式
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            timestamp: this.timestamp.toISOString(),
+            context: this.context,
+            stack: this.stack
+        }
+    }
+
+    /**
+     * 转换为用户友好的格式
+     */
+    toUserString(): string {
+        return `[${this.code}] ${this.message}`
+    }
+}
+
+/**
+ * 配置相关错误
+ */
+export class ConfigError extends ZhinError {
+    constructor(message: string, context?: Record<string, any>) {
+        super(message, 'CONFIG_ERROR', context)
+    }
+}
+
+/**
+ * 插件相关错误
+ */
+export class PluginError extends ZhinError {
+    public readonly pluginName: string
+
+    constructor(message: string, pluginName: string, context?: Record<string, any>) {
+        super(message, 'PLUGIN_ERROR', { ...context, pluginName })
+        this.pluginName = pluginName
+    }
+}
+
+/**
+ * 适配器相关错误
+ */
+export class AdapterError extends ZhinError {
+    public readonly adapterName: string
+    public readonly botName?: string
+
+    constructor(message: string, adapterName: string, botName?: string, context?: Record<string, any>) {
+        super(message, 'ADAPTER_ERROR', { ...context, adapterName, botName })
+        this.adapterName = adapterName
+        this.botName = botName
+    }
+}
+
+/**
+ * 连接相关错误
+ */
+export class ConnectionError extends ZhinError {
+    public readonly retryable: boolean
+
+    constructor(message: string, retryable: boolean = true, context?: Record<string, any>) {
+        super(message, 'CONNECTION_ERROR', { ...context, retryable })
+        this.retryable = retryable
+    }
+}
+
+/**
+ * 消息处理错误
+ */
+export class MessageError extends ZhinError {
+    public readonly messageId?: string
+    public readonly channelId?: string
+
+    constructor(message: string, messageId?: string, channelId?: string, context?: Record<string, any>) {
+        super(message, 'MESSAGE_ERROR', { ...context, messageId, channelId })
+        this.messageId = messageId
+        this.channelId = channelId
+    }
+}
+
+/**
+ * 上下文相关错误
+ */
+export class ContextError extends ZhinError {
+    public readonly contextName: string
+
+    constructor(message: string, contextName: string, context?: Record<string, any>) {
+        super(message, 'CONTEXT_ERROR', { ...context, contextName })
+        this.contextName = contextName
+    }
+}
+
+/**
+ * 验证错误
+ */
+export class ValidationError extends ZhinError {
+    public readonly field?: string
+    public readonly value?: any
+
+    constructor(message: string, field?: string, value?: any, context?: Record<string, any>) {
+        super(message, 'VALIDATION_ERROR', { ...context, field, value })
+        this.field = field
+        this.value = value
+    }
+}
+
+/**
+ * 权限错误
+ */
+export class PermissionError extends ZhinError {
+    public readonly userId?: string
+    public readonly requiredPermission?: string
+
+    constructor(message: string, userId?: string, requiredPermission?: string, context?: Record<string, any>) {
+        super(message, 'PERMISSION_ERROR', { ...context, userId, requiredPermission })
+        this.userId = userId
+        this.requiredPermission = requiredPermission
+    }
+}
+
+/**
+ * 超时错误
+ */
+export class TimeoutError extends ZhinError {
+    public readonly timeoutMs: number
+
+    constructor(message: string, timeoutMs: number, context?: Record<string, any>) {
+        super(message, 'TIMEOUT_ERROR', { ...context, timeoutMs })
+        this.timeoutMs = timeoutMs
+    }
+}
+
+/**
+ * 错误处理器接口
+ */
+export interface ErrorHandler {
+    (error: Error, context?: Record<string, any>): void | Promise<void>
+}
+
+/**
+ * 错误管理器
+ */
+export class ErrorManager {
+    private handlers: Map<string, ErrorHandler[]> = new Map()
+    private globalHandlers: ErrorHandler[] = []
+
+    /**
+     * 注册错误处理器
+     */
+    register(errorType: string, handler: ErrorHandler): void {
+        if (!this.handlers.has(errorType)) {
+            this.handlers.set(errorType, [])
+        }
+        this.handlers.get(errorType)!.push(handler)
+    }
+
+    /**
+     * 注册全局错误处理器
+     */
+    registerGlobal(handler: ErrorHandler): void {
+        this.globalHandlers.push(handler)
+    }
+
+    /**
+     * 处理错误
+     */
+    async handle(error: Error, context?: Record<string, any>): Promise<void> {
+        // 首先调用全局处理器
+        for (const handler of this.globalHandlers) {
+            try {
+                await handler(error, context)
+            } catch (handlerError) {
+                // console.error 已替换为注释
+            }
+        }
+
+        // 然后调用特定类型的处理器
+        const errorType = error.constructor.name
+        const handlers = this.handlers.get(errorType) || []
+        
+        for (const handler of handlers) {
+            try {
+                await handler(error, context)
+            } catch (handlerError) {
+                // console.error 已替换为注释
+            }
+        }
+    }
+
+    /**
+     * 移除错误处理器
+     */
+    unregister(errorType: string, handler: ErrorHandler): boolean {
+        const handlers = this.handlers.get(errorType)
+        if (handlers) {
+            const index = handlers.indexOf(handler)
+            if (index !== -1) {
+                handlers.splice(index, 1)
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * 清理所有处理器
+     */
+    clear(): void {
+        this.handlers.clear()
+        this.globalHandlers.length = 0
+    }
+}
+
+/**
+ * 错误重试工具
+ */
+export class RetryManager {
+    /**
+     * 执行重试逻辑
+     */
+    static async retry<T>(
+        fn: () => Promise<T>,
+        options: {
+            maxRetries?: number
+            delay?: number
+            exponentialBackoff?: boolean
+            retryCondition?: (error: Error) => boolean
+        } = {}
+    ): Promise<T> {
+        const {
+            maxRetries = 3,
+            delay = 1000,
+            exponentialBackoff = true,
+            retryCondition = () => true
+        } = options
+
+        let lastError: Error
+        
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn()
+            } catch (error) {
+                lastError = error as Error
+                
+                // 如果是最后一次尝试或不满足重试条件，直接抛出错误
+                if (attempt === maxRetries || !retryCondition(lastError)) {
+                    throw lastError
+                }
+                
+                // 计算延迟时间
+                const currentDelay = exponentialBackoff 
+                    ? delay * Math.pow(2, attempt)
+                    : delay
+                
+                // 等待后重试
+                await new Promise(resolve => setTimeout(resolve, currentDelay))
+            }
+        }
+        
+        throw lastError!
+    }
+}
+
+/**
+ * 断路器模式实现
+ */
+export class CircuitBreaker {
+    private failures: number = 0
+    private lastFailureTime: number = 0
+    private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED'
+
+    constructor(
+        private failureThreshold: number = 5,
+        private timeoutMs: number = 60000,
+        private monitoringPeriodMs: number = 10000
+    ) {}
+
+    /**
+     * 执行受保护的操作
+     */
+    async execute<T>(fn: () => Promise<T>): Promise<T> {
+        if (this.state === 'OPEN') {
+            if (Date.now() - this.lastFailureTime > this.timeoutMs) {
+                this.state = 'HALF_OPEN'
+            } else {
+                throw new Error('Circuit breaker is OPEN')
+            }
+        }
+
+        try {
+            const result = await fn()
+            this.onSuccess()
+            return result
+        } catch (error) {
+            this.onFailure()
+            throw error
+        }
+    }
+
+    private onSuccess(): void {
+        this.failures = 0
+        this.state = 'CLOSED'
+    }
+
+    private onFailure(): void {
+        this.failures++
+        this.lastFailureTime = Date.now()
+        
+        if (this.failures >= this.failureThreshold) {
+            this.state = 'OPEN'
+        }
+    }
+
+    /**
+     * 获取断路器状态
+     */
+    getState(): 'CLOSED' | 'OPEN' | 'HALF_OPEN' {
+        return this.state
+    }
+
+    /**
+     * 重置断路器
+     */
+    reset(): void {
+        this.failures = 0
+        this.lastFailureTime = 0
+        this.state = 'CLOSED'
+    }
+}
+
+// 默认错误管理器实例
+export const errorManager = new ErrorManager()
+
+// 默认错误处理器
+errorManager.registerGlobal((error, context) => {
+    // Default error handler - logs to console
+})

package/src/index.ts

@@ -1,14 +1,17 @@
-// ============================================================================
-// Zhin Bot Framework - HMR Edition
-// ============================================================================
-
-// 核心系统
-export type { Bot } from './bot.js';
-export { loadConfig, saveConfig, createDefaultConfig } from './config.js';
-export * from './types.js';
-export * from './config.js';
+// Core exports
+export * from './app.js'
+export * from './bot.js'
+export * from './plugin.js'
+export * from './command.js'
+export * from './component.js'
 export * from './adapter.js'
-export * from './plugin.js';
-// HMR Bot系统 (主要API)
-export * from './app.js';
-export * from '@zhin.js/hmr';
+export * from './config.js'
+export * from './message.js'
+// Logger moved to @zhin.js/logger package
+export * from './types.js'
+export * from './utils.js'
+export * from './errors.js'  // 导出错误处理系统
+export * from './cron.js'
+export * from '@zhin.js/database'
+
+export { Dependency } from '@zhin.js/hmr'

package/src/message.ts

@@ -0,0 +1,44 @@
+import {MaybePromise} from "@zhin.js/types";
+import {MessageSegment, MessageSender, RegisteredAdapter, SendContent} from "./types";
+
+/**
+ * 消息组件类型：用于自定义消息结构
+ */
+export type MessageComponent<T extends object>=(props:T&{children:SendContent})=>MaybePromise<SendContent>
+/**
+ * 消息频道信息
+ */
+export interface MessageChannel{
+    id: string;
+    type: MessageType;
+}
+/**
+ * 消息类型枚举
+ */
+export type MessageType = 'group' | 'private' | 'channel'
+/**
+ * 消息基础结构
+ */
+export interface MessageBase {
+    $id: string;
+    $adapter:string
+    $bot:string
+    $content: MessageSegment[];
+    $sender: MessageSender;
+    $reply(content:SendContent,quote?:boolean|string):Promise<void>
+    $channel: MessageChannel;
+    $timestamp: number;
+    $raw: string;
+}
+/**
+ * 完整消息类型，支持扩展
+ */
+export type Message<T extends object={}>=MessageBase&T;
+export namespace Message{
+    /**
+     * 工具方法：合并自定义字段与基础消息结构
+     */
+    export function from<T extends object>(input:T,format:MessageBase):Message<T>{
+        return Object.assign(input,format)
+    }
+}

package/src/plugin.ts

@@ -1,52 +1,123 @@
 // ============================================================================
-// 插件类型定义
+// 插件类型定义（定义插件中间件、生命周期、命令、组件等核心类型）
 // ============================================================================
 
 
 import {MaybePromise} from '@zhin.js/types'
-import { Message, BeforeSendHandler, SendOptions} from "./types";
+import {AdapterMessage, BeforeSendHandler, RegisteredAdapter, SendOptions} from "./types.js";
+import {Message} from './message.js'
 import {Dependency, Logger,} from "@zhin.js/hmr";
 import {App} from "./app";
+import {MessageCommand} from "./command.js";
+import {Component} from "./component.js";
+import { PluginError, MessageError, errorManager } from './errors.js';
+import {remove} from "./utils.js";
+import {Prompt} from "./prompt.js";
+import { Schema } from '@zhin.js/database';
+import { Cron} from './cron.js';
 
 /** 消息中间件函数 */
-export type MessageMiddleware = (message: Message, next: () => Promise<void>) => MaybePromise<void>;
-
-/** 事件监听器函数 */
-export type EventListener<T = any> = (data: T) => void | Promise<void>;
-
-/** 定时任务配置 */
-export interface CronJob {
-    name: string;
-    schedule: string; // cron 表达式
-    handler: () => void | Promise<void>;
-    enabled?: boolean;
-}
+export type MessageMiddleware<P extends RegisteredAdapter=RegisteredAdapter> = (message: Message<AdapterMessage<P>>, next: () => Promise<void>) => MaybePromise<void>;
 
 
 // ============================================================================
-// Plugin 类
+// Plugin 类（插件的生命周期、命令/中间件/组件/定时任务等管理）
 // ============================================================================
 
 /**
- * 插件类：继承自Dependency，提供机器人特定功能
+ * 插件类：继承自 Dependency，提供机器人特定功能与生命周期管理。
+ * 支持命令注册、中间件、组件、定时任务、模型等。
  */
 export class Plugin extends Dependency<Plugin> {
-    middlewares: MessageMiddleware[] = [];
-    eventListeners = new Map<string, EventListener[]>();
-    cronJobs = new Map<string, CronJob>();
-
+    middlewares: MessageMiddleware<any>[] = [];
+    components: Map<string, Component<any, any, any>> = new Map();
+    schemas: Map<string,Schema<any>>=new Map();
+    commands:MessageCommand[]=[];
+    crons:Cron[]=[];
     #logger?:Logger
+    /**
+     * 构造函数：初始化插件，注册消息事件、命令中间件、资源清理等
+     * @param parent 所属 App 实例
+     * @param name 插件名
+     * @param filePath 插件文件路径
+     */
     constructor(parent: Dependency<Plugin>, name: string, filePath: string) {
         super(parent, name, filePath);
+        // 绑定消息事件，自动分发到命令和中间件
         this.on('message.receive',this.#handleMessage.bind(this))
+        // 注册命令处理为默认中间件
+        this.addMiddleware(async (message,next)=>{
+            for(const command of this.commands){
+                const result=await command.handle(message);
+                if(result) message.$reply(result);
+            }
+            return next()
+        });
+        // 发送前渲染组件
+        this.beforeSend((options)=>Component.render(this.components,options))
+        // 资源清理：卸载时清空模型、定时任务等
+        this.on('dispose',()=>{
+            for(const name of this.schemas.keys()){
+                this.app.database?.models.delete(name);
+            }
+            this.schemas.clear();
+            for(const cron of this.crons){
+                cron.dispose();
+            }
+            this.crons.length = 0;
+        });
+        // 挂载时启动定时任务
+        this.on('mounted',()=>{
+            for(const cron of this.crons){
+                cron.run();
+            }
+        });
     }
-    #handleMessage(message:Message){
-        const next=async (index:number)=>{
-            if(!this.middlewares[index]) return
-            const middleware=this.middlewares[index]
-            middleware(message,()=>next(index+1))
+    async #handleMessage(message: Message) {
+        try {
+            await this.#runMiddlewares(message, 0)
+        } catch (error) {
+            const messageError = new MessageError(
+                `消息处理失败: ${(error as Error).message}`,
+                message.$id,
+                message.$channel.id,
+                { pluginName: this.name, originalError: error }
+            )
+            
+            await errorManager.handle(messageError)
+            
+            // 可选：发送错误回复给用户
+            try {
+                await message.$reply('抱歉，处理您的消息时出现了错误。')
+            } catch (replyError) {
+                // 静默处理回复错误，避免错误循环
+                // console.error 已替换为注释
+            }
+        }
+    }
+    cron(cronExpression:string,callback:()=>void){
+        const cronJob = new Cron(cronExpression,callback);
+        this.crons.push(cronJob);
+        return this;
+    }
+    async #runMiddlewares(message: Message, index: number): Promise<void> {
+        if (index >= this.middlewares.length) return
+        
+        const middleware = this.middlewares[index]
+        
+        try {
+            await middleware(message, () => this.#runMiddlewares(message, index + 1))
+        } catch (error) {
+            throw new PluginError(
+                `中间件执行失败: ${(error as Error).message}`,
+                this.name,
+                { middlewareIndex: index, originalError: error }
+            )
         }
-        next(0)
+    }
+    defineModel<S extends Record<string,any>>(name:string,schema:Schema<S>){
+        this.schemas.set(name,schema);
+        return this;
     }
     beforeSend(handler:BeforeSendHandler){
         this.before('message.send',handler)
@@ -60,63 +131,74 @@ export class Plugin extends Dependency<Plugin> {
     }
     get logger(): Logger {
         if(this.#logger) return this.#logger
-        const names = [this.name];
+        const names = [];
         let temp=this as Dependency<Plugin>
         while(temp.parent){
-            names.unshift(temp.parent.name)
+            names.unshift(temp.name)
             temp=temp.parent
         }
-        return this.#logger=this.app.getLogger(...names)
+        return temp.getLogger(names.join('/'))
+    }
+    /** 添加组件 */
+    addComponent<T = {}, D = {}, P = Component.Props<T>>(component:Component<T,D,P>){
+        this.components.set(component.name,component);
     }
-
     /** 添加中间件 */
-    addMiddleware(middleware: MessageMiddleware): void {
+    addCommand(command:MessageCommand){
+        this.commands.push(command);
+        this.dispatch('command.add',command);
+    }
+    /** 添加中间件 */
+    addMiddleware<T extends RegisteredAdapter>(middleware: MessageMiddleware<T>) {
         this.middlewares.push(middleware);
         this.dispatch('middleware.add',middleware)
-    }
-
-    /** 添加事件监听器 */
-    addEventListener<T = any>(event: string, listener: EventListener<T>): void {
-        if (!this.eventListeners.has(event)) {
-            this.eventListeners.set(event, []);
+        return ()=>{
+            remove(this.middlewares,middleware)
         }
-        this.eventListeners.get(event)!.push(listener);
-        this.dispatch('listener.add',event,listener)
     }
-
-    /** 添加定时任务 */
-    addCronJob(job: CronJob): void {
-        this.cronJobs.set(job.name, job);
-        this.dispatch('cron-job.add',job)
+    prompt<P extends RegisteredAdapter>(message:Message<AdapterMessage<P>>){
+        return new Prompt<P>(this,message)
     }
+
+
+
     /** 发送消息 */
-    async sendMessage(options:SendOptions): Promise<void> {
-        await this.app.sendMessage(options);
+    async sendMessage(options: SendOptions): Promise<void> {
+        try {
+            await this.app.sendMessage(options);
+        } catch (error) {
+            const messageError = new MessageError(
+                `发送消息失败: ${(error as Error).message}`,
+                undefined,
+                (options as any).channel_id,
+                { pluginName: this.name, sendOptions: options, originalError: error }
+            )
+            
+            await errorManager.handle(messageError)
+            throw messageError
+        }
     }
 
     /** 销毁插件 */
     dispose(): void {
-        // 移除所有中间件
-        for (const middleware of this.middlewares) {
-            this.dispatch('middleware.remove', middleware)
-        }
-        this.middlewares = []
-
-        // 移除所有事件监听器
-        for (const [event, listeners] of this.eventListeners) {
-            for (const listener of listeners) {
-                this.dispatch('listener.remove', event, listener)
+        try {
+            // 移除所有中间件
+            for (const middleware of this.middlewares) {
+                this.dispatch('middleware.remove', middleware)
             }
+            this.middlewares = []
+            
+            // 调用父类的dispose方法
+            super.dispose()
+        } catch (error) {
+            const pluginError = new PluginError(
+                `插件销毁失败: ${(error as Error).message}`,
+                this.name,
+                { originalError: error }
+            )
+            
+            errorManager.handle(pluginError).catch(console.error)
+            throw pluginError
         }
-        this.eventListeners.clear()
-
-        // 移除所有定时任务
-        for (const [name, job] of this.cronJobs) {
-            this.dispatch('cron-job.remove', job)
-        }
-        this.cronJobs.clear()
-
-        // 调用父类的dispose方法
-        super.dispose()
     }
 }