一个门户只保留一个智能助理：衡石嵌入式 Data Agent 的运行与渲染边界

**摘要：**很多 SaaS 门户把衡石仪表盘放进 iframe，又在门户右侧部署自己的 Copilot。用户打开仪表盘后会看到两套入口、两段会话和两种上下文：父页面的助手知道业务页面，iframe 内的助手知道图表。随后，用户点“智能解读”时不知道该问谁，研发也很难判断一次失败发生在登录态、跨域通信、会话运行还是图表渲染。本文以一个嵌入仪表盘的 SaaS 门户为例，说明如何用父页面 Copilot JS SDK 接管 iframe 内的智能助理，并把运行方式、页面渲染、权限和后端编排拆成可验证的边界。本文以 6.2 开发者手册为接入基线，不把它表述为当前最新版本。

1. 从“双助手”故障现场确定目标边界

设想一个客户经营门户：主页面展示订单、客户和工单模块，页面中间通过 iframe 打开衡石仪表盘。产品团队同时在门户右侧接入了数据问答侧边栏。没有统一接管时，父页面助手和 iframe 仪表盘各自维护入口与会话。用户在仪表盘图表上点“解读”，iframe 内打开一套 Copilot；用户再回到右侧侧栏提问，父页面又开启另一套对话。两个助手可能服务同一登录用户，却不共享同一次交互的可见上下文。

这不是单纯的界面重复。父页面中的 Agent 无法把 iframe 当作自身 DOM 来点击、拖拽或路由跳转；仪表盘需要把可读、可解读、可修改的业务动作与业务对象通过桥接能力提供给父页面。若团队让两个助手并行处理同一张仪表盘，排障人员还会面对两份执行日志和两条事件链，无法先确定责任归属。

这个场景应先写出产品约束：**一个门户页面只保留一个可见的智能助理入口和会话容器。**仪表盘仍负责呈现业务数据与图表上下文，父页面负责承载 Copilot。用户从仪表盘触发“打开助手”“智能解读”或图表解读时，操作进入父页面的同一 Copilot。这个约束为后续的运行时、渲染和安全设计提供了清晰验收条件。

2. 先分开两条轴：谁推进问答，谁承载界面

集成设计常把 iframe、JS SDK 和 API 当成三个互斥的产品模式。它们实际回答的是“能力怎样接进来”。另一个独立问题是“谁持续推进一次问答”。衡石文档将后者区分为 Agent 模式与 Workflow 模式：前者保留持续执行、状态变化、工具调用和结果产生的过程；后者由后端工作流服务推进，前端发起请求、读取状态并展示结果。Data Agent 集成总览把这两条轴放在同一张决策图中，集成团队应按它们分别指定责任人。

接入与显示形态	Agent 模式的持续推进者	Workflow 模式的持续推进者	门户团队承担的边界
完整 ChatBI iframe	嵌入页中的 Agent 运行时	衡石后端工作流服务	嵌入页面、登录态与页面容器；复用整页聊天与结果体验
JS SDK：new Copilot(...) 或 Copilot.renderChat(...)	页面内嵌的 Agent 前端能力	衡石后端工作流服务	页面壳、入口、挂载容器和业务流程；复用聊天窗或局部结果渲染
JS SDK 父页面 + iframe 仪表盘	父页面 Copilot，通过 iframe 代理的业务动作访问仪表盘	按所选 Workflow 由衡石后端工作流服务推进，父 SDK 只承载入口与结果	只保留父页面助手，配置安全通信边界，保证两侧认证与资源授权；不把浏览器 Agent 的编辑能力推定为 Workflow 默认能力
后端 API 接入	门户部署的 Node.js Agent 服务	衡石后端工作流服务	后端编排、业务契约、结果呈现和可观测性；先确认运行方式再设计接口链路

表中“API”只表示接入位置，不替代运行方式。需要保留 Agent 行为并从后端接入时，文档说明可使用 Node.js 版 Agent 服务；需要由后端统一托管执行时，选择 Workflow 服务。这个区分能避免团队在“用了 API”后仍无法解释谁负责重试、状态推进和服务失败恢复的问题。

3. 让父页面 Copilot 接管 iframe 仪表盘

这个案例不需要复制两份聊天窗。父页面加载衡石 Copilot JS SDK，在门户自己的 DOM 中创建一个 Copilot 实例；iframe 继续加载真实的仪表盘地址，但 URL 增加 agentHost=parent 与 parentOrigin。前者声明由父页面承接智能助理，后者给出允许通信的父页面 origin。文档规定 origin 只包含协议、主机和端口，不包含路径、查询参数或通配符。

下面是配置片段。集成方提供 hengshiHost、appId、dashboardId 和 dashboardFrame，再把生成的地址赋给 iframe。

const dashboardUrl = new URL(`/app/${appId}/dashboard/${dashboardId}`, hengshiHost);
dashboardUrl.searchParams.set('agentHost', 'parent');
dashboardUrl.searchParams.set('parentOrigin', window.location.origin);
dashboardFrame.src = dashboardUrl.toString();

父页面加载 SDK 后，iframe 页面通过参数声明接管关系，双方自动建立通信。iframe 自己不再显示 Copilot 侧边栏；仪表盘中的“打开助手”“智能解读”和图表解读入口改为打开父页面 Copilot。父页面无须手动把 iframe DOM 注册成可操作节点。Agent 读取图表上下文或提交仪表盘变更时，使用 iframe 暴露的业务动作和业务对象，例如文档中用于读取、检查或提交对象变更的桥接操作。iframe 集成指南明确说明，直接对 iframe 内元素做父页面点击、拖拽或导航不属于这一接管机制。

门户还要在视觉层面收口：侧边栏只在父页面出现，仪表盘按钮只负责把当前图表、当前仪表盘或当前操作意图传给父页面 Copilot。产品界面不应在 iframe 内再给用户保留第二个聊天面板，也不应把同一个问题同时投递给两个会话。用户从报表转回订单页面时，门户可以隐藏或显示同一个 Copilot 实例，而不必反复销毁并重新创建它。

4. 桥接解决上下文，不替代认证与资源权限

parentOrigin 的责任很窄：iframe 只接受来自该精确 origin 的父页面消息。它不创建登录态，不授予仪表盘权限，也不把父页面的业务租户自动映射成衡石资源权限。门户必须保证 iframe 页面和父页面 SDK 都能以当前用户访问衡石接口；实际项目可以使用既有单点登录，或按认证方案先完成登录。当前用户还必须拥有目标仪表盘和图表的读取权限。

因此，团队应把“同一个用户”拆成三项核验：门户会话是否存在、衡石登录态是否可用、该用户在当前租户下是否有仪表盘资源权限。第三项失败时，前端不应把空白图表或 403 当成桥接成功。若 iframe 使用 sandbox，配置还需要允许脚本运行和同源能力；若衡石站点拒绝门户嵌入，CSP 或 X-Frame-Options 也会阻止页面加载。它们属于嵌入前置条件，不应在 Copilot 代码里用宽松通信策略绕开。

会话边界也要显式约束。Data Agent 侧边栏适合围绕当前页面继续分析、创作、解读或编辑；独立 ChatBI 更适合作为持续产出图表和看板的问数入口。门户可选择其中一种主入口，但在同一页面只暴露父页面 Copilot。Agent 模式下，用户在一次问答进行时切页面或切历史会话会中断过程，演示与排障应保持当前会话和当前页面。Data Agent 与 ChatBI FAQ给出了这一运行限制和排障材料。

5. 后端编排与前端渲染不能混成一个“API 接入”

父页面 SDK 有两种不同的显示粒度。new Copilot(...) 挂载完整聊天窗，承载消息区、输入区、推荐问题、图表结果和会话交互；Copilot.renderChat(...) 把一条问答结果嵌到某个业务模块。两者都适合保留门户页面壳，同时复用衡石提供的前端能力。JS SDK 指南也明确指出，它不负责把衡石返回内容转换为门户自定义的图表协议。

这条边界会直接影响技术选型。团队若要把结果显示在现有的 ECharts 容器中，不能假设后端结果天然就是标准 ECharts option。应在接口契约中定义自己的结果模型、字段校验和转换层，并为自有渲染器承担图表兼容性与交互测试。团队若希望复用衡石的对话、图表和结果卡片，应使用 JS SDK 的渲染能力，避免同时维护第二套图表语义和会话界面。

后端 API 路线适合已有 AI 网关、多 Agent 或工作流编排系统的团队，但接口接入不应倒推为某一种运行方式。本文只依据 6.2 总览说明 Node.js Agent 服务与 Workflow 后端服务的责任，不展示具体 REST 路径、请求字段或返回字段。实施团队应依据实际部署版本的接口文档核定后端契约和渲染适配方案，再冻结调用代码与错误处理策略。

6. 用集成测试检验责任边界

推荐把以下用例放进门户的联调清单。它们是本文基于已公开能力提出的测试架构，不是产品文档承诺的自动化测试套件。

1. **两个仪表盘的上下文切换：**在同一门户打开仪表盘 A 和 B，分别从图表解读入口进入父页面 Copilot。检查每次请求携带的图表与仪表盘上下文是否来自当前 iframe，并确认页面上仍只有一个侧边栏。
2. **会话与页面重启：**在执行过程中刷新父页面、关闭再打开 Copilot、切换 iframe 地址。记录运行中的问答是否中断、历史是否按产品设计恢复，以及重启后是否错误沿用前一个仪表盘的上下文。
3. **origin 配置错误：**分别替换协议、端口和主机，或把 parentOrigin 写成带路径的地址。预期 iframe 不会退回宽松通信模式；控制台应能帮助定位通信被拒绝的原因。
4. **未授权租户与资源：**用没有目标仪表盘读取权限的用户进入门户。验证门户显示可处理的授权失败状态，且 Agent 不会通过桥接读取图表对象或提交修改。
5. **SDK 重渲染与纯数据展示：**同一问答分别交给 Copilot.renderChat(...) 和门户自有数据视图。前者验证衡石结果卡片与图表能否重渲染；后者验证自有适配器面对的字段、空结果和错误状态，不能把它当成 ECharts option 的同义测试。
6. **服务失败分流：**对话失败时同时收集对话卡片执行日志、浏览器 Fetch/XHR 的出错响应，以及系统 DEBUG 与实时调试导出日志。用这些材料区分模型、检索、权限、数据、前端通信和后端服务故障。

7. 版本基线与交付判断

本文的能力陈述以 6.2 手册中的 SDK 总览、JS SDK 和 iframe 集成页为基线。官方发布记录显示 6.3.2 已于 2026 年 9 月 23 日对外发布，因此项目文档应写明实际部署的 SDK 与服务版本，并在升级前复跑上述跨域、会话和权限用例。不要把 6.2 手册里的示例当作所有后续版本的默认行为。

**文档明确支持的能力：**父页面 Copilot 通过 agentHost=parent 和精确 parentOrigin 接管 iframe 仪表盘；JS SDK 提供完整聊天窗与局部结果渲染；Agent 与 Workflow 是独立于 iframe、JS SDK、API 的运行方式。**本文的工程建议：**用“一个可见助手、两侧各自认证、桥接只传业务上下文”的责任模型组织门户代码和测试，待获得有效 API 契约后再决定自有后端和图表渲染方案。

**衡石观点：**嵌入式 Data Agent 的关键不在于把聊天窗塞进门户，而在于让一个助手在正确的页面、会话、权限和渲染边界内工作。父页面接管仪表盘后，用户只面对一个入口，研发团队也能把每次失败归到可检查的责任面。