跳转到主要内容

远程组件宿主桥接

宿主桥接连接远程组件 iframe、工作台宿主和插件视图提供器。它不是任意远程调用通道:业务能力需要清单声明、宿主处理器,以及适用时的服务端实现。通用上下文生命周期事件不需要订阅。
远程组件只发送业务意图。宿主负责解析当前用户、宿主、租户和组织上下文,并在调用提供器前校验视图、功能、权限和能力声明。

三层能力契约

缺少任意一层时,该能力都不应执行。

消息信封

所有消息使用固定通道和协议版本:
  • iframe 加载完成后发送 ready。
  • 宿主使用 init 返回 instanceId、runtimeScope、scopeRevision、视图清单、初始查询、语言、主题和调试配置。
  • 后续消息必须携带匹配的 instanceId。
  • 请求与响应使用同一个 requestId。
  • iframe 只接受 window.parent 发出的消息;宿主只接受当前 iframe contentWindow 发出的消息。

支持的消息

宿主发送给 iframe: iframe 发送给宿主:

能力映射

切换上下文而不重建 iframe

同一认证身份、组织和助手下切换项目或会话时,iframe 保持不变。宿主重新授权目标 View 和入口,在解析期间暂停操作;完成后向所有已挂载 View(包括隐藏页签)发送 view.context.changed,无需清单订阅或确认握手。 init.runtimeScope 与事件中的 data.runtimeScope 都是完整快照。未绑定字段为 null,应整体替换,不能合并旧 ID。当前 Angular 宿主提供项目与会话字段,支持分组路由的宿主还可提供 groupId。
revision 在同一实例内单调增加,但不保证连续。忽略过期修订,拒绝旧待处理请求,清空选择,并在新作用域刷新或重新绑定。后续每次请求携带最新 scopeRevision。宿主使用自己的授权上下文,不接受请求指定身份范围,并随上下文轮换文件会话。 更换身份、组织、助手或入口,显式重新加载或关闭 View 会销毁旧实例。入口访问被拒绝时,旧文档也必须移除。取消请求或丢弃响应不会撤销已经提交的服务端修改。

TypeScript 桥接客户端

桥接集中在 bridge.ts,业务组件不直接拼装协议消息。以下示例面向支持上下文修订的宿主,每个 iframe 只安装一次桥接。业务包装函数在使用结果前仍需校验返回载荷。
业务代码可以在此基础上封装 requestData()、executeAction() 和 invokeClientCommand() 等具名方法。桥接层返回稳定错误代码,由 UI 多语言层转换成用户可见文案。 在 onContextChange 中先清空依赖作用域的状态,再刷新或重新绑定。响应后的异步处理也应保存 currentScopeRevision(),在写入结果前再次比较。相同修订的重复 init 可更新主题/语言,不应重置所选资源。

查询数据

XpertViewQuery.parameters 只支持标量或标量数组。复杂筛选条件应序列化为明确的 JSON 字符串参数,并由提供器安全解析。 大型表格应使用服务端分页。远程组件不要一次把所有记录加载到 iframe。

执行操作

普通业务变更使用 JSON 操作:
actionKey 必须存在于 manifest.actions,且传输方式必须匹配。提供器仍需校验目标对象、当前用户和租户/组织范围。 文件上传使用 executeFileAction,不要把二进制内容或 Base64 放进 JSON 操作。文件预览与下载使用 requestFileAccess,由宿主换取有时效的访问授权。

客户端命令

客户端命令用于宿主本地 UI 行为,不调用插件提供器。例如发送 Assistant 消息、设置 Assistant 上下文、打开文件或导航到另一工作台视图。 它是一个封闭的三方契约:
  1. 源视图在 manifest.clientCommands 中声明命令键。
  2. 当前宿主注册同名处理器。
  3. 远程组件通过 invokeClientCommand 调用,并处理结构化失败结果。
不要从 iframe 直接修改顶层窗口地址。

当前宿主命令

声明实际使用的命令,检查结构化结果,并展示处理器不可用或弹窗拦截。清单声明不代表每个宿主都实现了命令。不能在载荷中添加租户/工作区身份或凭据。

宿主事件

远程组件可以订阅宿主归一化后的事件,例如 Agent 中间件工具完成:
声明式视图通常使用 refresh。远程组件优先使用 forward,根据业务 ID 只刷新受影响的数据区域,并在本地存在未保存编辑时避免静默覆盖。

初始化、主题和多语言

以 init.locale 为准,在入口处一次性归一化为 BCP 47 语言标签,例如 en-US、zh-Hans 和 zh-Hant。不要在业务组件中根据语言直接选择文本。 应用 init.theme.tokens 后,调用 installShadcnThemeVars() 安装语义主题变量。调试日志由 init.debug.enabled 控制;不要根据 URL、主机名或平台身份猜测开发环境。 不要依赖 localStorage 或 sessionStorage。临时状态保存在 React 状态中,持久状态通过宿主桥接写入服务端。

安全检查

  • 不向 iframe 传递访问令牌、API 地址、Assistant ID、租户 ID 或组织 ID。
  • 不让 iframe 自行选择 hostType 或 hostId。
  • 不执行清单未声明的操作、文件能力或客户端命令。
  • 不在日志中输出令牌、文件内容、完整业务快照或个人敏感信息。
  • 提供器对每次读取和变更重新执行授权与租户/组织隔离。
  • 对消息来源、协议版本、实例 ID 和请求 ID 添加自动化测试。
返回工作台远程组件查看完整开发流程。