跳到主要内容
版本：0.4.x(Latest)

基本介绍​

源码插件通过services.Files()读取宿主管理文件的可见视图。动态插件通过plugin.yaml声明service: files后使用BatchGetFiles和EnsureFilesVisible。可信源码插件需要删除宿主文件时，使用services.Admin().Files().DeleteFiles。

Files能力面向宿主文件管理系统的只读访问。插件不能通过此能力上传文件或修改文件元数据。

能力阶段：运行期

类型支持：源码插件、动态插件

能力设计​

宿主文件管理模型​

宿主文件管理以sys_file表为核心，管理用户上传文件的完整生命周期：

字段说明
id文件主键
tenant_id租户归属
name存储文件名
original原始文件名
suffix文件扩展名
scene业务场景标识
size文件大小
hashSHA-256哈希值，用于去重
url访问路径
path物理存储路径
engine存储引擎标识
created_by上传者

上传流程自动计算SHA-256哈希，在同一租户内实现文件去重：相同哈希的文件复用物理存储，仅创建新的元数据记录。

插件可见视图​

插件通过FileProjection访问文件信息，不暴露物理存储路径、哈希值或底层存储后端：

字段说明
ID文件标识
Name展示文件名
MimeType媒体类型
SizeBytes文件大小
BusinessScene业务场景

与其他资源能力的关系​

能力用途
Files()读取宿主文件管理视图，例如用户上传文件、业务附件
Storage()插件自己的对象读写，例如导出结果、临时产物
Manifest()读取插件随产物发布的只读manifest/资源
AI AssetRef在AI能力中引用受保护的输入或输出资产

接口定义​

源码插件接口​

入口方法说明
Files()BatchGetFiles批量读取可见文件视图
Files()EnsureFilesVisible校验目标文件集合对当前调用上下文可见
Admin().Files()DeleteFiles删除可见文件，由宿主执行场景和目标校验

动态插件接口​

动态插件可访问两类服务：

files服务——宿主文件视图：

动态方法能力常量说明
files.batch_gethost:files批量读取可见文件视图
files.visible.ensurehost:files校验文件可见性

storage服务——插件作用域对象存储：

动态方法说明
storage.put写入对象
storage.get读取对象
storage.delete删除对象
storage.list列举对象
storage.stat查询对象元数据

能力使用​

源码插件使用​

源码插件通过services.Files()读取宿主管理文件视图：

// 批量读取文件视图
result, err := services.Files().BatchGetFiles(ctx, capabilityCtx, fileIDs)

// 校验文件可见性
err := services.Files().EnsureFilesVisible(ctx, capabilityCtx, fileIDs)

可信源码插件删除文件：

err := services.Admin().Files().DeleteFiles(ctx, capabilityCtx, fileIDs)

动态插件使用​

动态插件在plugin.yaml中声明files服务：

hostServices:
  - service: files
    methods:
      - batch_get
      - visible.ensure

设计约束​

  • 只读视图。 插件不能通过Files能力上传或修改文件，只能读取和校验。
  • 不暴露物理路径。 FileProjection不包含存储路径、哈希值或访问URL。
  • 删除属于治理命令。 删除操作必须走Admin().Files()，由宿主执行场景和目标校验。
  • 可见性由宿主控制。 文件是否对当前插件可见，由宿主基于租户和数据范围决定。

相关服务​