travel-agent-cli 0.2.0 → 0.2.2

package/python/tools/flyai_tools.py

@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+"""FlyAI 风格工具 - 旅行搜索服务
+
+基于 ClawHub FlyAI 设计模式，集成 Fliggy MCP 真实 API
+提供：
+- 🔍 Search: 自然语言旅行搜索
+- ✈️ Flights: 航班价格查询
+- 🏨 Hotels: 酒店搜索
+- 🎭 Attractions: 景点推荐
+"""
+from typing import Dict, Any, List, Optional
+from tools.mcp_tools import build_tool, string_property, integer_property
+from tools.fliggy_mcp import FliggyMCPClient, FliggyToolHandlers
+
+
+# =============================================================================
+# FlyAI 工具定义（MCP 格式）
+# =============================================================================
+
+def build_flyai_tools() -> Dict[str, Any]:
+    """构建 FlyAI 风格的工具集"""
+    return {
+        "travel_search": build_travel_search_tool(),
+        "search_flights": build_search_flights_tool(),
+        "search_hotels": build_search_hotels_tool(),
+        "search_attractions": build_search_attractions_tool(),
+    }
+
+
+def build_travel_search_tool() -> Dict[str, Any]:
+    """🔍 自然语言旅行搜索工具"""
+    return build_tool(
+        name="travel_search",
+        description="使用自然语言搜索旅行相关信息，包括目的地、行程、价格等综合信息",
+        properties={
+            "query": string_property("搜索查询，例如'5 天日本行程规划'、'三亚海岛游'等"),
+            "destination": string_property("目的地（可选）"),
+            "duration": string_property("行程天数，例如'5 天'、'3-5 天'"),
+            "budget": string_property("预算范围，例如'5000-10000 元'"),
+        },
+        required=["query"],
+    )
+
+
+def build_search_flights_tool() -> Dict[str, Any]:
+    """✈️ 航班搜索工具"""
+    return build_tool(
+        name="search_flights",
+        description="搜索航班价格和时间",
+        properties={
+            "origin": string_property("出发城市，例如'北京'、'上海'"),
+            "destination": string_property("目的地城市，例如'东京'、'曼谷'"),
+            "departure_date": string_property("出发日期，格式 YYYY-MM-DD 或'下周五'"),
+            "return_date": string_property("返程日期（可选），格式 YYYY-MM-DD"),
+            "cabin_class": string_property(
+                "舱位等级",
+                enum=["economy", "premium", "business", "first"],
+                default="economy"
+            ),
+        },
+        required=["origin", "destination"],
+    )
+
+
+def build_search_hotels_tool() -> Dict[str, Any]:
+    """🏨 酒店搜索工具"""
+    return build_tool(
+        name="search_hotels",
+        description="搜索酒店价格和房源",
+        properties={
+            "destination": string_property("目的地城市或地区"),
+            "check_in": string_property("入住日期，格式 YYYY-MM-DD 或'明天'"),
+            "check_out": string_property("退房日期（可选），格式 YYYY-MM-DD"),
+            "guests": integer_property("入住人数", minimum=1, maximum=10, default=2),
+            "star_rating": string_property(
+                "星级要求",
+                enum=["3", "4", "5", "luxury"],
+                default="4"
+            ),
+            "price_min": integer_property("最低价格", minimum=0, default=0),
+            "price_max": integer_property("最高价格", minimum=0, default=5000),
+        },
+        required=["destination"],
+    )
+
+
+def build_search_attractions_tool() -> Dict[str, Any]:
+    """🎭 景点搜索工具"""
+    return build_tool(
+        name="search_attractions",
+        description="搜索目的地景点和活动",
+        properties={
+            "destination": string_property("目的地城市或地区"),
+            "category": string_property(
+                "景点类型",
+                enum=["nature", "culture", "entertainment", "food", "shopping", "all"],
+                default="all"
+            ),
+            "duration": string_property("游玩时长，例如'半天'、'一天'"),
+            "group_type": string_property(
+                "出行类型",
+                enum=["family", "couple", "solo", "friends"],
+                default="family"
+            ),
+        },
+        required=["destination"],
+    )
+
+
+# =============================================================================
+# FlyAI 工具处理器
+# =============================================================================
+
+class FlyAIToolHandlers:
+    """FlyAI 工具处理器（集成 Fliggy MCP）"""
+
+    def __init__(self, app_key: Optional[str] = None, app_secret: Optional[str] = None):
+        """初始化
+
+        Args:
+            app_key: 飞猪开放平台 App Key（可选，不传则使用沙箱模式）
+            app_secret: 飞猪开放平台 App Secret（可选）
+        """
+        self.client = FliggyMCPClient(
+            app_key=app_key,
+            app_secret=app_secret,
+            use_sandbox=(app_key is None),  # 未配置 App Key 时使用沙箱
+        )
+        self.fliggy_handlers = FliggyToolHandlers(self.client)
+
+    async def handle_travel_search(
+        self,
+        query: str,
+        destination: Optional[str] = None,
+        duration: Optional[str] = None,
+        budget: Optional[str] = None
+    ) -> str:
+        """处理旅行搜索请求"""
+        # 智能识别查询类型并调用相应的 Fliggy API
+        import re
+
+        # 检测航班查询
+        if re.search(r'(航班 | 机票|flight|fly|机场 | 飞)', query.lower()):
+            return await self.handle_search_flights(
+                origin=query,
+                destination=destination or "目的地",
+                departure_date=duration,
+            )
+
+        # 检测酒店查询
+        if re.search(r'(酒店|住宿|hotel|民宿 | 旅馆)', query.lower()):
+            return await self.handle_search_hotels(
+                destination=destination or query.replace("酒店", "").replace("hotel", "").strip(),
+                check_in=duration,
+            )
+
+        # 检测景点查询
+        if re.search(r'(景点 | 景区 | 游玩 | 玩|attraction|tourist)', query.lower()):
+            return await self.handle_search_attractions(
+                destination=destination or query,
+            )
+
+        # 综合旅行搜索 - 调用多个 API
+        results = []
+
+        # 1. 搜索景点
+        dest = destination or "旅行目的地"
+        attraction_result = await self.handle_search_attractions(dest)
+        results.append(f"🎭 景点推荐\n{attraction_result}")
+
+        # 2. 搜索酒店
+        hotel_result = await self.handle_search_hotels(dest)
+        results.append(f"🏨 酒店推荐\n{hotel_result}")
+
+        return "\n".join(results)
+
+    async def handle_search_flights(
+        self,
+        origin: str,
+        destination: str,
+        departure_date: Optional[str] = None,
+        return_date: Optional[str] = None,
+        cabin_class: str = "economy"
+    ) -> str:
+        """处理航班搜索请求"""
+        try:
+            return await self.fliggy_handlers.search_flights(
+                origin=origin,
+                destination=destination,
+                departure_date=departure_date,
+                return_date=return_date,
+                cabin_class=cabin_class,
+            )
+        except Exception as e:
+            return f"航班搜索失败：{e}"
+
+    async def handle_search_hotels(
+        self,
+        destination: str,
+        check_in: Optional[str] = None,
+        check_out: Optional[str] = None,
+        guests: int = 2,
+        star_rating: str = "4",
+        price_min: int = 0,
+        price_max: int = 5000
+    ) -> str:
+        """处理酒店搜索请求"""
+        try:
+            return await self.fliggy_handlers.search_hotels(
+                destination=destination,
+                check_in=check_in,
+                check_out=check_out,
+                guests=guests,
+                star_rating=star_rating,
+                price_min=price_min,
+                price_max=price_max,
+            )
+        except Exception as e:
+            return f"酒店搜索失败：{e}"
+
+    async def handle_search_attractions(
+        self,
+        destination: str,
+        category: str = "all",
+        duration: Optional[str] = None,
+        group_type: str = "family"
+    ) -> str:
+        """处理景点搜索请求"""
+        try:
+            return await self.fliggy_handlers.search_attractions(
+                destination=destination,
+                category=category,
+                duration=duration,
+            )
+        except Exception as e:
+            return f"景点搜索失败：{e}"
+
+
+# =============================================================================
+# 工具工厂函数
+# =============================================================================
+
+def get_flyai_tool_handlers() -> Dict[str, callable]:
+    """获取 FlyAI 工具处理器"""
+    handlers = FlyAIToolHandlers()
+    return {
+        "travel_search": handlers.handle_travel_search,
+        "search_flights": handlers.handle_search_flights,
+        "search_hotels": handlers.handle_search_hotels,
+        "search_attractions": handlers.handle_search_attractions,
+    }

package/python/tools/mcp_tools.py

@@ -0,0 +1,412 @@
+"""MCP 风格工具定义模块
+
+参考 @modelcontextprotocol/sdk 的 Tool 接口设计
+https://github.com/modelcontextprotocol/python-sdk
+
+核心设计原则：
+1. 工具定义与执行逻辑分离
+2. 使用标准的 JSON Schema 格式
+3. 支持动态工具注册
+4. 工具元数据（名称、描述、schema）集中管理
+"""
+from typing import Any, Callable, Dict, List, Optional, TypedDict, Union
+from dataclasses import dataclass, field
+
+
+# =============================================================================
+# MCP 风格 Tool 定义（参考 @modelcontextprotocol/sdk/types.js）
+# =============================================================================
+
+class JsonSchemaProperty(TypedDict, total=False):
+    """JSON Schema 属性定义"""
+    type: str
+    description: str
+    enum: List[Any]
+    default: Any
+    minimum: int
+    maximum: int
+    items: Dict[str, Any]
+    minItems: int
+    maxItems: int
+    required: List[str]
+    properties: Dict[str, "JsonSchemaProperty"]
+
+
+class JsonSchemaObject(TypedDict, total=False):
+    """JSON Schema 对象定义"""
+    type: str
+    description: str
+    properties: Dict[str, JsonSchemaProperty]
+    required: List[str]
+    items: Dict[str, Any]
+
+
+class ToolInputSchema(TypedDict):
+    """工具输入 Schema（MCP 标准格式）"""
+    type: str  # 固定为 "object"
+    properties: Dict[str, JsonSchemaProperty]
+    required: List[str]
+
+
+class Tool(TypedDict):
+    """MCP Tool 接口定义
+
+    参考：@modelcontextprotocol/sdk/types.js:Tool
+
+    示例:
+        {
+            "name": "search_social_media",
+            "description": "搜索社交媒体平台上的旅行相关内容",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "keyword": {
+                        "type": "string",
+                        "description": "搜索关键词"
+                    }
+                },
+                "required": ["keyword"]
+            }
+        }
+    """
+    name: str
+    description: str
+    inputSchema: ToolInputSchema
+
+
+# =============================================================================
+# 工具处理器类型定义
+# =============================================================================
+
+# 同步工具处理函数类型
+SyncToolHandler = Callable[..., Any]
+
+# 异步工具处理函数类型
+AsyncToolHandler = Callable[..., Any]
+
+# 工具处理函数（同步或异步）
+ToolHandler = Union[SyncToolHandler, AsyncToolHandler]
+
+
+# =============================================================================
+# 工具注册表
+# =============================================================================
+
+@dataclass
+class ToolRegistration:
+    """工具注册信息
+
+    将工具定义与处理函数绑定在一起
+    """
+    definition: Tool
+    handler: ToolHandler
+    is_async: bool = False
+
+    def __post_init__(self):
+        # 检测是否为异步函数
+        import inspect
+        if inspect.iscoroutinefunction(self.handler):
+            self.is_async = True
+
+
+class ToolRegistry:
+    """工具注册表
+
+    管理所有已注册工具的定义和处理器
+
+    使用示例:
+        registry = ToolRegistry()
+
+        # 定义工具
+        search_tool = Tool(
+            name="search_social_media",
+            description="搜索社交媒体",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "keyword": {"type": "string", "description": "关键词"}
+                },
+                "required": ["keyword"]
+            }
+        )
+
+        # 注册工具
+        async def search_handler(keyword: str) -> str:
+            return f"搜索结果：{keyword}"
+
+        registry.register(search_tool, search_handler)
+
+        # 调用工具
+        result = await registry.call("search_social_media", keyword="旅行")
+    """
+
+    def __init__(self):
+        self._tools: Dict[str, ToolRegistration] = {}
+
+    def register(
+        self,
+        definition: Tool,
+        handler: ToolHandler,
+    ) -> None:
+        """注册工具
+
+        Args:
+            definition: 工具定义（MCP 格式）
+            handler: 工具处理函数
+
+        Raises:
+            ValueError: 工具名称已存在
+        """
+        tool_name = definition["name"]
+        if tool_name in self._tools:
+            raise ValueError(f"工具 '{tool_name}' 已注册")
+
+        self._tools[tool_name] = ToolRegistration(
+            definition=definition,
+            handler=handler,
+        )
+
+    def unregister(self, tool_name: str) -> None:
+        """注销工具"""
+        if tool_name in self._tools:
+            del self._tools[tool_name]
+
+    def get_definition(self, tool_name: str) -> Optional[Tool]:
+        """获取工具定义"""
+        reg = self._tools.get(tool_name)
+        return reg.definition if reg else None
+
+    def get_definitions(self) -> List[Tool]:
+        """获取所有工具定义（用于传递给 LLM）"""
+        return [reg.definition for reg in self._tools.values()]
+
+    def get_handler(self, tool_name: str) -> Optional[ToolHandler]:
+        """获取工具处理函数"""
+        reg = self._tools.get(tool_name)
+        return reg.handler if reg else None
+
+    async def call(
+        self,
+        tool_name: str,
+        **kwargs: Any,
+    ) -> Any:
+        """调用工具
+
+        Args:
+            tool_name: 工具名称
+            **kwargs: 工具参数
+
+        Returns:
+            工具执行结果
+
+        Raises:
+            ValueError: 工具不存在
+        """
+        reg = self._tools.get(tool_name)
+        if not reg:
+            raise ValueError(f"未知工具：{tool_name}")
+
+        # 执行处理函数
+        result = reg.handler(**kwargs)
+
+        # 如果是异步函数，等待结果
+        if reg.is_async:
+            return await result
+        return result
+
+    def has_tool(self, tool_name: str) -> bool:
+        """检查工具是否已注册"""
+        return tool_name in self._tools
+
+    def list_tools(self) -> List[str]:
+        """列出所有已注册工具名称"""
+        return list(self._tools.keys())
+
+
+# =============================================================================
+# 工具定义辅助函数
+# =============================================================================
+
+def string_property(
+    description: str,
+    enum: List[str] = None,
+    default: str = None,
+) -> JsonSchemaProperty:
+    """创建字符串类型属性定义
+
+    Args:
+        description: 属性描述
+        enum: 可选的枚举值
+        default: 默认值
+
+    Returns:
+        JSON Schema 属性定义
+    """
+    prop: JsonSchemaProperty = {
+        "type": "string",
+        "description": description,
+    }
+    if enum:
+        prop["enum"] = enum
+    if default:
+        prop["default"] = default
+    return prop
+
+
+def integer_property(
+    description: str,
+    minimum: int = None,
+    maximum: int = None,
+    default: int = None,
+) -> JsonSchemaProperty:
+    """创建整数类型属性定义"""
+    prop: JsonSchemaProperty = {
+        "type": "integer",
+        "description": description,
+    }
+    if minimum is not None:
+        prop["minimum"] = minimum
+    if maximum is not None:
+        prop["maximum"] = maximum
+    if default is not None:
+        prop["default"] = default
+    return prop
+
+
+def boolean_property(
+    description: str,
+    default: bool = None,
+) -> JsonSchemaProperty:
+    """创建布尔类型属性定义"""
+    prop: JsonSchemaProperty = {
+        "type": "boolean",
+        "description": description,
+    }
+    if default is not None:
+        prop["default"] = default
+    return prop
+
+
+def array_property(
+    description: str,
+    items: Dict[str, Any],
+    minItems: int = None,
+    maxItems: int = None,
+) -> JsonSchemaProperty:
+    """创建数组类型属性定义"""
+    prop: JsonSchemaProperty = {
+        "type": "array",
+        "description": description,
+        "items": items,
+    }
+    if minItems is not None:
+        prop["minItems"] = minItems
+    if maxItems is not None:
+        prop["maxItems"] = maxItems
+    return prop
+
+
+def object_property(
+    description: str,
+    properties: Dict[str, JsonSchemaProperty],
+    required: List[str] = None,
+) -> JsonSchemaProperty:
+    """创建对象类型属性定义"""
+    prop: JsonSchemaProperty = {
+        "type": "object",
+        "description": description,
+        "properties": properties,
+    }
+    if required:
+        prop["required"] = required
+    return prop
+
+
+def build_tool(
+    name: str,
+    description: str,
+    properties: Dict[str, JsonSchemaProperty],
+    required: List[str] = None,
+) -> Tool:
+    """构建 MCP 格式的工具定义
+
+    Args:
+        name: 工具名称
+        description: 工具描述
+        properties: 输入属性定义
+        required: 必填参数列表
+
+    Returns:
+        MCP 格式 Tool 对象
+
+    使用示例:
+        tool = build_tool(
+            name="search_social_media",
+            description="搜索社交媒体内容",
+            properties={
+                "keyword": string_property("搜索关键词"),
+                "platform": string_property(
+                    "目标平台",
+                    enum=["xiaohongshu", "weibo", "all"],
+                    default="all"
+                ),
+                "limit": integer_property("结果数量", minimum=1, maximum=100, default=20)
+            },
+            required=["keyword"]
+        )
+    """
+    return Tool(
+        name=name,
+        description=description,
+        inputSchema=ToolInputSchema(
+            type="object",
+            properties=properties,
+            required=required or [],
+        ),
+    )
+
+
+# =============================================================================
+# Agent 基类集成
+# =============================================================================
+
+class ToolEnabledMixin:
+    """工具启用 Mixin
+
+    为 Agent 提供工具注册和调用能力
+
+    使用示例:
+        class CollectionAgent(BaseAgent, ToolEnabledMixin):
+            def __init__(self):
+                super().__init__()
+                ToolEnabledMixin.__init__(self)
+
+                # 注册工具
+                self.register_tool(
+                    build_tool(...),
+                    self._handle_search
+                )
+    """
+
+    def __init__(self):
+        self.tool_registry = ToolRegistry()
+
+    def register_tool(
+        self,
+        definition: Tool,
+        handler: ToolHandler,
+    ) -> None:
+        """注册工具到 Agent"""
+        self.tool_registry.register(definition, handler)
+
+    def get_tool_definitions(self) -> List[Tool]:
+        """获取所有工具定义（用于传递给 LLM）"""
+        return self.tool_registry.get_definitions()
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        **kwargs: Any,
+    ) -> Any:
+        """调用工具"""
+        return await self.tool_registry.call(tool_name, **kwargs)

package/python/utils/__init__.py

@@ -0,0 +1,9 @@
+"""工具模块"""
+from utils.http import get_client, fetch_with_retry
+from utils.storage import Storage
+
+__all__ = [
+    "get_client",
+    "fetch_with_retry",
+    "Storage",
+]