TaskMate

macOS 图形化本地脚本定时器：用 GUI 管理 launchd、Python、Shell、Node.js 等任务。

简体中文 · English

TaskMate 是一个面向 macOS 的本地任务调度器和脚本自动化工具。它用图形界面创建每天或按间隔执行的任务，不需要手写 launchd plist，也不需要把脚本改造成服务。选择脚本或可执行文件、确认本机运行环境并设置计划后，TaskMate 会负责后台执行、失败重试、超时控制、错过计划处理和运行日志；即使退出 App，任务也能继续按计划执行。

如果你正在寻找 macOS 定时任务 GUI、launchd 图形界面、cron 替代方案、本地 Python 定时运行、Shell 脚本定时器或 Node.js 任务调度器，TaskMate 就是这类工具。它适合个人自动化、数据采集、备份、报告生成、开发脚本和长期运行的本地任务。

当前版本为 0.2.0，仍处于早期开发阶段。请先保留重要脚本和数据的备份，并通过运行历史确认任务符合预期。

适合谁

• 想定时运行本地脚本，但不想学习 launchd 和 plist 的用户
• 需要管理多个 Python、Shell、Node.js 或其他可执行程序的开发者
• 需要查看每次执行结果、错误输出和重试过程，而不是只知道“任务失败”的用户

TaskMate 只在本机运行，不上传脚本、参数、环境变量或日志。

它解决什么问题

macOS 的 launchd 很强大，但创建和排查任务通常需要编辑 plist、使用命令行，并处理非交互环境下的 PATH、解释器和文件权限问题。TaskMate 把这些细节收敛到一个本地 App 中，同时保留任务执行所需的透明度。

• 不熟悉 launchd 也能创建和管理定时任务
• 明确选择 Python、Shell、Node.js 等本机运行环境
• 直接查看每次执行的状态、耗时、退出码、stdout 和 stderr
• 对睡眠错过、失败重试、运行超时和重复执行作出明确处理
• 所有任务配置和日志都保存在本机，不依赖账号或云服务

核心功能

• 创建、编辑、启用、暂停和删除任务
• 创建前实际运行检查，以及创建后的手动运行和停止
• 每天从指定时间执行，或每隔 N 分钟/小时执行
• 两种计划都可添加随机延迟，并始终保持原计划节奏
• 可配置错过计划后的补跑期限，且不会跨过下一轮计划
• 可配置失败重试次数、重试间隔和最长运行时间
• 区分脚本错误、依赖缺失、环境配置错误、超时和用户取消等结果
• 自动发现 Python、Shell、Node.js、Ruby、PHP、Perl 和 Swift
• 自动发现运行环境，也可按类型手动添加一个默认环境；不安装解释器或依赖
• 运行检查、手动运行和计划任务统一由用户级 LaunchAgent 托管的后台 Helper 执行
• 三种运行方式使用同一个后台执行身份，权限与结果保持一致
• 识别桌面、文稿和下载目录的后台访问失败；停止无意义重试、暂停当前计划并提供修复入口
• 启动时检查后台配置和 Helper 心跳，并自动修复可恢复的问题
• 运行历史、按尝试查看日志、日志保留与大小限制
• 防止同一任务重复运行，并在超时时终止整个进程组

TaskMate 目前只面向当前 Mac，不提供云同步、账号系统、远程执行、任务依赖或复杂工作流。

它也不会安装 Python、Node.js、虚拟环境、包管理器或脚本依赖；运行环境和依赖由用户自己维护。

安装

从项目的 GitHub Releases 下载最新的 TaskMate-<version>.dmg，打开后将 TaskMate 拖入“应用程序”。

当前无需付费开发者账户的发行包使用 ad-hoc 签名。从网络下载后，macOS 首次打开时可能要求你在“系统设置 → 隐私与安全性”中确认。产品名称和版本号不因此附加额外渠道标记。

完整步骤和 SHA-256 校验方式见安装与首次打开说明。TaskMate 不会主动唤醒睡眠或关机中的 Mac；设备恢复后会按任务的补跑期限决定执行一次或记录为已错过。

基本使用

1. 点击工具栏中的“新建任务”，选择脚本或可执行文件。
2. 确认 TaskMate 发现的运行环境。
3. 选择“每天一次”或“按间隔执行”，按需启用随机延迟并确认错过计划的处理方式。
4. 普通任务可直接使用推荐规则；参数和工作目录、运行保护分别放在两个明确的折叠区中。
5. 强烈建议使用“实际运行一次”。它会通过与自动任务相同的后台 Helper 检查系统文件权限、运行环境和依赖；长任务可随时停止，检查期间不会允许保存或关闭编辑器。
6. 首次保存任务时启用本机后台执行服务；之后可在“设置 → 后台执行”查看状态。运行检查、手动运行和计划任务都依赖这个服务。
7. 在任务详情的运行历史中查看结果和输出。

测试或正式运行提示依赖缺失时，请在所选运行环境中自行安装。首次创建任务前建议执行“实际运行一次”，提前处理文件权限、解释器和依赖问题。

自行构建

环境要求

• macOS 13 或更高版本
• Xcode（工程当前使用 Swift 6；建议使用包含 Swift 6.1 或更高版本的 Xcode）
• 系统 SQLite 开发库（由 macOS SDK 提供）

使用 Xcode

克隆仓库并打开工程：

git clone https://github.com/mr-hanlu/TaskMate.git
cd TaskMate
open TaskMate.xcodeproj

在 Xcode 中选择 TaskMate scheme 后运行即可。

使用命令行

运行核心与界面模型测试：

swift test

构建无需开发者证书的本地 Debug App：

xcodebuild \
  -project TaskMate.xcodeproj \
  -scheme TaskMate \
  -configuration Debug \
  -derivedDataPath .build/xcode-derived \
  CODE_SIGNING_ALLOWED=NO \
  build

生成可分发的正常版本号 DMG 和 SHA-256 文件：

scripts/build-release.sh

产物位于 dist/。如需 Developer ID 签名和 Apple 公证，请参阅发布检查表。

技术实现

• Swift 6、SwiftUI、AppKit
• Swift Package Manager + Xcode 工程
• SQLite（WAL 模式）保存任务、调度状态、运行轮次和尝试
• 单个用户级 LaunchAgent 常驻托管内嵌 Scheduler Helper
• Scheduler Helper 为每次运行启动独立任务进程组，并分别记录 stdout、stderr 和结构化结果
• 后台文件权限失败分类与任务级暂停/恢复；历史运行结果保持不可变
• XCTest 覆盖调度、重试、存储、Runner、后台控制器和 ViewModel

SwiftUI App ── SQLite ── Scheduler Helper ── task process group
     │                         │                    │
     └──── task editing        └──── launchd       └──── stdout/stderr

本地数据

TaskMate 默认将数据放在：

~/Library/Application Support/TaskMate/
├── taskmate.sqlite
├── Runs/
├── TestRuns/
└── Logs/

后台调度配置位于：

~/Library/LaunchAgents/com.taskmate.scheduler.plist

项目结构

App/                         SwiftUI macOS App
Sources/TaskMateCore/        调度、执行、SQLite 与后台控制
Sources/TaskMatePresentation/界面状态与 ViewModel
Sources/TaskMateScheduler/   后台 Scheduler 命令入口
Tests/                       单元与集成测试
docs/                        产品、开发、决策、研究与发布文档
scripts/                     构建和发布脚本

完整文档导航见 docs/README.md。项目当前状态和已知限制见开发状态。

参与开发

提交改动前请至少运行 swift test。涉及 macOS App、后台 Helper、文件权限或 LaunchAgent 的变更，还应执行 Debug App 构建和对应的可靠性实机验收。

欢迎通过 Issue 描述使用场景、复现步骤和期望行为。当前仓库尚未声明开源许可证；在许可证确定前，请不要假定代码可用于再分发或商业项目。