Remote Component 插件开发

本文说明如何开发一套新的 Assistant Workbench remote_component 类型插件。remote_component 是 View Extension 的一种视图 schema，不限定触发方式：它既可以作为普通 view slot 被宿主枚举展示，也可以由工具结果中的 xpert.extension_view 显式触发。该模式适合插件需要完整自定义 UI，而不是只使用声明式 table、list、stats、detail renderer 的场景。

架构

一套 remote component 插件至少由两部分组成；如果需要让 Agent 在对话中按需打开视图，再额外提供工具入口：

ViewExtensionProvider：提供 manifest、data、parameter options、actions 和远程组件 HTML entry。
远程 React 页面：运行在 sandbox iframe 中，通过 postMessage 与宿主通信。
可选工具入口：返回 _meta['xpertai/visualization']，其中 type 为 xpert.extension_view，用于工具触发型场景。

iframe 不是可信 API 调用方，因此不会拿到：

access token
API base URL
assistantId
hostId
hostType
权限信息

请求链路是：

remote iframe
  -> postMessage(requestData / requestParameterOptions / executeAction)
  -> data-xpert Workbench 宿主页面
  -> authenticatedFetch(...)
  -> data-xpert API proxy
  -> xpert-pro ViewExtension API
  -> 插件 ViewExtensionProvider

认证和授权发生在 data-xpert 与 xpert-pro：

data-xpert Web 通过 authenticatedFetch 携带当前用户 OIDC token。
data-xpert API 校验当前用户，并根据 assistantCode 解析 effective assistant。
data-xpert API 固定转发到 hostType=agent 和 hostId=<assistant.assistantId>。
xpert-pro 在调用 provider 前校验 view host 访问权限、manifest 可见性和 action 权限。

定义稳定 Key

先定义稳定 key。它们会成为 view host、Workbench canvas、可选工具结果和 provider 之间的公开协议。

export const PROVIDER_KEY = 'my_metric_management'
export const VIEW_KEY = 'metrics'
export const PUBLIC_VIEW_KEY = 'my_metric_management__metrics'
export const REMOTE_ENTRY_KEY = 'metric-management'

公开 view key 的规则是：

<providerKey>__<manifestKey>

选择视图触发方式

remote_component 可以通过两种方式进入宿主界面：

Slot 枚举型：宿主调用 GET /api/view-hosts/:hostType/:hostId/slots/:slot/views 获取某个 slot 下的 views，并按 manifest 渲染 remote component。
工具触发型：工具调用结果携带 _meta['xpertai/visualization']，宿主只在对应工具被使用后打开这个视图。

如果你的插件视图是某个宿主页面的常驻扩展入口，优先使用 slot 枚举型。如果视图只应该随着某个工具调用结果出现，例如“打开指标管理”，再使用工具触发型。

可选：通过工具触发视图

工具只负责打开视图，不应该返回远程页面需要展示的完整数据。

return {
  content: [
    {
      type: 'text',
      text: '正在打开指标管理。'
    }
  ],
  _meta: {
    'xpertai/visualization': {
      type: 'xpert.extension_view',
      title: '指标管理',
      slotKey: 'tool:metric-management',
      parameterKey: `metrics:${projectId ?? 'all'}:${modelId ?? 'all'}`,
      renderMode: 'replace',
      payload: {
        version: 1,
        viewKey: 'my_metric_management__metrics',
        parameters: {
          projectId,
          modelId
        },
        initialQuery: {
          page: 1,
          pageSize: 20
        }
      },
      metadata: {
        source: 'mcp-tool',
        sourceId: 'metric_management_open'
      }
    }
  }
}

不要在工具结果中放 hostId、hostType、API URL、token 或权限信息。真实宿主由 data-xpert 后端根据当前会话重新解析。

提供 Remote Component Manifest

通过 @ViewExtensionProvider(providerKey) 注册 provider，并在 agent.workbench.main slot 中返回 remote_component + react + iframe manifest。

import {
  IXpertViewExtensionProvider,
  ViewExtensionProvider
} from '@xpert-ai/plugin-sdk'
import type {
  XpertExtensionViewManifest,
  XpertResolvedViewHostContext
} from '@xpert-ai/contracts'

@ViewExtensionProvider('my_metric_management')
export class MetricManagementViewProvider
  implements IXpertViewExtensionProvider
{
  supports(context: XpertResolvedViewHostContext) {
    return context.hostType === 'agent'
  }

  getViewManifests(
    _context: XpertResolvedViewHostContext,
    slot: string
  ): XpertExtensionViewManifest[] {
    if (slot !== 'agent.workbench.main') {
      return []
    }

    return [
      {
        key: 'metrics',
        title: { en_US: 'Metric Management', zh_Hans: '指标管理' },
        hostType: 'agent',
        slot,
        refreshable: true,
        parameters: [
          {
            key: 'projectId',
            label: { en_US: 'Project', zh_Hans: '项目' },
            required: true,
            type: 'string',
            optionSource: {
              mode: 'provider',
              searchable: true,
              preload: true
            }
          },
          {
            key: 'modelId',
            label: { en_US: 'Model', zh_Hans: '模型' },
            type: 'string',
            optionSource: {
              mode: 'provider',
              searchable: true,
              dependsOn: ['projectId']
            }
          }
        ],
        view: {
          type: 'remote_component',
          runtime: 'react',
          protocolVersion: 1,
          component: {
            isolation: 'iframe',
            entry: 'metric-management'
          },
          dataSource: {
            mode: 'platform'
          }
        },
        dataSource: {
          mode: 'platform',
          querySchema: {
            supportsPagination: true,
            supportsSearch: true,
            supportsSort: true,
            supportsParameters: true,
            defaultPageSize: 20
          },
          cache: {
            enabled: false
          }
        },
        actions: [
          {
            key: 'create',
            label: { en_US: 'Create', zh_Hans: '新建' },
            placement: 'toolbar',
            actionType: 'invoke'
          },
          {
            key: 'edit',
            label: { en_US: 'Edit', zh_Hans: '编辑' },
            placement: 'row',
            actionType: 'invoke',
            inputDefaults: 'target'
          }
        ]
      }
    ]
  }
}

如果变更类 action 需要比读取视图更高的权限，应在 action 上声明 permissions。

返回 iframe HTML Entry

provider 需要为 iframe 返回单文件 HTML。推荐使用 @xpert-ai/plugin-sdk 的 renderRemoteReactIframeHtml()，让多个插件共享同一套 shell、reset、主题变量和 .xui-* UI 类。

import { createRequire } from 'module'
import { readFile } from 'fs/promises'
import { dirname, join } from 'path'
import {
  IXpertViewExtensionProvider,
  renderRemoteReactIframeHtml
} from '@xpert-ai/plugin-sdk'
import type {
  XpertRemoteComponentEntry,
  XpertRemoteComponentViewSchema,
  XpertResolvedViewHostContext
} from '@xpert-ai/contracts'

const requireFromHere = createRequire(__filename)

async function readPackageFile(packageName: string, relativePath: string) {
  const packageRoot = dirname(
    requireFromHere.resolve(`${packageName}/package.json`)
  )
  return readFile(join(packageRoot, relativePath), 'utf8')
}

export class MetricManagementViewProvider
  implements IXpertViewExtensionProvider
{
  async getRemoteComponentEntry(
    _context: XpertResolvedViewHostContext,
    viewKey: string,
    component: XpertRemoteComponentViewSchema['component']
  ): Promise<XpertRemoteComponentEntry> {
    if (viewKey !== 'metrics' || component.entry !== 'metric-management') {
      return {
        html: '<!doctype html><html><body>Unsupported entry.</body></html>',
        contentType: 'text/html; charset=utf-8'
      }
    }

    const appScript = await readFile(
      join(__dirname, 'remote-components', 'metric-management', 'app.js'),
      'utf8'
    )
    const react = await readPackageFile('react', 'umd/react.production.min.js')
    const reactDom = await readPackageFile(
      'react-dom',
      'umd/react-dom.production.min.js'
    )

    return {
      html: renderRemoteReactIframeHtml({
        title: '指标管理',
        lang: 'zh-Hans',
        reactUmd: react,
        reactDomUmd: reactDom,
        appScript
      }),
      contentType: 'text/html; charset=utf-8'
    }
  }
}

entry 是 provider-local key，不是浏览器 URL。ViewExtension API 会拒绝绝对 URL、..、反斜杠等不安全值。

实现 Remote Bridge Client

iframe 页面通过 message 与父窗口通信，并用 requestId 关联响应。

(function () {
  const CHANNEL = 'xpertai.remote_component'
  const VERSION = 1
  let instanceId = null
  let sequence = 0
  const pending = new Map()

  function post(type, body) {
    if (!instanceId && type !== 'ready') return
    parent.postMessage(
      {
        channel: CHANNEL,
        protocolVersion: VERSION,
        instanceId,
        type,
        ...(body || {})
      },
      '*'
    )
  }

  function request(type, body) {
    const requestId = String(++sequence)
    post(type, { requestId, ...(body || {}) })
    return new Promise((resolve, reject) => {
      pending.set(requestId, { resolve, reject })
    })
  }

  window.addEventListener('message', (event) => {
    const message = event.data
    if (
      !message ||
      message.channel !== CHANNEL ||
      message.protocolVersion !== VERSION
    ) {
      return
    }

    if (message.type === 'init') {
      instanceId = message.instanceId
      window.startApp({
        manifest: message.manifest,
        payload: message.payload,
        initialQuery: message.initialQuery || {},
        locale: message.locale,
        theme: message.theme
      })
      return
    }

    if (message.instanceId !== instanceId) return

    if (message.requestId && pending.has(message.requestId)) {
      const item = pending.get(message.requestId)
      pending.delete(message.requestId)
      if (message.type === 'error') {
        item.reject(new Error(message.message || 'Remote request failed'))
      } else {
        item.resolve(message)
      }
    }
  })

  window.xpertRemote = { request }
  post('ready')
})()

Workbench 宿主只接受来自当前 iframe contentWindow 且 instanceId 匹配的消息。

示例：获取指标列表

远程页面不直接调用 fetch，而是请求宿主读取 view data：

async function loadData(query) {
  const response = await window.xpertRemote.request('requestData', {
    query: {
      page: query.page,
      pageSize: query.pageSize,
      search: query.search,
      parameters: {
        projectId: query.parameters.projectId,
        modelId: query.parameters.modelId
      }
    }
  })

  setData(response.data || { items: [], total: 0 })
}

宿主会转成：

GET /agent-workbench/extensions/:assistantCode/views/:viewKey/data
  ?page=1
  &pageSize=20
  &search=收入
  &parameters={"projectId":"project-1","modelId":"model-1"}
Authorization: Bearer <current-user-token>

data-xpert API 解析 assistant 后转发到 xpert-pro：

GET /api/view-hosts/agent/:assistantId/views/:viewKey/data
Authorization: Bearer <current-user-token>
organization-id: <assistant-organization-id>

provider 处理查询：

async getViewData(
  _context: XpertResolvedViewHostContext,
  viewKey: string,
  query: XpertViewQuery
): Promise<XpertViewDataResult> {
  if (viewKey !== 'metrics') {
    return {}
  }

  const projectId = getStringParameter(query.parameters, 'projectId')
  if (!projectId) {
    return {
      items: [],
      total: 0,
      meta: {
        reason: 'project_required'
      }
    }
  }

  const modelId = getStringParameter(query.parameters, 'modelId')
  const page = query.page ?? 1
  const pageSize = query.pageSize ?? 20

  const result = await this.indicatorService.findMy({
    where: buildIndicatorWhere(projectId, modelId, query.search),
    relations: ['model'],
    take: pageSize,
    skip: (page - 1) * pageSize,
    order: buildIndicatorOrder(query.sortBy, query.sortDirection)
  })

  return {
    items: result.items.map(toMetricRow),
    total: result.total
  }
}

结果会通过 message 回到 iframe：

{
  type: 'data',
  requestId,
  data: {
    items: [],
    total: 0
  }
}

示例：保存单个指标

新建和编辑可以复用同一个表单。远程页面提交受控 action：

async function saveMetric(mode, row, form, query) {
  const input = {
    code: form.code.trim(),
    name: form.name.trim(),
    type: form.type,
    modelId: form.modelId || undefined,
    entity: form.entity.trim() || undefined,
    business: form.business.trim() || undefined,
    unit: form.unit.trim() || undefined,
    visible: form.visible
  }

  const response = await window.xpertRemote.request('executeAction', {
    actionKey: mode === 'create' ? 'create' : 'edit',
    targetId: row && row.id,
    input,
    parameters: query.parameters
  })

  if (response.result?.refresh) {
    await loadData(query)
  }
}

宿主会转成：

POST /agent-workbench/extensions/:assistantCode/views/:viewKey/actions/edit
Authorization: Bearer <current-user-token>
Content-Type: application/json

{
  "targetId": "metric-1",
  "input": {
    "code": "gmv",
    "name": "GMV",
    "type": "BASIC",
    "modelId": "model-1",
    "business": "订单总成交额",
    "unit": "元",
    "visible": true
  },
  "parameters": {
    "projectId": "project-1",
    "modelId": "model-1"
  }
}

provider 执行变更：

async executeViewAction(
  _context: XpertResolvedViewHostContext,
  viewKey: string,
  actionKey: string,
  request: XpertViewActionRequest
): Promise<XpertViewActionResult> {
  if (viewKey !== 'metrics') {
    return failure('Unsupported view', '不支持的视图')
  }

  if (actionKey === 'create') {
    const projectId = getStringParameter(request.parameters, 'projectId')
    if (!projectId) {
      return failure('Project is required', '请先选择项目')
    }

    await this.indicatorService.createDraft(
      toIndicatorDraft(request.input),
      projectId
    )
    return success('Metric created', '指标已创建')
  }

  const targetId = request.targetId?.trim()
  if (!targetId) {
    return failure('Target metric is required', '缺少目标指标')
  }

  if (actionKey === 'edit') {
    await this.indicatorService.updateDraft(
      targetId,
      toIndicatorDraft(request.input)
    )
    return success('Metric updated', '指标已更新')
  }

  return failure('Unsupported action', '不支持的操作')
}

变更类 action 成功后应返回 refresh: true，这样宿主可以清理缓存，远程页面也可以刷新当前查询。

function success(en_US: string, zh_Hans: string): XpertViewActionResult {
  return {
    success: true,
    message: { en_US, zh_Hans },
    refresh: true
  }
}

参数选项

下拉框和依赖字段使用 requestParameterOptions：

const projects = await window.xpertRemote.request('requestParameterOptions', {
  parameterKey: 'projectId',
  parameters: query.parameters
})

const models = await window.xpertRemote.request('requestParameterOptions', {
  parameterKey: 'modelId',
  parameters: {
    ...query.parameters,
    projectId
  }
})

provider 实现：

async getViewParameterOptions(
  _context: XpertResolvedViewHostContext,
  viewKey: string,
  parameterKey: string,
  query: XpertViewParameterOptionsQuery
): Promise<XpertViewParameterOptionsResult> {
  if (viewKey !== 'metrics') {
    return { items: [] }
  }

  if (parameterKey === 'projectId') {
    return {
      items: projects.map((project) => ({
        value: project.id,
        label: project.name ?? project.id
      }))
    }
  }

  if (parameterKey === 'modelId') {
    const projectId = getStringParameter(query.parameters, 'projectId')
    return {
      items: modelsFor(projectId).map((model) => ({
        value: model.id,
        label: model.name ?? model.id
      }))
    }
  }

  return { items: [] }
}

样式

remote component 应使用 renderRemoteReactIframeHtml() 提供的共享 .xui-* 类：

.xui-app
.xui-toolbar
.xui-control
.xui-input
.xui-button
.xui-button-primary
.xui-table
.xui-modal
.xui-notice

宿主会发送 init.theme.tokens，helper 会把它们映射为 --xui-* CSS variables。插件 CSS 应只补充业务布局，不要重新定义基础控件视觉。

构建 Assets

如果远程脚本放在插件源码目录下，需要确保包构建时复制到生产输出目录。

{
  "glob": "**/*.{html,css,js}",
  "input": "packages/analytics/src/plugins",
  "output": "src/plugins"
}

测试清单

上线前建议验证：

工具返回合法 xpert.extension_view payload。
公开 view key 符合 <providerKey>__<manifestKey>。
manifest 返回 remote_component + react + iframe。
getRemoteComponentEntry 返回 HTML，且不包含 token、API URL、assistantId 或 hostId。
列表加载通过 requestData。
保存通过 executeAction。
参数 options 支持独立字段和依赖字段。
无权限用户无法访问 view host。
必要时变更类 action 拥有比读取视图更严格的权限。
iframe 在 sandbox="allow-scripts" 且没有直接网络凭据的情况下可以正常工作。

默认

触发器

集成

飞书文档示例

Remote Component 插件开发

Remote Component 插件开发

架构

定义稳定 Key

选择视图触发方式

可选：通过工具触发视图

提供 Remote Component Manifest

返回 iframe HTML Entry

实现 Remote Bridge Client

示例：获取指标列表

示例：保存单个指标

参数选项

样式

构建 Assets

测试清单

​Remote Component 插件开发

​架构

​定义稳定 Key

​选择视图触发方式

​可选：通过工具触发视图

​提供 Remote Component Manifest

​返回 iframe HTML Entry

​实现 Remote Bridge Client

​示例：获取指标列表

​示例：保存单个指标

​参数选项

​样式

​构建 Assets

​测试清单

Remote Component 插件开发

架构

定义稳定 Key

选择视图触发方式

可选：通过工具触发视图

提供 Remote Component Manifest

返回 iframe HTML Entry

实现 Remote Bridge Client

示例：获取指标列表

示例：保存单个指标

参数选项

样式

构建 Assets

测试清单