# @diagrid/agent-mastra 中文文档

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

版本：0\.2\.0
npm 元数据更新时间：2026-09-17T22:34:08.890Z
中文译文更新时间：2026-11-12T06:34:26.806Z
软件包许可：BUSL-1\.1

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

原始 npm 页面：https://www.npmjs.com/package/%40diagrid/agent-mastra
原文对照：https://npmcn.com/package/%40diagrid/agent-mastra/?lang=original
项目主页：https://github.com/diagridio/typescript-ai/tree/main/packages/mastra#readme
源码仓库：https://github.com/diagridio/typescript-ai

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

- 包体积（解压后）：239 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：1 个
- peer 依赖：zod ^4\.0\.0，@mastra/core \>=1\.50\.0 \<2
- 首次发布：2026-08-23T08:52:56.868Z
- 最新版本发布：2026-09-17T22:34:08.534Z
- 近 30 天下载量：5564（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

在Dapr工作流程上长期处决Mastra特工

## 安装

```sh
npm install @diagrid/agent-mastra
```

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

## README

# @diagrid/ 代理服务器

长期执行 [马斯特拉](https://mastra.ai/) 探员在 [Dapr 工作流程](https://docs.dapr.io/developing-applications/building-blocks/workflow/)。 。 。 .

代理控制回路是仿照Dapr Workflow和每个模型调用和 工具执行作为一种持久的活性,所以一个代理在进程崩溃中存活, 侧行车重新启动, 供应商停用, 而无需重新运行它的工作 已完成.

## 状态

工作,通过运行核查,而不是通过检查——针对当地 `dapr run` 与奥拉马公司对峙`qwen2.5:7b`作为 型号.

| 区域 | 状态 |
| --- | --- |
| 运行周期和工作流程命名 | ✅ |
| 持久代理循环( R)`agentWorkflow`(中文(简体) ) | \* 模式调用 \* 工具活动 \* 重复 |
| 模型桥 | – 通过每次重复的一步 `clientTools` |
| 工具桥 | 每个工具呼叫一个检查站活动 |
| 崩溃恢复 | xq 工具在中转后不重运行( 见下文- 至少一次) |
| 活动重试(模型和工具) | 3次尝试,有耐用后退 |
| 书记官处元数据`getMetadata()`(中文(简体) ) | 记录是正确的,但没有任何出版物——见下文 |
| 检查站的持久性 | 执行和测试,但跑者从来不叫它——见下文 |
| 土著达普活动 `RetryPolicy` | 而不是在JS SDK; 管弦乐团重唱 |
| 登记册元数据的组成部分发现 | ❌ `TODO(mastra-adapter)` |
| 需要的工具 `RequestContext` / 工作空间 | ❌ `TODO(mastra-adapter)` |

### 两行

两者都是建造和单位测试的,但没有呼叫者——工作部分不是 与工作特征相同:

-   **检查站的持久性.** `DaprMastraCheckpointer.save()/load()/list()` 有过 测试之外没有电话 跑步者建造一个并暴露为 公共领域;没有写,所以 `load()` 总是返回 `undefined` 内 实践。 今天继续线程意味着通过前 `messages` 输入 `invoke()` 你自己来.
-   **登记册元数据.** `getMetadata()` 返回 a _多数_ 正确记录—— 实例打印它, 但是没有向国家商店或代理发布它 注册,并且其三个字段不是配置. `memory.shortTerm` 报告 `{ type: 'DaprMastraCheckpointer' }`,准确的意向和前面 电线. `agent.maxIterations` 硬代码为 `1` 财务报告和审定财务报表 `pubsub` 实值 `{ resourceName: '', broadcastTopic: null, agentTopic: null }` 两者 `TODO(mastra-adapter)` 内 `mapper.ts`。将这三种读作未定而非 作为设置 : `inspect-agent.ts` 以 `maxIterations: 10` 财务报告和审定财务报表 将仍然打印 `1`。 。 。 .

`grep -rn 'TODO(mastra-adapter)' .` 从 repo 根列表中列出剩下的内容 — 6 标记。 将它定义为 `src` 从此目录中只找到三个;另一个 三个搬进来了 `packages/core` 与持久的循环. `tests/e2e/` 运行 以CI中真正的侧车为例 所以这些说法是诚实的.

## 安装

```bash
pnpm add @diagrid/agent-mastra @mastra/core zod
```

`@mastra/core` 财务报告和审定财务报表 `zod` 为: **端点** 依赖性:您的应用程序拥有它们 版本,并安装此适配器 永远不会将另一个框架的 SDK 拖入 你的树。 两者都必须在安装线上命名——对等依赖不是 为您安装.

-   节点.js 22.13
-   `@mastra/core` ≥ 1.50 < 2
-   `zod` ^ 4

## 使用量

```ts
import { Agent } from '@mastra/core/agent';
import { openai } from '@ai-sdk/openai';
import { DaprWorkflowAgentRunner } from '@diagrid/agent-mastra';

const agent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: 'You help customers with billing questions.',
  model: openai('gpt-4o-mini'),
});

const runner = new DaprWorkflowAgentRunner({
  agent,
  name: 'support-agent',
  maxIterations: 10,
});

// Shut down cleanly on SIGINT/SIGTERM (opt-in: a library must not install
// process-wide handlers behind your back).
const disposeHandlers = runner.registerShutdownHandlers();

await runner.start();

const result = await runner.invoke({
  prompt: 'Why was I charged twice?',
  threadId: 'thread-123',
});

console.log(result.text, result.status, result.iterations);

disposeHandlers();
await runner.shutdown();
```

偏爱 `runner.schedule(...)` 当呼叫者不应阻挡时——代理转弯 超过HTTP请求是正常情况,而不是例外。 它还原 工作流程实例 id, 您可以通过它进行投票 `runner.getWorkflowStatus(id)`。 。 。 .

## 模块布局

此 repo 中的每个适配器的形状如下 :

| 文件 | 作用 |
| --- | --- |
| `bridge.ts` | 驱动 Mastra 一步一步——唯一知道 Mastra API 的文件 |
| `mapper.ts` | `MastraAgentMapper` - 那个 `BaseAgentMapper` 执行 |
| `runner.ts` | 公共入境点 - `DaprWorkflowAgentRunner`、生命周期和援引 |
| `state.ts` | `DaprMastraCheckpointer` - 核心的检查器与 `mastra` 前缀 |
| `version.ts` | 版本标记,由发布工作流程所印出 |

耐用剂循环是 **没有** 在这里。 管弦乐团,它的活动 重试行为和I/O计划 `@diagrid/agent-core` 下级 `src/agent/`,这个软件包再导出它们,所以导入适配器仍然 足够转弯了 他们搬到那里是因为他们都没有提到 Mastra: 把它们放在适配器中意味着适配器 #2 会复制耐用循环 以及跨语言的检查站密钥布局,包括微妙的变数 两个会漂流.

## 关于元数据提取的说明

`MastraAgentMapper` 读取 Mastra `Agent` **结构** 而不是说 导入 `@mastra/core`。这是有意的:在此输入框架 把它放在任何安装适配器的运行时间图中 `tests/guards/cross-framework-imports.test.ts` 禁止进入.

四个后果值得了解:

-   **通过类访问者读取配置**,而不是平地属性。 A 类 真实 `Agent` 保留 `instructions` 财务报告和审定财务报表 `tools` 私下和揭露他们通过 `getInstructions()` 财务报告和审定财务报表 `listTools()`读取 `agent.tools` 返回时 `undefined`。 。 。 . `listTools()` 是async, 这就是为什么 `mapper.mapAgentMetadata()` 财务报告和审定财务报表 `runner.getMetadata()` 也一样.
-   **Mastra的三种模式表格都得到了支持**:模型路由魔法 字符串( r)`'openai/gpt-4o-mini'`),一个 OpenAI 兼容配置 (单位:千美元)`{ id, url }` 或者说 `{ providerId, modelId, url }` - 你如何指向奥拉马, 和AI SDK模型实例。 错误的路由器 ID 被反射回原声 类型在登记册中可见,而不是崩溃为 `unknown`。 。 。 .
-   马斯特拉也接受 `instructions`, (中文(简体) ), `model` 财务报告和审定财务报表 `tools` 作为 **工厂**A级 工厂需要 `RuntimeContext` 登记时不存在的,因此 动态配置是 **跳过** ——登记册显示静态配置. 这个 不猜测.
-   工具参数计划通过 Zod 4 演示为 JSON Schema `z.toJSONSchema()`. Zod 3 含有变换的分型和分型不是 可代表,并降解为空字符串而不是 `[object Object]`。 。 。 .

见 [`examples/mastra/`](https://npmcn.com/package/examples/mastra/README.md) —— 说 `pnpm inspect` 指纹 整个记录 一个真正的经纪人.

## 许可证

[业务来源许可证1.1](https://npmcn.com/package/LICENSE.md) 2026年 — Present Diagrid Inc.

## 至少一次,没有完全一次

工作流程引擎保证每个活动运行 **至少一次**任意 因此,具有副作用的活动必须能够安全地进行两次.

活动边界使完成的呼叫具有持久性:一旦其结果是 检查,重放 读检查,而不是再次呼喊。 不过 活动函数返回和引擎持续返回之间有一个窗口 记录完成, 和一个坠入窗口 重新运行的活动. 对于 `invokeModel` 这意味着这个模型被叫做——并且记了两次帐。 作为工具 它意味着不管工具做了什么 发生两次.

所以,一个工具 收费卡,发送电子邮件, 或写一个非意识形态记录 需要自己的一能键或有条件的写入。 引擎会缩小窗口 无法关闭它.

失事恢复实例显示,在工具所在的地方,一个特定的死亡时间 不重运行。 它没有,在结构上也无法证明没有这一点 窗口.

## 常见问题

### @diagrid/agent-mastra 是什么？

在Dapr工作流程上长期处决Mastra特工

### 如何安装 @diagrid/agent-mastra？

在项目目录运行 npm install @diagrid/agent-mastra，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）、@mastra/core（\>=1\.50\.0 \<2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @diagrid/agent-mastra 支持 TypeScript 吗？

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

### @diagrid/agent-mastra 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @diagrid/agent-mastra 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @diagrid/agent-mastra 可以商用吗？

@diagrid/agent-mastra 使用 BUSL-1\.1 许可。声明的许可为 BUSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @diagrid/agent-mastra 的下载量有多少？

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

### @diagrid/agent-mastra 还在维护吗？

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