# kefu 客服系统 · 操作说明书

> 适用对象：超级管理员、客服、运营、运维
> 文档版本：v1.0（2026-08-09）
> 在线地址：https://kefu.xiaozhusho.top
> 开发团队：kefu 开发团队 zero
> 邮箱：619864585@qq.com
> 测试账号：`admin` / `agent01` / `agent02`，初始密码 `admin123`

---

## 目录

1. [系统简介](#一系统简介)
2. [登录与基础操作](#二登录与基础操作)
3. [管理后台（超级管理员）操作指南](#三管理后台超级管理员操作指南)
4. [客服工作台操作指南](#四客服工作台操作指南)
5. [访客端使用说明](#五访客端使用说明)
6. [常见操作流程](#六常见操作流程)
7. [常见问题 FAQ](#七常见问题-faq)

---

## 一、系统简介

kefu 是一套面向企业的 **AI 智能客服系统**，包含三大子系统：

| 子系统 | 入口 | 用途 |
| --- | --- | --- |
| 管理后台 | `/admin/login.html` | 客服/部门/角色/权限、会话监控、报表、配置 |
| 客服工作台 | `/agent/login.html` | 在线接待、收发消息、转接、工单 |
| 访客端 SDK | `/widget/kefu.js` | H5/小程序/网站接入聊天窗口 |

**核心特性**：
- 多租户 SaaS 架构（按 `tenant_id` 隔离）
- 接入百度千帆大模型，支持 AI 智能接待
- 关键词 + 负面情绪 + 访客主动请求 → 三重触发转人工
- 三态消息机制（sending → delivered → read），保证消息可达
- 文件 + 进程内映射队列替代 WebSocket，**Windows 单进程即可运行**
- 支持微信公众号、小程序、网页、API 渠道接入

---

## 二、登录与基础操作

### 2.1 默认账号

| 账号 | 角色 | 权限范围 | 初始密码 |
| --- | --- | --- | --- |
| `admin` | 超级管理员（role_id=1） | 全部权限 | `admin123` |
| `agent01` | 普通客服（role_id=3） | 接待、留言、快捷回复 | `admin123` |
| `agent02` | 普通客服（role_id=3） | 同上 | `admin123` |

> 默认租户编码：`demo`（演示企业）。生产环境可创建新租户。

### 2.2 登录管理后台

1. 浏览器访问 https://kefu.xiaozhusho.top/admin/login.html
2. 输入账号、密码（`admin` / `admin123`）
3. 点击「登录」即可进入管理后台首页
4. 首页左侧为一级菜单（按权限过滤），右侧为子页面（以 iframe 加载）

### 2.3 登录客服工作台

1. 浏览器访问 https://kefu.xiaozhusho.top/agent/login.html
2. 输入客服账号（如 `agent01`）和密码
3. 登录后自动进入「在线接待」控制台
4. **登录即视为"在线"**，无需手动切换状态

### 2.4 退出登录

- 点击右上角头像 → 「退出」
- 或浏览器关闭后 60 分钟 Token 失效自动登出

### 2.5 修改密码

- 客服工作台右上角头像 → 「个人资料」→ 「修改密码」
- 管理员可在「员工列表」→ 选中员工 → 「重置密码」

---

## 三、管理后台（超级管理员）操作指南

> 入口：https://kefu.xiaozhusho.top/admin/login.html

### 3.1 主导航菜单

| 分组 | 菜单 | 说明 |
| --- | --- | --- |
| **会话管理** | 当前会话 / 历史会话 / 转接会话 | 监控进行中的会话 |
| **数据报表** | 实时数据 / 历史数据 / 坐席报表 / 质检报告 / 评价分析 | 业务数据看板 |
| **客户管理** | 员工列表 / 角色分配 / 部门管理 / 权限分配 / 客户管理 / 留言记录 / 在线坐席 | 员工与客户 |
| **业务功能** | 工单系统 / SLA 报表 / 标签管理 / 黑名单 | 业务流转 |
| **营销分析** | 多渠道接入 / 客户轨迹 / 营销活动 / 满意度调研 / 知识库 / 漏斗分析 | 营销与转化 |
| **通讯** | 站内信箱 / 访客留言 / 团队协作 | 内部沟通 |
| **系统设置** | AI 智能体 / 敏感词 / 系统设置 / 系统集成 / 接入指南 / 访客端样式 / 访客自定义字段 / 故障诊断 / 操作日志 | 配置中心 |

### 3.2 实时数据看板（首页默认页）

展示 8 个核心指标：

1. 今日新会话
2. 进行中会话
3. 今日消息量
4. 今日满意度
5. 在线客服
6. 今日待回复
7. 今日访客数
8. AI 接待中

下方含 4 张图表：
- 近 30 天会话趋势（折线图）
- 会话渠道分布（饼图）
- 24 小时时段分布（柱状图）
- 客服业务排行（Top 10）

### 3.3 员工管理

**路径**：`客户管理 → 员工列表`

操作步骤：
1. 点击「+ 新增员工」→ 填写用户名、姓名、工号、邮箱、手机、部门、角色、最大接待量、技能值
2. 「保存」后默认密码为 `admin123`，可点击「重置密码」修改
3. 删除员工 → 系统将自动关闭该员工遗留的活跃会话
4. 「查看权限」可看到该员工当前拥有的菜单/API 权限

### 3.4 角色与权限

**路径**：`客户管理 → 角色分配` / `权限分配`

- 内置 3 个角色：`admin`（超管）、`supervisor`（主管）、`agent`（客服）
- 可创建自定义角色，并为角色绑定权限（菜单权限 + API 权限）
- 修改后立即生效，前端菜单按 `data-perm` 自动过滤

### 3.5 部门管理

**路径**：`客户管理 → 部门管理`

- 支持多级部门（parent_id 树形）
- 每个部门可指定负责人（leader_id）
- 删除部门前需先迁移部门下的员工

### 3.6 多渠道接入

**路径**：`营销分析 → 多渠道接入`

支持的渠道：

| 渠道 | 类型 | 用途 |
| --- | --- | --- |
| 微信公众号 | 微信官方 | 服务号 / 订阅号咨询消息 |
| 微信小程序 | 微信官方 | 小程序客服消息 |
| 微信客服 | 微信官方 | 微信客服（新版 kfwork） |
| API 渠道 | 自定义 | 任何能调用 HTTP 的应用 |

每个渠道可绑定多个账号（如多店铺、多公众号），每个账号独立 URL：

```
POST https://kefu.xiaozhusho.top/api/channel/{code}/{account_id}
```

详细接入流程参考：`接入指南` 页面（`/docs/integration-guide.md`）。

### 3.7 AI 智能体配置

**路径**：`系统设置 → AI 智能体`

1. **启用 AI**：开关
2. **API Key / Secret Key**：百度千帆应用凭证
3. **系统提示词**：AI 人设、回答风格
4. **转人工关键词**：数组，访客命中即触发转人工
5. **转人工累计次数**：访客消息命中关键词累计 N 次后真正转人工（默认 1）
6. **负面情绪转人工**：开关 + 负面关键词
7. **最大回复耗时**：单次 AI 调用超时（毫秒）

点击「测试」可立即用一条样例消息验证 AI 是否连通。

### 3.8 敏感词管理

**路径**：`系统设置 → 敏感词`

- **访客敏感词**：访客发消息时被替换为同长度 `*` 号，不阻断发送
- **客服违禁词**：客服发消息时被拦截 / 替换 / 警告（按 action 配置）
- 支持普通词和正则（is_regex=1）
- 全局词库（tenant_id=0）对所有租户生效

### 3.9 系统设置

**路径**：`系统设置 → 系统设置`

可配置：
- 企业名称、联系电话、邮箱
- 会话超时（客户无操作多久自动关闭，默认 30 分钟）
- 评价超时（默认 24 小时）
- 留言自动回复

### 3.10 数据报表

**路径**：`数据报表 → 历史数据` / `坐席报表` / `质检报告` / `评价分析`

- 历史数据：按日 / 时段 / 渠道统计会话量、消息量、响应时长
- 坐席报表：每位客服的接待量、平均响应时长、满意度
- 质检报告：基于规则的会话质检命中记录
- 评价分析：满意度评分分布、评价标签云图

### 3.11 工单系统

**路径**：`业务功能 → 工单系统`

- 创建工单：标题、内容、分类、优先级、处理人、SLA 时间
- 流转：`pending → assigned → in_progress → replied → resolved → closed`
- 客户可重新开启已关闭工单（`reopen`）
- SLA 报表统计 SLA 命中率

### 3.12 知识库

**路径**：`营销分析 → 知识库`

- 树形分类管理
- 添加问答（标准问 + 答案 + 相似问法）
- 测试问答（输入问题，返回命中答案）
- 命中率统计（命中次数 / 解决次数 / 有用次数）

### 3.13 黑名单

**路径**：`业务功能 → 黑名单`

- 支持三种类型：`customer`（客户ID）、`ip`（IP）、`phone`（手机号）
- 可设置过期时间（NULL=永久）
- 命中黑名单的访客将无法发起新会话

### 3.14 站内信箱

**路径**：`通讯 → 站内信箱`

客服之间互发站内信，支持未读已读标记。

### 3.15 操作日志

**路径**：`系统设置 → 操作日志`

记录所有写操作（登录、增删改），可按模块、操作人、时间范围筛选。

---

## 四、客服工作台操作指南

> 入口：https://kefu.xiaozhusho.top/agent/login.html

### 4.1 主界面布局

```
┌────┬──────────────┬─────────────────────┬──────────┐
│ 📋 │ 会话列表      │ 聊天窗口             │ 客户信息  │
│ 👥 │ - 访客1       │ - 消息区              │ - 基本信息 │
│ 📊 │ - 访客2       │ - 输入区              │ - 历史会话 │
│ ...│ - 访客3       │ - 工具栏              │ - AI 接待  │
└────┴──────────────┴─────────────────────┴──────────┘
```

### 4.2 工作状态切换

右上角状态指示：
- 🟢 **在线**（默认）：自动接收新会话
- 🟡 **忙碌**：不接收自动分配，但保留当前会话
- ⚪ **离线**：不接收新会话

切换方式：点击状态指示下拉框 → 选择目标状态

### 4.3 收发消息

- **发送**：在输入框输入内容 → 按 Enter 发送（Shift+Enter 换行）
- **快捷回复**：点击输入区上方「📋 快捷回复」按钮 → 选择预设回复
- **插入图片 / 文件**：点击工具栏图标
- **消息状态**：
  - `sending`：发送中
  - `delivered`：已送达
  - `read`：对方已读

### 4.4 转接会话

1. 在聊天窗口右上角点击「↔️ 转接」按钮
2. 在弹窗中选择目标客服（显示其当前接待量）
3. 选择转接原因（如「专业问题」、「客服繁忙」）
4. 点击「确认转接」

转接后原客服自动解除绑定，目标客服接管会话并收到新消息提醒。

### 4.5 关闭会话

1. 点击右上角「✓ 关闭会话」
2. 选择关闭原因：已解决 / 客户离开 / 客服忙碌 / 转工单 / 转移其他
3. 确认关闭

关闭后会向访客发送评价邀请（24 小时内有效）。

### 4.6 接管历史会话

1. 点击左侧「历史会话」Tab
2. 找到超时或被关闭的会话
3. 点击「重新接管」→ 会话状态变为 `active`，自动分配给当前客服

### 4.7 个人资料

路径：右上角头像 → 「个人资料」

- 修改姓名、昵称、邮箱、手机
- 上传头像（自动裁剪为正方形）
- 修改密码
- 查看个人接待统计（今日 / 本周 / 本月）

### 4.8 知识库查询

路径：左侧菜单「知识库」

- 输入问题 → 检索标准问 + 相似问法 → 返回命中答案
- 一键将答案发送到当前会话

### 4.9 留言查看

路径：左侧菜单「留言」

- 查看分配给当前客服或所在部门的留言
- 回复留言（支持文字 / 图片）

### 4.10 服务小记

会话结束后，填写「服务小记」：
- 咨询分类
- 是否解决
- 备注
- 自定义字段值

用于后续质检和报表分析。

---

## 五、访客端使用说明

### 5.1 网页嵌入（推荐）

```html
<!-- 在网站 </body> 前插入 -->
<script src="https://kefu.xiaozhusho.top/widget/kefu.js" async></script>
<script>
  KefuWidget.init({
    tenantId: 1,                 // 租户 ID
    position: 'bottom-right',    // 位置：bottom-right / bottom-left
    name: '访客',                // 默认昵称（可后续修改）
    autoOpen: false,             // 是否自动展开窗口
  });
</script>
```

### 5.2 访客侧功能

- 💬 发送文字 / 图片 / 文件 / 表情
- 🤖 默认由 AI 接待（（自动启用））
- 🔄 输入关键词（如「人工」「客服」）→ 自动转人工
- 📊 实时显示排队位置
- ⭐ 会话结束后弹窗评价
- 📝 离线时填写留言

### 5.3 访客端 SDK API

| 方法 | 说明 |
| --- | --- |
| `KefuWidget.init(cfg)` | 初始化 |
| `KefuWidget.open()` / `close()` / `toggle()` | 控制窗口 |
| `KefuWidget.setVisitor({name, avatar, meta})` | 设置用户信息 |
| `KefuWidget.submitCustomFields(values)` | 提交自定义字段值 |
| `KefuWidget.on('message', cb)` | 监听消息事件 |

### 5.4 访客体验 Demo

访问 https://kefu.xiaozhusho.top/visitor-demo.html 即可体验。

---

## 六、常见操作流程

### 6.1 新增客服账号

```
1. 登录管理后台
2. 「员工列表」 → 「+ 新增员工」
3. 填写：用户名、姓名、部门、角色（选 agent）、最大接待量
4. 保存 → 默认密码 admin123
5. 通知客服登录工作台 → 自行修改密码
```

### 6.2 启用 AI 智能接待

```
1. 登录管理后台
2. 「AI 智能体」→ 启用开关
3. 填写百度千帆 API Key / Secret Key
4. 配置系统提示词（人设）
5. 配置转人工关键词（默认：人工、客服、投诉）
6. 点击「测试」验证 AI 连通
7. 保存 → 立即生效
```

### 6.3 接入微信公众号

```
1. 登录管理后台
2. 「多渠道接入」→ 选择「微信公众号」 → 启用
3. 「+ 新增账号」→ 填写：账号名称、AppID、AppSecret、Token、EncodingAESKey
4. 点击「验通」验证凭证
5. 在公众号后台填写服务器 URL（自动生成）：
   https://kefu.xiaozhusho.top/api/channel/wechat/{account_id}
6. 启用 Token 校验
```

### 6.4 处理客户投诉

```
1. 客服工作台收到会话（含敏感词标记）
2. 查看客户画像 / 历史会话 / 订单
3. 必要时邀请主管协作（点击「👥 协作」）
4. 填写服务小记（分类：投诉；是否解决：是）
5. 关闭会话 → 邀请客户评价
6. 主管在「质检报告」中复核
```

### 6.5 创建工单

```
1. 客服工作台会话中点击「📋 转工单」
2. 选择分类、优先级、分配人、SLA 时间
3. 提交 → 工单进入待处理队列
4. 处理人在「工单系统」中查看并处理
5. 处理完成后工单状态变为 resolved → closed
```

### 6.6 数据导出

```
1. 管理后台「数据报表」→ 选择报表
2. 选择时间范围 → 点击「导出 CSV」
3. 文件自动下载到本地
```

---

## 七、常见问题 FAQ

### Q1：登录后看不到菜单？
**A**：当前账号没有该模块的权限。请联系超级管理员在「权限分配」中授予对应权限。

### Q2：客服登录后没有自动接收新会话？
**A**：
- 确认右上角工作状态是「在线」（非「忙碌」或「离线」）
- 确认「最大接待量」未达到上限
- 确认员工账号状态为「正常」（非「禁用」）

### Q3：消息发送失败？
**A**：
- 检查网络连接
- 检查 Token 是否过期（60 分钟），重新登录
- 查看 `runtime/logs/webman.log` 日志

### Q4：AI 不回复？
**A**：
- 确认「AI 智能体」开关已启用
- 确认 API Key 配置正确，点击「测试」验证
- 检查百度千帆账户余额

### Q5：访客侧看不到聊天窗口？
**A**：
- 检查 SDK 加载（浏览器控制台是否有 404 / JS 错误）
- 检查 `tenantId` 是否正确
- 检查域名是否被防火墙拦截

### Q6：Windows 下启动失败？
**A**：
- 在 `server/` 目录下执行 `php start.php start`
- Windows 下部分定时任务自动运行（cron-worker），需在 `start.php` 启动
- 详细日志：`server/runtime/logs/webman.log`

### Q7：超时会话没自动关闭？
**A**：
- 确认「系统设置」中「会话超时」已配置
- 系统每 60 秒检查一次，可能存在 1 分钟延迟
- 也可在「系统设置 → 系统设置」中点击「立即清理超时会话」

### Q8：怎么备份数据？
**A**：
```bash
mysqldump -u kefu -p kefu > kefu_backup_$(date +%Y%m%d).sql
```
建议每天定时备份，保留至少 30 天。

### Q9：怎么升级到新版本？
**A**：
1. 备份数据库
2. 替换 `server/` 目录代码
3. 执行新的 `sql/migration_*.sql` 升级脚本
4. 重启服务：`php start.php restart`

### Q10：技术联系方式？
**A**：邮箱 619864585@qq.com，或参考项目根目录 `README.md`。

---

## 附录 A：快捷键

| 快捷键 | 功能 |
| --- | --- |
| `Enter` | 发送消息 |
| `Shift + Enter` | 换行 |
| `Ctrl + K` | 快速搜索 |
| `Esc` | 关闭弹窗 |
| `Alt + 1~9` | 切换左侧 Tab |

## 附录 B：术语表

| 术语 | 含义 |
| --- | --- |
| 租户（Tenant） | 一个企业客户，资源完全隔离 |
| 会话（Session） | 一次完整的人或 AI 与访客的 |
| 工单（Ticket） | 需要跨部门协作处理的工单 |
| 转人工（H | 从 AI 接待切换到人工客服 |
| SLA | 服务水平协议（响应 / 解决时长） |
| 三态消息 | sending → delivered → read |
| 漏斗（Funnel） | 访客从进入到转化的各阶段统计 |
| 自定义字段 | 业务侧自定义的客户扩展属性 |

---

**文档维护**：kefu 开发团队 zero
**最后更新**：2026-08-10
**邮箱**：619864585@qq.com