@ahxlo/lite-ai-websdk

@ahxlo/lite-ai-websdk

Ahxlo 智能体 Web 嵌入聊天 SDK。支持 npm（ESM） 与 CDN（IIFE） 接入。

对接后端： ahxlo-cloud-core-v2 开放嵌入接口（/indexApi/open/embed/**）。应用需开启嵌入（embedEnabled=1）。

要求

开放接口（v2）

身份头：X-Embed-Guest-Key（必填）、可选 X-Embed-User-Id / X-Embed-User-Name。
SSE 载荷对齐 AigcSsePayload：meta / text / think / tool / citation / done / error（含 chatId）。

生成参数（temperature、sandbox、知识库等）由服务端按应用 modelConfig 注入，无需在 SDK 请求中传递。SDK 仅传访客身份、appId、prompt、conversationId、enableThink 与可选 media。

安装

npm

npm install @ahxlo/lite-ai-websdk

CDN

从 npm 发布产物加载（推荐固定版本号）：

• 使用 @1：始终解析为最新 1.x（如 1.0.2），一般无需每次 patch 改 URL。
• 使用 @1.0.2：锁定该版本，升级 SDK 时需手动改地址。
• 亦可自托管 dist/aigc-widget.js。

快速接入

CDN（IIFE）

<script src="https://cdn.jsdelivr.net/npm/@ahxlo/lite-ai-websdk@1/dist/aigc-widget.js"></script>
<script>
  window.AigcEmbed.init({
    appId: 'YOUR_APP_ID',
    apiBase: 'https://your-api.example.com/indexApi',
    user: { id: 'user-1', name: '访客' }
  });
</script>

• 加载完成后调用 window.AigcEmbed.init，必须传入 appId、apiBase。
• 样式已内联，无需额外 CSS。
• 脚本使用 async / defer 时，在 onload 或 DOMContentLoaded 后再调用 init。

npm（ESM）

import { createAigcEmbed } from '@ahxlo/lite-ai-websdk';

const embed = createAigcEmbed({
  appId: 'YOUR_APP_ID',
  apiBase: 'https://your-api.example.com/indexApi'
});

embed.init({ user: { id: 'user-1', name: '访客' } });
embed.open();
embed.close();
embed.destroy();

• 不挂载 window.AigcEmbed。
• 同一 appId 多次调用 createAigcEmbed 返回同一实例。

API

window.AigcEmbed（CDN）

createAigcEmbed（npm）

function createAigcEmbed(options: {
  appId: string | number;
  apiBase: string;
  cssUrl?: string;
  webSdkConfig?: EmbedWebSdkConfigInput;
}): AigcEmbedInstance;

EmbedInitOptions

类型见 dist/index.d.ts、dist/types.d.ts。

应用配置（体验对齐）

SDK 从公开 config 读取并生效：

包内容

发布

发版到 npm 的步骤、检查项与常见问题见 PUBLISH.md。

许可证

Apache License 2.0