fix(pipeline): make data-analysis stage opt-in per agent (#1244)

The legacy in-pipeline DuckDB SQL data-analysis stage used to run on every
quick-answer RAG request whose retrieved chunks included a CSV/Excel file,
adding one extra LLM round-trip (~3s) to generate a SQL query that most
plain Q&A users never wanted. There was no way to disable it.

Introduce a per-agent DataAnalysisEnabled flag (default off), wire it
through PipelineRequest, and gate the DATA_ANALYSIS stage on it. Surface
the toggle in the agent editor for quick-answer agents with at least one
knowledge base attached.

Refs: https://github.com/Tencent/WeKnora/issues/1244

frontend/src/i18n/locales/en-US.ts

@@ -4007,6 +4007,10 @@ export default {
       boostLabel: 'FAQ Score Boost',
       boostDesc: 'Multiply FAQ relevance scores by this factor to rank them higher',
     },
+    dataAnalysis: {
+      enableLabel: 'Enable Tabular Data Analysis',
+      enableDesc: 'When the retrieved chunks come from a CSV/Excel file, ask the LLM to generate a DuckDB SQL query before answering. This adds one extra LLM call and several seconds of latency, so only enable it when you actually need SQL-style analysis.',
+    },
     fallback: {
       fixed: 'Fixed Response',
       model: 'Model Generated',

frontend/src/i18n/locales/ko-KR.ts

@@ -4070,6 +4070,10 @@ export default {
       boostLabel: 'FAQ 점수 가중치',
       boostDesc: 'FAQ 관련성 점수에 이 계수를 곱하여 순위를 높입니다',
     },
+    dataAnalysis: {
+      enableLabel: '표 데이터 분석 활성화',
+      enableDesc: '검색된 청크가 CSV/Excel 파일에서 온 경우, 답변 전에 LLM에 DuckDB SQL 쿼리를 생성하도록 요청합니다. LLM 호출이 한 번 더 발생하고 수 초의 지연이 추가되므로 SQL 스타일 분석이 실제로 필요할 때만 활성화하세요.',
+    },
     fallback: {
       fixed: '고정 응답',
       model: '모델 생성',

frontend/src/i18n/locales/ru-RU.ts

@@ -3679,6 +3679,10 @@ export default {
       boostLabel: 'Коэффициент FAQ',
       boostDesc: 'Умножение оценки релевантности FAQ на этот коэффициент для повышения ранга'
     },
+    dataAnalysis: {
+      enableLabel: 'Включить анализ табличных данных',
+      enableDesc: 'Если извлечённые фрагменты относятся к файлу CSV/Excel, перед ответом LLM сгенерирует SQL-запрос DuckDB. Это добавляет ещё один вызов LLM и несколько секунд задержки, поэтому включайте только при действительной необходимости SQL-анализа.'
+    },
     fallback: {
       fixed: 'Фиксированный ответ',
       model: 'Генерация моделью'

frontend/src/i18n/locales/zh-CN.ts

@@ -4003,6 +4003,10 @@ export default {
       boostLabel: "FAQ 分数加权",
       boostDesc: "FAQ 结果的相关性分数乘以此系数，使其排序更靠前",
     },
+    dataAnalysis: {
+      enableLabel: "启用表格数据分析",
+      enableDesc: "命中 CSV/Excel 类文件时，先调用大模型生成 DuckDB SQL 进行统计或筛选，再据此回答。会额外增加一次模型调用与几秒延迟，仅在确实需要时开启。",
+    },
     fallback: {
       fixed: "固定回复",
       model: "模型生成",

frontend/src/views/agent/AgentEditorModal.vue

@@ -1064,6 +1064,17 @@
                         </div>
                       </div>
                     </div>
+
+                    <!-- 数据分析阶段开关（quick-answer 模式下，针对 CSV/Excel 文件触发额外 SQL 生成） -->
+                    <div v-if="!isAgentMode && hasKnowledgeBase" class="setting-row">
+                      <div class="setting-info">
+                        <label>{{ $t('agentEditor.dataAnalysis.enableLabel') }}</label>
+                        <p class="desc">{{ $t('agentEditor.dataAnalysis.enableDesc') }}</p>
+                      </div>
+                      <div class="setting-control">
+                        <t-switch v-model="formData.config.data_analysis_enabled" />
+                      </div>
+                    </div>
                   </div>
                 </div>
 
@@ -1850,6 +1861,8 @@ const defaultFormData = {
     image_storage_provider: '',
     // 文件类型限制
     supported_file_types: [] as string[],
+    // 数据分析阶段开关（默认关闭，避免在普通问答上多一次 LLM 调用生成 SQL）
+    data_analysis_enabled: false,
     // FAQ 策略设置
     faq_priority_enabled: true, // 是否启用 FAQ 优先策略
     faq_direct_answer_threshold: 0.9, // FAQ 直接回答阈值（相似度高于此值直接使用 FAQ 答案）

internal/application/service/session_knowledge_qa.go

@@ -179,7 +179,7 @@ func (s *sessionService) KnowledgeQA(
 			AddIf(req.WebSearchEnabled, types.WEB_FETCH).
 			Add(types.CHUNK_MERGE).
 			Add(types.FILTER_TOP_K).
-			Add(types.DATA_ANALYSIS).
+			AddIf(chatManage.DataAnalysisEnabled, types.DATA_ANALYSIS).
 			Add(types.INTO_CHAT_MESSAGE).
 			Add(types.CHAT_COMPLETION_STREAM).
 			Build()

internal/application/service/session_qa_helpers.go

@@ -199,6 +199,12 @@ func (s *sessionService) applyAgentOverridesToChatManage(
 		logger.Infof(ctx, "FAQ priority enabled: threshold=%.2f, boost=%.2f",
 			cm.FAQDirectAnswerThreshold, cm.FAQScoreBoost)
 	}
+
+	// Data-analysis pipeline stage (opt-in, default off).
+	cm.DataAnalysisEnabled = customAgent.Config.DataAnalysisEnabled
+	if cm.DataAnalysisEnabled {
+		logger.Infof(ctx, "Data analysis pipeline stage enabled by custom agent")
+	}
 }
 
 // restrictMentionsToAgentScope filters user-provided @mention targets (KB IDs

internal/types/chat_manage.go

@@ -42,6 +42,11 @@ type PipelineRequest struct {
 	FAQDirectAnswerThreshold float64 `json:"-"`
 	FAQScoreBoost            float64 `json:"-"`
 
+	// DataAnalysisEnabled controls whether the in-pipeline DuckDB SQL
+	// data-analysis stage runs. Off by default to avoid an extra LLM call on
+	// every RAG request that happens to retrieve CSV/Excel chunks.
+	DataAnalysisEnabled bool `json:"-"`
+
 	// Image / multimodal support
 	Images                  []string `json:"-"`
 	VLMModelID              string   `json:"-"`
@@ -199,6 +204,7 @@ func (c *ChatManage) Clone() *ChatManage {
 			FAQPriorityEnabled:       c.FAQPriorityEnabled,
 			FAQDirectAnswerThreshold: c.FAQDirectAnswerThreshold,
 			FAQScoreBoost:            c.FAQScoreBoost,
+			DataAnalysisEnabled:      c.DataAnalysisEnabled,
 			Images:                   append([]string(nil), c.Images...),
 			VLMModelID:               c.VLMModelID,
 			ChatModelSupportsVision:  c.ChatModelSupportsVision,

internal/types/custom_agent.go

@@ -168,6 +168,13 @@ type CustomAgentConfig struct {
 	// When set, only files with matching extensions can be used with this agent
 	SupportedFileTypes []string `yaml:"supported_file_types" json:"supported_file_types"`
 
+	// ===== Data Analysis Settings =====
+	// Whether to run the legacy in-pipeline DuckDB SQL data-analysis stage when
+	// the retrieved chunks include CSV/Excel files. This issues an extra LLM
+	// call to generate a SQL query and is disabled by default because most
+	// quick-answer / RAG-style agents do not want the added latency.
+	DataAnalysisEnabled bool `yaml:"data_analysis_enabled" json:"data_analysis_enabled"`
+
 	// ===== FAQ Strategy Settings =====
 	// Whether FAQ priority strategy is enabled (FAQ answers prioritized over document chunks)
 	FAQPriorityEnabled bool `yaml:"faq_priority_enabled" json:"faq_priority_enabled"`