@roll-agent/octopus-agent 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/octopus-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "丸子Agent（Octopus Agent）",
   "license": "UNLICENSED",
   "keywords": [

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "octopus-skill"
-version = "0.1.0"
+version = "0.1.1"
 description = "丸子Agent（Octopus Agent）"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/octopus_skill/_version.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

package/src/octopus_skill/agent.py

@@ -25,6 +25,7 @@ from .sql_generator import (
     build_sql_rule_validation_error,
     enforce_sql_rules,
     finalize_generated_sql,
+    format_sql_quality_issue,
     _is_business_query,
     is_low_quality_sql_for_question,
     low_quality_sql_issue_for_question,
@@ -365,8 +366,14 @@ class SpongeAgent:
         if schema is not None:
             candidate_sql = apply_time_range_filters_from_question(candidate_sql, time_range_question, schema)
         if not sql_satisfies_time_range(candidate_sql, time_range_question, schema, query_plan=query_plan):
+            quality_message = _query_quality_failure_message(
+                "用户问题包含时间范围，SQL 必须在 WHERE 条件中直接包含对应时间字段过滤。",
+                missing_items=["用户要求的时间范围过滤"],
+                current_problem="当前 SQL 没有覆盖用户问题中的时间范围，执行后可能返回全量或错误时间段的数据。",
+                repair_hint="按 schema concepts/metrics 或查询计划中的时间字段补充 WHERE 时间范围条件。",
+            )
             if sampler is None or schema_context is None or generator is None:
-                reason = "SQL 缺少用户问题要求的时间范围过滤，且当前没有 sampler 可修复。"
+                reason = f"{quality_message}；当前没有 sampler 可修复。"
                 steps.error(8, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
@@ -375,8 +382,11 @@ class SpongeAgent:
                 sql=candidate_sql,
                 validation_error={
                     "code": "MISSING_TIME_RANGE_FILTER",
-                    "message": "用户问题包含时间范围，SQL 必须在 WHERE 条件中直接包含对应时间字段过滤。",
+                    "message": quality_message,
                     "originalSql": candidate_sql,
+                    "missingItems": ["用户要求的时间范围过滤"],
+                    "currentProblem": "当前 SQL 没有覆盖用户问题中的时间范围。",
+                    "repairHint": "按 schema concepts/metrics 或查询计划中的时间字段补充 WHERE 时间范围条件。",
                 },
                 schema_context=sql_schema_context,
                 audit_logger=self.audit_logger,
@@ -387,8 +397,8 @@ class SpongeAgent:
                 schema=schema,
                 check=lambda candidate: _require_time_range(candidate, time_range_question, schema, query_plan),
                 steps=steps,
-                running_detail="SQL 缺少时间范围过滤，尝试修复",
-                failure_detail="SQL 缺少时间范围过滤，修复失败",
+                running_detail=f"SQL 口径校验失败，尝试修复：{quality_message}",
+                failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
                 steps.error(9, fail_reason)
@@ -398,8 +408,14 @@ class SpongeAgent:
             steps.done(9, "已补充时间范围过滤。")
         if query_plan and not sql_satisfies_query_plan_filters(candidate_sql, query_plan):
             missing_filters = sql_missing_query_plan_filters(candidate_sql, query_plan)
+            quality_message = _query_quality_failure_message(
+                f"SQL 缺少查询计划中的筛选条件：{'; '.join(missing_filters)}。",
+                missing_items=missing_filters,
+                current_problem="当前 SQL 没有覆盖用户已确认的关键筛选，执行后可能返回范围过宽或不相关的数据。",
+                repair_hint="必须 JOIN 相关表，并把缺失的 table.column 过滤写入 WHERE；同组 OR 条件需要用括号包裹。",
+            )
             if sampler is None or schema_context is None or generator is None:
-                reason = f"SQL 缺少查询计划中的筛选条件：{'; '.join(missing_filters)}"
+                reason = quality_message
                 steps.error(8, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
@@ -408,12 +424,12 @@ class SpongeAgent:
                 sql=candidate_sql,
                 validation_error={
                     "code": "MISSING_QUERY_PLAN_FILTER",
-                    "message": (
-                        f"SQL 缺少查询计划中的筛选条件：{'; '.join(missing_filters)}。"
-                        "必须 JOIN 相关表并在 WHERE 中包含全部 table.column 过滤。"
-                    ),
+                    "message": quality_message,
                     "originalSql": candidate_sql,
                     "missingFilters": missing_filters,
+                    "missingItems": missing_filters,
+                    "currentProblem": "当前 SQL 没有覆盖用户已确认的关键筛选。",
+                    "repairHint": "必须 JOIN 相关表，并把缺失的 table.column 过滤写入 WHERE。",
                 },
                 schema_context=sql_schema_context,
                 audit_logger=self.audit_logger,
@@ -424,8 +440,8 @@ class SpongeAgent:
                 schema=schema,
                 check=lambda candidate: sql_satisfies_query_plan_filters(candidate, query_plan),
                 steps=steps,
-                running_detail=f"SQL 缺少查询计划筛选条件，尝试修复：{'; '.join(missing_filters)}",
-                failure_detail="SQL 缺少查询计划筛选条件，修复失败",
+                running_detail=f"SQL 口径校验失败，尝试修复：{quality_message}",
+                failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
                 steps.error(9, fail_reason)
@@ -435,8 +451,14 @@ class SpongeAgent:
             steps.done(9, "已补充查询计划筛选条件。")
         if query_plan and not sql_satisfies_query_plan_select_fields(candidate_sql, query_plan):
             missing_select_fields = sql_missing_query_plan_select_fields(candidate_sql, query_plan)
+            quality_message = _query_quality_failure_message(
+                f"SQL 缺少查询计划中的展示字段：{'; '.join(missing_select_fields)}。",
+                missing_items=missing_select_fields,
+                current_problem="当前 SQL 没有展示用户已确认的必要字段，结果无法解释或无法区分命中的实体。",
+                repair_hint="把缺失字段加入 SELECT，并使用中文别名。",
+            )
             if sampler is None or schema_context is None or generator is None:
-                reason = f"SQL 缺少查询计划中的展示字段：{'; '.join(missing_select_fields)}"
+                reason = quality_message
                 steps.error(8, reason)
                 return _attach_execution_steps(_query_only_result(reason), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
@@ -445,12 +467,12 @@ class SpongeAgent:
                 sql=candidate_sql,
                 validation_error={
                     "code": "MISSING_QUERY_PLAN_SELECT_FIELD",
-                    "message": (
-                        f"SQL 缺少查询计划中的展示字段：{'; '.join(missing_select_fields)}。"
-                        "同一别称命中多个实体类型时，必须在 SELECT 中展示各实体名称字段，方便用户自行缩小范围。"
-                    ),
+                    "message": quality_message,
                     "originalSql": candidate_sql,
                     "missingSelectFields": missing_select_fields,
+                    "missingItems": missing_select_fields,
+                    "currentProblem": "当前 SQL 没有展示用户已确认的必要字段。",
+                    "repairHint": "把缺失字段加入 SELECT，并使用中文别名。",
                 },
                 schema_context=sql_schema_context,
                 audit_logger=self.audit_logger,
@@ -461,8 +483,8 @@ class SpongeAgent:
                 schema=schema,
                 check=lambda candidate: sql_satisfies_query_plan_select_fields(candidate, query_plan),
                 steps=steps,
-                running_detail=f"SQL 缺少查询计划展示字段，尝试修复：{'; '.join(missing_select_fields)}",
-                failure_detail="SQL 缺少查询计划展示字段，修复失败",
+                running_detail=f"SQL 口径校验失败，尝试修复：{quality_message}",
+                failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
                 steps.error(9, fail_reason)
@@ -472,17 +494,21 @@ class SpongeAgent:
             steps.done(9, "已补充查询计划展示字段。")
         low_quality_issue = low_quality_sql_issue_for_question(sql_question, candidate_sql, schema=schema)
         if low_quality_issue is not None:
+            quality_message = format_sql_quality_issue(low_quality_issue)
             if sampler is None or schema_context is None or generator is None:
-                steps.error(8, low_quality_issue.message)
-                return _attach_execution_steps(_low_quality_sql_result(low_quality_issue.message, candidate_sql), steps)
+                steps.error(8, quality_message)
+                return _attach_execution_steps(_low_quality_sql_result(quality_message, candidate_sql), steps)
             repaired_sql, fail_reason = _repair_sql_with_llm_retries(
                 generator=generator,
                 question=sql_question,
                 sql=candidate_sql,
                 validation_error={
                     "code": low_quality_issue.code,
-                    "message": low_quality_issue.message,
+                    "message": quality_message,
                     "originalSql": candidate_sql,
+                    "missingItems": list(low_quality_issue.missing_items),
+                    "currentProblem": low_quality_issue.current_problem,
+                    "repairHint": low_quality_issue.repair_hint,
                 },
                 schema_context=sql_schema_context,
                 audit_logger=self.audit_logger,
@@ -493,8 +519,8 @@ class SpongeAgent:
                 schema=schema,
                 check=lambda candidate: _require_low_quality_pass(candidate, sql_question, schema),
                 steps=steps,
-                running_detail=f"SQL 质量检查失败，尝试修复：{low_quality_issue.message}",
-                failure_detail=f"SQL 质量检查失败，修复失败：{low_quality_issue.message}",
+                running_detail=f"SQL 口径校验失败，尝试修复：{quality_message}",
+                failure_detail=f"SQL 口径校验失败，修复失败：{quality_message}",
             )
             if repaired_sql is None:
                 steps.error(9, fail_reason)
@@ -634,6 +660,28 @@ class SpongeAgent:
                 return _attach_execution_steps(_query_only_result(schema_fail), steps)
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
         candidate_sql = _remove_noise_name_like_filters_from_sql(candidate_sql, analysis=analysis)
+        if candidate_sql != prior_sql:
+            generated = GeneratedSql(sql="", tables=[], placeholders=[])
+            repaired_sql = candidate_sql
+        prior_sql = candidate_sql
+        candidate_sql, expert_fail = _review_sql_with_llm_expert_if_needed(
+            generator=generator,
+            question=sql_question,
+            sql=candidate_sql,
+            schema_context=sql_schema_context,
+            schema=schema,
+            query_plan=query_plan,
+            time_range_question=time_range_question,
+            default_limit=self.config.sql.default_limit,
+            max_limit=self.config.sql.max_limit,
+            max_repair_attempts=self.config.sql.max_repair_attempts,
+            steps=steps,
+            audit_logger=self.audit_logger,
+            session_id=context.session_id,
+        )
+        if expert_fail:
+            steps.error(10, expert_fail)
+            return _attach_execution_steps(_query_only_result(expert_fail), steps)
         if candidate_sql != prior_sql:
             generated = GeneratedSql(sql="", tables=[], placeholders=[])
             repaired_sql = candidate_sql
@@ -790,7 +838,66 @@ class SpongeAgent:
             result = self._execute_sql(context, user_question, normalized_sql)
         except Exception as exc:
             unknown_col = _parse_execute_unknown_column(str(exc))
-            if (
+            invalid_group_function = _is_execute_invalid_group_function(str(exc))
+            if invalid_group_function and sampler is not None and generator is not None and schema_context is not None:
+                exec_error = {
+                    "code": "MYSQL_INVALID_GROUP_FUNCTION_USE",
+                    "message": (
+                        "MySQL 执行失败：Invalid use of group function。"
+                        "通常是聚合函数写在 WHERE 或 JOIN ON 中，或聚合筛选没有放到 HAVING/子查询外层。"
+                    ),
+                    "originalSql": normalized_sql,
+                    "repairHint": "把聚合条件移动到 HAVING，或先用子查询聚合后在外层 WHERE 过滤；不要改变业务口径。",
+                }
+                repaired_exec_sql, fail_reason = _repair_sql_with_llm_retries(
+                    generator=generator,
+                    question=sql_question,
+                    sql=normalized_sql,
+                    validation_error=exec_error,
+                    schema_context=sql_schema_context,
+                    audit_logger=self.audit_logger,
+                    session_id=context.session_id,
+                    max_attempts=self.config.sql.max_repair_attempts,
+                    default_limit=self.config.sql.default_limit,
+                    max_limit=self.config.sql.max_limit,
+                    schema=schema,
+                    check=lambda candidate: _require_sql_expert_local_pass(candidate, schema, self.config.sql.max_limit),
+                    steps=steps,
+                    running_detail="execute_sql 报聚合函数用法错误，尝试修复",
+                    failure_detail="execute_sql 聚合函数用法错误修复失败",
+                )
+                if repaired_exec_sql is None:
+                    reason = fail_reason or f"{type(exc).__name__}: {exc}"
+                    steps.error(11, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+                if query_plan:
+                    repaired_exec_sql = apply_time_range_filters_from_plan(repaired_exec_sql, query_plan)
+                if schema is not None:
+                    repaired_exec_sql = apply_time_range_filters_from_question(repaired_exec_sql, time_range_question, schema)
+                try:
+                    _require_sql_expert_local_pass(repaired_exec_sql, schema, self.config.sql.max_limit)
+                    revalidated = self._validate_sql(context, user_question, repaired_exec_sql)
+                except Exception as validate_exc:
+                    reason = f"{type(validate_exc).__name__}: {validate_exc}"
+                    steps.error(10, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+                if revalidated is None:
+                    reason = (
+                        f"execute 聚合函数用法修复后 validate_sql 失败："
+                        f"{_validation_error_message(self._last_validation_result)}"
+                    )
+                    steps.error(10, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+                try:
+                    result = self._execute_sql(context, user_question, revalidated)
+                    normalized_sql = revalidated
+                    repaired_sql = repaired_exec_sql
+                    steps.done(11, f"execute_sql 完成，rowCount={result.get('rowCount')}")
+                except Exception as retry_exc:
+                    reason = f"{type(retry_exc).__name__}: {retry_exc}"
+                    steps.error(11, reason)
+                    return _attach_execution_steps(_query_only_result(reason), steps)
+            elif (
                 unknown_col
                 and sampler is not None
                 and generator is not None
@@ -1303,7 +1410,7 @@ def _build_query_plan(
         analysis=analysis,
     )
     selected_concepts = match_concepts_for_question(getattr(schema_context, "concepts", []) or [], question)
-    filters = _query_plan_filters(
+    sql_filters = _query_plan_sql_filters(
         question,
         schema_context,
         searched_entities=searched_entities,
@@ -1313,6 +1420,11 @@ def _build_query_plan(
         selected_concepts=selected_concepts,
         analysis=analysis,
     )
+    filters = _query_plan_semantic_filters(
+        question,
+        sql_filters=sql_filters,
+        analysis=analysis,
+    )
     entities = _query_plan_entities(
         question,
         schema_context,
@@ -1340,6 +1452,7 @@ def _build_query_plan(
         "tables": tables,
         "fields": fields,
         "filters": filters,
+        "_sqlFilters": sql_filters,
         "entities": entities,
         "matchedConcepts": [
             {
@@ -1390,7 +1503,7 @@ def _ensure_query_plan_bridge_tables(plan: dict[str, Any]) -> None:
     job_tables = {"job", "job_basic_info", "job_address", "job_store", "job_hiring_requirement"}
     has_store = "store" in names
     if not has_store:
-        for flt in plan.get("filters") or []:
+        for flt in _plan_sql_filters(plan):
             if isinstance(flt, dict) and str(flt.get("field") or "").startswith("store."):
                 has_store = True
                 break
@@ -1420,7 +1533,7 @@ def _ensure_query_plan_entity_display_fields(plan: dict[str, Any]) -> None:
         for item in fields
         if isinstance(item, dict)
     }
-    for flt in plan.get("filters") or []:
+    for flt in _plan_sql_filters(plan):
         if not isinstance(flt, dict):
             continue
         if str(flt.get("source") or "") != "search_entities":
@@ -1460,6 +1573,14 @@ def _ensure_query_plan_entity_display_fields(plan: dict[str, Any]) -> None:
         existing.add(key)
 
 
+def _plan_sql_filters(plan: dict[str, Any]) -> list[Any]:
+    filters = plan.get("_sqlFilters")
+    if isinstance(filters, list):
+        return filters
+    filters = plan.get("filters")
+    return filters if isinstance(filters, list) else []
+
+
 def _query_plan_tables(tables: list[dict[str, Any]]) -> list[dict[str, str]]:
     result: list[dict[str, str]] = []
     for table in tables[:10]:
@@ -2653,6 +2774,172 @@ def _query_plan_filters(
     time_range_question: str | None = None,
     selected_concepts: list[dict[str, Any]] | None = None,
     analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    sql_filters = _query_plan_sql_filters(
+        question,
+        schema_context,
+        searched_entities=searched_entities,
+        question_entities=question_entities,
+        schema=schema,
+        time_range_question=time_range_question,
+        selected_concepts=selected_concepts,
+        analysis=analysis,
+    )
+    return _query_plan_semantic_filters(
+        question,
+        sql_filters=sql_filters,
+        analysis=analysis,
+    )
+
+
+def _query_plan_semantic_filters(
+    question: str,
+    *,
+    sql_filters: list[dict[str, str]],
+    analysis: QuestionAnalysis | None = None,
+) -> list[dict[str, str]]:
+    filters: list[dict[str, str]] = []
+
+    def append_filter(item: dict[str, str]) -> None:
+        field = str(item.get("field") or "").strip()
+        value = str(item.get("value") or "").strip()
+        if not field or not value:
+            return
+        operator = str(item.get("operator") or "=").strip() or "="
+        normalized = {**item, "field": field, "operator": operator, "value": value}
+        key = (
+            field,
+            operator.upper(),
+            value,
+            str(normalized.get("logicalGroup") or ""),
+            str(normalized.get("logicalOperator") or ""),
+        )
+        if any(
+            (
+                existing.get("field"),
+                str(existing.get("operator") or "").upper(),
+                existing.get("value"),
+                str(existing.get("logicalGroup") or ""),
+                str(existing.get("logicalOperator") or ""),
+            )
+            == key
+            for existing in filters
+        ):
+            return
+        filters.append(normalized)
+
+    if analysis is not None:
+        for item in analysis.filters:
+            if not isinstance(item, dict):
+                continue
+            append_filter(
+                {
+                    "field": str(item.get("field") or "筛选条件"),
+                    "operator": str(item.get("operator") or "="),
+                    "value": str(item.get("value") or ""),
+                    "source": "llm.semanticFilter",
+                }
+            )
+        time_filter = _semantic_time_filter_from_analysis(analysis)
+        if time_filter is not None:
+            append_filter(time_filter)
+
+    if not any(str(item.get("source") or "") == "question.timeRange" for item in filters):
+        time_filter = _semantic_time_filter_from_sql_filters(sql_filters)
+        if time_filter is not None:
+            append_filter(time_filter)
+
+    for item in sql_filters:
+        semantic = _semantic_filter_from_sql_filter(item)
+        if semantic is not None:
+            append_filter(semantic)
+    return filters
+
+
+def _semantic_time_filter_from_analysis(analysis: QuestionAnalysis) -> dict[str, str] | None:
+    time_range = analysis.time_range
+    if not isinstance(time_range, dict):
+        return None
+    value = str(time_range.get("originalText") or time_range.get("value") or "").strip()
+    if not value:
+        start = str(time_range.get("start") or "").strip()
+        end = str(time_range.get("endExclusive") or "").strip()
+        if start and end:
+            value = f"{start} 至 {end}"
+    if not value:
+        return None
+    return {
+        "field": "时间范围",
+        "operator": "=",
+        "value": value,
+        "source": "question.timeRange",
+    }
+
+
+def _semantic_time_filter_from_sql_filters(filters: list[dict[str, str]]) -> dict[str, str] | None:
+    start = ""
+    end = ""
+    for item in filters:
+        if str(item.get("source") or "") != "question.timeRange":
+            continue
+        operator = str(item.get("operator") or "")
+        value = str(item.get("value") or "").strip()
+        if operator == ">=":
+            start = value
+        elif operator == "<":
+            end = value
+    if not start and not end:
+        return None
+    value = f"{start} 至 {end}" if start and end else start or end
+    return {
+        "field": "时间范围",
+        "operator": "BETWEEN" if start and end else "=",
+        "value": value,
+        "source": "question.timeRange",
+    }
+
+
+_TECHNICAL_QUERY_PLAN_FILTER_SOURCES = frozenset({"schema.concepts", "structure.defaultFilters"})
+
+
+def _semantic_filter_from_sql_filter(item: dict[str, str]) -> dict[str, str] | None:
+    source = str(item.get("source") or "")
+    operator = str(item.get("operator") or "").upper()
+    if source in _TECHNICAL_QUERY_PLAN_FILTER_SOURCES or operator == "DEFAULT":
+        return None
+    if source in {"question.timeRange", "question_analysis.timeRange"}:
+        return None
+    field = str(item.get("field") or "").strip()
+    value = str(item.get("value") or "").strip()
+    if not field or not value:
+        return None
+    label = _query_plan_filter_display_label(field, item)
+    display_value = _query_plan_filter_display_value(value, item)
+    if not label or not display_value:
+        return None
+    display_operator = "=" if operator in {"", "LIKE"} else str(item.get("operator") or "=")
+    semantic = {
+        "field": label,
+        "operator": display_operator,
+        "value": display_value,
+        "source": source or "queryPlan.sqlFilter",
+    }
+    for key in ("description", "logicalGroup", "logicalOperator"):
+        if key in item:
+            semantic[key] = str(item[key])
+    return semantic
+
+
+def _query_plan_sql_filters(
+    question: str,
+    schema_context: Any,
+    *,
+    searched_entities: dict[str, Any] | None = None,
+    question_entities: list[dict[str, str]] | None = None,
+    schema: dict[str, Any] | None = None,
+    time_range_question: str | None = None,
+    selected_concepts: list[dict[str, Any]] | None = None,
+    analysis: QuestionAnalysis | None = None,
 ) -> list[dict[str, str]]:
     filters: list[dict[str, str]] = []
 
@@ -2787,7 +3074,12 @@ def _apply_query_plan_time_range_filters(
     analysis: QuestionAnalysis | None = None,
 ) -> list[dict[str, str]]:
     """Replace noisy date LIKE filters with explicit range filters defaulting to current year."""
-    time_filters = _analysis_time_range_plan_filters(analysis, selected_concepts=selected_concepts)
+    time_filters = _analysis_time_range_plan_filters(
+        analysis,
+        selected_concepts=selected_concepts,
+        question=question,
+        schema=schema,
+    )
     if not time_filters:
         time_filters = time_range_plan_filters(question, schema, concepts=selected_concepts)
     if not time_filters:
@@ -2812,6 +3104,8 @@ def _analysis_time_range_plan_filters(
     analysis: QuestionAnalysis | None,
     *,
     selected_concepts: list[dict[str, Any]] | None = None,
+    question: str | None = None,
+    schema: dict[str, Any] | None = None,
 ) -> list[dict[str, str]]:
     if analysis is None or not isinstance(analysis.time_range, dict):
         return []
@@ -2819,7 +3113,7 @@ def _analysis_time_range_plan_filters(
     end = str(analysis.time_range.get("endExclusive") or analysis.time_range.get("end") or "").strip()
     if not (_looks_like_iso_date(start) and _looks_like_iso_date(end)):
         return []
-    field = _time_range_field_from_concepts(selected_concepts)
+    field = _time_range_field_from_question_schema(question, schema) or _time_range_field_from_concepts(selected_concepts)
     if not field:
         return []
     original = str(analysis.time_range.get("originalText") or analysis.time_range.get("value") or "时间范围").strip()
@@ -2841,6 +3135,20 @@ def _analysis_time_range_plan_filters(
     ]
 
 
+def _time_range_field_from_question_schema(
+    question: str | None,
+    schema: dict[str, Any] | None,
+) -> str:
+    if not question or schema is None:
+        return ""
+    filters = time_range_plan_filters(question, schema, concepts=[])
+    for item in filters:
+        field = str(item.get("field") or "").strip()
+        if "." in field:
+            return field
+    return ""
+
+
 def _time_range_field_from_concepts(concepts: list[dict[str, Any]] | None) -> str:
     for concept in concepts or []:
         if not isinstance(concept, dict):
@@ -3533,8 +3841,11 @@ def _query_plan_summary_filters(query_plan: dict[str, Any]) -> list[str]:
     for item in filters:
         if not isinstance(item, dict):
             continue
-        field = str(item.get("field") or "")
+        source = str(item.get("source") or "")
         operator = str(item.get("operator") or "")
+        if source in _TECHNICAL_QUERY_PLAN_FILTER_SOURCES or operator.upper() == "DEFAULT":
+            continue
+        field = str(item.get("field") or "")
         value = str(item.get("value") or "")
         label = _query_plan_filter_display_label(field, item)
         display_value = _query_plan_filter_display_value(value, item)
@@ -3723,6 +4034,10 @@ def _parse_execute_unknown_column(error_text: str) -> str | None:
     return match.group(1).strip()
 
 
+def _is_execute_invalid_group_function(error_text: str) -> bool:
+    return bool(re.search(r"invalid use of group function|ER_INVALID_GROUP_FUNC_USE", error_text, re.IGNORECASE))
+
+
 def _repair_sql_for_local_schema_issues(
     *,
     candidate_sql: str,
@@ -3932,6 +4247,154 @@ def _repair_sql_with_llm_retries(
     return None, last_reason
 
 
+def _review_sql_with_llm_expert_if_needed(
+    *,
+    generator: SamplingSqlGenerator | None,
+    question: str,
+    sql: str,
+    schema_context: Any,
+    schema: dict[str, Any],
+    query_plan: dict[str, Any] | None,
+    time_range_question: str,
+    default_limit: int,
+    max_limit: int,
+    max_repair_attempts: int,
+    steps: _ExecutionSteps,
+    audit_logger: AuditLogger,
+    session_id: str | None,
+) -> tuple[str, str | None]:
+    if generator is None or schema_context is None or not _should_llm_sql_expert_review(sql, query_plan):
+        return sql, None
+    steps.running(8, "LLM SQL 专家复核高风险 SQL 写法。")
+    try:
+        review = generator.review_sql(
+            question=question,
+            sql=sql,
+            schema_context=schema_context,
+        )
+    except SqlGenerationError as exc:
+        audit_logger.log(
+            {
+                "sessionId": session_id,
+                "question": question,
+                "tool": "llm_sql_expert_review",
+                "success": False,
+                "error": str(exc),
+            }
+        )
+        return sql, None
+    audit_logger.log(
+        {
+            "sessionId": session_id,
+            "question": question,
+            "tool": "llm_sql_expert_review",
+            "success": review.executable,
+            "sqlHash": sql_hash(sql),
+            "issues": review.issues,
+            "repaired": bool(review.repaired_sql),
+        }
+    )
+    if review.executable and not review.repaired_sql:
+        steps.done(8, "LLM SQL 专家复核通过。")
+        return sql, None
+    validation_error = {
+        "code": "LLM_SQL_EXPERT_REVIEW_FAILED",
+        "message": _sql_expert_review_message(review.issues),
+        "originalSql": sql,
+        "issues": review.issues,
+        "repairHint": "只修复 SQL 写法问题，不改变业务口径；聚合筛选放 HAVING 或先子查询聚合后外层过滤。",
+    }
+    candidate = review.repaired_sql
+    if candidate:
+        candidate = _finalize_candidate_sql(
+            candidate,
+            question,
+            default_limit=default_limit,
+            max_limit=max_limit,
+            schema=schema,
+        )
+        if query_plan:
+            candidate = apply_time_range_filters_from_plan(candidate, query_plan)
+        candidate = apply_time_range_filters_from_question(candidate, time_range_question, schema)
+        try:
+            enforce_sql_rules(candidate, max_limit=max_limit)
+            _require_no_schema_issues(candidate, schema)
+            steps.done(9, "已根据 LLM SQL 专家复核修复 SQL 写法问题。")
+            steps.done(8, "LLM SQL 专家复核后 SQL 满足本地规则。")
+            return candidate, None
+        except SqlGenerationError as exc:
+            schema_issues = validate_sql_against_schema(candidate, schema)
+            if schema_issues:
+                validation_error = build_schema_validation_error(
+                    candidate,
+                    schema_issues,
+                    schema,
+                    max_attempts=max_repair_attempts,
+                )
+            else:
+                validation_error = build_sql_rule_validation_error(
+                    candidate,
+                    exc,
+                    max_limit=max_limit,
+                    max_attempts=max_repair_attempts,
+                )
+                validation_error["message"] = f"LLM SQL 专家修复后仍有 SQL 写法问题：{exc}"
+            sql = candidate
+    repaired_sql, fail_reason = _repair_sql_with_llm_retries(
+        generator=generator,
+        question=question,
+        sql=sql,
+        validation_error=validation_error,
+        schema_context=schema_context,
+        audit_logger=audit_logger,
+        session_id=session_id,
+        max_attempts=max_repair_attempts,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        schema=schema,
+        check=lambda candidate_sql: _require_sql_expert_local_pass(candidate_sql, schema, max_limit),
+        steps=steps,
+        running_detail=f"LLM SQL 专家发现写法问题，尝试修复：{validation_error['message']}",
+        failure_detail="LLM SQL 专家发现写法问题，修复失败",
+    )
+    if repaired_sql is None:
+        return sql, fail_reason
+    steps.done(8, "LLM SQL 专家复核后 SQL 满足本地规则。")
+    return repaired_sql, None
+
+
+def _require_sql_expert_local_pass(sql: str, schema: dict[str, Any], max_limit: int) -> None:
+    enforce_sql_rules(sql, max_limit=max_limit)
+    _require_no_schema_issues(sql, schema)
+
+
+def _should_llm_sql_expert_review(sql: str, query_plan: dict[str, Any] | None) -> bool:
+    normalized = sql.lower()
+    if re.search(r"\b(group\s+by|having|count|sum|avg|min|max|group_concat)\s*\b", normalized):
+        return True
+    if re.search(r"\(\s*select\b", normalized):
+        return True
+    if isinstance(query_plan, dict):
+        for concept in query_plan.get("matchedConcepts") or []:
+            if isinstance(concept, dict) and str(concept.get("name") or "") in {"filled_job_by_period"}:
+                return True
+    return False
+
+
+def _sql_expert_review_message(issues: list[dict[str, str]]) -> str:
+    if not issues:
+        return "LLM SQL 专家判断 SQL 可能存在写法问题，需修复后再执行。"
+    parts: list[str] = []
+    for issue in issues:
+        message = str(issue.get("message") or issue.get("code") or "").strip()
+        hint = str(issue.get("repairHint") or "").strip()
+        if message and hint:
+            parts.append(f"{message}；建议：{hint}")
+        elif message:
+            parts.append(message)
+    return "；".join(parts) or "LLM SQL 专家判断 SQL 可能存在写法问题，需修复后再执行。"
+
+
 def _query_only_result(reason: str | None = None) -> QueryResult:
     answer = reason.strip() if isinstance(reason, str) and reason.strip() else "查询未能完成，请稍后重试。"
     return QueryResult(
@@ -3991,6 +4454,25 @@ def _low_quality_sql_result(message: str, generated_sql: str) -> QueryResult:
     )
 
 
+def _query_quality_failure_message(
+    message: str,
+    *,
+    missing_items: list[str] | tuple[str, ...] | None = None,
+    current_problem: str = "",
+    repair_hint: str = "",
+) -> str:
+    parts = [f"当前 SQL 不满足查询口径：{message.strip()}"]
+    if missing_items:
+        missing_text = "；".join(str(item) for item in missing_items if str(item).strip())
+        if missing_text:
+            parts.append(f"缺失口径：{missing_text}")
+    if current_problem:
+        parts.append(f"当前 SQL 的问题：{current_problem}")
+    if repair_hint:
+        parts.append(f"建议修复方向：{repair_hint}")
+    return "；".join(parts)
+
+
 def _sensitive_query_only_result(terms: list[str], *, reason: str | None = None) -> QueryResult:
     notice = _sensitive_field_notice(terms)
     if isinstance(reason, str) and reason.strip():

package/src/octopus_skill/llm_sql_generator.py

@@ -5,7 +5,12 @@ import re
 from dataclasses import dataclass
 from typing import Any, Callable
 
-from .prompt_builder import NL2SQL_SYSTEM_PROMPT, build_nl2sql_prompt, build_sql_repair_prompt
+from .prompt_builder import (
+    NL2SQL_SYSTEM_PROMPT,
+    build_nl2sql_prompt,
+    build_sql_expert_review_prompt,
+    build_sql_repair_prompt,
+)
 from .schema_context_retriever import SchemaContext
 from .sql_generator import GeneratedSql, SqlGenerationError, contains_forbidden_dml_keyword
 
@@ -54,6 +59,30 @@ class SamplingSqlGenerator:
         )
         return _parse_generated_sql(self.sampler(NL2SQL_SYSTEM_PROMPT, prompt))
 
+    def review_sql(
+        self,
+        *,
+        question: str,
+        sql: str,
+        schema_context: SchemaContext,
+    ) -> "SqlExpertReview":
+        prompt = build_sql_expert_review_prompt(
+            question=question,
+            sql=sql,
+            schema_context=schema_context,
+            default_limit=self.default_limit,
+            max_limit=self.max_limit,
+            confirmed_query_plan=self.confirmed_query_plan,
+        )
+        return _parse_sql_expert_review(self.sampler(NL2SQL_SYSTEM_PROMPT, prompt))
+
+
+@dataclass(frozen=True)
+class SqlExpertReview:
+    executable: bool
+    issues: list[dict[str, str]]
+    repaired_sql: str | None = None
+
 
 def _parse_generated_sql(text: str) -> GeneratedSql:
     try:
@@ -101,6 +130,31 @@ def _parse_generated_sql(text: str) -> GeneratedSql:
     )
 
 
+def _parse_sql_expert_review(text: str) -> SqlExpertReview:
+    payload = _load_json_object(text)
+    executable = bool(payload.get("executable", False))
+    issues_payload = payload.get("issues")
+    issues: list[dict[str, str]] = []
+    if isinstance(issues_payload, list):
+        for item in issues_payload:
+            if not isinstance(item, dict):
+                continue
+            issues.append(
+                {
+                    "code": str(item.get("code") or ""),
+                    "message": str(item.get("message") or ""),
+                    "repairHint": str(item.get("repairHint") or ""),
+                }
+            )
+    repaired_sql = payload.get("repairedSql")
+    if isinstance(repaired_sql, str) and repaired_sql.strip():
+        repaired_sql = repaired_sql.strip()
+        _require_select_sql(repaired_sql)
+    else:
+        repaired_sql = None
+    return SqlExpertReview(executable=executable, issues=issues, repaired_sql=repaired_sql)
+
+
 def _load_json_object(text: str) -> dict[str, Any]:
     cleaned = text.strip()
     if cleaned.startswith("```"):

package/src/octopus_skill/octopus_run.py

@@ -469,7 +469,7 @@ def _query_result_payload(query_result: Any, *, include_sql: bool = False, base_
     }
     query_plan = getattr(query_result, "query_plan", None)
     if isinstance(query_plan, dict):
-        payload["queryPlan"] = query_plan
+        payload["queryPlan"] = _public_query_plan(query_plan)
     execution_steps = getattr(query_result, "execution_steps", None)
     if isinstance(execution_steps, list):
         payload["executionSteps"] = execution_steps
@@ -485,6 +485,14 @@ def _query_result_payload(query_result: Any, *, include_sql: bool = False, base_
     return _jsonable(payload)
 
 
+def _public_query_plan(query_plan: dict[str, Any]) -> Json:
+    return {
+        key: value
+        for key, value in query_plan.items()
+        if not str(key).startswith("_")
+    }
+
+
 def _user_visible_answer(query_result: Any, *, base_question: str | None = None) -> str:
     answer = str(getattr(query_result, "answer", ""))
     question = base_question or ""

package/src/octopus_skill/prompt_builder.py

@@ -17,7 +17,8 @@ INSTRUCTION_STAGE_PREFIX: dict[InstructionStage, str] = {
 }
 
 
-NL2SQL_SYSTEM_PROMPT = """你是丸子Agent（Octopus Agent）的海绵数据 SQL 生成器。
+NL2SQL_SYSTEM_PROMPT = """你是丸子Agent（Octopus Agent）的海绵数据 SQL 专家，一名专业 MySQL SQL 专家。
+你必须以 SQL 专家的标准生成 SQL：输出前逐句自检，确保 SQL 整体可以直接执行，没有任何 SQL 语法错误，也没有 SQL 写法问题（如括号/引号不闭合、SELECT 与 GROUP BY 不一致、聚合函数误用、JOIN 缺少等值键、别名冲突、字段/表拼写错误等）。
 业务规则的唯一来源是 payload 中的 mandatoryAgentInstructions 与 schemaContext.policy；必须逐条遵守，不得使用训练记忆中的业务口径替代 schema 要求。
 生成 SQL 前必须严格按 schemaContext.readOrder 顺序阅读 schemaContext 各段内容，再组合 SELECT、JOIN、WHERE、LIMIT。
 只输出 JSON，结构见 outputSchema。返回 JSON 中的 sql 字段必须直接以 SELECT 开头；不要为了状态枚举单独返回 clarification。用户明确提出状态筛选时把状态条件写入 WHERE；用户未提出状态筛选或 schemaContext 缺少枚举时不要追问，首次查询保持宽泛，并把相关状态字段及中文含义加入 SELECT 结果。"""
@@ -76,6 +77,46 @@ def build_sql_repair_prompt(
     )
 
 
+def build_sql_expert_review_prompt(
+    *,
+    question: str,
+    sql: str,
+    schema_context: SchemaContext,
+    default_limit: int,
+    max_limit: int,
+    confirmed_query_plan: dict[str, Any] | None = None,
+) -> str:
+    payload = _base_sql_prompt_payload(
+        question=question,
+        schema_context=schema_context,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        confirmed_query_plan=confirmed_query_plan,
+        task="review_sql_executability",
+        original_sql=sql,
+    )
+    payload["reviewInstruction"] = (
+        "你是专业 MySQL SQL 专家，只检查 SQL 写法是否整体可执行，不改变业务口径。"
+        "重点检查：聚合函数是否误写在 WHERE/JOIN ON；GROUP BY/HAVING 是否合法；"
+        "子查询和派生表别名是否完整；外层引用的派生表字段是否存在；"
+        "SELECT 中非聚合字段与 GROUP BY 是否兼容；MySQL 低版本不支持 WITH。"
+        "如果 SQL 可执行，返回 executable=true 且 repairedSql 为空；"
+        "如果不可执行，返回 executable=false、issues，并在不改变业务口径和 schema 字段的前提下给出 repairedSql。"
+    )
+    payload["reviewOutputSchema"] = {
+        "executable": True,
+        "issues": [{"code": "ISSUE_CODE", "message": "中文问题说明", "repairHint": "中文修复建议"}],
+        "repairedSql": "SELECT ... LIMIT 50 或空字符串",
+    }
+    compact = confirmed_query_plan is not None
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        indent=None if compact else 2,
+        separators=(",", ":") if compact else (", ", ": "),
+    )
+
+
 def _base_sql_prompt_payload(
     *,
     question: str,
@@ -99,8 +140,13 @@ def _base_sql_prompt_payload(
             "schemaContext 未提供对应口径时，不要凭训练记忆或字段名猜测 SQL。"
             "涉及时间范围时，如果命中的 schemaContext.concepts 或 metrics 提供 timeRangeField，"
             "必须使用该字段生成 WHERE 时间过滤，不要改用关联维表的同名时间字段。"
+            "JOIN ... ON 只能写 schemaContext.relations / joins / exampleJoinPatterns 中提供的等值关联键；"
+            "禁止凭字段名相似或训练记忆新增 schema 未定义 JOIN。"
             "涉及“最多/最高/最大/排名/排行”等聚合极值诉求时，必须优先按聚合指标倒序排序，"
             "再按时间等次要维度排序。"
+            "你必须作为专业 MySQL SQL 专家自检 SQL 整体可执行性：聚合函数不能写在 WHERE/JOIN ON，"
+            "聚合筛选必须放 HAVING 或先在子查询聚合后外层过滤；派生表字段和别名必须真实存在；"
+            "MySQL 低版本不支持 WITH。"
             "不要把查询动作、状态变化、时间词或范围词当作名称筛选；"
             "只有用户明确说“名称包含/岗位名称是/叫做/简称为”时，才允许对 name/title/job_name 写 LIKE。"
             if not compact
@@ -112,8 +158,13 @@ def _base_sql_prompt_payload(
             "schemaContext 未提供对应口径时，不要凭训练记忆或字段名猜测 SQL。"
             "涉及时间范围时，如果命中的 schemaContext.concepts 或 metrics 提供 timeRangeField，"
             "必须使用该字段生成 WHERE 时间过滤，不要改用关联维表的同名时间字段。"
+            "JOIN ... ON 只能写 schemaContext.relations / joins / exampleJoinPatterns 中提供的等值关联键；"
+            "禁止凭字段名相似或训练记忆新增 schema 未定义 JOIN。"
             "涉及“最多/最高/最大/排名/排行”等聚合极值诉求时，必须优先按聚合指标倒序排序，"
             "再按时间等次要维度排序。"
+            "你必须作为专业 MySQL SQL 专家自检 SQL 整体可执行性：聚合函数不能写在 WHERE/JOIN ON，"
+            "聚合筛选必须放 HAVING 或先在子查询聚合后外层过滤；派生表字段和别名必须真实存在；"
+            "MySQL 低版本不支持 WITH。"
             "JOIN ... ON 只能写 schema relations / joins 中的等值关联键（如 a.id = b.x_id）；"
             "confirmedQueryPlan.filters 里的 LIKE/IN 筛选必须写在 WHERE，禁止写在 JOIN ON；"
             "同一 logicalGroup 且 logicalOperator=OR 的筛选必须用 OR 连接，并用括号包裹；"
@@ -125,10 +176,13 @@ def _base_sql_prompt_payload(
         "schemaContext": _schema_context_payload(schema_context, compact=compact),
         "outputSchema": _sql_output_schema(default_limit, question),
     }
-    if task == "repair_sql":
+    if task:
         payload["task"] = task
+    if task == "repair_sql":
         payload["originalSql"] = original_sql or ""
         payload["validationError"] = validation_error or {}
+    elif task == "review_sql_executability":
+        payload["sqlToReview"] = original_sql or ""
     if confirmed_query_plan:
         payload["confirmedQueryPlan"] = _compact_query_plan_for_sql(confirmed_query_plan)
     return payload
@@ -198,13 +252,16 @@ def _compact_query_plan_for_sql(query_plan: dict[str, Any]) -> dict[str, Any]:
     ]
     if entities:
         compact["entities"] = entities
+    plan_filters = query_plan.get("_sqlFilters")
+    if not isinstance(plan_filters, list):
+        plan_filters = query_plan.get("filters", [])
     filters = [
         {
             key: item[key]
             for key in ("field", "operator", "value", "description", "source", "logicalGroup", "logicalOperator")
             if key in item
         }
-        for item in query_plan.get("filters", [])
+        for item in plan_filters
         if isinstance(item, dict)
     ]
     if filters:

package/src/octopus_skill/question_analyzer.py

@@ -132,10 +132,15 @@ class QuestionAnalysisError(Exception):
     """Raised when question analysis fails."""
 
 
+SAMPLING_MAX_RETRIES = 2
+
+
 def analyze_question(
     question: str,
     sampler: Sampler,
     agent_instructions: list[dict[str, Any]] | None = None,
+    *,
+    max_sampling_retries: int = SAMPLING_MAX_RETRIES,
 ) -> QuestionAnalysis:
     """Use LLM to analyze user question and extract structured intent + query targets.
 
@@ -152,12 +157,18 @@ def analyze_question(
     """
     prompt = build_question_analysis_prompt(question, agent_instructions)
 
-    try:
-        raw_response = sampler(QUESTION_ANALYSIS_SYSTEM_PROMPT, prompt)
-    except Exception as exc:
-        raise QuestionAnalysisError(f"LLM 调用失败：{type(exc).__name__}: {exc}") from exc
-
-    payload = _parse_analysis_response(raw_response)
+    raw_response: str | None = None
+    for attempt in range(max_sampling_retries + 1):
+        try:
+            raw_response = sampler(QUESTION_ANALYSIS_SYSTEM_PROMPT, prompt)
+            break
+        except Exception as exc:
+            if attempt >= max_sampling_retries:
+                raise QuestionAnalysisError(
+                    f"LLM 调用失败（已重试 {max_sampling_retries} 次）：{type(exc).__name__}: {exc}"
+                ) from exc
+
+    payload = _parse_analysis_response(raw_response or "")
     return _build_analysis(payload, question)
 
 

package/src/octopus_skill/sql_generator.py

@@ -49,6 +49,9 @@ class SchemaValidationIssue:
 class LowQualitySqlIssue:
     code: str
     message: str
+    missing_items: tuple[str, ...] = ()
+    current_problem: str = ""
+    repair_hint: str = ""
 
 
 _SELECT_AS_ALIAS_PATTERN = (
@@ -86,6 +89,7 @@ def enforce_sql_rules(sql: str, *, max_limit: int) -> None:
         raise SqlGenerationError("SQL must not contain scope placeholders")
     _enforce_text_filters_use_like(sql)
     _enforce_join_on_uses_equality_keys(sql)
+    _enforce_no_aggregate_functions_in_row_filters(sql)
     _enforce_chinese_select_aliases(sql)
     _enforce_no_null_placeholder_select_items(sql)
     _enforce_no_tautological_join_conditions(sql)
@@ -724,6 +728,41 @@ def _enforce_join_on_uses_equality_keys(sql: str) -> None:
         raise SqlGenerationError(violations[0])
 
 
+_AGGREGATE_FUNCTION_RE = re.compile(
+    r"\b(?:count|sum|avg|min|max|group_concat)\s*\(",
+    flags=re.IGNORECASE,
+)
+
+
+def _enforce_no_aggregate_functions_in_row_filters(sql: str) -> None:
+    for clause in _iter_join_on_clauses(sql):
+        if _AGGREGATE_FUNCTION_RE.search(clause):
+            raise SqlGenerationError(
+                "SQL aggregate functions must not be used in JOIN ON; "
+                "aggregate first in a subquery or move aggregate predicates to HAVING"
+            )
+    where_clause = _top_level_where_clause(sql)
+    if where_clause and _AGGREGATE_FUNCTION_RE.search(where_clause):
+        raise SqlGenerationError(
+            "SQL aggregate functions must not be used in WHERE; "
+            "move aggregate predicates to HAVING or aggregate first in a subquery"
+        )
+
+
+def _top_level_where_clause(sql: str) -> str:
+    where_index = _find_top_level_keyword(sql, "where", start=0)
+    if where_index is None:
+        return ""
+    body_start = where_index + len("where")
+    suffix_starts = [
+        index
+        for keyword in ("group by", "having", "order by", "limit")
+        if (index := _find_top_level_keyword(sql, keyword, start=body_start)) is not None
+    ]
+    body_end = min(suffix_starts) if suffix_starts else len(sql)
+    return sql[body_start:body_end]
+
+
 def _select_item_has_chinese_alias(item: str) -> bool:
     alias = _extract_select_alias(item)
     return alias is not None and re.search(r"[\u4e00-\u9fff]", alias) is not None
@@ -877,7 +916,18 @@ def low_quality_sql_issue_for_question(question: str, sql: str, *, schema: dict[
             table = str(table_name or "").strip().lower()
             if table and table not in normalized:
                 message = str(checks.get("message") or f"SQL 必须引用 schema 要求的表：{table_name}")
-                return LowQualitySqlIssue(code="SCHEMA_SQL_QUALITY", message=message)
+                concept_label = str(concept.get("comment") or concept.get("name") or "命中的 schema concept")
+                return LowQualitySqlIssue(
+                    code="SCHEMA_SQL_QUALITY",
+                    message=message,
+                    missing_items=(f"必须引用表 {table_name}",),
+                    current_problem=(
+                        f"当前 SQL 没有使用 {table_name}，无法覆盖“{concept_label}”要求的查询口径。"
+                    ),
+                    repair_hint=(
+                        f"按 schema.concepts 中“{concept_label}”的定义补充 {table_name} 及对应 JOIN/WHERE 条件。"
+                    ),
+                )
     aggregate_issue = _aggregate_sql_quality_issue(question, sql)
     if aggregate_issue is not None:
         return aggregate_issue
@@ -901,6 +951,9 @@ def _concept_time_range_field_issue(
                 f"用户问题包含时间范围，且 schema concept 指定时间字段为 {qualified}；"
                 "SQL 必须使用该字段过滤时间范围，不要改用关联维表的同名时间字段。"
             ),
+            missing_items=(f"时间范围字段 {qualified}",),
+            current_problem=f"当前 SQL 没有使用 {qualified} 过滤用户要求的时间范围。",
+            repair_hint=f"在 WHERE 中使用 {qualified} 补充时间范围过滤。",
         )
     unexpected = _unexpected_time_filter_fields(sql, expected_field=qualified)
     if unexpected:
@@ -910,6 +963,9 @@ def _concept_time_range_field_issue(
                 f"用户问题包含时间范围，且 schema concept 指定时间字段为 {qualified}；"
                 f"SQL 不应同时使用 {'、'.join(unexpected)} 过滤时间范围。"
             ),
+            missing_items=(f"唯一时间范围字段 {qualified}",),
+            current_problem=f"当前 SQL 还使用了 {'、'.join(unexpected)} 过滤时间范围，可能把口径切到关联表时间。",
+            repair_hint=f"删除关联表时间过滤，只保留 {qualified} 的时间范围条件。",
         )
     return None
 
@@ -972,9 +1028,23 @@ def _aggregate_sql_quality_issue(question: str, sql: str) -> LowQualitySqlIssue
     return LowQualitySqlIssue(
         code="AGGREGATE_SQL_REQUIRED",
         message="用户问题要求统计数量/最多值及对应维度，SQL 必须使用 COUNT/SUM/AVG/MIN/MAX 等聚合函数，不能只返回明细行。",
+        missing_items=("聚合函数 COUNT/SUM/AVG/MIN/MAX",),
+        current_problem="当前 SQL 返回明细行，不能回答数量、最多值、排名或按维度统计问题。",
+        repair_hint="按用户问题中的统计维度 GROUP BY，并用聚合函数生成指标。",
     )
 
 
+def format_sql_quality_issue(issue: LowQualitySqlIssue) -> str:
+    parts = [f"当前 SQL 不满足查询口径：{issue.message}"]
+    if issue.missing_items:
+        parts.append(f"缺失口径：{'；'.join(issue.missing_items)}")
+    if issue.current_problem:
+        parts.append(f"当前 SQL 的问题：{issue.current_problem}")
+    if issue.repair_hint:
+        parts.append(f"建议修复方向：{issue.repair_hint}")
+    return "；".join(parts)
+
+
 def _question_requires_aggregate_sql(question: str) -> bool:
     if not re.search(r"(计数|统计|数量|个数|总数|多少)", question):
         return False
@@ -1207,6 +1277,7 @@ def _schema_invalid_join_issues(
     allowed_pairs = _schema_allowed_join_pairs(schema)
     if not allowed_pairs:
         return []
+    derived_aliases = set(_sql_derived_subquery_aliases(sql))
     issues: list[SchemaValidationIssue] = []
     seen: set[tuple[tuple[str, str], tuple[str, str]]] = set()
     for pair in _sql_equality_pairs(sql, table_aliases):
@@ -1216,6 +1287,8 @@ def _schema_invalid_join_issues(
         if pair in allowed_pairs:
             continue
         left, right = pair
+        if left[0] in derived_aliases or right[0] in derived_aliases:
+            continue
         issues.append(
             SchemaValidationIssue(
                 code="INVALID_JOIN",
@@ -1323,19 +1396,37 @@ def _sql_derived_subquery_spans(sql: str) -> list[tuple[int, int]]:
     ]
 
 
+_DERIVED_SUBQUERY_TRAILING = (
+    r"on\b"
+    r"|(?:(?:left|right|inner|outer|cross|natural)\s+)?join\b"
+    r"|where\b|group\b|order\b|having\b|limit\b"
+    r"|,"
+    r"|\)(?!\s*[a-zA-Z_])"
+    r"|;"
+)
+_DERIVED_SUBQUERY_ALIAS_PATTERN = re.compile(
+    rf"\)\s*(?:as\s+)?([a-zA-Z_][a-zA-Z0-9_]*)(?:\s+(?:{_DERIVED_SUBQUERY_TRAILING})|\s*$)",
+    flags=re.IGNORECASE,
+)
+_RESERVED_DERIVED_ALIASES = frozenset(
+    {"on", "where", "left", "right", "inner", "outer", "join", "select", "cross", "natural", "group", "order", "having", "limit"}
+)
+
+
 def _sql_derived_subquery_matches(sql: str) -> list[tuple[str, int, int]]:
     matches: list[tuple[str, int, int]] = []
-    for match in re.finditer(
-        r"\)\s*(?:as\s+)?([a-zA-Z_][a-zA-Z0-9_]*)\s+on\b",
-        sql,
-        flags=re.IGNORECASE,
-    ):
+    seen_ranges: set[tuple[int, int]] = set()
+    for match in _DERIVED_SUBQUERY_ALIAS_PATTERN.finditer(sql):
         alias = match.group(1).lower()
-        if alias in {"on", "where", "left", "right", "inner", "outer", "join", "select"}:
+        if alias in _RESERVED_DERIVED_ALIASES:
             continue
         subquery_start = _find_matching_open_paren(sql, match.start())
         if subquery_start is None:
             continue
+        range_key = (subquery_start, match.start())
+        if range_key in seen_ranges:
+            continue
+        seen_ranges.add(range_key)
         matches.append((alias, subquery_start, match.start()))
     return matches
 
@@ -1662,7 +1753,7 @@ def time_range_from_query_plan(query_plan: dict[str, Any] | None) -> TimeRange |
     start_value = ""
     end_value = ""
     field_name = ""
-    for flt in query_plan.get("filters") or []:
+    for flt in _query_plan_sql_filters(query_plan):
         if not isinstance(flt, dict):
             continue
         if str(flt.get("source") or "") != "question.timeRange":
@@ -1853,7 +1944,34 @@ def resolve_time_range_for_sql(
 
     concepts = match_concepts_for_question(_schema_concepts(schema), question)
     sql_schema = _schema_limited_to_sql_tables(schema, sql)
-    return resolve_time_range_for_question(question, sql_schema or schema, concepts=concepts)
+    if sql_schema is None and _sql_referenced_table_names(sql):
+        return None
+    if sql_schema is not None:
+        return resolve_time_range_for_question(
+            question,
+            sql_schema,
+            concepts=_concepts_limited_to_schema_tables(concepts, sql_schema),
+        )
+    return resolve_time_range_for_question(question, schema, concepts=concepts)
+
+
+def _concepts_limited_to_schema_tables(
+    concepts: list[dict[str, Any]],
+    schema: dict[str, Any],
+) -> list[dict[str, Any]]:
+    table_names = {name.lower() for name in _table_names(schema)}
+    if not table_names:
+        return []
+    limited: list[dict[str, Any]] = []
+    for concept in concepts:
+        qualified = str(concept.get("timeRangeField") or "").strip()
+        if "." not in qualified:
+            limited.append(concept)
+            continue
+        table_name = qualified.split(".", 1)[0].lower()
+        if table_name in table_names:
+            limited.append(concept)
+    return limited
 
 
 def _qualified_time_range_field(time_range: TimeRange) -> str:
@@ -2004,7 +2122,7 @@ def sql_missing_query_plan_filters(sql: str, query_plan: dict[str, Any] | None)
     missing: list[str] = []
     normalized_sql = sql.lower()
     grouped_filters: dict[str, list[dict[str, Any]]] = {}
-    for flt in query_plan.get("filters") or []:
+    for flt in _query_plan_sql_filters(query_plan):
         if not isinstance(flt, dict):
             continue
         if str(flt.get("operator") or "").upper() != "LIKE":
@@ -2045,6 +2163,14 @@ def sql_satisfies_query_plan_filters(sql: str, query_plan: dict[str, Any] | None
     return not sql_missing_query_plan_filters(sql, query_plan)
 
 
+def _query_plan_sql_filters(query_plan: dict[str, Any]) -> list[Any]:
+    filters = query_plan.get("_sqlFilters")
+    if isinstance(filters, list):
+        return filters
+    filters = query_plan.get("filters")
+    return filters if isinstance(filters, list) else []
+
+
 def _or_group_filters_connected_by_or(normalized_sql: str, filters: list[dict[str, Any]]) -> bool:
     if not re.search(r"\bor\b", normalized_sql):
         return False