SDK 集成
配置项
ts
interface DataSource {
appId: number;
chartId?: number;
dataAppId: number;
datasetId?: number;
}
interface Config {
userConfig: DataSource | {
dataSources: DataSource[];
};
closable?: boolean;
draggable?: boolean | {
enable: boolean;
minWidth: number;
minHeight: number;
bounds: 'window' | 'parent';
position: {
x: number;
y: number;
};
size: {
width: number;
height: number;
};
};
locale?: string;
stylesheet?: string;
className?: string;
style?: React.CSSProperties;
bodyClassName?: string;
bodyStyle?: React.CSSProperties;
header?: string | React.ReactElement;
systemMsg?: string;
parser?: {
selectText: string;
onSelect: (chart: any) => void;
};
chartTheme?: string | Theme;
}
interface Theme {
base?: string | number;
background?: string;
color?: string;
fontSize?: number;
fontFamily?: any;
fontWeight?: string;
textAlign?: string;
borderColor?: string;
borderWidth?: number;
borderStyle?: string;
borderRadius?: number;
boxShadow?: string;
chartBackground?: string;
chartPadding?: number;
schema?: string[];
mapTheme?: string;
}
// 创建 Copilot 配置对象
const config: Config = {
userConfig: {
dataSources: [{
// appId 和 datasetId 或 chartId 必须提供其中之一
// 示例:appId: 130870, datasetId: 1 // 数据包 id + 数据集 id
// 或者
// appId: 130870, chartId: 1 // 应用 id + 图表 id
}],
},
closable: true, // 可选,是否显示关闭按钮,默认为 false
draggable: { // 可选,是否可拖拽,默认不可以拖拽
enable: false,
minWidth: 400,
minHeight: 400,
bounds: 'window',
position: {
x: window.innerWidth - 480,
y: 20,
},
size: {
width: 440,
height: window.innerHeight * 0.8,
},
},
locale: 'zh-CN', // 可选,语言设置,默认为中文简体
stylesheet: '', // 可选,自定义 CSS 样式
className: '', // 可选,自定义类名
style: {}, // 可选,自定义样式
bodyClassName: '', // 可选,对话框内容容器的类名
bodyStyle: {}, // 可选,对话框内容容器的样式
header: '', // 可选,标题内额外内容
systemMsg: '欢迎使用智能分析助手', // 可选,欢迎语,默认值
parser: {
selectText: '选择图表', // 按钮文案
onSelect: (chart) => {
// 点击按钮时触发的事件,chart 参数需要根据实际使用场景定义类型
console.log('图表选择事件', chart);
},
},
chartTheme: 'HAWAII_SEA', // 可选,图表主题,参考仪表盘主题
};
登录认证
集成 SDK 时,您可能需要进行登录认证。我们提供两种方式:
- SSO 单点登录:如果您的系统已与衡石系统集成,无需额外登录。
- JWT 认证:通过以下代码使用 JWT 进行登录认证:
js
fetch('https://develop.hengshi.org/api/auth/login-info?activeAuth=jwt-param&jwtParam=您的 JWT 参数')
.then(response => {
// 登录成功,继续使用 SDK
})
.catch(error => {
// 登录失败,处理错误
});
提示
确保您已经在 '设置->组织管理->认证方式->JWT 请求参数' 中配置了 JWT。
请将 '您的 JWT 参数' 替换为实际的 JWT 参数。
自定义样式
如果您想自定义 AI 助手的样式,可以通过以下 CSS 代码实现:
css
/* 示例: 使用 css 批量自定义皮肤样式 */
*, ::before, ::after {
--brand: #4CAF50; // 这是系统整体的品牌色
}
/* 设置 AI 助手对话框根元素样式 */
.hengshi-copilot-sdk .hst-copilot {
position: fixed;
// z-index: 1; // 按需设定
top: 10vh;
right: 50px;
width: 440px;
height: 80vh;
border-width: 1px;
}
/* 设置 AI 助手 标题 元素样式 */
.hengshi-copilot-sdk .hst-copilot-header {
color: #fff;
background-color: darkslategray;
}
/* 设置 AI 助手 对话区域 元素样式 */
.hengshi-copilot-sdk .hst-copilot-conversations {
border-color: #aaa;
background-color: darkslategray;
height: calc(100% - 50px);
}
/* 设置 AI 助手 消息 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg,
/* 设置 AI 助手 消息下方 ICON 操作 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg > .hs-relative > *,
/* 设置 AI 助手 辅助信息 元素样式 */
.hengshi-copilot-sdk .hst-copilot-mark {
color: #fff;
}
.hengshi-copilot-sdk .hst-copilot-mark .hs-bg-\[color\:var\(--hs-bg-lighter\)\] {
background-color: transparent;
}
/* 设置 AI 助手 消息下方 ICON 操作 hover 时 元素背景样式 */
.hengshi-copilot-sdk .hover\:hs-bg-\[\#eee\]:hover {
--tw-bg-opacity: .2;
}
/* 设置 AI 助手 AI 消息气泡 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg-bot .hst-copilot-msg-inner,
/* 设置 AI 助手 用户消息气泡 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg-user .hst-copilot-msg-inner {
border-color: darkgray;
background-color: darkgray;
}
/* 设置 AI 助手推荐问题的问题气泡背景色 */
.hengshi-copilot-sdk .hst-copilot-msg-inner .hst-copilot-msg-inner {
background-color: slategray !important;
}
/* 设置 AI 助手 输入内容区域 元素样式 */
.hengshi-copilot-sdk .hst-copilot-prompt {
color: #fff;
background-color: darkslategray;
}
/* 设置 AI 助手 输入框 元素样式 */
.hengshi-copilot-sdk .hst-copilot-prompt textarea {
color: #fff;
border-color: darkgray !important;
}
.hengshi-copilot-sdk .hst-copilot-prompt .hs-from-\[\#f1f1f1\],
.hengshi-copilot-sdk .hst-copilot-prompt .hs-to-\[\#f1f1f1\] {
--tw-gradient-to: darkslategray;
}
将上述 css 作为字符串传递在 Copilot 配置中的 stylesheet 即可:
ts
// 创建 Copilot 配置对象
const config: Config = {
...
stylesheet: css,
...
};
API 方式的集成也有前端和后端两种方式,前端方式直接调用 Copilot SDK 提供的 js API,后端方式则通过 http 接口。
拦截 api 请求、自定义 api 请求
你可以在 copilotConfig
中配置 api
拦截 api 请求、自定义 api 请求。
有下列 api 可以配置:
- requestFetchConversations: 获取对话列表
- requestCreateConversation: 创建对话
- requestFetchConversation: 获取对话详情
- requestDeleteConversation: 删除对话
- requestFetchChats: 获取一个对话里聊天记录
- requestCreateChat: 创建一条聊天记录
- requestFetchChat: 获取一条聊天记录
- requestUpdateChat: 更新一条聊天记录
- requestDeleteChat: 删除一条聊天记录
- requestfetchChatLogs: 获取一条聊天记录的日志
- requestRegenerateChat: 重新生成回答
每一个 api 都是一个 js function,接收的参数是一个 object, 规则如下:
- requestFetchConversations({ offset?: number, limit?: number })
- requestCreateConversation({ body: { title: string }})
- requestFetchConversation({ id: number })
- requestDeleteConversation({ id: number })
- requestFetchChats({ id: number, offset?: number, limit?: number })
- requestCreateChat({ id: number, body: { prompt: string, userConfig: object }})
- requestFetchChat({ id: number, chatUid: string })
- requestUpdateChat({ id: number, chatUid: string, body: object })
- requestDeleteChat({ id: number, chatUid: string })
- requestfetchChatLogs({ id: number, chatUid: string })
- requestRegenerateChat({ id: number, chatUid: string })
function 返回值也是一个 object,格式如下:
js
{
abort: function abort() {}, // abort 接口请求
value: Promise, // 接口请求的 Promise
}
例如你想要在每一次对话创建时,拦截请求并添加一些自定义参数,你可以这样配置:
js
const copilotConfig = {
// ...
api: {
// 自定义创建对话的 api
requestCreateChat: params => {
// 添加一些自定义参数
if (!params.body.yourCustomProperty) {
params.body.yourCustomProperty = 'yourCustomValue';
}
return copilotInstance.context.endpoints.requestCreateChat(params);
},
// ... 也可以配置其他 api
},
};