WeKnora IM 集成完全指南：把 RAG 智能体接入企业微信、飞书、Slack 等 10 个聊天平台

WeKnora IM 集成完全指南：把 RAG 智能体接入企业微信、飞书、Slack 等 10 个聊天平台

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

IM 集成是 WeKnora 将知识库问答与 Agent 能力延伸到即时通讯场景的核心模块：通过「设置 → IM 集成」新建渠道，把某个平台机器人绑定到一个自定义智能体，用户即可在聊天窗口中直接提问，由 WeKnora 执行检索（RAG）或 Agent 推理后回复。本文以 website-docs/03-features/12-im-integration.md 为主线，结合 internal/im 的源码实现，系统讲解平台接入模式、内置命令、群聊/私聊行为、文件消息、回复图片外链、MCP OAuth 授权通知，以及多实例部署下的 Redis 协调机制，帮助读者完成渠道配置、排障与二次开发。

支持的平台与能力对比

internal/handler/im.go中validIMPlatforms定义了 10 个合法平台：wecom、feishu、lark、slack、telegram、dingtalk、mattermost、wechat、qqbot、yunzhijia。非法平台会被拒绝，错误信息由invalidIMPlatformError自动从该集合生成，两者不会漂移。

各平台能力（以各factory.go与 adapter 的编译期断言为准）：

从源码结构看，模式默认值在internal/im/types.go的BeforeCreate钩子中补齐：mattermost/yunzhijia默认webhook，其余默认websocket；wechat由 internal/handler/im.go 强制longpoll+full。

内置命令系统

命令框架位于internal/im/command.go与command_registry.go：命令只声明意图（CommandResult.Action），副作用由 Service 执行。LooksLikeCommand（见command_registry.go）用于区分"命令尝试"（/help）与应透传给 QA 的路径文本（如/api/v2/users）——前者未注册时回复"未知指令"，后者正常进入问答。

NewService中注册的全部命令：

命令注册使用小写 key，重复注册会在启动时 panic（command_registry.go的Register），把配置错误尽早暴露。

群聊与私聊行为

• ChatType由适配器判定：direct（私聊，ChatID为空）或group，常量定义见 internal/im/adapter.go。
• 飞书/Lark：群聊中通常需要 @机器人（长连接订阅到的群消息文本带@_user_N前缀，适配器循环剥除后再处理）；回复时群聊优先走 reply-in-thread（话题回复），若群不支持话题（错误码 230071 等）自动回退普通发消息（adapter.go的 fallback 逻辑）。
• Slack：群聊消息来自AppMentionEvent（@机器人）以及 channel/group 的MessageEvent（过滤BotID非空的机器人消息、非file_share的 subtype）；回复固定发在 thread 中（thread_ts顶层消息用自身时间戳）。
• Telegram：group/supergroup判定为群聊，剥除@botname提及前缀；回复带reply_to_message_id。
• Mattermost：Outgoing Webhook 触发词必须是消息第一个词，否则回调解析为空消息（internal/handler/im.go 中有针对性的排查日志）；post_to_main凭据控制回帖发主频道还是线程。
• 会话隔离：user模式下同一用户在"私聊"与"群 A""群 B"分别是不同ChannelSession（key 含chat_id）；thread模式下同一线程内所有用户共享会话。两种模式常量在adapter.go的SessionMode中定义。

文件消息处理

文件和图片会作为 QA 附件处理：文档内容会提供给模型，图片会在模型支持时直接识别。因此，即使渠道未配置文件知识库，机器人也会基于附件内容正常回复。

knowledge_base_id只决定是否将附件额外保存到知识库。配置后，保存任务在后台执行，不影响当前 QA 回复，也不会额外发送"已入库"或"解析完成"消息。解析文本最多保留前 500 行且不超过 32 KiB（常量maxIMAttachmentLines、maxIMAttachmentContentBytes，见 internal/im/service.go），触及任一限制时模型会得到通用截断提示。附件无法读取、平台不支持下载或文件超过 32 MiB 时（maxIMAttachmentBytes），机器人会提示用户改用文字描述或重新发送。图片另有 8 MiB 上限（maxIMVisionAttachmentBytes），防止超大图展开为过大的 data URI。

回复中的图片外链（resource:// 改写）

答案里引用知识库图片时，正文中是resource://或local:///minio://等内部引用，IM 客户端无法直接拉取。rewriteStorageURLs（internal/im/service.go）在发送前把它们换成可访问的 http(s) URL，其核心逻辑委托给 internal/storageurl 的共享实现：

• 解析结果不是http(s) 时（例如仍是内部storage://路径），保留原引用并打一条可操作的 WARN，而不是把 IM 端注定加载失败的链接发出去；
• 成功改写记 INFO 日志（含签名 URL，便于排障，代价是有日志权限的人可在有效期内使用该链接）。

要让图片正常显示，二选一：

1. 存储后端公网可达：对象存储使用公网 endpoint（或把MINIO_ENDPOINT设为公网 host），resource://会回退到后端预签名 URL；
2. 配置APP_EXTERNAL_URL：resource://改写成<APP_EXTERNAL_URL>/r/<token>，请求经 nginx 的location ^~ /r/反代回 app。官方前端镜像已内置该 location；自建反代必须补上，否则请求落进 SPA fallback 返回空白页。

默认的 MinIO 内网部署（minio:9000）和local后端只能走第二种。IM 渠道已启用但APP_EXTERNAL_URL为空时，LoadAndStartChannels会打印一次启动告警（imImageConfigWarning，相关行为由 internal/im/im_config_warning_test.go 验证）。

图片仍然不显示时，按 图片与文件的对外访问 的排查表逐项对照——那里汇总了四种 URL 形式与各渠道的取法。

MCP OAuth 授权通知（身份绑定）

IM 场景下没有可交互的前端来完成 MCP 服务的会话内 OAuth 授权，因此：

• withIMIdentity给上下文打上MCPOAuthNonInteractive标记——Agent 遇到未授权的 OAuth MCP 服务时不阻塞等待，而是发出一次性EventMCPOAuthRequired事件；
• handleMessageStream收集这些事件（按 ServiceID 去重），回答结束后由buildIMMCPAuthNotice生成授权提示追加在回复末尾：若配置了APP_EXTERNAL_URL且 OAuthManager 可用，则为每个服务生成专属授权链接（回调地址<APP_EXTERNAL_URL>/api/v1/mcp-oauth/callback，主体为PrincipalIMUser，即授权与"租户+渠道+平台+IM 用户"绑定）；否则提示到 WeKnora 管理后台完成授权；
• 用户点链接完成授权后重新发送原消息即可使用该 MCP 服务。

配置与运行参考

渠道模型与配置（internal/im/types.go）

一个IMChannel（表im_channels）把某个平台机器人绑定到某个 Agent：

ChannelSession（表im_channel_sessions）把(platform, user_id, chat_id, thread_id, tenant_id)映射到 WeKnorasession_id，实现 IM 侧的对话连续性。若底层 Session 被从 Web UI 删除，HandleMessage会检测ErrSessionNotFound，软删陈旧映射并自动重建（修复"机器人永久失联"类问题，相关回归测试见 internal/im/session_not_found_test.go）。

渠道管理 API（internal/handler/im.go + router.go）

路由注册位于 internal/router/router.go 的RegisterIMRoutes/RegisterIMChannelRoutes。Webhook 模式的接入方式就是把https://<你的域名>/api/v1/im/callback/<channel_id>填到平台的事件订阅/回调地址处；WeKnora 会先响应平台的 URL 验证挑战（HandleURLVerification，如飞书的 challenge 回显、企微的 echostr 解密），之后每个回调都过VerifyCallback签名校验。WebSocket/长连接模式则无需公网回调地址，由 WeKnora 主动连接平台网关。

飞书/Lark 反向代理

credentials.api_base_url可覆盖 API origin，并同时用作长连接 SDK 的 bootstrap domain。留空分别使用飞书/Lark 默认云地址；私有网络可填https://feishu-proxy.example.com，不在结尾附加具体 API 路径。代理应转发平台 API 与长连接启动请求，启动响应返回的 WebSocket 地址也必须能从 WeKnora 服务器访问。只代理网页控制台不能解决服务器到飞书的网络问题。

{"platform":"feishu","mode":"websocket","credentials":{"app_id":"<app-id>","app_secret":"<app-secret>","api_base_url":"https://feishu-proxy.example.com"}}

云之家选择session_mode=thread后按话题复用会话，顶层消息启动新线程，回复沿根消息线程继续。钉钉富文本消息会提取可读内容；飞书 post 消息中的图片进入图片处理。output_mode=full可显示中间过程与输出进度，answer_only保留最终答案。

长连接的可靠性：leader 选举与 Supervisor

• 多实例 leader 选举（service.go）：websocket/longpoll 渠道在多实例部署（有 Redis）时，通过SETNX im:ws:leader:<channelID>（TTL 15s，每 5s 续期）保证只有一个实例维持长连接；非 leader 实例每 10s 重试抢锁，leader 宕机后自动接管。longpoll 渠道停止后保留锁至过期，等 TTL 自然过期，避免新旧实例短暂双写。续期失败（丢失 leader 身份）时走handleWSLeadershipLoss：先停掉本实例的适配器，再把渠道放回抢锁重试循环——重试前会重新读一次数据库中的渠道行，因此期间被删除、禁用或改配置的渠道不会被旧运行时复活。相关常量（wsLeaderTTL、wsLeaderRenewInterval、wsLeaderRetryInterval）见 internal/im/service.go。
• 连接保活（supervisor.go的RunSupervised）：部分 SDK（钉钉、飞书）的内部重连可能出现连接对象存在但无法接收消息的状态，Supervisor 每 6 小时（defaultRecycleInterval，见 internal/im/supervisor.go）主动重建连接，连接失败按 5s 退避重试，把最坏停摆时间限制在回收间隔内。

多实例部署要点

所有分布式状态集中定义在service.go的 Redis key 前缀常量：

无 Redis（Lite/单实例模式）时全部回退为本地内存实现，功能不变，仅失去跨实例语义。

消息处理流程

IMCallback（webhook）或长连接回调最终都进入Service.HandleMessage，随后经队列进入 QA 执行：

关键细节（均见service.go）：

• 去重：MessageID写入 Redisim:dedup:（TTL 5 分钟）或本地sync.Map（单实例模式），IM 平台重推的回调直接跳过。
• 限流：按channelID:userID:chatID[:threadID]做滑动窗口限流（默认 60s 内 10 条，可经config.IM覆盖）；斜杠命令绕过限流，保证用户在风暴中仍能/stop。
• QA 队列（internal/im/qaqueue.go）：有界队列 + 固定 worker 池（默认workers=5、defaultMaxQueueSize=50、单用户排队上限 3、排队超时queueTimeout=60s），多实例下通过 Redis 计数实现全局单用户上限（im:queue:user:）与可选的全局并发闸门（im:global:active+ Lua 脚本，GlobalMaxWorkers配置），对下游 LLM 形成背压。排队位置 > 0 时先回一条"排队中"提示。
• 会话解析：user模式按用户维度共享会话，标题形如"张三 · 群聊 1a2b3c4d"；thread模式每个顶层消息/话题一个会话（Slack thread、飞书话题群、Telegram Forum Topic、Mattermost root_id）。首条消息会异步生成会话标题（GenerateTitleAsync）。
• 身份注入（withIMIdentity）：IM 回调走平台签名而非 WeKnora 登录态，因此注入合成身份system-<tenantID>+PrincipalIMUser（tenantID:channelID:platform:userID）+ Viewer 角色，使组织共享知识库等依赖 UserID 的逻辑正常工作；同时标记MCPOAuthNonInteractive（见上文 MCP OAuth 授权通知）。
• 流式渲染（handleMessageStream+think.go+tool_display.go）：订阅 EventBus 的EventAgentThought（思考）、EventAgentToolCall/EventAgentToolResult（工具状态行，内部工具经isToolVisibleToUser过滤；快速问答只显示query_understand/knowledge_search两个 RAG 流水线工具）、EventAgentFinalAnswer（答案分片）、EventAgentReferences（引用）、EventAgentComplete。Agent 模式下"乐观答案"在后续又发起工具调用时会被撤回进思考块（retractAgentLiveAnswer，与 Web 端 superseded preamble 一致）。每 300ms 把缓冲内容整段推送（UpdateStreamContent为替换语义）；holdbackCutoff会扣住跨分片边界的不完整provider://URL、Markdown 图片、XML 标签，避免闪烁半截内容。最终FinalizeStream只保留答案文本（StripThinkBlocks），并把<kb/>、<web/>引用标签与<image>XML 清洗掉、provider://存储 URL 重写为可访问链接（cleanIMContent/rewriteStorageURLs）。
• 非流式路径：渠道output_mode=full、适配器不支持StreamSender、或StartStream失败时，走runQA聚合完整答案后SendReply一次性发送。
• 引用消息（Quote，目前由 WeCom 长连接适配器等填充）：文本引用以<quoted_message>包裹注入 LLM 上下文（上限 500 rune，区分"引用了机器人自己的回复"）；引用图片/文件/视频等非文本消息时，注入的是"明确告知用户无法查看该内容"的指令，避免模型猜测无法读取的内容（QuotedMessage.NonTextType字段与行为见 internal/im/adapter.go）。

架构总览

Adapter 接口（internal/im/adapter.go）

每个平台适配器实现统一的Adapter接口，把平台差异收敛到四个方法：

type Adapter interface { Platform() Platform // VerifyCallback 校验回调请求的签名/Token VerifyCallback(c *gin.Context) error // ParseCallback 把平台原始回调解析为统一的 IncomingMessage（非消息事件返回 nil） ParseCallback(c *gin.Context) (*IncomingMessage, error) // SendReply 把回复发回 IM 平台 SendReply(ctx context.Context, incoming *IncomingMessage, reply *ReplyMessage) error // HandleURLVerification 处理平台的 URL 验证挑战 HandleURLVerification(c *gin.Context) bool }

两个可选扩展接口决定了平台能力差异：

• StreamSender—— 流式回复（StartStream→UpdateStreamContent（整段替换语义）→FinalizeStream（最终只保留答案，剥离思考/工具过程）→EndStream）。实现者：Feishu/Lark（流式卡片）、DingTalk（AI 卡片，需card_template_id）、Slack、Telegram（消息编辑）、Mattermost、WeCom WebSocket 模式。
• FileDownloader—— 从平台下载用户发送的文件/图片（DownloadFile）。实现者：除 QQ 机器人外的全部平台（WeCom 两种模式均支持）。

统一消息模型IncomingMessage携带Platform、MessageType（text/file/image）、UserID、ChatID、ChatType（direct/group）、Content、MessageID（用于去重）、FileKey/FileName/FileSize、ThreadID（话题/线程 ID）、Quote（引用消息）等字段。

Service 编排（internal/im/service.go）

im.Service是消息处理中枢，职责：

1. 从 Adapter 接收统一的IncomingMessage；
2. 为该 IM 渠道解析或创建 WeKnora 会话（Session）；
3. 优先分发斜杠命令（不进入 QA 流水线）；
4. 普通消息调用 WeKnora QA 流水线（KnowledgeQA/AgentQA）；
5. 收集流式回答并通过 Adapter 回发。

平台适配器通过AdapterFactory注册（internal/container/container.go 的registerIMAdapterFactories）：

imService.RegisterAdapterFactory("wecom", wecom.NewFactory()) imService.RegisterAdapterFactory("feishu", feishu.NewFactory(feishu.RegionFeishu)) imService.RegisterAdapterFactory("lark", feishu.NewFactory(feishu.RegionLark)) // Lark 与飞书同一适配器，仅 API 域名不同 imService.RegisterAdapterFactory("slack", slack.NewFactory()) imService.RegisterAdapterFactory("telegram", telegram.NewFactory()) imService.RegisterAdapterFactory("dingtalk", dingtalk.NewFactory()) imService.RegisterAdapterFactory("mattermost", mattermost.NewFactory()) imService.RegisterAdapterFactory("wechat", wechat.NewFactory()) imService.RegisterAdapterFactory("qqbot", qqbot.NewFactory()) imService.RegisterAdapterFactory("yunzhijia", yunzhijia.NewFactory())

实现参考

• 核心框架与编排：internal/im（adapter.go、service.go、supervisor.go、command*.go、qaqueue.go、session/stream/think/tool_display等）
• 各平台适配器：internal/im/{wecom,feishu,dingtalk,slack,telegram,mattermost,wechat,qqbot,yunzhijia}
• HTTP 接口层：internal/handler/im.go
• 路由：internal/router/router.go 的RegisterIMRoutes/RegisterIMChannelRoutes
• 渠道数据模型与默认值：internal/im/types.go
• 相关文档：图片与文件的对外访问

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora