CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
feat: 更新应用图标并发布 3.4.0
Bob6c668c31b431
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxprojindex 6896712..0a3ddda 100644--- a/CodexBar.xcodeproj/project.pbxproj+++ b/CodexBar.xcodeproj/project.pbxproj@@ -274,7 +274,7 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 49;+ CURRENT_PROJECT_VERSION = 50;DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;@@ -290,7 +290,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.3.11;+ MARKETING_VERSION = 3.4.0;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";REGISTER_APP_GROUPS = YES;@@ -313,7 +313,7 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 49;+ CURRENT_PROJECT_VERSION = 50;DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;@@ -329,7 +329,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.3.11;+ MARKETING_VERSION = 3.4.0;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";PROVISIONING_PROFILE_SPECIFIER = "";diff --git a/CodexBar/Resources/AppIcon.icon/Assets/AppIcon.png b/CodexBar/Resources/AppIcon.icon/Assets/AppIcon.pngnew file mode 100644index 0000000..4c77a8dBinary files /dev/null and b/CodexBar/Resources/AppIcon.icon/Assets/AppIcon.png differdiff --git a/CodexBar/Resources/AppIcon.icon/Assets/bar-black.png b/CodexBar/Resources/AppIcon.icon/Assets/bar-black.pngdeleted file mode 100644index 1fe6f53..0000000Binary files a/CodexBar/Resources/AppIcon.icon/Assets/bar-black.png and /dev/null differdiff --git a/CodexBar/Resources/AppIcon.icon/Assets/bar-white.png b/CodexBar/Resources/AppIcon.icon/Assets/bar-white.pngdeleted file mode 100644index c247719..0000000Binary files a/CodexBar/Resources/AppIcon.icon/Assets/bar-white.png and /dev/null differdiff --git a/CodexBar/Resources/AppIcon.icon/Assets/codex-black.png b/CodexBar/Resources/AppIcon.icon/Assets/codex-black.pngdeleted file mode 100644index ac91e87..0000000Binary files a/CodexBar/Resources/AppIcon.icon/Assets/codex-black.png and /dev/null differdiff --git a/CodexBar/Resources/AppIcon.icon/Assets/codex-white.png b/CodexBar/Resources/AppIcon.icon/Assets/codex-white.pngdeleted file mode 100644index be762e0..0000000Binary files a/CodexBar/Resources/AppIcon.icon/Assets/codex-white.png and /dev/null differdiff --git a/CodexBar/Resources/AppIcon.icon/icon.json b/CodexBar/Resources/AppIcon.icon/icon.jsonindex fb0b91f..8f5a0d5 100644--- a/CodexBar/Resources/AppIcon.icon/icon.json+++ b/CodexBar/Resources/AppIcon.icon/icon.json@@ -1,47 +1,15 @@{- "fill" : "automatic",+ "color-space-for-untagged-svg-colors" : "display-p3",+ "fill" : {+ "solid" : "extended-gray:1.00000,1.00000"+ },"groups" : [{"layers" : [{- "glass" : false,- "image-name-specializations" : [- {- "value" : "bar-white.png"- },- {- "appearance" : "light",- "value" : "bar-black.png"- }- ],- "name" : "bar",- "position" : {- "scale" : 1,- "translation-in-points" : [- 0,- 340- ]- }- },- {- "glass" : false,- "image-name-specializations" : [- {- "value" : "codex-white.png"- },- {- "appearance" : "light",- "value" : "codex-black.png"- }- ],- "name" : "codex",- "position" : {- "scale" : 1,- "translation-in-points" : [- 0,- -50- ]- }+ "glass" : true,+ "image-name" : "AppIcon.png",+ "name" : "AppIcon"}],"shadow" : {diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swiftindex 7769163..701dc8f 100644--- a/CodexBar/Views/Settings/AppSettingsView.swift+++ b/CodexBar/Views/Settings/AppSettingsView.swift@@ -218,7 +218,7 @@ private extension AppSettingsView {return SettingsToggleRow(icon: "list.bullet.rectangle",- title: "主面板任务中心",+ title: "任务中心",isOn: Binding(get: { isDisplayedOn },set: { mainPanelSettings.setShowsTaskCenter($0) }diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.mdindex 62d2aa1..ee9748b 100644--- a/Docs/DevelopmentGuide.md+++ b/Docs/DevelopmentGuide.md@@ -945,7 +945,7 @@ App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主| 开机自动启动 | `SMAppService.mainApp.status` | `register()` / `unregister()` || 自动检查更新 | Sparkle updater | 设置 `automaticallyChecksForUpdates` || 菜单栏额度指示 | `MenuBarQuotaSettings.selection` / `MenuBarQuota.lastWindowSelection` | 开关写入 `.off` 或恢复持久化的上次窗口选择, 窗口菜单写入所选窗口并同步记住; 标签优先来自当前账号 Codex limit 返回的额度窗口, 缺失时使用 fallback 标题 |-| 主面板任务中心 | `MainPanelSettings.showsTaskCenter` + Codex Hook 状态 | 写入 `MainPanel.showsTaskCenter`; 缺失时默认开启。Hook 关闭时显示为关闭并置灰但保留偏好, 重新开启后恢复 |+| 任务中心 | `MainPanelSettings.showsTaskCenter` + Codex Hook 状态 | 写入 `MainPanel.showsTaskCenter`; 缺失时默认开启。Hook 关闭时显示为关闭并置灰但保留偏好, 重新开启后恢复 || 系统通知 | `NotificationSettings` + `UNUserNotificationCenter` | 总开关、五类通知子开关、任务触觉开关与阈值写入 `UserDefaults`; 首次开启时请求系统通知授权 || Codex TUI 通知 | `CodexCLINotificationSettings` + app-server `config/read` / `config/batchWrite` | 读取用户级 `[tui].notifications`; 缺失时按开启处理,关闭/开启分别 upsert `false` / `true`,不修改顶层 `notify` || 使用快捷键 | `GlobalHotKeySettings.shortcut` | 写入 `UserDefaults` 并注册 hot key |@@ -1133,7 +1133,7 @@ App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主活动并发以 session 为边界:不同 session 可以同时运行;同一 session 的 turn 按顺序执行。收到新的 `UserPromptSubmit` 时,monitor 会让该 session 中更早且缺少结束信号的 turn 立即退出活动列表,但保留为等待终态确认任务并触发一次即时 rollout 查询;5 秒内收到 Hook `Stop`、rollout `task_complete` 或 `turn_aborted` 时按真实终态归类,到期仍无终态才生成灰色最近终止记录。子 Agent 事件只能通过共享 session 关联父任务,早于当前顶层任务可信开始时间的事件会被当作上一 turn 的迟到事件忽略。已完成和已终止任务键分别保留 24 小时 tombstone,避免迟到事件恢复旧任务或误操作同 session 的新 turn。终止不会触发绿色完成状态、长任务通知或完成触觉反馈。Hook `Stop` 与 rollout `task_complete` 均视为完成信号,先到者生效,后到者按任务键和 session 回退键去重;重复完成不会覆盖首次确认结果,也不会缩短去重窗口或再次触发反馈。-设置页交互: 「系统通知」主开关行保留在设置窗口内, 子选项 (五类通知子开关、任务触觉开关、Codex TUI 通知开关与两个阈值 Picker) 在主选项右侧的子面板中展开 (`NotificationOptionsPanelController`, 复用 SidePanelSupport 抽屉机制挂在设置窗口上, 内容用常驻 hosting controller + ObservableObject 驱动, 面板尺寸在 Hook 开/关两种状态下保持不变)。「任务等待通知」和「任务触觉反馈」依次排列在「任务完成通知」下方。主开关开启后仅在系统授权允许时展开, 首次授权场景会等待授权结果; 点击行内滑杆按钮可手动展开; 设置窗口 resign key/关闭、主开关关闭或授权变为被拒时自动收起。任务完成、任务等待与任务触觉子项在 Hook 未开启时显示为关闭并置灰, 不修改各自持久化偏好, Hook 重新开启后恢复用户原选择。「Codex TUI 通知」与用户级 `[tui] notifications` 联动,面板打开时刷新,写入后回读验证;已有 CLI 会话需重启后生效。该项不服从 CodexBar 通知发送判定,也不修改顶层 `notify`。「主面板任务中心」沿用相同依赖语义;关闭只隐藏活动卡片和任务中心入口,不停止 Monitor、状态点、通知或触觉反馈。授权被拒的引导文案与"打开系统设置"按钮仍内联显示在主开关行下方, 插入提示时不触发设置项纵向动画。+设置页交互: 「系统通知」主开关行保留在设置窗口内, 子选项 (五类通知子开关、任务触觉开关、Codex TUI 通知开关与两个阈值 Picker) 在主选项右侧的子面板中展开 (`NotificationOptionsPanelController`, 复用 SidePanelSupport 抽屉机制挂在设置窗口上, 内容用常驻 hosting controller + ObservableObject 驱动, 面板尺寸在 Hook 开/关两种状态下保持不变)。「任务等待通知」和「任务触觉反馈」依次排列在「任务完成通知」下方。主开关开启后仅在系统授权允许时展开, 首次授权场景会等待授权结果; 点击行内滑杆按钮可手动展开; 设置窗口 resign key/关闭、主开关关闭或授权变为被拒时自动收起。任务完成、任务等待与任务触觉子项在 Hook 未开启时显示为关闭并置灰, 不修改各自持久化偏好, Hook 重新开启后恢复用户原选择。「Codex TUI 通知」与用户级 `[tui] notifications` 联动,面板打开时刷新,写入后回读验证;已有 CLI 会话需重启后生效。该项不服从 CodexBar 通知发送判定,也不修改顶层 `notify`。「任务中心」沿用相同依赖语义;关闭只隐藏活动卡片和任务中心入口,不停止 Monitor、状态点、通知或触觉反馈。授权被拒的引导文案与"打开系统设置"按钮仍内联显示在主开关行下方, 插入提示时不触发设置项纵向动画。五类通知的触发与去重:diff --git a/Docs/UserGuide.md b/Docs/UserGuide.mdindex 71fd908..6738e19 100644--- a/Docs/UserGuide.md+++ b/Docs/UserGuide.md@@ -1,605 +1,670 @@-# CodexBar 使用指南与常见问题+# CodexBar 使用指南-这份文档面向 CodexBar 用户,介绍日常使用方法、容易错过的点击入口、各种状态的含义,以及遇到异常时的排查步骤。--如果你正在了解实现或数据格式,请阅读 [开发文档](DevelopmentGuide.md)、[Codex Hook 文档](CodexHook.md) 和 [跨设备同步文档](CrossDeviceSync.md)。+这份指南面向日常使用 CodexBar 的用户。你可以按功能查找需要开启的设置、具体操作、界面状态,以及遇到问题时的处理方法。## 目录- [1. 快速开始](#1-快速开始)-- [2. 所有入口与快捷操作](#2-所有入口与快捷操作)+- [2. 入口、快捷键与功能依赖](#2-入口快捷键与功能依赖)- [3. 看懂菜单栏图标](#3-看懂菜单栏图标)-- [4. 使用菜单面板](#4-使用菜单面板)-- [5. 设置 CodexBar](#5-设置-codexbar)-- [6. Codex Hook 与实时任务](#6-codex-hook-与实时任务)-- [7. 跨设备同步](#7-跨设备同步)-- [8. 通知与触觉反馈](#8-通知与触觉反馈)-- [9. 日志、版本与更新](#9-日志版本与更新)-- [10. 常见问题](#10-常见问题)-- [11. 隐私与数据边界](#11-隐私与数据边界)+- [4. 账号状态与数据刷新](#4-账号状态与数据刷新)+- [5. 额度、重置时间与手动重置机会](#5-额度重置时间与手动重置机会)+- [6. Token 摘要与近 30 周热力图](#6-token-摘要与近-30-周热力图)+- [7. Codex Hook、活动卡片与任务中心](#7-codex-hook活动卡片与任务中心)+- [8. 重建工作流统计](#8-重建工作流统计)+- [9. 跨设备同步](#9-跨设备同步)+- [10. 系统通知、Codex TUI 通知与触觉反馈](#10-系统通知codex-tui-通知与触觉反馈)+- [11. 其他设置与全局快捷键](#11-其他设置与全局快捷键)+- [12. 日志、版本与更新](#12-日志版本与更新)+- [13. 常见问题速查](#13-常见问题速查)+- [14. 隐私与数据范围](#14-隐私与数据范围)## 1. 快速开始### 使用要求-- macOS 15.0 或更高版本。-- 已安装 Codex CLI 或 Codex.app。-- 已在 Codex 中完成登录。--CodexBar 是菜单栏 App,不显示 Dock 图标,也没有传统的主窗口。启动后请在屏幕顶部菜单栏查找 CodexBar 图标。--### 第一次使用建议--1. 左键点击菜单栏图标,确认账号、额度和 Token 用量能够正常显示。-2. 右键点击菜单栏图标并打开「设置」。-3. 按需要开启「开机自动启动」和「自动检查更新」。-4. 如果需要工作流统计、实时任务状态或任务通知,开启「启用 Codex Hook」。-5. 如果需要在多台 Mac 之间合并 Hook 统计,再开启「跨设备同步」。-6. 如果需要提醒,开启「系统通知」,再点击通知行右侧的滑杆图标配置具体通知。--## 2. 所有入口与快捷操作--下面这些交互有一部分没有文字按钮,第一次使用时容易错过。--| 位置 | 操作 | 结果 |-| -------------------------------- | ----------------------------------- | ------------------------------------------------------ |-| 菜单栏图标 | 左键点击 | 打开或关闭主菜单面板 |-| 菜单栏图标 | 右键点击,或按住 `Control` 左键点击 | 打开设置、日志和退出菜单 |-| 任意 App 中 | 默认按 `⌘⇧W` | 打开或关闭主菜单面板 |-| 任意位置 | 按 `⌘,` | 打开 CodexBar 设置窗口 |-| 主菜单面板打开时 | 按 `⌘L` | 关闭菜单面板并打开日志窗口 |-| 账号卡片头像 | 双击 | 立即刷新账号、额度和用量 |-| 账号邮箱 | 双击 | 模糊或恢复邮箱显示 |-| 活动卡片 | 单击 | 打开或关闭并发任务中心;需要开启 Hook 且存在可展示任务 |-| `重置次数: N` | 单击 | 查看各批手动重置机会的过期时间和数量 |-| Token 热力图方块 | 鼠标悬停 | 查看当天 Token 和 Hook 工作流统计 |-| 菜单面板底部同步图标 | 鼠标悬停 | 查看同步未开启、正在同步、失败或最近同步时间 |-| 菜单面板底部更新提示 | 双击 | 立即开始安装可用更新 |-| 设置中的「系统通知」右侧滑杆图标 | 单击 | 展开具体通知和触觉选项 |-| 设置中的 Codex 安装路径 | 单击 | 复制路径,短暂显示「已复制」 |-| 日志列表中的一行 | 单击 | 展开请求、响应或错误摘要 |-| 日志展开内容 | 点击「预览」或「复制」 | 查看或复制完整内容 |--点击菜单面板和侧边详情面板之外的区域会关闭菜单面板,这是菜单栏工具的正常行为。+- macOS 15.0 或更高版本+- 已安装 Codex CLI 或 Codex App+- 已在 Codex 中完成登录++CodexBar 是纯菜单栏 App,不显示 Dock 图标,也没有传统主窗口。启动后请在屏幕顶部菜单栏寻找带对勾的人物图标。++### 第一次使用++1. 左键点击菜单栏图标,确认账号、额度和 Token 用量能够显示。+2. 右键点击菜单栏图标,选择「设置」。+3. 根据需要开启「开机自动启动」和「自动检查更新」。+4. 如果希望在菜单栏直接看到剩余额度,开启「菜单栏额度指示」并选择额度窗口。+5. 如果希望查看工作流统计、实时任务或任务提醒,开启「启用 Codex Hook」。+6. 开启 Hook 后,可继续开启「任务中心」和「跨设备同步」。+7. 如果希望接收提醒,开启「系统通知」,允许 macOS 通知权限,再打开右侧的通知选项。++如果第一步显示「未登录」或「初始化失败」,先阅读[账号状态与数据刷新](#4-账号状态与数据刷新)。++## 2. 入口、快捷键与功能依赖++### 所有常用入口++| 位置 | 操作 | 结果 |+| -------------------------------- | ----------------------------------- | ------------------------------------ |+| 菜单栏图标 | 左键点击 | 打开或关闭主菜单面板 |+| 菜单栏图标 | 右键点击,或按住 `Control` 左键点击 | 打开设置、日志和退出菜单 |+| 任意 App 中 | 按全局快捷键,默认 `⌘⇧W` | 打开或关闭主菜单面板 |+| 任意位置 | 按 `⌘,` | 打开 CodexBar 设置窗口 |+| 主菜单面板打开时 | 按 `⌘L` | 关闭菜单面板并打开日志窗口 |+| 账号卡片人物图标 | 双击 | 立即刷新账号、额度和用量 |+| 账号邮箱 | 双击 | 模糊或恢复邮箱显示 |+| 活动卡片 | 单击 | 打开或关闭任务中心 |+| `重置次数: N` | 单击 | 查看每批手动重置机会的过期时间和数量 |+| Token 热力图日期方块 | 鼠标悬停 | 查看当天 Token 和工作流统计 |+| 菜单面板底部 iCloud 图标 | 鼠标悬停 | 查看同步状态或最近同步时间 |+| 菜单面板底部更新提示 | 双击 | 开始安装可用更新 |+| 设置中的「系统通知」右侧滑杆图标 | 单击 | 打开通知和触觉选项 |+| 设置中的 Codex 安装路径 | 单击 | 复制路径,短暂显示「已复制」 |+| 日志列表中的一行 | 单击 | 展开请求结果或错误摘要 |+| 日志展开内容 | 点击「预览」或「复制」 | 查看或复制完整内容 |++点击菜单面板和侧边详情面板以外的区域会关闭菜单,这是菜单栏 App 的正常交互。++### 功能依赖一览++| 功能 | 需要开启或满足的条件 |+| ---------------------- | ---------------------------------------------------- |+| 账号、额度、Token 用量 | Codex 已安装并登录 |+| 菜单栏额度指示 | 开启「菜单栏额度指示」,且所选额度窗口有数据 |+| 工作流统计 | 开启「启用 Codex Hook」 |+| 活动卡片与任务中心 | 开启「启用 Codex Hook」和「任务中心」 |+| 任务状态点 | 开启 Hook,且当前主数据可用 |+| 跨设备同步 | 开启 Hook 和「跨设备同步」,并登录可用的 iCloud 账号 |+| 额度类通知 | 开启「系统通知」、macOS 通知权限和对应通知选项 |+| 任务类通知 | 在通知条件基础上额外开启 Hook |+| 任务触觉反馈 | 开启「系统通知」「任务触觉反馈」和 Hook |+| Codex TUI 通知 | 开启「系统通知」后,从通知选项中配置 |## 3. 看懂菜单栏图标-### 账号状态--- 正常人物图标:账号数据可用。-- 带叉图标:未登录、初始化失败,或当前快照不可信。-- 将鼠标停在图标上可以查看账号异常、实时任务和额度窗口的摘要。--### 菜单栏额度指示--设置中的「菜单栏额度指示」开启后,图标左侧会显示当前所选额度窗口的剩余比例。可以在同一设置行切换要显示的额度窗口。--颜色按剩余额度分档:--| 剩余额度 | 颜色含义 |-| ---------- | -------- |-| 80% 及以上 | 充足 |-| 60%–79% | 较充足 |-| 40%–59% | 需要留意 |-| 20%–39% | 较低 |-| 低于 20% | 紧张 |--额度窗口暂时没有可信数据时,菜单栏不会显示这条额度指示。--### 实时任务状态点--开启 Codex Hook 后,人物图标右下角可能出现状态点:--- 橙色:有任务正在等待批准。-- 蓝色:有任务正在运行。-- 绿色:任务刚刚完成,绿色状态保留约 30 秒。-- 无状态点:当前没有等待或运行任务,也没有处于绿色高亮期的完成任务。--状态点只在主面板额度快照可用时按上述任务状态绘制;活动卡片显示「暂无数据」时不显示状态点。+菜单栏图标同时表达账号、额度和实时任务三类信息。将鼠标停在图标上,可以查看文字摘要。-当多个状态同时存在时,显示优先级为:等待批准、运行中、刚完成、空闲。+### 人物图标-## 4. 使用菜单面板+| 图标 | 含义 | 建议操作 |+| ------------ | ---------------------------------- | ------------------------------------------ |+| 带对勾的人物 | Codex 账号数据可用 | 正常使用 |+| 带叉的人物 | 未登录、初始化失败或当前数据不可用 | 打开菜单查看具体状态,再按账号排障步骤处理 |-### 账号卡片+### 左侧额度竖条-账号卡片显示当前账号、订阅类型和刷新状态。+开启「菜单栏额度指示」后,人物图标左侧会显示所选额度窗口的剩余比例。设置行右侧的下拉菜单可以切换额度窗口。-- 双击头像可以立即刷新。-- 双击邮箱可以模糊邮箱,适合共享屏幕或截图时临时隐藏账号信息。-- 刷新中的小进度指示只表示正在请求本机 Codex app-server。+| 剩余额度 | 颜色 | 含义 |+| ---------- | ---- | ---------- |+| 80% 及以上 | 绿色 | 额度充足 |+| 60%–79% | 蓝色 | 额度较充足 |+| 40%–59% | 黄色 | 建议留意 |+| 20%–39% | 橙色 | 额度较低 |+| 低于 20% | 红色 | 额度紧张 |-CodexBar 默认每 60 秒自动刷新一次。菜单面板底部「数据更新时间」左侧的蓝色圆环表示距离下一次刷新还有多久。+如果开关已经开启但没有竖条,通常是所选额度窗口暂时没有可用数据。打开设置切换到另一个窗口,或双击账号卡片人物图标刷新。-### 活动卡片和任务中心+### 右下角任务状态点-活动卡片只在 Codex Hook 开启时出现。它优先显示:+任务状态点需要开启 Codex Hook。-1. 等待批准的任务。-2. 正在运行的任务。-3. 最近完成的任务。-4. 最近终止的任务。-5. 暂无活动。+| 状态点 | 含义 |+| -------- | -------------------------------- |+| 橙色 | 至少有一个任务正在等待用户批准 |+| 蓝色 | 至少有一个任务正在运行 |+| 绿色 | 有任务刚刚完成,通常保留约 30 秒 |+| 无状态点 | 当前空闲,或任务数据暂不可用 |-右侧 `+N` 表示还有其他正在运行或等待批准的任务。点击活动卡片会打开任务中心,完整列出:+多个状态同时出现时,优先显示:等待批准 → 运行中 → 刚完成 → 空闲。-- 等待确认。-- 运行中。-- 最近完成。-- 最近终止。+如果活动卡片显示「暂无数据」,状态点也不会显示。此时先处理账号或主数据加载问题。-「完成」只表示 Codex 已确认该轮结束,不代表任务结果一定成功。「终止」表示任务没有按正常完成路径结束,也不会触发绿色状态或完成通知。+## 4. 账号状态与数据刷新-最近完成和最近终止记录保留约 10 分钟。任务中心会在菜单侧面展开,右侧空间不足时自动改到左侧,顶边优先与活动卡片对齐。点击时如果卡片布局尚未稳定,任务中心会等待一次布局更新后重试;仍然无法取得有效位置时,才在主面板旁垂直居中。面板高度随列表内容变化,底部与最后一个项目保持固定留白且不会低于主面板底边;内容达到可用高度上限后改为内部滚动。+### 需要什么-### 额度和重置时间+账号卡片不需要额外开关,但需要本机已安装并登录 Codex CLI 或 Codex App。-额度区域按 Codex 返回的时间窗口展示:+### 账号卡片显示什么-- 剩余百分比。-- 分段额度条。-- 下一次重置时间。+- 当前账号邮箱或账号名称+- 当前订阅类型+- 数据刷新状态-如果某一轮刷新失败,但之前有同账号的可用数据,CodexBar 会暂时显示旧缓存。此时额度或用量区域会变淡,表示数据可能不是最新值。+双击邮箱可以临时模糊显示,适合共享屏幕或截图;再次双击即可恢复。账号发生变化后,模糊状态会自动恢复为正常显示。-如果 Codex 返回可用的手动重置机会,主额度标题右侧会出现 `重置次数: N`。点击后可以查看:+### 刷新数据-- 各过期时间下有多少次机会。-- 过期时间未知时显示「未知过期时间」。+CodexBar 默认每 60 秒刷新一次账号、额度和 Token 用量。菜单底部「数据更新时间」左侧的蓝色圆环表示距离下一次自动刷新还有多久。-CodexBar 只查询重置机会和过期时间,不会代替用户执行额度重置。+需要立即刷新时,双击账号卡片左侧的人物图标。刷新期间人物图标旁会出现小型进度指示,完成后倒计时重新开始。-### Token 摘要和近 30 周热力图+### 状态与处理方法-用量区域包括:+| 状态 | 含义 | 处理方法 |+| ---------------------- | ---------------------------------------- | ---------------------------------------------------------------- |+| 「未登录」橙色提示 | CodexBar 没有读取到已登录账号 | 在 Codex CLI 或 Codex App 中完成登录,再双击人物图标刷新 |+| 「初始化失败」红色提示 | 没有成功启动或连接本机 Codex | 检查 Codex 是否仍安装,打开设置确认 Codex 版本与路径,再查看日志 |+| 「暂无数据」 | 账号已识别,但当前没有可展示的额度或用量 | 等待自动刷新,或手动刷新;持续出现时查看日志 |+| 额度或热力图变淡 | 本轮刷新失败,当前显示的是较早缓存 | 网络或本机 Codex 恢复后再次刷新 |+| 长时间显示刷新中 | 本次读取可能超时或连接异常 | 等待状态结束后重试,并在日志中查看最新错误 |-- 全时累计 Token。-- 单日峰值。-- 当前连续使用天数。-- 最长连续使用天数。-- 最长任务耗时。-- 近 30 周每日 Token 热力图。+如果安装了多个 Codex,设置中的「Codex 版本」会标记「当前使用」的来源。确认它是否是你实际登录和使用的版本。-将鼠标移动到热力图方块上,会在菜单侧面显示当天详情。蓝色越深,表示当天 Token 用量相对越高。+## 5. 额度、重置时间与手动重置机会-Hook 关闭时,详情主要显示日期、Token 和用量强度。Hook 开启后,还会显示最热模型、会话总数、对话轮次、子智能体、工具调用、权限请求和上下文压缩次数。+### 需要什么-这些工作流指标表示:+主面板额度不需要额外开关,只需要账号已登录并返回额度数据。「菜单栏额度指示」只控制菜单栏竖条,不会隐藏主面板额度。-| 指标 | 通俗解释 |-| ---------- | --------------------------------------------------------- |-| 最热模型 | 当天 Hook 事件中出现次数最多的模型,不代表消耗 Token 最多 |-| 会话总数 | 当天识别到的不同 Codex 会话数量 |-| 对话轮次 | 当天识别到的不同任务轮次数量 |-| 子智能体 | 子智能体启动或结束事件归一后的数量 |-| 调用工具 | 工具调用开始或结束事件归一后的数量 |-| 权限请求 | Codex 请求用户批准操作的次数 |-| 上下文压缩 | 上下文压缩开始或结束事件归一后的数量 |+### 查看额度-Hook 统计只从开启后开始记录,不能补出开启前的工作流历史。Token 数据和 Hook 统计来源不同,因此某一天可能有 Token,但没有 Hook 明细;也可能当天 Hook 已有事件,但 Token 桶尚未返回。+每个额度窗口会显示:-### 菜单底部状态+- 窗口名称+- 分段额度条+- 剩余百分比+- 下一次重置时间-菜单底部包含三类信息:+额度条和百分比使用与菜单栏竖条相同的绿色、蓝色、黄色、橙色和红色分档。某个窗口显示 `--`,表示当前没有该项数据或重置时间。-- 数据更新时间和 60 秒刷新倒计时。-- 跨设备同步状态图标;悬停可查看详情。-- 可用更新提示;双击提示可以开始更新。+### 在菜单栏持续显示额度-## 5. 设置 CodexBar+1. 打开设置。+2. 开启「菜单栏额度指示」。+3. 在右侧下拉菜单选择希望关注的额度窗口。-通过右键菜单中的「设置」或 `⌘,` 打开设置窗口。+关闭后,CodexBar 会记住最后选择的窗口,下次开启时自动恢复。-| 设置项 | 作用 | 注意事项 |-| --------------- | ----------------------------------------------- | -------------------------------------- |-| 开机自动启动 | 登录 macOS 后自动启动 CodexBar | 移动 App 后建议重新关闭再开启一次 |-| 自动检查更新 | 允许 Sparkle 自动检查新版本 | 关闭后仍可手动检查 |-| 菜单栏额度指示 | 在图标左侧显示所选额度窗口 | 没有可用数据时自动隐藏 |-| 启用 Codex Hook | 开启工作流统计、活动卡片和任务提醒 | 会修改当前用户的 `~/.codex/hooks.json` |-| 跨设备同步 | 通过 iCloud private database 合并 Hook 日聚合 | 需要 Hook 已开启且 iCloud 可用 |-| 重建数据 | 选择日期范围并批量重新生成有原始事件的每日聚合 | 会替换当前设备对应日期的云端聚合 |-| 系统通知 | 控制 CodexBar 通知和任务触觉反馈总开关 | 首次开启需要系统授权 |-| 使用快捷键 | 设置全局打开/关闭菜单面板的快捷键 | 至少需要两个修饰键 |-| Codex 版本 | 查看全局 CLI、Codex.app 内置 CLI 和当前使用来源 | 点击路径可以复制 |-| CodexBar 版本 | 查看更新状态和当前版本 | 有更新时可点击右侧更新按钮 |+### 查看手动重置机会-### 修改全局快捷键+如果账号存在可用的手动重置机会,主额度标题右侧会显示绿色的 `重置次数: N`。-默认快捷键是 `⌘⇧W`。+点击后,侧边面板会按过期时间从近到远列出每批机会:-如果已经设置快捷键,需要先点击叉号清除,再点击「未设置」开始录制新的组合。快捷键至少包含两个修饰键,且不能使用 `⌘Space`、`⌘Tab` 等系统保留组合。+| 数量颜色 | 含义 |+| -------- | ------------------ |+| 绿色 | 距离过期超过 7 天 |+| 橙色 | 将在 7 天内过期 |+| 红色 | 将在 24 小时内过期 |-- 按 `Esc` 取消本次录制。-- 点击回转箭头恢复默认快捷键。-- 如果注册失败,设置行下方会显示原因,原快捷键会被恢复。+`重置次数: N` 用于查看机会和过期时间,不会直接执行额度重置。-### 配置通知子选项+### 常见问题-开启「系统通知」后,点击该行右侧的滑杆图标,可以分别设置额度预警、额度重置、任务完成、任务等待、任务触觉、重置次数临期提醒和 Codex TUI 通知。具体说明见[通知与触觉反馈](#8-通知与触觉反馈)。--## 6. Codex Hook 与实时任务--### Hook 能带来什么--开启 Hook 后,CodexBar 可以:--- 统计会话、对话轮次、工具调用、权限请求、上下文压缩和子智能体事件。-- 在活动卡片和任务中心显示正在运行、等待批准、最近完成和最近终止任务。-- 发送任务等待和长任务完成通知。-- 在支持的设备上请求任务触觉反馈。--### Hook 会读取什么--CodexBar Hook 记录事件类型、时间、模型、权限模式、会话和轮次标识、工具名以及工作目录。UI 只展示工作目录最后一级名称,不展示完整路径、会话 ID 或轮次 ID。--为补齐缺失的开始、完成或中断信号,主 App 还会只读当前活跃任务对应的本机 Codex session rollout。它只解析生命周期字段,不提取提示词、回复、推理或工具内容。--### Hook 配置提示是什么意思--| 提示 | 含义和处理建议 |-| ------------------------- | ------------------------------------------------------------------------ |-| `Codex 配置已禁用 Hook` | Codex 全局配置关闭了 Hook;先在 Codex 配置中启用 Hook |-| `hooks.json 文件格式错误` | `~/.codex/hooks.json` 不是有效格式;修复文件后重试 |-| `CodexBar Hook 已被禁用` | Hook 存在,但 Codex 报告它未启用 |-| `CodexBar Hook 未被信任` | Codex 没有信任当前命令;重新开关 Hook,仍失败时查看日志 |-| `CodexBar Hook 已不完整` | 部分需要的事件没有安装;重新关闭并开启 Hook |-| `CodexBar Hook 意外来源` | 生效的 Hook 不是来自预期的全局配置文件 |-| `无法验证 Codex Hook` | 配置可能已经写入,但 app-server 验证失败;查看日志中的 `hooks/list` 请求 |-| `设置 Codex Hook 失败` | 开启前检查或写入失败;根据下方错误及日志排查 |+#### 为什么看不到 `重置次数: N`?-CodexBar 只增删属于当前 CodexBar 可执行文件的 Hook,不会删除其他 App 或用户自己的 Hook。+只有账号当前存在大于零的可用机会时才显示。手动刷新后仍没有,表示当前没有可展示的机会。-### 批量重建日期范围内的工作流数据+#### 为什么显示「未知过期时间」?-如果手动修改过 `events/YYYY-MM-DD.jsonl`,或确认一段日期范围内的本机聚合需要重新计算,可以在设置页「重建数据」第一次点击开始日期,再翻月并点击结束日期;如果只处理一天,则连续点击同一天两次。日期固定使用 `yyyy-MM-dd` 格式,最近 210 天保留窗口内的日期均可选择,未来日期和更早日期不可选。本机原始事件非空的日期会显示圆点;没有圆点的日期可以参与范围选择和高亮,但不会进入实际重建。日历固定显示六周,月首和月末相邻月份的日期会以较淡颜色补齐。+CodexBar 已读取到可用次数,但暂时没有取得有效过期时间。次数仍会显示,可以稍后再次刷新。-每次重新打开设置窗口时,日期范围和上次操作消息都会恢复为未选择状态。重建行下方固定显示一行状态:尚未选择时显示「未选择重建日期范围」,只选择开始日期后显示「选择结束日期」,范围完成且其中存在可重建数据时显示完整日历范围包含的「已选择 X 天」,范围内没有非空原始事件时显示「没有可重建的本地数据」。+#### 为什么额度突然变淡?-确认弹窗和「重建」按钮只按范围内实际有非空本机原始事件文件的日期处理。CodexBar 会逐日从对应文件第一行重新统计,分别生成新的本地 generation,但不会修改原始事件。例如选择 1–15 号而只有 1、2、3、4、9、10 号有数据时,只批量重建这 6 天。重建与自动维护、CloudKit 同步由同一调度器串行执行;重建期间到达的自动刷新请求会合并排队,完成后继续处理。日期较多时本机重建耗时会随实际数据量增加;CloudKit 每批最多处理 25 天、每轮最多使用 20 秒,未完成的替换会由后续同步继续。若跨设备同步正在生效,当前设备这 6 天的旧云端 generation 会被删除,再以对应的新 generation 上传重建结果;其他设备、范围外日期和范围内无数据日期不受影响。同步暂不可用时先显示本机重建结果,云端替换会在后续同步恢复后自动重试。无效 JSONL 行会被跳过并在完成提示中汇总数量。+当前显示的是较早缓存,不一定是最新结果。双击人物图标刷新;如果持续变淡,请查看日志中的额度读取错误。-### 关闭 Hook 或移动 App+#### 为什么菜单栏竖条和主面板不一致?-关闭 Hook 会停止记录新事件、隐藏 Hook 统计和活动卡片,并清空当前进程中的实时任务状态,但不会删除已经保存在本机的历史文件。以后重新开启 Hook 时,已有聚合仍可继续使用。+先确认设置中选择的是哪个额度窗口。主面板可能同时展示多个窗口,而菜单栏只显示选中的一个。-Hook 命令包含 CodexBar 当前可执行文件的完整路径。如果准备把 `CodexBar.app` 移到其他目录,建议先在旧位置关闭 Hook,移动后再重新开启。已经移动且旧 Hook 无法执行时,需要检查 `~/.codex/hooks.json` 中是否仍有指向旧路径的 CodexBar 命令。+## 6. Token 摘要与近 30 周热力图-不要同时保留指向不同 CodexBar 安装位置的 Hook。Codex 会分别调用每条生效命令,同一个事件可能被追加多次,导致统计重复;其他位置的 CodexBar 还可能改写共享的维护状态,使当天的 generation 再次变化。移动或替换 App 后应先移除原路径 Hook,再只启用最终安装位置的版本。+### 需要什么-### Codex 被关闭后为什么任务仍显示运行中+- Token 摘要和热力图不需要额外开关。+- 热力图中的工作流明细需要开启「启用 Codex Hook」。-如果 Codex 正常写入 `Stop`、`task_complete` 或 `turn_aborted`,CodexBar 可以识别完成或终止。+### 摘要指标-如果 Codex 被强制关闭、进程崩溃、终端直接退出或电脑断电,而且没有留下终态事件,CodexBar 无法立即确定任务是否真的结束。此时:+用量区域会根据可用数据展示:-- 同一 session 后续出现新 Prompt,旧任务会立即退出运行列表,并等待约 5 秒确认真实终态;仍无终态时记为最近终止。-- 始终没有任何后续事件,任务最多可能保留 24 小时。-- 重新启动 CodexBar 或重新开启 Hook 后,最近 24 小时事件可能再次恢复这条无终态任务。+| 指标 | 含义 |+| -------------- | --------------------------------- |+| 全时累计 Token | 当前可读取范围内的累计 Token 用量 |+| 单日峰值 | 单日 Token 用量最高值 |+| 当前连胜 | 最近连续有使用记录的天数 |+| 最长连胜 | 历史最长连续使用天数 |+| 最长任务 | 可识别到的最长任务耗时 |-当前版本没有单任务「手动移除」功能。单纯长时间没有事件也不能安全地自动判定终止,因为任务可能正在长时间调用工具、等待输入或经历系统休眠。+### 使用热力图-## 7. 跨设备同步+热力图以周为列、日为行展示近 30 周。蓝色越深,表示当天 Token 用量相对于当前 30 周峰值越高。-### 开启条件+把鼠标移到任意日期方块上,侧边详情会自动出现。详情跟随鼠标悬停,不需要点击;如果消失,将鼠标重新移回日期即可。-跨设备同步同时需要:+### Hook 开启后的每日统计-- Codex Hook 已开启。-- 设置中的「跨设备同步」已开启。-- 当前 Mac 已登录可用的 iCloud 账号。+| 指标 | 含义 |+| ---------- | ------------------------------------- |+| 用量强度 | 当天 Token 相对于当前热力图峰值的强度 |+| 最热模型 | 当天出现次数最多的模型 |+| 会话总数 | 当天识别到的 Codex 会话数量 |+| 对话轮次 | 当天识别到的任务轮次数量 |+| 子智能体 | 当天记录到的子 Agent 活动数量 |+| 调用工具 | 当天记录到的工具调用数量 |+| 权限请求 | 当天请求用户批准操作的次数 |+| 上下文压缩 | 当天发生的上下文压缩次数 |-如果开关呈灰色或显示「同步不可用」,请先确认 Hook 状态和 macOS 的 iCloud 登录状态。+### 常见问题-### 同步什么+#### 为什么某天有 Token,却没有工作流明细?-同步使用当前 iCloud 账号的 CloudKit private database,只上传按设备、按天生成的脱敏聚合数据,用于合并热力图中的工作流统计。+Token 用量和 Hook 工作流统计来自不同功能。请确认当天使用 Codex 时 Hook 已开启,并检查设置中的 Hook 是否有错误提示。-同一台 Mac 同一天、同一 generation 的本地聚合和 iCloud 副本不会重复相加,通常显示事件数更完整的一份。如果当天事件文件被完整删除或清空,CodexBar 能确认后续事件属于新的独立 generation,因此新统计会与已有云端贡献相加;如果文件被替换成一份非空且来源不明确的数据,CodexBar 会继续使用已有云端记录,不自动覆盖或叠加,避免重复统计。+#### 为什么今天显示 `--`?-设置页的显式重建是上述自动保护的例外:只有用户确认后,CodexBar 才会把所选本机原始事件视为权威来源,删除当前设备同日旧 generation,并上传与本机一致的新 generation。+今天的工作流活动可能已经出现,但 Token 用量尚未更新。等待下一次自动刷新即可。-直接删除某个历史日期的本机 events 文件不会同步删除 daily 聚合或云端记录,因此页面通常仍会显示原来的统计。如果连对应 daily 行也删除,开启同步时页面会回退使用已缓存的云端贡献;关闭同步或云端没有副本时,该日期才会消失。+#### 为什么工作流次数和 Token 数对不上?-不会上传:+工作流次数表示会话、轮次和事件数量,Token 表示用量,两者不是相同口径,不需要逐项对应。-- Codex 账号和额度。-- Token 用量。-- 原始 Hook 事件。-- 会话 ID 和轮次 ID。-- 实时任务状态。-- 请求日志和 Codex 认证文件。+#### 为什么悬停后看不到侧边详情?-### 看懂同步状态+将鼠标准确移动到有颜色的日期格上。如果菜单靠近屏幕边缘,详情会自动改到另一侧显示。-菜单面板底部的 iCloud 图标表示同步状态,悬停可以查看文字:+## 7. Codex Hook、活动卡片与任务中心-- 带斜杠:同步未开启或未实际生效。-- 旋转箭头:正在同步。-- 感叹号:最近一次同步失败。-- 普通 iCloud:同步已开启;悬停显示最近同步时间或「暂无同步记录」。+### Hook 提供什么-同步在 Hook 统计维护后触发。网络或服务暂时失败时不需要反复开关,后续刷新会继续重试尚未成功的日期。+开启 Codex Hook 后,CodexBar 可以:-## 8. 通知与触觉反馈+- 在热力图中显示每日工作流统计+- 在活动卡片中显示当前任务+- 在任务中心查看并发任务+- 在菜单栏人物图标上显示实时状态点+- 发送任务等待和任务完成通知+- 提供任务触觉反馈+- 使用跨设备同步合并每日工作流统计### 开启步骤-1. 打开 CodexBar 设置。-2. 开启「系统通知」。-3. 在 macOS 授权提示中允许通知。-4. 点击通知行右侧的滑杆图标,配置具体提醒。--如果系统权限被拒绝,设置页会显示提示和「打开系统设置」按钮。--### 可用通知+1. 打开设置。+2. 开启「启用 Codex Hook」。+3. 等待开关更新完成,确认下方没有错误提示。+4. 开启「任务中心」,让活动卡片显示在主面板中。-| 选项 | 触发条件 | 配置或频率 |-| ---------------- | -------------------------------------------------- | -------------------------------- |-| 额度预警通知 | 可信额度从阈值上方跌到阈值或以下 | 5%、10%、25%,默认 10% |-| 额度重置通知 | 已发生消耗的额度窗口恢复到 100% | 提供重置时间时,同周期提醒一次 |-| 任务完成通知 | Hook 任务确认完成且耗时达到阈值 | 30 秒、1、2、5 分钟,默认 1 分钟 |-| 任务等待通知 | 用户审批模式下,任务在一批事件处理结束后仍等待批准 | 无 |-| 任务触觉反馈 | 任务进入等待批准或确认结束 | 需要 Hook;服从通知总开关 |-| 重置次数临期通知 | 手动重置机会将在 7 天内过期 | 最多每 24 小时提醒一次 |-| Codex TUI 通知 | Codex CLI TUI 发送终端通知 | 与 `[tui] notifications` 联动 |+「任务中心」依赖 Hook。Hook 关闭时,该开关会显示为关闭并置灰;重新开启 Hook 后会恢复此前选择。-任务完成、任务等待和任务触觉选项需要 Hook。Hook 关闭时,这些选项会显示为关闭并置灰,但不会丢失用户原来的偏好。+### 活动卡片图标-「Codex TUI 通知」读取用户级 `~/.codex/config.toml`:`[tui] notifications = false` 时显示为关闭。切换开关会通过本机 Codex app-server 写入 `tui.notifications = false/true`,不会修改顶层 `notify` 外部回调。已经运行的 Codex CLI 需要重新启动会话后采用新设置;读取或写入失败时,选项旁显示警告图标,悬停可查看原因。+| 图标与颜色 | 状态 | 含义 |+| ---------- | -------- | -------------------------- |+| 橙色举手 | 等待批准 | Codex 正在等待用户确认操作 |+| 蓝色闪电 | 运行中 | Codex 正在执行任务 |+| 绿色对勾 | 最近完成 | 任务已经确认结束 |+| 灰色叉号 | 最近终止 | 任务没有按正常完成状态结束 |+| 灰色月亮 | 暂无活动 | 当前没有可展示任务 |-当前 App 进程发出的等待批准通知会跟随 Monitor 中的任务状态;任务恢复运行、完成、终止或以其他方式离开等待状态后,通知会自动从通知中心移除,不影响其他仍在等待的并发任务。+活动卡片会优先显示等待批准,其次是运行中、最近完成、最近终止和空闲。标题可能包含模型、推理强度和项目名称,第二行可能显示工具、阶段、耗时和活跃子 Agent 数量。-触觉反馈是否真的发生、震感强弱和形式由 Mac、触控板、辅助功能及系统偏好决定。CodexBar 请求了触觉,不代表所有设备都能产生明显反馈。+右侧 `+N` 表示还有其他正在运行或等待批准的任务。-点击 CodexBar 发出的系统通知会尝试打开主菜单面板,方便继续查看当前状态。+### 使用任务中心-## 9. 日志、版本与更新+点击活动卡片即可打开任务中心。任务按以下分组展示:-### 打开日志+- 等待确认+- 运行中+- 最近完成+- 最近终止-- 右键菜单栏图标,选择「日志」。-- 主菜单面板打开时按 `⌘L`。+最近完成和最近终止通常保留约 10 分钟。任务中心优先显示在主面板右侧,空间不足时会自动切换到左侧;任务较多时可以在面板内滚动。-日志记录 CodexBar 与本机 app-server 的请求状态,适合排查「未登录」「初始化失败」、刷新超时、Hook 验证和接口兼容问题。+「完成」表示该轮任务已结束,不评价结果是否符合预期;「终止」表示没有收到正常完成状态,因此不会显示绿色菜单栏状态,也不会触发任务完成通知。-使用方法:+### Hook 错误提示-- 点击一行展开。-- 点击「预览」打开完整内容;JSON 会格式化并高亮。-- 点击「复制」复制完整请求、响应或错误。-- 点击顶部「清空」删除当前进程内的日志列表。+| 提示 | 含义 | 处理方法 |+| ------------------------- | ------------------------------- | ---------------------------------------------- |+| `Codex 配置已禁用 Hook` | 当前 Codex 不允许 Hook 工作 | 检查 Codex 的 Hook 设置,更新 Codex 后重新开启 |+| `hooks.json 文件格式错误` | Codex 的 Hook 配置无法正常读取 | 修复 Hook 配置后回到 CodexBar 重新开启 |+| `CodexBar Hook 已被禁用` | Hook 已存在但当前未生效 | 关闭再开启 Hook;仍失败时查看日志 |+| `CodexBar Hook 未被信任` | Codex 尚未信任当前 CodexBar | 关闭再开启 Hook,并确认使用的是最终安装位置 |+| `CodexBar Hook 已不完整` | 部分所需事件没有正确启用 | 关闭再开启 Hook,让 CodexBar 重新配置 |+| `CodexBar Hook 意外来源` | 当前生效的 Hook 不是预期配置 | 检查是否装有多个 CodexBar,保留最终使用的版本 |+| `无法验证 Codex Hook` | Hook 可能已设置,但验证没有完成 | 查看日志,确认 Codex 可正常使用后重试 |+| `设置 Codex Hook 失败` | 开启、关闭或保存设置失败 | 根据提示检查权限、Codex 状态和 App 安装位置 |-提交问题前建议先查看日志,但分享日志前仍应自行检查内容是否适合公开。+### 常见问题-### Codex 版本+#### 为什么 Hook 已开启,活动卡片仍显示「暂无 Codex 活动」?-设置中的「Codex 版本」会同时展示:+这表示主数据正常,但当前没有运行、等待、最近完成或最近终止的任务。启动一个新的 Codex 任务后再观察。-- 全局安装的 Codex CLI。-- Codex.app 内置的 CLI。-- 当前 app-server 实际使用的来源。-- 磁盘安装版本与当前运行版本是否一致。--点击安装路径可以复制,便于确认 CodexBar 实际连接了哪个 Codex。--### 更新 CodexBar+#### 为什么活动卡片显示「暂无数据」?-- 开启「自动检查更新」后,Sparkle 会定期检查新版本。-- 可以随时点击设置底部的「检查更新」。-- 有可用更新时,设置中的版本行会出现更新按钮。-- 菜单面板底部出现更新提示时,可以双击提示开始更新。+主面板账号或用量数据还没有准备好。先解决「未登录」「初始化失败」或「暂无数据」,再检查任务状态。-## 10. 常见问题+#### 为什么有任务在运行,但 CodexBar 没有显示?-### A. 启动、账号与数据--#### 为什么启动后没有 Dock 图标或主窗口?--这是正常设计。CodexBar 是纯菜单栏 App,请从屏幕顶部菜单栏打开。--#### 为什么菜单栏图标显示叉号?+依次检查:-通常表示 Codex 未登录、CodexBar 初始化 app-server 失败,或当前数据不可信。先打开 Codex CLI 或 Codex.app 确认已经登录,然后双击 CodexBar 账号头像刷新;仍失败时查看日志。+1. 「启用 Codex Hook」是否开启且没有错误。+2. 「任务中心」是否开启。+3. 该任务是否在开启 Hook 后启动。+4. 当前使用的 Codex 是否为设置中标记「当前使用」的版本。+5. 日志中是否有 Hook 验证或读取错误。-#### 「未登录」应该怎么处理?+#### 为什么任务显示运行中但没有精确耗时?-在 Codex CLI 或 Codex.app 中完成登录,再回到 CodexBar 双击头像刷新。CodexBar 不提供独立登录流程。+CodexBar 没有取得可信的任务开始时间时,只显示「正在运行」,不会显示可能不准确的时长。-#### 「初始化失败」应该怎么处理?+#### 为什么 Codex 已关闭,任务仍显示运行中?-依次检查:+强制关闭、崩溃、终端直接退出或电脑断电时,任务可能没有留下结束状态。后续新任务通常会使旧任务转为最近终止;如果一直没有新活动,旧状态最多可能保留约 24 小时。-1. Codex CLI 或 Codex.app 是否仍安装在磁盘上。-2. 设置中的「Codex 版本」能否找到安装路径。-3. 点击路径确认当前使用来源是否符合预期。-4. 打开日志查看是找不到可执行文件、超时、断连还是接口不兼容。-5. 更新 Codex CLI、Codex.app 和 CodexBar 后重试。+#### 能否手动删除一条卡住的任务?-#### 为什么只显示「暂无数据」?+当前没有单任务删除按钮。等待后续任务更新状态,或等待旧活动自动过期。-账号可能已经识别,但本轮没有返回可展示的额度或用量。等待下一次自动刷新,或双击头像手动刷新;日志中会保留更具体的请求结果。+#### 移动 CodexBar 后 Hook 不工作怎么办?-#### 为什么额度或热力图突然变淡?+Hook 与当前 App 位置相关。建议先在旧位置关闭 Hook,把 App 移到最终位置,再重新开启。不要同时运行多个不同位置的 CodexBar,否则可能重复记录同一活动。-变淡表示本轮刷新失败,CodexBar 正在显示同账号的旧缓存。缓存仍可参考,但可能不是最新值。+#### 关闭 Hook 会删除历史统计吗?-#### 数据多久刷新一次?+不会。关闭后会停止记录新活动,并隐藏活动卡片和 Hook 统计;重新开启后,仍可继续使用保留的历史数据。-账号、额度和 Token 用量默认每 60 秒刷新一次。双击头像可以立即刷新,并重新开始 60 秒倒计时。+## 8. 重建工作流统计-### B. 点击入口和菜单行为+### 什么时候使用-#### 哪些地方可以点击或悬停?+当某段日期的工作流统计缺失、重复或与本机记录不一致时,可以使用设置中的「重建数据」。日常使用不需要定期重建。-最容易错过的入口是:活动卡片、`重置次数: N`、热力图方块、通知行右侧滑杆图标、Codex 安装路径,以及日志行。完整列表见[所有入口与快捷操作](#2-所有入口与快捷操作)。+### 需要什么-#### 为什么点击活动卡片没有反应?+- 所选日期在本机仍有 Hook 原始记录。+- 当前可选择最近 210 天内的日期。+- 是否正在开启 Hook,不影响对已有本机记录执行重建。-任务中心只有在以下条件同时满足时才能打开:+### 操作步骤-- Hook 已开启。-- 账号和主数据快照已经加载。-- 当前存在运行、等待、最近完成或最近终止任务。+1. 打开设置,找到「重建数据」。+2. 点击「选择日期范围」。+3. 第一次点击选择开始日期,第二次点击选择结束日期。+4. 只重建一天时,连续点击同一天两次。+5. 检查设置行下方显示的选择结果。+6. 点击「重建」,在确认窗口中再次确认。-显示「暂无数据」或「暂无 Codex 活动」时不会打开空任务中心。+日历中带圆点的日期表示本机存在可用于重建的数据。范围可以包含没有圆点的日期,但实际只处理有本机数据的日期。-#### 为什么热力图详情不能点击?+### 状态提示-热力图详情是跟随鼠标悬停的只读侧边面板,不接收点击。把鼠标移回目标日期即可重新显示。+| 提示 | 含义 |+| ------------------------------ | ---------------------------------------- |+| 「未选择重建日期范围」 | 尚未开始选择 |+| 「选择结束日期」 | 已选择开始日期,等待选择结束日期 |+| 「已选择 X 天」 | 日期范围已完成,范围中有可重建数据 |+| 「没有可重建的本地数据」 | 所选范围没有可用的本机 Hook 记录 |+| 「共处理 X 天,包含 X 条数据」 | 本机重建完成 |+| 「跳过 X 条无效数据」 | 有少量记录无法读取,其余内容已完成重建 |+| 「云端替换将在同步可用后继续」 | 本机已完成,跨设备数据会在同步恢复后更新 |+| 「重建失败」 | 本次没有完成,请根据后续错误信息处理 |-#### 为什么点击菜单外部后面板关闭了?+如果跨设备同步已开启,重建结果会更新当前设备在所选日期的同步数据,不影响其他设备或范围外日期。-这是菜单栏工具的预期行为。任务中心和重置次数面板属于菜单面板的侧边区域,点击它们内部不会关闭主菜单。+## 9. 跨设备同步-#### 怎么隐藏截图里的邮箱?+### 同步内容-双击账号卡片中的邮箱即可模糊,再双击一次恢复。账号变化后模糊状态会自动重置。+跨设备同步用于在多台 Mac 上合并 Hook 的每日工作流统计,例如会话、轮次、模型和工具使用次数。Token 用量与实时任务不会跨设备同步。-### C. 额度、重置次数和热力图+### 开启条件-#### 为什么菜单栏没有额度竖条?+- 「启用 Codex Hook」已开启+- 「跨设备同步」已开启+- 当前 Mac 已登录可用的 iCloud 账号+- 多台 Mac 使用同一个 iCloud 账号-检查设置中的「菜单栏额度指示」是否开启,以及所选窗口是否有可信数据。窗口没有返回数据时,指示会自动隐藏。+### 开启步骤-#### 为什么看不到 `重置次数: N`?+1. 先开启「启用 Codex Hook」。+2. 确认 macOS 已登录 iCloud。+3. 开启「跨设备同步」。+4. 等待设置中出现「最近同步」时间,或在菜单底部查看 iCloud 图标。-只有 Codex 返回大于零的可用手动重置机会时才显示。CodexBar 不会自行预测或创建重置机会。+首次开启后,历史统计需要一些时间完成合并。保持 CodexBar 运行即可,无需反复开关。-#### 为什么重置次数详情显示「未知过期时间」?+### 同步图标-CodexBar 已知道可用次数,但读取过期时间的只读请求失败或没有返回有效时间。次数本身仍可能有效。+| 图标 | 含义 | 建议操作 |+| ------------------- | ------------------------ | ---------------------------------------------------- |+| 普通 iCloud | 同步已开启 | 悬停查看最近同步时间;显示「暂无同步记录」时继续等待 |+| 带斜杠的 iCloud | 同步未开启或没有实际生效 | 检查 Hook、同步开关和 iCloud 登录状态 |+| 带旋转箭头的 iCloud | 正在同步 | 等待完成 |+| 带感叹号的 iCloud | 最近一次同步失败 | 悬停查看原因,按网络、账号或服务状态处理 |-#### 为什么热力图中的今天显示 `--`?+### 常见问题-Hook 已记录今天的工作流事件,但 Token 用量接口还没有返回今天的 bucket 时,会显示 `--`。这不代表 Hook 数据丢失。+#### 为什么同步开关是灰色的?-#### 为什么 Hook 统计和 Token 数对不上?+先开启 Hook,并确认当前 Mac 已登录 iCloud。Hook 正在更新或 iCloud 状态尚未确认时,也可能暂时不可操作。-两者来自不同数据源:Token 来自本机 app-server 用量接口,工作流统计来自 Codex Hook。它们的更新时间、保留范围和统计口径不同,不应逐项一一对应。+#### 为什么显示「同步不可用」?-### D. Hook 与实时任务+常见原因包括 iCloud 未登录、账号受限、网络不可用或服务暂时不可用。先打开 macOS 系统设置确认 iCloud,再稍后返回 CodexBar。-#### 为什么开启 Hook 后看不到以前的统计?+#### 为什么另一台 Mac 没有马上出现数据?-Hook 只能从开启后开始记录事件,无法还原此前没有写入的工作流历史。+确认两台 Mac 使用同一 iCloud 账号,并且都开启 Hook 和跨设备同步。首次合并或历史数据较多时需要等待后续同步完成。-#### 关闭 Hook 会删除以前的统计吗?+#### 同步失败后需要重新开关吗?-不会。关闭 Hook 只停止新事件记录、同步调度和实时任务监测,本机历史文件仍然保留。重新开启后可以继续显示已有统计。+通常不需要。网络或服务恢复后,CodexBar 会在后续刷新中继续尝试。长期失败时再检查 iCloud 登录和系统网络。-#### 移动 CodexBar.app 后 Hook 不工作了怎么办?+#### 为什么两台 Mac 的 Token 热力图不同?-Hook 保存的是 App 可执行文件的完整路径。将 App 移回原位置后先关闭 Hook,再把 App 移到最终位置并重新开启;或者检查 `~/.codex/hooks.json`,移除指向旧 CodexBar 路径的命令后重新开启。+跨设备同步只合并 Hook 工作流统计,不同步 Token 用量,因此每台 Mac 的 Token 数据仍来自各自本机 Codex。-#### 为什么有任务在 Codex 中运行,CodexBar 却没有显示?+## 10. 系统通知、Codex TUI 通知与触觉反馈-可能原因包括:Hook 未开启或不完整、任务开始事件没有送达、Hook 配置未被信任、主菜单数据尚未加载,或正在使用的 Codex 版本不支持所需事件。先查看 Hook 行提示,再检查日志。+### 开启步骤-#### 为什么任务显示「正在运行」但没有精确耗时?+1. 打开设置。+2. 开启「系统通知」。+3. 在 macOS 弹窗中允许 CodexBar 发送通知。+4. 点击「系统通知」右侧的滑杆图标。+5. 分别开启需要的通知类型并选择阈值。-任务可能是从工具或权限事件恢复出来的,缺少可信的 Prompt 起点;匿名任务也不会猜测精确耗时。CodexBar 会保留运行状态,但显示「正在运行」而不是不可靠的时长。+如果通知权限被拒绝,设置中会显示提示和「打开系统设置」按钮。允许通知后,返回 CodexBar 即可继续配置。-#### 为什么 Codex 已经关闭,任务仍显示运行中?+### 通知选项-强制关闭或崩溃可能来不及写入结束事件。没有终态时 CodexBar 无法立即判断,任务最多可能保留 24 小时。详见[Codex 被关闭后为什么任务仍显示运行中](#codex-被关闭后为什么任务仍显示运行中)。+| 选项 | 触发条件 | 依赖与设置 |+| ---------------- | ----------------------------- | ----------------------------------- |+| 额度预警通知 | 剩余额度下降到所选阈值 | 可选 5%、10%、25%,默认 10% |+| 额度重置通知 | 已使用过的额度恢复到 100% | 需要可用额度数据 |+| 任务完成通知 | 任务确认完成且耗时达到阈值 | 需要 Hook;可选 30 秒、1、2、5 分钟 |+| 任务等待通知 | 任务正在等待用户批准 | 需要 Hook |+| 任务触觉反馈 | 任务进入等待批准或确认结束 | 需要 Hook 和支持的输入设备 |+| 重置次数临期通知 | 手动重置机会将在 7 天内过期 | 需要读取到机会及过期时间 |+| Codex TUI 通知 | 控制 Codex CLI 自身的终端通知 | 修改后重新启动正在运行的 Codex 会话 |-#### 能否手动清除一条卡住的运行任务?+任务完成、任务等待和任务触觉选项依赖 Hook。Hook 关闭时,它们会置灰,但会保留此前选择。-当前版本不能。重新启动或重新开启 Hook 也可能从最近事件中恢复它。同一 session 出现新 Prompt 后,旧任务通常会在约 5 秒内归入最近终止;否则等待 24 小时活动过期。+### 图标与状态-#### 为什么「最近终止」没有发送完成通知?+| 图标或状态 | 含义 |+| ---------------------------- | ------------------------------ |+| 「系统通知」右侧滑杆 | 打开通知子选项 |+| Codex TUI 通知旁的小进度圈 | 正在读取或保存设置 |+| Codex TUI 通知旁的橙色感叹号 | 读取或保存失败;悬停可查看原因 |+| 「打开系统设置」按钮 | macOS 尚未授权 CodexBar 通知 |-终止不等于完成。终止记录只用于说明任务不再处于正常运行路径,不触发绿色状态、完成通知或完成触觉反馈。+点击 CodexBar 发出的系统通知,会尝试打开主菜单面板,方便继续查看任务或额度状态。-#### 为什么多个任务只在卡片上看到一个?+### 常见问题-卡片只展示优先级最高的一项,右侧 `+N` 表示其他活动任务。点击卡片打开任务中心可以查看完整列表。+#### 为什么开启后仍收不到通知?-### E. 跨设备同步+依次确认:-#### 为什么跨设备同步开关不可用?+1. 「系统通知」总开关已开启。+2. macOS 系统设置允许 CodexBar 通知。+3. 对应通知子选项已开启。+4. 额度数据正常,或任务类通知所需的 Hook 已开启。+5. 任务耗时达到所选完成通知阈值。-先开启 Hook,再确认 macOS 已登录 iCloud 且 CloudKit 账号状态可用。任一条件不满足时,同步不会实际生效。+#### 为什么短任务没有完成通知?-#### 同步会上传 Token、提示词或会话 ID 吗?+任务完成通知只提醒达到所选时长的任务。默认阈值为 1 分钟,可改为 30 秒、2 分钟或 5 分钟。-不会。跨设备同步只上传脱敏的每日 Hook 聚合,不上传 Token 用量、提示词、回复、原始事件、会话 ID 或轮次 ID。+#### 为什么短暂显示等待批准,却没有通知?-#### 为什么刚开启同步没有立刻看到另一台 Mac 的数据?+只有确实需要用户处理、并且仍处于等待状态的任务才会通知。自动处理或很快恢复运行的请求不会产生过期提醒。-首次开启会安排历史聚合回填,并在后续统计维护和刷新中分批上传、下载。请保持 Hook 与同步开启,并查看菜单底部同步图标和设置中的最近同步时间。+#### 为什么等待通知从通知中心消失了?-#### 同步失败后需要重新开关吗?+当任务恢复运行、完成或终止后,对应等待通知会自动撤回,避免留下已经失效的提示。-通常不需要。网络、账号或 CloudKit 服务暂时失败时,后续刷新会重试未完成日期。长期失败时检查 iCloud 登录状态和系统网络。+#### 为什么没有触觉反馈?-#### 在 CloudKit Dashboard 删除记录后为什么没有自动传回来?+确认「系统通知」「任务触觉反馈」和 Hook 都已开启。触觉效果还取决于 Mac、触控板、辅助功能和系统偏好,部分设备不会产生明显反馈。-云端删除会从本机同步缓存移除,但不会清除已经确认上传的本机日期 hash。如果该日的本机聚合没有变化,下一轮不会立即重复上传;只有本机内容变化,或同步状态中的对应 hash 被清除后,才会再次进入上传候选。+#### 为什么 Codex TUI 通知旁有感叹号?-### F. 通知与触觉反馈+把鼠标停在感叹号上查看原因。确认 Codex 可以正常使用后重试;保存成功后,重新启动已打开的 Codex 会话。-#### 为什么开启通知后仍收不到提醒?+## 11. 其他设置与全局快捷键-依次检查:+### 设置项说明-1. CodexBar「系统通知」总开关是否开启。-2. macOS 系统设置是否允许 CodexBar 通知。-3. 通知子面板中的对应类型是否开启。-4. 额度数据是否可信,或任务类型是否需要 Hook。-5. 任务完成耗时是否达到所选阈值。+| 设置项 | 图标 | 作用 | 常见问题 |+| --------------- | -------- | ---------------------------------- | ------------------------------------------------------- |+| 开机自动启动 | 电源 | 登录 macOS 后自动运行 CodexBar | 设置失败时下方会显示错误;移动 App 后建议关闭再开启一次 |+| 自动检查更新 | 循环箭头 | 定期检查 CodexBar 新版本 | 关闭后仍可手动点击「检查更新」 |+| 菜单栏额度指示 | 仪表 | 在菜单栏显示所选额度窗口 | 没有对应额度数据时自动隐藏 |+| 启用 Codex Hook | 链接 | 开启工作流统计和实时任务能力 | 失败时根据该行下方提示处理 |+| 任务中心 | 列表 | 在主面板显示活动卡片和任务中心入口 | 需要 Hook;Hook 关闭时置灰 |+| 跨设备同步 | iCloud | 合并多台 Mac 的每日工作流统计 | 需要 Hook 和可用 iCloud 账号 |+| 重建数据 | 圆形箭头 | 重新生成所选日期的本机工作流统计 | 需要所选日期仍有本机记录 |+| 系统通知 | 铃铛 | 控制 CodexBar 通知与任务触觉总开关 | 首次开启需要 macOS 授权 |+| 使用快捷键 | 键盘 | 设置全局打开或关闭菜单面板的快捷键 | 至少需要两个修饰键 |+| Codex 版本 | 数字圆圈 | 查看已安装 Codex 及当前使用来源 | 点击路径可以复制 |+| CodexBar 版本 | 信息圆圈 | 查看当前版本与更新状态 | 有更新时显示下载按钮 |-#### 为什么短任务没有完成通知?+### 设置全局快捷键-任务完成通知只针对达到所选时长阈值的任务,默认阈值为 1 分钟。+默认快捷键为 `⌘⇧W`。-#### 为什么短暂出现「等待批准」却没有通知?+修改步骤:-`PermissionRequest` 也可能由 Codex 自动审批产生。CodexBar 会同时检查当前 turn 的审批 reviewer,只有明确路由给用户并且批次结束后仍在等待时才进入等待状态;自动审批或同一批内已经恢复运行、完成的任务不会发送等待提醒。+1. 点击叉号图标清除当前快捷键。+2. 点击「未设置」。+3. 按下新的按键组合。-#### 为什么触觉反馈没有感觉?+快捷键至少需要 `Control`、`Option`、`Shift`、`Command` 中的两个修饰键。-触觉需要通知总开关和任务触觉选项开启,也需要 Hook。最终反馈由输入设备、系统设置和辅助功能决定,部分鼠标或触控板不会产生明显反馈。+| 图标或操作 | 作用 |+| ---------- | -------------------- |+| 回转箭头 | 恢复默认快捷键 `⌘⇧W` |+| 叉号 | 清除当前快捷键 |+| `Esc` | 取消本次录制 |-### G. 快捷键、日志和更新+如果提示「至少需要两个修饰键」,请增加修饰键后重试。如果提示「不可使用系统快捷键」,请选择未被 macOS 保留的组合。注册失败时,CodexBar 会恢复之前的可用设置并显示原因。-#### 为什么无法直接覆盖当前快捷键?+### 开机自动启动失败-为避免录制时误触发当前全局快捷键,需要先点击叉号清除,再录制新组合。可以随时用回转箭头恢复 `⌘⇧W`。+确认 CodexBar 已放在最终安装位置,并检查 macOS 是否允许登录项。移动 App 后,关闭再开启「开机自动启动」,让系统记录新位置。-#### 为什么快捷键提示「至少需要两个修饰键」?+### 退出 CodexBar-全局快捷键必须至少组合 `Control`、`Option`、`Shift`、`Command` 中的两个,以减少和普通输入冲突。+可以右键菜单栏图标选择「退出」,也可以在设置底部点击红色的「退出 CodexBar」。-#### 日志窗口关闭后记录会消失吗?+## 12. 日志、版本与更新-关闭日志窗口不会立即清空当前进程中的记录;点击日志顶部「清空」或退出 CodexBar 才会清除当前内存日志。+### 使用日志-#### 为什么设置中显示两个 Codex 版本?+打开方式:-CodexBar 会同时探测全局 CLI 和 Codex.app 内置 CLI,并标记当前 app-server 实际使用的一项。这样可以排查「磁盘已经更新,但当前连接仍来自旧版本」的问题。+- 右键菜单栏图标,选择「日志」+- 主菜单面板打开时按 `⌘L`-#### 自动更新关闭后还能更新吗?+日志适合排查未登录、初始化失败、刷新超时、Hook 验证和设置失败。-可以。点击设置底部「检查更新」,或在发现更新后点击版本行右侧的更新按钮。+| 日志标签 | 颜色 | 含义 |+| -------- | ---- | -------------------------- |+| 进行 | 橙色 | 正在等待结果 |+| 完成 | 绿色 | 已收到正常结果 |+| 错误 | 红色 | 请求或操作失败 |+| 请求 | 蓝色 | 已发出不需要等待结果的操作 |-## 11. 隐私与数据边界+点击日志行可以展开摘要;点击「预览」查看完整内容,点击「复制」复制内容。顶部数字表示当前日志条数,「清空」会删除当前运行期间的日志列表。-CodexBar 的主要账号、额度和 Token 数据通过本机 Codex app-server 获取并在本机处理。+关闭日志窗口不会立即清空记录;退出 CodexBar 后,本次运行日志会消失。-默认本机 Hook 数据位于:+### 查看 Codex 版本-```text-~/Library/Application Support/CodexBar/HookEvents/-```+设置中的「Codex 版本」会列出:-CodexBar 最多保留最近 210 天的本机 Hook 事件和每日聚合。关闭 Hook 不会自动删除这些文件。当前版本没有单独的历史清除按钮;如需清除本机记录,应先关闭 Hook 和跨设备同步、退出 CodexBar,再通过 Finder 的「前往文件夹」检查并移除上述目录。已经上传到 CloudKit 的聚合不会因为删除本机目录而自动删除,当前版本也没有远端历史删除入口。+| 图标 | 来源 |+| -------- | -------------------- |+| 终端 | 全局安装的 Codex CLI |+| App 标记 | Codex App 内置的 CLI |-CodexBar 不在 UI 中展示完整工作目录、会话 ID 或轮次 ID,也不会读取或展示 rollout 中的提示词、回复、推理和工具内容。+绿色「当前使用」表示 CodexBar 当前连接的来源。橙色「已更新至」表示磁盘上已有更新版本,但当前运行中的 Codex 仍可能是较早版本;重新启动 Codex 后再刷新即可确认。-只有以下功能会产生网络请求:+点击路径可以复制,复制成功后会短暂显示「已复制」。-- 查询手动重置机会的过期时间。-- Sparkle 检查和下载更新。-- 用户明确开启跨设备同步后的 CloudKit private database 请求。+### 更新 CodexBar-更详细的边界见 [README 隐私说明](../README.md#隐私)、[Codex Hook 文档](CodexHook.md) 和 [跨设备同步文档](CrossDeviceSync.md)。+- 开启「自动检查更新」后,CodexBar 会定期检查新版本。+- 点击设置底部「检查更新」可以立即手动检查。+- 发现更新后,「CodexBar 版本」右侧会出现向下箭头按钮。+- 菜单面板底部也会显示新版本提示,双击即可开始更新。++| 更新提示 | 含义 |+| ------------------ | -------------------------------------------------------- |+| 「正在检查更新」 | 正在查询新版本 |+| 「没有可用更新」 | 当前已是最新版本 |+| 「发现新版本」 | 可以点击更新按钮安装 |+| 「检查更新失败」 | 本次检查没有完成,请稍后重试 |+| 「未配置更新资源」 | 当前安装版本不支持内置更新,建议从 Releases 重新下载安装 |++## 13. 常见问题速查++| 现象 | 优先检查 |+| ------------------------ | ---------------------------------------------------- |+| 找不到 Dock 图标或主窗口 | CodexBar 只显示在菜单栏,这是正常设计 |+| 菜单栏人物带叉 | 打开菜单查看「未登录」或「初始化失败」 |+| 主面板显示「暂无数据」 | 确认 Codex 已登录,手动刷新并查看日志 |+| 额度或热力图变淡 | 当前显示的是较早缓存,等待或手动刷新 |+| 菜单栏没有额度竖条 | 开启「菜单栏额度指示」,并检查所选窗口是否有数据 |+| 看不到手动重置次数 | 当前账号没有可用机会,或数据尚未刷新 |+| 热力图没有工作流统计 | 开启 Hook,并确认该日期有 Hook 记录 |+| 活动卡片没有出现 | 同时开启 Hook 和「任务中心」 |+| 点击活动卡片没有反应 | 当前没有可展示任务,或主数据尚未加载 |+| 任务一直显示运行中 | 任务可能没有正常留下结束状态,等待后续活动或自动过期 |+| 跨设备同步开关置灰 | 先开启 Hook,并确认 iCloud 可用 |+| iCloud 图标带感叹号 | 悬停查看网络、账号或服务错误 |+| 收不到系统通知 | 检查总开关、macOS 权限、子选项和 Hook 依赖 |+| 没有触觉反馈 | 检查三个开关,并确认设备支持触觉 |+| 快捷键无法设置 | 先清除原快捷键,使用至少两个修饰键的新组合 |+| 设置显示两个 Codex 版本 | 查看绿色「当前使用」标记确认实际来源 |+| 更新检查失败 | 稍后重试,或从 Releases 手动下载安装 |++如果速查表仍无法解决问题,请打开日志,找到最新红色「错误」记录,再结合对应功能章节处理。++## 14. 隐私与数据范围++CodexBar 以本机处理为主:++- 账号、额度和 Token 用量在本机读取和展示。+- Hook 原始记录保存在当前 Mac,默认保留最近 210 天。+- 实时任务只在当前 App 运行期间用于状态展示。+- 菜单面板只显示项目名称,不显示完整工作目录、会话编号或轮次编号。+- CodexBar 不展示提示词、回复、推理内容、工具内容或审批内容。++跨设备同步完全可选。开启后,只通过当前 iCloud 账号的私有数据库同步每日工作流聚合;不会同步 Codex 账号、额度、Token 用量、原始 Hook 记录、实时任务、请求日志或认证信息。++CodexBar 只有在以下用户可见功能中使用网络:++- 查询手动重置机会的过期时间+- 检查和下载 CodexBar 更新+- 用户主动开启的跨设备同步++关闭 Hook 会停止记录新的工作流活动;关闭跨设备同步会停止后续同步。更详细的数据说明见 [Codex Hook 文档](CodexHook.md) 和 [跨设备同步文档](CrossDeviceSync.md)diff --git a/README.md b/README.mdindex 3ad8081..0880cf0 100644--- a/README.md+++ b/README.md@@ -1,111 +1,23 @@# CodexBar-> 常驻 macOS 菜单栏的 Codex 状态看板+> 在 macOS 菜单栏,一眼查看 Codex 状态、额度与使用情况。-CodexBar 在不打开 Codex CLI 或 Codex App 的情况下快速查看 Codex 账号状态、额度重置时间、Token 用量和本机使用情况统计。它连接本机 Codex app-server 获取账号与用量信息,也可以通过 Codex Hook 记录本机 Codex 事件,让菜单栏成为一个轻量、实时的 Codex 仪表盘。+CodexBar 是一款无 Dock 图标的 macOS 菜单栏应用。无需打开 Codex CLI 或 Codex App,即可快速了解账号状态、剩余额度、重置时间、Token 用量和正在进行的任务。<p align="center">- <img src="Images/preview.gif" width="600">+ <img src="Images/preview.gif" width="600" alt="CodexBar 预览"></p>-> 第一次使用或想了解所有可点击入口、状态含义和排障方法,请阅读[完整使用指南与常见问题](Docs/UserGuide.md)。+## 主要功能-## 为什么需要 CodexBar--Codex 的额度、Token 用量和使用情况通常分散在终端、App 或 Session 中。CodexBar 把这些信息放到一个可随时呼出的菜单栏面板中,适合需要频繁使用 Codex、关注剩余额度和使用情况的 macOS 用户。--- 查看当前账号是否已登录,以及 Codex CLI / Codex.app 的运行版本-- 跟踪不同时间窗口的额度剩余比例和下一次重置时间-- 用 30 周热力图回顾每日 Token 用量-- 在开启 Codex Hook 后在 30 周热力图中可查看当天最热模型,以及会话、对话轮次、调用工具、权限请求、上下文压缩和子智能体统计 (仅在开启后可记录查看,无法查看到历史数据)-- 通过菜单栏状态点、活动卡片和并发任务中心实时查看 Codex 正在运行、等待批准及刚完成的任务,并展示当前推理强度;可可靠统计且存在活跃子 Agent 时,活动卡片还会显示其数量-- 通过可选 iCloud 私有数据库同步实现跨设备数据合并-- 额度告急、额度恢复、任务等待批准、长任务完成时收到系统通知(可选开启)-- 任务等待批准或结束时通过支持的触控板获得触觉反馈(可选开启)--## 有什么功能--### 菜单栏即状态中心--CodexBar 是一个无 Dock 图标的 macOS 菜单栏应用。--左键点击菜单栏图标即可打开状态面板。--右键 (或者 `⌃ + 鼠标左键点击`) 可进入设置、日志或退出应用。--使用默认全局快捷键 `⌘ ⇧ W` 适合在任何工作区快速查看当前 Codex 状态。--系统设置快捷键 `⌘,` 会打开 CodexBar 的自定义设置窗口;菜单面板打开时按 `⌘L` 会直接打开日志窗口。--「菜单栏额度指示」默认开启,菜单栏图标左侧会以一条细竖向进度条显示当前账号 Codex 额度中所选窗口的剩余比例;关闭后菜单栏图标保持纯图标显示。--开启 Codex Hook 后,菜单栏小人右下角的状态点会反映实时任务状态:运行中为蓝色、等待批准为橙色、刚完成为绿色,暂无活动时不显示。主面板额度快照不可用时也不显示状态点,与活动卡片的「暂无数据」状态保持一致。状态优先级依次为等待批准、运行中、刚完成和暂无活动;小人保持系统前景色,账号异常仍使用带叉图标表示,额度竖条也保持自己的颜色。--菜单面板账号卡片下方默认显示活动卡片,汇总当前项目、模型、推理强度、工具、耗时和其他并发任务数量;可可靠统计且存在活跃子 Agent 时还会显示其数量。可在设置中关闭「主面板任务中心」来隐藏活动卡片及任务中心入口;该选项依赖 Codex Hook,Hook 关闭时显示为关闭并置灰,但会保留原偏好。隐藏只影响主面板展示,不停止 Hook 记录、菜单栏任务状态点、任务通知或触觉反馈。模型、推理强度与项目等同一行信息统一使用 `•` 连接。主面板快照不可用时,活动卡片显示「暂无数据」且不开放任务中心;快照可用并存在活动任务、最近完成或最近终止记录时,点击卡片会打开并发任务中心,按等待确认、运行中、最近完成和最近终止分组展示全部任务,其中模型后的推理强度同样使用 `•` 连接。只有终止历史时,卡片显示最近一项灰色终止状态。面板优先在菜单右侧展开,空间不足时自动切换到左侧,并优先与活动卡片顶边对齐;暂时无法取得有效位置时会等待布局更新后重试,仍然失败才在主面板旁垂直居中。绿色完成状态保留 30 秒,最近完成和最近终止记录保留 10 分钟;终止记录不触发完成提醒。--### 额度与重置时间一眼可见--额度区用分段电量条展示不同时间窗口的剩余额度,并显示剩余百分比和重置时间。存在可用手动重置机会时,主 limit 标题右侧会显示 `重置次数: N`,点击后通过侧边详情面板按过期时间展示各重置机会的数量;未来 7 天内过期的次数显示为橙色,少于 24 小时过期的次数显示为红色。--### 近 30 周 Token 热力图--热力图以周为列、日为行展示近 30 周的每日 Token 用量。--鼠标悬停到任意日期时,会打开侧边详情面板展示当天 Token 数和用量强度。--开启 Codex Hook 后,同一面板还会展示当天的使用详情统计。--### Codex Hook 使用详情--在设置中开启「启用 Codex Hook」后,CodexBar 会把自身注册为本机 Codex Hook 用于记录会话开始、回复结束、调用工具、权限请求、上下文压缩和子智能体事件。--统计结果会汇总到热力图详情面板中,不打断正常的 Codex 使用流程。--设置页「重建数据」第一次点击选择开始日期,第二次点击选择结束日期,并批量重新统计范围内仍存在且非空的分日原始事件;连续点击同一天两次即可只重建一天,选择范围允许跨月。最近 210 天保留窗口内的日期均可选择,本机原始事件非空的日期以圆点标记,没有数据的日期不会进入实际重建。确认后会为实际重建的每一天生成新的本机 generation;开启跨设备同步时,只替换当前设备对应日期的旧云端聚合,其他设备、范围外日期、无数据日期和原始事件不受影响。--主 App 还会在后台只读 Hook JSONL:启动时按块恢复最近 24 小时的活动,之后 tail 当天新增事件,并在内存中维护并发任务状态。跨日任务缺少起点时会按精确 session + turn 定向查找更早的 Prompt;对于仍处于运行、等待终态确认或等待批准状态的精确 turn,CodexBar 会每秒增量读取对应本机 Codex session rollout,用 `task_started` 回填缺失起点、用 `task_complete` 补齐缺失的结束、用 `turn_aborted` 清理中断任务并生成最近终止记录,用 `turn_context.approvals_reviewer` 区分用户审批和自动审批,并用 `turn_context.effort` 补齐当前 turn 的推理强度;初始 512 KB 未找到 effort 时,主 App 会按精确 turn 从文件尾部最多 8 MB 执行一次受限回查。只有 reviewer 明确为 `user` 且同时收到 `PermissionRequest` 时才显示等待批准;`auto_review` 不会触发等待状态或提醒。Subagent Hook 带有稳定 `agent_id` 时,CodexBar 会通过共享 session 将子 Agent 归属到唯一的当前顶层任务,并在内存中幂等配对开始和结束事件,统计当前活跃数量;早于当前顶层任务可信开始时间的事件会被视为上一 turn 的迟到事件并忽略,字段缺失、同 session 无法唯一关联顶层任务或事件序列不完整时则隐藏数量,避免展示不可靠结果。同 session 新 Prompt 会让旧 turn 立即退出活动列表,但先保留 5 秒终态确认窗口,优先接受 rollout 或迟到 Hook 的完成/终止信号,仍无终态才记为终止。不读取提示词、回复、推理内容、工具内容、审批内容或 token 数据。该实时状态用于菜单栏状态点、活动卡片、并发任务中心、可选任务通知和触觉反馈,不新增历史状态文件,也不参与跨设备同步。--CodexBar 只会追加或移除属于当前 CodexBar 可执行文件的 Hook,不会删除用户已有的其他 Codex Hook。--更详细的配置、存储和统计口径见 [Codex Hook 文档](Docs/CodexHook.md)--### 可选跨设备同步--如果已经开启 Codex Hook,且当前 iCloud 账号可用,可以在设置里开启「跨设备同步」--CodexBar 会把该设备的使用详情数据同步到当前 iCloud 账号的 CloudKit private database,用于在多台 Mac 上合并查看工作流统计。--同步不会上传 Codex 账号、额度、Token 用量、原始 Hook events、会话 ID、轮次 ID、请求日志或 Codex 认证文件。--完整同步范围见 [跨设备同步文档](Docs/CrossDeviceSync.md)--### 系统通知与触觉反馈--在设置中开启「系统通知」后,CodexBar 会在关键状态变化时发送本地通知:--- 额度剩余比例跌破所选阈值 (5% / 10% / 25%)-- 每个额度类型和时间窗口产生消耗后恢复至 100% 时提示额度已重置;窗口提供重置时间时,同一周期只提醒一次-- Codex 完成一轮超过所选时长的任务 (需开启 Codex Hook)-- Codex 请求批准工具操作并等待用户处理;当前 App 运行期间任务离开等待状态后自动撤回对应通知 (需开启 Codex Hook)-- 手动重置机会将在 7 天内过期,并按 24 小时间隔提醒--五类通知可以单独开关;全部为本地通知,不新增网络请求。--通知子面板还可以控制「Codex TUI 通知」。该开关与用户级 `~/.codex/config.toml` 中的 `[tui] notifications` 联动:关闭时写入 `false`,开启时写入 `true`,不会修改顶层 `notify` 外部回调;已经运行的 Codex CLI 需要重新启动会话后采用新设置。--通知子面板中的「任务触觉反馈」默认开启;当任务进入等待批准或确认结束时,CodexBar 会每 100 ms 请求一次层级变化触觉反馈,连续 10 次。该功能服从 App 内「系统通知」总开关,但不依赖系统通知授权或长任务时长阈值;是否实际反馈及震感强弱由当前输入设备、辅助功能和系统偏好决定。--Hook 事件可能在一次轮询中成批到达。CodexBar 会先处理完整批次,再按任务合并等待状态:只有 reviewer 为 `user`、批次结束后仍在等待批准的任务才通知一次;自动审批以及已经恢复运行、完成或移除的短暂候选不会产生过期提醒。--Hook `Stop` 与本机 rollout 的完成信号会统一去重;迟到的重复完成、工具或权限事件不会让已完成任务重复通知、触发触觉反馈或重新显示为活动状态。--### 日志与版本信息--CodexBar 内置请求日志窗口,用于查看 app-server 请求状态和排查刷新问题。设置页会展示 CodexBar 版本、当前 Codex CLI / Codex.app 版本、运行来源和本地安装路径,路径点击即可复制。--### 自动更新--CodexBar 使用 Sparkle 检查更新。安装后,新版本会通过内置更新流程推送;也可以从设置窗口手动检查更新。+- **额度状态**:查看各时间窗口的剩余额度、重置时间和手动重置机会+- **Token 热力图**:用近 30 周日历热力图回顾每日 Token 用量+- **实时任务**:开启 Codex Hook 后,查看运行中、等待批准、最近完成和终止的任务+- **工作流统计**:按日期查看会话、对话轮次、工具调用、权限请求、上下文压缩和子 Agent 等数据+- **及时提醒**:可选额度告急、额度恢复、等待批准、长任务完成通知与触觉反馈+- **跨设备汇总**:通过可选的 iCloud 私有数据库同步每日聚合数据+- **本地优先**:账号、额度、Token 用量和工作流事件均以本机处理为主+- **原生体验**:支持全局快捷键、开机启动、系统日志和 Sparkle 自动更新## 安装@@ -115,65 +27,14 @@ CodexBar 使用 Sparkle 检查更新。安装后,新版本会通过内置更brew install --cask bob-zebedy/tap/codexbar```-### 下载安装--从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载最新 DMG,打开后把 `CodexBar.app` 拖入 `/Applications`--后续版本会通过内置 Sparkle 自动更新推送。+也可以从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载最新 DMG,并将 `CodexBar.app` 拖入 `/Applications`。-### 运行要求+运行要求:- macOS 15.0 或更高版本-- 已安装 [Codex CLI](https://github.com/openai/codex),或已安装 `Codex.app`-- 已在 Codex 中完成登录--> 如果移动应用位置后才开启开机自启,建议重新开关一次「开机启动」,让 macOS 记录最终应用路径。--## 隐私--CodexBar 默认通过本机 Codex app-server 读取账号、额度和 Token 用量。若 app-server 返回可用手动重置机会,CodexBar 会使用本机 Codex OAuth token 向 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 发起只读请求,用于读取这些重置机会的过期时间;请求失败时不展示具体过期时间,重置次数侧边详情面板显示「未知过期时间」,也不会保留原始响应。--用户在通知子面板切换「Codex TUI 通知」时,CodexBar 通过本机 app-server 只更新用户级 `config.toml` 的 `tui.notifications`,不修改顶层 `notify` 或其他 Codex 配置。--Codex Hook 工作流数据默认只保存在本机:--```text-~/Library/Application Support/CodexBar/HookEvents/-```--菜单栏实时任务状态只存在于当前 App 进程内。活动卡片和并发任务中心只展示工作目录最后一级项目名、模型、推理强度、工具、阶段与耗时;可可靠统计且存在活跃子 Agent 时,活动卡片还会显示其数量。不展示完整路径、会话 ID、轮次 ID 或 agent ID。这份状态不会上传到 CloudKit,也不会产生新的网络请求。为补齐 Hook 缺失的起点、结束、中断、审批路由或推理强度,CodexBar 只对当前活跃 turn 读取 `~/.codex/sessions/` 或 `~/.codex/archived_sessions/` 下对应 rollout JSONL:正常情况下只增量解析生命周期事件、turn ID、起止耗时、`turn_context.approvals_reviewer` 和 `turn_context.effort`,effort 缺失时最多额外读取文件尾部 8 MB;不会提取、保存或展示其中的提示词、回复、推理内容、工具内容或 token 数据。--只有在用户开启「跨设备同步」后,CodexBar 才会通过 `CloudKit private database` 同步每日使用详情数据;同步的数据副本只包含各个事件数量、项目聚合、模型名使用次数,以及用于区分同一日期独立数据段的随机 generation,不包含原始事件、会话 ID 或轮次 ID。正常追加时,同一 generation 的本机数据和云端副本只取一份;确认事件文件从空文件重新开始时,新 generation 会与旧云端贡献相加;无法确认来源的非空替换不会自动覆盖或叠加旧云端数据。只有用户在设置页确认批量重建日期范围时,才会以范围内实际存在的本机原始事件为准,替换当前设备对应日期的云端 generation。--除上述重置机会过期时间查询、Sparkle appcast / DMG 下载,以及用户开启跨设备同步后的 CloudKit 请求外,CodexBar 自身不发起其他网络请求。--## 从源码构建--项目使用 Swift 6、SwiftUI + AppKit + MVVM,依赖 Sparkle (SwiftPM)--```bash-git clone [email protected]:bob-zebedy/CodexBar.git-cd CodexBar-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build-```--也可以直接用 Xcode 打开 `CodexBar.xcodeproj` 运行。--## 项目文档--- [完整使用指南与常见问题](Docs/UserGuide.md)-- [app-server 通信合约](Docs/AppServer.md)-- [Codex Hook 工作流统计](Docs/CodexHook.md)-- [跨设备同步](Docs/CrossDeviceSync.md)-- [开发文档](Docs/DevelopmentGuide.md)--Swift 源码按职责放在 `CodexBar/` 下:+- 已安装并登录 [Codex CLI](https://github.com/openai/codex) 或 Codex App-- `App/`: 应用入口-- `Controllers/`: 菜单栏、菜单面板和独立窗口控制器-- `Models/`: 账号、额度、用量、工作流统计和错误模型-- `Services/`: app-server、Codex CLI、设置、Hook、统计、日志、开机自启和更新服务-- `Views/`: 菜单面板、设置窗口、日志窗口和共享 Liquid Glass 样式+更多使用方法见[使用指南与常见问题](Docs/UserGuide.md)## 许可证diff --git a/appcast.xml b/appcast.xmlindex 5f87c97..4b89d72 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.4.0</title>+ <sparkle:version>50</sparkle:version>+ <sparkle:shortVersionString>3.4.0</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.4.0</sparkle:releaseNotesLink>+ <pubDate>Tue, 21 Jul 2026 16:06:26 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.4.0.dmg" sparkle:edSignature="tonVt6j9oDtgI7FAqBH5y+qg38WAJEycXBnHSyw7eMv9br5ppuOBYtfsngqCkBP/QkMFKnn6QZqlUlkbSMZHCA==" length="4176079" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.3.11</title><sparkle:version>49</sparkle:version>