# @fusioni/client-sdk 中文文档

规范地址：https://npmcn.com/package/%40fusioni/client-sdk/

版本：1\.1\.42
npm 元数据更新时间：2026-11-12T16:50:09.653Z
中文译文更新时间：2026-11-15T20:04:11.809Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fusioni/client-sdk
原文对照：https://npmcn.com/package/%40fusioni/client-sdk/?lang=original

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

- 包体积（解压后）：5.8 MB，171 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2026-03-26T09:23:44.829Z
- 最新版本发布：2026-11-12T16:50:09.445Z
- 近 30 天下载量：3094（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

Fusioni SDK 用于网络应用程序

## 安装

```sh
npm install @fusioni/client-sdk
```

也可以使用：`pnpm add @fusioni/client-sdk`、`yarn add @fusioni/client-sdk`、`bun add @fusioni/client-sdk`

## README

# 幻想聊天SDK

一个反应TypeScript SDK,用于将Fusioni Chat功能整合到网络应用中. 这个 SDK 提供了一个可以嵌入到任何网页的浮动聊天部件,提供 AI 驱动的聊天能力,支持文本,图像和音频消息.

## 特征

-   🤖 **AI 聊天接口** - 提供实时信息的现代、响应性聊天UI
-   🎤 **音频记录** - 录音和回放语音信息支持
-   📁 **文件上传** - 图像上传和预览功能
-   💬 **对话管理** - 创建、管理和删除对话
-   🎨 **自定义主题** - 有自定义颜色的浅/暗主题支持
-   📱 **响应设计** - 桌面和移动设备无缝工作
-   🔄 **实时更新** - 实时消息流的服务器发送事件
-   🛡️ **类型脚本支持** - 全面安全和情报支持
-   **小型应用程序** - 按位置或标记选择的可信任的网络组件捆绑或收藏
-   **搜索** - 用页码、输入式自动完成和自定义结果容器进行聚合数据搜索

## 安装

你可以用SDK的两种方式:

### 作为图书馆( npm)

```bash
npm install @fusioni/client-sdk
```

### 作为脚本( 没有构建步骤)

在您的页面上添加一个脚本标签 。 浏览器捆绑是一个 **IIFE (英语)** (文件名称仍然) `fusioni-sdk.umd.js` 用于 CDN URL : 它指定全局 `Fusioni` 包括反应和风格。 IIFE是用来代替经典UMD的 `Fusioni` 即使主机页面的捆绑器定义了普通JS,仍然正确 `module`编号 :`exports` 同一范围(UMD方案) `Fusioni` 作为 `{}` (见a/cn.9/wg.iii/wp.iii/wp.1号文件).

```html
<script src="https://unpkg.com/@fusioni/client-sdk/dist/fusioni-sdk.umd.js"></script>
<!-- or use your own path -->
<script src="/path/to/fusioni-sdk.umd.js"></script>
```

## 快速启动

### 基本用途

```tsx
import React from 'react';
import { ChatWidget } from '@fusioni/client-sdk';

function App() {
  const config = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token', // Optional
    theme: 'light', // 'light' | 'dark' | 'auto'
    position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    primaryColor: '#6366f1',
    showConversationList: true,
    enableAudioRecording: true,
    enableFileUpload: true,
    maxFileSize: 10, // MB
    allowedFileTypes: ['image/*']
  };

  return (
    <div className="App">
      <h1>My Website</h1>
      <ChatWidget config={config} />
    </div>
  );
}

export default App;
```

### 脚本tag 使用( 不需要 React app)

包含通过 `<script src="...">`SDK暴露了一个全球 `Fusioni` 对象。 不需要建立步骤或反应设置 .

**初始化一次和链式特性 :**

```html
<label for="site-search">Search the site</label>
<input id="site-search" type="search">
<div id="search-widget"></div>
<div id="mini-apps"></div>
<div id="actions"></div>

<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const sdk = Fusioni.init({
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token'
  })
    .search('#search-widget', {
      mode: 'autocomplete',
      inputElement: '#site-search'
    })
    .mountMiniApp('#mini-apps', {position: 'dashboard'})
    .mountActionButtons('#actions', {tags: ['tools']})
    .chatWidget();

  // sdk.getSearch('#search-widget').search('setup');
  // sdk.getMiniApp('#mini-apps').run();
  // sdk.getActionButtons('#actions').executeAction('report');
  // sdk.getChatWidget().setLanguage('el');
  // sdk.unmount('#search-widget'); // Unmount one feature.
  // sdk.unmount();                 // Unmount all features belonging to this instance.
</script>
```

`init()` 初始化共享设置和默认的 API 客户端而不创建 UI 或请求 。 每个挂载方法返回相同 `FusioniSDKInstance`特征继承 `apiBaseUrl`, (中文(简体) ), `agencyId`, (中文(简体) ), `accessToken`,和配置的语言;搜索也继承主题。 每个地物选项可以覆盖这些默认或提供明确 `apiClient`。搜索、 Mini Apps 和 Action Buttons 在创建另一个实例时保留其初始化的连接,并且将清理范围扩大到每个实例.

每个后端API请求包括 `agency_id` 在查询字符串中,包括POST/PUT请求其JSON正文也包含. SDK从初始或每个地貌机构提供,而明确要求的参数优先。 对于低级使用,将代理作为第三个论据传递至 `new ApiClient(apiBaseUrl, accessToken, agencyId)` 或者说 `initializeApiClient(apiBaseUrl, accessToken, agencyId)`。在发出请求前,未对请求进行范围审查的请求被拒绝.

`.chatWidget()` 明确挂载浮动聊天。 使用 `.chatWidget({theme: 'dark'})` 用于聊天覆盖或 `.chatWidget('#my-chat', {theme: 'dark'})` 用于特定的容器。 可连锁 `.mount()` 方法也可以作为聊天别名. `.search()` 财务报告和审定财务报表 `.mountSearch()` 在初始化的情况下是别名.

**移徙:** `Fusioni.init(config)` 以前自动挂载的聊天。 使用 `Fusioni.init(config).chatWidget()` 以保持这种行为。 要访问聊天控制, 请使用 `sdk.getChatWidget()`; 独立 `Fusioni.mount(container, config)` 仍然直接返回聊天控点 .

**默认位置( 浮动聊天部件) :**

```html
<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  Fusioni.init({
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1',
    showConversationList: true,
    showThoughts: false,
    enableAudioRecording: true,
    enableFileUpload: true,
    maxFileSize: 10,
    allowedFileTypes: ['image/*']
  }).chatWidget();
</script>
```

**挂入特定容器 :**

```html
<div id="my-chat"></div>
<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  Fusioni.mount('#my-chat', {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  });
  // Optional: unmount or change language/theme later
  // const result = Fusioni.mount('#my-chat', config);
  // result.unmount();
  // result.setLanguage('el');
  // result.setTheme('auto');
</script>
```

**脚本 API :**

| 方法 | 说明 |
| --- | --- |
| `Fusioni.init(config)` | 初始化共享设置并返回可链条 `FusioniSDKInstance`;挂载无UI. |
| `Fusioni.mount(container, config)` | 装入 `container` (CSS 选择字符串或 `HTMLElement`) (中文(简体) ). 回返 [`FusioniMountResult`](https://npmcn.com/package/%40fusioni/client-sdk/#readme-changing-language-and-theme-after-init)。 。 。 . |
| `Fusioni.mountSearch(container, props)` | 挂载 [搜索](https://npmcn.com/package/%40fusioni/client-sdk/#readme-search),可选择性地约束现有输入,并生成一个单独要素. |
| `Fusioni.mountMiniApp(container, props)` | 挂起迷你Apps并返回他们的手柄. |
| `Fusioni.mountActionButtons(container, props)` | Mounts Action按钮并返回其手柄. |
| `Fusioni.version` | SDK版本字符串. |

初始化案例提供 `chatWidget`, (中文(简体) ), `search`, (中文(简体) ), `mountMiniApp`,以及 `mountActionButtons`,所有返回 同一实例. `getChatWidget`, (中文(简体) ), `getSearch`, (中文(简体) ), `getMiniApp`,以及 `getActionButtons` 返回相应的组件控件,或 `null` 当此实例没有匹配挂载时 . `unmount(container?)` 清理一个或所有由实例拥有的挂载。 集装箱可以是CSS选取器或DOM元件;组件把手一挂起即可使用.

### 搜索

`Search` 支持两种模式: `search` (默认)呼叫 `FusionDataResource.search_paginated` 提交时,和 `autocomplete` 电话 `FusionDataResource.search_autocomplete` 作为用户类型。 选择结果 `url` 在当前标签中。 没有可用的 HTTP( S) 或相对 URL 的结果作为非交互式项目显示 .

**反应 :**

```tsx
import {Search} from '@fusioni/client-sdk';

function SiteSearch() {
  return <Search
    apiBaseUrl="https://your-fusioni-api.com/api"
    agencyId="your-agency-id"
    accessToken="your-access-token"
    mode="autocomplete"
    placeholder="Search the site…"
  />;
}
```

搜索包括自己的范围样式. 切换到 `mode="search"` 对于带有前一个/下一个控件的搜索窗体。 在自动完成模式下,在页面滚动或调整大小时会随输入而下放. 使用 Up/ Down 来选择, Enter 来跟踪结果, 而 Escape 则去掉 .

**脚本标记, 绑定在您现有的输入上 :**

```html
<label for="site-search">Search the site</label>
<input id="site-search" type="search" placeholder="Search…">
<div id="search-widget"></div>

<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const search = Fusioni.mountSearch('#search-widget', {
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    mode: 'autocomplete',
    inputElement: '#site-search'
  });

  // search.search('setup'); // Run immediately, skipping the debounce.
  // search.clear();
  // search.focus();
  // search.unmount();
</script>
```

离开 `inputElement` 制造SDK自己的球场 将装入的容器与装入的输入相分离,因此装入不能将其取出。 卸载会移除下放,取消待定的工作,并恢复输入的原始自動完整和可访问性属性.

**渲染结果为:**

```html
<form>
  <label for="query">Search</label>
  <input id="query" type="search">
  <button type="submit">Search</button>
</form>
<div id="search-controller"></div>
<section id="search-results" aria-label="Search results"></section>

<script>
  const search = Fusioni.mountSearch('#search-controller', {
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    mode: 'search',
    inputElement: '#query',
    resultElement: '#search-results',
    pageSize: 10
  });
</script>
```

`inputElement` 财务报告和审定财务报表 `resultElement` 接受 CSS 选择器或 DOM 元素在 React 和脚本标签使用中。 搜索挂载时, 元素必须存在 。 所提供的结果要素在两种模式中都收到内入结果,保留其现有子女;没有这种结果,自动完成将使用下放,全面搜索将低于其域。 输入或提交绑定输入的表单运行搜索.

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `agencyId` | 需求 | 联合机构要搜索. |
| `apiBaseUrl`, (中文(简体) ), `accessToken` | 初始化的 SDK 客户端 | 连接设置 。 替代供应 `apiClient`。 。 。 . |
| `mode` | `'search'` | `'search'` 或者说 `'autocomplete'`。 。 。 . |
| `inputElement` | SDK 字段 | 现有输入选择器或 `HTMLInputElement`。 。 。 . |
| `resultElement` | 自动放置 | 结果选择者或 `HTMLElement`。 。 。 . |
| `pageSize` | `25` | 请求的页面大小 。 Fusion目前以10个建议自动完成封顶,无论这个值如何. |
| `minLength` | `2` | 在请求结果前最小修剪了查询长度 。 空问从不请求结果 . |
| `debounceMs` | `250` | 输入自动完成模式时出现延迟 . |
| `label`, (中文(简体) ), `placeholder` | 本地化搜索文本 | SDK自己的字段的文本. 在主机页面上标记外部输入 . |
| `currentLanguage` | `'en'` | `'en'` 或者说 `'el'`。 。 。 . |
| `theme` | `'light'` | `'light'`, (中文(简体) ), `'dark'`,或 `'auto'`。 。 。 . |
| `className`, (中文(简体) ), `style` | —— 说 | 根样式;内置样式也适用于出入口结果面板. |
| `onResults(response)` | —— 说 | 接收 `{body, pagination}` 在成功请求后. |
| `onError(error)` | —— 说 | 接收请求错误; UI 也提供重试 . |
| `onSelect(item)` | 导航到 `item.url` | 返回时 `false` 防止导航,例如,在使用您的应用程序的路由器处理时. |

脚本挂载返回 `search(query?, page?)`, (中文(简体) ), `clear()`, (中文(简体) ), `focus()`, (中文(简体) ), `unmount()`,则只读 `results` 财务报告和审定财务报表 `pagination`在反应中,附加一个 `ref` 类型 `SearchHandle` 用于同一API的除外 `unmount()`。页码为零。 新输入立即取消待决请求,而更古老的响应无法覆盖新的结果.

在没有UI的情况下获取时,使用明确输出的服务 `ApiClient` 或初始化的 SDK 客户端 :

```ts
import {ApiClient, SearchService} from '@fusioni/client-sdk';

const search = new SearchService(new ApiClient('https://your-fusioni-api.com/api', 'your-access-token', 'your-agency-id'));
const suggestions = await search.autocomplete('your-agency-id', 'set');
const results = await search.search('your-agency-id', 'setup guide', {page: 0, size: 10});
// Both return {body: SearchItem[], pagination: SearchPagination | null}.
// Options also accept an AbortSignal as `signal`.
```

两种方法 `{agency_id, inp}` 与 `agency_id`, (中文(简体) ), `page`,以及 `size` 查询参数。 自动完成使用 `/sdk-client/dasearch`; 全部搜索用途 `/sdk-client/dpsearch`使用 SDK 的请求 `ApiKey` 认证和要求 Fusion 数据视图访问.

### 输入后更改语言和主题

聊天手柄( 在 TypeScript 中: `FusioniMountResult`包括 **`setLanguage`** 财务报告和审定财务报表 **`setTheme`** 从而可以在不重挂的情况下切换地盘或外观. 拿着 `sdk.getChatWidget()` 之后 `sdk.chatWidget()`,或直接从独立的 `Fusioni.mount(container, config)`。 。 。 .

| 属性/方法 | 说明 |
| --- | --- |
| `unmount()` | 删除部件并清理反应根. |
| `setLanguage(language)` | 设置用户界面语言到 `'en'` 或者说 `'el'`。无效的值会被忽略. |
| `setTheme(theme)` | 设置外观到 `'light'`, (中文(简体) ), `'dark'`,或 `'auto'` (遵循系统偏好). 恒相如入微软主题控制. |

**脚本示例 :**

```html
<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const sdk = Fusioni.init({
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    language: 'en'
  }).chatWidget();

  document.getElementById('locale-el').addEventListener('click', () => {
    sdk.getChatWidget().setLanguage('el');
  });
  document.getElementById('theme-dark').addEventListener('click', () => {
    sdk.getChatWidget().setTheme('dark');
  });
</script>
```

**反应( npm) 实例 :** 传回 `ChatWidget` 并调用相同方法(类型 : `FusioniChatWidgetHandle`) (中文(简体) ).

```tsx
import { useRef } from 'react';
import { ChatWidget, type FusioniChatWidgetHandle, type FusioniSDKConfig } from '@fusioni/client-sdk';

function App() {
  const chatRef = useRef<FusioniChatWidgetHandle>(null);
  const config: FusioniSDKConfig = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
  };

  return (
    <>
      <button type="button" onClick={() => chatRef.current?.setLanguage('el')}>
        Greek
      </button>
      <button type="button" onClick={() => chatRef.current?.setTheme('dark')}>
        Dark mode
      </button>
      <ChatWidget ref={chatRef} config={config} />
    </>
  );
}
```

### 事件处理器的高级使用

```tsx
import React from 'react';
import type { Conversation, FusioniMemoryMessage, FusioniSDKConfig } from '@fusioni/client-sdk';
import { ChatWidget } from '@fusioni/client-sdk';

function App() {
  const config: FusioniSDKConfig = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    theme: 'auto',
    position: 'bottom-right',
    primaryColor: '#6366f1',
    showConversationList: true,
    enableAudioRecording: true,
    enableFileUpload: true,
    maxFileSize: 10,
    allowedFileTypes: ['image/*', 'application/pdf']
  };

  const handleMessageSent = (message: FusioniMemoryMessage) => {
    console.log('Message sent:', message);
    // Track analytics, update UI, etc.
  };

  const handleMessageReceived = (message: FusioniMemoryMessage) => {
    console.log('Message received:', message);
    // Handle AI responses
  };

  const handleConversationCreated = (conversation: Conversation) => {
    console.log('New conversation:', conversation);
    // Update conversation list, analytics, etc.
  };

  const handleError = (error) => {
    console.error('Chat error:', error);
    // Handle errors, show notifications, etc.
  };

  return (
    <div className="App">
      <h1>My Website</h1>
      <ChatWidget
        config={config}
        onMessageSent={handleMessageSent}
        onMessageReceived={handleMessageReceived}
        onConversationCreated={handleConversationCreated}
        onError={handleError}
      />
    </div>
  );
}

export default App;
```

## 小型应用程序渲染

`MiniAppRenderer` 是Fusion Web的Angular微型应用程序渲染器的等效反应. 它导入了快照的网络组件捆绑,并挂载其条目ES模块所注册的自定义元素.

```tsx
import {MiniAppRenderer} from '@fusioni/client-sdk';
import '@fusioni/client-sdk/dist/index.css';

function Dashboard() {
  return (
    <MiniAppRenderer
      apiBaseUrl="https://your-fusioni-api.com/api"
      accessToken="your-access-token"
      agencyId="your-agency-id"
      position="dashboard"
      columns={2}
      options={{title: 'Dashboard', rows: 25}}
      onReady={element => console.log('Mini App mounted', element)}
      onFailed={error => console.error(error)}
    />
  );
}
```

使用 `miniApp={snapshot}` 一个应用或 `miniApps={snapshots}` 用于提供收藏。 每张快照都需要一张 `bundle` 与 `element`, (中文(简体) ), `entry`,并且文件元数据 :

```ts
const snapshot = {
  id: 'your-mini-app-id',
  name: 'Reports',
  bundle: {
    element: 'fusion-reports',
    entry: 'frontend/index.js',
    files: [{path: 'frontend/index.js', sha256: 'file-content-hash', size: 1024}],
  },
};
```

文件在Mini App运行时直播. 输入必须调用 `customElements.define('fusion-reports', …)` ;导出一个类或等待 `DOMContentLoaded` 不够充分。 浏览器装入相对导入和 `new URL(path, import.meta.url)` 从已签名的运行时间 URL 中获取资产.

要通过标签加载已安装的应用程序, 请使用 `agencyId` 财务报告和审定财务报表 `tags={['billing', 'reports']}`选择优先 **位置 标签 小型Apps 小型Apps**位置和标签检查需要一个机构;安装捆绑还需要一个机构,要么是道具,要么是明确的运行时间。 单一结果可转化为外部结果 `element`; 多个结果每个得到自己的容器。 收藏使用移动和 `columns` 宽度为768px及以上.

| Prop | 默认 | 目的 |
| --- | --- | --- |
| `miniApp` | —— 说 | 包含自定义元素捆绑的快照 |
| `miniApps` | —— 说 | 要一起制作的快照 |
| `agencyId`, (中文(简体) ), `position`, (中文(简体) ), `tags` | —— 说 | 从 API 中选择应用程序 |
| `element` | 自有容器 | 将自定义元素挂入的外部容器 |
| `columns` | `1` | 桌面列的正整数 |
| `options`, (中文(简体) ), `context` | `{}` | 自定义组件配置和主机服务, 在连接前指定 |
| `reloadable`, (中文(简体) ), `showStatus` | `true` | 显示重新装入控制和空态消息 |
| `currentLanguage` | `'en'` | 控制/状态语言(`'en'` 或者说 `'el'`(中文(简体) ) |
| `apiBaseUrl`, (中文(简体) ), `accessToken` | 初始化的 SDK 客户端 | 查询和后端调用的独立连接; 基址包括 `/api` |
| `apiClient` | —— 说 | 明确 `ApiClient`中,优先于 URL/token |
| `onReady`, (中文(简体) ), `onFailed` | —— 说 | 接收挂载自定义元素或文件/模块/注册失败 |
| `className`, (中文(简体) ), `style` | —— 说 | 外包装样式 |

变化 `options`, (中文(简体) ), `context`,回调,或 `columns` 不重新启动元素。 使用一个 `ref` 类型为 `MiniAppRendererHandle` 打电话 `ref.current.run()` 重新装入当前选项/文本。 内容 `api` getter 显示挂载 `MiniAppElement` 为单一应用程序,或 `null` 为了收藏. `loadMiniApps()` 重试当前服务器查询 。 替换、再装入和卸载删除元素,取出其原生元素 `disconnectedCallback()` 当连接时.

对于一个快照, `element.context.backend.request(path, request?)` 自动调用 `/api/mini-app-runtime/{miniAppId}{path}` 与代理和SDK认证。 请求选项包括: `method`, (中文(简体) ), `query`, (中文(简体) ), `headers`, (中文(简体) ), `body`,以及 `responseType` (单位:千美元)`'json'` 或者说 `'text'`) (中文(简体) ). 提供 `context.backend` 优先; `MiniAppBackendService.createBuilderContext()` 为文件和后端调用选择构建器运行时间. `element.context.lifecycle.signal` 和后端请求信号在重新装入或卸载时中止。 使用该信号取消同步工作 `disconnectedCallback()` 删除听众/计时器.

冰冻的 `element.context.files` 提供 `base` (已签名的文件库 URL)和 `url(path)` 用于解决捆绑资产。 档案赠款的使用 `/api/mini-app-files/{installed|builder}/{miniAppId}` 并且通过连接、运行时间、应用、代理和捆绑版本被缓存,所以同一模块在重载时保留相同的URL。 失败的赠款可以再审。 浏览器无法重新定义自定义元素:使用已注册名的不同捆绑版本需要重新装入页面. 用无关的主机代码已经注册的名称被拒绝.

脚本捆绑在Shadow DOM中提供了具有SDK风格的同一种渲染器:

```html
<div id="mini-apps"></div>
<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const apps = Fusioni.mountMiniApp('#mini-apps', {
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    accessToken: 'your-access-token',
    agencyId: 'your-agency-id',
    position: 'dashboard',
    columns: 2,
    reloadable: false
  });
  // apps.run(); apps.loadMiniApps(); apps.unmount();
</script>
```

以主机页面权限执行并不存在沙盒 。 Render只信任Mini App快照. 内容安全 政策必须允许运行时间模块和资产来源; `unsafe-eval` 此渲染器不再需要.

## 动作按钮

`ActionButtons` 是Fusion Web的动作按钮组件的对应反应。 它启用了组标记的动作,并用其对话配置字段执行它们.

```tsx
import { useRef } from 'react';
import { ActionButtons, type ActionButtonsHandle } from '@fusioni/client-sdk';
import '@fusioni/client-sdk/dist/index.css';

function Tools() {
  const actions = useRef<ActionButtonsHandle>(null);
  return (
    <ActionButtons
      ref={actions}
      agencyId="your-agency-id"
      tags={['tools']}
      apiBaseUrl="https://your-fusioni-api.com/api"
      accessToken="your-access-token"
      currentLanguage="en"
      showButtonsPanel
      actionInputFieldValues={{ '*': { customer_id: '123' }, report: { format: 'pdf' } }}
      actionEnabledStates={{ report: true }}
      onResponse={results => console.log(results)}
      onError={error => console.error(error)}
    />
  );
}
```

你可以提供 `apiClient` 而不是 URL/token 道具,或者使用 SDK 的初始客户端. 标记被修剪并被破解;要装入动作,既需要代理标记,也需要非空标记. 共享价值 `'*'` 被行动所压倒 `key`。只发送已宣布的字段。 应用值隐藏其控制并必须通过验证. `actionEnabledStates` 仅在动作 **键** 地图到 `false`。 。 。 .

配置文件格式为支持文本,数字,布尔,日期,JSON,列表,文件,即时和嵌入式聊天字段,包括默认,本地化标签和验证规则. 即使动作选择了配置文件的子集,也包含必要的字段. 文件字段接受最多8个文件,并通过执行请求发送数据 URL `image` 频道. 快速字段再利用 `ChatInput`,在验证失败后保留草稿,并提交 Enter 或 Send。 嵌入式聊天字段创建了配置关联的对话并再用SDK的聊天输入,消息,图像相册,出行执行和流出进度.

维持的行动有独立的对话历史和按页面路由和代理所显示的会话存储ID. `conversationStorageKey` 自定义存储前缀;代理总是附加. 历史修复没有发出任何响应事件,无法保存的存储会回到内存. `results_sort` 控制器转动命令 。 结果包括已消毒的HTML,带有画廊预览的图像,文档链接,执行时间和输出变量. `onResponse` 行动累积结果 `show_results`,而当前执行的结果除外.

| Prop | 默认 | 目的 |
| --- | --- | --- |
| `showRunButton` | `true` | 显示表单的提交按钮; 及时发送仍然提交 |
| `showLoadingPanel` | `true` | 显示执行进度 |
| `showActionResult` | `true` | 显示并恢复结果; 隐藏时回调仍然会起火 |
| `showButtonsPanel` | `false` | 在动作卡周围添加一个容器 |
| `fullscreen` | `false` | 打开配置格式全屏 |
| `onFullscreenChange` | —— 说 | 接收全屏切换, 包括 Escape |
| `sidePanel` 编号 : `children` | —— 说 | 在全屏显示窗体旁边的内容 |

裁判曝光 `executeAction(actionOrIdOrKey)`, (中文(简体) ), `submitFields()`, (中文(简体) ), `cancelFields()`, (中文(简体) ), `startNewConversation(actionOrIdOrKey?)`, (中文(简体) ), `loadActions()`,以及用于 `selectedAction`, (中文(简体) ), `results`,以及 `conversationMessages`。如果需要输入,执行动作将打开其形式。 更改代理或标签会取消待决请求并重放视图 。 卸载也会取消请求和定时器.

对于脚本-tag集成,使用与孤立的Shadow DOM风格相同的道具:

```js
const actions = Fusioni.mountActionButtons('#actions', {
  agencyId: 'your-agency-id',
  tags: ['tools'],
  apiBaseUrl: 'https://your-fusioni-api.com/api',
  accessToken: 'your-access-token',
  onResponse: results => console.log(results),
});
// actions.executeAction('report'); // call after actions have loaded
// actions.startNewConversation();
// actions.unmount();
```

## 配置选项

### FusioniSDK 配置

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiBaseUrl` | `string` | **需求** | 您 Fusioni API 的基础 URL |
| `agencyId` | `string` | **需求** | 您的代理身份证明 |
| `accessToken` | `string` | `undefined` | 认证的可选访问符 |
| `ownerId` | `string` | SDK客户端ID或JWT `oid` | 目前的发送者融合所有者身份 。 通常从 SDK 客户端配置或 JWT 访问符自动解决 |
| `theme` | `'light' | 'dark' | 'auto'` | `'light'` | UI 主题偏好( 稍后可通过 [`setTheme`](https://npmcn.com/package/%40fusioni/client-sdk/#readme-changing-language-and-theme-after-init)(中文(简体) ) |
| `language` | `'en' | 'el'` | `'en'` | UI 复制语言( 稍后可通过 [`setLanguage`](https://npmcn.com/package/%40fusioni/client-sdk/#readme-changing-language-and-theme-after-init)(中文(简体) ) |
| `showThemeToggle` | `boolean` | `true` | 在聊天标题中显示/ 隐藏主题切换按钮 |
| `showFullscreenToggle` | `boolean` | `true` | 在聊天头显示/隐藏全屏切换按钮 |
| `showLanguageSwitcher` | `boolean` | `true` | 在聊天头显示/ 隐藏语言切换器 |
| `showThoughts` | `boolean` | `false` | 显示每个信件 `thoughts` 在相撞面板中的字段 |
| `showContextUsage` | `boolean` | `true` | 当回答包含使用数据时,在聊天作曲器上方显示上下文窗口表. |
| `showContextUsageDetails` | `boolean` | `false` | 让用户打开上下文窗口表来查看每个代理符数,窗口大小,以及模型名. 要求数 `showContextUsage`。 。 。 . |
| `position` | `'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'` | `'bottom-right'` | 浮动按钮的位置 |
| `primaryColor` | `string` | `'#6366f1'` | 界面的主要颜色 |
| `showConversationList` | `boolean` | `true` | 是否显示对白侧边栏 |
| `enableAudioRecording` | `boolean` | `true` | 启用语音信件记录 |
| `enableFileUpload` | `boolean` | `true` | 启用文件上传功能 |
| `maxFileSize` | `number` | `10` | MB 最大文件大小 |
| `allowedFileTypes` | `string[]` | `['image/*']` | 允许上传的 MIME 类型 |
| `buttonVariant` | `'minimal' | 'glass' | 'solid'` | `'glass'` | 浮动启动器按钮样式 |

## 事件处理器

### ChatWidget 选项

| 处理器 | 类型 | 说明 |
| --- | --- | --- |
| `onMessageSent` | `(message: FusioniMemoryMessage) => void` | 当用户发送消息时调用 |
| `onMessageReceived` | `(message: FusioniMemoryMessage) => void` | 收到大赦国际的答复后打电话 |
| `onConversationCreated` | `(conversation: Conversation) => void` | 创建新对话时调用 |
| `onConversationDeleted` | `(conversationId: string) => void` | 对话被删除时调用 |
| `onError` | `(error: Error) => void` | 发生错误时调用 |

## API 整合

SDK自动处理与您的 Fusioni API 端点的通信 :

-   **对话**数字 : `/api/conversation`
-   **信件**数字 : `/api/mem`
-   **巡回处决**数字 : `/api/journey/exec_async` (承认)
-   **文件上传**数字 : `/api/upload`
-   **服务器事件**数字 : `/api/sse/connect` (单位:千美元)`chat_stream` 进展和 `message_stream` 答复)

## 样式

SDK包括可使用 CSS 变量定制的综合 CSS 样式 :

```css
:root {
  --fusioni-primary: #6366f1;
  --fusioni-primary-light: #818cf8;
  --fusioni-primary-dark: #4f46e5;
  --fusioni-bg-primary: #ffffff;
  --fusioni-text-primary: #1e293b;
  /* ... more variables */
}
```

### 黑暗主题

SDK 当 `theme: 'dark'` 或者说 `theme: 'auto'` (带有系统偏好)设置.

## 浏览器支持

-   颜色60+
-   Firefox 55+ (英语)
-   第12条+
-   边缘79+

### 录音要求

-   HTTPS 或本地主机( 安全上下文)
-   麦克风权限
-   有 Media Recorder API 支持的现代浏览器

## 发展

### 建造SDK

```bash
npm run build
```

### 发展模式

```bash
npm run dev
```

### 类型检查

```bash
npm run type-check
```

### 测试

```bash
npm test -- --runInBand
```

Mini App测试覆盖渲染,同步的生命周期清理,目录查询,后端传输,和脚本-tag上架. 搜索测试覆盖了Fusion API运输,自动完成交互,结果导航,pagination,外部元素绑定,取消,以及脚本-tag上架. SDK初始化测试涵盖流畅的链路,共享的默认,每个地貌的覆盖,明确的聊天挂起,独立实例,以及清理.

### 线性

```bash
npm run lint
```

## 实例

### 自定义样式

```tsx
import React from 'react';
import { ChatWidget } from '@fusioni/client-sdk';
import './custom-chat-styles.css';

function App() {
  const config = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  };

  return (
    <div>
      <ChatWidget config={config} />
    </div>
  );
}
```

```css
/* custom-chat-styles.css */
.fusioni-chat-widget {
  --fusioni-primary: #your-brand-color;
  --fusioni-bg-primary: #your-background-color;
}

.fusioni-floating-button {
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
}
```

### 有条件渲染

```tsx
import React, { useState } from 'react';
import { ChatWidget } from '@fusioni/client-sdk';

function App() {
  const [showChat, setShowChat] = useState(false);

  const config = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  };
  
  return (
    <div>
      <button onClick={() => setShowChat(!showChat)}>
        Toggle Chat
      </button>
      {showChat && <ChatWidget config={config} />}
    </div>
  );
}
```

## 解决问题

### 共同问题

1.  **录音不工作**
    
    -   确保您在 HTTPS 或本地主机
    -   检查麦克风权限
    -   验证 Media Recorder API 的浏览器支持
2.  **文件上传失败**
    
    -   检查文件大小限制
    -   校验允许的文件类型
    -   确保适当的 API 端点配置
3.  **未出现的消息**
    
    -   验证 API 基础 URL 和代理 ID
    -   检查网络连接
    -   浏览器检查出错

### 调试模式

SDK使用过 `accessToken` 向您的 Fusioni API 认证请求。 (Logging,如果存在的话,由您的应用/构建环境控制,而不是由符号值控制. )

```tsx
const config = {
  // ... other config
  accessToken: 'your-access-token',
};
```

## 许可证

麻省理工学院许可证 - 详情见LICENSE文件.

## 支助

支助和问题:

-   在 GitHub 上创建一期
-   联系Fusioni团队

## 正在链接 npm

. . . . .

. . . . . . . . .

## 常见问题

### @fusioni/client-sdk 是什么？

Fusioni SDK 用于网络应用程序

### 如何安装 @fusioni/client-sdk？

在项目目录运行 npm install @fusioni/client-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fusioni/client-sdk 支持 TypeScript 吗？

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

### @fusioni/client-sdk 支持 ESM 还是 CommonJS？

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

### @fusioni/client-sdk 可以商用吗？

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

### @fusioni/client-sdk 的下载量有多少？

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

### @fusioni/client-sdk 还在维护吗？

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