CodexBar CLI 重构指南JSON-only 错误模型、配置校验与 SettingsStore 拆分实战【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar本文围绕 CodexBar 仓库内的 CLI 重构计划文档 展开系统讲解其核心目标——让 CLI 在usage/cost等命令下输出纯 JSON 错误、实现逐 Provider 作用域的错误载荷、落地配置校验规则以及如何通过SettingsStore 拆分控制文件规模。读完本文你将掌握codexbar config validate、codexbar config dump等命令的实际用法、CodexBarConfigValidator的全部校验规则与错误码并理解 CLI 错误上报管线的底层实现位置可直接用于排查配置问题与二次开发。一、重构背景与目标CodexBar 的 CLI入口见 Sources/CodexBarCLI/CLIEntry.swift是一个基于 Commander 框架解析参数、按命令路径分发的 Swift 可执行程序。随着 Provider 数量增长当前仓库Sources/CodexBarCore/Providers下已有数百个 Provider 实现文件CLI 的错误处理、配置解析与设置存储逐渐暴露出三类问题错误输出不统一部分路径向 stderr 写文本部分路径混入日志机器脚本难以稳定解析失败原因配置错误静默吞掉无效的source、region、apiKey字段只有在运行时才以模糊错误暴露文件体积膨胀CLIEntry.swift、SettingsStore.swift承担过多职责单文件行数失控。重构计划因此设定了五个目标详见 docs/refactor/cli.mdJSON-only每个错误都以合法 JSON 输出到 stdout不再混入 stderr 文本Per-provider errorsProvider 失败产出带 Provider 作用域的错误载荷Config validation对无效字段、不支持的 source 模式、错误的 region 等给出显式告警Config parity新增 CLI 命令用于校验可选转储配置SettingsStore split文件控制在 500 行以内明确划分 defaults 与 config 职责。同时重构保留了四条约束Provider 顺序仍由配置providers[]数组顺序驱动Provider 启停仍由配置enabled字段控制Provider 密钥不做 Keychain 持久化CLI 仍支持面向非 JSON 场景的文本输出。二、JSON-only 错误模型错误即数据重构的核心约定是usage与cost命令的 JSON 输出始终是数组错误不是单独的行外文本而是数组内的载荷条目——正常条目携带usage/credits等数据失败条目携带error字段。2.1 全局/CLI 级错误形状对于参数错误、配置加载失败这类与具体 Provider 无关的错误使用固定的provider: cli、source: cli标识{ provider: cli, source: cli, error: { code: 1, message: ..., kind: config } }字段语义字段类型说明providerstring固定为cli表示 CLI 自身错误sourcestring固定为cli与 Provider 载荷中的auto/web/api等来源区分error.codeint退出码与进程退出码一致见 Sources/CodexBarCLI/CLIExitCode.swifterror.messagestring人类可读的错误描述error.kindstring错误类别args/config/provider/runtime见 CLIErrorReporting.swift2.2 源码中的实现落点错误上报的统一出口在 Sources/CodexBarCLI/CLIErrorReporting.swiftmakeCLIErrorProviderPayload(message:code:kind:)构造provider: cli的ProviderPayloadsource写死为climakeProviderErrorPayload(provider:account:source:status:error:kind:)构造逐 Provider 作用域的错误载荷provider使用真实的UsageProvidersource使用实际生效的ProviderSourceModeexit(code:message:output:kind:)是唯一退出出口当output.usesJSONOutput为真时先打印 JSON 载荷数组再退出否则才回退到 stderr 文本。这正对应计划中路由所有退出到 JSON-aware reporter的步骤 3。ProviderPayload的结构定义在 Sources/CodexBarCLI/CLIPayloads.swift包含provider、account、version、source、status、usage、credits、error等可空字段JSON 编码时未设置字段自动省略。2.3 输出格式决策链CLIOutputPreferencesSources/CodexBarCLI/CLIOutputPreferences.swift决定了何时走 JSONusesJSONOutputjsonOnly || format .json--json与--json-only都是 JSON 快捷键但--format显式值优先从源码注释可见usage --format toon是唯一的 TOON 特例TOON 借用 JSON 获取/渲染管线但错误/退出载荷也按 TOON 渲染避免--format toon在早期失败时悄悄回退成 JSON。CLIEntry.swift在解析命令前就通过CLIOutputPreferences.from(argv:)预先扫描 argv 中的--json-only/--json/--pretty/--format这正是计划步骤 3parse--json-onlyearly的落地实现。三、配置校验CodexBarConfigValidator 全规则解析计划步骤 1 要求新增CodexBarConfigIssue与CodexBarConfigValidator位于CodexBarCore/Config且单文件控制在 500 行以内。这两者已实现于 Sources/CodexBarCore/Config/CodexBarConfigValidation.swift约 324 行。3.1 问题模型public enum CodexBarConfigIssueSeverity: String, Codable, Sendable { case warning case error } public struct CodexBarConfigIssue: Codable, Sendable, Equatable { public let severity: CodexBarConfigIssueSeverity public let provider: UsageProvider? public let field: String? public let code: String public let message: String }每个问题包含五个字段severitywarning/error、provider可空全局问题为空、field如source、apiKey、hooks.events[0].executable、机器可读的code、人类可读的message。3.2 顶层校验流程validate(_ config:)按三步执行版本检查config.version ! CodexBarConfig.currentVersion当前版本为 1见 CodexBarConfig.swift时报version_mismatch错误逐 Provider 校验遍历config.providers调用validateProviderHooks 校验validateHooks检查事件规则数量上限、ID 唯一性、可执行文件绝对路径、阈值范围、超时范围与命令尺寸。3.3 Provider 级校验规则对应文档五条规则计划文档列出了五条核心规则源码实现为更细的十二类检查计划规则源码错误码触发条件严重级source必须在fetchPlan.sourceModes内unsupported_source配置的source不在 Provider 描述符fetchPlan.sourceModes中errorapiKey仅当支持.apiapi_key_unused设置了apiKey但 Provider 不支持apisourcewarning同上api_source_unsupportedsource .api但 Provider 不支持apierror同上api_key_missingsource .api且需要 key但未配置任何 API 凭据含 tokenAccounts 兜底warningcookieSource仅当支持.web/.autocookie_source_unused设置cookieSource但 Provider 不用 web cookiewarning同上cookie_header_unused设置cookieHeader但 Provider 不用 web cookiewarning同上cookie_header_missingcookieSource .manual但cookieHeader缺失warningregion仅限 zai/minimax 等region_unused设置region但 Provider 描述符credentials.usesRegion为假warningworkspaceID仅限 opencode 等workspace_unused设置workspaceID但 Provider 无workspaceIDValidationOrderwarningtokenAccounts仅在TokenAccountSupportCatalog内token_accounts_unused设置tokenAccounts但TokenAccountSupportCatalog.support(for:)返回 nilwarning额外未知 Providerunsupported_providerproviders[].id无 first-party 实现error额外secretKey误用secret_key_unused设置secretKey但 Provider 的credentials.usesSecretKey不为 true仅 bedrock、doubao 使用warning注意计划文档中 region 仅用于 zai 或 minimax 是对当前已知使用 region 的 Provider的概括源码的实际判定依据是每个 Provider 描述符的credentials.usesRegion标志validateRegion逻辑见 CodexBarConfigValidation.swift因此支持 region 的 Provider 集合以注册表为准这也是避免硬编码 Provider 名单的通用做法。3.4 Hooks 校验规则当配置包含hooks时HooksConfig以下错误码会被触发too_many_hook_rules规则数超过HooksConfig.maximumRuleCountduplicate_hook_id规则 ID 重复invalid_hook_executable可执行文件路径非空绝对路径invalid_hook_provider规则绑定的 Provider 未识别invalid_hook_threshold阈值必须 0 且 ≤ 1invalid_hook_timeout超时必须在 0.1300 秒之间invalid_hook_command_sizeID、参数或聚合命令尺寸超限。测试用例可见 Tests/CodexBarTests/ConfigValidationTests.swift其中reports unsafe hook rule fields与reports hook workload limits直接断言了上述错误码集合。四、CLI 命令config validate 与 config dump计划步骤 2 要求新增config validate命令可选新增config dump。两者均已落地命令注册在 CLIEntry.swift 的config子命令组中分发逻辑在 CLIConfigCommand.swift。4.1 codexbar config validate校验当前配置文件并输出问题列表# 文本摘要默认 codexbar config validate # JSON 数组输出机器可读 codexbar config validate --json-only codexbar config validate --format json --pretty行为细节见 CLIConfigCommand.swift加载配置后调用CodexBarConfigValidator.validate(config)文本模式无问题时打印Config: OK有问题时逐条打印[SEVERITY] provider (field): messageProvider 为空时显示configJSON 模式直接打印[CodexBarConfigIssue]数组--pretty可美化退出码只要存在任一severity .error的问题进程以.failure退出仅 warning 时仍以.success退出——这使config validate可直接用于 CI 门禁。4.2 codexbar config dump打印归一化后的配置 JSONcodexbar config dump # 脱敏输出 codexbar config dump --show-secrets # 原始密钥慎用源码中sanitizedForDump(showSecrets:)CodexBarConfig.swift在未指定--show-secrets时会把apiKey、secretKey、cookieHeader、pluginSecrets及tokenAccounts中的 token 替换为[REDACTED]避免明文密钥进入日志或终端。4.3 配套的 Provider 管理命令同一个config子命令组还包含计划之外的实用命令同样实现在 CLIConfigCommand.swiftcodexbar config providers列出每个 Provider 的enabled/disabled状态及是否默认启用codexbar config enable --provider name/codexbar config disable --provider name读写配置中的enabled字段并落盘codexbar config set-api-key --provider name [--api-key key | --stdin] [--no-enable]为支持 API source 的 Provider 写入密钥支持--stdin管道输入避免密钥进 shell 历史z.ai 团队 token 还支持--label、--usage-scope team、--organization-id、--workspace-id仅--provider zai接受这些参数源码见resolveConfigAPIKeyAccountOptions。需要注意codexbar config set-api-key --provider codex会报错并提示改用--provider openai见unsupportedAPIKeyErrorMessage因为 Codex 与 OpenAI Platform 是不同 Provider 实例。五、SettingsStore 拆分defaults 与 config 的职责分离计划步骤 5 要求把巨型SettingsStore.swift拆分为多个 500 行文件。该拆分已在Sources/CodexBar/目录完成当前布局为SettingsStore.swift核心状态定义与基础能力SettingsStoreConfig.swift由配置CodexBarConfig支撑的计算属性SettingsStoreDefaults.swift由默认值支撑的计算属性SettingsStoreProviderDetection.swiftProvider 检测逻辑另有 SettingsStoreTokenCost.swift、SettingsStoreTokenAccounts.swift、SettingsStoreMenuPreferences.swift、SettingsStoreMenuObservation.swift、SettingsStoreSync.swift、SettingsStoreConfigPersistence.swift 等按职责拆分的小文件。这种基础类型 领域扩展的组织方式让每个扩展文件只处理一类读取路径config-backed / defaults-backed / 检测逻辑配合.gitignore与格式化工具更容易维持行数上限。六、Provider toggles 清理与约束保持计划步骤 6 要求移除未使用的ProviderToggleStore及其测试同时保留 legacy toggles 的迁移路径。之所以要保留迁移路径是因为旧的启用/停用开关数据需要平滑并入新的providers[].enabled模型避免用户升级后丢失启用状态。约束方面enabled与顺序的语义定义在 CodexBarConfig.swiftproviders[]数组顺序即 Provider 展示与处理顺序orderedProviders()enabledProviders(metadata:)在计算启用集合时enabled缺省时回退到 Provider 元数据的defaultEnablednormalized()会为配置中缺失的 first-party Provider 追加默认配置alibaba token plan 例外地追加为chinaMainlandregion保证配置缺失条目不等于禁用。这些不变量有专门测试守护Tests/CodexBarTests/下的 SettingsStore 相关测试重构期间通过make test回归验证。七、验证与回归清单计划步骤 8 给出了完整的验证路径结合仓库现状可归纳为# 单元测试与风格检查 make test swiftformat Sources Tests swiftlint --strict make check # 本地编译运行冒烟 ./Scripts/compile_and_run.sh # CLI 端到端验证 codexbar --json-only --provider codex # JSON-only 错误载荷 codexbar config validate --json-only # 校验输出 JSON 数组 codexbar config validate # 文本摘要 非零退出码存在 error 时 codexbar config dump --pretty # 归一化配置转储脱敏关键回归点CLI json-only 错误载荷无效 source、无效 Provider 选择——对应测试在 Tests/CodexBarTests/CLIProviderSelectionTests.swift 与 CLIOutputTests.swift配置校验bad region / source / apiKey 字段——对应测试在 ConfigValidationTests.swift共 492 行覆盖 hooks 规则、Alibaba region、API 凭据等场景SettingsStore 顺序与 toggle 不变量继续通过。八、总结CodexBar 的 CLI 重构围绕错误即 JSON 数据与配置可被机器校验两条主线展开ProviderPayload/CLIErrorReporting提供了统一的 JSON 错误载荷出口CodexBarConfigValidator以CodexBarConfigIssueseverity/field/code/message的形态覆盖了计划中的全部校验规则并扩展出 hooks 校验config validate/config dump命令让配置问题在运行前即可被发现和排查SettingsStore的职责拆分则保证了代码库的可维护性。如果你正在为 CLI 工具设计机器可解析的错误协议或配置校验层本文涉及的错误码表格、校验触发条件与命令行为可直接作为参考蓝本。【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考