前阵子因为换电脑被迫把散落在三个笔记软件、十几个 Markdown 文件、还有聊天记录里的一大堆碎片信息归拢到一起。过程极其痛苦这边复制一段代码那边粘一条灵感有的文件命名是“新建文档 17”有的根本打不开……整理到半夜我突然意识到自己缺的不是又一个精致的知识管理软件而是一个足够原始、足够直接的“杂物间”。然后我就看到了caveman这个开源小项目。一开始是被名字戳中了——穴居人简单粗暴。用了一个周末之后我把手上百分之八十的日常记录都迁了进去并且打算长期留着它。这篇文章就把我的完整使用经历、踩过的坑、以及我对这套“原始方案”的理解一次性写清楚希望对同样被信息爆炸折磨的人有帮助。1. Caveman 解决的问题当知识库变成垃圾堆1.1 我的痛点和“洞穴”的灵感过去这两年我尝试过 Notion、Obsidian、语雀、Flomo……每个工具刚上手都觉得“这次应该行了”但三个月后总会陷入同一个死循环结构越建越复杂分类越来越细最后整理分类的时间比真正写内容的时间还多然后某一天彻底放弃。caveman的思路和这些工具完全相反它不给你预设任何分类、标签、文件夹结构甚至不给你一个图形界面。它的全部逻辑就是——你把一条一条的信息扔进一个目录里就像穴居人捡回一块一块的石头丢进自己的洞穴。每一块石头都是独立的纯文本文件石头之间可以通过内容里的链接互相咬合垒成一堵墙。我第一反应是“这也太简陋了”。但真正用起来才发现这种原始恰恰是它的护城河没有数据库、没有云同步、没有插件市场、没有权限管理。你拥有的只是一堆普通文件任何能编辑文本的东西都能打开它们。这意味着永远不会出现“软件倒闭数据全没”的灾难也永远不会出现“这个功能在免费版被锁住”的憋屈。1.2 为什么不是 Notion / Obsidian我朋友问我Obsidian 不也是本地 Markdown 文件吗你为什么不直接用 Obsidian区别其实很大。Obsidian 的核心是“库Vault”你需要在里面建立笔记之间的双链关系官方仓库和社区插件加起来有好几百个功能可选。对于有明确整理习惯的人这是利器但对于我这种三天两头改变分类逻辑的人来说它就是负担。caveman没有库的概念只有一个caveman.md索引文件记录所有石头的位置和一句摘要。你不需要预先设计任何层级想到什么就丢什么索引文件会自动更新。这相当于把一个无限灵活的白板压缩成了一张能随手涂改的草稿纸。另外Obsidian 的同步功能常年依赖第三方插件或付费服务而caveman因为所有数据都是普通文件天然支持 Git、坚果云、Syncthing 甚至 U 盘拷贝。这种“退化”反而成了最大的可取之处——工具不应该绑架你的数据数据应该回归纯粹的文本。2. 从零装好 Caveman不折腾的安装过程2.1 依赖准备与获取方式caveman是一个基于 Node.js 的命令行小工具没有图形界面。安装它只需要两样东西Node.js版本不低于 14和一个终端Windows 用户建议直接用 PowerShell 或 Windows Terminal。我用的是 macOS安装过程是git clone https://github.com/caveman-cli/caveman.git cd caveman npm install -g .注意最后一步是.不要漏掉。npm 会把caveman命令全局安装到系统里。如果你只想像我一样先试玩一下不全局安装也行直接在项目目录里用node bin/caveman.js来调用。但全局安装之后会更顺手之后在任何目录都能使用caveman开头的一系列命令。安装完成后执行caveman --version能看到版本号就说明装好了。我当时卡在这里好几秒钟因为 npm 在全局安装时需要当前用户对全局目录有写权限。如果你遇到EACCES: permission denied之类的报错不要去用sudo npm install -g强改权限那是给自己埋雷。正确做法是修复 npm 的全局目录权限或者直接改用nvm管理 Node 版本让全局目录落在用户目录下。2.2 初始化「洞穴」和目录结构装好后找一块舒服的地方创建你的“洞穴目录”。我的建议是放在一个你平时不太会乱动、且会被备份覆盖到的位置比如~/Documents/caveman下。然后在终端里开一个cave子目录mkdir ~/Documents/caveman cd ~/Documents/caveman caveman cave --init执行完初始化目录里会出现三个东西stones/这是核心数据目录里面每个.md文件就是一块“石头”文件名是创建时的时间戳形如20250614-213045.md。caveman.md总索引文件记录了每一块石头的文件名、首行摘要和创建时间。你可以随时打开它手动调整顺序或添加备注。config.json配置文件包括默认编辑器、搜索时忽略的规则、以及是否开启自动摘要等。我不建议你在stones/目录里手动建子文件夹去分类那样会破坏caveman的扁平结构。想分类用标签后面会讲。这个工具的设计哲学就是“先扔进去再说”分类是之后检索时做的事情而不是存储时的事情。2.3 数据存储的安全性设计因为每块“石头”都是独立的 Markdown 文件所以数据安全性非常简单粗暴你只要备份了stones/这个目录就备份了整个知识库。我直接把它放进了坚果云的同步文件夹同时用 Git 做版本管理。这样即使哪一天在某一台电脑上误删了一条记录也能从历史记录里捞回来。有一个细节值得单独提caveman默认不会自动压缩图片或附件你可以在石头文件里通过相对路径引用stones/旁边的attachments/目录。这意味着整个知识库就是一个普通文件夹你可以用任何同步工具、压缩工具、甚至是 grep 命令直接处理它。没有任何私有二进制格式没有任何需要专用软件才能解开的锁。3. 日常操作像穴居人一样扔石头3.1 添加、查看、搜索三个核心指令caveman的命令只有六个左右日常高频使用的是这三个添加一条记录caveman add 今天读《设计数据密集型应用》第3章分布式系统的分区策略重点哈希分区可以避免热点但范围分区对范围查询更友好。这个命令会把引号里的内容写入一个新的时间戳文件并自动更新索引。如果你在命令末尾加上--interactive它反而会打开编辑器让你输入多行内容。个人建议直接用引号参数快、干净。查看最近记录caveman list [n]list默认显示最近 20 条记录的摘要和时间。我习惯加一个数字参数比如caveman list 50看最近五十条。每条摘要就是每块石头文件的第一行内容超过 80 个字符会被截断。搜索记录caveman dig 分区策略dig是核心中的核心它的意思是“在洞穴里挖”。实现原理就是递归扫描stones/目录然后在每个文件内容里做字符串匹配最后输出匹配到的文件名、行号和上下文。它不支持复杂的正则也没有全文检索的评分机制就是一个朴素的grep加强版。但对大多数碎片记录来说这种搜索已经足够快——几百个文件几毫秒就出结果。3.2 建立知识关联——把石头垒成墙如果说扔石头是基础操作那让石头之间产生关联才是caveman真正好用的地方。关联语法非常简单在一条记录里写上另一块石头的时间戳文件名中间不加扩展名。例如caveman add TODO: 把 20250614-213045 里关于哈希分区的笔记整理成博客草稿这样在查看20250614-213045.md这块石头时如果你用caveman cat 20250614-213045命令查看它会在底部自动渲染出所有“提到过这个文件的记录”的摘要。反向链接不需要预先声明是自动计算的。这种机制和 Roam Research 的双向链接类似但实现成本低了不知道多少倍它只是每次查看时临时扫描一遍所有文件找谁在正文里写下了这个文件名。我后来还写了个简单的 shell 脚本可以批量把某条记录链接到当前正在看的文件caveman add 补充参见 20250614-213045 的延伸思考频率高了之后我的“洞壁”上自然而然垒出了几堵厚墙技术阅读、项目灵感、生活琐事。尽管我没有给它们建过任何文件夹这些墙是通过链接自动长出来的。3.3 用真实场景走一遍完整流程说了半天命令不如走一遍完整场景。假设我现在同时在看一本书、准备两个项目的方案、还要记一些突然蹦出来的购物灵感。我先初始化洞穴然后随手添加caveman add 《卡片笔记写作法》第4章文献笔记必须用自己的语言写不能直接抄原文 caveman add 项目A的技术选型考虑用 SQLite 代替 PostgreSQL减少运维成本 caveman add 今天下班路上想到的营销点子办一场「素人故事交换市集」第二天我想找“文献笔记”相关的所有内容执行caveman dig 文献笔记它列出了第一条记录下面还同步显示了引用过它的两个新文件。原来我昨天把《卡片笔记》的观点和项目B的方案做了一个链接这个链接在搜索结果里也被列出来了。这种“搜索结果附带反向引用”的体验确实让我感觉洞穴里的石头之间有了隐形的锚点。4. 进阶玩法和周边生态4.1 用标签代替分类caveman本身没有标签功能但你可以自己约定一个语法在内容里写上#标签名。检索时直接用caveman dig #深度工作来过滤。我给自己定了三条规则标签放在行首方便一眼扫到。标签必须落在固定的白名单里不在白名单里的词不配当标签这是防止标签泛化。标签之间可以互相组合搜索比如caveman dig #读书 #技术虽然底层只是字符串匹配但加了自定义脚本后也能实现简单的与逻辑。为什么不用真正的标签系统因为那个复杂需要维护标签表需要设计层级。而用#前缀不过是自然语言里的一个约定既可以用grep直接搜也可以在任何编辑器中着色显示。我宁愿多花一点打字时间也不愿再多维护一个“标签管理中心”。4.2 自动化和定时备份因为所有数据都是文件自动化就非常简单。我写了三个定时脚本配合 crontab 运行自动摘要每三天执行一次caveman tidy它会自动为长度超过 200 字符的石头生成第一行摘要如果有空行的话就截取第一自然段。这样索引列表不至于被长内容淹没。同步到远端仓库每晚用 Git 把stones/目录 push 到私有仓库。临时清理每周清除 30 天内没有访问过、且没有任何反向链接的孤立石头被放进archive/文件夹而不是直接删除。这三条规则让我不用分心去想“这个文件要不要留”系统会自己保持整洁。如果你不想碰 crontab也可以用 macOS 的 launchd 或者 Windows 任务计划程序本质都一样。4.3 与其它工具的联用方案有了命令行接口和外部工具的联动就变得非常自由。和终端里的 todo 系统结合我用caveman add加上一句约定前缀TODO:来收集待办然后写一个脚本today把今天所有含TODO:且日期匹配的内容输出算是一个极简的 GTD。和编辑器结合在 VS Code 里把stones/目录作为工作区打开用快捷键绑定caveman add命令就能在写代码时随手记录灵感不用切换窗口。和手机结合我用 Termux 在手机上安装 Node.js把同一个stones/目录放到 Syncthing 同步文件夹里出门在地铁上直接用手机命令行添加灵感回家后在电脑上就能看到。这套最爽的地方在于没有任何一个环节需要用商业软件。数据全部在自己手里流程可审计可替换。5. 踩坑实录我在这几天里遇到的三类问题5.1 编码问题中文乱码的罪魁祸首第一次在终端里添加中文内容时caveman list显示的摘要全变成了????但直接用文本编辑器打开文件内容却是好的。排查过程花了我将近半小时。最后发现原因不在caveman而在终端自身的字符编码。macOS 的终端默认 UTF-8 没错但有些切换过语言的机器会把终端编码设置成GBK或Latin-1。解决办法是在终端配置文件里显式加上export LANGen_US.UTF-8 export LC_ALLen_US.UTF-8加上之后重启终端重新执行caveman list中文显示就正常了。另外还要注意Windows 的 PowerShell 默认编码是UTF-16 LE如果你直接在 PowerShell 里调用 Node.js 的caveman很可能会出现编码不匹配。最好的办法是执行下面这句话让 PowerShell 用 UTF-8 输出[Console]::OutputEncoding [System.Text.Encoding]::UTF85.2 搜索静默失败关键词包含特殊字符有一次我想找一条和C相关的笔记执行caveman dig C结果返回空。后来发现caveman内部实现用的是String.includes()进行匹配按理说C一定能匹配到问题出在我添加记录时用的是全角加号或者记录里写的是Cpp这样的缩写。这种“静默失败”比报错更坑因为你以为没找到实际上是关键词不一致。我的规避方案写自定义fast-dig命令在底层调用ripgrep做正则搜索并同时忽略大小写、支持最长匹配alias fast-digrg -i -l然后用fast-dig C\\|Cpp|c plus plus来搜。如果你对搜索精度有更高要求完全可以把底层换成ripgrep只要你会写几行脚本caveman的命令管道就能很轻松地和周围生态对接。5.3 同步冲突多设备编辑同一块「石头」有次手机和电脑同时修改了同一块石头同步工具自动生成了一个冲突副本文件名变成了20250614-213045_conflict.md。因为caveman索引里根本没记录这个文件导致它变成了一颗“游离的石头”在检索时能搜到内容但在索引列表和反向链接里都看不到。那次之后我学乖了在同步工具里把stones/设成了单向同步手机只上传、电脑只下载然后主要在电脑端做编辑手机上只做新记录的添加不做已有记录的修改。同时写了一个小脚本每天检测stones/目录下有没有在索引之外的文件有就自动合并进索引。这样再也没出现过“鬼文件”的问题。6. 为什么我最终留住了 Caveman用“效率软件”的标准衡量caveman明显是落后于时代的。没有移动端 App没有全文检索评分没有富文本编辑器甚至连个像样的 UI 都没有。但我留它下来的原因也恰恰是这些“落后”它让我告别了整理强迫症。以前我用 Notion 时为一个“今日灵感”放在哪个页面下都能纠结十分钟现在我只做一件事——扔消息不整理。搜索的时候宁可多挖几下也不想预先画好一堆抽屉然后把东西分门别类塞进去。对我来说“随手能挖出来”比“放得井井有条”重要得多。也许你的习惯和我不同也许你真的需要一个功能强大的知识库。但如果你想给自己的碎片信息找一个不被任何厂商绑架的家一个哪怕五十年后只要还能打开文本文件就能读的家caveman这个“洞穴”值得你花一个周末试试。往洞里扔第一块石头的时候你大概也会觉得原来摆脱工具焦虑的感觉这么好。 
长河君 · 2026/10/29 4:12:14 · 阅读 1.2k 用本地Markdown和命令行构建原始知识库：Caveman工具实战
前阵子因为换电脑被迫把散落在三个笔记软件、十几个 Markdown 文件、还有聊天记录里的一大堆碎片信息归拢到一起。过程极其痛苦这边复制一段代码那边粘一条灵感有的文件命名是“新建文档 17”有的根本打不开……整理到半夜我突然意识到自己缺的不是又一个精致的知识管理软件而是一个足够原始、足够直接的“杂物间”。然后我就看到了caveman这个开源小项目。一开始是被名字戳中了——穴居人简单粗暴。用了一个周末之后我把手上百分之八十的日常记录都迁了进去并且打算长期留着它。这篇文章就把我的完整使用经历、踩过的坑、以及我对这套“原始方案”的理解一次性写清楚希望对同样被信息爆炸折磨的人有帮助。1. Caveman 解决的问题当知识库变成垃圾堆1.1 我的痛点和“洞穴”的灵感过去这两年我尝试过 Notion、Obsidian、语雀、Flomo……每个工具刚上手都觉得“这次应该行了”但三个月后总会陷入同一个死循环结构越建越复杂分类越来越细最后整理分类的时间比真正写内容的时间还多然后某一天彻底放弃。caveman的思路和这些工具完全相反它不给你预设任何分类、标签、文件夹结构甚至不给你一个图形界面。它的全部逻辑就是——你把一条一条的信息扔进一个目录里就像穴居人捡回一块一块的石头丢进自己的洞穴。每一块石头都是独立的纯文本文件石头之间可以通过内容里的链接互相咬合垒成一堵墙。我第一反应是“这也太简陋了”。但真正用起来才发现这种原始恰恰是它的护城河没有数据库、没有云同步、没有插件市场、没有权限管理。你拥有的只是一堆普通文件任何能编辑文本的东西都能打开它们。这意味着永远不会出现“软件倒闭数据全没”的灾难也永远不会出现“这个功能在免费版被锁住”的憋屈。1.2 为什么不是 Notion / Obsidian我朋友问我Obsidian 不也是本地 Markdown 文件吗你为什么不直接用 Obsidian区别其实很大。Obsidian 的核心是“库Vault”你需要在里面建立笔记之间的双链关系官方仓库和社区插件加起来有好几百个功能可选。对于有明确整理习惯的人这是利器但对于我这种三天两头改变分类逻辑的人来说它就是负担。caveman没有库的概念只有一个caveman.md索引文件记录所有石头的位置和一句摘要。你不需要预先设计任何层级想到什么就丢什么索引文件会自动更新。这相当于把一个无限灵活的白板压缩成了一张能随手涂改的草稿纸。另外Obsidian 的同步功能常年依赖第三方插件或付费服务而caveman因为所有数据都是普通文件天然支持 Git、坚果云、Syncthing 甚至 U 盘拷贝。这种“退化”反而成了最大的可取之处——工具不应该绑架你的数据数据应该回归纯粹的文本。2. 从零装好 Caveman不折腾的安装过程2.1 依赖准备与获取方式caveman是一个基于 Node.js 的命令行小工具没有图形界面。安装它只需要两样东西Node.js版本不低于 14和一个终端Windows 用户建议直接用 PowerShell 或 Windows Terminal。我用的是 macOS安装过程是git clone https://github.com/caveman-cli/caveman.git cd caveman npm install -g .注意最后一步是.不要漏掉。npm 会把caveman命令全局安装到系统里。如果你只想像我一样先试玩一下不全局安装也行直接在项目目录里用node bin/caveman.js来调用。但全局安装之后会更顺手之后在任何目录都能使用caveman开头的一系列命令。安装完成后执行caveman --version能看到版本号就说明装好了。我当时卡在这里好几秒钟因为 npm 在全局安装时需要当前用户对全局目录有写权限。如果你遇到EACCES: permission denied之类的报错不要去用sudo npm install -g强改权限那是给自己埋雷。正确做法是修复 npm 的全局目录权限或者直接改用nvm管理 Node 版本让全局目录落在用户目录下。2.2 初始化「洞穴」和目录结构装好后找一块舒服的地方创建你的“洞穴目录”。我的建议是放在一个你平时不太会乱动、且会被备份覆盖到的位置比如~/Documents/caveman下。然后在终端里开一个cave子目录mkdir ~/Documents/caveman cd ~/Documents/caveman caveman cave --init执行完初始化目录里会出现三个东西stones/这是核心数据目录里面每个.md文件就是一块“石头”文件名是创建时的时间戳形如20250614-213045.md。caveman.md总索引文件记录了每一块石头的文件名、首行摘要和创建时间。你可以随时打开它手动调整顺序或添加备注。config.json配置文件包括默认编辑器、搜索时忽略的规则、以及是否开启自动摘要等。我不建议你在stones/目录里手动建子文件夹去分类那样会破坏caveman的扁平结构。想分类用标签后面会讲。这个工具的设计哲学就是“先扔进去再说”分类是之后检索时做的事情而不是存储时的事情。2.3 数据存储的安全性设计因为每块“石头”都是独立的 Markdown 文件所以数据安全性非常简单粗暴你只要备份了stones/这个目录就备份了整个知识库。我直接把它放进了坚果云的同步文件夹同时用 Git 做版本管理。这样即使哪一天在某一台电脑上误删了一条记录也能从历史记录里捞回来。有一个细节值得单独提caveman默认不会自动压缩图片或附件你可以在石头文件里通过相对路径引用stones/旁边的attachments/目录。这意味着整个知识库就是一个普通文件夹你可以用任何同步工具、压缩工具、甚至是 grep 命令直接处理它。没有任何私有二进制格式没有任何需要专用软件才能解开的锁。3. 日常操作像穴居人一样扔石头3.1 添加、查看、搜索三个核心指令caveman的命令只有六个左右日常高频使用的是这三个添加一条记录caveman add 今天读《设计数据密集型应用》第3章分布式系统的分区策略重点哈希分区可以避免热点但范围分区对范围查询更友好。这个命令会把引号里的内容写入一个新的时间戳文件并自动更新索引。如果你在命令末尾加上--interactive它反而会打开编辑器让你输入多行内容。个人建议直接用引号参数快、干净。查看最近记录caveman list [n]list默认显示最近 20 条记录的摘要和时间。我习惯加一个数字参数比如caveman list 50看最近五十条。每条摘要就是每块石头文件的第一行内容超过 80 个字符会被截断。搜索记录caveman dig 分区策略dig是核心中的核心它的意思是“在洞穴里挖”。实现原理就是递归扫描stones/目录然后在每个文件内容里做字符串匹配最后输出匹配到的文件名、行号和上下文。它不支持复杂的正则也没有全文检索的评分机制就是一个朴素的grep加强版。但对大多数碎片记录来说这种搜索已经足够快——几百个文件几毫秒就出结果。3.2 建立知识关联——把石头垒成墙如果说扔石头是基础操作那让石头之间产生关联才是caveman真正好用的地方。关联语法非常简单在一条记录里写上另一块石头的时间戳文件名中间不加扩展名。例如caveman add TODO: 把 20250614-213045 里关于哈希分区的笔记整理成博客草稿这样在查看20250614-213045.md这块石头时如果你用caveman cat 20250614-213045命令查看它会在底部自动渲染出所有“提到过这个文件的记录”的摘要。反向链接不需要预先声明是自动计算的。这种机制和 Roam Research 的双向链接类似但实现成本低了不知道多少倍它只是每次查看时临时扫描一遍所有文件找谁在正文里写下了这个文件名。我后来还写了个简单的 shell 脚本可以批量把某条记录链接到当前正在看的文件caveman add 补充参见 20250614-213045 的延伸思考频率高了之后我的“洞壁”上自然而然垒出了几堵厚墙技术阅读、项目灵感、生活琐事。尽管我没有给它们建过任何文件夹这些墙是通过链接自动长出来的。3.3 用真实场景走一遍完整流程说了半天命令不如走一遍完整场景。假设我现在同时在看一本书、准备两个项目的方案、还要记一些突然蹦出来的购物灵感。我先初始化洞穴然后随手添加caveman add 《卡片笔记写作法》第4章文献笔记必须用自己的语言写不能直接抄原文 caveman add 项目A的技术选型考虑用 SQLite 代替 PostgreSQL减少运维成本 caveman add 今天下班路上想到的营销点子办一场「素人故事交换市集」第二天我想找“文献笔记”相关的所有内容执行caveman dig 文献笔记它列出了第一条记录下面还同步显示了引用过它的两个新文件。原来我昨天把《卡片笔记》的观点和项目B的方案做了一个链接这个链接在搜索结果里也被列出来了。这种“搜索结果附带反向引用”的体验确实让我感觉洞穴里的石头之间有了隐形的锚点。4. 进阶玩法和周边生态4.1 用标签代替分类caveman本身没有标签功能但你可以自己约定一个语法在内容里写上#标签名。检索时直接用caveman dig #深度工作来过滤。我给自己定了三条规则标签放在行首方便一眼扫到。标签必须落在固定的白名单里不在白名单里的词不配当标签这是防止标签泛化。标签之间可以互相组合搜索比如caveman dig #读书 #技术虽然底层只是字符串匹配但加了自定义脚本后也能实现简单的与逻辑。为什么不用真正的标签系统因为那个复杂需要维护标签表需要设计层级。而用#前缀不过是自然语言里的一个约定既可以用grep直接搜也可以在任何编辑器中着色显示。我宁愿多花一点打字时间也不愿再多维护一个“标签管理中心”。4.2 自动化和定时备份因为所有数据都是文件自动化就非常简单。我写了三个定时脚本配合 crontab 运行自动摘要每三天执行一次caveman tidy它会自动为长度超过 200 字符的石头生成第一行摘要如果有空行的话就截取第一自然段。这样索引列表不至于被长内容淹没。同步到远端仓库每晚用 Git 把stones/目录 push 到私有仓库。临时清理每周清除 30 天内没有访问过、且没有任何反向链接的孤立石头被放进archive/文件夹而不是直接删除。这三条规则让我不用分心去想“这个文件要不要留”系统会自己保持整洁。如果你不想碰 crontab也可以用 macOS 的 launchd 或者 Windows 任务计划程序本质都一样。4.3 与其它工具的联用方案有了命令行接口和外部工具的联动就变得非常自由。和终端里的 todo 系统结合我用caveman add加上一句约定前缀TODO:来收集待办然后写一个脚本today把今天所有含TODO:且日期匹配的内容输出算是一个极简的 GTD。和编辑器结合在 VS Code 里把stones/目录作为工作区打开用快捷键绑定caveman add命令就能在写代码时随手记录灵感不用切换窗口。和手机结合我用 Termux 在手机上安装 Node.js把同一个stones/目录放到 Syncthing 同步文件夹里出门在地铁上直接用手机命令行添加灵感回家后在电脑上就能看到。这套最爽的地方在于没有任何一个环节需要用商业软件。数据全部在自己手里流程可审计可替换。5. 踩坑实录我在这几天里遇到的三类问题5.1 编码问题中文乱码的罪魁祸首第一次在终端里添加中文内容时caveman list显示的摘要全变成了????但直接用文本编辑器打开文件内容却是好的。排查过程花了我将近半小时。最后发现原因不在caveman而在终端自身的字符编码。macOS 的终端默认 UTF-8 没错但有些切换过语言的机器会把终端编码设置成GBK或Latin-1。解决办法是在终端配置文件里显式加上export LANGen_US.UTF-8 export LC_ALLen_US.UTF-8加上之后重启终端重新执行caveman list中文显示就正常了。另外还要注意Windows 的 PowerShell 默认编码是UTF-16 LE如果你直接在 PowerShell 里调用 Node.js 的caveman很可能会出现编码不匹配。最好的办法是执行下面这句话让 PowerShell 用 UTF-8 输出[Console]::OutputEncoding [System.Text.Encoding]::UTF85.2 搜索静默失败关键词包含特殊字符有一次我想找一条和C相关的笔记执行caveman dig C结果返回空。后来发现caveman内部实现用的是String.includes()进行匹配按理说C一定能匹配到问题出在我添加记录时用的是全角加号或者记录里写的是Cpp这样的缩写。这种“静默失败”比报错更坑因为你以为没找到实际上是关键词不一致。我的规避方案写自定义fast-dig命令在底层调用ripgrep做正则搜索并同时忽略大小写、支持最长匹配alias fast-digrg -i -l然后用fast-dig C\\|Cpp|c plus plus来搜。如果你对搜索精度有更高要求完全可以把底层换成ripgrep只要你会写几行脚本caveman的命令管道就能很轻松地和周围生态对接。5.3 同步冲突多设备编辑同一块「石头」有次手机和电脑同时修改了同一块石头同步工具自动生成了一个冲突副本文件名变成了20250614-213045_conflict.md。因为caveman索引里根本没记录这个文件导致它变成了一颗“游离的石头”在检索时能搜到内容但在索引列表和反向链接里都看不到。那次之后我学乖了在同步工具里把stones/设成了单向同步手机只上传、电脑只下载然后主要在电脑端做编辑手机上只做新记录的添加不做已有记录的修改。同时写了一个小脚本每天检测stones/目录下有没有在索引之外的文件有就自动合并进索引。这样再也没出现过“鬼文件”的问题。6. 为什么我最终留住了 Caveman用“效率软件”的标准衡量caveman明显是落后于时代的。没有移动端 App没有全文检索评分没有富文本编辑器甚至连个像样的 UI 都没有。但我留它下来的原因也恰恰是这些“落后”它让我告别了整理强迫症。以前我用 Notion 时为一个“今日灵感”放在哪个页面下都能纠结十分钟现在我只做一件事——扔消息不整理。搜索的时候宁可多挖几下也不想预先画好一堆抽屉然后把东西分门别类塞进去。对我来说“随手能挖出来”比“放得井井有条”重要得多。也许你的习惯和我不同也许你真的需要一个功能强大的知识库。但如果你想给自己的碎片信息找一个不被任何厂商绑架的家一个哪怕五十年后只要还能打开文本文件就能读的家caveman这个“洞穴”值得你花一个周末试试。往洞里扔第一块石头的时候你大概也会觉得原来摆脱工具焦虑的感觉这么好。