Directus AI 的 files 工具文件元数据 CRUD 与远程文件导入实战指南【免费下载链接】directusThe flexible backend for all your projects Turn your DB into a headless CMS, admin panels, or apps with a custom UI, instant APIs, auth more.项目地址: https://gitcode.com/GitHub_Trending/di/directus导读在 Directus 的 AI Agent / MCP 能力体系中files是面向「文件资产」的核心工具它允许 AI 在不接触二进制内容的前提下查询文件元数据、批量更新标题与描述、维护标签与焦点坐标以及从外部 URL 直接导入远程文件。本指南以 files 工具提示词 为主干结合其 工具实现、Schema 定义 与 FilesService 服务层 源码系统讲解files工具的四个动作read/update/delete/import、全部元数据字段、真实业务用法与底层调用原理帮助你掌握在 Directus 中构建「内容素材管理」「资产清洗归档」「远程图片入库」等 AI 工作流的具体方法。工具定位什么是 Directus AI 的 files 工具files是 Directus 面向 AI 暴露的一组工具之一与collections、fields、items、folders、schema、relations等并列统一在 AI 工具入口 中注册导出。它在代码中的完整定义为export const files defineTool({ name: files, description: Reads and changes Directus file metadata or imports remote files. Use for uploads, media metadata, folders, titles, and file records., instructions: requireText(resolve(__dirname, ./prompt.md)), keywords: [media, upload, import, asset metadata, attachments, documents], annotations: { title: Directus - Files, destructiveHint: true, }, inputSchema: FilesInputSchema, validateSchema: FilesValidateSchema, output: FilesOutputSchema, readOnly: (input) input.action read, // ... });从源码可以看出几个关键设计点见 工具实现工具名固定为files供 Agent 在注册表中通过execute({ name: files, input })精确调用工具分发逻辑见 registry.ts。提示词即指令上面这份prompt.md通过requireText原样加载为工具的instructions它是引导大模型正确构造请求参数的「行为说明书」。readOnly是一个函数当action read时该调用被判定为只读从而可能跳过耗时的审批流程其余写操作update/delete/import被标记为需要额外确认。工具的 MCP annotations 中destructiveHint: true也提示消费方「该工具可能造成破坏」。要理解files的运行边界还需知道整个工具注册表的执行模型Agent 先用根工具search发现并加载工具详情再用根工具execute真正执行工具详情中会包含此处加载的instructions见 registry.ts如果调用上下文设置了allowDeletes false任何action: delete都会直接被拒绝并抛出InvalidPayloadError({ reason: Delete actions are disabled })见 registry.ts执行前请求参数会先经过 ZodvalidateSchema校验、再由isToolCallApproved决定是否需要用户批准见 registry.ts每个工具内部使用new FilesService({ schema, accountability })操作directus_files集合因此完整遵循 Directus 的权限系统accountability 即当前登录用户上下文。支持的动作read / update / delete / import根据 files 工具提示词 及 Schema 定义 中的 discriminated union工具按顶层action字段区分四种操作action用途必填参数read按 query 列出/查询元数据或按 keys 获取指定文件keys可选或query可选二选一update修改已有文件的元数据data对象或数组keys或query之一delete按 keys 删除文件含元数据与底层存储文件keys必填数组import从 URL 导入远程文件并创建/更新其元数据data数组每项含url与file对应地工具实现 的handler将四种动作分别映射到 FilesService 的方法调用链上read有keys时调用service.readMany(keys, sanitizedQuery)否则调用service.readByQuery(sanitizedQuery)最终返回{ type: text, data }update按data形态分流——data为数组走service.updateBatch(data)批处理每个元素必须含iddata为对象且提供keys走service.updateMany(keys, data)两者皆无则按query定位走service.updateByQuery(sanitizedQuery, data)。更新成功后统一回读readMany(updatedKeys)作为返回值delete调用service.deleteMany(args.keys)并返回被删除的主键列表import对data数组中的每一项循环调用service.importOne(file.url, file.file)收集保存后的主键返回。所有涉及查询的动作都会先经buildSanitizedQueryFromArgs把 AI 构造的查询对象清洗、校验为 Directus 标准 Query与 REST/GraphQL 走的查询管线保持一致见 utils.ts。操作示例详解下面完整继承提示词中的四类典型调用。1. 读取文件元数据批量查询{ action: read, query: { fields: [id, title, type, filesize, width, height], filter: { type: { _starts_with: image/ } }, limit: 10 } }含义只返回图片类文件MIME 以image/开头的 6 个字段最多 10 条。query支持完整 Directus 查询能力包括fields、filter、limit、offset、page、sort、search、deep、alias、aggregate、groupBy等全部字段可参考 QueryInputSchema。2. 读取单个文件元数据按主键{ action: read, keys: [file-uuid-here] }keys必须是数组[item]而非item元素为主键string 或 number见 PrimaryKeyInputSchema。同时省略query与keys时等价于不带任何条件地读取整个文件集合。3. 通过 URL 导入文件{ action: import, data: [ { url: file-url, file: { title: New Title, description: Updated description, tags: [tag1, tag2, category], folder: folder-uuid } } ] }url为要抓取的远程文件地址file为导入后要写入的元数据支持FileItemInputSchema任意子集。可一次传入多条记录批量导入。在底层每次导入都会调用 FilesService 的importOne见 files.ts其核心逻辑为先做访问校验validateAccess要求当前 accountability 对directus_files具备create权限通过 axios 以stream方式请求该 URL失败则抛ServiceUnavailableError错误码服务名external-file从响应的最终重定向地址解析出文件名、从content-type解析 MIME依次校验全局 MIME 白名单环境变量FILES_MIME_TYPE_ALLOW_LIST与字段级 MIME 限制不合规则抛InvalidPayloadError。提示这里的“文件元数据导入”不等同于本地文件上传。如果你需要让 AI 读取已上传文件的图像内容应配合提示词中提到的assets工具获取 base64 内容后再做视觉分析。4. 更新文件元数据单个文件按 keys 对象 data{ action: update, keys: [file-uuid], data: { title: New Title, description: Updated description, tags: [tag1, tag2, category], folder: folder-uuid } }批量更新data 为带 id 的数组{ action: update, data: [ { id: file-uuid-1, title: New Title 1 }, { id: file-uuid-2, title: New Title 2 } ] }当data是数组时其每个元素必须携带id走updateBatch路径这与仅按keys定位的“同一条更新作用于多个 key”是两种不同的语义实际对应测试用例可参见 files 工具测试其中分别验证了 keys 单对象、批量数组两种更新方式分别命中updateMany与updateBatch。5. 常用组合过滤器{ query: { filter: { _and: [ { type: { _icontains: /png } }, // PNG 文件 { folder: { _eq: folder-uuid } }, // 指定文件夹 { filesize: { _lt: 5000000 } }, // 小于 5MB { uploaded_on: { _gte: $NOW(-7 days) } } // 最近一周上传 ] } } }要点Directus 过滤器运算符均可用_eq、_starts_with、_icontains、_lt、_gte、_null等_and/_or用于组合多个条件时间字段支持$NOW(...)这类相对时间动态值如上例的“最近 7 天”注意_icontains的子串不包含前导点匹配/png而不是image/png的image/段可同时命中image/png等具体子类型。文件元数据字段清单提示词完整列出了directus_files的可写/可查元数据字段这些字段与 FileItemInputSchema 基本一一对应schema 还额外覆盖了charset、embed、tus_id、tus_data等内部字段字段含义id唯一标识符storage使用的存储适配器local / s3 / gcs…filename_disk磁盘上的实际文件名filename_download建议下载文件名title展示标题typeMIME 类型如image/jpeg、application/pdffolder父文件夹 IDuploaded_by上传用户uploaded_on上传时间戳modified_by最后修改者modified_on最后修改时间filesize字节数width/height图片像素尺寸duration音视频时长description文件描述location地理位置数据tags标签字符串数组如[product, red, handbag]metadata附加元数据对象focal_point_x水平焦点距左边缘的像素值focal_point_y垂直焦点距顶部边缘的像素值特别说明keys与tags都必须以数组形式传递[item]而非item这也是提示词「Key Points」中的硬性要求否则会在参数校验阶段被 Zod schema 拒绝。真实业务场景从素材检索到资产治理提示词为files工具规划了两大类实际用途下面完整展开并补充实现层面的解读。场景一为内容选择合适素材Asset Selection for Content典型诉求“在我们的素材库里为新的帮助中心文章找出与客户支持相关的图片。”{ action: read, query: { fields: [id, title, description, tags, type], search: help center } }search会对多个文本字段做模糊匹配是最轻量的全文检索手段。对于海量素材可配合filter先缩小范围如type、folder再结合fields控制返回体积避免把大文件二进制拉入上下文。场景二素材组织与清洗Asset Organization Cleanup把一堆无元数据的文件变成可检索、可分类的资产三步走① 找出缺失描述的文件{ action: read, query: { fields: [id, filename_disk, title, description], filter: { description: { _null: true } } } }② 用视觉分析内容如需理解图片语义可调用assets工具获取图片的 base64 数据交给视觉模型生成标题、描述与标签。③ 回写结构化元数据{ action: update, keys: [image-uuid], data: { title: Red leather handbag product photo, description: Professional e-commerce photo with white background, tags: [handbag, leather, red, product-photo, accessories], focal_point_x: 512, focal_point_y: 300 } }提示词特别注解了焦点坐标的意义当图片被裁剪成不同宽高比缩略图、横幅图等时focal_point_x/focal_point_y能确保重要主体始终处于可视区域坐标以原图左上角为原点、单位为像素。为图片写入准确焦点是电商、新闻类项目保证“自动裁剪不裁掉主体”的关键元数据资产。上述「查缺失 → 分析 → 回写」是一个可由 Agent 自主循环的经典流程read是只读操作readOnly: action read而update触达写路径并经由工具注册表进入审批/权限流程形成「批量只读侦察 单点人工确认写回」的安全模式。Key Points调用 files 工具必须遵守的约定以下五条约束来自 提示词 的 Key Points是让 AI 调用稳定成功的关键始终以原生对象传参data、query、filter必须是对象/数组结构不要传字符串化stringified的 JSON。实现侧注册表在执行前会用coerceJsonFields做一次宽松的类型纠正再用 Zod 严格校验见 registry.ts传字符串化 JSON 极易在strictObject校验处失败。只管理元数据不处理内容files工具负责文件记录与元数据二进制上传不在其职责范围真正的上传走 Directus Files API/界面。遵守权限所有操作在 FilesService 内部执行会基于当前accountability做访问校验如importOne中的validateAccess要求create权限Agent 权限不会越过用户权限。数组参数keys和tags必须为数组形式。性能大文件会被自动流式处理但导入/读取超大文件仍可能影响整体性能应限制导入并发与单次查询量。从源码看整体调用链一次 files 调用发生了什么把上面的信息串起来一次完整调用在 Directus 中经过的链路为可对照 工具实现、registry.ts、FilesService 阅读AgentMCP/聊天等场景通过根工具execute以{ name: files, input: { action, query/keys/data } }发起调用MountedToolRegistry.execute按名找到工具先执行validateSchema.safeParse做 Zod 校验同时受allowDeletes、isToolCallApproved门控见 registry.ts进入files.handler实例化携带当前用户上下文的FilesService依据action分流到readMany/readByQuery/updateBatch/updateMany/updateByQuery/deleteMany/importOne返回{ type: text, data }若数据为单条且配置了PUBLIC_URL注册表还会通过工具的endpoint为其拼接管理后台详情页 URL#addUrl与buildURL见 registry.ts 与 工具实现方便用户直接跳转到后台核对记录。测试覆盖与验证想要验证你对files行为的理解可直接运行仓库中已有的单元测试files 工具测试 使用 vitest 对FilesService的 mock覆盖了四类关键断言read by keys验证readkeys会以(keys, {})调用readManyupdate 两种形态keys 对象 data →updateMany数组 data →updateBatchdeletedelete keys →deleteMany(keys)并返回 keysSchema 可接受性对FilesValidateSchema.safeParse分别验证对象 data、数组 data 两种更新负载均通过校验非法动作action: invalid会抛出Invalid action.异常工具配置工具名称为files、非 admin 工具、description 与 input/validate schema 均已定义。在本地开发调试时可以vitest run api/src/ai/tools/files/index.test.ts单独执行该测试文件作为理解工具行为与回归验证的入口。总结files工具的价值在于把 Directus 强大的文件资产管理能力封装成一个语义清晰、参数校验严格的 AI 函数式接口对 Agent 而言它是一份自带 Zod 契约的「元数据操作说明书」对人类开发者而言它是通往 FilesService 数据管线的桥梁。掌握read/update/delete/import四种动作的语义边界、记住「数组参数、原生对象、元数据优先」三条铁律再结合 Directus 的权限与 MIME 白名单机制你就可以在聊天、MCP 或自定义 Agent 中安全地搭建素材检索、资产清洗、远程取图入库等自动化工作流。【免费下载链接】directusThe flexible backend for all your projects Turn your DB into a headless CMS, admin panels, or apps with a custom UI, instant APIs, auth more.项目地址: https://gitcode.com/GitHub_Trending/di/directus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
