跳转到主要内容
运行时能力(Runtime Capability)是插件与 Xpert 宿主服务之间的类型安全边界。插件无需导入宿主实现类或重复搭建基础设施,即可使用工作区文件、知识库、产物、沙箱任务、操作者令牌和项目预配等平台能力。 本页涉及的公共类型和能力键均由 @xpert-ai/plugin-sdk 导出。

能力模型

能力键是一个冻结对象,包含稳定 ID、说明和仅用于 TypeScript 推导的 API 类型:
请使用 SDK 导出的能力键对象,不要直接使用字符串。能力键既能让 get() 和 require() 推导出准确 API 类型,也能让宿主与动态加载的插件通过稳定 ID 对齐同一份契约。 能力注册表提供四个操作:

在智能体中间件中解析能力

智能体中间件可通过 context.runtime.capabilities 访问当前执行范围内的能力注册表:
功能可以隐藏或降级时使用 get();只有在插件已确认该能力是当前操作的必要前提时,才使用 require():
能力注册表由宿主按执行上下文提供。能力方法仍会执行租户、组织、用户、工作区、项目和 Xpert 范围校验;调用者传入 ID 并不能绕过这些边界。

在 NestJS 服务提供器中解析能力

Nest 实例化模块后,平台通过 RuntimeCapabilityProvider 发现并填充注册表。注入 XPERT_RUNTIME_CAPABILITIES_TOKEN,在发现完成后的实际操作中解析能力;不要在服务构造函数中解析工厂。 当前平台注册表直接提供工作区文件能力。显式操作仍需正确授权的存储卷,运行时相对路径仍需绑定项目或助手;并非每个领域 API 都要求创建完整 Agent 运行时。 在平台注册表中应检查工厂能力是否存在,不能通过检查其 scoped 操作键来判断工厂是否安装。
authorizedScope 来自经过认证与授权的请求、已解析的 View 上下文或已恢复的任务身份。不能从 iframe 或工具输入构造租户、组织、用户、助手、项目、会话或执行身份。工厂本身不授予权限。 返回的 API 仅在当前操作内复用,不能缓存在单例或重新注册回平台注册表。连接绑定、令牌缓存和已签发视觉路径属于单次调用者/执行。

运行时包中的能力

将预配、项目访问与业务任务能力组合使用的产品体验和步骤,见 SDK 项目集成指南。 继续阅读详细参考:

定义能力与测试消费者

createRuntimeCapability<T>() 可为宿主或插件子系统创建类型化能力键。不要复用现有 platform.* ID 来承载不同契约。如果消费者不应注册实现,请使用只暴露 get() 的只读 RuntimeCapabilityResolver。
单元测试可使用 DefaultRuntimeCapabilityRegistry 注册类型化模拟实现:
生产插件通常只消费平台能力键,其实现由宿主基础设施注册。对于可选能力,应同时测试“可用”和“不可用”两条路径。

兼容性规则

  • 从 @xpert-ai/plugin-sdk 导入能力键和 API 类型,不要在插件中复制接口。
  • 根据契约选择领域 API、作用域工厂或 Agent facade;作用域 API 缺失时不能回退到更宽的权限。
  • 跨 SDK 副本使用稳定能力 ID,不要由插件分发平台 CQRS 类。宿主内部服务仍使用普通 Nest 注入,不能只为解耦模块而导出 SDK 能力。
  • 将能力可用性视为运行时条件。插件安装成功,并不代表宿主服务、提供器、绑定或已注册沙箱操作一定就绪。
  • 在异步边界传递可移植引用和结构化 DTO,不要通过队列或持久化聊天元数据传递原始文件字节、持有者令牌、宿主路径或实现实例。
  • 将能力返回值限制在当前授权范围内;后续任务或回调应重新解析所需资源。