import sys
print(f"Python 版本: {sys.version}")
assert sys.version_info >= (3, 9), "需要 Python 3.9 或更高版本"
print("✅ Python 版本检查通过")

# 需要把安装一下提前配置好的依赖
#!pip install -r requirements.txt

import os
from dotenv import load_dotenv
from openai import OpenAI

# 从项目根目录的 .env 文件加载环境变量（DEEPSEEK_API_KEY 等）
load_dotenv()

# 测试连接
client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

# 最小调用样例
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=50
)
print(f"✅ API 连接成功，模型响应: {response.choices[0].message.content}")

react_prompt = """
你在一个由"思考、行动、观察、回答"组成的循环中运行。
在循环的最后，你输出一个答案。

使用"思考"来描述你对所提问题的思考。
使用"行动"来执行你可用的动作之一。
"观察"将是执行这些动作的结果。
"回答"将是分析"观察"结果后得出的答案。

你可用的动作包括：

calculate（计算）:
例如：calculate: 4 * 7 / 3
执行计算并返回数字

wikipedia（维基百科）:
例如：wikipedia: Django
返回从维基百科搜索的摘要

如果有机会，请始终在维基百科上查找信息。

示例会话：

问题：法国的首都是什么？

思考：我应该在维基百科上查找关于法国的信息
行动：wikipedia: France
PAUSE

你然后会收到：

观察：法国是一个国家。首都是巴黎。

思考：我已经找到了答案
回答：法国的首都是巴黎

现在轮到你了：
"""

pip install openai -q

import os
from dotenv import load_dotenv
from openai import OpenAI

# 从项目根目录的 .env 文件加载环境变量（DEEPSEEK_API_KEY 等）
load_dotenv()

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"  # DeepSeek API 端点
)

def chat(prompt: str, model: str = "deepseek-chat") -> str:
    """向 LLM 发送单轮对话请求并返回回答"""
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
        max_tokens=1024
    )
    return response.choices[0].message.content

# 验证连接
print(chat("你好，请用一句话介绍你自己。"))

# 实验一：实时信息获取
response = chat("今天北京的天气怎么样？气温多少度？")
print("【实时信息获取】")
print(response)
print("\n" + "="*60)
print("📌 观察：LLM 无法获取实时天气数据，只能给出模糊回答或声明自己无法访问实时信息。")
print("🔧 Agent 解法：通过 get_weather 工具调用天气 API 获取实时数据。")

# 实验二：精确数学计算
response = chat("请计算 7654321 × 1234567 的结果。")
print("【精确数学计算】")
print(response)
print("\n" + "="*60)

# 验证正确答案
correct = 7654321 * 1234567
print(f"✅ Python 计算的正确答案：{correct}")
print(f"📌 观察：LLM 的回答是否与正确答案一致？大概率不一致。")
print(f"🔧 Agent 解法：通过 calculator 工具或 code_executor 工具执行精确计算。")

# 实验三：文件系统操作
response = chat("请帮我在桌面上创建一个名为 'agent_test.txt' 的文件，内容写入 'Hello Agent!'。")
print("【文件系统操作】")
print(response)
print("\n" + "="*60)
print("📌 观察：LLM 只能告诉你'怎么做'，但无法真正执行文件操作。")
print("🔧 Agent 解法：通过 file_write 工具直接操作文件系统。")

# 实验四：多步推理与信息整合
response = chat(
    "请帮我完成以下任务：\n"
    "1. 查找 Python 3.12 的发布日期\n"
    "2. 计算从发布日期到今天过了多少天\n"
    "3. 查找 Python 3.12 新增了哪些主要特性\n"
    "4. 将以上信息整理成一份简短的技术摘要"
)
print("【多步推理与信息整合】")
print(response)
print("\n" + "="*60)
print("📌 观察：LLM 会尝试回答，但信息可能过时、天数计算可能错误、特性列表可能不完整。")
print("🔧 Agent 解法：分步调用搜索工具获取准确信息 + 计算工具精确计算 + 最终整合。")

# 实验五：与外部服务交互
response = chat("请帮我向 https://httpbin.org/post 发送一个 POST 请求，body 为 {'test': 'hello'}，并告诉我返回结果。")
print("【外部服务交互】")
print(response)
print("\n" + "="*60)
print("📌 观察：LLM 会给出代码示例，但无法真正发送 HTTP 请求。")
print("🔧 Agent 解法：通过 http_request 工具直接发送请求并获取响应。")

!curl -X POST https://httpbin.org/post -H "Content-Type: application/json" -d '{"test": "hello"}'

import json
import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv(override=True)

# 使用Deepseek的API来调用大模型
client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)
# 1. 这是你本地真正能干活的函数（大模型并不知道它的具体实现代码）
def get_weather(location: str):
    print(f"🔧 [本地执行中] 正在查询 {location} 的天气...")

    # 这里可以是发HTTP请求、查数据库等真实操作
    if location == "北京":
        return '{"temp": 25, "condition": "晴"}'
    return '{"temp": 20, "condition": "未知"}'


# 2. 【关键抽象】建立“字符串名字”到“内存里的真实函数”的映射字典
available_functions = {
    "get_weather": get_weather,             # 这里是将字符串 "get_weather" 映射到你本地的 get_weather 函数
    # 如果有别的工具："search_database": search_database
}

# 3. 告诉大模型你有这个工具（只给说明书，不给代码）
tools_description = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }
}]

messages = [{"role": "user", "content": "北京今天热吗？"}]

# 大模型看到你的问题和工具说明书，它决定调用工具
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=messages,
    tools=tools_description    # 告诉大模型你有哪些工具
)

response_message = response.choices[0].message
# 查看大模型是否调用了工具
print(response_message.tool_calls)

# 检查大模型是不是发出了调用工具的请求
if response_message.tool_calls:
    
    # 记得把大模型的"请求调用"这条记录也放进历史对话里
    messages.append(response_message)
    
    # 遍历大模型想要调用的所有函数（有时候它会并行调用多个）
    for tool_call in response_message.tool_calls:
        
        # 1. 提取大模型建议的指令
        function_name = tool_call.function.name # 比如提取到 "get_weather"
        function_args_json = tool_call.function.arguments # 比如提取到 "{\"location\": \"北京\"}"
        
        # 2. 将大模型生成的 JSON 字符串解析为真正的 Python 字典
        function_args = json.loads(function_args_json)
        
        # 3. 【真正执行的魔法在此】
        # 通过大模型给的字符串名字，从你的映射字典里找到真正的 Python 函数内存地址
        function_to_call = available_functions.get(function_name)
        
        if function_to_call:
            # 4. 在你的本地机器上，真正执行这个函数，并传入解析好的参数！
            function_result = function_to_call(**function_args)
            print(f"✅ [本地执行完毕] 得到结果: {function_result}")
        else:
            function_result = "Error: 找不到该函数"
            
        # 5. 将执行得到的结果，打包成特定格式（role="tool"），准备发回给大模型
        messages.append({
            "tool_call_id": tool_call.id, # 必须带上这个ID，告诉大模型这是对刚才它请求的回复
            "role": "tool",
            "name": function_name,
            "content": function_result,   # 把真实结果（如 '{"temp": 25}'）塞进去
        })
# 打印最终的messages
print(messages)

# 现在 messages 里面包含了：用户问题 -> 模型的调用请求 -> 你本地执行的结果
# 再次发给大模型，它就能看着真实结果，总结出人话了
second_response = client.chat.completions.create(
    model="deepseek-chat",
    messages=messages,
)

print("\n🤖 最终回答：", second_response.choices[0].message.content)

# 一个完整的工具定义示例：天气查询工具
weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",                          # 工具名称，建议：小写 + 下划线 + 动词开头
        "description": (                                 # 工具描述，决定调用命运：做什么、何时调用、边界在哪里。
            "获取指定城市的当前天气信息，包括气温、天气状况和湿度。"
            "当用户询问某个城市的天气、气温、是否需要带伞等问题时，调用此工具。"
        ),
        "parameters": {                                  # 参数定义
            "type": "object",                            # 参数类型：object 表示 JSON 对象
            "properties": {
                "city": {                                # 属性名：city
                    "type": "string",                    # 基础类型：string、number、boolean
                    "description": "要查询天气的城市名称，例如：北京、上海、广州"   # 参数说明
                }
            },
            "required": ["city"]                         # 必填参数列表
        }
    }
}

# ✅ 好的命名：清晰、具体、动词开头
# "name": "get_weather"
# "name": "search_web"
# "name": "calculate_math"
# "name": "read_file"

# ❌ 差的命名：模糊、过于通用
# "name": "tool1"
# "name": "helper"
# "name": "do_something"

import json

# 好描述版本的工具定义（前面已定义）
good_tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": (
                "获取指定城市的当前天气信息，包括气温（摄氏度）、天气状况和湿度。"
                "当用户询问某个城市的天气、气温、是否需要带伞/穿外套等问题时，调用此工具。"
                "目前支持的城市：北京、上海、广州、深圳、杭州。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "要查询天气的城市名称，例如：北京、上海、广州"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": (
                "执行数学计算，支持加减乘除、幂运算、三角函数、对数等。"
                "当用户需要精确计算数学表达式时调用此工具。"
                "输入应为合法的 Python 数学表达式，例如：'2**10'、'sqrt(144)'。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "要计算的数学表达式，使用 Python 语法"
                    }
                },
                "required": ["expression"]
            }
        }
    }
]

# 坏描述版本的工具定义
bad_tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取天气",          # ❌ 过于简略
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市"}
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "计算",              # ❌ 极度模糊
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "表达式"}
                },
                "required": ["expression"]
            }
        }
    }
]

# 测试用例
test_cases = [
    ("北京今天天气怎么样？", "应调用 get_weather"),
    ("帮我算一下 123 * 456", "应调用 calculate"),
    ("Python 是什么语言？", "不应调用任何工具"),
]

print("=" * 60)
print("📊 对照实验：好描述 vs 坏描述")
print("=" * 60)

MODEL="deepseek-chat"

for question, expected in test_cases:
    print(f"\n问题：{question}")
    print(f"预期：{expected}")

    # 好描述版本
    resp_good = client.chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": question}],
        tools=good_tools,
        tool_choice="auto",
        max_tokens=256
    )
    good_calls = resp_good.choices[0].message.tool_calls
    good_result = [tc.function.name for tc in good_calls] if good_calls else ["无工具调用"]

    # 坏描述版本
    resp_bad = client.chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": question}],
        tools=bad_tools,
        tool_choice="auto",
        max_tokens=256
    )
    bad_calls = resp_bad.choices[0].message.tool_calls
    bad_result = [tc.function.name for tc in bad_calls] if bad_calls else ["无工具调用"]

    print(f"  好描述结果：{good_result}")
    print(f"  坏描述结果：{bad_result}")

# 黄金模板示例
description = (
    "获取指定城市的当前天气信息，包括气温（摄氏度）、天气状况和湿度。"   # 功能说明
    "当用户询问某个城市的天气、气温、是否需要带伞/穿外套等问题时，"     # 触发条件
    "城市名称应为中文全称，例如：北京、上海、广州。"                    # 输入格式
    "目前仅支持中国大陆主要城市，不支持历史天气和天气预报查询。"         # 能力边界
)

# 一个更复杂的参数定义示例：搜索工具
search_tool_params = {
    "type": "object",                   # 参数容器类型，通常为 object
    "properties": {                     # 具体参数定义集合
        "query": {                      # 参数名：query（搜索词）
            "type": "string",           # 参数数据类型：字符串
            "description": "搜索关键词，应该是简洁明确的搜索查询" # 参数功能描述，供模型理解何时使用
        },
        "max_results": {                # 参数名：max_results（结果数）
            "type": "integer",          # 参数数据类型：整数
            "description": "返回的最大结果数量，默认为 5", # 参数功能描述
            "default": 5                # 默认值设定：若模型未提供则使用此值
        },
        "language": {                   # 参数名：language（语言）
            "type": "string",           # 参数数据类型：字符串
            "description": "搜索结果的语言偏好", # 参数功能描述
            "enum": ["zh", "en"],       # 枚举约束：限定模型只能从指定列表中选择
            "default": "zh"             # 默认值设定
        }
    },
    "required": ["query"]               # 只有 query 是必填的
}

import os
from dotenv import load_dotenv
from openai import OpenAI

# 加载 .env 配置文件，获取 API 密钥等环境变量
load_dotenv()

# 初始化 OpenAI 客户端（此处配置为 DeepSeek API 终端）
client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)
MODEL = "deepseek-chat"

# 定义工具（Tools）列表，采用 JSON Schema 描述函数接口
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"] # 声明必选参数
            }
        }
    }
]

def test_tool_choice_mode(user_message: str, mode, label: str):
    """
    封装测试函数，演示不同 tool_choice 策略对模型决策的影响
    :param user_message: 用户输入的文本
    :param mode: tool_choice 参数值 ('auto', 'required', 'none')
    :param label: 打印显示的模式说明
    """
    print(f"\n{'='*55}")
    print(f"模式：{label}  |  tool_choice={mode!r}")
    print(f"问题：{user_message}")
    print('='*55)

    # 发起对话请求
    response = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": "你是一个有用的助手。"},
            {"role": "user", "content": user_message}
        ],
        tools=tools,          # 注入工具定义
        tool_choice=mode,     # 控制工具调用行为的关键参数
        temperature=0.7,      # 控制随机性
        max_tokens=512        # 控制回复长度
    )
    msg = response.choices[0].message

    # 判断模型返回的是工具调用指令还是普通文本回复
    if msg.tool_calls:
        for tc in msg.tool_calls:
            print(f"  🔧 调用工具：{tc.function.name}")
            print(f"  📦 参数：{tc.function.arguments}")
    else:
        # 若无 tool_calls，则输出模型生成的直接回答
        print(f"  💬 直接回答：{msg.content[:200]}")

# 核心对比测试：针对同一天气查询问题，观察三种模式的差异
question = "北京今天天气怎么样？"

# 1. auto：默认模式，模型根据意图自动判断是否需要调用工具
test_tool_choice_mode(question, "auto",     "自动模式（auto）")

# 2. required：强制模式，模型必须选择并调用一个工具（即使不一定合适）
test_tool_choice_mode(question, "required", "强制调用（required）")

# 3. none：禁用模式，模型被禁止使用工具，只能进行纯文本回复
test_tool_choice_mode(question, "none",     "禁止调用（none）")

# 测试：对于不需要工具的问题，三种模式的差异
question2 = "Python 中 list 和 tuple 有什么区别？"

test_tool_choice_mode(question2, "auto",     "自动模式（auto）")
test_tool_choice_mode(question2, "required", "强制调用（required）")
test_tool_choice_mode(question2, "none",     "禁止调用（none）")

# 获取带工具调用的响应
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto"
)

assistant_message = response.choices[0].message

# 检查是否包含工具调用
if assistant_message.tool_calls:
    for tool_call in assistant_message.tool_calls:
        print(f"调用 ID：{tool_call.id}")                    # 唯一标识符
        print(f"工具类型：{tool_call.type}")                 # 通常是 "function"
        print(f"函数名称：{tool_call.function.name}")        # 要调用的函数名
        print(f"函数参数：{tool_call.function.arguments}")   # JSON 格式的参数
        print("-" * 40)

import os
import json
from dotenv import load_dotenv
from openai import OpenAI

# 从项目根目录的 .env 文件加载环境变量（DEEPSEEK_API_KEY 等）
load_dotenv()

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

MODEL = "deepseek-chat"
print("✅ 环境配置完成")

import math
import requests

# 请确保环境变量中已经设置了 TAVILY_API_KEY，获取API官网地址：https://app.tavily.com/home
TAVILY_API_KEY = os.environ.get("TAVILY_API_KEY", "你的_tavily_api_key")

# ==========================================
# 1. 本地真正的工具函数执行逻辑：调用 Tavily API
# ==========================================
def get_weather(query: str) -> str:
    """
    使用 Tavily 搜索天气信息的底层真实函数
    """
    print(f"\n🌍 [Tool 执行中] 正在通过 Tavily 搜索: {query} ...")
    
    url = "https://api.tavily.com/search"
    headers = {"Content-Type": "application/json"}
    payload = {
        "api_key": TAVILY_API_KEY,
        "query": query,
        "search_depth": "basic",     # 基础搜索速度更快
        "include_answer": True,      # 让 Tavily 尝试直接提取简短回答
        "max_results": 3             # 只要前 3 个最相关的网页结果
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        # 提取有价值的信息返回给大模型（优先返回 Tavily 的总结内容）
        result_text = data.get("answer", "")
        if not result_text:
            # 如果没有直接 answer，就把搜索到的 snippet 组装起来
            snippets = [result["content"] for result in data.get("results", [])]
            result_text = "\n".join(snippets)
        return json.dumps({"status": "success", "search_result": result_text},ensure_ascii=False)
    else:
        return json.dumps({"status": "error", "message": f"Tavily API 请求失败: {response.text}"})


def calculate(expression: str) -> str:
    """安全的数学计算工具，支持基本运算和常用数学函数"""
    # 安全白名单：只允许数学相关的函数和运算符
    allowed_names = {
        "abs": abs, "round": round, "min": min, "max": max,
        "pow": pow, "sum": sum,
        "sqrt": math.sqrt, "log": math.log, "log10": math.log10,
        "sin": math.sin, "cos": math.cos, "tan": math.tan,
        "pi": math.pi, "e": math.e,
    }

    try:
        # 使用 eval 配合白名单，防止代码注入
        result = eval(expression, {"__builtins__": {}}, allowed_names)
        return json.dumps({
            "expression": expression,
            "result": result,
            "status": "success"
        }, ensure_ascii=False)
    except Exception as e:
        return json.dumps({
            "expression": expression,
            "error": str(e),
            "status": "failed"
        }, ensure_ascii=False)


# 验证工具函数
print("天气查询测试：", get_weather("搜索北京今天的天气"))
print("计算测试：", calculate("7654321 * 1234567"))

text = "(1 + 2) * 3"
print(text) 
# 输出的是字符串本身："(1 + 2) * 3"

result = eval(text)
print(result) 
# 输出的是数字：9

# 定义工具的 JSON Schema —— 这是 LLM 的"工具说明书"
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": (
                "获取指定城市的当前天气信息，包括气温（摄氏度）、天气状况和湿度。"
                "当用户询问某个城市的天气、气温、是否需要带伞/穿外套等问题时，调用此工具。"
                "目前支持的城市：北京、上海、广州、深圳、杭州。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "要查询天气的城市名称，例如：北京、上海、广州，对应的日期，例如：今天、明天、后天，以及需要查询的天气信息，例如：天气、气温、湿度等"
                    }
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": (
                "执行数学计算，支持加减乘除、幂运算、三角函数、对数等。"
                "当用户需要精确计算数学表达式时调用此工具。"
                "输入应为合法的 Python 数学表达式，例如：'2**10'、'sqrt(144)'、'7654321 * 1234567'。"
                "注意：不要用此工具回答不涉及计算的问题。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "要计算的数学表达式，使用 Python 语法，例如：'2**10'、'sqrt(144)'"
                    }
                },
                "required": ["expression"]
            }
        }
    }
]

print(f"✅ 已注册 {len(tools)} 个工具：{[t['function']['name'] for t in tools]}")

def call_llm_with_tools(messages: list, tools: list) -> dict:
    """向 LLM 发送带工具定义的请求，返回完整的响应对象"""
    
    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        tools=tools,
        tool_choice="auto",   # "auto" 让 LLM 自主决定是否调用工具
        temperature=0.7,
        max_tokens=2048
    )
    return response


# 测试：一个需要工具的问题
messages = [
    {"role": "system", "content": "你是一个有用的助手，可以查询天气和进行数学计算。"},
    {"role": "user", "content": "北京今天天气怎么样？"}
]

response = call_llm_with_tools(messages, tools)
assistant_message = response.choices[0].message

# 检查 LLM 是否决定调用工具
print(f"LLM 是否调用工具：{assistant_message.tool_calls is not None}")
if assistant_message.tool_calls:
    for tool_call in assistant_message.tool_calls:
        print(f"  工具名称：{tool_call.function.name}")
        print(f"  调用参数：{tool_call.function.arguments}")
        print(f"  调用 ID：{tool_call.id}")
else:
    print(f"  直接回答：{assistant_message.content}")

# 建立工具名称到函数的映射（工具注册表），方便根据 LLM 返回的名称动态调用
TOOL_REGISTRY = {
    "get_weather": get_weather,
    "calculate": calculate,
}

def execute_tool_calls(assistant_message) -> list:
    """
    解析并执行 LLM 消息中的所有工具调用请求。
    
    参数:
        assistant_message: LLM 生成的消息对象，包含 tool_calls 列表。
        
    返回:
        list: 包含工具执行结果的消息列表，格式符合 OpenAI API 的 tool 角色要求。
    """
    tool_results = []

    # 如果 LLM 没有发起工具调用，直接返回空结果列表
    if not assistant_message.tool_calls:
        return tool_results

    # 遍历 LLM 请求的所有工具调用（LLM 可能会一次性请求调用多个工具）
    for tool_call in assistant_message.tool_calls:
        
        # 提取工具名称和 LLM 生成的参数（参数通常为 JSON 字符串，需解析为字典）
        func_name = tool_call.function.name
        func_args = json.loads(tool_call.function.arguments)

        print(f"🔧 正在执行工具：{func_name}，参数：{func_args}")

        # 在注册表中查找对应的函数并传入参数执行
        if func_name in TOOL_REGISTRY:
            # 使用 ** 语法将字典解包为函数的关键字参数
            result = TOOL_REGISTRY[func_name](**func_args)
        else:
            # 如果 LLM 请求了一个未定义的工具，返回错误信息给模型
            result = json.dumps({"error": f"未知工具：{func_name}"})

        print(f"📋 执行结果：{result}")

        # 将执行结果封装为特定的消息格式
        # 核心要点：role 必须为 "tool"，且 tool_call_id 必须与原始请求的 id 严格一致
        tool_results.append({
            "role": "tool",
            "tool_call_id": tool_call.id,    # 关键：用于 LLM 匹配请求与响应
            "content": str(result)          # 结果内容需转为字符串
        })

    return tool_results


# 调用执行函数，处理 assistant_message 中的工具请求
tool_results = execute_tool_calls(assistant_message)
print(f"\n✅ 工具执行完毕，共完成 {len(tool_results)} 个任务")

# 将 assistant 的工具调用决策追加到消息历史中
messages.append(assistant_message.model_dump())

# 将工具的实际执行结果追加到消息历史中，作为 LLM 生成回答的参考上下文
messages.extend(tool_results)

# 再次调用 LLM，传入包含工具执行结果的完整上下文，以生成最终的自然语言回答
final_response = client.chat.completions.create(
    model=MODEL,
    messages=messages,
    tools=tools,
    temperature=0.7,
    max_tokens=2048
)

# 从响应中提取最终的回答文本内容
final_answer = final_response.choices[0].message.content

# 打印并展示最终生成的回答结果
print("🤖 最终回答：")
print(final_answer)

def function_calling_pipeline(
    user_message: str,
    tools: list,
    tool_registry: dict,
    system_prompt: str = "你是一个有用的助手。",
    model: str = "deepseek-chat",
    verbose: bool = True
) -> str:
    """
    完整的 Function Calling 管线（单轮工具调用）

    参数：
        user_message: 用户输入
        tools: 工具定义列表（JSON Schema）
        tool_registry: 工具名称到函数的映射字典
        system_prompt: 系统提示词
        model: 模型名称
        verbose: 是否打印中间过程

    返回：
        LLM 的最终回答文本
    """
    # 步骤 1：构建消息历史
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_message}
    ]

    # 步骤 2-3：发送请求，获取 LLM 决策
    response = client.chat.completions.create(
        model=model, 
        messages=messages,
        tools=tools, 
        tool_choice="auto",
        temperature=0.7, 
        max_tokens=2048
    )
    assistant_message = response.choices[0].message

    # 如果 LLM 不需要调用工具，直接返回回答
    if not assistant_message.tool_calls:
        if verbose:
            print("💬 LLM 直接回答（未调用工具）")
        return assistant_message.content

    # 步骤 4：执行工具调用
    if verbose:
        print(f"🔧 LLM 决定调用 {len(assistant_message.tool_calls)} 个工具")

    messages.append(assistant_message.model_dump())

    for tool_call in assistant_message.tool_calls:
        func_name = tool_call.function.name
        func_args = json.loads(tool_call.function.arguments)

        if verbose:
            print(f"  → {func_name}({func_args})")

        # 执行工具
        if func_name in tool_registry:
            result = tool_registry[func_name](**func_args)
        else:
            result = json.dumps({"error": f"未知工具：{func_name}"})

        if verbose:
            print(f"  ← {result[:200]}")  # 截断过长的输出

        # 步骤 5：将结果追加到消息历史
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result
        })

    # 步骤 6：再次调用 LLM 生成最终回答
    final_response = client.chat.completions.create(
        model=model, messages=messages,
        tools=tools, temperature=0.7, max_tokens=2048
    )

    final_answer = final_response.choices[0].message.content
    if verbose:
        print(f"✅ 最终回答生成完成")

    return final_answer

# 测试 1：需要天气工具的问题
print("=" * 60)
print("测试 1：天气查询")
print("=" * 60)

answer = function_calling_pipeline(
    "上海今天天气怎么样？需要带伞吗？",
    tools=tools,
    tool_registry=TOOL_REGISTRY
)
print(f"\n🤖 {answer}\n")

# 测试 2：需要计算工具的问题
print("=" * 60)
print("测试 2：数学计算")
print("=" * 60)
answer = function_calling_pipeline(
    "请帮我计算 2 的 20 次方是多少？",
    tools=tools,
    tool_registry=TOOL_REGISTRY
)
print(f"\n🤖 {answer}\n")

# 测试 3：不需要工具的问题
print("=" * 60)
print("测试 3：纯知识问答（不需要工具）")
print("=" * 60)
answer = function_calling_pipeline(
    "请简要解释什么是 Function Calling？",
    tools=tools,
    tool_registry=TOOL_REGISTRY
)
print(f"\n🤖 {answer}\n")

# 测试 4：需要同时调用两个工具的问题
print("=" * 60)
print("测试 4：多工具调用")
print("=" * 60)
answer = function_calling_pipeline(
    "北京今天多少度？另外帮我算一下 sqrt(144) + 3.14 * 2",
    tools=tools,
    tool_registry=TOOL_REGISTRY
)
print(f"\n🤖 {answer}")

import os
import json
from dotenv import load_dotenv
from openai import OpenAI

# 加载环境变量
load_dotenv()

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)
MODEL = "deepseek-chat"

# ❌ 错误示例：参数描述过于简略
bad_weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取天气",  # ← 描述过于简略
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市"  # ← 参数描述不清晰
                }
            },
            "required": ["city"]
        }
    }
}

# 测试：LLM 能否正确提取参数？
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=[bad_weather_tool],
    tool_choice="auto"
)

assistant_message = response.choices[0].message
if assistant_message.tool_calls:
    tool_call = assistant_message.tool_calls[0]
    print(f"🔧 LLM 决定调用工具：{tool_call.function.name}")
    print(f"📦 提取的参数：{tool_call.function.arguments}")

    # 解析参数
    args = json.loads(tool_call.function.arguments)
    print(f"✅ 参数解析成功：{args}")
else:
    print("💬 LLM 直接回答，未调用工具")

# 更复杂的测试问题
complex_question = "我下周要去北京出差，帮我查一下那边的天气"

response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": complex_question}],
    tools=[bad_weather_tool],
    tool_choice="auto"
)

assistant_message = response.choices[0].message
if assistant_message.tool_calls:
    tool_call = assistant_message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"📦 提取的参数：{args}")
    # 可能出现的问题：LLM 提取了 {"city": "北京出差"} 或 {"city": "那边"}
else:
    print("💬 LLM 未调用工具")

# ✅ 修复版本：清晰的参数描述
good_weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": (
            "获取指定城市的当前天气信息，包括气温（摄氏度）、天气状况和湿度。"
            "当用户询问某个城市的天气、气温、是否需要带伞/穿外套等问题时，调用此工具。"
            "目前支持的城市：北京、上海、广州、深圳、杭州。"
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": (
                        "要查询天气的城市名称，必须是完整的中文城市名（不含'市'字）。"
                        "例如：北京、上海、广州。"
                        "如果用户使用代词（如'那边'、'这里'），需要根据上下文推断具体城市名。"
                    )
                }
            },
            "required": ["city"]
        }
    }
}

# 用相同的复杂问题测试修复后的工具
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "我下周要去北京出差，帮我查一下那边的天气"}],
    tools=[good_weather_tool],
    tool_choice="auto"
)

assistant_message = response.choices[0].message
if assistant_message.tool_calls:
    tool_call = assistant_message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"✅ 修复后提取的参数：{args}")
    # 预期输出：{"city": "北京"}

def get_weather_safe(city: str = None) -> str:
    """带参数校验的天气查询工具"""
    # 参数校验
    if not city or not isinstance(city, str):
        return json.dumps({
            "error": "参数错误：city 必须是非空字符串",
            "received": city,
            "hint": "请提供有效的城市名称，例如：北京、上海、广州"
        }, ensure_ascii=False)

    # 支持的城市列表
    supported_cities = ["北京", "上海", "广州", "深圳", "杭州"]
    if city not in supported_cities:
        return json.dumps({
            "error": f"暂不支持查询 {city} 的天气",
            "supported_cities": supported_cities
        }, ensure_ascii=False)

    # 模拟天气数据
    weather_db = {
        "北京": {"temperature": 33, "condition": "晴", "humidity": 45},
        "上海": {"temperature": 28, "condition": "多云", "humidity": 72},
        "广州": {"temperature": 35, "condition": "雷阵雨", "humidity": 85},
        "深圳": {"temperature": 34, "condition": "晴转多云", "humidity": 78},
        "杭州": {"temperature": 30, "condition": "阴", "humidity": 68},
    }

    data = weather_db[city]
    return json.dumps({
        "city": city,
        "temperature": data["temperature"],
        "condition": data["condition"],
        "humidity": data["humidity"],
        "unit": "摄氏度"
    }, ensure_ascii=False)

# 测试参数校验
print("测试1：正常参数")
print(get_weather_safe("北京"))

print("\n测试2：空参数")
print(get_weather_safe(None))

print("\n测试3：不支持的城市")
print(get_weather_safe("纽约"))

# 定义工具（正确的名称）
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",  # ← 正确的名称
            "description": (
                "获取指定城市的当前天气信息，包括气温（摄氏度）、天气状况和湿度。"
                "当用户询问某个城市的天气、气温、是否需要带伞/穿外套等问题时，调用此工具。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "要查询天气的城市名称，例如：北京、上海、广州"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# ❌ 错误示例：注册表中的名称拼写错误
def get_weather(city: str) -> str:
    """天气查询工具"""
    weather_db = {
        "北京": {"temperature": 33, "condition": "晴", "humidity": 45},
        "上海": {"temperature": 28, "condition": "多云", "humidity": 72},
    }
    data = weather_db.get(city, {"temperature": 25, "condition": "未知", "humidity": 50})
    return json.dumps({"city": city, **data}, ensure_ascii=False)


# 注册表中的名称拼写错误（少了一个 't'）
BUGGY_TOOL_REGISTRY = {
    "get_waether": get_weather,  # ← 拼写错误！应该是 get_weather
}

# 测试调用
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto"
)

assistant_message = response.choices[0].message

if assistant_message.tool_calls:
    tool_call = assistant_message.tool_calls[0]
    func_name = tool_call.function.name
    func_args = json.loads(tool_call.function.arguments)

    print(f"🔧 LLM 决定调用工具：{func_name}")
    print(f"📦 参数：{func_args}")

    # 尝试执行工具（会报错）
    try:
        func = BUGGY_TOOL_REGISTRY[func_name]  # ← 这里会抛出 KeyError
        result = func(**func_args)
        print(f"✅ 执行成功：{result}")
    except KeyError as e:
        print(f"❌ 执行失败：KeyError: {e}")
        print(f"💡 原因：注册表中没有名为 '{func_name}' 的工具")
        print(f"💡 注册表中的工具：{list(BUGGY_TOOL_REGISTRY.keys())}")