企业官网建设流程全解析

深入理解 @mastra/code-sdk：用 mountAgentControllerOnMastra 构建自己的 AI 编程 Agent 服务

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

Mastra 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.md：

npm 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(), });

这个调用会做三件事：

1. 构建共享资源：存储（storage）、可观测性（observability）、记忆（memory）、MCP、模型网关（gateway）、Agent 本体与各模式；
2. 注册控制器：把AgentController注册到服务器持有的 Mastra 上，再调用controller.init()；
3. 启动 workers：mastra.startWorkers()，并注册插件信号提供方与输入处理器（见 finalize 的实现）。

两种挂载方式

mountAgentControllerOnMastra接受两种用法（源码注释明确区分，见 index.ts）：

• 不传mastra：SDK 内部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），下面是源码中带注释的全部配置项及其默认行为：

需要注意的默认行为

• 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（构建所有共享资源与「惰性」控制器）与prepareAgentControllerMount+mountAgentControllerOnMastra（负责挂载、init 与启动）。从 index.ts 可以梳理出完整的启动流水线：

1. 环境准备：加载 cwd 下的.env；创建AuthStorage并把同一实例注入 Claude Max / OpenAI Codex / GitHub Copilot / Kimi / xAI 等 OAuth 能力提供方（createAuthStorage，测试见 createAuthStorage 用例）；把已存储的 API key 灌入process.env（已存在的环境变量优先，且存在租户凭据存储时跳过，避免泄入进程全局环境）。
2. 项目检测：detectProject(cwd)得出根路径、git 分支、resourceId；通过 sha256 前 12 位短哈希生成稳定且与 cwd 绑定的会话 ID（mastracode-session-<hash>）与机器绑定的 ownerId（mastracode-<hash>）——同一项目多次调用得到相同的 ID（见 index.test.ts 的 id/ownerId 用例）。
3. 存储与可观测性：根据配置或自动检测创建MastraCompositeStore（默认域 + 可选的 DuckDB observability 域 + 内存 harness 域）；本地 tracing 通过/observability local on开启，否则 observability 域整体禁用，避免 trace 数据落进默认 libsql 库。观测性默认的requestContextKeys白名单只记录线程/资源/模型/状态等元数据，防止控制器大对象泄漏进 span。
4. MCP / Hooks / 插件：分别创建McpManager、HookManager、PluginManager，插件加载后其工具会并入各模式的 availableTools 白名单（addPluginToolsToModeAllowlists）。
5. 评分器（scorers）：注册 outcome 评分器（samplingnone）与 efficiency 评分器（sampling ratio 0.3）。
6. Agent 组装：createCodingAgent构建code-agent，挂载动态模型解析、动态工具工厂（合并 MCP 工具、extraTools、禁用列表、插件工具）、hooks、信号提供方（任务信号、可选 agent-connections、可选 GitHub 信号）、原生 goal 机制（judge 模型 + 文件系统验证工具）以及多层处理器（输入、输出、错误）。
7. 模式与子代理：默认三种模式 build（绿）/ plan（紫）/ fast（橙），子代理 explore→fast、plan→plan、execute→build 映射各自默认模型；disabledTools会同时过滤子代理允许的工具。
8. 控制器构造：new AgentController({ ... })传入存储、可观测性、记忆、PubSub、工作区工厂、初始状态、周期处理器与模型用量统计。
9. 挂载与启动：mountAgentControllerOnMastra先注册控制器再init()（注册先于 init 是控制器继承服务器 Mastra 的存储/agents/gateways 的关键，而非自建内部 Mastra），随后startWorkers()并注册配置化处理器与插件信号提供方。

源码注释还明确梳理了三种接线方式（见 index.ts）：

1. Server + Web：控制器注册在服务器 Mastra 上并 init，每个浏览器客户端通过 HTTP 各自 mint 会话；
2. Server + TUI：同样的服务器组合，TUI 驱动一个进程内会话（远程传输是未来工作）；
3. Local + TUI：bootLocalAgentController（即历史别名createMastraCode）让控制器在init()时自建内部 Mastra，并为整个进程 mint 一个 eager 会话。

五、挂载后能拿到什么

mountAgentControllerOnMastra返回MountedMastraCode（MastraCodeAgentController & { mastra: Mastra }）。除了mastra与controller，还暴露了一批共享句柄（见 createMastraCodeAgentController 的返回值）：

• storage/storageMaintenance：存储与/prune维护句柄；
• observability/memory/mcpManager/hookManager/pluginManager；
• createKnowledgeInspector(session)：知识域检查器；
• signalsPubSub、authStorage、resolveModel、builtinPacks/builtinOmPacks/effectiveDefaults；
• sessionId/ownerId：本地单会话（Case 3）的身份；服务器忽略它们，改为按请求用客户端提供的 resourceId mint 会话；
• codeAgent：把code-agent注册为普通 agent 供 workflow 组合（agentId: 'code-agent'）；
• setActiveSession、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.ts）：

• runMC不触碰process.*、从不调用process.exit，可安全嵌入 CI 或 Node 服务；只有 CLI 适配层runMCCli才负责 argv/stdin/退出码。
• 返回的MCRun既是AsyncIterable<AgentControllerEvent>，又通过resultresolve 出聚合后的RunMCResult（含text、finishReason、usage、toolCalls、toolResults、threadId、exitCode等）；事件缓冲有界（默认 10000），只取结果不迭代也不会无限积压。
• ResolutionPolicy控制审批/挂起：onToolApproval返回approve | deny，onSuspension返回resumeData或{ abort: true }；内置autoApprovePolicy（全部放行，默认）与denyPolicy（全部拒绝），另有permissionModeToPolicy把'auto' | 'deny'权限模式映射为策略。
• 运行选项：mode（build/plan/fast）、model（显式模型覆盖）、thinkingLevel（off/low/medium/high/xhigh/max）、thread（按 id 恢复 /continueLatest/clone克隆线程）、timeoutMs（超时 → exitCode 2）、maxTurns（达到上限 →max_turns，exitCode 1）、signal（外部 AbortSignal）、goal（运行持久化目标而非普通 prompt）。
• 格式器：formatHuman/formatJsonl/renderTextResult/renderJsonResult是纯函数、与 sink 无关，便于你接到自己的渲染层。

CLI 适配层的流程（见 cli.ts）就是「解析 argv →createMastraCode→runMC→ 格式器渲染 → 映射退出码 → 清理线程锁并process.exit」，你的自定义 UI 可以完全复用其中除进程 IO 之外的所有部分。

七、把控制器接进服务器：buildApiRoutes 与多会话模型

mountAgentControllerOnMastra还支持两个面向服务端组合的高级参数（定义见 index.ts）：

• buildApiRoutes({ 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.ts）；ProviderHistoryCompat在重试前先修复不兼容的历史（如工具调用 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 上获得线程管理、三种模式、动态工具、记忆与多会话支持；通过createMastraCode+runMC（mastracode/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