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 網頁版或 App 中變更，Kit 畫面會遵循該設定。
- 登入由你的服務處理，Kit 只會接收已登入使用者的資訊。