# @astralbeam/sdk 中文文档

规范地址：https://npmcn.com/package/%40astralbeam/sdk/

版本：0\.30\.1
npm 元数据更新时间：2026-11-07T11:00:03.918Z
中文译文更新时间：2026-11-07T18:20:53.095Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40astralbeam/sdk
原文对照：https://npmcn.com/package/%40astralbeam/sdk/?lang=original
项目主页：https://astralbeam.ai/
源码仓库：https://github.com/AstralBeamAI/astralbeam

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

- 包体积（解压后）：2.6 MB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-08-19T11:45:48.997Z
- 最新版本发布：2026-11-07T11:00:03.609Z
- 近 30 天下载量：3152（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：74（近 12 个月 74 个）

## 中文简介

AstralBeam 前端 SDK: 滴入代理 UI, 聊天流和服务器帮助器

## 安装

```sh
npm install @astralbeam/sdk
```

也可以使用：`pnpm add @astralbeam/sdk`、`yarn add @astralbeam/sdk`、`bun add @astralbeam/sdk`

## README

# @ astralbeam/ sdk (英语)

在您的网络应用程序中嵌入代理聊天边栏或只读的租户目录, 或者用无头核心构建自己的聊天 UI 。 部件用阴影根孤立其风格.

```sh
npm install @astralbeam/sdk
```

## 快开始

React中的一个组件,一个功能在其它任何地方. 完整的设置,包括所需的符号端点,在 [开始](https://astralbeam.ai/docs/sdk/getting-started)。 。 。 .

```tsx
import { AstralBeamChat } from "@astralbeam/sdk/react"

export function Sidebar() {
  return (
    <aside style={{ height: "100dvh" }}>
      <AstralBeamChat />
    </aside>
  )
}
```

```ts
import { mountAstralBeamChat } from "@astralbeam/sdk/client"

const handle = mountAstralBeamChat(document.getElementById("sidebar")!, {})
// Update with handle.update({ colorScheme: "dark" }), then clean up with handle.unmount().
```

没有 npm 或 捆绑器, 请从 jsDelivr 从模块脚本中导入相同的条目 。 精确的版本和全文 `/dist/client.js` 路径,因为加载器导入了相对自身的懒散块. 见 [脚本标签](https://astralbeam.ai/docs/sdk/script-tag)。 。 。 .

```html
<div id="sidebar" style="height:100dvh"></div>
<script type="module">
  import { mountAstralBeamChat } from "https://cdn.jsdelivr.net/npm/@astralbeam/sdk@0.30.1/dist/client.js"

  mountAstralBeamChat(document.getElementById("sidebar"), {})
</script>
```

-   聊天横向调整大小并填充其母高. 你们应当高一些`min-h-0` 宽度.
-   聊天默认使用主机云. 托肯斯来自您的申请。 自我接待,设定 `apiUrl` 您的部署 `/api` 基础.
-   `@astralbeam/sdk/client` 没有反应 聊天内容是一个懒散的块,有它自己的捆绑副本.
-   没有运行时间依赖 . `react` 财务报告和审定财务报表 `react-dom` 是可选对等器,仅由 `@astralbeam/sdk/react`。 。 。 .
-   把它挂到路由器上 如果记录稿能活下来的话.

## 认证

您的服务器在部件可以聊天前必须认证主机会话并刻出聊天符 。 只保留 API 密钥服务器 。 见 [认证](https://astralbeam.ai/docs/sdk/authentication)。 。 。 .

替换 `getApplicationSession` 下面是您的应用程序认证的会话查询。 返回当前用户及其经核实的客户账户成员身份 `session.user` 财务报告和审定财务报表 `session.tenant`。 。 。 .

```ts
import { createAstralBeamToken } from "@astralbeam/sdk/server"

const apiKey = process.env.ASTRALBEAM_API_KEY // key_<organizationId>_<id>_abo_<secret>

export async function POST(request: Request) {
  const headers = { "Cache-Control": "no-store" }
  if (!apiKey) return Response.json({ error: "Not configured" }, { status: 503, headers })
  const session = await getApplicationSession(request)
  if (!session) return Response.json({ error: "Unauthenticated" }, { status: 401, headers })
  try {
    const token = await createAstralBeamToken({
      apiKey,
      user: {
        id: session.user.id,
        name: session.user.name,
        metadata: { email: session.user.email },
      },
      tenant: {
        id: session.tenant.id,
        name: session.tenant.name,
        metadata: { plan: session.tenant.plan },
      },
    })
    return Response.json({ token }, { headers })
  } catch {
    return Response.json({ error: "Token could not be issued" }, { status: 500, headers })
  }
}
```

-   认证一次并获得稳定 `user.id` 财务报告和审定财务报表 `tenant.id` 来自该信任会话的值.
-   只保留 API 密钥服务器 。 托肯斯是签名的,而不是加密的,所以他们的诉求必须包含任何秘密.
-   返回时 `Cache-Control: no-store` 当配置或认证缺失时,则关闭失败.
-   目录访问额外需要签名 `user.admin: true`,并坚持记录。 跟随 [租户目录](https://astralbeam.ai/docs/sdk/listings)。 。 。 .
-   租户管理,使用 `createAstralBeamOrganizationToken`编辑 [API 客户端指南](https://astralbeam.ai/docs/sdk/api) 涵盖数据库支持的角色和浏览器集成.

在获得一个符号后, 组件调用 `POST /api/v1/me` 并在期满前续约。 见 [认证和刷新行为](https://astralbeam.ai/docs/sdk/authentication)。 。 。 .

## 选项

通过选项作为回放道具或应用子集 `handle.update(options)`。演示文稿更改保留聊天。 变化 `threadId` 选择对话,并更改 `apiUrl` 清除之前部署的状态。 见 [配置](https://astralbeam.ai/docs/sdk/configuration) 用于所有选项、默认、布局和铬槽.

大多数嵌入器都让 `<AstralBeamChat {...options} />` 管理会话。 对于外部控制,创建 `chat` 与 `useAstralBeamChat(options)` 提供 `<AstralBeamChat chat={chat} />`。在钩上配置认证和工具,在视图上配置部件和外观。 直接调用动作 `chat` 读取状态 `chat.getState()`。 。 。 .

对话会自动被保存,然后从私人开始。 部件搜索保存了对话标题 。 重新打开历史不执行较早的工具调用 。 断接可以中断当前响应.

无头会话暴露出对话的导航,搜索,和相扑. 与 `useAstralBeamChat`,通过 `chat`,例如 `chat.openThread(threadId)`。历史一次加载一页. `reset()` 启动新聊天并保留保存的聊天.

下载附件 `chat.getThreadAttachment({ threadId, fileId })`时返回 a `Blob`组织和参与者租户范围来自您的全权证书。 行政下载也通过 `tenantId`启用 `{ preview: true }` 作为缩略语的第二个论据。 只有未发送的上传预览可以省略 `threadId`。 。 。 .

默认, `threadId: "auto"` 使用会话存储重新装入后恢复此标签的选择, 范围为当前账户, API, 以及 `placementKey ?? agentId ?? "default"`。在与同一代理进行独立聊天时,使用不同的定位键。 一个新的独立打开的标签开始一个新的聊天. 使用 `threadId: "new"` 以绕过恢复,或通过已保存的线程 UUID。 部件保存未发送的文本, 并在本地存储、 账户、 API 和对话中上传文件引用 。 重新打开恢复了草稿而不自动发送. 主机拥有侧边栏能见度,可以在会话存储中单独坚持.

## 工具和部件

一个工具做一些事情:它 `execute` 运行在您的页面。 一个部件显示一些东西:它的 `render` 让你的UI进入对话。 双方均宣布 `description` (单位:千美元) `parameters` 计划 见 [工具和部件](https://astralbeam.ai/docs/sdk/tools-and-widgets)。 。 。 .

```tsx
tools: {
  restart_service: {
    metadata: { title: "Restart a service" },
    description: "Restart one of the host app's services by name",
    parameters: { type: "object", properties: { service: { type: "string" } }, required: ["service"] },
    execute: async ({ service }) => await restartService(String(service)),
  },
},
widgets: {
  systemStatus: {
    description: "Shows the current status of the host app's systems",
    parameters: { type: "object", properties: { degraded: { type: "boolean" } } },
    render: ({ degraded }) => <StatusCard degraded={Boolean(degraded)} />,
  },
}
```

-   斯克马斯是普通的JSON斯克马或任何 [标准Schema](https://standardschema.dev/) 验证符(Zod, Valibot, ArkType).
-   只有标准Schema验证浏览器中的输入. 与平原JSON Schema,将输入视为不信任.
-   从工具返回纯 JSON 值, 无 `undefined` 字段。 如果无法发送结果,行动可能仍然发生.

## MCP 连接

远程工具出现在 **MCP 连接** 在经过认证的租户部件中。 组织管理员配置可用的MCP服务器. 每个租户用户都会建立自己与服务器的连接. 支持公共端点,静态头和OAuth. 工具结果遵循了对话的能见度和保留规则. 断开连接从 AstralBeam 中删除已保存的连接及其证书 .

无头消费者可以使用 `chat.getMcpCatalog()`, (中文(简体) ), `chat.manageMcpConnection(operation)` 财务报告和审定财务报表 `chat.authorizeMcpConnection({ mcpServerId, id? })`。从用户手势开始 OAuth 打开弹出。 浏览器绑定并补全使用经认证的会话 。 服务器工具标题到达 `state.serverToolTitles`,独立于主机工具执行.

重用仪表盘的服务器列表和格式 `AstralBeamMcpServers` 从 `/react` 或者说 `mountAstralBeamMcpServers` 从 `/client`。提供服务器列表和授权的回信。 见 [MCP 服务器管理](https://astralbeam.ai/docs/sdk/configuration#mcp-server-management)。 。 。 .

## 文档

| 指南 | 封面 |
| --- | --- |
| [API 客户端](https://astralbeam.ai/docs/sdk/api) | 用 API 密钥或 JWTs 键输入了资源和聊天请求. |
| [开始](https://astralbeam.ai/docs/sdk/getting-started) | 安装、挂载、布局要求. |
| [脚本标签](https://astralbeam.ai/docs/sdk/script-tag) | 从jsDelivr装入 没有捆绑, 和Ruby在铁路. |
| [认证](https://astralbeam.ai/docs/sdk/authentication) | 标志性终点、安全规则以及用其他语言计价. |
| [租户目录](https://astralbeam.ai/docs/sdk/listings) | 提供、租户和用户列表、保存对话浏览、生命周期和选项. |
| [配置](https://astralbeam.ai/docs/sdk/configuration) | 每个选项,什么 `update` 可以改变. |
| [他们](https://astralbeam.ai/docs/sdk/theming) | 彩色方案 CSS标志 阴影根边界. |
| [工具和部件](https://astralbeam.ai/docs/sdk/tools-and-widgets) | 计程车 现场直播 把记录录下来. |
| [附录](https://astralbeam.ai/docs/sdk/attachments) | 文件类型、限制、端点执行的内容. |
| [限制](https://astralbeam.ai/docs/sdk/limits) | 请求、附件和沙盒限制. |
| [沙盒](https://astralbeam.ai/docs/sdk/sandbox) | 步骤、选入面板、下载、内置图像. |
| [无头](https://astralbeam.ai/docs/sdk/headless) | 在同一会话中拥有整个聊天 UI . |
| [安保模式](https://astralbeam.ai/docs/sdk/security) | 谁给予,谁执行, 什么客户可以改变. |

## 入境点

仅可阅读的租户、租户用户和谈话部件来自 `/client` 财务报告和审定财务报表 `/react`。见 [租户目录](https://astralbeam.ai/docs/sdk/listings) 用于设置和嵌入示例.

反应目录 refs 曝光 `refresh()` 财务报告和审定财务报表 `reset()`,两个返回 `Promise<void>`。使用道具进行更新和有条件的渲染以卸载。 香草手柄也暴露出来 `update()` 财务报告和审定财务报表 `unmount()`。在退出或身份更改时卸载。 见 [生命周期合同](https://astralbeam.ai/docs/sdk/listings#account-changes-and-lifecycle) 用于认证、缓存、再挂载再利用和动作完成.

没有根导出 .

| 入境点 | 目录 | 同伴依赖关系 |
| --- | --- | --- |
| `@astralbeam/sdk/client` | 聊天、目录和 MCP 服务器挂载 | 无 |
| `@astralbeam/sdk/core` | `createAstralBeamChat`,无头会议 | 无 |
| `@astralbeam/sdk/react` | 聊天钩和孤立的 UI 包装 | `react`, (中文(简体) ), `react-dom` |
| `@astralbeam/sdk/server` | 租户和组织 | 无 |
| `@astralbeam/sdk/api` | 资源和聊天 HTTP 助手 | 无 |

每个类型Script模块解析模式下的类型解析,包括经典 `"moduleResolution": "node"`。要求类型脚本 5.0 或稍后,因为声明使用 `const` 类型参数,无法解析 TypeScript 4.x.

## 实例

[`examples/linearity-react`](https://npmcn.com/package/%40astralbeam/examples/linearity-react) 是一个 TanStack Start和shadcn/ui 项目跟踪器,有两个工作空间,局部Storage 坚持性,以及一个名叫Astro的助手. 它展示了经验证的工具、现场发行卡、房客换乘以及托管游乐场的基本Auth门.

[`examples/todos`](https://npmcn.com/package/%40astralbeam/examples/todos) 嵌入侧边栏和一个租户范围用户在最小的 TanStack Start app 上市. 两者都使用相同的演示符号路由. 该应用程序还显示主机工具大于活的React状态和 a `todoCard` 部件,没有自带的尾风或阴影/ ui .

[`examples/todos-rails`](https://npmcn.com/package/%40astralbeam/examples/todos-rails) 是铁路8号的Ruby的同名应用软件. 它通过导入地图从jsDelivr装入SDK,从平版ES模块装入它,薄荷符与 `jwt` 并给代理工具 通过应用程序的JSON API.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40astralbeam/sdk/LICENSE)

## 常见问题

### @astralbeam/sdk 是什么？

AstralBeam 前端 SDK: 滴入代理 UI, 聊天流和服务器帮助器

### 如何安装 @astralbeam/sdk？

在项目目录运行 npm install @astralbeam/sdk，或使用 pnpm add / yarn add / bun add。

### @astralbeam/sdk 支持 TypeScript 吗？

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

### @astralbeam/sdk 支持 ESM 还是 CommonJS？

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

### @astralbeam/sdk 可以商用吗？

@astralbeam/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @astralbeam/sdk 的下载量有多少？

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

### @astralbeam/sdk 还在维护吗？

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