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

package/README.md

@@ -1,1886 +1,670 @@
 # @h-ai/ai
 
-AI 能力模块，提供统一的 `ai` 对象访问大模型、MCP 服务和工具调用功能。
-
-## 功能特性
-
-| 子系统     | 说明                                                                | 依赖子系统                                        |
-| ---------- | ------------------------------------------------------------------- | ------------------------------------------------- |
-| Tools      | 工具定义（Zod → JSON Schema）、注册表管理、批量执行                 | —（纯函数）                                       |
-| Stream     | 流式块处理、SSE 编解码、流收集                                      | —（纯函数）                                       |
-| MCP Server | MCP HTTP 服务器、多传输层支持                                       | —（独立创建）                                     |
-| Client     | 前端轻量客户端（流式响应、SSE 解析、记忆/会话查询）                 | —（独立创建，依赖 api-client）                    |
-| LLM        | 大模型调用（非流式 / 流式）、简易问答、对话历史                     | LLM Provider                                      |
-| Token      | Token 估算（文本 / 消息列表）                                       | LLM                                               |
-| MCP        | 工具注册与调用、资源读取、提示词管理                                | LLM                                               |
-| Embedding  | 文本向量化、单条 / 批量嵌入                                         | LLM Provider                                      |
-| Summary    | 消息摘要生成（支持增量摘要）                                        | LLM                                               |
-| Rerank     | 重排序（查询-文档相关性排序）                                       | LLM                                               |
-| File       | 文件解析（PDF / DOCX / HTML / OCR）                                 | LLM（OCR 需 Vision 模型）                         |
-| Compress   | 上下文压缩（sliding-window / summary / hybrid）                     | LLM + Summary                                     |
-| Memory     | 对话记忆提取、存储、检索、注入（支持 objectId 隔离）                | LLM + Embedding + Store                           |
-| Reasoning  | 推理引擎（CoT / ReAct / Plan-Execute）                              | LLM + Tools                                       |
-| Retrieval  | 多来源向量检索、分数过滤                                            | Embedding + Store                                 |
-| RAG        | 检索增强问答（Retrieval + LLM）                                     | LLM + Retrieval                                   |
-| Knowledge  | 知识库管理（入库、检索、问答、实体提取）                            | LLM + Embedding + VecDB + RelDB + Datapipe        |
-| Context    | 有状态上下文管理器（压缩 + LLM/Memory/RAG/Reasoning 编排 + 持久化） | LLM + Memory + Compress + RAG + Reasoning + Store |
-| A2A        | Agent-to-Agent 协议（代理间通信与任务委派）                         | LLM + A2A 配置（延迟初始化）                      |
-| Store      | 统一存储抽象（对话记录、会话、检索源、记忆、上下文持久化）          | AIStoreProvider（默认实现基于 RelDB + VecDB）     |
-
-## 安装
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
 
-```bash
-pnpm add @h-ai/ai
-```
+[框架首页](../../README.md) · 相关模块：[@h-ai/api-contract](../api-contract/README.md) · [@h-ai/core](../core/README.md) · [@h-ai/datapipe](../datapipe/README.md) · [@h-ai/reldb](../reldb/README.md) · [@h-ai/vecdb](../vecdb/README.md)
+
+## 简介
+
+AI 能力模块，提供统一的 `ai` 服务对象，覆盖 LLM 对话、文生图、工具调用、MCP、Embedding、记忆、检索/RAG、知识库、上下文管理、文件解析、Rerank、语音（ASR/TTS）与 A2A。Node.js 侧通过 `ai.init()` 初始化，浏览器侧通过 API/client 代理访问。
 
-## 依赖
+## 核心功能清单
+
+- `ai.tools`：工具定义、注册表、批量执行；无需初始化。
+- `ai.stream`：ChatCompletion 流式 chunk 处理；无需初始化。
+- `ai.llm`：非流式/流式对话、模型列表、历史记录。
+- `ai.mcp` / `createMcpServer`：内置 MCP 注册表与独立 MCP Server。
+- `ai.embedding`：单条/批量文本向量化。
+- `ai.memory`：记忆提取、存储、召回、注入。
+- `ai.persona`：AI 角色人格档案（系统提示词 + 特征）与系统提示词组合。
+- `ai.retrieval` / `ai.rag`：多源向量检索与检索增强问答。
+- `ai.knowledge`：文档入库、实体增强检索、知识问答。
+- `ai.context`：LLM + Memory + RAG + 压缩的一体化会话管理。
+- `ai.file` / `ai.rerank`：文件解析/OCR 与文本重排序。
+- `ai.audio`：语音识别（ASR）与语音合成（TTS），支持完整与流式调用，覆盖 OpenAI / MiMo / Qwen / 豆包平台。
+- `ai.image`：文生图，覆盖 OpenAI GPT Image、Google Gemini Image / Nano Banana、Qwen-Image 2.0/3.0、Seedream 4.x/5.x 与 Pollinations 免费额度模型。
+- `ai.a2a`：Agent-to-Agent 请求处理与远端调用。
+- `@h-ai/ai/client`：独立浏览器 Audio WebSocket 客户端。
+
+`@h-ai/ai/client` 仅提供 `createAudioClient({ url, getTicket })` 与 Audio 客户端类型。HTTP 使用 `@h-ai/api-client` 的 typed 领域方法；默认聊天补全非流式，流与 A2A 使用应用自行绑定的 contract。旧字符串路径客户端和重复 SSE helper 已删除，浏览器不导出 Node 单例 `ai`。
+
+```ts
+import { apiClient } from '@h-ai/api-client'
 
-- `@h-ai/datapipe` — 数据管道（知识库文档切分，内部使用）
+const ready = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1' })
+if (!ready.success)
+  throw new Error(ready.error.message)
+try {
+  const response = await apiClient.ai.chats.createCompletion({ messages: [{ role: 'user', content: '你好' }] })
+  if (!response.success)
+    throw new Error(response.error.message)
+  const reply = response.data.choices[0]?.message.content
+}
+finally {
+  await apiClient.close()
+}
+```
 
-存储层通过 `AIStoreProvider` 抽象，**不再硬性依赖** reldb / vecdb：
+- `AIStoreProvider`：统一存储抽象；生产要求 `stateScope: 'shared'`，内置实现须先初始化 PostgreSQL/MySQL 与网络 vecdb。开发/显式测试无数据库时使用临时 Store。
 
-- **默认 DB Provider**（未传入自定义 Provider 时自动使用）：需 `@h-ai/reldb` + `@h-ai/vecdb`，且在 `ai.init()` 前完成初始化
-- **自定义 Provider**：实现 `AIStoreProvider` 接口后通过 `ai.init(config, { storeProvider })` 注入，无需 reldb / vecdb
+更完整的方法清单、错误码与长示例见 [REFERENCE.md](./REFERENCE.md)。
 
-> `ai.tools` 和 `ai.stream` 为纯函数子系统，无需 init 即可使用。
+## 使用入门
 
-## 快速开始
+### 快速开始
 
-### 方式一：默认 DB Provider（reldb + vecdb）
+#### 开发 LLM-only（零数据库依赖）
 
 ```ts
 import { ai } from '@h-ai/ai'
-import { reldb } from '@h-ai/reldb'
-import { vecdb } from '@h-ai/vecdb'
-
-// 1. 初始化存储依赖
-await reldb.init({ type: 'sqlite', database: './ai.db' })
-await vecdb.init({ type: 'lancedb', path: './ai-vec.db' })
 
-// 2. 初始化 AI 模块（自动使用已初始化的 reldb + vecdb 单例）
-await ai.init({
+const init = await ai.init({
   llm: {
     model: 'gpt-4o-mini',
-    apiKey: process.env.HAI_AI_LLM_API_KEY,
+    apiKey: process.env.HAI_AI_LLM_APIKEY,
   },
 })
+if (!init.success)
+  return init
 
-// 3. 对话
 const result = await ai.llm.chat({
-  messages: [
-    { role: 'system', content: '你是一个有帮助的助手' },
-    { role: 'user', content: '你好！' },
-  ],
+  messages: [{ role: 'user', content: '你好！' }],
 })
-if (result.success) {
-  const reply = result.data.choices[0].message.content
-}
 
-// 4. 关闭
-ai.close()
+await ai.close()
 ```
 
-### 方式二：自定义 StoreProvider
+开发/显式测试未初始化 reldb/vecdb 时，AI 使用进程内临时 Store；关闭、退出或切换实例后不保留。`NODE_ENV` 或 `HAI_CORE_ENV` 为 production 时，临时 Store、SQLite 或本地向量后端会使初始化失败。生产必须先初始化共享 RelDB 与网络 vecdb，或传入满足同等原子契约的共享 Provider。
+
+#### 持久化 DB Provider（reldb + vecdb）
 
 ```ts
-import type { AIStoreProvider } from '@h-ai/ai'
 import { ai } from '@h-ai/ai'
+import { reldb } from '@h-ai/reldb'
+import { vecdb } from '@h-ai/vecdb'
 
-// 实现自定义 Provider（对接 SaaS API、其他数据库等）
-const myProvider: AIStoreProvider = { /* ... */ }
-
-await ai.init(
-  { llm: { model: 'gpt-4o-mini', apiKey: process.env.HAI_AI_LLM_API_KEY } },
-  { storeProvider: myProvider }, // 无需 reldb / vecdb
-)
-
-// 使用方式与默认 Provider 完全一致
-const result = await ai.llm.chat({ messages: [{ role: 'user', content: '你好' }] })
-
-ai.close()
+// 开发/测试使用本地后端；生产改为共享 PostgreSQL/MySQL 与网络 vecdb。
+const failures: unknown[] = []
+try {
+  const database = await reldb.init({ type: 'sqlite', database: './ai.db' })
+  if (!database.success)
+    throw new Error(database.error.message)
+  const vectors = await vecdb.init({ type: 'lancedb', path: './ai-vec.db' })
+  if (!vectors.success)
+    throw new Error(vectors.error.message)
+  const initialized = await ai.init({
+    llm: { model: 'gpt-4o-mini', apiKey: process.env.HAI_AI_LLM_APIKEY },
+  })
+  if (!initialized.success)
+    throw new Error(initialized.error.message)
+  const result = await ai.llm.chat({ messages: [{ role: 'user', content: 'Hello!' }] })
+  if (!result.success)
+    throw new Error(result.error.message)
+  const reply = result.data.choices[0]?.message.content ?? ''
+}
+catch (error) {
+  failures.push(error)
+}
+finally {
+  await ai.close()
+  for (const service of [vecdb, reldb]) {
+    const closed = await service.close()
+    if (!closed.success)
+      failures.push(new Error(closed.error.message))
+  }
+}
+if (failures.length)
+  throw new AggregateError(failures, 'AI operation or cleanup failed')
 ```
 
----
-
-## 初始化与配置
+MySQL 首次初始化允许多个节点并发建索引：仅接受 mysql2 明确的 ER_DUP_KEYNAME/1061，并重新核对列及顺序、非唯一完整列、升序可见 BTREE 和无表达式；已有同名错误结构仍失败。账户需要建表和 INDEX 权限，元数据读取、权限或其他 DDL 错误使 ai.init 返回 CONFIGURATION_ERROR。返回前等待全部已启动 DDL 结束；MySQL DDL 不回滚，失败保留已创建结构，修复权限/结构后再重试。逐步检查初始化结果，失败不接收业务请求，并逆序关闭 AI、vecdb、reldb。
 
-### 完整配置
-
-```ts
-await ai.init({
-  // LLM 配置
-  llm: {
-    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: 'embed', model: 'text-embedding-3-small', baseUrl: 'https://...' },
-    ],
-    scenarios: {
-      chat: 'fast',
-      reasoning: 'strong',
-    },
-  },
-
-  // Embedding 配置
-  embedding: {
-    dimensions: 1536,
-    batchSize: 100,
-  },
-
-  // Knowledge 配置
-  knowledge: {
-    collection: 'hai_ai_knowledge',
-    dimension: 1536,
-    enableEntityExtraction: true,
-    cleanOptions: {
-      removeHtml: true,
-      normalizeWhitespace: true,
-    },
-    chunkOptions: {
-      mode: 'markdown', // sentence | paragraph | markdown | page | custom
-      maxSize: 1500,
-      overlap: 200,
-    },
-    entityBoostWeight: 0.15, // 实体命中加权系数 [0, 1]
-  },
-
-  // Memory 配置
-  memory: {
-    maxEntries: 1000,
-    embeddingEnabled: true, // 启用向量检索（关闭则仅关键词匹配）
-    recencyDecay: 0.95, // 时间衰减系数
-    defaultTopK: 10,
-  },
-
-  // Token 配置
-  token: {
-    tokenRatio: 0.25, // Token 估算系数（4 字符 ≈ 1 token）
-  },
-
-  // Summary 配置
-  summary: {
-    systemPrompt: '...', // 可选，覆盖内置摘要提示词
-  },
-
-  // Compress 配置
-  compress: {
-    defaultStrategy: 'hybrid', // summary | sliding-window | hybrid
-    defaultMaxTokens: 0, // 0 = 模型 maxTokens × 80%
-    preserveLastN: 4, // 保留最近 N 条不压缩
-  },
-
-  // MCP 配置
-  mcp: {
-    server: {
-      name: 'my-app',
-      version: '1.0.0',
-    },
-  },
-})
-```
-
-### 配合 core 配置文件使用
+#### 自定义 StoreProvider
 
 ```ts
+import type { AIStoreProvider } from '@h-ai/ai'
 import { ai } from '@h-ai/ai'
-import { core } from '@h-ai/core'
 
-await core.init({ configDir: './config' })
-await ai.init(core.config.get('ai'))
-// ...
-ai.close()
-await core.close()
-```
+const storeProvider: AIStoreProvider = createMyStoreProvider()
 
-### 初始化状态检测
+await ai.init(
+  { llm: { model: 'gpt-4o-mini', apiKey: process.env.HAI_AI_LLM_APIKEY } },
+  { storeProvider },
+)
 
-```ts
-ai.isInitialized // boolean
-ai.config // 当前配置对象，未初始化时为 null
+await ai.close()
 ```
 
----
-
-## LLM 对话 — `ai.llm`
-
-### 非流式对话
-
-```ts
-const result = await ai.llm.chat({
-  messages: [
-    { role: 'system', content: '你是一个翻译助手' },
-    { role: 'user', content: '将以下内容翻译为英文：你好世界' },
-  ],
-  temperature: 0.3,
-  max_tokens: 1000,
-})
+### API 契约
 
-if (result.success) {
-  const response = result.data
-  const content = response.choices[0].message.content
-  const usage = response.usage // { prompt_tokens, completion_tokens, total_tokens }
-}
-```
+- 对外只通过 `ai` 服务对象和少量独立工厂（如 `createMcpServer`）访问。
+- 生命周期为 `await ai.init(config, options?)` / `await ai.close()`；关闭会等待自定义 `AIStoreProvider.close()`。
+- 领域方法返回 `HaiResult<T>` 或 `Promise<HaiResult<T>>`；业务失败通过 `result.success === false` 和 `result.error.code` 表达。流式 `AsyncIterable`、客户端传输和第三方回调在建立或迭代期间可能抛异常。
+- `ai.tools` 与 `ai.stream` 是纯函数子系统，无需初始化即可使用。
+- 开发/测试缺少 reldb/vecdb 时使用临时 Store；两者均已初始化时自动使用 DB Provider。生产校验真实数据库与向量后端共享能力，自定义 Provider 必须如实声明 `stateScope`。
 
-### 指定模型
+公共扩展通过 AIStoreProvider 注入 Store；内置 LLM Provider/工厂依赖与 Context 内部依赖不属于公开 API。模型接入使用配置，历史查询、AskOptions 和 ChatRecord 保持公开。
 
-```ts
-// 使用 init 时注册的模型 ID 或直接传模型名
-const result = await ai.llm.chat({
-  model: 'gpt-4o',
-  messages: [{ role: 'user', content: '复杂推理问题' }],
-})
-```
+### API 概览
 
-### 流式对话
+#### LLM
 
 ```ts
-const messages = [{ role: 'user' as const, content: '写一首关于编程的诗' }]
-
+const result = await ai.llm.chat({ messages })
 for await (const chunk of ai.llm.chatStream({ messages })) {
   const delta = chunk.choices[0]?.delta?.content
   if (delta) {
-    process.stdout.write(delta) // 逐字输出
+    process.stdout.write(delta)
   }
 }
-```
 
-### 多模态输入（图片）
+// 请求取消：传入 AbortSignal，主持人打断/用户切换时 abort() 立即停止上游生成与计费
+const controller = new AbortController()
+const cancellable = ai.llm.chat({ messages, signal: controller.signal })
+// controller.abort()
 
-```ts
-const result = await ai.llm.chat({
-  model: 'gpt-4o',
-  messages: [{
-    role: 'user',
-    content: [
-      { type: 'text', text: '描述这张图片' },
-      { type: 'image_url', image_url: { url: 'https://example.com/photo.jpg', detail: 'high' } },
-    ],
-  }],
+// 多协议：模型的 api 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
+// - chat（默认）：OpenAI Chat Completions（兼容绝大多数厂商）
+// - responses：OpenAI Responses API（/v1/responses）
+// - anthropic：Anthropic Messages API（Claude 原生协议，环境变量 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL）
+const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 api: anthropic
+
+// 临时模型：单次请求绕过配置注册模型，直接指定端点与凭据（chat/chatStream/ask/askStream 均支持）
+// 临时客户端按 TTL 缓存（llm.tempModelCacheTtl，默认 10 分钟），与常驻模型客户端隔离
+const temp = await ai.llm.chat({
+  messages,
+  tempModel: { model: 'claude-3-5-sonnet', api: 'anthropic', apiKey: 'sk-temp' },
 })
 ```
 
-### 获取可用模型列表
-
-```ts
-const models = await ai.llm.listModels()
-if (models.success) {
-  // models.data: string[]
-}
-```
+SSE 文本解码遵循 [WHATWG 事件流规则](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation)：LF/CRLF/CR 跨片、多行 data、仅去冒号后一个空格、继承有效 id/retry；空或缺省 event 按 message，EOF 不补空行派发残余事件。encodeSSE 规范化 data 换行，并对 id/event 换行、id 的 NUL 或无效 retry 显式抛错。Anthropic/MiMo 共用内部 UTF-8 流读取；消费方退出、取消、协议结束和失败均取消正文并释放 reader，不自动重连或重放业务。Anthropic timeout 覆盖正文，MiMo 保留每个 HTTP 请求的独立 timeout。
 
-### 简易问答
+#### 工具调用
 
 ```ts
-// 非流式（返回纯文本回复）
-const result = await ai.llm.ask('什么是 TypeScript？')
-if (result.success) {
-  console.warn(result.data) // string
-}
+import { z } from 'zod'
 
-// 流式
-for await (const text of ai.llm.askStream('讲个笑话')) {
-  process.stdout.write(text)
-}
-```
+const registry = ai.tools.createRegistry({
+  // 统一授权在 Zod 校验后、handler 前执行；false/异常均 fail-closed
+  authorize: ({ toolName, context }) => canExecuteTool(context.objectId, toolName),
+})
+const registered = registry.register(ai.tools.define({
+  name: 'get_weather',
+  description: '获取天气',
+  parameters: z.object({ city: z.string() }),
+  // handler 第二参为执行上下文：可响应取消（打断/超时）、感知截止时间与交互主体
+  handler: async ({ city }, { signal }) => {
+    const res = await fetch(`https://api.example.com/weather?city=${city}`, { signal })
+    return res.json()
+  },
+  timeoutMs: 10_000, // 本工具默认超时（可被 execute 的 deadline / timeoutMs 覆盖）
+}))
+if (!registered.success)
+  return registered
 
-### 对话历史
+// 执行时可传入取消信号 / 超时 / 作用域；取消或超时返回 TOOL_TIMEOUT，且不再等待未响应的 handler
+const result = await registry.execute(toolCall, { signal: controller.signal, objectId: 'user-001', timeoutMs: 30_000 })
 
-```ts
-// 获取某对象的聊天记录（需在 chat 请求中传 objectId + enablePersist）
-const history = await ai.llm.getHistory('user-001', { sessionId: 'sess-001', limit: 50 })
-if (history.success) {
-  // history.data: ChatRecord[]
-}
+// 批量调用默认串行，避免副作用工具并发启动；纯读取且确认安全时才显式并行
+const batch = await registry.executeAll(toolCalls)
 
-// 列出某对象的所有会话
-const sessions = await ai.llm.listSessions('user-001')
-if (sessions.success) {
-  // sessions.data: SessionInfo[]
-}
+const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 ```
 
----
+#### A2A 协议边界
 
-## 工具调用 — `ai.tools`
+`ai.a2a.getAgentCard()` 返回完整 A2A 0.3 Agent Card，含 `protocolVersion`、MIME 和 streaming 能力；Kit 默认发现路径为 `/.well-known/agent-card.json`。`handleRequest()` 始终返回 JSON-RPC/SSE 处理结果，未初始化返回 JSON-RPC 错误。可信 HTTP 认证上下文的 `agentId` 映射为 executor 的 `context.user.userName`。当前支持 JSON-RPC/SSE，不声明 push notifications、gRPC 或 REST 支持；业务资源授权仍由应用负责。
 
-> `ai.tools` 为纯函数操作，**不需要初始化**即可使用。
+A2A 的 journal、context 归属与消息表在 `ai.init()` 阶段初始化。任务按可信 `agentId` 隔离（含获取、取消和续接）；匿名请求共享匿名主体，生产应在可信传输层认证。`listMessages` 是服务端管理接口，支持 `callerId`、`contextId`、`since`，不能向未授权客户端暴露。
 
-### 定义工具
+Task 与事件使用同一共享 journal，不再装配独立的旧 TaskStore。push notification 配置和 authenticated extended card RPC 返回 SDK 标准“不支持/未配置”错误，不执行任务；executor 相关类型保留公开导出，内部 handler/Store 装配类型不属于公共契约。
 
-```ts
-import { ai } from '@h-ai/ai'
-import { z } from 'zod'
+入站消息必须持久化后才进入 executor，并在等待后重新校验共享执行代际与期限；agent 消息在同一有界事件队列内等待日志成功后才提交 journal。日志失败会产生 failed/interrupted Task，不会发布虚假的成功结果；同一消息重试不重新执行。日志与 journal 不是跨记录事务，已有日志不等于成功交付，最终以 Task 的 `requiresEffectReconciliation` 标记核对可能已发生的业务效果。消息查询失败返回 `A2A_LIST_MESSAGES_FAILED`（984），不暴露原始 SQL 或连接详情。
 
-const weatherTool = ai.tools.define({
-  name: 'get_weather',
-  description: '获取指定城市的天气信息',
-  parameters: z.object({
-    city: z.string().describe('城市名称'),
-    unit: z.enum(['celsius', 'fahrenheit']).optional().describe('温度单位'),
-  }),
-  handler: async ({ city, unit }) => {
-    // 调用天气 API
-    return { temperature: 20, city, unit: unit ?? 'celsius' }
-  },
-})
-```
+Task 与事件一次 CAS 持久化，任意节点可订阅；相同 message ID/内容重试仅返回同一轮结果，改变内容或重复旧轮消息失败。跨节点取消由真实执行 owner 调用 executor.cancelTask，取消未确认期间同一 Task 不接受新消息，避免迟到取消作用于新执行；input-required 可在节点重启后续接。DB 租约过期、绝对期限到达或执行器只返回 working 时标记 failed/interrupted，并设置 `metadata.haiExecution.requiresEffectReconciliation=true`；旧节点恢复不能写入，不自动重放未知外部效果。`a2a.execution` 默认 `leaseMs: 30000`、`pollIntervalMs: 250`、`maxExecutionMs: 300000`。单消息 1 MiB、journal 8 MiB、单轮 2048 事件、Task 256 回执、32 个 reference tasks，超限明确失败。外部副作用须使用稳定业务幂等键并核对未知结果；详细部署/验证边界见[共享状态能力表](../../.agents/instructions/distributed-state.md)。
 
-### 注册表管理
+#### MCP Server
+
+`ai.mcp` 是进程内注册表，独立 `createMcpServer` 使用 SDK transport，两者不会自动互相注册。`ai.mcp` 在注册时编译工具 JSON Schema，调用时校验输入；资源输出必须恰好含 `text` / `blob` 之一；提示词参数与 SDK 消息输出均校验，支持图片和音频内容。HTTP 示例只展示 transport 连接，应用仍须挂载请求处理与认证，并在退出时关闭 server。
 
 ```ts
-const registry = ai.tools.createRegistry()
+import { createMcpServer, StreamableHTTPServerTransport } from '@h-ai/ai'
+import { z } from 'zod'
 
-// 注册单个 / 批量注册
-registry.register(weatherTool)
-registry.registerMany([tool1, tool2, tool3])
+const server = createMcpServer({ name: 'my-server', version: '1.0.0' })
+server.registerTool('search', {
+  description: '搜索',
+  inputSchema: { query: z.string() },
+}, async ({ query }) => ({
+  content: [{ type: 'text', text: `Results for ${query}` }],
+}))
+await server.connect(new StreamableHTTPServerTransport({ sessionIdGenerator: () => globalThis.crypto.randomUUID() }))
+```
 
-// 查询
-registry.has('get_weather') // true
-registry.get('get_weather') // Tool 对象
-registry.getNames() // ['get_weather', ...]
-registry.size // 注册数量
+#### Memory / RAG / Knowledge
 
-// 获取 OpenAI 工具定义（传递给 LLM）
-const definitions = registry.getDefinitions() // ToolDefinition[]
+Knowledge 每次导入生成唯一 `revision` 和分块 ID，先完整准备分块、向量及实体，再持久化暂存清单、写入向量，最后通过共享 Store CAS 一次发布正文、实体和元数据。相同文档并发重建只允许一个写入者；失败时保留完整旧版，缩短文档不会留下可见旧尾块。检索只接受当前发布版本，并在发布穿插时重试，持续冲突返回错误供调用方重试。向量候选可能按需扩大，清理积压会增加查询成本。
 
-// 执行工具调用
-const toolMessage = await registry.execute(toolCall) // HaiResult<ToolMessage>
+`ingest` 成功结果包含 `revision` 与 `cleanupPending`：后者为 true 表示新版本已经发布，但旧向量删除仍待补偿。调用 `repair({ collection, offset, limit })` 分页重试；`setup` 自动检查前 100 份清单，生产环境应定期扫描全部页。暂存期限为存储端时钟的 5 分钟，超时写入者不能发布；故障暂存的永久墓碑用于反复删除迟到的外部写入，不能随日志保留期删除。SQL 与 vecdb 不组成跨库事务，恢复依赖持久清单和持续补偿。`removeDocument` / `deleteCollection` 先撤销可见性，清理失败返回错误；集合删除保留空向量集合及代际墓碑以支持补偿，重新 setup 不显示上一代内容。
 
-// 批量执行（支持并行）
-const toolMessages = await registry.executeAll(toolCalls, { parallel: true })
+默认 DB Store 传播集合查询/创建及向量写入失败。LanceDB 使用持久主键原子 merge；Qdrant 写入/删除等待应用完成，计数使用精确计数。多节点必须共享关系存储和服务端向量后端；自定义 `KnowledgeStore` 须实现相同的版本发布与补偿契约。
 
-// 取消注册 / 清空
-registry.unregister('get_weather')
-registry.clear()
-```
+使用 LanceDB 时，集合维度与 metric 随 Arrow schema 持久化；连接 metric 只影响新集合。重启后复用同一持久目录，embedding 维数改变时重建匹配集合；多个节点各自的本地路径不会自动共享，分布式 Knowledge 推荐服务端向量后端。
 
-### 工具集成 LLM 调用
+Knowledge 的 `retrieve/ask` 及默认 DB Store 会将 `filter` 传给向量 Provider，过滤校验/查询失败会向上传播；Knowledge 返回 `KNOWLEDGE_RETRIEVE_FAILED`（ask 包装为 `RAG_FAILED`），不会伪装成空结果。LanceDB 的过滤只支持顶层键的 string/有限 number/boolean/null AND 精确匹配，例如 `{ tenant: 'acme', active: true }`；null 不匹配缺失字段，不支持对象/数组/undefined。条件在向量 topK 前执行；其它后端的 null/复杂值语义须单独核对。LanceDB 元数据改用原生 JSON 字段，仍可保存嵌套 JSON；旧字符串元数据集合须重建后才能写入或过滤。
 
 ```ts
-const result = await ai.llm.chat({
-  messages,
-  tools: registry.getDefinitions(),
-  tool_choice: 'auto', // 'auto' | 'none' | { type: 'function', function: { name: '...' } }
-})
-
-if (result.success) {
-  const choice = result.data.choices[0]
-
-  // 检查是否有工具调用
-  if (choice.finish_reason === 'tool_calls' && choice.message.tool_calls) {
-    // 执行所有工具调用并获得 ToolMessage[]
-    const toolResults = await registry.executeAll(choice.message.tool_calls, { parallel: true })
-    if (toolResults.success) {
-      // 将工具结果追加到消息继续对话
-      messages.push(choice.message) // assistant 消息（含 tool_calls）
-      messages.push(...toolResults.data) // tool 结果消息
-    }
-  }
+const enriched = await ai.memory.injectMemories(messages, { objectId: 'user-001', topK: 5 })
+if (!enriched.success) {
+  return enriched
 }
-```
-
----
-
-## 流处理 — `ai.stream`
 
-> `ai.stream` 为纯函数操作，**不需要初始化**即可使用。
+// 多租户推荐入口：scoped() 绑定主体与作用域，所有操作自动携带 objectId / scope（含归属校验），杜绝「忘记传 objectId」越权
+const memory = ai.memory.scoped({ objectId: 'user-001', scope: { topicId: 't-1', personaId: 'p-1' } })
+await memory.add({ content: '用户偏好中文', type: 'preference' })
+const recalled = await memory.recall('语言偏好')
 
-### 逐块处理
+// clear 拒绝空过滤（防误清全局）；全局清空只能显式走管理接口
+await memory.clear({ types: ['event'] }) // 仅清该作用域内的 event
+await ai.memory.admin.clearAll({ confirm: true }) // 危险：清空整个记忆后端，需显式确认
 
-```ts
-const processor = ai.stream.createProcessor()
+const rag = await ai.rag.query('核心架构是什么？', { sources: ['docs'], topK: 5 })
 
-for await (const chunk of ai.llm.chatStream({ messages })) {
-  const delta = processor.process(chunk)
-  if (delta?.content) {
-    process.stdout.write(delta.content)
+const setup = await ai.knowledge.setup()
+if (setup.success) {
+  const ingested = await ai.knowledge.ingest({ documentId: 'doc-001', content: markdownText, title: '产品手册' })
+  if (!ingested.success)
+    return ingested
+  if (ingested.data.cleanupPending) {
+    const repaired = await ai.knowledge.repair({ offset: 0, limit: 100 })
+    if (!repaired.success)
+      return repaired
   }
 }
-
-// 获取完整结果
-const result = processor.getResult()
-// { content: string, toolCalls: ToolCall[], finishReason: string | null }
-
-// 转为 assistant 消息（可直接 push 到 messages 数组）
-const assistantMsg = processor.toAssistantMessage()
-// { role: 'assistant', content: '...', tool_calls?: [...] }
-
-// 重置（复用 processor）
-processor.reset()
 ```
 
-### 快捷收集
+Knowledge 分块直接遵循 datapipe 的单位与硬上限：word 为词，其他为 Unicode code point，保留清洗后文本的分隔符；AI 默认 chunkOptions 仍为 markdown/maxSize=1500/overlap=200，覆盖较小 maxSize 时须同时保证继承的 overlap 小于它。分块配置/表达式失败返回 KNOWLEDGE_INGEST_FAILED，embedding 与版本发布均不会执行，不退回整篇文本绕过预算。
 
-```ts
-// 一次性收集全部内容（不做逐块处理）
-const result = await ai.stream.collect(ai.llm.chatStream({ messages }))
-// { content: string, toolCalls: ToolCall[], finishReason: string | null }
-```
+#### 语音（Audio）
 
-### 流式工具调用
+先在 `ai.init()` 中注册语音模型并映射默认识别/合成模型。凭据默认回退到平台环境变量；只有 LLM 与语音模型确认使用同一凭据时，才显式启用 `inheritLlmApiKey`：
 
-流式响应中 LLM 触发工具调用时，`processor` 会同样累积 `tool_calls`，通过 `finishReason` 判断后执行工具并继续对话：
+平台（`provider`）表示调用协议而非部署位置：`openai` / `mimo` / `qwen` / `doubao` 为云服务；`whisper`（ASR）/ `indextts`（TTS）为可自托管协议，无 canonical 端点，必须显式配置 `baseUrl`，同一协议可切换多个 Endpoint（云 / 内网 / 本地）而不改业务代码。云平台缺少凭据返回 `CONFIGURATION_ERROR`；自托管平台可无凭据（配置 `apiKey` 后按 `Authorization: Bearer` 发送）。
 
 ```ts
-const registry = ai.tools.createRegistry()
-registry.registerMany([weatherTool, searchTool])
-
-const messages: ChatMessage[] = [{ role: 'user', content: '北京今天天气怎么样？' }]
-
-let continueLoop = true
-while (continueLoop) {
-  const processor = ai.stream.createProcessor()
-
-  for await (const chunk of ai.llm.chatStream({ messages, tools: registry.getDefinitions() })) {
-    const delta = processor.process(chunk)
-    if (delta?.content) {
-      process.stdout.write(delta.content)
-    }
-  }
-
-  const result = processor.getResult()
-
-  if (result.finishReason === 'tool_calls' && result.toolCalls.length > 0) {
-    // 将 assistant 消息（含 tool_calls）追加到对话
-    messages.push(processor.toAssistantMessage())
+await ai.init({
+  llm: {
+    apiKey: process.env.HAI_AI_LLM_APIKEY,
+  },
+  audio: {
+    inheritLlmApiKey: true,
+    models: [
+      { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime', operations: ['transcribe'] },
+      { id: 'tts', provider: 'qwen', model: 'qwen3-tts-flash-realtime', operations: ['synthesize'] },
+      // 自托管：whisper / indextts 必须显式配置 baseUrl
+      { id: 'whisper', provider: 'whisper', model: 'faster-whisper-large-v3', operations: ['transcribe'], baseUrl: 'http://127.0.0.1:8101/v1' },
+      { id: 'indextts', provider: 'indextts', model: 'indextts-2.5', operations: ['synthesize'], baseUrl: 'http://127.0.0.1:8102/v1' },
+    ],
+    transcribeModel: 'asr',
+    synthesizeModel: 'tts',
+  },
+})
 
-    // 执行所有工具调用
-    const toolResults = await registry.executeAll(result.toolCalls, { parallel: true })
-    if (toolResults.success) {
-      messages.push(...toolResults.data) // 追加 tool 结果消息
-    }
-    // 继续循环，让 LLM 消费工具结果
-  }
-  else {
-    // finish_reason 为 'stop'，对话结束
-    messages.push(processor.toAssistantMessage())
-    continueLoop = false
-  }
+// 完整识别（可选热词、时间戳粒度与 VAD；strictCapabilities 要求模型真实支持所请求能力）
+const result = await ai.audio.transcribe({
+  audio: { data: wavBytes, format: 'wav' },
+  language: 'zh',
+  contextHints: ['专有名词'],
+  timestampGranularities: ['segment', 'word'],
+  vad: true,
+  model: 'whisper',
+})
+if (result.success) {
+  const text = result.data.text
+  const language = result.data.language // 实际检测语言
+  const words = result.data.segments?.[0]?.words // 词级时间轴（毫秒整数）
+}
+
+// 说话人 / 风格参考合成（IndexTTS）：speakerReference 表达“谁在说”，styleReference 表达“怎么说”
+const cloned = await ai.audio.synthesize({
+  text: '我们下午三点出发。',
+  language: 'zh',
+  model: 'indextts',
+  speakerReference: { audio: speakerWav, language: 'ja' },
+  styleReference: { audio: styleWav },
+  styleStrength: 0.8,
+  targetDurationMs: 3280, // 目标时长（与 speed 互斥），metadata.durationMatched 反馈是否达标
+  durationToleranceMs: 120,
+})
+
+// 实时识别（持续音频输入 → 领域事件流：speech_started / transcript / speech_stopped）
+for await (const event of ai.audio.transcribeStream({
+  audio: { chunks: microphoneChunks, format: 'pcm16', sampleRate: 16000 },
+})) {
+  if (event.type === 'speech_started')
+    onSpeechStart() // 支持服务端 VAD 的平台会在检测到说话时立即产出，可据此取消上游生成
+  else if (event.type === 'transcript')
+    updateTranscript(event.text, event.final)
+}
+
+// 流式合成：调用方为文本段分配稳定 ID，事件可精确关联文本与音频；signal 可随时打断
+const controller = new AbortController()
+for await (const event of ai.audio.synthesizeStream({
+  text: { id: 'answer-1', text: '欢迎参加访谈。' },
+  voice: 'Cherry',
+  instruction: '用轻快的语气',
+  signal: controller.signal,
+})) {
+  if (event.type === 'segment_started')
+    prepareDecoder(event.format, event.sampleRate, event.channels) // 真实输出格式来自服务端解析后的 Provider 输出
+  else if (event.type === 'audio')
+    await player.write(event.data)
+  else if (event.type === 'segment_done')
+    markSegmentReadyToCommit(event.segmentId)
 }
-```
 
-### SSE 编解码
+// 实时会话启动前按操作校验模型能力
+const caps = ai.audio.getCapabilities({ operation: 'synthesize', model: 'tts' })
+if (caps.success && caps.data.synthesize?.streamingAudioOutput) { /* 可实时 TTS */ }
+```
 
-SSE 编解码适用于**自建 HTTP 流式接口**（如 SvelteKit `GET` 路由推送 AI 内容到前端）：
+`ai.audio.synthesize` 返回统一的 `AudioContent` 字节。需要通过 API 返回浏览器可播放的 Base64 负载时，使用 `serializePlayableAudio(result.data)`；该函数会将 `pcm16` 补齐为 WAV 容器，并透传 WAV/MP3：
 
 ```ts
-// 服务端：将 LLM 流式 chunk 编码为 SSE 事件推送给客户端
-async function* streamToSSE(messages: ChatMessage[]): AsyncGenerator<string> {
-  for await (const chunk of ai.llm.chatStream({ messages })) {
-    const delta = chunk.choices[0]?.delta?.content
-    if (delta) {
-      yield ai.stream.encodeSSE({ event: 'delta', data: JSON.stringify({ text: delta }) })
-    }
-  }
-  yield ai.stream.encodeSSE({ event: 'done', data: '' })
-}
+import { serializePlayableAudio } from '@h-ai/ai'
 
-// 客户端：解码 SSE 分片（rawText 可能是不完整的多行数据）
-const decoder = ai.stream.createSSEDecoder()
+const synthesized = await ai.audio.synthesize({ text: '欢迎参加访谈。', voice: 'Cherry' })
+if (!synthesized.success)
+  return synthesized
 
-for await (const rawChunk of response.body) {
-  for (const event of decoder.decode(rawChunk)) {
-    if (event.event === 'delta') {
-      const { text } = JSON.parse(event.data!)
-      process.stdout.write(text)
-    }
-    else if (event.event === 'done') {
-      break
-    }
-  }
-}
+const playable = serializePlayableAudio(synthesized.data)
+if (!playable.success)
+  return playable
 
-// 重置解码器以复用（如下一次请求）
-decoder.reset()
+return playable.data
 ```
 
-> `createSSEDecoder` 内部维护缓冲区，自动拼接跨分片的不完整 SSE 帧，无需手动处理粘包。
+`OptionalSecretSchema` 统一用于 LLM、Audio 与 Image 的可选密钥字段：YAML `null`、空字符串和纯空白字符串都会规范化为 `undefined`。语音密钥优先级为模型条目 `apiKey` → 启用继承后的 LLM `apiKey` → 对应平台环境变量；`inheritLlmApiKey` 默认关闭，避免跨供应商误用密钥。
 
----
+> `synthesizeStream` 严格按 `segment_started → audio* → segment_done` 产出事件。`segment_started` 携带服务端解析 Provider 后的**真实输出音频参数**（`format` / `sampleRate` / `channels`），播放器据此正确解码，不应按请求参数猜测格式。播放器只有在对应音频真正播放完成后才应把该段文本计入 `spokenText`；播放状态仍由应用管理。
 
-## Embedding — `ai.embedding`
+取消/超时/连接错误统一为领域错误：`AbortSignal` 触发 → `AUDIO_CANCELLED`（超时 → `AUDIO_TIMEOUT`），连接失败或 `end` 前异常断连 → `AUDIO_CONNECTION_FAILED`。实时连接时长受 `audio.maxStreamDurationMs`（默认 5 分钟）限制。
 
-### 单条文本嵌入
+浏览器 / 移动端通过 `@h-ai/serv` 暴露的统一语音 WebSocket 入口访问，`@h-ai/ai/client` 提供与 Node 端一致的 `audio.*` API（传输细节内部隐藏）。浏览器客户端严格区分正常结束、取消（`AUDIO_CANCELLED`）与异常断连（`AUDIO_CONNECTION_FAILED`）：取消或在 `end` 前断连会抛出对应领域错误码，`synthesize` 不会把未完成的部分音频当作成功结果返回。
 
-```ts
-const result = await ai.embedding.embedText('这是一段需要向量化的文本')
-if (result.success) {
-  const vector = result.data // number[]（如 1536 维向量）
-}
-```
+IndexTTS 的 Node HTTP 请求使用同版本 Undici fetch/Agent 与 multipart 类型，避免混用 Node 内置 fetch 的调度器协议；模型 `timeout` 覆盖响应头与正文等待。主动取消返回 `AUDIO_CANCELLED`，超时返回 `AUDIO_TIMEOUT`，成功、失败和取消均关闭独立连接；按段流式降级仍在迭代时抛出领域错误。
 
-### 批量文本嵌入
+> 自托管模型服务（faster-whisper / IndexTTS / Qwen3-4B 的 CPU/GPU Docker 镜像、权重下载与离线打包）见 [`models/`](./models/README.md)。镜像与权重下载优先使用 ModelScope，自动回退 HuggingFace 镜像。
 
-```ts
-const result = await ai.embedding.embedBatch([
-  '第一段文本',
-  '第二段文本',
-  '第三段文本',
-])
-if (result.success) {
-  const vectors = result.data // number[][]
-}
-```
+#### 文生图（Image）
 
-### 完整嵌入请求
+在 `ai.init()` 注册模型后，调用方只接收标准化图片字节，不感知厂商 Base64、内联数据或临时 URL：
 
 ```ts
-const result = await ai.embedding.embed({
-  input: ['文本1', '文本2'],
-  model: 'text-embedding-3-small',
-  dimensions: 1536,
+await ai.init({
+  image: {
+    models: [
+      { id: 'image', provider: 'openai', model: 'gpt-image-2' },
+      { id: 'free', provider: 'pollinations', model: 'zimage' },
+    ],
+    generateModel: 'image',
+  },
 })
-if (result.success) {
-  const response = result.data
-  // response.data: EmbeddingItem[]（{ index, embedding }）
-  // response.usage: { prompt_tokens, total_tokens }
-}
-```
-
----
-
-## 推理引擎 — `ai.reasoning`
-
-支持三种推理策略：
-
-| 策略           | 说明                       | 适用场景           |
-| -------------- | -------------------------- | ------------------ |
-| `cot`          | 思维链（Chain of Thought） | 分步推理           |
-| `react`        | 思考-行动-观察循环         | 需要工具调用的推理 |
-| `plan-execute` | 先规划后执行               | 复杂多步任务       |
 
-### 基本推理
-
-```ts
-const result = await ai.reasoning.run('如何计算圆的面积？', {
-  strategy: 'cot', // 默认 'react'
+const result = await ai.image.generate({
+  prompt: '一个正在构建开源框架的友好机器人',
+  size: { width: 1024, height: 1024 },
+  referenceImages: [
+    { data: await readImage('character.png'), mimeType: 'image/png' },
+  ],
 })
-
 if (result.success) {
-  const { answer, steps, rounds } = result.data
-  // answer: 最终回答
-  // steps: ReasoningStep[]（每步包含 type, content）
-  //   type: 'thought' | 'action' | 'observation' | 'plan' | 'answer'
-  // rounds: 执行轮数
+  const { data, mimeType } = result.data.images[0]!
+  await saveImage(data, mimeType)
 }
 ```
 
-### 带工具的推理
+`referenceImages` 可省略；公共层只接受图片字节与 MIME，multipart、`inlineData`、Data URL 等差异由 Provider 转换。凭据可在模型条目传入，或使用 `HAI_AI_IMAGE_<PROVIDER>_APIKEY` / 厂商环境变量。Qwen 与 Seedream 返回的临时 URL 会在 Provider 内立即下载，不会泄漏到公共返回值。完整接口差异与模型说明见 [REFERENCE.md](./REFERENCE.md#image)。
 
-```ts
-const registry = ai.tools.createRegistry()
-registry.register(calculatorTool)
-registry.register(searchTool)
-
-const result = await ai.reasoning.run('北京到上海的距离是多少公里？', {
-  strategy: 'react',
-  tools: registry,
-  maxRounds: 5, // 最大轮次（默认 10）
-  model: 'gpt-4o',
-  temperature: 0.2,
-  systemPrompt: '你是一个地理知识专家',
-})
-```
+图片下载只允许无凭证、默认 443 端口的公网 HTTPS，每次 socket DNS 解析校验全部地址并直接使用该批地址；阻止 IPv4/IPv6 私网、回环、链路本地、映射/转换及保留地址，重定向最多 3 次且每跳重新校验。下载使用独立连接，不传递厂商认证头或应用 Cookie。`baseUrl` 是可信运维配置，厂商 API 请求拒绝重定向。
+
+`image.maxImageBytes` 默认 20971520（20 MiB，最大 100 MiB），限制单张输出和参考图；`image.maxImages` 默认 4（最大 16），限制输出与参考图数量，临时 URL 串行下载。实际读取（含解压后）超过上限立即取消；JSON 响应最多 `max(64 KiB, 2 × maxImageBytes)`，错误正文最多 64 KiB。模型 `timeout` 默认 120000ms，覆盖厂商请求、重定向和全部下载；`signal` 可取消整个过程。输出仅支持 PNG/JPEG/GIF/WebP 的 MIME 与魔数匹配，拒绝 SVG；魔数校验不等于完整图片解码或尺寸核验。拒绝地址、超限、超时分别返回 `IMAGE_DOWNLOAD_BLOCKED`、`IMAGE_TOO_LARGE`、`IMAGE_TIMEOUT`，调用方须先检查 success。
 
----
+#### Context 管理器
 
-## 检索 — `ai.retrieval`
+自动记忆提取在本节点后台运行；`pendingMemoryTasks=0` 不代表全部成功。`flush()` 等待本批任务，异常和失败 HaiResult 都返回 `MEMORY_EXTRACT_FAILED`（含失败数量），同轮并发观察者共享结果。返回即确认该批报告，后续只观察新任务，不自动重放可能部分完成的提取。`save()`、`reset({ waitForMemoryTasks: true })`、`consolidate()` 遇到该失败立即返回，不继续后续状态或记忆写入。进程崩溃后的外部效果仍须人工核对。
 
-### 注册检索源
+`scope: { objectId, sessionId }` 必填。相同 scope 的所有节点共用一条版本记录，原子保存消息、摘要、生成 owner、轮次及待提交状态；`addMessage`、每个对外流式 delta 和最终提交即时持久化，`save()` 只刷新共享快照、等待本节点记忆任务并同步会话目录。`getMessages/getTurns/getSummaries/getTokenUsage` 返回最近一次成功读写的独立快照；跨节点读取前调用 `await manager.reload()` 或 `restoreManager()`。
 
-检索源可以在 `ai.init()` 中通过 `retrieval.sources` 预配置，也可以在初始化后动态注册。
+并发限制按共享 scope 生效；`reject` 立即返回忙，`queue` 可取消地轮询（不承诺 FIFO）。生成租约为存储端时钟 30 秒，每 10 秒续租，最终写入同时校验版本、owner 和期限。失联生成过期后由下一次操作标为 interrupted，保留生成记录，不自动重放 LLM、工具或记忆提取。manual 的 pending 不自动过期，可在另一节点/重启后按同一 turnId 提交；相同终态与文本重复提交幂等，不同内容拒绝。外部工具/LLM/后台记忆不与上下文跨系统原子提交，进程失联后须核对未知副作用，不能据此承诺外部恰好一次。`reset` 更换共享纪元；`removeSession` 清空正文并保留永久墓碑，同一 scope 不复用，旧节点不能重建。
 
-**方式一：初始化时预配置**
+自定义 `AIRelStore` 必须提供 `readVersioned`、`compareAndSwap` 和存储端 `currentTime`；普通 save/saveMany 也要更换不可复用版本。CAS 的 `expectedVersion: undefined` 仅创建，`notAfter` 在最终写入以存储时钟严格检查，冲突/截止返回 undefined，存储故障抛错。默认 PostgreSQL/MySQL/SQLite 实现均执行这些条件；SQLite 仅供开发/测试，生产使用 PostgreSQL/MySQL。新 schema 含 version 列，不提供旧表自动迁移。
 
 ```ts
-await 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: '常见问题' },
-    ],
-  },
+const manager = ai.context.createManager({
+  scope: { objectId: 'user-001', sessionId: 'sess-001' },
+  compress: { auto: true, strategy: 'hybrid', maxTokens: 8000 },
+  memory: { enable: true, enableExtract: true },
+  concurrency: 'reject', // 单活动生成（默认）：活动生成期间的新 chat 返回 CONTEXT_BUSY；'queue' 则排队
 })
+if (manager.success) {
+  const reply = await manager.data.chat('你好')
+  const saved = await manager.data.save()
+  if (!saved.success)
+    return saved
+  // reset 生命周期完整：终止活动生成、清空消息/摘要/轮次，默认保留系统提示词
+  await manager.data.reset() // 可传 { preserveSystemPrompt, cancelActiveTurn, waitForMemoryTasks }
+}
 ```
 
-**方式二：动态注册**
+同一 scope 默认实行**跨节点单活动生成**，避免「上一轮 AI 尚未退出，下一轮 user 消息先写入」导致的消息乱序；`reset()` 现为异步并会终止活动生成、释放并发屏障、清空轮次并默认重新写入 Persona/System Prompt。
 
-```ts
-// 添加检索源（持久化到 DB）
-await ai.retrieval.addSource({
-  id: 'docs',
-  collection: 'documentation',
-  name: '产品文档',
-  topK: 5,
-  minScore: 0.7,
-})
+##### 真实对话状态（Conversation Commit Layer）
 
-await ai.retrieval.addSource({
-  id: 'faq',
-  collection: 'faq',
-  name: '常见问题',
-})
+默认（`turnCommit: 'auto'`）下，`chat` / `chatStream` 会把**模型生成的完整文本**写入上下文。但在「模型生成 → TTS 合成 → 实际播放」链路中，AI 可能说到一半就被打断——此时进入下一轮所有参与者可见的对话状态，应当是**实际播放出去的部分**，而非模型本想说完的全文。
 
-// 查看已注册的源（从 DB 读取）
-const sources = await ai.retrieval.listSources() // RetrievalSource[]
-```
+设置 `turnCommit: 'manual'` 后，生成结果不会自动写入上下文，而是返回一个 `turnId`；由调用方在确定「实际发生了什么」后显式提交真实文本。
 
-### 执行检索
+`chatStream` 在**调用上游模型前**就登记轮次并产出 `turn_started`（事件序列 `turn_started → delta* → done`，中途取消时 `turn_started → delta* → cancelled`）。因此即使生成到一半被 `AbortSignal` 取消，也能拿到 `turnId` 与已生成文本，用真实内容提交：
 
 ```ts
-const result = await ai.retrieval.retrieve({
-  query: '如何配置数据库连接？',
-  sources: ['docs', 'faq'], // 指定源（不传则查所有源）
-  topK: 10,
-  minScore: 0.6,
-})
+const created = ai.context.createManager({ scope: { objectId: 'user-001', sessionId: 'sess-001' }, turnCommit: 'manual' })
+if (!created.success)
+  return created
+const m = created.data
+const controller = new AbortController()
 
-if (result.success) {
-  for (const item of result.data.items) {
-    // item.content   — 匹配的文本内容
-    // item.score     — 相似度分数
-    // item.sourceId  — 来自哪个检索源
-    // item.citation  — 引用信息（documentId, title, url 等）
+for await (const ev of m.chatStream('请展开讲讲', { signal: controller.signal })) {
+  if (ev.type === 'turn_started') {
+    await m.markTurnSpeaking(ev.turnId) // 可选：标记进入播放
+  }
+  else if (ev.type === 'delta') {
+    feedTts(ev.text) // 边生成边合成播放
+  }
+  else if (ev.type === 'done') {
+    await m.commitTurn(ev.turnId) // 完整提交
+  }
+  else if (ev.type === 'cancelled') {
+    // 生成被 controller.abort() 取消：轮次保留，只提交实际播放出去的部分
+    await m.interruptTurn(ev.turnId, { text: actuallySpokenText })
   }
 }
-```
-
-### 移除检索源
 
-```ts
-await ai.retrieval.removeSource('docs')
+// 观测每一轮的 generated / committed / status
+const turns = m.getTurns()
 ```
 
----
+- `commitTurn(turnId, { text? })` — 提交真实文本（缺省用完整生成文本），状态转 `completed`。
+- `interruptTurn(turnId, { text? })` — 只写入实际表达出去的部分（缺省视为未表达，不写入），状态转 `interrupted`。
+- 只有 `committed` 的内容进入上下文与记忆提取；未提交/被打断丢弃的部分不会污染后续轮次。
+- 若轮次在流完成前已被 `interruptTurn` 打断（如主持人抢话，同时上游模型恰好正常结束），`chatStream` **不会再产出 `done`**，避免业务层误判为正常完成后继续提交文本。
 
-## RAG 问答 — `ai.rag`
+##### 会话固化（Memory 生命周期）
 
-基于 Retrieval + LLM 的检索增强问答。
+会话进行中，每轮对话按 `scope: { sessionId }` 提取**短期会话记忆**；会话结束时用 `consolidate()`
+把「短期记忆 + 摘要」沉淀为**跨会话长期记忆**，形成 `Session Memory → Summary → Long-term Memory` 闭环：
 
 ```ts
-const result = await ai.rag.query('项目的部署流程是什么？', {
-  sources: ['docs'],
-  topK: 5,
-  minScore: 0.6,
-  model: 'gpt-4o-mini',
-  temperature: 0.3,
-  systemPrompt: '根据检索到的文档内容回答问题，注明信息来源。',
-})
-
+// 会话结束时固化：整合摘要 → 提取长期记忆（写入不含 sessionId 的持久作用域）
+const result = await manager.consolidate({ scope: { userId: 'user-001', personaId: 'xiaoq' } })
 if (result.success) {
-  const { answer, citations, context } = result.data
-  // answer: LLM 生成的回答
-  // citations: Citation[]（引用来源列表）
-  // context: RagContextItem[]（使用的上下文片段）
+  // result.data.summary  —— 本次会话整合摘要
+  // result.data.memories —— 固化到长期记忆的条目
 }
 ```
 
-### 自定义上下文格式
+#### Persona（AI 角色人格）
+
+Memory 用 `objectId` / `scope` 回答「谁的记忆」；Persona 回答「AI 是谁」——为每个 AI 角色定义
+稳定的系统提示词与性格特征，并通过 `scope: { personaId }` 关联其长期记忆：
 
 ```ts
-const result = await ai.rag.query('问题', {
-  formatContext: (items) => {
-    return items
-      .map((item, i) => `[来源${i + 1}] ${item.content}`)
-      .join('\n\n')
-  },
+await ai.persona.save({
+  id: 'xiaoq',
+  name: '小Q',
+  systemPrompt: '你是一位经济学家，善于从长期视角分析问题。',
+  traits: ['数据驱动', '偏好引用真实案例'],
 })
-```
 
-### 多轮 RAG 对话
-
-```ts
-const result = await ai.rag.query('更详细地解释第二点', {
-  messages: [
-    { role: 'user', content: '部署流程是什么？' },
-    { role: 'assistant', content: '部署分为三步：1. 构建镜像 2. 推送仓库 3. 更新集群' },
-  ],
+// 组合出可直接喂给 ContextManager 的系统提示词（systemPrompt + traits）
+const composed = await ai.persona.compose('xiaoq')
+const manager = ai.context.createManager({
+  scope: { objectId: 'user-001', sessionId: 'persona-session' },
+  systemPrompt: composed.data,
+  memory: { enable: true, enableExtract: true, scope: { personaId: 'xiaoq' } },
 })
 ```
 
----
+`ai.persona` 提供 `save` / `get` / `update` / `remove` / `list` / `compose`；角色档案全局共享（不按 `objectId` 隔离）。
+
+### 配置
 
-## 知识库 — `ai.knowledge`
+```yaml
+llm:
+  apiKey: ''
+  baseUrl: https://api.openai.com/v1
+  model: gpt-4o-mini
+  api: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
+  timeout: 60000
+  tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
+  models: # 可为每个模型单独指定协议
+    - {id: fast, model: gpt-4o-mini}
+    - {id: strong, model: gpt-4.1, api: responses}
+    - {id: claude, model: claude-3-5-sonnet-latest, api: anthropic}
+  scenarios:
+    chat: fast
+    reasoning: strong
+    embedding: embed
 
-完整的知识库管理：文档入库（自动分块 + 向量化 + 实体提取）→ 语义检索 → 知识问答。
+embedding:
+  dimensions: 1536
+  batchSize: 100
 
-### 初始化知识库
+knowledge:
+  collection: hai_ai_knowledge
+  dimension: 1536
+  cleanOptions:
+    removeHtml: true
+    normalizeWhitespace: true
+  chunkOptions:
+    mode: markdown
+    maxSize: 1500
+    overlap: 200
 
-```ts
-await ai.knowledge.setup({
-  collection: 'my-knowledge',
-  dimension: 1536,
-})
+memory:
+  provider: native # native | mem0
+  maxEntriesPerObject: 1000 # 单主体（objectId）最大记忆条数
+  maxEntriesGlobal: 100000 # 跨所有主体的全局上限
+  recencyDecay: 0.95
+  embeddingEnabled: true
+  defaultTopK: 10
+  candidateMultiplier: 5 # 候选池倍数：先取回 topK×倍数 条候选，再按 scope/重要性过滤，最后截取 topK
+  writebackRelatedTopK: 20
 ```
 
-### 文档入库
+通过 `core.config.load('ai', ...)` 加载时，约定环境变量优先于 YAML；
+例如 `HAI_AI_LLM_APIKEY`、`HAI_AI_LLM_BASEURL`、`HAI_AI_LLM_MODEL`。
 
-```ts
-const result = await ai.knowledge.ingest({
-  documentId: 'doc-001',
-  content: markdownContent,
-  title: '产品使用手册',
-  url: 'https://docs.example.com/manual',
-  enableEntityExtraction: true, // 自动提取人物、项目、概念等实体
-  cleanOptions: {
-    removeHtml: true,
-  },
-  chunkOptions: {
-    mode: 'markdown', // sentence | paragraph | markdown | page | custom
-    maxSize: 1500,
-    overlap: 200,
-  },
-  metadata: { category: 'manual', version: '2.0' },
-})
+启用 mem0（真·嵌入式 mem0ai/oss 引擎）：
 
-if (result.success) {
-  const { chunkCount, entities, duration } = result.data
-  // chunkCount: 分块数量
-  // entities: KnowledgeEntity[]（提取到的实体）
-  // duration: 耗时（毫秒）
-}
+```yaml
+memory:
+  provider: mem0
+  defaultTopK: 10
 ```
 
-### 知识检索
+- **`native`（默认，推荐）**：HAI 原生引擎，复用同一套 vecdb（向量库）、reldb（关系库）、LLM 与 Embedding。`extract` 采用 **Mem0 式批量合并**——一次 LLM 调用对整批抽取事实与相关既有记忆做 ADD / UPDATE / DELETE / NONE 决策，实现增量更新、跨条去重与矛盾删除，并支持 `category` 主题标签。`maxEntriesPerObject`、`maxEntriesGlobal`、`recencyDecay`、`embeddingEnabled`、`writebackRelatedTopK` 均作用于此后端；淘汰按 `objectId` 分区触发，不会因某一主体写入过多而淘汰其他主体的记忆。native 后端的 `scope` 过滤：候选集已被 `objectId` 索引收窄（≤ `maxEntriesPerObject`），PostgreSQL 上还会把 scope 下推为 `data @> '{"scope":...}'::jsonb` 包含查询并命中 JSONB **GIN 索引**（SQLite / MySQL 退回内存匹配，结果一致）。
+- **`mem0`（真·mem0ai/oss）**：直接使用 `mem0ai/oss` 的 `Memory` 引擎（嵌入式，无云服务）。LLM / Embedder 从 `llm` 配置提取；`qdrant` 可复用底层 vecdb。当前适配仅映射带完整连接参数的 `qdrant`；生产环境（`NODE_ENV` 或 `HAI_CORE_ENV` 为 `production`）即使设置 `memory.allowEphemeralFallback: true` 也拒绝实际内存回退。临时回退仅限开发或明确的 `HAI_E2E=1` / `HAI_E2E_MOCK=1`；缺少后端同样不能在生产启动。历史记录默认禁用。
 
-```ts
-const result = await ai.knowledge.retrieve('数据库配置方法', {
-  topK: 10,
-  minScore: 0.6,
-  enableEntityBoost: true, // 实体命中时加权（提高相关性）
-  collection: 'my-knowledge',
-})
+两个 Provider 对外 `ai.memory.*` API 完全一致（`extract` / `recall` / `injectMemories` / `add` / `update` / `get` / `remove` / `list` / `listPage` / `clear`），均支持 `objectId`（主体隔离）与 `scope`（业务作用域 key-value 过滤，如 `{ topicId, personaId }`）。`recall` / `list` / `listPage` / `clear` 均按 `scope` 严格过滤，`clear` 在传入 `types` / `scope` 时仅删除同时匹配项（避免误删）。mem0 后端的 `extract` 在框架层用统一提取器完成分类与打分（honor `types` / `model` / `minImportance` / `systemPrompt`）后以 `infer:false` 写入，保留 `hai_type` / `hai_importance`；`recall` 同样支持 `types` 过滤与 `recencyWeight` 时间衰减——二者行为与 native 一致。Mem0 的 `update` 使用 SDK 原地修改文本与元数据，保持 `id` 和创建时间。SDK 查询使用 `filters.user_id`，写入和整主体删除使用 `userId`。SDK 无列表游标：`list` / `listPage` / 条件 `clear` 最多支持每主体 1000 条原始候选（含过期条目），多取一条探测完整性；超限返回 `MEMORY_LIST_INCOMPLETE`（906），不会伪造 total 或执行部分条件删除。候选完整时按 UTC 日期剔除过期项，再按类型/scope 过滤和分页；仅 `objectId` 的清理使用 SDK `deleteAll`，不受列表上限限制。公共空条件清理被拒绝；跨主体全清仅限受信管理员显式 `admin.clearAll({ confirm: true })`。
 
-if (result.success) {
-  for (const item of result.data.items) {
-    // item.content         — 匹配的文本
-    // item.score           — 综合分数
-    // item.citation        — 引用（documentId, title, url）
-    // item.matchedEntities — 命中的实体名称
-  }
-}
-```
+Mem0 3.3.1 的 Qdrant 适配仍依赖 `QdrantClient.search`；项目将 `@qdrant/js-client-rest` 精确锁定为受测的 `1.18.0`，AI 的可选 peer 也声明此版本。启动会检查该公开方法，缺失时明确配置失败；不要覆盖为已移除此方法的 1.19。
 
-### 知识问答
+适配器通过 SDK 公开的 `client` 配置注入独享客户端；Mem0 的 Qdrant 写入与删除均使用 `wait: true`，等待服务端应用完成后才继续写后读或分批清理。
 
-```ts
-const result = await ai.knowledge.ask('如何配置 Redis 缓存？', {
-  topK: 5,
-  model: 'gpt-4o-mini',
-  temperature: 0.3,
-  systemPrompt: '基于提供的知识回答，标注信息来源。',
-})
+Mem0 的 pgvector 组合在所有环境拒绝启动：当前 SDK 将 PostgreSQL 连接保存在私有对象中，未提供公开关闭入口，框架无法履行资源清理契约。需要 pgvector 时选择 `memory.provider: native`；该原生后端保持支持。`disableHistory: true` 使用 SDK 无资源的历史占位实现，不创建历史 SQLite 文件。工厂通过公开的一条有界只读查询等待实际后端 ready 后才发布成功。
 
-if (result.success) {
-  const { answer, citations, usage } = result.data
-  // answer: LLM 生成的回答
-  // citations: Citation[]（引用列表）
-  // usage: { prompt_tokens, completion_tokens, total_tokens }
-}
-```
+`add` / `extract` 的 SDK 回执不含完整业务字段，框架写后读取权威记录再返回；并发提取等待全部在途写入结束。若写入或写后读失败，`error.ext.requiresEffectReconciliation=true`，`memoryIds` 保存已知写入 ID（回执丢失时可能为空）。应按主体核对实际记忆后决定恢复，不能盲目重做 add/extract；框架不自动重放。
 
-### 多轮知识问答
+**候选池与 scope 漏召回**：`scope` 过滤在内存中完成，若先按 `topK` 截断再过滤，同一主体下相关度较高的其它主题/角色记忆会把目标 scope 的记忆挤出候选池，导致「明明有却召回 0 条」。为此 `recall` / `injectMemories` 先取回 `topK × candidateMultiplier`（默认 5）条候选，过滤后再截取 `topK`。scope 隔离越细（如按 `topicId` + `personaId`），可将 `candidateMultiplier` 调大：
 
 ```ts
-const result = await ai.knowledge.ask('请详细解释第二步', {
-  messages: [
-    { role: 'user', content: 'Redis 配置流程？' },
-    { role: 'assistant', content: '分三步：1. 安装 2. 配置 3. 连接测试' },
-  ],
+const memories = await ai.memory.recall('经济发展', {
+  objectId: 'user-001',
+  scope: { topicId: 'C' },
+  topK: 10,
+  candidateMultiplier: 8, // 覆盖配置默认值，扩大候选池
 })
 ```
 
-### 实体管理
+`ai.config` 返回脱敏后的配置快照；`apiKey`、`privateKey`、URL 内嵌凭证等敏感字段不会原样暴露。
 
-```ts
-// 列出所有实体
-const entities = await ai.knowledge.listEntities({
-  type: 'person', // person | project | concept | organization | location | event | other
-  keyword: '张',
-  limit: 50,
-})
+### 安全边界
 
-// 按实体查询关联文档
-const result = await ai.knowledge.findByEntity('Redis', {
-  collection: 'my-knowledge',
-  type: 'concept',
-})
-if (result.success) {
-  // result.data: EntityDocumentResult[]
-}
-```
+- Prompt、检索文档和模型输出都按不可信输入处理；不要把用户内容拼进不可覆盖的系统规则。
+- Zod 只校验工具参数形状，不代表调用者有权限。高权限工具必须在 handler 内再次校验身份、租户、资源归属与配额，并只把允许自动执行的工具注册给模型。
+- `callRemoteAgent()` 是独立客户端能力，只依赖 `ai.init()`，不要求配置 Agent Card 或注册本地 executor。它拒绝非 HTTP(S) 和 URL 内嵌凭据，但应用仍必须对远端 origin 配置白名单，并在出口代理处限制 DNS 重绑定、重定向到私网和云元数据地址。
+- 不记录完整 Prompt、工具参数、A2A headers、临时模型凭据或带 query 的远端 URL；确需审计时仅保存脱敏摘要。
 
----
+### 错误处理
 
-## 记忆管理 — `ai.memory`
+```ts
+const result = await ai.llm.chat({ messages })
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiAIError.NOT_INITIALIZED.code:
+      // 先调用 ai.init()
+      break
+    case HaiAIError.API_ERROR.code:
+      // 上游模型服务失败，可重试或降级
+      break
+  }
+}
+```
 
-从对话中自动提取关键信息（事实、偏好、事件等），存储并在后续对话中检索注入。支持 `objectId` 隔离不同对象（用户/智能体）的记忆空间。
+常见错误段位：
 
-### 记忆类型
+- `hai:ai:010-012`：初始化/配置。
+- `hai:ai:100-107`：LLM 与历史记录。
+- `hai:ai:300-302`：Embedding。
+- `hai:ai:600-701`：Retrieval/RAG。
+- `hai:ai:800-805`：Knowledge。
+- `hai:ai:050-059`：Audio。
+- `hai:ai:060-068`：Image，含下载地址拒绝、资源超限与总超时。
+- `hai:ai:900-906`：Memory。
+- `hai:ai:980-984`：A2A。
 
-| 类型          | 说明                 |
-| ------------- | -------------------- |
-| `fact`        | 事实信息             |
-| `preference`  | 用户偏好、习惯       |
-| `event`       | 重要事件、截止日期   |
-| `entity`      | 关键人物、组织、项目 |
-| `instruction` | 用户的明确指令或规则 |
+## 开发测试
 
-### 自动提取记忆
+```bash
+pnpm --filter @h-ai/ai typecheck
+pnpm --filter @h-ai/ai lint
+pnpm --filter @h-ai/ai test
+pnpm --filter @h-ai/ai build
+```
 
-```ts
-const messages = [
-  { role: 'user' as const, content: '我叫张三，我更喜欢用中文回复，我的项目叫 HAI Framework' },
-  { role: 'assistant' as const, content: '好的张三，我记住了你的偏好。' },
-]
-
-const result = await ai.memory.extract(messages, {
-  types: ['preference', 'entity'], // 只提取指定类型（可选）
-  minImportance: 0.5, // 过滤低重要性条目（可选）
-  objectId: 'user-001', // 关联到对象标识（可选，不传为全局）
-  model: 'gpt-4o-mini', // 指定提取模型（可选）
-  systemPrompt: 'Only extract durable user preferences and explicit long-term instructions.', // 自定义提取提示词（可选）
-})
-
-if (result.success) {
-  // result.data: MemoryEntry[]（已自动存储到内存）
-  // 每条包含：id, content, type, importance, vector, createdAt 等
-}
-```
-
-### 手动添加记忆
-
-```ts
-const result = await ai.memory.add({
-  content: '用户是后端开发工程师，使用 TypeScript',
-  type: 'fact',
-  importance: 0.8, // [0, 1]，默认 0.5
-  objectId: 'user-001', // 可选，不传为全局
-  metadata: { tags: ['tech', 'profile'] },
-})
-
-if (result.success) {
-  const entry = result.data // MemoryEntry（含自动生成的 id 和 vector）
-}
-```
-
-### 更新记忆
-
-```ts
-const result = await ai.memory.update('mem_1709712345_abc12345', {
-  content: '用户是全栈开发工程师',
-  importance: 0.9,
-})
-if (result.success) {
-  // result.data: MemoryEntry（更新后的条目）
-}
-```
-
-### 检索记忆
-
-```ts
-const result = await ai.memory.recall('用户的编程语言偏好', {
-  topK: 5, // 返回数量（默认 10）
-  types: ['preference'], // 按类型过滤
-  minImportance: 0.3, // 最低重要性
-  recencyWeight: 0.2, // 时间权重 [0, 1]（0 = 纯相似度，1 = 纯时间排序）
-  objectId: 'user-001', // 按对象过滤（可选）
-})
-
-if (result.success) {
-  for (const memory of result.data) {
-    // memory.content      — 记忆内容
-    // memory.type         — 类型
-    // memory.importance   — 重要性
-    // memory.createdAt    — 创建时间
-    // memory.accessCount  — 被检索次数
-  }
-}
-```
-
-### 注入记忆到对话
-
-```ts
-const messages = [
-  { role: 'system' as const, content: '你是一个编程助手' },
-  { role: 'user' as const, content: '帮我写一个排序函数' },
-]
-
-const result = await ai.memory.injectMemories(messages, {
-  topK: 5, // 注入记忆数量
-  maxTokens: 500, // 记忆最大 Token 预算
-  position: 'system', // 'system' = 追加到 system 末尾，'before-last' = 插入最后一条用户消息之前
-  objectId: 'user-001', // 按对象过滤（可选）
-})
-
-if (result.success) {
-  // result.data: ChatMessage[]（已注入记忆的消息列表）
-  // system 消息末尾会追加:
-  // --- Relevant Memories ---
-  // [1] (preference) 用户偏好使用 TypeScript
-  // [2] (fact) 用户是后端工程师
-  // --- End Memories ---
-
-  const response = await ai.llm.chat({ messages: result.data })
-}
-```
-
-### 列表、删除与清空
-
-```ts
-// 列出记忆（支持过滤）
-const list = await ai.memory.list({
-  types: ['fact', 'preference'],
-  objectId: 'user-001',
-  limit: 50,
-})
-
-// 分页列出记忆
-const page = await ai.memory.listPage({
-  objectId: 'user-001',
-  offset: 0,
-  limit: 20,
-})
-if (page.success) {
-  // page.data.items: MemoryEntry[]
-  // page.data.total: number
-}
-
-// 删除指定记忆
-await ai.memory.remove('mem_1709712345_abc12345')
-
-// 按类型清空
-await ai.memory.clear({ types: ['event'] })
-
-// 按对象清空
-await ai.memory.clear({ objectId: 'user-001' })
-
-// 全部清空
-await ai.memory.clear()
-```
-
----
-
-## Token 估算 — `ai.token`
-
-估算文本或消息列表的 Token 数量。
-
-```ts
-// 估算消息列表的 Token 数
-const tokenCount = ai.token.estimateMessages(messages)
-// tokenCount: number
-
-// 估算纯文本的 Token 数
-const count = ai.token.estimateText('Hello world')
-// count: number（中文约 1.5 token/字，英文约 4 字符/token）
-```
-
----
-
-## 消息摘要 — `ai.summary`
-
-对消息列表生成 LLM 摘要，支持增量追加。
-
-```ts
-// 对消息生成摘要
-const result = await ai.summary.summarize(messages, {
-  model: 'gpt-4o-mini',
-  temperature: 0.3,
-  systemPrompt: 'Focus on key decisions, constraints, and unresolved action items.',
-})
-
-if (result.success) {
-  const { summary, tokenCount, coveredMessages } = result.data
-  // summary: 摘要文本
-  // tokenCount: 摘要的估算 Token 数
-  // coveredMessages: 覆盖的原始消息数
-}
-
-// 生成纯文本摘要
-const textResult = await ai.summary.generate(messages, {
-  systemPrompt: 'Summarize in one concise paragraph for handoff notes.',
-})
-if (textResult.success) {
-  // textResult.data: string（摘要文本）
-}
-
-// 增量摘要（在已有摘要基础上追加）
-const updated = await ai.summary.summarize(newMessages, {
-  systemPrompt: 'Keep the summary focused on product decisions and next steps.',
-  previousSummary: existingSummary,
-})
-```
-
----
-
-## 上下文压缩 — `ai.compress`
-
-压缩超长对话至指定 Token 预算。
-
-### 压缩策略
-
-| 策略             | 说明                                     |
-| ---------------- | ---------------------------------------- |
-| `sliding-window` | 保留 system + 最近 N 条消息，丢弃旧消息  |
-| `summary`        | 对旧消息生成 LLM 摘要替换                |
-| `hybrid`（默认） | 先滑动窗口，仍超限则对被移除部分生成摘要 |
-
-### 压缩消息列表
-
-```ts
-const result = await ai.compress.tryCompress(messages, {
-  strategy: 'hybrid', // summary | sliding-window | hybrid
-  maxTokens: 4000, // 目标 Token 预算
-  preserveSystem: true, // 保留 system 消息（默认 true）
-  preserveLastN: 4, // 保留最近 N 条不压缩（默认 4）
-  summaryModel: 'gpt-4o-mini', // 摘要用模型
-})
-
-if (result.success) {
-  const { messages: compressed, originalTokens, compressedTokens, removedCount, summary } = result.data
-  // compressed: 压缩后的消息列表
-  // originalTokens: 原始 Token 数
-  // compressedTokens: 压缩后 Token 数
-  // removedCount: 被移除/合并的消息数
-  // summary: 生成的摘要文本（仅 summary/hybrid 策略有值）
-
-  const response = await ai.llm.chat({ messages: compressed })
-}
-```
-
----
-
-## 上下文管理 — `ai.context`
-
-有状态上下文管理器，适用于多轮对话场景。自动跟踪 Token 使用量、超限时自动压缩，并可编排 LLM / Memory / RAG / Reasoning / Tools 进行完整的对话流程。支持会话级持久化。
-
-### 创建管理器并对话
-
-```ts
-const managerResult = ai.context.createManager({
-  scope: { objectId: 'user-001', sessionId: 'sess-001' },
-  systemPrompt: '你是一个友好的助手。',
-  model: 'gpt-4o-mini',
-  compress: {
-    maxTokens: 8000,
-    strategy: 'hybrid',
-    preserveLastN: 4,
-    auto: true,
-  },
-  memory: { enable: true, enableExtract: true, topK: 5 },
-})
-
-if (!managerResult.success)
-  return
-
-const manager = managerResult.data
-
-// 直接对话（自动编排 LLM + 记忆注入/提取 + 压缩）
-const chatResult = await manager.chat('你好')
-if (chatResult.success) {
-  // chatResult.data.reply — LLM 回复
-  // chatResult.data.model — 使用的模型
-  // chatResult.data.usage — Token 使用统计
-}
-
-// 流式对话
-for await (const event of manager.chatStream('讲个故事')) {
-  if (event.type === 'delta')
-    process.stdout.write(event.text)
-  if (event.type === 'done')
-    console.warn('\n完成', event.model)
-}
-
-// 持久化
-await manager.save()
-```
-
-### 底层消息管理
-
-```ts
-const managerResult = ai.context.createManager({
-  compress: { maxTokens: 8000, strategy: 'hybrid' },
-})
-const manager = managerResult.data
-
-// 手动追加消息（超限时自动触发压缩）
-await manager.addMessage({ role: 'user', content: userInput })
-
-// 获取当前消息列表（已压缩）
-const msgs = manager.getMessages()
-const response = await ai.llm.chat({ messages: msgs.data })
-
-// 追加助手回复
-await manager.addMessage(response.data.choices[0].message)
-
-// 查看 Token 使用量
-const usage = manager.getTokenUsage()
-// usage.data.current / usage.data.budget
-
-// 查看历史摘要
-const summaries = manager.getSummaries()
-
-// 重置
-manager.reset()
-```
-
-### 恢复已有会话
-
-```ts
-const managerResult = await ai.context.restoreManager(
-  { objectId: 'user-001', sessionId: 'sess-001' },
-  { compress: { maxTokens: 8000 }, memory: { enable: true } },
-)
-if (managerResult.success) {
-  const manager = managerResult.data
-  // manager 已包含之前保存的消息和摘要
-  const result = await manager.chat('继续上次的话题')
-}
-```
-
-### 启用 RAG / Reasoning / Tools
-
-```ts
-const registry = ai.tools.createRegistry()
-registry.register(ai.tools.define({
-  name: 'search',
-  description: '搜索',
-  parameters: z.object({ query: z.string() }),
-  execute: async ({ query }) => `结果: ${query}`,
-}))
-
-const managerResult = ai.context.createManager({
-  scope: { objectId: 'user-001', sessionId: 'sess-001' },
-  rag: { enable: true, sources: ['docs'], topK: 5 },
-  reasoning: { enable: true, strategy: 'react', maxRounds: 5 },
-  tools: registry,
-})
-```
-
-### 列出对象的所有会话
-
-```ts
-const result = await ai.context.listSessions('user-001')
-if (result.success) {
-  for (const session of result.data) {
-    // session.sessionId / session.objectId / session.createdAt / session.updatedAt
-  }
-}
-```
-
----
-
-## 重排序 — `ai.rerank`
-
-对检索结果按查询相关性重新排序，提升 RAG / 检索质量。
-
-```ts
-// 快捷方式：文本列表重排序
-const result = await ai.rerank.rerankTexts('数据库配置方法', [
-  '本文介绍如何配置 PostgreSQL 连接池',
-  '前端组件的生命周期管理',
-  '数据库连接字符串的最佳实践',
-], 2) // topN: 返回前 2 个最相关的
-
-if (result.success) {
-  for (const item of result.data) {
-    // item.index — 原始位置
-    // item.relevanceScore — 相关性分数
-    // item.document — 原始文本
-  }
-}
-
-// 完整请求
-const result = await ai.rerank.rerank({
-  query: '配置方法',
-  documents: ['文档1', '文档2', '文档3'],
-  topN: 3,
-  returnDocuments: true,
-})
-```
-
----
-
-## 文件解析 — `ai.file`
-
-解析多种格式文件为文本内容，支持 OCR。
-
-```ts
-const result = await ai.file.parse({
-  content: fileBuffer, // Buffer | string
-  mimeType: 'application/pdf',
-  maxPages: 50,
-  outputFormat: 'markdown', // 'text' | 'markdown'
-  useOcr: false, // 使用 Vision LLM 做 OCR
-})
-
-if (result.success) {
-  // result.data.text — 解析出的文本内容
-  // result.data.pages — 页数（PDF 有效）
-  // result.data.metadata — 文件元信息
-}
-```
-
-**支持格式**：`text`（UTF-8）、`html`（HTML→text）、`pdf`（pdfjs-dist）、`docx`（mammoth）、`ocr`（Vision LLM）。
-
----
-
-## A2A — `ai.a2a`
-
-Agent-to-Agent 协议支持，实现代理间通信与任务委派。A2A 为延迟初始化子系统，需在配置中提供 `a2a` 配置段。
-
-### 配置
-
-```ts
-await ai.init({
-  llm: { model: 'gpt-4o-mini', apiKey: process.env.API_KEY },
-  a2a: {
-    agentCard: {
-      name: 'my-agent',
-      description: '智能助手',
-      url: 'https://agent.example.com',
-      skills: [{ id: 'chat', name: '对话', description: '通用对话能力' }],
-    },
-  },
-})
-```
-
-### 注册执行器并处理请求
-
-```ts
-import type { AgentExecutor } from '@h-ai/ai'
-
-// 实现执行器
-const executor: AgentExecutor = {
-  async* execute(context) {
-    // context.userMessage — 用户消息
-    // 处理任务并返回结果
-    yield { state: 'completed', message: { role: 'agent', parts: [{ type: 'text', text: '处理完成' }] } }
-  },
-}
-
-ai.a2a.registerExecutor(executor)
-
-// 在 API 端点中处理请求
-const result = await ai.a2a.handleRequest(requestBody)
-if (result.streaming) {
-  // result.stream — AsyncGenerator（流式响应）
-}
-else {
-  // result.body — JSON 响应
-}
-```
-
-### 调用远端代理
-
-```ts
-const result = await ai.a2a.callRemoteAgent(
-  'https://remote-agent.example.com',
-  '帮我分析这份季度报告',
-  { timeout: 30000 },
-)
-
-if (result.success) {
-  // result.data.taskId — 任务 ID
-  // result.data.taskState — 任务状态
-  // result.data.responseText — 回复文本
-}
-```
-
-### 查询消息记录
-
-```ts
-const messages = await ai.a2a.listMessages({
-  contextId: 'ctx-001',
-  limit: 20,
-})
-if (messages.success) {
-  // messages.data.items: A2AMessageRecord[]
-  // messages.data.total: number
-}
-```
-
----
-
-## MCP 服务器 — `createMcpServer`
-
-> 独立工厂函数，**不需要初始化**即可使用。
-
-### 创建服务器
-
-```ts
-import { createMcpServer, StreamableHTTPServerTransport } from '@h-ai/ai'
-import { z } from 'zod'
-
-const mcp = createMcpServer({ name: 'my-server', version: '1.0.0' })
-```
-
-### 注册工具
-
-```ts
-mcp.registerTool('search', {
-  description: '搜索文档',
-  inputSchema: { query: z.string(), limit: z.number().optional() },
-}, async ({ query, limit }) => ({
-  content: [{ type: 'text', text: `Found ${limit ?? 10} results for: ${query}` }],
-}))
-```
-
-### 注册资源
-
-```ts
-mcp.registerResource('config', 'config://app', {
-  description: '应用配置',
-}, async uri => ({
-  contents: [{ uri: uri.href, text: JSON.stringify(appConfig) }],
-}))
-```
-
-### 注册提示词
-
-```ts
-mcp.registerPrompt('summarize', {
-  description: '总结文本',
-  argsSchema: { text: z.string() },
-}, async ({ text }) => ({
-  messages: [{ role: 'user', content: { type: 'text', text: `请总结：${text}` } }],
-}))
-```
-
-### 连接传输层
-
-```ts
-import { randomUUID } from 'node:crypto'
-
-// Streamable HTTP（推荐）
-const transport = new StreamableHTTPServerTransport({
-  sessionIdGenerator: () => randomUUID(),
-})
-await mcp.connect(transport)
-
-// 其他传输层
-// import { SSEServerTransport, StdioServerTransport } from '@h-ai/ai'
-```
-
----
-
-## MCP 操作 — `ai.mcp`
-
-作为 MCP 客户端注册与调用工具、资源和提示词。
-
-```ts
-// 注册工具
-ai.mcp.registerTool(
-  { name: 'calc', description: '计算', inputSchema: { expr: { type: 'string' } } },
-  async ({ expr }) => ({ result: '2' }),
-)
-
-// 调用工具
-const result = await ai.mcp.callTool('calc', { expr: '1+1' })
-
-// 注册并读取资源
-ai.mcp.registerResource(
-  { uri: 'data://users', name: 'users', description: '用户列表' },
-  async () => ({ uri: 'data://users', text: JSON.stringify(users) }),
-)
-const resource = await ai.mcp.readResource('data://users')
-
-// 注册并获取提示词
-ai.mcp.registerPrompt(
-  { name: 'greet', arguments: [{ name: 'name', required: true }] },
-  async ({ name }) => [{ role: 'user', content: { type: 'text', text: `你好 ${name}` } }],
-)
-const prompt = await ai.mcp.getPrompt('greet', { name: '张三' })
-```
-
----
-
-## 前端客户端 — `createAIClient`
-
-> 浏览器端轻量客户端，通过 API 代理层与后端 AI 通信。
-
-```ts
-import { createAIClient } from '@h-ai/ai/client'
-import { api } from '@h-ai/api-client'
-
-await api.init({ baseUrl: '/api' })
-const client = createAIClient({ api })
-```
-
-### 非流式对话
-
-```ts
-const response = await client.chat({
-  messages: [{ role: 'user', content: '你好' }],
-})
-// response: ChatCompletionResponse（同服务端返回结构）
-```
-
-### 流式对话
-
-```ts
-for await (const chunk of client.chatStream({ messages }, {
-  onProgress: (progress) => {
-    // progress.content — 已累积的内容
-    // progress.done    — 是否结束
-    // progress.finishReason — 结束原因
-  },
-})) {
-  const delta = chunk.choices[0]?.delta?.content
-  if (delta) {
-    updateUI(delta)
-  }
-}
-```
-
-### 便捷方式
-
-```ts
-// 发送单条消息，返回回复文本
-const reply = await client.sendMessage('你好', '你是一个翻译助手')
-
-// 流式发送，返回完整回复文本
-const reply = await client.sendMessageStream('写一首诗', {
-  onProgress: p => updateUI(p.content),
-})
-```
-
-### 记忆与会话查询
-
-```ts
-// 检索相关记忆
-const memories = await client.recallMemories('用户偏好', {
-  topK: 5,
-  objectId: 'user-001',
-})
-
-// 分页列出记忆
-const page = await client.listMemories({
-  objectId: 'user-001',
-  offset: 0,
-  limit: 20,
-})
-// page.items: MemoryEntry[], page.total: number
-
-// 列出某对象的所有会话
-const sessions = await client.listSessions('user-001')
-// sessions: SessionInfo[]
-```
-
----
-
-## 错误处理
-
-所有需要初始化的子系统方法均返回 `HaiResult<T>`，通过 `result.success` 判断成功/失败。
-
-```ts
-import { HaiAIError } from '@h-ai/ai'
-
-const result = await ai.llm.chat({ messages })
-
-if (!result.success) {
-  switch (result.error.code) {
-    case HaiAIError.NOT_INITIALIZED.code:
-      // 未初始化，请先调用 ai.init()
-      break
-    case HaiAIError.RATE_LIMITED.code:
-      // API 限流，稍后重试
-      break
-    case HaiAIError.TIMEOUT.code:
-      // 请求超时
-      break
-    case HaiAIError.CONTEXT_LENGTH_EXCEEDED.code:
-      // 上下文超长，需压缩消息
-      break
-    case HaiAIError.MEMORY_RECALL_FAILED.code:
-      // 记忆检索失败
-      break
-    case HaiAIError.CONTEXT_COMPRESS_FAILED.code:
-      // 上下文压缩失败
-      break
-    default:
-      // 通用错误
-      break
-  }
-}
-```
-
----
-
-## 设计说明
-
-### 架构概览
-
-AI 是**生命周期单例**模块，通过 `ai.init()` / `ai.close()` 管理运行时状态。内部由 17 个子模块构成，通过 getter 暴露给调用方。
-
-```
-ai.init(config?, options?)
-  ├─ 配置校验（Zod schema）
-  ├─ 存储 Provider 解析
-  │   ├─ options.storeProvider → 使用自定义 Provider
-  │   └─ 未提供 → 检查 reldb + vecdb 已初始化 → 创建默认 DB Provider
-  ├─ createAISubsystems() — 按依赖创建所有子模块
-  │   ├─ LLM Provider（OpenAI 兼容，多模型场景映射）
-  │   ├─ MCP（工具/资源/提示词注册表）
-  │   ├─ Embedding（文本向量化）
-  │   ├─ Token（Token 估算）
-  │   ├─ Summary（消息摘要）
-  │   ├─ Compress（上下文压缩）
-  │   ├─ Memory（记忆提取/存储/检索）
-  │   ├─ Rerank（结果重排序）
-  │   ├─ Retrieval（多源向量检索）
-  │   ├─ RAG（检索增强问答）
-  │   ├─ Knowledge（知识库管理）
-  │   ├─ Reasoning（推理引擎）
-  │   ├─ Context（有状态上下文管理器）
-  │   ├─ File（文件解析）
-  │   └─ A2A（Agent-to-Agent，延迟初始化）
-  └─ StoreProvider.setupAll()（建表/建连接）
-```
-
-初始化前访问任何需要 init 的子模块方法，均返回 `NOT_INITIALIZED` 错误（基于 `NotInitializedKit` Proxy）。`ai.tools` 和 `ai.stream` 为纯函数，**无需初始化**。
-
-### 数据存储分布
-
-> 下表为默认 DB Provider（reldb + vecdb）的存储映射。自定义 `AIStoreProvider` 可对接其他存储后端。
-
-| 数据类型   | 存储位置   | 表/集合名                                 |
-| ---------- | ---------- | ----------------------------------------- |
-| 对话记录   | DB         | `hai_ai_chat_records`                     |
-| 会话元数据 | DB         | `hai_ai_sessions`                         |
-| 检索源配置 | DB         | `hai_ai_retrieval_sources`                |
-| 记忆条目   | DB + VecDB | `hai_ai_memory` + `hai_ai_memory_vectors` |
-| 上下文状态 | DB         | `hai_ai_context`                          |
-| 知识库内容 | VecDB      | `hai_ai_knowledge`（可配置）              |
-
-### 多模型场景映射
-
-通过 `llm.models` 注册多个模型，通过 `llm.scenarios` 将不同使用场景映射到对应模型：
-
-```ts
-await ai.init({
-  llm: {
-    model: 'gpt-4o-mini', // 默认模型
-    models: [
-      { id: 'fast', model: 'gpt-4o-mini', temperature: 0.3 },
-      { id: 'strong', model: 'gpt-4o', maxTokens: 8192 },
-      { id: 'embed', model: 'text-embedding-3-small' },
-    ],
-    scenarios: {
-      default: 'fast',
-      chat: 'fast',
-      reasoning: 'strong',
-      embedding: 'embed',
-      summary: 'fast',
-      extraction: 'fast',
-      rerank: 'fast',
-      ocr: 'strong',
-    },
-  },
-})
-```
-
-各子模块自动使用对应场景的模型：
-
-- `ai.llm.chat()`：`scenarios.chat` → `scenarios.default` → `llm.model`
-- `ai.embedding.embed()`：`scenarios.embedding` → `llm.model`
-- `ai.reasoning.run()`：`scenarios.reasoning` → `llm.model`
-- `ai.summary.summarize()`：`scenarios.summary` → `llm.model`
-- `ai.rerank.rerank()`：`scenarios.rerank` → `llm.model`
-
-### Provider 模式
-
-#### LLM Provider
-
-当前内置 **OpenAI 兼容** Provider（`ai-llm-provider-openai.ts`），支持所有 OpenAI API 兼容服务（OpenAI、Azure OpenAI、Ollama、vLLM 等）：
-
-- API Key 解析顺序：模型条目 > 全局配置 > 环境变量（`HAI_AI_LLM_API_KEY` / `OPENAI_API_KEY`）
-- Base URL 解析顺序：模型条目 > 全局配置 > 环境变量（`HAI_AI_LLM_BASE_URL` / `OPENAI_BASE_URL`）> OpenAI 默认
-
-#### Store Provider
-
-存储层通过 `AIStoreProvider` 接口抽象，所有需要持久化的子系统（Memory / Knowledge / Context / Retrieval / A2A 等）统一通过此接口存取数据：
-
-```ts
-interface AIStoreProvider {
-  readonly name: string
-  createRelStore: <T>(name: string, options?: AIRelStoreOptions) => AIRelStore<T>
-  createVectorStore: (name: string) => AIVectorStore
-  createKnowledgeStore?: () => KnowledgeStore
-  setupAll: () => Promise<void>
-}
-```
-
-- **默认 DB Provider**：基于 `@h-ai/reldb` + `@h-ai/vecdb`，未传入自定义 Provider 时自动使用
-- **自定义 Provider**：通过 `ai.init(config, { storeProvider })` 注入，可对接 SaaS API、其他数据库等
-
-### 上下文管理编排
-
-`ai.context.createManager()` 创建的 ContextManager 是最上层的编排器，一次 `chat()` 调用的内部流程：
-
-```
-manager.chat(query)
-  ├─ 记忆注入（memory.injectMemories → 从 VecDB 召回相关记忆追加到 system）
-  ├─ RAG 检索（retrieval.retrieve → 从知识库检索相关片段注入上下文）
-  ├─ 上下文压缩（compress.tryCompress → 超限时自动压缩旧消息）
-  ├─ 推理引擎（reasoning.run → CoT/ReAct/Plan-Execute）或 LLM 直接调用
-  ├─ 工具调用循环（tools 注册表 → 自动执行并续接）
-  ├─ 记忆提取（memory.extract → 从新对话中提取事实/偏好/实体等）
-  └─ 持久化（save → 消息和摘要写入 DB）
-```
-
----
-
-## 典型场景
-
-### 带工具调用的多轮对话循环
-
-```ts
-import type { ChatMessage } from '@h-ai/ai'
-import { ai } from '@h-ai/ai'
-import { z } from 'zod'
-
-// 定义并注册工具
-const weatherTool = ai.tools.define({
-  name: 'get_weather',
-  description: '获取天气',
-  parameters: z.object({ city: z.string() }),
-  handler: async ({ city }) => ({ temp: 22, city, condition: '晴' }),
-})
-
-const registry = ai.tools.createRegistry()
-registry.register(weatherTool)
-
-const messages: ChatMessage[] = [
-  { role: 'user', content: '北京和上海今天天气怎么样？' },
-]
-
-// 对话循环
-let result = await ai.llm.chat({
-  messages,
-  tools: registry.getDefinitions(),
-})
-
-while (result.success && result.data.choices[0].finish_reason === 'tool_calls') {
-  const assistantMsg = result.data.choices[0].message
-  messages.push(assistantMsg)
-
-  const toolResults = await registry.executeAll(assistantMsg.tool_calls!, { parallel: true })
-  if (toolResults.success) {
-    messages.push(...toolResults.data)
-  }
-
-  result = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
-}
-
-if (result.success) {
-  const finalAnswer = result.data.choices[0].message.content
-}
-```
-
-### 记忆增强的长期对话
-
-```ts
-import type { ChatMessage } from '@h-ai/ai'
-import { ai } from '@h-ai/ai'
-
-await ai.init({
-  llm: { model: 'gpt-4o-mini', apiKey: process.env.API_KEY },
-  memory: { maxEntries: 500, embeddingEnabled: true },
-  compress: { defaultStrategy: 'hybrid', preserveLastN: 6 },
-})
-
-const messages: ChatMessage[] = [
-  { role: 'system', content: '你是用户的私人助手，请记住用户的偏好。' },
-]
-
-async function chat(userInput: string): Promise<string | undefined> {
-  messages.push({ role: 'user', content: userInput })
-
-  // 1. 注入历史记忆
-  const enriched = await ai.memory.injectMemories(messages, {
-    topK: 5,
-    position: 'system',
-    maxTokens: 500,
-  })
-  const enrichedMessages = enriched.success ? enriched.data : messages
-
-  // 2. 压缩上下文以适应模型限制
-  const compressed = await ai.compress.tryCompress(enrichedMessages, {
-    maxTokens: 4000,
-    strategy: 'hybrid',
-  })
-  const finalMessages = compressed.success ? compressed.data.messages : enrichedMessages
-
-  // 3. 调用 LLM
-  const result = await ai.llm.chat({ messages: finalMessages })
-  if (!result.success)
-    return undefined
-
-  const reply = result.data.choices[0].message
-  messages.push(reply)
-
-  // 4. 异步提取新记忆（不阻塞响应）
-  ai.memory.extract(messages.slice(-2), { objectId: 'chat' })
-
-  return reply.content ?? undefined
-}
-```
-
-### 知识库 + RAG 完整流程
-
-```ts
-import { ai } from '@h-ai/ai'
-
-// 初始化（默认 DB Provider 需要 vecdb + reldb）
-await ai.init({
-  llm: { model: 'gpt-4o-mini', apiKey: process.env.API_KEY },
-  embedding: { model: 'text-embedding-3-small' },
-  knowledge: {
-    enableEntityExtraction: true,
-    cleanOptions: { removeHtml: true },
-    chunkOptions: { mode: 'markdown', maxSize: 1500, overlap: 200 },
-  },
-})
-
-// 1. 初始化知识库
-await ai.knowledge.setup()
-
-// 2. 批量导入文档
-const documents = [
-  { id: 'doc-1', content: '# 产品架构\n...', title: '架构文档' },
-  { id: 'doc-2', content: '# 部署指南\n...', title: '部署文档' },
-]
-
-for (const doc of documents) {
-  const result = await ai.knowledge.ingest({
-    documentId: doc.id,
-    content: doc.content,
-    title: doc.title,
-    enableEntityExtraction: true,
-  })
-}
-
-// 3. 知识问答
-const answer = await ai.knowledge.ask('项目的部署流程是什么？', {
-  topK: 5,
-  enableEntityBoost: true,
-  systemPrompt: '基于文档准确回答，标注引用来源。',
-})
-
-if (answer.success) {
-  // answer.data.answer — LLM 回答
-  // answer.data.citations — 引用列表
-}
-```
-
-### 有状态上下文管理器 + 流式输出
-
-```ts
-import { ai } from '@h-ai/ai'
-
-await ai.init({
-  llm: { model: 'gpt-4o-mini', apiKey: process.env.API_KEY },
-  compress: { defaultStrategy: 'hybrid', preserveLastN: 6 },
-})
-
-// 创建管理器（使用嵌套 compress 配置）
-const managerResult = ai.context.createManager({
-  compress: { maxTokens: 8000, auto: true },
-  memory: { enable: true, enableExtract: true },
-})
-if (!managerResult.success)
-  return
-const manager = managerResult.data
-
-// 方式一：直接使用 chatStream（推荐，自动编排）
-for await (const event of manager.chatStream('你好')) {
-  if (event.type === 'delta')
-    process.stdout.write(event.text)
-  if (event.type === 'done')
-    console.warn('\n完成，模型:', event.model)
-}
-
-// 方式二：手动编排
-async function streamChat(userInput: string): Promise<string> {
-  await manager.addMessage({ role: 'user', content: userInput })
-
-  const msgs = manager.getMessages()
-  if (!msgs.success)
-    return ''
-
-  const processor = ai.stream.createProcessor()
-  for await (const chunk of ai.llm.chatStream({ messages: msgs.data })) {
-    const delta = processor.process(chunk)
-    if (delta?.content) {
-      process.stdout.write(delta.content)
-    }
-  }
-
-  const assistantMsg = processor.toAssistantMessage()
-  await manager.addMessage(assistantMsg)
-  return assistantMsg.content ?? ''
-}
-```
-
-### A2A 代理协作
-
-```ts
-import type { AgentExecutor } from '@h-ai/ai'
-import { ai } from '@h-ai/ai'
-
-await ai.init({
-  llm: { model: 'gpt-4o-mini', apiKey: process.env.API_KEY },
-  a2a: {
-    agentCard: {
-      name: 'coordinator',
-      description: '协调代理，分发任务给专业代理',
-      url: 'https://coordinator.example.com',
-      skills: [{ id: 'coordinate', name: '任务协调', description: '分析任务并委派给合适的代理' }],
-    },
-  },
-})
-
-// 注册本地执行器
-const executor: AgentExecutor = {
-  async* execute(context) {
-    // 委派子任务给远端专业代理
-    const analysis = await ai.a2a.callRemoteAgent(
-      'https://analyst.example.com',
-      context.userMessage,
-      { timeout: 60000 },
-    )
-    if (analysis.success) {
-      yield {
-        state: 'completed',
-        message: {
-          role: 'agent',
-          parts: [{ type: 'text', text: `分析结果：${analysis.data.responseText}` }],
-        },
-      }
-    }
-  },
-}
-ai.a2a.registerExecutor(executor)
-```
-
----
-
-## 测试
-
-```bash
-pnpm --filter @h-ai/ai test
-```
+源码 JSDoc 的公开示例从实际包入口导入，内部工厂示例标记“模块内部上下文”，分别按真实声明编译。根目录执行 `pnpm check:jsdoc --package ai` 核验覆盖与示例类型；普通业务方法检查 HaiResult，流式与浏览器 AudioClient 保留显式抛错契约。
 
-## License
+## 许可证
 
 Apache-2.0