中文 (简体)

English (US)

中文 (简体)

English (US)

主题

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 时，您可能需要进行登录认证。我们提供两种方式：

  1. SSO 单点登录：如果您的系统已与衡石系统集成，无需额外登录。
  2. 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
  },
};

衡石分析平台使用手册

版权所有 © 2016-present hengshi.com