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 统一处理。