@zhin.js/ai 0.0.2 → 1.0.1

package/src/storage.ts

@@ -0,0 +1,135 @@
+/**
+ * StorageBackend — Unified storage abstraction layer
+ *
+ * Provides a common interface for AI sub-systems (session, context, memory,
+ * user profile, follow-up) to switch between in-memory and database backends
+ * without changing business logic.
+ *
+ * Usage:
+ *   const backend = new MemoryStorageBackend<MyRecord>();
+ *   // ... later, when DB is ready:
+ *   const dbBackend = new DatabaseStorageBackend<MyRecord>(model, { keyField: 'session_id' });
+ *   service.upgradeBackend(dbBackend);
+ */
+
+export interface StorageBackend<T extends Record<string, any>> {
+  get(key: string): Promise<T | null>;
+  set(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list(filter?: Partial<T>): Promise<T[]>;
+  clear(): Promise<void>;
+  readonly type: 'memory' | 'database';
+}
+
+/**
+ * In-memory storage backend.
+ */
+export class MemoryStorageBackend<T extends Record<string, any>> implements StorageBackend<T> {
+  readonly type = 'memory' as const;
+  private data = new Map<string, T>();
+
+  async get(key: string): Promise<T | null> {
+    return this.data.get(key) ?? null;
+  }
+
+  async set(key: string, value: T): Promise<void> {
+    this.data.set(key, value);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.data.delete(key);
+  }
+
+  async list(filter?: Partial<T>): Promise<T[]> {
+    const all = Array.from(this.data.values());
+    if (!filter) return all;
+    return all.filter(item => {
+      for (const [k, v] of Object.entries(filter)) {
+        if (item[k] !== v) return false;
+      }
+      return true;
+    });
+  }
+
+  async clear(): Promise<void> {
+    this.data.clear();
+  }
+}
+
+/**
+ * Database model interface aligned with @zhin.js/database's RelatedModel API.
+ */
+export interface DbModel {
+  select(...fields: string[]): any;
+  create(data: Record<string, any>): Promise<any>;
+  update(data: Partial<any>): any;
+  delete(condition: Record<string, any>): any;
+}
+
+/**
+ * Database-backed storage backend.
+ */
+export class DatabaseStorageBackend<T extends Record<string, any>> implements StorageBackend<T> {
+  readonly type = 'database' as const;
+
+  constructor(
+    private model: DbModel,
+    private options: {
+      /** The field name used as lookup key (e.g. 'session_id', 'user_id') */
+      keyField: string;
+    },
+  ) {}
+
+  async get(key: string): Promise<T | null> {
+    const rows: T[] = await this.model
+      .select()
+      .where({ [this.options.keyField]: key });
+    return rows[0] ?? null;
+  }
+
+  async set(key: string, value: T): Promise<void> {
+    const existing = await this.get(key);
+    if (existing) {
+      await this.model
+        .update(value)
+        .where({ [this.options.keyField]: key });
+    } else {
+      await this.model.create({ ...value, [this.options.keyField]: key });
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    try {
+      await this.model.delete({ [this.options.keyField]: key });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async list(filter?: Partial<T>): Promise<T[]> {
+    if (filter) {
+      return this.model.select().where(filter);
+    }
+    return this.model.select();
+  }
+
+  async clear(): Promise<void> {
+    const all = await this.list();
+    for (const item of all) {
+      const key = (item as Record<string, unknown>)[this.options.keyField] as string | undefined;
+      if (key) await this.delete(key);
+    }
+  }
+}
+
+/**
+ * Helper to create a swappable backend ref.
+ * Call `swap(newBackend)` to atomically upgrade from memory to database.
+ */
+export function createSwappableBackend<T extends Record<string, any>>(
+  initial: StorageBackend<T>,
+): { backend: StorageBackend<T>; swap: (next: StorageBackend<T>) => void } {
+  const ref = { backend: initial, swap: (next: StorageBackend<T>) => { ref.backend = next; } };
+  return ref;
+}

package/src/tone-detector.ts

@@ -0,0 +1,89 @@
+/**
+ * ToneDetector — 轻量级情绪/语气检测
+ *
+ * 通过标点符号、emoji 密度、关键词分析用户语气，
+ * 生成一条 hint 注入 system prompt，让 AI 的回复匹配用户情绪。
+ *
+ * 零 LLM 开销，纯正则/统计分析。
+ */
+
+export type Tone = 'neutral' | 'frustrated' | 'excited' | 'questioning' | 'sad' | 'urgent';
+
+interface ToneResult {
+  tone: Tone;
+  hint: string;
+}
+
+// 常见负面情绪词
+const FRUSTRATED_WORDS = /不行|不对|又错|还是不|怎么回事|搞不定|烦死|崩溃|无语|什么鬼|bug|报错|失败|出问题/;
+const SAD_WORDS = /难过|伤心|失落|遗憾|可惜|唉|哎|不开心|郁闷|心累/;
+const URGENT_WORDS = /急|赶紧|马上|立刻|紧急|尽快|快点|asap|hurry/i;
+const EXCITED_WORDS = /太好了|太棒了|厉害|牛|可以|成功|搞定|完美|赞|nice|amazing|awesome|cool/i;
+
+/**
+ * 检测用户消息的情绪语气
+ */
+export function detectTone(message: string): ToneResult {
+  const len = message.length;
+  if (len === 0) return { tone: 'neutral', hint: '' };
+
+  // 统计特征
+  const exclamations = (message.match(/!/g) || []).length + (message.match(/！/g) || []).length;
+  const questions = (message.match(/\?/g) || []).length + (message.match(/？/g) || []).length;
+  const ellipsis = (message.match(/\.\.\./g) || []).length + (message.match(/…/g) || []).length;
+  const capsRatio = len > 5 ? (message.match(/[A-Z]/g) || []).length / len : 0;
+
+  // emoji 检测（常见 Unicode 范围）
+  const emojiCount = (message.match(/[\u{1F600}-\u{1F64F}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F1E0}-\u{1F1FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}]/gu) || []).length;
+
+  // 关键词检测
+  const isFrustrated = FRUSTRATED_WORDS.test(message);
+  const isSad = SAD_WORDS.test(message);
+  const isUrgent = URGENT_WORDS.test(message);
+  const isExcited = EXCITED_WORDS.test(message);
+
+  // 判定优先级: frustrated > urgent > sad > excited > questioning > neutral
+  if (isFrustrated || (exclamations >= 3 && !isExcited)) {
+    return {
+      tone: 'frustrated',
+      hint: '用户似乎有些沮丧或受挫，请用耐心、理解的语气回复，先表示共情再提供帮助。',
+    };
+  }
+
+  if (isUrgent) {
+    return {
+      tone: 'urgent',
+      hint: '用户似乎很着急，请直接给出解决方案，减少寒暄，优先效率。',
+    };
+  }
+
+  if (isSad || ellipsis >= 2) {
+    return {
+      tone: 'sad',
+      hint: '用户的语气似乎有些低落，请用温暖、关心的语气回复。',
+    };
+  }
+
+  if (isExcited || (emojiCount >= 2 && exclamations >= 1)) {
+    return {
+      tone: 'excited',
+      hint: '用户的心情不错，可以用更活泼、热情的语气回复。',
+    };
+  }
+
+  if (questions >= 2 || (questions >= 1 && len < 20)) {
+    return {
+      tone: 'questioning',
+      hint: '', // 提问是正常的，不需要特殊 hint
+    };
+  }
+
+  if (capsRatio > 0.5 && len > 10) {
+    return {
+      tone: 'frustrated',
+      hint: '用户使用了大量大写字母，可能在表达强烈情绪，请注意语气。',
+    };
+  }
+
+  return { tone: 'neutral', hint: '' };
+}

package/src/types.ts

@@ -8,7 +8,7 @@
 // ============================================================================
 
 /** 消息角色 */
-export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool' | 'tool_call' | 'tool_result';
 
 /** 聊天消息 */
 export interface ChatMessage {
@@ -51,10 +51,11 @@ export interface JsonSchema {
   properties?: Record<string, JsonSchema>;
   required?: string[];
   items?: JsonSchema;
-  enum?: any[];
+  enum?: unknown[];
   description?: string;
-  default?: any;
-  [key: string]: any;
+  default?: unknown;
+  /** JSON Schema allows arbitrary extension properties */
+  [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any -- JSON Schema spec requires open index
 }
 
 // ============================================================================
@@ -75,6 +76,8 @@ export interface ChatCompletionRequest {
   presence_penalty?: number;
   frequency_penalty?: number;
   user?: string;
+  /** 是否启用模型思考（如 qwen3 的 <think> 模式）。设为 false 可跳过思考加速响应。 */
+  think?: boolean;
 }
 
 /** 聊天补全响应 */
@@ -126,14 +129,27 @@ export interface ChatCompletionChunkChoice {
 // Provider 类型
 // ============================================================================
 
+/** Provider 能力声明 */
+export interface ProviderCapabilities {
+  vision?: boolean;
+  streaming?: boolean;
+  toolCalling?: boolean;
+  thinking?: boolean;
+}
+
 /** Provider 配置 */
 export interface ProviderConfig {
   apiKey?: string;
   baseUrl?: string;
   defaultModel?: string;
+  models?: string[];
   timeout?: number;
   maxRetries?: number;
   headers?: Record<string, string>;
+  /** 上下文窗口大小（token 数），各 Provider 映射到自身参数 */
+  contextWindow?: number;
+  /** Provider 能力声明 */
+  capabilities?: ProviderCapabilities;
 }
 
 /** Provider 接口 */
@@ -152,6 +168,33 @@ export interface AIProvider {
   
   /** 检查连接 */
   healthCheck?(): Promise<boolean>;
+
+  /** 上下文窗口大小（token 数），由 Provider 实现暴露 */
+  contextWindow?: number;
+
+  /** Provider 能力声明 */
+  capabilities?: ProviderCapabilities;
+}
+
+// ============================================================================
+// Tool Context (generic, IM-free)
+// ============================================================================
+
+/**
+ * 通用工具执行上下文。
+ *
+ * 定义了平台无关的字段，IM 应用通过 core 的 IMToolContext 扩展。
+ * 非 IM 应用可直接使用此接口。
+ */
+export interface ToolContext {
+  /** 来源平台标识 */
+  platform?: string;
+  /** 发送者 ID */
+  senderId?: string;
+  /** 场景 / 频道 ID */
+  sceneId?: string;
+  /** 额外数据（应用自行扩展） */
+  [key: string]: unknown;
 }
 
 // ============================================================================
@@ -163,7 +206,31 @@ export interface AgentTool {
   name: string;
   description: string;
   parameters: JsonSchema;
-  execute: (args: Record<string, any>) => Promise<any>;
+  execute: (args: Record<string, any>) => Promise<unknown>;
+  /** 工具标签，用于分类和快速匹配 */
+  tags?: string[];
+  /** 触发关键词，用户消息包含这些词时优先选择此工具 */
+  keywords?: string[];
+  /** 所需权限级别 (0=所有人, 1=群管理, 2=群主, 3=Bot管理员, 4=拥有者) */
+  permissionLevel?: number;
+  /** 是否允许预执行（opt-in），默认 false */
+  preExecutable?: boolean;
+  /** 工具分类（如 file / shell / web），用于 formatToolTitle 等展示 */
+  kind?: string;
+}
+
+/**
+ * 工具过滤选项
+ * 在 Agent.run() / runStream() 中启用程序化工具预过滤，
+ * 省去额外的 AI 意图分析往返
+ */
+export interface ToolFilterOptions {
+  /** 调用者权限级别 (0-4)，高于工具要求才能使用 */
+  callerPermissionLevel?: number;
+  /** 最大返回工具数量 (默认 10) */
+  maxTools?: number;
+  /** 最低相关性得分阈值，低于此分数的工具被过滤掉 (默认 0.1) */
+  minScore?: number;
 }
 
 /** Agent 配置 */
@@ -215,6 +282,13 @@ export interface Session {
 // AI Service 配置
 // ============================================================================
 
+/** Ollama-specific fields for AIConfig typing (mirrors OllamaConfig) */
+export interface OllamaProviderConfig extends ProviderConfig {
+  host?: string;
+  models?: string[];
+  num_ctx?: number;
+}
+
 /** AI 服务配置 */
 export interface AIConfig {
   enabled?: boolean;
@@ -225,7 +299,7 @@ export interface AIConfig {
     deepseek?: ProviderConfig;
     moonshot?: ProviderConfig;
     zhipu?: ProviderConfig;
-    ollama?: ProviderConfig & { host?: string; models?: string[] };
+    ollama?: OllamaProviderConfig;
     custom?: ProviderConfig[];
   };
   sessions?: {
@@ -250,6 +324,21 @@ export interface AIConfig {
     /** 自定义总结提示词 */
     summaryPrompt?: string;
   };
+  /** Agent 工具开关与执行安全 */
+  agent?: {
+    /** 禁用的工具名列表，这些工具不会下发给 AI */
+    disabledTools?: string[];
+    /** 仅允许的工具名列表；若设置则只下发列表中的工具（与 disabledTools 二选一，allowedTools 优先） */
+    allowedTools?: string[];
+    /** bash 执行策略：deny=禁止执行，allowlist=仅允许列表内命令，full=不限制 */
+    execSecurity?: 'deny' | 'allowlist' | 'full';
+    /** 预设命令白名单模式：readonly / network / development / custom（默认 custom，使用自定义 execAllowlist） */
+    execPreset?: 'readonly' | 'network' | 'development' | 'custom';
+    /** allowlist 模式下允许的命令（支持正则字符串，如 "^ls "、"^cat "），与 preset 合并 */
+    execAllowlist?: string[];
+    /** allowlist 未命中时：true=需审批（当前实现为拒绝并提示），false=直接拒绝 */
+    execAsk?: boolean;
+  };
   /** AI 触发配置 */
   trigger?: {
     /** 是否启用（默认 true） */