@h-ai/ai 0.1.0-alpha.67 → 0.1.0-alpha.69

package/dist/ai-reasoning-types-DZd_6Umd.d.ts

@@ -1,3936 +0,0 @@
-import { HaiResult, HaiError } from '@h-ai/core';
-import { CleanOptionsInput, ChunkOptionsInput } from '@h-ai/datapipe';
-import { ZodType, z } from 'zod';
-import { AgentCard } from '@a2a-js/sdk';
-import { AgentExecutor } from '@a2a-js/sdk/server';
-import OpenAI from 'openai';
-
-/**
- * @h-ai/ai — Store 存储抽象类型
- *
- * 定义统一的键值式 CRUD + 查询接口，所有需要状态持久化的子系统通过此接口存取数据。
- * @module ai-store-types
- */
-/**
- * 存储作用域——用于索引列加速查询
- *
- * 在 save 时传入 scope，值将写入独立索引列（object_id / session_id），
- * 后续 query / removeBy 可通过 StoreFilter.objectId / sessionId 使用索引过滤。
- */
-interface StoreScope {
-    /** 交互主体 ID（写入 object_id 索引列） */
-    objectId?: string;
-    /** 会话 ID（写入 session_id 索引列） */
-    sessionId?: string;
-    /** 状态（写入 status 索引列） */
-    status?: string;
-    /** 引用 ID（写入 ref_id 索引列，关联外部实体） */
-    refId?: string;
-}
-/**
- * where 条件中单个字段的值——纯值表示等值匹配，对象表示操作符
- *
- * @example
- * ```ts
- * // 等值：type === 'fact'
- * { type: 'fact' }
- *
- * // IN：type ∈ ['fact', 'preference']
- * { type: { $in: ['fact', 'preference'] } }
- *
- * // 范围：importance >= 0.5
- * { importance: { $gte: 0.5 } }
- *
- * // 组合：objectId === 'user-1' AND type ∈ ['fact'] AND importance >= 0.3
- * { objectId: 'user-1', type: { $in: ['fact'] }, importance: { $gte: 0.3 } }
- * ```
- */
-interface WhereOperator<V> {
-    /** 值在给定列表中（IN 语义） */
-    $in?: V[];
-    /** 大于等于 */
-    $gte?: V;
-    /** 大于 */
-    $gt?: V;
-    /** 小于等于 */
-    $lte?: V;
-    /** 小于 */
-    $lt?: V;
-}
-/**
- * 单字段条件：纯值 = 等值匹配，WhereOperator 对象 = 操作符匹配
- */
-type WhereValue<V> = V | WhereOperator<V>;
-/**
- * where 子句类型——每个字段可以是等值匹配或操作符对象
- */
-type WhereClause<T> = {
-    [K in keyof T]?: WhereValue<T[K]>;
-};
-/**
- * 存储查询过滤条件
- *
- * @typeParam T - 记录类型
- *
- * @example
- * ```ts
- * // 等值匹配（兼容旧写法）
- * store.query({ where: { type: 'fact', objectId: 'user-1' } })
- *
- * // 操作符匹配
- * store.query({ where: { type: { $in: ['fact', 'preference'] }, importance: { $gte: 0.5 } } })
- * ```
- */
-interface StoreFilter<T> {
-    /** 字段匹配条件（等值或操作符） */
-    where?: WhereClause<T>;
-    /** 按 object_id 索引列过滤（需要 AIRelStoreOptions.hasObjectId 启用） */
-    objectId?: string;
-    /** 按 session_id 索引列过滤（需要 AIRelStoreOptions.hasSessionId 启用） */
-    sessionId?: string;
-    /** 按 status 索引列过滤（需要 AIRelStoreOptions.hasStatus 启用，支持单值或多值 IN 匹配） */
-    status?: string | string[];
-    /** 按 ref_id 索引列过滤（需要 AIRelStoreOptions.hasRefId 启用） */
-    refId?: string;
-    /**
-     * 按业务作用域过滤（`data.scope` JSON 字段的 key-value 包含匹配）。
-     *
-     * 仅在 PostgreSQL 上下推为 `data @> ?::jsonb`（配合 GIN 索引加速）；
-     * SQLite / MySQL 上为 no-op（不影响结果，由调用方在内存中完成 scope 匹配）。
-     */
-    scope?: Record<string, unknown>;
-    /** 排序 */
-    orderBy?: {
-        field: keyof T;
-        direction: 'asc' | 'desc';
-    };
-    /** 数量限制 */
-    limit?: number;
-}
-/**
- * 分页查询结果
- */
-interface StorePage<T> {
-    /** 当前页数据 */
-    items: T[];
-    /** 总记录数 */
-    total: number;
-}
-/**
- * AIRelStore 配置选项
- *
- * 控制存储实例需要创建哪些索引列（object_id / session_id / status / ref_id）。
- */
-interface AIRelStoreOptions {
-    /** 是否创建 object_id 索引列 */
-    hasObjectId?: boolean;
-    /** 是否创建 session_id 索引列 */
-    hasSessionId?: boolean;
-    /** 是否创建 status 索引列 */
-    hasStatus?: boolean;
-    /** 是否创建 ref_id 索引列 */
-    hasRefId?: boolean;
-    /**
-     * 是否为业务作用域（记录内 `data.scope` JSON 字段）建立索引以加速 scope 过滤。
-     *
-     * 仅 PostgreSQL 生效：在 JSONB `data` 列上建 GIN 索引，配合 `StoreFilter.scope`
-     * 的 `data @> ?::jsonb` 包含查询下推，避免加载全部候选再在内存过滤。
-     * SQLite / MySQL 不建索引，`scope` 过滤退回调用方内存匹配（当前行为不变）。
-     */
-    hasScopeIndex?: boolean;
-}
-/**
- * AI 关系存储适配器
- *
- * 提供统一的 KV 式 CRUD + 查询能力，由 AIStoreProvider 创建具体实现。
- *
- * @typeParam T - 记录类型
- */
-interface AIRelStore<T> {
-    /** 保存一条记录（upsert 语义） */
-    save: (id: string, data: T, scope?: StoreScope) => Promise<void>;
-    /** 批量保存 */
-    saveMany: (items: Array<{
-        id: string;
-        data: T;
-        scope?: StoreScope;
-    }>) => Promise<void>;
-    /** 按 ID 获取 */
-    get: (id: string) => Promise<T | undefined>;
-    /** 按条件查询 */
-    query: (filter: StoreFilter<T>) => Promise<T[]>;
-    /** 分页查询 */
-    queryPage: (filter: StoreFilter<T>, page: {
-        offset: number;
-        limit: number;
-    }) => Promise<StorePage<T>>;
-    /** 删除一条记录 */
-    remove: (id: string) => Promise<boolean>;
-    /** 按条件删除 */
-    removeBy: (filter: StoreFilter<T>) => Promise<number>;
-    /** 计数 */
-    count: (filter?: StoreFilter<T>) => Promise<number>;
-    /** 清空（可选按条件） */
-    clear: (filter?: StoreFilter<T>) => Promise<void>;
-}
-/**
- * AI 向量存储适配器
- *
- * 专用于需要向量检索的场景（如 Memory），由 AIStoreProvider 创建具体实现。
- */
-interface AIVectorStore {
-    /** 存储向量 */
-    upsert: (id: string, vector: number[], metadata?: Record<string, unknown>) => Promise<void>;
-    /** 向量相似度检索 */
-    search: (vector: number[], options?: {
-        topK?: number;
-        minScore?: number;
-        filter?: Record<string, unknown>;
-    }) => Promise<Array<{
-        id: string;
-        score: number;
-        content?: string;
-        metadata?: Record<string, unknown>;
-    }>>;
-    /** 删除向量 */
-    remove: (id: string) => Promise<void>;
-    /** 清空 */
-    clear: (filter?: Record<string, unknown>) => Promise<void>;
-}
-/**
- * 交互主体引用
- *
- * 代表"和谁"交互 — 可以是人、AI Agent、或系统自身。
- */
-interface ObjectRef {
-    /** 主体唯一 ID */
-    objectId: string;
-    /** 主体类型 */
-    objectType?: 'human' | 'agent' | 'system';
-}
-/**
- * 完整的交互作用域 = Object + Session
- */
-interface InteractionScope {
-    /** 交互主体 ID */
-    objectId: string;
-    /** 会话 ID */
-    sessionId: string;
-}
-/**
- * 会话信息
- */
-interface SessionInfo {
-    /** 会话 ID */
-    sessionId: string;
-    /** 所属主体 ID */
-    objectId: string;
-    /** 会话标题 */
-    title?: string;
-    /** 创建时间（Unix 毫秒） */
-    createdAt: number;
-    /** 更新时间（Unix 毫秒） */
-    updatedAt: number;
-    /** 附加元数据 */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Knowledge 专用存储接口
- *
- * 封装知识库的实体索引、文档元数据和向量操作。
- * 默认实现使用 reldb 归一化表 + vecdb 向量检索；
- * SaaS 实现可对接远端知识库 API。
- */
-interface KnowledgeStore {
-    /** 初始化存储（建表 / 建集合 / 建索引，幂等） */
-    initialize: (collection: string, dimension: number) => Promise<void>;
-    /** 插入或更新实体 */
-    upsertEntity: (entity: {
-        id: string;
-        name: string;
-        type: string;
-        collection: string;
-        aliases?: string[];
-        description?: string;
-    }) => Promise<void>;
-    /** 按名称模糊搜索实体（匹配 name 和 aliases，可按 collection 过滤） */
-    findEntitiesByName: (keyword: string, collection?: string) => Promise<Array<{
-        id: string;
-        name: string;
-        type: string;
-        aliases: string[];
-    }>>;
-    /** 列出实体（支持 collection / 类型 / 关键词搜索） */
-    listEntities: (options?: {
-        collection?: string;
-        type?: string;
-        keyword?: string;
-        limit?: number;
-    }) => Promise<Array<{
-        id: string;
-        name: string;
-        type: string;
-        aliases: string[];
-        description: string | null;
-        createdAt: string | null;
-        updatedAt: string | null;
-    }>>;
-    /** 批量删除实体本体 */
-    deleteEntities: (entityIds: string[]) => Promise<void>;
-    /**
-     * 删除指定文档在指定 collection 中的所有实体本体
-     *
-     * 使用子查询，必须在 removeDocumentEntityRelations 之前调用（关联行删除后子查询结果为空）。
-     * removeDocument 使用此方法完成实体数据闭环，无需两步查询。
-     */
-    deleteDocumentEntities: (documentId: string, collection: string) => Promise<void>;
-    /** 插入文档-实体关联 */
-    insertEntityDocument: (relation: {
-        entityId: string;
-        documentId: string;
-        chunkId?: string;
-        collection: string;
-        relevance?: number;
-        context?: string;
-    }) => Promise<void>;
-    /** 按实体 ID 列表查询关联文档 */
-    findDocumentsByEntityIds: (entityIds: string[], collection?: string) => Promise<Array<{
-        entityId: string;
-        documentId: string;
-        chunkId: string;
-        collection: string;
-        relevance: number;
-        context: string | null;
-    }>>;
-    /** 按实体名称查询实体及其关联文档 */
-    findByEntityName: (entityName: string, options?: {
-        collection?: string;
-        type?: string;
-    }) => Promise<Array<{
-        entity: {
-            id: string;
-            name: string;
-            type: string;
-            aliases: string[];
-            description: string | null;
-        };
-        documents: Array<{
-            documentId: string;
-            chunkId: string;
-            collection: string;
-            relevance: number;
-            context: string | null;
-        }>;
-    }>>;
-    /**
-     * 删除文档相关的实体关联行
-     *
-     * 仅删除 entity_document 关联行，不删除实体本体。
-     * 调用前应先执行 deleteDocumentEntities，否则子查询结果为空导致实体无法清理。
-     */
-    removeDocumentEntityRelations: (documentId: string, collection: string) => Promise<void>;
-    /** 保存文档元数据 */
-    upsertDocument: (doc: {
-        documentId: string;
-        collection: string;
-        title?: string;
-        url?: string;
-        chunkCount: number;
-        createdAt: number;
-    }) => Promise<void>;
-    /** 按 documentId + collection 获取单个文档元数据 */
-    getDocument: (documentId: string, collection: string) => Promise<{
-        documentId: string;
-        collection: string;
-        title: string | null;
-        url: string | null;
-        chunkCount: number;
-        createdAt: number;
-    } | undefined>;
-    /** 列出文档元数据 */
-    listDocuments: (collection: string, options?: {
-        offset?: number;
-        limit?: number;
-    }) => Promise<Array<{
-        documentId: string;
-        collection: string;
-        title: string | null;
-        url: string | null;
-        chunkCount: number;
-        createdAt: number;
-    }>>;
-    /** 查询每个文档的实体关联数 */
-    listDocumentEntityCounts: (documentIds: string[], collection: string) => Promise<Map<string, number>>;
-    /** 删除文档元数据 */
-    removeDocument: (documentId: string, collection: string) => Promise<void>;
-    /** 批量写入向量 */
-    upsertVectors: (collection: string, vectors: Array<{
-        id: string;
-        vector: number[];
-        content?: string;
-        metadata?: Record<string, unknown>;
-    }>) => Promise<void>;
-    /** 向量相似度检索 */
-    searchVectors: (collection: string, vector: number[], options?: {
-        topK?: number;
-        minScore?: number;
-        filter?: Record<string, unknown>;
-    }) => Promise<Array<{
-        id: string;
-        score: number;
-        content?: string;
-        metadata?: Record<string, unknown>;
-    }>>;
-    /** 批量删除向量 */
-    removeVectors: (collection: string, ids: string[]) => Promise<void>;
-    /** 确保向量集合存在 */
-    ensureCollection: (collection: string, dimension: number) => Promise<void>;
-    /** 注册 collection（setup 时持久化，幂等） */
-    registerCollection: (collection: string, dimension: number) => Promise<void>;
-    /** 检查 collection 是否已在注册表中存在（跨节点/重启后仍有效） */
-    collectionExists: (collection: string) => Promise<boolean>;
-    /**
-     * 删除整个 collection（清理 vecdb 集合 + 所有 reldb 关联数据）
-     * 幂等：collection 不存在时静默成功
-     */
-    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 接口
- *
- * 负责创建 AIRelStore / AIVectorStore 实例，并管理存储层生命周期。
- * reldb + vecdb 已初始化时默认使用持久化 DB 实现，否则使用进程内临时实现；
- * 也可对接 SaaS API 或其他后端。
- *
- * @example
- * ```ts
- * await ai.init(config, { storeProvider: myProvider })
- * ```
- */
-interface AIStoreProvider {
-    /** Provider 名称（如 'db'、'api'） */
-    readonly name: string;
-    /** 创建关系数据存储实例 */
-    createRelStore: <T>(name: string, options?: AIRelStoreOptions) => AIRelStore<T>;
-    /** 创建向量数据存储实例 */
-    createVectorStore: (name: string) => AIVectorStore;
-    /**
-     * 暴露底层向量库后端连接（可选）
-     *
-     * 供需要直连同一向量库的外部引擎（如 mem0 OSS）复用后端。未初始化或不支持时返回
-     * `undefined`。返回值含凭证，仅供同进程内集成使用，禁止写入日志。
-     */
-    getVectorBackend?: () => AIVectorBackend | undefined;
-    /**
-     * 创建 knowledge 专用存储（可选）
-     *
-     * 如果 Provider 不提供此方法，knowledge 子系统将不可用。
-     * 默认 db Provider 提供基于 reldb 归一化表 + vecdb 的高效实现。
-     */
-    createKnowledgeStore?: () => KnowledgeStore;
-    /**
-     * 初始化所有已创建的存储（建表、建连接等）
-     *
-     * 由 ai.init() 在创建完所有 store 实例后统一调用。
-     */
-    initialize: () => Promise<void>;
-    /** 关闭所有存储（释放连接等），由 ai.close() 调用 */
-    close?: () => Promise<void>;
-}
-
-/**
- * @h-ai/ai — LLM 子功能类型
- *
- * 定义 LLM 消息、请求、响应、流、工具等公共类型。
- * @module ai-llm-types
- */
-
-/** 消息角色枚举：`'system'` | `'developer'` | `'user'` | `'assistant'` | `'tool'` */
-type MessageRole = 'system' | 'developer' | 'user' | 'assistant' | 'tool';
-/** 文本内容块（多模态消息中的纯文本部分） */
-type TextContent = OpenAI.Chat.Completions.ChatCompletionContentPartText;
-/** 图片内容块（多模态消息中的图片部分） */
-type ImageContent = OpenAI.Chat.Completions.ChatCompletionContentPartImage;
-/** 消息内容（纯文本字符串，或由内容块组成的多模态数组） */
-type MessageContent = string | OpenAI.Chat.Completions.ChatCompletionContentPart[];
-/** 系统消息，用于设定对话的行为规则 */
-type SystemMessage = OpenAI.Chat.Completions.ChatCompletionSystemMessageParam;
-/** 开发者消息（高优先级运行时约束） */
-interface DeveloperMessage {
-    role: 'developer';
-    content: string | TextContent[];
-    name?: string;
-}
-/** 用户消息 */
-type UserMessage = OpenAI.Chat.Completions.ChatCompletionUserMessageParam;
-/** 工具调用描述，由助手消息中的 `tool_calls` 字段携带 */
-type ToolCall = OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
-/** 助手消息（模型生成的回复，或传入对话上下文的助手轮次） */
-type AssistantMessage = OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam & {
-    /**
-     * 推理模型额外返回的思维链内容。
-     *
-     * DeepSeek thinking mode 在 function calling 多轮续写时要求回传该字段。
-     */
-    reasoning_content?: string | null;
-};
-/** 工具消息（工具执行结果，用于回传给模型） */
-type ToolMessage = OpenAI.Chat.Completions.ChatCompletionToolMessageParam;
-/** 聊天消息联合类型，涵盖对话中所有角色的消息 */
-type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam | DeveloperMessage;
-/** OpenAI function calling 工具定义格式 */
-type ToolDefinition = OpenAI.Chat.Completions.ChatCompletionTool;
-/**
- * 临时模型配置
- *
- * 单次请求级别的临时模型端点，绕过配置中注册的模型与场景映射，
- * 直接指定 API Key / Base URL / 模型名等参数。适用于运行时动态切换模型、
- * 多租户各自携带凭据等场景。其客户端实例按 TTL 缓存（见 `LLMConfig.tempModelCacheTtl`），
- * 与常驻模型客户端缓存隔离。
- *
- * 未指定的字段回退到全局 LLM 配置：`apiKey` / `baseUrl` 回退全局值或环境变量，
- * `maxTokens` / `temperature` / `timeout` 回退全局默认值。
- */
-interface TempModelConfig {
-    /** 模型名称（传给 API 的实际模型名） */
-    model: string;
-    /** API 协议（未指定时回退全局 `api`，再回退 `chat`；决定走 Chat Completions / Responses / Anthropic） */
-    api?: ApiType;
-    /** API Key（未指定时回退全局配置 / 环境变量） */
-    apiKey?: string;
-    /** API 基础 URL（未指定时回退全局配置 / 环境变量 / 默认 OpenAI） */
-    baseUrl?: string;
-    /** 最大 Token 数（未指定时回退全局配置；请求显式指定 `max_tokens` 时以请求为准） */
-    maxTokens?: number;
-    /** 采样温度（未指定时回退全局配置；请求显式指定 `temperature` 时以请求为准） */
-    temperature?: number;
-    /** 请求超时时间（毫秒，未指定时回退全局配置） */
-    timeout?: number;
-}
-/**
- * 聊天完成请求参数
- *
- * 继承 OpenAI SDK 全部标准请求字段，并扩展框架专属字段（`objectId`、`sessionId`）。
- * `model` 改为可选（未指定时使用配置中的默认模型）。
- * `stream` 字段由框架内部控制，不对外暴露。
- */
-type ChatCompletionRequest = Omit<OpenAI.Chat.ChatCompletionCreateParamsNonStreaming, 'model' | 'stream' | 'messages'> & {
-    /** 对话消息列表 */
-    messages: ChatMessage[];
-    /** 模型名称（可选，未指定时使用配置中的默认模型） */
-    model?: string;
-    /** 交互主体 ID（传入后 LLM 会自动关联到该主体） */
-    objectId?: string;
-    /** 会话 ID（传入后 LLM 会自动关联到该会话） */
-    sessionId?: string;
-    /** 是否持久化对话记录（默认 true；传入 false 时跳过记录，适用于内部调用如实体提取） */
-    enablePersist?: boolean;
-    /** 临时模型配置（传入后绕过配置注册的模型，使用临时端点；优先级高于 `model`） */
-    tempModel?: TempModelConfig;
-    /**
-     * 请求取消信号
-     *
-     * 传入后透传给底层 SDK（OpenAI / Anthropic）的请求取消参数。主持人打断、
-     * 用户切换等场景可 `abortController.abort()` 立即停止上游生成与计费。
-     */
-    signal?: AbortSignal;
-};
-/** Token 使用统计 */
-type TokenUsage = OpenAI.CompletionUsage;
-/** 聊天完成响应中的单个选择 */
-type ChatCompletionChoice = OpenAI.Chat.ChatCompletion.Choice;
-/** 聊天完成响应（非流式） */
-type ChatCompletionResponse = OpenAI.Chat.ChatCompletion;
-/** 流式增量内容（每个 chunk 中的变化部分） */
-type ChatCompletionDelta = OpenAI.Chat.ChatCompletionChunk.Choice.Delta;
-/** 流式响应块（SSE 传输的单个数据帧） */
-type ChatCompletionChunk = OpenAI.Chat.ChatCompletionChunk;
-/** 流处理结果（完整消费流后的累积数据） */
-interface StreamResult {
-    /** 累积的完整文本内容 */
-    content: string;
-    /** 累积的完整 reasoning 内容 */
-    reasoningContent: string;
-    /** 累积的完整工具调用列表 */
-    toolCalls: ToolCall[];
-    /** 完成原因（流未结束时为 `null`） */
-    finishReason: string | null;
-}
-/**
- * 流处理器接口
- *
- * 逐 chunk 喂入，内部累积文本和工具调用，支持 reset 复用。
- */
-interface StreamProcessor {
-    /** 处理单个 chunk，返回增量 delta；空 choices 时返回 `null` */
-    process: (chunk: ChatCompletionChunk) => ChatCompletionDelta | null;
-    /** 获取当前累积结果（不重置状态） */
-    getResult: () => StreamResult;
-    /** 将累积结果转换为 AssistantMessage（有 tool_calls 时 content 为 `null`） */
-    toAssistantMessage: () => AssistantMessage;
-    /** 重置内部状态，可重新处理新一轮流 */
-    reset: () => void;
-}
-/** SSE（Server-Sent Events）事件结构 */
-interface SSEEvent {
-    /** 事件类型（`event:` 字段） */
-    event?: string;
-    /** 事件 ID（`id:` 字段） */
-    id?: string;
-    /** 重连间隔（毫秒，`retry:` 字段） */
-    retry?: number;
-    /** 数据载荷（`data:` 字段，多行数据以 `\n` 合并） */
-    data?: string;
-}
-/**
- * SSE 解码器接口
- *
- * 内部维护缓冲区，支持跨 chunk 的不完整数据拼接。
- */
-interface SSEDecoder {
-    /** 追加文本并解码出完整事件；未完成的部分留在缓冲区 */
-    decode: (text: string) => Iterable<SSEEvent>;
-    /** 清空缓冲区 */
-    reset: () => void;
-}
-/** 流处理操作接口（通过 `ai.stream` 访问，纯函数，无需初始化） */
-interface StreamOperations {
-    /** 创建新的流处理器实例 */
-    createProcessor: () => StreamProcessor;
-    /** 完整消费流并返回累积结果 */
-    collect: (stream: AsyncIterable<ChatCompletionChunk>) => Promise<StreamResult>;
-    /** 创建新的 SSE 解码器实例 */
-    createSSEDecoder: () => SSEDecoder;
-    /** 将 SSE 事件编码为符合规范的文本（以 `\n\n` 结尾） */
-    encodeSSE: (event: SSEEvent) => string;
-}
-/** 工具错误类型枚举 */
-type ToolErrorType = 'TOOL_NOT_FOUND' | 'TOOL_ALREADY_REGISTERED' | 'VALIDATION_FAILED' | 'EXECUTION_FAILED' | 'FORBIDDEN' | 'TIMEOUT';
-/**
- * 工具执行上下文（传给 handler）
- *
- * 由框架在 `execute` / `executeAll` 时构造并透传给工具 handler，使工具能够：
- * - 响应取消（主持人打断、上层 AbortSignal）提前中止耗时操作（DB 查询 / HTTP 请求）；
- * - 感知超时截止时间；
- * - 获知当前交互主体 / 会话，做数据隔离或审计。
- *
- * `signal` 始终存在：即便调用方未传入信号，框架也会依据默认超时构造一个。
- */
-interface ToolExecutionContext {
-    /** 取消信号（始终存在；结合调用方信号与超时截止） */
-    signal: AbortSignal;
-    /** 交互主体 ID（透传自 Context / Reasoning 作用域） */
-    objectId?: string;
-    /** 会话 ID（透传自 Context / Reasoning 作用域） */
-    sessionId?: string;
-    /** 截止时间（Unix 毫秒；到期自动取消） */
-    deadline?: number;
-}
-/**
- * 工具授权请求
- *
- * `input` 已通过工具的 Zod schema 校验；授权函数在 handler 执行前调用。
- */
-interface ToolAuthorizationRequest<TInput = unknown> {
-    /** 工具名称 */
-    toolName: string;
-    /** 已校验的工具输入 */
-    input: TInput;
-    /** 本次执行上下文 */
-    context: ToolExecutionContext;
-}
-/** 工具授权函数；返回 `false` 或抛出异常时均拒绝执行（fail-closed） */
-type ToolAuthorizer = (request: ToolAuthorizationRequest) => Promise<boolean> | boolean;
-/**
- * 工具执行入参（调用方传给 `execute` / `executeAll`）
- *
- * 所有字段可选。框架据此解析出传给 handler 的 {@link ToolExecutionContext}：
- * 组合调用方 `signal` 与超时信号，超时优先级 `deadline` > `timeoutMs` > 工具默认 > 全局默认。
- */
-interface ToolExecutionOptions {
-    /** 调用方取消信号（与超时信号组合） */
-    signal?: AbortSignal;
-    /** 交互主体 ID */
-    objectId?: string;
-    /** 会话 ID */
-    sessionId?: string;
-    /** 截止时间（Unix 毫秒；优先级高于 timeoutMs） */
-    deadline?: number;
-    /** 本次执行超时（毫秒；覆盖工具默认超时） */
-    timeoutMs?: number;
-    /**
-     * 本次执行授权函数
-     *
-     * 与 Registry 级授权同时存在时必须全部通过。授权异常不会进入 handler，统一返回
-     * `TOOL_FORBIDDEN`，避免因授权服务故障而放行高风险操作。
-     */
-    authorize?: ToolAuthorizer;
-}
-/**
- * 工具定义选项（传给 `ai.tools.define()`）
- *
- * @typeParam TInput - 参数类型（由 Zod schema 推断）
- * @typeParam TOutput - 返回值类型
- */
-interface DefineToolOptions<TInput, TOutput> {
-    /** 工具名称（需唯一，用于 function calling name 字段） */
-    name: string;
-    /** 工具功能描述（供模型理解何时调用） */
-    description: string;
-    /** Zod schema，用于参数校验和 JSON Schema 转换 */
-    parameters: ZodType<TInput>;
-    /**
-     * 执行函数，接收校验后的参数与执行上下文，支持同步/异步
-     *
-     * `context.signal` 用于响应取消：长耗时操作应把它透传给 DB / HTTP 客户端，
-     * 以便打断或超时时提前中止。
-     */
-    handler: (input: TInput, context: ToolExecutionContext) => Promise<TOutput> | TOutput;
-    /** 本工具默认执行超时（毫秒；execute 未指定 deadline/timeoutMs 时生效） */
-    timeoutMs?: number;
-}
-/**
- * 工具实例（由 `ai.tools.define()` 创建）
- *
- * @typeParam TInput - 参数类型
- * @typeParam TOutput - 返回值类型
- */
-interface Tool<TInput = unknown, TOutput = unknown> {
-    /** 工具名称 */
-    name: string;
-    /** 工具功能描述 */
-    description: string;
-    /** Zod 参数 schema */
-    parameters: ZodType<TInput>;
-    /** 执行工具（自动校验参数），失败返回 ToolError；超时 / 取消返回 TOOL_TIMEOUT */
-    execute: (input: TInput, options?: ToolExecutionOptions) => Promise<HaiResult<TOutput>>;
-    /** 转换为 OpenAI function calling 定义格式（$schema 字段已移除） */
-    toDefinition: () => ToolDefinition;
-}
-/**
- * 工具注册表接口（由 `ai.tools.createRegistry()` 创建）
- *
- * 管理一组工具的注册、查询与批量执行。注册方法返回 `HaiResult<void>`，
- * 调用方应显式处理重名等配置错误。
- */
-interface ToolRegistryOperations {
-    /** 注册工具；同名工具已存在时返回 `TOOL_ALREADY_REGISTERED` */
-    register: <TInput, TOutput>(tool: Tool<TInput, TOutput>) => HaiResult<void>;
-    /** 原子批量注册；列表内或注册表内存在重名时不写入任何工具 */
-    registerMany: (tools: Tool<unknown, unknown>[]) => HaiResult<void>;
-    /** 显式替换已注册工具；目标不存在时返回 `TOOL_NOT_FOUND` */
-    replace: <TInput, TOutput>(tool: Tool<TInput, TOutput>) => HaiResult<void>;
-    /** 注销指定名称的工具，成功返回 `true`，不存在返回 `false` */
-    unregister: (name: string) => boolean;
-    /** 按名称获取工具实例，不存在返回 `undefined` */
-    get: (name: string) => Tool | undefined;
-    /** 判断指定名称的工具是否已注册 */
-    has: (name: string) => boolean;
-    /** 获取所有已注册的工具名称列表 */
-    getNames: () => string[];
-    /** 获取所有工具的 OpenAI function calling 定义（用于传入 ChatCompletionRequest.tools） */
-    getDefinitions: () => ToolDefinition[];
-    /** 执行单个工具调用，自动解析 JSON 参数并校验；失败返回 ToolError，超时 / 取消返回 TOOL_TIMEOUT */
-    execute: (toolCall: ToolCall, options?: ToolExecutionOptions) => Promise<HaiResult<ToolMessage>>;
-    /** 批量执行工具调用（默认串行），任一失败立即返回错误；仅显式 `parallel: true` 时并行 */
-    executeAll: (toolCalls: ToolCall[], options?: ToolExecutionOptions & {
-        parallel?: boolean;
-    }) => Promise<HaiResult<ToolMessage[]>>;
-    /** 清空所有已注册的工具 */
-    clear: () => void;
-    /** 当前已注册的工具数量 */
-    readonly size: number;
-}
-/** 工具注册表创建选项 */
-interface ToolRegistryOptions {
-    /**
-     * Registry 级授权函数
-     *
-     * 适合统一执行租户、角色、资源归属和高风险操作确认。它不能替代 handler 内针对最终资源的
-     * 业务校验；两层校验应共同采用最小权限原则。
-     */
-    authorize?: ToolAuthorizer;
-}
-/** 工具操作接口（通过 `ai.tools` 访问，纯函数，无需初始化） */
-interface ToolsOperations {
-    /** 定义工具（Zod schema 类型推断 + 自动参数校验） */
-    define: <TInput, TOutput>(options: DefineToolOptions<TInput, TOutput>) => Tool<TInput, TOutput>;
-    /** 创建新的工具注册表实例，可注入统一授权函数 */
-    createRegistry: (options?: ToolRegistryOptions) => ToolRegistryOperations;
-}
-/** 对话记录查询选项 */
-interface ChatHistoryOptions {
-    /** 返回数量限制 */
-    limit?: number;
-    /** 排序方向（默认 `'desc'` 最新在前） */
-    order?: 'asc' | 'desc';
-}
-/**
- * ask/askStream 便捷方法选项
- */
-interface AskOptions {
-    /** 系统提示词 */
-    systemPrompt?: string;
-    /** 使用的模型 */
-    model?: string;
-    /** 交互主体 ID */
-    objectId?: string;
-    /** 会话 ID */
-    sessionId?: string;
-    /** 温度（0~2） */
-    temperature?: number;
-    /** 是否持久化对话记录（默认 true；传入 false 时跳过记录） */
-    enablePersist?: boolean;
-    /** 临时模型配置（传入后绕过配置注册的模型，使用临时端点；优先级高于 `model`） */
-    tempModel?: TempModelConfig;
-    /** 请求取消信号（透传给底层 SDK，支持主动打断上游生成） */
-    signal?: AbortSignal;
-}
-/**
- * 对话记录
- *
- * 每次 `llm.chat()` 调用在传入 `objectId` 时自动保存的请求+响应快照。
- */
-interface ChatRecord {
-    /** 记录唯一 ID */
-    id: string;
-    /** 交互主体 ID */
-    objectId: string;
-    /** 会话 ID */
-    sessionId: string;
-    /** 请求摘要 */
-    request: {
-        model: string;
-        messages: ChatMessage[];
-    };
-    /** 响应摘要 */
-    response: {
-        content: string;
-        toolCalls?: ToolCall[];
-        finishReason: string;
-        usage: TokenUsage;
-    };
-    /** 创建时间（Unix 毫秒） */
-    createdAt: number;
-    /** 耗时（毫秒） */
-    duration: number;
-}
-/**
- * LLM Provider 接口
- *
- * 底层 API 适配层，当前内置 OpenAI 兼容实现。
- */
-interface LLMProvider {
-    /** 发送聊天请求并获取完整响应 */
-    chat: (request: ChatCompletionRequest) => Promise<HaiResult<ChatCompletionResponse>>;
-    /** 发送聊天请求并获取流式响应（逐 chunk 产出） */
-    chatStream: (request: ChatCompletionRequest) => AsyncIterable<ChatCompletionChunk>;
-    /** 获取可用模型列表 */
-    listModels: () => Promise<HaiResult<string[]>>;
-}
-/**
- * 结构化输出请求
- *
- * 给定 Zod schema，让模型返回严格符合结构的 JSON（内部使用 `json_schema` response_format），
- * 解析失败时自动带错误修复重试，避免调用方手写 `JSON.parse` 的不稳定性。
- */
-interface GenerateObjectRequest<T> {
-    /** 输出结构的 Zod schema */
-    schema: ZodType<T>;
-    /** 对话消息 */
-    messages: ChatMessage[];
-    /** 模型名（可选，不传时使用默认模型） */
-    model?: string;
-    /** 系统提示词（可选，追加为首条 system 消息） */
-    systemPrompt?: string;
-    /** 温度覆盖 */
-    temperature?: number;
-    /** 临时模型配置 */
-    tempModel?: TempModelConfig;
-    /** schema 名称（用于 json_schema response_format，默认 `result`） */
-    schemaName?: string;
-    /** 解析失败时的修复重试次数（默认 1） */
-    maxRepairs?: number;
-    /** 取消信号 */
-    signal?: AbortSignal;
-}
-/**
- * LLM 操作接口（通过 `ai.llm` 访问）
- *
- * 需要先调用 `ai.init()` 初始化，否则返回 `NOT_INITIALIZED` 错误。
- */
-interface LLMOperations {
-    /** 发送聊天请求，返回 `HaiResult<ChatCompletionResponse>` */
-    chat: (request: ChatCompletionRequest) => Promise<HaiResult<ChatCompletionResponse>>;
-    /** 发送流式聊天请求，逐 chunk 产出 `ChatCompletionChunk` */
-    chatStream: (request: ChatCompletionRequest) => AsyncIterable<ChatCompletionChunk>;
-    /** 获取可用模型名称列表 */
-    listModels: () => Promise<HaiResult<string[]>>;
-    /** 查询对话历史记录（需传入 objectId；可选 sessionId 以按会话过滤） */
-    getHistory: (scope: InteractionScope, options?: ChatHistoryOptions) => Promise<HaiResult<ChatRecord[]>>;
-    /** 列出指定 objectId 下的所有会话 */
-    listSessions: (objectId: string) => Promise<HaiResult<SessionInfo[]>>;
-    /**
-     * 便捷方法：发送纯文本问题，返回回复文本
-     *
-     * 内部构建 ChatCompletionRequest 并调用 `chat()`，只返回第一个 choice 的文本。
-     *
-     * @param question - 用户问题文本
-     * @param options - 可选的模型、systemPrompt、objectId、sessionId 等
-     * @returns 回复文本
-     */
-    ask: (question: string, options?: AskOptions) => Promise<HaiResult<string>>;
-    /**
-     * 便捷方法：流式发送纯文本问题，返回文本片段异步迭代器
-     *
-     * @param question - 用户问题文本
-     * @param options - 可选配置
-     * @returns 文本片段的异步迭代器
-     */
-    askStream: (question: string, options?: AskOptions) => AsyncIterable<string>;
-    /**
-     * 结构化输出：按 Zod schema 约束模型输出并解析为对象
-     *
-     * 内部使用 `json_schema` response_format 约束输出，解析/校验失败时自动带错误提示重试。
-     *
-     * @param request - 包含 schema、messages 及可选模型/修复次数等
-     * @returns 符合 schema 的对象；多次重试仍无法解析时返回 `INVALID_REQUEST`
-     */
-    generateObject: <T>(request: GenerateObjectRequest<T>) => Promise<HaiResult<T>>;
-}
-/** LLM 子功能工厂依赖（内部使用） */
-interface AILLMFunctionsDeps {
-    /** 校验后的 AI 配置 */
-    config: AIConfig;
-}
-
-/**
- * @h-ai/ai — Retrieval 子功能类型
- *
- * 定义检索操作的类型接口，支持向量检索和混合检索。
- * @module ai-retrieval-types
- */
-
-/**
- * 信源引用——结构化描述检索结果的来源信息
- *
- * 用于在 RAG 回答中追踪每段内容的出处。
- *
- * @example
- * ```ts
- * const citation: Citation = {
- *   documentId: 'doc-001',
- *   title: '项目文档',
- *   url: 'https://docs.example.com/project',
- *   position: 'section:2',
- *   chunkId: 'chunk-003',
- * }
- * ```
- */
-interface Citation {
-    /** 原始文档 ID（入库时的文档级唯一标识） */
-    documentId?: string;
-    /** 原始文档标题 */
-    title?: string;
-    /** 原始文档 URL / 路径 */
-    url?: string;
-    /** 位置信息（页码、段落、section 等） */
-    position?: string;
-    /** 分块 ID（对应 vecdb 中的向量记录 ID） */
-    chunkId?: string;
-    /** 信源集合名 */
-    collection?: string;
-}
-/**
- * 检索源——描述一个可查询的知识来源
- */
-interface RetrievalSource {
-    /** 来源唯一标识 */
-    id: string;
-    /** collection / table 名称 */
-    collection: string;
-    /** 信源显示名（用于 UI 展示） */
-    name?: string;
-    /** 信源 URL / 路径 */
-    url?: string;
-    /** 最大返回条数（默认 5） */
-    topK?: number;
-    /** 最低相似度（低于此值的结果被过滤） */
-    minScore?: number;
-    /** 元数据过滤条件 */
-    filter?: Record<string, unknown>;
-}
-/**
- * 检索请求参数
- */
-interface RetrievalRequest {
-    /** 查询文本 */
-    query: string;
-    /** 使用的检索源（不指定则使用全部已注册源） */
-    sources?: string[];
-    /** 全局 topK 覆盖 */
-    topK?: number;
-    /** 全局 minScore 覆盖 */
-    minScore?: number;
-    /** 是否启用 Rerank 重排序（需要已初始化 ai.rerank） */
-    enableRerank?: boolean;
-    /** Rerank 使用的模型名称覆盖 */
-    rerankModel?: string;
-}
-/**
- * 单条检索结果
- */
-interface RetrievalResultItem {
-    /** 文档 ID */
-    id: string;
-    /** 内容文本 */
-    content: string;
-    /** 相似度分数 [0, 1] */
-    score: number;
-    /** 来源 id */
-    sourceId: string;
-    /** 元数据 */
-    metadata?: Record<string, unknown>;
-    /** 结构化信源引用 */
-    citation?: Citation;
-}
-/**
- * 检索结果
- */
-interface RetrievalResult {
-    /** 检索结果列表（按分数降序） */
-    items: RetrievalResultItem[];
-    /** 查询文本 */
-    query: string;
-    /** 查询耗时（毫秒） */
-    duration: number;
-}
-/**
- * 检索操作接口
- */
-interface RetrievalOperations {
-    /**
-     * 注册一个检索源（持久化到 DB）
-     *
-     * @param source - 检索源配置
-     * @returns 成功返回 ok，重复 id 返回错误
-     */
-    addSource: (source: RetrievalSource) => Promise<HaiResult<void>>;
-    /**
-     * 移除一个检索源（从 DB 删除）
-     *
-     * @param sourceId - 检索源 ID
-     * @returns 成功返回 ok，未找到返回错误
-     */
-    removeSource: (sourceId: string) => Promise<HaiResult<void>>;
-    /**
-     * 列出所有已注册的检索源（从 DB 读取，分布式一致）
-     */
-    listSources: () => Promise<RetrievalSource[]>;
-    /**
-     * 执行检索
-     *
-     * @param request - 检索请求
-     * @returns 检索结果
-     */
-    retrieve: (request: RetrievalRequest) => Promise<HaiResult<RetrievalResult>>;
-}
-
-/**
- * @h-ai/ai — Knowledge 子功能类型
- *
- * 定义知识库操作的类型接口：文档导入、实体索引、信源追踪检索。
- * @module ai-knowledge-types
- */
-
-/**
- * 内置实体类型枚举（预设值，可通过配置 `entityTypes` 扩展）
- */
-declare const EntityTypeSchema: z.ZodEnum<{
-    event: "event";
-    person: "person";
-    project: "project";
-    concept: "concept";
-    organization: "organization";
-    location: "location";
-    other: "other";
-}>;
-/** 实体类型（字符串，支持内置类型及用户自定义类型） */
-type EntityType = string;
-/**
- * 知识实体
- *
- * 表示从文档中提取的命名实体（人名、项目名、概念等），
- * 存储在 KnowledgeStore 中用于倒排索引查询。
- *
- * @example
- * ```ts
- * const entity: KnowledgeEntity = {
- *   id: 'ent-001',
- *   name: '张三',
- *   type: 'person',
- *   aliases: ['小张', 'Zhang San'],
- * }
- * ```
- */
-interface KnowledgeEntity {
-    /** 实体唯一标识 */
-    id: string;
-    /** 实体名称 */
-    name: string;
-    /** 实体类型 */
-    type: EntityType;
-    /** 别名列表（可选） */
-    aliases?: string[];
-    /** 描述（可选） */
-    description?: string;
-    /** 创建时间 */
-    createdAt?: string;
-    /** 更新时间 */
-    updatedAt?: string;
-}
-/**
- * 文档-实体关联记录
- *
- * 倒排索引中的一条记录，记录实体与文档/分块的关联关系。
- */
-interface EntityDocumentRelation {
-    /** 实体 ID */
-    entityId: string;
-    /** 文档 ID（对应向量存储中的 documentId） */
-    documentId: string;
-    /** 分块 ID（对应向量存储中的向量记录 ID） */
-    chunkId?: string;
-    /** 集合名 */
-    collection: string;
-    /** 关联强度 [0, 1]（默认 1.0） */
-    relevance?: number;
-    /** 实体在该文档中的上下文片段（可选） */
-    context?: string;
-    /** 创建时间 */
-    createdAt?: string;
-}
-/**
- * 知识库初始化选项
- */
-interface KnowledgeSetupOptions {
-    /** 集合名（可选，默认使用配置中的 collection） */
-    collection?: string;
-    /** 向量维度（可选，默认使用配置中的 dimension） */
-    dimension?: number;
-}
-/**
- * 文档导入输入
- *
- * @example
- * ```ts
- * const input: KnowledgeIngestInput = {
- *   documentId: 'doc-001',
- *   content: '# 项目文档\n\n张三负责了核心模块...',
- *   title: '项目文档',
- *   url: 'https://docs.example.com/project',
- *   metadata: { author: '李四' },
- * }
- * ```
- */
-interface KnowledgeIngestInput {
-    /** 文档唯一标识（必填，用于关联信源和实体） */
-    documentId: string;
-    /** 文档原始内容文本 */
-    content: string;
-    /** 文档标题（可选，存入 metadata 用于信源展示） */
-    title?: string;
-    /** 文档 URL / 路径（可选，存入 metadata 用于信源展示） */
-    url?: string;
-    /** 集合名（可选，默认使用配置中的 collection） */
-    collection?: string;
-    /** 附加元数据（可选，合并到每个 chunk 的 metadata 中） */
-    metadata?: Record<string, unknown>;
-    /** 是否启用实体提取（可选，覆盖全局配置） */
-    enableEntityExtraction?: boolean;
-    /**
-     * 文本清洗选项（可选，覆盖全局配置默认值）
-     *
-     * 字段含义与 @h-ai/datapipe CleanOptionsInput 完全一致，
-     * 支持 removeHtml、removeUrls、normalizeWhitespace、customReplacements 等。
-     */
-    cleanOptions?: CleanOptionsInput;
-    /**
-     * 分块选项（可选，覆盖全局配置默认值）
-     *
-     * 字段含义与 @h-ai/datapipe ChunkOptionsInput 完全一致，
-     * 支持 mode、maxSize、overlap、separator、markdownMinLevel 等完整选项。
-     */
-    chunkOptions?: ChunkOptionsInput;
-}
-/**
- * 文档导入结果
- */
-interface KnowledgeIngestResult {
-    /** 文档 ID */
-    documentId: string;
-    /** 生成的分块数量 */
-    chunkCount: number;
-    /** 提取的实体列表（未启用实体提取时为空数组） */
-    entities: KnowledgeEntity[];
-    /** 处理耗时（毫秒） */
-    duration: number;
-}
-/**
- * 知识检索选项
- */
-interface KnowledgeRetrieveOptions {
-    /** 集合名（可选，默认使用配置中的 collection） */
-    collection?: string;
-    /** 返回的最大结果数（默认 10） */
-    topK?: number;
-    /** 最低相似度（默认无限制） */
-    minScore?: number;
-    /** 是否启用实体增强检索（默认 true） */
-    enableEntityBoost?: boolean;
-    /** 元数据过滤条件 */
-    filter?: Record<string, unknown>;
-}
-/**
- * 知识检索结果项
- */
-interface KnowledgeRetrieveItem {
-    /** 分块 ID */
-    id: string;
-    /** 分块内容 */
-    content: string;
-    /** 综合得分（向量相似度 + 实体加权） */
-    score: number;
-    /** 结构化信源引用 */
-    citation: Citation;
-    /** 元数据 */
-    metadata?: Record<string, unknown>;
-    /** 命中的实体名称列表（实体增强检索时填充） */
-    matchedEntities?: string[];
-}
-/**
- * 知识检索结果
- */
-interface KnowledgeRetrieveResult {
-    /** 检索结果列表（按综合分数降序） */
-    items: KnowledgeRetrieveItem[];
-    /** 去重后的信源引用列表 */
-    citations: Citation[];
-    /** 查询文本 */
-    query: string;
-    /** 查询耗时（毫秒） */
-    duration: number;
-}
-/**
- * 知识问答选项
- */
-interface KnowledgeAskOptions extends KnowledgeRetrieveOptions {
-    /** LLM 模型名称覆盖 */
-    model?: string;
-    /** 系统提示词覆盖 */
-    systemPrompt?: string;
-    /** 温度覆盖 */
-    temperature?: number;
-    /** 消息历史（多轮对话） */
-    messages?: ChatMessage[];
-}
-/**
- * 知识问答结果
- */
-interface KnowledgeAskResult {
-    /** LLM 生成的回答 */
-    answer: string;
-    /** 使用的上下文 */
-    context: KnowledgeRetrieveItem[];
-    /** 去重后的信源引用列表 */
-    citations: Citation[];
-    /** 查询文本 */
-    query: string;
-    /** 使用的模型 */
-    model: string;
-    /** Token 使用统计 */
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
-/**
- * 实体查询选项
- */
-interface EntityQueryOptions {
-    /** 集合名（可选，默认使用配置中的 collection） */
-    collection?: string;
-    /** 实体类型过滤 */
-    type?: EntityType;
-}
-/**
- * 实体关联文档结果
- */
-interface EntityDocumentResult {
-    /** 实体信息 */
-    entity: KnowledgeEntity;
-    /** 关联文档列表 */
-    documents: Array<{
-        documentId: string;
-        chunkId?: string;
-        collection: string;
-        relevance: number;
-        context?: string;
-    }>;
-}
-/**
- * 实体列表查询选项
- */
-interface EntityListOptions {
-    /** 集合名过滤（不指定则返回所有 collection 的实体） */
-    collection?: string;
-    /** 实体类型过滤 */
-    type?: EntityType;
-    /** 关键词搜索（模糊匹配实体名称和别名） */
-    keyword?: string;
-    /** 最大返回数 */
-    limit?: number;
-}
-/**
- * 文件导入输入（从文件路径读取内容后自动 ingest）
- *
- * 仅 Node.js 端可用。
- *
- * @example
- * ```ts
- * await knowledge.ingestFile({
- *   filePath: '/data/docs/README.md',
- *   documentId: 'readme',
- * })
- * ```
- */
-interface KnowledgeIngestFileInput {
-    /** 文件路径（绝对路径或相对路径） */
-    filePath: string;
-    /** 文档唯一标识（可选，默认从文件名派生） */
-    documentId?: string;
-    /** 文档标题（可选，默认为文件名） */
-    title?: string;
-    /** 文件编码（默认 'utf-8'） */
-    encoding?: BufferEncoding;
-    /** 集合名（可选，默认使用配置中的 collection） */
-    collection?: string;
-    /** 附加元数据 */
-    metadata?: Record<string, unknown>;
-    /** 是否启用实体提取 */
-    enableEntityExtraction?: boolean;
-    /** 清洗选项 */
-    cleanOptions?: CleanOptionsInput;
-    /** 分块选项 */
-    chunkOptions?: ChunkOptionsInput;
-}
-/**
- * 文档信息（列表展示用）
- */
-interface KnowledgeDocumentInfo {
-    /** 文档 ID */
-    documentId: string;
-    /** 文档标题 */
-    title?: string;
-    /** 文档来源 URL / 路径 */
-    url?: string;
-    /** 分块数量 */
-    chunkCount: number;
-    /** 关联实体数 */
-    entityCount: number;
-    /** 创建时间（Unix 毫秒） */
-    createdAt: number;
-}
-/**
- * 文档列表查询选项
- */
-interface KnowledgeDocumentListOptions {
-    /** 集合名覆盖（不指定则使用配置中的 default） */
-    collection?: string;
-    /** 偏移量 */
-    offset?: number;
-    /** 每页数量（默认 20） */
-    limit?: number;
-}
-/**
- * 文档删除选项
- */
-interface KnowledgeDocumentRemoveOptions {
-    /** 集合名覆盖 */
-    collection?: string;
-}
-/**
- * 批量导入进度回调参数
- */
-interface KnowledgeIngestBatchProgress {
-    /** 已完成数量 */
-    completed: number;
-    /** 总数量 */
-    total: number;
-    /** 当前文档 ID */
-    currentDocumentId: string;
-    /** 当前文档导入结果（失败时为 undefined） */
-    result?: KnowledgeIngestResult;
-    /** 当前文档导入错误（成功时为 undefined） */
-    error?: HaiError;
-}
-/**
- * 批量导入结果
- */
-interface KnowledgeIngestBatchResult {
-    /** 成功导入的文档数 */
-    successCount: number;
-    /** 失败的文档数 */
-    failureCount: number;
-    /** 各文档导入结果 */
-    results: Array<{
-        documentId: string;
-        result?: KnowledgeIngestResult;
-        error?: HaiError;
-    }>;
-    /** 总耗时（毫秒） */
-    duration: number;
-}
-/**
- * Knowledge 操作接口（通过 `ai.knowledge` 访问）
- *
- * 知识库管理与检索的统一入口，编排 datapipe + KnowledgeStore + embedding + LLM。
- *
- * ## 生命周期
- *
- * 每个 collection 在使用前必须先调用 `setup()`，支持多次调用以初始化不同分区：
- *
- * ```ts
- * await ai.knowledge.setup()                          // 使用配置默认 collection
- * await ai.knowledge.setup({ collection: 'kb-prod' }) // 初始化额外分区
- * ```
- *
- * ## 单 collection 示例
- *
- * ```ts
- * // 初始化
- * await ai.knowledge.setup()
- *
- * // 导入文档
- * await ai.knowledge.ingest({
- *   documentId: 'doc-001',
- *   content: markdownContent,
- *   title: '项目文档',
- * })
- *
- * // 查询（带信源追踪）
- * const result = await ai.knowledge.retrieve('张三负责了哪些模块？')
- *
- * // 问答（RAG + 信源引用）
- * const answer = await ai.knowledge.ask('张三负责了哪些模块？')
- * ```
- *
- * ## 多 collection（多分区）示例
- *
- * ```ts
- * // 分别初始化两个知识库分区
- * await ai.knowledge.setup({ collection: 'kb-product' })
- * await ai.knowledge.setup({ collection: 'kb-support' })
- *
- * // 写入不同分区
- * await ai.knowledge.ingest({ documentId: 'p-001', content: '...', collection: 'kb-product' })
- * await ai.knowledge.ingest({ documentId: 's-001', content: '...', collection: 'kb-support' })
- *
- * // 从指定分区检索（对未 setup 的 collection 发起任何操作都会返回 KNOWLEDGE_NOT_SETUP 错误）
- * const result = await ai.knowledge.retrieve('query', { collection: 'kb-support' })
- * ```
- */
-interface KnowledgeOperations {
-    /**
-     * 初始化知识库（幂等，支持多次调用以初始化不同 collection）
-     *
-     * 创建向量集合和实体表。每个 collection 需独立调用本方法，
-     * 未 setup 的 collection 执行以下操作时均会返回 `KNOWLEDGE_NOT_SETUP` 错误：
-     * `ingest` / `ingestFile` / `ingestBatch` / `retrieve` / `ask` /
-     * `findByEntity` / `listDocuments` / `removeDocument`。
-     *
-     * @param options - 初始化选项（collection 名称、向量维度）
-     * @returns 成功返回 ok(undefined)
-     */
-    setup: (options?: KnowledgeSetupOptions) => Promise<HaiResult<void>>;
-    /**
-     * 导入文档
-     *
-     * 执行流程：clean → chunk → embed → 向量存储 → 实体提取 → 实体存储
-     *
-     * @param input - 文档导入输入
-     * @returns 导入结果（分块数、实体列表等）
-     */
-    ingest: (input: KnowledgeIngestInput) => Promise<HaiResult<KnowledgeIngestResult>>;
-    /**
-     * 知识检索（带实体增强 + 信源追踪）
-     *
-     * @param query - 查询文本
-     * @param options - 检索选项
-     * @returns 检索结果（带 citations）
-     */
-    retrieve: (query: string, options?: KnowledgeRetrieveOptions) => Promise<HaiResult<KnowledgeRetrieveResult>>;
-    /**
-     * 知识问答（RAG + 信源引用）
-     *
-     * @param query - 用户问题
-     * @param options - 问答选项
-     * @returns 问答结果（回答 + 信源）
-     */
-    ask: (query: string, options?: KnowledgeAskOptions) => Promise<HaiResult<KnowledgeAskResult>>;
-    /**
-     * 按实体查询关联文档
-     *
-     * @param entityName - 实体名称
-     * @param options - 查询选项
-     * @returns 实体关联文档列表
-     */
-    findByEntity: (entityName: string, options?: EntityQueryOptions) => Promise<HaiResult<EntityDocumentResult[]>>;
-    /**
-     * 列出所有实体
-     *
-     * @param options - 列表选项
-     * @returns 实体列表
-     */
-    listEntities: (options?: EntityListOptions) => Promise<HaiResult<KnowledgeEntity[]>>;
-    /**
-     * 列出已导入的文档列表
-     *
-     * @param options - 列表选项
-     * @returns 文档信息列表
-     */
-    listDocuments: (options?: KnowledgeDocumentListOptions) => Promise<HaiResult<KnowledgeDocumentInfo[]>>;
-    /**
-     * 删除已导入的文档（同时删除向量和实体关联）
-     *
-     * @param documentId - 文档 ID
-     * @param options - 删除选项
-     * @returns 成功返回 ok(undefined)
-     */
-    removeDocument: (documentId: string, options?: KnowledgeDocumentRemoveOptions) => Promise<HaiResult<void>>;
-    /**
-     * 从文件路径导入文档（仅 Node.js 端可用）
-     *
-     * 读取文件内容后自动调用 ingest() 完成导入。
-     *
-     * @param input - 文件导入输入
-     * @returns 导入结果
-     */
-    ingestFile: (input: KnowledgeIngestFileInput) => Promise<HaiResult<KnowledgeIngestResult>>;
-    /**
-     * 批量导入文档
-     *
-     * 依次执行 ingest()，通过 onProgress 回调报告进度，单个文档失败不中断整体流程。
-     *
-     * @param inputs - 文档导入输入列表
-     * @param onProgress - 每完成一个文档后的回调
-     * @returns 批量导入汇总结果
-     */
-    ingestBatch: (inputs: KnowledgeIngestInput[], onProgress?: (progress: KnowledgeIngestBatchProgress) => void) => Promise<HaiResult<KnowledgeIngestBatchResult>>;
-    /**
-     * 删除整个 collection（幂等）
-     *
-     * 同时清除：vecdb 向量集合、实体-文档关联、文档元数据、collection 注册记录。
-     * 删除后 collection 需重新执行 `setup` 才可使用。
-     *
-     * @param collection - 要删除的 collection 名称，默认使用 config.collection
-     * @returns 成功返回 ok(undefined)；store 不可用时返回 `KNOWLEDGE_SETUP_FAILED`
-     */
-    deleteCollection: (collection?: string) => Promise<HaiResult<void>>;
-}
-
-/**
- * @h-ai/ai — Memory 子功能类型
- *
- * 定义记忆管理操作的类型接口：提取、存储、检索、注入。
- * 支持从对话中自动提取关键事实、偏好、事件等记忆，并在后续对话中检索注入。
- * @module ai-memory-types
- */
-
-/**
- * 记忆类型枚举 Schema
- *
- * 定义系统支持的五种记忆类型，用于对提取和存储的记忆进行分类：
- * - `fact` — 客观事实（如「用户是后端工程师」「项目使用 TypeScript」）
- * - `preference` — 用户偏好（如「喜欢简洁的代码风格」「偏好中文回复」）
- * - `event` — 事件/时间线信息（如「上周部署了 v2.0」「昨天修复了登录 Bug」）
- * - `entity` — 命名实体（如人名、产品名、组织名等，便于后续实体关联）
- * - `instruction` — 用户给出的持久指令（如「以后都用函数式写法」「回复不超过 200 字」）
- *
- * @example
- * ```ts
- * import { MemoryTypeSchema } from '@h-ai/ai'
- *
- * // 校验字符串是否为合法记忆类型
- * const result = MemoryTypeSchema.safeParse('preference') // { success: true }
- *
- * // 用于配置或过滤
- * await ai.memory.recall('编程语言', { types: ['preference', 'fact'] })
- * ```
- */
-declare const MemoryTypeSchema: z.ZodEnum<{
-    fact: "fact";
-    preference: "preference";
-    event: "event";
-    entity: "entity";
-    instruction: "instruction";
-}>;
-/** 记忆类型 */
-type MemoryType = z.infer<typeof MemoryTypeSchema>;
-/**
- * 记忆条目输入（手动添加时使用）
- *
- * @example
- * ```ts
- * const input: MemoryEntryInput = {
- *   content: '用户偏好使用中文回复',
- *   type: 'preference',
- *   importance: 0.8,
- *   objectId: 'user-001',
- * }
- * ```
- */
-interface MemoryEntryInput {
-    /** 记忆内容 */
-    content: string;
-    /** 记忆类型 */
-    type: MemoryType;
-    /** 重要性评分 [0, 1]（可选，默认 0.5） */
-    importance?: number;
-    /** 所属主体 ID（不指定时为全局记忆） */
-    objectId?: string;
-    /** 作用域（JSON 对象，key-value 匹配过滤。用于子 session 记忆隔离等场景） */
-    scope?: Record<string, unknown>;
-    /** 附加元数据 */
-    metadata?: Record<string, unknown>;
-}
-/**
- * 完整的记忆条目
- */
-interface MemoryEntry {
-    /** 记忆唯一标识 */
-    id: string;
-    /** 记忆内容 */
-    content: string;
-    /** 记忆类型 */
-    type: MemoryType;
-    /** 重要性评分 [0, 1] */
-    importance: number;
-    /** 所属主体 ID */
-    objectId?: string;
-    /** 作用域（JSON 对象，key-value 匹配过滤。用于子 session 记忆隔离等场景） */
-    scope?: Record<string, unknown>;
-    /** 附加元数据 */
-    metadata?: Record<string, unknown>;
-    /** 向量（embedding 已计算时填充） */
-    vector?: number[];
-    /** 创建时间（Unix 毫秒） */
-    createdAt: number;
-    /** 最近访问时间（Unix 毫秒） */
-    lastAccessedAt: number;
-    /** 被检索次数 */
-    accessCount: number;
-}
-/**
- * 记忆提取选项
- */
-interface MemoryExtractOptions {
-    /** 只提取指定类型 */
-    types?: MemoryType[];
-    /** 指定提取用的模型 */
-    model?: string;
-    /** 自定义提取 systemPrompt（覆盖模块配置与内置默认提示词） */
-    systemPrompt?: string;
-    /** 过滤低重要性条目（默认 0） */
-    minImportance?: number;
-    /** 所属主体 ID（关联到提取结果） */
-    objectId?: string;
-    /** 作用域（JSON 对象，提取的记忆将关联此 scope） */
-    scope?: Record<string, unknown>;
-    /**
-     * 临时模型配置（携带凭据的模型请求）。
-     *
-     * 用于传递运行时解析的 apiKey / baseUrl 等凭证，
-     * 避免回退到全局 .env 配置。优先级高于全局 config.models 查找。
-     */
-    tempModel?: TempModelConfig;
-    /** 取消整条记忆提取链（包括事实抽取与 native 对账 LLM 调用） */
-    signal?: AbortSignal;
-}
-/**
- * 记忆检索选项
- */
-interface MemoryRecallOptions {
-    /** 返回数量（默认使用配置的 defaultTopK） */
-    topK?: number;
-    /**
-     * 候选池倍数（覆盖配置的 candidateMultiplier）
-     *
-     * 检索时先取回 `topK × candidateMultiplier` 条候选再按 scope / 类型 / 重要性过滤，
-     * 最后截取 topK。scope 过滤较严（如按 topic / persona 隔离）时应调大，避免漏召回。
-     */
-    candidateMultiplier?: number;
-    /** 过滤类型 */
-    types?: MemoryType[];
-    /** 最低重要性 */
-    minImportance?: number;
-    /** 时间衰减权重 [0, 1]（0 = 不考虑时间，1 = 仅按时间排序） */
-    recencyWeight?: number;
-    /** 限定主体 ID */
-    objectId?: string;
-    /** 限定作用域（key-value 匹配过滤，用于子 session 记忆隔离等场景） */
-    scope?: Record<string, unknown>;
-}
-/**
- * 记忆注入选项（`injectMemories` 使用）
- *
- * 控制记忆注入行为：检索数量、Token 预算、注入位置等。
- */
-interface MemoryInjectionOptions {
-    /** 注入的记忆数量（默认 5） */
-    topK?: number;
-    /**
-     * 候选池倍数（覆盖配置的 candidateMultiplier）
-     *
-     * 透传给底层 `recall`，scope 过滤较严时应调大以避免漏召回。
-     */
-    candidateMultiplier?: number;
-    /** 记忆占用的最大 token 预算（默认不限） */
-    maxTokens?: number;
-    /** 注入位置：system = 追加到 system 消息末尾，before-last = 插入在最后一条用户消息之前 */
-    position?: 'system' | 'before-last';
-    /** 限定主体 ID */
-    objectId?: string;
-    /** 限定作用域（key-value 匹配过滤，用于子 session 记忆隔离等场景） */
-    scope?: Record<string, unknown>;
-    /** 限定记忆类型 */
-    types?: MemoryType[];
-    /** 最低重要性阈值 */
-    minImportance?: number;
-}
-/**
- * 记忆列表选项
- */
-interface MemoryListOptions {
-    /** 过滤类型 */
-    types?: MemoryType[];
-    /** 限定主体 ID */
-    objectId?: string;
-    /** 限定作用域（key-value 匹配过滤，用于子 session / 主题 / 角色记忆隔离等场景） */
-    scope?: Record<string, unknown>;
-    /** 最大返回数 */
-    limit?: number;
-}
-/**
- * 记忆分页选项
- */
-interface MemoryListPageOptions {
-    /** 过滤类型 */
-    types?: MemoryType[];
-    /** 限定主体 ID */
-    objectId?: string;
-    /** 限定作用域（key-value 匹配过滤，用于子 session / 主题 / 角色记忆隔离等场景） */
-    scope?: Record<string, unknown>;
-    /** 偏移量 */
-    offset?: number;
-    /** 每页数量（默认 20） */
-    limit?: number;
-}
-/**
- * 记忆清空选项
- *
- * 安全语义：未传任何过滤条件时清空全部；传入 objectId / types / scope 时
- * 仅删除同时匹配所有给定条件的记忆，避免误删其他主体或类型的记忆。
- */
-interface MemoryClearOptions {
-    /** 仅清空指定类型 */
-    types?: MemoryType[];
-    /** 仅清空指定主体 */
-    objectId?: string;
-    /** 仅清空匹配指定作用域的记忆（key-value 匹配过滤） */
-    scope?: Record<string, unknown>;
-}
-/**
- * 记忆条目更新输入
- *
- * 所有字段均为可选，仅传入需要更新的字段。
- */
-interface MemoryUpdateInput {
-    /** 更新记忆内容（同时重新计算向量） */
-    content?: string;
-    /** 更新记忆类型 */
-    type?: MemoryType;
-    /** 更新重要性 */
-    importance?: number;
-    /** 更新元数据 */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Memory 操作接口（通过 `ai.memory` 访问）
- *
- * 管理对话中产生的关键事实、用户偏好、长期知识的提取、存储与检索。
- * 需要先调用 `ai.init()` 初始化后使用。
- *
- * @example
- * ```ts
- * // 从对话中自动提取记忆
- * const extracted = await ai.memory.extract(messages, {
- *   objectId: 'user-001',
- *   systemPrompt: 'Only extract durable user preferences and explicit long-term instructions.',
- * })
- *
- * // 手动添加记忆
- * await ai.memory.add({ content: '用户偏好中文', type: 'preference', objectId: 'user-001' })
- *
- * // 检索相关记忆
- * const memories = await ai.memory.recall('用户的语言偏好', { objectId: 'user-001' })
- *
- * // 将记忆注入消息列表
- * const enriched = await ai.memory.injectMemories(newMessages, { objectId: 'user-001' })
- * const response = await ai.llm.chat({ messages: enriched.value })
- * ```
- */
-/**
- * 按 ID 访问单条记忆（get / update / remove）时的归属校验作用域。
- *
- * 传入后，Provider 先读取记忆再校验：`entry.objectId` 必须等于 `objectId`，且 `entry.scope`
- * 包含 `scope` 的全部 key-value；不匹配时统一返回 `MEMORY_NOT_FOUND`（避免通过错误差异
- * 枚举其他主体的记忆）。不传时不做归属校验（向后兼容）；处理不可信输入的 memoryId 时必须传入。
- */
-interface MemoryAccessScope {
-    /** 归属主体 ID（必须与记忆 entry.objectId 一致） */
-    objectId: string;
-    /** 业务作用域（entry.scope 必须包含这些 key-value） */
-    scope?: Record<string, unknown>;
-}
-/**
- * 记忆作用域绑定（`ai.memory.scoped()` 使用）
- *
- * 绑定后，所有操作自动携带 `objectId` 与 `scope`，无需每次手动传入，
- * 从根本上避免「忘记传 objectId 导致跨租户越权」的安全隐患。
- */
-interface ScopedMemoryBinding {
-    /** 归属主体 ID（所有操作自动绑定） */
-    objectId: string;
-    /** 业务作用域（所有操作自动绑定并作为归属校验的一部分，如 `{ topicId, personaId }`） */
-    scope?: Record<string, unknown>;
-}
-/**
- * 全局清空选项（`ai.memory.admin.clearAll()` 使用）
- *
- * 危险操作：清空整个记忆后端的全部数据。必须显式传入 `confirm: true`，
- * 防止误调用；普通 `clear()` 不再支持通过省略参数隐式清空全局。
- */
-interface MemoryClearAllOptions {
-    /** 必须显式为 `true`，否则拒绝执行 */
-    confirm: true;
-}
-/**
- * 记忆管理接口（`ai.memory.admin`）
- *
- * 承载危险的全局操作，与业务作用域操作明确分离。
- */
-interface MemoryAdminOperations {
-    /**
-     * 清空整个记忆后端的全部数据（跨所有主体 / 作用域）
-     *
-     * @param options - 必须传入 `{ confirm: true }`
-     * @returns 成功返回 ok(undefined)；未确认返回 MEMORY_STORE_FAILED
-     */
-    clearAll: (options: MemoryClearAllOptions) => Promise<HaiResult<void>>;
-}
-/**
- * 记忆核心操作（Provider 实现层）
- *
- * 各 Provider（native / mem0）实现这一组操作。公共入口 `ai.memory` 在其基础上
- * 叠加作用域绑定（`scoped`）与管理接口（`admin`），并对 `clear` 施加空过滤保护。
- */
-interface MemoryCoreOperations {
-    /**
-     * 从对话消息中自动提取记忆条目
-     *
-     * 使用 LLM 分析对话内容，提取值得记住的事实、偏好、事件等。
-     * 提取的记忆会自动持久化到 Store（含向量计算）。
-     *
-     * @param messages - 对话消息列表
-     * @param options - 提取选项
-     * @returns 提取到的记忆条目列表
-     */
-    extract: (messages: ChatMessage[], options?: MemoryExtractOptions) => Promise<HaiResult<MemoryEntry[]>>;
-    /**
-     * 根据查询检索最相关的记忆
-     *
-     * 综合向量相似度、重要性、时间衰减进行排序。
-     *
-     * @param query - 查询文本
-     * @param options - 检索选项
-     * @returns 相关记忆列表
-     */
-    recall: (query: string, options?: MemoryRecallOptions) => Promise<HaiResult<MemoryEntry[]>>;
-    /**
-     * 将相关记忆注入到消息列表中
-     *
-     * 工作流程：
-     * 1. 从消息列表中提取最后一条用户消息作为检索查询
-     * 2. 调用 `recall` 检索最相关的记忆条目
-     * 3. 将记忆格式化为文本块，按指定位置注入消息列表
-     *
-     * @param messages - 原始消息列表
-     * @param options - 注入选项（数量、位置、Token 预算等）
-     * @returns 注入记忆后的新消息列表（不修改原数组）
-     */
-    injectMemories: (messages: ChatMessage[], options?: MemoryInjectionOptions) => Promise<HaiResult<ChatMessage[]>>;
-    /**
-     * 手动添加一条记忆
-     *
-     * 记忆会自动持久化到 Store（含向量计算）。
-     *
-     * @param entry - 记忆条目输入
-     * @returns 存储后的完整记忆条目
-     */
-    add: (entry: MemoryEntryInput) => Promise<HaiResult<MemoryEntry>>;
-    /**
-     * 更新一条已有记忆
-     *
-     * 仅更新传入的字段，其余字段保持不变。
-     * 若 content 被更新，会重新计算向量。
-     * 更新结果自动持久化到 Store。
-     *
-     * @param memoryId - 记忆 ID
-     * @param updates - 需要更新的字段
-     * @param accessScope - 可选归属校验（不匹配返回 MEMORY_NOT_FOUND）
-     * @returns 更新后的完整记忆条目
-     */
-    update: (memoryId: string, updates: MemoryUpdateInput, accessScope?: MemoryAccessScope) => Promise<HaiResult<MemoryEntry>>;
-    /**
-     * 按 ID 获取单条记忆
-     *
-     * @param memoryId - 记忆 ID
-     * @param accessScope - 可选归属校验（不匹配返回 MEMORY_NOT_FOUND）
-     * @returns 记忆条目，不存在时返回 MEMORY_NOT_FOUND
-     */
-    get: (memoryId: string, accessScope?: MemoryAccessScope) => Promise<HaiResult<MemoryEntry>>;
-    /**
-     * 删除单条记忆
-     *
-     * 同时从 Store 中移除持久化数据。
-     *
-     * @param memoryId - 记忆 ID
-     * @param accessScope - 可选归属校验（不匹配返回 MEMORY_NOT_FOUND）
-     * @returns 成功返回 ok(undefined)
-     */
-    remove: (memoryId: string, accessScope?: MemoryAccessScope) => Promise<HaiResult<void>>;
-    /**
-     * 获取记忆列表
-     *
-     * @param options - 列表选项
-     * @returns 记忆条目列表
-     */
-    list: (options?: MemoryListOptions) => Promise<HaiResult<MemoryEntry[]>>;
-    /**
-     * 分页获取记忆列表
-     *
-     * @param options - 分页选项
-     * @returns 分页结果
-     */
-    listPage: (options?: MemoryListPageOptions) => Promise<HaiResult<StorePage<MemoryEntry>>>;
-    /**
-     * 清空记忆
-     *
-     * 同时从 Store 中移除持久化数据。
-     *
-     * @param options - 清空选项（可按类型/主体过滤）
-     */
-    clear: (options?: MemoryClearOptions) => Promise<HaiResult<void>>;
-}
-/**
- * 作用域绑定的记忆操作（`ai.memory.scoped()` 返回）
- *
- * 所有操作自动携带绑定的 `objectId` 与 `scope`，无需重复传入；`get` / `update` / `remove`
- * 自动施加归属校验（跨租户访问返回 `MEMORY_NOT_FOUND`）；`clear` 仅清空绑定作用域内的记忆，
- * 永远不会误清全局。
- */
-interface ScopedMemoryOperations {
-    /** 从对话中提取记忆（自动绑定 objectId / scope） */
-    extract: (messages: ChatMessage[], options?: Omit<MemoryExtractOptions, 'objectId' | 'scope'>) => Promise<HaiResult<MemoryEntry[]>>;
-    /** 检索相关记忆（自动绑定 objectId / scope） */
-    recall: (query: string, options?: Omit<MemoryRecallOptions, 'objectId' | 'scope'>) => Promise<HaiResult<MemoryEntry[]>>;
-    /** 注入相关记忆（自动绑定 objectId / scope） */
-    injectMemories: (messages: ChatMessage[], options?: Omit<MemoryInjectionOptions, 'objectId' | 'scope'>) => Promise<HaiResult<ChatMessage[]>>;
-    /** 添加记忆（自动绑定 objectId / scope） */
-    add: (entry: Omit<MemoryEntryInput, 'objectId' | 'scope'>) => Promise<HaiResult<MemoryEntry>>;
-    /** 更新记忆（自动施加归属校验） */
-    update: (memoryId: string, updates: MemoryUpdateInput) => Promise<HaiResult<MemoryEntry>>;
-    /** 按 ID 获取记忆（自动施加归属校验） */
-    get: (memoryId: string) => Promise<HaiResult<MemoryEntry>>;
-    /** 删除记忆（自动施加归属校验） */
-    remove: (memoryId: string) => Promise<HaiResult<void>>;
-    /** 列出记忆（自动绑定 objectId / scope） */
-    list: (options?: Omit<MemoryListOptions, 'objectId' | 'scope'>) => Promise<HaiResult<MemoryEntry[]>>;
-    /** 分页列出记忆（自动绑定 objectId / scope） */
-    listPage: (options?: Omit<MemoryListPageOptions, 'objectId' | 'scope'>) => Promise<HaiResult<StorePage<MemoryEntry>>>;
-    /** 清空绑定作用域内的记忆（自动绑定 objectId / scope，不会误清全局） */
-    clear: (options?: Omit<MemoryClearOptions, 'objectId' | 'scope'>) => Promise<HaiResult<void>>;
-}
-/**
- * 公共记忆操作接口（通过 `ai.memory` 访问）
- *
- * 在核心操作基础上增加：
- * - `scoped(binding)`：返回自动绑定 objectId / scope 的安全实例（多租户推荐入口）；
- * - `admin`：承载危险的全局操作（如 `clearAll`）；
- * - `clear`：拒绝空过滤调用（无 objectId / types / scope 时返回错误），防止误清全局。
- */
-interface MemoryOperations extends MemoryCoreOperations {
-    /**
-     * 创建绑定作用域的记忆实例
-     *
-     * @param binding - 作用域绑定（objectId + 可选 scope）
-     * @returns 所有操作自动携带该作用域的记忆实例
-     */
-    scoped: (binding: ScopedMemoryBinding) => ScopedMemoryOperations;
-    /** 管理接口（危险的全局操作，需显式确认） */
-    admin: MemoryAdminOperations;
-}
-
-/**
- * @h-ai/ai — 错误码 + 配置 Schema
- *
- * 定义 AI 模块的错误码常量、Zod Schema 和配置类型。
- * @module ai-config
- */
-
-/**
- * 可选密钥 Schema。
- *
- * 配置文件中的空插值、空白字符串或 YAML null 都表示“未配置”，输出统一为 undefined；
- * 非空密钥保持原值，避免模块调用方重复编写兼容清洗逻辑。
- */
-declare const OptionalSecretSchema: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-/**
- * 模型场景枚举
- *
- * 预定义的模型使用场景，用于自动选择合适的模型。
- *
- * - `default` — 默认场景（兜底）
- * - `chat` — 对话场景
- * - `reasoning` — 推理场景（ReAct、CoT，需要强逻辑能力）
- * - `plan` — Plan-Execute 规划阶段（需要强推理）
- * - `execute` — Plan-Execute 执行阶段（需要工具调用能力）
- * - `extraction` — 信息提取场景（记忆提取、实体抽取）
- * - `summary` — 摘要/压缩场景（上下文摘要）
- * - `embedding` — 向量嵌入场景
- * - `rerank` — 文档重排序场景
- * - `ocr` — 图片 OCR 识别场景（视觉模型）
- * - `fast` — 快速响应场景（低延迟优先）
- */
-declare const ModelScenarioSchema: z.ZodEnum<{
-    chat: "chat";
-    default: "default";
-    reasoning: "reasoning";
-    plan: "plan";
-    execute: "execute";
-    extraction: "extraction";
-    summary: "summary";
-    embedding: "embedding";
-    rerank: "rerank";
-    ocr: "ocr";
-    fast: "fast";
-}>;
-/** 模型场景类型 */
-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
- *
- * 定义单个模型的配置信息，包含唯一 ID、模型名称和可选参数覆盖。
- *
- * @example
- * ```ts
- * const model = {
- *   id: 'gpt-4o',
- *   model: 'gpt-4o',
- *   maxTokens: 8192,
- *   temperature: 0.3,
- * }
- * ```
- */
-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.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-    baseUrl: z.ZodOptional<z.ZodURL>;
-    maxTokens: z.ZodOptional<z.ZodNumber>;
-    temperature: z.ZodOptional<z.ZodNumber>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-/** 模型条目类型 */
-type ModelEntry = z.infer<typeof ModelEntrySchema>;
-/**
- * LLM 配置 Schema
- *
- * 配置大模型调用参数：模型名称、API Key、Base URL、温度等。
- * 支持多模型注册和场景映射。
- *
- * 顶层 `apiKey`、`baseUrl`、`maxTokens`、`temperature`、`timeout` 作为全局默认值，
- * 当 `models` 条目中未指定对应字段时，自动回退到这些全局默认值。
- * 通过 `resolveModelEntry()` 统一解析。
- *
- * @example
- * ```ts
- * const llmConfig = {
- *   // 全局默认值（各模型未指定时回退到此处）
- *   apiKey: 'sk-xxx',
- *   baseUrl: 'https://api.openai.com/v1',
- *   model: 'gpt-4o-mini',
- *   maxTokens: 4096,
- *   temperature: 0.7,
- *   timeout: 60000,
- *   // 多模型注册（各字段可选，未指定时回退到全局默认值）
- *   models: [
- *     { id: 'fast', model: 'gpt-4o-mini', temperature: 0.3 },
- *     { id: 'strong', model: 'gpt-4o', maxTokens: 8192 },
- *     { id: 'rerank', model: 'rerank-english-v3.0', baseUrl: 'https://api.cohere.com' },
- *   ],
- *   // 场景映射（场景名 → 模型 ID 或模型名称）
- *   scenarios: { chat: 'fast', reasoning: 'strong', rerank: 'rerank' },
- * }
- * ```
- */
-declare const LLMConfigSchema: z.ZodObject<{
-    apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-    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>>;
-    tempModelCacheTtl: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    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.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-        baseUrl: z.ZodOptional<z.ZodURL>;
-        maxTokens: z.ZodOptional<z.ZodNumber>;
-        temperature: z.ZodOptional<z.ZodNumber>;
-        timeout: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>>;
-    scenarios: z.ZodOptional<z.ZodObject<{
-        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>;
-        extraction: z.ZodOptional<z.ZodString>;
-        summary: z.ZodOptional<z.ZodString>;
-        embedding: z.ZodOptional<z.ZodString>;
-        rerank: z.ZodOptional<z.ZodString>;
-        ocr: z.ZodOptional<z.ZodString>;
-        fast: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** LLM 配置类型 */
-type LLMConfig = z.infer<typeof LLMConfigSchema>;
-/**
- * 已解析的模型配置
- *
- * 由 `resolveModelEntry()` 返回，包含模型名称和完整的参数配置（已合并全局默认值和环境变量）。
- */
-interface ResolvedModelConfig {
-    /** 模型名称（传给 API 的实际模型名） */
-    model: string;
-    /** API 协议（模型条目 > 全局配置 > `chat`） */
-    api: ApiType;
-    /** API Key（模型条目 > 全局配置 > 环境变量） */
-    apiKey: string | undefined;
-    /** API 基础 URL（模型条目 > 全局配置 > 环境变量 > 默认 OpenAI） */
-    baseUrl: string;
-    /** 最大 Token 数（模型条目 > 全局配置） */
-    maxTokens: number;
-    /** 采样温度（模型条目 > 全局配置） */
-    temperature: number;
-    /** 请求超时时间（毫秒）（模型条目 > 全局配置） */
-    timeout: number;
-}
-/**
- * 必需模型解析选项
- */
-interface ResolveRequiredModelEntryOptions {
-    /** 缺少 API Key 时的自定义错误消息 */
-    missingApiKeyMessage?: string;
-}
-/**
- * 根据场景解析完整模型配置，并要求必须存在 API Key
- *
- * 用于需要访问远程模型 API 的场景，避免各子模块重复编写
- * `if (!resolved.apiKey)` 之类的配置校验逻辑。
- *
- * @param llmConfig - LLM 配置
- * @param scenario - 使用场景
- * @param explicit - 调用方显式指定的模型名称（最高优先级）
- * @param options - 必需校验选项
- * @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>>;
-    resources: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    prompts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-/** MCP 服务器能力类型 */
-type MCPServerCapabilities = z.infer<typeof MCPServerCapabilitiesSchema>;
-/** MCP 服务器配置 Schema */
-declare const MCPServerConfigSchema: z.ZodObject<{
-    name: z.ZodString;
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    capabilities: z.ZodOptional<z.ZodObject<{
-        tools: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-        resources: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-        prompts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** MCP 服务器配置类型 */
-type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
-/**
- * MCP 配置 Schema
- *
- * 配置 MCP（Model Context Protocol）服务器参数。
- *
- * @example
- * ```ts
- * const mcpConfig = {
- *   server: {
- *     name: 'my-app',
- *     version: '1.0.0',
- *     capabilities: { tools: true, resources: true, prompts: true },
- *   },
- * }
- * ```
- */
-declare const MCPConfigSchema: z.ZodObject<{
-    server: z.ZodOptional<z.ZodObject<{
-        name: z.ZodString;
-        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        capabilities: z.ZodOptional<z.ZodObject<{
-            tools: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-            resources: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-            prompts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** MCP 配置类型 */
-type MCPConfig = z.infer<typeof MCPConfigSchema>;
-/**
- * Embedding 配置 Schema
- *
- * 配置文本向量化参数。
- * 模型通过 LLMConfigSchema.scenarios.embedding 解析，
- * apiKey / baseUrl 统一使用 LLM 配置。
- *
- * @example
- * ```ts
- * const embeddingConfig = {
- *   dimensions: 1536,
- *   batchSize: 100,
- * }
- * ```
- */
-declare const EmbeddingConfigSchema: z.ZodObject<{
-    dimensions: z.ZodOptional<z.ZodNumber>;
-    batchSize: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** Embedding 配置类型 */
-type EmbeddingConfig = z.infer<typeof EmbeddingConfigSchema>;
-
-/**
- * Knowledge 配置 Schema
- *
- * 配置知识库管理参数：向量集合、分块策略、实体提取等。
- * 模型通过 LLMConfigSchema.scenarios 解析，
- * apiKey / baseUrl 统一使用 LLM 配置。
- *
- * @example
- * ```ts
- * const knowledgeConfig = {
- *   collection: 'my-knowledge',
- *   dimension: 1536,
- *   enableEntityExtraction: true
- * }
- * ```
- */
-declare const KnowledgeConfigSchema: z.ZodObject<{
-    collection: z.ZodDefault<z.ZodString>;
-    dimension: z.ZodDefault<z.ZodNumber>;
-    enableEntityExtraction: z.ZodDefault<z.ZodBoolean>;
-    cleanOptions: z.ZodDefault<z.ZodObject<{
-        removeHtml: z.ZodDefault<z.ZodBoolean>;
-        removeUrls: z.ZodDefault<z.ZodBoolean>;
-        removeEmails: z.ZodDefault<z.ZodBoolean>;
-        normalizeWhitespace: z.ZodDefault<z.ZodBoolean>;
-        trim: z.ZodDefault<z.ZodBoolean>;
-        customReplacements: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            pattern: z.ZodString;
-            replacement: z.ZodString;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
-    chunkOptions: z.ZodDefault<z.ZodObject<{
-        mode: z.ZodEnum<{
-            custom: "custom";
-            sentence: "sentence";
-            paragraph: "paragraph";
-            markdown: "markdown";
-            page: "page";
-            word: "word";
-            character: "character";
-        }>;
-        maxSize: z.ZodDefault<z.ZodNumber>;
-        overlap: z.ZodDefault<z.ZodNumber>;
-        separator: z.ZodOptional<z.ZodString>;
-        markdownMinLevel: z.ZodDefault<z.ZodNumber>;
-        markdownKeepTitle: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strip>>;
-    entityBoostWeight: z.ZodDefault<z.ZodNumber>;
-    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    systemPrompt: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** Knowledge 配置类型 */
-type KnowledgeConfig = z.infer<typeof KnowledgeConfigSchema>;
-
-/**
- * Memory 配置 Schema
- *
- * 配置对话记忆的提取、存储与检索参数。两种 provider 均为嵌入式，复用同一套
- * vecdb / reldb / LLM / Embedding；模型通过 LLMConfigSchema.scenarios.extraction
- * 解析，apiKey / baseUrl 统一使用 LLM 配置。
- *
- * @example
- * ```ts
- * const memoryConfig = {
- *   provider: 'native',
- *   maxEntriesPerObject: 1000,
- *   maxEntriesGlobal: 100000,
- *   embeddingEnabled: true,
- *   recencyDecay: 0.95,
- *   defaultTopK: 10,
- * }
- * ```
- */
-declare const MemoryConfigSchema: z.ZodObject<{
-    provider: z.ZodDefault<z.ZodEnum<{
-        native: "native";
-        mem0: "mem0";
-    }>>;
-    allowEphemeralFallback: z.ZodDefault<z.ZodBoolean>;
-    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>;
-    defaultTopK: z.ZodDefault<z.ZodNumber>;
-    candidateMultiplier: z.ZodDefault<z.ZodNumber>;
-    writebackRelatedTopK: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** Memory 配置类型 */
-type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
-
-/**
- * Token 配置 Schema
- *
- * 配置 Token 估算参数。
- *
- * @example
- * ```ts
- * const tokenConfig = { tokenRatio: 0.25 }
- * ```
- */
-declare const TokenConfigSchema: z.ZodObject<{
-    tokenRatio: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** Token 配置类型 */
-type TokenConfig = z.infer<typeof TokenConfigSchema>;
-/**
- * Summary 配置 Schema
- *
- * 配置摘要生成参数。
- * 模型通过 LLMConfigSchema.scenarios.summary 解析，
- * apiKey / baseUrl 统一使用 LLM 配置。
- *
- * @example
- * ```ts
- * const summaryConfig = { systemPrompt: 'You are a summarizer.' }
- * ```
- */
-declare const SummaryConfigSchema: z.ZodObject<{
-    systemPrompt: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** Summary 配置类型 */
-type SummaryConfig = z.infer<typeof SummaryConfigSchema>;
-/**
- * Compress 配置 Schema
- *
- * 配置上下文压缩参数：压缩策略、Token 预算、保留消息数。
- *
- * @example
- * ```ts
- * const compressConfig = {
- *   defaultStrategy: 'hybrid',
- *   defaultMaxTokens: 4000,
- *   preserveLastN: 4,
- * }
- * ```
- */
-declare const CompressConfigSchema: z.ZodObject<{
-    defaultStrategy: z.ZodDefault<z.ZodEnum<{
-        summary: "summary";
-        "sliding-window": "sliding-window";
-        hybrid: "hybrid";
-    }>>;
-    defaultMaxTokens: z.ZodDefault<z.ZodNumber>;
-    preserveLastN: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** Compress 配置类型 */
-type CompressConfig = z.infer<typeof CompressConfigSchema>;
-/**
- * File 配置 Schema
- *
- * 配置文件解析参数：OCR 提示词。
- * OCR 使用的视觉模型通过 `llm.scenarios.ocr` 指定。
- */
-declare const FileConfigSchema: z.ZodObject<{
-    systemPrompt: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** File 配置类型 */
-type FileConfig = z.infer<typeof FileConfigSchema>;
-/**
- * 检索源配置 Schema
- *
- * 与 `RetrievalSource` 接口字段对齐，支持在 `ai.init()` 中预注册检索源。
- */
-declare const RetrievalSourceSchema: z.ZodObject<{
-    id: z.ZodString;
-    collection: z.ZodString;
-    name: z.ZodOptional<z.ZodString>;
-    url: z.ZodOptional<z.ZodString>;
-    topK: z.ZodOptional<z.ZodNumber>;
-    minScore: z.ZodOptional<z.ZodNumber>;
-    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-/** 检索源配置类型 */
-type RetrievalSourceConfig = z.infer<typeof RetrievalSourceSchema>;
-/**
- * Retrieval 配置 Schema
- *
- * 在 `ai.init()` 时预注册检索源，等价于初始化后逐条调用 `ai.retrieval.addSource()`。
- *
- * @example
- * ```ts
- * ai.init({
- *   llm: { apiKey: 'sk-xxx', model: 'gpt-4o-mini' },
- *   retrieval: {
- *     sources: [
- *       { id: 'docs', collection: 'documentation', name: '产品文档', topK: 5, minScore: 0.7 },
- *       { id: 'faq',  collection: 'faq', name: '常见问题' },
- *     ],
- *   },
- * })
- * ```
- */
-declare const RetrievalConfigSchema: z.ZodObject<{
-    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        collection: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        url: z.ZodOptional<z.ZodString>;
-        topK: z.ZodOptional<z.ZodNumber>;
-        minScore: z.ZodOptional<z.ZodNumber>;
-        filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-/** Retrieval 配置类型 */
-type RetrievalConfig = z.infer<typeof RetrievalConfigSchema>;
-/** A2A Agent Skill 配置 Schema */
-declare const A2ASkillConfigSchema: z.ZodObject<{
-    id: z.ZodString;
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-/**
- * A2A 配置 Schema
- *
- * 配置 Agent-to-Agent 协议参数：Agent Card、认证等。
- *
- * @example
- * ```ts
- * ai.init({
- *   llm: { apiKey: 'sk-xxx', model: 'gpt-4o-mini' },
- *   a2a: {
- *     agentCard: {
- *       name: 'my-agent',
- *       description: 'An example agent',
- *       url: 'https://example.com',
- *       skills: [{ id: 'chat', name: 'General Chat' }],
- *     },
- *   },
- * })
- * ```
- */
-declare const A2AConfigSchema: z.ZodObject<{
-    agentCard: z.ZodObject<{
-        name: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-        url: z.ZodString;
-        version: z.ZodOptional<z.ZodString>;
-        skills: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>;
-    security: z.ZodOptional<z.ZodObject<{
-        apiKey: z.ZodOptional<z.ZodObject<{
-            in: z.ZodDefault<z.ZodEnum<{
-                header: "header";
-                query: "query";
-            }>>;
-            name: z.ZodDefault<z.ZodString>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** A2A 配置类型 */
-type A2AConfig = z.infer<typeof A2AConfigSchema>;
-/**
- * 语音平台枚举
- *
- * 决定 `ai.audio` 底层调用哪个厂商 / 协议（对使用方透明，公共请求/响应形状保持一致）：
- *
- * - `openai` — OpenAI Audio API（transcriptions / speech）
- * - `mimo` — 小米 MiMo（Chat Completions 风格 ASR / TTS）
- * - `qwen` — 阿里云百炼 Qwen Realtime（DashScope WebSocket ASR / TTS）
- * - `doubao` — 火山引擎豆包语音（二进制 WebSocket ASR / TTS）
- * - `whisper` — hai-framework Whisper Service 协议（HTTP 文件识别，可自托管）
- * - `indextts` — hai-framework IndexTTS Service 协议（HTTP 合成，可自托管）
- *
- * 平台仅表示「用哪种协议调用」，不表示服务部署在哪里；`whisper` / `indextts` 需显式配置 `baseUrl`。
- */
-declare const AudioProviderSchema: z.ZodEnum<{
-    openai: "openai";
-    mimo: "mimo";
-    qwen: "qwen";
-    doubao: "doubao";
-    whisper: "whisper";
-    indextts: "indextts";
-}>;
-/** 语音平台类型 */
-type AudioProviderName = z.infer<typeof AudioProviderSchema>;
-/** 单个语音操作类型 */
-declare const AudioOperationSchema: z.ZodEnum<{
-    transcribe: "transcribe";
-    synthesize: "synthesize";
-}>;
-/** 语音操作类型 */
-type AudioOperation = z.infer<typeof AudioOperationSchema>;
-/**
- * 语音模型允许的操作列表
- *
- * 至少一项，且不允许重复。
- */
-declare const AudioOperationsSchema: z.ZodArray<z.ZodEnum<{
-    transcribe: "transcribe";
-    synthesize: "synthesize";
-}>>;
-/**
- * 语音模型条目 Schema
- *
- * 定义单个语音模型：唯一 ID、所属平台、厂商模型名及凭据。凭据未提供时回退到对应平台的环境变量。
- *
- * @example
- * ```ts
- * const model = { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime', operations: ['transcribe'] }
- * ```
- */
-declare const AudioModelEntrySchema: z.ZodObject<{
-    id: z.ZodString;
-    provider: z.ZodEnum<{
-        openai: "openai";
-        mimo: "mimo";
-        qwen: "qwen";
-        doubao: "doubao";
-        whisper: "whisper";
-        indextts: "indextts";
-    }>;
-    model: z.ZodString;
-    operations: z.ZodArray<z.ZodEnum<{
-        transcribe: "transcribe";
-        synthesize: "synthesize";
-    }>>;
-    apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-    baseUrl: z.ZodOptional<z.ZodString>;
-    appKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-    accessKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-    resourceId: z.ZodOptional<z.ZodString>;
-    workspaceId: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-/** 语音模型条目类型 */
-type AudioModelEntry = z.infer<typeof AudioModelEntrySchema>;
-/**
- * Audio 配置 Schema
- *
- * 注册语音模型并映射默认识别 / 合成模型。调用方通常无需指定模型，仅在临时切换时通过 `request.model` 覆盖。
- *
- * @example
- * ```ts
- * ai.init({
- *   audio: {
- *     models: [
- *       { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime', operations: ['transcribe'] },
- *       { id: 'tts', provider: 'qwen', model: 'qwen3-tts-flash-realtime', operations: ['synthesize'] },
- *     ],
- *     transcribeModel: 'asr',
- *     synthesizeModel: 'tts',
- *   },
- * })
- * ```
- */
-declare const AudioConfigSchema: z.ZodObject<{
-    models: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        provider: z.ZodEnum<{
-            openai: "openai";
-            mimo: "mimo";
-            qwen: "qwen";
-            doubao: "doubao";
-            whisper: "whisper";
-            indextts: "indextts";
-        }>;
-        model: z.ZodString;
-        operations: z.ZodArray<z.ZodEnum<{
-            transcribe: "transcribe";
-            synthesize: "synthesize";
-        }>>;
-        apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-        baseUrl: z.ZodOptional<z.ZodString>;
-        appKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-        accessKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-        resourceId: z.ZodOptional<z.ZodString>;
-        workspaceId: z.ZodOptional<z.ZodString>;
-        timeout: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>>;
-    inheritLlmApiKey: z.ZodDefault<z.ZodBoolean>;
-    transcribeModel: z.ZodOptional<z.ZodString>;
-    synthesizeModel: z.ZodOptional<z.ZodString>;
-    maxAudioBytes: z.ZodDefault<z.ZodNumber>;
-    maxStreamDurationMs: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** Audio 配置类型 */
-type AudioConfig = z.infer<typeof AudioConfigSchema>;
-/**
- * 已解析的语音模型配置
- *
- * 由 `resolveAudioModel()` 返回，凭据已按模型条目、显式 LLM 继承、平台环境变量的顺序解析，
- * 端点已应用平台默认值。
- */
-interface ResolvedAudioModel {
-    /** 模型条目 ID */
-    id: string;
-    /** 所属平台 */
-    provider: AudioProviderName;
-    /** 厂商模型名 */
-    model: string;
-    /** API Key（模型条目 > 显式启用的 LLM 密钥继承 > 平台环境变量） */
-    apiKey: string | undefined;
-    /** 端点（条目 > 平台默认） */
-    baseUrl: string;
-    /** 火山引擎 App Key */
-    appKey: string | undefined;
-    /** 火山引擎 Access Key */
-    accessKey: string | undefined;
-    /** 火山引擎资源 ID（条目 > 平台默认） */
-    resourceId: string;
-    /** 阿里云百炼业务空间 ID */
-    workspaceId: string | undefined;
-    /** 请求超时（毫秒） */
-    timeout: number;
-}
-/**
- * 解析语音操作应使用的模型配置
- *
- * 解析优先级：请求显式 `model` > 场景默认（transcribe/synthesize）；凭据回退到平台环境变量。
- *
- * @param audioConfig - Audio 配置
- * @param operation - 操作类型（识别 / 合成），决定使用哪个默认模型
- * @param explicit - 请求显式指定的模型 ID（最高优先级）
- * @param llmApiKey - LLM 全局密钥，仅在 `inheritLlmApiKey` 启用时参与解析
- * @returns 成功返回已解析模型；无匹配模型返回 `AUDIO_MODEL_NOT_FOUND`；缺少凭据返回 `CONFIGURATION_ERROR`
- */
-declare function resolveAudioModel(audioConfig: AudioConfig, operation: 'transcribe' | 'synthesize', explicit?: string, llmApiKey?: string): HaiResult<ResolvedAudioModel>;
-/**
- * 校验已解析模型是否具备该平台协议所需的凭据
- *
- * 凭据是否必需由平台协议决定：自托管的 `whisper` / `indextts` 可无凭据；豆包允许 API Key
- * 或 App/Access Key 组合；其余云平台必须提供 API Key。仅在真正发起识别 / 合成前调用，
- * 能力查询（`getCapabilities`）不需要凭据。
- *
- * @param model - 已解析模型
- * @returns 缺少必需凭据时返回 `CONFIGURATION_ERROR`，否则返回 `null`
- */
-declare function ensureAudioCredential(model: ResolvedAudioModel): HaiError | null;
-/**
- * 文生图平台枚举
- *
- * - `openai` — OpenAI GPT Image（Image API）
- * - `google` — Google Gemini Image / Nano Banana（Generate Content API）
- * - `qwen` — 阿里云百炼 Qwen-Image 2.0 / 3.0
- * - `seedream` — 火山方舟 Seedream 4.x / 5.x
- * - `pollinations` — Pollinations 免费额度图片 API
- */
-declare const ImageProviderSchema: z.ZodEnum<{
-    openai: "openai";
-    qwen: "qwen";
-    google: "google";
-    seedream: "seedream";
-    pollinations: "pollinations";
-}>;
-/** 文生图平台类型 */
-type ImageProviderName = z.infer<typeof ImageProviderSchema>;
-/** 文生图模型条目 Schema */
-declare const ImageModelEntrySchema: z.ZodObject<{
-    id: z.ZodString;
-    provider: z.ZodEnum<{
-        openai: "openai";
-        qwen: "qwen";
-        google: "google";
-        seedream: "seedream";
-        pollinations: "pollinations";
-    }>;
-    model: z.ZodString;
-    apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-    baseUrl: z.ZodOptional<z.ZodURL>;
-    workspaceId: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** 文生图模型条目类型 */
-type ImageModelEntry = z.infer<typeof ImageModelEntrySchema>;
-/** 文生图配置 Schema */
-declare const ImageConfigSchema: z.ZodObject<{
-    models: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        provider: z.ZodEnum<{
-            openai: "openai";
-            qwen: "qwen";
-            google: "google";
-            seedream: "seedream";
-            pollinations: "pollinations";
-        }>;
-        model: z.ZodString;
-        apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-        baseUrl: z.ZodOptional<z.ZodURL>;
-        workspaceId: z.ZodOptional<z.ZodString>;
-        timeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>>;
-    generateModel: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** 文生图配置类型 */
-type ImageConfig = z.infer<typeof ImageConfigSchema>;
-/** 已解析的文生图模型 */
-interface ResolvedImageModel {
-    id: string;
-    provider: ImageProviderName;
-    model: string;
-    apiKey: string;
-    baseUrl: string;
-    workspaceId?: string;
-    timeout: number;
-}
-/**
- * 解析文生图模型配置
- *
- * @param imageConfig - 文生图配置
- * @param explicit - 请求显式模型 ID 或厂商模型名
- * @returns 已解析模型；模型或凭据缺失时返回 HaiResult 错误
- */
-declare function resolveImageModel(imageConfig: ImageConfig, explicit?: string): HaiResult<ResolvedImageModel>;
-/**
- * AI 配置 Schema
- *
- * 统一 AI 模块配置：LLM、MCP、Embedding、Knowledge、Retrieval、Memory、Token、Summary、Compress、File。
- * 模型通过 LLM.scenarios 映射场景，子系统不再独立配置 apiKey / baseUrl / model。
- *
- * @example
- * ```ts
- * ai.init({
- *   llm: {
- *     apiKey: 'sk-xxx',
- *     model: 'gpt-4o-mini',
- *     maxTokens: 4096,
- *     models: [
- *       { id: 'rerank', model: 'rerank-english-v3.0', baseUrl: 'https://api.cohere.com' },
- *     ],
- *     scenarios: {
- *       extraction: 'gpt-4o',
- *       summary: 'gpt-4o-mini',
- *       embedding: 'text-embedding-3-small',
- *       rerank: 'rerank',
- *       ocr: 'gpt-4o',
- *     },
- *   },
- *   embedding: { dimensions: 1536 },
- *   knowledge: {
- *     collection: 'docs',
- *     enableEntityExtraction: true,
- *     cleanOptions: { removeHtml: true },
- *     chunkOptions: { mode: 'markdown', maxSize: 1500, overlap: 200 },
- *   },
- *   retrieval: {
- *     sources: [
- *       { id: 'docs', collection: 'documentation', name: '产品文档', topK: 5, minScore: 0.7 },
- *     ],
- *   },
- *   memory: { maxEntriesPerObject: 500, embeddingEnabled: true },
- *   token: { tokenRatio: 0.25 },
- *   summary: { systemPrompt: 'You are a summarizer.' },
- *   compress: { defaultStrategy: 'hybrid', preserveLastN: 4 },
- * })
- * ```
- */
-declare const AIConfigSchema: z.ZodObject<{
-    llm: z.ZodDefault<z.ZodObject<{
-        apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-        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>>;
-        tempModelCacheTtl: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-        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.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-            baseUrl: z.ZodOptional<z.ZodURL>;
-            maxTokens: z.ZodOptional<z.ZodNumber>;
-            temperature: z.ZodOptional<z.ZodNumber>;
-            timeout: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>>;
-        scenarios: z.ZodOptional<z.ZodObject<{
-            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>;
-            extraction: z.ZodOptional<z.ZodString>;
-            summary: z.ZodOptional<z.ZodString>;
-            embedding: z.ZodOptional<z.ZodString>;
-            rerank: z.ZodOptional<z.ZodString>;
-            ocr: z.ZodOptional<z.ZodString>;
-            fast: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-    mcp: z.ZodOptional<z.ZodObject<{
-        server: z.ZodOptional<z.ZodObject<{
-            name: z.ZodString;
-            version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-            capabilities: z.ZodOptional<z.ZodObject<{
-                tools: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-                resources: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-                prompts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-    embedding: z.ZodOptional<z.ZodObject<{
-        dimensions: z.ZodOptional<z.ZodNumber>;
-        batchSize: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    knowledge: z.ZodOptional<z.ZodObject<{
-        collection: z.ZodDefault<z.ZodString>;
-        dimension: z.ZodDefault<z.ZodNumber>;
-        enableEntityExtraction: z.ZodDefault<z.ZodBoolean>;
-        cleanOptions: z.ZodDefault<z.ZodObject<{
-            removeHtml: z.ZodDefault<z.ZodBoolean>;
-            removeUrls: z.ZodDefault<z.ZodBoolean>;
-            removeEmails: z.ZodDefault<z.ZodBoolean>;
-            normalizeWhitespace: z.ZodDefault<z.ZodBoolean>;
-            trim: z.ZodDefault<z.ZodBoolean>;
-            customReplacements: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                pattern: z.ZodString;
-                replacement: z.ZodString;
-            }, z.core.$strip>>>;
-        }, z.core.$strip>>;
-        chunkOptions: z.ZodDefault<z.ZodObject<{
-            mode: z.ZodEnum<{
-                custom: "custom";
-                sentence: "sentence";
-                paragraph: "paragraph";
-                markdown: "markdown";
-                page: "page";
-                word: "word";
-                character: "character";
-            }>;
-            maxSize: z.ZodDefault<z.ZodNumber>;
-            overlap: z.ZodDefault<z.ZodNumber>;
-            separator: z.ZodOptional<z.ZodString>;
-            markdownMinLevel: z.ZodDefault<z.ZodNumber>;
-            markdownKeepTitle: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip>>;
-        entityBoostWeight: z.ZodDefault<z.ZodNumber>;
-        entityTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        systemPrompt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    memory: z.ZodOptional<z.ZodObject<{
-        provider: z.ZodDefault<z.ZodEnum<{
-            native: "native";
-            mem0: "mem0";
-        }>>;
-        allowEphemeralFallback: z.ZodDefault<z.ZodBoolean>;
-        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>;
-        defaultTopK: z.ZodDefault<z.ZodNumber>;
-        candidateMultiplier: z.ZodDefault<z.ZodNumber>;
-        writebackRelatedTopK: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    token: z.ZodOptional<z.ZodObject<{
-        tokenRatio: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    summary: z.ZodOptional<z.ZodObject<{
-        systemPrompt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    compress: z.ZodOptional<z.ZodObject<{
-        defaultStrategy: z.ZodDefault<z.ZodEnum<{
-            summary: "summary";
-            "sliding-window": "sliding-window";
-            hybrid: "hybrid";
-        }>>;
-        defaultMaxTokens: z.ZodDefault<z.ZodNumber>;
-        preserveLastN: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    retrieval: z.ZodOptional<z.ZodObject<{
-        sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            collection: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-            url: z.ZodOptional<z.ZodString>;
-            topK: z.ZodOptional<z.ZodNumber>;
-            minScore: z.ZodOptional<z.ZodNumber>;
-            filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
-    file: z.ZodOptional<z.ZodObject<{
-        systemPrompt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    a2a: z.ZodOptional<z.ZodObject<{
-        agentCard: z.ZodObject<{
-            name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            url: z.ZodString;
-            version: z.ZodOptional<z.ZodString>;
-            skills: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                id: z.ZodString;
-                name: z.ZodString;
-                description: z.ZodOptional<z.ZodString>;
-                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strip>>>;
-        }, z.core.$strip>;
-        security: z.ZodOptional<z.ZodObject<{
-            apiKey: z.ZodOptional<z.ZodObject<{
-                in: z.ZodDefault<z.ZodEnum<{
-                    header: "header";
-                    query: "query";
-                }>>;
-                name: z.ZodDefault<z.ZodString>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-    audio: z.ZodOptional<z.ZodObject<{
-        models: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodEnum<{
-                openai: "openai";
-                mimo: "mimo";
-                qwen: "qwen";
-                doubao: "doubao";
-                whisper: "whisper";
-                indextts: "indextts";
-            }>;
-            model: z.ZodString;
-            operations: z.ZodArray<z.ZodEnum<{
-                transcribe: "transcribe";
-                synthesize: "synthesize";
-            }>>;
-            apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-            baseUrl: z.ZodOptional<z.ZodString>;
-            appKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-            accessKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-            resourceId: z.ZodOptional<z.ZodString>;
-            workspaceId: z.ZodOptional<z.ZodString>;
-            timeout: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>>;
-        inheritLlmApiKey: z.ZodDefault<z.ZodBoolean>;
-        transcribeModel: z.ZodOptional<z.ZodString>;
-        synthesizeModel: z.ZodOptional<z.ZodString>;
-        maxAudioBytes: z.ZodDefault<z.ZodNumber>;
-        maxStreamDurationMs: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    image: z.ZodOptional<z.ZodObject<{
-        models: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodEnum<{
-                openai: "openai";
-                qwen: "qwen";
-                google: "google";
-                seedream: "seedream";
-                pollinations: "pollinations";
-            }>;
-            model: z.ZodString;
-            apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
-            baseUrl: z.ZodOptional<z.ZodURL>;
-            workspaceId: z.ZodOptional<z.ZodString>;
-            timeout: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip>>>;
-        generateModel: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** AI 配置类型（校验后的完整类型） */
-type AIConfig = z.infer<typeof AIConfigSchema>;
-/** AI 配置输入类型（允许部分字段） */
-type AIConfigInput = z.input<typeof AIConfigSchema>;
-
-/**
- * @h-ai/ai — A2A（Agent-to-Agent）子功能类型
- *
- * 定义 A2A 协议集成所需的类型、SDK 类型再导出、操作接口。
- * @module ai-a2a-types
- */
-
-/** A2A 调用方身份信息 */
-interface A2ACallerIdentity {
-    /** 调用方 Agent ID（如 AgentCard.name 或自定义标识） */
-    agentId: string;
-    /** 调用方显示名 */
-    name?: string;
-    /** 调用方 URL（AgentCard 地址） */
-    url?: string;
-}
-/** A2A 消息记录（存储每条 A2A 交互） */
-interface A2AMessageRecord {
-    /** 记录 ID（自动生成） */
-    id: string;
-    /** 关联的 A2A Task ID */
-    taskId: string;
-    /** 所属会话上下文 ID（历史记录可能缺失） */
-    contextId?: string;
-    /** 消息角色：user（入站请求）/ agent（出站响应） */
-    role: 'user' | 'agent';
-    /** 消息内容（JSON 序列化的 Part[] 数组） */
-    parts: unknown[];
-    /** 调用方身份信息（仅 role=user 时） */
-    caller?: A2ACallerIdentity;
-    /** 创建时间戳（毫秒） */
-    createdAt: number;
-}
-/** A2A 上下文信息（对话/会话级别） */
-interface A2AContextInfo {
-    /** 上下文 ID（对应 SDK 的 contextId） */
-    id: string;
-    /** 关联的 Agent 标识 */
-    agentId?: string;
-    /** 上下文标题（可选） */
-    title?: string;
-    /** 创建时间戳 */
-    createdAt: number;
-    /** 最后更新时间戳 */
-    updatedAt: number;
-}
-/**
- * A2A 认证器接口
- *
- * 纯接口设计，由应用层实现，Kit 模块做胶水集成。
- * 用于验证入站 A2A 请求的身份。
- */
-interface A2AAuthenticator {
-    /**
-     * 验证入站请求
-     *
-     * @param headers - HTTP 请求头
-     * @returns 成功返回调用方身份信息，失败返回错误
-     */
-    authenticate: (headers: Record<string, string | undefined>) => Promise<HaiResult<A2ACallerIdentity>>;
-}
-/** A2A 任务查询过滤器 */
-interface A2ATaskFilter {
-    /** 按消息角色过滤（user / agent），不是任务生命周期状态 */
-    status?: string | string[];
-    /** 按上下文 ID 过滤 */
-    contextId?: string;
-    /** 按调用方 Agent ID 过滤 */
-    callerId?: string;
-    /** 时间范围起始（毫秒） */
-    since?: number;
-    /** 最大返回数 */
-    limit?: number;
-    /** 偏移量 */
-    offset?: number;
-}
-/**
- * A2A 操作接口
- *
- * 提供 Agent-to-Agent 协议能力：Agent Card 管理、请求处理、客户端调用。
- */
-interface A2AOperations {
-    /**
-     * 注册 Agent 执行器
-     *
-     * 需要先调用 `ai.init()` 并配置 `a2a` 后才能注册。
-     * 注册后 `handleRequest()`、`listMessages()` 等方法即可使用。
-     *
-     * @param executor - Agent 执行器（由应用层实现）
-     * @returns 注册成功返回 `ok(undefined)`；未配置/未初始化返回 `err(HaiAIError.*)`
-     */
-    registerExecutor: (executor: AgentExecutor) => HaiResult<void>;
-    /**
-     * 获取当前 Agent Card
-     *
-     * 配置了 a2a 后即可使用，无需注册 executor。
-     *
-     * @returns 符合 A2A 0.3 的完整 Agent Card（含能力与安全方案）
-     */
-    getAgentCard: () => HaiResult<AgentCard>;
-    /**
-     * 处理入站 JSON-RPC 请求
-     *
-     * 将 HTTP 请求体路由到 SDK 的 JsonRpcTransportHandler。
-     *
-     * @param requestBody - JSON-RPC 请求体
-     * @param context - 可信 HTTP 层认证上下文；agentId 映射为 SDK user.userName
-     * @returns JSON-RPC 响应（单条或流式）；未初始化也返回 JSON-RPC 错误，不混入 HaiResult
-     */
-    handleRequest: (requestBody: unknown, context?: Record<string, unknown>) => Promise<A2AHandleResult>;
-    /**
-     * 查询 A2A 消息列表（服务端管理接口，不自动推断调用方权限）
-     *
-     * @param filter - 查询过滤器
-     * @returns 分页的消息记录列表
-     */
-    listMessages: (filter: A2ATaskFilter) => Promise<HaiResult<StorePage<A2AMessageRecord>>>;
-    /**
-     * 作为客户端调用远端 Agent
-     *
-     * remoteUrl 只应来自受信配置。框架校验协议和内嵌凭据，应用仍须按部署环境实施来源白名单与出口策略。
-     *
-     * @param remoteUrl - 远端 Agent 的 A2A 端点 URL
-     * @param message - 发送的消息文本
-     * @param options - 调用选项
-     * @returns 远端响应
-     */
-    callRemoteAgent: (remoteUrl: string, message: string, options?: A2ACallOptions) => Promise<HaiResult<A2ACallResult>>;
-}
-/** A2A API Key 安全配置 */
-interface A2AApiKeySecurity {
-    /** API Key 的传递位置 */
-    in: 'header' | 'query';
-    /** 参数名 */
-    name: string;
-}
-/** A2A 安全认证配置 */
-interface A2ASecurityConfig {
-    /** API Key 认证配置 */
-    apiKey?: A2AApiKeySecurity;
-}
-/** Agent Card 配置（应用层提供） */
-interface A2AAgentCardConfig {
-    /** Agent 名称 */
-    name: string;
-    /** Agent 描述 */
-    description?: string;
-    /** Agent URL（对外可访问的 base URL） */
-    url: string;
-    /** Agent 版本 */
-    version?: string;
-    /** Agent 能力声明 */
-    skills?: Array<{
-        id: string;
-        name: string;
-        description?: string;
-        tags?: string[];
-    }>;
-    /** 安全认证配置（体现在 Agent Card 的 securitySchemes / security 字段） */
-    security?: A2ASecurityConfig;
-}
-/** 处理结果（单条或流式） */
-interface A2AHandleResult {
-    /** 是否为流式响应 */
-    streaming: boolean;
-    /** 单条 JSON-RPC 响应体（非流式时） */
-    body?: unknown;
-    /** 流式 JSON-RPC 响应迭代器（流式时） */
-    stream?: AsyncGenerator<unknown, void, undefined>;
-}
-/** 远端调用选项 */
-interface A2ACallOptions {
-    /** 超时时间（毫秒），默认 60 秒。 */
-    timeout?: number;
-    /** 额外请求头 */
-    headers?: Record<string, string>;
-}
-/** 远端调用结果 */
-interface A2ACallResult {
-    /** 远端任务 ID */
-    taskId?: string;
-    /** 任务最终状态 */
-    taskState?: string;
-    /** 响应消息文本 */
-    responseText?: string;
-    /** 响应消息 Part 数组 */
-    responseParts?: unknown[];
-}
-
-/**
- * @h-ai/ai — Audio 子功能公共类型
- *
- * 仅定义语音识别（ASR）与语音合成（TTS）的对外业务类型。
- * 不暴露 WebSocket、SSE、厂商事件、Session/Commit、二进制帧等传输细节，
- * 也不暴露内部 Provider 接口与厂商报文结构。
- * @module audio/ai-audio-types
- */
-
-/**
- * 音频编码格式
- *
- * - `pcm16` — 16bit 小端裸 PCM（必须提供 `sampleRate`）
- * - `wav` — WAV 容器（自描述采样率，可不传 `sampleRate`）
- * - `mp3` — MP3 容器
- * - `opus` — Opus 编码
- */
-type AudioFormat = 'pcm16' | 'wav' | 'mp3' | 'opus';
-/**
- * 完整音频内容（一次性输入/输出）
- *
- * `data` 统一使用二进制字节；Node.js 中的 `Buffer` 可直接作为 `Uint8Array` 传入。
- * Provider 内部会按厂商要求转换为 Base64 / Multipart / 二进制帧，调用方无需感知。
- */
-interface AudioContent {
-    /** 音频二进制数据 */
-    data: Uint8Array;
-    /** 音频编码格式 */
-    format: AudioFormat;
-    /** 采样率（Hz）；`pcm16` 等裸音频必填，`wav` / `mp3` 等自描述格式可省略 */
-    sampleRate?: number;
-    /** 声道数（默认单声道） */
-    channels?: 1 | 2;
-}
-/** 可直接作为浏览器音频响应传输的负载 */
-interface PlayableAudio {
-    /** Base64 编码的音频字节 */
-    audioBase64: string;
-    /** 浏览器可播放的容器格式 */
-    format: 'wav' | 'mp3';
-    /** 浏览器播放所需的 MIME 类型 */
-    mimeType: 'audio/wav' | 'audio/mpeg';
-}
-/**
- * 实时音频输入流（持续到达的音频分片）
- *
- * 仅表达「音频分片持续到达」这一业务语义，不包含 WebSocket、Session、Commit 等传输概念。
- */
-interface AudioInputStream {
-    /** 持续到达的音频分片 */
-    chunks: AsyncIterable<Uint8Array>;
-    /** 音频编码格式 */
-    format: AudioFormat;
-    /** 采样率（Hz） */
-    sampleRate: number;
-    /** 声道数（默认单声道） */
-    channels?: 1 | 2;
-}
-/**
- * ASR 时间戳粒度
- *
- * - `segment` — 语义段 / 句级时间轴
- * - `word` — 词级时间轴
- */
-type TranscriptionTimestampGranularity = 'segment' | 'word';
-/** 单个 ASR 词级识别结果 */
-interface TranscriptionWord {
-    /** 识别出的文字、单词或 Token */
-    text: string;
-    /** 起始时间（毫秒） */
-    startMs: number;
-    /** 结束时间（毫秒） */
-    endMs: number;
-    /** 置信度（仅 Provider 能提供明确概率语义时返回） */
-    confidence?: number;
-}
-/** ASR 分段结果 */
-interface TranscriptionSegment {
-    /** Provider 返回或 Framework 生成的 Segment ID */
-    id?: string;
-    /** 当前 Segment 完整文本 */
-    text: string;
-    /** Segment 起始位置（毫秒） */
-    startMs: number;
-    /** Segment 结束位置（毫秒） */
-    endMs: number;
-    /** 当前 Segment 下的词级时间轴 */
-    words?: TranscriptionWord[];
-    /** 为后续 Speaker Diarization 预留的说话人 ID */
-    speakerId?: string;
-}
-/**
- * ASR 公共请求选项
- *
- * 完整识别与流式识别共用；所有高级能力字段均为可选，不支持的平台会忽略或（在
- * `strictCapabilities` 为真时）提前失败。
- */
-interface TranscriptionOptions {
-    /** 语言提示（如 `zh` / `en`；不传时由模型自动检测） */
-    language?: string;
-    /**
-     * 领域提示词 / 热词（如角色名、专有名词、当前主题关键词）
-     *
-     * Provider 按能力映射为热词表 / phrase list / vocabulary / 提示词；不支持的平台会忽略。
-     */
-    contextHints?: string[];
-    /** 请求返回的时间戳粒度（`segment` / `word`） */
-    timestampGranularities?: TranscriptionTimestampGranularity[];
-    /** 是否启用模型 / 服务端 VAD */
-    vad?: boolean;
-    /** 是否严格要求高级能力全部被支持（true 时不支持则提前失败，false 为 best effort） */
-    strictCapabilities?: boolean;
-    /** 模型 ID（不传时使用配置中的默认识别模型） */
-    model?: string;
-    /** 取消信号 */
-    signal?: AbortSignal;
-}
-/** 完整语音识别请求 */
-interface TranscriptionRequest extends TranscriptionOptions {
-    /** 待识别的完整音频 */
-    audio: AudioContent;
-}
-/** 流式语音识别请求（支持完整音频或持续音频输入） */
-interface TranscriptionStreamRequest extends TranscriptionOptions {
-    /** 完整音频，或持续到达的音频输入流 */
-    audio: AudioContent | AudioInputStream;
-}
-/** 完整语音识别结果 */
-interface TranscriptionResult {
-    /** 识别文本 */
-    text: string;
-    /** 实际检测或使用的语言 */
-    language?: string;
-    /** 输入音频总时长（毫秒） */
-    durationMs?: number;
-    /**
-     * 结构化识别时间轴
-     *
-     * Word Timestamp 统一存储在 `segments[].words`，不在顶层重复。
-     */
-    segments?: TranscriptionSegment[];
-}
-/**
- * 流式语音识别领域事件
- *
- * 统一的语音领域事件（非厂商协议）。支持服务端 VAD 的平台（如 Qwen 实时识别）会在检测到
- * 语音起止时额外产出 `speech_started` / `speech_stopped`，使调用方可在「开始说话」的瞬间做出
- * 反应（如取消当前上游生成），而无需自行运行 VAD；不产出 VAD 事件的平台（如豆包）仅产出
- * `transcript`，此时是否需要 VAD 由调用方自行决定。
- *
- * `transcript.text` 表示当前语句的完整识别文本（非字符增量），实时 ASR 会修订前一次临时结果，
- * 调用方可直接用 `text` 覆盖当前临时文本。
- */
-type TranscriptionEvent = {
-    type: 'speech_started';
-} | {
-    type: 'transcript';
-    text: string;
-    final: boolean;
-    startMs?: number;
-    endMs?: number;
-    words?: TranscriptionWord[];
-} | {
-    type: 'speech_stopped';
-};
-/**
- * TTS 通用参考音频
- *
- * 不绑定任何具体 TTS 模型。既可表达「谁在说话」（说话人参考），也可表达「怎么说」（风格参考），
- * 由 `SynthesisOptions.speakerReference` / `styleReference` 决定用途。
- */
-interface AudioReference {
-    /** 参考音频 */
-    audio: AudioContent;
-    /** 参考音频对应文本（仅需要参考 Transcript 的 Provider 使用） */
-    transcript?: string;
-    /** 参考音频语言 */
-    language?: string;
-}
-/**
- * TTS 公共请求选项
- *
- * 完整合成与流式合成共用；所有高级能力字段均为可选，不支持的平台会忽略或（在
- * `strictCapabilities` 为真时）提前失败。
- */
-interface SynthesisOptions {
-    /** 目标语言 */
-    language?: string;
-    /** 音色（厂商音色名，不传时使用模型默认音色） */
-    voice?: string;
-    /** 说话人 / 音色参考（表达「谁在说话」） */
-    speakerReference?: AudioReference;
-    /** 风格、情绪、韵律参考（表达「怎么说」） */
-    styleReference?: AudioReference;
-    /** 风格参考影响强度，统一为 `[0, 1]` */
-    styleStrength?: number;
-    /**
-     * 自然语言风格指令（如语速、情绪、角色语气）
-     *
-     * Provider 按能力映射（如 MiMo 放入 user 消息、Qwen instructions）；不支持的平台会忽略。
-     */
-    instruction?: string;
-    /**
-     * 语速倍数
-     *
-     * `1.0` 正常、`>1` 更快、`<1` 更慢。
-     */
-    speed?: number;
-    /** 输出音频格式（不传时使用模型默认格式） */
-    format?: AudioFormat;
-    /** 输出采样率（Hz） */
-    sampleRate?: number;
-    /** 模型 ID（不传时使用配置中的默认合成模型） */
-    model?: string;
-    /** 是否严格要求高级能力全部被支持（true 时不支持则提前失败，false 为 best effort） */
-    strictCapabilities?: boolean;
-    /** 取消信号 */
-    signal?: AbortSignal;
-}
-/** 完整语音合成请求 */
-interface SynthesisRequest extends SynthesisOptions {
-    /** 待合成文本 */
-    text: string;
-    /**
-     * 最终音频目标时长（毫秒）
-     *
-     * 表达 Framework 业务目标，不对应某个模型私有参数；由支持的 Provider / Model Service 闭环逼近。
-     */
-    targetDurationMs?: number;
-    /** 目标时长允许误差（毫秒） */
-    durationToleranceMs?: number;
-}
-/** 带稳定 ID 的合成文本段 */
-interface SynthesisTextSegment {
-    /** 调用方分配的稳定 ID，用于关联文本、音频与播放完成状态 */
-    id: string;
-    /** 本段待合成文本 */
-    text: string;
-}
-/** 流式语音合成请求（支持单段或持续文本段输入） */
-interface SynthesisStreamRequest extends SynthesisOptions {
-    /** 单个文本段，或持续到达的文本段流 */
-    text: SynthesisTextSegment | AsyncIterable<SynthesisTextSegment>;
-}
-/** 完整语音合成结果 */
-interface SynthesisResult extends AudioContent {
-    /** 实际输出音频时长（毫秒） */
-    durationMs?: number;
-    /** 通用生成元数据 */
-    metadata?: {
-        /** 是否满足调用方指定的时长容差（无法判断时保持 undefined） */
-        durationMatched?: boolean;
-        /** Provider 最终使用的 Framework speed */
-        speed?: number;
-    };
-}
-/**
- * 流式语音合成领域事件
- *
- * 每个文本段严格按 `segment_started → audio* → segment_done` 顺序产出，调用方可在
- * 对应音频真正播放完成后提交该段文本，不需要按字节数反推文本边界。
- *
- * `segment_started` 携带服务端解析 Provider 后的**真实输出音频参数**（format / sampleRate / channels），
- * 调用方据此正确解码、设置 PCM 播放参数、选择保存扩展名，而非根据请求参数猜测。
- */
-type SynthesisEvent = {
-    type: 'segment_started';
-    segmentId: string;
-    text: string;
-    format: AudioFormat;
-    sampleRate?: number;
-    channels?: 1 | 2;
-} | {
-    type: 'audio';
-    segmentId: string;
-    data: Uint8Array;
-} | {
-    type: 'segment_done';
-    segmentId: string;
-};
-/**
- * 语音模型的实时能力声明
- *
- * 由 `ai.audio.getCapabilities({ operation, model })` 返回，供实时会话在启动前校验：不同平台对「持续音频输入 /
- * 服务端 VAD / 增量文本输入 / 流式输出」的原生支持不同，同一方法签名在不同平台下的实时语义并不一致。
- * 调用方应据此选择模型或调整策略（如实时 ASR 要求 `realtimeAudioInput` 与 `speechBoundaryEvents`，
- * 实时 TTS 要求 `streamingAudioOutput`）。
- */
-interface AudioModelCapabilities {
-    /** 语音识别能力；模型未声明识别操作时不返回 */
-    transcribe?: {
-        /** 是否支持 ASR */
-        supported: boolean;
-        /** 是否原生支持持续实时音频输入 */
-        realtimeAudioInput: boolean;
-        /** 是否产生语音边界事件（speech_started / speech_stopped） */
-        speechBoundaryEvents: boolean;
-        /** 是否原生输出增量 Transcript */
-        streamingTranscriptOutput: boolean;
-        /** 是否接受 Language Hint */
-        languageHint?: boolean;
-        /** 是否支持自动语言检测 */
-        languageDetection?: boolean;
-        /** 是否支持 Segment Timestamp */
-        segmentTimestamps?: boolean;
-        /** 是否支持 Word Timestamp */
-        wordTimestamps?: boolean;
-        /** 是否支持 Context Hints */
-        contextHints?: boolean;
-        /** 是否支持 VAD */
-        vad?: boolean;
-        /** 是否支持 Speaker Diarization */
-        speakerDiarization?: boolean;
-    };
-    /** 语音合成能力；模型未声明合成操作时不返回 */
-    synthesize?: {
-        /** 是否支持 TTS */
-        supported: boolean;
-        /** 是否原生支持增量文本输入 */
-        incrementalTextInput: boolean;
-        /** 是否原生支持流式音频输出 */
-        streamingAudioOutput: boolean;
-        /** 是否支持指定目标语言 */
-        languageSelection?: boolean;
-        /** 是否支持预置 Voice */
-        presetVoice?: boolean;
-        /** 是否支持 Speaker Reference */
-        speakerReference?: boolean;
-        /** 是否必须提供 Speaker Reference */
-        speakerReferenceRequired?: boolean;
-        /** 是否支持 Style Reference */
-        styleReference?: boolean;
-        /** 是否支持通用自然语言 Instruction */
-        instruction?: boolean;
-        /** 是否支持 Framework Speed */
-        speedControl?: boolean;
-        /** 是否支持 Framework Target Duration */
-        targetDuration?: boolean;
-        /** 已知支持语言 */
-        supportedLanguages?: string[];
-    };
-}
-/** 查询语音模型能力的参数 */
-interface AudioCapabilitiesRequest {
-    /** 要查询的操作，决定默认模型和返回的能力分支 */
-    operation: 'transcribe' | 'synthesize';
-    /** 模型 ID；不传时使用该操作配置的默认模型 */
-    model?: string;
-}
-/**
- * Audio 操作接口（通过 `ai.audio` 访问）
- *
- * 提供语音识别与语音合成的完整与流式能力。普通方法返回 `HaiResult`；
- * 流式方法返回 `AsyncIterable`，迭代期间发生的连接/协议/上游错误会终止异步迭代（抛出异常）。
- */
-interface AudioOperations {
-    /** 将完整音频识别为完整文本 */
-    transcribe: (request: TranscriptionRequest) => Promise<HaiResult<TranscriptionResult>>;
-    /** 持续输入音频或增量返回识别文本（含语音起止领域事件） */
-    transcribeStream: (request: TranscriptionStreamRequest) => AsyncIterable<TranscriptionEvent>;
-    /** 将完整文本合成为完整音频 */
-    synthesize: (request: SynthesisRequest) => Promise<HaiResult<SynthesisResult>>;
-    /** 持续输入文本段并按段输出结构化音频事件 */
-    synthesizeStream: (request: SynthesisStreamRequest) => AsyncIterable<SynthesisEvent>;
-    /**
-     * 查询指定模型的实时能力声明
-     *
-     * @param request - 操作类型与可选模型 ID
-     * @returns 该模型对应操作的能力；模型不存在或操作不匹配时返回失败结果
-     */
-    getCapabilities: (request: AudioCapabilitiesRequest) => HaiResult<AudioModelCapabilities>;
-}
-
-/**
- * @h-ai/ai — RAG（Retrieval-Augmented Generation）子功能类型
- *
- * 定义 RAG 操作的类型接口：检索 + 生成。
- * @module ai-rag-types
- */
-
-/**
- * RAG 选项
- */
-interface RagOptions {
-    /** 交互主体 ID */
-    objectId?: string;
-    /** 会话 ID */
-    sessionId?: string;
-    /** 使用的检索源（不指定则使用全部已注册源） */
-    sources?: string[];
-    /** 返回的上下文条数（默认 5） */
-    topK?: number;
-    /** 最低相似度 */
-    minScore?: number;
-    /** 是否启用 Rerank 重排序 */
-    enableRerank?: boolean;
-    /** Rerank 使用的模型名称覆盖 */
-    rerankModel?: string;
-    /** LLM 模型名称覆盖 */
-    model?: string;
-    /** 系统提示词（可选，会自动注入检索上下文） */
-    systemPrompt?: string;
-    /** 温度覆盖 */
-    temperature?: number;
-    /** 自定义上下文格式化函数 */
-    formatContext?: (items: RagContextItem[]) => string;
-    /** 是否保留消息历史（用于多轮对话） */
-    messages?: ChatMessage[];
-    /** 是否启用内部 LLM 调用的持久化（默认 true；Context 层调用时传 false 避免重复记录） */
-    enablePersist?: boolean;
-    /** 请求取消信号（透传给内部 LLM 调用，支持中途取消生成） */
-    signal?: AbortSignal;
-}
-/**
- * RAG 上下文项
- */
-interface RagContextItem {
-    /** 文档内容 */
-    content: string;
-    /** 相似度分数 */
-    score: number;
-    /** 来源 */
-    sourceId: string;
-    /** 元数据 */
-    metadata?: Record<string, unknown>;
-    /** 结构化信源引用 */
-    citation?: Citation;
-}
-/**
- * RAG 结果
- */
-interface RagResult {
-    /** LLM 生成的回答 */
-    answer: string;
-    /** 使用的上下文 */
-    context: RagContextItem[];
-    /** 去重后的信源引用列表（方便 UI 展示引用栏） */
-    citations: Citation[];
-    /** 查询文本 */
-    query: string;
-    /** 使用的模型 */
-    model: string;
-    /** Token 使用统计 */
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
-/**
- * RAG 流式事件
- *
- * queryStream 产出的事件序列：
- * 1. `context` — 检索结果就绪，携带上下文列表
- * 2. `delta` — LLM 增量文本
- * 3. `done` — 生成完成，携带完整结果汇总
- */
-type RagStreamEvent = {
-    type: 'context';
-    items: RagContextItem[];
-    citations: Citation[];
-} | {
-    type: 'delta';
-    text: string;
-} | {
-    type: 'done';
-    answer: string;
-    model: string;
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-};
-/**
- * RAG 操作接口
- */
-interface RagOperations {
-    /**
-     * 执行 RAG（检索增强生成）
-     *
-     * 1. 将查询文本向量化
-     * 2. 从已注册的检索源中检索相关文档
-     * 3. 将检索上下文注入 LLM 提示词
-     * 4. 调用 LLM 生成回答
-     *
-     * @param query - 用户查询文本
-     * @param options - RAG 选项
-     * @returns RAG 结果
-     */
-    query: (query: string, options?: RagOptions) => Promise<HaiResult<RagResult>>;
-    /**
-     * 流式 RAG 查询
-     *
-     * 产出事件序列：context → delta* → done
-     *
-     * @param query - 用户查询文本
-     * @param options - RAG 选项
-     * @returns 异步可迭代的 RagStreamEvent
-     */
-    queryStream: (query: string, options?: RagOptions) => AsyncIterable<RagStreamEvent>;
-}
-
-/**
- * @h-ai/ai — Reasoning 子功能类型
- *
- * 定义推理策略和推理操作的类型接口。
- * 支持 ReAct、Chain-of-Thought（CoT）、Plan-and-Execute 三种策略。
- * @module ai-reasoning-types
- */
-
-/**
- * 推理策略类型
- *
- * - `react` — ReAct（Reasoning + Acting）：交替 思考→行动→观察 循环
- * - `cot` — Chain-of-Thought：将问题分解为思维链逐步推理
- * - `plan-execute` — Plan-and-Execute：先生成计划再逐步执行
- */
-type ReasoningStrategy = 'react' | 'cot' | 'plan-execute';
-/**
- * 推理执行选项
- */
-interface ReasoningOptions {
-    /** 交互主体 ID */
-    objectId?: string;
-    /** 会话 ID */
-    sessionId?: string;
-    /** 推理策略（默认 `'react'`） */
-    strategy?: ReasoningStrategy;
-    /** 最大推理轮次（默认 10） */
-    maxRounds?: number;
-    /** 使用的模型 ID 或名称（可选，默认使用 reasoning 场景的模型） */
-    model?: string;
-    /** Plan-Execute 规划阶段模型（可选，默认回退到 `model` → 场景 `plan` → 场景 `reasoning`） */
-    planModel?: string;
-    /** Plan-Execute 执行阶段模型（可选，默认回退到 `model` → 场景 `execute` → 场景 `reasoning`） */
-    executeModel?: string;
-    /** 系统提示词（可选，覆盖默认的策略提示词） */
-    systemPrompt?: string;
-    /** 是否启用内部 LLM 调用的持久化（默认 true；Context 层调用时传 false 避免重复记录） */
-    enablePersist?: boolean;
-    /**
-     * 前置对话上下文（可选）
-     *
-     * 插入到系统提示词之后、当前问题之前，用于注入：
-     * - 历史对话轮次（连续对话场景）
-     * - `ai.memory.injectMemories()` 处理后的记忆增强消息
-     * - RAG 检索到的内容片段（构造为 system 消息）
-     *
-     * @example
-     * ```ts
-     * // 将记忆注入推理上下文
-     * const withMemory = await ai.memory.injectMemories(
-     *   [{ role: 'user', content: query }],
-     *   { objectId: 'user-001' },
-     * )
-     * await ai.reasoning.run(query, { messages: withMemory.data })
-     * ```
-     */
-    messages?: ChatMessage[];
-    /** 可用工具注册表（可选，ReAct 和 Plan-Execute 策略可用） */
-    tools?: ToolRegistryOperations;
-    /** 温度覆盖 */
-    temperature?: number;
-    /** 请求取消信号（透传给内部 LLM 调用，支持中途取消推理） */
-    signal?: AbortSignal;
-}
-/**
- * 推理步骤类型
- */
-type ReasoningStepType = 'thought' | 'action' | 'observation' | 'plan' | 'answer';
-/**
- * 单个推理步骤
- */
-interface ReasoningStep {
-    /** 步骤类型 */
-    type: ReasoningStepType;
-    /** 步骤内容 */
-    content: string;
-    /** 工具调用信息（仅 action 类型） */
-    toolCall?: {
-        name: string;
-        arguments: Record<string, unknown>;
-        result?: string;
-    };
-    /** 步骤索引（从 0 开始） */
-    index: number;
-}
-/**
- * 推理执行结果
- */
-interface ReasoningResult {
-    /** 最终答案 */
-    answer: string;
-    /** 推理步骤列表 */
-    steps: ReasoningStep[];
-    /** 使用的策略 */
-    strategy: ReasoningStrategy;
-    /** 总推理轮次 */
-    rounds: number;
-    /** 完整的消息历史 */
-    messages: ChatMessage[];
-}
-/**
- * 推理流式事件
- *
- * runStream 产出的事件序列：
- * - `step` — 推理步骤完成（思考/行动/观察/计划）
- * - `delta` — LLM 增量文本（最终答案的流式输出）
- * - `done` — 推理完成，携带完整结果
- */
-type ReasoningStreamEvent = {
-    type: 'step';
-    step: ReasoningStep;
-} | {
-    type: 'delta';
-    text: string;
-} | {
-    type: 'done';
-    result: ReasoningResult;
-};
-/**
- * 推理操作接口（通过 `ai.reasoning` 访问）
- *
- * 需要先调用 `ai.init()` 初始化后使用。
- *
- * @example
- * ```ts
- * // ReAct 推理（带工具）
- * const result = await ai.reasoning.run(
- *   '分析这份数据...',
- *   {
- *     strategy: 'react',
- *     tools: registry,
- *     maxRounds: 5,
- *   },
- * )
- *
- * // CoT 推理
- * const result = await ai.reasoning.run(
- *   '解释量子纠缠',
- *   { strategy: 'cot' },
- * )
- * ```
- */
-interface ReasoningOperations {
-    /**
-     * 执行推理
-     *
-     * @param query - 用户问题或任务描述
-     * @param options - 推理选项
-     * @returns 推理结果
-     */
-    run: (query: string, options?: ReasoningOptions) => Promise<HaiResult<ReasoningResult>>;
-    /**
-     * 流式推理（逐步产出推理步骤 + 最终答案增量文本）
-     *
-     * 产出事件序列：step* → delta* → done
-     *
-     * @param query - 用户问题或任务描述
-     * @param options - 推理选项
-     * @returns 异步可迭代的 ReasoningStreamEvent
-     */
-    runStream: (query: string, options?: ReasoningOptions) => AsyncIterable<ReasoningStreamEvent>;
-}
-
-export { ModelEntrySchema as $, type A2AConfig as A, EntityTypeSchema as B, type CompressConfig as C, FileConfigSchema as D, type EmbeddingConfig as E, type FileConfig as F, ImageConfigSchema as G, type ImageModelEntry as H, type ImageConfig as I, ImageModelEntrySchema as J, type ImageProviderName as K, ImageProviderSchema as L, type KnowledgeConfig as M, KnowledgeConfigSchema as N, type LLMConfig as O, LLMConfigSchema as P, type MCPConfig as Q, MCPConfigSchema as R, type MCPServerCapabilities as S, MCPServerCapabilitiesSchema as T, type MCPServerConfig as U, MCPServerConfigSchema as V, type MemoryConfig as W, MemoryConfigSchema as X, type MemoryType as Y, MemoryTypeSchema as Z, type ModelEntry as _, A2AConfigSchema as a, type ChatRecord as a$, type ModelScenario as a0, ModelScenarioSchema as a1, OptionalSecretSchema as a2, type PlayableAudio as a3, type ResolveRequiredModelEntryOptions as a4, type ResolvedAudioModel as a5, type ResolvedImageModel as a6, type ResolvedModelConfig as a7, type RetrievalConfig as a8, RetrievalConfigSchema as a9, type A2AAgentCardConfig as aA, type A2AApiKeySecurity as aB, type A2AAuthenticator as aC, type A2ACallOptions as aD, type A2ACallResult as aE, type A2ACallerIdentity as aF, type A2AContextInfo as aG, type A2AHandleResult as aH, type A2AMessageRecord as aI, type A2AOperations as aJ, type A2ASecurityConfig as aK, type A2ATaskFilter as aL, type AILLMFunctionsDeps as aM, type AIRelStore as aN, type AIRelStoreOptions as aO, type AIStoreProvider as aP, type AIVectorBackend as aQ, type AIVectorStore as aR, type AskOptions as aS, type AssistantMessage as aT, type ChatCompletionChoice as aU, type ChatCompletionChunk as aV, type ChatCompletionDelta as aW, type ChatCompletionRequest as aX, type ChatCompletionResponse as aY, type ChatHistoryOptions as aZ, type ChatMessage as a_, type RetrievalSourceConfig as aa, RetrievalSourceSchema as ab, type SummaryConfig as ac, SummaryConfigSchema as ad, type SynthesisEvent as ae, type SynthesisOptions as af, type SynthesisRequest as ag, type SynthesisResult as ah, type SynthesisStreamRequest as ai, type SynthesisTextSegment as aj, type TokenConfig as ak, TokenConfigSchema as al, type TranscriptionEvent as am, type TranscriptionOptions as an, type TranscriptionRequest as ao, type TranscriptionResult as ap, type TranscriptionSegment as aq, type TranscriptionStreamRequest as ar, type TranscriptionTimestampGranularity as as, type TranscriptionWord as at, ensureAudioCredential as au, resolveAudioModel as av, resolveImageModel as aw, resolveModelApi as ax, resolveModelEntry as ay, type InteractionScope as az, A2ASkillConfigSchema as b, type SSEEvent as b$, type Citation as b0, type DefineToolOptions as b1, type DeveloperMessage as b2, type EntityDocumentRelation as b3, type EntityDocumentResult as b4, type EntityListOptions as b5, type EntityQueryOptions as b6, type GenerateObjectRequest as b7, type ImageContent as b8, type KnowledgeAskOptions as b9, type MemoryInjectionOptions as bA, type MemoryListOptions as bB, type MemoryListPageOptions as bC, type MemoryOperations as bD, type MemoryRecallOptions as bE, type MemoryUpdateInput as bF, type MessageContent as bG, type MessageRole as bH, type ObjectRef as bI, type RagContextItem as bJ, type RagOperations as bK, type RagOptions as bL, type RagResult as bM, type RagStreamEvent as bN, type ReasoningOperations as bO, type ReasoningOptions as bP, type ReasoningResult as bQ, type ReasoningStep as bR, type ReasoningStepType as bS, type ReasoningStrategy as bT, type ReasoningStreamEvent as bU, type RetrievalOperations as bV, type RetrievalRequest as bW, type RetrievalResult as bX, type RetrievalResultItem as bY, type RetrievalSource as bZ, type SSEDecoder as b_, type KnowledgeAskResult as ba, type KnowledgeDocumentInfo as bb, type KnowledgeDocumentListOptions as bc, type KnowledgeDocumentRemoveOptions as bd, type KnowledgeEntity as be, type KnowledgeIngestBatchProgress as bf, type KnowledgeIngestBatchResult as bg, type KnowledgeIngestFileInput as bh, type KnowledgeIngestInput as bi, type KnowledgeIngestResult as bj, type KnowledgeOperations as bk, type KnowledgeRetrieveItem as bl, type KnowledgeRetrieveOptions as bm, type KnowledgeRetrieveResult as bn, type KnowledgeSetupOptions as bo, type KnowledgeStore as bp, type LLMOperations as bq, type LLMProvider as br, type MemoryAccessScope as bs, type MemoryAdminOperations as bt, type MemoryClearAllOptions as bu, type MemoryClearOptions as bv, type MemoryCoreOperations as bw, type MemoryEntry as bx, type MemoryEntryInput as by, type MemoryExtractOptions as bz, type AIConfig as c, type ScopedMemoryBinding as c0, type ScopedMemoryOperations as c1, type SessionInfo as c2, type StoreFilter as c3, type StorePage as c4, type StoreScope as c5, type StreamOperations as c6, type StreamProcessor as c7, type StreamResult as c8, type SystemMessage as c9, type TempModelConfig as ca, type TextContent as cb, type TokenUsage as cc, type Tool as cd, type ToolAuthorizationRequest as ce, type ToolAuthorizer as cf, type ToolCall as cg, type ToolDefinition as ch, type ToolErrorType as ci, type ToolExecutionContext as cj, type ToolExecutionOptions as ck, type ToolMessage as cl, type ToolRegistryOperations as cm, type ToolRegistryOptions as cn, type ToolsOperations as co, type UserMessage as cp, type WhereClause as cq, type WhereOperator as cr, type WhereValue as cs, type AIConfigInput as d, AIConfigSchema as e, type ApiType as f, ApiTypeSchema as g, type AudioCapabilitiesRequest as h, type AudioConfig as i, AudioConfigSchema as j, type AudioContent as k, type AudioFormat as l, type AudioInputStream as m, type AudioModelCapabilities as n, type AudioModelEntry as o, AudioModelEntrySchema as p, type AudioOperation as q, AudioOperationSchema as r, type AudioOperations as s, AudioOperationsSchema as t, type AudioProviderName as u, AudioProviderSchema as v, type AudioReference as w, CompressConfigSchema as x, EmbeddingConfigSchema as y, type EntityType as z };