9afb8b7b68
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>
173 lines
6.7 KiB
Go
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)
|
|
}
|