Yao Assistant Models 完全指南：为每个 Agent 定义命名空间隔离的数据模型

Agent 框架后端低代码RAG【免费下载链接】yao✨ All your agents and workspaces in one place, on every device you own. Track tasks on a board, accessible from desktop, mobile, browser, or API. Self-hosted.项目地址https://gitcode.com/gh_mirrors/ya/yao点击查看免费下载导读在 Yao 的 Agent 体系中每个 Assistant助手都可以在自身的models/目录下定义一套完全独立命名的数据模型模型会自动以agents.assistant-id.前缀注册并使用agents_assistant-id_前缀的独立数据库表从而做到一个助手一套数据、互不干扰。本文以 agent/docs/models.md 为核心结合仓库源码model/model.go、model/migrate.go讲解模型目录结构、标准模型定义语法、命名空间与表名推导规则、在 Hooks/MCP/Scripts 中的三种调用方式以及自动迁移机制与yao migrate命令的完整用法。读完本文你将能够为任意 Yao Assistant 定义带隔离表的数据模型并通过模型进程models.model-id.*在助手逻辑中完成增删改查。目录结构模型放在哪里Yao Assistant 的模型遵循随助手打包的约定在应用根目录的assistants/目录下每个助手是一个独立的子目录含package.yao清单文件而模型统一放在该助手目录下的models/子目录中assistants/ └── my-assistant/ ├── package.yao └── models/ ├── order.mod.yao # → agents.my-assistant.order ├── item.mod.yao # → agents.my-assistant.item └── nested/ └── log.mod.yao # → agents.my-assistant.nested.log几个关键约定文件扩展名模型文件支持*.mod.yao、*.mod.json、*.mod.jsonc三种格式见 model/model.go 中的扩展名列表mod.yao是主推格式。嵌套目录models/下的子目录会被拍平为点号路径。models/nested/log.mod.yao的模型 ID 是agents.my-assistant.nested.log/替换为.。模型 ID 推导模型 ID agents. 助手 ID . 相对models/的路径去除扩展名。例如assistants/my-assistant/models/order.mod.yao→agents.my-assistant.order。从源码实现看model/model.go 的loadAssistantModels加载器会先确认目录中存在package.yao否则跳过该目录再用application.App.Walk递归扫描models/下的所有模型文件并通过processedAssistants映射做去重避免同一助手被重复加载。模型定义标准 Yao Model 语法助手模型使用标准 Yao 模型定义与全局模型语法一致唯一的差异是表名会被自动加前缀。以下是一个订单模型models/order.mod.yao的完整示例{ name: Order, label: Order Record, description: Customer orders, table: { name: order, comment: Order records }, columns: [ { name: id, type: ID, label: ID, primary: true }, { name: order_no, type: string, label: Order Number, length: 100, nullable: false, unique: true, index: true }, { name: customer_id, type: string, label: Customer ID, length: 255, nullable: false, index: true }, { name: total_amount, type: decimal, label: Total Amount, precision: 15, scale: 2, nullable: false }, { name: status, type: enum, label: Status, option: [pending, confirmed, shipped, completed, cancelled], default: pending, nullable: false, index: true }, { name: metadata, type: json, label: Metadata, nullable: true } ], relations: { items: { type: hasMany, model: item, key: order_id, foreign: id } }, indexes: [ { name: idx_customer_status, columns: [customer_id, status], type: index } ], option: { timestamps: true, soft_deletes: true } }结构解析name/label/description模型名、展示名与说明其中name用于关系引用见下文 Relations 的model: item。table指定物理表名name与表注释comment。助手模型无需关心前缀加载时自动拼接。columns字段定义数组支持primary、unique、index、default、length、precision、scale、nullable等修饰。relations模型间关系声明。indexes复合索引可指定type如index/unique与多列组合。上例中的idx_customer_status即customer_id status联合索引。option模型级行为开关timestamps自动维护created_at/updated_atsoft_deletes启用软删除。仓库中内置的全局模型如 yao/models/agent/assistant.mod.yao使用了完全相同的结构columns中assistant_id设置了unique: true与index: trueconnector使用length: 200与nullable: false——可作为编写助手模型时的参照范本。命名空间与表名规则如何实现隔离助手模型与全局模型的本质区别在于命名空间namespace助手模型一律挂在agents.命名空间下且表名统一加agents_assistant-id_前缀。Assistant IDModel FileModel IDTable Nameexpensemodels/order.mod.yaoagents.expense.orderagents_expense_ordertests.demomodels/user.mod.yaoagents.tests.demo.useragents_tests_demo_user推导规则见 model/model.go 与 model/model.go模型 IDagents.assistant-id.模型相对路径。助手 ID 中的/已被替换为.支持嵌套助手如tests.demo。表名先计算前缀agents_ 助手 ID.全部替换为__再拼上模型文件中声明的table.name。expense助手的前缀是agents_expense_表名即为agents_expense_order。幂等去重加载器会先剥离可能已存在的agents_mcpload_/ 本助手前缀再重新拼接model/model.go避免重复加前缀。这样的隔离带来的直接收益不同助手可以使用同名的模型文件与表名例如两个助手都定义models/user.mod.yao物理表互不冲突进程命名互不覆盖。从源码结构可以推断这一机制与全局模型models/*.mod.yao并行存在全局模型使用share.ID(root, file)推导 ID见 model/model.go而助手模型强制进入agents.命名空间二者在 agent/search/DESIGN.md 中被明确区分为Global models与Assistant-specific models。使用模型三种调用场景模型注册后即获得一套models.model-id.action形式的模型进程Process。进程的命名规则与全局模型一致——在 widgets/form/action.go 中可以看到表单组件正是通过models.%s.Find/Save/Create/Update/Delete绑定模型动作的。助手模型同样适用只需把model-id换成完整的agents.assistant-id.model。在 Hooks 中使用Hooks 是助手处理消息流的入口如Createhook可以直接查询助手自己的模型import { Process } from yao/runtime; function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create { // Query assistants own model const orders Process(models.agents.my-assistant.order.Paginate, { wheres: [{ column: status, value: pending }], limit: 10, }); return { messages }; }在 MCP Tools 中使用将模型动作直接暴露为 MCP 工具transport: process让 LLM 通过工具调用读写数据{ transport: process, tools: { list_orders: models.agents.my-assistant.order.Paginate, get_order: models.agents.my-assistant.order.Find, create_order: models.agents.my-assistant.order.Create, update_order: models.agents.my-assistant.order.Update } }在 Scripts 中使用助手自带的 TypeScript 脚本src/目录同样通过Process调用模型适合封装业务逻辑src/orders.tsimport { Process } from yao/runtime; export function ListPending(): any[] { return Process(models.agents.my-assistant.order.Get, { wheres: [{ column: status, value: pending }], orders: [{ column: created_at, option: desc }], }); } export function CreateOrder(data: any): any { return Process(models.agents.my-assistant.order.Create, data); } export function UpdateStatus(id: number, status: string): any { return Process(models.agents.my-assistant.order.Update, id, { status }); }三种场景的定位差异Hooks 适合在消息生命周期内做数据联动MCP 工具面向 LLM 的自主调用Scripts 则用于沉淀可复用的业务函数三者可以组合使用例如 Script 封装逻辑、MCP 暴露给模型。列类型Column Types助手模型支持与全局模型一致的完整列类型体系TypeDescriptionOptionsIDAuto-increment primary keyprimary: truestringVARCHARlength(default: 255)textTEXT-integerINT-bigIntegerBIGINT-floatFLOATprecision,scaledecimalDECIMALprecision,scalebooleanBOOLEAN-dateDATE-datetimeDATETIME-timestampTIMESTAMP-jsonJSON/JSONB-enumENUMoption: [...]使用建议主键一律用ID类型并声明primary: true需要精确金额计算时优先decimal并显式声明precision/scale上例订单金额precision: 15, scale: 2即 15 位有效数字、2 位小数json列适合存放元数据等半结构化内容上例的metadata。列选项Column Options每个列都可以叠加以下选项OptionTypeDescriptionnullablebooleanAllow NULL valuesdefaultanyDefault valueuniquebooleanUnique constraintindexbooleanCreate indexprimarybooleanPrimary keylengthintegerString lengthprecisionintegerDecimal precisionscaleintegerDecimal scalecommentstringColumn comment注意组合语义unique与index可同时为true订单号order_no即如此——既唯一又建索引加速按单号查询default对enum列特别有用状态列默认pending。comment会写入数据库列注释建议每个列都补上以提升可维护性。关系Relations关系在relations键下声明用于在查询时关联其他模型{ relations: { items: { type: hasMany, model: item, key: order_id, foreign: id }, customer: { type: hasOne, model: customer, key: id, foreign: customer_id } } }TypeDescriptionhasOneOne-to-one relationshiphasManyOne-to-many relationshiphasOneThroughHas one through intermediatehasManyThroughHas many through intermediate字段语义model指向被关联模型此处用name而非完整模型 ID 引用如itemkey是当前模型用于关联的字段foreign是被关联模型的对应字段。上例中items关系即一个订单有多条明细明细表以order_id关联订单的idcustomer关系即一个订单对应一个客户以本表customer_id关联客户表id。hasOneThrough/hasManyThrough则用于跨越中间模型的间接关系如通过中间表关联第三张表。模型选项Model Options模型级行为通过option键开启{ option: { timestamps: true, soft_deletes: true, permission: true } }OptionDescriptiontimestampsAddcreated_at,updated_atcolumnssoft_deletesAdddeleted_atfor soft deletepermissionEnable permission checkstimestamps会为表自动追加created_at/updated_at两列并由框架维护这也是脚本示例中按created_at排序的前提soft_deletes追加deleted_at使Delete动作变为逻辑删除、Destroy才物理删除permission开启模型级权限校验校验逻辑由 Yao 的模型 DSL 管理器执行详见 dsl/model/model.go。进程参考Process Reference模型注册后自动暴露的常用进程如下ProcessDescriptionArgumentsFindGet by IDid,query?GetGet recordsqueryPaginatePaginated listquery,page,pagesizeCreateCreate recorddataUpdateUpdate recordid,dataSaveCreate or updatedataDeleteDelete recordidDestroyHard deleteidInsertBatch insertcolumns,rowsUpdateWhereBatch updatequery,dataDeleteWhereBatch deletequery完整进程名形如models.agents.my-assistant.order.Paginate。query参数支持wheres条件数组如[{ column: status, value: pending }]、orders排序如[{ column: created_at, option: desc }]与limit条数上限Get返回数组、Find返回单条记录。注意Delete软删除与Destroy物理删除的区别取决于模型是否开启soft_deletes。迁移机制启动自动建表与手动同步启动时的自动迁移模型加载与建表发生在 Yao 启动阶段model/model.go 的Load流程加载内置系统模型如__yao.agent.assistant对应 yao/models/agent/assistant.mod.yao加载应用根目录models/下的全局模型调用loadAssistantModels加载所有助手的models/模型此时仅解析、不建表将系统模型与助手模型合并统一执行批量迁移最后加载数据库中的模型忽略错误。自动迁移的具体行为见 model/migrate.go 的BatchMigrate只建缺失表先通过schema.Use(default).Tables()一次性查出全部已有表再对比模型表名仅对不存在的表执行CreateTable()避免对已存在表重复操作。添加新列对已存在的表迁移会补齐新增的列。创建索引包括列级index/unique与indexes中声明的复合索引。不会删列迁移是安全的已存在的列不会被删除防止误删数据。BatchMigrate通过在YAO_ENVdevelopment时输出→ Creating N tables.../✓ table (duration)的彩色进度日志方便开发阶段观察建表情况model/migrate.go其幂等性由 model/migrate_test.go 中的BatchMigrateIdempotent用例验证。手动强制同步当模型结构变更需要强制重建时使用yao migrate命令详见 cmd/migrate.go 与 cmd/README.md# 迁移所有模型 yao migrate # 迁移指定模型 yao migrate -n user # 生产模式强制迁移 yao migrate --force # 重置删表重建 yao migrate --reset # Warning: drops and recreates tablesFlagShortDescription--name-nSpecific model name to migrate--forceForce migrate in production mode--resetDrop tables before migration注意事项生产模式config.Conf.Mode production下默认禁止迁移必须显式加--forcecmd/migrate.go--reset会先删表再重建会清空数据仅应在开发/测试环境使用。完整示例带模型与 MCP 工具的库存助手把以上知识串起来构建一个完整的库存助手Inventory Assistant它拥有自己的product模型、暴露查询与更新类 MCP 工具并通过脚本封装库存更新逻辑。assistants/inventory/package.yao{ name: Inventory Assistant, connector: gpt-4o, mcp: { servers: [{ server_id: inventory }] } }assistants/inventory/models/product.mod.yao{ name: Product, table: { name: product }, columns: [ { name: id, type: ID, primary: true }, { name: sku, type: string, length: 50, unique: true }, { name: name, type: string, length: 200 }, { name: quantity, type: integer, default: 0 }, { name: price, type: decimal, precision: 10, scale: 2 } ], option: { timestamps: true } }这个模型最终会注册为agents.inventory.product物理表为agents_inventory_product。assistants/inventory/mcps/inventory.mcp.yao{ label: Inventory, transport: process, tools: { list_products: models.agents.inventory.product.Paginate, get_product: models.agents.inventory.product.Find, update_stock: agents.inventory.stock.Update } }注意update_stock没有直接绑定模型动作而是指向助手脚本进程agents.inventory.stock.Update脚本进程的命名规则为agents.assistantID.scriptID见 agent/assistant/scripts.go从而在工具中嵌入业务校验。assistants/inventory/src/stock.tsimport { Process } from yao/runtime; export function Update(args: { sku: string; quantity: number }): any { const product Process(models.agents.inventory.product.Get, { wheres: [{ column: sku, value: args.sku }], limit: 1, }); if (!product || product.length 0) { throw new Error(Product not found: ${args.sku}); } return Process(models.agents.inventory.product.Update, product[0].id, { quantity: args.quantity, }); }流程串联LLM 调用 MCP 工具update_stock→ 触发脚本进程 → 脚本先按sku查询产品Getwhereslimit: 1找不到即抛错找到则以主键id调用Update更新库存。这展示了模型做存储、脚本做逻辑、MCP 做暴露的典型分层。小结与最佳实践隔离优先任何需要持久化的助手私有数据都应放在助手自己的models/目录下利用agents.命名空间与agents_*_表前缀天然隔离避免与全局模型和其他助手冲突。显式声明约束为高频查询字段声明index/unique金额用decimal明确precision/scale半结构化数据用json列。善用关系跨模型查询优先通过relations声明hasOne/hasMany/hasOneThrough/hasManyThrough保持数据规范化。迁移安全日常开发依赖启动自动迁移只增不减结构大改需要重建时在非生产环境使用yao migrate --reset生产环境务必确认数据备份后再--force。分层调用Hooks 内联查询适合轻量联动Scripts 封装复用逻辑MCP 工具面向 LLM 自主调用三者结合可获得最大的灵活性与可维护性。赞分享Agent 框架后端低代码RAG【免费下载链接】yao✨ All your agents and workspaces in one place, on every device you own. Track tasks on a board, accessible from desktop, mobile, browser, or API. Self-hosted.项目地址https://gitcode.com/gh_mirrors/ya/yao点击查看免费下载相关推荐Resque命名空间隔离多环境数据分离方案Resque命名空间隔离多环境数据分离方案 你是否曾在开发Resque应用时遇到测试环境任务污染生产队列的问题或者在多租户系统中担心不同用户的任务数据相互干任务调度消息队列后端iSH命名空间进程隔离与资源命名空间iSH命名空间进程隔离与资源命名空间 在iOS设备上运行完整的Linux shell环境iSH项目通过用户态x86模拟和系统调用转换实现了这一壮举。作为核心操作系统虚拟化CLISyft集成测试数据隔离使用命名空间与隔离技术Syft集成测试数据隔离使用命名空间与隔离技术 测试数据隔离的必要性 在SyftSoftware Bill of Materials生成工具的开发过程中供应链安全开发工具合规审计开源治理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考