diff --git a/frontend/src/api/agent/index.ts b/frontend/src/api/agent/index.ts
index 04572426..70797386 100644
--- a/frontend/src/api/agent/index.ts
+++ b/frontend/src/api/agent/index.ts
@@ -25,6 +25,10 @@ export interface CustomAgentConfig {
// 知识库选择模式:all=全部知识库, selected=指定知识库, none=不使用知识库
kb_selection_mode?: 'all' | 'selected' | 'none';
knowledge_bases?: string[];
+ // 是否仅在显式 @ 提及时检索知识库(默认: false)
+ // true: 只有用户通过 @ 明确提及知识库/文档时才检索
+ // false: 根据 kb_selection_mode 自动检索知识库
+ retrieve_kb_only_when_mentioned?: boolean;
// ===== 文件类型限制 =====
// 支持的文件类型(如 ["csv", "xlsx", "xls"])
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index 55b5daa9..332cc58e 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -327,6 +327,8 @@ export default {
noKnowledgeBase: 'No Knowledge Base',
noKnowledgeBaseDesc: 'Pure model conversation, no knowledge retrieval',
selectKnowledgeBases: 'Select Knowledge Bases',
+ retrieveKBOnlyWhenMentioned: 'Retrieve Only When Mentioned',
+ retrieveKBOnlyWhenMentionedDesc: 'Off: auto-retrieve configured KBs; On: retrieve only when user @ mentions',
rerankModel: 'ReRank Model',
rerankModelDesc: 'Used to rerank knowledge base retrieval results for better accuracy',
rerankModelPlaceholder: 'Select ReRank Model',
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index b098eeb6..cfcc5eee 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -857,6 +857,8 @@ export default {
noKnowledgeBase: "不使用知识库",
noKnowledgeBaseDesc: "纯模型对话,不检索知识库",
selectKnowledgeBases: "选择知识库",
+ retrieveKBOnlyWhenMentioned: "仅在 @ 提及时检索",
+ retrieveKBOnlyWhenMentionedDesc: "关闭:自动检索已配置的知识库;开启:仅当用户 @ 提及时才检索",
rerankModel: "ReRank 模型",
rerankModelDesc: "用于对知识库检索结果进行重排序,提高回答准确性",
rerankModelPlaceholder: "请选择 ReRank 模型",
diff --git a/frontend/src/views/agent/AgentEditorModal.vue b/frontend/src/views/agent/AgentEditorModal.vue
index 37c4ce29..73876818 100644
--- a/frontend/src/views/agent/AgentEditorModal.vue
+++ b/frontend/src/views/agent/AgentEditorModal.vue
@@ -652,6 +652,17 @@
+
+
diff --git a/internal/application/service/session.go b/internal/application/service/session.go
index 3308f8a5..c5362638 100644
--- a/internal/application/service/session.go
+++ b/internal/application/service/session.go
@@ -418,10 +418,21 @@ func (s *sessionService) KnowledgeQA(
// 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 len(knowledgeBaseIDs) == 0 && len(knowledgeIDs) == 0 {
- knowledgeBaseIDs = s.resolveKnowledgeBasesFromAgent(ctx, customAgent)
- } else {
+ // 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)
}
// Determine chat model ID: prioritize request's summaryModelID, then Remote models
@@ -1106,20 +1117,25 @@ func (s *sessionService) AgentQA(
// 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,
+ 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,
}
// Resolve knowledge bases: request-level @ mentions take priority over agent config
- if len(knowledgeBaseIDs) > 0 || len(knowledgeIDs) > 0 {
+ // 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
@@ -1129,6 +1145,11 @@ func (s *sessionService) AgentQA(
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)
diff --git a/internal/types/agent.go b/internal/types/agent.go
index 459cf75e..03557bbe 100644
--- a/internal/types/agent.go
+++ b/internal/types/agent.go
@@ -31,6 +31,8 @@ type AgentConfig struct {
MCPServices []string `json:"mcp_services"` // Selected MCP service IDs (when mode is "selected")
// Whether to enable thinking mode (for models that support extended thinking)
Thinking *bool `json:"thinking"`
+ // Whether to retrieve knowledge base only when explicitly mentioned with @ (default: false)
+ RetrieveKBOnlyWhenMentioned bool `json:"retrieve_kb_only_when_mentioned"`
}
// SessionAgentConfig represents session-level agent configuration
diff --git a/internal/types/custom_agent.go b/internal/types/custom_agent.go
index 0d700a50..3785ddd2 100644
--- a/internal/types/custom_agent.go
+++ b/internal/types/custom_agent.go
@@ -99,6 +99,10 @@ type CustomAgentConfig struct {
KBSelectionMode string `yaml:"kb_selection_mode" json:"kb_selection_mode"`
// Associated knowledge base IDs (only used when KBSelectionMode is "selected")
KnowledgeBases []string `yaml:"knowledge_bases" json:"knowledge_bases"`
+ // Whether to retrieve knowledge base only when explicitly mentioned with @ (default: false)
+ // When true, knowledge base retrieval only happens if user explicitly mentions KB/files with @
+ // When false, knowledge base retrieval happens according to KBSelectionMode
+ RetrieveKBOnlyWhenMentioned bool `yaml:"retrieve_kb_only_when_mentioned" json:"retrieve_kb_only_when_mentioned"`
// ===== File Type Restriction Settings =====
// Supported file types for this agent (e.g., ["csv", "xlsx", "xls"])
@@ -245,13 +249,14 @@ func GetBuiltinQuickAnswerAgent(tenantID uint64) *CustomAgent {
{{contexts}}
用户问题:{{query}}`,
- Temperature: 0.7,
- MaxCompletionTokens: 2048,
- WebSearchEnabled: true,
- WebSearchMaxResults: 5,
- MultiTurnEnabled: true,
- HistoryTurns: 5,
- KBSelectionMode: "all",
+ Temperature: 0.7,
+ MaxCompletionTokens: 2048,
+ WebSearchEnabled: true,
+ WebSearchMaxResults: 5,
+ MultiTurnEnabled: true,
+ HistoryTurns: 5,
+ KBSelectionMode: "all",
+ RetrieveKBOnlyWhenMentioned: false, // Default: retrieve KB based on KBSelectionMode
// FAQ strategy
FAQPriorityEnabled: true,
FAQDirectAnswerThreshold: 0.9,
@@ -279,18 +284,19 @@ func GetBuiltinSmartReasoningAgent(tenantID uint64) *CustomAgent {
IsBuiltin: true,
TenantID: tenantID,
Config: CustomAgentConfig{
- AgentMode: AgentModeSmartReasoning,
- SystemPrompt: "",
- Temperature: 0.7,
- MaxCompletionTokens: 2048,
- MaxIterations: 50,
- KBSelectionMode: "all",
- AllowedTools: []string{"thinking", "todo_write", "knowledge_search", "grep_chunks", "list_knowledge_chunks", "query_knowledge_graph", "get_document_info"},
- WebSearchEnabled: true,
- WebSearchMaxResults: 5,
- ReflectionEnabled: false,
- MultiTurnEnabled: true,
- HistoryTurns: 5,
+ AgentMode: AgentModeSmartReasoning,
+ SystemPrompt: "",
+ Temperature: 0.7,
+ MaxCompletionTokens: 2048,
+ MaxIterations: 50,
+ KBSelectionMode: "all",
+ RetrieveKBOnlyWhenMentioned: false, // Default: retrieve KB based on KBSelectionMode
+ AllowedTools: []string{"thinking", "todo_write", "knowledge_search", "grep_chunks", "list_knowledge_chunks", "query_knowledge_graph", "get_document_info"},
+ WebSearchEnabled: true,
+ WebSearchMaxResults: 5,
+ ReflectionEnabled: false,
+ MultiTurnEnabled: true,
+ HistoryTurns: 5,
// FAQ strategy
FAQPriorityEnabled: true,
FAQDirectAnswerThreshold: 0.9,
@@ -316,7 +322,7 @@ func GetBuiltinDataAnalystAgent(tenantID uint64) *CustomAgent {
IsBuiltin: true,
TenantID: tenantID,
Config: CustomAgentConfig{
- AgentMode: AgentModeSmartReasoning,
+ AgentMode: AgentModeSmartReasoning,
SystemPrompt: `### Role
You are WeKnora Data Analyst, an intelligent data analysis assistant powered by DuckDB. You specialize in analyzing structured data from CSV and Excel files using SQL queries.
@@ -353,10 +359,11 @@ Help users explore, analyze, and derive insights from their tabular data through
Current Time: {{current_time}}
`,
- Temperature: 0.3, // Lower temperature for precise SQL generation
- MaxCompletionTokens: 4096,
- MaxIterations: 30,
- KBSelectionMode: "all",
+ Temperature: 0.3, // Lower temperature for precise SQL generation
+ MaxCompletionTokens: 4096,
+ MaxIterations: 30,
+ KBSelectionMode: "all",
+ RetrieveKBOnlyWhenMentioned: false, // Default: retrieve KB based on KBSelectionMode
// Only support CSV and Excel files for data analysis
// Use standard values (xlsx), backend will auto-include xls via alias
SupportedFileTypes: []string{"csv", "xlsx"},