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 @@
-
+
+
+
+
+
+
{{ $t('agentEditor.imageUpload.label') }}
+
{{ $t('agentEditor.imageUpload.desc') }}
+
+
+
+
+
+
+
+
+
+
{{ $t('agentEditor.imageUpload.vlmModel') }} *
+
{{ $t('agentEditor.imageUpload.vlmModelDesc') }}
+
+
+ formData.config.vlm_model_id = val"
+ @add-model="handleAddModel('vllm')"
+ :placeholder="$t('agentEditor.imageUpload.vlmModelPlaceholder')"
+ />
+
+
+
+
+
+
+
{{ $t('agentEditor.imageUpload.storageProvider') }}
+
{{ $t('agentEditor.imageUpload.storageProviderDesc') }}
+
+
+
@@ -1066,7 +1128,7 @@ import { listModels, type ModelConfig } from '@/api/model';
import { listKnowledgeBases } from '@/api/knowledge-base';
import { listMCPServices, type MCPService } from '@/api/mcp-service';
import { listSkills, type SkillInfo } from '@/api/skill';
-import { getAgentConfig, getConversationConfig } from '@/api/system';
+import { getAgentConfig, getConversationConfig, getStorageEngineStatus, type StorageEngineStatusItem } from '@/api/system';
import { useUIStore } from '@/stores/ui';
import { useOrganizationStore } from '@/stores/organization';
import AgentAvatar from '@/components/AgentAvatar.vue';
@@ -1099,6 +1161,21 @@ const mcpOptions = ref<{ label: string; value: string }[]>([]);
const skillOptions = ref<{ name: string; description: string }[]>([]);
// 是否允许启用 Skills(取决于后端沙箱是否启用,disabled 时为 false;未请求前为 false 避免闪显)
const skillsAvailable = ref(false);
+// 存储引擎可用状态(用于图片存储 provider 选择)
+const storageEngineStatus = ref([]);
+const imageStorageOptions = computed(() => {
+ const statusMap: Record = {};
+ for (const e of storageEngineStatus.value) {
+ statusMap[e.name] = e.available;
+ }
+ return [
+ { value: 'local', label: t('settings.storage.engineLocal'), disabled: false },
+ { value: 'minio', label: 'MinIO', disabled: statusMap.minio === false },
+ { value: 'cos', label: t('settings.storage.engineCos'), disabled: statusMap.cos === false },
+ { value: 'tos', label: t('settings.storage.engineTos'), disabled: statusMap.tos === false },
+ { value: 's3', label: 'Amazon S3', disabled: statusMap.s3 === false },
+ ];
+});
// 系统默认配置(用于内置智能体显示默认提示词)
const defaultAgentSystemPrompt = ref(''); // Agent 模式的默认系统提示词(来自 agent-config)
@@ -1320,6 +1397,10 @@ const defaultFormData = {
// 知识库设置
kb_selection_mode: 'none' as 'all' | 'selected' | 'none',
knowledge_bases: [] as string[],
+ // 图片上传/多模态设置
+ image_upload_enabled: false,
+ vlm_model_id: '',
+ image_storage_provider: '',
// 文件类型限制
supported_file_types: [] as string[],
// FAQ 策略设置
@@ -1642,12 +1723,18 @@ watch(() => uiStore.showSettingsModal, async (visible, prevVisible) => {
// 从设置页面返回时(弹窗关闭),刷新模型列表
if (prevVisible && !visible && props.visible) {
try {
- const models = await listModels();
+ const [models, statusRes] = await Promise.all([
+ listModels(),
+ getStorageEngineStatus(),
+ ]);
if (models && models.length > 0) {
allModels.value = models;
}
+ if (statusRes?.data?.engines) {
+ storageEngineStatus.value = statusRes.data.engines;
+ }
} catch (e) {
- console.warn('Failed to refresh models after settings closed', e);
+ console.warn('Failed to refresh data after settings closed', e);
}
}
});
@@ -1725,6 +1812,16 @@ const loadDependencies = async () => {
skillsAvailable.value = false;
}
+ // 加载存储引擎可用状态(用于图片存储 provider 选择)
+ try {
+ const statusRes = await getStorageEngineStatus();
+ if (statusRes?.data?.engines) {
+ storageEngineStatus.value = statusRes.data.engines;
+ }
+ } catch (e) {
+ console.warn('Failed to load storage engine status', e);
+ }
+
// 加载占位符定义(从统一 API)
try {
const placeholdersRes = await getPlaceholders();
@@ -2627,6 +2724,13 @@ const handleSave = async () => {
return;
}
+ // 校验 VLM 模型(当图片上传启用时必填)
+ if (formData.value.config.image_upload_enabled && !formData.value.config.vlm_model_id) {
+ MessagePlugin.error(t('agentEditor.imageUpload.vlmModelRequired'));
+ currentSection.value = 'model';
+ return;
+ }
+
// 校验 ReRank 模型(当需要时必填)
if (needsRerankModel.value && !formData.value.config.rerank_model_id) {
MessagePlugin.error(t('agent.editor.rerankModelRequired'));
@@ -2914,6 +3018,24 @@ const handleSave = async () => {
}
}
+.select-option-with-tag {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ width: 100%;
+ gap: 8px;
+}
+
+.go-settings-link {
+ font-size: 12px;
+ color: var(--td-brand-color);
+ margin-top: 4px;
+ text-decoration: none;
+ &:hover {
+ text-decoration: underline;
+ }
+}
+
// 名称输入框带头像预览
.name-input-wrapper {
display: flex;
diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vue
index 4cb37b12..278e46d7 100644
--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue
+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue
@@ -33,7 +33,7 @@
-
+
@@ -296,12 +291,7 @@
-
+
@@ -435,6 +425,7 @@ const TOOL_NAME_KEYS: Record = {
todo_write: 'agentStream.tools.todoWrite',
knowledge_graph_extract: 'agentStream.tools.knowledgeGraphExtract',
thinking: 'agentStream.tools.thinking',
+ image_analysis: 'agentStream.tools.imageAnalysis',
};
const getLocalizedToolName = (toolName?: string | null): string => {
@@ -443,6 +434,42 @@ const getLocalizedToolName = (toolName?: string | null): string => {
return key ? t(key) : toolName;
};
+const TOOL_NAME_DISPLAY: Record = {
+ knowledge_search: '语义搜索',
+ search_knowledge: '语义搜索',
+ grep_chunks: '文本搜索',
+ list_knowledge_chunks: '阅读文档内容',
+ get_document_info: '获取文档信息',
+ query_knowledge_graph: '知识图谱查询',
+ web_search: '网络搜索',
+ web_fetch: '网页抓取',
+ todo_write: '制定计划',
+ final_answer: '生成回答',
+ thinking: '思考',
+ read_skill: '读取技能',
+ execute_skill_script: '执行技能脚本',
+ data_analysis: '数据分析',
+ data_schema: '数据结构',
+ database_query: '数据库查询',
+ image_analysis: '查看图片内容',
+};
+
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const ID_LABEL_RE = /\b(knowledge_base_id|knowledge_id|chunk_id|knowledge_base_ids)\s*[:=]\s*/gi;
+
+const sanitizeForDisplay = (text: string): string => {
+ if (!text) return text;
+ let result = text;
+ for (const [name, display] of Object.entries(TOOL_NAME_DISPLAY)) {
+ result = result.replaceAll(name, display);
+ }
+ result = result.replace(ID_LABEL_RE, '');
+ result = result.replace(UUID_RE, '');
+ result = result.replace(/`\s*`/g, '');
+ result = result.replace(/\(\s*\)/g, '');
+ return result;
+};
+
// 根元素引用
const rootElement = ref(null);
@@ -759,13 +786,12 @@ const getThinkingContent = (event: any): string => {
const getThinkingSummary = (event: any): string => {
const content = getThinkingContent(event);
if (!content) return '';
- // Strip markdown formatting and take first meaningful line
- const cleaned = content
- .replace(/^#+\s+/gm, '') // remove heading markers
- .replace(/\*\*/g, '') // remove bold
- .replace(/\*/g, '') // remove italic
- .replace(/`/g, '') // remove code ticks
- .replace(/\n+/g, ' ') // collapse newlines
+ const cleaned = sanitizeForDisplay(content)
+ .replace(/^#+\s+/gm, '')
+ .replace(/\*\*/g, '')
+ .replace(/\*/g, '')
+ .replace(/`/g, '')
+ .replace(/\n+/g, ' ')
.trim();
if (cleaned.length <= 50) return cleaned;
return cleaned.slice(0, 50) + '...';
@@ -1321,12 +1347,12 @@ const preprocessMarkdown = (contentStr: string): string => {
);
};
-// Get tokens from markdown content
+// Get tokens from markdown content (with sanitization for user-friendly display)
const getTokens = (content: any) => {
const contentStr = typeof content === 'string' ? content : String(content || '');
if (!contentStr.trim()) return [];
- const processed = preprocessMarkdown(contentStr);
+ const processed = preprocessMarkdown(sanitizeForDisplay(contentStr));
return marked.lexer(processed);
};
@@ -1524,6 +1550,8 @@ const getToolIcon = (toolName: string): string => {
return documentIcon;
} else if (toolName === 'todo_write') {
return fileAddIcon;
+ } else if (toolName === 'image_analysis') {
+ return thinkingIcon;
} else {
return documentIcon; // default icon
}
@@ -1621,6 +1649,9 @@ const getQueryText = (args: any): string => {
// Get tool title - prefer summary over description, add query for search tools
const getToolTitle = (event: any): string => {
if (event.pending) {
+ if (event.tool_name === 'image_analysis') {
+ return t('agentStream.toolStatus.imageAnalyzing');
+ }
const localizedName = getLocalizedToolName(event.tool_name);
return t('agentStream.toolStatus.calling', { name: localizedName });
}
@@ -1706,6 +1737,9 @@ const getToolTitle = (event: any): string => {
// Tool description
const getToolDescription = (event: any): string => {
if (event.pending) {
+ if (event.tool_name === 'image_analysis') {
+ return t('agentStream.toolStatus.imageAnalyzing');
+ }
const localizedName = getLocalizedToolName(event.tool_name);
return t('agentStream.toolStatus.calling', { name: localizedName });
}
@@ -1723,6 +1757,8 @@ const getToolDescription = (event: any): string => {
return success ? t('agentStream.toolStatus.thinkingDone') : t('agentStream.toolStatus.thinkingFailed');
} else if (toolName === 'todo_write') {
return success ? t('agentStream.toolStatus.updateTodos') : t('agentStream.toolStatus.updateTodosFailed');
+ } else if (toolName === 'image_analysis') {
+ return success ? t('agentStream.toolStatus.imageAnalysisDone') : t('agentStream.toolStatus.imageAnalysisFailed');
} else {
const localizedName = getLocalizedToolName(toolName);
return success ? t('agentStream.toolStatus.called', { name: localizedName }) : t('agentStream.toolStatus.calledFailed', { name: localizedName });
@@ -2121,7 +2157,6 @@ const handleAddToKnowledge = (answerEvent: any) => {
&.action-error {
border-left: 2px solid var(--td-error-color);
- animation: shakeError 0.4s ease-out;
}
&.action-pending {
diff --git a/frontend/src/views/chat/components/usermsg.vue b/frontend/src/views/chat/components/usermsg.vue
index 48b5d768..85145190 100644
--- a/frontend/src/views/chat/components/usermsg.vue
+++ b/frontend/src/views/chat/components/usermsg.vue
@@ -1,5 +1,5 @@
-
+
{{ item.name }}
+
+
+
+
{{ content }}
+
diff --git a/frontend/src/views/knowledge/settings/KBAdvancedSettings.vue b/frontend/src/views/knowledge/settings/KBAdvancedSettings.vue
index 7be04239..9512c64b 100644
--- a/frontend/src/views/knowledge/settings/KBAdvancedSettings.vue
+++ b/frontend/src/views/knowledge/settings/KBAdvancedSettings.vue
@@ -42,57 +42,12 @@
-
-
-
-
{{ $t('knowledgeEditor.advanced.multimodal.label') }}
-
{{ $t('knowledgeEditor.advanced.multimodal.description') }}
-
-
-
-
-
-
-
-
-
-
-
{{ $t('knowledgeEditor.advanced.multimodal.vllmLabel') }} *
-
{{ $t('knowledgeEditor.advanced.multimodal.vllmDescription') }}
-
-
-
-
-
-
-
-
diff --git a/internal/application/repository/retriever/postgres/repository.go b/internal/application/repository/retriever/postgres/repository.go
index 0f8cda4a..cf357e08 100644
--- a/internal/application/repository/retriever/postgres/repository.go
+++ b/internal/application/repository/retriever/postgres/repository.go
@@ -233,10 +233,19 @@ func (g *pgRepository) KeywordsRetrieve(ctx context.Context,
logger.GetLogger(ctx).Infof("[Postgres] Keywords retrieval found %d results", len(embeddingDBList))
results := make([]*types.IndexWithScore, len(embeddingDBList))
+ const maxKeywordResultLog = 8
for i := range embeddingDBList {
results[i] = fromDBVectorEmbeddingWithScore(&embeddingDBList[i], types.MatchTypeKeywords)
- logger.GetLogger(ctx).Debugf("[Postgres] Keywords result %d: chunk=%s, score=%f",
- i, results[i].ChunkID, results[i].Score)
+ if i < maxKeywordResultLog {
+ logger.GetLogger(ctx).Debugf("[Postgres] Keywords result %d: chunk=%s, score=%f",
+ i, results[i].ChunkID, results[i].Score)
+ }
+ }
+ if len(results) > maxKeywordResultLog {
+ logger.GetLogger(ctx).Debugf(
+ "[Postgres] Keywords result summary: total=%d logged=%d truncated=%d",
+ len(results), maxKeywordResultLog, len(results)-maxKeywordResultLog,
+ )
}
return []*types.RetrieveResult{
{
@@ -387,10 +396,19 @@ func (g *pgRepository) VectorRetrieve(ctx context.Context,
logger.GetLogger(ctx).Infof("[Postgres] Vector retrieval found %d results", len(embeddingDBList))
results := make([]*types.IndexWithScore, len(embeddingDBList))
+ const maxVectorResultLog = 8
for i := range embeddingDBList {
results[i] = fromDBVectorEmbeddingWithScore(&embeddingDBList[i], types.MatchTypeEmbedding)
- logger.GetLogger(ctx).Debugf("[Postgres] Vector search result %d: chunk_id %s, score %.4f",
- i, results[i].ChunkID, results[i].Score)
+ if i < maxVectorResultLog {
+ logger.GetLogger(ctx).Debugf("[Postgres] Vector search result %d: chunk_id %s, score %.4f",
+ i, results[i].ChunkID, results[i].Score)
+ }
+ }
+ if len(results) > maxVectorResultLog {
+ logger.GetLogger(ctx).Debugf(
+ "[Postgres] Vector search result summary: total=%d logged=%d truncated=%d",
+ len(results), maxVectorResultLog, len(results)-maxVectorResultLog,
+ )
}
return []*types.RetrieveResult{
{
@@ -494,7 +512,7 @@ func (g *pgRepository) CopyIndices(ctx context.Context,
// Create new vector index, copy the content and vector of the source index
targetVector := &pgVector{
Content: sourceVector.Content,
- SourceID: targetSourceID, // Handle SourceID transformation properly
+ SourceID: targetSourceID, // Handle SourceID transformation properly
SourceType: sourceVector.SourceType,
ChunkID: targetChunkID, // Update to target chunk ID
KnowledgeID: targetKnowledgeID, // Update to target knowledge ID
diff --git a/internal/application/service/chat_pipline/into_chat_message.go b/internal/application/service/chat_pipline/into_chat_message.go
index d9d422cd..a81275f6 100644
--- a/internal/application/service/chat_pipline/into_chat_message.go
+++ b/internal/application/service/chat_pipline/into_chat_message.go
@@ -77,6 +77,30 @@ func (p *PluginIntoChatMessage) OnEvent(ctx context.Context,
// Prepare weekday names
weekdayName := []string{"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}
+ // Intent-based no-search path: bypass "reference materials" template entirely.
+ if chatManage.SkipKBSearch {
+ // Prefer rewritten query in no-search mode; fallback to original query.
+ userContent := safeQuery
+ if rewrite := strings.TrimSpace(chatManage.RewriteQuery); rewrite != "" {
+ if safeRewrite, ok := utils.ValidateInput(rewrite); ok {
+ userContent = safeRewrite
+ } else {
+ pipelineWarn(ctx, "IntoChatMessage", "invalid_rewrite_query_fallback", map[string]interface{}{
+ "session_id": chatManage.SessionID,
+ })
+ }
+ }
+ if chatManage.ImageOCRText != "" && !chatManage.ChatModelSupportsVision {
+ userContent += "\n\n[用户上传图片内容]\n" + chatManage.ImageOCRText
+ }
+ chatManage.UserContent = userContent
+ pipelineInfo(ctx, "IntoChatMessage", "skip_template_no_search", map[string]interface{}{
+ "session_id": chatManage.SessionID,
+ "user_content_len": len(chatManage.UserContent),
+ })
+ return next()
+ }
+
var contextsBuilder strings.Builder
// Build contexts string based on FAQ priority strategy
diff --git a/internal/application/service/chat_pipline/rerank.go b/internal/application/service/chat_pipline/rerank.go
index 3b6cd0c1..94560316 100644
--- a/internal/application/service/chat_pipline/rerank.go
+++ b/internal/application/service/chat_pipline/rerank.go
@@ -121,15 +121,7 @@ func (p *PluginRerank) OnEvent(ctx context.Context,
"result_cnt": len(rerankResp),
})
- // Log input scores before reranking for debugging
- for i, sr := range chatManage.SearchResult {
- pipelineInfo(ctx, "Rerank", "input_score", map[string]interface{}{
- "index": i,
- "chunk_id": sr.ID,
- "score": fmt.Sprintf("%.4f", sr.Score),
- "match_type": sr.MatchType,
- })
- }
+ logRerankInputScoreSample(ctx, chatManage.SearchResult)
for i := range chatManage.SearchResult {
chatManage.SearchResult[i].Metadata = ensureMetadata(chatManage.SearchResult[i].Metadata)
@@ -162,13 +154,6 @@ func (p *PluginRerank) OnEvent(ctx context.Context,
})
}
- pipelineInfo(ctx, "Rerank", "composite_calc", map[string]interface{}{
- "chunk_id": sr.ID,
- "base_score": fmt.Sprintf("%.4f", base),
- "model_score": fmt.Sprintf("%.4f", modelScore),
- "final_score": fmt.Sprintf("%.4f", sr.Score),
- "match_type": sr.MatchType,
- })
reranked = append(reranked, sr)
}
@@ -179,13 +164,6 @@ func (p *PluginRerank) OnEvent(ctx context.Context,
// Assign high model score for direct load items
modelScore := 1.0
sr.Score = compositeScore(sr, modelScore, base)
- pipelineInfo(ctx, "Rerank", "composite_calc_direct", map[string]interface{}{
- "chunk_id": sr.ID,
- "base_score": fmt.Sprintf("%.4f", base),
- "model_score": fmt.Sprintf("%.4f", modelScore),
- "final_score": fmt.Sprintf("%.4f", sr.Score),
- "match_type": sr.MatchType,
- })
reranked = append(reranked, sr)
}
final := applyMMR(ctx, reranked, chatManage, min(len(reranked), max(1, chatManage.RerankTopK)), 0.7)
@@ -237,18 +215,26 @@ func (p *PluginRerank) rerank(ctx context.Context,
pipelineInfo(ctx, "Rerank", "threshold", map[string]interface{}{
"threshold": chatManage.RerankThreshold,
})
- for i := range min(5, len(rerankResp)) {
+ logged := min(5, len(rerankResp))
+ for i := range logged {
if rerankResp[i].Index < len(candidates) {
pipelineInfo(ctx, "Rerank", "top_score", map[string]interface{}{
- "rank": i + 1,
- "score": rerankResp[i].RelevanceScore,
- "chunk_id": candidates[rerankResp[i].Index].ID,
- "match_type": candidates[rerankResp[i].Index].MatchType,
- "chunk_type": candidates[rerankResp[i].Index].ChunkType,
- "content": candidates[rerankResp[i].Index].Content,
+ "rank": i + 1,
+ "score": rerankResp[i].RelevanceScore,
+ "chunk_id": candidates[rerankResp[i].Index].ID,
+ "match_type": candidates[rerankResp[i].Index].MatchType,
+ "chunk_type": candidates[rerankResp[i].Index].ChunkType,
+ "content_len": len(candidates[rerankResp[i].Index].Content),
})
}
}
+ if len(rerankResp) > logged {
+ pipelineInfo(ctx, "Rerank", "top_score_summary", map[string]interface{}{
+ "total": len(rerankResp),
+ "logged": logged,
+ "truncated": len(rerankResp) - logged,
+ })
+ }
// Filter results based on threshold
rankFilter := []rerank.RankResult{}
@@ -529,11 +515,26 @@ func getEnrichedPassage(ctx context.Context, result *types.SearchResult) string
}
combinedText += strings.Join(enrichments, "\n")
- pipelineInfo(ctx, "Rerank", "passage_enrich", map[string]interface{}{
- "content_len": len(result.Content),
- "cleaned_len": len(cleanPassageForRerank(result.Content)),
- "enrichment_len": len(strings.Join(enrichments, "\n")),
- })
-
return combinedText
}
+
+func logRerankInputScoreSample(ctx context.Context, results []*types.SearchResult) {
+ const maxLogRows = 8
+ limit := min(maxLogRows, len(results))
+ for i := 0; i < limit; i++ {
+ sr := results[i]
+ pipelineInfo(ctx, "Rerank", "input_score", map[string]interface{}{
+ "index": i,
+ "chunk_id": sr.ID,
+ "score": fmt.Sprintf("%.4f", sr.Score),
+ "match_type": sr.MatchType,
+ })
+ }
+ if len(results) > limit {
+ pipelineInfo(ctx, "Rerank", "input_score_summary", map[string]interface{}{
+ "total": len(results),
+ "logged": limit,
+ "truncated": len(results) - limit,
+ })
+ }
+}
diff --git a/internal/application/service/chat_pipline/rewrite.go b/internal/application/service/chat_pipline/rewrite.go
index 8b31c96d..1a0ba737 100644
--- a/internal/application/service/chat_pipline/rewrite.go
+++ b/internal/application/service/chat_pipline/rewrite.go
@@ -11,9 +11,11 @@ import (
"time"
"github.com/Tencent/WeKnora/internal/config"
+ "github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/google/uuid"
)
// PluginRewrite is a plugin for rewriting user queries
@@ -26,10 +28,10 @@ type PluginRewrite struct {
// reg is a regular expression used to match and remove content between tags
var reg = regexp.MustCompile(`(?s).*? `)
+var rewriteImageSepPattern = regexp.MustCompile(`(?s)^(.*?)\s*\n?---\n(.*)$`)
const (
- noSearchPrefix = "[NO_SEARCH]"
- imageDescSeparator = "\n---\n"
+ noSearchPrefix = "[NO_SEARCH]"
)
// NewPluginRewrite creates a new query rewriting plugin instance
@@ -118,8 +120,23 @@ func (p *PluginRewrite) OnEvent(ctx context.Context,
maxTokens = 500
}
+ // --- Emit progress event for image analysis ---
+ var toolCallID string
+ if useImages && chatManage.EventBus != nil {
+ toolCallID = uuid.New().String()
+ chatManage.EventBus.Emit(ctx, types.Event{
+ Type: types.EventType(event.EventAgentToolCall),
+ SessionID: chatManage.SessionID,
+ Data: event.AgentToolCallData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ },
+ })
+ }
+
// --- Call model ---
thinking := false
+ vlmStart := time.Now()
response, err := rewriteModel.Chat(ctx, []chat.Message{
{Role: "system", Content: systemContent},
userMsg,
@@ -129,6 +146,19 @@ func (p *PluginRewrite) OnEvent(ctx context.Context,
Thinking: &thinking,
})
if err != nil {
+ if toolCallID != "" && chatManage.EventBus != nil {
+ chatManage.EventBus.Emit(ctx, types.Event{
+ Type: types.EventType(event.EventAgentToolResult),
+ SessionID: chatManage.SessionID,
+ Data: event.AgentToolResultData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ Output: "图片分析失败",
+ Success: false,
+ Duration: time.Since(vlmStart).Milliseconds(),
+ },
+ })
+ }
pipelineError(ctx, "Rewrite", "model_call", map[string]interface{}{
"session_id": chatManage.SessionID,
"error": err.Error(),
@@ -136,9 +166,23 @@ func (p *PluginRewrite) OnEvent(ctx context.Context,
return next()
}
+ // --- Emit completion event for image analysis ---
+ if toolCallID != "" && chatManage.EventBus != nil {
+ chatManage.EventBus.Emit(ctx, types.Event{
+ Type: types.EventType(event.EventAgentToolResult),
+ SessionID: chatManage.SessionID,
+ Data: event.AgentToolResultData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ Output: "已分析图片内容",
+ Success: true,
+ Duration: time.Since(vlmStart).Milliseconds(),
+ },
+ })
+ }
+
// --- Parse structured output ---
p.parseRewriteOutput(chatManage, response.Content)
-
pipelineInfo(ctx, "Rewrite", "output", map[string]interface{}{
"session_id": chatManage.SessionID,
"rewrite_query": chatManage.RewriteQuery,
@@ -261,6 +305,13 @@ func (p *PluginRewrite) buildPrompts(chatManage *types.ChatManage, historyList [
if chatManage.RewritePromptSystem != "" {
systemPrompt = chatManage.RewritePromptSystem
}
+ // Strengthen context inheritance in multi-turn conversation:
+ // for follow-up questions that clearly refer to previous turns (especially
+ // uploaded-image understanding), prefer NO_SEARCH over KB retrieval.
+ systemPrompt += "\n\n## Additional Context Inheritance Guidance\n" +
+ "- If the current question is a follow-up to previous conversation content (especially previously uploaded images) and can be answered by that context, you MUST classify it as NO_SEARCH.\n" +
+ "- Examples: “第一张图再详细描述一下”, “第二张门上的字是什么意思”, “这个再展开讲讲”.\n" +
+ "- In these follow-up cases, output with [NO_SEARCH] prefix."
conversationText := formatConversationHistory(historyList)
currentTime := time.Now().Format("2006-01-02 15:04:05")
@@ -296,11 +347,16 @@ func (p *PluginRewrite) parseRewriteOutput(chatManage *types.ChatManage, raw str
content = strings.TrimSpace(strings.TrimPrefix(content, noSearchPrefix))
}
- // 2. Split rewritten query and image description
- if idx := strings.Index(content, imageDescSeparator); idx >= 0 {
- chatManage.RewriteQuery = strings.TrimSpace(content[:idx])
- chatManage.ImageOCRText = strings.TrimSpace(content[idx+len(imageDescSeparator):])
- } else if content != "" {
+ // 2. Split rewritten query and image description.
+ // Be tolerant to model output variants like:
+ // - "query\n---\nimage_desc" (expected)
+ // - "query---\nimage_desc" (missing leading newline before separator)
+ if m := rewriteImageSepPattern.FindStringSubmatch(content); len(m) == 3 {
+ chatManage.RewriteQuery = strings.TrimSpace(m[1])
+ chatManage.ImageOCRText = strings.TrimSpace(m[2])
+ return
+ }
+ if content != "" {
chatManage.RewriteQuery = content
}
}
diff --git a/internal/application/service/chat_pipline/search.go b/internal/application/service/chat_pipline/search.go
index 8d9ed23d..4422f2cb 100644
--- a/internal/application/service/chat_pipline/search.go
+++ b/internal/application/service/chat_pipline/search.go
@@ -113,15 +113,7 @@ func (p *PluginSearch) OnEvent(ctx context.Context,
chatManage.SearchResult = allResults
- // Log all search results with scores before any processing
- for i, r := range chatManage.SearchResult {
- pipelineInfo(ctx, "Search", "result_score_before_normalize", map[string]interface{}{
- "index": i,
- "chunk_id": r.ID,
- "score": fmt.Sprintf("%.4f", r.Score),
- "match_type": r.MatchType,
- })
- }
+ logSearchScoreSample(ctx, "result_score_before_normalize", chatManage.SearchResult)
// If recall is low, attempt query expansion with keyword-focused search
if chatManage.EnableQueryExpansion && len(chatManage.SearchResult) < max(1, chatManage.EmbeddingTopK) {
@@ -131,15 +123,7 @@ func (p *PluginSearch) OnEvent(ctx context.Context,
}
}
- // Log final scores after all processing
- for i, r := range chatManage.SearchResult {
- pipelineInfo(ctx, "Search", "final_score", map[string]interface{}{
- "index": i,
- "chunk_id": r.ID,
- "score": fmt.Sprintf("%.4f", r.Score),
- "match_type": r.MatchType,
- })
- }
+ logSearchScoreSample(ctx, "final_score", chatManage.SearchResult)
// Return if we have results
if len(chatManage.SearchResult) != 0 {
@@ -204,6 +188,27 @@ func buildContentSignature(content string) string {
return searchutil.BuildContentSignature(content)
}
+func logSearchScoreSample(ctx context.Context, action string, results []*types.SearchResult) {
+ const maxLogRows = 8
+ limit := min(maxLogRows, len(results))
+ for i := 0; i < limit; i++ {
+ r := results[i]
+ pipelineInfo(ctx, "Search", action, map[string]interface{}{
+ "index": i,
+ "chunk_id": r.ID,
+ "score": fmt.Sprintf("%.4f", r.Score),
+ "match_type": r.MatchType,
+ })
+ }
+ if len(results) > limit {
+ pipelineInfo(ctx, "Search", action+"_summary", map[string]interface{}{
+ "total": len(results),
+ "logged": limit,
+ "truncated": len(results) - limit,
+ })
+ }
+}
+
// searchByTargets performs KB searches using pre-computed SearchTargets
// This is the main search method that uses the unified search targets
func (p *PluginSearch) searchByTargets(
diff --git a/internal/application/service/knowledgebase.go b/internal/application/service/knowledgebase.go
index 41f4c029..310f2b11 100644
--- a/internal/application/service/knowledgebase.go
+++ b/internal/application/service/knowledgebase.go
@@ -1231,6 +1231,9 @@ func (s *knowledgeBaseService) processSearchResults(ctx context.Context,
// Build final search results - preserve original order from input chunks
var searchResults []*types.SearchResult
addedChunkIDs := make(map[string]bool)
+ const maxInvalidChunkLog = 8
+ invalidChunkCnt := 0
+ invalidChunkSamples := make([]string, 0, maxInvalidChunkLog)
// First pass: Add results in the original order from input chunks
for _, inputChunk := range chunks {
@@ -1240,7 +1243,10 @@ func (s *knowledgeBaseService) processSearchResults(ctx context.Context,
continue
}
if !s.isValidTextChunk(chunk) {
- logger.Debugf(ctx, "Chunk is not valid text chunk: %s, type: %s", chunk.ID, chunk.ChunkType)
+ invalidChunkCnt++
+ if len(invalidChunkSamples) < maxInvalidChunkLog {
+ invalidChunkSamples = append(invalidChunkSamples, chunk.ID+":"+chunk.ChunkType)
+ }
continue
}
if addedChunkIDs[chunk.ID] {
@@ -1257,6 +1263,12 @@ func (s *knowledgeBaseService) processSearchResults(ctx context.Context,
logger.Warnf(ctx, "Knowledge not found for chunk: %s, knowledge_id: %s", chunk.ID, chunk.KnowledgeID)
}
}
+ if invalidChunkCnt > 0 {
+ logger.Debugf(ctx,
+ "Skip non-text chunks in search results: total=%d sampled=%d samples=%v",
+ invalidChunkCnt, len(invalidChunkSamples), invalidChunkSamples,
+ )
+ }
// Second pass: Add additional chunks (parent, nearby, relation) that weren't in original input
if !skipEnrichment {
diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.go
index 308dd17b..ad566399 100644
--- a/internal/handler/session/qa.go
+++ b/internal/handler/session/qa.go
@@ -165,21 +165,10 @@ func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestCo
return nil, nil, errors.NewBadRequestError(fmt.Sprintf("Image save failed: %v", err))
}
- // Decide whether to run VLM analysis here or defer.
- // Agent mode defers to the async execution flow (so SSE stream is up and progress is visible).
- // Normal mode defers when the RAG pipeline will run (rewrite step handles it).
- // Only run here for Normal mode pure-chat paths (no KB, no web search).
- isAgentEntry := logPrefix == "AgentQA"
- hasRequestKBs := len(kbIDs) > 0 || len(knowledgeIDs) > 0
- agentWillResolveKBs := !hasRequestKBs &&
- !customAgent.Config.RetrieveKBOnlyWhenMentioned &&
- customAgent.Config.KBSelectionMode != "" &&
- customAgent.Config.KBSelectionMode != "none"
- willDeferVLM := isAgentEntry || hasRequestKBs || agentWillResolveKBs || request.WebSearchEnabled
- if !willDeferVLM {
- agentVLMModelID := customAgent.Config.VLMModelID
- h.analyzeImageAttachments(ctx, request.Images, agentVLMModelID, request.Query)
- }
+ // VLM analysis is always deferred to after SSE stream is up:
+ // - Agent mode: runs in async execution flow with tool_call/tool_result events
+ // - Normal RAG mode: runs in the pipeline rewrite step with progress events
+ // - Normal pure-chat mode: runs in the async goroutine with progress events
}
// Build request context
@@ -478,6 +467,54 @@ func (h *Handler) executeNormalModeQA(reqCtx *qaRequestContext, generateTitle bo
}
}()
+ // For pure-chat path (no KB, no web search), VLM analysis isn't handled by the
+ // rewrite pipeline step, so run it here with progress events.
+ // RAG paths (with KB/web search, including agent-resolved KBs) defer VLM analysis
+ // to the rewrite step to avoid duplicate progress events.
+ hasRequestKBs := len(reqCtx.knowledgeBaseIDs) > 0 || len(reqCtx.knowledgeIDs) > 0
+ agentWillResolveKBs := false
+ if !hasRequestKBs && reqCtx.customAgent != nil && !reqCtx.customAgent.Config.RetrieveKBOnlyWhenMentioned {
+ mode := reqCtx.customAgent.Config.KBSelectionMode
+ switch mode {
+ case "all":
+ agentWillResolveKBs = true
+ case "selected", "":
+ // "" keeps backward-compatible behavior (same as selected).
+ agentWillResolveKBs = len(reqCtx.customAgent.Config.KnowledgeBases) > 0
+ case "none":
+ agentWillResolveKBs = false
+ default:
+ agentWillResolveKBs = len(reqCtx.customAgent.Config.KnowledgeBases) > 0
+ }
+ }
+ isPureChatPath := !hasRequestKBs && !agentWillResolveKBs && !reqCtx.webSearchEnabled
+ if isPureChatPath && len(reqCtx.images) > 0 &&
+ reqCtx.customAgent != nil && reqCtx.customAgent.Config.VLMModelID != "" {
+ toolCallID := uuid.New().String()
+ streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
+ Type: event.EventAgentToolCall,
+ SessionID: sessionID,
+ Data: event.AgentToolCallData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ },
+ })
+ vlmStart := time.Now()
+ h.analyzeImageAttachments(streamCtx.asyncCtx, reqCtx.images,
+ reqCtx.customAgent.Config.VLMModelID, reqCtx.query)
+ streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
+ Type: event.EventAgentToolResult,
+ SessionID: sessionID,
+ Data: event.AgentToolResultData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ Output: "已分析图片内容",
+ Success: true,
+ Duration: time.Since(vlmStart).Milliseconds(),
+ },
+ })
+ }
+
imageURLs, imageOCRText := extractImageURLsAndOCRText(reqCtx.images)
err := h.sessionService.KnowledgeQA(
streamCtx.asyncCtx,
diff --git a/internal/logger/logger.go b/internal/logger/logger.go
index 7fbfc13c..ed78113b 100644
--- a/internal/logger/logger.go
+++ b/internal/logger/logger.go
@@ -82,10 +82,10 @@ func (f *CustomFormatter) Format(entry *logrus.Entry) ([]byte, error) {
// request_id 优先输出
if v, ok := entry.Data["request_id"]; ok {
if f.ForceColor {
- fields += fmt.Sprintf("%srequest_id%s=%s%v%s ",
- colorCyan, colorReset, colorBlue, v, colorReset)
+ fields += fmt.Sprintf("%s%v%s ",
+ colorBlue, v, colorReset)
} else {
- fields += fmt.Sprintf("request_id=%v ", v)
+ fields += fmt.Sprintf("%v ", v)
}
}
diff --git a/internal/models/chat/image_resolve.go b/internal/models/chat/image_resolve.go
index d7f41577..c4503b81 100644
--- a/internal/models/chat/image_resolve.go
+++ b/internal/models/chat/image_resolve.go
@@ -3,6 +3,7 @@ package chat
import (
"encoding/base64"
"fmt"
+ "log"
"net/http"
"os"
"path/filepath"
@@ -55,6 +56,7 @@ func readLocalStorageBytes(storagePath string) []byte {
localPath := filepath.Join(baseDir, filepath.FromSlash(relPath))
data, err := os.ReadFile(localPath)
if err != nil {
+ log.Printf("[image-resolve] failed to read local file %s: %v", localPath, err)
return nil
}
return data
diff --git a/internal/models/rerank/aliyun_reranker.go b/internal/models/rerank/aliyun_reranker.go
index 3643b7f7..75103c87 100644
--- a/internal/models/rerank/aliyun_reranker.go
+++ b/internal/models/rerank/aliyun_reranker.go
@@ -112,10 +112,7 @@ func (r *AliyunReranker) Rerank(ctx context.Context, query string, documents []s
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", r.apiKey))
- // Log the curl equivalent for debugging
- logger.Debugf(ctx, "curl -X POST %s -H \"Content-Type: application/json\" -H \"Authorization: Bearer %s\" -d '%s'",
- r.baseURL, r.apiKey, string(jsonData),
- )
+ logger.Debugf(ctx, "%s", buildRerankRequestDebug(r.modelName, r.baseURL, query, documents))
resp, err := r.client.Do(req)
if err != nil {
diff --git a/internal/models/rerank/jina_reranker.go b/internal/models/rerank/jina_reranker.go
index 4b7b1947..5067123e 100644
--- a/internal/models/rerank/jina_reranker.go
+++ b/internal/models/rerank/jina_reranker.go
@@ -80,11 +80,7 @@ func (r *JinaReranker) Rerank(ctx context.Context, query string, documents []str
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),
- )
+ logger.Debugf(ctx, "%s", buildRerankRequestDebug(r.modelName, fmt.Sprintf("%s/rerank", r.baseURL), query, documents))
resp, err := r.client.Do(req)
if err != nil {
diff --git a/internal/models/rerank/logging.go b/internal/models/rerank/logging.go
new file mode 100644
index 00000000..de38c111
--- /dev/null
+++ b/internal/models/rerank/logging.go
@@ -0,0 +1,42 @@
+package rerank
+
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+ "unicode/utf8"
+)
+
+const (
+ maxLogDocuments = 3
+ maxLogTextRunes = 120
+)
+
+func buildRerankRequestDebug(model, endpoint, query string, documents []string) string {
+ previews := make([]string, 0, maxLogDocuments)
+ for i, doc := range documents {
+ if i >= maxLogDocuments {
+ break
+ }
+ previews = append(previews, compactForLog(doc, maxLogTextRunes))
+ }
+
+ previewJSON, _ := json.Marshal(previews)
+ return fmt.Sprintf(
+ "rerank request endpoint=%s model=%s query_preview=%q query_runes=%d documents=%d preview_docs=%s",
+ endpoint,
+ model,
+ compactForLog(query, maxLogTextRunes),
+ utf8.RuneCountInString(query),
+ len(documents),
+ string(previewJSON),
+ )
+}
+
+func compactForLog(text string, maxRunes int) string {
+ normalized := strings.Join(strings.Fields(strings.TrimSpace(text)), " ")
+ if utf8.RuneCountInString(normalized) <= maxRunes {
+ return normalized
+ }
+ return string([]rune(normalized)[:maxRunes]) + "...(truncated)"
+}
diff --git a/internal/models/rerank/remote_api.go b/internal/models/rerank/remote_api.go
index 945b9fc4..d9b77771 100644
--- a/internal/models/rerank/remote_api.go
+++ b/internal/models/rerank/remote_api.go
@@ -82,11 +82,7 @@ func (r *OpenAIReranker) Rerank(ctx context.Context, query string, documents []s
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),
- )
+ logger.Debugf(ctx, "%s", buildRerankRequestDebug(r.modelName, fmt.Sprintf("%s/rerank", r.baseURL), query, documents))
resp, err := r.client.Do(req)
if err != nil {
diff --git a/internal/models/rerank/zhipu_reranker.go b/internal/models/rerank/zhipu_reranker.go
index c9bbd7b4..ad0d801c 100644
--- a/internal/models/rerank/zhipu_reranker.go
+++ b/internal/models/rerank/zhipu_reranker.go
@@ -93,10 +93,7 @@ func (r *ZhipuReranker) Rerank(ctx context.Context, query string, documents []st
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", r.apiKey))
- // Log the curl equivalent for debugging
- logger.Debugf(ctx, "curl -X POST %s -H \"Content-Type: application/json\" -H \"Authorization: Bearer %s\" -d '%s'",
- r.baseURL, r.apiKey, string(jsonData),
- )
+ logger.Debugf(ctx, "%s", buildRerankRequestDebug(r.modelName, r.baseURL, query, documents))
resp, err := r.client.Do(req)
if err != nil {
From 421c83452c538be4d35d8c1fdc9a2dea7f454ab8 Mon Sep 17 00:00:00 2001
From: wizardchen
Date: Thu, 12 Mar 2026 13:17:47 +0800
Subject: [PATCH 14/35] feat: enhance multimodal image processing and session
management
- Updated configuration to support three tasks in the assistant's prompt: rewriting questions, classifying intent for knowledge base retrieval, and analyzing attached images.
- Implemented backend functionality to update image descriptions in user messages, ensuring that image context is preserved across conversation history.
- Modified session handling to return complete session data after updates, improving the accuracy of session information provided to users.
- Enhanced the chat pipeline to include detailed image descriptions and manage image captions effectively, enriching user interactions with visual content.
These improvements significantly enhance the application's multimodal capabilities, providing a more robust and user-friendly experience when handling image-based queries.
---
config/config.yaml | 29 +--
internal/application/repository/message.go | 10 +
internal/application/repository/session.go | 13 +-
.../service/chat_pipline/common.go | 13 ++
.../service/chat_pipline/into_chat_message.go | 17 +-
.../service/chat_pipline/load_history.go | 4 +-
.../service/chat_pipline/rewrite.go | 203 ++++++++++++++++--
internal/application/service/message.go | 5 +
internal/application/service/session.go | 39 ++--
internal/handler/session/handler.go | 10 +-
internal/handler/session/helpers.go | 7 +-
internal/handler/session/qa.go | 19 +-
internal/types/chat_manage.go | 6 +-
internal/types/interfaces/message.go | 5 +
internal/types/interfaces/session.go | 4 +-
15 files changed, 319 insertions(+), 65 deletions(-)
diff --git a/config/config.yaml b/config/config.yaml
index e5c99725..acdaa28a 100644
--- a/config/config.yaml
+++ b/config/config.yaml
@@ -29,9 +29,10 @@ conversation:
enable_query_expansion: true
enable_rerank: true
rewrite_prompt_system: |
- You are an intelligent assistant that performs TWO tasks on the user's question:
+ You are an intelligent assistant that performs THREE tasks on the user's question:
1. Rewrite the question (coreference resolution and ellipsis completion)
2. Classify whether the question requires knowledge base retrieval
+ 3. Analyze attached images (when present)
## Task 1: Rewriting Goals
Based on the conversation history, rewrite the current user question:
@@ -44,30 +45,32 @@ conversation:
## Task 2: Intent Classification
Determine if the question requires knowledge base retrieval.
- - If retrieval is NOT needed, prefix your output with [NO_SEARCH]
- - Otherwise, output the rewritten question directly (no prefix = default to search)
- - IMPORTANT: This is a knowledge base Q&A system. Default to SEARCH. Only add [NO_SEARCH] when you are very confident the question has nothing to do with the knowledge base.
+ - Output a boolean field `skip_kb_search` instead of any prefix marker.
+ - IMPORTANT: This is a knowledge base Q&A system. Default to search (`skip_kb_search=false`).
+ - Set `skip_kb_search=true` only when you are very confident retrieval is unnecessary.
- When to output [NO_SEARCH]:
+ When to set skip_kb_search=true:
- Pure greetings, thanks, or farewell with no question ("谢谢", "你好", "再见")
- Requests to summarize or manipulate the previous conversation itself ("总结一下我们的对话")
- Pure image understanding with NO intent to search documents: describing, summarizing, translating, or extracting content from the image itself ("这张图片是什么", "描述一下图片内容", "帮我翻译图中文字", "图里的表格数据是什么", "帮我识别一下这张图")
- Follow-up questions that clearly refer to previous conversation content (especially previously uploaded images) and can be answered from dialogue context directly ("第一张图再详细描述一下", "第二张门上的字是什么意思", "这个再展开讲讲")
- When NOT to output [NO_SEARCH] (common mistakes to avoid):
+ When NOT to set skip_kb_search=true (common mistakes to avoid):
- User uploads an image and asks to FIND/SEARCH related content in knowledge base → SEARCH (the image content is the search query)
- User asks how to fix/solve/handle something shown in the image ("这个报错怎么解决") → SEARCH (knowledge base may have solutions)
- User asks a question that implies comparing image content against documents → SEARCH
## Task 3: Image Analysis (only when images are attached)
- If the user's message includes images, after the rewritten question, add a separator "---" on a new line, then provide a concise description of the image content. This description is used as a text fallback for models that cannot process images directly.
- If the image contains OCR text, also extract the key text information (OCR) from the image and include it in the description.
+ If the user's message includes images, provide a detailed description in `image_description`, including objects, scene, layout, relationships, and any visible key details.
+ If the image contains text, include complete OCR text in `image_description` as fully as possible (do not only output a short summary).
+ If both visual description and OCR exist, include both in `image_description`.
+ If there are no images or truly no useful visual/text information, set `image_description` to an empty string.
## Output Format
- - Text only (needs search): rewritten question
- - Text only (no search): [NO_SEARCH] rewritten question
- - With images (needs search): rewritten question\n---\nimage description (including extracted OCR if present)
- - With images (no search): [NO_SEARCH] rewritten question\n---\nimage description (including extracted OCR if present)
+ You MUST output ONLY a single JSON object.
+ Do NOT output markdown, code fences, explanations, or any extra text.
+ JSON schema:
+ {"rewrite_query":"string","skip_kb_search":true|false,"image_description":"string"}
rewrite_prompt_user: |
## Conversation History
@@ -76,7 +79,7 @@ conversation:
## User Question to Rewrite
{{query}}
- ## Rewritten Question
+ ## JSON Output
keywords_extraction_prompt: |
# Role
You are a professional keyword extraction assistant. Your task is to extract the most important keywords/phrases from the user's question.
diff --git a/internal/application/repository/message.go b/internal/application/repository/message.go
index 68c5ea83..011d1ca8 100644
--- a/internal/application/repository/message.go
+++ b/internal/application/repository/message.go
@@ -235,6 +235,16 @@ func (r *messageRepository) GetKnowledgeIDsBySessionID(
return knowledgeIDs, nil
}
+// UpdateMessageImages updates only the images JSONB column for a message.
+// Uses Select to force GORM to include the column even when struct-based
+// Updates would otherwise skip custom Valuer types.
+func (r *messageRepository) UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error {
+ return r.db.WithContext(ctx).
+ Model(&types.Message{}).
+ Where("id = ? AND session_id = ?", messageID, sessionID).
+ Update("images", images).Error
+}
+
// UpdateMessageKnowledgeID updates the knowledge_id field for a message
func (r *messageRepository) UpdateMessageKnowledgeID(
ctx context.Context, messageID string, knowledgeID string,
diff --git a/internal/application/repository/session.go b/internal/application/repository/session.go
index 9187fce3..7b30b0e0 100644
--- a/internal/application/repository/session.go
+++ b/internal/application/repository/session.go
@@ -43,7 +43,7 @@ func (r *sessionRepository) Get(ctx context.Context, tenantID uint64, id string)
// GetByTenantID retrieves all sessions for a tenant
func (r *sessionRepository) GetByTenantID(ctx context.Context, tenantID uint64) ([]*types.Session, error) {
var sessions []*types.Session
- err := r.db.WithContext(ctx).Where("tenant_id = ?", tenantID).Order("created_at DESC").Find(&sessions).Error
+ err := r.db.WithContext(ctx).Where("tenant_id = ?", tenantID).Order("updated_at DESC").Find(&sessions).Error
if err != nil {
return nil, err
}
@@ -66,7 +66,7 @@ func (r *sessionRepository) GetPagedByTenantID(
// Then query the paginated data
err = r.db.WithContext(ctx).
Where("tenant_id = ?", tenantID).
- Order("created_at DESC").
+ Order("updated_at DESC").
Offset(page.Offset()).
Limit(page.Limit()).
Find(&sessions).Error
@@ -80,7 +80,14 @@ func (r *sessionRepository) GetPagedByTenantID(
// Update updates a session
func (r *sessionRepository) Update(ctx context.Context, session *types.Session) error {
session.UpdatedAt = time.Now()
- return r.db.WithContext(ctx).Where("tenant_id = ?", session.TenantID).Save(session).Error
+ return r.db.WithContext(ctx).
+ Model(&types.Session{}).
+ Where("tenant_id = ? AND id = ?", session.TenantID, session.ID).
+ Updates(map[string]interface{}{
+ "title": session.Title,
+ "description": session.Description,
+ "updated_at": session.UpdatedAt,
+ }).Error
}
// Delete deletes a session
diff --git a/internal/application/service/chat_pipline/common.go b/internal/application/service/chat_pipline/common.go
index 53b74f5a..26ace7ca 100644
--- a/internal/application/service/chat_pipline/common.go
+++ b/internal/application/service/chat_pipline/common.go
@@ -78,6 +78,19 @@ func prepareMessagesWithHistory(chatManage *types.ChatManage) []chat.Message {
return chatMessages
}
+// extractImageCaptions concatenates non-empty Caption fields from stored
+// message images. Used when loading history so that previous turns' image
+// descriptions are visible to the model.
+func extractImageCaptions(images types.MessageImages) string {
+ var parts []string
+ for _, img := range images {
+ if img.Caption != "" {
+ parts = append(parts, img.Caption)
+ }
+ }
+ return strings.Join(parts, "\n")
+}
+
// renderSystemPromptPlaceholders replaces placeholders in system prompt
// Supported placeholders:
// - {{current_time}} -> current time in RFC3339 format
diff --git a/internal/application/service/chat_pipline/into_chat_message.go b/internal/application/service/chat_pipline/into_chat_message.go
index a81275f6..7ac951ca 100644
--- a/internal/application/service/chat_pipline/into_chat_message.go
+++ b/internal/application/service/chat_pipline/into_chat_message.go
@@ -90,8 +90,8 @@ func (p *PluginIntoChatMessage) OnEvent(ctx context.Context,
})
}
}
- if chatManage.ImageOCRText != "" && !chatManage.ChatModelSupportsVision {
- userContent += "\n\n[用户上传图片内容]\n" + chatManage.ImageOCRText
+ if chatManage.ImageDescription != "" && !chatManage.ChatModelSupportsVision {
+ userContent += "\n\n[用户上传图片内容]\n" + chatManage.ImageDescription
}
chatManage.UserContent = userContent
pipelineInfo(ctx, "IntoChatMessage", "skip_template_no_search", map[string]interface{}{
@@ -148,16 +148,19 @@ func (p *PluginIntoChatMessage) OnEvent(ctx context.Context,
// Append image description as text fallback only when the chat model cannot
// process images directly. Vision-capable models see images via MultiContent.
- if chatManage.ImageOCRText != "" && !chatManage.ChatModelSupportsVision {
- userContent += "\n\n[用户上传图片内容]\n" + chatManage.ImageOCRText
+ if chatManage.ImageDescription != "" && !chatManage.ChatModelSupportsVision {
+ userContent += "\n\n[用户上传图片内容]\n" + chatManage.ImageDescription
}
// Set formatted content back to chat management
chatManage.UserContent = userContent
pipelineInfo(ctx, "IntoChatMessage", "output", map[string]interface{}{
- "session_id": chatManage.SessionID,
- "user_content_len": len(chatManage.UserContent),
- "faq_priority": chatManage.FAQPriorityEnabled,
+ "session_id": chatManage.SessionID,
+ "user_content_len": len(chatManage.UserContent),
+ "faq_priority": chatManage.FAQPriorityEnabled,
+ "skip_kb_search": chatManage.SkipKBSearch,
+ "image_description": chatManage.ImageDescription,
+ "chat_model_supports_vision": chatManage.ChatModelSupportsVision,
})
return next()
}
diff --git a/internal/application/service/chat_pipline/load_history.go b/internal/application/service/chat_pipline/load_history.go
index 4c3563c2..44b0045f 100644
--- a/internal/application/service/chat_pipline/load_history.go
+++ b/internal/application/service/chat_pipline/load_history.go
@@ -83,9 +83,11 @@ func (p *PluginLoadHistory) OnEvent(ctx context.Context,
h = &types.History{}
}
if message.Role == "user" {
- // User message as query
h.Query = message.Content
h.CreateAt = message.CreatedAt
+ if desc := extractImageCaptions(message.Images); desc != "" {
+ h.Query += "\n\n[用户上传图片内容]\n" + desc
+ }
} else {
// System message as answer, while removing thinking process
h.Answer = regThink.ReplaceAllString(message.Content, "")
diff --git a/internal/application/service/chat_pipline/rewrite.go b/internal/application/service/chat_pipline/rewrite.go
index 1a0ba737..705536c0 100644
--- a/internal/application/service/chat_pipline/rewrite.go
+++ b/internal/application/service/chat_pipline/rewrite.go
@@ -4,6 +4,7 @@ package chatpipline
import (
"context"
+ "encoding/json"
"regexp"
"slices"
"sort"
@@ -34,6 +35,12 @@ const (
noSearchPrefix = "[NO_SEARCH]"
)
+type rewriteOutput struct {
+ RewriteQuery string
+ SkipKBSearch bool
+ ImageDescription string
+}
+
// NewPluginRewrite creates a new query rewriting plugin instance
// Also registers the plugin with the event manager
func NewPluginRewrite(eventManager *EventManager,
@@ -183,16 +190,53 @@ func (p *PluginRewrite) OnEvent(ctx context.Context,
// --- Parse structured output ---
p.parseRewriteOutput(chatManage, response.Content)
+
+ // Persist image description back to the user message so that future turns
+ // can see it when loading conversation history.
+ if chatManage.ImageDescription != "" && chatManage.UserMessageID != "" {
+ p.updateUserMessageImageCaption(ctx, chatManage)
+ }
+
pipelineInfo(ctx, "Rewrite", "output", map[string]interface{}{
"session_id": chatManage.SessionID,
"rewrite_query": chatManage.RewriteQuery,
"skip_kb_search": chatManage.SkipKBSearch,
- "has_image_desc": chatManage.ImageOCRText != "",
+ "has_image_desc": chatManage.ImageDescription != "",
"original_output": response.Content,
})
return next()
}
+// updateUserMessageImageCaption writes the generated ImageDescription back to
+// the stored user message's Images so that subsequent turns can see it in history.
+func (p *PluginRewrite) updateUserMessageImageCaption(ctx context.Context, chatManage *types.ChatManage) {
+ msg, err := p.messageService.GetMessage(ctx, chatManage.SessionID, chatManage.UserMessageID)
+ if err != nil {
+ pipelineWarn(ctx, "Rewrite", "get_user_message", map[string]interface{}{
+ "session_id": chatManage.SessionID,
+ "user_message_id": chatManage.UserMessageID,
+ "error": err.Error(),
+ })
+ return
+ }
+
+ if len(msg.Images) == 0 {
+ return
+ }
+
+ msg.Images[0].Caption = chatManage.ImageDescription
+
+ // Use the targeted UpdateMessageImages to reliably persist the JSONB column.
+ // GORM's struct-based Updates may silently skip custom Valuer types.
+ if err := p.messageService.UpdateMessageImages(ctx, chatManage.SessionID, chatManage.UserMessageID, msg.Images); err != nil {
+ pipelineWarn(ctx, "Rewrite", "update_image_caption", map[string]interface{}{
+ "session_id": chatManage.SessionID,
+ "user_message_id": chatManage.UserMessageID,
+ "error": err.Error(),
+ })
+ }
+}
+
// loadHistory fetches and processes conversation history for rewrite context.
func (p *PluginRewrite) loadHistory(ctx context.Context, chatManage *types.ChatManage) []*types.History {
history, err := p.messageService.GetRecentMessagesBySession(ctx, chatManage.SessionID, 20)
@@ -212,6 +256,9 @@ func (p *PluginRewrite) loadHistory(ctx context.Context, chatManage *types.ChatM
if message.Role == "user" {
h.Query = message.Content
h.CreateAt = message.CreatedAt
+ if desc := extractImageCaptions(message.Images); desc != "" {
+ h.Query += "\n\n[用户上传图片内容]\n" + desc
+ }
} else {
h.Answer = reg.ReplaceAllString(message.Content, "")
h.KnowledgeReferences = message.KnowledgeReferences
@@ -307,11 +354,14 @@ func (p *PluginRewrite) buildPrompts(chatManage *types.ChatManage, historyList [
}
// Strengthen context inheritance in multi-turn conversation:
// for follow-up questions that clearly refer to previous turns (especially
- // uploaded-image understanding), prefer NO_SEARCH over KB retrieval.
+ // uploaded-image understanding), prefer skipping KB retrieval.
systemPrompt += "\n\n## Additional Context Inheritance Guidance\n" +
- "- If the current question is a follow-up to previous conversation content (especially previously uploaded images) and can be answered by that context, you MUST classify it as NO_SEARCH.\n" +
+ "- If the current question is a follow-up to previous conversation content (especially previously uploaded images) and can be answered by that context, you MUST set skip_kb_search=true.\n" +
"- Examples: “第一张图再详细描述一下”, “第二张门上的字是什么意思”, “这个再展开讲讲”.\n" +
- "- In these follow-up cases, output with [NO_SEARCH] prefix."
+ "- You MUST output ONLY a single JSON object (no markdown/code fences, no extra text) with schema: {\"rewrite_query\":\"...\",\"skip_kb_search\":true|false,\"image_description\":\"...\"}.\n" +
+ "- `skip_kb_search` field is REQUIRED and must be explicit true/false.\n" +
+ "- For images, `image_description` MUST include a detailed visual description and complete OCR text. Keep all key details; do not overly summarize.\n" +
+ "- image_description should be empty string only when there are no images or truly no readable visual text/details."
conversationText := formatConversationHistory(historyList)
currentTime := time.Now().Format("2006-01-02 15:04:05")
@@ -333,27 +383,34 @@ func (p *PluginRewrite) buildPrompts(chatManage *types.ChatManage, historyList [
//
// Expected formats:
//
-// Text only: "[NO_SEARCH] rewritten question" or "rewritten question"
-// With images: "[NO_SEARCH]\nrewritten question\n---\nimage description"
+// Preferred: {"rewrite_query":"...","skip_kb_search":false,"image_description":"..."}
+// Legacy fallback:
+// - Text only: "[NO_SEARCH] rewritten question" or "rewritten question"
+// - With images: "[NO_SEARCH]\nrewritten question\n---\nimage description"
func (p *PluginRewrite) parseRewriteOutput(chatManage *types.ChatManage, raw string) {
content := strings.TrimSpace(raw)
if content == "" {
return
}
- // 1. Parse intent marker
+ if output, ok := parseStructuredRewriteOutput(content); ok {
+ if rewrite := strings.TrimSpace(output.RewriteQuery); rewrite != "" {
+ chatManage.RewriteQuery = rewrite
+ }
+ chatManage.SkipKBSearch = output.SkipKBSearch
+ chatManage.ImageDescription = strings.TrimSpace(output.ImageDescription)
+ return
+ }
+
+ // Legacy fallback parsing for older prompts/models.
if strings.HasPrefix(content, noSearchPrefix) {
chatManage.SkipKBSearch = true
content = strings.TrimSpace(strings.TrimPrefix(content, noSearchPrefix))
}
- // 2. Split rewritten query and image description.
- // Be tolerant to model output variants like:
- // - "query\n---\nimage_desc" (expected)
- // - "query---\nimage_desc" (missing leading newline before separator)
if m := rewriteImageSepPattern.FindStringSubmatch(content); len(m) == 3 {
chatManage.RewriteQuery = strings.TrimSpace(m[1])
- chatManage.ImageOCRText = strings.TrimSpace(m[2])
+ chatManage.ImageDescription = strings.TrimSpace(m[2])
return
}
if content != "" {
@@ -361,6 +418,128 @@ func (p *PluginRewrite) parseRewriteOutput(chatManage *types.ChatManage, raw str
}
}
+func parseStructuredRewriteOutput(raw string) (rewriteOutput, bool) {
+ content := strings.TrimSpace(raw)
+ if content == "" {
+ return rewriteOutput{}, false
+ }
+
+ var out rewriteOutput
+ if parsed, ok := parseStructuredRewriteOutputJSON(content); ok {
+ return parsed, true
+ }
+
+ // Be tolerant to occasional markdown wrappers or extra prose.
+ start := strings.Index(content, "{")
+ end := strings.LastIndex(content, "}")
+ if start < 0 || end <= start {
+ return rewriteOutput{}, false
+ }
+ candidate := content[start : end+1]
+ if parsed, ok := parseStructuredRewriteOutputJSON(candidate); ok {
+ return parsed, true
+ }
+ return out, false
+}
+
+func parseStructuredRewriteOutputJSON(content string) (rewriteOutput, bool) {
+ var obj map[string]json.RawMessage
+ if err := json.Unmarshal([]byte(content), &obj); err != nil {
+ return rewriteOutput{}, false
+ }
+
+ out := rewriteOutput{
+ RewriteQuery: strings.TrimSpace(firstStringField(obj,
+ "rewrite_query", "rewritten_query", "query", "question")),
+ }
+
+ // Support common variants and semantic inversion for need_search.
+ if v, ok := firstBoolField(obj, "skip_kb_search", "skip_search", "no_search"); ok {
+ out.SkipKBSearch = v
+ } else if v, ok := firstBoolField(obj, "need_search", "requires_search"); ok {
+ out.SkipKBSearch = !v
+ }
+
+ desc := strings.TrimSpace(firstStringField(obj,
+ "image_description", "image_desc", "image_text", "image_ocr_text", "description"))
+ ocr := strings.TrimSpace(firstStringField(obj,
+ "ocr_text", "ocr", "full_ocr", "image_ocr", "ocr_content"))
+ combined, set := mergeImageDescAndOCR(desc, ocr)
+ if set {
+ out.ImageDescription = combined
+ }
+
+ return out, true
+}
+
+func firstStringField(obj map[string]json.RawMessage, keys ...string) string {
+ for _, key := range keys {
+ raw, ok := obj[key]
+ if !ok || len(raw) == 0 {
+ continue
+ }
+
+ var s string
+ if err := json.Unmarshal(raw, &s); err == nil {
+ return s
+ }
+ }
+ return ""
+}
+
+func firstBoolField(obj map[string]json.RawMessage, keys ...string) (bool, bool) {
+ for _, key := range keys {
+ raw, ok := obj[key]
+ if !ok || len(raw) == 0 {
+ continue
+ }
+ if v, ok := parseBoolJSON(raw); ok {
+ return v, true
+ }
+ }
+ return false, false
+}
+
+func parseBoolJSON(raw json.RawMessage) (bool, bool) {
+ var b bool
+ if err := json.Unmarshal(raw, &b); err == nil {
+ return b, true
+ }
+
+ var s string
+ if err := json.Unmarshal(raw, &s); err == nil {
+ switch strings.ToLower(strings.TrimSpace(s)) {
+ case "true", "1", "yes", "y":
+ return true, true
+ case "false", "0", "no", "n":
+ return false, true
+ }
+ }
+
+ var n float64
+ if err := json.Unmarshal(raw, &n); err == nil {
+ return n != 0, true
+ }
+
+ return false, false
+}
+
+func mergeImageDescAndOCR(desc, ocr string) (string, bool) {
+ if desc == "" && ocr == "" {
+ return "", false
+ }
+ if desc == "" {
+ return ocr, true
+ }
+ if ocr == "" {
+ return desc, true
+ }
+ if strings.Contains(desc, ocr) {
+ return desc, true
+ }
+ return desc + "\n\n[OCR]\n" + ocr, true
+}
+
// formatConversationHistory formats conversation history for prompt template
func formatConversationHistory(historyList []*types.History) string {
if len(historyList) == 0 {
diff --git a/internal/application/service/message.go b/internal/application/service/message.go
index 938f61ed..5199a9f7 100644
--- a/internal/application/service/message.go
+++ b/internal/application/service/message.go
@@ -237,6 +237,11 @@ func (s *messageService) UpdateMessage(ctx context.Context, message *types.Messa
return nil
}
+// UpdateMessageImages updates only the images JSONB column for a message.
+func (s *messageService) UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error {
+ return s.messageRepo.UpdateMessageImages(ctx, sessionID, messageID, images)
+}
+
// DeleteMessage removes a message from a session, also cleaning up its Knowledge entry in the chat history KB.
func (s *messageService) DeleteMessage(ctx context.Context, sessionID string, messageID string) error {
logger.Info(ctx, "Start deleting message")
diff --git a/internal/application/service/session.go b/internal/application/service/session.go
index 29b39f6b..ee953fbf 100644
--- a/internal/application/service/session.go
+++ b/internal/application/service/session.go
@@ -523,7 +523,7 @@ func (s *sessionService) KnowledgeQA(
eventBus *event.EventBus,
customAgent *types.CustomAgent,
enableMemory bool,
- imageURLs []string, imageOCRText string,
+ imageURLs []string, imageDescription string, userMessageID string,
) error {
logger.Infof(
ctx,
@@ -768,8 +768,9 @@ func (s *sessionService) KnowledgeQA(
FAQDirectAnswerThreshold: faqDirectAnswerThreshold,
FAQScoreBoost: faqScoreBoost,
// Image support
+ UserMessageID: userMessageID,
Images: imageURLs,
- ImageOCRText: imageOCRText,
+ ImageDescription: imageDescription,
VLMModelID: vlmModelID,
ChatModelSupportsVision: chatModelSupportsVision,
}
@@ -783,8 +784,8 @@ func (s *sessionService) KnowledgeQA(
// For pure chat, UserContent is the Query (since INTO_CHAT_MESSAGE is skipped)
// Only append image text description for non-vision models; vision models see images directly
userContent := query
- if imageOCRText != "" && !chatModelSupportsVision {
- userContent += "\n\n[用户上传图片内容]\n" + imageOCRText
+ if imageDescription != "" && !chatModelSupportsVision {
+ userContent += "\n\n[用户上传图片内容]\n" + imageDescription
}
chatManage.UserContent = userContent
@@ -1391,8 +1392,9 @@ func (s *sessionService) AgentQA(
customAgent *types.CustomAgent,
knowledgeBaseIDs []string,
knowledgeIDs []string,
- imageURLs []string, imageOCRText string,
+ imageURLs []string, imageDescription string, userMessageID string,
) error {
+ _ = userMessageID // reserved for future use (AgentQA pipeline differs from KnowledgeQA)
sessionID := session.ID
sessionJSON, err := json.Marshal(session)
if err != nil {
@@ -1624,9 +1626,9 @@ func (s *sessionService) AgentQA(
if agentModelSupportsVision && len(imageURLs) > 0 {
agentImageURLs = imageURLs
logger.Infof(ctx, "Agent model supports vision, passing %d image(s) directly", len(agentImageURLs))
- } else if imageOCRText != "" {
- agentQuery = query + "\n\n[用户上传图片内容]\n" + imageOCRText
- logger.Infof(ctx, "Agent model does not support vision, appending image OCR text (%d chars)", len(imageOCRText))
+ } else if imageDescription != "" {
+ agentQuery = query + "\n\n[用户上传图片内容]\n" + imageDescription
+ logger.Infof(ctx, "Agent model does not support vision, appending image description (%d chars)", len(imageDescription))
}
// Execute agent with streaming (asynchronously)
@@ -1762,9 +1764,11 @@ func (s *sessionService) handleModelFallback(ctx context.Context, chatManage *ty
}
// Start streaming response
- responseChan, err := chatModel.ChatStream(ctx, []chat.Message{
- {Role: "user", Content: promptContent},
- }, opt)
+ userMsg := chat.Message{Role: "user", Content: promptContent}
+ if chatManage.ChatModelSupportsVision && len(chatManage.Images) > 0 {
+ userMsg.Images = chatManage.Images
+ }
+ responseChan, err := chatModel.ChatStream(ctx, []chat.Message{userMsg}, opt)
if err != nil {
logger.Errorf(ctx, "Failed to start streaming fallback response: %v, falling back to fixed response", err)
s.handleFixedFallback(ctx, chatManage)
@@ -1781,10 +1785,17 @@ func (s *sessionService) handleModelFallback(ctx context.Context, chatManage *ty
go s.consumeFallbackStream(ctx, chatManage, responseChan)
}
-// renderFallbackPrompt renders the fallback prompt template with Query variable
+// renderFallbackPrompt renders the fallback prompt template with query and image context.
func (s *sessionService) renderFallbackPrompt(ctx context.Context, chatManage *types.ChatManage) (string, error) {
- // Use simple string replacement instead of Go template
- result := strings.ReplaceAll(chatManage.FallbackPrompt, "{{query}}", chatManage.Query)
+ query := chatManage.Query
+ if rq := strings.TrimSpace(chatManage.RewriteQuery); rq != "" {
+ query = rq
+ }
+ result := strings.ReplaceAll(chatManage.FallbackPrompt, "{{query}}", query)
+
+ if chatManage.ImageDescription != "" && !chatManage.ChatModelSupportsVision {
+ result += "\n\n[用户上传图片内容]\n" + chatManage.ImageDescription
+ }
return result, nil
}
diff --git a/internal/handler/session/handler.go b/internal/handler/session/handler.go
index e73da62f..02dbee6e 100644
--- a/internal/handler/session/handler.go
+++ b/internal/handler/session/handler.go
@@ -260,11 +260,19 @@ func (h *Handler) UpdateSession(c *gin.Context) {
return
}
+ // Reload session from database to return complete timestamps and stored fields
+ updatedSession, err := h.sessionService.GetSession(ctx, id)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, nil)
+ c.Error(errors.NewInternalServerError(err.Error()))
+ return
+ }
+
// Return updated session
logger.Infof(ctx, "Session updated successfully, ID: %s", id)
c.JSON(http.StatusOK, gin.H{
"success": true,
- "data": session,
+ "data": updatedSession,
})
}
diff --git a/internal/handler/session/helpers.go b/internal/handler/session/helpers.go
index 7a545a91..783e57a1 100644
--- a/internal/handler/session/helpers.go
+++ b/internal/handler/session/helpers.go
@@ -164,9 +164,9 @@ func createAgentQueryEvent(sessionID, assistantMessageID string) interfaces.Stre
}
}
-// createUserMessage creates a user message
-func (h *Handler) createUserMessage(ctx context.Context, sessionID, query, requestID string, mentionedItems types.MentionedItems, images types.MessageImages) error {
- _, err := h.messageService.CreateMessage(ctx, &types.Message{
+// createUserMessage creates a user message and returns the created message.
+func (h *Handler) createUserMessage(ctx context.Context, sessionID, query, requestID string, mentionedItems types.MentionedItems, images types.MessageImages) (*types.Message, error) {
+ return h.messageService.CreateMessage(ctx, &types.Message{
SessionID: sessionID,
Role: "user",
Content: query,
@@ -176,7 +176,6 @@ func (h *Handler) createUserMessage(ctx context.Context, sessionID, query, reque
MentionedItems: mentionedItems,
Images: images,
})
- return err
}
// createAssistantMessage creates an assistant message
diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.go
index ad566399..457a4ced 100644
--- a/internal/handler/session/qa.go
+++ b/internal/handler/session/qa.go
@@ -35,6 +35,7 @@ type qaRequestContext struct {
mentionedItems types.MentionedItems
effectiveTenantID uint64 // when using shared agent, tenant ID for model/KB/MCP resolution; 0 = use context tenant
images []ImageAttachment // Uploaded images with analysis text
+ userMessageID string // Created user message ID (populated after createUserMessage)
}
// parseQARequest parses and validates a QA request, returns the request context
@@ -403,10 +404,12 @@ func (h *Handler) executeNormalModeQA(reqCtx *qaRequestContext, generateTitle bo
sessionID := reqCtx.sessionID
// Create user message
- if err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images)); err != nil {
+ userMsg, err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images))
+ if err != nil {
reqCtx.c.Error(errors.NewInternalServerError(err.Error()))
return
}
+ reqCtx.userMessageID = userMsg.ID
// Create assistant message
if _, err := h.createAssistantMessage(ctx, reqCtx.assistantMessage); err != nil {
@@ -515,7 +518,7 @@ func (h *Handler) executeNormalModeQA(reqCtx *qaRequestContext, generateTitle bo
})
}
- imageURLs, imageOCRText := extractImageURLsAndOCRText(reqCtx.images)
+ imageURLs, imageDescription := extractImageURLsAndOCRText(reqCtx.images)
err := h.sessionService.KnowledgeQA(
streamCtx.asyncCtx,
reqCtx.session,
@@ -528,7 +531,8 @@ func (h *Handler) executeNormalModeQA(reqCtx *qaRequestContext, generateTitle bo
streamCtx.eventBus,
reqCtx.customAgent,
reqCtx.enableMemory,
- imageURLs, imageOCRText,
+ imageURLs, imageDescription,
+ reqCtx.userMessageID,
)
if err != nil {
logger.ErrorWithFields(streamCtx.asyncCtx, err, nil)
@@ -571,10 +575,12 @@ func (h *Handler) executeAgentModeQA(reqCtx *qaRequestContext) {
}
// Create user message
- if err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images)); err != nil {
+ userMsg, err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images))
+ if err != nil {
reqCtx.c.Error(errors.NewInternalServerError(err.Error()))
return
}
+ reqCtx.userMessageID = userMsg.ID
// Create assistant message
assistantMessagePtr, err := h.createAssistantMessage(ctx, reqCtx.assistantMessage)
@@ -635,7 +641,7 @@ func (h *Handler) executeAgentModeQA(reqCtx *qaRequestContext) {
})
}
- imageURLs, imageOCRText := extractImageURLsAndOCRText(reqCtx.images)
+ imageURLs, imageDescription := extractImageURLsAndOCRText(reqCtx.images)
err := h.sessionService.AgentQA(
streamCtx.asyncCtx,
reqCtx.session,
@@ -646,7 +652,8 @@ func (h *Handler) executeAgentModeQA(reqCtx *qaRequestContext) {
reqCtx.customAgent,
reqCtx.knowledgeBaseIDs,
reqCtx.knowledgeIDs,
- imageURLs, imageOCRText,
+ imageURLs, imageDescription,
+ reqCtx.userMessageID,
)
if err != nil {
logger.ErrorWithFields(streamCtx.asyncCtx, err, nil)
diff --git a/internal/types/chat_manage.go b/internal/types/chat_manage.go
index 8616e7d6..13827b4d 100644
--- a/internal/types/chat_manage.go
+++ b/internal/types/chat_manage.go
@@ -62,8 +62,9 @@ type ChatManage struct {
FAQScoreBoost float64 `json:"-"` // Score multiplier for FAQ results
// Image support for multimodal chat
+ UserMessageID string `json:"-"` // User message ID for updating image captions after rewrite
Images []string `json:"-"` // Image URLs for MultiContent in current user message
- ImageOCRText string `json:"-"` // Image description/OCR text generated by VLM (used as fallback for non-vision models)
+ ImageDescription string `json:"-"` // Image description (visual details + OCR text) generated by VLM (used as fallback for non-vision models)
VLMModelID string `json:"-"` // Agent-configured VLM model ID for image analysis
ChatModelSupportsVision bool `json:"-"` // Whether the chat model accepts multimodal/image input
SkipKBSearch bool `json:"-"` // Set by rewrite intent classification: true = skip KB retrieval
@@ -136,8 +137,9 @@ func (c *ChatManage) Clone() *ChatManage {
FAQPriorityEnabled: c.FAQPriorityEnabled,
FAQDirectAnswerThreshold: c.FAQDirectAnswerThreshold,
FAQScoreBoost: c.FAQScoreBoost,
+ UserMessageID: c.UserMessageID,
Images: append([]string(nil), c.Images...),
- ImageOCRText: c.ImageOCRText,
+ ImageDescription: c.ImageDescription,
VLMModelID: c.VLMModelID,
ChatModelSupportsVision: c.ChatModelSupportsVision,
SkipKBSearch: c.SkipKBSearch,
diff --git a/internal/types/interfaces/message.go b/internal/types/interfaces/message.go
index 61bc6652..1be5777b 100644
--- a/internal/types/interfaces/message.go
+++ b/internal/types/interfaces/message.go
@@ -29,6 +29,9 @@ type MessageService interface {
// UpdateMessage updates a message
UpdateMessage(ctx context.Context, message *types.Message) error
+ // UpdateMessageImages updates only the images JSONB column for a message.
+ UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error
+
// DeleteMessage deletes a message
DeleteMessage(ctx context.Context, sessionID string, id string) error
@@ -66,6 +69,8 @@ type MessageRepository interface {
) ([]*types.Message, error)
// UpdateMessage updates a message
UpdateMessage(ctx context.Context, message *types.Message) error
+ // UpdateMessageImages updates only the images JSONB column for a message
+ UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error
// DeleteMessage deletes a message
DeleteMessage(ctx context.Context, sessionID string, id string) error
// GetFirstMessageOfUser gets the first message of a user
diff --git a/internal/types/interfaces/session.go b/internal/types/interfaces/session.go
index 1d8a0fa9..776b93b6 100644
--- a/internal/types/interfaces/session.go
+++ b/internal/types/interfaces/session.go
@@ -44,7 +44,7 @@ type SessionService interface {
session *types.Session, query string, knowledgeBaseIDs []string, knowledgeIDs []string,
assistantMessageID string, summaryModelID string, webSearchEnabled bool, eventBus *event.EventBus,
customAgent *types.CustomAgent, enableMemory bool,
- imageURLs []string, imageOCRText string,
+ imageURLs []string, imageDescription string, userMessageID string,
) error
// KnowledgeQAByEvent performs knowledge-based question answering by event
KnowledgeQAByEvent(ctx context.Context, chatManage *types.ChatManage, eventList []types.EventType) error
@@ -66,7 +66,7 @@ type SessionService interface {
customAgent *types.CustomAgent,
knowledgeBaseIDs []string,
knowledgeIDs []string,
- imageURLs []string, imageOCRText string,
+ imageURLs []string, imageDescription string, userMessageID string,
) error
// ClearContext clears the LLM context for a session
ClearContext(ctx context.Context, sessionID string) error
From a6f77cec1450dcd3ca7a2d0391263fbf3da21d3d Mon Sep 17 00:00:00 2001
From: wizardchen
Date: Thu, 12 Mar 2026 14:47:56 +0800
Subject: [PATCH 15/35] feat: enhance knowledge update functionality
- Added support for updating the description field in knowledge records, improving the detail and context of knowledge entries.
- Refactored knowledge base update logic to ensure configuration updates are only applied when provided, enhancing robustness and preventing unnecessary overwrites.
- Modified the request structure to make the configuration field optional, allowing for more flexible updates.
These changes improve the knowledge management system by allowing for more comprehensive updates and better handling of configuration data.
---
internal/application/service/knowledge.go | 3 +++
internal/application/service/knowledgebase.go | 11 ++++++-----
internal/handler/knowledgebase.go | 2 +-
3 files changed, 10 insertions(+), 6 deletions(-)
diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.go
index f4667fa6..6233baff 100644
--- a/internal/application/service/knowledge.go
+++ b/internal/application/service/knowledge.go
@@ -2434,6 +2434,9 @@ func (s *knowledgeService) UpdateKnowledge(ctx context.Context, knowledge *types
if knowledge.Title != "" {
record.Title = knowledge.Title
}
+ if knowledge.Description != "" {
+ record.Description = knowledge.Description
+ }
// Update knowledge record in the repository
if err := s.repo.UpdateKnowledge(ctx, record); err != nil {
diff --git a/internal/application/service/knowledgebase.go b/internal/application/service/knowledgebase.go
index 310f2b11..afc0759e 100644
--- a/internal/application/service/knowledgebase.go
+++ b/internal/application/service/knowledgebase.go
@@ -291,11 +291,12 @@ func (s *knowledgeBaseService) UpdateKnowledgeBase(ctx context.Context,
// Update the knowledge base properties
kb.Name = name
kb.Description = description
- kb.ChunkingConfig = config.ChunkingConfig
- kb.ImageProcessingConfig = config.ImageProcessingConfig
- // Update FAQ config if provided
- if config.FAQConfig != nil {
- kb.FAQConfig = config.FAQConfig
+ if config != nil {
+ kb.ChunkingConfig = config.ChunkingConfig
+ kb.ImageProcessingConfig = config.ImageProcessingConfig
+ if config.FAQConfig != nil {
+ kb.FAQConfig = config.FAQConfig
+ }
}
kb.UpdatedAt = time.Now()
kb.EnsureDefaults()
diff --git a/internal/handler/knowledgebase.go b/internal/handler/knowledgebase.go
index c06d88b1..8ae600b3 100644
--- a/internal/handler/knowledgebase.go
+++ b/internal/handler/knowledgebase.go
@@ -427,7 +427,7 @@ func (h *KnowledgeBaseHandler) TogglePinKnowledgeBase(c *gin.Context) {
type UpdateKnowledgeBaseRequest struct {
Name string `json:"name" binding:"required"`
Description string `json:"description"`
- Config *types.KnowledgeBaseConfig `json:"config" binding:"required"`
+ Config *types.KnowledgeBaseConfig `json:"config"`
}
// UpdateKnowledgeBase godoc
From 149e71f765595abd01cd4b99152a9d7b30aba43d Mon Sep 17 00:00:00 2001
From: wizardchen
Date: Thu, 12 Mar 2026 15:08:49 +0800
Subject: [PATCH 16/35] feat: enhance agent and user information structures
- Added support for image attachments in agent Q&A requests, enabling multimodal chat capabilities.
- Introduced a new UserInfo struct to represent user information in API responses, improving user data management.
- Updated existing request structures to include image handling, enhancing the overall functionality of the chat system.
These changes significantly improve the application's ability to handle multimodal interactions and manage user data effectively.
---
client/agent.go | 21 +++++++++++----------
client/organization.go | 13 +++++++++++++
client/session.go | 26 ++++++++++++++++++--------
3 files changed, 42 insertions(+), 18 deletions(-)
diff --git a/client/agent.go b/client/agent.go
index f669f4f5..f3773ac2 100644
--- a/client/agent.go
+++ b/client/agent.go
@@ -22,16 +22,17 @@ type MentionedItem struct {
// AgentQARequest agent Q&A request payload.
type AgentQARequest struct {
- Query string `json:"query"` // Required query text
- KnowledgeBaseIDs []string `json:"knowledge_base_ids,omitempty"` // Optional KBs for this query
- KnowledgeIDs []string `json:"knowledge_ids,omitempty"` // Optional specific knowledge IDs for this query
- AgentEnabled bool `json:"agent_enabled"` // Whether to run in agent mode
- AgentID string `json:"agent_id,omitempty"` // Optional custom agent ID
- WebSearchEnabled bool `json:"web_search_enabled"` // Whether to enable web search
- SummaryModelID string `json:"summary_model_id,omitempty"` // Optional summary model override
- MentionedItems []MentionedItem `json:"mentioned_items,omitempty"` // @mentioned knowledge bases and files
- DisableTitle bool `json:"disable_title,omitempty"` // Whether to disable auto title generation
- MCPServiceIDs []string `json:"mcp_service_ids,omitempty"` // Optional MCP service allow list (deprecated)
+ Query string `json:"query"` // Required query text
+ KnowledgeBaseIDs []string `json:"knowledge_base_ids,omitempty"` // Optional KBs for this query
+ KnowledgeIDs []string `json:"knowledge_ids,omitempty"` // Optional specific knowledge IDs for this query
+ AgentEnabled bool `json:"agent_enabled"` // Whether to run in agent mode
+ AgentID string `json:"agent_id,omitempty"` // Optional custom agent ID
+ WebSearchEnabled bool `json:"web_search_enabled"` // Whether to enable web search
+ SummaryModelID string `json:"summary_model_id,omitempty"` // Optional summary model override
+ MentionedItems []MentionedItem `json:"mentioned_items,omitempty"` // @mentioned knowledge bases and files
+ DisableTitle bool `json:"disable_title,omitempty"` // Whether to disable auto title generation
+ MCPServiceIDs []string `json:"mcp_service_ids,omitempty"` // Optional MCP service allow list (deprecated)
+ Images []ImageAttachment `json:"images,omitempty"` // Attached images for multimodal chat
}
// AgentResponseType defines the type of agent response
diff --git a/client/organization.go b/client/organization.go
index aec50405..f0c21626 100644
--- a/client/organization.go
+++ b/client/organization.go
@@ -126,6 +126,19 @@ type JoinRequestResponse struct {
ReviewedAt *time.Time `json:"reviewed_at,omitempty"`
}
+// 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"`
+}
+
// SharedKnowledgeBaseInfo represents a shared knowledge base
type SharedKnowledgeBaseInfo struct {
ShareID string `json:"share_id"`
diff --git a/client/session.go b/client/session.go
index 9ea3621b..831fc4c6 100644
--- a/client/session.go
+++ b/client/session.go
@@ -198,16 +198,26 @@ func (c *Client) GenerateTitle(ctx context.Context, sessionID string, request *G
return response.Data, nil
}
+// ImageAttachment represents an image in a chat request.
+// Frontend sends base64 data in the Data field; the backend saves, runs VLM analysis,
+// and populates URL/Caption before proceeding with the chat pipeline.
+type ImageAttachment struct {
+ Data string `json:"data,omitempty"` // base64 data URI (data:image/png;base64,...)
+ URL string `json:"url,omitempty"` // serving URL after saving to storage
+ Caption string `json:"caption,omitempty"` // VLM analysis result
+}
+
// KnowledgeQARequest knowledge Q&A request
type KnowledgeQARequest struct {
- Query string `json:"query"` // Query text for knowledge base search
- KnowledgeBaseIDs []string `json:"knowledge_base_ids"` // Selected knowledge base IDs for this request
- KnowledgeIDs []string `json:"knowledge_ids"` // Selected knowledge IDs for this request
- AgentEnabled bool `json:"agent_enabled"` // Whether agent mode is enabled for this request
- AgentID string `json:"agent_id"` // Selected custom agent ID for this request
- WebSearchEnabled bool `json:"web_search_enabled"` // Whether web search is enabled for this request
- SummaryModelID string `json:"summary_model_id"` // Optional summary model ID (overrides session default)
- DisableTitle bool `json:"disable_title"` // Whether to disable auto title generation
+ Query string `json:"query"` // Query text for knowledge base search
+ KnowledgeBaseIDs []string `json:"knowledge_base_ids"` // Selected knowledge base IDs for this request
+ KnowledgeIDs []string `json:"knowledge_ids"` // Selected knowledge IDs for this request
+ AgentEnabled bool `json:"agent_enabled"` // Whether agent mode is enabled for this request
+ AgentID string `json:"agent_id"` // Selected custom agent ID for this request
+ WebSearchEnabled bool `json:"web_search_enabled"` // Whether web search is enabled for this request
+ SummaryModelID string `json:"summary_model_id"` // Optional summary model ID (overrides session default)
+ DisableTitle bool `json:"disable_title"` // Whether to disable auto title generation
+ Images []ImageAttachment `json:"images,omitempty"` // Attached images for multimodal chat
}
// LLMToolCall represents a function/tool call from the LLM
From da4c68a24d1706880b4919f7950baf1ac78c4c99 Mon Sep 17 00:00:00 2001
From: wizardchen
Date: Thu, 12 Mar 2026 21:19:22 +0800
Subject: [PATCH 17/35] feat: introduce Quick Notes 5.0 with enhanced clipping
and context menu features
- Added new background service worker to manage API requests and context menu interactions.
- Implemented a new HTML structure for clips and a JavaScript file to handle clip rendering and user interactions.
- Introduced a content script for capturing and processing selected content on web pages, enabling users to save clips easily.
- Enhanced the popup interface for Quick Notes with improved navigation and user experience.
- Updated the manifest to support new features and permissions for the extension.
These changes significantly enhance the functionality of the Quick Notes extension, providing users with a more robust and interactive experience for managing web content.
---
.../快速笔记 5.0/background.js | 401 ++++++++
.../chrome-extension/快速笔记 5.0/clips.html | 623 ++++++++++++
.../chrome-extension/快速笔记 5.0/clips.js | 746 +++++++++++++++
.../chrome-extension/快速笔记 5.0/content.css | 261 ++++++
.../chrome-extension/快速笔记 5.0/content.js | 876 +++++++++++++++++
.../快速笔记 5.0/icons/icon128.png | Bin 0 -> 799 bytes
.../快速笔记 5.0/icons/icon16.png | Bin 0 -> 160 bytes
.../快速笔记 5.0/icons/icon32.png | Bin 0 -> 234 bytes
.../快速笔记 5.0/icons/icon48.png | Bin 0 -> 317 bytes
.../快速笔记 5.0/manifest.json | 76 ++
.../chrome-extension/快速笔记 5.0/popup.html | 861 +++++++++++++++++
.../chrome-extension/快速笔记 5.0/popup.js | 884 ++++++++++++++++++
.../快速笔记 5.0/requirements.md | 127 +++
.../快速笔记 5.0/sidepanel.html | 397 ++++++++
.../快速笔记 5.0/sidepanel.js | 209 +++++
.../快速笔记 5.0/weknora.html | 265 ++++++
.../chrome-extension/快速笔记 5.0/weknora.js | 109 +++
17 files changed, 5835 insertions(+)
create mode 100644 frontend/chrome-extension/快速笔记 5.0/background.js
create mode 100644 frontend/chrome-extension/快速笔记 5.0/clips.html
create mode 100644 frontend/chrome-extension/快速笔记 5.0/clips.js
create mode 100644 frontend/chrome-extension/快速笔记 5.0/content.css
create mode 100644 frontend/chrome-extension/快速笔记 5.0/content.js
create mode 100644 frontend/chrome-extension/快速笔记 5.0/icons/icon128.png
create mode 100644 frontend/chrome-extension/快速笔记 5.0/icons/icon16.png
create mode 100644 frontend/chrome-extension/快速笔记 5.0/icons/icon32.png
create mode 100644 frontend/chrome-extension/快速笔记 5.0/icons/icon48.png
create mode 100644 frontend/chrome-extension/快速笔记 5.0/manifest.json
create mode 100644 frontend/chrome-extension/快速笔记 5.0/popup.html
create mode 100644 frontend/chrome-extension/快速笔记 5.0/popup.js
create mode 100644 frontend/chrome-extension/快速笔记 5.0/requirements.md
create mode 100644 frontend/chrome-extension/快速笔记 5.0/sidepanel.html
create mode 100644 frontend/chrome-extension/快速笔记 5.0/sidepanel.js
create mode 100644 frontend/chrome-extension/快速笔记 5.0/weknora.html
create mode 100644 frontend/chrome-extension/快速笔记 5.0/weknora.js
diff --git a/frontend/chrome-extension/快速笔记 5.0/background.js b/frontend/chrome-extension/快速笔记 5.0/background.js
new file mode 100644
index 00000000..d0631c68
--- /dev/null
+++ b/frontend/chrome-extension/快速笔记 5.0/background.js
@@ -0,0 +1,401 @@
+// background.js — Service Worker
+// 存储管理 + 消息路由 + 右键菜单
+
+// === 右键菜单 ===
+// 防止并发注册
+var _menuSetupInProgress = false;
+
+function setupContextMenus() {
+ if (_menuSetupInProgress) return;
+ _menuSetupInProgress = true;
+
+ chrome.contextMenus.removeAll(function () {
+ void chrome.runtime.lastError; // 清除可能的 lastError
+
+ // 保存选中文字
+ chrome.contextMenus.create({
+ id: 'ka-save-selection',
+ title: '保存到快速笔记 5.0',
+ contexts: ['selection']
+ }, function () { void chrome.runtime.lastError; });
+
+ // 用选中文字提问
+ chrome.contextMenus.create({
+ id: 'ka-ask-selection',
+ title: '使用知识助理提问',
+ contexts: ['selection']
+ }, function () { void chrome.runtime.lastError; });
+
+ // 保存图片到快速笔记
+ chrome.contextMenus.create({
+ id: 'ka-save-image',
+ title: '保存图片到快速笔记',
+ contexts: ['image']
+ }, function () { void chrome.runtime.lastError; });
+
+ _menuSetupInProgress = false;
+
+ // 根据登录状态更新菜单文案
+ updateContextMenuTitle();
+ });
+}
+
+// 插件安装/更新时注册
+chrome.runtime.onInstalled.addListener(function () {
+ setupContextMenus();
+});
+
+// Service Worker 每次启动时也注册(确保重载后菜单存在)
+setupContextMenus();
+
+// 根据登录类型动态更新右键菜单中"提问"的文案
+async function updateContextMenuTitle() {
+ var data = await chrome.storage.local.get('ka_auth');
+ var auth = data.ka_auth;
+ var askTitle = '使用知识助理提问';
+ if (auth && auth.type === 'wk') {
+ askTitle = '使用 WeKnora 提问';
+ } else if (auth && auth.type === 'ka') {
+ askTitle = '使用知识助理提问';
+ }
+ try {
+ chrome.contextMenus.update('ka-ask-selection', { title: askTitle });
+ } catch (e) { /* 菜单还未创建时忽略 */ }
+}
+
+chrome.contextMenus.onClicked.addListener(function (info, tab) {
+ // 处理图片保存(不需要 selectionText)
+ if (info.menuItemId === 'ka-save-image') {
+ var imgUrl = info.srcUrl;
+ if (!imgUrl) return;
+ var title = '图片收藏 - ' + (tab.title || '未知页面');
+ var clip = {
+ type: 'image-clip',
+ content: '',
+ title: title,
+ meta: { url: tab.url || '', title: tab.title || '', imageUrl: imgUrl }
+ };
+ saveClip(clip).then(function () {
+ if (tab && tab.id) {
+ chrome.tabs.sendMessage(tab.id, {
+ type: 'SHOW_NOTIFICATION',
+ payload: { msg: '图片已保存到快速笔记', status: 'success' }
+ }).catch(function () {});
+ }
+ });
+ return;
+ }
+
+ if (!info.selectionText) return;
+
+ if (info.menuItemId === 'ka-save-selection') {
+ var title = '选中文本 - ' + (tab.title || '未知页面');
+ var clip = {
+ type: 'select-clip',
+ content: info.selectionText,
+ title: title,
+ meta: { url: tab.url || '', title: tab.title || '' }
+ };
+ saveClip(clip).then(function () {
+ if (tab && tab.id) {
+ chrome.tabs.sendMessage(tab.id, {
+ type: 'SHOW_NOTIFICATION',
+ payload: { msg: '已保存到快速笔记', status: 'success' }
+ }).catch(function () {});
+ }
+ });
+ }
+
+ if (info.menuItemId === 'ka-ask-selection') {
+ // 打开侧边栏并将选中文字作为问题
+ if (tab && tab.id) {
+ chrome.storage.local.set({
+ ka_pending_query: { query: info.selectionText, ts: Date.now() }
+ });
+ chrome.sidePanel.open({ tabId: tab.id }).catch(function () {});
+ }
+ }
+});
+
+chrome.runtime.onMessage.addListener(function (msg, sender, sendResponse) {
+ handleMessage(msg, sender).then(function (result) {
+ sendResponse(result);
+ }).catch(function (err) {
+ sendResponse({ success: false, error: err.message || '未知错误' });
+ });
+ return true;
+});
+
+async function handleMessage(msg, sender) {
+ switch (msg.type) {
+ case 'GET_AUTH':
+ return getAuth();
+ case 'SET_AUTH':
+ return setAuth(msg.payload);
+ case 'CLEAR_AUTH':
+ return clearAuth();
+ case 'GET_CONFIG':
+ return getConfig();
+ case 'SET_CONFIG':
+ return setConfig(msg.payload);
+ case 'SAVE_NOTE':
+ return saveNote(msg.payload);
+ case 'GET_NOTES':
+ return getNotes();
+ case 'SAVE_CLIP':
+ return saveClip(msg.payload);
+ case 'GET_CLIPS':
+ return getClips();
+ case 'DELETE_CLIP':
+ return deleteClip(msg.payload);
+ case 'DELETE_NOTE':
+ return deleteNote(msg.payload);
+ case 'UPDATE_CLIP':
+ return updateClip(msg.payload);
+ case 'UPDATE_NOTE':
+ return updateNote(msg.payload);
+ case 'INJECT_SCRIPT':
+ return injectScript(msg.payload.tabId);
+ case 'ASK_WEKNORA':
+ // 打开侧边栏并传递选中的文字作为问题
+ if (sender && sender.tab && sender.tab.id) {
+ await chrome.sidePanel.open({ tabId: sender.tab.id });
+ // 存储待处理的问题,sidepanel 加载后会读取
+ await chrome.storage.local.set({
+ ka_pending_query: { query: msg.payload.text, ts: Date.now() }
+ });
+ }
+ return { success: true };
+ case 'SAVE_SELECTION':
+ // 从气泡保存选中文字
+ return saveClip(msg.payload);
+ case 'SAVE_IMAGE':
+ // 从气泡保存图片
+ return saveClip(msg.payload);
+ case 'CAPTURE_SCREENSHOT':
+ // 截取当前标签页可见区域
+ try {
+ var tabId = sender && sender.tab && sender.tab.id;
+ if (!tabId) return { success: false, error: '无法获取标签页' };
+ var dataUrl = await chrome.tabs.captureVisibleTab(null, { format: 'jpeg', quality: 90 });
+ return { success: true, dataUrl: dataUrl };
+ } catch (err) {
+ return { success: false, error: err.message || '截图失败' };
+ }
+ default:
+ return { success: false, error: '未知消息类型' };
+ }
+}
+
+// === Auth ===
+async function getAuth() {
+ var data = await chrome.storage.local.get('ka_auth');
+ return { success: true, data: data.ka_auth || null };
+}
+
+async function setAuth(auth) {
+ await chrome.storage.local.set({ ka_auth: auth });
+ updateContextMenuTitle();
+ return { success: true };
+}
+
+async function clearAuth() {
+ await chrome.storage.local.remove('ka_auth');
+ updateContextMenuTitle();
+ return { success: true };
+}
+
+// === Config (WeKnora) ===
+async function getConfig() {
+ var data = await chrome.storage.local.get('ka_config');
+ return { success: true, data: data.ka_config || { baseUrl: '', apiKey: '' } };
+}
+
+async function setConfig(config) {
+ await chrome.storage.local.set({ ka_config: config });
+ return { success: true };
+}
+
+// === Notes (Markdown) ===
+async function saveNote(note) {
+ var data = await chrome.storage.local.get('ka_notes');
+ var notes = data.ka_notes || [];
+ note.id = Date.now().toString();
+ note.createdAt = new Date().toISOString();
+ notes.unshift(note);
+ if (notes.length > 100) notes = notes.slice(0, 100);
+ await chrome.storage.local.set({ ka_notes: notes });
+ return { success: true, data: note };
+}
+
+async function getNotes() {
+ var data = await chrome.storage.local.get('ka_notes');
+ return { success: true, data: data.ka_notes || [] };
+}
+
+// === Clips (网页截取收藏) ===
+async function saveClip(clip) {
+ try {
+ var data = await chrome.storage.local.get('ka_clips');
+ var clips = data.ka_clips || [];
+
+ // 如果传入了已有 id,说明是编辑已有笔记,执行更新而非新增
+ if (clip.id) {
+ var found = false;
+ for (var i = 0; i < clips.length; i++) {
+ if (clips[i].id === clip.id) {
+ // 保留原始创建时间和其他元数据,只更新内容相关字段
+ clips[i].content = clip.content;
+ if (clip.title) clips[i].title = clip.title;
+ if (clip.type) clips[i].type = clip.type;
+ clips[i].updatedAt = new Date().toISOString();
+ clip = clips[i]; // 返回完整的更新后记录
+ found = true;
+ break;
+ }
+ }
+ // 如果在 ka_clips 中没找到,再到 ka_notes 中查找并更新
+ if (!found) {
+ var notesData = await chrome.storage.local.get('ka_notes');
+ var notes = notesData.ka_notes || [];
+ for (var j = 0; j < notes.length; j++) {
+ if (notes[j].id === clip.id) {
+ notes[j].content = clip.content;
+ if (clip.title) notes[j].title = clip.title;
+ if (clip.type) notes[j].type = clip.type;
+ notes[j].updatedAt = new Date().toISOString();
+ clip = notes[j];
+ found = true;
+ await chrome.storage.local.set({ ka_notes: notes });
+ break;
+ }
+ }
+ }
+ if (found) {
+ await chrome.storage.local.set({ ka_clips: clips });
+ return { success: true, data: clip };
+ }
+ // 没找到原记录,当作新建处理(fallthrough)
+ }
+
+ // 新建记录
+ clip.id = Date.now().toString();
+ clip.createdAt = new Date().toISOString();
+ clips.unshift(clip);
+ if (clips.length > 200) clips = clips.slice(0, 200);
+ await chrome.storage.local.set({ ka_clips: clips });
+ return { success: true, data: clip };
+ } catch (err) {
+ // 如果保存失败(可能是截图太大),尝试去掉截图再保存
+ if (clip.screenshot) {
+ try {
+ delete clip.screenshot;
+ var data2 = await chrome.storage.local.get('ka_clips');
+ var clips2 = data2.ka_clips || [];
+ clips2.unshift(clip);
+ if (clips2.length > 200) clips2 = clips2.slice(0, 200);
+ await chrome.storage.local.set({ ka_clips: clips2 });
+ return { success: true, data: clip, warning: '截图过大已省略,仅保存文字' };
+ } catch (err2) {
+ return { success: false, error: '保存失败: ' + (err2.message || '存储空间不足') };
+ }
+ }
+ return { success: false, error: '保存失败: ' + (err.message || '未知错误') };
+ }
+}
+
+async function getClips() {
+ var data = await chrome.storage.local.get('ka_clips');
+ return { success: true, data: data.ka_clips || [] };
+}
+
+async function deleteClip(payload) {
+ var data = await chrome.storage.local.get('ka_clips');
+ var clips = data.ka_clips || [];
+ clips = clips.filter(function (c) { return c.id !== payload.id; });
+ await chrome.storage.local.set({ ka_clips: clips });
+ return { success: true };
+}
+
+async function deleteNote(payload) {
+ var data = await chrome.storage.local.get('ka_notes');
+ var notes = data.ka_notes || [];
+ notes = notes.filter(function (n) { return n.id !== payload.id; });
+ await chrome.storage.local.set({ ka_notes: notes });
+ return { success: true };
+}
+
+async function updateClip(payload) {
+ var data = await chrome.storage.local.get('ka_clips');
+ var clips = data.ka_clips || [];
+ var found = false;
+ for (var i = 0; i < clips.length; i++) {
+ if (clips[i].id === payload.id) {
+ clips[i].content = payload.content;
+ if (payload.title) clips[i].title = payload.title;
+ clips[i].updatedAt = new Date().toISOString();
+ found = true;
+ break;
+ }
+ }
+ if (!found) return { success: false, error: '未找到对应记录' };
+ await chrome.storage.local.set({ ka_clips: clips });
+ return { success: true };
+}
+
+async function updateNote(payload) {
+ var data = await chrome.storage.local.get('ka_notes');
+ var notes = data.ka_notes || [];
+ var found = false;
+ for (var i = 0; i < notes.length; i++) {
+ if (notes[i].id === payload.id) {
+ notes[i].content = payload.content;
+ if (payload.title) notes[i].title = payload.title;
+ notes[i].updatedAt = new Date().toISOString();
+ found = true;
+ break;
+ }
+ }
+ if (!found) return { success: false, error: '未找到对应记录' };
+ await chrome.storage.local.set({ ka_notes: notes });
+ return { success: true };
+}
+
+// === Inject content script ===
+async function injectScript(tabId) {
+ try {
+ await chrome.scripting.executeScript({ target: { tabId: tabId }, files: ['content.js'] });
+ await chrome.scripting.insertCSS({ target: { tabId: tabId }, files: ['content.css'] });
+ return { success: true };
+ } catch (e) {
+ return { success: false, error: e.message };
+ }
+}
+
+// === Commands ===
+chrome.commands.onCommand.addListener(async function (cmd, tab) {
+ if (!tab || !tab.id) return;
+ if (cmd === 'open-sidepanel') {
+ await chrome.sidePanel.open({ tabId: tab.id });
+ }
+ if (cmd === 'quick-ask') {
+ await chrome.sidePanel.open({ tabId: tab.id });
+ }
+ if (cmd === 'select-clip') {
+ // 快捷键触发选择剪藏:先确保 content script 已注入,再发消息
+ try {
+ await chrome.tabs.sendMessage(tab.id, { type: 'SELECT_CLIP' });
+ } catch (e) {
+ // content script 未注入,先注入再发送
+ try {
+ await chrome.scripting.executeScript({ target: { tabId: tab.id }, files: ['content.js'] });
+ await chrome.scripting.insertCSS({ target: { tabId: tab.id }, files: ['content.css'] });
+ setTimeout(function () {
+ chrome.tabs.sendMessage(tab.id, { type: 'SELECT_CLIP' }).catch(function () {});
+ }, 300);
+ } catch (injectErr) {
+ // 无法注入的页面(如 chrome:// 页面),忽略
+ }
+ }
+ }
+});
diff --git a/frontend/chrome-extension/快速笔记 5.0/clips.html b/frontend/chrome-extension/快速笔记 5.0/clips.html
new file mode 100644
index 00000000..88f4f7e7
--- /dev/null
+++ b/frontend/chrome-extension/快速笔记 5.0/clips.html
@@ -0,0 +1,623 @@
+
+
+
+
+
+网页内容收藏 - 快速笔记 5.0
+
+
+
+
+
+
+
+
内容收藏
+
+
+
+
+ 刷新
+
+
+
+ 清空全部
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
暂无收藏内容
+
使用插件的「选择剪藏」或「智能剪藏」功能 截取网页内容后会自动保存到这里
+
+
+
+
+
+
+
+ 全部类型
+ 截图
+ 智能剪藏
+ 速记笔记
+ 图片收藏
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/frontend/chrome-extension/快速笔记 5.0/clips.js b/frontend/chrome-extension/快速笔记 5.0/clips.js
new file mode 100644
index 00000000..9ed25c7a
--- /dev/null
+++ b/frontend/chrome-extension/快速笔记 5.0/clips.js
@@ -0,0 +1,746 @@
+(function () {
+ 'use strict';
+
+ function $(id) { return document.getElementById(id); }
+
+ var clipList = $('clip-list');
+ var emptyState = $('empty-state');
+ var totalEl = $('clips-total');
+ var searchInput = $('search-input');
+ var filterType = $('filter-type');
+ var contentTitle = $('content-title');
+ var allClips = []; // 每条记录增加 _source 字段: 'ka_clips' | 'ka_notes'
+
+ // === 图片灯箱 ===
+ var lightbox = $('lightbox');
+ var lightboxImg = $('lightbox-img');
+ var lightboxClose = $('lightbox-close');
+
+ function openLightbox(src) {
+ lightboxImg.src = src;
+ lightbox.classList.add('show');
+ document.body.style.overflow = 'hidden';
+ }
+
+ function closeLightbox() {
+ lightbox.classList.remove('show');
+ lightboxImg.src = '';
+ document.body.style.overflow = '';
+ }
+
+ // 点击遮罩关闭(不点击图片本身)
+ lightbox.addEventListener('click', function (e) {
+ if (e.target === lightbox) closeLightbox();
+ });
+ lightboxClose.addEventListener('click', closeLightbox);
+ // ESC 关闭
+ document.addEventListener('keydown', function (e) {
+ if (e.key === 'Escape' && lightbox.classList.contains('show')) {
+ closeLightbox();
+ }
+ });
+
+ // 分类名称映射
+ var categoryLabels = {
+ 'all': '全部内容',
+ 'select-clip': '截图',
+ 'smart-clip': '智能剪藏',
+ 'markdown': '速记笔记',
+ 'image-clip': '图片收藏'
+ };
+
+ // === Toast ===
+ function toast(msg, type) {
+ var el = $('toast');
+ el.textContent = msg;
+ el.className = 'toast show' + (type ? ' ' + type : '');
+ setTimeout(function () { el.classList.remove('show'); }, 2000);
+ }
+
+ // === 轻量级 Markdown → HTML 渲染 ===
+ function renderMarkdown(text) {
+ if (!text) return '';
+ var html = text;
+
+ // 代码块 (```...```) — 先处理,避免内部被其他规则干扰
+ html = html.replace(/```(\w*)\n([\s\S]*?)```/g, function (_, lang, code) {
+ return '' + escapeHtml(code.replace(/\n$/, '')) + ' ';
+ });
+
+ // 行内代码
+ html = html.replace(/`([^`]+)`/g, '$1');
+
+ // 表格(简单支持)
+ html = html.replace(/((?:\|.+\|\n)+)/g, function (tableBlock) {
+ var rows = tableBlock.trim().split('\n');
+ if (rows.length < 2) return tableBlock;
+ var out = '';
+ rows.forEach(function (row, i) {
+ // 跳过分隔行 |---|---|
+ if (/^\|[\s\-:|]+\|$/.test(row)) return;
+ var tag = i === 0 ? 'th' : 'td';
+ var cells = row.split('|').filter(function (c, ci, arr) { return ci > 0 && ci < arr.length - 1; });
+ out += '';
+ cells.forEach(function (cell) {
+ out += '<' + tag + '>' + cell.trim() + '' + tag + '>';
+ });
+ out += ' ';
+ });
+ out += '
';
+ return out;
+ });
+
+ // 将剩余文本按行处理
+ var lines = html.split('\n');
+ var result = [];
+ var inList = false;
+ var listType = '';
+
+ for (var i = 0; i < lines.length; i++) {
+ var line = lines[i];
+
+ // 已渲染的 / 块直接保留
+ if (line.indexOf('') !== -1 || line.indexOf(' ') !== -1) {
+ if (inList) { result.push('' + listType + '>'); inList = false; }
+ result.push(line);
+ continue;
+ }
+
+ // 标题
+ if (/^####\s+(.+)/.test(line)) { if (inList) { result.push('' + listType + '>'); inList = false; } result.push('' + RegExp.$1 + ' '); continue; }
+ if (/^###\s+(.+)/.test(line)) { if (inList) { result.push('' + listType + '>'); inList = false; } result.push('' + RegExp.$1 + ' '); continue; }
+ if (/^##\s+(.+)/.test(line)) { if (inList) { result.push('' + listType + '>'); inList = false; } result.push('' + RegExp.$1 + ' '); continue; }
+ if (/^#\s+(.+)/.test(line)) { if (inList) { result.push('' + listType + '>'); inList = false; } result.push('' + RegExp.$1 + ' '); continue; }
+
+ // 分隔线
+ if (/^---+$/.test(line.trim())) { if (inList) { result.push('' + listType + '>'); inList = false; } result.push(' '); continue; }
+
+ // 引用
+ if (/^>\s*(.*)/.test(line)) { if (inList) { result.push('' + listType + '>'); inList = false; } result.push('' + RegExp.$1 + ' '); continue; }
+
+ // 无序列表
+ if (/^[\-\*]\s+(.+)/.test(line)) {
+ if (!inList || listType !== 'ul') {
+ if (inList) result.push('' + listType + '>');
+ result.push('