@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/types.ts

@@ -0,0 +1,531 @@
+/**
+ * AI Chat Core 类型定义
+ */
+
+import type { McpServerConfig } from './mcp/types';
+import { 
+  getVisibleModels, 
+  getModelFamily,
+  getModelEntry,
+  modelSupportsThinking,
+  modelSupportsVision,
+  modelSupportsNativeSearch,
+  getModelSearchStrategy,
+  type ModelRegistryEntry,
+} from './providers/model-registry';
+import type { ProviderType } from './router';
+
+// ==================== 模式与模型 ====================
+
+/** 对话模式 */
+export type ChatMode = 'agent' | 'ask';
+
+// 重新导出 router 和 Model Registry 类型
+export type { ProviderType };
+export type { ModelFamilyId, ModelFamilyConfig, ModelRegistryEntry } from './providers/model-registry';
+export { getModelFamily, getModelEntry, modelSupportsThinking, modelSupportsNativeSearch, getModelSearchStrategy };
+
+/** 模型选项（前端显示用） */
+export interface ModelOption {
+  /** 模型 ID（发送给 API） */
+  modelId: string;
+  /** 显示名称 */
+  displayName: string;
+  /** 是否支持深度思考 */
+  supportsThinking: boolean;
+  /** 是否支持图片理解 */
+  supportsVision: boolean;
+  /** 用于模型项 hover 的特性描述（由后端定义，前端只渲染） */
+  tooltip?: {
+    features?: string[];
+    /** 开销信息（数组，分行显示） */
+    cost?: string[];
+    description?: string;
+  };
+}
+
+/** 生成模型 tooltip 的 features 列表 */
+function buildModelFeatures(entry: ModelRegistryEntry): string[] {
+  const family = getModelFamily(entry.id);
+  const supportsVision = modelSupportsVision(entry.id);
+  const supportsThinking = family?.supportsThinking ?? false;
+  const supportsNativeSearch = family?.supportsNativeSearch ?? false;
+  
+  const features: string[] = [];
+  // 顺序：多模态 > 深度思考 > 长上下文 > 联网搜索
+  if (supportsVision) features.push('多模态');
+  if (supportsThinking) features.push('深度思考');
+  if (entry.contextWindow) features.push(`长上下文（${entry.contextWindow}）`);
+  if (supportsNativeSearch) features.push('联网搜索');
+  
+  return features;
+}
+
+/**
+ * 预定义模型列表
+ */
+export const MODELS: ModelOption[] = getVisibleModels().map(entry => {
+  const family = getModelFamily(entry.id);
+  const supportsThinking = family?.supportsThinking ?? false;
+  const supportsVision = modelSupportsVision(entry.id);
+
+  return {
+    modelId: entry.id,
+    displayName: entry.displayName,
+    supportsThinking,
+    supportsVision,
+    tooltip: {
+      features: buildModelFeatures(entry),
+      cost: entry.pricing,
+    },
+  };
+});
+
+/** 根据 modelId 获取模型 */
+export function getModelByModelId(modelId: string): ModelOption | undefined {
+  return MODELS.find(m => m.modelId === modelId);
+}
+
+// ==================== 配置 ====================
+
+/** 工具批准回调函数 */
+export type ToolApprovalCallback = (toolCall: {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}) => Promise<boolean>;
+
+/** Agent 配置 */
+export interface AgentConfig {
+  /** 豆包/火山引擎 API Key (用于豆包和 DeepSeek) */
+  arkApiKey: string;
+  /** 豆包 API URL */
+  arkApiUrl?: string;
+  /** 通义千问 API Key */
+  qwenApiKey?: string;
+  /** 通义千问 API URL */
+  qwenApiUrl?: string;
+  /** OpenRouter API Key */
+  openrouterApiKey?: string;
+  /** OpenRouter API URL */
+  openrouterApiUrl?: string;
+  /** Vercel API Key（用于 Vercel AI Gateway 访问 Claude） */
+  vercelApiKey?: string;
+  /** Tavily API Key（用于统一 Web Search） */
+  tavilyApiKey?: string;
+  /** Gemini API Key (用于图片/视频，注意：中国大陆无法直接访问) */
+  geminiApiKey: string;
+  /** 当前工作目录（Current Working Directory） */
+  cwd?: string;
+  /** 
+   * 工具列表（Vite 插件风格）
+   * 
+   * 支持多种形式：
+   * - 单个工具：getCwdTool
+   * - 工具插件：searchPlugin({ dataDir, workspace })
+   * - Promise：await asyncPlugin()
+   * 
+   * @example
+   * ```typescript
+   * tools: [
+   *   getCwdTool,
+   *   executeCommandTool,
+   *   searchPlugin({ dataDir: '/path', workspace: '/project' }),
+   * ]
+   * ```
+   */
+  tools?: ToolConfigItem[];
+  /** 
+   * 工具批准回调（manual 模式使用）
+   * 返回 true 表示批准执行，false 表示跳过
+   */
+  onToolApprovalRequest?: ToolApprovalCallback;
+  /**
+   * 动态获取自动运行配置回调
+   * 每次检查工具批准时调用，获取最新配置
+   */
+  getAutoRunConfig?: () => Promise<AutoRunConfig | undefined>;
+  /**
+   * MCP Server 配置列表
+   * 
+   * 初始化时自动连接所有 MCP Server，发现工具并注册到 Agent。
+   * 
+   * @example
+   * ```typescript
+   * mcpServers: [
+   *   { name: 'filesystem', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/Users/me'] },
+   *   { name: 'github', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
+   *   { name: 'remote-db', transport: 'sse', url: 'http://localhost:3001/mcp' },
+   * ]
+   * ```
+   */
+  mcpServers?: McpServerConfig[];
+}
+
+/** 深度思考模式 */
+export type ThinkingMode = 'enabled' | 'disabled';
+
+/** 自动运行模式 */
+export type AutoRunMode = 'run-everything' | 'manual';
+
+/** 自动运行配置 */
+export interface AutoRunConfig {
+  /** 
+   * 自动运行模式
+   * - 'run-everything': 运行所有内容（自动执行）
+   * - 'manual': 手动批准（每次执行前询问）
+   */
+  mode?: AutoRunMode;
+}
+
+/** 聊天消息格式（用于传递历史） */
+export interface ChatHistoryMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+}
+
+/**
+ * 用户工具定义（透传模式）
+ * 
+ * 只包含 schema，不包含 execute 函数
+ * 由客户端执行，服务端透传 tool_call_request 事件
+ */
+export interface UserToolDefinition {
+  /** 工具名称 */
+  name: string;
+  /** 工具描述（供 AI 理解） */
+  description: string;
+  /** 参数定义（JSON Schema，支持嵌套） */
+  parameters: JsonSchemaObject;
+}
+
+/** 聊天配置（每次聊天可变的选项） */
+export interface ChatOptions {
+  /** 对话模式 */
+  mode?: ChatMode;
+  /** 使用的模型 */
+  model?: string;
+  /** 模型提供商 */
+  provider?: ProviderType;
+  /** 是否启用联网搜索 */
+  enableWebSearch?: boolean;
+  /** 
+   * 深度思考模式
+   * - 'enabled': 强制开启深度思考
+   * - 'disabled': 强制关闭深度思考
+   */
+  thinkingMode?: ThinkingMode;
+  /** 启用的工具名称列表（agent 模式有效，ask 模式强制禁用） */
+  enabledTools?: string[];
+  /** 自动运行配置 */
+  autoRunConfig?: AutoRunConfig;
+  /** 对话历史（从数据库加载，无状态架构） */
+  history?: ChatHistoryMessage[];
+  /**
+   * 用户自定义工具（透传模式）
+   * 
+   * 这些工具不在服务端执行，而是：
+   * 1. 传递给 AI 模型
+   * 2. AI 返回 tool_call 时，发送 tool_call_request 事件给客户端
+   * 3. 客户端执行后，发新请求继续对话
+   */
+  userTools?: UserToolDefinition[];
+  /**
+   * 上次请求的计划快照（可选，仅用于断点续传）
+   * 
+   * 正常流程不需要传：AI 会在单次请求内自主创建和管理计划。
+   * 
+   * 仅在请求被中断后需要恢复时使用：
+   * - 客户端工具透传模式（请求中断，等客户端执行后重新发请求）
+   * - 用户 abort 后想继续
+   */
+  /**
+   * Skills 内容（启用的 Skills 的 content 数组，由前端/服务端拼好传入）
+   * 
+   * 自动注入到 system prompt 的【用户指令】段落。
+   * 前端合并「默认启用的 skills + @ 手动选的 skills」后传入。
+   */
+  skillContents?: string[];
+  // 注意：每个 provider 内部使用自己的最优参数
+  // - ARK: reasoning.effort = 'high'
+  // - Qwen: thinking_budget = 38400
+  // - Gemini: thinkingLevel = 'high'
+  // 外部只需关心 thinkingMode 开关即可
+}
+
+// ==================== 工具相关 ====================
+
+/**
+ * 副作用定义（参考 REST API 规范）
+ * 
+ * @example
+ * // 通知
+ * { type: 'notification', success: true, message: '图片生成完成' }
+ * 
+ * // 文件系统变更
+ * { type: 'filesystem', success: true, data: { paths: ['/path/to/file'] } }
+ * 
+ * // 失败
+ * { type: 'notification', success: false, message: 'API 超时' }
+ */
+export interface SideEffect {
+  /** 副作用类型 */
+  type: string;
+  /** 是否成功 */
+  success: boolean;
+  /** 附加数据 */
+  data?: unknown;
+  /** 消息（成功时为提示，失败时为错误信息） */
+  message?: string;
+}
+
+/**
+ * 工具执行结果（支持动态副作用）
+ * 
+ * 工具可以返回此类型来动态声明副作用
+ */
+export interface ToolResult {
+  /** 执行结果（字符串） */
+  result: string;
+  /** 动态副作用（覆盖静态声明） */
+  sideEffects?: SideEffect[];
+}
+
+/** 工具执行上下文 */
+export interface ToolContext {
+  /** 当前工作目录（Current Working Directory） */
+  cwd: string;
+  /** Gemini 客户端（供多模态工具使用） */
+  geminiClient?: unknown;
+  /** 执行 Shell 命令（内置方法） */
+  executeCommand: (
+    command: string,
+    cwd?: string
+  ) => Promise<{ success: boolean; output?: string; error?: string }>;
+  /** 中断信号（用于取消长时间操作） */
+  signal?: AbortSignal;
+}
+
+/** JSON Schema 属性定义（支持嵌套，符合 JSON Schema 规范） */
+export interface JsonSchemaProperty {
+  type?: string;
+  description?: string;
+  enum?: unknown[];
+  items?: JsonSchemaProperty;
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  default?: unknown;
+}
+
+/** JSON Schema 对象类型（工具参数的根类型） */
+export interface JsonSchemaObject {
+  type: 'object';
+  properties: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  description?: string;
+}
+
+/** 
+ * 工具接口（用户可实现此接口创建自定义工具）
+ * 
+ * 示例：
+ * ```typescript
+ * const myTool: Tool = {
+ *   name: 'my_tool',
+ *   description: '我的自定义工具',
+ *   parameters: { type: 'object', properties: {}, required: [] },
+ *   sideEffects: ['filesystem'], // 声明副作用
+ *   resultType: 'my_result',     // 结果类型（用于前端渲染）
+ *   execute: async (args, ctx) => '执行结果'
+ * };
+ * ```
+ */
+export interface Tool {
+  /** 工具名称 */
+  name: string;
+  /** 工具描述（供 AI 理解） */
+  description: string;
+  /** 参数定义（JSON Schema，支持嵌套对象和数组） */
+  parameters: JsonSchemaObject;
+  /** 
+   * 静态副作用声明（可选）
+   * 
+   * 用于通知前端该工具执行后可能产生的副作用
+   * 
+   * @example
+   * sideEffects: [{ type: 'notification', message: '图片生成完成', level: 'success' }]
+   * 
+   * 注意：如果 execute 返回 ToolResult 带有 sideEffects，会覆盖此静态声明
+   */
+  sideEffects?: SideEffect[];
+  /**
+   * 结果类型（用于前端渲染）
+   * 
+   * 当工具执行成功时，前端会根据此类型生成对应的 ContentPart
+   * 例如：resultType: 'weather' 会生成 { type: 'weather', ...result }
+   * 
+   * 如果不指定，工具结果仅显示在 ToolCallPart 的折叠面板中
+   */
+  resultType?: string;
+  /** 
+   * 执行函数
+   * 
+   * 返回值：
+   * - string: 简单返回结果，使用静态 sideEffects
+   * - ToolResult: 带动态副作用的结果，覆盖静态 sideEffects
+   */
+  execute: (args: Record<string, unknown>, context: ToolContext) => Promise<string | ToolResult>;
+}
+
+/** 工具执行器接口（可由使用方实现，用于自定义命令执行环境） */
+export interface ToolExecutor {
+  /** 执行 Shell 命令 */
+  executeCommand(
+    command: string,
+    cwd?: string,
+    signal?: AbortSignal,
+    hooks?: {
+      onStdout?: (chunk: string) => void;
+      onStderr?: (chunk: string) => void;
+    }
+  ): Promise<{ success: boolean; output?: string; error?: string }>;
+}
+
+// ==================== 工具插件（Vite 插件风格） ====================
+
+/**
+ * 工具插件实例
+ * 
+ * 由 createXxxPlugin() 返回，可直接在 tools 数组中展开使用
+ */
+export interface ToolPlugin {
+  /** 插件提供的工具数组 */
+  tools: Tool[];
+  /** 插件控制方法（可选，由各插件自定义） */
+  [key: string]: unknown;
+}
+
+/**
+ * 创建单个工具插件（辅助函数）
+ * 
+ * @example
+ * ```typescript
+ * export function getCwdTool(): ToolPlugin {
+ *   return tool({
+ *     name: 'get_cwd',
+ *     description: '...',
+ *     parameters: { ... },
+ *     execute: async (args, context) => { ... }
+ *   });
+ * }
+ * ```
+ */
+export function tool(t: Tool): ToolPlugin {
+  return { tools: [t] };
+}
+
+/**
+ * 创建多个工具插件（辅助函数）
+ * 
+ * @example
+ * ```typescript
+ * export function myPlugin(): ToolPlugin {
+ *   return tools([
+ *     { name: 'tool1', ... },
+ *     { name: 'tool2', ... },
+ *   ]);
+ * }
+ * ```
+ */
+export function tools(ts: Tool[]): ToolPlugin {
+  return { tools: ts };
+}
+
+/**
+ * 工具配置项（Vite 插件风格，只支持插件形式）
+ * 
+ * @example
+ * ```typescript
+ * tools: [
+ *   getCwdTool(),                          // 工具插件（函数调用）
+ *   searchPlugin({ dataDir, workspace }), // 异步插件（返回 Promise<ToolPlugin>）
+ * ]
+ * ```
+ */
+export type ToolConfigItem = Tool | ToolPlugin | Promise<Tool | ToolPlugin>;
+
+/**
+ * 解析工具配置，统一转换为 Tool[]
+ * 
+ * 支持三种形式：
+ * - Tool: 单个工具（直接使用）
+ * - ToolPlugin: 工具插件（展开 .tools 数组）
+ * - Promise<Tool | ToolPlugin>: 异步工具/插件
+ */
+export async function resolveTools(items: ToolConfigItem[]): Promise<Tool[]> {
+  const tools: Tool[] = [];
+  
+  for (const item of items) {
+    const resolved = await item;
+    
+    if ('tools' in resolved && Array.isArray(resolved.tools)) {
+      // ToolPlugin
+      tools.push(...resolved.tools);
+    } else if ('name' in resolved && 'execute' in resolved) {
+      // Tool
+      tools.push(resolved as Tool);
+    } else {
+      console.warn('无法识别的工具配置项:', resolved);
+    }
+  }
+  
+  return tools;
+}
+
+/** 工具定义（OpenAI 格式，内部使用） */
+export interface ToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: JsonSchemaObject;
+  };
+}
+
+// ==================== 消息相关 ====================
+
+/** 聊天消息（内部格式） */
+export interface ChatMessage {
+  /** 消息 ID */
+  id?: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  /** 深度思考内容 */
+  reasoning_content?: string;
+  tool_call_id?: string;
+  tool_calls?: Array<{
+    id: string;
+    type: 'function';
+    function: {
+      name: string;
+      arguments: string;
+    };
+    /** Gemini 模型需要的 thought_signature（用于工具调用循环） */
+    thought_signature?: string;
+  }>;
+}
+
+// ==================== API 特定类型 ====================
+
+/** 火山引擎 Responses API 工具定义 */
+export interface ResponsesApiTool {
+  type: 'function' | 'web_search';
+  // Function 类型
+  name?: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+  // Web Search 类型
+  max_keyword?: number;
+  limit?: number;
+  sources?: string[];
+}

package/src/utils.ts

@@ -0,0 +1,86 @@
+/**
+ * 调试日志工具
+ * 
+ * 通过 DebugLogger.enable(true) 全局开启，
+ * 通过 DebugLogger.setLogFile(path) 同时写入 JSONL 文件，
+ * 各模块通过 DebugLogger.module('Name') 创建带前缀的 logger。
+ */
+
+import { appendFileSync } from 'node:fs';
+
+let enabled = false;
+let logFilePath: string | null = null;
+
+export class DebugLogger {
+  private prefix: string;
+
+  private constructor(prefix: string) {
+    this.prefix = prefix;
+  }
+
+  /** 全局启停调试日志 */
+  static enable(value: boolean): void {
+    enabled = value;
+  }
+
+  /** 查询是否已启用 */
+  static isEnabled(): boolean {
+    return enabled;
+  }
+
+  /** 设置日志文件路径（JSONL 格式，追加写入） */
+  static setLogFile(filePath: string): void {
+    logFilePath = filePath;
+  }
+
+  /** 创建模块专用 logger */
+  static module(name: string): DebugLogger {
+    return new DebugLogger(`[${name}]`);
+  }
+
+  debug(...args: unknown[]): void {
+    if (enabled) {
+      console.debug(this.prefix, ...args);
+      this.writeToFile('debug', args);
+    }
+  }
+
+  info(...args: unknown[]): void {
+    if (enabled) {
+      console.info(this.prefix, ...args);
+      this.writeToFile('info', args);
+    }
+  }
+
+  warn(...args: unknown[]): void {
+    if (enabled) {
+      console.warn(this.prefix, ...args);
+      this.writeToFile('warn', args);
+    }
+  }
+
+  error(...args: unknown[]): void {
+    if (enabled) {
+      console.error(this.prefix, ...args);
+      this.writeToFile('error', args);
+    }
+  }
+
+  private writeToFile(level: string, args: unknown[]): void {
+    if (!logFilePath) return;
+    try {
+      const entry = JSON.stringify({
+        t: Date.now(),
+        level,
+        module: this.prefix,
+        args: args.map(a => {
+          try { return typeof a === 'string' ? a : JSON.parse(JSON.stringify(a)); }
+          catch { return String(a); }
+        }),
+      });
+      appendFileSync(logFilePath, entry + '\n');
+    } catch {
+      // 写文件失败不影响主流程
+    }
+  }
+}