企业官网建设流程全解析

CodexBar Provider IDs 权威指南：69 个用量提供商标识符的生成机制、校验规则与实战用法

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar

CodexBar 通过一套编译期固定的 Provider ID来标识每一个可接入的用量统计来源（OpenAI Codex、Claude Code、Gemini、Cursor 等）。本文以仓库中的生成文档 docs/provider-ids.md 为核心，完整梳理 69 个 Provider ID 的清单、它们在UsageProvider枚举中的定义方式、由脚本驱动的生成与同步校验机制、ProviderInstanceID的合法性规则，以及这些 ID 在 CLI、配置与新增 Provider 流程中的实际用法。读完本文，你将掌握如何识别、校验、查询与扩展 CodexBar 的 Provider ID 体系。

一、什么是 Provider ID：一次调用、一处标识

Provider ID 是 CodexBar 中每一个用量数据源（Provider）的稳定小写标识符。它同时承担三重职责：

• 持久化与 Widget 标识：配置、缓存和 WidgetKit 扩展中都用它来指代某个 Provider；
• CLI 查询参数：codexbar usage --provider <id>、codexbar cards --provider <id>等命令直接以 ID 作为筛选依据；
• 注册与派发键：描述符注册表、实现清单、实例 ID 别名都以 ID 为纽带串联。

从源码结构看，Provider ID 是编译期常量而非运行时字符串：Sources/CodexBarCore/Providers/Providers.swift中的UsageProvider枚举（public enum UsageProvider: String, CaseIterable, Sendable, Codable）是全部 ID 的唯一定义源头。这也解释了为什么 docs/provider-ids.md 开头会标注 "Generated by Scripts/regenerate-provider-manifests.sh. Do not edit by hand."——文档本身是生成产物，不是手写清单。

同一家公司为何会有多个 ID

从 docs/providers.md 可以确认：同一公司可能暴露多个 Provider ID，因为认证来源与配额形态不同。典型例子：

• codex与openai：Codex 走 OAuth/CLI RPC，OpenAI 走 Admin API key，配额口径完全不同；
• opencode与opencodego：前者是 Web 仪表盘（cookie），后者是本地 SQLite 成本历史 + 用量 API；
• alibaba（Alibaba Coding Plan）与alibabatokenplan（Alibaba Token Plan）：同为阿里系，但前者是控制台 RPC，后者是 Bailian CLI + 订阅 API；
• grok与xai：Grok 跟踪消费者 Grok/SuperGrok 订阅配额（CLI/Web 会话），xAI 跟踪开发者平台预付计费面，凭据与余额互不共享。

因此在阅读 Provider ID 清单时，应将其理解为"数据源实例"而非"公司"。

二、完整 Provider ID 清单（69 个）

以下是 docs/provider-ids.md 中登记的全部 69 个 Provider ID，顺序与UsageProvider枚举的 bootstrap 顺序完全一致：

codex, openai, azureopenai, claude, clinepass, cursor, opencode, opencodego, alibaba, alibabatokenplan, qwencloud, factory, fireworks, gemini, antigravity, copilot, devin, zai, minimax, manus, kimi, kilo, kiro, vertexai, augment, jetbrains, moonshot, amp, t3chat, ollama, synthetic, openrouter, elevenlabs, warp, windsurf, zed, perplexity, mimo, doubao, sakana, abacus, mistral, deepseek, deepinfra, codebuff, crof, venice, commandcode, qoder, stepfun, bedrock, grok, groq, llmproxy, litellm, deepgram, poe, chutes, neuralwatt, clawrouter, longcat, sub2api, wayfinder, zenmux, aiand, zoommate, xai, notion, ibmbob

为便于检索，可按数据源类型将这批 ID 归类（归类依据见 docs/providers.md 的 Fetch strategies 总表）：

说明：上表的归类是便于检索的粗分组，不代表代码中的注册顺序；唯一权威顺序仍是UsageProvider枚举定义顺序。

三、底层实现：UsageProvider枚举与描述符注册表

Provider ID 的权威定义位于 Sources/CodexBarCore/Providers/Providers.swift。该枚举满足String、CaseIterable、Sendable、Codable，意味着：

• ID 可以直接与字符串互相转换（rawValue），用于配置文件持久化；
• CaseIterable支撑遍历与测试同步校验；
• Sendable允许 ID 安全跨并发边界传递（网络请求、后台刷新任务）。

ID 的运行时绑定通过描述符注册表完成。在 Sources/CodexBarCore/Providers/ProviderDescriptor.swift 中，ProviderDescriptorRegistry使用ProviderManifest.allDescriptors在首次访问时完成 bootstrap 注册，并提供三张派生映射：

• metadata：[UsageProvider: ProviderMetadata]，供菜单标题、开关文案使用；
• descriptor(for:)：按 ID 取描述符；
• cliNameMap：[String: UsageProvider]，把 CLI 名称与别名映射回 Provider ID，这是--provider参数解析的基础。

四、生成机制：regenerate-provider-manifests.sh如何产出 ID 文档

Scripts/regenerate-provider-manifests.sh 是 Provider ID 体系的"唯一写入方"。它以sed从Providers.swift中解析UsageProvider枚举的全部case，然后在同一趟运行中生成四个产物：

脚本支持两种模式：

Scripts/regenerate-provider-manifests.sh write # 重新生成并覆盖四个产物 Scripts/regenerate-provider-manifests.sh check # 仅校验，产物过期则报错并输出 diff

脚本内部还对每个 Provider 施加了强一致性约束：每个 ID 必须恰好存在一个声明id: .<provider>,的*ProviderDescriptor.swift文件和恰好一个声明let id: UsageProvider = .<provider>的*ProviderImplementation.swift文件，否则直接失败退出。也就是说，Provider ID 列表、描述符、实现三者在生成期就被强制一一对应。

五、ProviderInstanceID的合法性校验规则

Provider ID 不只是枚举值，还会被包装为ProviderInstanceID（定义于 Sources/CodexBarCore/Providers/ProviderInstanceID.swift）。它是RawRepresentable的String包装类型，核心价值在于构造时校验：

• 长度必须为1–64 字节；
• 字符仅允许小写 ASCII 字母（a–z）、数字（0–9）与连字符（-）；
• 非法值构造返回nil，解码时抛出DecodingError（错误信息为 "Provider instance ID must contain 1-64 lowercase ASCII letters, digits, or hyphens"）。

这套规则对两类场景尤其重要：

1. 插件体系：第三方 Provider 插件也要注册一个合法的实例 ID，规则校验保证了 ID 空间不会混入不可持久化的字符串；
2. Codable 持久化：配置读写经过同一校验，从根上阻止脏数据进入缓存与 Widget 数据。

同时，UsageProvider提供instanceID便捷属性（ProviderInstanceID(firstPartyProvider: self)），而生成的 ProviderInstanceIDAliases.generated.swift 进一步为每个 ID 生成了静态常量（如ProviderInstanceID.codex、ProviderInstanceID.ibmbob），调用点无需手写字符串字面量，也就不会打错 ID。

六、同步保障：文档与枚举的自动化测试校验

为了确保 docs/provider-ids.md 永远不会与UsageProvider脱节，仓库提供了专门的同步测试 Tests/CodexBarTests/ConfigurationDocsProviderIDTests.swift：

• 测试从仓库根目录读取docs/provider-ids.md；
• 定位# Provider IDs标记后的第一个反引号行，按逗号切分并清洗出 ID 序列；
• 与UsageProvider.allCases.map(\.rawValue)逐一比对；
• 任何顺序不一致或缺失都会导致测试失败。

这意味着"文档 = 枚举"是一条被 CI 强制执行的契约：凡是改了Providers.swift而没有运行生成脚本并提交新文档，测试就会报警。这也是docs/provider-ids.md全文"极简"却足够可信的原因——它不是一个手写备忘，而是一个可验证的机器产物。

七、在 CLI 中的实战用法

Provider ID 最频繁的使用场景是 CodexBar CLI。所有子命令的--provider参数都接受这些 ID 之一，也支持all（全部启用 Provider）与both等特殊值。ID 选项列表由 Sources/CodexBarCLI/CLIOptions.swift 中的ProviderHelp.list动态生成——它遍历ProviderDescriptorRegistry.all取出每个描述符的cli.name并拼上both、all，因此帮助文本中的合法 ID 始终与注册表保持实时一致。

常见命令示例（出处见 Sources/CodexBarCLI/CLIHelp.swift）：

# 查询单个 Provider codexbar usage --provider claude codexbar usage --provider gemini # 查询全部启用 Provider，JSON 输出 codexbar usage --provider all --json # 指定数据源模式（web / cli / oauth / api / local） codexbar usage --provider codex --source web --format json --pretty # 卡片式一览 codexbar cards --provider codex codexbar cards --provider all --status # 成本历史 codexbar cost --provider codex --group-by project codexbar cost --provider claude --format json --pretty # 配置管理：启用 / 禁用 / 设置 API key codexbar config enable --provider grok codexbar config disable --provider cursor printf '%s' "$ELEVENLABS_API_KEY" | codexbar config set-api-key --provider elevenlabs --stdin

Cookie 相关命令同样依赖 ID 精确指代，例如codexbar cookie refresh --provider grok只会刷新 grok 的 Cookie 缓存；CLICookieCommand要求恰好指定一个--provider或--all，二者互斥。codexbar guard子命令则强制要求--provider <id>。

--provider的解析语义

从CLIOptions.swift的枚举分支可以看到，Provider 选择被建模为三种形态：

• 主 Provider 默认值：当未显式指定且配置中没有启用项时，回退到ProviderDescriptorRegistry.all.prefix(2)（前两个注册的 Provider，即codex、openai）；
• all：展开为注册表中全部 Provider ID；
• 自定义列表：按用户给定的 ID 精确解析，未知 ID 会触发 "Unknown or missing provider. Use --provider ." 之类的参数错误（见 CLIConfigCommand.swift）。

八、配置文件中的 Provider ID

在~/.codexbar/config.json中，Provider ID 同样作为键出现。综合 docs/providers.md 中各家 Provider 的说明，典型的按 ID 组织的配置字段包括：

此外 docs/configuration.md 在第 275 行明确将 provider-ids.md 作为配置文档的索引清单引用（"See the generated provider ID list, sourced fromUsageProviderin enum order"），说明阅读配置文档时同样以本文档为 ID 权威来源。

九、如何新增一个 Provider ID

由于 ID 体系是"枚举定义 + 脚本生成 + 测试守卫"的三段式，新增 Provider 必须走完整注册流程。依据 docs/provider.md 的 "Adding a new provider" 章节，全部注册点包括：

1. 在Sources/CodexBarCore/Providers/<Name>/创建描述符、fetch 策略与核心设置/凭据类型；
2. 在Sources/CodexBar/Providers/<Name>/创建 App 实现与 UI 设置贡献；
3. 按预期 bootstrap 顺序在UsageProvider（Providers.swift）中新增一个稳定的case；
4. 运行Scripts/regenerate-provider-manifests.sh重新生成清单与 provider-ids.md——不要手改三个 generated Swift 文件；
5. 添加Sources/CodexBar/Resources/ProviderIcon-<id>.svg并在描述符 branding 中引用；
6. 若widgetSelectable为 true，还需在 WidgetKit 的ProviderChoiceAppEnum中同步 case 与caseDisplayRepresentations字面量表（AppIntents 静态提取，无法运行时推导）；
7. 为解析器、策略可用性/回退、凭据投影、CLI 别名等补充测试；
8. 更新 docs/providers.md 中的用户侧条目，必要时新增独立文档。

其中第 3、4 步直接决定新 ID 是否出现在本文档中；ProviderArchitectureGatekeeperTests还会以词法扫描方式侦测遗漏的描述符、实现、图标、设置区段或 Widget 注册。

十、ID 的稳定性约定与使用注意事项

综合源码与文档，使用 Provider ID 时有几点约定值得注意：

• ID 一经发布即为稳定标识：它被持久化进配置与缓存，改名会破坏既有用户数据，因此新增容易、改名需谨慎；
• 大小写敏感且全小写：UsageProvider的rawValue与校验规则都要求小写 ASCII，配置文件中不要混入大写；
• 同一来源的多个 ID 不会互相合并：例如 OpenCodex 本地日志与原生 Codex 会话会保持独立行，避免重复计数（见 docs/providers.md 的 OpenCodex 说明）；
• all与both是 CLI 保留值，不属于合法 Provider ID，配置与注册表不会出现它们。

结语

CodexBar 的 Provider ID 体系是一个"小文档、大机制"的典型：69 个 ID 的清单本身只有一行，但背后是UsageProvider编译期枚举、regenerate-provider-manifests.sh的四产物生成、ProviderInstanceID的严格校验、CLI 动态帮助与 CI 同步测试共同构成的自洽闭环。理解这套 ID 机制，是深度使用codexbarCLI、排查配置问题以及为仓库贡献新 Provider 的第一步。

进一步阅读：完整的每家 Provider 认证方式、数据源策略与状态页信息见 docs/providers.md；新增 Provider 的架构与完整步骤见 docs/provider.md；配置文件中各字段的全局说明见 docs/configuration.md。

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar