Mastra Workspace 模块详解为 Agent 构建文件系统、沙箱执行与混合搜索的统一工作区【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文围绕 Mastra 核心包中的 Workspace 模块packages/core/src/workspace展开。读完后你将掌握如何用Workspace类组合可插拔的文件系统与沙箱如何让 Agent 自动获得文件读写、命令执行、搜索与技能Skills等工具以及如何通过requireApproval、requireReadBeforeWrite、只读模式等安全配置控制 Agent 的写操作风险。1. Workspace 模块概览根据模块内的 READMEWorkspace 模块通过一个统一接口为 Agent 提供文件系统访问与代码执行能力。其核心特性包括文件系统访问Filesystem access—— 通过可插拔的 filesystem provider 读取、写入和管理文件代码执行Code execution—— 通过沙箱sandbox环境运行代码和 shell 命令搜索Search—— 支持 BM25 关键词搜索、向量语义搜索以及混合搜索技能Skills—— 发现并使用SKILL.md文件作为可复用的指令集安全控制Safety controls—— 写前必读read-before-write守卫、审批流approval flows与只读模式。从源码结构看Workspace是一个泛型类构造函数签名保留了传入 provider 的具体类型使得workspace.filesystem、workspace.sandbox等访问器能返回你实际传入的类型见 workspace.ts。构造函数要求至少配置 filesystem、sandbox 或 skills 之一否则抛出NO_PROVIDERS错误// packages/core/src/workspace/workspace.ts if (!this._fs !this._filesystemResolver !this._sandbox !this._sandboxResolver !this.hasSkillsConfig()) { throw new WorkspaceError(Workspace requires at least a filesystem, sandbox, or skills, NO_PROVIDERS); }2. 快速开始README 中给出的最小可用示例如下传入一个LocalFilesystem和一个LocalSandbox开启 BM25 搜索即可完成文件操作、命令执行与内容搜索import { Workspace, LocalFilesystem, LocalSandbox } from mastra/core/workspace; const workspace new Workspace({ filesystem: new LocalFilesystem({ basePath: ./workspace, }), sandbox: new LocalSandbox({ workingDirectory: ./workspace, }), bm25: true, }); await workspace.init(); // 文件操作 await workspace.writeFile(/docs/guide.md, # Guide); const content await workspace.readFile(/docs/guide.md, { encoding: utf-8 }); // 命令执行 const result await workspace.executeCommand(echo, [hello world]); // 搜索 await workspace.index(/docs/guide.md, content as string); const results await workspace.search(guide);关键步骤说明new Workspace({...})声明式地组合 provider 实例。除了静态实例filesystem与sandbox也支持传入 resolver 函数({ requestContext }) Provider按请求动态解析不同的文件系统或沙箱且解析结果会按RequestContext做记忆化见 workspace.ts 中的resolveFilesystem/resolveSandboxawait workspace.init()初始化是显式动作。从源码看init()会依次调用 filesystem 的init生命周期钩子、sandbox 的start钩子并在配置了autoIndexPaths时自动执行一次rebuildSearchIndex最后把状态从initializing置为ready文件/命令/搜索操作文件操作需要 filesystem命令执行需要 sandbox搜索需要bm25或vectorStore embedder配置缺配置时分别抛出对应错误如SearchNotAvailableError。2.1 核心配置项WorkspaceConfig结合 workspace.ts 中WorkspaceConfig的字段注释常用配置项及其取值如下配置项类型默认值说明id/namestring自动生成工作区标识与人类可读名称未提供时 id 形如ws-base36时间戳-随机串filesystem实例或 resolver无文件系统 provider静态实例或按请求解析的函数sandbox实例或 resolver无沙箱 providerresolver 模式下沙箱生命周期由调用方拥有且与mounts、lsp: true不兼容mountsRecordstring, WorkspaceFilesystem无将多个文件系统挂载到不同路径内部生成CompositeFilesystem按路径路由不能与filesystem同时使用onMount钩子函数无挂载前钩子返回false跳过挂载返回{ success: true }表示自行完成挂载bm25boolean \| BM25Config \| { bm25?, tokenize? }关闭开启 BM25 搜索可传k1/b参数及分词选项如 CJK 场景调tokenize.minLengthvectorStore/embedderMastraVector/Embedder无二者同时提供时启用向量与混合搜索vectorStore必须有embedder否则抛INVALID_SEARCH_CONFIGsearchIndexNamestring${id}_search的清洗结果向量索引名必须满足 SQL 标识符规则字母/下划线开头仅字母数字下划线最长 63 字符autoIndexPathsstring[]无init()时自动索引这些目录如[docs, support]skillsstring[]或函数无发现SKILL.md的目录函数形式可按requestContext如用户等级动态返回路径skillSource/checkSkillFileMtime对象 /boolean无 /false自定义技能来源是否额外检查 SKILL.md 文件 mtime 以支持热更新lspboolean \| LSPConfig关闭为编辑类工具追加语言服务器诊断需要带进程管理器的沙箱与vscode-jsonrpc等可选依赖toolsWorkspaceToolsConfig无工具级安全与启用配置详见第 5 节autoSync/operationTimeoutboolean/numberfalse/ 无文件系统与沙箱间自动同步单操作超时毫秒bm25的三种形态在构造函数中由parseBM25Config统一归一化为搜索引擎所需的配置其中BM25Config的两个经典参数默认值为k1: 1.5词频饱和度典型范围 1.2–2.0与b: 0.75文档长度归一化0 不归一、1 完全归一定义见 bm25.ts。2.2 LocalFilesystem 的关键选项内置的 LocalFilesystem 以本地目录为后端是开发场景的默认选择其LocalFilesystemOptions中有几个值得注意的字段basePath必填磁盘上的根目录支持~展开contained默认true所有文件操作被限制在basePath及allowedPaths之内逃逸路径抛PermissionError可防止路径穿越与符号链接逃逸需要访问全局技能目录等外部路径时设为falsereadOnly默认false为true时阻断一切写操作读操作不受影响allowedPaths在contained模式下额外放行的目录相对路径基于basePath解析instructions覆盖getInstructions()的默认说明文本可为字符串或函数。3. 将 Workspace 分配给 AgentREADME 中说明只要给Agent传入workspaceAgent 就会自动获得 workspace 工具集import { Agent } from mastra/core/agent; const agent new Agent({ id: my-agent, workspace: workspace, // Agent receives workspace tools when a workspace is provided });从源码看Agent 侧通过createWorkspaceTools工厂生成这批工具工具名统一以mastra_workspace为前缀完整工具清单定义在 constants/index.ts文件系统类mastra_workspace_read_file、write_file、edit_file、list_files、delete、file_stat、mkdir、grep、ast_edit沙箱类mastra_workspace_execute_command、get_process_output、kill_process搜索类mastra_workspace_search、index计算机操作类computer_screenshot、computer_click、computer_type、computer_scroll等仅当沙箱支持 computer 能力时输出LSP 类mastra_workspace_lsp_inspect配置lsp后启用。工具的实际挂载逻辑在 tools/tools.ts每个工具被包装一层执行前会先按请求上下文解析动态 providerresolveEffectiveWorkspace并把解析后的workspace注入工具执行上下文如果工具使用了 read-before-write 守卫包装层还会挂接文件读取追踪器read tracker。4. 安全配置审批、写前必读与只读模式README 中的安全配置示例如下const workspace new Workspace({ filesystem: new LocalFilesystem({ basePath: ./workspace, readOnly: true, // 阻断所有写操作默认 false }), sandbox: new LocalSandbox({ workingDirectory: ./workspace }), tools: { // 顶层默认值作用于所有工具 requireApproval: true, // 按工具覆盖 mastra_workspace_write_file: { requireReadBeforeWrite: true, // 写入前必须先读取文件 }, mastra_workspace_execute_command: { requireApproval: true, }, }, });这里涉及三层独立的安全机制理解它们的分工有助于设计最小权限的 Agentprovider 级只读LocalFilesystem({ readOnly: true })直接拦截 filesystem 的所有写调用是最硬的一道闸适合“只读知识库”场景工具级审批requireApproval控制 Agent 调用工具前是否需要用户批准写前必读requireReadBeforeWrite防止 Agent 在未查看当前内容的情况下覆盖文件由InMemoryFileReadTracker见 file-read-tracker.ts追踪哪些文件已被读取未读即写会失败。4.1 tools 配置的解析顺序tools/types.ts 与 tools/tools.ts 中的resolveToolConfig明确了配置解析规则——内置默认 → 顶层默认 → 按工具覆盖后者覆盖前者// resolveToolConfig 的解析顺序later overrides earlier // 1. 内置默认enabled: true, requireApproval: false // 2. 顶层配置tools.enabled、tools.requireApproval // 3. 按工具配置tools[toolName].*WorkspaceToolConfig的完整字段对每个mastra_workspace_*工具都可用字段默认值说明enabledtrue工具是否启用解析失败时按false处理fail-closedrequireApprovalfalse执行前需用户审批requireReadBeforeWrite无仅写工具写入前必须已读取该文件maxOutputTokens3000工具输出 token 上限超出截断name原名暴露给模型的工具名重映射配置键仍须是原始工具名更高级的用法enabled、requireApproval、requireReadBeforeWrite都支持动态函数形式接收requestContext执行期还包含args可实现按租户等级、文件路径前缀等条件动态放行例如“写入/protected前缀路径前强制先读”tools: { mastra_workspace_write_file: { requireReadBeforeWrite: async ({ args }) (args.path as string).startsWith(/protected), }, }此外针对具体工具还有扩展配置mastra_workspace_execute_command支持backgroundProcesses后台进程的 stdout/stderr/exit 回调与 abort 策略mastra_workspace_read_file支持mediaTypes默认image/png、image/jpeg、image/webp、application/pdf与maxMediaBytes默认 10 MiB控制二进制文件如何进入模型上下文。顶层还可以配置writeLockTimeoutMs写锁等待上限默认 30000ms。运行时也可用workspace.setToolsConfig(...)热切换例如一键禁用所有写工具进入只读模式。5. 搜索索引、BM25 与向量/混合检索README 将“BM25 关键词搜索、向量语义搜索和混合搜索”列为核心特性源码中的实现路径是索引workspace.index(path, content, options?)以文件路径作为文档 ID将内容交给内部SearchEngine。init()时若配置了autoIndexPaths会自动调用rebuildSearchIndexrebuildSearchIndex支持目录、单文件与 glob 三种路径形态并先clear()旧索引再重建。批量读取时并发度固定为 8FS_READ_CONCURRENCY且超长文件会被splitIntoChunks自动切块——每个 chunk 的文档 ID 形如path#chunk-i并携带startLineOffset用于结果中的行号回溯行号工具见 line-utils.ts查询workspace.search(query, options?)根据已启用的引擎执行 BM25、向量或混合检索返回带分数的结果未配置任何搜索能力时抛出SearchNotAvailableError能力探测workspace.canBM25/canVector/canHybrid三个 getter 可在运行时判断某类检索是否可用。BM25 的算法实现位于 search/bm25.ts是一个标准的 BM25 概率排序函数按查询词在文档中的词频与文档长度归一化打分。若需针对中文等非拉丁语系调整分词行为可通过bm25.tokenize传入TokenizeOptions例如removePunctuation: false, minLength: 1。6. 生命周期管理与模块结构6.1 init / stop / destroy从 workspace.ts 的源码看工作区提供两级停机语义init()按“filesystem init → sandbox start → 自动索引”顺序启动resolver 形式的 provider 在此被跳过它们在首次工具调用时才解析stop()只停活动资源不销毁——关闭 LSP 客户端、关闭浏览器、调用 sandbox 的stop远程沙箱会暂停/挂起以便后续恢复。文件系统、搜索索引与 skills 均不受影响这是Mastra.shutdown()调用的路径destroy()完全清理——stop之外的destroy生命周期、释放搜索索引与技能注册表引用源码注释特别强调这一步能避免被销毁的工作区继续持有全部索引文本状态进入destroyed。destroy()开始后任何迟到的index()写入会被assertSearchWritable拒绝。6.2 模块目录结构README 的 “Module Structure” 一节列出了该模块的构成文件对照当前仓库的实际目录组织workspace 目录各文件的职责如下路径职责workspace.ts主Workspace类配置校验、provider 解析、搜索、生命周期filesystem/WorkspaceFilesystem接口filesystem.ts、LocalFilesystem与CompositeFilesystem实现、写前必读追踪file-read-tracker.ts、写锁file-write-lock.ts、挂载mount.tssandbox/WorkspaceSandbox接口sandbox.ts、LocalSandbox实现、进程管理器、原生隔离后端检测bubblewrap/seatbelttools/全部 workspace 工具的定义每个工具独立文件如read-file.ts、write-file.ts、execute-command.ts、grep.ts、ast-edit.ts等与 tools.ts 工厂search/SearchEngineBM25 向量 混合与 bm25.ts 算法实现skills/Skills 系统SKILL.md发现、校验、版本化来源VersionedSkillSource与技能发布lsp/LSP 客户端、语言服务器管理与诊断line-utils.ts搜索结果行号计算工具glob.ts统一的路径模式glob解析供索引与文件工具共用constants/index.tsWORKSPACE_TOOLS工具名常量index.ts模块公共导出Workspace、内置 provider、基类MastraFilesystem/MastraSandbox、错误类型、工具工厂与 glob 工具外部 provider如 AgentFS、E2B 等沙箱只需继承 index.ts 导出的MastraFilesystem/MastraSandbox基类即可获得日志集成与生命周期约定。7. 小结Workspace 模块把“文件存储”与“代码执行”抽象为两个可互换的 provider 接口并在此之上叠加了搜索索引、技能发现、LSP 诊断与细粒度的工具安全配置。对开发者而言三个实践要点本地开发直接用LocalFilesystem LocalSandbox生产/多租户场景用 resolver 函数按请求动态提供 provider安全配置遵循“provider 只读 工具审批 写前必读”的分层思路动态函数形式可以按请求上下文精确收紧权限所有面向 Agent 的能力都以mastra_workspace_*工具名暴露便于在审批、日志与自定义 hooks 中按名拦截。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra Workspace 模块详解：为 Agent 构建文件系统、沙箱执行与混合搜索的统一工作区
Mastra Workspace 模块详解为 Agent 构建文件系统、沙箱执行与混合搜索的统一工作区【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文围绕 Mastra 核心包中的 Workspace 模块packages/core/src/workspace展开。读完后你将掌握如何用Workspace类组合可插拔的文件系统与沙箱如何让 Agent 自动获得文件读写、命令执行、搜索与技能Skills等工具以及如何通过requireApproval、requireReadBeforeWrite、只读模式等安全配置控制 Agent 的写操作风险。1. Workspace 模块概览根据模块内的 READMEWorkspace 模块通过一个统一接口为 Agent 提供文件系统访问与代码执行能力。其核心特性包括文件系统访问Filesystem access—— 通过可插拔的 filesystem provider 读取、写入和管理文件代码执行Code execution—— 通过沙箱sandbox环境运行代码和 shell 命令搜索Search—— 支持 BM25 关键词搜索、向量语义搜索以及混合搜索技能Skills—— 发现并使用SKILL.md文件作为可复用的指令集安全控制Safety controls—— 写前必读read-before-write守卫、审批流approval flows与只读模式。从源码结构看Workspace是一个泛型类构造函数签名保留了传入 provider 的具体类型使得workspace.filesystem、workspace.sandbox等访问器能返回你实际传入的类型见 workspace.ts。构造函数要求至少配置 filesystem、sandbox 或 skills 之一否则抛出NO_PROVIDERS错误// packages/core/src/workspace/workspace.ts if (!this._fs !this._filesystemResolver !this._sandbox !this._sandboxResolver !this.hasSkillsConfig()) { throw new WorkspaceError(Workspace requires at least a filesystem, sandbox, or skills, NO_PROVIDERS); }2. 快速开始README 中给出的最小可用示例如下传入一个LocalFilesystem和一个LocalSandbox开启 BM25 搜索即可完成文件操作、命令执行与内容搜索import { Workspace, LocalFilesystem, LocalSandbox } from mastra/core/workspace; const workspace new Workspace({ filesystem: new LocalFilesystem({ basePath: ./workspace, }), sandbox: new LocalSandbox({ workingDirectory: ./workspace, }), bm25: true, }); await workspace.init(); // 文件操作 await workspace.writeFile(/docs/guide.md, # Guide); const content await workspace.readFile(/docs/guide.md, { encoding: utf-8 }); // 命令执行 const result await workspace.executeCommand(echo, [hello world]); // 搜索 await workspace.index(/docs/guide.md, content as string); const results await workspace.search(guide);关键步骤说明new Workspace({...})声明式地组合 provider 实例。除了静态实例filesystem与sandbox也支持传入 resolver 函数({ requestContext }) Provider按请求动态解析不同的文件系统或沙箱且解析结果会按RequestContext做记忆化见 workspace.ts 中的resolveFilesystem/resolveSandboxawait workspace.init()初始化是显式动作。从源码看init()会依次调用 filesystem 的init生命周期钩子、sandbox 的start钩子并在配置了autoIndexPaths时自动执行一次rebuildSearchIndex最后把状态从initializing置为ready文件/命令/搜索操作文件操作需要 filesystem命令执行需要 sandbox搜索需要bm25或vectorStore embedder配置缺配置时分别抛出对应错误如SearchNotAvailableError。2.1 核心配置项WorkspaceConfig结合 workspace.ts 中WorkspaceConfig的字段注释常用配置项及其取值如下配置项类型默认值说明id/namestring自动生成工作区标识与人类可读名称未提供时 id 形如ws-base36时间戳-随机串filesystem实例或 resolver无文件系统 provider静态实例或按请求解析的函数sandbox实例或 resolver无沙箱 providerresolver 模式下沙箱生命周期由调用方拥有且与mounts、lsp: true不兼容mountsRecordstring, WorkspaceFilesystem无将多个文件系统挂载到不同路径内部生成CompositeFilesystem按路径路由不能与filesystem同时使用onMount钩子函数无挂载前钩子返回false跳过挂载返回{ success: true }表示自行完成挂载bm25boolean \| BM25Config \| { bm25?, tokenize? }关闭开启 BM25 搜索可传k1/b参数及分词选项如 CJK 场景调tokenize.minLengthvectorStore/embedderMastraVector/Embedder无二者同时提供时启用向量与混合搜索vectorStore必须有embedder否则抛INVALID_SEARCH_CONFIGsearchIndexNamestring${id}_search的清洗结果向量索引名必须满足 SQL 标识符规则字母/下划线开头仅字母数字下划线最长 63 字符autoIndexPathsstring[]无init()时自动索引这些目录如[docs, support]skillsstring[]或函数无发现SKILL.md的目录函数形式可按requestContext如用户等级动态返回路径skillSource/checkSkillFileMtime对象 /boolean无 /false自定义技能来源是否额外检查 SKILL.md 文件 mtime 以支持热更新lspboolean \| LSPConfig关闭为编辑类工具追加语言服务器诊断需要带进程管理器的沙箱与vscode-jsonrpc等可选依赖toolsWorkspaceToolsConfig无工具级安全与启用配置详见第 5 节autoSync/operationTimeoutboolean/numberfalse/ 无文件系统与沙箱间自动同步单操作超时毫秒bm25的三种形态在构造函数中由parseBM25Config统一归一化为搜索引擎所需的配置其中BM25Config的两个经典参数默认值为k1: 1.5词频饱和度典型范围 1.2–2.0与b: 0.75文档长度归一化0 不归一、1 完全归一定义见 bm25.ts。2.2 LocalFilesystem 的关键选项内置的 LocalFilesystem 以本地目录为后端是开发场景的默认选择其LocalFilesystemOptions中有几个值得注意的字段basePath必填磁盘上的根目录支持~展开contained默认true所有文件操作被限制在basePath及allowedPaths之内逃逸路径抛PermissionError可防止路径穿越与符号链接逃逸需要访问全局技能目录等外部路径时设为falsereadOnly默认false为true时阻断一切写操作读操作不受影响allowedPaths在contained模式下额外放行的目录相对路径基于basePath解析instructions覆盖getInstructions()的默认说明文本可为字符串或函数。3. 将 Workspace 分配给 AgentREADME 中说明只要给Agent传入workspaceAgent 就会自动获得 workspace 工具集import { Agent } from mastra/core/agent; const agent new Agent({ id: my-agent, workspace: workspace, // Agent receives workspace tools when a workspace is provided });从源码看Agent 侧通过createWorkspaceTools工厂生成这批工具工具名统一以mastra_workspace为前缀完整工具清单定义在 constants/index.ts文件系统类mastra_workspace_read_file、write_file、edit_file、list_files、delete、file_stat、mkdir、grep、ast_edit沙箱类mastra_workspace_execute_command、get_process_output、kill_process搜索类mastra_workspace_search、index计算机操作类computer_screenshot、computer_click、computer_type、computer_scroll等仅当沙箱支持 computer 能力时输出LSP 类mastra_workspace_lsp_inspect配置lsp后启用。工具的实际挂载逻辑在 tools/tools.ts每个工具被包装一层执行前会先按请求上下文解析动态 providerresolveEffectiveWorkspace并把解析后的workspace注入工具执行上下文如果工具使用了 read-before-write 守卫包装层还会挂接文件读取追踪器read tracker。4. 安全配置审批、写前必读与只读模式README 中的安全配置示例如下const workspace new Workspace({ filesystem: new LocalFilesystem({ basePath: ./workspace, readOnly: true, // 阻断所有写操作默认 false }), sandbox: new LocalSandbox({ workingDirectory: ./workspace }), tools: { // 顶层默认值作用于所有工具 requireApproval: true, // 按工具覆盖 mastra_workspace_write_file: { requireReadBeforeWrite: true, // 写入前必须先读取文件 }, mastra_workspace_execute_command: { requireApproval: true, }, }, });这里涉及三层独立的安全机制理解它们的分工有助于设计最小权限的 Agentprovider 级只读LocalFilesystem({ readOnly: true })直接拦截 filesystem 的所有写调用是最硬的一道闸适合“只读知识库”场景工具级审批requireApproval控制 Agent 调用工具前是否需要用户批准写前必读requireReadBeforeWrite防止 Agent 在未查看当前内容的情况下覆盖文件由InMemoryFileReadTracker见 file-read-tracker.ts追踪哪些文件已被读取未读即写会失败。4.1 tools 配置的解析顺序tools/types.ts 与 tools/tools.ts 中的resolveToolConfig明确了配置解析规则——内置默认 → 顶层默认 → 按工具覆盖后者覆盖前者// resolveToolConfig 的解析顺序later overrides earlier // 1. 内置默认enabled: true, requireApproval: false // 2. 顶层配置tools.enabled、tools.requireApproval // 3. 按工具配置tools[toolName].*WorkspaceToolConfig的完整字段对每个mastra_workspace_*工具都可用字段默认值说明enabledtrue工具是否启用解析失败时按false处理fail-closedrequireApprovalfalse执行前需用户审批requireReadBeforeWrite无仅写工具写入前必须已读取该文件maxOutputTokens3000工具输出 token 上限超出截断name原名暴露给模型的工具名重映射配置键仍须是原始工具名更高级的用法enabled、requireApproval、requireReadBeforeWrite都支持动态函数形式接收requestContext执行期还包含args可实现按租户等级、文件路径前缀等条件动态放行例如“写入/protected前缀路径前强制先读”tools: { mastra_workspace_write_file: { requireReadBeforeWrite: async ({ args }) (args.path as string).startsWith(/protected), }, }此外针对具体工具还有扩展配置mastra_workspace_execute_command支持backgroundProcesses后台进程的 stdout/stderr/exit 回调与 abort 策略mastra_workspace_read_file支持mediaTypes默认image/png、image/jpeg、image/webp、application/pdf与maxMediaBytes默认 10 MiB控制二进制文件如何进入模型上下文。顶层还可以配置writeLockTimeoutMs写锁等待上限默认 30000ms。运行时也可用workspace.setToolsConfig(...)热切换例如一键禁用所有写工具进入只读模式。5. 搜索索引、BM25 与向量/混合检索README 将“BM25 关键词搜索、向量语义搜索和混合搜索”列为核心特性源码中的实现路径是索引workspace.index(path, content, options?)以文件路径作为文档 ID将内容交给内部SearchEngine。init()时若配置了autoIndexPaths会自动调用rebuildSearchIndexrebuildSearchIndex支持目录、单文件与 glob 三种路径形态并先clear()旧索引再重建。批量读取时并发度固定为 8FS_READ_CONCURRENCY且超长文件会被splitIntoChunks自动切块——每个 chunk 的文档 ID 形如path#chunk-i并携带startLineOffset用于结果中的行号回溯行号工具见 line-utils.ts查询workspace.search(query, options?)根据已启用的引擎执行 BM25、向量或混合检索返回带分数的结果未配置任何搜索能力时抛出SearchNotAvailableError能力探测workspace.canBM25/canVector/canHybrid三个 getter 可在运行时判断某类检索是否可用。BM25 的算法实现位于 search/bm25.ts是一个标准的 BM25 概率排序函数按查询词在文档中的词频与文档长度归一化打分。若需针对中文等非拉丁语系调整分词行为可通过bm25.tokenize传入TokenizeOptions例如removePunctuation: false, minLength: 1。6. 生命周期管理与模块结构6.1 init / stop / destroy从 workspace.ts 的源码看工作区提供两级停机语义init()按“filesystem init → sandbox start → 自动索引”顺序启动resolver 形式的 provider 在此被跳过它们在首次工具调用时才解析stop()只停活动资源不销毁——关闭 LSP 客户端、关闭浏览器、调用 sandbox 的stop远程沙箱会暂停/挂起以便后续恢复。文件系统、搜索索引与 skills 均不受影响这是Mastra.shutdown()调用的路径destroy()完全清理——stop之外的destroy生命周期、释放搜索索引与技能注册表引用源码注释特别强调这一步能避免被销毁的工作区继续持有全部索引文本状态进入destroyed。destroy()开始后任何迟到的index()写入会被assertSearchWritable拒绝。6.2 模块目录结构README 的 “Module Structure” 一节列出了该模块的构成文件对照当前仓库的实际目录组织workspace 目录各文件的职责如下路径职责workspace.ts主Workspace类配置校验、provider 解析、搜索、生命周期filesystem/WorkspaceFilesystem接口filesystem.ts、LocalFilesystem与CompositeFilesystem实现、写前必读追踪file-read-tracker.ts、写锁file-write-lock.ts、挂载mount.tssandbox/WorkspaceSandbox接口sandbox.ts、LocalSandbox实现、进程管理器、原生隔离后端检测bubblewrap/seatbelttools/全部 workspace 工具的定义每个工具独立文件如read-file.ts、write-file.ts、execute-command.ts、grep.ts、ast-edit.ts等与 tools.ts 工厂search/SearchEngineBM25 向量 混合与 bm25.ts 算法实现skills/Skills 系统SKILL.md发现、校验、版本化来源VersionedSkillSource与技能发布lsp/LSP 客户端、语言服务器管理与诊断line-utils.ts搜索结果行号计算工具glob.ts统一的路径模式glob解析供索引与文件工具共用constants/index.tsWORKSPACE_TOOLS工具名常量index.ts模块公共导出Workspace、内置 provider、基类MastraFilesystem/MastraSandbox、错误类型、工具工厂与 glob 工具外部 provider如 AgentFS、E2B 等沙箱只需继承 index.ts 导出的MastraFilesystem/MastraSandbox基类即可获得日志集成与生命周期约定。7. 小结Workspace 模块把“文件存储”与“代码执行”抽象为两个可互换的 provider 接口并在此之上叠加了搜索索引、技能发现、LSP 诊断与细粒度的工具安全配置。对开发者而言三个实践要点本地开发直接用LocalFilesystem LocalSandbox生产/多租户场景用 resolver 函数按请求动态提供 provider安全配置遵循“provider 只读 工具审批 写前必读”的分层思路动态函数形式可以按请求上下文精确收紧权限所有面向 Agent 的能力都以mastra_workspace_*工具名暴露便于在审批、日志与自定义 hooks 中按名拦截。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考