04 · 工具系统：给 Agent 装上双手

# 反面教材：模型不知道什么时候该用、参数什么格式 → 乱用
Tool(name="calc", description="计算", parameters={...})

# 正面教材：说清场景、边界、例子 → 用得准
Tool(name="calculator",
     description="计算数学表达式的值，支持 + - * / % ** 、括号、小数。"
                 "涉及任何算术（哪怕很简单）都应该用它，不要心算，心算容易错。",
     ...)

@dataclass
class Tool:
    name: str          # 英文名，模型靠它点名
    description: str   # 中文说明书，模型靠它决策
    parameters: dict   # 参数 JSON Schema，模型靠它拼参数
    func: Callable     # 真正干活的函数

class Registry:
    def schemas(self):            # 翻译成 OpenAI 协议格式发给模型
        return [{"type": "function", "function": {...}} for t in ...]

    def call(self, name, arguments_json):
        # 1. json.loads 解析参数   2. 执行函数   3. 一切异常 → 错误文本
        # 4. 结果截断到 2000 字符（太长会撑爆上下文）

def _tokenize(expr):   # 词法分析："1+2*3" → [("num",1),("op","+"),("num",2),("op","*"),("num",3)]
    token_re = re.compile(r"\s*(?:(\d+\.\d*|\.\d+|\d+)|(\*\*|[+\-*/%()]))")
    ...                # 任何不认识的字符在这里被拒——白名单边界

class _Parser:         # 语法分析：优先级写在"调用层级"里
    def expr(self):    # 加减（最低优先级）
    def term(self):    # 乘除取余
    def power(self):   # 幂（右结合）
    def atom(self):    # 数字和括号（最高）

def _resolve_in_sandbox(base, rel_path):
    target = (base / rel_path).resolve()
    if target != base and base not in target.parents:
        raise ValueError(f"路径越界：{rel_path} 不在沙箱目录内")   # ../../.env 到此为止
    return target

def _check_url(url):
    if parsed.scheme not in ("http", "https"): raise ...   # 1. 协议白名单
    for info in socket.getaddrinfo(host, port, ...):
        ip = ipaddress.ip_address(info[4][0])
        if ip.is_private or ip.is_loopback or ip.is_link_local or ...:
            raise ValueError(...)                           # 2. 解析后逐 IP 校验

def _safe_get(url, max_redirects=3):   # 3. 关自动重定向，手动逐跳重新校验
    ...

# 1. 写函数（返回字符串！）
def roll_dice(sides: int = 6) -> str:
    import random
    return f"掷出了 {random.randint(1, sides)} 点（{sides} 面骰）"

# 2. 配说明书
reg.register(Tool(
    name="roll_dice",
    description="掷一个骰子，返回随机点数。用户想抽签、做随机决定时使用。",
    parameters={
        "type": "object",
        "properties": {"sides": {"type": "integer", "description": "面数，默认 6"}},
    },
    func=roll_dice,
))