@zhin.js/core 1.0.39 → 1.0.41

package/src/built/common-adapter-tools.ts

@@ -59,55 +59,55 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
   {
     method: 'kickMember',
     toolSuffix: 'kick_member',
-    description: '将成员踢出群/服务器',
+    description: '将成员踢出群/服务器。适用于严重违规、广告号等需要移除的场景。踢出后该成员将无法再进入群聊（部分平台可重新邀请）。如果只需要用户名而没有 user_id，请先调用 list_members 查询',
     keywords: ['踢', 'kick', '移除', '踢出'],
     permissionLevel: 'group_admin',
     extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID' },
+      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
     },
     extraRequired: ['user_id'],
   },
   {
     method: 'muteMember',
     toolSuffix: 'mute_member',
-    description: '禁言群成员（duration=0 解除）',
-    keywords: ['禁言', 'mute', '静音', '解除禁言'],
+    description: '禁言或解除禁言群成员。适用于违规发言、刷屏、骚扰他人等需要临时限制发言的场景。duration 单位为秒，传 0 表示解除禁言。默认禁言 10 分钟(600秒)。如果只有昵称而没有 user_id，请先调用 list_members 查询',
+    keywords: ['禁言', 'mute', '静音', '解除禁言', '解禁', '闭嘴'],
     permissionLevel: 'group_admin',
     extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID' },
-      duration: { type: 'number', description: '禁言时长(秒)，0=解除', default: 600 },
+      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
+      duration: { type: 'number', description: '禁言时长(秒)，0=解除禁言，默认600(10分钟)。常用值：60=1分钟, 600=10分钟, 3600=1小时, 86400=1天', default: 600 },
     },
     extraRequired: ['user_id'],
   },
   {
     method: 'setMemberNickname',
     toolSuffix: 'set_nickname',
-    description: '设置群成员昵称/名片',
-    keywords: ['昵称', '名片', 'nickname', 'card'],
+    description: '设置群成员的群昵称/名片。仅修改群内显示名称，不影响用户的全局昵称。如果只有昵称而没有 user_id，请先调用 list_members 查询',
+    keywords: ['昵称', '名片', 'nickname', 'card', '改名片'],
     permissionLevel: 'group_admin',
     extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID' },
-      nickname: { type: 'string', description: '新昵称' },
+      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
+      nickname: { type: 'string', description: '新的群昵称/名片' },
     },
     extraRequired: ['user_id', 'nickname'],
   },
   {
     method: 'setAdmin',
     toolSuffix: 'set_admin',
-    description: '设置/取消群管理员',
-    keywords: ['管理员', 'admin', '设置管理'],
+    description: '设置或取消群管理员。注意：此操作需要群主权限，普通管理员无法执行。enable=true 为设置管理员，enable=false 为取消管理员。如果只有昵称而没有 user_id，请先调用 list_members 查询',
+    keywords: ['管理员', 'admin', '设置管理', '取消管理', '提升管理', '撤销管理'],
     permissionLevel: 'group_owner',
     extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID' },
-      enable: { type: 'boolean', description: '设置(true)/取消(false)', default: true },
+      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
+      enable: { type: 'boolean', description: 'true=设置为管理员，false=取消管理员身份', default: true },
     },
     extraRequired: ['user_id'],
   },
   {
     method: 'listMembers',
     toolSuffix: 'list_members',
-    description: '获取群/服务器成员列表',
-    keywords: ['成员', '列表', 'members', 'list'],
+    description: '获取群/服务器成员列表。返回所有成员的 ID、昵称、名片、角色等信息。当用户提供昵称/名片而非 ID 时，应先调用此工具查询成员列表，从中匹配到目标用户的 user_id，再执行禁言、踢人等操作',
+    keywords: ['成员', '列表', 'members', 'list', '查找', '搜索用户'],
     permissionLevel: 'user',
     extraParams: {},
     preExecutable: true,
@@ -115,52 +115,52 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
   {
     method: 'banMember',
     toolSuffix: 'ban_member',
-    description: '封禁成员',
-    keywords: ['封禁', 'ban', '拉黑'],
+    description: '永久封禁成员（拉入黑名单）。与踢人(kick)不同，封禁后该成员无法再加入群聊。适用于恶意用户、严重违规等需要永久禁止的场景。如果只有昵称而没有 user_id，请先调用 list_members 查询',
+    keywords: ['封禁', 'ban', '拉黑', '黑名单'],
     permissionLevel: 'group_admin',
     extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID' },
-      reason: { type: 'string', description: '封禁原因' },
+      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
+      reason: { type: 'string', description: '封禁原因（将记录在封禁日志中）' },
     },
     extraRequired: ['user_id'],
   },
   {
     method: 'unbanMember',
     toolSuffix: 'unban_member',
-    description: '解除封禁',
-    keywords: ['解封', 'unban', '解除封禁'],
+    description: '解除封禁，将成员从黑名单中移除。解除后该成员可以重新加入群聊。如果只有昵称而没有 user_id，请先调用 list_members 查询',
+    keywords: ['解封', 'unban', '解除封禁', '移出黑名单'],
     permissionLevel: 'group_admin',
     extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID' },
+      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
     },
     extraRequired: ['user_id'],
   },
   {
     method: 'setGroupName',
     toolSuffix: 'set_group_name',
-    description: '修改群名称',
-    keywords: ['群名', '改名', 'group name'],
+    description: '修改群/服务器名称。修改后所有成员立即可见新群名',
+    keywords: ['群名', '改名', 'group name', '修改群名'],
     permissionLevel: 'group_admin',
     extraParams: {
-      name: { type: 'string', description: '新群名' },
+      name: { type: 'string', description: '新群名称' },
     },
     extraRequired: ['name'],
   },
   {
     method: 'muteAll',
     toolSuffix: 'mute_all',
-    description: '全员禁言/解除全员禁言',
-    keywords: ['全员禁言', 'mute all', '全体禁言'],
+    description: '开启或关闭全员禁言。开启后除管理员外所有成员都无法发言。适用于紧急维护、重要通知、聊天秩序混乱等场景。enable=true 开启，enable=false 解除',
+    keywords: ['全员禁言', 'mute all', '全体禁言', '全体解禁'],
     permissionLevel: 'group_admin',
     extraParams: {
-      enable: { type: 'boolean', description: '开启(true)/解除(false)', default: true },
+      enable: { type: 'boolean', description: 'true=开启全员禁言，false=解除全员禁言', default: true },
     },
   },
   {
     method: 'getGroupInfo',
     toolSuffix: 'get_group_info',
-    description: '获取群/服务器基本信息',
-    keywords: ['群信息', 'group info', '群资料'],
+    description: '获取群/服务器基本信息，包括群名、群主、成员数量、创建时间等。用于了解群聊概况',
+    keywords: ['群信息', 'group info', '群资料', '群详情'],
     permissionLevel: 'user',
     extraParams: {},
     preExecutable: true,
@@ -173,7 +173,13 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
 
 export const GROUP_MANAGEMENT_SKILL_DESCRIPTION =
   '群聊管理能力：在 IM 系统中对群/服务器进行管理，包括踢人、禁言、封禁、' +
-  '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。';
+  '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。\n\n' +
+  '使用指南：\n' +
+  '1. 用户提供昵称/名片而非 ID 时，必须先调用 list_members 查询成员列表，从返回结果中匹配目标用户的 user_id，再执行后续操作\n' +
+  '2. 禁言(mute_member)适用场景：违规发言、刷屏、骚扰他人等；传 duration=0 可解除禁言\n' +
+  '3. 设置/取消管理员(set_admin)需要群主权限，普通管理员无法操作；enable=false 为取消管理员\n' +
+  '4. 踢人(kick_member)是将成员移出群聊，封禁(ban_member)是永久拉黑，两者不同\n' +
+  '5. 操作前应确认目标用户正确，避免误操作';
 
 export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
 export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [

package/src/cron.ts

@@ -1,142 +1,4 @@
-import { Cron as Croner } from 'croner';
-
 /**
- * Cron 定时任务类
- * 基于 croner 实现的定时任务调度器 (无需 Luxon，内存占用更小)
+ * Re-export from @zhin.js/kernel for backward compatibility.
  */
-export class Cron {
-  private job: Croner | null = null;
-  id:string = '';
-  private callback: () => void | Promise<void>;
-  private isDisposed = false;
-  private _cronExpression: string;
-
-  /**
-   * 创建一个新的 Cron 实例
-   * @param cronExpression - Cron 表达式 (例如: '0 0 * * *' 表示每天午夜执行)
-   * @param callback - 要执行的回调函数
-   */
-  constructor(cronExpression: string, callback: () => void | Promise<void>) {
-    this.id=Math.random().toString(36).substring(2, 10);
-    try {
-      this._cronExpression = cronExpression;
-      this.callback = callback;
-      
-      // 验证 cron 表达式是否有效 (不启动)
-      const testJob = new Croner(cronExpression, { paused: true });
-      testJob.stop();
-    } catch (error) {
-      throw new Error(`Invalid cron expression "${cronExpression}": ${(error as Error).message}`);
-    }
-  }
-
-  /**
-   * 启动定时任务
-   */
-  run(): void {
-    if (this.isDisposed) {
-      throw new Error('Cannot run a disposed cron job');
-    }
-
-    if (this.job) {
-      return; // 已经在运行中
-    }
-
-    // 创建并启动任务
-    this.job = new Croner(this._cronExpression, async () => {
-      try {
-        await this.callback();
-      } catch (error) {
-        console.error(`Error executing cron callback: ${(error as Error).message}`);
-      }
-    });
-  }
-
-  /**
-   * 停止定时任务
-   */
-  stop(): void {
-    if (this.job) {
-      this.job.stop();
-      this.job = null;
-    }
-  }
-
-  /**
-   * 销毁定时任务，释放资源
-   */
-  dispose(): void {
-    this.stop();
-    this.isDisposed = true;
-  }
-
-  /**
-   * 获取下一次执行时间
-   */
-  getNextExecutionTime(): Date {
-    if (this.isDisposed) {
-      throw new Error('Cannot get next execution time for a disposed cron job');
-    }
-    
-    // 创建临时任务来获取下次执行时间
-    const tempJob = new Croner(this._cronExpression, { paused: true });
-    const nextRun = tempJob.nextRun();
-    tempJob.stop();
-    
-    if (!nextRun) {
-      throw new Error('Cannot determine next execution time');
-    }
-    
-    return nextRun;
-  }
-
-  /**
-   * 检查任务是否正在运行
-   */
-  get running(): boolean {
-    return this.job !== null;
-  }
-
-  /**
-   * 检查任务是否已被销毁
-   */
-  get disposed(): boolean {
-    return this.isDisposed;
-  }
-
-  /**
-   * 获取原始的 cron 表达式字符串
-   */
-  get cronExpression(): string {
-    return this._cronExpression;
-  }
-}
-
-//
-// Cron 表达式格式说明:
-//
-// 标准格式: "分 时 日 月 周" (5 字段)
-//
-// 字段说明:
-// - 分: 0-59
-// - 时: 0-23
-// - 日: 1-31
-// - 月: 1-12 (或 JAN-DEC)
-// - 周: 0-7 (0和7都表示周日，或 SUN-SAT)
-//
-// > croner 也支持 6 字段格式 "秒 分 时 日 月 周"，但推荐使用 5 字段格式。
-//
-// 特殊字符:
-// - 星号: 匹配任意值
-// - 问号: 用于日和周字段，表示不指定值
-// - 横线: 表示范围，如 1-5
-// - 逗号: 表示列表，如 1,3,5
-// - 斜杠: 表示步长，如 */15 表示每15分钟
-//
-// 常用示例:
-// - "0 0 * * *": 每天午夜执行
-// - "*/15 * * * *": 每15分钟执行
-// - "0 12 * * *": 每天中午12点执行
-// - "0 0 1 * *": 每月1号午夜执行
-// - "0 0 * * 0": 每周日午夜执行
-//
+export { Cron } from '@zhin.js/kernel';

package/src/errors.ts

@@ -1,70 +1,21 @@
-// ============================================================================
-// 错误处理系统
-// ============================================================================
-
 /**
- * 基础错误类，所有自定义错误都应该继承此类
+ * Re-export generic errors from @zhin.js/kernel
  */
-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 {
+  ZhinError,
+  ConfigError,
+  PluginError,
+  ConnectionError,
+  ContextError,
+  ValidationError,
+  PermissionError,
+  TimeoutError,
+  ErrorManager,
+  RetryManager,
+  CircuitBreaker,
+} from '@zhin.js/kernel';
 
-/**
- * 配置相关错误
- */
-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
-    }
-}
+import { ZhinError } from '@zhin.js/kernel';
 
 /**
  * 适配器相关错误
@@ -80,18 +31,6 @@ export class AdapterError extends ZhinError {
     }
 }
 
-/**
- * 连接相关错误
- */
-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
-    }
-}
-
 /**
  * 消息处理错误
  */
@@ -105,261 +44,3 @@ export class MessageError extends ZhinError {
         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
-})