{
    // 通用实用任务：标题生成、摘要、意图分类、重命名建议、终端命令/修复/解释、搜索助手、VS Code 问答
    "chat.utilityModel": "gcmp.deepseek/gcmp.deepseek:::deepseek-v4-pro",
    // 轻量实用任务：提交信息、分支名生成、进度消息、待办跟踪（建议用快速低成本模型）
    "chat.utilitySmallModel": "gcmp.deepseek/gcmp.deepseek:::deepseek-v4-flash",
    // 内联聊天（Inline Chat）默认模型
    "inlineChat.defaultModel": "GLM-4.7 (CodingPlan) (gcmp.zhipu)",
    // Agent 模式中的探索/规划子 Agent（如代码库搜索、方案规划）
    "chat.exploreAgent.defaultModel": "GLM-4.7 (CodingPlan) (gcmp.zhipu)",
    "chat.planAgent.defaultModel": "GLM-4.7 (CodingPlan) (gcmp.zhipu)",
    // GitHub Copilot Chat 各专用 Agent（Ask / Implement / Explore）
    "github.copilot.chat.askAgent.model": "GLM-4.7 (CodingPlan) (gcmp.zhipu)",
    "github.copilot.chat.implementAgent.model": "GLM-4.7 (CodingPlan) (gcmp.zhipu)",
    "github.copilot.chat.exploreAgent.model": "GLM-4.7 (CodingPlan) (gcmp.zhipu)",
    // GCMP 内置 Commit 消息生成模型
    "gcmp.commit.model": {
        "provider": "zhipu",
        "model": "glm-4.7"
    },
    // GCMP 内置视觉分析模型（必须支持图像输入）
    "gcmp.vision.model": {
        "provider": "zhipu",
        "model": "glm-4.6v"
    }
}

推荐规格：utilitySmallModel 选择响应快的模型（如 deepseek-v4-flash），可配合 maxInputTokens: 16384 等低规格满足快捷任务即可。通用任务（标题生成、摘要等）使用 chat.utilityModel。

> 在 settings.json 中编辑时，将光标置于值位置，使用 VS Code 智能提示从已注册的模型中选择即可。

> 也可通过命令面板执行 GCMP: 设置辅助偏好，在可视化面板中统一配置上述所有模型。

> 入口快捷方式：悬停状态栏的 Token 消耗图标，在弹出的每日统计底部文本菜单中点击「设置辅助偏好」即可进入同一面板。

• chat.utilitySmallModel：轻量实用任务模型。覆盖 chat-title（标题）、git-commit-message（提交信息）、git-branch-name（分支名）、inline-progress-message（进度消息）、prompt-categorizer（意图分类）、todo-tracker（待办跟踪）、rename-suggestions（重命名建议）、terminal-command/quickfix/explain（终端命令/修复/解释）、workspace-search（搜索助手）。
• chat.utilityModel：通用实用任务模型。覆盖 settings-resolver（设置搜索）、explain-code（代码解释）、vscode-qa（VS Code 问答）。
• inlineChat.defaultModel：内联聊天（Inline Chat）默认模型，用于编辑器内联对话（Ctrl+I / 右键 "在行内聊天"）。
• chat.exploreAgent.defaultModel：Explore 子 Agent 默认模型，用于 search-subagent 代码库探索与搜索。
• chat.planAgent.defaultModel：Plan 子 Agent 默认模型，用于 Agent 模式中的方案规划与任务拆解。
• github.copilot.chat.askAgent.model：Ask Agent 默认模型，用于 Ask 模式问答。
• github.copilot.chat.implementAgent.model：Implement Agent 默认模型，用于 Implement 模式代码实现。
• github.copilot.chat.exploreAgent.model：Explore Agent 默认模型，用于 Explore 模式代码库探索。
• gcmp.commit.model：GCMP 内置提交消息生成模型。
• gcmp.vision.model：GCMP 内置视觉分析模型，必须选择支持图像输入的模型。

通用模型参数 及 额外支持功能 配置

{
    "gcmp.retry.enabled": true, // 启用自动重试（默认 true），关闭后请求失败直接停止
    "gcmp.retry.maxAttempts": 3 // 1-10，仅对可重试错误生效
}

• gcmp.retry.enabled 默认值为 true，开启后自动重试 429 限流、503 服务繁忙等可重试错误。设为 false 可完全禁用重试，请求失败立即停止。
• gcmp.retry.maxAttempts 默认值为 3，用于控制 429 限流、502/503/504 服务端错误、网络中断等可重试错误的最大自动重试次数。
• 重试延迟按累加序列递增（1s → 3s → 6s → 10s → 15s），上限 15s。
• 重试期间状态栏会显示重试进度（如 模型名 retry #2/3 in 3s），模型开始返回数据时自动清除。
• gcmp.maxTokens 已弃用：此设置不再生效，各模型现在自动使用自身的 maxOutputTokens 配置。

提供商级别重试配置覆盖

通过 gcmp.providerOverrides.{provider}.retry 可为每个提供商独立设置重试策略，覆盖全局 gcmp.retry.* 行为。maxAttempts 不受全局 1-10 上限约束，允许设置为任意正整数或 -1（无限重试）。

{
    "gcmp.providerOverrides": {
        "xfyun": {
            "retry": {
                "enabled": true,
                "maxAttempts": 15, // 不受 1-10 上限约束
                "maxDelayMs": 30000 // 最大延迟上限 30s
            },
            "retry.xfyun-coding": {
                // 子 provider 独立策略（优先级更高）
                "enabled": true,
                "maxAttempts": 20,
                "maxDelayMs": 60000
            }
        }
    }
}

合并优先级（字段级合并，每个字段独立回退）：

providerOverrides["retry.{subProvider}"] → providerOverrides.retry → 内置预置 → 全局默认

特殊语义：

| 字段值 | 含义 | | ------------------------ | ------------------------------------------------------- | | maxAttempts = -1 | 无限重试（仅由可重试错误判断决定退出） | | maxAttempts = 0 | 禁止重试（override 路径，等价于 enabled: false） | | preset.maxAttempts = 0 | 不会压低全局 maxAttempts；若需强制禁用应使用 override | | enabled = false | 按 enabled 字段合并优先级生效 |

提供商级别限流配置（limit）

通过 gcmp.providerOverrides.{provider}.limit 可为每个提供商独立设置请求限流。支持四个维度，0 或缺省表示该维度不限；任一维度触顶即自主延迟（匀速 pacing）或排队等待。

| 字段 | 含义 | | ---------- | ------------------------------------------------ | | rpm | 每分钟请求数上限（匀速 pacing） | | rps | 每秒请求数上限（匀速 pacing） | | tpm | 每分钟 token 数上限（按输入估算，匀速 pacing） | | parallel | 最大并发在途请求数，超限请求按 FIFO 排队等待槽位 |

{
    "gcmp.providerOverrides": {
        "dashscope": {
            "limit": { "rpm": 60, "parallel": 3 },
            // 子 provider 独立限流（优先级更高）
            "limit.dashscope-coding": { "rpm": 30 },
            "models": [
                // 模型级限流：字段级覆盖 provider 级同名维度，并使用独立的 provider::model 限流桶
                { "id": "deepseek-v4-pro", "limit": { "tpm": 100000 } }
            ]
        }
    }
}

合并优先级（与 retry 一致，字段级合并）：

providerOverrides["limit.{subProvider}"] → providerOverrides.limit → 内置预置

跨实例行为：多个 VS Code 窗口共享 Leader 权威限流桶（窗口间自动选举），维度以 Leader 本机配置为准，配置修改即时生效；Leader 不可用时自动降级为单窗口本地桶并每 60 秒探测恢复，恢复后自动回到跨实例严格模式；窗口关闭或断线时，其排队请求与持有的配额会被自动回收，不会阻塞其他窗口。Remote（SSH/WSL 等）场景跨实例通道不可用，各窗口始终使用本地桶。

各功能专属设置（如 gcmp.commit.enabled、gcmp.vision.model、gcmp.zhipu.search.enableMCP）分别在其对应的功能章节中说明，不在此处展开。

状态栏余额警告阈值

余额型状态栏默认在可用余额不高于 20 时显示黄色背景，负余额显示红色背景。可通过 gcmp.providerOverrides.{provider}.balanceWarning 按提供商覆盖阈值，设置为 0 可仅在欠费时标红。

{
    "gcmp.providerOverrides": {
        "deepseek": {
            "balanceWarning": 10
        },
        "moonshot": {
            "balanceWarning": 30
        },
        "compatible": {
            // 未单独设置的 Compatible provider 使用 compatible 默认阈值
            "balanceWarning": 20
        }
    }
}

• 适用 DeepSeek、Moonshot、纯余额模式的智谱/CommandCode，以及 Compatible 中的各余额查询提供商。
• 数值单位与提供商返回的余额单位一致；套餐用量状态栏仍按用量百分比警告。
• 修改设置会立即按当前缓存重绘背景，不会额外发起余额查询请求。

调试与 HAR 录制

{
    "gcmp.debug.captureHar": false, // 是否将所有 HTTP 请求记录为 HAR 文件（默认关闭）
    "gcmp.debug.harRetentionCount": 7 // 每个 VS Code 进程保留的最近 HAR 文件数量（0 表示仅禁用按数量清理，2 小时硬删除仍生效）
}

• 开启 gcmp.debug.captureHar 后，GCMP 会在 globalStorage/har/ 目录下按 VS Code 实例和日期生成 HAR 1.2 文件，方便排查兼容性与网关问题。
• FIM / NES 补全、Gist 同步、CLI OAuth 刷新等敏感或高频请求默认不录制，避免敏感凭据和大量重复请求落盘。
• 写入前会对敏感请求头、URL 查询参数及重定向 URL 中的凭据进行脱敏，但请求体和响应体仍会按原样保存，请妥善保管 HAR 文件。
• HAR 文件最长每 30 分钟轮换一次；超过 2 小时的旧文件会在新录制或文件轮换时强制删除。
• harRetentionCount 控制每个进程按数量保留的最近文件数；设为 0 时仅禁用按数量清理，2 小时硬删除仍会继续执行。

代理与系统证书配置

{
    "gcmp.proxy": "http://127.0.0.1:7890", // 全局代理（可选），推荐使用完整 URL
    "gcmp.machineOverrides": {
        "dashscope": {
            "proxy": "http://127.0.0.1:7891", // 当前机器的提供商代理
            "models": [
                {
                    "id": "deepseek-v3.2",
                    "proxy": "noproxy" // 当前机器上仅此模型绕过代理
                }
            ]
        },
        "codex": {
            "proxy": "noproxy" // 当前机器上所有 Codex 模型绕过代理
        }
    },
    "gcmp.tls.useSystemCertificates": true // 追加系统根证书（默认开启）
}

• gcmp.proxy 会作为扩展内所有网络请求的默认代理，包括：聊天请求、FIM / NES 补全、联网搜索、MCP 客户端、状态栏余额/用量查询、Compatible Provider 的"获取模型"请求，以及 CLI OAuth 刷新请求。
• gcmp.machineOverrides 是不会参与设置同步的机器级总配置入口；当前支持在每个 Remote SSH 窗口的“远程”设置中按 provider 配置 proxy，或在 models[] 中按模型 id 配置 proxy。
• gcmp.machineOverrides 的 Provider ID 区分大小写，键名必须与模型或内置配置中的 Provider ID 完全一致；例如 Acme 与 acme 是两个不同的 Provider。
• gcmp.providerOverrides..proxy 与内置 Provider 的 models[].proxy 保持兼容并参与设置同步；需要每台机器使用不同代理时，请使用 gcmp.machineOverrides。gcmp.compatibleModels[*].proxy 仍是模型自身配置。
• 代理优先级为：gcmp.machineOverrides..models[] 匹配模型 → 模型自身 model.proxy → gcmp.machineOverrides..proxy → gcmp.providerOverrides..models[] 匹配模型 → gcmp.providerOverrides..proxy → 提供商内置代理 → gcmp.proxy → VS Code http.proxy → 环境变量（HTTPS_PROXY / HTTP_PROXY）→ 系统代理（自动检测）。
• 代理地址支持 host:port 简写（如 127.0.0.1:7890），但推荐使用完整 URL，如 http://127.0.0.1:7890。
• 填写 noproxy 可显式绕过所有代理（包括系统代理和已配置代理），且在代理链路上任一层次设为 noproxy 时立即短路，不再继续回退。
• 当无显式代理配置时，扩展会自动检测 Windows 注册表或 macOS scutil 中的系统代理设置并自动沿用。
• > ⚠️ 不支持 PAC (Proxy Auto-Config) 代理协议。若系统代理设为 PAC，扩展将忽略该配置，需要时请改为显式代理地址。
• gcmp.tls.useSystemCertificates 用于将操作系统信任的根证书追加到 Node.js 默认 CA 列表，适合企业代理、内网网关或本地安装自签根证书场景。
• 支持带认证的代理 URL，日志中会自动脱敏用户名和密码。

提供商配置覆盖

GCMP 支持通过会参与设置同步的 gcmp.providerOverrides 覆盖提供商默认设置，包括兼容原有的同步代理字段；仅当前机器使用的代理覆盖请使用 gcmp.machineOverrides，且其优先级更高。

支持范围因提供商类型而异：

| 提供商类型 | 支持覆盖的字段 | models[] | | ------------------------------------------------------ | ------------------------------------------------------- | --------------------------------------- | | 内置提供商（deepseek/zhipu 等） | baseUrl、proxy、customHeader、retry、models[] | ✅ 支持新增和覆盖模型 | | 已知提供商（aihubmix/openrouter 等） | proxy、customHeader、retry | ❌ 不支持（走 gcmp.compatibleModels） | | 自定义提供商（compatibleModels 中自定义 provider） | proxy、customHeader、retry | ❌ 不支持（走 gcmp.compatibleModels） | | compatible 自身 | proxy、customHeader、retry | ❌ 不支持（走 gcmp.compatibleModels） |

已知/自定义/compatible 提供商不支持 models[]，模型定义统一通过 gcmp.compatibleModels 配置。

配置优先级：

模型自身非代理设置 > providerOverrides.{provider} > providerOverrides.compatible

• providerOverrides.compatible 作为全局默认值，对所有 Compatible Provider 下的模型生效
• 代理地址：machineOverrides.{provider}.models[] > model.proxy > machineOverrides.{provider}.proxy > providerOverrides.{provider}.models[].proxy > providerOverrides.{provider}.proxy > 提供商内置代理 > gcmp.proxy > VS Code http.proxy > 环境变量
• 自定义 HTTP 头：providerOverrides.{provider}.customHeader > 模型自身 customHeader > providerOverrides.compatible.customHeader
• 重试配置：providerOverrides["retry.{subProvider}"] > providerOverrides.retry > 内置预置 > 全局 gcmp.retry.*

{
    "gcmp.providerOverrides": {
        "dashscope": {
            "models": [
                {
                    "id": "deepseek-v3.2", // 增加额外模型：不在提示可选选项，但允许自定义新增
                    "name": "Deepseek-V3.2 (阿里云百炼)",
                    "tooltip": "DeepSeek-V3.2是引入DeepSeek Sparse Attention（一种稀疏注意力机制）的正式版模型，也是DeepSeek推出的首个将思考融入工具使用的模型，同时支持思考模式与非思考模式的工具调用。",
                    // "sdkMode": "openai", // 阿里云百炼已默认继承提供商设置，其他提供商模型可按需设置
                    // "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
                    "maxInputTokens": 128000,
                    "maxOutputTokens": 16000,
                    "capabilities": {
                        "toolCalling": true,
                        "imageInput": false
                    }
                }
            ]
        },
        "aihubmix": {
            "customHeader": { "X-Custom": "value" },
            "retry": {
                // 提供商级重试覆盖
                "enabled": true,
                "maxAttempts": 5,
                "maxDelayMs": 30000
            }
        }
    }
}

自定义模型内置已知提供商ID及显示名称列表

聚合转发类型的提供商可提供内置特殊适配，不作为单一提供商提供。

若需要内置或特殊适配的请通过 Issue 提供相关信息。

已知提供商支持通过 gcmp.providerOverrides.{providerId} 覆盖同步的 proxy、customHeader、retry；仅当前机器使用的代理请配置 gcmp.machineOverrides.{providerId}。

| 提供商ID | 提供商名称 | 提供商描述 | 余额查询 | | --------------- | ------------------------------------------------------------- | --------------- | ------------ | | aiping | AI Ping | | 用户账户余额 | | aihubmix | AIHubMix | 可立享 10% 优惠 | ApiKey余额 | | openrouter | OpenRouter | | 用户账户余额 | | siliconflow | 硅基流动 | | 用户账户余额 |

配置示例：

{
    "gcmp.compatibleModels": [
        {
            "id": "glm-4.7",
            "name": "GLM-4.7",
            "provider": "zhipu",
            "model": "glm-4.7",
            "sdkMode": "openai",
            "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
            // "proxy": "http://127.0.0.1:7890", // 可选：仅对该模型生效，也用于“获取模型”探测请求
            // "sdkMode": "anthropic",
            // "baseUrl": "https://open.bigmodel.cn/api/anthropic",
            "maxInputTokens": 128000,
            "maxOutputTokens": 4096,
            "capabilities": {
                "toolCalling": true, // Agent模式下模型必须支持工具调用
                "imageInput": false
            },
            // customHeader 和 extraBody 可按需设置
            "customHeader": {
                "X-Model-Specific": "value",
                "X-Custom-Key": "${APIKEY}"
            },
            "extraBody": {
                "temperature": 0.1,
                "top_p": 0.9,
                // "top_p": null, // 部分提供商不支持同时设置 temperature 和 top_p
                "thinking": { "type": "disabled" }
            }
            // "webSearchTool": true, // 可选：启用联网搜索（仅 sdkMode=anthropic / openai-responses 生效）
            // "nativeTools": [{ "type": "web_search" }] // 可选：注入原生工具（仅 sdkMode=openai-responses 生效）
            // "cacheTtl": "1h" // 可选：Anthropic 提示缓存 TTL（仅 sdkMode=anthropic 生效），省略为默认 5m；1h 缓存写入约为基础输入价 2 倍
        }
    ]
}

提示：如果你使用 OpenAI Responses / 兼容转发，并且不想回传加密思考（reasoning.encrypted_content），可显式设置 extraBody.include 为 null 或 []；此时历史思维链会以明文 reasoning_text 通道回传，且 ThinkingPart 被剥离时会从 StatefulMarker 恢复。需要回传密文时请包含 reasoning.encrypted_content。

• gcmp.compatibleModels[*].proxy 仅作用于当前自定义模型；在填写 baseUrl 后点击“获取模型”时，也会使用同一代理设置进行探测。

sdkMode

gcmp.compatibleModels[*].sdkMode 指定请求/流式解析方式，可选值：openai（默认）、openai-sse、openai-responses、anthropic、gemini-sse（Gemini GenerateContent SSE）。

gemini-sse 对 Google 官方端点使用 x-goog-api-key，对第三方网关默认使用 Authorization: Bearer，并请求 /v1beta/models/{model}:streamGenerateContent?alt=sse；可通过 customHeader 覆盖或删除默认鉴权头。extraBody.generationConfig 会合并到 generationConfig，其余字段按 Gemini GenerateContent 顶层字段透传（contents、tools、systemInstruction 等核心字段除外）。serviceTier 支持 unspecified、standard、flex、priority。

Anthropic 提示缓存 TTL：cacheTtl

sdkMode=anthropic 的模型可配置 gcmp.compatibleModels[*].cacheTtl：

• 省略（默认）：不写 ttl 字段，走 Anthropic 默认 5 分钟缓存，行为与历史版本一致
• "5m" / "1h"：请求内全部块级 cache_control 断点统一携带该 TTL，不会出现混用 TTL 导致的 400
• "1h" 适合会话常出现 5 分钟以上、1 小时以内空档的场景；缓存写入按基础输入价约 2 倍计费，缓存读取仍为 0.1 倍

自定义 provider 余额/用量查询示例：usage + usages 智能合并

对于 Compatible 自定义 provider，可在 gcmp.providerOverrides.{providerId} 下配置：

• usage：可选；配置一个查询接口。即使同一响应包含多个额度，也只需一个 usage 配合 fields 配置数组；它还可作为 usages 的公共默认值
• usages：可选；用于多个命名查询模式，例如不同 URL、鉴权方式或查询参数。每个条目可在 usage 基础上增量覆盖，但 fields 数组是完整替换，不按项合并

一个接口返回多个额度：fields 配置数组

fields 既可以保持旧的单对象写法，也可以是非空数组。数组中每项都必须提供 balance，并可独立配置：

• balance：必填，可用余额/剩余额度的字段路径或计算字段
• paid：可选，充值/已付余额的字段路径或计算字段
• granted：可选，赠送余额的字段路径或计算字段
• displayName：可选，先尝试按路径读取名称；得到非空字符串或有限数字时使用该值，否则原样显示配置文本。例如 data.wallet.name 或 现金钱包
• arrayPath：可选，明确指定要遍历的数组，其元素分别解析为额度项
• unit：可选，该项的单位；依次回退到外层 usage.unit、USD，不做货币或单位换算

假设接口返回如下 JSON：

{
    "data": {
        "wallet": { "name": "现金钱包", "remaining": 88.5, "paid": 80, "granted": 8.5 },
        "packages": [
            { "name": "月度套餐", "total": 1000, "used": 250 },
            { "name": "加油包", "total": 200, "used": 50 }
        ],
        "addons": [{ "name": "联网搜索", "remaining": 30 }]
    }
}

下面的配置会从一次响应中解析钱包、两个套餐和搜索额度。示例 provider 与 URL 仅作说明，需替换为实际配置；自定义模型的 provider 也应使用相同的 key。

{
    "gcmp.providerOverrides": {
        "readme_demo": {
            "usage": {
                "url": "https://api.example.com/usage",
                "unit": "CNY",
                "fields": [
                    {
                        "displayName": "data.wallet.name",
                        "balance": "data.wallet.remaining",
                        "paid": "data.wallet.paid",
                        "granted": "data.wallet.granted"
                    },
                    {
                        "arrayPath": "data.packages",
                        "displayName": "name",
                        "balance": {
                            "operation": "subtract",
                            "paths": ["total", "used"]
                        },
                        "unit": "次"
                    },
                    {
                        "displayName": "data.addons[].name",
                        "balance": "data.addons[].remaining",
                        "unit": "次"
                    }
                ]
            }
        }
    }
}

解析结果按 fields 配置顺序、再按数组元素顺序展开：

| 额度名称 | 可用余额 | 单位 | | -------- | -------- | ---- | | 现金钱包 | 88.5 | CNY | | 月度套餐 | 750 | 次 | | 加油包 | 150 | 次 | | 联网搜索 | 30 | 次 |

钱包还会显示充值 80、赠送 8.5 的明细。不同单位的额度分别展示，不会把它们累加成一个总额，也不会为每个额度项单独请求接口。

数组路径：拆分、求和与索引的区别

拆分范围由 arrayPath 或 balance 的路径决定；计算字段也会检查其操作数路径。paid、granted 与 displayName 跟随同一个额度上下文解析，不独立决定拆分范围。

假设 data.packages 包含两个元素，其 remaining 分别为 10 和 20：

| 写法 | 结果 | | ---------------------------------------------------- | ---------------------------- | | balance: "data.packages[].remaining" | 拆分为两项：10、20 | | balance: "data.packages.remaining" | 途经数组自动拆分为两项 | | balance: "data.packages[*].remaining" | 对数组求和，只产生一项：30 | | balance: "data.packages[0].remaining" | 只选第一项：10 | | balance: "data.packages.0.remaining" | 与 [0] 相同，只选第一项 | | arrayPath: "data.packages"，balance: "remaining" | 明确遍历数组，分别得到两项 |

arrayPath 不是必填项。它适合明确指定某个数组，并将其元素作为字段解析上下文，让名称、余额与计算操作数可以使用元素相对路径：

{
    "fields": {
        "arrayPath": "data.packages",
        "displayName": "name",
        "balance": "remaining",
        "unit": "次"
    }
}

不写 arrayPath 时，可用 data.packages[].remaining 或 data.packages.remaining 自动拆分。嵌套数组也可逐层展开，例如 data.groups[].limits[].remaining；响应本身是数组时，直接写 remaining 即可按元素解析。

这些路径是 dot 字段路径及数组索引/通配语法，不是完整的 JSONPath 表达式。不要把 [*] 当作拆分，也不要把 [0] 当作遍历全部元素。

计算字段与数组求和

fields 中的 balance、paid、granted 支持 sum / subtract / multiply / divide。paths 里既可以写字段路径、常量数值（例如 500000），也可以继续嵌套计算字段对象，适合 Ticket / 500000、(总额 - 已用) / 500000 这类余额换算。

数组拆分后，计算按元素执行，相对操作数路径优先在当前元素、父级元素中查找，再回退到响应根数据；完整数组路径会绑定到当前选中的元素。因此上面的 arrayPath 示例可以直接用 total 和 used，无需手写元素索引。

{
    "balance": {
        "operation": "divide",
        "paths": [
            {
                "operation": "subtract",
                "paths": [
                    "data.subscriptions[0].subscription.amount_total",
                    "data.subscriptions[0].subscription.amount_used"
                ]
            },
            500000
        ]
    }
}

嵌套对象会先计算子表达式，再参与外层运算。

路径中的 [] 可匹配数组中的所有元素，并对目标字段求和。例如，data.subscriptions[].subscription.amount_total 会汇总所有订阅的 amount_total。匹配不到数组、字段缺失或值无法解析为有限数字时按 0 处理；该规则也适用于嵌套计算，以及 fields.paid 和 fields.granted。

{
    "balance": {
        "operation": "divide",
        "paths": [
            {
                "operation": "subtract",
                "paths": [
                    "data.subscriptions[*].subscription.amount_total",
                    "data.subscriptions[*].subscription.amount_used"
                ]
            },
            500000
        ]
    }
}

查询模式的继承与请求次数

• 只配置 usage：注册一个查询模式；一个模式仍可通过 fields 数组返回多个额度
• 需要多个查询模式时：通过 usages 配置，每个最终注册的模式分别查询一次。即使 URL 相同，不同模式也不会因为使用同一个接口而自动合并请求；同一响应内的多额度应优先使用 fields 数组
• usage 与某个命名模式最终解析出的查询配置等价时，不额外生成重复的 default 模式；外层模式 displayName 不影响该等价判断
• usage 和 usages 都不配置：就不会注册该自定义 provider 的余额/用量查询

• 默认值为单对象时，覆盖对象按字段增量合并，例如只修改 granted，仍保留默认 balance
• 覆盖值为数组时，完整替换默认 fields，不拼接、不按索引继承。数组不能为空，每一项都必须重新提供 balance
• 默认 fields 是多项数组时，改成单对象不会继承其中任意一项；必须提供完整的 balance。默认数组只有一项时，兼容对该唯一项作对象增量覆盖
• 未配置共享 usage 时，每个 usages 条目都必须自行提供 url 和完整 fields

注意：gcmp.providerOverrides 的 provider key 必须与 gcmp.compatibleModels[*].provider 完全一致，包括大小写。

例如，下面这个更贴近实际 settings.json 的 NekoCode 相关配置片段表示：

• gcmp.compatibleModels 中的模型使用 provider: "NekoCode"，也可继续添加相同 provider 的其他模型
• gcmp.providerOverrides.NekoCode.usage 提供默认查询 URL https://api2.nekoapi.ai/v1/usage 和公共字段路径 balance
• gcmp.providerOverrides.NekoCode.usages.pay 与 usage 的最终查询配置等价，只额外提供显示名称 余额
• gcmp.providerOverrides.NekoCode.usages.sub 把查询 URL 覆盖为 https://api2.nekoapi.ai/v1/user/balance，并把余额字段覆盖为 remaining

{
    "gcmp.compatibleModels": [
        {
            "id": "nekocode:gpt-5.5",
            "name": "GPT-5.5 (NekoCode)",
            "provider": "NekoCode",
            "model": "gpt-5.5",
            "sdkMode": "openai-responses",
            "baseUrl": "https://api2.nekoapi.ai/v1",
            "proxy": "noproxy",
            "maxInputTokens": 272000,
            "maxOutputTokens": 128000,
            "capabilities": {
                "toolCalling": true,
                "imageInput": true
            },
            "reasoningDefault": "xhigh",
            "reasoningEffort": ["none", "low", "medium", "high", "xhigh"],
            "extraBody": {
                "store": false,
                "reasoning": {
                    "effort": "xhigh",
                    "summary": "auto"
                }
            },
            "useInstructions": true,
            "customHeader": {
                "version": "0.134.0",
                "user-agent": "codex-tui/0.134.0 (Windows 10.0.26200; x86_64) unknown (codex-tui; 0.134.0)",
                "originator": "codex-tui"
            }
        }
    ],
    "gcmp.providerOverrides": {
        "NekoCode": {
            "usage": {
                "url": "https://api2.nekoapi.ai/v1/usage",
                "fields": {
                    "balance": "balance"
                }
            },
            "usages": {
                "pay": {
                    "displayName": "余额",
                    "url": "https://api2.nekoapi.ai/v1/usage"
                },
                "sub": {
                    "displayName": "订阅",
                    "url": "https://api2.nekoapi.ai/v1/user/balance",
                    "fields": {
                        "balance": "remaining"
                    }
                }
            }
        }
    }
}

该配置的实际效果是：

• providerOverrides.NekoCode 会作用于所有 provider: "NekoCode" 的兼容模型，包括示例中的 GPT-5.5 (NekoCode)
• pay 会继承 usage.fields.balance = "balance"
• sub 会使用覆盖后的 fields.balance = "remaining"
• 因为 pay 与 usage 解析出的查询配置等价，所以不会再额外生成一个重复的 default 模式

• NekoCode / 余额
• NekoCode / 订阅

展示、告警与刷新注意事项

• Compatible 状态栏逐项显示余额；悬浮表格显示额度名称、余额及可选的充值/赠送明细。配置面板对具名的单个额度和多个额度显示名称与余额；无名单项保持紧凑展示
• 所有成功解析的额度都参与余额告警：任意一项为负数时标红，否则按提供商的 balanceWarning 阈值判断黄色警告。不同单位的额度沿用同一个提供商数值阈值，不做单位换算
• balance 未取到数值时，仅当 paid 与 granted 都有效才回退为两者之和，否则跳过该额度项。空的拆分数组不会生成额度项，所有配置都未解析出额度时查询失败；[*] 求和的缺失值仍按 0 处理
• 修改 gcmp.providerOverrides 下的 usage / usages 后，不会立即重新查询现有缓存；可点击 Compatible 状态栏手动刷新。状态栏尚未出现时，可重新加载窗口；配置面板可点击对应配置的“刷新”按钮重新查询

数组目标校验：显式 arrayPath 必须对应实际数组。路径缺失或目标不是数组时，跳过该 fields 配置；嵌套路径只跳过无效分支，不回退到根余额。其他有效额度仍正常展示，所有配置都没有有效额度时查询失败。配置前应核对真实响应结构。