From f16aa128221d8ca30e8fb461a43fc0b6aaf2f65f Mon Sep 17 00:00:00 2001 From: nullkey Date: Sun, 15 Mar 2026 20:42:50 +0800 Subject: [PATCH] feat: enhance IM integration with streaming support and documentation - add StreamSender interface and streaming output for WeCom/Feishu - refactor WeCom adapter into separate webhook and websocket files - add output_mode config for stream/full toggle per platform - add stream flush batching, dedup cleanup, and think-block filtering - improve context template to handle irrelevant retrieved info gracefully - add IM streaming integration tests - add IM integration documentation with quick start guide --- config/config.yaml | 18 +- docs/IM集成开发文档.md | 630 ++++++++++++++++++ internal/config/config.go | 4 + internal/container/container.go | 12 +- internal/im/adapter.go | 15 + internal/im/feishu/adapter.go | 326 +++++++++ internal/im/service.go | 237 ++++++- internal/im/stream_test.go | 143 ++++ internal/im/wecom/bot_adapter.go | 42 -- internal/im/wecom/longconn.go | 86 +++ .../wecom/{adapter.go => webhook_adapter.go} | 27 +- internal/im/wecom/ws_adapter.go | 62 ++ 12 files changed, 1532 insertions(+), 70 deletions(-) create mode 100644 docs/IM集成开发文档.md create mode 100644 internal/im/stream_test.go delete mode 100644 internal/im/wecom/bot_adapter.go rename internal/im/wecom/{adapter.go => webhook_adapter.go} (90%) create mode 100644 internal/im/wecom/ws_adapter.go 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) +}