From b7ed54f8de6920eabe6a56401d9fd2d67644c119 Mon Sep 17 00:00:00 2001 From: ChenRussell <792608290@qq.com> Date: Fri, 13 Mar 2026 11:24:15 +0800 Subject: [PATCH 01/35] fix: add missing UserInfo in organization.go --- client/organization.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/client/organization.go b/client/organization.go index ee6c4023..aec50405 100644 --- a/client/organization.go +++ b/client/organization.go @@ -146,6 +146,19 @@ type SharedAgentInfo struct { SharedAt time.Time `json:"shared_at"` } +// UserInfo represents user information for API responses +type UserInfo struct { + ID string `json:"id"` + Username string `json:"username"` + Email string `json:"email"` + Avatar string `json:"avatar"` + TenantID uint64 `json:"tenant_id"` + IsActive bool `json:"is_active"` + CanAccessAllTenants bool `json:"can_access_all_tenants"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + // --- Organization CRUD --- // CreateOrganization creates a new organization From 5afc81d00bf78849d140dca1355c1af71e25cf55 Mon Sep 17 00:00:00 2001 From: Manx98 Date: Tue, 10 Mar 2026 12:32:48 +0800 Subject: [PATCH 02/35] feat: support NVIDIA model API --- frontend/src/components/ModelEditorDialog.vue | 12 ++ frontend/src/i18n/locales/en-US.ts | 4 + frontend/src/i18n/locales/ko-KR.ts | 4 + frontend/src/i18n/locales/ru-RU.ts | 6 +- frontend/src/i18n/locales/zh-CN.ts | 4 + internal/application/service/knowledgebase.go | 2 +- internal/models/embedding/embedder.go | 8 + internal/models/embedding/nvidia.go | 203 ++++++++++++++++++ internal/models/provider/nvidia.go | 54 +++++ internal/models/provider/provider.go | 5 + internal/models/provider/provider_test.go | 2 + internal/models/rerank/nvidia_reranker.go | 138 ++++++++++++ internal/models/rerank/reranker.go | 2 + internal/types/const.go | 2 + 14 files changed, 444 insertions(+), 2 deletions(-) create mode 100644 internal/models/embedding/nvidia.go create mode 100644 internal/models/provider/nvidia.go create mode 100644 internal/models/rerank/nvidia_reranker.go diff --git a/frontend/src/components/ModelEditorDialog.vue b/frontend/src/components/ModelEditorDialog.vue index 4012aae7..b1918d30 100644 --- a/frontend/src/components/ModelEditorDialog.vue +++ b/frontend/src/components/ModelEditorDialog.vue @@ -356,6 +356,18 @@ const fallbackProviderOptions = computed(() => [ description: t('model.editor.providers.jina.description'), modelTypes: ['embedding', 'rerank'] }, + { + value: 'nvidia', + label: t('model.editor.providers.nvidia.label'), + defaultUrls: { + chat: 'https://integrate.api.nvidia.com/v1', + embedding: 'https://integrate.api.nvidia.com/v1', + rerank: 'https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking', + vllm: 'https://integrate.api.nvidia.com/v1', + }, + description: t('model.editor.providers.nvidia.description'), + modelTypes: ['chat', 'embedding', 'rerank', 'vllm'] + }, { value: 'generic', label: t('model.editor.providers.generic.label'), diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index 8ce2b4c7..cde8b640 100755 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -2129,6 +2129,10 @@ export default { label: 'Tencent Cloud LKEAP', description: 'DeepSeek-R1, DeepSeek-V3 series with chain-of-thought', }, + nvidia: { + label: "NVIDIA", + description: "deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.", + }, }, }, builtinTag: 'Built-in', diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index d1948dfa..3397adcc 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -1611,6 +1611,10 @@ export default { label: "텐센트 클라우드 LKEAP", description: "DeepSeek-R1, DeepSeek-V3 시리즈, 사고 체인 지원", }, + nvidia: { + label: "NVIDIA", + description: "deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.", + }, }, }, builtinTag: '내장', diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index 0ac82bf8..c5e02379 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -1457,7 +1457,11 @@ export default { lkeap: { label: 'Tencent Cloud LKEAP', description: 'DeepSeek-R1, DeepSeek-V3 с поддержкой цепочки рассуждений' - } + }, + nvidia: { + label: "NVIDIA", + description: "deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.", + }, } }, builtinTag: 'Built-in' diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index a084635e..ba42f3cc 100755 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -1588,6 +1588,10 @@ export default { label: "腾讯云 LKEAP", description: "DeepSeek-R1, DeepSeek-V3 系列模型,支持思维链", }, + nvidia: { + label: "NVIDIA", + description: "deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.", + }, }, }, builtinTag: "内置", diff --git a/internal/application/service/knowledgebase.go b/internal/application/service/knowledgebase.go index c5c9314b..41f4c029 100644 --- a/internal/application/service/knowledgebase.go +++ b/internal/application/service/knowledgebase.go @@ -660,7 +660,7 @@ func (s *knowledgeBaseService) HybridSearch(ctx context.Context, // Generate embedding vector for the query text logger.Info(ctx, "Starting to generate query embedding") - queryEmbedding, err := embeddingModel.Embed(ctx, params.QueryText) + queryEmbedding, err := embeddingModel.Embed(context.WithValue(ctx, types.EmbedQueryContextKey, true), params.QueryText) if err != nil { logger.Errorf(ctx, "Failed to embed query text, query text: %s, error: %v", params.QueryText, err) return nil, err diff --git a/internal/models/embedding/embedder.go b/internal/models/embedding/embedder.go index 470edae9..014c4d96 100644 --- a/internal/models/embedding/embedder.go +++ b/internal/models/embedding/embedder.go @@ -126,6 +126,14 @@ func NewEmbedder(config Config, pooler EmbedderPooler, ollamaService *ollama.Oll config.ModelID, pooler) return embedder, err + case provider.ProviderNvidia: + embedder, err = NewNvidiaEmbedder(config.APIKey, + config.BaseURL, + config.ModelName, + config.Dimensions, + config.ModelID, + pooler) + return embedder, err default: // Use OpenAI-compatible embedder for other providers embedder, err = NewOpenAIEmbedder(config.APIKey, diff --git a/internal/models/embedding/nvidia.go b/internal/models/embedding/nvidia.go new file mode 100644 index 00000000..2c37dbbd --- /dev/null +++ b/internal/models/embedding/nvidia.go @@ -0,0 +1,203 @@ +package embedding + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "time" + + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" +) + +// NvidiaEmbedder implements text vectorization functionality using NVIDIA API +type NvidiaEmbedder struct { + apiKey string + baseURL string + modelName string + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + EmbedderPooler +} + +// NvidiaEmbedRequest represents an NVIDIA embedding request +type NvidiaEmbedRequest struct { + Model string `json:"model"` + Input []string `json:"input"` + EncodingFormat string `json:"encoding_format,omitempty"` + TruncatePromptTokens int `json:"truncate_prompt_tokens,omitempty"` + InputType string `json:"input_type,omitempty"` +} + +// NvidiaEmbedResponse represents an NVIDIA embedding response +type NvidiaEmbedResponse struct { + Data []struct { + Embedding []float32 `json:"embedding"` + Index int `json:"index"` + } `json:"data"` +} + +// NewNvidiaEmbedder creates a new NVIDIA embedder +func NewNvidiaEmbedder(apiKey, baseURL, modelName string, + dimensions int, modelID string, pooler EmbedderPooler, +) (*NvidiaEmbedder, error) { + if baseURL == "" { + baseURL = "https://integrate.api.nvidia.com/v1" + } + + if modelName == "" { + return nil, fmt.Errorf("model name is required") + } + + timeout := 60 * time.Second + + // Create HTTP client + client := &http.Client{ + Timeout: timeout, + } + + return &NvidiaEmbedder{ + apiKey: apiKey, + baseURL: baseURL, + modelName: modelName, + httpClient: client, + EmbedderPooler: pooler, + dimensions: dimensions, + modelID: modelID, + timeout: timeout, + maxRetries: 3, // Maximum retry count + }, nil +} + +// Embed converts text to vector +func (e *NvidiaEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { + for range 3 { + embeddings, err := e.BatchEmbed(ctx, []string{text}) + if err != nil { + return nil, err + } + if len(embeddings) > 0 { + return embeddings[0], nil + } + } + return nil, fmt.Errorf("no embedding returned") +} + +func (e *NvidiaEmbedder) doRequestWithRetry(ctx context.Context, jsonData []byte) (*http.Response, error) { + var resp *http.Response + var err error + url := e.baseURL + "/embeddings" + + for i := 0; i <= e.maxRetries; i++ { + if i > 0 { + backoffTime := time.Duration(1< 10*time.Second { + backoffTime = 10 * time.Second + } + logger.GetLogger(ctx). + Infof("NvidiaEmbedder retrying request (%d/%d), waiting %v", i, e.maxRetries, backoffTime) + + select { + case <-time.After(backoffTime): + case <-ctx.Done(): + return nil, ctx.Err() + } + } + + // Rebuild request each time to ensure Body is valid + req, err := http.NewRequestWithContext(ctx, "POST", url, bytes.NewReader(jsonData)) + if err != nil { + logger.GetLogger(ctx).Errorf("NvidiaEmbedder failed to create request: %v", err) + continue + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+e.apiKey) + + resp, err = e.httpClient.Do(req) + if err == nil { + return resp, nil + } + + logger.GetLogger(ctx).Errorf("NvidiaEmbedder request failed (attempt %d/%d): %v", i+1, e.maxRetries+1, err) + } + + return nil, err +} + +func (e *NvidiaEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]float32, error) { + // Create request body + reqBody := NvidiaEmbedRequest{ + Model: e.modelName, + Input: texts, + EncodingFormat: "float", + InputType: "passage", + } + isQuery, _ := ctx.Value(types.EmbedQueryContextKey).(bool) + if isQuery { + reqBody.InputType = "query" + } + + jsonData, err := json.Marshal(reqBody) + if err != nil { + logger.GetLogger(ctx).Errorf("NvidiaEmbedder EmbedBatch marshal request error: %v", err) + return nil, fmt.Errorf("marshal request: %w", err) + } + + // Send request (passing jsonData instead of constructing http.Request) + resp, err := e.doRequestWithRetry(ctx, jsonData) + if err != nil { + logger.GetLogger(ctx).Errorf("NvidiaEmbedder EmbedBatch send request error: %v", err) + return nil, fmt.Errorf("send request: %w", err) + } + if resp.Body != nil { + defer resp.Body.Close() + } + + // Read response + body, err := io.ReadAll(resp.Body) + if err != nil { + logger.GetLogger(ctx).Errorf("NvidiaEmbedder EmbedBatch read response error: %v", err) + return nil, fmt.Errorf("read response: %w", err) + } + + if resp.StatusCode != http.StatusOK { + logger.GetLogger(ctx).Errorf("NvidiaEmbedder EmbedBatch API error: Http Status %s", resp.Status) + return nil, fmt.Errorf("EmbedBatch API error: Http Status %s", resp.Status) + } + + // Parse response + var response NvidiaEmbedResponse + if err := json.Unmarshal(body, &response); err != nil { + logger.GetLogger(ctx).Errorf("NvidiaEmbedder EmbedBatch unmarshal response error: %v", err) + return nil, fmt.Errorf("unmarshal response: %w", err) + } + + // Extract embedding vectors + embeddings := make([][]float32, 0, len(response.Data)) + for _, data := range response.Data { + embeddings = append(embeddings, data.Embedding) + } + + return embeddings, nil +} + +// GetModelName returns the model name +func (e *NvidiaEmbedder) GetModelName() string { + return e.modelName +} + +// GetDimensions returns the vector dimensions +func (e *NvidiaEmbedder) GetDimensions() int { + return e.dimensions +} + +// GetModelID returns the model ID +func (e *NvidiaEmbedder) GetModelID() string { + return e.modelID +} diff --git a/internal/models/provider/nvidia.go b/internal/models/provider/nvidia.go new file mode 100644 index 00000000..9fb87c0d --- /dev/null +++ b/internal/models/provider/nvidia.go @@ -0,0 +1,54 @@ +package provider + +import ( + "fmt" + + "github.com/Tencent/WeKnora/internal/types" +) + +const ( + // NvidiaChatBaseURL NVIDIA Chat 的默认 BaseURL + NvidiaChatBaseURL = "https://integrate.api.nvidia.com/v1" + // NvidiaRerankBaseURL NVIDIA Rerank 的默认 BaseURL + NvidiaRerankBaseURL = "https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking" +) + +// NvidiaProvider 实现NVIDIA AI 的 Provider 接口 +type NvidiaProvider struct{} + +func init() { + Register(&NvidiaProvider{}) +} + +// Info 返回NVIDIA provider 的元数据 +func (p *NvidiaProvider) Info() ProviderInfo { + return ProviderInfo{ + Name: ProviderNvidia, + DisplayName: "NVIDIA", + Description: "deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.", + DefaultURLs: map[types.ModelType]string{ + types.ModelTypeKnowledgeQA: NvidiaChatBaseURL, + types.ModelTypeEmbedding: NvidiaChatBaseURL, + types.ModelTypeRerank: NvidiaRerankBaseURL, + types.ModelTypeVLLM: NvidiaChatBaseURL, + }, + ModelTypes: []types.ModelType{ + types.ModelTypeKnowledgeQA, + types.ModelTypeEmbedding, + types.ModelTypeRerank, + types.ModelTypeVLLM, + }, + RequiresAuth: true, + } +} + +// ValidateConfig 验证NVIDIA provider 配置 +func (p *NvidiaProvider) ValidateConfig(config *Config) error { + if config.APIKey == "" { + return fmt.Errorf("API key is required for NVIDIA") + } + if config.ModelName == "" { + return fmt.Errorf("model name is required") + } + return nil +} diff --git a/internal/models/provider/provider.go b/internal/models/provider/provider.go index aabfb8f6..6accdf1d 100644 --- a/internal/models/provider/provider.go +++ b/internal/models/provider/provider.go @@ -53,6 +53,8 @@ const ( ProviderLongCat ProviderName = "longcat" // 腾讯云 LKEAP (知识引擎原子能力) ProviderLKEAP ProviderName = "lkeap" + // NVIDIA + ProviderNvidia ProviderName = "nvidia" ) // AllProviders 返回所有注册的提供者名称 @@ -78,6 +80,7 @@ func AllProviders() []ProviderName { ProviderLongCat, ProviderLKEAP, ProviderGPUStack, + ProviderNvidia, } } @@ -243,6 +246,8 @@ func DetectProvider(baseURL string) ProviderName { return ProviderLongCat case containsAny(baseURL, "lkeap.cloud.tencent.com", "api.lkeap"): return ProviderLKEAP + case containsAny(baseURL, "nvidia.com"): + return ProviderNvidia default: return ProviderGeneric } diff --git a/internal/models/provider/provider_test.go b/internal/models/provider/provider_test.go index fde9cbce..e0b4a014 100644 --- a/internal/models/provider/provider_test.go +++ b/internal/models/provider/provider_test.go @@ -48,6 +48,8 @@ func TestDetectProvider(t *testing.T) { {"https://api.xiaomimimo.com/v1", ProviderMimo}, {"https://custom-endpoint.example.com/v1", ProviderGeneric}, {"http://localhost:11434/v1", ProviderGeneric}, + {"https://integrate.api.nvidia.com/v1", ProviderNvidia}, + {"https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking", ProviderNvidia}, } for _, tt := range tests { diff --git a/internal/models/rerank/nvidia_reranker.go b/internal/models/rerank/nvidia_reranker.go new file mode 100644 index 00000000..13097ed8 --- /dev/null +++ b/internal/models/rerank/nvidia_reranker.go @@ -0,0 +1,138 @@ +package rerank + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + + "github.com/Tencent/WeKnora/internal/logger" +) + +// NvidiaReranker implements a reranking system using Jina AI API +// Jina API uses different parameters than standard OpenAI-compatible APIs +type NvidiaReranker struct { + modelName string // Name of the model used for reranking + modelID string // Unique identifier of the model + apiKey string // API key for authentication + baseURL string // Base URL for API requests + client *http.Client // HTTP client for making API requests +} +type NvidiaRerankDocument struct { + Text string `json:"text"` +} + +// NvidiaRerankRequest represents a Jina rerank request +// Note: Jina does NOT support truncate_prompt_tokens parameter +type NvidiaRerankRequest struct { + Model string `json:"model"` // Model to use for reranking + Query NvidiaRerankDocument `json:"query"` // Query text to compare documents against + Documents []NvidiaRerankDocument `json:"passages"` // List of document texts to rerank +} + +type NvidiaRankResult struct { + Index int `json:"index"` + RelevanceScore float64 `json:"logit"` +} + +// NvidiaRerankResponse represents the response from a Jina reranking request +type NvidiaRerankResponse struct { + Model string `json:"model"` // Model used for reranking + Results []NvidiaRankResult `json:"rankings"` // Ranked results with relevance scores +} + +// NewNvidiaReranker creates a new instance of Jina reranker with the provided configuration +func NewNvidiaReranker(config *RerankerConfig) (*NvidiaReranker, error) { + apiKey := config.APIKey + baseURL := "https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking" + if url := config.BaseURL; url != "" { + baseURL = url + } + + return &NvidiaReranker{ + modelName: config.ModelName, + modelID: config.ModelID, + apiKey: apiKey, + baseURL: baseURL, + client: &http.Client{ + Transport: &http.Transport{ + Proxy: http.ProxyFromEnvironment, + }, + }, + }, nil +} + +// Rerank performs document reranking based on relevance to the query +func (r *NvidiaReranker) Rerank(ctx context.Context, query string, documents []string) ([]RankResult, error) { + // Build the request body - Jina does NOT use truncate_prompt_tokens + requestBody := &NvidiaRerankRequest{ + Model: r.modelName, + Query: NvidiaRerankDocument{Text: query}, + Documents: make([]NvidiaRerankDocument, len(documents)), + } + for i := range requestBody.Documents { + requestBody.Documents[i].Text = documents[i] + } + + jsonData, err := json.Marshal(requestBody) + if err != nil { + return nil, fmt.Errorf("marshal request body: %w", err) + } + + // Send the request + req, err := http.NewRequestWithContext(ctx, "POST", r.baseURL, bytes.NewBuffer(jsonData)) + if err != nil { + return nil, fmt.Errorf("create request: %w", err) + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", r.apiKey)) + + // Log the curl equivalent for debugging (API key masked for security) + logger.GetLogger(ctx).Infof( + "curl -X POST %s/rerank -H \"Content-Type: application/json\" -H \"Authorization: Bearer ***\" -d '%s'", + r.baseURL, string(jsonData), + ) + + resp, err := r.client.Do(req) + if err != nil { + return nil, fmt.Errorf("do request: %w", err) + } + defer resp.Body.Close() + + // Read the response + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("read response body: %w", err) + } + + if resp.StatusCode != http.StatusOK { + logger.GetLogger(ctx).Errorf("JinaReranker API error: Http Status: %s, Body: %s", resp.Status, string(body)) + return nil, fmt.Errorf("Rerank API error: Http Status: %s", resp.Status) + } + + var response NvidiaRerankResponse + if err := json.Unmarshal(body, &response); err != nil { + return nil, fmt.Errorf("unmarshal response: %w", err) + } + ret := make([]RankResult, len(response.Results)) + for i, result := range response.Results { + ret[i] = RankResult{ + Index: result.Index, + Document: DocumentInfo{Text: documents[result.Index]}, + RelevanceScore: result.RelevanceScore, + } + } + return ret, nil +} + +// GetModelName returns the name of the reranking model +func (r *NvidiaReranker) GetModelName() string { + return r.modelName +} + +// GetModelID returns the unique identifier of the reranking model +func (r *NvidiaReranker) GetModelID() string { + return r.modelID +} diff --git a/internal/models/rerank/reranker.go b/internal/models/rerank/reranker.go index d9e7d321..5ed45dba 100644 --- a/internal/models/rerank/reranker.go +++ b/internal/models/rerank/reranker.go @@ -101,6 +101,8 @@ func NewReranker(config *RerankerConfig) (Reranker, error) { return NewZhipuReranker(config) case provider.ProviderJina: return NewJinaReranker(config) + case provider.ProviderNvidia: + return NewNvidiaReranker(config) default: return NewOpenAIReranker(config) } diff --git a/internal/types/const.go b/internal/types/const.go index db586915..dcbe343e 100644 --- a/internal/types/const.go +++ b/internal/types/const.go @@ -19,6 +19,8 @@ const ( // SessionTenantIDContextKey is the context key for session owner's tenant ID. // When set (e.g. in pipeline with shared agent), session/message lookups use this instead of TenantIDContextKey. SessionTenantIDContextKey ContextKey = "SessionTenantID" + // EmbedQueryContextKey is the context key for embedding query text + EmbedQueryContextKey ContextKey = "EmbedQuery" ) // String returns the string representation of the context key From a355ac889e47f2ac6bb1a4177f8e066e860c7570 Mon Sep 17 00:00:00 2001 From: Manx98 Date: Wed, 11 Mar 2026 10:48:26 +0800 Subject: [PATCH 03/35] feat: NVIDIA chat model API support custom endpoint --- frontend/src/components/ModelEditorDialog.vue | 2 +- internal/models/chat/chat.go | 3 ++ internal/models/chat/nvidia.go | 34 ++++++++++++++ internal/models/chat/remote_api.go | 46 +++++++++++++++---- internal/models/provider/nvidia.go | 2 +- 5 files changed, 76 insertions(+), 11 deletions(-) create mode 100644 internal/models/chat/nvidia.go diff --git a/frontend/src/components/ModelEditorDialog.vue b/frontend/src/components/ModelEditorDialog.vue index b1918d30..7db7a57a 100644 --- a/frontend/src/components/ModelEditorDialog.vue +++ b/frontend/src/components/ModelEditorDialog.vue @@ -360,7 +360,7 @@ const fallbackProviderOptions = computed(() => [ value: 'nvidia', label: t('model.editor.providers.nvidia.label'), defaultUrls: { - chat: 'https://integrate.api.nvidia.com/v1', + chat: 'https://integrate.api.nvidia.com/v1/chat/completions', embedding: 'https://integrate.api.nvidia.com/v1', rerank: 'https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking', vllm: 'https://integrate.api.nvidia.com/v1', diff --git a/internal/models/chat/chat.go b/internal/models/chat/chat.go index 781804fb..2cb1752a 100644 --- a/internal/models/chat/chat.go +++ b/internal/models/chat/chat.go @@ -121,6 +121,9 @@ func NewRemoteChat(config *ChatConfig) (Chat, error) { case provider.ProviderGeneric: // Generic provider (如 vLLM) 使用 ChatTemplateKwargs return NewGenericChat(config) + case provider.ProviderNvidia: + // NVIDIA provider 使用BaseURL为请求地址 + return NewNvidiaChat(config) default: // 其他 provider 使用标准 OpenAI 兼容实现 return NewRemoteAPIChat(config) diff --git a/internal/models/chat/nvidia.go b/internal/models/chat/nvidia.go new file mode 100644 index 00000000..08ad176b --- /dev/null +++ b/internal/models/chat/nvidia.go @@ -0,0 +1,34 @@ +package chat + +import ( + "github.com/Tencent/WeKnora/internal/models/provider" +) + +// NvidiaChat NVIDIA 模型聊天实现 +// NVIDIA 模型需要自定义请求地址 +type NvidiaChat struct { + *RemoteAPIChat +} + +// NewNvidiaChat 创建 NVIDIA 聊天实例 +func NewNvidiaChat(config *ChatConfig) (*NvidiaChat, error) { + config.Provider = string(provider.ProviderAliyun) + + remoteChat, err := NewRemoteAPIChat(config) + if err != nil { + return nil, err + } + + chat := &NvidiaChat{ + RemoteAPIChat: remoteChat, + } + + // 设置请求地址自定义器 + remoteChat.SetEndpointCustomizer(chat.endpointCustomizer) + return chat, nil +} + +// customizeRequest 自定义 Qwen 请求 +func (c *NvidiaChat) endpointCustomizer(baseURL string, modelID string, isStream bool) string { + return baseURL +} diff --git a/internal/models/chat/remote_api.go b/internal/models/chat/remote_api.go index 1900fd05..c7ad5c6f 100644 --- a/internal/models/chat/remote_api.go +++ b/internal/models/chat/remote_api.go @@ -28,6 +28,10 @@ type RemoteAPIChat struct { // requestCustomizer 允许子类自定义请求 // 返回自定义请求体(如果为 nil 则使用标准请求)和是否需要使用原始 HTTP 请求 requestCustomizer func(req *openai.ChatCompletionRequest, opts *ChatOptions, isStream bool) (customReq any, useRawHTTP bool) + + // endpointCustomizer 允许子类自定义请求的 endpoint + // 返回是否使用自定义请求地址, 返回空则使用默认OpenAI格式地址 + endpointCustomizer func(baseURL string, modelID string, isStream bool) (endpoint string) } // NewRemoteAPIChat 创建远程 API 聊天实例 @@ -58,6 +62,11 @@ func (c *RemoteAPIChat) SetRequestCustomizer(customizer func(req *openai.ChatCom c.requestCustomizer = customizer } +// SetEndpointCustomizer 设置请求地址自定义器 +func (c *RemoteAPIChat) SetEndpointCustomizer(customizer func(baseURL string, modelID string, isStream bool) string) { + c.endpointCustomizer = customizer +} + // ConvertMessages 转换消息格式为 OpenAI 格式(导出供子类使用) func (c *RemoteAPIChat) ConvertMessages(messages []Message) []openai.ChatCompletionMessage { openaiMessages := make([]openai.ChatCompletionMessage, 0, len(messages)) @@ -178,15 +187,23 @@ func (c *RemoteAPIChat) logRequest(ctx context.Context, req any, isStream bool) // Chat 进行非流式聊天 func (c *RemoteAPIChat) Chat(ctx context.Context, messages []Message, opts *ChatOptions) (*types.ChatResponse, error) { req := c.BuildChatCompletionRequest(messages, opts, false) - + var customEndpoint string + if c.endpointCustomizer != nil { + customEndpoint = c.endpointCustomizer(c.baseURL, c.modelID, true) + } // 检查是否需要自定义请求 if c.requestCustomizer != nil { customReq, useRawHTTP := c.requestCustomizer(&req, opts, false) if useRawHTTP && customReq != nil { - return c.chatWithRawHTTP(ctx, customReq) + return c.chatWithRawHTTP(ctx, customEndpoint, customReq) } } + // 使用自定义请求地址 + if customEndpoint != "" { + return c.chatWithRawHTTP(ctx, customEndpoint, &req) + } + c.logRequest(ctx, req, false) resp, err := c.client.CreateChatCompletion(ctx, req) @@ -198,15 +215,16 @@ func (c *RemoteAPIChat) Chat(ctx context.Context, messages []Message, opts *Chat } // chatWithRawHTTP 使用原始 HTTP 请求进行聊天(供自定义请求使用) -func (c *RemoteAPIChat) chatWithRawHTTP(ctx context.Context, customReq any) (*types.ChatResponse, error) { +func (c *RemoteAPIChat) chatWithRawHTTP(ctx context.Context, endpoint string, customReq any) (*types.ChatResponse, error) { jsonData, err := json.Marshal(customReq) if err != nil { return nil, fmt.Errorf("marshal request: %w", err) } logger.Infof(ctx, "[LLM Request] model=%s, raw HTTP request:\n%s", c.modelName, string(jsonData)) - - endpoint := c.baseURL + "/chat/completions" + if endpoint == "" { + endpoint = c.baseURL + "/chat/completions" + } httpReq, err := http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewBuffer(jsonData)) if err != nil { return nil, fmt.Errorf("create request: %w", err) @@ -304,14 +322,22 @@ func removeThinkingContent(content string) string { func (c *RemoteAPIChat) ChatStream(ctx context.Context, messages []Message, opts *ChatOptions) (<-chan types.StreamResponse, error) { req := c.BuildChatCompletionRequest(messages, opts, true) + var customEndpoint string + if c.endpointCustomizer != nil { + customEndpoint = c.endpointCustomizer(c.baseURL, c.modelID, true) + } + // 检查是否需要自定义请求 if c.requestCustomizer != nil { customReq, useRawHTTP := c.requestCustomizer(&req, opts, true) if useRawHTTP && customReq != nil { - return c.chatStreamWithRawHTTP(ctx, customReq) + return c.chatStreamWithRawHTTP(ctx, customEndpoint, customReq) } } - + // 使用自定义请求地址 + if customEndpoint != "" { + return c.chatStreamWithRawHTTP(ctx, customEndpoint, &req) + } c.logRequest(ctx, req, true) streamChan := make(chan types.StreamResponse) @@ -328,7 +354,7 @@ func (c *RemoteAPIChat) ChatStream(ctx context.Context, messages []Message, opts } // chatStreamWithRawHTTP 使用原始 HTTP 请求进行流式聊天 -func (c *RemoteAPIChat) chatStreamWithRawHTTP(ctx context.Context, customReq any) (<-chan types.StreamResponse, error) { +func (c *RemoteAPIChat) chatStreamWithRawHTTP(ctx context.Context, endpoint string, customReq any) (<-chan types.StreamResponse, error) { jsonData, err := json.Marshal(customReq) if err != nil { return nil, fmt.Errorf("marshal request: %w", err) @@ -336,7 +362,9 @@ func (c *RemoteAPIChat) chatStreamWithRawHTTP(ctx context.Context, customReq any logger.Infof(ctx, "[LLM Stream] model=%s", c.modelName) - endpoint := c.baseURL + "/chat/completions" + if endpoint == "" { + endpoint = c.baseURL + "/chat/completions" + } httpReq, err := http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewBuffer(jsonData)) if err != nil { return nil, fmt.Errorf("create request: %w", err) diff --git a/internal/models/provider/nvidia.go b/internal/models/provider/nvidia.go index 9fb87c0d..6f2a9305 100644 --- a/internal/models/provider/nvidia.go +++ b/internal/models/provider/nvidia.go @@ -8,7 +8,7 @@ import ( const ( // NvidiaChatBaseURL NVIDIA Chat 的默认 BaseURL - NvidiaChatBaseURL = "https://integrate.api.nvidia.com/v1" + NvidiaChatBaseURL = "https://integrate.api.nvidia.com/v1/chat/completions" // NvidiaRerankBaseURL NVIDIA Rerank 的默认 BaseURL NvidiaRerankBaseURL = "https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking" ) From 447fac4b54d5f92aabb009c5656b35ee14156df8 Mon Sep 17 00:00:00 2001 From: Manx98 Date: Wed, 11 Mar 2026 11:50:58 +0800 Subject: [PATCH 04/35] fix: NVIDIA VLM model API default BaseURL --- internal/models/provider/nvidia.go | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/internal/models/provider/nvidia.go b/internal/models/provider/nvidia.go index 6f2a9305..3f958eff 100644 --- a/internal/models/provider/nvidia.go +++ b/internal/models/provider/nvidia.go @@ -9,6 +9,8 @@ import ( const ( // NvidiaChatBaseURL NVIDIA Chat 的默认 BaseURL NvidiaChatBaseURL = "https://integrate.api.nvidia.com/v1/chat/completions" + // NvidiaVLMBaseURL NVIDIA VLM 的默认 BaseURL + NvidiaVLMBaseURL = "https://integrate.api.nvidia.com/v1" // NvidiaRerankBaseURL NVIDIA Rerank 的默认 BaseURL NvidiaRerankBaseURL = "https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking" ) @@ -30,7 +32,7 @@ func (p *NvidiaProvider) Info() ProviderInfo { types.ModelTypeKnowledgeQA: NvidiaChatBaseURL, types.ModelTypeEmbedding: NvidiaChatBaseURL, types.ModelTypeRerank: NvidiaRerankBaseURL, - types.ModelTypeVLLM: NvidiaChatBaseURL, + types.ModelTypeVLLM: NvidiaVLMBaseURL, }, ModelTypes: []types.ModelType{ types.ModelTypeKnowledgeQA, From 166f106b7fde7ec8bfe31d2c3d44ab4e323f45b5 Mon Sep 17 00:00:00 2001 From: ChenRussell <792608290@qq.com> Date: Fri, 13 Mar 2026 18:26:20 +0800 Subject: [PATCH 05/35] fix: ensure builtin engine handles simple formats correctly Builtin engine was incorrectly falling back to simple engine for md/txt/csv files. Added explicit builtin engine check in selection logic. Fixes #755 --- internal/application/service/knowledge.go | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.go index 36664879..868efd5a 100644 --- a/internal/application/service/knowledge.go +++ b/internal/application/service/knowledge.go @@ -7449,7 +7449,11 @@ func (s *knowledgeService) resolveDocReader(engine, fileType string, isURL bool, return docparser.NewMinerUReader(overrides) case "mineru_cloud": return docparser.NewMinerUCloudReader(overrides) + case "builtin": + // 明确指定使用 builtin 引擎(docreader),不使用 simple format 兜底 + return s.documentReader default: + // 未指定引擎时的兜底逻辑:simple format 使用 Go 原生处理,其他使用 docreader if !isURL && docparser.IsSimpleFormat(fileType) { return &docparser.SimpleFormatReader{} } From 0fe5d67b6a53393d0bee104a4b9e18af8975d939 Mon Sep 17 00:00:00 2001 From: ChenRussell <792608290@qq.com> Date: Fri, 13 Mar 2026 20:24:45 +0800 Subject: [PATCH 06/35] fix: enforce 7500 char limit in chunker to prevent embedding API errors Prevents 400 Bad Request errors when uploading documents with large tables or code blocks by adding hard limits in buildUnitsWithProtection and mergeUnits functions. --- internal/infrastructure/chunker/splitter.go | 98 +++++++++++++++++++-- internal/models/embedding/openai.go | 37 +++++++- 2 files changed, 128 insertions(+), 7 deletions(-) diff --git a/internal/infrastructure/chunker/splitter.go b/internal/infrastructure/chunker/splitter.go index 37dff63d..fefae05e 100644 --- a/internal/infrastructure/chunker/splitter.go +++ b/internal/infrastructure/chunker/splitter.go @@ -167,7 +167,11 @@ func SplitText(text string, cfg SplitterConfig) []Chunk { // buildUnitsWithProtection splits text into units, preserving protected spans as atomic. // Start/End positions in the returned units are rune offsets (not byte offsets), // because downstream merge logic indexes content via []rune slicing. +// If a protected span exceeds maxProtectedSize, it will be forcibly split to prevent +// creating chunks that are too large for downstream processing (e.g., embedding APIs). func buildUnitsWithProtection(text string, protected []span, separators []string) []splitUnit { + const maxProtectedSize = 7500 // Maximum size for a protected unit (留余量给标题等) + var units []splitUnit bytePos := 0 runePos := 0 @@ -191,11 +195,43 @@ func buildUnitsWithProtection(text string, protected []span, separators []string protText := text[p.start:p.end] protRuneLen := runeLen(protText) - units = append(units, splitUnit{ - text: protText, - start: runePos, - end: runePos + protRuneLen, - }) + + // If protected content is too large, forcibly split it + if protRuneLen > maxProtectedSize { + // Split into smaller chunks at line breaks or spaces + runes := []rune(protText) + offset := 0 + for offset < len(runes) { + chunkEnd := offset + maxProtectedSize + if chunkEnd > len(runes) { + chunkEnd = len(runes) + } else { + // Try to break at a newline or space + for i := chunkEnd - 1; i > offset && i > chunkEnd-200; i-- { + if runes[i] == '\n' || runes[i] == ' ' { + chunkEnd = i + 1 + break + } + } + } + + chunkText := string(runes[offset:chunkEnd]) + chunkLen := chunkEnd - offset + units = append(units, splitUnit{ + text: chunkText, + start: runePos + offset, + end: runePos + offset + chunkLen, + }) + offset = chunkEnd + } + } else { + // Normal case: keep protected content as a single unit + units = append(units, splitUnit{ + text: protText, + start: runePos, + end: runePos + protRuneLen, + }) + } runePos += protRuneLen bytePos = p.end } @@ -219,11 +255,15 @@ func buildUnitsWithProtection(text string, protected []span, separators []string } // mergeUnits combines split units into chunks with overlap tracking. +// Enforces an absolute maximum chunk size to prevent exceeding downstream limits (e.g., embedding APIs). func mergeUnits(units []splitUnit, chunkSize, chunkOverlap int) []Chunk { if len(units) == 0 { return nil } + // Absolute maximum chunk size (留余量给标题等额外内容) + const absoluteMaxSize = 7500 + var chunks []Chunk var current []splitUnit curLen := 0 @@ -231,6 +271,44 @@ func mergeUnits(units []splitUnit, chunkSize, chunkOverlap int) []Chunk { for _, u := range units { uLen := runeLen(u.text) + // If this single unit exceeds absolute max, force split it further + if uLen > absoluteMaxSize { + // Flush current chunk if any + if len(current) > 0 { + chunks = append(chunks, buildChunk(current, len(chunks))) + current = nil + curLen = 0 + } + + // Split this oversized unit into smaller chunks + runes := []rune(u.text) + offset := 0 + for offset < len(runes) { + chunkEnd := offset + absoluteMaxSize + if chunkEnd > len(runes) { + chunkEnd = len(runes) + } else { + // Try to break at a newline or space + for i := chunkEnd - 1; i > offset && i > chunkEnd-200; i-- { + if runes[i] == '\n' || runes[i] == ' ' { + chunkEnd = i + 1 + break + } + } + } + + chunkText := string(runes[offset:chunkEnd]) + chunks = append(chunks, Chunk{ + Content: chunkText, + Seq: len(chunks), + Start: u.start + offset, + End: u.start + chunkEnd, + }) + offset = chunkEnd + } + continue + } + // If adding this unit exceeds chunk size and we have content, flush if curLen+uLen > chunkSize && len(current) > 0 { chunks = append(chunks, buildChunk(current, len(chunks))) @@ -239,6 +317,16 @@ func mergeUnits(units []splitUnit, chunkSize, chunkOverlap int) []Chunk { current, curLen = computeOverlap(current, chunkOverlap, chunkSize, uLen) } + // Check if adding this unit would exceed absolute max + if curLen+uLen > absoluteMaxSize { + // Flush current and start fresh + if len(current) > 0 { + chunks = append(chunks, buildChunk(current, len(chunks))) + current = nil + curLen = 0 + } + } + current = append(current, u) curLen += uLen } diff --git a/internal/models/embedding/openai.go b/internal/models/embedding/openai.go index 3c13fdb8..7e495e13 100644 --- a/internal/models/embedding/openai.go +++ b/internal/models/embedding/openai.go @@ -149,6 +149,34 @@ func (e *OpenAIEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl return nil, fmt.Errorf("marshal request: %w", err) } + // Log request details for debugging + logger.GetLogger(ctx).Debugf("OpenAIEmbedder BatchEmbed: model=%s, input_count=%d, truncate_tokens=%d", + e.modelName, len(texts), e.truncatePromptTokens) + + // Check for invalid input lengths and log details + hasInvalidLength := false + for i, text := range texts { + textLen := len(text) + textPreview := text + if len(textPreview) > 200 { + textPreview = textPreview[:200] + "..." + } + + // Log warning if length is outside valid range [1, 8192] + if textLen == 0 || textLen > 8192 { + hasInvalidLength = true + logger.GetLogger(ctx).Errorf("OpenAIEmbedder BatchEmbed input[%d]: INVALID length=%d (must be [1, 8192]), preview=%s", + i, textLen, textPreview) + } else { + logger.GetLogger(ctx).Debugf("OpenAIEmbedder BatchEmbed input[%d]: length=%d, preview=%s", + i, textLen, textPreview) + } + } + + if hasInvalidLength { + logger.GetLogger(ctx).Errorf("OpenAIEmbedder BatchEmbed: Found invalid input lengths, this will likely cause API error") + } + // Send request (passing jsonData instead of constructing http.Request) resp, err := e.doRequestWithRetry(ctx, jsonData) if err != nil { @@ -167,8 +195,13 @@ func (e *OpenAIEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl } if resp.StatusCode != http.StatusOK { - logger.GetLogger(ctx).Errorf("OpenAIEmbedder EmbedBatch API error: Http Status %s", resp.Status) - return nil, fmt.Errorf("EmbedBatch API error: Http Status %s", resp.Status) + // Log detailed error response from OpenAI API + bodyStr := string(body) + if len(bodyStr) > 1000 { + bodyStr = bodyStr[:1000] + "... (truncated)" + } + logger.GetLogger(ctx).Errorf("OpenAIEmbedder EmbedBatch API error: Http Status %s, Response Body: %s", resp.Status, bodyStr) + return nil, fmt.Errorf("EmbedBatch API error: Http Status %s, Response: %s", resp.Status, bodyStr) } // Parse response From 0e8f1b1c81f9f0cddc62dc94d74863dee9e21e59 Mon Sep 17 00:00:00 2001 From: AndyYang Date: Sun, 15 Mar 2026 11:09:20 +0800 Subject: [PATCH 07/35] fix: improve auth error messages and unify username validation length --- internal/handler/auth.go | 2 +- internal/types/user.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/internal/handler/auth.go b/internal/handler/auth.go index aabe3528..58fb8d38 100644 --- a/internal/handler/auth.go +++ b/internal/handler/auth.go @@ -87,7 +87,7 @@ func (h *AuthHandler) Register(c *gin.Context) { user, err := h.userService.Register(ctx, &req) if err != nil { logger.Errorf(ctx, "Failed to register user: %v", err) - appErr := errors.NewBadRequestError("Registration failed").WithDetails(err.Error()) + appErr := errors.NewBadRequestError(err.Error()) c.Error(appErr) return } diff --git a/internal/types/user.go b/internal/types/user.go index 333c0055..1c28cfbf 100644 --- a/internal/types/user.go +++ b/internal/types/user.go @@ -66,7 +66,7 @@ type LoginRequest struct { // RegisterRequest represents a registration request type RegisterRequest struct { - Username string `json:"username" binding:"required,min=3,max=50"` + Username string `json:"username" binding:"required,min=2,max=50"` Email string `json:"email" binding:"required,email"` Password string `json:"password" binding:"required,min=6"` } From 9fa969fb5cbbb902c3076b0aa5bf0fab271cb71f Mon Sep 17 00:00:00 2001 From: nullkey Date: Sun, 15 Mar 2026 18:45:53 +0800 Subject: [PATCH 08/35] feat: add WeCom and Feishu IM bot integration - support webhook and websocket modes for both platforms - add im_channel_sessions migration for channel-session mapping - register IM adapters and callback routes - update config and docker-compose for IM env vars --- config/config.yaml | 43 +- docker-compose.yml | 9 +- go.mod | 3 +- go.sum | 2 + internal/config/config.go | 40 ++ internal/container/container.go | 121 +++++ internal/handler/im.go | 132 ++++++ internal/im/adapter.go | 76 ++++ internal/im/feishu/adapter.go | 424 ++++++++++++++++++ internal/im/feishu/longconn.go | 149 ++++++ internal/im/service.go | 378 ++++++++++++++++ internal/im/types.go | 40 ++ internal/im/wecom/adapter.go | 369 +++++++++++++++ internal/im/wecom/bot_adapter.go | 42 ++ internal/im/wecom/longconn.go | 353 +++++++++++++++ internal/router/router.go | 17 + .../000021_im_channel_sessions.down.sql | 1 + .../000021_im_channel_sessions.up.sql | 44 ++ 18 files changed, 2239 insertions(+), 4 deletions(-) create mode 100644 internal/handler/im.go create mode 100644 internal/im/adapter.go create mode 100644 internal/im/feishu/adapter.go create mode 100644 internal/im/feishu/longconn.go create mode 100644 internal/im/service.go create mode 100644 internal/im/types.go create mode 100644 internal/im/wecom/adapter.go create mode 100644 internal/im/wecom/bot_adapter.go create mode 100644 internal/im/wecom/longconn.go create mode 100644 migrations/versioned/000021_im_channel_sessions.down.sql create mode 100644 migrations/versioned/000021_im_channel_sessions.up.sql diff --git a/config/config.yaml b/config/config.yaml index 299269c1..4f502e85 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -206,7 +206,12 @@ conversation: - If the user asks in English, respond in English - If the user asks in Chinese, respond in Chinese - context_template: "{{query}}" + context_template: | + The following is retrieved information: + {{contexts}} + + Based on the above retrieved information, answer the following question: + {{query}} extract_entities_prompt: | ## Task Extract all entities from the user-provided text that match the following entity types: @@ -536,3 +541,39 @@ extract: tenant: # Enable cross-tenant access (can be enabled for intranet environments) enable_cross_tenant_access: false + +# IM integration configuration (optional) +# Uncomment and configure to enable WeCom/Feishu bot integration +# +# mode: +# "webhook" — (default) platform pushes events to your callback URL, requires public domain +# "websocket" — long connection, no public domain needed, SDK maintains persistent connection +im: + wecom: + enabled: true + tenant_id: 10000 # WeKnora tenant ID to use + agent_id: "" # Default agent ID (optional) + knowledge_base_ids: + - "" # Default knowledge bases (optional) + mode: "websocket" # "webhook" or "websocket" + # --- websocket mode (智能机器人长连接) --- + bot_id: "${WECOM_BOT_ID}" # 智能机器人 Bot ID + bot_secret: "${WECOM_BOT_SECRET}" # 智能机器人 Secret + # --- webhook mode (自建应用回调) --- + # corp_id: "${WECOM_CORP_ID}" # 企业微信 Corp ID + # agent_secret: "${WECOM_AGENT_SECRET}" # 应用 Secret + # token: "${WECOM_TOKEN}" # 回调 Token + # encoding_aes_key: "${WECOM_AES_KEY}" # 回调 EncodingAESKey + # corp_agent_id: 1000001 # 应用 AgentID + feishu: + enabled: true + tenant_id: 10000 # WeKnora tenant ID to use + agent_id: "" # Default agent ID (optional) + knowledge_base_ids: # Default knowledge bases + - "" + mode: "websocket" # "webhook" or "websocket" + app_id: "${FEISHU_APP_ID}" # 飞书 App ID + app_secret: "${FEISHU_APP_SECRET}" # 飞书 App Secret + # --- 以下仅 webhook 模式需要,websocket 模式可留空 --- + # verification_token: "${FEISHU_TOKEN}" # 事件订阅 Verification Token (webhook only) + # encrypt_key: "${FEISHU_ENCRYPT_KEY}" # 事件订阅 Encrypt Key (webhook only) diff --git a/docker-compose.yml b/docker-compose.yml index 11c731d6..527a6d8b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -38,8 +38,8 @@ services: volumes: - data-files:/data/files - docreader-tmp:/tmp/docreader:ro - # Optional: mount custom config file - # - ./config/config.yaml:/app/config/config.yaml + # Mount custom config file (required for IM integration) + - ./config/config.yaml:/app/config/config.yaml # Optional: mount custom skills directory (allows adding skills without rebuilding image) - ./skills/preloaded:/app/skills/preloaded healthcheck: @@ -114,6 +114,11 @@ services: - SYSTEM_AES_KEY=${SYSTEM_AES_KEY:-} - CONCURRENCY_POOL_SIZE=${CONCURRENCY_POOL_SIZE:-5} - JWT_SECRET=${JWT_SECRET:-} + # IM integration + - FEISHU_APP_ID=${FEISHU_APP_ID:-} + - FEISHU_APP_SECRET=${FEISHU_APP_SECRET:-} + - WECOM_BOT_ID=${WECOM_BOT_ID:-} + - WECOM_BOT_SECRET=${WECOM_BOT_SECRET:-} # File size limit (in MB) - MAX_FILE_SIZE_MB=${MAX_FILE_SIZE_MB:-50} # Agent Skills Sandbox diff --git a/go.mod b/go.mod index d949c88a..74f030ef 100644 --- a/go.mod +++ b/go.mod @@ -22,7 +22,9 @@ require ( github.com/golang-migrate/migrate/v4 v4.19.1 github.com/google/jsonschema-go v0.4.2 github.com/google/uuid v1.6.0 + github.com/gorilla/websocket v1.5.0 github.com/hibiken/asynq v0.25.1 + github.com/larksuite/oapi-sdk-go/v3 v3.5.3 github.com/mark3labs/mcp-go v0.43.0 github.com/milvus-io/milvus/client/v2 v2.6.2 github.com/minio/minio-go/v7 v7.0.91 @@ -167,7 +169,6 @@ require ( github.com/google/s2a-go v0.1.9 // indirect github.com/googleapis/enterprise-certificate-proxy v0.3.7 // indirect github.com/googleapis/gax-go/v2 v2.16.0 // indirect - github.com/gorilla/websocket v1.5.0 // indirect github.com/grpc-ecosystem/go-grpc-middleware v1.4.0 // indirect github.com/grpc-ecosystem/go-grpc-prometheus v1.2.0 // indirect github.com/grpc-ecosystem/grpc-gateway v1.16.0 // indirect diff --git a/go.sum b/go.sum index 48921a4d..78b2cedf 100644 --- a/go.sum +++ b/go.sum @@ -2085,6 +2085,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw= github.com/labstack/echo/v4 v4.5.0/go.mod h1:czIriw4a0C1dFun+ObrXp7ok03xON0N1awStJ6ArI7Y= github.com/labstack/gommon v0.3.0/go.mod h1:MULnywXg0yavhxWKc+lOruYdAhDwPK9wf0OL7NoOu+k= +github.com/larksuite/oapi-sdk-go/v3 v3.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk= +github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI= github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo= github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs= github.com/leodido/go-urn v1.2.0/go.mod h1:+8+nEpDfqqsY+g338gtMEUOtuK+4dEMhiQEgxpxOKII= diff --git a/internal/config/config.go b/internal/config/config.go index c691af6d..6405bce9 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -27,6 +27,46 @@ type Config struct { ExtractManager *ExtractManagerConfig `yaml:"extract" json:"extract"` WebSearch *WebSearchConfig `yaml:"web_search" json:"web_search"` PromptTemplates *PromptTemplatesConfig `yaml:"prompt_templates" json:"prompt_templates"` + IM *IMConfig `yaml:"im" json:"im"` +} + +// IMConfig IM 集成配置 +type IMConfig struct { + WeCom *WeComIMConfig `yaml:"wecom" json:"wecom"` + Feishu *FeishuIMConfig `yaml:"feishu" json:"feishu"` +} + +// WeComIMConfig 企业微信配置 +type WeComIMConfig struct { + Enabled bool `yaml:"enabled" json:"enabled"` + TenantID uint64 `yaml:"tenant_id" json:"tenant_id"` + AgentID string `yaml:"agent_id" json:"agent_id"` + KnowledgeBases []string `yaml:"knowledge_base_ids" json:"knowledge_base_ids"` + // Mode: "webhook" (default, requires public domain) or "websocket" (long connection via intelligent bot, no public domain needed) + Mode string `yaml:"mode" json:"mode"` + // --- Webhook mode fields (self-built app callback) --- + CorpID string `yaml:"corp_id" json:"corp_id"` + AgentSecret string `yaml:"agent_secret" json:"agent_secret"` + Token string `yaml:"token" json:"token"` + EncodingAESKey string `yaml:"encoding_aes_key" json:"encoding_aes_key"` + CorpAgentID int `yaml:"corp_agent_id" json:"corp_agent_id"` + // --- WebSocket mode fields (intelligent bot long connection) --- + BotID string `yaml:"bot_id" json:"bot_id"` + BotSecret string `yaml:"bot_secret" json:"bot_secret"` +} + +// FeishuIMConfig 飞书配置 +type FeishuIMConfig struct { + Enabled bool `yaml:"enabled" json:"enabled"` + TenantID uint64 `yaml:"tenant_id" json:"tenant_id"` + AgentID string `yaml:"agent_id" json:"agent_id"` + KnowledgeBases []string `yaml:"knowledge_base_ids" json:"knowledge_base_ids"` + AppID string `yaml:"app_id" json:"app_id"` + AppSecret string `yaml:"app_secret" json:"app_secret"` + VerificationToken string `yaml:"verification_token" json:"verification_token"` + EncryptKey string `yaml:"encrypt_key" json:"encrypt_key"` + // Mode: "websocket" (default, long connection, no public domain needed) or "webhook" (requires public domain) + Mode string `yaml:"mode" json:"mode"` } // DocReaderConfig configures the document parser client (gRPC or HTTP). diff --git a/internal/container/container.go b/internal/container/container.go index 4475f66e..ab1561cb 100644 --- a/internal/container/container.go +++ b/internal/container/container.go @@ -52,6 +52,9 @@ import ( "github.com/Tencent/WeKnora/internal/event" "github.com/Tencent/WeKnora/internal/handler" "github.com/Tencent/WeKnora/internal/handler/session" + imPkg "github.com/Tencent/WeKnora/internal/im" + "github.com/Tencent/WeKnora/internal/im/feishu" + "github.com/Tencent/WeKnora/internal/im/wecom" "github.com/Tencent/WeKnora/internal/infrastructure/docparser" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/mcp" @@ -235,6 +238,12 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(service.NewSkillService)) must(container.Provide(handler.NewSkillHandler)) must(container.Provide(handler.NewOrganizationHandler)) + + // IM integration + logger.Debugf(ctx, "[Container] Registering IM integration...") + must(container.Provide(imPkg.NewService)) + must(container.Invoke(registerIMAdapters)) + must(container.Provide(handler.NewIMHandler)) logger.Debugf(ctx, "[Container] HTTP handlers registered") // Router configuration @@ -937,3 +946,115 @@ func registerWebSearchProviders(registry *web_search.Registry) { return web_search.NewBingProvider() }) } + +// registerIMAdapters registers IM platform adapters based on configuration. +// For "websocket" mode, it also starts a long connection client in a goroutine. +func registerIMAdapters(cfg *config.Config, imService *imPkg.Service) { + if cfg.IM == nil { + logger.Infof(context.Background(), "[IM] No IM configuration found, skipping adapter registration") + return + } + + ctx := context.Background() + + // Register WeCom + if cfg.IM.WeCom != nil && cfg.IM.WeCom.Enabled { + registerWeComAdapter(ctx, cfg.IM.WeCom, imService) + } + + // Register Feishu + if cfg.IM.Feishu != nil && cfg.IM.Feishu.Enabled { + registerFeishuAdapter(ctx, cfg.IM.Feishu, imService) + } +} + +func registerWeComAdapter(ctx context.Context, cfg *config.WeComIMConfig, imService *imPkg.Service) { + mode := cfg.Mode + if mode == "" { + mode = "websocket" + } + + switch mode { + case "webhook": + adapter, err := wecom.NewAdapter( + cfg.CorpID, + cfg.AgentSecret, + cfg.Token, + cfg.EncodingAESKey, + cfg.CorpAgentID, + ) + if err != nil { + logger.Warnf(ctx, "[IM] Failed to create WeCom webhook adapter: %v", err) + return + } + imService.RegisterAdapter(adapter) + logger.Infof(ctx, "[IM] WeCom adapter registered (mode=webhook, corp_id=%s)", cfg.CorpID) + + case "websocket": + // Build the message handler that delegates to imService.HandleMessage + handler := func(msgCtx context.Context, msg *imPkg.IncomingMessage) error { + return imService.HandleMessage(msgCtx, msg, cfg.TenantID, cfg.AgentID, cfg.KnowledgeBases) + } + + client := wecom.NewLongConnClient(cfg.BotID, cfg.BotSecret, handler) + + // Register a BotAdapter so the service can send replies via WebSocket + imService.RegisterAdapter(wecom.NewBotAdapter(client)) + logger.Infof(ctx, "[IM] WeCom adapter registered (mode=websocket, bot_id=%s)", cfg.BotID) + + // Start the long connection in a goroutine + go func() { + if err := client.Start(context.Background()); err != nil { + logger.Errorf(context.Background(), "[IM] WeCom long connection stopped: %v", err) + } + }() + + default: + logger.Warnf(ctx, "[IM] Unknown WeCom mode: %s (expected 'webhook' or 'websocket')", mode) + } +} + +func registerFeishuAdapter(ctx context.Context, cfg *config.FeishuIMConfig, imService *imPkg.Service) { + mode := cfg.Mode + if mode == "" { + mode = "websocket" + } + + // Always register the HTTP adapter (needed for SendReply in both modes) + adapter := feishu.NewAdapter( + cfg.AppID, + cfg.AppSecret, + cfg.VerificationToken, + cfg.EncryptKey, + ) + imService.RegisterAdapter(adapter) + + switch mode { + case "webhook": + logger.Infof(ctx, "[IM] Feishu adapter registered (mode=webhook, app_id=%s)", cfg.AppID) + + case "websocket": + logger.Infof(ctx, "[IM] Feishu adapter registered (mode=websocket, app_id=%s)", cfg.AppID) + + // Build the message handler + handler := func(msgCtx context.Context, msg *imPkg.IncomingMessage) error { + return imService.HandleMessage(msgCtx, msg, cfg.TenantID, cfg.AgentID, cfg.KnowledgeBases) + } + + client := feishu.NewLongConnClient( + cfg.AppID, + cfg.AppSecret, + handler, + ) + + // Start the long connection in a goroutine + go func() { + if err := client.Start(context.Background()); err != nil { + logger.Errorf(context.Background(), "[IM] Feishu long connection stopped: %v", err) + } + }() + + default: + logger.Warnf(ctx, "[IM] Unknown Feishu mode: %s (expected 'webhook' or 'websocket')", mode) + } +} diff --git a/internal/handler/im.go b/internal/handler/im.go new file mode 100644 index 00000000..66379d55 --- /dev/null +++ b/internal/handler/im.go @@ -0,0 +1,132 @@ +package handler + +import ( + "context" + "net/http" + + "github.com/Tencent/WeKnora/internal/config" + "github.com/Tencent/WeKnora/internal/im" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/gin-gonic/gin" +) + +// IMHandler handles IM platform callback requests. +type IMHandler struct { + imService *im.Service + config *config.Config +} + +// NewIMHandler creates a new IM handler. +func NewIMHandler(imService *im.Service, cfg *config.Config) *IMHandler { + return &IMHandler{ + imService: imService, + config: cfg, + } +} + +// WeComCallback handles WeCom callback requests (both URL verification and message events). +func (h *IMHandler) WeComCallback(c *gin.Context) { + ctx := c.Request.Context() + + adapter, ok := h.imService.GetAdapter(im.PlatformWeCom) + if !ok { + logger.Error(ctx, "[IM] WeCom adapter not registered") + c.JSON(http.StatusServiceUnavailable, gin.H{"error": "WeCom integration not enabled"}) + return + } + + // Handle URL verification (GET request) + if adapter.HandleURLVerification(c) { + return + } + + // Verify callback signature + if err := adapter.VerifyCallback(c); err != nil { + logger.Errorf(ctx, "[IM] WeCom callback verification failed: %v", err) + c.JSON(http.StatusForbidden, gin.H{"error": "verification failed"}) + return + } + + // Parse the callback message + msg, err := adapter.ParseCallback(c) + if err != nil { + logger.Errorf(ctx, "[IM] WeCom parse callback failed: %v", err) + c.JSON(http.StatusBadRequest, gin.H{"error": "parse failed"}) + return + } + + // If nil, it's a non-message event (e.g., system event) - just acknowledge + if msg == nil { + c.JSON(http.StatusOK, gin.H{"success": true}) + return + } + + // Respond immediately to avoid WeCom timeout, process asynchronously + c.JSON(http.StatusOK, gin.H{"success": true}) + + // Get config for this platform + wecomCfg := h.config.IM.WeCom + + // Detach from gin request context to prevent cancellation after HTTP response. + asyncCtx := context.WithoutCancel(ctx) + + // Process message asynchronously + go func() { + if err := h.imService.HandleMessage(asyncCtx, msg, wecomCfg.TenantID, wecomCfg.AgentID, wecomCfg.KnowledgeBases); err != nil { + logger.Errorf(asyncCtx, "[IM] WeCom handle message error: %v", err) + } + }() +} + +// FeishuCallback handles Feishu callback requests (both URL verification and message events). +func (h *IMHandler) FeishuCallback(c *gin.Context) { + ctx := c.Request.Context() + + adapter, ok := h.imService.GetAdapter(im.PlatformFeishu) + if !ok { + logger.Error(ctx, "[IM] Feishu adapter not registered") + c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Feishu integration not enabled"}) + return + } + + // Handle URL verification (challenge) + if adapter.HandleURLVerification(c) { + return + } + + // Verify callback + if err := adapter.VerifyCallback(c); err != nil { + logger.Errorf(ctx, "[IM] Feishu callback verification failed: %v", err) + c.JSON(http.StatusForbidden, gin.H{"error": "verification failed"}) + return + } + + // Parse the callback message + msg, err := adapter.ParseCallback(c) + if err != nil { + logger.Errorf(ctx, "[IM] Feishu parse callback failed: %v", err) + c.JSON(http.StatusBadRequest, gin.H{"error": "parse failed"}) + return + } + + if msg == nil { + c.JSON(http.StatusOK, gin.H{"success": true}) + return + } + + // Respond immediately + c.JSON(http.StatusOK, gin.H{"success": true}) + + // Get config + feishuCfg := h.config.IM.Feishu + + // Detach from gin request context to prevent cancellation after HTTP response. + asyncCtx := context.WithoutCancel(ctx) + + // Process asynchronously + go func() { + if err := h.imService.HandleMessage(asyncCtx, msg, feishuCfg.TenantID, feishuCfg.AgentID, feishuCfg.KnowledgeBases); err != nil { + logger.Errorf(asyncCtx, "[IM] Feishu handle message error: %v", err) + } + }() +} diff --git a/internal/im/adapter.go b/internal/im/adapter.go new file mode 100644 index 00000000..1cbe6396 --- /dev/null +++ b/internal/im/adapter.go @@ -0,0 +1,76 @@ +package im + +import ( + "context" + + "github.com/gin-gonic/gin" +) + +// Platform identifies an IM platform. +type Platform string + +const ( + PlatformWeCom Platform = "wecom" + PlatformFeishu Platform = "feishu" +) + +// IncomingMessage is the unified message parsed from an IM callback. +type IncomingMessage struct { + // Platform identifies which IM platform the message comes from. + Platform Platform + // 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. + Content string + // MessageID is the IM-platform message identifier (for dedup). + MessageID string + // Extra holds platform-specific fields (e.g., WeCom stream ID). + Extra map[string]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 +} diff --git a/internal/im/feishu/adapter.go b/internal/im/feishu/adapter.go new file mode 100644 index 00000000..ac5906fe --- /dev/null +++ b/internal/im/feishu/adapter.go @@ -0,0 +1,424 @@ +// Package feishu implements the Feishu (飞书/Lark) IM adapter for WeKnora. +// +// Feishu bot flow: +// 1. User sends a message to the bot (direct or @mention in group) +// 2. Feishu calls our event subscription URL with the message event +// 3. We parse the event, run QA, then call Feishu API to send reply +// 4. For streaming: create a card, then use CardKit streaming update API +// +// Reference: https://open.feishu.cn/document/server-docs/im-v1/message/create +package feishu + +import ( + "bytes" + "context" + "crypto/aes" + "crypto/cipher" + "crypto/sha256" + "encoding/base64" + "encoding/json" + "fmt" + "io" + "net/http" + "strings" + "sync" + "time" + + "github.com/Tencent/WeKnora/internal/im" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/gin-gonic/gin" +) + +var httpClient = &http.Client{Timeout: 10 * time.Second} + +// Adapter implements im.Adapter for Feishu/Lark. +type Adapter struct { + appID string + appSecret string + verificationToken string + encryptKey string + + // Token cache + tokenMu sync.Mutex + tokenCache string + tokenExpAt time.Time +} + +// NewAdapter creates a new Feishu adapter. +func NewAdapter(appID, appSecret, verificationToken, encryptKey string) *Adapter { + return &Adapter{ + appID: appID, + appSecret: appSecret, + verificationToken: verificationToken, + encryptKey: encryptKey, + } +} + +// Platform returns the platform identifier. +func (a *Adapter) Platform() im.Platform { + return im.PlatformFeishu +} + +// VerifyCallback verifies the Feishu event callback by checking the verification token. +// If no verification token is configured (e.g., WebSocket mode), skip verification. +func (a *Adapter) VerifyCallback(c *gin.Context) error { + if a.verificationToken == "" { + return nil + } + + bodyBytes, err := io.ReadAll(c.Request.Body) + if err != nil { + return fmt.Errorf("read body: %w", err) + } + // Always restore body for subsequent reads (ParseCallback) + defer func() { c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes)) }() + + var raw []byte + + // Handle encrypted events + var encryptedBody struct { + Encrypt string `json:"encrypt"` + } + if err := json.Unmarshal(bodyBytes, &encryptedBody); err == nil && encryptedBody.Encrypt != "" { + decrypted, err := a.decrypt(encryptedBody.Encrypt) + if err != nil { + return fmt.Errorf("decrypt event for verification: %w", err) + } + raw = decrypted + } else { + raw = bodyBytes + } + + var eventBody struct { + Header *feishuEventHeader `json:"header"` + } + if err := json.Unmarshal(raw, &eventBody); err != nil { + return fmt.Errorf("unmarshal event header: %w", err) + } + + if eventBody.Header == nil || eventBody.Header.Token != a.verificationToken { + return fmt.Errorf("invalid verification token") + } + + return nil +} + +// HandleURLVerification handles the Feishu URL verification challenge. +func (a *Adapter) HandleURLVerification(c *gin.Context) bool { + bodyBytes, err := io.ReadAll(c.Request.Body) + if err != nil { + return false + } + c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes)) + + // Try to parse as a challenge request + var body map[string]interface{} + + // If encrypted, try to decrypt first + var encryptedBody struct { + Encrypt string `json:"encrypt"` + } + if err := json.Unmarshal(bodyBytes, &encryptedBody); err == nil && encryptedBody.Encrypt != "" { + decrypted, err := a.decrypt(encryptedBody.Encrypt) + if err != nil { + logger.Errorf(c.Request.Context(), "[Feishu] Failed to decrypt: %v", err) + return false + } + if err := json.Unmarshal(decrypted, &body); err != nil { + return false + } + } else { + if err := json.Unmarshal(bodyBytes, &body); err != nil { + return false + } + } + + // Check if this is a URL verification challenge + if challenge, ok := body["challenge"].(string); ok { + c.JSON(http.StatusOK, gin.H{"challenge": challenge}) + return true + } + + // Reset body for subsequent reads + c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes)) + return false +} + +// feishuEventBody is the typed structure of a Feishu event callback. +type feishuEventBody struct { + Header *feishuEventHeader `json:"header"` + Event *feishuEvent `json:"event"` +} + +type feishuEventHeader struct { + EventType string `json:"event_type"` + Token string `json:"token"` +} + +type feishuEvent struct { + Message *feishuMessage `json:"message"` + Sender *feishuSender `json:"sender"` +} + +type feishuMessage struct { + MessageID string `json:"message_id"` + MessageType string `json:"message_type"` + ChatType string `json:"chat_type"` + ChatID string `json:"chat_id"` + Content string `json:"content"` +} + +type feishuSender struct { + SenderID *feishuSenderID `json:"sender_id"` +} + +type feishuSenderID struct { + OpenID string `json:"open_id"` +} + +// ParseCallback parses a Feishu event callback into a unified IncomingMessage. +func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { + bodyBytes, err := io.ReadAll(c.Request.Body) + if err != nil { + return nil, fmt.Errorf("read body: %w", err) + } + + var raw []byte + + // Handle encrypted events + var encryptedBody struct { + Encrypt string `json:"encrypt"` + } + if err := json.Unmarshal(bodyBytes, &encryptedBody); err == nil && encryptedBody.Encrypt != "" { + decrypted, err := a.decrypt(encryptedBody.Encrypt) + if err != nil { + return nil, fmt.Errorf("decrypt event: %w", err) + } + raw = decrypted + } else { + raw = bodyBytes + } + + var eventBody feishuEventBody + if err := json.Unmarshal(raw, &eventBody); err != nil { + return nil, fmt.Errorf("unmarshal event: %w", err) + } + + // Token verification is handled by VerifyCallback; no need to re-check here. + + // Check event type + if eventBody.Header == nil || eventBody.Header.EventType != "im.message.receive_v1" { + if eventBody.Header != nil { + logger.Infof(c.Request.Context(), "[Feishu] Ignoring event type: %s", eventBody.Header.EventType) + } + return nil, nil + } + + // Extract message info + if eventBody.Event == nil || eventBody.Event.Message == nil { + return nil, nil + } + msg := eventBody.Event.Message + + if msg.MessageType != "text" { + logger.Infof(c.Request.Context(), "[Feishu] Ignoring non-text message type: %s", msg.MessageType) + return nil, nil + } + + // Parse text content + var textContent struct { + Text string `json:"text"` + } + if err := json.Unmarshal([]byte(msg.Content), &textContent); err != nil { + return nil, fmt.Errorf("unmarshal text content: %w", err) + } + + // Determine chat type + chatType := im.ChatTypeDirect + chatID := "" + if msg.ChatType == "group" { + chatType = im.ChatTypeGroup + chatID = msg.ChatID + } + + // Get sender info + openID := "" + if eventBody.Event.Sender != nil && eventBody.Event.Sender.SenderID != nil { + openID = eventBody.Event.Sender.SenderID.OpenID + } + + // Strip @bot mention from group messages + content := textContent.Text + if chatType == im.ChatTypeGroup { + // Feishu @mentions are in the format @_user_xxx + for strings.HasPrefix(content, "@_user_") { + idx := strings.Index(content, " ") + if idx >= 0 { + content = content[idx+1:] + } else { + break + } + } + } + + return &im.IncomingMessage{ + Platform: im.PlatformFeishu, + UserID: openID, + ChatID: chatID, + ChatType: chatType, + Content: strings.TrimSpace(content), + MessageID: msg.MessageID, + }, nil +} + +// SendReply sends a reply message via Feishu API. +func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { + accessToken, err := a.getTenantAccessToken(ctx) + if err != nil { + return fmt.Errorf("get access token: %w", err) + } + + // Determine receive_id_type and receive_id + receiveIDType := "open_id" + receiveID := incoming.UserID + if incoming.ChatType == im.ChatTypeGroup && incoming.ChatID != "" { + receiveIDType = "chat_id" + receiveID = incoming.ChatID + } + + // Build text message + content, _ := json.Marshal(map[string]string{"text": reply.Content}) + payload := map[string]interface{}{ + "receive_id": receiveID, + "msg_type": "text", + "content": string(content), + } + + payloadBytes, _ := json.Marshal(payload) + + url := fmt.Sprintf("https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=%s", receiveIDType) + req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payloadBytes)) + if err != nil { + return fmt.Errorf("create request: %w", err) + } + req.Header.Set("Content-Type", "application/json; charset=utf-8") + req.Header.Set("Authorization", "Bearer "+accessToken) + + resp, err := httpClient.Do(req) + if err != nil { + return fmt.Errorf("send message: %w", err) + } + defer resp.Body.Close() + + var result struct { + Code int `json:"code"` + Msg string `json:"msg"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return fmt.Errorf("decode response: %w", err) + } + if result.Code != 0 { + return fmt.Errorf("feishu api error: code=%d msg=%s", result.Code, result.Msg) + } + + return nil +} + +// getTenantAccessToken retrieves the Feishu tenant access token with caching. +// Feishu tokens expire in 2 hours; we cache with a safety margin. +func (a *Adapter) getTenantAccessToken(ctx context.Context) (string, error) { + a.tokenMu.Lock() + defer a.tokenMu.Unlock() + + if a.tokenCache != "" && time.Now().Before(a.tokenExpAt) { + return a.tokenCache, nil + } + + payload, _ := json.Marshal(map[string]string{ + "app_id": a.appID, + "app_secret": a.appSecret, + }) + + req, err := http.NewRequestWithContext(ctx, http.MethodPost, + "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", + bytes.NewReader(payload)) + if err != nil { + return "", fmt.Errorf("create request: %w", err) + } + req.Header.Set("Content-Type", "application/json; charset=utf-8") + + resp, err := httpClient.Do(req) + if err != nil { + return "", fmt.Errorf("request token: %w", err) + } + defer resp.Body.Close() + + var result struct { + Code int `json:"code"` + Msg string `json:"msg"` + TenantAccessToken string `json:"tenant_access_token"` + Expire int `json:"expire"` // seconds + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return "", fmt.Errorf("decode response: %w", err) + } + if result.Code != 0 { + return "", fmt.Errorf("get token error: code=%d msg=%s", result.Code, result.Msg) + } + + a.tokenCache = result.TenantAccessToken + // Cache with 5-minute safety margin + ttl := time.Duration(result.Expire) * time.Second + if ttl > 5*time.Minute { + ttl -= 5 * time.Minute + } + a.tokenExpAt = time.Now().Add(ttl) + + return a.tokenCache, nil +} + +// decrypt decrypts a Feishu encrypted event body. +// Feishu uses AES-256-CBC with SHA-256 of the encrypt key as the AES key. +func (a *Adapter) decrypt(encrypted string) ([]byte, error) { + if a.encryptKey == "" { + return nil, fmt.Errorf("encrypt_key not configured") + } + + ciphertext, err := base64.StdEncoding.DecodeString(encrypted) + if err != nil { + return nil, fmt.Errorf("base64 decode: %w", err) + } + + // SHA-256 of encrypt key as AES key + keyHash := sha256.Sum256([]byte(a.encryptKey)) + block, err := aes.NewCipher(keyHash[:]) + if err != nil { + return nil, fmt.Errorf("new cipher: %w", err) + } + + if len(ciphertext) < aes.BlockSize { + return nil, fmt.Errorf("ciphertext too short") + } + + iv := ciphertext[:aes.BlockSize] + ciphertext = ciphertext[aes.BlockSize:] + + mode := cipher.NewCBCDecrypter(block, iv) + mode.CryptBlocks(ciphertext, ciphertext) + + // Remove and verify PKCS#7 padding + if len(ciphertext) == 0 { + return nil, fmt.Errorf("empty plaintext") + } + padLen := int(ciphertext[len(ciphertext)-1]) + if padLen > aes.BlockSize || padLen == 0 || padLen > len(ciphertext) { + return nil, fmt.Errorf("invalid padding") + } + for i := 0; i < padLen; i++ { + if ciphertext[len(ciphertext)-1-i] != byte(padLen) { + return nil, fmt.Errorf("invalid padding") + } + } + + return ciphertext[:len(ciphertext)-padLen], nil +} diff --git a/internal/im/feishu/longconn.go b/internal/im/feishu/longconn.go new file mode 100644 index 00000000..aec48f57 --- /dev/null +++ b/internal/im/feishu/longconn.go @@ -0,0 +1,149 @@ +package feishu + +import ( + "context" + "encoding/json" + "fmt" + "strings" + + "github.com/Tencent/WeKnora/internal/im" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher" + larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1" + larkws "github.com/larksuite/oapi-sdk-go/v3/ws" +) + +// MessageHandler is called when an IM message is received via long connection. +type MessageHandler func(ctx context.Context, msg *im.IncomingMessage) error + +// LongConnClient manages a Feishu WebSocket long connection. +type LongConnClient struct { + appID string + wsClient *larkws.Client +} + +// NewLongConnClient creates a Feishu long connection client. +// When a text message arrives, it converts it to IncomingMessage and calls handler. +func NewLongConnClient(appID, appSecret string, handler MessageHandler) *LongConnClient { + // Long connection mode does not require verificationToken or encryptKey; + // those are only used for webhook signature verification and decryption. + eventHandler := dispatcher.NewEventDispatcher("", ""). + OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error { + msg := convertEvent(event) + if msg == nil { + return nil + } + return handler(ctx, msg) + }) + + sdkLogger := &feishuLoggerAdapter{appID: appID} + + wsClient := larkws.NewClient(appID, appSecret, + larkws.WithEventHandler(eventHandler), + larkws.WithAutoReconnect(true), + larkws.WithLogger(sdkLogger), + ) + + return &LongConnClient{appID: appID, wsClient: wsClient} +} + +// Start begins the WebSocket long connection. It blocks until ctx is cancelled. +func (c *LongConnClient) Start(ctx context.Context) error { + logger.Infof(ctx, "[IM] Feishu WebSocket connecting (app_id=%s)...", c.appID) + return c.wsClient.Start(ctx) +} + +// feishuLoggerAdapter bridges the Feishu SDK logger to our unified logger, +// replacing raw SDK connection messages with a consistent format. +type feishuLoggerAdapter struct { + appID string +} + +func (l *feishuLoggerAdapter) Debug(ctx context.Context, args ...interface{}) { + logger.Debugf(ctx, "[Feishu] %s", fmt.Sprint(args...)) +} + +func (l *feishuLoggerAdapter) Info(ctx context.Context, args ...interface{}) { + msg := fmt.Sprint(args...) + if strings.HasPrefix(msg, "connected to ") { + logger.Infof(ctx, "[IM] Feishu WebSocket connected successfully (app_id=%s)", l.appID) + return + } + logger.Infof(ctx, "[Feishu] %s", msg) +} + +func (l *feishuLoggerAdapter) Warn(ctx context.Context, args ...interface{}) { + logger.Warnf(ctx, "[Feishu] %s", fmt.Sprint(args...)) +} + +func (l *feishuLoggerAdapter) Error(ctx context.Context, args ...interface{}) { + logger.Errorf(ctx, "[Feishu] %s", fmt.Sprint(args...)) +} + +// convertEvent converts a Feishu SDK event to a unified IncomingMessage. +// Returns nil for non-text messages. +func convertEvent(event *larkim.P2MessageReceiveV1) *im.IncomingMessage { + if event == nil || event.Event == nil || event.Event.Message == nil { + return nil + } + + msg := event.Event.Message + if msg.MessageType == nil || *msg.MessageType != "text" { + return nil + } + + // Parse text content from JSON: {"text": "..."} + var textContent struct { + Text string `json:"text"` + } + if msg.Content == nil { + return nil + } + if err := json.Unmarshal([]byte(*msg.Content), &textContent); err != nil { + return nil + } + + // Sender info + openID := "" + if event.Event.Sender != nil && event.Event.Sender.SenderId != nil && event.Event.Sender.SenderId.OpenId != nil { + openID = *event.Event.Sender.SenderId.OpenId + } + + // Chat type + chatType := im.ChatTypeDirect + chatID := "" + if msg.ChatType != nil && *msg.ChatType == "group" { + chatType = im.ChatTypeGroup + if msg.ChatId != nil { + chatID = *msg.ChatId + } + } + + // Message ID + messageID := "" + if msg.MessageId != nil { + messageID = *msg.MessageId + } + + // Strip @bot mention from group messages + content := textContent.Text + if chatType == im.ChatTypeGroup { + for strings.HasPrefix(content, "@_user_") { + idx := strings.Index(content, " ") + if idx >= 0 { + content = content[idx+1:] + } else { + break + } + } + } + + return &im.IncomingMessage{ + Platform: im.PlatformFeishu, + UserID: openID, + ChatID: chatID, + ChatType: chatType, + Content: strings.TrimSpace(content), + MessageID: messageID, + } +} diff --git a/internal/im/service.go b/internal/im/service.go new file mode 100644 index 00000000..6fff47d0 --- /dev/null +++ b/internal/im/service.go @@ -0,0 +1,378 @@ +package im + +import ( + "context" + "fmt" + "strings" + "sync" + "time" + + "github.com/Tencent/WeKnora/internal/event" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/google/uuid" + "gorm.io/gorm" +) + +const ( + // qaTimeout is the maximum time to wait for the QA pipeline to complete. + qaTimeout = 120 * time.Second + // dedupTTL is how long processed message IDs are retained. + dedupTTL = 5 * time.Minute + // dedupCleanupInterval is how often the dedup map is cleaned. + dedupCleanupInterval = 1 * time.Minute + // maxContentLength is the maximum allowed message content length. + maxContentLength = 4096 +) + +// Service orchestrates IM message handling: +// 1. Receives a unified IncomingMessage from an Adapter +// 2. Resolves or creates a WeKnora session for the IM channel +// 3. Calls the WeKnora QA pipeline +// 4. Collects the streaming answer and sends it back via the Adapter +type Service struct { + db *gorm.DB + sessionService interfaces.SessionService + messageService interfaces.MessageService + tenantService interfaces.TenantService + agentService interfaces.CustomAgentService + + adapters map[Platform]Adapter + mu sync.RWMutex + + // processedMsgs tracks recently processed message IDs to prevent duplicate handling. + processedMsgs sync.Map + + stopCh chan struct{} +} + +// NewService creates a new IM service. +func NewService( + db *gorm.DB, + sessionService interfaces.SessionService, + messageService interfaces.MessageService, + tenantService interfaces.TenantService, + agentService interfaces.CustomAgentService, +) *Service { + s := &Service{ + db: db, + sessionService: sessionService, + messageService: messageService, + tenantService: tenantService, + agentService: agentService, + adapters: make(map[Platform]Adapter), + stopCh: make(chan struct{}), + } + + // Start periodic dedup cleanup instead of per-message goroutines + go s.dedupCleanupLoop() + + return s +} + +// Stop gracefully shuts down the service, stopping background goroutines. +func (s *Service) Stop() { + close(s.stopCh) +} + +// dedupCleanupLoop periodically cleans up expired entries from the dedup map. +func (s *Service) dedupCleanupLoop() { + ticker := time.NewTicker(dedupCleanupInterval) + defer ticker.Stop() + for { + select { + case <-ticker.C: + cutoff := time.Now().Add(-dedupTTL) + s.processedMsgs.Range(func(key, value interface{}) bool { + if t, ok := value.(time.Time); ok && t.Before(cutoff) { + s.processedMsgs.Delete(key) + } + return true + }) + case <-s.stopCh: + return + } + } +} + +// RegisterAdapter registers an IM platform adapter. +func (s *Service) RegisterAdapter(adapter Adapter) { + s.mu.Lock() + defer s.mu.Unlock() + s.adapters[adapter.Platform()] = adapter +} + +// GetAdapter returns the adapter for a given platform. +func (s *Service) GetAdapter(platform Platform) (Adapter, bool) { + s.mu.RLock() + defer s.mu.RUnlock() + a, ok := s.adapters[platform] + return a, ok +} + +// HandleMessage processes an incoming IM message end-to-end: +// resolves session, runs QA, sends reply. +func (s *Service) HandleMessage(ctx context.Context, msg *IncomingMessage, tenantID uint64, agentID string, kbIDs []string) error { + // Dedup: skip if this message was already processed (IM platforms may retry) + if msg.MessageID != "" { + if _, loaded := s.processedMsgs.LoadOrStore(msg.MessageID, time.Now()); loaded { + logger.Infof(ctx, "[IM] Skipping duplicate message: %s", msg.MessageID) + return nil + } + } + + // Reject overly long messages to protect the QA pipeline + contentRunes := []rune(msg.Content) + if len(contentRunes) > maxContentLength { + logger.Warnf(ctx, "[IM] Message too long (%d runes), truncating to %d", len(contentRunes), maxContentLength) + msg.Content = string(contentRunes[:maxContentLength]) + } + + logger.Infof(ctx, "[IM] HandleMessage: platform=%s user=%s chat=%s content_len=%d", + msg.Platform, msg.UserID, msg.ChatID, len(msg.Content)) + + // 1. Get tenant (once, shared across resolve + QA) + tenant, err := s.tenantService.GetTenantByID(ctx, tenantID) + if err != nil { + return fmt.Errorf("get tenant: %w", err) + } + sessionCtx := context.WithValue(ctx, types.TenantIDContextKey, tenantID) + sessionCtx = context.WithValue(sessionCtx, types.TenantInfoContextKey, tenant) + + // 2. Resolve or create a WeKnora session + channelSession, err := s.resolveSession(sessionCtx, msg, tenantID, agentID) + if err != nil { + return fmt.Errorf("resolve session: %w", err) + } + + // 3. Get the WeKnora session + session, err := s.sessionService.GetSession(sessionCtx, channelSession.SessionID) + if err != nil { + return fmt.Errorf("get session: %w", err) + } + + // 4. Resolve custom agent (optional) + var customAgent *types.CustomAgent + if agentID != "" { + agent, err := s.agentService.GetAgentByID(sessionCtx, agentID) + if err != nil { + logger.Warnf(ctx, "[IM] Failed to get agent %s: %v, using default", agentID, err) + } else { + customAgent = agent + } + } + + // 5. Run the QA pipeline and collect the full answer + answer, err := s.runQA(sessionCtx, session, msg.Content, customAgent, kbIDs) + if err != nil { + logger.Errorf(ctx, "[IM] QA failed: %v, sending fallback reply", err) + answer = "抱歉,处理您的问题时出现了异常,请稍后再试。" + } + + // 6. Send the reply back via the platform adapter + adapter, ok := s.GetAdapter(msg.Platform) + if !ok { + return fmt.Errorf("no adapter for platform: %s", msg.Platform) + } + + reply := &ReplyMessage{ + Content: answer, + IsFinal: true, + } + if err := adapter.SendReply(ctx, msg, reply); err != nil { + return fmt.Errorf("send reply: %w", err) + } + + logger.Infof(ctx, "[IM] Reply sent: platform=%s user=%s answer_len=%d", msg.Platform, msg.UserID, len(answer)) + return nil +} + +// resolveSession finds or creates a ChannelSession for the given IM message. +// ctx must already carry TenantIDContextKey and TenantInfoContextKey. +func (s *Service) resolveSession(ctx context.Context, msg *IncomingMessage, tenantID uint64, agentID string) (*ChannelSession, error) { + var cs ChannelSession + result := s.db.Where("platform = ? AND user_id = ? AND chat_id = ? AND tenant_id = ? AND deleted_at IS NULL", + string(msg.Platform), msg.UserID, msg.ChatID, tenantID). + First(&cs) + + if result.Error == nil { + return &cs, nil + } + + if result.Error != gorm.ErrRecordNotFound { + return nil, fmt.Errorf("query channel session: %w", result.Error) + } + + // Create a new WeKnora session + title := fmt.Sprintf("IM-%s", msg.Platform) + if msg.UserName != "" { + title = fmt.Sprintf("IM-%s-%s", msg.Platform, msg.UserName) + } + + newSession := &types.Session{ + TenantID: tenantID, + Title: title, + Description: fmt.Sprintf("Auto-created from %s IM integration", msg.Platform), + } + + createdSession, err := s.sessionService.CreateSession(ctx, newSession) + if err != nil { + return nil, fmt.Errorf("create session: %w", err) + } + + // Create the channel-session mapping; use a unique constraint fallback + // to handle concurrent creation attempts for the same channel. + cs = ChannelSession{ + Platform: string(msg.Platform), + UserID: msg.UserID, + ChatID: msg.ChatID, + SessionID: createdSession.ID, + TenantID: tenantID, + AgentID: agentID, + } + if err := s.db.Create(&cs).Error; err != nil { + // If the insert failed due to unique constraint (concurrent request), + // fetch the existing record. + var existing ChannelSession + if findErr := s.db.Where("platform = ? AND user_id = ? AND chat_id = ? AND tenant_id = ? AND deleted_at IS NULL", + string(msg.Platform), msg.UserID, msg.ChatID, tenantID). + First(&existing).Error; findErr != nil { + return nil, fmt.Errorf("create channel session: %w (lookup fallback: %v)", err, findErr) + } + return &existing, nil + } + + logger.Infof(ctx, "[IM] Created new session mapping: channel=%s/%s/%s -> session=%s", + msg.Platform, msg.UserID, msg.ChatID, createdSession.ID) + + return &cs, nil +} + +// runQA executes the WeKnora QA pipeline and returns the full answer text. +func (s *Service) runQA(ctx context.Context, session *types.Session, query string, customAgent *types.CustomAgent, kbIDs []string) (string, error) { + // Add timeout to prevent indefinite blocking + ctx, cancel := context.WithTimeout(ctx, qaTimeout) + defer cancel() + + eventBus := event.NewEventBus() + + // Thread-safe answer collection + var answerMu sync.Mutex + var answerBuilder strings.Builder + var qaErr error + done := make(chan struct{}) + var closeOnce sync.Once + closeDone := func() { closeOnce.Do(func() { close(done) }) } + + eventBus.On(event.EventAgentFinalAnswer, func(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentFinalAnswerData) + if !ok { + return nil + } + answerMu.Lock() + answerBuilder.WriteString(data.Content) + answerMu.Unlock() + if data.Done { + closeDone() + } + return nil + }) + + eventBus.On(event.EventError, func(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.ErrorData) + if !ok { + return nil + } + logger.Errorf(ctx, "[IM] QA error: %s", data.Error) + answerMu.Lock() + qaErr = fmt.Errorf("QA pipeline error: %s", data.Error) + answerMu.Unlock() + closeDone() + return nil + }) + + // Determine whether to use agent mode + useAgent := customAgent != nil && customAgent.IsAgentMode() + + // Generate a shared RequestID to pair user and assistant messages for history + requestID := uuid.New().String() + + // Create user message so it appears in conversation history + userMsg, err := s.messageService.CreateMessage(ctx, &types.Message{ + SessionID: session.ID, + Role: "user", + Content: query, + RequestID: requestID, + CreatedAt: time.Now(), + IsCompleted: true, + }) + if err != nil { + return "", fmt.Errorf("create user message: %w", err) + } + _ = userMsg + + // Create a placeholder assistant message + assistantMsg, err := s.messageService.CreateMessage(ctx, &types.Message{ + SessionID: session.ID, + Role: "assistant", + RequestID: requestID, + CreatedAt: time.Now(), + IsCompleted: false, + }) + if err != nil { + return "", fmt.Errorf("create assistant message: %w", err) + } + + // Run QA async + go func() { + var err error + if useAgent { + err = s.sessionService.AgentQA(ctx, session, query, assistantMsg.ID, "", eventBus, customAgent, kbIDs, nil) + } else { + err = s.sessionService.KnowledgeQA(ctx, session, query, kbIDs, nil, assistantMsg.ID, "", false, eventBus, customAgent, false) + } + if err != nil { + logger.Errorf(ctx, "[IM] QA execution error: %v", err) + answerMu.Lock() + qaErr = fmt.Errorf("QA execution error: %w", err) + answerMu.Unlock() + closeDone() + } + }() + + // Wait for completion or timeout + select { + case <-done: + case <-ctx.Done(): + // Mark assistant message as completed to avoid dangling incomplete records + assistantMsg.Content = "抱歉,回答超时,请稍后再试。" + assistantMsg.IsCompleted = true + // Use a fresh context since the original is cancelled + if updateErr := s.messageService.UpdateMessage(context.WithoutCancel(ctx), assistantMsg); updateErr != nil { + logger.Warnf(ctx, "[IM] Failed to update timed-out assistant message: %v", updateErr) + } + return "", fmt.Errorf("QA timed out after %v", qaTimeout) + } + + answerMu.Lock() + answer := answerBuilder.String() + qaError := qaErr + answerMu.Unlock() + + if answer == "" && qaError != nil { + return "", qaError + } + if answer == "" { + answer = "抱歉,我暂时无法回答这个问题。" + } + + // Update assistant message with the final answer content + assistantMsg.Content = answer + assistantMsg.IsCompleted = true + if err := s.messageService.UpdateMessage(ctx, assistantMsg); err != nil { + logger.Warnf(ctx, "[IM] Failed to update assistant message: %v", err) + } + + return answer, nil +} diff --git a/internal/im/types.go b/internal/im/types.go new file mode 100644 index 00000000..96e7ae43 --- /dev/null +++ b/internal/im/types.go @@ -0,0 +1,40 @@ +package im + +import ( + "time" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/google/uuid" + "gorm.io/gorm" +) + +// ChannelSession maps an IM channel (user+chat combination) to a WeKnora session. +// This allows the IM integration to maintain conversation continuity. +type ChannelSession struct { + ID string `json:"id" gorm:"type:varchar(36);primaryKey;default:uuid_generate_v4()"` + Platform string `json:"platform" gorm:"type:varchar(20);not null"` + UserID string `json:"user_id" gorm:"type:varchar(128);not null"` + ChatID string `json:"chat_id" gorm:"type:varchar(128);not null;default:''"` + SessionID string `json:"session_id" gorm:"type:varchar(36);not null;index"` + TenantID uint64 `json:"tenant_id" gorm:"not null;index"` + AgentID string `json:"agent_id" gorm:"type:varchar(36);default:''"` + Status string `json:"status" gorm:"type:varchar(20);not null;default:'active'"` + Metadata types.JSON `json:"metadata" gorm:"type:jsonb;default:'{}'"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + DeletedAt gorm.DeletedAt `json:"deleted_at" gorm:"index"` +} + +func (ChannelSession) TableName() string { + return "im_channel_sessions" +} + +func (cs *ChannelSession) BeforeCreate(tx *gorm.DB) error { + if cs.ID == "" { + cs.ID = uuid.New().String() + } + if cs.Status == "" { + cs.Status = "active" + } + return nil +} diff --git a/internal/im/wecom/adapter.go b/internal/im/wecom/adapter.go new file mode 100644 index 00000000..98062dc4 --- /dev/null +++ b/internal/im/wecom/adapter.go @@ -0,0 +1,369 @@ +// Package wecom implements the WeCom (企业微信) IM adapter for WeKnora. +// +// WeCom Smart Bot flow: +// 1. User sends a message to the bot (direct or @mention in group) +// 2. WeCom calls our callback URL with the encrypted message +// 3. We decrypt, parse, and return an immediate response (or stream response) +// 4. For streaming: respond with msgtype="stream", WeCom pulls subsequent chunks via refresh callbacks +// +// Reference: https://developer.work.weixin.qq.com/document/path/101031 +package wecom + +import ( + "bytes" + "context" + "crypto/aes" + "crypto/cipher" + "crypto/hmac" + "crypto/sha1" + "encoding/base64" + "encoding/binary" + "encoding/json" + "encoding/xml" + "fmt" + "io" + "net/http" + "sort" + "strings" + "sync" + "time" + + "github.com/Tencent/WeKnora/internal/im" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/gin-gonic/gin" +) + +var httpClient = &http.Client{Timeout: 10 * time.Second} + +// Adapter implements im.Adapter for WeCom. +type Adapter struct { + corpID string + token string + encodingAESKey string + aesKey []byte + agentSecret string + corpAgentID int + + // Token cache + tokenMu sync.Mutex + tokenCache string + tokenExpAt time.Time +} + +// NewAdapter creates a new WeCom adapter. +func NewAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID int) (*Adapter, error) { + // Decode the AES key from base64 + aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=") + if err != nil { + return nil, fmt.Errorf("decode encoding_aes_key: %w", err) + } + + return &Adapter{ + corpID: corpID, + token: token, + encodingAESKey: encodingAESKey, + aesKey: aesKey, + agentSecret: agentSecret, + corpAgentID: corpAgentID, + }, nil +} + +// Platform returns the platform identifier. +func (a *Adapter) Platform() im.Platform { + return im.PlatformWeCom +} + +// VerifyCallback verifies the WeCom callback signature. +func (a *Adapter) VerifyCallback(c *gin.Context) error { + timestamp := c.Query("timestamp") + nonce := c.Query("nonce") + msgSignature := c.Query("msg_signature") + + // For GET requests (URL verification), use echostr + // For POST requests (message callback), use request body's Encrypt field + var encrypt string + if c.Request.Method == http.MethodGet { + encrypt = c.Query("echostr") + } else { + var body callbackRequestBody + bodyBytes, err := io.ReadAll(c.Request.Body) + if err != nil { + return fmt.Errorf("read request body: %w", err) + } + c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes)) + if err := xml.Unmarshal(bodyBytes, &body); err != nil { + return fmt.Errorf("unmarshal xml body: %w", err) + } + encrypt = body.Encrypt + } + + if !a.verifySignature(msgSignature, timestamp, nonce, encrypt) { + return fmt.Errorf("invalid signature") + } + + return nil +} + +// HandleURLVerification handles the WeCom URL verification (GET request). +func (a *Adapter) HandleURLVerification(c *gin.Context) bool { + if c.Request.Method != http.MethodGet { + return false + } + + echoStr := c.Query("echostr") + if echoStr == "" { + return false + } + + // Decrypt the echostr and return it + decrypted, err := a.decrypt(echoStr) + if err != nil { + logger.Errorf(c.Request.Context(), "[WeCom] Failed to decrypt echostr: %v", err) + c.String(http.StatusBadRequest, "decrypt failed") + return true + } + + c.String(http.StatusOK, string(decrypted)) + return true +} + +// ParseCallback parses a WeCom callback into a unified IncomingMessage. +func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { + bodyBytes, err := io.ReadAll(c.Request.Body) + if err != nil { + return nil, fmt.Errorf("read body: %w", err) + } + + var body callbackRequestBody + if err := xml.Unmarshal(bodyBytes, &body); err != nil { + return nil, fmt.Errorf("unmarshal xml: %w", err) + } + + // Decrypt the message + decrypted, err := a.decrypt(body.Encrypt) + if err != nil { + return nil, fmt.Errorf("decrypt message: %w", err) + } + + var msg wecomMessage + if err := xml.Unmarshal(decrypted, &msg); err != nil { + return nil, fmt.Errorf("unmarshal decrypted message: %w", err) + } + + // Only handle text messages + if msg.MsgType != "text" { + logger.Infof(c.Request.Context(), "[WeCom] Ignoring non-text message type: %s", msg.MsgType) + return nil, nil + } + + chatType := im.ChatTypeDirect + chatID := "" + content := msg.Content + + // Check if this is a group message (has ChatId field in WeCom smart bot callback) + // In group chats, the content may contain @bot mention prefix that should be stripped + if msg.ChatID != "" { + chatType = im.ChatTypeGroup + chatID = msg.ChatID + } + + return &im.IncomingMessage{ + Platform: im.PlatformWeCom, + UserID: msg.FromUserName, + UserName: msg.FromUserName, + ChatID: chatID, + ChatType: chatType, + Content: strings.TrimSpace(content), + MessageID: msg.MsgID, + }, nil +} + +// SendReply sends a reply message via WeCom API. +// For simplicity, this uses the "应用消息" API to proactively send messages. +// A production implementation would integrate with the streaming callback model. +func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { + // Get access token + accessToken, err := a.getAccessToken(ctx) + if err != nil { + return fmt.Errorf("get access token: %w", err) + } + + // Build message payload. + // Note: /cgi-bin/message/send only supports touser/toparty/totag — it does NOT + // support regular group chat IDs (chatid is only for appchat-created groups). + // So for both direct and group messages we reply to the user directly. + payload := map[string]interface{}{ + "touser": incoming.UserID, + "msgtype": "markdown", + "agentid": a.corpAgentID, + "markdown": map[string]string{ + "content": reply.Content, + }, + } + + payloadBytes, err := json.Marshal(payload) + if err != nil { + return fmt.Errorf("marshal payload: %w", err) + } + + sendURL := fmt.Sprintf("https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=%s", accessToken) + req, err := http.NewRequestWithContext(ctx, http.MethodPost, sendURL, bytes.NewReader(payloadBytes)) + if err != nil { + return fmt.Errorf("create request: %w", err) + } + req.Header.Set("Content-Type", "application/json") + + resp, err := httpClient.Do(req) + if err != nil { + return fmt.Errorf("send message: %w", err) + } + defer resp.Body.Close() + + var result struct { + ErrCode int `json:"errcode"` + ErrMsg string `json:"errmsg"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return fmt.Errorf("decode response: %w", err) + } + if result.ErrCode != 0 { + return fmt.Errorf("wecom api error: code=%d msg=%s", result.ErrCode, result.ErrMsg) + } + + return nil +} + +// getAccessToken retrieves the WeCom access token with caching. +// WeCom tokens expire in 7200 seconds (2 hours); we cache with a safety margin. +func (a *Adapter) getAccessToken(ctx context.Context) (string, error) { + a.tokenMu.Lock() + defer a.tokenMu.Unlock() + + if a.tokenCache != "" && time.Now().Before(a.tokenExpAt) { + return a.tokenCache, nil + } + + tokenURL := fmt.Sprintf("https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=%s&corpsecret=%s", + a.corpID, a.agentSecret) + + req, err := http.NewRequestWithContext(ctx, http.MethodGet, tokenURL, nil) + if err != nil { + return "", fmt.Errorf("create request: %w", err) + } + + resp, err := httpClient.Do(req) + if err != nil { + return "", fmt.Errorf("request access token: %w", err) + } + defer resp.Body.Close() + + var result struct { + ErrCode int `json:"errcode"` + ErrMsg string `json:"errmsg"` + AccessToken string `json:"access_token"` + ExpiresIn int `json:"expires_in"` // seconds + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return "", fmt.Errorf("decode token response: %w", err) + } + if result.ErrCode != 0 { + return "", fmt.Errorf("get token error: code=%d msg=%s", result.ErrCode, result.ErrMsg) + } + + a.tokenCache = result.AccessToken + // Cache with 5-minute safety margin + ttl := time.Duration(result.ExpiresIn) * time.Second + if ttl > 5*time.Minute { + ttl -= 5 * time.Minute + } + a.tokenExpAt = time.Now().Add(ttl) + + return a.tokenCache, nil +} + +// verifySignature verifies the WeCom callback signature using constant-time comparison. +func (a *Adapter) verifySignature(signature, timestamp, nonce, encrypt string) bool { + parts := []string{a.token, timestamp, nonce, encrypt} + sort.Strings(parts) + combined := strings.Join(parts, "") + + hash := sha1.New() + hash.Write([]byte(combined)) + computed := fmt.Sprintf("%x", hash.Sum(nil)) + + return hmac.Equal([]byte(computed), []byte(signature)) +} + +// decrypt decrypts a WeCom AES-encrypted message. +func (a *Adapter) decrypt(encrypted string) ([]byte, error) { + ciphertext, err := base64.StdEncoding.DecodeString(encrypted) + if err != nil { + return nil, fmt.Errorf("base64 decode: %w", err) + } + + block, err := aes.NewCipher(a.aesKey) + if err != nil { + return nil, fmt.Errorf("new cipher: %w", err) + } + + if len(ciphertext) < aes.BlockSize { + return nil, fmt.Errorf("ciphertext too short") + } + + iv := a.aesKey[:aes.BlockSize] + mode := cipher.NewCBCDecrypter(block, iv) + mode.CryptBlocks(ciphertext, ciphertext) + + // Remove and verify PKCS#7 padding + padLen := int(ciphertext[len(ciphertext)-1]) + if padLen > aes.BlockSize || padLen == 0 || padLen > len(ciphertext) { + return nil, fmt.Errorf("invalid padding") + } + for i := 0; i < padLen; i++ { + if ciphertext[len(ciphertext)-1-i] != byte(padLen) { + return nil, fmt.Errorf("invalid padding") + } + } + plaintext := ciphertext[:len(ciphertext)-padLen] + + // WeCom format: random(16) + msg_len(4) + msg + corp_id + if len(plaintext) < 20 { + return nil, fmt.Errorf("plaintext too short") + } + + msgLen := binary.BigEndian.Uint32(plaintext[16:20]) + if uint32(len(plaintext)) < 20+msgLen { + return nil, fmt.Errorf("message length mismatch") + } + + msgBytes := plaintext[20 : 20+msgLen] + + // Verify corp_id from plaintext tail + corpIDBytes := plaintext[20+msgLen:] + if string(corpIDBytes) != a.corpID { + return nil, fmt.Errorf("corp_id mismatch: expected %s, got %s", a.corpID, string(corpIDBytes)) + } + + return msgBytes, nil +} + +// callbackRequestBody is the XML structure of a WeCom callback request body. +type callbackRequestBody struct { + XMLName xml.Name `xml:"xml"` + ToUserName string `xml:"ToUserName"` + Encrypt string `xml:"Encrypt"` + AgentID string `xml:"AgentID"` +} + +// wecomMessage is the decrypted WeCom message structure. +type wecomMessage struct { + XMLName xml.Name `xml:"xml"` + ToUserName string `xml:"ToUserName"` + FromUserName string `xml:"FromUserName"` + CreateTime int64 `xml:"CreateTime"` + MsgType string `xml:"MsgType"` + Content string `xml:"Content"` + MsgID string `xml:"MsgId"` + AgentID string `xml:"AgentID"` + ChatID string `xml:"ChatId"` +} diff --git a/internal/im/wecom/bot_adapter.go b/internal/im/wecom/bot_adapter.go new file mode 100644 index 00000000..eccd6911 --- /dev/null +++ b/internal/im/wecom/bot_adapter.go @@ -0,0 +1,42 @@ +package wecom + +import ( + "context" + "fmt" + + "github.com/Tencent/WeKnora/internal/im" + "github.com/gin-gonic/gin" +) + +// BotAdapter implements im.Adapter for WeCom intelligent bot (long connection mode). +// It delegates SendReply to the WebSocket LongConnClient. +// The webhook methods (VerifyCallback, ParseCallback, HandleURLVerification) are no-ops +// since messages arrive via WebSocket, not HTTP. +type BotAdapter struct { + client *LongConnClient +} + +// NewBotAdapter creates an adapter backed by a WeCom long connection client. +func NewBotAdapter(client *LongConnClient) *BotAdapter { + return &BotAdapter{client: client} +} + +func (a *BotAdapter) Platform() im.Platform { + return im.PlatformWeCom +} + +func (a *BotAdapter) VerifyCallback(c *gin.Context) error { + return fmt.Errorf("WeCom bot adapter does not support webhook callbacks") +} + +func (a *BotAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { + return nil, fmt.Errorf("WeCom bot adapter does not support webhook callbacks") +} + +func (a *BotAdapter) HandleURLVerification(c *gin.Context) bool { + return false +} + +func (a *BotAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { + return a.client.SendReply(ctx, incoming, reply) +} diff --git a/internal/im/wecom/longconn.go b/internal/im/wecom/longconn.go new file mode 100644 index 00000000..df04ee9c --- /dev/null +++ b/internal/im/wecom/longconn.go @@ -0,0 +1,353 @@ +// WeCom Intelligent Bot long connection client. +// +// Protocol reference: https://developer.work.weixin.qq.com/document/path/101463 +// Node.js SDK reference: https://github.com/WecomTeam/aibot-node-sdk +// +// Flow: +// 1. Connect to wss://openws.work.weixin.qq.com +// 2. Send aibot_subscribe with bot_id + secret +// 3. Receive aibot_msg_callback / aibot_event_callback frames +// 4. Reply via aibot_respond_msg on the same WebSocket +// 5. Heartbeat via ping/pong every 30s +package wecom + +import ( + "context" + "encoding/json" + "fmt" + "math" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/Tencent/WeKnora/internal/im" + "github.com/Tencent/WeKnora/internal/logger" + ws "github.com/gorilla/websocket" +) + +const ( + wecomWSEndpoint = "wss://openws.work.weixin.qq.com" + + cmdSubscribe = "aibot_subscribe" + cmdPing = "ping" + cmdMsgCallback = "aibot_msg_callback" + cmdEventCallback = "aibot_event_callback" + cmdResponse = "aibot_respond_msg" + + defaultHeartbeatInterval = 30 * time.Second + defaultReconnectBaseDelay = 1 * time.Second + defaultReconnectMaxDelay = 30 * time.Second + defaultMaxReconnectAttempts = -1 // infinite +) + +// wsFrame is the JSON frame exchanged over the WeCom bot WebSocket. +type wsFrame struct { + Cmd string `json:"cmd,omitempty"` + Headers map[string]string `json:"headers,omitempty"` + Body json.RawMessage `json:"body,omitempty"` + ErrCode int `json:"errcode,omitempty"` + ErrMsg string `json:"errmsg,omitempty"` +} + +// botMessage is the body of an aibot_msg_callback frame. +type botMessage struct { + MsgID string `json:"msgid"` + AiBotID string `json:"aibotid"` + ChatID string `json:"chatid"` + ChatType string `json:"chattype"` // "single" or "group" + MsgType string `json:"msgtype"` // "text", "image", "event", ... + CreateTime int64 `json:"create_time"` + From struct { + UserID string `json:"userid"` + } `json:"from"` + Text struct { + Content string `json:"content"` + } `json:"text"` +} + +// streamReplyBody is the body for a streaming text reply. +type streamReplyBody struct { + MsgType string `json:"msgtype"` + Stream struct { + ID string `json:"id"` + Finish bool `json:"finish"` + Content string `json:"content"` + } `json:"stream"` +} + +// MessageHandler is called when an IM message is received via long connection. +type MessageHandler func(ctx context.Context, msg *im.IncomingMessage) error + +// LongConnClient manages a WeCom intelligent bot WebSocket long connection. +type LongConnClient struct { + botID string + secret string + handler MessageHandler + + conn *ws.Conn + mu sync.Mutex + closed atomic.Bool + reqSeq atomic.Int64 +} + +// NewLongConnClient creates a WeCom long connection client. +func NewLongConnClient(botID, secret string, handler MessageHandler) *LongConnClient { + return &LongConnClient{ + botID: botID, + secret: secret, + handler: handler, + } +} + +// Start connects and runs the long connection loop. It reconnects automatically on failure. +func (c *LongConnClient) Start(ctx context.Context) error { + logger.Infof(ctx, "[IM] WeCom WebSocket connecting (bot_id=%s)...", c.botID) + + attempts := 0 + for { + if ctx.Err() != nil { + return ctx.Err() + } + + err := c.connectAndRun(ctx) + if c.closed.Load() { + return nil + } + if ctx.Err() != nil { + return ctx.Err() + } + + attempts++ + if defaultMaxReconnectAttempts >= 0 && attempts >= defaultMaxReconnectAttempts { + return fmt.Errorf("max reconnect attempts reached: %w", err) + } + + delay := reconnectDelay(attempts) + logger.Warnf(ctx, "[WeCom] Connection lost (%v), reconnecting in %v (attempt %d)...", err, delay, attempts) + + select { + case <-time.After(delay): + case <-ctx.Done(): + return ctx.Err() + } + } +} + +// Stop gracefully closes the connection. +func (c *LongConnClient) Stop() { + c.closed.Store(true) + c.mu.Lock() + defer c.mu.Unlock() + if c.conn != nil { + _ = c.conn.Close() + c.conn = nil + } +} + +// SendReply sends a text reply through the WebSocket connection. +// This is used by the IM service to reply to messages in long connection mode. +func (c *LongConnClient) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { + reqID, ok := incoming.Extra["req_id"] + if !ok || reqID == "" { + return fmt.Errorf("missing req_id in incoming message extra") + } + + // Generate a unique stream ID for this reply + streamID := fmt.Sprintf("stream_%d", c.reqSeq.Add(1)) + + body := streamReplyBody{MsgType: "stream"} + body.Stream.ID = streamID + body.Stream.Finish = true + body.Stream.Content = reply.Content + + bodyBytes, err := json.Marshal(body) + if err != nil { + return fmt.Errorf("marshal reply body: %w", err) + } + + frame := wsFrame{ + Cmd: cmdResponse, + Headers: map[string]string{"req_id": reqID}, + Body: bodyBytes, + } + + return c.writeJSON(frame) +} + +func (c *LongConnClient) connectAndRun(ctx context.Context) error { + conn, _, err := ws.DefaultDialer.DialContext(ctx, wecomWSEndpoint, nil) + if err != nil { + return fmt.Errorf("dial: %w", err) + } + + c.mu.Lock() + c.conn = conn + c.mu.Unlock() + + defer func() { + c.mu.Lock() + c.conn = nil + c.mu.Unlock() + _ = conn.Close() + }() + + // Authenticate + if err := c.authenticate(ctx); err != nil { + return fmt.Errorf("authenticate: %w", err) + } + + logger.Infof(ctx, "[IM] WeCom WebSocket connected successfully (bot_id=%s)", c.botID) + + // Start heartbeat + heartbeatCtx, heartbeatCancel := context.WithCancel(ctx) + defer heartbeatCancel() + go c.heartbeatLoop(heartbeatCtx) + + // Message receive loop + for { + _, message, err := conn.ReadMessage() + if err != nil { + return fmt.Errorf("read message: %w", err) + } + + var frame wsFrame + if err := json.Unmarshal(message, &frame); err != nil { + logger.Warnf(ctx, "[WeCom] Failed to unmarshal frame: %v", err) + continue + } + + switch frame.Cmd { + case cmdMsgCallback, cmdEventCallback: + // Detach from connection ctx so in-flight messages survive reconnects. + go c.handleCallback(context.WithoutCancel(ctx), frame) + default: + // pong or other control frames — ignore + } + } +} + +func (c *LongConnClient) authenticate(ctx context.Context) error { + authBody, _ := json.Marshal(map[string]string{ + "bot_id": c.botID, + "secret": c.secret, + }) + + reqID := fmt.Sprintf("%s_%d", cmdSubscribe, time.Now().UnixNano()) + frame := wsFrame{ + Cmd: cmdSubscribe, + Headers: map[string]string{"req_id": reqID}, + Body: authBody, + } + + if err := c.writeJSON(frame); err != nil { + return fmt.Errorf("send subscribe: %w", err) + } + + // Read auth response + c.mu.Lock() + conn := c.conn + c.mu.Unlock() + if conn == nil { + return fmt.Errorf("connection closed") + } + + _ = conn.SetReadDeadline(time.Now().Add(10 * time.Second)) + _, msg, err := conn.ReadMessage() + _ = conn.SetReadDeadline(time.Time{}) // clear deadline + if err != nil { + return fmt.Errorf("read auth response: %w", err) + } + + var resp wsFrame + if err := json.Unmarshal(msg, &resp); err != nil { + return fmt.Errorf("unmarshal auth response: %w", err) + } + + if resp.ErrCode != 0 { + return fmt.Errorf("auth failed: code=%d msg=%s", resp.ErrCode, resp.ErrMsg) + } + + return nil +} + +func (c *LongConnClient) heartbeatLoop(ctx context.Context) { + ticker := time.NewTicker(defaultHeartbeatInterval) + defer ticker.Stop() + + for { + select { + case <-ctx.Done(): + return + case <-ticker.C: + reqID := fmt.Sprintf("%s_%d", cmdPing, time.Now().UnixNano()) + frame := wsFrame{ + Cmd: cmdPing, + Headers: map[string]string{"req_id": reqID}, + } + if err := c.writeJSON(frame); err != nil { + logger.Warnf(ctx, "[WeCom] Heartbeat failed: %v", err) + return + } + } + } +} + +func (c *LongConnClient) handleCallback(ctx context.Context, frame wsFrame) { + var msg botMessage + if err := json.Unmarshal(frame.Body, &msg); err != nil { + logger.Warnf(ctx, "[WeCom] Failed to unmarshal callback body: %v", err) + return + } + + // Only handle text messages for now + if msg.MsgType != "text" { + logger.Infof(ctx, "[WeCom] Ignoring non-text message type: %s", msg.MsgType) + return + } + + chatType := im.ChatTypeDirect + chatID := "" + if msg.ChatType == "group" { + chatType = im.ChatTypeGroup + chatID = msg.ChatID + } + + // Preserve req_id in Extra for reply routing + reqID := "" + if frame.Headers != nil { + reqID = frame.Headers["req_id"] + } + + incoming := &im.IncomingMessage{ + Platform: im.PlatformWeCom, + UserID: msg.From.UserID, + UserName: msg.From.UserID, + ChatID: chatID, + ChatType: chatType, + Content: strings.TrimSpace(msg.Text.Content), + MessageID: msg.MsgID, + Extra: map[string]string{"req_id": reqID}, + } + + if err := c.handler(ctx, incoming); err != nil { + logger.Errorf(ctx, "[WeCom] Handle message error: %v", err) + } +} + +func (c *LongConnClient) writeJSON(v interface{}) error { + c.mu.Lock() + defer c.mu.Unlock() + if c.conn == nil { + return fmt.Errorf("connection closed") + } + return c.conn.WriteJSON(v) +} + +func reconnectDelay(attempt int) time.Duration { + delay := defaultReconnectBaseDelay * time.Duration(math.Pow(2, float64(attempt-1))) + if delay > defaultReconnectMaxDelay { + delay = defaultReconnectMaxDelay + } + return delay +} diff --git a/internal/router/router.go b/internal/router/router.go index 1c98b2de..77ef3f11 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -59,6 +59,7 @@ type RouterParams struct { CustomAgentHandler *handler.CustomAgentHandler SkillHandler *handler.SkillHandler OrganizationHandler *handler.OrganizationHandler + IMHandler *handler.IMHandler } // NewRouter 创建新的路由 @@ -103,6 +104,9 @@ func NewRouter(params RouterParams) *gin.Engine { serveFrontendStatic(r) } + // IM 回调路由(在认证中间件之前注册,使用各平台自身的签名验证) + RegisterIMRoutes(r, params.IMHandler) + // 认证中间件 r.Use(middleware.Auth(params.TenantService, params.UserService, params.Config)) @@ -576,6 +580,19 @@ func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.Organiza r.POST("/shared-agents/disabled", orgHandler.SetSharedAgentDisabledByMe) } +// RegisterIMRoutes registers IM callback routes. +// These are registered BEFORE auth middleware since IM platforms use their own signature verification. +func RegisterIMRoutes(r *gin.Engine, imHandler *handler.IMHandler) { + im := r.Group("/api/v1/im") + { + // WeCom callback (supports both GET for URL verification and POST for message events) + im.GET("/callback/wecom", imHandler.WeComCallback) + im.POST("/callback/wecom", imHandler.WeComCallback) + // Feishu callback (POST for both URL verification challenge and message events) + im.POST("/callback/feishu", imHandler.FeishuCallback) + } +} + // serveFrontendStatic registers a middleware that serves the frontend SPA // from the ./web directory if it exists. Must be called BEFORE auth middleware // so static files are served without authentication. diff --git a/migrations/versioned/000021_im_channel_sessions.down.sql b/migrations/versioned/000021_im_channel_sessions.down.sql new file mode 100644 index 00000000..2ca2bfb6 --- /dev/null +++ b/migrations/versioned/000021_im_channel_sessions.down.sql @@ -0,0 +1 @@ +DROP TABLE IF EXISTS im_channel_sessions; diff --git a/migrations/versioned/000021_im_channel_sessions.up.sql b/migrations/versioned/000021_im_channel_sessions.up.sql new file mode 100644 index 00000000..175d2d76 --- /dev/null +++ b/migrations/versioned/000021_im_channel_sessions.up.sql @@ -0,0 +1,44 @@ +-- Migration: 000021_im_channel_sessions +-- Description: Create IM channel-to-session mapping table +DO $$ BEGIN RAISE NOTICE '[Migration 000021] Creating table: im_channel_sessions'; END $$; + +CREATE TABLE IF NOT EXISTS im_channel_sessions ( + id VARCHAR(36) PRIMARY KEY DEFAULT uuid_generate_v4(), + platform VARCHAR(20) NOT NULL, + user_id VARCHAR(128) NOT NULL, + chat_id VARCHAR(128) NOT NULL DEFAULT '', + session_id VARCHAR(36) NOT NULL REFERENCES sessions(id) ON DELETE CASCADE, + tenant_id BIGINT NOT NULL, + agent_id VARCHAR(36) DEFAULT '', + status VARCHAR(20) NOT NULL DEFAULT 'active', + metadata JSONB DEFAULT '{}', + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted_at TIMESTAMP WITH TIME ZONE +); + +-- Partial unique index: only enforce uniqueness for non-deleted rows +CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_lookup + ON im_channel_sessions (platform, user_id, chat_id, tenant_id) + WHERE deleted_at IS NULL; + +-- Index for tenant-based queries +CREATE INDEX IF NOT EXISTS idx_im_channel_tenant ON im_channel_sessions (tenant_id); + +-- Index for session-based queries +CREATE INDEX IF NOT EXISTS idx_im_channel_session ON im_channel_sessions (session_id); + +-- Partial index for soft deletes (only index deleted rows) +CREATE INDEX IF NOT EXISTS idx_im_channel_deleted ON im_channel_sessions (deleted_at) WHERE deleted_at IS NOT NULL; + +COMMENT ON TABLE im_channel_sessions IS 'Maps IM platform channels to WeKnora conversation sessions'; +COMMENT ON COLUMN im_channel_sessions.platform IS 'IM platform identifier: wecom, feishu, etc.'; +COMMENT ON COLUMN im_channel_sessions.user_id IS 'Platform-specific user identifier'; +COMMENT ON COLUMN im_channel_sessions.chat_id IS 'Platform-specific chat/group identifier, empty for direct messages'; +COMMENT ON COLUMN im_channel_sessions.session_id IS 'Associated WeKnora session ID'; +COMMENT ON COLUMN im_channel_sessions.tenant_id IS 'Tenant that owns this channel mapping'; +COMMENT ON COLUMN im_channel_sessions.agent_id IS 'Custom agent ID used for this channel, empty for default'; +COMMENT ON COLUMN im_channel_sessions.status IS 'Channel status: active, paused, expired'; +COMMENT ON COLUMN im_channel_sessions.metadata IS 'Platform-specific extra data (JSON)'; + +DO $$ BEGIN RAISE NOTICE '[Migration 000021] im_channel_sessions setup completed successfully!'; END $$; From f16aa128221d8ca30e8fb461a43fc0b6aaf2f65f Mon Sep 17 00:00:00 2001 From: nullkey Date: Sun, 15 Mar 2026 20:42:50 +0800 Subject: [PATCH 09/35] feat: enhance IM integration with streaming support and documentation - add StreamSender interface and streaming output for WeCom/Feishu - refactor WeCom adapter into separate webhook and websocket files - add output_mode config for stream/full toggle per platform - add stream flush batching, dedup cleanup, and think-block filtering - improve context template to handle irrelevant retrieved info gracefully - add IM streaming integration tests - add IM integration documentation with quick start guide --- config/config.yaml | 18 +- docs/IM集成开发文档.md | 630 ++++++++++++++++++ internal/config/config.go | 4 + internal/container/container.go | 12 +- internal/im/adapter.go | 15 + internal/im/feishu/adapter.go | 326 +++++++++ internal/im/service.go | 237 ++++++- internal/im/stream_test.go | 143 ++++ internal/im/wecom/bot_adapter.go | 42 -- internal/im/wecom/longconn.go | 86 +++ .../wecom/{adapter.go => webhook_adapter.go} | 27 +- internal/im/wecom/ws_adapter.go | 62 ++ 12 files changed, 1532 insertions(+), 70 deletions(-) create mode 100644 docs/IM集成开发文档.md create mode 100644 internal/im/stream_test.go delete mode 100644 internal/im/wecom/bot_adapter.go rename internal/im/wecom/{adapter.go => webhook_adapter.go} (90%) create mode 100644 internal/im/wecom/ws_adapter.go diff --git a/config/config.yaml b/config/config.yaml index 4f502e85..2aafb94e 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -207,11 +207,15 @@ conversation: - If the user asks in Chinese, respond in Chinese context_template: | - The following is retrieved information: + The following is retrieved information that may or may not be relevant: {{contexts}} - Based on the above retrieved information, answer the following question: - {{query}} + User question: {{query}} + + Instructions: + - If the retrieved information is relevant to the user's question, use it to provide an accurate answer. + - If the retrieved information is NOT relevant (e.g., the user is greeting, chatting, or asking something unrelated), ignore it and respond naturally as a helpful assistant. + - Do not mention "retrieved information" or "reference materials" in your response unless the user explicitly asks about sources. extract_entities_prompt: | ## Task Extract all entities from the user-provided text that match the following entity types: @@ -553,9 +557,10 @@ im: enabled: true tenant_id: 10000 # WeKnora tenant ID to use agent_id: "" # Default agent ID (optional) - knowledge_base_ids: - - "" # Default knowledge bases (optional) + knowledge_base_ids: + - "2f046c68-869c-460f-866a-b149ac9a5195" # Default knowledge bases (optional) mode: "websocket" # "webhook" or "websocket" + output_mode: "stream" # "stream" (default, real-time) or "full" (wait for complete answer) # --- websocket mode (智能机器人长连接) --- bot_id: "${WECOM_BOT_ID}" # 智能机器人 Bot ID bot_secret: "${WECOM_BOT_SECRET}" # 智能机器人 Secret @@ -570,8 +575,9 @@ im: tenant_id: 10000 # WeKnora tenant ID to use agent_id: "" # Default agent ID (optional) knowledge_base_ids: # Default knowledge bases - - "" + - "2f046c68-869c-460f-866a-b149ac9a5195" mode: "websocket" # "webhook" or "websocket" + output_mode: "stream" # "stream" (default, real-time) or "full" (wait for complete answer) app_id: "${FEISHU_APP_ID}" # 飞书 App ID app_secret: "${FEISHU_APP_SECRET}" # 飞书 App Secret # --- 以下仅 webhook 模式需要,websocket 模式可留空 --- diff --git a/docs/IM集成开发文档.md b/docs/IM集成开发文档.md new file mode 100644 index 00000000..1fb35061 --- /dev/null +++ b/docs/IM集成开发文档.md @@ -0,0 +1,630 @@ +# IM 集成开发文档 + +WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。 + +## 目录 + +- [快速接入指南](#快速接入指南) + - [企业微信接入](#企业微信接入) + - [飞书接入](#飞书接入) +- [配置参考](#配置参考) +- [架构总览](#架构总览) +- [核心概念](#核心概念) +- [数据流](#数据流) +- [接口定义](#接口定义) +- [平台适配器详解](#平台适配器详解) + - [企业微信 (WeCom)](#企业微信-wecom) + - [飞书 (Feishu)](#飞书-feishu) +- [关键参数与阈值](#关键参数与阈值) +- [错误处理](#错误处理) +- [扩展新平台](#扩展新平台) + +--- + +## 快速接入指南 + +### 企业微信接入 + +企业微信提供两种接入模式,根据你的应用类型选择: + +#### 方式一:WebSocket 模式(智能机器人,推荐) + +> 无需公网域名,适合快速验证和内网部署。 + +**第一步:创建智能机器人** + +1. 登录 [企业微信工作台](确认已升级到最新版企业微信) → **智能机器人** → **创建机器人** → **手动创建** → **切换API模式创建** → **选择“使用长连接”** +2. 创建完成后,在机器人详情页获取: + - **BotID** — 机器人唯一标识 + - **BotSecret** — 机器人密钥(点击重置可重新生成) + +**第二步:配置 WeKnora** + +编辑 `config/config.yaml`: + +```yaml +im: + wecom: + enabled: true + mode: "websocket" # 使用 WebSocket 长连接 + output_mode: "stream" # 流式输出(推荐) + tenant_id: ["你的租户ID"] # WeKnora 租户 ID + knowledge_base_ids: ["你的知识库ID"] # 关联的知识库 + bot_id: "${WECOM_BOT_ID}" # 机器人 ID + bot_secret: "${WECOM_BOT_SECRET}" # 机器人 Secret +``` + +**第三步:启动服务** + +启动 WeKnora 后,程序会自动建立到企业微信的 WebSocket 长连接(`wss://openws.work.weixin.qq.com`),无需额外配置回调地址。日志中出现以下内容表示连接成功: + +``` +[IM] WeCom WebSocket connecting (bot_id=xxx)... +``` + +此时在企业微信中给机器人发消息即可收到 AI 回复。 + +--- + +#### 方式二:Webhook 模式(自建应用) + +> 需要公网可达的回调地址,适合已有自建应用的场景。 + +**第一步:创建自建应用** + +1. 登录 [企业微信管理后台](https://work.weixin.qq.com/) → **应用管理** → **自建** → **创建应用** +2. 记录以下信息: + - **CorpID** — 在 **我的企业** → **企业信息** 页面底部 + - **AgentID** — 应用详情页中的 AgentId(整数) + - **Secret** — 应用详情页中的 Secret + +**第二步:配置接收消息** + +1. 在应用详情页 → **接收消息** → **设置 API 接收** +2. 填写: + - **URL**:`https://你的域名/api/v1/im/callback/wecom` + - **Token**:自定义或随机生成(记录下来) + - **EncodingAESKey**:点击随机生成(记录下来) +3. 点击保存,企业微信会发送 GET 验证请求,WeKnora 需先启动以响应验证 + +**第三步:配置 WeKnora** + +```yaml +im: + wecom: + enabled: true + mode: "webhook" # 使用 Webhook 回调 + output_mode: "stream" + tenant_id: ["你的租户ID"] + knowledge_base_ids: ["你的知识库ID"] + corp_id: "${WECOM_CORP_ID}" # 企业 ID + agent_secret: "${WECOM_AGENT_SECRET}" # 应用 Secret + token: "${WECOM_TOKEN}" # 接收消息 Token + encoding_aes_key: "${WECOM_AES_KEY}" # 接收消息 EncodingAESKey + corp_agent_id: 1000001 # 应用 AgentID(整数) +``` + +**第四步:配置可信域名(可选)** + +如需在群聊中使用,在应用详情页 → **网页授权及 JS-SDK** 中添加可信域名。 + +--- + +### 飞书接入 + +飞书同样提供两种模式,WebSocket 模式配置更简单。 + +#### 方式一:WebSocket 模式(推荐) + +> 无需公网域名,无需配置事件加密。 + +**第一步:创建飞书应用** + +1. 登录 [飞书开放平台](https://open.feishu.cn/) → **开发者后台** → **创建企业自建应用** +2. 在 **凭证与基础信息** 页获取: + - **App ID** + - **App Secret** + +**第二步:开通权限与事件** + +1. **添加应用能力**:在应用详情页 → **添加应用能力** → 添加 **机器人** 能力 +2. **配置权限**:在 **权限管理** 中搜索并开通以下权限: + - `im:message` — 获取与发送单聊、群组消息(读写权限) + - `im:message.group_at_msg` — 接收群聊中 @ 机器人消息 + - `im:chat` — 获取群组信息(只读权限,群聊场景需要) + - `cardkit:card` — 创建和更新卡片(**流式输出必需**) +3. **配置事件订阅**: + - 在 **事件与回调** → **事件配置** 中,选择请求方式为 **使用长连接接收事件** + - 添加事件 `im.message.receive_v1`(接收消息) + +**第三步:发布应用** + +在 **版本管理与发布** 中创建版本并提交审核。审核通过后用户才能与机器人交互。 + +**第四步:配置 WeKnora** + +```yaml +im: + feishu: + enabled: true + mode: "websocket" # 使用长连接 + output_mode: "stream" # 流式输出(推荐,需开启 cardkit:card 权限) + tenant_id: ["你的租户ID"] + knowledge_base_ids: ["你的知识库ID"] + app_id: "${FEISHU_APP_ID}" # App ID + app_secret: "${FEISHU_APP_SECRET}" # App Secret + # WebSocket 模式无需 verification_token 和 encrypt_key +``` + +启动后日志出现以下内容表示连接成功: + +``` +[IM] Feishu WebSocket connecting (app_id=xxx)... +``` + +--- + +#### 方式二:Webhook 模式 + +> 需要公网可达的回调地址。 + +**前置步骤**同上(创建应用、开通权限),额外需要: + +1. **配置事件订阅**: + - 在 **事件与回调** → **事件配置** 中,选择请求方式为 **将事件发送到开发者服务器** + - **请求地址**:`https://你的域名/api/v1/im/callback/feishu` + - 记录页面上的 **Encrypt Key** 和 **Verification Token** + - 添加事件 `im.message.receive_v1` +2. 点击保存时飞书会发送 URL 验证请求(challenge),WeKnora 需先启动以响应 + +```yaml +im: + feishu: + enabled: true + mode: "webhook" + output_mode: "stream" + tenant_id: ["你的租户ID"] + knowledge_base_ids: ["你的知识库ID"] + app_id: "${FEISHU_APP_ID}" + app_secret: "${FEISHU_APP_SECRET}" + verification_token: "${FEISHU_TOKEN}" # 事件订阅页面的 Verification Token + encrypt_key: "${FEISHU_ENCRYPT_KEY}" # 事件订阅页面的 Encrypt Key +``` + +--- + +### 通用配置项说明 + +| 配置项 | 类型 | 说明 | +|--------|------|------| +| `enabled` | bool | 是否启用该平台 | +| `tenant_id` | uint64 | 关联的 WeKnora 租户 ID,消息处理在该租户上下文中执行 | +| `agent_id` | string | 指定自定义 Agent(可选,为空则使用默认知识库问答) | +| `knowledge_base_ids` | []string | 默认关联的知识库 ID 列表 | +| `mode` | string | 连接模式:`"websocket"` (长连接) 或 `"webhook"` (HTTP 回调) | +| `output_mode` | string | 输出模式:`"stream"` (实时流式) 或 `"full"` (等待完整回答后一次发送) | + +### 模式选择指南 + +| | Webhook | WebSocket | +|---|---------|-----------| +| 网络要求 | 需要公网可达的 HTTPS 回调地址 | 仅需出站网络,无需公网 | +| 适用场景 | 已有域名和证书、自建应用 | 快速部署、内网环境、PoC 验证 | +| 连接管理 | 无状态,平台推送 | 自动维护长连接、心跳、断线重连 | +| 配置复杂度 | 需要配置回调 URL、加密密钥 | 只需 App ID/Secret | +| 流式输出 | 支持 | 支持 | + +> **建议:** 优先使用 WebSocket 模式,部署更简单,不依赖公网域名。 + +--- + +## 配置参考 + +完整的 `config/config.yaml` 中 `im` 段配置: + +```yaml +im: + wecom: + enabled: true # 是否启用企业微信 + tenant_id: 10000 # 对应的 WeKnora 租户 ID + agent_id: "" # 指定自定义 Agent (可选) + knowledge_base_ids: [] # 默认知识库 ID 列表 + mode: "websocket" # 连接模式: "webhook" | "websocket" + output_mode: "stream" # 输出模式: "stream" (流式) | "full" (完整) + + # ── Webhook 模式配置 (自建应用) ── + corp_id: "${WECOM_CORP_ID}" # 企业 ID + agent_secret: "${WECOM_AGENT_SECRET}" # 应用 Secret + token: "${WECOM_TOKEN}" # 接收消息的 Token + encoding_aes_key: "${WECOM_AES_KEY}" # 接收消息的 EncodingAESKey + corp_agent_id: 1000001 # 应用 AgentID(整数) + + # ── WebSocket 模式配置 (智能机器人) ── + bot_id: "${WECOM_BOT_ID}" # 机器人 ID + bot_secret: "${WECOM_BOT_SECRET}" # 机器人 Secret + + feishu: + enabled: true # 是否启用飞书 + tenant_id: 10000 + agent_id: "" + knowledge_base_ids: [] + mode: "websocket" # "websocket" | "webhook" + output_mode: "stream" # "stream" | "full" + app_id: "${FEISHU_APP_ID}" # 应用 App ID + app_secret: "${FEISHU_APP_SECRET}" # 应用 App Secret + verification_token: "${FEISHU_TOKEN}" # 事件验证 Token (仅 Webhook 模式) + encrypt_key: "${FEISHU_ENCRYPT_KEY}" # 加密密钥 (仅 Webhook 模式) +``` + +> **提示:** 配置值支持环境变量引用(`${VAR_NAME}` 语法),建议将密钥类配置通过环境变量注入,避免明文提交到代码仓库。 + +--- + +## 架构总览 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ IM 集成架构 │ +│ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ 企业微信 │ │ 飞书 │ IM 平台层 │ +│ └────┬─────┘ └────┬─────┘ │ +│ │ Webhook/WS │ Webhook/WS │ +│ ─────┼───────────────┼────────────────────────────────────────────── │ +│ ▼ ▼ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ WeCom │ │ Feishu │ 平台适配器层 (im.Adapter) │ +│ │ Adapter │ │ Adapter │ · 消息解密、解析 │ +│ └────┬─────┘ └────┬─────┘ · 签名验证 │ +│ │ │ · 回复发送、流式推送 │ +│ ─────┼───────────────┼────────────────────────────────────────────── │ +│ └───────┬───────┘ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ im.Service │ 服务编排层 │ +│ │ │ · 消息去重 (MessageID + TTL) │ +│ │ │ · 会话映射 (ChannelSession) │ +│ │ │ · 流式/全量路由 │ +│ └──────┬───────┘ · QA 管道调度 │ +│ │ │ +│ ────────────┼───────────────────────────────────────────────────── │ +│ ▼ │ +│ ┌─────────────────────────────────────┐ │ +│ │ WeKnora Core (QA Pipeline) │ 核心层 │ +│ │ SessionService · MessageService │ │ +│ │ TenantService · AgentService │ │ +│ └─────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**设计模式:** + +| 模式 | 用途 | +|------|------| +| Adapter Pattern | 统一不同 IM 平台的差异,每个平台实现 `im.Adapter` 接口 | +| Strategy Pattern | `StreamSender` 可选接口,让平台按需支持流式输出 | +| Event-Driven | 通过 `EventBus` 解耦 QA 管道与 IM 输出,支持实时块推送 | + +--- + +## 核心概念 + +### IncomingMessage — 统一入站消息 + +所有平台的消息在解密、解析后被归一化为 `IncomingMessage`,抹平平台差异: + +```go +type IncomingMessage struct { + Platform Platform // "wecom" | "feishu" + UserID string // 平台用户标识 + UserName string // 显示名 (可选) + ChatID string // 群聊 ID (私聊为空) + ChatType ChatType // "direct" | "group" + Content string // 纯文本内容 + MessageID string // 平台消息 ID (用于去重) + Extra map[string]string // 平台特有字段 +} +``` + +### ReplyMessage — 统一出站回复 + +```go +type ReplyMessage struct { + Content string // Markdown 文本 + IsStreaming bool // 是否为流式块 + IsFinal bool // 是否为最后一块 + Extra map[string]string // 平台特有字段 +} +``` + +### ChannelSession — 会话映射 + +将 IM 渠道 (平台 + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性: + +``` +(Platform, UserID, ChatID, TenantID) → SessionID +``` + +首次交互自动创建,后续消息复用同一会话。存储于 `im_channel_sessions` 表。 + +--- + +## 数据流 + +### 完整消息处理流程 + +``` +用户在 IM 中发送消息 + │ + ▼ +┌─ HTTP Handler ──────────────────────────────────┐ +│ 1. 签名验证 (VerifyCallback) │ +│ 2. URL 验证处理 (HandleURLVerification) │ +│ 3. 解密 + 解析 → IncomingMessage (ParseCallback) │ +│ 4. 立即返回 HTTP 200 (异步处理) │ +└──────────────────────────┬──────────────────────-┘ + │ goroutine + ▼ +┌─ im.Service ────────────────────────────────────┐ +│ 1. 去重检查 (MessageID, 5 分钟 TTL) │ +│ 2. 内容长度校验 (≤ 4096 字符) │ +│ 3. 解析/创建 ChannelSession │ +│ 4. 获取 WeKnora Session │ +│ 5. 解析自定义 Agent (可选) │ +│ 6. 判断流式/全量模式 │ +└───────────┬─────────────────────┬───────────────┘ + │ │ + 流式模式 ▼ 全量模式 ▼ +┌────────────────────┐ ┌─────────────────────┐ +│ handleMessageStream│ │ runQA (阻塞收集完整 │ +│ │ │ 回答后一次性发送) │ +│ · StartStream │ └─────────────────────┘ +│ · EventBus 订阅 │ +│ · 300ms 批量刷新 │ +│ · SendStreamChunk │ +│ · EndStream │ +└────────────────────┘ + │ + ▼ + 消息持久化 (user + assistant) +``` + +### 流式输出机制 + +流式模式通过 `EventBus` 实时收集 QA 管道产生的内容块,以 **300ms 间隔批量推送**,在延迟与 API 限频之间取得平衡: + +``` +QA 管道 ──chunk──chunk──chunk──▶ EventBus + │ + 每 300ms 刷新 + │ + ┌───────────▼───────────┐ + │ 累积内容 → 完整替换推送 │ + │ (非增量,每次发送全文) │ + └───────────────────────┘ +``` + +**关键细节:** +- `...` 块在流式输出中被过滤,不展示给用户 +- 流式初始化失败时自动降级到全量模式 (`fallbackNonStream`) +- 完整内容(含 thinking)持久化到数据库,确保历史完整 + +--- + +## 接口定义 + +### im.Adapter — 平台适配器 (必须实现) + +```go +type Adapter interface { + Platform() Platform + VerifyCallback(c *gin.Context) error + ParseCallback(c *gin.Context) (*IncomingMessage, error) + SendReply(ctx context.Context, incoming *IncomingMessage, reply *ReplyMessage) error + HandleURLVerification(c *gin.Context) bool +} +``` + +| 方法 | 职责 | +|------|------| +| `Platform()` | 返回平台标识,用于路由和注册 | +| `VerifyCallback()` | 验证回调请求的签名/Token | +| `ParseCallback()` | 解密并解析回调为 `IncomingMessage`,非消息事件返回 `nil` | +| `SendReply()` | 通过平台 API 发送完整回复 | +| `HandleURLVerification()` | 处理平台初始 URL 验证(首次配置时调用) | + +### im.StreamSender — 流式推送 (可选实现) + +```go +type StreamSender interface { + StartStream(ctx context.Context, incoming *IncomingMessage) (streamID string, err error) + SendStreamChunk(ctx context.Context, incoming *IncomingMessage, streamID string, content string) error + EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error +} +``` + +实现此接口后,Service 会自动路由到流式模式。可通过配置 `output_mode: "full"` 强制关闭。 + +--- + +## 平台适配器详解 + +### 企业微信 (WeCom) + +提供两种连接模式,对应两套适配器实现: + +#### Webhook 模式 (`WebhookAdapter`) + +适用于**自建应用**,需要公网可访问的回调地址。 + +``` +企业微信服务器 ──HTTP POST──▶ /api/v1/im/callback/wecom + │ + 解密 (AES-128-CBC) + 解析 XML → IncomingMessage + │ + 处理完成后调用 WeCom REST API 回复 +``` + +- **加密方案:** AES-128-CBC,Key 由 `encoding_aes_key` Base64 解码得到,IV 为 Key 前 16 字节 +- **消息格式:** `random(16) + msg_len(4) + message + corp_id`,PKCS#7 填充 +- **签名验证:** SHA-1(`sort([token, timestamp, nonce, encrypt])`),常量时间比较 +- **回复方式:** 通过 `/cgi-bin/message/send` 接口发送 Markdown 消息 + +#### WebSocket 模式 (`WSAdapter` + `LongConnClient`) + +适用于**智能客服机器人**,无需公网域名,由客户端主动建立 WebSocket 长连接。 + +``` +LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com + │ + 1. 发送 aibot_subscribe (bot_id + secret) + 2. 接收 aibot_msg_callback 消息帧 + 3. 通过 aibot_respond_msg 回复 + 4. 每 30s 心跳保活 (ping/pong) + 5. 断连自动重连 (指数退避 1s → 30s) +``` + +- **认证:** Bot ID + Bot Secret +- **流式回复:** 通过 WebSocket 帧发送,`finish=true` 标记结束 +- **容错:** 指数退避重连,无限重试 + +#### 源码文件 + +| 文件 | 职责 | +|------|------| +| `internal/im/wecom/adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、Token 缓存 | +| `internal/im/wecom/bot_adapter.go` | WebSocket 模式适配器壳,代理到 `LongConnClient` | +| `internal/im/wecom/longconn.go` | WebSocket 客户端:连接管理、心跳、帧协议、自动重连 | + +--- + +### 飞书 (Feishu) + +统一适配器同时支持 Webhook 和 WebSocket 模式,且原生实现 `StreamSender` 接口。 + +#### Webhook 模式 + +``` +飞书服务器 ──HTTP POST──▶ /api/v1/im/callback/feishu + │ + 解密 (AES-256-CBC,可选) + 解析 JSON → IncomingMessage + │ + 通过飞书 Open API 回复 +``` + +- **加密方案:** AES-256-CBC,Key 为 `SHA-256(encrypt_key)`,IV 为密文前 16 字节 +- **事件过滤:** 仅处理 `im.message.receive_v1` 事件,忽略其他事件类型 +- **群消息处理:** 自动去除 `@_user_xxx` 提及前缀 + +#### WebSocket 模式 + +通过飞书官方 SDK (`github.com/larksuite/oapi-sdk-go`) 建立长连接,事件推送与 Webhook 等价,无需公网域名,内置自动重连。 + +#### 流式回复 (CardKit v1) + +飞书的流式输出基于 **CardKit 卡片流式更新**,是官方推荐的最佳实践: + +``` +StartStream: + 1. POST /cardkit/v1/cards → 创建卡片实体 (streaming_mode: true) + 2. POST /im/v1/messages → 发送卡片消息到聊天 + +SendStreamChunk: + 3. PUT /cardkit/v1/cards/{id}/elements/{eid}/content → 更新元素内容 (累积全文) + +EndStream: + 4. PATCH /cardkit/v1/cards/{id}/settings → 设置 streaming_mode: false +``` + +每次 `SendStreamChunk` 发送的是**累积全文**而非增量,由 `feishuStreamState` 跟踪完整内容和严格递增的 `sequence` 序号。 + +#### 源码文件 + +| 文件 | 职责 | +|------|------| +| `internal/im/feishu/adapter.go` | 事件解析、CardKit 流式实现、Token 缓存、AES 解密 | +| `internal/im/feishu/longconn.go` | WebSocket 长连接(封装飞书 SDK) | + +--- + +## 关键参数与阈值 + +| 参数 | 值 | 说明 | +|------|------|------| +| `qaTimeout` | 120s | QA 管道最大执行时间 | +| `dedupTTL` | 5 min | 消息去重 ID 保留时长 | +| `dedupCleanupInterval` | 1 min | 去重清理周期 | +| `maxContentLength` | 4096 | 消息最大长度 (rune),超出截断 | +| `streamFlushInterval` | 300ms | 流式内容批量刷新间隔 | +| WeCom 心跳 | 30s | WebSocket 保活频率 | +| WeCom 重连退避 | 1s → 30s | 指数退避,上限 30 秒 | +| Token 缓存安全余量 | 5 min | Token 过期前提前刷新 | + +--- + +## 错误处理 + +| 场景 | 处理策略 | +|------|---------| +| 流式初始化失败 | 自动降级到全量模式 | +| QA 管道异常 | 回复 "抱歉,处理您的问题时出现了异常,请稍后再试。" | +| QA 超时 (>120s) | 标记消息完成,回复超时提示 | +| 空回答 | 回复 "抱歉,我暂时无法回答这个问题。" | +| WebSocket 断连 | 指数退避自动重连 | +| 平台重试 | MessageID 去重,5 分钟内自动跳过 | + +--- + +## API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET/POST | `/api/v1/im/callback/wecom` | 企业微信回调 (GET 用于 URL 验证) | +| POST | `/api/v1/im/callback/feishu` | 飞书回调 (URL 验证 + 消息事件) | + +--- + +## 扩展新平台 + +接入新的 IM 平台只需 3 步: + +### 1. 实现 `im.Adapter` 接口 + +在 `internal/im//` 下创建适配器: + +```go +package dingtalk + +type Adapter struct { /* 平台配置 */ } + +func (a *Adapter) Platform() im.Platform { return "dingtalk" } +func (a *Adapter) VerifyCallback(c *gin.Context) error { /* 签名验证 */ } +func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { /* 解析消息 */ } +func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { /* 发送回复 */ } +func (a *Adapter) HandleURLVerification(c *gin.Context) bool { /* URL 验证 */ } +``` + +如需流式输出,额外实现 `im.StreamSender`。 + +### 2. 注册适配器 + +在 `internal/container/container.go` 的 `registerIMAdapters` 中初始化并注册: + +```go +if cfg.IM.DingTalk.Enabled { + adapter := dingtalk.NewAdapter(cfg.IM.DingTalk.AppKey, cfg.IM.DingTalk.AppSecret) + imService.RegisterAdapter(adapter) +} +``` + +### 3. 添加回调路由 + +在 `internal/router/router.go` 中注册 HTTP 端点: + +```go +im.POST("/callback/dingtalk", imHandler.DingTalkCallback) +``` + +Service 层 (`im.Service`) 不需要任何修改 —— 消息编排、会话管理、QA 调度、流式控制全部由 Service 统一处理。 diff --git a/internal/config/config.go b/internal/config/config.go index 6405bce9..f6866a1e 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -44,6 +44,8 @@ type WeComIMConfig struct { KnowledgeBases []string `yaml:"knowledge_base_ids" json:"knowledge_base_ids"` // Mode: "webhook" (default, requires public domain) or "websocket" (long connection via intelligent bot, no public domain needed) Mode string `yaml:"mode" json:"mode"` + // OutputMode: "stream" (default, real-time streaming) or "full" (wait for complete answer then send) + OutputMode string `yaml:"output_mode" json:"output_mode"` // --- Webhook mode fields (self-built app callback) --- CorpID string `yaml:"corp_id" json:"corp_id"` AgentSecret string `yaml:"agent_secret" json:"agent_secret"` @@ -67,6 +69,8 @@ type FeishuIMConfig struct { EncryptKey string `yaml:"encrypt_key" json:"encrypt_key"` // Mode: "websocket" (default, long connection, no public domain needed) or "webhook" (requires public domain) Mode string `yaml:"mode" json:"mode"` + // OutputMode: "stream" (default, real-time streaming) or "full" (wait for complete answer then send) + OutputMode string `yaml:"output_mode" json:"output_mode"` } // DocReaderConfig configures the document parser client (gRPC or HTTP). diff --git a/internal/container/container.go b/internal/container/container.go index ab1561cb..0a77b01a 100644 --- a/internal/container/container.go +++ b/internal/container/container.go @@ -960,11 +960,19 @@ func registerIMAdapters(cfg *config.Config, imService *imPkg.Service) { // Register WeCom if cfg.IM.WeCom != nil && cfg.IM.WeCom.Enabled { registerWeComAdapter(ctx, cfg.IM.WeCom, imService) + if cfg.IM.WeCom.OutputMode == "full" { + imService.SetStreamDisabled(imPkg.PlatformWeCom, true) + logger.Infof(ctx, "[IM] WeCom streaming disabled (output_mode=full)") + } } // Register Feishu if cfg.IM.Feishu != nil && cfg.IM.Feishu.Enabled { registerFeishuAdapter(ctx, cfg.IM.Feishu, imService) + if cfg.IM.Feishu.OutputMode == "full" { + imService.SetStreamDisabled(imPkg.PlatformFeishu, true) + logger.Infof(ctx, "[IM] Feishu streaming disabled (output_mode=full)") + } } } @@ -976,7 +984,7 @@ func registerWeComAdapter(ctx context.Context, cfg *config.WeComIMConfig, imServ switch mode { case "webhook": - adapter, err := wecom.NewAdapter( + adapter, err := wecom.NewWebhookAdapter( cfg.CorpID, cfg.AgentSecret, cfg.Token, @@ -999,7 +1007,7 @@ func registerWeComAdapter(ctx context.Context, cfg *config.WeComIMConfig, imServ client := wecom.NewLongConnClient(cfg.BotID, cfg.BotSecret, handler) // Register a BotAdapter so the service can send replies via WebSocket - imService.RegisterAdapter(wecom.NewBotAdapter(client)) + imService.RegisterAdapter(wecom.NewWSAdapter(client)) logger.Infof(ctx, "[IM] WeCom adapter registered (mode=websocket, bot_id=%s)", cfg.BotID) // Start the long connection in a goroutine diff --git a/internal/im/adapter.go b/internal/im/adapter.go index 1cbe6396..d23fd89d 100644 --- a/internal/im/adapter.go +++ b/internal/im/adapter.go @@ -74,3 +74,18 @@ type Adapter interface { // 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) + + // SendStreamChunk appends a content chunk to an ongoing stream. + SendStreamChunk(ctx context.Context, incoming *IncomingMessage, streamID string, content string) error + + // EndStream finalizes a streaming reply. + EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error +} diff --git a/internal/im/feishu/adapter.go b/internal/im/feishu/adapter.go index ac5906fe..7b1ba5ed 100644 --- a/internal/im/feishu/adapter.go +++ b/internal/im/feishu/adapter.go @@ -29,6 +29,9 @@ import ( "github.com/gin-gonic/gin" ) +// Compile-time check that Adapter implements im.StreamSender. +var _ im.StreamSender = (*Adapter)(nil) + var httpClient = &http.Client{Timeout: 10 * time.Second} // Adapter implements im.Adapter for Feishu/Lark. @@ -324,6 +327,329 @@ func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, r return nil } +// ────────────────────────────────────────────────────────────────────── +// Feishu CardKit v1 streaming implementation (official best practice) +// +// Flow: +// 1. POST /cardkit/v1/cards — create card entity +// 2. POST /im/v1/messages content={"type":"card","data":{"card_id":"…"}} — send card +// 3. PUT /cardkit/v1/cards/{id}/elements/{eid}/content — stream element content +// 4. PATCH /cardkit/v1/cards/{id}/settings — set streaming_mode=false +// +// Reference: https://github.com/larksuite/openclaw-lark (official Lark plugin) +// https://open.feishu.cn/document/cardkit-v1/streaming-updates-openapi-overview +// ────────────────────────────────────────────────────────────────────── + +const ( + // streamingElementID is the element_id used in the card JSON for streaming content. + streamingElementID = "streaming_content" +) + +// feishuStreamState tracks per-stream accumulated content. +type feishuStreamState struct { + mu sync.Mutex + content strings.Builder + seq int64 // strictly incrementing sequence for CardKit API +} + +var ( + feishuStreamsMu sync.Mutex + feishuStreams = map[string]*feishuStreamState{} +) + +func (s *feishuStreamState) nextSeq() int { + s.seq++ + return int(s.seq) +} + +// buildStreamingCardJSON builds a Card JSON 2.0 with streaming_mode enabled. +func buildStreamingCardJSON() string { + card := map[string]interface{}{ + "schema": "2.0", + "config": map[string]interface{}{ + "streaming_mode": true, + "summary": map[string]string{"content": "正在思考..."}, + }, + "header": map[string]interface{}{ + "template": "blue", + "title": map[string]string{"tag": "plain_text", "content": "WeKnora"}, + }, + "body": map[string]interface{}{ + "elements": []map[string]interface{}{ + { + "tag": "markdown", + "content": "", + "text_size": "normal", + "element_id": streamingElementID, + }, + }, + }, + } + b, _ := json.Marshal(card) + return string(b) +} + +// StartStream creates a CardKit card entity, sends it as a message, and returns the card_id. +func (a *Adapter) StartStream(ctx context.Context, incoming *im.IncomingMessage) (string, error) { + accessToken, err := a.getTenantAccessToken(ctx) + if err != nil { + return "", fmt.Errorf("get access token: %w", err) + } + + // 1. Create card entity via CardKit API + cardJSON := buildStreamingCardJSON() + cardID, err := a.cardkitCreate(ctx, accessToken, cardJSON) + if err != nil { + return "", fmt.Errorf("create card: %w", err) + } + + // 2. Send the card as a message (content type="card") + if err := a.sendCardByCardID(ctx, accessToken, incoming, cardID); err != nil { + return "", fmt.Errorf("send card message: %w", err) + } + + // 3. Track stream state + feishuStreamsMu.Lock() + feishuStreams[cardID] = &feishuStreamState{} + feishuStreamsMu.Unlock() + + logger.Infof(ctx, "[Feishu] Streaming started: card_id=%s", cardID) + return cardID, nil +} + +// SendStreamChunk accumulates content and pushes it to the card element. +func (a *Adapter) SendStreamChunk(ctx context.Context, incoming *im.IncomingMessage, streamID string, content string) error { + if content == "" { + return nil + } + + feishuStreamsMu.Lock() + state, ok := feishuStreams[streamID] + feishuStreamsMu.Unlock() + if !ok { + return fmt.Errorf("unknown stream ID: %s", streamID) + } + + state.mu.Lock() + state.content.WriteString(content) + fullContent := state.content.String() + seq := state.nextSeq() + state.mu.Unlock() + + accessToken, err := a.getTenantAccessToken(ctx) + if err != nil { + return fmt.Errorf("get access token: %w", err) + } + + return a.cardkitUpdateElement(ctx, accessToken, streamID, streamingElementID, fullContent, seq) +} + +// EndStream disables streaming_mode and cleans up state. +func (a *Adapter) EndStream(ctx context.Context, incoming *im.IncomingMessage, streamID string) error { + feishuStreamsMu.Lock() + state, ok := feishuStreams[streamID] + delete(feishuStreams, streamID) + feishuStreamsMu.Unlock() + + accessToken, err := a.getTenantAccessToken(ctx) + if err != nil { + return fmt.Errorf("get access token: %w", err) + } + + var seq int + if ok { + state.mu.Lock() + seq = state.nextSeq() + state.mu.Unlock() + } + + // Turn off streaming_mode to remove loading indicator + if err := a.cardkitSetStreaming(ctx, accessToken, streamID, false, seq); err != nil { + logger.Warnf(ctx, "[Feishu] Failed to disable streaming_mode: %v", err) + } + + logger.Infof(ctx, "[Feishu] Streaming ended: card_id=%s", streamID) + return nil +} + +// ── CardKit v1 API helpers ── + +// cardkitCreate creates a card entity and returns the card_id. +// POST /open-apis/cardkit/v1/cards +func (a *Adapter) cardkitCreate(ctx context.Context, accessToken, cardJSON string) (string, error) { + payload, _ := json.Marshal(map[string]interface{}{ + "type": "card_json", + "data": cardJSON, + }) + + req, err := http.NewRequestWithContext(ctx, http.MethodPost, + "https://open.feishu.cn/open-apis/cardkit/v1/cards", bytes.NewReader(payload)) + if err != nil { + return "", err + } + req.Header.Set("Content-Type", "application/json; charset=utf-8") + req.Header.Set("Authorization", "Bearer "+accessToken) + + resp, err := httpClient.Do(req) + if err != nil { + return "", err + } + defer resp.Body.Close() + + respBody, err := io.ReadAll(resp.Body) + if err != nil { + return "", fmt.Errorf("read response: %w", err) + } + + var result struct { + Code int `json:"code"` + Msg string `json:"msg"` + Data json.RawMessage `json:"data"` + } + if err := json.Unmarshal(respBody, &result); err != nil { + return "", fmt.Errorf("decode: %w (body: %s)", err, string(respBody)) + } + if result.Code != 0 { + return "", fmt.Errorf("code=%d msg=%s", result.Code, result.Msg) + } + + var data struct { + CardID string `json:"card_id"` + } + if err := json.Unmarshal(result.Data, &data); err != nil { + return "", fmt.Errorf("parse card_id: %w (raw: %s)", err, string(result.Data)) + } + return data.CardID, nil +} + +// sendCardByCardID sends a card_id as an interactive message. +// POST /open-apis/im/v1/messages with content={"type":"card","data":{"card_id":"…"}} +func (a *Adapter) sendCardByCardID(ctx context.Context, accessToken string, incoming *im.IncomingMessage, cardID string) error { + receiveIDType := "open_id" + receiveID := incoming.UserID + if incoming.ChatType == im.ChatTypeGroup && incoming.ChatID != "" { + receiveIDType = "chat_id" + receiveID = incoming.ChatID + } + + // Key: type must be "card" (not "card_id") + content, _ := json.Marshal(map[string]interface{}{ + "type": "card", + "data": map[string]string{"card_id": cardID}, + }) + + payload, _ := json.Marshal(map[string]interface{}{ + "receive_id": receiveID, + "msg_type": "interactive", + "content": string(content), + }) + + apiURL := fmt.Sprintf("https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=%s", receiveIDType) + req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(payload)) + if err != nil { + return err + } + req.Header.Set("Content-Type", "application/json; charset=utf-8") + req.Header.Set("Authorization", "Bearer "+accessToken) + + resp, err := httpClient.Do(req) + if err != nil { + return err + } + defer resp.Body.Close() + + respBody, err := io.ReadAll(resp.Body) + if err != nil { + return fmt.Errorf("read response: %w", err) + } + + var result struct { + Code int `json:"code"` + Msg string `json:"msg"` + } + if err := json.Unmarshal(respBody, &result); err != nil { + return fmt.Errorf("decode: %w (body: %s)", err, string(respBody)) + } + if result.Code != 0 { + return fmt.Errorf("send card error: code=%d msg=%s", result.Code, result.Msg) + } + return nil +} + +// cardkitUpdateElement updates a card element's content for streaming. +// PUT /open-apis/cardkit/v1/cards/:card_id/elements/:element_id/content +func (a *Adapter) cardkitUpdateElement(ctx context.Context, accessToken, cardID, elementID, content string, sequence int) error { + payload, _ := json.Marshal(map[string]interface{}{ + "content": content, + "sequence": sequence, + }) + + apiURL := fmt.Sprintf("https://open.feishu.cn/open-apis/cardkit/v1/cards/%s/elements/%s/content", + cardID, elementID) + req, err := http.NewRequestWithContext(ctx, http.MethodPut, apiURL, bytes.NewReader(payload)) + if err != nil { + return err + } + req.Header.Set("Content-Type", "application/json; charset=utf-8") + req.Header.Set("Authorization", "Bearer "+accessToken) + + resp, err := httpClient.Do(req) + if err != nil { + return err + } + defer resp.Body.Close() + + var result struct { + Code int `json:"code"` + Msg string `json:"msg"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return fmt.Errorf("decode: %w", err) + } + if result.Code != 0 { + return fmt.Errorf("update element error: code=%d msg=%s", result.Code, result.Msg) + } + return nil +} + +// cardkitSetStreaming updates the card's streaming_mode setting. +// PATCH /open-apis/cardkit/v1/cards/:card_id/settings +func (a *Adapter) cardkitSetStreaming(ctx context.Context, accessToken, cardID string, streaming bool, sequence int) error { + settings, _ := json.Marshal(map[string]interface{}{ + "streaming_mode": streaming, + }) + payload, _ := json.Marshal(map[string]interface{}{ + "settings": string(settings), + "sequence": sequence, + }) + + apiURL := fmt.Sprintf("https://open.feishu.cn/open-apis/cardkit/v1/cards/%s/settings", cardID) + req, err := http.NewRequestWithContext(ctx, http.MethodPatch, apiURL, bytes.NewReader(payload)) + if err != nil { + return err + } + req.Header.Set("Content-Type", "application/json; charset=utf-8") + req.Header.Set("Authorization", "Bearer "+accessToken) + + resp, err := httpClient.Do(req) + if err != nil { + return err + } + defer resp.Body.Close() + + var result struct { + Code int `json:"code"` + Msg string `json:"msg"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return fmt.Errorf("decode: %w", err) + } + if result.Code != 0 { + return fmt.Errorf("set streaming error: code=%d msg=%s", result.Code, result.Msg) + } + return nil +} + // getTenantAccessToken retrieves the Feishu tenant access token with caching. // Feishu tokens expire in 2 hours; we cache with a safety margin. func (a *Adapter) getTenantAccessToken(ctx context.Context) (string, error) { diff --git a/internal/im/service.go b/internal/im/service.go index 6fff47d0..f7b39fc2 100644 --- a/internal/im/service.go +++ b/internal/im/service.go @@ -24,6 +24,9 @@ const ( dedupCleanupInterval = 1 * time.Minute // maxContentLength is the maximum allowed message content length. maxContentLength = 4096 + // streamFlushInterval is how often buffered stream content is flushed to the IM platform. + // This prevents API rate-limiting while keeping perceived latency low. + streamFlushInterval = 300 * time.Millisecond ) // Service orchestrates IM message handling: @@ -44,6 +47,9 @@ type Service struct { // processedMsgs tracks recently processed message IDs to prevent duplicate handling. processedMsgs sync.Map + // streamDisabled tracks platforms where streaming is explicitly disabled via output_mode config. + streamDisabled map[Platform]bool + stopCh chan struct{} } @@ -62,6 +68,7 @@ func NewService( tenantService: tenantService, agentService: agentService, adapters: make(map[Platform]Adapter), + streamDisabled: make(map[Platform]bool), stopCh: make(chan struct{}), } @@ -103,6 +110,15 @@ func (s *Service) RegisterAdapter(adapter Adapter) { s.adapters[adapter.Platform()] = adapter } +// SetStreamDisabled disables streaming output for a specific platform. +// When disabled, the service will always collect the full answer before sending, +// even if the adapter implements StreamSender. +func (s *Service) SetStreamDisabled(platform Platform, disabled bool) { + s.mu.Lock() + defer s.mu.Unlock() + s.streamDisabled[platform] = disabled +} + // GetAdapter returns the adapter for a given platform. func (s *Service) GetAdapter(platform Platform) (Adapter, bool) { s.mu.RLock() @@ -163,19 +179,30 @@ func (s *Service) HandleMessage(ctx context.Context, msg *IncomingMessage, tenan } } - // 5. Run the QA pipeline and collect the full answer + // 5. Get the platform adapter + adapter, ok := s.GetAdapter(msg.Platform) + if !ok { + return fmt.Errorf("no adapter for platform: %s", msg.Platform) + } + + // 6. If the adapter supports streaming and streaming is not disabled, use streaming mode; + // otherwise collect full answer. + s.mu.RLock() + disabled := s.streamDisabled[msg.Platform] + s.mu.RUnlock() + if !disabled { + if streamer, ok := adapter.(StreamSender); ok { + return s.handleMessageStream(sessionCtx, msg, session, customAgent, kbIDs, streamer) + } + } + + // Non-streaming fallback: collect full answer then send answer, err := s.runQA(sessionCtx, session, msg.Content, customAgent, kbIDs) if err != nil { logger.Errorf(ctx, "[IM] QA failed: %v, sending fallback reply", err) answer = "抱歉,处理您的问题时出现了异常,请稍后再试。" } - // 6. Send the reply back via the platform adapter - adapter, ok := s.GetAdapter(msg.Platform) - if !ok { - return fmt.Errorf("no adapter for platform: %s", msg.Platform) - } - reply := &ReplyMessage{ Content: answer, IsFinal: true, @@ -249,6 +276,202 @@ func (s *Service) resolveSession(ctx context.Context, msg *IncomingMessage, tena return &cs, nil } +// handleMessageStream runs the QA pipeline and streams answer chunks to the IM platform +// in real-time via the StreamSender interface. Chunks are batched at streamFlushInterval +// to avoid API rate-limiting. +func (s *Service) handleMessageStream(ctx context.Context, msg *IncomingMessage, session *types.Session, customAgent *types.CustomAgent, kbIDs []string, streamer StreamSender) error { + // Start the stream on the IM platform (e.g., create Feishu streaming card) + streamID, err := streamer.StartStream(ctx, msg) + if err != nil { + logger.Warnf(ctx, "[IM] StartStream failed, falling back to non-streaming: %v", err) + return s.fallbackNonStream(ctx, msg, session, customAgent, kbIDs) + } + + // Prepare the QA pipeline + qaCtx, qaCancel := context.WithTimeout(ctx, qaTimeout) + defer qaCancel() + + eventBus := event.NewEventBus() + + var ( + bufMu sync.Mutex + buf strings.Builder // buffered content awaiting flush (answer only) + answerBuilder strings.Builder // full answer for DB persistence (includes ) + qaErr error + done = make(chan struct{}) + closeOnce sync.Once + inThinking bool // tracks whether we're inside a block + ) + closeDone := func() { closeOnce.Do(func() { close(done) }) } + + // Subscribe to answer chunks + eventBus.On(event.EventAgentFinalAnswer, func(_ context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentFinalAnswerData) + if !ok { + return nil + } + + bufMu.Lock() + // Always persist the full content (including thinking) + answerBuilder.WriteString(data.Content) + + // Filter ... blocks from the streamed output. + // The pipeline emits: ..chunks.. then answer chunks. + content := data.Content + if !inThinking { + if strings.HasPrefix(content, "") { + inThinking = true + content = "" // skip this chunk for streaming + } + } + if inThinking { + if idx := strings.Index(content, ""); idx >= 0 { + inThinking = false + // Keep anything after + content = strings.TrimSpace(content[idx+len(""):]) + } else { + content = "" // still inside thinking block + } + } + + if content != "" { + buf.WriteString(content) + } + bufMu.Unlock() + + if data.Done { + closeDone() + } + return nil + }) + + eventBus.On(event.EventError, func(_ context.Context, evt event.Event) error { + data, ok := evt.Data.(event.ErrorData) + if !ok { + return nil + } + logger.Errorf(ctx, "[IM] QA stream error: %s", data.Error) + bufMu.Lock() + qaErr = fmt.Errorf("QA pipeline error: %s", data.Error) + bufMu.Unlock() + closeDone() + return nil + }) + + // Determine whether to use agent mode + useAgent := customAgent != nil && customAgent.IsAgentMode() + requestID := uuid.New().String() + + // Create user message + if _, err := s.messageService.CreateMessage(qaCtx, &types.Message{ + SessionID: session.ID, Role: "user", Content: msg.Content, + RequestID: requestID, CreatedAt: time.Now(), IsCompleted: true, + }); err != nil { + return fmt.Errorf("create user message: %w", err) + } + + // Create placeholder assistant message + assistantMsg, err := s.messageService.CreateMessage(qaCtx, &types.Message{ + SessionID: session.ID, Role: "assistant", + RequestID: requestID, CreatedAt: time.Now(), IsCompleted: false, + }) + if err != nil { + return fmt.Errorf("create assistant message: %w", err) + } + + // Run QA async + go func() { + var err error + if useAgent { + err = s.sessionService.AgentQA(qaCtx, session, msg.Content, assistantMsg.ID, "", eventBus, customAgent, kbIDs, nil) + } else { + err = s.sessionService.KnowledgeQA(qaCtx, session, msg.Content, kbIDs, nil, assistantMsg.ID, "", false, eventBus, customAgent, false) + } + if err != nil { + logger.Errorf(ctx, "[IM] QA stream execution error: %v", err) + bufMu.Lock() + qaErr = fmt.Errorf("QA execution error: %w", err) + bufMu.Unlock() + closeDone() + } + }() + + // Flush loop: periodically send buffered content to the IM platform + ticker := time.NewTicker(streamFlushInterval) + defer ticker.Stop() + + flush := func() { + bufMu.Lock() + chunk := buf.String() + buf.Reset() + bufMu.Unlock() + + if chunk != "" { + if err := streamer.SendStreamChunk(ctx, msg, streamID, chunk); err != nil { + logger.Warnf(ctx, "[IM] SendStreamChunk failed: %v", err) + } + } + } + +loop: + for { + select { + case <-ticker.C: + flush() + case <-done: + break loop + case <-qaCtx.Done(): + break loop + } + } + + // Final flush of any remaining content + flush() + + // End the stream + if err := streamer.EndStream(ctx, msg, streamID); err != nil { + logger.Warnf(ctx, "[IM] EndStream failed: %v", err) + } + + // Persist the full answer + bufMu.Lock() + answer := answerBuilder.String() + finalErr := qaErr + bufMu.Unlock() + + if answer == "" && finalErr != nil { + answer = "抱歉,处理您的问题时出现了异常,请稍后再试。" + } + if answer == "" { + answer = "抱歉,我暂时无法回答这个问题。" + } + + assistantMsg.Content = answer + assistantMsg.IsCompleted = true + if err := s.messageService.UpdateMessage(ctx, assistantMsg); err != nil { + logger.Warnf(ctx, "[IM] Failed to update assistant message: %v", err) + } + + logger.Infof(ctx, "[IM] Stream reply sent: platform=%s user=%s answer_len=%d", msg.Platform, msg.UserID, len(answer)) + return nil +} + +// fallbackNonStream is used when streaming initialization fails. +func (s *Service) fallbackNonStream(ctx context.Context, msg *IncomingMessage, session *types.Session, customAgent *types.CustomAgent, kbIDs []string) error { + answer, err := s.runQA(ctx, session, msg.Content, customAgent, kbIDs) + if err != nil { + logger.Errorf(ctx, "[IM] QA fallback failed: %v", err) + answer = "抱歉,处理您的问题时出现了异常,请稍后再试。" + } + + adapter, ok := s.GetAdapter(msg.Platform) + if !ok { + return fmt.Errorf("no adapter for platform: %s", msg.Platform) + } + + return adapter.SendReply(ctx, msg, &ReplyMessage{Content: answer, IsFinal: true}) +} + // runQA executes the WeKnora QA pipeline and returns the full answer text. func (s *Service) runQA(ctx context.Context, session *types.Session, query string, customAgent *types.CustomAgent, kbIDs []string) (string, error) { // Add timeout to prevent indefinite blocking diff --git a/internal/im/stream_test.go b/internal/im/stream_test.go new file mode 100644 index 00000000..583860af --- /dev/null +++ b/internal/im/stream_test.go @@ -0,0 +1,143 @@ +package im + +import ( + "context" + "sync" + "testing" + "time" +) + +// mockStreamSender is a test double that records streaming calls. +type mockStreamSender struct { + mu sync.Mutex + started bool + streamID string + chunks []string + ended bool +} + +func (m *mockStreamSender) StartStream(_ context.Context, _ *IncomingMessage) (string, error) { + m.mu.Lock() + defer m.mu.Unlock() + m.started = true + m.streamID = "test-stream-1" + return m.streamID, nil +} + +func (m *mockStreamSender) SendStreamChunk(_ context.Context, _ *IncomingMessage, _ string, content string) error { + m.mu.Lock() + defer m.mu.Unlock() + m.chunks = append(m.chunks, content) + return nil +} + +func (m *mockStreamSender) EndStream(_ context.Context, _ *IncomingMessage, _ string) error { + m.mu.Lock() + defer m.mu.Unlock() + m.ended = true + return nil +} + +func (m *mockStreamSender) getChunks() []string { + m.mu.Lock() + defer m.mu.Unlock() + out := make([]string, len(m.chunks)) + copy(out, m.chunks) + return out +} + +func TestStreamSenderInterface(t *testing.T) { + mock := &mockStreamSender{} + + ctx := context.Background() + incoming := &IncomingMessage{ + Platform: PlatformFeishu, + UserID: "test-user", + Content: "hello", + } + + // Start stream + streamID, err := mock.StartStream(ctx, incoming) + if err != nil { + t.Fatalf("StartStream failed: %v", err) + } + if streamID == "" { + t.Fatal("expected non-empty stream ID") + } + + // Send chunks + chunks := []string{"Hello", ", ", "world", "!"} + for _, c := range chunks { + if err := mock.SendStreamChunk(ctx, incoming, streamID, c); err != nil { + t.Fatalf("SendStreamChunk failed: %v", err) + } + } + + // End stream + if err := mock.EndStream(ctx, incoming, streamID); err != nil { + t.Fatalf("EndStream failed: %v", err) + } + + // Verify + if !mock.started { + t.Error("expected stream to be started") + } + if !mock.ended { + t.Error("expected stream to be ended") + } + + got := mock.getChunks() + if len(got) != len(chunks) { + t.Fatalf("expected %d chunks, got %d", len(chunks), len(got)) + } + for i, want := range chunks { + if got[i] != want { + t.Errorf("chunk[%d] = %q, want %q", i, got[i], want) + } + } +} + +func TestStreamFlushBatching(t *testing.T) { + // Simulate the batching behavior: multiple writes within one flush interval + // should be combined into a single chunk. + mock := &mockStreamSender{} + + ctx := context.Background() + incoming := &IncomingMessage{ + Platform: PlatformFeishu, + UserID: "test-user", + Content: "test", + } + + streamID, _ := mock.StartStream(ctx, incoming) + + // Simulate buffer: accumulate content then flush as one chunk + var buf string + tokens := []string{"Hello", " ", "world", "!"} + for _, tok := range tokens { + buf += tok + } + + // Single flush + if err := mock.SendStreamChunk(ctx, incoming, streamID, buf); err != nil { + t.Fatalf("SendStreamChunk failed: %v", err) + } + + got := mock.getChunks() + if len(got) != 1 { + t.Fatalf("expected 1 batched chunk, got %d", len(got)) + } + if got[0] != "Hello world!" { + t.Errorf("batched chunk = %q, want %q", got[0], "Hello world!") + } +} + +func TestStreamFlushIntervalConstant(t *testing.T) { + // Verify the flush interval is set to a reasonable value + if streamFlushInterval < 100*time.Millisecond { + t.Errorf("streamFlushInterval too small: %v (may cause API rate limiting)", streamFlushInterval) + } + if streamFlushInterval > 2*time.Second { + t.Errorf("streamFlushInterval too large: %v (poor user experience)", streamFlushInterval) + } +} diff --git a/internal/im/wecom/bot_adapter.go b/internal/im/wecom/bot_adapter.go deleted file mode 100644 index eccd6911..00000000 --- a/internal/im/wecom/bot_adapter.go +++ /dev/null @@ -1,42 +0,0 @@ -package wecom - -import ( - "context" - "fmt" - - "github.com/Tencent/WeKnora/internal/im" - "github.com/gin-gonic/gin" -) - -// BotAdapter implements im.Adapter for WeCom intelligent bot (long connection mode). -// It delegates SendReply to the WebSocket LongConnClient. -// The webhook methods (VerifyCallback, ParseCallback, HandleURLVerification) are no-ops -// since messages arrive via WebSocket, not HTTP. -type BotAdapter struct { - client *LongConnClient -} - -// NewBotAdapter creates an adapter backed by a WeCom long connection client. -func NewBotAdapter(client *LongConnClient) *BotAdapter { - return &BotAdapter{client: client} -} - -func (a *BotAdapter) Platform() im.Platform { - return im.PlatformWeCom -} - -func (a *BotAdapter) VerifyCallback(c *gin.Context) error { - return fmt.Errorf("WeCom bot adapter does not support webhook callbacks") -} - -func (a *BotAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { - return nil, fmt.Errorf("WeCom bot adapter does not support webhook callbacks") -} - -func (a *BotAdapter) HandleURLVerification(c *gin.Context) bool { - return false -} - -func (a *BotAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { - return a.client.SendReply(ctx, incoming, reply) -} diff --git a/internal/im/wecom/longconn.go b/internal/im/wecom/longconn.go index df04ee9c..b7bd35a9 100644 --- a/internal/im/wecom/longconn.go +++ b/internal/im/wecom/longconn.go @@ -89,6 +89,12 @@ type LongConnClient struct { mu sync.Mutex closed atomic.Bool reqSeq atomic.Int64 + + // streamBufs tracks accumulated content per stream ID. + // WeCom stream protocol is replace-based: each frame's content replaces + // the previously displayed text, so we must send the full accumulated text. + streamBufsMu sync.Mutex + streamBufs map[string]*strings.Builder } // NewLongConnClient creates a WeCom long connection client. @@ -175,6 +181,86 @@ func (c *LongConnClient) SendReply(ctx context.Context, incoming *im.IncomingMes return c.writeJSON(frame) } +// ────────────────────────────────────────────────────────────────────── +// Streaming support: send answer chunks over WebSocket in real-time +// ────────────────────────────────────────────────────────────────────── + +// StartStream begins a streaming reply session. +// Returns a stream ID that must be used in subsequent chunk/end calls. +func (c *LongConnClient) StartStream(ctx context.Context, incoming *im.IncomingMessage) (string, error) { + if _, ok := incoming.Extra["req_id"]; !ok { + return "", fmt.Errorf("missing req_id in incoming message extra") + } + streamID := fmt.Sprintf("stream_%d", c.reqSeq.Add(1)) + + // Initialize the accumulation buffer for this stream + c.streamBufsMu.Lock() + if c.streamBufs == nil { + c.streamBufs = make(map[string]*strings.Builder) + } + c.streamBufs[streamID] = &strings.Builder{} + c.streamBufsMu.Unlock() + + return streamID, nil +} + +// SendStreamChunk accumulates the content and sends the full text so far. +// WeCom stream protocol is replace-based: each frame replaces the previous display. +func (c *LongConnClient) SendStreamChunk(ctx context.Context, incoming *im.IncomingMessage, streamID string, content string) error { + if content == "" { + return nil + } + + // Accumulate + c.streamBufsMu.Lock() + buf, ok := c.streamBufs[streamID] + if !ok { + c.streamBufsMu.Unlock() + return fmt.Errorf("unknown stream ID: %s", streamID) + } + buf.WriteString(content) + fullContent := buf.String() + c.streamBufsMu.Unlock() + + return c.sendStreamFrame(incoming, streamID, fullContent, false) +} + +// EndStream sends the final frame with the full accumulated content and cleans up. +func (c *LongConnClient) EndStream(ctx context.Context, incoming *im.IncomingMessage, streamID string) error { + c.streamBufsMu.Lock() + buf, ok := c.streamBufs[streamID] + var fullContent string + if ok { + fullContent = buf.String() + delete(c.streamBufs, streamID) + } + c.streamBufsMu.Unlock() + + return c.sendStreamFrame(incoming, streamID, fullContent, true) +} + +func (c *LongConnClient) sendStreamFrame(incoming *im.IncomingMessage, streamID, content string, finish bool) error { + reqID := incoming.Extra["req_id"] + + body := streamReplyBody{MsgType: "stream"} + body.Stream.ID = streamID + body.Stream.Finish = finish + body.Stream.Content = content + + bodyBytes, err := json.Marshal(body) + if err != nil { + return fmt.Errorf("marshal stream body: %w", err) + } + + frame := wsFrame{ + Cmd: cmdResponse, + Headers: map[string]string{"req_id": reqID}, + Body: bodyBytes, + } + + return c.writeJSON(frame) +} + func (c *LongConnClient) connectAndRun(ctx context.Context) error { conn, _, err := ws.DefaultDialer.DialContext(ctx, wecomWSEndpoint, nil) if err != nil { diff --git a/internal/im/wecom/adapter.go b/internal/im/wecom/webhook_adapter.go similarity index 90% rename from internal/im/wecom/adapter.go rename to internal/im/wecom/webhook_adapter.go index 98062dc4..e0f4aaf1 100644 --- a/internal/im/wecom/adapter.go +++ b/internal/im/wecom/webhook_adapter.go @@ -35,8 +35,9 @@ import ( var httpClient = &http.Client{Timeout: 10 * time.Second} -// Adapter implements im.Adapter for WeCom. -type Adapter struct { +// WebhookAdapter implements im.Adapter for WeCom in webhook (self-built app callback) mode. +// Messages arrive via HTTP callback; replies are sent via the WeCom REST API. +type WebhookAdapter struct { corpID string token string encodingAESKey string @@ -50,15 +51,15 @@ type Adapter struct { tokenExpAt time.Time } -// NewAdapter creates a new WeCom adapter. -func NewAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID int) (*Adapter, error) { +// NewWebhookAdapter creates a new WeCom webhook adapter. +func NewWebhookAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID int) (*WebhookAdapter, error) { // Decode the AES key from base64 aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=") if err != nil { return nil, fmt.Errorf("decode encoding_aes_key: %w", err) } - return &Adapter{ + return &WebhookAdapter{ corpID: corpID, token: token, encodingAESKey: encodingAESKey, @@ -69,12 +70,12 @@ func NewAdapter(corpID, agentSecret, token, encodingAESKey string, corpAgentID i } // Platform returns the platform identifier. -func (a *Adapter) Platform() im.Platform { +func (a *WebhookAdapter) Platform() im.Platform { return im.PlatformWeCom } // VerifyCallback verifies the WeCom callback signature. -func (a *Adapter) VerifyCallback(c *gin.Context) error { +func (a *WebhookAdapter) VerifyCallback(c *gin.Context) error { timestamp := c.Query("timestamp") nonce := c.Query("nonce") msgSignature := c.Query("msg_signature") @@ -105,7 +106,7 @@ func (a *Adapter) VerifyCallback(c *gin.Context) error { } // HandleURLVerification handles the WeCom URL verification (GET request). -func (a *Adapter) HandleURLVerification(c *gin.Context) bool { +func (a *WebhookAdapter) HandleURLVerification(c *gin.Context) bool { if c.Request.Method != http.MethodGet { return false } @@ -128,7 +129,7 @@ func (a *Adapter) HandleURLVerification(c *gin.Context) bool { } // ParseCallback parses a WeCom callback into a unified IncomingMessage. -func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { +func (a *WebhookAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { bodyBytes, err := io.ReadAll(c.Request.Body) if err != nil { return nil, fmt.Errorf("read body: %w", err) @@ -181,7 +182,7 @@ func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { // SendReply sends a reply message via WeCom API. // For simplicity, this uses the "应用消息" API to proactively send messages. // A production implementation would integrate with the streaming callback model. -func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { +func (a *WebhookAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { // Get access token accessToken, err := a.getAccessToken(ctx) if err != nil { @@ -235,7 +236,7 @@ func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, r // getAccessToken retrieves the WeCom access token with caching. // WeCom tokens expire in 7200 seconds (2 hours); we cache with a safety margin. -func (a *Adapter) getAccessToken(ctx context.Context) (string, error) { +func (a *WebhookAdapter) getAccessToken(ctx context.Context) (string, error) { a.tokenMu.Lock() defer a.tokenMu.Unlock() @@ -282,7 +283,7 @@ func (a *Adapter) getAccessToken(ctx context.Context) (string, error) { } // verifySignature verifies the WeCom callback signature using constant-time comparison. -func (a *Adapter) verifySignature(signature, timestamp, nonce, encrypt string) bool { +func (a *WebhookAdapter) verifySignature(signature, timestamp, nonce, encrypt string) bool { parts := []string{a.token, timestamp, nonce, encrypt} sort.Strings(parts) combined := strings.Join(parts, "") @@ -295,7 +296,7 @@ func (a *Adapter) verifySignature(signature, timestamp, nonce, encrypt string) b } // decrypt decrypts a WeCom AES-encrypted message. -func (a *Adapter) decrypt(encrypted string) ([]byte, error) { +func (a *WebhookAdapter) decrypt(encrypted string) ([]byte, error) { ciphertext, err := base64.StdEncoding.DecodeString(encrypted) if err != nil { return nil, fmt.Errorf("base64 decode: %w", err) diff --git a/internal/im/wecom/ws_adapter.go b/internal/im/wecom/ws_adapter.go new file mode 100644 index 00000000..4040b9e6 --- /dev/null +++ b/internal/im/wecom/ws_adapter.go @@ -0,0 +1,62 @@ +package wecom + +import ( + "context" + "fmt" + + "github.com/Tencent/WeKnora/internal/im" + "github.com/gin-gonic/gin" +) + +// Compile-time checks. +var ( + _ im.Adapter = (*WSAdapter)(nil) + _ im.StreamSender = (*WSAdapter)(nil) +) + +// WSAdapter implements im.Adapter and im.StreamSender for WeCom in WebSocket +// (long connection) mode. It delegates to the WebSocket LongConnClient. +// The webhook methods (VerifyCallback, ParseCallback, HandleURLVerification) are no-ops +// since messages arrive via WebSocket, not HTTP. +type WSAdapter struct { + client *LongConnClient +} + +// NewWSAdapter creates an adapter backed by a WeCom long connection client. +func NewWSAdapter(client *LongConnClient) *WSAdapter { + return &WSAdapter{client: client} +} + +func (a *WSAdapter) Platform() im.Platform { + return im.PlatformWeCom +} + +func (a *WSAdapter) VerifyCallback(c *gin.Context) error { + return fmt.Errorf("WeCom bot adapter does not support webhook callbacks") +} + +func (a *WSAdapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { + return nil, fmt.Errorf("WeCom bot adapter does not support webhook callbacks") +} + +func (a *WSAdapter) HandleURLVerification(c *gin.Context) bool { + return false +} + +func (a *WSAdapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { + return a.client.SendReply(ctx, incoming, reply) +} + +// ── StreamSender implementation ── + +func (a *WSAdapter) StartStream(ctx context.Context, incoming *im.IncomingMessage) (string, error) { + return a.client.StartStream(ctx, incoming) +} + +func (a *WSAdapter) SendStreamChunk(ctx context.Context, incoming *im.IncomingMessage, streamID string, content string) error { + return a.client.SendStreamChunk(ctx, incoming, streamID, content) +} + +func (a *WSAdapter) EndStream(ctx context.Context, incoming *im.IncomingMessage, streamID string) error { + return a.client.EndStream(ctx, incoming, streamID) +} From cc8a99f0a3891210a3d81749649f9a5f9d77405d Mon Sep 17 00:00:00 2001 From: wizardchen Date: Mon, 9 Mar 2026 20:27:24 +0800 Subject: [PATCH 10/35] feat: enhance storage engine configuration and user notifications - Updated the summary length requirement for document summarization to 100-300 words. - Added new localization strings for missing storage engine notifications in English, Korean, Russian, and Chinese. - Implemented UI warnings for users regarding storage engine configuration when files exist, including confirmation dialogs for storage engine changes. - Enhanced backend validation to ensure a storage engine is configured before allowing content uploads. These changes improve user experience by providing clearer guidance on storage engine requirements and enhancing the overall functionality of the knowledge base management system. --- config/config.yaml | 2 +- frontend/src/i18n/locales/en-US.ts | 7 ++- frontend/src/i18n/locales/ko-KR.ts | 6 +++ frontend/src/i18n/locales/ru-RU.ts | 7 ++- frontend/src/i18n/locales/zh-CN.ts | 6 +++ .../src/views/knowledge/KnowledgeBase.vue | 49 +++++++++++++++++++ .../knowledge/KnowledgeBaseEditorModal.vue | 33 ++++++++++++- .../knowledge/settings/KBStorageSettings.vue | 7 ++- internal/application/service/knowledge.go | 32 ++++++++++++ internal/handler/initialization.go | 4 +- 10 files changed, 144 insertions(+), 9 deletions(-) diff --git a/config/config.yaml b/config/config.yaml index 2aafb94e..2a14bac6 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -141,7 +141,7 @@ conversation: You are a precise document summarization expert. Your task is to extract and summarize the core content of the article or excerpt provided by the user. ## Core Requirements - - Summary length should be 50-100 words, adjusted flexibly based on content complexity + - Summary length should be 100-300 words, adjusted flexibly based on content complexity - Generate the summary entirely based on the provided content, without adding any information not present in the article - Ensure the summary captures key information points and main conclusions - Even for complex or specialized content, you must attempt to extract core points for summarization diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index cde8b640..32df9920 100755 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -151,6 +151,9 @@ export default { confirmDeleteQuestion: 'Are you sure you want to delete this question? The corresponding vector index will also be removed.', legacyQuestionCannotDelete: 'Legacy format questions cannot be deleted. Please regenerate questions.', notInitialized: 'Knowledge base is not initialized. Please configure models in settings before uploading files', + missingStorageEngine: 'This knowledge base has no storage engine selected. Please configure a storage engine in settings before uploading content.', + missingStorageEngineUpload: 'Please configure a storage engine before uploading content', + goToStorageSettings: 'Go to Settings', getInfoFailed: 'Failed to get knowledge base information, file upload is not possible', missingId: 'Knowledge base ID is missing', deleteFailed: 'Delete failed. Please try again later!', @@ -1442,7 +1445,8 @@ export default { missingId: 'Knowledge base ID is missing', buildDataFailed: 'Failed to construct submission data', updateSuccess: 'Configuration saved successfully', - indexModeRequired: 'Please select an indexing mode for FAQ knowledge bases' + indexModeRequired: 'Please select an indexing mode for FAQ knowledge bases', + storageChangeConfirm: 'This knowledge base already has files. Changing the storage engine may make old files inaccessible. Do you want to proceed?' }, document: { title: 'Document Management', @@ -3043,6 +3047,7 @@ export default { notConfigured: 'Not Configured', unavailable: 'Unavailable', lockedHint: 'This knowledge base already has files. Cannot switch storage engine. To change, please clear all files first.', + changeWarning: 'Changing the storage engine only affects newly uploaded files. Existing files will still be read from the original storage engine, but some old files may become inaccessible if their paths cannot be automatically recognized.', goGlobalSettings: 'Go to Global Settings', engineLocal: 'Local Storage', engineLocalDesc: 'For single-node deployment, simple and lightweight', diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index 3397adcc..966c22fd 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -160,6 +160,10 @@ export default { docActionUnsupported: "현재 지식베이스 유형은 이 작업을 지원하지 않습니다", notInitialized: "이 지식베이스는 아직 초기화되지 않았습니다. 설정 페이지에서 모델 정보를 먼저 구성한 후 파일을 업로드하세요", + missingStorageEngine: + "이 지식베이스에 스토리지 엔진이 선택되지 않았습니다. 콘텐츠를 업로드하기 전에 설정 페이지에서 스토리지 엔진을 구성하세요.", + missingStorageEngineUpload: "콘텐츠를 업로드하기 전에 스토리지 엔진을 구성하세요", + goToStorageSettings: "설정으로 이동", getInfoFailed: "지식베이스 정보를 가져오는 데 실패하여 파일을 업로드할 수 없습니다", missingId: "지식베이스 ID가 없습니다", deleteFailed: "삭제 실패, 나중에 다시 시도하세요!", @@ -1932,6 +1936,7 @@ export default { buildDataFailed: "데이터 구축 실패", updateSuccess: "설정 저장 성공", indexModeRequired: "FAQ 인덱스 방식을 선택해주세요", + storageChangeConfirm: "지식베이스에 파일이 있습니다. 스토리지 엔진을 변경하면 이전 파일에 접근할 수 없게 될 수 있습니다. 계속하시겠습니까?", }, document: { title: "문서", @@ -3111,6 +3116,7 @@ export default { notConfigured: '미구성', unavailable: '사용 불가', lockedHint: '지식베이스에 파일이 있어 스토리지 엔진을 변경할 수 없습니다. 변경하려면 모든 파일을 먼저 삭제하세요.', + changeWarning: '스토리지 엔진을 변경하면 새로 업로드된 파일에만 영향을 미칩니다. 기존 파일은 여전히 원래 스토리지 엔진에서 읽히지만, 일부 이전 파일의 경로를 자동으로 인식할 수 없어 접근이 불가능할 수 있습니다.', goGlobalSettings: '전역 설정으로 이동', engineLocal: 'Local(로컬 스토리지)', engineLocalDesc: '단일 노드 배포에 적합, 간단하고 가벼움', diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index c5e02379..82138efb 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -129,6 +129,9 @@ export default { confirmDeleteQuestion: 'Вы уверены, что хотите удалить этот вопрос? Соответствующий векторный индекс также будет удален.', legacyQuestionCannotDelete: 'Вопросы в устаревшем формате нельзя удалить. Пожалуйста, сгенерируйте вопросы заново.', notInitialized: 'База знаний не инициализирована. Пожалуйста, настройте модели в разделе настроек перед загрузкой файлов', + missingStorageEngine: 'Для этой базы знаний не выбрано хранилище. Пожалуйста, настройте хранилище в параметрах перед загрузкой содержимого.', + missingStorageEngineUpload: 'Пожалуйста, настройте хранилище перед загрузкой содержимого', + goToStorageSettings: 'Перейти к настройкам', getInfoFailed: 'Не удалось получить информацию о базе знаний, загрузка файла невозможна', missingId: 'Отсутствует ID базы знаний', deleteFailed: 'Не удалось удалить. Пожалуйста, попробуйте позже!', @@ -1611,7 +1614,8 @@ export default { missingId: 'Отсутствует ID базы знаний', buildDataFailed: 'Не удалось сформировать данные для отправки', updateSuccess: 'Настройки сохранены', - indexModeRequired: 'Выберите режим индексации для FAQ базы знаний' + indexModeRequired: 'Выберите режим индексации для FAQ базы знаний', + storageChangeConfirm: 'В базе знаний уже есть файлы. Смена хранилища может сделать старые файлы недоступными. Продолжить?' }, document: { title: 'Управление документами', @@ -2642,6 +2646,7 @@ export default { notConfigured: 'Не настроено', unavailable: 'Недоступно', lockedHint: 'В базе знаний уже есть файлы. Невозможно сменить хранилище. Для смены сначала удалите все файлы.', + changeWarning: 'Смена хранилища влияет только на новые загружаемые файлы. Существующие файлы по-прежнему будут читаться из прежнего хранилища, но некоторые старые файлы могут стать недоступными.', goGlobalSettings: 'Перейти в глобальные настройки', engineLocal: 'Локальное хранилище', engineLocalDesc: 'Для однонодового развёртывания, простое и лёгкое', diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index ba42f3cc..504e8032 100755 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -152,6 +152,10 @@ export default { docActionUnsupported: "当前知识库类型不支持该操作", notInitialized: "该知识库尚未完成初始化配置,请先前往设置页面配置模型信息后再上传文件", + missingStorageEngine: + "该知识库尚未选择存储引擎,请先前往设置页面配置存储引擎后再上传内容。", + missingStorageEngineUpload: "请先配置存储引擎后再上传内容", + goToStorageSettings: "前往配置", getInfoFailed: "获取知识库信息失败,无法上传文件", missingId: "缺少知识库ID", deleteFailed: "删除失败,请稍后再试!", @@ -1901,6 +1905,7 @@ export default { buildDataFailed: "数据构建失败", updateSuccess: "配置保存成功", indexModeRequired: "请选择 FAQ 的索引方式", + storageChangeConfirm: "知识库中已有文件,更改存储引擎后旧文件可能无法正常访问。是否确认更改?", }, document: { title: "文档", @@ -3040,6 +3045,7 @@ export default { notConfigured: "未配置", unavailable: "不可用", lockedHint: "知识库中已有文件,无法切换存储引擎。如需更换,请先清空知识库中的所有文件。", + changeWarning: "更改存储引擎仅影响新上传的文件。已有文件仍使用原存储引擎读取,但部分旧文件可能无法自动识别而导致访问失败。", goGlobalSettings: "去全局设置中配置", engineLocal: "Local(本地存储)", engineLocalDesc: "仅适合单机部署,简单轻量", diff --git a/frontend/src/views/knowledge/KnowledgeBase.vue b/frontend/src/views/knowledge/KnowledgeBase.vue index 494365fc..548bced0 100644 --- a/frontend/src/views/knowledge/KnowledgeBase.vue +++ b/frontend/src/views/knowledge/KnowledgeBase.vue @@ -43,6 +43,11 @@ const folderUploadInputRef = ref(null); const uploading = ref(false); const kbLoading = ref(false); const isFAQ = computed(() => (kbInfo.value?.type || '') === 'faq'); +const missingStorageEngine = computed(() => { + if (!kbInfo.value || isFAQ.value) return false + const spc = kbInfo.value.storage_provider_config + return !spc || !spc.provider +}) const parserEngines = ref([]); const supportedFileTypes = computed>(() => { @@ -947,6 +952,10 @@ const ensureDocumentKbReady = () => { MessagePlugin.warning(t('knowledgeBase.notInitialized')); return false; } + if (missingStorageEngine.value) { + MessagePlugin.warning(t('knowledgeBase.missingStorageEngineUpload')); + return false; + } return true; }; @@ -1459,6 +1468,11 @@ async function createNewSession(value: string): Promise { {{ $t('knowledgeBase.unsupportedTypesHint', { types: unsupportedFileTypes.map(t => '.' + t).join('、') }) }} {{ $t('knowledgeBase.goToParserSettings') }} →

+
+ + {{ $t('knowledgeBase.missingStorageEngine') }} + {{ $t('knowledgeBase.goToStorageSettings') }} → +
@@ -2714,6 +2728,41 @@ async function createNewSession(value: string): Promise { white-space: nowrap; } } + + .storage-engine-warning { + display: flex; + align-items: center; + gap: 6px; + margin: 8px 0 0; + padding: 8px 12px; + background: var(--td-warning-color-1, #fff8e6); + border: 1px solid var(--td-warning-color-3, #ffcc33); + border-radius: 6px; + color: var(--td-warning-color); + font-size: 13px; + line-height: 1.4; + cursor: pointer; + transition: background 0.15s ease; + + &:hover { + background: var(--td-warning-color-2, #fff1c9); + + .warning-link { + text-decoration: underline; + } + } + + .warning-icon { + font-size: 14px; + flex-shrink: 0; + } + + .warning-link { + color: var(--td-brand-color); + margin-left: 2px; + white-space: nowrap; + } + } } diff --git a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue index c43473e4..07c04b34 100644 --- a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue +++ b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue @@ -193,7 +193,7 @@