@zhin.js/core 1.0.37 → 1.0.39

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

@@ -0,0 +1,207 @@
+/**
+ * Group Management Skill — 方法规范与元数据
+ *
+ * 设计理念：
+ *   群管理是 IM 系统的一种"技能"(Skill)，而非一组零散的工具。
+ *   Adapter 基类声明群管理操作的方法规范（可选），
+ *   具体适配器（ICQQ/Discord/Telegram 等）选择性覆写。
+ *   Adapter.start() 自动检测哪些方法已被子类实现，
+ *   生成对应的 Tool 并注册为 "群聊管理" Skill。
+ *
+ * 子类无需任何额外调用：
+ *
+ *   class IcqqAdapter extends Adapter<IcqqBot> {
+ *     async kickMember(botId, sceneId, userId) { ... }
+ *     async muteMember(botId, sceneId, userId, duration) { ... }
+ *     // start() 中自动检测 → 自动注册 Skill，零样板代码
+ *   }
+ */
+
+import type { ToolPermissionLevel } from '../types.js';
+
+// ============================================================================
+// Adapter 群管理方法规范
+// ============================================================================
+
+/**
+ * 群管理能力接口。
+ * Adapter 基类通过此接口声明方法签名，子类选择性覆写。
+ */
+export interface IGroupManagement {
+  kickMember?(botId: string, sceneId: string, userId: string): Promise<any>;
+  muteMember?(botId: string, sceneId: string, userId: string, duration?: number): Promise<any>;
+  setMemberNickname?(botId: string, sceneId: string, userId: string, nickname: string): Promise<any>;
+  setAdmin?(botId: string, sceneId: string, userId: string, enable?: boolean): Promise<any>;
+  listMembers?(botId: string, sceneId: string): Promise<any>;
+  banMember?(botId: string, sceneId: string, userId: string, reason?: string): Promise<any>;
+  unbanMember?(botId: string, sceneId: string, userId: string): Promise<any>;
+  setGroupName?(botId: string, sceneId: string, name: string): Promise<any>;
+  muteAll?(botId: string, sceneId: string, enable?: boolean): Promise<any>;
+  getGroupInfo?(botId: string, sceneId: string): Promise<any>;
+}
+
+// ============================================================================
+// 方法 → Tool 元数据映射
+// ============================================================================
+
+export interface GroupMethodSpec {
+  method: keyof IGroupManagement;
+  toolSuffix: string;
+  description: string;
+  keywords: string[];
+  permissionLevel: ToolPermissionLevel;
+  extraParams: Record<string, { type: string; description: string; default?: any }>;
+  extraRequired?: string[];
+  preExecutable?: boolean;
+}
+
+export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
+  {
+    method: 'kickMember',
+    toolSuffix: 'kick_member',
+    description: '将成员踢出群/服务器',
+    keywords: ['踢', 'kick', '移除', '踢出'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'muteMember',
+    toolSuffix: 'mute_member',
+    description: '禁言群成员（duration=0 解除）',
+    keywords: ['禁言', 'mute', '静音', '解除禁言'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      duration: { type: 'number', description: '禁言时长(秒)，0=解除', default: 600 },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'setMemberNickname',
+    toolSuffix: 'set_nickname',
+    description: '设置群成员昵称/名片',
+    keywords: ['昵称', '名片', 'nickname', 'card'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      nickname: { type: 'string', description: '新昵称' },
+    },
+    extraRequired: ['user_id', 'nickname'],
+  },
+  {
+    method: 'setAdmin',
+    toolSuffix: 'set_admin',
+    description: '设置/取消群管理员',
+    keywords: ['管理员', 'admin', '设置管理'],
+    permissionLevel: 'group_owner',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      enable: { type: 'boolean', description: '设置(true)/取消(false)', default: true },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'listMembers',
+    toolSuffix: 'list_members',
+    description: '获取群/服务器成员列表',
+    keywords: ['成员', '列表', 'members', 'list'],
+    permissionLevel: 'user',
+    extraParams: {},
+    preExecutable: true,
+  },
+  {
+    method: 'banMember',
+    toolSuffix: 'ban_member',
+    description: '封禁成员',
+    keywords: ['封禁', 'ban', '拉黑'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      reason: { type: 'string', description: '封禁原因' },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'unbanMember',
+    toolSuffix: 'unban_member',
+    description: '解除封禁',
+    keywords: ['解封', 'unban', '解除封禁'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'setGroupName',
+    toolSuffix: 'set_group_name',
+    description: '修改群名称',
+    keywords: ['群名', '改名', 'group name'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      name: { type: 'string', description: '新群名' },
+    },
+    extraRequired: ['name'],
+  },
+  {
+    method: 'muteAll',
+    toolSuffix: 'mute_all',
+    description: '全员禁言/解除全员禁言',
+    keywords: ['全员禁言', 'mute all', '全体禁言'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      enable: { type: 'boolean', description: '开启(true)/解除(false)', default: true },
+    },
+  },
+  {
+    method: 'getGroupInfo',
+    toolSuffix: 'get_group_info',
+    description: '获取群/服务器基本信息',
+    keywords: ['群信息', 'group info', '群资料'],
+    permissionLevel: 'user',
+    extraParams: {},
+    preExecutable: true,
+  },
+];
+
+// ============================================================================
+// Skill 常量
+// ============================================================================
+
+export const GROUP_MANAGEMENT_SKILL_DESCRIPTION =
+  '群聊管理能力：在 IM 系统中对群/服务器进行管理，包括踢人、禁言、封禁、' +
+  '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。';
+
+export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
+export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [
+  '群管理', '踢人', '禁言', '封禁', '管理员', '群名',
+  '成员', 'kick', 'mute', 'ban', 'admin', 'members',
+];
+
+// ============================================================================
+// 参数映射（method → 有序参数列表）
+// ============================================================================
+
+export function buildMethodArgs(
+  method: keyof IGroupManagement,
+  botId: string,
+  sceneId: string,
+  rest: Record<string, any>,
+): any[] {
+  switch (method) {
+    case 'kickMember':      return [botId, sceneId, rest.user_id];
+    case 'muteMember':      return [botId, sceneId, rest.user_id, rest.duration ?? 600];
+    case 'setMemberNickname': return [botId, sceneId, rest.user_id, rest.nickname];
+    case 'setAdmin':        return [botId, sceneId, rest.user_id, rest.enable ?? true];
+    case 'listMembers':     return [botId, sceneId];
+    case 'banMember':       return [botId, sceneId, rest.user_id, rest.reason];
+    case 'unbanMember':     return [botId, sceneId, rest.user_id];
+    case 'setGroupName':    return [botId, sceneId, rest.name];
+    case 'muteAll':         return [botId, sceneId, rest.enable ?? true];
+    case 'getGroupInfo':    return [botId, sceneId];
+    default:                return [botId, sceneId, ...Object.values(rest)];
+  }
+}

package/src/built/dispatcher.ts

@@ -149,72 +149,73 @@ declare module '../plugin.js' {
  * 创建 MessageDispatcher Context
  */
 export function createMessageDispatcher(): Context<'dispatcher', DispatcherContextExtensions> {
-  // 护栏中间件列表
   const guardrails: GuardrailMiddleware[] = [];
-
-  // AI 处理函数（由 AI 模块注册）
   let aiHandler: AIHandler | null = null;
-
-  // AI 触发判定器（由 AI 模块注册）
   let aiTriggerMatcher: AITriggerMatcher | null = null;
-
-  // 命令匹配器（默认由 command service 驱动）
   let commandMatcher: CommandMatcher | null = null;
-
-  // 根插件引用（mounted 时设置）
   let rootPlugin: Plugin | null = null;
 
+  // Command prefix index — rebuilt lazily for O(1) lookup
+  let commandPrefixIndex: Map<string, boolean> | null = null;
+  let lastCommandCount = -1;
+
+  function rebuildCommandIndex(): Map<string, boolean> {
+    const index = new Map<string, boolean>();
+    if (rootPlugin) {
+      const commandService = rootPlugin.inject('command');
+      if (commandService?.items) {
+        for (const cmd of commandService.items) {
+          const prefix = cmd.pattern?.split(/\s/)[0];
+          if (prefix) index.set(prefix, true);
+        }
+      }
+    }
+    return index;
+  }
+
+  function getCommandIndex(): Map<string, boolean> {
+    const commandService = rootPlugin?.inject('command');
+    const currentCount = commandService?.items?.length ?? 0;
+    if (!commandPrefixIndex || currentCount !== lastCommandCount) {
+      commandPrefixIndex = rebuildCommandIndex();
+      lastCommandCount = currentCount;
+    }
+    return commandPrefixIndex;
+  }
+
   /**
-   * 执行 Guardrail 管道
-   * 返回 true 表示消息通过，false 表示被拦截
+   * Guardrail pipeline — a guardrail that does NOT call next() blocks the message.
    */
   async function runGuardrails(message: Message<any>): Promise<boolean> {
     if (guardrails.length === 0) return true;
 
-    let passed = true;
-    let index = 0;
-
-    const runNext = async (): Promise<void> => {
-      if (index >= guardrails.length) return;
-      const guardrail = guardrails[index++];
+    for (const guardrail of guardrails) {
+      let nextCalled = false;
       try {
-        await guardrail(message, runNext);
+        await guardrail(message, async () => { nextCalled = true; });
       } catch {
-        // Guardrail 抛异常 → 拦截消息
-        passed = false;
+        return false;
       }
-    };
-
-    await runNext();
-    return passed;
+      if (!nextCalled) return false;
+    }
+    return true;
   }
 
-  /**
-   * 路由判定：这条消息该走哪条路径？
-   */
   function route(message: Message<any>): RouteResult {
-    // 提取文本内容
     const text = extractText(message);
 
-    // 1. 如果有自定义命令匹配器，优先使用
     if (commandMatcher && commandMatcher(text, message)) {
       return { type: 'command' };
     }
 
-    // 2. 默认命令匹配：检查 commandService
-    if (rootPlugin) {
-      const commandService = rootPlugin.inject('command');
-      if (commandService?.items) {
-        for (const cmd of commandService.items) {
-          const pattern = cmd.pattern?.split(/\s/)[0];
-          if (pattern && text.startsWith(pattern)) {
-            return { type: 'command' };
-          }
-        }
+    // Use indexed lookup instead of O(N) scan
+    const index = getCommandIndex();
+    for (const [prefix] of index) {
+      if (text.startsWith(prefix)) {
+        return { type: 'command' };
       }
     }
 
-    // 3. AI 触发判定
     if (aiTriggerMatcher) {
       const { triggered, content } = aiTriggerMatcher(message);
       if (triggered) {
@@ -222,13 +223,9 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
       }
     }
 
-    // 4. 都不匹配 → 跳过
     return { type: 'skip' };
   }
 
-  /**
-   * 提取消息文本（简单实现，与 ai-trigger 中的 extractTextContent 对齐）
-   */
   function extractText(message: Message<any>): string {
     if (!message.$content) return '';
     return message.$content
@@ -241,8 +238,6 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
       .trim();
   }
 
-  // ─── 服务实例 ───────────────────────────────────────────────────────────
-
   const service: MessageDispatcherService = {
     async dispatch(message: Message<any>) {
       // Stage 1: Guardrail
@@ -255,7 +250,6 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
       // Stage 3: Handle
       switch (result.type) {
         case 'command': {
-          // 命令快速路径 — 直接委托给 commandService
           if (rootPlugin) {
             const commandService = rootPlugin.inject('command');
             if (commandService) {
@@ -269,7 +263,6 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
         }
 
         case 'ai': {
-          // AI Agent 路径
           if (aiHandler) {
             await aiHandler(message, result.content);
           }
@@ -278,13 +271,19 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
 
         case 'skip':
         default:
-          // 不处理
           break;
       }
 
-      // 兼容：仍然执行旧的中间件链（除了默认的命令中间件和 AI 触发中间件）
-      // 这样既有 Guardrail/Dispatcher 新逻辑，又不会丢失已有的自定义中间件
-      // Phase 1 阶段先保持兼容，后续逐步迁移
+      // Run legacy custom middlewares (skip the built-in command middleware at index 0).
+      // This ensures plugins that registered middlewares via addMiddleware() still work.
+      if (rootPlugin) {
+        const customMiddlewares = (rootPlugin as any)._getCustomMiddlewares?.() as MessageMiddleware<RegisteredAdapter>[] | undefined;
+        if (customMiddlewares && customMiddlewares.length > 0) {
+          const { compose } = await import('../utils.js');
+          const composed = compose(customMiddlewares);
+          await composed(message, async () => {});
+        }
+      }
     },
 
     addGuardrail(guardrail: GuardrailMiddleware) {

package/src/built/skill.ts

@@ -232,21 +232,20 @@ export class SkillFeature extends Feature<Skill> {
         const pluginName = plugin.name;
 
         // 收集该插件注册的工具
-        const toolService = plugin.root.inject('tool' as any) as any;
+        const toolService = plugin.root.inject('tool') as { getToolsByPlugin?: (name: string) => Tool[] } | undefined;
         let tools: Tool[] = [];
 
         if (toolService && typeof toolService.getToolsByPlugin === 'function') {
           tools = toolService.getToolsByPlugin(pluginName);
         } else {
-          // 回退：从插件本地工具获取
           tools = plugin.getAllTools?.() || [];
         }
 
         // 聚合关键词：开发者声明 + 工具自带
         const allKeywords = new Set<string>(metadata.keywords || []);
         for (const tool of tools) {
-          if ((tool as any).keywords) {
-            for (const kw of (tool as any).keywords) {
+          if (tool.keywords) {
+            for (const kw of tool.keywords) {
               allKeywords.add(kw);
             }
           }

package/src/built/tool.ts

@@ -6,7 +6,7 @@ import { Feature, FeatureJSON } from "../feature.js";
 import { MessageCommand } from "../command.js";
 import { Message } from "../message.js";
 import { Plugin, getPlugin } from "../plugin.js";
-import type { Tool, ToolDefinition, RegisteredAdapter, AdapterMessage, ToolContext, ToolJsonSchema, ToolParametersSchema, PropertySchema, MaybePromise, ToolPermissionLevel, ToolScope } from "../types.js";
+import type { Tool, RegisteredAdapter, AdapterMessage, ToolContext, ToolJsonSchema, ToolParametersSchema, PropertySchema, MaybePromise, ToolPermissionLevel, ToolScope } from "../types.js";
 import { MatchResult } from "segment-matcher";
 
 // ============================================================================
@@ -147,7 +147,7 @@ export function extractParamInfo(parameters: ToolJsonSchema): Tool.ParamInfo[] {
  * 定义工具的辅助函数（提供类型推断）
  */
 export function defineTool<TArgs extends Record<string, any> = Record<string, any>>(
-  tool: ToolDefinition<TArgs>
+  tool: Tool<TArgs>
 ): Tool {
   return tool as Tool;
 }
@@ -587,7 +587,7 @@ function commandToToolFn(
         
         const plugin = getPlugin();
         const result = await command.handle(tempMessage, plugin);
-        return result;
+        return result as import("../types.js").ToolResult;
       }
       
       return { 

package/src/feature.ts

@@ -16,6 +16,11 @@ export interface FeatureJSON {
   items: any[];
 }
 
+/**
+ * Feature 变更事件监听器类型
+ */
+export type FeatureListener<T> = (item: T, pluginName: string) => void;
+
 /**
  * Feature<T> 抽象类
  * - name / icon / desc: 自描述元数据
@@ -24,6 +29,7 @@ export interface FeatureJSON {
  * - toJSON: 控制 HTTP API 返回的数据格式
  * - extensions: 提供给 Plugin.prototype 的扩展方法（如 addCommand）
  * - mounted / dispose: 可选生命周期钩子
+ * - on('add' | 'remove'): 变更事件通知
  */
 export abstract class Feature<T = any> {
   abstract readonly name: string;
@@ -36,6 +42,32 @@ export abstract class Feature<T = any> {
   /** 按插件名分组的 item 列表 */
   protected pluginItems = new Map<string, T[]>();
 
+  /** 事件监听器 */
+  #listeners = new Map<string, Set<FeatureListener<T>>>();
+
+  /**
+   * 监听变更事件
+   * @param event 'add' | 'remove'
+   * @param listener 回调函数
+   * @returns 取消监听的函数
+   */
+  on(event: 'add' | 'remove', listener: FeatureListener<T>): () => void {
+    if (!this.#listeners.has(event)) {
+      this.#listeners.set(event, new Set());
+    }
+    this.#listeners.get(event)!.add(listener);
+    return () => { this.#listeners.get(event)?.delete(listener); };
+  }
+
+  /** 触发事件 */
+  protected emit(event: 'add' | 'remove', item: T, pluginName: string): void {
+    const listeners = this.#listeners.get(event);
+    if (!listeners) return;
+    for (const listener of listeners) {
+      try { listener(item, pluginName); } catch { /* 防止监听器异常影响主流程 */ }
+    }
+  }
+
   /**
    * 添加 item，同时记录所属插件
    * @returns dispose 函数，用于移除该 item
@@ -46,25 +78,36 @@ export abstract class Feature<T = any> {
       this.pluginItems.set(pluginName, []);
     }
     this.pluginItems.get(pluginName)!.push(item);
-    return () => this.remove(item);
+    this.emit('add', item, pluginName);
+    return () => this.remove(item, pluginName);
   }
 
   /**
    * 移除 item
    */
-  remove(item: T): boolean {
+  remove(item: T, pluginName?: string): boolean {
     const idx = this.items.indexOf(item);
     if (idx !== -1) {
       this.items.splice(idx, 1);
+      const resolvedPluginName = pluginName ?? this.#findPluginName(item);
       for (const [, items] of this.pluginItems) {
         const i = items.indexOf(item);
         if (i !== -1) items.splice(i, 1);
       }
+      this.emit('remove', item, resolvedPluginName ?? '');
       return true;
     }
     return false;
   }
 
+  /** 反查 item 所属的 pluginName */
+  #findPluginName(item: T): string | undefined {
+    for (const [name, items] of this.pluginItems) {
+      if (items.includes(item)) return name;
+    }
+    return undefined;
+  }
+
   /**
    * 获取指定插件注册的 item 列表
    */

package/src/index.ts

@@ -26,6 +26,8 @@ export * from './built/ai-trigger.js'
 export * from './built/dispatcher.js'
 // Skill 系统 (AI 能力描述)
 export * from './built/skill.js'
+// Common adapter tool factories (shared across adapters)
+export * from './built/common-adapter-tools.js'
 // AI 模块 (原 @zhin.js/ai，已合并至 core)
 export * from './ai/index.js'