@roll-agent/octopus-agent 0.0.1 → 0.0.2

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}",

package/src/octopus_sponge_skill/roll_server.py

@@ -73,7 +73,7 @@ def tool_definitions() -> list[Json]:
     return [
         {
             "name": "diagnostic_status",
-            "description": "检查 Octopus Sponge Agent 配置、缓存和本地持久化状态",
+            "description": "调试专用：检查 Octopus Sponge Agent 配置、缓存和本地持久化状态。普通业务查询不要先调用本工具，直接调用 query_sponge。",
             "inputSchema": {
                 "type": "object",
                 "properties": {},
@@ -82,7 +82,7 @@ def tool_definitions() -> list[Json]:
         },
         {
             "name": "refresh_schema",
-            "description": "调用 Sponge MCP Server 刷新本地 Schema Cache（表结构缓存）",
+            "description": "调试/运维专用：手动刷新本地 Schema Cache（表结构缓存）。只有用户明确要求刷新 schema 时才调用；普通业务查询不要先调用本工具。",
             "inputSchema": {
                 "type": "object",
                 "required": ["traceId"],
@@ -90,10 +90,6 @@ def tool_definitions() -> list[Json]:
                     "traceId": {
                         "type": "string",
                         "description": "调用链路 ID，必填，会原样传给 Sponge get_schema",
-                    },
-                    "refreshReason": {
-                        "type": "string",
-                        "description": "刷新原因，默认 manual（人工触发）",
                     }
                 },
                 "additionalProperties": False,
@@ -101,18 +97,28 @@ def tool_definitions() -> list[Json]:
         },
         {
             "name": "query_sponge",
-            "description": "把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行",
+            "description": "业务查询唯一入口：把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。上层模型必须直接调用本工具；不要先调用 diagnostic_status 或 refresh_schema；不要自行生成 SQL；不要解释 schema；不要要求用户提供 SQL；不要改写用户问题。originalQuestion 必须传用户原始话术；如果 question 被上层改写，Agent 会忽略改写版并优先用 originalQuestion 生成 SQL、审计和缓存。对“匹配效果/分析报告/报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，必须只调用一次 query_sponge 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。工具返回后应把 answer 原文复制到最终答复正文完整展示，不要只放在折叠步骤、思考过程或工具调用详情中；如果 answer 已包含分析报告，必须先展示完整报告，再展示总结关键发现；不要自行汇总替代 answer，不要追加“是否继续查询/是否需要更多字段/我可以继续帮你”等引导。默认 fastMode=true、finalAnswerOnly=true，会优先使用缓存和规则模板。",
             "inputSchema": {
                 "type": "object",
-                "required": ["question", "userId"],
+                "required": ["question", "originalQuestion"],
                 "properties": {
-                    "question": {"type": "string", "description": "用户自然语言问题"},
-                    "userId": {"type": "integer", "description": "当前登录用户对应的 Duliri userId"},
+                    "question": {"type": "string", "description": "当前要处理的问题；兼容旧调用方"},
+                    "originalQuestion": {
+                        "type": "string",
+                        "description": "必填，用户原始话术。上层不得摘要、翻译、拆分或改写；即使 question 与原话一致也要原样传入。",
+                    },
+                    "fastMode": {
+                        "type": "boolean",
+                        "description": "是否启用快路径；默认 true。true 时优先使用本地 schema 缓存、SQL 缓存和规则模板，失败才走 LLM；false 时优先让 LLM 生成 SQL。",
+                    },
+                    "finalAnswerOnly": {
+                        "type": "boolean",
+                        "description": "是否只返回最终业务答案；默认 true。普通上层 Agent 应保持 true，并在最终回复正文原文复制 answer，不要只放在折叠步骤里，不要追加后续引导。includeSql=true 的显式调试请求仍会返回 SQL 调试信息。",
+                    },
                     "sessionId": {"type": "string", "description": "可选会话 ID"},
-                    "deviceId": {"type": "string", "description": "可选设备 ID"},
                     "resultFormat": {
                         "type": "string",
-                        "enum": ["text", "yaml", "md", "markdown", "html"],
+                        "enum": ["text", "json", "yaml", "md", "markdown", "html"],
                         "description": "结果输出格式；不传则根据问题自动识别",
                     },
                     "includeSql": {
@@ -142,18 +148,18 @@ def call_tool(
                 _refresh_schema(
                     agent,
                     trace_id=_required_string(arguments, "traceId"),
-                    refresh_reason=str(arguments.get("refreshReason") or "manual"),
                 )
             )
         if tool_name == "query_sponge":
             agent = _make_agent(agent_factory)
             answer_kwargs = {
                 "question": _required_string(arguments, "question"),
-                "user_id": _required_int(arguments, "userId"),
+                "original_question": _required_string(arguments, "originalQuestion"),
+                "fast_mode": _optional_bool(arguments, "fastMode", default=True),
                 "session_id": arguments.get("sessionId"),
-                "device_id": arguments.get("deviceId"),
                 "result_format": arguments.get("resultFormat"),
             }
+            final_answer_only = _optional_bool(arguments, "finalAnswerOnly", default=True)
             if sampler is not None:
                 answer_kwargs["sampler"] = sampler
             query_result = agent.query(**answer_kwargs)
@@ -202,23 +208,16 @@ def _diagnostic_status(config: AppConfig) -> Json:
     }
 
 
-def _refresh_schema(agent: SpongeAgent, *, trace_id: str, refresh_reason: str) -> Json:
+def _refresh_schema(agent: SpongeAgent, *, trace_id: str) -> Json:
     cached_schema = agent.schema_cache.load()
     current_version = str(cached_schema.get("schemaVersion")) if cached_schema and cached_schema.get("schemaVersion") else None
     schema = agent.mcp_client.get_schema(
         trace_id=trace_id,
         schema_version=current_version,
-        refresh_reason=refresh_reason,
     )
     response_changed = schema.get("changed")
     if schema.get("changed") is False and cached_schema is not None:
         schema = cached_schema
-    elif schema.get("changed") is False and cached_schema is None:
-        schema = agent.mcp_client.get_schema(
-            trace_id=trace_id,
-            schema_version=None,
-            refresh_reason=refresh_reason,
-        )
     if "tables" in schema:
         agent.schema_cache.save(schema)
     schema_source = "cache" if response_changed is False and cached_schema is not None else "response"
@@ -227,7 +226,6 @@ def _refresh_schema(agent: SpongeAgent, *, trace_id: str, refresh_reason: str) -
             "traceId": trace_id,
             "tool": "get_schema",
             "schemaVersion": schema.get("schemaVersion"),
-            "refreshReason": refresh_reason,
             "changed": response_changed,
         }
     )
@@ -236,7 +234,6 @@ def _refresh_schema(agent: SpongeAgent, *, trace_id: str, refresh_reason: str) -
         "request": {
             "traceId": trace_id,
             "schemaVersion": current_version,
-            "refreshReason": refresh_reason,
         },
         "schema": {
             "schemaVersion": schema.get("schemaVersion"),
@@ -264,6 +261,24 @@ def _required_string(arguments: Json, key: str) -> str:
     return value
 
 
+def _optional_string(arguments: Json, key: str) -> str | None:
+    value = arguments.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{key} must be a string")
+    return value or None
+
+
+def _optional_bool(arguments: Json, key: str, *, default: bool) -> bool:
+    value = arguments.get(key)
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        raise ValueError(f"{key} must be a boolean")
+    return value
+
+
 def _required_int(arguments: Json, key: str) -> int:
     value = arguments.get(key)
     if not isinstance(value, int):