# ip-query

## 功能

查询公网 IP 地址及其地理位置信息。当需要知道当前网络环境 IP、判断用户所在地区、或排查网络问题时使用。

## 使用方法

将此文件内容放入 AI Agent 的系统提示词或 Skill 配置中，Agent 即可自动调用。

## 工具定义

### tool: ip_query

**description:** 查询当前公网 IP 地址。免费模式返回纯文本 IP，带 API Key 返回地理位置详情（国家、城市、ASN）。

**parameters:**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| key | string | 否 | - | API Key。不填只返回纯文本 IP；填写后返回完整 JSON |

**api endpoint:**

```
GET https://ip.shxai.space?key={key}
```

**free endpoint:**

```
GET https://ip.shxai.space
```

**response (free):**

返回纯文本，直接就是 IP 地址字符串。

```
1.2.3.4
```

**response (with key):**

```json
{
  "ip": "1.2.3.4",
  "country": "US",
  "city": "San Francisco",
  "region": "California",
  "timezone": "America/Los_Angeles",
  "asn": 13335,
  "colo": "SFO",
  "http": "HTTP/2"
}
```

**error responses:**

| HTTP 状态 | 说明 |
|--------|------|
| 401 | 缺少 API Key（请求 JSON 但未传 key） |
| 403 | API Key 无效 |

## 示例

```bash
curl https://ip.shxai.space
# → 1.2.3.4

curl "https://ip.shxai.space?key=sk-xxxxx"
# → {"ip":"1.2.3.4","country":"US","city":"San Francisco",...}
```

## 获取 API Key

访问 [shxai.space](https://shxai.space) 注册获取。

---

> Skill 版本: 1.0 | 平台: shxai.space | 更新: 2026-08