mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-23 17:45:28 +08:00
bbed2a1fe1
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
182 lines
4.3 KiB
Markdown
182 lines
4.3 KiB
Markdown
# 2.5 用量查询
|
||
|
||
## 功能说明
|
||
|
||
用量查询功能允许你配置自定义脚本，实时查询供应商的剩余额度、已用量等信息。
|
||
|
||
**使用场景**：
|
||
- 查看 API 账户剩余余额
|
||
- 监控套餐使用情况
|
||
- 多套餐额度汇总显示
|
||
|
||
## 打开配置
|
||
|
||
1. 鼠标悬停在供应商卡片上，显示操作按钮
|
||
2. 点击「用量查询」按钮（📊 图标）
|
||
3. 打开用量查询配置面板
|
||
|
||
## 启用用量查询
|
||
|
||
在配置面板顶部，开启「启用用量查询」开关。
|
||
|
||
## 预设模板
|
||
|
||
CC Switch 提供三种预设模板：
|
||
|
||
### 自定义模板
|
||
|
||
完全自定义请求和提取逻辑，适用于特殊 API 格式。
|
||
|
||
### 通用模板
|
||
|
||
适用于大多数标准 API 格式的供应商：
|
||
|
||
```javascript
|
||
({
|
||
request: {
|
||
url: "{{baseUrl}}/user/balance",
|
||
method: "GET",
|
||
headers: {
|
||
"Authorization": "Bearer {{apiKey}}",
|
||
"User-Agent": "cc-switch/1.0"
|
||
}
|
||
},
|
||
extractor: function(response) {
|
||
return {
|
||
isValid: response.is_active || true,
|
||
remaining: response.balance,
|
||
unit: "USD"
|
||
};
|
||
}
|
||
})
|
||
```
|
||
|
||
**配置参数**：
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| API Key | 用于认证的密钥（可选，留空则使用供应商配置的 Key） |
|
||
| Base URL | API 基础地址（可选，留空则使用供应商端点） |
|
||
|
||
### New API 模板
|
||
|
||
专为 New API 类型的中转服务设计：
|
||
|
||
```javascript
|
||
({
|
||
request: {
|
||
url: "{{baseUrl}}/api/user/self",
|
||
method: "GET",
|
||
headers: {
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer {{accessToken}}",
|
||
"New-Api-User": "{{userId}}"
|
||
},
|
||
},
|
||
extractor: function (response) {
|
||
if (response.success && response.data) {
|
||
return {
|
||
planName: response.data.group || "默认套餐",
|
||
remaining: response.data.quota / 500000,
|
||
used: response.data.used_quota / 500000,
|
||
total: (response.data.quota + response.data.used_quota) / 500000,
|
||
unit: "USD",
|
||
};
|
||
}
|
||
return {
|
||
isValid: false,
|
||
invalidMessage: response.message || "查询失败"
|
||
};
|
||
},
|
||
})
|
||
```
|
||
|
||
**配置参数**：
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| Base URL | New API 服务地址 |
|
||
| Access Token | 访问令牌 |
|
||
| User ID | 用户 ID |
|
||
|
||
## 通用配置
|
||
|
||
### 超时时间
|
||
|
||
请求超时时间（秒），默认 10 秒。
|
||
|
||
### 自动查询间隔
|
||
|
||
自动刷新用量数据的间隔（分钟）：
|
||
- 设为 `0` 表示禁用自动查询
|
||
- 范围：0-1440 分钟（最长 24 小时）
|
||
- 仅当供应商处于「当前启用」状态时生效
|
||
|
||
## 提取器返回格式
|
||
|
||
提取器函数需要返回包含以下字段的对象：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `isValid` | boolean | 否 | 账户是否有效，默认 true |
|
||
| `invalidMessage` | string | 否 | 无效时的提示信息 |
|
||
| `remaining` | number | 是 | 剩余额度 |
|
||
| `unit` | string | 是 | 单位（如 USD、CNY、次） |
|
||
| `planName` | string | 否 | 套餐名称（支持多套餐） |
|
||
| `total` | number | 否 | 总额度 |
|
||
| `used` | number | 否 | 已使用额度 |
|
||
| `extra` | object | 否 | 额外信息 |
|
||
|
||
## 测试脚本
|
||
|
||
配置完成后，点击「测试脚本」按钮验证：
|
||
|
||
1. 发送请求到配置的 URL
|
||
2. 执行提取器函数
|
||
3. 显示返回结果或错误信息
|
||
|
||
## 显示效果
|
||
|
||
配置成功后，供应商卡片上会显示：
|
||
|
||
- **单套餐**：直接显示剩余额度
|
||
- **多套餐**：显示套餐数量，点击展开查看详情
|
||
|
||
## 变量占位符
|
||
|
||
脚本中可使用以下占位符，运行时自动替换：
|
||
|
||
| 占位符 | 说明 |
|
||
|--------|------|
|
||
| `{{apiKey}}` | 配置的 API Key |
|
||
| `{{baseUrl}}` | 配置的 Base URL |
|
||
| `{{accessToken}}` | 配置的 Access Token（New API） |
|
||
| `{{userId}}` | 配置的 User ID（New API） |
|
||
|
||
## 常见供应商配置示例
|
||
|
||
### 故障排除
|
||
|
||
### 查询失败
|
||
|
||
**检查**：
|
||
1. API Key 是否正确
|
||
2. Base URL 是否正确
|
||
3. 网络是否可访问
|
||
4. 超时时间是否足够
|
||
|
||
### 返回数据为空
|
||
|
||
**检查**：
|
||
1. 提取器函数是否有 `return` 语句
|
||
2. 响应数据结构是否与提取器匹配
|
||
3. 使用「测试脚本」查看原始响应
|
||
|
||
### 格式化失败
|
||
|
||
脚本语法错误时，点击「格式化」按钮会提示错误位置。
|
||
|
||
## 注意事项
|
||
|
||
- 用量查询会消耗少量 API 请求配额
|
||
- 建议设置合理的自动查询间隔，避免频繁请求
|
||
- 敏感信息（API Key、Token）会安全存储在本地
|