caveman最近在圈子里被玩成了一个很有意思的梗——有人拿它代表“原始人调试法”能print就不上断点有人把它类比成回归极简的生活方式还有人干脆用它形容那种“啥功能都不要能跑就行”的工具哲学。我去年折腾了一个叫 caveman 的小项目恰好就是这种精神的产物一台老旧的笔记本、一堆越来越臃肿的笔记工具逼着我写了一个在命令行下跑得飞快、零依赖、纯文本的本地记录与任务管理工具。这篇文章就聊聊我为什么做它、怎么选型、踩了哪些坑以及用了一个月之后还算诚实的评价。1. 一台老笔记本逼我重新理解“够用”这个词1.1 崩溃现场打开一个笔记软件要等三秒事情的起因特别朴素。我有一台用了六七年的笔记本8G内存平时写代码、开浏览器、跑虚拟机就已经很吃力了。某天我像往常一样准备打开某款主流的笔记软件记一条新想法然后眼睁睁看着它转了三四秒的圈才弹出界面输入中文还有肉眼可见的延迟。那一刻我忽然意识到一个荒诞的事实我只是想记一条“明天记得带充电器”的话却要为一个几百兆的Electron程序付出几秒的等待和几百兆的内存。更让我烦躁的是这些工具的功能越来越多我实际用到的却越来越少。什么双链、白板、协作、模板、插件市场我一个都没碰过。我每天在笔记里做的事情翻来覆去就三件快速记一条想法、写一段稍长的草稿、事后把它找出来。而我为这三件事所付出的代价却是启动速度、内存占用、格式锁定和同步冲突。于是那个周末我决定自己写一个工具。要求很简单启动速度必须肉眼无感知内存占用必须忽略不计数据必须是我能随时用vim打开看懂的东西。它不需要界面不需要图标不需要安装包。它只需要像一个穴居人那样原始、直接、不加修饰地完成“记录”和“查找”这两件事。1.2 caveman的设计原则无依赖、纯文本、秒开我给这个项目取名叫 caveman就是“穴居人”的意思。名字听起来像开玩笑但背后其实是三条非常认真的设计原则。第一条零依赖。我希望这个工具在任何一台机器上都能跑起来不需要装Node、不需要装Python、不需要拉一堆node_modules。最后我选择了用Rust写静态编译单个二进制文件扔到任何Linux或者macOS机器上都能直接用。Windows我也顺带编译了一份后面会讲到在Windows上踩的坑。第二条纯文本存储。所有数据都是普通的markdown文件按目录分类文件名就是标题文件内容就是正文。我想看数据的时候不需要启动任何程序直接用ls和cat就能读。想备份的时候一个tar命令打包走人。想迁移到别的工具把目录复制过去就行。数据属于我不属于某个私有格式。第三条秒开。所有命令的启动时间从敲下回车到看到输出必须小于50毫秒。这个目标在Rust下其实很容易达到因为二进制本身就小不需要初始化任何运行时。在我的老笔记本上实测下来cave相关的所有子命令都在10毫秒左右几乎感觉不到“等待”这件事。1.3 它解决什么问题适合什么人所以caveman到底解决什么问题说穿了就一句话给那些不需要复杂协作、不需要多媒体富交互、只想要一个可靠地方存文字的人一个零负担的替代方案。它适合这几类人受够了Electron笔记软件卡顿的命令行爱好者需要随手记录灵感、日志、TODO但不想被某个商业软件绑定的人有git使用习惯希望所有数据都能版本化的人以及跟我一样机器配置不太行、但想保持高效记录习惯的人。它不适合谁不适合需要团队共享笔记的人不适合需要大量插入图片、表格、附件的人不适合希望用手机随时打开看的人。这些先天短板我后面会详细说但我自己不介意因为我的需求就是“记下来找得到”而不是“随时随地、图文并茂”。2. 存储方案定了三次SQLite、JSON、最后回到纯文本2.1 第一版SQLite虽然好用但“备份”总是很沉重caveman最早的存储方案其实是最常规的做法SQLite。一张notes表字段是id、title、content、tags、created_at用一个单文件数据库搞定所有查询。这个方案非常成熟索引快、查询灵活、并发安全写起来也省事。我花了一个晚上就把增删改查写完了当天就用它记了十来条笔记。但很快问题就来了SQLite文件对我而言是个黑盒。我无法用编辑器直接看我写了什么无法用grep在笔记里做上下文搜索无法让其他脚本方便地处理这些内容。最要命的是备份数据库文件在写入过程中如果被中断可能整个文件损坏。我这个人有强迫症每次想备份都要去跑一次sqlite3 .backup时间一长就不想坚持了。有一天我忽然想通了一件事对我来说笔记的本质是“一堆能被人读的文本”。如果它沦落成了“必须依赖某个程序才能解读的字节序列”那这个笔记就失去了它最宝贵的属性——可读性。于是我把SQLite方案推翻开始第二版。2.2 第二版JSON文件崩溃后才知道它有多脆第二版我用了一个很“现代”的方案所有笔记存在一个notes.json文件里数据结构是一个数组每条笔记是一个对象。这样既保留了结构化查询的方便又能用任何文本编辑器查看内容。事实证明小规模用没问题一旦写多了JSON方案的脆弱性全暴露了。首先是手滑问题一个不小心少写一个逗号整个文件解析失败所有笔记全部打不开。有一次我甚至只是用文本编辑器打开文件想改一处文字自动保存时把文件截断了结果整个JSON文件损坏我花了二十分钟从备份里恢复数据。其次是并发问题两个终端各打开一个窗口同时往里写内容就会发生“最后一写覆盖前一个写”的情况。你说谁会同时开两个终端记笔记听起来很荒谬但等你在电脑前时一边开着终端A查资料一边用终端B记笔记AI工具又在自动追加日志这种并发写入的场景其实很常见。那几天我一边恢复数据一边反复问自己我的需求明明那么简单为什么要付出“文件损坏”这个代价于是我把JSON方案也扔了。2.3 最终版目录即数据库文件名即索引第三版也就是最终版我彻底放弃了“把所有数据装进一个文件”的思路改用最原始的方案每个笔记一个markdown文件目录结构即分类结构文件名即标题创建时间戳写在文件头部正文随写随存。具体结构长这样cave/ ├── inbox/ # 快速记录区 │ ├── 20250115_0930_买充电器.md │ └── 20250115_1420_关于caveman的后续想法.md ├── projects/ │ ├── caveman/ │ │ ├── 20250110_设计原则.md │ │ └── 20250112_存储方案.md │ └── blog/ └── archive/ # 归档区这个方案根本不存在“解析失败”的问题因为每个文件都是独立的一个文件损坏不影响其他文件。备份就是复制目录迁移就是scp整个文件夹。搜索直接用grep或者内置的hunt命令排序就靠文件名里的时间戳前缀想给笔记加标签就在正文头部写一行tags:然后脚本自己解析前几行就行。它带来的最大好处是我的笔记库任何时间、任何工具、任何环境都可以直接被读取。哪怕Rust的整个程序崩溃了我依然能打开这个目录把每篇笔记读出来。这种“安全感”比任何花哨的同步机制都实在。2.4 为什么我坚决不搞插件系统在设计caveman的时候有一个声音一直在诱惑我搞一个插件系统吧这样别人就能为它开发各种扩展了比如图片管理、日历视图、富文本渲染之类。我挣扎了很久最后还是决定不做。理由很现实。第一插件系统意味着要定义一个SDK、插件生命周期、权限管理、兼容性约定这些工作量的投入比核心功能本身还要大。第二插件系统意味着这个项目从“我自己的工具”变成了“一个平台”需要维护社区、处理各种需求这是我一个业余项目扛不动的。第三最重要的是插件的存在会让核心工具变得复杂而caveman的核心价值就是“简单到没有退化空间”。我把简单当作功能而不是缺陷。如果有人需要图片我会建议他把图片放在cave目录下的assets/文件夹里在markdown里引用相对路径这比任何插件都更稳定。3. 六个核心命令把“原始人”的日常操作做顺手caveman没有繁复的菜单和工具栏所有交互都靠几个短命令来完成。从设计之初我就刻意让命令词汇尽量“原始”——不要什么create、insert、retrieve而是用cave、stick、hunt这种本能感很强的词。用起来也很顺手。3.1 cave init 与 cave add建立和进入你的洞穴一切都是从一个“洞穴”开始的。cave init会在当前目录下初始化一个cave仓库生成标准的目录结构inbox/、projects/、archive/还有一个名为.cave的配置目录。初次使用大概只需要三秒钟。cave init my-notes cd my-notes cave add projects/blogcave add用来新增分类目录比如我建了projects/blog、projects/caveman、life/trips它会自动创建目录并保证cave的元数据文件同步更新。这个命令说穿了就是mkdir -p加一点校验但我特意把它放在cave里是为了让“添加一个分类”这件事成为所有用户共同的操作语言而不是各想各的。3.2 stick三秒内完成一次快速记录stick是caveman里最高频的命令也是整个项目存在的最核心理由。它做的事情十分简单在inbox/目录下新建一个markdown文件文件名以当前时间戳开头然后打开编辑器让你输入内容。如果你不想打开编辑器也可以直接传参# 直接记录一句话适合灵感一闪而过的时候 cave stick 明天上午十点找老王确认接口文档 # 或者带标签 cave stick Rust的Result类型是真的难写 --tag code,rust # 不传内容时会打开 $EDITOR 环境变量指定的编辑器 cave stickstick这个动词很贴合它的动作像原始人把一根树枝插在地上做标记几分钟后回来就知道自己在这里想记过什么。它不试图帮你整理思路不主动弹提醒不打标签不做一切多余的事。它只是“把话留存下来”。我用它最多的时候是写代码写到一半冒出别的念头——比如突然想起“该缴电费了”或者冒出一个跟当前任务无关的灵感。以前我可能会掏出手机记一下现在就是ctrlc切到终端敲一句cave stick三秒完事继续写代码。3.3 hunt在没有索引的原始森林里找东西找笔记靠的是hunt。它的实现就是一个多线程的grep遍历cave目录下所有md文件匹配关键词输出文件路径和匹配行的上下文。因为数据都是纯文本hunt的搜索速度和文件数量成正比在我的测试目录里8000多个md文件全量搜索一个词耗时大概120毫秒。# 基本搜搜 cave hunt Result # 只看某个分类下 cave hunt Result --path projects # 按时间过滤只搜最近30天写的 cave hunt Result --since 30d # 输出json方便配合其他工具 cave hunt Result --format jsonhunt没有引入SQLite全文索引也没有用tantivy之类的搜索引擎理由是在绝大多数场景下纯文本grep已经足够快而引入索引会带来“索引文件损坏”“索引与数据不同步”等一系列新问题。我想要的不是“毫秒级全库搜索”这种惊艳效果而是“在任何情况下都能搜到我要的东西”这种稳妥的确定性。想要更快的语义搜索我会选择把它开放成外部命令后面再说。3.4 totem拿一根棍子把任务串起来totem负责任务管理但它的理念跟主流任务软件不太一样。它不管什么优先级、截止日期、提醒、依赖关系它就是让你给任务“选一个日子插一根棍子”。# 把inbox里某条笔记转成任务 cave totem add 20250115_0930_买充电器.md --due today # 把今天该做的任务列出来 cave totem --today # 把任务标记完成 cave totem done 20250115_0930_买充电器.md它的实现也极其原始在cave的.cave/totem/目录下建立任务文件文件名就是关联的笔记文件名内容里写status: open/done和due: 2025-01-15。没有独立的数据库没有复杂的状态机。查询“今天该做什么”就是遍历.cave/totem/下所有状态为open且due日期等于今天的文件。这套简化到极致的任务系统反而治好了我以前在任务管理软件里反复折腾“方法论”的毛病。因为没有地方给你配置“艾森豪威尔矩阵”或者“番茄钟”你就只剩下一件事把任务定到哪一天然后做掉它。3.5 crunch用数字审视自己的记录轨迹crunch是个统计命令没有它caveman也能用但我个人非常依赖它。它能统计你每天、每周、每个月写了多少条记录最常搜索的关键词排行以及各个分类下的笔记数量分布。cave crunch --weekly cave crunch --keywords --top 20 cave crunch --by-category我之所以说它重要是因为人对自己习惯的感知往往是模糊的。我以为自己这一周很努力地记录了结果crunch --weekly告诉我这周只写了3条而上周五天写了17条。数字不会骗人看到下降趋势第二天我就会下意识地多动手记几笔。一个好的工具不只是被动存储它还应该像一个诚实的小助手偶尔把你最近的状态摆到你面前。3.6 clean给洞穴做定期大扫除最后是clean它处理的是所有工具都会遇见的“陈旧内容堆积”问题。inbox里的笔记会越来越多projects下的旧文档会越来越乱。clean这个命令做的事情是把30天前、状态为open的任务自动改为“已过期”并压缩到archive把inbox里超过60天没有改动过的记录压缩到archive目录要求你在归档前随手删掉不再需要的文件这里没有什么内容过期算法它就是靠“改很少量的规则保证长期稳定”。我特意没有做“自动删除”功能因为删除是一件需要人亲自确认的事。clean只负责帮你收拢和归类不负责替你决定什么东西可以丢掉。4. 踩坑实录索引扫描、中文路径、并发冲突与那个emoji4.1 递归扫描目录为什么会扫出性能问题caveman早期版本里hunt的实现是直接用标准库的fs::read_dir递归遍历整个cave目录然后对每个文件做正则匹配。在小目录里跑没任何毛病但当我把写了半年的所有笔记全部导入之后问题立刻暴露目录大小超过两万个文件一次搜索耗时居然接近两秒。排查过程很有意思。我先以为是正则编译太慢换成grep -r做对比发现原生grep只要200毫秒。然后我怀疑是读取文件内容造成IO瓶颈于是加了一个快速过滤只读超过8KB大小的文件仍然没有改观。最后用perf一看发现瓶颈其实在系统调用大量小文件的读取上。每读一个文件都要两次open、read、close两万个小文件就意味着六万多次系统调用光是上下文切换的开销就占了大头。解决方式很原始顺序预读 mmap。对所有小文件用mmap映射避免反复open/close并且把读取文件的线程数固定为4内核数1。优化之后同样两万个文件的搜索耗时从1900毫秒降到了320毫秒。4.2 中文文件名差点毁了我的排序逻辑这个坑说起来有点好笑。cave的文件名格式是YYYYMMDD_HHMM_标题.md时间戳在前标题在后。我最初实现的“按时间排序”逻辑是直接对文件名做字典序排序——因为时间戳按零填充的YYYYMMDD格式排列字典序恰好等于时间顺序。一切都很完美直到有一次我贴了一个中文标题进去。中文文件的字典序跟英文完全不同文件名里混杂了UTF-8的汉字之后排序结果就开始错乱。更离谱的是同一个标题在不同系统下的字节序可能不同导致排序结果在Linux和macOS上不一致。我查了半天才发现问题不在排序算法而在文件名编码。有人可能觉得文件名只要保存了UTF-8就没问题但在某些macOS文件系统里文件名会以NFD形式存储和Linux上的NFC形式字节完全不同。而我当时没有做统一的标准化。修复方案是在写入文件时文件名里只保留时间戳标题全部写在文件正文的第一行文件名只留下一个短哈希。这样排序完全依赖时间戳不再被标题内容干扰。4.3 两个终端同时写同一个文件都会发生什么我以为自己永远不会遇到并发写直到某天我用cave stick ...记录一句话同时一个长时间运行的构建脚本也往cave的同一个分类目录里追加了一条日志。虽然这种情况很少但一旦发生后果就是文件内容被互相覆盖其中一条记录彻底丢失。让我意外的是这种问题在纯文本方案下反而更好解决。因为每个笔记都是独立文件你可以直接用文件锁或者原子替换解决冲突。我的处理方式是写入新笔记时先写到一个临时文件再通过rename原子替换目标文件。读取时如果发现目标文件不存在就直接以“跳过”处理。这样并发写入顶多丢失最后写入的那一条不会损坏整个记录库。这套策略在SQLite版和JSON版里我都做不到这么干净。纯文本的每个文件、每个目录都是独立的冲突域出了问题影响范围也被限制在单个文件内这是我选择这个方案后最深的体会。4.4 从“原始人调试法”里捡回一条命最后说一个调试层面的心得。caveman早期有个特别诡异的问题在某些机器上cave hunt能搜到内容在另一些机器上却一条都搜不到。我一开始怀疑是环境差异加了一堆日志打印编码、路径、IO错误逐个排查都没定位到根因。后来我愤怒之下直接用了最原始的办法在hunt的内部循环里每处理一个文件就往stderr打印一行file... matchesN。这个调试方法在圈子里被称为“caveman debugging”——不打断点、不看堆栈就是用大量输出把执行过程赤裸裸地暴露出来。结果跑了几百行日志之后我立刻发现搜不到结果的机器上路径末尾多了一个看不见的\r字符。问题出在配置文件上Windows下编辑过的配置文件默认带CRLF行尾我在解析配置时没有处理\r导致所有路径都被污染。修复也就一行trim_end_matches(\r)。这件事给我最大的教训不是“解析配置要处理换行符”而是当问题百思不解时不要迷信高级调试工具先把自己拉到原始人的视角用最粗糙但完整的信息流去看问题。5. 真正让它好用起来的是几个不起眼的外挂caveman本身的功能很克制但搭配上几个外部小工具之后使用体验会有一个质的飞跃。这些外挂不是我硬塞进去的功能而是每个命令行用户都在用的成熟工具。5.1 终端别名把命令压成一两个字母再短的命令每天敲十遍也会烦。我在.zshrc里为最高频的操作用别名和函数做了一层包装alias ckcave stick alias ckhcave hunt alias cktcave totem --today alias ckkcave crunch --weekly于是记一条笔记只需要敲ck加内容查找一条笔记只需要ckh 关键词。别小看这个优化当“记录”动作的操作成本降到两秒以内你记录的频率会明显提高。工具的使用频率跟它的启动成本呈反比这在任何软件上都成立。5.2 git私有仓库三行脚本搞定多设备同步cave是纯文本目录结构这意味着它天然就是一个git仓库。我建了一个私有仓库专门放cave目录然后在cron里配置每五分钟自动提交和推送*/5 * * * * cd ~/cave git add -A git commit -m auto sync --quiet git push --quiet git pull --quiet有了git作为同步层相当于白嫖了版本历史、增量备份和跨设备同步三份功能。我可以随时随地在一台新机器上git clone一下整套笔记立刻可用。这也是纯文本存储方案最爽的地方——任何通用工具都能直接成为它的配套设施。5.3 编辑器快捷键与手机端补充日常写代码时我经常需要快速查一条旧笔记。我把cave hunt绑定到了编辑器的一个快捷键上按下后弹出一个quickfix窗口显示搜索结果回车直接跳转到对应笔记文件。这样“查旧笔记”的成本又降了一截几乎等同于编辑器内置的grep。手机端的场景我也有个偏方用一个Terminal APP连到家里的Linux机器上通过ssh直接操作cave。虽然手机界面比不上原生App美观但对于“突然想起一件事想记一记”这种轻量操作打开Terminal敲cave stick ...完全够用。同步就依靠git自动推送拉取。6. 用了一个月说说它哪里爽哪里疼6.1 爽的地方专注、可控、零启动成本这一个月用下来最爽的感受是三个词专注、可控、零启动成本。专注体现在使用过程中。caveman没有任何弹窗、红点、通知、待办提醒你打开它就是一片空白的光标只能写字。过去用图形笔记软件时我常常在“美化排版”“调整样式”上耗掉半小时现在已经彻底没有这种选项了反而回到最原始的写作状态。可控体现在安全感上。任何时候我都可以用find、grep、tar直接操作整个笔记库不用担心某个商业软件的数据库崩溃或者服务下线。我把cave目录备份到了两块硬盘上恢复方式就是解压复制没有任何学习成本。零启动成本是最直观的。cave stick在终端里是秒开我甚至不需要等待进程启动思绪几乎不会被打断。这个体验对码农来说太重要了——很多灵感真的只有十几秒的存活窗口慢一拍就没了。6.2 疼的地方图片、附件、语义搜索全都缺席诚实地说caveman也有不少时候让我不太舒服。最明显的痛点是图片无法内嵌查看。写技术笔记时我经常需要截图贴进文档现在只能先存到assets/目录然后写相对链接想看图必须在终端里拿图像预览插件或者另开工具体验远不如图形笔记软件。第二个痛点是没有语义搜索。hunt是基于关键词的当我想找“上周跟老王聊过的那个关于性能优化的话题”时如果当时没记下“性能”这个关键词搜索就会扑空。第三个痛点是手机端体验太弱虽然有ssh方案兜底但在没网络时就等于完全没法访问笔记。这些痛点我都清楚也想过要不要在caveman里加图片插件、嵌入式数据库、全文索引但每次想到“加一个功能就多一层复杂度”这个原则我就又冷静下来了。6.3 我给它规划的下一步短期内我不会大改caveman但我有三个明确的扩展方向。第一给hunt加一个外部的语义搜索接口。caveman保持纯文本输出然后把内容交给一个可选的embedding服务做向量检索这样既保留零依赖核心也能享受现代搜索技术的红利。第二增加一个“导出到目录结构”的命令把纯文本笔记一键转换成HTML或者PDF解决“发给别人看”的问题。第三考虑支持一个简单的附件管理命令把图片等二进制文件纳入cave的版本控制体系但依旧不内置预览预览交给系统默认工具。写到这里回到“caveman”这个词本身。原始人不是不会用火、不会用工具而是用最少、最可靠的方式活下来。我现在也觉得一个工具的好坏不在于它功能多强大而在于它在你想记东西的那一秒钟能不能毫无负担地接住你。最后分享一个小技巧如果你也打算自己折腾一个类似的工具第一版别急着上框架、上数据库、上插件系统先用最蠢的纯文本方案跑一个月。一个月之后你会发现能留下来的永远是你真正需要的那几个操作。