尧图网站建设 
Mastra × TanStack Start 服务端适配器用一条 Catch-All 路由挂载完整的 Agent HTTP 服务【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南围绕 Mastra 仓库中mastra/tanstack-start服务端适配器展开结合其 README、核心实现、单元测试 与 CHANGELOG 完整梳理该包的定位、接入方式、配置选项、底层原理与版本演进。读完本文你将掌握如何在一个 TanStack Start 应用中通过一条 catch-allsplat路由把 Mastra 实例的 REST、流式、自定义 API、MCP 与 A2A 端点全部对外暴露并理解适配器内部基于 Hono 的MastraServer机制及其鉴权、中间件行为。一、适配器定位一个路由点承载全部 Mastra 服务端能力mastra/tanstack-start的 README 开宗明义它通过 TanStack Start 服务端路由处理器暴露 Mastra 实例用于在同一个 TanStack Start 应用中对外提供 Mastra 的 REST、流式、自定义 API、MCP 和 A2A 端点。也就是说你不需要单独部署一个 Mastra 服务进程只需在既有 TanStack Start 应用里挂一个路由Mastra 的全部 HTTP 能力即随之就位。从 CHANGELOG 看该包诞生于0.2.0版本的一次 Minor 变更对应 PR #18270Addedmastra/tanstack-startserver adapter for mounting Mastra in TanStack Start apps via a catch-all server route. Uses the same Hono-based MastraServer pattern asmastra/next.这段记录说明了两个关键事实其一挂载方式是通过catch-all server routesplat 路由实现的其二它的底层沿用了与mastra/next一致的Hono 版 MastraServer模式——这解释了为什么它依赖mastra/hono与mastra/server见 package.json 的dependenciesmastra/server与mastra/hono均为 workspace 依赖。二、安装与最小接入安装只需一个命令同时装上 Hono peer 依赖npm install mastra/tanstack-start honopackage.json 中规定了运行时边界Node.js 版本要求22.13.0peer 依赖为mastra/core 1.50.0-0 2.0.0-0与hono ^4.12.8。最小接入方式是在src/routes/api/$.ts创建一个 splat 服务端路由import { createFileRoute } from tanstack/react-router; import { createStartRouteHandler } from mastra/tanstack-start; import { mastra } from ../../mastra; export const Route createFileRoute(/api/$)({ server: { handlers: createStartRouteHandler({ mastra }), }, });这里mastra是从src/mastra/index.ts导出的Mastra实例通常由mastra init初始化可包含 agents、tools、memory 等配置。createStartRouteHandler返回一个包含GET / POST / PUT / DELETE / PATCH / OPTIONS / HEAD全部七个 HTTP 方法处理器的对象正好满足 TanStack Startserver.handlers的签名要求。三、配置选项mastra、tools、prefixcreateStartRouteHandler的完整选项定义在 src/index.ts 的StartRouteHandlerOptions接口中选项类型默认值说明mastraMastra必填要对外提供的 Mastra 实例toolsToolsInput{}需要随服务端一起注册的工具prefixstring/apiAPI 路由前缀必须与 splat 路由的挂载路径一致其中prefix是最容易踩坑的选项。README 明确强调路由前缀与 splat 位置必须匹配如果路由文件是src/routes/api/$.ts则前缀保持默认的/api即可如果把路由挂到/api/mastra之下就必须显式传入相同前缀createStartRouteHandler({ mastra, prefix: /api/mastra, tools: { customTool }, });若不匹配适配器内部的 Hono 应用将无法正确解析路径请求会落在错误的路由段上。四、底层原理createStartRouteHandler 与 Hono 版 MastraServer阅读 src/index.ts 可以还原适配器的完整工作方式惰性初始化createStartRouteHandler内部维护一个appPromise首次请求到来时才调用initApp(mastra, tools, prefix)构建 Hono 应用并缓存从而保证模块级导出可以同步执行这在 TanStack Start 的服务端模块加载场景下很重要。统一处理器所有 HTTP 方法共享同一个handler内部只是app.fetch(request)——即把 TanStack Start 收到的标准Request原样转交给 Hono 应用处理再返回Response。MastraServer 装配initApp中创建一个新的Hono实例读取mastra.getServer()拿到服务端配置然后实例化MastraServer来自mastra/hono传入mastra、tools、taskStore、bodyLimitOptions、customRouteAuthConfig、customApiRoutes、prefix与mcpOptions。一次性 init最后调用await honoServerAdapter.init()这一调用完成上下文中间件、鉴权中间件、内建路由与自定义 API 路由的注册。值得注意的两个实现细节A2A 任务使用内存存储适配器创建了InMemoryTaskStore来自mastra/server/a2a/store意味着 A2A 任务状态不跨进程持久化重启即失效——这在 docs 框架指南 中同样有说明。请求体大小限制bodySizeLimit取自serverConfig?.bodySizeLimit ?? 4.5 * 1024 * 1024即默认约 4.5 MiB超限时onError返回{ error: Request body too large }。五、版本演进CHANGELOG 里的关键修复与变化CHANGELOG 完整记录了从0.2.0新增到0.2.25-alpha.3当前的版本轨迹。除去大量依赖版本对齐条目真正对本包功能有实质影响的变更集中在以下几处。5.1 中间件注册与公共路由鉴权修复0.2.18这是本包历史上最重要的一次功能修复对应 PR #22161、issue #21869。此前存在一个隐蔽缺陷通过server.middleware或在server配置中经mastra.setServerMiddleware()注册的中间件在通过服务端适配器而非mastra dev/mastra build提供时会被静默忽略。修复后的行为是以 Hono 为基础的适配器mastra/hono以及在其之上构建的mastra/next、mastra/tanstack-start会在init()期间注册已配置的中间件并保证与内建服务器相同的语义——用户中间件永远不会运行在声明为requiresAuth: false的公共路由上。同时修复了自定义路由声明requiresAuth: false但未被当作框架公共路由的问题当适配器从 Mastra 实例派生路由鉴权配置而非在构造时显式接收时公共路由也能被正确识别并豁免鉴权与用户中间件。这一保证在mastra/hono的测试中也有直接验证见 user-middleware.test.tsserver.middleware在自定义 API 路由上运行、但不在requiresAuth: false的框架公共路由上运行并在 auth-middleware.ts 中以requiresAuth开关实现。5.2 AgentController 命名统一0.2.10.2.1 引入了Harness→AgentController的重命名PR #18505mastra/core新增规范子路径mastra/core/agent-controllermastra/server的控制器会话 API 改为只在/agent-controller/...下提供。由于mastra/server是 tanstack-start 的依赖该重命名被同步传播到包括mastra/tanstack-start在内的全部服务端适配器同时mastra/core的 peer 依赖下限被抬高到1.47.0-0。这条记录对升级者是一个明确的兼容性提示。5.3 统一 schedules API 与 peer 依赖更新0.2.40.2.4 的变更内容是为统一的 schedules API 更新mastra/corepeer 依赖PR #18874。这类变更通常不引入新 API但要求使用方同步升级mastra/core属于跟着核心走的适配器常态。5.4 包体瘦身与文档改进0.2.22、0.2.230.2.22从分发到 npm 的文件中移除CHANGELOG.md以减小包体积同时更新 README 使其信息准确、及时。0.2.23将 Next.js 与 TanStack Start 适配器的 README 链接到各自的设置指南与 API 参考文档PR #22964。5.5 版本节奏与依赖对齐从 CHANGELOG 可以清晰看到适配器的版本节奏每个mastra/core/mastra/server/mastra/hono发布包括大量alpha.x预发布都会同步产生 tanstack-start 的对应Patch Changes。这正是适配器包跟随上游核心版本漂流的典型形态——功能面稳定主要变化来自底层依赖。截至本文最新版本为0.2.25-alpha.3对应的核心版本为mastra/core1.67.0-alpha.3。六、实战验证用 curl 测试天气 Agent按 docs 框架指南 的步骤完成mastra init初始化会在src/mastra下生成天气示例 agent、工具与配置并挂载适配器后启动应用npm run dev在另一个终端用 curl 调用天气 agent 的生成接口curl -X POST http://localhost:3000/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:What is the weather like in Seoul?}]}该端点会返回 agent 的完整 JSON 响应。注意这里的路径api/agents/...与默认前缀/api一致正是 splat 路由src/routes/api/$.ts捕获的请求。七、工程化配置Vite 与 Nitro 的 Node 依赖豁免Mastra 的依赖中包含 DuckDB 等 Node 原生模块直接进入 TanStack Start 的 Vite/Nitro 处理管线会出问题。框架指南给出两处vite.config.ts调整const config defineConfig({ resolve: { tsconfigPaths: true }, optimizeDeps: { exclude: [mastra/duckdb, execa], }, plugins: [ devtools(), - nitro({ rollupConfig: { external: [/^sentry\//] } }), nitro({ rollupConfig: { external: [/^sentry\//, /^duckdb\//], }, }),原理如下optimizeDeps.exclude中的mastra/duckdb防止 Vite 开发优化器把 DuckDB 的原生.node二进制当作 JavaScript 解析execa是mastra/core用于本地进程执行的仅服务端依赖其传递依赖npm-run-path、unicorn-magic使用了仅 Node 的条件导出浏览器构建优化器无法解析。Nitro 的rollupConfig.external增加/^duckdb\//把 DuckDB 的原生 Node 包排除在生产 bundle 之外由 Node.js 在运行时加载。这些改动只涉及vite.config.ts无需改动应用或 Mastra 源码。八、测试保障七个方法处理器与路由行为验证tanstack-start-adapter.test.ts 用 Vitest 覆盖了适配器的核心契约返回全部七个 HTTP 方法处理器GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD均为函数处理器返回Response对象GET /api返回 OpenAPI 规范或根响应状态码 500GET /api/agents正常返回响应未知路由如/api/nonexistent-route-xyz返回404支持自定义prefix如/custom-api与空tools。其中 404 测试直接验证了 Hono 应用路由穿透与未命中回退行为是理解splat 路由 Hono fetch链路的最直观样例。九、延伸阅读适配器包说明server-adapters/tanstack-start/README.md核心实现server-adapters/tanstack-start/src/index.ts单元测试server-adapters/tanstack-start/src/tests/tanstack-start-adapter.test.ts框架接入指南docs/src/content/en/integrations/frameworks/tanstack-start.mdx服务端适配器总览docs/src/content/en/docs/server/server-adapters.mdx服务端中间件说明docs/src/content/en/docs/server/middleware.mdx底层 Hono 适配器含中间件/鉴权实现与测试server-adapters/hono/src/index.ts、server-adapters/hono/src/tests/user-middleware.test.ts一句话总结mastra/tanstack-start是Mastra 服务端能力进 TanStack Start 应用的桥一条/api/$splat 路由 createStartRouteHandler({ mastra })即完成挂载其余所有复杂度Hono 装配、鉴权、中间件、MCP/A2A、体积限制都由其内部基于MastraServer的实现接管版本演进中的关键变更则集中在中间件注册修复、AgentController 重命名与依赖对齐之上。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra × TanStack Start 服务端适配器：用一条 Catch-All 路由挂载完整的 Agent HTTP 服务
Mastra × TanStack Start 服务端适配器用一条 Catch-All 路由挂载完整的 Agent HTTP 服务【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南围绕 Mastra 仓库中mastra/tanstack-start服务端适配器展开结合其 README、核心实现、单元测试 与 CHANGELOG 完整梳理该包的定位、接入方式、配置选项、底层原理与版本演进。读完本文你将掌握如何在一个 TanStack Start 应用中通过一条 catch-allsplat路由把 Mastra 实例的 REST、流式、自定义 API、MCP 与 A2A 端点全部对外暴露并理解适配器内部基于 Hono 的MastraServer机制及其鉴权、中间件行为。一、适配器定位一个路由点承载全部 Mastra 服务端能力mastra/tanstack-start的 README 开宗明义它通过 TanStack Start 服务端路由处理器暴露 Mastra 实例用于在同一个 TanStack Start 应用中对外提供 Mastra 的 REST、流式、自定义 API、MCP 和 A2A 端点。也就是说你不需要单独部署一个 Mastra 服务进程只需在既有 TanStack Start 应用里挂一个路由Mastra 的全部 HTTP 能力即随之就位。从 CHANGELOG 看该包诞生于0.2.0版本的一次 Minor 变更对应 PR #18270Addedmastra/tanstack-startserver adapter for mounting Mastra in TanStack Start apps via a catch-all server route. Uses the same Hono-based MastraServer pattern asmastra/next.这段记录说明了两个关键事实其一挂载方式是通过catch-all server routesplat 路由实现的其二它的底层沿用了与mastra/next一致的Hono 版 MastraServer模式——这解释了为什么它依赖mastra/hono与mastra/server见 package.json 的dependenciesmastra/server与mastra/hono均为 workspace 依赖。二、安装与最小接入安装只需一个命令同时装上 Hono peer 依赖npm install mastra/tanstack-start honopackage.json 中规定了运行时边界Node.js 版本要求22.13.0peer 依赖为mastra/core 1.50.0-0 2.0.0-0与hono ^4.12.8。最小接入方式是在src/routes/api/$.ts创建一个 splat 服务端路由import { createFileRoute } from tanstack/react-router; import { createStartRouteHandler } from mastra/tanstack-start; import { mastra } from ../../mastra; export const Route createFileRoute(/api/$)({ server: { handlers: createStartRouteHandler({ mastra }), }, });这里mastra是从src/mastra/index.ts导出的Mastra实例通常由mastra init初始化可包含 agents、tools、memory 等配置。createStartRouteHandler返回一个包含GET / POST / PUT / DELETE / PATCH / OPTIONS / HEAD全部七个 HTTP 方法处理器的对象正好满足 TanStack Startserver.handlers的签名要求。三、配置选项mastra、tools、prefixcreateStartRouteHandler的完整选项定义在 src/index.ts 的StartRouteHandlerOptions接口中选项类型默认值说明mastraMastra必填要对外提供的 Mastra 实例toolsToolsInput{}需要随服务端一起注册的工具prefixstring/apiAPI 路由前缀必须与 splat 路由的挂载路径一致其中prefix是最容易踩坑的选项。README 明确强调路由前缀与 splat 位置必须匹配如果路由文件是src/routes/api/$.ts则前缀保持默认的/api即可如果把路由挂到/api/mastra之下就必须显式传入相同前缀createStartRouteHandler({ mastra, prefix: /api/mastra, tools: { customTool }, });若不匹配适配器内部的 Hono 应用将无法正确解析路径请求会落在错误的路由段上。四、底层原理createStartRouteHandler 与 Hono 版 MastraServer阅读 src/index.ts 可以还原适配器的完整工作方式惰性初始化createStartRouteHandler内部维护一个appPromise首次请求到来时才调用initApp(mastra, tools, prefix)构建 Hono 应用并缓存从而保证模块级导出可以同步执行这在 TanStack Start 的服务端模块加载场景下很重要。统一处理器所有 HTTP 方法共享同一个handler内部只是app.fetch(request)——即把 TanStack Start 收到的标准Request原样转交给 Hono 应用处理再返回Response。MastraServer 装配initApp中创建一个新的Hono实例读取mastra.getServer()拿到服务端配置然后实例化MastraServer来自mastra/hono传入mastra、tools、taskStore、bodyLimitOptions、customRouteAuthConfig、customApiRoutes、prefix与mcpOptions。一次性 init最后调用await honoServerAdapter.init()这一调用完成上下文中间件、鉴权中间件、内建路由与自定义 API 路由的注册。值得注意的两个实现细节A2A 任务使用内存存储适配器创建了InMemoryTaskStore来自mastra/server/a2a/store意味着 A2A 任务状态不跨进程持久化重启即失效——这在 docs 框架指南 中同样有说明。请求体大小限制bodySizeLimit取自serverConfig?.bodySizeLimit ?? 4.5 * 1024 * 1024即默认约 4.5 MiB超限时onError返回{ error: Request body too large }。五、版本演进CHANGELOG 里的关键修复与变化CHANGELOG 完整记录了从0.2.0新增到0.2.25-alpha.3当前的版本轨迹。除去大量依赖版本对齐条目真正对本包功能有实质影响的变更集中在以下几处。5.1 中间件注册与公共路由鉴权修复0.2.18这是本包历史上最重要的一次功能修复对应 PR #22161、issue #21869。此前存在一个隐蔽缺陷通过server.middleware或在server配置中经mastra.setServerMiddleware()注册的中间件在通过服务端适配器而非mastra dev/mastra build提供时会被静默忽略。修复后的行为是以 Hono 为基础的适配器mastra/hono以及在其之上构建的mastra/next、mastra/tanstack-start会在init()期间注册已配置的中间件并保证与内建服务器相同的语义——用户中间件永远不会运行在声明为requiresAuth: false的公共路由上。同时修复了自定义路由声明requiresAuth: false但未被当作框架公共路由的问题当适配器从 Mastra 实例派生路由鉴权配置而非在构造时显式接收时公共路由也能被正确识别并豁免鉴权与用户中间件。这一保证在mastra/hono的测试中也有直接验证见 user-middleware.test.tsserver.middleware在自定义 API 路由上运行、但不在requiresAuth: false的框架公共路由上运行并在 auth-middleware.ts 中以requiresAuth开关实现。5.2 AgentController 命名统一0.2.10.2.1 引入了Harness→AgentController的重命名PR #18505mastra/core新增规范子路径mastra/core/agent-controllermastra/server的控制器会话 API 改为只在/agent-controller/...下提供。由于mastra/server是 tanstack-start 的依赖该重命名被同步传播到包括mastra/tanstack-start在内的全部服务端适配器同时mastra/core的 peer 依赖下限被抬高到1.47.0-0。这条记录对升级者是一个明确的兼容性提示。5.3 统一 schedules API 与 peer 依赖更新0.2.40.2.4 的变更内容是为统一的 schedules API 更新mastra/corepeer 依赖PR #18874。这类变更通常不引入新 API但要求使用方同步升级mastra/core属于跟着核心走的适配器常态。5.4 包体瘦身与文档改进0.2.22、0.2.230.2.22从分发到 npm 的文件中移除CHANGELOG.md以减小包体积同时更新 README 使其信息准确、及时。0.2.23将 Next.js 与 TanStack Start 适配器的 README 链接到各自的设置指南与 API 参考文档PR #22964。5.5 版本节奏与依赖对齐从 CHANGELOG 可以清晰看到适配器的版本节奏每个mastra/core/mastra/server/mastra/hono发布包括大量alpha.x预发布都会同步产生 tanstack-start 的对应Patch Changes。这正是适配器包跟随上游核心版本漂流的典型形态——功能面稳定主要变化来自底层依赖。截至本文最新版本为0.2.25-alpha.3对应的核心版本为mastra/core1.67.0-alpha.3。六、实战验证用 curl 测试天气 Agent按 docs 框架指南 的步骤完成mastra init初始化会在src/mastra下生成天气示例 agent、工具与配置并挂载适配器后启动应用npm run dev在另一个终端用 curl 调用天气 agent 的生成接口curl -X POST http://localhost:3000/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:What is the weather like in Seoul?}]}该端点会返回 agent 的完整 JSON 响应。注意这里的路径api/agents/...与默认前缀/api一致正是 splat 路由src/routes/api/$.ts捕获的请求。七、工程化配置Vite 与 Nitro 的 Node 依赖豁免Mastra 的依赖中包含 DuckDB 等 Node 原生模块直接进入 TanStack Start 的 Vite/Nitro 处理管线会出问题。框架指南给出两处vite.config.ts调整const config defineConfig({ resolve: { tsconfigPaths: true }, optimizeDeps: { exclude: [mastra/duckdb, execa], }, plugins: [ devtools(), - nitro({ rollupConfig: { external: [/^sentry\//] } }), nitro({ rollupConfig: { external: [/^sentry\//, /^duckdb\//], }, }),原理如下optimizeDeps.exclude中的mastra/duckdb防止 Vite 开发优化器把 DuckDB 的原生.node二进制当作 JavaScript 解析execa是mastra/core用于本地进程执行的仅服务端依赖其传递依赖npm-run-path、unicorn-magic使用了仅 Node 的条件导出浏览器构建优化器无法解析。Nitro 的rollupConfig.external增加/^duckdb\//把 DuckDB 的原生 Node 包排除在生产 bundle 之外由 Node.js 在运行时加载。这些改动只涉及vite.config.ts无需改动应用或 Mastra 源码。八、测试保障七个方法处理器与路由行为验证tanstack-start-adapter.test.ts 用 Vitest 覆盖了适配器的核心契约返回全部七个 HTTP 方法处理器GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD均为函数处理器返回Response对象GET /api返回 OpenAPI 规范或根响应状态码 500GET /api/agents正常返回响应未知路由如/api/nonexistent-route-xyz返回404支持自定义prefix如/custom-api与空tools。其中 404 测试直接验证了 Hono 应用路由穿透与未命中回退行为是理解splat 路由 Hono fetch链路的最直观样例。九、延伸阅读适配器包说明server-adapters/tanstack-start/README.md核心实现server-adapters/tanstack-start/src/index.ts单元测试server-adapters/tanstack-start/src/tests/tanstack-start-adapter.test.ts框架接入指南docs/src/content/en/integrations/frameworks/tanstack-start.mdx服务端适配器总览docs/src/content/en/docs/server/server-adapters.mdx服务端中间件说明docs/src/content/en/docs/server/middleware.mdx底层 Hono 适配器含中间件/鉴权实现与测试server-adapters/hono/src/index.ts、server-adapters/hono/src/tests/user-middleware.test.ts一句话总结mastra/tanstack-start是Mastra 服务端能力进 TanStack Start 应用的桥一条/api/$splat 路由 createStartRouteHandler({ mastra })即完成挂载其余所有复杂度Hono 装配、鉴权、中间件、MCP/A2A、体积限制都由其内部基于MastraServer的实现接管版本演进中的关键变更则集中在中间件注册修复、AgentController 重命名与依赖对齐之上。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考