@roll-agent/octopus-agent 0.0.10 → 0.1.0

package/src/octopus_skill/agent.py

@@ -8,25 +8,78 @@ from typing import Any
 from .audit_logger import AuditLogger, sql_hash
 from .config import AppConfig
 from .context import UserContext, new_session_id, new_trace_id
+from .exporter import export_result_to_csv
+from .llm_result_renderer import render_result_with_llm
 from .llm_sql_generator import Sampler, SamplingSqlGenerator
 from .mcp_client import SpongeMcpClient
-from .query_sql_cache import QuerySqlCache
+from .prompt_builder import _business_examples, filter_agent_instructions_by_stage, format_numbered_instruction_lines
+from .question_analyzer import QuestionAnalysis, QuestionAnalysisError, analyze_question
 from .result_renderer import normalize_result_format, render_result
 from .schema_cache import SchemaCache
-from .schema_context_retriever import retrieve_schema_context
+from .schema_context_retriever import match_concepts_for_question, narrow_schema_context_for_query_plan, retrieve_schema_context, _schema_agent_instructions
 from .sql_generator import (
     GeneratedSql,
-    RuleBasedSqlGenerator,
     SqlGenerationError,
+    build_schema_validation_error,
+    build_execute_unknown_column_error,
+    build_sql_rule_validation_error,
     enforce_sql_rules,
+    finalize_generated_sql,
+    _is_business_query,
     is_low_quality_sql_for_question,
-    is_recruiting_match_effect_query,
+    low_quality_sql_issue_for_question,
+    normalize_text_filters_to_like,
+    normalize_chinese_select_aliases,
     sensitive_terms_in_text,
+    sql_missing_query_plan_filters,
+    sql_missing_query_plan_select_fields,
+    sql_satisfies_query_plan_filters,
+    sql_satisfies_query_plan_select_fields,
     sql_satisfies_time_range,
+    apply_time_range_filters_from_plan,
+    apply_time_range_filters_from_question,
+    time_range_plan_filters,
     validate_sql_against_schema,
 )
 
 
+# Entity types supported by Sponge search_entities; mapsTo values map here.
+_SEARCHABLE_ENTITY_TYPES = frozenset({"brand", "project", "province", "city", "region"})
+_MAPS_TO_SEARCH_ENTITY_TYPE = {
+    "brand": "brand",
+    "sponge_project": "project",
+    "project": "project",
+    "province": "province",
+    "city": "city",
+    "region": "region",
+}
+# Always available location dimensions; merged into catalog when schema omits them.
+_CORE_LOCATION_DIMENSIONS: tuple[dict[str, str], ...] = (
+    {"term": "城市", "mapsTo": "city", "type": "dimension"},
+    {"term": "省份", "mapsTo": "province", "type": "dimension"},
+    {"term": "区域", "mapsTo": "region", "type": "dimension"},
+)
+_STORE_NAME_MARKERS = ("店", "广场", "路", "街", "中心", "大厦", "号楼", "商场", "地铁", "项目")
+_EXPLICIT_ENTITY_TYPES_KEY = "__explicitTypes"
+
+
+# Validate error codes treated as "caller has no data scope" -> a valid empty
+# result, not a SQL failure.
+#
+# Per MCP source review (alignment checklist Q1), the *current* server emits NO
+# error for empty scope: it injects an `IN (NULL)` scope filter and returns
+# success with 0 rows, which the normal empty-result path already handles. These
+# codes are therefore only a defensive net for OLDER ONLINE deployments still
+# observed emitting MCP_SQL_MISSING_SCOPE in audit logs (plus the declared-but-
+# currently-unthrown MCP_PERMISSION_EMPTY_SCOPE).
+#
+# This is intentionally NOT treated as the live MCP contract. Remove once every
+# online MCP instance runs the no-error-code behaviour.
+_LEGACY_EMPTY_SCOPE_CODES = frozenset(
+    {"MCP_PERMISSION_EMPTY_SCOPE", "MCP_SQL_MISSING_SCOPE"}
+)
+
+
 @dataclass(frozen=True)
 class QueryResult:
     answer: str
@@ -34,6 +87,13 @@ class QueryResult:
     normalized_sql: str
     repaired_sql: str | None
     validation: dict[str, Any]
+    needs_clarification: bool = False
+    clarification_type: str | None = None
+    clarification_payload: dict[str, Any] | None = None
+    query_plan: dict[str, Any] | None = None
+    execution_steps: list[dict[str, Any]] = field(default_factory=list)
+    raw_result: dict[str, Any] | None = None
+    result_format: str | None = None
 
 
 @dataclass
@@ -88,272 +148,764 @@ class SpongeAgent:
         result_format: str | None = None,
         fast_mode: bool = True,
     ) -> QueryResult:
-        user_question = original_question or question
-        if _is_mutation_request(user_question):
-            return _query_only_result()
+        steps = _ExecutionSteps()
+        steps.done(1, "已进入 query_sponge")
+        user_question = _isolate_current_question(original_question or question)
+        schema: dict[str, Any] | None = None
+        pre_sql_agent_instructions: list[dict[str, Any]] = []
+        try:
+            schema = self._ensure_schema()
+            pre_sql_agent_instructions = _schema_agent_instructions(schema)
+        except Exception:
+            schema = None
+            pre_sql_agent_instructions = []
+        # Step 2: LLM 需求分析
+        steps.running(2)
+        if sampler is None:
+            reason = "当前无模型可用，请确认配置文件。"
+            steps.error(2, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        try:
+            analysis = analyze_question(
+                user_question,
+                sampler,
+                agent_instructions=pre_sql_agent_instructions,
+            )
+        except QuestionAnalysisError as exc:
+            reason = f"需求分析失败：{exc}"
+            steps.error(2, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        if analysis.intent == "mutation":
+            reason = f"检测到写操作意图（置信度 {analysis.confidence:.0%}）；query_sponge 只支持只读查询。"
+            steps.error(2, reason)
+            return _attach_execution_steps(_non_query_result(reason), steps)
+        if analysis.intent == "non_query":
+            reason = analysis.clarification_reason or "请先输入明确的业务数据查询需求。"
+            steps.error(2, reason)
+            return _attach_execution_steps(_non_query_result(reason), steps)
+        # intent == "query"
+        sql_question = _preserve_limit_scope_in_normalized_question(
+            analysis.normalized_question or user_question,
+            user_question,
+        )
+        time_range_question = _time_range_source_question(user_question, sql_question)
+        steps.done(
+            2,
+            f"意图=query（{analysis.confidence:.0%}）；"
+            f"对象={analysis.target_entities or '未提取'}；"
+            f"规范化问题={sql_question}",
+        )
+        self.audit_logger.log(
+            {
+                "sessionId": session_id,
+                "question": user_question,
+                "tool": "question_analysis",
+                "intent": analysis.intent,
+                "confidence": analysis.confidence,
+                "targetEntities": analysis.target_entities,
+                "metrics": analysis.metrics,
+                "noiseValues": analysis.noise_values,
+                "requiredConcepts": analysis.required_concepts,
+                "mutationSignals": analysis.mutation_signals,
+                "normalizedQuestion": sql_question,
+            }
+        )
         context = UserContext(
             session_id=session_id or new_session_id(),
         )
-        sql_question = _strip_result_format_instruction(user_question)
         sensitive_terms = sensitive_terms_in_text(sql_question)
-        schema = self._ensure_schema()
+        steps.running(3)
+        if schema is None:
+            try:
+                schema = self._ensure_schema()
+            except Exception as exc:
+                reason = f"{type(exc).__name__}: {exc}"
+                steps.error(3, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+        steps.done(3, f"schemaVersion={schema.get('schemaVersion') or 'unknown'}")
+        required_concept_gap = _required_schema_concepts_gap_message(analysis, schema)
+        if required_concept_gap is not None:
+            steps.error(4, required_concept_gap)
+            return _attach_execution_steps(_business_metric_clarification_result(required_concept_gap), steps)
         unsupported_field_message = _unsupported_requested_field_message(sql_question, schema)
         if unsupported_field_message is not None:
-            return _business_metric_clarification_result(unsupported_field_message)
+            steps.error(4, unsupported_field_message)
+            return _attach_execution_steps(_business_metric_clarification_result(unsupported_field_message), steps)
         business_clarification = _business_metric_clarification(sql_question, schema)
         if business_clarification is not None:
-            return _business_metric_clarification_result(business_clarification)
-        schema_version = str(schema.get("schemaVersion")) if schema.get("schemaVersion") is not None else None
+            steps.error(4, "业务指标口径不明确，需要用户先确认指标、时间、状态和聚合维度。")
+            return _attach_execution_steps(_business_metric_clarification_result(business_clarification), steps)
         repaired_sql: str | None = None
-        prefer_rule_based = is_recruiting_match_effect_query(sql_question)
-        sql_cache = _make_query_sql_cache(self.config)
-        cached_sql = sql_cache.get(question=sql_question, schema_version=schema_version) if sql_cache is not None else None
-        if cached_sql is not None and not sql_satisfies_time_range(cached_sql, sql_question, schema):
-            cached_sql = None
-        if cached_sql is not None and is_low_quality_sql_for_question(sql_question, cached_sql):
-            sql_cache.delete(question=sql_question, schema_version=schema_version)
-            cached_sql = None
-        if cached_sql is not None and validate_sql_against_schema(cached_sql, schema):
-            sql_cache.delete(question=sql_question, schema_version=schema_version)
-            cached_sql = None
-        if cached_sql is not None:
-            generated = GeneratedSql(sql=cached_sql, tables=[], placeholders=[])
-        if sampler is not None:
-            schema_context = None
-            generator: SamplingSqlGenerator | None = None
-            if cached_sql is None:
-                schema_context = retrieve_schema_context(schema, sql_question)
-                generator = SamplingSqlGenerator(
-                    sampler=sampler,
-                    default_limit=self.config.sql.default_limit,
-                    max_limit=self.config.sql.max_limit,
-                )
-                if fast_mode or prefer_rule_based:
-                    try:
-                        generated = _generate_rule_based_sql(
-                            question=sql_question,
-                            schema=schema,
-                            default_limit=self.config.sql.default_limit,
-                            max_limit=self.config.sql.max_limit,
-                        )
-                    except SqlGenerationError:
-                        generated, repaired_sql = _generate_with_sampler(
-                            generator=generator,
-                            question=sql_question,
-                            schema_context=schema_context,
-                        )
-                    else:
-                        repaired_sql = None
-                else:
-                    generated, repaired_sql = _generate_with_sampler(
-                        generator=generator,
-                        question=sql_question,
-                        schema_context=schema_context,
-                    )
-                    if generated.sql == "" and repaired_sql is None:
-                        return _query_only_result()
-                if fast_mode and generated.sql == "" and repaired_sql is None:
-                    return _query_only_result()
-                if not fast_mode and generated.sql == "" and repaired_sql is None:
-                    return _query_only_result()
-        elif cached_sql is None:
-            schema_context = None
-            generated = _generate_rule_based_sql(
+        steps.running(4)
+        try:
+            schema_context = retrieve_schema_context(
+                schema,
+                sql_question,
+            )
+        except Exception as exc:
+            reason = f"{type(exc).__name__}: {exc}"
+            steps.error(4, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        steps.done(4, _schema_context_step_detail(schema_context))
+        if not _schema_context_has_semantic_match(sql_question, schema_context):
+            reason = "schemaContext 未匹配到可用表、字段、指标、概念或示例。"
+            steps.error(4, reason)
+            return _attach_execution_steps(_schema_no_match_result(sql_question), steps)
+        steps.running(5)
+        searched_entities = self._search_entities_for_question(
+            context,
+            sql_question,
+            schema_context,
+            schema,
+            sampler=sampler,
+            analysis=analysis,
+        )
+        steps.done(5, _entity_search_step_detail(searched_entities))
+        steps.running(6)
+        query_plan = _build_query_plan(
+            sql_question,
+            schema_context,
+            schema,
+            searched_entities=searched_entities,
+            sampler=sampler,
+            time_range_question=time_range_question,
+            analysis=analysis,
+        )
+        steps.done(6, "已生成查询计划并直接执行。")
+        sql_schema_context = (
+            narrow_schema_context_for_query_plan(schema_context, query_plan, full_schema=schema)
+            if query_plan
+            else schema_context
+        )
+        generator: SamplingSqlGenerator | None = None
+        steps.running(7)
+        if sampler is None:
+            generated = _generate_from_schema_example(
                 question=sql_question,
-                schema=schema,
+                schema_context=sql_schema_context,
+            )
+            self.audit_logger.log(
+                {
+                    "sessionId": context.session_id,
+                    "question": sql_question,
+                    "tool": "schema_example_fallback",
+                    "matched": generated is not None,
+                    "exampleCount": len(schema_context.examples),
+                    "sqlHash": sql_hash(generated.sql) if generated is not None else None,
+                }
+            )
+            if generated is None:
+                reason = "未提供 sampler，且 schema examples 没有匹配到可复用 SQL。"
+                steps.error(7, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+            steps.done(7, "已从 schema examples 匹配 SQL。")
+        else:
+            generator = SamplingSqlGenerator(
+                sampler=sampler,
                 default_limit=self.config.sql.default_limit,
                 max_limit=self.config.sql.max_limit,
+                confirmed_query_plan=query_plan,
             )
-        else:
-            schema_context = None
-            generator = None
-        candidate_sql = repaired_sql or _apply_limit_policy(
+            generated, repaired_sql, generation_repair_attempted = _generate_with_sampler(
+                generator=generator,
+                question=sql_question,
+                schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_repair_attempts=self.config.sql.max_repair_attempts,
+                schema=schema,
+            )
+            generation_clarification = _sql_generation_clarification_result(
+                sql_question,
+                generated,
+                query_plan=query_plan,
+            )
+            if generation_clarification is not None:
+                steps.waiting(7, "LLM 判断需要用户补充信息。")
+                return _attach_execution_steps(generation_clarification, steps)
+            if generated.sql == "" and repaired_sql is None:
+                if generation_repair_attempted:
+                    reason = "LLM SQL 生成失败，自动修复后仍未返回可用 SELECT SQL。"
+                    steps.error(7, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+                repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+                    generator=generator,
+                    question=sql_question,
+                    sql="",
+                    validation_error={
+                        "code": "EMPTY_SQL",
+                        "message": "schemaContext 已提供相关表、JOIN、枚举或示例时，不要直接返回空 SQL；请基于当前 schemaContext 生成完整 SELECT SQL。",
+                        "originalSql": "",
+                    },
+                    schema_context=sql_schema_context,
+                    audit_logger=self.audit_logger,
+                    session_id=context.session_id,
+                    max_attempts=self.config.sql.max_repair_attempts,
+                    default_limit=self.config.sql.default_limit,
+                    max_limit=self.config.sql.max_limit,
+                    schema=schema,
+                    check=lambda candidate: _require_non_empty_select(candidate),
+                    steps=steps,
+                    running_detail="LLM 返回空 SQL，尝试修复",
+                    failure_detail="LLM 返回空 SQL，修复失败",
+                )
+                if repaired_sql is None:
+                    steps.error(9, fail_reason)
+                    return _attach_execution_steps(_query_only_result(fail_reason), steps)
+            steps.done(7, "已通过 LLM 生成 SQL。")
+        candidate_sql = repaired_sql or _finalize_candidate_sql(
             generated.sql,
             sql_question,
             default_limit=self.config.sql.default_limit,
             max_limit=self.config.sql.max_limit,
+            schema=schema,
         )
-        if not sql_satisfies_time_range(candidate_sql, sql_question, schema):
+        if query_plan:
+            candidate_sql = apply_time_range_filters_from_plan(candidate_sql, query_plan)
+        if schema is not None:
+            candidate_sql = apply_time_range_filters_from_question(candidate_sql, time_range_question, schema)
+        if not sql_satisfies_time_range(candidate_sql, time_range_question, schema, query_plan=query_plan):
             if sampler is None or schema_context is None or generator is None:
-                return _query_only_result()
-            try:
-                repaired = generator.repair(
-                    question=sql_question,
-                    original_sql=candidate_sql,
-                    validation_error={
-                        "code": "MISSING_TIME_RANGE_FILTER",
-                        "message": "用户问题包含时间范围，SQL 必须在 WHERE 条件中直接包含对应时间字段过滤。",
-                    },
-                    schema_context=schema_context,
-                )
-            except SqlGenerationError:
-                return _query_only_result()
-            generated = GeneratedSql(sql="", tables=[], placeholders=[])
-            repaired_sql = _apply_limit_policy(
-                repaired.sql,
-                sql_question,
+                reason = "SQL 缺少用户问题要求的时间范围过滤，且当前没有 sampler 可修复。"
+                steps.error(8, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+            repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+                generator=generator,
+                question=sql_question,
+                sql=candidate_sql,
+                validation_error={
+                    "code": "MISSING_TIME_RANGE_FILTER",
+                    "message": "用户问题包含时间范围，SQL 必须在 WHERE 条件中直接包含对应时间字段过滤。",
+                    "originalSql": candidate_sql,
+                },
+                schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_attempts=self.config.sql.max_repair_attempts,
                 default_limit=self.config.sql.default_limit,
                 max_limit=self.config.sql.max_limit,
+                schema=schema,
+                check=lambda candidate: _require_time_range(candidate, time_range_question, schema, query_plan),
+                steps=steps,
+                running_detail="SQL 缺少时间范围过滤，尝试修复",
+                failure_detail="SQL 缺少时间范围过滤，修复失败",
             )
+            if repaired_sql is None:
+                steps.error(9, fail_reason)
+                return _attach_execution_steps(_query_only_result(fail_reason), steps)
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            if not sql_satisfies_time_range(candidate_sql, sql_question, schema):
-                return _query_only_result()
-        if is_low_quality_sql_for_question(sql_question, candidate_sql):
+            steps.done(9, "已补充时间范围过滤。")
+        if query_plan and not sql_satisfies_query_plan_filters(candidate_sql, query_plan):
+            missing_filters = sql_missing_query_plan_filters(candidate_sql, query_plan)
             if sampler is None or schema_context is None or generator is None:
-                return _query_only_result()
-            try:
-                repaired = generator.repair(
-                    question=sql_question,
-                    original_sql=candidate_sql,
-                    validation_error={
-                        "code": "LOW_QUALITY_SQL",
-                        "message": "SQL 与问题意图不匹配，业务查询不能退化成品牌、项目、城市、门店、岗位等单表列表；明确名称时必须在完整业务 SQL 中 JOIN 对应表并使用 name LIKE 或 job_name LIKE。",
-                    },
-                    schema_context=schema_context,
-                )
-            except SqlGenerationError:
-                return _query_only_result()
-            generated = GeneratedSql(sql="", tables=[], placeholders=[])
-            repaired_sql = _apply_limit_policy(
-                repaired.sql,
-                sql_question,
+                reason = f"SQL 缺少查询计划中的筛选条件：{'; '.join(missing_filters)}"
+                steps.error(8, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+            repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+                generator=generator,
+                question=sql_question,
+                sql=candidate_sql,
+                validation_error={
+                    "code": "MISSING_QUERY_PLAN_FILTER",
+                    "message": (
+                        f"SQL 缺少查询计划中的筛选条件：{'; '.join(missing_filters)}。"
+                        "必须 JOIN 相关表并在 WHERE 中包含全部 table.column 过滤。"
+                    ),
+                    "originalSql": candidate_sql,
+                    "missingFilters": missing_filters,
+                },
+                schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_attempts=self.config.sql.max_repair_attempts,
                 default_limit=self.config.sql.default_limit,
                 max_limit=self.config.sql.max_limit,
+                schema=schema,
+                check=lambda candidate: sql_satisfies_query_plan_filters(candidate, query_plan),
+                steps=steps,
+                running_detail=f"SQL 缺少查询计划筛选条件，尝试修复：{'; '.join(missing_filters)}",
+                failure_detail="SQL 缺少查询计划筛选条件，修复失败",
             )
+            if repaired_sql is None:
+                steps.error(9, fail_reason)
+                return _attach_execution_steps(_query_only_result(fail_reason), steps)
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            if is_low_quality_sql_for_question(sql_question, candidate_sql):
-                return _query_only_result()
-        schema_issues = validate_sql_against_schema(candidate_sql, schema)
-        if schema_issues:
+            steps.done(9, "已补充查询计划筛选条件。")
+        if query_plan and not sql_satisfies_query_plan_select_fields(candidate_sql, query_plan):
+            missing_select_fields = sql_missing_query_plan_select_fields(candidate_sql, query_plan)
             if sampler is None or schema_context is None or generator is None:
-                return _query_only_result()
-            try:
-                repaired = generator.repair(
-                    question=sql_question,
-                    original_sql=candidate_sql,
-                    validation_error={
-                        "code": schema_issues[0].code,
-                        "message": schema_issues[0].message,
-                    },
-                    schema_context=schema_context,
-                )
-            except SqlGenerationError:
-                return _query_only_result()
+                reason = f"SQL 缺少查询计划中的展示字段：{'; '.join(missing_select_fields)}"
+                steps.error(8, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+            repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+                generator=generator,
+                question=sql_question,
+                sql=candidate_sql,
+                validation_error={
+                    "code": "MISSING_QUERY_PLAN_SELECT_FIELD",
+                    "message": (
+                        f"SQL 缺少查询计划中的展示字段：{'; '.join(missing_select_fields)}。"
+                        "同一别称命中多个实体类型时，必须在 SELECT 中展示各实体名称字段，方便用户自行缩小范围。"
+                    ),
+                    "originalSql": candidate_sql,
+                    "missingSelectFields": missing_select_fields,
+                },
+                schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_attempts=self.config.sql.max_repair_attempts,
+                default_limit=self.config.sql.default_limit,
+                max_limit=self.config.sql.max_limit,
+                schema=schema,
+                check=lambda candidate: sql_satisfies_query_plan_select_fields(candidate, query_plan),
+                steps=steps,
+                running_detail=f"SQL 缺少查询计划展示字段，尝试修复：{'; '.join(missing_select_fields)}",
+                failure_detail="SQL 缺少查询计划展示字段，修复失败",
+            )
+            if repaired_sql is None:
+                steps.error(9, fail_reason)
+                return _attach_execution_steps(_query_only_result(fail_reason), steps)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
-            repaired_sql = _apply_limit_policy(
-                repaired.sql,
-                sql_question,
+            candidate_sql = repaired_sql
+            steps.done(9, "已补充查询计划展示字段。")
+        low_quality_issue = low_quality_sql_issue_for_question(sql_question, candidate_sql, schema=schema)
+        if low_quality_issue is not None:
+            if sampler is None or schema_context is None or generator is None:
+                steps.error(8, low_quality_issue.message)
+                return _attach_execution_steps(_low_quality_sql_result(low_quality_issue.message, candidate_sql), steps)
+            repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+                generator=generator,
+                question=sql_question,
+                sql=candidate_sql,
+                validation_error={
+                    "code": low_quality_issue.code,
+                    "message": low_quality_issue.message,
+                    "originalSql": candidate_sql,
+                },
+                schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_attempts=self.config.sql.max_repair_attempts,
                 default_limit=self.config.sql.default_limit,
                 max_limit=self.config.sql.max_limit,
+                schema=schema,
+                check=lambda candidate: _require_low_quality_pass(candidate, sql_question, schema),
+                steps=steps,
+                running_detail=f"SQL 质量检查失败，尝试修复：{low_quality_issue.message}",
+                failure_detail=f"SQL 质量检查失败，修复失败：{low_quality_issue.message}",
             )
+            if repaired_sql is None:
+                steps.error(9, fail_reason)
+                return _attach_execution_steps(_low_quality_sql_result(fail_reason, candidate_sql), steps)
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            if validate_sql_against_schema(candidate_sql, schema):
-                return _query_only_result()
+            steps.done(9, "已修复 SQL 质量问题。")
+        prior_sql = candidate_sql
+        candidate_sql, schema_fail = _repair_sql_for_local_schema_issues(
+            candidate_sql=candidate_sql,
+            sql_question=sql_question,
+            schema=schema,
+            generator=generator,
+            schema_context=schema_context,
+            sql_schema_context=sql_schema_context,
+            audit_logger=self.audit_logger,
+            session_id=context.session_id,
+            max_repair_attempts=self.config.sql.max_repair_attempts,
+            default_limit=self.config.sql.default_limit,
+            max_limit=self.config.sql.max_limit,
+            steps=steps,
+        )
+        if schema_fail:
+            steps.error(8, schema_fail)
+            return _attach_execution_steps(_query_only_result(schema_fail), steps)
+        if candidate_sql != prior_sql:
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
+        candidate_sql = _finalize_candidate_sql(
+            candidate_sql,
+            sql_question,
+            default_limit=self.config.sql.default_limit,
+            max_limit=self.config.sql.max_limit,
+            schema=schema,
+        )
         try:
+            steps.running(8)
             enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
+            steps.done(8, "SQL 满足只读、安全、LIMIT、中文别名等规则。")
         except SqlGenerationError as exc:
+            if sampler is None or schema_context is None or generator is None:
+                reason = f"SQL 违反本地规则，且当前没有 sampler 可修复：{exc}"
+                steps.error(8, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
             if _is_sensitive_sql_error(exc) and sensitive_terms:
-                if sampler is None or schema_context is None or generator is None:
-                    return _sensitive_query_only_result(sensitive_terms)
+                validation_error = {
+                    "code": "SENSITIVE_FIELD",
+                    "message": "用户要求的敏感字段必须从 SELECT 中排除；如还有其他非敏感字段，请继续生成去敏后的 SQL。",
+                    "originalSql": candidate_sql,
+                    "violatingColumns": build_sql_rule_validation_error(
+                        candidate_sql, exc, max_limit=self.config.sql.max_limit
+                    ).get("violatingColumns", []),
+                }
+                running_detail = f"SQL 包含敏感字段，尝试去敏修复：{exc}"
+                failure_detail = f"SQL 包含敏感字段，去敏修复失败"
+            else:
+                validation_error = build_sql_rule_validation_error(
+                    candidate_sql,
+                    exc,
+                    max_limit=self.config.sql.max_limit,
+                    max_attempts=self.config.sql.max_repair_attempts,
+                )
+                running_detail = f"SQL 违反本地规则，尝试修复：{exc}"
+                failure_detail = "SQL 违反本地规则，修复失败"
+            repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+                generator=generator,
+                question=sql_question,
+                sql=candidate_sql,
+                validation_error=validation_error,
+                schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_attempts=self.config.sql.max_repair_attempts,
+                default_limit=self.config.sql.default_limit,
+                max_limit=self.config.sql.max_limit,
+                schema=schema,
+                check=lambda candidate: enforce_sql_rules(candidate, max_limit=self.config.sql.max_limit),
+                steps=steps,
+                running_detail=running_detail,
+                failure_detail=failure_detail,
+            )
+            if repaired_sql is None:
+                steps.error(9, fail_reason)
+                if _is_sensitive_sql_error(exc) and sensitive_terms:
+                    return _attach_execution_steps(_sensitive_query_only_result(sensitive_terms, reason=fail_reason), steps)
+                return _attach_execution_steps(_query_only_result(fail_reason), steps)
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
+            candidate_sql = repaired_sql
+            steps.done(8, "SQL 修复后满足本地规则。")
+        if not any(step["status"] == "done" and step["step"] == 9 for step in steps.steps):
+            steps.skipped(9, "SQL 无需修复。")
+        prior_sql = candidate_sql
+        candidate_sql, schema_fail = _repair_sql_for_local_schema_issues(
+            candidate_sql=candidate_sql,
+            sql_question=sql_question,
+            schema=schema,
+            generator=generator,
+            schema_context=schema_context,
+            sql_schema_context=sql_schema_context,
+            audit_logger=self.audit_logger,
+            session_id=context.session_id,
+            max_repair_attempts=self.config.sql.max_repair_attempts,
+            default_limit=self.config.sql.default_limit,
+            max_limit=self.config.sql.max_limit,
+            steps=steps,
+            repair_success_detail="validate_sql 前已修复本地 schema 校验问题。",
+            running_prefix="validate_sql 前本地 schema 校验失败，尝试修复",
+        )
+        if schema_fail:
+            steps.error(10, schema_fail)
+            return _attach_execution_steps(_query_only_result(schema_fail), steps)
+        if candidate_sql != prior_sql:
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
+        prior_sql = candidate_sql
+        if query_plan:
+            candidate_sql = apply_time_range_filters_from_plan(candidate_sql, query_plan)
+        if schema is not None:
+            candidate_sql = apply_time_range_filters_from_question(candidate_sql, time_range_question, schema)
+        if candidate_sql != prior_sql:
+            candidate_sql, schema_fail = _repair_sql_for_local_schema_issues(
+                candidate_sql=candidate_sql,
+                sql_question=sql_question,
+                schema=schema,
+                generator=generator,
+                schema_context=schema_context,
+                sql_schema_context=sql_schema_context,
+                audit_logger=self.audit_logger,
+                session_id=context.session_id,
+                max_repair_attempts=self.config.sql.max_repair_attempts,
+                default_limit=self.config.sql.default_limit,
+                max_limit=self.config.sql.max_limit,
+                steps=steps,
+                repair_success_detail="补充时间范围后已修复本地 schema 校验问题。",
+                running_prefix="补充时间范围后本地 schema 校验失败，尝试修复",
+            )
+            if schema_fail:
+                steps.error(10, schema_fail)
+                return _attach_execution_steps(_query_only_result(schema_fail), steps)
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
+        candidate_sql = _remove_noise_name_like_filters_from_sql(candidate_sql, analysis=analysis)
+        if candidate_sql != prior_sql:
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
+            repaired_sql = candidate_sql
+        steps.running(10)
+        try:
+            normalized_sql = self._validate_sql(context, user_question, candidate_sql)
+        except Exception as exc:
+            reason = f"{type(exc).__name__}: {exc}"
+            steps.error(10, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        if normalized_sql is None and _is_auth_validation_error(self._validation_error_code()):
+            reason = _validation_error_message(self._last_validation_result) or "MCP 用户认证失败。"
+            steps.error(10, reason)
+            return _attach_execution_steps(
+                _auth_error_result(
+                    self._last_validation_result,
+                    generated_sql=generated.sql,
+                    repaired_sql=repaired_sql,
+                ),
+                steps,
+            )
+        if normalized_sql is None and self._validation_error_code() in _LEGACY_EMPTY_SCOPE_CODES:
+            # Legacy online-version compatibility only (see _LEGACY_EMPTY_SCOPE_CODES):
+            # the current MCP contract returns an empty success result for no-scope
+            # users, which the normal flow already renders. Older deployments still
+            # emit these codes, so treat them as an empty result instead of raising.
+            steps.done(10, "validate_sql 返回旧版空权限错误，按空结果兼容处理。")
+            return _attach_execution_steps(_empty_scope_result(user_question, result_format), steps)
+        if sampler is not None and normalized_sql is None and schema_context is not None and generator is not None:
+            current_sql = candidate_sql
+            validation_error: dict[str, Any] = dict(self._last_validation_error or {})
+            validation_error["originalSql"] = current_sql
+            validate_message = _validation_error_message(self._last_validation_result)
+            last_reason = f"validate_sql 失败，修复失败：{validate_message}"
+            for attempt in range(1, self.config.sql.max_repair_attempts + 1):
+                steps.running(9, f"validate_sql 失败，尝试修复：{validate_message}（第 {attempt}/{self.config.sql.max_repair_attempts} 次）")
+                repair_error = {
+                    **validation_error,
+                    "attempt": attempt,
+                    "maxAttempts": self.config.sql.max_repair_attempts,
+                    "originalSql": current_sql,
+                }
                 try:
                     repaired = generator.repair(
                         question=sql_question,
-                        original_sql=candidate_sql,
-                        validation_error={
-                            "code": "SENSITIVE_FIELD",
-                            "message": "用户要求的敏感字段必须从 SELECT 中排除；如还有其他非敏感字段，请继续生成去敏后的 SQL。",
-                        },
-                        schema_context=schema_context,
+                        original_sql=current_sql,
+                        validation_error=repair_error,
+                        schema_context=sql_schema_context,
+                    )
+                except SqlGenerationError as exc:
+                    last_reason = f"validate_sql 失败，LLM 修复调用失败（第 {attempt}/{self.config.sql.max_repair_attempts} 次）：{exc}"
+                    _log_llm_sql_repair_audit(
+                        self.audit_logger,
+                        session_id=context.session_id,
+                        question=sql_question,
+                        success=False,
+                        error=str(exc),
+                        attempt=attempt,
                     )
-                except SqlGenerationError:
-                    return _sensitive_query_only_result(sensitive_terms)
-                repaired_sql = _apply_limit_policy(
+                    continue
+                repaired_sql = _finalize_candidate_sql(
                     repaired.sql,
                     sql_question,
                     default_limit=self.config.sql.default_limit,
                     max_limit=self.config.sql.max_limit,
+                    schema=schema,
+                )
+                if query_plan:
+                    repaired_sql = apply_time_range_filters_from_plan(repaired_sql, query_plan)
+                if schema is not None:
+                    repaired_sql = apply_time_range_filters_from_question(repaired_sql, time_range_question, schema)
+                _log_llm_sql_repair_audit(
+                    self.audit_logger,
+                    session_id=context.session_id,
+                    question=sql_question,
+                    success=bool(repaired_sql.strip()),
+                    sql=repaired_sql if repaired_sql.strip() else None,
+                    error=None if repaired_sql.strip() else "empty_sql",
+                    attempt=attempt,
                 )
+                if not repaired_sql.strip():
+                    last_reason = f"validate_sql 修复返回空 SQL（第 {attempt}/{self.config.sql.max_repair_attempts} 次）"
+                    current_sql = repaired_sql
+                    continue
                 try:
                     enforce_sql_rules(repaired_sql, max_limit=self.config.sql.max_limit)
-                except SqlGenerationError as repaired_exc:
-                    if _is_sensitive_sql_error(repaired_exc):
-                        return _sensitive_query_only_result(sensitive_terms)
-                    return _query_only_result()
-                generated = GeneratedSql(sql="", tables=[], placeholders=[])
-                candidate_sql = repaired_sql
-            else:
-                if sampler is None:
-                    return _query_only_result()
-                if not fast_mode:
-                    return _query_only_result()
-                try:
-                    generated = _generate_rule_based_sql(
-                        question=sql_question,
-                        schema=schema,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
-                    )
-                    repaired_sql = None
-                    candidate_sql = _apply_limit_policy(
-                        generated.sql,
-                        sql_question,
-                        default_limit=self.config.sql.default_limit,
+                except SqlGenerationError as exc:
+                    if _is_sensitive_sql_error(exc) and sensitive_terms:
+                        reason = f"validate_sql 修复后包含敏感字段：{exc}"
+                        steps.error(9, reason)
+                        return _attach_execution_steps(_sensitive_query_only_result(sensitive_terms, reason=reason), steps)
+                    last_reason = f"validate_sql 修复后违反本地规则：{exc}"
+                    validation_error = build_sql_rule_validation_error(
+                        repaired_sql,
+                        exc,
                         max_limit=self.config.sql.max_limit,
+                        attempt=attempt,
+                        max_attempts=self.config.sql.max_repair_attempts,
                     )
-                    enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
-                except SqlGenerationError:
-                    return _query_only_result()
-        normalized_sql = self._validate_sql(context, user_question, candidate_sql)
-        if sampler is not None and normalized_sql is None and schema_context is not None and generator is not None:
-            try:
-                repaired = generator.repair(
-                    question=sql_question,
-                    original_sql=generated.sql,
-                    validation_error=self._last_validation_error,
-                    schema_context=schema_context,
-                )
-            except SqlGenerationError:
+                    current_sql = repaired_sql
+                    continue
                 try:
-                    if not fast_mode:
-                        return _query_only_result()
-                    generated = _generate_rule_based_sql(
-                        question=sql_question,
-                        schema=schema,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
+                    _require_no_schema_issues(repaired_sql, schema)
+                except SqlGenerationError as exc:
+                    schema_issues = validate_sql_against_schema(repaired_sql, schema)
+                    last_reason = f"validate_sql 修复后本地 schema 校验失败：{exc}"
+                    validation_error = build_schema_validation_error(
+                        repaired_sql,
+                        schema_issues,
+                        schema,
+                        attempt=attempt,
+                        max_attempts=self.config.sql.max_repair_attempts,
                     )
-                    repaired_sql = None
-                    candidate_sql = _apply_limit_policy(
-                        generated.sql,
-                        sql_question,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
+                    current_sql = repaired_sql
+                    continue
+                generated = GeneratedSql(sql="", tables=[], placeholders=[])
+                try:
+                    normalized_sql = self._validate_sql(context, user_question, repaired_sql)
+                except Exception as exc:
+                    reason = f"{type(exc).__name__}: {exc}"
+                    steps.error(10, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+                if normalized_sql is not None:
+                    candidate_sql = repaired_sql
+                    steps.done(9, f"已根据 validate_sql 错误修复 SQL（第 {attempt}/{self.config.sql.max_repair_attempts} 次）。")
+                    break
+                if _is_auth_validation_error(self._validation_error_code()):
+                    reason = _validation_error_message(self._last_validation_result) or "MCP 用户认证失败。"
+                    steps.error(10, reason)
+                    return _attach_execution_steps(
+                        _auth_error_result(
+                            self._last_validation_result,
+                            generated_sql=generated.sql,
+                            repaired_sql=repaired_sql,
+                        ),
+                        steps,
                     )
-                    enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
-                    normalized_sql = self._validate_sql(context, user_question, candidate_sql, raise_on_error=True)
-                except SqlGenerationError:
-                    return _query_only_result()
+                validate_message = _validation_error_message(self._last_validation_result)
+                last_reason = f"validate_sql 修复后仍失败：{validate_message}"
+                validation_error = dict(self._last_validation_error or {})
+                validation_error["originalSql"] = repaired_sql
+                current_sql = repaired_sql
             else:
-                generated = GeneratedSql(sql="", tables=[], placeholders=[])
-                repaired_sql = _apply_limit_policy(
-                    repaired.sql,
-                    sql_question,
+                steps.error(9, last_reason)
+                steps.error(10, last_reason)
+                return _attach_execution_steps(_query_only_result(last_reason), steps)
+        if normalized_sql is None:
+            reason = f"SQL validation failed: {_validation_error_message(self._last_validation_result)}"
+            steps.error(10, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        steps.done(10, "validate_sql 通过。")
+        steps.running(11)
+        try:
+            result = self._execute_sql(context, user_question, normalized_sql)
+        except Exception as exc:
+            unknown_col = _parse_execute_unknown_column(str(exc))
+            if (
+                unknown_col
+                and sampler is not None
+                and generator is not None
+                and schema_context is not None
+            ):
+                exec_error = build_execute_unknown_column_error(
+                    normalized_sql,
+                    unknown_col,
+                    schema,
+                    max_attempts=self.config.sql.max_repair_attempts,
+                )
+                repaired_exec_sql, fail_reason = _repair_sql_for_local_schema_issues(
+                    candidate_sql=normalized_sql,
+                    sql_question=sql_question,
+                    schema=schema,
+                    generator=generator,
+                    schema_context=schema_context,
+                    sql_schema_context=sql_schema_context,
+                    audit_logger=self.audit_logger,
+                    session_id=context.session_id,
+                    max_repair_attempts=self.config.sql.max_repair_attempts,
                     default_limit=self.config.sql.default_limit,
                     max_limit=self.config.sql.max_limit,
+                    steps=steps,
+                    repair_success_detail=f"已根据 execute 未知列 {unknown_col} 修复 SQL。",
+                    running_prefix=f"execute_sql 报未知列 {unknown_col}，尝试修复",
+                    failure_prefix=f"execute_sql 未知列 {unknown_col} 修复失败",
+                    validation_error=exec_error,
                 )
-                try:
-                    enforce_sql_rules(repaired_sql, max_limit=self.config.sql.max_limit)
-                except SqlGenerationError as exc:
-                    if _is_sensitive_sql_error(exc) and sensitive_terms:
-                        return _sensitive_query_only_result(sensitive_terms)
-                    return _query_only_result()
-                normalized_sql = self._validate_sql(context, user_question, repaired_sql, raise_on_error=True)
-        if normalized_sql is None:
-            raise RuntimeError("SQL validation failed")
-        if sql_cache is not None and cached_sql is None and not is_low_quality_sql_for_question(sql_question, normalized_sql):
-            sql_cache.set(question=sql_question, schema_version=schema_version, sql=normalized_sql)
-        result = self._execute_sql(context, user_question, normalized_sql)
-        answer = render_result(user_question, result, result_format)
+                if repaired_exec_sql is not None:
+                    prior_exec_sql = repaired_exec_sql
+                    if query_plan:
+                        repaired_exec_sql = apply_time_range_filters_from_plan(repaired_exec_sql, query_plan)
+                    if schema is not None:
+                        repaired_exec_sql = apply_time_range_filters_from_question(repaired_exec_sql, time_range_question, schema)
+                    if repaired_exec_sql != prior_exec_sql:
+                        repaired_exec_sql, schema_fail = _repair_sql_for_local_schema_issues(
+                            candidate_sql=repaired_exec_sql,
+                            sql_question=sql_question,
+                            schema=schema,
+                            generator=generator,
+                            schema_context=schema_context,
+                            sql_schema_context=sql_schema_context,
+                            audit_logger=self.audit_logger,
+                            session_id=context.session_id,
+                            max_repair_attempts=self.config.sql.max_repair_attempts,
+                            default_limit=self.config.sql.default_limit,
+                            max_limit=self.config.sql.max_limit,
+                            steps=steps,
+                            repair_success_detail="execute 修复补充时间范围后已修复本地 schema 校验问题。",
+                            running_prefix="execute 修复补充时间范围后本地 schema 校验失败，尝试修复",
+                        )
+                        if schema_fail:
+                            steps.error(10, schema_fail)
+                            return _attach_execution_steps(_query_only_result(schema_fail), steps)
+                    try:
+                        revalidated = self._validate_sql(context, user_question, repaired_exec_sql)
+                    except Exception as validate_exc:
+                        reason = f"{type(validate_exc).__name__}: {validate_exc}"
+                        steps.error(10, reason)
+                        return _attach_execution_steps(_query_only_result(reason), steps)
+                    if revalidated is not None:
+                        try:
+                            result = self._execute_sql(context, user_question, revalidated)
+                            normalized_sql = revalidated
+                            repaired_sql = repaired_exec_sql
+                            steps.done(11, f"execute_sql 完成，rowCount={result.get('rowCount')}")
+                        except Exception as retry_exc:
+                            reason = f"{type(retry_exc).__name__}: {retry_exc}"
+                            steps.error(11, reason)
+                            return _attach_execution_steps(_query_only_result(reason), steps)
+                    else:
+                        reason = (
+                            f"execute 未知列修复后 validate_sql 失败："
+                            f"{_validation_error_message(self._last_validation_result)}"
+                        )
+                        steps.error(10, reason)
+                        return _attach_execution_steps(_query_only_result(reason), steps)
+                else:
+                    reason = fail_reason or f"{type(exc).__name__}: {exc}"
+                    steps.error(11, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+            else:
+                reason = f"{type(exc).__name__}: {exc}"
+                steps.error(11, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+        else:
+            steps.done(11, f"execute_sql 完成，rowCount={result.get('rowCount')}")
+        result = self._ensure_limited_flag(result)
+        steps.running(12)
+        try:
+            if sampler is not None:
+                answer = render_result_with_llm(
+                    question=user_question,
+                    result=result,
+                    agent_instructions=getattr(schema_context, "agent_instructions", []) or [],
+                    sampler=sampler,
+                    result_format=result_format,
+                )
+            else:
+                answer = render_result(user_question, result, result_format)
+        except Exception as exc:
+            reason = f"{type(exc).__name__}: {exc}"
+            steps.error(12, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        if query_plan:
+            answer = ensure_query_plan_summary_answer(answer, user_question, result_format, query_plan)
+        export_notice = _csv_export_notice(user_question, result)
+        if export_notice:
+            answer = _append_default_limit_notice(
+                answer,
+                user_question,
+                result_format,
+                export_notice,
+            )
         if _should_append_default_limit_notice(
             question=sql_question,
             result=result,
@@ -372,13 +924,17 @@ class SpongeAgent:
                 result_format,
                 _sensitive_field_notice(sensitive_terms),
             )
-        return QueryResult(
+        steps.done(12, "LLM 已渲染结果并返回。" if sampler is not None else "结果已渲染并返回。")
+        return _attach_execution_steps(QueryResult(
             answer=answer,
             generated_sql=generated.sql,
             normalized_sql=normalized_sql,
             repaired_sql=repaired_sql,
             validation=self._last_validation_result,
-        )
+            query_plan=query_plan,
+            raw_result=result,
+            result_format=result_format,
+        ), steps)
 
     def _ensure_schema(self) -> dict[str, Any]:
         cached_schema = self.schema_cache.load()
@@ -429,6 +985,84 @@ class SpongeAgent:
             return cached_schema
         raise RuntimeError("Sponge get_schema did not return tables and no local schema cache exists")
 
+    def _search_entities_for_question(
+        self,
+        context: UserContext,
+        question: str,
+        schema_context: Any,
+        schema: dict[str, Any],
+        *,
+        sampler: Sampler | None = None,
+        analysis: QuestionAnalysis | None = None,
+    ) -> dict[str, Any] | None:
+        search_candidates, schema_candidates = _collect_entity_resolution_candidates(
+            question,
+            schema,
+            schema_context,
+            sampler,
+            agent_instructions=getattr(schema_context, "agent_instructions", []) or [],
+            analysis=analysis,
+        )
+        if not search_candidates and not schema_candidates:
+            return None
+
+        search_results: list[dict[str, Any]] = []
+        for candidate in search_candidates:
+            entity_type = str(candidate.get("type") or "")
+            name = str(candidate.get("value") or "")
+            if not entity_type or not name:
+                continue
+            trace_id = new_trace_id("trace_entity")
+            try:
+                response = self.mcp_client.search_entities(
+                    trace_id=trace_id,
+                    session_id=context.session_id,
+                    entity_types=[entity_type],
+                    name=name,
+                )
+            except AttributeError:
+                break
+            except Exception as exc:
+                self.audit_logger.log(
+                    {
+                        "traceId": trace_id,
+                        "sessionId": context.session_id,
+                        "question": question,
+                        "tool": "search_entities",
+                        "entityType": entity_type,
+                        "name": name,
+                        "error": f"{type(exc).__name__}: {exc}",
+                    }
+                )
+                continue
+            self.audit_logger.log(
+                {
+                    "traceId": trace_id,
+                    "sessionId": context.session_id,
+                    "question": question,
+                    "tool": "search_entities",
+                    "entityType": entity_type,
+                    "name": name,
+                    "matchedCount": len(_flatten_entity_search_items(response)),
+                }
+            )
+            search_results.append(
+                {
+                    "candidate": candidate,
+                    "searchedName": name,
+                    "entityType": entity_type,
+                    "response": response,
+                }
+            )
+        return {
+            "traceId": search_results[0]["response"].get("traceId") if search_results else "",
+            "searchedName": search_candidates[0].get("value") or "" if search_candidates else "",
+            "entityCandidates": search_candidates,
+            "schemaCandidates": schema_candidates,
+            "searchResults": search_results,
+            "entities": _merge_entity_search_results(search_results),
+        }
+
     def _validate_sql(
         self,
         context: UserContext,
@@ -467,6 +1101,38 @@ class SpongeAgent:
         self._last_validation_trace_id = trace_id
         return str(result.get("normalizedSql") or sql)
 
+    def _validation_error_code(self) -> str | None:
+        error = self._last_validation_error
+        if isinstance(error, dict):
+            code = error.get("code")
+            return str(code) if code else None
+        return None
+
+    def _ensure_limited_flag(self, result: dict[str, Any]) -> dict[str, Any]:
+        """Derive `limited` from the validate-stage LIMIT when execute omits it.
+
+        MCP execute_sql does not return a `limited` flag (alignment checklist
+        supplementary #1); the agreed approach is to infer it client-side from
+        the LIMIT that validate_sql parsed. The ceiling is never hardcoded here:
+        the value always comes from MCP's validate response.
+        """
+        if "limited" in result:
+            return result
+        limit: int | None = None
+        if isinstance(self._last_validation_result, dict):
+            raw_limit = self._last_validation_result.get("limit")
+            if isinstance(raw_limit, int) and not isinstance(raw_limit, bool):
+                limit = raw_limit
+        if limit is None:
+            return result
+        row_count = result.get("rowCount")
+        if row_count is None:
+            rows = result.get("rows")
+            row_count = len(rows) if isinstance(rows, list) else None
+        if not isinstance(row_count, int):
+            return result
+        return {**result, "limited": row_count >= limit}
+
     def _execute_sql(self, context: UserContext, question: str, sql: str) -> dict[str, Any]:
         if self._last_validation_trace_id is None:
             raise RuntimeError("SQL execution requires a prior successful validate_sql trace")
@@ -497,40 +1163,2871 @@ class SpongeAgent:
         return result
 
 
-def _strip_result_format_instruction(question: str) -> str:
-    cleaned = question
-    patterns = [
-        r"^\s*返回\s*(?:json|yaml|html|markdown|md)\s*格式\s*的?",
-        r"[，,。；;]?\s*输出\s*(?:json|yaml|html|markdown|md)\s*(?:格式)?",
-        r"[，,。；;]?\s*用\s*表格\s*展示",
-        r"[，,。；;]?\s*以\s*(?:json|yaml|html|markdown|md)\s*(?:格式)?\s*输出",
-        r"[，,。；;]?\s*return\s+(?:json|yaml|html|markdown|md)",
-    ]
-    for pattern in patterns:
-        cleaned = re.sub(pattern, "", cleaned, flags=re.IGNORECASE)
-    return cleaned.strip() or question
+class _ExecutionSteps:
+    def __init__(self) -> None:
+        self.steps: list[dict[str, Any]] = [
+            {"step": 1, "name": "接收 query_sponge 调用", "status": "pending"},
+            {"step": 2, "name": "LLM 需求分析", "status": "pending"},
+            {"step": 3, "name": "获取 schema", "status": "pending"},
+            {"step": 4, "name": "按读取顺序匹配 schemaContext", "status": "pending"},
+            {"step": 5, "name": "识别并确认实体", "status": "pending"},
+            {"step": 6, "name": "生成并确认查询计划", "status": "pending"},
+            {"step": 7, "name": "按 policy 和 schemaContext 生成 SQL", "status": "pending"},
+            {"step": 8, "name": "生成后按 policy 复查 SQL", "status": "pending"},
+            {"step": 9, "name": "修复 SQL", "status": "pending"},
+            {"step": 10, "name": "调用 validate_sql", "status": "pending"},
+            {"step": 11, "name": "调用 execute_sql", "status": "pending"},
+            {"step": 12, "name": "LLM 渲染并返回结果", "status": "pending"},
+        ]
 
+    def running(self, step: int, detail: str | None = None) -> None:
+        self._set(step, "running", detail=detail)
 
-def _query_only_result() -> QueryResult:
-    return QueryResult(
-        answer="已按当前 schema 判断，目前不支持该查询",
-        generated_sql="",
-        normalized_sql="",
-        repaired_sql=None,
-        validation={},
+    def done(self, step: int, detail: str | None = None) -> None:
+        self._set(step, "done", detail=detail)
+
+    def waiting(self, step: int, detail: str | None = None) -> None:
+        self._set(step, "waiting", detail=detail)
+
+    def skipped(self, step: int, detail: str | None = None) -> None:
+        self._set(step, "skipped", detail=detail)
+
+    def error(self, step: int, reason: str) -> None:
+        self._set(step, "error", detail=reason, error=reason)
+
+    def snapshot(self) -> list[dict[str, Any]]:
+        return [dict(step) for step in self.steps]
+
+    def _set(self, step: int, status: str, *, detail: str | None = None, error: str | None = None) -> None:
+        for item in self.steps:
+            if item["step"] != step:
+                continue
+            item["status"] = status
+            if detail:
+                item["detail"] = detail
+            if error:
+                item["error"] = error
+            return
+
+
+def _attach_execution_steps(result: QueryResult, steps: _ExecutionSteps) -> QueryResult:
+    snapshot = steps.snapshot()
+    return QueryResult(
+        answer=result.answer,
+        generated_sql=result.generated_sql,
+        normalized_sql=result.normalized_sql,
+        repaired_sql=result.repaired_sql,
+        validation=result.validation,
+        needs_clarification=result.needs_clarification,
+        clarification_type=result.clarification_type,
+        clarification_payload=result.clarification_payload,
+        query_plan=result.query_plan,
+        execution_steps=snapshot,
+    )
+
+
+def _schema_context_step_detail(schema_context: Any) -> str:
+    parts = [
+        ("agentInstructions", getattr(schema_context, "agent_instructions", []) or []),
+        ("policy", getattr(schema_context, "policy", []) or []),
+        ("glossary", getattr(schema_context, "glossary_terms", []) or []),
+        ("schema.tables", getattr(schema_context, "tables", []) or []),
+        ("businessTerms", getattr(schema_context, "business_terms", []) or []),
+        ("concepts", getattr(schema_context, "concepts", []) or []),
+        ("metrics", getattr(schema_context, "metrics", []) or []),
+        ("tableDefaults", getattr(schema_context, "default_filters", []) or []),
+        ("joins", getattr(schema_context, "manual_joins", []) or []),
+        ("structure.relations", getattr(schema_context, "inferred_relations", []) or []),
+        ("example.joinPattern", getattr(schema_context, "example_join_patterns", []) or []),
+        ("enums", getattr(schema_context, "enums", []) or []),
+    ]
+    return "；".join(f"{name}={len(value) if isinstance(value, list) else 0}" for name, value in parts)
+
+
+def _entity_search_step_detail(searched_entities: dict[str, Any] | None) -> str:
+    if not searched_entities:
+        return "未发现需要远程确认的实体。"
+    items = _flatten_entity_search_items(searched_entities)
+    schema_count = len(searched_entities.get("schemaCandidates") or [])
+    return f"search_entities 返回 {len(items)} 个候选；schema 路径 {schema_count} 个实体。"
+
+
+def _sql_generation_clarification_result(
+    question: str,
+    generated: GeneratedSql,
+    query_plan: dict[str, Any] | None = None,
+) -> QueryResult | None:
+    clarification = generated.clarification
+    if not isinstance(clarification, dict):
+        return None
+    clarification_type = str(clarification.get("type") or "")
+    if clarification_type == "status_enum_confirmation":
+        return None
+    if clarification_type == "status_enum_missing":
+        return None
+    return None
+
+
+def _validation_error_message(validation: dict[str, Any] | None) -> str:
+    if not isinstance(validation, dict):
+        return ""
+    error = validation.get("error")
+    if not isinstance(error, dict):
+        return ""
+    code = str(error.get("code") or "")
+    message = str(error.get("message") or error.get("detail") or "")
+    if code and message:
+        return f"{code}: {message}"
+    return code or message
+
+
+def _build_query_plan(
+    question: str,
+    schema_context: Any,
+    schema: dict[str, Any],
+    *,
+    searched_entities: dict[str, Any] | None = None,
+    sampler: Sampler | None = None,
+    time_range_question: str | None = None,
+    analysis: QuestionAnalysis | None = None,
+) -> dict[str, Any]:
+    tables = _query_plan_tables(getattr(schema_context, "tables", []) or [])
+    fields = _query_plan_fields(question, getattr(schema_context, "tables", []) or [])
+    # Extract open-valued entities once (schema-driven LLM), reused by both
+    # filters and entities so the two views never diverge.
+    question_entities = _extract_question_entities(
+        question,
+        schema,
+        sampler,
+        agent_instructions=getattr(schema_context, "agent_instructions", []) or [],
+        analysis=analysis,
+    )
+    selected_concepts = match_concepts_for_question(getattr(schema_context, "concepts", []) or [], question)
+    filters = _query_plan_filters(
+        question,
+        schema_context,
+        searched_entities=searched_entities,
+        question_entities=question_entities if searched_entities is None else None,
+        schema=schema,
+        time_range_question=time_range_question or question,
+        selected_concepts=selected_concepts,
+        analysis=analysis,
+    )
+    entities = _query_plan_entities(
+        question,
+        schema_context,
+        searched_entities=searched_entities,
+        question_entities=question_entities if searched_entities is None else None,
+        analysis=analysis,
+    )
+    plan = {
+        "question": question,
+        "schemaVersion": schema.get("schemaVersion"),
+        "steps": [
+            {"step": 1, "name": "上层 Agent 调用 query_sponge", "status": "done"},
+            {"step": 2, "name": "判断用户意图是查询", "status": "done"},
+            {"step": 3, "name": "按 schema 中文语义匹配表、字段、筛选条件", "status": "done"},
+            {"step": 4, "name": "固化查询计划并直接执行", "status": "done"},
+            {"step": 5, "name": "按表关联关系组合单条 SQL", "status": "pending"},
+            {"step": 6, "name": "按 schema 补充筛选条件和枚举值", "status": "pending"},
+            {"step": 7, "name": "检查 SELECT、WHERE、LIKE、枚举和单 SQL 要求", "status": "pending"},
+            {"step": 8, "name": "调用 validate_sql 校验 SQL", "status": "pending"},
+            {"step": 9, "name": "同 traceId 调用 execute_sql 执行", "status": "pending"},
+            {"step": 10, "name": "检查结果是否符合口径", "status": "pending"},
+            {"step": 11, "name": "按指定格式渲染结果", "status": "pending"},
+            {"step": 12, "name": "返回 content 和 structuredContent.answer", "status": "pending"},
+        ],
+        "tables": tables,
+        "fields": fields,
+        "filters": filters,
+        "entities": entities,
+        "matchedConcepts": [
+            {
+                "name": str(concept.get("name") or ""),
+                "comment": str(concept.get("comment") or ""),
+            }
+            for concept in selected_concepts
+        ],
+    }
+    _ensure_query_plan_concept_required_tables(plan, selected_concepts)
+    _ensure_query_plan_bridge_tables(plan)
+    _ensure_query_plan_entity_display_fields(plan)
+    return plan
+
+
+def _ensure_query_plan_concept_required_tables(plan: dict[str, Any], concepts: list[dict[str, Any]]) -> None:
+    """Pin concept.requiredTables onto the query plan."""
+    tables = plan.get("tables")
+    if not isinstance(tables, list):
+        tables = []
+        plan["tables"] = tables
+    names = {str(item.get("name") or "") for item in tables if isinstance(item, dict)}
+    names.discard("")
+    for concept in concepts:
+        if not isinstance(concept, dict):
+            continue
+        for table_name in concept.get("requiredTables") or []:
+            table = str(table_name or "").strip()
+            if not table or table in names:
+                continue
+            tables.append(
+                {
+                    "name": table,
+                    "description": str(concept.get("comment") or concept.get("description") or ""),
+                    "source": "schema.concepts",
+                }
+            )
+            names.add(table)
+
+
+def _ensure_query_plan_bridge_tables(plan: dict[str, Any]) -> None:
+    """Pin bridge tables implied by entity/filter semantics onto the plan."""
+    tables = plan.get("tables")
+    if not isinstance(tables, list):
+        return
+    names = {str(item.get("name") or "") for item in tables if isinstance(item, dict)}
+    names.discard("")
+    job_tables = {"job", "job_basic_info", "job_address", "job_store", "job_hiring_requirement"}
+    has_store = "store" in names
+    if not has_store:
+        for flt in plan.get("filters") or []:
+            if isinstance(flt, dict) and str(flt.get("field") or "").startswith("store."):
+                has_store = True
+                break
+    if not has_store:
+        for entity in plan.get("entities") or []:
+            if isinstance(entity, dict) and str(entity.get("type") or "") == "store":
+                has_store = True
+                break
+    if has_store and names.intersection(job_tables) and "job_store" not in names:
+        tables.append(
+            {
+                "name": "job_store",
+                "description": "岗位门店关系持久化对象。 对应表：job_store。",
+                "source": "schema.planRules",
+            }
+        )
+
+
+def _ensure_query_plan_entity_display_fields(plan: dict[str, Any]) -> None:
+    """Require display names for OR-matched entity dimensions."""
+    fields = plan.get("fields")
+    if not isinstance(fields, list):
+        fields = []
+        plan["fields"] = fields
+    existing = {
+        (str(item.get("table") or ""), str(item.get("field") or ""))
+        for item in fields
+        if isinstance(item, dict)
+    }
+    for flt in plan.get("filters") or []:
+        if not isinstance(flt, dict):
+            continue
+        if str(flt.get("source") or "") != "search_entities":
+            continue
+        if not str(flt.get("logicalGroup") or ""):
+            continue
+        field = str(flt.get("field") or "")
+        if "." not in field:
+            continue
+        table_name, column_name = field.split(".", 1)
+        if column_name != "name":
+            continue
+        key = (table_name, column_name)
+        label = _query_plan_filter_field_label(field)
+        description = f"{label}名称" if label else "实体名称"
+        if key in existing:
+            for item in fields:
+                if not isinstance(item, dict):
+                    continue
+                if (str(item.get("table") or ""), str(item.get("field") or "")) != key:
+                    continue
+                item["required"] = True
+                item["source"] = "search_entities"
+                if not item.get("description"):
+                    item["description"] = description
+                break
+            continue
+        fields.append(
+            {
+                "table": table_name,
+                "field": column_name,
+                "description": description,
+                "source": "search_entities",
+                "required": True,
+            }
+        )
+        existing.add(key)
+
+
+def _query_plan_tables(tables: list[dict[str, Any]]) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    for table in tables[:10]:
+        if not isinstance(table, dict):
+            continue
+        name = str(table.get("tableName") or table.get("name") or "")
+        if not name:
+            continue
+        result.append(
+            {
+                "name": name,
+                "description": str(table.get("comment") or table.get("description") or ""),
+                "source": "schema.tables",
+            }
+        )
+    return result
+
+
+def _question_requests_id_field(question: str) -> bool:
+    lowered = question.lower()
+    return "id" in lowered or "编号" in question or "主键" in question
+
+
+def _is_query_plan_id_column(column_name: str) -> bool:
+    lowered = column_name.lower()
+    return lowered == "id" or lowered.endswith("_id")
+
+
+def _is_query_plan_display_column(column_name: str) -> bool:
+    lowered = column_name.lower()
+    if lowered in {"name", "info", "title", "text", "remark", "remarks", "desc", "description", "job_name", "nick_name", "status"}:
+        return True
+    return lowered.endswith("_name") or lowered.endswith("_info") or lowered.endswith("_text")
+
+
+def _query_plan_field_description(column: dict[str, Any], description: str) -> str:
+    enum = column.get("enum")
+    if not isinstance(enum, dict):
+        return description
+    values = enum.get("values")
+    if not isinstance(values, list):
+        return description
+    labels = [str(item.get("label") or "").strip() for item in values if isinstance(item, dict) and item.get("label")]
+    if not labels:
+        return description
+    preview = "、".join(labels[:5])
+    if len(labels) > 5:
+        preview += "..."
+    suffix = f"（枚举：{preview}）"
+    return f"{description}{suffix}" if description else suffix
+
+
+def _query_plan_fields(question: str, tables: list[dict[str, Any]]) -> list[dict[str, str]]:
+    allow_id = _question_requests_id_field(question)
+    tokens = _query_plan_tokens(question)
+    matched: list[tuple[int, dict[str, str]]] = []
+    fallback: list[dict[str, str]] = []
+    for table in tables:
+        if not isinstance(table, dict):
+            continue
+        table_name = str(table.get("tableName") or table.get("name") or "")
+        columns = table.get("columns", [])
+        if not isinstance(columns, list):
+            continue
+        for column in columns:
+            if not isinstance(column, dict):
+                continue
+            column_name = str(column.get("columnName") or column.get("name") or "")
+            if not column_name:
+                continue
+            description = _query_plan_field_description(
+                column,
+                str(column.get("comment") or column.get("description") or ""),
+            )
+            field = {
+                "table": table_name,
+                "field": column_name,
+                "description": description,
+                "source": "schema.columns",
+            }
+            text = f"{table_name} {column_name} {description}".lower()
+            score = sum(1 for token in tokens if token and token in text)
+            if score > 0:
+                if _is_query_plan_display_column(column_name):
+                    score += 2
+                if not allow_id and _is_query_plan_id_column(column_name):
+                    score -= 50
+                if score > 0:
+                    matched.append((score, field))
+            elif not allow_id and _is_query_plan_id_column(column_name):
+                continue
+            elif column_name in {"name", "job_name", "status", "info", "create_at", "created_at"} or _is_query_plan_display_column(column_name):
+                fallback.append(field)
+            elif allow_id and column_name == "id":
+                fallback.append(field)
+    matched.sort(key=lambda item: item[0], reverse=True)
+    fields = [field for _, field in matched[:12]]
+    if not fields:
+        fields = fallback[:8]
+    return fields
+
+
+def _schema_context_has_semantic_match(question: str, schema_context: Any) -> bool:
+    if any(getattr(schema_context, attr, []) for attr in ("business_terms", "concepts", "metrics", "examples")):
+        return True
+    tokens = _schema_match_tokens(question)
+    if not tokens:
+        return bool(getattr(schema_context, "tables", []) or [])
+    for table in getattr(schema_context, "tables", []) or []:
+        if not isinstance(table, dict):
+            continue
+        text = _schema_table_search_text(table)
+        if any(token in text for token in tokens):
+            return True
+    if getattr(schema_context, "tables", None) and _has_query_intent(question):
+        return True
+    return False
+
+
+def _schema_match_tokens(question: str) -> list[str]:
+    ignored = {
+        "查询",
+        "查看",
+        "看看",
+        "搜索",
+        "统计",
+        "多少",
+        "几个",
+        "几条",
+        "哪些",
+        "有哪些",
+        "列表",
+        "明细",
+        "数据",
+        "目前",
+        "当前",
+        "现在",
+        "帮我",
+        "一下",
+        "返回",
+        "输出",
+    }
+    tokens = []
+    for token in _query_plan_tokens(question):
+        if token in ignored or len(token) < 2:
+            continue
+        tokens.append(token)
+    return list(dict.fromkeys(tokens))
+
+
+def _schema_table_search_text(table: dict[str, Any]) -> str:
+    parts = [
+        str(table.get("tableName") or table.get("name") or ""),
+        str(table.get("comment") or table.get("description") or ""),
+    ]
+    columns = table.get("columns")
+    if isinstance(columns, list):
+        for column in columns:
+            if isinstance(column, dict):
+                parts.extend(
+                    str(column.get(key) or "")
+                    for key in ("columnName", "name", "comment", "description", "dataType", "type")
+                )
+    return " ".join(parts).lower()
+
+
+def _schema_entity_candidates(question: str, schema_context: Any) -> list[dict[str, str]]:
+    return _dedupe_schema_entity_candidates(_schema_generic_entity_candidates(question, schema_context))
+
+
+def _search_entity_type_for_maps_to(maps_to: str) -> str | None:
+    return _MAPS_TO_SEARCH_ENTITY_TYPE.get(maps_to)
+
+
+def _search_maps_to_for_entity_type(entity_type: str) -> str:
+    reverse = {
+        "brand": "brand",
+        "project": "sponge_project",
+        "province": "province",
+        "city": "city",
+        "region": "region",
+    }
+    return reverse.get(entity_type, entity_type)
+
+
+def _entity_table_name_column(maps_to: str, schema: dict[str, Any]) -> str | None:
+    table_name = maps_to.strip()
+    if not table_name:
+        return None
+    for table in schema.get("tables", []):
+        if not isinstance(table, dict):
+            continue
+        current = str(table.get("tableName") or table.get("name") or "")
+        if current != table_name:
+            continue
+        columns = table.get("columns")
+        if not isinstance(columns, list):
+            break
+        preferred: list[str] = []
+        fallback: list[str] = []
+        for column in columns:
+            if not isinstance(column, dict):
+                continue
+            column_name = str(column.get("columnName") or column.get("name") or "")
+            if not column_name or _is_identifier_column(column_name):
+                continue
+            comment = str(column.get("comment") or column.get("description") or "")
+            if column_name in {"name", "nick_name", "job_name"} or "名称" in comment:
+                preferred.append(column_name)
+            else:
+                fallback.append(column_name)
+        chosen = (preferred or fallback or ["name"])[0]
+        return f"{table_name}.{chosen}"
+    return f"{table_name}.name"
+
+
+def _resolve_query_plan_filter_field(field: str, schema: dict[str, Any] | None) -> str:
+    if not field or "." in field or schema is None:
+        return field
+    for item in _entity_catalog(schema):
+        if item["filterField"] == field:
+            return _entity_table_name_column(item["type"], schema) or field
+    return field
+
+
+def _looks_like_store_name(value: str) -> bool:
+    cleaned = value.strip()
+    if not cleaned:
+        return False
+    if re.search(r"PS\d", cleaned, re.IGNORECASE):
+        return True
+    return any(marker in cleaned for marker in _STORE_NAME_MARKERS)
+
+
+def _looks_like_region_name(value: str) -> bool:
+    cleaned = value.strip()
+    if not cleaned or _looks_like_store_name(cleaned):
+        return False
+    if re.search(r"\d", cleaned):
+        return False
+    return cleaned.endswith(("区", "县", "旗")) and len(cleaned) <= 12
+
+
+def _looks_like_city_name(value: str) -> bool:
+    cleaned = value.strip()
+    if not cleaned or _looks_like_store_name(cleaned) or _looks_like_region_name(cleaned):
+        return False
+    if re.search(r"\d", cleaned):
+        return False
+    if cleaned.endswith(("里", "村", "镇")):
+        return False
+    if cleaned.endswith("市") and len(cleaned) <= 8:
+        return True
+    return 2 <= len(cleaned) <= 4
+
+
+def _city_name_filter_values(name: str) -> list[str]:
+    cleaned = name.strip()
+    if not cleaned:
+        return []
+    if cleaned.endswith("市"):
+        base = cleaned[:-1]
+        return list(dict.fromkeys([base, cleaned]))
+    return list(dict.fromkeys([cleaned, f"{cleaned}市"]))
+
+
+def _region_name_filter_values(name: str) -> list[str]:
+    cleaned = name.strip()
+    if not cleaned:
+        return []
+    if cleaned.endswith("区"):
+        base = cleaned[:-1]
+        return list(dict.fromkeys([cleaned, base]))
+    if cleaned.endswith("县"):
+        base = cleaned[:-1]
+        return list(dict.fromkeys([cleaned, base]))
+    return [cleaned]
+
+
+def _promote_region_search_candidate(
+    search_candidates: list[dict[str, str]],
+    schema_candidates: list[dict[str, str]],
+    *,
+    value: str,
+    schema: dict[str, Any],
+    seen_search: set[tuple[str, str]],
+) -> None:
+    field = _entity_table_name_column("region", schema) or "region.name"
+    key = ("region", value)
+    if key in seen_search:
+        return
+    seen_search.add(key)
+    search_candidates.append(
+        {
+            "type": "region",
+            "label": "区域",
+            "value": value,
+            "field": field,
+            "mapsTo": "region",
+            "source": "search_entities.candidate",
+        }
+    )
+    schema_candidates[:] = [
+        item
+        for item in schema_candidates
+        if not (
+            str(item.get("type") or "") in {"city", "store"}
+            and str(item.get("value") or "") == value
+        )
+    ]
+    search_candidates[:] = [
+        item
+        for item in search_candidates
+        if not (
+            str(item.get("type") or "") == "city"
+            and str(item.get("value") or "") == value
+        )
+    ]
+
+
+def _promote_city_search_candidate(
+    search_candidates: list[dict[str, str]],
+    schema_candidates: list[dict[str, str]],
+    *,
+    value: str,
+    schema: dict[str, Any],
+    seen_search: set[tuple[str, str]],
+) -> None:
+    field = _entity_table_name_column("city", schema) or "city.name"
+    key = ("city", value)
+    if key in seen_search:
+        return
+    seen_search.add(key)
+    search_candidates.append(
+        {
+            "type": "city",
+            "label": "城市",
+            "value": value,
+            "field": field,
+            "mapsTo": "city",
+            "source": "search_entities.candidate",
+        }
+    )
+    schema_candidates[:] = [
+        item
+        for item in schema_candidates
+        if not (str(item.get("type") or "") == "store" and str(item.get("value") or "") == value)
+    ]
+
+
+def _extract_region_tokens(question: str) -> list[str]:
+    tokens: list[str] = []
+    for match in re.finditer(r"([\u4e00-\u9fff]{2,4})区", question):
+        district = match.group(0)
+        tokens.append(district)
+        core = match.group(1)
+        for size in (2, 3):
+            if len(core) >= size:
+                suffix = f"{core[-size:]}区"
+                if _looks_like_region_name(suffix):
+                    tokens.append(suffix)
+    return list(dict.fromkeys(tokens))
+
+
+def _expand_brand_project_search_candidates(
+    search_candidates: list[dict[str, str]],
+    llm_values: dict[str, Any],
+    schema: dict[str, Any],
+    seen_search: set[tuple[str, str]],
+) -> None:
+    """Brand/project names are often ambiguous; search both when only one slot is filled."""
+    if _explicit_brand_or_project_types(llm_values):
+        return
+    brand_value = _normalize_entity_search_value("brand", str(llm_values.get("brand") or "").strip())
+    project_value = _normalize_entity_search_value(
+        "sponge_project",
+        str(llm_values.get("sponge_project") or "").strip(),
+    )
+    expansions: list[tuple[str, str, str]] = []
+    if brand_value and not project_value:
+        expansions.append(("project", brand_value, "sponge_project"))
+    if project_value and not brand_value:
+        expansions.append(("brand", project_value, "brand"))
+    for search_type, value, maps_to in expansions:
+        key = (search_type, value)
+        if key in seen_search:
+            continue
+        seen_search.add(key)
+        field = _entity_table_name_column(maps_to, schema) or f"{maps_to}.name"
+        search_candidates.append(
+            {
+                "type": search_type,
+                "label": _entity_type_label(search_type),
+                "value": value,
+                "field": field,
+                "mapsTo": maps_to,
+                "source": "search_entities.candidate",
+            }
+        )
+
+
+def _explicit_brand_or_project_types(llm_values: dict[str, Any]) -> set[str]:
+    explicit_types = llm_values.get(_EXPLICIT_ENTITY_TYPES_KEY)
+    if not isinstance(explicit_types, list):
+        return set()
+    return {str(item) for item in explicit_types if str(item) in {"brand", "sponge_project"}}
+
+
+def _reconcile_location_entity_candidates(
+    question: str,
+    search_candidates: list[dict[str, str]],
+    schema_candidates: list[dict[str, str]],
+    schema: dict[str, Any],
+) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
+    """Move location tokens onto city/region search paths; keep store for store-like names."""
+    seen_search = {(str(item.get("type") or ""), str(item.get("value") or "")) for item in search_candidates}
+    for token in _extract_region_tokens(question):
+        if _looks_like_region_name(token):
+            _promote_region_search_candidate(
+                search_candidates,
+                schema_candidates,
+                value=token,
+                schema=schema,
+                seen_search=seen_search,
+            )
+    for candidate in list(schema_candidates):
+        value = str(candidate.get("value") or "").strip()
+        if not value:
+            continue
+        if _looks_like_region_name(value):
+            _promote_region_search_candidate(
+                search_candidates,
+                schema_candidates,
+                value=value,
+                schema=schema,
+                seen_search=seen_search,
+            )
+            continue
+        if str(candidate.get("type") or "") != "store":
+            continue
+        if _looks_like_city_name(value):
+            _promote_city_search_candidate(
+                search_candidates,
+                schema_candidates,
+                value=value,
+                schema=schema,
+                seen_search=seen_search,
+            )
+    for candidate in list(search_candidates):
+        value = str(candidate.get("value") or "").strip()
+        if not value:
+            continue
+        if str(candidate.get("type") or "") == "city" and _looks_like_region_name(value):
+            search_candidates.remove(candidate)
+            _promote_region_search_candidate(
+                search_candidates,
+                schema_candidates,
+                value=value,
+                schema=schema,
+                seen_search=seen_search,
+            )
+            continue
+        if str(candidate.get("type") or "") != "store":
+            continue
+        if _looks_like_city_name(value):
+            search_candidates.remove(candidate)
+            _promote_city_search_candidate(
+                search_candidates,
+                schema_candidates,
+                value=value,
+                schema=schema,
+                seen_search=seen_search,
+            )
+    return search_candidates, schema_candidates
+
+
+def _collect_entity_resolution_candidates(
+    question: str,
+    schema: dict[str, Any],
+    schema_context: Any,
+    sampler: Sampler | None,
+    *,
+    agent_instructions: list[dict[str, Any]] | None = None,
+    analysis: QuestionAnalysis | None = None,
+) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
+    """Split entity mentions into search_entities candidates and schema-path candidates."""
+    search_candidates: list[dict[str, str]] = []
+    schema_candidates: list[dict[str, str]] = []
+    seen_search: set[tuple[str, str]] = set()
+    seen_schema: set[tuple[str, str]] = set()
+
+    catalog = _entity_catalog(schema)
+    llm_values: dict[str, Any] = {}
+    if sampler is not None and catalog:
+        llm_values = _llm_extract_entity_values(question, catalog, sampler, agent_instructions)
+    llm_values = _merge_analysis_entity_candidates_into_llm_values(llm_values, analysis, catalog)
+    _drop_implicit_location_values_inside_named_entities(llm_values)
+    for item in catalog:
+        value = llm_values.get(item["type"]) or _extract_value_near_label(question, item["label"])
+        if not value:
+            continue
+        value = _normalize_entity_search_value(item["type"], value)
+        if _is_analysis_noise_value(value, analysis):
+            continue
+        search_type = _search_entity_type_for_maps_to(item["type"])
+        field = _entity_table_name_column(item["type"], schema) or item["filterField"]
+        if search_type:
+            key = (search_type, value)
+            if key in seen_search:
+                continue
+            seen_search.add(key)
+            search_candidates.append(
+                {
+                    "type": search_type,
+                    "label": item["label"],
+                    "value": value,
+                    "field": field,
+                    "mapsTo": item["type"],
+                    "source": "search_entities.candidate",
+                }
+            )
+        else:
+            key = (item["type"], value)
+            if key in seen_schema:
+                continue
+            seen_schema.add(key)
+            schema_candidates.append(
+                {
+                    "type": item["type"],
+                    "label": item["label"],
+                    "value": value,
+                    "field": field,
+                    "mapsTo": item["type"],
+                    "source": "schema.businessTerms",
+                }
+            )
+
+    for candidate in _schema_generic_entity_candidates(question, schema_context):
+        field = str(candidate.get("field") or "")
+        value = str(candidate.get("value") or "")
+        key = (field, value)
+        if not value or key in seen_schema or _is_analysis_noise_value(value, analysis):
+            continue
+        seen_schema.add(key)
+        schema_candidates.append(candidate)
+
+    _expand_brand_project_search_candidates(search_candidates, llm_values, schema, seen_search)
+    search_candidates, schema_candidates = _reconcile_location_entity_candidates(
+        question,
+        search_candidates,
+        schema_candidates,
+        schema,
+    )
+    return search_candidates, schema_candidates
+
+
+def _schema_generic_entity_candidates(question: str, schema_context: Any) -> list[dict[str, str]]:
+    candidates: list[dict[str, str]] = []
+    for table in getattr(schema_context, "tables", []) or []:
+        if not isinstance(table, dict):
+            continue
+        table_name = str(table.get("tableName") or table.get("name") or "")
+        columns = table.get("columns")
+        if not isinstance(columns, list):
+            continue
+        for column in columns:
+            if not isinstance(column, dict):
+                continue
+            column_name = str(column.get("columnName") or column.get("name") or "")
+            if _is_identifier_column(column_name):
+                continue
+            if column_name.endswith("_ids") or column_name.endswith("_id_list"):
+                continue
+            label = _generic_schema_entity_label(column)
+            if not label or label not in question:
+                continue
+            value = _extract_value_near_label(question, label)
+            if not value:
+                continue
+            candidates.append(
+                {
+                    "type": table_name or column_name or label,
+                    "label": label,
+                    "value": value,
+                    "field": f"{table_name}.{column_name}" if table_name and column_name else f"{label}名称",
+                    "source": "schema.columns",
+                }
+            )
+    return candidates
+
+
+def _is_identifier_column(column_name: str) -> bool:
+    lowered = column_name.lower()
+    return lowered == "id" or lowered.endswith("_id")
+
+
+def _generic_schema_entity_label(column: dict[str, Any]) -> str:
+    raw = str(column.get("comment") or column.get("description") or "")
+    if not raw:
+        return ""
+    label = re.split(r"[\s,，。；;（(]", raw, maxsplit=1)[0]
+    label = re.sub(r"(名称|名字|姓名|编号|编码|ID|Id|id)$", "", label).strip()
+    if len(label) < 2 or len(label) > 12 or not _contains_cjk(label):
+        return ""
+    return label
+
+
+def _extract_value_near_label(question: str, label: str) -> str | None:
+    escaped = re.escape(label)
+    # The value char class intentionally excludes whitespace so the capture stops
+    # at the next token boundary instead of eating across words (e.g. it must not
+    # turn "项目：成都你六姐 门店：..." into "成都你六姐 门店").
+    value_class = r"[\u4e00-\u9fffA-Za-z0-9][\u4e00-\u9fffA-Za-z0-9_\-]{0,39}"
+    # A value is only trustworthy when an explicit connector links it to the label.
+    # A leading label with no connector usually means the label is the query subject,
+    # not a filter.
+    forward = re.search(rf"{escaped}\s*(?:名称|名字)?\s*(?:为|是|叫|名为|=|：|:)\s*({value_class})", question)
+    if forward is not None:
+        value = _clean_entity_value(_truncate_entity_value(forward.group(1)), label)
+        if value:
+            return value
+    # Reverse form "成都你六姐项目" is allowed, but reject captures that span a whole
+    # clause (still contain a connector verb) so the query subject noun does not pull
+    # in unrelated filter text.
+    reverse = re.search(rf"({value_class})\s*{escaped}", question)
+    if reverse is not None:
+        raw = _truncate_entity_value(_strip_leading_connectives(reverse.group(1)))
+        if not any(connector in raw for connector in ("为", "是", "=", "：", ":")):
+            value = _clean_entity_value(raw, label)
+            if value:
+                return value
+    return None
+
+
+# Chinese connective particles that mark the end of an entity value. They are CJK
+# characters, so the capture regex above would otherwise greedily consume them and
+# everything after a connector into one long phrase. We cut the value
+# at the first particle whose preceding segment already looks like a real value,
+# so multi-char names that legitimately contain the particle (e.g. "美的") survive.
+_ENTITY_VALUE_BOUNDARIES = "的及和与或"
+
+
+def _truncate_entity_value(value: str) -> str:
+    for index, char in enumerate(value):
+        if char in _ENTITY_VALUE_BOUNDARIES and index >= 2:
+            return value[:index]
+    return value
+
+
+def _strip_leading_connectives(value: str) -> str:
+    return value.lstrip(_ENTITY_VALUE_BOUNDARIES)
+
+
+def _contains_cjk(value: str) -> bool:
+    return bool(re.search(r"[\u4e00-\u9fff]", value))
+
+
+def _clean_entity_value(value: str, label: str = "") -> str:
+    cleaned = value.strip(" \t\r\n，,。；;？?！!（）()[]【】")
+    if label:
+        cleaned = cleaned.replace(label, " ")
+    for stop in (
+        "帮我查询",
+        "帮我查",
+        "查询",
+        "查看",
+        "看看",
+        "列出",
+        "返回",
+        "统计",
+        "有多少",
+        "有哪些",
+        "列表",
+        "明细",
+        "数据",
+        "目前",
+        "当前",
+        "现在",
+        "的",
+    ):
+        cleaned = cleaned.replace(stop, " ")
+    cleaned = re.sub(r"\s+", " ", cleaned).strip(" -_：:")
+    if len(cleaned) < 2:
+        return ""
+    return cleaned[:40]
+
+
+def _schema_entity_candidate(entity_type: str, value: str, source: str) -> dict[str, str]:
+    return {
+        "type": entity_type,
+        "label": _entity_type_label(entity_type),
+        "value": value,
+        "field": _entity_search_filter_field(entity_type),
+        "source": source,
+    }
+
+
+def _dedupe_schema_entity_candidates(candidates: list[dict[str, str]]) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for candidate in candidates:
+        key = (str(candidate.get("type") or ""), str(candidate.get("value") or ""))
+        if not key[0] or not key[1] or key in seen:
+            continue
+        seen.add(key)
+        result.append(candidate)
+    return result
+
+
+def _merge_entity_search_results(search_results: list[dict[str, Any]]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for search_result in search_results:
+        if not isinstance(search_result, dict):
+            continue
+        response = search_result.get("response")
+        if not isinstance(response, dict):
+            continue
+        entities = response.get("entities")
+        if not isinstance(entities, dict):
+            continue
+        for entity_type, group in entities.items():
+            if not isinstance(group, dict):
+                continue
+            target = merged.setdefault(str(entity_type), {key: group.get(key) for key in ("table", "idColumn", "nameColumn", "parentType")})
+            target.setdefault("items", [])
+            items = group.get("items")
+            if isinstance(items, list):
+                target["items"].extend(item for item in items if isinstance(item, dict))
+    return merged
+
+
+def _flatten_entity_search_items(search_response: dict[str, Any] | None) -> list[dict[str, str]]:
+    if not isinstance(search_response, dict):
+        return []
+    entities = search_response.get("entities")
+    if not isinstance(entities, dict):
+        return []
+    result: list[dict[str, str]] = []
+    for entity_type, group in entities.items():
+        if not isinstance(group, dict):
+            continue
+        items = group.get("items")
+        if not isinstance(items, list):
+            continue
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            name = str(item.get("name") or "")
+            if not name:
+                continue
+            aliases = item.get("aliases")
+            result.append(
+                {
+                    "type": str(entity_type),
+                    "id": str(item.get("id") or ""),
+                    "name": name,
+                    "aliases": "、".join(str(alias) for alias in aliases) if isinstance(aliases, list) else "",
+                    "pinyin": str(item.get("pinyin") or ""),
+                    "parentId": str(item.get("parentId") or ""),
+                    "table": str(group.get("table") or ""),
+                    "idColumn": str(group.get("idColumn") or ""),
+                    "nameColumn": str(group.get("nameColumn") or ""),
+                    "parentType": str(group.get("parentType") or ""),
+                }
+            )
+    return result
+
+
+def _unique_entity_search_item(search_response: dict[str, Any] | None) -> dict[str, str] | None:
+    items = _flatten_entity_search_items(search_response)
+    return items[0] if len(items) == 1 else None
+
+
+def _unique_entity_search_items(search_response: dict[str, Any] | None) -> list[dict[str, str]]:
+    if not isinstance(search_response, dict):
+        return []
+    search_results = search_response.get("searchResults")
+    if not isinstance(search_results, list):
+        item = _unique_entity_search_item(search_response)
+        return [item] if item is not None else []
+    result: list[dict[str, str]] = []
+    for search_result in search_results:
+        if not isinstance(search_result, dict):
+            continue
+        item = _unique_entity_search_item(search_result.get("response"))
+        if item is not None:
+            result.append(item)
+    return result
+
+
+def _entity_search_filter_items(search_response: dict[str, Any] | None) -> list[dict[str, str]]:
+    if not isinstance(search_response, dict):
+        return []
+    search_results = search_response.get("searchResults")
+    if not isinstance(search_results, list):
+        return _entity_search_filter_items_for_response(
+            search_response,
+            searched_name=str(search_response.get("searchedName") or ""),
+            group_seed="entity_search",
+        )
+    result: list[dict[str, str]] = []
+    group_counts: dict[str, int] = {}
+    for search_result in search_results:
+        if not isinstance(search_result, dict):
+            continue
+        response = search_result.get("response")
+        if not isinstance(response, dict):
+            continue
+        group_key = _entity_search_alias_group_key(search_result)
+        if not group_key:
+            continue
+        group_counts[group_key] = group_counts.get(group_key, 0) + len(_flatten_entity_search_items(response))
+    for index, search_result in enumerate(search_results, start=1):
+        if not isinstance(search_result, dict):
+            continue
+        response = search_result.get("response")
+        if not isinstance(response, dict):
+            continue
+        searched_name = str(search_result.get("searchedName") or "")
+        candidate = search_result.get("candidate")
+        candidate_type = str(candidate.get("type") or "") if isinstance(candidate, dict) else ""
+        group_key = _entity_search_alias_group_key(search_result)
+        if group_key and group_counts.get(group_key, 0) > 1:
+            group_seed = f"entity_search:{group_key}"
+        else:
+            group_seed = f"entity_search:{index}:{candidate_type}:{searched_name}"
+        result.extend(
+            _entity_search_filter_items_for_response(
+                response,
+                searched_name=searched_name,
+                group_seed=group_seed,
+                force_logical_group=bool(group_key and group_counts.get(group_key, 0) > 1),
+            )
+        )
+    return result
+
+
+def _entity_search_alias_group_key(search_result: dict[str, Any]) -> str:
+    candidate = search_result.get("candidate")
+    raw = ""
+    if isinstance(candidate, dict):
+        raw = str(candidate.get("value") or "")
+    if not raw:
+        raw = str(search_result.get("searchedName") or "")
+    return re.sub(r"[^0-9A-Za-z\u4e00-\u9fff]+", "", raw).lower()
+
+
+def _entity_search_filter_items_for_response(
+    response: dict[str, Any],
+    *,
+    searched_name: str,
+    group_seed: str,
+    force_logical_group: bool = False,
+) -> list[dict[str, str]]:
+    items = _flatten_entity_search_items(response)
+    if not items:
+        return []
+    logical_group = group_seed if force_logical_group or len(items) > 1 else ""
+    result: list[dict[str, str]] = []
+    for item in items:
+        enriched = dict(item)
+        if searched_name:
+            enriched["matchedName"] = searched_name
+        if logical_group:
+            enriched["logicalGroup"] = logical_group
+            enriched["logicalOperator"] = "OR"
+        result.append(enriched)
+    return result
+
+
+def _direct_entity_candidates(search_response: dict[str, Any] | None) -> list[dict[str, str]]:
+    if not isinstance(search_response, dict):
+        return []
+    candidates = [
+        candidate
+        for candidate in search_response.get("entityCandidates") or []
+        if isinstance(candidate, dict) and candidate.get("type") and candidate.get("value")
+    ]
+    search_results = search_response.get("searchResults")
+    if not isinstance(search_results, list):
+        return candidates
+    resolved: set[tuple[str, str]] = set()
+    for search_result in search_results:
+        if not isinstance(search_result, dict):
+            continue
+        candidate = search_result.get("candidate")
+        if not isinstance(candidate, dict):
+            continue
+        if _flatten_entity_search_items(search_result.get("response")):
+            resolved.add((str(candidate.get("type") or ""), str(candidate.get("value") or "")))
+    return [
+        candidate
+        for candidate in candidates
+        if (str(candidate.get("type") or ""), str(candidate.get("value") or "")) not in resolved
+    ]
+
+
+def _entity_type_label(entity_type: str) -> str:
+    return {
+        "brand": "品牌",
+        "project": "项目",
+        "province": "省份",
+        "city": "城市",
+        "region": "区域",
+        "store": "门店",
+        "sponge_project": "项目",
+        "supplier": "供应商",
+    }.get(entity_type, entity_type)
+
+
+_ENTITY_TYPE_SUFFIXES: dict[str, tuple[str, ...]] = {
+    "brand": ("品牌",),
+    "project": ("项目",),
+    "sponge_project": ("项目",),
+    "store": ("门店",),
+}
+
+
+def _normalize_entity_search_value(entity_type: str, value: str) -> str:
+    """Drop trailing type words such as 项目/品牌/门店 when they are labels, not part of the name."""
+    cleaned = value.strip()
+    if not cleaned:
+        return cleaned
+    suffixes = _ENTITY_TYPE_SUFFIXES.get(entity_type, ())
+    for suffix in suffixes:
+        if cleaned.endswith(suffix) and len(cleaned) > len(suffix) + 1:
+            return cleaned[: -len(suffix)].strip()
+    return cleaned
+
+
+def _entity_search_filter_field(entity_type: str) -> str:
+    return entity_type
+
+
+def _entity_catalog(schema: dict[str, Any]) -> list[dict[str, str]]:
+    """Build extractable entity slots from ``structure.businessTerms`` only."""
+    catalog: list[dict[str, str]] = []
+    seen_types: set[str] = set()
+    for term in list(_schema_structure(schema).get("businessTerms", [])) + list(_CORE_LOCATION_DIMENSIONS):
+        if not isinstance(term, dict):
+            continue
+        if term.get("type") not in ("dimension", "entity"):
+            continue
+        label = str(term.get("term") or "").strip()
+        type_code = str(term.get("mapsTo") or "").strip()
+        if not label or not type_code or type_code in seen_types:
+            continue
+        seen_types.add(type_code)
+        filter_field = label if label.endswith("名称") else f"{label}名称"
+        catalog.append({"type": type_code, "label": label, "filterField": filter_field})
+    return catalog
+
+
+def _llm_extract_entity_values(
+    question: str,
+    catalog: list[dict[str, str]],
+    sampler: Sampler,
+    agent_instructions: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """One LLM call that extracts open values for every catalog type at once."""
+    field_lines = "\n".join(f'- {item["type"]}: {item["label"]}' for item in catalog)
+    instruction_lines = format_numbered_instruction_lines(
+        filter_agent_instructions_by_stage(agent_instructions or [], "before")
+    )
+    system = (
+        "你是一个严格的实体槽位抽取器。payload 中的 mandatoryAgentInstructions 必须逐条遵守。"
+        "从用户问题中抽取字段值，"
+        "只输出一个 JSON 对象，键为字段代码，值为问题中出现的实体名称原文；"
+        "问题中没有提到的字段一律输出 null。不要输出任何解释或多余文本。"
+        "城市（如上海、北京）填 city；区县（如杨浦区、浦东新区）填 region，不要填 city；"
+        "具体门店（含店/路/广场等）填 store。"
+        "品牌与项目可能同名：如果用户明确说这是项目，只填 sponge_project，不填 brand；"
+        "如果用户明确说这是品牌，只填 brand，不填 sponge_project；"
+        "只有问题没有明确标注品牌或项目时，brand 与 sponge_project 才都填同一检索词。"
+        "实体名称必须保留用户原文中的括号补充说明，例如 Mstand（打包店员）不能改成 Mstand。"
+        "遇到“名称 + 时间词 + 阶段/动作词 + 业务对象/指标”的连续短语时，必须拆分后只保留名称部分为实体值；"
+        "例如“成都你六姐明天面试的工单数量”中，brand 和 sponge_project 都填“成都你六姐”，"
+        "不要把“成都你六姐明天面试”填入任何字段，尤其不能填入工单、报名时间、面试时间等字段。"
+        "时间、查询动作、统计意图、范围词和状态口径不要填为实体值；这些不是品牌、项目、门店、城市等名称。"
+        "同时输出 explicitTypes 数组，放入用户明确标注的字段代码；未明确标注则输出空数组。"
+    )
+    payload = {
+        "mandatoryAgentInstructions": instruction_lines,
+        "fields": field_lines,
+        "question": question,
+        "outputExample": {
+            "brand": None,
+            "sponge_project": "Mstand（打包店员）",
+            "explicitTypes": ["sponge_project"],
+        },
+        "compoundPhraseExample": {
+            "question": "成都你六姐明天面试的工单数量",
+            "brand": "成都你六姐",
+            "sponge_project": "成都你六姐",
+            "mvp_applied_jobs_by_helped_account": None,
+            "sign_up_time": None,
+            "explicitTypes": [],
+        },
+    }
+    prompt = json.dumps(payload, ensure_ascii=False, indent=2)
+    try:
+        raw = sampler(system, prompt)
+    except Exception:  # noqa: BLE001 - extraction is best-effort, never fatal
+        return {}
+    payload = _load_json_object_safe(raw)
+    values: dict[str, Any] = {}
+    allowed = {item["type"] for item in catalog}
+    value_payload = payload.get("values")
+    if not isinstance(value_payload, dict):
+        value_payload = payload
+    for key, value in value_payload.items():
+        if key in allowed and isinstance(value, str) and value.strip():
+            values[key] = value.strip()
+    explicit_types = _normalize_explicit_entity_types(payload.get("explicitTypes"), allowed)
+    if explicit_types:
+        values[_EXPLICIT_ENTITY_TYPES_KEY] = explicit_types
+    return values
+
+
+def _normalize_explicit_entity_types(raw: Any, allowed: set[str]) -> list[str]:
+    if not isinstance(raw, list):
+        return []
+    result: list[str] = []
+    for item in raw:
+        entity_type = _normalize_entity_slot_type(str(item or "").strip())
+        if entity_type and entity_type in allowed and entity_type not in result:
+            result.append(entity_type)
+    return result
+
+
+def _normalize_entity_slot_type(entity_type: str) -> str:
+    mapped = {
+        "品牌": "brand",
+        "项目": "sponge_project",
+        "工程": "sponge_project",
+        "门店": "store",
+        "城市": "city",
+        "省份": "province",
+        "区域": "region",
+        "区县": "region",
+    }.get(entity_type)
+    if mapped:
+        return mapped
+    if entity_type == "project":
+        return "sponge_project"
+    return entity_type
+
+
+def _merge_analysis_entity_candidates_into_llm_values(
+    llm_values: dict[str, Any],
+    analysis: QuestionAnalysis | None,
+    catalog: list[dict[str, str]],
+) -> dict[str, Any]:
+    """Use the demand-analysis entity candidates as a fallback for entity search."""
+    if analysis is None:
+        return dict(llm_values)
+    allowed = {item["type"] for item in catalog}
+    merged = dict(llm_values)
+    for candidate in analysis.entity_candidates:
+        if not isinstance(candidate, dict) or candidate.get("isNoise") is True:
+            continue
+        entity_type = _normalize_entity_slot_type(str(candidate.get("type") or "").strip())
+        value = str(candidate.get("value") or "").strip()
+        if not entity_type or entity_type not in allowed or not value:
+            continue
+        if _is_analysis_noise_value(value, analysis):
+            continue
+        merged.setdefault(entity_type, value)
+    return merged
+
+
+def _drop_implicit_location_values_inside_named_entities(llm_values: dict[str, Any]) -> None:
+    """Avoid treating the location-looking prefix of a brand/project name as a separate location."""
+    explicit_types = llm_values.get(_EXPLICIT_ENTITY_TYPES_KEY)
+    explicit = set(explicit_types) if isinstance(explicit_types, list) else set()
+    if explicit.intersection({"province", "city", "region"}):
+        return
+    named_values = [
+        str(llm_values.get(entity_type) or "").strip()
+        for entity_type in ("brand", "sponge_project", "project", "store")
+        if str(llm_values.get(entity_type) or "").strip()
+    ]
+    if not named_values:
+        return
+    for entity_type in ("province", "city", "region"):
+        value = str(llm_values.get(entity_type) or "").strip()
+        if value and any(value != name and value in name for name in named_values):
+            llm_values.pop(entity_type, None)
+
+
+def _is_analysis_noise_value(value: Any, analysis: QuestionAnalysis | None) -> bool:
+    normalized = _normalize_analysis_noise_text(value)
+    if not normalized:
+        return False
+    return normalized in _analysis_noise_value_set(analysis)
+
+
+def _analysis_noise_value_set(analysis: QuestionAnalysis | None) -> set[str]:
+    if analysis is None:
+        return set()
+    values: set[str] = set()
+    for item in analysis.noise_values:
+        if not isinstance(item, dict):
+            continue
+        normalized = _normalize_analysis_noise_text(item.get("value"))
+        if normalized:
+            values.add(normalized)
+    for item in analysis.entity_candidates:
+        if not isinstance(item, dict) or item.get("isNoise") is not True:
+            continue
+        normalized = _normalize_analysis_noise_text(item.get("value"))
+        if normalized:
+            values.add(normalized)
+    return values
+
+
+def _normalize_analysis_noise_text(value: Any) -> str:
+    return str(value or "").strip().strip("%").strip().lower()
+
+
+def _load_json_object_safe(text: str) -> dict[str, Any]:
+    cleaned = (text or "").strip()
+    if cleaned.startswith("```"):
+        cleaned = cleaned.strip("`")
+        if cleaned.lower().startswith("json"):
+            cleaned = cleaned[4:].strip()
+    try:
+        payload = json.loads(cleaned)
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start == -1 or end == -1 or end <= start:
+            return {}
+        try:
+            payload = json.loads(cleaned[start : end + 1])
+        except json.JSONDecodeError:
+            return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _extract_question_entities(
+    question: str,
+    schema: dict[str, Any],
+    sampler: Sampler | None,
+    *,
+    agent_instructions: list[dict[str, Any]] | None = None,
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    """Unified schema-driven entity extraction used by both filters and entities."""
+    results: list[dict[str, str]] = []
+    catalog = _entity_catalog(schema)
+    llm_values: dict[str, Any] = {}
+    if sampler is not None and catalog:
+        llm_values = _llm_extract_entity_values(question, catalog, sampler, agent_instructions)
+    llm_values = _merge_analysis_entity_candidates_into_llm_values(llm_values, analysis, catalog)
+    _drop_implicit_location_values_inside_named_entities(llm_values)
+    for item in catalog:
+        value = llm_values.get(item["type"]) or _extract_value_near_label(question, item["label"])
+        if value and not _is_analysis_noise_value(value, analysis):
+            results.append(
+                {
+                    "type": item["type"],
+                    "label": item["label"],
+                    "filterField": item["filterField"],
+                    "value": value,
+                }
+            )
+    return results
+
+
+def _time_range_source_question(original_question: str, normalized_question: str) -> str:
+    """Prefer the user's original wording for date parsing when they omitted an explicit year."""
+    original = original_question.strip()
+    normalized = normalized_question.strip()
+    if not original:
+        return normalized
+    if re.search(r"20\d{2}\s*年", original):
+        return original
+    if re.search(r"20\d{2}\s*年", normalized):
+        return original
+    return normalized or original
+
+
+def _query_plan_filters(
+    question: str,
+    schema_context: Any,
+    *,
+    searched_entities: dict[str, Any] | None = None,
+    question_entities: list[dict[str, str]] | None = None,
+    schema: dict[str, Any] | None = None,
+    time_range_question: str | None = None,
+    selected_concepts: list[dict[str, Any]] | None = None,
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    filters: list[dict[str, str]] = []
+
+    def _append_filter(item: dict[str, str]) -> None:
+        field = _resolve_query_plan_filter_field(str(item.get("field") or ""), schema)
+        normalized = {**item, "field": field}
+        key = (field, str(normalized.get("operator") or ""), str(normalized.get("value") or ""))
+        if any(existing for existing in filters if (existing.get("field"), existing.get("operator"), existing.get("value")) == key):
+            return
+        filters.append(normalized)
+
+    if isinstance(searched_entities, dict):
+        for candidate in searched_entities.get("schemaCandidates") or []:
+            if not isinstance(candidate, dict):
+                continue
+            entity_type = str(candidate.get("type") or "")
+            normalized_value = _normalize_entity_search_value(entity_type, str(candidate.get("value") or ""))
+            if _is_analysis_noise_value(normalized_value, analysis):
+                continue
+            _append_filter(
+                {
+                    "field": str(candidate.get("field") or _entity_search_filter_field(entity_type)),
+                    "operator": "LIKE",
+                    "value": f"%{normalized_value}%",
+                    "source": str(candidate.get("source") or "schema"),
+                }
+            )
+
+    for entity in question_entities or []:
+        if _is_analysis_noise_value(entity.get("value"), analysis):
+            continue
+        _append_filter(
+            {
+                "field": entity["filterField"],
+                "operator": "LIKE",
+                "value": f"%{entity['value']}%",
+                "source": "用户问题",
+            }
+        )
+    for filter_item in _query_plan_search_entity_filters(searched_entities, schema):
+        _append_filter(filter_item)
+    for candidate in _direct_entity_candidates(searched_entities):
+        maps_to = str(candidate.get("mapsTo") or candidate.get("type") or "")
+        field = str(candidate.get("field") or "")
+        if not field or "." not in field:
+            field = _entity_table_name_column(maps_to, schema) if schema and maps_to else _entity_search_filter_field(str(candidate.get("type") or ""))
+        raw_value = str(candidate.get("value") or "")
+        normalized_value = _normalize_entity_search_value(maps_to, _normalize_entity_search_value(str(candidate.get("type") or ""), raw_value))
+        if _is_analysis_noise_value(normalized_value, analysis):
+            continue
+        _append_filter(
+            {
+                "field": field,
+                "operator": "LIKE",
+                "value": f"%{normalized_value}%",
+                "source": str(candidate.get("source") or "schema.columns"),
+            }
+        )
+    for enum_filter in _query_plan_enum_filters(question, getattr(schema_context, "enums", []) or []):
+        filters.append(enum_filter)
+    if selected_concepts is None:
+        selected_concepts = match_concepts_for_question(getattr(schema_context, "concepts", []) or [], question)
+    filters.extend(_query_plan_concept_filters(selected_concepts))
+    for default_filter in getattr(schema_context, "table_defaults", []) or []:
+        if not isinstance(default_filter, dict):
+            continue
+        condition = (
+            default_filter.get("condition")
+            or default_filter.get("where")
+            or default_filter.get("predicate")
+            or default_filter.get("expression")
+            or default_filter.get("filter")
+        )
+        if condition:
+            filters.append(
+                {
+                    "field": str(default_filter.get("table") or ""),
+                    "operator": "DEFAULT",
+                    "value": str(condition),
+                    "source": "structure.defaultFilters",
+                }
+            )
+    filters = _merge_query_plan_equality_filters(filters)
+    filters = _drop_conflicting_status_concept_filters(filters)
+    filters = _drop_schema_column_noise_filters(filters, analysis=analysis)
+    filters = _drop_time_field_text_like_filters(filters, analysis=analysis)
+    filters = _apply_query_plan_time_range_filters(
+        filters,
+        time_range_question or question,
+        schema,
+        selected_concepts=selected_concepts,
+        analysis=analysis,
+    )
+    return filters
+
+
+def _query_plan_search_entity_filters(
+    searched_entities: dict[str, Any] | None,
+    schema: dict[str, Any] | None,
+) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    for unique_entity in _entity_search_filter_items(searched_entities):
+        maps_to = _search_maps_to_for_entity_type(unique_entity.get("type", ""))
+        field = _entity_table_name_column(maps_to, schema) if schema and maps_to else _entity_search_filter_field(unique_entity["type"])
+        if unique_entity.get("type") == "city":
+            name_variants = _city_name_filter_values(unique_entity["name"])
+        elif unique_entity.get("type") == "region":
+            name_variants = _region_name_filter_values(unique_entity["name"])
+        else:
+            name_variants = [unique_entity["name"]]
+        for variant in name_variants:
+            filter_item = {
+                "field": field,
+                "operator": "LIKE",
+                "value": f"%{variant}%",
+                "source": "search_entities",
+            }
+            logical_group = unique_entity.get("logicalGroup")
+            if logical_group:
+                filter_item["logicalGroup"] = logical_group
+                filter_item["logicalOperator"] = "OR"
+            result.append(filter_item)
+    return result
+
+
+def _apply_query_plan_time_range_filters(
+    filters: list[dict[str, str]],
+    question: str,
+    schema: dict[str, Any] | None,
+    *,
+    selected_concepts: list[dict[str, Any]] | None = None,
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    """Replace noisy date LIKE filters with explicit range filters defaulting to current year."""
+    time_filters = _analysis_time_range_plan_filters(analysis, selected_concepts=selected_concepts)
+    if not time_filters:
+        time_filters = time_range_plan_filters(question, schema, concepts=selected_concepts)
+    if not time_filters:
+        return filters
+    qualified_fields = {str(item.get("field") or "") for item in time_filters if item.get("field")}
+    column_names = {field.split(".", 1)[-1] for field in qualified_fields if field}
+    cleaned: list[dict[str, str]] = []
+    for item in filters:
+        field = str(item.get("field") or "")
+        operator = str(item.get("operator") or "").upper()
+        if operator == "LIKE" and (
+            field in qualified_fields
+            or field.split(".", 1)[-1] in column_names
+            or _looks_like_time_range_noise_like(item.get("value"), analysis=analysis)
+        ):
+            continue
+        cleaned.append(item)
+    return cleaned + time_filters
+
+
+def _analysis_time_range_plan_filters(
+    analysis: QuestionAnalysis | None,
+    *,
+    selected_concepts: list[dict[str, Any]] | None = None,
+) -> list[dict[str, str]]:
+    if analysis is None or not isinstance(analysis.time_range, dict):
+        return []
+    start = str(analysis.time_range.get("start") or "").strip()
+    end = str(analysis.time_range.get("endExclusive") or analysis.time_range.get("end") or "").strip()
+    if not (_looks_like_iso_date(start) and _looks_like_iso_date(end)):
+        return []
+    field = _time_range_field_from_concepts(selected_concepts)
+    if not field:
+        return []
+    original = str(analysis.time_range.get("originalText") or analysis.time_range.get("value") or "时间范围").strip()
+    return [
+        {
+            "field": field,
+            "operator": ">=",
+            "value": start[:10],
+            "description": f"{original}起",
+            "source": "question_analysis.timeRange",
+        },
+        {
+            "field": field,
+            "operator": "<",
+            "value": end[:10],
+            "description": f"{original}止",
+            "source": "question_analysis.timeRange",
+        },
+    ]
+
+
+def _time_range_field_from_concepts(concepts: list[dict[str, Any]] | None) -> str:
+    for concept in concepts or []:
+        if not isinstance(concept, dict):
+            continue
+        field = str(concept.get("timeRangeField") or "").strip()
+        if "." in field:
+            return field
+    return ""
+
+
+def _looks_like_iso_date(value: str) -> bool:
+    return bool(re.fullmatch(r"20\d{2}-\d{2}-\d{2}", value[:10]))
+
+
+def _drop_time_field_text_like_filters(
+    filters: list[dict[str, str]],
+    *,
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    cleaned: list[dict[str, str]] = []
+    for item in filters:
+        operator = str(item.get("operator") or "").upper()
+        field = str(item.get("field") or "")
+        value = str(item.get("value") or "")
+        if operator == "LIKE" and _is_time_like_query_plan_field(field):
+            stripped = value.strip().strip("%").strip()
+            if _is_analysis_noise_value_or_part(stripped, analysis) or not _contains_date_like_text(stripped):
+                continue
+        cleaned.append(item)
+    return cleaned
+
+
+def _is_time_like_query_plan_field(field: str) -> bool:
+    column = field.rsplit(".", 1)[-1].strip("`").lower()
+    return bool(column in {"date", "day"} or column.endswith("_time") or column.endswith("_date") or column.endswith("_at"))
+
+
+def _contains_date_like_text(value: str) -> bool:
+    return bool(
+        re.search(r"20\d{2}-\d{1,2}-\d{1,2}", value)
+        or re.search(r"20\d{2}\s*年", value)
+        or re.search(r"\d{1,2}\s*月\s*\d{1,2}\s*日", value)
+    )
+
+
+def _looks_like_time_range_noise_like(value: Any, *, analysis: QuestionAnalysis | None = None) -> bool:
+    text = str(value or "")
+    if not text:
+        return False
+    stripped = text.strip("%")
+    if _is_analysis_noise_value(stripped, analysis):
+        return True
+    return bool(re.search(r"\d{1,2}\s*月", stripped) and re.search(r"(到|至|日|整个|整月|之间)", stripped))
+
+
+def _is_schema_column_name_filter(field: str) -> bool:
+    if "." not in field:
+        return False
+    column = field.rsplit(".", 1)[-1].lower()
+    return column in {"name", "title"} or column.endswith("_name")
+
+
+_GENERIC_ENTITY_NAME_VALUES = frozenset(
+    {
+        "岗位",
+        "职位",
+        "工单",
+        "门店",
+        "品牌",
+        "项目",
+        "供应商",
+        "城市",
+        "区域",
+        "省份",
+    }
+)
+
+
+def _is_generic_entity_name_value(value: Any) -> bool:
+    normalized = str(value or "").strip().strip("%").strip()
+    return normalized in _GENERIC_ENTITY_NAME_VALUES
+
+
+def _drop_schema_column_noise_filters(
+    filters: list[dict[str, str]],
+    *,
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    """Drop name-field LIKE filters whose values are query-intent phrases, not entity names."""
+    authoritative_tables: set[str] = set()
+    for item in filters:
+        source = str(item.get("source") or "")
+        if source not in {"search_entities", "search_entities.candidate", "schema.businessTerms", "用户问题"}:
+            continue
+        field = str(item.get("field") or "")
+        if "." in field:
+            authoritative_tables.add(field.split(".", 1)[0])
+
+    cleaned: list[dict[str, str]] = []
+    for item in filters:
+        operator = str(item.get("operator") or "").upper()
+        field = str(item.get("field") or "")
+        source = str(item.get("source") or "")
+        if operator == "LIKE" and _is_schema_column_name_filter(field):
+            if _is_analysis_noise_value(item.get("value"), analysis) or _is_generic_entity_name_value(item.get("value")):
+                continue
+        if source != "schema.columns":
+            cleaned.append(item)
+            continue
+        if operator != "LIKE":
+            cleaned.append(item)
+            continue
+        if not _is_schema_column_name_filter(field):
+            continue
+        table = field.split(".", 1)[0] if "." in field else ""
+        if table in authoritative_tables:
+            continue
+        cleaned.append(item)
+    return cleaned
+
+
+def _remove_noise_name_like_filters_from_sql(sql: str, *, analysis: QuestionAnalysis | None = None) -> str:
+    if not sql.strip() or not _analysis_noise_value_set(analysis):
+        return sql
+    where_bounds = _top_level_where_bounds(sql)
+    if where_bounds is None:
+        return sql
+    where_start, body_start, body_end = where_bounds
+    where_body = sql[body_start:body_end].strip()
+    predicates = [predicate for predicate in _split_top_level_and_predicates(where_body) if predicate.strip()]
+    kept = [
+        predicate.strip()
+        for predicate in predicates
+        if not _is_noise_name_like_sql_predicate(predicate, analysis=analysis)
+    ]
+    if len(kept) == len(predicates):
+        return sql
+    prefix = sql[:where_start].rstrip()
+    suffix = sql[body_end:].strip()
+    rebuilt = f"{prefix} WHERE {' AND '.join(kept)}" if kept else prefix
+    if suffix:
+        rebuilt = f"{rebuilt} {suffix}"
+    return rebuilt.strip()
+
+
+def _top_level_where_bounds(sql: str) -> tuple[int, int, int] | None:
+    where_start = _find_top_level_sql_keyword(sql, "where", start=0)
+    if where_start is None:
+        return None
+    body_start = where_start + len("where")
+    suffix_starts = [
+        index
+        for keyword in ("group by", "order by", "having", "limit")
+        if (index := _find_top_level_sql_keyword(sql, keyword, start=body_start)) is not None
+    ]
+    body_end = min(suffix_starts) if suffix_starts else len(sql)
+    return where_start, body_start, body_end
+
+
+def _find_top_level_sql_keyword(sql: str, keyword: str, *, start: int) -> int | None:
+    target = keyword.lower()
+    depth = 0
+    quote: str | None = None
+    index = start
+    while index < len(sql):
+        char = sql[index]
+        if quote:
+            if char == quote:
+                if quote == "'" and index + 1 < len(sql) and sql[index + 1] == "'":
+                    index += 2
+                    continue
+                quote = None
+            index += 1
+            continue
+        if char in {"'", '"', "`"}:
+            quote = char
+            index += 1
+            continue
+        if char == "(":
+            depth += 1
+            index += 1
+            continue
+        if char == ")":
+            depth = max(0, depth - 1)
+            index += 1
+            continue
+        if depth == 0 and sql[index : index + len(target)].lower() == target:
+            before = sql[index - 1] if index > 0 else " "
+            after = sql[index + len(target)] if index + len(target) < len(sql) else " "
+            if not (before.isalnum() or before == "_") and not (after.isalnum() or after == "_"):
+                return index
+        index += 1
+    return None
+
+
+def _split_top_level_and_predicates(where_body: str) -> list[str]:
+    predicates: list[str] = []
+    depth = 0
+    quote: str | None = None
+    start = 0
+    index = 0
+    while index < len(where_body):
+        char = where_body[index]
+        if quote:
+            if char == quote:
+                if quote == "'" and index + 1 < len(where_body) and where_body[index + 1] == "'":
+                    index += 2
+                    continue
+                quote = None
+            index += 1
+            continue
+        if char in {"'", '"', "`"}:
+            quote = char
+            index += 1
+            continue
+        if char == "(":
+            depth += 1
+            index += 1
+            continue
+        if char == ")":
+            depth = max(0, depth - 1)
+            index += 1
+            continue
+        if depth == 0 and where_body[index : index + 3].lower() == "and":
+            before = where_body[index - 1] if index > 0 else " "
+            after = where_body[index + 3] if index + 3 < len(where_body) else " "
+            if not (before.isalnum() or before == "_") and not (after.isalnum() or after == "_"):
+                predicates.append(where_body[start:index])
+                start = index + 3
+                index += 3
+                continue
+        index += 1
+    predicates.append(where_body[start:])
+    return predicates
+
+
+def _is_noise_name_like_sql_predicate(predicate: str, *, analysis: QuestionAnalysis | None) -> bool:
+    match = re.fullmatch(
+        r"\s*(?P<field>(?:`?[\w]+`?\.)?`?[\w]+`?)\s+LIKE\s+(?P<quote>'|\")(?P<value>.*)(?P=quote)\s*",
+        predicate,
+        flags=re.IGNORECASE | re.DOTALL,
+    )
+    if match is None:
+        return False
+    field = match.group("field").replace("`", "")
+    if not _is_schema_column_name_filter(field):
+        return False
+    return _is_analysis_noise_value_or_part(match.group("value"), analysis)
+
+
+def _is_analysis_noise_value_or_part(value: Any, analysis: QuestionAnalysis | None) -> bool:
+    normalized = _normalize_analysis_noise_text(value)
+    if not normalized:
+        return False
+    for noise in _analysis_noise_value_set(analysis):
+        if normalized == noise or normalized in noise or noise in normalized:
+            return True
+    return False
+
+
+def _merge_query_plan_equality_filters(filters: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Merge multiple ``=`` filters on the same field into one ``IN`` filter."""
+    passthrough: list[dict[str, str]] = []
+    equality_by_field: dict[str, list[dict[str, str]]] = {}
+    for item in filters:
+        if not isinstance(item, dict):
+            continue
+        operator = str(item.get("operator") or "").upper()
+        field = str(item.get("field") or "").strip()
+        if operator == "=" and field:
+            equality_by_field.setdefault(field, []).append(item)
+        else:
+            passthrough.append(item)
+    merged: list[dict[str, str]] = []
+    for field, items in equality_by_field.items():
+        values: list[str] = []
+        descriptions: list[str] = []
+        source = str(items[0].get("source") or "")
+        seen_values: set[str] = set()
+        for item in items:
+            value = str(item.get("value") or "")
+            if not value or value in seen_values:
+                continue
+            seen_values.add(value)
+            values.append(value)
+            desc = str(item.get("description") or "").strip()
+            if desc and desc not in descriptions:
+                descriptions.append(desc)
+        if len(values) <= 1:
+            merged.extend(items)
+            continue
+        entry: dict[str, str] = {
+            "field": field,
+            "operator": "IN",
+            "value": ", ".join(values),
+            "source": source,
+        }
+        if descriptions:
+            entry["description"] = "、".join(descriptions)
+        merged.append(entry)
+    return passthrough + merged
+
+
+def _drop_conflicting_status_concept_filters(filters: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Drop single-status concept predicates when the plan already uses multi-value IN."""
+    multi_in_fields: dict[str, set[str]] = {}
+    for item in filters:
+        if str(item.get("operator") or "").upper() != "IN":
+            continue
+        field = str(item.get("field") or "").strip()
+        if not field or not field.endswith(".status"):
+            continue
+        values = {part.strip() for part in str(item.get("value") or "").split(",") if part.strip()}
+        if len(values) > 1:
+            multi_in_fields[field] = values
+    if not multi_in_fields:
+        return filters
+    result: list[dict[str, str]] = []
+    for item in filters:
+        if str(item.get("operator") or "").upper() != "DEFAULT":
+            result.append(item)
+            continue
+        if str(item.get("source") or "") != "schema.concepts":
+            result.append(item)
+            continue
+        predicate = str(item.get("value") or "").strip()
+        drop = False
+        for field, allowed_values in multi_in_fields.items():
+            if not predicate.startswith(f"{field} = "):
+                continue
+            single = predicate[len(f"{field} = ") :].strip()
+            if single in allowed_values:
+                drop = True
+                break
+        if not drop:
+            result.append(item)
+    return result
+
+
+def _query_plan_concept_filters(concepts: list[dict[str, Any]]) -> list[dict[str, str]]:
+    filters: list[dict[str, str]] = []
+    for concept in concepts:
+        if not isinstance(concept, dict):
+            continue
+        predicates = concept.get("sqlPredicate")
+        if not isinstance(predicates, list):
+            continue
+        description = str(concept.get("comment") or concept.get("name") or "")
+        for predicate in predicates:
+            predicate_text = str(predicate).strip()
+            if not predicate_text:
+                continue
+            field = predicate_text.split(".", 1)[0] if "." in predicate_text else ""
+            filters.append(
+                {
+                    "field": field,
+                    "operator": "DEFAULT",
+                    "value": predicate_text,
+                    "source": "schema.concepts",
+                    "description": description,
+                }
+            )
+    return filters
+
+
+def _query_plan_entities(
+    question: str,
+    schema_context: Any,
+    *,
+    searched_entities: dict[str, Any] | None = None,
+    question_entities: list[dict[str, str]] | None = None,
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    entities: list[dict[str, str]] = []
+    if isinstance(searched_entities, dict):
+        for candidate in searched_entities.get("schemaCandidates") or []:
+            if not isinstance(candidate, dict):
+                continue
+            entities.append(
+                {
+                    "type": str(candidate.get("type") or ""),
+                    "label": str(candidate.get("label") or _entity_type_label(str(candidate.get("type") or ""))),
+                    "value": str(candidate.get("value") or ""),
+                    "source": str(candidate.get("source") or "schema"),
+                }
+            )
+    entities.extend(_query_plan_search_entity_entities(searched_entities))
+    for candidate in _direct_entity_candidates(searched_entities):
+        entities.append(
+            {
+                "type": str(candidate.get("type") or ""),
+                "label": str(candidate.get("label") or _entity_type_label(str(candidate.get("type") or ""))),
+                "value": str(candidate.get("value") or ""),
+                "source": str(candidate.get("source") or "schema.columns"),
+            }
+        )
+    for entity in question_entities or []:
+        entities.append(
+            {
+                "type": entity["type"],
+                "label": entity["label"],
+                "value": entity["value"],
+                "source": "用户问题",
+            }
+        )
+    for enum_filter in _query_plan_enum_filters(question, getattr(schema_context, "enums", []) or []):
+        description = str(enum_filter.get("description") or "")
+        field = str(enum_filter.get("field") or "")
+        value = str(enum_filter.get("value") or "")
+        if description and value:
+            entities.append(
+                {
+                    "type": "status",
+                    "label": "状态",
+                    "value": description,
+                    "matchedField": field,
+                    "matchedValue": value,
+                    "source": "schema.enums",
+                }
+            )
+    return _dedupe_query_plan_entities(
+        entity for entity in entities if not _is_schema_column_noise_entity(entity, analysis=analysis)
+    )
+
+
+def _query_plan_search_entity_entities(searched_entities: dict[str, Any] | None) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    for unique_entity in _entity_search_filter_items(searched_entities):
+        entity = {
+            "type": unique_entity["type"],
+            "label": _entity_type_label(unique_entity["type"]),
+            "value": unique_entity["name"],
+            "id": str(unique_entity.get("id") or ""),
+            "source": "search_entities",
+            "matchedName": str(unique_entity.get("matchedName") or ""),
+        }
+        logical_group = unique_entity.get("logicalGroup")
+        if logical_group:
+            entity["logicalGroup"] = logical_group
+            entity["logicalOperator"] = "OR"
+        result.append(entity)
+    return result
+
+
+def _is_schema_column_noise_entity(
+    entity: dict[str, str],
+    *,
+    analysis: QuestionAnalysis | None = None,
+) -> bool:
+    if str(entity.get("source") or "") != "schema.columns":
+        return False
+    return _is_analysis_noise_value(entity.get("value"), analysis)
+
+
+def _dedupe_query_plan_entities(entities: list[dict[str, str]]) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    seen: set[tuple[str, str, str]] = set()
+    for entity in entities:
+        key = (
+            str(entity.get("type") or ""),
+            str(entity.get("value") or ""),
+            str(entity.get("matchedField") or ""),
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(entity)
+    return result
+
+
+def _query_plan_enum_filters(question: str, enums: list[dict[str, Any]]) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    for enum in enums:
+        if not isinstance(enum, dict):
+            continue
+        field = str(enum.get("field") or "")
+        values = enum.get("values")
+        if not isinstance(values, list):
+            continue
+        for item in values:
+            if not isinstance(item, dict):
+                continue
+            label = str(item.get("label") or "")
+            value = item.get("value")
+            if not label or value is None:
+                continue
+            if any(term and term in question for term in _split_enum_label_terms(label)):
+                result.append(
+                    {
+                        "field": field,
+                        "operator": "=",
+                        "value": str(value),
+                        "description": label,
+                        "source": "schema.enums",
+                    }
+                )
+    return result
+
+
+def _split_enum_label_terms(label: str) -> set[str]:
+    terms = {label.strip()}
+    terms.update(part.strip() for part in re.split(r"[/、,，;；\s]+", label) if part.strip())
+    return {term for term in terms if term}
+
+
+def _query_plan_tokens(question: str) -> list[str]:
+    tokens = [question.lower()]
+    tokens.extend(part for part in re.split(r"[\s_\-:：,，。；;]+", question.lower()) if part)
+    for run in re.findall(r"[\u4e00-\u9fff]+", question):
+        if len(run) == 1:
+            tokens.append(run)
+        for index in range(len(run) - 1):
+            tokens.append(run[index : index + 2])
+    return list(dict.fromkeys(tokens))
+
+
+def _prepend_query_plan_summary(
+    answer: str,
+    question: str,
+    result_format: str | None,
+    query_plan: dict[str, Any],
+) -> str:
+    output_format = normalize_result_format(question, result_format)
+    summary = _identification_summary(query_plan)
+    filters = _query_plan_summary_filters(query_plan)
+    entities = _query_plan_summary_entities(query_plan)
+    if output_format == "json":
+        try:
+            payload = json.loads(answer)
+        except json.JSONDecodeError:
+            return f"{_format_identification_section(query_plan)}\n\n3. 查询结果：\n{answer}"
+        return json.dumps(
+            {
+                "查询实体": entities,
+                "筛选条件": filters,
+                "查询结果": payload,
+            },
+            ensure_ascii=False,
+            indent=2,
+        ) + "\n"
+    if output_format == "yaml":
+        return (
+            "查询实体:\n"
+            + "".join(f"  - {json.dumps(item, ensure_ascii=False)}\n" for item in entities)
+            + "筛选条件:\n"
+            + "".join(f"  - {json.dumps(item, ensure_ascii=False)}\n" for item in filters)
+            + "查询结果:\n"
+            + "\n".join(f"  {line}" if line else "" for line in answer.rstrip().splitlines())
+            + "\n"
+        )
+    if output_format == "html":
+        return (
+            "<section><p>1. 查询实体：</p><p>"
+            + (html_escape("；".join(entities)) or "无")
+            + "</p></section>"
+            + "<section><p>2. 筛选条件：</p><p>"
+            + (html_escape("；".join(filters)) or "无")
+            + "</p></section>"
+            + "<section><p>3. 查询结果：</p></section>"
+            + answer
+        )
+    return f"{summary}\n\n3. 查询结果：\n{answer}"
+
+
+def ensure_query_plan_summary_answer(
+    answer: str,
+    question: str,
+    result_format: str | None,
+    query_plan: dict[str, Any] | None,
+) -> str:
+    if not isinstance(query_plan, dict) or not query_plan:
+        return answer
+    if _has_query_plan_summary_answer(answer, question, result_format):
+        return _replace_query_plan_summary(answer, question, result_format, query_plan)
+    return _prepend_query_plan_summary(answer, question, result_format, query_plan)
+
+
+def _replace_query_plan_summary(
+    answer: str,
+    question: str,
+    result_format: str | None,
+    query_plan: dict[str, Any],
+) -> str:
+    output_format = normalize_result_format(question, result_format)
+    filters = _query_plan_summary_filters(query_plan)
+    entities = _query_plan_summary_entities(query_plan)
+    if output_format == "json":
+        try:
+            payload = json.loads(answer)
+        except json.JSONDecodeError:
+            return _prepend_query_plan_summary(answer, question, result_format, query_plan)
+        if isinstance(payload, dict):
+            rebuilt: dict[str, Any] = {
+                "查询实体": entities,
+                "筛选条件": filters,
+                "查询结果": payload.get("查询结果", payload),
+            }
+            return json.dumps(rebuilt, ensure_ascii=False, indent=2) + "\n"
+        return _prepend_query_plan_summary(answer, question, result_format, query_plan)
+    if output_format == "yaml":
+        result_body = _yaml_query_result_body(answer)
+        return _prepend_query_plan_summary(result_body, question, result_format, query_plan)
+    if output_format == "html":
+        result_match = re.search(r"(?is)<section><p>3\.\s*查询结果：</p></section>(?P<body>.*)$", answer)
+        result_body = result_match.group("body") if result_match else answer
+        return _prepend_query_plan_summary(result_body, question, result_format, query_plan)
+    result_body = _plain_query_result_body(answer)
+    return _prepend_query_plan_summary(result_body, question, result_format, query_plan)
+
+
+def _plain_query_result_body(answer: str) -> str:
+    match = re.search(r"(?s)\b3\.\s*查询结果：\s*\n?(?P<body>.*)$", answer)
+    if match is None:
+        return answer
+    return match.group("body").strip()
+
+
+def _yaml_query_result_body(answer: str) -> str:
+    match = re.search(r"(?ms)^查询结果:\s*\n(?P<body>.*)$", answer)
+    if match is None:
+        return answer
+    lines = []
+    for line in match.group("body").splitlines():
+        lines.append(line[2:] if line.startswith("  ") else line)
+    return "\n".join(lines).strip()
+
+
+def _has_query_plan_summary_answer(answer: str, question: str, result_format: str | None) -> bool:
+    output_format = normalize_result_format(question, result_format)
+    if output_format == "json":
+        try:
+            payload = json.loads(answer)
+        except json.JSONDecodeError:
+            return False
+        return (
+            isinstance(payload, dict)
+            and "查询实体" in payload
+            and "筛选条件" in payload
+            and "查询结果" in payload
+        )
+    if output_format == "yaml":
+        return "查询实体:" in answer and "筛选条件:" in answer and "查询结果:" in answer
+    return "1. 查询实体" in answer and "2. 筛选条件" in answer and "3. 查询结果" in answer
+
+
+def _format_identification_section(query_plan: dict[str, Any]) -> str:
+    return _identification_summary(query_plan)
+
+
+def _identification_summary(query_plan: dict[str, Any]) -> str:
+    entities = _query_plan_summary_entities(query_plan)
+    filters = _query_plan_summary_filters(query_plan)
+    return (
+        "1. 查询实体：\n" + ("；".join(entities) if entities else "无")
+        + "\n\n"
+        + "2. 筛选条件：\n" + ("；".join(filters) if filters else "无")
+    )
+
+
+def _query_plan_summary_entities(query_plan: dict[str, Any]) -> list[str]:
+    entities = query_plan.get("entities") if isinstance(query_plan.get("entities"), list) else []
+    result: list[str] = []
+    for entity in entities:
+        if not isinstance(entity, dict):
+            continue
+        if _entity_summary_as_filter_label(entity):
+            continue
+        label = str(entity.get("label") or entity.get("type") or "").strip()
+        value = str(entity.get("value") or "").strip()
+        if label in {"实体", "实体类型", "查询对象", "对象"} and value:
+            label = value
+        if label and label not in result:
+            result.append(label)
+    return result
+
+
+def _query_plan_summary_filters(query_plan: dict[str, Any]) -> list[str]:
+    filters = query_plan.get("filters") if isinstance(query_plan.get("filters"), list) else []
+    result: list[str] = []
+
+    def append_filter(display: str) -> None:
+        if display and display not in result:
+            result.append(display)
+
+    entity_filter_labels: set[str] = set()
+    for display, label in _query_plan_entity_filter_summaries(query_plan):
+        append_filter(display)
+        entity_filter_labels.add(label)
+
+    for item in filters:
+        if not isinstance(item, dict):
+            continue
+        field = str(item.get("field") or "")
+        operator = str(item.get("operator") or "")
+        value = str(item.get("value") or "")
+        label = _query_plan_filter_display_label(field, item)
+        display_value = _query_plan_filter_display_value(value, item)
+        if label in entity_filter_labels and label in _FILTER_SUMMARY_ENTITY_LABELS:
+            continue
+        if label and display_value:
+            append_filter(f"{label}{_query_plan_filter_display_operator(operator)}{display_value}" + _query_plan_filter_logic_label(item))
+            continue
+        if field or value:
+            append_filter(" ".join(part for part in (field, operator, value) if part) + _query_plan_filter_logic_label(item))
+    return result
+
+
+_FILTER_SUMMARY_ENTITY_LABELS = frozenset({"品牌", "项目", "省份", "城市", "区域", "门店", "供应商", "状态", "岗位状态"})
+
+
+def _query_plan_entity_filter_summaries(query_plan: dict[str, Any]) -> list[tuple[str, str]]:
+    entities = query_plan.get("entities") if isinstance(query_plan.get("entities"), list) else []
+    result: list[tuple[str, str]] = []
+    for entity in entities:
+        if not isinstance(entity, dict):
+            continue
+        label = _entity_summary_as_filter_label(entity)
+        if not label:
+            continue
+        value = _query_plan_filter_display_value(str(entity.get("value") or ""), entity)
+        if not value:
+            continue
+        result.append((f"{label}={value}" + _query_plan_filter_logic_label(entity), label))
+    return result
+
+
+def _entity_summary_as_filter_label(entity: dict[str, Any]) -> str | None:
+    value = str(entity.get("value") or "").strip()
+    if not value:
+        return None
+    entity_type = str(entity.get("type") or "")
+    label = str(entity.get("label") or "").strip()
+    if entity_type == "status":
+        field_label = _query_plan_filter_field_label(str(entity.get("matchedField") or ""))
+        return field_label or "状态"
+    normalized = _entity_type_label(entity_type)
+    for candidate in (normalized, label):
+        if candidate in _FILTER_SUMMARY_ENTITY_LABELS:
+            return candidate
+    return None
+
+
+def _query_plan_filter_display_label(field: str, item: dict[str, Any]) -> str:
+    source = str(item.get("source") or "")
+    if source == "schema.enums":
+        field_label = _query_plan_filter_field_label(field)
+        return field_label if field_label.endswith("状态") else "状态"
+    return _query_plan_filter_field_label(field)
+
+
+def _query_plan_filter_field_label(field: str) -> str:
+    cleaned = field.strip()
+    lowered = cleaned.lower()
+    if lowered.startswith("brand.") or cleaned in {"品牌", "品牌名称"}:
+        return "品牌"
+    if lowered.startswith("city.") or cleaned in {"城市", "城市名称"}:
+        return "城市"
+    if lowered.startswith("region.") or cleaned in {"区域", "区域名称"}:
+        return "区域"
+    if lowered.startswith("province.") or cleaned in {"省份", "省份名称"}:
+        return "省份"
+    if lowered.startswith(("sponge_project.", "project.")) or cleaned in {"项目", "项目名称"}:
+        return "项目"
+    if lowered.startswith("store.") or cleaned in {"门店", "门店名称"}:
+        return "门店"
+    if "supplier" in lowered or cleaned in {"供应商", "供应商名称"}:
+        return "供应商"
+    if lowered == "job_basic_info.status":
+        return "岗位状态"
+    if lowered.endswith(".status") or cleaned == "状态":
+        return "状态"
+    if cleaned.endswith("名称") and len(cleaned) > 2:
+        return cleaned[: -len("名称")]
+    return cleaned
+
+
+def _query_plan_filter_display_value(value: str, item: dict[str, Any]) -> str:
+    description = str(item.get("description") or "").strip()
+    if str(item.get("source") or "") == "schema.enums" and description:
+        return description
+    return value.strip().strip("'\"").strip("%").strip()
+
+
+def _query_plan_filter_display_operator(operator: str) -> str:
+    normalized = operator.upper()
+    if normalized in {"=", "LIKE"}:
+        return "="
+    if normalized:
+        return f" {operator} "
+    return "="
+
+
+def _query_plan_filter_logic_label(item: dict[str, Any]) -> str:
+    logical_group = str(item.get("logicalGroup") or "")
+    logical_operator = str(item.get("logicalOperator") or "").upper()
+    if logical_group and logical_operator:
+        return f"（同组{logical_operator}）"
+    return ""
+
+
+def html_escape(value: str) -> str:
+    return (
+        value.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+_NEW_QUESTION_STARTERS = re.compile(
+    r"(?=你得查|你得|请查|请帮|另外|接下来|然后|再查|继续查|现在查|帮我查|还要查|再帮我)"
+)
+
+
+def _split_question_clauses(question: str) -> list[str]:
+    parts: list[str] = []
+    for chunk in re.split(r"[。；;\n]+", question):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        for part in _NEW_QUESTION_STARTERS.split(chunk):
+            cleaned = part.strip("，, ")
+            if cleaned:
+                parts.append(cleaned)
+    return parts
+
+
+def _isolate_current_question(question: str) -> str:
+    """When an orchestrator concatenates prior turns, keep the latest business clause."""
+    normalized = question.strip()
+    if not normalized:
+        return question
+    parts = _split_question_clauses(normalized)
+    if len(parts) <= 1:
+        return question
+    business_parts = [part for part in parts if _is_business_query(part)]
+    if not business_parts:
+        return question
+    if len(business_parts) == 1:
+        return business_parts[0]
+    return business_parts[-1]
+
+
+def _strip_result_format_instruction(question: str) -> str:
+    cleaned = question
+    patterns = [
+        r"^\s*返回\s*(?:json|yaml|html|markdown|md)\s*格式\s*的?",
+        r"[，,。；;]?\s*输出\s*(?:json|yaml|html|markdown|md)\s*(?:格式)?",
+        r"[，,。；;]?\s*用\s*表格\s*展示",
+        r"[，,。；;]?\s*以\s*(?:json|yaml|html|markdown|md)\s*(?:格式)?\s*输出",
+        r"[，,。；;]?\s*return\s+(?:json|yaml|html|markdown|md)",
+    ]
+    for pattern in patterns:
+        cleaned = re.sub(pattern, "", cleaned, flags=re.IGNORECASE)
+    return cleaned.strip() or question
+
+
+def _preserve_limit_scope_in_normalized_question(normalized_question: str, original_question: str) -> str:
+    """Keep scope words that the question-analysis LLM may omit while rewriting."""
+    normalized = normalized_question.strip() or original_question
+    if _question_requests_all_rows(original_question) and not _question_requests_all_rows(normalized):
+        return f"{normalized}；返回范围：所有数据"
+    original_limit = _requested_limit(original_question)
+    if original_limit is not None and _requested_limit(normalized) is None:
+        return f"{normalized}；返回条数：{original_limit}条"
+    return normalized
+
+
+def _require_non_empty_select(sql: str) -> None:
+    if not sql.strip():
+        raise SqlGenerationError("SQL must not be empty")
+    if not sql.strip().lower().startswith("select "):
+        raise SqlGenerationError("SQL must be SELECT only")
+
+
+def _parse_execute_unknown_column(error_text: str) -> str | None:
+    match = re.search(r"Unknown column ['`]([^'`]+)['`]", error_text, re.IGNORECASE)
+    if not match:
+        return None
+    return match.group(1).strip()
+
+
+def _repair_sql_for_local_schema_issues(
+    *,
+    candidate_sql: str,
+    sql_question: str,
+    schema: dict[str, Any],
+    generator: SamplingSqlGenerator | None,
+    schema_context: Any,
+    sql_schema_context: Any,
+    audit_logger: AuditLogger,
+    session_id: str | None,
+    max_repair_attempts: int,
+    default_limit: int,
+    max_limit: int,
+    steps: _ExecutionSteps,
+    repair_success_detail: str = "已修复本地 schema 校验问题。",
+    running_prefix: str = "本地 schema 校验失败，尝试修复",
+    failure_prefix: str = "本地 schema 校验失败，修复失败",
+    validation_error: dict[str, Any] | None = None,
+) -> tuple[str | None, str | None]:
+    if validation_error is None:
+        schema_issues = validate_sql_against_schema(candidate_sql, schema)
+        if not schema_issues:
+            return candidate_sql, None
+        if generator is None or schema_context is None:
+            return None, f"本地 schema 校验失败：{schema_issues[0].message}"
+        validation_error = build_schema_validation_error(
+            candidate_sql,
+            schema_issues,
+            schema,
+            max_attempts=max_repair_attempts,
+        )
+    elif generator is None or schema_context is None:
+        return None, str(validation_error.get("message") or "本地 schema 校验失败")
+    repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+        generator=generator,
+        question=sql_question,
+        sql=candidate_sql,
+        validation_error=validation_error,
+        schema_context=sql_schema_context,
+        audit_logger=audit_logger,
+        session_id=session_id,
+        max_attempts=max_repair_attempts,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        schema=schema,
+        check=lambda candidate: _require_no_schema_issues(candidate, schema),
+        steps=steps,
+        running_detail=f"{running_prefix}：{validation_error['message']}",
+        failure_detail=failure_prefix,
+    )
+    if repaired_sql is None:
+        return None, fail_reason
+    steps.done(9, repair_success_detail)
+    return repaired_sql, None
+
+
+def _require_time_range(
+    sql: str,
+    question: str,
+    schema: dict[str, Any],
+    query_plan: dict[str, Any] | None = None,
+) -> None:
+    if not sql_satisfies_time_range(sql, question, schema, query_plan=query_plan):
+        raise SqlGenerationError("SQL must include the requested time range filter")
+
+
+def _require_no_schema_issues(sql: str, schema: dict[str, Any]) -> None:
+    issues = validate_sql_against_schema(sql, schema)
+    if issues:
+        raise SqlGenerationError(issues[0].message)
+
+
+def _require_low_quality_pass(sql: str, question: str, schema: dict[str, Any]) -> None:
+    issue = low_quality_sql_issue_for_question(question, sql, schema=schema)
+    if issue is not None:
+        raise SqlGenerationError(issue.message)
+
+
+def _log_llm_sql_repair_audit(
+    audit_logger: AuditLogger,
+    *,
+    session_id: str | None,
+    question: str,
+    success: bool,
+    sql: str | None = None,
+    error: str | None = None,
+    attempt: int | None = None,
+) -> None:
+    audit_logger.log(
+        {
+            "sessionId": session_id,
+            "question": question,
+            "tool": "llm_sql_repair",
+            "success": success,
+            "attempt": attempt,
+            "sqlHash": sql_hash(sql) if sql else None,
+            "error": error,
+        }
+    )
+
+
+def _repair_sql_with_llm_retries(
+    *,
+    generator: SamplingSqlGenerator,
+    question: str,
+    sql: str,
+    validation_error: dict[str, Any],
+    schema_context: Any,
+    audit_logger: AuditLogger,
+    session_id: str | None,
+    max_attempts: int,
+    default_limit: int,
+    max_limit: int,
+    schema: dict[str, Any] | None,
+    check: Any,
+    steps: _ExecutionSteps,
+    running_detail: str,
+    failure_detail: str,
+) -> tuple[str | None, str]:
+    current_sql = sql
+    current_error = validation_error
+    last_reason = failure_detail
+    for attempt in range(1, max_attempts + 1):
+        steps.running(9, f"{running_detail}（第 {attempt}/{max_attempts} 次）")
+        repair_error = {
+            **current_error,
+            "attempt": attempt,
+            "maxAttempts": max_attempts,
+            "originalSql": current_sql,
+        }
+        try:
+            repaired = generator.repair(
+                question=question,
+                original_sql=current_sql,
+                validation_error=repair_error,
+                schema_context=schema_context,
+            )
+        except SqlGenerationError as exc:
+            last_reason = f"{failure_detail}：LLM 修复调用失败（第 {attempt}/{max_attempts} 次）：{exc}"
+            _log_llm_sql_repair_audit(
+                audit_logger,
+                session_id=session_id,
+                question=question,
+                success=False,
+                error=str(exc),
+                attempt=attempt,
+            )
+            continue
+        repaired_sql = _finalize_candidate_sql(
+            repaired.sql,
+            question,
+            default_limit=default_limit,
+            max_limit=max_limit,
+            schema=schema,
+        )
+        if schema is not None:
+            repaired_sql = apply_time_range_filters_from_question(repaired_sql, question, schema)
+        _log_llm_sql_repair_audit(
+            audit_logger,
+            session_id=session_id,
+            question=question,
+            success=bool(repaired_sql.strip()),
+            sql=repaired_sql if repaired_sql.strip() else None,
+            error=None if repaired_sql.strip() else "empty_sql",
+            attempt=attempt,
+        )
+        if not repaired_sql.strip():
+            last_reason = f"{failure_detail}：LLM 修复返回空 SQL（第 {attempt}/{max_attempts} 次）"
+            current_sql = repaired_sql
+            current_error = {**current_error, "message": last_reason}
+            continue
+        try:
+            check(repaired_sql)
+            steps.done(9, f"已修复 SQL（第 {attempt}/{max_attempts} 次）。")
+            return repaired_sql, ""
+        except SqlGenerationError as exc:
+            if schema is not None:
+                schema_issues = validate_sql_against_schema(repaired_sql, schema)
+                if schema_issues:
+                    current_error = build_schema_validation_error(
+                        repaired_sql,
+                        schema_issues,
+                        schema,
+                        attempt=attempt,
+                        max_attempts=max_attempts,
+                    )
+                    last_reason = f"{failure_detail}：{current_error['message']}"
+                    current_sql = repaired_sql
+                    continue
+            last_reason = f"{failure_detail}：{exc}"
+            rule_error = build_sql_rule_validation_error(
+                repaired_sql,
+                exc,
+                max_limit=max_limit,
+                attempt=attempt,
+                max_attempts=max_attempts,
+            )
+            if rule_error.get("violatingColumns") or validation_error.get("code") == "SQL_RULE_VIOLATION":
+                current_error = rule_error
+            else:
+                current_error = {
+                    **validation_error,
+                    "message": str(exc),
+                    "originalSql": repaired_sql,
+                }
+            current_sql = repaired_sql
+    return None, last_reason
+
+
+def _query_only_result(reason: str | None = None) -> QueryResult:
+    answer = reason.strip() if isinstance(reason, str) and reason.strip() else "查询未能完成，请稍后重试。"
+    return QueryResult(
+        answer=answer,
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
+def _has_query_intent(question: str) -> bool:
+    return bool(
+        _is_business_query(question)
+        or re.search(
+            r"(查询|查看|看看|搜索|统计|多少|几|哪些|有哪些|列表|明细|清单|展示|返回|输出|分析|报告|count)",
+            question,
+            flags=re.IGNORECASE,
+        )
+    )
+
+
+def _non_query_result(reason: str | None = None) -> QueryResult:
+    return QueryResult(
+        answer="目前仅支持查询功能",
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
     )
 
 
-def _sensitive_query_only_result(terms: list[str]) -> QueryResult:
+def _schema_no_match_result(question: str) -> QueryResult:
     return QueryResult(
-        answer=f"该查询包含敏感字段，{_sensitive_field_notice(terms)}已按当前 schema 判断，目前不支持该查询。",
+        answer=f"目前匹配不到 schema 里的任何表，暂不支持该查询。\n\n用户问题：{question}",
         generated_sql="",
         normalized_sql="",
         repaired_sql=None,
         validation={},
+        needs_clarification=True,
+        clarification_type="schema_no_match",
+        clarification_payload={
+            "type": "schema_no_match",
+            "baseQuestion": question,
+            "instruction": "请直接展示 answer，等待用户改写查询问题；不要替用户选择表或字段。",
+        },
     )
 
 
+def _low_quality_sql_result(message: str, generated_sql: str) -> QueryResult:
+    return QueryResult(
+        answer=message,
+        generated_sql=generated_sql,
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
+def _sensitive_query_only_result(terms: list[str], *, reason: str | None = None) -> QueryResult:
+    notice = _sensitive_field_notice(terms)
+    if isinstance(reason, str) and reason.strip():
+        answer = f"该查询包含敏感字段，{notice}{reason.strip()}"
+    else:
+        answer = f"该查询包含敏感字段，{notice}无法生成去敏后的查询 SQL。"
+    return QueryResult(
+        answer=answer,
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
+def _auth_error_result(
+    validation: dict[str, Any] | None,
+    *,
+    generated_sql: str = "",
+    repaired_sql: str | None = None,
+) -> QueryResult:
+    error = validation.get("error") if isinstance(validation, dict) else None
+    code = error.get("code") if isinstance(error, dict) else None
+    suffix = f"（错误码：{code}）" if code else ""
+    return QueryResult(
+        answer=f"当前 MCP 用户认证失败，无法校验和执行查询。请检查 MCP 访问 token 或重新登录后再试。{suffix}",
+        generated_sql=generated_sql,
+        normalized_sql="",
+        repaired_sql=repaired_sql,
+        validation=validation or {},
+    )
+
+
+def _is_auth_validation_error(code: str | None) -> bool:
+    return code in {"MCP_AUTH_INVALID_TOKEN", "MCP_AUTH_REQUIRED", "MCP_AUTH_FORBIDDEN"}
+
+
 def _business_metric_clarification_result(answer: str) -> QueryResult:
     return QueryResult(
         answer=answer,
@@ -541,6 +4038,21 @@ def _business_metric_clarification_result(answer: str) -> QueryResult:
     )
 
 
+def _empty_scope_result(question: str, result_format: str | None) -> QueryResult:
+    # Reuses the standard empty-result rendering so the requested output format is
+    # respected. Only used as legacy compatibility for older online MCP versions
+    # (see _LEGACY_EMPTY_SCOPE_CODES); the current contract returns this shape
+    # directly as a normal success result.
+    answer = render_result(question, {"success": True, "rowCount": 0, "rows": []}, result_format)
+    return QueryResult(
+        answer=answer,
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
 def _sensitive_field_notice(terms: list[str]) -> str:
     if not terms:
         return "已排除敏感字段。"
@@ -558,225 +4070,318 @@ def _generate_with_sampler(
     generator: SamplingSqlGenerator,
     question: str,
     schema_context: Any,
-) -> tuple[GeneratedSql, str | None]:
+    audit_logger: AuditLogger | None = None,
+    session_id: str | None = None,
+    max_repair_attempts: int = 2,
+    schema: dict[str, Any] | None = None,
+) -> tuple[GeneratedSql, str | None, bool]:
+    def _audit(tool: str, **fields: Any) -> None:
+        if audit_logger is None:
+            return
+        audit_logger.log(
+            {
+                "sessionId": session_id,
+                "question": question,
+                "tool": tool,
+                **fields,
+            }
+        )
+
     try:
-        return (
-            generator.generate(
-                question=question,
-                schema_context=schema_context,
-            ),
-            None,
+        generated = generator.generate(
+            question=question,
+            schema_context=schema_context,
         )
     except SqlGenerationError as sampling_exc:
-        try:
-            repaired = generator.repair(
-                question=question,
-                original_sql="",
-                validation_error={"code": type(sampling_exc).__name__, "message": str(sampling_exc)},
-                schema_context=schema_context,
-            )
-        except SqlGenerationError:
-            return GeneratedSql(sql="", tables=[], placeholders=[]), None
-        return (
-            GeneratedSql(sql="", tables=[], placeholders=[]),
-            _apply_limit_policy(
+        _audit("llm_sql_generate", success=False, error=str(sampling_exc))
+        validation_error = {"code": type(sampling_exc).__name__, "message": str(sampling_exc), "originalSql": ""}
+        for attempt in range(1, max_repair_attempts + 1):
+            try:
+                repaired = generator.repair(
+                    question=question,
+                    original_sql="",
+                    validation_error={
+                        **validation_error,
+                        "attempt": attempt,
+                        "maxAttempts": max_repair_attempts,
+                    },
+                    schema_context=schema_context,
+                )
+            except SqlGenerationError as repair_exc:
+                _audit("llm_sql_repair", success=False, error=str(repair_exc), attempt=attempt)
+                continue
+            repaired_sql = _finalize_candidate_sql(
                 repaired.sql,
                 question,
                 default_limit=generator.default_limit,
                 max_limit=generator.max_limit,
-            ),
-        )
+                schema=schema,
+            )
+            _audit(
+                "llm_sql_repair",
+                success=bool(repaired_sql.strip()),
+                sqlHash=sql_hash(repaired_sql) if repaired_sql.strip() else None,
+                error=None if repaired_sql.strip() else "empty_sql",
+                attempt=attempt,
+            )
+            if repaired_sql.strip():
+                return (
+                    GeneratedSql(sql="", tables=[], placeholders=[]),
+                    repaired_sql,
+                    True,
+                )
+        return GeneratedSql(sql="", tables=[], placeholders=[]), None, True
+    if generated.sql.strip():
+        _audit("llm_sql_generate", success=True, sqlHash=sql_hash(generated.sql))
+    else:
+        _audit("llm_sql_generate", success=False, error="empty_sql")
+    return generated, None, False
 
 
-def _generate_rule_based_sql(
+def _generate_from_schema_example(
     *,
     question: str,
-    schema: dict[str, Any],
-    default_limit: int,
-    max_limit: int,
-) -> GeneratedSql:
-    generator = RuleBasedSqlGenerator(
-        default_limit=default_limit,
-        max_limit=max_limit,
-    )
-    return generator.generate(
-        question=question,
-        schema=schema,
+    schema_context: Any,
+) -> GeneratedSql | None:
+    examples = _business_examples(getattr(schema_context, "examples", []) or [])
+    best: tuple[int, dict[str, Any]] | None = None
+    for example in examples:
+        if not isinstance(example, dict) or not isinstance(example.get("sql"), str):
+            continue
+        if not _is_high_match_example(question, str(example.get("question") or "")):
+            continue
+        score = _example_match_score(question, str(example.get("question") or ""))
+        if best is None or score > best[0]:
+            best = (score, example)
+    if best is None:
+        return None
+    example = best[1]
+    tables = example.get("tables") if isinstance(example.get("tables"), list) else []
+    return GeneratedSql(
+        sql=str(example["sql"]).strip(),
+        tables=[str(table) for table in tables],
+        placeholders=[],
     )
 
 
-def _generate_sampling_fallback_sql(
-    *,
-    question: str,
-    schema: dict[str, Any],
-    default_limit: int,
-    max_limit: int,
-) -> GeneratedSql:
-    if re.search(r"(岗位|职位|招聘|在招)", question) is None:
-        raise SqlGenerationError("No sampling fallback matched the question")
-    return _generate_rule_based_sql(
-        question=question,
-        schema=schema,
-        default_limit=default_limit,
-        max_limit=max_limit,
-    )
+def _is_high_match_example(question: str, example_question: str) -> bool:
+    if not question or not example_question:
+        return False
+    question_compact = _compact_match_text(question)
+    example_compact = _compact_match_text(example_question)
+    if len(example_compact) >= 12 and (example_compact in question_compact or question_compact in example_compact):
+        return True
+    question_tokens = set(_match_tokens(question))
+    example_tokens = set(_match_tokens(example_question))
+    if not question_tokens or not example_tokens:
+        return False
+    overlap = len(question_tokens & example_tokens)
+    return overlap >= 8 and overlap / min(len(question_tokens), len(example_tokens)) >= 0.65
 
 
-def _make_query_sql_cache(config: AppConfig) -> QuerySqlCache | None:
-    if config.sql.query_cache_path is None:
-        return None
-    return QuerySqlCache(config.sql.query_cache_path, config.sql.query_cache_ttl_minutes)
+def _example_match_score(question: str, example_question: str) -> int:
+    question_tokens = set(_match_tokens(question))
+    example_tokens = set(_match_tokens(example_question))
+    return len(question_tokens & example_tokens)
 
 
-def _is_mutation_request(question: str) -> bool:
-    mutation_match = re.search(
-        r"(新增|新建|创建|添加|插入|录入|修改|更新|编辑|变更|调整|删除|移除|作废|发布|下架|保存|提交|审批|导入|同步|insert|update|delete|create|drop|alter|truncate)",
-        question,
-        flags=re.IGNORECASE,
-    )
-    if mutation_match is None:
-        return False
-    if _is_mutation_analytics_request(question):
-        return False
-    return True
+def _compact_match_text(text: str) -> str:
+    return "".join(re.findall(r"[A-Za-z0-9\u4e00-\u9fff]+", text.lower()))
 
 
-def _is_mutation_analytics_request(question: str) -> bool:
-    return bool(
-        re.search(r"(统计|查询|查看|看看|多少|几次|次数|数量|count|列表|明细|记录|日志|历史|趋势|分组)", question, flags=re.IGNORECASE)
-        and re.search(r"(新增|新建|创建|添加|插入|录入|修改|更新|编辑|变更|调整|删除|移除|作废|发布|下架|保存|提交|审批|导入|同步)", question)
-        and re.search(r"(次数|数量|count|列表|明细|记录|日志|历史|趋势|分组|显示|展示|返回|包含|字段)", question, flags=re.IGNORECASE)
-    )
+def _match_tokens(text: str) -> list[str]:
+    compact = _compact_match_text(text)
+    tokens = re.findall(r"[a-z0-9]+", compact)
+    cjk = "".join(re.findall(r"[\u4e00-\u9fff]+", compact))
+    for index in range(max(0, len(cjk) - 1)):
+        tokens.append(cjk[index : index + 2])
+    return list(dict.fromkeys(tokens))
 
 
 def _business_metric_clarification(question: str, schema: dict[str, Any]) -> str | None:
-    if is_recruiting_match_effect_query(question):
-        return None
-    metric_terms = _ambiguous_business_metric_terms(question)
-    if not metric_terms:
-        return None
-    if _schema_has_metric_definition(question, schema, metric_terms):
-        return None
-
-    lines = [
-        "这个查询涉及业务口径，我暂时不直接生成 SQL，避免结果口径不准。",
-        "",
-        "请先确认：",
-        f"1. 指标定义：“{'、'.join(metric_terms)}”具体包含哪些数据？",
-        "2. 时间口径：按哪个时间字段统计？",
-        "3. 状态口径：哪些状态算有效/成功/完成/异常？",
-        "4. 聚合维度：需要按什么维度展示？",
-    ]
-    return "\n".join(lines)
+    return None
 
 
 def _unsupported_requested_field_message(question: str, schema: dict[str, Any]) -> str | None:
-    if "供应商" not in question:
-        return None
-    if not re.search(r"(报名|工单|候选人|人员|清单|明细)", question):
-        return None
-    if not _schema_has_table(schema, "supplier") or not _schema_has_column(schema, "supplier", "nick_name"):
-        return "当前 schema 不支持“供应商”字段的查询，可联系管理员补充。"
-    if not _schema_supports_work_order_supplier_relation(schema):
-        return "当前 schema 缺少“供应商”的关联关系，可联系管理员补充。"
     return None
 
 
-def _schema_supports_work_order_supplier_relation(schema: dict[str, Any]) -> bool:
-    return (
-        _schema_has_join(schema, "mvp_applied_jobs_by_helped_account", "c_helped_account")
-        and _schema_has_join(schema, "c_helped_account", "resume")
-        and (
-            _schema_has_join(schema, "resume", "supplier")
-            or (_schema_has_column(schema, "resume", "supplier_id") and _schema_has_column(schema, "supplier", "id"))
-        )
-    )
+def _required_schema_concepts_gap_message(analysis: QuestionAnalysis, schema: dict[str, Any]) -> str | None:
+    missing_labels: list[str] = []
+    for required in analysis.required_concepts:
+        if not isinstance(required, dict):
+            continue
+        if _required_concept_is_defined(required, schema):
+            continue
+        label = str(required.get("label") or required.get("name") or "").strip()
+        if label:
+            missing_labels.append(label)
+    if not missing_labels:
+        return None
+    if len(missing_labels) == 1:
+        return f"schema 缺少{missing_labels[0]}口径"
+    return "schema 缺少以下口径：" + "、".join(missing_labels)
 
 
-def _schema_has_table(schema: dict[str, Any], table_name: str) -> bool:
-    tables = schema.get("tables", [])
-    return isinstance(tables, list) and any(
-        isinstance(table, dict) and str(table.get("tableName") or table.get("name") or "") == table_name
-        for table in tables
-    )
+def _required_concept_search_terms(required: dict[str, Any]) -> list[str]:
+    terms: list[str] = []
+    primary = str(required.get("name") or "").strip()
+    if primary:
+        terms.append(primary)
+    for name in required.get("fallbackNames") or []:
+        value = str(name or "").strip()
+        if value and value not in terms:
+            terms.append(value)
+    label = str(required.get("label") or "").strip()
+    if label and label not in terms:
+        terms.append(label)
+    return terms
 
 
-def _schema_has_column(schema: dict[str, Any], table_name: str, column_name: str) -> bool:
-    tables = schema.get("tables", [])
-    if not isinstance(tables, list):
-        return False
-    for table in tables:
-        if not isinstance(table, dict) or str(table.get("tableName") or table.get("name") or "") != table_name:
+def _required_concept_is_defined(required: dict[str, Any], schema: dict[str, Any]) -> bool:
+    terms = _required_concept_search_terms(required)
+    if not terms:
+        return True
+    business_items = _schema_concepts(schema) + _schema_metrics(schema)
+    for item in business_items:
+        if _business_definition_matches_required_terms(item, terms):
+            return True
+    glossary_targets = _schema_glossary_maps_to_targets(schema, terms)
+    for item in business_items:
+        identifiers = _business_definition_identifiers(item)
+        if identifiers & glossary_targets:
+            return True
+    return False
+
+
+def _business_definition_matches_required_terms(item: dict[str, Any], terms: list[str]) -> bool:
+    identifiers = _business_definition_identifiers(item)
+    if any(term in identifiers for term in terms):
+        return True
+    for term in terms:
+        if not term:
             continue
-        columns = table.get("columns", [])
-        if not isinstance(columns, list):
-            return False
-        return any(
-            isinstance(column, dict)
-            and str(column.get("columnName") or column.get("name") or "") == column_name
-            for column in columns
-        )
+        for key in ("comment", "description"):
+            body = str(item.get(key) or "")
+            if term in body:
+                return True
+        for example in item.get("positiveExamples") or []:
+            example_text = str(example or "").strip()
+            if term == example_text or term in example_text:
+                return True
     return False
 
 
-def _schema_has_join(schema: dict[str, Any], left_table: str, right_table: str) -> bool:
-    joins = schema.get("joins", [])
-    if not isinstance(joins, list):
-        return False
-    for join in joins:
-        if not isinstance(join, dict):
+def _business_definition_identifiers(item: dict[str, Any]) -> set[str]:
+    identifiers: set[str] = set()
+    for key in ("name", "id", "term", "metric", "baseTable", "comment"):
+        value = str(item.get(key) or "").strip()
+        if value:
+            identifiers.add(value)
+    for key in ("requiredTables", "positiveExamples", "filters"):
+        values = item.get(key)
+        if not isinstance(values, list):
+            continue
+        for entry in values:
+            value = str(entry or "").strip()
+            if value:
+                identifiers.add(value)
+    return identifiers
+
+
+def _schema_glossary_maps_to_targets(schema: dict[str, Any], terms: list[str]) -> set[str]:
+    targets: set[str] = set()
+    for item in _schema_glossary(schema):
+        if not isinstance(item, dict):
+            continue
+        maps_to = str(item.get("mapsTo") or "").strip()
+        if not maps_to:
             continue
-        join_tables = {
-            str(join.get("leftTable") or join.get("from") or ""),
-            str(join.get("rightTable") or join.get("to") or ""),
+        searchable = {
+            maps_to,
+            str(item.get("term") or "").strip(),
+            str(item.get("description") or "").strip(),
         }
-        if {left_table, right_table} <= join_tables:
-            return True
-    return False
+        if any(term in searchable or term in str(item.get("description") or "") for term in terms if term):
+            targets.add(maps_to)
+    return targets
 
 
-def _ambiguous_business_metric_terms(question: str) -> list[str]:
-    terms = (
-        "漏斗",
-        "转化率",
-        "转化",
-        "有效",
-        "活跃",
-        "成功率",
-        "留存",
-        "履约",
-        "异常",
-        "质量",
-        "效率",
-        "趋势",
-        "健康度",
-        "达成率",
-        "完成率",
-    )
-    return [term for term in terms if term in question]
-
-
-def _schema_has_metric_definition(question: str, schema: dict[str, Any], metric_terms: list[str]) -> bool:
-    metric_texts: list[str] = []
-    for metric in schema.get("metrics") or []:
-        if not isinstance(metric, dict):
-            continue
-        parts: list[str] = []
-        for key in ("name", "term", "displayName", "definition", "description", "aggregation"):
-            value = metric.get(key)
-            if isinstance(value, str):
-                parts.append(value)
-        filters = metric.get("filters")
-        if isinstance(filters, list):
-            parts.extend(str(item) for item in filters)
-        metric_text = " ".join(parts)
-        if metric_text:
-            metric_texts.append(metric_text)
-            name = metric.get("name")
-            if isinstance(name, str) and name and name in question:
-                return True
+def _schema_glossary(schema: dict[str, Any]) -> list[dict[str, Any]]:
+    glossary = schema.get("glossary")
+    if isinstance(glossary, list):
+        return [item for item in glossary if isinstance(item, dict)]
+    return []
+
+
+def _schema_concepts(schema: dict[str, Any]) -> list[dict[str, Any]]:
+    concepts = _schema_structure(schema).get("concepts")
+    if isinstance(concepts, list):
+        return [concept for concept in concepts if isinstance(concept, dict)]
+    legacy_concepts = schema.get("concepts")
+    if isinstance(legacy_concepts, list):
+        return [concept for concept in legacy_concepts if isinstance(concept, dict)]
+    return []
+
+
+def _schema_structure(schema: dict[str, Any]) -> dict[str, Any]:
+    structure = schema.get("structure")
+    return structure if isinstance(structure, dict) else {}
+
+
+def _schema_relations(schema: dict[str, Any]) -> list[dict[str, Any]]:
+    relations = _schema_structure(schema).get("relations")
+    if isinstance(relations, list):
+        return [relation for relation in relations if isinstance(relation, dict)]
+    joins = schema.get("joins")
+    if isinstance(joins, list):
+        return [join for join in joins if isinstance(join, dict)]
+    return []
+
+
+def _schema_metrics(schema: dict[str, Any]) -> list[dict[str, Any]]:
+    metrics = _schema_structure(schema).get("metrics")
+    if isinstance(metrics, list):
+        return [metric for metric in metrics if isinstance(metric, dict)]
+    legacy_metrics = schema.get("metrics")
+    if isinstance(legacy_metrics, list):
+        return [metric for metric in legacy_metrics if isinstance(metric, dict)]
+    return []
+
+
+def _relation_left(relation: dict[str, Any]) -> tuple[str, str]:
+    table = str(relation.get("leftTable") or "")
+    column = str(relation.get("leftColumn") or relation.get("fromColumn") or "")
+    if table:
+        return table, column
+    return _split_field_ref(str(relation.get("from") or ""))
+
+
+def _relation_right(relation: dict[str, Any]) -> tuple[str, str]:
+    table = str(relation.get("rightTable") or "")
+    column = str(relation.get("rightColumn") or relation.get("toColumn") or "")
+    if table:
+        return table, column
+    return _split_field_ref(str(relation.get("to") or ""))
 
-    return any(term in metric_text for term in metric_terms for metric_text in metric_texts)
+
+def _split_field_ref(value: str) -> tuple[str, str]:
+    if "." not in value:
+        return value, ""
+    table, column = value.split(".", 1)
+    return table, column
+
+
+def _finalize_candidate_sql(
+    sql: str,
+    question: str,
+    *,
+    default_limit: int,
+    max_limit: int,
+    schema: dict[str, Any] | None = None,
+) -> str:
+    normalized = finalize_generated_sql(sql, question, schema=schema)
+    return _apply_limit_policy(normalized, question, default_limit=default_limit, max_limit=max_limit)
 
 
 def _apply_limit_policy(sql: str, question: str, *, default_limit: int, max_limit: int) -> str:
@@ -795,7 +4400,10 @@ def _apply_default_limit(sql: str, question: str, default_limit: int) -> str:
 
 
 def _replace_limit(sql: str, limit: int) -> str:
-    return re.sub(r"\blimit\s+\d+\b", f"LIMIT {limit}", sql, count=1, flags=re.IGNORECASE)
+    stripped = sql.strip().rstrip(";")
+    if re.search(r"\blimit\s+\d+\b", stripped, flags=re.IGNORECASE):
+        return re.sub(r"\blimit\s+\d+\b", f"LIMIT {limit}", stripped, count=1, flags=re.IGNORECASE)
+    return f"{stripped} LIMIT {limit}"
 
 
 def _question_requests_limit(question: str) -> bool:
@@ -823,8 +4431,8 @@ def _question_requests_all_rows(question: str) -> bool:
     lowered = question.lower()
     return bool(
         re.search(r"(所有|全部|全量|完整)", question)
-        or re.search(r"(导出|生成|下载).{0,12}(excel|xlsx|表格|文件)", lowered)
-        or re.search(r"(excel|xlsx).{0,12}(导出|生成|下载)", lowered)
+        or re.search(r"(导出|生成|下载).{0,12}(excel|xlsx|csv|表格|文件)", lowered)
+        or re.search(r"(excel|xlsx|csv).{0,12}(导出|生成|下载)", lowered)
     )
 
 
@@ -832,6 +4440,28 @@ def _default_limit_notice(default_limit: int) -> str:
     return f"本次为默认查询 {default_limit} 条数据；如果需要查询更多数据，可以修改查询口径。"
 
 
+def _csv_export_notice(question: str, result: dict[str, Any]) -> str | None:
+    if not _question_requests_all_rows(question):
+        return None
+    if not result.get("success", True):
+        return None
+    export = export_result_to_csv(result)
+    if export is None:
+        return None
+    try:
+        row_count = int(result.get("rowCount", export.row_count))
+    except (TypeError, ValueError):
+        row_count = export.row_count
+    if row_count > export.row_count:
+        count_text = f"查询匹配 {row_count} 条，本次 CSV 写入当前返回的 {export.row_count} 条。"
+    else:
+        count_text = f"查询返回 {export.row_count} 条数据。"
+    return (
+        f"{count_text}因为页面展示大量数据不太友好，已生成可用 Excel 打开的 CSV 文件："
+        f"{export.path}"
+    )
+
+
 def _should_append_default_limit_notice(*, question: str, result: dict[str, Any], default_limit: int) -> bool:
     if _question_requests_limit(question):
         return False