Mastra 開源代理框架:一條指令長出帶記憶與工作流的代理

Mastra 是 Gatsby 背景團隊打造的開源 TypeScript AI 代理框架,一條指令就長出帶記憶、工作流與本機檔案操作的代理系統。本文實跑專案產生器並核對授權原始檔,攤開 ee/ 企業授權邊界、Gateway 按 token 計費路徑與遙測預設出口這三條導入前該看清的線。

用 AI 摘要這篇文章:

在乾淨目錄執行 npx create-mastra@latest my-mastra-app --llm openai,大約一分鐘後終端機顯示安裝成功,訊息只要求一件事:把 .env.example 複製成 .env 並填入 OPENAI_API_KEY。這條指令背後的框架是 Mastra,一個用 TypeScript 寫的 AI 代理開發框架,npm 上的專案產生器 create-mastra 前一天(2026 年 11 月 17 日)才剛改版到 1.40.0,核心套件 @mastra/core 同日已經推到 1.84.0。對於前端介面、資料庫存取與商業邏輯都跑在 Node.js 生態的團隊來說,這個框架想解決的問題很明確:代理、工作流、檢索與評測全部收進同一套型別檢查,不必為了 AI 層另外維護一套 Python 微服務。

不過把它當成單純的開源套件看待會漏看重點。這個專案背後是德拉瓦州的 Kepler Software 公司(對外品牌就叫 Mastra),官方網站列出的三位領導成員,執行長 Sam Bhagwat、技術長 Abhi Aiyer、產品長 Shane Thomas,在結構化資料裡都標註了 Gatsby 背景;GitHub 儲存庫在 2024 年 8 月建立,到 2026 年 11 月 18 日累積 29,574 顆星、3,110 次 fork,最近一次推送就在同一天。發布節奏也密:1.82.0 在 11 月 4 日、1.83.0 在 11 月 13 日,中間沒有停過週更。真正值得寫成一篇導入評估的,是它已經長出完整的商業結構:核心程式碼走 Apache 2.0,但劃出了明確的企業授權區,模型的付費閘道有自己的計費體系,遙測則有一條預設關閉的雲端出口。這三條線畫在哪裡,比功能清單更影響採用決策。

一條指令長出來的不是空殼,是完整的本機代理系統

先把實際跑出來的東西攤開。專案產生器選的範本叫 Agent Harness,安裝完成後專案目錄裡有幾個值得注意的產物。package.json 的依賴清單是 @mastra/core 1.84.0、@mastra/memory 1.41.2、@mastra/libsql 1.31.0、@mastra/duckdb 1.19.1、@mastra/observability 1.24.1 加上 zod,三個腳本指令 mastra dev、mastra build、mastra start 對應開發、建置與啟動。安裝過程還自動做了兩件事:在 .claude/skills 與 .agents/skills 底下裝了給 Claude Code 與 Codex 用的代理技能檔(mastra 與 mastra-factory 兩組),並對專案做了 git 初始化,第一個 commit 訊息寫著 Initial commit from Mastra。這個細節反映了框架對開發工作樣貌的判斷:官方文件開頭就建議使用本機編碼代理的開發者執行 npx skills add mastra-ai/skills 取得最新指引,專案產生器索性把這步做成自動,連 AGENTS.md 與 CLAUDE.md 兩份代理說明檔都一起放進專案。換句話說,它預設你不是徒手寫代理,而是帶著編碼代理一起寫。

範本裡的代理程式碼也不是示範用的 Hello World。src/mastra/agents/agent.ts 建了一個掛著本機工作區的通用助理:檔案系統走 LocalFilesystem、指令執行走 LocalSandbox,寫檔與編輯被設成 requireReadBeforeWrite(先讀才能寫),刪除檔案直接要求人工許可,另外掛了網頁抓取、網頁搜尋、詢問使用者三個內建工具,以及建立與停止排程的工具。儲存層在 src/mastra/index.ts 裡組成複合結構:預設走 LibSQL 存本機檔案 mastra.db,observability 這個域另外交給 DuckDB。執行 npm run dev 之後 Studio 介面顧名思義跑在本機 4111 埠,啟動時間約兩秒,沒有 API 金鑰也能開,只是代理呼叫會失敗。Studio 在開發階段是互動式的工作台,可以直接跟代理對話、逐步檢視工作流每個節點的輸入輸出、測試工具呼叫,底層的 REST API 另有 swagger 介面掛在 /swagger-ui 路徑下,前後串接時不用猜端點。官方文件在每頁開頭標明自己是唯一的當前參考、模型 ID 即時有效,要讀者信任文件勝過訓練資料,這對照著舊教學文章寫程式的人是省時間的設計。

本機執行的 Mastra Studio 介面,Agents 頁列出預設入門代理與其掛載的九個工具,側欄含 Workflows、Knowledge、Evaluation 與 ObservabilityPin
Mastra Studio 本機開發介面的 Agents 頁

這些預設值代表的方向值得停下來看:框架把「一個能操作本機檔案、會排程、有記憶的代理」當成出廠預設,而且把危險操作(刪除)的許可邏輯寫進範本。對照多數代理框架給一個空 agent 讓開發者自己組裝,Mastra 選的路線是把本機工作環境整個包進來。把多少環境控制權交給代理,是各種代理工作台共同的設計取捨,Browser Use 把瀏覽器引擎整併進代理的做法是同一個問題的另一種答案。想調整也行,這些全部是專案裡的原始碼,改掉權限設定不需要繞過框架。

授權邊界:ee/ 目錄不是 Apache 2.0

導入前最該先讀的檔案是儲存庫根目錄的 LICENSE.md,全文只有一千多字,結構卻很清楚。所有名為 ee/ 的目錄底下的程式碼,適用另外一份 Mastra Enterprise Edition License,其餘全部是 Apache License 2.0,著作權人是 Kepler Software, Inc.,這份企業授權目前是 2.0 版,生效日期 2026 年 9 月 22 日,也就是說才剛換版不到兩個月,正在評估的團隊拿到的是最新條款。

條款本身寫得直接。它明說企業功能是 source-available 而非開放原始碼:可以讀、可以建置、可以修改、可以測試,但禁止正式環境使用,也禁止再散布。正式環境的定義是開發與測試以外的任何使用,包括任何服務終端使用者、客戶或商業營運資料的情境;啟用企業功能需要 Kepler 發放的 License Key,這把鑰匙記錄授權範圍、用途與到期日。哪些功能被劃進企業區,LICENSE.md 點名三個套件路徑:@mastra/core/auth/ee、@mastra/core/agent-builder/ee 與 @mastra/editor/ee(清單非窮盡,儲存庫裡另有內部模組與範例專案的 ee 目錄)。實際翻儲存庫,packages/core/src/auth/ee/ 底下放的是精細授權檢查(fga-check)、授權金鑰驗證與遙測相關模組。

GitHub 上 mastra-ai/mastra 儲存庫的 LICENSE.md 檔案頁,載明 ee/ 目錄走企業授權、其餘內容適用 Apache License 2.0Pin
LICENSE.md 劃出 ee/ 目錄與 Apache 2.0 的授權邊界

對採用者的實際影響可以講得更白:代理、工作流、記憶、RAG、MCP 整合這些核心能力都不在企業區,中小團隊用 Apache 2.0 的部分就能走完開發到上線。但多租戶的精細授權這條線已經被劃進 ee,如果產品需要這類能力,不是自己用 Apache 2.0 的部分補寫,就是進入企業授權的洽談範圍;伺服器 API 的基本身分驗證仍留在 Apache 2.0 範圍內。另外要注意再散布的限制:把含 ee 程式碼的修改版提供給客戶或第三方,同樣在禁止之列。

模型路由與 Gateway:223 家供應商背後的計費路徑

模型介接的現況與多數人印象有段落差。官方文件目前的說法是單一 API 介接 223 家供應商、8,285 個模型(截至 2026 年 11 月 18 日),OpenAI、Anthropic、Google、xAI 這些主流之外,清單一路排到長尾的區域型供應商。網路上常見的「支援 40 家以上」是舊口徑,實際數字一年內膨脹了好幾倍,供應商覆蓋已經不是選型風險。模型在程式碼裡用字串指定,格式是 openai/gpt-6.1-sol 這種供應商加模型名,不用另外 import 供應商物件。

Mastra 官方文件的模型供應商頁,開頭載明透過單一 API 介接 223 家供應商共 8285 個模型Pin
官方文件 Model Providers 頁的供應商數量說明

計費路徑則藏在專案產生器的參數裡。--llm 接受五個值:openai、anthropic、google、xai 與 mastra。前四個是直連供應商,金鑰填自己的;選 mastra 走的是 Mastra Gateway,一支金鑰呼叫所有模型,模型呼叫按 token 從 Gateway 點數扣款,餘額為零時指令會引導去儀表板儲值並提供自動加值選項。Gateway 是框架官方經營的付費聚合層,對不想管理多把供應商金鑰的團隊方便,但成本結構從各供應商的直接計價換成點數制,導入前值得先算一筆帳。不想走這條路,在初始化時明確選其他供應商即可,直連路徑完全獨立。

遙測預設:追蹤留在本機,雲端匯出要 token 才會動

預設範本的 observability 設定適合逐行讀,因為它同時出現了三個角色:負責本機落地的 MastraStorageExporter、負責敏感資訊過濾的 SensitiveDataFilter,以及負責雲端匯出的 MastraPlatformExporter。前兩個的行為直觀,追蹤資料寫進本機的 DuckDB 儲存,跨出去前先過一層敏感資料過濾器。第三個則需要翻安裝後的套件原始碼才能確認行為:MastraPlatformExporter 初始化時讀取 MASTRA_PLATFORM_ACCESS_TOKEN 環境變數(相容舊名 MASTRA_CLOUD_ACCESS_TOKEN),讀不到就把自己停用,只在 debug 層級留一行紀錄;有 token 時,匯出端點預設是 observability.mastra.ai。

換句話說,這個框架的遙測預設是留在本機,雲端匯出屬於明確選擇後才會啟動的路徑。對照不少代理框架預設把追蹤送到雲端平台的設計,這條邊界對隱私敏感的場景友善。反過來說,團隊若決定接上 Mastra 平台,要知道代理呼叫的追蹤資料會流向官方的收集端點,SensitiveDataFilter 擋多少、放行多少,值得在接上之前自己審一遍過濾規則。

最近的改版方向:MCP 進了伺服器層

依官方 release notes 的說法(這部分未實測),1.83.0 在 11 月 13 日打包了幾個方向明確的更新。內建 MCP 端點是其中最有代表性的一條:@mastra/server 直接提供 /api/mcp 端點,只要設定了 server.auth 就預設開啟,MCP 客戶端可以直接呼叫代理、工作流與工具,不必自己定義 MCPServer,另外附帶 OAuth 探索與一個新的內省路由。可恢復的代理串流則開放給所有 Agent,用戶端斷線重連不會殺掉執行中的任務,提供 observe 與 abort 介面並強制所有權與存活時間檢查。工作流儲存的第二版(官方標為實驗性)改為差量寫入,只保存每步的變更而不是重寫整個執行紀錄,目前支援 Postgres 與 libSQL 兩種儲存後端。對前端整合有感的還有一條:聊天路由打開 resumable 選項後會生成對應的重連端點,Vercel AI SDK 的 useChat 勾上 resume 就能吃到這套可恢復機制,等於把斷線續傳從代理層一路接到 React 元件。

再往回一個版本,1.82.0 在 11 月 4 日把知識庫功能升級成頁面樹模型,頁、筆記與釘選構成第一級結構,讀取工具支援行級與區段級操作,外部內容可以透過伺服器端 API 同步進來。把兩個版本合起來看,改版重心放在兩件事:把代理產品化需要的基建(可恢復、可觀測、可對接)補進伺服器層,以及把知識與記憶的結構做深。這與前面企業授權區的劃分方向一致,框架在往平台化走。

工作流與記憶的語意細節

文件裡有兩處細節容易在導入時踩坑,需要單獨提出。工作流的編排語法是鏈式的 .then()、.parallel() 與 .branch(),分別處理順序、並行與條件分流,語意本身直觀,但 .branch() 有個容易被忽略的性質:所有條件都會被求值,所有為真的分支都會執行,一次執行可以走多條路。官方文件特別提醒,若要恰好走一條路,條件必須寫成互斥,而且不要在結尾掛無條件的 true 當作預設分支,否則它會與符合條件的分支一起跑。從提示詞控制流程遷移到程式碼控制的團隊,這個語意與直覺的「if else」不同,先讀懂再寫。

記憶系統分三層:訊息歷史、工作記憶與觀察式記憶(Observational Memory)。前兩層常見,第三層是這個框架的設計重點:背景代理持續把較舊的對話壓縮成觀察紀錄,用密集的觀察日誌取代原始訊息,讓上下文視窗保持小體積。代價官方也寫得明白,壓縮會失去精確措辭,被摘要捨棄的細節事後不一定找得回來;配套的 recall 回查工具預設關閉,要開啟需要額外設定,開了向量模式還需要自備向量庫與嵌入器。長對話場景要不要打開這層,取決於業務能不能接受措辭級的損失,這是資料面而非功能面的取捨。若三層記憶加總仍然超出模型的上下文上限,框架另外提供記憶處理器,在送出前過濾、刪減或排序內容,保住優先度最高的資訊。搭配工作流的暫停恢復機制,代理可以在等待人工放行的期間把整個執行狀態存進資料庫,放行後從中斷點繼續,這對有審核關卡的流程是實用的一塊,也是常駐代理把長時間工作拆成可恢復執行的同一套思路,工作流也支援排程執行,定期任務不用外掛 cron 另拼一層。

沒驗證的部分,與誰該現在進場

先把這篇的邊界講清楚:實際執行的部分只到專案產生器與範本原始碼的閱讀,代理的實際回答品質、工作流在真實負載下的效能、Studio 在長期專案的穩定度,都沒有測。與 Python 生態框架的優劣比較也刻意不做,那需要對稱的任務、負載與成本基準,只有單邊官方文件撐不起結論。版本與供應商數字全部以 2026 年 11 月 18 日為基準,這個專案每週都在改版,數字會漂。

決策建議可以收斂成三句話。技術堆疊已經壓在 TypeScript 與 Node.js 的團隊,需要把代理裝進既有後端而非另起 Python 服務,現在的 Mastra 值得認真試:入門成本一條指令,核心能力完整,授權邊界清楚。需要精細身分驗證與授權的產品,先確認那些功能落在企業授權區,把授權成本算進評估。重度依賴 PyTorch 本機推論或科學計算函式庫的團隊,留在 Python 生態仍然是務實選擇,這個框架解的問題不是你的問題。下一步很輕:npx create-mastra@latest 加一個供應商參數,五分鐘後你會有自己的判斷。

Sliven 褚崇名
Sliven 褚崇名

每日分享科技新知、免費資源以及 WordPress、虛擬主機相關主題,任何問題歡迎在科技月球下方留言,或是發送 Email 至 [email protected] 與我聯繫。

文章: 2553

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *


Share to...