@zhin.js/core 1.0.37 → 1.0.38

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', () => {

package/lib/ai/agent.d.ts

@@ -1,130 +0,0 @@
-/**
- * @zhin.js/ai - Agent System
- * AI Agent 实现，支持工具调用和多轮对话
- */
-import type { AIProvider, AgentConfig, AgentTool, AgentResult, ChatMessage, ToolFilterOptions, Usage } from './types.js';
-/**
- * 根据工具名和参数生成简短标题（用于日志、TOOLS.md 等）
- */
-export declare function formatToolTitle(name: string, args?: Record<string, any>): string;
-/**
- * Agent 执行状态
- */
-export interface AgentState {
-    messages: ChatMessage[];
-    toolCalls: {
-        tool: string;
-        args: Record<string, any>;
-        result: any;
-    }[];
-    usage: Usage;
-    iterations: number;
-}
-/**
- * Agent 事件
- */
-export interface AgentEvents {
-    'thinking': (message: string) => void;
-    'tool_call': (tool: string, args: Record<string, any>) => void;
-    'tool_result': (tool: string, result: any) => void;
-    'streaming': (content: string) => void;
-    'complete': (result: AgentResult) => void;
-    'error': (error: Error) => void;
-}
-/**
- * AI Agent 类
- * 支持工具调用、多轮对话、流式输出
- */
-export declare class Agent {
-    private provider;
-    private config;
-    private tools;
-    private eventHandlers;
-    constructor(provider: AIProvider, config: AgentConfig);
-    /**
-     * 默认系统提示词
-     */
-    private getDefaultSystemPrompt;
-    /**
-     * 注册事件处理器
-     */
-    on<K extends keyof AgentEvents>(event: K, handler: AgentEvents[K]): () => void;
-    /**
-     * 触发事件
-     */
-    private emit;
-    /**
-     * 添加工具
-     */
-    addTool(tool: AgentTool): void;
-    /**
-     * 移除工具
-     */
-    removeTool(name: string): void;
-    /**
-     * 获取工具定义（缓存在第一次调用后保持不变）
-     */
-    private getToolDefinitions;
-    /**
-     * 生成工具调用的去重 key（规范化参数以避免 "" vs "{}" 等差异）
-     */
-    private static toolCallKey;
-    /**
-     * 安全解析 JSON，失败则返回原始字符串
-     */
-    private static safeParse;
-    /**
-     * 程序化工具过滤 —— 替代 AI 意图分析的高效方案
-     *
-     * 评分规则（按权重从高到低）：
-     * 1. keywords 精确匹配: +1.0 per hit   —— 工具声明的触发关键词
-     * 2. tags 匹配:          +0.5 per hit   —— 工具分类标签
-     * 3. 工具名 token 匹配:  +0.3 per hit   —— 工具名按 `.` `_` `-` 拆词
-     * 4. description 关键词:  +0.15 per hit  —— 描述中的词/短语
-     *
-     * 权限过滤发生在评分之前，直接跳过无权使用的工具。
-     *
-     * @param message      用户消息原文
-     * @param tools        候选工具列表
-     * @param options      过滤选项
-     * @returns            按相关性降序排列的工具子集
-     */
-    static filterTools(message: string, tools: AgentTool[], options?: ToolFilterOptions): AgentTool[];
-    /**
-     * 执行单个工具调用（带超时保护）
-     */
-    private executeToolCall;
-    /**
-     * 并行执行多个工具调用（跳过重复的）
-     * @returns 新执行的工具调用结果列表；如果全部重复则返回空数组
-     */
-    private executeToolCalls;
-    /**
-     * 累加 token 用量
-     */
-    private static addUsage;
-    /**
-     * 运行 Agent
-     *
-     * @param userMessage    用户消息
-     * @param context        对话上下文
-     * @param filterOptions  工具过滤选项 —— 启用后在 AI 调用之前程序化筛选工具，省去额外的 AI 意图分析往返
-     */
-    run(userMessage: string, context?: ChatMessage[], filterOptions?: ToolFilterOptions): Promise<AgentResult>;
-    /**
-     * 流式运行 Agent
-     *
-     * @param userMessage    用户消息
-     * @param context        对话上下文
-     * @param filterOptions  工具过滤选项 —— 启用后在 AI 调用之前程序化筛选工具
-     */
-    runStream(userMessage: string, context?: ChatMessage[], filterOptions?: ToolFilterOptions): AsyncIterable<{
-        type: 'content' | 'tool_call' | 'tool_result' | 'done';
-        data: any;
-    }>;
-}
-/**
- * 创建 Agent 实例
- */
-export declare function createAgent(provider: AIProvider, config: Omit<AgentConfig, 'provider'>): Agent;
-//# sourceMappingURL=agent.d.ts.map

package/lib/ai/agent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/ai/agent.ts"],"names":[],"mappings":"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"}