Files
Enterprise-Knowledge-Base/internal/im/adapter.go
T
qilifan 9afb8b7b68 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>
2026-07-17 11:05:54 +08:00

173 lines
6.7 KiB
Go

package im
import (
"context"
"io"
"github.com/gin-gonic/gin"
)
// Platform identifies an IM platform.
type Platform string
const (
PlatformWeCom Platform = "wecom"
PlatformFeishu Platform = "feishu"
// PlatformLark is Feishu's international edition (open.larksuite.com).
// It shares the Feishu adapter; only the API host and tenant differ.
PlatformLark Platform = "lark"
PlatformSlack Platform = "slack"
PlatformTelegram Platform = "telegram"
PlatformDingtalk Platform = "dingtalk"
PlatformMattermost Platform = "mattermost"
PlatformWeChat Platform = "wechat"
PlatformQQBot Platform = "qqbot"
)
// SessionMode determines how IM sessions are resolved.
type SessionMode string
const (
// SessionModeUser resolves sessions by (platform, user_id, chat_id, tenant_id).
SessionModeUser SessionMode = "user"
// SessionModeThread resolves sessions by (platform, thread_id, chat_id, tenant_id).
SessionModeThread SessionMode = "thread"
)
// MessageType identifies the kind of IM message.
type MessageType string
const (
MessageTypeText MessageType = "text"
MessageTypeFile MessageType = "file"
MessageTypeImage MessageType = "image"
)
// IncomingMessage is the unified message parsed from an IM callback.
type IncomingMessage struct {
// Platform identifies which IM platform the message comes from.
Platform Platform
// MessageType is "text" (default) or "file".
MessageType MessageType
// UserID is the IM-platform user identifier.
UserID string
// UserName is the display name of the user (optional).
UserName string
// ChatID is the group/channel ID (empty for direct messages).
ChatID string
// ChatType distinguishes direct message from group chat.
ChatType ChatType
// Content is the text content of the message (empty for file messages).
Content string
// MessageID is the IM-platform message identifier (for dedup).
MessageID string
// FileKey is the platform file identifier (for file messages).
FileKey string
// FileName is the original file name (for file messages).
FileName string
// FileSize is the file size in bytes (for file messages, optional).
FileSize int64
// ThreadID is the platform-specific thread identifier.
// - Slack: thread_ts (top-level message uses its own timestamp)
// - Mattermost: root_id, or post_id if top-level
// - Feishu/Lark: root_id, or message_id if top-level
// - Telegram: message_thread_id (Forum Topics only)
// Empty for platforms without thread support (WeCom, DingTalk).
// In thread mode, top-level messages use their own ID as ThreadID,
// effectively creating a new session per top-level message.
ThreadID string
// Quote is the quoted/replied message, if any.
// Populated by adapters on platforms that support quote-reply.
Quote *QuotedMessage
// Extra holds platform-specific fields (e.g., WeCom stream ID).
Extra map[string]string
}
// QuotedMessage holds the content and metadata of a quoted/replied message.
// Populated by platform adapters that support quote-reply (e.g. WeCom long-connection).
type QuotedMessage struct {
// MessageID is the platform message ID of the quoted message.
MessageID string
// Content is the text content. Empty for non-text message types.
Content string
// SenderID is the platform user ID of the quoted message's author.
SenderID string
// IsBotMessage indicates whether the quoted message was from the bot.
IsBotMessage bool
// NonTextType records the original message type when the quoted message
// has no extractable text (e.g. "image", "file", "video").
// Empty when Content is populated. Used to generate LLM instructions
// instead of content placeholders that cause hallucination.
NonTextType string
}
// ChatType represents the IM chat type.
type ChatType string
const (
ChatTypeDirect ChatType = "direct"
ChatTypeGroup ChatType = "group"
)
// ReplyMessage is what WeKnora sends back to the IM platform.
type ReplyMessage struct {
// Content is the text content (Markdown).
Content string
// IsStreaming indicates whether this is a streaming chunk.
IsStreaming bool
// IsFinal marks the last chunk of a streaming reply.
IsFinal bool
// Extra holds platform-specific fields.
Extra map[string]string
}
// Adapter is the interface every IM platform must implement.
type Adapter interface {
// Platform returns the platform identifier.
Platform() Platform
// VerifyCallback verifies the signature/token of an incoming callback request.
// Returns nil if verification passes.
VerifyCallback(c *gin.Context) error
// ParseCallback parses the raw IM callback request into a unified IncomingMessage.
// Returns nil message for non-message events (e.g., URL verification).
ParseCallback(c *gin.Context) (*IncomingMessage, error)
// SendReply sends a reply back to the IM platform.
SendReply(ctx context.Context, incoming *IncomingMessage, reply *ReplyMessage) error
// HandleURLVerification handles the initial URL verification challenge from the IM platform.
// 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)
// UpdateStreamContent replaces the user-visible stream text with fullContent so far.
// Platforms with replace semantics (WeCom, Telegram edit, etc.) show this as the entire message.
UpdateStreamContent(ctx context.Context, incoming *IncomingMessage, streamID string, fullContent string) error
// FinalizeStream performs the final replace with answer-only content (thinking/tools stripped).
FinalizeStream(ctx context.Context, incoming *IncomingMessage, streamID string, finalContent string) error
// EndStream finalizes a streaming reply.
EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error
}
// FileDownloader is an optional interface that adapters can implement to support
// downloading file attachments from the IM platform. When the adapter implements
// this interface and the IM channel has a knowledge_base_id configured, file
// messages will be downloaded and saved to the specified knowledge base.
type FileDownloader interface {
// DownloadFile downloads a file resource from the IM platform.
// Returns the file content reader, the resolved file name, and any error.
DownloadFile(ctx context.Context, msg *IncomingMessage) (io.ReadCloser, string, error)
}