@h-ai/ai 0.1.0-alpha.34 → 0.1.0-alpha.35

package/README.md

@@ -1,6 +1,6 @@
 # @h-ai/ai
 
-AI 能力模块，提供统一的 `ai` 服务对象，覆盖 LLM 对话、工具调用、MCP、Embedding、记忆、检索/RAG、知识库、上下文管理、文件解析、Rerank 与 A2A。Node.js 侧通过 `ai.init()` 初始化，浏览器侧通过 API/client 代理访问。
+AI 能力模块，提供统一的 `ai` 服务对象，覆盖 LLM 对话、工具调用、MCP、Embedding、记忆、检索/RAG、知识库、上下文管理、文件解析、Rerank、语音（ASR/TTS）与 A2A。Node.js 侧通过 `ai.init()` 初始化，浏览器侧通过 API/client 代理访问。
 
 ## 能力概览
 
@@ -10,10 +10,12 @@ AI 能力模块，提供统一的 `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.a2a`：Agent-to-Agent 请求处理与远端调用。
 - `@h-ai/ai/client`：前端轻量客户端（配合 API 服务）。
 - `AIStoreProvider`：统一存储抽象；默认 DB Provider 基于 reldb + vecdb。
@@ -155,6 +157,49 @@ if (setup.success) {
 }
 ```
 
+### 语音（Audio）
+
+先在 `ai.init()` 中注册语音模型并映射默认识别/合成模型（凭据可回退到平台环境变量）：
+
+```ts
+await ai.init({
+  audio: {
+    models: [
+      { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime' },
+      { id: 'tts', provider: 'qwen', model: 'qwen3-tts-flash-realtime' },
+    ],
+    transcribeModel: 'asr',
+    synthesizeModel: 'tts',
+  },
+})
+
+// 完整识别（可选热词提示提升专有名词识别率）
+const result = await ai.audio.transcribe({ audio: { data: wavBytes, format: 'wav' }, language: 'zh', contextHints: ['专有名词'] })
+if (result.success) {
+  const text = result.data.text
+}
+
+// 实时识别（持续音频输入 → 领域事件流：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)
+}
+
+// 流式合成：可带自然语言风格指令，并直接连接 LLM 文本流边生成边合成；signal 可随时打断
+const controller = new AbortController()
+for await (const audio of ai.audio.synthesizeStream({ text: ai.llm.askStream(question), voice: 'Cherry', instruction: '用轻快的语气', signal: controller.signal })) {
+  await player.write(audio)
+}
+```
+
+取消/超时/连接错误统一为领域错误：`AbortSignal` 触发 → `AUDIO_CANCELLED`（超时 → `AUDIO_TIMEOUT`），连接失败 → `AUDIO_CONNECTION_FAILED`。实时连接时长受 `audio.maxStreamDurationMs`（默认 5 分钟）限制。
+
+浏览器 / 移动端通过 `@h-ai/serv` 暴露的统一语音 WebSocket 入口访问，`@h-ai/ai/client` 提供与 Node 端一致的 `audio.*` API（传输细节内部隐藏）。
+
 ### Context 管理器
 
 ```ts
@@ -169,7 +214,72 @@ if (manager.success) {
 }
 ```
 
-## 配置
+#### 真实对话状态（Conversation Commit Layer）
+
+默认（`turnCommit: 'auto'`）下，`chat` / `chatStream` 会把**模型生成的完整文本**写入上下文。但在「模型生成 → TTS 合成 → 实际播放」链路中，AI 可能说到一半就被打断——此时进入下一轮所有参与者可见的对话状态，应当是**实际播放出去的部分**，而非模型本想说完的全文。
+
+设置 `turnCommit: 'manual'` 后，生成结果不会自动写入上下文，而是返回一个 `turnId`；由调用方在确定「实际发生了什么」后显式提交真实文本：
+
+```ts
+const m = ai.context.createManager({ turnCommit: 'manual' /* ... */ }).data
+
+for await (const ev of m.chatStream('请展开讲讲')) {
+  if (ev.type === 'delta') {
+    feedTts(ev.text)
+  } // 边生成边合成播放
+  else if (ev.type === 'done') {
+    m.markTurnSpeaking(ev.turnId) // 可选：标记进入播放
+    if (interrupted)
+      await m.interruptTurn(ev.turnId, { text: actuallySpokenText }) // 只提交播放出去的部分
+    else
+      await m.commitTurn(ev.turnId) // 完整提交
+  }
+}
+
+// 观测每一轮的 generated / committed / status
+const turns = m.getTurns()
+```
+
+- `commitTurn(turnId, { text? })` — 提交真实文本（缺省用完整生成文本），状态转 `completed`。
+- `interruptTurn(turnId, { text? })` — 只写入实际表达出去的部分（缺省视为未表达，不写入），状态转 `interrupted`。
+- 只有 `committed` 的内容进入上下文与记忆提取；未提交/被打断丢弃的部分不会污染后续轮次。
+
+#### 会话固化（Memory 生命周期）
+
+会话进行中，每轮对话按 `scope: { sessionId }` 提取**短期会话记忆**；会话结束时用 `consolidate()`
+把「短期记忆 + 摘要」沉淀为**跨会话长期记忆**，形成 `Session Memory → Summary → Long-term Memory` 闭环：
+
+```ts
+// 会话结束时固化：整合摘要 → 提取长期记忆（写入不含 sessionId 的持久作用域）
+const result = await manager.consolidate({ scope: { userId: 'user-001', personaId: 'xiaoq' } })
+if (result.success) {
+  // result.data.summary  —— 本次会话整合摘要
+  // result.data.memories —— 固化到长期记忆的条目
+}
+```
+
+### Persona（AI 角色人格）
+
+Memory 用 `objectId` / `scope` 回答「谁的记忆」；Persona 回答「AI 是谁」——为每个 AI 角色定义
+稳定的系统提示词与性格特征，并通过 `scope: { personaId }` 关联其长期记忆：
+
+```ts
+await ai.persona.save({
+  id: 'xiaoq',
+  name: '小Q',
+  systemPrompt: '你是一位经济学家，善于从长期视角分析问题。',
+  traits: ['数据驱动', '偏好引用真实案例'],
+})
+
+// 组合出可直接喂给 ContextManager 的系统提示词（systemPrompt + traits）
+const composed = await ai.persona.compose('xiaoq')
+const manager = ai.context.createManager({
+  systemPrompt: composed.data,
+  memory: { enable: true, enableExtract: true, scope: { personaId: 'xiaoq' } },
+})
+```
+
+`ai.persona` 提供 `save` / `get` / `update` / `remove` / `list` / `compose`；角色档案全局共享（不按 `objectId` 隔离）。
 
 ```yaml
 llm:
@@ -210,6 +320,7 @@ memory:
   recencyDecay: 0.95
   embeddingEnabled: true
   defaultTopK: 10
+  candidateMultiplier: 5 # 候选池倍数：先取回 topK×倍数 条候选，再按 scope/重要性过滤，最后截取 topK
   writebackRelatedTopK: 20
 ```
 
@@ -221,11 +332,22 @@ memory:
   defaultTopK: 10
 ```
 
-- **`native`（默认，推荐）**：HAI 原生引擎，复用同一套 vecdb（向量库）、reldb（关系库）、LLM 与 Embedding。`extract` 采用 **Mem0 式批量合并**——一次 LLM 调用对整批抽取事实与相关既有记忆做 ADD / UPDATE / DELETE / NONE 决策，实现增量更新、跨条去重与矛盾删除，并支持 `category` 主题标签。`maxEntriesPerObject`、`maxEntriesGlobal`、`recencyDecay`、`embeddingEnabled`、`writebackRelatedTopK` 均作用于此后端；淘汰按 `objectId` 分区触发，不会因某一主体写入过多而淘汰其他主体的记忆。
+- **`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` 配置提取（OpenAI 兼容，走 `baseUrl` / `apiKey` / 场景模型）；向量库从底层 vecdb 后端提取——`qdrant` / `pgvector` 直接复用同一后端，`lancedb` / `chroma`（mem0 TS 不支持）则退回 mem0 自带的 in-memory 存储。历史记录默认禁用。需安装 `mem0ai`（已内置为依赖）；复用 qdrant/pgvector 时需对应客户端。
 
 两个 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 后端在 `update` 涉及 type/importance/metadata 时会重建记忆并重新分配 `id`（native 后端保持 id 稳定）。
 
+**候选池与 scope 漏召回**：`scope` 过滤在内存中完成，若先按 `topK` 截断再过滤，同一主体下相关度较高的其它主题/角色记忆会把目标 scope 的记忆挤出候选池，导致「明明有却召回 0 条」。为此 `recall` / `injectMemories` 先取回 `topK × candidateMultiplier`（默认 5）条候选，过滤后再截取 `topK`。scope 隔离越细（如按 `topicId` + `personaId`），可将 `candidateMultiplier` 调大：
+
+```ts
+const memories = await ai.memory.recall('经济发展', {
+  objectId: 'user-001',
+  scope: { topicId: 'C' },
+  topK: 10,
+  candidateMultiplier: 8, // 覆盖配置默认值，扩大候选池
+})
+```
+
 `ai.config` 返回脱敏后的配置快照；`apiKey`、`privateKey`、URL 内嵌凭证等敏感字段不会原样暴露。
 
 ## 错误处理

package/dist/{ai-types-BZjo_rWW.d.ts → ai-audio-ws-protocol-C-V8N8YL.d.ts}

@@ -1,6 +1,6 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult } from '@h-ai/core';
-import { aj as ChatMessage, at as InteractionScope, v as MemoryType, b0 as RagOptions, b4 as ReasoningOptions, bx as ToolRegistryOperations, bh as SessionInfo, aL as LLMOperations, aU as MemoryOperations, a$ as RagOperations, b3 as ReasoningOperations, c as AIConfig, d as AIConfigInput, a8 as AIStoreProvider, by as ToolsOperations, bl as StreamOperations, ba as RetrievalOperations, aF as KnowledgeOperations, a2 as A2AOperations } from './ai-reasoning-types-Cm3-HVVN.js';
+import { aC as ChatMessage, aN as InteractionScope, J as MemoryType, bk as RagOptions, bo as ReasoningOptions, bR as ToolRegistryOperations, b6 as MemoryEntry, bB as SessionInfo, b3 as LLMOperations, bc as MemoryOperations, bj as RagOperations, bn as ReasoningOperations, c as AIConfig, d as AIConfigInput, ar as AIStoreProvider, bS as ToolsOperations, bF as StreamOperations, bu as RetrievalOperations, aZ as KnowledgeOperations, al as A2AOperations, o as AudioOperations, k as AudioFormat } from './ai-reasoning-types-BGf-x2Qj.js';
 import { z } from 'zod';
 import { Buffer } from 'node:buffer';
 
@@ -177,6 +177,82 @@ interface ContextDeps {
     rag?: RagOperations;
     /** Reasoning 操作（推理引擎需要） */
     reasoning?: ReasoningOperations;
+    /** Summary 操作（会话固化 consolidate 需要） */
+    summary?: SummaryOperations;
+}
+/**
+ * 会话固化选项（`ContextManager.consolidate` 使用）
+ *
+ * 把「短期会话记忆 + 摘要」固化为「长期记忆」，形成
+ * `Session Memory → Summary → Long-term Memory` 的生命周期闭环。
+ */
+interface ConsolidateOptions {
+    /**
+     * 长期记忆作用域。
+     *
+     * 默认使用管理器 `memory.scope`。通常应传入**不含 sessionId** 的作用域
+     * （如 `{ userId, personaId }`），使固化后的记忆跨会话持久，而非绑定单次会话。
+     */
+    scope?: Record<string, unknown>;
+    /** 固化提取的记忆类型限制 */
+    types?: MemoryType[];
+    /** 摘要 / 提取使用的模型 */
+    model?: string;
+    /** 固化提取的自定义 systemPrompt */
+    extractionSystemPrompt?: string;
+}
+/**
+ * 会话固化结果
+ */
+interface ConsolidateResult {
+    /** 本次会话的整合摘要 */
+    summary: string;
+    /** 固化到长期记忆的条目 */
+    memories: MemoryEntry[];
+}
+/**
+ * 对话轮次状态
+ *
+ * 描述一次 assistant 生成从「模型产出」到「真实进入对话」的生命周期：
+ * - `generating` — 模型正在/已生成，但尚未确定实际对外表达的内容
+ * - `speaking` — 已进入下游表达（如 TTS 合成 / 播放）
+ * - `completed` — 已提交，完整生成文本即为真实文本
+ * - `interrupted` — 被打断，仅实际表达出去的部分（committed）进入对话
+ */
+type ConversationTurnStatus = 'generating' | 'speaking' | 'completed' | 'interrupted';
+/**
+ * 对话轮次
+ *
+ * 区分「模型生成的文本」与「真实进入对话的文本」，解决多智能体 / 语音访谈等场景中
+ * 「AI 说到一半被打断，下一轮所有参与者应看到真实发生了什么」的问题。
+ */
+interface ConversationTurn {
+    /** 轮次唯一标识 */
+    id: string;
+    /** 发言者 */
+    speaker: 'user' | 'assistant';
+    /** 模型生成的完整文本 */
+    generated: string;
+    /** 实际提交进入上下文的文本（`completed` 时通常等于 generated；`interrupted` 时为真实表达部分） */
+    committed: string;
+    /** 轮次状态 */
+    status: ConversationTurnStatus;
+    /** 创建时间（Unix 毫秒） */
+    createdAt: number;
+    /** 提交时间（Unix 毫秒，未提交时为 undefined） */
+    committedAt?: number;
+}
+/**
+ * 提交 / 打断轮次的输入
+ */
+interface CommitTurnInput {
+    /**
+     * 实际进入对话的文本。
+     *
+     * - `commitTurn` 不传时默认使用模型生成的完整文本（generated）。
+     * - `interruptTurn` 不传时默认视为「未表达任何内容」（空串，不写入上下文）。
+     */
+    text?: string;
 }
 /**
  * 有状态上下文管理器配置
@@ -192,6 +268,17 @@ interface ContextManagerOptions {
     model?: string;
     /** 温度覆盖 */
     temperature?: number;
+    /**
+     * 对话提交模式（默认 `auto`）
+     *
+     * - `auto`：`chat` / `chatStream` 生成结束后，自动把**模型生成的完整文本**写入上下文并触发记忆提取。
+     * - `manual`：生成结束后**不写入**上下文，仅登记一个待提交轮次并返回 `turnId`；由调用方在确定
+     *   「实际发生了什么」后，通过 `commitTurn` / `interruptTurn` 写入**真实文本**。
+     *
+     * 用于「模型生成 → TTS 合成 → 实际播放」链路：AI 说到一半被打断时，只有真正播放出去的
+     * 部分才应进入下一轮所有参与者可见的对话状态，而不是模型本想说完的全文。
+     */
+    turnCommit?: 'auto' | 'manual';
     /**
      * 压缩配置（覆盖全局 compress 配置）
      *
@@ -284,6 +371,13 @@ interface ContextChatResult {
     reply: string;
     /** 使用的模型 */
     model: string;
+    /**
+     * 本次生成对应的对话轮次 ID
+     *
+     * `turnCommit: 'manual'` 时，用于后续 `commitTurn` / `interruptTurn` 提交真实文本；
+     * `auto` 模式下该轮已自动提交（`completed`）。
+     */
+    turnId: string;
     /** Token 使用统计 */
     usage?: {
         prompt_tokens: number;
@@ -310,6 +404,7 @@ type ContextStreamEvent = {
     type: 'done';
     reply: string;
     model: string;
+    turnId: string;
     usage?: {
         prompt_tokens: number;
         completion_tokens: number;
@@ -404,6 +499,57 @@ interface ContextManager {
      * 重置管理器（清空所有消息和摘要）
      */
     reset: () => void;
+    /**
+     * 获取对话轮次列表（Conversation Commit Layer）
+     *
+     * 记录每次 chat/chatStream 生成的轮次及其 `generated` / `committed` / `status`，
+     * 供应用侧观测「模型生成」与「真实进入对话」的差异。
+     *
+     * @returns 轮次列表（按发生顺序）
+     */
+    getTurns: () => HaiResult<ConversationTurn[]>;
+    /**
+     * 标记某轮次进入「表达中」（如 TTS 开始播放）
+     *
+     * 仅更新状态用于观测，不改变上下文内容。
+     *
+     * @param turnId - 轮次 ID
+     * @returns 成功返回 ok(undefined)；轮次不存在返回 CONTEXT_TURN_NOT_FOUND
+     */
+    markTurnSpeaking: (turnId: string) => HaiResult<void>;
+    /**
+     * 提交轮次（`turnCommit: 'manual'` 场景）
+     *
+     * 把真实文本写入上下文并触发记忆提取；`text` 缺省时使用模型生成的完整文本。
+     * 提交后该轮 `status` 变为 `completed`。
+     *
+     * @param turnId - 轮次 ID
+     * @param input - 提交内容（可覆盖为真实表达文本）
+     * @returns 成功返回 ok(undefined)；轮次不存在或已提交返回对应错误
+     */
+    commitTurn: (turnId: string, input?: CommitTurnInput) => Promise<HaiResult<void>>;
+    /**
+     * 打断轮次（`turnCommit: 'manual'` 场景）
+     *
+     * 只把「实际表达出去的部分」写入上下文；`text` 缺省时视为未表达任何内容（不写入）。
+     * 打断后该轮 `status` 变为 `interrupted`。
+     *
+     * @param turnId - 轮次 ID
+     * @param input - 实际表达出去的文本
+     * @returns 成功返回 ok(undefined)；轮次不存在或已提交返回对应错误
+     */
+    interruptTurn: (turnId: string, input?: CommitTurnInput) => Promise<HaiResult<void>>;
+    /**
+     * 将当前会话固化为长期记忆（Memory 生命周期）
+     *
+     * 流程：整合会话摘要（历史摘要 + 当前消息）→ 从摘要中提取长期记忆 → 以持久作用域写入。
+     * 需要 deps.summary + deps.memory 可用。用于会话结束时把「短期会话记忆」沉淀为
+     * 「跨会话长期记忆」，形成 Session → Summary → Long-term Memory 闭环。
+     *
+     * @param options - 固化选项（长期作用域、类型、模型等）
+     * @returns 会话摘要与固化的记忆条目
+     */
+    consolidate: (options?: ConsolidateOptions) => Promise<HaiResult<ConsolidateResult>>;
     /**
      * 发送消息并获取回复（需 deps.llm 可用）
      *
@@ -841,6 +987,164 @@ interface AIMCPFunctionsDeps {
     config: AIConfig;
 }
 
+/**
+ * @h-ai/ai — Persona 子功能类型
+ *
+ * 定义「AI 角色人格」的持久化与组合接口。Persona 解决的是「AI 是谁」的问题：
+ * 多智能体场景（如多位专家同台访谈）中，每个 AI 有稳定的系统提示词、性格特征与
+ * 长期人格。它与 Memory 正交——Memory 用 `objectId` / `scope` 回答「谁的记忆」，
+ * Persona 回答「这个 AI 的身份与人设」，二者通过 `scope: { personaId }` 关联。
+ * @module ai-persona-types
+ */
+
+/**
+ * Persona 档案输入（创建 / 覆盖保存时使用）
+ *
+ * @example
+ * ```ts
+ * const input: PersonaProfileInput = {
+ *   id: 'xiaop',
+ *   name: '小P',
+ *   systemPrompt: '你是一位社会学家，善于从群体行为视角分析问题。',
+ *   traits: ['谨慎', '喜欢引用真实案例'],
+ * }
+ * ```
+ */
+interface PersonaProfileInput {
+    /** 角色唯一标识（业务侧稳定 ID，如 `xiaop`） */
+    id: string;
+    /**
+     * 所属主体 ID（多租户隔离）
+     *
+     * 不同主体可创建同名角色而互不覆盖；不传时归为平台内置角色 `system`。
+     */
+    objectId?: string;
+    /** 角色显示名（如「小P」） */
+    name?: string;
+    /** 角色系统提示词（定义身份、职责、语气） */
+    systemPrompt: string;
+    /** 性格 / 风格特征（组合进系统提示词，如「谨慎」「喜欢引用案例」） */
+    traits?: string[];
+    /** 附加元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 完整的 Persona 档案
+ */
+interface PersonaProfile {
+    /** 角色唯一标识 */
+    id: string;
+    /** 所属主体 ID（多租户隔离；平台内置角色为 `system`） */
+    objectId: string;
+    /** 角色显示名 */
+    name?: string;
+    /** 角色系统提示词 */
+    systemPrompt: string;
+    /** 性格 / 风格特征 */
+    traits: string[];
+    /** 附加元数据 */
+    metadata?: Record<string, unknown>;
+    /** 创建时间（Unix 毫秒） */
+    createdAt: number;
+    /** 更新时间（Unix 毫秒） */
+    updatedAt: number;
+}
+/**
+ * Persona 档案更新输入
+ *
+ * 所有字段可选，仅更新传入的字段。
+ */
+interface PersonaProfileUpdate {
+    /** 更新显示名 */
+    name?: string;
+    /** 更新系统提示词 */
+    systemPrompt?: string;
+    /** 更新特征列表（整体替换） */
+    traits?: string[];
+    /** 更新元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Persona 操作接口（通过 `ai.persona` 访问）
+ *
+ * 管理 AI 角色人格的持久化与系统提示词组合。需要先调用 `ai.init()` 初始化后使用。
+ *
+ * @example
+ * ```ts
+ * // 定义一个 AI 角色
+ * await ai.persona.save({
+ *   id: 'xiaoq',
+ *   name: '小Q',
+ *   systemPrompt: '你是一位经济学家。',
+ *   traits: ['数据驱动', '偏好长期视角'],
+ * })
+ *
+ * // 组合出可直接喂给 ContextManager 的系统提示词
+ * const composed = await ai.persona.compose('xiaoq')
+ * const manager = ai.context.createManager({
+ *   systemPrompt: composed.data,
+ *   // 该角色的长期记忆用 scope 关联
+ *   memory: { enable: true, enableExtract: true, scope: { personaId: 'xiaoq' } },
+ * })
+ * ```
+ */
+interface PersonaOperations {
+    /**
+     * 创建或覆盖保存一个角色档案（upsert 语义）
+     *
+     * @param profile - 角色档案输入
+     * @returns 保存后的完整档案
+     */
+    save: (profile: PersonaProfileInput) => Promise<HaiResult<PersonaProfile>>;
+    /**
+     * 按 ID 获取角色档案
+     *
+     * @param id - 角色 ID
+     * @returns 角色档案，不存在时返回 PERSONA_NOT_FOUND
+     */
+    get: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile>>;
+    /**
+     * 更新角色档案（仅更新传入字段）
+     *
+     * @param id - 角色 ID
+     * @param updates - 需要更新的字段
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 更新后的完整档案
+     */
+    update: (id: string, updates: PersonaProfileUpdate, options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile>>;
+    /**
+     * 删除角色档案
+     *
+     * @param id - 角色 ID
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 成功返回 ok(undefined)
+     */
+    remove: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<void>>;
+    /**
+     * 列出指定主体的角色档案
+     *
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 角色档案列表
+     */
+    list: (options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile[]>>;
+    /**
+     * 组合角色的完整系统提示词
+     *
+     * 将 `systemPrompt` 与 `traits` 拼装为一段可直接作为 system 消息的文本，
+     * 供 `ai.context.createManager({ systemPrompt })` 使用。
+     *
+     * @param id - 角色 ID
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 组合后的系统提示词，角色不存在时返回 PERSONA_NOT_FOUND
+     */
+    compose: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<string>>;
+}
+/** Persona 操作的主体作用域选项 */
+interface PersonaScopeOptions {
+    /** 所属主体 ID（不传时归为平台内置角色 `system`） */
+    objectId?: string;
+}
+
 /**
  * @h-ai/ai — Rerank 子功能类型
  *
@@ -1030,14 +1334,29 @@ declare const HaiAIError: {
     readonly MEMORY_RECALL_FAILED: _h_ai_core.HaiErrorDef;
     readonly MEMORY_NOT_FOUND: _h_ai_core.HaiErrorDef;
     readonly MEMORY_ENRICH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly MEMORY_PROMOTE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly PERSONA_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly PERSONA_SAVE_FAILED: _h_ai_core.HaiErrorDef;
     readonly FILE_PARSE_FAILED: _h_ai_core.HaiErrorDef;
     readonly FILE_UNSUPPORTED_FORMAT: _h_ai_core.HaiErrorDef;
     readonly FILE_OCR_FAILED: _h_ai_core.HaiErrorDef;
     readonly FILE_INVALID_CONTENT: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_INVALID_REQUEST: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_MODEL_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_PROVIDER_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_UNSUPPORTED_INPUT: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_UPSTREAM_ERROR: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_PROTOCOL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_INPUT_TOO_LARGE: _h_ai_core.HaiErrorDef;
+    readonly AUDIO_CANCELLED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_COMPRESS_FAILED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_SUMMARIZE_FAILED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_TOKEN_ESTIMATE_FAILED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_BUDGET_EXCEEDED: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_TURN_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_TURN_INVALID_STATE: _h_ai_core.HaiErrorDef;
     readonly STORE_FAILED: _h_ai_core.HaiErrorDef;
     readonly STORE_NOT_AVAILABLE: _h_ai_core.HaiErrorDef;
     readonly SESSION_NOT_FOUND: _h_ai_core.HaiErrorDef;
@@ -1121,6 +1440,8 @@ interface AIFunctions {
     readonly knowledge: KnowledgeOperations;
     /** Memory 操作（记忆提取、存储、检索、注入），需要先调用 `init()` */
     readonly memory: MemoryOperations;
+    /** Persona 操作（AI 角色人格档案与系统提示词组合），需要先调用 `init()` */
+    readonly persona: PersonaOperations;
     /** Token 操作（Token 估算），需要先调用 `init()` */
     readonly token: TokenOperations;
     /** Summary 操作（消息摘要生成），需要先调用 `init()` */
@@ -1135,6 +1456,91 @@ interface AIFunctions {
     readonly file: FileOperations;
     /** A2A 操作（Agent-to-Agent 协议），需要先调用 `init()` 并配置 `a2a` */
     readonly a2a: A2AOperations;
+    /** Audio 操作（语音识别 / 语音合成），需要先调用 `init()` 并配置 `audio` */
+    readonly audio: AudioOperations;
+}
+
+/**
+ * @h-ai/ai — 统一语音 WebSocket 协议
+ *
+ * 定义浏览器 / 远程客户端与 `@h-ai/serv` 语音入口之间的统一 WebSocket 消息协议。
+ * 客户端与服务端共享此协议，客户端不接收任何厂商原生事件；音频以二进制帧传输，
+ * 控制与文本以 JSON 帧传输。
+ * @module audio/ai-audio-ws-protocol
+ */
+
+/** 统一语音入口的默认路径（相对 API 前缀） */
+declare const AUDIO_WS_PATH = "/ai/audio";
+/**
+ * 会话起始消息（客户端首个 JSON 帧）
+ *
+ * 表达本次语音操作：识别或合成，及可选的模型 / 语言 / 音色 / 格式等参数。
+ */
+interface AudioWsStartMessage {
+    type: 'start';
+    /** 操作类型 */
+    operation: 'transcribe' | 'synthesize';
+    /**
+     * 是否流式返回增量结果
+     *
+     * 识别操作：`true` 时服务端桥接为持续音频输入并流式返回临时结果；
+     * `false`（默认）时服务端缓冲完整音频后返回单条最终结果。
+     */
+    stream?: boolean;
+    /** 模型 ID（不传时使用服务端默认模型） */
+    model?: string;
+    /** 识别语言提示 */
+    language?: string;
+    /** 领域提示词 / 热词（识别） */
+    contextHints?: string[];
+    /** 合成音色 */
+    voice?: string;
+    /** 合成自然语言风格指令 */
+    instruction?: string;
+    /** 音频格式（识别时为输入格式，合成时为输出格式） */
+    format?: AudioFormat;
+    /** 采样率 */
+    sampleRate?: number;
+    /** 声道数 */
+    channels?: 1 | 2;
+}
+/** 文本输入帧（合成操作时携带待合成文本） */
+interface AudioWsTextMessage {
+    type: 'text';
+    /** 待合成文本片段 */
+    text: string;
+}
+/** 输入结束帧（音频 / 文本输入全部发送完毕） */
+interface AudioWsDoneMessage {
+    type: 'done';
+}
+/** 客户端 JSON 控制消息（音频输入以二进制帧发送，不走 JSON） */
+type AudioWsClientMessage = AudioWsStartMessage | AudioWsTextMessage | AudioWsDoneMessage;
+/** 语音起止事件（识别操作时服务端 VAD 检测到语音开始 / 结束） */
+interface AudioWsSpeechMessage {
+    type: 'speech_started' | 'speech_stopped';
+}
+/** 识别结果帧（识别操作时返回当前语句的完整文本） */
+interface AudioWsTranscriptMessage {
+    type: 'transcript';
+    /** 当前语句的完整识别文本 */
+    text: string;
+    /** 是否为该语句的最终结果 */
+    final: boolean;
+}
+/** 错误帧（领域语义错误码，不暴露厂商协议细节） */
+interface AudioWsErrorMessage {
+    type: 'error';
+    /** 领域错误码（如 `hai:ai:054`） */
+    code: string;
+    /** 错误消息 */
+    message: string;
+}
+/** 结束帧（服务端已发送全部结果，随后关闭连接） */
+interface AudioWsEndMessage {
+    type: 'end';
 }
+/** 服务端 JSON 消息（合成音频以二进制帧返回，不走 JSON） */
+type AudioWsServerMessage = AudioWsSpeechMessage | AudioWsTranscriptMessage | AudioWsErrorMessage | AudioWsEndMessage;
 
-export { type AIFunctions as A, type MCPProvider as B, type CompressionStrategy as C, type MCPResource as D, type EmbeddingItem as E, type FileOperations as F, type MCPResourceContent as G, HaiAIError as H, type MCPToolDefinition as I, type MCPToolHandler as J, type McpServerOptions as K, type RerankItem as L, type MCPContext as M, type RerankOperations as N, type OutputFormat as O, type RerankRequest as P, type RerankResponse as Q, type RerankDocument as R, type SummaryOperations as S, type SummaryOptions as T, type SummaryResult as U, type TokenOperations as V, type AIInitOptions as a, CompressionStrategySchema as b, type AIMCPFunctionsDeps as c, type CompressOperations as d, type CompressOptions as e, type CompressResult as f, type ContextChatOptions as g, type ContextChatResult as h, type ContextDeps as i, type ContextManager as j, type ContextManagerOptions as k, type ContextOperations as l, type ContextStreamEvent as m, type EmbeddingOperations as n, type EmbeddingProvider as o, type EmbeddingRequest as p, type EmbeddingResponse as q, type FileParseMethod as r, type FileParseOptions as s, type FileParseRequest as t, type FileParseResult as u, type MCPOperations as v, type MCPPrompt as w, type MCPPromptArgument as x, type MCPPromptContent as y, type MCPPromptMessage as z };
+export { type OutputFormat as $, type AIFunctions as A, type ConversationTurn as B, type CompressionStrategy as C, type ConversationTurnStatus as D, type EmbeddingItem as E, type EmbeddingOperations as F, type EmbeddingProvider as G, HaiAIError as H, type EmbeddingRequest as I, type EmbeddingResponse as J, type FileOperations as K, type FileParseMethod as L, type FileParseOptions as M, type FileParseRequest as N, type FileParseResult as O, type MCPContext as P, type MCPOperations as Q, type MCPPrompt as R, type MCPPromptArgument as S, type MCPPromptContent as T, type MCPPromptMessage as U, type MCPProvider as V, type MCPResource as W, type MCPResourceContent as X, type MCPToolDefinition as Y, type MCPToolHandler as Z, type McpServerOptions as _, type AIInitOptions as a, type PersonaOperations as a0, type PersonaProfile as a1, type PersonaProfileInput as a2, type PersonaProfileUpdate as a3, type PersonaScopeOptions as a4, type RerankDocument as a5, type RerankItem as a6, type RerankOperations as a7, type RerankRequest as a8, type RerankResponse as a9, type SummaryOperations as aa, type SummaryOptions as ab, type SummaryResult as ac, type TokenOperations as ad, AUDIO_WS_PATH as b, type AudioWsClientMessage as c, type AudioWsDoneMessage as d, type AudioWsEndMessage as e, type AudioWsErrorMessage as f, type AudioWsServerMessage as g, type AudioWsSpeechMessage as h, type AudioWsStartMessage as i, type AudioWsTextMessage as j, type AudioWsTranscriptMessage as k, CompressionStrategySchema as l, type AIMCPFunctionsDeps as m, type CommitTurnInput as n, type CompressOperations as o, type CompressOptions as p, type CompressResult as q, type ConsolidateOptions as r, type ConsolidateResult as s, type ContextChatOptions as t, type ContextChatResult as u, type ContextDeps as v, type ContextManager as w, type ContextManagerOptions as x, type ContextOperations as y, type ContextStreamEvent as z };