AI 客服与人工坐席完整手册

一、功能、部署与安全

1.1 插件隔离与默认入口

这是独立可选插件。未启用时，宿主不应监听客服端口、不创建客服数据库，也不启动无关后台任务。启用插件后，仍可在设置页单独关闭 Web 服务。

默认本机入口：

端口可以在设置中修改。公网正式使用时，不应让访客直接访问明文 http://公网IP:28681。

1.2 第一次启用和测试

1. 在“设置 → 组件与插件”启用“AI 客服与人工坐席”；
2. 打开插件设置，确认监听地址和端口；
3. 保存首次生成的随机客服密码和管理员密码；
4. 两种密码应分开保存，不要使用相同密码；
5. 需要 AI 接待时，开启写吗 JSON AI API；
6. 默认客服 AI 地址通常为：

http://127.0.0.1:28680/api/v1/chat

7. 启动客服 Web 服务；
8. 分别打开访客、客服和管理员入口；
9. 访客发送普通问题，确认 AI 回复；
10. 点击“人工客服”或输入转人工关键词；
11. 客服从公共队列接入；
12. 测试文字、图片、转接、退回、结束人工和彻底结束会话；
13. 在管理员入口检查消息、审计和统计。

1.3 访客端功能

• AI 自动回答常见问题；
• 请求人工后停止自动 AI 回复；
• 快捷命令，例如公司介绍、联系方式、产品、下载地址和人工客服；
• 文字和图片；
• 可配置表情面板；
• 显示排队、已接入、客服断线和结束状态；
• 刷新或短暂断线后恢复原会话和历史；
• 网站、小程序或 APP 可传入外部 sessionId、昵称和头像；
• 外部会话 ID 可用于关联会员、订单或售后，但不是登录认证凭证。

示例业务信息：

{
  "sessionId": "order-after-sale-10086",
  "nickname": "张先生",
  "avatar": "https://example.com/avatar/10086.png"
}

1.4 人工客服工作台

• 多个客服使用不同客服名称登录；
• 查看公共等待队列；
• 接入前查看访客的 AI 对话、排队留言和外部会话信息；
• 多客服同时抢同一会话时，只允许一个客服成功接入；
• 支持转接给其他客服；
• 支持退回公共区；
• 支持结束人工服务；
• 支持彻底结束会话；
• 每名客服可设置最大同时接待数量；
• 同一客服名称默认只保留一个有效工作台；
• 客服通过心跳维持在线；
• 超过断线保护时间后，会话可退回公共区；
• 支持文字、图片、可选表情和快捷回复；
• 图片读取需要所属会话授权。

1.5 老板和管理员中心

管理员可以查看：

• 新增、等待、服务中和已结束会话；
• 按昵称、外部会话 ID、客服和状态检索；
• 访客、AI 和客服消息数量；
• 接入、转接、释放、结束、登录和失败登录记录；
• 禁用词、IP 拒绝和限流事件；
• 平均等待时间；
• 首次人工回复时间；
• 客服接待量、发送量、结束量和转接量；
• 每日趋势；
• 当前连接、连接峰值和累计请求；
• AI 请求、失败、排队和工作线程；
• 当前存储后端和协调后端。

管理员入口应尽量只用于查看和管理，不应与普通客服共用账号、密码和网络权限。

1.6 快捷命令与转人工关键词

“快捷命令”是在访客页面显示的按钮；“转人工关键词”用于识别用户主动请求人工。

常见转人工关键词：

人工客服
转人工
找客服
真人客服
我要人工
联系工作人员

建议保留一个专用“人工客服”命令类型，不要完全依赖自然语言模糊判断。业务快捷命令可设置为：

• 订单查询；
• 退款规则；
• 营业时间；
• 下载地址；
• 售后流程；
• 联系方式。

1.7 敏感词和禁用词怎样工作

当前匹配方式

• 默认敏感词列表为空，需要企业自行配置；
• 访客和客服发送的文字都会在服务端检查；
• 修改浏览器脚本不能绕过服务端检查；
• 当前采用不区分英文大小写的连续子串匹配；
• 多个词同时命中时会记录全部命中项，较长词优先处理；
• 可以选择拒绝发送或替换为星号；
• 星号模式保存替换后的正文，同时记录审计事件；
• 它不是 AI 语义审核，也不是正则表达式；
• 不会自动识别拆字、空格、同音字、拼音、繁简变体或图片中的文字；
• 常见变体需要分别配置。

不要轻易添加过短的单字，否则容易误伤正常咨询。优先使用完整短语，并先观察审计记录。

建议分类

推荐维护流程

1. 建立分类，不要把所有词混成一张表；
2. 初期使用“星号替换 + 审计”；
3. 根据误报和漏报调整；
4. 高风险词再改为“拒绝发送”；
5. 为每次变更记录日期、负责人、原因和测试结果；
6. 同时测试访客发送和客服发送；
7. 定期检查变体、拼音、空格和繁简写法。

1.8 表情控制

• 总开关关闭后，网页隐藏表情按钮；
• 服务端也应拒绝手工输入或粘贴的常见 Emoji；
• “可选表情”只决定面板显示哪些表情；
• 总开关开启时，服务端仍可能允许面板之外的 Emoji；
• 政务、企业内部支持或需要纯文本归档的场景，可以关闭表情。

1.9 安全设置

可信代理为什么重要

只有当请求直接来自已配置的可信代理时，程序才应接受 X-Forwarded-For 或 X-Real-IP。否则攻击者可以自行伪造这些请求头，绕过 IP 白名单、黑名单或限流。

1.10 默认限流与容量起点

以下是配置起点，不代表任何电脑都能稳定承载对应人数，正式上线必须压力测试：

1.11 AI 接待可靠性

• AI 请求进入有界后台队列，不长时间占住访客 HTTP 请求；
• 默认 AI 并发任务数和队列容量可以根据机器与模型速度调整；
• 同一会话按固定分区处理，减少连续问题回复乱序；
• 队列满时消息仍应保存，并提示转人工或稍后重试；
• 每条消息包含服务器序号、服务器时间和客户端消息 ID；
• 网络重试时应根据客户端消息 ID 去重；
• AI 故障不能阻止访客继续请求人工。

1.12 数据库、Redis 和备份

Redis 主要负责：

• 登录状态；
• 客服在线状态；
• 分布式限流；
• 会话锁；
• 事件广播。

Redis 不应作为正式聊天记录的唯一保存位置。

默认数据目录通常为：

%LocalAppData%\写吗\PluginData\WritingSystem.Plugin.CustomerService

备份建议：

1. 停止客服服务；
2. 同时备份数据库和附件；
3. 验证备份可以恢复；
4. 更新插件 DLL 时不要删除数据目录；
5. 卸载插件但需要保留历史时，只删除插件目录；
6. 自动清理只针对已结束会话，并按记录保留天数执行。

1.13 公网部署

推荐结构：

访客浏览器
    ↓ HTTPS
Nginx / Caddy / 云负载均衡
    ↓ 本机或内网 HTTP
写吗 AI 客服服务 127.0.0.1:28681

正式公网建议：

• 使用域名和有效 HTTPS 证书；
• 插件监听 127.0.0.1:28681；
• 只允许反向代理访问客服端口；
• 开启可信代理；
• 开启“非本机必须经过 HTTPS 代理”；
• 后台设置独立 IP 白名单；
• 更换高强度客服和管理员密码；
• 开启限流、黑名单、单客服单窗口和审计；
• 防火墙或云安全组不开放 28681 给普通公网用户；
• 根据真实图片流量、AI 延迟和数据库配置进行压力测试。

二、知识库回答原则

写作助手与在线客服可以读取同一项目资料库，但客服还会经过队列、会话和事实校验。为了让客户得到稳定答案，应遵守：

• 价格、日期、地址、电话、版本、套餐和型号等事实，只能来自本轮检索到的资料；
• 资料有明确答案时直接回答，不应只说“请查资料库”；
• 资料未命中时明确说明未找到，不推测“基础版、VIP 版”等不存在的名称；
• 短问题只有在“这个呢、一个月的呢”等明确追问时才继承上一轮主题；
• 被事实校验拦截的答案不能写入快速缓存。