Update agent bridge, directions tool, and add tests

features/mcp/agent_bridge.py

@@ -140,6 +140,141 @@ class MCPAgentBridge:
 
         return enriched
 
+    async def _resolve_coordinate_label(self, lat: Any, lon: Any) -> Optional[str]:
+        """透過 reverse_geocode 將座標轉換為可朗讀的地點名稱。"""
+        try:
+            lat_f = float(lat)
+            lon_f = float(lon)
+        except (TypeError, ValueError):
+            return None
+
+        reverse_tool = self.mcp_server.tools.get("reverse_geocode")
+        if not reverse_tool or not reverse_tool.handler:
+            return None
+
+        try:
+            res = await reverse_tool.handler({"lat": lat_f, "lon": lon_f})
+        except Exception as ge:
+            logger.debug(f"reverse_geocode 失敗: {ge}")
+            return None
+
+        if not isinstance(res, dict):
+            return None
+        if not res.get("success"):
+            return None
+
+        payload = res.get("data") or res
+        label = (
+            payload.get("label")
+            or payload.get("display_name")
+            or ", ".join(
+                part for part in [payload.get("city"), payload.get("admin")] if part
+            )
+        )
+        return label.strip() if label else None
+
+    async def _prepare_route_arguments(self, arguments: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, str]]:
+        """為 directions 工具補齊可讀地點名稱並正規化座標。"""
+        prepared = dict(arguments or {})
+        labels: Dict[str, str] = {}
+
+        def _normalize_coord(value: Any) -> Optional[float]:
+            try:
+                if value is None:
+                    return None
+                return float(value)
+            except (TypeError, ValueError):
+                return None
+
+        for prefix, default_label in (("origin", "起點"), ("dest", "目的地")):
+            lat_key = f"{prefix}_lat"
+            lon_key = f"{prefix}_lon"
+            label_key = f"{prefix}_label"
+
+            lat_val = _normalize_coord(prepared.get(lat_key))
+            lon_val = _normalize_coord(prepared.get(lon_key))
+            if lat_val is not None:
+                prepared[lat_key] = lat_val
+            if lon_val is not None:
+                prepared[lon_key] = lon_val
+
+            label_val = str(prepared.get(label_key) or "").strip()
+            if not label_val and lat_val is not None and lon_val is not None:
+                label_val = await self._resolve_coordinate_label(lat_val, lon_val) or ""
+
+            if not label_val:
+                label_val = default_label
+
+            prepared[label_key] = label_val
+            labels[label_key] = label_val
+
+        return prepared, labels
+
+    @staticmethod
+    def _format_distance(distance_m: Optional[float]) -> str:
+        """將距離換算為人類可讀格式。"""
+        if distance_m is None:
+            return "未知距離"
+        try:
+            distance = float(distance_m)
+        except (TypeError, ValueError):
+            return "未知距離"
+
+        if distance >= 1000:
+            return f"{distance / 1000:.1f} 公里"
+        return f"{round(distance)} 公尺"
+
+    @staticmethod
+    def _format_duration(duration_s: Optional[float]) -> str:
+        """將秒數換算為人類可讀格式。"""
+        if duration_s is None:
+            return "未知時間"
+        try:
+            total_seconds = int(round(float(duration_s)))
+        except (TypeError, ValueError):
+            return "未知時間"
+
+        minutes = total_seconds // 60
+        if minutes < 1:
+            return "不到 1 分鐘"
+
+        hours = minutes // 60
+        remaining_minutes = minutes % 60
+
+        if hours and remaining_minutes:
+            return f"{hours} 小時 {remaining_minutes} 分"
+        if hours:
+            return f"{hours} 小時"
+        return f"{minutes} 分鐘"
+
+    def _build_directions_message(
+        self,
+        tool_data: Dict[str, Any],
+        labels: Dict[str, str],
+    ) -> Tuple[str, Dict[str, Any]]:
+        """依據 directions 工具回傳資料，產出友善訊息與乾淨的 tool_data。"""
+        origin_label = labels.get("origin_label") or tool_data.get("origin_label") or "起點"
+        dest_label = labels.get("dest_label") or tool_data.get("dest_label") or "目的地"
+
+        distance_m = tool_data.get("distance_m")
+        duration_s = tool_data.get("duration_s")
+
+        distance_str = self._format_distance(distance_m)
+        duration_str = self._format_duration(duration_s)
+
+        polite_message = (
+            f"從 {origin_label} 前往 {dest_label} 大約需要 {duration_str}，"
+            f"總距離約 {distance_str}。"
+        )
+
+        sanitized_tool_data = dict(tool_data or {})
+        sanitized_tool_data["origin_label"] = origin_label
+        sanitized_tool_data["dest_label"] = dest_label
+        sanitized_tool_data["distance_readable"] = distance_str
+        sanitized_tool_data["duration_readable"] = duration_str
+
+        return polite_message, sanitized_tool_data
+
     def get_current_time_data(self) -> Dict[str, Any]:
         """
         獲取當前時間數據，用於生成個性化歡迎詞
@@ -598,6 +733,9 @@ class MCPAgentBridge:
             return f"⚠️ 工具 {tool_name} 尚未實作，請稍後再試"
 
         arguments = await self._enrich_arguments_with_env(tool_name, arguments, user_id)
+        route_labels: Dict[str, str] = {}
+        if tool_name == "directions":
+            arguments, route_labels = await self._prepare_route_arguments(arguments)
 
         logger.info(f"🔧 調用 MCP 工具: {tool_name}")
         logger.debug("📋 調用參數: %s", _safe_json(arguments))
@@ -639,6 +777,14 @@ class MCPAgentBridge:
 
                         logger.debug(f"📊 提取的 tool_data: {type(tool_data)} = {tool_data if tool_data is None or isinstance(tool_data, (str, int, bool)) else '<dict/list>'}")
 
+                        if tool_name == "directions":
+                            message, sanitized_tool_data = self._build_directions_message(
+                                tool_data if isinstance(tool_data, dict) else {},
+                                route_labels,
+                            )
+                            content = message
+                            tool_data = sanitized_tool_data
+
                         if self._should_reformat(tool_name, content):
                             logger.info(f"🎨 啟用 AI 格式化: {tool_name}")
                             try:

features/mcp/tools/directions_tool.py

@@ -40,7 +40,9 @@ class DirectionsTool(MCPTool):
             "origin_lon": {"type": "number"},
             "dest_lat": {"type": "number"},
             "dest_lon": {"type": "number"},
-            "mode": {"type": "string", "enum": ["driving-car", "foot-walking", "cycling-regular"], "default": "foot-walking"}
+            "mode": {"type": "string", "enum": ["driving-car", "foot-walking", "cycling-regular"], "default": "foot-walking"},
+            "origin_label": {"type": "string"},
+            "dest_label": {"type": "string"},
         }, required=["origin_lat", "origin_lon", "dest_lat", "dest_lon"])
 
     @classmethod
@@ -49,7 +51,9 @@ class DirectionsTool(MCPTool):
         schema["properties"].update({
             "distance_m": {"type": "number"},
             "duration_s": {"type": "number"},
-            "polyline": {"type": "string"}
+            "polyline": {"type": "string"},
+            "origin_label": {"type": "string"},
+            "dest_label": {"type": "string"},
         })
         return schema
 
@@ -109,6 +113,16 @@ class DirectionsTool(MCPTool):
         d_lat = float(arguments.get("dest_lat"))
         d_lon = float(arguments.get("dest_lon"))
         mode = arguments.get("mode", "foot-walking")
+        origin_label = (arguments.get("origin_label") or "").strip()
+        dest_label = (arguments.get("dest_label") or "").strip()
+
+        def _attach_labels(data: Dict[str, Any]) -> Dict[str, Any]:
+            enriched = dict(data)
+            if origin_label:
+                enriched["origin_label"] = origin_label
+            if dest_label:
+                enriched["dest_label"] = dest_label
+            return enriched
 
         # 快取鍵（geohash 簡化）
         try:
@@ -119,12 +133,20 @@ class DirectionsTool(MCPTool):
 
         cached = await db_cache.get_route_cached(key)
         if cached:
-            return cls.create_success_response(content=f"距離 {int(cached['distance_m'])}m，約 {int(cached['duration_s']/60)} 分鐘", data=cached)
+            cached_payload = _attach_labels(cached)
+            return cls.create_success_response(
+                content=f"距離 {int(cached['distance_m'])}m，約 {int(cached['duration_s']/60)} 分鐘",
+                data=cached_payload,
+            )
 
         db_cached = await get_route_cache(key)
         if db_cached:
             await db_cache.set_route_cache(key, db_cached)
-            return cls.create_success_response(content=f"距離 {int(db_cached['distance_m'])}m，約 {int(db_cached['duration_s']/60)} 分鐘", data=db_cached)
+            db_payload = _attach_labels(db_cached)
+            return cls.create_success_response(
+                content=f"距離 {int(db_cached['distance_m'])}m，約 {int(db_cached['duration_s']/60)} 分鐘",
+                data=db_payload,
+            )
 
         # 呼叫 ORS Directions
         url = f"https://api.openrouteservice.org/v2/directions/{mode}"
@@ -148,12 +170,19 @@ class DirectionsTool(MCPTool):
             distance_m = float(summary["distance"])  # meters
             duration_s = float(summary["duration"])  # seconds
             polyline = feat["geometry"]["coordinates"]  # LineString 座標
-            payload = {"distance_m": distance_m, "duration_s": duration_s, "polyline": json.dumps(polyline)}
+            base_payload = {
+                "distance_m": distance_m,
+                "duration_s": duration_s,
+                "polyline": json.dumps(polyline),
+            }
         except Exception as e:
             raise ExecutionError(f"解析 ORS 回應失敗: {e}")
 
         # 回寫快取
-        await db_cache.set_route_cache(key, payload)
-        await set_route_cache(key, payload)
+        await db_cache.set_route_cache(key, base_payload)
+        await set_route_cache(key, base_payload)
 
-        return cls.create_success_response(content=f"距離 {int(distance_m)}m，約 {int(duration_s/60)} 分鐘", data=payload)
+        return cls.create_success_response(
+            content=f"距離 {int(distance_m)}m，約 {int(duration_s/60)} 分鐘",
+            data=_attach_labels(base_payload),
+        )

tests/features/mcp/test_agent_bridge_route_labels.py

@@ -0,0 +1,53 @@
+import asyncio
+from pathlib import Path
+import sys
+
+ROOT_DIR = Path(__file__).resolve().parents[4]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.append(str(ROOT_DIR))
+
+from features.mcp.agent_bridge import MCPAgentBridge  # noqa: E402
+
+
+def test_prepare_route_arguments_injects_labels():
+    bridge = MCPAgentBridge.__new__(MCPAgentBridge)
+
+    async def fake_resolve(_self, _lat, _lon):
+        return "測試地點"
+
+    bridge._resolve_coordinate_label = fake_resolve.__get__(bridge, MCPAgentBridge)  # type: ignore[attr-defined]
+
+    prepared, labels = asyncio.run(
+        bridge._prepare_route_arguments(
+            {
+                "origin_lat": "24.9915",
+                "origin_lon": "121.3423",
+                "dest_lat": "24.9891",
+                "dest_lon": "121.3134",
+                # 未提供 label，應自動補上
+            }
+        )
+    )
+
+    assert prepared["origin_label"] == "測試地點"
+    assert prepared["dest_label"] == "測試地點"
+    assert isinstance(prepared["origin_lat"], float)
+    assert isinstance(prepared["dest_lon"], float)
+    assert labels["origin_label"] == "測試地點"
+    assert labels["dest_label"] == "測試地點"
+
+
+def test_build_directions_message_returns_human_friendly_text():
+    bridge = MCPAgentBridge.__new__(MCPAgentBridge)
+
+    message, tool_data = bridge._build_directions_message(
+        {"distance_m": 1450.0, "duration_s": 840.0, "polyline": "[]"},
+        {"origin_label": "測試起點 A", "dest_label": "測試目的地 B"},
+    )
+
+    assert "測試起點 A" in message
+    assert "測試目的地 B" in message
+    assert "公里" in tool_data["distance_readable"] or "公尺" in tool_data["distance_readable"]
+    assert tool_data["duration_readable"].endswith("分") or tool_data["duration_readable"].endswith("分鐘")
+    assert "origin_lat" not in tool_data
+    assert "dest_lon" not in tool_data

tests/features/mcp/tools/test_directions_tool.py

@@ -1,5 +1,7 @@
+import asyncio
 from pathlib import Path
 import sys
+
 import pytest
 
 ROOT_DIR = Path(__file__).resolve().parents[4]
@@ -7,6 +9,7 @@ if str(ROOT_DIR) not in sys.path:
     sys.path.append(str(ROOT_DIR))
 
 from features.mcp.tools.base_tool import ValidationError  # noqa: E402
+from features.mcp.tools import directions_tool  # noqa: E402
 from features.mcp.tools.directions_tool import DirectionsTool  # noqa: E402
 
 
@@ -40,3 +43,42 @@ def test_validate_input_missing_dest_lon_gives_clear_error():
     message = str(excinfo.value)
     assert "dest_lon" in message
     assert "經度" in message
+
+
+def test_execute_returns_labels_when_cache_hit(monkeypatch):
+    monkeypatch.setattr(directions_tool, "ORS_API_KEY", "dummy-key", raising=False)
+
+    async def fake_get_route_cached(_key: str):
+        return {"distance_m": 1325.5, "duration_s": 780.0, "polyline": "[]"}
+
+    async def fake_get_route_cache(_key: str):
+        return None
+
+    async def noop_set_route_cache(*_args, **_kwargs):
+        return None
+
+    monkeypatch.setattr(directions_tool.db_cache, "get_route_cached", fake_get_route_cached)
+    monkeypatch.setattr(directions_tool, "get_route_cache", fake_get_route_cache)
+    monkeypatch.setattr(directions_tool.db_cache, "set_route_cache", noop_set_route_cache)
+    monkeypatch.setattr(directions_tool, "set_route_cache", noop_set_route_cache)
+
+    args = {
+        "origin_lat": 24.9915,
+        "origin_lon": 121.3423,
+        "dest_lat": 24.9891,
+        "dest_lon": 121.3134,
+        "origin_label": "測試起點 A",
+        "dest_label": "測試目的地 B",
+    }
+
+    result = asyncio.run(DirectionsTool.execute(args))
+
+    assert result["success"] is True
+    assert "距離" in result["content"]
+    assert result["origin_label"] == "測試起點 A"
+    assert result["dest_label"] == "測試目的地 B"
+    assert "distance_m" in result and "duration_s" in result
+    # 確保沒有把 label 寫入快取的原始資料
+    cached = asyncio.run(directions_tool.db_cache.get_route_cached("ignored"))  # type: ignore[arg-type]
+    assert cached["distance_m"] == pytest.approx(1325.5)
+    assert "origin_label" not in cached