feat: implement IM channel management in agent editor
- Introduced a new IMChannelPanel component for managing WeCom and Feishu channels. - Added CRUD operations for IM channels, including create, update, delete, and list functionalities. - Enhanced the backend with new API endpoints for IM channel management. - Updated documentation to reflect changes in IM integration and channel management. - Improved localization support for new IM-related UI elements across multiple languages.
This commit is contained in:
+241
-167
@@ -2,13 +2,17 @@
|
||||
|
||||
WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
|
||||
|
||||
IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置通过前端 Agent 编辑器管理,存储在数据库中。
|
||||
|
||||
## 目录
|
||||
|
||||
- [快速接入指南](#快速接入指南)
|
||||
- [企业微信接入](#企业微信接入)
|
||||
- [飞书接入](#飞书接入)
|
||||
- [配置参考](#配置参考)
|
||||
- [前端管理](#前端管理)
|
||||
- [架构总览](#架构总览)
|
||||
- [数据模型](#数据模型)
|
||||
- [API 端点](#api-端点)
|
||||
- [核心概念](#核心概念)
|
||||
- [数据流](#数据流)
|
||||
- [接口定义](#接口定义)
|
||||
@@ -23,6 +27,12 @@ WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书
|
||||
|
||||
## 快速接入指南
|
||||
|
||||
### 前置条件
|
||||
|
||||
- WeKnora 已部署并运行
|
||||
- 已创建至少一个 Agent(自定义智能体)
|
||||
- Agent 已配置好模型和知识库
|
||||
|
||||
### 企业微信接入
|
||||
|
||||
企业微信提供两种接入模式,根据你的应用类型选择:
|
||||
@@ -33,30 +43,27 @@ WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书
|
||||
|
||||
**第一步:创建智能机器人**
|
||||
|
||||
1. 登录 [企业微信工作台](确认已升级到最新版企业微信) → **智能机器人** → **创建机器人** → **手动创建** → **切换API模式创建** → **选择“使用长连接”**
|
||||
1. 登录 [企业微信工作台](确认已升级到最新版企业微信) → **智能机器人** → **创建机器人** → **手动创建** → **切换API模式创建** → **选择"使用长连接"**
|
||||
2. 创建完成后,在机器人详情页获取:
|
||||
- **BotID** — 机器人唯一标识
|
||||
- **BotSecret** — 机器人密钥(点击重置可重新生成)
|
||||
|
||||
**第二步:配置 WeKnora**
|
||||
**第二步:在 WeKnora 中添加 IM 渠道**
|
||||
|
||||
编辑 `config/config.yaml`:
|
||||
1. 进入 Agent 编辑器 → 左侧导航选择 **IM 集成** 标签页
|
||||
2. 点击 **添加渠道**
|
||||
3. 填写配置:
|
||||
- **平台**:选择「企业微信」
|
||||
- **渠道名称**:自定义名称,方便辨识(如「客服机器人」)
|
||||
- **接入模式**:选择「WebSocket」
|
||||
- **输出模式**:选择「流式输出」(推荐)
|
||||
- **Bot ID**:填入从企业微信获取的 BotID
|
||||
- **Bot Secret**:填入从企业微信获取的 BotSecret
|
||||
4. 点击保存
|
||||
|
||||
```yaml
|
||||
im:
|
||||
wecom:
|
||||
enabled: true
|
||||
mode: "websocket" # 使用 WebSocket 长连接
|
||||
output_mode: "stream" # 流式输出(推荐)
|
||||
tenant_id: ["你的租户ID"] # WeKnora 租户 ID
|
||||
knowledge_base_ids: ["你的知识库ID"] # 关联的知识库
|
||||
bot_id: "${WECOM_BOT_ID}" # 机器人 ID
|
||||
bot_secret: "${WECOM_BOT_SECRET}" # 机器人 Secret
|
||||
```
|
||||
**第三步:验证**
|
||||
|
||||
**第三步:启动服务**
|
||||
|
||||
启动 WeKnora 后,程序会自动建立到企业微信的 WebSocket 长连接(`wss://openws.work.weixin.qq.com`),无需额外配置回调地址。日志中出现以下内容表示连接成功:
|
||||
保存后 WeKnora 会自动建立到企业微信的 WebSocket 长连接。日志中出现以下内容表示连接成功:
|
||||
|
||||
```
|
||||
[IM] WeCom WebSocket connecting (bot_id=xxx)...
|
||||
@@ -78,31 +85,29 @@ im:
|
||||
- **AgentID** — 应用详情页中的 AgentId(整数)
|
||||
- **Secret** — 应用详情页中的 Secret
|
||||
|
||||
**第二步:配置接收消息**
|
||||
**第二步:在 WeKnora 中添加 IM 渠道**
|
||||
|
||||
1. 进入 Agent 编辑器 → **IM 集成** 标签页 → **添加渠道**
|
||||
2. 填写配置:
|
||||
- **平台**:选择「企业微信」
|
||||
- **接入模式**:选择「Webhook」
|
||||
- **输出模式**:选择「流式输出」
|
||||
- **Corp ID**:企业 ID
|
||||
- **Agent Secret**:应用 Secret
|
||||
- **Token**:自定义或随机生成(记录下来)
|
||||
- **EncodingAESKey**:自定义或随机生成(记录下来)
|
||||
- **Corp Agent ID**:应用 AgentID(整数)
|
||||
3. 保存后,渠道卡片上会显示**回调地址**,格式为 `https://你的域名/api/v1/im/callback/{channel_id}`
|
||||
4. 复制该回调地址
|
||||
|
||||
**第三步:配置企业微信接收消息**
|
||||
|
||||
1. 在应用详情页 → **接收消息** → **设置 API 接收**
|
||||
2. 填写:
|
||||
- **URL**:`https://你的域名/api/v1/im/callback/wecom`
|
||||
- **Token**:自定义或随机生成(记录下来)
|
||||
- **EncodingAESKey**:点击随机生成(记录下来)
|
||||
3. 点击保存,企业微信会发送 GET 验证请求,WeKnora 需先启动以响应验证
|
||||
|
||||
**第三步:配置 WeKnora**
|
||||
|
||||
```yaml
|
||||
im:
|
||||
wecom:
|
||||
enabled: true
|
||||
mode: "webhook" # 使用 Webhook 回调
|
||||
output_mode: "stream"
|
||||
tenant_id: ["你的租户ID"]
|
||||
knowledge_base_ids: ["你的知识库ID"]
|
||||
corp_id: "${WECOM_CORP_ID}" # 企业 ID
|
||||
agent_secret: "${WECOM_AGENT_SECRET}" # 应用 Secret
|
||||
token: "${WECOM_TOKEN}" # 接收消息 Token
|
||||
encoding_aes_key: "${WECOM_AES_KEY}" # 接收消息 EncodingAESKey
|
||||
corp_agent_id: 1000001 # 应用 AgentID(整数)
|
||||
```
|
||||
- **URL**:粘贴上一步复制的回调地址
|
||||
- **Token**:填入在 WeKnora 中设置的 Token
|
||||
- **EncodingAESKey**:填入在 WeKnora 中设置的 EncodingAESKey
|
||||
3. 点击保存,企业微信会发送 GET 验证请求,WeKnora 会自动响应
|
||||
|
||||
**第四步:配置可信域名(可选)**
|
||||
|
||||
@@ -141,20 +146,16 @@ im:
|
||||
|
||||
在 **版本管理与发布** 中创建版本并提交审核。审核通过后用户才能与机器人交互。
|
||||
|
||||
**第四步:配置 WeKnora**
|
||||
**第四步:在 WeKnora 中添加 IM 渠道**
|
||||
|
||||
```yaml
|
||||
im:
|
||||
feishu:
|
||||
enabled: true
|
||||
mode: "websocket" # 使用长连接
|
||||
output_mode: "stream" # 流式输出(推荐,需开启 cardkit:card 权限)
|
||||
tenant_id: ["你的租户ID"]
|
||||
knowledge_base_ids: ["你的知识库ID"]
|
||||
app_id: "${FEISHU_APP_ID}" # App ID
|
||||
app_secret: "${FEISHU_APP_SECRET}" # App Secret
|
||||
# WebSocket 模式无需 verification_token 和 encrypt_key
|
||||
```
|
||||
1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道**
|
||||
2. 填写配置:
|
||||
- **平台**:选择「飞书」
|
||||
- **接入模式**:选择「WebSocket」
|
||||
- **输出模式**:选择「流式输出」(需开启 cardkit:card 权限)
|
||||
- **App ID**:填入从飞书获取的 App ID
|
||||
- **App Secret**:填入从飞书获取的 App Secret
|
||||
3. 保存
|
||||
|
||||
启动后日志出现以下内容表示连接成功:
|
||||
|
||||
@@ -170,40 +171,26 @@ im:
|
||||
|
||||
**前置步骤**同上(创建应用、开通权限),额外需要:
|
||||
|
||||
1. **配置事件订阅**:
|
||||
- 在 **事件与回调** → **事件配置** 中,选择请求方式为 **将事件发送到开发者服务器**
|
||||
- **请求地址**:`https://你的域名/api/v1/im/callback/feishu`
|
||||
- 记录页面上的 **Encrypt Key** 和 **Verification Token**
|
||||
- 添加事件 `im.message.receive_v1`
|
||||
2. 点击保存时飞书会发送 URL 验证请求(challenge),WeKnora 需先启动以响应
|
||||
**第一步:在 WeKnora 中添加 IM 渠道**
|
||||
|
||||
```yaml
|
||||
im:
|
||||
feishu:
|
||||
enabled: true
|
||||
mode: "webhook"
|
||||
output_mode: "stream"
|
||||
tenant_id: ["你的租户ID"]
|
||||
knowledge_base_ids: ["你的知识库ID"]
|
||||
app_id: "${FEISHU_APP_ID}"
|
||||
app_secret: "${FEISHU_APP_SECRET}"
|
||||
verification_token: "${FEISHU_TOKEN}" # 事件订阅页面的 Verification Token
|
||||
encrypt_key: "${FEISHU_ENCRYPT_KEY}" # 事件订阅页面的 Encrypt Key
|
||||
```
|
||||
1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道**
|
||||
2. 填写配置:
|
||||
- **平台**:选择「飞书」
|
||||
- **接入模式**:选择「Webhook」
|
||||
- **App ID** / **App Secret**
|
||||
- **Verification Token**:从飞书事件订阅页面获取
|
||||
- **Encrypt Key**:从飞书事件订阅页面获取
|
||||
3. 保存后,复制渠道卡片上显示的**回调地址**
|
||||
|
||||
**第二步:配置飞书事件订阅**
|
||||
|
||||
1. 在 **事件与回调** → **事件配置** 中,选择请求方式为 **将事件发送到开发者服务器**
|
||||
2. **请求地址**:粘贴从 WeKnora 复制的回调地址
|
||||
3. 添加事件 `im.message.receive_v1`
|
||||
4. 点击保存时飞书会发送 URL 验证请求(challenge),WeKnora 会自动响应
|
||||
|
||||
---
|
||||
|
||||
### 通用配置项说明
|
||||
|
||||
| 配置项 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| `enabled` | bool | 是否启用该平台 |
|
||||
| `tenant_id` | uint64 | 关联的 WeKnora 租户 ID,消息处理在该租户上下文中执行 |
|
||||
| `agent_id` | string | 指定自定义 Agent(可选,为空则使用默认知识库问答) |
|
||||
| `knowledge_base_ids` | []string | 默认关联的知识库 ID 列表 |
|
||||
| `mode` | string | 连接模式:`"websocket"` (长连接) 或 `"webhook"` (HTTP 回调) |
|
||||
| `output_mode` | string | 输出模式:`"stream"` (实时流式) 或 `"full"` (等待完整回答后一次发送) |
|
||||
|
||||
### 模式选择指南
|
||||
|
||||
| | Webhook | WebSocket |
|
||||
@@ -218,45 +205,27 @@ im:
|
||||
|
||||
---
|
||||
|
||||
## 配置参考
|
||||
## 前端管理
|
||||
|
||||
完整的 `config/config.yaml` 中 `im` 段配置:
|
||||
IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模式可见,创建 Agent 时不显示)。
|
||||
|
||||
```yaml
|
||||
im:
|
||||
wecom:
|
||||
enabled: true # 是否启用企业微信
|
||||
tenant_id: 10000 # 对应的 WeKnora 租户 ID
|
||||
agent_id: "" # 指定自定义 Agent (可选)
|
||||
knowledge_base_ids: [] # 默认知识库 ID 列表
|
||||
mode: "websocket" # 连接模式: "webhook" | "websocket"
|
||||
output_mode: "stream" # 输出模式: "stream" (流式) | "full" (完整)
|
||||
### 渠道列表
|
||||
|
||||
# ── Webhook 模式配置 (自建应用) ──
|
||||
corp_id: "${WECOM_CORP_ID}" # 企业 ID
|
||||
agent_secret: "${WECOM_AGENT_SECRET}" # 应用 Secret
|
||||
token: "${WECOM_TOKEN}" # 接收消息的 Token
|
||||
encoding_aes_key: "${WECOM_AES_KEY}" # 接收消息的 EncodingAESKey
|
||||
corp_agent_id: 1000001 # 应用 AgentID(整数)
|
||||
每个渠道以卡片形式展示,包含:
|
||||
- **平台标识**:企业微信(绿色)/ 飞书(蓝色)
|
||||
- **渠道名称**:用户自定义
|
||||
- **接入模式**:WebSocket / Webhook
|
||||
- **输出模式**:流式输出 / 完整输出
|
||||
- **启用开关**:可即时启用/停用渠道
|
||||
- **回调地址**:Webhook 模式下显示,可一键复制
|
||||
- **编辑/删除**:管理渠道配置
|
||||
|
||||
# ── WebSocket 模式配置 (智能机器人) ──
|
||||
bot_id: "${WECOM_BOT_ID}" # 机器人 ID
|
||||
bot_secret: "${WECOM_BOT_SECRET}" # 机器人 Secret
|
||||
### 渠道操作
|
||||
|
||||
feishu:
|
||||
enabled: true # 是否启用飞书
|
||||
tenant_id: 10000
|
||||
agent_id: ""
|
||||
knowledge_base_ids: []
|
||||
mode: "websocket" # "websocket" | "webhook"
|
||||
output_mode: "stream" # "stream" | "full"
|
||||
app_id: "${FEISHU_APP_ID}" # 应用 App ID
|
||||
app_secret: "${FEISHU_APP_SECRET}" # 应用 App Secret
|
||||
verification_token: "${FEISHU_TOKEN}" # 事件验证 Token (仅 Webhook 模式)
|
||||
encrypt_key: "${FEISHU_ENCRYPT_KEY}" # 加密密钥 (仅 Webhook 模式)
|
||||
```
|
||||
|
||||
> **提示:** 配置值支持环境变量引用(`${VAR_NAME}` 语法),建议将密钥类配置通过环境变量注入,避免明文提交到代码仓库。
|
||||
- **添加渠道**:选择平台 → 填写凭证 → 选择模式 → 保存
|
||||
- **编辑渠道**:可修改名称、模式、输出模式和凭证(平台不可更改)
|
||||
- **启用/停用**:通过开关即时切换,停用的渠道不会处理消息
|
||||
- **删除渠道**:删除后不可恢复
|
||||
|
||||
---
|
||||
|
||||
@@ -280,15 +249,17 @@ im:
|
||||
│ ─────┼───────────────┼────────────────────────────────────────────── │
|
||||
│ └───────┬───────┘ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ im.Service │ 服务编排层 │
|
||||
│ │ │ · 消息去重 (MessageID + TTL) │
|
||||
│ │ │ · 会话映射 (ChannelSession) │
|
||||
│ │ │ · 流式/全量路由 │
|
||||
│ └──────┬───────┘ · QA 管道调度 │
|
||||
│ │ │
|
||||
│ ────────────┼───────────────────────────────────────────────────── │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────┐ │
|
||||
│ │ im.Service │ 服务编排层 │
|
||||
│ │ │ · IM 渠道管理 (CRUD) │
|
||||
│ │ ┌───────────────┐ │ · Adapter Factory (动态创建) │
|
||||
│ │ │ im_channels │ │ · 消息去重 (MessageID + TTL) │
|
||||
│ │ │ (DB表) │ │ · 会话映射 (ChannelSession) │
|
||||
│ │ └───────────────┘ │ · 流式/全量路由 │
|
||||
│ └──────────┬──────────┘ · QA 管道调度 │
|
||||
│ │ │
|
||||
│ ───────────┼────────────────────────────────────────────────────── │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ WeKnora Core (QA Pipeline) │ 核心层 │
|
||||
│ │ SessionService · MessageService │ │
|
||||
@@ -302,13 +273,84 @@ im:
|
||||
| 模式 | 用途 |
|
||||
|------|------|
|
||||
| Adapter Pattern | 统一不同 IM 平台的差异,每个平台实现 `im.Adapter` 接口 |
|
||||
| Factory Pattern | 通过 `AdapterFactory` 从数据库渠道配置动态创建 Adapter 实例 |
|
||||
| Strategy Pattern | `StreamSender` 可选接口,让平台按需支持流式输出 |
|
||||
| Event-Driven | 通过 `EventBus` 解耦 QA 管道与 IM 输出,支持实时块推送 |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### im_channels 表
|
||||
|
||||
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
|
||||
);
|
||||
```
|
||||
|
||||
**credentials 字段结构:**
|
||||
|
||||
| 平台 | 模式 | 字段 |
|
||||
|------|------|------|
|
||||
| 企业微信 | WebSocket | `bot_id`, `bot_secret` |
|
||||
| 企业微信 | Webhook | `corp_id`, `agent_secret`, `token`, `encoding_aes_key`, `corp_agent_id` |
|
||||
| 飞书 | WebSocket | `app_id`, `app_secret` |
|
||||
| 飞书 | Webhook | `app_id`, `app_secret`, `verification_token`, `encrypt_key` |
|
||||
|
||||
### im_channel_sessions 表
|
||||
|
||||
将 IM 渠道中的用户会话映射到 WeKnora 会话:
|
||||
|
||||
```
|
||||
(im_channel_id, Platform, UserID, ChatID, TenantID) → SessionID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
|
||||
### IM 渠道管理 API(需认证)
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/agents/:id/im-channels` | 创建 IM 渠道 |
|
||||
| GET | `/api/v1/agents/:id/im-channels` | 列出 Agent 的所有 IM 渠道 |
|
||||
| PUT | `/api/v1/im-channels/:id` | 更新 IM 渠道 |
|
||||
| DELETE | `/api/v1/im-channels/:id` | 删除 IM 渠道 |
|
||||
| POST | `/api/v1/im-channels/:id/toggle` | 启用/停用 IM 渠道 |
|
||||
|
||||
### IM 回调端点(无需认证,平台签名验证)
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET/POST | `/api/v1/im/callback/:channel_id` | 通用回调(根据 channel_id 自动路由到对应 Adapter) |
|
||||
|
||||
> Webhook 模式下,每个渠道有唯一的回调地址 `/api/v1/im/callback/{channel_id}`,在前端渠道卡片上可一键复制。
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
### IMChannel — IM 渠道
|
||||
|
||||
每个 IM 渠道代表一个 IM 平台机器人与 WeKnora Agent 的绑定关系。一个 Agent 可以绑定多个渠道(如同时接入企业微信和飞书),同一平台也可以创建多个渠道(如不同的企业微信机器人)。
|
||||
|
||||
渠道启动时,Service 通过 `AdapterFactory` 根据平台类型和凭证动态创建对应的 Adapter 实例。
|
||||
|
||||
### IncomingMessage — 统一入站消息
|
||||
|
||||
所有平台的消息在解密、解析后被归一化为 `IncomingMessage`,抹平平台差异:
|
||||
@@ -339,13 +381,7 @@ type ReplyMessage struct {
|
||||
|
||||
### ChannelSession — 会话映射
|
||||
|
||||
将 IM 渠道 (平台 + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性:
|
||||
|
||||
```
|
||||
(Platform, UserID, ChatID, TenantID) → SessionID
|
||||
```
|
||||
|
||||
首次交互自动创建,后续消息复用同一会话。存储于 `im_channel_sessions` 表。
|
||||
将 IM 渠道 (渠道 ID + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性。首次交互自动创建,后续消息复用同一会话。存储于 `im_channel_sessions` 表。
|
||||
|
||||
---
|
||||
|
||||
@@ -358,20 +394,23 @@ type ReplyMessage struct {
|
||||
│
|
||||
▼
|
||||
┌─ HTTP Handler ──────────────────────────────────┐
|
||||
│ 1. 签名验证 (VerifyCallback) │
|
||||
│ 2. URL 验证处理 (HandleURLVerification) │
|
||||
│ 3. 解密 + 解析 → IncomingMessage (ParseCallback) │
|
||||
│ 4. 立即返回 HTTP 200 (异步处理) │
|
||||
│ 1. 根据 channel_id 查找渠道配置 │
|
||||
│ 2. 获取对应 Adapter │
|
||||
│ 3. 签名验证 (VerifyCallback) │
|
||||
│ 4. URL 验证处理 (HandleURLVerification) │
|
||||
│ 5. 解密 + 解析 → IncomingMessage (ParseCallback) │
|
||||
│ 6. 立即返回 HTTP 200 (异步处理) │
|
||||
└──────────────────────────┬──────────────────────-┘
|
||||
│ goroutine
|
||||
▼
|
||||
┌─ im.Service ────────────────────────────────────┐
|
||||
│ 1. 去重检查 (MessageID, 5 分钟 TTL) │
|
||||
│ 2. 内容长度校验 (≤ 4096 字符) │
|
||||
│ 3. 解析/创建 ChannelSession │
|
||||
│ 4. 获取 WeKnora Session │
|
||||
│ 5. 解析自定义 Agent (可选) │
|
||||
│ 6. 判断流式/全量模式 │
|
||||
│ 3. 从渠道配置获取 agent_id、tenant_id │
|
||||
│ 4. 解析/创建 ChannelSession │
|
||||
│ 5. 获取 WeKnora Session │
|
||||
│ 6. 加载 Agent 配置(获取知识库等信息) │
|
||||
│ 7. 判断流式/全量模式 │
|
||||
└───────────┬─────────────────────┬───────────────┘
|
||||
│ │
|
||||
流式模式 ▼ 全量模式 ▼
|
||||
@@ -389,6 +428,29 @@ type ReplyMessage struct {
|
||||
消息持久化 (user + assistant)
|
||||
```
|
||||
|
||||
### 渠道生命周期
|
||||
|
||||
```
|
||||
渠道创建/更新 (前端 UI)
|
||||
│
|
||||
▼
|
||||
┌─ im.Service ──────────────────────────┐
|
||||
│ 1. 保存渠道配置到数据库 │
|
||||
│ 2. 如果渠道已启用: │
|
||||
│ a. AdapterFactory 创建 Adapter │
|
||||
│ b. WebSocket 模式:建立长连接 │
|
||||
│ c. Webhook 模式:注册回调处理 │
|
||||
│ 3. 维护 channels map (channel_id → │
|
||||
│ channelState{Channel, Adapter}) │
|
||||
└────────────────────────────────────────┘
|
||||
|
||||
服务启动时:
|
||||
LoadAndStartChannels() → 从 DB 加载所有 enabled 的渠道 → 逐个 StartChannel()
|
||||
|
||||
渠道停用/删除时:
|
||||
StopChannel() → 取消 Adapter 上下文 → 从 map 移除
|
||||
```
|
||||
|
||||
### 流式输出机制
|
||||
|
||||
流式模式通过 `EventBus` 实时收集 QA 管道产生的内容块,以 **300ms 间隔批量推送**,在延迟与 API 限频之间取得平衡:
|
||||
@@ -443,7 +505,15 @@ type StreamSender interface {
|
||||
}
|
||||
```
|
||||
|
||||
实现此接口后,Service 会自动路由到流式模式。可通过配置 `output_mode: "full"` 强制关闭。
|
||||
实现此接口后,Service 会自动路由到流式模式。渠道配置 `output_mode: "full"` 可强制关闭。
|
||||
|
||||
### im.AdapterFactory — 适配器工厂
|
||||
|
||||
```go
|
||||
type AdapterFactory func(ctx context.Context, channel *IMChannel, msgHandler func(*IncomingMessage)) (Adapter, CancelFunc, error)
|
||||
```
|
||||
|
||||
每个平台注册一个工厂函数,Service 在启动渠道时调用工厂创建 Adapter 实例。工厂函数根据渠道的 `mode` 和 `credentials` 决定创建哪种 Adapter。
|
||||
|
||||
---
|
||||
|
||||
@@ -458,7 +528,7 @@ type StreamSender interface {
|
||||
适用于**自建应用**,需要公网可访问的回调地址。
|
||||
|
||||
```
|
||||
企业微信服务器 ──HTTP POST──▶ /api/v1/im/callback/wecom
|
||||
企业微信服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id}
|
||||
│
|
||||
解密 (AES-128-CBC)
|
||||
解析 XML → IncomingMessage
|
||||
@@ -493,8 +563,8 @@ LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `internal/im/wecom/adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、Token 缓存 |
|
||||
| `internal/im/wecom/bot_adapter.go` | WebSocket 模式适配器壳,代理到 `LongConnClient` |
|
||||
| `internal/im/wecom/webhook_adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、Token 缓存 |
|
||||
| `internal/im/wecom/ws_adapter.go` | WebSocket 模式适配器壳,代理到 `LongConnClient` |
|
||||
| `internal/im/wecom/longconn.go` | WebSocket 客户端:连接管理、心跳、帧协议、自动重连 |
|
||||
|
||||
---
|
||||
@@ -506,7 +576,7 @@ LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com
|
||||
#### Webhook 模式
|
||||
|
||||
```
|
||||
飞书服务器 ──HTTP POST──▶ /api/v1/im/callback/feishu
|
||||
飞书服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id}
|
||||
│
|
||||
解密 (AES-256-CBC,可选)
|
||||
解析 JSON → IncomingMessage
|
||||
@@ -574,15 +644,7 @@ EndStream:
|
||||
| 空回答 | 回复 "抱歉,我暂时无法回答这个问题。" |
|
||||
| WebSocket 断连 | 指数退避自动重连 |
|
||||
| 平台重试 | MessageID 去重,5 分钟内自动跳过 |
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET/POST | `/api/v1/im/callback/wecom` | 企业微信回调 (GET 用于 URL 验证) |
|
||||
| POST | `/api/v1/im/callback/feishu` | 飞书回调 (URL 验证 + 消息事件) |
|
||||
| 渠道启动失败 | 日志记录错误,不影响其他渠道 |
|
||||
|
||||
---
|
||||
|
||||
@@ -608,23 +670,35 @@ func (a *Adapter) HandleURLVerification(c *gin.Context) bool { /* URL 验证 */
|
||||
|
||||
如需流式输出,额外实现 `im.StreamSender`。
|
||||
|
||||
### 2. 注册适配器
|
||||
### 2. 注册适配器工厂
|
||||
|
||||
在 `internal/container/container.go` 的 `registerIMAdapters` 中初始化并注册:
|
||||
在 `internal/container/container.go` 的 `registerIMAdapterFactories` 中注册工厂函数:
|
||||
|
||||
```go
|
||||
if cfg.IM.DingTalk.Enabled {
|
||||
adapter := dingtalk.NewAdapter(cfg.IM.DingTalk.AppKey, cfg.IM.DingTalk.AppSecret)
|
||||
imService.RegisterAdapter(adapter)
|
||||
}
|
||||
imService.RegisterAdapterFactory("dingtalk", func(ctx context.Context, channel *im.IMChannel, msgHandler func(*im.IncomingMessage)) (im.Adapter, im.CancelFunc, error) {
|
||||
creds := parseCredentials(channel.Credentials)
|
||||
appKey := getString(creds, "app_key")
|
||||
appSecret := getString(creds, "app_secret")
|
||||
|
||||
adapter := dingtalk.NewAdapter(appKey, appSecret)
|
||||
|
||||
// WebSocket 模式需要启动长连接
|
||||
if channel.Mode == "websocket" {
|
||||
cancelCtx, cancel := context.WithCancel(ctx)
|
||||
go adapter.StartLongConn(cancelCtx, msgHandler)
|
||||
return adapter, func() { cancel() }, nil
|
||||
}
|
||||
|
||||
return adapter, func() {}, nil
|
||||
})
|
||||
```
|
||||
|
||||
### 3. 添加回调路由
|
||||
### 3. 前端添加平台选项
|
||||
|
||||
在 `internal/router/router.go` 中注册 HTTP 端点:
|
||||
在 `IMChannelPanel.vue` 中:
|
||||
- 添加平台 radio 选项
|
||||
- 添加该平台的凭证表单字段
|
||||
|
||||
```go
|
||||
im.POST("/callback/dingtalk", imHandler.DingTalkCallback)
|
||||
```
|
||||
在 i18n 文件中添加平台名称翻译。
|
||||
|
||||
Service 层 (`im.Service`) 不需要任何修改 —— 消息编排、会话管理、QA 调度、流式控制全部由 Service 统一处理。
|
||||
Service 层 (`im.Service`) 不需要任何修改 — 渠道管理、消息编排、会话管理、QA 调度、流式控制全部由 Service 统一处理。
|
||||
|
||||
Reference in New Issue
Block a user