Worklog Obsidian Plugin

Worklog 是一个本地化工时管理插件，用于在 Obsidian 中维护月度任务、每日工时、日历完成状态和年度统计看板。

当前能力

• 打开当月工时工作台，没有当月数据时自动创建
• 创建工时工作台时可手动输入年份、选择月份，并按对应年份目录创建数据
• 跳转到月份工时工作台时可手动输入年份、选择月份；已有数据直接打开，无数据时会询问是否创建
• 跳转到年度工时看板时可手动输入年份；已有数据直接打开，无数据时只提示暂无数据
• 年度工时看板默认打开当年，按“上方总数据统计、下方月度趋势 + 任务类型占比 + 近期月份卡片”展示年度统计
• 年度任务类型占比使用该任务类型的计划工时 / 全年总计划工时统计
• 年度工时看板包含项目统计，可查看全年项目汇总，也可筛选到某个月
• 使用本地 JSON 保存月度数据，并按年份目录归档
• 可在插件设置中开启终结报告自动创建，开启后会创建模板；每月 1 日读取上个月数据生成月度总结，每年 1 月 1 日读取上一年度数据生成年度总结
• 可在插件设置中维护任务类型和默认任务模板
• 新月份按启用的默认任务模板自动创建任务；没有模板时不会自动生成任务
• 新增任务时可填写归属项目，内部任务标识自动生成且不在界面中展示
• 已登记过工时的任务不能删除，避免历史工时失去任务引用
• 新增工时，同一天同任务防重复
• 每日工时记录支持编辑和删除
• 月度数据看板，包含统计卡和计划/实际柱状图
• 日历按实际月份天数渲染
• 日历中的当日工时合计以悬浮层显示
• 手动勾选日期完成状态
• 任务状态下拉修改

启用方式

1. 确认插件目录位于：

.obsidian/plugins/worklog/

2. 重启 Obsidian 或在社区插件里刷新插件列表。
3. 启用 Worklog 插件。
4. 使用左侧日历按钮，或命令面板执行：

打开工时工作台
创建工时工作台
跳转到月份工时工作台
跳转到年度工时看板
打开年度工时看板

数据路径

插件配置路径：

.obsidian/plugins/worklog/config.json

默认数据路径：

<vault-config-dir>/plugins/worklog/data/YYYY/YYYY-MM.json

默认终结报告路径：

worklog/YYYY/YYYY-MM 月度终结报告.md
worklog/YYYY/YYYY 年度终结报告.md
worklog/月度终结报告模板.md
worklog/年度终结报告模板.md

数据目录在设置中留空时会自动使用当前插件安装目录下的 data/YYYY 文件夹；如果你的库配置目录不是 .obsidian，插件也会跟随 Obsidian 的实际配置目录保存数据。

在设置中修改“JSON 数据保存位置”或“终结报告目录”时，输入框内容不会立即生效；需要点击对应的“保存并迁移”按钮。保存后插件会把原目录中的文件复制到新目录：

• JSON 数据保存位置：复制原目录中的 .json 数据文件到新目录
• 终结报告目录：复制原目录中的 .md 报告和模板到新目录
• 迁移采用复制方式，原目录文件会保留
• 如果新目录已有同名文件，插件会跳过，不会覆盖
• 路径会自动规范化，例如去掉末尾斜杠和重复斜杠

首次启用时，任务类型和默认任务模板为空，需要先在 Worklog 设置中手动新增。设置面板中可以维护：

• 任务类型、颜色、启用状态、是否要求填写 issue
• 新月份默认任务模板、归属项目、计划工时
• 终结报告开关和报告目录
• JSON 数据保存位置

初始化

初始化插件数据时，只需要删除 config.json 和数据目录下的年份目录或月份 JSON。不要删除插件目录中的 main.js、styles.css、manifest.json 和 README.md。