type
status
date
slug
summary
tags
category
icon
password
语言
📋 目录
- 项目概述
- 项目结构
- 核心模块说明
- 运行环境
- 安装部署
- 功能详解
- API接口说明
- 配置说明
- 开发指南
- 常见问题
🎯 项目概述
这是一个为 Obsidian 开发的任务管理和番茄时钟插件，集成了 AI 智能任务拆分功能。插件提供了完整的任务生命周期管理，支持重复性任务和一次性任务，并配备了番茄工作法计时器来提高工作效率。
主要特性
- 📝 任务管理: 支持重复性任务（年/月/周/日周期）和一次性任务
- 🍅 番茄时钟: 集成番茄工作法，支持自定义工作和休息时间
- 🤖 AI 智能拆分: 集成 DeepSeek API，自动将复杂任务拆分为子任务
- 📊 进度跟踪: 实时跟踪任务进度和完成状态
- 🔔 智能提醒: 支持自定义提示音和到期提醒
- 📁 文件管理: 自动归档已完成任务到指定文件夹
📁 项目结构
文件说明
文件 | 大小 | 功能描述 |
main.js | 4007行 | 核心逻辑，包含所有类和功能实现 |
manifest.json | 10行 | Obsidian 插件元数据配置 |
package.json | 9行 | NPM 包配置信息 |
data.json | 16行 | 用户个性化设置数据 |
styles.css | 412行 | UI 样式定义 |
README.md | 64行 | 用户使用说明 |
🏗️ 核心模块说明
1. YuhanboTaskPlugin (主插件类)
位置:
main.js:47-385功能: 插件的入口点，负责初始化和协调各个模块核心方法:
onload(): 插件加载时的初始化逻辑
onunload(): 插件卸载时的清理逻辑
saveSettings(): 保存用户设置
resetTaskSystem(): 重置任务系统
startDailyCleanupTimer(): 启动每日清理定时器
performDailyCleanup(): 执行每日清理任务
2. TaskManager (任务管理器)
位置:
main.js:1180-2531功能: 核心任务管理逻辑，处理任务的增删改查核心方法:
createTask(taskData): 创建新任务
updateTask(taskId, updates): 更新任务状态
deleteTask(taskId): 删除任务
getAllActiveTasks(): 获取所有活跃任务
loadTasks(): 从文件加载任务
saveTasks(): 保存任务到文件
filterRepeatingTasks(): 过滤重复性任务显示
cleanupExpiredRepeatingTasks(): 清理过期重复性任务
3. PomodoroTimer (番茄时钟)
位置:
main.js:386-737功能: 番茄工作法计时器实现核心方法:
startWorkWithTaskSelection(): 开始工作并选择任务
startWork(task): 开始工作计时
startBreak(): 开始休息计时
pause(): 暂停计时器
resume(): 恢复计时器
stop(): 停止计时器
playSound(): 播放提示音
4. Modal 类族 (用户界面)
TaskSelectionModal (任务选择弹窗)
位置:
main.js:2532-2675功能: 番茄时钟开始前的任务选择界面TaskProgressModal (任务进度弹窗)
位置:
main.js:2676-2824功能: 任务进度更新界面TaskModal (任务创建/编辑弹窗)
位置:
main.js:2825-3584功能: 任务创建和编辑的主界面TaskListModal (任务列表弹窗)
位置:
main.js:3585-4007功能: 任务列表查看和管理界面5. YuhanboTaskSettingTab (设置页面)
位置:
main.js:738-1179功能: 插件设置界面设置项:
- API 配置 (DeepSeek API Key)
- 任务文件夹路径配置
- 番茄时钟时间配置
- 提示音设置
- AI 功能开关
🔧 运行环境
基础要求
- Obsidian: 版本 0.15.0 或更高
- 操作系统: Windows / macOS / Linux
- Node.js: 不需要（插件运行在 Obsidian 环境中）
依赖项
插件使用 Obsidian 内置的依赖项：
Plugin: Obsidian 插件基类
Notice: 通知组件
PluginSettingTab: 设置页面基类
Setting: 设置项组件
Modal: 弹窗基类
moment: 日期处理库
normalizePath: 路径标准化工具
📦 安装部署
方法一：手动安装
- 下载插件文件
- 启用插件
- 打开 Obsidian 设置
- 进入"第三方插件"页面
- 找到"yuhanbo-task"插件并启用
方法二：开发模式安装
- 克隆代码
- 重启 Obsidian
- 重启 Obsidian 应用
- 在设置中启用插件
初始化配置
插件首次启动时会自动：
- 创建任务文件夹结构
- 初始化默认设置
- 工作时间：25分钟
- 短休息：5分钟
- 长休息：15分钟
- 长休息间隔：4个工作周期
⚙️ 功能详解
1. 任务管理功能
任务类型
一次性任务
- 只需要完成一次的任务
- 完成后自动归档到"已完成任务"文件夹
- 支持进度跟踪（0-100%）
重复性任务
- 支持四种周期：年、月、周、日
- 每个周期只显示当前应该执行的任务
- 完成当期任务后，下个周期自动重新显示
任务属性
智能过滤逻辑
重复性任务过滤规则:
- 过期任务: 超过截止日期的任务不显示
- 周期判断: 只显示当前周期应该执行的任务
- 完成状态: 已完成当期的任务隐藏，直到下个周期
2. 番茄时钟功能
工作流程
- 任务选择: 从活跃任务中选择要执行的任务
- 工作计时: 开始工作倒计时（默认25分钟）
- 休息提醒: 工作结束后提示休息
- 进度更新: 可选择更新任务进度
状态管理
计时器逻辑
3. AI 智能拆分功能
DeepSeek API 集成
插件集成了 DeepSeek API 来实现任务的智能拆分：
4. 数据持久化
文件存储格式
任务数据以 Markdown 格式存储在用户的笔记库中：
自动备份机制
- 实时保存: 任务状态变更时自动保存
- 文件同步: 利用 Obsidian 的文件同步功能
- 版本控制: 支持 Git 等版本控制系统
🔌 API接口说明
TaskManager API
创建任务
更新任务
查询任务
PomodoroTimer API
开始番茄时钟
控制计时器
⚙️ 配置说明
data.json 配置文件
环境变量配置
如果需要在开发环境中使用，可以设置以下环境变量：
🛠️ 开发指南
代码结构说明
1. 常量定义
2. 类继承关系
3. 事件处理机制
扩展开发
添加新的任务类型
- 扩展 TaskType 枚举
- 修改任务创建逻辑
- 实现特定逻辑
添加新的 AI 模型支持
- 扩展模型配置
- 实现模型适配器
调试技巧
1. 启用调试日志
2. 使用 Obsidian 开发者工具
- 按
Ctrl+Shift+I(Windows) 或Cmd+Option+I(Mac) 打开开发者工具
- 在 Console 面板查看日志输出
- 使用 Sources 面板设置断点调试
3. 任务数据检查
❓ 常见问题
1. 安装和配置问题
Q: 插件无法加载怎么办？
A: 检查以下几点：
- 确认 Obsidian 版本 ≥ 0.15.0
- 检查插件文件是否完整
- 查看控制台是否有错误信息
- 尝试重启 Obsidian
Q: 任务文件夹创建失败？
A: 可能的原因：
- 文件夹路径包含特殊字符
- 磁盘空间不足
- 权限不足
解决方案：
2. 功能使用问题
Q: 重复性任务不显示？
A: 检查以下设置：
- 任务是否设置了正确的执行日期
- 任务是否已过截止日期
- 当前日期是否在任务的执行周期内
Q: AI 拆分功能不工作？
A: 确认以下配置：
- DeepSeek API Key 是否正确
- 网络连接是否正常
- API 配额是否充足
3. 性能问题
Q: 插件运行缓慢？
A: 优化建议：
- 定期清理已完成的任务
- 减少同时显示的任务数量
- 检查是否有大量子任务
Q: 内存占用过高？
A: 可能原因：
- 任务数据过多
- 定时器未正确清理
- 事件监听器泄漏
解决方案：
4. 数据安全问题
Q: 如何备份任务数据？
A: 任务数据存储在以下位置：
- 重复性任务：
Tasks/Repeating/文件夹
- 一次性任务：
Tasks/OneTime/文件夹
- 已完成任务：
Tasks/Completed/文件夹
建议使用 Obsidian 的同步功能或 Git 进行版本控制。
Q: 数据丢失如何恢复？
A: 恢复步骤：
- 检查 Obsidian 的备份文件
- 从同步服务恢复
- 使用版本控制系统回滚
- 重新导入任务数据
5. 开发相关问题
Q: 如何修改插件代码？
A: 开发流程：
- 修改
main.js文件
- 重启 Obsidian 或重新加载插件
- 测试功能是否正常
- 提交代码更改
Q: 如何添加新功能？
A: 参考开发指南部分，按照现有的代码结构进行扩展。
📞 技术支持
如果您在使用过程中遇到问题，可以：
- 查看日志: 打开开发者工具查看控制台输出
- 重置系统: 使用"重置任务系统"命令
- 联系开发者: 通过 GitHub Issues 反馈问题
- 社区支持: 在 Obsidian 社区寻求帮助
