CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
feat: 展示重置次数过期时间
Bobdd4ac0e60dc3
diff --git a/AGENTS.md b/AGENTS.mdindex 1eb9ce0..ff4682a 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -132,6 +132,7 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省 `"codex"`。- 其余 limit 按 `limitName ?? limitId` 做 localized standard 排序, 再按 `limitId` 稳定排序。- `rateLimitResetCredits.availableCount` 读入 `resetCreditsAvailableCount`; 缺失时为 `nil`。+- `resetCreditsAvailableCount > 0` 时, 主 App 可使用本机 Codex OAuth token 请求 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits`; 401/403 时复用本轮认证刷新预算重试; 只保留可用且未过期的 `credits[].expires_at` 到 `resetCreditExpirationDates`, 请求失败时为 `nil` 且 UI 不展示过期时间 help text。- `primary` / `secondary` 合成 `[QuotaWindow]`; 没有窗口的 limit 被过滤。- `QuotaWindow.remainingPercent = clamp(100 - usedPercent, 0...100)`; 无 `usedPercent` 视为无数据。- `windowDurationMins` 标签: 整天 `ND`, 整小时 `NH`, 否则 `NM`, 缺失或非正数为「额度」。@@ -178,7 +179,7 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m- `LiquidGlassStyle.swift` 是自绘玻璃效果, 不是 macOS 原生 `.glassEffect`; 没有明确设计要求时不要切换。- 账号图标双击触发刷新。邮箱文本双击切换模糊。- 计划名是右侧加粗纯文字; `planBadgeTint(for:)` 优先级: enterprise -> team/business -> pro -> plus -> edu -> free -> 默认 cyan。-- `resetCreditsAvailableCount` 有值时, 只在置顶主 limit 标题右侧显示 `重置 xN`。+- `resetCreditsAvailableCount` 有值时, 只在置顶主 limit 标题右侧显示 `重置 xN`; `resetCreditExpirationDates` 非空时, 鼠标悬停在该文本上通过 help text 按升序逐行展示 `过期时间: yyyy-MM-dd HH:mm:ss [xN]`, 相同展示时间合并数量, 单个也显示 `x1`。- 额度条展示剩余百分比, 固定为 50 个胶囊, 每个胶囊宽 `3.5`, 间距 `2`, 高 `12`; 颜色按 20% 一档: 红、橙、黄、薄荷、绿。- 额度行标签列宽 `34`, 居中显示, 标签允许最小缩放到 `0.75`, 标签到额度条间距 `12`, 额度条到百分比间距 `8`, 百分比列宽 `37`, 百分比到重置时间最小间距 `6`, 重置时间列宽 `75`; 不通过加宽菜单面板解决额度行溢出。- 无 quota 数据时显示 `--` / `暂无数据`, 并使用占位色。@@ -236,9 +237,9 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m## 认证、隐私与沙盒-- CodexBar 只通过本机 Codex app-server 读取账号、额度和 token 使用量; 这些数据不发往第三方服务。+- CodexBar 主要通过本机 Codex app-server 读取账号、额度和 token 使用量; 为展示手动重置机会过期时间, 可使用本机 Codex OAuth token 向 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 发起只读请求, 只保留可展示的过期时间数组。- Codex Hook 工作流统计默认只写入本机 `~/Library/Application Support/CodexBar/HookEvents/`; 用户开启「跨设备同步」后, CloudKit 只保存去掉 `sessionIds` / `turnIds` 的 daily 聚合副本, 不保存原始 Hook events。-- 除 Sparkle appcast/DMG 下载, 以及用户显式开启「跨设备同步」后的 CloudKit private database 请求外, 应用自身不做网络请求。+- 除手动重置机会过期时间查询、Sparkle appcast/DMG 下载, 以及用户显式开启「跨设备同步」后的 CloudKit private database 请求外, 应用自身不做网络请求。- App Sandbox 必须保持关闭。- app-server 和版本探测必须使用真实用户 home。- 不要把 Codex auth 文件、stderr、原始敏感 RPC 响应或用户路径之外的敏感信息写入 UI、文档或测试夹具。diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxprojindex 1de4748..a5acc70 100644--- a/CodexBar.xcodeproj/project.pbxproj+++ b/CodexBar.xcodeproj/project.pbxproj@@ -282,7 +282,7 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 30;+ CURRENT_PROJECT_VERSION = 31;DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;@@ -298,7 +298,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.2.2;+ MARKETING_VERSION = 3.2.3;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";REGISTER_APP_GROUPS = YES;@@ -321,7 +321,7 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 30;+ CURRENT_PROJECT_VERSION = 31;DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;@@ -337,7 +337,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.2.2;+ MARKETING_VERSION = 3.2.3;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";PROVISIONING_PROFILE_SPECIFIER = "";diff --git a/CodexBar/Models/CodexQuotaModels.swift b/CodexBar/Models/CodexQuotaModels.swiftindex 58e587d..cd8fc25 100644--- a/CodexBar/Models/CodexQuotaModels.swift+++ b/CodexBar/Models/CodexQuotaModels.swift@@ -5,6 +5,7 @@ nonisolated struct CodexQuotaSnapshot: Equatable {let account: CodexAccountlet planType: String?let resetCreditsAvailableCount: Int?+ let resetCreditExpirationDates: [Date]?let generatedAt: Datelet limits: [CodexQuotaLimitSnapshot]let usage: CodexUsageSnapshot?@@ -138,6 +139,7 @@ nonisolated extension CodexQuotaSnapshot {init(accountResponse: AccountReadResponse,rateLimitsResponse: AccountRateLimitsResponse?,+ resetCreditExpirationDates: [Date]? = nil,usageResponse: AccountUsageResponse? = nil,isRateLimitsStale: Bool = false,isUsageStale: Bool = false,@@ -164,6 +166,7 @@ nonisolated extension CodexQuotaSnapshot {account: account,planType: rateLimitsResponse?.rateLimits.planType,resetCreditsAvailableCount: rateLimitsResponse?.rateLimitResetCredits?.availableCount,+ resetCreditExpirationDates: resetCreditExpirationDates,generatedAt: generatedAt,limits: limits,usage: usage,diff --git a/CodexBar/Services/CodexStatus/CodexResetCreditsService.swift b/CodexBar/Services/CodexStatus/CodexResetCreditsService.swiftnew file mode 100644index 0000000..a5965cf--- /dev/null+++ b/CodexBar/Services/CodexStatus/CodexResetCreditsService.swift@@ -0,0 +1,143 @@+import Foundation++nonisolated enum CodexResetCreditsService {+ enum FetchError: Error {+ case invalidResponse+ case unauthorized+ }++ private static let endpoint = URL(string: "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits")!+ private static let timeout: TimeInterval = 4++ static func fetchExpirationDates(environment: [String: String]) async throws -> [Date] {+ let credentials = try CodexOAuthCredentials.load(environment: environment)+ let request = makeRequest(credentials: credentials)+ let (data, response) = try await URLSession.shared.data(for: request)+ guard let httpResponse = response as? HTTPURLResponse else {+ throw FetchError.invalidResponse+ }++ switch httpResponse.statusCode {+ case 200 ... 299:+ return try decodeExpirationDates(from: data)+ case 401, 403:+ throw FetchError.unauthorized+ default:+ throw FetchError.invalidResponse+ }+ }++ private static func makeRequest(credentials: CodexOAuthCredentials) -> URLRequest {+ var request = URLRequest(url: endpoint, timeoutInterval: timeout)+ request.httpMethod = "GET"+ request.setValue("Bearer \(credentials.accessToken)", forHTTPHeaderField: "Authorization")+ request.setValue("CodexBar", forHTTPHeaderField: "User-Agent")+ request.setValue("application/json", forHTTPHeaderField: "Accept")+ request.setValue("Codex Desktop", forHTTPHeaderField: "originator")++ if let accountId = credentials.accountId, !accountId.isEmpty {+ request.setValue(accountId, forHTTPHeaderField: "ChatGPT-Account-ID")+ }++ return request+ }++ private static func decodeExpirationDates(from data: Data) throws -> [Date] {+ let decoder = JSONDecoder()+ decoder.dateDecodingStrategy = .custom(Self.decodeISO8601Date)+ let payload = try decoder.decode(RateLimitResetCreditsResponse.self, from: data)+ let now = Date()++ return payload.credits+ .compactMap { credit in+ guard credit.status == "available",+ let expiresAt = credit.expiresAt,+ expiresAt > now else {+ return nil+ }++ return expiresAt+ }+ .sorted()+ }++ private static func decodeISO8601Date(from decoder: Decoder) throws -> Date {+ let container = try decoder.singleValueContainer()+ let raw = try container.decode(String.self)+ if let date = CodexDateFormat.iso8601FractionalDate(from: raw)+ ?? CodexDateFormat.iso8601InternetDateTimeDate(from: raw) {+ return date+ }++ throw DecodingError.dataCorruptedError(+ in: container,+ debugDescription: "Invalid ISO-8601 date: \(raw)"+ )+ }+}++private nonisolated extension CodexResetCreditsService {+ struct RateLimitResetCreditsResponse: Decodable {+ let credits: [RateLimitResetCredit]+ }++ struct RateLimitResetCredit: Decodable {+ let status: String+ let expiresAt: Date?++ private enum CodingKeys: String, CodingKey {+ case status+ case expiresAt = "expires_at"+ }+ }++ struct CodexOAuthCredentials {+ let accessToken: String+ let accountId: String?++ static func load(environment: [String: String]) throws -> Self {+ let authURL = authFileURL(environment: environment)+ let data = try Data(contentsOf: authURL)+ let authFile = try JSONDecoder().decode(CodexAuthFile.self, from: data)+ guard let accessToken = authFile.tokens?.accessToken, !accessToken.isEmpty else {+ throw FetchError.invalidResponse+ }++ return Self(accessToken: accessToken, accountId: authFile.tokens?.accountId)+ }++ private static func authFileURL(environment: [String: String]) -> URL {+ if let codexHome = nonEmptyEnvironmentValue("CODEX_HOME", in: environment) {+ return URL(fileURLWithPath: codexHome).appendingPathComponent("auth.json")+ }++ let home = nonEmptyEnvironmentValue("HOME", in: environment) ?? NSHomeDirectory()+ let homeURL = URL(fileURLWithPath: home)+ return homeURL+ .appendingPathComponent(".codex")+ .appendingPathComponent("auth.json")+ }++ private static func nonEmptyEnvironmentValue(+ _ key: String,+ in environment: [String: String]+ ) -> String? {+ let value = environment[key]?.trimmingCharacters(in: .whitespacesAndNewlines)+ return value?.isEmpty == false ? value : nil+ }+ }++ struct CodexAuthFile: Decodable {+ let tokens: Tokens?++ struct Tokens: Decodable {+ let accessToken: String?+ let accountId: String?++ private enum CodingKeys: String, CodingKey {+ case accessToken = "access_token"+ case accountId = "account_id"+ }+ }+ }+}diff --git a/CodexBar/Services/CodexStatus/CodexStatusService.swift b/CodexBar/Services/CodexStatus/CodexStatusService.swiftindex db6a35d..5d4de75 100644--- a/CodexBar/Services/CodexStatus/CodexStatusService.swift+++ b/CodexBar/Services/CodexStatus/CodexStatusService.swift@@ -98,7 +98,7 @@ actor CodexStatusService {}func fetchOutcome() async -> CodexFetchOutcome {- resolveOutcome(allowRebuild: true)+ await resolveOutcome(allowRebuild: true)}func currentConnectionInfo() async -> CodexCLIConnectionInfo? {@@ -138,7 +138,7 @@ actor CodexStatusService {/// 复用连接出现传输故障时只重建重试一次/// 避免故障状态下反复拉起进程- private func resolveOutcome(allowRebuild: Bool) -> CodexFetchOutcome {+ private func resolveOutcome(allowRebuild: Bool) async -> CodexFetchOutcome {switch ensureConnection() {case .notLoggedIn:return .notLoggedIn@@ -146,7 +146,7 @@ actor CodexStatusService {return .initializationFailedcase let .ready(connection, reused):do {- let snapshot = try fetchData(using: connection, refreshAccountInfo: reused)+ let snapshot = try await fetchData(using: connection, refreshAccountInfo: reused)return .data(snapshot)} catch FetchFailure.notLoggedIn {supplementalDataCache = SupplementalDataCache()@@ -155,7 +155,7 @@ actor CodexStatusService {} catch FetchFailure.needsRebuild {teardownConnection()if reused, allowRebuild {- return resolveOutcome(allowRebuild: false)+ return await resolveOutcome(allowRebuild: false)}return .initializationFailed} catch {@@ -220,7 +220,7 @@ actor CodexStatusService {/// 额度与用量独立读取/// 认证失败全程只刷新一次 token/// 传输故障交给外层重建连接- private func fetchData(using connection: AppServerConnection, refreshAccountInfo: Bool) throws -> CodexQuotaSnapshot {+ private func fetchData(using connection: AppServerConnection, refreshAccountInfo: Bool) async throws -> CodexQuotaSnapshot {var didRefresh = falsefunc refreshTokenIfNeeded() throws {@@ -282,11 +282,17 @@ actor CodexStatusService {cache: &supplementalDataCache.usage)+ let resetCreditExpirationDates = await fetchResetCreditExpirationDates(+ availableCount: rateLimitsRead.value?.rateLimitResetCredits?.availableCount,+ refreshTokenIfNeeded: refreshTokenIfNeeded+ )+// rateLimits/usage 都可为空, 只要账户有效就让 UI 展示"暂无数据"guard let snapshot = try? CodexQuotaSnapshot(accountResponse: connection.accountResponse,rateLimitsResponse: rateLimitsRead.value,+ resetCreditExpirationDates: resetCreditExpirationDates,usageResponse: usageRead.value,isRateLimitsStale: rateLimitsRead.isStale,isUsageStale: usageRead.isStale@@ -297,6 +303,33 @@ actor CodexStatusService {return snapshot}+ private func fetchResetCreditExpirationDates(+ availableCount: Int?,+ refreshTokenIfNeeded: () throws -> Void+ ) async -> [Date]? {+ guard let availableCount, availableCount > 0 else {+ return nil+ }++ func fetchExpirationDates() async throws -> [Date] {+ try await CodexResetCreditsService.fetchExpirationDates(environment: Self.environment)+ }++ do {+ return try await fetchExpirationDates()+ } catch CodexResetCreditsService.FetchError.unauthorized {+ do {+ try refreshTokenIfNeeded()+ } catch {+ return nil+ }++ return try? await fetchExpirationDates()+ } catch {+ return nil+ }+ }+/// 新值更新缓存/// 本轮请求失败则回退到缓存并标记陈旧/// 方法不支持/认证/断连一律视为无数据diff --git a/CodexBar/Views/Menu/CodexStatusMenuSections.swift b/CodexBar/Views/Menu/CodexStatusMenuSections.swiftindex 26092ce..d28c33f 100644--- a/CodexBar/Views/Menu/CodexStatusMenuSections.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuSections.swift@@ -137,6 +137,7 @@ struct EmptyDataPanel: View {struct QuotaLimitsSection: View {let limits: [CodexQuotaLimitSnapshot]let resetCreditsAvailableCount: Int?+ let resetCreditExpirationDates: [Date]?let isStale: Boolvar body: some View {@@ -166,11 +167,7 @@ struct QuotaLimitsSection: View {Spacer(minLength: 8)if showsResetCredits, let resetCreditsText {- Text(resetCreditsText)- .font(.caption2.weight(.semibold))- .foregroundStyle(.secondary)- .lineLimit(1)- .fixedSize(horizontal: true, vertical: false)+ resetCreditsLabel(resetCreditsText)}}@@ -190,6 +187,55 @@ struct QuotaLimitsSection: View {resetCreditsAvailableCount.map { "重置 x\($0)" }}+ @ViewBuilder+ private func resetCreditsLabel(_ text: String) -> some View {+ let label = Text(text)+ .font(.caption2.weight(.semibold))+ .foregroundStyle(.secondary)+ .lineLimit(1)+ .fixedSize(horizontal: true, vertical: false)++ if let helpText = resetCreditsHelpText {+ label.help(helpText)+ } else {+ label+ }+ }++ private var resetCreditsHelpText: String? {+ guard let resetCreditExpirationDates, !resetCreditExpirationDates.isEmpty else {+ return nil+ }++ return groupedResetCreditExpirationLines(from: resetCreditExpirationDates)+ .joined(separator: "\n")+ }++ private func groupedResetCreditExpirationLines(from dates: [Date]) -> [String] {+ let expirationTexts = dates+ .sorted()+ .map { Self.resetCreditExpirationFormatter.string(from: $0) }++ let groups = expirationTexts.reduce(into: [(expirationText: String, count: Int)]()) { groups, expirationText in+ if let lastIndex = groups.indices.last, groups[lastIndex].expirationText == expirationText {+ groups[lastIndex].count += 1+ } else {+ groups.append((expirationText: expirationText, count: 1))+ }+ }++ return groups.map { group in+ "过期时间: \(group.expirationText) [x\(group.count)]"+ }+ }++ private static let resetCreditExpirationFormatter: DateFormatter = {+ let formatter = DateFormatter()+ formatter.locale = Locale(identifier: "en_US_POSIX")+ formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"+ return formatter+ }()+private func isPrimaryLimit(_ limit: CodexQuotaLimitSnapshot) -> Bool {limit.id == primaryLimitId}diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swiftindex c1840d2..91fdbe0 100644--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift@@ -75,6 +75,7 @@ private extension CodexStatusMenuView {QuotaLimitsSection(limits: snapshot.limits,resetCreditsAvailableCount: snapshot.resetCreditsAvailableCount,+ resetCreditExpirationDates: snapshot.resetCreditExpirationDates,isStale: snapshot.isRateLimitsStale)}diff --git a/Docs/AppServer.md b/Docs/AppServer.mdindex ca9aea6..5260ba0 100644--- a/Docs/AppServer.md+++ b/Docs/AppServer.md@@ -49,7 +49,7 @@ codex app-server --listen stdio://同一会话后续读取:- `account/read` 每轮复用连接时用 `refreshToken: false` 更新账户状态。-- `account/rateLimits/read` 读取额度, 包括可选的 `rateLimitResetCredits.availableCount`。+- `account/rateLimits/read` 读取额度, 包括可选的 `rateLimitResetCredits.availableCount`。当可用重置次数大于 0 时, 主 App 会通过 `CodexResetCreditsService` 额外读取本机 Codex OAuth token, 只读请求 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 获取各重置机会的 `expires_at`; 这条请求不走 app-server 日志, 失败时只是不展示过期时间 tooltip。- `account/usage/read` 读取 `summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`。- `config/read` 在开启 Codex Hook 前读取有效配置,用于判断 `[features] hooks = false` 或兼容旧名 `codex_hooks = false` 是否禁用了 Hook;关闭清理时也读取 `hooks.state` 以保留其他 Hook 的信任状态。- `hooks/list` 在写入 Hook 后或设置页刷新时验证 Codex 实际识别到的 Hook,检查 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`key`、`currentHash`、`warnings` 和 `errors`。@@ -60,6 +60,7 @@ codex app-server --listen stdio://- `rateLimitsByLimitId` 优先于顶层 `rateLimits`; 为空时回退顶层 `rateLimits`。- 顶层 `rateLimits.limitId` 指向主 limit, 缺省为 `codex`。- `rateLimitResetCredits.availableCount` 是可用额度重置次数; 字段缺失时 UI 不显示重置次数。+- `rateLimitResetCredits.availableCount > 0` 时, `CodexResetCreditsService` 使用真实用户 `CODEX_HOME/auth.json` 或 `HOME/.codex/auth.json` 中的 access token 请求 ChatGPT backend, 超时为 4 秒。401/403 时复用本轮认证刷新预算调用一次 `account/read(refreshToken:true)` 后重试; 其他失败静默降级。成功响应只保留 `status == "available"` 且未过期 credit 的 `expires_at`, 按时间升序展示在 `重置 xN` 的 help text 中, 格式为 `过期时间: yyyy-MM-dd HH:mm:ss [xN]`; 相同展示时间合并数量, 单个也显示 `x1`。认证失败时,同会话最多调用一次 `account/read(refreshToken:true)` 后重试原读取。diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.mdindex d286349..e96ad98 100644--- a/Docs/DevelopmentGuide.md+++ b/Docs/DevelopmentGuide.md@@ -15,7 +15,7 @@ App 通过本机 Codex app-server 读取账号, 额度和 token 用量, 通过 C- 应用形态是 `LSUIElement`, 不显示 Dock 图标, 不依赖主窗口- 最低系统版本是 macOS 15.0- App Sandbox 保持关闭, 因为需要启动本机 `codex`, 读取真实用户 Codex 登录状态, 并写入用户级 Hook 配置-- 除 Sparkle 检查/下载更新, 以及用户显式开启「跨设备同步」后的 CloudKit private database 同步外, App 自身不发起网络请求+- 除手动重置机会过期时间查询、Sparkle 检查/下载更新, 以及用户显式开启「跨设备同步」后的 CloudKit private database 同步外, App 自身不发起网络请求- 账号, 额度和 token 用量只在本机处理, 不发送给第三方;Hook 工作流统计默认只在本机处理, 仅在用户开启「跨设备同步」后把脱敏 daily 聚合行同步到当前 iCloud 账号- Swift 工程使用 Swift 6 并开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, UI 默认 MainActor 隔离;服务共享状态优先用 actor 管理, DTO、模型、同步辅助类型和静态工具需要显式使用 `nonisolated`@@ -378,22 +378,23 @@ codex app-server --listen stdio://app-server 与状态刷新错误:-| 错误来源 | 检测位置 | 用户可见状态 | 日志或存储 | 重试或降级 |-| -------------------------------------------- | -------------------------------------------- | ---------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |-| 找不到全局 Codex CLI 和 Codex APP 内置 CLI | `CodexCLIResolver.resolveAppServerCommand()` | `初始化失败` | `RequestLogStorage.recordFailure` 记录可读错误 | 不启动 app-server, 下轮刷新重新解析 |-| app-server 进程启动失败 | `Process.run()` | `初始化失败` | 记录"app-server 启动失败" | 不复用本次进程, 下轮刷新重试 |-| `initialize` 或首次 `account/read` 失败 | `CodexStatusService.openConnection` | `初始化失败` | 对应 JSON-RPC 请求进入日志 | 关闭本次 session, 不重复完整握手 |-| 首次 `account/read` 返回 `account == nil` | `CodexStatusService.openConnection` | `未登录` | 请求响应进入日志 | 关闭本次 session, 不生成 snapshot |-| 复用连接刷新 account 后返回 `account == nil` | `CodexStatusService.fetchData` | `未登录` | 请求响应进入日志 | 清空 supplemental cache, teardown connection |-| JSON-RPC 认证失败 | `CodexStatusError.isAuthenticationRequired` | 取决于刷新后结果 | 失败响应进入日志 | 同一轮最多 `account/read(refreshToken:true)` 一次, 然后重试原读取 |-| refresh token 后仍认证失败 | `ReadResult.resultAfterAuthAttempt` | `未登录` | 失败响应进入日志 | 清空 cache, teardown connection |-| unsupported method | `CodexStatusError.isUnsupportedMethod` | 对应区域可能显示无数据 | 失败响应进入日志 | 当前 session 记住 method, 后续跳过, 不复用旧缓存 |-| 非认证业务错误 | `CodexStatusError.isRetriableServerError` | 通常不改变整体状态 | 失败响应进入日志 | 同请求立即重试一次, 仍失败则 supplemental 读取按失败处理 |-| rate limits 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无额度区 | 失败进入日志 | 同账号旧缓存复用并标记 `isRateLimitsStale` |-| usage 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无用量区 | 失败进入日志 | 同账号旧缓存复用并标记 `isUsageStale` |-| 连接断开, 请求超时, 响应解析失败 | `CodexStatusError.isTransportFailure` | 复用连接重建失败后为 `初始化失败` | 请求标记为错误 | 复用连接只重建重试一次, 新连接失败不再重试 |-| app-server 关闭超时 | `AppServerSession.close()` | 不直接改变 UI | 记录强制结束或仍在后台运行 | 先 terminate 等 1 秒, 再 SIGKILL 等 0.5 秒 |-| snapshot 无可信 quota 和 usage | `CodexQuotaSnapshot.hasTrustedData` | 菜单栏切换错误图标 | 不新增日志 | 仍可展示 stale 数据或无数据面板 |+| 错误来源 | 检测位置 | 用户可见状态 | 日志或存储 | 重试或降级 |+| -------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |+| 找不到全局 Codex CLI 和 Codex APP 内置 CLI | `CodexCLIResolver.resolveAppServerCommand()` | `初始化失败` | `RequestLogStorage.recordFailure` 记录可读错误 | 不启动 app-server, 下轮刷新重新解析 |+| app-server 进程启动失败 | `Process.run()` | `初始化失败` | 记录"app-server 启动失败" | 不复用本次进程, 下轮刷新重试 |+| `initialize` 或首次 `account/read` 失败 | `CodexStatusService.openConnection` | `初始化失败` | 对应 JSON-RPC 请求进入日志 | 关闭本次 session, 不重复完整握手 |+| 首次 `account/read` 返回 `account == nil` | `CodexStatusService.openConnection` | `未登录` | 请求响应进入日志 | 关闭本次 session, 不生成 snapshot |+| 复用连接刷新 account 后返回 `account == nil` | `CodexStatusService.fetchData` | `未登录` | 请求响应进入日志 | 清空 supplemental cache, teardown connection |+| JSON-RPC 认证失败 | `CodexStatusError.isAuthenticationRequired` | 取决于刷新后结果 | 失败响应进入日志 | 同一轮最多 `account/read(refreshToken:true)` 一次, 然后重试原读取 |+| refresh token 后仍认证失败 | `ReadResult.resultAfterAuthAttempt` | `未登录` | 失败响应进入日志 | 清空 cache, teardown connection |+| unsupported method | `CodexStatusError.isUnsupportedMethod` | 对应区域可能显示无数据 | 失败响应进入日志 | 当前 session 记住 method, 后续跳过, 不复用旧缓存 |+| 非认证业务错误 | `CodexStatusError.isRetriableServerError` | 通常不改变整体状态 | 失败响应进入日志 | 同请求立即重试一次, 仍失败则 supplemental 读取按失败处理 |+| rate limits 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无额度区 | 失败进入日志 | 同账号旧缓存复用并标记 `isRateLimitsStale` |+| usage 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无用量区 | 失败进入日志 | 同账号旧缓存复用并标记 `isUsageStale` |+| 重置机会过期时间请求失败 | `CodexStatusService.fetchResetCreditExpirationDates` / `CodexResetCreditsService` | `重置 xN` 保留, 不显示过期时间 help text | 不展示错误, 不保存原始响应 | 401/403 时复用本轮认证刷新预算重试, 其他失败静默降级为 `nil` |+| 连接断开, 请求超时, 响应解析失败 | `CodexStatusError.isTransportFailure` | 复用连接重建失败后为 `初始化失败` | 请求标记为错误 | 复用连接只重建重试一次, 新连接失败不再重试 |+| app-server 关闭超时 | `AppServerSession.close()` | 不直接改变 UI | 记录强制结束或仍在后台运行 | 先 terminate 等 1 秒, 再 SIGKILL 等 0.5 秒 |+| snapshot 无可信 quota 和 usage | `CodexQuotaSnapshot.hasTrustedData` | 菜单栏切换错误图标 | 不新增日志 | 仍可展示 stale 数据或无数据面板 |日志错误处理:@@ -472,6 +473,7 @@ Codex 版本探测错误:- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省为 `codex`- 其他 limit 按 `limitName ?? limitId` localized standard 排序, 再按 `limitId` 稳定排序- `rateLimitResetCredits.availableCount` 写入 `resetCreditsAvailableCount`, 缺失时不展示重置次数+- 如果 `resetCreditsAvailableCount > 0`, `CodexResetCreditsService` 会用真实用户 `CODEX_HOME/auth.json` 或 `HOME/.codex/auth.json` 中的 access token, 只读请求 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits`; 401/403 时复用本轮认证刷新预算, 尚未刷新过时通过当前 app-server 会话刷新一次 token 后重试。成功时将可用且未过期的 `credits[].expires_at` 按升序写入 `resetCreditExpirationDates`; 请求失败时为 `nil`- 每个 limit 的 `primary` 和 `secondary` 合成 `[QuotaWindow]`- 没有窗口的 limit 被过滤- `remainingPercent = clamp(100 - usedPercent, 0...100)`@@ -530,7 +532,7 @@ flowchart TD额度区:- 多个 limit 间用 `LiquidGlassDivider` 分隔-- 如果 `resetCreditsAvailableCount` 有值, 只在置顶主 limit 标题右侧显示 `重置 xN`+- 如果 `resetCreditsAvailableCount` 有值, 只在置顶主 limit 标题右侧显示 `重置 xN`; 如果 `resetCreditExpirationDates` 非空, 鼠标悬停时通过 help text 按 `过期时间: yyyy-MM-dd HH:mm:ss [xN]` 逐行展示过期时间, 相同展示时间合并数量, 单个也显示 `x1`- 每个 quota window 展示标签, 50 个固定胶囊组成的电量条, 剩余百分比和重置时间- 胶囊宽度为 `3.5`, 间距为 `2`, 高度为 `12`- 额度行标签列宽 `34`, 居中显示, 标签允许最小缩放到 `0.75`, 标签到电量条间距 `12`, 电量条到百分比间距 `8`, 百分比列宽 `37`, 百分比到重置时间最小间距 `6`, 重置时间列宽 `75`@@ -1025,7 +1027,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并隐私和敏感信息边界:- 不展示 app-server stderr-- 不读取或展示 Codex auth 文件内容+- 不展示 Codex OAuth token 或 `auth.json` 内容; 只用 access token 发起 `rate-limit-reset-credits` 只读请求, 丢弃原始响应, 只保留可用且未过期的过期时间数组- 不把原始敏感 RPC 响应写入文档或测试夹具- 日志完整保存 request/detail, UI 默认只渲染单行预览; 完整内容通过标题行预览或复制查看- Hook 统计默认只保存在用户 Application Support 的 CodexBar 目录;开启「跨设备同步」后, CloudKit 只保存去掉 `sessionIds` / `turnIds` 的 daily 聚合副本, 不保存原始 Hook eventsdiff --git a/README.md b/README.mdindex 2c0c740..02003aa 100644--- a/README.md+++ b/README.md@@ -32,7 +32,7 @@ CodexBar 是一个无 Dock 图标的 macOS 菜单栏应用。### 额度与重置时间一眼可见-额度区用分段电量条展示不同时间窗口的剩余额度,并显示剩余百分比和重置时间+额度区用分段电量条展示不同时间窗口的剩余额度,并显示剩余百分比和重置时间。存在可用手动重置机会时,鼠标悬停在 `重置 xN` 上会显示各重置机会的过期时间和数量。### 近 30 周 Token 热力图@@ -88,7 +88,7 @@ CodexBar 使用 Sparkle 检查更新。安装后,新版本会通过内置更## 隐私-CodexBar 默认只和本机 Codex app-server 通信,用于读取账号、额度和 Token 用量。这些数据不会发送到任何人或第三方服务。+CodexBar 默认通过本机 Codex app-server 读取账号、额度和 Token 用量。若 app-server 返回可用手动重置机会,CodexBar 会使用本机 Codex OAuth token 向 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 发起只读请求,用于读取这些重置机会的过期时间;请求失败时不会展示过期时间,也不会保留原始响应。Codex Hook 工作流数据默认只保存在本机:@@ -98,7 +98,7 @@ Codex Hook 工作流数据默认只保存在本机:只有在用户开启「跨设备同步」后,CodexBar 才会通过 `CloudKit private database` 同步每日使用详情数据; 同步的数据副本只包含各个事件数量,不包含事件具体的数据。-除 Sparkle appcast / DMG 下载,以及用户开启跨设备同步后的 CloudKit 请求外,CodexBar 自身不发起其他网络请求。+除上述重置机会过期时间查询、Sparkle appcast / DMG 下载,以及用户开启跨设备同步后的 CloudKit 请求外,CodexBar 自身不发起其他网络请求。## 从源码构建diff --git a/Scripts/appcast.sh b/Scripts/appcast.shindex 7048849..7bb97e6 100755--- a/Scripts/appcast.sh+++ b/Scripts/appcast.sh@@ -221,13 +221,13 @@ if [[ "${INCLUDE_RELEASE_NOTES}" != "0" ]]; thenfiAPPCAST_ITEM=" <item>- <title>${TITLE}</title>- <sparkle:version>${BUILD_VERSION}</sparkle:version>- <sparkle:shortVersionString>${SHORT_VERSION}</sparkle:shortVersionString>- <sparkle:minimumSystemVersion>${MIN_SYSTEM_ESCAPED}</sparkle:minimumSystemVersion>- ${RELEASE_NOTES_XML} <pubDate>${PUB_DATE}</pubDate>- <enclosure url=\"${DOWNLOAD_URL_ESCAPED}\" sparkle:edSignature=\"${ED_SIGNATURE_ESCAPED}\" length=\"${ARCHIVE_LENGTH}\" type=\"application/octet-stream\"/>-</item>"+ <title>${TITLE}</title>+ <sparkle:version>${BUILD_VERSION}</sparkle:version>+ <sparkle:shortVersionString>${SHORT_VERSION}</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>${MIN_SYSTEM_ESCAPED}</sparkle:minimumSystemVersion>+ ${RELEASE_NOTES_XML} <pubDate>${PUB_DATE}</pubDate>+ <enclosure url=\"${DOWNLOAD_URL_ESCAPED}\" sparkle:edSignature=\"${ED_SIGNATURE_ESCAPED}\" length=\"${ARCHIVE_LENGTH}\" type=\"application/octet-stream\"/>+ </item>"echo "==> Updating appcast"APPCAST_ITEM="${APPCAST_ITEM}" APPCAST_VERSION="${BUILD_VERSION}" perl -0pi -e 'diff --git a/appcast.xml b/appcast.xmlindex bce6a3d..5d898d4 100644--- a/appcast.xml+++ b/appcast.xml@@ -7,6 +7,15 @@<link>https://codexbar.zabrian.app/appcast.xml</link><description>CodexBar appcast feed</description><language>zh-CN</language>+ <item>+ <title>CodexBar.app 3.2.3</title>+ <sparkle:version>31</sparkle:version>+ <sparkle:shortVersionString>3.2.3</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.2.3</sparkle:releaseNotesLink>+ <pubDate>Mon, 29 Jun 2026 13:04:49 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.2.3.dmg" sparkle:edSignature="OXJfyNWHk28CvigPBo2OHFW2jbAw9d2pz+OCXVtpIu2WGGylOnLN1Gs5qvGRqd5DsTqMhbuF/zq79eAT3PBVAA==" length="3384594" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.2.2</title><sparkle:version>30</sparkle:version>