WordPress ai在线客服插件

最后更新：2025-12-13

插件简介

插件名称：Aurora Chat （WordPress ai在线客服插件）

主要功能：在前端为网站访客提供一个 AI 聊天窗口（AI 客服），支持悬浮气泡或内容区嵌入，与 OpenAI 兼容接口通信，可配置模型、系统提示词、对话记忆、敏感词过滤和使用配额等。

典型用途：站点智能客服、知识库问答、通用 AI 助手。

核心特点

  • 前端浮窗 + 短代码：支持右下角/左下角悬浮气泡，也支持通过短代码嵌入到文章或页面中。
  • 多模型支持：可配置多个模型，前端可（可选）让用户切换。
  • 记忆对话：支持将多轮对话持久化，形成连续会话体验。
  • 敏感词过滤：可自动用“*”替换回答中的敏感/次敏感词。
  • 配额统计：内置每日/月度 tokens 用量统计和上限控制。
  • 知识库模式：可加载站内 FAQ/文档生成知识库提示，提高回答贴合度。
  • 日志与数据表：会话、消息和用量都有数据库表记录，便于后期分析与排错。

安装与启用

安装插件

方式一：后台上传 ZIP 安装

  1. 进入 WordPress 后台 “插件 > 安装插件”。
  2. 点击顶部 “上传插件”，选择 Aurora Chat 安装包 ZIP 文件。
  3. 上传完成后，点击 “现在安装” 然后点击 “启用” （WordPress ai在线客服插件）。

方式二：FTP / 文件管理器上传

  1. 将插件目录 aurora-chat 上传到服务器 wp-content/plugins/ 目录。
  2. 进入后台 “插件 > 已安装插件”，启用 Aurora Chat。

激活后会做什么

  • 注册后台菜单 “Aurora Chat”。
  • 准备 REST 接口、日志与会话存储表（当开始使用聊天功能时自动创建）。
  • 加载前端所需的 JS/CSS 文件（按页面内容与设置条件加载）。

后台入口与整体结构

后台菜单入口

  • 启用后，在后台左侧会出现 “Aurora Chat” 顶级菜单。
  • 点击后进入设置页面，分为多个区域：API 配置、模型设置、显示设置、知识库、使用统计、授权管理等。

主要组成模块（仅了解）

  • class-admin.php：后台菜单、表单渲染与管理 JS/CSS。
  • class-frontend.php：短代码、自动注入、前端脚本和样式加载。
  • class-rest.php：REST API 端点（对话、测试、统计等）。
  • class-api-client.php：对 OpenAI 兼容接口的 HTTP 调用封装。
  • class-session-store.php：会话与消息表读写。
  • words/zonghe.php：敏感词词库（启用过滤后使用）。
  • templates/embed-chat.php：前端聊天 UI 模板。

API 配置（连接大模型）

配置入口

  • 后台左侧 Aurora Chat > 打开设置页，在 “API 配置” 区域进行设置。

核心字段说明

  • API 状态：显示当前是否已正确配置有效的 API Key；保存成功后一般会显示“已连接”。
  • API 地址（API Base）：
    • 内部默认会对地址做合法性校验，必须以 http:// 或 https:// 开头。
    • 未配置或填写错误时，会回退到内置默认网关（如 https://sk.slapi.cn/）。
  • API Key：你的 OpenAI 兼容服务的密钥。
  • 聊天接口路径：通常为 /v1/chat/completions，如无特殊需求可保持默认。
  • 模型列表接口路径：一般为 /v1/models，用于后台获取模型列表。
  • 超时时间（毫秒）：默认约 30 秒，长对话可适当调大。
  • 重试次数：当上游短暂网络错误时自动重试的次数。
  • 认证方式：默认使用 Bearer Token，兼容部分网关的自定义请求头 api-key / X-API-Key。
  • API 测试：输入简单测试问题（如“你好，请回复测试成功”），点击“发送测试”，如果配置无误会返回成功提示。

安全建议

  • 仅管理员角色应有权限访问该设置页面。
  • 不要在前端页面、文章或截图中暴露 API Key。
  • 如更换上游服务时，记得同步修改 API 基址和模型名称。

模型与对话行为设置

模型列表与默认模型

  • 可用模型列表：在“模型设置”中配置多个模型 ID（如 gpt-4o-mini、其它兼容模型）。
  • 默认模型：指定打开聊天窗口时默认使用的模型。
  • 前端模型选择器：可在“显示设置/高级”中开启“显示模型选择器”，允许访客在已配置的模型间切换。

系统提示词（System Prompt）

  • 默认内置一段较长的系统提示词（在 Aurora_Chat_REST::DEFAULT_SYSTEM_PROMPT 中），用于控制 AI 的语气、回答风格以及敏感话题处理规则。
  • 你可以在后台“API 配置 / 模型配置”区域里修改 系统提示词 字段，重写为适合你业务的角色说明，例如：
    • “你是一个专业的电商客服……”
    • “你是本网站的技术支持顾问……”

对话记忆与上下文长度

  • 启用记忆（enable_memory）：开启后插件会把多轮对话写入数据库，在后续提问时带上历史对话。
  • 记忆长度（memory_length）：控制每次调用时最多带入多少轮历史对话，数值越大越“健谈”，但 tokens 消耗越多。
  • 会话持久化（persist_sessions）：控制是否持久保存对话到数据库，会配合 Aurora_Chat_Session_Store。

温度与最大长度

  • temperature：越高回答越发散、创意，越低则更稳、更接近训练语料。
  • max_tokens：单次回答最多 tokens 数，上游超过会被截断。

前端显示与嵌入方式

悬浮模式（默认）

  • 前端 UI 模板位于 templates/embed-chat.php：右下角悬浮按钮 + 展开后的对话框。
  • 默认浮窗结构：
    • 悬浮按钮（id: ai-chatbot-toggle）。
    • 对话容器（id: ai-chatbot-container）。
    • 消息区、输入框、发送按钮、清空按钮、关闭按钮等。

悬浮位置与大小

  • 在“显示设置”中可配置：
    • 悬浮图标大小（float_icon_size）：按钮直径，单位 px。
    • 水平偏移（float_offset_x）：相对于默认右下角位置的左右偏移。
    • 垂直偏移（float_offset_y）：相对于默认底部的上移/下移。
  • 用于避免与页面已有“返回顶部”按钮、客服图标等重叠。

短代码嵌入

  • 插件注册了两个短代码：

    • AI 客服

      你好，我是本站的 AI 客服助手。可以帮你快速查询产品说明、订单状态、售后规则等信息，也可以回答通用问题。

      Aurora Chat v0.2.0
      回复内容由 AI 生成，仅供参考。

    • AI 客服

      你好，我是本站的 AI 客服助手。可以帮你快速查询产品说明、订单状态、售后规则等信息，也可以回答通用问题。

      Aurora Chat v0.2.0
      回复内容由 AI 生成，仅供参考。
  • 在文章或页面内容中插入上述短代码，即可在内容区域嵌入聊天窗口。
  • 如果使用短代码，插件会自动检测正文中是否存在短代码，当存在时不会再在页脚自动注入，避免重复出现。

自动注入规则

  • 在“显示范围/Display Pages”中勾选：
    • home：首页/博客主页。
    • posts：文章详情页。
    • pages：独立页面。
    • archives：列表页（分类/标签归档、搜索结果等）。
  • 当满足勾选的条件且正文中不存在短代码，插件会在页脚自动 include embed-chat.php，渲染悬浮聊天框。

嵌入模式高度（embed_min_height）

  • 当通过短代码嵌入内容区域时，可配置“嵌入模式最小高度”（单位 px）。
  • 插件会自动限制高度在合理区间（如 300～2000px），兼顾桌面与移动端显示。

前端显示选项

  • 显示模型选择器（show_model_selector）：在对话框头部显示模型下拉选择。
  • 显示清除对话按钮（show_clear_button）：展示一个清空历史对话按钮。
  • 主题风格（theme_style）：例如深色浮窗、浅色抽屉等不同皮肤（具体以设置项为准）。
  • 底部品牌提示（show_footer_brand）：是否显示 “Aurora Chat vX.Y.Z” 小字与链接。
  • 底部免责声明（show_footer_tips）：是否显示“回复内容由 AI 生成，仅供参考。”。

知识库（可选）

知识库的作用

  • 可将站内 FAQ、帮助文档或商品说明整合成一份“知识库文本”，在调用 AI 时作为额外的上下文或指令。
  • 适合做“站内客服/知识问答”，而不仅仅是通用聊天。

配置方式（概览）

  • 在“知识库/Knowledge Base”区域，填写或上传你整理好的知识内容。
  • 部分实现会在系统提示词或用户消息前自动附加知识库内容，并提醒模型只按知识库回答。

敏感词过滤

启用方式

  • 在“API/模型或高级设置”里有 敏感词过滤（enable_word_filter） 选项。
  • 勾选后，Aurora Chat 会在返回前对回答内容做二次处理。

词库来源

  • 词库文件位于 words/zonghe.php，包含各类敏感/次敏感词。
  • 当回答命中这些词汇时，会将命中部分用“*”替换，而不是完全拒答。

使用统计与配额控制

用量统计表

  • 插件会在数据库中创建 wp_aurora_chat_usage_daily 表，按日期和模型统计：
  • 请求次数、prompt tokens、completion tokens、total tokens 等。

每日/每月 tokens 上限

  • 每日上限（daily_quota_tokens）：设置为 >0 时，优先使用该限制。
  • 月度上限（monthly_quota_tokens）：如果未设置每日上限，则可设置一个整体月度 tokens 上限。
  • 配额重置日（quota_reset_day）：控制月度统计从每月哪一天开始，默认 1 号。

触发配额上限时的行为

  • 当达到上限后，再次发起对话请求会被后端直接拦截。
  • REST 返回 quota_exceeded 错误，前端可展示“已达到使用上限”的提示。

授权管理（如有）

授权状态

  • Aurora Chat 内部通常通过独立的授权类（如 AC_License）检查是否处于授权状态。
  • 未授权或授权过期时，聊天 REST 接口会返回 license_required 错误，并附带“当前插件未授权，功能不可用”的提示。

建议

  • 根据插件提供的授权说明，在“授权管理”区域输入正确的授权信息。
  • 授权通常与当前站点域名绑定，请在正式域名环境下完成授权。

常见问题与排错

1. 前端没有出现聊天按钮/浮窗

  • 检查是否已在“显示范围”中勾选当前页面类型（home/posts/pages/archives）。
  • 已经嵌入

    AI 客服

    你好，我是本站的 AI 客服助手。可以帮你快速查询产品说明、订单状态、售后规则等信息，也可以回答通用问题。

    Aurora Chat v0.2.0
    回复内容由 AI 生成，仅供参考。
     短代码时，不会再自动注入浮窗，属正常行为。
  • 确认页面源代码中是否有 aurora-chat-frontend 等 JS/CSS 被加载：
  • 若完全未加载，可能是：
    • 页面类型不在勾选范围内。
    • 主题/构建器未执行 wp_footer() 钩子。
    • 缓存插件或静态化工具异常清理了相关输出。

2. 点击按钮无反应 / 无法展开窗口

  • 查看浏览器控制台是否有 JS 报错（可能是其它脚本冲突）。
  • 确认前端 JS 文件 assets/js/chat-bootstrap.js 与 assets/js/frontend.js 已正确加载。
  • 如使用页面构建器，请确保未重复包裹或过滤掉嵌入模板中的元素 ID。

3. 聊天请求报错 / 一直转圈

  • 检查后台 API 配置：
    • API Base 地址是否正确（协议、域名、路径）。
    • API Key 是否有效、是否有余额。
    • 兼容网关是否支持 /v1/chat/completions 风格的调用。
  • 在“API 测试”中尝试发送简单问题，查看是否有错误提示。
  • 在服务器 error_log 或 logs 目录中查看是否有 [AuroraChat] 相关错误。
  • 注意防火墙/安全插件是否拦截了对外 HTTP 请求。

4. 返回内容提示“未授权 / license_required”

  • 说明当前 Aurora Chat 的授权校验未通过。
  • 在“授权管理”区域核对授权信息是否填写正确，是否在有效期内。
  • 域名变更或迁移服务器后，可能需要重新授权。

5. tokens 用量过快/超出配额

  • 适当减小“记忆长度”（memory_length），避免每次带入过多历史对话。
  • 控制“最大 tokens”（max_tokens），避免单次回答过长。
  • 使用较经济的模型作为默认模型，把昂贵模型留给管理员或特定入口使用。
  • 根据预算设置合理的每日/每月 tokens 上限。

6. 敏感话题回答不符合预期

  • 查看是否开启了“敏感词过滤”：过滤器只会对输出文字做“脱敏”，并不会改变上游大模型策略。
  • 如希望 AI 在某些话题上统一回复“建议换个话题”，可在系统提示词中添加显式规则。

7. 数据库表或日志过大

  • 会话与消息表（aurora_chat_sessions、aurora_chat_messages）会随使用时间增长。
  • 建议定期：
    • 备份数据库。
    • 使用 SQL 工具清理很久之前的旧会话（注意备份后再操作）。
    • 对 logs 目录中的日志文件做归档或轮转。

使用建议

快速配置建议

  • 先在测试环境完成：API 配置 → 测试调用 → 简单对话验证。
  • 配置 1～2 个模型：一个通用模型，一个偏便宜/高性价比。
  • 设置合理的系统提示词，明确“你是谁、能做什么、不能做什么”。
  • 启用基础的敏感词过滤和简要免责声明。

线上运营建议

  • 根据页面类型选择展示范围，避免所有页面都弹出，影响体验。
  • 结合站点业务，将常见问题整理进知识库或欢迎区“快捷问题”。
  • 定期查看用量统计（daily/monthly tokens），控制成本。
  • 如有运营或法务要求，可自定义“回复内容由 AI 生成，仅供参考”文案并保持展示。

安全与隐私

  • API Key 和授权信息仅保存在站点端，不会写入公共前端。
  • 建议在隐私政策中说明会话内容可能被发送至第三方 AI 服务进行处理。
  • 避免在系统提示词或知识库中写入敏感隐私数据。