Keural Kit

将 Keural 对话、云盘和提示词界面嵌入您的网页服务中的嵌入脚本。

Keural Kit 通过一个脚本即可将 Keural 界面放入您的页面。界面绘制在 Shadow DOM 中，因此不会与您页面的 CSS 混在一起。Kit 会随 Keural 网页版部署一同更新。部署后若仍显示旧界面，请清除浏览器和 CDN 缓存，并通过 window.KeuralKit.__build 确认构建时间。

Kit 依赖 Keural 登录会话（Keural API 域名下的 Cookie）运行。userInfo 仅用于界面显示，用户身份通过 Cookie 会话确认。若要在您的服务域名中使用，请在接入前与 Keural 负责人协商域名登记和登录对接（如 SSO）。

加载

Kit 从您所使用的 Keural 环境的网址加载。keural.ai 为 https://keural.ai，本地部署或专用环境则为该环境的 Keural 网址。脚本之前，请先将 Kit 要调用的服务器地址设置到 window.__KEURAL_ENV__。这三个地址必须属于同一环境，接入时向负责人获取。

<script>
  window.__KEURAL_ENV__ = {
    NEXT_PUBLIC_API_BASE_URL: '<KEURAL_API_URL>',
    NEXT_PUBLIC_FAST_API_BASE_URL: '<KEURAL_AGENT_URL>',
    NEXT_PUBLIC_MODE: 'prd',
  };
</script>
<script src="<KEURAL_WEB_URL>/plugin/kit/keural.js" async></script>

值	说明
`<KEURAL_WEB_URL>`	Keural 网址。例：`https://keural.ai`
`<KEURAL_API_URL>`	Keural API 服务器地址。例：`https://api.keural.ai`
`<KEURAL_AGENT_URL>`	Keural 智能体服务器地址
`NEXT_PUBLIC_MODE`	生产环境为 `prd`，开发环境为 `dev`

若要在第二个域名中也使用同一 Kit，请同时设置 NEXT_PUBLIC_ADDITIONAL_FRONTEND_URL、NEXT_PUBLIC_ADDITIONAL_API_BASE_URL、NEXT_PUBLIC_ADDITIONAL_FAST_API_BASE_URL 三个值。缺少任何一个都会报错。值为不含路径的 https:// 地址。

脚本加载后会生成 window.KeuralKit。在 React 等 SPA 中，请使用加载器，确保脚本只加载一次。

export function loadKeuralKit(src = '<KEURAL_WEB_URL>/plugin/kit/keural.js') {
  if (window.KeuralKit) return Promise.resolve(window.KeuralKit);
  return new Promise((resolve, reject) => {
    const s = document.createElement('script');
    s.src = src;
    s.async = true;
    s.onload = () => resolve(window.KeuralKit);
    s.onerror = () => {
      s.remove();
      reject(new Error('Keural Kit failed to load'));
    };
    document.head.appendChild(s);
  });
}

嵌入对话

const el = document.getElementById('keural-chat')!;

window.KeuralKit.mountChat(el, {
  userInfo: { userId: user.id, name: user.name },
  colorMode: 'light',
  initialData: { message: '总结一下本季度的营收', room_name: '季度报告' },
  onSessionCreated: (roomId) => router.push(`/c/${roomId}`),
  onError: () => router.push('/'),
});

// 离开界面时
window.KeuralKit.unmount(el);

若要打开已有对话，请在 sessionId 中填入对话 ID。
initialData 仅在打开新对话时填写。打开已有对话时填写，同一条消息会被再次发送。
若缺少 userInfo.userId，则按未登录处理。请在登录信息准备好之后再挂载。

方法

方法	说明
`mountChat(el, options)`	对话界面
`mountDrivePage(el, options)`	云盘界面。通过 `onAsk(files)` 接收要提问的文件
`mountPromptPage(el, options)`	提示词界面。通过 `onAsk(prompts)` 接收所选的提示词
`mountDriveDialog(el, options)` / `updateDriveDialog`	云盘文件选择窗口（必须提供 `open`，另有 `onClose`、`onSelect(files)`、`initialSelected`）
`mountPromptDialog(el, options)` / `updatePromptDialog`	提示词选择窗口（必须提供 `open`，另有 `onClose`、`onSelect`、`onDefaultSelect`、`selectDefaultPrompt`、`defaultPromptDismissed`）
`unmount(el)`	移除已挂载的界面

mount* 和 update* 方法同时接收 colorMode 和 userInfo，unmount(el) 只接收元素。update* 会用新选项重新绘制同一元素。打开和关闭窗口时，请更改 open 的值并调用 update*。对同一元素再次调用 mount* 时，将复用已有界面。

mountChat 选项

选项	类型	说明
`sessionId`	`string`	要打开的对话 ID。若不填，则开始新对话
`userInfo`	`{ userId, name?, orgId?, orgName? }`	用户信息。`userId` 为必填
`initialData`	`object`	新对话的第一条消息。参见下方的 initialData
`colorMode`	`'light' \| 'dark'`	主题。默认 `light`
`initialEffort`	`'fast' \| 'balanced' \| 'high' \| 'xhigh' \| 'max'`	初始级别。默认 `fast`
`initialWebSearch`	`boolean`	以开启网页搜索的状态开始。默认 `true`
`initialDeepResearch`	`boolean`	以开启 Deep Research 的状态开始
`hideHomeButton` / `hideNewChatButton`	`boolean`	隐藏标题栏按钮
`hideModePopup`	`boolean`	隐藏模式选择弹窗
`messageActions`	`{ id, label, onClick(messageId) }[]`	在回答菜单中添加自定义操作
`headerLeftActions` / `headerRightActions`	`HeaderLeftAction[]`	在标题栏中添加自定义按钮
`onHeaderLeftMount`	`(el: HTMLElement) => void`	标题栏左侧区域绘制后，接收该元素
`mobileMenuItems` / `mobileBottomActions`	`array`	在移动端宽度下添加菜单或底部按钮
`onMobileHomeButton`	`() => void`	在移动端宽度下点击首页按钮时
`chatInputFooter`	`string`	输入框下方的提示文字
`shareTooltip`	`string`	分享按钮的提示文字
`onSessionCreated`	`(roomId) => void`	创建新对话时
`onStreamDone`	`(roomId) => void`	回答结束时
`onSummaryDone`	`(roomId) => void`	对话标题和摘要生成时
`onRoomInfo`	`(info) => void`	对话信息变化时
`onShare` / `onExport`	`(roomId) => void`	点击分享或导出按钮时
`onError`	`(error: Error) => void`	发生错误时

initialData

字段	类型	说明
`message`	`string`	必填。第一条消息
`files`	`FileType[]`	一并发送的云盘文件（即 `mountDriveDialog` 的 `onSelect` 接收到的值）
`prompts`	`object[]`	一并使用的提示词
`webSearch`	`boolean`	网页搜索
`deepResearch`	`boolean`	Deep Research
`effort`	`'fast' \| 'balanced' \| 'high' \| 'xhigh' \| 'max'`	级别
`model`	`{ label, value }`	用于回答的模型
`room_name`	`string`	对话名称。同时接受 `roomName`、`title`、`name`。
`folder_id`	`string \| null`	保存到的文件夹
`hideModePopup`	`boolean`	隐藏模式选择弹窗

界面语言

Kit 界面以韩语显示。

用户设置请在 Keural 网页版或应用中更改，Kit 界面会遵循这些设置。
登录由您的服务处理，Kit 只接收已登录用户的信息。

Keural Kit

加载复制锚点链接

嵌入对话复制锚点链接

方法复制锚点链接

mountChat 选项复制锚点链接

initialData复制锚点链接

界面语言复制锚点链接

设置与登录复制锚点链接

本页目录

加载

嵌入对话

方法

mountChat 选项

initialData

界面语言

设置与登录