@roll-agent/octopus-agent 0.0.11 → 0.1.1

package/src/octopus_skill/octopus_run.py

@@ -3,14 +3,13 @@ from __future__ import annotations
 import json
 import re
 import sys
-import time
 from dataclasses import asdict, is_dataclass
-from pathlib import Path
 from typing import Any, Callable
 
 from . import __version__
-from .agent import SpongeAgent
+from .agent import SpongeAgent, ensure_query_plan_summary_answer
 from .config import AppConfig, load_config_from_env
+from .result_renderer import RESULT_ROW_DISPLAY_LIMIT, normalize_result_format, render_result
 from .schema_cache import SchemaCacheError
 
 SERVER_NAME = "octopus-agent"
@@ -20,10 +19,6 @@ PROTOCOL_VERSION = "2024-11-05"
 Json = dict[str, Any]
 AgentFactory = Callable[[], SpongeAgent]
 SamplerFactory = Callable[[str, str], str]
-_DEFAULT_CLARIFICATION_SESSION = "__default__"
-_PENDING_CLARIFICATIONS: dict[str, Json] = {}
-_CLARIFICATION_CACHE_PATH = Path.cwd() / "data/sponge-clarification-cache.json"
-_CLARIFICATION_CACHE_TTL_SECONDS = 10 * 60
 
 
 def main() -> None:
@@ -31,7 +26,12 @@ def main() -> None:
 
 
 def serve_stdio() -> None:
-    session = StdioSession(sys.stdin.buffer, sys.stdout.buffer)
+    config = load_config_from_env()
+    session = StdioSession(
+        sys.stdin.buffer,
+        sys.stdout.buffer,
+        max_tokens=config.sampling.max_tokens,
+    )
     while True:
         message = session.read_message()
         if message is None:
@@ -80,7 +80,7 @@ def tool_definitions() -> list[Json]:
     return [
         {
             "name": "diagnostic_status",
-            "description": "调试专用：检查丸子Agent（Octopus Agent）配置、缓存和本地持久化状态。普通业务查询不要先调用本工具，直接调用 query_sponge。",
+            "description": "调试专用：检查丸子Agent（Octopus Agent）配置、缓存和本地持久化状态。用户只是说使用、启动、检查、看看丸子Agent，或确认 Agent 是否可用时，只调用本工具并在返回状态后停止，不得主动调用 query_sponge 或编造示例业务问题。普通业务查询不要先调用本工具，直接调用 query_sponge。",
             "inputSchema": {
                 "type": "object",
                 "properties": {},
@@ -104,7 +104,7 @@ def tool_definitions() -> list[Json]:
         },
         {
             "name": "query_sponge",
-            "description": "业务查询唯一入口：把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。本工具内部第一步会检查本地 schemaVersion，并调用 Sponge get_schema 按需刷新 schema cache；普通业务查询不得额外调用 refresh_schema。上层模型必须直接调用本工具；不要先调用 diagnostic_status 或 refresh_schema；query_sponge 返回“目前不支持该查询”后也不要自行 retry fastMode=false 或再调用 refresh_schema，除非用户明确要求调试；不要自行生成 SQL；不要解释 schema；不要要求用户提供 SQL；不要改写用户问题。originalQuestion 必须传用户原始话术；如果 question 被上层改写，Agent 会忽略改写版并优先用 originalQuestion 生成 SQL 和审计。对“匹配效果/分析报告/报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，必须只调用一次 query_sponge 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。工具返回后必须把 content[0].text 或 structuredContent.answer 原文作为最终用户可见答复完整展示，最终消息必须直接包含完整业务答案；不要只放在折叠步骤、思考过程、工具详情或可折叠步骤里，不要自行改写成摘要；finalAnswerOnly=true（默认）时只能使用 structuredContent.answer 作为最终回复，不得改写、删减或追加内容；如果 structuredContent.needsClarification=true，必须立即停止，用户未确认前不得再次调用 query_sponge，不得自行选择品牌/项目/地点候选，不得把品牌+地点拼成项目名，必须原样展示 structuredContent.answer 并等待用户确认；用户确认品牌/项目后，不要重新发现工具，不要调用 diagnostic_status 或 refresh_schema，不要解释 schema，不要自行判断“schema 不支持项目维度”，必须直接再次调用 query_sponge 并传 clarificationSelection；clarificationSelection 必须包含 baseQuestion、entityType、entityId、entityName，优先从 structuredContent.clarificationContext 构造，避免依赖进程内存。如果 answer 已包含分析报告，必须先展示完整报告，再展示总结关键发现；不要自行汇总替代 answer，不要追加“是否继续查询/是否需要更多字段/我可以继续帮你”等引导。如果 answer 开头包含“已识别并用于筛选：…”这类实体识别说明（说明系统已把口语/简称/错字归一为标准品牌、项目、地点并据此过滤），必须在最终回复中原样保留并展示这条说明，不得删除或改写，便于用户确认筛选口径。默认 fastMode=true、finalAnswerOnly=true，structuredContent.responseMode=verbatim，便于上层 Agent 直接把 answer 展示给用户；复杂查询会使用 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 会返回每一步状态，失败时包含实际 error 原因。默认 fastMode=true、finalAnswerOnly=true，structuredContent.responseMode=verbatim；复杂查询会使用 schema context 和 LLM 生成。",
             "inputSchema": {
                 "type": "object",
                 "required": ["question", "originalQuestion"],
@@ -120,7 +120,7 @@ def tool_definitions() -> list[Json]:
                     },
                     "finalAnswerOnly": {
                         "type": "boolean",
-                        "description": "是否只返回最终业务答案；默认 true。true 时 content 与 structuredContent.answer 均为 verbatim 业务答复，上层 Agent 必须原样展示给用户，不要只放在折叠步骤里，不要改写成摘要或追加后续引导。includeSql=true 的显式调试请求仍会返回 SQL 调试信息。",
+                        "description": "是否只返回最终业务答案；默认 true。true 时 content 与 structuredContent.answer 均为三段式 verbatim 答复：1.查询实体；2.筛选条件；3.查询结果。上层 Agent 必须原样展示给用户，不要只放在折叠步骤里，不要改写成摘要、截断表格或追加后续引导。includeSql=true 的显式调试请求仍会返回 SQL 调试信息。",
                     },
                     "sessionId": {"type": "string", "description": "可选会话 ID"},
                     "resultFormat": {
@@ -132,31 +132,6 @@ def tool_definitions() -> list[Json]:
                         "type": "boolean",
                         "description": "是否在回参中包含 generatedSql、normalizedSql、repairedSql 等调试信息",
                     },
-                    "clarificationSelection": {
-                        "type": "object",
-                        "required": ["entityType", "entityId"],
-                        "description": "用户已确认候选项时传入的结构化选择。未经用户确认不得传；无状态调用必须同时传 baseQuestion 和 entityName。",
-                        "properties": {
-                            "baseQuestion": {
-                                "type": "string",
-                                "description": "原始业务问题，优先使用上一轮 structuredContent.clarificationContext.baseQuestion",
-                            },
-                            "entityType": {
-                                "type": "string",
-                                "enum": ["brand", "project"],
-                                "description": "实体类型：brand=品牌，project=项目",
-                            },
-                            "entityId": {
-                                "type": ["integer", "string"],
-                                "description": "候选实体 ID，必须来自上一轮 clarificationPayload",
-                            },
-                            "entityName": {
-                                "type": "string",
-                                "description": "候选实体名称，必须来自上一轮 clarificationPayload",
-                            },
-                        },
-                        "additionalProperties": False,
-                    },
                 },
                 "additionalProperties": False,
             },
@@ -183,22 +158,16 @@ def call_tool(
                 )
             )
         if tool_name == "query_sponge":
-            agent = _make_agent(agent_factory)
             question = _required_string(arguments, "question")
             original_question = _required_string(arguments, "originalQuestion")
             session_id = arguments.get("sessionId")
-            resolved_question = _resolve_pending_clarification(
+            blocked_reason = _blocked_query_call_reason(
                 question=question,
                 original_question=original_question,
-                session_id=session_id,
-                clarification_selection=arguments.get("clarificationSelection"),
             )
-            if resolved_question is not None:
-                question = resolved_question
-                original_question = resolved_question
-                _forget_pending_clarification(session_id)
-            elif not _is_clarification_reply(original_question):
-                _forget_pending_clarification(session_id)
+            if blocked_reason is not None:
+                return _tool_blocked_query(blocked_reason)
+            agent = _make_agent(agent_factory)
             answer_kwargs = {
                 "question": question,
                 "original_question": original_question,
@@ -210,15 +179,10 @@ def call_tool(
             if sampler is not None:
                 answer_kwargs["sampler"] = sampler
             query_result = agent.query(**answer_kwargs)
-            _sync_pending_clarification(
-                query_result,
-                question=question,
-                original_question=original_question,
-                session_id=session_id,
-            )
             base_question = original_question or question
             if arguments.get("includeSql") is True:
                 payload = _query_result_payload(query_result, include_sql=True, base_question=base_question)
+                payload["answer"] = _user_visible_answer(query_result, base_question=base_question)
                 return _tool_json(payload, structured_content=payload)
             if final_answer_only:
                 return _tool_final_answer(query_result, base_question=base_question)
@@ -254,22 +218,23 @@ def _diagnostic_status(config: AppConfig) -> Json:
             "enabled": config.audit.enabled,
             "logPath": str(config.audit.log_path),
         },
+        "sampling": {
+            "maxTokens": config.sampling.max_tokens,
+        },
         "binding": _binding_status(config),
     }
 
 
 def _binding_status(config: AppConfig) -> Json:
     binding = config.binding
-    dictionary = config.dictionary
     return {
-        "configured": binding is not None,
+        "configured": False,
+        "mode": "disabled",
+        "entitySource": "schema",
+        "dictionaryPersisted": False,
         "shadowMode": bool(binding.shadow_mode) if binding is not None else None,
         "enabledEntityTypes": list(binding.enabled_entity_types) if binding is not None else [],
         "minFuzzyScore": binding.min_fuzzy_score if binding is not None else None,
-        "dictionaryCachePath": str(dictionary.cache_path) if dictionary is not None else None,
-        "dictionaryCacheExists": dictionary.cache_path.exists() if dictionary is not None else False,
-        "geoAliasPath": str(dictionary.geo_alias_path) if dictionary is not None else None,
-        "geoAliasExists": dictionary.geo_alias_path.exists() if dictionary is not None else False,
     }
 
 
@@ -326,15 +291,6 @@ 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:
@@ -351,230 +307,135 @@ def _required_int(arguments: Json, key: str) -> int:
     return value
 
 
-def _clarification_key(session_id: Any) -> str:
-    if isinstance(session_id, str) and session_id.strip():
-        return session_id
-    return _DEFAULT_CLARIFICATION_SESSION
-
-
-def _forget_pending_clarification(session_id: Any) -> None:
-    _PENDING_CLARIFICATIONS.pop(_clarification_key(session_id), None)
-    _delete_cached_clarification(session_id)
+_PRESERVATION_SIGNAL_PATTERN = re.compile(
+    r"(今天|今日|昨天|昨日|明天|明日|本周|上周|本月|上月|最近\d+天"
+    r"|招满|已招满|在招|上架|下架|新发布|新上架"
+    r"|\d{4}年\d{1,2}月|\d{1,2}月\d{1,2}日"
+    r"|\d+日)"
+)
+_PRESERVATION_SIGNAL_EQUIVALENTS: dict[str, tuple[str, ...]] = {
+    "今天": ("今天", "今日"),
+    "今日": ("今天", "今日"),
+    "昨天": ("昨天", "昨日"),
+    "昨日": ("昨天", "昨日"),
+    "招满": ("招满", "已招满"),
+    "已招满": ("招满", "已招满"),
+}
+_REWRITTEN_SUMMARY_MARKERS = (
+    "相关的统计数据",
+    "相关统计数据",
+    "相关的统计",
+    "查询相关数据",
+    "查询相关统计",
+)
+
+
+def _extract_preservation_signals(text: str) -> list[str]:
+    return list(dict.fromkeys(match.group(0) for match in _PRESERVATION_SIGNAL_PATTERN.finditer(text)))
+
+
+def _signal_preserved(signal: str, text: str) -> bool:
+    candidates = _PRESERVATION_SIGNAL_EQUIVALENTS.get(signal, (signal,))
+    return any(candidate in text for candidate in candidates)
+
+
+def _missing_preservation_signals(*, source: str, target: str) -> list[str]:
+    missing: list[str] = []
+    for signal in _extract_preservation_signals(source):
+        if not _signal_preserved(signal, target):
+            missing.append(signal)
+    return missing
+
+
+def _looks_like_rewritten_summary(text: str) -> bool:
+    normalized = text.strip()
+    if len(normalized) > 40 or _extract_preservation_signals(normalized):
+        return False
+    if not re.search(r"(查询|统计)", normalized):
+        return False
+    return any(marker in normalized for marker in _REWRITTEN_SUMMARY_MARKERS)
 
 
-def _load_pending_clarification(session_id: Any) -> Json | None:
-    key = _clarification_key(session_id)
-    cached = _read_clarification_cache().get(key)
-    if not isinstance(cached, dict):
-        return None
-    updated_at = cached.get("updatedAt")
-    if not isinstance(updated_at, (int, float)) or time.time() - float(updated_at) > _CLARIFICATION_CACHE_TTL_SECONDS:
-        _delete_cached_clarification(session_id)
-        return None
-    question = cached.get("question")
-    payload = cached.get("payload")
-    if not isinstance(question, str) or not isinstance(payload, dict):
-        _delete_cached_clarification(session_id)
+def _blocked_original_question_reason(*, question: str, original_question: str) -> str | None:
+    q = question.strip()
+    oq = original_question.strip()
+    if not q or not oq:
         return None
-    pending = {"question": question, "payload": payload}
-    _PENDING_CLARIFICATIONS[key] = pending
-    return pending
-
-
-def _save_pending_clarification(session_id: Any, pending: Json) -> None:
-    question = pending.get("question")
-    payload = pending.get("payload")
-    if not isinstance(question, str) or not isinstance(payload, dict):
-        return
-    items = _read_clarification_cache()
-    items[_clarification_key(session_id)] = {
-        "updatedAt": time.time(),
-        "question": question,
-        "payload": payload,
-    }
-    _write_clarification_cache(items)
-
-
-def _delete_cached_clarification(session_id: Any) -> None:
-    items = _read_clarification_cache()
-    key = _clarification_key(session_id)
-    if key not in items:
-        return
-    items.pop(key, None)
-    _write_clarification_cache(items)
-
-
-def _read_clarification_cache() -> dict[str, Json]:
-    try:
-        if not _CLARIFICATION_CACHE_PATH.exists():
-            return {}
-        data = json.loads(_CLARIFICATION_CACHE_PATH.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return {}
-    if not isinstance(data, dict):
-        return {}
-    items = data.get("items")
-    return items if isinstance(items, dict) else {}
-
-
-def _write_clarification_cache(items: dict[str, Json]) -> None:
-    try:
-        if items:
-            _CLARIFICATION_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
-            _CLARIFICATION_CACHE_PATH.write_text(
-                json.dumps({"items": items}, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
-                encoding="utf-8",
+    if q == oq and _looks_like_rewritten_summary(oq):
+        return (
+            "originalQuestion 疑似上层摘要改写（例如“查询岗位相关的统计数据”），"
+            "请原样传入用户原始话术，不要摘要、翻译或改写。"
+        )
+    if q != oq:
+        missing = _missing_preservation_signals(source=q, target=oq)
+        if missing:
+            joined = "、".join(missing)
+            return (
+                f"originalQuestion 未保留 question 中的关键语义（{joined}）。"
+                "originalQuestion 必须传用户原始话术，上层不得摘要、翻译或改写。"
             )
-        elif _CLARIFICATION_CACHE_PATH.exists():
-            _CLARIFICATION_CACHE_PATH.unlink()
-    except OSError:
-        return
+    return None
 
 
-def _sync_pending_clarification(
-    query_result: Any,
-    *,
-    question: str,
-    original_question: str,
-    session_id: Any,
-) -> None:
-    payload = getattr(query_result, "clarification_payload", None)
-    if (
-        bool(getattr(query_result, "needs_clarification", False))
-        and getattr(query_result, "clarification_type", None) == "entity_resolution"
-        and isinstance(payload, dict)
-        and (payload.get("brands") or payload.get("projects"))
-    ):
-        pending = {
-            "question": original_question or question,
-            "payload": _jsonable(payload),
-        }
-        _PENDING_CLARIFICATIONS[_clarification_key(session_id)] = pending
-        _save_pending_clarification(session_id, pending)
-        return
-    _forget_pending_clarification(session_id)
+def _blocked_query_call_reason(*, question: str, original_question: str) -> str | None:
+    text = (original_question or question or "").strip()
+    if not text:
+        return "请先输入明确的业务数据查询需求，例如：查询我能看到的品牌列表。"
+    if _is_agent_meta_request(text) and not _has_explicit_business_object(text):
+        return "请先输入明确的业务数据查询需求；检查或测试丸子Agent时只允许调用 diagnostic_status。"
+    rewrite_reason = _blocked_original_question_reason(question=question, original_question=original_question)
+    if rewrite_reason is not None:
+        return rewrite_reason
+    return None
 
 
-def _resolve_pending_clarification(
-    *,
-    question: str,
-    original_question: str,
-    session_id: Any,
-    clarification_selection: Any = None,
-) -> str | None:
-    pending = _PENDING_CLARIFICATIONS.get(_clarification_key(session_id)) or _load_pending_clarification(session_id)
-    if clarification_selection is not None:
-        selected = None
-        if pending is not None:
-            selected = _select_structured_clarification_candidate(clarification_selection, pending.get("payload"))
-        if selected is None:
-            return _stateless_clarification_question(clarification_selection)
-    else:
-        text = original_question or question
-        if not _is_clarification_reply(text):
-            return None
-        if pending is None:
-            return None
-        selected = _select_clarification_candidate(text, pending.get("payload"))
-    if selected is None:
-        return None
-    entity_type, candidate = selected
-    label = "品牌" if entity_type == "brand" else "项目"
-    name = str(candidate.get("name") or "")
-    entity_id = candidate.get("id")
-    base_question = str(pending.get("question") or question)
-    if entity_id is None:
-        return f"{base_question}，按{label}「{name}」查询"
-    return f"{base_question}，按{label}「{name}」(id: {entity_id})查询"
-
-
-def _is_clarification_reply(text: str) -> bool:
-    cleaned = _normalize_clarification_reply(text)
-    if len(cleaned) > 30:
-        return False
+def _is_agent_meta_request(text: str) -> bool:
     return bool(
-        re.fullmatch(r"(?:按)?(?:品牌|项目)(?:查询)?(?:id)?\d*", cleaned)
-        or re.fullmatch(r"(?:品牌|项目)\d+", cleaned)
+        re.search(r"(丸子|octopus|agent|roll[- ]?core|工具|技能)", text, flags=re.IGNORECASE)
+        and re.search(r"(使用|启动|检查|看看|查看|测试|尝试|状态|健康|诊断|可用|功能)", text)
     )
 
 
-def _normalize_clarification_reply(text: str) -> str:
-    return re.sub(r"[\s:：,，。;；()（）「」“”\"'《》【】]+", "", text or "").lower()
-
-
-def _select_clarification_candidate(text: str, payload: Any) -> tuple[str, Json] | None:
-    if not isinstance(payload, dict):
-        return None
-    cleaned = _normalize_clarification_reply(text)
-    wants_brand = "品牌" in cleaned
-    wants_project = "项目" in cleaned
-    if wants_brand == wants_project:
-        return None
-    entity_type = "brand" if wants_brand else "project"
-    candidates = payload.get("brands" if entity_type == "brand" else "projects")
-    if not isinstance(candidates, list) or not candidates:
-        return None
-    id_match = re.search(r"(?<!\d)(\d+)(?!\d)", cleaned)
-    if id_match is not None:
-        wanted_id = id_match.group(1)
-        for candidate in candidates:
-            if isinstance(candidate, dict) and str(candidate.get("id")) == wanted_id:
-                return entity_type, candidate
-        return None
-    for candidate in candidates:
-        if isinstance(candidate, dict):
-            return entity_type, candidate
-    return None
-
-
-def _select_structured_clarification_candidate(selection: Any, payload: Any) -> tuple[str, Json] | None:
-    if not isinstance(selection, dict):
-        raise ValueError("clarificationSelection must be an object")
-    if not isinstance(payload, dict):
-        return None
-    entity_type = selection.get("entityType")
-    if entity_type not in {"brand", "project"}:
-        raise ValueError("clarificationSelection.entityType must be brand or project")
-    if "entityId" not in selection:
-        raise ValueError("clarificationSelection.entityId is required")
-    candidates = payload.get("brands" if entity_type == "brand" else "projects")
-    if not isinstance(candidates, list) or not candidates:
-        return None
-    wanted_id = str(selection.get("entityId"))
-    for candidate in candidates:
-        if isinstance(candidate, dict) and str(candidate.get("id")) == wanted_id:
-            return entity_type, candidate
-    return None
-
-
-def _stateless_clarification_question(selection: Any) -> str:
-    if not isinstance(selection, dict):
-        raise ValueError("clarificationSelection must be an object")
-    entity_type = selection.get("entityType")
-    if entity_type not in {"brand", "project"}:
-        raise ValueError("clarificationSelection.entityType must be brand or project")
-    if "entityId" not in selection:
-        raise ValueError("clarificationSelection.entityId is required")
-    base_question = _required_selection_string(selection, "baseQuestion")
-    entity_name = _required_selection_string(selection, "entityName")
-    entity_id = selection.get("entityId")
-    label = "品牌" if entity_type == "brand" else "项目"
-    return f"{base_question}，按{label}「{entity_name}」(id: {entity_id})查询"
+def _has_explicit_business_object(text: str) -> bool:
+    return bool(
+        re.search(
+            r"(品牌|项目|岗位|门店|工单|报名|入职|候选人|城市|省份|区域|供应商|员工|薪资|招聘|数据|列表|明细|数量|多少|哪些|有哪些)",
+            text,
+        )
+    )
 
 
-def _required_selection_string(selection: Json, key: str) -> str:
-    value = selection.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"clarificationSelection.{key} is required for stateless clarification")
-    return value.strip()
+def _tool_blocked_query(answer: str) -> Json:
+    payload: Json = {
+        "answer": answer,
+        "needsClarification": False,
+        "clarificationType": None,
+        "clarificationPayload": None,
+        "finalAnswerOnly": True,
+        "responseMode": "verbatim",
+        "blocked": True,
+        "blockedReason": answer,
+    }
+    return {
+        "content": _answer_content(answer),
+        "structuredContent": payload,
+    }
 
 
 def _tool_text(text: str) -> Json:
     return {"content": [{"type": "text", "text": text}]}
 
 
+def _answer_content(answer: str) -> list[Json]:
+    return [
+        {"type": "text", "text": answer},
+    ]
+
+
 def _tool_final_answer(query_result: Any, *, base_question: str | None = None) -> Json:
     payload = _query_result_payload(query_result, base_question=base_question)
+    answer = _user_visible_answer(query_result, base_question=base_question)
+    payload["answer"] = answer
     payload.update(
         {
             "finalAnswerOnly": True,
@@ -582,7 +443,7 @@ def _tool_final_answer(query_result: Any, *, base_question: str | None = None) -
         }
     )
     return {
-        "content": [{"type": "text", "text": str(getattr(query_result, "answer", ""))}],
+        "content": _answer_content(answer),
         "structuredContent": payload,
     }
 
@@ -591,8 +452,10 @@ def _tool_query_answer(query_result: Any, *, final_answer_only: bool, base_quest
     payload = _query_result_payload(query_result, base_question=base_question)
     payload["finalAnswerOnly"] = final_answer_only
     payload["responseMode"] = "verbatim"
+    answer = _user_visible_answer(query_result, base_question=base_question)
+    payload["answer"] = answer
     return {
-        "content": [{"type": "text", "text": str(getattr(query_result, "answer", ""))}],
+        "content": _answer_content(answer),
         "structuredContent": payload,
     }
 
@@ -604,9 +467,12 @@ def _query_result_payload(query_result: Any, *, include_sql: bool = False, base_
         "clarificationType": getattr(query_result, "clarification_type", None),
         "clarificationPayload": getattr(query_result, "clarification_payload", None),
     }
-    clarification_context = _clarification_context(payload["clarificationPayload"], base_question)
-    if clarification_context is not None:
-        payload["clarificationContext"] = clarification_context
+    query_plan = getattr(query_result, "query_plan", None)
+    if isinstance(query_plan, dict):
+        payload["queryPlan"] = _public_query_plan(query_plan)
+    execution_steps = getattr(query_result, "execution_steps", None)
+    if isinstance(execution_steps, list):
+        payload["executionSteps"] = execution_steps
     if include_sql:
         payload.update(
             {
@@ -619,26 +485,140 @@ def _query_result_payload(query_result: Any, *, include_sql: bool = False, base_
     return _jsonable(payload)
 
 
-def _clarification_context(clarification_payload: Any, base_question: str | None) -> Json | None:
-    if not isinstance(clarification_payload, dict) or not base_question:
-        return None
-    brands = clarification_payload.get("brands")
-    projects = clarification_payload.get("projects")
-    if not brands and not projects:
-        return None
+def _public_query_plan(query_plan: dict[str, Any]) -> Json:
     return {
-        "baseQuestion": base_question,
-        "brands": brands or [],
-        "projects": projects or [],
-        "selectionFields": {
-            "baseQuestion": "原始业务问题",
-            "entityType": "实体类型：brand=品牌，project=项目",
-            "entityId": "候选实体 ID",
-            "entityName": "候选实体名称",
-        },
+        key: value
+        for key, value in query_plan.items()
+        if not str(key).startswith("_")
     }
 
 
+def _user_visible_answer(query_result: Any, *, base_question: str | None = None) -> str:
+    answer = str(getattr(query_result, "answer", ""))
+    question = base_question or ""
+    result_format = getattr(query_result, "result_format", None)
+    answer = _ensure_complete_detail_answer(query_result, answer, question, result_format)
+    query_plan = getattr(query_result, "query_plan", None)
+    return _ensure_two_section_answer(answer, question, result_format, query_plan)
+
+
+def _ensure_two_section_answer(
+    answer: str,
+    question: str,
+    result_format: str | None,
+    query_plan: Any,
+) -> str:
+    if isinstance(query_plan, dict) and query_plan:
+        return ensure_query_plan_summary_answer(answer, question, result_format, query_plan)
+    if _answer_has_two_section_structure(answer, question, result_format):
+        return answer
+    return _prepend_missing_query_plan_section(answer, question, result_format)
+
+
+def _answer_has_two_section_structure(answer: str, question: str, result_format: str | None) -> bool:
+    output_format = normalize_result_format(question, result_format)
+    if output_format == "json":
+        try:
+            payload = json.loads(answer)
+        except json.JSONDecodeError:
+            return False
+        return (
+            isinstance(payload, dict)
+            and "查询实体" in payload
+            and "筛选条件" in payload
+            and "查询结果" in payload
+        )
+    if output_format == "yaml":
+        return "查询实体:" in answer and "筛选条件:" in answer and "查询结果:" in answer
+    return "1. 查询实体" in answer and "2. 筛选条件" in answer and "3. 查询结果" in answer
+
+
+def _prepend_missing_query_plan_section(answer: str, question: str, result_format: str | None) -> str:
+    output_format = normalize_result_format(question, result_format)
+    if output_format == "json":
+        try:
+            result_payload: Any = json.loads(answer)
+        except json.JSONDecodeError:
+            result_payload = answer
+        return json.dumps(
+            {
+                "查询实体": ["未返回查询计划"],
+                "筛选条件": ["未返回查询计划"],
+                "查询结果": result_payload,
+            },
+            ensure_ascii=False,
+            indent=2,
+        ) + "\n"
+    if output_format == "yaml":
+        return (
+            "查询实体:\n"
+            "  - 未返回查询计划\n"
+            "筛选条件:\n"
+            "  - 未返回查询计划\n"
+            "查询结果:\n"
+            + "\n".join(f"  {line}" if line else "" for line in answer.rstrip().splitlines())
+            + "\n"
+        )
+    if output_format == "html":
+        return (
+            "<section><p>1. 查询实体：</p><p>未返回查询计划</p></section>"
+            "<section><p>2. 筛选条件：</p><p>未返回查询计划</p></section>"
+            "<section><p>3. 查询结果：</p>"
+            + answer
+            + "</section>"
+        )
+    return (
+        "1. 查询实体：\n"
+        "未返回查询计划\n\n"
+        "2. 筛选条件：\n"
+        "未返回查询计划\n\n"
+        "3. 查询结果：\n"
+        f"{answer}"
+    )
+
+
+def _ensure_complete_detail_answer(
+    query_result: Any,
+    answer: str,
+    question: str,
+    result_format: str | None,
+) -> str:
+    raw_result = getattr(query_result, "raw_result", None)
+    if not isinstance(raw_result, dict):
+        return answer
+    rows = raw_result.get("rows")
+    if not isinstance(rows, list):
+        return answer
+    display_count = min(len(rows), RESULT_ROW_DISPLAY_LIMIT)
+    if display_count <= 0:
+        return answer
+    output_format = normalize_result_format(question, result_format)
+    if output_format in {"text", "markdown"}:
+        if _answer_contains_markdown_table_row(answer, display_count):
+            return answer
+        return render_result(question, raw_result, "markdown")
+    if _answer_contains_display_row(answer, display_count):
+        return answer
+    local_format = result_format or "markdown"
+    return render_result(question, raw_result, local_format)
+
+
+def _answer_contains_markdown_table_row(answer: str, row_number: int) -> bool:
+    escaped = re.escape(str(row_number))
+    return bool(re.search(rf"(?m)^\|\s*{escaped}\s*\|", answer))
+
+
+def _answer_contains_display_row(answer: str, row_number: int) -> bool:
+    escaped = re.escape(str(row_number))
+    patterns = (
+        rf"(?m)^\|\s*{escaped}\s*\|",
+        rf"(?m)^\s*{escaped}[\.\)、]\s+",
+        rf"<td>\s*{escaped}\s*</td>",
+        rf'"序号"\s*:\s*"?{escaped}"?',
+    )
+    return any(re.search(pattern, answer) for pattern in patterns)
+
+
 def _tool_json(data: Any, *, structured_content: Any | None = None) -> Json:
     result = {
         "content": [
@@ -686,11 +666,22 @@ def _error_response(request_id: Any, code: int, message: str, data: Json | None
     return {"jsonrpc": "2.0", "id": request_id, "error": error}
 
 
+def _sampling_user_prompt(system_prompt: str, prompt: str) -> str:
+    system = (system_prompt or "").strip()
+    user = (prompt or "").strip()
+    if not system:
+        return user
+    if not user:
+        return system
+    return f"{system}\n\n---\n\n{user}"
+
+
 class StdioSession:
-    def __init__(self, input_stream: Any, output_stream: Any) -> None:
+    def __init__(self, input_stream: Any, output_stream: Any, *, max_tokens: int = 4096) -> None:
         self.input_stream = input_stream
         self.output_stream = output_stream
         self.next_request_id = 1
+        self.max_tokens = max_tokens
 
     def read_message(self) -> Json | None:
         return _read_message(self.input_stream)
@@ -701,6 +692,9 @@ class StdioSession:
     def sample(self, system_prompt: str, prompt: str) -> str:
         request_id = f"sampling_{self.next_request_id}"
         self.next_request_id += 1
+        # roll sampling handler currently forwards only `messages` to the LLM and
+        # ignores `systemPrompt`; embed system instructions in the user payload.
+        user_prompt = _sampling_user_prompt(system_prompt, prompt)
         self.write_message(
             {
                 "jsonrpc": "2.0",
@@ -708,9 +702,9 @@ class StdioSession:
                 "method": "sampling/createMessage",
                 "params": {
                     "systemPrompt": system_prompt,
-                    "messages": [{"role": "user", "content": {"type": "text", "text": prompt}}],
+                    "messages": [{"role": "user", "content": {"type": "text", "text": user_prompt}}],
                     "temperature": 0,
-                    "maxTokens": 1600,
+                    "maxTokens": self.max_tokens,
                     "includeContext": "none",
                 },
             }