@h-ai/ai 0.1.0-alpha5

package/dist/ai-types-7iSHMnGM.d.ts

@@ -0,0 +1,1095 @@
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+import { af as ChatMessage, ao as InteractionScope, aM as MemoryInjectionOptions, aX as RagOptions, a$ as ReasoningOptions, br as ToolRegistryOperations, bc as SessionInfo, aG as LLMOperations, aP as MemoryOperations, aW as RagOperations, a_ as ReasoningOperations, c as AIConfig, d as AIConfigInput, a5 as AIStoreProvider, bs as ToolsOperations, bg as StreamOperations, b5 as RetrievalOperations, aA as KnowledgeOperations, $ as A2AOperations } from './ai-reasoning-types-ZRy23rSK.js';
+import { z } from 'zod';
+import { Buffer } from 'node:buffer';
+
+/**
+ * @h-ai/ai — Compress 子功能类型
+ *
+ * 定义上下文压缩操作的类型接口：滑动窗口、摘要、混合三种策略。
+ * 在对话超出模型上下文窗口时，自动压缩历史消息以保持对话连续性。
+ * @module ai-compress-types
+ */
+
+/** 压缩策略枚举 */
+declare const CompressionStrategySchema: z.ZodEnum<{
+    summary: "summary";
+    "sliding-window": "sliding-window";
+    hybrid: "hybrid";
+}>;
+/** 压缩策略类型 */
+type CompressionStrategy = z.infer<typeof CompressionStrategySchema>;
+/**
+ * 上下文压缩选项
+ */
+interface CompressOptions {
+    /** 压缩策略（默认使用配置的 defaultStrategy） */
+    strategy?: CompressionStrategy;
+    /** 目标 token 数（默认使用配置的 defaultMaxTokens，0 表示取模型 maxTokens 的 80%） */
+    maxTokens?: number;
+    /** 保留 system 消息（默认 true） */
+    preserveSystem?: boolean;
+    /** 保留最近 N 条消息不压缩（默认使用配置的 preserveLastN） */
+    preserveLastN?: number;
+    /** 摘要用的模型 */
+    summaryModel?: string;
+}
+/**
+ * 上下文压缩结果
+ */
+interface CompressResult {
+    /** 压缩后的消息列表 */
+    messages: ChatMessage[];
+    /** 原始消息的估算 token 数 */
+    originalTokens: number;
+    /** 压缩后的估算 token 数 */
+    compressedTokens: number;
+    /** 被移除/合并的消息数 */
+    removedCount: number;
+    /** 生成的摘要文本（仅 summary/hybrid 策略有值） */
+    summary?: string;
+}
+/**
+ * Compress 操作接口
+ *
+ * 管理对话消息的压缩，支持三种策略：
+ * - `sliding-window`：移除最旧的消息，保留最近 N 条
+ * - `summary`：使用 LLM 生成摘要替换旧消息
+ * - `hybrid`：先滑动窗口，不够则回退到摘要
+ *
+ * @example
+ * ```ts
+ * const result = await compressOps.tryCompress(messages, {
+ *   strategy: 'hybrid',
+ *   maxTokens: 4000,
+ * })
+ * if (result.success) {
+ *   const compressed = result.data.messages
+ * }
+ * ```
+ */
+interface CompressOperations {
+    /**
+     * 尝试压缩消息列表，使其不超过指定 Token 预算
+     *
+     * 如果当前 token 数未超限则直接返回（不压缩），因此命名为 tryCompress。
+     *
+     * @param messages - 消息列表
+     * @param options - 压缩选项
+     * @returns 压缩结果
+     */
+    tryCompress: (messages: ChatMessage[], options?: CompressOptions) => Promise<HaiResult<CompressResult>>;
+}
+
+/**
+ * @h-ai/ai — Summary 子功能类型
+ *
+ * 定义摘要生成操作的类型接口：使用 LLM 对对话消息生成摘要，支持增量摘要。
+ * @module ai-summary-types
+ */
+
+/**
+ * 摘要生成选项
+ */
+interface SummaryOptions {
+    /** 摘要用的模型 */
+    model?: string;
+    /** 温度覆盖 */
+    temperature?: number;
+    /** 自定义摘要 systemPrompt（覆盖模块配置与内置默认提示词） */
+    systemPrompt?: string;
+    /** 前序摘要文本（用于增量摘要） */
+    previousSummary?: string;
+}
+/**
+ * 摘要生成结果
+ */
+interface SummaryResult {
+    /** 摘要文本 */
+    summary: string;
+    /** 摘要的估算 Token 数 */
+    tokenCount: number;
+    /** 覆盖的原始消息数 */
+    coveredMessages: number;
+}
+/**
+ * Summary 操作接口
+ *
+ * 使用 LLM 对消息列表生成摘要，支持全量摘要与增量摘要。
+ *
+ * @example
+ * ```ts
+ * // 生成摘要（含元数据）
+ * const result = await summaryOps.summarize(messages)
+ * // result.data: { summary, tokenCount, coveredMessages }
+ *
+ * // 仅获取摘要文本
+ * const text = await summaryOps.generate(messages)
+ *
+ * // 增量摘要
+ * const updated = await summaryOps.summarize(newMessages, {
+ *   systemPrompt: 'Focus on product decisions and pending action items.',
+ *   previousSummary: oldSummary,
+ * })
+ * ```
+ */
+interface SummaryOperations {
+    /**
+     * 生成摘要文本
+     *
+     * @param messages - 消息列表
+     * @param options - 摘要选项
+     * @returns 摘要文本
+     */
+    generate: (messages: ChatMessage[], options?: SummaryOptions) => Promise<HaiResult<string>>;
+    /**
+     * 生成摘要（含元数据）
+     *
+     * @param messages - 消息列表
+     * @param options - 摘要选项
+     * @returns 摘要结果（含 Token 数、覆盖消息数）
+     */
+    summarize: (messages: ChatMessage[], options?: SummaryOptions) => Promise<HaiResult<SummaryResult>>;
+}
+
+/**
+ * @h-ai/ai — Context 子功能类型
+ *
+ * 定义上下文管理操作的类型接口。
+ * Context 是全部子模块的聚合层，提供有状态的 ContextManager：
+ * 多轮对话自动压缩 + 可选 LLM / Memory / RAG / Reasoning / Tools 编排。
+ * @module ai-context-types
+ */
+
+/**
+ * Context 子功能可选依赖
+ *
+ * 传入后 ContextManager 可提供 chat/chatStream 等高层编排能力。
+ * 各依赖按需传入，未传入的能力不可用。
+ */
+interface ContextDeps {
+    /** LLM 操作（chat/chatStream 必需） */
+    llm?: LLMOperations;
+    /** Memory 操作（记忆注入/提取需要） */
+    memory?: MemoryOperations;
+    /** RAG 操作（检索增强生成需要） */
+    rag?: RagOperations;
+    /** Reasoning 操作（推理引擎需要） */
+    reasoning?: ReasoningOperations;
+}
+/**
+ * 有状态上下文管理器配置
+ *
+ * 通过嵌套子对象直接引用各子模块的配置类型，避免字段重复声明。
+ */
+interface ContextManagerOptions {
+    /** 交互作用域（objectId + sessionId） */
+    scope?: InteractionScope;
+    /** 系统提示词（创建时作为首条 system 消息追加） */
+    systemPrompt?: string;
+    /** LLM 模型名覆盖 */
+    model?: string;
+    /** 温度覆盖 */
+    temperature?: number;
+    /**
+     * 压缩配置（覆盖全局 compress 配置）
+     *
+     * 直接引用 CompressOptions，加上 auto 开关。
+     */
+    compress?: CompressOptions & {
+        /** 是否自动触发压缩（默认 true） */
+        auto?: boolean;
+    };
+    /**
+     * 记忆配置
+     *
+     * 引用 MemoryInjectionOptions 的检索控制字段，加上 enable/enableExtract 开关。
+     */
+    memory?: Pick<MemoryInjectionOptions, 'topK' | 'maxTokens' | 'position'> & {
+        /** 是否启用记忆注入（默认 false） */
+        enable?: boolean;
+        /** 是否启用自动记忆提取（默认 false） */
+        enableExtract?: boolean;
+    };
+    /**
+     * RAG 配置
+     *
+     * 引用 RagOptions 中检索相关的字段。
+     */
+    rag?: Pick<RagOptions, 'sources' | 'topK' | 'minScore' | 'enableRerank' | 'rerankModel'> & {
+        /** 是否启用 RAG 检索增强（默认 false） */
+        enable?: boolean;
+    };
+    /**
+     * 推理配置
+     *
+     * 引用 ReasoningOptions 中策略相关的字段。
+     */
+    reasoning?: Pick<ReasoningOptions, 'strategy' | 'maxRounds'> & {
+        /** 是否启用推理引擎替代普通 LLM（默认 false） */
+        enable?: boolean;
+    };
+    /** 工具注册表（传入后 chat/chatStream 支持 function calling） */
+    tools?: ToolRegistryOperations;
+    /**
+     * 工具调用最大轮次（默认 10）
+     *
+     * 当 LLM 返回 tool_calls 时，自动执行工具并将结果回传 LLM，
+     * 重复此过程直到 LLM 给出文本回复或达到最大轮次。
+     */
+    maxToolRounds?: number;
+}
+/**
+ * 单次 chat/chatStream 请求的覆盖选项
+ */
+interface ContextChatOptions {
+    /** LLM 模型名覆盖 */
+    model?: string;
+    /** 温度覆盖 */
+    temperature?: number;
+    /** 是否启用本次 LLM 调用的持久化（默认 false，Context 自行管理状态） */
+    enablePersist?: boolean;
+}
+/**
+ * chat() 返回的结果
+ */
+interface ContextChatResult {
+    /** LLM 回复内容 */
+    reply: string;
+    /** 使用的模型 */
+    model: string;
+    /** Token 使用统计 */
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * chatStream() 产出的事件
+ */
+type ContextStreamEvent = {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'tool_call';
+    name: string;
+    arguments: string;
+} | {
+    type: 'tool_result';
+    name: string;
+    content: string;
+    success: boolean;
+} | {
+    type: 'done';
+    reply: string;
+    model: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+};
+/**
+ * 有状态上下文管理器接口
+ *
+ * 适用于多轮对话场景。追加消息并在超限时自动压缩；
+ * 若传入 deps.llm 则可直接通过 chat/chatStream 进行对话编排。
+ *
+ * @example
+ * ```ts
+ * // 创建管理器并直接对话
+ * const managerResult = ai.context.createManager({
+ *   scope: { objectId: 'user-001', sessionId: 'sess-001' },
+ *   systemPrompt: '你是一个友好的助手。',
+ *   compress: { maxTokens: 8000, strategy: 'hybrid' },
+ *   memory: { enable: true, enableExtract: true },
+ * })
+ * const manager = managerResult.data
+ *
+ * const result = await manager.chat('你好')
+ * console.log(result.data.reply)
+ *
+ * for await (const event of manager.chatStream('讲个故事')) {
+ *   if (event.type === 'delta') process.stdout.write(event.text)
+ * }
+ *
+ * await manager.save()
+ * ```
+ */
+interface ContextManager {
+    /** 当前作用域（如已配置） */
+    readonly scope?: InteractionScope;
+    /**
+     * 追加消息
+     *
+     * 自动在超限时触发压缩（如果启用了 compress.auto）。
+     *
+     * @param message - 要追加的消息
+     * @returns 成功返回 ok(undefined)
+     */
+    addMessage: (message: ChatMessage) => Promise<HaiResult<void>>;
+    /**
+     * 获取当前消息列表（压缩后）
+     *
+     * @returns 当前消息列表
+     */
+    getMessages: () => HaiResult<ChatMessage[]>;
+    /**
+     * 获取当前 token 使用量
+     *
+     * @returns 当前 token 数和预算
+     */
+    getTokenUsage: () => HaiResult<{
+        current: number;
+        budget: number;
+    }>;
+    /**
+     * 获取历史摘要列表
+     *
+     * @returns 每次压缩产生的摘要
+     */
+    getSummaries: () => HaiResult<SummaryResult[]>;
+    /**
+     * 持久化当前状态（需要 scope + 存储可用）
+     */
+    save: () => Promise<HaiResult<void>>;
+    /**
+     * 重置管理器（清空所有消息和摘要）
+     */
+    reset: () => void;
+    /**
+     * 发送消息并获取回复（需 deps.llm 可用）
+     *
+     * 流程：追加用户消息 → 自动压缩 → 注入记忆(可选) → RAG(可选) → LLM/Reasoning → 追加助手消息 → 提取记忆(可选)
+     *
+     * @param message - 用户消息文本
+     * @param options - 单次请求覆盖选项
+     * @returns 对话结果
+     */
+    chat: (message: string, options?: ContextChatOptions) => Promise<HaiResult<ContextChatResult>>;
+    /**
+     * 流式发送消息并获取回复（需 deps.llm 可用）
+     *
+     * 产出事件序列：delta* → done
+     *
+     * @param message - 用户消息文本
+     * @param options - 单次请求覆盖选项
+     * @returns 异步可迭代的 ContextStreamEvent
+     */
+    chatStream: (message: string, options?: ContextChatOptions) => AsyncIterable<ContextStreamEvent>;
+}
+/**
+ * Context 操作接口（通过 `ai.context` 访问）
+ *
+ * 提供有状态的 ContextManager，管理多轮对话的消息追加、自动压缩与对话编排。
+ * 原子操作（token / summary / compress）已独立暴露在 `ai.token`、`ai.summary`、`ai.compress`。
+ * 需要先调用 `ai.init()` 初始化后使用。
+ *
+ * @example
+ * ```ts
+ * // 创建管理器并对话
+ * const managerResult = ai.context.createManager({
+ *   scope: { objectId: 'user-001', sessionId: 'sess-001' },
+ *   compress: { maxTokens: 8000 },
+ *   memory: { enable: true },
+ * })
+ * const manager = managerResult.data
+ * const result = await manager.chat('你好')
+ *
+ * // 从持久化恢复管理器
+ * const restored = await ai.context.restoreManager(
+ *   { objectId: 'user-001', sessionId: 'sess-001' },
+ *   { memory: { enable: true } },
+ * )
+ * ```
+ */
+interface ContextOperations {
+    /**
+     * 创建有状态上下文管理器
+     *
+     * @param options - 管理器配置
+     * @returns 管理器实例
+     */
+    createManager: (options?: ContextManagerOptions) => HaiResult<ContextManager>;
+    /**
+     * 从持久化恢复上下文管理器
+     *
+     * @param scope - 交互作用域
+     * @param options - 管理器配置覆盖
+     * @returns 恢复的管理器实例
+     */
+    restoreManager: (scope: InteractionScope, options?: Omit<ContextManagerOptions, 'scope'>) => Promise<HaiResult<ContextManager>>;
+    /**
+     * 列出指定主体的所有会话
+     *
+     * @param objectId - 主体 ID
+     * @returns 会话信息列表
+     */
+    listSessions: (objectId: string) => Promise<HaiResult<SessionInfo[]>>;
+    /**
+     * 重命名会话
+     *
+     * @param sessionId - 会话 ID
+     * @param title - 新标题
+     * @returns 成功返回 ok(undefined)
+     */
+    renameSession: (sessionId: string, title: string) => Promise<HaiResult<void>>;
+    /**
+     * 删除会话（删除会话元数据和对应的上下文数据）
+     *
+     * @param sessionId - 会话 ID
+     * @returns 成功返回 ok(undefined)
+     */
+    removeSession: (sessionId: string) => Promise<HaiResult<void>>;
+}
+
+/**
+ * @h-ai/ai — Embedding 子功能类型
+ *
+ * 定义向量嵌入操作的类型接口。
+ * @module ai-embedding-types
+ */
+
+/**
+ * Embedding 请求参数
+ */
+interface EmbeddingRequest {
+    /** 输入文本（单条或批量） */
+    input: string | string[];
+    /** 模型名称（可选，未指定时使用配置中的默认模型） */
+    model?: string;
+    /** 向量维度（可选，部分模型支持） */
+    dimensions?: number;
+}
+/**
+ * 单条 Embedding 结果
+ */
+interface EmbeddingItem {
+    /** 在输入列表中的索引 */
+    index: number;
+    /** 向量数据 */
+    embedding: number[];
+}
+/**
+ * Embedding 响应
+ */
+interface EmbeddingResponse {
+    /** 模型名称 */
+    model: string;
+    /** Embedding 结果列表 */
+    data: EmbeddingItem[];
+    /** Token 使用统计 */
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Embedding Provider 接口
+ *
+ * 底层嵌入 API 适配层。
+ */
+interface EmbeddingProvider {
+    /** 生成向量嵌入 */
+    embed: (request: EmbeddingRequest) => Promise<HaiResult<EmbeddingResponse>>;
+}
+/**
+ * Embedding 操作接口（通过 `ai.embedding` 访问）
+ *
+ * 需要先调用 `ai.init()` 初始化后使用。
+ *
+ * @example
+ * ```ts
+ * // 单条文本嵌入
+ * const result = await ai.embedding.embed({ input: 'Hello World' })
+ *
+ * // 批量嵌入
+ * const result = await ai.embedding.embed({
+ *   input: ['文本1', '文本2', '文本3'],
+ * })
+ * ```
+ */
+interface EmbeddingOperations {
+    /**
+     * 生成向量嵌入
+     *
+     * @param request - Embedding 请求
+     * @returns Embedding 响应
+     */
+    embed: (request: EmbeddingRequest) => Promise<HaiResult<EmbeddingResponse>>;
+    /**
+     * 便捷方法：嵌入单条文本，直接返回向量
+     *
+     * @param text - 输入文本
+     * @returns 向量数组
+     */
+    embedText: (text: string) => Promise<HaiResult<number[]>>;
+    /**
+     * 便捷方法：批量嵌入文本，返回向量列表
+     *
+     * @param texts - 输入文本列表
+     * @returns 向量数组列表（与输入顺序一致）
+     */
+    embedBatch: (texts: string[]) => Promise<HaiResult<number[][]>>;
+}
+
+/**
+ * @h-ai/ai — File 子功能类型
+ *
+ * 定义文件解析操作的类型接口。
+ * @module ai-file-types
+ */
+
+/**
+ * 文件解析方法
+ *
+ * - `text` — 直接解码为 UTF-8 文本（txt / md / csv / 等文本格式）
+ * - `html` — HTML 标签剥除后提取文本
+ * - `pdf` — 使用 pdfjs-dist 解析 PDF（需安装可选依赖）
+ * - `docx` — 使用 mammoth 解析 Word 文档（需安装可选依赖）
+ * - `ocr` — 通过视觉 LLM 进行 OCR 识别（图片及无原生解析器的格式）
+ */
+type FileParseMethod = 'text' | 'html' | 'pdf' | 'docx' | 'ocr';
+/**
+ * 文件解析输出格式
+ * - `text` — 纯文本（默认），适合程序处理
+ * - `markdown` — Markdown 格式，保留文档结构（标题、列表、粗斜体等），
+ *   适用于 HTML、PDF、DOCX；图片 OCR 会提示模型输出 Markdown
+ */
+type OutputFormat = 'text' | 'markdown';
+/**
+ * 文件解析选项
+ */
+interface FileParseOptions {
+    /** 强制使用指定 MIME 类型（覆盖自动检测） */
+    mimeType?: string;
+    /** 强制使用 OCR（即使有原生解析器支持） */
+    useOcr?: boolean;
+    /**
+     * OCR 使用的视觉模型（请求级覆盖）
+     *
+     * 最高优先级，覆盖 `llm.scenarios.ocr` 场景映射。
+     * 未指定时通过 `llm.scenarios.ocr` 解析。
+     */
+    model?: string;
+    /** OCR 系统提示词（覆盖全局 `file.systemPrompt` 配置） */
+    systemPrompt?: string;
+    /** PDF 最大解析页数（默认解析全部页） */
+    maxPages?: number;
+    /**
+     * 输出格式（默认 `'text'`）
+     */
+    outputFormat?: OutputFormat;
+}
+/**
+ * 文件解析请求
+ */
+interface FileParseRequest {
+    /**
+     * 文件内容
+     *
+     * - `Buffer` — 二进制文件（图片、PDF、DOCX 等）
+     * - `string` — 文本内容（直接传入文本格式文件）
+     */
+    content: Buffer | string;
+    /** 文件名（用于 MIME 类型自动检测，可选） */
+    filename?: string;
+    /** 解析选项 */
+    options?: FileParseOptions;
+}
+/**
+ * 文件解析结果
+ */
+interface FileParseResult {
+    /** 提取的文本内容（当 `outputFormat` 为 `'markdown'` 时为 Markdown 格式） */
+    text: string;
+    /** 解析方法 */
+    method: FileParseMethod;
+    /** 页数（PDF 解析时） */
+    pageCount?: number;
+    /** 元数据 */
+    metadata?: {
+        filename?: string;
+        mimeType?: string;
+        charCount?: number;
+    };
+}
+/**
+ * File 操作接口（通过 `ai.file` 访问）
+ *
+ * 需要先调用 `ai.init()` 初始化后使用（OCR 功能需要 LLM 配置）。
+ *
+ * 支持的格式：
+ * - 文本格式（txt、md、csv 等）：直接解码
+ * - HTML：剥除标签后提取文本
+ * - PDF：使用 pdfjs-dist（需安装），否则回退到 OCR
+ * - DOCX：使用 mammoth（需安装），否则回退到 OCR
+ * - 图片（JPEG、PNG、GIF、WebP）：通过视觉 LLM OCR 识别
+ *
+ * @example
+ * ```ts
+ * import { readFile } from 'node:fs/promises'
+ *
+ * // 解析 PDF（OCR 模型通过 llm.scenarios.ocr 配置）
+ * ai.init({ llm: { apiKey: 'sk-...', scenarios: { ocr: 'gpt-4o' } } })
+ *
+ * const pdf = await readFile('document.pdf')
+ * const result = await ai.file.parse({ content: pdf, filename: 'document.pdf' })
+ *
+ * // 解析图片（OCR）
+ * const image = await readFile('screenshot.png')
+ * const result = await ai.file.parse({ content: image, filename: 'screenshot.png' })
+ *
+ * // 便捷方法：直接获取文本
+ * const text = await ai.file.parseText(content, 'document.pdf')
+ * ```
+ */
+interface FileOperations {
+    /**
+     * 解析文件内容，提取文本
+     *
+     * 自动检测文件格式，选择最优解析方法。
+     *
+     * @param request - 文件解析请求
+     * @returns 解析结果，包含文本内容、解析方法和元数据
+     */
+    parse: (request: FileParseRequest) => Promise<HaiResult<FileParseResult>>;
+    /**
+     * 便捷方法：直接返回提取的文本字符串
+     *
+     * @param content - 文件内容（Buffer 或文本字符串）
+     * @param filename - 文件名（用于格式检测，可选）
+     * @returns 提取的文本内容
+     */
+    parseText: (content: Buffer | string, filename?: string) => Promise<HaiResult<string>>;
+}
+
+/**
+ * @h-ai/ai — MCP 子功能类型
+ *
+ * 定义 MCP 工具、资源、提示词的注册与调用接口。
+ * @module ai-mcp-types
+ */
+
+/** MCP 工具定义（注册工具时的元数据） */
+interface MCPToolDefinition {
+    /** 工具名称（需唯一） */
+    name: string;
+    /** 工具功能描述 */
+    description: string;
+    /** 输入参数的 JSON Schema */
+    inputSchema: Record<string, unknown>;
+}
+/** MCP 工具处理器，接收输入参数和执行上下文 */
+type MCPToolHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: MCPContext) => Promise<TOutput> | TOutput;
+/** MCP 执行上下文，携带请求元数据 */
+interface MCPContext {
+    /** 请求唯一标识（未传入时自动生成 UUID） */
+    requestId?: string;
+    /** 客户端信息（可选） */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 自定义元数据（可选） */
+    metadata?: Record<string, unknown>;
+}
+/** MCP 资源描述（注册资源时的元数据） */
+interface MCPResource {
+    /** 资源 URI（唯一标识） */
+    uri: string;
+    /** 资源名称 */
+    name: string;
+    /** 资源描述（可选） */
+    description?: string;
+    /** MIME 类型（可选，如 `'application/json'`） */
+    mimeType?: string;
+}
+/** MCP 资源内容（readResource 的返回值） */
+interface MCPResourceContent {
+    /** 资源 URI */
+    uri: string;
+    /** MIME 类型（可选） */
+    mimeType?: string;
+    /** 文本内容（与 blob 二选一） */
+    text?: string;
+    /** Base64 编码的二进制内容（与 text 二选一） */
+    blob?: string;
+}
+/** MCP 提示词模板描述 */
+interface MCPPrompt {
+    /** 提示词名称（唯一标识） */
+    name: string;
+    /** 提示词描述（可选） */
+    description?: string;
+    /** 参数定义列表（可选） */
+    arguments?: MCPPromptArgument[];
+}
+/** MCP 提示词参数定义 */
+interface MCPPromptArgument {
+    /** 参数名称 */
+    name: string;
+    /** 参数描述（可选） */
+    description?: string;
+    /** 是否必填（默认 `false`） */
+    required?: boolean;
+}
+/** MCP 提示词消息（getPrompt 的返回值元素） */
+interface MCPPromptMessage {
+    /** 消息角色 */
+    role: 'user' | 'assistant';
+    /** 消息内容 */
+    content: MCPPromptContent;
+}
+/** MCP 提示词内容（支持纯文本或资源引用） */
+interface MCPPromptContent {
+    /** 内容类型：`'text'` 纯文本 | `'resource'` 资源引用 */
+    type: 'text' | 'resource';
+    /** 文本内容（type 为 `'text'` 时） */
+    text?: string;
+    /** 资源引用（type 为 `'resource'` 时） */
+    resource?: {
+        uri: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    };
+}
+/** MCP 服务器创建选项 */
+interface McpServerOptions {
+    /** 服务器名称 */
+    name: string;
+    /** 服务器版本（默认 `'1.0.0'`） */
+    version?: string;
+}
+/**
+ * MCP Provider 接口
+ *
+ * 定义 MCP 工具/资源/提示词的注册与调用能力。
+ */
+interface MCPProvider {
+    registerTool: <TInput, TOutput>(definition: MCPToolDefinition, handler: MCPToolHandler<TInput, TOutput>) => HaiResult<void>;
+    registerResource: (resource: MCPResource, handler: () => Promise<MCPResourceContent>) => HaiResult<void>;
+    registerPrompt: (prompt: MCPPrompt, handler: (args: Record<string, string>) => Promise<MCPPromptMessage[]>) => HaiResult<void>;
+    callTool: (name: string, args: unknown, context?: MCPContext) => Promise<HaiResult<unknown>>;
+    readResource: (uri: string) => Promise<HaiResult<MCPResourceContent>>;
+    getPrompt: (name: string, args: Record<string, string>) => Promise<HaiResult<MCPPromptMessage[]>>;
+}
+/**
+ * MCP 操作接口（通过 `ai.mcp` 访问）
+ *
+ * 需要先调用 `ai.init()` 初始化，否则所有方法返回 `NOT_INITIALIZED` 错误。
+ */
+interface MCPOperations {
+    registerTool: <TInput, TOutput>(definition: MCPToolDefinition, handler: MCPToolHandler<TInput, TOutput>) => HaiResult<void>;
+    registerResource: (resource: MCPResource, handler: () => Promise<MCPResourceContent>) => HaiResult<void>;
+    registerPrompt: (prompt: MCPPrompt, handler: (args: Record<string, string>) => Promise<MCPPromptMessage[]>) => HaiResult<void>;
+    callTool: (name: string, args: unknown, context?: MCPContext) => Promise<HaiResult<unknown>>;
+    readResource: (uri: string) => Promise<HaiResult<MCPResourceContent>>;
+    getPrompt: (name: string, args: Record<string, string>) => Promise<HaiResult<MCPPromptMessage[]>>;
+}
+/** MCP 子功能工厂依赖（内部使用） */
+interface AIMCPFunctionsDeps {
+    /** 校验后的 AI 配置 */
+    config: AIConfig;
+}
+
+/**
+ * @h-ai/ai — Rerank 子功能类型
+ *
+ * 定义文档重排序操作的类型接口。
+ * @module ai-rerank-types
+ */
+
+/**
+ * 单条待排序文档
+ */
+interface RerankDocument {
+    /** 文档唯一标识（可选，便于结果追踪） */
+    id?: string;
+    /** 文档文本内容 */
+    text: string;
+}
+/**
+ * Rerank 请求参数
+ */
+interface RerankRequest {
+    /** 查询文本 */
+    query: string;
+    /** 待排序文档列表（字符串数组或带 id 的文档对象数组） */
+    documents: string[] | RerankDocument[];
+    /** 模型名称（可选，未指定时使用配置中的默认模型） */
+    model?: string;
+    /** 返回结果数量（可选，默认返回全部文档） */
+    topN?: number;
+    /** 是否在结果中返回文档原文（默认 false） */
+    returnDocuments?: boolean;
+}
+/**
+ * 单条 Rerank 结果
+ */
+interface RerankItem {
+    /** 文档在原始输入中的索引 */
+    index: number;
+    /** 文档 ID（当输入为带 id 的文档对象时） */
+    id?: string;
+    /** 相关性分数（越高越相关） */
+    relevanceScore: number;
+    /** 文档原文（当 returnDocuments 为 true 时） */
+    document?: string;
+}
+/**
+ * Rerank 响应
+ */
+interface RerankResponse {
+    /** 使用的模型名称 */
+    model: string;
+    /** 重排序结果列表（按相关性分数降序排列） */
+    results: RerankItem[];
+}
+/**
+ * Rerank 操作接口（通过 `ai.rerank` 访问）
+ *
+ * 需要先调用 `ai.init()` 初始化后使用。
+ * 通过专用 Rerank API（兼容 Cohere 格式）对文档进行相关性重排序。
+ *
+ * @example
+ * ```ts
+ * // 对检索结果重排序
+ * const result = await ai.rerank.rerank({
+ *   query: '机器学习入门',
+ *   documents: [
+ *     '深度学习是机器学习的一个分支',
+ *     '今天天气真好',
+ *     '神经网络是深度学习的基础',
+ *   ],
+ *   topN: 2,
+ * })
+ *
+ * // 便捷方法：直接传入文本数组
+ * const items = await ai.rerank.rerankTexts('query', ['doc1', 'doc2'])
+ * ```
+ */
+interface RerankOperations {
+    /**
+     * 对文档列表进行相关性重排序
+     *
+     * @param request - Rerank 请求
+     * @returns 重排序响应，结果按相关性分数降序排列
+     */
+    rerank: (request: RerankRequest) => Promise<HaiResult<RerankResponse>>;
+    /**
+     * 便捷方法：对文本数组重排序，直接返回结果列表
+     *
+     * @param query - 查询文本
+     * @param texts - 待排序文本列表
+     * @param topN - 返回条数（可选）
+     * @returns RerankItem 列表，按相关性分数降序排列
+     */
+    rerankTexts: (query: string, texts: string[], topN?: number) => Promise<HaiResult<RerankItem[]>>;
+}
+
+/**
+ * @h-ai/ai — Token 子功能类型
+ *
+ * 定义 Token 估算操作的类型接口：文本与消息级别的 Token 数估算。
+ * 使用 CJK 感知的字符级估算算法，无需外部分词库依赖。
+ * @module ai-token-types
+ */
+
+/**
+ * Token 操作接口
+ *
+ * 提供 Token 估算能力，使用配置的 `tokenRatio` 做估算。
+ *
+ * @example
+ * ```ts
+ * const tokens = tokenOps.estimateText('Hello 世界')
+ * const total = tokenOps.estimateMessages(messages)
+ * ```
+ */
+interface TokenOperations {
+    /**
+     * 估算单条文本的 Token 数
+     *
+     * 使用字符级估算：中文约每字 1.5 token，英文约每 4 字符 1 token。
+     *
+     * @param text - 文本内容
+     * @returns 估算 Token 数
+     */
+    estimateText: (text: string) => number;
+    /**
+     * 估算消息列表的总 Token 数
+     *
+     * 包含消息结构开销（每条消息约 4 token 用于角色标记和分隔）。
+     *
+     * @param messages - 消息列表
+     * @returns 估算 Token 总数
+     */
+    estimateMessages: (messages: ChatMessage[]) => number;
+}
+
+/**
+ * AI 模块标准错误定义对象。
+ *
+ * 通过 `HaiAIError.ERROR_CODE_NAME` 访问具体错误定义，如：
+ * ```ts
+ * const def = HaiAIError.NOT_INITIALIZED
+ * // => { code: 'hai:ai:010', httpStatus: 500, system: 'hai', module: 'ai' }
+ * ```
+ */
+declare const HaiAIError: {
+    readonly INTERNAL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly CONFIGURATION_ERROR: _h_ai_core.HaiErrorDef;
+    readonly INIT_IN_PROGRESS: _h_ai_core.HaiErrorDef;
+    readonly RERANK_API_ERROR: _h_ai_core.HaiErrorDef;
+    readonly RERANK_INVALID_REQUEST: _h_ai_core.HaiErrorDef;
+    readonly API_ERROR: _h_ai_core.HaiErrorDef;
+    readonly INVALID_REQUEST: _h_ai_core.HaiErrorDef;
+    readonly RATE_LIMITED: _h_ai_core.HaiErrorDef;
+    readonly TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly MODEL_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_LENGTH_EXCEEDED: _h_ai_core.HaiErrorDef;
+    readonly LLM_RECORD_FAILED: _h_ai_core.HaiErrorDef;
+    readonly LLM_HISTORY_FAILED: _h_ai_core.HaiErrorDef;
+    readonly MCP_CONNECTION_ERROR: _h_ai_core.HaiErrorDef;
+    readonly MCP_PROTOCOL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly MCP_TOOL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly MCP_RESOURCE_ERROR: _h_ai_core.HaiErrorDef;
+    readonly MCP_SERVER_ERROR: _h_ai_core.HaiErrorDef;
+    readonly EMBEDDING_API_ERROR: _h_ai_core.HaiErrorDef;
+    readonly EMBEDDING_MODEL_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly EMBEDDING_INPUT_TOO_LONG: _h_ai_core.HaiErrorDef;
+    readonly TOOL_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly TOOL_VALIDATION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly TOOL_EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly TOOL_TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly REASONING_FAILED: _h_ai_core.HaiErrorDef;
+    readonly REASONING_MAX_ROUNDS: _h_ai_core.HaiErrorDef;
+    readonly REASONING_STRATEGY_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly RETRIEVAL_FAILED: _h_ai_core.HaiErrorDef;
+    readonly RETRIEVAL_SOURCE_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly RAG_FAILED: _h_ai_core.HaiErrorDef;
+    readonly RAG_CONTEXT_BUILD_FAILED: _h_ai_core.HaiErrorDef;
+    readonly KNOWLEDGE_SETUP_FAILED: _h_ai_core.HaiErrorDef;
+    readonly KNOWLEDGE_INGEST_FAILED: _h_ai_core.HaiErrorDef;
+    readonly KNOWLEDGE_RETRIEVE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly KNOWLEDGE_ENTITY_EXTRACT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly KNOWLEDGE_NOT_SETUP: _h_ai_core.HaiErrorDef;
+    readonly KNOWLEDGE_COLLECTION_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly MEMORY_EXTRACT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly MEMORY_STORE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly MEMORY_RECALL_FAILED: _h_ai_core.HaiErrorDef;
+    readonly MEMORY_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly MEMORY_ENRICH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly FILE_PARSE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly FILE_UNSUPPORTED_FORMAT: _h_ai_core.HaiErrorDef;
+    readonly FILE_OCR_FAILED: _h_ai_core.HaiErrorDef;
+    readonly FILE_INVALID_CONTENT: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_COMPRESS_FAILED: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_SUMMARIZE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_TOKEN_ESTIMATE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_BUDGET_EXCEEDED: _h_ai_core.HaiErrorDef;
+    readonly STORE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly STORE_NOT_AVAILABLE: _h_ai_core.HaiErrorDef;
+    readonly SESSION_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly SESSION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly A2A_NOT_CONFIGURED: _h_ai_core.HaiErrorDef;
+    readonly A2A_HANDLE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly A2A_REMOTE_CALL_FAILED: _h_ai_core.HaiErrorDef;
+    readonly A2A_AUTH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly A2A_LIST_MESSAGES_FAILED: _h_ai_core.HaiErrorDef;
+};
+/**
+ * AI 初始化运行时选项
+ *
+ * 用于传入运行时对象（如自定义 StoreProvider），
+ * 这些对象无法通过 Zod 配置 Schema 传递。
+ */
+interface AIInitOptions {
+    /**
+     * 自定义存储 Provider
+     *
+     * 提供后 AI 模块将使用此 Provider 而非默认的 reldb+vecdb 实现，
+     * 此时不需要提前初始化 reldb/vecdb。
+     */
+    storeProvider?: AIStoreProvider;
+}
+/**
+ * AI 服务接口（通过 `ai` 对象访问）
+ *
+ * 所有 AI 功能的统一入口，需先调用 `init()` 初始化后才能使用 `llm`、`mcp` 操作。
+ * `tools` 和 `stream` 为纯函数，无需初始化即可使用。
+ *
+ * @example
+ * ```ts
+ * import { ai } from '@h-ai/ai'
+ *
+ * await ai.init({ llm: { model: 'gpt-4o-mini' } })
+ * const result = await ai.llm.chat({ messages: [{ role: 'user', content: '你好' }] })
+ * ai.close()
+ * ```
+ */
+interface AIFunctions {
+    /**
+     * 初始化 AI 服务
+     *
+     * 使用 Zod Schema 校验配置，失败返回 `CONFIGURATION_ERROR`。
+     * 重复调用会先关闭旧实例再重新初始化。
+     *
+     * @param config - AI 配置（可选，默认使用空对象并应用 Schema 默认值）
+     * @param options - 运行时选项（可选，用于传入自定义 StoreProvider 等运行时对象）
+     * @returns 成功返回 `ok(undefined)`；配置校验失败返回 `err(HaiAIError.CONFIGURATION_ERROR)`
+     */
+    init: (config?: AIConfigInput, options?: AIInitOptions) => Promise<HaiResult<void>>;
+    /**
+     * 关闭 AI 服务，释放内部状态
+     *
+     * 关闭后 `llm`、`mcp` 操作将返回 `NOT_INITIALIZED` 错误。
+     * 重复关闭不会报错。
+     */
+    close: () => void;
+    /** 当前配置（未初始化时为 `null`） */
+    readonly config: AIConfig | null;
+    /** 是否已初始化（`init()` 成功后为 `true`，`close()` 后为 `false`） */
+    readonly isInitialized: boolean;
+    /** LLM 操作（聊天、流式、模型列表），需要先调用 `init()` */
+    readonly llm: LLMOperations;
+    /** MCP 操作（工具/资源/提示词注册与调用），需要先调用 `init()` */
+    readonly mcp: MCPOperations;
+    /** 工具操作（定义工具与注册表），纯函数，无需初始化 */
+    readonly tools: ToolsOperations;
+    /** 流处理操作（流处理器、SSE 编解码），纯函数，无需初始化 */
+    readonly stream: StreamOperations;
+    /** Embedding 操作（向量嵌入），需要先调用 `init()` */
+    readonly embedding: EmbeddingOperations;
+    /** 推理操作（ReAct / CoT / Plan-Execute），需要先调用 `init()` */
+    readonly reasoning: ReasoningOperations;
+    /** 检索操作（向量检索），需要先调用 `init()` */
+    readonly retrieval: RetrievalOperations;
+    /** RAG 操作（检索增强生成），需要先调用 `init()` */
+    readonly rag: RagOperations;
+    /** Knowledge 操作（知识库管理与检索），需要先调用 `init()` 和 `knowledge.setup()` */
+    readonly knowledge: KnowledgeOperations;
+    /** Memory 操作（记忆提取、存储、检索、注入），需要先调用 `init()` */
+    readonly memory: MemoryOperations;
+    /** Token 操作（Token 估算），需要先调用 `init()` */
+    readonly token: TokenOperations;
+    /** Summary 操作（消息摘要生成），需要先调用 `init()` */
+    readonly summary: SummaryOperations;
+    /** Compress 操作（上下文压缩），需要先调用 `init()` */
+    readonly compress: CompressOperations;
+    /** Context 操作（有状态上下文管理器，编排 LLM + Memory + RAG + Reasoning），需要先调用 `init()` */
+    readonly context: ContextOperations;
+    /** Rerank 操作（文档重排序），需要先调用 `init()` */
+    readonly rerank: RerankOperations;
+    /** File 操作（文件内容解析），需要先调用 `init()` */
+    readonly file: FileOperations;
+    /** A2A 操作（Agent-to-Agent 协议），需要先调用 `init()` 并配置 `a2a` */
+    readonly a2a: A2AOperations;
+}
+
+export { type AIFunctions as A, type MCPProvider as B, type CompressionStrategy as C, type MCPResource as D, type EmbeddingItem as E, type FileOperations as F, type MCPResourceContent as G, HaiAIError as H, type MCPToolDefinition as I, type MCPToolHandler as J, type McpServerOptions as K, type RerankItem as L, type MCPContext as M, type RerankOperations as N, type OutputFormat as O, type RerankRequest as P, type RerankResponse as Q, type RerankDocument as R, type SummaryOperations as S, type SummaryOptions as T, type SummaryResult as U, type TokenOperations as V, type AIInitOptions as a, CompressionStrategySchema as b, type AIMCPFunctionsDeps as c, type CompressOperations as d, type CompressOptions as e, type CompressResult as f, type ContextChatOptions as g, type ContextChatResult as h, type ContextDeps as i, type ContextManager as j, type ContextManagerOptions as k, type ContextOperations as l, type ContextStreamEvent as m, type EmbeddingOperations as n, type EmbeddingProvider as o, type EmbeddingRequest as p, type EmbeddingResponse as q, type FileParseMethod as r, type FileParseOptions as s, type FileParseRequest as t, type FileParseResult as u, type MCPOperations as v, type MCPPrompt as w, type MCPPromptArgument as x, type MCPPromptContent as y, type MCPPromptMessage as z };