# @dbx-tools/shared-mastra 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/shared-mastra/

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:18:44.258Z
中文译文更新时间：2026-11-11T17:33:03.910Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：396 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-07-17T16:16:50.464Z
- 最新版本发布：2026-11-10T19:18:43.920Z
- 近 30 天下载量：9543（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：355（近 12 个月 355 个）

## 中文简介

AppKit Mastra 插件的浏览器安全合同

## 安装

```sh
npm install @dbx-tools/shared-mastra
```

也可以使用：`pnpm add @dbx-tools/shared-mastra`、`yarn add @dbx-tools/shared-mastra`、`bun add @dbx-tools/shared-mastra`

## README

# @dbx-tools/ 共享- mastra

验证与浏览器交换的数据 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/node/appkit-mastra)定义共享 路由常数、信头、嵌入标记、反馈计划、线程选择 字段、已公布的客户端配置和响应计划.

## 快开始

```ts
import { wire } from "@dbx-tools/shared-mastra";

const config = wire.MastraClientConfigSchema.parse(await response.json());
```

共同合同包括:

-   官方 AI SDK 聊天挂载和 AppKit- Mastra 的路由常数 添加,包括建议,模型列表,每代理默认模式 寻找,嵌入,反馈,和直接Genie聊天. 代理历史和线索 使用 Mastra 的本地客户端 API. 直接模式映射 Genie 对话和 在同一个UI合同上发送信件.
-   用于线程选择和模型覆盖请求的页眉/清空/身体常数.
-   嵌入标记 解析延迟图表和语句数据有效载荷 流动助手文本.
-   用于插件发布的客户端配置和路由响应的Zod schemas.
-   ML流回馈请求/响应计和微量头常数.
-   让用户界面软件包与服务器保持对齐的浏览器安全类型 导入节点或 Mastra 运行时代码 .

## 运行时边界

这个包包含合同和纯助工. 它没有注册 AppKit 插件、 调用 Databricks 服务、 运行 Mastra 代理或坚持对话 状态。 使用 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/node/appkit-mastra) 用于服务器 工作流程和 [@dbx-tools/ui-mastra (英语)](https://npmcn.com/package/ui/mastra) 用于回放聊天.

## 验证已发布的客户端配置

```ts
import { wire } from "@dbx-tools/shared-mastra";

const config = wire.MastraClientConfigSchema.parse(await response.json());
```

`wire.MastraClientConfigSchema` 验证插件发布的客户端 配置,包括挂载路径、默认代理、代理名册、反馈 可用性、背景-回合支持和聊天身份行为。 使用 已发布配置,而不是硬编码服务器路径.

## 使用路由常数

```ts
import { routes } from "@dbx-tools/shared-mastra";

const suggestionsUrl = `${basePath}${routes.MASTRA_ROUTES.suggestions}`;
const chatUrl = `${basePath}${routes.MASTRA_ROUTES.chat}/${agentId}`;
```

`routes.MASTRA_ROUTES` 使客户端获取呼叫与插件路由名称保持一致 用于聊天,模型,默认模式的查找,建议,反馈,并嵌入.

## 选择线索和模型

```ts
import { override, thread } from "@dbx-tools/shared-mastra";

await fetch(chatUrl, {
  method: "POST",
  headers: {
    [thread.THREAD_ID_HEADER]: activeThreadId,
    [override.MODEL_OVERRIDE_HEADER]: "claude sonnet",
  },
  body: JSON.stringify({ messages }),
});
```

使用页眉/平滑常数,而不是字符串字串,这样浏览器代码, 服务器中间软件,测试则同意请求如何选择活动 谈话和模特儿.

## 分析嵌入标记

```ts
import { markers } from "@dbx-tools/shared-mastra";

const parts = markers.parseMarkers("Here is the chart:\n[chart:abc123]");
const safeText = markers.stripIncompleteMarkerTail(streamingText);
```

标记让代理商用标识提及大型或延迟的文物,例如 `[chart:<id>]`, (中文(简体) ), `[data:<statement_id>]`,以及 `[visualization:<statement_id>]`。可视化标记选择 AppKit UI genie 请求图表之后的本地 Genie 图表/表格渲染器 .

## 验证反馈

```ts
import { feedback } from "@dbx-tools/shared-mastra";

const body = feedback.MastraFeedbackRequestSchema.parse({
  traceId: "tr-abc",
  value: true,
  comment: "Helpful",
});
```

反馈常数包括ML流量追踪头和默认评估名. Schemas在将拇指/评论有效载荷发送到插件之前验证.

## 验证插件响应

```ts
const chart = wire.ChartSchema.parse(await chartRes.json());
const event = wire.GenieWriterEventSchema.parse(writerPayload);
```

这个 `wire` 模块包含建议响应计划、示范清单、, 图表,语句数据,直接Genie线程/历史,以及Genie写作事件. 它还定义了AppKit UI所消耗的浏览器可视化有效载荷.

## 软件包出口

-   `wire`: Zod 策略和客户端配置的类型,模型列表,建议, 图表、报表数据和撰写事件.
-   `routes`:插件路由段常数和直接Genie路由构建器.
-   `markers`:嵌入-标记分解和不完全-尾条分解.
-   `feedback`: ML流量反馈信头、评估名称、请求/答复 计划.
-   `override`:模型覆盖头部/后部/身体常数.
-   `thread`:线状ID头/平分常数.

## 常见问题

### @dbx-tools/shared-mastra 是什么？

AppKit Mastra 插件的浏览器安全合同

### 如何安装 @dbx-tools/shared-mastra？

在项目目录运行 npm install @dbx-tools/shared-mastra，或使用 pnpm add / yarn add / bun add。

### @dbx-tools/shared-mastra 支持 TypeScript 吗？

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

### @dbx-tools/shared-mastra 支持 ESM 还是 CommonJS？

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

### @dbx-tools/shared-mastra 可以商用吗？

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

### @dbx-tools/shared-mastra 的下载量有多少？

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

### @dbx-tools/shared-mastra 还在维护吗？

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