ClassyGitShadowzzh

tools.py

tools.py
"""
tools.py —— 各专业角色的专属工具实现 + OpenAI function-calling schema。

设计原则(配合实验 10-2):
- 工具用「轻量真实实现」或「可控 mock」,重点不是工具多强,
  而是展示「自主角色移交」这一机制。
- research.web_search:内置知识库 mock(可控、可复现),
  未命中时诚实返回「未检索到」。
- coding.execute_python:真实执行 Python 代码并捕获标准输出(受限命名空间)。
- data_analysis.calculate / descriptive_stats:真实的安全计算。
- writing.count_characters:真实的中英文字数统计。

每个工具函数签名为 func(**kwargs) -> str(统一返回字符串,方便塞回对话历史)。
"""

from __future__ import annotations

import ast
import io
import math
import operator
import contextlib
from typing import Callable, Dict, List


# ---------------------------------------------------------------------------
# research 角色:web_search —— 内置知识库 mock
# ---------------------------------------------------------------------------

# 一个极小的「联网检索结果」知识库。命中关键词即返回内置资料,
# 保证 demo 可复现,同时不依赖真实外网。
_KNOWLEDGE_BASE = [
    {
        "keywords": ["新能源", "汽车", "销量", "nev", "电动车"],
        "content": (
            "【检索结果·中国乘用车市场信息联席会/中汽协】\n"
            "中国新能源汽车年度销量(单位:万辆):\n"
            "- 2021 年:352.1 万辆\n"
            "- 2022 年:688.7 万辆\n"
            "- 2023 年:949.5 万辆\n"
            "备注:包含纯电动(BEV)与插电混动(PHEV)乘用车。"
        ),
    },
    {
        "keywords": ["光伏", "装机", "太阳能"],
        "content": (
            "【检索结果·国家能源局】\n"
            "中国光伏新增装机量(单位:GW):\n"
            "- 2021 年:54.9 GW\n"
            "- 2022 年:87.4 GW\n"
            "- 2023 年:216.9 GW"
        ),
    },
    {
        "keywords": ["python", "gil", "全局解释器锁"],
        "content": (
            "【检索结果·技术资料】\n"
            "CPython 的 GIL(全局解释器锁)保证同一时刻只有一个线程执行字节码,"
            "因此 CPU 密集型任务用多线程无法并行,需改用多进程或 C 扩展。"
            "PEP 703 提出可选的 no-GIL 构建,Python 3.13 起以实验特性提供。"
        ),
    },
]


def web_search(query: str) -> str:
    """在内置知识库中检索(mock 联网检索)。"""
    q = (query or "").lower()
    hits: List[str] = []
    for entry in _KNOWLEDGE_BASE:
        if any(kw.lower() in q for kw in entry["keywords"]):
            hits.append(entry["content"])
    if hits:
        return "\n\n".join(hits)
    return (
        f"未在内置知识库中检索到与「{query}」直接相关的权威数据。"
        "请换一个更具体的检索词,或说明需要哪一年的数据。"
    )


# ---------------------------------------------------------------------------
# coding 角色:execute_python —— 真实执行代码并捕获 stdout
# ---------------------------------------------------------------------------

def execute_python(code: str) -> str:
    """在受限命名空间中执行 Python 代码,返回其标准输出。"""
    safe_globals: Dict[str, object] = {
        "__builtins__": {
            "print": print,
            "range": range,
            "len": len,
            "sum": sum,
            "min": min,
            "max": max,
            "abs": abs,
            "round": round,
            "sorted": sorted,
            "enumerate": enumerate,
            "zip": zip,
            "map": map,
            "list": list,
            "dict": dict,
            "tuple": tuple,
            "float": float,
            "int": int,
            "str": str,
        },
        "math": math,
    }
    buf = io.StringIO()
    try:
        with contextlib.redirect_stdout(buf):
            exec(code, safe_globals, {})  # noqa: S102 —— 受限命名空间下的教学示例
    except Exception as exc:  # noqa: BLE001
        return f"代码执行出错:{type(exc).__name__}: {exc}\n已捕获输出:\n{buf.getvalue()}"
    out = buf.getvalue().strip()
    return out if out else "(代码已执行,但没有任何 print 输出)"


# ---------------------------------------------------------------------------
# data_analysis 角色:calculate(安全表达式求值)+ descriptive_stats
# ---------------------------------------------------------------------------

_ALLOWED_OPERATORS = {
    ast.Add: operator.add,
    ast.Sub: operator.sub,
    ast.Mult: operator.mul,
    ast.Div: operator.truediv,
    ast.Pow: operator.pow,
    ast.Mod: operator.mod,
    ast.USub: operator.neg,
    ast.UAdd: operator.pos,
}


def _safe_eval(node: ast.AST) -> float:
    """只支持四则运算/幂/取模的安全表达式求值(不走 Python 内置 eval)。"""
    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
        return float(node.value)
    if isinstance(node, ast.BinOp) and type(node.op) in _ALLOWED_OPERATORS:
        return _ALLOWED_OPERATORS[type(node.op)](_safe_eval(node.left), _safe_eval(node.right))
    if isinstance(node, ast.UnaryOp) and type(node.op) in _ALLOWED_OPERATORS:
        return _ALLOWED_OPERATORS[type(node.op)](_safe_eval(node.operand))
    raise ValueError("表达式包含不被支持的运算,只允许 + - * / ** % 与括号。")


def calculate(expression: str) -> str:
    """安全地计算一个纯数学表达式,例如 (949.5/352.1)**(1/2)-1 。"""
    try:
        tree = ast.parse(expression, mode="eval")
        result = _safe_eval(tree.body)
    except Exception as exc:  # noqa: BLE001
        return f"计算失败:{exc}"
    return f"{expression} = {result}"


def descriptive_stats(numbers: List[float]) -> str:
    """给一组数值返回基本描述统计(均值/最大/最小/极差)。"""
    if not numbers:
        return "输入为空,无法统计。"
    nums = [float(x) for x in numbers]
    n = len(nums)
    mean = sum(nums) / n
    return (
        f"样本量={n}, 均值={mean:.4f}, 最小={min(nums)}, "
        f"最大={max(nums)}, 极差={max(nums) - min(nums)}"
    )


# ---------------------------------------------------------------------------
# writing 角色:count_characters —— 中英文字数统计
# ---------------------------------------------------------------------------

def count_characters(text: str) -> str:
    """统计文本的字符数与中文字符数,帮助控制篇幅。"""
    if text is None:
        text = ""
    total = len(text)
    chinese = sum(1 for ch in text if "一" <= ch <= "鿿")
    return f"总字符数={total}, 其中中文字符={chinese}"


# ---------------------------------------------------------------------------
# 工具注册表:名称 -> (实现函数, OpenAI schema)
# ---------------------------------------------------------------------------

# 每个工具的 OpenAI function-calling schema。
TOOL_SCHEMAS: Dict[str, dict] = {
    "web_search": {
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "联网检索信息(本实验用内置知识库 mock)。用于查数据、事实、资料。",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "检索关键词或问题"},
                },
                "required": ["query"],
            },
        },
    },
    "execute_python": {
        "type": "function",
        "function": {
            "name": "execute_python",
            "description": "执行一段 Python 代码并返回其 print 输出。适合写脚本、跑逻辑。",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {"type": "string", "description": "要执行的 Python 源码,用 print 输出结果"},
                },
                "required": ["code"],
            },
        },
    },
    "calculate": {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "安全计算一个数学表达式,支持 + - * / ** % 和括号。",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "数学表达式,如 (949.5/352.1)**(1/2)-1"},
                },
                "required": ["expression"],
            },
        },
    },
    "descriptive_stats": {
        "type": "function",
        "function": {
            "name": "descriptive_stats",
            "description": "对一组数值做基本描述统计(均值/最大/最小/极差)。",
            "parameters": {
                "type": "object",
                "properties": {
                    "numbers": {
                        "type": "array",
                        "items": {"type": "number"},
                        "description": "数值数组",
                    },
                },
                "required": ["numbers"],
            },
        },
    },
    "count_characters": {
        "type": "function",
        "function": {
            "name": "count_characters",
            "description": "统计文本字符数与中文字符数,帮助控制篇幅。",
            "parameters": {
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "要统计的文本"},
                },
                "required": ["text"],
            },
        },
    },
}

# 工具名 -> 实现函数
TOOL_IMPLEMENTATIONS: Dict[str, Callable[..., str]] = {
    "web_search": web_search,
    "execute_python": execute_python,
    "calculate": calculate,
    "descriptive_stats": descriptive_stats,
    "count_characters": count_characters,
}