Skip to content

CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息

feat: 展示重置次数过期时间

Bobdd4ac0e60dc3
diff --git a/AGENTS.md b/AGENTS.md
index 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.pbxproj
index 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.swift
index 58e587d..cd8fc25 100644
--- a/CodexBar/Models/CodexQuotaModels.swift
+++ b/CodexBar/Models/CodexQuotaModels.swift
@@ -5,6 +5,7 @@ nonisolated struct CodexQuotaSnapshot: Equatable {
let account: CodexAccount
let planType: String?
let resetCreditsAvailableCount: Int?
+ let resetCreditExpirationDates: [Date]?
let generatedAt: Date
let 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.swift
new file mode 100644
index 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.swift
index 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 .initializationFailed
case 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 = false
func 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.swift
index 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: Bool
var 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.swift
index 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.md
index 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.md
index 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 events
diff --git a/README.md b/README.md
index 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.sh
index 7048849..7bb97e6 100755
--- a/Scripts/appcast.sh
+++ b/Scripts/appcast.sh
@@ -221,13 +221,13 @@ if [[ "${INCLUDE_RELEASE_NOTES}" != "0" ]]; then
fi
APPCAST_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.xml
index 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>