# @embeddable\.com/ai-chat 中文文档 规范地址：https://npmcn.com/package/%40embeddable.com/ai-chat/ 版本：0\.3\.4 npm 元数据更新时间：2026-10-21T13:44:47.488Z 中文译文更新时间：2026-11-13T23:55:42.300Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40embeddable.com/ai-chat 原文对照：https://npmcn.com/package/%40embeddable.com/ai-chat/?lang=original 项目主页：https://github.com/embeddable-hq/embeddable-ai-chat#readme 源码仓库：https://github.com/embeddable-hq/embeddable-ai-chat ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.7 MB，136 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2026-07-09T08:20:25.964Z - 最新版本发布：2026-10-21T13:44:47.270Z - 近 30 天下载量：2810（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：16（近 12 个月 16 个） ## 中文简介 一个框架不可知的Web组件,它使一个流动的 AI 聊天部件在 STOMP WebSocket 上连接到一个可嵌入的管弦乐后端. ## 安装 ```sh npm install @embeddable.com/ai-chat ``` 也可以使用：`pnpm add @embeddable.com/ai-chat`、`yarn add @embeddable.com/ai-chat`、`bun add @embeddable.com/ai-chat` ## README # @embeddable.com/ai-chat (英语) 一个框架不可知的Web组件,它使一个流动的 AI 聊天部件在 STOMP WebSocket 上连接到一个可嵌入的管弦乐后端. 与 [斯坦西尔](https://stenciljs.com/) ——在平版HTML,React,Vue,Angular或任何其他框架中工作. * * * ## 快开始 ### 1\. 配置您的 LLM 在ai-chat回复之前,您的工作空间需要配置在管弦乐后端的LLM. 发送一个 `POST` 改为 `/api/v1/llm-config`,用您的可嵌入的 API 密钥认证 (`Authorization: Bearer `) (中文(简体) ). 这是一个一次性的,每个工作空间的设置——配置被加密存储,每一次聊天都重复使用. ```bash curl -X POST https://api.[us|eu].embeddable.com/api/v1/llm-config \ -H "Authorization: Bearer YOUR_EMBEDDABLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "anthropic", "model": "claude-sonnet-4-5", "apiKey": "sk-ant-...", "temperature": 0.7, "maxTokens": 2048, "systemPrompt": "You are a helpful analytics assistant." }' ``` #### LLM 配置字段 | 外地 | 类型 | 需求 | 说明 | | --- | --- | --- | --- | | `provider` | `string` | 对 | LLM 供应商 ID. 必须是后端支持的 : `anthropic`, (中文(简体) ), `openai`, (中文(简体) ), `google`, (中文(简体) ), `openrouter`, (中文(简体) ), `mistralai`, (中文(简体) ), `bedrock`,或 `ollama`未支持的值返回 `400`。 。 。 . | | `model` | `string` | 对 | 所选提供者的型号ID(例如. `claude-sonnet-4-5`, (中文(简体) ), `claude-haiku-4-5`) (中文(简体) ). 必须是提供者支持的模型; 不支持的值返回 `400` 和接受的一组. | | `apiKey` | `string` | 对 | API 密钥用于认证 LLM 调用 。 被加密了,再也没有完全返回.. `GET`编号 :`POST` 反应掩盖它. | | `temperature` | `number` | 没有 | 采样温度. 较高的值产生更多样化的产出. 省略时使用提供者默认值 . | | `maxTokens` | `integer` | 没有 | 每个响应生成的最大符数 。 省略时使用提供者默认值 . | | `systemPrompt` | `string` | 没有 | 系统迅速为每次对话做准备以引导语气和行为. | 获取当前配置( 用 API 密钥遮盖) `GET /api/v1/llm-config`。如果没有设置,则返回 `404`。 。 。 . ### 2\. 薄荷证券 每个用户都需要一个安全标志,用您嵌入的 API 密钥将服务器侧刻出并传递到 `embeddable-tokens` 道具 (英语). 见 [安全标志](https://npmcn.com/package/%40embeddable.com/ai-chat/#readme-security-tokens) 用于请求及其选项(包括使画布只读). ### 3\. 装入交流 添加此脚本以从 unpkg 装入组件最新版本( 不需要构建步骤) : ```html ``` ### 4\. 在您的页面上添加 ai-chat 在模式(浮动面板)或内线(装入容器)之间选择: 1. **模式** - 触发时在浮动面板中打开聊天 ```html ``` 2. **内入模式** - 聊天充满了它的容器 ```html
``` 见 [演示.html](https://npmcn.com/package/%40embeddable.com/ai-chat/demo.html) 对于一个完整的例子. * * * ## 安全标志 空谈提出的每一项请求 都用安全标志认证 每个用户使用薄荷一 `POST /api/v1/security-token` (用可嵌入的 API 密钥认证),然后传递给 `embeddable-tokens` 道具作为JSON-编码阵列——第一个道具被用作"熊克"证书. ```bash curl -X POST https://api.[us|eu].embeddable.com/api/v1/security-token \ -H "Authorization: Bearer YOUR_EMBEDDABLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "embeddableId": "your-embeddable-id", "user": "user-123", "securityContext": {}, "expiryInSeconds": 3600 }' ``` ### 与页面上的仪表板匹配符号 如果页面还制作出一个或多个可嵌入式仪表板(``),建议将同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同 `embeddable-tokens` 打开 ``聊天时只看 `` 其符号与它得到的匹配的元素 – 匹配就是它允许它读取当前屏幕上的仪表板(它所装入的部件,查询和数据)并读取自定义画布的当前布局(例如它有多少列),所以它可以像新生成的图表那样明智地大小和定位添加. 部件仍然使用不同的或独立的符号工作——它仍然可以在画布上添加一个图表——但是没有匹配,它不会在页面上的仪表盘数据或其布局中具有能见度,因此它不能调整大小或定位它有效添加的内容. 这种匹配符符的要求是暂时的——未来的发布会消除AI-chat符符符与仪表盘相匹配的需要,所以这些能力不管怎样都有效. ### 取消自定义画布突变 AI可以改变仪表板自定义画布(例如,添加它刚刚生成的图表). 添加 `"customCanvasReadOnly": true` 答复上述请求。 设定时,管弦乐团拒绝为该指使书写画布,而AI-chat的工具被标记为只读——助手仍然可以回答问题并预览图表,但不能添加或以其他方式修改画布. 旗帜默认为 `false` 省略时(允许的更改)。 由于它活在符上,不同的用户可以用相同的嵌入式部件获得不同的访问级别. * * * ## 爱聊天道具 | 属性 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | `orchestrator-url` | `string` | —— 说 | 嵌入式管弦乐后端的 WebSocket URL(`ws://` 或者说 `wss://`(中文(简体) ) | | `embeddable-tokens` | `string` | —— 说 | JSON编码的安全标志阵列. 首个标志被作为"熊克"证书使用. | | `client-context` | `string` | —— 说 | JSON-编码的仪表板客户端上下文(同一对象被传递给嵌入式). 内容 `timezone` 解决日期与仪表板一致。 传入管弦乐团并注入组件. | | `mode` | `"modal" | "inline"` | `"inline"` | `modal` 打开可浮动拖动面板; `inline` 装入容器 | | `placement` | `"bottom-right" | "bottom-left" | "top-right" | "top-left"` | `"top-right"` | 模式面板相对于触发要素的显示 | | `chart-preview-supported` | `"true" | "false"` | `"true"` | 告诉管弦乐手, 此客户端是否能够制作可嵌入图表预览 。 送来的 `Embeddable-Chart-Preview-Supported` 在STOMP CONNECT框架上的标题. | | `labels` | `Partial` | —— 说 | 覆盖部件的 UI 文本( 欢迎信件、 输入占位符、 反馈对话框副本) 。 这是对象属性,不是字符串属性——通过DOM属性在JS中设置(DOM属性)`el.labels = {…}`),而不是作为HTML属性。 见 [标签](https://npmcn.com/package/%40embeddable.com/ai-chat/#readme-labels) 见下文. | ### 标签 所有介绍用户的文本都通过 `labels` 属性( 类型) `ChatLabels`) (中文(简体) ). 提供以下密钥的任何子集; 省略密钥返回默认值 . | 密钥 | 默认 | 说明 | | --- | --- | --- | | `welcomeMessage` | _(内置问候)_ | 信件在第一个用户信件前的空状态中显示 | | `inputPlaceholder` | `"Ask anything..."` | 信件输入中的占位符文本 | | `feedbackTitlePositive` | `"Tell us what you liked"` | 缩略图评分后反馈注释对话框的标题 | | `feedbackTitleNegative` | `"How can we improve?"` | 缩略图下评分后反馈注释对话框的标题 | | `feedbackPlaceholderPositive` | `"Share more"` | 缩略图后反馈注释输入中的占位符文字 | | `feedbackPlaceholderNegative` | `"Share more"` | 缩略图下行后反馈注释输入中的占位符文字 | | `feedbackDismiss` | `"Dismiss"` | 反馈对话框中解开按钮的标签 | | `feedbackSubmit` | `"Submit feedback"` | 反馈对话框中提交按钮的标签 | | `feedbackThanksForFeedback` | `"Thanks for your feedback"` | 提交书面评论后显示的确认信件 | | `feedbackThanksForRating` | `"Thanks for your rating"` | 在仅给出拇指上下评分后显示的确认消息 | | `addToDashboardConfirmationText` | `"Shall I add this to your dashboard?"` | 在生成的图表旁显示提示, 询问是否将其添加到仪表盘中 | | `addToDashboard` | `"Add to dashboard"` | 在仪表板上添加生成的图表的按钮标签 | | `addingToDashboard` | `"Adding to dashboard…"` | 添加到 Dashboard 动作正在进行时在按钮上显示标签 | | `newConversation` | `"New conversation"` | 启动新对话的按钮/ 动作标签 | | `ratePositive` | `"Rate this positive"` | 拇指上调的评分按钮可访问标签 | | `rateNegative` | `"Rate this negative"` | 拇指下评分按钮的可访问标签 | | `addToDashboardMessageWithTitle` | `'Add the chart "{title}" to the dashboard'` | 在有标题的图表上点击“ 添加到仪表板” 时发送用户信息文本(`{title}` 改为 | | `addToDashboardMessage` | `"Add the chart to the dashboard"` | 在没有标题的图表上点击“ 添加到仪表板” 时发送用户信息文本 | | `conversationTooLongError` | `"This conversation has become too long to continue. Please start a new conversation to keep chatting."` | 当谈话记录长得太大而无法继续时显示 | | `unknownError` | `"An unknown error occurred"` | 当服务器错误到达时没有特定错误消息时显示 | ```js const chat = document.querySelector('em-ai-chat'); chat.labels = { welcomeMessage: 'Hi! Ask me anything about your dashboard.', inputPlaceholder: 'Type a question…', }; ``` ### 槽数 | 名称 | 说明 | | --- | --- | | `trigger` | _(仅模式)_ 切换聊天面板打开/ 关闭的元素 | * * * ## 他们 组件的视觉属性被定义为 `--em-ai-chat-*` CSS自定义属性. 默认情况下,这些决心是来自 [难得一见](https://github.com/embeddable-hq/remarkable-ui) 设计系统 `--em-sem-*` (语义)和 `--em-core-*` (原始内容) 符号层. 你可以看到完整的地图 [src/em-ai-chat/em-ai-chat.tokens.css (中文(简体) )](https://npmcn.com/package/%40embeddable.com/ai-chat/src/em-ai-chat/em-ai-chat.tokens.css)。 。 。 . 如果一个 `` 已经在您的应用程序中, 符号中 `--em-sem-*` (语义)和 `--em-core-*` (原始内容)将自动注入 `:root`,样式将自动应用. 若无 `` ,或者如果聊天需要特定的样式,设置 `--em-ai-chat-*` 变量直接打开 `em-ai-chat` 匹配您自己的设计 : ```css em-ai-chat { /* Shell */ --em-ai-chat-shell-background: #ffffff; --em-ai-chat-shell-border-color: #e4e4ea; /* Input composer */ --em-ai-chat-composer-input-border-color: #e4e4ea; --em-ai-chat-composer-input-border-color--focus: #2d52cc; /* Primary icon button (send / cancel) */ --em-ai-chat-icon-button-primary-background: #2d52cc; --em-ai-chat-icon-button-primary-color: #ffffff; /* Panel size (modal mode) */ --em-ai-chat-panel-width: 23.75rem; --em-ai-chat-panel-height: 32.5rem; ...; } ``` 现有变量的完整列表在 [src/em-ai-chat/em-ai-chat.tokens.css (中文(简体) )](https://npmcn.com/package/%40embeddable.com/ai-chat/src/em-ai-chat/em-ai-chat.tokens.css)。 。 。 . * * * ## 框架整合 ### 反应 / Vue / 角 (ESM 导入) ```js import { defineCustomElements } from '@embeddable.com/ai-chat/loader'; defineCustomElements(); ``` 然后使用 `` 和其他 HTML 元素一样 : ```tsx return ( ); ``` **虚拟用户** - 把这个添加到 `vite.config.ts` 防止Vite预装装入器(它打破了Stencil的懒散块分辨率): ```ts export default defineConfig({ optimizeDeps: { exclude: ['@embeddable.com/ai-chat'], }, }); ``` * * * ## 地方发展 ```bash npm install npm start # dev server with hot reload at http://localhost:3333 ``` 编辑 [src/index.html (中文(简体) )](https://npmcn.com/package/%40embeddable.com/ai-chat/src/index.html) 在本地开发时更改道具或令牌。 乐团后端预计在 `ws://localhost:8080/ws` 默认. ```bash npm run build # production build → dist/ ``` * * * ## 建筑 `em-ai-chat` 是根组件。 它拥有STOMP WebSocket连接,持有所有消息状态,并协调下面的儿童组件. ``` em-ai-chat │ Root. Manages the STOMP WebSocket lifecycle, accumulates streaming │ events into a display list, and switches between modal and inline modes. │ ├── em-ai-chat-modal-shell (modal mode only) │ Floating panel with trigger-based open/close, drag-to-reposition, │ and mouse/keyboard resize. Persists panel size and position across toggles. │ ├── em-ai-chat-messages │ Scrolling feed of user messages, assistant responses, tool calls, errors, │ and injected components. Groups tool calls under their parent message │ and auto-scrolls to the latest entry. │ │ ├── em-ai-chat-message-feedback │ │ Thumbs up/down rating attached to each assistant message. │ │ │ └── em-ai-chat-component │ Sandboxed host for Embeddable component bundles injected by the AI. │ Injects theme tokens, scales height via ResizeObserver, and proxies │ data-fetch requests to the orchestrator. │ └── em-ai-chat-input Textarea composer. Enter sends, Shift+Enter adds a newline. Auto-focuses on visibility and toggles the action button between send and cancel while a response is streaming. ``` 服务器事件由处理 `reduceEvent()` 内 [src/utils/messages.utils.ts (中文(简体) )](https://npmcn.com/package/%40embeddable.com/ai-chat/src/utils/messages.utils.ts)它保持 `Map` 用于 O(1) 流出更新,并返回每个变化上的新数组引用,以触发 Stencil 重报. ## 常见问题 ### @embeddable\.com/ai-chat 是什么？ 一个框架不可知的Web组件,它使一个流动的 AI 聊天部件在 STOMP WebSocket 上连接到一个可嵌入的管弦乐后端\. ### 如何安装 @embeddable\.com/ai-chat？ 在项目目录运行 npm install @embeddable\.com/ai-chat，或使用 pnpm add / yarn add / bun add。 ### @embeddable\.com/ai-chat 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @embeddable\.com/ai-chat 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @embeddable\.com/ai-chat 可以商用吗？ @embeddable\.com/ai-chat 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @embeddable\.com/ai-chat 的下载量有多少？ 根据 npm 官方下载统计，@embeddable\.com/ai-chat 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,810 次，日均约 94 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @embeddable\.com/ai-chat 还在维护吗？ 最新版本 0\.3\.4 发布于 2026/10/21（23 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/07/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。