# @astropods/adapter-mastra 中文文档

规范地址：https://npmcn.com/package/%40astropods/adapter-mastra/

版本：0\.10\.1
npm 元数据更新时间：2026-11-04T12:49:44.365Z
中文译文更新时间：2026-11-07T01:27:30.344Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40astropods/adapter-mastra
原文对照：https://npmcn.com/package/%40astropods/adapter-mastra/?lang=original
项目主页：https://github.com/astropods/adapters#readme
源码仓库：https://github.com/astropods/adapters

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：103 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：zod ^3\.25\.0 \|\| ^4\.0\.0，@mastra/core \>=1\.14\.0
- 首次发布：2026-02-24T19:50:18.284Z
- 最新版本发布：2026-11-04T12:49:43.664Z
- 近 30 天下载量：2348（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

每一个回合的请求上下文 `userName`,发送者在源平台上的名字(他们在Slack中的全名,或者他们在网络聊天中的Astro名). 当平台发送无, 它缺席, 所以检查它。 告诉模型如何使用这个名字,或者它可能

## 安装

```sh
npm install @astropods/adapter-mastra
```

也可以使用：`pnpm add @astropods/adapter-mastra`、`yarn add @astropods/adapter-mastra`、`bun add @astropods/adapter-mastra`

## README

# @astropods/ 适应器- mastra

## 发送者姓名

每一个回合的请求上下文 `userName`,发送者在源平台上的名字(他们在Slack中的全名,或者他们在网络聊天中的Astro名). 当平台发送无, 它缺席, 所以检查它。 告诉模型如何使用这个名字,或者它可能在每次答复中重复:

```ts
const agent = new Agent({
  id: "greeter",
  name: "Greeter",
  model,
  instructions: ({ requestContext }) => {
    const name = requestContext.get("userName");
    return name
      ? `The user's name is ${name}. Greet them by name in your first reply only; don't repeat it after that.`
      : "You are a helpful assistant.";
  },
});
```

请求的背景还包含: `threadId` 财务报告和审定财务报表 `resourceId`。 。 。 . `resourceId` 是发送转弯的用户.

## 内存

记忆线是对话. 内存资源取决于谁分享:

-   在1:1聊天中,如DM或网络聊天中,资源是用户,因此资源范围内存在聊天间跟踪.
-   在Slack线条等频道对话中,资源就是对话. 线上任何人都可以和经纪人交谈,没有人自己的记忆混入其中.
-   已存在内存中的线程保留着它用它创建的资源,因为马斯特拉拒绝用不同资源使用的线程.

工作记忆和语义记忆默认为 `scope: "resource"`将一个人的记忆带过他们的线程 将每条线程的内存保留到线程上, 设置为 `scope: "thread"`数字 :

```ts
new Memory({
  storage,
  options: {
    workingMemory: { enabled: true, scope: "thread" },
    semanticRecall: { topK: 5, messageRange: 2, scope: "thread" },
  },
});
```

## 所选模式

将聊天用户可以选择的模型传递到 `serve()`;第一个是默认。 通过两个或两个以上,网络聊天显示一个取型器,每个回合的请求上下文带有取型器为 `model`。当没有选择模型时,它就不存在了,比如在Slack转弯时,所以回到默认状态:

```ts
const MODELS = [process.env.MODEL_DEFAULT ?? "claude-sonnet-4-6", "claude-opus-4-7"];

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: ({ requestContext }) =>
    gateway.chat(requestContext.get<"model", string | undefined>("model") ?? MODELS[0]),
});

serve(agent, { models: MODELS });
```

在工具批准或表格之后,恢复运行获得相同的请求上下文.

## 文件

适配器将每个附件文件的名称和路径附加到转弯的文本上. `fileTools()` 提供打开这些路径的模型工具。 它们处理任何大小的文件而不将文件装入提示中:

| 工具 | 它会做什么 |
| --- | --- |
| `inspect_file` | 报告文件的类型(PDF,DOCX,XLSX,文本),其大小,文本长度,以及表格每个工作表的列和行数. |
| `read_file` | 返回一个 PDF 、 DOCX 或文本文件的 2万个字符页, 并带有 `nextOffset` 下页. |
| `read_table` | 从 CSV 或 XLSX 文件返回一行的一页, 默认为 100, 与 `nextOffset` 下页. |
| `create_file` | 将文本文件写入文件目录并附在回复中 `attachFile`,并返回它的名称和读取它的道路. |

```ts
import { fileTools, serve } from "@astropods/adapter-mastra";

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  model,
  instructions: "Answer questions about the files the user attaches.",
  tools: { ...fileTools() },
});

serve(agent, { supportsFiles: true });
```

`supportsFiles` 打开网络聊天上传。 Slack发送文件的方式。 工具只打开当前对话中附加或创建的文件,因此后续问题可以回到更早的文件. 列表随文件一起被保存,所以会通过重启持续. 工具返回文件内容而不进行分析 。 对于大表格上的计数或总数,请给代理服务器一个查询引擎,如附件上的 DuckDB `path`如适配器核心README所描述。 被扫描的PDF没有文本层,所以读取一个取自自OCR工具.

## 沙盒

`AstroSandbox` 是马斯特拉沙盒供应商 所以马斯特拉自己的工作空间驱动器 它: 文件系统、挂载和内置的工作空间工具全部运行 对抗MicroVM 没有可供学习的平行工具.

```ts
import { AstroSandbox } from "@astropods/adapter-mastra";
import { Workspace } from "@mastra/core/workspace";

const workspace = new Workspace({
  sandbox: new AstroSandbox({ name: threadId }),
});
```

名曰沙盒. 师曰. 使用线条编号:一条线是一沙盒,所以 对话恢复到自己的文件和两个线程 共享文件系统.

编辑后的消息不会重置沙盒 。 当用户编辑信件时 网络聊天,适配器重建线程的内存,但一个按键的沙盒 线程保存替换的转折所写文件。 探员就能看到 工作来自用户放弃的谈话版本。 如果这很重要的话, 通过 `supportsHistory: false` 改为 `serve()`编辑器 探员.

### 它的地图

| 马斯特拉 | 天体 |
| --- | --- |
| `start()` | 一个附件。 报告 `created` 在第一个呼叫, `connected` 之后 |
| `executeCommand()` | 短命令,或者通过时的背景进程 `onStdout`编号 :`onStderr`,因为普通执行官不能流 |
| `processes` | `spawn`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `kill` 超过真实背景过程 |
| `handle.wait()` | 投出投出, 将每个块交给你的召回 |
| `stop()` 编号 : `destroy()` | 挂起并删除 |
| `getInfo()` | 包括 `timeoutAt`沙盒的8小时天花板 |

Mastra 按要求启动沙盒: 它的流程管理器呼叫 `ensureRunning()` 在产卵之前, 没有什么用手开始.

### 它不会做的

`supportsCheckpoints` 实值 `false`。 。 。 . `snapshot()` 暂停, 显示快照 microVM的内存 所以下一个附件从它恢复,但只有 永远回到最近的状态 坚持过天花板不是 已经建成了.

一个过程没有 stdin . `sendStdin()` 投掷而不是接受写入 并丢出;通过命令或文件传递输入.

## 常见问题

### @astropods/adapter-mastra 是什么？

每一个回合的请求上下文 userName,发送者在源平台上的名字\(他们在Slack中的全名,或者他们在网络聊天中的Astro名\)\. 当平台发送无, 它缺席, 所以检查它。 告诉模型如何使用这个名字,或者它可能

### 如何安装 @astropods/adapter-mastra？

在项目目录运行 npm install @astropods/adapter-mastra，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^3\.25\.0 \|\| ^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @astropods/adapter-mastra 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @astropods/adapter-mastra 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @astropods/adapter-mastra 可以商用吗？

@astropods/adapter-mastra 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @astropods/adapter-mastra 的下载量有多少？

根据 npm 官方下载统计，@astropods/adapter-mastra 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,348 次，日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @astropods/adapter-mastra 还在维护吗？

最新版本 0\.10\.1 发布于 2026/11/04（3 天前）；至今共发布 49 个版本，其中过去 12 个月发布了 49 个；首次发布于 2026/02/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。