# 实用工具

`/tools` 端点是公共工具 — 无需认证。对于需要服务器时间、安全数学计算或随机值的 LLM Agent 很有用。

## GET /tools/time

获取当前服务器时间、时区与 UTC 偏移。

```bash
curl https://synapse.schaefer.zone/tools/time
```

响应：

```json
{
  "time": "2026-06-27T14:30:00.000Z",
  "timezone": "Europe/Berlin",
  "offset": 120
}
```

用例：LLM Agent 需要知道“现在是几点”，用于调度、时间戳或相对日期计算。

## GET /tools/calc

安全计算器 — 仅支持算术运算，不使用 `eval()`。支持 `+`、`-`、`*`、`/`、`%`、`(`、`)` 和数字。

```bash
curl "https://synapse.schaefer.zone/tools/calc?expr=(10+5)*3"
```

响应：

```json
{
  "result": 45,
  "expr": "(10+5)*3"
}
```

> [!TIP]
> 用它代替在脑中计算或字符串解析。它既安全（无法注入代码）又准确。

### 支持的运算符

- `+` 加法
- `-` 减法
- `*` 乘法
- `/` 除法
- `%` 取模
- `(` `)` 括号
- 数字（整数与小数）

### 示例

```bash
curl ".../tools/calc?expr=2+2"          # → 4
curl ".../tools/calc?expr=3.14*100"     # → 314
curl ".../tools/calc?expr=100%7"        # → 2
curl ".../tools/calc?expr=(2+3)*4-1"    # → 19
```

## GET /tools/random

生成随机值。

```bash
# UUID v4
curl "https://synapse.schaefer.zone/tools/random?type=uuid"
# → { "value": "a1b2c3d4-...", "type": "uuid" }

# 整数（默认范围 0-100）
curl "https://synapse.schaefer.zone/tools/random?type=int&min=1&max=10"
# → { "value": 7, "type": "int" }

# 浮点数
curl "https://synapse.schaefer.zone/tools/random?type=float&min=0&max=1"
# → { "value": 0.7234, "type": "float" }

# 十六进制字符串
curl "https://synapse.schaefer.zone/tools/random?type=hex&min=8&max=16"
# → { "value": "a3f7b2c1", "type": "hex" }

# 字母字符串
curl "https://synapse.schaefer.zone/tools/random?type=alpha&min=8&max=12"
# → { "value": "kQmzPwXn", "type": "alpha" }
```

### 类型参数

| 类型 | 参数 | 输出 |
|------|-----------|--------|
| `uuid` | 无 | UUID v4 字符串 |
| `int` | `min`、`max`（默认 0-100） | 整数 |
| `float` | `min`、`max`（默认 0-100） | 浮点数 |
| `hex` | `min`、`max`（长度范围，默认 8-16） | 十六进制字符串 |
| `alpha` | `min`、`max`（长度范围，默认 8-16） | 字母字符串 |

## LLM Agent 的用例

### 生成唯一 ID

```bash
ID=$(curl -s .../tools/random?type=uuid | jq -r .value)
curl -X POST .../memory -d "{\"key\": \"task_$ID\", ...}"
```

### 计算百分比

```bash
TOTAL=142
DONE=87
PERCENT=$(curl -s ".../tools/calc?expr=($DONE*100)/$TOTAL" | jq -r .result)
echo "Progress: $PERCENT%"
```

### 获取当前时间戳

```bash
NOW=$(curl -s .../tools/time | jq -r .time)
curl -X POST .../var -d "{\"key\": \"last_run\", \"value\": \"$NOW\"}"
```

### 生成测试数据

```bash
for i in {1..10}; do
  NAME=$(curl -s ".../tools/random?type=alpha&min=5&max=10" | jq -r .value)
  curl -X POST .../memory -d "{\"key\": \"test_$i\", \"content\": \"$NAME\"}"
done
```

## 下一步

- [API 概览](/docs/api/overview) — 所有端点分组
- [错误与错误处理](/docs/api/errors)