# 1. 安装 Node.js 22.13+（winget 或官网安装包）
winget install OpenJS.NodeJS.LTS

# 2. 创建 Mastra 项目
npm create mastra@latest

# 3. 按交互提示输入项目名与模型提供商（openai / anthropic / google / xai）

# 4. 进入项目并启动 dev server
cd my-mastra-app
npm run dev
# 打开 http://localhost:4111 使用 Studio

# 1. Node 22.13+（nvm 示例）
nvm install 22 && nvm use 22

# 2. 推荐方式：脚手架创建项目（会安装 Mastra skills、按需初始化 Git）
npm create mastra@latest
# pnpm / Yarn / Bun 同理：pnpm create mastra@latest 等
# 也可直接指定提供商：npm create mastra@latest my-app -- --llm openai

# 3. 进入项目并启动
cd my-mastra-app
npm run dev

# 在既有 Node/TS 项目中安装核心包
npm install @mastra/core @mastra/libsql
npm install -D mastra          # mastra CLI（dev/build/deploy 命令）
npm install zod                # schema 定义

npx mastra dev    # 本地开发服务器 + Studio（默认 http://localhost:4111）
npx mastra build  # 生产构建

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build       # 内部执行 mastra build
EXPOSE 4111
CMD ["node", ".mastra/output/index.mjs"]

docker build -t my-mastra-app .
docker run -d -p 4111:4111 --env-file .env --name mastra-app my-mastra-app

# Vercel（官方内置 deployer）
npx mastra deploy vercel
# Cloudflare
npx mastra deploy cloudflare
# Netlify
npx mastra deploy netlify

git clone https://github.com/mastra-ai/mastra.git
cd mastra
# 参考仓库 DEVELOPMENT.md 安装依赖并运行测试

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { testAgent } from './agents/test-agent'
import { testWorkflow } from './workflows/test-workflow'

export const mastra = new Mastra({
  // 注册 Agent 与 Workflow
  agents: { testAgent },
  workflows: { testWorkflow },

  // 持久化存储：本地用 LibSQL 文件库；生产换 PostgresStore
  // 注意：与 mastra dev 同库时使用绝对路径
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:/absolute/path/to/your/project/mastra.db',
  }),
})

import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL,
  }),
  // ...agents / workflows
})

npm run dev          # 开发模式，启动 mastra dev（Studio 默认 http://localhost:4111）
npx mastra build     # 生产构建
npm run start        # 启动构建产物（以项目 package.json 实际脚本为准）

# /etc/systemd/system/mastra-app.service
[Unit]
Description=Mastra App Server
After=network-online.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/opt/mastra-app
EnvironmentFile=/opt/mastra-app/.env
ExecStart=/usr/bin/node .mastra/output/index.mjs
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mastra-app
journalctl -u mastra-app -f

# PM2（Node 生态常用）
npm install -g pm2
pm2 start .mastra/output/index.mjs --name mastra-app
pm2 startup && pm2 save      # 开机自启

services:
  mastra-app:
    build: .
    restart: unless-stopped
    ports:
      - "4111:4111"
    env_file: .env
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

server {
  listen 443 ssl;
  server_name mastra.example.com;
  location / {
    proxy_pass http://127.0.0.1:4111;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;      # 支持流式/WebSocket
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }
}

import { Agent } from '@mastra/core/agent'

export const testAgent = new Agent({
  id: 'test-agent',
  name: 'Test Agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-4o',   // 格式：'provider/model-name'，模型目录见 mastra.ai/models
})

const agent = mastra.getAgentById('test-agent')
const response = await agent.generate('Help me organize my day')
console.log(response.text)

// Anthropic（需 ANTHROPIC_API_KEY）
model: 'anthropic/claude-sonnet-4-5'
// Grok / xAI（需 XAI_API_KEY）
model: 'xai/grok-3'
// Ollama 本地模型（无需云端 Key，按模型路由文档配置本地端点）
// Google Gemini（需 GOOGLE_GENERATIVE_AI_API_KEY）
model: 'google/gemini-2.5-pro'

import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'

const step1 = createStep({
  id: 'step-1',
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ formatted: z.string() }),
  execute: async ({ inputData }) => ({
    formatted: inputData.message.toUpperCase(),
  }),
})

export const testWorkflow = createWorkflow({
  id: 'test-workflow',
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ output: z.string() }),
})
  .then(step1)     // 串联；还可用 .branch()/.parallel()/.dowhile() 等控制流
  .commit()        // 结束定义

// 运行
const run = await testWorkflow.createRun()
const result = await run.start({ inputData: { message: 'Hello world' } })
if (result.status === 'success') console.log(result.result)

// 本地：LibSQL 文件库
import { LibSQLStore } from '@mastra/libsql'
storage: new LibSQLStore({ id: 's', url: 'file:./mastra.db' })

// 生产：PostgreSQL
import { PostgresStore } from '@mastra/pg'
storage: new PostgresStore({ id: 's', connectionString: process.env.DATABASE_URL })

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number() }),
  execute: async ({ inputData }) => ({ temp: 25 }),   // 替换为真实 API 调用
})

// 在 Agent 中挂载
new Agent({ id: 'a', name: 'A', instructions: '...', model: 'openai/gpt-4o', tools: { weatherTool } })

npm ls @mastra/core mastra
npx mastra --version       # CLI 版本（以官方命令输出为准）

# 升级核心包与 CLI
npm install @mastra/core@latest @mastra/libsql@latest
npm install -D mastra@latest

# 脚手架项目可用官方文档指引的 npx 命令更新依赖
npx npm-check-updates -u '@mastra/*' && npm install

npm install @mastra/core@1.78.0    # 回到指定版本
git checkout <上一个正常 tag/commit> # 项目代码配合回滚

# 1. 卸载 npm 依赖
npm uninstall @mastra/core @mastra/libsql mastra

# 2. 删除项目
rm -rf my-mastra-app

# 3. 清理本地数据
rm -f mastra.db            # LibSQL 本地库
docker compose down -v     # 若使用 Docker Compose，含 Postgres 卷

# 4. 清理环境变量与全局工具
# 从 .env / 系统环境中移除 OPENAI_API_KEY、DATABASE_URL 等
npm uninstall -g pm2       # 若安装了 PM2

# ===== 初始化 =====
npm create mastra@latest                 # 脚手架创建项目
npm create mastra@latest my-app -- --llm openai   # 指定提供商
npm install @mastra/core @mastra/libsql  # 手动集成
npm install -D mastra zod

# ===== 开发 =====
npm run dev                              # 启动 mastra dev（Studio: http://localhost:4111）
npx mastra build                         # 生产构建
npx mastra deploy vercel                 # 部署到 Vercel（cloudflare / netlify 同理）

# ===== 调用 =====
# agent.generate('...') / agent.stream('...')        # 直接调用 Agent
# workflow.createRun() → run.start({ inputData })     # 运行 Workflow
# mastra.getAgentById('id') / mastra.getWorkflow('id')

# ===== 存储 =====
# 本地：LibSQLStore({ url: 'file:./mastra.db' })（与 dev 共用时用绝对路径）
# 生产：PostgresStore({ connectionString: process.env.DATABASE_URL })

# ===== 运维 =====
npm ls @mastra/core                      # 查看版本
npm install @mastra/core@latest          # 升级
npm install @mastra/core@1.78.0          # 回滚
docker compose up -d                     # 容器化部署（restart: unless-stopped 自启）