caveman 这个名字我第一次看到的时候还以为是个游戏模组或者岩石分类工具直到有一次我在整理项目记录时无意间翻到它的官网才反应过来——这是个时间追踪工具而且是个纯粹跑在命令行里的老派工具。用了一段时间之后我不得不承认它可能是目前最符合“记录真实工作痕迹”这个需求的小工具之一。它不推销、不社交、不弹窗只是安静地坐在终端里问你“刚才在做什么”然后把答案写进一个纯文本的数据库里。对那些每天要面对一堆开发任务、经常被会议打断、又需要向周报交代时间去向的人来说caveman 的价值不在于花哨而在于它的诚实和克制。它的使用场景非常明确你不想为“今天我干了什么”而费心回忆只想在每次切换任务、结束一项工作、或者一天收尾的时候花几秒钟回答几个问题剩下的汇总和统计让工具去做。适合的人群也相当清晰——程序员、独立开发者、研究型岗位、以及所有需要复盘时间去向但讨厌复杂操作的人。这篇文章我就把它的设计逻辑、安装方式、真实记录机制、报告生成和集成玩法完整拆一遍顺带把我踩过的一些坑也列出来。1. caveman 到底是什么一个时间追踪工具的设计思路1.1 为什么叫 caveman它的核心主张是什么caveman 由英国程序员 Simon Tatham 开发他是个老资格的开发者如果你用过 PuTTY应该对他的名字不陌生。这个工具的名字其实带着一点自嘲和返璞归真的意味——在一个充满云端同步、AI 助手和可视化仪表盘的时代它坚持“穴居人”级别的简单没有 GUI没有守护进程没有数据库服务器只有可执行文件和一个纯文本数据文件。它的核心主张可以用一句话概括记录工具不应该干扰你的工作。大多数时间管理软件的问题在于它们要求你事前去规划要求你建项目、建任务、建标签甚至要求你在任务开始前点一下“开始”。可是真实的工作节奏根本不是那样我们经常是被打断之后才意识到上一件事已经结束了或者一天过了大半才想起来需要记录。caveman 反其道而行之它只关心过去的事实不预测未来。你运行它的时候它只会问三个问题你刚才在做什么这件事是什么时候开始的你现在要切换到什么回答完毕它就安静退场。整个过程不会超过三十秒而且不需要你提前设置任何结构。这种设计理念让我联想到了另一个工具——ledger它同样是命令行、纯文本、不依赖云服务。它们共享同一类价值观数据属于用户工具只是辅助凡是能用文件解决的问题就不应该引入服务端。如果你习惯了那种“打开软件先选工作区再建任务”的流程caveman 会给你一种反直觉的轻松感因为你的记录成本被压到了最低。1.2 使用场景与目标用户caveman 适用的场景有很强的指向性。第一类是自由职业者和远程工作者你需要给客户分项目计费但又不想用复杂的工时软件第二类是程序员尤其是那些一天要在编码、代码审查、会议、文档之间切换多次的人用 caveman 记录切换过程非常自然第三类是研究者或者写作人员他们的工作成果很难用“完成了几个任务”来衡量但用时间片段来复盘却非常有效。不太适合 caveman 的人主要是两类一类是依赖项目经理分配任务、需要团队协作看板的人另一类是喜欢丰富图表和移动端提醒的用户。它也有一个配套的 HTML 报告生成能力可以生成按项目、按日期的统计页面但整体上它还是面向单体用户你的数据默认只存在你自己的工作目录下。当前的设计中也没有多人协作的概念所以如果你想拿它来做团队工时管理系统那大概率会失望。我个人的建议是如果你已经有一套基于日历的规划方式只是缺一个“事后回顾”的工具caveman 正好补位。它不会替代你的 TODO 列表而是给你一个可靠的“实际时间都花到哪里去了”的答案。2. 安装与初始化把 caveman 跑起来2.1 源码编译与安装注意事项caveman 的安装方式比较“古早”它在官网提供源代码包需要自己编译。别被这一步吓退实际上它的依赖非常少是一个标准的 ANSI C 程序只需要 make 和一个 C 编译器。在 Linux 和 macOS 上通常直接执行make就能编译出caveman可执行文件在 Windows 上则需要一个具备 make 能力的编译环境比如 MSYS2 或者 WSL。我安装时的具体步骤是这样的wget https://www.chiark.greenend.org.uk/~sgtatham/caveman/caveman-1.2.tar.gz tar -xzf caveman-1.2.tar.gz cd caveman-1.2 make sudo make install安装完成后把二进制加入 PATH然后建议设置一个别名因为caveman这个名字有点长每天敲很多遍会烦。我一般用cm作为别名。值得注意的一点是这个工具的帮助信息不是通过--help访问的你需要运行caveman之后在交互界面里输入help命令或者直接查看 man 文档。第一次接触的人容易在命令行里加--help发现没反应然后就以为安装失败了这其实只是设计上的风格选择——它把一切都收敛到了交互模式里。2.2 初始化向导与核心参数第一次运行 caveman 时它会在当前目录初始化一个名为caveman.log的数据文件并启动一个向导。这个向导会询问一些基本信息比如你的默认工作开始时间、项目名列表、以及是否启用彩色输出等。这个初始化过程设计得比较友好它会用对话方式引导你完成不需要你去翻配置文件。有几个关键参数值得说清楚。第一个是默认时区caveman 会读取系统时区但如果你有跨时区协作或者经常出差建议显式设置避免记录的本地时间与真实时间错位。第二个是项目的默认标签列表你可以提前把常用项目写进去后续记录时会自动补全这个操作类似 shell 的历史补全能减少不少输入量。第三个是报告中的“小时单位”设置caveman 支持十进制小时和 HH:MM 两种显示方式我建议选十进制因为后续做费用核算时直接用数字乘单价就行。初始化完成后数据文件里会有一些基础记录但此时还没有任何时间条目。你不需要再准备其他配置文件——它把配置也写进了同一个日志文件里好处是你搬家或者换电脑时只要带着caveman.log走所有历史记录和配置都在。2.3 核心命令速览caveman 的所有交互都是运行caveman后输入子命令完成的。最常用的几个命令我用一张表列出来方便随时查阅命令作用示例start开始一个新任务记录start codingend结束当前任务恢复自由状态endstatus查看当前正在进行的任务与开始时间statusreport生成时间报告reportstats按项目汇总统计statsread读取旧记录精确到某个时间点read 2024-01-15edit手动修正某条记录edit这里要特别提醒start和end是本工具的灵魂。它的工作机制不是简单地记录“几号几点我做了什么”而是记录一个“状态切换序列”。比如你上午 9 点开始写代码运行start coding那么从 9 点起就处于 coding 状态如果你 11 点被叫去开会运行start meeting它会自动把 9 点到 11 点之间的时间归给 coding。这种设计省去了大量手工输入起止时间的操作也让中间的中断变得透明。3. 核心细节与真实记录机制3.1 数据存储方式与恢复逻辑caveman 的数据文件本质上是一堆人类可读的文本行。每行代表一次状态切换包含四个元素日期、时间、动作开始或结束、项目名。比如下面这样2024-03-12 09:02:30 start coding 2024-03-12 11:05:12 start meeting 2024-03-12 11:48:02 end 2024-03-12 13:30:45 start coding这种格式有一个非常大的好处完全透明。你随时可以用任何文本编辑器打开它看看自己那天到底做了什么。我的习惯是每周末用 Vim 打开caveman.log快速扫一遍这比看任何统计图表都更有真实感因为你能看到那些细微的切换痕迹——比如下午 2 点突然有十分钟的空档那多半是接了通电话。恢复逻辑也很有意思。如果你手动修改了文件caveman 还能通过日期解析把修改后的内容重新纳入统计因此它也兼作文档记录。不需要担心工具升级导致数据不可用因为这个纯文本格式几十年都不会变。比起那些存在云端、数据被锁在私有格式里的商业软件这种朴素反而成了一种长期主义的设计优点。3.2 记录时间与容错补漏真实使用中你不可能做到每次任务切换都准点打卡caveman 对此的处理方式相当宽容。当你运行start时它会询问当前任务是什么时候开始的如果你不太确定可以直接回车它会默认使用当前时间。但更实用的是它允许你输入一个模糊时间比如“10分钟前”或者“下午2点”解析器会尝试理解这些自然语言描述。这就是 caveman 的一个杀手级特性——它不要求你实时记录允许事后补记。中午吃饭回来突然想到上午忘了记录你只需要运行start coding然后输入“上午9点半”作为开始时间前面的空档就会被自动填上。如果再配合edit命令微调你完全可以在一周结束时花十分钟把整周的时间账补完只要你的记忆力还靠得住。不过要注意这种容错也有边界如果两条记录之间的时间有重叠caveman 会按照后一条记录为准进行截断。逻辑上它是线性账本不支持并行任务。也就是说你不可能同时处于 coding 和 meeting 两个状态。如果你确实需要处理“穿插进行”的工作建议拆成更细的片段或者用项目命名去区分例如coding - backend和coding - frontend。3.3 别名机制与配置技巧caveman 除了交互式记录还支持通过命令行直接传参caveman start coding这种写法就能直接开启记录省去进入交互界面的步骤。我是用 shell 别名配合快捷键来提高效率的比如在.bashrc中加入alias cmcaveman alias cmscaveman status alias cmrcaveman report这样在终端里输入cms就能看到当前进行中的任务输入cmr就能生成报告。这套组合用习惯了以后记录过程的心理负担几乎为零。初始化时设置的项目名列表也很关键。我会建议把它看成一个“项目 动作”的复合标签体系不要只写项目名应该加上动词。例如coding - feature-x、meeting - weekly、research - logs。这样后续跑stats时你能直接看出自己在“编码、开会、研究”这些动作上的时间分布。另外项目名的命名尽量保持稳定因为 caveman 是按字符串精确匹配来聚合统计的同一个项目换个写法报告里就会裂成两行。4. 输出报告与钩子集成4.1 四种报告格式对比caveman 的report命令支持生成四种格式纯文本txt、HTML、CSV 和 JSON。其中纯文本格式适合在终端直接查看HTML 适合浏览CSV 适合导入 Excel 或在线表格JSON 则适合写脚本进一步处理。我日常用得最多的是 HTML 报告因为它会按日期排序、按项目着色看起来非常直观而且可以直接在浏览器里打印成 PDF 作为周报附件。CSV 格式我一般用来做月度汇总导入 Excel 后自己再加一列“单价 × 小时数”就能算成本。JSON 格式用得最少一般只在写自动统计脚本时才用。生成报告的命令也很简单在 caveman 交互界面里输入report后选择格式与时间范围。另外它还支持stats命令它会生成一个简单的 ASCII 图表按项目显示占据的时间百分比。这个图表虽然简陋但对快速把握一周的时间分布非常有帮助——比如周一开会占比突然到 60% 以上就该反思是不是会议密度过大。4.2 Git 钩子自动生成日报告如果你是一个 Git 重度使用者caveman 有一个非常巧妙的玩法——把它接入 Git 的钩子。我的做法是在项目仓库里创建.git/hooks/pre-commit文件内容大致如下#!/bin/sh caveman report --formattext --sincetoday time-report.txt git add time-report.txt每次提交代码时它会自动生成一份当日的时间报告并附带进提交。这样做的好处是你提交代码时也同步提交了“这段时间的工作痕迹”代码审查时如果能配合时间报告就能还原出某个功能的实际开发耗时。不过我建议不要把自动生成的报告放到与源码同级的位置而是放到docs/或者reports/目录下避免污染根目录。如果你用git commit --amend或者 rebase 之类的操作注意时间报告的内容是基于“当前时间”的因此补交时可能会把你正在做的其他任务时间也算进去这个坑我在一开始踩过几次后面就只在pre-commit里生成而不再在 hook 里存储历史报告文件减少误提交的干扰。4.3 估算时间与统计视图caveman 的统计视角对“估算”这件事情有独特的帮助。它不仅能告诉你每件事花了多久还能通过read命令回溯某一天的记录看看当时的时间切分。这种“事后复盘”的价值在于你可以逐渐修正自己的任务估算能力。比如我连续记录了六周之后发现自己对“debug 时间”的估算总是偏少实际用时往往是预估的两倍。如果不借助工具这种偏差很难被量化因为大脑倾向于美化记忆。有了记录之后我写项目排期时会自动给调试类任务乘以 1.5 的系数准确率提升了很多。这就是实时记录数据带来的直接收益——它不是用来惩罚你“哪里浪费时间”而是帮你了解自己的真实工作节奏。5. 常见问题与实战心得5.1 高频问题排查速查表我整理了一份使用 caveman 过程中最容易遇到的几个问题以及对应的解决办法供大家按图索骥问题原因解决方式start后忘记end导致时间被记到下一个任务状态没有及时切换运行end后重新start或手动编辑文件修正报告里的时间总和与时钟对不上存在跨天未结束的记录检查read 昨天的末尾状态补上end启动时报时区相关警告系统时区配置异常在 shell 环境变量里显式设置TZHTML 报告中文乱码字符编码未声明在 caveman 源码目录中查看生成模板改成 UTF-8想合并两个相同项目名但大小写不同字符串精确匹配手动编辑日志文件统一项目名大小写report默认只输出最近七天设计如此用read加日期参数或进入交互模式选择区间有一个问题我想单独强调如果日志文件被错误地截断或误删恢复起来非常麻烦。因为 caveman 没有云同步它在本地只有一份数据。我的建议是把caveman.log纳入 Git 仓库或同步盘并在.gitignore之外单独为它建一条备份策略。我自己是把日志文件放在 Dropbox 的同步目录里配合版本历史误删也能找回。5.2 几条长期使用的建议最后说几条我从实际使用中总结出来的经验不是官方文档里的内容但我觉得非常有用。第一条尽量固定每天第一次记录的时间点。你可以把它嵌入晨间例程打开电脑后第一件事就是运行caveman start daily-planning这样无论后面怎么切换当天的起点是明确的。第二条不要追求 100% 的完美记录。你漏记一段很正常与其强迫自己补全每一个空洞不如接受不完美保持“大致准确”即可。caveman 的定位是给你一个可靠的时间镜像不是让你产生更多焦虑。第三条定期运行 report 并留档。我通常是每周一生成上周周报 PDF存到工作档案目录。这样季度总结时无需再翻原始数据直接看周报就能回顾大概。第四条善用 edit 命令修正模糊边界。比如你写着写着代码被拉去处理了 15 分钟服务器问题回来又继续写可以把这 15 分钟单独拆成ops - server-issue条目。这种细节粒度在月度复盘时非常有用能帮你发现那些“隐性运维时间”。caveman 这个工具我已经用了快两年它没有逆天的功能也没有好看的数据可视化面板但它帮我解决了一个最核心的问题——不再凭记忆编造时间账。每次客户问我某个功能实际花了多久我都能从报告里翻出真实数据来回答。这种“心里有底”的感觉是那些花哨的时间管理软件很少能带给你的。如果你也厌倦了到处记账、被各种提醒打扰不妨试试这个穴居人风格的老派工具它可能比你想的更懂“记录”这件事。