@xpert-ai/plugin-sdk 导出。
能力模型
能力键是一个冻结对象,包含稳定 ID、说明和仅用于 TypeScript 推导的 API 类型:get() 和 require() 推导出准确 API 类型,也能让宿主与动态加载的插件通过稳定 ID 对齐同一份契约。
能力注册表提供四个操作:
在智能体中间件中解析能力
智能体中间件可通过context.runtime.capabilities 访问当前执行范围内的能力注册表:
get();只有在插件已确认该能力是当前操作的必要前提时,才使用 require():
在 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,不要通过队列或持久化聊天元数据传递原始文件字节、持有者令牌、宿主路径或实现实例。
- 将能力返回值限制在当前授权范围内;后续任务或回调应重新解析所需资源。