# @dbx-tools/ui-mastra 中文文档 规范地址：https://npmcn.com/package/%40dbx-tools/ui-mastra/ 版本：0\.9\.206 npm 元数据更新时间：2026-11-10T19:18:48.893Z 中文译文更新时间：2026-11-11T17:44:14.786Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/ui-mastra 原文对照：https://npmcn.com/package/%40dbx-tools/ui-mastra/?lang=original 项目主页：https://github.com/reggie-db/dbx-tools#readme 源码仓库：https://github.com/reggie-db/dbx-tools ## 关键信息（来自 npm 元数据） - 包体积（解压后）：550 kB，56 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：19 个 - peer 依赖：react ~19\.2\.4，react-dom ~19\.2\.4，react-router-dom ^7\.6\.2 - 首次发布：2026-07-17T16:17:03.130Z - 最新版本发布：2026-11-10T19:18:48.519Z - 近 30 天下载量：8646（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：354（近 12 个月 354 个） ## 中文简介 AppKit- Mastra 插件的反应聊天 UI ## 安装 ```sh npm install @dbx-tools/ui-mastra ``` 也可以使用：`pnpm add @dbx-tools/ui-mastra`、`yarn add @dbx-tools/ui-mastra`、`bun add @dbx-tools/ui-mastra` ## README # @dbx-tools/ui-mastra (英语) 添加回声聊天表面到 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/node/appkit-mastra)软件包 流程、模型选择、AI/BI Genie进度、图表、表格、核准、, 历史、线程、导出和ML流反馈. ## 快开始 ```tsx import { MastraChat } from "@dbx-tools/ui-mastra/react"; import "@dbx-tools/ui-mastra/styles.css"; export function Assistant() { return ; } ``` 样式表导入共享 [@dbx-tools/ ui (英语)](https://npmcn.com/package/%40dbx-tools/appkit) 基础。 这个 主机应用程序还必须装入 Databricks AppKit UI 样式. 软件包内容 : - 下潜 `MastraChat` 读取插件客户端配置和 连接到默认代理人. - 重新装入代理后背背景回转的回收: 活动运行的元数据是 每个代理和线程持续,缓存流在页面后重新连接 重新装入,最终持续历史在恢复完成后被刷新. - 无头 `useMastraChat()` 想要同样传输逻辑的应用程序驱动程序 带有自定义布局. - 持久性 `MastraAssistant` 带有浮动发射器的应用程序外壳, 码头/重叠模式,每个边缘,可选的再调整大小,外部控制,以及 路由稳定聊天状态 . - 已控制 `ChatView` 用于拥有信件、流媒体、模式状态和 路由自称. - `MastraPluginClient` 结合 Mastra 的官方 AI SDK 聊天路线, 本地 内存 API,以及 AppKit- Mastra 模型、建议、反馈、图表和 语句路由. - 暂停的 Mastra 工具核准支持 `requireApproval` 电话,包括 恢复处理流程。 电子邮件形状的输入( `send_email` 工具) 制作为格式化为 / Cc / 主题/ 马克下体预览而非 生JSON(英语:JSON). - 可扩展的完整本地工具输入/结果, 语法突出的JSON请求和响应行在每个工具丸. - 通过 Mastra 本地输入的每回合应用程序上下文 `RequestContext` 和服务器侧 `requestContextSchema`。 。 。 . - 内嵌渲染 `[chart:]` 财务报告和审定财务报表 `[data:]` 生产的标记 服务器插件. - 与新、 选择、 重命名、 删除、 活动线程对话, 以及 背景流状态,加上运行线程的每行取消. - 可移动对话框 UI: 左或右对接列表, 切换到一个 编辑器风格的标签条横跨顶部,关闭,或者让 `auto` 选择 一个侧面板和来自聊天本身宽度的标签. - 同步线程: 一次运行数个对话, 在它们之间切换 ,然后独立取消 。 中止路径 每个线程,没有共享客户端状态. - 回合中向导队列: 当回合流堆起时提交信件 等待方向盘。 他们排出最老的第一 当转弯结束。 每个已排队的项目 现在可以发送( 中断当前转折)、 删除或拖曳到 重排队列 . - 导出 PDF 和 Markdown 菜单, 解析图表和表格 导出对话框仍然有用. ## 选择用户界面软件包 使用本地语言 `@databricks/appkit-ui` 因为它的原始人,AI/BI Genie聊天, 或带有本地 AppKit 插件的模型服务钩. 服务器时使用此软件包 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/node/appkit-mastra) 并且UI需要 了解马斯特拉特有的行为: - Mastra官方AI SDK聊天流,本土资源范围内存 API,并 插件的模型、建议、反馈、图表和语句路径. - 暂停 `requireApproval` 通过本地恢复工具呼叫 `resumeData`。 。 。 . - Genie 写作事件作为内在工具的进步,而不仅仅是 终极答案. - `[chart:]` 财务报告和审定财务报表 `[data:]` 作为ECharts图表提供的助理标记 和可分类的表格. - 同步多行串行,每行串行取消,并采用中转方向盘 队列。 运行时提交以排队、排出最老的先取或发送任何项目 立刻打断 本地的 AppKit 聊天表层 一次一个转 没有方向盘. - 解决这些嵌入到Markdown或PDF中的对话导出 . 在此软件包的样式表之前导入 AppKit UI 样式表 。 挂载聊天 在应用程序认证边界内。 代理聊天可以使用其中之一 根据服务器插件的用户身份或主要服务身份 配置 。 Direct Genie 聊天需要登录用户的半名 (OBO)语境. `MastraChat` 读取 `mastra` 插件已发布 `clientConfig()` 有效载数 通过 AppKit. 有效载荷提供挂载路径,默认代理,已注册 代理、反馈可用性、背景回合支持和聊天身份 行为 在浏览器代码中不要使用硬码插件路由. 使用 [@dbx-tools/ ui (英语)](https://npmcn.com/package/%40dbx-tools/appkit) 用于常见的 AppKit、认证、电子邮件和 搜索组件. ## 配置样式 ```css @import "@databricks/appkit-ui/styles.css"; @import "@dbx-tools/ui-mastra/styles.css"; ``` 样式表导入共享 `@dbx-tools/ui` 基金会和登记册 此软件包与 Tailwind 对应文件 。 它没有定义设计符. 这个 聊天UI使用来自主机应用程序的AppKit语义符号. ## 添加持续助手 挂载 `MastraAssistant` 在应用程序的现有认证门内及以上 路线出口。 关闭面板隐藏其演示文稿而不卸载 聊天驱动程序,所以草稿,线程,和活性流在页面导航中幸存. ```tsx import { MastraAssistant, useMastraAssistant } from "@dbx-tools/ui-mastra/react"; const AskAboutStore = ({ storeId }: { storeId: string }) => { const assistant = useMastraAssistant<{ storeId: string; route: string }>(); return ( ); }; export function App() { return ( ); } ``` `mode="dock"` 重回儿童申请. `mode="overlay"` 重叠. `side` 接受 `top`, (中文(简体) ), `right`, (中文(简体) ), `bottom`,或 `left`设置 `resizable={false}` 改为 锁大小, `launcher={false}` 当每次发射都来自 `useMastraAssistant()`, (中文(简体) ), `header={false}` 将新、历史和关闭放在旁边 谈话药 有了信头,这些控制就可以进入它 谈话药留在自己的第二行 替换 `icon`, (中文(简体) ), `closeIcon`, (中文(简体) ), `newConversationIcon`, (中文(简体) ), `historyIcon`,以及 `launcher.icon`下图 `mobileBreakpoint` 面板成为带有焦点的模式并带有逃逸模式 在申请无效的情况下予以解雇。 A 类 `storageKey` 保留 水平和垂直大小独立. `MastraAssistant` 关闭时仍然挂载,保存草稿、滚动 状态,活动流,以及独立的水平和垂直大小. ## 播放一个空闲聊天 ```tsx import { MastraChat } from "@dbx-tools/ui-mastra/react"; export function App() { return ( ); } ``` `MastraChat` 为 AppKit- Mastra 插件提供捆绑客户端。 它读到 插件已发布客户端配置, 创建 `MastraPluginClient`,流转 通过 Mastra 的官方 AI SDK 聊天路线,水合本地记忆,并制作 控件 `ChatView`当马斯特拉返回时 `messages` 无 预计算 `uiMessages` 使用 Mastra 的原生水分 `convertMessages(...).to("AIV5.UI")` 转换. 用这些选项配置客户端 : - `agentId` 选择注册代理,并默认为插件默认代理. - `genieSpace` 选择已配置的 Genie 化名并绕过代理. - `showModelPicker` 获取 `/models` 发送 `X-Mastra-Model` 超载. - `showSelectedModel` 将友好型号名称添加到助理脚下 一旦线路结束 混凝土的终点就悬浮 键盘焦点 。 默认关闭. - `metrics` 添加一个或多个右对齐的倒转页脚计数器 : `tokens`, (中文(简体) ), `time`, (中文(简体) ), `dbu`,或 `usd`默认关闭。 疏导或突出重点 度量组显示所有四个值,即使只有子集可见. - `enableRetry={false}` 隐藏重试动作 。 默认启用重试 . - `onModelRoute` 一旦路由完成,就收到混凝土终点. - `onModelUsage` 在每个完成后收到最新的累积符号 模型步骤,连同已解析的终点,智能路由器观测 可适用,加当Databricks公布象征性费率时估计的DBU费用. `onModelRoute` 并带有选定的标准列表价格行和 数据砖 $ - / - DBU 价格乘以云,使客户可以得出特定云 当响应文本仍在流出时成本. - `composerActions` 在模型旁放置主机自控每回合控件 选择器而不取代内置作曲器. - `modelSelectorActions` 将主机控件在模型菜单中放置,然后 选择终点。 只有在代理商支持时才能供应 选项,例如 Genie 传输切换. - `composerLeadingActions` 在左侧放置附件或应用程序动作 固定的作曲脚. 文字区域在上方会长到一顶,然后滚动. 建模和发送/停止在右下方固定 . - `suggestions` 覆盖 Genie 启动问题 。 用自动牵引 `/suggestions`,或通过 `[]` 隐藏建议. - `threadPlacement` 选择对话管理器的所在, 或翻转 关闭。 见 [放置对话列表](https://npmcn.com/package/%40dbx-tools/ui-mastra/#readme-place-the-conversation-list)。 。 。 . - `enableThreads: false` 另设 `threadPlacement: "disabled"`。 。 。 . - `threadId` 财务报告和审定财务报表 `onThreadIdChange` 让主机绑定当前对话 URL状态或另一个外部选择器. 未知的外部标识被替换为 一条新线程并随 `missing` 理由,你觉得呢. - `conversationHistory="browser"` 发送完整浏览器持有的记录 每一个转动 代理没有马斯特拉记忆。 默认 `"memory"` 因为马斯特拉线是 权威历史. - `browserPersistence` 存储本地存储的浏览器控件, 由插件挂载、代理、已签名的资源和线程进行范围化。 过 `true` 默认的 100 消息限制或 `{ maxMessages }` 来设定约束. - `enableExport` 增加了全程对接和每个消息的输出支付能力. - 自动反馈默认: 拇指、 不喜欢和注释控件出现时 服务器报告 ML流量反馈可用,并生成了跟踪 编号. 设定 `enableFeedback={false}` 藏起来 查看器为 `CAN_MANAGE` 打开 实验还得到了动作行末端的实验调试链接. 转会后后续跟进AppKit-Mastra发布的政策. 原生精灵 问题和持续存在的问题 `data-follow-up-suggestions` 部件使用相同的 近相复制过滤器和源回旋相机。 转弯后就解决了 最新的 提出的问题 `SuggestionPills` 在可滚动的末尾 记录 当下一个用户开始转动并保持可用时它们就会消失 在历史水合之后,因为所产生的建议在 辅助消息. ## 使用直接 Genie 聊天 使用 `genieSpace` 当应用程序需要同样的聊天 shell 没有 主管代理人 : ```tsx ``` 设定 `genieVisualization="image"` 显示Genie最初制作的PNG 在表格标签中保留链接查询结果的图表标签 : ```tsx ``` 别名来自服务器插件 `genieSpaces`。客户端仍然使用 AI SDK 软件 `UIMessage` 溪流和同样的 `ChatView`。精灵对话替换 Mastra 线条和Genie 消息仍然是可见的历史. 当马斯特拉 内存被配置,服务器会注入资源范围语义召回和 保存已完成的直接转会,而不取代Genie的对话所有权. 转身和历史需要天才特工API 永远不要回到经典 天才信息民调. 侧边栏过滤 Genie 对话列表 代理模式对话。 Genie决定一个查询是否应该可视化. 通过 AppKit UI 本地端渲染可视化附件 `GenieQueryVisualization`,带有图表和表格标签,除非图像模式 选中 。 这不援引主管或Mastra模式服务图表 计划员。 无查询 通过现有的可排序数据表渲染可视化附件 . 直接模式需要签名用户的Databricks OBO上下文. 它支持 新的/选择/删除对话、历史、建议、思想、出口 溪流取消。 它不支持对话重命名、 文件 附件、 ML流反馈、 批准、 背景转换或流 复相通达. 列出最新的100个对话,并分别选定 对话作为历史的一页. ## 放置对话列表 对话管理是默认的。 它住的地方是一个选择: ```tsx ``` | `threadPlacement` | 版式 | | --- | --- | | `auto` (默认) | `left` 谈话是宽广的, `top` 一旦它太窄 不适合面板 | | `left` 编号 : `right` | 列表停靠在那边上, 在狭义聊天时倒塌到覆盖抽屉中 | | `top` | 打开对话的标签条, 其余有历史菜单 | | `disabled` | 无线UI. 在会话 cookie上使用单个线索 | 相接位置使侧边栏成为一柱一柱的内置柱 显示/隐藏切换。 在聊天宽度的768px以下,面板变成一个覆盖抽屉 在同一个边缘,所以记录 永远不会失去空间。 抽屉是 会话扫描并开始关闭,选择后关闭. 编曲接受上传动作的图像,拖放或剪贴板 贴. 超大小的图像在提交前使用相同的客户端调整大小路径. 这个 `top` 放置为编辑器- tab 模式: 每一个打开的谈话都是标签 它的名号,在它的后方有旋转器 这只把标签从条子上取出(对话留在历史中)。 A 类 `+` 开始新的对话。 历史按钮打开完整的侧边栏作为 菜单,因此重命名、删除并取消尚未打开的对话框 标签条。 关闭活动标签移动到相邻的标签, 或 当最后一个标签打开时, 开始新的对话 。 打开的是 会话状态。 脱衣舞从最近的谈话中重新播音 装入. 对于代理支持的聊天,选择对话只获取最新的20个 本土记忆信息. 向上滚动请求下一页并预留 不动读者的取景口。 代理转动仍然只发送新用户 留言。 Mastra 装入记忆中的记录服务器侧. 直接精灵模式 将选定的Genie对话装入一页. `auto` 测量聊天本身的元素而不是取景端,所以是聊天 嵌入到分割视图或侧面板切换到它实际空间上的标签 而不是等待窗口收缩. ## 使用无头驱动程序 ```tsx import { ChatView, useMastraChat } from "@dbx-tools/ui-mastra/react"; export function CustomChat() { const chat = useMastraChat({ agentId: "analyst", showModelPicker: true, threadPlacement: "left", }); return ; } ``` 使用 `useMastraChat()` 需要用自己的软件包传输行为时 设置。 钩子拥有流线、中止、历史呼号、线程 选择、模型覆盖、建议、出口、批准和反馈状态. ## 密码键入应用程序上下文 `requestContext` 接受打入的简单记录, Mastra `RequestContext`,或一个 每回合解析器。 当一个消息被提交时, 驱动程序将它抓取到 保持该快照与排队方向盘,再生, 和批准续作. ```tsx import { RequestContext } from "@mastra/client-js"; type StoreContext = { storeId: string; route: string }; const chat = useMastraChat({ requestContext: () => new RequestContext([ ["storeId", selectedStore.id], ["route", location.pathname], ]), }); ``` 在服务器上,与Mastra的本地人宣布同样的合同 `requestContextSchema` 打开 `createAgent()`应用程序上下文 无法覆盖已认证的内存资源、线程、用户、范围、模型, 或由 AppKit-Mastra 所标记的跟踪字段。 直接 Genie 聊天同样转发 本地上下文作为唯一代理模式用户消息的参考数据. ## 构建一个可控聊天面 ```tsx import { ChatView, type ChatViewProps } from "@dbx-tools/ui-mastra/react"; export function ReviewChat(props: ChatViewProps) { return ; } ``` `ChatView` 是演示文稿。 它使标题,模型采摘者,谈话 边栏、记录、工具进度、批准卡、建议、出口管制、, 反馈控制 道具的作曲 当你的应用程序已经有一个 运输或需要将 Mastra 消息与另一种状态模式相结合. 设定 `showComposer={false}` 当母体表面拥有一个共享输入时, 例如 相邻模型比较. `MastraChat` 显示模型控件中的自旋器, 而其运行默认模式 正在解决。 采取者将终点组合成 模范家庭子菜单。 它的紧凑第一次弹出只显示当前 模型,主机拥有的动作,例如 Genie Agent Mode, 以及一个推理滑动器 选定的终点支持它。 目前的模式打开了家庭选手, 因此,长端点目录 保持出主控弹出。 家属 和模型菜单使用与作曲动作相同的紧凑工具类型, 省去重复的标题并省去已经选中的模型。 模型菜单上写着 `Default ()` 首先,保留 `Other` 最后,并制作一个单型 可直接选择的家族,而不是打开另一个子菜单. ## 直接调用插件路由 ```ts import type { MastraClientConfig } from "@dbx-tools/shared-mastra"; import { MastraPluginClient } from "@dbx-tools/ui-mastra/react"; export async function listChatModels(clientConfig: MastraClientConfig) { const client = new MastraPluginClient(clientConfig); return client.models(); } ``` 每个对话线程独立运行:打开一条线程,切换 到另一个并启动第二, 两条流同时。 使用它取消一个 `AbortSignal` (或驾驶员) `onCancelThread`) 而不接触他人. `MastraPluginClient` 扩展 `@mastra/client-js` 与官方AI SDK `chatRoute` 交通和AppKit-Mastra 添加。 用这个 `credentials: "include"` 因此会话 cookie 旅行与流和 REST 打电话 反应钩包 本地记忆 +模型目录,建议, 图表获取和语句数据获取。 使用 `useMastraClient()` 访问 在 React 内配置客户端 . `useMastraModels()`, (中文(简体) ), `useMastraDefaultModel()`, (中文(简体) ), `useMastraSuggestions()`,以及 `useMastraThreads()` 暴露特定路线状态 . ## 处理批准、嵌入和反馈 联合调查组了解了由 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/node/appkit-mastra)数字 : - 批准块成为内置批准卡并继续进行正式聊天 使用 Mastra 本地语言的路线 `{ approved, reason? }` 恢复数据. - 原生工具呼叫和工具结果有效载荷仍然完整。 扩展工具 行会显示默认关闭的请求和响应查看器 。 大值滚动 没有字符串或收藏节选. - 精灵 `thinking` 事件流入助理崩溃的思绪 显示面板。 中间答题附件和查询结果表留在工具上 进步,而不是思想。 其他写作活动仍附于工具 进展,包括SQL、行数、结果摘要和图表/数据 标记. - `[chart:]` 标记图缓存的长波并让 ECharts 内置. - `[data:]` 标记 列切换和 CSV 导出. - `[visualization:]` 标记以 OBO 身份获取相同的语句 创建 AppKit UI 本地的 Genie 图表/表组件 . - ML流痕头在服务器时启用每个消息反馈控制 报告有反馈. ## 配置图表主题 ECharts画到画布上,不会从画框中继承CSS的颜色. 这个 服务器规划器提供系列调色板和字体堆栈. 浏览器解析 appKit 语义符号中的轴、网格、标题、图例和工具提示颜色 提供时间. - 主题符号是从图表元素读取的, 所以一个主题范围是聊天 子树优先于文档主题。 图表在 文档 `.dark` 或者说 `.light` 类更改或操作系统时 颜色偏好变化. - AppKit 使其符号在下方变暗 `@media (prefers-color-scheme: dark)` 用于任何 `:root` 未明确 `.light`。如果您的主机使自己的光线 铬、针 `.light` (或 `.dark`继续 `:root` 而不是离开 AppKit上 操作系统偏好. PDF导出时在白打印文档上使用光线图主题. ## 导出对话框 ```tsx ``` 导出支持Markdown下载和PDF(通过隐藏的打印iframe交付,因此浏览器的Save-as-PDF对话框打开时没有弹出标签). 图表和数据标记为 导出时已解决 : 用 ECharts 服务器向内置 SVG 提供图表 渲染器和数据标记成为真正的表格。 过期或缺失的嵌入 这么老的笔录被跳过 仍然干净的输出. ## 复制和下载内容 复制和下载控制在消息泡、代码块、对话中出现 导出和数据网CSV菜单. 复制主机上的作品服务于普通的HTTP. 没有安全的环境 剪贴板 API, 这么空 `navigator.clipboard.writeText` 默不作声 a 当地或内联网部署。 软件包掉回隐藏的 `