README file from
GithubOvertime Visualizer
1.5.0 解压日历与月份筛选
- 概览常驻「解压日历」,打开时默认选中今天。有解压记录的日期以绿点标记,可跨月查看。
- 选中任意日期即可补录、修改或删除当天的解压事项,考勤尚未同步时也可以记录。宽栏并排显示月历与明细,窄栏上下排列。
- 「每日记录」在日期旁显示星期,并提供中文月份选择器,支持跨年浏览和一键回到本月。空月份也能完整打开选择器。
- 「压力构成」在各下班时段旁显示单日压力分,并保留对应天数。
1.4.0 月周平均压力指数
- 新增月平均压力指数、周平均压力指数面板,沿用平均下班时间图表样式。
- 默认展示原始加班压力;分别勾选后可叠加解压抵扣后的最终压力曲线。
- 按已结算考勤日计算平均值,包含周末出勤及零压力日,排除当天和缺失下班时间的记录。
- 解压仅抵扣当日压力;缺失周期保留断点并以虚线连接,切换曲线保留滚动位置。
1.3.0 平均下班趋势与日期选择优化
- 概览新增独立的月平均、周平均下班时间图表,覆盖全部可用考勤数据,不受概览日期筛选影响。
- 复用主卡片的周一至周四有效出勤口径;自然周按周一至周日划分,跨夜保留次日偏移。
- 趋势使用平滑实线,缺失周期用同色虚线连接真实数据点,不补造平均值,首尾缺失不延伸。
- 日期筛选改为统一风格日历,支持月份切换、今天快捷选择及 Esc 关闭。
1.2.0 本地考勤自动同步
- 可选择从笔记库中的脱敏考勤文件自动导入,启动时及运行期间每 4 小时检查;支持随时手动同步。
- 沿用考勤去重、人工修正保护和跨夜关联规则,校验完整快照后再写入。
- 顺序处理后台导入和手动修改,避免并发写入覆盖数据;优化设置面板在新版 Obsidian 中的布局。
- 考勤数据需要由独立的外部任务生成,插件不会连接考勤网站。
1.1.1 社区检查修复
- 修复测试目录与桌面模块加载的检查问题,保留桌面下载目录导出和移动端笔记库备份。
- 支持新版设置搜索,并保持事项独立保存与即时启用行为。
- 更新安全依赖,调整样式兼容性并补充剪贴板与文件访问说明。
- 发布附件新增来源证明工作流,构建一致后由 GitHub Actions 生成。
1.1.0 出勤趋势与合并备份
- 压力趋势和每日列表、详情只展示有打卡的日期,保留单次打卡与休息日出勤。
- 压力曲线平滑连接实际出勤日,保持原始分值。
- 顶部新增合并及单独导出入口,桌面端默认保存到下载文件夹。
- 支持考勤、解压明细和配置的一次导出与预览导入,重复导入按日期及记录 ID 合并。
- 修复桌面插件导出模块加载兼容性,失败提示展示真实原因。
1.0.0 年度总结与图片分享
- 提供概览、每日记录与年度回顾,以及可独立保存的解压事项配置。
- 年度分享卡增加工作日总数、七档下班时间分布及跨夜工作日统计。
- 在“年度回顾 → 分享年度总结”中点击“复制图片”,生成完整高清 PNG 并复制到剪贴板。
- 保留预览中的字体、字重、渐变和山形背景;修复记录及撤销今日解压后滚动位置复位。
- 图片在本地生成,需运行环境支持图片剪贴板;不支持时可使用系统截图。
- 第三方图片生成依赖的许可见 Third-party notices。
数据导出
顶部「导入考勤」旁新增「导出全部」,一次导出考勤、解压明细和统计配置到一个 JSON 文件。点击「导入考勤」选择该合并文件,预览数量后确认即可一次恢复;考勤按日期、解压按 ID 合并,相同标识以备份为准,其余记录保留,重复导入不会增加重复记录。合并备份同时恢复统计规则及解压事项配置。
仍提供「导出考勤」和「导出解压」,导出全部已保存的数据,不受页面筛选影响。桌面端默认保存到当前用户的 Downloads(下载)文件夹,成功后提示完整路径;命令面板备份及完整明细页也使用同一路径。移动端保留笔记库内「加班时长备份」目录。文件仍为可重新导入的 JSON。
本地考勤自动同步
插件设置中的「考勤自动同步」默认关闭。开启后,插件启动时及运行期间每 4 小时检查一次笔记库内指定 JSON 文件;也可使用「立即同步」或命令面板中的「从本地文件同步考勤」。默认位置为 加班时长备份/自动同步/attendance.json,可在设置中修改为笔记库内相对路径。插件不访问考勤网站,外部抓取任务需要独立运行并生成文件;Obsidian 未运行时不会导入。
交换文件使用 schemaVersion: 1、complete: true、capturedAt(ISO 时间)、startDate、endDate、total 和 list 字段。total 必须与完整列表长度相同,日期格式为 YYYY-MM-DD。抓取端应核验接口成功及所有分页,只保留日期、上下班时间、星期、日类型、考勤状态和申请原因,并通过临时文件原子替换。导入保留人工修改,发现无效记录时整批不写入,并跳过已处理或更早的快照。
交换文件位于笔记库中,可能被用户配置的笔记库同步服务复制到其他设备或云端;不应包含姓名、工号、打卡位置、登录凭证或考勤备注。
考勤日期展示
- 概览压力趋势与每日记录只展示至少有一次上班或下班打卡的日期,不按工作日、休息日区分。
- 无打卡日期及仅有解压记录的日期可以在「概览 → 解压日历」中查看和补录解压。
- 每日详情与列表使用同一筛选结果,前后切换会跳过无考勤日期;压力曲线平滑连接实际出勤日期,数值不变。
English
Overtime Visualizer is an offline-first Obsidian dashboard for reviewing late departures, overnight work, weekend attendance, and recent workload pressure from local attendance records.
Features
- Calculates a standardized workload pressure score for the latest 30 days.
- Groups late departures into six mutually exclusive time ranges, including overnight work.
- Shows the daily pressure score and attendance count for each late-departure range.
- Lets you add, edit, or delete relief records by date from the overview calendar, even before attendance data has synced.
- Shows weekdays in daily records and provides a month picker with year navigation and a shortcut to the current month.
- Displays daily departure trends, reference lines, weekend markers, and a 30-day heatmap.
- Provides a dedicated attendance data management view.
- Imports attendance records from JSON files, JSON code blocks in Markdown, or pasted text.
- Previews added, updated, skipped, and invalid records before saving.
- Recognizes leave, missing punches, and overnight attendance records.
- Stores versioned data locally in the current vault and supports rolling back import batches.
- Exports a sanitized JSON backup that can be imported again.
- Supports both light and dark Obsidian themes.
Installation
After the plugin is available in the Community Plugins directory, search for Overtime Visualizer under Settings → Community plugins → Browse and install it.
For manual installation, copy the following files into <vault>/.obsidian/plugins/overtime-visualizer/:
main.js
manifest.json
styles.css
Reload Obsidian, then enable Overtime Visualizer in the Community plugins settings. Open the dashboard from the clock icon in the ribbon or run Open overtime dashboard from the command palette.
Import format limitation
The current version only supports the internal JD attendance data format. Attendance exports from other companies, platforms, or custom systems are not supported by default. To import another format, you must develop your own parser and conversion adapter.
Privacy
- Attendance records, relief records, and plugin settings remain in the current Obsidian vault.
- The plugin contains no telemetry, analytics, or advertising and does not upload attendance data to network services.
- The system clipboard is written only when you click “Copy image” in the annual summary; clipboard contents are never read.
- Desktop exports may write JSON backups to your Downloads folder when explicitly requested. Optional attendance synchronization periodically reads only the configured JSON path within the vault.
- Exported backups contain only allowlisted fields. Desktop exports are written to the current user’s Downloads folder; mobile exports remain in the vault’s 加班时长备份 folder.
中文
一个离线优先的 Obsidian 下班压力看板,用于分析晚下班、跨夜工作和周末加班。
安装
发布到社区插件市场后,可在 Obsidian 的 设置 → 第三方插件 → 浏览 中搜索 Overtime Visualizer 并安装。
手动安装时,将以下文件放入仓库的 .obsidian/plugins/overtime-visualizer/ 目录:
main.js
manifest.json
styles.css
重新加载 Obsidian 后,在第三方插件设置中启用 Overtime Visualizer。
独立应用与共享代码
桌面版已迁出插件目录,独立项目位于本机 /Users/dingxinyi.2/Documents/practice/overtime-visualizer/。Electron 构建与安装包在独立项目维护,插件不再依赖桌面开发工具。
统计、导入与数据迁移由 @overtime-visualizer/[email protected] 提供,通用图表和组件由 @overtime-visualizer/[email protected] 提供。两份固定版本 tarball 随仓库保存在 vendor/,因此克隆本插件仓库后可独立执行 npm ci、测试和构建,无需旁边存在独立应用仓库。src 中相应目录仅保留包导出适配层;插件构建时会复制共享样式到 styles.css。
更新流程见 共享包说明。
数据导入限制
当前版本仅支持导入京东内部的考勤数据格式,不保证兼容其他公司、平台或自定义格式的考勤数据。如需导入其他格式,请自行开发相应的数据解析与转换适配。
当前进度
当前版本已经打通本地真实数据链路:
- 固定近 30 天的标准化压力分、强制升级红线和轻松、适中、疲惫、痛苦评价
- 21:00–21:29、21:30–21:59、22:00–22:59、23:00–23:29、23:30–23:59 和跨夜六档互斥指标
- 22:00 后下班的上线日归因与前 30 天压力变化
- 默认展示含今天在内近 30 天、并可自定义日期区间的每日下班时间折线图
- 带 21:00、21:30、22:00、23:00、23:30 和跨夜参考线及周末标记
- 固定近 30 天下班时间热力图
- 独立的考勤数据管理
ItemView - JSON 文件、Markdown 多 JSON 代码块和粘贴文本导入
- 新增、更新、跳过、错误的写入前预览
- 隐私字段白名单清洗、请假/缺卡/跨夜识别
- Obsidian
data.json版本化本地存储和导入批次回滚能力 - 可通过命令面板导出可重新导入的脱敏 JSON 备份
- Obsidian 深色与浅色主题适配
本地开发
npm install
npm run dev
插件 ID 为 overtime-visualizer。用于本地测试的插件目录或软链接名称应与该 ID 保持一致。若源码目录不在测试笔记库中,可在笔记库的 .obsidian/plugins/ 目录创建名为 overtime-visualizer 的软链接。
生产校验:
npm run test:run
npm run build
npm run lint
在 Obsidian 命令面板执行 打开加班时长仪表盘,或点击左侧栏的时钟图标。
隐私
- 所有考勤记录、舒缓记录和插件设置仅保存在当前 Obsidian 仓库的插件数据中。
- 插件不包含遥测、分析或广告,不会把考勤数据上传到网络服务。
- 仅点击年度总结的「复制图片」时写入系统剪贴板,不读取剪贴板内容。
- 用户主动导出时,桌面端在下载目录创建 JSON 备份;可选的自动同步会定时读取笔记库内用户配置的单个 JSON 文件,不扫描其他文件。
- 导出的备份仅包含白名单字段;桌面端写入当前用户的 Downloads(下载)文件夹,移动端继续写入笔记库的「加班时长备份」目录。
发布文件
GitHub Release 的标签必须与 manifest.json 中的版本完全一致。每个 Release 应分别上传:
main.jsmanifest.jsonstyles.css
License
发布产物证明
.github/workflows/attest-release.yml 在 GitHub Release 发布后,对同一 Tag 运行测试、检查和构建;核对发布附件与重新构建的 main.js、manifest.json、styles.css 完全一致后,为附件生成 GitHub artifact attestations。若发布附件尚未上传,任务会失败;附件补齐后可在 Actions 中手动选择该 Tag 重跑。
本地构建不会生成 GitHub 签名证明,新增工作流也不会回写旧版本检查结果;需要提交修复并发布新版本,再等待社区自动复检。