@roll-agent/octopus-agent 0.0.1 → 0.0.4

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

package/src/octopus_sponge_skill/schema_cache.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -41,3 +42,8 @@ class SchemaCache:
         version = schema.get("schemaVersion")
         return str(version) if version is not None else None
 
+    def is_fresh(self, max_age_minutes: int) -> bool:
+        if max_age_minutes <= 0 or not self.path.exists():
+            return False
+        age_seconds = time.time() - self.path.stat().st_mtime
+        return age_seconds <= max_age_minutes * 60

package/src/octopus_sponge_skill/schema_context_retriever.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from typing import Any
 
@@ -13,17 +14,69 @@ class SchemaContext:
     examples: list[dict[str, Any]]
 
 
+LOCATION_RECRUITING_TABLES = (
+    "province",
+    "city",
+    "region",
+    "job_basic_info",
+    "job_address",
+    "job_store",
+    "store",
+)
+
+WORK_ORDER_DETAIL_TABLES = (
+    "mvp_applied_jobs_by_helped_account",
+    "brand",
+    "job_basic_info",
+    "sponge_project",
+)
+
+
 def retrieve_schema_context(schema: dict[str, Any], question: str, *, max_tables: int = 8) -> SchemaContext:
     glossary = _matching_items(schema.get("glossary", []), question, keys=("term", "description"))
     metrics = _matching_items(schema.get("metrics", []), question, keys=("name", "metric", "description", "definition"))
     examples = _matching_items(schema.get("examples", []), question, keys=("question", "description"))
     table_names_from_context = _target_table_names(glossary + metrics + examples)
-    tables = _rank_tables(schema.get("tables", []), question, table_names_from_context)[:max_tables]
+    tables = _select_tables(schema.get("tables", []), question, table_names_from_context, max_tables)
     selected_table_names = {_table_name(table) for table in tables}
     joins = _filter_joins(schema.get("joins", []), selected_table_names)
     return SchemaContext(tables=tables, joins=joins, glossary=glossary, metrics=metrics, examples=examples)
 
 
+def _select_tables(tables: Any, question: str, preferred_names: set[str], max_tables: int) -> list[dict[str, Any]]:
+    ranked = _rank_tables(tables, question, preferred_names)
+    if _needs_work_order_detail_tables(question) and isinstance(tables, list):
+        return _prepend_named_tables(tables, ranked, WORK_ORDER_DETAIL_TABLES, max_tables)
+    if not _needs_location_recruiting_tables(question) or not isinstance(tables, list):
+        return ranked[:max_tables]
+
+    return _prepend_named_tables(tables, ranked, LOCATION_RECRUITING_TABLES, max_tables)
+
+
+def _prepend_named_tables(
+    tables: Any,
+    ranked: list[dict[str, Any]],
+    names: tuple[str, ...],
+    max_tables: int,
+) -> list[dict[str, Any]]:
+    by_name = {_table_name(table): table for table in tables if isinstance(table, dict)}
+    selected: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for name in names:
+        table = by_name.get(name)
+        if table is not None:
+            selected.append(table)
+            seen.add(name)
+    for table in ranked:
+        name = _table_name(table)
+        if name not in seen:
+            selected.append(table)
+            seen.add(name)
+        if len(selected) >= max_tables:
+            break
+    return selected[:max_tables]
+
+
 def _rank_tables(tables: Any, question: str, preferred_names: set[str]) -> list[dict[str, Any]]:
     if not isinstance(tables, list):
         return []
@@ -33,6 +86,8 @@ def _rank_tables(tables: Any, question: str, preferred_names: set[str]) -> list[
             continue
         name = _table_name(table)
         score = 5 if name in preferred_names else 0
+        if _needs_work_order_detail_tables(question) and name in WORK_ORDER_DETAIL_TABLES:
+            score += 10
         text = " ".join(
             [
                 name,
@@ -53,14 +108,29 @@ def _matching_items(items: Any, question: str, *, keys: tuple[str, ...]) -> list
     if not isinstance(items, list):
         return []
     tokens = _question_tokens(question)
-    matches: list[dict[str, Any]] = []
+    matches: list[tuple[int, dict[str, Any]]] = []
     for item in items:
         if not isinstance(item, dict):
             continue
-        text = " ".join(str(item.get(key) or "") for key in keys).lower()
-        if any(token and token in text for token in tokens):
-            matches.append(item)
-    return matches[:8]
+        text = " ".join(str(item.get(key) or "") for key in keys + ("sql",)).lower()
+        score = sum(1 for token in tokens if token and token in text)
+        if _needs_work_order_detail_tables(question):
+            for term in (
+                "mvp_applied_jobs_by_helped_account",
+                "work_order_status",
+                "current_helper_status_id",
+                "job_basic_info.job_id",
+                "报名",
+                "工单",
+                "候选人状态",
+                "面试成功",
+            ):
+                if term.lower() in text:
+                    score += 5
+        if score > 0:
+            matches.append((score, item))
+    matches.sort(key=lambda match: match[0], reverse=True)
+    return [item for _, item in matches[:8]]
 
 
 def _target_table_names(items: list[dict[str, Any]]) -> set[str]:
@@ -70,6 +140,9 @@ def _target_table_names(items: list[dict[str, Any]]) -> set[str]:
             value = item.get(key)
             if isinstance(value, list):
                 names.update(str(name) for name in value)
+        sql = item.get("sql")
+        if isinstance(sql, str):
+            names.update(referenced_table for referenced_table in _referenced_tables(sql))
         targets = item.get("targets")
         if isinstance(targets, list):
             for target in targets:
@@ -108,8 +181,40 @@ def _question_tokens(question: str) -> list[str]:
     lowered = question.lower()
     tokens = [lowered]
     tokens.extend(part for part in lowered.replace("_", " ").replace("-", " ").split() if part)
-    for word in ("品牌", "项目", "岗位", "门店", "招聘", "在招", "数量", "列表"):
+    for word in (
+        "品牌",
+        "项目",
+        "岗位",
+        "门店",
+        "招聘",
+        "在招",
+        "数量",
+        "列表",
+        "报名",
+        "报名情况",
+        "报名工单",
+        "工单",
+        "候选人",
+        "候选人状态",
+        "面试成功",
+        "进行中",
+        "姓名",
+    ):
         if word in question:
             tokens.append(word)
     return list(dict.fromkeys(tokens))
 
+
+def _referenced_tables(sql: str) -> set[str]:
+    return set(match.group(1) for match in re.finditer(r"\b(?:from|join)\s+([a-zA-Z_][a-zA-Z0-9_]*)\b", sql, re.IGNORECASE))
+
+
+def _needs_location_recruiting_tables(question: str) -> bool:
+    return any(word in question for word in ("岗位", "门店", "招聘", "在招"))
+
+
+def _needs_work_order_detail_tables(question: str) -> bool:
+    return bool(
+        any(word in question for word in ("报名", "工单", "候选人"))
+        and any(word in question for word in ("姓名", "岗位", "项目", "候选人状态"))
+    )