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

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。
@@ -113,6 +115,8 @@ const temp = await ai.llm.chat({
 ### 工具调用
 
 ```ts
+import { z } from 'zod'
+
 const registry = ai.tools.createRegistry()
 registry.register(ai.tools.define({
   name: 'get_weather',
@@ -128,6 +132,7 @@ const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 
 ```ts
 import { createMcpServer, StreamableHTTPServerTransport } from '@h-ai/ai'
+import { z } from 'zod'
 
 const server = createMcpServer({ name: 'my-server', version: '1.0.0' })
 server.registerTool('search', {
@@ -155,6 +160,63 @@ if (setup.success) {
 }
 ```
 
+### 语音（Audio）
+
+先在 `ai.init()` 中注册语音模型并映射默认识别/合成模型（凭据可回退到平台环境变量）：
+
+```ts
+await ai.init({
+  audio: {
+    models: [
+      { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime', operations: ['transcribe'] },
+      { id: 'tts', provider: 'qwen', model: 'qwen3-tts-flash-realtime', operations: ['synthesize'] },
+    ],
+    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)
+}
+
+// 流式合成：调用方为文本段分配稳定 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 === 'audio')
+    await player.write(event.data)
+  else if (event.type === 'segment_done')
+    markSegmentReadyToCommit(event.segmentId)
+}
+
+// 实时会话启动前按操作校验模型能力
+const caps = ai.audio.getCapabilities({ operation: 'synthesize', model: 'tts' })
+if (caps.success && caps.data.synthesize?.streamingAudioOutput) { /* 可实时 TTS */ }
+```
+
+> `synthesizeStream` 严格按 `segment_started → audio* → segment_done` 产出事件。播放器只有在对应音频真正播放完成后才应把该段文本计入 `spokenText`；播放状态仍由应用管理。
+
+取消/超时/连接错误统一为领域错误：`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 +231,78 @@ if (manager.success) {
 }
 ```
 
-## 配置
+#### 真实对话状态（Conversation Commit Layer）
+
+默认（`turnCommit: 'auto'`）下，`chat` / `chatStream` 会把**模型生成的完整文本**写入上下文。但在「模型生成 → TTS 合成 → 实际播放」链路中，AI 可能说到一半就被打断——此时进入下一轮所有参与者可见的对话状态，应当是**实际播放出去的部分**，而非模型本想说完的全文。
+
+设置 `turnCommit: 'manual'` 后，生成结果不会自动写入上下文，而是返回一个 `turnId`；由调用方在确定「实际发生了什么」后显式提交真实文本。
+
+`chatStream` 在**调用上游模型前**就登记轮次并产出 `turn_started`（事件序列 `turn_started → delta* → done`，中途取消时 `turn_started → delta* → cancelled`）。因此即使生成到一半被 `AbortSignal` 取消，也能拿到 `turnId` 与已生成文本，用真实内容提交：
+
+```ts
+const m = ai.context.createManager({ turnCommit: 'manual' /* ... */ }).data
+const controller = new AbortController()
+
+for await (const ev of m.chatStream('请展开讲讲', { signal: controller.signal })) {
+  if (ev.type === 'turn_started') {
+    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 })
+  }
+}
+
+// 观测每一轮的 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 +343,7 @@ memory:
   recencyDecay: 0.95
   embeddingEnabled: true
   defaultTopK: 10
+  candidateMultiplier: 5 # 候选池倍数：先取回 topK×倍数 条候选，再按 scope/重要性过滤，最后截取 topK
   writebackRelatedTopK: 20
 ```
 
@@ -221,13 +355,31 @@ 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 稳定）。
+两个 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` 涉及 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 内嵌凭证等敏感字段不会原样暴露。
 
+## 安全边界
+
+- Prompt、检索文档和模型输出都按不可信输入处理；不要把用户内容拼进不可覆盖的系统规则。
+- Zod 只校验工具参数形状，不代表调用者有权限。高权限工具必须在 handler 内再次校验身份、租户、资源归属与配额，并只把允许自动执行的工具注册给模型。
+- `callRemoteAgent()` 是独立客户端能力，只依赖 `ai.init()`，不要求配置 Agent Card 或注册本地 executor。它拒绝非 HTTP(S) 和 URL 内嵌凭据，但应用仍必须对远端 origin 配置白名单，并在出口代理处限制 DNS 重绑定、重定向到私网和云元数据地址。
+- 不记录完整 Prompt、工具参数、A2A headers、临时模型凭据或带 query 的远端 URL；确需审计时仅保存脱敏摘要。
+
 ## 错误处理
 
 ```ts
@@ -251,7 +403,8 @@ if (!result.success) {
 - `hai:ai:300-302`：Embedding。
 - `hai:ai:600-701`：Retrieval/RAG。
 - `hai:ai:800-805`：Knowledge。
-- `hai:ai:900-904`：Memory。
+- `hai:ai:050-059`：Audio。
+- `hai:ai:900-905`：Memory。
 - `hai:ai:980-984`：A2A。
 
 ## 测试