@h-ai/ai 0.1.0-alpha.32 → 0.1.0-alpha.34

package/README.md

@@ -91,11 +91,22 @@ for await (const chunk of ai.llm.chatStream({ messages })) {
   }
 }
 
+// 请求取消：传入 AbortSignal，主持人打断/用户切换时 abort() 立即停止上游生成与计费
+const controller = new AbortController()
+const cancellable = ai.llm.chat({ messages, signal: controller.signal })
+// controller.abort()
+
+// 多协议：模型的 api 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
+// - chat（默认）：OpenAI Chat Completions（兼容绝大多数厂商）
+// - responses：OpenAI Responses API（/v1/responses）
+// - anthropic：Anthropic Messages API（Claude 原生协议，环境变量 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL）
+const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 api: anthropic
+
 // 临时模型：单次请求绕过配置注册模型，直接指定端点与凭据（chat/chatStream/ask/askStream 均支持）
 // 临时客户端按 TTL 缓存（llm.tempModelCacheTtl，默认 10 分钟），与常驻模型客户端隔离
 const temp = await ai.llm.chat({
   messages,
-  tempModel: { model: 'claude-3-5-sonnet', apiKey: 'sk-temp', baseUrl: 'https://temp.endpoint/v1' },
+  tempModel: { model: 'claude-3-5-sonnet', api: 'anthropic', apiKey: 'sk-temp' },
 })
 ```
 
@@ -165,8 +176,13 @@ llm:
   apiKey: ${HAI_AI_LLM_API_KEY:}
   baseUrl: ${HAI_AI_LLM_BASE_URL:https://api.openai.com/v1}
   model: ${HAI_AI_LLM_MODEL:gpt-4o-mini}
+  api: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
   timeout: 60000
   tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
+  models: # 可为每个模型单独指定协议
+    - {id: fast, model: gpt-4o-mini}
+    - {id: strong, model: gpt-4.1, api: responses}
+    - {id: claude, model: claude-3-5-sonnet-latest, api: anthropic}
   scenarios:
     chat: fast
     reasoning: strong
@@ -188,12 +204,28 @@ knowledge:
     overlap: 200
 
 memory:
-  maxEntries: 1000
+  provider: native # native | mem0
+  maxEntriesPerObject: 1000 # 单主体（objectId）最大记忆条数
+  maxEntriesGlobal: 100000 # 跨所有主体的全局上限
   recencyDecay: 0.95
   embeddingEnabled: true
   defaultTopK: 10
+  writebackRelatedTopK: 20
+```
+
+启用 mem0（真·嵌入式 mem0ai/oss 引擎）：
+
+```yaml
+memory:
+  provider: mem0
+  defaultTopK: 10
 ```
 
+- **`native`（默认，推荐）**：HAI 原生引擎，复用同一套 vecdb（向量库）、reldb（关系库）、LLM 与 Embedding。`extract` 采用 **Mem0 式批量合并**——一次 LLM 调用对整批抽取事实与相关既有记忆做 ADD / UPDATE / DELETE / NONE 决策，实现增量更新、跨条去重与矛盾删除，并支持 `category` 主题标签。`maxEntriesPerObject`、`maxEntriesGlobal`、`recencyDecay`、`embeddingEnabled`、`writebackRelatedTopK` 均作用于此后端；淘汰按 `objectId` 分区触发，不会因某一主体写入过多而淘汰其他主体的记忆。
+- **`mem0`（真·mem0ai/oss）**：直接使用 `mem0ai/oss` 的 `Memory` 引擎（嵌入式，无云服务）。LLM / Embedder 从 `llm` 配置提取（OpenAI 兼容，走 `baseUrl` / `apiKey` / 场景模型）；向量库从底层 vecdb 后端提取——`qdrant` / `pgvector` 直接复用同一后端，`lancedb` / `chroma`（mem0 TS 不支持）则退回 mem0 自带的 in-memory 存储。历史记录默认禁用。需安装 `mem0ai`（已内置为依赖）；复用 qdrant/pgvector 时需对应客户端。
+
+两个 Provider 对外 `ai.memory.*` API 完全一致（`extract` / `recall` / `injectMemories` / `add` / `update` / `get` / `remove` / `list` / `listPage` / `clear`），均支持 `objectId`（主体隔离）与 `scope`（业务作用域 key-value 过滤，如 `{ topicId, personaId }`）。`recall` / `list` / `listPage` / `clear` 均按 `scope` 严格过滤，`clear` 在传入 `types` / `scope` 时仅删除同时匹配项（避免误删）。一个差异：mem0 后端在 `update` 涉及 type/importance/metadata 时会重建记忆并重新分配 `id`（native 后端保持 id 稳定）。
+
 `ai.config` 返回脱敏后的配置快照；`apiKey`、`privateKey`、URL 内嵌凭证等敏感字段不会原样暴露。
 
 ## 错误处理

package/dist/{ai-reasoning-types-Dtsg32tx.d.ts → ai-reasoning-types-Cm3-HVVN.d.ts}

@@ -379,6 +379,34 @@ interface KnowledgeStore {
      */
     deleteCollection: (collection: string) => Promise<void>;
 }
+/**
+ * 向量库后端连接信息
+ *
+ * 由 Provider 暴露底层向量库的原始连接，供需要复用同一后端的外部引擎（如 mem0 OSS）
+ * 直连。字段按后端类型填充；包含凭证，仅供同进程内集成使用。
+ */
+interface AIVectorBackend {
+    /** 后端类型（如 'qdrant'、'pgvector'、'lancedb'、'chroma'） */
+    type: string;
+    /** 服务 URL（qdrant / chroma） */
+    url?: string;
+    /** API Key（qdrant / chroma） */
+    apiKey?: string;
+    /** 主机（pgvector） */
+    host?: string;
+    /** 端口（pgvector / chroma） */
+    port?: number;
+    /** 数据库名（pgvector） */
+    database?: string;
+    /** 用户名（pgvector） */
+    user?: string;
+    /** 密码（pgvector） */
+    password?: string;
+    /** 连接串（pgvector） */
+    connectionString?: string;
+    /** 本地路径（lancedb / chroma 嵌入式） */
+    path?: string;
+}
 /**
  * AI 存储 Provider 接口
  *
@@ -401,6 +429,13 @@ interface AIStoreProvider {
     createRelStore: <T>(name: string, options?: AIRelStoreOptions) => AIRelStore<T>;
     /** 创建向量数据存储实例 */
     createVectorStore: (name: string) => AIVectorStore;
+    /**
+     * 暴露底层向量库后端连接（可选）
+     *
+     * 供需要直连同一向量库的外部引擎（如 mem0 OSS）复用后端。未初始化或不支持时返回
+     * `undefined`。返回值含凭证，仅供同进程内集成使用，禁止写入日志。
+     */
+    getVectorBackend?: () => AIVectorBackend | undefined;
     /**
      * 创建 knowledge 专用存储（可选）
      *
@@ -680,6 +715,8 @@ type ToolDefinition = OpenAI.Chat.Completions.ChatCompletionTool;
 interface TempModelConfig {
     /** 模型名称（传给 API 的实际模型名） */
     model: string;
+    /** API 协议（未指定时回退全局 `api`，再回退 `chat`；决定走 Chat Completions / Responses / Anthropic） */
+    api?: ApiType;
     /** API Key（未指定时回退全局配置 / 环境变量） */
     apiKey?: string;
     /** API 基础 URL（未指定时回退全局配置 / 环境变量 / 默认 OpenAI） */
@@ -711,6 +748,13 @@ type ChatCompletionRequest = Omit<OpenAI.Chat.ChatCompletionCreateParamsNonStrea
     enablePersist?: boolean;
     /** 临时模型配置（传入后绕过配置注册的模型，使用临时端点；优先级高于 `model`） */
     tempModel?: TempModelConfig;
+    /**
+     * 请求取消信号
+     *
+     * 传入后透传给底层 SDK（OpenAI / Anthropic）的请求取消参数。主持人打断、
+     * 用户切换等场景可 `abortController.abort()` 立即停止上游生成与计费。
+     */
+    signal?: AbortSignal;
 };
 /** Token 使用统计 */
 type TokenUsage = OpenAI.CompletionUsage;
@@ -880,6 +924,8 @@ interface AskOptions {
     enablePersist?: boolean;
     /** 临时模型配置（传入后绕过配置注册的模型，使用临时端点；优先级高于 `model`） */
     tempModel?: TempModelConfig;
+    /** 请求取消信号（透传给底层 SDK，支持主动打断上游生成） */
+    signal?: AbortSignal;
 }
 /**
  * 对话记录
@@ -1660,6 +1706,8 @@ interface MemoryEntryInput {
     importance?: number;
     /** 所属主体 ID（不指定时为全局记忆） */
     objectId?: string;
+    /** 作用域（JSON 对象，key-value 匹配过滤。用于子 session 记忆隔离等场景） */
+    scope?: Record<string, unknown>;
     /** 附加元数据 */
     metadata?: Record<string, unknown>;
 }
@@ -1677,6 +1725,8 @@ interface MemoryEntry {
     importance: number;
     /** 所属主体 ID */
     objectId?: string;
+    /** 作用域（JSON 对象，key-value 匹配过滤。用于子 session 记忆隔离等场景） */
+    scope?: Record<string, unknown>;
     /** 附加元数据 */
     metadata?: Record<string, unknown>;
     /** 向量（embedding 已计算时填充） */
@@ -1702,6 +1752,8 @@ interface MemoryExtractOptions {
     minImportance?: number;
     /** 所属主体 ID（关联到提取结果） */
     objectId?: string;
+    /** 作用域（JSON 对象，提取的记忆将关联此 scope） */
+    scope?: Record<string, unknown>;
     /**
      * 临时模型配置（携带凭据的模型请求）。
      *
@@ -1724,6 +1776,8 @@ interface MemoryRecallOptions {
     recencyWeight?: number;
     /** 限定主体 ID */
     objectId?: string;
+    /** 限定作用域（key-value 匹配过滤，用于子 session 记忆隔离等场景） */
+    scope?: Record<string, unknown>;
 }
 /**
  * 记忆注入选项（`injectMemories` 使用）
@@ -1739,6 +1793,12 @@ interface MemoryInjectionOptions {
     position?: 'system' | 'before-last';
     /** 限定主体 ID */
     objectId?: string;
+    /** 限定作用域（key-value 匹配过滤，用于子 session 记忆隔离等场景） */
+    scope?: Record<string, unknown>;
+    /** 限定记忆类型 */
+    types?: MemoryType[];
+    /** 最低重要性阈值 */
+    minImportance?: number;
 }
 /**
  * 记忆列表选项
@@ -1748,6 +1808,8 @@ interface MemoryListOptions {
     types?: MemoryType[];
     /** 限定主体 ID */
     objectId?: string;
+    /** 限定作用域（key-value 匹配过滤，用于子 session / 主题 / 角色记忆隔离等场景） */
+    scope?: Record<string, unknown>;
     /** 最大返回数 */
     limit?: number;
 }
@@ -1759,6 +1821,8 @@ interface MemoryListPageOptions {
     types?: MemoryType[];
     /** 限定主体 ID */
     objectId?: string;
+    /** 限定作用域（key-value 匹配过滤，用于子 session / 主题 / 角色记忆隔离等场景） */
+    scope?: Record<string, unknown>;
     /** 偏移量 */
     offset?: number;
     /** 每页数量（默认 20） */
@@ -1766,12 +1830,17 @@ interface MemoryListPageOptions {
 }
 /**
  * 记忆清空选项
+ *
+ * 安全语义：未传任何过滤条件时清空全部；传入 objectId / types / scope 时
+ * 仅删除同时匹配所有给定条件的记忆，避免误删其他主体或类型的记忆。
  */
 interface MemoryClearOptions {
     /** 仅清空指定类型 */
     types?: MemoryType[];
     /** 仅清空指定主体 */
     objectId?: string;
+    /** 仅清空匹配指定作用域的记忆（key-value 匹配过滤） */
+    scope?: Record<string, unknown>;
 }
 /**
  * 记忆条目更新输入
@@ -1934,8 +2003,8 @@ interface MemoryOperations {
  * - `fast` — 快速响应场景（低延迟优先）
  */
 declare const ModelScenarioSchema: z.ZodEnum<{
-    default: "default";
     chat: "chat";
+    default: "default";
     reasoning: "reasoning";
     plan: "plan";
     execute: "execute";
@@ -1948,6 +2017,22 @@ declare const ModelScenarioSchema: z.ZodEnum<{
 }>;
 /** 模型场景类型 */
 type ModelScenario = z.infer<typeof ModelScenarioSchema>;
+/**
+ * LLM API 协议枚举
+ *
+ * 决定底层通过哪种 API 协议与模型交互（对使用方透明，公共请求/响应形状保持一致）：
+ *
+ * - `chat` — OpenAI Chat Completions API（`/v1/chat/completions`，默认，兼容绝大多数厂商）
+ * - `responses` — OpenAI Responses API（`/v1/responses`，新一代有状态接口）
+ * - `anthropic` — Anthropic Messages API（Claude 原生协议，需安装 `@anthropic-ai/sdk`）
+ */
+declare const ApiTypeSchema: z.ZodEnum<{
+    chat: "chat";
+    responses: "responses";
+    anthropic: "anthropic";
+}>;
+/** LLM API 协议类型 */
+type ApiType = z.infer<typeof ApiTypeSchema>;
 /**
  * 模型条目 Schema
  *
@@ -1966,6 +2051,11 @@ type ModelScenario = z.infer<typeof ModelScenarioSchema>;
 declare const ModelEntrySchema: z.ZodObject<{
     id: z.ZodString;
     model: z.ZodString;
+    api: z.ZodOptional<z.ZodEnum<{
+        chat: "chat";
+        responses: "responses";
+        anthropic: "anthropic";
+    }>>;
     apiKey: z.ZodOptional<z.ZodString>;
     baseUrl: z.ZodOptional<z.ZodURL>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -2009,6 +2099,11 @@ declare const LLMConfigSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodString>;
     baseUrl: z.ZodOptional<z.ZodURL>;
     model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    api: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        chat: "chat";
+        responses: "responses";
+        anthropic: "anthropic";
+    }>>>;
     maxTokens: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     temperature: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
@@ -2016,6 +2111,11 @@ declare const LLMConfigSchema: z.ZodObject<{
     models: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         model: z.ZodString;
+        api: z.ZodOptional<z.ZodEnum<{
+            chat: "chat";
+            responses: "responses";
+            anthropic: "anthropic";
+        }>>;
         apiKey: z.ZodOptional<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodURL>;
         maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -2023,8 +2123,8 @@ declare const LLMConfigSchema: z.ZodObject<{
         timeout: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
     scenarios: z.ZodOptional<z.ZodObject<{
-        default: z.ZodOptional<z.ZodString>;
         chat: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodString>;
         reasoning: z.ZodOptional<z.ZodString>;
         plan: z.ZodOptional<z.ZodString>;
         execute: z.ZodOptional<z.ZodString>;
@@ -2046,6 +2146,8 @@ type LLMConfig = z.infer<typeof LLMConfigSchema>;
 interface ResolvedModelConfig {
     /** 模型名称（传给 API 的实际模型名） */
     model: string;
+    /** API 协议（模型条目 > 全局配置 > `chat`） */
+    api: ApiType;
     /** API Key（模型条目 > 全局配置 > 环境变量） */
     apiKey: string | undefined;
     /** API 基础 URL（模型条目 > 全局配置 > 环境变量 > 默认 OpenAI） */
@@ -2077,6 +2179,18 @@ interface ResolveRequiredModelEntryOptions {
  * @returns 成功返回已解析模型配置，失败返回 `CONFIGURATION_ERROR`
  */
 declare function resolveModelEntry(llmConfig: LLMConfig, scenario: ModelScenario, explicit?: string, options?: ResolveRequiredModelEntryOptions): HaiResult<ResolvedModelConfig>;
+/**
+ * 解析某次 chat 请求应使用的 API 协议（不校验 API Key）
+ *
+ * 供 LLM Provider 路由层选择底层实现使用：优先取显式模型条目的 `api`，
+ * 其次全局 `api`，最后回退 `chat`。临时模型的 `api` 由调用方单独传入优先。
+ *
+ * @param llmConfig - LLM 配置
+ * @param explicitModel - 显式指定的模型名/ID（可选）
+ * @param tempApi - 临时模型显式指定的 API 协议（可选，最高优先级）
+ * @returns 解析出的 API 协议
+ */
+declare function resolveModelApi(llmConfig: LLMConfig, explicitModel?: string, tempApi?: ApiType): ApiType;
 /** MCP 服务器能力 Schema */
 declare const MCPServerCapabilitiesSchema: z.ZodObject<{
     tools: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -2205,14 +2319,16 @@ type KnowledgeConfig = z.infer<typeof KnowledgeConfigSchema>;
 /**
  * Memory 配置 Schema
  *
- * 配置对话记忆的提取、存储与检索参数。
- * 模型通过 LLMConfigSchema.scenarios.extraction 解析，
- * apiKey / baseUrl 统一使用 LLM 配置。
+ * 配置对话记忆的提取、存储与检索参数。两种 provider 均为嵌入式，复用同一套
+ * vecdb / reldb / LLM / Embedding；模型通过 LLMConfigSchema.scenarios.extraction
+ * 解析，apiKey / baseUrl 统一使用 LLM 配置。
  *
  * @example
  * ```ts
  * const memoryConfig = {
- *   maxEntries: 1000,
+ *   provider: 'native',
+ *   maxEntriesPerObject: 1000,
+ *   maxEntriesGlobal: 100000,
  *   embeddingEnabled: true,
  *   recencyDecay: 0.95,
  *   defaultTopK: 10,
@@ -2220,7 +2336,12 @@ type KnowledgeConfig = z.infer<typeof KnowledgeConfigSchema>;
  * ```
  */
 declare const MemoryConfigSchema: z.ZodObject<{
-    maxEntries: z.ZodDefault<z.ZodNumber>;
+    provider: z.ZodDefault<z.ZodEnum<{
+        native: "native";
+        mem0: "mem0";
+    }>>;
+    maxEntriesPerObject: z.ZodDefault<z.ZodNumber>;
+    maxEntriesGlobal: z.ZodDefault<z.ZodNumber>;
     systemPrompt: z.ZodOptional<z.ZodString>;
     recencyDecay: z.ZodDefault<z.ZodNumber>;
     embeddingEnabled: z.ZodDefault<z.ZodBoolean>;
@@ -2433,7 +2554,7 @@ type A2AConfig = z.infer<typeof A2AConfigSchema>;
  *       { id: 'docs', collection: 'documentation', name: '产品文档', topK: 5, minScore: 0.7 },
  *     ],
  *   },
- *   memory: { maxEntries: 500, embeddingEnabled: true },
+ *   memory: { maxEntriesPerObject: 500, embeddingEnabled: true },
  *   token: { tokenRatio: 0.25 },
  *   summary: { systemPrompt: 'You are a summarizer.' },
  *   compress: { defaultStrategy: 'hybrid', preserveLastN: 4 },
@@ -2445,6 +2566,11 @@ declare const AIConfigSchema: z.ZodObject<{
         apiKey: z.ZodOptional<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodURL>;
         model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        api: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            chat: "chat";
+            responses: "responses";
+            anthropic: "anthropic";
+        }>>>;
         maxTokens: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         temperature: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
@@ -2452,6 +2578,11 @@ declare const AIConfigSchema: z.ZodObject<{
         models: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             model: z.ZodString;
+            api: z.ZodOptional<z.ZodEnum<{
+                chat: "chat";
+                responses: "responses";
+                anthropic: "anthropic";
+            }>>;
             apiKey: z.ZodOptional<z.ZodString>;
             baseUrl: z.ZodOptional<z.ZodURL>;
             maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -2459,8 +2590,8 @@ declare const AIConfigSchema: z.ZodObject<{
             timeout: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
         scenarios: z.ZodOptional<z.ZodObject<{
-            default: z.ZodOptional<z.ZodString>;
             chat: z.ZodOptional<z.ZodString>;
+            default: z.ZodOptional<z.ZodString>;
             reasoning: z.ZodOptional<z.ZodString>;
             plan: z.ZodOptional<z.ZodString>;
             execute: z.ZodOptional<z.ZodString>;
@@ -2523,7 +2654,12 @@ declare const AIConfigSchema: z.ZodObject<{
         systemPrompt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     memory: z.ZodOptional<z.ZodObject<{
-        maxEntries: z.ZodDefault<z.ZodNumber>;
+        provider: z.ZodDefault<z.ZodEnum<{
+            native: "native";
+            mem0: "mem0";
+        }>>;
+        maxEntriesPerObject: z.ZodDefault<z.ZodNumber>;
+        maxEntriesGlobal: z.ZodDefault<z.ZodNumber>;
         systemPrompt: z.ZodOptional<z.ZodString>;
         recencyDecay: z.ZodDefault<z.ZodNumber>;
         embeddingEnabled: z.ZodDefault<z.ZodBoolean>;
@@ -2877,4 +3013,4 @@ interface ReasoningOperations {
     runStream: (query: string, options?: ReasoningOptions) => AsyncIterable<ReasoningStreamEvent>;
 }
 
-export { type A2AOperations as $, type A2AConfig as A, type RetrievalConfig as B, type CompressConfig as C, RetrievalConfigSchema as D, type EmbeddingConfig as E, type FileConfig as F, type RetrievalSourceConfig as G, RetrievalSourceSchema as H, SummaryConfigSchema as I, TokenConfigSchema as J, type KnowledgeConfig as K, type LLMConfig as L, type MCPConfig as M, resolveModelEntry as N, type A2AAgentCardConfig as O, type A2AApiKeySecurity as P, type A2AAuthenticator as Q, type ResolveRequiredModelEntryOptions as R, type SummaryConfig as S, type TokenConfig as T, type A2ACallOptions as U, type A2ACallResult as V, type A2ACallerIdentity as W, type A2AClientCallRecord as X, type A2AContextInfo as Y, type A2AHandleResult as Z, type A2AMessageRecord as _, A2AConfigSchema as a, type ReasoningOperations as a$, type A2ASecurityConfig as a0, type A2ATaskFilter as a1, type AILLMFunctionsDeps as a2, type AIRelStore as a3, type AIRelStoreOptions as a4, type AIStoreProvider as a5, type AIVectorStore as a6, type AskOptions as a7, type AssistantMessage as a8, type ChatCompletionChoice as a9, type KnowledgeIngestResult as aA, type KnowledgeOperations as aB, type KnowledgeRetrieveItem as aC, type KnowledgeRetrieveOptions as aD, type KnowledgeRetrieveResult as aE, type KnowledgeSetupOptions as aF, type KnowledgeStore as aG, type LLMOperations as aH, type LLMProvider as aI, type MemoryClearOptions as aJ, type MemoryEntry as aK, type MemoryEntryInput as aL, type MemoryExtractOptions as aM, type MemoryInjectionOptions as aN, type MemoryListOptions as aO, type MemoryListPageOptions as aP, type MemoryOperations as aQ, type MemoryRecallOptions as aR, type MemoryUpdateInput as aS, type MessageContent as aT, type MessageRole as aU, type ObjectRef as aV, type RagContextItem as aW, type RagOperations as aX, type RagOptions as aY, type RagResult as aZ, type RagStreamEvent as a_, type ChatCompletionChunk as aa, type ChatCompletionDelta as ab, type ChatCompletionRequest as ac, type ChatCompletionResponse as ad, type ChatHistoryOptions as ae, type ChatMessage as af, type ChatRecord as ag, type Citation as ah, type DefineToolOptions as ai, type DeveloperMessage as aj, type EntityDocumentRelation as ak, type EntityDocumentResult as al, type EntityListOptions as am, type EntityQueryOptions as an, type ImageContent as ao, type InteractionScope as ap, type KnowledgeAskOptions as aq, type KnowledgeAskResult as ar, type KnowledgeDocumentInfo as as, type KnowledgeDocumentListOptions as at, type KnowledgeDocumentRemoveOptions as au, type KnowledgeEntity as av, type KnowledgeIngestBatchProgress as aw, type KnowledgeIngestBatchResult as ax, type KnowledgeIngestFileInput as ay, type KnowledgeIngestInput as az, A2ASkillConfigSchema as b, type ReasoningOptions as b0, type ReasoningResult as b1, type ReasoningStep as b2, type ReasoningStepType as b3, type ReasoningStrategy as b4, type ReasoningStreamEvent as b5, type RetrievalOperations as b6, type RetrievalRequest as b7, type RetrievalResult as b8, type RetrievalResultItem as b9, type RetrievalSource as ba, type SSEDecoder as bb, type SSEEvent as bc, type SessionInfo as bd, type StoreFilter as be, type StorePage as bf, type StoreScope as bg, type StreamOperations as bh, type StreamProcessor as bi, type StreamResult as bj, type SystemMessage as bk, type TempModelConfig as bl, type TextContent as bm, type TokenUsage as bn, type Tool as bo, type ToolCall as bp, type ToolDefinition as bq, type ToolErrorType as br, type ToolMessage as bs, type ToolRegistryOperations as bt, type ToolsOperations as bu, type UserMessage as bv, type WhereClause as bw, type WhereOperator as bx, type WhereValue as by, type AIConfig as c, type AIConfigInput as d, AIConfigSchema as e, CompressConfigSchema as f, EmbeddingConfigSchema as g, type EntityType as h, EntityTypeSchema as i, FileConfigSchema as j, KnowledgeConfigSchema as k, LLMConfigSchema as l, MCPConfigSchema as m, type MCPServerCapabilities as n, MCPServerCapabilitiesSchema as o, type MCPServerConfig as p, MCPServerConfigSchema as q, type MemoryConfig as r, MemoryConfigSchema as s, type MemoryType as t, MemoryTypeSchema as u, type ModelEntry as v, ModelEntrySchema as w, type ModelScenario as x, ModelScenarioSchema as y, type ResolvedModelConfig as z };
+export { type A2AContextInfo as $, type A2AConfig as A, ModelScenarioSchema as B, type CompressConfig as C, type ResolvedModelConfig as D, type EmbeddingConfig as E, type FileConfig as F, type RetrievalConfig as G, RetrievalConfigSchema as H, type RetrievalSourceConfig as I, RetrievalSourceSchema as J, type KnowledgeConfig as K, type LLMConfig as L, type MCPConfig as M, SummaryConfigSchema as N, TokenConfigSchema as O, resolveModelApi as P, resolveModelEntry as Q, type ResolveRequiredModelEntryOptions as R, type SummaryConfig as S, type TokenConfig as T, type A2AAgentCardConfig as U, type A2AApiKeySecurity as V, type A2AAuthenticator as W, type A2ACallOptions as X, type A2ACallResult as Y, type A2ACallerIdentity as Z, type A2AClientCallRecord as _, A2AConfigSchema as a, type RagOperations as a$, type A2AHandleResult as a0, type A2AMessageRecord as a1, type A2AOperations as a2, type A2ASecurityConfig as a3, type A2ATaskFilter as a4, type AILLMFunctionsDeps as a5, type AIRelStore as a6, type AIRelStoreOptions as a7, type AIStoreProvider as a8, type AIVectorBackend as a9, type KnowledgeIngestBatchProgress as aA, type KnowledgeIngestBatchResult as aB, type KnowledgeIngestFileInput as aC, type KnowledgeIngestInput as aD, type KnowledgeIngestResult as aE, type KnowledgeOperations as aF, type KnowledgeRetrieveItem as aG, type KnowledgeRetrieveOptions as aH, type KnowledgeRetrieveResult as aI, type KnowledgeSetupOptions as aJ, type KnowledgeStore as aK, type LLMOperations as aL, type LLMProvider as aM, type MemoryClearOptions as aN, type MemoryEntry as aO, type MemoryEntryInput as aP, type MemoryExtractOptions as aQ, type MemoryInjectionOptions as aR, type MemoryListOptions as aS, type MemoryListPageOptions as aT, type MemoryOperations as aU, type MemoryRecallOptions as aV, type MemoryUpdateInput as aW, type MessageContent as aX, type MessageRole as aY, type ObjectRef as aZ, type RagContextItem as a_, type AIVectorStore as aa, type AskOptions as ab, type AssistantMessage as ac, type ChatCompletionChoice as ad, type ChatCompletionChunk as ae, type ChatCompletionDelta as af, type ChatCompletionRequest as ag, type ChatCompletionResponse as ah, type ChatHistoryOptions as ai, type ChatMessage as aj, type ChatRecord as ak, type Citation as al, type DefineToolOptions as am, type DeveloperMessage as an, type EntityDocumentRelation as ao, type EntityDocumentResult as ap, type EntityListOptions as aq, type EntityQueryOptions as ar, type ImageContent as as, type InteractionScope as at, type KnowledgeAskOptions as au, type KnowledgeAskResult as av, type KnowledgeDocumentInfo as aw, type KnowledgeDocumentListOptions as ax, type KnowledgeDocumentRemoveOptions as ay, type KnowledgeEntity as az, A2ASkillConfigSchema as b, type RagOptions as b0, type RagResult as b1, type RagStreamEvent as b2, type ReasoningOperations as b3, type ReasoningOptions as b4, type ReasoningResult as b5, type ReasoningStep as b6, type ReasoningStepType as b7, type ReasoningStrategy as b8, type ReasoningStreamEvent as b9, type WhereClause as bA, type WhereOperator as bB, type WhereValue as bC, type RetrievalOperations as ba, type RetrievalRequest as bb, type RetrievalResult as bc, type RetrievalResultItem as bd, type RetrievalSource as be, type SSEDecoder as bf, type SSEEvent as bg, type SessionInfo as bh, type StoreFilter as bi, type StorePage as bj, type StoreScope as bk, type StreamOperations as bl, type StreamProcessor as bm, type StreamResult as bn, type SystemMessage as bo, type TempModelConfig as bp, type TextContent as bq, type TokenUsage as br, type Tool as bs, type ToolCall as bt, type ToolDefinition as bu, type ToolErrorType as bv, type ToolMessage as bw, type ToolRegistryOperations as bx, type ToolsOperations as by, type UserMessage as bz, type AIConfig as c, type AIConfigInput as d, AIConfigSchema as e, type ApiType as f, ApiTypeSchema as g, CompressConfigSchema as h, EmbeddingConfigSchema as i, type EntityType as j, EntityTypeSchema as k, FileConfigSchema as l, KnowledgeConfigSchema as m, LLMConfigSchema as n, MCPConfigSchema as o, type MCPServerCapabilities as p, MCPServerCapabilitiesSchema as q, type MCPServerConfig as r, MCPServerConfigSchema as s, type MemoryConfig as t, MemoryConfigSchema as u, type MemoryType as v, MemoryTypeSchema as w, type ModelEntry as x, ModelEntrySchema as y, type ModelScenario as z };

package/dist/{ai-types-D3cT4zTc.d.ts → ai-types-BZjo_rWW.d.ts}

@@ -1,6 +1,6 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult } from '@h-ai/core';
-import { af as ChatMessage, ap as InteractionScope, aN as MemoryInjectionOptions, aY as RagOptions, b0 as ReasoningOptions, bt as ToolRegistryOperations, bd as SessionInfo, aH as LLMOperations, aQ as MemoryOperations, aX as RagOperations, a$ as ReasoningOperations, c as AIConfig, d as AIConfigInput, a5 as AIStoreProvider, bu as ToolsOperations, bh as StreamOperations, b6 as RetrievalOperations, aB as KnowledgeOperations, $ as A2AOperations } from './ai-reasoning-types-Dtsg32tx.js';
+import { aj as ChatMessage, at as InteractionScope, v as MemoryType, b0 as RagOptions, b4 as ReasoningOptions, bx as ToolRegistryOperations, bh as SessionInfo, aL as LLMOperations, aU as MemoryOperations, a$ as RagOperations, b3 as ReasoningOperations, c as AIConfig, d as AIConfigInput, a8 as AIStoreProvider, by as ToolsOperations, bl as StreamOperations, ba as RetrievalOperations, aF as KnowledgeOperations, a2 as A2AOperations } from './ai-reasoning-types-Cm3-HVVN.js';
 import { z } from 'zod';
 import { Buffer } from 'node:buffer';
 
@@ -204,13 +204,31 @@ interface ContextManagerOptions {
     /**
      * 记忆配置
      *
-     * 引用 MemoryInjectionOptions 的检索控制字段，加上 enable/enableExtract 开关。
+     * 控制记忆注入与提取。`scope` / `types` / `minImportance` 会完整透传给 Memory 的
+     * `injectMemories` 与 `extract`，用于表达「用户 + 主题 + 角色」等多维隔离
+     * （如 `{ userId, topicId, personaId }`）。
      */
-    memory?: Pick<MemoryInjectionOptions, 'topK' | 'maxTokens' | 'position'> & {
+    memory?: {
         /** 是否启用记忆注入（默认 false） */
         enable?: boolean;
         /** 是否启用自动记忆提取（默认 false） */
         enableExtract?: boolean;
+        /** 业务作用域（透传给 injectMemories / extract，key-value 匹配隔离） */
+        scope?: Record<string, unknown>;
+        /** 注入 / 提取时限定的记忆类型 */
+        types?: MemoryType[];
+        /** 注入时的最低重要性阈值 */
+        minImportance?: number;
+        /** 注入的记忆数量 */
+        topK?: number;
+        /** 注入记忆占用的最大 token 预算 */
+        maxTokens?: number;
+        /** 注入位置：system 追加或最后一条用户消息前插入 */
+        position?: 'system' | 'before-last';
+        /** 记忆提取使用的模型（覆盖默认提取模型） */
+        extractionModel?: string;
+        /** 记忆提取的自定义 systemPrompt */
+        extractionSystemPrompt?: string;
     };
     /**
      * RAG 配置
@@ -250,6 +268,13 @@ interface ContextChatOptions {
     temperature?: number;
     /** 是否启用本次 LLM 调用的持久化（默认 false，Context 自行管理状态） */
     enablePersist?: boolean;
+    /**
+     * 请求取消信号
+     *
+     * 透传给底层 LLM 调用；主持人打断、用户切换等场景可 `abortController.abort()`
+     * 立即停止上游生成与计费。
+     */
+    signal?: AbortSignal;
 }
 /**
  * chat() 返回的结果
@@ -356,8 +381,25 @@ interface ContextManager {
     getSummaries: () => HaiResult<SummaryResult[]>;
     /**
      * 持久化当前状态（需要 scope + 存储可用）
+     *
+     * 内部会先 `flush()` 等待所有后台记忆提取完成，确保持久化时记忆已写入。
      */
     save: () => Promise<HaiResult<void>>;
+    /**
+     * 等待所有后台记忆提取任务完成
+     *
+     * chat/chatStream 的自动记忆提取是「即发即忘」的后台任务；在开始下一轮召回、
+     * 生成总结或关闭前调用 `flush()`，可避免「上一轮记忆尚未写完」的时序问题（issue #14）。
+     *
+     * @returns 全部任务完成返回 ok(undefined)
+     */
+    flush: () => Promise<HaiResult<void>>;
+    /**
+     * 当前挂起的后台记忆提取任务数量
+     *
+     * 供应用侧观测；为 0 表示无待写入的记忆任务。
+     */
+    readonly pendingMemoryTasks: number;
     /**
      * 重置管理器（清空所有消息和摘要）
      */

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-export { A as A2AConfig, a as A2AConfigSchema, b as A2ASkillConfigSchema, c as AIConfig, d as AIConfigInput, e as AIConfigSchema, C as CompressConfig, f as CompressConfigSchema, E as EmbeddingConfig, g as EmbeddingConfigSchema, h as EntityType, i as EntityTypeSchema, F as FileConfig, j as FileConfigSchema, K as KnowledgeConfig, k as KnowledgeConfigSchema, L as LLMConfig, l as LLMConfigSchema, M as MCPConfig, m as MCPConfigSchema, n as MCPServerCapabilities, o as MCPServerCapabilitiesSchema, p as MCPServerConfig, q as MCPServerConfigSchema, r as MemoryConfig, s as MemoryConfigSchema, t as MemoryType, u as MemoryTypeSchema, v as ModelEntry, w as ModelEntrySchema, x as ModelScenario, y as ModelScenarioSchema, R as ResolveRequiredModelEntryOptions, z as ResolvedModelConfig, B as RetrievalConfig, D as RetrievalConfigSchema, G as RetrievalSourceConfig, H as RetrievalSourceSchema, S as SummaryConfig, I as SummaryConfigSchema, T as TokenConfig, J as TokenConfigSchema, N as resolveModelEntry } from './ai-reasoning-types-Dtsg32tx.js';
-export { A as AIFunctions, a as AIInitOptions, C as CompressionStrategy, b as CompressionStrategySchema, H as HaiAIError } from './ai-types-D3cT4zTc.js';
+export { A as A2AConfig, a as A2AConfigSchema, b as A2ASkillConfigSchema, c as AIConfig, d as AIConfigInput, e as AIConfigSchema, f as ApiType, g as ApiTypeSchema, C as CompressConfig, h as CompressConfigSchema, E as EmbeddingConfig, i as EmbeddingConfigSchema, j as EntityType, k as EntityTypeSchema, F as FileConfig, l as FileConfigSchema, K as KnowledgeConfig, m as KnowledgeConfigSchema, L as LLMConfig, n as LLMConfigSchema, M as MCPConfig, o as MCPConfigSchema, p as MCPServerCapabilities, q as MCPServerCapabilitiesSchema, r as MCPServerConfig, s as MCPServerConfigSchema, t as MemoryConfig, u as MemoryConfigSchema, v as MemoryType, w as MemoryTypeSchema, x as ModelEntry, y as ModelEntrySchema, z as ModelScenario, B as ModelScenarioSchema, R as ResolveRequiredModelEntryOptions, D as ResolvedModelConfig, G as RetrievalConfig, H as RetrievalConfigSchema, I as RetrievalSourceConfig, J as RetrievalSourceSchema, S as SummaryConfig, N as SummaryConfigSchema, T as TokenConfig, O as TokenConfigSchema, P as resolveModelApi, Q as resolveModelEntry } from './ai-reasoning-types-Cm3-HVVN.js';
+export { A as AIFunctions, a as AIInitOptions, C as CompressionStrategy, b as CompressionStrategySchema, H as HaiAIError } from './ai-types-BZjo_rWW.js';
 export { A2AClientOperations, AIApiAdapter, AIClient, AIClientConfig, StreamOptions, StreamProgress, collectStreamContent, createA2AClient, createAIClient, parseSSE } from './client/index.js';
 import '@a2a-js/sdk/server';
 import '@h-ai/core';

package/dist/browser.js

@@ -1,4 +1,4 @@
-export { A2AConfigSchema, A2ASkillConfigSchema, AIConfigSchema, CompressConfigSchema, CompressionStrategySchema, EmbeddingConfigSchema, EntityTypeSchema, FileConfigSchema, HaiAIError, KnowledgeConfigSchema, LLMConfigSchema, MCPConfigSchema, MCPServerCapabilitiesSchema, MCPServerConfigSchema, MemoryConfigSchema, MemoryTypeSchema, ModelEntrySchema, ModelScenarioSchema, RetrievalConfigSchema, RetrievalSourceSchema, SummaryConfigSchema, TokenConfigSchema, resolveModelEntry } from './chunk-TPHVO2QP.js';
+export { A2AConfigSchema, A2ASkillConfigSchema, AIConfigSchema, ApiTypeSchema, CompressConfigSchema, CompressionStrategySchema, EmbeddingConfigSchema, EntityTypeSchema, FileConfigSchema, HaiAIError, KnowledgeConfigSchema, LLMConfigSchema, MCPConfigSchema, MCPServerCapabilitiesSchema, MCPServerConfigSchema, MemoryConfigSchema, MemoryTypeSchema, ModelEntrySchema, ModelScenarioSchema, RetrievalConfigSchema, RetrievalSourceSchema, SummaryConfigSchema, TokenConfigSchema, resolveModelApi, resolveModelEntry } from './chunk-CXO3YSIG.js';
 export { collectStreamContent, createA2AClient, createAIClient, parseSSE } from './chunk-Y5BQR7QA.js';
 //# sourceMappingURL=browser.js.map
 //# sourceMappingURL=browser.js.map

package/dist/{chunk-TPHVO2QP.js → chunk-CXO3YSIG.js}

@@ -220,11 +220,14 @@ var aiM = core.i18n.createMessageGetter({
 
 // src/ai-config.ts
 var ModelScenarioSchema = z.enum(["default", "chat", "reasoning", "plan", "execute", "extraction", "summary", "embedding", "rerank", "ocr", "fast"]);
+var ApiTypeSchema = z.enum(["chat", "responses", "anthropic"]);
 var ModelEntrySchema = z.object({
   /** 模型唯一标识（用于 ModelResolver 解析） */
   id: z.string(),
   /** 模型名称（传给 API 的实际模型名） */
   model: z.string(),
+  /** API 协议（可选，未指定时回退全局 `api`，再回退 `chat`；决定走 Chat Completions / Responses / Anthropic） */
+  api: ApiTypeSchema.optional(),
   /** API Key 覆盖（可选，未提供时使用全局配置） */
   apiKey: z.string().optional(),
   /** Base URL 覆盖（可选） */
@@ -243,6 +246,8 @@ var LLMConfigSchema = z.object({
   baseUrl: z.url().optional(),
   /** 默认模型名称（默认 `'gpt-4o-mini'`） */
   model: z.string().optional().default("gpt-4o-mini"),
+  /** 全局 API 协议（各模型 fallback，默认 `'chat'`；可选 `chat` / `responses` / `anthropic`） */
+  api: ApiTypeSchema.optional().default("chat"),
   /** 全局最大 Token 数（各模型 fallback，默认 `4096`） */
   maxTokens: z.number().positive().optional().default(4096),
   /** 全局采样温度（各模型 fallback，范围 `[0, 2]`，默认 `0.7`） */
@@ -273,6 +278,7 @@ function resolveModelEntry(llmConfig, scenario, explicit, options) {
   }
   const resolved = {
     model: modelName,
+    api: entry?.api ?? llmConfig.api ?? "chat",
     apiKey: entry?.apiKey ?? llmConfig.apiKey ?? process.env.HAI_AI_LLM_API_KEY ?? process.env.OPENAI_API_KEY,
     baseUrl: entry?.baseUrl ?? llmConfig.baseUrl ?? process.env.HAI_AI_LLM_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
     maxTokens: entry?.maxTokens ?? llmConfig.maxTokens ?? 4096,
@@ -284,6 +290,12 @@ function resolveModelEntry(llmConfig, scenario, explicit, options) {
   }
   return ok(resolved);
 }
+function resolveModelApi(llmConfig, explicitModel, tempApi) {
+  if (tempApi)
+    return tempApi;
+  const entry = explicitModel ? llmConfig.models?.find((m) => m.id === explicitModel || m.model === explicitModel) : void 0;
+  return entry?.api ?? llmConfig.api ?? "chat";
+}
 var MCPServerCapabilitiesSchema = z.object({
   /** 是否支持工具调用（默认 `true`） */
   tools: z.boolean().optional().default(true),
@@ -343,8 +355,21 @@ var KnowledgeConfigSchema = z.object({
   systemPrompt: z.string().optional()
 });
 var MemoryConfigSchema = z.object({
-  /** 最大记忆条数（默认 1000） */
-  maxEntries: z.number().int().positive().default(1e3),
+  /** 记忆后端：native = 逐条写回；mem0 = 批量 ADD/UPDATE/DELETE 合并（均为嵌入式，复用 HAI 组件） */
+  provider: z.enum(["native", "mem0"]).default("native"),
+  /**
+   * 单个主体（objectId）的最大记忆条数（默认 1000）
+   *
+   * native 淘汰按 objectId 分区触发：某个主体写入超过此上限时，只淘汰该主体自身
+   * 最低优先级的条目，不会波及其他主体的记忆。
+   */
+  maxEntriesPerObject: z.number().int().positive().default(1e3),
+  /**
+   * 全局最大记忆条数（默认 100000）
+   *
+   * 跨所有主体的总量上限，作为整体保护阈值；超过时淘汰全局最低优先级条目。
+   */
+  maxEntriesGlobal: z.number().int().positive().default(1e5),
   /** 自定义记忆提取 systemPrompt（可选，覆盖内置默认提示词） */
   systemPrompt: z.string().optional(),
   /** 时间衰减系数（默认 0.95，每次检索乘以此系数调整 recency 权重） */
@@ -353,6 +378,7 @@ var MemoryConfigSchema = z.object({
   embeddingEnabled: z.boolean().default(true),
   /** 检索时默认返回数量（默认 10） */
   defaultTopK: z.number().int().positive().default(10),
+  /** 写回 / 合并时检索相关记忆的数量（native 与 mem0 共用，默认 20） */
   writebackRelatedTopK: z.number().int().positive().default(20)
 });
 var TokenConfigSchema = z.object({
@@ -434,6 +460,7 @@ var AIConfigSchema = z.object({
   /** LLM 配置（可选，所有字段有默认值） */
   llm: LLMConfigSchema.default({
     model: "gpt-4o-mini",
+    api: "chat",
     maxTokens: 4096,
     temperature: 0.7,
     timeout: 6e4,
@@ -461,6 +488,6 @@ var AIConfigSchema = z.object({
   a2a: A2AConfigSchema.optional()
 });
 
-export { A2AConfigSchema, A2ASkillConfigSchema, AIConfigSchema, CompressConfigSchema, CompressionStrategySchema, EmbeddingConfigSchema, EntityTypeSchema, FileConfigSchema, HaiAIError, KnowledgeConfigSchema, LLMConfigSchema, MCPConfigSchema, MCPServerCapabilitiesSchema, MCPServerConfigSchema, MemoryConfigSchema, MemoryTypeSchema, ModelEntrySchema, ModelScenarioSchema, RetrievalConfigSchema, RetrievalSourceSchema, SummaryConfigSchema, TokenConfigSchema, aiM, resolveModelEntry };
-//# sourceMappingURL=chunk-TPHVO2QP.js.map
-//# sourceMappingURL=chunk-TPHVO2QP.js.map
+export { A2AConfigSchema, A2ASkillConfigSchema, AIConfigSchema, ApiTypeSchema, CompressConfigSchema, CompressionStrategySchema, EmbeddingConfigSchema, EntityTypeSchema, FileConfigSchema, HaiAIError, KnowledgeConfigSchema, LLMConfigSchema, MCPConfigSchema, MCPServerCapabilitiesSchema, MCPServerConfigSchema, MemoryConfigSchema, MemoryTypeSchema, ModelEntrySchema, ModelScenarioSchema, RetrievalConfigSchema, RetrievalSourceSchema, SummaryConfigSchema, TokenConfigSchema, aiM, resolveModelApi, resolveModelEntry };
+//# sourceMappingURL=chunk-CXO3YSIG.js.map
+//# sourceMappingURL=chunk-CXO3YSIG.js.map