深入理解 mastra/code-sdk用 mountAgentControllerOnMastra 构建自己的 AI 编程 Agent 服务【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra Code 是 Mastra 框架中的 AI 编程 Agent而其终端 UI 之外的「agent core」全部沉淀在 mastra/code-sdk 这个包中——mastra/code-sdk让你可以在自己的 Web 应用、编辑器或机器人里完整复用一个具备线程管理、模式mode、工具tools与记忆memory能力的编程 Agent 控制器。本文将围绕该包的入口 APImountAgentControllerOnMastra结合仓库源码讲解安装、挂载、配置项、底层组装流程与无头headless编程用法帮助你把 Mastra Code 的能力嵌入到自己的产品中。一、SDK 的定位除了 TUI 的一切mastra/code-sdk是 Mastra Code 的「agent core」——官方说明将其定义为「everything except the terminal UI」mastracode/sdk/README.md。已发布的mastracodeCLI/TUI 与 Mastra Code 的 Web 界面都构建在这套 SDK 之上mastracode/tui的入口 mastracode/tui/src/index.ts 只有一行export * from mastra/code-sdk说明终端 UI 是对 SDK 的薄封装Web 部署入口 mastracode/web/src/mastra/index.ts 则基于mastra/factory组装出可被mastra dev/mastra build/mastra deploy消费的Mastra实例其底层同样是该 SDK。因此理解了这个 SDK就同时理解了 CLI、TUI 与 Web 版背后的同一套编程 Agent 运行时。二、安装与最小挂载示例SDK 是标准的 npm 包安装命令见 mastracode/sdk/README.mdnpm install mastra/code-sdk从 package.json 可以看到它要求node 22.19.0是 ESM 包type: module对外导出dist/index.js并支持mastra/code-sdk/*子路径导入例如mastra/code-sdk/utils/project。最核心的用法是把 Mastra Code 的 Agent 控制器挂载到一个 Mastra 实例上对应 mastracode/sdk/README.md 的 Usage 示例即 mountAgentControllerOnMastra 的实现import { mountAgentControllerOnMastra } from mastra/code-sdk; // 创建一个承载 Mastra Code Agent 控制器的 Mastra 实例 // 线程管理、模式、工具、记忆并启动其 workers。 const { mastra, controller } await mountAgentControllerOnMastra({ cwd: process.cwd(), });这个调用会做三件事构建共享资源存储storage、可观测性observability、记忆memory、MCP、模型网关gateway、Agent 本体与各模式注册控制器把AgentController注册到服务器持有的 Mastra 上再调用controller.init()启动 workersmastra.startWorkers()并注册插件信号提供方与输入处理器见 finalize 的实现。两种挂载方式mountAgentControllerOnMastra接受两种用法源码注释明确区分见 index.ts不传mastraSDK 内部new Mastra(...)构造一个服务器 Mastra并让它拥有控制器的存储持久化集中在一处配置传入已有的mastra挂载到一个已经托管了其他原语agents、gateways、workflows 等的 Mastra 实例上实现多个组件共享同一个 Mastra 运行时。此时由调用方负责该 Mastra 上注册了哪些东西。无论哪种方式mountAgentControllerOnMastra都不会预创建会话session每个客户端浏览器或终端通过controller.createSession({ resourceId })创建/恢复自己隔离的会话因此一个服务器可以同时驱动多个并发用户。三、完整配置项MastraCodeConfig 逐项解析mountAgentControllerOnMastra的配置参数类型为MastraCodeConfig定义见 mastracode/sdk/src/index.ts#L242-L343下面是源码中带注释的全部配置项及其默认行为配置项类型默认值说明cwdstringprocess.cwd()项目检测的工作目录homeDirstringos.homedir()全局配置发现的主目录modesAgentControllerMode[]build/plan/fast三种覆盖模式模型 ID、颜色、存在哪些模式subagentsAgentControllerSubagent[]explore/plan/execute替换子代理定义传空数组可禁用子代理extraToolsRecord或(ctx) Record无合并进动态工具集的额外工具可以是同步对象也可以是接收requestContext的同步或异步函数postToolObserverPostToolObserver无观察已完成的工具调用但不替换/修改内置工具实现inputProcessorsInputProcessor[]无前置在 Mastra Code 强制处理器之前的无状态输入处理器可扩展处理但不能替换内置的安全与兼容性策略disabledToolsstring[]无从动态工具集中移除的工具名storageStorageConfig或MastraCompositeStore自动检测自定义存储配置或已构建的存储实例注入实例时原样使用不做连接测试、也无 LibSQL 回退——失败即硬错误storageBackendlibsql \| pg自动推断注入自定义存储实例时的后端标识对LibSQLStore/PostgresStore可自动推断其他实例必须显式传入vectorMastraVector自动创建预构建的向量存储实例用于 recall 搜索跳过默认创建omScopethread \| resource自动检测回退thread观察记忆的作用域settingsPathstring全局 settings自定义 settings.json 路径initialStatePartialMastraCodeState无初始状态覆盖yolo、thinkingLevel等hostInstructionsstring或(ctx) string无宿主指令在可变会话状态之外解析coAuthor{ name?, email? }core 默认提交共作者身份写入 coding-agent 提交指引idGenerator函数默认覆盖线程/消息 ID 生成主要用于确定性测试intervalHandlersIntervalHandler[]gateway-sync每 5 分钟覆盖周期处理器workspaceAgentControllerConfig[workspace]本地文件系统 本地沙箱覆盖工作区configDirstring.mastracode覆盖配置目录名会替换所有项目级与全局配置路径MCP、hooks、命令、数据库、skills、agent instructions中的.mastracodemcpServersRecordstring, McpServerConfig无编程式 MCP 服务器配置与文件配置合并且优先级更高disableMcpbooleanfalse禁用 MCP 服务器发现disableHooksbooleanfalse禁用 hooksdisablePluginsbooleanfalse禁用插件发现/加载disableGithubSignalsbooleanfalse即使全局设置启用也禁用轮询式 GitHub 信号disableSettingsOmSeedbooleanfalse跳过从 settings.json 播种观察记忆旋钮observer/reflector 模型、阈值等服务器部署把记忆设置持久化在自己的数据库中时使用防止宿主机 TUI 设置泄漏进服务器会话pluginManagerPluginManager默认新建覆盖插件管理器主要用于测试或嵌入memory记忆实例或工厂或falsegetDynamicMemory(storage, vector)覆盖传给 AgentController 的记忆实例传false完全禁用browser浏览器配置无浏览器自动化工具提供方设置后 Agent 获得浏览器工具pubsubPubSub无信号路由的 PubSub跨进程 PubSub 开启时禁用线程锁unixSocketPubSubboolean全局设置使用内置 Unix socket PubSub 做本地跨进程信号路由Windows 上忽略crossProcessPubSubboolean派生标记 PubSub 为跨进程安全跳过文件线程锁要求必须提供 pubsub 实例否则抛错agentConnectionsAgentConnectionsSignalProviderOptions无Agent 连接状态与发现选项crossAgentSignalsboolean全局signals.experimentalCrossAgentSignals默认关启用实验性跨 Agent 通信线程所有权广播、对等发现与 agent connection 工具需要注意的默认行为yolo默认开启控制器initialState中yolo: true见 AgentController 构造随后才被全局设置和你的initialState覆盖。yolo决定工具审批策略requireToolApproval: state.yolo ! true。thinkingLevel不会被播种进会话状态源码注释说明该状态槽是会话级覆盖实际生效级别在请求时解析per-mode 默认 → 全局偏好因此修改设置后下一次请求即可生效见 index.ts。configDir优先级最高在initialState合并中总是最后写入保证与已初始化的 MCP/hooks/storage 保持同步。观察记忆旋钮的播种默认从 settings.json 播种 observer/reflector 模型、观测/反思阈值、caveman 观测与附件观测测试见 index.test.ts 的 settings.json OM seeding 组disableSettingsOmSeed可整体跳过。四、源码中的内部组装流程mountAgentControllerOnMastra的底层实现分成两层createMastraCodeAgentController构建所有共享资源与「惰性」控制器与prepareAgentControllerMountmountAgentControllerOnMastra负责挂载、init 与启动。从 index.ts 可以梳理出完整的启动流水线环境准备加载 cwd 下的.env创建AuthStorage并把同一实例注入 Claude Max / OpenAI Codex / GitHub Copilot / Kimi / xAI 等 OAuth 能力提供方createAuthStorage测试见 createAuthStorage 用例把已存储的 API key 灌入process.env已存在的环境变量优先且存在租户凭据存储时跳过避免泄入进程全局环境。项目检测detectProject(cwd)得出根路径、git 分支、resourceId通过 sha256 前 12 位短哈希生成稳定且与 cwd 绑定的会话 IDmastracode-session-hash与机器绑定的 ownerIdmastracode-hash——同一项目多次调用得到相同的 ID见 index.test.ts 的 id/ownerId 用例。存储与可观测性根据配置或自动检测创建MastraCompositeStore默认域 可选的 DuckDB observability 域 内存 harness 域本地 tracing 通过/observability local on开启否则 observability 域整体禁用避免 trace 数据落进默认 libsql 库。观测性默认的requestContextKeys白名单只记录线程/资源/模型/状态等元数据防止控制器大对象泄漏进 span。MCP / Hooks / 插件分别创建McpManager、HookManager、PluginManager插件加载后其工具会并入各模式的 availableTools 白名单addPluginToolsToModeAllowlists。评分器scorers注册 outcome 评分器samplingnone与 efficiency 评分器sampling ratio 0.3。Agent 组装createCodingAgent构建code-agent挂载动态模型解析、动态工具工厂合并 MCP 工具、extraTools、禁用列表、插件工具、hooks、信号提供方任务信号、可选 agent-connections、可选 GitHub 信号、原生 goal 机制judge 模型 文件系统验证工具以及多层处理器输入、输出、错误。模式与子代理默认三种模式 build绿/ plan紫/ fast橙子代理 explore→fast、plan→plan、execute→build 映射各自默认模型disabledTools会同时过滤子代理允许的工具。控制器构造new AgentController({ ... })传入存储、可观测性、记忆、PubSub、工作区工厂、初始状态、周期处理器与模型用量统计。挂载与启动mountAgentControllerOnMastra先注册控制器再init()注册先于 init 是控制器继承服务器 Mastra 的存储/agents/gateways 的关键而非自建内部 Mastra随后startWorkers()并注册配置化处理器与插件信号提供方。源码注释还明确梳理了三种接线方式见 index.tsServer Web控制器注册在服务器 Mastra 上并 init每个浏览器客户端通过 HTTP 各自 mint 会话Server TUI同样的服务器组合TUI 驱动一个进程内会话远程传输是未来工作Local TUIbootLocalAgentController即历史别名createMastraCode让控制器在init()时自建内部 Mastra并为整个进程 mint 一个 eager 会话。五、挂载后能拿到什么mountAgentControllerOnMastra返回MountedMastraCodeMastraCodeAgentController { mastra: Mastra }。除了mastra与controller还暴露了一批共享句柄见 createMastraCodeAgentController 的返回值storage/storageMaintenance存储与/prune维护句柄observability/memory/mcpManager/hookManager/pluginManagercreateKnowledgeInspector(session)知识域检查器signalsPubSub、authStorage、resolveModel、builtinPacks/builtinOmPacks/effectiveDefaultssessionId/ownerId本地单会话Case 3的身份服务器忽略它们改为按请求用客户端提供的 resourceId mint 会话codeAgent把code-agent注册为普通 agent 供 workflow 组合agentId: code-agentsetActiveSession、startPluginSignalProviders/stopPluginSignalProviders、registerConfiguredProcessorsWithMastra供组合层在 init 之后按需调用。六、构建自己的 UI/服务无头headless编程接口README 的核心意图是「build your own UIs and surfaces」。SDK 为此提供了mastracode/headless子路径的程序化 API见 headless/index.ts它是 CLI 与 TUI 之上「process-free」的纯运行器import { createMastraCode } from mastracode; import { runMC } from mastracode/headless; const { controller, session } await createMastraCode({ settingsPath }); // runMC 是异步可迭代的既可流式消费事件也可直接取结果 const run runMC({ controller, session, prompt: 修复这个 bug }); for await (const event of run) { // 实时观察 message_end / tool_start / tool_end / usage_update / error 等事件 } const result await run.result; // 类型化 RunMCResult console.log(result.text, result.exitCode);关键设计见 run-mc.ts 与 types.tsrunMC不触碰process.*、从不调用process.exit可安全嵌入 CI 或 Node 服务只有 CLI 适配层runMCCli才负责 argv/stdin/退出码。返回的MCRun既是AsyncIterableAgentControllerEvent又通过resultresolve 出聚合后的RunMCResult含text、finishReason、usage、toolCalls、toolResults、threadId、exitCode等事件缓冲有界默认 10000只取结果不迭代也不会无限积压。ResolutionPolicy控制审批/挂起onToolApproval返回approve | denyonSuspension返回resumeData或{ abort: true }内置autoApprovePolicy全部放行默认与denyPolicy全部拒绝另有permissionModeToPolicy把auto | deny权限模式映射为策略。运行选项modebuild/plan/fast、model显式模型覆盖、thinkingLeveloff/low/medium/high/xhigh/max、thread按 id 恢复 /continueLatest/clone克隆线程、timeoutMs超时 → exitCode 2、maxTurns达到上限 →max_turnsexitCode 1、signal外部 AbortSignal、goal运行持久化目标而非普通 prompt。格式器formatHuman/formatJsonl/renderTextResult/renderJsonResult是纯函数、与 sink 无关便于你接到自己的渲染层。CLI 适配层的流程见 cli.ts就是「解析 argv →createMastraCode→runMC→ 格式器渲染 → 映射退出码 → 清理线程锁并process.exit」你的自定义 UI 可以完全复用其中除进程 IO 之外的所有部分。七、把控制器接进服务器buildApiRoutes 与多会话模型mountAgentControllerOnMastra还支持两个面向服务端组合的高级参数定义见 index.tsbuildApiRoutes({ controller, authStorage })为服务器 Mastra 组装 API 路由buildServerConfig({ controller, authStorage })折叠额外的server配置middleware、cors等到构造的 Mastra 上仅在 SDK 自建 Mastra 时生效传入已有mastra时被忽略。另外prepareAgentControllerMount把「构造new Mastra(...)的参数」与「post-construct 的finalize()启动步骤」分离返回见 index.ts这保证了部署器deployer的checkConfigExportBabel 插件能在入口文件里找到顶层new Mastra(...)导出——Web 平台入口 mastracode/web/src/mastra/index.ts 正是利用这一设计。对于服务器场景每个客户端应通过controller.createSession({ resourceId })创建自己的会话session 是隔离的一个控制器进程可以服务多个并发用户若使用unixSocketPubSub或跨进程 PubSub则同一项目可跨进程共享信号同时线程锁会被跳过以保证并发一致性。八、扩展性与测试保障插件系统PluginManager支持技能skills、命令commands、指令instructions与信号提供方插件提供的工具会并入各模式的工具白名单处理器通过PluginSignalLane在请求间动态插拔启用/禁用/更新插件无需重建 Agent。MCP 集成支持文件配置 编程式mcpServers合并工具经createDynamicTools汇入模型可见工具集。健壮性全局重试策略StreamErrorRetryProcessor对瞬时连接错误ECONNRESET/EPIPE、socket hang up与服务器错误500/502/503做指数退避重试初始 500ms、上限 30s、最多 10 次并通过emitTransientRetry向控制器发出可重试事件见 index.tsProviderHistoryCompat在重试前先修复不兼容的历史如工具调用 ID 清洗。测试覆盖核心启动流程、settings 播种、跨进程信号、工具审批、配置目录名校验等均有 vitest 用例见 mastracode/sdk/src/tests/ 与各模块目录下的__tests__例如 index.test.ts、tool-approval-libsql.test.ts、cross-process-agent-signals.integration.test.ts。九、小结mastra/code-sdk把 Mastra Code 的编程 Agent 运行时完整地抽象为一个可嵌入的AgentController通过mountAgentControllerOnMastra一条调用即可在自有 Mastra 上获得线程管理、三种模式、动态工具、记忆与多会话支持通过createMastraCoderunMCmastracode/headless则可在 CI、Web 服务或自定义 UI 中程序化驱动编程 Agent。CLI/TUI 与官方 Web 界面本身都构建在这套 SDK 之上这意味着你自己的「surface」与官方产品拥有完全一致的底层能力。更多版本历史见 mastracode/sdk/CHANGELOG.md完整参考文档可从 mastracode/sdk/README.md 进入。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考