@roll-agent/octopus-agent 0.0.10 → 0.0.11

package/src/octopus_skill/agent.py

@@ -8,25 +8,62 @@ from typing import Any
 from .audit_logger import AuditLogger, sql_hash
 from .config import AppConfig
 from .context import UserContext, new_session_id, new_trace_id
+from .entity_binding import bind_entities, missing_entities_in_sql
+from .entity_dictionary import EntityDictionaryCache
+from .entity_resolver import EntityResolver, load_geo_aliases
 from .llm_sql_generator import Sampler, SamplingSqlGenerator
 from .mcp_client import SpongeMcpClient
-from .query_sql_cache import QuerySqlCache
+from .prompt_builder import _business_examples
 from .result_renderer import normalize_result_format, render_result
 from .schema_cache import SchemaCache
 from .schema_context_retriever import retrieve_schema_context
 from .sql_generator import (
     GeneratedSql,
-    RuleBasedSqlGenerator,
     SqlGenerationError,
+    _extract_brand_name,
+    _extract_location_for_recruiting_job_question,
+    _extract_project_name,
+    _requested_job_status_values,
+    _enum_label_terms,
+    _is_job_count_intent_question,
+    _preferred_count_alias,
+    _status_enum,
+    _user_requests_recruiting_job_count,
     enforce_sql_rules,
+    _is_business_query,
     is_low_quality_sql_for_question,
     is_recruiting_match_effect_query,
+    low_quality_sql_issue_for_question,
+    normalize_job_count_sql,
+    normalize_text_filters_to_like,
     sensitive_terms_in_text,
     sql_satisfies_time_range,
     validate_sql_against_schema,
 )
 
 
+# Resolver indexes are keyed by dictVersion and shared across agent instances in
+# the same process. The MCP server recreates a SpongeAgent per tools/call, so an
+# instance-level cache alone would rebuild the (large) index on every request.
+_RESOLVER_CACHE: dict[str, EntityResolver] = {}
+
+# Validate error codes treated as "caller has no data scope" -> a valid empty
+# result, not a SQL failure.
+#
+# Per MCP source review (alignment checklist Q1), the *current* server emits NO
+# error for empty scope: it injects an `IN (NULL)` scope filter and returns
+# success with 0 rows, which the normal empty-result path already handles. These
+# codes are therefore only a defensive net for OLDER ONLINE deployments still
+# observed emitting MCP_SQL_MISSING_SCOPE in audit logs (plus the declared-but-
+# currently-unthrown MCP_PERMISSION_EMPTY_SCOPE).
+#
+# This is intentionally NOT treated as the live MCP contract. Remove once every
+# online MCP instance runs the no-error-code behaviour.
+_LEGACY_EMPTY_SCOPE_CODES = frozenset(
+    {"MCP_PERMISSION_EMPTY_SCOPE", "MCP_SQL_MISSING_SCOPE"}
+)
+
+
 @dataclass(frozen=True)
 class QueryResult:
     answer: str
@@ -34,6 +71,9 @@ class QueryResult:
     normalized_sql: str
     repaired_sql: str | None
     validation: dict[str, Any]
+    needs_clarification: bool = False
+    clarification_type: str | None = None
+    clarification_payload: dict[str, Any] | None = None
 
 
 @dataclass
@@ -42,9 +82,12 @@ class SpongeAgent:
     mcp_client: SpongeMcpClient
     schema_cache: SchemaCache
     audit_logger: AuditLogger
+    dictionary_cache: EntityDictionaryCache | None = None
     _last_validation_error: dict[str, Any] = field(default_factory=dict, init=False)
     _last_validation_result: dict[str, Any] = field(default_factory=dict, init=False)
     _last_validation_trace_id: str | None = field(default=None, init=False)
+    _resolver: EntityResolver | None = field(default=None, init=False)
+    _resolver_loaded: bool = field(default=False, init=False)
 
     @classmethod
     def from_config(cls, config: AppConfig) -> "SpongeAgent":
@@ -57,6 +100,11 @@ class SpongeAgent:
             ),
             schema_cache=SchemaCache(config.schema.cache_path),
             audit_logger=AuditLogger(config.audit.log_path, enabled=config.audit.enabled),
+            dictionary_cache=(
+                EntityDictionaryCache(config.dictionary.cache_path)
+                if config.dictionary is not None
+                else None
+            ),
         )
 
     def answer(
@@ -88,7 +136,7 @@ class SpongeAgent:
         result_format: str | None = None,
         fast_mode: bool = True,
     ) -> QueryResult:
-        user_question = original_question or question
+        user_question = _isolate_current_question(original_question or question)
         if _is_mutation_request(user_question):
             return _query_only_result()
         context = UserContext(
@@ -103,76 +151,95 @@ class SpongeAgent:
         business_clarification = _business_metric_clarification(sql_question, schema)
         if business_clarification is not None:
             return _business_metric_clarification_result(business_clarification)
-        schema_version = str(schema.get("schemaVersion")) if schema.get("schemaVersion") is not None else None
+        self._log_entity_bindings_shadow(context, user_question, sql_question)
+        bindings = self._compute_entity_bindings(sql_question)
+        entity_clarification = _entity_ambiguity_clarification(bindings)
+        if entity_clarification is not None:
+            return _entity_clarification_result(
+                entity_clarification,
+                _entity_ambiguity_payload(bindings),
+            )
+        resolved_entities = self._resolved_entities_for_prompt(bindings)
         repaired_sql: str | None = None
-        prefer_rule_based = is_recruiting_match_effect_query(sql_question)
-        sql_cache = _make_query_sql_cache(self.config)
-        cached_sql = sql_cache.get(question=sql_question, schema_version=schema_version) if sql_cache is not None else None
-        if cached_sql is not None and not sql_satisfies_time_range(cached_sql, sql_question, schema):
-            cached_sql = None
-        if cached_sql is not None and is_low_quality_sql_for_question(sql_question, cached_sql):
-            sql_cache.delete(question=sql_question, schema_version=schema_version)
-            cached_sql = None
-        if cached_sql is not None and validate_sql_against_schema(cached_sql, schema):
-            sql_cache.delete(question=sql_question, schema_version=schema_version)
-            cached_sql = None
-        if cached_sql is not None:
-            generated = GeneratedSql(sql=cached_sql, tables=[], placeholders=[])
-        if sampler is not None:
-            schema_context = None
-            generator: SamplingSqlGenerator | None = None
-            if cached_sql is None:
-                schema_context = retrieve_schema_context(schema, sql_question)
-                generator = SamplingSqlGenerator(
-                    sampler=sampler,
+        schema_context = retrieve_schema_context(
+            schema,
+            sql_question,
+            required_tables=_resolved_entity_tables(resolved_entities),
+        )
+        generator: SamplingSqlGenerator | None = None
+        if sampler is None:
+            generated = _generate_from_schema_example(
+                question=sql_question,
+                schema_context=schema_context,
+            )
+            self.audit_logger.log(
+                {
+                    "sessionId": context.session_id,
+                    "question": sql_question,
+                    "tool": "schema_example_fallback",
+                    "matched": generated is not None,
+                    "exampleCount": len(schema_context.examples),
+                    "sqlHash": sql_hash(generated.sql) if generated is not None else None,
+                }
+            )
+            if generated is None:
+                generated = _generate_from_resolved_entities(
+                    question=sql_question,
+                    resolved_entities=resolved_entities,
+                    schema=schema,
                     default_limit=self.config.sql.default_limit,
-                    max_limit=self.config.sql.max_limit,
                 )
-                if fast_mode or prefer_rule_based:
-                    try:
-                        generated = _generate_rule_based_sql(
-                            question=sql_question,
-                            schema=schema,
-                            default_limit=self.config.sql.default_limit,
-                            max_limit=self.config.sql.max_limit,
-                        )
-                    except SqlGenerationError:
-                        generated, repaired_sql = _generate_with_sampler(
-                            generator=generator,
-                            question=sql_question,
-                            schema_context=schema_context,
-                        )
-                    else:
-                        repaired_sql = None
-                else:
-                    generated, repaired_sql = _generate_with_sampler(
-                        generator=generator,
+            if generated is None:
+                return _query_only_result()
+        else:
+            generator = SamplingSqlGenerator(
+                sampler=sampler,
+                default_limit=self.config.sql.default_limit,
+                max_limit=self.config.sql.max_limit,
+                resolved_entities=resolved_entities,
+            )
+            generated, repaired_sql, generation_repair_attempted = _generate_with_sampler(
+                generator=generator,
+                question=sql_question,
+                schema_context=schema_context,
+            )
+            if generated.sql == "" and repaired_sql is None:
+                if generation_repair_attempted:
+                    return _query_only_result()
+                try:
+                    repaired = generator.repair(
                         question=sql_question,
+                        original_sql="",
+                        validation_error={
+                            "code": "EMPTY_SQL",
+                            "message": "schemaContext 已提供相关表、JOIN、枚举或示例时，不要直接返回空 SQL；请基于当前 schemaContext 生成完整 SELECT SQL。",
+                        },
                         schema_context=schema_context,
                     )
-                    if generated.sql == "" and repaired_sql is None:
-                        return _query_only_result()
-                if fast_mode and generated.sql == "" and repaired_sql is None:
-                    return _query_only_result()
-                if not fast_mode and generated.sql == "" and repaired_sql is None:
+                except SqlGenerationError:
                     return _query_only_result()
-        elif cached_sql is None:
-            schema_context = None
-            generated = _generate_rule_based_sql(
-                question=sql_question,
-                schema=schema,
-                default_limit=self.config.sql.default_limit,
-                max_limit=self.config.sql.max_limit,
-            )
-        else:
-            schema_context = None
-            generator = None
-        candidate_sql = repaired_sql or _apply_limit_policy(
+                repaired_sql = _finalize_candidate_sql(
+                    repaired.sql,
+                    sql_question,
+                    default_limit=self.config.sql.default_limit,
+                    max_limit=self.config.sql.max_limit,
+                )
+        candidate_sql = repaired_sql or _finalize_candidate_sql(
             generated.sql,
             sql_question,
             default_limit=self.config.sql.default_limit,
             max_limit=self.config.sql.max_limit,
+            schema=schema,
+        )
+        candidate_sql, still_missing_entities = self._enforce_resolved_entities(
+            candidate_sql,
+            sql_question,
+            resolved_entities,
+            generator,
+            schema_context,
         )
+        if still_missing_entities:
+            return _missing_resolved_entities_result(still_missing_entities)
         if not sql_satisfies_time_range(candidate_sql, sql_question, schema):
             if sampler is None or schema_context is None or generator is None:
                 return _query_only_result()
@@ -189,7 +256,7 @@ class SpongeAgent:
             except SqlGenerationError:
                 return _query_only_result()
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
-            repaired_sql = _apply_limit_policy(
+            repaired_sql = _finalize_candidate_sql(
                 repaired.sql,
                 sql_question,
                 default_limit=self.config.sql.default_limit,
@@ -198,31 +265,34 @@ class SpongeAgent:
             candidate_sql = repaired_sql
             if not sql_satisfies_time_range(candidate_sql, sql_question, schema):
                 return _query_only_result()
-        if is_low_quality_sql_for_question(sql_question, candidate_sql):
+        low_quality_issue = low_quality_sql_issue_for_question(sql_question, candidate_sql, schema=schema)
+        if low_quality_issue is not None:
             if sampler is None or schema_context is None or generator is None:
-                return _query_only_result()
+                return _low_quality_sql_result(low_quality_issue.message, candidate_sql)
             try:
                 repaired = generator.repair(
                     question=sql_question,
                     original_sql=candidate_sql,
                     validation_error={
-                        "code": "LOW_QUALITY_SQL",
-                        "message": "SQL 与问题意图不匹配，业务查询不能退化成品牌、项目、城市、门店、岗位等单表列表；明确名称时必须在完整业务 SQL 中 JOIN 对应表并使用 name LIKE 或 job_name LIKE。",
+                        "code": low_quality_issue.code,
+                        "message": low_quality_issue.message,
                     },
                     schema_context=schema_context,
                 )
             except SqlGenerationError:
-                return _query_only_result()
+                return _low_quality_sql_result(low_quality_issue.message, candidate_sql)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
-            repaired_sql = _apply_limit_policy(
+            repaired_sql = _finalize_candidate_sql(
                 repaired.sql,
                 sql_question,
                 default_limit=self.config.sql.default_limit,
                 max_limit=self.config.sql.max_limit,
+                schema=schema,
             )
             candidate_sql = repaired_sql
-            if is_low_quality_sql_for_question(sql_question, candidate_sql):
-                return _query_only_result()
+            low_quality_issue = low_quality_sql_issue_for_question(sql_question, candidate_sql, schema=schema)
+            if low_quality_issue is not None:
+                return _low_quality_sql_result(low_quality_issue.message, candidate_sql)
         schema_issues = validate_sql_against_schema(candidate_sql, schema)
         if schema_issues:
             if sampler is None or schema_context is None or generator is None:
@@ -240,7 +310,7 @@ class SpongeAgent:
             except SqlGenerationError:
                 return _query_only_result()
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
-            repaired_sql = _apply_limit_policy(
+            repaired_sql = _finalize_candidate_sql(
                 repaired.sql,
                 sql_question,
                 default_limit=self.config.sql.default_limit,
@@ -249,6 +319,12 @@ class SpongeAgent:
             candidate_sql = repaired_sql
             if validate_sql_against_schema(candidate_sql, schema):
                 return _query_only_result()
+        candidate_sql = _finalize_candidate_sql(
+            candidate_sql,
+            sql_question,
+            default_limit=self.config.sql.default_limit,
+            max_limit=self.config.sql.max_limit,
+        )
         try:
             enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
         except SqlGenerationError as exc:
@@ -267,7 +343,7 @@ class SpongeAgent:
                     )
                 except SqlGenerationError:
                     return _sensitive_query_only_result(sensitive_terms)
-                repaired_sql = _apply_limit_policy(
+                repaired_sql = _finalize_candidate_sql(
                     repaired.sql,
                     sql_question,
                     default_limit=self.config.sql.default_limit,
@@ -282,28 +358,46 @@ class SpongeAgent:
                 generated = GeneratedSql(sql="", tables=[], placeholders=[])
                 candidate_sql = repaired_sql
             else:
-                if sampler is None:
-                    return _query_only_result()
-                if not fast_mode:
+                if generator is None:
                     return _query_only_result()
                 try:
-                    generated = _generate_rule_based_sql(
+                    repaired = generator.repair(
                         question=sql_question,
-                        schema=schema,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
-                    )
-                    repaired_sql = None
-                    candidate_sql = _apply_limit_policy(
-                        generated.sql,
-                        sql_question,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
+                        original_sql=candidate_sql,
+                        validation_error={
+                            "code": "SQL_RULE_VIOLATION",
+                            "message": str(exc),
+                        },
+                        schema_context=schema_context,
                     )
-                    enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
                 except SqlGenerationError:
                     return _query_only_result()
+                repaired_sql = _finalize_candidate_sql(
+                    repaired.sql,
+                    sql_question,
+                    default_limit=self.config.sql.default_limit,
+                    max_limit=self.config.sql.max_limit,
+                )
+                try:
+                    enforce_sql_rules(repaired_sql, max_limit=self.config.sql.max_limit)
+                except SqlGenerationError as repaired_exc:
+                    if _is_sensitive_sql_error(repaired_exc) and sensitive_terms:
+                        return _sensitive_query_only_result(sensitive_terms)
+                    return _query_only_result()
+                candidate_sql = repaired_sql
         normalized_sql = self._validate_sql(context, user_question, candidate_sql)
+        if normalized_sql is None and _is_auth_validation_error(self._validation_error_code()):
+            return _auth_error_result(
+                self._last_validation_result,
+                generated_sql=generated.sql,
+                repaired_sql=repaired_sql,
+            )
+        if normalized_sql is None and self._validation_error_code() in _LEGACY_EMPTY_SCOPE_CODES:
+            # Legacy online-version compatibility only (see _LEGACY_EMPTY_SCOPE_CODES):
+            # the current MCP contract returns an empty success result for no-scope
+            # users, which the normal flow already renders. Older deployments still
+            # emit these codes, so treat them as an empty result instead of raising.
+            return _empty_scope_result(user_question, result_format)
         if sampler is not None and normalized_sql is None and schema_context is not None and generator is not None:
             try:
                 repaired = generator.repair(
@@ -313,29 +407,10 @@ class SpongeAgent:
                     schema_context=schema_context,
                 )
             except SqlGenerationError:
-                try:
-                    if not fast_mode:
-                        return _query_only_result()
-                    generated = _generate_rule_based_sql(
-                        question=sql_question,
-                        schema=schema,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
-                    )
-                    repaired_sql = None
-                    candidate_sql = _apply_limit_policy(
-                        generated.sql,
-                        sql_question,
-                        default_limit=self.config.sql.default_limit,
-                        max_limit=self.config.sql.max_limit,
-                    )
-                    enforce_sql_rules(candidate_sql, max_limit=self.config.sql.max_limit)
-                    normalized_sql = self._validate_sql(context, user_question, candidate_sql, raise_on_error=True)
-                except SqlGenerationError:
-                    return _query_only_result()
+                return _query_only_result()
             else:
                 generated = GeneratedSql(sql="", tables=[], placeholders=[])
-                repaired_sql = _apply_limit_policy(
+                repaired_sql = _finalize_candidate_sql(
                     repaired.sql,
                     sql_question,
                     default_limit=self.config.sql.default_limit,
@@ -347,13 +422,23 @@ class SpongeAgent:
                     if _is_sensitive_sql_error(exc) and sensitive_terms:
                         return _sensitive_query_only_result(sensitive_terms)
                     return _query_only_result()
-                normalized_sql = self._validate_sql(context, user_question, repaired_sql, raise_on_error=True)
+                normalized_sql = self._validate_sql(context, user_question, repaired_sql)
+                if normalized_sql is None:
+                    if _is_auth_validation_error(self._validation_error_code()):
+                        return _auth_error_result(
+                            self._last_validation_result,
+                            generated_sql=generated.sql,
+                            repaired_sql=repaired_sql,
+                        )
+                    return _query_only_result()
         if normalized_sql is None:
             raise RuntimeError("SQL validation failed")
-        if sql_cache is not None and cached_sql is None and not is_low_quality_sql_for_question(sql_question, normalized_sql):
-            sql_cache.set(question=sql_question, schema_version=schema_version, sql=normalized_sql)
         result = self._execute_sql(context, user_question, normalized_sql)
+        result = self._ensure_limited_flag(result)
         answer = render_result(user_question, result, result_format)
+        entity_notice = _resolved_entity_notice(resolved_entities)
+        if entity_notice:
+            answer = _prepend_entity_notice(answer, user_question, result_format, entity_notice)
         if _should_append_default_limit_notice(
             question=sql_question,
             result=result,
@@ -429,6 +514,255 @@ class SpongeAgent:
             return cached_schema
         raise RuntimeError("Sponge get_schema did not return tables and no local schema cache exists")
 
+    def resolver(self) -> EntityResolver | None:
+        """Lazily build the entity resolver from the dictionary snapshot.
+
+        The dictionary is an optional, additive capability: if the MCP server
+        does not expose ``get_entity_dictionary`` and no cache exists, this
+        returns ``None`` and callers fall back to existing behaviour.
+        """
+        if self._resolver_loaded:
+            return self._resolver
+        self._resolver_loaded = True
+        dictionary = self._ensure_dictionary()
+        if dictionary is None or self.config.dictionary is None:
+            self._resolver = None
+            return None
+        version = str(dictionary.get("dictVersion") or "")
+        cached = _RESOLVER_CACHE.get(version) if version else None
+        if cached is not None:
+            self._resolver = cached
+            return cached
+        geo_aliases = load_geo_aliases(self.config.dictionary.geo_alias_path)
+        resolver = EntityResolver.from_payload(dictionary, geo_aliases=geo_aliases)
+        if version:
+            _RESOLVER_CACHE[version] = resolver
+        self._resolver = resolver
+        return resolver
+
+    def _ensure_dictionary(self) -> dict[str, Any] | None:
+        if self.dictionary_cache is None or self.config.dictionary is None:
+            return None
+        cached = self.dictionary_cache.load()
+        if cached is not None and self.dictionary_cache.is_fresh(
+            self.config.dictionary.refresh_interval_minutes
+        ):
+            return cached
+        cached_version = (
+            str(cached.get("dictVersion")) if cached and cached.get("dictVersion") else None
+        )
+        trace_id = new_trace_id("trace_dict")
+        try:
+            response = self.mcp_client.get_entity_dictionary(
+                trace_id=trace_id,
+                dict_version=cached_version,
+                entity_types=self.config.dictionary.entity_types,
+            )
+        except Exception:
+            if cached is not None:
+                self.audit_logger.log(
+                    {
+                        "traceId": trace_id,
+                        "tool": "get_entity_dictionary",
+                        "dictVersion": cached_version,
+                        "fallback": "cached_dictionary",
+                    }
+                )
+                return cached
+            return None
+
+        if response.get("changed") is False and cached is not None:
+            self.audit_logger.log(
+                {
+                    "traceId": trace_id,
+                    "tool": "get_entity_dictionary",
+                    "dictVersion": cached_version,
+                    "changed": False,
+                }
+            )
+            return cached
+
+        if "entities" in response:
+            self.dictionary_cache.save(response)
+            self.audit_logger.log(
+                {
+                    "traceId": trace_id,
+                    "tool": "get_entity_dictionary",
+                    "dictVersion": response.get("dictVersion"),
+                    "changed": response.get("changed"),
+                }
+            )
+            return response
+
+        return cached
+
+    def _compute_entity_bindings(self, sql_question: str) -> Any | None:
+        if self.config.binding is None:
+            return None
+        try:
+            resolver = self.resolver()
+            if resolver is None:
+                return None
+            return bind_entities(
+                sql_question,
+                resolver,
+                fuzzy_candidates=_regex_entity_spans(sql_question),
+                min_fuzzy_score=self.config.binding.min_fuzzy_score,
+            )
+        except Exception:  # pragma: no cover - binding must never break a query
+            return None
+
+    def _live_enabled_entity_types(self) -> tuple[str, ...]:
+        """Entity types whose bindings may drive SQL right now.
+
+        Empty while in shadow mode, so bindings are computed and logged but
+        never change SQL generation.
+        """
+        if self.config.binding is None or self.config.binding.shadow_mode:
+            return ()
+        return tuple(self.config.binding.enabled_entity_types)
+
+    def _resolved_entities_for_prompt(self, bindings: Any | None) -> dict[str, Any] | None:
+        """Serialize enabled bindings for injection into the LLM prompt.
+
+        The LLM uses these corrected entities (canonical name + id + the main
+        data table/column) together with schemaContext.joins to build correct
+        SQL. Returns ``None`` in shadow mode or when nothing is enabled/bound,
+        so the prompt is unchanged. Table relationships stay owned by the MCP
+        schema; this only supplies the normalized entity identity.
+        """
+        enabled = self._live_enabled_entity_types()
+        if bindings is None or not enabled:
+            return None
+        payload: dict[str, Any] = {}
+        if "brand" in enabled and bindings.brands:
+            payload["brands"] = [_resolved_entity_payload(entity) for entity in bindings.brands]
+        if "project" in enabled and bindings.projects:
+            payload["projects"] = [_resolved_entity_payload(entity) for entity in bindings.projects]
+        if "location" in enabled and bindings.location:
+            payload["location"] = {
+                level: _resolved_entity_payload(entity)
+                for level, entity in bindings.location.items()
+            }
+        return payload or None
+
+    def _enforce_resolved_entities(
+        self,
+        candidate_sql: str,
+        question: str,
+        resolved_entities: dict[str, Any] | None,
+        generator: SamplingSqlGenerator | None,
+        schema_context: Any | None,
+    ) -> tuple[str, list[str]]:
+        """Deterministic safety net for model compliance.
+
+        If the generated SQL has no trace of a recognized entity (id/name/core
+        completely absent), repair once with an explicit error. When repair
+        still misses entities, return the missing list so the caller can refuse
+        execute. The presence check is active for every generation path; the
+        LLM repair step is only used when a sampler is available.
+        """
+        if not resolved_entities:
+            return candidate_sql, []
+        missing = missing_entities_in_sql(candidate_sql, resolved_entities)
+        self.audit_logger.log(
+            {
+                "tool": "entity_enforcement",
+                "question": question,
+                "missing": missing,
+                "sql": candidate_sql,
+            }
+        )
+        if not missing:
+            return candidate_sql, []
+        if generator is None or schema_context is None:
+            return candidate_sql, missing
+        try:
+            repaired = generator.repair(
+                question=question,
+                original_sql=candidate_sql,
+                validation_error={
+                    "code": "MISSING_RESOLVED_ENTITY",
+                    "message": (
+                        "SQL 未对以下已识别实体过滤：" + "；".join(missing) + "。"
+                        "必须按 resolvedEntities 用最细粒度补齐这些过滤条件，"
+                        "地点有 region 时按 region 过滤。"
+                    ),
+                },
+                schema_context=schema_context,
+            )
+        except SqlGenerationError:
+            self.audit_logger.log(
+                {
+                    "tool": "entity_enforcement_repair",
+                    "question": question,
+                    "missingBefore": missing,
+                    "stillMissing": missing,
+                    "repairFailed": True,
+                }
+            )
+            return candidate_sql, missing
+        repaired_sql = _finalize_candidate_sql(
+            repaired.sql,
+            question,
+            default_limit=self.config.sql.default_limit,
+            max_limit=self.config.sql.max_limit,
+        )
+        still_missing = (
+            missing_entities_in_sql(repaired_sql, resolved_entities) if repaired_sql else missing
+        )
+        self.audit_logger.log(
+            {
+                "tool": "entity_enforcement_repair",
+                "question": question,
+                "missingBefore": missing,
+                "sqlAfter": repaired_sql or candidate_sql,
+                "stillMissing": still_missing,
+            }
+        )
+        if still_missing:
+            return repaired_sql or candidate_sql, still_missing
+        return repaired_sql or candidate_sql, []
+
+    def _log_entity_bindings_shadow(
+        self,
+        context: UserContext,
+        question: str,
+        sql_question: str,
+    ) -> None:
+        """Compute entity bindings and record them for comparison.
+
+        This logging path never changes SQL generation. It exists so the
+        binding pipeline can be validated against real traffic. Any failure
+        here must not break the actual query.
+        """
+        if self.config.binding is None:
+            return
+        try:
+            bindings = self._compute_entity_bindings(sql_question)
+            if bindings is None or bindings.is_empty():
+                return
+            self.audit_logger.log(
+                {
+                    "sessionId": context.session_id,
+                    "question": question,
+                    "tool": "entity_binding_shadow",
+                    "shadowMode": self.config.binding.shadow_mode,
+                    "enabledEntityTypes": list(self.config.binding.enabled_entity_types),
+                    "appliedEntityTypes": list(self._live_enabled_entity_types()),
+                    "bindings": bindings.to_log_dict(),
+                    "regexSpans": _regex_entity_spans(sql_question),
+                }
+            )
+        except Exception as exc:  # pragma: no cover - shadow logging must never break a query
+            self.audit_logger.log(
+                {
+                    "sessionId": context.session_id,
+                    "tool": "entity_binding_shadow",
+                    "error": f"{type(exc).__name__}: {exc}",
+                }
+            )
+
     def _validate_sql(
         self,
         context: UserContext,
@@ -467,6 +801,38 @@ class SpongeAgent:
         self._last_validation_trace_id = trace_id
         return str(result.get("normalizedSql") or sql)
 
+    def _validation_error_code(self) -> str | None:
+        error = self._last_validation_error
+        if isinstance(error, dict):
+            code = error.get("code")
+            return str(code) if code else None
+        return None
+
+    def _ensure_limited_flag(self, result: dict[str, Any]) -> dict[str, Any]:
+        """Derive `limited` from the validate-stage LIMIT when execute omits it.
+
+        MCP execute_sql does not return a `limited` flag (alignment checklist
+        supplementary #1); the agreed approach is to infer it client-side from
+        the LIMIT that validate_sql parsed. The ceiling is never hardcoded here:
+        the value always comes from MCP's validate response.
+        """
+        if "limited" in result:
+            return result
+        limit: int | None = None
+        if isinstance(self._last_validation_result, dict):
+            raw_limit = self._last_validation_result.get("limit")
+            if isinstance(raw_limit, int) and not isinstance(raw_limit, bool):
+                limit = raw_limit
+        if limit is None:
+            return result
+        row_count = result.get("rowCount")
+        if row_count is None:
+            rows = result.get("rows")
+            row_count = len(rows) if isinstance(rows, list) else None
+        if not isinstance(row_count, int):
+            return result
+        return {**result, "limited": row_count >= limit}
+
     def _execute_sql(self, context: UserContext, question: str, sql: str) -> dict[str, Any]:
         if self._last_validation_trace_id is None:
             raise RuntimeError("SQL execution requires a prior successful validate_sql trace")
@@ -497,6 +863,93 @@ class SpongeAgent:
         return result
 
 
+def _resolved_entity_tables(resolved_entities: Any | None) -> set[str]:
+    """Tables referenced by injected resolvedEntities, so the retriever pulls
+    in their MCP-maintained joins (e.g. brand -> brand_project -> project)."""
+    if not resolved_entities:
+        return set()
+    tables: set[str] = set()
+    for entity in resolved_entities.get("brands", []) or []:
+        if entity.get("table"):
+            tables.add(str(entity["table"]))
+    for entity in resolved_entities.get("projects", []) or []:
+        if entity.get("table"):
+            tables.add(str(entity["table"]))
+    location = resolved_entities.get("location") or {}
+    for entity in location.values():
+        if isinstance(entity, dict) and entity.get("table"):
+            tables.add(str(entity["table"]))
+    return tables
+
+
+def _resolved_entity_payload(entity: Any) -> dict[str, Any]:
+    """Compact entity descriptor for the LLM prompt (name + id + location)."""
+    return {
+        "name": entity.canonical,
+        "table": entity.table,
+        "column": entity.column,
+        "id": entity.id,
+    }
+
+
+def _regex_entity_spans(question: str) -> dict[str, list[str]]:
+    """Candidate entity spans from the existing regex extractors.
+
+    Fed to the binding layer as fuzzy candidates so typo/colloquial spans the
+    dictionary substring scan misses (e.g. "刘姐") can still resolve.
+    """
+    spans: dict[str, list[str]] = {}
+    brand = _extract_brand_name(question)
+    if brand:
+        spans["brand"] = [brand]
+    project = _extract_project_name(question)
+    if project:
+        spans["project"] = [project]
+    location = _extract_location_for_recruiting_job_question(question)
+    if location:
+        spans["location"] = [location]
+    return spans
+
+
+_CLARIFICATION_RESOLVED_SUFFIX = re.compile(
+    r"，按(?:品牌|项目)「.+?」(?:\(id:\s*[^)]+\))?查询\s*$"
+)
+_NEW_QUESTION_STARTERS = re.compile(
+    r"(?=你得查|你得|请查|请帮|另外|接下来|然后|再查|继续查|现在查|帮我查|还要查|再帮我)"
+)
+
+
+def _split_question_clauses(question: str) -> list[str]:
+    parts: list[str] = []
+    for chunk in re.split(r"[。；;\n]+", question):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        for part in _NEW_QUESTION_STARTERS.split(chunk):
+            cleaned = part.strip("，, ")
+            if cleaned:
+                parts.append(cleaned)
+    return parts
+
+
+def _isolate_current_question(question: str) -> str:
+    """When an orchestrator concatenates prior turns, keep the latest business clause."""
+    normalized = question.strip()
+    if not normalized:
+        return question
+    if _CLARIFICATION_RESOLVED_SUFFIX.search(normalized):
+        return question
+    parts = _split_question_clauses(normalized)
+    if len(parts) <= 1:
+        return question
+    business_parts = [part for part in parts if _is_business_query(part)]
+    if not business_parts:
+        return question
+    if len(business_parts) == 1:
+        return business_parts[0]
+    return business_parts[-1]
+
+
 def _strip_result_format_instruction(question: str) -> str:
     cleaned = question
     patterns = [
@@ -521,6 +974,30 @@ def _query_only_result() -> QueryResult:
     )
 
 
+def _missing_resolved_entities_result(missing: list[str]) -> QueryResult:
+    detail = "；".join(missing)
+    return QueryResult(
+        answer=(
+            f"已识别到{detail}，但本次生成的 SQL 未能正确加入对应筛选条件，无法执行查询。"
+            "请换一种问法重试。"
+        ),
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
+def _low_quality_sql_result(message: str, generated_sql: str) -> QueryResult:
+    return QueryResult(
+        answer=message,
+        generated_sql=generated_sql,
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
 def _sensitive_query_only_result(terms: list[str]) -> QueryResult:
     return QueryResult(
         answer=f"该查询包含敏感字段，{_sensitive_field_notice(terms)}已按当前 schema 判断，目前不支持该查询。",
@@ -531,6 +1008,28 @@ def _sensitive_query_only_result(terms: list[str]) -> QueryResult:
     )
 
 
+def _auth_error_result(
+    validation: dict[str, Any] | None,
+    *,
+    generated_sql: str = "",
+    repaired_sql: str | None = None,
+) -> QueryResult:
+    error = validation.get("error") if isinstance(validation, dict) else None
+    code = error.get("code") if isinstance(error, dict) else None
+    suffix = f"（错误码：{code}）" if code else ""
+    return QueryResult(
+        answer=f"当前 MCP 用户认证失败，无法校验和执行查询。请检查 MCP 访问 token 或重新登录后再试。{suffix}",
+        generated_sql=generated_sql,
+        normalized_sql="",
+        repaired_sql=repaired_sql,
+        validation=validation or {},
+    )
+
+
+def _is_auth_validation_error(code: str | None) -> bool:
+    return code in {"MCP_AUTH_INVALID_TOKEN", "MCP_AUTH_REQUIRED", "MCP_AUTH_FORBIDDEN"}
+
+
 def _business_metric_clarification_result(answer: str) -> QueryResult:
     return QueryResult(
         answer=answer,
@@ -541,6 +1040,113 @@ def _business_metric_clarification_result(answer: str) -> QueryResult:
     )
 
 
+def _entity_clarification_result(answer: str, payload: dict[str, Any] | None) -> QueryResult:
+    return QueryResult(
+        answer=answer,
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+        needs_clarification=True,
+        clarification_type="entity_resolution",
+        clarification_payload=payload,
+    )
+
+
+def _entity_ambiguity_clarification(bindings: Any | None) -> str | None:
+    ambiguity = getattr(bindings, "ambiguity", None)
+    if ambiguity is None:
+        return None
+
+    brands = list(getattr(ambiguity, "brands", []))
+    projects = list(getattr(ambiguity, "projects", []))
+    if brands and projects:
+        lines = [
+            f"“{ambiguity.term}”同时匹配到品牌和项目，请确认按哪类查询？",
+            "",
+            "品牌：",
+        ]
+        lines.extend(_format_entity_options(brands))
+        lines.extend(["", "项目："])
+    elif projects:
+        lines = [
+            f"“{ambiguity.term}”未完全匹配到唯一项目，请确认要查询哪个项目？",
+            "",
+            "项目：",
+        ]
+    elif brands:
+        lines = [
+            f"“{ambiguity.term}”未完全匹配到唯一品牌，请确认要查询哪个品牌？",
+            "",
+            "品牌：",
+        ]
+        lines.extend(_format_entity_options(brands))
+        return "\n".join(lines)
+    else:
+        return f"“{ambiguity.term}”未匹配到明确实体，请提供完整的品牌或项目名称。"
+
+    lines.extend(_format_entity_options(projects[:10]))
+    if len(projects) > 10:
+        lines.extend(
+            [
+                "",
+                "项目命中较多，当前只展示前 10 个；如果需要查询明确数据，请提供完整项目名称。",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def _entity_ambiguity_payload(bindings: Any | None) -> dict[str, Any] | None:
+    ambiguity = getattr(bindings, "ambiguity", None)
+    if ambiguity is None:
+        return None
+    brands = list(getattr(ambiguity, "brands", []))
+    projects = list(getattr(ambiguity, "projects", []))
+    return {
+        "term": getattr(ambiguity, "term", ""),
+        "brands": [_entity_candidate_payload(entity) for entity in brands],
+        "projects": [_entity_candidate_payload(entity) for entity in projects[:10]],
+        "projectTotal": len(projects),
+        "projectDisplayLimit": 10,
+        "projectTruncated": len(projects) > 10,
+        "instruction": "必须先把 answer 原文展示给用户并等待确认；不得自行选择候选项、不得改写问题、不得再次调用 query_sponge。",
+    }
+
+
+def _entity_candidate_payload(entity: Any) -> dict[str, Any]:
+    return {
+        "type": getattr(entity, "entity_type", ""),
+        "id": getattr(entity, "id", None),
+        "name": getattr(entity, "canonical", ""),
+        "matchedVia": getattr(entity, "matched_via", ""),
+        "score": getattr(entity, "score", None),
+    }
+
+
+def _format_entity_options(entities: list[Any]) -> list[str]:
+    if not entities:
+        return ["无"]
+    return [
+        f"{index}. {getattr(entity, 'canonical', '')}（id: {getattr(entity, 'id', '')}）"
+        for index, entity in enumerate(entities, start=1)
+    ]
+
+
+def _empty_scope_result(question: str, result_format: str | None) -> QueryResult:
+    # Reuses the standard empty-result rendering so the requested output format is
+    # respected. Only used as legacy compatibility for older online MCP versions
+    # (see _LEGACY_EMPTY_SCOPE_CODES); the current contract returns this shape
+    # directly as a normal success result.
+    answer = render_result(question, {"success": True, "rowCount": 0, "rows": []}, result_format)
+    return QueryResult(
+        answer=answer,
+        generated_sql="",
+        normalized_sql="",
+        repaired_sql=None,
+        validation={},
+    )
+
+
 def _sensitive_field_notice(terms: list[str]) -> str:
     if not terms:
         return "已排除敏感字段。"
@@ -558,7 +1164,7 @@ def _generate_with_sampler(
     generator: SamplingSqlGenerator,
     question: str,
     schema_context: Any,
-) -> tuple[GeneratedSql, str | None]:
+) -> tuple[GeneratedSql, str | None, bool]:
     try:
         return (
             generator.generate(
@@ -566,6 +1172,7 @@ def _generate_with_sampler(
                 schema_context=schema_context,
             ),
             None,
+            False,
         )
     except SqlGenerationError as sampling_exc:
         try:
@@ -576,56 +1183,77 @@ def _generate_with_sampler(
                 schema_context=schema_context,
             )
         except SqlGenerationError:
-            return GeneratedSql(sql="", tables=[], placeholders=[]), None
+            return GeneratedSql(sql="", tables=[], placeholders=[]), None, True
         return (
             GeneratedSql(sql="", tables=[], placeholders=[]),
-            _apply_limit_policy(
+            _finalize_candidate_sql(
                 repaired.sql,
                 question,
                 default_limit=generator.default_limit,
                 max_limit=generator.max_limit,
             ),
+            True,
         )
 
 
-def _generate_rule_based_sql(
+def _generate_from_schema_example(
     *,
     question: str,
-    schema: dict[str, Any],
-    default_limit: int,
-    max_limit: int,
-) -> GeneratedSql:
-    generator = RuleBasedSqlGenerator(
-        default_limit=default_limit,
-        max_limit=max_limit,
-    )
-    return generator.generate(
-        question=question,
-        schema=schema,
+    schema_context: Any,
+) -> GeneratedSql | None:
+    examples = _business_examples(getattr(schema_context, "examples", []) or [])
+    best: tuple[int, dict[str, Any]] | None = None
+    for example in examples:
+        if not isinstance(example, dict) or not isinstance(example.get("sql"), str):
+            continue
+        if not _is_high_match_example(question, str(example.get("question") or "")):
+            continue
+        score = _example_match_score(question, str(example.get("question") or ""))
+        if best is None or score > best[0]:
+            best = (score, example)
+    if best is None:
+        return None
+    example = best[1]
+    tables = example.get("tables") if isinstance(example.get("tables"), list) else []
+    return GeneratedSql(
+        sql=str(example["sql"]).strip(),
+        tables=[str(table) for table in tables],
+        placeholders=[],
     )
 
 
-def _generate_sampling_fallback_sql(
-    *,
-    question: str,
-    schema: dict[str, Any],
-    default_limit: int,
-    max_limit: int,
-) -> GeneratedSql:
-    if re.search(r"(岗位|职位|招聘|在招)", question) is None:
-        raise SqlGenerationError("No sampling fallback matched the question")
-    return _generate_rule_based_sql(
-        question=question,
-        schema=schema,
-        default_limit=default_limit,
-        max_limit=max_limit,
-    )
+def _is_high_match_example(question: str, example_question: str) -> bool:
+    if not question or not example_question:
+        return False
+    question_compact = _compact_match_text(question)
+    example_compact = _compact_match_text(example_question)
+    if len(example_compact) >= 12 and (example_compact in question_compact or question_compact in example_compact):
+        return True
+    question_tokens = set(_match_tokens(question))
+    example_tokens = set(_match_tokens(example_question))
+    if not question_tokens or not example_tokens:
+        return False
+    overlap = len(question_tokens & example_tokens)
+    return overlap >= 8 and overlap / min(len(question_tokens), len(example_tokens)) >= 0.65
 
 
-def _make_query_sql_cache(config: AppConfig) -> QuerySqlCache | None:
-    if config.sql.query_cache_path is None:
-        return None
-    return QuerySqlCache(config.sql.query_cache_path, config.sql.query_cache_ttl_minutes)
+def _example_match_score(question: str, example_question: str) -> int:
+    question_tokens = set(_match_tokens(question))
+    example_tokens = set(_match_tokens(example_question))
+    return len(question_tokens & example_tokens)
+
+
+def _compact_match_text(text: str) -> str:
+    return "".join(re.findall(r"[A-Za-z0-9\u4e00-\u9fff]+", text.lower()))
+
+
+def _match_tokens(text: str) -> list[str]:
+    compact = _compact_match_text(text)
+    tokens = re.findall(r"[a-z0-9]+", compact)
+    cjk = "".join(re.findall(r"[\u4e00-\u9fff]+", compact))
+    for index in range(max(0, len(cjk) - 1)):
+        tokens.append(cjk[index : index + 2])
+    return list(dict.fromkeys(tokens))
 
 
 def _is_mutation_request(question: str) -> bool:
@@ -636,11 +1264,30 @@ def _is_mutation_request(question: str) -> bool:
     )
     if mutation_match is None:
         return False
+    if _is_status_enum_query(question):
+        return False
     if _is_mutation_analytics_request(question):
         return False
     return True
 
 
+def _is_status_enum_query(question: str) -> bool:
+    """Allow read-only queries that mention publish/offline status labels."""
+    has_read_intent = re.search(
+        r"(查询|查看|看看|搜索|统计|多少|哪些|有哪些|列表|明细|展示|返回|状态|数量|数|总数)",
+        question,
+        flags=re.IGNORECASE,
+    )
+    has_status_label = re.search(r"(已发布|未发布|已下架|已上架|在招)", question)
+    if has_read_intent and has_status_label and re.search(r"(岗位|职位)", question):
+        return True
+    return bool(
+        has_read_intent
+        and re.search(r"(岗位状态|状态|包括|包含|为|是|=|:|：)", question)
+        and has_status_label
+    )
+
+
 def _is_mutation_analytics_request(question: str) -> bool:
     return bool(
         re.search(r"(统计|查询|查看|看看|多少|几次|次数|数量|count|列表|明细|记录|日志|历史|趋势|分组)", question, flags=re.IGNORECASE)
@@ -779,6 +1426,235 @@ def _schema_has_metric_definition(question: str, schema: dict[str, Any], metric_
     return any(term in metric_text for term in metric_terms for metric_text in metric_texts)
 
 
+def _finalize_candidate_sql(
+    sql: str,
+    question: str,
+    *,
+    default_limit: int,
+    max_limit: int,
+    schema: dict[str, Any] | None = None,
+) -> str:
+    normalized = normalize_text_filters_to_like(sql)
+    normalized = normalize_job_count_sql(normalized, question, schema=schema)
+    return _apply_limit_policy(normalized, question, default_limit=default_limit, max_limit=max_limit)
+
+
+def _is_job_count_question(question: str) -> bool:
+    return _is_job_count_intent_question(question)
+
+
+def _is_job_list_question(question: str) -> bool:
+    if _is_job_count_question(question):
+        return False
+    return bool(
+        re.search(r"(岗位|职位)", question)
+        and re.search(r"(哪些|有什么|列表|明细|清单|查询|查看|看看|列出|返回|展示)", question)
+    )
+
+
+def _generate_from_resolved_entities(
+    *,
+    question: str,
+    resolved_entities: dict[str, Any] | None,
+    schema: dict[str, Any],
+    default_limit: int,
+) -> GeneratedSql | None:
+    if not resolved_entities:
+        return None
+
+    location = resolved_entities.get("location") or {}
+    location_filter = _resolved_location_job_filter(location)
+    if location_filter is None:
+        return None
+
+    projects = resolved_entities.get("projects") or []
+    brands = resolved_entities.get("brands") or []
+    entity_filter: str | None = None
+    extra_tables: list[str] = []
+    if projects:
+        project_id = projects[0].get("id")
+        if project_id is None:
+            return None
+        entity_filter = f"sp.id = {project_id}"
+        extra_tables = ["sponge_project"]
+    elif brands:
+        brand_id = brands[0].get("id")
+        if brand_id is None:
+            return None
+        entity_filter = f"jbi.brand_id = {brand_id}"
+    else:
+        return None
+
+    if _is_job_list_question(question):
+        return _generate_job_list_from_resolved_entities(
+            question=question,
+            schema=schema,
+            default_limit=default_limit,
+            entity_filter=entity_filter,
+            location_filter=location_filter,
+            projects=projects,
+            location=location,
+        )
+
+    if not _is_job_count_question(question):
+        return None
+
+    status_values = _requested_job_status_values(question, schema)
+    status_clause = ""
+    if status_values:
+        status_clause = f" AND jbi.status IN ({', '.join(sorted(status_values, key=int))})"
+    elif _user_requests_recruiting_job_count(question, schema):
+        status_enum = _status_enum(schema, "job_basic_info.status")
+        recruiting_values: set[str] = set()
+        if status_enum:
+            for item in status_enum:
+                value = item.get("value")
+                labels = _enum_label_terms(str(item.get("label") or ""))
+                if value is None:
+                    continue
+                if any(label in {"在招", "已发布", "已上架"} or "在招" in label for label in labels):
+                    recruiting_values.add(str(value))
+        if recruiting_values:
+            status_clause = f" AND jbi.status IN ({', '.join(sorted(recruiting_values, key=int))})"
+
+    count_alias = _preferred_count_alias(question) or "岗位总数"
+    project_join = (
+        "INNER JOIN sponge_project sp ON sp.id = jbi.organization_id AND sp.is_delete = 0 "
+        if projects
+        else ""
+    )
+    sql = (
+        f"SELECT COUNT(DISTINCT jbi.id) AS {count_alias} "
+        "FROM job_basic_info jbi "
+        f"{project_join}"
+        "LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0 "
+        "LEFT JOIN store s ON s.id = js.store_id AND s.delete_at IS NULL "
+        "LEFT JOIN job_address ja ON ja.job_id = jbi.job_id AND ja.delete_at IS NULL "
+        "WHERE jbi.is_deleted = 0 "
+        f"AND {entity_filter} "
+        f"AND ({location_filter})"
+        f"{status_clause} "
+        f"LIMIT {default_limit}"
+    )
+    tables = ["job_basic_info", "job_store", "store", "job_address", *extra_tables]
+    return GeneratedSql(
+        sql=sql,
+        tables=tables,
+        placeholders=[],
+    )
+
+
+def _generate_job_list_from_resolved_entities(
+    *,
+    question: str,
+    schema: dict[str, Any],
+    default_limit: int,
+    entity_filter: str,
+    location_filter: str,
+    projects: list[Any],
+    location: dict[str, Any],
+) -> GeneratedSql | None:
+    required_columns = (
+        ("job_basic_info", "id"),
+        ("job_basic_info", "job_name"),
+        ("job_basic_info", "status"),
+        ("job_basic_info", "is_deleted"),
+        ("job_basic_info", "organization_id"),
+        ("job_basic_info", "job_id"),
+        ("sponge_project", "id"),
+        ("sponge_project", "name"),
+        ("sponge_project", "is_delete"),
+        ("job_store", "job_basic_info_id"),
+        ("job_store", "store_id"),
+        ("job_store", "is_deleted"),
+        ("store", "id"),
+        ("store", "city_id"),
+        ("store", "region_id"),
+        ("store", "delete_at"),
+        ("job_address", "job_id"),
+        ("job_address", "city_id"),
+        ("job_address", "region_id"),
+        ("job_address", "delete_at"),
+    )
+    if any(not _schema_has_column(schema, table, column) for table, column in required_columns):
+        return None
+
+    status_values = _requested_job_status_values(question, schema)
+    status_clause = ""
+    if status_values:
+        status_clause = f" AND jbi.status IN ({', '.join(sorted(status_values, key=int))})"
+    status_expr = _job_status_select_expression(schema)
+    city_name = _sql_string_literal(_resolved_location_display_name(location))
+    project_join = (
+        "INNER JOIN sponge_project sp ON sp.id = jbi.organization_id AND sp.is_delete = 0 "
+        if projects
+        else "LEFT JOIN sponge_project sp ON sp.id = jbi.organization_id AND sp.is_delete = 0 "
+    )
+    sql = (
+        "SELECT DISTINCT "
+        "jbi.id AS 岗位ID, "
+        "jbi.job_name AS 岗位名称, "
+        "sp.name AS 项目名称, "
+        f"{city_name} AS 城市, "
+        f"{status_expr} AS 岗位状态 "
+        "FROM job_basic_info jbi "
+        f"{project_join}"
+        "LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0 "
+        "LEFT JOIN store s ON s.id = js.store_id AND s.delete_at IS NULL "
+        "LEFT JOIN job_address ja ON ja.job_id = jbi.job_id AND ja.delete_at IS NULL "
+        "WHERE jbi.is_deleted = 0 "
+        f"AND {entity_filter} "
+        f"AND ({location_filter})"
+        f"{status_clause} "
+        "ORDER BY jbi.id DESC "
+        f"LIMIT {default_limit}"
+    )
+    return GeneratedSql(
+        sql=sql,
+        tables=["job_basic_info", "sponge_project", "job_store", "store", "job_address"],
+        placeholders=[],
+    )
+
+
+def _job_status_select_expression(schema: dict[str, Any]) -> str:
+    status_enum = _status_enum(schema, "job_basic_info.status")
+    if not status_enum:
+        return "jbi.status"
+    clauses: list[str] = []
+    for item in status_enum:
+        value = item.get("value")
+        label = str(item.get("label") or "").strip()
+        if value is None or not label:
+            continue
+        clauses.append(f"WHEN {value} THEN {_sql_string_literal(label)}")
+    if not clauses:
+        return "jbi.status"
+    return "CASE jbi.status " + " ".join(clauses) + " ELSE jbi.status END"
+
+
+def _resolved_location_display_name(location: dict[str, Any]) -> str:
+    entity = location.get("region") or location.get("city") or location.get("province") or {}
+    if isinstance(entity, dict):
+        return str(entity.get("name") or "")
+    return ""
+
+
+def _sql_string_literal(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _resolved_location_job_filter(location: dict[str, Any]) -> str | None:
+    region = location.get("region")
+    if isinstance(region, dict) and region.get("id") is not None:
+        region_id = region["id"]
+        return f"s.region_id = {region_id}"
+    city = location.get("city")
+    if isinstance(city, dict) and city.get("id") is not None:
+        city_id = city["id"]
+        return f"s.city_id = {city_id}"
+    return None
+
+
 def _apply_limit_policy(sql: str, question: str, *, default_limit: int, max_limit: int) -> str:
     if _question_requests_all_rows(question):
         return _replace_limit(sql, max_limit)
@@ -795,7 +1671,10 @@ def _apply_default_limit(sql: str, question: str, default_limit: int) -> str:
 
 
 def _replace_limit(sql: str, limit: int) -> str:
-    return re.sub(r"\blimit\s+\d+\b", f"LIMIT {limit}", sql, count=1, flags=re.IGNORECASE)
+    stripped = sql.strip().rstrip(";")
+    if re.search(r"\blimit\s+\d+\b", stripped, flags=re.IGNORECASE):
+        return re.sub(r"\blimit\s+\d+\b", f"LIMIT {limit}", stripped, count=1, flags=re.IGNORECASE)
+    return f"{stripped} LIMIT {limit}"
 
 
 def _question_requests_limit(question: str) -> bool:
@@ -842,6 +1721,80 @@ def _should_append_default_limit_notice(*, question: str, result: dict[str, Any]
     return row_count == default_limit
 
 
+def _resolved_entity_notice(resolved_entities: Any | None) -> str | None:
+    """Human-readable note of which entities were recognized and applied.
+
+    Only present when binding is live and matched (resolved_entities non-empty),
+    so the user sees how their colloquial wording was normalized (e.g. the
+    canonical brand name actually used to filter).
+    """
+    if not resolved_entities:
+        return None
+    parts: list[str] = []
+    brands = resolved_entities.get("brands") or []
+    if brands:
+        parts.append("品牌「" + "、".join(str(item["name"]) for item in brands) + "」")
+    projects = resolved_entities.get("projects") or []
+    if projects:
+        parts.append("项目「" + "、".join(str(item["name"]) for item in projects) + "」")
+    location = resolved_entities.get("location") or {}
+    if location:
+        location_names: list[str] = []
+        for level in ("province", "city", "region"):
+            entity = location.get(level)
+            if not entity:
+                continue
+            name = str(entity["name"])
+            # 直辖市的省名与市名相同，去掉相邻重复，避免「上海市 / 上海市」
+            if location_names and location_names[-1] == name:
+                continue
+            location_names.append(name)
+        if location_names:
+            parts.append("地点「" + " / ".join(location_names) + "」")
+    if not parts:
+        return None
+    return "已识别并用于筛选：" + "；".join(parts) + "。"
+
+
+def _append_entity_notice(answer: str, question: str, result_format: str | None, notice: str) -> str:
+    output_format = normalize_result_format(question, result_format)
+    if output_format == "json":
+        try:
+            payload = json.loads(answer)
+        except json.JSONDecodeError:
+            return f"{answer}\n\n{notice}"
+        if isinstance(payload, dict):
+            payload["recognizedEntities"] = notice
+            return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+    if output_format == "yaml":
+        return f"{answer.rstrip()}\nrecognizedEntities: {notice}\n"
+    if output_format == "html":
+        return f"{answer}<p>{notice}</p>"
+    return f"{answer}\n\n{notice}"
+
+
+def _prepend_entity_notice(answer: str, question: str, result_format: str | None, notice: str) -> str:
+    """Lead the answer with the recognized-entity note.
+
+    Placed first (not appended) so the upper model is more likely to surface it
+    when it reformats the tool output.
+    """
+    output_format = normalize_result_format(question, result_format)
+    if output_format == "json":
+        try:
+            payload = json.loads(answer)
+        except json.JSONDecodeError:
+            return f"{notice}\n\n{answer}"
+        if isinstance(payload, dict):
+            payload["recognizedEntities"] = notice
+            return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+    if output_format == "yaml":
+        return f"recognizedEntities: {notice}\n{answer}"
+    if output_format == "html":
+        return f"<p>{notice}</p>{answer}"
+    return f"{notice}\n\n{answer}"
+
+
 def _append_default_limit_notice(answer: str, question: str, result_format: str | None, notice: str) -> str:
     output_format = normalize_result_format(question, result_format)
     if output_format == "json":