# @dbx-tools/genie 中文文档

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

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

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

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

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

- 包体积（解压后）：178 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：sharp ^0\.35\.5
- 首次发布：2026-06-07T18:54:21.208Z
- 最新版本发布：2026-11-10T19:19:50.146Z
- 近 30 天下载量：9802（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：420（近 12 个月 420 个）

## 中文简介

服务器侧数据砖 精灵聊天驱动程序

## 安装

```sh
npm install @dbx-tools/genie
```

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

## README

# @dbx-工具/基因

运行 Databricks Genie 从节点或 AppKit 代码转换为原始信件快照或 键入事件流。 AppKit 请求保持其半用户( OBO) 身份,独立呼叫者使用Databricks SDK认证链,以及 两种模式都支持取消.

## 快开始

```ts
import { chat } from "@dbx-tools/genie";

const spaceId = process.env.DATABRICKS_GENIE_SPACE_ID!;

for await (const event of chat.genieEventChat(spaceId, "Top stores by revenue?")) {
  console.log(event.type, event);
}
```

纯精灵计划与事件探测器帮助者 [@dbx-工具/共享基因](https://npmcn.com/package/shared/genie)。 。 。 .

驾驶员:

-   默认流出 Genie Agent 模式 API,包括推理, SQL 调用, 查询输出,以及合成的答案.
-   开始新的 Genie 对话或继续已有的对话 `conversationId`。 。 。 .
-   项目代理 模式 响应项目到现有的 `GenieMessage` 简介 和语义-活动合同,包括声明标识和可视化 附录.
-   装入代理模式对口项目并将其重新组合到一个 `GenieMessage` 每回转历史播放.
-   保留对话 API 投票驱动程序 `agentMode: false` 作为 自动流前倒置 `FEATURE_DISABLED` 或预览切换 错误.
-   将原始的 Genie 信件转换成语义事件用于思考文本, 生成 SQL,行数,最终结果,以及出错.
-   在 AppKit 请求中调用时保存 AppKit OCO 认证, 但也工作 从带有普通 Databricks SDK 认证的独立脚本.
-   接受 SDK `Context` 网络 `AbortSignal` 取消路由处理器和 CLI工具.
-   获取 Genie 空间元数据和启动问题供 UI 推荐 .

## 选择基因集成

使用本地 AppKit 的 Genie 插件进行独立的 Genie 聊天体验 。 这个 提供命名的空间别名、 SSE 状态更新、 对话 历史重放、 查询结果获取、 OBO 执行和 AppKit UI `GenieChat` 组件.

当一个Genie空间拥有谈话和回答时使用直接Genie. 使用 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/%40dbx-tools/appkit-mastra) 当监督代理人必须 将Genie与其他工具,Mastra内存,批准,或工作流程相结合. 使用 当自定义后端代码需要下层流时, 直接使用此软件包 :

-   您想要一个低级的同位素执行器, 而不是 AppKit HTTP 路径 .
-   您想要原始消息快照或可被输入的正态事件流 输入 Mastra 写入事件、日志、测试或自定义 SSE 端点.
-   你需要散发快照 并只发出新观察到的思维 SQL,行, 结果和出错事件.
-   您想要将 Genie 的回答和代理侧图规划、 语句合并 行取取,或自在的持久线程存储 .
-   你需要同一个司机 在AppKit和OBO Auth以及外面工作 使用普通 Databricks SDK 认证的脚本的 AppKit.

## 处理语义事件

```ts
import { chat } from "@dbx-tools/genie";

for await (const event of chat.genieEventChat(spaceId, "Top stores by revenue?")) {
  switch (event.type) {
    case "thinking":
      console.log(event.thought_type, event.text);
      break;
    case "query":
      console.log(event.sql);
      break;
    case "rows":
      console.log(event.row_count);
      break;
    case "result":
      console.log(event.status);
      break;
  }
}
```

`chat.genieEventChat()` 覆盖下层快照流并生成 a `GenieChatEvent` 工会。 用于 SSE 流、日志管道和工具写入器 消费者关心进步和SQL而不只是终端的事件 留言.

## 流出原始信件快照

```ts
import { chat } from "@dbx-tools/genie";

for await (const message of chat.genieChat(spaceId, "Top stores by revenue?")) {
  renderSnapshot(message);
}
```

`chat.genieChat()` 启动代理模式响应或继续已有 对话框,项目 SSE 输出到 `GenieMessage` 示意图、过滤器 相同的连续有效载荷, 并在终端响应后停止。 设定 `agentMode: false` 来强制对话 API 启动/创建/获取消息 投票流程。 使用它,当你想运行自己的 diffing 或坚持 电线形状正常 代理模式返回内含的查询输出为 Markdown 和 复制查询输出 `statement_id` 在匹配的查询附件上 数据砖供应一.

## 继续谈话

```ts
let conversationId: string | undefined;

for (const prompt of prompts) {
  for await (const event of chat.genieEventChat(spaceId, prompt, { conversationId })) {
    if ("conversation_id" in event && event.conversation_id) {
      conversationId = event.conversation_id;
    }
  }
}
```

呼叫者通过读取对话的ID来保持多回合状态 消息或事件,并传递到下一个转折。 这在无国籍状态下有效 路由处理器、耐用线程商店和一次性脚本。 AppKit- Mastra 仓库 和它的线 并传递回来,当一个谈话继续.

## 解决工作空间客户端

```ts
import { createWorkspaceClient } from "@databricks/appkit";
import { chat } from "@dbx-tools/genie";

await chat.genieEventChat(spaceId, content, {
  workspaceClient: createWorkspaceClient(),
});
```

客户解析命令 :

1.  `options.workspaceClient`。 。 。 .
2.  AppKit 执行语句客户端, 当存在时 .
3.  `createWorkspaceClient()` 使用 AppKit 的普通 Databricks 认证链.

过 `options.context` 作为 `AbortSignal` 或 SDK 上下文以取消代理 模式流,SDK电话, 和任何投票倒计时睡眠.

## 读取空间元数据和启动问题

```ts
import { space } from "@dbx-tools/genie";

const genieSpace = await space.getGenieSpace(spaceId);
const questions = space.genieSampleQuestions(genieSpace);
```

`space.getGenieSpace()` 获取空间定义,包括序列化空间 默认的元数据. `space.genieSampleQuestions()` 提取自定义启动器 问题和返回 `[]` 当没有配置时.

序列化的blob需求 `Can Edit` 空间,同时 `Can Run` 足够了 标题和说明。 当工作空间拒绝序列化请求时 未经许可, `getGenieSpace()` 重复一次没有它和日志 `serialized-space:forbidden`,所以应用程序服务本金只持有 `Can Run` 仍然解决空格,没有报告开始的问题。 每一个 失败, 如请求被取消, 空格缺失, 或是重试, 也可以 失败, 被丢弃 .

## 选项

`chat.GenieChatOptions` 由两个驱动程序共享:

-   `conversationId` - 加入已有的精灵对话.
-   `agentMode` - 使用代理模式 SSE,默认 `true`。 。 。 . `false` 部队投票.
-   `agentModeFallback` - 回到典型的民调 当代理Mode是 不可用, 默认 `true`。直接代理呼叫器设置 `false`。 。 。 .
-   `enableVisualization` - 请求代理模式可视化生成.
-   `workspaceClient` - 明确的Databricks SDK客户端.
-   `pollIntervalMs` - 倒计时投票,默认 `500`。 。 。 .
-   `context` - SDK(英语:SDK) `Context` 或者说 `AbortSignal` 用于取消.

## 下载图表图像

在请求可视化后,请用一个 `viz` 字段,并使用相同的对话和消息ID下载其PNG:

```ts
import { downloadGenieVisualization } from "@dbx-tools/genie";

const visualization = message.attachments?.find((attachment) => attachment.viz);
if (visualization?.attachment_id) {
  const png = await downloadGenieVisualization(
    {
      space_id: message.space_id,
      conversation_id: message.conversation_id,
      message_id: message.message_id,
      attachment_id: visualization.attachment_id,
    },
    { workspaceClient },
  );
}
```

使用可视化附件ID,而不是其链接的查询附件ID. SDK的车 `raw: true` 运输返回二进制正文并保持正常的 SDK 认证和取消。 帮助者验证了PNG的反应,然后 使用可选 `sharp` 需要将其大小调整为原来的四倍 与Lanczos3相接的宽度和高度,并应用了轻度的无尖口罩. 若为 `sharp` 没有 安装或无法处理图像, 帮助者返回已验证的 原字节. 处理发生在字节返回呼叫者之前,所以 下游缓存在增强成功时存储增强后图像.

这是光栅清理后退。 如果源 Ekharts 实例可用, 首选项 `getDataURL({ pixelRatio: 3 })` 或 SVG 这样图表文本被重置 而不是从截图上放大。 终点也接受可视化 来自代理模式对话的附件 .

## 模块

-   `chat` - 说吧 `genieChat()` 原始快照流和 `genieEventChat()` 类型事件 流线.
-   `agentMode` - 说吧 `genieAgentModeChat()`和代理人 模式传输选项加上代理模式对话历史 .
-   `space` - 说吧 `getGenieSpace()` 财务报告和审定财务报表 `genieSampleQuestions()`。 。 。 .
-   `visualization` - 说吧 `downloadGenieVisualization()` 用于验证和可选增强的PNG下载.

AppKit-Mastra软件包在此驱动程序上方构建了它的Genie工具. 见 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/%40dbx-tools/appkit-mastra) 用于代理级 工作流程.

## 常见问题

### @dbx-tools/genie 是什么？

服务器侧数据砖 精灵聊天驱动程序

### 如何安装 @dbx-tools/genie？

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

### @dbx-tools/genie 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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