From 463f40fadcc156c1c1ea6a3eb559223c88b71b93 Mon Sep 17 00:00:00 2001 From: Austin Xia Date: Fri, 27 Mar 2026 11:07:09 +0800 Subject: [PATCH 01/16] Add im channel Mattermost --- docs/IM集成开发文档.md | 123 +++++++- frontend/src/api/agent/index.ts | 2 +- frontend/src/components/IMChannelPanel.vue | 97 +++++- frontend/src/i18n/locales/en-US.ts | 8 +- frontend/src/i18n/locales/ko-KR.ts | 8 +- frontend/src/i18n/locales/ru-RU.ts | 8 +- frontend/src/i18n/locales/zh-CN.ts | 8 +- internal/container/container.go | 56 ++++ internal/handler/im.go | 19 +- internal/im/adapter.go | 11 +- internal/im/mattermost/adapter.go | 341 +++++++++++++++++++++ internal/im/mattermost/client.go | 182 +++++++++++ internal/im/mattermost/form_parse.go | 27 ++ internal/im/types.go | 10 +- 14 files changed, 874 insertions(+), 26 deletions(-) create mode 100644 internal/im/mattermost/adapter.go create mode 100644 internal/im/mattermost/client.go create mode 100644 internal/im/mattermost/form_parse.go diff --git a/docs/IM集成开发文档.md b/docs/IM集成开发文档.md index 7d907f9e..1632e8ca 100644 --- a/docs/IM集成开发文档.md +++ b/docs/IM集成开发文档.md @@ -1,6 +1,6 @@ # IM 集成开发文档 -WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Slack、Telegram、钉钉)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。 +WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。 IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置通过前端 Agent 编辑器管理,存储在数据库中。 @@ -12,6 +12,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置 - [Slack 接入](#slack-接入) - [Telegram 接入](#telegram-接入) - [钉钉接入](#钉钉接入) + - [Mattermost 接入](#mattermost-接入) - [前端管理](#前端管理) - [架构总览](#架构总览) - [数据模型](#数据模型) @@ -25,6 +26,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置 - [Slack](#slack) - [Telegram](#telegram) - [钉钉 (DingTalk)](#钉钉-dingtalk) + - [Mattermost](#mattermost) - [斜杠指令系统](#斜杠指令系统) - [QA 队列与限流](#qa-队列与限流) - [流式输出机制](#流式输出机制) @@ -466,6 +468,49 @@ curl -X POST "https://api.telegram.org/bot/setWebhook" \ 2. **消息接收地址**:粘贴从 WeKnora 复制的回调地址 3. 钉钉会通过 HmacSHA256 签名验证回调请求 +--- + +### Mattermost 接入 + +Mattermost 为**自建部署**,当前仅支持 **Webhook** 模式:**出站 Webhook(Outgoing Webhook)** 将用户消息 POST 到 WeKnora,Bot 通过 **REST API v4** 发回频道/线程回复。与 Slack Events API 类似,回调需快速返回 `200`,实际回答由 Bot Token 异步调用接口完成。 + +> 需要公网或内网可达的回调 URL(Mattermost 服务器能访问 WeKnora 的 `/api/v1/im/callback/{channel_id}`)。若 WeKnora 在内网,请在 Mattermost 中配置 [Trusted Internal Connections](https://docs.mattermost.com/configure/environment-configuration-settings.html) 或将回调地址加入允许列表。 + +#### 第一步:创建 Bot 账户并获取 Token + +1. 在 Mattermost 中创建专用 Bot 账户(或使用个人账户的 **Personal Access Token**,不推荐生产环境)。 +2. 为 Bot 授予在目标频道/团队发消息、读取文件等所需权限(若需将用户上传的文件写入知识库,需能下载附件)。 +3. 在 **Profile → Security → Personal Access Tokens**(或 Bot 设置)生成 Token,复制保存为 **Bot Token**。 + +#### 第二步:创建 Outgoing Webhook + +1. 打开 **产品菜单 → 集成 → 出站 Webhook**(若不可见,需系统管理员在 **系统控制台 → 集成** 中启用出站 Webhook)。 +2. 点击 **Add Outgoing Webhook**,填写标题与描述。 +3. **Content Type** 建议选择 **application/json**(也支持 `application/x-www-form-urlencoded`,WeKnora 两种均可解析)。 +4. 选择触发频道,或配置**触发词**(与频道组合规则以 Mattermost 说明为准)。 +5. **Callback URLs** 先留空或填占位;保存后在 WeKnora 创建渠道后会得到正式地址。 +6. 保存后复制页面上的 **Token**(出站 Webhook 密钥),即 **Outgoing Webhook Token**。 + +#### 第三步:在 WeKnora 中添加 IM 渠道 + +1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道**。 +2. 填写配置: + - **平台**:选择「Mattermost」 + - **接入模式**:固定为 **Webhook**(选择 Mattermost 后界面会禁用 WebSocket) + - **输出模式**:流式输出 / 完整输出(流式通过编辑帖子实现) + - **Site URL**:Mattermost 站点根地址,如 `https://mattermost.example.com`(无尾部 `/`) + - **Bot Token**:上一步生成的 Token + - **Outgoing Webhook Token**:出站 Webhook 页面复制的 Token(用于校验回调,且参与 `bot_identity` 去重) + - **Bot User ID**(可选):Bot 在 Mattermost 中的用户 ID;填写后可忽略 Bot 自身触发的回调,避免自回复循环 +3. 保存后,复制渠道卡片上的 **回调地址**,回到 Mattermost 出站 Webhook 配置,将 **Callback URLs** 设为该地址并保存。 + +#### 第四步:验证 + +在绑定频道发送触发出站 Webhook 的消息,应收到 WeKnora 的回复;回复默认出现在**触发帖所在线程**(使用 Mattermost 的 `root_id` 与触发 `post_id` 对齐)。 + +**参考文档:** [Outgoing webhooks](https://developers.mattermost.com/integrate/webhooks/outgoing/) + + --- ## 前端管理 @@ -475,7 +520,7 @@ IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模 ### 渠道列表 每个渠道以卡片形式展示,包含: -- **平台标识**:企业微信(绿色)/ 飞书(蓝色)/ Slack(紫色)/ Telegram(蓝色)/ 钉钉(蓝色) +- **平台标识**:企业微信(绿色)/ 飞书(蓝色)/ Slack(紫色)/ Telegram(蓝色)/ 钉钉(蓝色)/ Mattermost(蓝色) - **渠道名称**:用户自定义 - **接入模式**:WebSocket / Webhook - **输出模式**:流式输出 / 完整输出 @@ -511,6 +556,17 @@ IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模 │ │ │ │ │ │ │ │ ─────┼─────────────┼─────────────┼──────────────┼─────────────┼──────── │ │ └─────────────┼─────────────┼──────────────┘─────────────┘ │ +│ │ │ +│ ┌────┴────────────┐ │ +│ │ Mattermost │ Webhook-only │ +│ └────────┬────────┘ │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ Mattermost │ │ +│ │ Adapter │ │ +│ └────────┬────────┘ │ +│ │ │ +│ ──────────────────┴────────────────────────────────────────────────────│ │ ▼ │ │ ┌──────────────────────────────────┐ │ │ │ im.Service │ 服务编排层 │ @@ -559,7 +615,7 @@ CREATE TABLE im_channels ( id VARCHAR(36) PRIMARY KEY, tenant_id BIGINT NOT NULL, agent_id VARCHAR(36) NOT NULL, -- 绑定的 Agent ID - platform VARCHAR(20) NOT NULL, -- 'wecom' | 'feishu' | 'slack' | 'telegram' | 'dingtalk' + platform VARCHAR(20) NOT NULL, -- 'wecom' | 'feishu' | 'slack' | 'telegram' | 'dingtalk' | 'mattermost' name VARCHAR(255) NOT NULL DEFAULT '', enabled BOOLEAN NOT NULL DEFAULT true, mode VARCHAR(20) NOT NULL DEFAULT 'websocket', -- 'webhook' | 'websocket' @@ -587,6 +643,9 @@ CREATE TABLE im_channels ( | Telegram | Webhook | `bot_token`, `secret_token`(可选) | | 钉钉 | WebSocket | `client_id`, `client_secret`, `card_template_id`(可选) | | 钉钉 | Webhook | `client_id`, `client_secret`, `card_template_id`(可选) | +| Mattermost | Webhook(唯一支持) | `site_url`, `bot_token`, `outgoing_token`(必填);`bot_user_id`(可选,过滤机器人自身消息) | + +`mattermost` 渠道的 `mode` 在数据库中固定为 `webhook`(创建时若未指定,服务端与模型钩子会默认 `webhook`)。`bot_identity` 形如 `mattermost:wh:{outgoing_token}`,用于防止同一出站 Webhook 重复绑定多个渠道。 ### im_channel_sessions 表 @@ -626,7 +685,7 @@ CREATE TABLE im_channels ( ### IMChannel — IM 渠道 -每个 IM 渠道代表一个 IM 平台机器人与 WeKnora Agent 的绑定关系。一个 Agent 可以绑定多个渠道(如同时接入企业微信、飞书和 Slack),同一平台也可以创建多个渠道(如不同的企业微信机器人)。 +每个 IM 渠道代表一个 IM 平台机器人与 WeKnora Agent 的绑定关系。一个 Agent 可以绑定多个渠道(如同时接入企业微信、飞书、Slack 与 Mattermost),同一平台也可以创建多个渠道(如不同的企业微信机器人)。 渠道有一个计算字段 `BotIdentity`,由平台类型、模式和核心凭证推导,用于防止同一机器人被重复创建。 @@ -638,7 +697,7 @@ CREATE TABLE im_channels ( ```go type IncomingMessage struct { - Platform Platform // "wecom" | "feishu" | "slack" | "telegram" | "dingtalk" + Platform Platform // "wecom" | "feishu" | "slack" | "telegram" | "dingtalk" | "mattermost" MessageType MessageType // "text" | "file" | "image" UserID string // 平台用户标识 UserName string // 显示名 (可选) @@ -1127,6 +1186,59 @@ EndStream: --- +### Mattermost + +仅支持 **Webhook** 模式:Mattermost **Outgoing Webhook** 将请求体 POST 到 WeKnora 统一回调地址;适配器实现 `Adapter`、`StreamSender`、`FileDownloader`(标准库 HTTP 调用 REST API,无第三方 SDK)。 + +#### Webhook 模式(Outgoing Webhook) + +``` +Mattermost 服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} + │ + 校验 body 中 token = outgoing_token + 解析 JSON 或 x-www-form-urlencoded + │ + 通过 REST API v4 回复(Bearer Bot Token) +``` + +- **安全校验:** 请求体中的 `token` 必须与渠道凭证中的 `outgoing_token` 一致(创建渠道时工厂会校验 `outgoing_token` 非空)。 +- **载荷格式:** 支持 `application/json` 与 `application/x-www-form-urlencoded`(与 [官方文档](https://developers.mattermost.com/integrate/webhooks/outgoing/) 一致)。 +- **机器人过滤:** 若配置了 `bot_user_id`,且 `user_id` 与之相同,则返回 `nil` 消息,避免自激。 +- **线程回复:** `IncomingMessage.Extra` 中保存 `thread_root_id`(有 `root_id` 时用其值,否则用触发帖 `post_id`);`SendReply` / `CreatePost` 时设置 `root_id`,使回复出现在同一线程。 +- **消息去重:** `MessageID` 使用触发帖的 `post_id`。 +- **文件消息:** 若载荷含 `file_ids`,取首个文件 ID 作为 `FileKey`;`DownloadFile` 先 `GET /api/v4/files/{id}/info` 再 `GET /api/v4/files/{id}` 下载内容。 + +#### 流式回复 + +与 Slack 类似,通过**编辑同一条帖子**展示累积全文: + +``` +StartStream: + 1. POST /api/v4/posts → 创建占位帖(如「正在思考...」),得到 post id + +SendStreamChunk: + 2. PUT /api/v4/posts/{post_id}/patch → Patch message 字段(累积全文) + +EndStream: + 3. 最后一次 Patch,与 SendStreamChunk 相同逻辑 +``` + +流式刷新间隔由 Service 侧 `streamFlushInterval`(300ms)批量合并,以降低编辑频率、减轻 API 压力。 + +#### URL 验证 + +Mattermost 出站 Webhook 无 Slack/Feishu 类 challenge 流程,`HandleURLVerification` 恒为 `false`。 + +#### 源码文件 + +| 文件 | 职责 | +|------|------| +| `internal/im/mattermost/adapter.go` | 出站 Webhook 解析、Token 校验、发帖/补丁流式、文件下载 | +| `internal/im/mattermost/client.go` | REST v4:`CreatePost`、`PatchPostMessage`、文件 info/下载 | +| `internal/im/mattermost/form_parse.go` | 表单编码 body 与 `file_ids` 辅助解析 | + +--- + ## 斜杠指令系统 IM 渠道支持斜杠指令(Slash Commands),用户在聊天中输入 `/指令名` 即可触发,无需经过 QA 管道,且不受限流约束。 @@ -1300,6 +1412,7 @@ QA 管道 ──chunk──chunk──chunk──▶ EventBus | 企业微信 Webhook | PicUrl 直接下载 或 MediaId 临时素材 API | | 企业微信 WebSocket | 加密附件 URL + per-message AES 密钥解密 | | Telegram | getFile API 获取文件路径 + HTTPS 下载(支持文档和图片) | +| Mattermost | `GET /api/v4/files/{file_id}/info` + `GET /api/v4/files/{file_id}`(Bearer Bot Token) | --- diff --git a/frontend/src/api/agent/index.ts b/frontend/src/api/agent/index.ts index 3e4a534e..33dbb470 100644 --- a/frontend/src/api/agent/index.ts +++ b/frontend/src/api/agent/index.ts @@ -182,7 +182,7 @@ export interface IMChannel { id: string; tenant_id?: number; agent_id: string; - platform: 'wecom' | 'feishu' | 'slack' | 'telegram' | 'dingtalk'; + platform: 'wecom' | 'feishu' | 'slack' | 'telegram' | 'dingtalk' | 'mattermost'; name: string; enabled: boolean; mode: 'webhook' | 'websocket'; diff --git a/frontend/src/components/IMChannelPanel.vue b/frontend/src/components/IMChannelPanel.vue index c7ea6d28..802c1be0 100644 --- a/frontend/src/components/IMChannelPanel.vue +++ b/frontend/src/components/IMChannelPanel.vue @@ -91,6 +91,7 @@ {{ $t('agentEditor.im.slack') }} {{ $t('agentEditor.im.telegram') }} {{ $t('agentEditor.im.dingtalk') }} + {{ $t('agentEditor.im.mattermost') }} @@ -104,10 +105,11 @@
- WebSocket + WebSocket Webhook -

{{ $t('agentEditor.im.modeHint') }}

+

{{ $t('agentEditor.im.mattermostModeHint') }}

+

{{ $t('agentEditor.im.modeHint') }}

@@ -283,13 +285,50 @@

{{ $t('agentEditor.im.dingtalkCardTemplateIdHint') }}

+ + +