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