@roll-agent/octopus-agent 0.1.0 → 0.1.2

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():