摘要：嵌入式 BI 的重点不在于把一张图放进业务系统，而在于让身份、资源、数据和分析体验沿着同一条受控链路工作。HENGSHI SENSE 面向门户、SaaS 和行业应用提供发布页嵌入、仪表盘与图表 SDK、数据服务及 Data Agent 集成方式；多租户工作空间、资源分享和分层权限则为平台方服务多个企业客户提供了产品化的组织边界。本文从集成层级、租户协作、权限设计和智能体接入四个方面说明实践要点。

图：嵌入式 BI 的交付与权限——身份映射、资源授权、数据规则与多租户二次授权共同决定结果可见性。

1 从嵌入页面到可交付的分析能力

业务系统需要的往往不是另一个独立的 BI 门户，而是与客户、订单、门店或项目页面连在一起的分析体验。用户在 CRM 中查看客户时，需要看到该客户的回款与商机趋势；渠道系统中的合作伙伴，需要在自己的账户范围内查看销量、库存和政策执行；SaaS 厂商则希望把分析作为产品的一部分交付。此类场景要求数据口径、身份和可视化都能复用，也要求集成方保留自己的导航、流程和品牌体验。

衡石把这类需求拆成了几种可以组合的交付面。应用、仪表盘和图表都可以从产品页面生成嵌入链接和 iframe 示例；嵌入页保留刷新、全屏、导出等查看动作，并可通过展示参数调整标题、边距、背景、过滤器标签或移动端样式。参数用于控制展示，不承担访问授权的职责。公开链接与登录后链接的身份状态不同，设计时需要先确定访问者是谁、可访问什么资源，再决定页面如何呈现。应用展示交互与嵌入提供了应用、仪表盘和图表的产品内入口。

若一个业务页面同时放置多个图表，集成方可以使用衡石的 JS SDK 在宿主页面中加载仪表盘或图表。SDK 支持容器尺寸、应用与仪表盘标识、联动过滤清除等配置，并可使用 Shadow DOM 做样式隔离；它仍然复用衡石的分析与渲染能力，因此适合希望控制页面布局、又不想自行重建图表逻辑的前端团队。对于创作区页面，官方手册明确了 iframe 的接入方式和移动端限制；对外发布页则提供了更适合展示端的嵌入路径。嵌入式数据分析方案和JS SDK 嵌入说明应作为项目生成链接与选择参数的依据。

当宿主系统需要自建展示层或将分析结果送入后续业务流程时，可以使用衡石的 API 服务。已发布的聚合数据 API、明细数据 API、自定义查询 API 和注册 API，分别覆盖图表聚合结果、数据集字段、连接查询及第三方接口封装；发布、授权、限流和监控属于交付过程的一部分。API 返回 Array 或 Object 等数据结果，前端团队可以据此完成自己的渲染和交互，但也需要承担查询参数、调用授权、版本变更和展示逻辑的工程责任。API 服务手册给出了 API 的发布与授权边界。

2 多租户以工作空间和资源交付为边界

衡石的租户模式面向一个平台方服务多个企业客户的场景。平台方创建、启停和管理租户，并可以配置有效期、用户配额和引擎分配；每个租户进入自己的分析空间，租户之间互不感知。平台方的普通租户管理视角聚焦于租户信息，不负责租户空间内的用户管理。这个产品边界解决的是平台运营与租户使用之间的职责划分，项目仍应由部署方按自身安全制度管理基础设施、备份和运维访问。

租户价值并不只是把账号分组。平台方可以将数据连接、数据包、团队空间应用和公共空间应用按产品规则单向分享给租户；租户管理员再将已获资源授权给本租户的成员。数据包和应用在分享时可以继续配置数据权限，团队空间或公共空间的资源也有各自的分享前提。这样，平台方能够把通用的数据服务、指标和分析资产交付给多个企业客户，同时让各租户在自己的工作空间内完成建模、分析和二次授权。租户管理手册对这些共享范围和管理职责有明确说明。

实施时应把“租户空间”“资源归属”和“数据可见范围”分别设计。不要把多租户理解为系统自动给每条业务 SQL 注入某个固定字段，也不要假设每个项目都采用独立库或独立 Schema。衡石提供的是可配置的租户工作空间、资源分享和授权机制；数据连接、数据包、应用与业务主题是否可见，以及行列如何过滤，应依据实际资源和规则配置验证。这个做法让同一套平台既能承载平台方统一供数，也能适应不同行业的组织、数据源与交付方式。

3 权限设计：先识别身份，再控制资源与数据

嵌入项目常把“用户已登录”误当成“用户已被授权”。两者需要分开完成。衡石支持内置认证、LDAP、CAS、SAML2、OAuth2、JWT 请求参数以及多种企业协同平台认证方式；外部认证可以映射登录名、邮箱、角色、用户组、组织、企业信息和会话有效期等字段。JWT 适合宿主系统已经完成登录、需要把当前身份带入嵌入页或 SDK 的情形。签名算法、验签密钥、加解密配置、声明映射和过期时间都需要双方一致，令牌本身不能替代衡石内已有的资源和数据授权规则。认证与 JWT 常见问题与认证方式说明了这些配置项。

认证完成后，功能权限决定用户能使用哪些模块，资源权限决定用户能管理或查看哪些连接、数据集、应用和指标，数据权限进一步决定实际查询结果。衡石的用户角色覆盖系统管理、数据管理、数据分析、数据查看、API 管理、指标管理与指标分析等职责；一个用户可以同时拥有多个角色。业务主题可单独授权管理者、编辑者、查看者或租户使用者，授权主题的用户仍受底层数据包行权限约束。用户角色和业务主题与指标权限可用于梳理组织中的职责分工。

数据控制需要落到实际资源上。连接权限可按连接、目录和表授予查看名称、查看结构、只读或完全访问；在表级只读访问中，还可用简单过滤、表达式过滤或 SQL 表达式过滤配置行过滤，并控制列可见性。应用的数据权限还需要先选择应用作者、数据集作者或使用者的模式：前两种模式下，应用管理者可以为数据集配置行、列规则；使用者模式下，应用管理者不能设置同类规则。同一用户在同一数据集上的多条行规则按并集生效，行权限和列权限按交集生效；基础数据集的行规则也不会自动传递到新建的下游 join 数据集，必须在该下游数据集单独配置。宿主页面传入过滤条件、隐藏控件或调整 iframe 样式只能影响交互和展示，不能取代连接、数据集和应用上的权限配置。连接权限和应用数据权限是上线前核对规则的依据。

4 Data Agent：把问数和创作能力接到合适的入口

Data Agent 为嵌入式产品增加了对话式分析、指标创建、可视化创作和仪表盘智能解读等能力。Agent 模式可以在用户有权限的范围内检索数据集市、应用集市和应用创作中的内容，并会结合当前页面与用户信息理解上下文；数据集命名、字段与指标描述、知识管理和向量化准备会影响回答质量。智能解读基于已有及历史数据进行查询、汇总和描述性报告生成，不承担未来预测；复杂报表与复杂表格也不在该功能的支持范围内。Data Agent 使用说明列出了能力范围与准备要求。

集成时，完整问数页面适合 iframe，聊天窗与结果卡片适合 JS SDK，后端编排或多智能体调用适合 API。JS SDK 仍由衡石负责结果渲染，宿主页面负责入口、容器、布局和交互；API 集成面向后端调用，不能简单等同于返回标准 ECharts 配置。Agent 模式、Agent API 模式与 Workflow 及其 API 的支持范围也不同：前两者可面向不限定数据源的问数，Workflow 更适合预先定义的数据源和流程。项目应围绕“用户最终在哪个页面看到什么”“谁发起调用”“谁负责渲染和审计”选择入口，而不是把三种方式混为一层。Data Agent 集成总览和Data Agent JS SDK提供了相应的接入契约。

5 面向智能体的工程接口

当企业希望让编码 Agent 或常驻 Agent 执行数据接入、HQL 查询、仪表盘生成、权限动作和运维动作时，HENGSHI CLI 提供了以 hbi 为入口的命令执行面。CLI 支持 JSON、YAML 和表格等结构化输出，配套 repo-managed skills，并在支持的命令中提供 dry-run 与 SSE 回显能力。它面向终端工具调用和 BI 工程执行，与面向业务用户的网页 ChatBI 或嵌入式聊天组件属于不同的交付面。

这使集成方案可以按责任分层：业务页面通过 iframe 或 SDK 交付可视化与问数体验，后端通过 API 编排数据服务，受控的工程智能体通过 CLI 执行有明确授权的 BI 操作。每一层都应沿用同一套身份、资源和数据权限设计，并在上线前覆盖匿名或公开链接、已登录用户、租户管理员、平台方管理者和 API 调用方等实际访问路径。HENGSHI CLI展示了当前的命令范围和 Agent 集成定位。

6 结语

嵌入式 BI 的交付质量，取决于分析能力能否带着正确的身份与权限进入业务场景。衡石以页面嵌入、JS SDK、API、租户工作空间、资源分享、行列权限和 Data Agent 集成覆盖不同层级的需求。平台方和集成团队应先明确分析资产由谁建设、用户从哪里登录、数据按什么规则可见，再选择 iframe、SDK、API 或 CLI 的组合。这条路径既能保留业务系统的产品体验，也能把指标、权限与分析能力沉淀为可持续复用的企业资产。