@h-ai/ai 0.1.0-alpha9 → 1.0.0-beta.1

package/dist/chunk-HYMP57AC.js

@@ -0,0 +1,118 @@
+import { core } from '@h-ai/core';
+
+// src/ai-types.ts
+var AIErrorInfo = {
+  // 通用 (000-009)
+  INTERNAL_ERROR: "000:500",
+  // 初始化 (010-019)
+  NOT_INITIALIZED: "010:500",
+  CONFIGURATION_ERROR: "011:500",
+  INIT_IN_PROGRESS: "012:500",
+  RERANK_API_ERROR: "020:502",
+  RERANK_INVALID_REQUEST: "021:400",
+  // LLM (100-199)
+  API_ERROR: "100:502",
+  INVALID_REQUEST: "101:400",
+  RATE_LIMITED: "102:429",
+  TIMEOUT: "103:504",
+  MODEL_NOT_FOUND: "104:404",
+  CONTEXT_LENGTH_EXCEEDED: "105:400",
+  LLM_RECORD_FAILED: "106:500",
+  LLM_HISTORY_FAILED: "107:500",
+  // MCP (200-299)
+  MCP_CONNECTION_ERROR: "200:502",
+  MCP_PROTOCOL_ERROR: "201:502",
+  MCP_TOOL_ERROR: "202:500",
+  MCP_RESOURCE_ERROR: "203:500",
+  MCP_SERVER_ERROR: "204:502",
+  // Embedding (300-399)
+  EMBEDDING_API_ERROR: "300:502",
+  EMBEDDING_MODEL_NOT_FOUND: "301:404",
+  EMBEDDING_INPUT_TOO_LONG: "302:400",
+  // 工具 (400-499)
+  TOOL_NOT_FOUND: "400:404",
+  TOOL_VALIDATION_FAILED: "401:400",
+  TOOL_EXECUTION_FAILED: "402:500",
+  TOOL_TIMEOUT: "403:504",
+  TOOL_ALREADY_REGISTERED: "404:409",
+  TOOL_FORBIDDEN: "405:403",
+  // Reasoning (500-599)
+  REASONING_FAILED: "500:500",
+  REASONING_MAX_ROUNDS: "501:400",
+  REASONING_STRATEGY_NOT_FOUND: "502:404",
+  // Retrieval (600-699)
+  RETRIEVAL_FAILED: "600:500",
+  RETRIEVAL_SOURCE_NOT_FOUND: "601:404",
+  // RAG (700-799)
+  RAG_FAILED: "700:500",
+  RAG_CONTEXT_BUILD_FAILED: "701:500",
+  // Knowledge (800-899)
+  KNOWLEDGE_SETUP_FAILED: "800:500",
+  KNOWLEDGE_INGEST_FAILED: "801:500",
+  KNOWLEDGE_RETRIEVE_FAILED: "802:500",
+  KNOWLEDGE_ENTITY_EXTRACT_FAILED: "803:500",
+  KNOWLEDGE_NOT_SETUP: "804:500",
+  KNOWLEDGE_COLLECTION_NOT_FOUND: "805:404",
+  // Memory (900-949)
+  MEMORY_EXTRACT_FAILED: "900:500",
+  MEMORY_STORE_FAILED: "901:500",
+  MEMORY_RECALL_FAILED: "902:500",
+  MEMORY_NOT_FOUND: "903:404",
+  MEMORY_ENRICH_FAILED: "904:500",
+  MEMORY_PROMOTE_FAILED: "905:500",
+  MEMORY_LIST_INCOMPLETE: "906:422",
+  // Persona (910-919)
+  PERSONA_NOT_FOUND: "910:404",
+  PERSONA_SAVE_FAILED: "911:500",
+  // File (030-049)
+  FILE_PARSE_FAILED: "030:500",
+  FILE_UNSUPPORTED_FORMAT: "031:400",
+  FILE_OCR_FAILED: "032:500",
+  FILE_INVALID_CONTENT: "033:400",
+  // Audio (050-059)
+  AUDIO_INVALID_REQUEST: "050:400",
+  AUDIO_MODEL_NOT_FOUND: "051:404",
+  AUDIO_PROVIDER_NOT_FOUND: "052:404",
+  AUDIO_UNSUPPORTED_INPUT: "053:400",
+  AUDIO_UPSTREAM_ERROR: "054:502",
+  AUDIO_PROTOCOL_ERROR: "055:502",
+  AUDIO_CONNECTION_FAILED: "056:502",
+  AUDIO_TIMEOUT: "057:504",
+  AUDIO_INPUT_TOO_LARGE: "058:413",
+  AUDIO_CANCELLED: "059:499",
+  // Image (060-069)
+  IMAGE_INVALID_REQUEST: "060:400",
+  IMAGE_MODEL_NOT_FOUND: "061:404",
+  IMAGE_PROVIDER_NOT_FOUND: "062:404",
+  IMAGE_UPSTREAM_ERROR: "063:502",
+  IMAGE_PROTOCOL_ERROR: "064:502",
+  IMAGE_CANCELLED: "065:499",
+  IMAGE_DOWNLOAD_BLOCKED: "066:502",
+  IMAGE_TOO_LARGE: "067:413",
+  IMAGE_TIMEOUT: "068:504",
+  // Context (950-999)
+  CONTEXT_COMPRESS_FAILED: "950:500",
+  CONTEXT_SUMMARIZE_FAILED: "951:500",
+  CONTEXT_TOKEN_ESTIMATE_FAILED: "952:500",
+  CONTEXT_BUDGET_EXCEEDED: "953:400",
+  CONTEXT_TURN_NOT_FOUND: "954:404",
+  CONTEXT_TURN_INVALID_STATE: "955:409",
+  CONTEXT_BUSY: "956:409",
+  // Store (960-969)
+  STORE_FAILED: "960:500",
+  STORE_NOT_AVAILABLE: "961:503",
+  // Session (970-979)
+  SESSION_NOT_FOUND: "970:404",
+  SESSION_FAILED: "971:500",
+  // A2A (980-999)
+  A2A_NOT_CONFIGURED: "980:500",
+  A2A_HANDLE_FAILED: "981:500",
+  A2A_REMOTE_CALL_FAILED: "982:502",
+  A2A_AUTH_FAILED: "983:401",
+  A2A_LIST_MESSAGES_FAILED: "984:500"
+};
+var HaiAIError = core.error.buildHaiErrorsDef("ai", AIErrorInfo);
+
+export { HaiAIError };
+//# sourceMappingURL=chunk-HYMP57AC.js.map
+//# sourceMappingURL=chunk-HYMP57AC.js.map

package/dist/chunk-HYMP57AC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ai-types.ts"],"names":[],"mappings":";;;AAuCA,IAAM,WAAA,GAAc;AAAA;AAAA,EAElB,cAAA,EAAgB,SAAA;AAAA;AAAA,EAGhB,eAAA,EAAiB,SAAA;AAAA,EACjB,mBAAA,EAAqB,SAAA;AAAA,EACrB,gBAAA,EAAkB,SAAA;AAAA,EAClB,gBAAA,EAAkB,SAAA;AAAA,EAClB,sBAAA,EAAwB,SAAA;AAAA;AAAA,EAGxB,SAAA,EAAW,SAAA;AAAA,EACX,eAAA,EAAiB,SAAA;AAAA,EACjB,YAAA,EAAc,SAAA;AAAA,EACd,OAAA,EAAS,SAAA;AAAA,EACT,eAAA,EAAiB,SAAA;AAAA,EACjB,uBAAA,EAAyB,SAAA;AAAA,EACzB,iBAAA,EAAmB,SAAA;AAAA,EACnB,kBAAA,EAAoB,SAAA;AAAA;AAAA,EAGpB,oBAAA,EAAsB,SAAA;AAAA,EACtB,kBAAA,EAAoB,SAAA;AAAA,EACpB,cAAA,EAAgB,SAAA;AAAA,EAChB,kBAAA,EAAoB,SAAA;AAAA,EACpB,gBAAA,EAAkB,SAAA;AAAA;AAAA,EAGlB,mBAAA,EAAqB,SAAA;AAAA,EACrB,yBAAA,EAA2B,SAAA;AAAA,EAC3B,wBAAA,EAA0B,SAAA;AAAA;AAAA,EAG1B,cAAA,EAAgB,SAAA;AAAA,EAChB,sBAAA,EAAwB,SAAA;AAAA,EACxB,qBAAA,EAAuB,SAAA;AAAA,EACvB,YAAA,EAAc,SAAA;AAAA,EACd,uBAAA,EAAyB,SAAA;AAAA,EACzB,cAAA,EAAgB,SAAA;AAAA;AAAA,EAGhB,gBAAA,EAAkB,SAAA;AAAA,EAClB,oBAAA,EAAsB,SAAA;AAAA,EACtB,4BAAA,EAA8B,SAAA;AAAA;AAAA,EAG9B,gBAAA,EAAkB,SAAA;AAAA,EAClB,0BAAA,EAA4B,SAAA;AAAA;AAAA,EAG5B,UAAA,EAAY,SAAA;AAAA,EACZ,wBAAA,EAA0B,SAAA;AAAA;AAAA,EAG1B,sBAAA,EAAwB,SAAA;AAAA,EACxB,uBAAA,EAAyB,SAAA;AAAA,EACzB,yBAAA,EAA2B,SAAA;AAAA,EAC3B,+BAAA,EAAiC,SAAA;AAAA,EACjC,mBAAA,EAAqB,SAAA;AAAA,EACrB,8BAAA,EAAgC,SAAA;AAAA;AAAA,EAGhC,qBAAA,EAAuB,SAAA;AAAA,EACvB,mBAAA,EAAqB,SAAA;AAAA,EACrB,oBAAA,EAAsB,SAAA;AAAA,EACtB,gBAAA,EAAkB,SAAA;AAAA,EAClB,oBAAA,EAAsB,SAAA;AAAA,EACtB,qBAAA,EAAuB,SAAA;AAAA,EACvB,sBAAA,EAAwB,SAAA;AAAA;AAAA,EAGxB,iBAAA,EAAmB,SAAA;AAAA,EACnB,mBAAA,EAAqB,SAAA;AAAA;AAAA,EAGrB,iBAAA,EAAmB,SAAA;AAAA,EACnB,uBAAA,EAAyB,SAAA;AAAA,EACzB,eAAA,EAAiB,SAAA;AAAA,EACjB,oBAAA,EAAsB,SAAA;AAAA;AAAA,EAGtB,qBAAA,EAAuB,SAAA;AAAA,EACvB,qBAAA,EAAuB,SAAA;AAAA,EACvB,wBAAA,EAA0B,SAAA;AAAA,EAC1B,uBAAA,EAAyB,SAAA;AAAA,EACzB,oBAAA,EAAsB,SAAA;AAAA,EACtB,oBAAA,EAAsB,SAAA;AAAA,EACtB,uBAAA,EAAyB,SAAA;AAAA,EACzB,aAAA,EAAe,SAAA;AAAA,EACf,qBAAA,EAAuB,SAAA;AAAA,EACvB,eAAA,EAAiB,SAAA;AAAA;AAAA,EAGjB,qBAAA,EAAuB,SAAA;AAAA,EACvB,qBAAA,EAAuB,SAAA;AAAA,EACvB,wBAAA,EAA0B,SAAA;AAAA,EAC1B,oBAAA,EAAsB,SAAA;AAAA,EACtB,oBAAA,EAAsB,SAAA;AAAA,EACtB,eAAA,EAAiB,SAAA;AAAA,EACjB,sBAAA,EAAwB,SAAA;AAAA,EACxB,eAAA,EAAiB,SAAA;AAAA,EACjB,aAAA,EAAe,SAAA;AAAA;AAAA,EAGf,uBAAA,EAAyB,SAAA;AAAA,EACzB,wBAAA,EAA0B,SAAA;AAAA,EAC1B,6BAAA,EAA+B,SAAA;AAAA,EAC/B,uBAAA,EAAyB,SAAA;AAAA,EACzB,sBAAA,EAAwB,SAAA;AAAA,EACxB,0BAAA,EAA4B,SAAA;AAAA,EAC5B,YAAA,EAAc,SAAA;AAAA;AAAA,EAGd,YAAA,EAAc,SAAA;AAAA,EACd,mBAAA,EAAqB,SAAA;AAAA;AAAA,EAGrB,iBAAA,EAAmB,SAAA;AAAA,EACnB,cAAA,EAAgB,SAAA;AAAA;AAAA,EAGhB,kBAAA,EAAoB,SAAA;AAAA,EACpB,iBAAA,EAAmB,SAAA;AAAA,EACnB,sBAAA,EAAwB,SAAA;AAAA,EACxB,eAAA,EAAiB,SAAA;AAAA,EACjB,wBAAA,EAA0B;AAC5B,CAAA;AAgBO,IAAM,UAAA,GAAa,IAAA,CAAK,KAAA,CAAM,iBAAA,CAAkB,MAAM,WAAW","file":"chunk-HYMP57AC.js","sourcesContent":["/**\n * @h-ai/ai — 公共类型定义\n *\n * 聚合导出模块根类型和子功能类型，供外部通过 `@h-ai/ai` 一站式引入。\n * @module ai-types\n */\n\nimport type { ErrorInfo, HaiResult } from '@h-ai/core'\nimport type { A2AOperations } from './a2a/ai-a2a-types.js'\n\nimport type { AIConfig, AIConfigInput } from './ai-config.js'\nimport type { AudioOperations } from './audio/ai-audio-types.js'\nimport type { CompressOperations } from './compress/ai-compress-types.js'\nimport type { ContextOperations } from './context/ai-context-types.js'\nimport type { EmbeddingOperations } from './embedding/ai-embedding-types.js'\nimport type { FileOperations } from './file/ai-file-types.js'\nimport type { ImageOperations } from './image/ai-image-types.js'\nimport type { KnowledgeOperations } from './knowledge/ai-knowledge-types.js'\nimport type { LLMOperations, StreamOperations, ToolsOperations } from './llm/ai-llm-types.js'\nimport type { MCPOperations } from './mcp/ai-mcp-types.js'\nimport type { MemoryOperations } from './memory/ai-memory-types.js'\nimport type { PersonaOperations } from './persona/ai-persona-types.js'\nimport type { RagOperations } from './rag/ai-rag-types.js'\nimport type { ReasoningOperations } from './reasoning/ai-reasoning-types.js'\nimport type { RerankOperations } from './rerank/ai-rerank-types.js'\nimport type { RetrievalOperations } from './retrieval/ai-retrieval-types.js'\nimport type { AIStoreProvider } from './store/ai-store-types.js'\nimport type { SummaryOperations } from './summary/ai-summary-types.js'\nimport type { TokenOperations } from './token/ai-token-types.js'\nimport { core } from '@h-ai/core'\n\n// ─── 错误定义（照 @h-ai/core 范式） ───\n\n/**\n * AI 错误信息映射（错误码:HTTP状态码）。\n *\n * 错误码采用 3 位数字格式（000-999），HTTP 状态码遵循标准 HTTP 规范。\n * 完整错误码将自动生成为：`hai:ai:NNN`\n */\nconst AIErrorInfo = {\n  // 通用 (000-009)\n  INTERNAL_ERROR: '000:500',\n\n  // 初始化 (010-019)\n  NOT_INITIALIZED: '010:500',\n  CONFIGURATION_ERROR: '011:500',\n  INIT_IN_PROGRESS: '012:500',\n  RERANK_API_ERROR: '020:502',\n  RERANK_INVALID_REQUEST: '021:400',\n\n  // LLM (100-199)\n  API_ERROR: '100:502',\n  INVALID_REQUEST: '101:400',\n  RATE_LIMITED: '102:429',\n  TIMEOUT: '103:504',\n  MODEL_NOT_FOUND: '104:404',\n  CONTEXT_LENGTH_EXCEEDED: '105:400',\n  LLM_RECORD_FAILED: '106:500',\n  LLM_HISTORY_FAILED: '107:500',\n\n  // MCP (200-299)\n  MCP_CONNECTION_ERROR: '200:502',\n  MCP_PROTOCOL_ERROR: '201:502',\n  MCP_TOOL_ERROR: '202:500',\n  MCP_RESOURCE_ERROR: '203:500',\n  MCP_SERVER_ERROR: '204:502',\n\n  // Embedding (300-399)\n  EMBEDDING_API_ERROR: '300:502',\n  EMBEDDING_MODEL_NOT_FOUND: '301:404',\n  EMBEDDING_INPUT_TOO_LONG: '302:400',\n\n  // 工具 (400-499)\n  TOOL_NOT_FOUND: '400:404',\n  TOOL_VALIDATION_FAILED: '401:400',\n  TOOL_EXECUTION_FAILED: '402:500',\n  TOOL_TIMEOUT: '403:504',\n  TOOL_ALREADY_REGISTERED: '404:409',\n  TOOL_FORBIDDEN: '405:403',\n\n  // Reasoning (500-599)\n  REASONING_FAILED: '500:500',\n  REASONING_MAX_ROUNDS: '501:400',\n  REASONING_STRATEGY_NOT_FOUND: '502:404',\n\n  // Retrieval (600-699)\n  RETRIEVAL_FAILED: '600:500',\n  RETRIEVAL_SOURCE_NOT_FOUND: '601:404',\n\n  // RAG (700-799)\n  RAG_FAILED: '700:500',\n  RAG_CONTEXT_BUILD_FAILED: '701:500',\n\n  // Knowledge (800-899)\n  KNOWLEDGE_SETUP_FAILED: '800:500',\n  KNOWLEDGE_INGEST_FAILED: '801:500',\n  KNOWLEDGE_RETRIEVE_FAILED: '802:500',\n  KNOWLEDGE_ENTITY_EXTRACT_FAILED: '803:500',\n  KNOWLEDGE_NOT_SETUP: '804:500',\n  KNOWLEDGE_COLLECTION_NOT_FOUND: '805:404',\n\n  // Memory (900-949)\n  MEMORY_EXTRACT_FAILED: '900:500',\n  MEMORY_STORE_FAILED: '901:500',\n  MEMORY_RECALL_FAILED: '902:500',\n  MEMORY_NOT_FOUND: '903:404',\n  MEMORY_ENRICH_FAILED: '904:500',\n  MEMORY_PROMOTE_FAILED: '905:500',\n  MEMORY_LIST_INCOMPLETE: '906:422',\n\n  // Persona (910-919)\n  PERSONA_NOT_FOUND: '910:404',\n  PERSONA_SAVE_FAILED: '911:500',\n\n  // File (030-049)\n  FILE_PARSE_FAILED: '030:500',\n  FILE_UNSUPPORTED_FORMAT: '031:400',\n  FILE_OCR_FAILED: '032:500',\n  FILE_INVALID_CONTENT: '033:400',\n\n  // Audio (050-059)\n  AUDIO_INVALID_REQUEST: '050:400',\n  AUDIO_MODEL_NOT_FOUND: '051:404',\n  AUDIO_PROVIDER_NOT_FOUND: '052:404',\n  AUDIO_UNSUPPORTED_INPUT: '053:400',\n  AUDIO_UPSTREAM_ERROR: '054:502',\n  AUDIO_PROTOCOL_ERROR: '055:502',\n  AUDIO_CONNECTION_FAILED: '056:502',\n  AUDIO_TIMEOUT: '057:504',\n  AUDIO_INPUT_TOO_LARGE: '058:413',\n  AUDIO_CANCELLED: '059:499',\n\n  // Image (060-069)\n  IMAGE_INVALID_REQUEST: '060:400',\n  IMAGE_MODEL_NOT_FOUND: '061:404',\n  IMAGE_PROVIDER_NOT_FOUND: '062:404',\n  IMAGE_UPSTREAM_ERROR: '063:502',\n  IMAGE_PROTOCOL_ERROR: '064:502',\n  IMAGE_CANCELLED: '065:499',\n  IMAGE_DOWNLOAD_BLOCKED: '066:502',\n  IMAGE_TOO_LARGE: '067:413',\n  IMAGE_TIMEOUT: '068:504',\n\n  // Context (950-999)\n  CONTEXT_COMPRESS_FAILED: '950:500',\n  CONTEXT_SUMMARIZE_FAILED: '951:500',\n  CONTEXT_TOKEN_ESTIMATE_FAILED: '952:500',\n  CONTEXT_BUDGET_EXCEEDED: '953:400',\n  CONTEXT_TURN_NOT_FOUND: '954:404',\n  CONTEXT_TURN_INVALID_STATE: '955:409',\n  CONTEXT_BUSY: '956:409',\n\n  // Store (960-969)\n  STORE_FAILED: '960:500',\n  STORE_NOT_AVAILABLE: '961:503',\n\n  // Session (970-979)\n  SESSION_NOT_FOUND: '970:404',\n  SESSION_FAILED: '971:500',\n\n  // A2A (980-999)\n  A2A_NOT_CONFIGURED: '980:500',\n  A2A_HANDLE_FAILED: '981:500',\n  A2A_REMOTE_CALL_FAILED: '982:502',\n  A2A_AUTH_FAILED: '983:401',\n  A2A_LIST_MESSAGES_FAILED: '984:500',\n} as const satisfies ErrorInfo\n\n/**\n * AI 模块标准错误定义。通过错误码比较分支，用户文案由业务边界本地化。\n *\n * @example\n * ```ts\n * import { HaiAIError } from '@h-ai/ai'\n * import { err } from '@h-ai/core'\n * const result = err(HaiAIError.NOT_INITIALIZED, 'AI is not initialized')\n * if (!result.success) {\n *   const status = result.error.httpStatus\n *   const code = result.error.code\n * }\n * ```\n */\nexport const HaiAIError = core.error.buildHaiErrorsDef('ai', AIErrorInfo)\n\n// ─── 初始化选项 ───\n\n/**\n * AI 初始化运行时选项\n *\n * 用于传入运行时对象（如自定义 StoreProvider），\n * 这些对象无法通过 Zod 配置 Schema 传递。\n *\n * @example\n * ```ts\n * import { ai, type AIConfigInput, type AIInitOptions, type AIStoreProvider } from '@h-ai/ai'\n * async function start(config: AIConfigInput, storeProvider: AIStoreProvider) {\n *   const options: AIInitOptions = { storeProvider }\n *   const result = await ai.init(config, options)\n *   if (!result.success) throw new Error(result.error.message)\n * }\n * ```\n */\nexport interface AIInitOptions {\n  /**\n   * 自定义存储 Provider\n   *\n   * 提供后 AI 模块将使用此 Provider，而不采用自动选择的存储实现。\n   * 未提供时：reldb + vecdb 已初始化则使用持久化 DB Provider，否则使用进程内临时 Provider。\n   */\n  storeProvider?: AIStoreProvider\n}\n\n// ─── AIFunctions 接口 ───\n\n/**\n * AI 服务接口（通过 `ai` 对象访问）\n *\n * 所有 AI 功能的统一入口，需先调用 `init()` 初始化后才能使用 `llm`、`mcp` 操作。\n * `tools` 和 `stream` 为纯函数，无需初始化即可使用。\n *\n * @example\n * ```ts\n * import { ai, type AIConfigInput, type AIInitOptions } from '@h-ai/ai'\n * // 一次性脚本示例；服务应用在启动阶段 init，在停止接入请求后 close。\n * async function run(config: AIConfigInput, options: AIInitOptions) {\n *   const ready = await ai.init(config, options)\n *   if (!ready.success) throw new Error(ready.error.message)\n *   try {\n *     const answer = await ai.llm.ask('你好', { objectId: 'user-1' })\n *     if (!answer.success) throw new Error(answer.error.message)\n *     return answer.data\n *   }\n *   finally {\n *     await ai.close()\n *   }\n * }\n * ```\n */\nexport interface AIFunctions {\n  /**\n   * 初始化 AI 服务\n   *\n   * 使用 Zod Schema 校验配置，失败返回 `CONFIGURATION_ERROR`。\n   * 重复调用会先关闭旧实例再重新初始化。\n   *\n   * @param config - AI 配置（可选，默认使用空对象并应用 Schema 默认值）\n   * @param options - 运行时选项（可选，用于传入自定义 StoreProvider 等运行时对象）\n   * @returns 成功返回 `ok(undefined)`；配置校验失败返回 `err(HaiAIError.CONFIGURATION_ERROR)`\n   */\n  init: (config?: AIConfigInput, options?: AIInitOptions) => Promise<HaiResult<void>>\n  /**\n   * 关闭 AI 服务，释放内部状态\n   *\n   * 关闭后 `llm`、`mcp` 操作将返回 `NOT_INITIALIZED` 错误。\n   * 重复关闭不会报错。\n   */\n  close: () => Promise<void>\n  /** 当前脱敏后的配置快照（未初始化时为 `null`） */\n  readonly config: AIConfig | null\n  /** 是否已初始化（`init()` 成功后为 `true`，`close()` 后为 `false`） */\n  readonly isInitialized: boolean\n  /** LLM 操作（聊天、流式、模型列表），需要先调用 `init()` */\n  readonly llm: LLMOperations\n  /** MCP 操作（工具/资源/提示词注册与调用），需要先调用 `init()` */\n  readonly mcp: MCPOperations\n  /** 工具操作（定义工具与注册表），纯函数，无需初始化 */\n  readonly tools: ToolsOperations\n  /** 流处理操作（流处理器、SSE 编解码），纯函数，无需初始化 */\n  readonly stream: StreamOperations\n  /** Embedding 操作（向量嵌入），需要先调用 `init()` */\n  readonly embedding: EmbeddingOperations\n  /** 推理操作（ReAct / CoT / Plan-Execute），需要先调用 `init()` */\n  readonly reasoning: ReasoningOperations\n  /** 检索操作（向量检索），需要先调用 `init()` */\n  readonly retrieval: RetrievalOperations\n  /** RAG 操作（检索增强生成），需要先调用 `init()` */\n  readonly rag: RagOperations\n  /** Knowledge 操作（知识库管理与检索），需要先调用 `init()` 和 `knowledge.setup()` */\n  readonly knowledge: KnowledgeOperations\n  /** Memory 操作（记忆提取、存储、检索、注入），需要先调用 `init()` */\n  readonly memory: MemoryOperations\n  /** Persona 操作（AI 角色人格档案与系统提示词组合），需要先调用 `init()` */\n  readonly persona: PersonaOperations\n  /** Token 操作（Token 估算），需要先调用 `init()` */\n  readonly token: TokenOperations\n  /** Summary 操作（消息摘要生成），需要先调用 `init()` */\n  readonly summary: SummaryOperations\n  /** Compress 操作（上下文压缩），需要先调用 `init()` */\n  readonly compress: CompressOperations\n  /** Context 操作（有状态上下文管理器，编排 LLM + Memory + RAG + Reasoning），需要先调用 `init()` */\n  readonly context: ContextOperations\n  /** Rerank 操作（文档重排序），需要先调用 `init()` */\n  readonly rerank: RerankOperations\n  /** File 操作（文件内容解析），需要先调用 `init()` */\n  readonly file: FileOperations\n  /** A2A 操作（Agent-to-Agent 协议），需要先调用 `init()` 并配置 `a2a` */\n  readonly a2a: A2AOperations\n  /** Audio 操作（语音识别 / 语音合成），需要先调用 `init()` 并配置 `audio` */\n  readonly audio: AudioOperations\n  /** Image 操作（文生图），需要先调用 `init()` 并配置 `image` */\n  readonly image: ImageOperations\n}\n"]}

package/dist/client/index.d.ts

@@ -1,266 +1,98 @@
-import { ac as ChatCompletionRequest, ad as ChatCompletionResponse, aa as ChatCompletionChunk, aD as KnowledgeRetrieveResult, aq as KnowledgeAskResult, az as KnowledgeIngestResult, ar as KnowledgeDocumentInfo, aJ as MemoryEntry, be as StorePage, aK as MemoryEntryInput, aR as MemoryUpdateInput, bc as SessionInfo, ag as ChatRecord, aY as RagResult, b0 as ReasoningResult, O as A2AAgentCardConfig, _ as A2AMessageRecord, V as A2ACallResult } from '../ai-reasoning-types-CGUgkLF7.js';
-import { HaiResult } from '@h-ai/core';
-import '@a2a-js/sdk/server';
-import '@h-ai/datapipe';
-import 'zod';
-import 'openai';
+import { m as TranscriptionRequest, n as TranscriptionResult, p as TranscriptionStreamRequest, T as TranscriptionEvent, h as SynthesisRequest, i as SynthesisResult, j as SynthesisStreamRequest, S as SynthesisEvent } from '../ai-audio-types-4R5yUAVl.js';
+import '@h-ai/core';
 
 /**
- * @h-ai/ai — 前端 AI 客户端
+ * @h-ai/ai/client — 浏览器语音客户端
  *
- * 基于 @h-ai/api-client 的 AI 领域客户端。
- * 通过 `createAIClient()` 工厂函数创建，消除自建 HTTP 层，
- * 复用 api-client 提供的 Token 管理、超时、拦截器等基础能力。
- * @module ai-client
+ * 通过统一 WebSocket 连接 `@h-ai/serv` 的语音入口，向浏览器暴露与 Node 端一致的
+ * `ai.audio.*` 业务 API。WebSocket 建立、消息编解码等传输细节在此内部完成，
+ * 调用方不接触任何厂商原生事件。
+ * @module client/ai-audio-client
  */
 
 /**
- * AI 客户端所需的 API 调用能力
+ * getTicket 收到的当前 Audio 请求摘要
  *
- * 结构兼容 `@h-ai/api-client` 的 `api` 单例（鸭子类型）。
- * 传入 `api` 单例即可，无需额外适配。
- */
-interface AIApiAdapter {
-    /** POST 请求（返回 HaiResult） */
-    post: <T>(path: string, body?: unknown) => Promise<HaiResult<T>>;
-    /** 流式请求（返回 SSE data 行的 AsyncIterable） */
-    stream: (path: string, body?: unknown) => AsyncIterable<string>;
-}
-/**
- * AI 客户端配置
+ * 供应用签发与本次操作严格绑定的能力票据（如 `iam.ticket.issue({ grant })`），
+ * 使票据只能用于本次操作 / 模型 / 会话，降低票据被重放的风险。
  *
  * @example
  * ```ts
- * import { api } from '@h-ai/api-client'
- * import { createAIClient } from '@h-ai/ai/client'
- *
- * await api.init({ baseUrl: '/api', auth: { ... } })
- * const aiClient = createAIClient({ api })
+ * import type { AudioTicketRequest } from '@h-ai/ai/client'
+ * function grant(request: AudioTicketRequest) {
+ *   return { operation: request.operation, model: request.model } // 经已登录 HTTP 接口签发并在服务端原子消费。
+ * }
  * ```
  */
-interface AIClientConfig {
-    /**
-     * API 调用适配器
-     *
-     * 传入 `api` 单例（初始化后）。
-     * baseUrl、Token 管理、超时等通过 api-client 配置。
-     */
-    api: AIApiAdapter;
-}
-/** 流式响应进度（`onProgress` 回调参数） */
-interface StreamProgress {
-    /** 当前累积的文本内容 */
-    content: string;
-    /** 是否已完成 */
-    done: boolean;
-    /** 完成原因（仅 `done=true` 时有值，如 `'stop'`） */
-    finishReason?: string;
-}
-/** 流式响应选项 */
-interface StreamOptions {
-    /** 进度回调（每次收到 chunk 时触发） */
-    onProgress?: (progress: StreamProgress) => void;
+interface AudioTicketRequest {
+    /** 本次操作类型 */
+    operation: 'transcribe' | 'synthesize';
+    /** 本次使用的模型 ID（如有指定） */
+    model?: string;
 }
 /**
- * AI 客户端接口
- *
- * 提供浏览器端调用 AI API 的能力，HTTP 基础设施委托给 @h-ai/api-client。
- */
-interface AIClient {
-    /** 发送对话请求（非流式） */
-    chat: (request: ChatCompletionRequest) => Promise<ChatCompletionResponse>;
-    /** 发送流式对话请求，返回异步迭代器 */
-    chatStream: (request: ChatCompletionRequest, options?: StreamOptions) => AsyncIterable<ChatCompletionChunk>;
-    /** 便捷方法：发送纯文本消息并返回回复文本 */
-    sendMessage: (message: string, systemPrompt?: string) => Promise<string>;
-    /** 便捷方法：流式发送纯文本消息并返回完整回复 */
-    sendMessageStream: (message: string, options?: StreamOptions, systemPrompt?: string) => Promise<string>;
-    /** 简单问答（单轮，自动构造 messages） */
-    ask: (question: string, options?: {
-        systemPrompt?: string;
-        model?: string;
-    }) => Promise<string>;
-    /** 流式简单问答，返回异步文本流 */
-    askStream: (question: string, options?: {
-        systemPrompt?: string;
-        model?: string;
-    }) => AsyncIterable<string>;
-    /** 知识检索（向量 + 实体增强） */
-    knowledgeRetrieve: (query: string, options?: {
-        topK?: number;
-        collection?: string;
-    }) => Promise<KnowledgeRetrieveResult>;
-    /** 知识问答（RAG + 信源） */
-    knowledgeAsk: (query: string, options?: {
-        model?: string;
-        collection?: string;
-    }) => Promise<KnowledgeAskResult>;
-    /** 导入文档 */
-    knowledgeIngest: (input: {
-        documentId: string;
-        content: string;
-        title?: string;
-        collection?: string;
-        metadata?: Record<string, unknown>;
-    }) => Promise<KnowledgeIngestResult>;
-    /** 列出已导入文档 */
-    knowledgeListDocuments: (options?: {
-        collection?: string;
-        offset?: number;
-        limit?: number;
-    }) => Promise<KnowledgeDocumentInfo[]>;
-    /** 删除已导入文档 */
-    knowledgeRemoveDocument: (documentId: string, options?: {
-        collection?: string;
-    }) => Promise<void>;
-    /** 检索相关记忆 */
-    recallMemories: (query: string, options?: {
-        topK?: number;
-        types?: string[];
-        minImportance?: number;
-        objectId?: string;
-    }) => Promise<MemoryEntry[]>;
-    /** 列出记忆（分页） */
-    listMemories: (options?: {
-        types?: string[];
-        objectId?: string;
-        offset?: number;
-        limit?: number;
-    }) => Promise<StorePage<MemoryEntry>>;
-    /** 添加记忆 */
-    addMemory: (entry: MemoryEntryInput) => Promise<MemoryEntry>;
-    /** 更新记忆 */
-    updateMemory: (memoryId: string, updates: MemoryUpdateInput) => Promise<MemoryEntry>;
-    /** 删除记忆 */
-    removeMemory: (memoryId: string) => Promise<void>;
-    /** 列出会话 */
-    listSessions: (objectId: string) => Promise<SessionInfo[]>;
-    /** 重命名会话 */
-    renameSession: (sessionId: string, title: string) => Promise<void>;
-    /** 删除会话 */
-    removeSession: (sessionId: string) => Promise<void>;
-    /** 获取对话历史 */
-    chatHistory: (objectId: string, sessionId: string, options?: {
-        limit?: number;
-        order?: 'asc' | 'desc';
-    }) => Promise<ChatRecord[]>;
-    /** RAG 查询（检索 + 生成） */
-    ragQuery: (query: string, options?: {
-        collection?: string;
-        topK?: number;
-        model?: string;
-    }) => Promise<RagResult>;
-    /** RAG 流式查询，返回 SSE 数据行 */
-    ragQueryStream: (query: string, options?: {
-        collection?: string;
-        topK?: number;
-        model?: string;
-    }) => AsyncIterable<string>;
-    /** 推理（多步思考） */
-    reasoningRun: (query: string, options?: {
-        model?: string;
-        maxSteps?: number;
-    }) => Promise<ReasoningResult>;
-    /** 推理流式，返回 SSE 数据行 */
-    reasoningRunStream: (query: string, options?: {
-        model?: string;
-        maxSteps?: number;
-    }) => AsyncIterable<string>;
-    /** 估算文本的 Token 数 */
-    estimateTokens: (text: string) => Promise<{
-        tokens: number;
-    }>;
-}
-/**
- * 创建 AI 客户端
- *
- * 通过 @h-ai/api-client 的 ApiClient 实例调用后端 AI API。
- * HTTP 层（Token、超时、拦截器）全部复用 api-client，本模块仅负责：
- * - 非流式 / 流式 ChatCompletion 协议适配
- * - SSE 解析与 ChatCompletionChunk 类型化
- * - onProgress 进度回调
- *
- * @param config - 客户端配置
- * @returns AI 客户端实例
+ * 浏览器语音客户端配置
  *
  * @example
  * ```ts
- * import { api } from '@h-ai/api-client'
- * import { createAIClient } from '@h-ai/ai/client'
- *
- * await api.init({ baseUrl: '/api' })
- * const client = createAIClient({ api })
- * const reply = await client.sendMessage('你好')
+ * import { createAudioClient } from '@h-ai/ai/client'
+ * import type { AudioTicketRequest } from '@h-ai/ai/client'
+ * function connect(issueTicket: (request: AudioTicketRequest) => Promise<string>) {
+ *   return createAudioClient({ url: 'wss://example.com/api/v1/ai/audio', getTicket: issueTicket })
+ * }
  * ```
  */
-declare function createAIClient(config: AIClientConfig): AIClient;
+interface AudioClientConfig {
+    /** 语音 WebSocket 完整 URL（如 `wss://host/api/v1/ai/audio`） */
+    url: string;
+    /**
+     * 获取短期、一次性的 Audio WebSocket ticket
+     *
+     * ticket 应由已登录 HTTP 请求签发，并在服务端首次校验时原子消费。
+     * 收到当前请求摘要（operation / model），可签发与本次操作严格绑定的票据。
+     */
+    getTicket: (request: AudioTicketRequest) => string | Promise<string>;
+}
 /**
- * 从 fetch Response 中解析 SSE data 字段
+ * 浏览器语音操作接口
  *
- * 自动处理分片缓冲和 `[DONE]` 结束标记。
- *
- * @param response - fetch 响应对象
- * @yields SSE data 字符串（不含 `[DONE]`）
+ * 与 Node 端 `AudioOperations` 业务形态一致；出错时抛出异常（浏览器 Client 约定）。
  *
  * @example
  * ```ts
- * const resp = await fetch('/api/chat', { method: 'POST', body })
- * for await (const data of parseSSE(resp)) {
- *   const chunk = JSON.parse(data) // ChatCompletionChunk
+ * import type { AudioClientOperations } from '@h-ai/ai/client'
+ * async function speak(audio: AudioClientOperations) {
+ *   // 浏览器 AudioClient 普通方法也显式抛错，由应用交互边界处理。
+ *   const result = await audio.synthesize({ text: '你好', format: 'mp3' })
+ *   return result.data
  * }
  * ```
  */
-declare function parseSSE(response: Response): AsyncIterable<string>;
+interface AudioClientOperations {
+    /** 将完整音频识别为完整文本 */
+    transcribe: (request: TranscriptionRequest) => Promise<TranscriptionResult>;
+    /** 持续输入音频或增量返回识别文本（含语音起止事件） */
+    transcribeStream: (request: TranscriptionStreamRequest) => AsyncIterable<TranscriptionEvent>;
+    /** 将完整文本合成为完整音频 */
+    synthesize: (request: SynthesisRequest) => Promise<SynthesisResult>;
+    /** 持续输入文本段并按段输出结构化音频事件 */
+    synthesizeStream: (request: SynthesisStreamRequest) => AsyncIterable<SynthesisEvent>;
+}
 /**
- * 收集流式响应的完整文本内容
+ * 创建浏览器语音客户端
  *
- * 完整消费流并拼接所有 `delta.content` 片段。
- *
- * @param stream - 聊天响应块流
- * @returns 完整文本
+ * @param config - 语音客户端配置
+ * @returns 浏览器语音操作接口
  *
  * @example
  * ```ts
- * const client = createAIClient({ api })
- * const stream = client.chatStream({ messages })
- * const fullText = await collectStreamContent(stream)
+ * import { createAudioClient } from '@h-ai/ai/client'
+ * import type { AudioTicketRequest } from '@h-ai/ai/client'
+ * function connect(issueTicket: (request: AudioTicketRequest) => Promise<string>) {
+ *   return createAudioClient({ url: 'wss://example.com/api/v1/ai/audio', getTicket: issueTicket })
+ * }
  * ```
  */
-declare function collectStreamContent(stream: AsyncIterable<ChatCompletionChunk>): Promise<string>;
-
-/**
- * @h-ai/ai — 前端 A2A 客户端
- *
- * 浏览器端 A2A 操作客户端，通过 API 服务调用后端 A2A 能力。
- * @module ai-a2a-client
- */
-
-/**
- * A2A 客户端接口
- *
- * 提供浏览器端调用后端 A2A API 的能力。
- */
-interface A2AClientOperations {
-    /** 获取当前 Agent Card 配置 */
-    getAgentCard: () => Promise<A2AAgentCardConfig>;
-    /** 查询 A2A 消息记录 */
-    listMessages: (filter?: {
-        contextId?: string;
-        status?: string;
-        limit?: number;
-        offset?: number;
-    }) => Promise<StorePage<A2AMessageRecord>>;
-    /** 作为客户端调用远端 Agent */
-    callRemoteAgent: (remoteUrl: string, message: string, options?: {
-        timeout?: number;
-    }) => Promise<A2ACallResult>;
-}
-/**
- * 创建 A2A 客户端
- *
- * @param api - API 适配器（来自 @h-ai/api-client）
- * @returns A2A 客户端操作实例
- */
-declare function createA2AClient(api: AIApiAdapter): A2AClientOperations;
+declare function createAudioClient(config: AudioClientConfig): AudioClientOperations;
 
-export { type A2AClientOperations, type AIApiAdapter, type AIClient, type AIClientConfig, type StreamOptions, type StreamProgress, collectStreamContent, createA2AClient, createAIClient, parseSSE };
+export { type AudioClientConfig, type AudioClientOperations, type AudioTicketRequest, createAudioClient };

package/dist/client/index.js

@@ -1,3 +1,4 @@
-export { collectStreamContent, createA2AClient, createAIClient, parseSSE } from '../chunk-ABP7RKIP.js';
+export { createAudioClient } from '../chunk-GMQFIWND.js';
+import '../chunk-HYMP57AC.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -1,13 +1,20 @@
-export { O as A2AAgentCardConfig, P as A2AApiKeySecurity, Q as A2AAuthenticator, U as A2ACallOptions, V as A2ACallResult, W as A2ACallerIdentity, X as A2AClientCallRecord, A as A2AConfig, a as A2AConfigSchema, Y as A2AContextInfo, Z as A2AHandleResult, _ as A2AMessageRecord, $ as A2AOperations, a0 as A2ASecurityConfig, b as A2ASkillConfigSchema, a1 as A2ATaskFilter, c as AIConfig, d as AIConfigInput, e as AIConfigSchema, a2 as AILLMFunctionsDeps, a3 as AIRelStore, a4 as AIRelStoreOptions, a5 as AIStoreProvider, a6 as AIVectorStore, a7 as AskOptions, a8 as AssistantMessage, a9 as ChatCompletionChoice, aa as ChatCompletionChunk, ab as ChatCompletionDelta, ac as ChatCompletionRequest, ad as ChatCompletionResponse, ae as ChatHistoryOptions, af as ChatMessage, ag as ChatRecord, ah as Citation, C as CompressConfig, f as CompressConfigSchema, ai as DefineToolOptions, E as EmbeddingConfig, g as EmbeddingConfigSchema, aj as EntityDocumentRelation, ak as EntityDocumentResult, al as EntityListOptions, am as EntityQueryOptions, h as EntityType, i as EntityTypeSchema, F as FileConfig, j as FileConfigSchema, an as ImageContent, ao as InteractionScope, ap as KnowledgeAskOptions, aq as KnowledgeAskResult, K as KnowledgeConfig, k as KnowledgeConfigSchema, ar as KnowledgeDocumentInfo, as as KnowledgeDocumentListOptions, at as KnowledgeDocumentRemoveOptions, au as KnowledgeEntity, av as KnowledgeIngestBatchProgress, aw as KnowledgeIngestBatchResult, ax as KnowledgeIngestFileInput, ay as KnowledgeIngestInput, az as KnowledgeIngestResult, aA as KnowledgeOperations, aB as KnowledgeRetrieveItem, aC as KnowledgeRetrieveOptions, aD as KnowledgeRetrieveResult, aE as KnowledgeSetupOptions, aF as KnowledgeStore, L as LLMConfig, l as LLMConfigSchema, aG as LLMOperations, aH as LLMProvider, M as MCPConfig, m as MCPConfigSchema, n as MCPServerCapabilities, o as MCPServerCapabilitiesSchema, p as MCPServerConfig, q as MCPServerConfigSchema, aI as MemoryClearOptions, r as MemoryConfig, s as MemoryConfigSchema, aJ as MemoryEntry, aK as MemoryEntryInput, aL as MemoryExtractOptions, aM as MemoryInjectionOptions, aN as MemoryListOptions, aO as MemoryListPageOptions, aP as MemoryOperations, aQ as MemoryRecallOptions, t as MemoryType, u as MemoryTypeSchema, aR as MemoryUpdateInput, aS as MessageContent, aT as MessageRole, v as ModelEntry, w as ModelEntrySchema, x as ModelScenario, y as ModelScenarioSchema, aU as ObjectRef, aV as RagContextItem, aW as RagOperations, aX as RagOptions, aY as RagResult, aZ as RagStreamEvent, a_ as ReasoningOperations, a$ as ReasoningOptions, b0 as ReasoningResult, b1 as ReasoningStep, b2 as ReasoningStepType, b3 as ReasoningStrategy, b4 as ReasoningStreamEvent, R as ResolveRequiredModelEntryOptions, z as ResolvedModelConfig, B as RetrievalConfig, D as RetrievalConfigSchema, b5 as RetrievalOperations, b6 as RetrievalRequest, b7 as RetrievalResult, b8 as RetrievalResultItem, b9 as RetrievalSource, G as RetrievalSourceConfig, H as RetrievalSourceSchema, ba as SSEDecoder, bb as SSEEvent, bc as SessionInfo, bd as StoreFilter, be as StorePage, bf as StoreScope, bg as StreamOperations, bh as StreamProcessor, bi as StreamResult, S as SummaryConfig, I as SummaryConfigSchema, bj as SystemMessage, bk as TextContent, T as TokenConfig, J as TokenConfigSchema, bl as TokenUsage, bm as Tool, bn as ToolCall, bo as ToolDefinition, bp as ToolErrorType, bq as ToolMessage, br as ToolRegistryOperations, bs as ToolsOperations, bt as UserMessage, bu as WhereClause, bv as WhereOperator, bw as WhereValue, N as resolveModelEntry } from './ai-reasoning-types-CGUgkLF7.js';
-import { A as AIFunctions } from './ai-types-CRCjluXI.js';
-export { a as AIInitOptions, c as AIMCPFunctionsDeps, d as CompressOperations, e as CompressOptions, f as CompressResult, C as CompressionStrategy, b as CompressionStrategySchema, g as ContextChatOptions, h as ContextChatResult, i as ContextDeps, j as ContextManager, k as ContextManagerOptions, l as ContextOperations, m as ContextStreamEvent, E as EmbeddingItem, n as EmbeddingOperations, o as EmbeddingProvider, p as EmbeddingRequest, q as EmbeddingResponse, F as FileOperations, r as FileParseMethod, s as FileParseOptions, t as FileParseRequest, u as FileParseResult, H as HaiAIError, M as MCPContext, v as MCPOperations, w as MCPPrompt, x as MCPPromptArgument, y as MCPPromptContent, z as MCPPromptMessage, B as MCPProvider, D as MCPResource, G as MCPResourceContent, I as MCPToolDefinition, J as MCPToolHandler, K as McpServerOptions, O as OutputFormat, R as RerankDocument, L as RerankItem, N as RerankOperations, P as RerankRequest, Q as RerankResponse, S as SummaryOperations, T as SummaryOptions, U as SummaryResult, V as TokenOperations } from './ai-types-CRCjluXI.js';
-export { TaskStore as A2ATaskStore, AgentExecutor, ExecutionEventBus, RequestContext, ServerCallContext } from '@a2a-js/sdk/server';
+import { r as AIFunctions, bK as McpServerOptions } from './ai-audio-ws-protocol-nfhO0tOo.js';
+export { A as A2AAgentCardConfig, a as A2AApiKeySecurity, b as A2AAuthenticator, c as A2ACallOptions, d as A2ACallResult, e as A2ACallerIdentity, f as A2AConfig, g as A2AConfigSchema, h as A2AContextInfo, i as A2AHandleResult, j as A2AMessageRecord, k as A2AOperations, l as A2ASecurityConfig, m as A2ASkillConfigSchema, n as A2ATaskFilter, o as AIConfig, p as AIConfigInput, q as AIConfigSchema, s as AIInitOptions, t as AIRelStore, u as AIRelStoreCompareAndSwap, v as AIRelStoreOptions, w as AIStoreProvider, x as AIVectorBackend, y as AIVectorStore, z as AIVersionedRecord, B as AUDIO_WS_PATH, C as ApiType, D as ApiTypeSchema, E as AskOptions, F as AssistantMessage, G as AudioConfig, H as AudioConfigSchema, I as AudioFormatSchema, J as AudioModelEntry, K as AudioModelEntrySchema, L as AudioOperation, M as AudioOperationSchema, N as AudioOperationsSchema, O as AudioProviderName, P as AudioProviderSchema, Q as AudioWsClientMessage, R as AudioWsClientMessageSchema, S as AudioWsDoneMessage, T as AudioWsDoneMessageSchema, U as AudioWsEndMessage, V as AudioWsErrorMessage, W as AudioWsSegmentDoneMessage, X as AudioWsSegmentStartedMessage, Y as AudioWsServerMessage, Z as AudioWsSpeechMessage, _ as AudioWsStartMessage, $ as AudioWsStartMessageSchema, a0 as AudioWsTextMessage, a1 as AudioWsTextMessageSchema, a2 as AudioWsTranscriptMessage, a3 as ChatCompletionChoice, a4 as ChatCompletionChunk, a5 as ChatCompletionDelta, a6 as ChatCompletionRequest, a7 as ChatCompletionResponse, a8 as ChatHistoryOptions, a9 as ChatMessage, aa as ChatRecord, ab as Citation, ac as CommitTurnInput, ad as CompressConfig, ae as CompressConfigSchema, af as CompressOperations, ag as CompressOptions, ah as CompressResult, ai as CompressionStrategy, aj as CompressionStrategySchema, ak as ConsolidateOptions, al as ConsolidateResult, am as ContextChatOptions, an as ContextChatResult, ao as ContextManager, ap as ContextManagerOptions, aq as ContextOperations, ar as ContextResetOptions, as as ContextStreamEvent, at as ConversationTurn, au as ConversationTurnStatus, av as DefineToolOptions, aw as DeveloperMessage, ax as EmbeddingConfig, ay as EmbeddingConfigSchema, az as EmbeddingItem, aA as EmbeddingOperations, aB as EmbeddingRequest, aC as EmbeddingResponse, aD as EntityDocumentRelation, aE as EntityDocumentResult, aF as EntityListOptions, aG as EntityQueryOptions, aH as EntityType, aI as EntityTypeSchema, aJ as FileConfig, aK as FileConfigSchema, aL as FileOperations, aM as FileParseMethod, aN as FileParseOptions, aO as FileParseRequest, aP as FileParseResult, aQ as GenerateImageRequest, aR as GenerateImageResult, aS as GenerateObjectRequest, aT as GeneratedImage, aU as HaiAIError, aV as ImageConfig, aW as ImageConfigSchema, aX as ImageContent, aY as ImageModelEntry, aZ as ImageModelEntrySchema, a_ as ImageOperations, a$ as ImageProviderName, b0 as ImageProviderSchema, b1 as ImageSize, b2 as InteractionScope, b3 as KnowledgeAskOptions, b4 as KnowledgeAskResult, b5 as KnowledgeConfig, b6 as KnowledgeConfigSchema, b7 as KnowledgeDocumentInfo, b8 as KnowledgeDocumentListOptions, b9 as KnowledgeDocumentMetadata, ba as KnowledgeDocumentRemoveOptions, bb as KnowledgeDocumentRevision, bc as KnowledgeEntity, bd as KnowledgeIngestBatchProgress, be as KnowledgeIngestBatchResult, bf as KnowledgeIngestFileInput, bg as KnowledgeIngestInput, bh as KnowledgeIngestResult, bi as KnowledgeOperations, bj as KnowledgeRepairOptions, bk as KnowledgeRepairProgress, bl as KnowledgeRepairResult, bm as KnowledgeRetrieveItem, bn as KnowledgeRetrieveOptions, bo as KnowledgeRetrieveResult, bp as KnowledgeSetupOptions, bq as KnowledgeStore, br as LLMConfig, bs as LLMConfigSchema, bt as LLMOperations, bu as MCPConfig, bv as MCPConfigSchema, bw as MCPContext, bx as MCPOperations, by as MCPPrompt, bz as MCPPromptArgument, bA as MCPPromptContent, bB as MCPPromptMessage, bC as MCPResource, bD as MCPResourceContent, bE as MCPServerCapabilities, bF as MCPServerCapabilitiesSchema, bG as MCPServerConfig, bH as MCPServerConfigSchema, bI as MCPToolDefinition, bJ as MCPToolHandler, bL as MemoryAccessScope, bM as MemoryAdminOperations, bN as MemoryClearAllOptions, bO as MemoryClearOptions, bP as MemoryConfig, bQ as MemoryConfigSchema, bR as MemoryCoreOperations, bS as MemoryEntry, bT as MemoryEntryInput, bU as MemoryExtractOptions, bV as MemoryInjectionOptions, bW as MemoryListOptions, bX as MemoryListPageOptions, bY as MemoryOperations, bZ as MemoryRecallOptions, b_ as MemoryType, b$ as MemoryTypeSchema, c0 as MemoryUpdateInput, c1 as MessageContent, c2 as MessageRole, c3 as ModelEntry, c4 as ModelEntrySchema, c5 as ModelScenario, c6 as ModelScenarioSchema, c7 as ObjectRef, c8 as OptionalSecretSchema, c9 as OutputFormat, ca as PersonaOperations, cb as PersonaProfile, cc as PersonaProfileInput, cd as PersonaProfileUpdate, ce as PersonaScopeOptions, cf as RagContextItem, cg as RagOperations, ch as RagOptions, ci as RagResult, cj as RagStreamEvent, ck as ReasoningOperations, cl as ReasoningOptions, cm as ReasoningResult, cn as ReasoningStep, co as ReasoningStepType, cp as ReasoningStrategy, cq as ReasoningStreamEvent, cr as ReferenceImage, cs as RerankDocument, ct as RerankItem, cu as RerankOperations, cv as RerankRequest, cw as RerankResponse, cx as ResolveRequiredModelEntryOptions, cy as ResolvedAudioModel, cz as ResolvedImageModel, cA as ResolvedModelConfig, cB as RetrievalConfig, cC as RetrievalConfigSchema, cD as RetrievalOperations, cE as RetrievalRequest, cF as RetrievalResult, cG as RetrievalResultItem, cH as RetrievalSource, cI as RetrievalSourceConfig, cJ as RetrievalSourceSchema, cK as SSEDecoder, cL as SSEEvent, cM as ScopedMemoryBinding, cN as ScopedMemoryOperations, cO as SessionInfo, cP as StoreFilter, cQ as StorePage, cR as StoreScope, cS as StreamOperations, cT as StreamProcessor, cU as StreamResult, cV as SummaryConfig, cW as SummaryConfigSchema, cX as SummaryOperations, cY as SummaryOptions, cZ as SummaryResult, c_ as SystemMessage, c$ as TempModelConfig, d0 as TextContent, d1 as TokenConfig, d2 as TokenConfigSchema, d3 as TokenOperations, d4 as TokenUsage, d5 as Tool, d6 as ToolAuthorizationRequest, d7 as ToolAuthorizer, d8 as ToolCall, d9 as ToolDefinition, da as ToolErrorType, db as ToolExecutionContext, dc as ToolExecutionOptions, dd as ToolMessage, de as ToolRegistryOperations, df as ToolRegistryOptions, dg as ToolsOperations, dh as UserMessage, di as WhereClause, dj as WhereOperator, dk as WhereValue, dl as ensureAudioCredential, dm as resolveAudioModel, dn as resolveImageModel, dp as resolveModelApi, dq as resolveModelEntry, dr as serializePlayableAudio } from './ai-audio-ws-protocol-nfhO0tOo.js';
+export { A as AudioCapabilitiesRequest, a as AudioContent, b as AudioFormat, c as AudioInputStream, d as AudioModelCapabilities, e as AudioOperations, f as AudioReference, P as PlayableAudio, S as SynthesisEvent, g as SynthesisOptions, h as SynthesisRequest, i as SynthesisResult, j as SynthesisStreamRequest, k as SynthesisTextSegment, T as TranscriptionEvent, l as TranscriptionOptions, m as TranscriptionRequest, n as TranscriptionResult, o as TranscriptionSegment, p as TranscriptionStreamRequest, q as TranscriptionTimestampGranularity, r as TranscriptionWord } from './ai-audio-types-4R5yUAVl.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { AgentCapabilities, AgentCard, AgentProvider, AgentSkill, Artifact, DataPart, FilePart, FileWithBytes, FileWithUri, Message, MessageSendParams, Part, PushNotificationConfig, Task, TaskArtifactUpdateEvent, TaskIdParams, TaskQueryParams, TaskState, TaskStatus, TaskStatusUpdateEvent, TextPart } from '@a2a-js/sdk';
+export { AgentExecutor, ExecutionEventBus, RequestContext, ServerCallContext } from '@a2a-js/sdk/server';
+export { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+export { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import '@h-ai/core';
-import '@h-ai/datapipe';
 import 'zod';
 import 'openai';
 import 'node:buffer';
+import '@h-ai/datapipe';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod/v4/core';
 
 /**
  * @h-ai/ai — AI 服务主入口
@@ -22,19 +29,45 @@ import 'node:buffer';
  * @example
  * ```ts
  * import { ai } from '@h-ai/ai'
+ * import type { AIConfigInput, AIInitOptions } from '@h-ai/ai'
+ * async function run(config: AIConfigInput, options: AIInitOptions) {
+ *   // 默认 Store 所需 reldb/vecdb 已由应用初始化；显式测试 Store 通过 options 注入。
+ *   const initialized = await ai.init(config, options)
+ *   if (!initialized.success) return initialized
+ *   try {
+ *     const result = await ai.llm.chat({ messages: [{ role: 'user', content: '你好' }] })
+ *     if (!result.success) return result
+ *     return result.data.choices[0]?.message.content
+ *   }
+ *   finally { await ai.close() }
+ * }
+ * ```
+ */
+declare const ai: AIFunctions;
+
+/**
+ * @h-ai/ai — MCP Server 创建与传输层
  *
- * // 初始化
- * await ai.init({ llm: { model: 'gpt-4o-mini', apiKey: process.env.HAI_AI_LLM_API_KEY } })
+ * 基于 `@modelcontextprotocol/sdk` 封装，提供便捷的 MCP 服务器创建。
+ * @module ai-mcp-server
+ */
+
+/**
+ * 创建 MCP 服务器
  *
- * // LLM 调用
- * const result = await ai.llm.chat({
- *   messages: [{ role: 'user', content: '你好' }],
- * })
+ * @param options - 服务器选项（名称、版本）
+ * @returns McpServer 实例
  *
- * // 关闭
- * ai.close()
+ * @example
+ * ```ts
+ * import { createMcpServer, StdioServerTransport } from '@h-ai/ai'
+ *
+ * const server = createMcpServer({ name: 'my-server', version: '1.0.0' })
+ * // 注册工具 / 资源 ...
+ * const transport = new StdioServerTransport()
+ * await server.connect(transport)
  * ```
  */
-declare const ai: AIFunctions;
+declare function createMcpServer(options: McpServerOptions): McpServer;
 
-export { AIFunctions, ai };
+export { AIFunctions, McpServerOptions, ai, createMcpServer };