From d2bd3881e7493ae96931a9f4467b93cf4fdb35f2 Mon Sep 17 00:00:00 2001 From: nullkey Date: Thu, 19 Mar 2026 04:17:04 +0800 Subject: [PATCH] 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 --- docs/IM集成开发文档.md | 453 ++++++++++++++++++++++++++++++----------- 1 file changed, 335 insertions(+), 118 deletions(-) diff --git a/docs/IM集成开发文档.md b/docs/IM集成开发文档.md index 377e3160..46cd0cdc 100644 --- a/docs/IM集成开发文档.md +++ b/docs/IM集成开发文档.md @@ -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 刷新 - │ - ┌───────────▼───────────┐ - │ 累积内容 → 完整替换推送 │ - │ (非增量,每次发送全文) │ - └───────────────────────┘ -``` - -**关键细节:** -- `...` 块在流式输出中被过滤,不展示给用户 -- 流式初始化失败时自动降级到全量模式 (`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 块处理:** 流式输出中的 `...` 块会被转换为飞书 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 块过滤/转换**:`...` 块在飞书中转换为引用块展示,在其他平台中过滤 +- **工具事件展示**:Agent 工具调用实时展示调用状态 + - 调用中:`⏳ [工具名]`(包裹在 think 块内) + - 调用成功:`✅ [工具名] · [摘要]` + - 调用失败:`⚠️ [工具名] 失败` + - 内部工具(thinking、todo_write 等)不展示给用户 +- **空内容回退**:流式过程中无可见内容产生时,回退到完整回复模式 (`fallbackNonStream`) +- **完整持久化**:完整内容(含 thinking)持久化到数据库,确保历史完整 + +### 飞书流式特殊处理 + +- **"正在思考..." 占位**:流式初始化后立即显示占位文本,提升用户感知 +- **孤立流清理**:后台协程每 `streamReaperInterval`(1 分钟)扫描超过 `streamOrphanTTL`(5 分钟)未关闭的流,自动关闭防止内存泄漏 +- **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 统一处理。