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

基本介绍​

源码插件通过services.Files()访问宿主文件管理能力。动态插件通过plugin.yaml声明service: files后使用pluginbridge.Default().Files()客户端访问。

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能力中引用受保护的输入或输出资产

接口定义​

源码插件接口​

方法说明
Get读取单个可见文件视图
Detail读取单个可见文件详情，包含原始文件名、访问URL和上传者
BatchGet批量读取可见文件视图，返回BatchResult
List按业务场景、关键词和媒体类型搜索可见文件候选
ListScenes返回受管控的文件业务场景选项
ListSuffixes返回可见文件后缀选项
Open打开可见文件流，经过目标和租户校验
EnsureVisible校验目标文件集合对当前调用上下文可见
Upload从上传内容创建宿主文件记录
CreateFromStorage从插件存储对象提升为宿主文件记录
UpdateMetadata更新可见文件元数据（文件名、业务场景）
Delete删除可见文件，经过场景、目标和租户校验
DeleteMany批量删除可见文件

动态插件接口​

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

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

动态方法能力常量说明
files.batch_gethost:files批量读取可见文件视图
files.searchhost:files按业务场景、关键词和媒体类型搜索可见文件候选
files.visible.ensurehost:files校验文件可见性

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

动态方法说明
storage.put写入对象
storage.get读取对象
storage.delete删除对象
storage.delete_many批量删除对象
storage.list列举对象
storage.list_cursor游标分页列举对象
storage.stat查询对象元数据
storage.batch_stat批量查询对象元数据

能力使用​

源码插件使用​

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

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

// 搜索可见文件候选
page, err := services.Files().List(ctx, filecap.ListInput{
    BusinessScene: "avatar",
    Keyword:       "profile",
    MimeType:      "image/png",
    Page:          pageRequest,
})

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

// 上传文件
fileInfo, err := services.Files().Upload(ctx, filecap.UploadInput{
    Filename:       "report.pdf",
    BusinessScene:  "export",
    Reader:         fileReader,
    SizeBytes:      fileSize,
})

// 从存储对象提升为宿主文件
fileInfo, err := services.Files().CreateFromStorage(ctx, filecap.CreateFromStorageInput{
    StoragePath:   "exports/report.pdf",
    Filename:      "report.pdf",
    BusinessScene: "export",
    SizeBytes:     fileSize,
})

// 打开文件流
content, err := services.Files().Open(ctx, fileID)
defer content.Reader.Close()

// 删除文件
err := services.Files().Delete(ctx, fileID)

动态插件使用​

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

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

设计约束​

  • 不暴露物理路径。 FileInfo和DetailInfo不包含存储路径或哈希值。
  • 删除经过治理校验。 Delete和DeleteMany经过场景、目标、租户和审计校验后执行。
  • 上传有大小限制。 动态插件直接上传上限10MB，大文件应使用CreateFromStorage从插件存储提升。
  • 可见性由宿主控制。 文件是否对当前插件可见，由宿主基于租户和数据范围决定。

相关服务​