工作区

🌐 Workspace

Mastra 工作区为代理提供了一个持久的环境，用于存储文件和执行命令。代理使用工作区工具来读取和写入文件、运行 shell 命令以及搜索索引内容。

🌐 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents use workspace tools to read and write files, run shell commands, and search indexed content.

工作区支持以下功能：

🌐 A workspace supports the following features:

• 文件系统：文件存储（读取、写入、列出、删除）
• 沙盒：命令执行（Shell命令）
• 搜索：对已索引内容进行 BM25、向量或混合搜索
• 技能：可重复使用的代理指令

它是如何工作的

🌐 How it works

当你将工作区分配给代理时，Mastra 会将相应的工具包含在代理的工具集中。然后，代理可以使用这些工具与文件进行交互并执行命令。

🌐 When you assign a workspace to an agent, Mastra includes the corresponding tools in the agent's toolset. The agent can then use these tools to interact with files and execute commands.

你可以使用任意组合的支持功能来创建工作区。代理只会接收到与配置相关的工具。

🌐 You can create a workspace with any combination of the supported features. The agent receives only the tools relevant to what's configured.

用法

🌐 Usage

创建工作区

🌐 Creating a workspace

通过使用你所需功能实例化 Workspace 类来创建工作区：

🌐 Create a workspace by instantiating the Workspace class with your desired features:

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  skills: ['/skills'],
});

skills 数组指定包含技能定义的目录路径，详见 Skills。

🌐 The skills array specifies paths to directories containing skill definitions, see Skills.

全局工作区

🌐 Global workspace

在 Mastra 实例上设置工作区。除非代理定义了自己的工作区，否则所有代理都会继承此工作区：

🌐 Set a workspace on the Mastra instance. All agents inherit this workspace unless they define their own:

src/mastra/index.ts

import { Mastra } from '@mastra/core';
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
});

const mastra = new Mastra({
  workspace,
  agents: { myAgent },
});

代理范围工作区

🌐 Agent-scoped workspace

将工作区直接分配给代理以覆盖全局工作区：

🌐 Assign a workspace directly to an agent to override the global workspace:

src/mastra/agents/my-agent.ts

import { Agent } from '@mastra/core/agent';
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './agent-workspace' }),
});

export const myAgent = new Agent({
  id: 'my-agent',
  model: 'openai/gpt-4o',
  workspace,
});

初始化

🌐 Initialization

Mastra 会在需要时自动初始化工作区。在使用 Mastra 以外的工作区（独立脚本、测试）时，或者在第一次代理交互之前需要预先配置资源时，请手动调用 init()。

🌐 Mastra automatically initializes workspaces when needed. Call init() manually when using a workspace outside of Mastra (standalone scripts, tests) or when you need to pre-provision resources before the first agent interaction.

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
});

await workspace.init();

init() 的作用

🌐 What init() does

初始化为每个已配置的提供程序运行设置逻辑：

🌐 Initialization runs setup logic for each configured provider:

• LocalFilesystem：如果不存在，则创建基础目录
• LocalSandbox：创建工作目录
• Search（如果已配置）：从 autoIndexPaths 索引文件，参见 搜索与索引

外部提供商可能会执行额外的设置，例如建立连接或进行身份验证。

🌐 External providers may perform additional setup like establishing connections or authenticating.

工具配置

🌐 Tool configuration

通过工作区中的 tools 选项配置工具行为。这可以控制哪些工具被启用以及它们的行为方式。

🌐 Configure tool behavior through the tools option on the workspace. This controls which tools are enabled and how they behave.

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    // Global defaults
    enabled: true,
    requireApproval: false,

    // Per-tool overrides
    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
      requireApproval: true,
      requireReadBeforeWrite: true,
    },
    [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: {
      enabled: false,
    },
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      requireApproval: true,
    },
  },
});

工具选项

🌐 Tool options

选项	类型	描述
enabled	boolean	工具是否可用（默认值：true）
requireApproval	boolean	工具在执行前是否需要用户批准（默认值：false）
requireReadBeforeWrite	boolean	对于写入工具：是否先读取文件（默认值：false）

先读后写

🌐 Read-before-write

当在写入工具上启用 requireReadBeforeWrite 时，代理必须在写入文件前先读取该文件。这可以防止覆盖代理未查看过的文件：

🌐 When requireReadBeforeWrite is enabled on write tools, agents must read a file before writing to it. This prevents overwriting files the agent hasn't seen:

• 新文件：可以在不读取的情况下写入（它们尚不存在）
• 现有文件：必须先读取
• 外部修改的文件：如果自代理读取文件后文件发生了更改，写入将失败

相关

🌐 Related

• 文件系统
• 沙盒
• 技能
• 搜索与索引
• 工作区类参考