feat(im,datasource): support Lark, Feishu's international edition

Lark and Feishu are the same product deployed on two isolated clouds
(open.larksuite.com and open.feishu.cn). WeKnora touches both from two
places — the IM bot and the Wiki data-source connector — and this brings
Lark to parity across both. Neither API surface differs, so rather than
duplicate either implementation, each is parametrized by a Region and
registered twice.

IM (internal/im/feishu):
  Every API call routes through a.api(), which prefixes the region's
  host, and the WebSocket client passes larkws.WithDomain — the SDK
  defaults to open.feishu.cn, so Lark long connections would otherwise
  fail to authenticate.

Data source (internal/datasource/connector/feishu):
  Lark was half-supported: the client honoured a base_url override and a
  LarkBaseURL constant existed, but the connector registered only as
  "feishu" and the UI never exposed base_url, so Lark wikis could not be
  configured at all. Lark is now its own connector type. base_url is kept
  as an explicit override so data sources that pointed a "feishu"
  connector at open.larksuite.com keep working.

Bugs found and fixed along the way:

- Wiki resource links were hardcoded to https://feishu.cn/wiki/{token} in
  four places, so a Lark wiki linked into the wrong cloud entirely.
- Bot identity is now platform-prefixed (feishu:cli_x vs lark:cli_x).
  BotIdentity carries a unique index, so without this a Lark channel
  would be rejected as a duplicate of an unrelated Feishu bot sharing an
  app_id.
- The card image cache is now keyed by app_id. image_keys are issued per
  app on one cloud; a Feishu key handed to a Lark app fails the card
  update with code=200570.
- The datasource doc claimed Lark "adapts automatically" — it could not,
  since the UI had no way to reach base_url.

Permissions are where the clouds genuinely diverge. Identical APIs do not
mean identical permission catalogues: aily:file:read, aily:file:write and
corehr:file:download exist on Feishu but not on Lark, so pasting Feishu's
scope JSON into Lark fails to import. That JSON is also over-broad (it
covers products WeKnora never calls) and simultaneously incomplete (it
omits the drive:*/docx:* scopes the connector needs). Lark therefore gets
its own list, derived from the 17 endpoints the code actually calls and
checked identifier-by-identifier against Lark's own API reference, plus a
full Feishu→Lark mapping table marking each scope verified, unverified,
or absent. Both features use tenant_access_token only — no user_access_
token exists anywhere in the repo — so the user dimension stays empty.

Known limitation: Region.ThinkingText makes Lark's initial card
placeholder English, but once streaming starts the think-block headers
come from the shared MarkdownThinkStyle and are Chinese on every platform
(Lark, Slack, Telegram, Mattermost alike). Fixing that means threading a
locale through FormatIMDisplayContent, which has no platform context — a
cross-platform change, not a Lark one. Documented as such.

The channel-creation 400 message is now derived from validIMPlatforms so
the list cannot drift as platforms are added.

Tests: region invariants and per-region URL construction on both sides,
the Feishu/Lark bot-identity split, platform-to-channel mapping, base_url
override precedence, an end-to-end SendReply against a fake Open Platform
(token fetch, reply, thread-unsupported fallback, hard-error surfacing),
and a ListResources drive asserting wiki links never leak the other
cloud's host.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
qilifan
2026-07-16 23:34:53 +08:00
committed by lyingbug
parent 3edd9c2c84
commit 9afb8b7b68
41 changed files with 1187 additions and 160 deletions
+135 -8
View File
@@ -1,6 +1,6 @@
# IM 集成开发文档
WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Lark、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置通过前端 Agent 编辑器管理,存储在数据库中。
@@ -9,6 +9,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置
- [快速接入指南](#快速接入指南)
- [企业微信接入](#企业微信接入)
- [飞书接入](#飞书接入)
- [Lark 接入](#lark-接入)
- [Slack 接入](#slack-接入)
- [Telegram 接入](#telegram-接入)
- [钉钉接入](#钉钉接入)
@@ -22,7 +23,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置
- [接口定义](#接口定义)
- [平台适配器详解](#平台适配器详解)
- [企业微信 (WeCom)](#企业微信-wecom)
- [飞书 (Feishu)](#飞书-feishu)
- [飞书 (Feishu) 与 Lark](#飞书-feishu-与-lark)
- [Slack](#slack)
- [Telegram](#telegram)
- [钉钉 (DingTalk)](#钉钉-dingtalk)
@@ -234,6 +235,64 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置
---
### Lark 接入
Lark 是飞书的国际版。两者是同一产品部署在两朵相互隔离的云上,**IM 的 API 接口、事件结构、
凭证字段、接入模式一致**,因此 WeKnora 中 Lark 与飞书共用同一套适配器代码。
但「代码一致」不等于「配置一致」,接入时有三处差别:
| | 飞书 | Lark |
|---|---|---|
| 开放平台 | <https://open.feishu.cn/> | <https://open.larksuite.com/> |
| 添加渠道时的**平台**选项 | 「飞书」 | 「Lark(飞书国际版)」 |
| 权限清单 | [飞书接入](#飞书接入)一节的 JSON | [Lark 权限配置](#lark-权限配置)一节的 JSON(**不可套用飞书的**) |
创建应用、添加机器人能力、订阅 `im.message.receive_v1` 事件、发布版本、填写
App ID / App Secret 等步骤与[飞书接入](#飞书接入)一节相同。**唯独权限配置不同,见下。**
#### Lark 权限配置
在 Lark 开放平台 **权限管理 → 批量导入** 粘贴下面的 JSON,覆盖 IM 机器人与知识库(Wiki)
数据源两块功能:
```json
{
"scopes": {
"tenant": [
"im:message",
"im:message:send_as_bot",
"im:resource",
"im:message.p2p_msg:readonly",
"im:message.group_at_msg:readonly",
"cardkit:card:write",
"wiki:wiki:readonly",
"drive:export:readonly",
"drive:drive:readonly",
"docx:document:readonly"
],
"user": []
}
}
```
> 不要套用[飞书接入](#飞书接入)一节的 JSON:其中 `aily:file:*`、`corehr:file:download`
> 在 Lark 不存在,整份导入会失败。
> **注意**:飞书应用与 Lark 应用互不通用。在 open.feishu.cn 创建的应用无法用于 Lark 渠道,
> 反之亦然——凭证只在创建它的那朵云上有效,跨云调用会认证失败。
WebSocket 模式启动后日志出现以下内容表示连接成功:
```
[IM] Lark WebSocket connecting (app_id=xxx)...
```
同一个 App ID 在两朵云上分别注册时,WeKnora 通过 `平台:app_id` 区分(如 `feishu:cli_xxx`
与 `lark:cli_xxx`),两个渠道可以并存,会话互不干扰。
---
### Slack 接入
Slack 提供两种接入模式,推荐使用 WebSocket (Socket Mode) 模式,无需公网域名。
@@ -520,7 +579,7 @@ IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模
### 渠道列表
每个渠道以卡片形式展示,包含:
- **平台标识**:企业微信(绿色)/ 飞书(蓝色)/ Slack(紫色)/ Telegram(蓝色)/ 钉钉(蓝色)/ Mattermost(蓝色)
- **平台标识**:企业微信(绿色)/ 飞书(青色)/ Lark(蓝色)/ Slack(紫色)/ Telegram(蓝色)/ 钉钉(蓝色)/ Mattermost(蓝色)
- **渠道名称**:用户自定义
- **接入模式**:WebSocket / Webhook
- **输出模式**:流式输出 / 完整输出
@@ -615,7 +674,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' | 'mattermost'
platform VARCHAR(20) NOT NULL, -- 'wecom' | 'feishu' | 'lark' | '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'
@@ -635,8 +694,8 @@ CREATE TABLE im_channels (
|------|------|------|
| 企业微信 | WebSocket | `bot_id`, `bot_secret` |
| 企业微信 | Webhook | `corp_id`, `agent_secret`, `token`, `encoding_aes_key`, `corp_agent_id` |
| 飞书 | WebSocket | `app_id`, `app_secret` |
| 飞书 | Webhook | `app_id`, `app_secret`, `verification_token`, `encrypt_key` |
| 飞书 / Lark | WebSocket | `app_id`, `app_secret` |
| 飞书 / Lark | Webhook | `app_id`, `app_secret`, `verification_token`, `encrypt_key` |
| Slack | WebSocket | `app_token`, `bot_token` |
| Slack | Webhook | `bot_token`, `signing_secret` |
| Telegram | WebSocket | `bot_token` |
@@ -697,7 +756,7 @@ CREATE TABLE im_channels (
```go
type IncomingMessage struct {
Platform Platform // "wecom" | "feishu" | "slack" | "telegram" | "dingtalk" | "mattermost"
Platform Platform // "wecom" | "feishu" | "lark" | "slack" | "telegram" | "dingtalk" | "mattermost"
MessageType MessageType // "text" | "file" | "image"
UserID string // 平台用户标识
UserName string // 显示名 (可选)
@@ -921,10 +980,71 @@ LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com
---
### 飞书 (Feishu)
### 飞书 (Feishu) 与 Lark
统一适配器同时支持 Webhook 和 WebSocket 模式,且原生实现 `StreamSender` 和 `FileDownloader` 接口。
#### 双云共用一套适配器
飞书与 Lark 是同一产品部署在两朵隔离的云上,API 与事件结构完全一致,因此 `internal/im/feishu`
包同时服务两个平台,由 `Region` 决定具体连哪朵云:
```go
// internal/im/feishu/region.go
type Region struct {
Platform im.Platform // "feishu" | "lark",写入 IncomingMessage
OpenBaseURL string // https://open.feishu.cn | https://open.larksuite.com
Label string // 日志前缀 [Feishu] / [Lark]
ThinkingText string // 流式卡片占位文案(中文 / 英文)
ImageFallbackLabel string // 图片上传失败时降级链接的文案
}
var (
RegionFeishu = Region{Platform: im.PlatformFeishu, OpenBaseURL: "https://open.feishu.cn", ...}
RegionLark = Region{Platform: im.PlatformLark, OpenBaseURL: "https://open.larksuite.com", ...}
)
```
容器中注册为两个平台:
```go
// internal/container/container.go
imService.RegisterAdapterFactory("feishu", feishu.NewFactory(feishu.RegionFeishu))
imService.RegisterAdapterFactory("lark", feishu.NewFactory(feishu.RegionLark))
```
适配器所有 API 调用经 `a.api(path, args...)` 拼接 `region.OpenBaseURL`;WebSocket 模式通过
`larkws.WithDomain(region.OpenBaseURL)` 指向对应云(SDK 默认连 open.feishu.cn,Lark 不指定会认证失败)。
> **跨云资源不通用**:`tenant_access_token`、`image_key`、`file_key`、`card_id` 均由单朵云的
> 单个应用签发,跨云或跨应用使用会被拒绝。图片上传缓存因此以 `app_id` 为前缀分区。
#### IM 适配器实际调用的接口与所需权限
下表说明适配器**实际**依赖哪些权限。表中的权限标识已对照 Lark 官方 API 文档逐条核对,
飞书侧同名。
> **两朵云的权限清单并不等价。** API 与事件结构一致,不代表权限目录一致——飞书开放平台
> 上存在的部分权限,Lark 开放平台并没有。因此各自的配置清单请分别参照
> [飞书接入](#飞书接入)与 [Lark 权限配置](#lark-权限配置),不要跨云复制粘贴。
>
> 飞书一节的 JSON 还同时覆盖了**飞书数据源连接器**(Wiki 同步),所以包含
> `wiki:wiki:readonly`、`docs:document.content:read`、`sheets:spreadsheet` 等 IM 用不到的权限。
| 适配器调用 | 用途 | 所需权限(满足其一即可) |
|---|---|---|
| `POST /auth/v3/tenant_access_token/internal` | 换取 tenant access token | 无需权限(凭 App ID / Secret) |
| `POST /im/v1/messages/{id}/reply` | 回复消息(主路径) | `im:message`、`im:message:send_as_bot` 或 `im:message:send` |
| `POST /im/v1/messages` | 发送消息(回复失败时降级) | 同上 |
| `GET /im/v1/messages/{id}/resources/{key}` | 下载用户发来的文件 / 图片 | `im:message` 或 `im:message:readonly` |
| `POST /im/v1/images` | 上传图片以取得 `image_key` | `im:resource` 或 `im:resource:upload` |
| `POST /cardkit/v1/cards`<br>`PUT /cardkit/v1/cards/{id}/elements/{eid}/content`<br>`PATCH /cardkit/v1/cards/{id}/settings` | 流式卡片(仅流式输出模式需要) | `cardkit:card:write` |
| 订阅事件 `im.message.receive_v1`(单聊) | 接收私聊消息 | `im:message.p2p_msg` 或 `im:message.p2p_msg:readonly` |
| 订阅事件 `im.message.receive_v1`(群聊 @) | 接收群内 @机器人 消息 | `im:message.group_at_msg` 或 `im:message.group_at_msg:readonly` |
因此 IM 功能全开(私聊 + 群聊 @ + 文件 + 图片 + 流式卡片)最少需要 5 类权限:收私聊、收群 @、
发消息、读写资源、写卡片。若关闭流式输出(输出模式选「完整输出」),`cardkit:card:write` 可省略。
#### Webhook 模式
```
@@ -974,14 +1094,21 @@ EndStream:
> [thinking content line 2]
```
> **已知限制**:`Region.ThinkingText` 只本地化了卡片的初始占位文案(Lark 显示 `Thinking...`)。
> 一旦开始流式输出,think 块标题来自共享的 `MarkdownThinkStyle`,目前对所有平台
> (Lark、Slack、Telegram、Mattermost 等)都是中文。本地化它需要把 locale 贯穿到
> `FormatIMDisplayContent`,属于跨平台改动,不在 Lark 接入范围内。
**孤立流清理:** 后台协程每 1 分钟扫描超过 5 分钟未关闭的流式卡片,自动调用 `EndStream` 关闭(防止内存泄漏)。
#### 源码文件
| 文件 | 职责 |
|------|------|
| `internal/im/feishu/region.go` | `Region` 定义(飞书 / Lark 的域名、平台标识、日志前缀、本地化文案) |
| `internal/im/feishu/adapter.go` | 事件解析、CardKit 流式实现、Token 缓存、AES 解密、Think 块转换、文件下载 |
| `internal/im/feishu/longconn.go` | WebSocket 长连接(封装飞书 SDK)、事件分发 |
| `internal/im/feishu/factory.go` | 按 `Region` 构造适配器与长连接客户端 |
---
+17 -2
View File
@@ -1,13 +1,13 @@
---
title: IM集成开发
tags: [集成扩展, IM, 企微, 飞书, Slack, Telegram, 钉钉, Mattermost]
tags: [集成扩展, IM, 企微, 飞书, Lark, Slack, Telegram, 钉钉, Mattermost]
aliases: [IM集成, IM开发, 企业微信, 即时通讯]
source: IM集成开发文档.md
---
# IM 集成开发
WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Lark、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道。
@@ -19,6 +19,7 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道。
|------|:-:|:-:|:-:|
| 企业微信 | ✅ | ✅ | ✅ |
| 飞书 | ✅ | ✅ | ✅ (CardKit) |
| Lark(飞书国际版) | ✅ | ✅ | ✅ (CardKit) |
| Slack | ✅ (Socket Mode) | ✅ (Events API) | ✅ |
| Telegram | ✅ (长轮询) | ✅ | ✅ |
| 钉钉 | ✅ (Stream) | ✅ | ✅ (AI 卡片) |
@@ -47,6 +48,20 @@ IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道。
> 飞书同时也是数据源导入的支持平台,参见 [数据源导入开发](数据源导入开发.md)
### Lark 接入
Lark 是飞书的国际版,IM 接口一致,与飞书共用同一套适配器。接入步骤基本相同,但开放平台
与**权限清单**不同:
- 飞书:<https://open.feishu.cn/>
- Lark:<https://open.larksuite.com/>
> **权限不可套用飞书的清单**:飞书清单混入了数据源连接器(Wiki 同步)用的权限,其中部分在
> Lark 并不存在,整份导入会失败。Lark 只需 IM 相关的 6 项,见
> [IM集成开发文档 — Lark 权限配置](../../IM集成开发文档.md#lark-权限配置)。
> 两朵云的应用互不通用,凭证只在创建它的那朵云上有效。
### Slack 接入
- **Socket Mode**(推荐)— 无需公网域名
+36 -1
View File
@@ -82,7 +82,42 @@ WeKnora 的数据源导入模块支持从外部平台(飞书、企业微信、
- **成功**:显示已创建/更新/跳过/失败的文档数量
- **失败**:显示错误信息,常见原因为权限不足或 Token 过期
> **注意**:飞书国际版(Lark)同样支持,在创建数据源时会自动适配 `https://open.larksuite.com` 的 API 地址。
---
### Lark 知识库接入
Lark 是飞书的国际版。Wiki / docx / drive 接口与飞书一致,**共用同一套连接器代码**,接入步骤
与[飞书知识库接入](#飞书知识库接入)相同,差别只有三处:
| | 飞书 | Lark |
|---|---|---|
| 开放平台 | <https://open.feishu.cn/> | <https://open.larksuite.com/> |
| 连接器类型 | 「飞书」 | 「Lark」 |
| API 地址 | `https://open.feishu.cn` | `https://open.larksuite.com`(选中 Lark 类型后自动使用) |
#### Lark 权限
权限标识与飞书相同,在 Lark 开放平台的 **权限管理** 中开通:
| 权限 | 说明 | Lark 官方文档核对 |
|------|------|------|
| `wiki:wiki:readonly` | 读取知识库空间列表和节点树 | ✅ 已核对 |
| `drive:export:readonly` | 导出文档内容(docx/xlsx) | ✅ 已核对 |
| `drive:drive:readonly` | 读取云文档基础信息、下载文件 | ✅ 已核对 |
| `docx:document:readonly` | 读取新版文档内容 | ⚠️ 未能核对(Lark 文档页渲染受限),沿用飞书侧标识 |
> **不要套用 [IM 集成文档](./IM集成开发文档.md#飞书接入)里的那份权限 JSON**:那份清单混入了
> `aily:file:*`、`corehr:file:download` 等在 Lark 并不存在的权限(整份导入会失败),
> 且反而**缺少**上表中数据源真正需要的 `drive:*` / `docx:*`。
>
> 若同一个 Lark 应用既做 IM 机器人又做知识库同步,请使用
> [IM 集成文档 — Lark 权限配置](./IM集成开发文档.md#lark-权限配置)中的合并清单。
#### 应用互不通用
在 open.feishu.cn 创建的应用无法读取 Lark 知识库,反之亦然——凭证只在创建它的那朵云上有效。
若你此前用「飞书」连接器加 `base_url=https://open.larksuite.com` 的方式接入过 Lark,该配置
仍然有效(`base_url` 保留为显式覆盖项),但新建数据源请直接选「Lark」类型。
---