「caveman」这个项目名是我在整理自己一团乱麻的开发环境时定下来的。当时我的 dotfiles、脚本、配置散落在各个目录里有的用了复杂的符号链接工具有的依赖特定 GUI 软件重装一次系统要折腾大半天。我真正想要的其实是一种「原始人」级别的简单打开终端敲一条命令所有东西都回到该在的位置不依赖花哨的框架不搞分布式同步就靠纯文本和一个简单的 shell 脚本。于是 Caveman 就这么诞生了它不是什么惊天动地的开源框架而是一套刻意做「薄」的个人工作流管理方案专治各种配置混乱和工具链臃肿。这篇文章我会把整套思路、核心设计和踩过的坑都摊开来讲适合那些不想再被复杂工具绑架的开发者、知识管理爱好者以及所有想用最小成本搞定环境管理的人。1. 项目起源我为什么非要做一个「原始人」工具1.1 痛点工具链越用越重环境越管越乱先说说我最初遇到的问题。几年前我开始认真管理自己的开发环境收集了一堆 dotfiles也试过市面上几款主流的配置管理工具。那些工具功能确实强大支持模块化、加密、多机同步甚至还能管理远程服务器的状态。但随之而来的是陡峭的学习曲线我要记住它们自定义的模板语法要理解状态声明和资源依赖还得定期维护配置文件里那些被封装过的抽象层。有一次我仅仅想加一个 shell 别名就得改两个文件再跑一遍完整的校验流程。这种事情发生几次之后我开始怀疑自己是不是被工具绑架了。我真正需要的可能不是另一个庞大的系统而是一个能让我「回到洞穴」的方案把复杂的东西剥掉只留下最简单、最透明、最容易理解的规则。就像原始人不需要多功能瑞士军刀一块趁手的石头就够了。Caveman 这个名字起的直接因为它就是一门「往回走」的学问——往回走到只用纯文本、只用 shell、只用 Git 的程度。1.2 Caveman 的核心哲学简单到不能再简单Caveman 的核心哲学总结下来是三句话一切皆文件同步靠 Git执行靠 shell。它不做守护进程不搞服务端不引入任何新的配置文件格式更不会在系统里埋藏隐藏的数据库。所有状态就是你自己组织好的那一堆纯文本文件所有操作就是对着这些文件执行的一串命令或者一个能反复运行的脚本。我最初定下的三条「军规」是第一任何新功能如果不能用 20 行以内的 shell 脚本实现就坚决不纳入主程序第二任何数据如果不能被cat直接读出来就不应该被管理第三任何操作如果不能在离线状态下完成就一定是过度设计。这三条「军规」帮我挡掉了很多诱惑比如有人建议我加个 Web 管理界面也有人建议我用 YAML 来定义复杂的状态依赖都被我拒绝了。因为一旦加入这些Caveman 就不再是 Caveman而是又一个等着被替代的中间层。2. 整体设计与原理拆解Caveman 是怎么运转的2.1 目录结构一份一眼就能看懂的「洞穴地图」Caveman 的目录结构大概是整个项目里我最得意的地方因为它简单到几乎不需要文档。整个工作区就两个核心目录和一组普通文件~/.caveman/存放配置和脚本~/caveman_stash/这个名字你可以随意改存放你真正想管理的「家当」包括 dotfiles、文档草稿、小工具脚本等等。在~/.caveman/里面我不做层级非常深的嵌套最多三层envs/放不同机器的环境变量定义scripts/放各种一键执行脚本最外层放一个README.md。为什么这么设计因为 Caveman 的根本逻辑是「约定优于配置」。你不需要去记某个文件具体存放在哪个抽象分类里只需要遵循一个简单的直觉能被find搜索到的能通过grep全局检索的就是好结构。我自己在实践里发现那些层级复杂、抽象度高的目录结构往往只在创建它的那一刻是合理的三个月后再看连自己都找不到东西。Caveman 的目录刻意保持扁平就是为了对抗这种「知识的熵增」。2.2 核心命令四个命令覆盖全部高频操作Caveman 没有做成一个需要pip install或者npm install的完整程序原因在后面会详细讲。它本质上是一组 shell 函数由一份caveman.sh定义用户在自己的.bashrc或.zshrc里 source 一下就能使用。我知道很多人会觉得这不够「正式」但正是这种设计让它保持极高的透明度和可定制性。核心命令只有四个。第一个是cm init用于在空目录或者既有目录里生成 Caveman 的标准骨架包括基本的目录树和一份占位 README。第二个是cm add path这个命令会把指定的文件或目录链接进 Caveman 工作区但它不复制文件而是建立一个相对路径的符号链接。第三个是cm sync它做的事情很简单先对比工作区和本地的文件差异再自动提交一条 Git 记录最后推送远程。第四个是cm restore在新机器上把整个工作区拉下来重新创建所有符号链接。你可能注意到了这套设计里没有显式的「删除」命令。因为删除文件本来就是 Git 的职责cm add是软链接你直接删掉源文件链接就断了再跑一次cm sync就能把这种删除记录同步到远程。我把命令数量压缩到四个每一个都对应一个动词初始化、添加、同步、恢复。这比再去设计什么cm move、cm clone、cm status要省心得多而且大部分时候我根本不需要额外的命令。2.3 为什么不用数据库、不用 YAML、不用守护进程Caveman 曾差点变成一个带 SQLite 存储的工具。当时我想给每个文件加 tag 元数据方便按标签搜索。认真思考之后我放弃了因为一旦引入数据库就会面临几个问题数据库文件损坏怎么办多台机器之间的元数据怎么合并如果只是加一行 tag我直接约定成文件名后缀不是更好吗于是我的方案是想要 tag 某份文档就在文件名里加一个点号前缀比如ideas.webscraper.txt然后用find命令一搜就全都出来了。不用 YAML 的原因也类似YAML 是给程序读的人的想象力和适应性很难被一套固定 schema 约束住。真实世界的信息是混乱且丰富的用缩进和冒号去规范它们只会带来解析错误和心智负担。纯文本则百无禁忌什么东西都能往里装就算哪天 Caveman 这个工具不存在了你的数据依然是可读的纯文本。不用守护进程则是因为永久在后台跑着的东西既消耗资源又会在无形中让用户失去掌控感。Caveman 的设计思路是需要同步的时候才同步不需要的时候绝对不打扰。3. 实操过程从零开始部署一套 Caveman 工作流3.1 五分钟初始化一个「洞穴」初始化过程简单得让人感动。假设你要在一台新机器上部署 Caveman第一步是克隆主仓库然后在自己熟悉的 shell 配置里加一行 source。在我这里整条命令长这样git clone https://github.com/yourname/caveman.git ~/.caveman echo source ~/.caveman/caveman.sh ~/.bashrc source ~/.bashrc接下来就可以运行cm init了。这个命令会在当前用户目录下创建一个caveman_stash/文件夹同时往~/.caveman/里写入一份基础的环境变量模板。你也许会问这一步为什么不自动完成因为我不喜欢那种「你都不知道它往系统里写了什么」的工具。所有文件都摆在明面上你随时可以打开看随时可以删除。初始化完毕后我还会手动创建一个~/.caveman/README.md用来记录一台机器的用途、主要软件清单和安装日期。这个 README 意义重大它就像洞穴门口刻的标记半年之后你重看它能迅速想起当初为什么要在这台机器上搭建环境。这样的元信息是任何自动生成工具都替代不了的。3.2 把 dotfiles 纳入管理符号链接是核心拿管理.bashrc来举个例子。cm add ~/.bashrc执行后Caveman 会怎么做它会先判断目标文件是否存在如果存在就把它移动到caveman_stash/user/bashrc再在原位置建立一个指向新位置的符号链接。注意这里我把目标移进了仓库而不是把仓库里的文件复制出来这是两个完全不同的思路。如果只是复制那你在当前机器上对.bashrc的每一次修改都只发生在副本上永远无法同步回去。符号链接则让「当前机器上的文件」和「仓库里的文件」在事实上是同一个文件任何修改都即时生效最终通过 Git 同步。这个设计可以类比为你不是把一份合同复印两份发给两家公司而是让两家公司共同使用同一位律师律师走到哪里合同就跟到哪里。在cm add的实现细节里路径处理是最容易出错的地方。我早期版本用的是绝对路径结果换一台用户名不同的机器就尴尬了。后来改成了相对于HOME的路径用realpath --relative-to来计算。这样配置在不同机器之间是可移植的。符号链接还有一个好处是数据冗余为零同样的 dotfiles 只存在一份本地机器改了仓库立刻就是最新状态。3.3 让配置脚本变成「一键执行」的仪式除了管理静态文件Caveman 的另一个大用途是存放那些琐碎但必要的操作脚本。我在这里举两个例子一个是我重装系统后的「环境一键恢复」脚本一个是我日常的「同步检查」脚本它们都放在~/.caveman/scripts/目录下。环境恢复脚本bootstrap.sh做的事情很朴素但写下来都是泪。它先根据当前系统的版本号安装基础编译工具和常用软件包再调用cm restore把符号链接全部还原最后逐个执行仓库里预设的各项服务配置命令。这个脚本我不是一次写成的而是每次重装系统时遇到一个坑就往里加一条命令半年下来脚本长度已经超过一百行但它每一次运行都能让一台裸机快速变成我熟悉的工作环境。同步检查脚本healthcheck.sh则更轻量它只做一件事检查当前机器上所有指向caveman_stash的符号链接是否都还活着。如果发现有断链就输出警告并给出指向原位置的绝对路径。这个脚本之所以有用是因为很多人包括我自己会在操作中不小心删掉源文件或者在搬迁目录时破坏了相对路径关系。定期跑一次healthcheck能避免等到提交 Git 时才发现一大片文件出了问题的尴尬。3.4 用 Git 做版本控制分支策略要克制Caveman 的版本控制策略非常克制没有复杂的工作流只有一条长期分支和按需创建的临时分支。我的日常操作就是git add -A git commit -m update然后推送。你可能会说这样的 commit message 一点信息量都没有。但对我来说Caveman 更像是「自动备份」而不是「精确到每一行变更的版本档案」。如果真的需要详细记录那我应该在源文档里写清楚变更日志而不是依赖 Git commit。多机同步时最怕的是两台机器同时修改同一个文件然后互相覆盖。Caveman 的应对策略很简单如果cm sync时发现有未合并的冲突它会停下来等待你手动处理绝不尝试自动合并。因为纯文本文件之间的自动合并在绝大多数场景下都会产生令人哭笑不得的结果。我宁可在本地先手工合并完再执行一次提交推送也不冒那个把两份内容搅在一起的风险。这也符合 Caveman 的哲学把决策权保留给人工具只负责执行明确的操作。4. 常见问题与排查技巧实录4.1 问题速查表90% 的问题都在这张表里我在使用 Caveman 的过程中把遇到过的典型问题和解决方法整理成了一张速查表。这些问题的规律性很强九成以上都逃不出这几类。症状可能原因快速解决方案执行cm sync提示大量文件被删除某个目录的符号链接失效且源文件被误移先运行cm status查看 Git 差异再用find -L ~/caveman_stash -type l ! -exec test -e {} \;扫出断链cm add报错说路径不存在计算机名或用户名不同导致路径解析失败检查是否用了绝对路径Caveman 要求必须用~开头的相对路径或基于HOME的符号链接新机器上 restore 后找不到命令环境变量没加载或caveman.sh没有被 source检查 shell 启动文件确认source行在配置文件里的位置两台机器出现 Git 冲突两个环境同时修改了同一文件手动选择保留版本删除冲突标记推送前先用cm sync命令做一次本地校验脚本执行时遇中文乱码文件编码不统一统一成 UTF-8在caveman.sh文件头部显式声明export LANGC.UTF-8表格里面顺手写的find -L命令是我排查断链问题的一个核心武器。-L参数会让 find 遍历时跟随符号链接如果链接指向的文件不存在它就会把这个链接当作异常项列出来。这个命令比一个个ls检查要高效得多尤其是当仓库目录开始变得庞大的时候。4.2 我踩过的坑路径、转义与跨平台踩坑记录里路径问题稳居第一名。早期我偷懒在配置文件里顺手写了带有空格的目录名类似Personal Notes这种。一开始在本地跑得好好的直到某一天把仓库克隆到另一台机器安装脚本瞬间爆出一串诡异错误。后来我把所有目录名和文件名里的空格全部替换成点号比如personal.notes同类的路径麻烦再也没有出现过。空格在 shell 脚本里是天然的分隔符你永远要在各个地方小心加引号才能保证正确解析这种心智负担完全可以用一个简单约定消除掉。转义问题是第二坑。写 shell 脚本时如果要在双引号字符串里嵌入变量再嵌套单引号稍不留神就会被 shell 的解析规则拆得七零八落。我最惨痛的一次经历是写环境恢复脚本时想把一段代理配置写入既有文件里结果因为没注意转义脚本执行完以后配置文件被写入了十几行残缺变量。现在我的处理原则是凡是涉及多行文本插入的场景一律使用 heredoc 格式并且保证 heredoc 的结束标记行顶格书写前面不能有空格或缩进。跨平台适配是第三个常青话题。Caveman 的 shell 脚本主要面向 Linux 和 macOS我用的是 Bash 的兼容子集。但有症状是 macOS 自带的 Bash 版本古老某些语法如关联数组无法原生工作还需要先升级成新版 Bash 才能运行。另外realpath命令在 macOS 上默认也不存在需要一个 fallback 实现。我给 Caveman 写了一个path_normalize函数优先调用系统的realpath如果不可用就退回到基于pwd的字符串拼接。这类细节不遇到一次真的不会长记性。4.3 使用心得什么场景适合用 Caveman什么场景不要用Caveman 最适合的场景是个人开发者或小型团队管理那些以文本为主、变更频率适中、容忍离线操作的工作资产比如 dotfiles、脚本、Markdown 笔记、配置文件模板。它也很适合那些不喜欢被工具约束、更愿意亲手掌控一切细节的资深用户。如果你是一个视效率为生命的人希望在五秒内完成「备份-同步-恢复」的完整闭环Caveman 这套组合拳会非常顺手。但有些场景Caveman 明确不适合。如果涉及敏感信息管理应该去用专门集成了加密功能的工具Caveman 不做任何数据加密Git 仓库一旦泄露里面所有内容都会曝光。如果要管理二进制大文件比如几 GB 的设计稿库Git 仓库和符号链接也会迅速变得难以维护。更大的差异在于协作场景Caveman 的松散约定和随性的 commit 风格会让习惯规范工作流的团队成员非常难受。所以它本质上是一套单兵作战工具别硬往团队协作上套。5. 写在最后一条维护十年的「原始人」路线Caveman 这个项目从最初那台旧笔记本上的一个 shell 函数慢慢长成了现在这套我每天都会用到的工作流。我个人的体会是做这类个人工具最难的不是技术实现而是克制住不断加法、不断堆功能的欲望。每当我冒出一个「要是 Caveman 也能干这个就好了」的念头我都会先问自己这个需求到底是真实的痛点还是只是追求新鲜感。百分之八十的情况下答案是后者。剩下的百分之二十我用目录、命名约定和外部命令就能解决根本不脏 Caveman 的本体。如果也给正在打造自己全套工具链的朋友一个建议那就是一定要确保每个工具都有它不可替代的清晰边界。Caveman 的边界就是管理文本、同步文本、恢复文本。它不装界面不搞服务端不去碰任何它不擅长的事情。这样的工具才会越用越顺十年后依然在那里安静地工作就像洞穴入口处那块经风雨而不腐的石碑。