Mastra Editor 深度解析mastra/editor 的存储、版本化与运行时水合机制【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/editor是 Mastra Studio 编辑体验背后的数据与 Provider 层统一管理代理agent、提示词块prompt、评分器scorer、MCP 客户端/服务器、工作区workspace、技能skill与收藏favorites并打通「代码源」与「数据库源」两种存储模式。读完本文你将掌握如何把MastraEditor接入 Mastra 实例、如何通过editor配置声明哪些代理字段允许 Studio 覆盖、如何理解 draft/published 版本解析与缓存语义以及如何利用处理器图、工具 Provider 与工作区/技能域构建可序列化的 Agent 配置体系。mastra/editor 在 Mastra 生态中的定位从仓库中的 包 README 可以确认其官方定位The data and provider layer behind Mastra Studio editing experiences. It manages agents, prompts, scorers, MCP servers, workspaces, skills, and favorites across code and storage sources.也就是说mastra/editor不是 UI 组件库而是承载「存储 版本化 水合hydration」的运行时层UI如 Studio/Playground通过它读写配置运行时通过它把存储的配置重新实例化为可执行的Agent、MCPServer、Workspace等对象。从 源码入口 可以看到它对外暴露了MastraEditor主类以及EditorAgentNamespace、EditorPromptNamespace、EditorScorerNamespace、EditorMCPServerNamespace、EditorWorkspaceNamespace、EditorSkillNamespace、EditorFavoritesNamespace等一组命名空间还有renderTemplate、evaluateRuleGroup、resolveInstructionBlocks三个可在外部复用的纯函数。安装与最小接入npm install mastra/editor最小接入方式是把编辑器实例交给Mastraimport { Mastra } from mastra/core/mastra; import { MastraEditor } from mastra/editor; export const mastra new Mastra({ editor: new MastraEditor(), });传入后编辑器会通过registerWithMastra()与Mastra共享 storage、logger 与运行时注册表源码见 index.ts。package.json中约定了 peer 依赖mastra/core 1.34.0-0 2.0.0-0mastra/mcp可选运行时要求 Node.js22.13.0。编辑器所有权模型code-defined 与 stored 配置如何共处用editor选项声明可编辑字段自 v0.11.0 起代码中定义的代理可以显式声明哪些字段允许 Studio 编辑其余字段保持代码值不变new Agent({ name: Weather Agent, model, editor: { instructions: true, tools: { description: true }, }, });编辑器只会对editor配置所「拥有」的字段应用存储覆盖被锁定的字段始终使用代码中的值单个代理传入editor: false则完全锁定MastraEditor提供source选项选择编辑体验source: code时自动接入FilesystemStore默认目录./mastra/editor/可用codePath覆盖把覆盖持久化为确定性的按代理 JSON 文件source: db默认则走项目已配置的存储后端。applyStoredOverrides 的合并边界v0.7.0 引入的applyStoredOverrides规定了合并的严格边界当某个 code-defined 代理存在存储配置时编辑器只把存储中的instructions和tools合并到代码值之上model、memory、workspace 等字段永不被覆盖因为它们可能包含 SDK 实例或动态函数无法安全序列化。代码原始值通过 WeakMap 保留存储覆盖被删除后即恢复。Studio 编辑指令不丢失 providerOptionsv0.14.2 修复了一个隐蔽问题当代码把指令定义为结构化系统消息例如带 Anthropic prompt-cache 断点时Studio 中编辑并发布指令曾会把它替换成纯字符串导致providerOptions静默丢失——此后每次请求都按未缓存输入付费。修复后 Studio 只拥有「措辞」发布文本会被重新包回代码定义的 message envelopeconst agent new Agent({ id: voice-agent, name: Voice Agent, instructions: { role: system, content: You are a helpful voice assistant., providerOptions: { anthropic: { cacheControl: { type: ephemeral } } }, }, model: anthropic/claude-sonnet-4-6, });该修复对既有发布覆盖是追溯生效的升级后自动套用代码 envelope无需迁移。指令完全委托给 Studioeditor: { instructions: true }的代理没有代码 envelope不受影响。指令委托 Studio 时的失败语义v0.14.0 起editor: { instructions: true }且 Studio 中尚无已发布版本从未供给、只有草稿、被删除、发布版本无指令或存储加载失败时解析或生成代理会抛出清晰错误而不再像以前那样静默以空 system prompt 运行// Agent definition — Studio owns the instructions: export const agent new Agent({ id: support-agent, editor: { instructions: true }, model: openai/gpt-4o, }); // Throws until a version is published in Studio: const agent client.getAgent(support-agent, { status: published }); await agent.generate(hi); // Use status: draft to run against the latest draft instead, without publishing: const draftAgent client.getAgent(support-agent, { status: draft }); await draftAgent.generate(hi);命名空间架构与缓存语义v0.3.0 将MastraEditor重构为命名空间模式v0.5.0 起把四个版本化域统一到CrudEditorNamespace基类之上源码见 namespaces/base.ts命名空间职责editor.agent存储代理的 CRUD、版本化、克隆与覆盖editor.prompt可复用提示词块prompt block的 CRUDeditor.scorerLLM-as-judge 与预设评分器定义的 CRUDeditor.mcp/editor.mcpServerMCP 客户端 / 服务器配置的 CRUD 与水合editor.workspace工作区配置 CRUD 与水合editor.skill技能定义 CRUD 与发布editor.favorites代理/技能的收藏管理CrudEditorNamespace内置了按实体 id 的缓存getById的默认版本请求走缓存而带versionId、versionNumber或status的版本请求直接穿透到存储。v0.14.6-alpha.1 修复了一个与此相关的边界 bug此前版本请求检测用真值判断导致getById(id, { versionNumber: 0 })被当作默认请求——在热缓存时从缓存返回默认实体、冷缓存时返回null。修复后在共享的CrudEditorNamespace与代理适配器中改用显式! undefined判断任何显式versionNumber包括0都会一致地绕过缓存直达版本解析。缓存失效方面所有变更操作create/update/delete会自动使受影响实体的缓存失效v0.9.0 起clearCache(id)即使在实体未被缓存时也会调用onCacheEvict(id)让子类可以清理绕过编辑器缓存的版本级运行时注册表v0.5.0 起四个版本化域agents、scorers、prompt-blocks、mcp-clients在版本激活、恢复、删除后都会清缓存。存储层db 源、代码源与来源控制FilesystemStoreGit 友好的编辑器存储v0.7.0 引入FilesystemStore把代理配置、提示词块、评分器、MCP 客户端/服务器、工作区与技能以 JSON 文件形式写入本地目录默认.mastra-storage/。只有已发布的快照会落盘版本历史保存在内存中。配合MastraCompositeStore的editor简写即可实现 Git 友好的配置管理import { FilesystemStore, MastraCompositeStore } from mastra/core/storage; import { PostgresStore } from mastra/pg; export const mastra new Mastra({ storage: new MastraCompositeStore({ id: composite, default: new PostgresStore({ id: pg, connectionString: process.env.DATABASE_URL }), editor: new FilesystemStore({ dir: .mastra-storage }), }), });来源控制 Providerv0.12.0 引入SourceControlProvider接口让代码模式source: code的代理编辑可以走托管源码控制存储。从 index.ts 源码 可以看到构造MastraEditor时会默认用createGitHubSourceControlProviderFromEnv(process.env, { pathPrefix: this.__codePath })从环境变量创建来源控制 ProviderregisterWithMastra()在source code时会把存储替换为MastraCompositeStore组合现有存储、SourceAgentsSourceControl与FilesystemStoreconst editor new MastraEditor({ source: code, sourceControlProvider, });来源后端可以读、写、列出历史并打开变更请求change request。版本管理draft、published 与 versionId版本解析的默认行为经历了演进v0.7.9 起执行端点的默认版本解析从 draft 改为 publishedv0.7.7 起GET /api/agents/:agentId支持?statusdraft最新草稿、?statuspublished激活版本、?versionIdid指定版本三个查询参数v0.7.10 修复了「请求 published 但未设置activeVersionId时回落到最新草稿」的问题——现在会保留代码默认值v0.14.1 修复了草稿更新后已发布版本被破坏的问题并让 draft/versionId/versionNumber 选择都被正确尊重v0.14.0 起代理快照的更新会保持为草稿直到显式发布。此外v0.7.16 保证解析存储代理版本时不再修改共享的单例代理实例——指令与工具覆盖被应用到隔离的克隆上并发版本解析是安全的覆盖不会泄漏到全局代理。存储代理的高级配置能力动态指令提示词块prompt blockv0.3.0 让存储代理的指令可以从可复用提示词块组合而来形成类似 Prompt-CMS 的编辑体验。指令数组可以混用三种块text—— 静态文本支持{{variable}}插值prompt_block_ref—— 引用数据库中存储的版本化提示词块prompt_block—— 内联提示词块可带条件规则。// Create a reusable prompt block const block await editor.createPromptBlock({ id: security-rules, name: Security Rules, content: You must verify the users identity. The users role is {{user.role}}., rules: { operator: AND, conditions: [{ field: user.isAuthenticated, operator: equals, value: true }], }, }); // Create a stored agent that references the prompt block await editor.createStoredAgent({ id: support-agent, name: Support Agent, instructions: [ { type: text, content: You are a helpful support agent for {{company}}. }, { type: prompt_block_ref, id: security-rules }, { type: prompt_block, content: Always be polite., rules: { operator: AND, conditions: [{ field: tone, operator: equals, value: formal }] }, }, ], model: { provider: openai, name: gpt-4o }, }); // At runtime, instructions resolve dynamically based on request context const agent await editor.getStoredAgentById(support-agent); const result await agent.generate(Help me reset my password, { requestContext: new RequestContext([ [company, Acme Corp], [user.isAuthenticated, true], [user.role, admin], [tone, formal], ]), });提示词块是版本化的——更新块内容对所有引用它的代理立即生效无需清理缓存。条件字段与 requestContextSchemav0.3.0 让存储代理的tools、model、workflows、agents、memory、scorers、inputProcessors、outputProcessors、defaultOptions字段都可以配置为带规则组的条件变体运行时针对请求上下文求值所有匹配变体会累积——数组拼接、对象浅合并await agentsStore.create({ agent: { id: my-agent, name: My Agent, instructions: You are a helpful assistant, model: { provider: openai, name: gpt-4 }, tools: [ { value: { basic-tool: {} } }, { value: { premium-tool: {} }, rules: { operator: AND, conditions: [{ field: tier, operator: equals, value: premium }], }, }, ], requestContextSchema: { type: object, properties: { tier: { type: string } }, }, }, });requestContextSchemaJSON Schema会被转换为 Zod schema 传给 Agent 构造器从而对请求上下文做校验。规则求值的核心函数evaluateRuleGroup与指令块解析函数resolveInstructionBlocks都作为独立导出暴露在 index.ts可被上层 UI 直接复用。观测记忆observational memoryv0.4.0 起存储代理支持观测记忆配置并在 v0.13.3 把 Agent Builder 代理的默认观测记忆模型从__GATEWAY_GOOGLE_MODEL__切换为__GATEWAY_OPENAI_MODEL_MINI__需要在这些环境设置OPENAI_API_KEY管理员仍可覆盖await editor.agent.create({ name: My Agent, memory: { observationalMemory: true, // enable with defaults options: { lastMessages: 40 }, }, }); // Or with custom configuration: await editor.agent.create({ name: My Agent, memory: { observationalMemory: { model: google/gemini-2.5-flash, scope: resource, // thread (per-conversation) or resource (shared across threads) shareTokenBudget: true, observation: { messageTokens: 50000 }, reflection: { observationTokens: 60000 }, }, options: { lastMessages: 40 }, }, });durable 存储代理v0.14.0 为存储代理新增durable选项使通过 Agents API 创建的代理无需部署代码即可获得持久化执行能力await mastraClient.createStoredAgent({ id: helper, name: Helper, instructions: You are a helpful assistant., model: { provider: openai, name: gpt-5 }, durable: true, });传入true使用默认值或传{ maxSteps, cleanupTimeoutMs }调优持久循环。Cache 与 pubsub 继承自服务器的Mastra实例——跨副本的持久化需要在那里配置分布式后端自动恢复仍通过代码中的recovery.durableAgents配置。metadatav0.8.0 为 code-defined 代理加入可选metadata传给new Agent({...})用agent.getMetadata()读取客户端可从现有/agents与/agents/:agentId响应过滤无需把数据编码进 id 或 name。metadata 支持与其他配置字段相同的DynamicArgument形式可基于请求上下文逐请求解析const tenantAgent new Agent({ id: tenant-agent, name: Tenant Agent, instructions: You help customers with tenant-specific tasks., model: openai/gpt-5, metadata: ({ requestContext }) ({ type: support, tenant: requestContext.get(tenant), }), }); await tenantAgent.getMetadata({ requestContext }); // { type: support, tenant: acme }通过editor.agent.clone()克隆运行时代理时若调用方未显式提供 metadata会继承源代理的 metadata。工具 ProviderOAuth 连接与多租户v1 ToolProvider 运行时v0.11.0 落地了 v1ToolProvider运行时、服务器路由、客户端 SDK 方法与编辑器接线。存储代理通过toolProviders配置在每次执行时绑定每个工具包toolkit的连接连接可以按作者per-author、跨组织共享shared或由调用方提供caller-supplied{ toolProviders: { composio: { connections: { gmail: [{ kind: author, toolkit: gmail, connectionId: auth_abc, scope: per-author }], }, tools: { GMAIL_FETCH_EMAILS: { toolkit: gmail }, }, }, }, }客户端 SDK 新增连接管理接口import { MastraClient } from mastra/client-js; const client new MastraClient({ baseUrl: … }); const composio client.toolProvider(composio); const { items } await composio.listConnections({ toolkit: gmail }); await composio.disconnectConnection(auth_abc);Provider 实现 vNext 表面listToolkitsVNext、listToolsVNext、resolveToolsVNext外加认证回路authorize、getAuthStatus、listConnections、disconnectConnection、listConnectionFields、health。Composio Provider 已按该表面重写旧目录方法保留为deprecated兼容垫片连接列表响应使用page/perPage分页与服务器其余表面一致。运行时还有两条错误隔离策略连接作用域无法从请求上下文解析时记录一次性警告并回退到共享桶多租户部署能及时发现身份接线未达运行时某个工具包返回的连接数超过其声明能力时记录并跳过该工具包而不影响同代理上的其他 Provider 与其他工具包。ComposioToolProvider 的多租户演进v0.13.7 起caller-supplied作用域的代理让 Composio 在每个租户的用户桶内选择已连接账户而非为所有调用者钉住一个共享账户ComposioToolProvider会转发defaultScope可在构造时一次性设置 Provider 级连接作用域。v0.14.0 进一步支持认证用户执行与确定性连接路由调用方绑定的连接精确路由到存储的对应已连接账户包括通过 Composio ACL 共享的账户。应用用户 id 与 Composio 用户 id 的映射通过userIdResolver完成import { MASTRA_USER_KEY } from mastra/server/auth; import { ComposioToolProvider } from mastra/editor/composio; const composio new ComposioToolProvider({ apiKey: process.env.COMPOSIO_API_KEY!, userIdResolver: ({ requestContext }) { const user requestContext?.getRaw(MASTRA_USER_KEY); if (!user || typeof user ! object || !(id in user) || typeof user.id ! string) return undefined; return user.id; }, });v0.14.0 还修复了 Composio 工具结果不校验的问题解析后的工具保留 Composio 提供的输出 schema真实 API 响应含 null 或多余字段通过而结构非法输出被拒绝而不是静默返回——这也让 Composio 工具可用于要求输出 schema 的 API如createStep(tool)。内置 Provider 与独立入口v0.4.0 起提供两个内置工具 Provider各自是独立入口点——只引入mastra/editor不会加载任何 Provider SDK 代码mastra/editor/composio—— 基于composio/core与composio/mastra支持工具包/工具发现与执行mastra/editor/arcade—— 基于arcadeai/arcadejs内置预置目录93 个工具包、工具发现与执行。import { MastraEditor } from mastra/editor; import { ComposioToolProvider } from mastra/editor/composio; import { ArcadeToolProvider } from mastra/editor/arcade; const editor new MastraEditor({ toolProviders: { composio: new ComposioToolProvider({ apiKey: ... }), arcade: new ArcadeToolProvider({ apiKey: ... }), }, });处理器 Provider 与处理器图v0.6.0 引入 Processor Provider——一套在存储代理上配置与水合处理器的系统。自定义处理器类型声明配置 schema、可用阶段phases与工厂方法然后组合成可序列化的处理器图支持顺序、并行与条件执行import { MastraEditor } from mastra/editor; // Built-in processors (token-limiter, unicode-normalizer, etc.) are registered automatically. // Only register custom providers for your own processors: const editor new MastraEditor({ processorProviders: { my-custom-filter: myCustomFilterProvider, }, });const agentConfig { inputProcessors: { steps: [ { type: step, step: { id: norm, providerId: unicode-normalizer, config: {}, enabledPhases: [processInput] }, }, { type: step, step: { id: limit, providerId: token-limiter, config: { limit: 4000 }, enabledPhases: [processInput, processOutputStream], }, }, ], }, };v0.14.6-alpha.1 加强了水合期校验处理器图水合现在会在实例化处理器前把每个存储步骤配置对照所选 Provider 的configSchema校验与文档化的ProcessorProvider契约一致。此前resolveStep()把原始存储配置直接传给createProcessor()畸形配置可能构造出有问题的处理器、到请求执行时才失败且 schema 的.default()/transform 输出被跳过。现在无效配置在水合时即抛出错误错误信息标明 Provider 与图步骤而校验后的配置含默认值与变换才会到达createProcessor()。工作区、技能与收藏工作区域v0.5.0 引入editor.workspace命名空间工作区配置的 CRUD以及hydrateSnapshotToWorkspace()把存储快照解析为运行时Workspace实例。v0.9.0 补充反向操作snapshotFromWorkspace()可把运行中的Workspace快照化以便持久化该方法是异步的会等待sandbox.getInfo()与filesystem.getInfo()让CompositeFilesystem这类异步 Provider 把挂载元数据保留在存储配置中const snapshot await editor.workspace.snapshotFromWorkspace(runtimeWorkspace); await editor.workspace.create({ id: my-workspace, ...snapshot });v0.13.5 新增工作区级 Provider 注册表WorkspaceProvider工厂把完整的Workspace实例作为一个单元构建而不必分别组合文件系统与沙箱 Provider存储代理可通过{ type: provider, provider: my-cloud, config: { ... } }引用编辑器在代理水合时调用注册的工厂import { MastraEditor } from mastra/editor; import { Workspace } from mastra/core/workspace; const editor new MastraEditor({ workspaces: { my-cloud: { id: my-cloud, name: My Cloud Workspace, createWorkspace: config new Workspace({ id: cloud-ws, name: Cloud WS, filesystem: new MyCloudFilesystem(config), sandbox: new MyCloudSandbox(config), }), }, }, }); // Stored agent workspace reference using the provider: // { type: provider, provider: my-cloud, config: { region: us-east-1 } }技能域与发布模型v0.5.0 为技能引入了文件系统原生的「草稿 → 发布」版本模型编辑表面实时文件系统与服务表面版本化 blob 存储分离。技能以文件系统树形式版本化配合基于 SHA-256 哈希的内容寻址BlobStore有InMemoryBlobStore、LibSQL/Postgres/MongoDB 实现以及面向 S3/S3 兼容存储的S3BlobStore可在MastraEditorConfig.blobStores注册 Provider。editor.skill.publish(skillId, source, skillPath)—— 把技能目录从文件系统快照进 blob 存储创建带树清单的新版本并设置activeVersionIdeditor.skill.update({ id, activeVersionId })—— 切换到历史版本无需重新发布发布技能会自动使引用它的缓存代理失效下次访问时以新版本重新水合。代理引用技能有三种解析策略strategy: latest—— 解析技能的激活版本尊重activeVersionId以便回滚pin: versionId—— 钉住特定版本不受后续发布影响strategy: live—— 直接从实时文件系统读取不走 blob 存储。import { MastraEditor } from mastra/editor; import { s3FilesystemProvider, s3BlobStoreProvider } from mastra/s3; import { e2bSandboxProvider } from mastra/e2b; const editor new MastraEditor({ filesystems: { s3: s3FilesystemProvider }, sandboxes: { e2b: e2bSandboxProvider }, blobStores: { s3: s3BlobStoreProvider }, }); // Create a skill and publish it const skill await editor.skill.create({ name: Code Review, description: Reviews code for best practices, instructions: Analyze the code and provide feedback..., }); await editor.skill.publish(skill.id, source, skills/code-review); // Agents resolve skills by strategy await editor.agent.create({ name: Dev Assistant, model: { provider: openai, name: gpt-4 }, workspace: { type: id, workspaceId: workspace.id }, skills: { [skill.id]: { strategy: latest } }, skillsFormat: xml, });对应服务器端点为GET/POST/PATCH/DELETE /stored/workspaces、GET/POST/PATCH/DELETE /stored/skills与POST /stored/skills/:id/publish。v0.9.0 还修正了publishSkillFromSource()在发布版本上存储新的files字段并在调用update()前剥离undefined键libsql/pg 适配器拒绝undefined绑定参数。收藏命名空间v0.9.0 新增editor.favorites让非 HTTP 调用方也能直接收藏/取消收藏/查询已收藏的存储代理与技能import { MastraEditor } from mastra/editor; const editor new MastraEditor({ mastra }); // Toggle await editor.favorites.favorite({ userId, entityType: agent, entityId }); await editor.favorites.unfavorite({ userId, entityType: agent, entityId }); // Lookups const isFav await editor.favorites.isFavorited({ userId, entityType: agent, entityId }); const favSet await editor.favorites.isFavoritedBatch({ userId, entityType: agent, entityIds }); const ids await editor.favorites.listFavoritedIds({ userId, entityType: agent });该命名空间只负责存储变更——可见性与归属强制仍由调用方承担mastra/server的 HTTP 路由处理器已经这样做。MCP 支持客户端、服务器与 Apps 扩展MCP 服务器存储v0.6.0editor.mcpServer提供完整 CRUD并自动把存储配置水合为运行中的MCPServer实例——通过从 Mastra 注册表解析工具、代理与工作流引用const editor new MastraEditor(); const mastra new Mastra({ tools: { getWeather: weatherTool, calculate: calculatorTool }, storage: new LibSQLStore({ url: :memory: }), editor, }); // Store an MCP server config referencing tools by ID const server await editor.mcpServer.create({ id: my-server, name: My MCP Server, version: 1.0.0, tools: { getWeather: {}, calculate: { description: Custom description } }, }); // Retrieve — automatically hydrates into a real MCPServer with resolved tools const mcp await editor.mcpServer.getById(my-server); const tools mcp.tools(); // { getWeather: ..., calculate: ... }MCP 客户端管理v0.4.0editor.mcpClient命名空间管理存储的 MCP 客户端配置存储代理可按服务器做工具过滤。编辑器内 MCP 体验修复v0.7.22MCP 客户端表单脏状态增删客户端后保存按钮可用、裸名与命名空间化工具名都正确匹配、cookie/header 中的 token 会转发到受认证保护的 MCP 服务器、系统提示中的请求上下文变量正确插值。MCP Apps 扩展v0.7.23SEP-1865MCPServer接受appResources配置注册交互式ui://HTML 资源MCPClient把 MCP 工具转换为 Mastra 工具时保留完整_meta含ui.resourceUri两者都声明io.modelcontextprotocol/ui扩展能力const server new MCPServer({ name: my-server, tools: { myTool }, appResources: { dashboard: { name: Dashboard, description: Interactive dashboard UI, html: html.../html, }, }, });模板引擎与安全修复模板引擎源码见 template-engine.ts支持三种插值语法{{variableName}}—— 直接变量替换{{nested.path.value}}—— 点号路径解析{{variable || default}}—— 单引号或双引号的兜底值。无法解析且没有兜底的变量原样保留。v0.7.21 修复了数组与对象的渲染此前{{products}}数组/对象会渲染成[object Object],[object Object]现在会自动 JSON 序列化输出完整 JSON 表示。v0.14.6-alpha.1 修复了原型链污染问题提示词块模板不再解析继承自Object.prototype的成员。此前renderTemplate会把{{constructor}}、{{toString}}、{{valueOf}}当作上下文数据读取把原生代码文本如function Object() { [native code] }注入存储代理的指令并跳过声明的兜底值。路径解析现在只沿自身属性hasOwnProperty前进——继承成员视为未解析无兜底时原样保留有兜底时被兜底替换而故意遮蔽内置名的上下文键如{ toString: shadowed }仍能正常解析。Agent Builder 与 EE 许可v0.10.0 通过mastra/editor/ee子路径提供EditorAgentBuilder与 Agent Builder 运行时。MastraEditor上接入了hasEnabledBuilderConfig()、resolveBuilder()、ensureBuilderWorkspaces()、reconcileBuilderWorkspaces()Builder 创建的代理默认启用observationalMemory: trueapplyBuilderDefaults/BUILDER_BASELINE_DEFAULTS。生产环境没有有效MASTRA_EE_LICENSE时resolveBuilder()会抛出[mastra/auth-ee] Agent Builder is configured but no valid EE license was found.开发环境通过isEEEnabled()绕过import { Mastra } from mastra/core; import { MastraEditor } from mastra/editor; const editor new MastraEditor({ builder: { enabled: true, configuration: { agent: { models: { default: { provider: openai, modelId: gpt-4o-mini } }, }, }, }, }); new Mastra({ storage, editor }); // Later, on demand: const builder await editor.resolveBuilder(); // builder is undefined when the builder is not configured/enabled.v0.10.1 为createBuilderAgent()加入可选构造参数允许在保留规范id、name、description的同时覆盖默认值const builder createBuilderAgent({ model: openai(gpt-4o), instructions: Custom instructions for this deployment, });v0.11.0 内置的 builder agent 默认启用三个错误处理器OpenAI 瞬时错误server_error、rate_limit、overloaded自动重试、Anthropic 400 prefill 拒绝恢复、按 Provider 的历史形状修复——也可以用自定义errorProcessors扩展或替换。工程与发布注意事项v0.12.1 修复了mastra/editor在原生 Windows 上的构建失败tsup 入口 glob 改用 POSIX 分隔符并针对 2026-06-17 easy-day-js 供应链事件做了安全补丁发布v0.14.3 起CHANGELOG.md不再随 npm 包分发减小包体积同版本还修复了应用存储描述时保留工具 schema 的问题v0.10.0 移除 zod 作为必需 peer 依赖内部 schema 改用纯 JSON Schema 对象v0.3.0 为破坏性变更cloneAgent()从Agent类移除克隆统一走editor.agent.clone(agent, { newId })同时存储代理的tools字段从string[]改为Recordstring, { description?: string }以支持逐工具描述覆盖缓存与注册表的一致性v0.3.0 起更新/删除存储代理时同时清理编辑器缓存与 Mastra 注册表避免 CMS 页面出现陈旧数据v0.5.0 修复了条件规则未持久化的问题并为 libsql/pg 增加mastra_agent_versions的ALTER TABLE迁移新增mcpClients、requestContextSchema、workspace、skills、skillsFormat列。结语mastra/editor把「可被 Studio 编辑、可从数据库重建、可参与版本管理」这组能力从 UI 中剥离出来沉淀为独立的运行时层。理解它的所有权模型editor配置 applyStoredOverrides、命名空间与缓存语义、draft/published 版本解析以及处理器图、工具 Provider、工作区/技能等扩展域是构建基于 Mastra 的动态代理管理系统的关键。相关实现可继续深入阅读 包 README、入口源码、命名空间基类 与 模板引擎完整的版本演进记录见 CHANGELOG。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra Editor 深度解析：@mastra/editor 的存储、版本化与运行时水合机制
Mastra Editor 深度解析mastra/editor 的存储、版本化与运行时水合机制【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/editor是 Mastra Studio 编辑体验背后的数据与 Provider 层统一管理代理agent、提示词块prompt、评分器scorer、MCP 客户端/服务器、工作区workspace、技能skill与收藏favorites并打通「代码源」与「数据库源」两种存储模式。读完本文你将掌握如何把MastraEditor接入 Mastra 实例、如何通过editor配置声明哪些代理字段允许 Studio 覆盖、如何理解 draft/published 版本解析与缓存语义以及如何利用处理器图、工具 Provider 与工作区/技能域构建可序列化的 Agent 配置体系。mastra/editor 在 Mastra 生态中的定位从仓库中的 包 README 可以确认其官方定位The data and provider layer behind Mastra Studio editing experiences. It manages agents, prompts, scorers, MCP servers, workspaces, skills, and favorites across code and storage sources.也就是说mastra/editor不是 UI 组件库而是承载「存储 版本化 水合hydration」的运行时层UI如 Studio/Playground通过它读写配置运行时通过它把存储的配置重新实例化为可执行的Agent、MCPServer、Workspace等对象。从 源码入口 可以看到它对外暴露了MastraEditor主类以及EditorAgentNamespace、EditorPromptNamespace、EditorScorerNamespace、EditorMCPServerNamespace、EditorWorkspaceNamespace、EditorSkillNamespace、EditorFavoritesNamespace等一组命名空间还有renderTemplate、evaluateRuleGroup、resolveInstructionBlocks三个可在外部复用的纯函数。安装与最小接入npm install mastra/editor最小接入方式是把编辑器实例交给Mastraimport { Mastra } from mastra/core/mastra; import { MastraEditor } from mastra/editor; export const mastra new Mastra({ editor: new MastraEditor(), });传入后编辑器会通过registerWithMastra()与Mastra共享 storage、logger 与运行时注册表源码见 index.ts。package.json中约定了 peer 依赖mastra/core 1.34.0-0 2.0.0-0mastra/mcp可选运行时要求 Node.js22.13.0。编辑器所有权模型code-defined 与 stored 配置如何共处用editor选项声明可编辑字段自 v0.11.0 起代码中定义的代理可以显式声明哪些字段允许 Studio 编辑其余字段保持代码值不变new Agent({ name: Weather Agent, model, editor: { instructions: true, tools: { description: true }, }, });编辑器只会对editor配置所「拥有」的字段应用存储覆盖被锁定的字段始终使用代码中的值单个代理传入editor: false则完全锁定MastraEditor提供source选项选择编辑体验source: code时自动接入FilesystemStore默认目录./mastra/editor/可用codePath覆盖把覆盖持久化为确定性的按代理 JSON 文件source: db默认则走项目已配置的存储后端。applyStoredOverrides 的合并边界v0.7.0 引入的applyStoredOverrides规定了合并的严格边界当某个 code-defined 代理存在存储配置时编辑器只把存储中的instructions和tools合并到代码值之上model、memory、workspace 等字段永不被覆盖因为它们可能包含 SDK 实例或动态函数无法安全序列化。代码原始值通过 WeakMap 保留存储覆盖被删除后即恢复。Studio 编辑指令不丢失 providerOptionsv0.14.2 修复了一个隐蔽问题当代码把指令定义为结构化系统消息例如带 Anthropic prompt-cache 断点时Studio 中编辑并发布指令曾会把它替换成纯字符串导致providerOptions静默丢失——此后每次请求都按未缓存输入付费。修复后 Studio 只拥有「措辞」发布文本会被重新包回代码定义的 message envelopeconst agent new Agent({ id: voice-agent, name: Voice Agent, instructions: { role: system, content: You are a helpful voice assistant., providerOptions: { anthropic: { cacheControl: { type: ephemeral } } }, }, model: anthropic/claude-sonnet-4-6, });该修复对既有发布覆盖是追溯生效的升级后自动套用代码 envelope无需迁移。指令完全委托给 Studioeditor: { instructions: true }的代理没有代码 envelope不受影响。指令委托 Studio 时的失败语义v0.14.0 起editor: { instructions: true }且 Studio 中尚无已发布版本从未供给、只有草稿、被删除、发布版本无指令或存储加载失败时解析或生成代理会抛出清晰错误而不再像以前那样静默以空 system prompt 运行// Agent definition — Studio owns the instructions: export const agent new Agent({ id: support-agent, editor: { instructions: true }, model: openai/gpt-4o, }); // Throws until a version is published in Studio: const agent client.getAgent(support-agent, { status: published }); await agent.generate(hi); // Use status: draft to run against the latest draft instead, without publishing: const draftAgent client.getAgent(support-agent, { status: draft }); await draftAgent.generate(hi);命名空间架构与缓存语义v0.3.0 将MastraEditor重构为命名空间模式v0.5.0 起把四个版本化域统一到CrudEditorNamespace基类之上源码见 namespaces/base.ts命名空间职责editor.agent存储代理的 CRUD、版本化、克隆与覆盖editor.prompt可复用提示词块prompt block的 CRUDeditor.scorerLLM-as-judge 与预设评分器定义的 CRUDeditor.mcp/editor.mcpServerMCP 客户端 / 服务器配置的 CRUD 与水合editor.workspace工作区配置 CRUD 与水合editor.skill技能定义 CRUD 与发布editor.favorites代理/技能的收藏管理CrudEditorNamespace内置了按实体 id 的缓存getById的默认版本请求走缓存而带versionId、versionNumber或status的版本请求直接穿透到存储。v0.14.6-alpha.1 修复了一个与此相关的边界 bug此前版本请求检测用真值判断导致getById(id, { versionNumber: 0 })被当作默认请求——在热缓存时从缓存返回默认实体、冷缓存时返回null。修复后在共享的CrudEditorNamespace与代理适配器中改用显式! undefined判断任何显式versionNumber包括0都会一致地绕过缓存直达版本解析。缓存失效方面所有变更操作create/update/delete会自动使受影响实体的缓存失效v0.9.0 起clearCache(id)即使在实体未被缓存时也会调用onCacheEvict(id)让子类可以清理绕过编辑器缓存的版本级运行时注册表v0.5.0 起四个版本化域agents、scorers、prompt-blocks、mcp-clients在版本激活、恢复、删除后都会清缓存。存储层db 源、代码源与来源控制FilesystemStoreGit 友好的编辑器存储v0.7.0 引入FilesystemStore把代理配置、提示词块、评分器、MCP 客户端/服务器、工作区与技能以 JSON 文件形式写入本地目录默认.mastra-storage/。只有已发布的快照会落盘版本历史保存在内存中。配合MastraCompositeStore的editor简写即可实现 Git 友好的配置管理import { FilesystemStore, MastraCompositeStore } from mastra/core/storage; import { PostgresStore } from mastra/pg; export const mastra new Mastra({ storage: new MastraCompositeStore({ id: composite, default: new PostgresStore({ id: pg, connectionString: process.env.DATABASE_URL }), editor: new FilesystemStore({ dir: .mastra-storage }), }), });来源控制 Providerv0.12.0 引入SourceControlProvider接口让代码模式source: code的代理编辑可以走托管源码控制存储。从 index.ts 源码 可以看到构造MastraEditor时会默认用createGitHubSourceControlProviderFromEnv(process.env, { pathPrefix: this.__codePath })从环境变量创建来源控制 ProviderregisterWithMastra()在source code时会把存储替换为MastraCompositeStore组合现有存储、SourceAgentsSourceControl与FilesystemStoreconst editor new MastraEditor({ source: code, sourceControlProvider, });来源后端可以读、写、列出历史并打开变更请求change request。版本管理draft、published 与 versionId版本解析的默认行为经历了演进v0.7.9 起执行端点的默认版本解析从 draft 改为 publishedv0.7.7 起GET /api/agents/:agentId支持?statusdraft最新草稿、?statuspublished激活版本、?versionIdid指定版本三个查询参数v0.7.10 修复了「请求 published 但未设置activeVersionId时回落到最新草稿」的问题——现在会保留代码默认值v0.14.1 修复了草稿更新后已发布版本被破坏的问题并让 draft/versionId/versionNumber 选择都被正确尊重v0.14.0 起代理快照的更新会保持为草稿直到显式发布。此外v0.7.16 保证解析存储代理版本时不再修改共享的单例代理实例——指令与工具覆盖被应用到隔离的克隆上并发版本解析是安全的覆盖不会泄漏到全局代理。存储代理的高级配置能力动态指令提示词块prompt blockv0.3.0 让存储代理的指令可以从可复用提示词块组合而来形成类似 Prompt-CMS 的编辑体验。指令数组可以混用三种块text—— 静态文本支持{{variable}}插值prompt_block_ref—— 引用数据库中存储的版本化提示词块prompt_block—— 内联提示词块可带条件规则。// Create a reusable prompt block const block await editor.createPromptBlock({ id: security-rules, name: Security Rules, content: You must verify the users identity. The users role is {{user.role}}., rules: { operator: AND, conditions: [{ field: user.isAuthenticated, operator: equals, value: true }], }, }); // Create a stored agent that references the prompt block await editor.createStoredAgent({ id: support-agent, name: Support Agent, instructions: [ { type: text, content: You are a helpful support agent for {{company}}. }, { type: prompt_block_ref, id: security-rules }, { type: prompt_block, content: Always be polite., rules: { operator: AND, conditions: [{ field: tone, operator: equals, value: formal }] }, }, ], model: { provider: openai, name: gpt-4o }, }); // At runtime, instructions resolve dynamically based on request context const agent await editor.getStoredAgentById(support-agent); const result await agent.generate(Help me reset my password, { requestContext: new RequestContext([ [company, Acme Corp], [user.isAuthenticated, true], [user.role, admin], [tone, formal], ]), });提示词块是版本化的——更新块内容对所有引用它的代理立即生效无需清理缓存。条件字段与 requestContextSchemav0.3.0 让存储代理的tools、model、workflows、agents、memory、scorers、inputProcessors、outputProcessors、defaultOptions字段都可以配置为带规则组的条件变体运行时针对请求上下文求值所有匹配变体会累积——数组拼接、对象浅合并await agentsStore.create({ agent: { id: my-agent, name: My Agent, instructions: You are a helpful assistant, model: { provider: openai, name: gpt-4 }, tools: [ { value: { basic-tool: {} } }, { value: { premium-tool: {} }, rules: { operator: AND, conditions: [{ field: tier, operator: equals, value: premium }], }, }, ], requestContextSchema: { type: object, properties: { tier: { type: string } }, }, }, });requestContextSchemaJSON Schema会被转换为 Zod schema 传给 Agent 构造器从而对请求上下文做校验。规则求值的核心函数evaluateRuleGroup与指令块解析函数resolveInstructionBlocks都作为独立导出暴露在 index.ts可被上层 UI 直接复用。观测记忆observational memoryv0.4.0 起存储代理支持观测记忆配置并在 v0.13.3 把 Agent Builder 代理的默认观测记忆模型从__GATEWAY_GOOGLE_MODEL__切换为__GATEWAY_OPENAI_MODEL_MINI__需要在这些环境设置OPENAI_API_KEY管理员仍可覆盖await editor.agent.create({ name: My Agent, memory: { observationalMemory: true, // enable with defaults options: { lastMessages: 40 }, }, }); // Or with custom configuration: await editor.agent.create({ name: My Agent, memory: { observationalMemory: { model: google/gemini-2.5-flash, scope: resource, // thread (per-conversation) or resource (shared across threads) shareTokenBudget: true, observation: { messageTokens: 50000 }, reflection: { observationTokens: 60000 }, }, options: { lastMessages: 40 }, }, });durable 存储代理v0.14.0 为存储代理新增durable选项使通过 Agents API 创建的代理无需部署代码即可获得持久化执行能力await mastraClient.createStoredAgent({ id: helper, name: Helper, instructions: You are a helpful assistant., model: { provider: openai, name: gpt-5 }, durable: true, });传入true使用默认值或传{ maxSteps, cleanupTimeoutMs }调优持久循环。Cache 与 pubsub 继承自服务器的Mastra实例——跨副本的持久化需要在那里配置分布式后端自动恢复仍通过代码中的recovery.durableAgents配置。metadatav0.8.0 为 code-defined 代理加入可选metadata传给new Agent({...})用agent.getMetadata()读取客户端可从现有/agents与/agents/:agentId响应过滤无需把数据编码进 id 或 name。metadata 支持与其他配置字段相同的DynamicArgument形式可基于请求上下文逐请求解析const tenantAgent new Agent({ id: tenant-agent, name: Tenant Agent, instructions: You help customers with tenant-specific tasks., model: openai/gpt-5, metadata: ({ requestContext }) ({ type: support, tenant: requestContext.get(tenant), }), }); await tenantAgent.getMetadata({ requestContext }); // { type: support, tenant: acme }通过editor.agent.clone()克隆运行时代理时若调用方未显式提供 metadata会继承源代理的 metadata。工具 ProviderOAuth 连接与多租户v1 ToolProvider 运行时v0.11.0 落地了 v1ToolProvider运行时、服务器路由、客户端 SDK 方法与编辑器接线。存储代理通过toolProviders配置在每次执行时绑定每个工具包toolkit的连接连接可以按作者per-author、跨组织共享shared或由调用方提供caller-supplied{ toolProviders: { composio: { connections: { gmail: [{ kind: author, toolkit: gmail, connectionId: auth_abc, scope: per-author }], }, tools: { GMAIL_FETCH_EMAILS: { toolkit: gmail }, }, }, }, }客户端 SDK 新增连接管理接口import { MastraClient } from mastra/client-js; const client new MastraClient({ baseUrl: … }); const composio client.toolProvider(composio); const { items } await composio.listConnections({ toolkit: gmail }); await composio.disconnectConnection(auth_abc);Provider 实现 vNext 表面listToolkitsVNext、listToolsVNext、resolveToolsVNext外加认证回路authorize、getAuthStatus、listConnections、disconnectConnection、listConnectionFields、health。Composio Provider 已按该表面重写旧目录方法保留为deprecated兼容垫片连接列表响应使用page/perPage分页与服务器其余表面一致。运行时还有两条错误隔离策略连接作用域无法从请求上下文解析时记录一次性警告并回退到共享桶多租户部署能及时发现身份接线未达运行时某个工具包返回的连接数超过其声明能力时记录并跳过该工具包而不影响同代理上的其他 Provider 与其他工具包。ComposioToolProvider 的多租户演进v0.13.7 起caller-supplied作用域的代理让 Composio 在每个租户的用户桶内选择已连接账户而非为所有调用者钉住一个共享账户ComposioToolProvider会转发defaultScope可在构造时一次性设置 Provider 级连接作用域。v0.14.0 进一步支持认证用户执行与确定性连接路由调用方绑定的连接精确路由到存储的对应已连接账户包括通过 Composio ACL 共享的账户。应用用户 id 与 Composio 用户 id 的映射通过userIdResolver完成import { MASTRA_USER_KEY } from mastra/server/auth; import { ComposioToolProvider } from mastra/editor/composio; const composio new ComposioToolProvider({ apiKey: process.env.COMPOSIO_API_KEY!, userIdResolver: ({ requestContext }) { const user requestContext?.getRaw(MASTRA_USER_KEY); if (!user || typeof user ! object || !(id in user) || typeof user.id ! string) return undefined; return user.id; }, });v0.14.0 还修复了 Composio 工具结果不校验的问题解析后的工具保留 Composio 提供的输出 schema真实 API 响应含 null 或多余字段通过而结构非法输出被拒绝而不是静默返回——这也让 Composio 工具可用于要求输出 schema 的 API如createStep(tool)。内置 Provider 与独立入口v0.4.0 起提供两个内置工具 Provider各自是独立入口点——只引入mastra/editor不会加载任何 Provider SDK 代码mastra/editor/composio—— 基于composio/core与composio/mastra支持工具包/工具发现与执行mastra/editor/arcade—— 基于arcadeai/arcadejs内置预置目录93 个工具包、工具发现与执行。import { MastraEditor } from mastra/editor; import { ComposioToolProvider } from mastra/editor/composio; import { ArcadeToolProvider } from mastra/editor/arcade; const editor new MastraEditor({ toolProviders: { composio: new ComposioToolProvider({ apiKey: ... }), arcade: new ArcadeToolProvider({ apiKey: ... }), }, });处理器 Provider 与处理器图v0.6.0 引入 Processor Provider——一套在存储代理上配置与水合处理器的系统。自定义处理器类型声明配置 schema、可用阶段phases与工厂方法然后组合成可序列化的处理器图支持顺序、并行与条件执行import { MastraEditor } from mastra/editor; // Built-in processors (token-limiter, unicode-normalizer, etc.) are registered automatically. // Only register custom providers for your own processors: const editor new MastraEditor({ processorProviders: { my-custom-filter: myCustomFilterProvider, }, });const agentConfig { inputProcessors: { steps: [ { type: step, step: { id: norm, providerId: unicode-normalizer, config: {}, enabledPhases: [processInput] }, }, { type: step, step: { id: limit, providerId: token-limiter, config: { limit: 4000 }, enabledPhases: [processInput, processOutputStream], }, }, ], }, };v0.14.6-alpha.1 加强了水合期校验处理器图水合现在会在实例化处理器前把每个存储步骤配置对照所选 Provider 的configSchema校验与文档化的ProcessorProvider契约一致。此前resolveStep()把原始存储配置直接传给createProcessor()畸形配置可能构造出有问题的处理器、到请求执行时才失败且 schema 的.default()/transform 输出被跳过。现在无效配置在水合时即抛出错误错误信息标明 Provider 与图步骤而校验后的配置含默认值与变换才会到达createProcessor()。工作区、技能与收藏工作区域v0.5.0 引入editor.workspace命名空间工作区配置的 CRUD以及hydrateSnapshotToWorkspace()把存储快照解析为运行时Workspace实例。v0.9.0 补充反向操作snapshotFromWorkspace()可把运行中的Workspace快照化以便持久化该方法是异步的会等待sandbox.getInfo()与filesystem.getInfo()让CompositeFilesystem这类异步 Provider 把挂载元数据保留在存储配置中const snapshot await editor.workspace.snapshotFromWorkspace(runtimeWorkspace); await editor.workspace.create({ id: my-workspace, ...snapshot });v0.13.5 新增工作区级 Provider 注册表WorkspaceProvider工厂把完整的Workspace实例作为一个单元构建而不必分别组合文件系统与沙箱 Provider存储代理可通过{ type: provider, provider: my-cloud, config: { ... } }引用编辑器在代理水合时调用注册的工厂import { MastraEditor } from mastra/editor; import { Workspace } from mastra/core/workspace; const editor new MastraEditor({ workspaces: { my-cloud: { id: my-cloud, name: My Cloud Workspace, createWorkspace: config new Workspace({ id: cloud-ws, name: Cloud WS, filesystem: new MyCloudFilesystem(config), sandbox: new MyCloudSandbox(config), }), }, }, }); // Stored agent workspace reference using the provider: // { type: provider, provider: my-cloud, config: { region: us-east-1 } }技能域与发布模型v0.5.0 为技能引入了文件系统原生的「草稿 → 发布」版本模型编辑表面实时文件系统与服务表面版本化 blob 存储分离。技能以文件系统树形式版本化配合基于 SHA-256 哈希的内容寻址BlobStore有InMemoryBlobStore、LibSQL/Postgres/MongoDB 实现以及面向 S3/S3 兼容存储的S3BlobStore可在MastraEditorConfig.blobStores注册 Provider。editor.skill.publish(skillId, source, skillPath)—— 把技能目录从文件系统快照进 blob 存储创建带树清单的新版本并设置activeVersionIdeditor.skill.update({ id, activeVersionId })—— 切换到历史版本无需重新发布发布技能会自动使引用它的缓存代理失效下次访问时以新版本重新水合。代理引用技能有三种解析策略strategy: latest—— 解析技能的激活版本尊重activeVersionId以便回滚pin: versionId—— 钉住特定版本不受后续发布影响strategy: live—— 直接从实时文件系统读取不走 blob 存储。import { MastraEditor } from mastra/editor; import { s3FilesystemProvider, s3BlobStoreProvider } from mastra/s3; import { e2bSandboxProvider } from mastra/e2b; const editor new MastraEditor({ filesystems: { s3: s3FilesystemProvider }, sandboxes: { e2b: e2bSandboxProvider }, blobStores: { s3: s3BlobStoreProvider }, }); // Create a skill and publish it const skill await editor.skill.create({ name: Code Review, description: Reviews code for best practices, instructions: Analyze the code and provide feedback..., }); await editor.skill.publish(skill.id, source, skills/code-review); // Agents resolve skills by strategy await editor.agent.create({ name: Dev Assistant, model: { provider: openai, name: gpt-4 }, workspace: { type: id, workspaceId: workspace.id }, skills: { [skill.id]: { strategy: latest } }, skillsFormat: xml, });对应服务器端点为GET/POST/PATCH/DELETE /stored/workspaces、GET/POST/PATCH/DELETE /stored/skills与POST /stored/skills/:id/publish。v0.9.0 还修正了publishSkillFromSource()在发布版本上存储新的files字段并在调用update()前剥离undefined键libsql/pg 适配器拒绝undefined绑定参数。收藏命名空间v0.9.0 新增editor.favorites让非 HTTP 调用方也能直接收藏/取消收藏/查询已收藏的存储代理与技能import { MastraEditor } from mastra/editor; const editor new MastraEditor({ mastra }); // Toggle await editor.favorites.favorite({ userId, entityType: agent, entityId }); await editor.favorites.unfavorite({ userId, entityType: agent, entityId }); // Lookups const isFav await editor.favorites.isFavorited({ userId, entityType: agent, entityId }); const favSet await editor.favorites.isFavoritedBatch({ userId, entityType: agent, entityIds }); const ids await editor.favorites.listFavoritedIds({ userId, entityType: agent });该命名空间只负责存储变更——可见性与归属强制仍由调用方承担mastra/server的 HTTP 路由处理器已经这样做。MCP 支持客户端、服务器与 Apps 扩展MCP 服务器存储v0.6.0editor.mcpServer提供完整 CRUD并自动把存储配置水合为运行中的MCPServer实例——通过从 Mastra 注册表解析工具、代理与工作流引用const editor new MastraEditor(); const mastra new Mastra({ tools: { getWeather: weatherTool, calculate: calculatorTool }, storage: new LibSQLStore({ url: :memory: }), editor, }); // Store an MCP server config referencing tools by ID const server await editor.mcpServer.create({ id: my-server, name: My MCP Server, version: 1.0.0, tools: { getWeather: {}, calculate: { description: Custom description } }, }); // Retrieve — automatically hydrates into a real MCPServer with resolved tools const mcp await editor.mcpServer.getById(my-server); const tools mcp.tools(); // { getWeather: ..., calculate: ... }MCP 客户端管理v0.4.0editor.mcpClient命名空间管理存储的 MCP 客户端配置存储代理可按服务器做工具过滤。编辑器内 MCP 体验修复v0.7.22MCP 客户端表单脏状态增删客户端后保存按钮可用、裸名与命名空间化工具名都正确匹配、cookie/header 中的 token 会转发到受认证保护的 MCP 服务器、系统提示中的请求上下文变量正确插值。MCP Apps 扩展v0.7.23SEP-1865MCPServer接受appResources配置注册交互式ui://HTML 资源MCPClient把 MCP 工具转换为 Mastra 工具时保留完整_meta含ui.resourceUri两者都声明io.modelcontextprotocol/ui扩展能力const server new MCPServer({ name: my-server, tools: { myTool }, appResources: { dashboard: { name: Dashboard, description: Interactive dashboard UI, html: html.../html, }, }, });模板引擎与安全修复模板引擎源码见 template-engine.ts支持三种插值语法{{variableName}}—— 直接变量替换{{nested.path.value}}—— 点号路径解析{{variable || default}}—— 单引号或双引号的兜底值。无法解析且没有兜底的变量原样保留。v0.7.21 修复了数组与对象的渲染此前{{products}}数组/对象会渲染成[object Object],[object Object]现在会自动 JSON 序列化输出完整 JSON 表示。v0.14.6-alpha.1 修复了原型链污染问题提示词块模板不再解析继承自Object.prototype的成员。此前renderTemplate会把{{constructor}}、{{toString}}、{{valueOf}}当作上下文数据读取把原生代码文本如function Object() { [native code] }注入存储代理的指令并跳过声明的兜底值。路径解析现在只沿自身属性hasOwnProperty前进——继承成员视为未解析无兜底时原样保留有兜底时被兜底替换而故意遮蔽内置名的上下文键如{ toString: shadowed }仍能正常解析。Agent Builder 与 EE 许可v0.10.0 通过mastra/editor/ee子路径提供EditorAgentBuilder与 Agent Builder 运行时。MastraEditor上接入了hasEnabledBuilderConfig()、resolveBuilder()、ensureBuilderWorkspaces()、reconcileBuilderWorkspaces()Builder 创建的代理默认启用observationalMemory: trueapplyBuilderDefaults/BUILDER_BASELINE_DEFAULTS。生产环境没有有效MASTRA_EE_LICENSE时resolveBuilder()会抛出[mastra/auth-ee] Agent Builder is configured but no valid EE license was found.开发环境通过isEEEnabled()绕过import { Mastra } from mastra/core; import { MastraEditor } from mastra/editor; const editor new MastraEditor({ builder: { enabled: true, configuration: { agent: { models: { default: { provider: openai, modelId: gpt-4o-mini } }, }, }, }, }); new Mastra({ storage, editor }); // Later, on demand: const builder await editor.resolveBuilder(); // builder is undefined when the builder is not configured/enabled.v0.10.1 为createBuilderAgent()加入可选构造参数允许在保留规范id、name、description的同时覆盖默认值const builder createBuilderAgent({ model: openai(gpt-4o), instructions: Custom instructions for this deployment, });v0.11.0 内置的 builder agent 默认启用三个错误处理器OpenAI 瞬时错误server_error、rate_limit、overloaded自动重试、Anthropic 400 prefill 拒绝恢复、按 Provider 的历史形状修复——也可以用自定义errorProcessors扩展或替换。工程与发布注意事项v0.12.1 修复了mastra/editor在原生 Windows 上的构建失败tsup 入口 glob 改用 POSIX 分隔符并针对 2026-06-17 easy-day-js 供应链事件做了安全补丁发布v0.14.3 起CHANGELOG.md不再随 npm 包分发减小包体积同版本还修复了应用存储描述时保留工具 schema 的问题v0.10.0 移除 zod 作为必需 peer 依赖内部 schema 改用纯 JSON Schema 对象v0.3.0 为破坏性变更cloneAgent()从Agent类移除克隆统一走editor.agent.clone(agent, { newId })同时存储代理的tools字段从string[]改为Recordstring, { description?: string }以支持逐工具描述覆盖缓存与注册表的一致性v0.3.0 起更新/删除存储代理时同时清理编辑器缓存与 Mastra 注册表避免 CMS 页面出现陈旧数据v0.5.0 修复了条件规则未持久化的问题并为 libsql/pg 增加mastra_agent_versions的ALTER TABLE迁移新增mcpClients、requestContextSchema、workspace、skills、skillsFormat列。结语mastra/editor把「可被 Studio 编辑、可从数据库重建、可参与版本管理」这组能力从 UI 中剥离出来沉淀为独立的运行时层。理解它的所有权模型editor配置 applyStoredOverrides、命名空间与缓存语义、draft/published 版本解析以及处理器图、工具 Provider、工作区/技能等扩展域是构建基于 Mastra 的动态代理管理系统的关键。相关实现可继续深入阅读 包 README、入口源码、命名空间基类 与 模板引擎完整的版本演进记录见 CHANGELOG。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考