8000 GitHub - colisys/mfish:  打工人时间统计工具……是吗? · GitHub
[go: up one dir, main page]

Skip to content
colisysPublic

About

 打工人时间统计工具……是吗?

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

MFish

面向 macOS 13+ 的菜单栏摸鱼日历,SwiftPM / Swift 5.8 构建,无第三方依赖。无聊但好玩。

功能

  • 菜单栏常驻鱼形图标与倒计时:工作日显示距下一个休息日的时间(如 4天6小时),休息日当天显示"摸鱼中";设置中可开启「讨债模式」,上班打卡后显示精确到秒的下班倒计时,未打下班卡且超过下班时间后显示红色闪烁的超时正计时;可设置每隔 1–120 分钟弹窗提醒。
  • 万年历面板:大日期 + 星期、农历月日、年干支与生肖、日干支;摸鱼黄历(按节气月建、日支推算十二建除,结合干支禁忌过滤,生成现代生活宜/忌与主题签语,同一天内结果不变)。
  • 面板下方:年度摸鱼进度条、今年剩余休息日数、下一个法定假期(名称、日期范围、天数)、今日打卡(上班/下班一键打卡,记录持久化)。
  • 主窗口六页:
    • 上班日历:月历视图,休/假/班徽标、假期名称与农历日、打卡圆点;显示本月应上班时长,点选日期可查看详情,并标记当天为"调休上班"或"额外休息"(自定义调休)。讨债模式下额外显示「工时与生活警戒线」:把所选日和所在周的排班工时、已打卡实际工时与国家规定的每日 8 小时/每周 40 小时对比,超过设定阈值(默认 150%,即 12/60 小时)时给出警示文案。
    • 打卡:全部打卡记录(日期、上下班时间、扣除午休后的实际工时),可补记任意日期、修改上下班时间、删除记录。
    • 加班统计:按天条形图汇总本周、本月晚于设定下班时间的实际打卡时长与超时天数;讨债模式下显示更直接的生活化提醒文案。
    • 节假日:列出当年全部法定假期与调休安排,可修改任意假期的起止日期(同名假期的官方调休会一并被替换)、添加自定义假期、恢复官方安排。
    • 提醒:上下班时间提醒(智能跳过休息日)、双休/单休/单双交替工作周,休息日可自由选择周几(如周一、周三),按日/工作日/每周/单次的自定义提醒;通知权限管理。
    • 设置:讨债模式及超时弹窗提醒、工时警戒线(每日/每周标准工时与警示阈值)、登录时自启、数据源模板、本地缓存状态。
  • 休息日判定优先级:节假日(含修改)> 调休上班(含自定义)> 个人工作周 > 普通周末。单双交替按锚定周一与单双属性推算任意日期。
  • 节假日数据来自 holiday-cn(每日自动同步国务院放假公告),每年无需更新 App。
  • 可选登录时自启(用户级 LaunchAgent,与 MGUpd 相同机制)。

构建与运行

需要 Xcode Command Line Tools 和 Swift 5.8+。在本目录运行:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer sh scripts/build-app.sh
open dist/MFish.app

脚本生成针对当前机器架构的 dist/MFish.app 并做 ad-hoc 签名,不是 Developer ID 签名或公证发行包。首次启动会打开上班日历窗口(设置页可开启登录启动);之后启动只驻留菜单栏。建议先将应用复制到 /Applications 或 ~/Applications 再启用登录启动,移动应用后需重新开启。

数据源

  • 默认 URL 模板:https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{year}.json。
  • 设置中可改为任何包含 {year} 占位符的 HTTPS 地址(如 jsDelivr 镜像 https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{year}.json),保存后立即重新拉取。
  • 启动时拉取当年与下一年,之后每 24 小时刷新一次;失败后 1 小时重试。下一年安排未公布时返回 404,属正常情况,不报错。
  • 仅 HTTPS、禁止重定向、响应上限 1 MiB、校验年份与日期合法性。无遥测,除数据源外不发起任何网络请求。
  • 离线时使用本地缓存;完全没有缓存时降级为纯周末计算,面板会提示"未含节假日数据"。

提醒与打卡

  • 提醒由 App 常驻触发(每 30 秒检查),退出 App 后不会提醒;到点后有 30 分钟宽限,睡眠唤醒后补发一次,同一天同一提醒只发一次。
  • 上下班提醒仅在工作日触发;自定义提醒支持每天、仅工作日、每周指定星期几、单次(触发后自动停用)。
  • 在「提醒 → 工作作息」中可开启午休,默认时段为 12:00–13:00,可修改开始、结束时间并分别开关提醒;需启用工作作息和系统通知后才会提醒,休息日自动跳过。打卡工时会扣除实际与午休重叠的时长;本月应上班时长也按设定午休扣除。
  • 「节假日 → 自定义调休 / 休息日」支持全天或同日内的起止时间,可编辑已有标记。按时段休息只扣除与排班重叠的净工时,按时段上班使用指定区间,均扣除午休重叠;月应上班时长和日/周排班同步更新,实际打卡工时不受影响。
  • 「设置 → 工时警戒线」可修改对比基准与警示阈值,默认每日 8 小时、每周 40 小时、超出 150%(12/60 小时)才警示;阈值按严格大于判断,12 小时整不触发。该对比仅作健康提醒,不构成加班合法性判断;排班工时包含未来工作日,已打卡工时只统计完整上下班记录。
  • 首次开启提醒会请求系统通知权限;被拒绝时请在系统设置的"通知"中允许 MFish。
  • 打卡与提醒触发记录:~/Library/Application Support/MFish/records.json,原子写入,损坏时不覆盖。

摸鱼黄历规则

  • 月建以太阳视黄经近似计算十二个「节」,交节当地日整日切换,不以农历初一换月;接近午夜的交节可能有一天误差。
  • 十二建除由 (日支索引 − 月建索引 + 12) % 12 得到,对应建、除、满、平、定、执、破、危、成、收、开、闭。
  • 每个建除日配置主题事项,再用部分彭祖百忌的现代类比过滤冲突;不涉及医疗等不宜类比的条目。宜/忌各三项,签语与建除主题一致,不再随机抽词。
  • 面板显示月建与建除日,悬浮可查看依据。这是传统规则的趣味转译,并非完整通书或办事吉凶建议。当前不请求在线黄历服务。

数据与行为

  • 配置:~/Library/Application Support/MFish/config.json(含假期修改、自定义调休、作息、自定义提醒与讨债模式),原子写入;读取损坏文件时不会覆盖原文件,本次运行不再写入。
  • 缓存:~/Library/Application Support/MFish/holidays/<year>.json,含拉取时间;损坏的缓存视为缺失并重新拉取。
  • 假期修改与自定义调休只影响本机计算,保存在配置中;数据源更新不会覆盖你的修改。
  • 登录项:~/Library/LaunchAgents/local.mfish.MFish.login.plist;关闭开关移除文件,下次登录生效。卸载前请先关闭该开关。
  • 睡眠期间不刷新,唤醒后随 30 秒计时恢复;倒计时按本机时区计算。
  • 农历与干支由 Foundation 中国历法本地推算:年干支以正月初一为界,日干支以 1949-10-01(甲子日)为锚连续推算,不依赖网络。

开发

  • Sources/FishCore:休息日日历、工作周与调休合并、提醒引擎、打卡存储、农历干支、倒计时、年度进度、黄历、数据源拉取与缓存,纯逻辑,swift test 覆盖(67 项测试)。
  • Sources/MFish:菜单栏万年历面板、六页主窗口、通知、LaunchAgent。

许可

GPLv3,与工作区其他工具一致。

About

 打工人时间统计工具……是吗?

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0