动态上下文

将实时上下文注入角色的理解中——游戏状态、用户偏好、场景变化——无需重新连接。

连接时的动态上下文

通过连接时传入初始上下文 dynamicInfo:

client.connect({
  apiKey: '...',
  characterId: '...',
  dynamicInfo: '玩家：Aria，等级：5，当前位置：Eldenmere 森林',
});

默认情况下，此上下文是可变的，并且可以在会话期间被替换。若要将其锁定为静态系统提示：

{
  dynamicInfo: '游戏规则：已禁用 PvP。经济：通胀模式。',
  keepInContext: true, // 在整个会话中作为固定提示保留
}

---

updateContext

会话中途更新上下文的主要方法。支持追加、替换和重置模式。

client.updateContext(options: ContextUpdateOptions)

选项

字段	类型	默认值	描述
text	string	—	要注入的上下文文本。除非 mode 为 "reset"
mode	"append" | "replace" | "reset"	"append"	如何应用上下文
run_llm	"true" | "false" | "auto"	"auto"	是否触发机器人回复
current_attention_object	string	—	机器人应聚焦的对象（必须匹配 actionConfig.objects[].name)

模式

append — 追加到现有的临时上下文：

client.updateContext({
  text: '用户刚捡起了魔法剑。',
  mode: 'append',
  run_llm: 'false', // 静默更新，不触发机器人回复
});

replace — 替换整个临时上下文：

client.updateContext({
  text: '游戏状态：10 级，已触发 Boss 战。',
  mode: 'replace',
  run_llm: 'auto', // 让服务器决定是否回复
});

reset — 完全清除临时上下文：

client.updateContext({ mode: 'reset' });

触发机器人回复

// 始终回复
client.updateContext({
  text: '出现了新的挑战者。',
  run_llm: 'true',
});

// 永不回复（静默上下文更新）
client.updateContext({
  text: '用户生命值：10/100',
  run_llm: 'false',
});

// 由服务器决定（默认）
client.updateContext({
  text: '天气已变为暴风雨。',
  run_llm: 'auto',
});

通过以下方式监控令牌使用情况 serverResponse

服务器会在每次 context-update:

client.on('serverResponse', (response) => {
  if (response.event_type === 'context-update' && response.status === 'success') {
    const { remaining_tokens, max_tokens } = response.extras ?? {};
    console.log(`上下文令牌：${max_tokens - remaining_tokens} / ${max_tokens}`);
  }
});

---

updateDynamicInfo

更简单的 updateContext —— 总是追加，并且永远不会触发机器人回复。

client.updateDynamicInfo('玩家生命值降至 30%。');

等同于：

client.updateContext({ text: '...', mode: 'append', run_llm: 'false' });

用于 updateContext 完全控制； updateDynamicInfo 用于快速静默更新。

---

叙事设计模板键

模板键可为每个会话定制叙事设计图。章节目标和说话标签可以包含占位符，例如 {player_name} 或 {quest_item} （单花括号）；当章节被评估时，Convai 会用你的值替换它们，因此一个叙事图可以服务于多个个性化会话。

控制台设置（前提条件）

在角色的叙事设计图引用这些键之前，模板键不会生效。在控制台中：

1. 在角色上 启用叙事设计
2. 创建一个章节 其 目标 （并且可选地 说话标签）包含你的占位符：

   向客人问好。请说出这句完整的欢迎语："{StartMessage}"。角色扮演上下文：{Situation}。

   占位符只会解析 在 章节目标和说话标签中—— {placeholder} 写入角色基础提示、问候语或触发消息中的内容会按字面原样播出。
3. 创建一个命名触发器 指向该章节，并带有一个 触发消息 （必填字段——例如“有位客人走进旅馆大门。现在向他们问好。”）。客户端通过以下方式触发它 sendTriggerMessage('<trigger name>') —— 名称必须完全匹配（区分大小写）。触发消息才会使机器人在触发时回复；带有目标但触发消息为空的触发器（仅可通过 REST API 实现）会静默更改章节 静默地 并且服务器会确认 “触发已处理，但未生成上下文”.
4. 还可以设置图的 起始章节 —— 它会在会话开始时自动进入，因此在连接时，配置中传入的键会在任何触发器触发之前应用到它。

为了获得确定性的测试输出，请将占位符放在章节的说话标签中——说话标签内容会经过相同的替换，并按原文播出。

有 一张键映射 ，可通过两种方式设置：

在会话开始时预设： narrativeTemplateKeys config

作为 narrative_template_keys 发送于 /connect 请求中。

const client = new ConvaiClient({
  apiKey: 'your-api-key',
  characterId: 'your-character-id',
  narrativeTemplateKeys: {
    player_name: 'Alex',
    location: 'Engineering Deck',
    quest_item: 'oxygen generator',
  },
});

如果章节目标是 向 {player_name} 问好。请他们修理 {quest_item}。，则机器人会收到 向 Alex 问好。请他们修理氧气发生器。

会话中更新： updateTemplateKeys()

在活动会话中替换相同的键映射。在触发进入使用新值的章节之前调用它：

client.updateTemplateKeys({
  player_name: 'Alex',
  location: 'Medical Bay',        // 玩家已移动
  quest_item: 'med kit',
});
client.sendTriggerMessage('NextObjective');

这是完全替换，而不是合并 —— 传入图仍然需要的每个键，或者被省略的键将解析为空字符串。

规则

• 需要一个已启用 叙事设计的角色。没有它， narrativeTemplateKeys 会被忽略，并且 updateTemplateKeys() 会以 status: "error" — "Narrative design service not available" （监听 serverResponse 用于 update-template-keys ack）。
• 占位符语法是在一个单词外包裹单花括号： {player_name}。键区分大小写，且必须与图中的占位符名称完全匹配。
• 替换发生在章节目标/说话标签被 评估时，而不是在键发送时——键只需要在触发器触发前准备好即可。
• 没有匹配键的占位符会解析为 空字符串 （不会保留为字面文本）。如果角色 说出 一个字面 {placeholder}，说明文本根本没有经过叙事设计——请检查它是否位于章节目标或说话标签中，而不是基础提示或问候语中。
• trigger_name 和 trigger_message 是保留字段。 在每个命名触发器中，服务器都会把它们注入键映射（覆盖你的键），因此不要把这些名称用于你自己的键——但你 可以 在目标中 {trigger_name} / {trigger_message} 自由引用。

故障排除

症状	原因
确认： "Narrative design service not available"	角色未启用叙事设计
确认： “触发已处理，但未生成上下文”	角色上不存在该触发器名称，或者该触发器的触发消息为空，且其目标章节没有说话标签（静默章节更改）
机器人说出字面 {placeholder}	占位符位于叙事设计之外（基础提示、问候语、触发消息）——请把它移到章节目标或说话标签中
机器人说出空值	键映射中缺少该键——请记住 updateTemplateKeys() 会替换整个映射，并且键区分大小写

---

文件上传

在活动会话中使用 uploadFile直接向角色发送文件。角色会将文件作为对话上下文的一部分接收，并可以对其内容作出回应。

await client.uploadFile(file, {
  onProgress: (pct) => console.log(`${pct}% 已上传`),
});

React

const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
  const file = e.target.files?.[0];
  if (!file) return;

  await client.uploadFile(file, {
    onProgress: (pct) => setProgress(pct),
  });
};

原生 JS

document.querySelector('#file-input').addEventListener('change', async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (!file) return;

  await client.uploadFile(file, {
    onProgress: (pct) => progressBar.style.width = `${pct}%`,
  });
});

选项

字段	类型	默认值	描述
主题	string	"file-upload"	上传通道的路由标识符
onProgress	(pct: number) => void	—	在上传进度中调用，参数为 0–100 的整数

支持的格式

格式	MIME 类型
JPEG	image/jpeg
PNG	image/png
GIF	image/gif
WebP	image/webp

最大文件大小： 10 MB。文件以原始二进制形式发送——不是 base64 编码。

错误处理

uploadFile 是异步的，失败时会抛出异常——务必将其包裹在 try/catch 中：

try {
  await client.uploadFile(file, { onProgress: setProgress });
} catch (err) {
  // 常见原因：
  // - 未连接（传输未就绪）
  // - 文件类型不受支持（仅 JPEG、PNG、GIF、WebP）
  // - 文件超过 10 MB
  // - 传输中发生网络错误
  console.error('上传失败：', err);
}

在调用前先验证类型和大小，这样可以给用户一个快速的本地错误，而不是等待传输失败：

const SUPPORTED = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];

if (!SUPPORTED.includes(file.type)) throw new Error(`不支持的类型：${file.type}`);
if (file.size > 10 * 1024 * 1024) throw new Error('文件超过 10 MB');

await client.uploadFile(file, { onProgress: setProgress });

注意

• 仅在使用 WebRTC 传输（transport: "livekit"，默认值）连接时可用。WebSocket 传输不支持。
• 在未连接时调用该方法会抛出异常。请先检查 client.state.isConnected 。

---

场景元数据

用于 updateSceneMetadata 用于描述环境变化。这 不会 添加新的动作目标——它只给机器人提供叙事上下文。

client.updateSceneMetadata([
  { name: 'fog', description: '一层浓雾已经弥漫开来，能见度很低。' },
  { name: 'ambience', description: '远处雷声和风声。' },
]);

如果机器人需要 作用于 场景中的对象，它们必须在 actionConfig.objects 中于连接时声明。参见 Actions。

---

会话管理

重置对话

resetSession() 会清除消息历史并开启一个新的对话线程。角色会忘记当前交流，但会保留任何长期记忆（如果 endUserId 已设置）。

await client.disconnect();
client.resetSession();
await client.connect();

空闲超时

服务器会在可配置的超时时间后断开空闲会话。使用 resetIdleTimer() 在任何用户交互时保持会话存活。

// 在点击、按键或任何用户活动时调用
document.addEventListener('click', () => {
  if (client.state.isConnected) {
    client.resetIdleTimer();
  }
});

// 在断开连接前监听警告
client.on('idleWarning', ({ remainingSeconds }) => {
  showBanner(`会话将在 ${remainingSeconds}s 后过期——点击继续`);
});

---

长期记忆

当 endUserId 提供时，角色会跨会话构建持久记忆。通过以下方式访问它们 client.memoryManager.

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  endUserId: 'user-uuid or any unique userid', // 启用记忆
});

// 连接后：
const memory = client.memoryManager;

if (memory) {
  // 列出记忆
  const { memories, total_count } = await memory.listMemories({ page: 1, pageSize: 20 });

  // 手动添加一条记忆
  await memory.addMemories(['用户是一名偏好 TypeScript 的软件工程师。']);

  // 删除特定记忆
  await memory.deleteMemory(memories[0].id);
}

完整参考请参阅 Memory API。