视图扩展

了解 Xpert 插件如何通过视图提供器和视图清单，把声明式视图或远程组件接入工作台等宿主界面。

​

视图扩展

视图扩展（View Extension）是插件向 Xpert 宿主界面提供可交互视图的标准协议。它定义视图出现在哪里、何时可见、能够读取哪些数据、允许执行哪些操作，以及由哪种方式完成渲染。

对于 Assistant 工作台，远程组件（Remote Component）是视图扩展的一种渲染方式。它负责 iframe 中的自定义前端 UI；视图扩展负责宿主插槽、功能激活、权限、数据和操作等完整契约。

Assistant 功能
  -> 工作台视图宿主
  -> agent.workbench.main / agent.workbench.fixed
  -> ViewExtensionProvider
  -> XpertExtensionViewManifest
  -> 平台声明式渲染器或远程组件

​

核心概念

概念	职责
宿主（Host）	提供可扩展的产品界面和当前用户上下文，例如 Assistant、项目或知识库
插槽（Slot）	宿主中允许视图出现的位置，例如 agent.workbench.main
视图提供器（View Provider）	插件服务端实现，提供视图清单、数据、操作和可选的远程组件入口
视图清单（Manifest）	声明视图的位置、激活条件、渲染方式和能力白名单
远程组件（Remote Component）	在宿主控制的 iframe 中运行的插件自定义前端 UI

远程组件不是独立的插件类型，也不能脱离视图清单单独注册。完整的工作台 UI 通常由服务端视图提供器和前端远程组件共同组成。

​

宿主与插槽

hostType 表示宿主类型。平台可以提供 agent、project、knowledgebase、integration 或 sandbox 等宿主。

Assistant 工作台使用 agent 宿主，常用插槽包括：

插槽	用途
agent.workbench.main	随当前工作台内容展示的主视图
agent.workbench.fixed	在工作台菜单中提供固定入口的视图
agent.profile.tabs	Assistant 资料卡内按需加载的 tabs
detail.sidebar	宿主详情页侧栏中的补充视图

插件只能向宿主已经声明的插槽提供视图。插槽描述产品位置，不应包含插件业务名称。

​

功能激活

Assistant 工作台插槽要求视图声明 activation.requiredFeatures。功能（Feature）是连接 Agent 能力和人类工作台界面的能力令牌：

Agent 中间件声明 Feature
  -> Assistant 连接该中间件
  -> 视图宿主获得功能
  -> 对应 View 才可见

activation: {
  requiredFeatures: ['contract-review']
}

视图应依赖拥有其数据与操作的领域能力。移除对应中间件后，它提供的 Agent 工具和工作台视图应一起消失。

​

视图提供器

插件通过 @ViewExtensionProvider(providerKey) 注册视图提供器：

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

@ViewExtensionProvider('contract_review')
export class ContractReviewViewProvider
  implements IXpertViewExtensionProvider
{
  constructor(private readonly reviewService: ContractReviewService) {}

  supports(context: XpertResolvedViewHostContext) {
    return context.hostType === 'agent'
  }

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

  async getViewData(
    context: XpertResolvedViewHostContext,
    viewKey: string,
    query: XpertViewQuery
  ): Promise<XpertViewDataResult> {
    return this.reviewService.getViewData(context, viewKey, query)
  }
}

提供器中的 viewKey 是本地清单键。平台公开的完整视图键为：

<providerKey>__<manifestKey>

例如 contract_review 提供器中的 review 视图，对外键为 contract_review__review。

​

选择渲染方式

视图清单的 view.type 决定渲染方式：

类型	适用场景	UI 所有者
stats	少量指标概览	平台
table	标准表格、搜索、排序和分页	平台
list	标准列表	平台
detail	只读字段详情	平台
raw_json	调试或原始数据展示	平台
remote_component	编辑器、画布、复杂工作流或多面板工作台	插件

优先选择能满足需求的声明式视图。只有在交互和布局明显超出平台表格、列表或表单能力时，才使用远程组件。

​

视图清单是能力白名单

视图清单不仅描述页面，还声明远程组件能够使用的宿主能力：

清单字段	能力
dataSource	查询视图数据、分页、搜索、排序和参数支持
parameters	视图参数以及服务端提供的动态选项
actions	JSON 操作或文件操作
fileAccess	预览或下载由提供器解析的文件
clientCommands	打开文件、导航或发送 Assistant 消息等宿主界面操作
hostEvents	接收工具完成等宿主侧事件
permissions	访问整个视图所需的权限

远程组件不能把宿主桥接当作任意远程调用通道。每项数据访问或操作都必须先在清单中声明，再由宿主和提供器执行。

​

打开方式与渲染方式彼此独立

视图可以由宿主枚举插槽后展示，也可以由工具结果中的 xpert.extension_view 按需打开。这只是入口不同，不会改变视图的清单、权限、数据提供器或远程组件实现。

工具结果只应携带公开视图键、初始查询和业务参数，不应包含访问令牌、API 地址、Assistant ID、租户 ID 或组织 ID。

​

安全边界

• 宿主根据已认证的服务端状态解析 hostType、hostId、租户、组织和用户。
• 清单由平台校验并按功能激活和权限过滤。
• 远程组件不接收访问令牌、平台 API 地址或宿主内部身份字段。
• 提供器必须重新校验业务权限，不能只信任 iframe 传入的业务 ID。
• JSON 操作用于有界结构化数据；文件和大对象使用专用能力。

​

下一步

• 工作台远程组件：构建插件自定义工作台 UI。
• 远程组件宿主桥接：查看消息、清单和提供器方法之间的映射。
• 运行时能力：在插件服务端调用宿主提供的平台服务。

​

Assistant Profile tabs

从 @xpert-ai/contracts 导入 AGENT_PROFILE_TABS_SLOT，向现有 agent host 注册视图。在 middleware metadata 中声明领域 Feature，每个 Profile manifest 都通过 activation.requiredFeatures 启用校验。同一 provider 可以同时提供 Workbench 与 Profile 视图。

import { AGENT_PROFILE_TABS_SLOT, type XpertExtensionViewManifest } from '@xpert-ai/contracts'

const profileTab: XpertExtensionViewManifest = {
  key: 'recent-cases',
  title: { en_US: 'Recent cases', zh_Hans: '最近案件' },
  hostType: 'agent', slot: AGENT_PROFILE_TABS_SLOT,
  activation: { requiredFeatures: ['case-profile'] },
  view: {
    type: 'remote_component', runtime: 'react', protocolVersion: 1,
    dataSource: { mode: 'platform' },
    component: { isolation: 'iframe', entry: 'case-profile' }
  },
  dataSource: { mode: 'platform', cache: { enabled: false } },
  actions: [{ key: 'approve_and_continue', label: '批准并继续',
    actionType: 'invoke', placement: 'row', requiredHostAccess: 'read' }],
  clientCommands: [{ key: 'assistant.profile.interaction' }, { key: 'assistant.profile.close' }]
}

​

可信身份与权限

getViewData(context, viewKey, query) 和 executeViewAction(context, viewKey, actionKey, request) 接收 XpertResolvedViewHostContext。Agent host 的后端专用 assistant 字段包含：

字段	含义
instanceId	此 host 解析出的已发布 Assistant
currentId	同一版本族中唯一的当前编辑实例；不存在时使用当前解析实例
versionIds	同一 Assistant 的版本身份集合，包含当前实例和发布版本

平台在租户、组织和工作空间边界内解析身份。不要根据名称、角色或相同模板推断实例。不要把 iframe query/action 中的 Assistant、用户、租户或组织 ID 当作授权依据。iframe 不接收认证信息，只通过 bridge 提交业务参数。

平台检查 host 访问、Feature、声明的 action 和 view session。Assistant 对业务资源的访问权限由插件控制。 工厂插件先将明确分配及执行参与记录，与当前人类用户可读的 Case Projects 取交集，再分页和统计。

服务端插件可以使用 @xpert-ai/plugin-sdk 的 ProjectAccessRuntimeCapability（platform.project.access），查询用户可读 Project（包含明确绑定的 assistantIds），通过 assertManage 校验 owner/manager 权限，或通过 assertEdit 校验 owner/manager/editor 权限。该能力供插件服务使用，不赋予 Agent 工具人类审批权。requiredHostAccess: 'read' 仅允许 Profile 读者进入 action 路由；插件必须再次校验具体案件的审批权限。

​

加载与决策生命周期

打开资料卡时获取基本资料和 manifests。扩展 tab 首次选中时实例化、查询并获取 view session，之后在资料卡打开期间保持挂载。切换 tab 时，宿主向隐藏的 Remote View 发送 viewActive: false；视图应暂停轮询、忽略过期响应，同时保留界面和数据状态。切回发送 viewActive: true，立即复用缓存数据，并从下一个轮询周期继续刷新。切换 Assistant 或关闭资料卡时释放全部缓存视图及 view session。基本资料接口 GET /xpert/:id/profile 返回展示白名单，不返回提示词、认证信息或完整 Assistant 图。

Profile Remote View 使用 opaque-origin iframe，不能读取 localStorage 或 sessionStorage。临时状态放在 React state 中，持久化状态通过 View actions 保存。

打开确认弹窗及提交期间，声明并调用 assistant.profile.interaction，传入 { busy: true }，结束后传 { busy: false }。宿主会保持卡片打开并禁止切换 tab。弹窗优先消费 Escape；没有弹窗和提交任务时，可调用 assistant.profile.close 关闭卡片并恢复焦点。销毁视图时一并注销命令作用域。

持久决策需携带业务版本和稳定的 operation ID。审批前展示方案和执行模式，审批与续跑意图在同一事务中保存，再通过 Managed Queue 和检查点推进。不要由浏览器编排后台续跑。工厂插件新增 approve_and_continue，保留原 approve_recovery_plan 语义，并始终使用 Factory Case 保存的协调 Assistant 派发验证任务，不替换成当前查看的专业 Assistant。