Skip to content
Back to search

weekly-time-report

SkillWorks with Claude CodeGitHub

生成「时间使用周报」HTML 可视化报告——从 Mac 日历(mac-calendar-mcp)读取指定时间段,按色系统计各板块时长/占比/与上期对比,逐色块拆解,并输出本周总结与下周建议。用户说“出周报”“看看这周/上周时间怎么用的”“统计时长”时使用。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yq-space--time-ledger-private/badge.svg)](/listings/yq-space--time-ledger-private)

HTML

<a href="/listings/yq-space--time-ledger-private"><img src="/api/listings/yq-space--time-ledger-private/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

作为 Claude Code Skill 安装(推荐):

git clone https://github.com/yq-space/time-ledger.git
cp -R time-ledger ~/.claude/skills/weekly-time-report

之后在 Claude Code 里说「出周报」「看看上周时间怎么用的」即可触发。

也可以只当命令行工具用:

python3 scripts/weekly_report.py --start 2026-11-14 --end 2026-11-21

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 108 lines
  1. ---
  2. name: weekly-time-report
  3. description: 生成「时间使用周报」HTML 可视化报告——从 Mac 日历(mac-calendar-mcp)读取指定时间段,按色系统计各板块时长/占比/与上期对比,逐色块拆解,并输出本周总结与下周建议。用户说“出周报”“看看这周/上周时间怎么用的”“统计时长”时使用。
  4. ---
  5. # 时间使用周报 v2
  6. 基于已安装并授权的 `mac-calendar-mcp`(只读,本地索引)生成可视化 HTML 报告。
  7. ## 报告架构(固定)
  8. 1. **时间去向**:各板块总时长 KPI、占比堆叠条、与上期分组条形图 + 表
  9. 2. **各色块详细分析**(固定顺序):
  10. - 2.1 蓝色(维护 + 规划)→ 2.2 紫色(成长)→ 2.3 灰色(睡眠 + 生活维持)→
  11. 2.4 黄色(家人朋友)→ 2.5 绿色(锻炼/当下)→ 2.6 粉色(自省)→ 2.7 红色(娱乐)
  12. - 每节含:总量/占比/较上期变化、内部构成条形图、每日分布、观察要点
  13. 3. **本周总结**:自动指标 + 关键数字 + **Claude 补写的「自我观察」**
  14. 4. **下周建议**:自动诊断 + **Claude 补写的「行动清单」**
  15. > 占比用 100% 堆叠条而非饼图:板块有 8 类且名称长,饼图难比较、标签会打架(dataviz 规范:part-to-whole 用 stacked bar)。
  16. ## 步骤
  17. 1. **确定日期范围**
  18. - 未指定 → 上一自然周(周一~周日)
  19. - “本周/这周” → `--week this`
  20. - 具体日期 → `--start YYYY-MM-DD --end YYYY-MM-DD`(左闭右开);“11.14~11.20” → start=11-14, end=11-21
  21. 2. **跑脚本**
  22. ```bash
  23. python3 ~/.claude/skills/weekly-time-report/scripts/weekly_report.py \
  24. --start 2026-11-14 --end 2026-11-21
  25. ```
  26. 输出:
  27. - `~/.claude/skills/weekly-time-report/out/report-<start>.html`(脚本会自动打开浏览器)
  28. - stdout 的 Markdown 摘要(板块对比、自动诊断、关键指标)
  29. 3. **补写第 3、4 节**(关键步骤)
  30. - 打开生成的 HTML,找到两个标记并替换:
  31. - `<!-- CLAUDE_SUMMARY -->` → 本周总结的「自我观察」HTML 片段
  32. - `<!-- CLAUDE_ADVICE -->` → 下周建议的「行动清单」HTML 片段
  33. - 用 `<h4>` + `<ul><li>` 结构,直接写 `<b>` 强调;不要改数据表。
  34. - 写完用 `open "<绝对路径>"`(macOS)在浏览器重新打开,确保看到的是补写后的完整版。
  35. 4. **在对话里**给出精简版结论(HTML 已在浏览器展示,不要重复贴全部数字)。
  36. - 不要引导用户点击聊天里的 HTML 文件链接:Claude Code 的 IDE 链接固定以源码打开,无法改为预览。直接说「已在浏览器打开」,需要时可再给 `open` 命令。
  37. ## 第 3 节「自我观察」怎么写
  38. 必须回答三个问题,并尽量指出**用户自己没看见的行为**:
  39. - 哪些板块/任务**时间不足**(对照日历描述里的意图,如紫色“想花更多时间”、蓝色“希望越来越少”)
  40. - 哪些**时间过多**(含一次性事件要注明)
  41. - 2–4 条「隐性规律」:分类漂移、恢复外包给碎片、周末补偿、被动输入占比高、记录替代产出等
  42. 只写有数据支撑的观察,引用具体日期/时长作证据;不确定处标注“如不是请告知”。
  43. **判定“时间不足”的证据来源只有两个**:用户明确说过的目标,或日历描述里写明的意图。用户提问时的举例(如“比方说单词学习时长”)**不是**目标,不得当成缺口写进报告;没有记录只说明“没记录”,不说明“没做”。
  44. ## 第 4 节「行动清单」怎么写
  45. 原则:**ISTP + 《精力管理》《时间贫困》《习惯的力量》《刻意练习》**,顺应性格而非对抗:
  46. - 精力周期排程(高精力窗口放深度任务,低精力放机械任务)
  47. - 深度块要有可检验产出(刻意练习:目标 + 反馈 + 略超舒适区)
  48. - 用「线索→惯常→奖励」替换具体习惯(习惯的力量),一次只改 1–2 个
  49. - 批量处理 + 保护块,降低切换与时间贫困感(时间贫困)
  50. - ISTP:先动手再听课、允许爆发日但设“最小日”、重复劳动 SOP 化
  51. 必须覆盖四个检查项(用户指定):
  52. 1. **碎片化**(≤30min 占比 / 中位段长)→ 减少上下文切换
  53. 2. **相邻同类**(同类相邻比例)→ 相近任务是否挨着排
  54. 3. **任务间休息**(无休息衔接次数 / 最长连续在忙)→ 是否主动休息
  55. 4. **睡眠规律**(入睡/起床波动、午睡时长)
  56. 每条建议要可执行(含数字目标与触发时机),不要泛泛而谈。
  57. ## 口径约定(固定)
  58. - 全周时间 = 起止日之间的小时数;清醒时间 = 全周 − 睡眠。
  59. - 色系映射:先按日历名(`CAL_COLOR_OVERRIDE`),再用颜色 RGB 兜底。
  60. - **色块语义**(不是按日历原名,而是按时间用途):
  61. - 蓝色 = 日常维护类:必须做但不产出的事,如贴发票、刷题保持手感;
  62. - 紫色 = 深度工作:需要深度思考、有可交付产出的事,如写博文、开发 MCP、把某类 SOP 做成 skill 并开源;
  63. - 灰色 = 固定开销:睡眠、吃饭、通勤等基本固定、压不动的时间(拆成睡眠/生活维持);
  64. - 黄色 = 社交与亲密关系:陪伴家人、约朋友聊天;
  65. - 绿色 = 当下分子时间:手工、锻炼、拼豆、遛弯等能脱离多巴胺劫持的活动;
  66. - 粉色 = 自我观察:感恩日记、自我肯定、mind dump;
  67. - 红色 = 无脑娱乐:刷社交媒体、打游戏,用醒目颜色提醒控制时长。
  68. - 还可以给「最想投入的目标」单独开一个色块(如开源项目),不承担其他语义,只用来让用户「看见」自己有没有真的花时间。
  69. - **日历会被重命名**(如蓝色日历现名「😡 | 课程学习,新知识学习,记笔记」)。因此工作块用别名列表 `BLUE_CAL_HINTS` / `PURPLE_CAL_HINTS` 匹配,`CAL_COLOR_OVERRIDE` 也要同步加别名;指标突然归零时先 `uvx mac-calendar-mcp calendars` 核对名称。
  70. - 紫色中「驾考/科目三/路线图/考试」(不含工作关键词)记为驾考,并从纯工作中剔除。
  71. - 睡眠:`#sleep`/`睡觉`/`睡不醒`;主睡眠 = ≥3h。跨周被截断,只报总量与规律性,不深究单日。
  72. - **所有时间运算必须用本地时区**(脚本已 `astimezone(TZ)`);不要用 UTC 小时解读时段。
  73. - 娱乐红线 8 h/周(按天数折算);娱乐里命中求职/学习关键词的记录要单列复核。
  74. - **输入 / 输出**:只统计工作块(蓝+紫)。标题含产出动作词(写/实现/跑通/测试/demo/交付…)记为输出,纯消费动词(看/学/听/读/课程…)记为输入,两者都中按输出算。目标输入:输出 ≈ 2:1(输出 ≥33%)。
  75. - **验收标准**:产出块标题含验收词(通过/跑通/测试/demo/交付…),或「数字 + 量词」(如「5 问 5 答」)才算 ✓;只有数字(如课程编号 W2.4)不算。每周目标 ≥3 个 ✓。
  76. - 排除全天事件与节假日/生日/Siri/gmail/提醒事项类日历。
  77. ## 配置
  78. 改脚本顶部:`BLUE_CAL`/`PURPLE_CAL`/`GRAY_CAL_HINT`/`ENT_CAL_HINTS`/`CAL_COLOR_OVERRIDE`/`*_KW`/`ENT_REDLINE_PER_WEEK`/`TZ`。
  79. ## 前置检查
  80. - `uvx mac-calendar-mcp calendars` 能返回日历;
  81. - 索引过期先 `uvx mac-calendar-mcp index`;
  82. - 无权限先 `uvx mac-calendar-mcp authorize`(用户点“允许”)。
README.md · README · 162 lines
  1. # Time Ledger · weekly-time-report
  2. **中文** | [English](README.en.md)
  3. 把 Mac 日历里的一周,变成一份看得懂、能行动的 **时间使用周报**。
  4. 这是一个 [Claude Code](https://claude.com/claude-code) Skill:脚本负责取数、统计和画图,Claude 负责补写「自我观察」和「行动清单」。最终产出一份单文件、可离线打开的 HTML 报告,同时输出 Markdown 摘要。
  5. > 📄 示例报告:[samples/report-2026-11-14.html](samples/report-2026-11-14.html)(下载后浏览器打开)
  6. ---
  7. ## 它解决什么问题
  8. 日历记录了大量真实的时间痕迹,但很少有人会回头统计。这个项目把一次性的「翻日历」变成可重复的流程:
  9. - **按色系统计**:把你自己的日历体系汇总成板块时长、占比,并与上一期对比。颜色不是装饰,是时间的「预算科目」:
  10. | 颜色 | 含义 | 例子 |
  11. | --- | --- | --- |
  12. | 蓝 | 日常维护:必须做,但不产出 | 贴发票、刷题保持手感 |
  13. | 紫 | 深度工作:需要思考、有可交付产出 | 写博文、开发 MCP、把 SOP 做成 skill 开源 |
  14. | 浅灰 | 固定开销:睡眠、吃饭、通勤 | 基本固定、压不动,融进背景色 |
  15. | 黄 | 社交与亲密关系 | 陪家人、约朋友 |
  16. | 绿 | 当下分子时间:远离多巴胺劫持 | 手工、锻炼、拼豆、遛弯 |
  17. | 粉 | 自我观察 | 感恩日记、自我肯定、mind dump |
  18. | 红 | 无脑娱乐:用醒目的颜色提醒自己 | 刷社交媒体、打游戏 |
  19. 还可以给你**最想投入的目标**单独开一个色块(比如「开源项目」),它不承担别的含义,只用来让你「看见」自己有没有真的在这件事上花时间。
  20. - **逐板块拆解**:每个板块的内部构成、每日分布、观察要点,固定顺序、固定口径。
  21. - **自动诊断**:碎片化(≤30min 占比 / 中位段长)、上下文切换、同类任务相邻度、块间休息、最长连续在忙、睡眠规律、输入与输出配比、娱乐红线。
  22. - **Claude 补写**:在自动指标之上,结合你的日历标题和意图,写「自我观察」和可执行的「行动清单」。
  23. ## 效果
  24. 报告固定四节:
  25. 1. **时间去向** — KPI、100% 堆叠占比条、与上期分组对比图 + 表
  26. 2. **各色块详细分析** — 每个色系:总量 / 占比 / 较上期变化、内部构成条形图、每日分布、观察
  27. 3. **本周总结** — 自动指标 + 关键数字 + 产出清单 + 自我观察(Claude 补写)
  28. 4. **下周建议** — 自动诊断 + 行动清单(Claude 补写)
  29. 图表都是内联 SVG,报告是单个 HTML 文件,支持系统深色模式,不依赖任何 CDN 或 JS。
  30. ## 工作原理
  31. ```
  32. Mac 日历 (EventKit)
  33. │ uvx mac-calendar-mcp events ... (只读,本地索引)
  34. ▼
  35. scripts/weekly_report.py
  36. ├── 取数 / 按色系归类 / 计算指标(工作、睡眠、娱乐、碎片化、切换、输入输出…)
  37. ├── 渲染 HTML → out/report-<start>.html
  38. └── 打印 Markdown 摘要 → stdout
  39. ▼
  40. Claude 读取 HTML,替换两处占位标记:
  41. <!-- CLAUDE_SUMMARY --> → 第 3 节「自我观察」
  42. <!-- CLAUDE_ADVICE --> → 第 4 节「行动清单」
  43. ```
  44. ## 目录结构
  45. ```
  46. weekly-time-report/
  47. ├── SKILL.md # Claude Code Skill 定义(触发词、口径、写作要求)
  48. ├── scripts/weekly_report.py # 取数 + 指标 + HTML 渲染(仅用 Python 标准库)
  49. ├── samples/ # 示例报告
  50. └── out/ # 运行输出(不提交)
  51. ```
  52. ## 前置要求
  53. - **macOS**(依赖系统日历,Linux / Windows 不适用)
  54. - [**uv**](https://docs.astral.sh/uv/)(提供 `uvx`)和 [`mac-calendar-mcp`](https://pypi.org/project/mac-calendar-mcp/)
  55. - **Python 3.8+**(脚本只用标准库,无需安装依赖)
  56. - **Claude Code**(用于补写第 3、4 节;只用脚本生成 HTML 也可以)
  57. 首次使用前需要授权日历访问:
  58. ```bash
  59. uvx mac-calendar-mcp authorize # 弹窗点「允许」
  60. uvx mac-calendar-mcp index # 建立本地索引
  61. uvx mac-calendar-mcp calendars # 核对日历列表
  62. ```
  63. ## 安装
  64. 作为 Claude Code Skill 安装(推荐):
  65. ```bash
  66. git clone https://github.com/yq-space/time-ledger.git
  67. cp -R time-ledger ~/.claude/skills/weekly-time-report
  68. ```
  69. 之后在 Claude Code 里说「出周报」「看看上周时间怎么用的」即可触发。
  70. 也可以只当命令行工具用:
  71. ```bash
  72. python3 scripts/weekly_report.py --start 2026-11-14 --end 2026-11-21
  73. ```
  74. ## 使用
  75. ```bash
  76. # 上一自然周(周一 ~ 周日)
  77. python3 scripts/weekly_report.py
  78. # 本周至今
  79. python3 scripts/weekly_report.py --week this
  80. # 指定日期(左闭右开)
  81. python3 scripts/weekly_report.py --start 2026-11-14 --end 2026-11-21
  82. # 从起始日算 7 天
  83. python3 scripts/weekly_report.py --start 2026-11-14 --days 7
  84. # 不自动打开浏览器
  85. python3 scripts/weekly_report.py --no-open
  86. ```
  87. 输出:
  88. - `out/report-<start>.html`(脚本会尝试自动打开浏览器)
  89. - stdout 的 Markdown 摘要,可喂给 Claude 继续分析
  90. ## 自定义配置
  91. 脚本的「世界观」默认按作者自己的日历体系写死,**开源使用前请先按自己的日历改造**。配置都在 [scripts/weekly_report.py](scripts/weekly_report.py) 顶部:
  92. | 配置 | 作用 |
  93. | --- | --- |
  94. | `TZ` | 本地时区,所有时间运算都按它换算 |
  95. | `CAL_COLOR_OVERRIDE` | 日历名关键词 → 色系映射(优先匹配)。**最常用**,按自己的日历名改这里即可 |
  96. | `BLUE_CAL_HINTS` / `PURPLE_CAL_HINTS` | 哪些日历算「工作块」,支持多个别名,防止日历改名后指标静默归零 |
  97. | `GRAY_CAL_HINT` / `ENT_CAL_HINTS` | 生活维持(灰)/ 娱乐(红)的日历名 |
  98. | `EXCLUDE_CAL_HINTS` | 排除的日历(节假日、生日、提醒事项等) |
  99. | `ENT_REDLINE_PER_WEEK` | 娱乐红线(小时/周,按天数折算) |
  100. | `*_KW` 系列 | 细分桶关键词:课程/代码、求职、驾考、睡眠、吃饭、交通、洗漱……以及输入/输出/验收词的判定 |
  101. | `WORK_HINTS` | 工作关键词,用于把「驾考」等非工作内容从成长类中剔除 |
  102. 色系归类是**两级**的:先按日历名匹配 `CAL_COLOR_OVERRIDE`,匹配不到再用日历颜色的 RGB 自动归类。所以最简单的改法是——把自己的日历在 macOS 日历里染成对应颜色,并把日历名关键词加进 `CAL_COLOR_OVERRIDE`。
  103. 更多口径约定(睡眠如何统计、输入输出如何判定、验收标准如何识别)见 [SKILL.md](SKILL.md)。
  104. ## 隐私说明
  105. - 日历数据**只在本机读取**,脚本不发起任何网络请求,也不上传任何数据。
  106. - `mac-calendar-mcp` 以只读方式访问日历。
  107. - 生成的报告包含你的日程标题和作息数据,**提交或分享前请自行脱敏**。仓库里的 `samples/` 是作者的示例输出(事件标题已匿名化),仅供预览效果。
  108. - `out/` 已在 `.gitignore` 中,避免误提交个人报告。
  109. ## 已知限制
  110. - 仅支持 macOS。
  111. - 关键词判定是中文启发式(看/学/听 = 输入,写/实现/测试 = 输出),标题写得越具体,统计越准。
  112. - 报告里的「自我观察」和「行动清单」依赖 Claude 生成;纯命令行运行会保留占位标记。
  113. - 色系语义(蓝=日常维护、紫=深度工作……)是作者的个人体系,请按需改造。
  114. ## License
  115. [MIT](LICENSE) © yq-space

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.