> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 远程组件宿主桥接

> 使用受控消息协议连接工作台远程组件、宿主和视图提供器。

# 远程组件宿主桥接

宿主桥接连接远程组件 iframe、工作台宿主和插件视图提供器。它不是任意远程调用通道：每项能力都必须同时具有清单声明、宿主消息处理和对应的服务端实现。

```text theme={null}
远程组件
  -> postMessage
  -> 工作台宿主
  -> 已认证的视图扩展 API
  -> IXpertViewExtensionProvider
```

远程组件只发送业务意图。宿主负责解析当前用户、宿主、租户和组织上下文，并在调用提供器前校验视图、功能、权限和能力声明。

## 三层能力契约

| 层     | 所有者     | 作用                       |
| ----- | ------- | ------------------------ |
| 消息协议  | 宿主与远程组件 | 定义 iframe 请求、响应和生命周期消息   |
| 视图清单  | 插件视图提供器 | 声明允许使用的数据、操作、文件、客户端命令和事件 |
| 提供器方法 | 插件服务端   | 在可信服务端上下文中执行数据查询或业务操作    |

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

## 消息信封

所有消息使用固定通道和协议版本：

```ts theme={null}
interface RemoteMessageEnvelope {
  channel: 'xpertai.remote_component'
  protocolVersion: 1
  instanceId?: string
  type: string
  requestId?: string
}
```

* iframe 加载完成后发送 `ready`。
* 宿主使用 `init` 返回 `instanceId`、视图清单、初始查询、语言、主题和调试配置。
* 后续消息必须携带匹配的 `instanceId`。
* 请求与响应使用同一个 `requestId`。
* iframe 只接受 `window.parent` 发出的消息；宿主只接受当前 iframe `contentWindow` 发出的消息。

## 支持的消息

宿主发送给 iframe：

| 消息                    | 用途                                |
| --------------------- | --------------------------------- |
| `init`                | 初始化清单、查询、语言、主题和调试状态               |
| `hostEvent`           | 转发与 `manifest.hostEvents` 匹配的宿主事件 |
| `data`                | `requestData` 的响应                 |
| `parameterOptions`    | 参数选项响应                            |
| `actionResult`        | JSON 操作响应                         |
| `fileActionResult`    | 文件操作响应                            |
| `fileAccessResult`    | 文件预览或下载授权响应                       |
| `clientCommandResult` | 客户端命令响应                           |
| `error`               | 与 `requestId` 对应的请求错误             |

iframe 发送给宿主：

| 消息                        | 用途                     |
| ------------------------- | ---------------------- |
| `ready`                   | 请求初始化                  |
| `resize`                  | 请求调整非固定工作台中的 iframe 高度 |
| `notify`                  | 请求显示宿主通知               |
| `requestData`             | 查询视图数据                 |
| `requestParameterOptions` | 查询动态参数选项               |
| `executeAction`           | 执行 JSON 操作             |
| `executeFileAction`       | 执行文件上传操作               |
| `requestFileAccess`       | 请求文件预览或下载授权            |
| `invokeClientCommand`     | 请求宿主执行界面操作             |

## 能力映射

| 能力      | 清单声明                             | iframe 消息                 | 服务端处理                     |
| ------- | -------------------------------- | ------------------------- | ------------------------- |
| 数据查询    | `dataSource`                     | `requestData`             | `getViewData`             |
| 参数选项    | `parameters[].optionSource`      | `requestParameterOptions` | `getViewParameterOptions` |
| JSON 操作 | `actions[].transport = 'json'`   | `executeAction`           | `executeViewAction`       |
| 文件操作    | `actions[].transport = 'file'`   | `executeFileAction`       | `executeViewFileAction`   |
| 文件访问    | `fileAccess.purposes`            | `requestFileAccess`       | `resolveViewFile`         |
| 客户端命令   | `clientCommands[]`               | `invokeClientCommand`     | 宿主命令注册表                   |
| 宿主事件    | `hostEvents.subscriptions[]`     | `hostEvent`               | 宿主管理                      |
| 远程入口    | `view.type = 'remote_component'` | 宿主管理                      | `getRemoteComponentEntry` |

## TypeScript 桥接客户端

将桥接代码集中在 `bridge.ts`，不要让业务组件直接拼接消息。

```ts theme={null}
const CHANNEL = 'xpertai.remote_component'
const VERSION = 1

type RemoteRequestType =
  | 'requestData'
  | 'requestParameterOptions'
  | 'executeAction'
  | 'executeFileAction'
  | 'requestFileAccess'
  | 'invokeClientCommand'

type RemoteOutboundType = RemoteRequestType | 'ready' | 'resize' | 'notify'

interface PendingRequest {
  resolve: (value: unknown) => void
  reject: (error: Error) => void
  timeout: number
}

interface BridgeMessage {
  channel?: unknown
  protocolVersion?: unknown
  instanceId?: unknown
  type?: unknown
  requestId?: unknown
  message?: unknown
  data?: unknown
  result?: unknown
  [key: string]: unknown
}

let instanceId: string | null = null
let sequence = 0
const pending = new Map<string, PendingRequest>()

export function installBridge(handlers: {
  onInit: (message: BridgeMessage) => void
  onHostEvent: (event: unknown) => void
}) {
  const listener = (event: MessageEvent) => {
    if (event.source !== window.parent || !isBridgeMessage(event.data)) return
    const message = event.data

    if (message.type === 'init') {
      instanceId = typeof message.instanceId === 'string'
        ? message.instanceId
        : null
      handlers.onInit(message)
      return
    }

    if (message.instanceId !== instanceId) return
    if (message.type === 'hostEvent') {
      handlers.onHostEvent(message.event)
      return
    }

    const requestId = typeof message.requestId === 'string'
      ? message.requestId
      : null
    const request = requestId ? pending.get(requestId) : undefined
    if (!request || !requestId) return

    pending.delete(requestId)
    window.clearTimeout(request.timeout)
    if (message.type === 'error') {
      request.reject(new Error(
        typeof message.message === 'string'
          ? message.message
          : 'remote_request_failed'
      ))
    } else {
      request.resolve(message.data ?? message.result)
    }
  }

  window.addEventListener('message', listener)
  post('ready')
  return () => {
    window.removeEventListener('message', listener)
    for (const request of pending.values()) {
      window.clearTimeout(request.timeout)
      request.reject(new Error('remote_bridge_disposed'))
    }
    pending.clear()
  }
}

export function requestHost(
  type: RemoteRequestType,
  body: Record<string, unknown>
) {
  const requestId = `${Date.now()}-${++sequence}`
  return new Promise<unknown>((resolve, reject) => {
    const timeout = window.setTimeout(() => {
      pending.delete(requestId)
      reject(new Error('remote_request_timeout'))
    }, 30_000)
    pending.set(requestId, { resolve, reject, timeout })
    post(type, { requestId, ...body })
  })
}

function post(type: RemoteOutboundType, body: Record<string, unknown> = {}) {
  window.parent.postMessage({
    channel: CHANNEL,
    protocolVersion: VERSION,
    instanceId,
    type,
    ...body
  }, '*')
}

function isBridgeMessage(value: unknown): value is BridgeMessage {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
  const message = value as BridgeMessage
  return message.channel === CHANNEL &&
    message.protocolVersion === VERSION &&
    typeof message.type === 'string'
}
```

业务代码可以在此基础上封装 `requestData()`、`executeAction()` 和 `invokeClientCommand()` 等具名方法。桥接层返回稳定错误代码，由 UI 多语言层转换成用户可见文案。

## 查询数据

```ts theme={null}
const result = await requestHost('requestData', {
  query: {
    page: 1,
    pageSize: 20,
    search,
    parameters: {
      table: 'contracts',
      status
    }
  }
})
```

`XpertViewQuery.parameters` 只支持标量或标量数组。复杂筛选条件应序列化为明确的 JSON 字符串参数，并由提供器安全解析。

大型表格应使用服务端分页。远程组件不要一次把所有记录加载到 iframe。

## 执行操作

普通业务变更使用 JSON 操作：

```ts theme={null}
await requestHost('executeAction', {
  actionKey: 'approve_contract',
  targetId: contractId,
  input: { comment },
  parameters: { projectId }
})
```

`actionKey` 必须存在于 `manifest.actions`，且传输方式必须匹配。提供器仍需校验目标对象、当前用户和租户/组织范围。

文件上传使用 `executeFileAction`，不要把二进制内容或 Base64 放进 JSON 操作。文件预览与下载使用 `requestFileAccess`，由宿主换取有时效的访问授权。

## 客户端命令

客户端命令用于宿主本地 UI 行为，不调用插件提供器。例如发送 Assistant 消息、设置 Assistant 上下文、打开文件或导航到另一工作台视图。

它是一个封闭的三方契约：

1. 源视图在 `manifest.clientCommands` 中声明命令键。
2. 当前宿主注册同名处理器。
3. 远程组件通过 `invokeClientCommand` 调用，并处理结构化失败结果。

```ts theme={null}
import {
  WORKBENCH_NAVIGATION_OPEN_COMMAND,
  WORKBENCH_EXTENSION_VIEW_TARGET
} from '@xpert-ai/contracts'

await requestHost('invokeClientCommand', {
  commandKey: WORKBENCH_NAVIGATION_OPEN_COMMAND,
  payload: {
    target: WORKBENCH_EXTENSION_VIEW_TARGET,
    viewKey: 'contract_review__history',
    selectionId: contractId
  }
})
```

不要从 iframe 直接修改顶层窗口地址。

## 宿主事件

远程组件可以订阅宿主归一化后的事件，例如 Agent 中间件工具完成：

```ts theme={null}
hostEvents: {
  subscriptions: [
    {
      key: 'contract-mutated',
      event: 'assistant.tool.completed',
      filter: {
        sources: ['chatkit'],
        toolNames: ['contract_update', 'contract_approve']
      },
      action: { type: 'forward', debounceMs: 800 }
    }
  ]
}
```

声明式视图通常使用 `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 添加自动化测试。

返回[工作台远程组件](./remote-component)查看完整开发流程。