(null);
// 图片预览状态
const imagePreviewVisible = ref(false);
@@ -644,6 +637,13 @@ watch(eventStream, (stream) => {
}
});
}
+ // Auto-scroll streaming steps container to bottom during streaming
+ if (!hasAnswerStarted.value && streamingStepsContainer.value) {
+ const el = streamingStepsContainer.value;
+ if (el.scrollHeight > el.clientHeight) {
+ el.scrollTop = el.scrollHeight;
+ }
+ }
});
}, { immediate: true, deep: true });
@@ -1352,7 +1352,21 @@ const getTokens = (content: any) => {
const contentStr = typeof content === 'string' ? content : String(content || '');
if (!contentStr.trim()) return [];
- const processed = preprocessMarkdown(sanitizeForDisplay(contentStr));
+ // Extract and tags before sanitization to prevent
+ // sanitizeForDisplay from stripping chunk_id labels and UUIDs inside them.
+ const tagPlaceholders: string[] = [];
+ const preserved = contentStr.replace(/<(?:kb|web)\b[^>]*\/>/g, (match) => {
+ const idx = tagPlaceholders.length;
+ tagPlaceholders.push(match);
+ return `\x00TAG${idx}\x00`;
+ });
+
+ let sanitized = sanitizeForDisplay(preserved);
+
+ // Restore preserved tags
+ sanitized = sanitized.replace(/\x00TAG(\d+)\x00/g, (_, idx) => tagPlaceholders[Number(idx)]);
+
+ const processed = preprocessMarkdown(sanitized);
return marked.lexer(processed);
};
@@ -1864,6 +1878,31 @@ const handleAddToKnowledge = (answerEvent: any) => {
position: relative;
}
+// Streaming steps container
+.streaming-steps-container {
+ &.streaming-steps-constrained {
+ max-height: 400px;
+ overflow-y: auto;
+
+ &::-webkit-scrollbar {
+ width: 4px;
+ }
+
+ &::-webkit-scrollbar-track {
+ background: transparent;
+ }
+
+ &::-webkit-scrollbar-thumb {
+ background: var(--td-bg-color-component-disabled);
+ border-radius: 2px;
+
+ &:hover {
+ background: var(--td-text-color-placeholder);
+ }
+ }
+ }
+}
+
// Event items (flat, no timeline)
.event-item {
position: relative;
@@ -1933,6 +1972,25 @@ const handleAddToKnowledge = (answerEvent: any) => {
position: relative;
padding-left: 12px; // indent for branch lines
margin-top: 6px; // gap from root
+ max-height: 400px;
+ overflow-y: auto;
+
+ &::-webkit-scrollbar {
+ width: 4px;
+ }
+
+ &::-webkit-scrollbar-track {
+ background: transparent;
+ }
+
+ &::-webkit-scrollbar-thumb {
+ background: var(--td-bg-color-component-disabled);
+ border-radius: 2px;
+
+ &:hover {
+ background: var(--td-text-color-placeholder);
+ }
+ }
}
.tree-child {
@@ -1942,12 +2000,13 @@ const handleAddToKnowledge = (answerEvent: any) => {
margin-bottom: 6px; // gap between children
// vertical trunk line (continues for non-last children)
+ // bottom: -6px extends the line through the margin-bottom gap between siblings
&::before {
content: '';
position: absolute;
left: 0;
top: 0;
- bottom: 0;
+ bottom: -6px;
width: 0;
border-left: 1px dashed var(--td-component-stroke);
}
diff --git a/frontend/src/views/chat/components/botmsg.vue b/frontend/src/views/chat/components/botmsg.vue
index bcc7560a..6b3776cd 100644
--- a/frontend/src/views/chat/components/botmsg.vue
+++ b/frontend/src/views/chat/components/botmsg.vue
@@ -31,6 +31,14 @@
+
+
@@ -548,6 +556,10 @@ onBeforeUnmount(() => {
padding: 8px 0;
}
+.loading-indicator {
+ padding: 8px 0;
+}
+
.loading-typing {
display: flex;
align-items: center;
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/application/service/chat_pipline/merge.go b/internal/application/service/chat_pipline/merge.go
index 92d0ffa9..bfeefe2b 100644
--- a/internal/application/service/chat_pipline/merge.go
+++ b/internal/application/service/chat_pipline/merge.go
@@ -3,11 +3,8 @@ package chatpipline
import (
"context"
"encoding/json"
- "fmt"
"sort"
- "strings"
- "github.com/Tencent/WeKnora/internal/searchutil"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
)
@@ -33,7 +30,16 @@ func (p *PluginMerge) ActivationEvents() []types.EventType {
return []types.EventType{types.CHUNK_MERGE}
}
-// OnEvent processes the CHUNK_MERGE event to merge search result chunks
+// OnEvent processes the CHUNK_MERGE event to merge search result chunks.
+// The merge pipeline is:
+// 1. Select input (rerank or search fallback)
+// 2. Deduplicate by ID and content signature
+// 3. Inject relevant history references
+// 4. Resolve parent chunks (child → parent content)
+// 5. Group by knowledge source + chunk type, merge overlapping ranges
+// 6. Populate FAQ answers
+// 7. Expand short contexts with neighboring chunks
+// 8. Final deduplication (catches duplicates introduced by steps 4-7)
func (p *PluginMerge) OnEvent(ctx context.Context,
eventType types.EventType, chatManage *types.ChatManage, next func() *PluginError,
) *PluginError {
@@ -42,46 +48,19 @@ func (p *PluginMerge) OnEvent(ctx context.Context,
"candidate_cnt": len(chatManage.RerankResult),
})
- // Use rerank results if available, fallback to search results
- searchResult := chatManage.RerankResult
- if len(searchResult) == 0 {
- pipelineWarn(ctx, "Merge", "fallback", map[string]interface{}{
- "reason": "empty_rerank_result",
- })
- searchResult = chatManage.SearchResult
- // Sort by score descending so dedup keeps highest-scored entries
- sort.Slice(searchResult, func(i, j int) bool {
- return searchResult[i].Score > searchResult[j].Score
- })
- }
+ // Step 1: Select input
+ searchResult := p.selectInputResults(ctx, chatManage)
- // Deduplicate after rerank so higher-scored duplicates are preferred
- beforeDedup := len(searchResult)
- searchResult = removeDuplicateResults(searchResult)
- pipelineInfo(ctx, "Merge", "dedup_summary", map[string]interface{}{
- "before": beforeDedup,
- "after": len(searchResult),
- })
+ // Step 2: Initial dedup
+ searchResult = p.dedup(ctx, "dedup_summary", searchResult)
- // Inject relevant results from chat history with similarity filtering.
- // History references were produced for a previous query, so we only keep
- // those that are textually relevant to the current query to avoid injecting
- // stale or off-topic context.
- historyResults := filterHistoryResults(ctx, chatManage, searchResult)
- if len(historyResults) > 0 {
- pipelineInfo(ctx, "Merge", "history_inject", map[string]interface{}{
- "session_id": chatManage.SessionID,
- "history_hits": len(historyResults),
- })
- searchResult = append(searchResult, historyResults...)
- searchResult = removeDuplicateResults(searchResult)
- }
+ // Step 3: Inject history references
+ searchResult = p.injectHistoryResults(ctx, chatManage, searchResult)
pipelineInfo(ctx, "Merge", "candidate_ready", map[string]interface{}{
"chunk_cnt": len(searchResult),
})
- // If there are no search results, return early
if len(searchResult) == 0 {
pipelineWarn(ctx, "Merge", "output", map[string]interface{}{
"chunk_cnt": 0,
@@ -90,24 +69,92 @@ func (p *PluginMerge) OnEvent(ctx context.Context,
return next()
}
- // Resolve parent chunks: replace child content with fuller parent content
+ // Step 4: Resolve parent chunks
searchResult = p.resolveParentChunks(ctx, chatManage, searchResult)
- // Group chunks by their knowledge source ID
+ // Step 5: Group by knowledge/chunkType and merge overlapping ranges
+ mergedChunks := p.groupAndMergeOverlapping(ctx, searchResult)
+
+ // Step 6: Populate FAQ answers
+ mergedChunks = p.populateFAQAnswers(ctx, chatManage, mergedChunks)
+
+ // Step 7: Expand short contexts
+ mergedChunks = p.expandShortContextWithNeighbors(ctx, chatManage, mergedChunks)
+
+ // Step 8: Final dedup (catches duplicates from parent resolution / expansion)
+ mergedChunks = p.dedup(ctx, "final_dedup", mergedChunks)
+
+ chatManage.MergeResult = mergedChunks
+ return next()
+}
+
+// selectInputResults picks rerank results if available, falling back to search
+// results sorted by score descending.
+func (p *PluginMerge) selectInputResults(ctx context.Context, chatManage *types.ChatManage) []*types.SearchResult {
+ if len(chatManage.RerankResult) > 0 {
+ return chatManage.RerankResult
+ }
+ pipelineWarn(ctx, "Merge", "fallback", map[string]interface{}{
+ "reason": "empty_rerank_result",
+ })
+ result := chatManage.SearchResult
+ sort.Slice(result, func(i, j int) bool {
+ return result[i].Score > result[j].Score
+ })
+ return result
+}
+
+// dedup wraps removeDuplicateResults with before/after logging.
+func (p *PluginMerge) dedup(ctx context.Context, label string, results []*types.SearchResult) []*types.SearchResult {
+ before := len(results)
+ out := removeDuplicateResults(results)
+ if len(out) < before {
+ pipelineInfo(ctx, "Merge", label, map[string]interface{}{
+ "before": before,
+ "after": len(out),
+ })
+ }
+ return out
+}
+
+// injectHistoryResults appends relevant history references to the current results
+// and deduplicates the combined set.
+func (p *PluginMerge) injectHistoryResults(
+ ctx context.Context,
+ chatManage *types.ChatManage,
+ current []*types.SearchResult,
+) []*types.SearchResult {
+ historyResults := filterHistoryResults(ctx, chatManage, current)
+ if len(historyResults) == 0 {
+ return current
+ }
+ pipelineInfo(ctx, "Merge", "history_inject", map[string]interface{}{
+ "session_id": chatManage.SessionID,
+ "history_hits": len(historyResults),
+ })
+ combined := append(current, historyResults...)
+ return removeDuplicateResults(combined)
+}
+
+// groupAndMergeOverlapping groups chunks by KnowledgeID + ChunkType, then merges
+// overlapping ranges within each group using mergeOverlappingChunks.
+func (p *PluginMerge) groupAndMergeOverlapping(ctx context.Context, results []*types.SearchResult) []*types.SearchResult {
+ // Group by KnowledgeID → ChunkType
knowledgeGroup := make(map[string]map[string][]*types.SearchResult)
- for _, chunk := range searchResult {
+ for _, chunk := range results {
if _, ok := knowledgeGroup[chunk.KnowledgeID]; !ok {
knowledgeGroup[chunk.KnowledgeID] = make(map[string][]*types.SearchResult)
}
- knowledgeGroup[chunk.KnowledgeID][chunk.ChunkType] = append(knowledgeGroup[chunk.KnowledgeID][chunk.ChunkType], chunk)
+ knowledgeGroup[chunk.KnowledgeID][chunk.ChunkType] = append(
+ knowledgeGroup[chunk.KnowledgeID][chunk.ChunkType], chunk,
+ )
}
pipelineInfo(ctx, "Merge", "group_summary", map[string]interface{}{
"knowledge_cnt": len(knowledgeGroup),
})
- mergedChunks := []*types.SearchResult{}
- // Process each knowledge source separately
+ var mergedChunks []*types.SearchResult
for knowledgeID, chunkGroup := range knowledgeGroup {
for _, chunks := range chunkGroup {
pipelineInfo(ctx, "Merge", "group_process", map[string]interface{}{
@@ -115,7 +162,7 @@ func (p *PluginMerge) OnEvent(ctx context.Context,
"chunk_cnt": len(chunks),
})
- // Sort chunks by their start position in the original document
+ // Sort by start position, then by end position
sort.Slice(chunks, func(i, j int) bool {
if chunks[i].StartAt == chunks[j].StartAt {
return chunks[i].EndAt < chunks[j].EndAt
@@ -123,69 +170,21 @@ func (p *PluginMerge) OnEvent(ctx context.Context,
return chunks[i].StartAt < chunks[j].StartAt
})
- // Merge overlapping or adjacent chunks
- knowledgeMergedChunks := []*types.SearchResult{chunks[0]}
- for i := 1; i < len(chunks); i++ {
- lastChunk := knowledgeMergedChunks[len(knowledgeMergedChunks)-1]
- // If the current chunk starts after the last chunk ends, add it to the merged chunks
- if chunks[i].StartAt > lastChunk.EndAt {
- knowledgeMergedChunks = append(knowledgeMergedChunks, chunks[i])
- continue
- }
- // Merge overlapping chunks
- if chunks[i].EndAt > lastChunk.EndAt {
- contentRunes := []rune(chunks[i].Content)
- offset := len(contentRunes) - (chunks[i].EndAt - lastChunk.EndAt)
- lastChunk.Content = lastChunk.Content + string(contentRunes[offset:])
- lastChunk.EndAt = chunks[i].EndAt
- lastChunk.SubChunkID = append(lastChunk.SubChunkID, chunks[i].ID)
-
- if err := mergeImageInfo(ctx, lastChunk, chunks[i]); err != nil {
- pipelineWarn(ctx, "Merge", "image_merge", map[string]interface{}{
- "knowledge_id": knowledgeID,
- "error": err.Error(),
- })
- }
- } else {
- // Fully contained: track the subsumed chunk and merge its ImageInfo
- if !containsID(lastChunk.SubChunkID, chunks[i].ID) {
- lastChunk.SubChunkID = append(lastChunk.SubChunkID, chunks[i].ID)
- }
- if err := mergeImageInfo(ctx, lastChunk, chunks[i]); err != nil {
- pipelineWarn(ctx, "Merge", "image_merge_contained", map[string]interface{}{
- "knowledge_id": knowledgeID,
- "error": err.Error(),
- })
- }
- }
- if chunks[i].Score > lastChunk.Score {
- lastChunk.Score = chunks[i].Score
- }
- }
+ grouped := p.mergeOverlappingChunks(ctx, knowledgeID, chunks)
pipelineInfo(ctx, "Merge", "group_output", map[string]interface{}{
"knowledge_id": knowledgeID,
- "merged_chunks": len(knowledgeMergedChunks),
+ "merged_chunks": len(grouped),
})
- // Sort merged chunks by their score (highest first)
- sort.Slice(knowledgeMergedChunks, func(i, j int) bool {
- return knowledgeMergedChunks[i].Score > knowledgeMergedChunks[j].Score
- })
-
- mergedChunks = append(mergedChunks, knowledgeMergedChunks...)
+ mergedChunks = append(mergedChunks, grouped...)
}
}
pipelineInfo(ctx, "Merge", "output", map[string]interface{}{
"merged_total": len(mergedChunks),
})
-
- mergedChunks = p.populateFAQAnswers(ctx, chatManage, mergedChunks)
- mergedChunks = p.expandShortContextWithNeighbors(ctx, chatManage, mergedChunks)
-
- chatManage.MergeResult = mergedChunks
- return next()
+ return mergedChunks
}
// resolveParentChunks replaces child chunk content with parent chunk content
@@ -358,611 +357,3 @@ func (p *PluginMerge) collectParentImageInfo(
return result
}
-
-// filterHistoryResults retrieves history references and filters them by
-// textual similarity to the current query. Only references that are above
-// a Jaccard similarity threshold are kept, and their scores are discounted
-// to reflect that they were not directly retrieved for the current query.
-// Results already present in currentResults (by chunk ID) are excluded.
-func filterHistoryResults(
- ctx context.Context,
- chatManage *types.ChatManage,
- currentResults []*types.SearchResult,
-) []*types.SearchResult {
- const (
- // minSimilarity is the minimum Jaccard similarity between the current
- // query and a history chunk's content for it to be injected.
- minSimilarity = 0.15
- // historyScoreDiscount reduces the original score of history results
- // to rank them below freshly-retrieved results of similar relevance.
- historyScoreDiscount = 0.6
- // maxHistoryResults caps the number of history results injected to
- // avoid overwhelming the context with stale references.
- maxHistoryResults = 3
- )
-
- raw := getSearchResultFromHistory(chatManage)
- if len(raw) == 0 {
- return nil
- }
-
- // Build a set of chunk IDs already in current results for fast dedup
- existingIDs := make(map[string]struct{}, len(currentResults))
- for _, r := range currentResults {
- existingIDs[r.ID] = struct{}{}
- }
-
- // Use RewriteQuery if available (it's the cleaned-up retrieval query),
- // otherwise fall back to the original query.
- query := chatManage.RewriteQuery
- if query == "" {
- query = chatManage.Query
- }
- queryTokens := searchutil.TokenizeSimple(query)
-
- var filtered []*types.SearchResult
- for _, r := range raw {
- if _, exists := existingIDs[r.ID]; exists {
- continue
- }
- contentTokens := searchutil.TokenizeSimple(r.Content)
- sim := searchutil.Jaccard(queryTokens, contentTokens)
- if sim < minSimilarity {
- pipelineInfo(ctx, "Merge", "history_filter_drop", map[string]interface{}{
- "chunk_id": r.ID,
- "similarity": sim,
- })
- continue
- }
- r.MatchType = types.MatchTypeHistory
- r.Score = r.Score * historyScoreDiscount
- r.Metadata = ensureMetadata(r.Metadata)
- r.Metadata["history_similarity"] = strings.TrimRight(strings.TrimRight(
- fmt.Sprintf("%.4f", sim), "0"), ".")
- filtered = append(filtered, r)
-
- pipelineInfo(ctx, "Merge", "history_filter_keep", map[string]interface{}{
- "chunk_id": r.ID,
- "similarity": sim,
- "new_score": r.Score,
- })
-
- if len(filtered) >= maxHistoryResults {
- break
- }
- }
- return filtered
-}
-
-// mergeImageInfo 合并两个chunk的ImageInfo
-func mergeImageInfo(ctx context.Context, target *types.SearchResult, source *types.SearchResult) error {
- // 如果source没有ImageInfo,不需要合并
- if source.ImageInfo == "" {
- return nil
- }
-
- var sourceImageInfos []types.ImageInfo
- if err := json.Unmarshal([]byte(source.ImageInfo), &sourceImageInfos); err != nil {
- pipelineWarn(ctx, "Merge", "image_unmarshal_source", map[string]interface{}{
- "error": err.Error(),
- })
- return err
- }
-
- // 如果source的ImageInfo为空,不需要合并
- if len(sourceImageInfos) == 0 {
- return nil
- }
-
- // 处理target的ImageInfo
- var targetImageInfos []types.ImageInfo
- if target.ImageInfo != "" {
- if err := json.Unmarshal([]byte(target.ImageInfo), &targetImageInfos); err != nil {
- pipelineWarn(ctx, "Merge", "image_unmarshal_target", map[string]interface{}{
- "error": err.Error(),
- })
- // 如果目标解析失败,直接使用源数据
- target.ImageInfo = source.ImageInfo
- return nil
- }
- }
-
- // 合并ImageInfo
- targetImageInfos = append(targetImageInfos, sourceImageInfos...)
-
- // 去重
- uniqueMap := make(map[string]bool)
- uniqueImageInfos := make([]types.ImageInfo, 0, len(targetImageInfos))
-
- for _, imgInfo := range targetImageInfos {
- // 使用URL作为唯一标识
- if imgInfo.URL != "" && !uniqueMap[imgInfo.URL] {
- uniqueMap[imgInfo.URL] = true
- uniqueImageInfos = append(uniqueImageInfos, imgInfo)
- }
- }
-
- // 序列化合并后的ImageInfo
- mergedImageInfoJSON, err := json.Marshal(uniqueImageInfos)
- if err != nil {
- pipelineWarn(ctx, "Merge", "image_marshal", map[string]interface{}{
- "error": err.Error(),
- })
- return err
- }
-
- // 更新目标chunk的ImageInfo
- target.ImageInfo = string(mergedImageInfoJSON)
- pipelineInfo(ctx, "Merge", "image_merged", map[string]interface{}{
- "image_refs": len(uniqueImageInfos),
- })
- return nil
-}
-
-// populateFAQAnswers populates FAQ answers for the search results
-func (p *PluginMerge) populateFAQAnswers(
- ctx context.Context,
- chatManage *types.ChatManage,
- results []*types.SearchResult,
-) []*types.SearchResult {
- if len(results) == 0 || p.chunkRepo == nil {
- return results
- }
-
- tenantID, _ := types.TenantIDFromContext(ctx)
- if tenantID == 0 && chatManage != nil {
- tenantID = chatManage.TenantID
- }
- if tenantID == 0 {
- pipelineWarn(ctx, "Merge", "faq_enrich_skip", map[string]interface{}{
- "reason": "missing_tenant",
- })
- return results
- }
-
- chunkResultMap := make(map[string][]*types.SearchResult)
- chunkIDSet := make(map[string]struct{})
- for _, r := range results {
- if r == nil || r.ID == "" {
- continue
- }
- if r.ChunkType != string(types.ChunkTypeFAQ) {
- continue
- }
- chunkResultMap[r.ID] = append(chunkResultMap[r.ID], r)
- if _, exists := chunkIDSet[r.ID]; !exists {
- chunkIDSet[r.ID] = struct{}{}
- }
- }
-
- if len(chunkIDSet) == 0 {
- return results
- }
-
- chunkIDs := make([]string, 0, len(chunkIDSet))
- for id := range chunkIDSet {
- chunkIDs = append(chunkIDs, id)
- }
-
- chunks, err := p.chunkRepo.ListChunksByID(ctx, tenantID, chunkIDs)
- if err != nil {
- pipelineWarn(ctx, "Merge", "faq_chunk_fetch_failed", map[string]interface{}{
- "error": err.Error(),
- })
- return results
- }
-
- updated := 0
- for _, chunk := range chunks {
- if chunk == nil {
- continue
- }
- meta, err := chunk.FAQMetadata()
- if err != nil || meta == nil {
- if err != nil {
- pipelineWarn(ctx, "Merge", "faq_metadata_parse_failed", map[string]interface{}{
- "chunk_id": chunk.ID,
- "error": err.Error(),
- })
- }
- continue
- }
- content := buildFAQAnswerContent(meta)
- if content == "" {
- continue
- }
- for _, r := range chunkResultMap[chunk.ID] {
- if r == nil {
- continue
- }
- r.Content = content
- updated++
- }
- }
-
- if updated > 0 {
- pipelineInfo(ctx, "Merge", "faq_content_enriched", map[string]interface{}{
- "chunk_cnt": updated,
- })
- }
- return results
-}
-
-// buildFAQAnswerContent builds the content of a FAQ answer
-func buildFAQAnswerContent(meta *types.FAQChunkMetadata) string {
- if meta == nil {
- return ""
- }
-
- question := strings.TrimSpace(meta.StandardQuestion)
- answers := make([]string, 0, len(meta.Answers))
- for _, ans := range meta.Answers {
- if trimmed := strings.TrimSpace(ans); trimmed != "" {
- answers = append(answers, trimmed)
- }
- }
-
- if question == "" && len(answers) == 0 {
- return ""
- }
-
- var builder strings.Builder
- if question != "" {
- builder.WriteString("Q: ")
- builder.WriteString(question)
- builder.WriteString("\n")
- }
-
- if len(answers) > 0 {
- builder.WriteString("Answer:\n")
- for _, ans := range answers {
- builder.WriteString("- ")
- builder.WriteString(ans)
- builder.WriteString("\n")
- }
- }
-
- return strings.TrimSpace(builder.String())
-}
-
-// expandShortContextWithNeighbors expands the short context with neighbors
-func (p *PluginMerge) expandShortContextWithNeighbors(
- ctx context.Context,
- chatManage *types.ChatManage,
- results []*types.SearchResult,
-) []*types.SearchResult {
- const (
- minLen = 350
- maxLen = 850
- )
-
- if len(results) == 0 || p.chunkRepo == nil {
- return results
- }
-
- tenantID, _ := types.TenantIDFromContext(ctx)
- if tenantID == 0 && chatManage != nil {
- tenantID = chatManage.TenantID
- }
- if tenantID == 0 {
- pipelineWarn(ctx, "Merge", "expand_skip", map[string]interface{}{
- "reason": "missing_tenant",
- })
- return results
- }
-
- type targetInfo struct {
- result *types.SearchResult
- }
-
- targets := make([]targetInfo, 0)
- baseIDsSet := make(map[string]struct{})
-
- for _, r := range results {
- if r == nil || r.ID == "" || r.Content == "" {
- continue
- }
- if r.ChunkType != string(types.ChunkTypeText) {
- continue
- }
- if runeLen(r.Content) >= minLen {
- continue
- }
- targets = append(targets, targetInfo{result: r})
- baseIDsSet[r.ID] = struct{}{}
- pipelineInfo(ctx, "Merge", "need_expand", map[string]interface{}{
- "chunk_id": r.ID,
- "content": r.Content,
- "chunk_type": r.ChunkType,
- "len": runeLen(r.Content),
- })
- }
-
- if len(targets) == 0 {
- return results
- }
-
- baseIDs := make([]string, 0, len(baseIDsSet))
- for id := range baseIDsSet {
- baseIDs = append(baseIDs, id)
- }
-
- chunkMap := make(map[string]*types.Chunk, len(baseIDs))
- chunks, err := p.chunkRepo.ListChunksByID(ctx, tenantID, baseIDs)
- if err != nil {
- pipelineWarn(ctx, "Merge", "expand_list_base_failed", map[string]interface{}{
- "error": err.Error(),
- })
- return results
- }
- for _, chunk := range chunks {
- chunkMap[chunk.ID] = chunk
- }
-
- neighborIDsSet := make(map[string]struct{})
- for _, chunk := range chunkMap {
- if chunk == nil {
- continue
- }
- if chunk.PreChunkID != "" {
- if _, exists := chunkMap[chunk.PreChunkID]; !exists {
- neighborIDsSet[chunk.PreChunkID] = struct{}{}
- }
- }
- if chunk.NextChunkID != "" {
- if _, exists := chunkMap[chunk.NextChunkID]; !exists {
- neighborIDsSet[chunk.NextChunkID] = struct{}{}
- }
- }
- }
-
- if len(neighborIDsSet) > 0 {
- neighborIDs := make([]string, 0, len(neighborIDsSet))
- for id := range neighborIDsSet {
- neighborIDs = append(neighborIDs, id)
- }
- neighbors, err := p.chunkRepo.ListChunksByID(ctx, tenantID, neighborIDs)
- if err != nil {
- pipelineWarn(ctx, "Merge", "expand_list_neighbor_failed", map[string]interface{}{
- "error": err.Error(),
- })
- } else {
- for _, chunk := range neighbors {
- chunkMap[chunk.ID] = chunk
- pipelineInfo(ctx, "Merge", "expand_list_neighbor_success", map[string]interface{}{
- "neighbor_chunk_id": chunk.ID,
- "neighbor_content": chunk.Content,
- "neighbor_chunk_type": chunk.ChunkType,
- "neighbor_len": runeLen(chunk.Content),
- })
- }
- }
- }
-
- for _, target := range targets {
- res := target.result
- p.fetchChunksIfMissing(ctx, tenantID, chunkMap, res.ID)
- baseChunk := chunkMap[res.ID]
- if baseChunk == nil || baseChunk.Content == "" || baseChunk.ChunkType != types.ChunkTypeText {
- continue
- }
-
- prevContent := ""
- nextContent := ""
- prevIDs := []string{}
- nextIDs := []string{}
-
- prevCursor := baseChunk.PreChunkID
- nextCursor := baseChunk.NextChunkID
-
- p.fetchChunksIfMissing(ctx, tenantID, chunkMap, prevCursor, nextCursor)
-
- if prevCursor != "" {
- if prevChunk := chunkMap[prevCursor]; prevChunk != nil && prevChunk.KnowledgeID == baseChunk.KnowledgeID {
- prevContent = prevChunk.Content
- prevIDs = append(prevIDs, prevChunk.ID)
- prevCursor = prevChunk.PreChunkID
- } else {
- prevCursor = ""
- }
- }
-
- if nextCursor != "" {
- if nextChunk := chunkMap[nextCursor]; nextChunk != nil && nextChunk.KnowledgeID == baseChunk.KnowledgeID {
- nextContent = nextChunk.Content
- nextIDs = append(nextIDs, nextChunk.ID)
- nextCursor = nextChunk.NextChunkID
- } else {
- nextCursor = ""
- }
- }
-
- var merged string
- for {
- merged = mergeOrderedContent(prevContent, baseChunk.Content, nextContent, maxLen)
- if merged == "" {
- break
- }
- if runeLen(merged) >= minLen {
- break
- }
- if prevCursor == "" && nextCursor == "" {
- break
- }
-
- expanded := false
- if prevCursor != "" {
- p.fetchChunksIfMissing(ctx, tenantID, chunkMap, prevCursor)
- if prevChunk := chunkMap[prevCursor]; prevChunk != nil &&
- prevChunk.KnowledgeID == baseChunk.KnowledgeID {
- prevContent = concatNoOverlap(prevChunk.Content, prevContent)
- prevIDs = append([]string{prevChunk.ID}, prevIDs...)
- prevCursor = prevChunk.PreChunkID
- expanded = true
- } else {
- prevCursor = ""
- }
- }
-
- merged = mergeOrderedContent(prevContent, baseChunk.Content, nextContent, maxLen)
- if runeLen(merged) >= minLen {
- break
- }
-
- if nextCursor != "" {
- p.fetchChunksIfMissing(ctx, tenantID, chunkMap, nextCursor)
- if nextChunk := chunkMap[nextCursor]; nextChunk != nil &&
- nextChunk.KnowledgeID == baseChunk.KnowledgeID {
- nextContent = concatNoOverlap(nextContent, nextChunk.Content)
- nextIDs = append(nextIDs, nextChunk.ID)
- nextCursor = nextChunk.NextChunkID
- expanded = true
- } else {
- nextCursor = ""
- }
- }
-
- if !expanded {
- break
- }
- }
-
- if merged == "" {
- continue
- }
-
- beforeLen := runeLen(res.Content)
- res.Content = merged
-
- for _, id := range prevIDs {
- if id != "" && !containsID(res.SubChunkID, id) {
- res.SubChunkID = append(res.SubChunkID, id)
- }
- }
- for _, id := range nextIDs {
- if id != "" && !containsID(res.SubChunkID, id) {
- res.SubChunkID = append(res.SubChunkID, id)
- }
- }
-
- if prevContent != "" {
- res.StartAt = baseChunk.StartAt - runeLen(prevContent)
- if res.StartAt < 0 {
- res.StartAt = 0
- }
- }
- res.EndAt = res.StartAt + runeLen(res.Content)
-
- pipelineInfo(ctx, "Merge", "expand_short_chunk", map[string]interface{}{
- "chunk_id": res.ID,
- "prev_ids": prevIDs,
- "next_ids": nextIDs,
- "before_len": beforeLen,
- "after_len": runeLen(res.Content),
- "base_content": baseChunk.Content,
- "after_content": res.Content,
- "chunk_type": res.ChunkType,
- "remaining_prev": prevCursor,
- "remaining_next": nextCursor,
- })
- }
-
- return results
-}
-
-// runeLen returns the length of a string in runes
-func runeLen(s string) int {
- return len([]rune(s))
-}
-
-// mergeOrderedContent merges ordered content
-func mergeOrderedContent(prev, base, next string, maxLen int) string {
- content := base
- if prev != "" {
- content = concatNoOverlap(prev, content)
- }
- if next != "" {
- content = concatNoOverlap(content, next)
- }
- runes := []rune(content)
- if len(runes) > maxLen {
- return string(runes[:maxLen])
- }
- return content
-}
-
-// concatNoOverlap concatenates two strings, removing potential overlapping prefix/suffix
-func concatNoOverlap(a, b string) string {
- if a == "" {
- return b
- }
- if b == "" {
- return a
- }
-
- ar := []rune(a)
- br := []rune(b)
- maxOverlap := minInt(len(ar), len(br))
- for k := maxOverlap; k > 0; k-- {
- if string(ar[len(ar)-k:]) == string(br[:k]) {
- return string(ar) + string(br[k:])
- }
- }
- return string(ar) + string(br)
-}
-
-func minInt(a, b int) int {
- if a < b {
- return a
- }
- return b
-}
-
-func containsID(ids []string, target string) bool {
- for _, id := range ids {
- if id == target {
- return true
- }
- }
- return false
-}
-
-func (p *PluginMerge) fetchChunksIfMissing(
- ctx context.Context,
- tenantID uint64,
- chunkMap map[string]*types.Chunk,
- chunkIDs ...string,
-) {
- missing := make([]string, 0, len(chunkIDs))
- for _, id := range chunkIDs {
- if id == "" {
- continue
- }
- if _, exists := chunkMap[id]; !exists {
- missing = append(missing, id)
- }
- }
- if len(missing) == 0 {
- return
- }
-
- chunks, err := p.chunkRepo.ListChunksByID(ctx, tenantID, missing)
- if err != nil {
- pipelineWarn(ctx, "Merge", "expand_fetch_missing_failed", map[string]interface{}{
- "missing_cnt": len(missing),
- "error": err.Error(),
- })
- }
-
- found := make(map[string]struct{}, len(chunks))
- for _, chunk := range chunks {
- chunkMap[chunk.ID] = chunk
- found[chunk.ID] = struct{}{}
- }
-
- for _, id := range missing {
- if _, ok := found[id]; !ok {
- chunkMap[id] = nil
- }
- }
-}
diff --git a/internal/application/service/chat_pipline/merge_expand.go b/internal/application/service/chat_pipline/merge_expand.go
new file mode 100644
index 00000000..7b61bb91
--- /dev/null
+++ b/internal/application/service/chat_pipline/merge_expand.go
@@ -0,0 +1,349 @@
+package chatpipline
+
+import (
+ "context"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// expandShortContextWithNeighbors expands the short context with neighbors
+func (p *PluginMerge) expandShortContextWithNeighbors(
+ ctx context.Context,
+ chatManage *types.ChatManage,
+ results []*types.SearchResult,
+) []*types.SearchResult {
+ const (
+ minLen = 350
+ maxLen = 850
+ )
+
+ if len(results) == 0 || p.chunkRepo == nil {
+ return results
+ }
+
+ tenantID, _ := types.TenantIDFromContext(ctx)
+ if tenantID == 0 && chatManage != nil {
+ tenantID = chatManage.TenantID
+ }
+ if tenantID == 0 {
+ pipelineWarn(ctx, "Merge", "expand_skip", map[string]interface{}{
+ "reason": "missing_tenant",
+ })
+ return results
+ }
+
+ type targetInfo struct {
+ result *types.SearchResult
+ }
+
+ targets := make([]targetInfo, 0)
+ baseIDsSet := make(map[string]struct{})
+
+ for _, r := range results {
+ if r == nil || r.ID == "" || r.Content == "" {
+ continue
+ }
+ if r.ChunkType != string(types.ChunkTypeText) {
+ continue
+ }
+ if runeLen(r.Content) >= minLen {
+ continue
+ }
+ targets = append(targets, targetInfo{result: r})
+ baseIDsSet[r.ID] = struct{}{}
+ pipelineInfo(ctx, "Merge", "need_expand", map[string]interface{}{
+ "chunk_id": r.ID,
+ "content": r.Content,
+ "chunk_type": r.ChunkType,
+ "len": runeLen(r.Content),
+ })
+ }
+
+ if len(targets) == 0 {
+ return results
+ }
+
+ baseIDs := make([]string, 0, len(baseIDsSet))
+ for id := range baseIDsSet {
+ baseIDs = append(baseIDs, id)
+ }
+
+ chunkMap := make(map[string]*types.Chunk, len(baseIDs))
+ chunks, err := p.chunkRepo.ListChunksByID(ctx, tenantID, baseIDs)
+ if err != nil {
+ pipelineWarn(ctx, "Merge", "expand_list_base_failed", map[string]interface{}{
+ "error": err.Error(),
+ })
+ return results
+ }
+ for _, chunk := range chunks {
+ chunkMap[chunk.ID] = chunk
+ }
+
+ neighborIDsSet := make(map[string]struct{})
+ for _, chunk := range chunkMap {
+ if chunk == nil {
+ continue
+ }
+ if chunk.PreChunkID != "" {
+ if _, exists := chunkMap[chunk.PreChunkID]; !exists {
+ neighborIDsSet[chunk.PreChunkID] = struct{}{}
+ }
+ }
+ if chunk.NextChunkID != "" {
+ if _, exists := chunkMap[chunk.NextChunkID]; !exists {
+ neighborIDsSet[chunk.NextChunkID] = struct{}{}
+ }
+ }
+ }
+
+ if len(neighborIDsSet) > 0 {
+ neighborIDs := make([]string, 0, len(neighborIDsSet))
+ for id := range neighborIDsSet {
+ neighborIDs = append(neighborIDs, id)
+ }
+ neighbors, err := p.chunkRepo.ListChunksByID(ctx, tenantID, neighborIDs)
+ if err != nil {
+ pipelineWarn(ctx, "Merge", "expand_list_neighbor_failed", map[string]interface{}{
+ "error": err.Error(),
+ })
+ } else {
+ for _, chunk := range neighbors {
+ chunkMap[chunk.ID] = chunk
+ pipelineInfo(ctx, "Merge", "expand_list_neighbor_success", map[string]interface{}{
+ "neighbor_chunk_id": chunk.ID,
+ "neighbor_content": chunk.Content,
+ "neighbor_chunk_type": chunk.ChunkType,
+ "neighbor_len": runeLen(chunk.Content),
+ })
+ }
+ }
+ }
+
+ for _, target := range targets {
+ res := target.result
+ p.fetchChunksIfMissing(ctx, tenantID, chunkMap, res.ID)
+ baseChunk := chunkMap[res.ID]
+ if baseChunk == nil || baseChunk.Content == "" || baseChunk.ChunkType != types.ChunkTypeText {
+ continue
+ }
+
+ prevContent := ""
+ nextContent := ""
+ prevIDs := []string{}
+ nextIDs := []string{}
+
+ prevCursor := baseChunk.PreChunkID
+ nextCursor := baseChunk.NextChunkID
+
+ p.fetchChunksIfMissing(ctx, tenantID, chunkMap, prevCursor, nextCursor)
+
+ if prevCursor != "" {
+ if prevChunk := chunkMap[prevCursor]; prevChunk != nil && prevChunk.KnowledgeID == baseChunk.KnowledgeID {
+ prevContent = prevChunk.Content
+ prevIDs = append(prevIDs, prevChunk.ID)
+ prevCursor = prevChunk.PreChunkID
+ } else {
+ prevCursor = ""
+ }
+ }
+
+ if nextCursor != "" {
+ if nextChunk := chunkMap[nextCursor]; nextChunk != nil && nextChunk.KnowledgeID == baseChunk.KnowledgeID {
+ nextContent = nextChunk.Content
+ nextIDs = append(nextIDs, nextChunk.ID)
+ nextCursor = nextChunk.NextChunkID
+ } else {
+ nextCursor = ""
+ }
+ }
+
+ var merged string
+ for {
+ merged = mergeOrderedContent(prevContent, baseChunk.Content, nextContent, maxLen)
+ if merged == "" {
+ break
+ }
+ if runeLen(merged) >= minLen {
+ break
+ }
+ if prevCursor == "" && nextCursor == "" {
+ break
+ }
+
+ expanded := false
+ if prevCursor != "" {
+ p.fetchChunksIfMissing(ctx, tenantID, chunkMap, prevCursor)
+ if prevChunk := chunkMap[prevCursor]; prevChunk != nil &&
+ prevChunk.KnowledgeID == baseChunk.KnowledgeID {
+ prevContent = concatNoOverlap(prevChunk.Content, prevContent)
+ prevIDs = append([]string{prevChunk.ID}, prevIDs...)
+ prevCursor = prevChunk.PreChunkID
+ expanded = true
+ } else {
+ prevCursor = ""
+ }
+ }
+
+ merged = mergeOrderedContent(prevContent, baseChunk.Content, nextContent, maxLen)
+ if runeLen(merged) >= minLen {
+ break
+ }
+
+ if nextCursor != "" {
+ p.fetchChunksIfMissing(ctx, tenantID, chunkMap, nextCursor)
+ if nextChunk := chunkMap[nextCursor]; nextChunk != nil &&
+ nextChunk.KnowledgeID == baseChunk.KnowledgeID {
+ nextContent = concatNoOverlap(nextContent, nextChunk.Content)
+ nextIDs = append(nextIDs, nextChunk.ID)
+ nextCursor = nextChunk.NextChunkID
+ expanded = true
+ } else {
+ nextCursor = ""
+ }
+ }
+
+ if !expanded {
+ break
+ }
+ }
+
+ if merged == "" {
+ continue
+ }
+
+ beforeLen := runeLen(res.Content)
+ res.Content = merged
+
+ for _, id := range prevIDs {
+ if id != "" && !containsID(res.SubChunkID, id) {
+ res.SubChunkID = append(res.SubChunkID, id)
+ }
+ }
+ for _, id := range nextIDs {
+ if id != "" && !containsID(res.SubChunkID, id) {
+ res.SubChunkID = append(res.SubChunkID, id)
+ }
+ }
+
+ if prevContent != "" {
+ res.StartAt = baseChunk.StartAt - runeLen(prevContent)
+ if res.StartAt < 0 {
+ res.StartAt = 0
+ }
+ }
+ res.EndAt = res.StartAt + runeLen(res.Content)
+
+ pipelineInfo(ctx, "Merge", "expand_short_chunk", map[string]interface{}{
+ "chunk_id": res.ID,
+ "prev_ids": prevIDs,
+ "next_ids": nextIDs,
+ "before_len": beforeLen,
+ "after_len": runeLen(res.Content),
+ "base_content": baseChunk.Content,
+ "after_content": res.Content,
+ "chunk_type": res.ChunkType,
+ "remaining_prev": prevCursor,
+ "remaining_next": nextCursor,
+ })
+ }
+
+ return results
+}
+
+// runeLen returns the length of a string in runes
+func runeLen(s string) int {
+ return len([]rune(s))
+}
+
+// mergeOrderedContent merges ordered content
+func mergeOrderedContent(prev, base, next string, maxLen int) string {
+ content := base
+ if prev != "" {
+ content = concatNoOverlap(prev, content)
+ }
+ if next != "" {
+ content = concatNoOverlap(content, next)
+ }
+ runes := []rune(content)
+ if len(runes) > maxLen {
+ return string(runes[:maxLen])
+ }
+ return content
+}
+
+// concatNoOverlap concatenates two strings, removing potential overlapping prefix/suffix
+func concatNoOverlap(a, b string) string {
+ if a == "" {
+ return b
+ }
+ if b == "" {
+ return a
+ }
+
+ ar := []rune(a)
+ br := []rune(b)
+ maxOverlap := minInt(len(ar), len(br))
+ for k := maxOverlap; k > 0; k-- {
+ if string(ar[len(ar)-k:]) == string(br[:k]) {
+ return string(ar) + string(br[k:])
+ }
+ }
+ return string(ar) + string(br)
+}
+
+func minInt(a, b int) int {
+ if a < b {
+ return a
+ }
+ return b
+}
+
+func containsID(ids []string, target string) bool {
+ for _, id := range ids {
+ if id == target {
+ return true
+ }
+ }
+ return false
+}
+
+func (p *PluginMerge) fetchChunksIfMissing(
+ ctx context.Context,
+ tenantID uint64,
+ chunkMap map[string]*types.Chunk,
+ chunkIDs ...string,
+) {
+ missing := make([]string, 0, len(chunkIDs))
+ for _, id := range chunkIDs {
+ if id == "" {
+ continue
+ }
+ if _, exists := chunkMap[id]; !exists {
+ missing = append(missing, id)
+ }
+ }
+ if len(missing) == 0 {
+ return
+ }
+
+ chunks, err := p.chunkRepo.ListChunksByID(ctx, tenantID, missing)
+ if err != nil {
+ pipelineWarn(ctx, "Merge", "expand_fetch_missing_failed", map[string]interface{}{
+ "missing_cnt": len(missing),
+ "error": err.Error(),
+ })
+ }
+
+ found := make(map[string]struct{}, len(chunks))
+ for _, chunk := range chunks {
+ chunkMap[chunk.ID] = chunk
+ found[chunk.ID] = struct{}{}
+ }
+
+ for _, id := range missing {
+ if _, ok := found[id]; !ok {
+ chunkMap[id] = nil
+ }
+ }
+}
diff --git a/internal/application/service/chat_pipline/merge_faq.go b/internal/application/service/chat_pipline/merge_faq.go
new file mode 100644
index 00000000..8bddbec8
--- /dev/null
+++ b/internal/application/service/chat_pipline/merge_faq.go
@@ -0,0 +1,134 @@
+package chatpipline
+
+import (
+ "context"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// populateFAQAnswers populates FAQ answers for the search results
+func (p *PluginMerge) populateFAQAnswers(
+ ctx context.Context,
+ chatManage *types.ChatManage,
+ results []*types.SearchResult,
+) []*types.SearchResult {
+ if len(results) == 0 || p.chunkRepo == nil {
+ return results
+ }
+
+ tenantID, _ := types.TenantIDFromContext(ctx)
+ if tenantID == 0 && chatManage != nil {
+ tenantID = chatManage.TenantID
+ }
+ if tenantID == 0 {
+ pipelineWarn(ctx, "Merge", "faq_enrich_skip", map[string]interface{}{
+ "reason": "missing_tenant",
+ })
+ return results
+ }
+
+ chunkResultMap := make(map[string][]*types.SearchResult)
+ chunkIDSet := make(map[string]struct{})
+ for _, r := range results {
+ if r == nil || r.ID == "" {
+ continue
+ }
+ if r.ChunkType != string(types.ChunkTypeFAQ) {
+ continue
+ }
+ chunkResultMap[r.ID] = append(chunkResultMap[r.ID], r)
+ if _, exists := chunkIDSet[r.ID]; !exists {
+ chunkIDSet[r.ID] = struct{}{}
+ }
+ }
+
+ if len(chunkIDSet) == 0 {
+ return results
+ }
+
+ chunkIDs := make([]string, 0, len(chunkIDSet))
+ for id := range chunkIDSet {
+ chunkIDs = append(chunkIDs, id)
+ }
+
+ chunks, err := p.chunkRepo.ListChunksByID(ctx, tenantID, chunkIDs)
+ if err != nil {
+ pipelineWarn(ctx, "Merge", "faq_chunk_fetch_failed", map[string]interface{}{
+ "error": err.Error(),
+ })
+ return results
+ }
+
+ updated := 0
+ for _, chunk := range chunks {
+ if chunk == nil {
+ continue
+ }
+ meta, err := chunk.FAQMetadata()
+ if err != nil || meta == nil {
+ if err != nil {
+ pipelineWarn(ctx, "Merge", "faq_metadata_parse_failed", map[string]interface{}{
+ "chunk_id": chunk.ID,
+ "error": err.Error(),
+ })
+ }
+ continue
+ }
+ content := buildFAQAnswerContent(meta)
+ if content == "" {
+ continue
+ }
+ for _, r := range chunkResultMap[chunk.ID] {
+ if r == nil {
+ continue
+ }
+ r.Content = content
+ updated++
+ }
+ }
+
+ if updated > 0 {
+ pipelineInfo(ctx, "Merge", "faq_content_enriched", map[string]interface{}{
+ "chunk_cnt": updated,
+ })
+ }
+ return results
+}
+
+// buildFAQAnswerContent builds the content of a FAQ answer
+func buildFAQAnswerContent(meta *types.FAQChunkMetadata) string {
+ if meta == nil {
+ return ""
+ }
+
+ question := strings.TrimSpace(meta.StandardQuestion)
+ answers := make([]string, 0, len(meta.Answers))
+ for _, ans := range meta.Answers {
+ if trimmed := strings.TrimSpace(ans); trimmed != "" {
+ answers = append(answers, trimmed)
+ }
+ }
+
+ if question == "" && len(answers) == 0 {
+ return ""
+ }
+
+ var builder strings.Builder
+ if question != "" {
+ builder.WriteString("Q: ")
+ builder.WriteString(question)
+ builder.WriteString("\n")
+ }
+
+ if len(answers) > 0 {
+ builder.WriteString("Answer:\n")
+ for _, ans := range answers {
+ builder.WriteString("- ")
+ builder.WriteString(ans)
+ builder.WriteString("\n")
+ }
+ }
+
+ return strings.TrimSpace(builder.String())
+}
diff --git a/internal/application/service/chat_pipline/merge_history.go b/internal/application/service/chat_pipline/merge_history.go
new file mode 100644
index 00000000..0c9ed355
--- /dev/null
+++ b/internal/application/service/chat_pipline/merge_history.go
@@ -0,0 +1,85 @@
+package chatpipline
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/searchutil"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// filterHistoryResults retrieves history references and filters them by
+// textual similarity to the current query. Only references that are above
+// a Jaccard similarity threshold are kept, and their scores are discounted
+// to reflect that they were not directly retrieved for the current query.
+// Results already present in currentResults (by chunk ID) are excluded.
+func filterHistoryResults(
+ ctx context.Context,
+ chatManage *types.ChatManage,
+ currentResults []*types.SearchResult,
+) []*types.SearchResult {
+ const (
+ // minSimilarity is the minimum Jaccard similarity between the current
+ // query and a history chunk's content for it to be injected.
+ minSimilarity = 0.15
+ // historyScoreDiscount reduces the original score of history results
+ // to rank them below freshly-retrieved results of similar relevance.
+ historyScoreDiscount = 0.6
+ // maxHistoryResults caps the number of history results injected to
+ // avoid overwhelming the context with stale references.
+ maxHistoryResults = 3
+ )
+
+ raw := getSearchResultFromHistory(chatManage)
+ if len(raw) == 0 {
+ return nil
+ }
+
+ // Build a set of chunk IDs already in current results for fast dedup
+ existingIDs := make(map[string]struct{}, len(currentResults))
+ for _, r := range currentResults {
+ existingIDs[r.ID] = struct{}{}
+ }
+
+ // Use RewriteQuery if available (it's the cleaned-up retrieval query),
+ // otherwise fall back to the original query.
+ query := chatManage.RewriteQuery
+ if query == "" {
+ query = chatManage.Query
+ }
+ queryTokens := searchutil.TokenizeSimple(query)
+
+ var filtered []*types.SearchResult
+ for _, r := range raw {
+ if _, exists := existingIDs[r.ID]; exists {
+ continue
+ }
+ contentTokens := searchutil.TokenizeSimple(r.Content)
+ sim := searchutil.Jaccard(queryTokens, contentTokens)
+ if sim < minSimilarity {
+ pipelineInfo(ctx, "Merge", "history_filter_drop", map[string]interface{}{
+ "chunk_id": r.ID,
+ "similarity": sim,
+ })
+ continue
+ }
+ r.MatchType = types.MatchTypeHistory
+ r.Score = r.Score * historyScoreDiscount
+ r.Metadata = ensureMetadata(r.Metadata)
+ r.Metadata["history_similarity"] = strings.TrimRight(strings.TrimRight(
+ fmt.Sprintf("%.4f", sim), "0"), ".")
+ filtered = append(filtered, r)
+
+ pipelineInfo(ctx, "Merge", "history_filter_keep", map[string]interface{}{
+ "chunk_id": r.ID,
+ "similarity": sim,
+ "new_score": r.Score,
+ })
+
+ if len(filtered) >= maxHistoryResults {
+ break
+ }
+ }
+ return filtered
+}
diff --git a/internal/application/service/chat_pipline/merge_overlap.go b/internal/application/service/chat_pipline/merge_overlap.go
new file mode 100644
index 00000000..4bcac2a4
--- /dev/null
+++ b/internal/application/service/chat_pipline/merge_overlap.go
@@ -0,0 +1,128 @@
+package chatpipline
+
+import (
+ "context"
+ "encoding/json"
+ "sort"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// mergeOverlappingChunks merges chunks with overlapping or adjacent StartAt/EndAt
+// ranges within a single knowledge source group. Chunks MUST be pre-sorted by
+// StartAt ascending, EndAt ascending. The highest score among merged chunks is kept.
+func (p *PluginMerge) mergeOverlappingChunks(
+ ctx context.Context,
+ knowledgeID string,
+ chunks []*types.SearchResult,
+) []*types.SearchResult {
+ if len(chunks) == 0 {
+ return nil
+ }
+
+ merged := []*types.SearchResult{chunks[0]}
+ for i := 1; i < len(chunks); i++ {
+ lastChunk := merged[len(merged)-1]
+
+ // Non-overlapping: add as a new entry
+ if chunks[i].StartAt > lastChunk.EndAt {
+ merged = append(merged, chunks[i])
+ continue
+ }
+
+ // Partial overlap: append the non-overlapping suffix
+ if chunks[i].EndAt > lastChunk.EndAt {
+ contentRunes := []rune(chunks[i].Content)
+ offset := len(contentRunes) - (chunks[i].EndAt - lastChunk.EndAt)
+ lastChunk.Content = lastChunk.Content + string(contentRunes[offset:])
+ lastChunk.EndAt = chunks[i].EndAt
+ lastChunk.SubChunkID = append(lastChunk.SubChunkID, chunks[i].ID)
+
+ if err := mergeImageInfo(ctx, lastChunk, chunks[i]); err != nil {
+ pipelineWarn(ctx, "Merge", "image_merge", map[string]interface{}{
+ "knowledge_id": knowledgeID,
+ "error": err.Error(),
+ })
+ }
+ } else {
+ // Fully contained: track the subsumed chunk and merge its ImageInfo
+ if !containsID(lastChunk.SubChunkID, chunks[i].ID) {
+ lastChunk.SubChunkID = append(lastChunk.SubChunkID, chunks[i].ID)
+ }
+ if err := mergeImageInfo(ctx, lastChunk, chunks[i]); err != nil {
+ pipelineWarn(ctx, "Merge", "image_merge_contained", map[string]interface{}{
+ "knowledge_id": knowledgeID,
+ "error": err.Error(),
+ })
+ }
+ }
+
+ // Keep the higher score
+ if chunks[i].Score > lastChunk.Score {
+ lastChunk.Score = chunks[i].Score
+ }
+ }
+
+ // Sort merged chunks by score (highest first)
+ sort.Slice(merged, func(i, j int) bool {
+ return merged[i].Score > merged[j].Score
+ })
+
+ return merged
+}
+
+// mergeImageInfo merges ImageInfo from source into target, deduplicating by URL.
+func mergeImageInfo(ctx context.Context, target *types.SearchResult, source *types.SearchResult) error {
+ if source.ImageInfo == "" {
+ return nil
+ }
+
+ var sourceImageInfos []types.ImageInfo
+ if err := json.Unmarshal([]byte(source.ImageInfo), &sourceImageInfos); err != nil {
+ pipelineWarn(ctx, "Merge", "image_unmarshal_source", map[string]interface{}{
+ "error": err.Error(),
+ })
+ return err
+ }
+
+ if len(sourceImageInfos) == 0 {
+ return nil
+ }
+
+ var targetImageInfos []types.ImageInfo
+ if target.ImageInfo != "" {
+ if err := json.Unmarshal([]byte(target.ImageInfo), &targetImageInfos); err != nil {
+ pipelineWarn(ctx, "Merge", "image_unmarshal_target", map[string]interface{}{
+ "error": err.Error(),
+ })
+ target.ImageInfo = source.ImageInfo
+ return nil
+ }
+ }
+
+ targetImageInfos = append(targetImageInfos, sourceImageInfos...)
+
+ uniqueMap := make(map[string]bool)
+ uniqueImageInfos := make([]types.ImageInfo, 0, len(targetImageInfos))
+
+ for _, imgInfo := range targetImageInfos {
+ if imgInfo.URL != "" && !uniqueMap[imgInfo.URL] {
+ uniqueMap[imgInfo.URL] = true
+ uniqueImageInfos = append(uniqueImageInfos, imgInfo)
+ }
+ }
+
+ mergedImageInfoJSON, err := json.Marshal(uniqueImageInfos)
+ if err != nil {
+ pipelineWarn(ctx, "Merge", "image_marshal", map[string]interface{}{
+ "error": err.Error(),
+ })
+ return err
+ }
+
+ target.ImageInfo = string(mergedImageInfoJSON)
+ pipelineInfo(ctx, "Merge", "image_merged", map[string]interface{}{
+ "image_refs": len(uniqueImageInfos),
+ })
+ return nil
+}
diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.go
index af7c8082..6233baff 100644
--- a/internal/application/service/knowledge.go
+++ b/internal/application/service/knowledge.go
@@ -7484,7 +7484,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{}
}
diff --git a/internal/application/service/knowledgebase.go b/internal/application/service/knowledgebase.go
index 95a236f1..6661ab32 100644
--- a/internal/application/service/knowledgebase.go
+++ b/internal/application/service/knowledgebase.go
@@ -4,13 +4,10 @@ import (
"context"
"encoding/json"
"errors"
- "slices"
- "strings"
"time"
"github.com/Tencent/WeKnora/internal/application/service/retriever"
"github.com/Tencent/WeKnora/internal/logger"
- "github.com/Tencent/WeKnora/internal/models/embedding"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/google/uuid"
@@ -604,991 +601,3 @@ func (s *knowledgeBaseService) CopyKnowledgeBase(ctx context.Context,
}
return sourceKB, targetKB, nil
}
-
-// GetQueryEmbedding computes the query embedding using the embedding model
-// associated with the given knowledge base. Callers can pre-compute and reuse
-// the result across multiple KBs that share the same embedding model to avoid
-// redundant embedding API calls.
-func (s *knowledgeBaseService) GetQueryEmbedding(ctx context.Context, kbID string, queryText string) ([]float32, error) {
- kb, err := s.repo.GetKnowledgeBaseByID(ctx, kbID)
- if err != nil {
- return nil, err
- }
-
- currentTenantID := types.MustTenantIDFromContext(ctx)
- var embeddingModel embedding.Embedder
-
- if kb.TenantID != currentTenantID {
- embeddingModel, err = s.modelService.GetEmbeddingModelForTenant(ctx, kb.EmbeddingModelID, kb.TenantID)
- } else {
- embeddingModel, err = s.modelService.GetEmbeddingModel(ctx, kb.EmbeddingModelID)
- }
- if err != nil {
- logger.Errorf(ctx, "GetQueryEmbedding: failed to get embedding model %s: %v", kb.EmbeddingModelID, err)
- return nil, err
- }
-
- return embeddingModel.Embed(ctx, queryText)
-}
-
-// ResolveEmbeddingModelKeys resolves embedding model IDs to their actual model
-// identity key (name + endpoint). KBs using the same underlying model across
-// different tenants will share the same key, enabling optimal grouping.
-func (s *knowledgeBaseService) ResolveEmbeddingModelKeys(ctx context.Context, kbs []*types.KnowledgeBase) map[string]string {
- type modelRef struct {
- ModelID string
- TenantID uint64
- }
-
- // Deduplicate model references
- uniqueRefs := make(map[modelRef]struct{})
- kbRefs := make(map[string]modelRef, len(kbs))
- for _, kb := range kbs {
- ref := modelRef{ModelID: kb.EmbeddingModelID, TenantID: kb.TenantID}
- uniqueRefs[ref] = struct{}{}
- kbRefs[kb.ID] = ref
- }
-
- // Resolve each unique (modelID, tenantID) to a model identity key
- resolvedKeys := make(map[modelRef]string, len(uniqueRefs))
- for ref := range uniqueRefs {
- tenantCtx := context.WithValue(ctx, types.TenantIDContextKey, ref.TenantID)
- model, err := s.modelService.GetModelByID(tenantCtx, ref.ModelID)
- if err != nil || model == nil {
- logger.Warnf(ctx, "ResolveEmbeddingModelKeys: cannot resolve model %s for tenant %d: %v", ref.ModelID, ref.TenantID, err)
- resolvedKeys[ref] = ref.ModelID
- continue
- }
- resolvedKeys[ref] = model.Name + "|" + model.Parameters.BaseURL
- }
-
- result := make(map[string]string, len(kbs))
- for _, kb := range kbs {
- result[kb.ID] = resolvedKeys[kbRefs[kb.ID]]
- }
- return result
-}
-
-// HybridSearch performs hybrid search, including vector retrieval and keyword retrieval.
-// When params.KnowledgeBaseIDs is set, those IDs are used for retrieval instead of `id`,
-// allowing a single call to span multiple KBs that share the same embedding model.
-func (s *knowledgeBaseService) HybridSearch(ctx context.Context,
- id string,
- params types.SearchParams,
-) ([]*types.SearchResult, error) {
- // Determine the set of KB IDs to search
- searchKBIDs := params.KnowledgeBaseIDs
- if len(searchKBIDs) == 0 {
- searchKBIDs = []string{id}
- }
-
- logger.Infof(ctx, "Hybrid search parameters, knowledge base IDs: %v, query text: %s", searchKBIDs, params.QueryText)
-
- tenantInfo, _ := types.TenantInfoFromContext(ctx)
- currentTenantID := types.MustTenantIDFromContext(ctx)
-
- // Create a composite retrieval engine with tenant's configured retrievers
- retrieveEngine, err := retriever.NewCompositeRetrieveEngine(s.retrieveEngine, tenantInfo.GetEffectiveEngines())
- if err != nil {
- logger.Errorf(ctx, "Failed to create retrieval engine: %v", err)
- return nil, err
- }
-
- var retrieveParams []types.RetrieveParams
- var embeddingModel embedding.Embedder
- var kb *types.KnowledgeBase
-
- kb, err = s.repo.GetKnowledgeBaseByID(ctx, id)
- if err != nil {
- logger.ErrorWithFields(ctx, err, map[string]interface{}{
- "knowledge_base_id": id,
- })
- return nil, err
- }
-
- // Use 5x over-retrieval to ensure sufficient candidates for RRF fusion and reranking.
- // Scale proportionally when searching multiple KBs to maintain per-KB recall quality.
- matchCount := max(params.MatchCount*5, 50) * len(searchKBIDs)
- if matchCount > 1000 {
- matchCount = 1000
- }
-
- // Add vector retrieval params if supported
- if retrieveEngine.SupportRetriever(types.VectorRetrieverType) && !params.DisableVectorMatch {
- logger.Info(ctx, "Vector retrieval supported, preparing vector retrieval parameters")
-
- var queryEmbedding []float32
-
- if len(params.QueryEmbedding) > 0 {
- queryEmbedding = params.QueryEmbedding
- logger.Infof(ctx, "Using pre-computed query embedding, vector length: %d", len(queryEmbedding))
- } else {
- logger.Infof(ctx, "Getting embedding model, model ID: %s", kb.EmbeddingModelID)
-
- // Check if this is a cross-tenant shared knowledge base
- // For shared KB, we must use the source tenant's embedding model to ensure vector compatibility
- if kb.TenantID != currentTenantID {
- logger.Infof(ctx, "Cross-tenant knowledge base detected, using source tenant's embedding model. KB tenant: %d, current tenant: %d", kb.TenantID, currentTenantID)
- embeddingModel, err = s.modelService.GetEmbeddingModelForTenant(ctx, kb.EmbeddingModelID, kb.TenantID)
- } else {
- embeddingModel, err = s.modelService.GetEmbeddingModel(ctx, kb.EmbeddingModelID)
- }
-
- if err != nil {
- logger.Errorf(ctx, "Failed to get embedding model, model ID: %s, error: %v", kb.EmbeddingModelID, err)
- return nil, err
- }
- logger.Infof(ctx, "Embedding model retrieved: %v", embeddingModel)
-
- logger.Info(ctx, "Starting to generate query embedding")
- queryEmbedding, err = embeddingModel.Embed(ctx, params.QueryText)
- if err != nil {
- logger.Errorf(ctx, "Failed to embed query text, query text: %s, error: %v", params.QueryText, err)
- return nil, err
- }
- logger.Infof(ctx, "Query embedding generated successfully, embedding vector length: %d", len(queryEmbedding))
- }
-
- vectorParams := types.RetrieveParams{
- Query: params.QueryText,
- Embedding: queryEmbedding,
- KnowledgeBaseIDs: searchKBIDs,
- TopK: matchCount,
- Threshold: params.VectorThreshold,
- RetrieverType: types.VectorRetrieverType,
- KnowledgeIDs: params.KnowledgeIDs,
- TagIDs: params.TagIDs,
- }
-
- // For FAQ knowledge base, use FAQ index
- if kb.Type == types.KnowledgeBaseTypeFAQ {
- vectorParams.KnowledgeType = types.KnowledgeTypeFAQ
- }
-
- retrieveParams = append(retrieveParams, vectorParams)
- logger.Info(ctx, "Vector retrieval parameters setup completed")
- }
-
- // Add keyword retrieval params if supported and not FAQ
- if retrieveEngine.SupportRetriever(types.KeywordsRetrieverType) && !params.DisableKeywordsMatch &&
- kb.Type != types.KnowledgeBaseTypeFAQ {
- logger.Info(ctx, "Keyword retrieval supported, preparing keyword retrieval parameters")
- retrieveParams = append(retrieveParams, types.RetrieveParams{
- Query: params.QueryText,
- KnowledgeBaseIDs: searchKBIDs,
- TopK: matchCount,
- Threshold: params.KeywordThreshold,
- RetrieverType: types.KeywordsRetrieverType,
- KnowledgeIDs: params.KnowledgeIDs,
- TagIDs: params.TagIDs,
- })
- logger.Info(ctx, "Keyword retrieval parameters setup completed")
- }
-
- if len(retrieveParams) == 0 {
- logger.Error(ctx, "No retrieval parameters available")
- return nil, errors.New("no retrieve params")
- }
-
- // Execute retrieval using the configured engines
- logger.Infof(ctx, "Starting retrieval, parameter count: %d", len(retrieveParams))
- retrieveResults, err := retrieveEngine.Retrieve(ctx, retrieveParams)
- if err != nil {
- logger.ErrorWithFields(ctx, err, map[string]interface{}{
- "knowledge_base_ids": searchKBIDs,
- "query_text": params.QueryText,
- })
- return nil, err
- }
-
- // Collect all results from different retrievers and deduplicate by chunk ID
- logger.Infof(ctx, "Processing retrieval results")
-
- // Separate results by retriever type for RRF fusion
- var vectorResults []*types.IndexWithScore
- var keywordResults []*types.IndexWithScore
- for _, retrieveResult := range retrieveResults {
- logger.Infof(ctx, "Retrieval results, engine: %v, retriever: %v, count: %v",
- retrieveResult.RetrieverEngineType,
- retrieveResult.RetrieverType,
- len(retrieveResult.Results),
- )
- if retrieveResult.RetrieverType == types.VectorRetrieverType {
- vectorResults = append(vectorResults, retrieveResult.Results...)
- } else {
- keywordResults = append(keywordResults, retrieveResult.Results...)
- }
- }
-
- // Early return if no results
- if len(vectorResults) == 0 && len(keywordResults) == 0 {
- logger.Info(ctx, "No search results found")
- return nil, nil
- }
- logger.Infof(ctx, "Result count before fusion: vector=%d, keyword=%d", len(vectorResults), len(keywordResults))
-
- var deduplicatedChunks []*types.IndexWithScore
-
- // If only vector results (no keyword results), keep original embedding scores
- // This is important for FAQ search which only uses vector retrieval
- if len(keywordResults) == 0 {
- logger.Info(ctx, "Only vector results, keeping original embedding scores")
- chunkInfoMap := make(map[string]*types.IndexWithScore)
- for _, r := range vectorResults {
- // Keep the highest score for each chunk (FAQ may have multiple similar questions)
- if existing, exists := chunkInfoMap[r.ChunkID]; !exists || r.Score > existing.Score {
- chunkInfoMap[r.ChunkID] = r
- }
- }
- deduplicatedChunks = make([]*types.IndexWithScore, 0, len(chunkInfoMap))
- for _, info := range chunkInfoMap {
- deduplicatedChunks = append(deduplicatedChunks, info)
- }
- slices.SortFunc(deduplicatedChunks, func(a, b *types.IndexWithScore) int {
- if a.Score > b.Score {
- return -1
- } else if a.Score < b.Score {
- return 1
- }
- return 0
- })
- logger.Infof(ctx, "Result count after deduplication: %d", len(deduplicatedChunks))
- } else {
- // Use RRF (Reciprocal Rank Fusion) to merge results from multiple retrievers
- // RRF score = sum(1 / (k + rank)) for each retriever where the chunk appears
- // k=60 is a common choice that works well in practice
- const rrfK = 60
-
- // Build rank maps for each retriever (already sorted by score from retriever)
- vectorRanks := make(map[string]int)
- for i, r := range vectorResults {
- if _, exists := vectorRanks[r.ChunkID]; !exists {
- vectorRanks[r.ChunkID] = i + 1 // 1-indexed rank
- }
- }
- keywordRanks := make(map[string]int)
- for i, r := range keywordResults {
- if _, exists := keywordRanks[r.ChunkID]; !exists {
- keywordRanks[r.ChunkID] = i + 1 // 1-indexed rank
- }
- }
-
- // Collect all unique chunks and compute RRF scores
- // Keep the highest score for each chunk from each retriever
- chunkInfoMap := make(map[string]*types.IndexWithScore)
- rrfScores := make(map[string]float64)
-
- // Process vector results - keep highest score per chunk
- for _, r := range vectorResults {
- if existing, exists := chunkInfoMap[r.ChunkID]; !exists || r.Score > existing.Score {
- chunkInfoMap[r.ChunkID] = r
- }
- }
- // Process keyword results - only add if not already from vector
- for _, r := range keywordResults {
- if _, exists := chunkInfoMap[r.ChunkID]; !exists {
- chunkInfoMap[r.ChunkID] = r
- }
- }
-
- // Compute weighted RRF scores (vector retrieval weighted higher for semantic relevance)
- const vectorWeight = 0.7
- const keywordWeight = 0.3
- for chunkID := range chunkInfoMap {
- rrfScore := 0.0
- if rank, ok := vectorRanks[chunkID]; ok {
- rrfScore += vectorWeight / float64(rrfK+rank)
- }
- if rank, ok := keywordRanks[chunkID]; ok {
- rrfScore += keywordWeight / float64(rrfK+rank)
- }
- rrfScores[chunkID] = rrfScore
- }
-
- // Convert to slice and sort by RRF score
- deduplicatedChunks = make([]*types.IndexWithScore, 0, len(chunkInfoMap))
- for chunkID, info := range chunkInfoMap {
- // Store RRF score in the Score field for downstream processing
- info.Score = rrfScores[chunkID]
- deduplicatedChunks = append(deduplicatedChunks, info)
- }
- slices.SortFunc(deduplicatedChunks, func(a, b *types.IndexWithScore) int {
- if a.Score > b.Score {
- return -1
- } else if a.Score < b.Score {
- return 1
- }
- return 0
- })
-
- logger.Infof(ctx, "Result count after RRF fusion: %d", len(deduplicatedChunks))
-
- // Log top results after RRF fusion for debugging
- for i, chunk := range deduplicatedChunks {
- if i < 15 {
- vRank, vOk := vectorRanks[chunk.ChunkID]
- kRank, kOk := keywordRanks[chunk.ChunkID]
- logger.Debugf(ctx, "RRF rank %d: chunk_id=%s, rrf_score=%.6f, vector_rank=%v(%v), keyword_rank=%v(%v)",
- i, chunk.ChunkID, chunk.Score, vRank, vOk, kRank, kOk)
- }
- }
- }
-
- kb.EnsureDefaults()
-
- // Check if we need iterative retrieval for FAQ with separate indexing
- // Only use iterative retrieval if we don't have enough unique chunks after first deduplication
- needsIterativeRetrieval := len(deduplicatedChunks) < params.MatchCount &&
- kb.Type == types.KnowledgeBaseTypeFAQ && len(vectorResults) == matchCount
- if needsIterativeRetrieval {
- logger.Info(ctx, "Not enough unique chunks, using iterative retrieval for FAQ")
- // Use iterative retrieval to get more unique chunks (with negative question filtering inside)
- deduplicatedChunks = s.iterativeRetrieveWithDeduplication(
- ctx,
- retrieveEngine,
- retrieveParams,
- params.MatchCount,
- params.QueryText,
- )
- } else if kb.Type == types.KnowledgeBaseTypeFAQ {
- // Filter by negative questions if not using iterative retrieval
- deduplicatedChunks = s.filterByNegativeQuestions(ctx, deduplicatedChunks, params.QueryText)
- logger.Infof(ctx, "Result count after negative question filtering: %d", len(deduplicatedChunks))
- }
-
- // Limit to MatchCount
- if len(deduplicatedChunks) > params.MatchCount {
- deduplicatedChunks = deduplicatedChunks[:params.MatchCount]
- }
-
- return s.processSearchResults(ctx, deduplicatedChunks, params.SkipContextEnrichment)
-}
-
-// iterativeRetrieveWithDeduplication performs iterative retrieval until enough unique chunks are found
-// This is used for FAQ knowledge bases with separate indexing mode
-// Negative question filtering is applied after each iteration with chunk data caching
-func (s *knowledgeBaseService) iterativeRetrieveWithDeduplication(ctx context.Context,
- retrieveEngine *retriever.CompositeRetrieveEngine,
- retrieveParams []types.RetrieveParams,
- matchCount int,
- queryText string,
-) []*types.IndexWithScore {
- maxIterations := 5
- // Start with a larger TopK since we're called when first retrieval wasn't enough
- // The first retrieval already used matchCount*3, so start from there
- currentTopK := matchCount * 3
- uniqueChunks := make(map[string]*types.IndexWithScore)
- // Cache chunk data to avoid repeated DB queries across iterations
- chunkDataCache := make(map[string]*types.Chunk)
- // Track chunks that have been filtered out by negative questions
- filteredOutChunks := make(map[string]struct{})
-
- queryTextLower := strings.ToLower(strings.TrimSpace(queryText))
- tenantID := types.MustTenantIDFromContext(ctx)
-
- for i := 0; i < maxIterations; i++ {
- // Update TopK in retrieve params
- updatedParams := make([]types.RetrieveParams, len(retrieveParams))
- for j := range retrieveParams {
- updatedParams[j] = retrieveParams[j]
- updatedParams[j].TopK = currentTopK
- }
-
- // Execute retrieval
- retrieveResults, err := retrieveEngine.Retrieve(ctx, updatedParams)
- if err != nil {
- logger.Warnf(ctx, "Iterative retrieval failed at iteration %d: %v", i+1, err)
- break
- }
-
- // Collect results
- iterationResults := []*types.IndexWithScore{}
- for _, retrieveResult := range retrieveResults {
- iterationResults = append(iterationResults, retrieveResult.Results...)
- }
-
- if len(iterationResults) == 0 {
- logger.Infof(ctx, "No results found at iteration %d", i+1)
- break
- }
-
- totalRetrieved := len(iterationResults)
-
- // Collect new chunk IDs that need to be fetched from DB
- newChunkIDs := make([]string, 0)
- for _, result := range iterationResults {
- if _, cached := chunkDataCache[result.ChunkID]; !cached {
- if _, filtered := filteredOutChunks[result.ChunkID]; !filtered {
- newChunkIDs = append(newChunkIDs, result.ChunkID)
- }
- }
- }
-
- // Batch fetch only new chunks
- if len(newChunkIDs) > 0 {
- newChunks, err := s.chunkRepo.ListChunksByID(ctx, tenantID, newChunkIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to fetch chunks at iteration %d: %v", i+1, err)
- } else {
- for _, chunk := range newChunks {
- chunkDataCache[chunk.ID] = chunk
- }
- }
- }
-
- // Deduplicate, merge, and filter in one pass
- for _, result := range iterationResults {
- // Skip if already filtered out
- if _, filtered := filteredOutChunks[result.ChunkID]; filtered {
- continue
- }
-
- // Check negative questions using cached data
- if chunkData, ok := chunkDataCache[result.ChunkID]; ok {
- if chunkData.ChunkType == types.ChunkTypeFAQ {
- if meta, err := chunkData.FAQMetadata(); err == nil && meta != nil {
- if s.matchesNegativeQuestions(queryTextLower, meta.NegativeQuestions) {
- filteredOutChunks[result.ChunkID] = struct{}{}
- delete(uniqueChunks, result.ChunkID)
- continue
- }
- }
- }
- }
-
- // Keep highest score for each chunk
- if existing, ok := uniqueChunks[result.ChunkID]; !ok || result.Score > existing.Score {
- uniqueChunks[result.ChunkID] = result
- }
- }
-
- logger.Infof(
- ctx,
- "After iteration %d: retrieved %d results, found %d valid unique chunks (target: %d)",
- i+1,
- totalRetrieved,
- len(uniqueChunks),
- matchCount,
- )
-
- // Early stop: Check if we have enough unique chunks after deduplication and filtering
- if len(uniqueChunks) >= matchCount {
- logger.Infof(ctx, "Found enough unique chunks after %d iterations", i+1)
- break
- }
-
- // Early stop: If we got fewer results than TopK, there are no more results to retrieve
- if totalRetrieved < currentTopK {
- logger.Infof(ctx, "No more results available (got %d < %d), stopping iteration", totalRetrieved, currentTopK)
- break
- }
-
- // Increase TopK for next iteration
- currentTopK *= 2
- }
-
- // Convert map to slice and sort by score
- result := make([]*types.IndexWithScore, 0, len(uniqueChunks))
- for _, chunk := range uniqueChunks {
- result = append(result, chunk)
- }
-
- // Sort by score descending
- slices.SortFunc(result, func(a, b *types.IndexWithScore) int {
- if a.Score > b.Score {
- return -1
- } else if a.Score < b.Score {
- return 1
- }
- return 0
- })
-
- logger.Infof(ctx, "Iterative retrieval completed: %d unique chunks found after filtering", len(result))
- return result
-}
-
-// filterByNegativeQuestions filters out chunks that match negative questions for FAQ knowledge bases.
-func (s *knowledgeBaseService) filterByNegativeQuestions(ctx context.Context,
- chunks []*types.IndexWithScore,
- queryText string,
-) []*types.IndexWithScore {
- if len(chunks) == 0 {
- return chunks
- }
-
- queryTextLower := strings.ToLower(strings.TrimSpace(queryText))
- if queryTextLower == "" {
- return chunks
- }
-
- tenantID := types.MustTenantIDFromContext(ctx)
-
- // Collect chunk IDs
- chunkIDs := make([]string, 0, len(chunks))
- for _, chunk := range chunks {
- chunkIDs = append(chunkIDs, chunk.ChunkID)
- }
-
- // Batch fetch chunks to get negative questions
- allChunks, err := s.chunkRepo.ListChunksByID(ctx, tenantID, chunkIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to fetch chunks for negative question filtering: %v", err)
- // If we can't fetch chunks, return original results
- return chunks
- }
-
- // Build chunk map for quick lookup
- chunkMap := make(map[string]*types.Chunk, len(allChunks))
- for _, chunk := range allChunks {
- chunkMap[chunk.ID] = chunk
- }
-
- // Filter out chunks that match negative questions
- filteredChunks := make([]*types.IndexWithScore, 0, len(chunks))
- for _, chunk := range chunks {
- chunkData, ok := chunkMap[chunk.ChunkID]
- if !ok {
- // If chunk not found, keep it (shouldn't happen, but be safe)
- filteredChunks = append(filteredChunks, chunk)
- continue
- }
-
- // Only filter FAQ type chunks
- if chunkData.ChunkType != types.ChunkTypeFAQ {
- filteredChunks = append(filteredChunks, chunk)
- continue
- }
-
- // Get FAQ metadata and check negative questions
- meta, err := chunkData.FAQMetadata()
- if err != nil || meta == nil {
- // If we can't parse metadata, keep the chunk
- filteredChunks = append(filteredChunks, chunk)
- continue
- }
-
- // Check if query matches any negative question
- if s.matchesNegativeQuestions(queryTextLower, meta.NegativeQuestions) {
- logger.Debugf(ctx, "Filtered FAQ chunk %s due to negative question match", chunk.ChunkID)
- continue
- }
-
- // Keep the chunk
- filteredChunks = append(filteredChunks, chunk)
- }
-
- return filteredChunks
-}
-
-// matchesNegativeQuestions checks if the query text matches any negative questions.
-// Returns true if the query matches any negative question, false otherwise.
-func (s *knowledgeBaseService) matchesNegativeQuestions(queryTextLower string, negativeQuestions []string) bool {
- if len(negativeQuestions) == 0 {
- return false
- }
-
- for _, negativeQ := range negativeQuestions {
- negativeQLower := strings.ToLower(strings.TrimSpace(negativeQ))
- if negativeQLower == "" {
- continue
- }
- // Check if query text is exactly the same as the negative question
- if queryTextLower == negativeQLower {
- return true
- }
- }
- return false
-}
-
-// processSearchResults handles the processing of search results, optimizing database queries
-func (s *knowledgeBaseService) processSearchResults(ctx context.Context,
- chunks []*types.IndexWithScore,
- skipEnrichment bool,
-) ([]*types.SearchResult, error) {
- if len(chunks) == 0 {
- return nil, nil
- }
-
- tenantID := types.MustTenantIDFromContext(ctx)
-
- // Prepare data structures for efficient processing
- var knowledgeIDs []string
- var chunkIDs []string
- chunkScores := make(map[string]float64)
- chunkMatchTypes := make(map[string]types.MatchType)
- chunkMatchedContents := make(map[string]string)
- processedKnowledgeIDs := make(map[string]bool)
-
- // Collect all knowledge and chunk IDs
- for _, chunk := range chunks {
- if !processedKnowledgeIDs[chunk.KnowledgeID] {
- knowledgeIDs = append(knowledgeIDs, chunk.KnowledgeID)
- processedKnowledgeIDs[chunk.KnowledgeID] = true
- }
-
- chunkIDs = append(chunkIDs, chunk.ChunkID)
- chunkScores[chunk.ChunkID] = chunk.Score
- chunkMatchTypes[chunk.ChunkID] = chunk.MatchType
- chunkMatchedContents[chunk.ChunkID] = chunk.Content
- }
-
- // Batch fetch knowledge data (include shared KB so cross-tenant retrieval works)
- logger.Infof(ctx, "Fetching knowledge data for %d IDs", len(knowledgeIDs))
- knowledgeMap, err := s.fetchKnowledgeDataWithShared(ctx, tenantID, knowledgeIDs)
- if err != nil {
- return nil, err
- }
-
- // Batch fetch chunks (include shared KB chunks: first by tenant, then by ID-only for missing with permission check)
- logger.Infof(ctx, "Fetching chunk data for %d IDs", len(chunkIDs))
- allChunks, err := s.listChunksByIDWithShared(ctx, tenantID, chunkIDs)
- if err != nil {
- logger.ErrorWithFields(ctx, err, map[string]interface{}{
- "tenant_id": tenantID,
- "chunk_ids": chunkIDs,
- })
- return nil, err
- }
- logger.Infof(ctx, "Chunk data fetched successfully, count: %d", len(allChunks))
-
- // Build chunk map and collect additional IDs to fetch
- chunkMap := make(map[string]*types.Chunk, len(allChunks))
- var additionalChunkIDs []string
- processedChunkIDs := make(map[string]bool)
-
- // First pass: Build chunk map and collect parent IDs
- for _, chunk := range allChunks {
- chunkMap[chunk.ID] = chunk
- processedChunkIDs[chunk.ID] = true
-
- if !skipEnrichment {
- // Collect parent chunks
- if chunk.ParentChunkID != "" && !processedChunkIDs[chunk.ParentChunkID] {
- additionalChunkIDs = append(additionalChunkIDs, chunk.ParentChunkID)
- processedChunkIDs[chunk.ParentChunkID] = true
-
- // Pass score to parent
- chunkScores[chunk.ParentChunkID] = chunkScores[chunk.ID]
- chunkMatchTypes[chunk.ParentChunkID] = types.MatchTypeParentChunk
- }
-
- // Collect related chunks
- relationChunkIDs := s.collectRelatedChunkIDs(chunk, processedChunkIDs)
- for _, chunkID := range relationChunkIDs {
- additionalChunkIDs = append(additionalChunkIDs, chunkID)
- chunkMatchTypes[chunkID] = types.MatchTypeRelationChunk
- }
-
- // Add nearby chunks (prev and next)
- if slices.Contains([]string{types.ChunkTypeText}, chunk.ChunkType) {
- if chunk.NextChunkID != "" && !processedChunkIDs[chunk.NextChunkID] {
- additionalChunkIDs = append(additionalChunkIDs, chunk.NextChunkID)
- processedChunkIDs[chunk.NextChunkID] = true
- chunkMatchTypes[chunk.NextChunkID] = types.MatchTypeNearByChunk
- }
- if chunk.PreChunkID != "" && !processedChunkIDs[chunk.PreChunkID] {
- additionalChunkIDs = append(additionalChunkIDs, chunk.PreChunkID)
- processedChunkIDs[chunk.PreChunkID] = true
- chunkMatchTypes[chunk.PreChunkID] = types.MatchTypeNearByChunk
- }
- }
- }
- }
-
- // Fetch all additional chunks in one go if needed (include shared KB)
- if len(additionalChunkIDs) > 0 {
- logger.Infof(ctx, "Fetching %d additional chunks", len(additionalChunkIDs))
- additionalChunks, err := s.listChunksByIDWithShared(ctx, tenantID, additionalChunkIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to fetch some additional chunks: %v", err)
- // Continue with what we have
- } else {
- // Add to chunk map
- for _, chunk := range additionalChunks {
- chunkMap[chunk.ID] = chunk
- }
- }
- }
-
- // 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 {
- chunk, exists := chunkMap[inputChunk.ChunkID]
- if !exists {
- logger.Debugf(ctx, "Chunk not found in chunkMap: %s", inputChunk.ChunkID)
- continue
- }
- if !s.isValidTextChunk(chunk) {
- invalidChunkCnt++
- if len(invalidChunkSamples) < maxInvalidChunkLog {
- invalidChunkSamples = append(invalidChunkSamples, chunk.ID+":"+chunk.ChunkType)
- }
- continue
- }
- if addedChunkIDs[chunk.ID] {
- continue
- }
-
- score := chunkScores[chunk.ID]
- if knowledge, ok := knowledgeMap[chunk.KnowledgeID]; ok {
- matchType := chunkMatchTypes[chunk.ID]
- matchedContent := chunkMatchedContents[chunk.ID]
- searchResults = append(searchResults, s.buildSearchResult(chunk, knowledge, score, matchType, matchedContent))
- addedChunkIDs[chunk.ID] = true
- } else {
- 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 {
- for chunkID, chunk := range chunkMap {
- if addedChunkIDs[chunkID] || !s.isValidTextChunk(chunk) {
- continue
- }
-
- score, hasScore := chunkScores[chunkID]
- if !hasScore || score <= 0 {
- score = 0.0
- }
-
- if knowledge, ok := knowledgeMap[chunk.KnowledgeID]; ok {
- matchType := types.MatchTypeParentChunk
- if specificType, exists := chunkMatchTypes[chunkID]; exists {
- matchType = specificType
- } else {
- logger.Warnf(ctx, "Unkonwn match type for chunk: %s", chunkID)
- continue
- }
- matchedContent := chunkMatchedContents[chunkID]
- searchResults = append(searchResults, s.buildSearchResult(chunk, knowledge, score, matchType, matchedContent))
- }
- }
- }
- logger.Infof(ctx, "Search results processed, total: %d", len(searchResults))
- return searchResults, nil
-}
-
-// collectRelatedChunkIDs extracts related chunk IDs from a chunk
-func (s *knowledgeBaseService) collectRelatedChunkIDs(chunk *types.Chunk, processedIDs map[string]bool) []string {
- var relatedIDs []string
- // Process direct relations
- if len(chunk.RelationChunks) > 0 {
- var relations []string
- if err := json.Unmarshal(chunk.RelationChunks, &relations); err == nil {
- for _, id := range relations {
- if !processedIDs[id] {
- relatedIDs = append(relatedIDs, id)
- processedIDs[id] = true
- }
- }
- }
- }
- return relatedIDs
-}
-
-// buildSearchResult creates a search result from chunk and knowledge
-func (s *knowledgeBaseService) buildSearchResult(chunk *types.Chunk,
- knowledge *types.Knowledge,
- score float64,
- matchType types.MatchType,
- matchedContent string,
-) *types.SearchResult {
- return &types.SearchResult{
- ID: chunk.ID,
- Content: chunk.Content,
- KnowledgeID: chunk.KnowledgeID,
- ChunkIndex: chunk.ChunkIndex,
- KnowledgeTitle: knowledge.Title,
- StartAt: chunk.StartAt,
- EndAt: chunk.EndAt,
- Seq: chunk.ChunkIndex,
- Score: score,
- MatchType: matchType,
- Metadata: knowledge.GetMetadata(),
- ChunkType: string(chunk.ChunkType),
- ParentChunkID: chunk.ParentChunkID,
- ImageInfo: chunk.ImageInfo,
- KnowledgeFilename: knowledge.FileName,
- KnowledgeSource: knowledge.Source,
- ChunkMetadata: chunk.Metadata,
- MatchedContent: matchedContent,
- KnowledgeBaseID: knowledge.KnowledgeBaseID,
- }
-}
-
-// isValidTextChunk checks if a chunk is a valid text chunk
-func (s *knowledgeBaseService) isValidTextChunk(chunk *types.Chunk) bool {
- return slices.Contains([]types.ChunkType{
- types.ChunkTypeText, types.ChunkTypeSummary,
- types.ChunkTypeTableColumn, types.ChunkTypeTableSummary,
- types.ChunkTypeFAQ,
- }, chunk.ChunkType)
-}
-
-// fetchKnowledgeData gets knowledge data in batch
-func (s *knowledgeBaseService) fetchKnowledgeData(ctx context.Context,
- tenantID uint64,
- knowledgeIDs []string,
-) (map[string]*types.Knowledge, error) {
- knowledges, err := s.kgRepo.GetKnowledgeBatch(ctx, tenantID, knowledgeIDs)
- if err != nil {
- logger.ErrorWithFields(ctx, err, map[string]interface{}{
- "tenant_id": tenantID,
- "knowledge_ids": knowledgeIDs,
- })
- return nil, err
- }
-
- knowledgeMap := make(map[string]*types.Knowledge, len(knowledges))
- for _, knowledge := range knowledges {
- knowledgeMap[knowledge.ID] = knowledge
- }
-
- return knowledgeMap, nil
-}
-
-// fetchKnowledgeDataWithShared gets knowledge data in batch, including knowledge from shared KBs the user has access to.
-func (s *knowledgeBaseService) fetchKnowledgeDataWithShared(ctx context.Context,
- tenantID uint64,
- knowledgeIDs []string,
-) (map[string]*types.Knowledge, error) {
- knowledges, err := s.kgRepo.GetKnowledgeBatch(ctx, tenantID, knowledgeIDs)
- if err != nil {
- logger.ErrorWithFields(ctx, err, map[string]interface{}{
- "tenant_id": tenantID,
- "knowledge_ids": knowledgeIDs,
- })
- return nil, err
- }
-
- knowledgeMap := make(map[string]*types.Knowledge, len(knowledges))
- for _, k := range knowledges {
- knowledgeMap[k.ID] = k
- }
-
- // Count how many IDs are missing (not found in current tenant)
- var missingIDs []string
- for _, id := range knowledgeIDs {
- if knowledgeMap[id] == nil {
- missingIDs = append(missingIDs, id)
- }
- }
- if len(missingIDs) == 0 {
- return knowledgeMap, nil
- }
- logger.Infof(ctx, "[fetchKnowledgeDataWithShared] %d knowledge IDs not found in current tenant, attempting shared KB lookup", len(missingIDs))
-
- userIDVal := ctx.Value(types.UserIDContextKey)
- if userIDVal == nil {
- logger.Warnf(ctx, "[fetchKnowledgeDataWithShared] userID not found in context, skipping shared KB lookup")
- return knowledgeMap, nil
- }
- userID, ok := userIDVal.(string)
- if !ok || userID == "" {
- logger.Warnf(ctx, "[fetchKnowledgeDataWithShared] userID is empty, skipping shared KB lookup")
- return knowledgeMap, nil
- }
-
- logger.Infof(ctx, "[fetchKnowledgeDataWithShared] Looking up %d missing knowledge IDs with userID=%s", len(missingIDs), userID)
- for _, id := range missingIDs {
- k, err := s.kgRepo.GetKnowledgeByIDOnly(ctx, id)
- if err != nil || k == nil || k.KnowledgeBaseID == "" {
- logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] Knowledge %s not found or has no KB", id)
- continue
- }
- hasPermission, err := s.kbShareService.HasKBPermission(ctx, k.KnowledgeBaseID, userID, types.OrgRoleViewer)
- if err != nil {
- logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] Permission check error for KB %s: %v", k.KnowledgeBaseID, err)
- continue
- }
- if !hasPermission {
- logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] No permission for KB %s", k.KnowledgeBaseID)
- continue
- }
- logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] Found shared knowledge %s in KB %s", id, k.KnowledgeBaseID)
- knowledgeMap[k.ID] = k
- }
-
- logger.Infof(ctx, "[fetchKnowledgeDataWithShared] After shared lookup, total knowledge found: %d", len(knowledgeMap))
- return knowledgeMap, nil
-}
-
-// listChunksByIDWithShared fetches chunks by IDs, including chunks from shared KBs the user has access to.
-func (s *knowledgeBaseService) listChunksByIDWithShared(ctx context.Context,
- tenantID uint64,
- chunkIDs []string,
-) ([]*types.Chunk, error) {
- chunks, err := s.chunkRepo.ListChunksByID(ctx, tenantID, chunkIDs)
- if err != nil {
- return nil, err
- }
-
- foundSet := make(map[string]bool)
- for _, c := range chunks {
- if c != nil {
- foundSet[c.ID] = true
- }
- }
-
- var missing []string
- for _, id := range chunkIDs {
- if !foundSet[id] {
- missing = append(missing, id)
- }
- }
- if len(missing) == 0 {
- return chunks, nil
- }
- logger.Infof(ctx, "[listChunksByIDWithShared] %d chunks not found in current tenant, attempting shared KB lookup", len(missing))
-
- userIDVal := ctx.Value(types.UserIDContextKey)
- if userIDVal == nil {
- logger.Warnf(ctx, "[listChunksByIDWithShared] userID not found in context, skipping shared KB lookup")
- return chunks, nil
- }
- userID, ok := userIDVal.(string)
- if !ok || userID == "" {
- logger.Warnf(ctx, "[listChunksByIDWithShared] userID is empty, skipping shared KB lookup")
- return chunks, nil
- }
-
- logger.Infof(ctx, "[listChunksByIDWithShared] Looking up %d missing chunks with userID=%s", len(missing), userID)
- crossChunks, err := s.chunkRepo.ListChunksByIDOnly(ctx, missing)
- if err != nil {
- logger.Warnf(ctx, "[listChunksByIDWithShared] Failed to fetch chunks by ID only: %v", err)
- return chunks, nil
- }
- logger.Infof(ctx, "[listChunksByIDWithShared] Found %d chunks without tenant filter", len(crossChunks))
-
- for _, c := range crossChunks {
- if c == nil || c.KnowledgeBaseID == "" {
- continue
- }
- hasPermission, err := s.kbShareService.HasKBPermission(ctx, c.KnowledgeBaseID, userID, types.OrgRoleViewer)
- if err != nil {
- logger.Debugf(ctx, "[listChunksByIDWithShared] Permission check error for KB %s: %v", c.KnowledgeBaseID, err)
- continue
- }
- if !hasPermission {
- logger.Debugf(ctx, "[listChunksByIDWithShared] No permission for KB %s", c.KnowledgeBaseID)
- continue
- }
- chunks = append(chunks, c)
- }
-
- logger.Infof(ctx, "[listChunksByIDWithShared] After shared lookup, total chunks: %d", len(chunks))
- return chunks, nil
-}
diff --git a/internal/application/service/knowledgebase_search.go b/internal/application/service/knowledgebase_search.go
new file mode 100644
index 00000000..d2717aa5
--- /dev/null
+++ b/internal/application/service/knowledgebase_search.go
@@ -0,0 +1,253 @@
+package service
+
+import (
+ "context"
+ "errors"
+
+ "github.com/Tencent/WeKnora/internal/application/service/retriever"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/embedding"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// GetQueryEmbedding computes the query embedding using the embedding model
+// associated with the given knowledge base. Callers can pre-compute and reuse
+// the result across multiple KBs that share the same embedding model to avoid
+// redundant embedding API calls.
+func (s *knowledgeBaseService) GetQueryEmbedding(ctx context.Context, kbID string, queryText string) ([]float32, error) {
+ kb, err := s.repo.GetKnowledgeBaseByID(ctx, kbID)
+ if err != nil {
+ return nil, err
+ }
+
+ currentTenantID := types.MustTenantIDFromContext(ctx)
+ var embeddingModel embedding.Embedder
+
+ if kb.TenantID != currentTenantID {
+ embeddingModel, err = s.modelService.GetEmbeddingModelForTenant(ctx, kb.EmbeddingModelID, kb.TenantID)
+ } else {
+ embeddingModel, err = s.modelService.GetEmbeddingModel(ctx, kb.EmbeddingModelID)
+ }
+ if err != nil {
+ logger.Errorf(ctx, "GetQueryEmbedding: failed to get embedding model %s: %v", kb.EmbeddingModelID, err)
+ return nil, err
+ }
+
+ return embeddingModel.Embed(ctx, queryText)
+}
+
+// ResolveEmbeddingModelKeys resolves embedding model IDs to their actual model
+// identity key (name + endpoint). KBs using the same underlying model across
+// different tenants will share the same key, enabling optimal grouping.
+func (s *knowledgeBaseService) ResolveEmbeddingModelKeys(ctx context.Context, kbs []*types.KnowledgeBase) map[string]string {
+ type modelRef struct {
+ ModelID string
+ TenantID uint64
+ }
+
+ // Deduplicate model references
+ uniqueRefs := make(map[modelRef]struct{})
+ kbRefs := make(map[string]modelRef, len(kbs))
+ for _, kb := range kbs {
+ ref := modelRef{ModelID: kb.EmbeddingModelID, TenantID: kb.TenantID}
+ uniqueRefs[ref] = struct{}{}
+ kbRefs[kb.ID] = ref
+ }
+
+ // Resolve each unique (modelID, tenantID) to a model identity key
+ resolvedKeys := make(map[modelRef]string, len(uniqueRefs))
+ for ref := range uniqueRefs {
+ tenantCtx := context.WithValue(ctx, types.TenantIDContextKey, ref.TenantID)
+ model, err := s.modelService.GetModelByID(tenantCtx, ref.ModelID)
+ if err != nil || model == nil {
+ logger.Warnf(ctx, "ResolveEmbeddingModelKeys: cannot resolve model %s for tenant %d: %v", ref.ModelID, ref.TenantID, err)
+ resolvedKeys[ref] = ref.ModelID
+ continue
+ }
+ resolvedKeys[ref] = model.Name + "|" + model.Parameters.BaseURL
+ }
+
+ result := make(map[string]string, len(kbs))
+ for _, kb := range kbs {
+ result[kb.ID] = resolvedKeys[kbRefs[kb.ID]]
+ }
+ return result
+}
+
+// HybridSearch performs hybrid search, including vector retrieval and keyword retrieval.
+//
+// id is the "primary" knowledge base ID used to resolve the embedding model and
+// determine the KB type (e.g. FAQ). When params.KnowledgeBaseIDs is set, those
+// IDs are used for the actual retrieval scope instead of id alone, allowing a
+// single call to span multiple KBs that share the same embedding model. In that
+// case id should be any one of those KBs (typically the first) so that its
+// embedding model and type configuration are used for the search.
+func (s *knowledgeBaseService) HybridSearch(ctx context.Context,
+ id string,
+ params types.SearchParams,
+) ([]*types.SearchResult, error) {
+ // Determine the set of KB IDs to search
+ searchKBIDs := params.KnowledgeBaseIDs
+ if len(searchKBIDs) == 0 {
+ searchKBIDs = []string{id}
+ }
+
+ logger.Infof(ctx, "Hybrid search parameters, knowledge base IDs: %v, query text: %s", searchKBIDs, params.QueryText)
+
+ tenantInfo, _ := types.TenantInfoFromContext(ctx)
+
+ // Create a composite retrieval engine with tenant's configured retrievers
+ retrieveEngine, err := retriever.NewCompositeRetrieveEngine(s.retrieveEngine, tenantInfo.GetEffectiveEngines())
+ if err != nil {
+ logger.Errorf(ctx, "Failed to create retrieval engine: %v", err)
+ return nil, err
+ }
+
+ kb, err := s.repo.GetKnowledgeBaseByID(ctx, id)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, map[string]interface{}{
+ "knowledge_base_id": id,
+ })
+ return nil, err
+ }
+
+ // Use 5x over-retrieval to ensure sufficient candidates for RRF fusion and reranking.
+ // Scale proportionally when searching multiple KBs to maintain per-KB recall quality.
+ matchCount := max(params.MatchCount*5, 50) * len(searchKBIDs)
+ if matchCount > 1000 {
+ matchCount = 1000
+ }
+
+ // Build retrieval parameters for vector and keyword engines
+ retrieveParams, err := s.buildRetrievalParams(ctx, retrieveEngine, kb, params, searchKBIDs, matchCount)
+ if err != nil {
+ return nil, err
+ }
+ if len(retrieveParams) == 0 {
+ logger.Error(ctx, "No retrieval parameters available")
+ return nil, errors.New("no retrieve params")
+ }
+
+ // Execute retrieval using the configured engines
+ logger.Infof(ctx, "Starting retrieval, parameter count: %d", len(retrieveParams))
+ retrieveResults, err := retrieveEngine.Retrieve(ctx, retrieveParams)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, map[string]interface{}{
+ "knowledge_base_ids": searchKBIDs,
+ "query_text": params.QueryText,
+ })
+ return nil, err
+ }
+
+ // Separate and fuse retrieval results
+ vectorResults, keywordResults := classifyRetrievalResults(ctx, retrieveResults)
+ if len(vectorResults) == 0 && len(keywordResults) == 0 {
+ logger.Info(ctx, "No search results found")
+ return nil, nil
+ }
+ logger.Infof(ctx, "Result count before fusion: vector=%d, keyword=%d", len(vectorResults), len(keywordResults))
+
+ deduplicatedChunks := fuseOrDeduplicate(ctx, vectorResults, keywordResults)
+
+ kb.EnsureDefaults()
+
+ // FAQ-specific post-processing: iterative retrieval or negative question filtering
+ deduplicatedChunks = s.applyFAQPostProcessing(ctx, kb, deduplicatedChunks, vectorResults, retrieveEngine, retrieveParams, params, matchCount)
+
+ // Limit to MatchCount
+ if len(deduplicatedChunks) > params.MatchCount {
+ deduplicatedChunks = deduplicatedChunks[:params.MatchCount]
+ }
+
+ return s.processSearchResults(ctx, deduplicatedChunks, params.SkipContextEnrichment)
+}
+
+// buildRetrievalParams constructs the vector and keyword retrieval parameters
+// based on the knowledge base type, engine capabilities, and search params.
+func (s *knowledgeBaseService) buildRetrievalParams(
+ ctx context.Context,
+ retrieveEngine *retriever.CompositeRetrieveEngine,
+ kb *types.KnowledgeBase,
+ params types.SearchParams,
+ searchKBIDs []string,
+ matchCount int,
+) ([]types.RetrieveParams, error) {
+ currentTenantID := types.MustTenantIDFromContext(ctx)
+ var retrieveParams []types.RetrieveParams
+
+ // Add vector retrieval params if supported
+ if retrieveEngine.SupportRetriever(types.VectorRetrieverType) && !params.DisableVectorMatch {
+ logger.Info(ctx, "Vector retrieval supported, preparing vector retrieval parameters")
+
+ var queryEmbedding []float32
+
+ if len(params.QueryEmbedding) > 0 {
+ queryEmbedding = params.QueryEmbedding
+ logger.Infof(ctx, "Using pre-computed query embedding, vector length: %d", len(queryEmbedding))
+ } else {
+ logger.Infof(ctx, "Getting embedding model, model ID: %s", kb.EmbeddingModelID)
+
+ // Check if this is a cross-tenant shared knowledge base
+ // For shared KB, we must use the source tenant's embedding model to ensure vector compatibility
+ var embeddingModel embedding.Embedder
+ var err error
+ if kb.TenantID != currentTenantID {
+ logger.Infof(ctx, "Cross-tenant knowledge base detected, using source tenant's embedding model. KB tenant: %d, current tenant: %d", kb.TenantID, currentTenantID)
+ embeddingModel, err = s.modelService.GetEmbeddingModelForTenant(ctx, kb.EmbeddingModelID, kb.TenantID)
+ } else {
+ embeddingModel, err = s.modelService.GetEmbeddingModel(ctx, kb.EmbeddingModelID)
+ }
+
+ if err != nil {
+ logger.Errorf(ctx, "Failed to get embedding model, model ID: %s, error: %v", kb.EmbeddingModelID, err)
+ return nil, err
+ }
+ logger.Infof(ctx, "Embedding model retrieved: %v", embeddingModel)
+
+ logger.Info(ctx, "Starting to generate query embedding")
+ queryEmbedding, err = embeddingModel.Embed(ctx, params.QueryText)
+ if err != nil {
+ logger.Errorf(ctx, "Failed to embed query text, query text: %s, error: %v", params.QueryText, err)
+ return nil, err
+ }
+ logger.Infof(ctx, "Query embedding generated successfully, embedding vector length: %d", len(queryEmbedding))
+ }
+
+ vectorParams := types.RetrieveParams{
+ Query: params.QueryText,
+ Embedding: queryEmbedding,
+ KnowledgeBaseIDs: searchKBIDs,
+ TopK: matchCount,
+ Threshold: params.VectorThreshold,
+ RetrieverType: types.VectorRetrieverType,
+ KnowledgeIDs: params.KnowledgeIDs,
+ TagIDs: params.TagIDs,
+ }
+
+ // For FAQ knowledge base, use FAQ index
+ if kb.Type == types.KnowledgeBaseTypeFAQ {
+ vectorParams.KnowledgeType = types.KnowledgeTypeFAQ
+ }
+
+ retrieveParams = append(retrieveParams, vectorParams)
+ logger.Info(ctx, "Vector retrieval parameters setup completed")
+ }
+
+ // Add keyword retrieval params if supported and not FAQ
+ if retrieveEngine.SupportRetriever(types.KeywordsRetrieverType) && !params.DisableKeywordsMatch &&
+ kb.Type != types.KnowledgeBaseTypeFAQ {
+ logger.Info(ctx, "Keyword retrieval supported, preparing keyword retrieval parameters")
+ retrieveParams = append(retrieveParams, types.RetrieveParams{
+ Query: params.QueryText,
+ KnowledgeBaseIDs: searchKBIDs,
+ TopK: matchCount,
+ Threshold: params.KeywordThreshold,
+ RetrieverType: types.KeywordsRetrieverType,
+ KnowledgeIDs: params.KnowledgeIDs,
+ TagIDs: params.TagIDs,
+ })
+ logger.Info(ctx, "Keyword retrieval parameters setup completed")
+ }
+
+ return retrieveParams, nil
+}
diff --git a/internal/application/service/knowledgebase_search_faq.go b/internal/application/service/knowledgebase_search_faq.go
new file mode 100644
index 00000000..85fb339a
--- /dev/null
+++ b/internal/application/service/knowledgebase_search_faq.go
@@ -0,0 +1,276 @@
+package service
+
+import (
+ "context"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/application/service/retriever"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "slices"
+)
+
+// applyFAQPostProcessing handles FAQ-specific post-processing: iterative retrieval
+// when not enough unique chunks are found, or negative question filtering otherwise.
+// For non-FAQ knowledge bases, returns the input unchanged.
+func (s *knowledgeBaseService) applyFAQPostProcessing(
+ ctx context.Context,
+ kb *types.KnowledgeBase,
+ chunks []*types.IndexWithScore,
+ vectorResults []*types.IndexWithScore,
+ retrieveEngine *retriever.CompositeRetrieveEngine,
+ retrieveParams []types.RetrieveParams,
+ params types.SearchParams,
+ matchCount int,
+) []*types.IndexWithScore {
+ if kb.Type != types.KnowledgeBaseTypeFAQ {
+ return chunks
+ }
+
+ // Check if we need iterative retrieval for FAQ with separate indexing
+ // Only use iterative retrieval if we don't have enough unique chunks after first deduplication
+ needsIterativeRetrieval := len(chunks) < params.MatchCount && len(vectorResults) == matchCount
+ if needsIterativeRetrieval {
+ logger.Info(ctx, "Not enough unique chunks, using iterative retrieval for FAQ")
+ return s.iterativeRetrieveWithDeduplication(
+ ctx,
+ retrieveEngine,
+ retrieveParams,
+ params.MatchCount,
+ params.QueryText,
+ )
+ }
+
+ // Filter by negative questions if not using iterative retrieval
+ result := s.filterByNegativeQuestions(ctx, chunks, params.QueryText)
+ logger.Infof(ctx, "Result count after negative question filtering: %d", len(result))
+ return result
+}
+
+// iterativeRetrieveWithDeduplication performs iterative retrieval until enough unique chunks are found.
+// This is used for FAQ knowledge bases with separate indexing mode.
+// Negative question filtering is applied after each iteration with chunk data caching.
+func (s *knowledgeBaseService) iterativeRetrieveWithDeduplication(ctx context.Context,
+ retrieveEngine *retriever.CompositeRetrieveEngine,
+ retrieveParams []types.RetrieveParams,
+ matchCount int,
+ queryText string,
+) []*types.IndexWithScore {
+ maxIterations := 5
+ // Start with a larger TopK since we're called when first retrieval wasn't enough
+ // The first retrieval already used matchCount*3, so start from there
+ currentTopK := matchCount * 3
+ uniqueChunks := make(map[string]*types.IndexWithScore)
+ // Cache chunk data to avoid repeated DB queries across iterations
+ chunkDataCache := make(map[string]*types.Chunk)
+ // Track chunks that have been filtered out by negative questions
+ filteredOutChunks := make(map[string]struct{})
+
+ queryTextLower := strings.ToLower(strings.TrimSpace(queryText))
+ tenantID := types.MustTenantIDFromContext(ctx)
+
+ for i := 0; i < maxIterations; i++ {
+ // Update TopK in retrieve params
+ updatedParams := make([]types.RetrieveParams, len(retrieveParams))
+ for j := range retrieveParams {
+ updatedParams[j] = retrieveParams[j]
+ updatedParams[j].TopK = currentTopK
+ }
+
+ // Execute retrieval
+ retrieveResults, err := retrieveEngine.Retrieve(ctx, updatedParams)
+ if err != nil {
+ logger.Warnf(ctx, "Iterative retrieval failed at iteration %d: %v", i+1, err)
+ break
+ }
+
+ // Collect results
+ iterationResults := []*types.IndexWithScore{}
+ for _, retrieveResult := range retrieveResults {
+ iterationResults = append(iterationResults, retrieveResult.Results...)
+ }
+
+ if len(iterationResults) == 0 {
+ logger.Infof(ctx, "No results found at iteration %d", i+1)
+ break
+ }
+
+ totalRetrieved := len(iterationResults)
+
+ // Collect new chunk IDs that need to be fetched from DB
+ newChunkIDs := make([]string, 0)
+ for _, result := range iterationResults {
+ if _, cached := chunkDataCache[result.ChunkID]; !cached {
+ if _, filtered := filteredOutChunks[result.ChunkID]; !filtered {
+ newChunkIDs = append(newChunkIDs, result.ChunkID)
+ }
+ }
+ }
+
+ // Batch fetch only new chunks
+ if len(newChunkIDs) > 0 {
+ newChunks, err := s.chunkRepo.ListChunksByID(ctx, tenantID, newChunkIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to fetch chunks at iteration %d: %v", i+1, err)
+ } else {
+ for _, chunk := range newChunks {
+ chunkDataCache[chunk.ID] = chunk
+ }
+ }
+ }
+
+ // Deduplicate, merge, and filter in one pass
+ for _, result := range iterationResults {
+ // Skip if already filtered out
+ if _, filtered := filteredOutChunks[result.ChunkID]; filtered {
+ continue
+ }
+
+ // Check negative questions using cached data
+ if chunkData, ok := chunkDataCache[result.ChunkID]; ok {
+ if chunkData.ChunkType == types.ChunkTypeFAQ {
+ if meta, err := chunkData.FAQMetadata(); err == nil && meta != nil {
+ if s.matchesNegativeQuestions(queryTextLower, meta.NegativeQuestions) {
+ filteredOutChunks[result.ChunkID] = struct{}{}
+ delete(uniqueChunks, result.ChunkID)
+ continue
+ }
+ }
+ }
+ }
+
+ // Keep highest score for each chunk
+ if existing, ok := uniqueChunks[result.ChunkID]; !ok || result.Score > existing.Score {
+ uniqueChunks[result.ChunkID] = result
+ }
+ }
+
+ logger.Infof(
+ ctx,
+ "After iteration %d: retrieved %d results, found %d valid unique chunks (target: %d)",
+ i+1,
+ totalRetrieved,
+ len(uniqueChunks),
+ matchCount,
+ )
+
+ // Early stop: Check if we have enough unique chunks after deduplication and filtering
+ if len(uniqueChunks) >= matchCount {
+ logger.Infof(ctx, "Found enough unique chunks after %d iterations", i+1)
+ break
+ }
+
+ // Early stop: If we got fewer results than TopK, there are no more results to retrieve
+ if totalRetrieved < currentTopK {
+ logger.Infof(ctx, "No more results available (got %d < %d), stopping iteration", totalRetrieved, currentTopK)
+ break
+ }
+
+ // Increase TopK for next iteration
+ currentTopK *= 2
+ }
+
+ // Convert map to slice and sort by score
+ result := make([]*types.IndexWithScore, 0, len(uniqueChunks))
+ for _, chunk := range uniqueChunks {
+ result = append(result, chunk)
+ }
+
+ slices.SortFunc(result, sortByScoreDesc)
+
+ logger.Infof(ctx, "Iterative retrieval completed: %d unique chunks found after filtering", len(result))
+ return result
+}
+
+// filterByNegativeQuestions filters out chunks that match negative questions for FAQ knowledge bases.
+func (s *knowledgeBaseService) filterByNegativeQuestions(ctx context.Context,
+ chunks []*types.IndexWithScore,
+ queryText string,
+) []*types.IndexWithScore {
+ if len(chunks) == 0 {
+ return chunks
+ }
+
+ queryTextLower := strings.ToLower(strings.TrimSpace(queryText))
+ if queryTextLower == "" {
+ return chunks
+ }
+
+ tenantID := types.MustTenantIDFromContext(ctx)
+
+ // Collect chunk IDs
+ chunkIDs := make([]string, 0, len(chunks))
+ for _, chunk := range chunks {
+ chunkIDs = append(chunkIDs, chunk.ChunkID)
+ }
+
+ // Batch fetch chunks to get negative questions
+ allChunks, err := s.chunkRepo.ListChunksByID(ctx, tenantID, chunkIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to fetch chunks for negative question filtering: %v", err)
+ // If we can't fetch chunks, return original results
+ return chunks
+ }
+
+ // Build chunk map for quick lookup
+ chunkMap := make(map[string]*types.Chunk, len(allChunks))
+ for _, chunk := range allChunks {
+ chunkMap[chunk.ID] = chunk
+ }
+
+ // Filter out chunks that match negative questions
+ filteredChunks := make([]*types.IndexWithScore, 0, len(chunks))
+ for _, chunk := range chunks {
+ chunkData, ok := chunkMap[chunk.ChunkID]
+ if !ok {
+ // If chunk not found, keep it (shouldn't happen, but be safe)
+ filteredChunks = append(filteredChunks, chunk)
+ continue
+ }
+
+ // Only filter FAQ type chunks
+ if chunkData.ChunkType != types.ChunkTypeFAQ {
+ filteredChunks = append(filteredChunks, chunk)
+ continue
+ }
+
+ // Get FAQ metadata and check negative questions
+ meta, err := chunkData.FAQMetadata()
+ if err != nil || meta == nil {
+ // If we can't parse metadata, keep the chunk
+ filteredChunks = append(filteredChunks, chunk)
+ continue
+ }
+
+ // Check if query matches any negative question
+ if s.matchesNegativeQuestions(queryTextLower, meta.NegativeQuestions) {
+ logger.Debugf(ctx, "Filtered FAQ chunk %s due to negative question match", chunk.ChunkID)
+ continue
+ }
+
+ // Keep the chunk
+ filteredChunks = append(filteredChunks, chunk)
+ }
+
+ return filteredChunks
+}
+
+// matchesNegativeQuestions checks if the query text matches any negative questions.
+// Returns true if the query matches any negative question, false otherwise.
+func (s *knowledgeBaseService) matchesNegativeQuestions(queryTextLower string, negativeQuestions []string) bool {
+ if len(negativeQuestions) == 0 {
+ return false
+ }
+
+ for _, negativeQ := range negativeQuestions {
+ negativeQLower := strings.ToLower(strings.TrimSpace(negativeQ))
+ if negativeQLower == "" {
+ continue
+ }
+ // Check if query text is exactly the same as the negative question
+ if queryTextLower == negativeQLower {
+ return true
+ }
+ }
+ return false
+}
diff --git a/internal/application/service/knowledgebase_search_fusion.go b/internal/application/service/knowledgebase_search_fusion.go
new file mode 100644
index 00000000..0085a8bb
--- /dev/null
+++ b/internal/application/service/knowledgebase_search_fusion.go
@@ -0,0 +1,134 @@
+package service
+
+import (
+ "context"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "slices"
+)
+
+// classifyRetrievalResults separates retrieval results by retriever type (vector vs keyword).
+func classifyRetrievalResults(ctx context.Context, retrieveResults []*types.RetrieveResult) (
+ vectorResults, keywordResults []*types.IndexWithScore,
+) {
+ for _, retrieveResult := range retrieveResults {
+ logger.Infof(ctx, "Retrieval results, engine: %v, retriever: %v, count: %v",
+ retrieveResult.RetrieverEngineType,
+ retrieveResult.RetrieverType,
+ len(retrieveResult.Results),
+ )
+ if retrieveResult.RetrieverType == types.VectorRetrieverType {
+ vectorResults = append(vectorResults, retrieveResult.Results...)
+ } else {
+ keywordResults = append(keywordResults, retrieveResult.Results...)
+ }
+ }
+ return
+}
+
+// fuseOrDeduplicate either fuses vector+keyword results via RRF or deduplicates vector-only results.
+func fuseOrDeduplicate(ctx context.Context, vectorResults, keywordResults []*types.IndexWithScore) []*types.IndexWithScore {
+ if len(keywordResults) == 0 {
+ // Vector-only: keep original embedding scores (important for FAQ)
+ result := deduplicateByScore(vectorResults)
+ logger.Infof(ctx, "Result count after deduplication: %d", len(result))
+ return result
+ }
+ // Hybrid: use RRF fusion to merge vector + keyword results
+ result := fuseWithRRF(ctx, vectorResults, keywordResults)
+ logger.Infof(ctx, "Result count after RRF fusion: %d", len(result))
+ return result
+}
+
+// sortByScoreDesc is a reusable sort comparator for IndexWithScore slices (descending by Score).
+func sortByScoreDesc(a, b *types.IndexWithScore) int {
+ if a.Score > b.Score {
+ return -1
+ } else if a.Score < b.Score {
+ return 1
+ }
+ return 0
+}
+
+// deduplicateByScore deduplicates retrieval results by chunk ID, keeping the highest score
+// for each chunk. Returns the results sorted by score descending.
+// Used when only a single retriever (e.g. vector-only for FAQ) is active.
+func deduplicateByScore(results []*types.IndexWithScore) []*types.IndexWithScore {
+ chunkInfoMap := make(map[string]*types.IndexWithScore, len(results))
+ for _, r := range results {
+ if existing, exists := chunkInfoMap[r.ChunkID]; !exists || r.Score > existing.Score {
+ chunkInfoMap[r.ChunkID] = r
+ }
+ }
+ deduped := make([]*types.IndexWithScore, 0, len(chunkInfoMap))
+ for _, info := range chunkInfoMap {
+ deduped = append(deduped, info)
+ }
+ slices.SortFunc(deduped, sortByScoreDesc)
+ return deduped
+}
+
+// fuseWithRRF merges vector and keyword retrieval results using Reciprocal Rank Fusion.
+// RRF score = vectorWeight/(k+vectorRank) + keywordWeight/(k+keywordRank), with k=60.
+// The merged results are sorted by RRF score descending.
+func fuseWithRRF(ctx context.Context, vectorResults, keywordResults []*types.IndexWithScore) []*types.IndexWithScore {
+ const rrfK = 60
+ const vectorWeight = 0.7
+ const keywordWeight = 0.3
+
+ // Build rank maps for each retriever (already sorted by score from retriever)
+ vectorRanks := make(map[string]int, len(vectorResults))
+ for i, r := range vectorResults {
+ if _, exists := vectorRanks[r.ChunkID]; !exists {
+ vectorRanks[r.ChunkID] = i + 1 // 1-indexed rank
+ }
+ }
+ keywordRanks := make(map[string]int, len(keywordResults))
+ for i, r := range keywordResults {
+ if _, exists := keywordRanks[r.ChunkID]; !exists {
+ keywordRanks[r.ChunkID] = i + 1
+ }
+ }
+
+ // Collect all unique chunks — prefer vector result's metadata for each chunk
+ chunkInfoMap := make(map[string]*types.IndexWithScore)
+ for _, r := range vectorResults {
+ if existing, exists := chunkInfoMap[r.ChunkID]; !exists || r.Score > existing.Score {
+ chunkInfoMap[r.ChunkID] = r
+ }
+ }
+ for _, r := range keywordResults {
+ if _, exists := chunkInfoMap[r.ChunkID]; !exists {
+ chunkInfoMap[r.ChunkID] = r
+ }
+ }
+
+ // Compute weighted RRF scores and assign to each chunk
+ result := make([]*types.IndexWithScore, 0, len(chunkInfoMap))
+ for chunkID, info := range chunkInfoMap {
+ rrfScore := 0.0
+ if rank, ok := vectorRanks[chunkID]; ok {
+ rrfScore += vectorWeight / float64(rrfK+rank)
+ }
+ if rank, ok := keywordRanks[chunkID]; ok {
+ rrfScore += keywordWeight / float64(rrfK+rank)
+ }
+ info.Score = rrfScore
+ result = append(result, info)
+ }
+ slices.SortFunc(result, sortByScoreDesc)
+
+ // Log top results for debugging
+ for i, chunk := range result {
+ if i >= 15 {
+ break
+ }
+ vRank, vOk := vectorRanks[chunk.ChunkID]
+ kRank, kOk := keywordRanks[chunk.ChunkID]
+ logger.Debugf(ctx, "RRF rank %d: chunk_id=%s, rrf_score=%.6f, vector_rank=%v(%v), keyword_rank=%v(%v)",
+ i, chunk.ChunkID, chunk.Score, vRank, vOk, kRank, kOk)
+ }
+
+ return result
+}
diff --git a/internal/application/service/knowledgebase_search_results.go b/internal/application/service/knowledgebase_search_results.go
new file mode 100644
index 00000000..8d6ff15c
--- /dev/null
+++ b/internal/application/service/knowledgebase_search_results.go
@@ -0,0 +1,288 @@
+package service
+
+import (
+ "context"
+ "encoding/json"
+ "slices"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// processSearchResults handles the processing of search results, optimizing database queries.
+func (s *knowledgeBaseService) processSearchResults(ctx context.Context,
+ chunks []*types.IndexWithScore,
+ skipEnrichment bool,
+) ([]*types.SearchResult, error) {
+ if len(chunks) == 0 {
+ return nil, nil
+ }
+
+ tenantID := types.MustTenantIDFromContext(ctx)
+
+ // Collect all knowledge and chunk IDs, track scores and match info
+ index := s.buildChunkIndex(chunks)
+
+ // Batch fetch knowledge data (include shared KB so cross-tenant retrieval works)
+ logger.Infof(ctx, "Fetching knowledge data for %d IDs", len(index.knowledgeIDs))
+ knowledgeMap, err := s.fetchKnowledgeDataWithShared(ctx, tenantID, index.knowledgeIDs)
+ if err != nil {
+ return nil, err
+ }
+
+ // Batch fetch chunks (include shared KB chunks)
+ logger.Infof(ctx, "Fetching chunk data for %d IDs", len(index.chunkIDs))
+ allChunks, err := s.listChunksByIDWithShared(ctx, tenantID, index.chunkIDs)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, map[string]interface{}{
+ "tenant_id": tenantID,
+ "chunk_ids": index.chunkIDs,
+ })
+ return nil, err
+ }
+ logger.Infof(ctx, "Chunk data fetched successfully, count: %d", len(allChunks))
+
+ // Build chunk map and collect enrichment IDs (parent, related, nearby)
+ chunkMap := make(map[string]*types.Chunk, len(allChunks))
+ for _, chunk := range allChunks {
+ chunkMap[chunk.ID] = chunk
+ }
+
+ if !skipEnrichment {
+ additionalChunkIDs := s.collectEnrichmentChunkIDs(ctx, allChunks, index)
+ if len(additionalChunkIDs) > 0 {
+ logger.Infof(ctx, "Fetching %d additional chunks", len(additionalChunkIDs))
+ additionalChunks, err := s.listChunksByIDWithShared(ctx, tenantID, additionalChunkIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to fetch some additional chunks: %v", err)
+ } else {
+ for _, chunk := range additionalChunks {
+ chunkMap[chunk.ID] = chunk
+ }
+ }
+ }
+ }
+
+ // Build final search results
+ searchResults := s.assembleSearchResults(ctx, chunks, chunkMap, knowledgeMap, index, skipEnrichment)
+ logger.Infof(ctx, "Search results processed, total: %d", len(searchResults))
+ return searchResults, nil
+}
+
+// chunkIndex holds pre-computed lookup structures for processing search results.
+type chunkIndex struct {
+ knowledgeIDs []string
+ chunkIDs []string
+ scores map[string]float64
+ matchTypes map[string]types.MatchType
+ matchedContents map[string]string
+ processedIDs map[string]bool // tracks all IDs (chunk + enrichment) to avoid duplicates
+}
+
+// buildChunkIndex collects knowledge/chunk IDs and builds score/matchType maps
+// from the raw retrieval results.
+func (s *knowledgeBaseService) buildChunkIndex(chunks []*types.IndexWithScore) *chunkIndex {
+ idx := &chunkIndex{
+ scores: make(map[string]float64, len(chunks)),
+ matchTypes: make(map[string]types.MatchType, len(chunks)),
+ matchedContents: make(map[string]string, len(chunks)),
+ processedIDs: make(map[string]bool, len(chunks)*2),
+ }
+
+ processedKnowledgeIDs := make(map[string]bool)
+ for _, chunk := range chunks {
+ if !processedKnowledgeIDs[chunk.KnowledgeID] {
+ idx.knowledgeIDs = append(idx.knowledgeIDs, chunk.KnowledgeID)
+ processedKnowledgeIDs[chunk.KnowledgeID] = true
+ }
+ idx.chunkIDs = append(idx.chunkIDs, chunk.ChunkID)
+ idx.scores[chunk.ChunkID] = chunk.Score
+ idx.matchTypes[chunk.ChunkID] = chunk.MatchType
+ idx.matchedContents[chunk.ChunkID] = chunk.Content
+ }
+ return idx
+}
+
+// collectEnrichmentChunkIDs gathers IDs for parent, related, and nearby chunks
+// that should be fetched to enrich the search results.
+func (s *knowledgeBaseService) collectEnrichmentChunkIDs(
+ ctx context.Context,
+ allChunks []*types.Chunk,
+ idx *chunkIndex,
+) []string {
+ // Mark all primary chunks as processed
+ for _, chunk := range allChunks {
+ idx.processedIDs[chunk.ID] = true
+ }
+
+ var additionalIDs []string
+
+ for _, chunk := range allChunks {
+ // Collect parent chunks
+ if chunk.ParentChunkID != "" && !idx.processedIDs[chunk.ParentChunkID] {
+ additionalIDs = append(additionalIDs, chunk.ParentChunkID)
+ idx.processedIDs[chunk.ParentChunkID] = true
+ idx.scores[chunk.ParentChunkID] = idx.scores[chunk.ID]
+ idx.matchTypes[chunk.ParentChunkID] = types.MatchTypeParentChunk
+ }
+
+ // Collect related chunks
+ relationChunkIDs := s.collectRelatedChunkIDs(chunk, idx.processedIDs)
+ for _, chunkID := range relationChunkIDs {
+ additionalIDs = append(additionalIDs, chunkID)
+ idx.matchTypes[chunkID] = types.MatchTypeRelationChunk
+ }
+
+ // Add nearby chunks (prev and next) for text chunks
+ if slices.Contains([]string{types.ChunkTypeText}, chunk.ChunkType) {
+ if chunk.NextChunkID != "" && !idx.processedIDs[chunk.NextChunkID] {
+ additionalIDs = append(additionalIDs, chunk.NextChunkID)
+ idx.processedIDs[chunk.NextChunkID] = true
+ idx.matchTypes[chunk.NextChunkID] = types.MatchTypeNearByChunk
+ }
+ if chunk.PreChunkID != "" && !idx.processedIDs[chunk.PreChunkID] {
+ additionalIDs = append(additionalIDs, chunk.PreChunkID)
+ idx.processedIDs[chunk.PreChunkID] = true
+ idx.matchTypes[chunk.PreChunkID] = types.MatchTypeNearByChunk
+ }
+ }
+ }
+
+ return additionalIDs
+}
+
+// assembleSearchResults builds the final []*types.SearchResult from chunk data and knowledge data.
+// Primary results (from input chunks) are added first in order, then enrichment results.
+func (s *knowledgeBaseService) assembleSearchResults(
+ ctx context.Context,
+ inputChunks []*types.IndexWithScore,
+ chunkMap map[string]*types.Chunk,
+ knowledgeMap map[string]*types.Knowledge,
+ idx *chunkIndex,
+ skipEnrichment bool,
+) []*types.SearchResult {
+ 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 inputChunks {
+ chunk, exists := chunkMap[inputChunk.ChunkID]
+ if !exists {
+ logger.Debugf(ctx, "Chunk not found in chunkMap: %s", inputChunk.ChunkID)
+ continue
+ }
+ if !s.isValidTextChunk(chunk) {
+ invalidChunkCnt++
+ if len(invalidChunkSamples) < maxInvalidChunkLog {
+ invalidChunkSamples = append(invalidChunkSamples, chunk.ID+":"+chunk.ChunkType)
+ }
+ continue
+ }
+ if addedChunkIDs[chunk.ID] {
+ continue
+ }
+
+ score := idx.scores[chunk.ID]
+ if knowledge, ok := knowledgeMap[chunk.KnowledgeID]; ok {
+ matchType := idx.matchTypes[chunk.ID]
+ matchedContent := idx.matchedContents[chunk.ID]
+ searchResults = append(searchResults, s.buildSearchResult(chunk, knowledge, score, matchType, matchedContent))
+ addedChunkIDs[chunk.ID] = true
+ } else {
+ 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 enrichment chunks (parent, nearby, relation)
+ if !skipEnrichment {
+ for chunkID, chunk := range chunkMap {
+ if addedChunkIDs[chunkID] || !s.isValidTextChunk(chunk) {
+ continue
+ }
+
+ score, hasScore := idx.scores[chunkID]
+ if !hasScore || score <= 0 {
+ score = 0.0
+ }
+
+ if knowledge, ok := knowledgeMap[chunk.KnowledgeID]; ok {
+ matchType := types.MatchTypeParentChunk
+ if specificType, exists := idx.matchTypes[chunkID]; exists {
+ matchType = specificType
+ } else {
+ logger.Warnf(ctx, "Unkonwn match type for chunk: %s", chunkID)
+ continue
+ }
+ matchedContent := idx.matchedContents[chunkID]
+ searchResults = append(searchResults, s.buildSearchResult(chunk, knowledge, score, matchType, matchedContent))
+ }
+ }
+ }
+
+ return searchResults
+}
+
+// collectRelatedChunkIDs extracts related chunk IDs from a chunk.
+func (s *knowledgeBaseService) collectRelatedChunkIDs(chunk *types.Chunk, processedIDs map[string]bool) []string {
+ var relatedIDs []string
+ if len(chunk.RelationChunks) > 0 {
+ var relations []string
+ if err := json.Unmarshal(chunk.RelationChunks, &relations); err == nil {
+ for _, id := range relations {
+ if !processedIDs[id] {
+ relatedIDs = append(relatedIDs, id)
+ processedIDs[id] = true
+ }
+ }
+ }
+ }
+ return relatedIDs
+}
+
+// buildSearchResult creates a search result from chunk and knowledge.
+func (s *knowledgeBaseService) buildSearchResult(chunk *types.Chunk,
+ knowledge *types.Knowledge,
+ score float64,
+ matchType types.MatchType,
+ matchedContent string,
+) *types.SearchResult {
+ return &types.SearchResult{
+ ID: chunk.ID,
+ Content: chunk.Content,
+ KnowledgeID: chunk.KnowledgeID,
+ ChunkIndex: chunk.ChunkIndex,
+ KnowledgeTitle: knowledge.Title,
+ StartAt: chunk.StartAt,
+ EndAt: chunk.EndAt,
+ Seq: chunk.ChunkIndex,
+ Score: score,
+ MatchType: matchType,
+ Metadata: knowledge.GetMetadata(),
+ ChunkType: string(chunk.ChunkType),
+ ParentChunkID: chunk.ParentChunkID,
+ ImageInfo: chunk.ImageInfo,
+ KnowledgeFilename: knowledge.FileName,
+ KnowledgeSource: knowledge.Source,
+ ChunkMetadata: chunk.Metadata,
+ MatchedContent: matchedContent,
+ KnowledgeBaseID: knowledge.KnowledgeBaseID,
+ }
+}
+
+// isValidTextChunk checks if a chunk is a valid text chunk.
+func (s *knowledgeBaseService) isValidTextChunk(chunk *types.Chunk) bool {
+ return slices.Contains([]types.ChunkType{
+ types.ChunkTypeText, types.ChunkTypeSummary,
+ types.ChunkTypeTableColumn, types.ChunkTypeTableSummary,
+ types.ChunkTypeFAQ,
+ }, chunk.ChunkType)
+}
diff --git a/internal/application/service/knowledgebase_search_shared.go b/internal/application/service/knowledgebase_search_shared.go
new file mode 100644
index 00000000..f690d15e
--- /dev/null
+++ b/internal/application/service/knowledgebase_search_shared.go
@@ -0,0 +1,162 @@
+package service
+
+import (
+ "context"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// fetchKnowledgeData gets knowledge data in batch.
+func (s *knowledgeBaseService) fetchKnowledgeData(ctx context.Context,
+ tenantID uint64,
+ knowledgeIDs []string,
+) (map[string]*types.Knowledge, error) {
+ knowledges, err := s.kgRepo.GetKnowledgeBatch(ctx, tenantID, knowledgeIDs)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, map[string]interface{}{
+ "tenant_id": tenantID,
+ "knowledge_ids": knowledgeIDs,
+ })
+ return nil, err
+ }
+
+ knowledgeMap := make(map[string]*types.Knowledge, len(knowledges))
+ for _, knowledge := range knowledges {
+ knowledgeMap[knowledge.ID] = knowledge
+ }
+
+ return knowledgeMap, nil
+}
+
+// fetchKnowledgeDataWithShared gets knowledge data in batch, including knowledge
+// from shared KBs the user has access to.
+func (s *knowledgeBaseService) fetchKnowledgeDataWithShared(ctx context.Context,
+ tenantID uint64,
+ knowledgeIDs []string,
+) (map[string]*types.Knowledge, error) {
+ knowledgeMap, err := s.fetchKnowledgeData(ctx, tenantID, knowledgeIDs)
+ if err != nil {
+ return nil, err
+ }
+
+ missingIDs := s.findMissingIDs(knowledgeIDs, func(id string) bool {
+ return knowledgeMap[id] != nil
+ })
+ if len(missingIDs) == 0 {
+ return knowledgeMap, nil
+ }
+ logger.Infof(ctx, "[fetchKnowledgeDataWithShared] %d knowledge IDs not found in current tenant, attempting shared KB lookup", len(missingIDs))
+
+ userID, ok := s.extractUserID(ctx)
+ if !ok {
+ logger.Warnf(ctx, "[fetchKnowledgeDataWithShared] userID not found or empty in context, skipping shared KB lookup")
+ return knowledgeMap, nil
+ }
+
+ logger.Infof(ctx, "[fetchKnowledgeDataWithShared] Looking up %d missing knowledge IDs with userID=%s", len(missingIDs), userID)
+ for _, id := range missingIDs {
+ k, err := s.kgRepo.GetKnowledgeByIDOnly(ctx, id)
+ if err != nil || k == nil || k.KnowledgeBaseID == "" {
+ logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] Knowledge %s not found or has no KB", id)
+ continue
+ }
+ hasPermission, err := s.kbShareService.HasKBPermission(ctx, k.KnowledgeBaseID, userID, types.OrgRoleViewer)
+ if err != nil {
+ logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] Permission check error for KB %s: %v", k.KnowledgeBaseID, err)
+ continue
+ }
+ if !hasPermission {
+ logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] No permission for KB %s", k.KnowledgeBaseID)
+ continue
+ }
+ logger.Debugf(ctx, "[fetchKnowledgeDataWithShared] Found shared knowledge %s in KB %s", id, k.KnowledgeBaseID)
+ knowledgeMap[k.ID] = k
+ }
+
+ logger.Infof(ctx, "[fetchKnowledgeDataWithShared] After shared lookup, total knowledge found: %d", len(knowledgeMap))
+ return knowledgeMap, nil
+}
+
+// listChunksByIDWithShared fetches chunks by IDs, including chunks from shared KBs the user has access to.
+func (s *knowledgeBaseService) listChunksByIDWithShared(ctx context.Context,
+ tenantID uint64,
+ chunkIDs []string,
+) ([]*types.Chunk, error) {
+ chunks, err := s.chunkRepo.ListChunksByID(ctx, tenantID, chunkIDs)
+ if err != nil {
+ return nil, err
+ }
+
+ foundSet := make(map[string]bool, len(chunks))
+ for _, c := range chunks {
+ if c != nil {
+ foundSet[c.ID] = true
+ }
+ }
+
+ missing := s.findMissingIDs(chunkIDs, func(id string) bool {
+ return foundSet[id]
+ })
+ if len(missing) == 0 {
+ return chunks, nil
+ }
+ logger.Infof(ctx, "[listChunksByIDWithShared] %d chunks not found in current tenant, attempting shared KB lookup", len(missing))
+
+ userID, ok := s.extractUserID(ctx)
+ if !ok {
+ logger.Warnf(ctx, "[listChunksByIDWithShared] userID not found or empty in context, skipping shared KB lookup")
+ return chunks, nil
+ }
+
+ logger.Infof(ctx, "[listChunksByIDWithShared] Looking up %d missing chunks with userID=%s", len(missing), userID)
+ crossChunks, err := s.chunkRepo.ListChunksByIDOnly(ctx, missing)
+ if err != nil {
+ logger.Warnf(ctx, "[listChunksByIDWithShared] Failed to fetch chunks by ID only: %v", err)
+ return chunks, nil
+ }
+ logger.Infof(ctx, "[listChunksByIDWithShared] Found %d chunks without tenant filter", len(crossChunks))
+
+ for _, c := range crossChunks {
+ if c == nil || c.KnowledgeBaseID == "" {
+ continue
+ }
+ hasPermission, err := s.kbShareService.HasKBPermission(ctx, c.KnowledgeBaseID, userID, types.OrgRoleViewer)
+ if err != nil {
+ logger.Debugf(ctx, "[listChunksByIDWithShared] Permission check error for KB %s: %v", c.KnowledgeBaseID, err)
+ continue
+ }
+ if !hasPermission {
+ logger.Debugf(ctx, "[listChunksByIDWithShared] No permission for KB %s", c.KnowledgeBaseID)
+ continue
+ }
+ chunks = append(chunks, c)
+ }
+
+ logger.Infof(ctx, "[listChunksByIDWithShared] After shared lookup, total chunks: %d", len(chunks))
+ return chunks, nil
+}
+
+// findMissingIDs returns IDs from the input slice that are not found by the exists predicate.
+func (s *knowledgeBaseService) findMissingIDs(ids []string, exists func(string) bool) []string {
+ var missing []string
+ for _, id := range ids {
+ if !exists(id) {
+ missing = append(missing, id)
+ }
+ }
+ return missing
+}
+
+// extractUserID extracts the user ID from context, returning ("", false) if not found.
+func (s *knowledgeBaseService) extractUserID(ctx context.Context) (string, bool) {
+ userIDVal := ctx.Value(types.UserIDContextKey)
+ if userIDVal == nil {
+ return "", false
+ }
+ userID, ok := userIDVal.(string)
+ if !ok || userID == "" {
+ return "", false
+ }
+ return userID, true
+}
diff --git a/internal/application/service/session.go b/internal/application/service/session.go
index a1841b25..d66bfded 100644
--- a/internal/application/service/session.go
+++ b/internal/application/service/session.go
@@ -2,26 +2,20 @@ package service
import (
"context"
- "encoding/json"
"errors"
"fmt"
- "os"
"strings"
- "github.com/Tencent/WeKnora/internal/agent/tools"
- chatpipline "github.com/Tencent/WeKnora/internal/application/service/chat_pipline"
- llmcontext "github.com/Tencent/WeKnora/internal/application/service/llmcontext"
"github.com/Tencent/WeKnora/internal/config"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/chat"
- "github.com/Tencent/WeKnora/internal/models/rerank"
- "github.com/Tencent/WeKnora/internal/tracing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/google/uuid"
- "go.opentelemetry.io/otel/attribute"
- "go.opentelemetry.io/otel/codes"
+
+ chatpipline "github.com/Tencent/WeKnora/internal/application/service/chat_pipline"
+ llmcontext "github.com/Tencent/WeKnora/internal/application/service/llmcontext"
)
// generateEventID generates a unique event ID with type suffix for better traceability
@@ -508,1339 +502,9 @@ func (s *sessionService) GenerateTitleAsync(
}()
}
-// KnowledgeQA performs knowledge base question answering with LLM summarization
-// Events are emitted through eventBus (references, answer chunks, completion)
-// customAgent is optional - if provided, uses custom agent configuration for multiTurnEnabled and historyTurns
-func (s *sessionService) KnowledgeQA(
- ctx context.Context,
- 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, imageDescription string, userMessageID string,
-) error {
- logger.Infof(
- ctx,
- "Knowledge base question answering parameters, session ID: %s, query: %s, webSearchEnabled: %v, enableMemory: %v",
- session.ID,
- query,
- webSearchEnabled,
- enableMemory,
- )
-
- // Use custom agent's knowledge bases only if request didn't specify any
- // When user explicitly @mentions a knowledge base or document, only search those
- // If RetrieveKBOnlyWhenMentioned is enabled and no @ mentions, don't use KB at all
- hasExplicitMention := len(knowledgeBaseIDs) > 0 || len(knowledgeIDs) > 0
- if customAgent != nil {
- logger.Infof(ctx, "KB resolution (quick-answer): hasExplicitMention=%v, RetrieveKBOnlyWhenMentioned=%v, KBSelectionMode=%s",
- hasExplicitMention, customAgent.Config.RetrieveKBOnlyWhenMentioned, customAgent.Config.KBSelectionMode)
- }
- if hasExplicitMention {
- logger.Infof(ctx, "Using request-specified targets (ignoring agent config): kbs=%v, docs=%v", knowledgeBaseIDs, knowledgeIDs)
- } else if customAgent != nil && customAgent.Config.RetrieveKBOnlyWhenMentioned {
- // User didn't mention any KB/file, and the setting requires explicit mention
- knowledgeBaseIDs = nil
- knowledgeIDs = nil
- logger.Infof(ctx, "RetrieveKBOnlyWhenMentioned is enabled and no @ mention found, KB retrieval disabled for this request")
- } else {
- knowledgeBaseIDs = s.resolveKnowledgeBasesFromAgent(ctx, customAgent, session.TenantID)
- }
-
- // Determine chat model ID priority:
- // 1. Request's summaryModelID (explicit override)
- // 2. Custom agent's ModelID (agent configuration)
- // 3. KB / session / system default model (legacy fallback)
- var chatModelID string
- if summaryModelID != "" {
- if model, err := s.modelService.GetModelByID(ctx, summaryModelID); err == nil && model != nil {
- chatModelID = summaryModelID
- logger.Infof(ctx, "Using request's summary model override: %s", chatModelID)
- } else {
- logger.Warnf(ctx, "Request provided invalid summary model ID %s: %v, falling back", summaryModelID, err)
- }
- }
- if chatModelID == "" && customAgent != nil && customAgent.Config.ModelID != "" {
- chatModelID = customAgent.Config.ModelID
- logger.Infof(ctx, "Using custom agent's model_id: %s", chatModelID)
- }
- if chatModelID == "" {
- var err error
- chatModelID, err = s.selectChatModelID(ctx, session, knowledgeBaseIDs, knowledgeIDs)
- if err != nil {
- return err
- }
- }
-
- // Initialize default values from config.yaml
- rewritePromptSystem := s.cfg.Conversation.RewritePromptSystem
- rewritePromptUser := s.cfg.Conversation.RewritePromptUser
- vectorThreshold := s.cfg.Conversation.VectorThreshold
- keywordThreshold := s.cfg.Conversation.KeywordThreshold
- embeddingTopK := s.cfg.Conversation.EmbeddingTopK
- rerankTopK := s.cfg.Conversation.RerankTopK
- rerankThreshold := s.cfg.Conversation.RerankThreshold
- maxRounds := s.cfg.Conversation.MaxRounds
- fallbackStrategy := types.FallbackStrategy(s.cfg.Conversation.FallbackStrategy)
- fallbackResponse := s.cfg.Conversation.FallbackResponse
- fallbackPrompt := s.cfg.Conversation.FallbackPrompt
- enableRewrite := s.cfg.Conversation.EnableRewrite
- enableQueryExpansion := s.cfg.Conversation.EnableQueryExpansion
- rerankModelID := ""
-
- summaryConfig := types.SummaryConfig{
- Prompt: s.cfg.Conversation.Summary.Prompt,
- ContextTemplate: s.cfg.Conversation.Summary.ContextTemplate,
- Temperature: s.cfg.Conversation.Summary.Temperature,
- NoMatchPrefix: s.cfg.Conversation.Summary.NoMatchPrefix,
- MaxCompletionTokens: s.cfg.Conversation.Summary.MaxCompletionTokens,
- Thinking: s.cfg.Conversation.Summary.Thinking,
- }
-
- // Set default fallback strategy if not set
- if fallbackStrategy == "" {
- fallbackStrategy = types.FallbackStrategyFixed
- logger.Infof(ctx, "Fallback strategy not set, using default: %v", fallbackStrategy)
- }
-
- // Apply custom agent configuration if provided
- if customAgent != nil {
- // Ensure defaults are set
- customAgent.EnsureDefaults()
-
- // Override system prompt
- if customAgent.Config.SystemPrompt != "" {
- summaryConfig.Prompt = customAgent.Config.SystemPrompt
- logger.Infof(ctx, "Using custom agent's system_prompt")
- }
- // Override context template
- if customAgent.Config.ContextTemplate != "" {
- summaryConfig.ContextTemplate = customAgent.Config.ContextTemplate
- logger.Infof(ctx, "Using custom agent's context_template")
- }
- // Override temperature
- if customAgent.Config.Temperature > 0 {
- summaryConfig.Temperature = customAgent.Config.Temperature
- logger.Infof(ctx, "Using custom agent's temperature: %f", customAgent.Config.Temperature)
- }
- // Override max completion tokens
- if customAgent.Config.MaxCompletionTokens > 0 {
- summaryConfig.MaxCompletionTokens = customAgent.Config.MaxCompletionTokens
- logger.Infof(ctx, "Using custom agent's max_completion_tokens: %d", customAgent.Config.MaxCompletionTokens)
- }
- // Override thinking mode from agent config
- // Agent-level thinking setting takes full control (no global fallback)
- summaryConfig.Thinking = customAgent.Config.Thinking
- if customAgent.Config.Thinking != nil {
- logger.Infof(ctx, "Using custom agent's thinking: %v", *customAgent.Config.Thinking)
- }
- // Override retrieval strategy settings
- if customAgent.Config.EmbeddingTopK > 0 {
- embeddingTopK = customAgent.Config.EmbeddingTopK
- }
- if customAgent.Config.KeywordThreshold > 0 {
- keywordThreshold = customAgent.Config.KeywordThreshold
- }
- if customAgent.Config.VectorThreshold > 0 {
- vectorThreshold = customAgent.Config.VectorThreshold
- }
- if customAgent.Config.RerankTopK > 0 {
- rerankTopK = customAgent.Config.RerankTopK
- }
- if customAgent.Config.RerankThreshold > 0 {
- rerankThreshold = customAgent.Config.RerankThreshold
- }
- if customAgent.Config.RerankModelID != "" {
- rerankModelID = customAgent.Config.RerankModelID
- }
- // Override rewrite settings
- enableRewrite = customAgent.Config.EnableRewrite
- enableQueryExpansion = customAgent.Config.EnableQueryExpansion
- if customAgent.Config.RewritePromptSystem != "" {
- rewritePromptSystem = customAgent.Config.RewritePromptSystem
- }
- if customAgent.Config.RewritePromptUser != "" {
- rewritePromptUser = customAgent.Config.RewritePromptUser
- }
- // Override fallback settings
- if customAgent.Config.FallbackStrategy != "" {
- fallbackStrategy = types.FallbackStrategy(customAgent.Config.FallbackStrategy)
- }
- if customAgent.Config.FallbackResponse != "" {
- fallbackResponse = customAgent.Config.FallbackResponse
- }
- if customAgent.Config.FallbackPrompt != "" {
- fallbackPrompt = customAgent.Config.FallbackPrompt
- }
- // Override history turns
- if customAgent.Config.HistoryTurns > 0 {
- maxRounds = customAgent.Config.HistoryTurns
- logger.Infof(ctx, "Using custom agent's history_turns: %d", maxRounds)
- }
- // Check if multi-turn is disabled
- if !customAgent.Config.MultiTurnEnabled {
- maxRounds = 0 // Disable history
- logger.Infof(ctx, "Multi-turn disabled by custom agent, clearing history")
- }
- }
-
- // Extract FAQ strategy settings from custom agent
- var faqPriorityEnabled bool
- var faqDirectAnswerThreshold float64
- var faqScoreBoost float64
- if customAgent != nil {
- faqPriorityEnabled = customAgent.Config.FAQPriorityEnabled
- faqDirectAnswerThreshold = customAgent.Config.FAQDirectAnswerThreshold
- faqScoreBoost = customAgent.Config.FAQScoreBoost
- if faqPriorityEnabled {
- logger.Infof(ctx, "FAQ priority enabled: threshold=%.2f, boost=%.2f",
- faqDirectAnswerThreshold, faqScoreBoost)
- }
- }
-
- // Resolve chat model vision capability and VLM model ID for image routing
- var chatModelSupportsVision bool
- var vlmModelID string
- if chatModelID != "" {
- if chatModelInfo, err := s.modelService.GetModelByID(ctx, chatModelID); err == nil && chatModelInfo != nil {
- chatModelSupportsVision = chatModelInfo.Parameters.SupportsVision
- }
- }
- if customAgent != nil {
- vlmModelID = customAgent.Config.VLMModelID
- }
-
- // Retrieval scope: when agent is set, use agent's tenant (own or shared); otherwise session tenant or context
- retrievalTenantID := session.TenantID
- if customAgent != nil && customAgent.TenantID != 0 {
- retrievalTenantID = customAgent.TenantID
- logger.Infof(ctx, "Using agent tenant %d for retrieval scope", retrievalTenantID)
- } else if v := ctx.Value(types.TenantIDContextKey); v != nil {
- if tid, ok := v.(uint64); ok && tid != 0 {
- retrievalTenantID = tid
- logger.Infof(ctx, "Using effective tenant %d for retrieval from context", retrievalTenantID)
- }
- }
-
- // Build unified search targets (computed once, used throughout pipeline)
- searchTargets, err := s.buildSearchTargets(ctx, retrievalTenantID, knowledgeBaseIDs, knowledgeIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to build search targets: %v", err)
- }
-
- // Create chat management object with session settings
- logger.Infof(
- ctx,
- "Creating chat manage object, knowledge base IDs: %v, knowledge IDs: %v, chat model ID: %s, search targets: %d",
- knowledgeBaseIDs,
- knowledgeIDs,
- chatModelID,
- len(searchTargets),
- )
-
- // Get UserID from context
- userID, _ := types.UserIDFromContext(ctx)
-
- chatManage := &types.ChatManage{
- Query: query,
- RewriteQuery: query,
- SessionID: session.ID,
- UserID: userID,
- MessageID: assistantMessageID, // NEW: For event emission in pipeline
- KnowledgeBaseIDs: knowledgeBaseIDs, // Multi-KB support
- KnowledgeIDs: knowledgeIDs, // Specific knowledge (file) IDs
- SearchTargets: searchTargets, // Pre-computed search targets
- VectorThreshold: vectorThreshold,
- KeywordThreshold: keywordThreshold,
- EmbeddingTopK: embeddingTopK,
- RerankModelID: rerankModelID,
- RerankTopK: rerankTopK,
- RerankThreshold: rerankThreshold,
- MaxRounds: maxRounds,
- ChatModelID: chatModelID,
- SummaryConfig: summaryConfig,
- FallbackStrategy: fallbackStrategy,
- FallbackResponse: fallbackResponse,
- FallbackPrompt: fallbackPrompt,
- EventBus: eventBus.AsEventBusInterface(), // NEW: For pipeline to emit events directly
- WebSearchEnabled: webSearchEnabled,
- EnableMemory: enableMemory, // Enable memory feature
- TenantID: retrievalTenantID, // Effective tenant for retrieval (shared agent = agent's tenant)
- RewritePromptSystem: rewritePromptSystem,
- RewritePromptUser: rewritePromptUser,
- EnableRewrite: enableRewrite,
- EnableQueryExpansion: enableQueryExpansion,
- // FAQ Strategy Settings
- FAQPriorityEnabled: faqPriorityEnabled,
- FAQDirectAnswerThreshold: faqDirectAnswerThreshold,
- FAQScoreBoost: faqScoreBoost,
- // Image support
- UserMessageID: userMessageID,
- Images: imageURLs,
- ImageDescription: imageDescription,
- VLMModelID: vlmModelID,
- ChatModelSupportsVision: chatModelSupportsVision,
- }
-
- // Determine pipeline based on knowledge bases availability and web search setting
- // If no knowledge bases are selected AND web search is disabled, use pure chat pipeline
- // Otherwise use rag_stream pipeline (which handles both KB search and web search)
- var pipeline []types.EventType
- if len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) == 0 && !webSearchEnabled {
- logger.Info(ctx, "No knowledge bases selected and web search disabled, using chat pipeline")
- // 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 imageDescription != "" && !chatModelSupportsVision {
- userContent += "\n\n[用户上传图片内容]\n" + imageDescription
- }
- chatManage.UserContent = userContent
-
- // Use chat_history_stream if multi-turn is enabled, otherwise use chat_stream
- if maxRounds > 0 {
- logger.Infof(ctx, "Multi-turn enabled with maxRounds=%d, using chat_history_stream pipeline", maxRounds)
- pipeline = types.Pipline["chat_history_stream"]
- } else {
- logger.Info(ctx, "Multi-turn disabled, using chat_stream pipeline")
- pipeline = types.Pipline["chat_stream"]
- }
- } else {
- if webSearchEnabled && len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) == 0 {
- logger.Info(ctx, "Web search enabled without knowledge bases, using rag_stream pipeline for web search only")
- } else {
- logger.Info(ctx, "Knowledge bases selected, using rag_stream pipeline")
- }
- pipeline = types.Pipline["rag_stream"]
- }
-
- // Start knowledge QA event processing (set session tenant so pipeline session/message lookups use session owner)
- ctx = context.WithValue(ctx, types.SessionTenantIDContextKey, session.TenantID)
- logger.Info(ctx, "Triggering question answering event")
- err = s.KnowledgeQAByEvent(ctx, chatManage, pipeline)
- if err != nil {
- logger.ErrorWithFields(ctx, err, map[string]interface{}{
- "session_id": session.ID,
- })
- return err
- }
-
- // Emit references event if we have search results
- if len(chatManage.MergeResult) > 0 {
- logger.Infof(ctx, "Emitting references event with %d results", len(chatManage.MergeResult))
- if err := eventBus.Emit(ctx, event.Event{
- ID: generateEventID("references"),
- Type: event.EventAgentReferences,
- SessionID: session.ID,
- Data: event.AgentReferencesData{
- References: chatManage.MergeResult,
- },
- }); err != nil {
- logger.Errorf(ctx, "Failed to emit references event: %v", err)
- }
- }
-
- // Note: Answer events are now emitted directly by chat_completion_stream plugin
- // Completion event will be emitted when the last answer event has Done=true
- // We can optionally add a completion watcher here if needed, but for now
- // the frontend can detect completion from the Done flag
-
- logger.Info(ctx, "Knowledge base question answering initiated")
- return nil
-}
-
-// selectChatModelID selects the appropriate chat model ID with priority for Remote models
-// Priority order:
-// 1. Session's SummaryModelID if it's a Remote model
-// 2. First knowledge base with a Remote model (from knowledgeBaseIDs or derived from knowledgeIDs)
-// 3. Session's SummaryModelID (if not Remote)
-// 4. First knowledge base's SummaryModelID
-func (s *sessionService) selectChatModelID(
- ctx context.Context,
- session *types.Session,
- knowledgeBaseIDs []string,
- knowledgeIDs []string,
-) (string, error) {
- // If no knowledge base IDs but have knowledge IDs, derive KB IDs from knowledge IDs (include shared KB files)
- if len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) > 0 {
- tenantID := types.MustTenantIDFromContext(ctx)
- knowledgeList, err := s.knowledgeService.GetKnowledgeBatchWithSharedAccess(ctx, tenantID, knowledgeIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to get knowledge batch for model selection: %v", err)
- } else {
- // Collect unique KB IDs from knowledge items
- kbIDSet := make(map[string]bool)
- for _, k := range knowledgeList {
- if k != nil && k.KnowledgeBaseID != "" {
- kbIDSet[k.KnowledgeBaseID] = true
- }
- }
- for kbID := range kbIDSet {
- knowledgeBaseIDs = append(knowledgeBaseIDs, kbID)
- }
- logger.Infof(ctx, "Derived %d knowledge base IDs from %d knowledge IDs for model selection",
- len(knowledgeBaseIDs), len(knowledgeIDs))
- }
- }
- // Check knowledge bases for models
- if len(knowledgeBaseIDs) > 0 {
- // Try to find a knowledge base with Remote model
- for _, kbID := range knowledgeBaseIDs {
- kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, kbID)
- if err != nil {
- logger.Warnf(ctx, "Failed to get knowledge base: %v", err)
- continue
- }
- if kb != nil && kb.SummaryModelID != "" {
- model, err := s.modelService.GetModelByID(ctx, kb.SummaryModelID)
- if err == nil && model != nil && model.Source == types.ModelSourceRemote {
- logger.Info(ctx, "Using Remote summary model from knowledge base")
- return kb.SummaryModelID, nil
- }
- }
- }
-
- // If no Remote model found, use first knowledge base's model
- kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, knowledgeBaseIDs[0])
- if err != nil {
- logger.Errorf(ctx, "Failed to get knowledge base for model ID: %v", err)
- return "", fmt.Errorf("failed to get knowledge base %s: %w", knowledgeBaseIDs[0], err)
- }
- if kb != nil && kb.SummaryModelID != "" {
- logger.Infof(
- ctx,
- "Using summary model from first knowledge base %s: %s",
- knowledgeBaseIDs[0],
- kb.SummaryModelID,
- )
- return kb.SummaryModelID, nil
- }
- }
-
- // No knowledge bases - try to find any available chat model
- models, err := s.modelService.ListModels(ctx)
- if err != nil {
- logger.Errorf(ctx, "Failed to list models: %v", err)
- return "", fmt.Errorf("failed to list models: %w", err)
- }
- for _, model := range models {
- if model != nil && model.Type == types.ModelTypeKnowledgeQA {
- logger.Infof(ctx, "Using first available KnowledgeQA model: %s", model.ID)
- return model.ID, nil
- }
- }
-
- logger.Error(ctx, "No chat model ID available")
- return "", errors.New("no chat model ID available: no knowledge bases configured and no available models")
-}
-
-// resolveKnowledgeBasesFromAgent resolves knowledge base IDs based on agent's KBSelectionMode.
-// sessionTenantID is the tenant of the current session (caller); it is compared with
-// customAgent.TenantID to detect the shared-agent scenario and avoid leaking the
-// current user's personal shared KBs into the agent's retrieval scope.
-//
-// Returns the resolved knowledge base IDs based on the selection mode:
-// - "all": fetches all knowledge bases for the tenant
-// - "selected": uses the explicitly configured knowledge bases
-// - "none": returns empty slice
-// - default: falls back to configured knowledge bases for backward compatibility
-func (s *sessionService) resolveKnowledgeBasesFromAgent(
- ctx context.Context,
- customAgent *types.CustomAgent,
- sessionTenantID uint64,
-) []string {
- if customAgent == nil {
- return nil
- }
-
- switch customAgent.Config.KBSelectionMode {
- case "all":
- // Get own knowledge bases (uses ctx TenantID = agent's tenant)
- allKBs, err := s.knowledgeBaseService.ListKnowledgeBases(ctx)
- if err != nil {
- logger.Warnf(ctx, "Failed to list all knowledge bases: %v", err)
- }
- kbIDSet := make(map[string]bool)
- kbIDs := make([]string, 0, len(allKBs))
- for _, kb := range allKBs {
- kbIDs = append(kbIDs, kb.ID)
- kbIDSet[kb.ID] = true
- }
-
- // For shared agents (session tenant != agent tenant), only use the agent
- // tenant's own KBs. Including the current user's shared KBs would leak
- // unrelated KBs from other organisations into the agent's retrieval scope.
- isSharedAgent := sessionTenantID != 0 && sessionTenantID != customAgent.TenantID
- if !isSharedAgent {
- tenantID := types.MustTenantIDFromContext(ctx)
- userIDVal := ctx.Value(types.UserIDContextKey)
- if userIDVal != nil {
- if userID, ok := userIDVal.(string); ok && userID != "" && s.kbShareService != nil {
- sharedList, err := s.kbShareService.ListSharedKnowledgeBases(ctx, userID, tenantID)
- if err != nil {
- logger.Warnf(ctx, "Failed to list shared knowledge bases: %v", err)
- } else {
- for _, info := range sharedList {
- if info != nil && info.KnowledgeBase != nil && !kbIDSet[info.KnowledgeBase.ID] {
- kbIDs = append(kbIDs, info.KnowledgeBase.ID)
- kbIDSet[info.KnowledgeBase.ID] = true
- }
- }
- }
- }
- }
- } else {
- logger.Infof(ctx, "Shared agent detected (session tenant %d != agent tenant %d): skipping user's shared KBs",
- sessionTenantID, customAgent.TenantID)
- }
-
- logger.Infof(ctx, "KBSelectionMode=all: loaded %d knowledge bases (own + shared)", len(kbIDs))
- return kbIDs
- case "selected":
- logger.Infof(ctx, "KBSelectionMode=selected: using %d configured knowledge bases", len(customAgent.Config.KnowledgeBases))
- return customAgent.Config.KnowledgeBases
- case "none":
- logger.Infof(ctx, "KBSelectionMode=none: no knowledge bases configured")
- return nil
- default:
- // Default to "selected" behavior for backward compatibility
- if len(customAgent.Config.KnowledgeBases) > 0 {
- logger.Infof(ctx, "KBSelectionMode not set: using %d configured knowledge bases", len(customAgent.Config.KnowledgeBases))
- }
- return customAgent.Config.KnowledgeBases
- }
-}
-
-// configureSkillsFromAgent configures skills settings in AgentConfig based on CustomAgentConfig
-// Returns the skill directories and allowed skills based on the selection mode:
-// - "all": uses all preloaded skills
-// - "selected": uses the explicitly selected skills
-// - "none" or "": skills are disabled
-func (s *sessionService) configureSkillsFromAgent(
- ctx context.Context,
- agentConfig *types.AgentConfig,
- customAgent *types.CustomAgent,
-) {
- if customAgent == nil {
- return
- }
- // When sandbox is disabled, skills cannot be enabled (no script execution environment)
- sandboxMode := os.Getenv("WEKNORA_SANDBOX_MODE")
- if sandboxMode == "" || sandboxMode == "disabled" {
- agentConfig.SkillsEnabled = false
- agentConfig.SkillDirs = nil
- agentConfig.AllowedSkills = nil
- logger.Infof(ctx, "Sandbox is disabled: skills are not available")
- return
- }
-
- switch customAgent.Config.SkillsSelectionMode {
- case "all":
- // Enable all preloaded skills
- agentConfig.SkillsEnabled = true
- agentConfig.SkillDirs = []string{DefaultPreloadedSkillsDir}
- agentConfig.AllowedSkills = nil // Empty means all skills allowed
- logger.Infof(ctx, "SkillsSelectionMode=all: enabled all preloaded skills")
- case "selected":
- // Enable only selected skills
- if len(customAgent.Config.SelectedSkills) > 0 {
- agentConfig.SkillsEnabled = true
- agentConfig.SkillDirs = []string{DefaultPreloadedSkillsDir}
- agentConfig.AllowedSkills = customAgent.Config.SelectedSkills
- logger.Infof(ctx, "SkillsSelectionMode=selected: enabled %d selected skills: %v",
- len(customAgent.Config.SelectedSkills), customAgent.Config.SelectedSkills)
- } else {
- agentConfig.SkillsEnabled = false
- logger.Infof(ctx, "SkillsSelectionMode=selected but no skills selected: skills disabled")
- }
- case "none", "":
- // Skills disabled
- agentConfig.SkillsEnabled = false
- logger.Infof(ctx, "SkillsSelectionMode=%s: skills disabled", customAgent.Config.SkillsSelectionMode)
- default:
- // Unknown mode, disable skills
- agentConfig.SkillsEnabled = false
- logger.Warnf(ctx, "Unknown SkillsSelectionMode=%s: skills disabled", customAgent.Config.SkillsSelectionMode)
- }
-
-}
-
-// buildSearchTargets computes the unified search targets from knowledgeBaseIDs and knowledgeIDs.
-// tenantID is the retrieval scope: session.TenantID or effective tenant from shared agent (set by handler).
-// This is called once at the request entry point to avoid repeated queries later in the pipeline.
-// Logic:
-// - For each knowledgeBaseID: resolve actual TenantID (own, org-shared, or in retrieval-tenant scope for shared agent)
-// - For each knowledgeID: find its knowledgeBaseID; if the KB is already in the list, skip; otherwise add SearchTargetTypeKnowledge
-func (s *sessionService) buildSearchTargets(
- ctx context.Context,
- tenantID uint64,
- knowledgeBaseIDs []string,
- knowledgeIDs []string,
-) (types.SearchTargets, error) {
- var targets types.SearchTargets
-
- // Build a map from KB ID to TenantID for all KBs we need to process
- kbTenantMap := make(map[string]uint64)
-
- // Track which KBs are fully searched
- fullKBSet := make(map[string]bool)
-
- // First pass: batch-fetch KBs, then resolve tenant per ID (tenant scope already set by caller)
- if len(knowledgeBaseIDs) > 0 {
- kbs, _ := s.knowledgeBaseService.GetKnowledgeBasesByIDsOnly(ctx, knowledgeBaseIDs)
- kbByID := make(map[string]*types.KnowledgeBase, len(kbs))
- for _, kb := range kbs {
- if kb != nil {
- kbByID[kb.ID] = kb
- }
- }
- userID, _ := types.UserIDFromContext(ctx)
- for _, kbID := range knowledgeBaseIDs {
- fullKBSet[kbID] = true
- kb := kbByID[kbID]
- if kb == nil {
- kbTenantMap[kbID] = tenantID
- } else if kb.TenantID == tenantID {
- kbTenantMap[kbID] = tenantID
- } else if s.kbShareService != nil && userID != "" {
- hasAccess, _ := s.kbShareService.HasKBPermission(ctx, kbID, userID, types.OrgRoleViewer)
- if hasAccess {
- kbTenantMap[kbID] = kb.TenantID
- } else {
- kbTenantMap[kbID] = tenantID
- }
- } else {
- kbTenantMap[kbID] = tenantID
- }
- targets = append(targets, &types.SearchTarget{
- Type: types.SearchTargetTypeKnowledgeBase,
- KnowledgeBaseID: kbID,
- TenantID: kbTenantMap[kbID],
- })
- }
- }
-
- // Process individual knowledge IDs (include shared KB files the user has access to)
- if len(knowledgeIDs) > 0 {
- knowledgeList, err := s.knowledgeService.GetKnowledgeBatchWithSharedAccess(ctx, tenantID, knowledgeIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to get knowledge batch for search targets: %v", err)
- return targets, nil // Return what we have, don't fail
- }
-
- // Group knowledge IDs by their KB, excluding those already covered by full KB search
- // Also track KB tenant IDs from knowledge items
- kbToKnowledgeIDs := make(map[string][]string)
- for _, k := range knowledgeList {
- if k == nil || k.KnowledgeBaseID == "" {
- continue
- }
- // Track KB -> TenantID mapping from knowledge items
- if kbTenantMap[k.KnowledgeBaseID] == 0 {
- kbTenantMap[k.KnowledgeBaseID] = k.TenantID
- }
- // Skip if this KB is already fully searched
- if fullKBSet[k.KnowledgeBaseID] {
- continue
- }
- kbToKnowledgeIDs[k.KnowledgeBaseID] = append(kbToKnowledgeIDs[k.KnowledgeBaseID], k.ID)
- }
-
- // Create SearchTargetTypeKnowledge targets for each KB with specific files
- for kbID, kidList := range kbToKnowledgeIDs {
- kbTenant := kbTenantMap[kbID]
- if kbTenant == 0 {
- kbTenant = tenantID // fallback
- }
- targets = append(targets, &types.SearchTarget{
- Type: types.SearchTargetTypeKnowledge,
- KnowledgeBaseID: kbID,
- TenantID: kbTenant,
- KnowledgeIDs: kidList,
- })
- }
- }
-
- logger.Infof(ctx, "Built %d search targets: %d full KB, %d partial KB, kbTenantMap=%v",
- len(targets), len(knowledgeBaseIDs), len(targets)-len(knowledgeBaseIDs), kbTenantMap)
-
- return targets, nil
-}
-
-// KnowledgeQAByEvent processes knowledge QA through a series of events in the pipeline
-func (s *sessionService) KnowledgeQAByEvent(ctx context.Context,
- chatManage *types.ChatManage, eventList []types.EventType,
-) error {
- ctx, span := tracing.ContextWithSpan(ctx, "SessionService.KnowledgeQAByEvent")
- defer span.End()
-
- logger.Info(ctx, "Start processing knowledge base question answering through events")
- logger.Infof(ctx, "Knowledge base question answering parameters, session ID: %s, query: %s",
- chatManage.SessionID, chatManage.Query)
-
- // Prepare method list for logging and tracing
- methods := []string{}
- for _, event := range eventList {
- methods = append(methods, string(event))
- }
-
- // Set up tracing attributes
- logger.Infof(ctx, "Trigger event list: %v", methods)
- span.SetAttributes(
- attribute.String("request_id", func() string { id, _ := types.RequestIDFromContext(ctx); return id }()),
- attribute.String("query", chatManage.Query),
- attribute.String("method", strings.Join(methods, ",")),
- )
-
- // Process each event in sequence
- for _, eventType := range eventList {
- logger.Infof(ctx, "Starting to trigger event: %v", eventType)
- err := s.eventManager.Trigger(ctx, eventType, chatManage)
-
- // Handle case where search returns no results
- if err == chatpipline.ErrSearchNothing {
- logger.Warnf(
- ctx,
- "Event %v triggered, search result is empty, using fallback response, strategy: %v",
- eventType,
- chatManage.FallbackStrategy,
- )
- s.handleFallbackResponse(ctx, chatManage)
- return nil
- }
-
- // Handle other errors
- if err != nil {
- logger.Errorf(ctx, "Event triggering failed, event: %v, error type: %s, description: %s, error: %v",
- eventType, err.ErrorType, err.Description, err.Err)
- span.RecordError(err.Err)
- span.SetStatus(codes.Error, err.Description)
- span.SetAttributes(attribute.String("error_type", err.ErrorType))
- return err.Err
- }
- logger.Infof(ctx, "Event %v triggered successfully", eventType)
- }
-
- logger.Info(ctx, "All events triggered successfully")
- return nil
-}
-
-// SearchKnowledge performs knowledge base search without LLM summarization
-// knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB)
-// knowledgeIDs: list of specific knowledge (file) IDs to search
-func (s *sessionService) SearchKnowledge(ctx context.Context,
- knowledgeBaseIDs []string, knowledgeIDs []string, query string,
-) ([]*types.SearchResult, error) {
- logger.Info(ctx, "Start knowledge base search without LLM summary")
- logger.Infof(ctx, "Knowledge base search parameters, knowledge base IDs: %v, knowledge IDs: %v, query: %s",
- knowledgeBaseIDs, knowledgeIDs, query)
-
- // Get tenant ID from context
- tenantID, ok := types.TenantIDFromContext(ctx)
- if !ok {
- logger.Error(ctx, "Failed to get tenant ID from context")
- return nil, fmt.Errorf("tenant ID not found in context")
- }
-
- // Build unified search targets (computed once, used throughout pipeline)
- searchTargets, err := s.buildSearchTargets(ctx, tenantID, knowledgeBaseIDs, knowledgeIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to build search targets: %v", err)
- }
-
- if len(searchTargets) == 0 {
- logger.Warn(ctx, "No search targets available, returning empty results")
- return []*types.SearchResult{}, nil
- }
-
- // Create default retrieval parameters — prefer tenant RetrievalConfig, fallback to built-in defaults
- userID, _ := types.UserIDFromContext(ctx)
-
- // Load tenant-level retrieval config (nil is safe — GetEffective* methods handle nil receiver)
- var rc *types.RetrievalConfig
- if tenant, err2 := s.tenantService.GetTenantByID(ctx, tenantID); err2 == nil {
- rc = tenant.RetrievalConfig
- }
-
- chatManage := &types.ChatManage{
- Query: query,
- RewriteQuery: query,
- UserID: userID,
- KnowledgeBaseIDs: knowledgeBaseIDs,
- KnowledgeIDs: knowledgeIDs,
- SearchTargets: searchTargets,
- MaxRounds: s.cfg.Conversation.MaxRounds,
- EmbeddingTopK: rc.GetEffectiveEmbeddingTopK(),
- VectorThreshold: rc.GetEffectiveVectorThreshold(),
- KeywordThreshold: rc.GetEffectiveKeywordThreshold(),
- RerankTopK: rc.GetEffectiveRerankTopK(),
- RerankThreshold: rc.GetEffectiveRerankThreshold(),
- }
-
- // Get default models
- models, err := s.modelService.ListModels(ctx)
- if err != nil {
- logger.Errorf(ctx, "Failed to get models: %v", err)
- return nil, err
- }
-
- // Use rerank model from RetrievalConfig if set, otherwise auto-select the first available
- if rc != nil && rc.RerankModelID != "" {
- chatManage.RerankModelID = rc.RerankModelID
- } else {
- for _, model := range models {
- if model == nil {
- continue
- }
- if model.Type == types.ModelTypeRerank {
- chatManage.RerankModelID = model.ID
- break
- }
- }
- }
-
- // Use specific event list, only including retrieval-related events, not LLM summarization
- searchEvents := []types.EventType{
- types.CHUNK_SEARCH, // Vector search
- types.CHUNK_RERANK, // Rerank search results
- types.CHUNK_MERGE, // Merge search results
- types.FILTER_TOP_K, // Filter top K results
- }
-
- ctx, span := tracing.ContextWithSpan(ctx, "SessionService.SearchKnowledge")
- defer span.End()
-
- // Prepare method list for logging and tracing
- methods := []string{}
- for _, event := range searchEvents {
- methods = append(methods, string(event))
- }
-
- // Set up tracing attributes
- logger.Infof(ctx, "Trigger search event list: %v", methods)
- span.SetAttributes(
- attribute.String("query", query),
- attribute.StringSlice("knowledge_base_ids", knowledgeBaseIDs),
- attribute.StringSlice("knowledge_ids", knowledgeIDs),
- attribute.String("method", strings.Join(methods, ",")),
- )
-
- // Process each search event in sequence
- for _, event := range searchEvents {
- logger.Infof(ctx, "Starting to trigger search event: %v", event)
- err := s.eventManager.Trigger(ctx, event, chatManage)
-
- // Handle case where search returns no results
- if err == chatpipline.ErrSearchNothing {
- logger.Warnf(ctx, "Event %v triggered, search result is empty", event)
- return []*types.SearchResult{}, nil
- }
-
- // Handle other errors
- if err != nil {
- logger.Errorf(ctx, "Event triggering failed, event: %v, error type: %s, description: %s, error: %v",
- event, err.ErrorType, err.Description, err.Err)
- span.RecordError(err.Err)
- span.SetStatus(codes.Error, err.Description)
- span.SetAttributes(attribute.String("error_type", err.ErrorType))
- return nil, err.Err
- }
- logger.Infof(ctx, "Event %v triggered successfully", event)
- }
-
- logger.Infof(ctx, "Knowledge base search completed, found %d results", len(chatManage.MergeResult))
- return chatManage.MergeResult, nil
-}
-
-// AgentQA performs agent-based question answering with conversation history and streaming support
-// customAgent is optional - if provided, uses custom agent configuration instead of tenant defaults
-// summaryModelID is optional - if provided, overrides the model from customAgent config
-func (s *sessionService) AgentQA(
- ctx context.Context,
- session *types.Session,
- query string,
- assistantMessageID string,
- summaryModelID string,
- eventBus *event.EventBus,
- customAgent *types.CustomAgent,
- knowledgeBaseIDs []string,
- knowledgeIDs []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 {
- logger.Errorf(ctx, "Failed to marshal session, session ID: %s, error: %v", sessionID, err)
- return fmt.Errorf("failed to marshal session: %w", err)
- }
-
- // customAgent is required for AgentQA (handler has already done permission check for shared agent)
- if customAgent == nil {
- logger.Warnf(ctx, "Custom agent not provided for session: %s", sessionID)
- return errors.New("custom agent configuration is required for agent QA")
- }
-
- // Use agent's tenant for retrieval and tenant-scoped config (handler has validated access)
- agentTenantID := customAgent.TenantID
- if agentTenantID == 0 {
- agentTenantID = session.TenantID
- }
- logger.Infof(ctx, "Start agent-based question answering, session ID: %s, agent tenant ID: %d, query: %s, session: %s",
- sessionID, agentTenantID, query, string(sessionJSON))
-
- var tenantInfo *types.Tenant
- if v := ctx.Value(types.TenantInfoContextKey); v != nil {
- tenantInfo, _ = v.(*types.Tenant)
- }
- // When agent belongs to another tenant (shared agent), use agent's tenant for KB/model scope; load tenantInfo if needed
- if tenantInfo == nil || tenantInfo.ID != agentTenantID {
- if s.tenantService != nil {
- if agentTenant, err := s.tenantService.GetTenantByID(ctx, agentTenantID); err == nil && agentTenant != nil {
- tenantInfo = agentTenant
- logger.Infof(ctx, "Using agent tenant info for retrieval scope, tenant ID: %d", agentTenantID)
- }
- }
- }
- if tenantInfo == nil {
- logger.Warnf(ctx, "Tenant info not available for agent tenant %d, proceeding with defaults", agentTenantID)
- tenantInfo = &types.Tenant{ID: agentTenantID}
- }
-
- // Ensure defaults are set
- customAgent.EnsureDefaults()
-
- // Create runtime AgentConfig from customAgent
- // Note: tenantInfo.AgentConfig is deprecated, all config comes from customAgent now
- agentConfig := &types.AgentConfig{
- MaxIterations: customAgent.Config.MaxIterations,
- ReflectionEnabled: customAgent.Config.ReflectionEnabled,
- Temperature: customAgent.Config.Temperature,
- WebSearchEnabled: customAgent.Config.WebSearchEnabled,
- WebSearchMaxResults: customAgent.Config.WebSearchMaxResults,
- MultiTurnEnabled: customAgent.Config.MultiTurnEnabled,
- HistoryTurns: customAgent.Config.HistoryTurns,
- MCPSelectionMode: customAgent.Config.MCPSelectionMode,
- MCPServices: customAgent.Config.MCPServices,
- Thinking: customAgent.Config.Thinking,
- RetrieveKBOnlyWhenMentioned: customAgent.Config.RetrieveKBOnlyWhenMentioned,
- }
-
- // Configure skills based on CustomAgentConfig
- s.configureSkillsFromAgent(ctx, agentConfig, customAgent)
-
- // Resolve knowledge bases: request-level @ mentions take priority over agent config
- // If RetrieveKBOnlyWhenMentioned is enabled and no @ mentions, don't use KB at all
- hasExplicitMention := len(knowledgeBaseIDs) > 0 || len(knowledgeIDs) > 0
- logger.Infof(ctx, "KB resolution: hasExplicitMention=%v, RetrieveKBOnlyWhenMentioned=%v, KBSelectionMode=%s",
- hasExplicitMention, agentConfig.RetrieveKBOnlyWhenMentioned, customAgent.Config.KBSelectionMode)
- if hasExplicitMention {
- // User explicitly specified via @ mention
- if len(knowledgeBaseIDs) > 0 {
- agentConfig.KnowledgeBases = knowledgeBaseIDs
- logger.Infof(ctx, "Using request-specified knowledge bases: %v", knowledgeBaseIDs)
- }
- if len(knowledgeIDs) > 0 {
- agentConfig.KnowledgeIDs = knowledgeIDs
- logger.Infof(ctx, "Using request-specified knowledge IDs: %v", knowledgeIDs)
- }
- } else if agentConfig.RetrieveKBOnlyWhenMentioned {
- // User didn't mention any KB/file, and the setting requires explicit mention
- agentConfig.KnowledgeBases = nil
- agentConfig.KnowledgeIDs = nil
- logger.Infof(ctx, "RetrieveKBOnlyWhenMentioned is enabled and no @ mention found, KB retrieval disabled for this request")
- } else {
- // Use agent's configured knowledge bases based on KBSelectionMode
- agentConfig.KnowledgeBases = s.resolveKnowledgeBasesFromAgent(ctx, customAgent, session.TenantID)
- }
-
- // Use custom agent's allowed tools if specified, otherwise use defaults
- if len(customAgent.Config.AllowedTools) > 0 {
- agentConfig.AllowedTools = customAgent.Config.AllowedTools
- } else {
- agentConfig.AllowedTools = tools.DefaultAllowedTools()
- }
-
- // Use custom agent's system prompt if specified
- if customAgent.Config.SystemPrompt != "" {
- agentConfig.UseCustomSystemPrompt = true
- agentConfig.SystemPrompt = customAgent.Config.SystemPrompt
- }
-
- logger.Infof(ctx, "Custom agent config applied: MaxIterations=%d, Temperature=%.2f, AllowedTools=%v, WebSearchEnabled=%v",
- agentConfig.MaxIterations, agentConfig.Temperature, agentConfig.AllowedTools, agentConfig.WebSearchEnabled)
-
- // Set web search max results from tenant config if not set (default: 5)
- if agentConfig.WebSearchMaxResults == 0 {
- agentConfig.WebSearchMaxResults = 5
- if tenantInfo.WebSearchConfig != nil && tenantInfo.WebSearchConfig.MaxResults > 0 {
- agentConfig.WebSearchMaxResults = tenantInfo.WebSearchConfig.MaxResults
- }
- }
-
- logger.Infof(ctx, "Merged agent config from tenant %d and session %s", tenantInfo.ID, sessionID)
-
- // Log knowledge bases if present
- if len(agentConfig.KnowledgeBases) > 0 {
- logger.Infof(ctx, "Agent configured with %d knowledge base(s): %v",
- len(agentConfig.KnowledgeBases), agentConfig.KnowledgeBases)
- } else {
- // Allow running without knowledge bases (Pure Agent mode)
- logger.Infof(ctx, "No knowledge bases specified for agent, running in pure agent mode")
- }
-
- // Build search targets using agent's tenant (handler has validated access for shared agent)
- searchTargets, err := s.buildSearchTargets(ctx, agentTenantID, agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs)
- if err != nil {
- logger.Warnf(ctx, "Failed to build search targets for agent: %v", err)
- // Continue without search targets, the tool will handle empty targets
- }
- agentConfig.SearchTargets = searchTargets
- logger.Infof(ctx, "Agent search targets built: %d targets", len(searchTargets))
-
- // Get summary model: prioritize request's summaryModelID, then custom agent config
- // Note: tenantInfo.ConversationConfig is deprecated, all config comes from customAgent now
- effectiveModelID := summaryModelID
- if effectiveModelID == "" {
- effectiveModelID = customAgent.Config.ModelID
- }
- if effectiveModelID == "" {
- logger.Warnf(ctx, "No summary model configured for custom agent %s", customAgent.ID)
- return errors.New("summary model (model_id) is not configured in custom agent settings")
- }
- if summaryModelID != "" {
- logger.Infof(ctx, "Using request's summary model override: %s", effectiveModelID)
- } else {
- logger.Infof(ctx, "Using custom agent's model_id: %s", effectiveModelID)
- }
-
- summaryModel, err := s.modelService.GetChatModel(ctx, effectiveModelID)
- if err != nil {
- logger.Warnf(ctx, "Failed to get chat model: %v", err)
- return fmt.Errorf("failed to get chat model: %w", err)
- }
-
- // Get rerank model from custom agent config (only required when knowledge bases are configured)
- var rerankModel rerank.Reranker
- hasKnowledge := len(agentConfig.KnowledgeBases) > 0 || len(agentConfig.KnowledgeIDs) > 0
- if hasKnowledge {
- rerankModelID := customAgent.Config.RerankModelID
- if rerankModelID == "" {
- logger.Warnf(ctx, "No rerank model configured for custom agent %s, but knowledge bases are specified", customAgent.ID)
- return errors.New("rerank model (rerank_model_id) is not configured in custom agent settings")
- }
-
- rerankModel, err = s.modelService.GetRerankModel(ctx, rerankModelID)
- if err != nil {
- logger.Warnf(ctx, "Failed to get rerank model: %v", err)
- return fmt.Errorf("failed to get rerank model: %w", err)
- }
- } else {
- logger.Infof(ctx, "No knowledge bases configured, skipping rerank model initialization")
- }
-
- // Get or create contextManager for this session
- contextManager := s.getContextManagerForSession(ctx, session, summaryModel)
-
- // Set system prompt for the current agent in context manager
- // This ensures the context uses the correct system prompt when switching agents
- systemPrompt := agentConfig.ResolveSystemPrompt(agentConfig.WebSearchEnabled)
- if systemPrompt != "" {
- if err := contextManager.SetSystemPrompt(ctx, sessionID, systemPrompt); err != nil {
- logger.Warnf(ctx, "Failed to set system prompt in context manager: %v", err)
- } else {
- logger.Infof(ctx, "System prompt updated in context manager for agent")
- }
- }
-
- // Get LLM context from context manager
- llmContext, err := s.getContextForSession(ctx, contextManager, sessionID)
- if err != nil {
- logger.Warnf(ctx, "Failed to get LLM context: %v, continuing without history", err)
- llmContext = []chat.Message{}
- }
- logger.Infof(ctx, "Loaded %d messages from LLM context manager", len(llmContext))
-
- // Apply multi-turn configuration for Agent mode
- // Note: In Agent mode, context is managed by contextManager with compression strategies,
- // so we don't apply HistoryTurns limit here. HistoryTurns is used in normal (KnowledgeQA) mode.
- if !agentConfig.MultiTurnEnabled {
- // Multi-turn disabled, clear history
- logger.Infof(ctx, "Multi-turn disabled for this agent, clearing history context")
- llmContext = []chat.Message{}
- }
-
- // Create agent engine with EventBus and ContextManager
- logger.Info(ctx, "Creating agent engine")
- engine, err := s.agentService.CreateAgentEngine(
- ctx,
- agentConfig,
- summaryModel,
- rerankModel,
- eventBus,
- contextManager,
- session.ID,
- )
- if err != nil {
- logger.Errorf(ctx, "Failed to create agent engine: %v", err)
- return err
- }
-
- // Route image data based on agent model's vision capability
- var agentModelSupportsVision bool
- if effectiveModelID != "" {
- if modelInfo, err := s.modelService.GetModelByID(ctx, effectiveModelID); err == nil && modelInfo != nil {
- agentModelSupportsVision = modelInfo.Parameters.SupportsVision
- }
- }
-
- agentQuery := query
- var agentImageURLs []string
- if agentModelSupportsVision && len(imageURLs) > 0 {
- agentImageURLs = imageURLs
- logger.Infof(ctx, "Agent model supports vision, passing %d image(s) directly", len(agentImageURLs))
- } 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)
- // Events will be emitted to EventBus and handled by the Handler layer
- logger.Info(ctx, "Executing agent with streaming")
- if _, err := engine.Execute(ctx, sessionID, assistantMessageID, agentQuery, llmContext, agentImageURLs); err != nil {
- logger.Errorf(ctx, "Agent execution failed: %v", err)
- // Emit error event to the EventBus used by this agent
- eventBus.Emit(ctx, event.Event{
- Type: event.EventError,
- SessionID: sessionID,
- Data: event.ErrorData{
- Error: err.Error(),
- Stage: "agent_execution",
- SessionID: sessionID,
- },
- })
- }
- // Return empty - events will be handled by Handler via EventBus subscription
- return nil
-}
-
-// getContextManagerForSession creates a context manager for the session based on configuration
-// Returns the configured context manager (tenant-level or session-level) or default
-func (s *sessionService) getContextManagerForSession(
- ctx context.Context,
- session *types.Session,
- chatModel chat.Chat,
-) interfaces.ContextManager {
- // Get tenant to access global context configuration
- tenant, _ := types.TenantInfoFromContext(ctx)
- // Determine which context config to use: tenant-level or default
- var contextConfig *types.ContextConfig
- if tenant != nil && tenant.ContextConfig != nil {
- // Use tenant-level configuration
- contextConfig = tenant.ContextConfig
- logger.Infof(ctx, "Using tenant-level context config for session %s", session.ID)
- } else {
- // Use service's default context manager
- logger.Debugf(ctx, "Using default context manager for session %s", session.ID)
- contextConfig = &types.ContextConfig{
- MaxTokens: llmcontext.DefaultMaxTokens,
- CompressionStrategy: llmcontext.DefaultCompressionStrategy,
- RecentMessageCount: llmcontext.DefaultRecentMessageCount,
- SummarizeThreshold: llmcontext.DefaultSummarizeThreshold,
- }
- }
- return llmcontext.NewContextManagerFromConfig(contextConfig, s.sessionStorage, chatModel)
-}
-
-// getContextForSession retrieves LLM context for a session
-func (s *sessionService) getContextForSession(
- ctx context.Context,
- contextManager interfaces.ContextManager,
- sessionID string,
-) ([]chat.Message, error) {
- history, err := contextManager.GetContext(ctx, sessionID)
- if err != nil {
- return nil, fmt.Errorf("failed to get context: %w", err)
- }
-
- // Log context statistics
- stats, _ := contextManager.GetContextStats(ctx, sessionID)
- if stats != nil {
- logger.Infof(ctx, "LLM context stats for session %s: messages=%d, tokens=~%d, compressed=%v",
- sessionID, stats.MessageCount, stats.TokenCount, stats.IsCompressed)
- }
-
- return history, nil
-}
-
// ClearContext clears the LLM context for a session
// This is useful when switching knowledge bases or agent modes to prevent context contamination
func (s *sessionService) ClearContext(ctx context.Context, sessionID string) error {
logger.Infof(ctx, "Clearing context for session: %s", sessionID)
return s.sessionStorage.Delete(ctx, sessionID)
}
-
-// handleFallbackResponse handles fallback response based on strategy
-func (s *sessionService) handleFallbackResponse(ctx context.Context, chatManage *types.ChatManage) {
- if chatManage.FallbackStrategy == types.FallbackStrategyModel {
- s.handleModelFallback(ctx, chatManage)
- } else {
- s.handleFixedFallback(ctx, chatManage)
- }
-}
-
-// handleFixedFallback handles fixed fallback response
-func (s *sessionService) handleFixedFallback(ctx context.Context, chatManage *types.ChatManage) {
- fallbackContent := chatManage.FallbackResponse
- chatManage.ChatResponse = &types.ChatResponse{Content: fallbackContent}
- s.emitFallbackAnswer(ctx, chatManage, fallbackContent)
-}
-
-// handleModelFallback handles model-based fallback response using streaming
-func (s *sessionService) handleModelFallback(ctx context.Context, chatManage *types.ChatManage) {
- // Check if FallbackPrompt is available
- if chatManage.FallbackPrompt == "" {
- logger.Warnf(ctx, "Fallback strategy is 'model' but FallbackPrompt is empty, falling back to fixed response")
- s.handleFixedFallback(ctx, chatManage)
- return
- }
-
- // Render template with Query variable
- promptContent, err := s.renderFallbackPrompt(ctx, chatManage)
- if err != nil {
- logger.Errorf(ctx, "Failed to render fallback prompt: %v, falling back to fixed response", err)
- s.handleFixedFallback(ctx, chatManage)
- return
- }
-
- // Check if EventBus is available for streaming
- if chatManage.EventBus == nil {
- logger.Warnf(ctx, "EventBus not available for streaming fallback, falling back to fixed response")
- s.handleFixedFallback(ctx, chatManage)
- return
- }
-
- // Get chat model
- chatModel, err := s.modelService.GetChatModel(ctx, chatManage.ChatModelID)
- if err != nil {
- logger.Errorf(ctx, "Failed to get chat model for fallback: %v, falling back to fixed response", err)
- s.handleFixedFallback(ctx, chatManage)
- return
- }
-
- // Prepare chat options
- thinking := false
- opt := &chat.ChatOptions{
- Temperature: chatManage.SummaryConfig.Temperature,
- MaxCompletionTokens: chatManage.SummaryConfig.MaxCompletionTokens,
- Thinking: &thinking,
- }
-
- // Start streaming response
- 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)
- return
- }
-
- if responseChan == nil {
- logger.Errorf(ctx, "Chat stream returned nil channel, falling back to fixed response")
- s.handleFixedFallback(ctx, chatManage)
- return
- }
-
- // Start goroutine to consume stream and emit events
- go s.consumeFallbackStream(ctx, chatManage, responseChan)
-}
-
-// renderFallbackPrompt renders the fallback prompt template with query and image context.
-func (s *sessionService) renderFallbackPrompt(ctx context.Context, chatManage *types.ChatManage) (string, error) {
- 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
-}
-
-// consumeFallbackStream consumes the streaming response and emits events
-func (s *sessionService) consumeFallbackStream(
- ctx context.Context,
- chatManage *types.ChatManage,
- responseChan <-chan types.StreamResponse,
-) {
- fallbackID := generateEventID("fallback")
- eventBus := chatManage.EventBus
- var finalContent string
- streamCompleted := false
-
- for response := range responseChan {
- // Emit event for each answer chunk
- if response.ResponseType == types.ResponseTypeAnswer {
- finalContent += response.Content
- if err := eventBus.Emit(ctx, types.Event{
- ID: fallbackID,
- Type: types.EventType(event.EventAgentFinalAnswer),
- SessionID: chatManage.SessionID,
- Data: event.AgentFinalAnswerData{
- Content: response.Content,
- Done: response.Done,
- IsFallback: true,
- },
- }); err != nil {
- logger.Errorf(ctx, "Failed to emit fallback answer chunk event: %v", err)
- }
-
- // Update ChatResponse with final content when done
- if response.Done {
- chatManage.ChatResponse = &types.ChatResponse{Content: finalContent}
- streamCompleted = true
- logger.Infof(ctx, "Fallback streaming response completed")
- break
- }
- }
- }
-
- // If channel closed without Done=true, emit final event with fixed response
- if !streamCompleted {
- logger.Warnf(ctx, "Fallback stream closed without completion, emitting final event with fixed response")
- s.emitFallbackAnswer(ctx, chatManage, chatManage.FallbackResponse)
- }
-}
-
-// emitFallbackAnswer emits fallback answer event
-func (s *sessionService) emitFallbackAnswer(ctx context.Context, chatManage *types.ChatManage, content string) {
- if chatManage.EventBus == nil {
- return
- }
-
- fallbackID := generateEventID("fallback")
- if err := chatManage.EventBus.Emit(ctx, types.Event{
- ID: fallbackID,
- Type: types.EventType(event.EventAgentFinalAnswer),
- SessionID: chatManage.SessionID,
- Data: event.AgentFinalAnswerData{
- Content: content,
- Done: true,
- IsFallback: true,
- },
- }); err != nil {
- logger.Errorf(ctx, "Failed to emit fallback answer event: %v", err)
- } else {
- logger.Infof(ctx, "Fallback answer event emitted successfully")
- }
-}
diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.go
new file mode 100644
index 00000000..ff9e0a6e
--- /dev/null
+++ b/internal/application/service/session_agent_qa.go
@@ -0,0 +1,368 @@
+package service
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "os"
+
+ "github.com/Tencent/WeKnora/internal/agent/tools"
+ llmcontext "github.com/Tencent/WeKnora/internal/application/service/llmcontext"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/models/rerank"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+)
+
+// AgentQA performs agent-based question answering with conversation history and streaming support
+// customAgent is optional - if provided, uses custom agent configuration instead of tenant defaults
+// summaryModelID is optional - if provided, overrides the model from customAgent config
+func (s *sessionService) AgentQA(
+ ctx context.Context,
+ req *types.QARequest,
+ eventBus *event.EventBus,
+) error {
+ sessionID := req.Session.ID
+ sessionJSON, err := json.Marshal(req.Session)
+ if err != nil {
+ logger.Errorf(ctx, "Failed to marshal session, session ID: %s, error: %v", sessionID, err)
+ return fmt.Errorf("failed to marshal session: %w", err)
+ }
+
+ // customAgent is required for AgentQA (handler has already done permission check for shared agent)
+ if req.CustomAgent == nil {
+ logger.Warnf(ctx, "Custom agent not provided for session: %s", sessionID)
+ return errors.New("custom agent configuration is required for agent QA")
+ }
+
+ // Resolve retrieval tenant using shared helper
+ agentTenantID := s.resolveRetrievalTenantID(ctx, req)
+ logger.Infof(ctx, "Start agent-based question answering, session ID: %s, agent tenant ID: %d, query: %s, session: %s",
+ sessionID, agentTenantID, req.Query, string(sessionJSON))
+
+ var tenantInfo *types.Tenant
+ if v := ctx.Value(types.TenantInfoContextKey); v != nil {
+ tenantInfo, _ = v.(*types.Tenant)
+ }
+ // When agent belongs to another tenant (shared agent), use agent's tenant for KB/model scope; load tenantInfo if needed
+ if tenantInfo == nil || tenantInfo.ID != agentTenantID {
+ if s.tenantService != nil {
+ if agentTenant, err := s.tenantService.GetTenantByID(ctx, agentTenantID); err == nil && agentTenant != nil {
+ tenantInfo = agentTenant
+ logger.Infof(ctx, "Using agent tenant info for retrieval scope, tenant ID: %d", agentTenantID)
+ }
+ }
+ }
+ if tenantInfo == nil {
+ logger.Warnf(ctx, "Tenant info not available for agent tenant %d, proceeding with defaults", agentTenantID)
+ tenantInfo = &types.Tenant{ID: agentTenantID}
+ }
+
+ // Ensure defaults are set
+ req.CustomAgent.EnsureDefaults()
+
+ // Build AgentConfig from custom agent and tenant info
+ agentConfig, err := s.buildAgentConfig(ctx, req, tenantInfo, agentTenantID)
+ if err != nil {
+ return err
+ }
+
+ // Resolve model ID using shared helper (AgentQA requires a model, so error if not found)
+ effectiveModelID, err := s.resolveChatModelID(ctx, req, agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs)
+ if err != nil {
+ return err
+ }
+ if effectiveModelID == "" {
+ logger.Warnf(ctx, "No summary model configured for custom agent %s", req.CustomAgent.ID)
+ return errors.New("summary model (model_id) is not configured in custom agent settings")
+ }
+
+ summaryModel, err := s.modelService.GetChatModel(ctx, effectiveModelID)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to get chat model: %v", err)
+ return fmt.Errorf("failed to get chat model: %w", err)
+ }
+
+ // Get rerank model from custom agent config (only required when knowledge bases are configured)
+ var rerankModel rerank.Reranker
+ hasKnowledge := len(agentConfig.KnowledgeBases) > 0 || len(agentConfig.KnowledgeIDs) > 0
+ if hasKnowledge {
+ rerankModelID := req.CustomAgent.Config.RerankModelID
+ if rerankModelID == "" {
+ logger.Warnf(ctx, "No rerank model configured for custom agent %s, but knowledge bases are specified", req.CustomAgent.ID)
+ return errors.New("rerank model (rerank_model_id) is not configured in custom agent settings")
+ }
+
+ rerankModel, err = s.modelService.GetRerankModel(ctx, rerankModelID)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to get rerank model: %v", err)
+ return fmt.Errorf("failed to get rerank model: %w", err)
+ }
+ } else {
+ logger.Infof(ctx, "No knowledge bases configured, skipping rerank model initialization")
+ }
+
+ // Get or create contextManager for this session
+ contextManager := s.getContextManagerForSession(ctx, req.Session, summaryModel)
+
+ // Set system prompt for the current agent in context manager
+ // This ensures the context uses the correct system prompt when switching agents
+ systemPrompt := agentConfig.ResolveSystemPrompt(agentConfig.WebSearchEnabled)
+ if systemPrompt != "" {
+ if err := contextManager.SetSystemPrompt(ctx, sessionID, systemPrompt); err != nil {
+ logger.Warnf(ctx, "Failed to set system prompt in context manager: %v", err)
+ } else {
+ logger.Infof(ctx, "System prompt updated in context manager for agent")
+ }
+ }
+
+ // Get LLM context from context manager
+ llmContext, err := s.getContextForSession(ctx, contextManager, sessionID)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to get LLM context: %v, continuing without history", err)
+ llmContext = []chat.Message{}
+ }
+ logger.Infof(ctx, "Loaded %d messages from LLM context manager", len(llmContext))
+
+ // Apply multi-turn configuration for Agent mode
+ // Note: In Agent mode, context is managed by contextManager with compression strategies,
+ // so we don't apply HistoryTurns limit here. HistoryTurns is used in normal (KnowledgeQA) mode.
+ if !agentConfig.MultiTurnEnabled {
+ // Multi-turn disabled, clear history
+ logger.Infof(ctx, "Multi-turn disabled for this agent, clearing history context")
+ llmContext = []chat.Message{}
+ }
+
+ // Create agent engine with EventBus and ContextManager
+ logger.Info(ctx, "Creating agent engine")
+ engine, err := s.agentService.CreateAgentEngine(
+ ctx,
+ agentConfig,
+ summaryModel,
+ rerankModel,
+ eventBus,
+ contextManager,
+ sessionID,
+ )
+ if err != nil {
+ logger.Errorf(ctx, "Failed to create agent engine: %v", err)
+ return err
+ }
+
+ // Route image data based on agent model's vision capability
+ var agentModelSupportsVision bool
+ if effectiveModelID != "" {
+ if modelInfo, err := s.modelService.GetModelByID(ctx, effectiveModelID); err == nil && modelInfo != nil {
+ agentModelSupportsVision = modelInfo.Parameters.SupportsVision
+ }
+ }
+
+ agentQuery := req.Query
+ var agentImageURLs []string
+ if agentModelSupportsVision && len(req.ImageURLs) > 0 {
+ agentImageURLs = req.ImageURLs
+ logger.Infof(ctx, "Agent model supports vision, passing %d image(s) directly", len(agentImageURLs))
+ } else if req.ImageDescription != "" {
+ agentQuery = req.Query + "\n\n[用户上传图片内容]\n" + req.ImageDescription
+ logger.Infof(ctx, "Agent model does not support vision, appending image description (%d chars)", len(req.ImageDescription))
+ }
+
+ // Execute agent with streaming (asynchronously)
+ // Events will be emitted to EventBus and handled by the Handler layer
+ logger.Info(ctx, "Executing agent with streaming")
+ if _, err := engine.Execute(ctx, sessionID, req.AssistantMessageID, agentQuery, llmContext, agentImageURLs); err != nil {
+ logger.Errorf(ctx, "Agent execution failed: %v", err)
+ // Emit error event to the EventBus used by this agent
+ eventBus.Emit(ctx, event.Event{
+ Type: event.EventError,
+ SessionID: sessionID,
+ Data: event.ErrorData{
+ Error: err.Error(),
+ Stage: "agent_execution",
+ SessionID: sessionID,
+ },
+ })
+ }
+ // Return empty - events will be handled by Handler via EventBus subscription
+ return nil
+}
+
+// buildAgentConfig creates a runtime AgentConfig from the QARequest's custom agent configuration,
+// tenant info, and resolved knowledge bases / search targets.
+func (s *sessionService) buildAgentConfig(
+ ctx context.Context,
+ req *types.QARequest,
+ tenantInfo *types.Tenant,
+ agentTenantID uint64,
+) (*types.AgentConfig, error) {
+ customAgent := req.CustomAgent
+ agentConfig := &types.AgentConfig{
+ MaxIterations: customAgent.Config.MaxIterations,
+ ReflectionEnabled: customAgent.Config.ReflectionEnabled,
+ Temperature: customAgent.Config.Temperature,
+ WebSearchEnabled: customAgent.Config.WebSearchEnabled && req.WebSearchEnabled,
+ WebSearchMaxResults: customAgent.Config.WebSearchMaxResults,
+ MultiTurnEnabled: customAgent.Config.MultiTurnEnabled,
+ HistoryTurns: customAgent.Config.HistoryTurns,
+ MCPSelectionMode: customAgent.Config.MCPSelectionMode,
+ MCPServices: customAgent.Config.MCPServices,
+ Thinking: customAgent.Config.Thinking,
+ RetrieveKBOnlyWhenMentioned: customAgent.Config.RetrieveKBOnlyWhenMentioned,
+ }
+
+ // Configure skills based on CustomAgentConfig
+ s.configureSkillsFromAgent(ctx, agentConfig, customAgent)
+
+ // Resolve knowledge bases using shared helper
+ agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs = s.resolveKnowledgeBases(ctx, req)
+
+ // Use custom agent's allowed tools if specified, otherwise use defaults
+ if len(customAgent.Config.AllowedTools) > 0 {
+ agentConfig.AllowedTools = customAgent.Config.AllowedTools
+ } else {
+ agentConfig.AllowedTools = tools.DefaultAllowedTools()
+ }
+
+ // Use custom agent's system prompt if specified
+ if customAgent.Config.SystemPrompt != "" {
+ agentConfig.UseCustomSystemPrompt = true
+ agentConfig.SystemPrompt = customAgent.Config.SystemPrompt
+ }
+
+ logger.Infof(ctx, "Custom agent config applied: MaxIterations=%d, Temperature=%.2f, AllowedTools=%v, WebSearchEnabled=%v",
+ agentConfig.MaxIterations, agentConfig.Temperature, agentConfig.AllowedTools, agentConfig.WebSearchEnabled)
+
+ // Set web search max results from tenant config if not set (default: 5)
+ if agentConfig.WebSearchMaxResults == 0 {
+ agentConfig.WebSearchMaxResults = 5
+ if tenantInfo.WebSearchConfig != nil && tenantInfo.WebSearchConfig.MaxResults > 0 {
+ agentConfig.WebSearchMaxResults = tenantInfo.WebSearchConfig.MaxResults
+ }
+ }
+
+ logger.Infof(ctx, "Merged agent config from tenant %d and session %s", tenantInfo.ID, req.Session.ID)
+
+ // Log knowledge bases if present
+ if len(agentConfig.KnowledgeBases) > 0 {
+ logger.Infof(ctx, "Agent configured with %d knowledge base(s): %v",
+ len(agentConfig.KnowledgeBases), agentConfig.KnowledgeBases)
+ } else {
+ logger.Infof(ctx, "No knowledge bases specified for agent, running in pure agent mode")
+ }
+
+ // Build search targets using agent's tenant (handler has validated access for shared agent)
+ searchTargets, err := s.buildSearchTargets(ctx, agentTenantID, agentConfig.KnowledgeBases, agentConfig.KnowledgeIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to build search targets for agent: %v", err)
+ }
+ agentConfig.SearchTargets = searchTargets
+ logger.Infof(ctx, "Agent search targets built: %d targets", len(searchTargets))
+
+ return agentConfig, nil
+}
+
+// configureSkillsFromAgent configures skills settings in AgentConfig based on CustomAgentConfig
+// Returns the skill directories and allowed skills based on the selection mode:
+// - "all": uses all preloaded skills
+// - "selected": uses the explicitly selected skills
+// - "none" or "": skills are disabled
+func (s *sessionService) configureSkillsFromAgent(
+ ctx context.Context,
+ agentConfig *types.AgentConfig,
+ customAgent *types.CustomAgent,
+) {
+ if customAgent == nil {
+ return
+ }
+ // When sandbox is disabled, skills cannot be enabled (no script execution environment)
+ sandboxMode := os.Getenv("WEKNORA_SANDBOX_MODE")
+ if sandboxMode == "" || sandboxMode == "disabled" {
+ agentConfig.SkillsEnabled = false
+ agentConfig.SkillDirs = nil
+ agentConfig.AllowedSkills = nil
+ logger.Infof(ctx, "Sandbox is disabled: skills are not available")
+ return
+ }
+
+ switch customAgent.Config.SkillsSelectionMode {
+ case "all":
+ // Enable all preloaded skills
+ agentConfig.SkillsEnabled = true
+ agentConfig.SkillDirs = []string{DefaultPreloadedSkillsDir}
+ agentConfig.AllowedSkills = nil // Empty means all skills allowed
+ logger.Infof(ctx, "SkillsSelectionMode=all: enabled all preloaded skills")
+ case "selected":
+ // Enable only selected skills
+ if len(customAgent.Config.SelectedSkills) > 0 {
+ agentConfig.SkillsEnabled = true
+ agentConfig.SkillDirs = []string{DefaultPreloadedSkillsDir}
+ agentConfig.AllowedSkills = customAgent.Config.SelectedSkills
+ logger.Infof(ctx, "SkillsSelectionMode=selected: enabled %d selected skills: %v",
+ len(customAgent.Config.SelectedSkills), customAgent.Config.SelectedSkills)
+ } else {
+ agentConfig.SkillsEnabled = false
+ logger.Infof(ctx, "SkillsSelectionMode=selected but no skills selected: skills disabled")
+ }
+ case "none", "":
+ // Skills disabled
+ agentConfig.SkillsEnabled = false
+ logger.Infof(ctx, "SkillsSelectionMode=%s: skills disabled", customAgent.Config.SkillsSelectionMode)
+ default:
+ // Unknown mode, disable skills
+ agentConfig.SkillsEnabled = false
+ logger.Warnf(ctx, "Unknown SkillsSelectionMode=%s: skills disabled", customAgent.Config.SkillsSelectionMode)
+ }
+
+}
+
+// getContextManagerForSession creates a context manager for the session based on configuration
+// Returns the configured context manager (tenant-level or session-level) or default
+func (s *sessionService) getContextManagerForSession(
+ ctx context.Context,
+ session *types.Session,
+ chatModel chat.Chat,
+) interfaces.ContextManager {
+ // Get tenant to access global context configuration
+ tenant, _ := types.TenantInfoFromContext(ctx)
+ // Determine which context config to use: tenant-level or default
+ var contextConfig *types.ContextConfig
+ if tenant != nil && tenant.ContextConfig != nil {
+ // Use tenant-level configuration
+ contextConfig = tenant.ContextConfig
+ logger.Infof(ctx, "Using tenant-level context config for session %s", session.ID)
+ } else {
+ // Use service's default context manager
+ logger.Debugf(ctx, "Using default context manager for session %s", session.ID)
+ contextConfig = &types.ContextConfig{
+ MaxTokens: llmcontext.DefaultMaxTokens,
+ CompressionStrategy: llmcontext.DefaultCompressionStrategy,
+ RecentMessageCount: llmcontext.DefaultRecentMessageCount,
+ SummarizeThreshold: llmcontext.DefaultSummarizeThreshold,
+ }
+ }
+ return llmcontext.NewContextManagerFromConfig(contextConfig, s.sessionStorage, chatModel)
+}
+
+// getContextForSession retrieves LLM context for a session
+func (s *sessionService) getContextForSession(
+ ctx context.Context,
+ contextManager interfaces.ContextManager,
+ sessionID string,
+) ([]chat.Message, error) {
+ history, err := contextManager.GetContext(ctx, sessionID)
+ if err != nil {
+ return nil, fmt.Errorf("failed to get context: %w", err)
+ }
+
+ // Log context statistics
+ stats, _ := contextManager.GetContextStats(ctx, sessionID)
+ if stats != nil {
+ logger.Infof(ctx, "LLM context stats for session %s: messages=%d, tokens=~%d, compressed=%v",
+ sessionID, stats.MessageCount, stats.TokenCount, stats.IsCompressed)
+ }
+
+ return history, nil
+}
diff --git a/internal/application/service/session_knowledge_qa.go b/internal/application/service/session_knowledge_qa.go
new file mode 100644
index 00000000..9f562dcc
--- /dev/null
+++ b/internal/application/service/session_knowledge_qa.go
@@ -0,0 +1,806 @@
+package service
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ chatpipline "github.com/Tencent/WeKnora/internal/application/service/chat_pipline"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/tracing"
+ "github.com/Tencent/WeKnora/internal/types"
+ "go.opentelemetry.io/otel/attribute"
+ "go.opentelemetry.io/otel/codes"
+)
+
+// KnowledgeQA performs knowledge base question answering with LLM summarization
+// Events are emitted through eventBus (references, answer chunks, completion)
+// customAgent is optional - if provided, uses custom agent configuration for multiTurnEnabled and historyTurns
+func (s *sessionService) KnowledgeQA(
+ ctx context.Context,
+ req *types.QARequest,
+ eventBus *event.EventBus,
+) error {
+ logger.Infof(
+ ctx,
+ "Knowledge base question answering parameters, session ID: %s, query: %s, webSearchEnabled: %v, enableMemory: %v",
+ req.Session.ID,
+ req.Query,
+ req.WebSearchEnabled,
+ req.EnableMemory,
+ )
+
+ // Resolve knowledge bases using shared helper
+ knowledgeBaseIDs, knowledgeIDs := s.resolveKnowledgeBases(ctx, req)
+
+ // Resolve chat model ID using shared helper
+ chatModelID, err := s.resolveChatModelID(ctx, req, knowledgeBaseIDs, knowledgeIDs)
+ if err != nil {
+ return err
+ }
+
+ // Initialize ChatManage defaults from config.yaml
+ summaryConfig := types.SummaryConfig{
+ Prompt: s.cfg.Conversation.Summary.Prompt,
+ ContextTemplate: s.cfg.Conversation.Summary.ContextTemplate,
+ Temperature: s.cfg.Conversation.Summary.Temperature,
+ NoMatchPrefix: s.cfg.Conversation.Summary.NoMatchPrefix,
+ MaxCompletionTokens: s.cfg.Conversation.Summary.MaxCompletionTokens,
+ Thinking: s.cfg.Conversation.Summary.Thinking,
+ }
+ fallbackStrategy := types.FallbackStrategy(s.cfg.Conversation.FallbackStrategy)
+ if fallbackStrategy == "" {
+ fallbackStrategy = types.FallbackStrategyFixed
+ logger.Infof(ctx, "Fallback strategy not set, using default: %v", fallbackStrategy)
+ }
+
+ // Resolve chat model vision capability and VLM model ID for image routing
+ var chatModelSupportsVision bool
+ var vlmModelID string
+ if chatModelID != "" {
+ if chatModelInfo, err := s.modelService.GetModelByID(ctx, chatModelID); err == nil && chatModelInfo != nil {
+ chatModelSupportsVision = chatModelInfo.Parameters.SupportsVision
+ }
+ }
+ if req.CustomAgent != nil {
+ vlmModelID = req.CustomAgent.Config.VLMModelID
+ }
+
+ // Resolve retrieval tenant scope using shared helper
+ retrievalTenantID := s.resolveRetrievalTenantID(ctx, req)
+
+ // Build unified search targets (computed once, used throughout pipeline)
+ searchTargets, err := s.buildSearchTargets(ctx, retrievalTenantID, knowledgeBaseIDs, knowledgeIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to build search targets: %v", err)
+ }
+
+ // Create chat management object with session settings
+ logger.Infof(
+ ctx,
+ "Creating chat manage object, knowledge base IDs: %v, knowledge IDs: %v, chat model ID: %s, search targets: %d",
+ knowledgeBaseIDs,
+ knowledgeIDs,
+ chatModelID,
+ len(searchTargets),
+ )
+
+ // Get UserID from context
+ userID, _ := types.UserIDFromContext(ctx)
+
+ chatManage := &types.ChatManage{
+ Query: req.Query,
+ RewriteQuery: req.Query,
+ SessionID: req.Session.ID,
+ UserID: userID,
+ MessageID: req.AssistantMessageID,
+ KnowledgeBaseIDs: knowledgeBaseIDs,
+ KnowledgeIDs: knowledgeIDs,
+ SearchTargets: searchTargets,
+ VectorThreshold: s.cfg.Conversation.VectorThreshold,
+ KeywordThreshold: s.cfg.Conversation.KeywordThreshold,
+ EmbeddingTopK: s.cfg.Conversation.EmbeddingTopK,
+ RerankTopK: s.cfg.Conversation.RerankTopK,
+ RerankThreshold: s.cfg.Conversation.RerankThreshold,
+ MaxRounds: s.cfg.Conversation.MaxRounds,
+ ChatModelID: chatModelID,
+ SummaryConfig: summaryConfig,
+ FallbackStrategy: fallbackStrategy,
+ FallbackResponse: s.cfg.Conversation.FallbackResponse,
+ FallbackPrompt: s.cfg.Conversation.FallbackPrompt,
+ EventBus: eventBus.AsEventBusInterface(),
+ WebSearchEnabled: req.WebSearchEnabled,
+ EnableMemory: req.EnableMemory,
+ TenantID: retrievalTenantID,
+ RewritePromptSystem: s.cfg.Conversation.RewritePromptSystem,
+ RewritePromptUser: s.cfg.Conversation.RewritePromptUser,
+ EnableRewrite: s.cfg.Conversation.EnableRewrite,
+ EnableQueryExpansion: s.cfg.Conversation.EnableQueryExpansion,
+ // Image support
+ UserMessageID: req.UserMessageID,
+ Images: req.ImageURLs,
+ ImageDescription: req.ImageDescription,
+ VLMModelID: vlmModelID,
+ ChatModelSupportsVision: chatModelSupportsVision,
+ }
+
+ // Apply custom agent overrides (system prompt, temperature, retrieval params,
+ // rewrite, fallback, FAQ strategy, history turns)
+ s.applyAgentOverridesToChatManage(ctx, req.CustomAgent, chatManage)
+
+ // Determine pipeline based on knowledge bases availability and web search setting
+ // If no knowledge bases are selected AND web search is disabled, use pure chat pipeline
+ // Otherwise use rag_stream pipeline (which handles both KB search and web search)
+ var pipeline []types.EventType
+ if len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) == 0 && !req.WebSearchEnabled {
+ logger.Info(ctx, "No knowledge bases selected and web search disabled, using chat pipeline")
+ // 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 := req.Query
+ if req.ImageDescription != "" && !chatModelSupportsVision {
+ userContent += "\n\n[用户上传图片内容]\n" + req.ImageDescription
+ }
+ chatManage.UserContent = userContent
+
+ // Use chat_history_stream if multi-turn is enabled, otherwise use chat_stream
+ if chatManage.MaxRounds > 0 {
+ logger.Infof(ctx, "Multi-turn enabled with maxRounds=%d, using chat_history_stream pipeline", chatManage.MaxRounds)
+ pipeline = types.Pipline["chat_history_stream"]
+ } else {
+ logger.Info(ctx, "Multi-turn disabled, using chat_stream pipeline")
+ pipeline = types.Pipline["chat_stream"]
+ }
+ } else {
+ if req.WebSearchEnabled && len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) == 0 {
+ logger.Info(ctx, "Web search enabled without knowledge bases, using rag_stream pipeline for web search only")
+ } else {
+ logger.Info(ctx, "Knowledge bases selected, using rag_stream pipeline")
+ }
+ pipeline = types.Pipline["rag_stream"]
+ }
+
+ // Start knowledge QA event processing (set session tenant so pipeline session/message lookups use session owner)
+ ctx = context.WithValue(ctx, types.SessionTenantIDContextKey, req.Session.TenantID)
+ logger.Info(ctx, "Triggering question answering event")
+ err = s.KnowledgeQAByEvent(ctx, chatManage, pipeline)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, map[string]interface{}{
+ "session_id": req.Session.ID,
+ })
+ return err
+ }
+
+ // Emit references event if we have search results
+ if len(chatManage.MergeResult) > 0 {
+ logger.Infof(ctx, "Emitting references event with %d results", len(chatManage.MergeResult))
+ if err := eventBus.Emit(ctx, event.Event{
+ ID: generateEventID("references"),
+ Type: event.EventAgentReferences,
+ SessionID: req.Session.ID,
+ Data: event.AgentReferencesData{
+ References: chatManage.MergeResult,
+ },
+ }); err != nil {
+ logger.Errorf(ctx, "Failed to emit references event: %v", err)
+ }
+ }
+
+ // Note: Answer events are now emitted directly by chat_completion_stream plugin
+ // Completion event will be emitted when the last answer event has Done=true
+ // We can optionally add a completion watcher here if needed, but for now
+ // the frontend can detect completion from the Done flag
+
+ logger.Info(ctx, "Knowledge base question answering initiated")
+ return nil
+}
+
+// selectChatModelID selects the appropriate chat model ID with priority for Remote models
+// Priority order:
+// 1. Session's SummaryModelID if it's a Remote model
+// 2. First knowledge base with a Remote model (from knowledgeBaseIDs or derived from knowledgeIDs)
+// 3. Session's SummaryModelID (if not Remote)
+// 4. First knowledge base's SummaryModelID
+func (s *sessionService) selectChatModelID(
+ ctx context.Context,
+ session *types.Session,
+ knowledgeBaseIDs []string,
+ knowledgeIDs []string,
+) (string, error) {
+ // If no knowledge base IDs but have knowledge IDs, derive KB IDs from knowledge IDs (include shared KB files)
+ if len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) > 0 {
+ tenantID := types.MustTenantIDFromContext(ctx)
+ knowledgeList, err := s.knowledgeService.GetKnowledgeBatchWithSharedAccess(ctx, tenantID, knowledgeIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to get knowledge batch for model selection: %v", err)
+ } else {
+ // Collect unique KB IDs from knowledge items
+ kbIDSet := make(map[string]bool)
+ for _, k := range knowledgeList {
+ if k != nil && k.KnowledgeBaseID != "" {
+ kbIDSet[k.KnowledgeBaseID] = true
+ }
+ }
+ for kbID := range kbIDSet {
+ knowledgeBaseIDs = append(knowledgeBaseIDs, kbID)
+ }
+ logger.Infof(ctx, "Derived %d knowledge base IDs from %d knowledge IDs for model selection",
+ len(knowledgeBaseIDs), len(knowledgeIDs))
+ }
+ }
+ // Check knowledge bases for models
+ if len(knowledgeBaseIDs) > 0 {
+ // Try to find a knowledge base with Remote model
+ for _, kbID := range knowledgeBaseIDs {
+ kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, kbID)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to get knowledge base: %v", err)
+ continue
+ }
+ if kb != nil && kb.SummaryModelID != "" {
+ model, err := s.modelService.GetModelByID(ctx, kb.SummaryModelID)
+ if err == nil && model != nil && model.Source == types.ModelSourceRemote {
+ logger.Info(ctx, "Using Remote summary model from knowledge base")
+ return kb.SummaryModelID, nil
+ }
+ }
+ }
+
+ // If no Remote model found, use first knowledge base's model
+ kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, knowledgeBaseIDs[0])
+ if err != nil {
+ logger.Errorf(ctx, "Failed to get knowledge base for model ID: %v", err)
+ return "", fmt.Errorf("failed to get knowledge base %s: %w", knowledgeBaseIDs[0], err)
+ }
+ if kb != nil && kb.SummaryModelID != "" {
+ logger.Infof(
+ ctx,
+ "Using summary model from first knowledge base %s: %s",
+ knowledgeBaseIDs[0],
+ kb.SummaryModelID,
+ )
+ return kb.SummaryModelID, nil
+ }
+ }
+
+ // No knowledge bases - try to find any available chat model
+ models, err := s.modelService.ListModels(ctx)
+ if err != nil {
+ logger.Errorf(ctx, "Failed to list models: %v", err)
+ return "", fmt.Errorf("failed to list models: %w", err)
+ }
+ for _, model := range models {
+ if model != nil && model.Type == types.ModelTypeKnowledgeQA {
+ logger.Infof(ctx, "Using first available KnowledgeQA model: %s", model.ID)
+ return model.ID, nil
+ }
+ }
+
+ logger.Error(ctx, "No chat model ID available")
+ return "", fmt.Errorf("no chat model ID available: no knowledge bases configured and no available models")
+}
+
+// resolveKnowledgeBasesFromAgent resolves knowledge base IDs based on agent's KBSelectionMode.
+// sessionTenantID is the tenant of the current session (caller); it is compared with
+// customAgent.TenantID to detect the shared-agent scenario and avoid leaking the
+// current user's personal shared KBs into the agent's retrieval scope.
+//
+// Returns the resolved knowledge base IDs based on the selection mode:
+// - "all": fetches all knowledge bases for the tenant
+// - "selected": uses the explicitly configured knowledge bases
+// - "none": returns empty slice
+// - default: falls back to configured knowledge bases for backward compatibility
+func (s *sessionService) resolveKnowledgeBasesFromAgent(
+ ctx context.Context,
+ customAgent *types.CustomAgent,
+ sessionTenantID uint64,
+) []string {
+ if customAgent == nil {
+ return nil
+ }
+
+ switch customAgent.Config.KBSelectionMode {
+ case "all":
+ // Get own knowledge bases (uses ctx TenantID = agent's tenant)
+ allKBs, err := s.knowledgeBaseService.ListKnowledgeBases(ctx)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to list all knowledge bases: %v", err)
+ }
+ kbIDSet := make(map[string]bool)
+ kbIDs := make([]string, 0, len(allKBs))
+ for _, kb := range allKBs {
+ kbIDs = append(kbIDs, kb.ID)
+ kbIDSet[kb.ID] = true
+ }
+
+ // For shared agents (session tenant != agent tenant), only use the agent
+ // tenant's own KBs. Including the current user's shared KBs would leak
+ // unrelated KBs from other organisations into the agent's retrieval scope.
+ isSharedAgent := sessionTenantID != 0 && sessionTenantID != customAgent.TenantID
+ if !isSharedAgent {
+ tenantID := types.MustTenantIDFromContext(ctx)
+ userIDVal := ctx.Value(types.UserIDContextKey)
+ if userIDVal != nil {
+ if userID, ok := userIDVal.(string); ok && userID != "" && s.kbShareService != nil {
+ sharedList, err := s.kbShareService.ListSharedKnowledgeBases(ctx, userID, tenantID)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to list shared knowledge bases: %v", err)
+ } else {
+ for _, info := range sharedList {
+ if info != nil && info.KnowledgeBase != nil && !kbIDSet[info.KnowledgeBase.ID] {
+ kbIDs = append(kbIDs, info.KnowledgeBase.ID)
+ kbIDSet[info.KnowledgeBase.ID] = true
+ }
+ }
+ }
+ }
+ }
+ } else {
+ logger.Infof(ctx, "Shared agent detected (session tenant %d != agent tenant %d): skipping user's shared KBs",
+ sessionTenantID, customAgent.TenantID)
+ }
+
+ logger.Infof(ctx, "KBSelectionMode=all: loaded %d knowledge bases (own + shared)", len(kbIDs))
+ return kbIDs
+ case "selected":
+ logger.Infof(ctx, "KBSelectionMode=selected: using %d configured knowledge bases", len(customAgent.Config.KnowledgeBases))
+ return customAgent.Config.KnowledgeBases
+ case "none":
+ logger.Infof(ctx, "KBSelectionMode=none: no knowledge bases configured")
+ return nil
+ default:
+ // Default to "selected" behavior for backward compatibility
+ if len(customAgent.Config.KnowledgeBases) > 0 {
+ logger.Infof(ctx, "KBSelectionMode not set: using %d configured knowledge bases", len(customAgent.Config.KnowledgeBases))
+ }
+ return customAgent.Config.KnowledgeBases
+ }
+}
+
+// buildSearchTargets computes the unified search targets from knowledgeBaseIDs and knowledgeIDs.
+// tenantID is the retrieval scope: session.TenantID or effective tenant from shared agent (set by handler).
+// This is called once at the request entry point to avoid repeated queries later in the pipeline.
+// Logic:
+// - For each knowledgeBaseID: resolve actual TenantID (own, org-shared, or in retrieval-tenant scope for shared agent)
+// - For each knowledgeID: find its knowledgeBaseID; if the KB is already in the list, skip; otherwise add SearchTargetTypeKnowledge
+func (s *sessionService) buildSearchTargets(
+ ctx context.Context,
+ tenantID uint64,
+ knowledgeBaseIDs []string,
+ knowledgeIDs []string,
+) (types.SearchTargets, error) {
+ var targets types.SearchTargets
+
+ // Build a map from KB ID to TenantID for all KBs we need to process
+ kbTenantMap := make(map[string]uint64)
+
+ // Track which KBs are fully searched
+ fullKBSet := make(map[string]bool)
+
+ // First pass: batch-fetch KBs, then resolve tenant per ID (tenant scope already set by caller)
+ if len(knowledgeBaseIDs) > 0 {
+ kbs, _ := s.knowledgeBaseService.GetKnowledgeBasesByIDsOnly(ctx, knowledgeBaseIDs)
+ kbByID := make(map[string]*types.KnowledgeBase, len(kbs))
+ for _, kb := range kbs {
+ if kb != nil {
+ kbByID[kb.ID] = kb
+ }
+ }
+ userID, _ := types.UserIDFromContext(ctx)
+ for _, kbID := range knowledgeBaseIDs {
+ fullKBSet[kbID] = true
+ kb := kbByID[kbID]
+ if kb == nil {
+ kbTenantMap[kbID] = tenantID
+ } else if kb.TenantID == tenantID {
+ kbTenantMap[kbID] = tenantID
+ } else if s.kbShareService != nil && userID != "" {
+ hasAccess, _ := s.kbShareService.HasKBPermission(ctx, kbID, userID, types.OrgRoleViewer)
+ if hasAccess {
+ kbTenantMap[kbID] = kb.TenantID
+ } else {
+ kbTenantMap[kbID] = tenantID
+ }
+ } else {
+ kbTenantMap[kbID] = tenantID
+ }
+ targets = append(targets, &types.SearchTarget{
+ Type: types.SearchTargetTypeKnowledgeBase,
+ KnowledgeBaseID: kbID,
+ TenantID: kbTenantMap[kbID],
+ })
+ }
+ }
+
+ // Process individual knowledge IDs (include shared KB files the user has access to)
+ if len(knowledgeIDs) > 0 {
+ knowledgeList, err := s.knowledgeService.GetKnowledgeBatchWithSharedAccess(ctx, tenantID, knowledgeIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to get knowledge batch for search targets: %v", err)
+ return targets, nil // Return what we have, don't fail
+ }
+
+ // Group knowledge IDs by their KB, excluding those already covered by full KB search
+ // Also track KB tenant IDs from knowledge items
+ kbToKnowledgeIDs := make(map[string][]string)
+ for _, k := range knowledgeList {
+ if k == nil || k.KnowledgeBaseID == "" {
+ continue
+ }
+ // Track KB -> TenantID mapping from knowledge items
+ if kbTenantMap[k.KnowledgeBaseID] == 0 {
+ kbTenantMap[k.KnowledgeBaseID] = k.TenantID
+ }
+ // Skip if this KB is already fully searched
+ if fullKBSet[k.KnowledgeBaseID] {
+ continue
+ }
+ kbToKnowledgeIDs[k.KnowledgeBaseID] = append(kbToKnowledgeIDs[k.KnowledgeBaseID], k.ID)
+ }
+
+ // Create SearchTargetTypeKnowledge targets for each KB with specific files
+ for kbID, kidList := range kbToKnowledgeIDs {
+ kbTenant := kbTenantMap[kbID]
+ if kbTenant == 0 {
+ kbTenant = tenantID // fallback
+ }
+ targets = append(targets, &types.SearchTarget{
+ Type: types.SearchTargetTypeKnowledge,
+ KnowledgeBaseID: kbID,
+ TenantID: kbTenant,
+ KnowledgeIDs: kidList,
+ })
+ }
+ }
+
+ logger.Infof(ctx, "Built %d search targets: %d full KB, %d partial KB, kbTenantMap=%v",
+ len(targets), len(knowledgeBaseIDs), len(targets)-len(knowledgeBaseIDs), kbTenantMap)
+
+ return targets, nil
+}
+
+// KnowledgeQAByEvent processes knowledge QA through a series of events in the pipeline
+func (s *sessionService) KnowledgeQAByEvent(ctx context.Context,
+ chatManage *types.ChatManage, eventList []types.EventType,
+) error {
+ ctx, span := tracing.ContextWithSpan(ctx, "SessionService.KnowledgeQAByEvent")
+ defer span.End()
+
+ logger.Info(ctx, "Start processing knowledge base question answering through events")
+ logger.Infof(ctx, "Knowledge base question answering parameters, session ID: %s, query: %s",
+ chatManage.SessionID, chatManage.Query)
+
+ // Prepare method list for logging and tracing
+ methods := []string{}
+ for _, event := range eventList {
+ methods = append(methods, string(event))
+ }
+
+ // Set up tracing attributes
+ logger.Infof(ctx, "Trigger event list: %v", methods)
+ span.SetAttributes(
+ attribute.String("request_id", func() string { id, _ := types.RequestIDFromContext(ctx); return id }()),
+ attribute.String("query", chatManage.Query),
+ attribute.String("method", strings.Join(methods, ",")),
+ )
+
+ // Process each event in sequence
+ for _, eventType := range eventList {
+ logger.Infof(ctx, "Starting to trigger event: %v", eventType)
+ err := s.eventManager.Trigger(ctx, eventType, chatManage)
+
+ // Handle case where search returns no results
+ if err == chatpipline.ErrSearchNothing {
+ logger.Warnf(
+ ctx,
+ "Event %v triggered, search result is empty, using fallback response, strategy: %v",
+ eventType,
+ chatManage.FallbackStrategy,
+ )
+ s.handleFallbackResponse(ctx, chatManage)
+ return nil
+ }
+
+ // Handle other errors
+ if err != nil {
+ logger.Errorf(ctx, "Event triggering failed, event: %v, error type: %s, description: %s, error: %v",
+ eventType, err.ErrorType, err.Description, err.Err)
+ span.RecordError(err.Err)
+ span.SetStatus(codes.Error, err.Description)
+ span.SetAttributes(attribute.String("error_type", err.ErrorType))
+ return err.Err
+ }
+ logger.Infof(ctx, "Event %v triggered successfully", eventType)
+ }
+
+ logger.Info(ctx, "All events triggered successfully")
+ return nil
+}
+
+// SearchKnowledge performs knowledge base search without LLM summarization
+// knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB)
+// knowledgeIDs: list of specific knowledge (file) IDs to search
+func (s *sessionService) SearchKnowledge(ctx context.Context,
+ knowledgeBaseIDs []string, knowledgeIDs []string, query string,
+) ([]*types.SearchResult, error) {
+ logger.Info(ctx, "Start knowledge base search without LLM summary")
+ logger.Infof(ctx, "Knowledge base search parameters, knowledge base IDs: %v, knowledge IDs: %v, query: %s",
+ knowledgeBaseIDs, knowledgeIDs, query)
+
+ // Get tenant ID from context
+ tenantID, ok := types.TenantIDFromContext(ctx)
+ if !ok {
+ logger.Error(ctx, "Failed to get tenant ID from context")
+ return nil, fmt.Errorf("tenant ID not found in context")
+ }
+
+ // Build unified search targets (computed once, used throughout pipeline)
+ searchTargets, err := s.buildSearchTargets(ctx, tenantID, knowledgeBaseIDs, knowledgeIDs)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to build search targets: %v", err)
+ }
+
+ if len(searchTargets) == 0 {
+ logger.Warn(ctx, "No search targets available, returning empty results")
+ return []*types.SearchResult{}, nil
+ }
+
+ // Create default retrieval parameters — prefer tenant RetrievalConfig, fallback to built-in defaults
+ userID, _ := types.UserIDFromContext(ctx)
+
+ // Load tenant-level retrieval config (nil is safe — GetEffective* methods handle nil receiver)
+ var rc *types.RetrievalConfig
+ if tenant, err2 := s.tenantService.GetTenantByID(ctx, tenantID); err2 == nil {
+ rc = tenant.RetrievalConfig
+ }
+
+ chatManage := &types.ChatManage{
+ Query: query,
+ RewriteQuery: query,
+ UserID: userID,
+ KnowledgeBaseIDs: knowledgeBaseIDs,
+ KnowledgeIDs: knowledgeIDs,
+ SearchTargets: searchTargets,
+ MaxRounds: s.cfg.Conversation.MaxRounds,
+ EmbeddingTopK: rc.GetEffectiveEmbeddingTopK(),
+ VectorThreshold: rc.GetEffectiveVectorThreshold(),
+ KeywordThreshold: rc.GetEffectiveKeywordThreshold(),
+ RerankTopK: rc.GetEffectiveRerankTopK(),
+ RerankThreshold: rc.GetEffectiveRerankThreshold(),
+ }
+
+ // Get default models
+ models, err := s.modelService.ListModels(ctx)
+ if err != nil {
+ logger.Errorf(ctx, "Failed to get models: %v", err)
+ return nil, err
+ }
+
+ // Use rerank model from RetrievalConfig if set, otherwise auto-select the first available
+ if rc != nil && rc.RerankModelID != "" {
+ chatManage.RerankModelID = rc.RerankModelID
+ } else {
+ for _, model := range models {
+ if model == nil {
+ continue
+ }
+ if model.Type == types.ModelTypeRerank {
+ chatManage.RerankModelID = model.ID
+ break
+ }
+ }
+ }
+
+ // Use specific event list, only including retrieval-related events, not LLM summarization
+ searchEvents := []types.EventType{
+ types.CHUNK_SEARCH, // Vector search
+ types.CHUNK_RERANK, // Rerank search results
+ types.CHUNK_MERGE, // Merge search results
+ types.FILTER_TOP_K, // Filter top K results
+ }
+
+ ctx, span := tracing.ContextWithSpan(ctx, "SessionService.SearchKnowledge")
+ defer span.End()
+
+ // Prepare method list for logging and tracing
+ methods := []string{}
+ for _, event := range searchEvents {
+ methods = append(methods, string(event))
+ }
+
+ // Set up tracing attributes
+ logger.Infof(ctx, "Trigger search event list: %v", methods)
+ span.SetAttributes(
+ attribute.String("query", query),
+ attribute.StringSlice("knowledge_base_ids", knowledgeBaseIDs),
+ attribute.StringSlice("knowledge_ids", knowledgeIDs),
+ attribute.String("method", strings.Join(methods, ",")),
+ )
+
+ // Process each search event in sequence
+ for _, event := range searchEvents {
+ logger.Infof(ctx, "Starting to trigger search event: %v", event)
+ err := s.eventManager.Trigger(ctx, event, chatManage)
+
+ // Handle case where search returns no results
+ if err == chatpipline.ErrSearchNothing {
+ logger.Warnf(ctx, "Event %v triggered, search result is empty", event)
+ return []*types.SearchResult{}, nil
+ }
+
+ // Handle other errors
+ if err != nil {
+ logger.Errorf(ctx, "Event triggering failed, event: %v, error type: %s, description: %s, error: %v",
+ event, err.ErrorType, err.Description, err.Err)
+ span.RecordError(err.Err)
+ span.SetStatus(codes.Error, err.Description)
+ span.SetAttributes(attribute.String("error_type", err.ErrorType))
+ return nil, err.Err
+ }
+ logger.Infof(ctx, "Event %v triggered successfully", event)
+ }
+
+ logger.Infof(ctx, "Knowledge base search completed, found %d results", len(chatManage.MergeResult))
+ return chatManage.MergeResult, nil
+}
+
+// handleFallbackResponse handles fallback response based on strategy
+func (s *sessionService) handleFallbackResponse(ctx context.Context, chatManage *types.ChatManage) {
+ if chatManage.FallbackStrategy == types.FallbackStrategyModel {
+ s.handleModelFallback(ctx, chatManage)
+ } else {
+ s.handleFixedFallback(ctx, chatManage)
+ }
+}
+
+// handleFixedFallback handles fixed fallback response
+func (s *sessionService) handleFixedFallback(ctx context.Context, chatManage *types.ChatManage) {
+ fallbackContent := chatManage.FallbackResponse
+ chatManage.ChatResponse = &types.ChatResponse{Content: fallbackContent}
+ s.emitFallbackAnswer(ctx, chatManage, fallbackContent)
+}
+
+// handleModelFallback handles model-based fallback response using streaming
+func (s *sessionService) handleModelFallback(ctx context.Context, chatManage *types.ChatManage) {
+ // Check if FallbackPrompt is available
+ if chatManage.FallbackPrompt == "" {
+ logger.Warnf(ctx, "Fallback strategy is 'model' but FallbackPrompt is empty, falling back to fixed response")
+ s.handleFixedFallback(ctx, chatManage)
+ return
+ }
+
+ // Render template with Query variable
+ promptContent, err := s.renderFallbackPrompt(ctx, chatManage)
+ if err != nil {
+ logger.Errorf(ctx, "Failed to render fallback prompt: %v, falling back to fixed response", err)
+ s.handleFixedFallback(ctx, chatManage)
+ return
+ }
+
+ // Check if EventBus is available for streaming
+ if chatManage.EventBus == nil {
+ logger.Warnf(ctx, "EventBus not available for streaming fallback, falling back to fixed response")
+ s.handleFixedFallback(ctx, chatManage)
+ return
+ }
+
+ // Get chat model
+ chatModel, err := s.modelService.GetChatModel(ctx, chatManage.ChatModelID)
+ if err != nil {
+ logger.Errorf(ctx, "Failed to get chat model for fallback: %v, falling back to fixed response", err)
+ s.handleFixedFallback(ctx, chatManage)
+ return
+ }
+
+ // Prepare chat options
+ thinking := false
+ opt := &chat.ChatOptions{
+ Temperature: chatManage.SummaryConfig.Temperature,
+ MaxCompletionTokens: chatManage.SummaryConfig.MaxCompletionTokens,
+ Thinking: &thinking,
+ }
+
+ // Start streaming response
+ 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)
+ return
+ }
+
+ if responseChan == nil {
+ logger.Errorf(ctx, "Chat stream returned nil channel, falling back to fixed response")
+ s.handleFixedFallback(ctx, chatManage)
+ return
+ }
+
+ // Start goroutine to consume stream and emit events
+ go s.consumeFallbackStream(ctx, chatManage, responseChan)
+}
+
+// renderFallbackPrompt renders the fallback prompt template with query and image context.
+func (s *sessionService) renderFallbackPrompt(ctx context.Context, chatManage *types.ChatManage) (string, error) {
+ 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
+}
+
+// consumeFallbackStream consumes the streaming response and emits events
+func (s *sessionService) consumeFallbackStream(
+ ctx context.Context,
+ chatManage *types.ChatManage,
+ responseChan <-chan types.StreamResponse,
+) {
+ fallbackID := generateEventID("fallback")
+ eventBus := chatManage.EventBus
+ var finalContent string
+ streamCompleted := false
+
+ for response := range responseChan {
+ // Emit event for each answer chunk
+ if response.ResponseType == types.ResponseTypeAnswer {
+ finalContent += response.Content
+ if err := eventBus.Emit(ctx, types.Event{
+ ID: fallbackID,
+ Type: types.EventType(event.EventAgentFinalAnswer),
+ SessionID: chatManage.SessionID,
+ Data: event.AgentFinalAnswerData{
+ Content: response.Content,
+ Done: response.Done,
+ IsFallback: true,
+ },
+ }); err != nil {
+ logger.Errorf(ctx, "Failed to emit fallback answer chunk event: %v", err)
+ }
+
+ // Update ChatResponse with final content when done
+ if response.Done {
+ chatManage.ChatResponse = &types.ChatResponse{Content: finalContent}
+ streamCompleted = true
+ logger.Infof(ctx, "Fallback streaming response completed")
+ break
+ }
+ }
+ }
+
+ // If channel closed without Done=true, emit final event with fixed response
+ if !streamCompleted {
+ logger.Warnf(ctx, "Fallback stream closed without completion, emitting final event with fixed response")
+ s.emitFallbackAnswer(ctx, chatManage, chatManage.FallbackResponse)
+ }
+}
+
+// emitFallbackAnswer emits fallback answer event
+func (s *sessionService) emitFallbackAnswer(ctx context.Context, chatManage *types.ChatManage, content string) {
+ if chatManage.EventBus == nil {
+ return
+ }
+
+ fallbackID := generateEventID("fallback")
+ if err := chatManage.EventBus.Emit(ctx, types.Event{
+ ID: fallbackID,
+ Type: types.EventType(event.EventAgentFinalAnswer),
+ SessionID: chatManage.SessionID,
+ Data: event.AgentFinalAnswerData{
+ Content: content,
+ Done: true,
+ IsFallback: true,
+ },
+ }); err != nil {
+ logger.Errorf(ctx, "Failed to emit fallback answer event: %v", err)
+ } else {
+ logger.Infof(ctx, "Fallback answer event emitted successfully")
+ }
+}
diff --git a/internal/application/service/session_qa_helpers.go b/internal/application/service/session_qa_helpers.go
new file mode 100644
index 00000000..5302f145
--- /dev/null
+++ b/internal/application/service/session_qa_helpers.go
@@ -0,0 +1,194 @@
+package service
+
+import (
+ "context"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// ---------------------------------------------------------------------------
+// Shared QA helpers: KB resolution, model resolution, retrieval tenant
+// ---------------------------------------------------------------------------
+
+// resolveKnowledgeBases resolves the effective knowledge base IDs and knowledge IDs
+// for a QA request. Priority:
+// 1. Explicit @mentions (request-specified kbIDs / knowledgeIDs)
+// 2. RetrieveKBOnlyWhenMentioned -> disable KB if no mention
+// 3. Agent's configured knowledge bases (via KBSelectionMode)
+func (s *sessionService) resolveKnowledgeBases(
+ ctx context.Context,
+ req *types.QARequest,
+) (kbIDs []string, knowledgeIDs []string) {
+ kbIDs = req.KnowledgeBaseIDs
+ knowledgeIDs = req.KnowledgeIDs
+ customAgent := req.CustomAgent
+
+ hasExplicitMention := len(kbIDs) > 0 || len(knowledgeIDs) > 0
+ if customAgent != nil {
+ logger.Infof(ctx, "KB resolution: hasExplicitMention=%v, RetrieveKBOnlyWhenMentioned=%v, KBSelectionMode=%s",
+ hasExplicitMention, customAgent.Config.RetrieveKBOnlyWhenMentioned, customAgent.Config.KBSelectionMode)
+ }
+
+ if hasExplicitMention {
+ logger.Infof(ctx, "Using request-specified targets: kbs=%v, docs=%v", kbIDs, knowledgeIDs)
+ } else if customAgent != nil && customAgent.Config.RetrieveKBOnlyWhenMentioned {
+ kbIDs = nil
+ knowledgeIDs = nil
+ logger.Infof(ctx, "RetrieveKBOnlyWhenMentioned is enabled and no @ mention found, KB retrieval disabled for this request")
+ } else if customAgent != nil {
+ kbIDs = s.resolveKnowledgeBasesFromAgent(ctx, customAgent, req.Session.TenantID)
+ }
+ return kbIDs, knowledgeIDs
+}
+
+// resolveChatModelID resolves the effective chat model ID for a QA request.
+// Priority:
+// 1. Request's SummaryModelID (explicit override, validated)
+// 2. Custom agent's ModelID
+// 3. KB / session / system default (via selectChatModelID)
+func (s *sessionService) resolveChatModelID(
+ ctx context.Context,
+ req *types.QARequest,
+ knowledgeBaseIDs []string,
+ knowledgeIDs []string,
+) (string, error) {
+ summaryModelID := req.SummaryModelID
+ customAgent := req.CustomAgent
+ session := req.Session
+
+ if summaryModelID != "" {
+ if model, err := s.modelService.GetModelByID(ctx, summaryModelID); err == nil && model != nil {
+ logger.Infof(ctx, "Using request's summary model override: %s", summaryModelID)
+ return summaryModelID, nil
+ }
+ logger.Warnf(ctx, "Request provided invalid summary model ID %s, falling back", summaryModelID)
+ }
+ if customAgent != nil && customAgent.Config.ModelID != "" {
+ logger.Infof(ctx, "Using custom agent's model_id: %s", customAgent.Config.ModelID)
+ return customAgent.Config.ModelID, nil
+ }
+ return s.selectChatModelID(ctx, session, knowledgeBaseIDs, knowledgeIDs)
+}
+
+// resolveRetrievalTenantID determines the tenant ID to use for retrieval scope.
+// Priority: agent's tenant > context tenant > session tenant.
+func (s *sessionService) resolveRetrievalTenantID(
+ ctx context.Context,
+ req *types.QARequest,
+) uint64 {
+ session := req.Session
+ customAgent := req.CustomAgent
+
+ retrievalTenantID := session.TenantID
+ if customAgent != nil && customAgent.TenantID != 0 {
+ retrievalTenantID = customAgent.TenantID
+ logger.Infof(ctx, "Using agent tenant %d for retrieval scope", retrievalTenantID)
+ } else if v := ctx.Value(types.TenantIDContextKey); v != nil {
+ if tid, ok := v.(uint64); ok && tid != 0 {
+ retrievalTenantID = tid
+ logger.Infof(ctx, "Using effective tenant %d for retrieval from context", retrievalTenantID)
+ }
+ }
+ return retrievalTenantID
+}
+
+// applyAgentOverridesToChatManage applies custom agent configuration overrides
+// to a ChatManage object that was initialized with system defaults.
+// This covers: system prompt, context template, temperature, max tokens, thinking,
+// retrieval thresholds, rewrite settings, fallback settings, FAQ strategy, and history turns.
+func (s *sessionService) applyAgentOverridesToChatManage(
+ ctx context.Context,
+ customAgent *types.CustomAgent,
+ cm *types.ChatManage,
+) {
+ if customAgent == nil {
+ return
+ }
+
+ // Ensure defaults are set
+ customAgent.EnsureDefaults()
+
+ // Override summary config fields
+ if customAgent.Config.SystemPrompt != "" {
+ cm.SummaryConfig.Prompt = customAgent.Config.SystemPrompt
+ logger.Infof(ctx, "Using custom agent's system_prompt")
+ }
+ if customAgent.Config.ContextTemplate != "" {
+ cm.SummaryConfig.ContextTemplate = customAgent.Config.ContextTemplate
+ logger.Infof(ctx, "Using custom agent's context_template")
+ }
+ if customAgent.Config.Temperature > 0 {
+ cm.SummaryConfig.Temperature = customAgent.Config.Temperature
+ logger.Infof(ctx, "Using custom agent's temperature: %f", customAgent.Config.Temperature)
+ }
+ if customAgent.Config.MaxCompletionTokens > 0 {
+ cm.SummaryConfig.MaxCompletionTokens = customAgent.Config.MaxCompletionTokens
+ logger.Infof(ctx, "Using custom agent's max_completion_tokens: %d", customAgent.Config.MaxCompletionTokens)
+ }
+ // Agent-level thinking setting takes full control (no global fallback)
+ cm.SummaryConfig.Thinking = customAgent.Config.Thinking
+ if customAgent.Config.Thinking != nil {
+ logger.Infof(ctx, "Using custom agent's thinking: %v", *customAgent.Config.Thinking)
+ }
+
+ // Override retrieval strategy settings
+ if customAgent.Config.EmbeddingTopK > 0 {
+ cm.EmbeddingTopK = customAgent.Config.EmbeddingTopK
+ }
+ if customAgent.Config.KeywordThreshold > 0 {
+ cm.KeywordThreshold = customAgent.Config.KeywordThreshold
+ }
+ if customAgent.Config.VectorThreshold > 0 {
+ cm.VectorThreshold = customAgent.Config.VectorThreshold
+ }
+ if customAgent.Config.RerankTopK > 0 {
+ cm.RerankTopK = customAgent.Config.RerankTopK
+ }
+ if customAgent.Config.RerankThreshold > 0 {
+ cm.RerankThreshold = customAgent.Config.RerankThreshold
+ }
+ if customAgent.Config.RerankModelID != "" {
+ cm.RerankModelID = customAgent.Config.RerankModelID
+ }
+
+ // Override rewrite settings
+ cm.EnableRewrite = customAgent.Config.EnableRewrite
+ cm.EnableQueryExpansion = customAgent.Config.EnableQueryExpansion
+ if customAgent.Config.RewritePromptSystem != "" {
+ cm.RewritePromptSystem = customAgent.Config.RewritePromptSystem
+ }
+ if customAgent.Config.RewritePromptUser != "" {
+ cm.RewritePromptUser = customAgent.Config.RewritePromptUser
+ }
+
+ // Override fallback settings
+ if customAgent.Config.FallbackStrategy != "" {
+ cm.FallbackStrategy = types.FallbackStrategy(customAgent.Config.FallbackStrategy)
+ }
+ if customAgent.Config.FallbackResponse != "" {
+ cm.FallbackResponse = customAgent.Config.FallbackResponse
+ }
+ if customAgent.Config.FallbackPrompt != "" {
+ cm.FallbackPrompt = customAgent.Config.FallbackPrompt
+ }
+
+ // Override history turns
+ if customAgent.Config.HistoryTurns > 0 {
+ cm.MaxRounds = customAgent.Config.HistoryTurns
+ logger.Infof(ctx, "Using custom agent's history_turns: %d", cm.MaxRounds)
+ }
+ if !customAgent.Config.MultiTurnEnabled {
+ cm.MaxRounds = 0
+ logger.Infof(ctx, "Multi-turn disabled by custom agent, clearing history")
+ }
+
+ // FAQ strategy settings
+ cm.FAQPriorityEnabled = customAgent.Config.FAQPriorityEnabled
+ cm.FAQDirectAnswerThreshold = customAgent.Config.FAQDirectAnswerThreshold
+ cm.FAQScoreBoost = customAgent.Config.FAQScoreBoost
+ if cm.FAQPriorityEnabled {
+ logger.Infof(ctx, "FAQ priority enabled: threshold=%.2f, boost=%.2f",
+ cm.FAQDirectAnswerThreshold, cm.FAQScoreBoost)
+ }
+}
diff --git a/internal/container/container.go b/internal/container/container.go
index 4475f66e..b862a197 100644
--- a/internal/container/container.go
+++ b/internal/container/container.go
@@ -6,6 +6,7 @@ package container
import (
"context"
"database/sql"
+ "encoding/json"
"fmt"
"net/url"
"os"
@@ -52,6 +53,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 +239,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(registerIMAdapterFactories))
+ must(container.Provide(handler.NewIMHandler))
logger.Debugf(ctx, "[Container] HTTP handlers registered")
// Router configuration
@@ -937,3 +947,134 @@ func registerWebSearchProviders(registry *web_search.Registry) {
return web_search.NewBingProvider()
})
}
+
+// registerIMAdapterFactories registers adapter factories for each IM platform
+// and loads enabled channels from the database.
+func registerIMAdapterFactories(imService *imPkg.Service) {
+ ctx := context.Background()
+
+ // Register WeCom adapter factory
+ imService.RegisterAdapterFactory("wecom", func(factoryCtx context.Context, channel *imPkg.IMChannel, msgHandler func(context.Context, *imPkg.IncomingMessage) error) (imPkg.Adapter, context.CancelFunc, error) {
+ creds, err := parseCredentials(channel.Credentials)
+ if err != nil {
+ return nil, nil, fmt.Errorf("parse wecom credentials: %w", err)
+ }
+
+ mode := channel.Mode
+ if mode == "" {
+ mode = "websocket"
+ }
+
+ switch mode {
+ case "webhook":
+ corpAgentID := 0
+ if v, ok := creds["corp_agent_id"]; ok {
+ switch val := v.(type) {
+ case float64:
+ corpAgentID = int(val)
+ case int:
+ corpAgentID = val
+ }
+ }
+ adapter, err := wecom.NewWebhookAdapter(
+ getString(creds, "corp_id"),
+ getString(creds, "agent_secret"),
+ getString(creds, "token"),
+ getString(creds, "encoding_aes_key"),
+ corpAgentID,
+ )
+ if err != nil {
+ return nil, nil, err
+ }
+ return adapter, nil, nil
+
+ case "websocket":
+ client := wecom.NewLongConnClient(
+ getString(creds, "bot_id"),
+ getString(creds, "bot_secret"),
+ msgHandler,
+ )
+
+ wsCtx, wsCancel := context.WithCancel(context.Background())
+ go func() {
+ if err := client.Start(wsCtx); err != nil && wsCtx.Err() == nil {
+ logger.Errorf(context.Background(), "[IM] WeCom long connection stopped for channel %s: %v", channel.ID, err)
+ }
+ }()
+
+ adapter := wecom.NewWSAdapter(client)
+ return adapter, wsCancel, nil
+
+ default:
+ return nil, nil, fmt.Errorf("unknown WeCom mode: %s", mode)
+ }
+ })
+
+ // Register Feishu adapter factory
+ imService.RegisterAdapterFactory("feishu", func(factoryCtx context.Context, channel *imPkg.IMChannel, msgHandler func(context.Context, *imPkg.IncomingMessage) error) (imPkg.Adapter, context.CancelFunc, error) {
+ creds, err := parseCredentials(channel.Credentials)
+ if err != nil {
+ return nil, nil, fmt.Errorf("parse feishu credentials: %w", err)
+ }
+
+ appID := getString(creds, "app_id")
+ appSecret := getString(creds, "app_secret")
+ verificationToken := getString(creds, "verification_token")
+ encryptKey := getString(creds, "encrypt_key")
+
+ // Always create the HTTP adapter (needed for SendReply in both modes)
+ adapter := feishu.NewAdapter(appID, appSecret, verificationToken, encryptKey)
+
+ mode := channel.Mode
+ if mode == "" {
+ mode = "websocket"
+ }
+
+ switch mode {
+ case "webhook":
+ return adapter, nil, nil
+
+ case "websocket":
+ client := feishu.NewLongConnClient(appID, appSecret, msgHandler)
+
+ wsCtx, wsCancel := context.WithCancel(context.Background())
+ go func() {
+ if err := client.Start(wsCtx); err != nil && wsCtx.Err() == nil {
+ logger.Errorf(context.Background(), "[IM] Feishu long connection stopped for channel %s: %v", channel.ID, err)
+ }
+ }()
+
+ return adapter, wsCancel, nil
+
+ default:
+ return nil, nil, fmt.Errorf("unknown Feishu mode: %s", mode)
+ }
+ })
+
+ // Load and start all enabled channels from database
+ if err := imService.LoadAndStartChannels(); err != nil {
+ logger.Warnf(ctx, "[IM] Failed to load channels from database: %v", err)
+ }
+}
+
+// parseCredentials parses the JSONB credentials field into a map.
+func parseCredentials(data []byte) (map[string]interface{}, error) {
+ if len(data) == 0 {
+ return map[string]interface{}{}, nil
+ }
+ var creds map[string]interface{}
+ if err := json.Unmarshal(data, &creds); err != nil {
+ return nil, err
+ }
+ return creds, nil
+}
+
+// getString safely extracts a string value from a credentials map.
+func getString(creds map[string]interface{}, key string) string {
+ if v, ok := creds[key]; ok {
+ if s, ok := v.(string); ok {
+ return s
+ }
+ }
+ return ""
+}
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/handler/im.go b/internal/handler/im.go
new file mode 100644
index 00000000..ec5f7942
--- /dev/null
+++ b/internal/handler/im.go
@@ -0,0 +1,264 @@
+package handler
+
+import (
+ "context"
+ "net/http"
+
+ "github.com/Tencent/WeKnora/internal/im"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/gin-gonic/gin"
+)
+
+// IMHandler handles IM platform callback requests and channel CRUD.
+type IMHandler struct {
+ imService *im.Service
+}
+
+// NewIMHandler creates a new IM handler.
+func NewIMHandler(imService *im.Service) *IMHandler {
+ return &IMHandler{
+ imService: imService,
+ }
+}
+
+// ── Channel CRUD handlers ──
+
+// CreateIMChannel creates a new IM channel for an agent.
+func (h *IMHandler) CreateIMChannel(c *gin.Context) {
+ agentID := c.Param("id")
+ if agentID == "" {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "agent_id is required"})
+ return
+ }
+
+ tenantID, ok := c.Request.Context().Value(types.TenantIDContextKey).(uint64)
+ if !ok {
+ c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+ return
+ }
+
+ var req struct {
+ Platform string `json:"platform" binding:"required"`
+ Name string `json:"name"`
+ Mode string `json:"mode"`
+ OutputMode string `json:"output_mode"`
+ Credentials types.JSON `json:"credentials"`
+ Enabled *bool `json:"enabled"`
+ }
+ if err := c.ShouldBindJSON(&req); err != nil {
+ c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+ return
+ }
+
+ if req.Platform != "wecom" && req.Platform != "feishu" {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "platform must be 'wecom' or 'feishu'"})
+ return
+ }
+
+ channel := &im.IMChannel{
+ TenantID: tenantID,
+ AgentID: agentID,
+ Platform: req.Platform,
+ Name: req.Name,
+ Mode: req.Mode,
+ OutputMode: req.OutputMode,
+ Credentials: req.Credentials,
+ Enabled: true,
+ }
+ if req.Enabled != nil {
+ channel.Enabled = *req.Enabled
+ }
+ if channel.Mode == "" {
+ channel.Mode = "websocket"
+ }
+ if channel.OutputMode == "" {
+ channel.OutputMode = "stream"
+ }
+ if channel.Credentials == nil {
+ channel.Credentials = types.JSON("{}")
+ }
+
+ if err := h.imService.CreateChannel(channel); err != nil {
+ logger.Errorf(c.Request.Context(), "[IM] Create channel failed: %v", err)
+ c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create channel"})
+ return
+ }
+
+ c.JSON(http.StatusOK, gin.H{"data": channel})
+}
+
+// ListIMChannels lists all IM channels for an agent.
+func (h *IMHandler) ListIMChannels(c *gin.Context) {
+ agentID := c.Param("id")
+ if agentID == "" {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "agent_id is required"})
+ return
+ }
+
+ channels, err := h.imService.ListChannelsByAgent(agentID)
+ if err != nil {
+ c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list channels"})
+ return
+ }
+
+ c.JSON(http.StatusOK, gin.H{"data": channels})
+}
+
+// UpdateIMChannel updates an IM channel.
+func (h *IMHandler) UpdateIMChannel(c *gin.Context) {
+ channelID := c.Param("id")
+ if channelID == "" {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "channel id is required"})
+ return
+ }
+
+ channel, err := h.imService.GetChannelByID(channelID)
+ if err != nil {
+ c.JSON(http.StatusNotFound, gin.H{"error": "channel not found"})
+ return
+ }
+
+ var req struct {
+ Name *string `json:"name"`
+ Mode *string `json:"mode"`
+ OutputMode *string `json:"output_mode"`
+ Credentials types.JSON `json:"credentials"`
+ Enabled *bool `json:"enabled"`
+ }
+ if err := c.ShouldBindJSON(&req); err != nil {
+ c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+ return
+ }
+
+ if req.Name != nil {
+ channel.Name = *req.Name
+ }
+ if req.Mode != nil {
+ channel.Mode = *req.Mode
+ }
+ if req.OutputMode != nil {
+ channel.OutputMode = *req.OutputMode
+ }
+ if req.Credentials != nil {
+ channel.Credentials = req.Credentials
+ }
+ if req.Enabled != nil {
+ channel.Enabled = *req.Enabled
+ }
+
+ if err := h.imService.UpdateChannel(channel); err != nil {
+ logger.Errorf(c.Request.Context(), "[IM] Update channel failed: %v", err)
+ c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to update channel"})
+ return
+ }
+
+ c.JSON(http.StatusOK, gin.H{"data": channel})
+}
+
+// DeleteIMChannel deletes an IM channel.
+func (h *IMHandler) DeleteIMChannel(c *gin.Context) {
+ channelID := c.Param("id")
+ if channelID == "" {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "channel id is required"})
+ return
+ }
+
+ if err := h.imService.DeleteChannel(channelID); err != nil {
+ c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to delete channel"})
+ return
+ }
+
+ c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+// ToggleIMChannel toggles the enabled state of an IM channel.
+func (h *IMHandler) ToggleIMChannel(c *gin.Context) {
+ channelID := c.Param("id")
+ if channelID == "" {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "channel id is required"})
+ return
+ }
+
+ channel, err := h.imService.ToggleChannel(channelID)
+ if err != nil {
+ c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to toggle channel"})
+ return
+ }
+
+ c.JSON(http.StatusOK, gin.H{"data": channel})
+}
+
+// ── Callback handlers ──
+
+// IMCallback handles IM platform callback requests for a specific channel.
+// Route: POST /api/v1/im/callback/:channel_id
+func (h *IMHandler) IMCallback(c *gin.Context) {
+ ctx := c.Request.Context()
+ channelID := c.Param("channel_id")
+
+ adapter, channel, ok := h.imService.GetChannelAdapter(channelID)
+ if !ok {
+ // Try loading from DB
+ ch, err := h.imService.GetChannelByID(channelID)
+ if err != nil {
+ logger.Errorf(ctx, "[IM] Channel not found for callback: %s", channelID)
+ c.JSON(http.StatusNotFound, gin.H{"error": "channel not found"})
+ return
+ }
+ if err := h.imService.StartChannel(ch); err != nil {
+ logger.Errorf(ctx, "[IM] Failed to start channel for callback: %v", err)
+ c.JSON(http.StatusServiceUnavailable, gin.H{"error": "channel not available"})
+ return
+ }
+ adapter, channel, ok = h.imService.GetChannelAdapter(channelID)
+ if !ok {
+ c.JSON(http.StatusServiceUnavailable, gin.H{"error": "channel not available"})
+ return
+ }
+ }
+
+ if !channel.Enabled {
+ c.JSON(http.StatusServiceUnavailable, gin.H{"error": "channel is disabled"})
+ return
+ }
+
+ // Handle URL verification
+ if adapter.HandleURLVerification(c) {
+ return
+ }
+
+ // Verify callback signature
+ if err := adapter.VerifyCallback(c); err != nil {
+ logger.Errorf(ctx, "[IM] Callback verification failed for channel %s: %v", channelID, 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] Parse callback failed for channel %s: %v", channelID, err)
+ c.JSON(http.StatusBadRequest, gin.H{"error": "parse failed"})
+ return
+ }
+
+ // If nil, it's a non-message event - just acknowledge
+ if msg == nil {
+ c.JSON(http.StatusOK, gin.H{"success": true})
+ return
+ }
+
+ // Respond immediately to avoid platform timeout
+ c.JSON(http.StatusOK, gin.H{"success": true})
+
+ // Detach from gin request context
+ asyncCtx := context.WithoutCancel(ctx)
+
+ // Process message asynchronously
+ go func() {
+ if err := h.imService.HandleMessage(asyncCtx, msg, channelID); err != nil {
+ logger.Errorf(asyncCtx, "[IM] Handle message error for channel %s: %v", channelID, err)
+ }
+ }()
+}
diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.go
index 457a4ced..4c1d5507 100644
--- a/internal/handler/session/qa.go
+++ b/internal/handler/session/qa.go
@@ -38,6 +38,25 @@ type qaRequestContext struct {
userMessageID string // Created user message ID (populated after createUserMessage)
}
+// buildQARequest converts the qaRequestContext into a types.QARequest for service invocation.
+func (rc *qaRequestContext) buildQARequest() *types.QARequest {
+ imageURLs, imageDescription := extractImageURLsAndOCRText(rc.images)
+ return &types.QARequest{
+ Session: rc.session,
+ Query: rc.query,
+ AssistantMessageID: rc.assistantMessage.ID,
+ SummaryModelID: rc.summaryModelID,
+ CustomAgent: rc.customAgent,
+ KnowledgeBaseIDs: rc.knowledgeBaseIDs,
+ KnowledgeIDs: rc.knowledgeIDs,
+ ImageURLs: imageURLs,
+ ImageDescription: imageDescription,
+ UserMessageID: rc.userMessageID,
+ WebSearchEnabled: rc.webSearchEnabled,
+ EnableMemory: rc.enableMemory,
+ }
+}
+
// parseQARequest parses and validates a QA request, returns the request context
func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestContext, *CreateKnowledgeQARequest, error) {
ctx := logger.CloneContext(c.Request.Context())
@@ -77,75 +96,10 @@ func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestCo
}
// Get custom agent if agent_id is provided. Backend resolves shared agent from share relation (no client-provided tenant).
- var customAgent *types.CustomAgent
- var effectiveTenantID uint64
- if request.AgentID != "" {
- logger.Infof(ctx, "Resolving agent, agent ID: %s", secutils.SanitizeForLog(request.AgentID))
- userIDVal, _ := c.Get(types.UserIDContextKey.String())
- currentTenantID := c.GetUint64(types.TenantIDContextKey.String())
- if h.agentShareService != nil && userIDVal != nil && currentTenantID != 0 {
- userID, _ := userIDVal.(string)
- agent, err := h.agentShareService.GetSharedAgentForUser(ctx, userID, currentTenantID, request.AgentID)
- if err == nil && agent != nil {
- effectiveTenantID = agent.TenantID
- customAgent = agent
- logger.Infof(ctx, "Using shared agent: ID=%s, Name=%s, effectiveTenantID=%d (retrieval scope)",
- customAgent.ID, customAgent.Name, effectiveTenantID)
- }
- }
- if customAgent == nil {
- agent, err := h.customAgentService.GetAgentByID(ctx, request.AgentID)
- if err == nil {
- customAgent = agent
- logger.Infof(ctx, "Using own agent: ID=%s, Name=%s, AgentMode=%s",
- customAgent.ID, customAgent.Name, customAgent.Config.AgentMode)
- } else {
- logger.Warnf(ctx, "Failed to get custom agent, agent ID: %s, error: %v, using default config",
- secutils.SanitizeForLog(request.AgentID), err)
- }
- } else {
- logger.Infof(ctx, "Using custom agent: ID=%s, Name=%s, IsBuiltin=%v, AgentMode=%s, effectiveTenantID=%d",
- customAgent.ID, customAgent.Name, customAgent.IsBuiltin, customAgent.Config.AgentMode, effectiveTenantID)
- }
- }
+ customAgent, effectiveTenantID := h.resolveAgent(ctx, c, request.AgentID)
- // Merge @mentioned items into knowledge_base_ids and knowledge_ids so that
- // retrieval (quick-answer and agent mode) uses the same targets the user @mentioned.
- // This fixes the case where user only @mentions a (shared) KB in the input but
- // does not select it in the sidebar — without this merge, retrieval would not search those KBs.
- kbIDs := make([]string, 0, len(request.KnowledgeBaseIDs)+len(request.MentionedItems))
- kbIDSet := make(map[string]bool)
- for _, id := range request.KnowledgeBaseIDs {
- if id != "" && !kbIDSet[id] {
- kbIDs = append(kbIDs, id)
- kbIDSet[id] = true
- }
- }
- knowledgeIDs := make([]string, 0, len(request.KnowledgeIds)+len(request.MentionedItems))
- knowledgeIDSet := make(map[string]bool)
- for _, id := range request.KnowledgeIds {
- if id != "" && !knowledgeIDSet[id] {
- knowledgeIDs = append(knowledgeIDs, id)
- knowledgeIDSet[id] = true
- }
- }
- for _, item := range request.MentionedItems {
- if item.ID == "" {
- continue
- }
- switch item.Type {
- case "kb":
- if !kbIDSet[item.ID] {
- kbIDs = append(kbIDs, item.ID)
- kbIDSet[item.ID] = true
- }
- case "file":
- if !knowledgeIDSet[item.ID] {
- knowledgeIDs = append(knowledgeIDs, item.ID)
- knowledgeIDSet[item.ID] = true
- }
- }
- }
+ // Merge @mentioned items into knowledge_base_ids and knowledge_ids
+ kbIDs, knowledgeIDs := mergeKnowledgeTargets(request.KnowledgeBaseIDs, request.KnowledgeIds, request.MentionedItems)
// Log merge results for debugging
logger.Infof(ctx, "[%s] @mention merge: request.KnowledgeBaseIDs=%v, request.MentionedItems=%d, merged kbIDs=%v, merged knowledgeIDs=%v",
@@ -200,6 +154,90 @@ func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestCo
return reqCtx, &request, nil
}
+// resolveAgent resolves the custom agent by ID, trying shared agent first, then own agent.
+// Returns (nil, 0) if agentID is empty or not found.
+func (h *Handler) resolveAgent(ctx context.Context, c *gin.Context, agentID string) (*types.CustomAgent, uint64) {
+ if agentID == "" {
+ return nil, 0
+ }
+
+ logger.Infof(ctx, "Resolving agent, agent ID: %s", secutils.SanitizeForLog(agentID))
+
+ // Try shared agent first
+ var customAgent *types.CustomAgent
+ var effectiveTenantID uint64
+ userIDVal, _ := c.Get(types.UserIDContextKey.String())
+ currentTenantID := c.GetUint64(types.TenantIDContextKey.String())
+ if h.agentShareService != nil && userIDVal != nil && currentTenantID != 0 {
+ userID, _ := userIDVal.(string)
+ agent, err := h.agentShareService.GetSharedAgentForUser(ctx, userID, currentTenantID, agentID)
+ if err == nil && agent != nil {
+ effectiveTenantID = agent.TenantID
+ customAgent = agent
+ logger.Infof(ctx, "Using shared agent: ID=%s, Name=%s, effectiveTenantID=%d (retrieval scope)",
+ customAgent.ID, customAgent.Name, effectiveTenantID)
+ }
+ }
+
+ // Fall back to own agent
+ if customAgent == nil {
+ agent, err := h.customAgentService.GetAgentByID(ctx, agentID)
+ if err == nil {
+ customAgent = agent
+ logger.Infof(ctx, "Using own agent: ID=%s, Name=%s, AgentMode=%s",
+ customAgent.ID, customAgent.Name, customAgent.Config.AgentMode)
+ } else {
+ logger.Warnf(ctx, "Failed to get custom agent, agent ID: %s, error: %v, using default config",
+ secutils.SanitizeForLog(agentID), err)
+ }
+ } else {
+ logger.Infof(ctx, "Using custom agent: ID=%s, Name=%s, IsBuiltin=%v, AgentMode=%s, effectiveTenantID=%d",
+ customAgent.ID, customAgent.Name, customAgent.IsBuiltin, customAgent.Config.AgentMode, effectiveTenantID)
+ }
+
+ return customAgent, effectiveTenantID
+}
+
+// mergeKnowledgeTargets merges request KB/knowledge IDs with @mentioned items into deduplicated slices.
+func mergeKnowledgeTargets(requestKBIDs []string, requestKnowledgeIDs []string, mentionedItems []MentionedItemRequest) (kbIDs []string, knowledgeIDs []string) {
+ kbIDSet := make(map[string]bool)
+ kbIDs = make([]string, 0, len(requestKBIDs)+len(mentionedItems))
+ for _, id := range requestKBIDs {
+ if id != "" && !kbIDSet[id] {
+ kbIDs = append(kbIDs, id)
+ kbIDSet[id] = true
+ }
+ }
+
+ knowledgeIDSet := make(map[string]bool)
+ knowledgeIDs = make([]string, 0, len(requestKnowledgeIDs)+len(mentionedItems))
+ for _, id := range requestKnowledgeIDs {
+ if id != "" && !knowledgeIDSet[id] {
+ knowledgeIDs = append(knowledgeIDs, id)
+ knowledgeIDSet[id] = true
+ }
+ }
+
+ for _, item := range mentionedItems {
+ if item.ID == "" {
+ continue
+ }
+ switch item.Type {
+ case "kb":
+ if !kbIDSet[item.ID] {
+ kbIDs = append(kbIDs, item.ID)
+ kbIDSet[item.ID] = true
+ }
+ case "file":
+ if !knowledgeIDSet[item.ID] {
+ knowledgeIDs = append(knowledgeIDs, item.ID)
+ knowledgeIDSet[item.ID] = true
+ }
+ }
+ }
+ return kbIDs, knowledgeIDs
+}
+
// sseStreamContext holds the context for SSE streaming
type sseStreamContext struct {
eventBus *event.EventBus
@@ -355,7 +393,7 @@ func (h *Handler) KnowledgeQA(c *gin.Context) {
}
// Execute normal mode QA, generate title unless disabled
- h.executeNormalModeQA(reqCtx, !request.DisableTitle)
+ h.executeQA(reqCtx, qaModeNormal, !request.DisableTitle)
}
// AgentQA godoc
@@ -390,188 +428,42 @@ func (h *Handler) AgentQA(c *gin.Context) {
// Route to appropriate handler based on agent mode
if agentModeEnabled {
- h.executeAgentModeQA(reqCtx)
+ h.executeQA(reqCtx, qaModeAgent, true)
} else {
logger.Infof(reqCtx.ctx, "Agent mode disabled, delegating to normal mode for session: %s", reqCtx.sessionID)
- // Knowledge bases should be specified in request or from custom agent
- h.executeNormalModeQA(reqCtx, false)
+ h.executeQA(reqCtx, qaModeNormal, false)
}
}
-// executeNormalModeQA executes the normal (KnowledgeQA) mode
-func (h *Handler) executeNormalModeQA(reqCtx *qaRequestContext, generateTitle bool) {
+// qaMode determines which QA execution path to use.
+type qaMode int
+
+const (
+ qaModeNormal qaMode = iota // KnowledgeQA pipeline (RAG / pure chat)
+ qaModeAgent // Agent engine with tool calling
+)
+
+// executeQA is the unified execution flow for both KnowledgeQA and AgentQA modes.
+// It handles message creation, SSE setup, VLM analysis, service invocation, and error handling.
+func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle bool) {
ctx := reqCtx.ctx
sessionID := reqCtx.sessionID
- // Create user message
- 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 {
- reqCtx.c.Error(errors.NewInternalServerError(err.Error()))
- return
- }
-
- logger.Infof(ctx, "Using knowledge bases: %v", reqCtx.knowledgeBaseIDs)
-
- // Setup SSE stream
- streamCtx := h.setupSSEStream(reqCtx, generateTitle)
-
- // Setup completion handler for normal mode
- // Note: Thinking content is now embedded in answer stream with tags
- // by chat_completion_stream.go, so we don't need separate thinking event handling
- var completionHandled bool // Prevent duplicate completion handling
-
- streamCtx.eventBus.On(event.EventAgentFinalAnswer, func(ctx context.Context, evt event.Event) error {
- data, ok := evt.Data.(event.AgentFinalAnswerData)
- if !ok {
- return nil
- }
- streamCtx.assistantMessage.Content += data.Content
- if data.IsFallback {
- streamCtx.assistantMessage.IsFallback = true
- }
- if data.Done {
- // Prevent duplicate completion handling
- if completionHandled {
- return nil
- }
- completionHandled = true
-
- logger.Infof(streamCtx.asyncCtx, "Knowledge QA service completed for session: %s", sessionID)
- // Content already contains ... tags from chat_completion_stream.go
- // Use session's tenant for message update (asyncCtx may have effectiveTenantID when using shared agent)
- updateCtx := context.WithValue(streamCtx.asyncCtx, types.TenantIDContextKey, reqCtx.session.TenantID)
- h.completeAssistantMessage(updateCtx, streamCtx.assistantMessage, reqCtx.query)
- // Emit EventAgentComplete - this will trigger handleComplete which sends the SSE complete event
- // Note: Don't cancel context here, let the SSE handler close naturally after receiving the complete event
- streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
- Type: event.EventAgentComplete,
- SessionID: sessionID,
- Data: event.AgentCompleteData{FinalAnswer: streamCtx.assistantMessage.Content},
- })
- }
- return nil
- })
-
- // Execute KnowledgeQA asynchronously
- go func() {
- defer func() {
- if r := recover(); r != nil {
- buf := make([]byte, 10240)
- runtime.Stack(buf, true)
- logger.ErrorWithFields(streamCtx.asyncCtx,
- errors.NewInternalServerError(fmt.Sprintf("Knowledge QA service panicked: %v\n%s", r, string(buf))), nil)
- }
- }()
-
- // 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, imageDescription := extractImageURLsAndOCRText(reqCtx.images)
- err := h.sessionService.KnowledgeQA(
- streamCtx.asyncCtx,
- reqCtx.session,
- reqCtx.query,
- reqCtx.knowledgeBaseIDs,
- reqCtx.knowledgeIDs,
- reqCtx.assistantMessage.ID,
- reqCtx.summaryModelID,
- reqCtx.webSearchEnabled,
- streamCtx.eventBus,
- reqCtx.customAgent,
- reqCtx.enableMemory,
- imageURLs, imageDescription,
- reqCtx.userMessageID,
- )
- if err != nil {
- logger.ErrorWithFields(streamCtx.asyncCtx, err, nil)
- streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
- Type: event.EventError,
- SessionID: sessionID,
- Data: event.ErrorData{
- Error: err.Error(),
- Stage: "knowledge_qa_execution",
- SessionID: sessionID,
- },
- })
- }
- }()
-
- // Handle SSE events (blocking)
- shouldWaitForTitle := generateTitle && reqCtx.session.Title == ""
- h.handleAgentEventsForSSE(ctx, reqCtx.c, sessionID, reqCtx.assistantMessage.ID,
- reqCtx.requestID, streamCtx.eventBus, shouldWaitForTitle)
-}
-
-// executeAgentModeQA executes the agent mode
-func (h *Handler) executeAgentModeQA(reqCtx *qaRequestContext) {
- ctx := reqCtx.ctx
- sessionID := reqCtx.sessionID
-
- // Emit agent query event
- if err := event.Emit(ctx, event.Event{
- Type: event.EventAgentQuery,
- SessionID: sessionID,
- RequestID: reqCtx.requestID,
- Data: event.AgentQueryData{
+ // Agent mode: emit agent query event before message creation
+ if mode == qaModeAgent {
+ if err := event.Emit(ctx, event.Event{
+ Type: event.EventAgentQuery,
SessionID: sessionID,
- Query: reqCtx.query,
RequestID: reqCtx.requestID,
- },
- }); err != nil {
- logger.Errorf(ctx, "Failed to emit agent query event: %v", err)
- return
+ Data: event.AgentQueryData{
+ SessionID: sessionID,
+ Query: reqCtx.query,
+ RequestID: reqCtx.requestID,
+ },
+ }); err != nil {
+ logger.Errorf(ctx, "Failed to emit agent query event: %v", err)
+ return
+ }
}
// Create user message
@@ -590,79 +482,93 @@ func (h *Handler) executeAgentModeQA(reqCtx *qaRequestContext) {
}
reqCtx.assistantMessage = assistantMessagePtr
- logger.Infof(ctx, "Calling agent QA service, session ID: %s", sessionID)
+ if mode == qaModeNormal {
+ logger.Infof(ctx, "Using knowledge bases: %v", reqCtx.knowledgeBaseIDs)
+ } else {
+ logger.Infof(ctx, "Calling agent QA service, session ID: %s", sessionID)
+ }
- // Setup SSE stream (agent mode always generates title)
- streamCtx := h.setupSSEStream(reqCtx, true)
+ // Setup SSE stream
+ streamCtx := h.setupSSEStream(reqCtx, generateTitle)
- // Execute AgentQA asynchronously
+ // Normal mode: register completion handler on EventAgentFinalAnswer
+ // (Agent mode handles completion in the defer block instead)
+ if mode == qaModeNormal {
+ var completionHandled bool
+ streamCtx.eventBus.On(event.EventAgentFinalAnswer, func(ctx context.Context, evt event.Event) error {
+ data, ok := evt.Data.(event.AgentFinalAnswerData)
+ if !ok {
+ return nil
+ }
+ streamCtx.assistantMessage.Content += data.Content
+ if data.IsFallback {
+ streamCtx.assistantMessage.IsFallback = true
+ }
+ if data.Done {
+ if completionHandled {
+ return nil
+ }
+ completionHandled = true
+
+ logger.Infof(streamCtx.asyncCtx, "Knowledge QA service completed for session: %s", sessionID)
+ updateCtx := context.WithValue(streamCtx.asyncCtx, types.TenantIDContextKey, reqCtx.session.TenantID)
+ h.completeAssistantMessage(updateCtx, streamCtx.assistantMessage, reqCtx.query)
+ streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
+ Type: event.EventAgentComplete,
+ SessionID: sessionID,
+ Data: event.AgentCompleteData{FinalAnswer: streamCtx.assistantMessage.Content},
+ })
+ }
+ return nil
+ })
+ }
+
+ // Execute QA asynchronously
go func() {
defer func() {
if r := recover(); r != nil {
- buf := make([]byte, 1024)
+ buf := make([]byte, 10240)
runtime.Stack(buf, true)
+ stageName := "Knowledge QA"
+ if mode == qaModeAgent {
+ stageName = "Agent QA"
+ }
logger.ErrorWithFields(streamCtx.asyncCtx,
- errors.NewInternalServerError(fmt.Sprintf("Agent QA service panicked: %v\n%s", r, string(buf))),
+ errors.NewInternalServerError(fmt.Sprintf("%s service panicked: %v\n%s", stageName, r, string(buf))),
map[string]interface{}{"session_id": sessionID})
}
- // Use session's tenant for message update (session belongs to session.TenantID; asyncCtx may have effectiveTenantID when using shared agent)
- updateCtx := context.WithValue(streamCtx.asyncCtx, types.TenantIDContextKey, reqCtx.session.TenantID)
- h.completeAssistantMessage(updateCtx, streamCtx.assistantMessage, reqCtx.query)
- logger.Infof(streamCtx.asyncCtx, "Agent QA service completed for session: %s", sessionID)
+ // Agent mode: complete the assistant message in defer (normal mode does it via event handler)
+ if mode == qaModeAgent {
+ updateCtx := context.WithValue(streamCtx.asyncCtx, types.TenantIDContextKey, reqCtx.session.TenantID)
+ h.completeAssistantMessage(updateCtx, streamCtx.assistantMessage, reqCtx.query)
+ logger.Infof(streamCtx.asyncCtx, "Agent QA service completed for session: %s", sessionID)
+ }
}()
- // Run VLM analysis inside the async flow so SSE stream is already up
- // and the user can see progress. Emit tool_call/tool_result events.
- if 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",
- Iteration: 0,
- },
- })
- 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(),
- Iteration: 0,
- },
- })
+ // Run VLM image analysis if applicable
+ h.runVLMAnalysisIfNeeded(streamCtx, reqCtx, mode)
+
+ // Build QA request and invoke the appropriate service
+ qaReq := reqCtx.buildQARequest()
+
+ var serviceErr error
+ var stageName string
+ if mode == qaModeNormal {
+ stageName = "knowledge_qa_execution"
+ serviceErr = h.sessionService.KnowledgeQA(streamCtx.asyncCtx, qaReq, streamCtx.eventBus)
+ } else {
+ stageName = "agent_execution"
+ serviceErr = h.sessionService.AgentQA(streamCtx.asyncCtx, qaReq, streamCtx.eventBus)
}
- imageURLs, imageDescription := extractImageURLsAndOCRText(reqCtx.images)
- err := h.sessionService.AgentQA(
- streamCtx.asyncCtx,
- reqCtx.session,
- reqCtx.query,
- reqCtx.assistantMessage.ID,
- reqCtx.summaryModelID,
- streamCtx.eventBus,
- reqCtx.customAgent,
- reqCtx.knowledgeBaseIDs,
- reqCtx.knowledgeIDs,
- imageURLs, imageDescription,
- reqCtx.userMessageID,
- )
- if err != nil {
- logger.ErrorWithFields(streamCtx.asyncCtx, err, nil)
+ if serviceErr != nil {
+ logger.ErrorWithFields(streamCtx.asyncCtx, serviceErr, nil)
streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
Type: event.EventError,
SessionID: sessionID,
Data: event.ErrorData{
- Error: err.Error(),
- Stage: "agent_execution",
+ Error: serviceErr.Error(),
+ Stage: stageName,
SessionID: sessionID,
},
})
@@ -670,8 +576,78 @@ func (h *Handler) executeAgentModeQA(reqCtx *qaRequestContext) {
}()
// Handle SSE events (blocking)
+ shouldWaitForTitle := generateTitle && reqCtx.session.Title == ""
h.handleAgentEventsForSSE(ctx, reqCtx.c, sessionID, reqCtx.assistantMessage.ID,
- reqCtx.requestID, streamCtx.eventBus, reqCtx.session.Title == "")
+ reqCtx.requestID, streamCtx.eventBus, shouldWaitForTitle)
+}
+
+// runVLMAnalysisIfNeeded runs VLM image analysis within the async goroutine,
+// emitting tool_call/tool_result events so the user can see progress.
+// For normal mode, VLM only runs on the pure-chat path (no KB, no web search);
+// RAG paths defer VLM to the pipeline rewrite step.
+// For agent mode, VLM always runs when images and a VLM model are present.
+func (h *Handler) runVLMAnalysisIfNeeded(streamCtx *sseStreamContext, reqCtx *qaRequestContext, mode qaMode) {
+ if len(reqCtx.images) == 0 || reqCtx.customAgent == nil || reqCtx.customAgent.Config.VLMModelID == "" {
+ return
+ }
+
+ sessionID := reqCtx.sessionID
+
+ // In normal mode, only run VLM for pure-chat path
+ if mode == qaModeNormal {
+ hasRequestKBs := len(reqCtx.knowledgeBaseIDs) > 0 || len(reqCtx.knowledgeIDs) > 0
+ agentWillResolveKBs := false
+ if !hasRequestKBs && reqCtx.customAgent != nil && !reqCtx.customAgent.Config.RetrieveKBOnlyWhenMentioned {
+ switch reqCtx.customAgent.Config.KBSelectionMode {
+ case "all":
+ agentWillResolveKBs = true
+ case "selected", "":
+ agentWillResolveKBs = len(reqCtx.customAgent.Config.KnowledgeBases) > 0
+ case "none":
+ agentWillResolveKBs = false
+ default:
+ agentWillResolveKBs = len(reqCtx.customAgent.Config.KnowledgeBases) > 0
+ }
+ }
+ if hasRequestKBs || agentWillResolveKBs || reqCtx.webSearchEnabled {
+ return // VLM will be handled by the pipeline rewrite step
+ }
+ }
+
+ // Emit VLM tool call/result events
+ toolCallID := uuid.New().String()
+ iteration := 0 // agent mode uses iteration field
+
+ streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
+ Type: event.EventAgentToolCall,
+ SessionID: sessionID,
+ Data: event.AgentToolCallData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ Iteration: iteration,
+ },
+ })
+
+ vlmStart := time.Now()
+ h.analyzeImageAttachments(streamCtx.asyncCtx, reqCtx.images,
+ reqCtx.customAgent.Config.VLMModelID, reqCtx.query)
+
+ outputMsg := "已分析图片内容"
+ if mode == qaModeAgent {
+ outputMsg = "已查看图片内容"
+ }
+ streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
+ Type: event.EventAgentToolResult,
+ SessionID: sessionID,
+ Data: event.AgentToolResultData{
+ ToolCallID: toolCallID,
+ ToolName: "image_analysis",
+ Output: outputMsg,
+ Success: true,
+ Duration: time.Since(vlmStart).Milliseconds(),
+ Iteration: iteration,
+ },
+ })
}
// completeAssistantMessage marks an assistant message as complete, updates it,
@@ -686,4 +662,3 @@ func (h *Handler) completeAssistantMessage(ctx context.Context, assistantMessage
bgCtx := context.WithoutCancel(ctx)
go h.messageService.IndexMessageToKB(bgCtx, userQuery, assistantMessage.Content, assistantMessage.ID, assistantMessage.SessionID)
}
-
diff --git a/internal/im/adapter.go b/internal/im/adapter.go
new file mode 100644
index 00000000..d23fd89d
--- /dev/null
+++ b/internal/im/adapter.go
@@ -0,0 +1,91 @@
+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
+}
+
+// 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
new file mode 100644
index 00000000..7b1ba5ed
--- /dev/null
+++ b/internal/im/feishu/adapter.go
@@ -0,0 +1,750 @@
+// 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"
+)
+
+// 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.
+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
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// 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) {
+ 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..ff521c2d
--- /dev/null
+++ b/internal/im/service.go
@@ -0,0 +1,798 @@
+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
+ // 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
+)
+
+// channelState holds runtime state for a running IM channel.
+type channelState struct {
+ Channel *IMChannel
+ Adapter Adapter
+ Cancel context.CancelFunc // for stopping websocket goroutines
+}
+
+// AdapterFactory creates an Adapter from an IMChannel configuration.
+// The second return value is an optional cleanup function (e.g., for stopping websocket connections).
+type AdapterFactory func(ctx context.Context, channel *IMChannel, msgHandler func(ctx context.Context, msg *IncomingMessage) error) (Adapter, context.CancelFunc, error)
+
+// 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
+
+ // channels maps channel ID -> running channel state
+ channels map[string]*channelState
+ mu sync.RWMutex
+
+ // adapterFactories maps platform name -> factory function
+ adapterFactories map[string]AdapterFactory
+
+ // processedMsgs tracks recently processed message IDs to prevent duplicate handling.
+ processedMsgs sync.Map
+
+ stopCh chan struct{}
+}
+
+func buildIMQARequest(
+ session *types.Session,
+ query string,
+ assistantMessageID string,
+ userMessageID string,
+ customAgent *types.CustomAgent,
+ kbIDs []string,
+) *types.QARequest {
+ return &types.QARequest{
+ Session: session,
+ Query: query,
+ AssistantMessageID: assistantMessageID,
+ CustomAgent: customAgent,
+ KnowledgeBaseIDs: kbIDs,
+ UserMessageID: userMessageID,
+ }
+}
+
+// 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,
+ channels: make(map[string]*channelState),
+ adapterFactories: make(map[string]AdapterFactory),
+ stopCh: make(chan struct{}),
+ }
+
+ // Start periodic dedup cleanup instead of per-message goroutines
+ go s.dedupCleanupLoop()
+
+ return s
+}
+
+// RegisterAdapterFactory registers a factory for creating adapters for a given platform.
+func (s *Service) RegisterAdapterFactory(platform string, factory AdapterFactory) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.adapterFactories[platform] = factory
+}
+
+// Stop gracefully shuts down the service, stopping all channels and background goroutines.
+func (s *Service) Stop() {
+ close(s.stopCh)
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ for id, cs := range s.channels {
+ if cs.Cancel != nil {
+ cs.Cancel()
+ }
+ delete(s.channels, id)
+ }
+}
+
+// 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
+ }
+ }
+}
+
+// LoadAndStartChannels loads all enabled channels from the database and starts them.
+func (s *Service) LoadAndStartChannels() error {
+ ctx := context.Background()
+ var channels []IMChannel
+ if err := s.db.Where("enabled = ? AND deleted_at IS NULL", true).Find(&channels).Error; err != nil {
+ return fmt.Errorf("load im channels: %w", err)
+ }
+
+ for i := range channels {
+ ch := channels[i]
+ if err := s.StartChannel(&ch); err != nil {
+ logger.Warnf(ctx, "[IM] Failed to start channel %s (%s/%s): %v", ch.ID, ch.Platform, ch.Name, err)
+ } else {
+ logger.Infof(ctx, "[IM] Started channel: id=%s platform=%s name=%s mode=%s agent=%s",
+ ch.ID, ch.Platform, ch.Name, ch.Mode, ch.AgentID)
+ }
+ }
+
+ logger.Infof(ctx, "[IM] Loaded %d enabled channels", len(channels))
+ return nil
+}
+
+// StartChannel creates and registers an adapter for the given channel.
+func (s *Service) StartChannel(channel *IMChannel) error {
+ s.mu.Lock()
+ factory, ok := s.adapterFactories[channel.Platform]
+ if !ok {
+ s.mu.Unlock()
+ return fmt.Errorf("no adapter factory for platform: %s", channel.Platform)
+ }
+ // Stop existing channel if running
+ if existing, ok := s.channels[channel.ID]; ok {
+ if existing.Cancel != nil {
+ existing.Cancel()
+ }
+ delete(s.channels, channel.ID)
+ }
+ s.mu.Unlock()
+
+ // Build the message handler that delegates to HandleMessage with this channel's config
+ msgHandler := func(msgCtx context.Context, msg *IncomingMessage) error {
+ return s.HandleMessage(msgCtx, msg, channel.ID)
+ }
+
+ ctx := context.Background()
+ adapter, cancelFn, err := factory(ctx, channel, msgHandler)
+ if err != nil {
+ return fmt.Errorf("create adapter: %w", err)
+ }
+
+ s.mu.Lock()
+ s.channels[channel.ID] = &channelState{
+ Channel: channel,
+ Adapter: adapter,
+ Cancel: cancelFn,
+ }
+ s.mu.Unlock()
+
+ return nil
+}
+
+// StopChannel stops and removes a running channel.
+func (s *Service) StopChannel(channelID string) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if cs, ok := s.channels[channelID]; ok {
+ if cs.Cancel != nil {
+ cs.Cancel()
+ }
+ delete(s.channels, channelID)
+ logger.Infof(context.Background(), "[IM] Stopped channel: id=%s", channelID)
+ }
+}
+
+// GetChannelAdapter returns the adapter and channel config for a given channel ID.
+func (s *Service) GetChannelAdapter(channelID string) (Adapter, *IMChannel, bool) {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ cs, ok := s.channels[channelID]
+ if !ok {
+ return nil, nil, false
+ }
+ return cs.Adapter, cs.Channel, true
+}
+
+// GetChannelByID loads a channel from the database.
+func (s *Service) GetChannelByID(channelID string) (*IMChannel, error) {
+ var ch IMChannel
+ if err := s.db.Where("id = ? AND deleted_at IS NULL", channelID).First(&ch).Error; err != nil {
+ return nil, err
+ }
+ return &ch, nil
+}
+
+// HandleMessage processes an incoming IM message end-to-end using channel config.
+func (s *Service) HandleMessage(ctx context.Context, msg *IncomingMessage, channelID 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])
+ }
+
+ // Get channel config
+ adapter, channel, ok := s.GetChannelAdapter(channelID)
+ if !ok {
+ // Try loading from DB (channel might have been created after service start)
+ ch, err := s.GetChannelByID(channelID)
+ if err != nil {
+ return fmt.Errorf("channel not found: %s", channelID)
+ }
+ // Start it dynamically
+ if err := s.StartChannel(ch); err != nil {
+ return fmt.Errorf("start channel %s: %w", channelID, err)
+ }
+ adapter, channel, ok = s.GetChannelAdapter(channelID)
+ if !ok {
+ return fmt.Errorf("channel adapter not available after start: %s", channelID)
+ }
+ }
+
+ tenantID := channel.TenantID
+ agentID := channel.AgentID
+
+ logger.Infof(ctx, "[IM] HandleMessage: channel=%s platform=%s user=%s chat=%s content_len=%d",
+ channelID, msg.Platform, msg.UserID, msg.ChatID, len(msg.Content))
+
+ // 1. Get tenant
+ 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, channelID)
+ 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. Resolve knowledge base IDs from agent config
+ var kbIDs []string
+ if customAgent != nil {
+ kbIDs = customAgent.Config.KnowledgeBases
+ }
+
+ // 6. If the adapter supports streaming and output_mode is not "full", use streaming
+ streamDisabled := channel.OutputMode == "full"
+ if !streamDisabled {
+ if streamer, ok := adapter.(StreamSender); ok {
+ return s.handleMessageStream(sessionCtx, msg, session, customAgent, kbIDs, streamer, adapter)
+ }
+ }
+
+ // 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 = "抱歉,处理您的问题时出现了异常,请稍后再试。"
+ }
+
+ 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: channel=%s platform=%s user=%s answer_len=%d",
+ channelID, 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, imChannelID 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,
+ IMChannelID: imChannelID,
+ }
+ 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
+}
+
+// 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, adapter Adapter) 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, adapter)
+ }
+
+ // 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
+ userMsg, err := s.messageService.CreateMessage(qaCtx, &types.Message{
+ SessionID: session.ID, Role: "user", Content: msg.Content,
+ RequestID: requestID, CreatedAt: time.Now(), IsCompleted: true,
+ })
+ if 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
+ req := buildIMQARequest(session, msg.Content, assistantMsg.ID, userMsg.ID, customAgent, kbIDs)
+ if useAgent {
+ err = s.sessionService.AgentQA(qaCtx, req, eventBus)
+ } else {
+ err = s.sessionService.KnowledgeQA(qaCtx, req, eventBus)
+ }
+ 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, adapter Adapter) error {
+ answer, err := s.runQA(ctx, session, msg.Content, customAgent, kbIDs)
+ if err != nil {
+ logger.Errorf(ctx, "[IM] QA fallback failed: %v", err)
+ answer = "抱歉,处理您的问题时出现了异常,请稍后再试。"
+ }
+
+ 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
+ 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)
+ }
+
+ // 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
+ req := buildIMQARequest(session, query, assistantMsg.ID, userMsg.ID, customAgent, kbIDs)
+ if useAgent {
+ err = s.sessionService.AgentQA(ctx, req, eventBus)
+ } else {
+ err = s.sessionService.KnowledgeQA(ctx, req, eventBus)
+ }
+ 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
+}
+
+// ── CRUD operations for IM channels ──
+
+// ListChannelsByAgent returns all channels for a given agent.
+func (s *Service) ListChannelsByAgent(agentID string) ([]IMChannel, error) {
+ var channels []IMChannel
+ if err := s.db.Where("agent_id = ? AND deleted_at IS NULL", agentID).
+ Order("created_at DESC").Find(&channels).Error; err != nil {
+ return nil, err
+ }
+ return channels, nil
+}
+
+// CreateChannel creates a new IM channel and optionally starts it.
+func (s *Service) CreateChannel(channel *IMChannel) error {
+ if err := s.db.Create(channel).Error; err != nil {
+ return err
+ }
+ if channel.Enabled {
+ if err := s.StartChannel(channel); err != nil {
+ logger.Warnf(context.Background(), "[IM] Created channel %s but failed to start: %v", channel.ID, err)
+ }
+ }
+ return nil
+}
+
+// UpdateChannel updates a channel and restarts it if needed.
+func (s *Service) UpdateChannel(channel *IMChannel) error {
+ if err := s.db.Save(channel).Error; err != nil {
+ return err
+ }
+ // Restart channel: stop old, start new if enabled
+ s.StopChannel(channel.ID)
+ if channel.Enabled {
+ if err := s.StartChannel(channel); err != nil {
+ logger.Warnf(context.Background(), "[IM] Updated channel %s but failed to restart: %v", channel.ID, err)
+ }
+ }
+ return nil
+}
+
+// DeleteChannel soft-deletes a channel and stops it.
+func (s *Service) DeleteChannel(channelID string) error {
+ s.StopChannel(channelID)
+ return s.db.Where("id = ?", channelID).Delete(&IMChannel{}).Error
+}
+
+// ToggleChannel enables or disables a channel.
+func (s *Service) ToggleChannel(channelID string) (*IMChannel, error) {
+ var ch IMChannel
+ if err := s.db.Where("id = ? AND deleted_at IS NULL", channelID).First(&ch).Error; err != nil {
+ return nil, err
+ }
+ ch.Enabled = !ch.Enabled
+ if err := s.db.Save(&ch).Error; err != nil {
+ return nil, err
+ }
+ if ch.Enabled {
+ if err := s.StartChannel(&ch); err != nil {
+ logger.Warnf(context.Background(), "[IM] Failed to start channel %s after enable: %v", ch.ID, err)
+ }
+ } else {
+ s.StopChannel(channelID)
+ }
+ return &ch, nil
+}
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/types.go b/internal/im/types.go
new file mode 100644
index 00000000..4a6804da
--- /dev/null
+++ b/internal/im/types.go
@@ -0,0 +1,75 @@
+package im
+
+import (
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/google/uuid"
+ "gorm.io/gorm"
+)
+
+// IMChannel represents an IM channel configuration stored in the database.
+// Each channel binds to an agent and contains platform-specific credentials.
+type IMChannel struct {
+ ID string `json:"id" gorm:"type:varchar(36);primaryKey;default:uuid_generate_v4()"`
+ TenantID uint64 `json:"tenant_id" gorm:"not null;index:idx_im_channels_tenant"`
+ AgentID string `json:"agent_id" gorm:"type:varchar(36);not null;index:idx_im_channels_agent"`
+ Platform string `json:"platform" gorm:"type:varchar(20);not null"`
+ Name string `json:"name" gorm:"type:varchar(255);not null;default:''"`
+ Enabled bool `json:"enabled" gorm:"not null;default:true"`
+ Mode string `json:"mode" gorm:"type:varchar(20);not null;default:'websocket'"`
+ OutputMode string `json:"output_mode" gorm:"type:varchar(20);not null;default:'stream'"`
+ Credentials types.JSON `json:"credentials" gorm:"type:jsonb;not null;default:'{}'"`
+ CreatedAt time.Time `json:"created_at"`
+ UpdatedAt time.Time `json:"updated_at"`
+ DeletedAt gorm.DeletedAt `json:"deleted_at" gorm:"index"`
+}
+
+func (IMChannel) TableName() string {
+ return "im_channels"
+}
+
+func (ch *IMChannel) BeforeCreate(tx *gorm.DB) error {
+ if ch.ID == "" {
+ ch.ID = uuid.New().String()
+ }
+ if ch.Mode == "" {
+ ch.Mode = "websocket"
+ }
+ if ch.OutputMode == "" {
+ ch.OutputMode = "stream"
+ }
+ return nil
+}
+
+// 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:''"`
+ IMChannelID string `json:"im_channel_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/longconn.go b/internal/im/wecom/longconn.go
new file mode 100644
index 00000000..b7bd35a9
--- /dev/null
+++ b/internal/im/wecom/longconn.go
@@ -0,0 +1,439 @@
+// 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
+
+ // 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.
+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)
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// 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 {
+ 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/im/wecom/webhook_adapter.go b/internal/im/wecom/webhook_adapter.go
new file mode 100644
index 00000000..e0f4aaf1
--- /dev/null
+++ b/internal/im/wecom/webhook_adapter.go
@@ -0,0 +1,370 @@
+// 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}
+
+// 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
+ aesKey []byte
+ agentSecret string
+ corpAgentID int
+
+ // Token cache
+ tokenMu sync.Mutex
+ tokenCache string
+ tokenExpAt time.Time
+}
+
+// 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 &WebhookAdapter{
+ corpID: corpID,
+ token: token,
+ encodingAESKey: encodingAESKey,
+ aesKey: aesKey,
+ agentSecret: agentSecret,
+ corpAgentID: corpAgentID,
+ }, nil
+}
+
+// Platform returns the platform identifier.
+func (a *WebhookAdapter) Platform() im.Platform {
+ return im.PlatformWeCom
+}
+
+// VerifyCallback verifies the WeCom callback signature.
+func (a *WebhookAdapter) 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 *WebhookAdapter) 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 *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)
+ }
+
+ 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 *WebhookAdapter) 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 *WebhookAdapter) 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 *WebhookAdapter) 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 *WebhookAdapter) 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/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)
+}
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/chat/chat.go b/internal/models/chat/chat.go
index afd10ba5..a4c9f173 100644
--- a/internal/models/chat/chat.go
+++ b/internal/models/chat/chat.go
@@ -122,6 +122,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 571f3cb6..62f245b9 100644
--- a/internal/models/chat/remote_api.go
+++ b/internal/models/chat/remote_api.go
@@ -29,6 +29,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 聊天实例
@@ -59,6 +63,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))
@@ -194,15 +203,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)
@@ -222,15 +239,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, secutils.CompactImageDataURLForLog(string(jsonData)))
-
- endpoint := c.baseURL + "/chat/completions"
+ logger.Infof(ctx, "[LLM Request] model=%s, raw HTTP request:\n%s", c.modelName, string(jsonData))
+ 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)
@@ -328,14 +346,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)
@@ -360,7 +386,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)
@@ -368,7 +394,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/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/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
diff --git a/internal/models/provider/nvidia.go b/internal/models/provider/nvidia.go
new file mode 100644
index 00000000..3f958eff
--- /dev/null
+++ b/internal/models/provider/nvidia.go
@@ -0,0 +1,56 @@
+package provider
+
+import (
+ "fmt"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+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"
+)
+
+// 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: NvidiaVLMBaseURL,
+ },
+ 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/router/router.go b/internal/router/router.go
index 44e5ca89..6d2f9e47 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))
@@ -134,6 +138,7 @@ func NewRouter(params RouterParams) *gin.Engine {
RegisterCustomAgentRoutes(v1, params.CustomAgentHandler)
RegisterSkillRoutes(v1, params.SkillHandler)
RegisterOrganizationRoutes(v1, params.OrganizationHandler)
+ RegisterIMChannelRoutes(v1, params.IMHandler)
}
return r
@@ -577,6 +582,34 @@ 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")
+ {
+ im.GET("/callback/:channel_id", imHandler.IMCallback)
+ im.POST("/callback/:channel_id", imHandler.IMCallback)
+ }
+}
+
+// RegisterIMChannelRoutes registers IM channel CRUD routes (requires authentication).
+func RegisterIMChannelRoutes(r *gin.RouterGroup, imHandler *handler.IMHandler) {
+ // Channel CRUD under agents
+ agentChannels := r.Group("/agents/:id/im-channels")
+ {
+ agentChannels.POST("", imHandler.CreateIMChannel)
+ agentChannels.GET("", imHandler.ListIMChannels)
+ }
+
+ // Channel operations by channel ID
+ channels := r.Group("/im-channels")
+ {
+ channels.PUT("/:id", imHandler.UpdateIMChannel)
+ channels.DELETE("/:id", imHandler.DeleteIMChannel)
+ channels.POST("/:id/toggle", imHandler.ToggleIMChannel)
+ }
+}
+
// 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/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
diff --git a/internal/types/interfaces/session.go b/internal/types/interfaces/session.go
index 776b93b6..1a2bf10a 100644
--- a/internal/types/interfaces/session.go
+++ b/internal/types/interfaces/session.go
@@ -32,42 +32,17 @@ type SessionService interface {
// It emits an event when the title is generated
// modelID: optional model ID to use for title generation (if empty, uses first available KnowledgeQA model)
GenerateTitleAsync(ctx context.Context, session *types.Session, userQuery string, modelID string, eventBus *event.EventBus)
- // KnowledgeQA performs knowledge-based question answering
- // knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB)
- // knowledgeIDs: list of specific knowledge (file) IDs to search
- // summaryModelID: optional summary model ID override (if empty, uses session/KB default)
- // webSearchEnabled: whether to enable web search to supplement knowledge base results
- // customAgent: optional custom agent for config override (multiTurnEnabled, historyTurns)
- // enableMemory: whether to enable memory feature for this request
- // Events are emitted through eventBus (references, answer chunks, completion)
- KnowledgeQA(ctx context.Context,
- 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, imageDescription string, userMessageID string,
- ) error
+ // KnowledgeQA performs knowledge-based question answering.
+ // Events are emitted through eventBus (references, answer chunks, completion).
+ KnowledgeQA(ctx context.Context, req *types.QARequest, eventBus *event.EventBus) error
// KnowledgeQAByEvent performs knowledge-based question answering by event
KnowledgeQAByEvent(ctx context.Context, chatManage *types.ChatManage, eventList []types.EventType) error
// SearchKnowledge performs knowledge-based search, without summarization
// knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB)
// knowledgeIDs: list of specific knowledge (file) IDs to search
SearchKnowledge(ctx context.Context, knowledgeBaseIDs []string, knowledgeIDs []string, query string) ([]*types.SearchResult, error)
- // AgentQA performs agent-based question answering with conversation history and streaming support
- // eventBus is optional - if nil, uses service's default EventBus
- // customAgent is optional - if provided, uses custom agent configuration instead of tenant defaults
- // summaryModelID is optional - if provided, overrides the model from customAgent config
- AgentQA(
- ctx context.Context,
- session *types.Session,
- query string,
- assistantMessageID string,
- summaryModelID string,
- eventBus *event.EventBus,
- customAgent *types.CustomAgent,
- knowledgeBaseIDs []string,
- knowledgeIDs []string,
- imageURLs []string, imageDescription string, userMessageID string,
- ) error
+ // AgentQA performs agent-based question answering with conversation history and streaming support.
+ AgentQA(ctx context.Context, req *types.QARequest, eventBus *event.EventBus) error
// ClearContext clears the LLM context for a session
ClearContext(ctx context.Context, sessionID string) error
}
diff --git a/internal/types/qa_request.go b/internal/types/qa_request.go
new file mode 100644
index 00000000..56cab9ac
--- /dev/null
+++ b/internal/types/qa_request.go
@@ -0,0 +1,19 @@
+package types
+
+// QARequest consolidates all parameters for KnowledgeQA and AgentQA service calls,
+// replacing the previous 14-parameter method signatures.
+// EventBus is passed separately to avoid circular dependency with the event package.
+type QARequest struct {
+ Session *Session // The conversation session
+ Query string // User query text
+ AssistantMessageID string // Pre-created assistant message ID
+ SummaryModelID string // Optional model override; empty = use agent/KB default
+ CustomAgent *CustomAgent // Optional custom agent for config override
+ KnowledgeBaseIDs []string // Knowledge base IDs to search (from request + @mentions)
+ KnowledgeIDs []string // Specific knowledge (file) IDs to search
+ ImageURLs []string // Image URLs for multimodal input
+ ImageDescription string // VLM-generated image description (fallback for non-vision models)
+ UserMessageID string // Created user message ID
+ WebSearchEnabled bool // Whether web search is enabled for this request
+ EnableMemory bool // Whether memory feature is enabled
+}
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"`
}
diff --git a/migrations/versioned/000021_im_channel.down.sql b/migrations/versioned/000021_im_channel.down.sql
new file mode 100644
index 00000000..1f328874
--- /dev/null
+++ b/migrations/versioned/000021_im_channel.down.sql
@@ -0,0 +1,3 @@
+ALTER TABLE im_channel_sessions DROP COLUMN IF EXISTS im_channel_id;
+DROP TABLE IF EXISTS im_channels;
+DROP TABLE IF EXISTS im_channel_sessions;
diff --git a/migrations/versioned/000021_im_channel.up.sql b/migrations/versioned/000021_im_channel.up.sql
new file mode 100644
index 00000000..66048012
--- /dev/null
+++ b/migrations/versioned/000021_im_channel.up.sql
@@ -0,0 +1,77 @@
+-- Migration: 000021_im_channel_sessions
+-- Description: Create IM channel session mapping and IM channel configuration tables
+DO $$ BEGIN RAISE NOTICE '[Migration 000021] Creating IM channel integration tables'; 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] Creating table: im_channels'; END $$;
+
+CREATE TABLE IF NOT EXISTS im_channels (
+ id VARCHAR(36) PRIMARY KEY DEFAULT uuid_generate_v4(),
+ tenant_id BIGINT NOT NULL,
+ agent_id VARCHAR(36) NOT NULL,
+ platform VARCHAR(20) NOT NULL,
+ name VARCHAR(255) NOT NULL DEFAULT '',
+ enabled BOOLEAN NOT NULL DEFAULT true,
+ mode VARCHAR(20) NOT NULL DEFAULT 'websocket',
+ output_mode VARCHAR(20) NOT NULL DEFAULT 'stream',
+ credentials JSONB NOT NULL 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
+);
+
+CREATE INDEX IF NOT EXISTS idx_im_channels_tenant ON im_channels (tenant_id);
+CREATE INDEX IF NOT EXISTS idx_im_channels_agent ON im_channels (agent_id);
+CREATE INDEX IF NOT EXISTS idx_im_channels_deleted ON im_channels (deleted_at) WHERE deleted_at IS NOT NULL;
+
+COMMENT ON TABLE im_channels IS 'IM platform channel configurations bound to agents';
+COMMENT ON COLUMN im_channels.agent_id IS 'Agent ID this channel is bound to';
+COMMENT ON COLUMN im_channels.platform IS 'IM platform: wecom, feishu';
+COMMENT ON COLUMN im_channels.name IS 'User-defined channel name for identification';
+COMMENT ON COLUMN im_channels.mode IS 'Connection mode: webhook or websocket';
+COMMENT ON COLUMN im_channels.output_mode IS 'Output mode: stream (real-time) or full (wait for complete answer)';
+COMMENT ON COLUMN im_channels.credentials IS 'Platform credentials (JSONB): WeCom webhook={corp_id,agent_secret,token,encoding_aes_key,corp_agent_id}, WeCom ws={bot_id,bot_secret}, Feishu={app_id,app_secret,verification_token,encrypt_key}';
+
+-- Add im_channel_id column to im_channel_sessions for linking
+ALTER TABLE im_channel_sessions ADD COLUMN IF NOT EXISTS im_channel_id VARCHAR(36) DEFAULT '';
+CREATE INDEX IF NOT EXISTS idx_im_channel_sessions_channel ON im_channel_sessions (im_channel_id) WHERE im_channel_id != '';
+
+DO $$ BEGIN RAISE NOTICE '[Migration 000021] IM channel integration setup completed successfully!'; END $$;
diff --git a/migrations/versioned/000022_message_images.down.sql b/migrations/versioned/000022_message_images.down.sql
new file mode 100644
index 00000000..e5c83b13
--- /dev/null
+++ b/migrations/versioned/000022_message_images.down.sql
@@ -0,0 +1 @@
+ALTER TABLE messages DROP COLUMN IF EXISTS images;
diff --git a/migrations/versioned/000022_message_images.up.sql b/migrations/versioned/000022_message_images.up.sql
new file mode 100644
index 00000000..89e191a3
--- /dev/null
+++ b/migrations/versioned/000022_message_images.up.sql
@@ -0,0 +1 @@
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS images JSONB DEFAULT '[]';