CatWiki 文档

Appearance

网页挂件机器人 ​

NOTE

“网页挂件”是 CatWiki AI 机器人能力的一种嵌入式展现方案。通过一行代码脚本，您可以将具备知识库能力的 AI 助手无缝集成到任何第三方网站中。

CatWiki 提供了一种极其简便的方式，通过一行脚本即可将智能 AI 助手集成到您的任何网站中。我们采用了“后端驱动”架构，确保您在无需修改代码的情况下即可调整挂件的表现。

推荐场景 ​

  • 官网访客接待：在公司官网站底部展示，解答访客对产品、方案的通用咨询。
  • SaaS 产品助手：嵌入到产品后台，为用户提供实时操作指南和功能解答。
  • 活动页面咨询：在营销活动页提供 AI 顾问，提升转化率。

1. 快速集成 ​

只需将以下代码粘贴到您网站 HTML 的 <body> 标签末尾即可：

html
<script 
  src="http://localhost:8002/widget.js" 
  data-site-id="YOUR_SITE_ID"
></script>

TIP

YOUR_SITE_ID 可以在 CatWiki 管理后台的“站点设置”中找到。

AI 机器人集成

核心设计理念 ​

后端驱动内容 (Backend-Driven) ​

挂件启动后，会自动从后端拉取该站点的所有核心配置，包括：

  • 标题: 挂件顶部的显示名称。
  • 主题色: 挂件的主色调（渐变色基础）。
  • 欢迎语: 机器人自动发送的第一条消息。

这意味着一旦集成完成，您可以在 CatWiki 管理后台随时修改这些设置，所有嵌入了挂件的网站都会在秒级（或缓存更新后）自动同步。

前端控制布局 (Frontend-First Layout) ​

为了避免样式冲突，挂件的物理显示位置完全由宿主页面控制。

  • 默认位置: 默认出现在页面右下角。
  • 居左显示: 如果您希望挂件出现在左下角，可以添加 data-position="left" 属性：
    html
    <script src="..." data-site-id="1" data-position="left"></script>
  • 更高级的控制: 因为挂件是 fixed 定位的 iframe，您也可以通过宿主页面的 CSS 直接覆盖 #chat-widget-iframe 的样式（如调整 bottom 间距）。

零闪烁加载体验 (Zero-Flash) ​

为了提供极致的用户体验，系统内置了加载逻辑：

  1. 隐形加载: 挂件初始状态是完全透明且隐藏的。
  2. 就绪显现: 只有当 React 应用完全加载、后端配置拉取成功且样式应用完成后，挂件才会执行平滑的淡入动画。

3. 技术特性 ​

  • 流式同步频率：实时（SSE/WebSocket 协议）。
    • 说明：网页挂件采用 Server-Sent Events 或 WebSocket 长连接，AI 生成的每一个 Token 都会立即在界面上呈现，实现极致的毫秒级流式响应。
  • 集成方式：单行 JS 脚本嵌入。
  • 配置同步：Backend-Driven（后端配置即时生效）。

调试与测试 ​

在本地开发环境下，您可以使用项目自带的模拟页面进行测试：

  • 访问地址：http://localhost:8002/test-widget.html
  • 该页面提供了一个完整的外部网站模拟环境，方便查看集成效果。

注意事项 ​

WARNING

请确保您的网站域名（Origin）已在 CatWiki 管理后台的白名单中（如果有启用的跨域限制），否则 API 请求可能会被拦截。