diff --git a/config/config.yaml b/config/config.yaml
index 4f502e85..2aafb94e 100644
--- a/config/config.yaml
+++ b/config/config.yaml
@@ -207,11 +207,15 @@ conversation:
- If the user asks in Chinese, respond in Chinese
context_template: |
- The following is retrieved information:
+ The following is retrieved information that may or may not be relevant:
{{contexts}}
- Based on the above retrieved information, answer the following question:
- {{query}}
+ User question: {{query}}
+
+ Instructions:
+ - If the retrieved information is relevant to the user's question, use it to provide an accurate answer.
+ - If the retrieved information is NOT relevant (e.g., the user is greeting, chatting, or asking something unrelated), ignore it and respond naturally as a helpful assistant.
+ - Do not mention "retrieved information" or "reference materials" in your response unless the user explicitly asks about sources.
extract_entities_prompt: |
## Task
Extract all entities from the user-provided text that match the following entity types:
@@ -553,9 +557,10 @@ im:
enabled: true
tenant_id: 10000 # WeKnora tenant ID to use
agent_id: "" # Default agent ID (optional)
- knowledge_base_ids:
- - "" # Default knowledge bases (optional)
+ knowledge_base_ids:
+ - "2f046c68-869c-460f-866a-b149ac9a5195" # Default knowledge bases (optional)
mode: "websocket" # "webhook" or "websocket"
+ output_mode: "stream" # "stream" (default, real-time) or "full" (wait for complete answer)
# --- websocket mode (智能机器人长连接) ---
bot_id: "${WECOM_BOT_ID}" # 智能机器人 Bot ID
bot_secret: "${WECOM_BOT_SECRET}" # 智能机器人 Secret
@@ -570,8 +575,9 @@ im:
tenant_id: 10000 # WeKnora tenant ID to use
agent_id: "" # Default agent ID (optional)
knowledge_base_ids: # Default knowledge bases
- - ""
+ - "2f046c68-869c-460f-866a-b149ac9a5195"
mode: "websocket" # "webhook" or "websocket"
+ output_mode: "stream" # "stream" (default, real-time) or "full" (wait for complete answer)
app_id: "${FEISHU_APP_ID}" # 飞书 App ID
app_secret: "${FEISHU_APP_SECRET}" # 飞书 App Secret
# --- 以下仅 webhook 模式需要,websocket 模式可留空 ---
diff --git a/docs/IM集成开发文档.md b/docs/IM集成开发文档.md
new file mode 100644
index 00000000..1fb35061
--- /dev/null
+++ b/docs/IM集成开发文档.md
@@ -0,0 +1,630 @@
+# IM 集成开发文档
+
+WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
+
+## 目录
+
+- [快速接入指南](#快速接入指南)
+ - [企业微信接入](#企业微信接入)
+ - [飞书接入](#飞书接入)
+- [配置参考](#配置参考)
+- [架构总览](#架构总览)
+- [核心概念](#核心概念)
+- [数据流](#数据流)
+- [接口定义](#接口定义)
+- [平台适配器详解](#平台适配器详解)
+ - [企业微信 (WeCom)](#企业微信-wecom)
+ - [飞书 (Feishu)](#飞书-feishu)
+- [关键参数与阈值](#关键参数与阈值)
+- [错误处理](#错误处理)
+- [扩展新平台](#扩展新平台)
+
+---
+
+## 快速接入指南
+
+### 企业微信接入
+
+企业微信提供两种接入模式,根据你的应用类型选择:
+
+#### 方式一:WebSocket 模式(智能机器人,推荐)
+
+> 无需公网域名,适合快速验证和内网部署。
+
+**第一步:创建智能机器人**
+
+1. 登录 [企业微信工作台](确认已升级到最新版企业微信) → **智能机器人** → **创建机器人** → **手动创建** → **切换API模式创建** → **选择“使用长连接”**
+2. 创建完成后,在机器人详情页获取:
+ - **BotID** — 机器人唯一标识
+ - **BotSecret** — 机器人密钥(点击重置可重新生成)
+
+**第二步:配置 WeKnora**
+
+编辑 `config/config.yaml`:
+
+```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`),无需额外配置回调地址。日志中出现以下内容表示连接成功:
+
+```
+[IM] WeCom WebSocket connecting (bot_id=xxx)...
+```
+
+此时在企业微信中给机器人发消息即可收到 AI 回复。
+
+---
+
+#### 方式二:Webhook 模式(自建应用)
+
+> 需要公网可达的回调地址,适合已有自建应用的场景。
+
+**第一步:创建自建应用**
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/) → **应用管理** → **自建** → **创建应用**
+2. 记录以下信息:
+ - **CorpID** — 在 **我的企业** → **企业信息** 页面底部
+ - **AgentID** — 应用详情页中的 AgentId(整数)
+ - **Secret** — 应用详情页中的 Secret
+
+**第二步:配置接收消息**
+
+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(整数)
+```
+
+**第四步:配置可信域名(可选)**
+
+如需在群聊中使用,在应用详情页 → **网页授权及 JS-SDK** 中添加可信域名。
+
+---
+
+### 飞书接入
+
+飞书同样提供两种模式,WebSocket 模式配置更简单。
+
+#### 方式一:WebSocket 模式(推荐)
+
+> 无需公网域名,无需配置事件加密。
+
+**第一步:创建飞书应用**
+
+1. 登录 [飞书开放平台](https://open.feishu.cn/) → **开发者后台** → **创建企业自建应用**
+2. 在 **凭证与基础信息** 页获取:
+ - **App ID**
+ - **App Secret**
+
+**第二步:开通权限与事件**
+
+1. **添加应用能力**:在应用详情页 → **添加应用能力** → 添加 **机器人** 能力
+2. **配置权限**:在 **权限管理** 中搜索并开通以下权限:
+ - `im:message` — 获取与发送单聊、群组消息(读写权限)
+ - `im:message.group_at_msg` — 接收群聊中 @ 机器人消息
+ - `im:chat` — 获取群组信息(只读权限,群聊场景需要)
+ - `cardkit:card` — 创建和更新卡片(**流式输出必需**)
+3. **配置事件订阅**:
+ - 在 **事件与回调** → **事件配置** 中,选择请求方式为 **使用长连接接收事件**
+ - 添加事件 `im.message.receive_v1`(接收消息)
+
+**第三步:发布应用**
+
+在 **版本管理与发布** 中创建版本并提交审核。审核通过后用户才能与机器人交互。
+
+**第四步:配置 WeKnora**
+
+```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
+```
+
+启动后日志出现以下内容表示连接成功:
+
+```
+[IM] Feishu WebSocket connecting (app_id=xxx)...
+```
+
+---
+
+#### 方式二:Webhook 模式
+
+> 需要公网可达的回调地址。
+
+**前置步骤**同上(创建应用、开通权限),额外需要:
+
+1. **配置事件订阅**:
+ - 在 **事件与回调** → **事件配置** 中,选择请求方式为 **将事件发送到开发者服务器**
+ - **请求地址**:`https://你的域名/api/v1/im/callback/feishu`
+ - 记录页面上的 **Encrypt Key** 和 **Verification Token**
+ - 添加事件 `im.message.receive_v1`
+2. 点击保存时飞书会发送 URL 验证请求(challenge),WeKnora 需先启动以响应
+
+```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
+```
+
+---
+
+### 通用配置项说明
+
+| 配置项 | 类型 | 说明 |
+|--------|------|------|
+| `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 |
+|---|---------|-----------|
+| 网络要求 | 需要公网可达的 HTTPS 回调地址 | 仅需出站网络,无需公网 |
+| 适用场景 | 已有域名和证书、自建应用 | 快速部署、内网环境、PoC 验证 |
+| 连接管理 | 无状态,平台推送 | 自动维护长连接、心跳、断线重连 |
+| 配置复杂度 | 需要配置回调 URL、加密密钥 | 只需 App ID/Secret |
+| 流式输出 | 支持 | 支持 |
+
+> **建议:** 优先使用 WebSocket 模式,部署更简单,不依赖公网域名。
+
+---
+
+## 配置参考
+
+完整的 `config/config.yaml` 中 `im` 段配置:
+
+```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 模式配置 (智能机器人) ──
+ 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}` 语法),建议将密钥类配置通过环境变量注入,避免明文提交到代码仓库。
+
+---
+
+## 架构总览
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ IM 集成架构 │
+│ │
+│ ┌──────────┐ ┌──────────┐ │
+│ │ 企业微信 │ │ 飞书 │ IM 平台层 │
+│ └────┬─────┘ └────┬─────┘ │
+│ │ Webhook/WS │ Webhook/WS │
+│ ─────┼───────────────┼────────────────────────────────────────────── │
+│ ▼ ▼ │
+│ ┌──────────┐ ┌──────────┐ │
+│ │ WeCom │ │ Feishu │ 平台适配器层 (im.Adapter) │
+│ │ Adapter │ │ Adapter │ · 消息解密、解析 │
+│ └────┬─────┘ └────┬─────┘ · 签名验证 │
+│ │ │ · 回复发送、流式推送 │
+│ ─────┼───────────────┼────────────────────────────────────────────── │
+│ └───────┬───────┘ │
+│ ▼ │
+│ ┌──────────────┐ │
+│ │ im.Service │ 服务编排层 │
+│ │ │ · 消息去重 (MessageID + TTL) │
+│ │ │ · 会话映射 (ChannelSession) │
+│ │ │ · 流式/全量路由 │
+│ └──────┬───────┘ · QA 管道调度 │
+│ │ │
+│ ────────────┼───────────────────────────────────────────────────── │
+│ ▼ │
+│ ┌─────────────────────────────────────┐ │
+│ │ WeKnora Core (QA Pipeline) │ 核心层 │
+│ │ SessionService · MessageService │ │
+│ │ TenantService · AgentService │ │
+│ └─────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**设计模式:**
+
+| 模式 | 用途 |
+|------|------|
+| Adapter Pattern | 统一不同 IM 平台的差异,每个平台实现 `im.Adapter` 接口 |
+| Strategy Pattern | `StreamSender` 可选接口,让平台按需支持流式输出 |
+| Event-Driven | 通过 `EventBus` 解耦 QA 管道与 IM 输出,支持实时块推送 |
+
+---
+
+## 核心概念
+
+### IncomingMessage — 统一入站消息
+
+所有平台的消息在解密、解析后被归一化为 `IncomingMessage`,抹平平台差异:
+
+```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 // 平台特有字段
+}
+```
+
+### ReplyMessage — 统一出站回复
+
+```go
+type ReplyMessage struct {
+ Content string // Markdown 文本
+ IsStreaming bool // 是否为流式块
+ IsFinal bool // 是否为最后一块
+ Extra map[string]string // 平台特有字段
+}
+```
+
+### ChannelSession — 会话映射
+
+将 IM 渠道 (平台 + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性:
+
+```
+(Platform, UserID, ChatID, TenantID) → SessionID
+```
+
+首次交互自动创建,后续消息复用同一会话。存储于 `im_channel_sessions` 表。
+
+---
+
+## 数据流
+
+### 完整消息处理流程
+
+```
+用户在 IM 中发送消息
+ │
+ ▼
+┌─ HTTP Handler ──────────────────────────────────┐
+│ 1. 签名验证 (VerifyCallback) │
+│ 2. URL 验证处理 (HandleURLVerification) │
+│ 3. 解密 + 解析 → IncomingMessage (ParseCallback) │
+│ 4. 立即返回 HTTP 200 (异步处理) │
+└──────────────────────────┬──────────────────────-┘
+ │ goroutine
+ ▼
+┌─ im.Service ────────────────────────────────────┐
+│ 1. 去重检查 (MessageID, 5 分钟 TTL) │
+│ 2. 内容长度校验 (≤ 4096 字符) │
+│ 3. 解析/创建 ChannelSession │
+│ 4. 获取 WeKnora Session │
+│ 5. 解析自定义 Agent (可选) │
+│ 6. 判断流式/全量模式 │
+└───────────┬─────────────────────┬───────────────┘
+ │ │
+ 流式模式 ▼ 全量模式 ▼
+┌────────────────────┐ ┌─────────────────────┐
+│ handleMessageStream│ │ runQA (阻塞收集完整 │
+│ │ │ 回答后一次性发送) │
+│ · StartStream │ └─────────────────────┘
+│ · EventBus 订阅 │
+│ · 300ms 批量刷新 │
+│ · SendStreamChunk │
+│ · EndStream │
+└────────────────────┘
+ │
+ ▼
+ 消息持久化 (user + assistant)
+```
+
+### 流式输出机制
+
+流式模式通过 `EventBus` 实时收集 QA 管道产生的内容块,以 **300ms 间隔批量推送**,在延迟与 API 限频之间取得平衡:
+
+```
+QA 管道 ──chunk──chunk──chunk──▶ EventBus
+ │
+ 每 300ms 刷新
+ │
+ ┌───────────▼───────────┐
+ │ 累积内容 → 完整替换推送 │
+ │ (非增量,每次发送全文) │
+ └───────────────────────┘
+```
+
+**关键细节:**
+- `...` 块在流式输出中被过滤,不展示给用户
+- 流式初始化失败时自动降级到全量模式 (`fallbackNonStream`)
+- 完整内容(含 thinking)持久化到数据库,确保历史完整
+
+---
+
+## 接口定义
+
+### im.Adapter — 平台适配器 (必须实现)
+
+```go
+type Adapter interface {
+ Platform() Platform
+ VerifyCallback(c *gin.Context) error
+ ParseCallback(c *gin.Context) (*IncomingMessage, error)
+ SendReply(ctx context.Context, incoming *IncomingMessage, reply *ReplyMessage) error
+ HandleURLVerification(c *gin.Context) bool
+}
+```
+
+| 方法 | 职责 |
+|------|------|
+| `Platform()` | 返回平台标识,用于路由和注册 |
+| `VerifyCallback()` | 验证回调请求的签名/Token |
+| `ParseCallback()` | 解密并解析回调为 `IncomingMessage`,非消息事件返回 `nil` |
+| `SendReply()` | 通过平台 API 发送完整回复 |
+| `HandleURLVerification()` | 处理平台初始 URL 验证(首次配置时调用) |
+
+### im.StreamSender — 流式推送 (可选实现)
+
+```go
+type StreamSender interface {
+ StartStream(ctx context.Context, incoming *IncomingMessage) (streamID string, err error)
+ SendStreamChunk(ctx context.Context, incoming *IncomingMessage, streamID string, content string) error
+ EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error
+}
+```
+
+实现此接口后,Service 会自动路由到流式模式。可通过配置 `output_mode: "full"` 强制关闭。
+
+---
+
+## 平台适配器详解
+
+### 企业微信 (WeCom)
+
+提供两种连接模式,对应两套适配器实现:
+
+#### Webhook 模式 (`WebhookAdapter`)
+
+适用于**自建应用**,需要公网可访问的回调地址。
+
+```
+企业微信服务器 ──HTTP POST──▶ /api/v1/im/callback/wecom
+ │
+ 解密 (AES-128-CBC)
+ 解析 XML → IncomingMessage
+ │
+ 处理完成后调用 WeCom REST API 回复
+```
+
+- **加密方案:** AES-128-CBC,Key 由 `encoding_aes_key` Base64 解码得到,IV 为 Key 前 16 字节
+- **消息格式:** `random(16) + msg_len(4) + message + corp_id`,PKCS#7 填充
+- **签名验证:** SHA-1(`sort([token, timestamp, nonce, encrypt])`),常量时间比较
+- **回复方式:** 通过 `/cgi-bin/message/send` 接口发送 Markdown 消息
+
+#### WebSocket 模式 (`WSAdapter` + `LongConnClient`)
+
+适用于**智能客服机器人**,无需公网域名,由客户端主动建立 WebSocket 长连接。
+
+```
+LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com
+ │
+ 1. 发送 aibot_subscribe (bot_id + secret)
+ 2. 接收 aibot_msg_callback 消息帧
+ 3. 通过 aibot_respond_msg 回复
+ 4. 每 30s 心跳保活 (ping/pong)
+ 5. 断连自动重连 (指数退避 1s → 30s)
+```
+
+- **认证:** Bot ID + Bot Secret
+- **流式回复:** 通过 WebSocket 帧发送,`finish=true` 标记结束
+- **容错:** 指数退避重连,无限重试
+
+#### 源码文件
+
+| 文件 | 职责 |
+|------|------|
+| `internal/im/wecom/adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、Token 缓存 |
+| `internal/im/wecom/bot_adapter.go` | WebSocket 模式适配器壳,代理到 `LongConnClient` |
+| `internal/im/wecom/longconn.go` | WebSocket 客户端:连接管理、心跳、帧协议、自动重连 |
+
+---
+
+### 飞书 (Feishu)
+
+统一适配器同时支持 Webhook 和 WebSocket 模式,且原生实现 `StreamSender` 接口。
+
+#### Webhook 模式
+
+```
+飞书服务器 ──HTTP POST──▶ /api/v1/im/callback/feishu
+ │
+ 解密 (AES-256-CBC,可选)
+ 解析 JSON → IncomingMessage
+ │
+ 通过飞书 Open API 回复
+```
+
+- **加密方案:** AES-256-CBC,Key 为 `SHA-256(encrypt_key)`,IV 为密文前 16 字节
+- **事件过滤:** 仅处理 `im.message.receive_v1` 事件,忽略其他事件类型
+- **群消息处理:** 自动去除 `@_user_xxx` 提及前缀
+
+#### WebSocket 模式
+
+通过飞书官方 SDK (`github.com/larksuite/oapi-sdk-go`) 建立长连接,事件推送与 Webhook 等价,无需公网域名,内置自动重连。
+
+#### 流式回复 (CardKit v1)
+
+飞书的流式输出基于 **CardKit 卡片流式更新**,是官方推荐的最佳实践:
+
+```
+StartStream:
+ 1. POST /cardkit/v1/cards → 创建卡片实体 (streaming_mode: true)
+ 2. POST /im/v1/messages → 发送卡片消息到聊天
+
+SendStreamChunk:
+ 3. PUT /cardkit/v1/cards/{id}/elements/{eid}/content → 更新元素内容 (累积全文)
+
+EndStream:
+ 4. PATCH /cardkit/v1/cards/{id}/settings → 设置 streaming_mode: false
+```
+
+每次 `SendStreamChunk` 发送的是**累积全文**而非增量,由 `feishuStreamState` 跟踪完整内容和严格递增的 `sequence` 序号。
+
+#### 源码文件
+
+| 文件 | 职责 |
+|------|------|
+| `internal/im/feishu/adapter.go` | 事件解析、CardKit 流式实现、Token 缓存、AES 解密 |
+| `internal/im/feishu/longconn.go` | WebSocket 长连接(封装飞书 SDK) |
+
+---
+
+## 关键参数与阈值
+
+| 参数 | 值 | 说明 |
+|------|------|------|
+| `qaTimeout` | 120s | QA 管道最大执行时间 |
+| `dedupTTL` | 5 min | 消息去重 ID 保留时长 |
+| `dedupCleanupInterval` | 1 min | 去重清理周期 |
+| `maxContentLength` | 4096 | 消息最大长度 (rune),超出截断 |
+| `streamFlushInterval` | 300ms | 流式内容批量刷新间隔 |
+| WeCom 心跳 | 30s | WebSocket 保活频率 |
+| WeCom 重连退避 | 1s → 30s | 指数退避,上限 30 秒 |
+| Token 缓存安全余量 | 5 min | Token 过期前提前刷新 |
+
+---
+
+## 错误处理
+
+| 场景 | 处理策略 |
+|------|---------|
+| 流式初始化失败 | 自动降级到全量模式 |
+| QA 管道异常 | 回复 "抱歉,处理您的问题时出现了异常,请稍后再试。" |
+| QA 超时 (>120s) | 标记消息完成,回复超时提示 |
+| 空回答 | 回复 "抱歉,我暂时无法回答这个问题。" |
+| WebSocket 断连 | 指数退避自动重连 |
+| 平台重试 | MessageID 去重,5 分钟内自动跳过 |
+
+---
+
+## API 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET/POST | `/api/v1/im/callback/wecom` | 企业微信回调 (GET 用于 URL 验证) |
+| POST | `/api/v1/im/callback/feishu` | 飞书回调 (URL 验证 + 消息事件) |
+
+---
+
+## 扩展新平台
+
+接入新的 IM 平台只需 3 步:
+
+### 1. 实现 `im.Adapter` 接口
+
+在 `internal/im//` 下创建适配器:
+
+```go
+package dingtalk
+
+type Adapter struct { /* 平台配置 */ }
+
+func (a *Adapter) Platform() im.Platform { return "dingtalk" }
+func (a *Adapter) VerifyCallback(c *gin.Context) error { /* 签名验证 */ }
+func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { /* 解析消息 */ }
+func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { /* 发送回复 */ }
+func (a *Adapter) HandleURLVerification(c *gin.Context) bool { /* URL 验证 */ }
+```
+
+如需流式输出,额外实现 `im.StreamSender`。
+
+### 2. 注册适配器
+
+在 `internal/container/container.go` 的 `registerIMAdapters` 中初始化并注册:
+
+```go
+if cfg.IM.DingTalk.Enabled {
+ adapter := dingtalk.NewAdapter(cfg.IM.DingTalk.AppKey, cfg.IM.DingTalk.AppSecret)
+ imService.RegisterAdapter(adapter)
+}
+```
+
+### 3. 添加回调路由
+
+在 `internal/router/router.go` 中注册 HTTP 端点:
+
+```go
+im.POST("/callback/dingtalk", imHandler.DingTalkCallback)
+```
+
+Service 层 (`im.Service`) 不需要任何修改 —— 消息编排、会话管理、QA 调度、流式控制全部由 Service 统一处理。
diff --git a/internal/config/config.go b/internal/config/config.go
index 6405bce9..f6866a1e 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -44,6 +44,8 @@ type WeComIMConfig struct {
KnowledgeBases []string `yaml:"knowledge_base_ids" json:"knowledge_base_ids"`
// Mode: "webhook" (default, requires public domain) or "websocket" (long connection via intelligent bot, no public domain needed)
Mode string `yaml:"mode" json:"mode"`
+ // OutputMode: "stream" (default, real-time streaming) or "full" (wait for complete answer then send)
+ OutputMode string `yaml:"output_mode" json:"output_mode"`
// --- Webhook mode fields (self-built app callback) ---
CorpID string `yaml:"corp_id" json:"corp_id"`
AgentSecret string `yaml:"agent_secret" json:"agent_secret"`
@@ -67,6 +69,8 @@ type FeishuIMConfig struct {
EncryptKey string `yaml:"encrypt_key" json:"encrypt_key"`
// Mode: "websocket" (default, long connection, no public domain needed) or "webhook" (requires public domain)
Mode string `yaml:"mode" json:"mode"`
+ // OutputMode: "stream" (default, real-time streaming) or "full" (wait for complete answer then send)
+ OutputMode string `yaml:"output_mode" json:"output_mode"`
}
// DocReaderConfig configures the document parser client (gRPC or HTTP).
diff --git a/internal/container/container.go b/internal/container/container.go
index ab1561cb..0a77b01a 100644
--- a/internal/container/container.go
+++ b/internal/container/container.go
@@ -960,11 +960,19 @@ func registerIMAdapters(cfg *config.Config, imService *imPkg.Service) {
// Register WeCom
if cfg.IM.WeCom != nil && cfg.IM.WeCom.Enabled {
registerWeComAdapter(ctx, cfg.IM.WeCom, imService)
+ if cfg.IM.WeCom.OutputMode == "full" {
+ imService.SetStreamDisabled(imPkg.PlatformWeCom, true)
+ logger.Infof(ctx, "[IM] WeCom streaming disabled (output_mode=full)")
+ }
}
// Register Feishu
if cfg.IM.Feishu != nil && cfg.IM.Feishu.Enabled {
registerFeishuAdapter(ctx, cfg.IM.Feishu, imService)
+ if cfg.IM.Feishu.OutputMode == "full" {
+ imService.SetStreamDisabled(imPkg.PlatformFeishu, true)
+ logger.Infof(ctx, "[IM] Feishu streaming disabled (output_mode=full)")
+ }
}
}
@@ -976,7 +984,7 @@ func registerWeComAdapter(ctx context.Context, cfg *config.WeComIMConfig, imServ
switch mode {
case "webhook":
- adapter, err := wecom.NewAdapter(
+ adapter, err := wecom.NewWebhookAdapter(
cfg.CorpID,
cfg.AgentSecret,
cfg.Token,
@@ -999,7 +1007,7 @@ func registerWeComAdapter(ctx context.Context, cfg *config.WeComIMConfig, imServ
client := wecom.NewLongConnClient(cfg.BotID, cfg.BotSecret, handler)
// Register a BotAdapter so the service can send replies via WebSocket
- imService.RegisterAdapter(wecom.NewBotAdapter(client))
+ imService.RegisterAdapter(wecom.NewWSAdapter(client))
logger.Infof(ctx, "[IM] WeCom adapter registered (mode=websocket, bot_id=%s)", cfg.BotID)
// Start the long connection in a goroutine
diff --git a/internal/im/adapter.go b/internal/im/adapter.go
index 1cbe6396..d23fd89d 100644
--- a/internal/im/adapter.go
+++ b/internal/im/adapter.go
@@ -74,3 +74,18 @@ type Adapter interface {
// Returns true if this request is a verification request and has been handled.
HandleURLVerification(c *gin.Context) bool
}
+
+// StreamSender is an optional interface that adapters can implement to support streaming replies.
+// When an adapter implements StreamSender, the IM service will push answer chunks in real-time
+// instead of waiting for the full answer.
+type StreamSender interface {
+ // StartStream initializes a streaming reply session (e.g., creates a streaming card).
+ // Returns a platform-specific stream ID for subsequent chunk/end calls.
+ StartStream(ctx context.Context, incoming *IncomingMessage) (string, error)
+
+ // SendStreamChunk appends a content chunk to an ongoing stream.
+ SendStreamChunk(ctx context.Context, incoming *IncomingMessage, streamID string, content string) error
+
+ // EndStream finalizes a streaming reply.
+ EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error
+}
diff --git a/internal/im/feishu/adapter.go b/internal/im/feishu/adapter.go
index ac5906fe..7b1ba5ed 100644
--- a/internal/im/feishu/adapter.go
+++ b/internal/im/feishu/adapter.go
@@ -29,6 +29,9 @@ import (
"github.com/gin-gonic/gin"
)
+// Compile-time check that Adapter implements im.StreamSender.
+var _ im.StreamSender = (*Adapter)(nil)
+
var httpClient = &http.Client{Timeout: 10 * time.Second}
// Adapter implements im.Adapter for Feishu/Lark.
@@ -324,6 +327,329 @@ func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, r
return nil
}
+// ──────────────────────────────────────────────────────────────────────
+// Feishu CardKit v1 streaming implementation (official best practice)
+//
+// Flow:
+// 1. POST /cardkit/v1/cards — create card entity
+// 2. POST /im/v1/messages content={"type":"card","data":{"card_id":"…"}} — send card
+// 3. PUT /cardkit/v1/cards/{id}/elements/{eid}/content — stream element content
+// 4. PATCH /cardkit/v1/cards/{id}/settings — set streaming_mode=false
+//
+// Reference: https://github.com/larksuite/openclaw-lark (official Lark plugin)
+// https://open.feishu.cn/document/cardkit-v1/streaming-updates-openapi-overview
+// ──────────────────────────────────────────────────────────────────────
+
+const (
+ // streamingElementID is the element_id used in the card JSON for streaming content.
+ streamingElementID = "streaming_content"
+)
+
+// feishuStreamState tracks per-stream accumulated content.
+type feishuStreamState struct {
+ mu sync.Mutex
+ content strings.Builder
+ seq int64 // strictly incrementing sequence for CardKit API
+}
+
+var (
+ feishuStreamsMu sync.Mutex
+ feishuStreams = map[string]*feishuStreamState{}
+)
+
+func (s *feishuStreamState) nextSeq() int {
+ s.seq++
+ return int(s.seq)
+}
+
+// buildStreamingCardJSON builds a Card JSON 2.0 with streaming_mode enabled.
+func buildStreamingCardJSON() string {
+ card := map[string]interface{}{
+ "schema": "2.0",
+ "config": map[string]interface{}{
+ "streaming_mode": true,
+ "summary": map[string]string{"content": "正在思考..."},
+ },
+ "header": map[string]interface{}{
+ "template": "blue",
+ "title": map[string]string{"tag": "plain_text", "content": "WeKnora"},
+ },
+ "body": map[string]interface{}{
+ "elements": []map[string]interface{}{
+ {
+ "tag": "markdown",
+ "content": "",
+ "text_size": "normal",
+ "element_id": streamingElementID,
+ },
+ },
+ },
+ }
+ b, _ := json.Marshal(card)
+ return string(b)
+}
+
+// StartStream creates a CardKit card entity, sends it as a message, and returns the card_id.
+func (a *Adapter) StartStream(ctx context.Context, incoming *im.IncomingMessage) (string, error) {
+ accessToken, err := a.getTenantAccessToken(ctx)
+ if err != nil {
+ return "", fmt.Errorf("get access token: %w", err)
+ }
+
+ // 1. Create card entity via CardKit API
+ cardJSON := buildStreamingCardJSON()
+ cardID, err := a.cardkitCreate(ctx, accessToken, cardJSON)
+ if err != nil {
+ return "", fmt.Errorf("create card: %w", err)
+ }
+
+ // 2. Send the card as a message (content type="card")
+ if err := a.sendCardByCardID(ctx, accessToken, incoming, cardID); err != nil {
+ return "", fmt.Errorf("send card message: %w", err)
+ }
+
+ // 3. Track stream state
+ feishuStreamsMu.Lock()
+ feishuStreams[cardID] = &feishuStreamState{}
+ feishuStreamsMu.Unlock()
+
+ logger.Infof(ctx, "[Feishu] Streaming started: card_id=%s", cardID)
+ return cardID, nil
+}
+
+// SendStreamChunk accumulates content and pushes it to the card element.
+func (a *Adapter) SendStreamChunk(ctx context.Context, incoming *im.IncomingMessage, streamID string, content string) error {
+ if content == "" {
+ return nil
+ }
+
+ feishuStreamsMu.Lock()
+ state, ok := feishuStreams[streamID]
+ feishuStreamsMu.Unlock()
+ if !ok {
+ return fmt.Errorf("unknown stream ID: %s", streamID)
+ }
+
+ state.mu.Lock()
+ state.content.WriteString(content)
+ fullContent := state.content.String()
+ seq := state.nextSeq()
+ state.mu.Unlock()
+
+ accessToken, err := a.getTenantAccessToken(ctx)
+ if err != nil {
+ return fmt.Errorf("get access token: %w", err)
+ }
+
+ return a.cardkitUpdateElement(ctx, accessToken, streamID, streamingElementID, fullContent, seq)
+}
+
+// EndStream disables streaming_mode and cleans up state.
+func (a *Adapter) EndStream(ctx context.Context, incoming *im.IncomingMessage, streamID string) error {
+ feishuStreamsMu.Lock()
+ state, ok := feishuStreams[streamID]
+ delete(feishuStreams, streamID)
+ feishuStreamsMu.Unlock()
+
+ accessToken, err := a.getTenantAccessToken(ctx)
+ if err != nil {
+ return fmt.Errorf("get access token: %w", err)
+ }
+
+ var seq int
+ if ok {
+ state.mu.Lock()
+ seq = state.nextSeq()
+ state.mu.Unlock()
+ }
+
+ // Turn off streaming_mode to remove loading indicator
+ if err := a.cardkitSetStreaming(ctx, accessToken, streamID, false, seq); err != nil {
+ logger.Warnf(ctx, "[Feishu] Failed to disable streaming_mode: %v", err)
+ }
+
+ logger.Infof(ctx, "[Feishu] Streaming ended: card_id=%s", streamID)
+ return nil
+}
+
+// ── CardKit v1 API helpers ──
+
+// cardkitCreate creates a card entity and returns the card_id.
+// POST /open-apis/cardkit/v1/cards
+func (a *Adapter) cardkitCreate(ctx context.Context, accessToken, cardJSON string) (string, error) {
+ payload, _ := json.Marshal(map[string]interface{}{
+ "type": "card_json",
+ "data": cardJSON,
+ })
+
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+ "https://open.feishu.cn/open-apis/cardkit/v1/cards", bytes.NewReader(payload))
+ if err != nil {
+ return "", err
+ }
+ req.Header.Set("Content-Type", "application/json; charset=utf-8")
+ req.Header.Set("Authorization", "Bearer "+accessToken)
+
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return "", err
+ }
+ defer resp.Body.Close()
+
+ respBody, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return "", fmt.Errorf("read response: %w", err)
+ }
+
+ var result struct {
+ Code int `json:"code"`
+ Msg string `json:"msg"`
+ Data json.RawMessage `json:"data"`
+ }
+ if err := json.Unmarshal(respBody, &result); err != nil {
+ return "", fmt.Errorf("decode: %w (body: %s)", err, string(respBody))
+ }
+ if result.Code != 0 {
+ return "", fmt.Errorf("code=%d msg=%s", result.Code, result.Msg)
+ }
+
+ var data struct {
+ CardID string `json:"card_id"`
+ }
+ if err := json.Unmarshal(result.Data, &data); err != nil {
+ return "", fmt.Errorf("parse card_id: %w (raw: %s)", err, string(result.Data))
+ }
+ return data.CardID, nil
+}
+
+// sendCardByCardID sends a card_id as an interactive message.
+// POST /open-apis/im/v1/messages with content={"type":"card","data":{"card_id":"…"}}
+func (a *Adapter) sendCardByCardID(ctx context.Context, accessToken string, incoming *im.IncomingMessage, cardID string) error {
+ receiveIDType := "open_id"
+ receiveID := incoming.UserID
+ if incoming.ChatType == im.ChatTypeGroup && incoming.ChatID != "" {
+ receiveIDType = "chat_id"
+ receiveID = incoming.ChatID
+ }
+
+ // Key: type must be "card" (not "card_id")
+ content, _ := json.Marshal(map[string]interface{}{
+ "type": "card",
+ "data": map[string]string{"card_id": cardID},
+ })
+
+ payload, _ := json.Marshal(map[string]interface{}{
+ "receive_id": receiveID,
+ "msg_type": "interactive",
+ "content": string(content),
+ })
+
+ apiURL := fmt.Sprintf("https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=%s", receiveIDType)
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(payload))
+ if err != nil {
+ return err
+ }
+ req.Header.Set("Content-Type", "application/json; charset=utf-8")
+ req.Header.Set("Authorization", "Bearer "+accessToken)
+
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+
+ respBody, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return fmt.Errorf("read response: %w", err)
+ }
+
+ var result struct {
+ Code int `json:"code"`
+ Msg string `json:"msg"`
+ }
+ if err := json.Unmarshal(respBody, &result); err != nil {
+ return fmt.Errorf("decode: %w (body: %s)", err, string(respBody))
+ }
+ if result.Code != 0 {
+ return fmt.Errorf("send card error: code=%d msg=%s", result.Code, result.Msg)
+ }
+ return nil
+}
+
+// cardkitUpdateElement updates a card element's content for streaming.
+// PUT /open-apis/cardkit/v1/cards/:card_id/elements/:element_id/content
+func (a *Adapter) cardkitUpdateElement(ctx context.Context, accessToken, cardID, elementID, content string, sequence int) error {
+ payload, _ := json.Marshal(map[string]interface{}{
+ "content": content,
+ "sequence": sequence,
+ })
+
+ apiURL := fmt.Sprintf("https://open.feishu.cn/open-apis/cardkit/v1/cards/%s/elements/%s/content",
+ cardID, elementID)
+ req, err := http.NewRequestWithContext(ctx, http.MethodPut, apiURL, bytes.NewReader(payload))
+ if err != nil {
+ return err
+ }
+ req.Header.Set("Content-Type", "application/json; charset=utf-8")
+ req.Header.Set("Authorization", "Bearer "+accessToken)
+
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+
+ var result struct {
+ Code int `json:"code"`
+ Msg string `json:"msg"`
+ }
+ if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+ return fmt.Errorf("decode: %w", err)
+ }
+ if result.Code != 0 {
+ return fmt.Errorf("update element error: code=%d msg=%s", result.Code, result.Msg)
+ }
+ return nil
+}
+
+// cardkitSetStreaming updates the card's streaming_mode setting.
+// PATCH /open-apis/cardkit/v1/cards/:card_id/settings
+func (a *Adapter) cardkitSetStreaming(ctx context.Context, accessToken, cardID string, streaming bool, sequence int) error {
+ settings, _ := json.Marshal(map[string]interface{}{
+ "streaming_mode": streaming,
+ })
+ payload, _ := json.Marshal(map[string]interface{}{
+ "settings": string(settings),
+ "sequence": sequence,
+ })
+
+ apiURL := fmt.Sprintf("https://open.feishu.cn/open-apis/cardkit/v1/cards/%s/settings", cardID)
+ req, err := http.NewRequestWithContext(ctx, http.MethodPatch, apiURL, bytes.NewReader(payload))
+ if err != nil {
+ return err
+ }
+ req.Header.Set("Content-Type", "application/json; charset=utf-8")
+ req.Header.Set("Authorization", "Bearer "+accessToken)
+
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+
+ var result struct {
+ Code int `json:"code"`
+ Msg string `json:"msg"`
+ }
+ if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+ return fmt.Errorf("decode: %w", err)
+ }
+ if result.Code != 0 {
+ return fmt.Errorf("set streaming error: code=%d msg=%s", result.Code, result.Msg)
+ }
+ return nil
+}
+
// getTenantAccessToken retrieves the Feishu tenant access token with caching.
// Feishu tokens expire in 2 hours; we cache with a safety margin.
func (a *Adapter) getTenantAccessToken(ctx context.Context) (string, error) {
diff --git a/internal/im/service.go b/internal/im/service.go
index 6fff47d0..f7b39fc2 100644
--- a/internal/im/service.go
+++ b/internal/im/service.go
@@ -24,6 +24,9 @@ const (
dedupCleanupInterval = 1 * time.Minute
// maxContentLength is the maximum allowed message content length.
maxContentLength = 4096
+ // streamFlushInterval is how often buffered stream content is flushed to the IM platform.
+ // This prevents API rate-limiting while keeping perceived latency low.
+ streamFlushInterval = 300 * time.Millisecond
)
// Service orchestrates IM message handling:
@@ -44,6 +47,9 @@ type Service struct {
// processedMsgs tracks recently processed message IDs to prevent duplicate handling.
processedMsgs sync.Map
+ // streamDisabled tracks platforms where streaming is explicitly disabled via output_mode config.
+ streamDisabled map[Platform]bool
+
stopCh chan struct{}
}
@@ -62,6 +68,7 @@ func NewService(
tenantService: tenantService,
agentService: agentService,
adapters: make(map[Platform]Adapter),
+ streamDisabled: make(map[Platform]bool),
stopCh: make(chan struct{}),
}
@@ -103,6 +110,15 @@ func (s *Service) RegisterAdapter(adapter Adapter) {
s.adapters[adapter.Platform()] = adapter
}
+// SetStreamDisabled disables streaming output for a specific platform.
+// When disabled, the service will always collect the full answer before sending,
+// even if the adapter implements StreamSender.
+func (s *Service) SetStreamDisabled(platform Platform, disabled bool) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.streamDisabled[platform] = disabled
+}
+
// GetAdapter returns the adapter for a given platform.
func (s *Service) GetAdapter(platform Platform) (Adapter, bool) {
s.mu.RLock()
@@ -163,19 +179,30 @@ func (s *Service) HandleMessage(ctx context.Context, msg *IncomingMessage, tenan
}
}
- // 5. Run the QA pipeline and collect the full answer
+ // 5. Get the platform adapter
+ adapter, ok := s.GetAdapter(msg.Platform)
+ if !ok {
+ return fmt.Errorf("no adapter for platform: %s", msg.Platform)
+ }
+
+ // 6. If the adapter supports streaming and streaming is not disabled, use streaming mode;
+ // otherwise collect full answer.
+ s.mu.RLock()
+ disabled := s.streamDisabled[msg.Platform]
+ s.mu.RUnlock()
+ if !disabled {
+ if streamer, ok := adapter.(StreamSender); ok {
+ return s.handleMessageStream(sessionCtx, msg, session, customAgent, kbIDs, streamer)
+ }
+ }
+
+ // Non-streaming fallback: collect full answer then send
answer, err := s.runQA(sessionCtx, session, msg.Content, customAgent, kbIDs)
if err != nil {
logger.Errorf(ctx, "[IM] QA failed: %v, sending fallback reply", err)
answer = "抱歉,处理您的问题时出现了异常,请稍后再试。"
}
- // 6. Send the reply back via the platform adapter
- adapter, ok := s.GetAdapter(msg.Platform)
- if !ok {
- return fmt.Errorf("no adapter for platform: %s", msg.Platform)
- }
-
reply := &ReplyMessage{
Content: answer,
IsFinal: true,
@@ -249,6 +276,202 @@ func (s *Service) resolveSession(ctx context.Context, msg *IncomingMessage, tena
return &cs, nil
}
+// handleMessageStream runs the QA pipeline and streams answer chunks to the IM platform
+// in real-time via the StreamSender interface. Chunks are batched at streamFlushInterval
+// to avoid API rate-limiting.
+func (s *Service) handleMessageStream(ctx context.Context, msg *IncomingMessage, session *types.Session, customAgent *types.CustomAgent, kbIDs []string, streamer StreamSender) error {
+ // Start the stream on the IM platform (e.g., create Feishu streaming card)
+ streamID, err := streamer.StartStream(ctx, msg)
+ if err != nil {
+ logger.Warnf(ctx, "[IM] StartStream failed, falling back to non-streaming: %v", err)
+ return s.fallbackNonStream(ctx, msg, session, customAgent, kbIDs)
+ }
+
+ // Prepare the QA pipeline
+ qaCtx, qaCancel := context.WithTimeout(ctx, qaTimeout)
+ defer qaCancel()
+
+ eventBus := event.NewEventBus()
+
+ var (
+ bufMu sync.Mutex
+ buf strings.Builder // buffered content awaiting flush (answer only)
+ answerBuilder strings.Builder // full answer for DB persistence (includes )
+ qaErr error
+ done = make(chan struct{})
+ closeOnce sync.Once
+ inThinking bool // tracks whether we're inside a block
+ )
+ closeDone := func() { closeOnce.Do(func() { close(done) }) }
+
+ // Subscribe to answer chunks
+ eventBus.On(event.EventAgentFinalAnswer, func(_ context.Context, evt event.Event) error {
+ data, ok := evt.Data.(event.AgentFinalAnswerData)
+ if !ok {
+ return nil
+ }
+
+ bufMu.Lock()
+ // Always persist the full content (including thinking)
+ answerBuilder.WriteString(data.Content)
+
+ // Filter ... blocks from the streamed output.
+ // The pipeline emits: ..chunks.. then answer chunks.
+ content := data.Content
+ if !inThinking {
+ if strings.HasPrefix(content, "") {
+ inThinking = true
+ content = "" // skip this chunk for streaming
+ }
+ }
+ if inThinking {
+ if idx := strings.Index(content, ""); idx >= 0 {
+ inThinking = false
+ // Keep anything after
+ content = strings.TrimSpace(content[idx+len(""):])
+ } else {
+ content = "" // still inside thinking block
+ }
+ }
+
+ if content != "" {
+ buf.WriteString(content)
+ }
+ bufMu.Unlock()
+
+ if data.Done {
+ closeDone()
+ }
+ return nil
+ })
+
+ eventBus.On(event.EventError, func(_ context.Context, evt event.Event) error {
+ data, ok := evt.Data.(event.ErrorData)
+ if !ok {
+ return nil
+ }
+ logger.Errorf(ctx, "[IM] QA stream error: %s", data.Error)
+ bufMu.Lock()
+ qaErr = fmt.Errorf("QA pipeline error: %s", data.Error)
+ bufMu.Unlock()
+ closeDone()
+ return nil
+ })
+
+ // Determine whether to use agent mode
+ useAgent := customAgent != nil && customAgent.IsAgentMode()
+ requestID := uuid.New().String()
+
+ // Create user message
+ if _, err := s.messageService.CreateMessage(qaCtx, &types.Message{
+ SessionID: session.ID, Role: "user", Content: msg.Content,
+ RequestID: requestID, CreatedAt: time.Now(), IsCompleted: true,
+ }); err != nil {
+ return fmt.Errorf("create user message: %w", err)
+ }
+
+ // Create placeholder assistant message
+ assistantMsg, err := s.messageService.CreateMessage(qaCtx, &types.Message{
+ SessionID: session.ID, Role: "assistant",
+ RequestID: requestID, CreatedAt: time.Now(), IsCompleted: false,
+ })
+ if err != nil {
+ return fmt.Errorf("create assistant message: %w", err)
+ }
+
+ // Run QA async
+ go func() {
+ var err error
+ if useAgent {
+ err = s.sessionService.AgentQA(qaCtx, session, msg.Content, assistantMsg.ID, "", eventBus, customAgent, kbIDs, nil)
+ } else {
+ err = s.sessionService.KnowledgeQA(qaCtx, session, msg.Content, kbIDs, nil, assistantMsg.ID, "", false, eventBus, customAgent, false)
+ }
+ if err != nil {
+ logger.Errorf(ctx, "[IM] QA stream execution error: %v", err)
+ bufMu.Lock()
+ qaErr = fmt.Errorf("QA execution error: %w", err)
+ bufMu.Unlock()
+ closeDone()
+ }
+ }()
+
+ // Flush loop: periodically send buffered content to the IM platform
+ ticker := time.NewTicker(streamFlushInterval)
+ defer ticker.Stop()
+
+ flush := func() {
+ bufMu.Lock()
+ chunk := buf.String()
+ buf.Reset()
+ bufMu.Unlock()
+
+ if chunk != "" {
+ if err := streamer.SendStreamChunk(ctx, msg, streamID, chunk); err != nil {
+ logger.Warnf(ctx, "[IM] SendStreamChunk failed: %v", err)
+ }
+ }
+ }
+
+loop:
+ for {
+ select {
+ case <-ticker.C:
+ flush()
+ case <-done:
+ break loop
+ case <-qaCtx.Done():
+ break loop
+ }
+ }
+
+ // Final flush of any remaining content
+ flush()
+
+ // End the stream
+ if err := streamer.EndStream(ctx, msg, streamID); err != nil {
+ logger.Warnf(ctx, "[IM] EndStream failed: %v", err)
+ }
+
+ // Persist the full answer
+ bufMu.Lock()
+ answer := answerBuilder.String()
+ finalErr := qaErr
+ bufMu.Unlock()
+
+ if answer == "" && finalErr != nil {
+ answer = "抱歉,处理您的问题时出现了异常,请稍后再试。"
+ }
+ if answer == "" {
+ answer = "抱歉,我暂时无法回答这个问题。"
+ }
+
+ assistantMsg.Content = answer
+ assistantMsg.IsCompleted = true
+ if err := s.messageService.UpdateMessage(ctx, assistantMsg); err != nil {
+ logger.Warnf(ctx, "[IM] Failed to update assistant message: %v", err)
+ }
+
+ logger.Infof(ctx, "[IM] Stream reply sent: platform=%s user=%s answer_len=%d", msg.Platform, msg.UserID, len(answer))
+ return nil
+}
+
+// fallbackNonStream is used when streaming initialization fails.
+func (s *Service) fallbackNonStream(ctx context.Context, msg *IncomingMessage, session *types.Session, customAgent *types.CustomAgent, kbIDs []string) error {
+ answer, err := s.runQA(ctx, session, msg.Content, customAgent, kbIDs)
+ if err != nil {
+ logger.Errorf(ctx, "[IM] QA fallback failed: %v", err)
+ answer = "抱歉,处理您的问题时出现了异常,请稍后再试。"
+ }
+
+ adapter, ok := s.GetAdapter(msg.Platform)
+ if !ok {
+ return fmt.Errorf("no adapter for platform: %s", msg.Platform)
+ }
+
+ return adapter.SendReply(ctx, msg, &ReplyMessage{Content: answer, IsFinal: true})
+}
+
// runQA executes the WeKnora QA pipeline and returns the full answer text.
func (s *Service) runQA(ctx context.Context, session *types.Session, query string, customAgent *types.CustomAgent, kbIDs []string) (string, error) {
// Add timeout to prevent indefinite blocking
diff --git a/internal/im/stream_test.go b/internal/im/stream_test.go
new file mode 100644
index 00000000..583860af
--- /dev/null
+++ b/internal/im/stream_test.go
@@ -0,0 +1,143 @@
+package im
+
+import (
+ "context"
+ "sync"
+ "testing"
+ "time"
+)
+
+// mockStreamSender is a test double that records streaming calls.
+type mockStreamSender struct {
+ mu sync.Mutex
+ started bool
+ streamID string
+ chunks []string
+ ended bool
+}
+
+func (m *mockStreamSender) StartStream(_ context.Context, _ *IncomingMessage) (string, error) {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ m.started = true
+ m.streamID = "test-stream-1"
+ return m.streamID, nil
+}
+
+func (m *mockStreamSender) SendStreamChunk(_ context.Context, _ *IncomingMessage, _ string, content string) error {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ m.chunks = append(m.chunks, content)
+ return nil
+}
+
+func (m *mockStreamSender) EndStream(_ context.Context, _ *IncomingMessage, _ string) error {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ m.ended = true
+ return nil
+}
+
+func (m *mockStreamSender) getChunks() []string {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ out := make([]string, len(m.chunks))
+ copy(out, m.chunks)
+ return out
+}
+
+func TestStreamSenderInterface(t *testing.T) {
+ mock := &mockStreamSender{}
+
+ ctx := context.Background()
+ incoming := &IncomingMessage{
+ Platform: PlatformFeishu,
+ UserID: "test-user",
+ Content: "hello",
+ }
+
+ // Start stream
+ streamID, err := mock.StartStream(ctx, incoming)
+ if err != nil {
+ t.Fatalf("StartStream failed: %v", err)
+ }
+ if streamID == "" {
+ t.Fatal("expected non-empty stream ID")
+ }
+
+ // Send chunks
+ chunks := []string{"Hello", ", ", "world", "!"}
+ for _, c := range chunks {
+ if err := mock.SendStreamChunk(ctx, incoming, streamID, c); err != nil {
+ t.Fatalf("SendStreamChunk failed: %v", err)
+ }
+ }
+
+ // End stream
+ if err := mock.EndStream(ctx, incoming, streamID); err != nil {
+ t.Fatalf("EndStream failed: %v", err)
+ }
+
+ // Verify
+ if !mock.started {
+ t.Error("expected stream to be started")
+ }
+ if !mock.ended {
+ t.Error("expected stream to be ended")
+ }
+
+ got := mock.getChunks()
+ if len(got) != len(chunks) {
+ t.Fatalf("expected %d chunks, got %d", len(chunks), len(got))
+ }
+ for i, want := range chunks {
+ if got[i] != want {
+ t.Errorf("chunk[%d] = %q, want %q", i, got[i], want)
+ }
+ }
+}
+
+func TestStreamFlushBatching(t *testing.T) {
+ // Simulate the batching behavior: multiple writes within one flush interval
+ // should be combined into a single chunk.
+ mock := &mockStreamSender{}
+
+ ctx := context.Background()
+ incoming := &IncomingMessage{
+ Platform: PlatformFeishu,
+ UserID: "test-user",
+ Content: "test",
+ }
+
+ streamID, _ := mock.StartStream(ctx, incoming)
+
+ // Simulate buffer: accumulate content then flush as one chunk
+ var buf string
+ tokens := []string{"Hello", " ", "world", "!"}
+ for _, tok := range tokens {
+ buf += tok
+ }
+
+ // Single flush
+ if err := mock.SendStreamChunk(ctx, incoming, streamID, buf); err != nil {
+ t.Fatalf("SendStreamChunk failed: %v", err)
+ }
+
+ got := mock.getChunks()
+ if len(got) != 1 {
+ t.Fatalf("expected 1 batched chunk, got %d", len(got))
+ }
+ if got[0] != "Hello world!" {
+ t.Errorf("batched chunk = %q, want %q", got[0], "Hello world!")
+ }
+}
+
+func TestStreamFlushIntervalConstant(t *testing.T) {
+ // Verify the flush interval is set to a reasonable value
+ if streamFlushInterval < 100*time.Millisecond {
+ t.Errorf("streamFlushInterval too small: %v (may cause API rate limiting)", streamFlushInterval)
+ }
+ if streamFlushInterval > 2*time.Second {
+ t.Errorf("streamFlushInterval too large: %v (poor user experience)", streamFlushInterval)
+ }
+}
diff --git a/internal/im/wecom/bot_adapter.go b/internal/im/wecom/bot_adapter.go
deleted file mode 100644
index eccd6911..00000000
--- a/internal/im/wecom/bot_adapter.go
+++ /dev/null
@@ -1,42 +0,0 @@
-package wecom
-
-import (
- "context"
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/im"
- "github.com/gin-gonic/gin"
-)
-
-// BotAdapter implements im.Adapter for WeCom intelligent bot (long connection mode).
-// It delegates SendReply to the WebSocket LongConnClient.
-// The webhook methods (VerifyCallback, ParseCallback, HandleURLVerification) are no-ops
-// since messages arrive via WebSocket, not HTTP.
-type BotAdapter struct {
- client *LongConnClient
-}
-
-// NewBotAdapter creates an adapter backed by a WeCom long connection client.
-func NewBotAdapter(client *LongConnClient) *BotAdapter {
- return &BotAdapter{client: client}
-}
-
-func (a *BotAdapter) Platform() im.Platform {
- return im.PlatformWeCom
-}
-
-func (a *BotAdapter) VerifyCallback(c *gin.Context) error {
- return fmt.Errorf("WeCom bot adapter does not support webhook callbacks")
-}
-
-func (a *BotAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) {
- return nil, fmt.Errorf("WeCom bot adapter does not support webhook callbacks")
-}
-
-func (a *BotAdapter) HandleURLVerification(c *gin.Context) bool {
- return false
-}
-
-func (a *BotAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error {
- return a.client.SendReply(ctx, incoming, reply)
-}
diff --git a/internal/im/wecom/longconn.go b/internal/im/wecom/longconn.go
index df04ee9c..b7bd35a9 100644
--- a/internal/im/wecom/longconn.go
+++ b/internal/im/wecom/longconn.go
@@ -89,6 +89,12 @@ type LongConnClient struct {
mu sync.Mutex
closed atomic.Bool
reqSeq atomic.Int64
+
+ // streamBufs tracks accumulated content per stream ID.
+ // WeCom stream protocol is replace-based: each frame's content replaces
+ // the previously displayed text, so we must send the full accumulated text.
+ streamBufsMu sync.Mutex
+ streamBufs map[string]*strings.Builder
}
// NewLongConnClient creates a WeCom long connection client.
@@ -175,6 +181,86 @@ func (c *LongConnClient) SendReply(ctx context.Context, incoming *im.IncomingMes
return c.writeJSON(frame)
}
+// ──────────────────────────────────────────────────────────────────────
+// Streaming support: send answer chunks over WebSocket in real-time
+// ──────────────────────────────────────────────────────────────────────
+
+// StartStream begins a streaming reply session.
+// Returns a stream ID that must be used in subsequent chunk/end calls.
+func (c *LongConnClient) StartStream(ctx context.Context, incoming *im.IncomingMessage) (string, error) {
+ if _, ok := incoming.Extra["req_id"]; !ok {
+ return "", fmt.Errorf("missing req_id in incoming message extra")
+ }
+ streamID := fmt.Sprintf("stream_%d", c.reqSeq.Add(1))
+
+ // Initialize the accumulation buffer for this stream
+ c.streamBufsMu.Lock()
+ if c.streamBufs == nil {
+ c.streamBufs = make(map[string]*strings.Builder)
+ }
+ c.streamBufs[streamID] = &strings.Builder{}
+ c.streamBufsMu.Unlock()
+
+ return streamID, nil
+}
+
+// SendStreamChunk accumulates the content and sends the full text so far.
+// WeCom stream protocol is replace-based: each frame replaces the previous display.
+func (c *LongConnClient) SendStreamChunk(ctx context.Context, incoming *im.IncomingMessage, streamID string, content string) error {
+ if content == "" {
+ return nil
+ }
+
+ // Accumulate
+ c.streamBufsMu.Lock()
+ buf, ok := c.streamBufs[streamID]
+ if !ok {
+ c.streamBufsMu.Unlock()
+ return fmt.Errorf("unknown stream ID: %s", streamID)
+ }
+ buf.WriteString(content)
+ fullContent := buf.String()
+ c.streamBufsMu.Unlock()
+
+ return c.sendStreamFrame(incoming, streamID, fullContent, false)
+}
+
+// EndStream sends the final frame with the full accumulated content and cleans up.
+func (c *LongConnClient) EndStream(ctx context.Context, incoming *im.IncomingMessage, streamID string) error {
+ c.streamBufsMu.Lock()
+ buf, ok := c.streamBufs[streamID]
+ var fullContent string
+ if ok {
+ fullContent = buf.String()
+ delete(c.streamBufs, streamID)
+ }
+ c.streamBufsMu.Unlock()
+
+ return c.sendStreamFrame(incoming, streamID, fullContent, true)
+}
+
+func (c *LongConnClient) sendStreamFrame(incoming *im.IncomingMessage, streamID, content string, finish bool) error {
+ reqID := incoming.Extra["req_id"]
+
+ body := streamReplyBody{MsgType: "stream"}
+ body.Stream.ID = streamID
+ body.Stream.Finish = finish
+ body.Stream.Content = content
+
+ bodyBytes, err := json.Marshal(body)
+ if err != nil {
+ return fmt.Errorf("marshal stream body: %w", err)
+ }
+
+ frame := wsFrame{
+ Cmd: cmdResponse,
+ Headers: map[string]string{"req_id": reqID},
+ Body: bodyBytes,
+ }
+
+ return c.writeJSON(frame)
+}
+
func (c *LongConnClient) connectAndRun(ctx context.Context) error {
conn, _, err := ws.DefaultDialer.DialContext(ctx, wecomWSEndpoint, nil)
if err != nil {
diff --git a/internal/im/wecom/adapter.go b/internal/im/wecom/webhook_adapter.go
similarity index 90%
rename from internal/im/wecom/adapter.go
rename to internal/im/wecom/webhook_adapter.go
index 98062dc4..e0f4aaf1 100644
--- a/internal/im/wecom/adapter.go
+++ b/internal/im/wecom/webhook_adapter.go
@@ -35,8 +35,9 @@ import (
var httpClient = &http.Client{Timeout: 10 * time.Second}
-// Adapter implements im.Adapter for WeCom.
-type Adapter struct {
+// WebhookAdapter implements im.Adapter for WeCom in webhook (self-built app callback) mode.
+// Messages arrive via HTTP callback; replies are sent via the WeCom REST API.
+type WebhookAdapter struct {
corpID string
token string
encodingAESKey string
@@ -50,15 +51,15 @@ type Adapter struct {
tokenExpAt time.Time
}
-// NewAdapter creates a new WeCom adapter.
-func NewAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID int) (*Adapter, error) {
+// NewWebhookAdapter creates a new WeCom webhook adapter.
+func NewWebhookAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID int) (*WebhookAdapter, error) {
// Decode the AES key from base64
aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
if err != nil {
return nil, fmt.Errorf("decode encoding_aes_key: %w", err)
}
- return &Adapter{
+ return &WebhookAdapter{
corpID: corpID,
token: token,
encodingAESKey: encodingAESKey,
@@ -69,12 +70,12 @@ func NewAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID i
}
// Platform returns the platform identifier.
-func (a *Adapter) Platform() im.Platform {
+func (a *WebhookAdapter) Platform() im.Platform {
return im.PlatformWeCom
}
// VerifyCallback verifies the WeCom callback signature.
-func (a *Adapter) VerifyCallback(c *gin.Context) error {
+func (a *WebhookAdapter) VerifyCallback(c *gin.Context) error {
timestamp := c.Query("timestamp")
nonce := c.Query("nonce")
msgSignature := c.Query("msg_signature")
@@ -105,7 +106,7 @@ func (a *Adapter) VerifyCallback(c *gin.Context) error {
}
// HandleURLVerification handles the WeCom URL verification (GET request).
-func (a *Adapter) HandleURLVerification(c *gin.Context) bool {
+func (a *WebhookAdapter) HandleURLVerification(c *gin.Context) bool {
if c.Request.Method != http.MethodGet {
return false
}
@@ -128,7 +129,7 @@ func (a *Adapter) HandleURLVerification(c *gin.Context) bool {
}
// ParseCallback parses a WeCom callback into a unified IncomingMessage.
-func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) {
+func (a *WebhookAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) {
bodyBytes, err := io.ReadAll(c.Request.Body)
if err != nil {
return nil, fmt.Errorf("read body: %w", err)
@@ -181,7 +182,7 @@ func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) {
// SendReply sends a reply message via WeCom API.
// For simplicity, this uses the "应用消息" API to proactively send messages.
// A production implementation would integrate with the streaming callback model.
-func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error {
+func (a *WebhookAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error {
// Get access token
accessToken, err := a.getAccessToken(ctx)
if err != nil {
@@ -235,7 +236,7 @@ func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, r
// getAccessToken retrieves the WeCom access token with caching.
// WeCom tokens expire in 7200 seconds (2 hours); we cache with a safety margin.
-func (a *Adapter) getAccessToken(ctx context.Context) (string, error) {
+func (a *WebhookAdapter) getAccessToken(ctx context.Context) (string, error) {
a.tokenMu.Lock()
defer a.tokenMu.Unlock()
@@ -282,7 +283,7 @@ func (a *Adapter) getAccessToken(ctx context.Context) (string, error) {
}
// verifySignature verifies the WeCom callback signature using constant-time comparison.
-func (a *Adapter) verifySignature(signature, timestamp, nonce, encrypt string) bool {
+func (a *WebhookAdapter) verifySignature(signature, timestamp, nonce, encrypt string) bool {
parts := []string{a.token, timestamp, nonce, encrypt}
sort.Strings(parts)
combined := strings.Join(parts, "")
@@ -295,7 +296,7 @@ func (a *Adapter) verifySignature(signature, timestamp, nonce, encrypt string) b
}
// decrypt decrypts a WeCom AES-encrypted message.
-func (a *Adapter) decrypt(encrypted string) ([]byte, error) {
+func (a *WebhookAdapter) decrypt(encrypted string) ([]byte, error) {
ciphertext, err := base64.StdEncoding.DecodeString(encrypted)
if err != nil {
return nil, fmt.Errorf("base64 decode: %w", err)
diff --git a/internal/im/wecom/ws_adapter.go b/internal/im/wecom/ws_adapter.go
new file mode 100644
index 00000000..4040b9e6
--- /dev/null
+++ b/internal/im/wecom/ws_adapter.go
@@ -0,0 +1,62 @@
+package wecom
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/Tencent/WeKnora/internal/im"
+ "github.com/gin-gonic/gin"
+)
+
+// Compile-time checks.
+var (
+ _ im.Adapter = (*WSAdapter)(nil)
+ _ im.StreamSender = (*WSAdapter)(nil)
+)
+
+// WSAdapter implements im.Adapter and im.StreamSender for WeCom in WebSocket
+// (long connection) mode. It delegates to the WebSocket LongConnClient.
+// The webhook methods (VerifyCallback, ParseCallback, HandleURLVerification) are no-ops
+// since messages arrive via WebSocket, not HTTP.
+type WSAdapter struct {
+ client *LongConnClient
+}
+
+// NewWSAdapter creates an adapter backed by a WeCom long connection client.
+func NewWSAdapter(client *LongConnClient) *WSAdapter {
+ return &WSAdapter{client: client}
+}
+
+func (a *WSAdapter) Platform() im.Platform {
+ return im.PlatformWeCom
+}
+
+func (a *WSAdapter) VerifyCallback(c *gin.Context) error {
+ return fmt.Errorf("WeCom bot adapter does not support webhook callbacks")
+}
+
+func (a *WSAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) {
+ return nil, fmt.Errorf("WeCom bot adapter does not support webhook callbacks")
+}
+
+func (a *WSAdapter) HandleURLVerification(c *gin.Context) bool {
+ return false
+}
+
+func (a *WSAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error {
+ return a.client.SendReply(ctx, incoming, reply)
+}
+
+// ── StreamSender implementation ──
+
+func (a *WSAdapter) StartStream(ctx context.Context, incoming *im.IncomingMessage) (string, error) {
+ return a.client.StartStream(ctx, incoming)
+}
+
+func (a *WSAdapter) SendStreamChunk(ctx context.Context, incoming *im.IncomingMessage, streamID string, content string) error {
+ return a.client.SendStreamChunk(ctx, incoming, streamID, content)
+}
+
+func (a *WSAdapter) EndStream(ctx context.Context, incoming *im.IncomingMessage, streamID string) error {
+ return a.client.EndStream(ctx, incoming, streamID)
+}