主题

AI 助手 JS SDK 集成指南 ​

本文档将引导您通过几个简单的步骤，将 AI 助手集成到您的系统中。

获取 Copilot SDK 链接 ​

为了确保您的系统集成了最新且适配的 Copilot AI 助手功能，您需要进入设置->功能配置->AI 助手->控制台页面，点击选项->Copilot SDK打开集成页面指南，在抽屉弹窗中，您将找到用于集成的 SDK 链接，格式类似于 https://develop.hengshi.org/assets/hengshi-copilot@5.2.js。请复制此链接。

在其他系统中集成 Copilot SDK ​

首先，您需要在 HTML 文档的<head>部分引入 SDK 文件。我们提供了一个示例代码块，您可以根据需要进行调整：

html
<!-- 引入 SDK 文件 -->
<script
  type="text/javascript"
  src="https://develop.hengshi.org/assets/hengshi-copilot@5.2.js"> 
</script>

接着，在页面上添加一个按钮，用于触发 AI 助手的显示：

html
<button id="trigger-ai">显示 AI 助手</button>

登录认证 ​

集成 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 参数。

在衡石系统中集成 Copilot ​

在衡石系统中集成 Copilot 稍微有些不同。首先，确保您的全局 JS 文件中包含了以下代码：

js
// 1. 保持 copilot sdk 与系统的 store 数据同步
window.__INITIAL_STATE__ = window._hs_store_.getState();
// 2. 引入 copilot sdk 代码
var script = document.createElement('script');
script.type = 'text/javascript';
script.src = 'https://develop.hengshi.org/assets/hengshi-copilot@5.2.js';
script.onload = function() {
  // 3. 重置 sdk base url
  window.__hs_sdk_base_url__ = undefined;
  // 4. 创建 sdk 容器
  var copilotRoot = document.createElement('div');
  copilotRoot.id = 'copilot-root';
  copilotRoot.style.width = '100%';
  copilotRoot.style.height = '100%';
  copilotRoot.style.position = 'fixed';
  copilotRoot.style.top = '0';
  copilotRoot.style.left = '0';
  copilotRoot.style.zIndex = '9999';
  copilotRoot.style.pointerEvents = 'none';
  document.body.appendChild(copilotRoot);
  // 5. 赋值给自定义 sandbox 变量以便自定义 js 能使用
  window.myJS = window.myJS || {};
  window.myJS.innerWidth = window.innerWidth;
  window.myJS.innerHeight = window.innerHeight;
  window.myJS.Copilot = Copilot;
  window.myJS.CopilotRoot = copilotRoot;
};
document.body.appendChild(script);

然后，您可以在仪表盘中使用控件按钮来唤起 Copilot，在按钮控件的设置中添加点击事件，执行相应的 JS 代码。

js
if (!myJS.copilotConfig) {
  myJS.copilotConfig = {
    locale: 'zh-CN',
    stylesheet: 'html.hengshi-copilot-sdk, html.hengshi-copilot-sdk body {  width:100% !important; height: 100% !important;}html.hengshi-copilot-sdk body.hst {  background: transparent;}.react-draggable {  pointer-events: all;}',
    draggable: {
      enable: true,
      minWidth: 440,
      minHeight: 440,
      position: {
        x: myJS.innerWidth - 480,
        y: 20,
      },
      size: {
        width: 440,
        height: myJS.innerHeight * 0.8,
      },
      // 设定记住拖动的位置和大小
      onDragStop: onDragStop,
      onResize: onResize,
    },
    // 设置对话数据来源
    userConfig: {
      appId: 354, // 数据包 id
      datasetId: 26, // 数据集 id
    },
  };
}
function onDragStop(event, position) {
  myJS.copilotConfig.draggable.position = position;
}
function onResize(event, position, size) {
  myJS.copilotConfig.draggable.position = position;
  myJS.copilotConfig.draggable.size = size;
}
function launchCopilot() {
  if (typeof myJS.Copilot === 'undefined') {
    (function (fn) {
      fn(launchCopilot);
    })(requestIdleCallback || setTimeout);
  } else {
    myJS.copilot = new myJS.Copilot(myJS.CopilotRoot, myJS.copilotConfig);
  }
}
if (myJS.copilot) {
  myJS.copilot.destroy();
  myJS.copilot = null;
} else {
  launchCopilot();
}

在 JavaScript 中使用 Copilot ​

在您的 JavaScript 文件中，首先引入 SDK 文件，然后创建一个容器并初始化 Copilot 实例：

js
// Ingest SDK file
var script = document.createElement('script');
script.type = 'text/javascript';
script.src = 'https://develop.hengshi.org/assets/hengshi-copilot@5.2.js';
script.onload = launchCopilot;
document.head.appendChild(script);
var copilotRoot = document.createElement('div')
copilotRoot.id = 'copilot-root';
// Add container to your page
document.body.appendChild(copilotRoot);
function launchCopilot() {
  if (typeof Copilot === 'undefined') {
    (function(fn) {
      fn(launchCopilot);
    })(requestIdleCallback || setTimeout);
  } else {
    var copilotConfig = {
      locale: 'zh-CN',
      // 设置对话框位置和大小
      style: {
        // position 固定为 fixed
        width: '440px',
        height: '440px',
        bottom: '20px',
        right: '20px',
        borderRadius: '10px',
        overflow: 'hidden',
      },
      // 设置对话数据来源
      userConfig: {
        appId: 130870, // 数据包 id
        datasetId: 1, // 数据集 id
      },
    };
    var copilot = new Copilot(copilotRoot, copilotConfig);
  }
}

配置 Copilot ​

Copilot 的配置非常灵活，您可以根据需要调整配置项：

ts
// Copilot 配置定义
interface ICopilotConfig {
  userConfig: {
    appId: number;
    datasetId?: number;
    chartId?: number;
  };
  draggable?: {
    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;
  };
}

// 创建 Copilot 配置对象
const copilotConfig: ICopilotConfig = {
  userConfig: {
    // appId 和 datasetId 或 chartId 必须提供其中之一
    // 示例：appId: 130870, datasetId: 1 // 数据包 id + 数据集 id
    // 或者
    // appId: 130870, chartId: 1 // 应用 id + 图表 id
  },
  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);
    },
  },
};

自定义 AI 助手样式 ​

如果您想自定义 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 copilotConfig: ICopilotConfig = {
  ...
  stylesheet: css, 
  ...
};

衡石分析平台使用手册

版权所有 © 2016-2024 hengshi.com