@zhin.js/core 1.0.25 → 1.0.27

package/src/ai/tools.ts

@@ -0,0 +1,218 @@
+/**
+ * @zhin.js/ai - Built-in Tools
+ * 内置工具集合 - 使用 ZhinTool 类定义
+ */
+
+import { ZhinTool } from '../built/tool.js';
+import type { Tool } from '../types.js';
+
+/**
+ * 计算器工具
+ * 支持基本运算和数学函数
+ */
+export const calculatorTool = new ZhinTool('calculator')
+  .desc('执行数学计算。支持基本运算（+、-、*、/、^）和数学函数（sin、cos、sqrt 等）')
+  .keyword('计算', '算', 'calc', '数学', '求值', '运算')
+  .tag('math', 'utility')
+  .param('expression', { type: 'string', description: '数学表达式，例如 "2 + 3 * 4" 或 "sqrt(16)"' }, true)
+  .execute(async ({ expression }) => {
+    try {
+      // 安全的数学表达式求值
+      const sanitized = (expression as string)
+        .replace(/[^0-9+\-*/().^eEsincosqrtabspowlogxMathPI\s]/g, '')
+        .replace(/\bsqrt\b/g, 'Math.sqrt')
+        .replace(/\bsin\b/g, 'Math.sin')
+        .replace(/\bcos\b/g, 'Math.cos')
+        .replace(/\btan\b/g, 'Math.tan')
+        .replace(/\blog\b/g, 'Math.log')
+        .replace(/\babs\b/g, 'Math.abs')
+        .replace(/\bpow\b/g, 'Math.pow')
+        .replace(/\bPI\b/g, 'Math.PI')
+        .replace(/\bE\b(?![0-9])/g, 'Math.E')
+        .replace(/\^/g, '**');
+
+      const result = new Function(`return ${sanitized}`)();
+      return { result, expression };
+    } catch (error) {
+      return { error: '无法计算表达式', expression };
+    }
+  });
+
+/**
+ * 时间工具
+ * 获取当前时间和日期
+ */
+export const timeTool = new ZhinTool('get_time')
+  .desc('获取当前时间和日期信息')
+  .keyword('时间', '日期', '几点', '今天', '现在', 'time', 'date')
+  .tag('time', 'utility')
+  .param('timezone', { type: 'string', description: '时区，例如 "Asia/Shanghai" 或 "UTC"' })
+  .param('format', { type: 'string', description: '输出格式: full(完整), date(日期), time(时间), timestamp(时间戳)' })
+  .execute(async ({ timezone, format = 'full' }) => {
+    const now = new Date();
+    const options: Intl.DateTimeFormatOptions = {
+      timeZone: (timezone as string) || 'Asia/Shanghai',
+    };
+
+    switch (format) {
+      case 'date':
+        options.dateStyle = 'full';
+        break;
+      case 'time':
+        options.timeStyle = 'long';
+        break;
+      case 'timestamp':
+        return { timestamp: now.getTime(), iso: now.toISOString() };
+      default:
+        options.dateStyle = 'full';
+        options.timeStyle = 'long';
+    }
+
+    return {
+      formatted: now.toLocaleString('zh-CN', options),
+      timestamp: now.getTime(),
+      iso: now.toISOString(),
+    };
+  });
+
+/**
+ * 网页搜索工具
+ * 需要配置搜索 API
+ */
+export const searchTool = new ZhinTool('web_search')
+  .desc('在互联网上搜索信息（需要配置搜索 API）')
+  .keyword('搜索', '搜一下', '查找', '查一查', 'search', 'google')
+  .tag('search', 'web')
+  .param('query', { type: 'string', description: '搜索关键词' }, true)
+  .param('limit', { type: 'number', description: '返回结果数量（默认 5）' })
+  .execute(async ({ query, limit = 5 }) => {
+    // 默认实现提示需要配置
+    return {
+      query,
+      error: '搜索功能未配置，请提供搜索 API',
+      hint: '可以集成 SerpAPI、Bing Search API 或 Google Custom Search',
+    };
+  });
+
+/**
+ * 代码执行工具
+ * 在安全沙箱中执行 JavaScript
+ */
+export const codeRunnerTool = new ZhinTool('run_code')
+  .desc('执行 JavaScript 代码（在安全沙箱中）')
+  .keyword('代码', '执行', '运行', 'code', 'js', 'javascript')
+  .tag('code', 'dev')
+  .param('code', { type: 'string', description: 'JavaScript 代码' }, true)
+  .execute(async ({ code }) => {
+    try {
+      // 简单的沙箱执行（生产环境应使用 vm2 或 isolated-vm）
+      const result = new Function(`
+        'use strict';
+        const console = { log: (...args) => args.join(' ') };
+        return (function() { ${code} })();
+      `)();
+      
+      return {
+        success: true,
+        result: result !== undefined ? String(result) : 'undefined',
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+
+/**
+ * HTTP 请求工具
+ * 发送 HTTP 请求获取数据
+ */
+export const httpTool = new ZhinTool('http_request')
+  .desc('发送 HTTP 请求获取数据')
+  .keyword('http', 'api', '请求', '接口', 'url', 'fetch')
+  .tag('http', 'web')
+  .param('url', { type: 'string', description: '请求 URL' }, true)
+  .param('method', { type: 'string', description: 'HTTP 方法: GET, POST, PUT, DELETE（默认 GET）' })
+  .param('headers', { type: 'object', description: '请求头（JSON 对象）' })
+  .param('body', { type: 'string', description: '请求体（JSON 字符串）' })
+  .execute(async ({ url, method = 'GET', headers = {}, body }) => {
+    try {
+      const response = await fetch(url as string, {
+        method: method as string,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(headers as Record<string, string>),
+        },
+        body: body ? (body as string) : undefined,
+      });
+
+      const contentType = response.headers.get('content-type') || '';
+      let data: any;
+
+      if (contentType.includes('application/json')) {
+        data = await response.json();
+      } else {
+        data = await response.text();
+        // 限制文本长度
+        if (data.length > 5000) {
+          data = data.substring(0, 5000) + '... (truncated)';
+        }
+      }
+
+      return {
+        status: response.status,
+        statusText: response.statusText,
+        data,
+      };
+    } catch (error) {
+      return {
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+
+/**
+ * 记忆工具
+ * 让 AI 记住重要信息
+ */
+export const memoryTool = new ZhinTool('remember')
+  .desc('记住用户告诉你的重要信息，以便后续对话中使用')
+  .keyword('记住', '记忆', '记下', 'remember', '别忘了')
+  .tag('memory', 'context')
+  .param('key', { type: 'string', description: '记忆的标识符，如 "user_name", "preference"' }, true)
+  .param('value', { type: 'string', description: '要记住的内容' }, true)
+  .execute(async ({ key, value }, context) => {
+    // 这里需要与 session/context manager 集成
+    return {
+      success: true,
+      message: `已记住 ${key}: ${value}`,
+      key,
+      value,
+    };
+  });
+
+/**
+ * 获取所有内置工具（ZhinTool 实例）
+ * 注意：天气工具已移除，请使用 weather-tool 插件，支持多平台配置
+ */
+export function getBuiltinTools(): ZhinTool[] {
+  return [
+    calculatorTool,
+    timeTool,
+  ];
+}
+
+/**
+ * 获取所有可用的内置工具（包括可选工具）
+ */
+export function getAllBuiltinTools(): ZhinTool[] {
+  return [
+    calculatorTool,
+    timeTool,
+    searchTool,
+    codeRunnerTool,
+    httpTool,
+    memoryTool,
+  ];
+}

package/src/ai/types.ts

@@ -0,0 +1,296 @@
+/**
+ * @zhin.js/ai - AI Service Types
+ * 统一的 AI 服务类型定义
+ */
+
+// ============================================================================
+// 基础类型
+// ============================================================================
+
+/** 消息角色 */
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool' | 'tool_call' | 'tool_result';
+
+/** 聊天消息 */
+export interface ChatMessage {
+  role: MessageRole;
+  content: string | ContentPart[];
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: ToolCall[];
+}
+
+/** 内容部分（支持多模态） */
+export type ContentPart = 
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string; detail?: 'auto' | 'low' | 'high' } }
+  | { type: 'audio'; audio: { data: string; format: 'wav' | 'mp3' } };
+
+/** 工具调用 */
+export interface ToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+/** 工具定义 */
+export interface ToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+  };
+}
+
+/** JSON Schema */
+export interface JsonSchema {
+  type: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: any[];
+  description?: string;
+  default?: any;
+  [key: string]: any;
+}
+
+// ============================================================================
+// 请求/响应类型
+// ============================================================================
+
+/** 聊天补全请求 */
+export interface ChatCompletionRequest {
+  model: string;
+  messages: ChatMessage[];
+  tools?: ToolDefinition[];
+  tool_choice?: 'auto' | 'none' | 'required' | { type: 'function'; function: { name: string } };
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  stream?: boolean;
+  stop?: string | string[];
+  presence_penalty?: number;
+  frequency_penalty?: number;
+  user?: string;
+  /** 是否启用模型思考（如 qwen3 的 <think> 模式）。设为 false 可跳过思考加速响应。 */
+  think?: boolean;
+}
+
+/** 聊天补全响应 */
+export interface ChatCompletionResponse {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: ChatCompletionChoice[];
+  usage?: Usage;
+}
+
+/** 选择 */
+export interface ChatCompletionChoice {
+  index: number;
+  message: ChatMessage;
+  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+
+/** 用量统计 */
+export interface Usage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+}
+
+// ============================================================================
+// 流式响应类型
+// ============================================================================
+
+/** 流式响应块 */
+export interface ChatCompletionChunk {
+  id: string;
+  object: 'chat.completion.chunk';
+  created: number;
+  model: string;
+  choices: ChatCompletionChunkChoice[];
+  usage?: Usage;
+}
+
+/** 流式选择 */
+export interface ChatCompletionChunkChoice {
+  index: number;
+  delta: Partial<ChatMessage>;
+  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+
+// ============================================================================
+// Provider 类型
+// ============================================================================
+
+/** Provider 配置 */
+export interface ProviderConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  defaultModel?: string;
+  timeout?: number;
+  maxRetries?: number;
+  headers?: Record<string, string>;
+}
+
+/** Provider 接口 */
+export interface AIProvider {
+  name: string;
+  models: string[];
+  
+  /** 聊天补全 */
+  chat(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+  
+  /** 流式聊天补全 */
+  chatStream(request: ChatCompletionRequest): AsyncIterable<ChatCompletionChunk>;
+  
+  /** 列出可用模型 */
+  listModels?(): Promise<string[]>;
+  
+  /** 检查连接 */
+  healthCheck?(): Promise<boolean>;
+}
+
+// ============================================================================
+// Agent 类型
+// ============================================================================
+
+/** Agent 工具 */
+export interface AgentTool {
+  name: string;
+  description: string;
+  parameters: JsonSchema;
+  execute: (args: Record<string, any>) => Promise<any>;
+  /** 工具标签，用于分类和快速匹配 */
+  tags?: string[];
+  /** 触发关键词，用户消息包含这些词时优先选择此工具 */
+  keywords?: string[];
+  /** 所需权限级别 (0=所有人, 1=群管理, 2=群主, 3=Bot管理员, 4=拥有者) */
+  permissionLevel?: number;
+}
+
+/**
+ * 工具过滤选项
+ * 在 Agent.run() / runStream() 中启用程序化工具预过滤，
+ * 省去额外的 AI 意图分析往返
+ */
+export interface ToolFilterOptions {
+  /** 调用者权限级别 (0-4)，高于工具要求才能使用 */
+  callerPermissionLevel?: number;
+  /** 最大返回工具数量 (默认 10) */
+  maxTools?: number;
+  /** 最低相关性得分阈值，低于此分数的工具被过滤掉 (默认 0.1) */
+  minScore?: number;
+}
+
+/** Agent 配置 */
+export interface AgentConfig {
+  provider: string;
+  model?: string;
+  systemPrompt?: string;
+  tools?: AgentTool[];
+  maxIterations?: number;
+  temperature?: number;
+}
+
+/** Agent 运行结果 */
+export interface AgentResult {
+  content: string;
+  toolCalls: {
+    tool: string;
+    args: Record<string, any>;
+    result: any;
+  }[];
+  usage: Usage;
+  iterations: number;
+}
+
+// ============================================================================
+// Session 类型
+// ============================================================================
+
+/** 会话配置 */
+export interface SessionConfig {
+  provider: string;
+  model?: string;
+  systemPrompt?: string;
+  maxHistory?: number;
+  expireMs?: number;
+}
+
+/** 会话 */
+export interface Session {
+  id: string;
+  config: SessionConfig;
+  messages: ChatMessage[];
+  createdAt: number;
+  updatedAt: number;
+  metadata?: Record<string, any>;
+}
+
+// ============================================================================
+// AI Service 配置
+// ============================================================================
+
+/** AI 服务配置 */
+export interface AIConfig {
+  enabled?: boolean;
+  defaultProvider?: string;
+  providers?: {
+    openai?: ProviderConfig;
+    anthropic?: ProviderConfig;
+    deepseek?: ProviderConfig;
+    moonshot?: ProviderConfig;
+    zhipu?: ProviderConfig;
+    ollama?: ProviderConfig & { host?: string; models?: string[] };
+    custom?: ProviderConfig[];
+  };
+  sessions?: {
+    /** 最大历史消息数（数据库模式默认200，内存模式默认100） */
+    maxHistory?: number;
+    /** 会话过期时间（毫秒，数据库模式默认7天，内存模式默认24小时） */
+    expireMs?: number;
+    /** 是否使用数据库持久化存储（默认 true） */
+    useDatabase?: boolean;
+  };
+  context?: {
+    /** 是否启用消息记录（默认 true） */
+    enabled?: boolean;
+    /** 读取的最近消息数量（默认 100） */
+    maxRecentMessages?: number;
+    /** 触发总结的消息数量阈值（默认 50） */
+    summaryThreshold?: number;
+    /** 总结后保留的消息数量（默认 10） */
+    keepAfterSummary?: number;
+    /** 上下文最大 token 估算（默认 4000） */
+    maxContextTokens?: number;
+    /** 自定义总结提示词 */
+    summaryPrompt?: string;
+  };
+  /** AI 触发配置 */
+  trigger?: {
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+    /** 触发前缀列表（默认 ['#', 'AI:']） */
+    prefixes?: string[];
+    /** 是否响应 @ 机器人（默认 true） */
+    respondToAt?: boolean;
+    /** 是否响应私聊（默认 true） */
+    respondToPrivate?: boolean;
+    /** 触发关键词（可选） */
+    keywords?: string[];
+    /** 忽略的前缀（命令前缀，避免与命令冲突，默认 ['/', '!', '！']） */
+    ignorePrefixes?: string[];
+    /** 超时时间（毫秒，默认 60000） */
+    timeout?: number;
+    /** 思考中提示语（可选，设置后会在处理前发送） */
+    thinkingMessage?: string;
+    /** 错误提示模板（默认 '❌ AI 处理失败: {error}'） */
+    errorTemplate?: string;
+  };
+}

package/src/ai/user-profile.ts

@@ -0,0 +1,181 @@
+/**
+ * UserProfileStore — 用户画像存储
+ *
+ * 持久化存储用户偏好和特征，让 AI 跨会话记住用户的个性化信息。
+ *
+ *   ai_user_profiles 表：
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │ user_id  | key          | value         | updated_at     │
+ *   │ u1       | name         | 小明          | 1700000000     │
+ *   │ u1       | style        | 简洁正式      | 1700000001     │
+ *   │ u1       | interests    | 编程,天气     | 1700000010     │
+ *   └──────────────────────────────────────────────────────────┘
+ */
+
+import { Logger } from '@zhin.js/logger';
+
+const logger = new Logger(null, 'UserProfile');
+
+// ============================================================================
+// 数据库模型
+// ============================================================================
+
+export const AI_USER_PROFILE_MODEL = {
+  user_id: { type: 'text' as const, nullable: false },
+  key: { type: 'text' as const, nullable: false },
+  value: { type: 'text' as const, nullable: false },
+  updated_at: { type: 'integer' as const, default: 0 },
+};
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+interface ProfileRecord {
+  id?: number;
+  user_id: string;
+  key: string;
+  value: string;
+  updated_at: number;
+}
+
+/**
+ * 数据库模型接口（与 RelatedModel 的链式查询 API 对齐）
+ */
+interface DbModel {
+  select(...fields: string[]): any;  // 返回 Selection (thenable, 支持 .where())
+  create(data: Record<string, any>): Promise<any>;
+  update(data: Partial<any>): any;   // 返回 Updation (thenable, 支持 .where())
+  delete(condition: Record<string, any>): any; // 返回 Deletion (thenable, 支持 .where())
+}
+
+// ============================================================================
+// Store 接口
+// ============================================================================
+
+interface IProfileStore {
+  get(userId: string, key: string): Promise<string | null>;
+  getAll(userId: string): Promise<Record<string, string>>;
+  set(userId: string, key: string, value: string): Promise<void>;
+  delete(userId: string, key: string): Promise<boolean>;
+  dispose(): void;
+}
+
+// ============================================================================
+// 内存实现
+// ============================================================================
+
+class MemoryProfileStore implements IProfileStore {
+  private data: Map<string, Map<string, string>> = new Map();
+
+  async get(userId: string, key: string): Promise<string | null> {
+    return this.data.get(userId)?.get(key) ?? null;
+  }
+
+  async getAll(userId: string): Promise<Record<string, string>> {
+    const map = this.data.get(userId);
+    if (!map) return {};
+    return Object.fromEntries(map);
+  }
+
+  async set(userId: string, key: string, value: string): Promise<void> {
+    let map = this.data.get(userId);
+    if (!map) { map = new Map(); this.data.set(userId, map); }
+    map.set(key, value);
+  }
+
+  async delete(userId: string, key: string): Promise<boolean> {
+    return this.data.get(userId)?.delete(key) ?? false;
+  }
+
+  dispose(): void { this.data.clear(); }
+}
+
+// ============================================================================
+// 数据库实现
+// ============================================================================
+
+class DatabaseProfileStore implements IProfileStore {
+  constructor(private model: DbModel) {}
+
+  async get(userId: string, key: string): Promise<string | null> {
+    const records = await this.model.select().where({ user_id: userId, key }) as ProfileRecord[];
+    return records.length > 0 ? records[0].value : null;
+  }
+
+  async getAll(userId: string): Promise<Record<string, string>> {
+    const records = await this.model.select().where({ user_id: userId }) as ProfileRecord[];
+    const result: Record<string, string> = {};
+    for (const r of records) result[r.key] = r.value;
+    return result;
+  }
+
+  async set(userId: string, key: string, value: string): Promise<void> {
+    const existing = await this.model.select().where({ user_id: userId, key });
+    if (existing.length > 0) {
+      await this.model.update({ value, updated_at: Date.now() }).where({ user_id: userId, key });
+    } else {
+      await this.model.create({ user_id: userId, key, value, updated_at: Date.now() });
+    }
+  }
+
+  async delete(userId: string, key: string): Promise<boolean> {
+    const existing = await this.model.select().where({ user_id: userId, key });
+    if (existing.length === 0) return false;
+    await this.model.delete({ user_id: userId, key });
+    return true;
+  }
+
+  dispose(): void {}
+}
+
+// ============================================================================
+// UserProfileStore
+// ============================================================================
+
+export class UserProfileStore {
+  private store: IProfileStore;
+
+  constructor() {
+    this.store = new MemoryProfileStore();
+  }
+
+  upgradeToDatabase(model: DbModel): void {
+    const old = this.store;
+    this.store = new DatabaseProfileStore(model);
+    old.dispose();
+    logger.debug('UserProfileStore: upgraded to database storage');
+  }
+
+  async get(userId: string, key: string): Promise<string | null> {
+    return this.store.get(userId, key);
+  }
+
+  async getAll(userId: string): Promise<Record<string, string>> {
+    return this.store.getAll(userId);
+  }
+
+  async set(userId: string, key: string, value: string): Promise<void> {
+    return this.store.set(userId, key, value);
+  }
+
+  async delete(userId: string, key: string): Promise<boolean> {
+    return this.store.delete(userId, key);
+  }
+
+  /**
+   * 构建用户画像摘要，注入 system prompt
+   */
+  async buildProfileSummary(userId: string): Promise<string> {
+    const profile = await this.store.getAll(userId);
+    const entries = Object.entries(profile);
+    if (entries.length === 0) return '';
+
+    const lines = entries.map(([k, v]) => `- ${k}: ${v}`).join('\n');
+    return `[用户画像]\n${lines}`;
+  }
+
+  dispose(): void {
+    this.store.dispose();
+  }
+}