Mastra @mastra/client-js 变更日志精读：版本演进脉络与关键客户端 API 实现

Mastra mastra/client-js 变更日志精读版本演进脉络与关键客户端 API 实现【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以 client-sdks/client-js/CHANGELOG.mdmastra/client-js的完整版本历史为核心梳理该 SDK 从 0.1.0 到 1.46.0-alpha.3 的演进主线重点解析近期版本引入的线程所有权转移、可观测性查询、实验管理等关键 API并结合 src/client.ts 等源码印证各能力的实际落地位置帮助你系统掌握该客户端 SDK 的能力边界与升级策略。包定位与基本信息mastra/client-js是 Mastra 官方为运行中的 Mastra 服务器提供的类型化 JavaScript/TypeScript 客户端见 README从浏览器或服务端应用中直接调用 agents、workflows、tools、memory 和 vector API而无需手动拼装 HTTP 请求。从 package.json 可以确认当前包的关键事实包名mastra/client-js仓库内当前版本为1.46.0-alpha.3type: module同时提供 ESMdist/index.js与 CJSdist/index.cjs双入口及.d.ts类型声明运行时依赖mastra/core与mastra/schema-compatmonorepo 内的workspace:*依赖以及jose、canonicalize、lukeed/uuid、json-schema等轻量库zod为 peerDependency兼容^3.25.0 || ^4.0.0两个大版本运行环境要求node 22.13.0。变更日志顶部的1.46.0-alpha.3条目只包含Updated dependencies依赖mastra/core1.67.0-alpha.3联动升级这类条目说明该包遵循 monorepo 的 changesets 版本策略只要核心依赖mastra/core发版mastra/client-js也会跟随发布 patch 版本。理解这一点是读懂整份 1.4 万余行变更日志的前提。变更日志的结构与阅读方法整份日志按版本号倒序排列每个版本下分两级变更说明这是 changesets 工具的标准格式Minor Changes新增的公开能力新 API、新路由、新选项通常附带可直接复制的代码示例Patch Changes缺陷修复、类型修正等不改变主版本号的变更Updated dependencies由mastra/core、mastra/schema-compat等依赖包发版触发的被动升级条目中只列 commit 哈希与目标版本。此外版本号中的-alpha.N后缀代表 alpha 预览通道。同一组变更往往先在若干alpha版本中滚动发布例如1.44.0-alpha.0到1.44.0-alpha.12验证后再以稳定版1.44.0、1.45.0落定。因此生产环境建议以稳定版为基准通过稳定版条目中的示例了解新 API而把 alpha 条目当作即将可用的前瞻参考。1.46.0-alpha.2线程所有权转移resourceId 重分配这是变更日志中篇幅最重、实现跨度最大的一个功能条目覆盖mastra/core、mastra/memory、mastra/server、mastra/client-js以及七个存储适配器。其解决的问题是把一个已有线程thread整体迁移到另一个资源resource名下同时保留线程原始的createdAt时间戳支持把私有线程移入共享工作区这类此前需要 upsert 变通方案才能实现的场景。各层新增的能力按变更日志的原始描述完整如下mastra/core/mastra/memory新增Memory.updateThreadResourceId({ threadId, resourceId })方法由默认的MemoryStorage.updateThreadResourceId实现支撑。当启用语义召回semantic recall时消息向量会随迁移到新resourceId保证按资源范围的检索仍能召回被转移的线程mastra/server新增POST /memory/threads/:threadId/transfer路由。该端点仅允许具有权限的、非资源作用域的调用方访问并拒绝携带已解析资源作用域的请求mastra/client-js新增MemoryThread.transfer({ resourceId })方法存储适配器mastra/pg、mastra/libsql、mastra/mssql、mastra/dsql、mastra/oracledb、mastra/mysql、mastra/spanner提供原子、串行化的updateThreadResourceId覆盖实现。线程及其全部消息在单个事务内完成迁移因此对同一线程的并发转移不会交错执行导致分裂所有权。具体并发控制手段因引擎而异Postgres、MySQL、SQL Server 与 Oracle 使用行锁SELECT ... FOR UPDATE/UPDLOCK, HOLDLOCKlibSQL 与 Spanner 对写事务做串行化Aurora DSQL 依赖其乐观并发控制与自动重试不具备事务原语的适配器回退到基础尽力实现出错时 fail-closed 回滚。变更日志给出的官方示例客户端与服务端两侧// Server-side, from a privileged (non-resource-scoped) context: const thread await memory.updateThreadResourceId({ threadId: thread-123, resourceId: new-resource-456, }); // Client-side: const client new MastraClient({ baseUrl: http://localhost:4111 }); const thread client.getMemoryThread(thread-123, agent-id); await thread.transfer({ resourceId: new-resource-456 });从源码结构看客户端侧的transfer确实落地在资源类 MemoryThreadtransfer(params: TransferMemoryThreadParams): PromiseStorageThreadType接收TransferMemoryThreadParams即{ resourceId }并返回StorageThreadType与日志描述一致。1.45.1-alpha.1会话订阅取消竞态修复该版本修复了AgentControllerSession.subscribe()的一系列取消竞态。按日志原文修复后unsubscribe()在每个 await 与 dispatch 边界上都会生效已分离的订阅者不会再收到过期的会话状态、也不会泄漏响应体。具体修复的四种竞态为reader.read()恰好在 unsubscribe 前一刻 resolve 时派发的onEventonEvent处理器在块处理中途取消订阅后仍被继续派发的已缓冲帧onReconnect取消订阅时新拉取的重连响应体未被释放取消订阅之后重连请求被 reject仍触发onError。对应修复的 issue 编号为 #23454。对使用 Agent Controller 实时会话能力的开发者这是一类典型的长连接生命周期修复升级后可消除停止订阅后的内存/连接残留。1.45.0可观测性查询与消息列表分页1.45.0是功能密集的一个稳定版Minor 与 Patch 变更合计包含五项客户端能力其原始代码示例全部保留如下。1.queryTraces支持 feedback 谓词反馈过滤条件可按时间范围加条件查询 traceawait client.queryTraces({ timeRange: { from: 2026-08-01T00:00:00.000Z, to: 2026-08-08T00:00:00.000Z, }, where: { feedback: { some: { op: eq, left: { path: feedbackType }, right: { literal: rating } } } }, });2. 新增deleteFeedback()与deleteScores()按 id 删除可观测性反馈与评分记录await mastraClient.deleteFeedback({ feedbackIds: [feedback-1] });3. Agent Controller 消息列表支持存储层的分页、排序、过滤与消息包含项。原有的 Session 与数值型客户端 API 为兼容性继续返回消息数组const page await session.listMessages(thread-id, { perPage: 20, page: 0 });从源码结构看AgentController 中的listMessages以重载形式同时支持旧的单参数签名listMessages(threadId: string, limit?: number)与新的分页选项签名与旧 API 保持返回数组以兼容的描述吻合。4.listDatasetExperimentResults()新增tags选项可将结果限定为携带全部所列标签的记录const { results } await client.listDatasetExperimentResults(dataset-id, exp-id, { tags: [regression, p0], });5. 移除冗余类型断言不改变运行时行为与公开类型属于纯类型层清理。在 client.ts 中可以看到这些方法均作为MastraClient的便捷委托存在queryTraces(params)委托给this.observability.queryTracesclient.ts#L1117-L1118deleteTraces、deleteScores、listFeedback、deleteFeedback等同样一一委托到 observability 资源client.ts#L1161-L1237说明客户端采用顶层方法 领域资源对象的分层设计顶层方法主要服务于调用便利性与类型聚合。1.44.0可观测性删除、实验管理与数据集净化1.44.0是一次 API 面显著扩大的版本日志条目可归纳为四类。可观测性数据删除。新增deleteTraces()删除 trace 及其关联的可观测性信号await mastraClient.deleteTraces({ traceIds: [trace-1] });同时listFeedback()在不额外发起网络请求的前提下返回带类型的可选作者档案author profile前提是服务端认证提供者支持用户查找const result await client.listFeedback(); // Before: only the stored author ID was typed. console.log(result.feedback[0]?.feedbackUserId); // Now: the resolved profile is also typed when available. console.log(result.feedback[0]?.author?.name);实验Experiment生命周期管理。新增删除实验的方法删除时会尝试移除实验产生的可观测性 trace包括其 span 与 trace 关联信号不受支持的可观测性存储会保留 trace 并记录警告。日志给出两种删除姿势——按数据集删除与删除任何实验包括数据集已被删除的孤儿实验await client.deleteDatasetExperiment(datasetId, experimentId, { organizationId, projectId, });await client.deleteExperiment(experimentId);并新增updateDatasetExperiment()用于重命名实验或修改其描述与元数据const experiment await client.updateDatasetExperiment({ datasetId: dataset-id, experimentId: exp-id, name: Baseline vs. new prompt, });client.ts#L2256-L2269 中可以确认deleteExperiment与updateDatasetExperiment已作为公开方法实现进一步印证日志条目。数据集条目净化。新增dataset.purgeItem()从既有数据集历史与关联实验结果中抹除条目内容同时保留版本历史与审核状态被净化的条目会拒绝后续数据集更新后续写入的实验结果保持已抹除状态MongoDB 的净化依赖事务支持且数据集条目的写入不得与 purge 并发执行await dataset.purgeItem({ itemId: item-123 });类型与行为修正。包括数据集条目版本历史响应现在包含requestContext字段此前该字段被存储但从响应中剥离无法跨版本比对agent 执行的providerOptions不再静默剥离内置白名单之外的 provider 命名空间provider 选项值会按 JSON 校验且生成的路由类型与开放的 provider 契约对齐getSystemPackages()新增liveKitConnectionRouteEnabled字段当服务端挂载了默认的mastra/livekit连接路由时为trueconst { liveKitConnectionRouteEnabled } await client.getSystemPackages();工作流 step-graph 条目也补充了可选的id、description、metadata字段const workflow await client.getWorkflow(my-workflow).details(); for (const entry of workflow.stepGraph) { // id, description, and metadata are now typed on every entry console.log(entry.id, entry.description, entry.metadata); }早期里程碑从 workflow watch 到完整 Agent API日志尾部保留了 SDK 的起点对理解能力积累节奏很有价值0.1.0为客户端 SDK 增加 workflow watch 与 resume提交说明 Add workflow watch and resume to client sdk0.1.5一次性补齐三项基础能力——为客户端 SDK 添加全部 agentstream/generate选项、补充更多类型、支持 CommonJS0.1.7-alpha.11之前的 alpha 序列中还有 Better workflow watch api watch workflow by runId 与 CJS 打包文件切分等改进。可见 SDK 的能力积累路径是workflow 观测watch/resume→ Agent stream/generate 全量选项与双模块格式支持 → 类型完善 → 记忆/可观测性/Eval 等高级域 API。当前 1.x 版本中queryTraces、deleteFeedback、transfer等能力正是这条主线的延续。升级建议与版本追踪结合日志结构与包配置可以给出几条实用结论以稳定版条目为准绳1.44.0、1.45.0这类无-alpha后缀的版本才建议进入生产依赖alpha 条目用于提前评估 API 形态1.46.0-alpha.2的transfer即为典型前瞻。关注Updated dependencies而非忽略它mastra/client-js与mastra/core版本联动当前1.46.0-alpha.3对应mastra/core1.67.0-alpha.3升级客户端前建议核对mastra/core的对应版本说明确认服务端行为匹配。示例可直接落地日志中的示例均使用new MastraClient({ baseUrl: http://localhost:4111 })这一 Mastra 默认服务端口约定配合 README 中的安装方式npm install mastra/client-js即可在真实项目复现本文列出的各 API。实现细节查证路径客户端行为问题优先查 src/client.ts顶层委托与 src/resources/ 下的领域资源文件如 memory-thread.ts、agent-controller.ts、observability.ts路由契约以自动生成的 route-types.generated.ts由pnpm generate:route-types从mastra/server生成见 package.json 脚本为准。小结mastra/client-js的变更日志清晰地呈现了一个客户端 SDK 的成熟路径从 workflow watch/resume 起步到 Agent stream/generate 与双模块支持再到近期以数据治理为主线的能力扩展——线程所有权原子转移、trace/feedback/score 的删除与条件查询、实验生命周期管理、数据集条目净化。每个条目都附带可复制的代码示例与明确的服务端路由/存储约束配合仓库源码中的委托实现与生成式路由类型构成了从版本公告到可验证实现的完整证据链。维护者可以据此做增量升级评估开发者则可以此作为mastra/client-js各 API 能力边界的速查参考。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考