TaskForge Reminder Sync

一个完全在本机运行的 macOS 双向同步工具：把 TaskForge 日历视图中的今日任务写入 Apple 提醒事项，并把 Apple 端的完成状态安全回写为 TaskForge done。

非 TaskForge 或 Apple 官方项目。当前版本针对 TaskForge tasks.v6.bin 数据格式开发。

功能

• 今日任务正向同步：只为本地当天、状态不是 done / cancelled 的 TaskForge 任务创建提醒。
• 历史完成反向同步：扫描目标列表中所有已完成的关联提醒，不受提醒日期限制。
• 近实时响应：
  • Apple 提醒事项变化通知经过约 0.75 秒防抖后触发；
  • 每秒检查 TaskForge 任务库修改时间；
  • 每分钟主动核对，弥补系统通知漏失；
  • 每天 07:00、11:00、15:00 再做定时兜底。
• 时间保真：全天任务保持为日期提醒；有时间的任务保留小时和分钟。
• 稳定去重：使用 Vault 路径与 TaskForge 任务 ID 生成稳定标记，多次运行不会重复创建。
• 持久源映射：提醒中保存经过 Base64 编码的任务源引用。任务离开 TaskForge 当前缓存后，历史提醒仍能定位原笔记。
• 防止误重开：任意一端已经完成时，正向同步不会把 Apple 提醒重新打开。
• 先备份再回写：每次反向修改前保存源文件副本，并记录修改前后的 SHA-256。
• 保守拒绝：重复任务、非 keep 完成策略、Vault 外路径、陈旧或歧义源行都不会被自动修改。
• 不删除源任务：
  • Markdown 内联任务：- [ ] 改为 - [x]，并追加完成日期；
  • TaskNotes 文件：frontmatter 改为 status: done 并更新 completedDate；
  • 工具不会删除任务行或 TaskNotes 文件。

工作原理

TaskForge tasks.v6.bin
        │ 读取今日未完成任务
        ▼
Apple 提醒事项 / TaskForge 今日
        │ 完成状态 + 持久源引用
        ▼
Vault Markdown / TaskNotes
        │ TaskForge 重新索引
        ▼
TaskForge done

正向同步只新建今天的任务，避免把整个 Vault 导入提醒事项。反向同步则会检查所有已经建立关联的提醒，因此昨天或更早的任务在 Apple 端完成后仍可闭环。

详细设计见 架构说明，数据与权限边界见 隐私说明。

系统要求

• macOS 13 或更高版本；
• 已安装 TaskForge；
• TaskForge 使用 tasks.v6.bin 数据格式；
• Xcode Command Line Tools / Swift 5.9 或更高版本；
• Apple 提醒事项账户；
• 建议 TaskForge 保持运行，以便反向写入后及时重新索引。

安装

git clone https://github.com/ezbug/taskforge-reminder-sync.git
cd taskforge-reminder-sync
./scripts/build-app.sh

先做完全无写入的配置检查与今日任务预览：

./dist/TaskForgeReminderSync.app/Contents/MacOS/TaskForgeReminderSync --check-config
./dist/TaskForgeReminderSync.app/Contents/MacOS/TaskForgeReminderSync --dry-run

第一次真实同步：

./dist/TaskForgeReminderSync.app/Contents/MacOS/TaskForgeReminderSync --sync

macOS 会请求“提醒事项”访问权限。工具不需要“日历”权限。根据系统隐私设置，读取 TaskForge 容器或 Vault 时可能还需要为 App 授予“完全磁盘访问权限”。

确认一次性同步正常后，安装常驻 LaunchAgent：

./scripts/install-daily-sync.sh

安装位置：

• App：~/Applications/TaskForgeReminderSync.app
• LaunchAgent：~/Library/LaunchAgents/local.codex.taskforge-reminder-sync.plist
• 标准日志：~/Library/Logs/TaskForgeReminderSync.log
• 错误日志：~/Library/Logs/TaskForgeReminderSync.error.log
• 回写备份：~/Library/Application Support/TaskForgeReminderSync/Backups/

命令

命令	作用	是否写入
--check-config	检查 TaskForge、数据版本、Vault 和今日任务数量	否
--dry-run	列出今天将被同步的任务	否
--reverse-dry-run	预览 Apple → TaskForge 的源文件修改	否
--reverse-once	执行一次反向完成并等待 TaskForge 回读	是
--sync	先反向扫描，再执行一次今日任务正向同步	是
--watch	常驻近实时双向同步	是

常用参数：

--list-name NAME       目标提醒事项列表，默认“TaskForge 今日”
--task-store PATH      自定义 tasks.v6.bin 路径
--date YYYY-MM-DD      指定正向预览/同步日期
--task-id ID           只处理一个 TaskForge 任务
--backup-root PATH     自定义反向写入备份目录

定向预览或完成一个任务：

./dist/TaskForgeReminderSync.app/Contents/MacOS/TaskForgeReminderSync \
  --reverse-dry-run --task-id TASK_ID
./dist/TaskForgeReminderSync.app/Contents/MacOS/TaskForgeReminderSync \
  --reverse-once --task-id TASK_ID

同步与安全规则

1. 提醒必须带有本工具生成的稳定标记，才会参与反向同步。
2. 源文件必须位于当前 TaskForge Vault 内。
3. 任务必须是非重复任务，且 onCompletion=keep。
4. 源行必须与保存的引用一致，或能在文件中唯一找到。
5. 写入前创建带时间戳的完整文件备份。
6. 写入后逐字节校验文件，并等待 TaskForge 任务库刷新。
7. TaskForge 可能从缓存中移除已完成的内联任务；这不等于源任务被删除。
8. 早期版本创建、没有持久源引用且已经离开 TaskForge 缓存的提醒会被安全跳过，不会猜测写入。

日志与排障

tail -f ~/Library/Logs/TaskForgeReminderSync.log
tail -f ~/Library/Logs/TaskForgeReminderSync.error.log
launchctl print "gui/$(id -u)/local.codex.taskforge-reminder-sync"

常见问题和恢复方式见 排障指南。

卸载

./scripts/uninstall-daily-sync.sh

卸载会停止 LaunchAgent 并移除安装的 App，不会删除：

• Apple 提醒事项中已经创建的内容；
• Vault 中的任何笔记或任务；
• 反向写入备份。

开发与测试

swift run TaskForgeReminderCoreTests
swift build
./scripts/build-app.sh

测试覆盖 MessagePack v6 解码、今日任务筛选、稳定标记、日期语义比较、正反向完成策略、历史源引用、Markdown / TaskNotes 回写和安全拒绝条件。

限制

• TaskForge 改变内部缓存格式后，解码器可能需要更新。
• 当前不会反向处理重复任务或完成后会移动、归档、删除的任务。
• TaskForge 未运行时，源文件可能不会立即被重新索引；建议让 TaskForge 保持运行。
• 本项目不提供云服务、遥测或跨设备同步；Apple 提醒事项自身的 iCloud 同步由系统负责。

参与贡献

请先阅读 CONTRIBUTING.md。安全或隐私问题请按 SECURITY.md 私下报告。

License

MIT