@zhin.js/ai 0.0.1

package/src/tools.ts

@@ -0,0 +1,205 @@
+/**
+ * @zhin.js/ai - Built-in Tools
+ * 内置工具集合 - 使用 ZhinTool 类定义
+ */
+
+import { ZhinTool, type Tool } from '@zhin.js/core';
+
+/**
+ * 计算器工具
+ * 支持基本运算和数学函数
+ */
+export const calculatorTool = new ZhinTool('calculator')
+  .desc('执行数学计算。支持基本运算（+、-、*、/、^）和数学函数（sin、cos、sqrt 等）')
+  .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('获取当前时间和日期信息')
+  .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）')
+  .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 代码（在安全沙箱中）')
+  .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 请求获取数据')
+  .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('记住用户告诉你的重要信息，以便后续对话中使用')
+  .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/types.ts

@@ -0,0 +1,274 @@
+/**
+ * @zhin.js/ai - AI Service Types
+ * 统一的 AI 服务类型定义
+ */
+
+// ============================================================================
+// 基础类型
+// ============================================================================
+
+/** 消息角色 */
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+/** 聊天消息 */
+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;
+}
+
+/** 聊天补全响应 */
+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>;
+}
+
+/** 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;
+  };
+}