# 自动客服使用说明

## 运行方式

1. 启动 `build/bin/qiweimanager.exe`。
2. 确认当前企业微信账号已经被工具接管。这里的“机器人”就是当前登录并被接管的企微账号。
3. 进入左侧菜单“自动客服”。
4. 配置 AI、知识库、人工接管信息。
5. 点击“重建知识库索引”。
6. 点击“测试 AI”和“测试人工私信”确认可用。
7. 打开总开关后，helper 会开始监听入站消息并自动处理。

## 知识库目录

默认目录是：

```text
config/knowledge
```

如果从发布目录运行，则实际目录通常是：

```text
build/bin/config/knowledge
```

支持的文件格式：

```text
.md
.txt
.csv
.xlsx
.docx
.pdf
```

建议把常见问题、产品介绍、价格说明、售后规则等内容拆成短段落。每次增删改知识库文件后，都需要在“自动客服”页面点击“重建知识库索引”。

PDF 解析目前是基础文本提取，扫描件或复杂编码 PDF 可能无法提取出有效内容。遇到这种文件，建议先转成 `.md`、`.txt`、`.docx` 或 `.xlsx`。

## AI 配置

第一种方式是 OpenAI-compatible 接口，例如：

```text
Provider: openai
Base URL: https://api.openai.com
Model: gpt-4o-mini
API Key: sk-...
```

程序会请求：

```text
/v1/chat/completions
```

第二种方式是本地 Ollama：

```text
Provider: ollama
Base URL: http://localhost:11434
Model: qwen2.5:7b
```

程序会请求：

```text
/api/chat
```

无论使用哪种 AI，提示词都会要求 AI 只能基于知识库片段回答。知识库没有答案时，AI 应输出 `NO_ANSWER`，系统会自动转人工。

## 消息触发规则

自动客服只处理文本消息：

```text
event = 20002
type  = 11041
```

私聊文本会自动处理。群聊文本只有在消息 @ 当前接管账号时才会处理。自己发送的消息会被忽略，重复消息会按 `robotId + conversationId + serverId/localId` 去重。

以下情况会转人工：

```text
知识库匹配分数太低
AI 超时或失败
AI 返回空内容
AI 返回 NO_ANSWER
命中敏感关键词
问题过长
自动回复发送失败
```

默认敏感关键词包括退款、投诉、合同、发票、赔偿、价格审批等，可在前端配置里调整。

## 转人工配置

优先填写 `humanConversationId`，这是最稳定的私信会话 ID。

如果没有 `humanConversationId`，可以填写 `humanUserId`。系统会尝试推导：

```text
S:<robotId>_<humanUserId>
```

推导不一定适用于所有企业微信版本，所以配置后请点击“测试人工私信”。测试成功后，再打开自动客服总开关。

## 已保留的兼容接口

以下原有接口保持不变：

```text
POST /api/send-wxwork-data
POST /api/third-party-request
```

原有 callback 推送、dashboard、requestdata 模板调用链也保持兼容。