@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/skills/hai-ai/SKILL.md

@@ -1,721 +1,50 @@
 ---
 name: hai-ai
-description: 使用 @h-ai/ai 进行 LLM 调用（OpenAI 兼容）、MCP 服务器创建、工具定义与注册、流式处理、记忆管理（objectId 隔离）、上下文压缩与会话持久化；当需求涉及 AI 对话、工具调用、MCP 协议、流式响应、记忆提取注入、上下文摘要压缩、会话管理或 AI 客户端时使用。
+description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音及 A2A。"
 ---
 
 # hai-ai
 
-> `@h-ai/ai` 提供统一的 AI 能力，支持 LLM 调用（OpenAI 兼容 API）、MCP 服务器、工具定义与注册、流式处理、记忆管理（objectId 隔离）、上下文压缩与会话持久化。支持 Node.js 与浏览器双端。
-
----
-
-## 运行环境
-
-| 能力 | Node.js | 浏览器 |
-|------|---------|--------|
-| `ai.llm` LLM 调用 | ✅ | ❌（通过 API 端点代理） |
-| `ai.mcp` MCP 服务器 | ✅ | ❌ |
-| `ai.tools` 工具定义 | ✅ | ✅（纯函数，无需 init） |
-| `ai.stream` 流处理 | ✅ | ✅（纯函数，无需 init） |
-| `ai.memory` / `ai.conversation` | ✅ | ❌（通过 API 查询） |
-| `ai.knowledge` 知识库 | ✅ | ❌（通过 API 查询） |
-
-浏览器端消费 AI 能力的标准模式：通过 `api.stream()` 或 `apiFetch` 调用服务端 API 端点。
-
----
-
-## 依赖
-
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/reldb` | 数据库（对话记录/会话/记忆/知识库持久化） | **必需** | 需在 `ai.init()` 前初始化 |
-| `@h-ai/vecdb` | 向量数据库（记忆向量检索/知识库检索） | **必需** | 需在 `ai.init()` 前初始化 |
-| `@h-ai/datapipe` | 数据管道（知识库文档切分） | 内部使用 | 无需手动初始化 |
-
-> `ai.tools` 和 `ai.stream` 为纯函数子系统，无需 init 即可使用。
-
----
-
-## 适用场景
-
-- 调用 LLM 进行对话（非流式/流式）
-- 定义和执行工具（Function Calling）
-- 创建 MCP 服务器（Streamable HTTP/SSE/Stdio）
-- 注册 MCP 资源与提示词
-- 自动提取和管理对话记忆
-- 上下文压缩与 Token 控制
-- 会话持久化与恢复（配合 reldb/vecdb）
-- 前端 AI 客户端集成（记忆/会话查询）
-
----
-
-## 使用步骤
-
-### 1. 配置
-
-```yaml
-# config/_ai.yml
-llm:
-  apiKey: ${HAI_AI_LLM_API_KEY:}
-  baseUrl: ${HAI_AI_LLM_BASE_URL:https://api.openai.com/v1}
-  model: ${HAI_AI_LLM_MODEL:gpt-4o-mini}
-  maxTokens: ${HAI_AI_LLM_MAX_TOKENS:4096}
-  temperature: 0.7
-  timeout: 60000
-
-# 存储配置（可选）
-store:
-  mode: memory               # memory | persistent（需 reldb + vecdb 已初始化）
-
-# 记忆管理（可选）
-memory:
-  maxEntries: 1000          # 最大记忆条数
-  extractModel: gpt-4o-mini # 提取用模型（默认用 LLM 配置模型）
-  apiKey:                   # 可选，覆盖 LLM apiKey
-  baseUrl:                  # 可选，覆盖 LLM baseUrl
-  recencyDecay: 0.95        # 时间衰减系数
-  embeddingEnabled: true    # 启用向量检索
-  defaultTopK: 10           # 默认检索数量
-
-# Token 估算（可选）
-token:
-  tokenRatio: 0.25           # Token 估算系数（4 字符 ≈ 1 token）
-
-# 摘要生成（可选）
-summary:
-  systemPrompt:              # 自定义摘要系统提示词
-
-# 上下文压缩（可选）
-compress:
-  defaultStrategy: hybrid    # 压缩策略：summary | sliding-window | hybrid
-  defaultMaxTokens: 0        # 0 = 取模型 maxTokens 的 80%
-  preserveLastN: 4           # 保留最近 N 条消息
-
-# 知识库（可选）
-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
-```
-
-### 2. 初始化与关闭
-
-```typescript
-import { ai } from '@h-ai/ai'
-import { reldb } from '@h-ai/reldb'
-import { vecdb } from '@h-ai/vecdb'
-
-// 先初始化依赖
-await reldb.init(core.config.get('db'))
-await vecdb.init(core.config.get('vecdb'))
-
-// 再初始化 AI 模块（自动使用已初始化的 reldb 和 vecdb 单例）
-ai.init(core.config.get('ai'))
-// 使用后
-ai.close()
-```
-
-**特殊说明**：`ai.tools` 和 `ai.stream` 无需 init 即可使用；`ai.llm` 和 `ai.mcp` 操作需要先 init。
-
----
-
-## 核心 API
-
-### LLM 操作 — `ai.llm`
-
-| 方法         | 签名                                                   | 说明             |
-| ------------ | ------------------------------------------------------ | ---------------- |
-| `chat`       | `(options) => Promise<HaiResult<ChatCompletionResponse>>` | 对话（非流式）   |
-| `chatStream` | `(options) => AsyncIterable<ChatCompletionChunk>`      | 对话（流式）     |
-| `listModels` | `() => Promise<HaiResult<string[]>>`                      | 获取可用模型列表 |
-
-```typescript
-// 非流式
-const result = await ai.llm.chat({
-  messages: [
-    { role: 'system', content: '你是一个有帮助的助手' },
-    { role: 'user', content: '你好' },
-  ],
-  tools: registry.getDefinitions(), // 可选
-})
-if (result.success) {
-  const message = result.data.choices[0].message
-}
-
-// 流式
-for await (const chunk of ai.llm.chatStream({ messages })) {
-  const delta = chunk.choices[0]?.delta?.content
-  if (delta)
-    process.stdout.write(delta)
-}
-```
-
-### 工具定义 — `ai.tools`
-
-```typescript
-import { ai } from '@h-ai/ai'
-import { z } from 'zod'
-
-// 定义工具（Zod Schema 自动转 JSON Schema）
-const weatherTool = ai.tools.define({
-  name: 'get_weather',
-  description: '获取天气信息',
-  parameters: z.object({
-    city: z.string().describe('城市名称'),
-    unit: z.enum(['celsius', 'fahrenheit']).optional(),
-  }),
-  handler: async ({ city, unit }) => {
-    return { temperature: 20, city, unit: unit ?? 'celsius' }
-  },
-})
-
-// 注册表管理
-const registry = ai.tools.createRegistry()
-registry.register(weatherTool)
-
-// 获取 OpenAI 工具定义（传递给 LLM）
-const definitions = registry.getDefinitions()
-
-// 执行 LLM 返回的工具调用
-const toolMessage = await registry.execute(toolCall)
-const toolMessages = await registry.executeAll(toolCalls, { parallel: true })
-```
-
-> `ai.tools.define` 和 `ai.tools.createRegistry` 也可通过 `defineTool` / `createToolRegistry` 直接导入，两者等价。
-
-### 流处理 — `ai.stream`
-
-```typescript
-import { ai } from '@h-ai/ai'
-
-const processor = ai.stream.createProcessor()
-for await (const chunk of ai.llm.chatStream({ messages })) {
-  const delta = processor.process(chunk)
-  if (delta?.content) { /* 实时显示 */ }
-}
-
-const result = processor.getResult()
-// { content: string, toolCalls: ToolCall[], finishReason: string | null }
-const message = processor.toAssistantMessage()
-// { role: 'assistant', content: '...', tool_calls?: [...] }
-
-// 快捷收集全部内容
-const collected = await ai.stream.collect(stream)
-```
-
-> `ai.stream.createProcessor` / `ai.stream.collect` 也可通过 `createStreamProcessor` / `collectStream` 直接导入。
-
-### MCP 服务器 — `createMcpServer`
-
-```typescript
-import { createMcpServer, StreamableHTTPServerTransport } from '@h-ai/ai'
-import { z } from 'zod'
-
-const mcp = createMcpServer({ name: 'my-server', version: '1.0.0' })
-
-// 注册工具
-mcp.registerTool('search', {
-  description: '搜索',
-  inputSchema: { query: z.string() },
-}, async ({ query }) => ({
-  content: [{ type: 'text', text: `Results for ${query}` }],
-}))
-
-// 注册资源
-mcp.registerResource('config', 'config://app', {
-  description: '应用配置',
-}, async uri => ({
-  contents: [{ uri: uri.href, text: '{}' }],
-}))
-
-// 注册提示词
-mcp.registerPrompt('summarize', {
-  description: '总结文本',
-  argsSchema: { text: z.string() },
-}, async ({ text }) => ({
-  messages: [{ role: 'user', content: { type: 'text', text } }],
-}))
-
-// 连接传输层
-const transport = new StreamableHTTPServerTransport({
-  sessionIdGenerator: () => randomUUID(),
-})
-await mcp.connect(transport)
-```
-
-**传输层选项**：`StreamableHTTPServerTransport`（推荐，Web 场景）、`SSEServerTransport`、`StdioServerTransport`
-
-### MCP 操作 — `ai.mcp`
-
-| 方法               | 签名                               | 说明       |
-| ------------------ | ---------------------------------- | ---------- |
-| `registerTool`     | `(def, handler) => void`           | 注册工具   |
-| `callTool`         | `(name, input) => Promise<HaiResult>` | 调用工具   |
-| `registerResource` | `(def, reader) => void`            | 注册资源   |
-| `readResource`     | `(uri) => Promise<HaiResult>`         | 读取资源   |
-| `registerPrompt`   | `(def, generator) => void`         | 注册提示词 |
-| `getPrompt`        | `(name, args) => Promise<HaiResult>`  | 获取提示词 |
-
-### 前端客户端
-
-```typescript
-import { api } from '@h-ai/api-client'
-import { createAIClient } from '@h-ai/ai/client'
-
-await api.init({ baseUrl: '/api', auth: { ... } })
-const client = createAIClient({ api })
-
-// 非流式
-const response = await client.chat({ messages })
-
-// 流式
-for await (const chunk of client.chatStream({ messages }, {
-  onProgress: (p) => { /* 处理进度 */ },
-})) { /* ... */ }
-
-// 便捷方法
-const reply = await client.sendMessage('你好', '系统提示')
-
-// 记忆与会话查询
-const memories = await client.recallMemories('用户偏好', { topK: 5, objectId: 'user-001' })
-const page = await client.listMemories({ objectId: 'user-001', offset: 0, limit: 20 })
-const sessions = await client.listSessions('user-001')
-```
-
-### 记忆管理 — `ai.memory`
-
-| 方法              | 签名                                                          | 说明                               |
-| ----------------- | ------------------------------------------------------------- | ---------------------------------- |
-| `extract`         | `(messages, options?) => Promise<HaiResult<MemoryEntry[]>>`      | 从对话中自动提取记忆（LLM 驱动）  |
-| `add`             | `(entry) => Promise<HaiResult<MemoryEntry>>`                     | 手动添加一条记忆                   |
-| `get`             | `(memoryId) => Promise<HaiResult<MemoryEntry>>`                  | 获取指定记忆                       |
-| `recall`          | `(query, options?) => Promise<HaiResult<MemoryEntry[]>>`         | 按查询检索最相关的记忆             |
-| `injectMemories`  | `(messages, options?) => Promise<HaiResult<ChatMessage[]>>`      | 将相关记忆自动注入消息列表         |
-| `remove`          | `(memoryId) => Promise<HaiResult<void>>`                         | 删除指定记忆                       |
-| `list`            | `(options?) => Promise<HaiResult<MemoryEntry[]>>`                | 列出记忆（支持类型/objectId 过滤） |
-| `listPage`        | `(options?) => Promise<HaiResult<StorePage<MemoryEntry>>>`       | 分页列出记忆                       |
-| `clear`           | `(options?) => Promise<HaiResult<void>>`                         | 清空记忆（支持按类型/objectId 清空）|
-
-```typescript
-// 从对话中自动提取记忆
-const extracted = await ai.memory.extract(messages, { objectId: 'user-001' })
-if (extracted.success) {
-  // extracted.data: MemoryEntry[]（已自动存储）
-}
-
-// 手动添加记忆
-await ai.memory.add({
-  content: '用户偏好使用中文',
-  type: 'preference', // fact | preference | event | entity | instruction
-  importance: 0.8,
-  objectId: 'user-001', // 可选，不传为全局
-})
-
-// 检索相关记忆
-const memories = await ai.memory.recall('语言偏好', { topK: 5, objectId: 'user-001' })
-
-// 将记忆注入消息列表（自动检索 + 格式化 + 插入 system prompt）
-const enriched = await ai.memory.injectMemories(messages, { topK: 5, position: 'system' })
-if (enriched.success) {
-  const response = await ai.llm.chat({ messages: enriched.data })
-}
-```
-
-### Token 估算 — `ai.token`
-
-| 方法               | 签名                                | 说明                     |
-| ------------------ | ----------------------------------- | ------------------------ |
-| `estimateMessages` | `(messages) => HaiResult<number>`      | 估算消息列表的 Token 数  |
-| `estimateText`     | `(text) => number`                  | 估算纯文本的 Token 数    |
-
-```typescript
-// 估算消息列表 Token 数
-const tokens = ai.token.estimateMessages(messages)
-if (tokens.success) {
-  // tokens.data — 估算的 Token 数
-}
-
-// 估算纯文本 Token 数
-const count = ai.token.estimateText('Hello world')
-```
-
-### 消息摘要 — `ai.summary`
-
-| 方法        | 签名                                                              | 说明                          |
-| ----------- | ----------------------------------------------------------------- | ----------------------------- |
-| `summarize` | `(messages, options?) => Promise<HaiResult<SummaryResult>>`          | 对消息生成摘要（支持增量）    |
-| `generate`  | `(text, options?) => Promise<HaiResult<SummaryResult>>`              | 对纯文本生成摘要              |
-
-### 上下文压缩 — `ai.compress`
-
-| 方法          | 签名                                                              | 说明                                  |
-| ------------- | ----------------------------------------------------------------- | ------------------------------------- |
-| `tryCompress` | `(messages, options?) => Promise<HaiResult<CompressResult>>`         | 压缩消息列表至指定 Token 预算         |
-
-```typescript
-// 压缩超长对话
-const result = await ai.compress.tryCompress(messages, {
-  strategy: 'hybrid', // summary | sliding-window | hybrid
-  maxTokens: 4000,
-  preserveLastN: 4,
-})
-if (result.success) {
-  // result.data.messages — 压缩后的消息列表
-  // result.data.originalTokens / compressedTokens — 压缩前后 Token 数
-  // result.data.summary — 生成的摘要文本
-}
-```
-
-### 上下文管理 — `ai.context`
-
-| 方法             | 签名                                                              | 说明                                                    |
-| ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
-| `createManager`  | `(options?) => HaiResult<ContextManager>`                            | 创建有状态上下文管理器（压缩 + LLM/Memory/RAG 编排）   |
-| `restoreManager` | `(scope, options?) => Promise<HaiResult<ContextManager>>`            | 从持久化存储恢复上下文管理器                            |
-| `listSessions`   | `(objectId) => Promise<HaiResult<SessionInfo[]>>`                    | 列出指定对象的所有会话                                  |
-| `renameSession`  | `(sessionId, title) => Promise<HaiResult<void>>`                     | 重命名会话                                              |
-| `removeSession`  | `(sessionId) => Promise<HaiResult<void>>`                            | 删除会话                                                |
-
-**ContextManager 方法**：
-- `addMessage(msg)` — 追加消息（自动压缩）
-- `getMessages()` / `getTokenUsage()` / `getSummaries()` — 查询状态
-- `chat(message, options?)` — 发送消息并获取回复（编排 LLM + Memory + RAG + Reasoning）
-- `chatStream(message, options?)` — 流式对话（产出 delta*/done 事件）
-- `save()` — 持久化 / `reset()` — 重置
-
-```typescript
-// 创建管理器并直接对话（推荐）
-const managerResult = ai.context.createManager({
-  scope: { objectId: 'user-001', sessionId: 'sess-001' },
-  systemPrompt: '你是一个友好的助手。',
-  compress: { maxTokens: 8000, strategy: 'hybrid', auto: true },
-  memory: { enable: true, enableExtract: true },
-})
-if (managerResult.success) {
-  const manager = managerResult.data
-  const result = await manager.chat('你好')
-  // result.data.reply / result.data.model / result.data.usage
-  await manager.save()
-}
-
-// 流式对话
-for await (const event of manager.chatStream('讲个故事')) {
-  if (event.type === 'delta') process.stdout.write(event.text)
-}
-
-// 恢复已有会话
-const restored = await ai.context.restoreManager(
-  { objectId: 'user-001', sessionId: 'sess-001' },
-  { compress: { maxTokens: 8000 }, memory: { enable: true } },
-)
-
-// 列出对象的所有会话
-const sessions = await ai.context.listSessions('user-001')
-```
-
----
-
-## 错误码 — `HaiAIError`
-
-| 错误码                                              | code           | 说明                 |
-| --------------------------------------------------- | -------------- | -------------------- |
-| `HaiAIError.INTERNAL_ERROR`                         | `hai:ai:000`   | 内部错误             |
-| `HaiAIError.NOT_INITIALIZED`                        | `hai:ai:010`   | 服务未初始化         |
-| `HaiAIError.CONFIGURATION_ERROR`                    | `hai:ai:011`   | 配置错误             |
-| `HaiAIError.INIT_IN_PROGRESS`                       | `hai:ai:012`   | 初始化进行中         |
-| `HaiAIError.RERANK_API_ERROR`                       | `hai:ai:020`   | Rerank API 调用错误  |
-| `HaiAIError.RERANK_INVALID_REQUEST`                 | `hai:ai:021`   | Rerank 请求参数无效  |
-| `HaiAIError.FILE_PARSE_FAILED`                      | `hai:ai:030`   | 文件解析失败         |
-| `HaiAIError.FILE_UNSUPPORTED_FORMAT`                | `hai:ai:031`   | 不支持的文件格式     |
-| `HaiAIError.FILE_OCR_FAILED`                        | `hai:ai:032`   | OCR 识别失败         |
-| `HaiAIError.FILE_INVALID_CONTENT`                   | `hai:ai:033`   | 文件内容无效         |
-| `HaiAIError.API_ERROR`                              | `hai:ai:100`   | API 调用错误         |
-| `HaiAIError.INVALID_REQUEST`                        | `hai:ai:101`   | 无效请求             |
-| `HaiAIError.RATE_LIMITED`                            | `hai:ai:102`   | 速率限制             |
-| `HaiAIError.TIMEOUT`                                | `hai:ai:103`   | 请求超时             |
-| `HaiAIError.MODEL_NOT_FOUND`                        | `hai:ai:104`   | 模型未找到           |
-| `HaiAIError.CONTEXT_LENGTH_EXCEEDED`                | `hai:ai:105`   | 上下文长度超限       |
-| `HaiAIError.LLM_RECORD_FAILED`                      | `hai:ai:106`   | 对话记录保存失败     |
-| `HaiAIError.LLM_HISTORY_FAILED`                     | `hai:ai:107`   | 对话历史查询失败     |
-| `HaiAIError.MCP_CONNECTION_ERROR`                   | `hai:ai:200`   | MCP 连接错误         |
-| `HaiAIError.MCP_PROTOCOL_ERROR`                     | `hai:ai:201`   | MCP 协议错误         |
-| `HaiAIError.MCP_TOOL_ERROR`                         | `hai:ai:202`   | MCP 工具错误         |
-| `HaiAIError.MCP_RESOURCE_ERROR`                     | `hai:ai:203`   | MCP 资源错误         |
-| `HaiAIError.MCP_SERVER_ERROR`                       | `hai:ai:204`   | MCP 服务器错误       |
-| `HaiAIError.EMBEDDING_API_ERROR`                    | `hai:ai:300`   | Embedding 调用错误   |
-| `HaiAIError.EMBEDDING_MODEL_NOT_FOUND`              | `hai:ai:301`   | Embedding 模型未找到 |
-| `HaiAIError.EMBEDDING_INPUT_TOO_LONG`               | `hai:ai:302`   | Embedding 输入过长   |
-| `HaiAIError.TOOL_NOT_FOUND`                         | `hai:ai:400`   | 工具未找到           |
-| `HaiAIError.TOOL_VALIDATION_FAILED`                 | `hai:ai:401`   | 工具验证失败         |
-| `HaiAIError.TOOL_EXECUTION_FAILED`                  | `hai:ai:402`   | 工具执行失败         |
-| `HaiAIError.TOOL_TIMEOUT`                           | `hai:ai:403`   | 工具执行超时         |
-| `HaiAIError.REASONING_FAILED`                       | `hai:ai:500`   | 推理执行失败         |
-| `HaiAIError.REASONING_MAX_ROUNDS`                   | `hai:ai:501`   | 推理轮次超限         |
-| `HaiAIError.REASONING_STRATEGY_NOT_FOUND`           | `hai:ai:502`   | 推理策略未找到       |
-| `HaiAIError.RETRIEVAL_FAILED`                       | `hai:ai:600`   | 检索执行失败         |
-| `HaiAIError.RETRIEVAL_SOURCE_NOT_FOUND`             | `hai:ai:601`   | 检索源未配置         |
-| `HaiAIError.RAG_FAILED`                             | `hai:ai:700`   | RAG 执行失败         |
-| `HaiAIError.RAG_CONTEXT_BUILD_FAILED`               | `hai:ai:701`   | RAG 上下文构建失败   |
-| `HaiAIError.KNOWLEDGE_SETUP_FAILED`                 | `hai:ai:800`   | 知识库初始化失败     |
-| `HaiAIError.KNOWLEDGE_INGEST_FAILED`                | `hai:ai:801`   | 知识入库失败         |
-| `HaiAIError.KNOWLEDGE_RETRIEVE_FAILED`              | `hai:ai:802`   | 知识检索失败         |
-| `HaiAIError.KNOWLEDGE_ENTITY_EXTRACT_FAILED`        | `hai:ai:803`   | 实体提取失败         |
-| `HaiAIError.KNOWLEDGE_NOT_SETUP`                    | `hai:ai:804`   | 知识库未初始化       |
-| `HaiAIError.KNOWLEDGE_COLLECTION_NOT_FOUND`         | `hai:ai:805`   | 集合不存在           |
-| `HaiAIError.MEMORY_EXTRACT_FAILED`                  | `hai:ai:900`   | 记忆提取失败         |
-| `HaiAIError.MEMORY_STORE_FAILED`                    | `hai:ai:901`   | 记忆存储失败         |
-| `HaiAIError.MEMORY_RECALL_FAILED`                   | `hai:ai:902`   | 记忆召回失败         |
-| `HaiAIError.MEMORY_NOT_FOUND`                       | `hai:ai:903`   | 记忆条目不存在       |
-| `HaiAIError.MEMORY_ENRICH_FAILED`                   | `hai:ai:904`   | 记忆注入失败         |
-| `HaiAIError.CONTEXT_COMPRESS_FAILED`                | `hai:ai:950`   | 上下文压缩失败       |
-| `HaiAIError.CONTEXT_SUMMARIZE_FAILED`               | `hai:ai:951`   | 上下文摘要失败       |
-| `HaiAIError.CONTEXT_TOKEN_ESTIMATE_FAILED`          | `hai:ai:952`   | Token 估算失败       |
-| `HaiAIError.CONTEXT_BUDGET_EXCEEDED`                | `hai:ai:953`   | Token 预算超限       |
-| `HaiAIError.STORE_FAILED`                           | `hai:ai:960`   | 存储操作失败         |
-| `HaiAIError.STORE_NOT_AVAILABLE`                    | `hai:ai:961`   | 存储后端不可用       |
-| `HaiAIError.SESSION_NOT_FOUND`                      | `hai:ai:970`   | 会话不存在           |
-| `HaiAIError.SESSION_FAILED`                         | `hai:ai:971`   | 会话操作失败         |
-| `HaiAIError.A2A_NOT_CONFIGURED`                     | `hai:ai:980`   | A2A 服务未配置       |
-| `HaiAIError.A2A_HANDLE_FAILED`                      | `hai:ai:981`   | A2A 请求处理失败     |
-| `HaiAIError.A2A_REMOTE_CALL_FAILED`                 | `hai:ai:982`   | A2A 远端调用失败     |
-| `HaiAIError.A2A_AUTH_FAILED`                        | `hai:ai:983`   | A2A 认证失败         |
-| `HaiAIError.A2A_LIST_MESSAGES_FAILED`               | `hai:ai:984`   | A2A 消息查询失败     |
-
----
-
-## 常见模式
-
-### 带工具调用的对话循环
-
-```typescript
-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 toolCalls = result.data.choices[0].message.tool_calls!
-  messages.push(result.data.choices[0].message)
-
-  const toolMessages = await registry.executeAll(toolCalls)
-  if (toolMessages.success)
-    messages.push(...toolMessages.data)
-
-  result = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
-}
-```
-
-### 知识库完整流程（文档入库 → 问答）
-
-```typescript
-import { ai } from '@h-ai/ai'
-
-// 初始化
-await ai.knowledge.setup()
-
-// 导入多篇文档
-for (const doc of documents) {
-  const result = await ai.knowledge.ingest({
-    documentId: doc.id,
-    content: doc.content,
-    title: doc.title,
-    enableEntityExtraction: true,
-  })
-  if (!result.success) {
-    // 按错误码处理
-    switch (result.error.code) {
-      case HaiAIError.KNOWLEDGE_INGEST_FAILED:
-        // 入库失败
-        break
-      case HaiAIError.EMBEDDING_API_ERROR:
-        // 嵌入调用失败
-        break
-    }
-  }
-}
-
-// 问答
-const answer = await ai.knowledge.ask('项目核心架构是什么？')
-if (answer.success) {
-  // answer.data.answer — LLM 生成的回答
-  // answer.data.citations — 信源引用列表
-}
-```
-
-### SvelteKit API 端点
-
-```typescript
-// src/routes/api/ai/+server.ts
-export async function POST(event) {
-  const { valid, data } = await kit.validate.form(event.request, ChatSchema)
-  if (!valid)
-    return kit.response.badRequest('Invalid request')
-
-  const result = await ai.llm.chat({ messages: data!.messages })
-  if (!result.success)
-    return kit.response.error(result.error.code, result.error.message)
-
-  return kit.response.ok(result.data)
-}
-```
-
-### 记忆增强的多轮对话
-
-```typescript
-import { ai } from '@h-ai/ai'
-
-const messages: ChatMessage[] = [
-  { role: 'system', content: '你是一个有帮助的助手' },
-]
-
-async function chat(userInput: string) {
-  messages.push({ role: 'user', content: userInput })
-
-  // 1. 注入相关记忆到消息列表
-  const enriched = await ai.memory.injectMemories(messages, {
-    topK: 5,
-    position: 'system',
-  })
-  if (!enriched.success) return
-
-  // 2. 压缩上下文以适应 Token 限制
-  const compressed = await ai.compress.tryCompress(enriched.data, {
-    maxTokens: 4000,
-    strategy: 'hybrid',
-  })
-  if (!compressed.success) return
-
-  // 3. 调用 LLM
-  const result = await ai.llm.chat({ messages: compressed.data.messages })
-  if (!result.success) return
-
-  const reply = result.data.choices[0].message
-  messages.push(reply)
-
-  // 4. 从新对话中提取记忆（异步，不阻塞响应）
-  ai.memory.extract(messages.slice(-2))
-
-  return reply.content
-}
-```
-
-### 有状态上下文管理器
-
-```typescript
-import { ai } from '@h-ai/ai'
-
-// 创建管理器（嵌套配置 + 对话编排）
-const managerResult = ai.context.createManager({
-  scope: { objectId: 'user-001', sessionId: 'sess-001' },
-  systemPrompt: '你是一个友好的助手。',
-  compress: { maxTokens: 8000, strategy: 'hybrid', preserveLastN: 4, auto: true },
-  memory: { enable: true, enableExtract: true },
-})
-if (!managerResult.success) throw new Error(managerResult.error.message)
-const manager = managerResult.data
-
-// 方式一：直接对话（推荐，自动编排 LLM + Memory + 压缩）
-const result = await manager.chat('你好')
-if (result.success) {
-  // result.data.reply / result.data.model / result.data.usage
-}
-
-// 流式对话
-for await (const event of manager.chatStream('讲个故事')) {
-  if (event.type === 'delta') process.stdout.write(event.text)
-}
-
-// 方式二：手动管理消息
-async function manualChat(userInput: string) {
-  await manager.addMessage({ role: 'user', content: userInput })
-  const msgs = manager.getMessages()
-  if (!msgs.success) return
-  const chatResult = await ai.llm.chat({ messages: msgs.data })
-  if (!chatResult.success) return
-  await manager.addMessage(chatResult.data.choices[0].message)
-  await manager.save()
-  return chatResult.data.choices[0].message.content
-}
-```
-
----
-
-## 浏览器端使用
-
-### 流式对话（SSE）
-
-浏览器通过 `api.stream()` 消费服务端流式 API：
-
-```typescript
-import { api } from '@h-ai/api-client'
-
-const controller = new AbortController()
-
-for await (const chunk of api.stream('/api/v1/ai/chat', {
-  conversationId: 'conv-1',
-  content: '你好',
-}, { signal: controller.signal })) {
-  // 每个 chunk 是 SSE data: 行的文本内容
-  appendToUI(chunk)
-}
-
-// 主动停止
-controller.abort()
-```
-
-或使用 `apiFetch`（SSR SvelteKit 同源场景）：
-
-```typescript
-import { apiFetch } from '$lib/utils/api'
-
-const res = await apiFetch('/api/v1/ai/chat', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ conversationId, content: userInput }),
-})
-
-// 手动消费 SSE 流
-const reader = res.body!.getReader()
-const decoder = new TextDecoder()
-while (true) {
-  const { done, value } = await reader.read()
-  if (done) break
-  appendToUI(decoder.decode(value))
-}
-```
-
-### 浏览器端使用 ai.stream（处理流式 chunk）
-
-`ai.stream` 是纯函数，浏览器端可直接使用：
-
-```typescript
-import { ai } from '@h-ai/ai'
-
-const processor = ai.stream.createProcessor()
-// 将服务端返回的 SSE chunk 逐条 process，提取 delta
-```
-
----
-
-## 相关 Skills
-
-- `hai-build`：模块初始化顺序
-- `hai-core`：配置与 HaiResult 模型
-- `hai-kit`：SvelteKit API 端点集成
-- `hai-vecdb`：向量数据库（Retrieval / RAG / Knowledge 的存储层）
-- `hai-reldb`：关系数据库（Knowledge 实体索引的存储层）
-- `hai-datapipe`：数据清洗与分块（Knowledge 入库前的数据处理）
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音及 A2A |
+| 适用场景 | AI 应用服务端集成或浏览器代理接入 |
+| 输入 | AIConfigInput、消息/音频/图片、scope、AbortSignal |
+| 输出 | 领域操作为 HaiResult；流为 AsyncIterable，迭代可抛错 |
+| 限制 | tools/stream 无需 init；其他领域先初始化。生产须先初始化共享 PostgreSQL/MySQL + 网络 vecdb 或传 stateScope=shared 的 Provider；临时 Store 仅开发/测试，关闭后丢失。工具调用仍需业务授权。 |
+
+## 使用路径
+
+- 先选择完整结果还是流式 API；不要对 AsyncIterable 取 `.success`。流取消/错误须结束播放器和连接。
+- Memory/Context 用 objectId/sessionId 隔离主体；Context scope 必填，跨节点读先 reload/restore，manual pending 可跨节点按 turnId 幂等提交实际文本。共享 Store 必须实现版本 CAS/存储端期限；过期生成不自动重放外部副作用。
+- Mem0 生产须实际映射持久 Qdrant；内存回退开关不能绕过。列表/条件清理最多 1000 条主体原始候选，超限检查 `MEMORY_LIST_INCOMPLETE`；禁止把截断结果当完整 total。
+- HTTP AI 使用 `@h-ai/api-client` 的 typed 领域方法；A2A 由应用定义并绑定自己的 contract；`@h-ai/ai/client` 只提供独立 `createAudioClient`，不再封装字符串路径 HTTP 或重复 SSE helper。
+- 语音客户端用一次性 ticket，不能把 IAM access token 放 URL；按 segment_started 的真实格式解码。
+- 压缩超过硬预算须停止模型请求；不能失败后发送原始超长消息。
+
+## 按需参考
+
+详细配置、API 签名、错误码和范本在 [guide.md](guide.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+
+- 使用边界
+- 初始化与关闭
+- 配置要点
+- 常用 API
+- LLM + 工具调用
+- 流式处理
+- 临时模型（tempModel）
+- MCP 服务器
+- 记忆、RAG 与知识库
+- Context 管理器
+- 语音（Audio）
+- 文生图（Image）
+- SvelteKit API 端点模式
+- 质量与安全检查
+
+补充类型/错误码与范本见 [reference.md](reference.md)，仅在上述用法不足时读取。
+
+公开 API 示例以安装包的实际入口为准；框架源码中的内部工厂例子仅供模块维护。HaiResult 调用先检查 success，流与浏览器 AudioClient 按显式抛错契约处理；Context flush 失败和 A2A 未知外部效果不得盲目重放。
+
+Node 自定义 SSE 使用 ai.stream 的统一编解码，不用 split/trim 手拆上游事件；encoder 的非法元数据会显式抛错。Anthropic/MiMo 的真实 HTTP 流在退出和取消时释放正文，EOF 不伪造未完成事件，不自动重连或重放业务。