中文 (简体)

English (US)

中文 (简体)

English (US)

主题

JS SDK 集成指南 ​

如果你们希望保留自己的页面、入口和业务壳，但又不想自己从零实现数据问答界面和结果渲染，那么应该使用 JS SDK。

不过在看 SDK 之前，也建议先想清楚：当前这套能力会以 Agent 模式运行，还是以 Workflow 模式运行。

建议先看总览

如果你们还没判断清楚运行方式和接入方式的关系，建议先读 Data Agent 集成总览。

JS SDK 解决的是什么问题 ​

JS SDK 解决的是：

  • 你们想保留自己的页面壳
  • 但希望把衡石现成的聊天能力或结果渲染能力嵌进去

它不解决的是：

  • 把衡石返回结果转换成你们自己的图表协议
  • 让你们完全不需要理解运行方式差异

JS SDK 有两种常见嵌入形态 ​

1. 完整聊天窗：new Copilot(...) ​

这种方式适合把一个完整聊天窗嵌进页面里。

它包含：

  • 消息区
  • 输入区
  • 推荐问题
  • 图表和结果展示
  • 会话相关交互

适合：

  • 希望在页面右侧或右下角挂一个 AI 助手
  • 希望复用完整聊天体验
  • 只想控制窗口开关、位置、大小和主题

2. 局部结果卡片：Copilot.renderChat(...) ​

这种方式适合把一条问答结果嵌在业务页面中。

适合：

  • 已经有自己的页面结构
  • 只想把答案和图表嵌到某个模块里
  • 希望把“数据问答结果”作为业务页面中的一个组成部分来展示

JS SDK 与运行方式的关系 ​

JS SDK + Workflow ​

如果当前使用的是 Workflow 模式：

  • 执行过程主要由衡石后端工作流服务负责
  • 你们的页面负责承载入口和业务壳
  • JS SDK 负责把聊天界面或结果渲染能力嵌进页面

这种组合最容易理解成：

  • 你们保留页面壳
  • 衡石负责执行和渲染

JS SDK + Agent ​

如果当前使用的是 Agent 模式：

  • JS SDK 不只是一个“显示结果的组件”
  • 它还会承接 Agent 模式在前端侧的运行过程
  • 你们看到的不只是一个渲染层，而是一套嵌入式的智能问答前端能力

这种组合更适合：

  • 希望在自有页面中直接保留 Agent 风格体验
  • 希望用户在页面里看到更连续的执行过程和交互反馈

前后端职责怎么理解 ​

组合你们主要负责什么衡石主要负责什么
JS SDK + Workflow页面壳、入口、业务流程后端执行推进 + 前端结果渲染
JS SDK + Agent页面壳、入口、业务流程Agent 运行过程 + 前端聊天与结果能力

什么时候最适合选 JS SDK ​

  • 你们明确要保留自己的页面壳
  • 你们不想自己做完整的数据问答前端体验
  • 你们希望结果卡片、图表和聊天能力能自然嵌进现有页面

什么时候不应该优先选 JS SDK ​

情况 1：你们只想接后端能力 ​

这时应该先看 API 集成。

情况 2：你们想最快复用完整页面 ​

这时通常 iframe 集成 更省事。

情况 3：你们想完全使用自己的前端协议和图表体系 ​

那就要准备自己承担更多前端适配成本，JS SDK 并不是为“协议转码”设计的。

最小接法示意 ​

完整聊天窗：new Copilot(...) ​

html
<script src="https://your-hengshi-host/assets/hengshi-copilot@<version>.js"></script>
<div id="copilot-root"></div>
<script>
 const root = document.getElementById('copilot-root');
 const copilot = new Copilot(root, {
   locale: 'zh-CN',
   userConfig: {
     dataSources: [
       { dataAppId: 130870, datasetId: 1 },
     ],
   },
 });
</script>

局部结果卡片：Copilot.renderChat(...) ​

html
<script src="https://your-hengshi-host/assets/hengshi-copilot@<version>.js"></script>
<div id="chat-result"></div>
<script>
 const container = document.getElementById('chat-result');
 window.Copilot.renderChat(container, {
   prompt: '华东区上月销售额是多少？',
   type: 'workflow',
 }, {
   userConfig: {
     dataSources: [
       { dataAppId: 130870, datasetId: 1 },
     ],
   },
 });
</script>

提示

type 用来指定这条问答按哪种运行方式执行，因此在集成前最好先确定你们选择的是 Agent 模式还是 Workflow 模式。

常用参数说明 ​

这一节不是把所有内部实现细节都摊开，而是先把集成时最常用、最容易搞混的参数讲清楚。

new Copilot(container, config) 的常用配置 ​

container ​

  • 类型：HTMLElement
  • 含义：聊天窗挂载到哪个 DOM 节点
  • 你们负责先在页面里准备这个容器

locale ​

  • 类型：string
  • 作用：指定界面语言，例如 zh-CN、en-US
  • 用途：控制 SDK 内部文案和本地化资源加载

userConfig ​

  • 类型：object
  • 作用：指定这次问答可用的数据范围
  • 最常见写法：
js
userConfig: {
  dataSources: [
    { dataAppId: 130870, datasetId: 1 },
  ],
}

dataSources 支持两种模式，但同一次配置里不要混用：

  1. 数据包 / 数据集模式

    • dataAppId
    • datasetId

  2. 主题域模式

    • subjectId

示例：

js
userConfig: {
  dataSources: [
    { subjectId: 1 },
    { subjectId: 2 },
  ],
}

draggable ​

  • 类型：object
  • 作用：把聊天窗做成可拖拽、可调整尺寸的浮层
  • 常用字段：
    • enable: 是否启用拖拽
    • bounds: 拖拽边界，常见值为 window 或 parent
    • minWidth / minHeight: 最小尺寸
    • position: 初始位置，例如 { x, y }
    • size: 初始宽高，例如 { width, height }

示例：

js
draggable: {
  enable: true,
  bounds: 'window',
  minWidth: 440,
  minHeight: 440,
  position: { x: window.innerWidth - 480, y: 20 },
  size: { width: 440, height: window.innerHeight * 0.8 },
}

stylesheet ​

  • 类型：string
  • 作用：向 SDK 的 shadow DOM 注入自定义样式
  • 适合改主题色、间距、字体等表现层

例如：

js
stylesheet: ':host > *, ::before, ::after { --brand: #4CAF50; }'

i18n ​

  • 类型：object
  • 作用：覆盖 SDK 内部部分文案
  • 适合微调“问题理解 / 数据表现 / 取数逻辑”这类标题文案

例如：

js
i18n: {
  'zh-CN': {
    'copilot.question-reasoning': '问题理解',
    'copilot.question-answer': '数据表现',
    'copilot.question-reasoning-logic': '取数逻辑',
  },
}

其他常用项 ​

参数作用
closable是否显示关闭按钮
headless是否先以隐藏状态初始化
style根容器样式
completionConfig控制结果渲染阶段的行为
onReadySDK 初始化完成后的回调
onHide调用 hide() 后触发的回调

completionConfig 常用字段 ​

这个配置会影响结果卡片和问答完成后的展示方式。

参数作用
meta指定要展示哪些内容，例如 answer,chart,chartConfig
openChartConfig是否默认展开取数逻辑面板
stylesheet结果卡片阶段额外样式
i18n结果卡片阶段额外文案覆盖
onCompletionDone问答完成时的回调，参数为 (conversationId, uid)

Copilot.renderChat(container, chatConfig, copilotConfig) 的参数 ​

renderChat(...) 接受 3 个参数：

第 1 个参数：container ​

  • 类型：HTMLElement
  • 作用：结果卡片要渲染进哪个容器

第 2 个参数：chatConfig ​

这是“这一条结果本身怎么来”的配置，常见两种用法：

  1. 动态问答
js
{
  prompt: '华东区上月销售额是多少？',
  type: 'workflow',
}

常用字段：

  • prompt: 用户问题
  • type: agent 或 workflow
  • conversationId: 如果要在已有会话里继续问，可以显式传入
  • meta: 控制最终展示哪些结果块
  • openChartConfig: 是否展开取数逻辑面板
  • onCompletionDone: 本次问答完成后的回调
  1. 静态渲染已有结果

如果你已经拿到了完整的问答数据，也可以直接传：

  • conversationId
  • uid
  • prompt
  • answer
  • refineQuestion
  • charts
  • 以及相关结果字段

这更适合“把一条现成结果重新渲染到另一个区域”。

第 3 个参数：copilotConfig ​

这部分和 new Copilot(...) 的配置思路一致，最常见的是继续传 userConfig，让这条结果在明确的数据范围内运行：

js
{
  userConfig: {
    dataSources: [
      { dataAppId: 130870, datasetId: 1 },
    ],
  },
}

部署和认证相关参数 ​

window.__hs_sdk_base_url__ ​

如果 SDK 文件不是直接从衡石系统同域加载，而是放在 CDN 或其他静态资源域名下，应该在加载脚本前显式指定后端地址：

html
<script>
  window.__hs_sdk_base_url__ = 'https://your-hengshi-host';
</script>
<script src="https://cdn.example.com/assets/hengshi-copilot@<version>.js"></script>

否则，SDK 默认会按当前脚本所在 host 去推断接口地址，容易把请求打错地方。

登录认证 ​

SDK 页面最终是否能正常显示问答和图表，还取决于登录态是否已经准备好。

常见方式有两种：

  1. 你们自己的系统已经和衡石打通 SSO
  2. 通过 JWT 登录接口先完成认证

例如：

js
fetch('https://your-hengshi-host/api/auth/login-info?activeAuth=jwt-param&jwtParam=<your-jwt-param>')

实例方法 ​

new Copilot(...) 返回的是一个实例。最常用的方法是：

方法作用
show()显示聊天窗
hide()隐藏聊天窗

所以在页面里，通常不需要反复销毁重建实例；直接控制显示 / 隐藏就够了。

一句话总结 ​

JS SDK 适合“保留自己的页面，但复用衡石前端能力”。

它不是一种独立于 Agent / Workflow 之外的新模式，而是承载这两种运行方式的前端嵌入方式。

衡石分析平台使用手册

版权所有 © 2016-present hengshi.com