@roll-agent/octopus-agent 0.0.10 → 0.0.11

package/src/octopus_skill/octopus_run.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
 import json
+import re
 import sys
+import time
 from dataclasses import asdict, is_dataclass
+from pathlib import Path
 from typing import Any, Callable
 
 from . import __version__
@@ -17,6 +20,10 @@ PROTOCOL_VERSION = "2024-11-05"
 Json = dict[str, Any]
 AgentFactory = Callable[[], SpongeAgent]
 SamplerFactory = Callable[[str, str], str]
+_DEFAULT_CLARIFICATION_SESSION = "__default__"
+_PENDING_CLARIFICATIONS: dict[str, Json] = {}
+_CLARIFICATION_CACHE_PATH = Path.cwd() / "data/sponge-clarification-cache.json"
+_CLARIFICATION_CACHE_TTL_SECONDS = 10 * 60
 
 
 def main() -> None:
@@ -97,7 +104,7 @@ def tool_definitions() -> list[Json]:
         },
         {
             "name": "query_sponge",
-            "description": "业务查询唯一入口：把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。本工具内部第一步会检查本地 schemaVersion，并调用 Sponge get_schema 按需刷新 schema cache；普通业务查询不得额外调用 refresh_schema。上层模型必须直接调用本工具；不要先调用 diagnostic_status 或 refresh_schema；query_sponge 返回“目前不支持该查询”后也不要自行 retry fastMode=false 或再调用 refresh_schema，除非用户明确要求调试；不要自行生成 SQL；不要解释 schema；不要要求用户提供 SQL；不要改写用户问题。originalQuestion 必须传用户原始话术；如果 question 被上层改写，Agent 会忽略改写版并优先用 originalQuestion 生成 SQL、审计和缓存。对“匹配效果/分析报告/报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，必须只调用一次 query_sponge 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。工具返回后应把 answer 原文复制到最终答复正文完整展示，不要只放在折叠步骤、思考过程或工具调用详情中；如果 answer 已包含分析报告，必须先展示完整报告，再展示总结关键发现；不要自行汇总替代 answer，不要追加“是否继续查询/是否需要更多字段/我可以继续帮你”等引导。默认 fastMode=true、finalAnswerOnly=true，会优先使用规则模板，复杂查询会使用 schema context 和 LLM 生成。",
+            "description": "业务查询唯一入口：把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。本工具内部第一步会检查本地 schemaVersion，并调用 Sponge get_schema 按需刷新 schema cache；普通业务查询不得额外调用 refresh_schema。上层模型必须直接调用本工具；不要先调用 diagnostic_status 或 refresh_schema；query_sponge 返回“目前不支持该查询”后也不要自行 retry fastMode=false 或再调用 refresh_schema，除非用户明确要求调试；不要自行生成 SQL；不要解释 schema；不要要求用户提供 SQL；不要改写用户问题。originalQuestion 必须传用户原始话术；如果 question 被上层改写，Agent 会忽略改写版并优先用 originalQuestion 生成 SQL 和审计。对“匹配效果/分析报告/报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，必须只调用一次 query_sponge 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。工具返回后必须把 content[0].text 或 structuredContent.answer 原文作为最终用户可见答复完整展示，最终消息必须直接包含完整业务答案；不要只放在折叠步骤、思考过程、工具详情或可折叠步骤里，不要自行改写成摘要；finalAnswerOnly=true（默认）时只能使用 structuredContent.answer 作为最终回复，不得改写、删减或追加内容；如果 structuredContent.needsClarification=true，必须立即停止，用户未确认前不得再次调用 query_sponge，不得自行选择品牌/项目/地点候选，不得把品牌+地点拼成项目名，必须原样展示 structuredContent.answer 并等待用户确认；用户确认品牌/项目后，不要重新发现工具，不要调用 diagnostic_status 或 refresh_schema，不要解释 schema，不要自行判断“schema 不支持项目维度”，必须直接再次调用 query_sponge 并传 clarificationSelection；clarificationSelection 必须包含 baseQuestion、entityType、entityId、entityName，优先从 structuredContent.clarificationContext 构造，避免依赖进程内存。如果 answer 已包含分析报告，必须先展示完整报告，再展示总结关键发现；不要自行汇总替代 answer，不要追加“是否继续查询/是否需要更多字段/我可以继续帮你”等引导。如果 answer 开头包含“已识别并用于筛选：…”这类实体识别说明（说明系统已把口语/简称/错字归一为标准品牌、项目、地点并据此过滤），必须在最终回复中原样保留并展示这条说明，不得删除或改写，便于用户确认筛选口径。默认 fastMode=true、finalAnswerOnly=true，structuredContent.responseMode=verbatim，便于上层 Agent 直接把 answer 展示给用户；复杂查询会使用 schema context 和 LLM 生成。",
             "inputSchema": {
                 "type": "object",
                 "required": ["question", "originalQuestion"],
@@ -109,11 +116,11 @@ def tool_definitions() -> list[Json]:
                     },
                     "fastMode": {
                         "type": "boolean",
-                        "description": "是否启用快路径；默认 true。true 时优先使用本地 schema 缓存、SQL 缓存和规则模板，失败才走 LLM；false 时优先让 LLM 生成 SQL。",
+                        "description": "是否启用快路径；默认 true。true 时优先使用本地 schema 缓存和规则模板，失败才走 LLM；false 时优先让 LLM 生成 SQL。",
                     },
                     "finalAnswerOnly": {
                         "type": "boolean",
-                        "description": "是否只返回最终业务答案；默认 true。普通上层 Agent 应保持 true，并在最终回复正文原文复制 answer，不要只放在折叠步骤里，不要追加后续引导。includeSql=true 的显式调试请求仍会返回 SQL 调试信息。",
+                        "description": "是否只返回最终业务答案；默认 true。true 时 content 与 structuredContent.answer 均为 verbatim 业务答复，上层 Agent 必须原样展示给用户，不要只放在折叠步骤里，不要改写成摘要或追加后续引导。includeSql=true 的显式调试请求仍会返回 SQL 调试信息。",
                     },
                     "sessionId": {"type": "string", "description": "可选会话 ID"},
                     "resultFormat": {
@@ -125,6 +132,31 @@ def tool_definitions() -> list[Json]:
                         "type": "boolean",
                         "description": "是否在回参中包含 generatedSql、normalizedSql、repairedSql 等调试信息",
                     },
+                    "clarificationSelection": {
+                        "type": "object",
+                        "required": ["entityType", "entityId"],
+                        "description": "用户已确认候选项时传入的结构化选择。未经用户确认不得传；无状态调用必须同时传 baseQuestion 和 entityName。",
+                        "properties": {
+                            "baseQuestion": {
+                                "type": "string",
+                                "description": "原始业务问题，优先使用上一轮 structuredContent.clarificationContext.baseQuestion",
+                            },
+                            "entityType": {
+                                "type": "string",
+                                "enum": ["brand", "project"],
+                                "description": "实体类型：brand=品牌，project=项目",
+                            },
+                            "entityId": {
+                                "type": ["integer", "string"],
+                                "description": "候选实体 ID，必须来自上一轮 clarificationPayload",
+                            },
+                            "entityName": {
+                                "type": "string",
+                                "description": "候选实体名称，必须来自上一轮 clarificationPayload",
+                            },
+                        },
+                        "additionalProperties": False,
+                    },
                 },
                 "additionalProperties": False,
             },
@@ -152,28 +184,45 @@ def call_tool(
             )
         if tool_name == "query_sponge":
             agent = _make_agent(agent_factory)
+            question = _required_string(arguments, "question")
+            original_question = _required_string(arguments, "originalQuestion")
+            session_id = arguments.get("sessionId")
+            resolved_question = _resolve_pending_clarification(
+                question=question,
+                original_question=original_question,
+                session_id=session_id,
+                clarification_selection=arguments.get("clarificationSelection"),
+            )
+            if resolved_question is not None:
+                question = resolved_question
+                original_question = resolved_question
+                _forget_pending_clarification(session_id)
+            elif not _is_clarification_reply(original_question):
+                _forget_pending_clarification(session_id)
             answer_kwargs = {
-                "question": _required_string(arguments, "question"),
-                "original_question": _required_string(arguments, "originalQuestion"),
+                "question": question,
+                "original_question": original_question,
                 "fast_mode": _optional_bool(arguments, "fastMode", default=True),
-                "session_id": arguments.get("sessionId"),
+                "session_id": session_id,
                 "result_format": arguments.get("resultFormat"),
             }
             final_answer_only = _optional_bool(arguments, "finalAnswerOnly", default=True)
             if sampler is not None:
                 answer_kwargs["sampler"] = sampler
             query_result = agent.query(**answer_kwargs)
+            _sync_pending_clarification(
+                query_result,
+                question=question,
+                original_question=original_question,
+                session_id=session_id,
+            )
+            base_question = original_question or question
             if arguments.get("includeSql") is True:
-                return _tool_json(
-                    {
-                        "answer": query_result.answer,
-                        "generatedSql": query_result.generated_sql,
-                        "normalizedSql": query_result.normalized_sql,
-                        "repairedSql": query_result.repaired_sql,
-                        "validation": query_result.validation,
-                    }
-                )
-            return _tool_text(query_result.answer)
+                payload = _query_result_payload(query_result, include_sql=True, base_question=base_question)
+                return _tool_json(payload, structured_content=payload)
+            if final_answer_only:
+                return _tool_final_answer(query_result, base_question=base_question)
+            return _tool_query_answer(query_result, final_answer_only=False, base_question=base_question)
         return _tool_error(f"Unknown tool: {tool_name}", code="unknown_tool")
     except Exception as exc:
         return _tool_error(str(exc), code=type(exc).__name__)
@@ -205,6 +254,22 @@ def _diagnostic_status(config: AppConfig) -> Json:
             "enabled": config.audit.enabled,
             "logPath": str(config.audit.log_path),
         },
+        "binding": _binding_status(config),
+    }
+
+
+def _binding_status(config: AppConfig) -> Json:
+    binding = config.binding
+    dictionary = config.dictionary
+    return {
+        "configured": binding is not None,
+        "shadowMode": bool(binding.shadow_mode) if binding is not None else None,
+        "enabledEntityTypes": list(binding.enabled_entity_types) if binding is not None else [],
+        "minFuzzyScore": binding.min_fuzzy_score if binding is not None else None,
+        "dictionaryCachePath": str(dictionary.cache_path) if dictionary is not None else None,
+        "dictionaryCacheExists": dictionary.cache_path.exists() if dictionary is not None else False,
+        "geoAliasPath": str(dictionary.geo_alias_path) if dictionary is not None else None,
+        "geoAliasExists": dictionary.geo_alias_path.exists() if dictionary is not None else False,
     }
 
 
@@ -286,12 +351,296 @@ def _required_int(arguments: Json, key: str) -> int:
     return value
 
 
+def _clarification_key(session_id: Any) -> str:
+    if isinstance(session_id, str) and session_id.strip():
+        return session_id
+    return _DEFAULT_CLARIFICATION_SESSION
+
+
+def _forget_pending_clarification(session_id: Any) -> None:
+    _PENDING_CLARIFICATIONS.pop(_clarification_key(session_id), None)
+    _delete_cached_clarification(session_id)
+
+
+def _load_pending_clarification(session_id: Any) -> Json | None:
+    key = _clarification_key(session_id)
+    cached = _read_clarification_cache().get(key)
+    if not isinstance(cached, dict):
+        return None
+    updated_at = cached.get("updatedAt")
+    if not isinstance(updated_at, (int, float)) or time.time() - float(updated_at) > _CLARIFICATION_CACHE_TTL_SECONDS:
+        _delete_cached_clarification(session_id)
+        return None
+    question = cached.get("question")
+    payload = cached.get("payload")
+    if not isinstance(question, str) or not isinstance(payload, dict):
+        _delete_cached_clarification(session_id)
+        return None
+    pending = {"question": question, "payload": payload}
+    _PENDING_CLARIFICATIONS[key] = pending
+    return pending
+
+
+def _save_pending_clarification(session_id: Any, pending: Json) -> None:
+    question = pending.get("question")
+    payload = pending.get("payload")
+    if not isinstance(question, str) or not isinstance(payload, dict):
+        return
+    items = _read_clarification_cache()
+    items[_clarification_key(session_id)] = {
+        "updatedAt": time.time(),
+        "question": question,
+        "payload": payload,
+    }
+    _write_clarification_cache(items)
+
+
+def _delete_cached_clarification(session_id: Any) -> None:
+    items = _read_clarification_cache()
+    key = _clarification_key(session_id)
+    if key not in items:
+        return
+    items.pop(key, None)
+    _write_clarification_cache(items)
+
+
+def _read_clarification_cache() -> dict[str, Json]:
+    try:
+        if not _CLARIFICATION_CACHE_PATH.exists():
+            return {}
+        data = json.loads(_CLARIFICATION_CACHE_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    items = data.get("items")
+    return items if isinstance(items, dict) else {}
+
+
+def _write_clarification_cache(items: dict[str, Json]) -> None:
+    try:
+        if items:
+            _CLARIFICATION_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+            _CLARIFICATION_CACHE_PATH.write_text(
+                json.dumps({"items": items}, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+                encoding="utf-8",
+            )
+        elif _CLARIFICATION_CACHE_PATH.exists():
+            _CLARIFICATION_CACHE_PATH.unlink()
+    except OSError:
+        return
+
+
+def _sync_pending_clarification(
+    query_result: Any,
+    *,
+    question: str,
+    original_question: str,
+    session_id: Any,
+) -> None:
+    payload = getattr(query_result, "clarification_payload", None)
+    if (
+        bool(getattr(query_result, "needs_clarification", False))
+        and getattr(query_result, "clarification_type", None) == "entity_resolution"
+        and isinstance(payload, dict)
+        and (payload.get("brands") or payload.get("projects"))
+    ):
+        pending = {
+            "question": original_question or question,
+            "payload": _jsonable(payload),
+        }
+        _PENDING_CLARIFICATIONS[_clarification_key(session_id)] = pending
+        _save_pending_clarification(session_id, pending)
+        return
+    _forget_pending_clarification(session_id)
+
+
+def _resolve_pending_clarification(
+    *,
+    question: str,
+    original_question: str,
+    session_id: Any,
+    clarification_selection: Any = None,
+) -> str | None:
+    pending = _PENDING_CLARIFICATIONS.get(_clarification_key(session_id)) or _load_pending_clarification(session_id)
+    if clarification_selection is not None:
+        selected = None
+        if pending is not None:
+            selected = _select_structured_clarification_candidate(clarification_selection, pending.get("payload"))
+        if selected is None:
+            return _stateless_clarification_question(clarification_selection)
+    else:
+        text = original_question or question
+        if not _is_clarification_reply(text):
+            return None
+        if pending is None:
+            return None
+        selected = _select_clarification_candidate(text, pending.get("payload"))
+    if selected is None:
+        return None
+    entity_type, candidate = selected
+    label = "品牌" if entity_type == "brand" else "项目"
+    name = str(candidate.get("name") or "")
+    entity_id = candidate.get("id")
+    base_question = str(pending.get("question") or question)
+    if entity_id is None:
+        return f"{base_question}，按{label}「{name}」查询"
+    return f"{base_question}，按{label}「{name}」(id: {entity_id})查询"
+
+
+def _is_clarification_reply(text: str) -> bool:
+    cleaned = _normalize_clarification_reply(text)
+    if len(cleaned) > 30:
+        return False
+    return bool(
+        re.fullmatch(r"(?:按)?(?:品牌|项目)(?:查询)?(?:id)?\d*", cleaned)
+        or re.fullmatch(r"(?:品牌|项目)\d+", cleaned)
+    )
+
+
+def _normalize_clarification_reply(text: str) -> str:
+    return re.sub(r"[\s:：,，。;；()（）「」“”\"'《》【】]+", "", text or "").lower()
+
+
+def _select_clarification_candidate(text: str, payload: Any) -> tuple[str, Json] | None:
+    if not isinstance(payload, dict):
+        return None
+    cleaned = _normalize_clarification_reply(text)
+    wants_brand = "品牌" in cleaned
+    wants_project = "项目" in cleaned
+    if wants_brand == wants_project:
+        return None
+    entity_type = "brand" if wants_brand else "project"
+    candidates = payload.get("brands" if entity_type == "brand" else "projects")
+    if not isinstance(candidates, list) or not candidates:
+        return None
+    id_match = re.search(r"(?<!\d)(\d+)(?!\d)", cleaned)
+    if id_match is not None:
+        wanted_id = id_match.group(1)
+        for candidate in candidates:
+            if isinstance(candidate, dict) and str(candidate.get("id")) == wanted_id:
+                return entity_type, candidate
+        return None
+    for candidate in candidates:
+        if isinstance(candidate, dict):
+            return entity_type, candidate
+    return None
+
+
+def _select_structured_clarification_candidate(selection: Any, payload: Any) -> tuple[str, Json] | None:
+    if not isinstance(selection, dict):
+        raise ValueError("clarificationSelection must be an object")
+    if not isinstance(payload, dict):
+        return None
+    entity_type = selection.get("entityType")
+    if entity_type not in {"brand", "project"}:
+        raise ValueError("clarificationSelection.entityType must be brand or project")
+    if "entityId" not in selection:
+        raise ValueError("clarificationSelection.entityId is required")
+    candidates = payload.get("brands" if entity_type == "brand" else "projects")
+    if not isinstance(candidates, list) or not candidates:
+        return None
+    wanted_id = str(selection.get("entityId"))
+    for candidate in candidates:
+        if isinstance(candidate, dict) and str(candidate.get("id")) == wanted_id:
+            return entity_type, candidate
+    return None
+
+
+def _stateless_clarification_question(selection: Any) -> str:
+    if not isinstance(selection, dict):
+        raise ValueError("clarificationSelection must be an object")
+    entity_type = selection.get("entityType")
+    if entity_type not in {"brand", "project"}:
+        raise ValueError("clarificationSelection.entityType must be brand or project")
+    if "entityId" not in selection:
+        raise ValueError("clarificationSelection.entityId is required")
+    base_question = _required_selection_string(selection, "baseQuestion")
+    entity_name = _required_selection_string(selection, "entityName")
+    entity_id = selection.get("entityId")
+    label = "品牌" if entity_type == "brand" else "项目"
+    return f"{base_question}，按{label}「{entity_name}」(id: {entity_id})查询"
+
+
+def _required_selection_string(selection: Json, key: str) -> str:
+    value = selection.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"clarificationSelection.{key} is required for stateless clarification")
+    return value.strip()
+
+
 def _tool_text(text: str) -> Json:
     return {"content": [{"type": "text", "text": text}]}
 
 
-def _tool_json(data: Any) -> Json:
+def _tool_final_answer(query_result: Any, *, base_question: str | None = None) -> Json:
+    payload = _query_result_payload(query_result, base_question=base_question)
+    payload.update(
+        {
+            "finalAnswerOnly": True,
+            "responseMode": "verbatim",
+        }
+    )
+    return {
+        "content": [{"type": "text", "text": str(getattr(query_result, "answer", ""))}],
+        "structuredContent": payload,
+    }
+
+
+def _tool_query_answer(query_result: Any, *, final_answer_only: bool, base_question: str | None = None) -> Json:
+    payload = _query_result_payload(query_result, base_question=base_question)
+    payload["finalAnswerOnly"] = final_answer_only
+    payload["responseMode"] = "verbatim"
     return {
+        "content": [{"type": "text", "text": str(getattr(query_result, "answer", ""))}],
+        "structuredContent": payload,
+    }
+
+
+def _query_result_payload(query_result: Any, *, include_sql: bool = False, base_question: str | None = None) -> Json:
+    payload: Json = {
+        "answer": str(getattr(query_result, "answer", "")),
+        "needsClarification": bool(getattr(query_result, "needs_clarification", False)),
+        "clarificationType": getattr(query_result, "clarification_type", None),
+        "clarificationPayload": getattr(query_result, "clarification_payload", None),
+    }
+    clarification_context = _clarification_context(payload["clarificationPayload"], base_question)
+    if clarification_context is not None:
+        payload["clarificationContext"] = clarification_context
+    if include_sql:
+        payload.update(
+            {
+                "generatedSql": getattr(query_result, "generated_sql", ""),
+                "normalizedSql": getattr(query_result, "normalized_sql", ""),
+                "repairedSql": getattr(query_result, "repaired_sql", None),
+                "validation": getattr(query_result, "validation", {}),
+            }
+        )
+    return _jsonable(payload)
+
+
+def _clarification_context(clarification_payload: Any, base_question: str | None) -> Json | None:
+    if not isinstance(clarification_payload, dict) or not base_question:
+        return None
+    brands = clarification_payload.get("brands")
+    projects = clarification_payload.get("projects")
+    if not brands and not projects:
+        return None
+    return {
+        "baseQuestion": base_question,
+        "brands": brands or [],
+        "projects": projects or [],
+        "selectionFields": {
+            "baseQuestion": "原始业务问题",
+            "entityType": "实体类型：brand=品牌，project=项目",
+            "entityId": "候选实体 ID",
+            "entityName": "候选实体名称",
+        },
+    }
+
+
+def _tool_json(data: Any, *, structured_content: Any | None = None) -> Json:
+    result = {
         "content": [
             {
                 "type": "text",
@@ -299,6 +648,9 @@ def _tool_json(data: Any) -> Json:
             }
         ]
     }
+    if structured_content is not None:
+        result["structuredContent"] = _jsonable(structured_content)
+    return result
 
 
 def _tool_error(message: str, *, code: str) -> Json:

package/src/octopus_skill/prompt_builder.py

@@ -1,46 +1,41 @@
 from __future__ import annotations
 
 import json
+import re
 from typing import Any
 
 from .schema_context_retriever import SchemaContext
+from .sql_generator import normalize_text_filters_to_like
 
 
 NL2SQL_SYSTEM_PROMPT = """你是丸子Agent（Octopus Agent）的海绵数据 SQL 生成器。
-你只能基于提供的 schema context 生成 MySQL SELECT 查询。
+你只能基于提供的 schemaContext 生成 MySQL SELECT 查询，所有表、字段、关联方式、状态枚举、默认过滤和业务口径都必须来自 schemaContext，不得自行猜测或记忆任何业务规则。
 返回 JSON 中的 sql 字段必须直接以 SELECT 开头，不能返回非 SQL 文本。
-只生成业务 SQL，不要生成权限占位符或权限条件。
-不得使用 :scope.project_ids、:scope.brand_ids 或任何 :scope.* placeholder（占位符）。
+只生成业务 SQL，不要生成权限占位符或权限条件；不得使用 :scope.project_ids、:scope.brand_ids 或任何 :scope.* placeholder（占位符）。
 如果用户没有明确要求返回条数，LIMIT 必须使用 defaultLimit。
-如果用户要求所有数据、全部数据、全量数据、完整数据，或要求导出/生成 Excel/xlsx/表格文件，LIMIT 必须使用 maxLimit，不要使用 defaultLimit。
+如果用户要求所有数据、全部数据、全量数据、完整数据，或要求导出/生成 Excel/xlsx/表格文件，LIMIT 必须使用 maxLimit。
 不得查询 auth 库、密码、令牌、密钥、凭证字段。
-不得输出敏感字段，包括手机号、电话、联系方式、身份证、密码、token、secret、credential、private_key 等。
-如果用户要求敏感字段，必须从 SELECT 中排除这些字段；还有其他非敏感字段时继续生成去敏后的 SQL。
+不得输出敏感字段，包括手机号、电话、联系方式、身份证、密码、token、secret、credential、private_key 等；如果用户要求敏感字段，必须从 SELECT 中排除，仍有其他非敏感字段时继续生成去敏后的 SQL。
 不得生成 INSERT、UPDATE、DELETE、DDL、非 SELECT SQL 或多语句 SQL。
-SELECT 中每个输出字段都必须使用 AS 中文含义，例如 b.name AS 品牌名称。
-禁止使用英文别名，例如 brand_name、project_name。
-用户点名要求输出的字段，必须优先使用 schema context 中含义匹配的真实字段或真实关联表生成。
-不得为了凑齐字段写 NULL AS 字段名、CAST(NULL AS ...) AS 字段名 等空占位表达式。
-只有 schema context 中完全没有相关真实字段或关联表时，才允许不返回该字段；不要用空占位字段替代。
-用户明确给出品牌、项目、岗位、职位、门店等实体名称时，必须在对应名称字段上使用 LIKE 过滤，不要先查询全量或默认 LIMIT 列表再比对。
-名称类字段和状态文本类字段的筛选条件必须使用 LIKE '%值%'，例如 name、job_name、status_text、status_name。
-数字 ID、数字状态枚举、删除标记、时间范围和 JOIN ON 表关联条件不要改成 LIKE；例如 status = 1、is_delete = 0、a.id = b.id、create_at >= '2026-05-01' 保持原比较符。
-只有“名称包含/名称为/是/等于/招聘xx岗位/在招xx职位”等明确关系才能判定为岗位或职位名称；不要仅因逗号、空格、冒号相邻就推断岗位名称。
-业务查询必须一次生成完整 SQL；不要先查 brand、sponge_project、city、store、job_basic_info 等单表列表来找 ID，也不要要求外部先提供 ID。
-业务查询中需要按品牌、项目、城市、门店、岗位名称过滤时，必须 JOIN 对应表并直接使用 name 或 job_name LIKE。
-涉及业务指标或业务口径时，必须优先使用 schemaContext.metrics 中的 definition、aggregation 和 filters。
-如果 schemaContext.metrics 没有给出对应业务口径，不得自行推断状态枚举、有效性过滤或跨轮次分割规则。
-所有业务字段、状态枚举、状态映射、表关联方式必须来自 schemaContext.tables、schemaContext.joins、schemaContext.glossary、schemaContext.metrics 或 schemaContext.examples。
-不得自行猜测状态值；例如“面试成功”“进行中”“已上岗”等状态必须使用 schemaContext 中给出的字段和枚举。
-所有 JOIN 必须优先使用 schemaContext.joins；如果相关 JOIN 只出现在 schemaContext.metrics.filters 或 schemaContext.examples 中，也必须严格照用。
-如果 schemaContext 没有明确给出表、字段、JOIN 或指标口径，不要猜测；返回 {"sql":"","tables":[],"placeholders":[],"usedColumns":[],"usedJoins":[],"metricRefs":[]}。
-报名/工单/候选人状态/姓名/岗位/项目明细查询，必须优先使用 schemaContext 中的报名工单表和示例，不得退化为只查询 brand 品牌列表。
-报名工单与岗位的关联方式必须来自 schemaContext；如果 schemaContext 指明 job_id 关联 job_basic_info.job_id，不得改用 job_basic_info.id。
-地点条件必须先按业务字典判断层级：province.name 省份优先，其次 city.name 城市，再其次 region.name 区域。
-用户提到南京、上海、江苏等地点时，不要先猜测为道路、商圈、门店或地址关键词；只有省/城市/区域都无法匹配时，才按地址关键词模糊查询。
-岗位或门店地点查询优先使用 job_address.city_id、job_address.region_id、store.city_id、store.region_id 等结构化字段。
-用户问题包含时间范围时，SQL 的 WHERE 条件必须直接包含对应时间字段过滤，不得先查询全量数据再补充时间范围。
-时间字段按语义选择：创建/新建/新增使用 create_at，发布/上架使用 publish_at，下架使用 off_at，更新/修改使用 update_at。
+SELECT 中每个输出字段都必须使用 AS 中文含义，例如 b.name AS 品牌名称；禁止使用英文别名，例如 brand_name、project_name。
+不得为了凑齐字段写 NULL AS 字段名、CAST(NULL AS ...) AS 字段名 等空占位表达式；schemaContext 中完全没有相关真实字段或关联表时，才允许不返回该字段。
+名称类字段筛选必须使用 LIKE '%值%'（例如 name、job_name、status_text、status_name），禁止对名称类字段使用 = '值' 精确匹配；即使 schemaContext.examples 中出现名称类字段 = '值'，也必须改写为 LIKE '%值%'。
+数字 ID、数字状态枚举、删除标记、时间范围和 JOIN ON 表关联条件使用等值或比较符，不要改成 LIKE。
+所有表关联必须使用 schemaContext.joins 给出的关联键；如果关联只出现在 schemaContext.metrics.filters 或 schemaContext.examples 中，也必须严格照用，不要自行假设外键。
+所有默认过滤（软删除、有效性等）必须使用 schemaContext.tableDefaults 给出的条件。
+所有业务指标口径必须使用 schemaContext.metrics 的 definition、aggregation、filters；所有状态枚举、状态映射必须使用 schemaContext.enums，不得自行推断状态值。
+岗位总数、岗位数、职位总数、职位数只表示岗位记录数量，不等于在招岗位数；用户只说“总数”“查询总数”“统计总数”且未提在招/已发布/已上架时，按全部岗位记录计数，不要默认加 status=在招 过滤，SELECT 别名必须使用用户原词（例如 AS 总数），禁止写成 AS 在招岗位数。
+除非用户明确说在招、已发布、已上架等状态词，或 schemaContext.metrics 的指标定义明确要求状态过滤，否则不要默认加岗位状态过滤，也不要把输出别名写成在招/已发布。
+用户明确说在招、已发布、已上架、未发布、已下架等状态词时，必须从 schemaContext.enums 找到对应字段和值并用于 WHERE；例如枚举 label 命中“已发布/已上架/在招”时，只能使用该 label 对应的枚举值，不得把未发布、已下架等其他状态一起放入 IN。
+只有用户明确要求多个状态（例如“岗位状态包括已发布、已下架、未发布”）时，才允许使用这些状态对应枚举值组成 IN。
+字段语义、时间字段选择、地点层级、实体口径等都必须遵循 schemaContext.glossary 的说明。
+如果 schemaContext 没有明确给出所需的表、字段、JOIN、枚举或指标口径，不要猜测；返回 {"sql":"","tables":[],"placeholders":[],"usedColumns":[],"usedJoins":[],"metricRefs":[]}。
+业务查询必须一次生成完整 SQL，不要先查单表列表找 ID，也不要要求外部先提供 ID；需要按名称过滤时直接 JOIN 对应表并使用 name/job_name LIKE。
+如果输入提供了 resolvedEntities，这些是已校正的真实实体（口语、简称、别名、错字已归一到标准名）；必须使用 resolvedEntities 中的标准名称或 id 作为过滤条件，并通过 schemaContext.joins / schemaContext.examples 关联到对应业务表，不要再用用户原始口语词做 LIKE，也不要自行猜测实体所属的表或层级。
+resolvedEntities 给出的 table/column/id 表示该实体在主数据表中的位置；若主数据表与业务事实表之间存在关联表，必须按 schemaContext.joins 给出的关联路径连接。
+resolvedEntities.location 可能同时给出 province、city、region 多个层级；必须按其中最细粒度过滤（有 region 用 region，没有才退到 city，再退到 province）。
+resolvedEntities 中给出的每一个实体都必须在 WHERE 中体现为过滤条件，一个都不能省略。
+用户问题包含时间范围时，SQL 的 WHERE 必须直接包含对应时间字段过滤；时间字段按 schemaContext.glossary 的说明选择。
 必须包含 LIMIT，且 LIMIT 不超过 500。
 不要使用 WITH；低版本 MySQL 不支持公共表表达式，请使用 JOIN 或派生表。
 只输出 JSON，不输出解释文本、拒绝文本或 Markdown。"""
@@ -52,6 +47,7 @@ def build_nl2sql_prompt(
     schema_context: SchemaContext,
     default_limit: int,
     max_limit: int,
+    resolved_entities: dict[str, Any] | None = None,
 ) -> str:
     payload = {
         "question": question,
@@ -59,6 +55,8 @@ def build_nl2sql_prompt(
         "schemaContext": {
             "tables": schema_context.tables,
             "joins": schema_context.joins,
+            "tableDefaults": schema_context.table_defaults,
+            "enums": schema_context.enums,
             "glossary": schema_context.glossary,
             "metrics": schema_context.metrics,
             "examples": _business_examples(schema_context.examples),
@@ -72,6 +70,8 @@ def build_nl2sql_prompt(
             "metricRefs": ["schemaContext.metrics.name"],
         },
     }
+    if resolved_entities:
+        payload["resolvedEntities"] = resolved_entities
     return json.dumps(payload, ensure_ascii=False, indent=2)
 
 
@@ -83,6 +83,7 @@ def build_sql_repair_prompt(
     schema_context: SchemaContext,
     default_limit: int,
     max_limit: int,
+    resolved_entities: dict[str, Any] | None = None,
 ) -> str:
     payload = {
         "task": "repair_sql",
@@ -93,6 +94,8 @@ def build_sql_repair_prompt(
         "schemaContext": {
             "tables": schema_context.tables,
             "joins": schema_context.joins,
+            "tableDefaults": schema_context.table_defaults,
+            "enums": schema_context.enums,
             "glossary": schema_context.glossary,
             "metrics": schema_context.metrics,
             "examples": _business_examples(schema_context.examples),
@@ -106,8 +109,48 @@ def build_sql_repair_prompt(
             "metricRefs": ["schemaContext.metrics.name"],
         },
     }
+    if resolved_entities:
+        payload["resolvedEntities"] = resolved_entities
     return json.dumps(payload, ensure_ascii=False, indent=2)
 
 
 def _business_examples(examples: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    return [example for example in examples if ":scope." not in str(example.get("sql") or "")]
+    """Prepare examples for the LLM prompt.
+
+    The MCP examples carry data-scope predicates (``... IN (:scope.project_ids)``)
+    that the LLM must never emit. Rather than dropping every example that has
+    them (which removed almost all join guidance), strip the scope predicates
+    and keep the rest of the pattern. If an example still contains ``:scope.``
+    after stripping, drop it to stay safe.
+    """
+    result: list[dict[str, Any]] = []
+    for example in examples:
+        sql = str(example.get("sql") or "")
+        original_sql = sql
+        if ":scope." in sql:
+            sql = _strip_scope_predicates(sql)
+            if ":scope." in sql:
+                continue
+        sql = _normalize_example_text_filters(sql)
+        if sql != original_sql:
+            example = {**example, "sql": sql}
+        result.append(example)
+    return result
+
+
+def _strip_scope_predicates(sql: str) -> str:
+    # Remove "AND <column> IN (:scope.<name>)" predicates, then tidy a WHERE
+    # clause that may be left starting with a stray AND.
+    cleaned = re.sub(
+        r"\s+AND\s+[A-Za-z_][\w.]*\s+IN\s*\(\s*:scope\.\w+\s*\)",
+        "",
+        sql,
+        flags=re.IGNORECASE,
+    )
+    cleaned = re.sub(r"\bWHERE\s+AND\s+", "WHERE ", cleaned, flags=re.IGNORECASE)
+    return cleaned
+
+
+def _normalize_example_text_filters(sql: str) -> str:
+    """Align business examples with SQL guardrails before prompting."""
+    return normalize_text_filters_to_like(sql)