back
loading skill details...
快代理(Kuaidaili)智能管理技能,专为快代理用户设计。支持API配置、订单信息获取、到期提醒、IP健康检测、智能并发调度、使用统计。触发场景:(1) 用户提及"快代理"、"kuaidaili"、"kdlapi"、"代理IP";(2) 用户需要检查快代理订单状态、IP质量、并发设置;(3) 用户使用命令 s...
---
name: proxy-ip-manager
description: '快代理(Kuaidaili)智能管理技能,专为快代理用户设计。支持API配置、订单信息获取、到期提醒、IP健康检测、智能并发调度、使用统计。触发场景:(1) 用户提及"快代理"、"kuaidaili"、"kdlapi"、"代理IP";(2) 用户需要检查快代理订单状态、IP质量、并发设置;(3) 用户使用命令 set_config/show_config/get_order_info/check_expiry/check_ip_health/get_concurrency/stats。此技能仅支持快代理服务。'
---
# 快代理智能管理器
专为快代理(Kuaidaili)用户打造的代理IP智能管理技能。
## 快速开始
首次使用需要配置快代理API密钥:
```
用户: set_config secret_id=example_id123 secret_key=example_key456
```
⚠️ **安全提示**:
- **请在私聊中配置密钥**,不要在群聊中发送,避免泄露给他人
- 密钥仅保存在你的本地设备,不会上传或分享
- 配置后使用 `show_config` 查看的是脱敏后的信息
**密钥获取方式**:
1. 登录快代理会员中心:https://www.kuaidaili.com/uc/overview/
2. 进入「API密钥管理」页面
3. 获取订单的 `SecretId` 和 `SecretKey`
**认证流程**:
系统会自动调用 `https://auth.kdlapi.com/api/get_secret_token` 获取 `secret_token` 作为签名凭证。
配置成功后可使用所有功能。
---
## 命令列表
| 命令 | 功能 | 示例 |
|------|------|------|
| `set_config` | 配置API密钥 | `set_config secret_id=xxx secret_key=xxx` |
| `show_config` | 显示当前配置(脱敏) | `show_config` |
| `get_order_info` | 获取订单详情 | `get_order_info` |
| `get_ip` | 获取代理IP | `get_ip` 或 `get_ip num=5` |
| `check_expiry` | 检查到期时间 | `check_expiry` |
| `check_ip_health` | IP健康检测 | `check_ip_health` |
| `get_concurrency` | 智能并发推荐 | `get_concurrency` |
| `stats` | 使用统计报告 | `stats` |
---
## 获取代理IP
配置 secret_id 和 secret_key 后,可以获取对应订单的代理IP。
### 命令
```
get_ip # 获取代理IP(默认1个)
get_ip num=5 # 指定获取数量
```
### 支持的产品类型
| 产品类型 | API接口 | 说明 |
|---------|---------|------|
| 隧道代理Pro | `https://tps.kdlapi.com/api/tpsprocurrentip` | 获取当前隧道IP |
| 隧道代理 | `https://tps.kdlapi.com/api/tpscurrentip` | 获取当前隧道IP |
| 私密代理 | `https://dps.kdlapi.com/api/getdps` | 提取IP,支持 `num` 参数 |
| 独享代理 | `https://kps.kdlapi.com/api/getkps` | 提取IP |
| 海外动态代理 | `https://fps.kdlapi.com/api/getfps` | 获取隧道IP |
| 海外静态住宅 | `https://dev.kdlapi.com/api/getsfps` | 获取静态住宅IP |
### 请求参数
| 参数 | 说明 |
|------|------|
| `secret_id` | 用户密钥ID(必填) |
| `signature` | 签名/令牌(必填,系统自动获取) |
| `num` | 提取数量(仅私密代理支持,默认1) |
### 调用示例
**隧道代理Pro当前IP**:
```
GET https://tps.kdlapi.com/api/tpsprocurrentip?secret_id=example_id&signature=xxx
```
⚠️ **限制**:仅支持换IP周期 >= 30秒的隧道订单,否则返回错误码 `-4`
**隧道代理当前IP**:
```
GET https://tps.kdlapi.com/api/tpscurrentip?secret_id=example_id&signature=xxx
```
⚠️ **限制**:仅支持换IP周期 >= 30秒的隧道订单,否则返回错误码 `-4`
**私密代理IP(支持数量)**:
```
GET https://dps.kdlapi.com/api/getdps?secret_id=example_id&num=5&signature=xxx
```
**独享代理IP**:
```
GET https://kps.kdlapi.com/api/getkps?secret_id=example_id&signature=xxx
```
**海外动态代理隧道IP**:
```
GET https://fps.kdlapi.com/api/getfps?secret_id=example_id&signature=xxx
```
**海外静态住宅IP**:
```
GET https://dev.kdlapi.com/api/getsfps?secret_id=example_id&signature=xxx
```
### 返回格式
```json
{
"code": 0,
"msg": "",
"data": {
"ip_list": ["1.2.3.4:5678", "5.6.7.8:9012"]
}
}
```
---
## 订单信息API
### 获取订单详情
**接口**:`GET https://dev.kdlapi.com/api/getorderinfo`
**返回字段**:
### 公共字段(所有产品)
| 字段 | 说明 |
|------|------|
| `orderid` | 订单ID |
| `product` | 产品类型 |
| `status` | 订单状态 |
| `pay_type` | 付费方式 |
| `expire_time` | 到期时间(仅包年包月订单) |
### 隧道代理 (TPS) 特有字段
| 字段 | 说明 |
|------|------|
| `tunnel_host` | 代理主机 |
| `tunnel_port_http` | HTTP端口 |
| `tunnel_username` | 认证用户名 |
| `tunnel_password` | 认证密码 |
| `tunnel_req` | 并发上限 |
| `tunnel_bandwidth` | 带宽(Mbps) |
### 私密代理 (DPS) 特有字段
| 字段 | 说明 |
|------|------|
| `proxy_username` | 认证用户名 |
| `proxy_password` | 认证密码 |
### 独享代理 (KPS) 特有字段
| 字段 | 说明 |
|------|------|
| `proxy_count` | 独享代理数量 |
| `proxy_username` | 认证用户名 |
| `proxy_password` | 认证密码 |
### 海外动态代理 (FPS) 特有字段
| 字段 | 说明 |
|------|------|
| `proxy_username` | 认证用户名 |
| `proxy_password` | 认证密码 |
| `transfer_area` | 转发地区(如 US、JP、UK) |
| `fps_host` | 隧道主机 |
| `fps_port_http` | HTTP端口 |
| `fps_port_socks` | SOCKS端口 |
### 海外静态代理 (FPS_STATIC) 特有字段
| 字段 | 说明 |
|------|------|
| `proxy_count` | 代理数量 |
| `proxy_username` | 认证用户名(包段订单返回) |
| `proxy_password` | 认证密码(包段订单返回) |
**注意**:不同产品返回的字段不同,带宽和并发仅隧道代理(TPS)返回。详见 [references/api_response.md](references/api_response.md)
### 获取到期时间
**接口**:`GET https://dev.kdlapi.com/api/getorderexpiretime`
**返回字段**:
| 字段 | 说明 |
|------|------|
| `expire_time` | 到期时间(格式:YYYY-MM-DD HH:MM:SS) |
详见 [references/api_response.md](references/api_response.md)
---
## 配置管理
### 初始化检查
运行 `scripts/config_manager.py` 检查配置状态:
- 未配置 → 提示用户使用 `set_config`
- 已配置 → 验证密钥有效性
### 配置存储
配置保存在 `~/.openclaw/skills/proxy-ip-manager/config.json`:
```json
{
"secret_id": "example_id123",
"secret_key": "example_key456",
"secret_token": "自动获取的令牌",
"token_expire_time": "令牌过期时间",
"test_url": "https://httpbin.org/ip",
"timeout": 5,
"configured_at": "YYYY-MM-DDTHH:MM:SS"
}
```
### 认证流程
1. 用户提供 `secret_id` 和 `secret_key`
2. 系统调用 `https://auth.kdlapi.com/api/get_secret_token` 获取 `secret_token`
3. `secret_token` 作为 `signature` 参数调用各API
### 安全脱敏
日志和输出中自动脱敏:
- `secret_id=exam***d123`
- `secret_key=exa***y456`
- `secret_token=自动脱敏`
---
## API调用规范
使用 `scripts/api_client.py` 封装所有API调用:
```python
# 自动特性
- 超时控制(5秒)
- 自动重试(最多3次)
- 错误处理和脱敏日志
```
### 返回字段解析
详见 [references/api_response.md](references/api_response.md)
关键字段:
- `ip_list` → 代理IP列表
- `max_concurrency` → 并发上限
- `expire_time` → 订单到期时间
- `username/password/host/port` → 认证信息
---
## 订单到期模块
运行 `scripts/expiry_checker.py`:
### 提醒规则
| 剩余天数 | 状态 | 提示级别 |
|---------|------|---------|
| >5天 | 正常 | 无 |
| 3-5天 | 注意 | 5天提醒 |
| 1-3天 | 警告 | 3天提醒 |
| <1天 | 紧急 | 1天提醒 |
| ≤0天 | 已过期 | 停止服务 |
### 过期处理
订单过期后:
- 并发 = 0
- 停止健康检测
- 状态标记为 `expired`
- 提示续费链接:https://www.kuaidaili.com/uc/order-list/
---
## IP健康检测
运行 `scripts/health_checker.py`:
### 检测流程
1. 从API获取多个代理IP
2. 使用 test_url 发请求测试
3. 记录成功/失败、响应延迟、状态码
### 评分算法
详见 [references/scoring_rules.md](references/scoring_rules.md)
```
score = success_rate * 70 + latency_score * 30
latency评分:
- <1s → 100分
- 1~3s → 80分
- >3s → 50分
```
### 输出指标
- IP质量评分(0-100)
- 成功率(%)
- 平均延迟(ms)
---
## 智能并发调度
运行 `scripts/scheduler.py`:
### 动态调整策略
| success_rate | 并发调整 |
|-------------|---------|
| >95% | base * 1.0 |
| 80-95% | base * 0.7 |
| 60-80% | base * 0.5 |
| <60% | base * 0.3 |
base = max_concurrency * 0.8
### 失败保护
- 连续失败 > 10 → 并发降低50%
- success_rate < 50% → 并发降至最低
---
## 使用统计
运行 `scripts/stats_tracker.py`:
### 统计内容
- 每日请求数
- 成功数/失败数
- 成功率
- 最近7天趋势
### 状态评估
| 成功率趋势 | 状态 |
|-----------|------|
| 稳定在90%+ | 稳定 |
| 波动10%以内 | 波动 |
| 波动>10%或<70% | 风险 |
---
## 异常处理
### API错误码对照
**隧道代理 (TPS) 错误码**:
| 错误码 | 说明 |
|-------|------|
| `-4` | 换IP周期不足30秒(仅支持换IP周期>=30秒的订单) |
**私密代理 (DPS) 错误码**:
| 错误码 | 说明 |
|-------|------|
| `1` | 今日提取余额已用尽 |
| `2` | 订单提取余额已用尽 |
| `3` | 没有找到符合条件的代理 |
| `4` | 账号尚未通过实名认证 |
| `-1` | 无效请求 |
| `-2` | 订单无效(刚下单需等待1分钟生效) |
| `-3` | 参数错误 |
| `-4` | 提取失败 |
| `-5` | 此订单不能提取私密代理 |
| `-6` | 调用IP不在白名单内 |
| `-51` | 订单1分钟内调用IP超限 |
| `-16` | 订单已退款 |
| `-15/-13` | 订单已过期 |
| `-14` | 订单被封禁(联系客服) |
| `-12` | 订单无效 |
| `-11` | 订单尚未支付 |
**独享代理 (KPS) 错误码**:
| 错误码 | 说明 |
|-------|------|
| `2` | 订单已过期 |
| `3` | 没有找到符合条件的代理 |
| `4` | 账号尚未通过实名认证 |
| `-1` | 无效请求 |
| `-2` | 订单无效(刚下单需等待1分钟生效) |
| `-3` | 参数错误 |
| `-4` | 提取失败 |
| `-5` | 此订单不能提取独享代理 |
| `-51` | 订单1分钟内调用IP超限 |
| `-16/-15/-13` | 订单已过期/退款 |
| `-14` | 订单被封禁(联系客服) |
| `-12/-11` | 订单无效/未支付 |
**海外动态代理 (FPS) 错误码**:
| 错误码 | 说明 |
|-------|------|
| `2` | 订单已过期 |
| `3` | 暂无可用代理 |
| `4` | 账号尚未通过实名认证 |
| `-1/-2/-3/-4` | 无效请求/订单无效/参数错误/提取失败 |
| `-5` | 此订单不能提取海外代理动态住宅 |
| `-51` | 订单1分钟内调用IP超限 |
| `-16/-15/-13/-14/-12/-11` | 订单状态异常(过期/退款/封禁等) |
**海外静态住宅 (FPS_STATIC) 错误码**:
| 错误码 | 说明 |
|-------|------|
| `2` | 订单已过期 |
| `3` | 没有找到符合条件的代理 |
| `4` | 账号尚未通过实名认证 |
| `-1/-2/-3/-4` | 无效请求/订单无效/参数错误/提取失败 |
| `-5` | 此订单不能提取海外代理静态住宅 |
| `-51` | 订单1分钟内调用IP超限 |
| `-16/-15/-13/-14/-12/-11` | 订单状态异常(过期/退款/封禁等) |
**公共错误码**:
| 错误码 | 说明 | 通用解决方案 |
|-------|------|---------|
| `-2` | 订单无效(刚下单) | 等待1分钟自动生效 |
| `-5` | 产品类型不匹配 | 确认订单产品类型与API对应 |
| `-51` | 调用IP数量超限 | 控制调用频率 |
| `-15/-13` | 订单已过期 | 续费或重新下单 |
| `-14` | 订单被封禁 | 联系客服处理 |
**其他异常**:
| 异常类型 | 输出提示 |
|---------|---------|
| 未配置 | "请先配置代理API密钥(使用 set_config)" |
| API调用失败 | "代理API调用失败,请检查API密钥是否有效" |
| 数据异常 | "API返回数据异常,请联系服务提供方" |
| 网络错误 | "网络连接失败,请检查网络环境" |
---
## 订单到期提醒
### 命令
```
check_expiry # 检查到期时间,输出提醒信息
```
### 输出格式
返回 JSON 格式,包含:
- `need_notify`: 是否需要提醒(true/false)
- `days_left`: 剩余天数
- `expire_time`: 到期时间
- `notification_text`: 格式化的提醒文本
### 提醒规则
| 剩余天数 | 级别 | 说明 |
|---------|------|------|
| 5天 | 📅 提醒 | 请安排续费 |
| 3天 | ⚠️ 警告 | 请尽快续费 |
| 1天 | 🚨 紧急 | 请立即续费 |
| 已过期 | 🚨 紧急 | 已过期,立即续费 |
### 配置定时提醒
用户可自行配置定时任务,调用脚本获取提醒信息后发送通知:
**脚本路径**(相对于 skill 目录):
```
scripts/expiry_notify.py
```
或使用绝对路径(将 `<USER>` 替换为你的用户名):
```
C:\Users\<USER>\.openclaw\skills\proxy-ip-manager\scripts\expiry_notify.py
```
**示例输出**(需要提醒时):
```json
{
"need_notify": true,
"days_left": 3,
"expire_time": "YYYY-MM-DD HH:MM:SS",
"notification_text": "⚠️【快代理订单到期警告】\n\n快代理订单将在3天后到期,请尽快续费。\n\n到期时间:YYYY-MM-DD HH:MM:SS\n剩余天数:3 天\n续费链接:https://www.kuaidaili.com/uc/order-list/"
}
```
---
## 脚本文件
| 脚本 | 用途 |
|------|------|
| `scripts/config_manager.py` | 配置管理(存储、读取、验证) |
| `scripts/api_client.py` | 代理IP获取 |
| `scripts/order_info.py` | 订单信息查询 |
| `scripts/expiry_checker.py` | 订单到期检查 |
| `scripts/health_checker.py` | IP健康检测 |
| `scripts/scheduler.py` | 智能并发调度 |
| `scripts/stats_tracker.py` | 使用统计 |don't have the plugin yet? install it then click "run inline in claude" again.