@zhin.js/core 1.0.36 → 1.0.38

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'
 

package/src/plugin.ts

@@ -21,7 +21,8 @@ import { Adapter, Adapters } from "./adapter.js";
 import { Feature, FeatureJSON } from "./feature.js";
 import { createHash } from "crypto";
 const contextsKey = Symbol("contexts");
-const loadedModules = new Map<string, Plugin>(); // 记录已加载的模块
+const extensionOwnersKey = Symbol("extensionOwners");
+const loadedModules = new Map<string, Plugin>();
 const require = createRequire(import.meta.url);
 
 
@@ -138,8 +139,11 @@ export interface Plugin extends Plugin.Extensions { }
  */
 export class Plugin extends EventEmitter<Plugin.Lifecycle> {
   static [contextsKey] = [] as string[];
+  /** Maps extension method name → context name that owns it */
+  static [extensionOwnersKey] = new Map<string, string>();
 
   #cachedName?: string;
+  #explicitName?: string;
   adapters: (keyof Plugin.Contexts)[] = [];
   started = false;
 
@@ -182,6 +186,14 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
   get middleware(): MessageMiddleware<RegisteredAdapter> {
     return compose<RegisteredAdapter>(this.#middlewares);
   }
+
+  /**
+   * Returns custom middlewares (excluding the built-in command middleware).
+   * Used by MessageDispatcher to run legacy middlewares after dispatch.
+   */
+  _getCustomMiddlewares(): MessageMiddleware<RegisteredAdapter>[] {
+    return this.#middlewares.filter(m => m !== this.#messageMiddleware);
+  }
   /**
    * 构造函数
    */
@@ -213,8 +225,10 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
    * @param middleware 中间件函数
    */
   addMiddleware<T extends RegisteredAdapter>(middleware: MessageMiddleware<T>): () => void {
-    if(this.parent){
-      const dispose= this.parent.addMiddleware(middleware);
+    // Always register on root so middlewares reach the global chain
+    const target = this.root;
+    if (target !== this) {
+      const dispose = target.addMiddleware(middleware);
       this.#disposables.add(dispose);
       return () => {
         dispose();
@@ -241,8 +255,7 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     tool: Tool,
     generateCommand: boolean = true
   ): () => void {
-    // 尝试使用 ToolFeature
-    const toolService = this.root.inject('tool' as any) as any;
+    const toolService = this.root.inject('tool') as { addTool?: (tool: Tool, name: string, gen: boolean) => () => void } | undefined;
     if (toolService && typeof toolService.addTool === 'function') {
       const dispose = toolService.addTool(tool, this.name, generateCommand);
       this.#disposables.add(dispose);
@@ -305,8 +318,7 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
    * 优先使用 ToolService，否则回退到本地收集
    */
   collectAllTools(): Tool[] {
-    // 尝试使用 ToolService
-    const toolService = this.root.inject('tool' as any) as any;
+    const toolService = this.root.inject('tool') as { collectAll?: (root: Plugin) => Tool[] } | undefined;
     if (toolService && typeof toolService.collectAll === 'function') {
       return toolService.collectAll(this.root);
     }
@@ -331,9 +343,22 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
   }
 
   /**
-   * 插件名称
+   * 显式设置插件名称（优先级高于路径推导）。
+   * 可通过以下方式声明：
+   *   1. 模块导出 `export const pluginName = 'my-plugin'`
+   *   2. 调用 `plugin.setName('my-plugin')`
+   */
+  setName(name: string): void {
+    this.#explicitName = name;
+    this.#cachedName = name;
+    this.logger = logger.getLogger(name);
+  }
+
+  /**
+   * 插件名称（显式名称 > 路径推导）
    */
   get name(): string {
+    if (this.#explicitName) return this.#explicitName;
     if (this.#cachedName) return this.#cachedName;
 
     let name = path
@@ -394,16 +419,15 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
       if (!dispose) return;
       const disposeFn = async (name: keyof Plugin.Contexts) => {
         if (contexts.includes(name)) {
-          await dispose(this.inject(name) as any)
+          await dispose(this.inject(name) as ArrayItem<ContextList<T>>)
         }
         this.off('context.dispose', disposeFn)
         sideEffect.finished = false;
       }
       this.on('context.dispose', disposeFn)
-      // 确保 dispose 时清理监听器（只注册一次）
       const cleanupOnDispose = () => {
         this.off('context.dispose', disposeFn)
-        dispose(this.inject(args[0] as any) as any)
+        dispose(this.inject(args[0] as unknown as keyof Plugin.Contexts) as unknown as ArrayItem<ContextList<T>>)
       }
       this.once('dispose', cleanupOnDispose)
     }
@@ -417,9 +441,11 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     if (!this.#contextsIsReady(contexts)) return
     contextReadyCallback()
   }
-  inject<T extends keyof Plugin.Contexts>(name: T): Plugin.Contexts[T] | undefined {
-    const context = this.root.contexts.get(name as string);
-    return context?.value as Plugin.Contexts[T];
+  inject<T extends keyof Plugin.Contexts>(name: T): Plugin.Contexts[T] | undefined;
+  inject(name: string): unknown;
+  inject(name: string): unknown {
+    const context = this.root.contexts.get(name);
+    return context?.value;
   }
   #contextsIsReady<CS extends (keyof Plugin.Contexts)[]>(contexts: CS) {
     if (!contexts.length) return true
@@ -457,13 +483,7 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     for (const child of this.children) {
       await child.start(t);
     }
-    // 输出启动日志（使用 debug 级别，避免重复输出）
-    // 只在根插件或重要插件时使用 info 级别
-    if (!this.parent || this.name === 'setup') {
-      this.logger.info(`Plugin "${this.name}" ${t ? `reloaded in ${Date.now() - t}ms` : "started"}`);
-    } else {
-      this.logger.debug(`Plugin "${this.name}" ${t ? `reloaded in ${Date.now() - t}ms` : "started"}`);
-    }
+    this.logger.debug(`Plugin "${this.name}" ${t ? `reloaded in ${Date.now() - t}ms` : "started"}`);
   }
   /**
    * 记录 Feature 贡献（由 Feature extensions 内部调用）
@@ -636,13 +656,15 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     }
     this.children = [];
 
-    // 停止服务
+    // 停止服务 — only remove extensions owned by this plugin's contexts
     for (const [name, context] of this.$contexts) {
       remove(Plugin[contextsKey], name);
-      // 移除扩展方法
       if (context.extensions) {
         for (const key of Object.keys(context.extensions)) {
-          delete (Plugin.prototype as any)[key];
+          if (Plugin[extensionOwnersKey].get(key) === name) {
+            delete (Plugin.prototype as unknown as Record<string, unknown>)[key];
+            Plugin[extensionOwnersKey].delete(key);
+          }
         }
       }
       if (typeof context.dispose === "function") {
@@ -750,16 +772,15 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
    */
   provide<T extends keyof Plugin.Contexts>(target: Feature | Context<T>): this {
     if (target instanceof Feature) {
-      // Feature → 自动转为内部 Context 格式存储
       const feature = target;
       const context: Context<T> = {
         name: feature.name as T,
         description: feature.desc,
-        value: feature as any,
+        value: feature as Plugin.Contexts[T],
         mounted: feature.mounted
           ? async (plugin: Plugin) => {
               await feature.mounted!(plugin);
-              return feature as any;
+              return feature as Plugin.Contexts[T];
             }
           : undefined,
         dispose: feature.dispose
@@ -770,17 +791,24 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
       return this.provide(context);
     }
 
-    // 传统 Context 路径
     const context = target;
     if (!Plugin[contextsKey].includes(context.name as string)) {
       Plugin[contextsKey].push(context.name as string);
     }
     this.logger.debug(`Context "${context.name as string}" provided`);
-    // 注册扩展方法到 Plugin.prototype
+
+    // Track which extension methods this context registers.
+    // On collision, log a warning but allow override (last-write-wins).
     if (context.extensions) {
+      const extNames: string[] = [];
       for (const [name, fn] of Object.entries(context.extensions)) {
         if (typeof fn === 'function') {
+          if (Reflect.has(Plugin.prototype, name) && !Plugin[extensionOwnersKey].has(name)) {
+            this.logger.warn(`Extension method "${name}" shadows an existing Plugin method`);
+          }
           Reflect.set(Plugin.prototype, name, fn);
+          Plugin[extensionOwnersKey].set(name, context.name as string);
+          extNames.push(name);
         }
       }
     }
@@ -894,7 +922,7 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     for (const key of Plugin.#coreMethods) {
       const value = proto[key];
       if (typeof value === "function") {
-        (this as any)[key] = value.bind(this);
+        (this as Record<string, unknown>)[key] = value.bind(this);
       }
     }
   }
@@ -926,16 +954,49 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     // 先记录，防止循环依赖时重复加载
     loadedModules.set(realPath, plugin);
 
+    let mod: any;
     await storage.run(plugin, async () => {
-      await import(`${pathToFileURL(entryFile).href}?t=${Date.now()}`);
+      mod = await import(`${pathToFileURL(entryFile).href}?t=${Date.now()}`);
     });
 
+    // 支持模块显式声明插件名称：export const pluginName = 'my-plugin'
+    if (mod?.pluginName && typeof mod.pluginName === 'string') {
+      plugin.setName(mod.pluginName);
+    }
+
     return plugin;
   }
 }
 export function defineContext<T extends keyof Plugin.Contexts, E extends Partial<Plugin.Extensions> = {}>(options: Context<T, E>): Context<T, E> {
   return options;
 }
+
+/**
+ * 声明式定义插件。
+ * 提供显式名称 + setup 函数，自动设置当前插件名称并执行 setup。
+ *
+ * @example
+ * ```typescript
+ * // plugins/weather/index.ts
+ * export default definePlugin({
+ *   name: 'weather',
+ *   setup(plugin) {
+ *     plugin.addTool({ ... });
+ *   },
+ * });
+ * ```
+ */
+export function definePlugin(options: {
+  name: string;
+  setup: (plugin: Plugin) => MaybePromise<void>;
+}): { pluginName: string } {
+  const plugin = usePlugin();
+  if (options.name) {
+    plugin.setName(options.name);
+  }
+  options.setup(plugin);
+  return { pluginName: options.name };
+}
 export interface Context<T extends keyof Plugin.Contexts = keyof Plugin.Contexts, E extends Partial<Plugin.Extensions> = {}> {
   name: T;
   description: string

package/src/scheduler/scheduler.ts

@@ -200,7 +200,7 @@ export class Scheduler implements IScheduler {
     };
     this.heartbeatJobId = job.id;
     this.store.jobs.push(job);
-    logger.info({ intervalMs: this.heartbeatIntervalMs }, 'Heartbeat job added');
+    logger.debug({ intervalMs: this.heartbeatIntervalMs }, 'Heartbeat job added');
   }
 
   private recomputeNextRuns(): void {