@zhin.js/core 1.0.37 → 1.0.39

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 {

package/src/types.ts

@@ -14,7 +14,7 @@ export interface Models extends Record<string,object>{
   SystemLog: SystemLog
   User: User,
 }
-export type MaybePromise<T> = T extends Promise<infer U> ? T|U : T|Promise<T>;
+export type MaybePromise<T> = [T] extends [Promise<infer U>] ? T|U : T|Promise<T>;
 export interface RegisteredAdapters {
   process: ProcessAdapter;
 }
@@ -71,6 +71,8 @@ export interface MessageSender{
   id: string;
   name?: string;
   permissions?:string[]
+  /** 平台侧角色标识（owner / admin / member 等） */
+  role?: string;
 }
 /**
  * 通用字典类型
@@ -305,25 +307,52 @@ export type ToolScope = 'private' | 'group' | 'channel';
  */
 export type ToolPermissionLevel = 'user' | 'group_admin' | 'group_owner' | 'bot_admin' | 'owner';
 
-export interface Tool {
+/**
+ * 标准化工具返回类型。
+ * execute 可返回以下任一形式：
+ * - string: 直接作为文本回复
+ * - { text: string }: 结构化文本
+ * - { data: unknown; format?: string }: 结构化数据
+ * - void/null/undefined: 无回复
+ * - Record / Array: 自动 JSON.stringify
+ */
+export type ToolResult = string | void | null | undefined | { text: string } | { data: unknown; format?: string } | Record<string, unknown> | unknown[];
+
+/**
+ * 统一的 Tool 定义（支持泛型参数类型推断）。
+ *
+ * @template TArgs 参数类型，默认 Record<string, any>
+ *
+ * @example
+ * ```typescript
+ * // 无泛型 — 兼容旧代码
+ * const tool: Tool = { name: 'ping', ... };
+ *
+ * // 有泛型 — 通过 defineTool 获得类型安全
+ * const tool = defineTool<{ city: string }>({
+ *   name: 'weather',
+ *   parameters: { type: 'object', properties: { city: { type: 'string', description: '城市' } }, required: ['city'] },
+ *   execute: async (args) => args.city, // args.city 有类型提示
+ * });
+ * ```
+ */
+export interface Tool<TArgs extends Record<string, any> = Record<string, any>> {
   /** 工具名称（唯一标识，建议使用 snake_case） */
   name: string;
   
   /** 工具描述（供 AI 和帮助系统使用） */
   description: string;
   
-  /** 
-   * 参数定义（JSON Schema 格式）
-   */
-  parameters: ToolParametersSchema;
+  /** 参数定义（JSON Schema 格式） */
+  parameters: ToolParametersSchema<TArgs>;
   
   /** 
    * 工具执行函数
    * @param args 解析后的参数
    * @param context 执行上下文（包含消息、发送者等信息）
-   * @returns 执行结果（字符串会直接作为回复，对象会被 JSON 序列化）
+   * @returns 执行结果
    */
-  execute: (args: Record<string, any>, context?: ToolContext) => MaybePromise<any>;
+  execute: (args: TArgs, context?: ToolContext) => MaybePromise<ToolResult>;
   
   /** 工具来源标识（自动填充：adapter:xxx / plugin:xxx） */
   source?: string;
@@ -386,27 +415,9 @@ export interface Tool {
 }
 
 /**
- * 类型安全的 Tool 定义（用于 defineTool）
- * 提供泛型参数以获得 execute 函数的类型推断
+ * @deprecated 使用 `Tool<TArgs>` 替代。Tool 已原生支持泛型。
  */
-export interface ToolDefinition<TArgs extends Record<string, any> = Record<string, any>> {
-  name: string;
-  description: string;
-  parameters: ToolParametersSchema<TArgs>;
-  execute: (args: TArgs, context?: ToolContext) => MaybePromise<any>;
-  source?: string;
-  tags?: string[];
-  keywords?: string[];
-  command?: Tool.CommandConfig | false;
-  permissions?: string[];
-  /** 支持的平台列表（不填则支持所有平台） */
-  platforms?: string[];
-  /** 支持的场景列表（不填则支持所有场景） */
-  scopes?: ToolScope[];
-  /** 调用所需的最低权限级别（默认 'user'） */
-  permissionLevel?: ToolPermissionLevel;
-  hidden?: boolean;
-}
+export type ToolDefinition<TArgs extends Record<string, any> = Record<string, any>> = Tool<TArgs>;
 
 export namespace Tool {
   /**

package/src/utils.ts

@@ -1,5 +1,6 @@
 import * as path from "path";
 import * as fs from "fs";
+import * as vm from "vm";
 import {
   AdapterMessage,
   Dict,
@@ -11,15 +12,21 @@ import {
 import { Message } from "./message.js";
 
 export function getValueWithRuntime(template: string, ctx: Dict) {
-  const result = evaluate(template, ctx);
-  if (result === `return(${template})`) return undefined;
-  return result;
+  return evaluate(template, ctx);
 }
-export const evaluate = <S, T = any>(exp: string, context: S) => {
-  const result = execute<S, T>(`return(${exp})`, context);
-  // 如果结果是原始表达式，说明访问被阻止，返回 undefined
-  if (result === `return(${exp})`) return undefined;
-  return result;
+/**
+ * Evaluate a single expression in a sandboxed vm context.
+ * Unlike `execute`, does NOT wrap in IIFE — the expression value is returned directly.
+ */
+export const evaluate = <S extends Record<string, unknown>, T = unknown>(exp: string, context: S): T | undefined => {
+  const script = getOrCompileScript(exp);
+  if (!script) return undefined;
+
+  try {
+    return script.runInNewContext(buildSandbox(context), { timeout: 200 }) as T;
+  } catch {
+    return undefined;
+  }
 };
 /**
  * 组合中间件,洋葱模型
@@ -74,25 +81,28 @@ export function compose<P extends RegisteredAdapter=RegisteredAdapter>(
     return dispatch(0);
   };
 }
-// 使用 LRU 缓存限制大小，防止内存泄漏
+// LRU cache for compiled vm.Script instances
 const MAX_EVAL_CACHE_SIZE = 1000;
-const evalCache: Record<string, Function> = Object.create(null);
-const evalCacheKeys: string[] = [];
+const scriptCache = new Map<string, vm.Script>();
 
-export const execute = <S, T = any>(exp: string, context: S): T => {
-  let fn = evalCache[exp];
-  
-  if (!fn) {
-    // 如果缓存已满，删除最旧的条目（LRU）
-    if (evalCacheKeys.length >= MAX_EVAL_CACHE_SIZE) {
-      const oldest = evalCacheKeys.shift()!;
-      delete evalCache[oldest];
-    }
-    
-    fn = evalCache[exp] = toFunction(exp);
-    evalCacheKeys.push(exp);
+function getOrCompileScript(code: string): vm.Script | null {
+  let script = scriptCache.get(code);
+  if (script) return script;
+  try {
+    script = new vm.Script(code);
+  } catch {
+    return null;
   }
-  context = {
+  if (scriptCache.size >= MAX_EVAL_CACHE_SIZE) {
+    const oldest = scriptCache.keys().next().value;
+    if (oldest !== undefined) scriptCache.delete(oldest);
+  }
+  scriptCache.set(code, script);
+  return script;
+}
+
+function buildSandbox<S extends Record<string, unknown>>(context: S): Record<string, unknown> {
+  return {
     ...context,
     process: {
       version: process.version,
@@ -106,48 +116,48 @@ export const execute = <S, T = any>(exp: string, context: S): T => {
       pid: process.pid,
       ppid: process.ppid,
     },
-    Bun: "你想干嘛",
     global: undefined,
+    globalThis: undefined,
     Buffer: undefined,
     crypto: undefined,
+    require: undefined,
+    import: undefined,
+    __dirname: undefined,
+    __filename: undefined,
+    Bun: undefined,
+    Deno: undefined,
   };
-  try {
-    return fn.apply(context, [context]);
-  } catch {
-    return exp as T;
-  }
-};
+}
 
-const toFunction = (exp: string): Function => {
-  try {
-    return new Function(`$data`, `with($data){${exp}}`);
-  } catch {
-    return () => { };
-  }
+/**
+ * Execute a code block in a sandboxed vm context.
+ * Supports `return` statements by wrapping in an IIFE.
+ * Throws on compilation or runtime errors.
+ */
+export const execute = <S extends Record<string, unknown>, T = unknown>(code: string, context: S): T => {
+  const wrapped = `(function(){${code}})()`;
+  const script = getOrCompileScript(wrapped);
+  if (!script) throw new SyntaxError(`Failed to compile: ${code.slice(0, 80)}`);
+
+  return script.runInNewContext(buildSandbox(context), { timeout: 200 }) as T;
 };
 
-// 清理 evalCache（用于内存调试）
 export function clearEvalCache(): void {
-  Object.keys(evalCache).forEach(key => {
-    delete evalCache[key];
-  });
-  evalCacheKeys.length = 0;
+  scriptCache.clear();
 }
 
-// 获取 evalCache 统计信息（用于内存调试）
 export function getEvalCacheStats(): { size: number; maxSize: number } {
   return {
-    size: evalCacheKeys.length,
-    maxSize: MAX_EVAL_CACHE_SIZE
+    size: scriptCache.size,
+    maxSize: MAX_EVAL_CACHE_SIZE,
   };
 }
 export function compiler(template: string, ctx: Dict) {
   const matched = [...template.matchAll(/\${([^}]*?)}/g)];
   for (const item of matched) {
     const tpl = item[1];
-    let value = getValueWithRuntime(tpl, ctx);
-    if (value === tpl) continue;
-    if (typeof value !== "string") value = JSON.stringify(value, null, 2);
+    const raw = getValueWithRuntime(tpl, ctx);
+    const value = typeof raw === 'string' ? raw : (raw == null ? 'undefined' : JSON.stringify(raw, null, 2));
     template = template.replace(`\${${item[1]}}`, value);
   }
   return template;
@@ -394,14 +404,15 @@ export namespace Time {
 
   export function parseDate(date: string) {
     const parsed = parseTime(date);
+    let dateInput: string | number = date;
     if (parsed) {
-      date = (Date.now() + parsed) as any;
+      dateInput = Date.now() + parsed;
     } else if (/^\d{1,2}(:\d{1,2}){1,2}$/.test(date)) {
-      date = `${new Date().toLocaleDateString()}-${date}`;
+      dateInput = `${new Date().toLocaleDateString()}-${date}`;
     } else if (/^\d{1,2}-\d{1,2}-\d{1,2}(:\d{1,2}){1,2}$/.test(date)) {
-      date = `${new Date().getFullYear()}-${date}`;
+      dateInput = `${new Date().getFullYear()}-${date}`;
     }
-    return date ? new Date(date) : new Date();
+    return dateInput ? new Date(dateInput) : new Date();
   }
 
   export function formatTimeShort(ms: number) {

package/tests/ai/setup.ts

@@ -8,7 +8,7 @@
  */
 import { vi } from 'vitest';
 import type { Message, MessageElement, Tool, ToolContext } from '@zhin.js/core';
-import type { AIConfig, AIProviderConfig, ChatMessage } from '../../src/ai/types.js';
+import type { AIConfig, ChatMessage } from '@zhin.js/core';
 
 // ============================================================================
 // Logger Mock
@@ -226,7 +226,7 @@ export const createMockAIConfig = (overrides: Partial<AIConfig> = {}): AIConfig
   defaultProvider: 'mock',
   sessions: {
     maxHistory: 10,
-    timeout: 300000,
+    expireMs: 300000,
   },
   context: {
     enabled: false,

package/tests/utils.test.ts

@@ -140,9 +140,7 @@ describe('evaluate and execute', () => {
   })
 
   it('should handle invalid expressions gracefully', () => {
-    const result = execute('invalid syntax here !!!', {})
-    // 无效表达式会被 try-catch 捕获，返回 undefined
-    expect(result).toBeUndefined()
+    expect(() => execute('invalid syntax here !!!', {})).toThrow()
   })
 
   it('should provide safe process context', () => {