TaskBridge

中文 | English

TaskBridge 是一个 macOS 菜单栏应用，用来在飞书任务和 Apple 提醒事项之间进行双向同步。

如果你平时在团队里使用飞书任务做协作，但个人工作流更依赖 macOS、iPhone、Apple Watch 上的「提醒事项」，TaskBridge 可以把这两套系统连接起来：

• 把飞书任务同步到本地提醒事项
• 把本地提醒事项中的变更回写到飞书任务
• 在尽量不打断你现有习惯的前提下，保留飞书侧的协作入口

项目仍处于早期开发阶段。建议先使用测试飞书应用、测试账号或少量任务验证同步效果，再接入正式工作数据。

这个项目适合谁

TaskBridge 适合这几类使用场景：

• 团队里必须使用飞书任务，但你个人习惯用 Apple Reminders 管理日常待办
• 希望在 iPhone / Apple Watch 上直接看到和勾选飞书任务
• 希望通过系统级提醒事项能力，把飞书任务纳入自己的 Apple 生态工作流
• 希望保留飞书中的任务清单结构，同时在本地拥有更顺手的查看和编辑体验

功能特性

当前版本已经支持：

• 飞书 OAuth 登录授权
• 飞书任务同步到 Apple 提醒事项
• Apple 提醒事项变更同步回飞书任务
• 支持同步任务标题、完成状态、截止时间
• 支持把飞书清单 / 分组映射为 Apple 提醒事项列表
• 应用启动后自动同步
• 应用唤醒后自动重试同步
• 后台每 120 秒自动同步一次
• 本地提醒事项发生变化后自动触发回写同步
• 飞书 Token 过期后自动刷新
• 使用本地 SQLite 保存映射关系，避免重复创建任务
• 菜单栏运行，不占用 Dock

工作方式概览

TaskBridge 的整体工作流是这样的：

1. 你在应用里填写飞书应用的 App ID 和 App Secret
2. 应用通过浏览器完成飞书 OAuth 授权
3. 应用请求 Apple Reminders 权限
4. TaskBridge 从飞书读取任务、清单、分组
5. TaskBridge 在本地创建或更新对应的提醒事项列表与任务
6. 你在飞书或提醒事项任一侧的后续变更，都会尽量同步到另一侧

自动同步触发时机

TaskBridge 会在以下时机尝试同步：

• 应用启动后，如果授权已经齐全，会立即同步一次
• Mac 从睡眠中唤醒后，会再次检查并尝试同步
• 正常运行期间，每 120 秒自动同步一次
• 当 Apple 提醒事项发生本地改动时，会在短暂防抖后自动回写飞书

同步范围与规则

理解同步规则很重要，这能帮你避免误操作和预期偏差。

飞书 → Apple 提醒事项

TaskBridge 会读取飞书任务、清单和分组，并在 Apple 提醒事项中创建对应列表。

默认命名规则如下：

• 飞书清单：飞书 - 清单名
• 飞书清单分组：飞书 - 清单名 - 分组名
• 未归属任何清单的任务：飞书 - 我负责的

飞书侧会同步到本地的字段包括：

• 任务标题
• 完成状态
• 截止时间
• 所属清单 / 分组
• 飞书侧删除状态（若飞书任务被删除，本地对应提醒事项也会被删除）

Apple 提醒事项 → 飞书

只有 TaskBridge 管理的提醒事项列表中的内容，才会尝试回写飞书。也就是说，通常是这些由应用创建或映射的列表：

• 飞书 - 清单名
• 飞书 - 清单名 - 分组名
• 飞书 - 我负责的

在这些列表中，你可以直接在 Apple 提醒事项里进行以下操作：

• 新建提醒事项
• 修改标题
• 修改完成状态
• 修改截止时间
• 删除提醒事项

这些操作会尽量同步回飞书任务。

冲突处理

TaskBridge 不是强一致的实时协作系统，而是一个偏实用主义的双向同步桥接工具。

当前实现依赖本地同步快照和映射关系来判断哪一侧发生了变化，因此：

• 更适合个人使用场景下的同步
• 不适合高频、多端、多人同时编辑同一任务的强一致需求
• 如果飞书和 Apple 两侧在很短时间内同时修改同一字段，结果可能受最后一次检测到的变更影响

去重与映射

为了避免重复创建任务，TaskBridge 会在本地 SQLite 数据库中记录：

• 飞书任务 ID 与 Apple 提醒事项 ID 的映射
• 飞书清单 / 分组 与 Apple 列表的映射
• 上次同步时的标题、完成状态、截止时间等快照

这也是双向同步能够成立的关键基础。

系统要求

• macOS 13.0 或更高版本
• Xcode 或 Swift 工具链（用于源码运行或构建）
• 一个可用的飞书开放平台自建应用
• Apple 提醒事项访问权限

快速开始

1. 克隆项目

git clone <your-repo-url>
cd TaskBridge

2. 安装依赖并编译

项目使用 Swift Package Manager 管理依赖。

开发模式运行：

swift run TaskBridge

仅构建：

swift build

3. 打包为 .app

./build_app.sh
open TaskBridge.app

如果脚本没有执行权限，可以先运行：

chmod +x build_app.sh

build_app.sh 会：

• 执行 swift build -c release
• 生成标准 macOS .app 包结构
• 复制可执行文件与 Info.plist
• 对 App Bundle 执行本地签名，提升系统权限识别稳定性

飞书应用配置

TaskBridge 不依赖公共 SaaS 服务，而是要求你使用自己的飞书开放平台应用完成 OAuth 授权。

1. 创建飞书企业自建应用

请在飞书开放平台创建一个企业自建应用，并记录以下信息：

• App ID
• App Secret

其中 App ID 通常以 cli_ 开头。

2. 配置重定向 URL 白名单

在飞书应用后台的 OAuth / 安全设置中，将以下地址加入重定向 URL 白名单：

http://127.0.0.1:21016/callback

TaskBridge 会在本机临时启动一个 HTTP 回调服务，用于接收飞书 OAuth 授权结果。

3. 开通相关权限

请根据飞书后台实际展示，为应用开通任务相关读写权限，以及获取当前用户信息所需权限。

当前代码会使用到的能力包括：

• 读取任务
• 读取任务清单
• 读取清单分组
• 创建任务
• 更新任务
• 删除任务
• 获取当前授权用户信息

不同版本的飞书后台，权限名称可能略有差异。如果授权完成后接口仍提示无权限，请根据报错补充对应权限，并确认应用已经发布或启用到正确范围。

首次使用流程

首次运行建议按下面顺序完成：

1. 启动 TaskBridge
2. 点击菜单栏中的 TaskBridge 图标
3. 打开“设置”窗口
4. 填写飞书 App ID 和 App Secret
5. 在系统弹窗中授予 Apple 提醒事项权限
6. 点击“飞书授权登录”，在浏览器完成授权
7. 返回 TaskBridge，点击“立即同步”进行第一次同步

当提醒事项权限和飞书登录都准备好后，应用会进入自动同步状态。

界面说明

TaskBridge 当前是一个纯菜单栏应用。

菜单栏窗口里主要包含：

• 提醒事项授权状态
• 飞书登录状态
• “授权提醒事项访问”按钮
• “飞书授权登录” / “退出飞书登录”按钮
• “立即同步”按钮
• “设置”入口
• “退出”入口

应用不会出现在 Dock 中，适合作为长期驻留的小工具运行。

本地数据保存位置

TaskBridge 会在本机保存同步所需的本地数据：

• 同步数据库：~/Library/Application Support/com.namrood.TaskBridge/taskbridge.sqlite
• 飞书用户授权 Token：UserDefaults
• 飞书 App ID / App Secret：UserDefaults

这些数据默认只保存在本机，不会上传到除飞书 API 之外的第三方服务。

兼容旧数据迁移

如果你之前使用过旧版本项目 LarkFlow，当前代码会尝试把旧的本地数据库迁移到 TaskBridge 的数据目录中，以保留原有映射关系。

隐私与安全说明

使用前请注意以下几点：

• TaskBridge 需要 Apple 提醒事项完全访问权限，用于创建、修改和删除提醒事项
• TaskBridge 需要你的飞书 OAuth 授权，以访问任务相关数据
• 当前版本将 App ID、App Secret、Access Token、Refresh Token 保存在本机配置中，而不是 Keychain
• 因此更建议你自行从源码构建，而不是使用来源不明的二进制文件
• 如果你不再使用 TaskBridge，建议同时撤销飞书授权并清理本地数据

排错指南

1. 点击飞书登录后没有成功回调

优先检查：

• 飞书后台是否正确配置了 http://127.0.0.1:21016/callback
• 本机 21016 端口是否被其他程序占用
• 浏览器授权完成后，是否成功跳回本地回调页面

如果 21016 端口被占用，当前版本的授权会失败，因为回调端口是固定的。

2. 授权了提醒事项，但仍然无法同步

请确认：

• 系统设置里 TaskBridge 已获得提醒事项权限
• 菜单栏状态中“提醒事项”显示为已授权
• 飞书账号已经登录成功

TaskBridge 只有在“提醒事项权限”和“飞书登录”同时满足时，才会启动自动同步。

3. 飞书任务没有出现在提醒事项里

请检查：

• 飞书应用权限是否齐全
• 当前授权账号是否真的拥有对应任务数据
• 是否点击过“立即同步”触发首轮同步
• 菜单栏中是否出现同步失败提示

4. 提醒事项改了，但没有回写到飞书

请确认你修改的是 TaskBridge 管理的列表，而不是普通私人列表。

通常只有这些列表中的提醒事项才会回写：

• 飞书 - 清单名
• 飞书 - 清单名 - 分组名
• 飞书 - 我负责的

此外，本地变更会经过一个短暂防抖过程，不一定会在修改后瞬间上传。

5. 出现重复任务或想重新开始同步

你可以先备份本地数据，再清理：

• 删除 ~/Library/Application Support/com.namrood.TaskBridge/taskbridge.sqlite
• 删除由 TaskBridge 创建的提醒事项列表
• 重新授权并同步

仓库里也提供了一个辅助脚本，可用于清理所有以 飞书 - 开头的提醒事项列表：

swift clear_reminders.swift

使用前请务必确认这些列表中没有你想保留的手工数据。

当前限制

目前版本有这些已知限制：

• 主要同步的是标题、完成状态、截止时间、所属清单 / 分组
• 暂不支持同步任务描述、评论、附件、子任务等高级字段
• OAuth 回调端口固定为本机 21016
• 当前没有正式的应用签名、公证和安装分发流程
• 当前没有专门的冲突可视化界面
• 由于依赖本地状态快照，不建议把它当作强一致协作系统使用

开发说明

依赖

主要依赖包括：

• SwiftUI：菜单栏界面
• AppKit：应用生命周期与窗口管理
• EventKit：访问 Apple 提醒事项
• Network：本地 OAuth 回调服务
• GRDB：本地 SQLite 数据库封装

项目结构

Sources/TaskBridge/
├── TaskBridge.swift              # 应用入口与启动逻辑
├── MenuBarContentView.swift      # 菜单栏 UI 与用户操作入口
├── SettingsView.swift            # 偏好设置界面
├── SettingsWindowController.swift# 设置窗口控制器
├── FeishuOAuthManager.swift      # 飞书 OAuth 登录与 Token 刷新
├── FeishuAPIClient.swift         # 飞书任务 API 客户端
├── EventKitManager.swift         # Apple 提醒事项访问封装
├── SyncEngine.swift              # 飞书 -> Apple 同步逻辑
├── AppleToFeishuSync.swift       # Apple -> 飞书同步逻辑
├── DatabaseManager.swift         # SQLite 映射与快照存储
└── TaskViewModel.swift           # 任务数据整理

辅助脚本

仓库根目录下还有几个调试 / 维护脚本：

• print_calendars.swift：打印所有以“飞书”开头的提醒事项列表
• print_tasks.swift：打印指定列表中的提醒事项
• clear_reminders.swift：清理由 TaskBridge 创建的飞书相关提醒事项列表

运行方式示例：

swift print_calendars.swift
swift print_tasks.swift
swift clear_reminders.swift

建议的开发验证

在提交修改前，至少建议验证：

swift build

如果你改动了同步逻辑，建议额外手动验证：

• 飞书新建任务是否能出现在提醒事项中
• 本地新建提醒事项是否能回写飞书
• 标题、完成状态、截止时间是否双向同步
• 删除行为是否符合预期
• 清单 / 分组映射是否正确

贡献

欢迎提交 Issue 和 Pull Request。

如果你准备修改同步逻辑，建议在说明中写清楚：

• 变更影响的是哪个同步方向
• 涉及哪些飞书字段和 Apple 提醒事项字段
• 是否会影响现有映射关系或已有本地数据
• 是否需要用户重新授权或清理历史数据

License

本项目基于 MIT License 开源。