usage-probe

用量查询辅助（usage-probe）

这是什么

供应商的用量/余额显示在「设置 → 配置管理 → 模型/认证」的 供应商卡片底部 （学 cc-switch：所有卡片同一位置、右对齐：相对时间 + 彩色数值 + 刷新按钮）。 支持分三层：

1. 内置模板（零配置）：命中内置候选的供应商开箱即用，弹窗里已识别、无需配置。 当前内置：
   • 官方余额：DeepSeek（/user/balance）、OpenRouter（/api/v1/key per-key 额度）、 Moonshot 官方余额（/users/me/balance）；
   • 套餐额度：Kimi For Coding（/usages，含 Boost 点数）、智谱 GLM Coding Plan （5h 滚动窗 / 周窗 / MCP 月度窗）、OpenCode Go（/usage 三档百分比）；
   • 官方订阅（登录态 OAuth，凭据来自 auth.json）：Codex/ChatGPT（/wham/usage）、 xAI Grok（billing 预检链）；
   • 通用 OpenAI 兼容网关兜底：实现了官方 /v1/usage（{ balance, unit }）的中转站自动显示余额。
2. 声明式模板（弹窗内可选）：不在内置列表时，弹窗提供两个模板——
   • 通用模板：请求 /usage（OpenAI 兼容），API Key / 请求地址可覆盖（留空用供应商的）；
   • New API：New API / OneAPI 中转站，填 访问令牌 + 用户 ID（积分自动换算）。
3. 旧版探针数组（AI 兜底）：上面都覆盖不了的接口（如自建网关的自定义余额端点）， 由 AI 写 ~/.pi/agent/usage-probes.json 的 probes 数组（见下文），运行时按 baseUrl 关键字匹配合入探测。

配置文件位置（和 models.json 同一个目录）：

~/.pi/agent/usage-probes.json

改完立刻生效（无需重启）。顶层 providers 映射由弹窗维护，AI 不要手改； probes 数组才是开放给 AI 写的部分。

改完立刻生效（无需重启），下次打开供应商卡片就能读到新配置。

你（AI）的工作流程

当用户说「帮我让 XX 供应商显示用量」时，按下面顺序做：

1. 先判断是否已内置：读 ~/.pi/agent/models.json 找到该 provider 的 baseUrl， 对照上面的内置清单。命中就直接告诉用户「已内置，无需配置，卡片底部会自动显示」， 不需要写任何文件。apiKey 的位置不用读出来，也不要把 key 贴到任何地方。
2. 没内置 → 引导弹窗模板：让用户在供应商卡片点「用量查询」打开弹窗：
   • OpenAI 兼容站点（有 /usage 端点）→ 选「通用模板」，必要时填请求地址（留空用供应商的）；
   • New API / OneAPI 中转站 → 选「New API」，填访问令牌和用户 ID；
   • 两个模板都覆盖不了 → 继续第 3 步。
3. 写旧版 probes 数组：确认该供应商的「余额 / usage / balance / credits」接口 （拿不到文档时让用户 F12 抓包，把 URL 路径和返回 JSON 发给你；记得提醒用户 抹掉 key/token），确定「剩余额度」字段后按下面结构生成 probes 数组。
4. 验证：让用户打开供应商卡片看底部用量行。不显示就继续对齐字段路径。

重要安全边界：配置文件里不要写 apiKey。鉴权统一走 Authorization: Bearer <key>， 主进程自动从 auth.json/models.json 取 key；只有个别接口用非标准鉴权头时才用 "headers": { "X-API-Key": "{{apiKey}}" } 占位。

配置文件结构

顶层 providers 映射由弹窗维护（开关/模板/超时/间隔），AI 不要手改。 下面这个 probes 数组是开放给 AI 写的兜底部分，每条是一个供应商。字段含义：

{
  "probes": [
    {
      // （可选）只是给自己看的名字，不影响功能
      "name": "我的中转站",

      // 匹配条件：你的供应商 baseUrl 里包含的任意关键字（小写匹配）
      "match": {
        "baseUrlContains": ["api.myprovider.com"]
      },

      // 发什么请求
      "request": {
        "path": "/user/balance",   // 相对 baseUrl 的路径，必须以 / 开头
        "method": "GET",            // 可选，GET 或 POST，缺省 GET
        // "body": { ... },         // 可选，POST 时的请求体
        // "headers": { "X-API-Key": "{{apiKey}}" }  // 可选，非标准鉴权头
      },

      // 怎么从响应里取数（三种形态选一种）
      "parse": {
        "kind": "balance",
        "valuePath": "balance_infos[0].total_balance",   // 剩余额度的字段路径
        "currencyPath": "balance_infos[0].currency"      // 可选，币种
      }
    }
  ]
}