export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  scorers: { ... },
  storage: new MastraCompositeStore({ ... }),
  logger: new PinoLogger({ ... }),
  observability: new Observability({ ... }),
});

                  ┌─────────────────────────────────────┐
                  │           Mastra 实例 (index.ts)      │
                  │  注册 agents/workflows/tools/scorers  │
                  └───────────────┬─────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
   ┌─────────┐             ┌───────────┐             ┌───────────┐
   │  Agent  │             │ Workflow  │             │  Scorer   │
   │ model + │  then()     │ step 链    │   评估       │ 4 步流水线 │
   │ tools + │ ──────►     │ schema 流转│ ◄──────────  │           │
   │ memory  │             │           │              └───────────┘
   └────┬────┘             └─────┬─────┘
        │                        │
        ▼                        ▼
   ┌─────────────────────────────────────┐
   │            Storage (Composite)        │
   │  LibSQL(default) + DuckDB(observ)    │
   └─────────────────────────────────────┘
        ▲                        ▲
        │                        │
   ┌────┴────┐             ┌─────┴─────┐
   │ Logger  │             │Observability│
   │  Pino   │             │ span+export│
   └─────────┘             └───────────┘

model: "provider/model-id"
// "openai/gpt-5.5"
// "anthropic/claude-sonnet-4-6"
// "deepseek/deepseek-v4-flash"

{
  "apiKeyEnvVar": "OPENAI_API_KEY",
  "name": "OpenAI",
  "models": ["gpt-5.5", "gpt-4o"],
  "gateway": "models.dev",
  "npm": "@ai-sdk/openai"
}

"deepseek/deepseek-v4-flash"
   │ parseModelString()
   ▼
{ provider:"deepseek", modelId:"deepseek-v4-flash" }
   │ getProviderConfig("deepseek")
   ▼
{ apiKeyEnvVar:"DEEPSEEK_API_KEY", gateway:"models.dev", npm:"@ai-sdk/deepseek" }
   │ Gateway.resolveLanguageModel()
   ▼
AI SDK LanguageModel 实例 → 供 Agent 推理

model: "openai/gpt-5.5"   // 走 Provider Registry

model: { id: "my/model", url: "https://.../v1", apiKey: "..." }
// 或
model: { providerId: "x", modelId: "y", url: "...", apiKey: "..." }

import { createOpenAI } from "@ai-sdk/openai";
model: createOpenAI({ apiKey })("gpt-5.5")

model: ({ runtime }) => runtime.userPlan === "pro" ? "openai/gpt-5.5" : "openai/gpt-5-mini"

model: [
  { model: "openai/gpt-5.5", retries: 2 },
  { model: "anthropic/claude-sonnet-4-6", retries: 1 },
]

await agent.generate("...", { model: "anthropic/claude-sonnet-4-6" });

new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: "...",                    // SystemMessage | string[] | 函数
  model: "deepseek/deepseek-v4-flash",
  tools: { weatherTool },
  memory: new Memory(),
  scorers: { ... },
  maxSteps: 5,
})

// generate：一次性
const res = await agent.generate("北京天气？");
const text: string = res.text;

// stream：流式
const out = await agent.stream("北京天气？");
for await (const chunk of out.textStream) { process.stdout.write(chunk); }
const full = await out.getFullOutput();   // 等价 generate 返回值

{
  text: string,            // 全部 step 文本拼接
  toolCalls: ToolCallChunk[],
  toolResults: ToolResultChunk[],
  usage: LanguageModelUsage,
  totalUsage: LanguageModelUsage,
  finishReason: string,
  steps: LLMStepResult[],  // 每步详情
  object: OUTPUT,          // structuredOutput 结果
  messages: MastraDBMessage[],
  error: Error | undefined,
  runId, traceId, spanId,
}

textStream       ReadableStream<string>          实时文本
fullStream       ReadableStream<ChunkType>        全部 chunk（含 tool_call 等）
objectStream     ReadableStream<Partial<OUTPUT>>  structuredOutput 增量
elementStream    ReadableStream<T>                数组输出逐元素
text             Promise<string>                  流结束后完整文本
object           Promise<OUTPUT>
toolCalls        Promise<ToolCallChunk[]>
usage            Promise<LanguageModelUsage>
getFullOutput()  Promise<FullOutput>              等价 generate 返回

用户提问
  ↓ Agent 依 instructions + tool.description + inputSchema 判断
模型生成工具参数
  ↓ Mastra 按 inputSchema 校验
execute() 运行
  ↓ 返回 outputSchema 声明的结构
结果回模型 → 自然语言回答

import { createTool } from '@mastra/core/tools';
createTool({
  id: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({ location: z.string().describe('City name') }),
  outputSchema: z.object({ temperature: z.number(), /* ... */ }),
  execute: async (inputData) => { return await getWeather(inputData.location); },
});

new Agent({ /* ... */ tools: { weatherTool } });

// Tool
execute: async (inputData) => {}

// Workflow Step
execute: async ({ inputData, mastra, getStepResult, getInitData,
                  suspend, resumeData, state, setState, requestContext }) => {}

const mcp = new MCPClient({
  servers: { weather: { url: new URL('http://localhost:8080/mcp') } },
});

// 静态注册
new Agent({ /* ... */ tools: await mcp.listTools() });

// 动态传入
agent.stream('...', { toolsets: await mcp.listToolsets() });

ScorerRun { input, output }
   │ ① preprocess()    提取/转换数据
   ▼
   │ ② analyze()       LLM 分析（可选）
   ▼
   │ ③ generateScore()  输出 0-1 分数
   ▼
   │ ④ generateReason() 输出可读解释
   ▼
{ score: number, reason: string }

// 工具调用准确性
createToolCallAccuracyScorerCode({
  expectedTool: 'weatherTool',
  strictMode: false,   // true → 仅允许调指定工具
})

// 回答完整性（LLM 判断）
createCompletenessScorer()

createScorer({
  id: 'translation-quality-scorer',
  type: 'agent',
  judge: { model: 'openai/gpt-5-mini', instructions: '...' },
})
  .preprocess(({ run }) => ({
    userText: getUserMessageFromRunInput(run.input) || '',
    assistantText: getAssistantMessageFromRunOutput(run.output) || '',
  }))
  .analyze({
    outputSchema: z.object({
      nonEnglish: z.boolean(),
      translated: z.boolean(),
      confidence: z.number().min(0).max(1),
    }),
    createPrompt: ({ results }) => `分析 ${results.preprocessStepResult.userText}...`,
  })
  .generateScore(({ results }) => {
    const r = results.analyzeStepResult;
    if (!r.nonEnglish) return 1;
    if (r.translated) return 0.7 + 0.3 * r.confidence;
    return 0;
  })
  .generateReason(({ results, score }) => `...score=${score}`);

new Agent({
  scorers: {
    translation: {
      scorer: translationScorer,
      sampling: { type: "ratio", rate: 1 },   // 100%
    },
  },
})

storage: new MastraCompositeStore({
  id: 'composite-storage',
  default: new LibSQLStore({ url: "file:./mastra.db" }),
  domains: {
    observability: await new DuckDBStore().getStore('observability'),
  },
}),

domains 显式指定 > editor 快捷方式 > default 默认

logger: new PinoLogger({ name: 'Mastra', level: 'info' })

observability: new Observability({
  configs: {
    default: {
      serviceName: 'mastra',
      exporters: [
        new MastraStorageExporter(),     // 写本地存储
        new MastraPlatformExporter(),    // 发 Mastra 平台（需 MASTRA_PLATFORM_ACCESS_TOKEN）
      ],
      spanOutputProcessors: [
        new SensitiveDataFilter(),       // 脱敏：密码/token/key
      ],
    },
  },
}),

Agent/Workflow 执行
   │ 生成 span（每步 LLM 调用、工具调用）
   ▼
spanOutputProcessors（脱敏/过滤）
   │
   ├── MastraStorageExporter  → DuckDB/LibSQL（本地）
   └── MastraPlatformExporter → Mastra 平台
   ▼
Studio Tracing 面板查看调用链