如果把 GitHub 贡献热力图——那种一张密密麻麻的绿色小方块记录你过去一年提交过代码的日子——用在阅读记录上会怎样我第一次看到 GitHub Heatmap for Reading 这个名字时脑子里冒出来的问题是这不就是给阅读套了一个“打卡游戏”的外壳吗后来我按这个思路搭了一个最小版本才发现它真正改变的不是记录方式而是人对“长期阅读”这件事的感知方式。如果只是把每天“读了没有”变成绿色方块那它确实很像打卡。但真正有意思的地方是当记录维度从“今天读了”变成“这一周到底有几天在读”长期阅读的节奏会第一次以清晰的时间序列呈现在你面前。你会看到习惯在哪里断裂也能看到它在什么时候稳定下来。这篇文章想聊的不只是某个叫 GitHub Heatmap for Reading 的项目而是一套可以被复制的阅读记录与可视化思路。你可以用它去评估一个现成项目也可以自己动手做一个适合自己流程的版本。1. 为什么一张热力图能改变阅读的持续感1.1 GitHub 热力图本身就是一套行为反馈系统GitHub 主页上的那套绿点矩阵本质上是一个“行为可视化面板”。它的输入是 commit、pull request 等事件输出是一张按日期排列的颜色网格。颜色越深代表当天活动越多。它并不直接告诉你“代码写得好不好”只告诉你“今天有没有往项目里留下记录”。阅读和写代码在长期积累上有相似之处。写代码的进度通常由提交频率体现而阅读进度常常被我们以“看完了多少本”来评价。两本同样读完的书可能一本花了三天集中读完另一本断断续续读了一个月。从最终结果看都是“读完”但从过程看后者包含大量碎片时间和被迫中断。如果只看总数很难发现哪种阅读节奏更适合自己。GitHub 热力图把“发生过”和“没发生”变得一目了然。一个连续三十天有绿色块的人哪怕每天只改了几行文档也比“一个月集中提交一次”的人更容易被系统判定为持续活跃。阅读也一样每天翻二十页比周末一口气读两小时更容易形成稳定习惯。热力图不是鼓励你追求形式上的连续而是帮助你看见自己的真实节奏。1.2 阅读热力图的核心不是“打卡”而是建立长期视角如果一个人每天只在睡前读五分钟热力图会显示出一整片浅绿色。从打卡角度看这确实算“完成”从阅读质量看可能并不值得称道。但热力图的价值恰恰在于它暴露出“浅绿”是常态而不是让人用一句“我天天在读书”自我安慰。我自己的体验是当你把数据拉到一年维度时你会很快发现真正有效的阅读时间其实集中在少数几个阶段。这不是坏事。它说明你在某段时间有充足精力而在另一段时间精力被工作或生活挤占。热力图不会替你判断哪个阶段该读更多但它能让你不再用“忙”这个模糊概念解释一切。所以我给这套方案的主判断是GitHub Heatmap for Reading 这一类工具真正解决的不是“多读书”的问题而是“长期阅读过程不可见”的问题。它让阅读从主观感受变成一组可回看的记录让你有条件对自己过去的阅读节奏做分析而不是一年到头只留下一句“今年好像没读几本书”。2. 动手之前先理解阅读热力图的数据模型2.1 记录什么字段决定了你能画什么图很多人一开始想直接用现成项目但遇到第一个障碍就是不知道往里面填什么数据。这其实比选工具更值得先想清楚。一个阅读热力图背后至少需要三类信息日期哪一天发生了阅读行为。时长或页数这一天的阅读量有多少。书籍标识这部分阅读属于哪一本书。如果只有日期你能得到“今天是否阅读”的二维图。加上时长或页数后颜色才能分深浅。加上书籍标识后你还能进一步思考“这本书是不是拖了太久”“哪一类书更容易让我连续阅读”。对于个人长期使用我建议在最小字段之外再加几个可选字段比如阅读起始页码、结束页码、笔记链接、阅读场景通勤、睡前、周末上午。这些字段不一定都进热力图但它们能帮你做更细的复盘。比如连续两周的绿色块都集中在深夜说明你的阅读时间有被高工作量挤到边缘的迹象。下面是一个适合作为长期记录的数据结构示例{ 2025-06-01: { minutes: 45, book_id: book_001, book_title: 人类群星闪耀时, pages: 30-58, note_url: obsidian://note/reading-2025-06-01 }, 2025-06-02: { minutes: 20, book_id: book_001, book_title: 人类群星闪耀时, pages: 59-78, note_url: } }2.2 为什么要用纯文本或 JSON 保存阅读数据大多数阅读 App 都自带统计页有的还能画柱状图。但这类统计的问题在于数据在闭环产品里导出格式不统一甚至根本不支持导出。一旦你想在年底把“这一年读过的书”和笔记、书评、时间投入放在一起分析就会很吃力。用 JSON、Markdown 或 YAML 这类纯文本保存阅读记录核心优势是可迁移、可版本管理、可编程处理。即使当前用来画图的脚本坏掉了只要 JSON 还在换一个渲染脚本就能恢复整套视图。这有点像是把阅读数据当成一份个人仓库里的代码每天加点记录定期提交沉淀出自己的“阅读 commit 历史”。对普通用户来说这听起来可能太重了。但如果你是对热力图这件事本身感兴趣的人你大概率不反感数据落到本地文件里。2.3 热力图只是视图数据才是资产很多开源项目的 README 会放一张漂亮的热力图截图。但你要理解那张图只是最终产物它能否长期运转取决于数据从哪来、数据格式是否开放、能否支持自己补充。如果一个项目只提供静态图生成却不支持导入自己的历史记录那它更像一个展示玩具而不是长期管理工具。我更喜欢把它看成两段流程数据收集把阅读事件记录成结构化文本。数据渲染把结构化文本变成热力图。前者决定你能否坚持后者决定你是否愿意回看。两者之间数据格式是承重墙。3. 三十分钟做一个最小可用版本3.1 数据收集先用手边最顺手的方式记录不一定要一上来就写脚本。更稳妥的做法是先用手机备忘录、日历或一个简单的表格记录一个月每天记录只需几秒。记录内容可以只有两个日期和当天的阅读分钟数。等积累了二十多条记录后再把它们转成 JSON交给脚本生成热力图。这种做法的好处是你能在投入技术开发之前先确认自己是否可以稳定记录。如果连用备忘录记录都坚持不了那再漂亮的自动化流程也无济于事。反过来一旦确认自己能稳定记录就可以放心把数据迁移到本地 JSON再逐步增加字段和自动化。3.2 用 Python 读取 JSON生成自定义 SVG 热力图我没有用现成的热力图库因为自定义 SVG 很简单。基本思路是把一年 365 天按周排列生成一个格子矩阵再根据每天阅读分钟数给格子填充不同颜色。一个最小脚本的结构如下import json from datetime import date, timedelta def load_log(path): with open(path, r, encodingutf-8) as f: return json.load(f) def get_level(minutes): if minutes 0: return 0 if minutes 20: return 1 if minutes 40: return 2 if minutes 60: return 3 return 4 def build_cells(log, year2025): cells [] day date(year, 1, 1) while day date(year, 12, 31): day_log log.get(day.isoformat(), {}) minutes day_log.get(minutes, 0) level get_level(minutes) cells.append({ date: day, level: level, minutes: minutes, book_title: day_log.get(book_title, ) }) day timedelta(days1) return cells真正的 SVG 渲染包含画布布局、坐标换算、颜色选择和小 tooltip。这部分完全取决于你想做得多么精致。关键是用一个动态 key 来控制颜色通常是这样颜色浓度与阅读分钟数正相关同时把“0 分钟”显示为浅灰背景保留热力图的整体形态。代码并不是完整生产版本但它说明了一个核心机制热力图本质是“数据映射到颜色”的过程。3.3 用 GitHub Actions 实现每天自动更新如果数据文件放在 GitHub 仓库里可以借助 GitHub Actions 在每天固定时间拉取最新记录、重新生成 SVG 并提交。这样你只需要在本地更新 JSON热力图会自动刷新。一个常见的 workflow 结构如下name: update_reading_heatmap on: schedule: - cron: 30 22 * * * workflow_dispatch: jobs: build: runs-on: ubuntu-latest permissions: contents: write steps: - uses: actions/checkoutv4 with: persist-credentials: false - uses: actions/setup-pythonv5 with: python-version: 3.12 - run: python scripts/generate_heatmap.py - run: | git config --global user.name github-actions[bot] git config --global user.email github-actions[bot]users.noreply.github.com if [[ git status --porcelain ]]; then git add . git commit -m chore: update reading heatmap git push fi这里有一个容易踩坑的点schedule事件里的 cron 用的是 GitHub Actions 的 UTC 时区。如果希望每天早上 8 点更新而你在东八区就要换算成 0 点或前一晚 22 点。这个不调整看起来就是“我明明设置了定时任务为什么图没有按预期时间更新”。3.4 本地先跑通再谈自动化从工程经验看这类小项目最容易出问题的不是代码逻辑而是“数据路径不对、Python 版本不一致、Git push 权限不足”这类环境问题。所以顺序应该是先在本地准备一条样例数据跑通脚本确认 SVG 生成成功。把生成结果放到浏览器里打开确认颜色映射和日期分布符合预期。再提交到 GitHub 仓库配置 Actions。最后把真实记录补充进去观察第二天的自动更新是否正常。如果你发现自动更新没有触发排查链路通常是这样先看 JSON 文件是否仍能被脚本正常读取。再看 Actions 日志里脚本是否报错。然后检查git status --porcelain是否检测到了文件变化。最后确认 workflow 是否有contents: write权限GITHUB_TOKEN 是否被仓库设置禁止了写操作。大部分“图没更新”的问题都出在最后一步提交没有权限或者没有真正产生文件变化。4. 在 GitHub 上挑阅读热力图项目时我看什么4.1 先看数据是不是你的如果你不想从零写代码而是想直接使用 GitHub 上的现成项目最值得关心的不是 UI 是否好看而是你的阅读记录最终存在哪里。有些项目把数据保存在本地 JSON这是最好的形态。有些数据保存在某个云服务上虽然方便但你要确认导出接口是否存在。还有一些项目直接把记录塞进 README 或 issue 里可视化很方便但想按日期做聚合统计时就会很痛苦。我的判断标准很简单如果项目的数据层是开放的、可导出的即使它的热力图样式不太完美也值得继续看。相反如果项目把数据锁在私有存储里再漂亮的热力图也只是用来演示而已。4.2 再看热力图定制能力一个项目能不能真正适配你的阅读习惯要看它是否支持调整统计粒度。比如配置项说明常见设置颜色级别数将阅读量映射到几种颜色4 到 6 级统计字段用分钟数还是页数计深浅minutes / pages / both空白颜色没有阅读的记录是否显示灰色块否显示为背景色日期范围只显示本年还是支持自定义周期近 365 天或自然年多标签能不能区分“在读”和“想读”仅用于筛选不参与热力图颜色这些配置不影响核心功能但决定了热力图放在你屏幕上是否真的有用。我见过不少项目默认配色很好看但统计周期写死为自然年如果你想看“从今天往前翻 365 天”就做不到长期使用会很受限。4.3 三看依赖和维护状态Stars 数量不代表一切。一个只有几百星但最近半年还在更新的项目通常比一个几千星但两年没动静的项目更适合长期使用。重点看三点是否依赖某个特定系统版本或第三方服务。是否默认带自动化更新能力。最近一次提交是什么时候。如果项目依赖了一个冷门的工具链光是安装依赖就耗掉一晚上那它的“开箱体验”就不合格。个人项目不需要复杂架构复杂反而是风险。4.4 最后看它解决的是“记录”还是“展示”很多 GitHub 项目只做了展示端你提供一个数据文件它生成一张图。但“记录”这一步它没有覆盖。这不一定是个缺点反而可能是优点。因为记录方式太个人化有人习惯写在日历里有人习惯用 Kindle 标注有人只想睡前随手填一下。我自己更推荐选择“只做展示不强行接管记录”的项目。这样你的记录流程可以独立演进今天用备忘录明天换成脚本热力图端不用跟着改。反过来如果一个项目既要求你用它的输入格式又要把记录存到它的数据库那你会逐渐被绑在一个细枝末节上。5. 真正把阅读热力图长期用起来的三个策略5.1 把记录成本降低到十秒以内再好的数据模型如果每天记录需要打开电脑、找到脚本、打开 JSON 文件人很快会放弃。更现实的做法是准备一个固定入口比如手机备忘录置顶一条“今日阅读”文本每天睡前把分钟数和页码写进去。周末抽五分钟把这一周记录批量补进 JSON。或者干脆写一个简单的命令行工具输入read 45 30-58就能追加一条记录。核心原则是不要试图在阅读结束后立刻打开电脑。阅读后的惯性很容易被技术操作打断。先只记录“日期 分钟”其他字段等周末一次性补充。5.2 定义适合自己的“有阅读的一天”热力图会放大你对“空白格子”的注意。如果你把标准设成“每天至少读 30 分钟”那大部分格子都会是空的你会很快感到挫败。我建议把标准调低一点只要当天读了 10 分钟以上就算作有效阅读日。10 分钟看起来很少但它的价值在于让绿色格子保持连贯。当一个人状态好的时候自然会读半小时以上状态差的时候10 分钟也能守住“今天有翻书”的底线。色调分级也可以按这个逻辑设计浅绿代表 10 到 20 分钟中绿代表 20 到 40 分钟深绿代表超过 40 分钟。这样热力图不会因为“某天读得比较少”而出现大片空白同时又能区分高投入和低投入的日子。5.3 把热力图当复盘工具而不是自我惩罚工具我最开始使用这类工具时很容易陷入“不能让绿点断掉”的心态。连续断了两天心里就开始焦虑甚至会为了补记录而刻意在凌晨看几页书。这已经完全偏离了阅读的本意。热力图真正的作用应该是帮助复盘哪些星期特别忙、哪些阶段阅读时间明显萎缩、哪本书读了很久还没结束。你可以问自己是我没有时间还是这本书不适合现在的状态是精力问题还是阅读安排不合理这些问题会比“我今天没打卡”更有价值。6. 适用边界它不是万能的但值得借鉴6.1 适合谁不适合谁GitHub Heatmap for Reading 这类方案适合愿意把阅读当作长期项目来管理的人。它不适合追求纯粹阅读体验的人——如果你觉得“记录本身会打断阅读”那就不必强求。它也不适合只是偶尔读一两本书的人因为热力图需要足够多的数据点才会形成有意义的图像。一个实用的判断标准是如果你在过去半年里有“想回头看读过什么”的冲动但发现自己什么也想不起来那说明你需要一个数据系统。如果你完全没有这个需求只是觉得绿点矩阵好看那最好先别搭系统先记录一个月再说。6.2 这类工具的真正价值是把阅读变成一组可分析的数据热力图本身只是一个入口。当你积累了 3 个月的 JSON 数据后你可以随手写一个脚本统计每周平均阅读天数、不同时间段的重合情况、单本书从开始到结束的周期。这些分析不需要复杂工具Python 加一个 CSV 就能完成。从更长远的角度看阅读热力图和其他个人量化系统可以联动。比如把阅读数据和睡眠记录放在一起你可能会发现睡眠较晚的那几周阅读时长却变长了。这不一定代表因果关系但它能让你更具体地观察自己的生活节奏而不是凭感觉判断“最近很忙”。6.3 我的实际建议先手工维护一个月如果你对这个想法动心了不要立刻搭建完整的自动化系统。更建议的做法是在手机备忘录里记每天阅读分钟数坚持一个月。月底拿出十分钟把这 30 条记录填进 JSON然后用脚本生成一张简单热力图。如果这个动作让你觉得有成就感再考虑接入 GitHub Actions 和自动提交。如果你在一个月内频繁遗忘记录说明记录入口不够顺手或者你并没有那么需要一套可视化系统。这时候就该回到“降低记录成本”而不是继续加功能。这件事最有意思的地方在于它不只是教你用一个工具而是让你重新理解长期习惯是怎么形成的。习惯不是靠“某一天狂读三小时”建立的而是靠一张张并不起眼的浅绿色方块在时间轴上连成一片。GitHub Heatmap for Reading 说到底只是把这种长期规律摆到了你面前。