情绪

启用情绪检测，以在对话期间接收角色的情绪状态。启用情绪检测，以在每次回复时一并接收角色的情绪状态。

连接时启用

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  enableEmotion: true,
});

当 enableEmotion 为 true，SDK 会发送 emotion_config 到服务器。如果没有它，就不会发送任何 bot-emotion 帧，并且 emotionChange 从不触发。

---

订阅 emotionChange

client.on('emotionChange', (emotion) => {
  if (emotion === null) {
    // 对话重置 — 清除任何情绪 UI
    return;
  }
  console.log(emotion.emotion); // 例如：“Trust”、“Grief”、“Joy”
  console.log(emotion.scale);   // 整数强度：1（低）→ 3（高）
});

事件触发时：

• 每次角色轮次后触发，带有检测到的情绪和强度
• 在 null 当对话被重置时（例如 resetSession())

---

React

import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk';
import { useEffect, useState } from 'react';

export default function App() {
  const client = useConvaiClient({
    apiKey: '...',
    characterId: '...',
    enableEmotion: true,
  });

  const [emotion, setEmotion] = useState<{ emotion: string; scale?: number } | null>(null);

  useEffect(() => {
    return client.on('emotionChange', setEmotion);
  }, [client]);

  return (
    <>
      {emotion && (
        <div style={{ position: 'fixed', top: 20, right: 20 }}>
          {emotion.emotion} ({emotion.scale})
        </div>
      )}
      <ConvaiWidget convaiClient={client} />
    </>
  );
}

client.on(...) 返回一个取消订阅函数 — 将其从 useEffect 中返回会自动清理。

通过 state.emotion

情绪也可在响应式状态对象上同步获取——如果你已经从 state 渲染，则无需额外订阅：

// 每当 stateChange 触发时，emotion 都会更新 — 无需 useEffect
<div>{client.state.emotion?.emotion}</div>

---

原生 JS

import { ConvaiClient } from '@convai/web-sdk/core';
import { createConvaiWidget } from '@convai/web-sdk/vanilla';

const client = new ConvaiClient({
  apiKey: '...',
  characterId: '...',
  enableEmotion: true,
});

const emotionEl = document.querySelector('#emotion');

const unsubEmotion = client.on('emotionChange', (emotion) => {
  if (emotionEl) {
    emotionEl.textContent = emotion ? `${emotion.emotion} (${emotion.scale})` : '';
  }
});

createConvaiWidget(document.body, { convaiClient: client as any });

// 清理时
// unsubEmotion();

---

微调检测

通过以下方式控制情绪检测的激进程度： emotionConfig:

支持两种提供方： "llm" 使用语言模型从回复文本中推断情绪； "nrclex" 使用 NRC 情绪词典，这是一种按词级别查找的词典，速度更快但上下文感知较弱。

// LLM 提供方（默认）— 无需额外选项
useConvaiClient({
  apiKey: '...',
  characterId: '...',
  enableEmotion: true,
  emotionConfig: { provider: 'llm' },
});

// NRCLex 提供方 — 支持强度阈值
useConvaiClient({
  apiKey: '...',
  characterId: '...',
  enableEmotion: true,
  emotionConfig: {
    provider: 'nrclex',
    min_word_threshold: 3,        // 跳过短于此长度的轮次
    low_intensity_threshold: 0.33,  // 分数低于此值 → 级别 1
    high_intensity_threshold: 0.66, // 分数高于此值 → 级别 3；介于两者之间 → 级别 2
  },
});

"llm" 配置

字段	类型	说明
提供方	"llm"	使用 LLM 从回复上下文推断情绪

"nrclex" 配置

字段	类型	默认值	说明
提供方	"nrclex"	—	词级别的 NRC 情绪词典查找
min_word_threshold	数字	3	跳过少于此词数的轮次的检测
low_intensity_threshold	数字	0.33	级别 1 和级别 2 之间的分数边界
high_intensity_threshold	数字	0.66	级别 2 和级别 3 之间的分数边界

---

API 参考

enableEmotion （连接选项）

字段	类型	默认值	说明
enableEmotion	布尔值	false	启用情绪检测。必须 true 用于 emotionChange 才会触发。

emotionChange 事件

client.on('emotionChange', (emotion: { emotion: string; scale?: number } | null) => { ... });

字段	类型	说明
emotion	string	情绪标签（例如 "Trust", "Grief", "Joy")
scale	数字	强度： 1 = 低， 2 = 中， 3 = 高

触发 null 在对话重置时。

state.emotion

client.state.emotion // { emotion: string; scale?: number } | null

与最后一个 emotionChange 有效载荷相同。可在 React 钩子中通过以下方式实现响应式： stateChange.