obsidian-plugin/wudanyang27_ticktick-today
1
0
Fork 0
mirror of https://github.com/wudanyang27/ticktick-today.git synced 2026-07-22 06:45:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
wudanyang27_ticktick-today/README-zh.md
wudanyang d5e9c1acc3 update
2025-07-24 13:13:48 +08:00

11 KiB
Raw Permalink Blame History

TickTick Today - Obsidian Plugin

⚠️ 重要提示: 此插件仅支持 macOS 系统，需要 TickTick 应用配合使用。

🎯 一个专为GTD (Getting Things Done) 方法论设计的Obsidian插件，直接从TickTick应用获取今日任务并在侧边栏显示，让你在写作和思考时能够快速查看和完成今日任务。

设计理念: 本插件并非为了替代TickTick，而是作为GTD实践的辅助工具。任务的创建、编辑、项目管理等主要操作仍应在TickTick中进行，插件的作用是在你专注于Obsidian工作时，提供便捷的今日任务概览和快速完成功能。

Plugin Screenshot Version macOS Only

📖 语言: 中文文档 | English

✨ 核心功能

  • 🔗 TickTick直接集成: 通过macOS JXA API直接获取TickTick今日任务
  • 📱 侧边栏面板: 专用的今日任务概览界面，无需切换应用
  • ⚡ 快速任务完成: 在Obsidian中直接标记任务完成，状态实时同步到TickTick
  • 🔄 智能自动刷新: 可配置的定时更新，保持任务状态同步
  • 🏷️ 项目信息显示: 显示任务所属项目名称，支持中文项目名
  • 📅 智能时间显示: 人性化的时间显示（今天、明天、X天前/后）
  • 🔗 快速跳转: 点击任务标题直接跳转到TickTick应用进行详细操作
  • 📌 置顶任务优先: 置顶任务自动排在最前面

🎯 使用场景与定位

GTD 工作流辅助

本插件是为了让GTD实践者在使用Obsidian进行知识管理、写作或思考时，能够：

  • 快速浏览今日待办事项
  • 不离开Obsidian就能完成简单任务
  • 保持对重要任务的视觉提醒
  • 无缝衔接思考工作与任务执行

不是TickTick的替代品

请注意，本插件不是为了替代TickTick，而是作为补充工具：

  • ✅ 适合: 快速查看今日任务、标记完成状态、获取任务提醒
  • ❌ 不适合: 创建新任务、编辑任务详情、管理项目、设置提醒
  • 💡 建议: 任务的创建、编辑、项目管理等核心操作仍应在TickTick中进行

🖥️ 系统要求

  • 操作系统: macOS（必须，使用JXA技术）
  • TickTick应用: 已安装并登录
  • Obsidian版本: 0.15.0+
  • 系统权限: Obsidian需要辅助功能权限来访问TickTick

🚀 安装和设置

1. 手动安装

# 下载插件文件到Obsidian插件目录
mkdir -p ~/.obsidian/plugins/ticktick-today/
# 复制 main.js, manifest.json, styles.css 到上述目录

2. 配置系统权限

  1. 打开系统偏好设置 → 安全性与隐私 → 隐私 → 辅助功能
  2. 点击锁图标解锁设置
  3. 添加Obsidian应用并勾选启用

3. 启用插件

  1. 重启Obsidian
  2. 打开设置 → 第三方插件
  3. 启用"TickTick Today"
  4. 插件会自动在右侧边栏显示今日任务面板

重要提示: 插件首次启动时会在插件目录自动创建两个JXA脚本文件：

  • ticktick-fetch.js - 用于获取今日任务
  • ticktick-toggle.js - 用于切换任务状态

这些文件会在插件卸载时自动清理。

📱 使用方法

基本操作

  • 打开面板: 点击左侧工具栏的📅图标或使用命令面板
  • 刷新任务: 点击面板顶部的🔄刷新按钮获取最新状态
  • 完成任务: 点击任务左侧的复选框快速标记完成
  • 查看详情: 点击任务标题跳转到TickTick进行详细管理

推荐工作流程

  1. 在TickTick中规划: 创建任务、设置项目、安排时间
  2. 在Obsidian中执行: 查看今日任务列表，专注于写作和思考
  3. 快速标记完成: 完成任务后直接在插件中标记，无需切换应用
  4. 详细管理回归TickTick: 需要编辑任务或查看详情时，点击跳转到TickTick

任务显示规则

  • 排序优先级: 置顶任务 → 未完成任务 → 已完成任务
  • 时间排序: 在同一分组内按到期时间升序排列

任务信息显示

  • 任务标题: 可点击跳转到TickTick进行详细操作
  • 项目名称: 显示任务所属项目（支持"收集箱"中文显示）
  • 到期时间: 智能显示（今天、明天、X天前/后，包含具体时间）
  • 完成状态: 实时同步显示，与TickTick保持一致

⚙️ 插件设置

自动刷新设置

  • 启用自动刷新: 定时获取最新任务状态
  • 刷新间隔: 1-60分钟可选（默认5分钟）

显示设置

  • 显示已完成任务: 选择是否在面板中显示已完成的任务
  • TickTick应用名称: 支持自定义应用名称（如中文版等）

🔧 技术特性

JXA脚本管理

  • 高效执行: 插件启动时创建JXA脚本文件，避免重复创建开销
  • 动态更新: 设置更改时自动重新生成脚本文件
  • 自动清理: 插件卸载时自动删除生成的脚本文件
  • 错误处理: 完善的错误捕获和用户友好的提示

数据处理

  • 项目缓存: 智能缓存项目信息，提高响应速度
  • 任务解析: 完整解析TickTick任务数据结构
  • 状态同步: 双向同步任务完成状态
  • 类型安全: 完整的TypeScript类型定义

用户体验

  • 响应式设计: 适配不同宽度的侧边栏
  • 主题兼容: 自动适配Obsidian主题颜色
  • 平滑动画: 任务状态切换的视觉反馈
  • 智能链接: 自动生成TickTick深度链接

🛠️ 开发信息

项目结构

ticktick-today/
├── main.ts              # 主插件代码（TypeScript）
├── main.js              # 编译后的插件文件
├── styles.css           # 插件样式
├── manifest.json        # 插件清单
├── ticktick-fetch.js    # JXA任务获取脚本（运行时生成）
├── ticktick-toggle.js   # JXA任务切换脚本（运行时生成）
├── package.json         # 项目配置
├── tsconfig.json        # TypeScript配置
└── README.md           # 项目文档

开发环境

# 克隆仓库
git clone https://github.com/wudanyang27/ticktick-today.git

# 安装依赖
npm install

# 开发模式（自动编译和监视）
npm run dev

# 构建生产版本
npm run build

技术栈

  • TypeScript: 主要开发语言
  • Obsidian API: 插件开发框架
  • JXA (JavaScript for Automation): macOS自动化技术
  • CSS3: 界面样式
  • Node.js: 构建工具链

🔍 故障排除

常见问题

Q: 为什么不能在插件中创建新任务？ A: 这是设计选择，不是功能缺陷。本插件专注于任务概览和快速完成，任务创建和编辑应该在TickTick中进行，这样可以：

  • 保持任务管理的完整性和一致性
  • 避免功能重复和界面复杂化
  • 让用户专注于Obsidian的核心价值：知识管理

Q: TickTick任务没有显示怎么办？ A: 请检查：

  • TickTick应用是否已打开并登录
  • macOS是否给予Obsidian辅助功能权限
  • 插件是否在设置中正确启用
  • 检查控制台是否有错误信息

Q: 任务状态切换失败？ A: 可能原因：

  • TickTick应用没有网络连接
  • 任务ID获取失败
  • 系统权限被撤销
  • 建议重启TickTick应用后重试

Q: 插件加载失败？ A: 解决方法：

  • 确认是在macOS系统上运行（此插件不支持Windows/Linux）
  • 检查插件文件是否完整
  • 查看Obsidian控制台的错误信息
  • 尝试重新安装插件

Q: JXA脚本文件相关问题？ A:

  • 脚本文件会在插件启动时自动创建
  • 如果文件损坏，重启插件会重新生成
  • 手动删除脚本文件不会影响插件功能

调试技巧

  1. 打开Obsidian开发者控制台（Cmd+Option+I）
  2. 查看Console标签页的错误信息
  3. 检查插件目录中的JXA脚本文件是否存在
  4. 在终端中手动测试JXA脚本： 
    osascript -l JavaScript /path/to/ticktick-fetch.js

📋 使用示例

GTD实践中的典型场景

场景1: 知识工作者的一天

  1. 早晨规划: 在TickTick中回顾和调整今日任务
  2. 专注工作: 打开Obsidian开始写作，侧边栏显示今日任务概览
  3. 任务提醒: 在写作间隙快速浏览待办事项，保持对优先级的感知
  4. 快速完成: 完成简单任务时直接在插件中标记，无需打断思路
  5. 深度操作: 需要详细编辑任务时，点击跳转到TickTick

场景2: 研究工作流程

  1. 文献阅读: 在Obsidian中阅读和做笔记
  2. 任务关联: 看到今日有"整理研究笔记"任务
  3. 即时完成: 笔记整理完成后，直接在侧边栏标记任务完成
  4. 状态同步: 任务状态自动同步到TickTick，其他设备可见

最佳实践建议

  • 任务创建: 始终在TickTick中创建和管理任务
  • 快速查看: 利用插件获得今日任务的视觉提醒
  • 专注模式: 在深度工作时，通过插件保持对重要任务的感知
  • 无缝切换: 需要详细操作时，一键跳转到TickTick
  • 状态同步: 利用快速完成功能保持跨设备的任务状态一致性

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

报告问题

  • 使用GitHub Issues报告Bug
  • 详细描述问题复现步骤
  • 提供系统环境信息

功能建议

  • 在Issues中标记为"enhancement"
  • 详细描述期望的功能
  • 说明使用场景和需求

<EFBFBD> 隐私与数据处理

本插件优先考虑您的隐私和数据安全：

  • 无数据收集: 本插件不收集、存储或传输任何个人数据
  • 本地运行: 所有任务数据处理均在您的设备上本地进行
  • 无外部服务器: 除了TickTick（通过本地JXA）外，不与任何外部服务器通信
  • 无分析统计: 未实现任何使用跟踪或分析功能
  • 最小权限: 仅请求TickTick集成所需的必要系统权限

插件仅通过macOS内置的JXA（JavaScript for Automation）接口访问TickTick数据，这需要用户通过macOS辅助功能设置明确授权。

许可证

MIT License - 详见 LICENSE 文件

📞 联系方式

⚠️ 重要说明:

  • 此插件仅支持macOS系统，使用JXA (JavaScript for Automation) 技术与TickTick通信
  • 本插件是GTD工作流的辅助工具，不是TickTick的替代品
  • 任务的创建、编辑、项目管理等主要功能请在TickTick应用中完成
  • 插件主要用于快速查看今日任务和标记完成状态

🙏 感谢: 感谢Obsidian社区和TickTick提供的优秀平台，让GTD实践变得更加高效便捷。