WorkspaceFilesRuntimeCapability 通过稳定 ID platform.workspace.files 暴露 WorkspaceFilesApi,是插件访问 Xpert 工作区存储卷的统一文件边界。
请使用该能力替代直接读取宿主文件系统或自建插件存储。它会保留平台作用域,为异步任务返回可移植引用,并可将已有文件接入平台文件理解流程。
目录与作用域
支持以下逻辑目录:WorkspaceFileScope 中的 tenantId、organizationId、userId、catalog、scopeId、projectId、knowledgeId、rootId 和 xpertId 等字段。运行时感知 API 会尽可能从当前智能体工作区推导作用域。
对于运行时相对路径,宿主需要绑定明确数据所有者:Project 模式绑定 projectId;非 Project 模式绑定 xpertId。个人 Xpert 使用 catalog: 'user-xperts',其中 scopeId 是 Xpert ID,userId 作为独立字段保留用户隔离。不要把 userId 和 xpertId 拼进一个 scopeId。
filePath 始终是相对工作区存储卷的路径,不是 /workspace/...,也不是宿主或 API 进程的文件系统路径。
在 NestJS Provider 中获取文件能力
智能体中间件直接使用context.runtime.capabilities。View Provider、Controller 或任务可从 XPERT_RUNTIME_CAPABILITIES_TOKEN 解析工作区文件,并调用 readBuffer、uploadBuffer 等显式作用域方法;每次操作仍会解析并授权目标存储卷。
需要为运行时相对路径绑定 Agent 默认值时,注入 XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN,根据宿主解析出的上下文创建 scoped API:
WorkspaceFilesRuntimeCapability。直接领域 API 与 Agent scoped facade 服务于不同调用方式,不能用其中一种绕过另一种的授权失败。scoped 调用不能通过工具输入覆盖绑定的数据所有者。完整的 Provider 获取规则见运行时能力。
助手文件与应用状态
用于创作资源的XpertWorkspace 不等于助手文件 ACL。非项目文件按具体已发布助手的访问策略授权:共享模式允许已授权用户协作,用户模式绑定当前认证用户。不能以创作工作区成员资格或助手创建者身份替代运行时文件授权。项目文件继续检查当前成员资格和助手绑定。
files.appData({ pluginName, projectId?, requireUserIsolation? }) 返回用于插件持久化应用状态的 WorkspaceStorage 句柄。宿主从已加载插件元数据解析命名空间。使用 read、write、mkdir、list、remove 和 withLock;路径及锁键必须是规范相对路径。工作区策略变化后重新创建句柄,个人数据应显式使用用户隔离存储。锁用于协调写入,不授予权限。
项目文件树与比较后写入见内容与编辑器运行时。
选择正确的引用类型
可移植引用包含
source: 'platform.workspace.files'、稳定 filePath、作用域元数据和面向运行时的 workspacePath。请持久化完整引用,不要将其简化成沙箱路径。
文件操作
读取智能体工具传入的路径:
文件理解
文件理解 API 复用平台现有的文件资产(FileAsset)和文件分块(FileChunk)索引,不会创建插件私有的重复索引。
注册并搜索文件:
listUnderstandingChunks() 的页码从 1 开始,并返回 hasMore。宿主会限制页大小、搜索数量、摘录长度和单个分块的内容长度。消费者应分页获取,不能假定一次调用会返回完整文档。
vectorIndexStatus 的取值为 pending、ready、failed 或 unavailable。在开放语义搜索前,应将它与通用解析 status 分开检查。
WorkspaceMediaFilesApi<TLocator> 是面向媒体生成适配器的窄类型。它要求实现 uploadBuffer() 和 readBuffer(),并可选暴露 readRuntimeBuffer() 与 deleteFile();当组件不应依赖完整工作区文件 API 时使用该类型。
安全与生命周期
- 每次操作都从可信服务端上下文推导显式作用域或创建 scoped facade,不要跨用户、助手或项目缓存绑定的文件 API 或存储句柄。
- 只需要元数据或可打开 URL 时优先使用
resolveFile();只有实际处理内容时才读取字节。 - 不要将
/workspace/...路径放入延迟任务;应先用resolveRuntimeReference()转换。 - 在展示证据或据此执行操作前,使用
validateUnderstandingReferences()重新校验证据。 - 所有显式操作都要声明作用域,不要从不可信绝对路径构造
filePath。 - 原始字节缓冲区(
Buffer)只属于当前服务端操作;后续工作应持久化可移植引用。