@roll-agent/octopus-agent 0.0.1 → 0.0.4

package/src/octopus_sponge_skill/device_info.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+import platform
+
+
+def get_device_info() -> str:
+    return platform.platform(aliased=True, terse=True)

package/src/octopus_sponge_skill/llm_sql_generator.py

@@ -24,12 +24,10 @@ class SamplingSqlGenerator:
         *,
         question: str,
         schema_context: SchemaContext,
-        scope_hints: dict[str, Any],
     ) -> GeneratedSql:
         prompt = build_nl2sql_prompt(
             question=question,
             schema_context=schema_context,
-            scope_hints=scope_hints,
             default_limit=self.default_limit,
             max_limit=self.max_limit,
         )
@@ -42,14 +40,13 @@ class SamplingSqlGenerator:
         original_sql: str,
         validation_error: dict[str, Any],
         schema_context: SchemaContext,
-        scope_hints: dict[str, Any],
     ) -> GeneratedSql:
         prompt = build_sql_repair_prompt(
             question=question,
             original_sql=original_sql,
             validation_error=validation_error,
             schema_context=schema_context,
-            scope_hints=scope_hints,
+            default_limit=self.default_limit,
             max_limit=self.max_limit,
         )
         return _parse_generated_sql(self.sampler(NL2SQL_SYSTEM_PROMPT, prompt))
@@ -62,19 +59,31 @@ def _parse_generated_sql(text: str) -> GeneratedSql:
         sql = _extract_sql_text(text)
         if sql is None:
             raise
+        _require_select_sql(sql)
         return GeneratedSql(sql=sql, tables=[], placeholders=[])
     sql = payload.get("sql")
-    if not isinstance(sql, str) or not sql.strip():
+    if isinstance(sql, str) and not sql.strip():
+        return GeneratedSql(sql="", tables=[], placeholders=[], used_columns=[], used_joins=[], metric_refs=[])
+    if not isinstance(sql, str):
         fallback_sql = _extract_sql_text(text)
         if fallback_sql is None:
             raise SqlGenerationError("LLM output must contain sql")
+        _require_select_sql(fallback_sql)
         return GeneratedSql(sql=fallback_sql, tables=[], placeholders=[])
+    sql = sql.strip()
+    _require_select_sql(sql)
     tables = payload.get("tables") if isinstance(payload.get("tables"), list) else []
     placeholders = payload.get("placeholders") if isinstance(payload.get("placeholders"), list) else []
+    used_columns = payload.get("usedColumns") if isinstance(payload.get("usedColumns"), list) else []
+    used_joins = payload.get("usedJoins") if isinstance(payload.get("usedJoins"), list) else []
+    metric_refs = payload.get("metricRefs") if isinstance(payload.get("metricRefs"), list) else []
     return GeneratedSql(
-        sql=sql.strip(),
+        sql=sql,
         tables=[str(table) for table in tables],
         placeholders=[str(placeholder) for placeholder in placeholders],
+        used_columns=[str(column) for column in used_columns],
+        used_joins=[str(join) for join in used_joins],
+        metric_refs=[str(metric) for metric in metric_refs],
     )
 
 
@@ -110,3 +119,11 @@ def _extract_sql_text(text: str) -> str | None:
     if sql.endswith(";"):
         sql = sql[:-1].strip()
     return sql
+
+
+def _require_select_sql(sql: str) -> None:
+    normalized = sql.strip().lower()
+    if not normalized.startswith("select "):
+        raise SqlGenerationError("LLM SQL must be SELECT only")
+    if re.search(r"\b(insert|update|delete|drop|alter|create|truncate)\b", normalized):
+        raise SqlGenerationError("LLM SQL contains a forbidden keyword")

package/src/octopus_sponge_skill/main.py

@@ -9,9 +9,7 @@ from .config import load_config_from_env
 def main() -> None:
     parser = argparse.ArgumentParser(prog="octopus-sponge")
     parser.add_argument("question")
-    parser.add_argument("--user-id", type=int, required=True)
     parser.add_argument("--session-id")
-    parser.add_argument("--device-id")
     args = parser.parse_args()
 
     config = load_config_from_env()
@@ -19,9 +17,7 @@ def main() -> None:
     print(
         agent.answer(
             question=args.question,
-            user_id=args.user_id,
             session_id=args.session_id,
-            device_id=args.device_id,
         )
     )
 

package/src/octopus_sponge_skill/mcp_client.py

@@ -21,46 +21,28 @@ class SpongeMcpClient:
         self,
         *,
         trace_id: str,
-        schema_version: str | None,
-        refresh_reason: str,
+        session_id: str | None = None,
+        schema_version: str | None = None,
     ) -> dict[str, Any]:
         payload = {
             "traceId": trace_id,
+            "sessionId": session_id,
             "schemaVersion": schema_version,
-            "refreshReason": refresh_reason,
         }
         return self._post("get_schema", payload)
 
-    def get_allowed_context(
-        self,
-        *,
-        user_id: int,
-        trace_id: str,
-        session_id: str,
-        question: str,
-        device_id: str | None = None,
-    ) -> dict[str, Any]:
-        payload = {
-            "userId": user_id,
-            "traceId": trace_id,
-            "sessionId": session_id,
-            "deviceId": device_id,
-            "question": question,
-        }
-        return self._post("get_allowed_context", payload)
-
     def validate_sql(
         self,
         *,
-        user_id: int,
         trace_id: str,
         session_id: str,
+        question: str,
         sql: str,
     ) -> dict[str, Any]:
         payload = {
-            "userId": user_id,
             "traceId": trace_id,
             "sessionId": session_id,
+            "question": question,
             "sql": sql,
         }
         return self._post("validate_sql", payload)
@@ -68,16 +50,16 @@ class SpongeMcpClient:
     def execute_sql(
         self,
         *,
-        user_id: int,
         trace_id: str,
         session_id: str,
+        question: str,
         sql: str,
         timeout_ms: int | None = None,
     ) -> dict[str, Any]:
         payload = {
-            "userId": user_id,
             "traceId": trace_id,
             "sessionId": session_id,
+            "question": question,
             "sql": sql,
             "timeoutMs": timeout_ms or self.timeout_ms,
         }

package/src/octopus_sponge_skill/prompt_builder.py

@@ -8,37 +8,59 @@ from .schema_context_retriever import SchemaContext
 
 NL2SQL_SYSTEM_PROMPT = """你是 Octopus 的 Sponge 数据查询 SQL 生成器。
 你只能基于提供的 schema context 生成 MySQL SELECT 查询。
-SQL 必须使用 :scope.project_ids 和 :scope.brand_ids 表示用户可访问范围。
-不得硬编码真实 projectId 或 brandId。
+返回 JSON 中的 sql 字段必须直接以 SELECT 开头，不能返回非 SQL 文本。
+只生成业务 SQL，不要生成权限占位符或权限条件。
+不得使用 :scope.project_ids、:scope.brand_ids 或任何 :scope.* placeholder（占位符）。
+如果用户没有明确要求返回条数，LIMIT 必须使用 defaultLimit。
 不得查询 auth 库、密码、令牌、密钥、凭证字段。
-不得生成 INSERT、UPDATE、DELETE、DDL 或多语句 SQL。
+不得生成 INSERT、UPDATE、DELETE、DDL、非 SELECT SQL 或多语句 SQL。
+SELECT 中每个输出字段都必须使用 AS 中文含义，例如 b.name AS 品牌名称。
+禁止使用英文别名，例如 brand_name、project_name。
+用户点名要求输出的字段，必须优先使用 schema context 中含义匹配的真实字段或真实关联表生成。
+不得为了凑齐字段写 NULL AS 字段名、CAST(NULL AS ...) AS 字段名 等空占位表达式。
+只有 schema context 中完全没有相关真实字段或关联表时，才允许不返回该字段；不要用空占位字段替代。
+涉及业务指标或业务口径时，必须优先使用 schemaContext.metrics 中的 definition、aggregation 和 filters。
+如果 schemaContext.metrics 没有给出对应业务口径，不得自行推断状态枚举、有效性过滤或跨轮次分割规则。
+所有业务字段、状态枚举、状态映射、表关联方式必须来自 schemaContext.tables、schemaContext.joins、schemaContext.glossary、schemaContext.metrics 或 schemaContext.examples。
+不得自行猜测状态值；例如“面试成功”“进行中”“已上岗”等状态必须使用 schemaContext 中给出的字段和枚举。
+所有 JOIN 必须优先使用 schemaContext.joins；如果相关 JOIN 只出现在 schemaContext.metrics.filters 或 schemaContext.examples 中，也必须严格照用。
+如果 schemaContext 没有明确给出表、字段、JOIN 或指标口径，不要猜测；返回 {"sql":"","tables":[],"placeholders":[],"usedColumns":[],"usedJoins":[],"metricRefs":[]}。
+报名/工单/候选人状态/姓名/岗位/项目明细查询，必须优先使用 schemaContext 中的报名工单表和示例，不得退化为只查询 brand 品牌列表。
+报名工单与岗位的关联方式必须来自 schemaContext；如果 schemaContext 指明 job_id 关联 job_basic_info.job_id，不得改用 job_basic_info.id。
+地点条件必须先按业务字典判断层级：province.name 省份优先，其次 city.name 城市，再其次 region.name 区域。
+用户提到南京、上海、江苏等地点时，不要先猜测为道路、商圈、门店或地址关键词；只有省/城市/区域都无法匹配时，才按地址关键词模糊查询。
+岗位或门店地点查询优先使用 job_address.city_id、job_address.region_id、store.city_id、store.region_id 等结构化字段。
+用户问题包含时间范围时，SQL 的 WHERE 条件必须直接包含对应时间字段过滤，不得先查询全量数据再补充时间范围。
+时间字段按语义选择：创建/新建/新增使用 create_at，发布/上架使用 publish_at，下架使用 off_at，更新/修改使用 update_at。
 必须包含 LIMIT，且 LIMIT 不超过 500。
-只输出 JSON，不输出解释文本。"""
+不要使用 WITH；低版本 MySQL 不支持公共表表达式，请使用 JOIN 或派生表。
+只输出 JSON，不输出解释文本、拒绝文本或 Markdown。"""
 
 
 def build_nl2sql_prompt(
     *,
     question: str,
     schema_context: SchemaContext,
-    scope_hints: dict[str, Any],
     default_limit: int,
     max_limit: int,
 ) -> str:
     payload = {
         "question": question,
-        "scopeHints": scope_hints,
         "limits": {"defaultLimit": default_limit, "maxLimit": max_limit},
         "schemaContext": {
             "tables": schema_context.tables,
             "joins": schema_context.joins,
             "glossary": schema_context.glossary,
             "metrics": schema_context.metrics,
-            "examples": schema_context.examples,
+            "examples": _business_examples(schema_context.examples),
         },
         "outputSchema": {
-            "sql": "SELECT ... LIMIT 100",
+            "sql": f"SELECT column AS 中文含义 ... LIMIT {default_limit}",
             "tables": ["table_name"],
-            "placeholders": [":scope.project_ids", ":scope.brand_ids"],
+            "placeholders": [],
+            "usedColumns": ["table.column"],
+            "usedJoins": ["left_table.left_column = right_table.right_column"],
+            "metricRefs": ["schemaContext.metrics.name"],
         },
     }
     return json.dumps(payload, ensure_ascii=False, indent=2)
@@ -50,7 +72,7 @@ def build_sql_repair_prompt(
     original_sql: str,
     validation_error: dict[str, Any],
     schema_context: SchemaContext,
-    scope_hints: dict[str, Any],
+    default_limit: int,
     max_limit: int,
 ) -> str:
     payload = {
@@ -58,20 +80,25 @@ def build_sql_repair_prompt(
         "question": question,
         "originalSql": original_sql,
         "validationError": validation_error,
-        "scopeHints": scope_hints,
-        "limits": {"maxLimit": max_limit},
+        "limits": {"defaultLimit": default_limit, "maxLimit": max_limit},
         "schemaContext": {
             "tables": schema_context.tables,
             "joins": schema_context.joins,
             "glossary": schema_context.glossary,
             "metrics": schema_context.metrics,
-            "examples": schema_context.examples,
+            "examples": _business_examples(schema_context.examples),
         },
         "outputSchema": {
-            "sql": "SELECT ... LIMIT 100",
+            "sql": f"SELECT column AS 中文含义 ... LIMIT {default_limit}",
             "tables": ["table_name"],
-            "placeholders": [":scope.project_ids", ":scope.brand_ids"],
+            "placeholders": [],
+            "usedColumns": ["table.column"],
+            "usedJoins": ["left_table.left_column = right_table.right_column"],
+            "metricRefs": ["schemaContext.metrics.name"],
         },
     }
     return json.dumps(payload, ensure_ascii=False, indent=2)
 
+
+def _business_examples(examples: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [example for example in examples if ":scope." not in str(example.get("sql") or "")]

package/src/octopus_sponge_skill/query_sql_cache.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+SQL_GENERATION_CACHE_VERSION = "v9"
+
+
+@dataclass
+class QuerySqlCache:
+    path: Path
+    ttl_minutes: int
+
+    def get(self, *, question: str, schema_version: str | None) -> str | None:
+        if self.ttl_minutes <= 0:
+            return None
+        entry = self._entries().get(_cache_key(question, schema_version))
+        if not isinstance(entry, dict):
+            return None
+        created_at = entry.get("createdAt")
+        sql = entry.get("sql")
+        if not isinstance(created_at, (int, float)) or not isinstance(sql, str):
+            return None
+        if time.time() - float(created_at) > self.ttl_minutes * 60:
+            return None
+        return sql
+
+    def delete(self, *, question: str, schema_version: str | None) -> None:
+        entries = self._entries()
+        key = _cache_key(question, schema_version)
+        if key not in entries:
+            return
+        del entries[key]
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(entries, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    def set(self, *, question: str, schema_version: str | None, sql: str) -> None:
+        if self.ttl_minutes <= 0:
+            return
+        entries = self._entries()
+        entries[_cache_key(question, schema_version)] = {
+            "questionKey": _normalize_question(question),
+            "schemaVersion": schema_version,
+            "sql": sql,
+            "createdAt": time.time(),
+        }
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(entries, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    def _entries(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return {}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            return {}
+        return data if isinstance(data, dict) else {}
+
+
+def _cache_key(question: str, schema_version: str | None) -> str:
+    raw = f"{SQL_GENERATION_CACHE_VERSION}:{schema_version or ''}:{_normalize_question(question)}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _normalize_question(question: str) -> str:
+    return re.sub(r"\s+", "", question.strip().lower())

package/src/octopus_sponge_skill/result_renderer.py

@@ -2,10 +2,12 @@ from __future__ import annotations
 
 import html
 import json
+import re
 from typing import Any
 
 
-SUPPORTED_RESULT_FORMATS = {"text", "yaml", "md", "markdown", "html"}
+SUPPORTED_RESULT_FORMATS = {"text", "json", "yaml", "md", "markdown", "html"}
+RESULT_ROW_DISPLAY_LIMIT = 500
 
 
 def normalize_result_format(question: str, result_format: str | None = None) -> str:
@@ -15,12 +17,16 @@ def normalize_result_format(question: str, result_format: str | None = None) ->
             raise ValueError(f"Unsupported resultFormat: {result_format}")
         return "markdown" if normalized == "md" else normalized
     lowered = question.lower()
+    if "json" in lowered:
+        return "json"
     if "yaml" in lowered:
         return "yaml"
     if "html" in lowered:
         return "html"
     if "markdown" in lowered or " md" in lowered or "表格" in question:
         return "markdown"
+    if _is_match_effect_report_question(question):
+        return "markdown"
     return "text"
 
 
@@ -33,10 +39,14 @@ def render_result(question: str, result: dict[str, Any], result_format: str | No
     columns = result.get("columns", [])
     if row_count == 0:
         return _format_empty(output_format)
-    sample = rows[:5] if isinstance(rows, list) else []
+    sample = rows[:RESULT_ROW_DISPLAY_LIMIT] if isinstance(rows, list) else []
+    if output_format == "json":
+        return _render_json(row_count, bool(result.get("limited", False)), sample)
     if output_format == "yaml":
         return _render_yaml(question, row_count, bool(result.get("limited", False)), sample)
     if output_format == "markdown":
+        if _is_match_effect_report_question(question):
+            return _render_match_effect_report(question, row_count, bool(result.get("limited", False)), sample, columns)
         return _render_markdown(question, row_count, bool(result.get("limited", False)), sample, columns)
     if output_format == "html":
         return _render_html(question, row_count, bool(result.get("limited", False)), sample, columns)
@@ -44,6 +54,8 @@ def render_result(question: str, result: dict[str, Any], result_format: str | No
 
 
 def _format_failure(output_format: str) -> str:
+    if output_format == "json":
+        return json.dumps({"success": False, "message": "查询失败。"}, ensure_ascii=False, indent=2) + "\n"
     if output_format == "yaml":
         return "success: false\nmessage: 查询失败。\n"
     if output_format == "markdown":
@@ -54,6 +66,12 @@ def _format_failure(output_format: str) -> str:
 
 
 def _format_empty(output_format: str) -> str:
+    if output_format == "json":
+        return json.dumps(
+            {"success": True, "rowCount": 0, "rows": [], "message": "没有查询到符合条件的数据。"},
+            ensure_ascii=False,
+            indent=2,
+        ) + "\n"
     if output_format == "yaml":
         return "success: true\nrowCount: 0\nrows: []\nmessage: 没有查询到符合条件的数据。\n"
     if output_format == "markdown":
@@ -63,6 +81,104 @@ def _format_empty(output_format: str) -> str:
     return "没有查询到符合条件的数据。"
 
 
+def _is_match_effect_report_question(question: str) -> bool:
+    return bool(
+        ("匹配效果" in question or "分析报告" in question)
+        and "岗位" in question
+        and any(term in question for term in ("候选人", "报名", "入职", "上岗"))
+    )
+
+
+def _render_match_effect_report(
+    question: str,
+    row_count: int,
+    limited: bool,
+    rows: list[Any],
+    columns: Any,
+) -> str:
+    table_columns = _column_names(columns, rows)
+    period = _extract_report_period(question)
+    lines = [
+        f"# {period}岗位与候选人匹配效果分析报告",
+        "",
+        "## 完整分析报告",
+        "",
+        f"数据范围：{period}；维度：品牌、项目、城市；口径：入职按上岗结果近似统计。",
+        f"返回 {row_count} 行。limited: {str(limited).lower()}",
+    ]
+    if table_columns:
+        lines.extend(["", "|" + "|".join(_escape_markdown(column) for column in table_columns) + "|"])
+        lines.append("|" + "|".join("---" for _ in table_columns) + "|")
+        for row in rows:
+            lines.append("|" + "|".join(_escape_markdown(_cell_value(row, column)) for column in table_columns) + "|")
+    else:
+        lines.extend(["", "```json", json.dumps(rows, ensure_ascii=False, indent=2), "```"])
+    lines.extend(["", "## 总结关键发现", ""])
+    findings = _match_effect_findings(rows)
+    lines.extend(findings or ["- 暂未发现明显异常组合。"])
+    return "\n".join(lines)
+
+
+def _extract_report_period(question: str) -> str:
+    relative_month = re.search(r"(今年|去年|前年|明年|后年)\s*(\d{1,2})\s*月", question)
+    if relative_month is not None:
+        return f"{relative_month.group(1)}{int(relative_month.group(2))}月"
+    explicit_month = re.search(r"(20\d{2})\s*年\s*(\d{1,2})\s*月", question)
+    if explicit_month is not None:
+        return f"{explicit_month.group(1)}年{int(explicit_month.group(2))}月"
+    return "本期"
+
+
+def _match_effect_findings(rows: list[Any]) -> list[str]:
+    if not rows:
+        return []
+    buckets = {
+        "报名多但入职少": [],
+        "在招多但报名少": [],
+        "候选人多但岗位少": [],
+    }
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        issue = str(row.get("问题类型", ""))
+        label = _dimension_label(row)
+        for bucket in buckets:
+            if bucket in issue:
+                buckets[bucket].append(label)
+    findings: list[str] = []
+    for bucket, labels in buckets.items():
+        if labels:
+            findings.append(f"- {bucket}：{_join_limited(labels)}。")
+    return findings
+
+
+def _dimension_label(row: dict[str, Any]) -> str:
+    parts = [
+        str(row.get("品牌名称") or "未知品牌"),
+        str(row.get("项目名称") or "未知项目"),
+        str(row.get("城市名称") or "未知城市"),
+    ]
+    return " / ".join(parts)
+
+
+def _join_limited(values: list[str], limit: int = 3) -> str:
+    visible = values[:limit]
+    suffix = f"等 {len(values)} 项" if len(values) > limit else ""
+    return "、".join(visible + ([suffix] if suffix else []))
+
+
+def _render_json(row_count: int, limited: bool, rows: list[Any]) -> str:
+    return json.dumps(
+        {
+            "rowCount": row_count,
+            "limited": limited,
+            "rows": rows,
+        },
+        ensure_ascii=False,
+        indent=2,
+    ) + "\n"
+
+
 def _render_yaml(question: str, row_count: int, limited: bool, rows: list[Any]) -> str:
     lines = [
         f"rowCount: {row_count}",