Directus relations 关系工具实战通过 AI Agent 在集合间创建与管理 M2O/O2M/M2M/M2A 数据关系【免费下载链接】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/directusDirectus 的 AI 工具系统为智能体提供了relations工具用于在数据集合Collections之间建立和管理多种类型的关系——多对一M2O、一对多O2M、多对多M2M与多态的多对任意M2A覆盖从基础外键到文件关系、多语言翻译的完整建模场景。本文以 relations 工具的系统提示词 为主体骨架结合其 TypeScript 实现、共享关系 Schema 与 单元测试讲解每一个关系类型的完整建模工作流、JSON 调用载荷、schema/meta 选项语义与底层存储机制读完即可让 AI Agent 或开发者直接照抄式地完成关系建模。工具定位与能力概览relations是 Directus API 中 AI/LLM Agent 可调用的管理类工具之一其定义位于 api/src/ai/tools/relations/index.ts。从实现上看它有以下几个关键特征管理权限限定admin: true只有管理员上下文测试中的accountability为{ user: test-user, admin: true }才能执行参见 index.test.ts指令即提示词工具的instructions字段通过requireText()直接加载同目录下的prompt.md也就是说本文讲解的文档就是模型每次调用relations工具时被注入的使用说明书只读优化readOnly: (input) input.action readAgent 平台据此可在只读场景下安全放行查询类调用后端对接handler 内统一实例化RelationsService见 api/src/services/relations.ts执行真正的数据库操作。工具支持四种操作actionsAction用途需要的前置参数create在集合间建立关系collection、field可选回退用data.field、dataread查看已存在的关系可选collection与field粒度见下文update修改关系设置collection、field、datadelete移除关系collection、field其中update只能修改两部分内容对应 prompt 原文外键行为schema.on_delete/schema.on_update以及关系元数据meta其他字段不可变。请求参数与返回结构输入参数在 schema.ts 中被建模为RelationItemInputSchemacollection关系所在集合名多端集合field关系所在字段名related_collection关联的目标集合可为nullM2A 的多态关系即此情况schema底层数据库外键描述metaDirectus 关系元数据界面联动、排序等。read具备三级粒度由 index.ts 实现返回数据也相应变化仅给collectionfield→ 读取并返回这一条关系的详情readOne(collection, field)只给collection→ 读取该集合下全部关系readAll(collection)什么都不给→ 读取整个实例的所有关系readAll()。create与update成功后都会回读一次最新关系数据作为响应delete成功后返回被删除关系的{ collection, field }标识。所有返回值统一包装为{ type: text, data: ... }。建模前置条件字段先行Prompt 的开篇就列出几条硬性前置条件违反其中任一条都会导致建模失败集合必须已存在——请先调用collections工具创建目标集合字段必须已用正确的类型创建——请先调用fields工具添加关系字段M2M / M2A 必须存在中间集合junction collection系统用户字段user_created/user_updated需要与directus_users建立关系具体配置见collections工具的system_fields章节。关系类型与字段定义之间存在严格的类型 special约定这在 fields 工具提示词的关系字段章节 中有 CRITICAL 级别的强调关系类型字段typemeta.special界面 interface说明M2Ouuid[m2o]select-dropdown-m2o存外键的真实字段O2Malias[o2m]list-o2m反向虚拟字段随 M2O 联动M2Malias[m2m]list-m2m需要 junction 集合M2Aalias[m2a]list-m2a多态需要 junction 集合单文件uuid[file]file/file-image指向directus_files多文件alias[files]files经 M2M 指向文件库翻译alias[translations]translations特殊的 M2M最小化创建示例基础 M2O 关系Prompt 给出的最精简调用如下语义是在articles集合上把author字段指向directus_users并配置作者被删除时外键置空{ action: create, collection: articles, field: author, related_collection: directus_users, meta: { sort_field: null }, schema: { on_delete: SET NULL } }这个结构会经 zod 的RelationItemValidateCreateSchemaschema.ts校验要求collection、field、related_collection必填schema只需是外键描述的部分字段因为建表后外键已物理存在通常只需声明on_delete/on_update覆盖meta为关系元数据的任意子集。而RelationItemOutputSchema则要求返回至少带齐collection与field。对应的单元测试index.test.ts验证了 create 的最小载荷{ collection, field, related_collection }会被透传至RelationsService.createOne()随后用readOne()回读。四种核心关系类型的完整工作流M2O多对一多端集合的多个条目共同指向另一端的一个条目例如许多篇文章 → 一位作者。完整流程分两步在多端集合加 M2O 字段——用fields工具type: uuid、special: [m2o]、interface: select-dropdown-m2o。字段的schema中应声明外键来源foreign_key_table/foreign_key_column完整示例见 fields 提示词的 M2O Field Example创建关系{ action: create, collection: articles, field: author, data: { collection: articles, field: author, related_collection: directus_users, schema: { on_delete: SET NULL } } }O2M一对多一端的一个条目对应多端的许多条目例如一位作者 → 许多篇文章。O2M 不会在数据库新增任何真实列它是一个挂在一端的虚拟别名字段必须复用 M2O 已建立的外键。完整流程在一端集合加 O2M 虚拟字段——用fields工具type: alias、special: [o2m]、interface: list-o2m因是虚拟字段schema为null参考 fields 提示词的 O2M Field Example创建关系在多端articles针对已有 M2O 字段author建立关系并用meta.one_field指出一端authors上的反向字段名articles{ action: create, collection: articles, field: author, data: { collection: articles, field: author, related_collection: authors, meta: { one_field: articles, sort_field: null }, schema: { on_delete: SET NULL } } }M2M多对多两侧集合都能关联对方多个条目例如文章 ↔ 标签。它需要一张junction中间集合存两条外键。完整流程四步创建 junction 集合——用collections工具创建article_tags主键为 UUID两侧加别名字段——在articles与tags上用fields工具加type: alias、special: [m2m]、interface: list-m2m的虚拟字段参考 fields 提示词的 M2M Field Example加 junction 字段——在article_tags上添加article_idUUID、tag_idUUID以及可选的排序字段sortinteger创建双向关系两个方向都建on_delete用CASCADE删除任一侧条目时同步清理 junction 行// First relation文章侧 { action: create, collection: article_tags, field: article_id, data: { collection: article_tags, field: article_id, related_collection: articles, meta: { one_field: tags, junction_field: tag_id, sort_field: sort }, schema: {on_delete: CASCADE} } } // Second relation标签侧 { action: create, collection: article_tags, field: tag_id, data: { collection: article_tags, field: tag_id, related_collection: tags, meta: { one_field: articles, junction_field: article_id }, schema: {on_delete: CASCADE} } }注意两条关系meta的对称关系第一条的one_field: tags对应articles.tags虚拟字段junction_field: tag_id指出另一条外键第二条则是tags.articles与junction_field: article_id。M2A多对任意多态一端的一个条目可以关联多个不同集合的条目。典型场景是页面构建器pages的blocks字段可以同时容纳block_hero、block_text、block_gallery等多种区块。完整流程五步创建各区块集合——用collections工具分别建block_hero、block_text、block_gallery均用 UUID 主键并各自定义字段创建 junction 集合——建page_blocks建议设为隐藏集合UUID 主键加 M2A 虚拟字段——在pages上加type: alias、special: [m2a]、interface: list-m2a参考 fields 提示词的 M2A Field Example加 junction 字段——在page_blocks上添加itemstring、collectionstring、页面引用字段与sortinteger其中item存被关联条目的主键、collection存该条目所属集合名创建两条关系——多态侧related_collection为null并用meta.one_allowed_collections声明白名单、meta.one_collection_field声明存放集合名的列页面侧按普通 O2M 处理// 多态关系item 关系 { action: create, collection: page_blocks, field: item, data: { collection: page_blocks, field: item, related_collection: null, meta: { one_allowed_collections: [block_hero, block_text, block_gallery], one_collection_field: collection, junction_field: page_id } } } // 页面关系 { action: create, collection: page_blocks, field: page_id, data: { collection: page_blocks, field: page_id, related_collection: pages, meta: { one_field: blocks, junction_field: item, sort_field: sort }, schema: {on_delete: CASCADE} } }实操提示两条关系meta.junction_field必须互相指向对方关系所在的 junction 字段item↔page_id且字段名要与第 4 步实际创建的 junction 字段保持一致。文件关系与多语言翻译单文件M2O在集合上加type: uuid、special: [file]、interface: file的字段完整字段示例见 fields 提示词的 File Field Example再创建指向directus_files的关系{ action: create, collection: articles, field: cover_image, data: { collection: articles, field: cover_image, related_collection: directus_files, schema: { on_delete: SET NULL } } }多文件Files本质是 M2M要支持一篇文章多张配图需要走一次完整的 M2M 建模见 fields 提示词的 Files Field Example创建 junction 集合如article_imagesUUID 主键在主集合加type: alias、special: [files]、interface: files的虚拟字段images在 junction 上加两个隐藏字段article_id与directus_files_id均 UUID建立两条 CASCADE 关系// Article relation { action: create, collection: article_images, field: article_id, data: { collection: article_images, field: article_id, related_collection: articles, meta: { one_field: images, junction_field: directus_files_id }, schema: {on_delete: CASCADE} } } // File relation { action: create, collection: article_images, field: directus_files_id, data: { collection: article_images, field: directus_files_id, related_collection: directus_files, meta: { junction_field: article_id }, schema: {on_delete: CASCADE} } }Translations多语言Translations 是与languages集合配合的特殊 M2M用于让条目的可翻译字段按语言分表存放。完整流程先确认languages集合存在可用schema工具检查创建翻译 junction 集合UUID 主键在主集合加type: alias、special: [translations]、interface: translations的字段——其options常配userLanguage: true默认跟随用户语言与defaultOpenSplitView: true默认开分栏编辑见 fields 提示词的 Translations Field Example之后的 junction 字段与关系配置完全遵循 M2M 模式将目标集合换为languages即可。Relation Settingsschema 与 meta 的全部可配项Prompt 中把可调参数分为数据库层 schema与应用层 meta两组它们与 schema.ts 中的RelationMetaSchema与ForeignKeySchema一一对应。Schema 选项外键约束选项取值行为默认场景on_deleteCASCADE删除关联条目时级联删除本端/中间记录M2M 的默认选择SET NULL删除时将该外键列置空M2O 的默认选择NO ACTION不做动作由数据库默认规则处理可阻止删除—RESTRICT只要存在关联条目就阻止删除—SET DEFAULT删除时回退为列的默认值—on_update与on_delete相同主键更新时的级联策略—在代码层面这些值被建模为FkActionEnum z.enum([NO ACTION, RESTRICT, CASCADE, SET NULL, SET DEFAULT])schema.ts也就是说非法取值在校验阶段就会直接报错不会进入数据库。Meta 选项Directus 关系元数据选项含义适用关系one_field关联集合一端上的反向虚拟字段名O2M / M2M / M2A 的一侧junction_fieldjunction 表中指向另一方向的那条外键字段M2M / M2A / Filessort_field启用手动排序通常指向 integer 字段O2M / M2M / M2A 等含列表的场景one_deselect_action取消关联时对另一端条目的处置nullify或deleteM2O / M2M 等one_allowed_collectionsM2A 允许关联的集合名数组M2Aone_collection_fieldM2A junction 中存放所属集合名的字段M2ARelationMetaSchema还保留了id、many_collection、many_field、one_collection、one_field等只读/系统字段与system标记这些由框架内部维护创建时通常不需要提供。底层机制RelationsService 与存储模型relations工具只是薄薄的一层翻译层真正落库的是 api/src/services/relations.ts 中的RelationsService。理解它有助于把握工具行为的边界双数据源模型关系由两层构成——数据库真实外键通过directus/schema的schemaInspector.foreignKeys()探测得到与directus_relations系统表里存储的关系元数据。RelationsService构造时会在directus_relations上实例化一个不带权限的ItemsServicerelations.ts并在读取时合并系统内置关系systemRelationRows来自directus/system-data缓存foreignKeys()结果会被写入localSchemaCache受CACHE_SCHEMA环境变量开关控制relations.ts——这就是为什么新建外键类结构后可能需要清理缓存才能被读到权限readAll()会先对directus_relations做read访问校验relations.ts在 AI 工具场景下由于admin: true管理员可直接通过。真实场景的组合建模模式Prompt 用几组组合拳示范了如何把上述基本类型拼成真实业务模型这些模式在 Agent 建模时可整体复用博客系统articlesM2Odirectus_usersauthor 作者articlesM2Mtags标签articlesM2Odirectus_filescover_image 封面articlesM2Mdirectus_filesgallery 相册articlesO2Mcomments评论commentsM2Odirectus_users评论作者电商productsM2McategoriesproductsM2ObrandsproductsO2MreviewsproductsM2Mdirectus_filesgalleryordersO2Morder_itemsorder_itemsM2OproductsordersM2Odirectus_userscustomerreviewsM2Odirectus_usersreviewer页面构建器pages上建 M2Ablocks字段junction 集合为page_blocks可关联集合block_hero、block_text、block_gallery。命名规范为了让关系和 API 输出可读且一致Prompt 给出了明确的命名约定junction 集合{单数}_{复数}或集合对例如product_categories、article_tagsjunction 字段用对应集合的单数形式例如product_id、category_id多端别名alias字段用复数形式例如tags、categories、imagesM2O 字段用单数形式例如author、brand。工具协同与测试验证relations工具从不孤立使用。Prompt 末尾的 Related Tools 明确了调用顺序依赖先用collections建集合与 junction再用fields添加关系字段最后才轮到relations建关系需要盘点整体结构时可交给schema工具其统一输出模型见 api/src/ai/tools/schema.ts。实现层面的行为均有测试兜底api/src/ai/tools/relations/index.test.tscreate验证RelationsService以{ schema, accountability }实例化、createOne后回读结果read验证collection field走readOne、仅collection走readAll且不会误触readOneupdate验证updateOne(collection, field, data)的透传delete验证deleteOne(collection, field)并回传{ collection, field }错误处理非法 action 会抛出Invalid action.工具配置确认工具名为relations、admin为true、description/input/validate 三件套齐全。小结relations工具把 Directus 的关系建模能力M2O/O2M/M2M/M2A、文件与翻译关系、外键约束与排序元数据封装成了可被 LLM 稳定调用的四类动作。掌握它的关键在于记住三层心智模型先建集合、再建字段type special 决定关系语义、最后建关系schema 管约束、meta 管界面行为。在管理员权限与 zod 严格校验的双重保障下AI 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），仅供参考