Skip to content

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

feat: 优化设置窗口分页布局

Bob6bb8611d5259
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 8a10fa0..86058b8 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -250,6 +250,7 @@
B10000000000000000000033 /* Debug configuration for PBXNativeTarget "CodexBarHelper" */ = {
isa = XCBuildConfiguration;
buildSettings = {
+ "CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
CREATE_INFOPLIST_SECTION_IN_BINARY = YES;
CURRENT_PROJECT_VERSION = 1;
@@ -423,7 +424,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 54;
+ CURRENT_PROJECT_VERSION = 55;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -440,7 +441,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.5.0;
+ MARKETING_VERSION = 3.5.1;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar.debug;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -463,7 +464,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 54;
+ CURRENT_PROJECT_VERSION = 55;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -480,7 +481,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.5.0;
+ MARKETING_VERSION = 3.5.1;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/Controllers/NotificationOptionsPanelController.swift b/CodexBar/Controllers/NotificationOptionsPanelController.swift
index 712670f..c1dc888 100644
--- a/CodexBar/Controllers/NotificationOptionsPanelController.swift
+++ b/CodexBar/Controllers/NotificationOptionsPanelController.swift
@@ -3,13 +3,13 @@ import Combine
import SwiftUI
/// 通知子选项面板动作, 由 AppSettingsView 发出并在 SettingsWindowController 中路由
-nonisolated enum NotificationOptionsPanelAction: Equatable {
- case toggle(alignmentScreenFrame: CGRect?)
- case open(alignmentScreenFrame: CGRect?)
+nonisolated enum NotificationOptionsPanelAction {
+ case toggle
+ case open
case close
}
-/// 通知子选项面板控制器, 挂在设置窗口右侧, 复用侧边抽屉动效
+/// 通知子选项面板控制器, 挂在设置窗口右侧并保持底边对齐, 复用侧边抽屉动效
/// 与重置次数面板不同: 内容是交互控件, 用常驻 hosting controller + ObservableObject 驱动更新, 不替换 rootView
@MainActor
final class NotificationOptionsPanelController {
@@ -44,16 +44,15 @@ final class NotificationOptionsPanelController {
observeContentHeightChanges()
}
- var isVisible: Bool {
+ private var isVisible: Bool {
presenter.isVisible
}
- func owns(_ window: NSWindow?) -> Bool {
+ private func owns(_ window: NSWindow?) -> Bool {
window === panel
}
func toggle(
- alignmentScreenFrame: CGRect?,
relativeTo window: NSWindow?,
contentView: NSView?
) {
@@ -62,15 +61,10 @@ final class NotificationOptionsPanelController {
return
}
- show(
- alignmentScreenFrame: alignmentScreenFrame,
- relativeTo: window,
- contentView: contentView
- )
+ show(relativeTo: window, contentView: contentView)
}
func show(
- alignmentScreenFrame: CGRect?,
relativeTo window: NSWindow?,
contentView: NSView?
) {
@@ -84,20 +78,12 @@ final class NotificationOptionsPanelController {
panel.contentView?.layoutSubtreeIfNeeded()
let windowSurfaceFrame = SidePanelSupport.contentScreenFrame(for: contentView, in: window) ?? window.frame
let panelSize = measuredPanelSize()
- let validatedAlignmentFrame = SidePanelSupport.validatedAlignmentScreenFrame(
- alignmentScreenFrame,
- menuSurfaceFrame: windowSurfaceFrame
- )
let position = SidePanelSupport.position(
panelSize: panelSize,
menuSurfaceFrame: windowSurfaceFrame,
visibleFrame: (window.screen ?? NSScreen.main)?.visibleFrame ?? windowSurfaceFrame,
preferredSide: .right,
- proposedY: SidePanelSupport.alignedProposedY(
- panelSize: panelSize,
- menuSurfaceFrame: windowSurfaceFrame,
- alignmentScreenFrame: validatedAlignmentFrame
- )
+ proposedY: windowSurfaceFrame.minY
)
panel.level = window.level
@@ -251,18 +237,13 @@ final class NotificationOptionsPanelController {
return
}
- let currentFrame = panel.frame
- var targetFrame = NSRect(
- x: currentFrame.minX,
- y: currentFrame.maxY - size.height,
- width: size.width,
- height: size.height
- )
+ var targetFrame = panel.frame
+ targetFrame.size = size
if let visibleFrame = panel.screen?.visibleFrame {
- targetFrame.origin.y = max(
- targetFrame.origin.y,
- visibleFrame.minY + SidePanelSupport.Metrics.screenPadding
- )
+ let maximumY = visibleFrame.maxY - SidePanelSupport.Metrics.screenPadding
+ if targetFrame.maxY > maximumY {
+ targetFrame.origin.y = maximumY - targetFrame.height
+ }
}
NSAnimationContext.runAnimationGroup { context in
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index e2a8027..13864ea 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -72,31 +72,34 @@ final class SettingsWindowController: HostingWindowController {
onRebuildWorkflowData: onRebuildWorkflowData,
onNotificationOptionsAction: { [weak self] action in
self?.handleNotificationOptionsAction(action)
+ },
+ onContentHeightChanged: { [weak self] height in
+ self?.resizeContentHeight(height)
}
)
.environmentObject(viewModel)
.environmentObject(appUpdater)
)
- hostingController.sizingOptions = [.preferredContentSize]
+ hostingController.sizingOptions = []
let window = AuxiliaryHostingWindow(contentViewController: hostingController)
window.title = "CodexBar 设置"
window.styleMask = [.titled, .closable, .miniaturizable]
window.contentMinSize = Metrics.minimumContentSize
+ window.setContentSize(Metrics.initialContentSize)
return window
}
override func prepareForDisplay(_ window: NSWindow) {
- if let fittingSize = window.contentViewController?.view.validFittingSize {
- window.setContentSize(clampedContentSize(fittingSize, for: window))
- }
-
- super.prepareForDisplay(window)
+ window.setContentSize(clampedContentSize(window.contentLayoutRect.size, for: window))
+ positionForTabResizing(window)
}
private enum Metrics {
static let minimumContentSize = NSSize(width: 420, height: 240)
+ static let initialContentSize = NSSize(width: 430, height: 270)
static let maximumFallbackContentSize = NSSize(width: 560, height: 720)
+ static let maximumPreferredContentHeight: CGFloat = 500
static let screenInset: CGFloat = 80
}
@@ -112,15 +115,13 @@ final class SettingsWindowController: HostingWindowController {
private func handleNotificationOptionsAction(_ action: NotificationOptionsPanelAction) {
switch action {
- case let .toggle(alignmentFrame):
+ case .toggle:
notificationOptionsPanelController.toggle(
- alignmentScreenFrame: alignmentFrame,
relativeTo: window,
contentView: window?.contentViewController?.view
)
- case let .open(alignmentFrame):
+ case .open:
notificationOptionsPanelController.show(
- alignmentScreenFrame: alignmentFrame,
relativeTo: window,
contentView: window?.contentViewController?.view
)
@@ -129,6 +130,79 @@ final class SettingsWindowController: HostingWindowController {
}
}
+ private func resizeContentHeight(_ height: CGFloat) {
+ guard let window else {
+ return
+ }
+
+ let currentContentSize = window.contentLayoutRect.size
+ let targetContentSize = clampedContentSize(
+ NSSize(
+ width: currentContentSize.width,
+ height: min(height, Metrics.maximumPreferredContentHeight)
+ ),
+ for: window
+ )
+ let targetFrameHeight = window.frameRect(
+ forContentRect: NSRect(origin: .zero, size: targetContentSize)
+ ).height
+ guard abs(window.frame.height - targetFrameHeight) > 0.5 else {
+ return
+ }
+
+ var targetFrame = window.frame
+ let topEdge = targetFrame.maxY
+ targetFrame.size.height = targetFrameHeight
+ targetFrame.origin.y = topEdge - targetFrame.height
+ targetFrame = constrainedFrame(targetFrame, for: window)
+ window.setFrame(targetFrame, display: true)
+ }
+
+ private func positionForTabResizing(_ window: NSWindow) {
+ guard let screen = screenProvider() ?? window.screen ?? NSScreen.main else {
+ window.center()
+ return
+ }
+
+ let visibleFrame = screen.visibleFrame
+ let maximumContentHeight = min(
+ maximumContentSize(for: window).height,
+ Metrics.maximumPreferredContentHeight
+ )
+ let maximumFrameHeight = window.frameRect(
+ forContentRect: NSRect(
+ origin: .zero,
+ size: NSSize(
+ width: window.contentLayoutRect.width,
+ height: maximumContentHeight
+ )
+ )
+ ).height
+ let reservedTopEdge = visibleFrame.midY - maximumFrameHeight / 2 + maximumFrameHeight
+ window.setFrameOrigin(
+ NSPoint(
+ x: visibleFrame.midX - window.frame.width / 2,
+ y: reservedTopEdge - window.frame.height
+ )
+ )
+ }
+
+ private func constrainedFrame(_ frame: NSRect, for window: NSWindow) -> NSRect {
+ guard let screen = screenProvider() ?? window.screen ?? NSScreen.main else {
+ return frame
+ }
+
+ var constrainedFrame = frame
+ let visibleFrame = screen.visibleFrame
+ if constrainedFrame.minY < visibleFrame.minY {
+ constrainedFrame.origin.y = visibleFrame.minY
+ }
+ if constrainedFrame.maxY > visibleFrame.maxY {
+ constrainedFrame.origin.y = visibleFrame.maxY - constrainedFrame.height
+ }
+ return constrainedFrame
+ }
+
private func maximumContentSize(for window: NSWindow) -> NSSize {
guard let screen = screenProvider() ?? window.screen ?? NSScreen.main else {
return Metrics.maximumFallbackContentSize
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index 85822a4..3b42827 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -1,7 +1,7 @@
import AppKit
import SwiftUI
-/// 设置窗口根视图, 汇总启动项; 显示; Hook; 同步; 通知; 快捷键和版本信息
+/// 设置窗口根视图, 按通用; 工作流和关于分页汇总设置与版本信息
struct AppSettingsView: View {
@EnvironmentObject private var statusViewModel: CodexStatusViewModel
@EnvironmentObject private var appUpdater: AppUpdater
@@ -17,7 +17,9 @@ struct AppSettingsView: View {
let onSyncChanged: (Bool) -> Void
let onRebuildWorkflowData: WorkflowSyncScheduler.RebuildHandler
let onNotificationOptionsAction: (NotificationOptionsPanelAction) -> Void
- @State private var notificationRowFrame: CGRect?
+ let onContentHeightChanged: (CGFloat) -> Void
+ @State private var selectedTab = SettingsTab.general
+ @State private var isTabContentSettled = true
@State private var shouldOpenNotificationOptionsAfterAuthorization = false
@State private var rebuildableDates = [String]()
@State private var selectedRebuildRange: RebuildDateRange?
@@ -26,47 +28,36 @@ struct AppSettingsView: View {
@State private var rebuildStatus: RebuildStatus?
var body: some View {
- VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
- VStack(alignment: .leading, spacing: Metrics.rowSpacing) {
- launchAtLoginRow
- LiquidGlassDivider()
- automaticUpdateCheckRow
- LiquidGlassDivider()
- menuBarQuotaRow
- LiquidGlassDivider()
- hotKeyRow
- LiquidGlassDivider()
- codexHookRow
- LiquidGlassDivider()
- taskCenterRow
- LiquidGlassDivider()
- notificationRow
- LiquidGlassDivider()
- syncRow
- LiquidGlassDivider()
- keepAliveRow
- LiquidGlassDivider()
- rebuildWorkflowDataRow
- LiquidGlassDivider()
- codexVersionSection
- LiquidGlassDivider()
- versionRow
- }
- .padding(Metrics.panelPadding)
- .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
-
- settingsErrorPanel
-
- HStack(alignment: .center, spacing: 12) {
- quitButton
- Spacer()
- checkUpdateButton
+ VStack(spacing: 0) {
+ settingsTabBar
+ .padding(.top, Metrics.padding)
+ .padding(.bottom, Metrics.tabContentSpacing)
+
+ ScrollView(.vertical) {
+ selectedSettingsPage
+ .frame(maxWidth: .infinity, alignment: .top)
+ .background {
+ GeometryReader { proxy in
+ Color.clear.preference(
+ key: SettingsPageHeightPreferenceKey.self,
+ value: proxy.size.height
+ )
+ }
+ }
+ .padding(.horizontal, Metrics.padding)
+ .padding(.bottom, Metrics.padding)
}
- .padding(Metrics.panelPadding)
- .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
+ .id(selectedTab)
+ .scrollIndicators(.automatic)
+ .scaleEffect(
+ isTabContentSettled ? 1 : Metrics.tabContentInitialScale,
+ anchor: .top
+ )
+ .offset(y: isTabContentSettled ? 0 : Metrics.tabContentInitialOffset)
+ .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
}
- .padding(Metrics.padding)
.frame(width: Metrics.windowWidth)
+ .frame(maxHeight: .infinity, alignment: .top)
.liquidGlassSurface(
cornerRadii: RectangleCornerRadii(
topLeading: 0,
@@ -97,6 +88,31 @@ struct AppSettingsView: View {
isShowingRebuildConfirmation = false
clearRebuildStatus()
}
+ .onChange(of: selectedTab) { _, _ in
+ shouldOpenNotificationOptionsAfterAuthorization = false
+ onNotificationOptionsAction(.close)
+ }
+ .task(id: selectedTab) {
+ guard !isTabContentSettled else {
+ return
+ }
+
+ await Task.yield()
+ guard !Task.isCancelled else {
+ return
+ }
+
+ withAnimation(Metrics.tabContentTransition) {
+ isTabContentSettled = true
+ }
+ }
+ .onPreferenceChange(SettingsPageHeightPreferenceKey.self) { pageHeight in
+ guard pageHeight.isFinite, pageHeight > 0 else {
+ return
+ }
+
+ onContentHeightChanged(pageHeight + Metrics.windowChromeHeight)
+ }
.alert(
"批量重建 \(selectedRebuildDateKeys.count) 天的数据?",
isPresented: $isShowingRebuildConfirmation
@@ -113,21 +129,153 @@ struct AppSettingsView: View {
private extension AppSettingsView {
enum Metrics {
- static let padding: CGFloat = 20
+ static let padding: CGFloat = 12
static let windowWidth: CGFloat = 430
static let sectionSpacing: CGFloat = 18
static let rowSpacing: CGFloat = 14
static let panelPadding: CGFloat = 12
static let surfaceCornerRadius: CGFloat = 16
static let panelCornerRadius: CGFloat = 10
+ static let tabBarWidth = windowWidth - padding * 2
+ static let tabBarHeight: CGFloat = 38
+ static let tabBarPadding: CGFloat = 4
+ static let tabSpacing: CGFloat = 4
+ static let tabVerticalPadding: CGFloat = 7
+ static let tabContentSpacing = padding
+ static let windowChromeHeight = padding * 2 + tabBarHeight + tabContentSpacing
static let notificationOptionsButtonSize: CGFloat = 22
static let menuBarQuotaPickerWidth: CGFloat = 72
static let keepAliveDurationPickerWidth: CGFloat = 88
static let syncStatusRowHeight: CGFloat = 16
static let syncStatusValueWidth: CGFloat = 160
+ static let tabContentInitialScale = 0.975
+ static let tabContentInitialOffset: CGFloat = 8
+ static let tabContentTransition = Animation.spring(
+ response: 0.32,
+ dampingFraction: 0.74,
+ blendDuration: 0.08
+ )
static let statusAnimation = Animation.codexStatus
}
+ var settingsTabBar: some View {
+ HStack(spacing: Metrics.tabSpacing) {
+ ForEach(SettingsTab.allCases) { tab in
+ let isSelected = selectedTab == tab
+
+ Button {
+ selectSettingsTab(tab)
+ } label: {
+ HStack(spacing: 6) {
+ Image(systemName: tab.icon)
+ .foregroundStyle(isSelected ? Color.accentColor : Color.secondary)
+
+ Text(tab.title)
+ .foregroundStyle(isSelected ? Color.primary : Color.secondary)
+ }
+ .font(.subheadline.weight(.medium))
+ .frame(maxWidth: .infinity)
+ .padding(.vertical, Metrics.tabVerticalPadding)
+ .contentShape(Capsule(style: .continuous))
+ .background {
+ if isSelected {
+ Capsule(style: .continuous)
+ .fill(.clear)
+ .liquidGlassCapsule(tint: .accentColor)
+ }
+ }
+ }
+ .buttonStyle(.plain)
+ .frame(maxWidth: .infinity)
+ .accessibilityAddTraits(isSelected ? .isSelected : [])
+ }
+ }
+ .padding(Metrics.tabBarPadding)
+ .frame(width: Metrics.tabBarWidth, height: Metrics.tabBarHeight)
+ .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
+ }
+
+ func selectSettingsTab(_ tab: SettingsTab) {
+ guard selectedTab != tab else {
+ return
+ }
+
+ var transaction = Transaction(animation: nil)
+ transaction.disablesAnimations = true
+ withTransaction(transaction) {
+ isTabContentSettled = false
+ selectedTab = tab
+ }
+ }
+
+ @ViewBuilder
+ var selectedSettingsPage: some View {
+ switch selectedTab {
+ case .general:
+ generalSettingsPage
+ case .advanced:
+ advancedSettingsPage
+ case .about:
+ aboutSettingsPage
+ }
+ }
+
+ var generalSettingsPage: some View {
+ VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
+ VStack(alignment: .leading, spacing: Metrics.rowSpacing) {
+ launchAtLoginRow
+ LiquidGlassDivider()
+ automaticUpdateCheckRow
+ LiquidGlassDivider()
+ menuBarQuotaRow
+ LiquidGlassDivider()
+ hotKeyRow
+ }
+ .padding(Metrics.panelPadding)
+ .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
+
+ settingsErrorPanel
+ }
+ }
+
+ var advancedSettingsPage: some View {
+ VStack(alignment: .leading, spacing: Metrics.rowSpacing) {
+ codexHookRow
+ LiquidGlassDivider()
+ taskCenterRow
+ LiquidGlassDivider()
+ notificationRow
+ LiquidGlassDivider()
+ keepAliveRow
+ LiquidGlassDivider()
+ syncRow
+ LiquidGlassDivider()
+ rebuildWorkflowDataRow
+ }
+ .padding(Metrics.panelPadding)
+ .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
+ }
+
+ var aboutSettingsPage: some View {
+ VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
+ VStack(alignment: .leading, spacing: Metrics.rowSpacing) {
+ codexVersionSection
+ LiquidGlassDivider()
+ versionRow
+ }
+ .padding(Metrics.panelPadding)
+ .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
+
+ HStack(alignment: .center, spacing: 12) {
+ quitButton
+ Spacer()
+ checkUpdateButton
+ }
+ .padding(Metrics.panelPadding)
+ .liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
+ }
+ }
+
var launchAtLoginRow: some View {
SettingsToggleRow(
icon: "power",
@@ -551,7 +699,7 @@ private extension AppSettingsView {
)
) {
Button {
- onNotificationOptionsAction(.toggle(alignmentScreenFrame: notificationRowFrame))
+ onNotificationOptionsAction(.toggle)
} label: {
Image(systemName: "slider.horizontal.3")
}
@@ -568,11 +716,6 @@ private extension AppSettingsView {
.help("通知选项")
.animation(Metrics.statusAnimation, value: notificationSettings.canShowOptions)
}
- .background(
- ScreenFrameReader { frame in
- notificationRowFrame = frame
- }
- )
if notificationSettings.isEnabled, notificationSettings.isAuthorizationDenied {
notificationDeniedRow
@@ -590,7 +733,7 @@ private extension AppSettingsView {
if shouldOpenNotificationOptionsAfterAuthorization {
shouldOpenNotificationOptionsAfterAuthorization = false
- onNotificationOptionsAction(.open(alignmentScreenFrame: notificationRowFrame))
+ onNotificationOptionsAction(.open)
}
}
.onChange(of: notificationSettings.isAuthorizationDenied) { _, isDenied in
@@ -605,7 +748,7 @@ private extension AppSettingsView {
notificationSettings.setEnabled(enabled)
if enabled, notificationSettings.canShowOptions {
shouldOpenNotificationOptionsAfterAuthorization = false
- onNotificationOptionsAction(.open(alignmentScreenFrame: notificationRowFrame))
+ onNotificationOptionsAction(.open)
} else {
shouldOpenNotificationOptionsAfterAuthorization = enabled
&& !notificationSettings.isAuthorizationDenied
@@ -1070,6 +1213,46 @@ private struct KeepAliveCaption: Equatable {
var showsSystemSettingsButton = false
}
+private enum SettingsTab: CaseIterable, Identifiable {
+ case general
+ case advanced
+ case about
+
+ var id: Self {
+ self
+ }
+
+ var title: String {
+ switch self {
+ case .general:
+ "通用"
+ case .advanced:
+ "高级"
+ case .about:
+ "关于"
+ }
+ }
+
+ var icon: String {
+ switch self {
+ case .general:
+ "gearshape"
+ case .advanced:
+ "gearshape.2"
+ case .about:
+ "info.circle"
+ }
+ }
+}
+
+private struct SettingsPageHeightPreferenceKey: PreferenceKey {
+ static let defaultValue: CGFloat = 0
+
+ static func reduce(value: inout CGFloat, nextValue: () -> CGFloat) {
+ value = max(value, nextValue())
+ }
+}
+
private struct SyncRowState {
/// 由 WorkflowSyncSettings.isEffectivelyActive 统一判定, 视图层不再拼接业务谓词
let isActive: Bool
diff --git a/CodexBar/Views/Settings/NotificationOptionsView.swift b/CodexBar/Views/Settings/NotificationOptionsView.swift
index 441754d..64cda0a 100644
--- a/CodexBar/Views/Settings/NotificationOptionsView.swift
+++ b/CodexBar/Views/Settings/NotificationOptionsView.swift
@@ -1,7 +1,7 @@
import AppKit
import SwiftUI
-/// 通知子选项面板, 挂在设置窗口"系统通知"行右侧展开
+/// 通知子选项面板, 挂在设置窗口右侧并与设置内容区底边对齐
/// 通知开启时展开音效子行, 关闭时连同占位一起收起
struct NotificationOptionsView: View {
@ObservedObject var notificationSettings: NotificationSettings
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
index 3f9d807..7c614f3 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -938,7 +938,7 @@ CloudKit Production schema 必须包含当前 schema `4` 使用的字段;schem
- `MainPanelSettings.refresh()`
- `KeepAliveController.refresh()`
-设置窗口按 SwiftUI 内容 `fittingSize` 自适应高度, 但必须校验尺寸有限且夹紧到当前屏幕可见区域内的安全上限, 避免 SwiftUI 初始化或状态刷新重入时给出异常尺寸导致空白大窗口。`MenuBarQuotaSettings.refresh()` 可能被设置页 `onAppear` 和 `didBecomeActive` 调用, 发布 `selection` 时需要延后到下一轮 MainActor, 避免在 SwiftUI view update 中同步发布造成未定义布局行为。
+设置窗口内容宽度固定为 430 pt, 外层四周以及分页栏与内容卡片之间统一使用 12 pt 间距。当前分页通过 `SettingsPageHeightPreferenceKey` 回报实际内容高度, 窗口按「顶部间距 + 分页栏 + 中间间距 + 页面内容 + 底部间距」计算目标高度, 不再为各分页维护容易产生不等留白的固定高度; 超过 500 pt 或屏幕安全上限时由共享纵向 `ScrollView` 承接。Hosting controller 关闭 `preferredContentSize` 自动联动, SwiftUI 根视图始终贴住窗口顶部, 由 `SettingsWindowController` 统一控制窗口高度和底边。初次打开时控制器按最大视口高度预留居中位置; 切换分页固定标题栏和左上角且不使用窗口缩放动画, 旧页面立即替换, 只让新内容区从轻微缩小和下移状态通过弹簧动画回到原位, 避免过渡期间保留两份页面造成内容重叠; 顶部分页栏不参与布局动画。同时保留可见区域约束作为异常屏幕尺寸的兜底。`MenuBarQuotaSettings.refresh()` 可能被设置页 `onAppear` 和 `didBecomeActive` 调用, 发布 `selection` 时需要延后到下一轮 MainActor, 避免在 SwiftUI view update 中同步发布造成未定义布局行为。
`AppSettingsView.onAppear` 时刷新:
@@ -953,15 +953,19 @@ CloudKit Production schema 必须包含当前 schema `4` 使用的字段;schem
- `KeepAliveController.refresh()`
- `WorkflowStorage.rebuildableEventDateKeys()`
-App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主面板、Codex 版本、通知授权、防休眠 helper 状态和可重建日期, 并重新运行 `hooks/list` 验证。`SettingsWindowController.open()` 发布 `.settingsWindowDidOpen` 后, 日期重建范围、确认弹窗和上次结果消息恢复为未选择状态。
+App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主面板、Codex 版本、通知授权、防休眠 helper 状态和可重建日期, 并重新运行 `hooks/list` 验证。`SettingsWindowController.open()` 发布 `.settingsWindowDidOpen` 后, 日期重建范围、确认弹窗和上次结果消息恢复为未选择状态。窗口存活期间保留最后选择的分页; 切换分页时关闭通知选项侧面板。
版本探测内部有 60 秒节流, 避免 `onAppear` 和 `didBecomeActive` 连续触发时重复启动子进程
-设置项:
+设置项通过与现有 Liquid Glass 卡片一致的顶部分页栏分为:
-主设置卡片依次展示「开机自动启动」「自动检查更新」「菜单栏额度指示」「设置快捷键」「CodexBar Hook」「主面板任务中心」「系统通知」「跨设备同步」「阻止系统休眠」「重建数据」「Codex 版本」和「CodexBar 版本」。
+- 「通用」: 开机自动启动、自动检查更新、菜单栏额度指示和设置快捷键
+- 「高级」: CodexBar Hook、主面板任务中心、系统通知、阻止系统休眠、跨设备同步和重建数据
+- 「关于」: Codex 版本、CodexBar 版本、检查更新和退出 CodexBar
-跨设备同步开启时,状态子行始终保留固定 16 pt 高的单行布局;右侧固定宽度 `ZStack` 让同步时间和 `.mini` 进度指示以交叉淡入淡出切换,不对 AppKit 进度控件应用几何缩放,也不改变该行高度或控件位置。关闭同步后移除整行占位,让设置窗口 fitting size 随开关状态缩回。
+窗口首次创建时默认进入「通用」, 后续关闭再打开沿用本次 App 运行期间最后选择的分页。检查更新和退出操作只在「关于」底部操作卡片展示。
+
+跨设备同步开启时,状态子行始终保留固定 16 pt 高的单行布局;右侧固定宽度 `ZStack` 让同步时间和 `.mini` 进度指示以交叉淡入淡出切换,不对 AppKit 进度控件应用几何缩放,也不改变该行高度或控件位置。关闭同步后移除整行占位, 让工作流页面回收对应的行内空间。
| 设置项 | 状态源 | 写入行为 |
| -------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1159,7 +1163,7 @@ App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主
活动并发以 session 为边界:不同 session 可以同时运行;同一 session 的 turn 按顺序执行。收到新的 `UserPromptSubmit` 时,monitor 会让该 session 中更早且缺少结束信号的 turn 立即退出活动列表,但保留为等待终态确认任务并触发一次即时 rollout 查询;5 秒内收到 Hook `Stop`、rollout `task_complete` 或 `turn_aborted` 时按真实终态归类,到期仍无终态才生成灰色最近终止记录。子 Agent 事件只能通过共享 session 关联父任务,早于当前顶层任务可信开始时间的事件会被当作上一 turn 的迟到事件忽略。已完成和已终止任务键分别保留 24 小时 tombstone,避免迟到事件恢复旧任务或误操作同 session 的新 turn。终止不会触发绿色完成状态、长任务通知或完成触觉反馈。Hook `Stop` 与 rollout `task_complete` 均视为完成信号,先到者生效,后到者按任务键和 session 回退键去重;重复完成不会覆盖首次确认结果,也不会缩短去重窗口或再次触发反馈。
-设置页交互: 「系统通知」主开关行保留在设置窗口内, 子选项 (五类通知子开关与声音、任务触觉开关、Codex TUI 通知开关及两个阈值 Picker) 在主选项右侧的子面板中展开 (`NotificationOptionsPanelController`, 复用 SidePanelSupport 抽屉机制挂在设置窗口上, 内容用常驻 hosting controller + ObservableObject 驱动)。五类通知按需使用双行布局:第一行展示通知名称、可选阈值和开关,阈值 Picker 位于开关前;通知开启且依赖可用时,第二行展示「通知音效」、加宽的声音菜单和独立播放按钮,关闭时整行从布局移除。控制器订阅五类通知开关和 Hook 状态;入场期间暂停 fitting-size 更新,动画完成后重新测量,后续内容变化在 SwiftUI 完成布局后按 fitting size 动画调整面板高度并保持面板顶边位置,避免收起后残留空白。菜单顶层提供默认和静音,其他声音按「经典提示音」和「现代提示音」子菜单分组。选择任意声音时立即试听,播放按钮可重复试听当前非静音选项,新的试听会停止上一段自定义声音;默认使用 `NSSound.beep()`, 静音不播放预览且禁用播放按钮,其余声音优先播放 App 包内与正式通知同源的 WAV。选项依次排列为「任务完成通知」「任务等待通知」「额度预警通知」「额度重置通知」「重置临期通知」「任务触觉反馈」和「Codex TUI 通知」。主开关开启后仅在系统授权允许时展开, 首次授权场景会等待授权结果; 点击行内滑杆按钮可手动展开; 设置窗口 resign key/关闭、主开关关闭或授权变为被拒时自动收起。任务完成、任务等待与任务触觉子项在 Hook 未开启时显示为关闭并置灰, 不修改各自持久化偏好及声音, Hook 重新开启后恢复用户原选择。「Codex TUI 通知」与用户级 `[tui] notifications` 联动,面板打开时刷新,写入后回读验证;已有 CLI 会话需重启后生效。该项不服从 CodexBar 通知发送判定,也不修改顶层 `notify`。「主面板任务中心」沿用相同依赖语义;关闭只隐藏活动卡片和任务中心入口,不停止 Monitor、状态点、通知或触觉反馈。授权被拒的引导文案与"打开系统设置"按钮仍内联显示在主开关行下方, 插入提示时不触发设置项纵向动画。
+设置页交互: 「系统通知」主开关行保留在设置窗口内, 子选项 (五类通知子开关与声音、任务触觉开关、Codex TUI 通知开关及两个阈值 Picker) 在设置窗口右侧的子面板中展开 (`NotificationOptionsPanelController`, 复用 SidePanelSupport 抽屉机制挂在设置窗口上, 内容用常驻 hosting controller + ObservableObject 驱动)。子面板不再读取通知行作为纵向锚点, 初次展开时底边与设置窗口内容区底边对齐。五类通知按需使用双行布局:第一行展示通知名称、可选阈值和开关,阈值 Picker 位于开关前;通知开启且依赖可用时,第二行展示「通知音效」、加宽的声音菜单和独立播放按钮,关闭时整行从布局移除。控制器订阅五类通知开关和 Hook 状态;入场期间暂停 fitting-size 更新,动画完成后重新测量,后续内容变化在 SwiftUI 完成布局后按 fitting size 动画调整面板高度并保持面板底边位置, 只在超过屏幕顶部安全边界时修正位置。菜单顶层提供默认和静音,其他声音按「经典提示音」和「现代提示音」子菜单分组。选择任意声音时立即试听,播放按钮可重复试听当前非静音选项,新的试听会停止上一段自定义声音;默认使用 `NSSound.beep()`, 静音不播放预览且禁用播放按钮,其余声音优先播放 App 包内与正式通知同源的 WAV。选项依次排列为「任务完成通知」「任务等待通知」「额度预警通知」「额度重置通知」「重置临期通知」「任务触觉反馈」和「Codex TUI 通知」。主开关开启后仅在系统授权允许时展开, 首次授权场景会等待授权结果; 点击行内滑杆按钮可手动展开; 设置窗口 resign key/关闭、主开关关闭或授权变为被拒时自动收起。任务完成、任务等待与任务触觉子项在 Hook 未开启时显示为关闭并置灰, 不修改各自持久化偏好及声音, Hook 重新开启后恢复用户原选择。「Codex TUI 通知」与用户级 `[tui] notifications` 联动,面板打开时刷新,写入后回读验证;已有 CLI 会话需重启后生效。该项不服从 CodexBar 通知发送判定,也不修改顶层 `notify`。「主面板任务中心」沿用相同依赖语义;关闭只隐藏活动卡片和任务中心入口,不停止 Monitor、状态点、通知或触觉反馈。授权被拒的引导文案与"打开系统设置"按钮仍内联显示在主开关行下方, 插入提示时不触发设置项纵向动画。
`NotificationOptionsView` 的两个实际行构建器保留 `@_optimize(none)`:Swift 6.3.3 在 `-O` 下优化这些包含原生 mini Switch 的动态布局时会漏绘开关 thumb。该约束只覆盖 `optionRow` 和带 accessory 的 `notificationOptionRow` 实现,其余通知视图与 Release target 继续使用正常优化;调整这两个构建器的编译属性后需要用 Release 产物人工检查开启状态的 thumb。
diff --git a/Docs/UserGuide.md b/Docs/UserGuide.md
index 2f105a3..b7b33e6 100644
--- a/Docs/UserGuide.md
+++ b/Docs/UserGuide.md
@@ -292,25 +292,116 @@ Token 用量和 Hook 工作流统计来自不同功能。请确认当天使用 C
### 防止任务因系统休眠中断
-开启设置中的「阻止系统休眠」后,CodexBar 会在至少一个任务真正运行时同时阻止空闲、合盖和手动系统休眠,因此 MacBook 合盖后任务仍可继续。首次开启需要在 macOS「登录项与扩展」中允许 CodexBar 后台运行;设置行出现提示时点击「打开系统设置」,允许后回到 CodexBar。
+长时间运行 Codex 任务时,即使任务本身没有结束,macOS 也可能因为长时间无人操作或 MacBook 合盖而进入休眠。开启「阻止系统休眠」后,CodexBar 会根据 Hook 提供的实时任务状态,只在确实还有任务运行时暂时阻止系统休眠;没有其他任务运行时,任务等待你处理、已经结束或超过保护时限后,会把休眠控制权交还给 macOS。
-开启后可选择最长防休眠期限:1、2、4、8、12、24 小时或无限制,默认 12 小时。CodexBar 只维护一个计时周期;每次启动新的运行任务,或同一任务等待用户批准后恢复运行,都会从这次启动或恢复的时间重新计时。同一任务继续产生普通 Hook 活动不会顺延,无限制不会自动到期。进入等待批准、任务完成或终止、没有活动任务、关闭功能以及达到有限期限时,CodexBar 都会恢复任务开始前的休眠设置,并释放运行期间持有的空闲休眠 assertion。macOS 随即根据当前空闲时间、用户活动、其他 App 的 assertion 和系统电源策略重新判断是否应休眠,所以开盖状态如果已经满足空闲休眠条件也可以立即进入休眠;CodexBar 不会绕过其他系统条件强制休眠。普通合盖且系统确认此次合盖应休眠时,CodexBar 还会主动请求系统休眠;外接显示器合盖工作或电脑原本就全局禁止休眠时不会强制休眠。即使旧任务仍在运行,之后启动新任务或等待任务获批恢复也会立即重新阻止休眠并开始完整的新周期。到期后改为无限制,或选择按当前起点计算后仍未到期的更长期限,也会继续当前周期。
+这个功能适合编译、分析、批量修改等需要离开电脑继续运行的长任务。它不是一个让 Mac 永久保持唤醒的总开关,也不会改变每个任务本身的执行逻辑。
-该选项依赖 Codex Hook。关闭 Hook 时,防休眠选项会自动关闭并置灰,同时恢复任务开始前的系统休眠设置;重新开启 Hook 后不会自动恢复该选项,需要手动再次开启。
+#### 它能阻止什么
-这个开关使用与活动卡片相同的任务状态:
+功能生效时,CodexBar 会同时处理几种常见的系统休眠来源:
-| 实时状态 | 是否阻止休眠 |
-| -------------------------- | ------------ |
-| 至少一个任务正在运行 | 是 |
-| 所有任务都在等待用户批准 | 否 |
-| 任务全部完成或终止 | 否 |
-| 已达到最近任务的防休眠上限 | 否 |
-| Hook 关闭或没有活动任务 | 否 |
+| 使用场景 | CodexBar 的行为 |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Mac 开盖,但长时间没有键盘鼠标操作 | 阻止系统因空闲而休眠 |
+| MacBook 合盖 | 阻止普通合盖休眠,让正在运行的任务继续 |
+| 从 Apple 菜单等位置手动请求休眠 | 正在保护任务时阻止这次系统休眠 |
+| 屏幕自动熄灭或系统锁屏 | 不阻止;屏幕熄灭和系统休眠是两件事,屏幕关闭时任务仍可继续 |
+| 关机、重启、断电或电量耗尽 | 无法阻止 |
+| 网络中断、Codex 报错或任务自身终止 | 无法阻止;这个功能只控制系统休眠,不保证任务一定成功 |
-等待批准只指 Codex 已确认需要你处理的请求;由自动 reviewer 继续处理的权限请求仍属于运行中。多个并发任务里只要还有一个运行任务,CodexBar 就会继续阻止休眠。任务不再运行或达到期限后会恢复任务开始前的系统休眠设置;新的运行任务以及同一任务从等待恢复都会更新所有运行任务共享的计时起点,并获得完整的新期限。
+如果你希望立即让 Mac 休眠,请先停止正在运行的任务,或直接关闭「阻止系统休眠」后再操作。开关仍然开启时,可以用设置行是否显示「当前允许系统休眠」确认任务已经不再受到保护。
-合盖运行会持续耗电并产生热量。请保持 Mac 通风,不要把仍在运行任务的电脑放进密闭包中;电量不足时请主动停止任务或关闭该选项。
+#### 开启与授权
+
+1. 打开设置并先开启「CodexBar Hook」。
+2. 开启「阻止系统休眠」,再从右侧菜单选择「最长阻止时间」。
+3. 首次开启时,如果设置行显示「需要授权允许 CodexBar 后台运行」,点击「打开系统设置」。
+4. 在 macOS「系统设置」→「通用」→「登录项与扩展」的 App 后台活动列表中允许 CodexBar,然后回到 CodexBar。设置行会在 App 再次激活时自动刷新。
+5. 启动一个 Codex 任务;设置行显示「当前禁止系统休眠」时,说明功能已经生效。没有任务运行时显示「当前允许系统休眠」是正常状态。
+
+这项功能必须依赖 Hook,因为 CodexBar 需要靠 Hook 分辨任务是在运行、等待批准还是已经结束。关闭 Hook 时,防休眠开关会自动关闭并置灰,系统休眠设置也会恢复;之后重新开启 Hook,不会自动重新开启防休眠,需要由你再次确认。
+
+「App 后台活动」授权和设置中的「开机自动启动」是两件事。前者允许随 App 安装的后台辅助服务切换和恢复系统休眠设置,后者决定登录后是否自动打开 CodexBar 主应用。
+
+#### 什么时候会真正阻止休眠
+
+设置开关保持开启只表示“允许 CodexBar 在需要时保护任务”,不表示系统此刻一定不能休眠。CodexBar 使用与活动卡片和任务中心相同的实时状态来决定是否生效:
+
+| 当前任务情况 | 是否阻止系统休眠 | 原因 |
+| ------------------------------------ | ---------------- | -------------------------------- |
+| 至少有一个任务正在运行 | 是 | 仍有实际工作需要继续 |
+| 一部分任务等待批准,另一部分仍在运行 | 是 | 只要还有一个任务运行,就继续保护 |
+| 所有任务都在等待用户批准 | 否 | Codex 已经暂停工作,等待你的操作 |
+| 任务全部完成、终止或不再活动 | 否 | 没有需要继续保护的任务 |
+| 已达到最长阻止时间 | 否 | 防止异常任务让电脑无限期保持唤醒 |
+| Hook 关闭或防休眠开关关闭 | 否 | CodexBar 不再接管系统休眠 |
+
+“等待用户批准”只指 Codex 已经确认需要你亲自处理的请求。某些权限请求会由自动审核流程继续处理,这时任务仍算运行中,CodexBar 也会继续阻止休眠。
+
+一个常见过程是:任务运行时阻止休眠;任务停下来等待你批准时恢复系统休眠;你批准后任务重新开始运行,CodexBar 再次阻止休眠。这样可以保护真正执行中的工作,又不会在任务整晚等待输入时持续耗电。
+
+#### 最长阻止时间
+
+可选时限为 1、2、4、8、12、24 小时或无限制,默认是 12 小时。这个时限不是任务超时时间:到期只会允许系统重新休眠,不会取消、终止或修改 Codex 任务。
+
+多个任务共享同一个防休眠周期,而不是每个任务各自倒计时。周期按下面的方式计算:
+
+- 第一个运行任务出现时开始计时。
+- 后来又启动一个新任务时,从新任务启动的时刻重新获得完整时限。
+- 等待批准的任务获批并恢复运行时,也从恢复时刻重新获得完整时限。
+- 同一任务只是继续输出内容、调用工具或产生普通 Hook 活动,不会延长时限。重新打开设置、激活 CodexBar 或刷新状态也不会延长。
+- 所有运行和等待任务都消失后,当前周期结束;下次出现任务时重新计时。
+- 关闭再开启防休眠后,如果此时仍有任务运行,会建立一个新的周期。
+
+例如,最长时间设为 12 小时:任务 A 在 10:00 启动,原本会保护到 22:00;任务 B 在 15:00 新启动后,共享截止时间会改为次日 03:00。A 或 B 的普通进度更新不会继续顺延。如果任务在 16:00 等待你批准,并在 16:30 获批恢复运行,则会从 16:30 再获得完整的 12 小时。
+
+达到上限后,即使原任务仍显示运行中,CodexBar 也会恢复系统休眠;该任务后续的普通活动不会自动重新开启保护。此后启动新任务,或让等待批准的任务恢复运行,才会开始新的完整周期。
+
+运行中修改时限会按当前周期的起点重新计算。改成更短时,如果新时限已经过去,会立即恢复休眠;改成更长时,只要按新时限计算还没有到期,就会继续保护。改成「无限制」会取消本周期的自动到期限制,但仍会在任务等待、结束、功能关闭或 CodexBar 退出时恢复系统休眠。无限制可能显著增加耗电,建议只在明确需要时使用。
+
+#### 任务停止运行后会发生什么
+
+开始保护任务前,CodexBar 会记住电脑原本的休眠设置;结束保护时恢复这个原始状态,而不是一律强制开启休眠。因此,如果你在任务开始前已经通过其他工具全局禁止休眠,CodexBar 结束后会保留那个选择。相反,也不建议在保护期间同时使用其他工具修改同一项全局休眠设置,因为结束时 CodexBar 会按任务开始前记录的状态恢复。休眠设置作用于整台 Mac,也应避免同时运行来自不同安装位置的多个 CodexBar。
+
+恢复设置不等于无条件让电脑立刻睡眠。CodexBar 会先交还休眠控制权,再让 macOS 根据已经累计的空闲时间、最近是否有人操作、其他 App 是否也在阻止休眠以及当前电源策略重新判断:
+
+- Mac 开盖时,如果早已达到系统设定的空闲时间,可能很快进入休眠;如果你刚操作过电脑,或其他 App 仍在保持唤醒,也可能继续运行。
+- MacBook 普通合盖、没有处于外接显示器合盖工作模式,并且任务开始前的设置允许休眠时,CodexBar 会在恢复设置后请求系统进入休眠。
+- MacBook 合盖连接外接显示器,并且 macOS 允许合盖工作时,只恢复原设置,不会强制休眠。
+
+正常退出 CodexBar 时会主动恢复休眠设置。如果 App 意外退出或与后台服务失去连接,后台服务会根据此前保存的恢复记录进行兜底,通常在约 15 秒的宽限时间后恢复。这个短暂等待是为了避免 CodexBar 更新或快速重连时来回切换系统状态。
+
+关闭防休眠后,CodexBar 的后台项目仍可能继续出现在「登录项与扩展」列表中,这不表示系统仍被禁止休眠。保留后台服务是为了下次启用以及在异常情况下完成恢复;是否正在阻止休眠,应以 CodexBar 设置行的当前状态为准。
+
+#### 后台权限与隐私
+
+之所以需要后台项目授权,是因为普通 App 只能可靠阻止空闲休眠,无法保证 MacBook 合盖后继续运行。CodexBar 使用随 App 一起签名的 CodexBarHelper 完成必要的系统级切换。
+
+这个辅助服务的能力受到严格限制:它只响应同一签名的 CodexBar,只能在“阻止休眠”和“恢复原设置”之间切换,并在本机保存一条用于异常恢复的状态记录。它不能接收任意命令或文件路径,不访问网络,也不读取 Codex 账号、提示词、回复、任务内容、会话信息或 Hook 原始记录。你不需要在终端运行 `sudo` 或手动修改系统休眠设置。
+
+#### 状态提示与排查
+
+| 设置行提示 | 表示什么 | 建议操作 |
+| ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------- |
+| 需要启用 CodexBar Hook | CodexBar 无法取得可靠的实时任务状态 | 先开启 Hook;重新开启 Hook 后还要手动重新开启防休眠 |
+| 需要授权允许 CodexBar 后台运行 | 后台服务已经注册,但仍在等待 macOS 授权 | 点击「打开系统设置」,在「登录项与扩展」中允许 CodexBar |
+| CodexBarHelper 尚未注册 | 后台服务还没有准备好 | 短暂出现可等待刷新;持续显示时确认 App 位于「应用程序」并重新安装 |
+| 当前允许系统休眠 | 功能已就绪,但当前没有需要保护的运行任务 | 通常无需处理;查看活动卡片确认任务是否正在运行 |
+| 当前禁止系统休眠 | 至少一个任务正在运行,保护已经生效 | 可以继续使用或合盖运行,同时注意散热和电量 |
+| 已达到禁用休眠上限 | 当前周期已经到期,系统休眠设置已恢复 | 需要继续时启动新任务、恢复等待任务,或重新评估最长阻止时间 |
+| 红色错误信息 | 注册、连接或切换休眠状态失败 | 打开日志查看最新错误;持续失败时退出并重新打开或重新安装 CodexBar |
+
+如果设置显示「当前允许系统休眠」,但你认为任务仍在运行,先查看活动卡片和任务中心:任务可能已经进入等待批准,或者当前周期已经达到上限。如果活动卡片也无法正确显示状态,请先排查 Hook。
+
+如果合盖后任务仍然停止,请依次确认:Hook 和防休眠开关都已开启;后台项目已经授权;合盖前设置行显示「当前禁止系统休眠」;当前周期尚未达到上限;任务不是在等待批准。还应检查任务是否因为断网、Codex 错误或其他与休眠无关的原因停止。
+
+如果功能关闭后 Mac 没有立刻休眠,这通常不表示恢复失败。macOS 仍会考虑最近的用户操作、其他 App 的唤醒请求和系统电源策略。只有设置行出现红色错误,或长时间无法恢复正常状态时,才需要查看日志进一步处理。
+
+#### 使用安全
+
+合盖运行会持续耗电并产生热量,CodexBar 不会根据低电量自动结束防休眠。请确保 Mac 通风良好,接通合适的电源,不要把仍在运行任务的电脑放进背包、保护套或其他密闭空间。需要携带电脑前,请停止任务并确认设置行已经显示「当前允许系统休眠」,或直接关闭该功能后再合盖携带。
+
+系统更新、关机、断电和电池耗尽仍会中断任务。对于无法轻易重跑的重要任务,建议同时保存中间结果,不要把防休眠功能当作任务可靠性的唯一保障。
### 活动卡片图标
diff --git a/appcast.xml b/appcast.xml
index 45fef85..56dbd56 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.5.1</title>
+ <sparkle:version>55</sparkle:version>
+ <sparkle:shortVersionString>3.5.1</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.5.1</sparkle:releaseNotesLink>
+ <pubDate>Sat, 25 Jul 2026 11:45:55 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.5.1.dmg" sparkle:edSignature="O1TzaDZPnX0hYJs+ZhJjz8CWU2Fdzm+xpX+j6a9eyPifD1J07J7KKeSukdAMw6T4hYrzLfQelbQc2P9+HoVtDQ==" length="5843097" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.5.0</title>
<sparkle:version>54</sparkle:version>