@h-ai/ai 0.1.0-alpha5

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

@@ -0,0 +1,2790 @@
+import { AgentExecutor } from '@a2a-js/sdk/server';
+import { HaiResult, HaiError } from '@h-ai/core';
+import { CleanOptionsInput, ChunkOptionsInput } from '@h-ai/datapipe';
+import { ZodType, z } from 'zod';
+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;
+    /** 排序 */
+    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;
+}
+/**
+ * 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;
+        aliases?: string[];
+        description?: string;
+    }) => Promise<void>;
+    /** 按名称模糊搜索实体（匹配 name 和 aliases） */
+    findEntitiesByName: (keyword: string) => Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        aliases: string[];
+    }>>;
+    /** 列出实体（支持类型过滤和关键词搜索） */
+    listEntities: (options?: {
+        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;
+    }>>;
+    /** 插入文档-实体关联 */
+    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;
+        }>;
+    }>>;
+    /** 删除文档相关的实体关联 */
+    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>;
+}
+/**
+ * AI 存储 Provider 接口
+ *
+ * 负责创建 AIRelStore / AIVectorStore 实例，并管理存储层生命周期。
+ * 默认实现基于 reldb + vecdb；也可对接 SaaS API 或其他后端。
+ *
+ * @example
+ * ```ts
+ * // 使用默认 reldb+vecdb provider
+ * ai.init({ store: { type: 'db' } })
+ *
+ * // 使用自定义 provider
+ * ai.init({ store: { type: 'custom', provider: myProvider } })
+ * ```
+ */
+interface AIStoreProvider {
+    /** Provider 名称（如 'db'、'api'） */
+    readonly name: string;
+    /** 创建关系数据存储实例 */
+    createRelStore: <T>(name: string, options?: AIRelStoreOptions) => AIRelStore<T>;
+    /** 创建向量数据存储实例 */
+    createVectorStore: (name: string) => AIVectorStore;
+    /**
+     * 创建 knowledge 专用存储（可选）
+     *
+     * 如果 Provider 不提供此方法，knowledge 子系统将不可用。
+     * 默认 db Provider 提供基于 reldb 归一化表 + vecdb 的高效实现。
+     */
+    createKnowledgeStore?: () => KnowledgeStore;
+    /**
+     * 初始化所有已创建的存储（建表、建连接等）
+     *
+     * 由 ai.init() 在创建完所有 store 实例后统一调用。
+     */
+    initialize: () => Promise<void>;
+    /** 关闭所有存储（释放连接等），由 ai.close() 调用 */
+    close?: () => Promise<void>;
+}
+
+/**
+ * @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;
+    /** 消息角色：user（入站请求）/ agent（出站响应） */
+    role: 'user' | 'agent';
+    /** 消息内容（JSON 序列化的 Part[] 数组） */
+    parts: unknown[];
+    /** 调用方身份信息（仅 role=user 时） */
+    caller?: A2ACallerIdentity;
+    /** 创建时间戳（毫秒） */
+    createdAt: number;
+}
+/** A2A 客户端调用记录（作为客户端调用远端 Agent 时的日志） */
+interface A2AClientCallRecord {
+    /** 记录 ID */
+    id: string;
+    /** 远端 Agent URL */
+    remoteUrl: string;
+    /** 远端 Agent 名称 */
+    remoteName?: string;
+    /** 请求消息 Part[] */
+    requestParts: unknown[];
+    /** 响应消息 Part[]（可选，流式时可能为空） */
+    responseParts?: unknown[];
+    /** A2A Task ID（远端返回的） */
+    taskId?: string;
+    /** 任务最终状态 */
+    taskState?: string;
+    /** 调用耗时（毫秒） */
+    duration?: number;
+    /** 创建时间戳 */
+    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 {
+    /** 按任务状态过滤 */
+    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 Agent Card 配置
+     */
+    getAgentCard: () => HaiResult<A2AAgentCardConfig>;
+    /**
+     * 处理入站 JSON-RPC 请求
+     *
+     * 将 HTTP 请求体路由到 SDK 的 JsonRpcTransportHandler。
+     *
+     * @param requestBody - JSON-RPC 请求体
+     * @param context - 可选的调用上下文（含认证信息）
+     * @returns JSON-RPC 响应（单条或流式）
+     */
+    handleRequest: (requestBody: unknown, context?: Record<string, unknown>) => Promise<A2AHandleResult>;
+    /**
+     * 查询 A2A 任务列表
+     *
+     * @param filter - 查询过滤器
+     * @returns 分页的消息记录列表
+     */
+    listMessages: (filter: A2ATaskFilter) => Promise<HaiResult<StorePage<A2AMessageRecord>>>;
+    /**
+     * 作为客户端调用远端 Agent
+     *
+     * @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 {
+    /** 请求超时（毫秒） */
+    timeout?: number;
+    /** 额外请求头 */
+    headers?: Record<string, string>;
+}
+/** 远端调用结果 */
+interface A2ACallResult {
+    /** 远端任务 ID */
+    taskId?: string;
+    /** 任务最终状态 */
+    taskState?: string;
+    /** 响应消息文本 */
+    responseText?: string;
+    /** 响应消息 Part 数组 */
+    responseParts?: unknown[];
+}
+
+/**
+ * @h-ai/ai — LLM 子功能类型
+ *
+ * 定义 LLM 消息、请求、响应、流、工具等公共类型。
+ * @module ai-llm-types
+ */
+
+/** 消息角色枚举：`'system'` | `'user'` | `'assistant'` | `'tool'` */
+type MessageRole = 'system' | '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;
+/** 用户消息 */
+type UserMessage = OpenAI.Chat.Completions.ChatCompletionUserMessageParam;
+/** 工具调用描述，由助手消息中的 `tool_calls` 字段携带 */
+type ToolCall = OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+/** 助手消息（模型生成的回复，或传入对话上下文的助手轮次） */
+type AssistantMessage = OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam;
+/** 工具消息（工具执行结果，用于回传给模型） */
+type ToolMessage = OpenAI.Chat.Completions.ChatCompletionToolMessageParam;
+/** 聊天消息联合类型，涵盖对话中所有角色的消息 */
+type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
+/** OpenAI function calling 工具定义格式 */
+type ToolDefinition = OpenAI.Chat.Completions.ChatCompletionTool;
+/**
+ * 聊天完成请求参数
+ *
+ * 继承 OpenAI SDK 全部标准请求字段，并扩展框架专属字段（`objectId`、`sessionId`）。
+ * `model` 改为可选（未指定时使用配置中的默认模型）。
+ * `stream` 字段由框架内部控制，不对外暴露。
+ */
+type ChatCompletionRequest = Omit<OpenAI.Chat.ChatCompletionCreateParamsNonStreaming, 'model' | 'stream'> & {
+    /** 模型名称（可选，未指定时使用配置中的默认模型） */
+    model?: string;
+    /** 交互主体 ID（传入后 LLM 会自动关联到该主体） */
+    objectId?: string;
+    /** 会话 ID（传入后 LLM 会自动关联到该会话） */
+    sessionId?: string;
+    /** 是否持久化对话记录（默认 true；传入 false 时跳过记录，适用于内部调用如实体提取） */
+    enablePersist?: boolean;
+};
+/** 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;
+    /** 累积的完整工具调用列表 */
+    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' | 'VALIDATION_FAILED' | 'EXECUTION_FAILED' | 'TIMEOUT';
+/**
+ * 工具定义选项（传给 `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>;
+    /** 执行函数，接收校验后的参数，支持同步/异步 */
+    handler: (input: TInput) => Promise<TOutput> | TOutput;
+}
+/**
+ * 工具实例（由 `ai.tools.define()` 创建）
+ *
+ * @typeParam TInput - 参数类型
+ * @typeParam TOutput - 返回值类型
+ */
+interface Tool<TInput = unknown, TOutput = unknown> {
+    /** 工具名称 */
+    name: string;
+    /** 工具功能描述 */
+    description: string;
+    /** Zod 参数 schema */
+    parameters: ZodType<TInput>;
+    /** 执行工具（自动校验参数），失败返回 ToolError */
+    execute: (input: TInput) => Promise<HaiResult<TOutput>>;
+    /** 转换为 OpenAI function calling 定义格式（$schema 字段已移除） */
+    toDefinition: () => ToolDefinition;
+}
+/**
+ * 工具注册表接口（由 `ai.tools.createRegistry()` 创建）
+ *
+ * 管理一组工具的注册、查询与批量执行，支持链式调用。
+ */
+interface ToolRegistryOperations {
+    /** 注册工具（同名覆盖），返回 registry 自身以支持链式调用 */
+    register: <TInput, TOutput>(tool: Tool<TInput, TOutput>) => ToolRegistryOperations;
+    /** 批量注册工具，返回 registry 自身 */
+    registerMany: (tools: Tool<unknown, unknown>[]) => ToolRegistryOperations;
+    /** 注销指定名称的工具，成功返回 `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 */
+    execute: (toolCall: ToolCall) => Promise<HaiResult<ToolMessage>>;
+    /** 批量执行工具调用（默认并行），任一失败立即返回错误 */
+    executeAll: (toolCalls: ToolCall[], options?: {
+        parallel?: boolean;
+    }) => Promise<HaiResult<ToolMessage[]>>;
+    /** 清空所有已注册的工具 */
+    clear: () => void;
+    /** 当前已注册的工具数量 */
+    readonly size: number;
+}
+/** 工具操作接口（通过 `ai.tools` 访问，纯函数，无需初始化） */
+interface ToolsOperations {
+    /** 定义工具（Zod schema 类型推断 + 自动参数校验） */
+    define: <TInput, TOutput>(options: DefineToolOptions<TInput, TOutput>) => Tool<TInput, TOutput>;
+    /** 创建新的工具注册表实例 */
+    createRegistry: () => 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;
+}
+/**
+ * 对话记录
+ *
+ * 每次 `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[]>>;
+}
+/**
+ * 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>;
+}
+/** 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 {
+    /** 实体类型过滤 */
+    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>>;
+}
+
+/**
+ * @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;
+    /** 附加元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 完整的记忆条目
+ */
+interface MemoryEntry {
+    /** 记忆唯一标识 */
+    id: string;
+    /** 记忆内容 */
+    content: string;
+    /** 记忆类型 */
+    type: MemoryType;
+    /** 重要性评分 [0, 1] */
+    importance: number;
+    /** 所属主体 ID */
+    objectId?: string;
+    /** 附加元数据 */
+    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;
+}
+/**
+ * 记忆检索选项
+ */
+interface MemoryRecallOptions {
+    /** 返回数量（默认使用配置的 defaultTopK） */
+    topK?: number;
+    /** 过滤类型 */
+    types?: MemoryType[];
+    /** 最低重要性 */
+    minImportance?: number;
+    /** 时间衰减权重 [0, 1]（0 = 不考虑时间，1 = 仅按时间排序） */
+    recencyWeight?: number;
+    /** 限定主体 ID */
+    objectId?: string;
+}
+/**
+ * 记忆注入选项（`injectMemories` 使用）
+ *
+ * 控制记忆注入行为：检索数量、Token 预算、注入位置等。
+ */
+interface MemoryInjectionOptions {
+    /** 注入的记忆数量（默认 5） */
+    topK?: number;
+    /** 记忆占用的最大 token 预算（默认不限） */
+    maxTokens?: number;
+    /** 注入位置：system = 追加到 system 消息末尾，before-last = 插入在最后一条用户消息之前 */
+    position?: 'system' | 'before-last';
+    /** 限定主体 ID */
+    objectId?: string;
+}
+/**
+ * 记忆列表选项
+ */
+interface MemoryListOptions {
+    /** 过滤类型 */
+    types?: MemoryType[];
+    /** 限定主体 ID */
+    objectId?: string;
+    /** 最大返回数 */
+    limit?: number;
+}
+/**
+ * 记忆分页选项
+ */
+interface MemoryListPageOptions {
+    /** 过滤类型 */
+    types?: MemoryType[];
+    /** 限定主体 ID */
+    objectId?: string;
+    /** 偏移量 */
+    offset?: number;
+    /** 每页数量（默认 20） */
+    limit?: number;
+}
+/**
+ * 记忆清空选项
+ */
+interface MemoryClearOptions {
+    /** 仅清空指定类型 */
+    types?: MemoryType[];
+    /** 仅清空指定主体 */
+    objectId?: string;
+}
+/**
+ * 记忆条目更新输入
+ *
+ * 所有字段均为可选，仅传入需要更新的字段。
+ */
+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 })
+ * ```
+ */
+interface MemoryOperations {
+    /**
+     * 从对话消息中自动提取记忆条目
+     *
+     * 使用 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 - 需要更新的字段
+     * @returns 更新后的完整记忆条目
+     */
+    update: (memoryId: string, updates: MemoryUpdateInput) => Promise<HaiResult<MemoryEntry>>;
+    /**
+     * 按 ID 获取单条记忆
+     *
+     * @param memoryId - 记忆 ID
+     * @returns 记忆条目，不存在时返回 MEMORY_NOT_FOUND
+     */
+    get: (memoryId: string) => Promise<HaiResult<MemoryEntry>>;
+    /**
+     * 删除单条记忆
+     *
+     * 同时从 Store 中移除持久化数据。
+     *
+     * @param memoryId - 记忆 ID
+     * @returns 成功返回 ok(undefined)
+     */
+    remove: (memoryId: string) => 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>>;
+}
+
+/**
+ * @h-ai/ai — 错误码 + 配置 Schema
+ *
+ * 定义 AI 模块的错误码常量、Zod Schema 和配置类型。
+ * @module ai-config
+ */
+
+/**
+ * 模型场景枚举
+ *
+ * 预定义的模型使用场景，用于自动选择合适的模型。
+ *
+ * - `default` — 默认场景（兜底）
+ * - `chat` — 对话场景
+ * - `reasoning` — 推理场景（ReAct、CoT，需要强逻辑能力）
+ * - `plan` — Plan-Execute 规划阶段（需要强推理）
+ * - `execute` — Plan-Execute 执行阶段（需要工具调用能力）
+ * - `extraction` — 信息提取场景（记忆提取、实体抽取）
+ * - `summary` — 摘要/压缩场景（上下文摘要）
+ * - `embedding` — 向量嵌入场景
+ * - `rerank` — 文档重排序场景
+ * - `ocr` — 图片 OCR 识别场景（视觉模型）
+ * - `fast` — 快速响应场景（低延迟优先）
+ */
+declare const ModelScenarioSchema: z.ZodEnum<{
+    default: "default";
+    chat: "chat";
+    reasoning: "reasoning";
+    plan: "plan";
+    execute: "execute";
+    extraction: "extraction";
+    summary: "summary";
+    embedding: "embedding";
+    rerank: "rerank";
+    ocr: "ocr";
+    fast: "fast";
+}>;
+/** 模型场景类型 */
+type ModelScenario = z.infer<typeof ModelScenarioSchema>;
+/**
+ * 模型条目 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;
+    apiKey: z.ZodOptional<z.ZodString>;
+    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.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodURL>;
+    model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    maxTokens: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    temperature: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    models: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        model: z.ZodString;
+        apiKey: z.ZodOptional<z.ZodString>;
+        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<{
+        default: z.ZodOptional<z.ZodString>;
+        chat: 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 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>;
+/** 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
+ *
+ * 配置对话记忆的提取、存储与检索参数。
+ * 模型通过 LLMConfigSchema.scenarios.extraction 解析，
+ * apiKey / baseUrl 统一使用 LLM 配置。
+ *
+ * @example
+ * ```ts
+ * const memoryConfig = {
+ *   maxEntries: 1000,
+ *   embeddingEnabled: true,
+ *   recencyDecay: 0.95,
+ *   defaultTopK: 10,
+ * }
+ * ```
+ */
+declare const MemoryConfigSchema: z.ZodObject<{
+    maxEntries: z.ZodDefault<z.ZodNumber>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    recencyDecay: z.ZodDefault<z.ZodNumber>;
+    embeddingEnabled: z.ZodDefault<z.ZodBoolean>;
+    defaultTopK: 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 配置 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: { maxEntries: 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.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodURL>;
+        model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        maxTokens: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        temperature: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        models: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            model: z.ZodString;
+            apiKey: z.ZodOptional<z.ZodString>;
+            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<{
+            default: z.ZodOptional<z.ZodString>;
+            chat: 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<{
+        maxEntries: z.ZodDefault<z.ZodNumber>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        recencyDecay: z.ZodDefault<z.ZodNumber>;
+        embeddingEnabled: z.ZodDefault<z.ZodBoolean>;
+        defaultTopK: 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>>;
+}, z.core.$strip>;
+/** AI 配置类型（校验后的完整类型） */
+type AIConfig = z.infer<typeof AIConfigSchema>;
+/** AI 配置输入类型（允许部分字段） */
+type AIConfigInput = z.input<typeof AIConfigSchema>;
+
+/**
+ * @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;
+}
+/**
+ * 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;
+}
+/**
+ * 推理步骤类型
+ */
+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 { type A2AOperations as $, type A2AConfig as A, type RetrievalConfig as B, type CompressConfig as C, RetrievalConfigSchema as D, type EmbeddingConfig as E, type FileConfig as F, type RetrievalSourceConfig as G, RetrievalSourceSchema as H, SummaryConfigSchema as I, TokenConfigSchema as J, type KnowledgeConfig as K, type LLMConfig as L, type MCPConfig as M, resolveModelEntry as N, type A2AAgentCardConfig as O, type A2AApiKeySecurity as P, type A2AAuthenticator as Q, type ResolveRequiredModelEntryOptions as R, type SummaryConfig as S, type TokenConfig as T, type A2ACallOptions as U, type A2ACallResult as V, type A2ACallerIdentity as W, type A2AClientCallRecord as X, type A2AContextInfo as Y, type A2AHandleResult as Z, type A2AMessageRecord as _, A2AConfigSchema as a, type ReasoningOptions as a$, type A2ASecurityConfig as a0, type A2ATaskFilter as a1, type AILLMFunctionsDeps as a2, type AIRelStore as a3, type AIRelStoreOptions as a4, type AIStoreProvider as a5, type AIVectorStore as a6, type AskOptions as a7, type AssistantMessage as a8, type ChatCompletionChoice as a9, type KnowledgeOperations as aA, type KnowledgeRetrieveItem as aB, type KnowledgeRetrieveOptions as aC, type KnowledgeRetrieveResult as aD, type KnowledgeSetupOptions as aE, type KnowledgeStore as aF, type LLMOperations as aG, type LLMProvider as aH, type MemoryClearOptions as aI, type MemoryEntry as aJ, type MemoryEntryInput as aK, type MemoryExtractOptions as aL, type MemoryInjectionOptions as aM, type MemoryListOptions as aN, type MemoryListPageOptions as aO, type MemoryOperations as aP, type MemoryRecallOptions as aQ, type MemoryUpdateInput as aR, type MessageContent as aS, type MessageRole as aT, type ObjectRef as aU, type RagContextItem as aV, type RagOperations as aW, type RagOptions as aX, type RagResult as aY, type RagStreamEvent as aZ, type ReasoningOperations as a_, type ChatCompletionChunk as aa, type ChatCompletionDelta as ab, type ChatCompletionRequest as ac, type ChatCompletionResponse as ad, type ChatHistoryOptions as ae, type ChatMessage as af, type ChatRecord as ag, type Citation as ah, type DefineToolOptions as ai, type EntityDocumentRelation as aj, type EntityDocumentResult as ak, type EntityListOptions as al, type EntityQueryOptions as am, type ImageContent as an, type InteractionScope as ao, type KnowledgeAskOptions as ap, type KnowledgeAskResult as aq, type KnowledgeDocumentInfo as ar, type KnowledgeDocumentListOptions as as, type KnowledgeDocumentRemoveOptions as at, type KnowledgeEntity as au, type KnowledgeIngestBatchProgress as av, type KnowledgeIngestBatchResult as aw, type KnowledgeIngestFileInput as ax, type KnowledgeIngestInput as ay, type KnowledgeIngestResult as az, A2ASkillConfigSchema as b, type ReasoningResult as b0, type ReasoningStep as b1, type ReasoningStepType as b2, type ReasoningStrategy as b3, type ReasoningStreamEvent as b4, type RetrievalOperations as b5, type RetrievalRequest as b6, type RetrievalResult as b7, type RetrievalResultItem as b8, type RetrievalSource as b9, type SSEDecoder as ba, type SSEEvent as bb, type SessionInfo as bc, type StoreFilter as bd, type StorePage as be, type StoreScope as bf, type StreamOperations as bg, type StreamProcessor as bh, type StreamResult as bi, type SystemMessage as bj, type TextContent as bk, type TokenUsage as bl, type Tool as bm, type ToolCall as bn, type ToolDefinition as bo, type ToolErrorType as bp, type ToolMessage as bq, type ToolRegistryOperations as br, type ToolsOperations as bs, type UserMessage as bt, type WhereClause as bu, type WhereOperator as bv, type WhereValue as bw, type AIConfig as c, type AIConfigInput as d, AIConfigSchema as e, CompressConfigSchema as f, EmbeddingConfigSchema as g, type EntityType as h, EntityTypeSchema as i, FileConfigSchema as j, KnowledgeConfigSchema as k, LLMConfigSchema as l, MCPConfigSchema as m, type MCPServerCapabilities as n, MCPServerCapabilitiesSchema as o, type MCPServerConfig as p, MCPServerConfigSchema as q, type MemoryConfig as r, MemoryConfigSchema as s, type MemoryType as t, MemoryTypeSchema as u, type ModelEntry as v, ModelEntrySchema as w, type ModelScenario as x, ModelScenarioSchema as y, type ResolvedModelConfig as z };