chatkit

@ 与 /

在输入框里输入 @ 选择提及对象，输入 / 选择指令。在 features.mentions 里给了候选项才开启，给了哪个开哪个。

mentions.tsx
import { Chatkit, type ChatkitMentionSource, type ChatkitSlashSource, useChatRuntime } from '@volcengine/chatkit';
import { createMockAdapter } from '@volcengine/chatkit/adapters/mock';
import '@volcengine/chatkit/styles.css';

const adapter = createMockAdapter({});

const mention: ChatkitMentionSource = {
  option: [
    { label: '产品经理 Agent', value: 'pm-agent', tips: '需求分析' },
    { label: '代码审查 Agent', value: 'review-agent', tips: '只读仓库' },
    { label: '数据分析 Agent', value: 'data-agent' },
  ],
};

const slash: ChatkitSlashSource = {
  option: [
    { label: '总结', value: 'summarize', tips: '总结上面的对话' },
    { label: '翻译', value: 'translate', tips: '中英互译' },
    { label: '写周报', value: 'weekly-report' },
  ],
};

// 在输入框里输入 @ 选择提及对象，输入 / 选择指令；选中的内容以标签形式插进正文。
// 给了哪个就开哪个。
export default function Mentions() {
  const runtime = useChatRuntime({ sessionId: 'mentions', adapter });
  if (!runtime) return null;
  return (
    <Chatkit
      runtime={runtime}
      settings={{ welcome: '在输入框里输入 @ 或 /', placeholder: '输入 @ 提及，输入 / 选择指令' }}
      features={{ mentions: { mention, slash } }}
    />
  );
}
输入 @ 或 / 试试新窗口打开

用法

import type { ChatkitMentionSource, ChatkitSlashSource } from '@volcengine/chatkit';

const mention: ChatkitMentionSource = {
  option: [
    { label: '销售助手', value: 'agent-sales', kind: 'agent' },
    { label: '周报.docx', value: 'file-weekly', kind: 'file' },
  ],
};
const slash: ChatkitSlashSource = {
  option: [{ label: '总结', value: 'summarize', kind: 'command', tips: '总结当前对话' }],
};

<Chatkit sessions={sessions} features={{ mentions: { mention, slash } }} />;

配置项

配置项类型默认说明
features.mentions.mentionChatkitMentionConfig—`@` 提及的候选项。
features.mentions.slashChatkitSlashCommandConfig—`/` 指令的候选项。

mention / slash 的常用字段：

字段作用
option候选项：{ label, value?, kind?, tips?, icon? }；kind 用于结构化引用
char / chars触发字符，默认 @ / /
matchQuery / getSearchText自定义过滤规则（默认子串匹配）
renderItem / renderPopover自定义候选项与面板
onSelect / getInsertValue选中后做什么、插入什么

说明

  • 默认选中后插入带触发字符的标签。带 kind 的选项在 onSend.content 中是 type: 'reference'，交给适配器时同时生成文字和 { kind, id, label } 形式的 references；id 优先取 value。请求中的具体位置由适配器决定。
  • 没有 kind 的标签按文本编码，不生成结构化引用：例如英文标签可能是 @agent()、/summarize()；中文标签不能编码成标记时会尝试 value，仍不符合时保留显示文字。不能依赖一律发送 @名称 的假设。
  • / 只提供选择与插入，不会自动执行指令。设置 onSelect 会接管选中行为，默认插入不再执行；只定制插入内容时用 getInsertValue。
  • 从输入框之外插入一个引用（比如点技能面板里的一项）：useComposer().insertReference(...)，见技能选择。
  • 只拦截指令、不发给后端的做法见发送前处理。