StandAlert

简体中文 · English · 日本語 · 한국어

工作与休息提醒工具。

持续显示当前工作或休息时长，在合适的时间温和提醒你离开屏幕，并用仅保存在本机的数据帮助你了解自己的节奏。

为什么使用 StandAlert

• 始终看得见，但不过度打扰。 菜单栏持续显示当前阶段与已用时间，提醒面板不会抢走正在使用的应用焦点。
• 休息由你决定。 到点后可以立即休息，也可以延后 1、5 或 15 分钟；休息引导可在菜单栏或独立窗口中显示。
• 顺应 macOS 使用习惯。 熄屏、合盖或系统睡眠时自动进入休息，达到休息目标后在唤醒时开始新的工作周期。
• 记录有用，不收集隐私。 工作、休息和延后事件只写入本机数据库，不需要账户，也不记录屏幕内容、网站或键盘输入。

功能概览

工作与休息

• 启动后自动开始新的工作计时
• 菜单栏以分钟精度显示当前阶段和已用时间，例如 12m、1h5m
• 休息临近时显示浮动倒计时面板
• 支持立即休息，或延后 1、5、15 分钟
• 轮换提供远眺、走动、活动肩颈和喝水引导
• 支持在菜单栏主界面或独立置顶窗口中显示休息引导
• 休息达到目标后可完成休息，未达到目标时也可以提前结束

本地统计

• 今日专注时长、休息次数和休息完成率
• 最近 7 天的专注与休息趋势
• 今日专注 / 休息时间占比
• 今日专注时段分布与最佳连续两小时专注窗口
• 统计记录异常时给出提示，避免把损坏数据当作正常结果

系统与可靠性

• 支持登录时启动
• 显示器熄屏、合盖或系统睡眠时自动开始休息
• 应用退出或检测到明显时钟变化时安全关闭当前计时段
• 异常退出后关闭不可靠的开放计时段，再开始新的工作计时
• 设置或本地存储异常时显示可恢复状态，不静默丢失记录

语言

界面默认跟随系统语言，也可以在设置中手动选择：

• 简体中文
• English
• 日本語
• 한국어

兼容性与系统要求

• 运行环境： macOS 14.0 或更高版本
• 当前验证环境： Xcode 搭配 macOS 26.5 SDK；SDK 版本不代表应用的最低运行版本
• 用于本机运行和 UI 测试的 Apple Development 签名团队

项目只使用 Apple 系统框架，包括 AppKit、SwiftUI、Charts、Core Data、ServiceManagement 和 Foundation，没有第三方依赖。

快速开始

1. 克隆仓库并进入项目目录：

   git clone https://github.com/fico308/StandAlert.git
   cd StandAlert

2. 打开 Xcode 项目：

   open StandAlert.xcodeproj

3. 在 Xcode 中选择 StandAlert target，打开 Signing & Capabilities，将 Team 改为你自己的开发团队。

4. 选择 StandAlert scheme 和 My Mac，点击 Run。

应用启动后不会显示 Dock 图标，而是直接在菜单栏开始工作计时。点击菜单栏中的 StandAlert 图标即可查看当前状态。

使用方法

1. 专注工作

打开 StandAlert 后无需手动开始。菜单栏会持续显示已工作时间，点击图标可以查看圆环进度、今日专注时长和设置入口。

2. 响应休息提醒

休息时间临近时，StandAlert 会在当前屏幕顶部显示浮动提醒。你可以：

• 点击“现在开始休息”进入休息引导
• 点击 +1m、+5m 或 +15m 延后本次提醒
• 暂时关闭面板；超过忽略期限后，应用会开始新的提醒周期

休息引导有两种显示方式：

• 主界面显示： 点击菜单栏图标查看引导并结束休息，这是默认方式。
• 独立弹窗： 自动打开置顶的固定尺寸休息窗口。

3. 让睡眠自动计入休息

如果当前正在工作，显示器熄屏、合盖或系统睡眠会自动结束当前工作并开始休息。熄屏到唤醒的完整时间会计入休息时长：

• 睡眠时间达到休息目标，唤醒后从零开始新的工作周期。
• 睡眠时间不足休息目标，唤醒后继续保持休息状态。

4. 查看统计

点击状态弹窗底部的统计入口，可以查看今日指标、最近 7 天趋势、专注 / 休息占比、小时分布和最佳专注时段。统计按照记录发生时的本地日期与时区计算，跨时区或夏令时变化也不会简单归入错误日期。

设置参考

设置	默认值	可选范围	生效时间
工作时长	50 分钟	5–180 分钟	下一个工作周期
休息目标	5 分钟	1–30 分钟	下一个工作周期
提前提醒	30 秒	关闭、10、30、60、120 秒	下一个工作周期
休息引导	主界面显示	主界面显示、独立弹窗	保存后立即生效
界面语言	跟随系统	简体中文、English、日本語、한국어	选择后立即生效
登录时启动	关闭	开启、关闭	保存后立即生效

提前提醒必须短于工作时长。无效或损坏的设置会按字段恢复为默认值，并在设置窗口中提示。

数据与隐私

StandAlert 不需要账户，也不会记录网站、应用内容、键盘输入或屏幕画面。计时事件与恢复状态保存在应用沙盒中的 SQLite 数据库：

~/Library/Containers/art.cloudmoon.StandAlert/Data/Library/Application Support/StandAlert/StandAlert.sqlite

你可以从应用的存储错误界面打开数据目录，也可以在“设置 → 历史记录”中删除全部本地历史。删除操作会暂停当前计时且无法撤销。

每次重新打开 StandAlert 都会使用最新设置从零开始新的工作段，之前保存的历史记录不会被删除。如果本地存储不可用，自动计时不会开始，应用会提供重试、打开数据目录或重置数据的入口。

开发

命令行构建

先在 Xcode 中配置自己的签名团队，然后运行：

xcodebuild \
  -project StandAlert.xcodeproj \
  -scheme StandAlert \
  -destination 'platform=macOS' \
  -derivedDataPath .build/DerivedData \
  build

运行测试

项目使用 Swift Testing 编写单元测试，并使用 XCTest 覆盖 macOS UI 流程：

xcodebuild \
  -project StandAlert.xcodeproj \
  -scheme StandAlert \
  -destination 'platform=macOS' \
  -derivedDataPath .build/DerivedData \
  -parallel-testing-enabled NO \
  test

UI 测试启动前请退出正在运行的 StandAlert 实例。macOS 自动化会话偶尔会延迟加载辅助功能；如果测试只因应用未加载辅助功能而超时，退出残留的 StandAlert 和测试 runner 后重试。

架构概览

NSStatusItem / AppKit 窗口协调
              │
              ▼
      SwiftUI 视图与 AppViewModel
              │
              ▼
          SessionEngine
              │
              ▼
    SessionReducer（纯状态转换）
              │
              ▼
 SessionStore（Core Data / SQLite）
              │
              ▼
        TodayAnalytics

• AppCoordinator 管理菜单栏、状态弹窗、提醒面板和独立窗口。
• SessionEngine 负责截止时间调度、心跳检查和持久化提交。
• SessionReducer 将命令转换为新状态和不可变事件，不直接操作 UI 或存储。
• SessionStore 同时保存生命周期事件和恢复快照，兼顾统计事实与快速恢复。
• 计时使用单调时钟计算持续时间，避免系统时间调整直接污染记录。

项目结构：

StandAlert/
├── App/           应用生命周期和窗口协调
├── Domain/        会话状态、命令和状态转换
├── Engine/        定时调度与副作用协调
├── Persistence/   Core Data、事件和恢复快照
├── Analytics/     今日与最近 7 天统计
├── Presentation/  展示状态与时间格式
├── Settings/      设置模型和校验
├── Time/          系统时钟与可测试时钟
└── UI/            状态弹窗、提醒面板、休息引导、统计和设置界面