@roll-agent/octopus-agent 0.1.1 → 0.1.3

package/src/octopus_skill/octopus_run.py

@@ -104,7 +104,7 @@ def tool_definitions() -> list[Json]:
         },
         {
             "name": "query_sponge",
-            "description": "业务查询唯一入口：把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。只有用户给出明确业务数据查询问题时才调用本工具；用户只是说使用、启动、检查、看看丸子Agent，或确认 Agent 是否可用时，不得调用本工具，应调用 diagnostic_status 后停止，不得编造示例业务问题。本工具内部第一步会检查本地 schemaVersion，并调用 Sponge get_schema 按需刷新 schema cache；普通业务查询不得额外调用 refresh_schema。工具会先按 schema 中文语义识别表、字段、筛选条件、枚举和实体，把 search_entities 的真实命中项固化进 queryPlan，再直接生成、校验并执行 SQL，不再要求用户确认查询计划；状态枚举不单独追问，用户未提出状态条件时首次查询保持宽泛，但查询结果必须展示相关状态字段的中文含义；search_entities 只用于实体别称和模糊召回，品牌/项目等多个实体同时命中时不追问用户，queryPlan 会用同组 OR 条件承载。上层模型必须直接调用本工具；不要自行生成 SQL；不要解释 schema；不要改写用户问题。originalQuestion 必须传用户原始话术。对报告类问题必须只调用一次 query_sponge 处理完整原始问题，不要拆成多个子查询。工具返回后必须把 content[0].text 或 structuredContent.answer 原文作为最终用户可见答复完整展示；finalAnswerOnly=true（默认）时不得改写、删减、摘要、截断或追加内容，表格不得只展示前 N 条。content[0].text 只展示三段式用户可见答复（1.查询实体；2.筛选条件；3.查询结果）；structuredContent.executionSteps 会返回每一步状态，失败时包含实际 error 原因。默认 fastMode=true、finalAnswerOnly=true，structuredContent.responseMode=verbatim；复杂查询会使用 schema context 和 LLM 生成。",
+            "description": "业务查询唯一入口：把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。只有用户给出明确业务数据查询问题时才调用本工具；用户只是说使用、启动、检查、看看丸子Agent，或确认 Agent 是否可用时，不得调用本工具，应调用 diagnostic_status 后停止，不得编造示例业务问题。本工具内部第一步会检查本地 schemaVersion，并调用 Sponge get_schema 按需刷新 schema cache；普通业务查询不得额外调用 refresh_schema。工具会先按 schema 中文语义识别表、字段、筛选条件、枚举和实体，把 search_entities 的真实命中项固化进 queryPlan，再直接生成、校验并执行 SQL，不再要求用户确认查询计划；状态枚举不单独追问，用户未提出状态条件时首次查询保持宽泛，但查询结果必须展示相关状态字段的中文含义；search_entities 只用于实体别称和模糊召回，品牌/项目等多个实体同时命中时不追问用户，queryPlan 会用同组 OR 条件承载。上层模型必须直接调用本工具；不要自行生成 SQL；不要解释 schema；不要改写用户问题。originalQuestion 必须传用户原始话术。对报告类问题必须只调用一次 query_sponge 处理完整原始问题，不要拆成多个子查询。工具返回后必须把 content[0].text 或 structuredContent.answer 原文作为最终用户可见答复完整展示；finalAnswerOnly=true（默认）时不得改写、删减、摘要、截断或追加内容，表格不得只展示前 N 条。content[0].text 只展示三段式用户可见答复（1.查询实体；2.筛选条件；3.查询结果）；structuredContent.executionSteps 会返回每一步状态和 durationMs，structuredContent.timing 会返回 totalDurationMs 与 stepDurationMs，失败时包含实际 error 原因。默认 fastMode=true、finalAnswerOnly=true，structuredContent.responseMode=verbatim；复杂查询会使用 schema context 和 LLM 生成。",
             "inputSchema": {
                 "type": "object",
                 "required": ["question", "originalQuestion"],
@@ -116,7 +116,7 @@ def tool_definitions() -> list[Json]:
                     },
                     "fastMode": {
                         "type": "boolean",
-                        "description": "是否启用快路径；默认 true。true 时优先使用本地 schema 缓存和规则模板，失败才走 LLM；false 时优先让 LLM 生成 SQL。",
+                        "description": "是否启用快路径；默认 true。true 时跳过 LLM SQL 专家复核，仍保留本地规则、validate_sql 与 execute_sql 兜底；false 时仅对含聚合/子查询的高风险 SQL 启用专家复核。",
                     },
                     "finalAnswerOnly": {
                         "type": "boolean",
@@ -473,6 +473,9 @@ def _query_result_payload(query_result: Any, *, include_sql: bool = False, base_
     execution_steps = getattr(query_result, "execution_steps", None)
     if isinstance(execution_steps, list):
         payload["executionSteps"] = execution_steps
+    timing = getattr(query_result, "timing", None)
+    if isinstance(timing, dict) and timing:
+        payload["timing"] = timing
     if include_sql:
         payload.update(
             {

package/src/octopus_skill/prompt_builder.py

@@ -168,6 +168,9 @@ def _base_sql_prompt_payload(
             "JOIN ... ON 只能写 schema relations / joins 中的等值关联键（如 a.id = b.x_id）；"
             "confirmedQueryPlan.filters 里的 LIKE/IN 筛选必须写在 WHERE，禁止写在 JOIN ON；"
             "同一 logicalGroup 且 logicalOperator=OR 的筛选必须用 OR 连接，并用括号包裹；"
+            "没有 logicalGroup 的筛选默认用 AND 连接；"
+            "不同地点维度（city.name 与 region.name）若没有同一 logicalGroup，必须用 AND 连接，"
+            "例如 c.name LIKE '%苏州%' AND r.name LIKE '%昆山%'；禁止写成 (c.name LIKE '%苏州%' OR r.name LIKE '%昆山%')；"
             "confirmedQueryPlan.fields 中 required=true 的字段必须出现在 SELECT 中；"
             "不要把查询动作、状态变化、时间词或范围词当作名称筛选。"
         ),

package/src/octopus_skill/question_analyzer.py

@@ -63,6 +63,8 @@ QUESTION_ANALYSIS_SYSTEM_PROMPT = """你是丸子Agent（Octopus Agent）的需
 - 例如“成都你六姐明天面试的工单数量”：`成都你六姐` 是品牌/项目候选，`明天` 是 timeRange，`面试` 是业务阶段或动作，`工单数量` 是业务对象和指标；`成都你六姐明天面试` 必须放入 noiseValues，不能作为任何时间字段、名称字段或工单字段的筛选值。
 - 遇到“名称 + 有多少 + 时间词 + 阶段/动作词 + 业务对象”时，查询对象必须是最后的业务对象，指标必须是该业务对象数量；例如“成都你六姐有多少明天面试的工单”必须输出 targetEntities=["工单"]、metrics=["工单数量"]，不能输出 targetEntities=["品牌"] 或 targetEntities=["项目"]。
 - 当用户未明确说明“品牌”或“项目”，但名称片段像品牌/项目名称时，entityCandidates 同时输出 brand 和 sponge_project 两个候选，后续模块会走实体检索确认。
+- 地级市倾向 type=city；区/县/旗倾向 type=region；用户同时说了地级市和其下区县/县级市时（如苏州昆山市），entityCandidates 分别输出 city=苏州 与 region=昆山市，二者是层级筛选不是二选一。
+- 用户只说了一个「XX市」且可能是县级市（如江阴市），entityCandidates 同时输出 city 和 region 两个候选（同一 value），后续由 search_entities 决定命中。
 - 只有能作为品牌、项目、门店、城市、岗位等真实名称的词，才可作为 entityCandidates 的非噪声实体值。
 - 不要因为一个词是状态或时间就忽略它；必须保留到正确语义字段里。
 

package/src/octopus_skill/sql_generator.py

@@ -970,18 +970,55 @@ def _concept_time_range_field_issue(
     return None
 
 
+_TIME_RANGE_DATE_LITERAL = r"'20\d{2}-\d{1,2}-\d{1,2}(?:\s+\d{1,2}:\d{2}:\d{2})?'"
+
+
 def _sql_has_time_filter_for_range(sql: str, time_range: TimeRange) -> bool:
-    where_index = _find_top_level_keyword(sql, "where", start=0)
-    if where_index is None:
-        return False
-    clause_start = where_index + len("where")
-    clause_end = _where_filter_insert_pos(sql[clause_start:])
-    if clause_end < len(sql[clause_start:]):
-        clause_end += clause_start
-    else:
-        clause_end = len(sql)
-    for predicate in _split_top_level_and_predicates(sql[clause_start:clause_end].strip()):
-        if _is_time_range_predicate(predicate, sql=sql, time_range=time_range):
+    if _scope_has_time_filter_for_range(sql, time_range):
+        return True
+    for subquery in _sql_derived_subqueries(sql).values():
+        if _sql_has_time_filter_for_range(subquery, time_range):
+            return True
+    return False
+
+
+def _mask_derived_subqueries(sql: str) -> str:
+    spans = _sql_derived_subquery_spans(sql)
+    if not spans:
+        return sql
+    chars = list(sql)
+    for start, end in spans:
+        for index in range(start, min(end, len(chars))):
+            chars[index] = " "
+    return "".join(chars)
+
+
+def _scope_has_time_filter_for_range(sql: str, time_range: TimeRange) -> bool:
+    """Return True if the designated time field is compared to a date literal in this
+    query scope.
+
+    Nested derived subqueries are masked out here and evaluated separately by
+    ``_sql_has_time_filter_for_range`` so alias resolution stays scoped. The check
+    scans the whole scope (not just the top-level WHERE) so the field can satisfy the
+    requirement whether it is used in WHERE or inside a conditional aggregate such as
+    ``SUM(CASE WHEN sign_up_time >= ... THEN 1 ELSE 0 END)``, which some schema concepts
+    mandate for period metrics.
+    """
+    scope_text = _mask_derived_subqueries(sql)
+    op = r"(?:>=|<=|>|<|=)"
+    date = _TIME_RANGE_DATE_LITERAL
+    field_patterns: list[str] = [_time_range_sql_field_pattern(scope_text, time_range)]
+    base_tables = set(_sql_top_level_table_aliases(scope_text).values())
+    if not time_range.table_name or base_tables == {time_range.table_name.lower()}:
+        # Single base table in scope: an unqualified column reference is unambiguous.
+        field_patterns.append(rf"(?<![.\w]){re.escape(time_range.field.lower())}\b")
+    for field_pattern in field_patterns:
+        checks = (
+            rf"{field_pattern}\s*{op}\s*{date}",
+            rf"{date}\s*{op}\s*{field_pattern}",
+            rf"{field_pattern}\s+between\s+{date}\s+and\s+{date}",
+        )
+        if any(re.search(pattern, scope_text, flags=re.IGNORECASE) for pattern in checks):
             return True
     return False
 
@@ -2122,9 +2159,8 @@ 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_sql_filters(query_plan):
-        if not isinstance(flt, dict):
-            continue
+    plan_filters = [flt for flt in _query_plan_sql_filters(query_plan) if isinstance(flt, dict)]
+    for flt in plan_filters:
         if str(flt.get("operator") or "").upper() != "LIKE":
             continue
         logical_group = str(flt.get("logicalGroup") or "").strip()
@@ -2156,6 +2192,18 @@ def sql_missing_query_plan_filters(sql: str, query_plan: dict[str, Any] | None)
             continue
         if not _or_group_filters_connected_by_or(normalized_sql, filters):
             missing.append(f"{group_name} requires OR between matched entities")
+    and_pairs = _hierarchical_location_and_filter_pairs(plan_filters)
+    for city_flt, region_flt in and_pairs:
+        city_token = f"{city_flt.get('field')} LIKE {city_flt.get('value')}"
+        region_token = f"{region_flt.get('field')} LIKE {region_flt.get('value')}"
+        if city_token in missing or region_token in missing:
+            continue
+        if _filters_connected_by_or(normalized_sql, [city_flt, region_flt]):
+            missing.append(
+                "city.name and region.name require AND for hierarchical location filters "
+                f"({city_flt.get('value')} AND {region_flt.get('value')})"
+            )
+            break
     return missing
 
 
@@ -2171,6 +2219,55 @@ def _query_plan_sql_filters(query_plan: dict[str, Any]) -> list[Any]:
     return filters if isinstance(filters, list) else []
 
 
+def _location_place_key_for_filter(value: str) -> str:
+    cleaned = str(value or "").strip().strip("%")
+    if not cleaned:
+        return ""
+    for suffix in ("自治州", "地区", "市", "区", "县", "旗"):
+        if cleaned.endswith(suffix) and len(cleaned) > len(suffix):
+            return cleaned[: -len(suffix)]
+    return cleaned
+
+
+def _hierarchical_location_and_filter_pairs(
+    filters: list[dict[str, Any]],
+) -> list[tuple[dict[str, Any], dict[str, Any]]]:
+    """City/region filters that must be AND-ed (distinct places, not same-place OR)."""
+    city_filters = [
+        flt
+        for flt in filters
+        if str(flt.get("field") or "") == "city.name" and str(flt.get("operator") or "").upper() == "LIKE"
+    ]
+    region_filters = [
+        flt
+        for flt in filters
+        if str(flt.get("field") or "") == "region.name" and str(flt.get("operator") or "").upper() == "LIKE"
+    ]
+    if not city_filters or not region_filters:
+        return []
+    pairs: list[tuple[dict[str, Any], dict[str, Any]]] = []
+    for city_flt in city_filters:
+        city_key = _location_place_key_for_filter(str(city_flt.get("value") or ""))
+        city_group = str(city_flt.get("logicalGroup") or "").strip()
+        city_op = str(city_flt.get("logicalOperator") or "").upper()
+        for region_flt in region_filters:
+            region_key = _location_place_key_for_filter(str(region_flt.get("value") or ""))
+            region_group = str(region_flt.get("logicalGroup") or "").strip()
+            region_op = str(region_flt.get("logicalOperator") or "").upper()
+            same_or_group = bool(
+                city_group
+                and city_group == region_group
+                and city_op == "OR"
+                and region_op == "OR"
+            )
+            if same_or_group:
+                continue
+            if city_key and region_key and city_key == region_key:
+                continue
+            pairs.append((city_flt, region_flt))
+    return pairs
+
+
 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
@@ -2189,6 +2286,24 @@ def _or_group_filters_connected_by_or(normalized_sql: str, filters: list[dict[st
     return bool(re.search(r"\bor\b", between))
 
 
+def _filters_connected_by_or(normalized_sql: str, filters: list[dict[str, Any]]) -> bool:
+    if not re.search(r"\bor\b", normalized_sql):
+        return False
+    positions: list[int] = []
+    for flt in filters:
+        value = str(flt.get("value") or "").strip().strip("%").lower()
+        if not value:
+            continue
+        found = normalized_sql.find(value)
+        if found >= 0:
+            positions.append(found)
+    if len(positions) < 2:
+        return False
+    start, end = min(positions), max(positions)
+    between = normalized_sql[start:end]
+    return bool(re.search(r"\bor\b", between))
+
+
 def sql_missing_query_plan_select_fields(sql: str, query_plan: dict[str, Any] | None) -> list[str]:
     """Return required SELECT display fields from query_plan that are absent in sql."""
     if not isinstance(query_plan, dict):