“caveman”这个小工具让我把笔记从各种App里解放了出来说句实话这两年记录和整理信息变得越来越累。手机里装着三四个笔记应用桌面端还有一堆“All in One”的知识库表面上功能一个比一个多实际上我想要的只是“打开一个文件写几个字以后能找到”。后来我自己做了个命令行小工具代号就叫 “caveman”名字的意思是“原始人”核心思路也很原始——所有笔记、任务、摘录都退回成纯文本保存在一个普通目录里用 Git 管理版本用终端来操作。它不依赖数据库不需要复杂的后台服务更不用把数据交给任何第三方平台。写完后我自己用了差不多一年发现这个看起来“倒退”的方案反而解决了我最大的几个痛点笔记分散、格式锁定、越用越慢。这篇文章就把“caveman”的设计思路、实操流程和踩坑过程完整拆一遍。如果你也厌倦了笨重的笔记软件或者只是想要一个完全拥有数据的个人记录方案可以照着下面的思路自己搭一个。即便你不打算写代码里面的目录组织、检索逻辑、备份策略也值得迁移到你现有的笔记流程里。1. 项目背景与思路拆解1.1 为什么叫“caveman”——返璞归真的设计哲学“原始人”这个名字不是随便起的。我们总觉得工具越智能越好结果多数笔记工具把简单的事情搞复杂了要建数据库要设计表结构要同步要搞双链要渲染卡片……而真正用得上的核心功能还是“写下来、找得到、改得动、带得走”。caveman 的立场是反着来的所有内容就是普通文本。它不需要启动一个服务没有“打开数据库”的概念也没有特殊的私有格式。你甚至关掉我写的这个命令行工具直接用系统自带编辑器打开那个文件夹就能看完全部内容。这种“往退一步”的设计反而最抗时间——从 2020 年到未来十年Markdown 和纯文本几乎不可能被淘汰而某个商业软件的专有格式三五年后大概率就没人维护了。我把它做成一个只有一层薄壳的工具它负责帮你新建、查找、归档文件但从来不试图“拥有”数据。用文件夹组织笔记用文本格式记录内容用 Git 做时间机器用你习惯的编辑器做入口。这些基础能力已经足够稳定稳定到我可以安心把记录交进去。1.2 它到底解决了什么问题在设计之初我给自己总结了三个痛点caveman 就是围绕这三个痛点展开的笔记散落在不同 App 里想找一个东西得先在脑子里判断它记在哪个软件里再逐个打开搜索。平台格式不互通从 A 应用导出来的内容B 应用大概率看不懂等于变相绑架。内容变多以后很多软件会变卡、索引出错、同步冲突而且排错无从下手。caveman 的解法很直接把所有内容收敛到一个目录里目录下按“年份/月份”建子文件夹每个笔记是一个独立的.md文件。查找时直接用全文搜索工具扫目录不需要任何索引数据库。数据天然就是一大堆标准文件你可以用 Git 做任意粒度的版本回滚也可以随时用任意脚本批量处理它们。因为格式统一内容永远不会被某个特定客户端锁死。如果你像我一样有本地写作、技术笔记、读书摘录、日常待办这些长期积累的需求这套方案几乎一劳永逸。它不需要你改变太多习惯只需要接受一件事你的笔记不是什么“云端资产”只是一些普通到不能再普通的文件。1.3 功能全景与边界caveman 的定位是“个人知识库的指挥层”。现在它提供这些核心动作动作作用典型的命令行示例记录新建一条带标题和正文的笔记caveman add -t 会议纪要 -b 待办...查看列出最近或指定日期范围内的笔记caveman list --from 2025-01-01检索按关键词搜正文、标题和标签caveman search 微服务编辑用默认编辑器打开指定文件caveman open meeting_0115.md归档把不再活跃的内容移入归档目录caveman archive --before 2024-12-31同步依赖 Git 完成提交和推送caveman sync -m 日常更新需要强调一下它不适合做什么。我不做富文本渲染不做多人实时协作不做移动端原生应用不做桌面悬浮快捷输入。这些能力不是不好而是它们会显著增加复杂度和锁粒度。caveman 的边界恰好是它的优势它只负责文件管理和路径约定剩下的交给生态。2. 工具选型与架构设计2.1 技术栈为什么用单二进制第一版我用纯 shell 脚本写的简单场景跑得很欢但到了几百个文件后参数解析和跨平台处理开始变得难受。后来我用 Go 重写了一遍编译成一个不依赖任何运行时的可执行文件。选 Go 而不是 Python 或者 Node主要是我希望安装过程足够原始下载一个文件放到 PATH 里完事。没有虚拟环境没有 node_modules没有版本地狱。这一点对终端工具很重要因为很多同事想用但卡在环境搭建上。Go 编译出来是静态二进制丢到 Linux / macOS 服务器上都能跑打包大小也在可接受范围内。内部实现其实也很朴素。核心逻辑就是读取一个配置文件确认笔记根目录然后执行对应子命令。文件操作全部走标准库的os和path/filepath搜索时我直接调用系统里已有的 ripgreprg而不是自己写一套索引。这种“跳出去用别人更专业的工具”的思路减少了大量维护成本。你完全可以用任何熟悉的语言重新实现一遍只要最终行为一致就行。2.2 数据组织用文件夹解决分类问题caveman 的默认结构长这样~/caveman/ ├── content/ │ ├── notes/ │ │ ├── 2025/ │ │ │ ├── 01/ │ │ │ │ ├── 2025-01-15-caveman-first.md │ │ │ │ └── 2025-01-16-reading.md │ │ │ └── 02/ │ │ │ └── 2025-02-01-project-plan.md │ │ └── 2024/ │ └── inbox/ ├── assets/ └── README.md每篇笔记头部带一段 YAML front matter记录标题、标签、创建日期方便脚本读取--- title: caveman 基本使用 tags: [tool, shell, my-workflow] created: 2025-01-15 --- 今天把 caveman 的重写提上日程核心是稳定命令交互和文件命中率。年份/月份作为目录层级是一个约定而不是强制规则。这样做的理由是绝大多数人记录内容时天然带时间属性按日期分目录可以在不做数据库索引的情况下快速定位历史内容。你甚至可以不用 caveman 工具本身直接用文件管理器按目录一层层翻体验跟看归档日志一样自然。思考要不要建“标签体系”时我一律顺手生成一个tags目录索引每个标签一个文件里面放笔记链接。但很快发现这个索引需要维护于是干脆不预生成只在搜索时用 ripgrep 匹配 front matter 里的tags字段。想要按标签过滤就搜tags: [标签名]同样快而且永远不会出现索引没更新导致漏掉内容的问题。2.3 为什么不用数据库很多人听到我不建数据库都觉得不可思议但真正用下来你会发现个人笔记的规模通常不会超过几万条全文搜索用rg扫描一次通常几百毫秒完全不需要维护一个倒排索引。数据库能带来的收益被感知不到反而引入一堆问题数据库文件损坏后怎么修数据格式私有如何导出换电脑时要不要先做个备份跨版本升级是否兼容文本文件最容易被所有工具认识也最容易被任何脚本处理。我用rg搜索用fzf做交互式选择用git diff查看每次改动用rsync做一般性备份——这些工具全部直接作用于文件系统。没有任何一层抽象挡在中间遇到问题也容易排查不会出现“客户端打不开但数据明明还在”的诡异状态。当然如果你有很强的结构化信息比如几百条带 ricing 金额的账目或者需要聚合统计的日志那么上数据库是正确的。caveman 只面向文档型内容这一点在项目开头要非常明确否则会有人拿它管理几千条客户记录那不是它该干的事。2.4 同步方案Git 作为底层既然是文件版本管理最可靠的选择还是 Git。从一开始我就要求caveman sync这个动作等价于三件事git pull --rebase git add -A git commit -m $(date %Y-%m-%d %H:%M:%S) 更新 git push这套流程能跑通的原因很简单笔记是文本改名、移动、删除在 Git 下都能清晰追踪。如果某天误删了一段文字直接git revert或者回滚到上一个 commit 就能找回来。如果两台电脑同时写了同一个文件Git 会留下冲突标记我用编辑器统一处理一次即可。为什么不使用其他同步盘同步这几个文件夹因为 Git 能保留每次提交的差异记录而普通的云同步盘只是帮你把最新文件同步过去无法回溯某个中间状态。对于写作和笔记场景“追溯当时写的版本”几乎和“当前内容”一样重要。所以我把同步交给 Git而不是交给某个云盘。你可以捎带用云盘做第三重备份但主版本历史必须由 Git 承担。3. 实操过程与核心环节实现3.1 从零初始化一个 caveman 仓库第一步找一个干净目录比如~/caveman初始化仓库并创建工作区mkdir -p ~/caveman/content/notes cd ~/caveman git init git config user.name 你的名字 git config user.email youexample.com然后把配置写入~/.config/caveman/config.tomlroot ~/caveman/content editor vim default_tags [inbox] default_author your_name如果不想用我提供的二进制也可以直接用别名模拟核心操作alias caveman-addmkdir -p ~/caveman/content/notes/$(date %Y/%m) vim ~/caveman/content/notes/$(date %Y/%m)/$(date %Y-%m-%d)-new.md但完整工具的好处是它也会帮你维护索引以及生成带日期的唯一文件名。初始化后可以先跑一次caveman add -b 首次测试然后运行caveman list确认文件已经落在正确目录里。3.2 最常用的 5 个命令以我自己每天的使用场景为例这几条命令占了九成快速记录闪念caveman add -t 闪现 -b 想起一个选题如何用文本整理输入输出。命令内部把正文写入~/caveman/content/inbox/2025-02-10.md加上了当天的时间戳属于一个稍后整理的区域。打开昨天写的会议纪要caveman open --date yesterday meeting。它先找出昨天所有匹配“meeting”的文件再把命中的文件交给$EDITOR。如果只匹配到一个文件就省掉交互选择。列出最近一周的内容caveman list --from 2025-02-01 --to 2025-02-08。输出格式简单不带花哨表格只显示文件名、行数和首行标题方便配合管道做进一步统计。全局搜索关键词caveman search 心跳机制。内部实现是rg -i --glob *.md 心跳机制 ~/caveman/content/默认忽略大小写输出带行号可以直接用-n定位到段落位置。归档旧内容caveman archive --before 2024-12-31。它把所有创建时间更早的 Markdown 文件移动到content/archive/目录搜索时默认跳过这个目录降低频繁扫描范围。这里每个动作都足够朴素没有抽象到“我的思维导图”“知识图谱”这种层面。我越来越觉得个人记录工具最该做好的是减少摩擦想记的时候一秒钟能写下想找的时候三秒钟能找到。3.3 把 caveman 与终端工作流串起来caveman 不是孤岛它最大的价值来自与终端生态的组合拳。我在~/.zshrc里加了几个配置大大提高了操作速度export CAVEMAN_ROOT$HOME/caveman/content # 常用快捷键 bindkey ^n caveman-widget caveman-widget() { local result result$(caveman list --all --pipe | fzf --preview head -40 {}) if [[ -n $result ]]; then $EDITOR $result fi zle reset-prompt }以上配置完成后按CtrlN会呼出一个列表用fzf过滤并预览文件内容选中后直接进入编辑器。这个交互速度比任何图形笔记软件的“快速切换”都要顺手因为它发生在键盘流里不需要鼠标不需要跨窗口转移注意力。搜索时我也会频繁配合rg和管道。比如统计某位作者相关笔记出现次数rg -l 作者名 ~/caveman/content/notes/ | wc -l或者连同文件名一起输出便于跳转caveman search 微服务 | cut -d: -f1 | sort -u如果你有 Vim 使用习惯还可以给caveman文件加一键标题补全和文件头模板。我用 Vim 写笔记时autocmd BufNewFile *.md会自动加上 front matter 和时间标签。这样我既能享受终端的速度又能保证文件规范一致。3.4 自动提交与多设备同步手动每天敲一两次sync相当烦我在 cron 里加了条语句每 30 分钟自动提交一次*/30 * * * * cd ~/caveman caveman sync -m 自动更新 /tmp/caveman-sync.log 21这里要提示一句加了git pull --rebase后如果另一台设备上有更早的提交并且与你本地产生分叉自动流程可能会卡在合并。我的解决方式是给caveman sync加一个--auto模式一旦发现 rebase 后产生冲突就停止操作而不是盲目合并等手动介入。毕竟个人场景下冲突概率极低但一旦发生必须人工判断。多设备同步的基础是在~/caveman里把远程仓库加好git remote add origin gitgithub.com:you/caveman-notes.git每台设备上执行同样的初始化并从远程拉取。理论上换一台新电脑只要重新安装 caveman然后git clone那一份笔记仓库再装好编辑器就恢复了整个知识库。整个恢复过程不超过十分钟。3.5 数据安全与备份策略虽然 Git 已经是很强的备份我仍然坚持每周用rsync把整个caveman目录额外拷贝一份到独立移动硬盘rsync -av --delete ~/caveman/ /Volumes/Backup/caveman/针对特别敏感的内容比如密码指引、密钥片段我从不直接以明文写在笔记里。caveman 提供了一个caveman vault命令本质是唤醒系统里的 gpg 对指定文件加密。使用时加密成.gpg文件需要时再解密阅读。如果你觉得麻烦也可以把敏感内容扔到单独目录再对整个目录做加密。加密策略可以后置但“纯文本完整历史多端备份”这三个底座必须一上来就搭好。4. 常见问题与排查技巧实录4.1 命令明明存在却报 command not found安装后第一反应是caveman --help结果提示找不到命令。这时候先确认二进制有没有下载到本地并检查是否有执行权限ls -l /usr/local/bin/caveman chmod x /usr/local/bin/caveman如果确实装好了但还是找不到再看PATH里有没有包含/usr/local/bin。macOS 上通常是有的但某些 Linux 发行版把用户安装路径放在~/go/bin或~/.local/bin需要手动加。如果不想改 PATH就在~/.bashrc里加一行别名反正工具只是入口别忘了原始目录才是数据本体。另外一个容易忽视的点是 shell 缓存了命令路径。新安装的二进制可能被 shell 的hash table记住了旧位置执行hash -r清一下缓存问题通常就解决。4.2 搜索中文或者带特殊字符的内容没有结果因为底层调用 ripgrep默认情况下它的行为跟 grep 一致比较讲究字符编码。正常 UTF-8 文本没问题最常遇到的是文件保存成了带 BOM 的 UTF-8或者从旧系统拷过来的 GBK 编码文件。排查步骤很简单file one-notes.md如果是非 UTF-8 编码可以用 iconv 转一下再存回iconv -f GBK -t UTF-8 one-notes.md one-notes-utf8.md mv one-notes-utf8.md one-notes.md另外搜索时想忽略大小写建议习惯性加--ignore-case想搜索包含空格或者括号的特殊内容最好给关键词加引号。4.3 Git 同步冲突怎么处理冲突出现时的文件里会有类似 HEAD和的标记。处理步骤是先用caveman search定位冲突文件再用编辑器打开逐个比较两个版本谁保留、谁合并。一般我不会机械地选某一个版本因为笔记不是代码两个版本往往记录了不同侧面需要人工合成。我的推荐流程# 1. 标记冲突状态中保留的文件你手动编辑过 git add content/notes/... # 2. 完成后一次性提交 git commit -m 手工合并冲突如果设备上残留下很多冲突文件又不想逐一处理可以用 reset 回到刚才的分叉点放弃本机这条支线的更新git checkout -- . git rebase --abort再执行一次git pull拿到另一端全部内容。个人使用偶尔一次全量放弃比花半小时纠结哪个段落重要要高效得多。4.4 笔记变多以后caveman 变慢了怎么办纯文本方案的瓶颈不在搜索而是在大量文件上执行list或者统计时进程启动和管道生成会有感知特别是在 Windows 或者网络目录下。我给常见性能下降场景给出几条应对策略把content/inbox/每天清空移动旧内容到归档目录保持活跃目录内文件在 1000 个以内。搜索时用caveman search --exclude-archive默认动作避免扫描归档文件。大附件图片、PDF不要直接放在笔记目录里。我真的踩过坑往笔记目录里塞了几个很大的截图导致本机全盘搜索都变慢。现在图片统一放到assets/搜索路径限定在content/notes/不再扫描assets/。如果目录跨过了上万文件考虑按项目拆分成多个独立仓库比如~/caveman/work/和~/caveman/notes/各自维护 git 历史避免一锅乱炖。遇到慢时别第一时间责怪工具先检查是不是书库被污染了。好的知识库应该像一个干净的图书馆而不是把所有杂物都堆在阅览室。4.5 误删除后如何恢复误删文件或者误改标题最稳的恢复姿势是git log看历史。我犯过一个比较经典的错手动把一篇几百字的长文删掉了又顺手同步了一下远程也跟着删了。此时本地 commit 还在只需要找到该文件曾经的 commit hash 即可git log --diff-filterD --summary然后恢复git checkout commit-hash^ -- 相对路径/文件名.md这个办法同样适用误改内容。如果你每天都自动提交那么最坏情况也就是丢掉最近半小时内的改动如果没提交过那文本文件还有第二道防线——文件系统历史备份比如 macOS 的本地快照或 Windows 的文件历史。所以数据安全真的不需要什么花哨技巧保持“有备份、有版本、有规律”三点就够了。4.6 常见问题速查表现象优先检查简单处理提示caveman: command not foundPATH、执行权限hash -r加执行权限确认安装路径同步时 stuck 在 rebase本地未提交文件git status看变更git stash暂存搜索漏掉内容文件编码、文件后缀用file查看编码转成 UTF-8打开文件很慢文件太大 / 目录太深移出 assets 或拆分成独立仓库命令记录不完整是否自动 sync 在跑检查 cron 配置与日志笔记目录下出现.DS_StoremacOS 自动生成写入.gitignore忽略最后说点我在实际使用中的体会这个项目的名字从“原始人”变成了一个提醒真正靠谱的记录方式不是追随最新的云体验而是回到最基本、最可控的文件组织上。我在用 caveman 的这段时间里最大的收获不是某个酷炫功能而是终于不再担心“某个笔记应用倒闭怎么办”“我存的格式还能打开吗”这类问题。数据握在自己手里格式公开透明历史版本保存在本地与远端这种安全感是再花哨的界面也给不了的。如果你也想动手试建议不要一次性大规模迁移先拿一周的新笔记来跑通流程再把旧数据慢慢灌入。等习惯了纯文本的打字节奏你会发现自己反而记了更多东西。