CC-Switch/docs/user-manual/zh/2-providers/2.5-usage-query.md

# 2.5 用量查询

CC Switch 的配额/余额展示分为两大类：**自动查询**（官方订阅类，开箱即用）和**手动启用**（内置模板 + 自定义脚本，需要用户配置后再显示）。

| 类别                       | 范围                                                                  | 是否需要用户启用 |
| -------------------------- | --------------------------------------------------------------------- | ---------------- |
| **自动查询**               | Claude / Codex / Gemini 官方订阅、GitHub Copilot、Codex OAuth 反向代理 | 否（默认启用）   |
| **手动启用（内置模板）**   | Token Plan、第三方余额查询                                            | 是（见下文）     |
| **手动启用（自定义脚本）** | 未被内置模板覆盖的中转服务、私有部署、特殊 API                        | 是（见下文）     |

## 自动查询（官方订阅类）

v3.13.0 起，以下三类供应商在启用后会**自动**在卡片底部显示配额，用户无需任何额外配置：

| 类别            | 覆盖供应商                                | 显示内容                    |
| --------------- | ----------------------------------------- | --------------------------- |
| 官方订阅        | Claude / Codex / Gemini 官方登录          | 官方订阅配额                |
| GitHub Copilot  | Copilot 供应商卡片                        | Premium interactions 剩余量 |
| Codex OAuth     | Codex OAuth 反向代理卡片（Claude 供应商） | ChatGPT 账号 Codex 配额     |

这三类的共同特点是**数据来源唯一且语义明确**（官方订阅的使用率），不存在歧义，因此 CC Switch 直接调用对应的官方或 OAuth 查询接口。

### 自动查询的交互

- **卡片底部显示**：使用百分比 + 重置倒计时，颜色随使用率变化（< 70% 绿 / 70–89% 橙 / ≥ 90% 红）
- **手动刷新**：点击卡片上的刷新图标按钮重新查询
- **卡片简化**：对这三类供应商，**健康检查**和**用量查询配置**按钮会被自动隐藏，避免干扰内置展示
- **会话过期提示**：如果 Token 无法刷新，卡片会显示「会话已过期」警告（Copilot / Codex OAuth）

---

## 手动启用（内置模板 + 自定义脚本）

除了上述三类自动查询的供应商，**所有其他供应商**（包括 Token Plan、第三方余额查询、以及各类中转服务）都需要在供应商卡片上**手动打开「用量查询」开关**后才会显示配额。

### 为什么需要手动启用？

一个重要原因是：**同一个请求地址（同一家供应商）可能同时提供多种查询模式** —— 既可能有按套餐的配额查询，也可能有按账户余额的查询。CC Switch 无法自动推断你想查哪一种，所以这类供应商的内置查询**默认关闭**，由你选择合适的模板后启用。

### 覆盖的内置模板

v3.13.0 为以下类别提供了**开箱即用的内置模板**，启用后无需手写脚本：

| 类别       | 覆盖供应商                                                | 模板类型                |
| ---------- | --------------------------------------------------------- | ----------------------- |
| Token Plan | Kimi / Zhipu GLM / MiniMax                                | 套餐配额（带使用进度）  |
| 第三方余额 | DeepSeek / StepFun / SiliconFlow / OpenRouter / Novita AI | 官方余额查询            |

> 💡 除了以上内置模板外，对未被覆盖的供应商，你可以使用**自定义脚本**方式（见下文）编写自己的查询逻辑。

### 启用步骤

1. 鼠标悬停在供应商卡片上，显示操作按钮
2. 点击 **用量查询** 按钮（📊 图标）
3. 在配置面板顶部打开 **启用用量查询** 开关
4. 选择合适的内置模板（例如 Token Plan、第三方余额）或选择「自定义」
5. 按需填入 API Key / Base URL / Access Token 等参数（大多数情况可留空，使用供应商本身的凭据）
6. 点击「测试脚本」确认能正常返回
7. 保存配置 —— 下次激活该供应商时，配额将显示在卡片底部

> ⚠️ **注意**：启用后的自动刷新间隔通过「自动查询间隔」字段控制（设为 `0` 禁用自动刷新），仅当供应商处于「当前启用」状态时才会触发后台查询。

---

## 自定义脚本查询（高级）

### 功能说明

当供应商**不在内置模板覆盖范围**内时，你可以用 JavaScript 编写自定义查询脚本。适用于中转服务、私有部署、特殊格式 API 等。

**使用场景**：
- 查看 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` | string | 否 | 额外展示文本 |

## 测试脚本

配置完成后，点击「测试脚本」按钮验证：

1. 发送请求到配置的 URL
2. 执行提取器函数
3. 显示返回结果或错误信息

## 显示效果

配置成功后，供应商卡片上会显示：

- **单套餐**：直接显示剩余额度
- **多套餐**：显示套餐数量，点击展开查看详情

## 变量占位符

脚本中可使用以下占位符，运行时自动替换：

| 占位符 | 说明 |
|--------|------|
| `{{apiKey}}` | 配置的 API Key |
| `{{baseUrl}}` | 配置的 Base URL |
| `{{accessToken}}` | 配置的 Access Token（New API） |
| `{{userId}}` | 配置的 User ID（New API） |

## 常见供应商配置示例

### 故障排除

### 自动查询未显示配额（官方订阅类）

**检查**：
1. 确认供应商是官方订阅类 —— Claude / Codex / Gemini 官方登录、GitHub Copilot、Codex OAuth 反向代理
2. 供应商是否处于「当前启用」状态（非激活时不会触发查询）
3. 对于 OAuth 类型（Copilot / Codex OAuth），检查 Token 是否仍在有效期内；如果卡片显示「会话已过期」，请到 **OAuth 认证中心**重新登录
4. 网络是否可访问官方配额接口

### 手动启用后仍未显示配额

**检查**：
1. 供应商卡片的「用量查询」面板顶部**启用用量查询**开关是否已打开
2. 是否选择了合适的内置模板（Token Plan / 第三方余额 / 自定义）
3. 点击「测试脚本」查看返回的具体错误信息
4. API Key / Base URL 等必要字段是否填写正确
5. 网络是否可访问供应商的配额端点
6. 仅当供应商处于「当前启用」状态时，后台自动查询才会生效

### 查询失败

**检查**：
1. API Key 是否正确
2. Base URL 是否正确
3. 网络是否可访问
4. 超时时间是否足够

### 返回数据为空

**检查**：
1. 提取器函数是否有 `return` 语句
2. 响应数据结构是否与提取器匹配
3. 使用「测试脚本」查看原始响应

### 格式化失败

脚本语法错误时，点击「格式化」按钮会提示错误位置。

## 注意事项

- 用量查询会消耗少量 API 请求配额
- 建议设置合理的自动查询间隔，避免频繁请求
- 敏感信息（API Key、Token）会安全存储在本地