@roll-agent/octopus-agent 0.1.1 → 0.1.3

package/src/octopus_skill/agent.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import json
 import re
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -93,6 +95,7 @@ class QueryResult:
     clarification_payload: dict[str, Any] | None = None
     query_plan: dict[str, Any] | None = None
     execution_steps: list[dict[str, Any]] = field(default_factory=list)
+    timing: dict[str, Any] = field(default_factory=dict)
     raw_result: dict[str, Any] | None = None
     result_format: str | None = None
 
@@ -150,21 +153,24 @@ class SpongeAgent:
         fast_mode: bool = True,
     ) -> QueryResult:
         steps = _ExecutionSteps()
-        steps.done(1, "已进入 query_sponge")
+        steps.running(1)
         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.done(1, "已进入 query_sponge")
+        # Step 2: 确认 schema 与最新版本一致（分析前必须完成，供 agentInstructions 使用）
         steps.running(2)
+        try:
+            schema, schema_ensure_detail = self._ensure_schema()
+        except Exception as exc:
+            reason = f"{type(exc).__name__}: {exc}"
+            steps.error(2, reason)
+            return _attach_execution_steps(_query_only_result(reason), steps)
+        pre_sql_agent_instructions = _schema_agent_instructions(schema)
+        steps.done(2, schema_ensure_detail or f"schemaVersion={schema.get('schemaVersion') or 'unknown'}")
+        # Step 3: LLM 需求分析
+        steps.running(3)
         if sampler is None:
             reason = "当前无模型可用，请确认配置文件。"
-            steps.error(2, reason)
+            steps.error(3, reason)
             return _attach_execution_steps(_query_only_result(reason), steps)
         try:
             analysis = analyze_question(
@@ -174,15 +180,15 @@ class SpongeAgent:
             )
         except QuestionAnalysisError as exc:
             reason = f"需求分析失败：{exc}"
-            steps.error(2, reason)
+            steps.error(3, 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)
+            steps.error(3, reason)
             return _attach_execution_steps(_non_query_result(reason), steps)
         if analysis.intent == "non_query":
             reason = analysis.clarification_reason or "请先输入明确的业务数据查询需求。"
-            steps.error(2, reason)
+            steps.error(3, reason)
             return _attach_execution_steps(_non_query_result(reason), steps)
         # intent == "query"
         sql_question = _preserve_limit_scope_in_normalized_question(
@@ -191,7 +197,7 @@ class SpongeAgent:
         )
         time_range_question = _time_range_source_question(user_question, sql_question)
         steps.done(
-            2,
+            3,
             f"意图=query（{analysis.confidence:.0%}）；"
             f"对象={analysis.target_entities or '未提取'}；"
             f"规范化问题={sql_question}",
@@ -215,15 +221,6 @@ class SpongeAgent:
             session_id=session_id or new_session_id(),
         )
         sensitive_terms = sensitive_terms_in_text(sql_question)
-        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)
@@ -237,49 +234,70 @@ class SpongeAgent:
             steps.error(4, "业务指标口径不明确，需要用户先确认指标、时间、状态和聚合维度。")
             return _attach_execution_steps(_business_metric_clarification_result(business_clarification), steps)
         repaired_sql: str | None = None
+        # Step 4: schemaContext 匹配与实体检索并行
+        # 实体检索先复用步骤 3 的候选并发起 search_entities；schemaContext 本地匹配同时进行。
+        # schemaContext 完成后补齐仅依赖匹配结果的 schema 路径候选。
         steps.running(4)
-        try:
-            schema_context = retrieve_schema_context(
-                schema,
+
+        def _match_schema_context() -> Any:
+            return retrieve_schema_context(schema, sql_question)
+
+        def _resolve_entities_from_analysis() -> dict[str, Any] | None:
+            return self._search_entities_for_question(
+                context,
                 sql_question,
+                None,
+                schema,
+                sampler=sampler,
+                analysis=analysis,
+                agent_instructions=pre_sql_agent_instructions,
             )
-        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,
+
+        with ThreadPoolExecutor(max_workers=2) as executor:
+            future_context = executor.submit(_match_schema_context)
+            future_entities = executor.submit(_resolve_entities_from_analysis)
+            try:
+                schema_context = future_context.result()
+            except Exception as exc:
+                reason = f"{type(exc).__name__}: {exc}"
+                steps.error(4, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+            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)
+            try:
+                searched_entities = future_entities.result()
+            except Exception as exc:
+                reason = f"{type(exc).__name__}: {exc}"
+                steps.error(4, reason)
+                return _attach_execution_steps(_query_only_result(reason), steps)
+
+        searched_entities = _merge_schema_context_entity_candidates(
+            searched_entities,
             sql_question,
             schema_context,
-            schema,
-            sampler=sampler,
             analysis=analysis,
         )
-        steps.done(5, _entity_search_step_detail(searched_entities))
-        steps.running(6)
+        steps.done(
+            4,
+            f"{_schema_context_step_detail(schema_context)}；{_entity_search_step_detail(searched_entities)}",
+        )
+        steps.running(5)
         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,
@@ -297,9 +315,9 @@ class SpongeAgent:
             )
             if generated is None:
                 reason = "未提供 sampler，且 schema examples 没有匹配到可复用 SQL。"
-                steps.error(7, reason)
+                steps.error(5, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
-            steps.done(7, "已从 schema examples 匹配 SQL。")
+            steps.done(5, "已生成查询计划并从 schema examples 匹配 SQL。")
         else:
             generator = SamplingSqlGenerator(
                 sampler=sampler,
@@ -322,12 +340,12 @@ class SpongeAgent:
                 query_plan=query_plan,
             )
             if generation_clarification is not None:
-                steps.waiting(7, "LLM 判断需要用户补充信息。")
+                steps.waiting(5, "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)
+                    steps.error(5, reason)
                     return _attach_execution_steps(_query_only_result(reason), steps)
                 repaired_sql, fail_reason = _repair_sql_with_llm_retries(
                     generator=generator,
@@ -351,9 +369,9 @@ class SpongeAgent:
                     failure_detail="LLM 返回空 SQL，修复失败",
                 )
                 if repaired_sql is None:
-                    steps.error(9, fail_reason)
+                    steps.error(7, fail_reason)
                     return _attach_execution_steps(_query_only_result(fail_reason), steps)
-            steps.done(7, "已通过 LLM 生成 SQL。")
+            steps.done(5, "已生成查询计划并通过 LLM 生成 SQL。")
         candidate_sql = repaired_sql or _finalize_candidate_sql(
             generated.sql,
             sql_question,
@@ -374,7 +392,7 @@ class SpongeAgent:
             )
             if sampler is None or schema_context is None or generator is None:
                 reason = f"{quality_message}；当前没有 sampler 可修复。"
-                steps.error(8, reason)
+                steps.error(6, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
                 generator=generator,
@@ -401,22 +419,26 @@ class SpongeAgent:
                 failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
-                steps.error(9, fail_reason)
+                steps.error(7, fail_reason)
                 return _attach_execution_steps(_query_only_result(fail_reason), steps)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            steps.done(9, "已补充时间范围过滤。")
+            steps.done(7, "已补充时间范围过滤。")
         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)
             quality_message = _query_quality_failure_message(
                 f"SQL 缺少查询计划中的筛选条件：{'; '.join(missing_filters)}。",
                 missing_items=missing_filters,
                 current_problem="当前 SQL 没有覆盖用户已确认的关键筛选，执行后可能返回范围过宽或不相关的数据。",
-                repair_hint="必须 JOIN 相关表，并把缺失的 table.column 过滤写入 WHERE；同组 OR 条件需要用括号包裹。",
+                repair_hint=(
+                    "必须 JOIN 相关表，并把缺失的 table.column 过滤写入 WHERE；"
+                    "同组 OR 条件需要用括号包裹；"
+                    "不同地点维度的 city.name 与 region.name（如苏州与昆山市）必须用 AND，禁止写成 OR。"
+                ),
             )
             if sampler is None or schema_context is None or generator is None:
                 reason = quality_message
-                steps.error(8, reason)
+                steps.error(6, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
                 generator=generator,
@@ -428,8 +450,11 @@ class SpongeAgent:
                     "originalSql": candidate_sql,
                     "missingFilters": missing_filters,
                     "missingItems": missing_filters,
-                    "currentProblem": "当前 SQL 没有覆盖用户已确认的关键筛选。",
-                    "repairHint": "必须 JOIN 相关表，并把缺失的 table.column 过滤写入 WHERE。",
+                    "currentProblem": "当前 SQL 没有覆盖用户已确认的关键筛选，或把层级地点条件错误写成了 OR。",
+                    "repairHint": (
+                        "必须 JOIN 相关表，并把缺失的 table.column 过滤写入 WHERE；"
+                        "city.name 与 region.name 若表示地级市+下级区县，必须 AND。"
+                    ),
                 },
                 schema_context=sql_schema_context,
                 audit_logger=self.audit_logger,
@@ -444,11 +469,11 @@ class SpongeAgent:
                 failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
-                steps.error(9, fail_reason)
+                steps.error(7, fail_reason)
                 return _attach_execution_steps(_query_only_result(fail_reason), steps)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            steps.done(9, "已补充查询计划筛选条件。")
+            steps.done(7, "已补充查询计划筛选条件。")
         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)
             quality_message = _query_quality_failure_message(
@@ -459,7 +484,7 @@ class SpongeAgent:
             )
             if sampler is None or schema_context is None or generator is None:
                 reason = quality_message
-                steps.error(8, reason)
+                steps.error(6, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
                 generator=generator,
@@ -487,16 +512,16 @@ class SpongeAgent:
                 failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
-                steps.error(9, fail_reason)
+                steps.error(7, fail_reason)
                 return _attach_execution_steps(_query_only_result(fail_reason), steps)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            steps.done(9, "已补充查询计划展示字段。")
+            steps.done(7, "已补充查询计划展示字段。")
         low_quality_issue = low_quality_sql_issue_for_question(sql_question, candidate_sql, schema=schema)
         if low_quality_issue is not None:
             quality_message = format_sql_quality_issue(low_quality_issue)
             if sampler is None or schema_context is None or generator is None:
-                steps.error(8, quality_message)
+                steps.error(6, quality_message)
                 return _attach_execution_steps(_low_quality_sql_result(quality_message, candidate_sql), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
                 generator=generator,
@@ -523,11 +548,11 @@ class SpongeAgent:
                 failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
-                steps.error(9, fail_reason)
+                steps.error(7, fail_reason)
                 return _attach_execution_steps(_low_quality_sql_result(fail_reason, candidate_sql), steps)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
             candidate_sql = repaired_sql
-            steps.done(9, "已修复 SQL 质量问题。")
+            steps.done(7, "已修复 SQL 质量问题。")
         prior_sql = candidate_sql
         candidate_sql, schema_fail = _repair_sql_for_local_schema_issues(
             candidate_sql=candidate_sql,
@@ -544,7 +569,7 @@ class SpongeAgent:
             steps=steps,
         )
         if schema_fail:
-            steps.error(8, schema_fail)
+            steps.error(6, schema_fail)
             return _attach_execution_steps(_query_only_result(schema_fail), steps)
         if candidate_sql != prior_sql:
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
@@ -556,13 +581,13 @@ class SpongeAgent:
             schema=schema,
         )
         try:
-            steps.running(8)
+            steps.running(6)
             enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
-            steps.done(8, "SQL 满足只读、安全、LIMIT、中文别名等规则。")
+            steps.done(6, "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)
+                steps.error(6, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             if _is_sensitive_sql_error(exc) and sensitive_terms:
                 validation_error = {
@@ -602,15 +627,14 @@ class SpongeAgent:
                 failure_detail=failure_detail,
             )
             if repaired_sql is None:
-                steps.error(9, fail_reason)
+                steps.error(7, 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 无需修复。")
+            steps.done(6, "SQL 修复后满足本地规则。")
+        _skip_repair_step_if_pending(steps, "SQL 无需修复。")
         prior_sql = candidate_sql
         candidate_sql, schema_fail = _repair_sql_for_local_schema_issues(
             candidate_sql=candidate_sql,
@@ -629,7 +653,7 @@ class SpongeAgent:
             running_prefix="validate_sql 前本地 schema 校验失败，尝试修复",
         )
         if schema_fail:
-            steps.error(10, 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=[])
@@ -656,7 +680,7 @@ class SpongeAgent:
                 running_prefix="补充时间范围后本地 schema 校验失败，尝试修复",
             )
             if schema_fail:
-                steps.error(10, schema_fail)
+                steps.error(8, 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)
@@ -678,23 +702,24 @@ class SpongeAgent:
             steps=steps,
             audit_logger=self.audit_logger,
             session_id=context.session_id,
+            enable_expert_review=not fast_mode,
         )
         if expert_fail:
-            steps.error(10, expert_fail)
+            steps.error(8, expert_fail)
             return _attach_execution_steps(_query_only_result(expert_fail), steps)
         if candidate_sql != prior_sql:
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
             repaired_sql = candidate_sql
-        steps.running(10)
+        steps.running(8)
         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)
+            steps.error(8, 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)
+            steps.error(8, reason)
             return _attach_execution_steps(
                 _auth_error_result(
                     self._last_validation_result,
@@ -708,7 +733,7 @@ class SpongeAgent:
             # 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 返回旧版空权限错误，按空结果兼容处理。")
+            steps.done(8, "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
@@ -717,7 +742,7 @@ class SpongeAgent:
             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} 次）")
+                steps.running(7, f"validate_sql 失败，尝试修复：{validate_message}（第 {attempt}/{self.config.sql.max_repair_attempts} 次）")
                 repair_error = {
                     **validation_error,
                     "attempt": attempt,
@@ -771,7 +796,7 @@ class SpongeAgent:
                 except SqlGenerationError as exc:
                     if _is_sensitive_sql_error(exc) and sensitive_terms:
                         reason = f"validate_sql 修复后包含敏感字段：{exc}"
-                        steps.error(9, reason)
+                        steps.error(7, 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(
@@ -802,15 +827,15 @@ class SpongeAgent:
                     normalized_sql = self._validate_sql(context, user_question, repaired_sql)
                 except Exception as exc:
                     reason = f"{type(exc).__name__}: {exc}"
-                    steps.error(10, reason)
+                    steps.error(8, 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} 次）。")
+                    steps.done(7, 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)
+                    steps.error(8, reason)
                     return _attach_execution_steps(
                         _auth_error_result(
                             self._last_validation_result,
@@ -825,15 +850,15 @@ class SpongeAgent:
                 validation_error["originalSql"] = repaired_sql
                 current_sql = repaired_sql
             else:
-                steps.error(9, last_reason)
-                steps.error(10, last_reason)
+                steps.error(7, last_reason)
+                steps.error(8, 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)
+            steps.error(8, reason)
             return _attach_execution_steps(_query_only_result(reason), steps)
-        steps.done(10, "validate_sql 通过。")
-        steps.running(11)
+        steps.done(8, "validate_sql 通过。")
+        steps.running(9)
         try:
             result = self._execute_sql(context, user_question, normalized_sql)
         except Exception as exc:
@@ -868,7 +893,7 @@ class SpongeAgent:
                 )
                 if repaired_exec_sql is None:
                     reason = fail_reason or f"{type(exc).__name__}: {exc}"
-                    steps.error(11, reason)
+                    steps.error(9, reason)
                     return _attach_execution_steps(_query_only_result(reason), steps)
                 if query_plan:
                     repaired_exec_sql = apply_time_range_filters_from_plan(repaired_exec_sql, query_plan)
@@ -879,23 +904,23 @@ class SpongeAgent:
                     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)
+                    steps.error(8, reason)
                     return _attach_execution_steps(_query_only_result(reason), steps)
                 if revalidated is None:
                     reason = (
                         f"execute 聚合函数用法修复后 validate_sql 失败："
                         f"{_validation_error_message(self._last_validation_result)}"
                     )
-                    steps.error(10, reason)
+                    steps.error(8, reason)
                     return _attach_execution_steps(_query_only_result(reason), steps)
                 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')}")
+                    steps.done(9, f"execute_sql 完成，rowCount={result.get('rowCount')}")
                 except Exception as retry_exc:
                     reason = f"{type(retry_exc).__name__}: {retry_exc}"
-                    steps.error(11, reason)
+                    steps.error(9, reason)
                     return _attach_execution_steps(_query_only_result(reason), steps)
             elif (
                 unknown_col
@@ -951,43 +976,43 @@ class SpongeAgent:
                             running_prefix="execute 修复补充时间范围后本地 schema 校验失败，尝试修复",
                         )
                         if schema_fail:
-                            steps.error(10, schema_fail)
+                            steps.error(8, 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)
+                        steps.error(8, 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')}")
+                            steps.done(9, f"execute_sql 完成，rowCount={result.get('rowCount')}")
                         except Exception as retry_exc:
                             reason = f"{type(retry_exc).__name__}: {retry_exc}"
-                            steps.error(11, reason)
+                            steps.error(9, 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)
+                        steps.error(8, reason)
                         return _attach_execution_steps(_query_only_result(reason), steps)
                 else:
                     reason = fail_reason or f"{type(exc).__name__}: {exc}"
-                    steps.error(11, reason)
+                    steps.error(9, reason)
                     return _attach_execution_steps(_query_only_result(reason), steps)
             else:
                 reason = f"{type(exc).__name__}: {exc}"
-                steps.error(11, reason)
+                steps.error(9, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
         else:
-            steps.done(11, f"execute_sql 完成，rowCount={result.get('rowCount')}")
+            steps.done(9, f"execute_sql 完成，rowCount={result.get('rowCount')}")
         result = self._ensure_limited_flag(result)
-        steps.running(12)
+        steps.running(10)
         try:
             if sampler is not None:
                 answer = render_result_with_llm(
@@ -1001,7 +1026,7 @@ class SpongeAgent:
                 answer = render_result(user_question, result, result_format)
         except Exception as exc:
             reason = f"{type(exc).__name__}: {exc}"
-            steps.error(12, reason)
+            steps.error(10, 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)
@@ -1031,8 +1056,8 @@ class SpongeAgent:
                 result_format,
                 _sensitive_field_notice(sensitive_terms),
             )
-        steps.done(12, "LLM 已渲染结果并返回。" if sampler is not None else "结果已渲染并返回。")
-        return _attach_execution_steps(QueryResult(
+        steps.done(10, "结果已渲染并返回。")
+        result_with_steps = _attach_execution_steps(QueryResult(
             answer=answer,
             generated_sql=generated.sql,
             normalized_sql=normalized_sql,
@@ -1042,55 +1067,98 @@ class SpongeAgent:
             raw_result=result,
             result_format=result_format,
         ), steps)
+        self.audit_logger.log(
+            {
+                "sessionId": context.session_id,
+                "question": user_question,
+                "tool": "query_timing",
+                "timing": result_with_steps.timing,
+            }
+        )
+        return result_with_steps
 
-    def _ensure_schema(self) -> dict[str, Any]:
+    def _ensure_schema(self) -> tuple[dict[str, Any], str]:
+        """Load schema only when local cache is confirmed to match the latest version.
+
+        Usable means either:
+        - ``get_schema`` returns ``changed=false`` for the cached ``schemaVersion``, or
+        - ``get_schema`` returns a fresh payload with ``tables`` that is saved as the new cache.
+
+        Stale local cache is never used when the latest version cannot be confirmed.
+        """
         cached_schema = self.schema_cache.load()
-        cached_version = str(cached_schema.get("schemaVersion")) if cached_schema and cached_schema.get("schemaVersion") else None
+        cached_version = (
+            str(cached_schema.get("schemaVersion"))
+            if cached_schema and cached_schema.get("schemaVersion")
+            else None
+        )
         trace_id = new_trace_id("trace_schema")
         try:
             schema_response = self.mcp_client.get_schema(
                 trace_id=trace_id,
                 schema_version=cached_version,
             )
-        except Exception:
-            if cached_schema is not None:
-                self.audit_logger.log(
-                    {
-                        "traceId": trace_id,
-                        "tool": "get_schema",
-                        "schemaVersion": cached_version,
-                        "fallback": "cached_schema",
-                    }
+        except Exception as exc:
+            self.audit_logger.log(
+                {
+                    "traceId": trace_id,
+                    "tool": "get_schema",
+                    "schemaVersion": cached_version,
+                    "versionConfirmed": False,
+                    "error": f"{type(exc).__name__}: {exc}",
+                }
+            )
+            raise RuntimeError(
+                "无法确认本地 schema 与最新版本一致："
+                f"get_schema 失败（{type(exc).__name__}: {exc}）"
+            ) from exc
+
+        if schema_response.get("changed") is False:
+            if cached_schema is None or not cached_version:
+                raise RuntimeError(
+                    "get_schema 返回 changed=false，但本地没有带 schemaVersion 的缓存，无法确认版本一致"
+                )
+            remote_version = schema_response.get("schemaVersion")
+            if remote_version is not None and str(remote_version) != cached_version:
+                raise RuntimeError(
+                    "本地 schemaVersion 与最新版本不一致："
+                    f"cache={cached_version}, latest={remote_version}"
                 )
-                return cached_schema
-            raise
-
-        if schema_response.get("changed") is False and cached_schema is not None:
             self.audit_logger.log(
                 {
                     "traceId": trace_id,
                     "tool": "get_schema",
                     "schemaVersion": cached_version,
                     "changed": False,
+                    "versionConfirmed": True,
+                    "source": "cache",
                 }
             )
-            return cached_schema
+            detail = f"已确认与最新版本一致（缓存 schemaVersion={cached_version}）"
+            return cached_schema, detail
 
         if "tables" in schema_response:
+            latest_version = schema_response.get("schemaVersion")
+            if latest_version is None or str(latest_version).strip() == "":
+                raise RuntimeError("get_schema 返回了 tables，但缺少 schemaVersion，无法确认已同步到最新版本")
             self.schema_cache.save(schema_response)
             self.audit_logger.log(
                 {
                     "traceId": trace_id,
                     "tool": "get_schema",
-                    "schemaVersion": schema_response.get("schemaVersion"),
+                    "schemaVersion": latest_version,
                     "changed": schema_response.get("changed"),
+                    "versionConfirmed": True,
+                    "source": "response",
                 }
             )
-            return schema_response
+            detail = f"已刷新到最新版本（schemaVersion={latest_version}）"
+            return schema_response, detail
 
-        if cached_schema is not None:
-            return cached_schema
-        raise RuntimeError("Sponge get_schema did not return tables and no local schema cache exists")
+        raise RuntimeError(
+            "无法确认本地 schema 与最新版本一致："
+            "get_schema 既未返回 changed=false，也未返回可刷新的 tables"
+        )
 
     def _search_entities_for_question(
         self,
@@ -1101,35 +1169,68 @@ class SpongeAgent:
         *,
         sampler: Sampler | None = None,
         analysis: QuestionAnalysis | None = None,
+        agent_instructions: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any] | None:
-        search_candidates, schema_candidates = _collect_entity_resolution_candidates(
+        instructions = agent_instructions
+        if instructions is None and schema_context is not None:
+            instructions = getattr(schema_context, "agent_instructions", []) or []
+        search_candidates, schema_candidates, question_entities = _collect_entity_resolution_candidates(
             question,
             schema,
             schema_context,
             sampler,
-            agent_instructions=getattr(schema_context, "agent_instructions", []) or [],
+            agent_instructions=instructions,
             analysis=analysis,
         )
         if not search_candidates and not schema_candidates:
-            return None
+            # Extraction already ran; keep the flat list for query plan reuse even
+            # when nothing needs remote search_entities confirmation.
+            return {
+                "traceId": "",
+                "searchedName": "",
+                "entityCandidates": [],
+                "schemaCandidates": [],
+                "searchResults": [],
+                "entities": {},
+                "questionEntities": question_entities,
+            }
 
-        search_results: list[dict[str, Any]] = []
+        search_jobs: list[tuple[dict[str, str], str, str, str]] = []
         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:
+            search_jobs.append((candidate, entity_type, name, new_trace_id("trace_entity")))
+
+        search_results: list[dict[str, Any]] = []
+        if search_jobs:
+            max_workers = min(4, len(search_jobs))
+
+            def _run_search(job: tuple[dict[str, str], str, str, str]) -> dict[str, Any] | None:
+                candidate, entity_type, name, trace_id = job
+                try:
+                    response = self.mcp_client.search_entities(
+                        trace_id=trace_id,
+                        session_id=context.session_id,
+                        entity_types=[entity_type],
+                        name=name,
+                    )
+                except AttributeError:
+                    raise
+                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}",
+                        }
+                    )
+                    return None
                 self.audit_logger.log(
                     {
                         "traceId": trace_id,
@@ -1138,28 +1239,37 @@ class SpongeAgent:
                         "tool": "search_entities",
                         "entityType": entity_type,
                         "name": name,
-                        "error": f"{type(exc).__name__}: {exc}",
+                        "matchedCount": len(_flatten_entity_search_items(response)),
                     }
                 )
-                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(
-                {
+                return {
                     "candidate": candidate,
                     "searchedName": name,
                     "entityType": entity_type,
                     "response": response,
                 }
+
+            try:
+                with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                    futures = [executor.submit(_run_search, job) for job in search_jobs]
+                    for future in as_completed(futures):
+                        item = future.result()
+                        if item is not None:
+                            search_results.append(item)
+            except AttributeError:
+                # Older/fake clients without search_entities: keep prior fail-soft behavior.
+                search_results = []
+
+            # Preserve candidate order for stable query-plan / audit readability.
+            order = {
+                (str(candidate.get("type") or ""), str(candidate.get("value") or "")): index
+                for index, (candidate, _, _, _) in enumerate(search_jobs)
+            }
+            search_results.sort(
+                key=lambda item: order.get(
+                    (str(item.get("entityType") or ""), str(item.get("searchedName") or "")),
+                    10**9,
+                )
             )
         return {
             "traceId": search_results[0]["response"].get("traceId") if search_results else "",
@@ -1168,6 +1278,7 @@ class SpongeAgent:
             "schemaCandidates": schema_candidates,
             "searchResults": search_results,
             "entities": _merge_entity_search_results(search_results),
+            "questionEntities": question_entities,
         }
 
     def _validate_sql(
@@ -1272,40 +1383,75 @@ class SpongeAgent:
 
 class _ExecutionSteps:
     def __init__(self) -> None:
+        self._query_started_at = time.perf_counter()
+        self._step_started_at: dict[int, float] = {}
         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"},
+            {"step": 2, "name": "确认 schema 与最新版本一致", "status": "pending"},
+            {"step": 3, "name": "LLM 需求分析", "status": "pending"},
+            {"step": 4, "name": "匹配 schemaContext 并检索实体", "status": "pending"},
+            {"step": 5, "name": "按查询计划生成 SQL", "status": "pending"},
+            {"step": 6, "name": "生成后按 policy 复查 SQL", "status": "pending"},
+            {"step": 7, "name": "修复 SQL", "status": "pending"},
+            {"step": 8, "name": "调用 validate_sql", "status": "pending"},
+            {"step": 9, "name": "调用 execute_sql", "status": "pending"},
+            {"step": 10, "name": "渲染并返回结果", "status": "pending"},
         ]
 
     def running(self, step: int, detail: str | None = None) -> None:
+        self._step_started_at[step] = time.perf_counter()
         self._set(step, "running", detail=detail)
 
     def done(self, step: int, detail: str | None = None) -> None:
-        self._set(step, "done", detail=detail)
+        self._finish(step, "done", detail=detail)
 
     def waiting(self, step: int, detail: str | None = None) -> None:
-        self._set(step, "waiting", detail=detail)
+        self._finish(step, "waiting", detail=detail)
 
     def skipped(self, step: int, detail: str | None = None) -> None:
-        self._set(step, "skipped", detail=detail)
+        self._finish(step, "skipped", detail=detail)
 
     def error(self, step: int, reason: str) -> None:
-        self._set(step, "error", detail=reason, error=reason)
+        self._finish(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:
+    def timing_summary(self) -> dict[str, Any]:
+        total_ms = int(round((time.perf_counter() - self._query_started_at) * 1000))
+        step_ms = {
+            str(item["step"]): int(item.get("durationMs") or 0)
+            for item in self.steps
+            if item.get("status") != "pending"
+        }
+        return {
+            "totalDurationMs": total_ms,
+            "stepDurationMs": step_ms,
+        }
+
+    def _finish(
+        self,
+        step: int,
+        status: str,
+        *,
+        detail: str | None = None,
+        error: str | None = None,
+    ) -> None:
+        started = self._step_started_at.pop(step, None)
+        elapsed_ms = 0
+        if started is not None:
+            elapsed_ms = int(round((time.perf_counter() - started) * 1000))
+        self._set(step, status, detail=detail, error=error, add_duration_ms=elapsed_ms)
+
+    def _set(
+        self,
+        step: int,
+        status: str,
+        *,
+        detail: str | None = None,
+        error: str | None = None,
+        add_duration_ms: int | None = None,
+    ) -> None:
         for item in self.steps:
             if item["step"] != step:
                 continue
@@ -1314,6 +1460,8 @@ class _ExecutionSteps:
                 item["detail"] = detail
             if error:
                 item["error"] = error
+            if add_duration_ms is not None:
+                item["durationMs"] = int(item.get("durationMs") or 0) + max(0, add_duration_ms)
             return
 
 
@@ -1330,6 +1478,9 @@ def _attach_execution_steps(result: QueryResult, steps: _ExecutionSteps) -> Quer
         clarification_payload=result.clarification_payload,
         query_plan=result.query_plan,
         execution_steps=snapshot,
+        timing=steps.timing_summary(),
+        raw_result=result.raw_result,
+        result_format=result.result_format,
     )
 
 
@@ -1352,11 +1503,14 @@ def _schema_context_step_detail(schema_context: Any) -> str:
 
 
 def _entity_search_step_detail(searched_entities: dict[str, Any] | None) -> str:
-    if not searched_entities:
-        return "未发现需要远程确认的实体。"
+    if not searched_entities or not _has_entity_resolution(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} 个实体。"
+    return (
+        "复用需求分析实体候选；"
+        f"search_entities 返回 {len(items)} 个候选；schema 路径 {schema_count} 个实体。"
+    )
 
 
 def _sql_generation_clarification_result(
@@ -1388,33 +1542,48 @@ def _validation_error_message(validation: dict[str, Any] | None) -> str:
     return code or message
 
 
+def _has_entity_resolution(searched_entities: dict[str, Any] | None) -> bool:
+    """True when Step 5 already produced search/schema candidates for the plan."""
+    if not isinstance(searched_entities, dict):
+        return False
+    return bool(
+        searched_entities.get("entityCandidates")
+        or searched_entities.get("schemaCandidates")
+        or searched_entities.get("searchResults")
+    )
+
+
+def _question_entities_from_searched_entities(
+    searched_entities: dict[str, Any],
+) -> list[dict[str, str]] | None:
+    """Consume Step 5's flat entity list only; never re-extract in the query-plan step."""
+    cached = searched_entities.get("questionEntities") or []
+    question_entities = [item for item in cached if isinstance(item, dict)]
+    if _has_entity_resolution(searched_entities):
+        # Search/schema paths already feed filters/entities; avoid duplicate slots.
+        return None
+    return question_entities
+
+
 def _build_query_plan(
     question: str,
     schema_context: Any,
     schema: dict[str, Any],
     *,
-    searched_entities: dict[str, Any] | None = None,
-    sampler: Sampler | None = None,
+    searched_entities: dict[str, Any],
     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,
-    )
+    # Step 5 already extracted entities into searched_entities.questionEntities.
+    question_entities = _question_entities_from_searched_entities(searched_entities)
     selected_concepts = match_concepts_for_question(getattr(schema_context, "concepts", []) or [], question)
     sql_filters = _query_plan_sql_filters(
         question,
         schema_context,
         searched_entities=searched_entities,
-        question_entities=question_entities if searched_entities is None else None,
+        question_entities=question_entities,
         schema=schema,
         time_range_question=time_range_question or question,
         selected_concepts=selected_concepts,
@@ -1429,7 +1598,7 @@ def _build_query_plan(
         question,
         schema_context,
         searched_entities=searched_entities,
-        question_entities=question_entities if searched_entities is None else None,
+        question_entities=question_entities,
         analysis=analysis,
     )
     plan = {
@@ -1502,11 +1671,15 @@ def _ensure_query_plan_bridge_tables(plan: dict[str, Any]) -> None:
     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_sql_filters(plan):
-            if isinstance(flt, dict) and str(flt.get("field") or "").startswith("store."):
-                has_store = True
-                break
+    needs_job_address = False
+    for flt in _plan_sql_filters(plan):
+        if not isinstance(flt, dict):
+            continue
+        field = str(flt.get("field") or "")
+        if field.startswith("store."):
+            has_store = True
+        if field.startswith("job_address.") or field in {"city.name", "region.name"}:
+            needs_job_address = True
     if not has_store:
         for entity in plan.get("entities") or []:
             if isinstance(entity, dict) and str(entity.get("type") or "") == "store":
@@ -1520,6 +1693,15 @@ def _ensure_query_plan_bridge_tables(plan: dict[str, Any]) -> None:
                 "source": "schema.planRules",
             }
         )
+        names.add("job_store")
+    if needs_job_address and names.intersection(job_tables - {"job_address"}) and "job_address" not in names:
+        tables.append(
+            {
+                "name": "job_address",
+                "description": "岗位地址。 对应表：job_address。",
+                "source": "schema.planRules",
+            }
+        )
 
 
 def _ensure_query_plan_entity_display_fields(plan: dict[str, Any]) -> None:
@@ -1851,38 +2033,124 @@ 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("县"):
+    if cleaned.endswith(("区", "县", "旗", "市")):
         base = cleaned[:-1]
         return list(dict.fromkeys([cleaned, base]))
-    return [cleaned]
+    return list(dict.fromkeys([cleaned, f"{cleaned}市"]))
 
 
-def _promote_region_search_candidate(
+def _location_place_key(value: str) -> str:
+    """Normalize a place name for comparing city/region tokens (苏州/苏州市 → 苏州)."""
+    cleaned = value.strip()
+    if not cleaned:
+        return ""
+    for suffix in ("自治州", "地区", "市", "区", "县", "旗"):
+        if cleaned.endswith(suffix) and len(cleaned) > len(suffix):
+            return cleaned[: -len(suffix)]
+    return cleaned
+
+
+def _distinct_location_place_keys(search_candidates: list[dict[str, str]]) -> set[str]:
+    keys: set[str] = set()
+    for candidate in search_candidates:
+        if str(candidate.get("type") or "") not in {"city", "region"}:
+            continue
+        key = _location_place_key(str(candidate.get("value") or ""))
+        if key:
+            keys.add(key)
+    return keys
+
+
+def _is_hierarchical_location_query(search_candidates: list[dict[str, str]]) -> bool:
+    """True when the question mentions two+ distinct places (e.g. 苏州 + 昆山市)."""
+    return len(_distinct_location_place_keys(search_candidates)) >= 2
+
+
+def _entity_hit_matches_searched_name(hit_name: str, searched_name: str) -> bool:
+    """Keep structured hits that refer to the same place token; drop loose contains matches."""
+    hit = hit_name.strip()
+    searched = searched_name.strip()
+    if not hit or not searched:
+        return bool(hit)
+    hit_key = _location_place_key(hit)
+    search_key = _location_place_key(searched)
+    if not search_key:
+        return True
+    if hit_key == search_key:
+        return True
+    if hit in {searched, search_key, f"{search_key}市", f"{search_key}区", f"{search_key}县"}:
+        return True
+    if searched in {hit, hit_key}:
+        return True
+    return False
+
+
+def _location_address_filter_values(name: str) -> list[str]:
+    cleaned = name.strip()
+    if not cleaned:
+        return []
+    variants = list(
+        dict.fromkeys(_city_name_filter_values(cleaned) + _region_name_filter_values(cleaned))
+    )
+    return variants or [cleaned]
+
+
+def _ensure_location_search_candidate(
     search_candidates: list[dict[str, str]],
-    schema_candidates: list[dict[str, str]],
     *,
+    entity_type: str,
+    label: 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)
+    key = (entity_type, value)
     if key in seen_search:
         return
     seen_search.add(key)
+    maps_to = entity_type
+    field = _entity_table_name_column(maps_to, schema) or f"{maps_to}.name"
     search_candidates.append(
         {
-            "type": "region",
-            "label": "区域",
+            "type": entity_type,
+            "label": label,
             "value": value,
             "field": field,
-            "mapsTo": "region",
+            "mapsTo": maps_to,
             "source": "search_entities.candidate",
         }
     )
+
+
+def _drop_location_schema_store_candidates(
+    schema_candidates: list[dict[str, str]],
+    *,
+    value: str,
+) -> None:
+    schema_candidates[:] = [
+        item
+        for item in schema_candidates
+        if not (str(item.get("type") or "") == "store" and str(item.get("value") or "") == value)
+    ]
+
+
+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:
+    """District-like names (区/县/旗) resolve to region only."""
+    _ensure_location_search_candidate(
+        search_candidates,
+        entity_type="region",
+        label="区域",
+        value=value,
+        schema=schema,
+        seen_search=seen_search,
+    )
     schema_candidates[:] = [
         item
         for item in schema_candidates
@@ -1901,7 +2169,7 @@ def _promote_region_search_candidate(
     ]
 
 
-def _promote_city_search_candidate(
+def _ensure_location_dual_search_candidates(
     search_candidates: list[dict[str, str]],
     schema_candidates: list[dict[str, str]],
     *,
@@ -1909,28 +2177,48 @@ def _promote_city_search_candidate(
     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",
-        }
+    """City-like place names may live in city or region (e.g. county-level 江阴市)."""
+    _ensure_location_search_candidate(
+        search_candidates,
+        entity_type="city",
+        label="城市",
+        value=value,
+        schema=schema,
+        seen_search=seen_search,
     )
-    schema_candidates[:] = [
+    _ensure_location_search_candidate(
+        search_candidates,
+        entity_type="region",
+        label="区域",
+        value=value,
+        schema=schema,
+        seen_search=seen_search,
+    )
+    _drop_location_schema_store_candidates(schema_candidates, value=value)
+    search_candidates[:] = [
         item
-        for item in schema_candidates
+        for item in search_candidates
         if not (str(item.get("type") or "") == "store" 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:
+    _ensure_location_dual_search_candidates(
+        search_candidates,
+        schema_candidates,
+        value=value,
+        schema=schema,
+        seen_search=seen_search,
+    )
+
+
 def _extract_region_tokens(question: str) -> list[str]:
     tokens: list[str] = []
     for match in re.finditer(r"([\u4e00-\u9fff]{2,4})区", question):
@@ -1989,14 +2277,147 @@ def _explicit_brand_or_project_types(llm_values: dict[str, Any]) -> set[str]:
     return {str(item) for item in explicit_types if str(item) in {"brand", "sponge_project"}}
 
 
+def _extract_hierarchical_location_pair(question: str) -> tuple[str, str] | None:
+    """Detect parent city + child region phrases like 苏州市昆山市 / 无锡市江阴市."""
+    match = re.search(
+        r"([\u4e00-\u9fff]{2,3})市([\u4e00-\u9fff]{2,4}(?:市|区|县|旗))",
+        question,
+    )
+    if not match:
+        return None
+    parent, child = match.group(1), match.group(2)
+    if _location_place_key(parent) == _location_place_key(child):
+        return None
+    return parent, child
+
+
+def _seed_hierarchical_location_candidates(
+    question: str,
+    search_candidates: list[dict[str, str]],
+    schema_candidates: list[dict[str, str]],
+    schema: dict[str, Any],
+    seen_search: set[tuple[str, str]],
+) -> None:
+    """Ensure parent city + child region are both searchable for hierarchical questions."""
+    pair = _extract_hierarchical_location_pair(question)
+    if pair is None and _is_hierarchical_location_query(search_candidates):
+        # LLM already filled distinct city + region slots (苏州 + 昆山市).
+        return
+    if pair is None:
+        # Soft pattern without 市 on parent: only when city+region slots already differ.
+        city_values = [
+            str(item.get("value") or "")
+            for item in search_candidates
+            if str(item.get("type") or "") == "city" and str(item.get("value") or "").strip()
+        ]
+        region_values = [
+            str(item.get("value") or "")
+            for item in search_candidates
+            if str(item.get("type") or "") == "region" and str(item.get("value") or "").strip()
+        ]
+        if len(city_values) == 1 and len(region_values) == 1:
+            parent, child = city_values[0], region_values[0]
+            if _location_place_key(parent) != _location_place_key(child):
+                pair = (_location_place_key(parent) or parent, child)
+        if pair is None:
+            soft = re.search(
+                r"([\u4e00-\u9fff]{2})([\u4e00-\u9fff]{2,4}(?:市|区|县|旗))",
+                question,
+            )
+            if soft and city_values and region_values:
+                parent, child = soft.group(1), soft.group(2)
+                if (
+                    _looks_like_city_name(parent)
+                    and _location_place_key(parent) != _location_place_key(child)
+                    and any(_location_place_key(parent) == _location_place_key(v) for v in city_values)
+                    and any(_location_place_key(child) == _location_place_key(v) for v in region_values)
+                ):
+                    pair = (parent, child)
+    if pair is None:
+        return
+    parent, child = pair
+    parent_key = _location_place_key(parent)
+    child_key = _location_place_key(child)
+    for item in list(search_candidates) + list(schema_candidates):
+        item_type = str(item.get("type") or "")
+        if item_type not in {"brand", "project", "sponge_project"}:
+            continue
+        name = str(item.get("value") or "")
+        if parent_key and parent_key in name:
+            return
+    # Drop fused tokens like 苏州昆山市 that should be split into city+region.
+    search_candidates[:] = [
+        item
+        for item in search_candidates
+        if not (
+            str(item.get("type") or "") in {"city", "region"}
+            and parent_key
+            and child_key
+            and parent_key in str(item.get("value") or "")
+            and child_key in str(item.get("value") or "")
+            and _location_place_key(str(item.get("value") or "")) not in {parent_key, child_key}
+        )
+    ]
+    seen_search.clear()
+    seen_search.update(
+        (str(item.get("type") or ""), str(item.get("value") or "")) for item in search_candidates
+    )
+    _ensure_location_search_candidate(
+        search_candidates,
+        entity_type="city",
+        label="城市",
+        value=parent,
+        schema=schema,
+        seen_search=seen_search,
+    )
+    if _looks_like_region_name(child) or child.endswith("市"):
+        _ensure_location_search_candidate(
+            search_candidates,
+            entity_type="region",
+            label="区域",
+            value=child,
+            schema=schema,
+            seen_search=seen_search,
+        )
+        search_candidates[:] = [
+            item
+            for item in search_candidates
+            if not (
+                str(item.get("type") or "") == "city"
+                and _location_place_key(str(item.get("value") or "")) == child_key
+            )
+        ]
+        seen_search.clear()
+        seen_search.update(
+            (str(item.get("type") or ""), str(item.get("value") or "")) for item in search_candidates
+        )
+    _drop_location_schema_store_candidates(schema_candidates, value=parent)
+    _drop_location_schema_store_candidates(schema_candidates, value=child)
+
+
 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."""
+    """Route location tokens to city/region search; keep store for store-like names.
+
+    District-like names (区/县/旗) go to region only. A single city-like name
+    (含「市」及短地名) dual-searches city and region so county-level cities like
+    江阴市 can hit region. When the question already has two+ distinct places
+    (苏州 + 昆山市), keep city/region slots as hierarchical AND filters and do
+    not dual-search each token.
+    """
     seen_search = {(str(item.get("type") or ""), str(item.get("value") or "")) for item in search_candidates}
+    _seed_hierarchical_location_candidates(
+        question,
+        search_candidates,
+        schema_candidates,
+        schema,
+        seen_search,
+    )
+    hierarchical = _is_hierarchical_location_query(search_candidates)
     for token in _extract_region_tokens(question):
         if _looks_like_region_name(token):
             _promote_region_search_candidate(
@@ -2022,20 +2443,55 @@ def _reconcile_location_entity_candidates(
         if str(candidate.get("type") or "") != "store":
             continue
         if _looks_like_city_name(value):
-            _promote_city_search_candidate(
+            if hierarchical:
+                _ensure_location_search_candidate(
+                    search_candidates,
+                    entity_type="city",
+                    label="城市",
+                    value=value,
+                    schema=schema,
+                    seen_search=seen_search,
+                )
+                _drop_location_schema_store_candidates(schema_candidates, value=value)
+            else:
+                _ensure_location_dual_search_candidates(
+                    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
+        candidate_type = str(candidate.get("type") or "")
+        if candidate_type == "city" and _looks_like_region_name(value):
+            search_candidates.remove(candidate)
+            seen_search.discard(("city", value))
+            _promote_region_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(
+        if hierarchical:
+            if candidate_type == "store" and _looks_like_city_name(value):
+                search_candidates.remove(candidate)
+                seen_search.discard(("store", value))
+                _ensure_location_search_candidate(
+                    search_candidates,
+                    entity_type="city",
+                    label="城市",
+                    value=value,
+                    schema=schema,
+                    seen_search=seen_search,
+                )
+            continue
+        if candidate_type in {"city", "region"} and _looks_like_city_name(value):
+            _ensure_location_dual_search_candidates(
                 search_candidates,
                 schema_candidates,
                 value=value,
@@ -2043,11 +2499,12 @@ def _reconcile_location_entity_candidates(
                 seen_search=seen_search,
             )
             continue
-        if str(candidate.get("type") or "") != "store":
+        if candidate_type != "store":
             continue
         if _looks_like_city_name(value):
             search_candidates.remove(candidate)
-            _promote_city_search_candidate(
+            seen_search.discard(("store", value))
+            _ensure_location_dual_search_candidates(
                 search_candidates,
                 schema_candidates,
                 value=value,
@@ -2065,8 +2522,13 @@ def _collect_entity_resolution_candidates(
     *,
     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."""
+) -> tuple[list[dict[str, str]], list[dict[str, str]], list[dict[str, str]]]:
+    """Split entity mentions into search/schema candidates and a query-plan flat list.
+
+    Returns ``(search_candidates, schema_candidates, question_entities)``. The flat
+    ``question_entities`` list is produced from the same extraction pass so SQL
+    generation can reuse it without a second LLM call.
+    """
     search_candidates: list[dict[str, str]] = []
     schema_candidates: list[dict[str, str]] = []
     seen_search: set[tuple[str, str]] = set()
@@ -2074,10 +2536,17 @@ def _collect_entity_resolution_candidates(
 
     catalog = _entity_catalog(schema)
     llm_values: dict[str, Any] = {}
-    if sampler is not None and catalog:
+    # Prefer Step-3 analysis.entityCandidates so the happy path needs only one
+    # Sampling call (analysis) before SQL generation. Fall back to a dedicated
+    # entity-slot Sampling only when analysis did not yield usable entity values.
+    if analysis is not None:
+        llm_values = _merge_analysis_entity_candidates_into_llm_values({}, analysis, catalog)
+        _infer_explicit_entity_types_from_analysis(llm_values, analysis)
+    if not _llm_values_have_entity_slots(llm_values, catalog) and 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)
+        llm_values = _merge_analysis_entity_candidates_into_llm_values(llm_values, analysis, catalog)
     _drop_implicit_location_values_inside_named_entities(llm_values)
+    question_entities = _question_entities_from_llm_values(catalog, llm_values, question, analysis)
     for item in catalog:
         value = llm_values.get(item["type"]) or _extract_value_near_label(question, item["label"])
         if not value:
@@ -2134,10 +2603,69 @@ def _collect_entity_resolution_candidates(
         schema_candidates,
         schema,
     )
-    return search_candidates, schema_candidates
+    return search_candidates, schema_candidates, question_entities
+
+
+def _merge_schema_context_entity_candidates(
+    searched_entities: dict[str, Any] | None,
+    question: str,
+    schema_context: Any,
+    *,
+    analysis: QuestionAnalysis | None = None,
+) -> dict[str, Any] | None:
+    """Append schemaContext-only entity candidates after parallel step 4 completes."""
+    if searched_entities is None:
+        return None
+    if schema_context is None:
+        return searched_entities
+    schema_candidates = list(searched_entities.get("schemaCandidates") or [])
+    seen_schema = {
+        (str(item.get("field") or ""), str(item.get("value") or ""))
+        for item in schema_candidates
+        if isinstance(item, dict)
+    }
+    added = False
+    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)
+        added = True
+    if not added:
+        return searched_entities
+    merged = dict(searched_entities)
+    merged["schemaCandidates"] = schema_candidates
+    return merged
+
+
+def _question_entities_from_llm_values(
+    catalog: list[dict[str, str]],
+    llm_values: dict[str, Any],
+    question: str,
+    analysis: QuestionAnalysis | None,
+) -> list[dict[str, str]]:
+    """Build the query-plan flat entity list from one extraction pass."""
+    results: list[dict[str, str]] = []
+    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 _schema_generic_entity_candidates(question: str, schema_context: Any) -> list[dict[str, str]]:
+    if schema_context is None:
+        return []
     candidates: list[dict[str, str]] = []
     for table in getattr(schema_context, "tables", []) or []:
         if not isinstance(table, dict):
@@ -2389,10 +2917,12 @@ def _entity_search_filter_items(search_response: dict[str, Any] | None) -> list[
         response = search_result.get("response")
         if not isinstance(response, dict):
             continue
-        group_key = _entity_search_alias_group_key(search_result)
+        group_key = _entity_search_or_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))
+        group_counts[group_key] = group_counts.get(group_key, 0) + len(
+            _matched_entity_search_items(search_result)
+        )
     for index, search_result in enumerate(search_results, start=1):
         if not isinstance(search_result, dict):
             continue
@@ -2402,17 +2932,20 @@ def _entity_search_filter_items(search_response: dict[str, Any] | None) -> list[
         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)
+        group_key = _entity_search_or_group_key(search_result)
         if group_key and group_counts.get(group_key, 0) > 1:
             group_seed = f"entity_search:{group_key}"
+            force_group = True
         else:
             group_seed = f"entity_search:{index}:{candidate_type}:{searched_name}"
+            force_group = False
         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),
+                force_logical_group=force_group,
+                candidate_type=candidate_type,
             )
         )
     return result
@@ -2428,14 +2961,60 @@ def _entity_search_alias_group_key(search_result: dict[str, Any]) -> str:
     return re.sub(r"[^0-9A-Za-z\u4e00-\u9fff]+", "", raw).lower()
 
 
+def _entity_search_or_group_key(search_result: dict[str, Any]) -> str:
+    """OR-group key for ambiguous aliases of the *same* place/name.
+
+    City/region use the normalized place key so 苏州/苏州市 stay one OR group,
+    while 苏州 + 昆山 stay separate (AND across hierarchy). Brand/project keep
+    the raw alias key so 必胜客 / 南京必胜客 can still OR together.
+    """
+    candidate = search_result.get("candidate")
+    candidate_type = str(candidate.get("type") or "") if isinstance(candidate, dict) else ""
+    if candidate_type in {"city", "region"}:
+        raw = ""
+        if isinstance(candidate, dict):
+            raw = str(candidate.get("value") or "")
+        if not raw:
+            raw = str(search_result.get("searchedName") or "")
+        place_key = _location_place_key(raw)
+        return place_key.lower() if place_key else _entity_search_alias_group_key(search_result)
+    return _entity_search_alias_group_key(search_result)
+
+
+def _matched_entity_search_items(search_result: dict[str, Any]) -> list[dict[str, str]]:
+    response = search_result.get("response")
+    if not isinstance(response, dict):
+        return []
+    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 ""
+    if not searched_name and isinstance(candidate, dict):
+        searched_name = str(candidate.get("value") or "")
+    items = _flatten_entity_search_items(response)
+    if candidate_type not in {"city", "region"}:
+        return items
+    return [
+        item
+        for item in items
+        if _entity_hit_matches_searched_name(str(item.get("name") or ""), searched_name)
+    ]
+
+
 def _entity_search_filter_items_for_response(
     response: dict[str, Any],
     *,
     searched_name: str,
     group_seed: str,
     force_logical_group: bool = False,
+    candidate_type: str = "",
 ) -> list[dict[str, str]]:
     items = _flatten_entity_search_items(response)
+    if candidate_type in {"city", "region"} and searched_name:
+        items = [
+            item
+            for item in items
+            if _entity_hit_matches_searched_name(str(item.get("name") or ""), searched_name)
+        ]
     if not items:
         return []
     logical_group = group_seed if force_logical_group or len(items) > 1 else ""
@@ -2451,7 +3030,10 @@ def _entity_search_filter_items_for_response(
     return result
 
 
-def _direct_entity_candidates(search_response: dict[str, Any] | None) -> list[dict[str, str]]:
+def _direct_entity_candidates(
+    search_response: dict[str, Any] | None,
+    schema: dict[str, Any] | None = None,
+) -> list[dict[str, str]]:
     if not isinstance(search_response, dict):
         return []
     candidates = [
@@ -2463,19 +3045,140 @@ def _direct_entity_candidates(search_response: dict[str, Any] | None) -> list[di
     if not isinstance(search_results, list):
         return candidates
     resolved: set[tuple[str, str]] = set()
+    location_group_types: dict[str, set[str]] = {}
+    location_group_hits: dict[str, bool] = {}
     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
-    ]
+        candidate_type = str(candidate.get("type") or "")
+        candidate_value = str(candidate.get("value") or "")
+        group_key = _entity_search_or_group_key(search_result)
+        if group_key and candidate_type in {"city", "region"}:
+            location_group_types.setdefault(group_key, set()).add(candidate_type)
+        if _matched_entity_search_items(search_result):
+            resolved.add((candidate_type, candidate_value))
+            if group_key and candidate_type in {"city", "region"}:
+                location_group_hits[group_key] = True
+    has_address_fallback = bool(schema and _schema_has_job_address_name(schema))
+    # Dual city+region: never AND an empty side with a hit. Both-miss uses address
+    # fallback when available; otherwise keep both sides as OR via logicalGroup.
+    suppressed_unresolved_locations: set[tuple[str, str]] = set()
+    or_group_unresolved_locations: 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
+        candidate_type = str(candidate.get("type") or "")
+        candidate_value = str(candidate.get("value") or "")
+        if candidate_type not in {"city", "region"}:
+            continue
+        if (candidate_type, candidate_value) in resolved:
+            continue
+        group_key = _entity_search_or_group_key(search_result)
+        types = location_group_types.get(group_key) or set()
+        if "city" not in types or "region" not in types:
+            continue
+        if location_group_hits.get(group_key):
+            suppressed_unresolved_locations.add((candidate_type, candidate_value))
+        elif has_address_fallback:
+            suppressed_unresolved_locations.add((candidate_type, candidate_value))
+        else:
+            or_group_unresolved_locations.add((candidate_type, candidate_value))
+    result: list[dict[str, str]] = []
+    for candidate in candidates:
+        key = (str(candidate.get("type") or ""), str(candidate.get("value") or ""))
+        if key in resolved or key in suppressed_unresolved_locations:
+            continue
+        item = dict(candidate)
+        if key in or_group_unresolved_locations:
+            group_key = _location_place_key(key[1]).lower() or re.sub(
+                r"[^0-9A-Za-z\u4e00-\u9fff]+", "", key[1]
+            ).lower()
+            item["logicalGroup"] = f"entity_search:{group_key}"
+            item["logicalOperator"] = "OR"
+        result.append(item)
+    return result
+
+
+def _location_address_fallback_filters(
+    searched_entities: dict[str, Any] | None,
+    schema: dict[str, Any] | None,
+) -> list[dict[str, str]]:
+    """When city/region dual search both miss, fall back to job_address.name LIKE."""
+    if not isinstance(searched_entities, dict) or not isinstance(schema, dict):
+        return []
+    if not _schema_has_job_address_name(schema):
+        return []
+    search_results = searched_entities.get("searchResults")
+    if not isinstance(search_results, list) or not search_results:
+        return []
+    groups: dict[str, dict[str, Any]] = {}
+    for search_result in search_results:
+        if not isinstance(search_result, dict):
+            continue
+        candidate = search_result.get("candidate")
+        if not isinstance(candidate, dict):
+            continue
+        candidate_type = str(candidate.get("type") or "")
+        if candidate_type not in {"city", "region"}:
+            continue
+        group_key = _entity_search_or_group_key(search_result)
+        if not group_key:
+            continue
+        bucket = groups.setdefault(
+            group_key,
+            {"types": set(), "hit": False, "value": str(candidate.get("value") or "").strip()},
+        )
+        bucket["types"].add(candidate_type)
+        if not bucket["value"]:
+            bucket["value"] = str(search_result.get("searchedName") or "").strip()
+        if _matched_entity_search_items(search_result):
+            bucket["hit"] = True
+    filters: list[dict[str, str]] = []
+    for group_key, bucket in groups.items():
+        types = bucket["types"]
+        if "city" not in types or "region" not in types:
+            continue
+        if bucket["hit"]:
+            continue
+        value = str(bucket["value"] or "").strip()
+        if not value:
+            continue
+        variants = _location_address_filter_values(value)
+        logical_group = f"entity_search:{group_key}:address_fallback"
+        for variant in variants:
+            filters.append(
+                {
+                    "field": "job_address.name",
+                    "operator": "LIKE",
+                    "value": f"%{variant}%",
+                    "source": "search_entities.address_fallback",
+                    "logicalGroup": logical_group,
+                    "logicalOperator": "OR",
+                }
+            )
+    return filters
+
+
+def _schema_has_job_address_name(schema: dict[str, Any]) -> bool:
+    for table in schema.get("tables") or []:
+        if not isinstance(table, dict):
+            continue
+        name = str(table.get("tableName") or table.get("name") or "")
+        if name != "job_address":
+            continue
+        for column in table.get("columns") or []:
+            if not isinstance(column, dict):
+                continue
+            column_name = str(column.get("columnName") or column.get("name") or "")
+            if column_name == "name":
+                return True
+    return False
 
 
 def _entity_type_label(entity_type: str) -> str:
@@ -2550,7 +3253,9 @@ def _llm_extract_entity_values(
         "从用户问题中抽取字段值，"
         "只输出一个 JSON 对象，键为字段代码，值为问题中出现的实体名称原文；"
         "问题中没有提到的字段一律输出 null。不要输出任何解释或多余文本。"
-        "城市（如上海、北京）填 city；区县（如杨浦区、浦东新区）填 region，不要填 city；"
+        "地级市（如上海、北京、无锡、苏州）填 city；区/县/旗（如杨浦区、浦东新区）填 region，不要填 city；"
+        "用户同时说了地级市和其下区县/县级市时（如苏州昆山市、无锡江阴市），city 填地级市、region 填下级区县/县级市，二者是层级 AND，不要把两个地名都填进 city；"
+        "用户只说了一个「XX市」且可能是县级市（如江阴市），city 与 region 都填同一检索词，由 search_entities 决定命中；"
         "具体门店（含店/路/广场等）填 store。"
         "品牌与项目可能同名：如果用户明确说这是项目，只填 sponge_project，不填 brand；"
         "如果用户明确说这是品牌，只填 brand，不填 sponge_project；"
@@ -2652,6 +3357,35 @@ def _merge_analysis_entity_candidates_into_llm_values(
     return merged
 
 
+def _llm_values_have_entity_slots(llm_values: dict[str, Any], catalog: list[dict[str, str]]) -> bool:
+    """True when analysis/extraction already filled at least one catalog entity slot."""
+    allowed = {item["type"] for item in catalog}
+    return any(str(llm_values.get(entity_type) or "").strip() for entity_type in allowed)
+
+
+def _infer_explicit_entity_types_from_analysis(
+    llm_values: dict[str, Any],
+    analysis: QuestionAnalysis,
+) -> None:
+    """Mark brand/project as explicit when analysis only emitted one of the two.
+
+    This preserves the old entity-slot ``explicitTypes`` behaviour without a second
+    Sampling call: ``_expand_brand_project_search_candidates`` skips cross-search
+    when the user clearly meant only brand or only project.
+    """
+    if llm_values.get(_EXPLICIT_ENTITY_TYPES_KEY):
+        return
+    present: set[str] = set()
+    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())
+        if entity_type in {"brand", "sponge_project"} and str(candidate.get("value") or "").strip():
+            present.add(entity_type)
+    if present == {"brand"} or present == {"sponge_project"}:
+        llm_values[_EXPLICIT_ENTITY_TYPES_KEY] = sorted(present)
+
+
 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)
@@ -2721,36 +3455,6 @@ def _load_json_object_safe(text: str) -> dict[str, Any]:
     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()
@@ -2981,7 +3685,7 @@ def _query_plan_sql_filters(
         )
     for filter_item in _query_plan_search_entity_filters(searched_entities, schema):
         _append_filter(filter_item)
-    for candidate in _direct_entity_candidates(searched_entities):
+    for candidate in _direct_entity_candidates(searched_entities, schema):
         maps_to = str(candidate.get("mapsTo") or candidate.get("type") or "")
         field = str(candidate.get("field") or "")
         if not field or "." not in field:
@@ -2990,14 +3694,19 @@ def _query_plan_sql_filters(
         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"),
-            }
-        )
+        filter_item = {
+            "field": field,
+            "operator": "LIKE",
+            "value": f"%{normalized_value}%",
+            "source": str(candidate.get("source") or "schema.columns"),
+        }
+        logical_group = candidate.get("logicalGroup")
+        if logical_group:
+            filter_item["logicalGroup"] = str(logical_group)
+            filter_item["logicalOperator"] = str(candidate.get("logicalOperator") or "OR")
+        _append_filter(filter_item)
+    for filter_item in _location_address_fallback_filters(searched_entities, schema):
+        _append_filter(filter_item)
     for enum_filter in _query_plan_enum_filters(question, getattr(schema_context, "enums", []) or []):
         filters.append(enum_filter)
     if selected_concepts is None:
@@ -3033,9 +3742,44 @@ def _query_plan_sql_filters(
         selected_concepts=selected_concepts,
         analysis=analysis,
     )
+    filters = _strip_hierarchical_location_or_groups(filters)
     return filters
 
 
+def _strip_hierarchical_location_or_groups(filters: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Ensure distinct city/region place filters are AND-ed, not OR-grouped."""
+    city_keys: set[str] = set()
+    region_keys: set[str] = set()
+    for flt in filters:
+        if str(flt.get("operator") or "").upper() != "LIKE":
+            continue
+        field = str(flt.get("field") or "")
+        key = _location_place_key(str(flt.get("value") or "").strip("%"))
+        if not key:
+            continue
+        if field == "city.name":
+            city_keys.add(key)
+        elif field == "region.name":
+            region_keys.add(key)
+    if not city_keys or not region_keys:
+        return filters
+    if city_keys == region_keys and len(city_keys) == 1:
+        # Same place dual-hit (江阴市 in city+region) may keep OR.
+        return filters
+    result: list[dict[str, str]] = []
+    for flt in filters:
+        item = dict(flt)
+        field = str(item.get("field") or "")
+        if field in {"city.name", "region.name"} and str(item.get("logicalOperator") or "").upper() == "OR":
+            key = _location_place_key(str(item.get("value") or "").strip("%"))
+            peer_keys = region_keys if field == "city.name" else city_keys
+            if key and any(peer != key for peer in peer_keys):
+                item.pop("logicalGroup", None)
+                item.pop("logicalOperator", None)
+        result.append(item)
+    return result
+
+
 def _query_plan_search_entity_filters(
     searched_entities: dict[str, Any] | None,
     schema: dict[str, Any] | None,
@@ -4090,7 +4834,7 @@ def _repair_sql_for_local_schema_issues(
     )
     if repaired_sql is None:
         return None, fail_reason
-    steps.done(9, repair_success_detail)
+    steps.done(7, repair_success_detail)
     return repaired_sql, None
 
 
@@ -4161,7 +4905,7 @@ def _repair_sql_with_llm_retries(
     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} 次）")
+        steps.running(7, f"{running_detail}（第 {attempt}/{max_attempts} 次）")
         repair_error = {
             **current_error,
             "attempt": attempt,
@@ -4211,7 +4955,7 @@ def _repair_sql_with_llm_retries(
             continue
         try:
             check(repaired_sql)
-            steps.done(9, f"已修复 SQL（第 {attempt}/{max_attempts} 次）。")
+            steps.done(7, f"已修复 SQL（第 {attempt}/{max_attempts} 次）。")
             return repaired_sql, ""
         except SqlGenerationError as exc:
             if schema is not None:
@@ -4262,10 +5006,15 @@ def _review_sql_with_llm_expert_if_needed(
     steps: _ExecutionSteps,
     audit_logger: AuditLogger,
     session_id: str | None,
+    enable_expert_review: bool = True,
 ) -> tuple[str, str | None]:
-    if generator is None or schema_context is None or not _should_llm_sql_expert_review(sql, query_plan):
+    if not enable_expert_review:
+        _skip_expert_review_step(steps, "fastMode 已关闭 LLM SQL 专家复核。")
+        return sql, None
+    if generator is None or schema_context is None or not _should_llm_sql_expert_review(sql):
+        _skip_expert_review_step(steps, "SQL 未命中聚合/子查询等高风险写法，跳过专家复核。")
         return sql, None
-    steps.running(8, "LLM SQL 专家复核高风险 SQL 写法。")
+    steps.running(6, "LLM SQL 专家复核高风险 SQL 写法。")
     try:
         review = generator.review_sql(
             question=question,
@@ -4295,7 +5044,7 @@ def _review_sql_with_llm_expert_if_needed(
         }
     )
     if review.executable and not review.repaired_sql:
-        steps.done(8, "LLM SQL 专家复核通过。")
+        steps.done(6, "LLM SQL 专家复核通过。")
         return sql, None
     validation_error = {
         "code": "LLM_SQL_EXPERT_REVIEW_FAILED",
@@ -4319,8 +5068,8 @@ def _review_sql_with_llm_expert_if_needed(
         try:
             enforce_sql_rules(candidate, max_limit=max_limit)
             _require_no_schema_issues(candidate, schema)
-            steps.done(9, "已根据 LLM SQL 专家复核修复 SQL 写法问题。")
-            steps.done(8, "LLM SQL 专家复核后 SQL 满足本地规则。")
+            steps.done(7, "已根据 LLM SQL 专家复核修复 SQL 写法问题。")
+            steps.done(6, "LLM SQL 专家复核后 SQL 满足本地规则。")
             return candidate, None
         except SqlGenerationError as exc:
             schema_issues = validate_sql_against_schema(candidate, schema)
@@ -4359,7 +5108,7 @@ def _review_sql_with_llm_expert_if_needed(
     )
     if repaired_sql is None:
         return sql, fail_reason
-    steps.done(8, "LLM SQL 专家复核后 SQL 满足本地规则。")
+    steps.done(6, "LLM SQL 专家复核后 SQL 满足本地规则。")
     return repaired_sql, None
 
 
@@ -4368,16 +5117,35 @@ def _require_sql_expert_local_pass(sql: str, schema: dict[str, Any], max_limit:
     _require_no_schema_issues(sql, schema)
 
 
-def _should_llm_sql_expert_review(sql: str, query_plan: dict[str, Any] | None) -> bool:
+def _skip_expert_review_step(steps: _ExecutionSteps, detail: str) -> None:
+    """Mark step 7 skipped only when it is still pending.
+
+    SQL generation may already have recorded a real repair on step 7; overwriting
+    that status with skipped would mis-attribute earlier repair latency.
+    """
+    _skip_repair_step_if_pending(steps, detail)
+
+
+def _skip_repair_step_if_pending(steps: _ExecutionSteps, detail: str) -> None:
+    for item in steps.steps:
+        if item["step"] != 7:
+            continue
+        if item.get("status") == "pending":
+            steps.skipped(7, detail)
+        return
+
+
+def _should_llm_sql_expert_review(sql: str) -> bool:
+    """Only review SQL that itself uses aggregation or subqueries.
+
+    Concept matches such as filled_job_by_period must not trigger review alone;
+    otherwise simple list queries can pay an extra LLM round for no reason.
+    """
     normalized = sql.lower()
     if re.search(r"\b(group\s+by|having|count|sum|avg|min|max|group_concat)\s*\b", normalized):
         return True
     if re.search(r"\(\s*select\b", normalized):
         return True
-    if isinstance(query_plan, dict):
-        for concept in query_plan.get("matchedConcepts") or []:
-            if isinstance(concept, dict) and str(concept.get("name") or "") in {"filled_job_by_period"}:
-                return True
     return False