对话系统

SDK 提供三种对话方法，覆盖不同场景：

方法	用途	保存消息	调 AI	扣费
`sdk.chat.send()`	用户发消息 → AI 回复	自动保存用户+AI消息	是	是
`sdk.chat.save()`	只保存一条消息	保存指定消息	否	否
`sdk.chat.generate()`	只请求 AI 生成	可选保存AI回复	是	是

sdk.chat.send()

一体化对话：发送用户消息 → AI 回复 → 自动保存双方消息。适合 1v1 对话场景。

参数

sdk.chat.send({
  message: string,       // 必填：用户消息内容
  topic?: string,        // 可选：话题标识，隔离对话历史
  context?: string,      // 可选：场景上下文，注入AI提示词
  stream?: boolean,      // 可选：是否流式输出（默认 false）
  onChunk?: (text) => void,  // stream=true 时：收到文本片段的回调
  onDone?: (id) => void,     // stream=true 时：生成完成的回调，id 为消息UUID
})

非流式用法

const reply = await sdk.chat.send({
  message: '你好',
  topic: 'dm_npc1',
  context: '[角色] 你是秦照野\n[场景] 私信聊天\n[好感度] 45/100',
});

console.log(reply.id);      // 消息 UUID
console.log(reply.content);  // AI 回复内容，如 "干嘛"

流式用法

await sdk.chat.send({
  message: '你好',
  topic: 'dm_npc1',
  context: '[角色] 你是秦照野',
  stream: true,
  onChunk: (text) => {
    // 每收到一个文本片段就会调用
    // text 是增量内容，不是完整内容
    chatBubble.textContent += text;
  },
  onDone: (id) => {
    // 流式输出完成
    console.log('消息ID:', id);
  },
});

流式模式下 send() 不返回 ChatResponse，AI 内容通过 onChunk 回调逐步传递。适合需要实时显示打字效果的场景。

sdk.chat.save()

只保存消息，不调 AI。用于先保存用户消息，再分别请求不同 NPC 回复的场景（如群聊）。

参数

sdk.chat.save({
  role: 'user' | 'assistant',  // 必填：消息角色
  content: string,              // 必填：消息内容
  topic?: string,               // 可选：话题标识
})

返回值

{ id: string }  // 保存的消息 UUID

用法

// 保存一条用户消息到群聊话题
await sdk.chat.save({
  role: 'user',
  content: '大家好！',
  topic: 'group_chat',
});

// 也可以保存 AI 消息（比如本地生成的内容）
await sdk.chat.save({
  role: 'assistant',
  content: '欢迎回来～',
  topic: 'group_chat',
});

save() 不会调用 AI、不会扣费。它只是把消息写入数据库对应的 topic 下，后续 send() 或 generate() 调用同一 topic 时，AI 能看到这条消息。

sdk.chat.generate()

只请求 AI 生成，不需要用户消息。AI 基于该 topic 的历史消息 + context 生成回复。

参数

sdk.chat.generate({
  topic?: string,        // 可选：话题标识
  context?: string,      // 可选：场景上下文
  stream?: boolean,      // 可选：是否流式（默认 false）
  save?: boolean,        // 可选：是否自动保存AI回复到该topic（默认 true）
  onChunk?: (text) => void,
  onDone?: (id) => void,
})

返回值（非流式）

{ id: string, content: string }  // save=true 时 id 为消息UUID，save=false 时 id 为空

用法

// NPC 在群聊中回复（AI 能看到 group_chat 的历史，包括之前 save 的消息）
const reply = await sdk.chat.generate({
  topic: 'group_chat',
  context: '[角色] 你是秦照野\n[场景] 主播群聊天',
  save: true,  // 自动保存到 group_chat topic
});

console.log(reply.content);  // "哟，稀客"

// 生成弹幕（不需要保存）
const danmaku = await sdk.chat.generate({
  topic: 'danmaku',
  context: '[角色] 你是弹幕生成器\n生成3条直播弹幕',
  save: false,  // 不保存
});

群聊场景完整示例

群聊是 save() + generate() 配合使用的典型场景：

// 1. 玩家发消息 → 保存到 group_chat topic
await sdk.chat.save({
  role: 'user',
  content: '大家晚上好！',
  topic: 'group_chat',
});

// 2. 请求秦照野回复
// AI 能看到 group_chat 历史中的「大家晚上好！」
const reply1 = await sdk.chat.generate({
  topic: 'group_chat',
  context: '[角色] 你是秦照野\n[场景] 主播群聊天\n[性格] 傲娇毒舌',
  save: true,  // 秦照野的回复保存到 group_chat
});
showMessage('秦照野', reply1.content);

// 3. 请求宋亦回复
// AI 能看到玩家的消息 + 秦照野的回复
const reply2 = await sdk.chat.generate({
  topic: 'group_chat',
  context: '[角色] 你是宋亦\n[场景] 主播群聊天\n[性格] 病娇温柔',
  save: true,
});
showMessage('宋亦', reply2.content);

每个 generate() 调用时，AI 都能看到该 topic 下最新的历史消息（包括前面刚保存的）。所以宋亦回复时，能看到玩家说了什么、秦照野回了什么，从而产生自然的群聊效果。

Topic 设计建议

场景	topic 示例	说明
和特定 NPC 私聊	`dm_qin_zhaoye`	每个 NPC 独立话题
群聊	`group_chat`	所有人共享一个话题
观看直播互动	`live_qin_zhaoye`	每个直播间独立
PK 对战	`pk_qin_zhaoye`	每场 PK 独立
弹幕生成	`danmaku`	一次性生成，可用 `save: false`
NPC 自动发言	`proactive_npc1`	NPC 主动行为

Topic 是一个字符串，格式没有限制。建议使用 类型_标识 的命名方式，保持一致性。同一 topic 下的消息共享历史，不同 topic 互不干扰。

Context 编写建议

Context 用于告诉 AI 当前的场景信息，推荐使用 [标签] 内容 的格式：

[角色] 你是秦照野，傲娇毒舌才艺主播
[场景] 私信聊天
[好感度] 45/100，关系：朋友
[心情] 开心（刚收到礼物）
[最近事件]
- 5分钟前：玩家送了玫瑰花
- 1小时前：玩家看了直播

Context 和面板状态（game_state）是互补的。面板数据由系统自动以 XML 注入 AI 提示词，context 用于传递面板之外的动态信息（比如当前扮演哪个角色、具体场景描述）。

对话系统

On this page