Skip to content

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

feat: 新增并发任务中心

Bob74bf1de05526
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 424d167..6876f25 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 = 41;
+ CURRENT_PROJECT_VERSION = 42;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -298,7 +298,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.3.3;
+ MARKETING_VERSION = 3.3.4;
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 = 41;
+ CURRENT_PROJECT_VERSION = 42;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -337,7 +337,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.3.3;
+ MARKETING_VERSION = 3.3.4;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/Controllers/ActivityCenterPanelController.swift b/CodexBar/Controllers/ActivityCenterPanelController.swift
new file mode 100644
index 0000000..e6ec8da
--- /dev/null
+++ b/CodexBar/Controllers/ActivityCenterPanelController.swift
@@ -0,0 +1,221 @@
+import AppKit
+import Combine
+import SwiftUI
+
+/// 点击活动卡片后展开的并发任务中心,复用菜单侧边抽屉定位和动画。
+@MainActor
+final class ActivityCenterPanelController {
+ private let activityMonitor: CodexActivityMonitor
+ private let presentationState: CodexActivityCenterPresentationState
+ private var panel: NSPanel?
+ private var hostingController: NSHostingController<CodexActivityCenterView>?
+ private var currentContext: CodexActivityCenterPanelContext?
+ private weak var menuSurfaceWindow: NSWindow?
+ private weak var menuContentView: NSView?
+ private var cancellables = Set<AnyCancellable>()
+ private lazy var presenter = SidePanelDrawerPresenter(
+ animationKey: Metrics.drawerTransformAnimationKey,
+ contentViewProvider: { [weak self] in
+ self?.hostingController?.view
+ }
+ )
+
+ init(
+ activityMonitor: CodexActivityMonitor,
+ presentationState: CodexActivityCenterPresentationState
+ ) {
+ self.activityMonitor = activityMonitor
+ self.presentationState = presentationState
+
+ activityMonitor.$snapshot
+ .dropFirst()
+ .sink { [weak self] snapshot in
+ guard let self, presentationState.isPresented else {
+ return
+ }
+ if snapshot.hasTaskCenterContent {
+ updateVisibleLayout(for: snapshot)
+ } else {
+ hide()
+ }
+ }
+ .store(in: &cancellables)
+ }
+
+ var isVisible: Bool {
+ presenter.isVisible
+ }
+
+ func containsScreenPoint(_ screenPoint: NSPoint) -> Bool {
+ guard let panel, panel.isVisible else {
+ return false
+ }
+ return panel.frame.contains(screenPoint)
+ }
+
+ func toggle(
+ context: CodexActivityCenterPanelContext,
+ relativeTo menuSurfaceWindow: NSWindow?,
+ contentView: NSView?
+ ) {
+ if isVisible {
+ hide()
+ return
+ }
+
+ show(
+ context: context,
+ relativeTo: menuSurfaceWindow,
+ contentView: contentView
+ )
+ }
+
+ func hide(immediate: Bool = false) {
+ // 热力图 hover 等高频路径会盲调 hide;已隐藏时跳过 @Published 写入,避免整个菜单重算。
+ guard presentationState.isPresented || presenter.isVisible else {
+ return
+ }
+ presentationState.isPresented = false
+ presenter.hide(immediate: immediate)
+ }
+
+ private func show(
+ context: CodexActivityCenterPanelContext,
+ relativeTo menuSurfaceWindow: NSWindow?,
+ contentView: NSView?
+ ) {
+ guard activityMonitor.snapshot.hasTaskCenterContent,
+ let menuSurfaceWindow else {
+ hide(immediate: true)
+ return
+ }
+
+ let panel = ensurePanel()
+ currentContext = context
+ self.menuSurfaceWindow = menuSurfaceWindow
+ menuContentView = contentView
+ let layout = panelLayout(
+ context: context,
+ menuSurfaceWindow: menuSurfaceWindow,
+ contentView: contentView,
+ snapshot: activityMonitor.snapshot
+ )
+
+ updateContent(panelSize: layout.size)
+ panel.level = menuSurfaceWindow.level
+ presentationState.isPresented = true
+ defer {
+ SidePanelSupport.restoreMenuSurfaceKeyWindow(menuSurfaceWindow)
+ }
+ presenter.present(panel, at: layout.position, relativeTo: menuSurfaceWindow)
+ }
+
+ private func panelLayout(
+ context: CodexActivityCenterPanelContext,
+ menuSurfaceWindow: NSWindow,
+ contentView: NSView?,
+ snapshot: CodexActivitySnapshot
+ ) -> (size: CGSize, position: SidePanelPosition) {
+ let menuSurfaceFrame = SidePanelSupport.contentScreenFrame(
+ for: contentView,
+ in: menuSurfaceWindow
+ ) ?? menuSurfaceWindow.frame
+ let screen = menuSurfaceWindow.screen ?? NSScreen.main
+ let visibleFrame = screen?.visibleFrame ?? menuSurfaceFrame
+ let alignmentScreenFrame = SidePanelSupport.validatedAlignmentScreenFrame(
+ context.alignmentScreenFrame,
+ menuSurfaceFrame: menuSurfaceFrame
+ )
+ let screenMaximumHeight = visibleFrame.height - SidePanelSupport.Metrics.screenPadding * 2
+ let menuMaximumHeight = alignmentScreenFrame.map {
+ $0.maxY - menuSurfaceFrame.minY
+ } ?? screenMaximumHeight
+ let panelSize = CodexActivityCenterView.panelSize(
+ maximumHeight: min(screenMaximumHeight, menuMaximumHeight),
+ snapshot: snapshot
+ )
+ let positioningFrame = SidePanelSupport.anchorAwareVisibleFrame(
+ visibleFrame: visibleFrame,
+ screenFrame: screen?.frame,
+ alignmentScreenFrame: alignmentScreenFrame
+ )
+ let position = SidePanelSupport.position(
+ panelSize: panelSize,
+ menuSurfaceFrame: menuSurfaceFrame,
+ visibleFrame: positioningFrame,
+ preferredSide: context.preferredSide,
+ proposedY: SidePanelSupport.alignedProposedY(
+ panelSize: panelSize,
+ menuSurfaceFrame: menuSurfaceFrame,
+ alignmentScreenFrame: alignmentScreenFrame
+ )
+ )
+
+ return (panelSize, position)
+ }
+
+ private func updateVisibleLayout(for snapshot: CodexActivitySnapshot) {
+ guard let panel,
+ panel.isVisible,
+ let currentContext,
+ let menuSurfaceWindow else {
+ return
+ }
+
+ let layout = panelLayout(
+ context: currentContext,
+ menuSurfaceWindow: menuSurfaceWindow,
+ contentView: menuContentView,
+ snapshot: snapshot
+ )
+ // 内容更新由 @ObservedObject 原地驱动;只有尺寸或位置变化才需要重建 rootView 和重设 frame。
+ guard panel.frame != layout.position.frame else {
+ return
+ }
+ if panel.frame.size != layout.size {
+ updateContent(panelSize: layout.size)
+ }
+ panel.setFrame(layout.position.frame, display: true)
+ }
+
+ private func ensurePanel() -> NSPanel {
+ if let panel {
+ return panel
+ }
+
+ let panel = SidePanelSupport.makePanel(
+ initialSize: CodexActivityCenterView.initialPanelSize,
+ ignoresMouseEvents: false
+ )
+ self.panel = panel
+ return panel
+ }
+
+ private func updateContent(panelSize: CGSize) {
+ let rootView = CodexActivityCenterView(
+ activityMonitor: activityMonitor,
+ presentationState: presentationState,
+ panelSize: panelSize
+ )
+
+ if let hostingController {
+ hostingController.rootView = rootView
+ } else {
+ let hostingController = NSHostingController(rootView: rootView)
+ hostingController.sizingOptions = [.preferredContentSize]
+ panel?.contentViewController = hostingController
+ self.hostingController = hostingController
+ }
+
+ SidePanelSupport.configureLayers(
+ hostingView: hostingController?.view,
+ contentView: panel?.contentView,
+ cornerRadius: CodexActivityCenterView.panelCornerRadius
+ )
+ panel?.setContentSize(panelSize)
+ }
+
+ private enum Metrics {
+ static let drawerTransformAnimationKey = "CodexBar.activityCenterDrawerTransform"
+ }
+}
diff --git a/CodexBar/Controllers/SidePanelSupport.swift b/CodexBar/Controllers/SidePanelSupport.swift
index 54051d2..6b2e631 100644
--- a/CodexBar/Controllers/SidePanelSupport.swift
+++ b/CodexBar/Controllers/SidePanelSupport.swift
@@ -393,6 +393,32 @@ enum SidePanelSupport {
return alignmentScreenFrame.maxY - panelSize.height
}
+ /// 宿主菜单面板可能进入系统菜单栏保留区域; 面板定位只向上放宽到锚点行顶边,
+ /// 让两者顶边对齐, 同时继续沿用 visibleFrame 的左右边界和 Dock 下边界
+ static func anchorAwareVisibleFrame(
+ visibleFrame: CGRect,
+ screenFrame: CGRect?,
+ alignmentScreenFrame: CGRect?
+ ) -> CGRect {
+ guard let screenFrame, let alignmentScreenFrame else {
+ return visibleFrame
+ }
+
+ let permittedMaxY = min(
+ screenFrame.maxY,
+ max(
+ visibleFrame.maxY,
+ alignmentScreenFrame.maxY + Metrics.screenPadding
+ )
+ )
+ return CGRect(
+ x: visibleFrame.minX,
+ y: visibleFrame.minY,
+ width: visibleFrame.width,
+ height: permittedMaxY - visibleFrame.minY
+ )
+ }
+
/// 锚点必须落在宿主内容区容差范围内才可信, 否则丢弃并走回退定位
static func validatedAlignmentScreenFrame(
_ alignmentScreenFrame: CGRect?,
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 6d78e04..9afc0db 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -71,8 +71,13 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
private let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
private let popover = NSPopover()
private let menuSurfaceVisibility = MenuSurfaceVisibilityState()
+ private let activityCenterPresentationState = CodexActivityCenterPresentationState()
private let heatmapDetailPanelController = HeatmapDetailPanelController()
private let resetCreditsPanelController = ResetCreditsPanelController()
+ private lazy var activityCenterPanelController = ActivityCenterPanelController(
+ activityMonitor: activityMonitor,
+ presentationState: activityCenterPresentationState
+ )
private var activeMenuSurface = ActiveMenuSurface.none
private lazy var globalHotKeyController = GlobalHotKeyController { [weak self] in
self?.toggleMenuSurfaceFromHotKey()
@@ -322,7 +327,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
.running
case .completed(_, highlighted: true):
.completed
- case .completed, .idle:
+ case .completed, .terminated, .idle:
nil
}
}
@@ -384,7 +389,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
text += " • 耗时 \(CodexActivityDurationFormat.text(for: duration))"
}
return text
- case .completed, .idle:
+ case .completed, .terminated, .idle:
return nil
}
}
@@ -501,11 +506,15 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
activityMonitor: activityMonitor,
syncSettings: syncSettings,
menuSurfaceVisibility: menuSurfaceVisibility,
+ activityCenterPresentationState: activityCenterPresentationState,
onUsageHeatmapHoverChange: { [weak self] context in
self?.updateHeatmapDetailPanel(context)
},
onResetCreditsTap: { [weak self] context in
self?.toggleResetCreditsPanel(context)
+ },
+ onActivityCenterTap: { [weak self] context in
+ self?.toggleActivityCenterPanel(context)
}
)
.environmentObject(appUpdater)
@@ -547,6 +556,17 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
refreshWorkflowIfHookEnabled(performMaintenance: true)
}
.store(in: &cancellables)
+
+ viewModel.$snapshot
+ .map { $0 != nil }
+ .removeDuplicates()
+ .sink { [weak self] isAvailable in
+ guard let self, !isAvailable else {
+ return
+ }
+ activityCenterPanelController.hide(immediate: true)
+ }
+ .store(in: &cancellables)
}
private func observeWorkflowSyncState() {
@@ -561,6 +581,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
workflowSyncScheduler.requestSync()
} else {
workflowSyncScheduler.clearPendingMaintenance()
+ activityCenterPanelController.hide(immediate: true)
}
}
.store(in: &cancellables)
@@ -1064,14 +1085,22 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
scheduleAuxiliaryWindowKeyFocusRestore()
}
- private func hideSideDetailPanels() {
- heatmapDetailPanelController.hide(immediate: true)
- resetCreditsPanelController.hide(immediate: true)
+ /// 侧边面板互斥名册:新增面板只需要加入这里,显隐与点击区域判定即可覆盖。
+ private var sideDetailPanels: [MenuSideDetailPanel] {
+ [heatmapDetailPanelController, resetCreditsPanelController, activityCenterPanelController]
+ }
+
+ private func hideSideDetailPanels(
+ except kept: MenuSideDetailPanel? = nil,
+ immediate: Bool = true
+ ) {
+ for panel in sideDetailPanels where panel !== kept {
+ panel.hide(immediate: immediate)
+ }
}
private func isPointInDetailPanel(_ screenPoint: NSPoint) -> Bool {
- heatmapDetailPanelController.containsScreenPoint(screenPoint)
- || resetCreditsPanelController.containsScreenPoint(screenPoint)
+ sideDetailPanels.contains { $0.containsScreenPoint(screenPoint) }
}
private func suspendAuxiliaryWindowKeyFocus() {
@@ -1146,7 +1175,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
if context != nil {
- resetCreditsPanelController.hide()
+ hideSideDetailPanels(except: heatmapDetailPanelController, immediate: false)
}
heatmapDetailPanelController.update(
@@ -1164,7 +1193,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
return
}
- heatmapDetailPanelController.hide(immediate: true)
+ hideSideDetailPanels(except: resetCreditsPanelController)
resetCreditsPanelController.toggle(
context: context,
relativeTo: menuSurfaceWindow,
@@ -1172,6 +1201,22 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
)
}
+ private func toggleActivityCenterPanel(_ context: CodexActivityCenterPanelContext) {
+ guard isActiveMenuSurfaceVisible,
+ let menuSurfaceContentView = activeMenuSurfaceContentView,
+ let menuSurfaceWindow = activeMenuSurfaceWindow else {
+ activityCenterPanelController.hide(immediate: true)
+ return
+ }
+
+ hideSideDetailPanels(except: activityCenterPanelController)
+ activityCenterPanelController.toggle(
+ context: context,
+ relativeTo: menuSurfaceWindow,
+ contentView: menuSurfaceContentView
+ )
+ }
+
private var isActiveMenuSurfaceVisible: Bool {
switch activeMenuSurface {
case .none:
@@ -1269,3 +1314,13 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
case fallbackPanel
}
}
+
+/// 菜单侧边面板的互斥名册接口;面板间互斥和点击区域判定统一走名册遍历。
+private protocol MenuSideDetailPanel: AnyObject {
+ func hide(immediate: Bool)
+ func containsScreenPoint(_ screenPoint: NSPoint) -> Bool
+}
+
+extension HeatmapDetailPanelController: MenuSideDetailPanel {}
+extension ResetCreditsPanelController: MenuSideDetailPanel {}
+extension ActivityCenterPanelController: MenuSideDetailPanel {}
diff --git a/CodexBar/Models/CodexActivityModels.swift b/CodexBar/Models/CodexActivityModels.swift
index d6e0bcc..4c8b4a8 100644
--- a/CodexBar/Models/CodexActivityModels.swift
+++ b/CodexBar/Models/CodexActivityModels.swift
@@ -19,7 +19,8 @@ nonisolated struct CodexActivityPromptReference: Hashable, Sendable {
}
/// 正在运行或等待批准的任务摘要,不对 UI 暴露原始会话 ID。
-nonisolated struct CodexActivityTaskSnapshot: Equatable, Sendable {
+nonisolated struct CodexActivityTaskSnapshot: Equatable, Identifiable, Sendable {
+ let id: UUID
let latestEvent: CodexActivityEvent
let projectName: String?
let modelName: String?
@@ -31,30 +32,62 @@ nonisolated struct CodexActivityTaskSnapshot: Equatable, Sendable {
/// 最近确认结束的任务。完成只表示一轮任务结束,不代表执行成功。
nonisolated struct CodexActivityCompletion: Equatable, Identifiable, Sendable {
- let id: String
+ let id: UUID
let projectName: String?
+ let modelName: String?
let completedAt: Date
let duration: TimeInterval?
}
+/// 最近确认终止的任务。终止不会被视为完成,也不会触发完成提醒。
+nonisolated struct CodexActivityTermination: Equatable, Identifiable, Sendable {
+ let id: UUID
+ let projectName: String?
+ let modelName: String?
+ let terminatedAt: Date
+ let duration: TimeInterval?
+}
+
/// UI 只消费该快照,不直接读取或解释 Hook 事件。
nonisolated struct CodexActivitySnapshot: Equatable, Sendable {
- let primaryWaitingTask: CodexActivityTaskSnapshot?
- let primaryRunningTask: CodexActivityTaskSnapshot?
- let mostRecentCompletion: CodexActivityCompletion?
- let waitingCount: Int
- let runningCount: Int
+ let waitingTasks: [CodexActivityTaskSnapshot]
+ let runningTasks: [CodexActivityTaskSnapshot]
+ let recentCompletions: [CodexActivityCompletion]
+ let recentTerminations: [CodexActivityTermination]
let isCompletionHighlighted: Bool
static let empty = CodexActivitySnapshot(
- primaryWaitingTask: nil,
- primaryRunningTask: nil,
- mostRecentCompletion: nil,
- waitingCount: 0,
- runningCount: 0,
+ waitingTasks: [],
+ runningTasks: [],
+ recentCompletions: [],
+ recentTerminations: [],
isCompletionHighlighted: false
)
+ var primaryWaitingTask: CodexActivityTaskSnapshot? {
+ waitingTasks.first
+ }
+
+ var primaryRunningTask: CodexActivityTaskSnapshot? {
+ runningTasks.first
+ }
+
+ var mostRecentCompletion: CodexActivityCompletion? {
+ recentCompletions.first
+ }
+
+ var mostRecentTermination: CodexActivityTermination? {
+ recentTerminations.first
+ }
+
+ var waitingCount: Int {
+ waitingTasks.count
+ }
+
+ var runningCount: Int {
+ runningTasks.count
+ }
+
var activeCount: Int {
waitingCount + runningCount
}
@@ -63,7 +96,11 @@ nonisolated struct CodexActivitySnapshot: Equatable, Sendable {
activeCount > 0
}
- /// 等待批准 > 运行中 > 最近完成 > 空闲;菜单栏图标、tooltip 和活动卡片共用同一判定。
+ var hasTaskCenterContent: Bool {
+ hasActiveTasks || !recentCompletions.isEmpty || !recentTerminations.isEmpty
+ }
+
+ /// 等待批准 > 运行中 > 最近完成 > 最近终止 > 空闲;菜单栏图标、tooltip 和活动卡片共用同一判定。
var primaryActivity: CodexPrimaryActivity {
if let task = primaryWaitingTask {
return .waiting(task)
@@ -74,6 +111,9 @@ nonisolated struct CodexActivitySnapshot: Equatable, Sendable {
if let completion = mostRecentCompletion {
return .completed(completion, highlighted: isCompletionHighlighted)
}
+ if let termination = mostRecentTermination {
+ return .terminated(termination)
+ }
return .idle
}
}
@@ -83,6 +123,7 @@ nonisolated enum CodexPrimaryActivity: Equatable, Sendable {
case waiting(CodexActivityTaskSnapshot)
case running(CodexActivityTaskSnapshot)
case completed(CodexActivityCompletion, highlighted: Bool)
+ case terminated(CodexActivityTermination)
case idle
}
@@ -106,3 +147,80 @@ nonisolated enum CodexActivityDurationFormat {
return "\(seconds) 秒"
}
}
+
+nonisolated enum CodexActivityDisplayFormat {
+ static func eventText(for task: CodexActivityTaskSnapshot) -> String {
+ switch task.latestEvent {
+ case .promptSubmitted:
+ "正在思考"
+ case .toolStarted:
+ task.toolName.map { "调用工具 \($0)" } ?? "调用工具"
+ case .toolFinished:
+ task.toolName.map { "调用工具 \($0) 完成" } ?? "调用工具完成"
+ case .compactionStarted:
+ "压缩上下文"
+ case .compactionFinished:
+ "上下文压缩完成"
+ case .subagentStarted:
+ "启动子智能体"
+ case .subagentFinished:
+ "子智能体完成"
+ case .approvalRequested:
+ "等待批准"
+ }
+ }
+
+ static func completionRelativeText(_ completedAt: Date, now: Date) -> String {
+ relativeText(since: completedAt, now: now, action: "完成")
+ }
+
+ static func terminationRelativeText(_ terminatedAt: Date, now: Date) -> String {
+ relativeText(since: terminatedAt, now: now, action: "终止")
+ }
+
+ /// 活动卡片和任务中心共用同一份文案片段,各自决定连接符。
+ static func waitingDetailComponents(
+ for task: CodexActivityTaskSnapshot,
+ now: Date
+ ) -> [String] {
+ [
+ task.toolName ?? "等待下一步操作",
+ "已等待 \(CodexActivityDurationFormat.text(for: now.timeIntervalSince(task.stateChangedAt)))"
+ ]
+ }
+
+ static func runningDetailComponents(
+ for task: CodexActivityTaskSnapshot,
+ now: Date
+ ) -> [String] {
+ let duration = if task.showsPreciseDuration, let startedAt = task.startedAt {
+ "已运行 \(CodexActivityDurationFormat.text(for: now.timeIntervalSince(startedAt)))"
+ } else {
+ "正在运行"
+ }
+ return [duration, eventText(for: task)]
+ }
+
+ static func historyDetailComponents(
+ duration: TimeInterval?,
+ relativeText: String
+ ) -> [String] {
+ var components = [String]()
+ if let duration {
+ components.append("耗时 \(CodexActivityDurationFormat.text(for: duration))")
+ }
+ components.append(relativeText)
+ return components
+ }
+
+ private static func relativeText(since date: Date, now: Date, action: String) -> String {
+ let seconds = max(0, Int(now.timeIntervalSince(date)))
+ if seconds < 10 {
+ return "刚刚\(action)"
+ }
+ if seconds < 60 {
+ return "\(seconds) 秒前\(action)"
+ }
+ return "\(seconds / 60) 分钟前\(action)"
+ }
+}
diff --git a/CodexBar/Services/Workflow/CodexActivityMonitor.swift b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
index a691b27..2b8c500 100644
--- a/CodexBar/Services/Workflow/CodexActivityMonitor.swift
+++ b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
@@ -15,8 +15,11 @@ final class CodexActivityMonitor: ObservableObject {
private let sessionLifecycleReader = CodexSessionLifecycleReader()
private let transitionSubject = PassthroughSubject<CodexActivityTransition, Never>()
private var tasks: [CodexActivityTaskKey: CodexActivityTask] = [:]
+ private var pendingTerminalTasks: [CodexActivityTaskKey: PendingTerminalTask] = [:]
private var completions: [CodexActivityCompletion] = []
+ private var terminations: [CodexActivityTermination] = []
private var recentlyCompletedTaskAt: [CodexActivityTaskKey: Date] = [:]
+ private var recentlyTerminatedTaskAt: [CodexActivityTaskKey: Date] = [:]
private var tailReader: HookEventTailReader?
private var tailReaderControlTask: Task<Void, Never>?
private var tailReaderGeneration: UInt64 = 0
@@ -119,9 +122,7 @@ final class CodexActivityMonitor: ObservableObject {
cleanupTask?.cancel()
cleanupTask = nil
cleanupDeadline = nil
- tasks.removeAll()
- completions.removeAll()
- recentlyCompletedTaskAt.removeAll()
+ clearCollectedActivityState()
isBootstrapping = false
sessionTransitionNotBefore = nil
snapshot = .empty
@@ -172,6 +173,7 @@ final class CodexActivityMonitor: ObservableObject {
return
}
let references = tasks.values.compactMap(\.turnReference)
+ + pendingTerminalTasks.values.compactMap(\.task.turnReference)
guard !references.isEmpty else {
return
}
@@ -188,13 +190,32 @@ final class CodexActivityMonitor: ObservableObject {
var transitions: [CodexActivityTransition] = []
for state in states {
let key = CodexActivityTaskKey.turn(session: state.sessionId, turn: state.turnId)
+ if var pending = pendingTerminalTasks[key] {
+ if let startedAt = Self.backfilledStartedAt(for: pending.task, state: state) {
+ pending.task.startedAt = startedAt
+ pendingTerminalTasks[key] = pending
+ }
+
+ guard let terminal = state.terminal else {
+ continue
+ }
+ pendingTerminalTasks.removeValue(forKey: key)
+ resolveTerminal(
+ terminal,
+ task: pending.task,
+ key: key,
+ abortFallback: pending.supersededAt,
+ into: &transitions
+ )
+ didChange = true
+ continue
+ }
+
guard var task = tasks[key] else {
continue
}
- if task.startedAt == nil,
- let startedAt = state.startedAt,
- startedAt <= task.lastActivityAt.addingTimeInterval(1) {
+ if let startedAt = Self.backfilledStartedAt(for: task, state: state) {
task.startedAt = startedAt
tasks[key] = task
didChange = true
@@ -203,31 +224,19 @@ final class CodexActivityMonitor: ObservableObject {
guard let terminal = state.terminal else {
continue
}
- switch terminal {
- case .aborted:
- tasks.removeValue(forKey: key)
- // 中断不是完成,不发布 transition,也不产生绿色状态或通知。
- didChange = true
- case let .completed(completedAt, duration):
- if recentCompletionDate(for: key) != nil {
- // 迟到事件恢复出的任务不能被 rollout 再次完成。
- tasks.removeValue(forKey: key)
- didChange = true
- continue
- }
- guard let completion = completeTask(
- key: key,
- completedAt: completedAt,
- reportedDuration: duration
- ) else {
- continue
- }
- didChange = true
- if let sessionTransitionNotBefore,
- completion.completedAt >= sessionTransitionNotBefore {
- transitions.append(.completed(completion))
- }
+ tasks.removeValue(forKey: key)
+ didChange = true
+ if case .completed = terminal, recentCompletionDate(for: key) != nil {
+ // 迟到事件恢复出的任务不能被 rollout 再次完成。
+ continue
}
+ resolveTerminal(
+ terminal,
+ task: task,
+ key: key,
+ abortFallback: Date(),
+ into: &transitions
+ )
}
if didChange {
@@ -243,9 +252,7 @@ final class CodexActivityMonitor: ObservableObject {
case .bootstrapStart:
isBootstrapping = true
sessionTransitionNotBefore = nil
- tasks.removeAll()
- completions.removeAll()
- recentlyCompletedTaskAt.removeAll()
+ clearCollectedActivityState()
case let .bootstrapEvents(events):
for event in events {
_ = apply(event)
@@ -257,6 +264,7 @@ final class CodexActivityMonitor: ObservableObject {
refreshSessionLifecycleNow()
backfillPromptStartTimesFromHistory()
case let .live(events):
+ let pendingKeysBefore = Set(pendingTerminalTasks.keys)
var transitions: [CodexActivityLiveTransition] = []
for event in events {
if let transition = apply(event) {
@@ -266,6 +274,13 @@ final class CodexActivityMonitor: ObservableObject {
refreshSnapshot(now: Date())
publishLiveTransitions(transitions)
+ if !pendingTerminalTasks.isEmpty {
+ // 只有刚进入终态确认窗口的任务需要重置解析缓存重试定位 rollout;
+ // 窗口期内的后续批次只做即时查询,避免反复递归扫描 sessions。
+ let hasNewPendingTasks = !Set(pendingTerminalTasks.keys)
+ .subtracting(pendingKeysBefore).isEmpty
+ refreshSessionLifecycleNow(resetsResolutionFallbacks: hasNewPendingTasks)
+ }
}
}
@@ -336,34 +351,52 @@ final class CodexActivityMonitor: ObservableObject {
private func startTask(from event: WorkflowHookEvent) {
let key = CodexActivityTaskKey(event: event)
+ let displayID = tasks[key]?.displayID ?? UUID()
if let completedAt = recentCompletionDate(for: key),
event.timestamp <= completedAt {
return
}
+ if let terminatedAt = recentTerminationDate(for: key),
+ event.timestamp <= terminatedAt {
+ return
+ }
if let existing = tasks[key], event.timestamp < existing.lastActivityAt {
return
}
if let sessionId = key.sessionId {
- // 同一 session 的 turn 按顺序执行。新 prompt 代表旧 turn 已被中断,
- // 即使旧 turn 没有 Stop,也不能继续显示为并发运行任务。
+ // 同一 session 的 turn 按顺序执行。新 prompt 让旧 turn 立即退出活动列表,
+ // 但保留短暂终态确认窗口,避免把迟到的正常完成误记为终止。
guard !tasks.values.contains(where: {
$0.key.sessionId == sessionId && $0.lastActivityAt > event.timestamp
}) else {
return
}
+ let supersededTasks = tasks.values.filter {
+ $0.key != key && $0.key.sessionId == sessionId
+ }
+ for task in supersededTasks {
+ pendingTerminalTasks[task.key] = PendingTerminalTask(
+ task: task,
+ supersededAt: event.timestamp,
+ deadline: Date().addingTimeInterval(Self.supersededTerminalGracePeriod)
+ )
+ }
tasks = tasks.filter { taskKey, _ in
taskKey == key || taskKey.sessionId != sessionId
}
}
recentlyCompletedTaskAt.removeValue(forKey: key)
+ recentlyTerminatedTaskAt.removeValue(forKey: key)
if let sessionId = key.sessionId {
// 缺少 turn 的 Stop 会使用 session 键;新 turn 开始后允许该键再次完成。
recentlyCompletedTaskAt.removeValue(forKey: .session(sessionId))
+ recentlyTerminatedTaskAt.removeValue(forKey: .session(sessionId))
}
tasks[key] = CodexActivityTask(
+ displayID: displayID,
key: key,
event: event,
state: .running,
@@ -378,7 +411,9 @@ final class CodexActivityMonitor: ObservableObject {
allowsRecovery: Bool
) {
let eventKey = CodexActivityTaskKey(event: event)
- guard recentCompletionDate(for: eventKey) == nil else {
+ guard recentCompletionDate(for: eventKey) == nil,
+ recentTerminationDate(for: eventKey) == nil,
+ pendingTerminalTasks[eventKey] == nil else {
return
}
@@ -403,6 +438,7 @@ final class CodexActivityMonitor: ObservableObject {
}
tasks[eventKey] = CodexActivityTask(
+ displayID: UUID(),
key: eventKey,
event: event,
state: .running,
@@ -413,7 +449,9 @@ final class CodexActivityMonitor: ObservableObject {
private func waitForApproval(from event: WorkflowHookEvent) -> CodexActivityLiveTransition? {
let eventKey = CodexActivityTaskKey(event: event)
- guard recentCompletionDate(for: eventKey) == nil else {
+ guard recentCompletionDate(for: eventKey) == nil,
+ recentTerminationDate(for: eventKey) == nil,
+ pendingTerminalTasks[eventKey] == nil else {
return nil
}
@@ -437,6 +475,7 @@ final class CodexActivityMonitor: ObservableObject {
}
let task = CodexActivityTask(
+ displayID: UUID(),
key: eventKey,
event: event,
state: .waitingApproval,
@@ -454,6 +493,25 @@ final class CodexActivityMonitor: ObservableObject {
tasks.removeValue(forKey: eventKey)
return nil
}
+ guard recentTerminationDate(for: eventKey) == nil else {
+ return nil
+ }
+
+ if let pending = pendingTerminalTasks[eventKey] {
+ guard event.timestamp >= pending.task.lastActivityAt else {
+ return nil
+ }
+ pendingTerminalTasks.removeValue(forKey: eventKey)
+ let completion = storeResolvedCompletion(
+ pending.task,
+ key: eventKey,
+ completedAt: event.timestamp,
+ reportedDuration: nil,
+ projectName: event.projectDisplayName,
+ modelName: event.modelName
+ )
+ return .completed(completion)
+ }
let matchedKey = matchingTaskKey(for: event)
let task = matchedKey.flatMap { tasks[$0] }
@@ -476,8 +534,8 @@ final class CodexActivityMonitor: ObservableObject {
let duration = task?.preciseDuration(until: event.timestamp)
let completion = storeCompletion(
- key: key,
projectName: event.projectDisplayName ?? task?.projectName,
+ modelName: event.modelName ?? task?.modelName,
completedAt: event.timestamp,
duration: duration
)
@@ -486,29 +544,6 @@ final class CodexActivityMonitor: ObservableObject {
return .completed(completion)
}
- private func completeTask(
- key: CodexActivityTaskKey,
- completedAt: Date,
- reportedDuration: TimeInterval?
- ) -> CodexActivityCompletion? {
- guard let task = tasks.removeValue(forKey: key) else {
- return nil
- }
-
- // rollout 时间戳是整秒,避免因为同一秒内的 Hook 毫秒时间戳而把完成时间记在最后活动之前。
- let recordedCompletedAt = max(completedAt, task.lastActivityAt)
- let duration = reportedDuration ?? task.preciseDuration(until: recordedCompletedAt)
-
- let completion = storeCompletion(
- key: key,
- projectName: task.projectName,
- completedAt: recordedCompletedAt,
- duration: duration
- )
- recordCompletedTask(key, at: recordedCompletedAt)
- return completion
- }
-
/// 精确 turn 失败后回退同 session 最近活动,再回退同项目匿名任务。
private func matchingTaskKey(for event: WorkflowHookEvent) -> CodexActivityTaskKey? {
let exactKey = CodexActivityTaskKey(event: event)
@@ -532,16 +567,17 @@ final class CodexActivityMonitor: ObservableObject {
private func refreshSnapshot(now: Date) {
pruneExpiredState(now: now)
- let waitingTasks = tasks.values.filter { $0.state == .waitingApproval }
- let runningTasks = tasks.values.filter { $0.state == .running }
- let mostRecentCompletion = completions.max { $0.completedAt < $1.completedAt }
+ let waitingTasks = sortedTasks(in: .waitingApproval)
+ let runningTasks = sortedTasks(in: .running)
+ let recentCompletions = completions.sorted(by: Self.recentFirst(\.completedAt, \.id))
+ let recentTerminations = terminations.sorted(by: Self.recentFirst(\.terminatedAt, \.id))
+ let mostRecentCompletion = recentCompletions.first
let newSnapshot = CodexActivitySnapshot(
- primaryWaitingTask: waitingTasks.max(by: { $0.lastActivityAt < $1.lastActivityAt })?.snapshot,
- primaryRunningTask: runningTasks.max(by: { $0.lastActivityAt < $1.lastActivityAt })?.snapshot,
- mostRecentCompletion: mostRecentCompletion,
- waitingCount: waitingTasks.count,
- runningCount: runningTasks.count,
+ waitingTasks: waitingTasks.map(\.snapshot),
+ runningTasks: runningTasks.map(\.snapshot),
+ recentCompletions: recentCompletions,
+ recentTerminations: recentTerminations,
isCompletionHighlighted: mostRecentCompletion.map {
now < $0.completedAt.addingTimeInterval(Self.completionHighlightDuration)
} ?? false
@@ -553,17 +589,42 @@ final class CodexActivityMonitor: ObservableObject {
scheduleNextCleanup(now: now, mostRecentCompletion: mostRecentCompletion)
}
+ private func sortedTasks(in state: CodexActivityTaskState) -> [CodexActivityTask] {
+ tasks.values
+ .filter { $0.state == state }
+ .sorted(by: Self.recentFirst(\.lastActivityAt, \.displayID))
+ }
+
+ /// 时间相同再按 UUID 字符串排序(Swift sort 不稳定),保证快照对 SwiftUI diff 稳定。
+ private static func recentFirst<Element>(
+ _ date: KeyPath<Element, Date>,
+ _ id: KeyPath<Element, UUID>
+ ) -> (Element, Element) -> Bool {
+ { lhs, rhs in
+ if lhs[keyPath: date] != rhs[keyPath: date] {
+ return lhs[keyPath: date] > rhs[keyPath: date]
+ }
+ return lhs[keyPath: id].uuidString < rhs[keyPath: id].uuidString
+ }
+ }
+
private func pruneExpiredState(now: Date) {
+ finalizeExpiredPendingTerminalTasks(now: now)
+
let activityCutoff = now.addingTimeInterval(-Self.activityRetention)
tasks = tasks.filter { $0.value.lastActivityAt > activityCutoff }
- let completionCutoff = now.addingTimeInterval(-Self.completionRetention)
- completions.removeAll { $0.completedAt <= completionCutoff }
+ let historyCutoff = now.addingTimeInterval(-Self.recentHistoryRetention)
+ completions.removeAll { $0.completedAt <= historyCutoff }
+ terminations.removeAll { $0.terminatedAt <= historyCutoff }
let completedTaskCutoff = now.addingTimeInterval(-Self.completedTaskRetention)
recentlyCompletedTaskAt = recentlyCompletedTaskAt.filter {
$0.value > completedTaskCutoff
}
+ recentlyTerminatedTaskAt = recentlyTerminatedTaskAt.filter {
+ $0.value > completedTaskCutoff
+ }
}
private func scheduleNextCleanup(
@@ -574,11 +635,18 @@ final class CodexActivityMonitor: ObservableObject {
$0.lastActivityAt.addingTimeInterval(Self.activityRetention)
}
deadlines.append(contentsOf: completions.map {
- $0.completedAt.addingTimeInterval(Self.completionRetention)
+ $0.completedAt.addingTimeInterval(Self.recentHistoryRetention)
})
+ deadlines.append(contentsOf: terminations.map {
+ $0.terminatedAt.addingTimeInterval(Self.recentHistoryRetention)
+ })
+ deadlines.append(contentsOf: pendingTerminalTasks.values.map(\.deadline))
deadlines.append(contentsOf: recentlyCompletedTaskAt.values.map {
$0.addingTimeInterval(Self.completedTaskRetention)
})
+ deadlines.append(contentsOf: recentlyTerminatedTaskAt.values.map {
+ $0.addingTimeInterval(Self.completedTaskRetention)
+ })
if let mostRecentCompletion {
let highlightDeadline = mostRecentCompletion.completedAt
.addingTimeInterval(Self.completionHighlightDuration)
@@ -610,56 +678,192 @@ final class CodexActivityMonitor: ObservableObject {
}
}
- private static let completionHighlightDuration: TimeInterval = 20
- private static let completionRetention: TimeInterval = 5 * 60
+ private static let completionHighlightDuration: TimeInterval = 30
+ private static let recentHistoryRetention: TimeInterval = 10 * 60
private static let completedTaskRetention: TimeInterval = 24 * 60 * 60
private static let activityRetention: TimeInterval = 24 * 60 * 60
- private static let sessionLifecyclePollInterval: TimeInterval = 2
+ private static let supersededTerminalGracePeriod: TimeInterval = 5
+ private static let sessionLifecyclePollInterval: TimeInterval = 1
}
private extension CodexActivityMonitor {
- func storeCompletion(
+ /// rollout 终态归类的唯一入口;活动任务和等待终态确认任务只有 abort 兜底时间不同。
+ /// 终止记录只供任务中心展示,不发布 transition,也不产生绿色状态或通知。
+ func resolveTerminal(
+ _ terminal: CodexSessionTaskTerminalState,
+ task: CodexActivityTask,
key: CodexActivityTaskKey,
+ abortFallback: Date,
+ into transitions: inout [CodexActivityTransition]
+ ) {
+ switch terminal {
+ case let .aborted(reportedAt):
+ let terminatedAt = max(reportedAt ?? abortFallback, task.lastActivityAt)
+ storeTermination(task, at: terminatedAt, includesDuration: reportedAt != nil)
+ recordTerminatedTask(key, at: terminatedAt)
+ case let .completed(completedAt, duration):
+ let completion = storeResolvedCompletion(
+ task,
+ key: key,
+ completedAt: completedAt,
+ reportedDuration: duration
+ )
+ if let sessionTransitionNotBefore,
+ completion.completedAt >= sessionTransitionNotBefore {
+ transitions.append(.completed(completion))
+ }
+ }
+ }
+
+ static func backfilledStartedAt(
+ for task: CodexActivityTask,
+ state: CodexSessionTaskLifecycleState
+ ) -> Date? {
+ guard task.startedAt == nil,
+ let startedAt = state.startedAt,
+ startedAt <= task.lastActivityAt.addingTimeInterval(1) else {
+ return nil
+ }
+ return startedAt
+ }
+
+ func storeResolvedCompletion(
+ _ task: CodexActivityTask,
+ key: CodexActivityTaskKey,
+ completedAt: Date,
+ reportedDuration: TimeInterval?,
+ projectName: String? = nil,
+ modelName: String? = nil
+ ) -> CodexActivityCompletion {
+ // rollout 时间戳是整秒,避免因为同一秒内的 Hook 毫秒时间戳而把完成时间记在最后活动之前。
+ let recordedCompletedAt = max(completedAt, task.lastActivityAt)
+ let completion = storeCompletion(
+ projectName: projectName ?? task.projectName,
+ modelName: modelName ?? task.modelName,
+ completedAt: recordedCompletedAt,
+ duration: reportedDuration ?? task.preciseDuration(until: recordedCompletedAt)
+ )
+ recordCompletedTask(key, at: recordedCompletedAt)
+ return completion
+ }
+
+ func storeCompletion(
projectName: String?,
+ modelName: String?,
completedAt: Date,
duration: TimeInterval?
) -> CodexActivityCompletion {
let completion = CodexActivityCompletion(
- id: "\(key.identifier)|\(Int64((completedAt.timeIntervalSince1970 * 1000).rounded()))",
+ id: UUID(),
projectName: projectName,
+ modelName: modelName,
completedAt: completedAt,
duration: duration
)
- completions.removeAll { $0.id == completion.id }
completions.append(completion)
return completion
}
+ func storeTermination(
+ _ task: CodexActivityTask,
+ at terminatedAt: Date,
+ includesDuration: Bool
+ ) {
+ let termination = CodexActivityTermination(
+ id: UUID(),
+ projectName: task.projectName,
+ modelName: task.modelName,
+ terminatedAt: terminatedAt,
+ duration: includesDuration ? task.preciseDuration(until: terminatedAt) : nil
+ )
+ terminations.append(termination)
+ }
+
func recentCompletionDate(
for key: CodexActivityTaskKey,
now: Date = Date()
) -> Date? {
- guard let completedAt = recentlyCompletedTaskAt[key] else {
+ Self.recentTerminalDate(
+ for: key,
+ storedIn: &recentlyCompletedTaskAt,
+ now: now
+ )
+ }
+
+ func recentTerminationDate(
+ for key: CodexActivityTaskKey,
+ now: Date = Date()
+ ) -> Date? {
+ Self.recentTerminalDate(
+ for: key,
+ storedIn: &recentlyTerminatedTaskAt,
+ now: now
+ )
+ }
+
+ func recordCompletedTask(_ key: CodexActivityTaskKey, at completedAt: Date) {
+ Self.recordTerminalTask(
+ key,
+ at: completedAt,
+ storedIn: &recentlyCompletedTaskAt
+ )
+ }
+
+ func recordTerminatedTask(_ key: CodexActivityTaskKey, at terminatedAt: Date) {
+ Self.recordTerminalTask(
+ key,
+ at: terminatedAt,
+ storedIn: &recentlyTerminatedTaskAt
+ )
+ }
+
+ func clearCollectedActivityState() {
+ tasks.removeAll()
+ pendingTerminalTasks.removeAll()
+ completions.removeAll()
+ terminations.removeAll()
+ recentlyCompletedTaskAt.removeAll()
+ recentlyTerminatedTaskAt.removeAll()
+ }
+
+ static func recentTerminalDate(
+ for key: CodexActivityTaskKey,
+ storedIn dates: inout [CodexActivityTaskKey: Date],
+ now: Date
+ ) -> Date? {
+ guard let date = dates[key] else {
return nil
}
- guard completedAt > now.addingTimeInterval(-Self.completedTaskRetention) else {
- recentlyCompletedTaskAt.removeValue(forKey: key)
+ guard date > now.addingTimeInterval(-completedTaskRetention) else {
+ dates.removeValue(forKey: key)
return nil
}
- return completedAt
+ return date
}
- func recordCompletedTask(_ key: CodexActivityTaskKey, at completedAt: Date) {
- recentlyCompletedTaskAt[key] = max(
- recentlyCompletedTaskAt[key] ?? .distantPast,
- completedAt
- )
+ static func recordTerminalTask(
+ _ key: CodexActivityTaskKey,
+ at date: Date,
+ storedIn dates: inout [CodexActivityTaskKey: Date]
+ ) {
+ dates[key] = max(dates[key] ?? .distantPast, date)
if let sessionId = key.sessionId {
let sessionKey = CodexActivityTaskKey.session(sessionId)
- recentlyCompletedTaskAt[sessionKey] = max(
- recentlyCompletedTaskAt[sessionKey] ?? .distantPast,
- completedAt
- )
+ dates[sessionKey] = max(dates[sessionKey] ?? .distantPast, date)
+ }
+ }
+
+ func finalizeExpiredPendingTerminalTasks(now: Date) {
+ let expiredKeys = pendingTerminalTasks.compactMap { key, pending in
+ pending.deadline <= now ? key : nil
+ }
+ for key in expiredKeys {
+ guard let pending = pendingTerminalTasks.removeValue(forKey: key) else {
+ continue
+ }
+ let terminatedAt = max(pending.supersededAt, pending.task.lastActivityAt)
+ storeTermination(pending.task, at: terminatedAt, includesDuration: true)
+ recordTerminatedTask(key, at: terminatedAt)
}
}
@@ -671,7 +875,7 @@ private extension CodexActivityMonitor {
}
}
- var publishedCompletionIDs = Set<String>()
+ var publishedCompletionIDs = Set<UUID>()
for (index, transition) in transitions.enumerated() {
switch transition {
case let .waitingApproval(key):
@@ -720,14 +924,6 @@ private enum CodexActivityTaskKey: Hashable {
return false
}
- var identifier: String {
- switch self {
- case let .turn(session, turn): "turn|\(session)|\(turn)"
- case let .session(session): "session|\(session)"
- case let .anonymous(project): "project|\(project)"
- }
- }
-
static func projectIdentifier(_ project: String?) -> String {
project ?? "__codex__"
}
@@ -743,7 +939,14 @@ private enum CodexActivityTaskState {
case waitingApproval
}
+private struct PendingTerminalTask {
+ var task: CodexActivityTask
+ let supersededAt: Date
+ let deadline: Date
+}
+
private struct CodexActivityTask {
+ let displayID: UUID
let key: CodexActivityTaskKey
var state: CodexActivityTaskState
var latestEvent: CodexActivityEvent
@@ -755,12 +958,14 @@ private struct CodexActivityTask {
var lastActivityAt: Date
init(
+ displayID: UUID,
key: CodexActivityTaskKey,
event: WorkflowHookEvent,
state: CodexActivityTaskState,
latestEvent: CodexActivityEvent,
startedAt: Date?
) {
+ self.displayID = displayID
self.key = key
self.state = state
self.latestEvent = latestEvent
@@ -786,6 +991,7 @@ private struct CodexActivityTask {
var snapshot: CodexActivityTaskSnapshot {
CodexActivityTaskSnapshot(
+ id: displayID,
latestEvent: latestEvent,
projectName: projectName,
modelName: modelName,
diff --git a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
index 636ad0a..1870b87 100644
--- a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
+++ b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
@@ -231,6 +231,7 @@ private nonisolated struct SessionFileCursor {
}
private nonisolated struct CodexSessionLifecycleEnvelope: Decodable {
+ let timestamp: String?
let type: String
let payload: CodexSessionLifecyclePayload?
@@ -257,7 +258,10 @@ private nonisolated struct CodexSessionLifecycleEnvelope: Decodable {
}
return SessionLifecycleEvent(turnId: turnId, change: .completed(at: completedAt, duration: duration))
case "turn_aborted":
- return SessionLifecycleEvent(turnId: turnId, change: .aborted)
+ return SessionLifecycleEvent(
+ turnId: turnId,
+ change: .aborted(at: timestamp.flatMap(CodexDateFormat.iso8601Date))
+ )
default:
return nil
}
@@ -295,7 +299,7 @@ private nonisolated struct SessionLifecycleEvent {
private nonisolated enum SessionLifecycleChange {
case started(at: Date)
case completed(at: Date, duration: TimeInterval?)
- case aborted
+ case aborted(at: Date?)
}
private nonisolated struct SessionTurnLifecycle {
@@ -312,8 +316,8 @@ private nonisolated struct SessionTurnLifecycle {
}
case let .completed(at, duration):
terminal = .completed(at: at, duration: duration)
- case .aborted:
- terminal = .aborted
+ case let .aborted(at):
+ terminal = .aborted(at: at)
}
}
}
@@ -327,5 +331,5 @@ nonisolated struct CodexSessionTaskLifecycleState: Sendable {
nonisolated enum CodexSessionTaskTerminalState: Sendable {
case completed(at: Date, duration: TimeInterval?)
- case aborted
+ case aborted(at: Date?)
}
diff --git a/CodexBar/Views/Menu/CodexActivityCard.swift b/CodexBar/Views/Menu/CodexActivityCard.swift
index f5d40be..1e2efa5 100644
--- a/CodexBar/Views/Menu/CodexActivityCard.swift
+++ b/CodexBar/Views/Menu/CodexActivityCard.swift
@@ -4,8 +4,34 @@ import SwiftUI
struct CodexActivityCard: View {
let snapshot: CodexActivitySnapshot
let isTimelineActive: Bool
+ let showsUnavailableState: Bool
+ let isTaskCenterPresented: Bool
+ let onTaskCenterTap: (CGRect?) -> Void
+ @State private var frameProvider = ScreenFrameProvider()
+ @State private var isHovered = false
var body: some View {
+ Group {
+ if snapshot.hasTaskCenterContent {
+ Button {
+ onTaskCenterTap(frameProvider.currentScreenFrame())
+ } label: {
+ timelineContent
+ }
+ .buttonStyle(ActivityCardButtonStyle())
+ .contentShape(Rectangle())
+ } else {
+ timelineContent
+ }
+ }
+ .background {
+ ScreenFrameReader(provider: frameProvider)
+ }
+ .onHover { isHovered = $0 }
+ }
+
+ @ViewBuilder
+ private var timelineContent: some View {
if isTimelineActive, needsPerSecondUpdates {
TimelineView(.periodic(from: .now, by: 1)) { timeline in
card(now: timeline.date)
@@ -31,6 +57,7 @@ struct CodexActivityCard: View {
VStack(alignment: .leading, spacing: 3) {
Text(content.title)
.font(.caption.weight(.semibold))
+ .foregroundStyle(Color.codexLabel)
.lineLimit(1)
.truncationMode(.middle)
@@ -53,21 +80,28 @@ struct CodexActivityCard: View {
.padding(.vertical, 3)
.background(.secondary.opacity(0.12), in: Capsule())
.help("另有 \(content.otherTaskCount) 个任务")
- .accessibilityLabel("另有 \(content.otherTaskCount) 个任务")
}
}
.padding(.horizontal, MenuMetrics.panelPadding)
.frame(maxWidth: .infinity, minHeight: Metrics.height, maxHeight: Metrics.height)
.liquidGlassSurface(cornerRadius: MenuMetrics.panelCornerRadius)
+ .overlay {
+ RoundedRectangle(cornerRadius: MenuMetrics.panelCornerRadius, style: .continuous)
+ .strokeBorder(
+ isTaskCenterPresented
+ ? Color.accentColor.opacity(0.55)
+ : Color.primary.opacity(isHovered && snapshot.hasTaskCenterContent ? 0.14 : 0),
+ lineWidth: 1
+ )
+ .animation(.codexStatus, value: isHovered)
+ .animation(.codexStatus, value: isTaskCenterPresented)
+ }
}
private func content(at now: Date) -> ActivityCardContent {
switch snapshot.primaryActivity {
case let .waiting(task):
- let details = [
- task.toolName ?? "等待下一步操作",
- "已等待 \(CodexActivityDurationFormat.text(for: now.timeIntervalSince(task.stateChangedAt)))"
- ]
+ let details = CodexActivityDisplayFormat.waitingDetailComponents(for: task, now: now)
return ActivityCardContent(
symbolName: "hand.raised.fill",
tint: .orange,
@@ -82,13 +116,7 @@ struct CodexActivityCard: View {
}
titles.append(task.projectName ?? "Codex")
- var details: [String] = []
- if task.showsPreciseDuration, let startedAt = task.startedAt {
- details.append("已运行 \(CodexActivityDurationFormat.text(for: now.timeIntervalSince(startedAt)))")
- } else {
- details.append("正在运行")
- }
- details.append(Self.eventText(for: task))
+ let details = CodexActivityDisplayFormat.runningDetailComponents(for: task, now: now)
return ActivityCardContent(
symbolName: "bolt.fill",
tint: .blue,
@@ -97,11 +125,10 @@ struct CodexActivityCard: View {
otherTaskCount: otherTaskCount
)
case let .completed(completion, _):
- var details: [String] = []
- if let duration = completion.duration {
- details.append("耗时 \(CodexActivityDurationFormat.text(for: duration))")
- }
- details.append(Self.completionRelativeText(completion.completedAt, now: now))
+ let details = CodexActivityDisplayFormat.historyDetailComponents(
+ duration: completion.duration,
+ relativeText: CodexActivityDisplayFormat.completionRelativeText(completion.completedAt, now: now)
+ )
return ActivityCardContent(
symbolName: "checkmark.circle.fill",
tint: .green,
@@ -109,11 +136,23 @@ struct CodexActivityCard: View {
detail: details.joined(separator: " • "),
otherTaskCount: 0
)
+ case let .terminated(termination):
+ let details = CodexActivityDisplayFormat.historyDetailComponents(
+ duration: termination.duration,
+ relativeText: CodexActivityDisplayFormat.terminationRelativeText(termination.terminatedAt, now: now)
+ )
+ return ActivityCardContent(
+ symbolName: "xmark.circle.fill",
+ tint: .secondary,
+ title: termination.projectName ?? "Codex 任务已终止",
+ detail: details.joined(separator: " • "),
+ otherTaskCount: 0
+ )
case .idle:
return ActivityCardContent(
symbolName: "waveform.path",
tint: .secondary,
- title: "暂无 Codex 活动",
+ title: showsUnavailableState ? "暂无数据" : "暂无 Codex 活动",
detail: nil,
otherTaskCount: 0
)
@@ -124,43 +163,18 @@ struct CodexActivityCard: View {
max(0, snapshot.activeCount - 1)
}
- private static func eventText(for task: CodexActivityTaskSnapshot) -> String {
- switch task.latestEvent {
- case .promptSubmitted:
- "正在思考"
- case .toolStarted:
- task.toolName.map { "调用工具 \($0)" } ?? "调用工具"
- case .toolFinished:
- task.toolName.map { "调用工具 \($0) 完成" } ?? "调用工具完成"
- case .compactionStarted:
- "压缩上下文"
- case .compactionFinished:
- "上下文压缩完成"
- case .subagentStarted:
- "启动子智能体"
- case .subagentFinished:
- "子智能体完成"
- case .approvalRequested:
- "等待批准"
- }
- }
-
- private static func completionRelativeText(_ completedAt: Date, now: Date) -> String {
- let seconds = max(0, Int(now.timeIntervalSince(completedAt)))
- if seconds < 10 {
- return "刚刚完成"
- }
- if seconds < 60 {
- return "\(seconds) 秒前完成"
- }
- return "\(seconds / 60) 分钟前完成"
- }
-
private enum Metrics {
static let height: CGFloat = 58
}
}
+/// 卡片自行处理 hover/选中描边,按钮样式不再修改 label 的前景色或透明度。
+private struct ActivityCardButtonStyle: ButtonStyle {
+ func makeBody(configuration: Configuration) -> some View {
+ configuration.label
+ }
+}
+
private struct ActivityCardContent {
let symbolName: String
let tint: Color
diff --git a/CodexBar/Views/Menu/CodexActivityCenterView.swift b/CodexBar/Views/Menu/CodexActivityCenterView.swift
new file mode 100644
index 0000000..1bc6ee8
--- /dev/null
+++ b/CodexBar/Views/Menu/CodexActivityCenterView.swift
@@ -0,0 +1,339 @@
+import Combine
+import SwiftUI
+
+/// 活动卡片与任务中心共享的显隐状态,控制选中外观和逐秒时间更新。
+@MainActor
+final class CodexActivityCenterPresentationState: ObservableObject {
+ @Published var isPresented = false
+}
+
+/// 点击活动卡片时传给 AppKit 控制器的定位信息。
+nonisolated struct CodexActivityCenterPanelContext: Equatable {
+ let alignmentScreenFrame: CGRect?
+ let preferredSide: UsageHeatmapDetailSide
+}
+
+/// 并发任务中心,实时展示全部等待、运行、最近完成和最近终止任务。
+struct CodexActivityCenterView: View {
+ @ObservedObject var activityMonitor: CodexActivityMonitor
+ @ObservedObject var presentationState: CodexActivityCenterPresentationState
+ let panelSize: CGSize
+
+ var body: some View {
+ Group {
+ if presentationState.isPresented, needsPerSecondUpdates {
+ TimelineView(.periodic(from: .now, by: 1)) { timeline in
+ content(now: timeline.date)
+ }
+ } else {
+ content(now: Date())
+ }
+ }
+ .frame(width: panelSize.width, height: panelSize.height, alignment: .topLeading)
+ .sidePanelChrome(cornerRadius: Metrics.cornerRadius)
+ .animation(.codexStatus, value: activityMonitor.snapshot)
+ }
+
+ static var initialPanelSize: CGSize {
+ CGSize(width: Metrics.panelWidth, height: Metrics.preferredPanelHeight)
+ }
+
+ static var panelCornerRadius: CGFloat {
+ Metrics.cornerRadius
+ }
+
+ static func panelSize(
+ maximumHeight: CGFloat,
+ snapshot: CodexActivitySnapshot
+ ) -> CGSize {
+ let sectionCounts = [
+ snapshot.waitingTasks.count,
+ snapshot.runningTasks.count,
+ snapshot.recentCompletions.count,
+ snapshot.recentTerminations.count
+ ].filter { $0 > 0 }
+ let contentHeight = Metrics.headerHeight
+ + Metrics.dividerHeight
+ + Metrics.verticalPadding * 2
+ + CGFloat(sectionCounts.count) * Metrics.sectionHeaderHeight
+ + CGFloat(sectionCounts.reduce(0, +)) * (Metrics.rowHeight + Metrics.rowSpacing)
+ + CGFloat(max(0, sectionCounts.count - 1)) * Metrics.sectionSpacing
+ let desiredHeight = max(Metrics.minimumPanelHeight, contentHeight)
+
+ return CGSize(
+ width: Metrics.panelWidth,
+ height: min(maximumHeight, desiredHeight)
+ )
+ }
+
+ private var needsPerSecondUpdates: Bool {
+ activityMonitor.snapshot.hasTaskCenterContent
+ }
+
+ private func content(now: Date) -> some View {
+ VStack(alignment: .leading, spacing: 0) {
+ header
+
+ LiquidGlassDivider()
+
+ ScrollView(.vertical) {
+ LazyVStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
+ if !activityMonitor.snapshot.waitingTasks.isEmpty {
+ taskSection(
+ title: "等待确认",
+ symbolName: "hand.raised.fill",
+ tint: .orange,
+ tasks: activityMonitor.snapshot.waitingTasks,
+ now: now,
+ isWaiting: true
+ )
+ }
+
+ if !activityMonitor.snapshot.runningTasks.isEmpty {
+ taskSection(
+ title: "运行中",
+ symbolName: "bolt.fill",
+ tint: .blue,
+ tasks: activityMonitor.snapshot.runningTasks,
+ now: now,
+ isWaiting: false
+ )
+ }
+
+ if !activityMonitor.snapshot.recentCompletions.isEmpty {
+ completionSection(now: now)
+ }
+
+ if !activityMonitor.snapshot.recentTerminations.isEmpty {
+ terminationSection(now: now)
+ }
+ }
+ .padding(.horizontal, Metrics.horizontalPadding)
+ .padding(.vertical, Metrics.verticalPadding)
+ }
+ .scrollIndicators(.never)
+ }
+ }
+
+ private var header: some View {
+ HStack(alignment: .firstTextBaseline, spacing: 10) {
+ Text("任务中心")
+ .font(.caption.weight(.semibold))
+
+ Spacer(minLength: 8)
+
+ Text(headerSummary)
+ .font(.caption2.monospacedDigit())
+ .foregroundStyle(.secondary)
+ .lineLimit(1)
+ }
+ .padding(.horizontal, Metrics.horizontalPadding)
+ .frame(height: Metrics.headerHeight)
+ }
+
+ private var headerSummary: String {
+ let snapshot = activityMonitor.snapshot
+ var components = [String]()
+ if snapshot.waitingCount > 0 {
+ components.append("等待 \(snapshot.waitingCount)")
+ }
+ if snapshot.runningCount > 0 {
+ components.append("运行 \(snapshot.runningCount)")
+ }
+ if snapshot.activeCount == 0 {
+ if !snapshot.recentCompletions.isEmpty {
+ components.append("最近完成 \(snapshot.recentCompletions.count)")
+ }
+ if !snapshot.recentTerminations.isEmpty {
+ components.append("最近终止 \(snapshot.recentTerminations.count)")
+ }
+ }
+ return components.joined(separator: " · ")
+ }
+
+ private func taskSection(
+ title: String,
+ symbolName: String,
+ tint: Color,
+ tasks: [CodexActivityTaskSnapshot],
+ now: Date,
+ isWaiting: Bool
+ ) -> some View {
+ section(title: title, count: tasks.count) {
+ ForEach(tasks) { task in
+ taskRow(
+ task,
+ symbolName: symbolName,
+ tint: tint,
+ now: now,
+ isWaiting: isWaiting
+ )
+ }
+ }
+ }
+
+ private func completionSection(now: Date) -> some View {
+ section(title: "最近完成", count: activityMonitor.snapshot.recentCompletions.count) {
+ ForEach(activityMonitor.snapshot.recentCompletions) { completion in
+ completionRow(completion, now: now)
+ }
+ }
+ }
+
+ private func terminationSection(now: Date) -> some View {
+ section(title: "最近终止", count: activityMonitor.snapshot.recentTerminations.count) {
+ ForEach(activityMonitor.snapshot.recentTerminations) { termination in
+ terminationRow(termination, now: now)
+ }
+ }
+ }
+
+ private func section(
+ title: String,
+ count: Int,
+ @ViewBuilder content: () -> some View
+ ) -> some View {
+ VStack(alignment: .leading, spacing: Metrics.rowSpacing) {
+ HStack(spacing: 5) {
+ Text(title)
+ .font(.caption2.weight(.semibold))
+ .foregroundStyle(.secondary)
+
+ Text("\(count)")
+ .font(.caption2.monospacedDigit())
+ .foregroundStyle(.tertiary)
+ }
+
+ content()
+ }
+ }
+
+ private func taskRow(
+ _ task: CodexActivityTaskSnapshot,
+ symbolName: String,
+ tint: Color,
+ now: Date,
+ isWaiting: Bool
+ ) -> some View {
+ row(
+ symbolName: symbolName,
+ tint: tint,
+ projectName: task.projectName,
+ modelName: task.modelName,
+ detail: taskDetail(task, now: now, isWaiting: isWaiting)
+ )
+ }
+
+ private func completionRow(_ completion: CodexActivityCompletion, now: Date) -> some View {
+ row(
+ symbolName: "checkmark.circle.fill",
+ tint: .green,
+ projectName: completion.projectName,
+ modelName: completion.modelName,
+ detail: historyDetail(
+ duration: completion.duration,
+ relativeText: CodexActivityDisplayFormat.completionRelativeText(
+ completion.completedAt,
+ now: now
+ )
+ )
+ )
+ }
+
+ private func terminationRow(_ termination: CodexActivityTermination, now: Date) -> some View {
+ row(
+ symbolName: "xmark.circle.fill",
+ tint: .secondary,
+ projectName: termination.projectName,
+ modelName: termination.modelName,
+ detail: historyDetail(
+ duration: termination.duration,
+ relativeText: CodexActivityDisplayFormat.terminationRelativeText(
+ termination.terminatedAt,
+ now: now
+ )
+ )
+ )
+ }
+
+ private func row(
+ symbolName: String,
+ tint: Color,
+ projectName: String?,
+ modelName: String?,
+ detail: String
+ ) -> some View {
+ HStack(alignment: .top, spacing: 9) {
+ Image(systemName: symbolName)
+ .font(.system(size: 11, weight: .semibold))
+ .foregroundStyle(tint)
+ .frame(width: Metrics.symbolWidth, height: Metrics.titleLineHeight)
+
+ VStack(alignment: .leading, spacing: 3) {
+ titleLine(projectName: projectName, modelName: modelName)
+
+ Text(detail)
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ .lineLimit(1)
+ .truncationMode(.tail)
+ }
+ }
+ .frame(maxWidth: .infinity, alignment: .leading)
+ }
+
+ private func titleLine(projectName: String?, modelName: String?) -> some View {
+ HStack(alignment: .firstTextBaseline, spacing: 8) {
+ Text(projectName ?? "Codex")
+ .font(.caption.weight(.semibold))
+ .lineLimit(1)
+ .truncationMode(.middle)
+
+ Spacer(minLength: 4)
+
+ if let modelName {
+ Text(modelName)
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ .lineLimit(1)
+ .truncationMode(.middle)
+ }
+ }
+ .frame(height: Metrics.titleLineHeight)
+ }
+
+ private func taskDetail(
+ _ task: CodexActivityTaskSnapshot,
+ now: Date,
+ isWaiting: Bool
+ ) -> String {
+ let components = isWaiting
+ ? CodexActivityDisplayFormat.waitingDetailComponents(for: task, now: now)
+ : CodexActivityDisplayFormat.runningDetailComponents(for: task, now: now)
+ return components.joined(separator: " · ")
+ }
+
+ private func historyDetail(duration: TimeInterval?, relativeText: String) -> String {
+ CodexActivityDisplayFormat.historyDetailComponents(
+ duration: duration,
+ relativeText: relativeText
+ ).joined(separator: " · ")
+ }
+
+ private enum Metrics {
+ static let panelWidth: CGFloat = 312
+ static let preferredPanelHeight: CGFloat = 360
+ static let minimumPanelHeight: CGFloat = 180
+ static let headerHeight: CGFloat = 42
+ static let dividerHeight: CGFloat = 1
+ static let horizontalPadding: CGFloat = 12
+ static let verticalPadding: CGFloat = 10
+ static let sectionSpacing: CGFloat = 14
+ static let sectionHeaderHeight: CGFloat = 14
+ static let rowSpacing: CGFloat = 9
+ static let rowHeight: CGFloat = 33
+ static let symbolWidth: CGFloat = 16
+ static let titleLineHeight: CGFloat = 16
+ static let cornerRadius: CGFloat = 12
+ }
+}
diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swift
index 9332bdd..adfc9cd 100644
--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift
+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift
@@ -17,8 +17,10 @@ struct CodexStatusMenuView: View {
@ObservedObject var activityMonitor: CodexActivityMonitor
@ObservedObject var syncSettings: WorkflowSyncSettings
@ObservedObject var menuSurfaceVisibility: MenuSurfaceVisibilityState
+ @ObservedObject var activityCenterPresentationState: CodexActivityCenterPresentationState
let onUsageHeatmapHoverChange: (UsageHeatmapHoverContext?) -> Void
let onResetCreditsTap: (ResetCreditsPanelContext) -> Void
+ let onActivityCenterTap: (CodexActivityCenterPanelContext) -> Void
@EnvironmentObject private var appUpdater: AppUpdater
var body: some View {
@@ -74,9 +76,20 @@ private extension CodexStatusMenuView {
@ViewBuilder
var activityCard: some View {
if codexHookSettings.isEnabled {
+ let hasQuotaSnapshot = viewModel.snapshot != nil
CodexActivityCard(
- snapshot: activityMonitor.snapshot,
- isTimelineActive: menuSurfaceVisibility.isVisible
+ snapshot: hasQuotaSnapshot ? activityMonitor.snapshot : .empty,
+ isTimelineActive: menuSurfaceVisibility.isVisible,
+ showsUnavailableState: !hasQuotaSnapshot,
+ isTaskCenterPresented: activityCenterPresentationState.isPresented,
+ onTaskCenterTap: { alignmentScreenFrame in
+ onActivityCenterTap(
+ CodexActivityCenterPanelContext(
+ alignmentScreenFrame: alignmentScreenFrame,
+ preferredSide: .right
+ )
+ )
+ }
)
}
}
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
index 49909f6..2741811 100644
--- a/Docs/CodexHook.md
+++ b/Docs/CodexHook.md
@@ -141,22 +141,22 @@ Hook 数据目录:
Codex Hook 事件可能缺少起点、结束或中断信号。`CodexSessionLifecycleReader` 会补充读取本机 Codex session rollout:
-- 只检查 monitor 内仍有运行或等待任务、并且同时具有 session ID 和 turn ID 的活跃项,不持续扫描所有历史会话。
+- 只检查 monitor 内仍在运行、等待批准或等待终态确认,并且同时具有 session ID 和 turn ID 的任务,不持续扫描所有历史会话。
- 优先在 `~/.codex/sessions/YYYY/MM/DD/` 和 `~/.codex/archived_sessions/` 按 session ID 定位对应 rollout;这些便宜目录允许每 10 秒重试。resume 的旧 session 找不到时,每个活跃生命周期只递归 `sessions` 一次并保留负缓存;session 重新活跃、缓存文件消失或 Mac 唤醒时重置递归资格。
-- 初次从文件末尾最多读取 512 KB,之后每 2 秒按 byte offset 增量读取,保留半行并检测截断或替换。只解出顶层 `type`、`payload.type`、`payload.turn_id`、`started_at`、`completed_at` 和 `duration_ms`;不提取、保存或展示提示词、回复、推理或工具内容。
+- 初次从文件末尾最多读取 512 KB,之后每 1 秒按 byte offset 增量读取,保留半行并检测截断或替换。只解出顶层 `type`、`payload.type`、`payload.turn_id`、`started_at`、`completed_at` 和 `duration_ms`;不提取、保存或展示提示词、回复、推理或工具内容。
- `event_msg / task_started` 只为缺少 Hook Prompt 起点的精确 turn 回填开始时间;`task_complete` 补齐缺失的 Hook `Stop`,使用 `completed_at` 和 `duration_ms` 生成完成状态。初始恢复只更新状态而不回放通知或触觉反馈;运行期间新收到的 `task_complete` 可发布一次完成 transition,后到的 Hook `Stop` 会被去重。定时轮询和唤醒/恢复触发的即时查询都绑定启动时的 reader generation,并在跨 actor 等待前后校验,旧 generation 的迟到 rollout 结果不会写入新状态。
-- `event_msg / turn_aborted` 静默移除对应任务,不生成完成记录、绿色状态、通知或触觉反馈。文件不存在、无法读取、格式变化或缺少精确 ID 时保留原 Hook 状态,最终仍由后续 prompt、Stop、Hook 关闭或 24 小时过期兜底。
+- `event_msg / turn_aborted` 移除对应任务,并在任务中心生成保留 10 分钟的灰色最近终止记录;优先使用 rollout 行时间,缺失时活跃任务使用检测时间、等待终态确认任务使用被新 Prompt 替代的时间,且都不猜测耗时。不生成完成记录、绿色状态、通知或触觉反馈。文件不存在、无法读取、格式变化或缺少精确 ID 时保留原 Hook 状态,最终仍由后续 prompt、Stop、Hook 关闭或 24 小时过期兜底。
任务状态机规则:
- 任务键优先使用 `session + turn`,缺少 turn 时使用 session;两者都缺少时按项目名归入匿名任务。匿名任务以及缺少起点的恢复任务不展示精确总耗时。
- `UserPromptSubmit` 创建运行任务;同一 session 收到新 prompt 时,旧 turn 即使缺少 Stop 也视为已中断并从运行状态移除,但不生成完成记录、通知或触觉反馈。工具、上下文压缩和子智能体事件更新已有任务并解除等待,同时记录最近事件供活动卡片实时展示。工具和权限事件缺少起点时可以恢复顶层状态,子智能体事件不会单独创建顶层任务。
- `PermissionRequest` 进入等待批准;重复的等待事件不重复发布等待 transition。live 读取一次可能包含多个事件,monitor 会在整批应用后按任务键合并等待候选:最终仍在等待时使用最终快照发布一次,已经恢复运行、完成或移除时不发布过期等待 transition;完成候选保持事件顺序,并按 completion ID 防止同批重复发布。
-- Hook `Stop` 或 rollout `task_complete` 结束任务并产生最近完成记录,两者在进程内按精确任务键和 session 回退键去重,保留第一次确认的完成及精确耗时且不重复发布 transition。后到的重复完成不会覆盖首次确认结果,也不会缩短 24 小时去重窗口。期间迟到的工具、压缩或权限事件不会恢复已完成任务,只有时间晚于完成记录的新 `UserPromptSubmit` 可以开始下一段生命周期。rollout `turn_aborted` 只静默移除中断任务。“完成”只表示该 turn 已结束,不表示任务成功。
+- Hook `Stop` 或 rollout `task_complete` 结束任务并产生最近完成记录,两者在进程内按精确任务键和 session 回退键去重,保留第一次确认的完成及精确耗时且不重复发布 transition。后到的重复完成不会覆盖首次确认结果,也不会缩短 24 小时去重窗口。期间迟到的工具、压缩或权限事件不会恢复已完成任务,只有时间晚于完成记录的新 `UserPromptSubmit` 可以开始下一段生命周期。rollout `turn_aborted` 会直接进入最近终止列表;同 session 新 prompt 淘汰的旧 turn 则立即退出活动列表并进入 5 秒终态确认窗口,期间继续参与 rollout 查询并优先接受 `task_complete`、`turn_aborted` 或迟到 Hook `Stop`,到期仍无终态才进入最近终止列表。“完成”只表示该 turn 已结束,不表示任务成功。
- 精确 turn 匹配失败时,回退同 session 最近活动任务,再回退同项目匿名任务。
-- UI 优先展示最近等待任务,其次最近运行任务,最后最近完成任务,同时保留运行与等待数量。运行卡片第一行组合项目与模型,第二行展示运行时间及最近的请求/工具/压缩/子智能体事件,其他任务数量以右侧 `+N` 徽标展示。菜单栏完成绿色保留 20 秒,最近完成卡片保留 5 分钟,24 小时没有新事件的活动自动过期。
+- UI 优先展示最近等待任务,其次最近运行任务、最近完成任务和最近终止任务,同时保留运行与等待数量。只有终止历史时,活动卡片使用灰色终止状态展示最近一项。运行卡片第一行组合项目与模型,第二行展示运行时间及最近的请求/工具/压缩/子智能体事件,其他任务数量以右侧 `+N` 徽标展示。菜单栏完成绿色保留 30 秒,任务中心的最近完成和最近终止记录保留 10 分钟,24 小时没有新事件的活动自动过期。
-跨日时仍在内存中的运行任务会继续保留;重启 App 后由滚动 24 小时 bootstrap 恢复近期活动,并为更早开始的精确 turn 定向回填起点。任务会一直保留到收到 Hook `Stop` 或 rollout `task_complete`、检测到 `turn_aborted`、同 session 新 prompt 将其淘汰、Hook 被关闭或连续 24 小时没有新事件。完成高亮、完成卡片、完成去重键和活动过期共用按最近到期时刻创建的单次清理任务,不运行常驻清理计时器;读取完成键时还会惰性淘汰已经超过 24 小时的记录,避免系统休眠或计时任务稍晚唤醒时误拦第一条新事件。
+跨日时仍在内存中的运行任务会继续保留;重启 App 后由滚动 24 小时 bootstrap 恢复近期活动,并为更早开始的精确 turn 定向回填起点。任务会一直保留到收到 Hook `Stop` 或 rollout `task_complete`、检测到 `turn_aborted`、同 session 新 prompt 将其淘汰、Hook 被关闭或连续 24 小时没有新事件。完成高亮、最近完成、最近终止、完成去重键和活动过期共用按最近到期时刻创建的单次清理任务,不运行常驻清理计时器;读取完成键时还会惰性淘汰已经超过 24 小时的记录,避免系统休眠或计时任务稍晚唤醒时误拦第一条新事件。
## 写入事务
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
index f80535a..d477c0c 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -98,11 +98,11 @@ App 退出时, `applicationWillTerminate` 调用 `StatusItemController.uninstall
正常图标是 `person.fill.checkmark`, 错误图标是 `person.fill.xmark`
-小人右下角的状态点只表达 Hook 任务状态,按 `等待批准 > 运行中 > 刚完成 > 暂无活动` 取最高优先级:等待批准使用系统橙色,运行中使用系统蓝色,确认 turn 完成后 20 秒内使用系统绿色,空闲时不显示。小人本体始终使用系统前景色,账号异常继续由 `person.fill.xmark` 表达,不改变状态点颜色;空闲且没有额度竖条时保持 template 图像,有状态点或显示额度竖条时使用非 template 合成图。状态点与额度竖条分别绘制,颜色互不影响。
+小人右下角的状态点只表达 Hook 任务状态,按 `等待批准 > 运行中 > 刚完成 > 暂无活动` 取最高优先级:等待批准使用系统橙色,运行中使用系统蓝色,确认 turn 完成后 30 秒内使用系统绿色,空闲时不显示。小人本体始终使用系统前景色,账号异常继续由 `person.fill.xmark` 表达,不改变状态点颜色;空闲且没有额度竖条时保持 template 图像,有状态点或显示额度竖条时使用非 template 合成图。状态点与额度竖条分别绘制,颜色互不影响。
设置页「菜单栏额度指示」默认开启, 使用独立开关控制启用状态; 缺失持久化选择时默认使用 `.primary`, 关闭时显式持久化 `.off`。开启后在同一行显示额度窗口菜单, 可选择当前账号 Codex limit 返回的额度窗口, 当前保留选择不在返回窗口中时用 fallback 标题追加到菜单。最后一次非关闭的窗口选择由 `MenuBarQuotaSettings` 以 `MenuBarQuota.lastWindowSelection` 键随偏好持久化: 关闭开关时它继续参与菜单淡出避免过渡期间回退, 重新开启时(含重开设置窗口或重启应用后)恢复该选择, 无记录时回退 `.primary`。开启后 `StatusItemController` 会把所选 Codex 窗口的剩余额度进度条绘制在图标左侧, 以竖条形式与 `person.fill.checkmark` / `person.fill.xmark` 合成为单个 `NSImage`, 并随 `CodexStatusViewModel` 自动刷新。合成图尺寸为 `27 x 17`, 图标本体保持原始 `24 x 17`, 左侧竖条轨道为 `2 x 15`, 状态点位于小人右下角。额度显隐或状态点变化时, `StatusItemController` 合并为同一个逐帧重绘任务,在 0.18 秒内同时插值竖条与状态点的透明度以及状态点颜色,避免两个动画任务竞争;过渡期间合成图宽度和绘制坐标保持固定。活动期间 tooltip 每分钟更新一次耗时并合并并发数量与额度,活动结束后取消刷新任务。
-Hook 开启时,账号卡片下方始终显示固定高度 `CodexActivityCard`;即使 app-server 异常进入空数据分支也不会隐藏。卡片按等待、运行、最近完成、空闲的顺序展示项目最后一级名称、模型或工具、耗时及其他任务数量。最近完成保留 5 分钟。耗时 `TimelineView` 只在 popover 或 fallback panel 可见时逐秒 tick。
+Hook 开启时,账号卡片下方始终显示固定高度 `CodexActivityCard`。主面板 `CodexQuotaSnapshot` 为 `nil` 时,卡片消费空活动快照并显示「暂无数据」,不开放任务中心;Monitor 仍在后台维护状态,主快照恢复后直接发布最新活动。卡片按等待、运行、最近完成、最近终止、空闲的顺序展示项目最后一级名称、模型或工具、耗时及其他任务数量;只有终止历史时使用灰色终止状态展示最近一项。存在活动任务、最近完成或最近终止记录时整张卡片成为无系统 label 状态变化的自定义 button:只有存在其他活动任务时才在右侧显示 `+N`,单任务不显示尾部附件,hover/选中反馈只作用于卡片描边。点击后由 `ActivityCenterPanelController` 展开并发任务中心,按等待、运行、最近完成和最近终止展示 `CodexActivitySnapshot` 的完整有序列表;等待和运行按最后活动时间倒序,完成和终止分别按结束时间倒序。任务及两类最近记录使用进程内 opaque UUID 供 SwiftUI diff,不向 UI 暴露 session/turn ID。最近完成和最近终止均保留 10 分钟,卡片与任务中心的耗时只在各自可见时逐秒 tick;已打开期间主快照变为 `nil` 时会立即收回任务中心。
错误图标触发条件:
@@ -119,6 +119,7 @@ Hook 开启时,账号卡片下方始终显示固定高度 `CodexActivityCard`
| 全局快捷键 | 切换菜单面板 |
| 系统 `⌘,` | 打开独立设置窗口 |
| 菜单面板内 `⌘L` | 打开独立日志窗口 |
+| 点击活动卡片 | 切换并发任务中心 |
| 上下文菜单"设置" | 打开独立设置窗口 |
| 上下文菜单"日志" | 打开独立日志窗口 |
| 上下文菜单"退出" | 终止 App |
@@ -144,7 +145,7 @@ Hook 开启时,账号卡片下方始终显示固定高度 `CodexActivityCard`
关闭菜单面板的顺序:
-- 立即隐藏热力图详情面板和重置次数详情面板
+- 立即隐藏热力图详情面板、重置次数详情面板和并发任务中心
- 移除本地和全局事件监听
- 将 `isVisible` 设为 `false`, 让倒计时停止 `TimelineView` 每秒 tick
- 临时禁止设置窗口和日志窗口成为 key window, 避免关闭菜单面板时 AppKit 把这些辅助窗口提到前面
@@ -162,9 +163,9 @@ Hook 开启时,账号卡片下方始终显示固定高度 `CodexActivityCard`
Command-Space 不直接关闭菜单面板, 只短暂抑制 600 ms 内的 active 变化关闭逻辑, 避免 Spotlight 或系统搜索抢焦点时误关弹窗。
-热力图详情面板和重置次数详情面板都会通过 `containsScreenPoint(_:)` 告诉关闭监听器自己的屏幕区域, 因此点击这些 child panel 内部不会触发主菜单面板关闭。重置次数详情面板可接收鼠标事件用于滚动; 热力图详情面板不接收鼠标事件。
+热力图详情面板、重置次数详情面板和并发任务中心都会通过 `containsScreenPoint(_:)` 告诉关闭监听器自己的屏幕区域, 因此点击这些 child panel 内部不会触发主菜单面板关闭。重置次数详情面板和并发任务中心可接收鼠标事件用于滚动; 热力图详情面板不接收鼠标事件。并发任务中心是点击后保持打开的面板;出现有效的热力图方块 hover context 时会自动收回任务中心并展示当天详情,点击重置次数也会显式切换并关闭任务中心。
-侧边面板的共同行为集中在 `CodexBar/Controllers/SidePanelSupport.swift`: `NonactivatingSidePanel` 固定不能成为 key/main window, `KeyableBorderlessPanel` 供需要键盘焦点的无边框面板(通知子选项面板、fallback 面板)共用, `SidePanelDrawerAnimator` 管理内容 view 的横向抽屉 transform, `SidePanelDrawerPresenter` 承载重置次数/通知子选项两类「一次性展开」面板共用的显隐状态机(generation 竞态防护、入退场动画、child window 挂载/卸载、可选 makeKey), `SidePanelSupport` 提供 panel 工厂(`makePanel`, 由 `ignoresMouseEvents`、初始尺寸与 `keyable` 决定)、完整定位入口(`position`, 内含左右侧选择、坐标夹紧与 `SidePanelPosition` 组装, 纵向由调用方传入期望位置)、锚点行对齐与校验(`alignedProposedY` / `validatedAlignmentScreenFrame`, 容差 6 pt)、共享几何/抽屉动画常量(`SidePanelSupport.Metrics`), 以及 child window 挂载/移除、菜单面板 key window 恢复、圆角 layer 配置和屏幕 frame 换算。`HeatmapDetailPanelController` 保留 hover 请求、Y 轴策略、侧边切换队列和 token/workflow 内容更新, 其切边/延迟隐藏状态机不走共享 presenter; `ResetCreditsPanelController` 主要保留重置次数内容、最大高度和点击切换状态。两个面板视图的玻璃底/背板/描边/圆角裁剪皮肤共用 `LiquidGlassStyle.swift` 的 `sidePanelChrome(cornerRadius:)`。
+侧边面板的共同行为集中在 `CodexBar/Controllers/SidePanelSupport.swift`: `NonactivatingSidePanel` 固定不能成为 key/main window, `KeyableBorderlessPanel` 供需要键盘焦点的无边框面板(通知子选项面板、fallback 面板)共用, `SidePanelDrawerAnimator` 管理内容 view 的横向抽屉 transform, `SidePanelDrawerPresenter` 承载重置次数、并发任务中心和通知子选项三类「一次性展开」面板共用的显隐状态机(generation 竞态防护、入退场动画、child window 挂载/卸载、可选 makeKey), `SidePanelSupport` 提供 panel 工厂(`makePanel`, 由 `ignoresMouseEvents`、初始尺寸与 `keyable` 决定)、完整定位入口(`position`, 内含左右侧选择、坐标夹紧与 `SidePanelPosition` 组装, 纵向由调用方传入期望位置)、锚点行对齐与校验(`alignedProposedY` / `validatedAlignmentScreenFrame`, 容差 6 pt)、锚点感知的定位边界放宽(`anchorAwareVisibleFrame`, 宿主进入系统菜单栏保留区时只向上放宽到锚点行顶边)、共享几何/抽屉动画常量(`SidePanelSupport.Metrics`), 以及 child window 挂载/移除、菜单面板 key window 恢复、圆角 layer 配置和屏幕 frame 换算。`HeatmapDetailPanelController` 保留 hover 请求、Y 轴策略、侧边切换队列和 token/workflow 内容更新, 其切边/延迟隐藏状态机不走共享 presenter; `ResetCreditsPanelController` 主要保留重置次数内容、最大高度和点击切换状态;`ActivityCenterPanelController` 使用常驻 Monitor 快照原地更新任务列表,只有显隐时播放抽屉动画,并在主面板进入系统菜单栏保留区时只向上放宽定位边界到活动卡片顶边。任务中心先按当前分区和条目数扩展高度,并在打开期间随快照变化重新布局;高度同时受屏幕可见高度和活动卡片顶边到主面板底边的距离限制,只有达到该上限后列表才内部滚动,因此顶边保持对齐且底边不会越过主面板。三个面板视图的玻璃底/背板/描边/圆角裁剪皮肤共用 `LiquidGlassStyle.swift` 的 `sidePanelChrome(cornerRadius:)`。
设置窗口和日志窗口都继承 `HostingWindowController` 的行为: 懒创建, 关闭后不释放, 重新打开复用, 按当前屏幕居中, 重新打开对应入口时只移动和置前对应窗口。窗口 level 保持 `.normal`; 置前时先恢复 `AuxiliaryHostingWindow.allowsKeyFocus`, 再 `orderFrontRegardless()`, `NSRunningApplication.current.activate(options: [])` 和 `makeKeyAndOrderFront(nil)`, 只做一次性置前, 不持续置顶。CodexBar 是 `LSUIElement` 菜单栏 App, 首次懒创建辅助窗口时需要通过当前运行中应用激活, 避免设置或日志窗口第一次打开时没有稳定拉到最前。
@@ -1077,7 +1078,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
- 不把原始敏感 RPC 响应写入文档或测试夹具
- 日志完整保存 request/detail, UI 默认只渲染单行预览; 完整内容通过标题行预览或复制查看
- Hook 统计默认只保存在用户 Application Support 的 CodexBar 目录;开启「跨设备同步」后, CloudKit 只保存去掉 `sessionIds` / `turnIds` 的 daily 聚合副本, 不保存原始 Hook events
-- 实时任务状态只保存在 `CodexActivityMonitor` 内存中,UI 只展示项目最后一级名称、模型、工具名与最近 Hook 事件类型;运行卡片第一行组合项目和模型,第二行组合运行时间与请求/工具/压缩/子智能体状态,其他任务数使用右侧 `+N` 徽标。不写历史文件、不上传 CloudKit,也不新增网络请求。`CodexSessionLifecycleReader` 只对活跃 session + turn 增量读取本机 rollout,提取事件类型、turn ID、起止时间和耗时,不提取、保存或展示提示词、回复、推理和工具内容
+- 实时任务状态只保存在 `CodexActivityMonitor` 内存中,UI 只展示项目最后一级名称、模型、工具名与最近 Hook 事件类型;运行卡片第一行组合项目和模型,第二行组合运行时间与请求/工具/压缩/子智能体状态,其他任务数使用右侧 `+N` 徽标。并发任务中心消费同一快照中的完整等待、运行、最近完成和最近终止列表,列表身份使用进程内 UUID,不展示或持久化 session/turn ID。不写历史文件、不上传 CloudKit,也不新增网络请求。`CodexSessionLifecycleReader` 只对活跃 session + turn 增量读取本机 rollout,提取事件类型、turn ID、起止时间和耗时,不提取、保存或展示提示词、回复、推理和工具内容
## 19. 通知与触觉提醒链路
@@ -1087,9 +1088,9 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
- `CodexNotificationService`: 集中判定、去重、调度与发送; 由 `CodexBarAppDelegate` 创建, 订阅 `CodexStatusViewModel.$snapshot`、`CodexActivityMonitor` live transition 与 `NSWorkspace.didWakeNotification`; 五类正式通知共用 `CodexNotificationContent` 文案工厂,系统提交失败时重试一次,等待与完成 transition 还会按偏好请求 AppKit `.levelChange` 触觉反馈
- `CodexActivityMonitor`: Hook 开启期间始终运行并维护并发任务;向 UI 发布快照,向提醒服务发布 live transition。单个 live 批次先完整应用事件,再按任务键合并等待候选;只有批次结束后仍处于等待的任务会使用最终快照发布一次等待 transition,完成候选保持顺序并按 completion ID 做批内去重。通知与触觉开关不会停止活动监测
- `HookEventTailReader` (`Services/Workflow/`): 后台 actor;bootstrap 以 512 KB 为单次分块流式读取滚动 24 小时事件,并用 start/events/end 三阶段恢复状态。当前文件用 inode + 完整行 offset 固定 bootstrap/live 边界;bootstrap 结束后 monitor 再发起一次定向回溯,为缺少起点的精确 turn 向旧日期文件最多回读 8 MB。之后每 2 秒 tail 当日增量,保留半行、跨日先读旧文件尾部;live 每成功处理一个分块就推进到最后完整行 offset,后续分块失败只重试未处理部分。旧文件异常触发 bootstrap 时保留 bootstrap 设置的新日期 offset,临时读取失败则保留旧日期等待下轮重试。bootstrap、定时轮询和 Mac 唤醒补读共用串行入口,读取期间到达的请求合并为当前读取结束后的一次补读;monitor generation 会丢弃停用 reader 的迟到批次
-- `CodexSessionLifecycleReader`: 后台 actor,只为 monitor 当前的精确 session + turn 定位对应 rollout;便宜目录每 10 秒重试,每个活跃生命周期最多递归 `sessions` 一次并保留负缓存,缓存文件移动、session 重新活跃或 Mac 唤醒时重置。rollout 初次最多读取末尾 512 KB,之后按 offset 增量读取;`task_started` 回填缺失起点,`task_complete` 补齐结束和精确耗时,`turn_aborted` 由 monitor 静默移除任务,读取失败时不改变 Hook 状态。轮询和即时 lifecycle 查询都绑定 reader generation,跨 actor 返回后仍会复核,旧查询不能落入新 reader 状态
+- `CodexSessionLifecycleReader`: 后台 actor,只为 monitor 当前活动或等待终态确认的精确 session + turn 定位对应 rollout;便宜目录每 10 秒重试,每个活跃生命周期最多递归 `sessions` 一次并保留负缓存,缓存文件移动、session 重新活跃或 Mac 唤醒时重置。rollout 初次最多读取末尾 512 KB,之后每 1 秒按 offset 增量读取;`task_started` 回填缺失起点,`task_complete` 补齐结束和精确耗时,`turn_aborted` 由 monitor 移除任务并生成灰色最近终止记录,读取失败时不改变 Hook 状态。轮询和即时 lifecycle 查询都绑定 reader generation,跨 actor 返回后仍会复核,旧查询不能落入新 reader 状态
-活动并发以 session 为边界:不同 session 可以同时运行;同一 session 的 turn 按顺序执行。收到新的 `UserPromptSubmit` 时,monitor 会移除该 session 中更早且缺少结束信号的 turn;rollout 收到 `turn_aborted` 时移除对应精确 turn。两种情况都视为中断而不是完成,因此不会触发绿色完成状态、长任务通知或完成触觉反馈。Hook `Stop` 与 rollout `task_complete` 均视为完成信号,先到者生效,后到者按任务键和 session 回退键去重 24 小时;重复完成不会覆盖首次确认结果,也不会缩短去重窗口或再次触发反馈。去重键独立参与最近 deadline 清理,读取时也会惰性移除过期值;迟到的非 Prompt 事件不会重新恢复已完成任务,时间晚于完成记录的新 Prompt 才能开始下一段生命周期。
+活动并发以 session 为边界:不同 session 可以同时运行;同一 session 的 turn 按顺序执行。收到新的 `UserPromptSubmit` 时,monitor 会让该 session 中更早且缺少结束信号的 turn 立即退出活动列表,但保留为等待终态确认任务并触发一次即时 rollout 查询;5 秒内收到 Hook `Stop`、rollout `task_complete` 或 `turn_aborted` 时按真实终态归类,到期仍无终态才生成灰色最近终止记录。已完成和已终止任务键分别保留 24 小时 tombstone,避免迟到事件恢复旧任务或误操作同 session 的新 turn。终止不会触发绿色完成状态、长任务通知或完成触觉反馈。Hook `Stop` 与 rollout `task_complete` 均视为完成信号,先到者生效,后到者按任务键和 session 回退键去重;重复完成不会覆盖首次确认结果,也不会缩短去重窗口或再次触发反馈。
设置页交互: 「系统通知」主开关行保留在设置窗口内, 子选项 (五类通知子开关、任务触觉开关与两个阈值 Picker) 在主选项右侧的子面板中展开 (`NotificationOptionsPanelController`, 复用 SidePanelSupport 抽屉机制挂在设置窗口上, 内容用常驻 hosting controller + ObservableObject 驱动, 面板尺寸在 Hook 开/关两种状态下保持不变)。「任务等待通知」和「任务触觉反馈」依次排列在「任务完成通知」下方。主开关开启后仅在系统授权允许时展开, 首次授权场景会等待授权结果; 点击行内滑杆按钮可手动展开; 设置窗口 resign key/关闭、主开关关闭或授权变为被拒时自动收起。任务完成、任务等待与任务触觉子项在 Hook 未开启时显示为关闭并置灰, 不修改各自持久化偏好, Hook 重新开启后恢复用户原选择。授权被拒的引导文案与"打开系统设置"按钮仍内联显示在主开关行下方, 插入提示时不触发设置项纵向动画。
@@ -1109,16 +1110,16 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
通知错误处理 (延续"细节不打扰用户"原则, 不写入请求日志窗口):
-| 场景 | 行为 |
-| ------------------------------ | ------------------------------------------------------------------------ |
-| 系统授权未决定或被拒 | 未决定时等待用户选择,被拒时静默不发并在设置页显示引导 |
-| 当日事件文件临时读取失败 | 提交已处理完整行的 offset,下轮只重试剩余部分 |
-| Hook 或 rollout 单行解码失败 | 跳过坏行并继续处理同批其他完整行,不写入请求日志 |
-| 跨日旧文件临时读取失败 | 暂不切换日期,下一轮继续读取旧尾部;bootstrap 接管时不重放 live |
-| rollout 文件不存在或读取失败 | 保留 Hook 推导的任务状态,不猜测任务已经中断 |
-| 额度快照为空、stale 或窗口消失 | 空快照清空全部待重置窗口;stale 快照不参与转换;可信快照移除已消失窗口 |
+| 场景 | 行为 |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| 系统授权未决定或被拒 | 未决定时等待用户选择,被拒时静默不发并在设置页显示引导 |
+| 当日事件文件临时读取失败 | 提交已处理完整行的 offset,下轮只重试剩余部分 |
+| Hook 或 rollout 单行解码失败 | 跳过坏行并继续处理同批其他完整行,不写入请求日志 |
+| 跨日旧文件临时读取失败 | 暂不切换日期,下一轮继续读取旧尾部;bootstrap 接管时不重放 live |
+| rollout 文件不存在或读取失败 | 保留 Hook 推导的任务状态,不猜测任务已经中断 |
+| 额度快照为空、stale 或窗口消失 | 空快照清空全部待重置窗口;stale 快照不参与转换;可信快照移除已消失窗口 |
| 系统通知提交失败 | 自动重试一次;最终失败不写去重键,额度通知在后续可信快照中重试;账号或窗口生命周期已变化时丢弃迟到的重置失败回调 |
-| Hook 关闭 | monitor 停止 tail 并清空实时状态 |
-| 通知总开关或任务通知关闭 | 阻止对应通知;额度重置状态仍继续推进但不补发,总开关关闭时也阻止触觉反馈 |
+| Hook 关闭 | monitor 停止 tail 并清空实时状态 |
+| 通知总开关或任务通知关闭 | 阻止对应通知;额度重置状态仍继续推进但不补发,总开关关闭时也阻止触觉反馈 |
通知点击通过 `UNUserNotificationCenterDelegate` 回调 `StatusItemController.openMenuSurfaceFromNotification()`, 复用全局快捷键的打开路径 (含 fallback 面板兜底)。
diff --git a/Docs/UserGuide.md b/Docs/UserGuide.md
new file mode 100644
index 0000000..b0e1324
--- /dev/null
+++ b/Docs/UserGuide.md
@@ -0,0 +1,577 @@
+# CodexBar 使用指南与常见问题
+
+这份文档面向 CodexBar 用户,介绍日常使用方法、容易错过的点击入口、各种状态的含义,以及遇到异常时的排查步骤。
+
+如果你正在了解实现或数据格式,请阅读 [开发文档](DevelopmentGuide.md)、[Codex Hook 文档](CodexHook.md) 和 [跨设备同步文档](CrossDeviceSync.md)。
+
+## 目录
+
+- [1. 快速开始](#1-快速开始)
+- [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-隐私与数据边界)
+
+## 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 安装路径 | 单击 | 复制路径,短暂显示「已复制」 |
+| 日志列表中的一行 | 单击 | 展开请求、响应或错误摘要 |
+| 日志展开内容 | 点击「预览」或「复制」 | 查看或复制完整内容 |
+
+点击菜单面板和侧边详情面板之外的区域会关闭菜单面板,这是菜单栏工具的正常行为。
+
+## 3. 看懂菜单栏图标
+
+### 账号状态
+
+- 正常人物图标:账号数据可用。
+- 带叉图标:未登录、初始化失败,或当前快照不可信。
+- 将鼠标停在图标上可以查看账号异常、实时任务和额度窗口的摘要。
+
+### 菜单栏额度指示
+
+设置中的「菜单栏额度指示」开启后,图标左侧会显示当前所选额度窗口的剩余比例。可以在同一设置行切换要显示的额度窗口。
+
+颜色按剩余额度分档:
+
+| 剩余额度 | 颜色含义 |
+| ---------- | -------- |
+| 80% 及以上 | 充足 |
+| 60%–79% | 较充足 |
+| 40%–59% | 需要留意 |
+| 20%–39% | 较低 |
+| 低于 20% | 紧张 |
+
+额度窗口暂时没有可信数据时,菜单栏不会显示这条额度指示。
+
+### 实时任务状态点
+
+开启 Codex Hook 后,人物图标右下角可能出现状态点:
+
+- 橙色:有任务正在等待批准。
+- 蓝色:有任务正在运行。
+- 绿色:任务刚刚完成,绿色状态保留约 30 秒。
+- 无状态点:当前没有等待或运行任务,也没有处于绿色高亮期的完成任务。
+
+当多个状态同时存在时,显示优先级为:等待批准、运行中、刚完成、空闲。
+
+## 4. 使用菜单面板
+
+### 账号卡片
+
+账号卡片显示当前账号、订阅类型和刷新状态。
+
+- 双击头像可以立即刷新。
+- 双击邮箱可以模糊邮箱,适合共享屏幕或截图时临时隐藏账号信息。
+- 刷新中的小进度指示只表示正在请求本机 Codex app-server。
+
+CodexBar 默认每 60 秒自动刷新一次。菜单面板底部「数据更新时间」左侧的蓝色圆环表示距离下一次刷新还有多久。
+
+### 活动卡片和任务中心
+
+活动卡片只在 Codex Hook 开启时出现。它优先显示:
+
+1. 等待批准的任务。
+2. 正在运行的任务。
+3. 最近完成的任务。
+4. 最近终止的任务。
+5. 暂无活动。
+
+右侧 `+N` 表示还有其他正在运行或等待批准的任务。点击活动卡片会打开任务中心,完整列出:
+
+- 等待确认。
+- 运行中。
+- 最近完成。
+- 最近终止。
+
+「完成」只表示 Codex 已确认该轮结束,不代表任务结果一定成功。「终止」表示任务没有按正常完成路径结束,也不会触发绿色状态或完成通知。
+
+最近完成和最近终止记录保留约 10 分钟。任务中心会在菜单侧面展开,右侧空间不足时自动改到左侧;内容较多时可以在任务中心内滚动。
+
+### 额度和重置时间
+
+额度区域按 Codex 返回的时间窗口展示:
+
+- 剩余百分比。
+- 分段额度条。
+- 下一次重置时间。
+
+如果某一轮刷新失败,但之前有同账号的可用数据,CodexBar 会暂时显示旧缓存。此时额度或用量区域会变淡,表示数据可能不是最新值。
+
+如果 Codex 返回可用的手动重置机会,主额度标题右侧会出现 `重置次数: N`。点击后可以查看:
+
+- 各过期时间下有多少次机会。
+- 过期时间未知时显示「未知过期时间」。
+
+CodexBar 只查询重置机会和过期时间,不会代替用户执行额度重置。
+
+### Token 摘要和近 30 周热力图
+
+用量区域包括:
+
+- 全时累计 Token。
+- 单日峰值。
+- 当前连续使用天数。
+- 最长连续使用天数。
+- 最长任务耗时。
+- 近 30 周每日 Token 热力图。
+
+将鼠标移动到热力图方块上,会在菜单侧面显示当天详情。蓝色越深,表示当天 Token 用量相对越高。
+
+Hook 关闭时,详情主要显示日期、Token 和用量强度。Hook 开启后,还会显示最热模型、会话总数、对话轮次、子智能体、工具调用、权限请求和上下文压缩次数。
+
+这些工作流指标表示:
+
+| 指标 | 通俗解释 |
+| ---------- | --------------------------------------------------------- |
+| 最热模型 | 当天 Hook 事件中出现次数最多的模型,不代表消耗 Token 最多 |
+| 会话总数 | 当天识别到的不同 Codex 会话数量 |
+| 对话轮次 | 当天识别到的不同任务轮次数量 |
+| 子智能体 | 子智能体启动或结束事件归一后的数量 |
+| 调用工具 | 工具调用开始或结束事件归一后的数量 |
+| 权限请求 | Codex 请求用户批准操作的次数 |
+| 上下文压缩 | 上下文压缩开始或结束事件归一后的数量 |
+
+Hook 统计只从开启后开始记录,不能补出开启前的工作流历史。Token 数据和 Hook 统计来源不同,因此某一天可能有 Token,但没有 Hook 明细;也可能当天 Hook 已有事件,但 Token 桶尚未返回。
+
+### 菜单底部状态
+
+菜单底部包含三类信息:
+
+- 数据更新时间和 60 秒刷新倒计时。
+- 跨设备同步状态图标;悬停可查看详情。
+- 可用更新提示;双击提示可以开始更新。
+
+## 5. 设置 CodexBar
+
+通过右键菜单中的「设置」或 `⌘,` 打开设置窗口。
+
+| 设置项 | 作用 | 注意事项 |
+| --------------- | ----------------------------------------------- | -------------------------------------- |
+| 开机自动启动 | 登录 macOS 后自动启动 CodexBar | 移动 App 后建议重新关闭再开启一次 |
+| 自动检查更新 | 允许 Sparkle 自动检查新版本 | 关闭后仍可手动检查 |
+| 菜单栏额度指示 | 在图标左侧显示所选额度窗口 | 没有可用数据时自动隐藏 |
+| 启用 Codex Hook | 开启工作流统计、活动卡片和任务提醒 | 会修改当前用户的 `~/.codex/hooks.json` |
+| 跨设备同步 | 通过 iCloud private database 合并 Hook 日聚合 | 需要 Hook 已开启且 iCloud 可用 |
+| 系统通知 | 控制 CodexBar 通知和任务触觉反馈总开关 | 首次开启需要系统授权 |
+| 使用快捷键 | 设置全局打开/关闭菜单面板的快捷键 | 至少需要两个修饰键 |
+| Codex 版本 | 查看全局 CLI、Codex.app 内置 CLI 和当前使用来源 | 点击路径可以复制 |
+| CodexBar 版本 | 查看更新状态和当前版本 | 有更新时可点击右侧更新按钮 |
+
+### 修改全局快捷键
+
+默认快捷键是 `⌘⇧W`。
+
+如果已经设置快捷键,需要先点击叉号清除,再点击「未设置」开始录制新的组合。快捷键至少包含两个修饰键,且不能使用 `⌘Space`、`⌘Tab` 等系统保留组合。
+
+- 按 `Esc` 取消本次录制。
+- 点击回转箭头恢复默认快捷键。
+- 如果注册失败,设置行下方会显示原因,原快捷键会被恢复。
+
+### 配置通知子选项
+
+开启「系统通知」后,点击该行右侧的滑杆图标,可以分别设置额度预警、额度重置、任务完成、任务等待、任务触觉和重置次数临期提醒。具体说明见[通知与触觉反馈](#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 失败` | 开启前检查或写入失败;根据下方错误及日志排查 |
+
+CodexBar 只增删属于当前 CodexBar 可执行文件的 Hook,不会删除其他 App 或用户自己的 Hook。
+
+### 关闭 Hook 或移动 App
+
+关闭 Hook 会停止记录新事件、隐藏 Hook 统计和活动卡片,并清空当前进程中的实时任务状态,但不会删除已经保存在本机的历史文件。以后重新开启 Hook 时,已有聚合仍可继续使用。
+
+Hook 命令包含 CodexBar 当前可执行文件的完整路径。如果准备把 `CodexBar.app` 移到其他目录,建议先在旧位置关闭 Hook,移动后再重新开启。已经移动且旧 Hook 无法执行时,需要检查 `~/.codex/hooks.json` 中是否仍有指向旧路径的 CodexBar 命令。
+
+### Codex 被关闭后为什么任务仍显示运行中
+
+如果 Codex 正常写入 `Stop`、`task_complete` 或 `turn_aborted`,CodexBar 可以识别完成或终止。
+
+如果 Codex 被强制关闭、进程崩溃、终端直接退出或电脑断电,而且没有留下终态事件,CodexBar 无法立即确定任务是否真的结束。此时:
+
+- 同一 session 后续出现新 Prompt,旧任务会立即退出运行列表,并等待约 5 秒确认真实终态;仍无终态时记为最近终止。
+- 始终没有任何后续事件,任务最多可能保留 24 小时。
+- 重新启动 CodexBar 或重新开启 Hook 后,最近 24 小时事件可能再次恢复这条无终态任务。
+
+当前版本没有单任务「手动移除」功能。单纯长时间没有事件也不能安全地自动判定终止,因为任务可能正在长时间调用工具、等待输入或经历系统休眠。
+
+## 7. 跨设备同步
+
+### 开启条件
+
+跨设备同步同时需要:
+
+- Codex Hook 已开启。
+- 设置中的「跨设备同步」已开启。
+- 当前 Mac 已登录可用的 iCloud 账号。
+
+如果开关呈灰色或显示「同步不可用」,请先确认 Hook 状态和 macOS 的 iCloud 登录状态。
+
+### 同步什么
+
+同步使用当前 iCloud 账号的 CloudKit private database,只上传按设备、按天生成的脱敏聚合数据,用于合并热力图中的工作流统计。
+
+不会上传:
+
+- Codex 账号和额度。
+- Token 用量。
+- 原始 Hook 事件。
+- 会话 ID 和轮次 ID。
+- 实时任务状态。
+- 请求日志和 Codex 认证文件。
+
+### 看懂同步状态
+
+菜单面板底部的 iCloud 图标表示同步状态,悬停可以查看文字:
+
+- 带斜杠:同步未开启或未实际生效。
+- 旋转箭头:正在同步。
+- 感叹号:最近一次同步失败。
+- 普通 iCloud:同步已开启;悬停显示最近同步时间或「暂无同步记录」。
+
+同步在 Hook 统计维护后触发。网络或服务暂时失败时不需要反复开关,后续刷新会继续重试尚未成功的日期。
+
+## 8. 通知与触觉反馈
+
+### 开启步骤
+
+1. 打开 CodexBar 设置。
+2. 开启「系统通知」。
+3. 在 macOS 授权提示中允许通知。
+4. 点击通知行右侧的滑杆图标,配置具体提醒。
+
+如果系统权限被拒绝,设置页会显示提示和「打开系统设置」按钮。
+
+### 可用通知
+
+| 选项 | 触发条件 | 可配置项 |
+| ---------------- | ---------------------------------- | -------------------------------- |
+| 额度预警通知 | 可信额度从阈值上方跌到阈值或以下 | 5%、10%、25%,默认 10% |
+| 额度重置通知 | 已发生消耗的额度窗口恢复到 100% | 无 |
+| 任务完成通知 | Hook 任务确认完成且耗时达到阈值 | 30 秒、1、2、5 分钟,默认 1 分钟 |
+| 任务等待通知 | 任务在一批事件处理结束后仍等待批准 | 无 |
+| 任务触觉反馈 | 任务进入等待批准或确认结束 | 需要 Hook;服从通知总开关 |
+| 重置次数临期通知 | 手动重置机会将在 7 天内过期 | 最多每 24 小时提醒一次 |
+
+任务完成、任务等待和任务触觉选项需要 Hook。Hook 关闭时,这些选项会显示为关闭并置灰,但不会丢失用户原来的偏好。
+
+触觉反馈是否真的发生、震感强弱和形式由 Mac、触控板、辅助功能及系统偏好决定。CodexBar 请求了触觉,不代表所有设备都能产生明显反馈。
+
+点击 CodexBar 发出的系统通知会尝试打开主菜单面板,方便继续查看当前状态。
+
+## 9. 日志、版本与更新
+
+### 打开日志
+
+- 右键菜单栏图标,选择「日志」。
+- 主菜单面板打开时按 `⌘L`。
+
+日志记录 CodexBar 与本机 app-server 的请求状态,适合排查「未登录」「初始化失败」、刷新超时、Hook 验证和接口兼容问题。
+
+使用方法:
+
+- 点击一行展开。
+- 点击「预览」打开完整内容;JSON 会格式化并高亮。
+- 点击「复制」复制完整请求、响应或错误。
+- 点击顶部「清空」删除当前进程内的日志列表。
+
+提交问题前建议先查看日志,但分享日志前仍应自行检查内容是否适合公开。
+
+### Codex 版本
+
+设置中的「Codex 版本」会同时展示:
+
+- 全局安装的 Codex CLI。
+- Codex.app 内置的 CLI。
+- 当前 app-server 实际使用的来源。
+- 磁盘安装版本与当前运行版本是否一致。
+
+点击安装路径可以复制,便于确认 CodexBar 实际连接了哪个 Codex。
+
+### 更新 CodexBar
+
+- 开启「自动检查更新」后,Sparkle 会定期检查新版本。
+- 可以随时点击设置底部的「检查更新」。
+- 有可用更新时,设置中的版本行会出现更新按钮。
+- 菜单面板底部出现更新提示时,可以双击提示开始更新。
+
+## 10. 常见问题
+
+### A. 启动、账号与数据
+
+#### 为什么启动后没有 Dock 图标或主窗口?
+
+这是正常设计。CodexBar 是纯菜单栏 App,请从屏幕顶部菜单栏打开。
+
+#### 为什么菜单栏图标显示叉号?
+
+通常表示 Codex 未登录、CodexBar 初始化 app-server 失败,或当前数据不可信。先打开 Codex CLI 或 Codex.app 确认已经登录,然后双击 CodexBar 账号头像刷新;仍失败时查看日志。
+
+#### 「未登录」应该怎么处理?
+
+在 Codex CLI 或 Codex.app 中完成登录,再回到 CodexBar 双击头像刷新。CodexBar 不提供独立登录流程。
+
+#### 「初始化失败」应该怎么处理?
+
+依次检查:
+
+1. Codex CLI 或 Codex.app 是否仍安装在磁盘上。
+2. 设置中的「Codex 版本」能否找到安装路径。
+3. 点击路径确认当前使用来源是否符合预期。
+4. 打开日志查看是找不到可执行文件、超时、断连还是接口不兼容。
+5. 更新 Codex CLI、Codex.app 和 CodexBar 后重试。
+
+#### 为什么只显示「暂无数据」?
+
+账号可能已经识别,但本轮没有返回可展示的额度或用量。等待下一次自动刷新,或双击头像手动刷新;日志中会保留更具体的请求结果。
+
+#### 为什么额度或热力图突然变淡?
+
+变淡表示本轮刷新失败,CodexBar 正在显示同账号的旧缓存。缓存仍可参考,但可能不是最新值。
+
+#### 数据多久刷新一次?
+
+账号、额度和 Token 用量默认每 60 秒刷新一次。双击头像可以立即刷新,并重新开始 60 秒倒计时。
+
+### B. 点击入口和菜单行为
+
+#### 哪些地方可以点击或悬停?
+
+最容易错过的入口是:活动卡片、`重置次数: N`、热力图方块、通知行右侧滑杆图标、Codex 安装路径,以及日志行。完整列表见[所有入口与快捷操作](#2-所有入口与快捷操作)。
+
+#### 为什么点击活动卡片没有反应?
+
+任务中心只有在以下条件同时满足时才能打开:
+
+- Hook 已开启。
+- 账号和主数据快照已经加载。
+- 当前存在运行、等待、最近完成或最近终止任务。
+
+显示「暂无数据」或「暂无 Codex 活动」时不会打开空任务中心。
+
+#### 为什么热力图详情不能点击?
+
+热力图详情是跟随鼠标悬停的只读侧边面板,不接收点击。把鼠标移回目标日期即可重新显示。
+
+#### 为什么点击菜单外部后面板关闭了?
+
+这是菜单栏工具的预期行为。任务中心和重置次数面板属于菜单面板的侧边区域,点击它们内部不会关闭主菜单。
+
+#### 怎么隐藏截图里的邮箱?
+
+双击账号卡片中的邮箱即可模糊,再双击一次恢复。账号变化后模糊状态会自动重置。
+
+### C. 额度、重置次数和热力图
+
+#### 为什么菜单栏没有额度竖条?
+
+检查设置中的「菜单栏额度指示」是否开启,以及所选窗口是否有可信数据。窗口没有返回数据时,指示会自动隐藏。
+
+#### 为什么看不到 `重置次数: N`?
+
+只有 Codex 返回大于零的可用手动重置机会时才显示。CodexBar 不会自行预测或创建重置机会。
+
+#### 为什么重置次数详情显示「未知过期时间」?
+
+CodexBar 已知道可用次数,但读取过期时间的只读请求失败或没有返回有效时间。次数本身仍可能有效。
+
+#### 为什么热力图中的今天显示 `--`?
+
+Hook 已记录今天的工作流事件,但 Token 用量接口还没有返回今天的 bucket 时,会显示 `--`。这不代表 Hook 数据丢失。
+
+#### 为什么 Hook 统计和 Token 数对不上?
+
+两者来自不同数据源:Token 来自本机 app-server 用量接口,工作流统计来自 Codex Hook。它们的更新时间、保留范围和统计口径不同,不应逐项一一对应。
+
+### D. Hook 与实时任务
+
+#### 为什么开启 Hook 后看不到以前的统计?
+
+Hook 只能从开启后开始记录事件,无法还原此前没有写入的工作流历史。
+
+#### 关闭 Hook 会删除以前的统计吗?
+
+不会。关闭 Hook 只停止新事件记录、同步调度和实时任务监测,本机历史文件仍然保留。重新开启后可以继续显示已有统计。
+
+#### 移动 CodexBar.app 后 Hook 不工作了怎么办?
+
+Hook 保存的是 App 可执行文件的完整路径。将 App 移回原位置后先关闭 Hook,再把 App 移到最终位置并重新开启;或者检查 `~/.codex/hooks.json`,移除指向旧 CodexBar 路径的命令后重新开启。
+
+#### 为什么有任务在 Codex 中运行,CodexBar 却没有显示?
+
+可能原因包括:Hook 未开启或不完整、任务开始事件没有送达、Hook 配置未被信任、主菜单数据尚未加载,或正在使用的 Codex 版本不支持所需事件。先查看 Hook 行提示,再检查日志。
+
+#### 为什么任务显示「正在运行」但没有精确耗时?
+
+任务可能是从工具或权限事件恢复出来的,缺少可信的 Prompt 起点;匿名任务也不会猜测精确耗时。CodexBar 会保留运行状态,但显示「正在运行」而不是不可靠的时长。
+
+#### 为什么 Codex 已经关闭,任务仍显示运行中?
+
+强制关闭或崩溃可能来不及写入结束事件。没有终态时 CodexBar 无法立即判断,任务最多可能保留 24 小时。详见[Codex 被关闭后为什么任务仍显示运行中](#codex-被关闭后为什么任务仍显示运行中)。
+
+#### 能否手动清除一条卡住的运行任务?
+
+当前版本不能。重新启动或重新开启 Hook 也可能从最近事件中恢复它。同一 session 出现新 Prompt 后,旧任务通常会在约 5 秒内归入最近终止;否则等待 24 小时活动过期。
+
+#### 为什么「最近终止」没有发送完成通知?
+
+终止不等于完成。终止记录只用于说明任务不再处于正常运行路径,不触发绿色状态、完成通知或完成触觉反馈。
+
+#### 为什么多个任务只在卡片上看到一个?
+
+卡片只展示优先级最高的一项,右侧 `+N` 表示其他活动任务。点击卡片打开任务中心可以查看完整列表。
+
+### E. 跨设备同步
+
+#### 为什么跨设备同步开关不可用?
+
+先开启 Hook,再确认 macOS 已登录 iCloud 且 CloudKit 账号状态可用。任一条件不满足时,同步不会实际生效。
+
+#### 同步会上传 Token、提示词或会话 ID 吗?
+
+不会。跨设备同步只上传脱敏的每日 Hook 聚合,不上传 Token 用量、提示词、回复、原始事件、会话 ID 或轮次 ID。
+
+#### 为什么刚开启同步没有立刻看到另一台 Mac 的数据?
+
+首次开启会安排历史聚合回填,并在后续统计维护和刷新中分批上传、下载。请保持 Hook 与同步开启,并查看菜单底部同步图标和设置中的最近同步时间。
+
+#### 同步失败后需要重新开关吗?
+
+通常不需要。网络、账号或 CloudKit 服务暂时失败时,后续刷新会重试未完成日期。长期失败时检查 iCloud 登录状态和系统网络。
+
+### F. 通知与触觉反馈
+
+#### 为什么开启通知后仍收不到提醒?
+
+依次检查:
+
+1. CodexBar「系统通知」总开关是否开启。
+2. macOS 系统设置是否允许 CodexBar 通知。
+3. 通知子面板中的对应类型是否开启。
+4. 额度数据是否可信,或任务类型是否需要 Hook。
+5. 任务完成耗时是否达到所选阈值。
+
+#### 为什么短任务没有完成通知?
+
+任务完成通知只针对达到所选时长阈值的任务,默认阈值为 1 分钟。
+
+#### 为什么短暂出现「等待批准」却没有通知?
+
+Hook 事件可能成批到达。CodexBar 会先处理完整批次;如果任务在同一批内已经恢复运行或完成,就不会发送已经过期的等待提醒。
+
+#### 为什么触觉反馈没有感觉?
+
+触觉需要通知总开关和任务触觉选项开启,也需要 Hook。最终反馈由输入设备、系统设置和辅助功能决定,部分鼠标或触控板不会产生明显反馈。
+
+### G. 快捷键、日志和更新
+
+#### 为什么无法直接覆盖当前快捷键?
+
+为避免录制时误触发当前全局快捷键,需要先点击叉号清除,再录制新组合。可以随时用回转箭头恢复 `⌘⇧W`。
+
+#### 为什么快捷键提示「至少需要两个修饰键」?
+
+全局快捷键必须至少组合 `Control`、`Option`、`Shift`、`Command` 中的两个,以减少和普通输入冲突。
+
+#### 日志窗口关闭后记录会消失吗?
+
+关闭日志窗口不会立即清空当前进程中的记录;点击日志顶部「清空」或退出 CodexBar 才会清除当前内存日志。
+
+#### 为什么设置中显示两个 Codex 版本?
+
+CodexBar 会同时探测全局 CLI 和 Codex.app 内置 CLI,并标记当前 app-server 实际使用的一项。这样可以排查「磁盘已经更新,但当前连接仍来自旧版本」的问题。
+
+#### 自动更新关闭后还能更新吗?
+
+可以。点击设置底部「检查更新」,或在发现更新后点击版本行右侧的更新按钮。
+
+## 11. 隐私与数据边界
+
+CodexBar 的主要账号、额度和 Token 数据通过本机 Codex app-server 获取并在本机处理。
+
+默认本机 Hook 数据位于:
+
+```text
+~/Library/Application Support/CodexBar/HookEvents/
+```
+
+CodexBar 最多保留最近 210 天的本机 Hook 事件和每日聚合。关闭 Hook 不会自动删除这些文件。当前版本没有单独的历史清除按钮;如需清除本机记录,应先关闭 Hook 和跨设备同步、退出 CodexBar,再通过 Finder 的「前往文件夹」检查并移除上述目录。已经上传到 CloudKit 的聚合不会因为删除本机目录而自动删除,当前版本也没有远端历史删除入口。
+
+CodexBar 不在 UI 中展示完整工作目录、会话 ID 或轮次 ID,也不会读取或展示 rollout 中的提示词、回复、推理和工具内容。
+
+只有以下功能会产生网络请求:
+
+- 查询手动重置机会的过期时间。
+- Sparkle 检查和下载更新。
+- 用户明确开启跨设备同步后的 CloudKit private database 请求。
+
+更详细的边界见 [README 隐私说明](../README.md#隐私)、[Codex Hook 文档](CodexHook.md) 和 [跨设备同步文档](CrossDeviceSync.md)。
diff --git a/README.md b/README.md
index 523b549..24ef63c 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,8 @@ CodexBar 在不打开 Codex CLI 或 Codex App 的情况下快速查看 Codex 账
<img src="Images/preview.gif" width="600">
</p>
+> 第一次使用或想了解所有可点击入口、状态含义和排障方法,请阅读[完整使用指南与常见问题](Docs/UserGuide.md)。
+
## 为什么需要 CodexBar
Codex 的额度、Token 用量和使用情况通常分散在终端、App 或 Session 中。CodexBar 把这些信息放到一个可随时呼出的菜单栏面板中,适合需要频繁使用 Codex、关注剩余额度和使用情况的 macOS 用户。
@@ -16,7 +18,7 @@ Codex 的额度、Token 用量和使用情况通常分散在终端、App 或 Ses
- 跟踪不同时间窗口的额度剩余比例和下一次重置时间
- 用 30 周热力图回顾每日 Token 用量
- 在开启 Codex Hook 后在 30 周热力图中可查看当天最热模型,以及会话、对话轮次、调用工具、权限请求、上下文压缩和子智能体统计 (仅在开启后可记录查看,无法查看到历史数据)
-- 通过菜单栏状态点和面板活动卡片实时查看 Codex 正在运行、等待批准及刚完成的任务
+- 通过菜单栏状态点、活动卡片和并发任务中心实时查看 Codex 正在运行、等待批准及刚完成的任务
- 通过可选 iCloud 私有数据库同步实现跨设备数据合并
- 额度告急、额度恢复、任务等待批准、长任务完成时收到系统通知(可选开启)
- 任务等待批准或结束时通过支持的触控板获得触觉反馈(可选开启)
@@ -39,7 +41,7 @@ CodexBar 是一个无 Dock 图标的 macOS 菜单栏应用。
开启 Codex Hook 后,菜单栏小人右下角的状态点会反映实时任务状态:运行中为蓝色、等待批准为橙色、刚完成为绿色,暂无活动时不显示。状态优先级依次为等待批准、运行中、刚完成和暂无活动;小人保持系统前景色,账号异常仍使用带叉图标表示,额度竖条也保持自己的颜色。
-菜单面板账号卡片下方会固定显示活动卡片,汇总当前项目、模型、工具、耗时和其他并发任务数量。绿色完成状态保留 20 秒,最近完成记录会在活动卡片保留 5 分钟;app-server 异常时活动卡片仍会继续展示本机 Hook 状态。
+菜单面板账号卡片下方会固定显示活动卡片,汇总当前项目、模型、工具、耗时和其他并发任务数量。主面板快照尚未加载时,活动卡片同步显示「暂无数据」且不开放任务中心;快照可用且存在活动任务、最近完成或最近终止记录时,点击卡片会打开并发任务中心,按等待确认、运行中、最近完成和最近终止分组展示全部任务。只有终止历史时,卡片会用灰色终止状态展示最近一项,不再显示「暂无 Codex 活动」。面板优先在菜单右侧展开,空间不足时自动切换到左侧。绿色完成状态保留 30 秒,最近完成和最近终止记录会保留 10 分钟;终止记录不触发完成提醒。
### 额度与重置时间一眼可见
@@ -59,7 +61,7 @@ CodexBar 是一个无 Dock 图标的 macOS 菜单栏应用。
统计结果会汇总到热力图详情面板中,不打断正常的 Codex 使用流程。
-主 App 还会在后台只读 Hook JSONL:启动时按块恢复最近 24 小时的活动,之后 tail 当天新增事件,并在内存中维护并发任务状态。跨日任务缺少起点时会按精确 session + turn 定向查找更早的 Prompt;对于仍处于运行或等待状态的精确 turn,CodexBar 会增量读取对应本机 Codex session rollout,仅用 `task_started` 回填缺失起点、用 `task_complete` 补齐缺失的结束、用 `turn_aborted` 静默清理中断任务。不读取提示词、回复、推理或工具内容。该实时状态用于菜单栏状态点、活动卡片、可选任务通知和触觉反馈,不新增历史状态文件,也不参与跨设备同步。
+主 App 还会在后台只读 Hook JSONL:启动时按块恢复最近 24 小时的活动,之后 tail 当天新增事件,并在内存中维护并发任务状态。跨日任务缺少起点时会按精确 session + turn 定向查找更早的 Prompt;对于仍处于运行、等待终态确认或等待批准状态的精确 turn,CodexBar 会每秒增量读取对应本机 Codex session rollout,仅用 `task_started` 回填缺失起点、用 `task_complete` 补齐缺失的结束、用 `turn_aborted` 清理中断任务并生成短暂的最近终止记录。同 session 新 Prompt 会让旧 turn 立即退出活动列表,但先保留 5 秒终态确认窗口,优先接受 rollout 或迟到 Hook 的完成/终止信号,仍无终态才记为终止。不读取提示词、回复、推理或工具内容。该实时状态用于菜单栏状态点、活动卡片、并发任务中心、可选任务通知和触觉反馈,不新增历史状态文件,也不参与跨设备同步。
CodexBar 只会追加或移除属于当前 CodexBar 可执行文件的 Hook,不会删除用户已有的其他 Codex Hook。
@@ -133,7 +135,7 @@ Codex Hook 工作流数据默认只保存在本机:
~/Library/Application Support/CodexBar/HookEvents/
```
-菜单栏实时任务状态只存在于当前 App 进程内。UI 只展示工作目录最后一级项目名,不展示完整路径;这份状态不会上传到 CloudKit,也不会产生新的网络请求。为补齐 Hook 缺失的起点、结束或中断信号,CodexBar 只对当前活跃 turn 增量读取 `~/.codex/sessions/` 或 `~/.codex/archived_sessions/` 下对应 rollout JSONL,解析生命周期事件、turn ID 和起止耗时;不会提取、保存或展示其中的提示词、回复、推理和工具内容。
+菜单栏实时任务状态只存在于当前 App 进程内。活动卡片和并发任务中心只展示工作目录最后一级项目名、模型、工具、阶段与耗时,不展示完整路径、会话 ID 或轮次 ID;这份状态不会上传到 CloudKit,也不会产生新的网络请求。为补齐 Hook 缺失的起点、结束或中断信号,CodexBar 只对当前活跃 turn 增量读取 `~/.codex/sessions/` 或 `~/.codex/archived_sessions/` 下对应 rollout JSONL,解析生命周期事件、turn ID 和起止耗时;不会提取、保存或展示其中的提示词、回复、推理和工具内容。
只有在用户开启「跨设备同步」后,CodexBar 才会通过 `CloudKit private database` 同步每日使用详情数据; 同步的数据副本只包含各个事件数量、项目聚合和模型名使用次数,不包含事件具体的数据。
@@ -153,6 +155,7 @@ xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/pl
## 项目文档
+- [完整使用指南与常见问题](Docs/UserGuide.md)
- [app-server 通信合约](Docs/AppServer.md)
- [Codex Hook 工作流统计](Docs/CodexHook.md)
- [跨设备同步](Docs/CrossDeviceSync.md)
diff --git a/appcast.xml b/appcast.xml
index fb6b7ca..dd7b38a 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.3.4</title>
+ <sparkle:version>42</sparkle:version>
+ <sparkle:shortVersionString>3.3.4</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.3.4</sparkle:releaseNotesLink>
+ <pubDate>Sun, 12 Jul 2026 10:14:23 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.3.4.dmg" sparkle:edSignature="X+JMSEHQ8WzjaREXFoLzTmZIa2NCWIBfoVwekABTdS2T8oBCv5htgZ1v3H9GGXYDPZ3ZLnWr5DlI8mM6HZhpDA==" length="3979311" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.3.3</title>
<sparkle:version>41</sparkle:version>