docs(im): update IM integration doc with Slack, commands, queue and streaming sections
- add Slack WebSocket/Webhook setup guide - add slash-command system documentation - add QA queue and rate limiting section - add streaming output and file message handling details
This commit is contained in:
+335
-118
@@ -15,11 +15,16 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置
|
||||
- [数据模型](#数据模型)
|
||||
- [API 端点](#api-端点)
|
||||
- [核心概念](#核心概念)
|
||||
- [数据流](#数据流)
|
||||
- [消息处理流程](#消息处理流程)
|
||||
- [接口定义](#接口定义)
|
||||
- [平台适配器详解](#平台适配器详解)
|
||||
- [企业微信 (WeCom)](#企业微信-wecom)
|
||||
- [飞书 (Feishu)](#飞书-feishu)
|
||||
- [Slack](#slack)
|
||||
- [斜杠指令系统](#斜杠指令系统)
|
||||
- [QA 队列与限流](#qa-队列与限流)
|
||||
- [流式输出机制](#流式输出机制)
|
||||
- [文件消息处理](#文件消息处理)
|
||||
- [关键参数与阈值](#关键参数与阈值)
|
||||
- [错误处理](#错误处理)
|
||||
- [扩展新平台](#扩展新平台)
|
||||
@@ -135,6 +140,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置
|
||||
|
||||
1. **添加应用能力**:在应用详情页 → **添加应用能力** → 添加 **机器人** 能力
|
||||
2. **配置权限**:在 **权限管理** 中搜索并开通以下权限:你的应用 → 权限管理 → 批量导入,粘贴下面 JSON(原文内容不变):
|
||||
```json
|
||||
{
|
||||
"scopes": {
|
||||
"tenant": [
|
||||
@@ -168,6 +174,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
3. **配置事件订阅**:
|
||||
- 在 **事件与回调** → **事件配置** 中,选择请求方式为 **使用长连接接收事件**
|
||||
- 添加事件 `im.message.receive_v1`(接收消息)
|
||||
@@ -321,20 +328,6 @@ Slack 提供两种接入模式,推荐使用 WebSocket (Socket Mode) 模式,
|
||||
|
||||
---
|
||||
|
||||
### 模式选择指南
|
||||
|
||||
| | Webhook | WebSocket |
|
||||
|---|---------|-----------|
|
||||
| 网络要求 | 需要公网可达的 HTTPS 回调地址 | 仅需出站网络,无需公网 |
|
||||
| 适用场景 | 已有域名和证书、自建应用 | 快速部署、内网环境、PoC 验证 |
|
||||
| 连接管理 | 无状态,平台推送 | 自动维护长连接、心跳、断线重连 |
|
||||
| 配置复杂度 | 需要配置回调 URL、加密密钥 | 只需 App ID/Secret |
|
||||
| 流式输出 | 支持 | 支持 |
|
||||
|
||||
> **建议:** 优先使用 WebSocket 模式,部署更简单,不依赖公网域名。
|
||||
|
||||
---
|
||||
|
||||
## 前端管理
|
||||
|
||||
IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模式可见,创建 Agent 时不显示)。
|
||||
@@ -342,7 +335,7 @@ IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模
|
||||
### 渠道列表
|
||||
|
||||
每个渠道以卡片形式展示,包含:
|
||||
- **平台标识**:企业微信(绿色)/ 飞书(蓝色)
|
||||
- **平台标识**:企业微信(绿色)/ 飞书(蓝色)/ Slack(紫色)
|
||||
- **渠道名称**:用户自定义
|
||||
- **接入模式**:WebSocket / Webhook
|
||||
- **输出模式**:流式输出 / 完整输出
|
||||
@@ -362,40 +355,44 @@ IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模
|
||||
## 架构总览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ IM 集成架构 │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 企业微信 │ │ 飞书 │ IM 平台层 │
|
||||
│ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ Webhook/WS │ Webhook/WS │
|
||||
│ ─────┼───────────────┼────────────────────────────────────────────── │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ WeCom │ │ Feishu │ 平台适配器层 (im.Adapter) │
|
||||
│ │ Adapter │ │ Adapter │ · 消息解密、解析 │
|
||||
│ └────┬─────┘ └────┬─────┘ · 签名验证 │
|
||||
│ │ │ · 回复发送、流式推送 │
|
||||
│ ─────┼───────────────┼────────────────────────────────────────────── │
|
||||
│ └───────┬───────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────┐ │
|
||||
│ │ im.Service │ 服务编排层 │
|
||||
│ │ │ · IM 渠道管理 (CRUD) │
|
||||
│ │ ┌───────────────┐ │ · Adapter Factory (动态创建) │
|
||||
│ │ │ im_channels │ │ · 消息去重 (MessageID + TTL) │
|
||||
│ │ │ (DB表) │ │ · 会话映射 (ChannelSession) │
|
||||
│ │ └───────────────┘ │ · 流式/全量路由 │
|
||||
│ └──────────┬──────────┘ · QA 管道调度 │
|
||||
│ │ │
|
||||
│ ───────────┼────────────────────────────────────────────────────── │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ WeKnora Core (QA Pipeline) │ 核心层 │
|
||||
│ │ SessionService · MessageService │ │
|
||||
│ │ TenantService · AgentService │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
┌──────────────────────────────────────────────────────────────────────────────┐
|
||||
│ IM 集成架构 │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 企业微信 │ │ 飞书 │ │ Slack │ IM 平台层 │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ Webhook/WS │ Webhook/WS │ Webhook/WS │
|
||||
│ ─────┼───────────────┼───────────────┼────────────────────────────────── │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ WeCom │ │ Feishu │ │ Slack │ 平台适配器层 (im.Adapter) │
|
||||
│ │ Adapter │ │ Adapter │ │ Adapter │ · 消息解密、解析 │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ · 签名验证 │
|
||||
│ │ │ │ · 回复发送、流式推送 │
|
||||
│ ─────┼───────────────┼───────────────┼────────────────────────────────── │
|
||||
│ └───────────────┼───────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ im.Service │ 服务编排层 │
|
||||
│ │ │ · IM 渠道管理 (CRUD) │
|
||||
│ │ ┌────────────────────────────┐ │ · Adapter Factory (动态创建) │
|
||||
│ │ │ CommandRegistry │ │ · 斜杠指令分发 │
|
||||
│ │ │ qaQueue (Worker Pool) │ │ · QA 队列调度 (有界, 异步) │
|
||||
│ │ │ rateLimiter (滑动窗口) │ │ · 滑动窗口限流 │
|
||||
│ │ │ processedMsgs (去重) │ │ · 消息去重 (MessageID + TTL) │
|
||||
│ │ │ inflight (取消跟踪) │ │ · 会话映射 (ChannelSession) │
|
||||
│ │ └────────────────────────────┘ │ · 流式/全量路由 │
|
||||
│ └──────────────┬───────────────────┘ │
|
||||
│ │ │
|
||||
│ ───────────────┼─────────────────────────────────────────────────────── │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ WeKnora Core (QA Pipeline) │ 核心层 │
|
||||
│ │ SessionService · MessageService │ │
|
||||
│ │ TenantService · AgentService │ │
|
||||
│ │ KnowledgeService (文件保存) │ │
|
||||
│ └──────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**设计模式:**
|
||||
@@ -404,7 +401,9 @@ IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模
|
||||
|------|------|
|
||||
| Adapter Pattern | 统一不同 IM 平台的差异,每个平台实现 `im.Adapter` 接口 |
|
||||
| Factory Pattern | 通过 `AdapterFactory` 从数据库渠道配置动态创建 Adapter 实例 |
|
||||
| Strategy Pattern | `StreamSender` 可选接口,让平台按需支持流式输出 |
|
||||
| Strategy Pattern | `StreamSender`、`FileDownloader` 可选接口,按需实现 |
|
||||
| Command Pattern | `Command` 接口 + `CommandRegistry` 实现可插拔的斜杠指令系统 |
|
||||
| Producer-Consumer | `qaQueue` 有界队列 + Worker Pool,解耦消息接收与 QA 执行 |
|
||||
| Event-Driven | 通过 `EventBus` 解耦 QA 管道与 IM 输出,支持实时块推送 |
|
||||
|
||||
---
|
||||
@@ -417,18 +416,20 @@ IM 渠道配置存储在 `im_channels` 表中,绑定到 Agent:
|
||||
|
||||
```sql
|
||||
CREATE TABLE im_channels (
|
||||
id VARCHAR(36) PRIMARY KEY,
|
||||
tenant_id BIGINT NOT NULL,
|
||||
agent_id VARCHAR(36) NOT NULL, -- 绑定的 Agent ID
|
||||
platform VARCHAR(20) NOT NULL, -- 'wecom' | 'feishu'
|
||||
name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
enabled BOOLEAN NOT NULL DEFAULT true,
|
||||
mode VARCHAR(20) NOT NULL DEFAULT 'websocket', -- 'webhook' | 'websocket'
|
||||
output_mode VARCHAR(20) NOT NULL DEFAULT 'stream', -- 'stream' | 'full'
|
||||
credentials JSONB NOT NULL DEFAULT '{}', -- 平台凭证
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
deleted_at TIMESTAMPTZ
|
||||
id VARCHAR(36) PRIMARY KEY,
|
||||
tenant_id BIGINT NOT NULL,
|
||||
agent_id VARCHAR(36) NOT NULL, -- 绑定的 Agent ID
|
||||
platform VARCHAR(20) NOT NULL, -- 'wecom' | 'feishu' | 'slack'
|
||||
name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
enabled BOOLEAN NOT NULL DEFAULT true,
|
||||
mode VARCHAR(20) NOT NULL DEFAULT 'websocket', -- 'webhook' | 'websocket'
|
||||
output_mode VARCHAR(20) NOT NULL DEFAULT 'stream', -- 'stream' | 'full'
|
||||
knowledge_base_id VARCHAR(36), -- 可选,绑定知识库以接收文件消息
|
||||
bot_identity VARCHAR(255), -- 计算字段,防止重复机器人
|
||||
credentials JSONB NOT NULL DEFAULT '{}', -- 平台凭证
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
deleted_at TIMESTAMPTZ
|
||||
);
|
||||
```
|
||||
|
||||
@@ -451,6 +452,8 @@ CREATE TABLE im_channels (
|
||||
(im_channel_id, Platform, UserID, ChatID, TenantID) → SessionID
|
||||
```
|
||||
|
||||
首次交互自动创建,后续消息复用同一会话。`/clear` 指令会软删除会话记录,下次消息重新创建。
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
@@ -471,7 +474,7 @@ CREATE TABLE im_channels (
|
||||
|------|------|------|
|
||||
| GET/POST | `/api/v1/im/callback/:channel_id` | 通用回调(根据 channel_id 自动路由到对应 Adapter) |
|
||||
|
||||
> Webhook 模式下,每个渠道有唯一的回调地址 `/api/v1/im/callback/{channel_id}`,在前端渠道卡片上可一键复制。
|
||||
> Webhook 模式下,每个渠道有唯一的回调地址 `/api/v1/im/callback/{channel_id}`,在前端渠道卡片上可一键复制。回调路由注册在认证中间件**之前**,由平台签名验证保护。
|
||||
|
||||
---
|
||||
|
||||
@@ -479,7 +482,9 @@ CREATE TABLE im_channels (
|
||||
|
||||
### IMChannel — IM 渠道
|
||||
|
||||
每个 IM 渠道代表一个 IM 平台机器人与 WeKnora Agent 的绑定关系。一个 Agent 可以绑定多个渠道(如同时接入企业微信和飞书),同一平台也可以创建多个渠道(如不同的企业微信机器人)。
|
||||
每个 IM 渠道代表一个 IM 平台机器人与 WeKnora Agent 的绑定关系。一个 Agent 可以绑定多个渠道(如同时接入企业微信、飞书和 Slack),同一平台也可以创建多个渠道(如不同的企业微信机器人)。
|
||||
|
||||
渠道有一个计算字段 `BotIdentity`,由平台类型、模式和核心凭证推导,用于防止同一机器人被重复创建。
|
||||
|
||||
渠道启动时,Service 通过 `AdapterFactory` 根据平台类型和凭证动态创建对应的 Adapter 实例。
|
||||
|
||||
@@ -489,14 +494,18 @@ CREATE TABLE im_channels (
|
||||
|
||||
```go
|
||||
type IncomingMessage struct {
|
||||
Platform Platform // "wecom" | "feishu"
|
||||
UserID string // 平台用户标识
|
||||
UserName string // 显示名 (可选)
|
||||
ChatID string // 群聊 ID (私聊为空)
|
||||
ChatType ChatType // "direct" | "group"
|
||||
Content string // 纯文本内容
|
||||
MessageID string // 平台消息 ID (用于去重)
|
||||
Extra map[string]string // 平台特有字段
|
||||
Platform Platform // "wecom" | "feishu" | "slack"
|
||||
MessageType MessageType // "text" | "file" | "image"
|
||||
UserID string // 平台用户标识
|
||||
UserName string // 显示名 (可选)
|
||||
ChatID string // 群聊 ID (私聊为空)
|
||||
ChatType ChatType // "direct" | "group"
|
||||
Content string // 纯文本内容
|
||||
MessageID string // 平台消息 ID (用于去重)
|
||||
FileKey string // 文件标识 (文件/图片消息)
|
||||
FileName string // 文件名 (文件/图片消息)
|
||||
FileSize int64 // 文件大小 (字节)
|
||||
Extra map[string]string // 平台特有字段 (如 req_id、aes_key)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -513,11 +522,11 @@ type ReplyMessage struct {
|
||||
|
||||
### ChannelSession — 会话映射
|
||||
|
||||
将 IM 渠道 (渠道 ID + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性。首次交互自动创建,后续消息复用同一会话。存储于 `im_channel_sessions` 表。
|
||||
将 IM 渠道 (渠道 ID + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性。首次交互自动创建,后续消息复用同一会话。并发创建通过唯一约束 + fallback 查询处理。存储于 `im_channel_sessions` 表。
|
||||
|
||||
---
|
||||
|
||||
## 数据流
|
||||
## 消息处理流程
|
||||
|
||||
### 完整消息处理流程
|
||||
|
||||
@@ -525,7 +534,7 @@ type ReplyMessage struct {
|
||||
用户在 IM 中发送消息
|
||||
│
|
||||
▼
|
||||
┌─ HTTP Handler ──────────────────────────────────┐
|
||||
┌─ HTTP Handler / WebSocket 回调 ─────────────────┐
|
||||
│ 1. 根据 channel_id 查找渠道配置 │
|
||||
│ 2. 获取对应 Adapter │
|
||||
│ 3. 签名验证 (VerifyCallback) │
|
||||
@@ -535,14 +544,22 @@ type ReplyMessage struct {
|
||||
└──────────────────────────┬──────────────────────-┘
|
||||
│ goroutine
|
||||
▼
|
||||
┌─ im.Service ────────────────────────────────────┐
|
||||
┌─ im.Service.HandleMessage ──────────────────────┐
|
||||
│ 1. 去重检查 (MessageID, 5 分钟 TTL) │
|
||||
│ 2. 内容长度校验 (≤ 4096 字符) │
|
||||
│ 3. 从渠道配置获取 agent_id、tenant_id │
|
||||
│ 4. 解析/创建 ChannelSession │
|
||||
│ 5. 获取 WeKnora Session │
|
||||
│ 6. 加载 Agent 配置(获取知识库等信息) │
|
||||
│ 7. 判断流式/全量模式 │
|
||||
│ 2. 内容长度校验 (≤ 4096 rune,超出截断) │
|
||||
│ 3. 斜杠指令检测 → 命中则分发到 CommandRegistry │
|
||||
│ 4. 限流检查 (滑动窗口, 10次/60s) │
|
||||
│ 5. 从渠道配置获取 agent_id、tenant_id │
|
||||
│ 6. 解析/创建 ChannelSession │
|
||||
│ 7. 获取 WeKnora Session │
|
||||
│ 8. 加载 Agent 配置(获取知识库、模型等信息) │
|
||||
│ 9. 文件消息?→ 下载并保存到知识库 │
|
||||
│ 10. 提交到 qaQueue (有界队列, 异步执行) │
|
||||
└───────────┬─────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─ qaQueue Worker ────────────────────────────────┐
|
||||
│ 从队列取出请求,记录 inflight,判断流式/全量模式 │
|
||||
└───────────┬─────────────────────┬───────────────┘
|
||||
│ │
|
||||
流式模式 ▼ 全量模式 ▼
|
||||
@@ -552,6 +569,7 @@ type ReplyMessage struct {
|
||||
│ · StartStream │ └─────────────────────┘
|
||||
│ · EventBus 订阅 │
|
||||
│ · 300ms 批量刷新 │
|
||||
│ · 工具事件展示 │
|
||||
│ · SendStreamChunk │
|
||||
│ · EndStream │
|
||||
└────────────────────┘
|
||||
@@ -583,26 +601,6 @@ type ReplyMessage struct {
|
||||
StopChannel() → 取消 Adapter 上下文 → 从 map 移除
|
||||
```
|
||||
|
||||
### 流式输出机制
|
||||
|
||||
流式模式通过 `EventBus` 实时收集 QA 管道产生的内容块,以 **300ms 间隔批量推送**,在延迟与 API 限频之间取得平衡:
|
||||
|
||||
```
|
||||
QA 管道 ──chunk──chunk──chunk──▶ EventBus
|
||||
│
|
||||
每 300ms 刷新
|
||||
│
|
||||
┌───────────▼───────────┐
|
||||
│ 累积内容 → 完整替换推送 │
|
||||
│ (非增量,每次发送全文) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
**关键细节:**
|
||||
- `<think>...</think>` 块在流式输出中被过滤,不展示给用户
|
||||
- 流式初始化失败时自动降级到全量模式 (`fallbackNonStream`)
|
||||
- 完整内容(含 thinking)持久化到数据库,确保历史完整
|
||||
|
||||
---
|
||||
|
||||
## 接口定义
|
||||
@@ -627,7 +625,7 @@ type Adapter interface {
|
||||
| `SendReply()` | 通过平台 API 发送完整回复 |
|
||||
| `HandleURLVerification()` | 处理平台初始 URL 验证(首次配置时调用) |
|
||||
|
||||
### im.StreamSender — 流式推送 (可选实现)
|
||||
### im.StreamSender — 流式推送 (可选)
|
||||
|
||||
```go
|
||||
type StreamSender interface {
|
||||
@@ -639,6 +637,16 @@ type StreamSender interface {
|
||||
|
||||
实现此接口后,Service 会自动路由到流式模式。渠道配置 `output_mode: "full"` 可强制关闭。
|
||||
|
||||
### im.FileDownloader — 文件下载 (可选)
|
||||
|
||||
```go
|
||||
type FileDownloader interface {
|
||||
DownloadFile(ctx context.Context, msg *IncomingMessage) (io.ReadCloser, string, error)
|
||||
}
|
||||
```
|
||||
|
||||
实现此接口后,当用户发送文件/图片消息且渠道配置了 `knowledge_base_id` 时,Service 会自动下载文件并保存到指定知识库。
|
||||
|
||||
### im.AdapterFactory — 适配器工厂
|
||||
|
||||
```go
|
||||
@@ -662,15 +670,17 @@ type AdapterFactory func(ctx context.Context, channel *IMChannel, msgHandler fun
|
||||
```
|
||||
企业微信服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id}
|
||||
│
|
||||
解密 (AES-128-CBC)
|
||||
解密 (AES-256-CBC)
|
||||
解析 XML → IncomingMessage
|
||||
│
|
||||
处理完成后调用 WeCom REST API 回复
|
||||
```
|
||||
|
||||
- **加密方案:** AES-128-CBC,Key 由 `encoding_aes_key` Base64 解码得到,IV 为 Key 前 16 字节
|
||||
- **加密方案:** AES-256-CBC,Key 由 `encoding_aes_key` Base64 解码得到(32 字节),IV 为 Key 前 16 字节
|
||||
- **消息格式:** `random(16) + msg_len(4) + message + corp_id`,PKCS#7 填充
|
||||
- **签名验证:** SHA-1(`sort([token, timestamp, nonce, encrypt])`),常量时间比较
|
||||
- **消息类型:** 支持 `text`(文本)和 `image`(图片,PicUrl 直接下载或 MediaId 临时素材 API)
|
||||
- **群聊回复:** 优先尝试 `appchat/send` 群聊 API,失败时降级到私聊直发
|
||||
- **回复方式:** 通过 `/cgi-bin/message/send` 接口发送 Markdown 消息
|
||||
|
||||
#### WebSocket 模式 (`WSAdapter` + `LongConnClient`)
|
||||
@@ -688,22 +698,24 @@ LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com
|
||||
```
|
||||
|
||||
- **认证:** Bot ID + Bot Secret
|
||||
- **流式回复:** 通过 WebSocket 帧发送,`finish=true` 标记结束
|
||||
- **容错:** 指数退避重连,无限重试
|
||||
- **消息类型:** `text`(文本)、`image`(图片)、`file`(文件)、`voice`(语音,服务端已转文本)、`mixed`(混合,文本 + 图片)、`event`(服务器事件)
|
||||
- **文件解密:** 附件使用每消息独立 AES-256-CBC 密钥解密(IV 为密钥前 16 字节)
|
||||
- **流式回复:** 通过 WebSocket 帧发送累积全文,`finish=true` 标记结束
|
||||
- **容错:** 指数退避重连(基础 1s,上限 30s),读超时 = 3 × 心跳间隔(90s)
|
||||
|
||||
#### 源码文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `internal/im/wecom/webhook_adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、Token 缓存 |
|
||||
| `internal/im/wecom/webhook_adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、群聊发送、Token 缓存、文件下载 |
|
||||
| `internal/im/wecom/ws_adapter.go` | WebSocket 模式适配器壳,代理到 `LongConnClient` |
|
||||
| `internal/im/wecom/longconn.go` | WebSocket 客户端:连接管理、心跳、帧协议、自动重连 |
|
||||
| `internal/im/wecom/longconn.go` | WebSocket 客户端:连接管理、心跳、帧协议、自动重连、多消息类型解析、文件解密 |
|
||||
|
||||
---
|
||||
|
||||
### 飞书 (Feishu)
|
||||
|
||||
统一适配器同时支持 Webhook 和 WebSocket 模式,且原生实现 `StreamSender` 接口。
|
||||
统一适配器同时支持 Webhook 和 WebSocket 模式,且原生实现 `StreamSender` 和 `FileDownloader` 接口。
|
||||
|
||||
#### Webhook 模式
|
||||
|
||||
@@ -718,6 +730,7 @@ LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com
|
||||
|
||||
- **加密方案:** AES-256-CBC,Key 为 `SHA-256(encrypt_key)`,IV 为密文前 16 字节
|
||||
- **事件过滤:** 仅处理 `im.message.receive_v1` 事件,忽略其他事件类型
|
||||
- **消息类型:** `text`(文本)、`file`(文件)、`image`(图片)、`post`(富文本,提取标题 + 结构化内容)
|
||||
- **群消息处理:** 自动去除 `@_user_xxx` 提及前缀
|
||||
|
||||
#### WebSocket 模式
|
||||
@@ -742,12 +755,22 @@ EndStream:
|
||||
|
||||
每次 `SendStreamChunk` 发送的是**累积全文**而非增量,由 `feishuStreamState` 跟踪完整内容和严格递增的 `sequence` 序号。
|
||||
|
||||
**Think 块处理:** 流式输出中的 `<think>...</think>` 块会被转换为飞书 Markdown 引用块格式:
|
||||
|
||||
```
|
||||
> 💭 **思考过程**
|
||||
> [thinking content line 1]
|
||||
> [thinking content line 2]
|
||||
```
|
||||
|
||||
**孤立流清理:** 后台协程每 1 分钟扫描超过 5 分钟未关闭的流式卡片,自动调用 `EndStream` 关闭(防止内存泄漏)。
|
||||
|
||||
#### 源码文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `internal/im/feishu/adapter.go` | 事件解析、CardKit 流式实现、Token 缓存、AES 解密 |
|
||||
| `internal/im/feishu/longconn.go` | WebSocket 长连接(封装飞书 SDK) |
|
||||
| `internal/im/feishu/adapter.go` | 事件解析、CardKit 流式实现、Token 缓存、AES 解密、Think 块转换、文件下载 |
|
||||
| `internal/im/feishu/longconn.go` | WebSocket 长连接(封装飞书 SDK)、事件分发 |
|
||||
|
||||
---
|
||||
|
||||
@@ -809,6 +832,181 @@ EndStream:
|
||||
|
||||
---
|
||||
|
||||
## 斜杠指令系统
|
||||
|
||||
IM 渠道支持斜杠指令(Slash Commands),用户在聊天中输入 `/指令名` 即可触发,无需经过 QA 管道,且不受限流约束。
|
||||
|
||||
### 内置指令
|
||||
|
||||
| 指令 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `/help` | `[指令名]` | 显示所有可用指令列表;带参数时显示指定指令的详细用法 |
|
||||
| `/info` | — | 查看当前绑定智能体的名称、角色设定、知识库列表等信息 |
|
||||
| `/search` | `<关键词>` | 对绑定的知识库执行混合检索(向量 + 关键词),返回最多 5 条原文片段,不经过 AI 总结 |
|
||||
| `/stop` | — | 取消当前排队中或正在执行的 QA 请求 |
|
||||
| `/clear` | — | 清空当前对话记忆(软删除 ChannelSession),下次消息开始全新会话 |
|
||||
|
||||
### 指令分发流程
|
||||
|
||||
```
|
||||
用户消息 ──▶ HandleMessage
|
||||
│
|
||||
├─ 以 "/" 开头?
|
||||
│ │
|
||||
│ ├─ 已注册指令 → CommandRegistry.Parse → Command.Execute → 回复结果
|
||||
│ │ │
|
||||
│ │ ActionClear → 软删除 ChannelSession
|
||||
│ │ ActionStop → 取消排队/执行中的 QA
|
||||
│ │
|
||||
│ └─ LooksLikeCommand() = true 但未注册
|
||||
│ → 回复 "未知指令,发送 /help 查看"
|
||||
│ LooksLikeCommand() = false (如 "/api/v2/users")
|
||||
│ → 当作普通消息,进入 QA 管道
|
||||
│
|
||||
└─ 普通消息 → 限流检查 → qaQueue → QA 管道
|
||||
```
|
||||
|
||||
> `LooksLikeCommand()` 通过检查首 token 是否含有 `/` 分隔符来区分指令尝试和 URL 路径,避免误拦截。
|
||||
|
||||
### 扩展自定义指令
|
||||
|
||||
实现 `im.Command` 接口并在 Service 初始化时注册到 `CommandRegistry`:
|
||||
|
||||
```go
|
||||
type Command interface {
|
||||
Name() string // 指令名 (不含 "/")
|
||||
Description() string // 一行描述,用于 /help 输出
|
||||
Execute(ctx context.Context, cmdCtx *CommandContext, args []string) (*CommandResult, error)
|
||||
}
|
||||
```
|
||||
|
||||
**设计约定:**
|
||||
- 依赖(DB、Service)通过构造函数注入,不放在 `CommandContext` 中
|
||||
- 用户输入错误通过 `CommandResult` 返回友好提示,`error` 仅用于基础设施故障(DB 异常、网络错误等)
|
||||
- 通过 `CommandResult.Action` 声明副作用意图(如清空会话),由 Service 执行
|
||||
- 重复注册同名指令会在启动时 panic,确保配置错误尽早暴露
|
||||
|
||||
### 源码文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `internal/im/command.go` | Command 接口、CommandAction、CommandContext 定义 |
|
||||
| `internal/im/command_registry.go` | CommandRegistry:指令注册、解析、分发、LooksLikeCommand |
|
||||
| `internal/im/cmd_help.go` | `/help` 指令实现 |
|
||||
| `internal/im/cmd_info.go` | `/info` 指令实现(展示 Agent 信息、知识库列表) |
|
||||
| `internal/im/cmd_search.go` | `/search` 指令实现(混合检索,最多 5 条,内容截断 200 rune) |
|
||||
| `internal/im/cmd_stop.go` | `/stop` 指令实现 |
|
||||
| `internal/im/cmd_clear.go` | `/clear` 指令实现 |
|
||||
|
||||
---
|
||||
|
||||
## QA 队列与限流
|
||||
|
||||
### QA 队列 (qaQueue)
|
||||
|
||||
有界工作池队列管理 QA 请求,防止并发过载:
|
||||
|
||||
```
|
||||
消息 ──▶ Enqueue ──▶ [ 等待队列 (≤50) ] ──▶ Worker Pool (5 workers) ──▶ QA 管道
|
||||
│ │
|
||||
├─ 队列已满 → 拒绝并回复提示 │
|
||||
├─ 用户排队超限 (≤3) → 拒绝 ├─ 等待超时 (>60s) → 丢弃并通知
|
||||
└─ /stop → Remove(userKey) 取消 └─ 正常执行 QA
|
||||
```
|
||||
|
||||
**设计要点:**
|
||||
|
||||
- **有界队列**:最大容量 50,防止内存无限增长
|
||||
- **Per-User 背压**:单用户最多同时排队 3 个请求,避免单用户刷屏占满队列
|
||||
- **排队等待提示**:入队成功且队列非空时,回复 "前面还有 N 条消息在处理,请稍候"
|
||||
- **排队超时**:请求在队列中等待超过 60 秒自动丢弃,回复超时提示
|
||||
- **可取消**:`/stop` 指令通过 `qaQueue.Remove(userKey)` 取消排队请求,通过 `inflight` map 中的 `context.CancelFunc` 取消执行中请求
|
||||
- **指标监控**:每 30 秒输出队列深度、活跃 Worker 数、入队/处理/拒绝/超时计数(仅在有活动时输出)
|
||||
|
||||
### 滑动窗口限流 (rateLimiter)
|
||||
|
||||
在消息进入 QA 队列之前,按 `channelID:userID:chatID` 维度进行滑动窗口限流:
|
||||
|
||||
| 参数 | 值 | 说明 |
|
||||
|------|------|------|
|
||||
| 窗口大小 | 60s | 滑动时间窗口 |
|
||||
| 最大请求数 | 10 次/窗口 | 每个用户每分钟最多 10 条消息进入 QA |
|
||||
| 清理周期 | 1 min | 自动清理过期条目,防止内存泄漏 |
|
||||
|
||||
超出限流时回复提示消息,不计入队列。斜杠指令不受限流约束。
|
||||
|
||||
### 源码文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `internal/im/qaqueue.go` | qaQueue:有界队列、Worker Pool、QueueMetrics、指标上报 |
|
||||
| `internal/im/ratelimit.go` | slidingWindowLimiter:per-key 滑动窗口限流、并发安全清理 |
|
||||
|
||||
---
|
||||
|
||||
## 流式输出机制
|
||||
|
||||
流式模式通过 `EventBus` 实时收集 QA 管道产生的内容块,以 **300ms 间隔批量推送**,在延迟与 API 限频之间取得平衡:
|
||||
|
||||
```
|
||||
QA 管道 ──chunk──chunk──chunk──▶ EventBus
|
||||
│
|
||||
每 300ms 刷新
|
||||
│
|
||||
┌───────────▼───────────┐
|
||||
│ 累积内容 → 完整替换推送 │
|
||||
│ (非增量,每次发送全文) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
### 内容处理
|
||||
|
||||
- **Think 块过滤/转换**:`<think>...</think>` 块在飞书中转换为引用块展示,在其他平台中过滤
|
||||
- **工具事件展示**:Agent 工具调用实时展示调用状态
|
||||
- 调用中:`⏳ [工具名]`(包裹在 think 块内)
|
||||
- 调用成功:`✅ [工具名] · [摘要]`
|
||||
- 调用失败:`⚠️ [工具名] 失败`
|
||||
- 内部工具(thinking、todo_write 等)不展示给用户
|
||||
- **空内容回退**:流式过程中无可见内容产生时,回退到完整回复模式 (`fallbackNonStream`)
|
||||
- **完整持久化**:完整内容(含 thinking)持久化到数据库,确保历史完整
|
||||
|
||||
### 飞书流式特殊处理
|
||||
|
||||
- **"正在思考..." 占位**:流式初始化后立即显示占位文本,提升用户感知
|
||||
- **孤立流清理**:后台协程每 `streamReaperInterval`(1 分钟)扫描超过 `streamOrphanTTL`(5 分钟)未关闭的流,自动关闭防止内存泄漏
|
||||
- **Think 块转换**:将 `<think>` 标签转换为飞书 Markdown 引用块(`> 💭 **思考过程**`)
|
||||
|
||||
---
|
||||
|
||||
## 文件消息处理
|
||||
|
||||
当用户在 IM 中发送文件或图片消息时,如果渠道配置了 `knowledge_base_id`,Service 会自动将文件保存到对应知识库:
|
||||
|
||||
```
|
||||
用户发送文件/图片消息
|
||||
│
|
||||
▼
|
||||
消息类型 = file/image?
|
||||
渠道配置了 knowledge_base_id?
|
||||
Adapter 实现了 FileDownloader?
|
||||
│ 全部满足
|
||||
▼
|
||||
1. adapter.DownloadFile(msg) → io.ReadCloser + fileName
|
||||
2. 通知用户 "正在处理文件..."
|
||||
3. knowledgeService.Save(file, knowledgeBaseID)
|
||||
4. 通知用户 "文件已保存到知识库"
|
||||
```
|
||||
|
||||
**各平台文件下载方式:**
|
||||
|
||||
| 平台 | 方式 |
|
||||
|------|------|
|
||||
| 飞书 | GetMessageResource API(通过 FileKey) |
|
||||
| 企业微信 Webhook | PicUrl 直接下载 或 MediaId 临时素材 API |
|
||||
| 企业微信 WebSocket | 加密附件 URL + per-message AES 密钥解密 |
|
||||
|
||||
---
|
||||
|
||||
## 关键参数与阈值
|
||||
|
||||
| 参数 | 值 | 说明 |
|
||||
@@ -818,8 +1016,18 @@ EndStream:
|
||||
| `dedupCleanupInterval` | 1 min | 去重清理周期 |
|
||||
| `maxContentLength` | 4096 | 消息最大长度 (rune),超出截断 |
|
||||
| `streamFlushInterval` | 300ms | 流式内容批量刷新间隔 |
|
||||
| WeCom 心跳 | 30s | WebSocket 保活频率 |
|
||||
| WeCom 重连退避 | 1s → 30s | 指数退避,上限 30 秒 |
|
||||
| `defaultMaxQueueSize` | 50 | QA 队列最大容量 |
|
||||
| `defaultMaxPerUser` | 3 | 单用户最大排队请求数 |
|
||||
| `defaultWorkers` | 5 | QA 并发 Worker 数 |
|
||||
| `queueTimeout` | 60s | 请求在队列中的最大等待时间 |
|
||||
| `rateLimitWindow` | 60s | 限流滑动窗口大小 |
|
||||
| `rateLimitMaxRequests` | 10 | 每用户每窗口最大请求数 |
|
||||
| `metricsLogInterval` | 30s | 队列指标日志上报周期 |
|
||||
| `streamOrphanTTL` | 5 min | 飞书孤立流超时时间 |
|
||||
| `streamReaperInterval` | 1 min | 飞书孤立流清理扫描周期 |
|
||||
| WeCom WS 心跳 | 30s | WebSocket 保活频率 |
|
||||
| WeCom WS 读超时 | 90s | 3 × 心跳间隔,允许一次心跳丢失 |
|
||||
| WeCom WS 重连退避 | 1s → 30s | 指数退避,上限 30 秒 |
|
||||
| Token 缓存安全余量 | 5 min | Token 过期前提前刷新 |
|
||||
|
||||
---
|
||||
@@ -828,13 +1036,20 @@ EndStream:
|
||||
|
||||
| 场景 | 处理策略 |
|
||||
|------|---------|
|
||||
| 流式初始化失败 | 自动降级到全量模式 |
|
||||
| 流式初始化失败 | 自动降级到全量模式 (`fallbackNonStream`) |
|
||||
| QA 管道异常 | 回复 "抱歉,处理您的问题时出现了异常,请稍后再试。" |
|
||||
| QA 超时 (>120s) | 标记消息完成,回复超时提示 |
|
||||
| 空回答 | 回复 "抱歉,我暂时无法回答这个问题。" |
|
||||
| 空流式内容 | 无可见内容时回退到完整回复 |
|
||||
| WebSocket 断连 | 指数退避自动重连 |
|
||||
| 平台重试 | MessageID 去重,5 分钟内自动跳过 |
|
||||
| 渠道启动失败 | 日志记录错误,不影响其他渠道 |
|
||||
| QA 队列已满 | 拒绝请求并回复 "当前排队人数较多,请稍后再试。" |
|
||||
| 用户排队超限 | 拒绝请求并回复提示(单用户 ≤3) |
|
||||
| 排队等待超时 | 超过 60s 自动丢弃,回复 "您的消息等待超时,请重新发送。" |
|
||||
| 消息限流 | 滑动窗口内超过 10 次,回复限流提示 |
|
||||
| 飞书孤立流 | 每分钟扫描,超过 5 分钟未关闭的自动结束 |
|
||||
| 企业微信群聊回复失败 | appchat API 失败时降级到用户私聊 |
|
||||
|
||||
---
|
||||
|
||||
@@ -858,7 +1073,9 @@ func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, r
|
||||
func (a *Adapter) HandleURLVerification(c *gin.Context) bool { /* URL 验证 */ }
|
||||
```
|
||||
|
||||
如需流式输出,额外实现 `im.StreamSender`。
|
||||
可选接口:
|
||||
- 实现 `im.StreamSender` 以支持流式输出
|
||||
- 实现 `im.FileDownloader` 以支持文件消息自动保存到知识库
|
||||
|
||||
### 2. 注册适配器工厂
|
||||
|
||||
@@ -891,4 +1108,4 @@ imService.RegisterAdapterFactory("dingtalk", func(ctx context.Context, channel *
|
||||
|
||||
在 i18n 文件中添加平台名称翻译。
|
||||
|
||||
Service 层 (`im.Service`) 不需要任何修改 — 渠道管理、消息编排、会话管理、QA 调度、流式控制全部由 Service 统一处理。
|
||||
Service 层 (`im.Service`) 不需要任何修改 — 渠道管理、指令分发、消息编排、会话管理、QA 调度、限流、流式控制全部由 Service 统一处理。
|
||||
|
||||
Reference in New Issue
Block a user