# 企业微信自动客服改造方案

## 1. 目标概述

当前项目已经具备企业微信消息管理能力，后端 `helper.exe` 通过 DLL 注入、Socket 回调、本地 HTTP 服务和 `requestdata` / `eventdata` 模板，能够接收企业微信事件并发送企业微信消息。

本次需求是在现有能力上增加“自动客服”模块：

- 前端提供一键开启入口。
- 后端自动监听企业微信消息。
- 私聊客户消息自动处理。
- 群聊消息仅在用户 @ 当前机器人时处理。
- 根据本地知识库检索内容。
- 调用 AI 根据知识库内容生成回复。
- 能回答则自动回复客户。
- 不能回答、AI 失败或知识库低匹配时，自动私信指定同事转人工处理。

## 2. 当前项目基础

### 2.1 技术结构

项目当前是：

- 桌面端：Wails
- 后端主程序：Go，`qiweimanager.exe`
- 辅助进程：Go，`helper.exe`
- 前端：Vue 3 + Vite + Element Plus
- 本地 HTTP 服务：默认 `http://localhost:10001`
- 企业微信底层通信：`Helper_4.1.33.6009.dll`、`Loader_4.1.33.6009.dll`
- 发送消息模板：`requestdata/*.json`
- 接收事件模板：`eventdata/*.json`

### 2.2 已有关键能力

现有项目已经支持：

- 启动/注入企业微信：`type=10000`
- 发送文本消息：`requestdata/sendVWorkTextMessage.json`
- 群 @ 消息：`requestdata/sendVWorkGroupAtMessage.json`
- 获取群列表：`requestdata/getVWorkGroupList.json`
- 获取内部好友列表：`requestdata/getVWorkInternalFriendList.json`
- 获取外部联系人列表：`requestdata/getVWorkExternalFriendList.json`
- 接收企业微信消息回调：`helper.go` 中的 `MyRecvCallback`
- 事件转换：`TransformData` 使用 `eventdata/<type>.json`
- 本地 HTTP 管理页面：`http://localhost:10001/`
- 操作日志和前端配置管理

### 2.3 最适合接入的位置

自动客服的核心入口建议放在：

```text
helper/helper.go
MyRecvCallback(...)
```

原因：

- 这里能拿到所有企业微信入站事件。
- 当前已经在这里做了消息解析、时间过滤、ResponseChannel 判断、回调转发。
- 自动客服需要的是“被动监听消息”，不是主动请求响应，所以这里最自然。
- 可保持现有 `/api/send-wxwork-data`、`/api/third-party-request` 和 callback 功能不被破坏。

## 3. 总体架构设计

### 3.1 新增模块

建议新增以下模块：

```text
config/
  types.go                       # 增加 AutoReplyConfig 配置结构

helper/
  auto_reply.go                  # 自动客服主流程
  auto_reply_ai.go               # AI 调用适配
  auto_reply_knowledge.go        # 本地知识库解析、索引、检索
  auto_reply_handoff.go          # 转人工通知
  auto_reply_status.go           # 状态统计、运行记录
  auto_reply_http.go             # helper 侧自动客服 HTTP 接口

frontend/src/
  components/AutoReply.vue       # 自动客服配置和状态页面
```

如果希望少建文件，也可以把 helper 侧先合并为 2 到 3 个文件，但不建议全部塞进 `helper.go`，否则后续维护会变得很吃力。

### 3.2 消息处理链路

整体链路如下：

```text
企业微信收到消息
  ↓
DLL Socket 回调
  ↓
helper.go / MyRecvCallback
  ↓
解析原始 JSON
  ↓
判断是否是主动请求响应
  ↓
如果是响应：继续走现有 ResponseChannel
  ↓
如果是独立入站消息：进入自动客服判断
  ↓
转换 eventdata 结构
  ↓
判断是否需要处理
  ↓
知识库检索
  ↓
AI 生成回复
  ↓
发送企业微信文本消息
  ↓
失败或无法回答时私信指定同事
```

### 3.3 不破坏现有功能的原则

自动客服必须做到：

- 不影响当前前端“启动企微”。
- 不影响现有 requestdata 模板调用。
- 不影响第三方 callback。
- 不影响本地 dashboard。
- 不影响主动请求等待回调的逻辑。
- 自动客服出错不能导致 `helper.exe` 崩溃。
- 自动客服处理必须异步，不阻塞 `MyRecvCallback`。

## 4. 配置设计

### 4.1 在 config 中新增 autoReplyConfig

建议在 `config/types.go` 中新增：

```go
type AutoReplyConfig struct {
    Enabled bool `json:"enabled"`

    Listen ListenConfig `json:"listen"`
    Knowledge KnowledgeConfig `json:"knowledge"`
    AI AIConfig `json:"ai"`
    Handoff HandoffConfig `json:"handoff"`
    ReplyPolicy ReplyPolicyConfig `json:"replyPolicy"`
}

type ListenConfig struct {
    EnablePrivateChat bool `json:"enablePrivateChat"`
    EnableGroupChat bool `json:"enableGroupChat"`
    GroupTriggerMode string `json:"groupTriggerMode"`
    IgnoreSelfMessage bool `json:"ignoreSelfMessage"`
    DeduplicateSeconds int `json:"deduplicateSeconds"`
}

type KnowledgeConfig struct {
    Directory string `json:"directory"`
    IndexPath string `json:"indexPath"`
    SupportedExtensions []string `json:"supportedExtensions"`
    TopK int `json:"topK"`
    MinScore float64 `json:"minScore"`
    AutoRebuildOnStart bool `json:"autoRebuildOnStart"`
}

type AIConfig struct {
    Provider string `json:"provider"`
    BaseURL string `json:"baseUrl"`
    APIKey string `json:"apiKey"`
    Model string `json:"model"`
    TimeoutSeconds int `json:"timeoutSeconds"`
    Temperature float64 `json:"temperature"`
    MaxTokens int `json:"maxTokens"`
}

type HandoffConfig struct {
    HumanUserID string `json:"humanUserId"`
    HumanConversationID string `json:"humanConversationId"`
    MessageTemplate string `json:"messageTemplate"`
    IncludeKnowledgeHits bool `json:"includeKnowledgeHits"`
}

type ReplyPolicyConfig struct {
    UnknownAnswerToken string `json:"unknownAnswerToken"`
    MaxQuestionLength int `json:"maxQuestionLength"`
    CooldownSeconds int `json:"cooldownSeconds"`
}
```

并把它挂到现有配置：

```go
type Config struct {
    CallbackConfig CallbackConfig `json:"callbackConfig"`
    AutoReplyConfig AutoReplyConfig `json:"autoReplyConfig"`
    LastUpdated int64 `json:"lastUpdated"`
}
```

### 4.2 默认配置

默认值建议：

```json
{
  "autoReplyConfig": {
    "enabled": false,
    "listen": {
      "enablePrivateChat": true,
      "enableGroupChat": true,
      "groupTriggerMode": "mention_only",
      "ignoreSelfMessage": true,
      "deduplicateSeconds": 300
    },
    "knowledge": {
      "directory": "config/knowledge",
      "indexPath": "config/knowledge/index.json",
      "supportedExtensions": [".md", ".txt", ".csv", ".xlsx", ".docx", ".pdf"],
      "topK": 5,
      "minScore": 0.35,
      "autoRebuildOnStart": false
    },
    "ai": {
      "provider": "openai_compatible",
      "baseUrl": "",
      "apiKey": "",
      "model": "",
      "timeoutSeconds": 25,
      "temperature": 0.2,
      "maxTokens": 800
    },
    "handoff": {
      "humanUserId": "",
      "humanConversationId": "",
      "messageTemplate": "客户问题需要人工处理：\n客户：{{customerName}}\n问题：{{question}}\n来源：{{source}}\n会话：{{conversationId}}\n原因：{{reason}}",
      "includeKnowledgeHits": true
    },
    "replyPolicy": {
      "unknownAnswerToken": "NO_ANSWER",
      "maxQuestionLength": 1000,
      "cooldownSeconds": 3
    }
  }
}
```

## 5. 前端改造方案

### 5.1 新增菜单

在 `frontend/src/App.vue` 左侧菜单新增：

```text
自动客服
```

建议位置：

```text
系统首页
企微账号
自动客服
操作记录
回调配置
```

### 5.2 新增 AutoReply.vue 页面

页面模块建议分为 6 块：

1. 运行状态
2. 一键开启/关闭
3. AI 配置
4. 知识库配置
5. 人工接管配置
6. 最近处理记录

### 5.3 运行状态区

显示：

- 自动客服状态：未开启 / 运行中 / 错误
- helper 连接状态
- 当前活跃企微账号数
- 知识库文件数
- 知识库切片数
- 今日处理消息数
- 今日自动回复数
- 今日转人工数
- 今日 AI 失败数
- 今日忽略消息数

### 5.4 一键开启按钮

按钮行为：

```text
点击“一键开启自动客服”
  ↓
保存当前自动客服配置
  ↓
调用启动企微 type=10000
  ↓
通知 helper reload 配置
  ↓
如果知识库索引不存在，提示并重建索引
  ↓
自动客服状态变为运行中
```

对应 Wails 方法：

```go
SetAutoReplyEnabled(true)
```

### 5.5 AI 配置区

字段：

- AI 类型：
  - OpenAI 兼容接口
  - 本地模型接口
- Base URL
- API Key
- Model
- Timeout
- Temperature
- Max Tokens
- 测试连接按钮

OpenAI 兼容接口示例：

```text
https://api.openai.com/v1
https://api.deepseek.com/v1
http://localhost:1234/v1
```

本地模型接口示例：

```text
http://localhost:11434
```

### 5.6 知识库配置区

字段：

- 本地知识库目录
- 支持格式展示：md、txt、csv、xlsx、docx、pdf
- TopK
- 最低匹配分数
- 重建知识库索引按钮
- 上次索引时间
- 索引结果

### 5.7 人工接管配置区

字段：

- 指定同事 user_id
- 指定同事 conversation_id
- 转人工消息模板
- 是否附带知识库命中片段
- 测试发送按钮

说明：

- 最稳妥方式是配置 `humanConversationId`。
- 如果只配置 `humanUserId`，后端按 `S:<robotId>_<humanUserId>` 推导 conversationId。
- 页面必须提供“测试发送”，确认能私信到指定同事。

## 6. Wails 后端接口方案

在 `app.go` 中新增方法：

```go
func (a *App) GetAutoReplyConfig() interface{}
func (a *App) SaveAutoReplyConfig(jsonData string) (bool, string)
func (a *App) SetAutoReplyEnabled(enabled bool) (bool, string)
func (a *App) GetAutoReplyStatus() interface{}
func (a *App) RebuildKnowledgeIndex() interface{}
func (a *App) TestAIConnection() interface{}
func (a *App) TestHumanHandoff() interface{}
```

这些方法主要负责：

- 读写 `config/config.json`
- 转发请求到 `helper.exe`
- 返回统一格式给前端

统一返回格式建议：

```json
{
  "success": true,
  "message": "ok",
  "data": {}
}
```

失败时：

```json
{
  "success": false,
  "message": "错误原因",
  "data": null
}
```

## 7. helper HTTP 接口方案

在 helper 本地 HTTP 服务中新增：

```text
GET  /api/auto-reply/status
POST /api/auto-reply/reload
POST /api/auto-reply/rebuild-knowledge
POST /api/auto-reply/test-ai
POST /api/auto-reply/test-handoff
```

### 7.1 GET /api/auto-reply/status

返回：

```json
{
  "success": true,
  "data": {
    "enabled": true,
    "running": true,
    "lastError": "",
    "knowledgeFileCount": 10,
    "knowledgeChunkCount": 320,
    "todayReceived": 100,
    "todayReplied": 60,
    "todayHandoff": 12,
    "todayIgnored": 28,
    "lastMessages": []
  }
}
```

### 7.2 POST /api/auto-reply/reload

用途：

- 重新加载 `config/config.json`
- 重新初始化自动客服配置
- 不重启 helper

### 7.3 POST /api/auto-reply/rebuild-knowledge

用途：

- 扫描本地知识库目录
- 解析文档
- 构建索引
- 写入 `config/knowledge/index.json`

### 7.4 POST /api/auto-reply/test-ai

用途：

- 使用当前 AI 配置发起一次测试请求
- 不进入企业微信消息流程

### 7.5 POST /api/auto-reply/test-handoff

用途：

- 给指定同事发送一条测试私信
- 验证 `humanConversationId` 或 `humanUserId` 是否正确

## 8. 自动客服消息判断规则

### 8.1 只处理文本消息

当前文本消息模板主要是：

```text
eventdata/11041.json
event = 20002
```

自动客服初版只处理：

```json
{
  "event": "20002",
  "data": {
    "message": "...",
    "conversationId": "...",
    "fromWxId": "...",
    "toWxId": "...",
    "fromNickName": "...",
    "atWxIdList": []
  }
}
```

非文本消息处理策略：

- 图片：转人工
- 文件：转人工
- 语音：转人工
- 视频：转人工
- 位置：转人工
- 链接：转人工
- 名片：转人工

### 8.2 私聊处理规则

私聊消息满足：

- 不是群聊 conversationId
- 不是机器人自己发出的消息
- 文本内容不为空
- 没有重复处理过

则自动处理。

### 8.3 群聊处理规则

群聊消息必须满足：

- 是群聊 conversationId
- 文本消息
- 不是机器人自己发出的消息
- `atWxIdList` 包含当前机器人 ID，或文本内容包含 @ 当前机器人昵称
- 未重复处理

未 @ 机器人时：

- 不回复
- 计入 ignored
- dashboard 可记录原因：`group message without mention`

### 8.4 自己消息过滤

如果满足以下任一条件，忽略：

- `fromWxId == robotId`
- `fromWxId == 当前登录企微 user_id`
- 原始消息标记为自己发送
- `sender == receiver` 且能确认是本机消息

### 8.5 去重策略

使用以下字段生成去重 key：

```text
robotId + conversationId + serverId
```

如果没有 `serverId`：

```text
robotId + conversationId + localId + sendTime + fromWxId
```

默认 300 秒内重复消息不处理。

## 9. 知识库方案

### 9.1 本地目录

默认目录：

```text
config/knowledge/
```

建议结构：

```text
config/knowledge/
  faq.md
  product.md
  price.xlsx
  after-sales.docx
  policy.pdf
  index.json
```

### 9.2 支持格式

用户选择“全都支持”，因此初版支持：

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

### 9.3 解析策略

不同文件策略：

- Markdown/TXT：按标题和段落切分。
- CSV：按行切分，每行拼接字段名和值。
- Excel：按 sheet + 行切分。
- DOCX：提取段落文本后切分。
- PDF：提取页面文本后切分。

每个 chunk 建议结构：

```json
{
  "id": "hash",
  "source": "faq.md",
  "title": "售后政策",
  "content": "具体内容",
  "line": 12,
  "page": 0,
  "updatedAt": 1710000000,
  "hash": "..."
}
```

### 9.4 检索策略

初版不引入向量库，使用本地关键词 / BM25 风格检索：

- 中文分词可先用 rune bigram + keyword 简化实现。
- 英文按空格和标点切词。
- 计算 query 和 chunk 的相关度。
- 返回 topK。
- 最高分低于 `minScore` 时认为知识库无法回答。

默认：

```text
topK = 5
minScore = 0.35
```

### 9.5 后续增强方向

后续可以升级为：

- 本地 embedding
- OpenAI embedding
- SQLite FTS5
- 向量数据库
- 混合检索

但初版不建议一开始引入复杂依赖，先把闭环跑通。

## 10. AI 调用方案

### 10.1 OpenAI 兼容接口

请求：

```text
POST {baseUrl}/chat/completions
Authorization: Bearer {apiKey}
```

如果用户填写的 `baseUrl` 是：

```text
https://api.openai.com/v1
```

则最终请求：

```text
https://api.openai.com/v1/chat/completions
```

请求体：

```json
{
  "model": "gpt-4.1-mini",
  "temperature": 0.2,
  "max_tokens": 800,
  "messages": [
    {
      "role": "system",
      "content": "你是企业微信客服助手，只能基于知识库回答。知识库没有答案时输出 NO_ANSWER。"
    },
    {
      "role": "user",
      "content": "客户问题 + 知识库片段"
    }
  ]
}
```

### 10.2 本地模型接口

默认适配 Ollama：

```text
POST {baseUrl}/api/chat
```

请求体：

```json
{
  "model": "qwen2.5",
  "stream": false,
  "messages": [
    {
      "role": "system",
      "content": "你是企业微信客服助手，只能基于知识库回答。知识库没有答案时输出 NO_ANSWER。"
    },
    {
      "role": "user",
      "content": "客户问题 + 知识库片段"
    }
  ]
}
```

如果本地模型提供 OpenAI-compatible 接口，则用户直接选择 OpenAI 兼容模式即可。

### 10.3 Prompt 约束

系统提示词建议：

```text
你是企业微信客服助手。
你只能根据提供的知识库片段回答客户问题。
如果知识库片段不能支持答案，必须只输出 NO_ANSWER。
不要编造政策、价格、承诺、库存、物流时效。
回答要简洁、礼貌、像真人客服。
如果客户要求人工、投诉、退款、合同、发票、价格特殊审批，也输出 NO_ANSWER。
```

用户消息格式：

```text
客户昵称：{{fromNickName}}
客户问题：{{question}}

知识库片段：
[1] {{chunk1}}
[2] {{chunk2}}
[3] {{chunk3}}

请基于知识库回答。
```

### 10.4 AI 无法回答判定

以下情况触发转人工：

- 知识库最高分低于阈值。
- AI 返回 `NO_ANSWER`。
- AI 返回空字符串。
- AI HTTP 调用失败。
- AI 超时。
- AI 返回结构无法解析。
- 消息是非文本。
- 客户明确要求人工客服。
- 客户问题超过最大长度。
- 命中敏感业务关键词，例如退款、投诉、合同、发票、赔偿等。

## 11. 自动回复发送方案

### 11.1 私聊回复

使用已有模板：

```text
requestdata/sendVWorkTextMessage.json
```

转换后的底层 type：

```json
{
  "type": 11029,
  "data": {
    "conversation_id": "{{conversationId}}",
    "content": "{{answer}}"
  }
}
```

调用方式：

```go
sendTextToConversation(clientId, conversationId, answer)
```

### 11.2 群聊回复

群聊 @ 机器人后，默认回复到原群：

```text
conversationId = 原消息 conversationId
```

可选策略：

- 默认不 @ 提问人，只回复文本。
- 后续可以增加 `replyWithAtSender` 开关，使用 `sendVWorkGroupAtMessage`。

初版建议默认不 @，避免 atList 字段兼容问题带来发送失败。

## 12. 转人工私信方案

### 12.1 私信对象配置

用户要求：

```text
直接发私信给指定同事的企业微信
```

因此配置：

```json
{
  "humanUserId": "指定同事user_id",
  "humanConversationId": "指定同事私聊conversation_id"
}
```

优先级：

1. 如果配置了 `humanConversationId`，直接使用。
2. 如果没有配置，则使用 `S:<robotId>_<humanUserId>` 推导。
3. 如果推导失败或发送失败，记录错误并在前端状态展示。

### 12.2 转人工消息内容

默认模板：

```text
客户问题需要人工处理

客户：{{customerName}}
客户ID：{{fromWxId}}
来源：{{source}}
会话ID：{{conversationId}}
问题：{{question}}
原因：{{reason}}
时间：{{time}}

请及时处理。
```

如果开启 `includeKnowledgeHits`，追加：

```text
知识库候选：
1. {{source}} / score={{score}}
2. {{source}} / score={{score}}
```

### 12.3 转人工触发原因枚举

建议原因：

```text
knowledge_low_score
ai_no_answer
ai_timeout
ai_http_error
ai_parse_error
non_text_message
manual_keyword
send_reply_failed
config_missing
```

前端展示时转成中文。

## 13. 状态统计和运行记录

新增内存状态对象：

```go
type AutoReplyStatus struct {
    Enabled bool
    Running bool
    LastError string

    KnowledgeFileCount int
    KnowledgeChunkCount int
    KnowledgeLastIndexedAt int64

    TodayReceived int
    TodayReplied int
    TodayHandoff int
    TodayIgnored int
    TodayAIFailed int

    LastMessages []AutoReplyRecord
}
```

运行记录：

```go
type AutoReplyRecord struct {
    ID int64
    Time string
    RobotID string
    ConversationID string
    Source string
    FromWxID string
    FromNickName string
    Question string
    Action string
    Reason string
    Answer string
}
```

`Action` 可选：

```text
ignored
replied
handoff
failed
```

## 14. 错误处理策略

### 14.1 自动客服不能影响主流程

自动客服所有处理都必须：

- `recover` panic
- 写日志
- 更新状态
- 不向外抛出导致 `MyRecvCallback` 异常

### 14.2 AI 超时

默认：

```text
25 秒
```

超时后：

- 不继续等待。
- 转人工。
- 状态计入 `TodayAIFailed` 和 `TodayHandoff`。

### 14.3 发送失败

自动回复发送失败时：

- 记录失败。
- 转人工通知。
- 如果转人工也失败，写入 `LastError`。

### 14.4 知识库索引失败

单个文件失败：

- 不影响其他文件。
- 在前端显示失败文件。
- 写入日志。

全部失败：

- 自动客服仍可开启。
- 所有问题都会因为知识库低分而转人工。

## 15. 实施步骤

### 阶段一：配置和接口骨架

1. 扩展 `config/types.go`，加入自动客服配置结构。
2. 修改默认配置生成逻辑。
3. 在 `app.go` 增加 Wails 方法：
   - `GetAutoReplyConfig`
   - `SaveAutoReplyConfig`
   - `SetAutoReplyEnabled`
   - `GetAutoReplyStatus`
4. 在 helper HTTP server 增加自动客服路由。
5. 确认现有编译不受影响。

### 阶段二：前端自动客服页面

1. 新增 `frontend/src/components/AutoReply.vue`。
2. 修改 `App.vue` 侧边栏，增加“自动客服”菜单。
3. 实现配置读取、保存、开关、状态刷新。
4. 实现测试 AI、测试人工私信、重建知识库按钮。
5. 保持当前 UI 风格，不做大规模视觉重构。

### 阶段三：知识库模块

1. 创建 `helper/auto_reply_knowledge.go`。
2. 实现本地目录扫描。
3. 实现 `.md/.txt/.csv` 解析。
4. 实现 `.xlsx/.docx/.pdf` 解析。
5. 实现 chunk 切分。
6. 实现索引保存和加载。
7. 实现关键词/BM25 风格检索。
8. 将统计信息暴露给状态接口。

### 阶段四：AI 模块

1. 创建 `helper/auto_reply_ai.go`。
2. 实现 OpenAI-compatible 调用。
3. 实现 Ollama 本地模型调用。
4. 实现 prompt 构造。
5. 实现 `NO_ANSWER` 判断。
6. 实现 AI 测试接口。

### 阶段五：消息监听和自动回复

1. 创建 `helper/auto_reply.go`。
2. 在 `MyRecvCallback` 中接入自动客服入口。
3. 确保 ResponseChannel 响应不触发自动客服。
4. 实现文本消息过滤。
5. 实现私聊自动处理。
6. 实现群聊 @ 机器人处理。
7. 实现去重。
8. 实现调用知识库 + AI + 发送回复。

### 阶段六：转人工私信

1. 创建 `helper/auto_reply_handoff.go`。
2. 实现转人工消息模板渲染。
3. 实现指定同事私信发送。
4. 实现测试发送。
5. 自动回复失败时触发转人工。

### 阶段七：测试和验证

1. 增加 Go 单元测试。
2. 增加 mock AI server 测试。
3. 前端执行 `npm run build`。
4. Go 执行 `go test ./...`。
5. 构建 helper。
6. 构建 Wails。
7. 实机验证私聊、群聊 @、群聊未 @、转人工。

## 16. 测试用例

### 16.1 私聊文本自动回复

输入：

```json
{
  "event": "20002",
  "data": {
    "conversationId": "S:customer_robot",
    "fromWxId": "customer",
    "toWxId": "robot",
    "message": "你们营业时间是几点？"
  }
}
```

预期：

- 检索知识库。
- 调用 AI。
- 发送回复到原 conversationId。
- 状态 `TodayReplied +1`。

### 16.2 群聊未 @ 不回复

输入：

```json
{
  "event": "20002",
  "data": {
    "conversationId": "R:group",
    "fromWxId": "customer",
    "message": "你们营业时间是几点？",
    "atWxIdList": []
  }
}
```

预期：

- 不调用 AI。
- 不发送消息。
- 状态 `TodayIgnored +1`。

### 16.3 群聊 @ 机器人自动回复

输入：

```json
{
  "event": "20002",
  "data": {
    "conversationId": "R:group",
    "fromWxId": "customer",
    "message": "@机器人 你们营业时间是几点？",
    "atWxIdList": ["robot"]
  }
}
```

预期：

- 调用知识库。
- 调用 AI。
- 回复到原群。

### 16.4 知识库无答案转人工

输入：

```text
你们能不能帮我办理完全无关的问题？
```

预期：

- 检索低分。
- 不调用或不采纳 AI。
- 私信指定同事。
- 状态 `TodayHandoff +1`。

### 16.5 AI 返回 NO_ANSWER 转人工

AI 输出：

```text
NO_ANSWER
```

预期：

- 不回复客户。
- 私信指定同事。
- 状态 `TodayAIFailed +1`、`TodayHandoff +1`。

### 16.6 AI 超时转人工

预期：

- 超过 timeout 后触发转人工。
- 不阻塞后续消息处理。

### 16.7 重复消息不重复回复

同一个 `serverId` 连续进入两次。

预期：

- 第一次处理。
- 第二次忽略。

## 17. 验收标准

完成后应满足：

- 前端有“自动客服”页面。
- 能一键开启/关闭自动客服。
- 能配置 AI 接口。
- 能配置本地知识库目录。
- 能重建知识库索引。
- 能测试 AI 连接。
- 能配置指定人工同事并测试私信。
- 私聊客户文本消息能自动回复。
- 群聊只有 @ 机器人时才自动回复。
- 未 @ 的群消息不会回复。
- AI 无法回答时能私信指定同事。
- 自动客服处理失败不影响现有企业微信管理能力。
- 原有 `http://localhost:10001/` dashboard 和 requestdata 接口保持可用。

## 18. 风险点和注意事项

### 18.1 conversationId 推导风险

私信指定同事最好配置明确的 `humanConversationId`。

如果只配置 `humanUserId`，按 `S:<robotId>_<humanUserId>` 推导可能因企业微信内部规则不同而失败，因此必须提供“测试发送”。

### 18.2 群聊 @ 判断风险

有些事件可能 `atWxIdList` 不完整，因此群聊触发判断应同时支持：

- `atWxIdList` 包含机器人 ID
- 文本内容包含 `@机器人昵称`

### 18.3 AI 胡答风险

必须强制 AI 只基于知识库回答。

如果知识库没有答案，AI 必须输出 `NO_ANSWER`。

### 18.4 文件解析依赖风险

`.xlsx/.docx/.pdf` 支持会引入新依赖或额外解析逻辑。

如果希望第一版更稳，可以先实现 `.md/.txt/.csv`，但本需求要求“全都支持”，因此计划里按全格式支持实现。

### 18.5 不阻塞 DLL 回调

AI 调用和知识库检索都不能直接阻塞 `MyRecvCallback`。

应通过 goroutine + 队列处理。

## 19. 建议的默认上线策略

第一版建议：

- 先只开启私聊自动回复。
- 群聊只开 @ 机器人触发。
- 最低知识库分数先设置偏高，例如 `0.4`。
- AI 无答案严格转人工。
- 所有转人工消息都附带原始 conversationId 和客户 ID。
- 开启详细日志，方便回放和排查。

## 20. 后续增强方向

后续可以继续增加：

- 多机器人分别配置知识库。
- 不同群使用不同知识库。
- 客户画像和历史上下文。
- 工单系统对接。
- 向量检索。
- 对话记忆。
- 人工接管后暂停自动回复。
- 黑名单/白名单群配置。
- 敏感词和合规审核。
- 前端消息实时流展示。