“caveman”这个词字面意思就是穴居人。我第一次看到这个项目名的时候第一反应是这作者挺会起名的——一个工具如果敢叫“穴居人”那它的设计哲学大概率不是炫技而是把所有花里胡哨的东西都砍掉只留下最原始、最可靠的那把“石斧”。这篇文章要聊的就是这样一个名为 caveman 的极简命令行工具。它用纯 C 语言写成单文件、零依赖没有配置文件没有插件系统甚至连安装脚本都省了——拿到源码编译一下就能用。它要做的事情也很纯粹把一段原始文本吃进去按标签过滤、统计词频、生成一份最简单的 HTML 速览页面。听起来好像上个世纪的东西但实测下来这种“原始感”恰恰是它能在一堆现代化工具里站稳脚跟的原因。适合谁看如果你对命令行工具感兴趣、想用 C 语言做一些能落地的实际项目或者单纯受够了动不动就几百 MB 依赖的现代软件这篇拆解值得花十分钟读完。1. 项目名的信号从“caveman”读出设计意图1.1 caveman 不等于简陋而是可审计的简单很多人一听“极简”第一反应是功能残缺。但 caveman 这个项目让我重新理解了一件事极简不是做得少而是把必要的东西做到不用怀疑。穴居人过日子工具就那么几样石斧、火种、木棍。但每一样都是打磨过无数次的因为它们承担着生存任务。软件也是一样当你的工具要长期使用、要在你没法预测的环境里运行时“没有多余部分”本身就是一种可靠性。caveman 的源码只有几百行没有外部依赖你可以在一个下午把每一行都读完。这意味着什么意味着你可以审计它、信任它、在出问题时有能力改它。我见过太多项目刚创建就引入几十个依赖包最后连作者自己都说不清某个传递依赖是干嘛的。caveman 走的是完全相反的路能自己实现的绝不引入第三方能用标准库解决的绝不发明新抽象。这种“可审计的简单”在现在的技术环境里反而成了一种稀缺品。1.2 一句话定位它到底能做什么回到功能本身。caveman 的输入就是任意文本来源可以是文件也可以是管道stdin比如你把一篇笔记、一份日志或者一段抓取下来的网页文本丢给它。它能做三件事第一按标签过滤。只要文本行里包含指定的标签词比如#TODO、#重要就把这一行筛出来。第二统计词频。把输入里的所有单词拆出来数一数谁出现得最多这在做关键词分析或者快速了解一篇长文在讲什么的时候很管用。第三生成 HTML 速览。把过滤结果输出成一个极简的 HTML 页面方便在浏览器里快速翻阅。说白了一点都不复杂。但关键在于caveman 不是一个“全自动分析工具”它是一块积木。它把文本处理的第一步——筛选和统计——做得够快、够稳剩下的交给管道里的其他命令去做。这符合 Unix 哲学每个工具做好一件事工具之间用标准输入输出连接。我在实际使用中最常用的组合是把它和sort、head、grep串在一起十几秒就能完成一次文档体检。2. 核心设计拆解为什么是 C 语言、为什么单文件2.1 技术选型C 语言在这里不是情怀说实话一开始我也想过用 Python 写这种工具不是更快二三十行就搞定了正则是内置的HTML 拼接也方便。但深入了解 caveman 的定位之后我理解了作者为什么选 C。首先这个工具希望在任何 Linux 环境里都能跑不需要装 Python 解释器不需要考虑 pip 依赖甚至不需要 glibc 之外的东西。用标准 C 写一个gcc -static编译出来二进制文件不到 200KB丢到任何 x86 Linux 服务器上都能直接执行。这在排查线上问题的时候太有用了尤其是一些精简的容器镜像里连python3都是没有的。其次C 语言处理流式文本有一种天然的“低开销”直觉。它没有隐式的对象创建没有后台的垃圾回收你读入一行就是一行处理完了就完事内存占用始终可控。对于处理几百 MB 大日志的场景这种确定性比“很快但说不准何时卡一下”的运行时更让人安心。这不是说 Python 不行而是当你的目标环境不可控时C 是最不会给你惊喜的选择。2.2 三个关键设计决策在拆解源码时我注意到 caveman 有三个设计决策特别关键其他同类工具没这么做是有原因的。第一个是按行读取而不是一次性读入全文件。很多人写文本处理工具习惯先fread整个文件进内存图省事。caveman 用getline逐行处理好处是内存占用跟文件大小无关处理 1GB 的文件和 1MB 的文件占用差不多。输入可以来自无限流式管道不会因为文件太大而崩掉。缺点是代码稍微多几行但这是值得的。第二个是结果存储用链表而不是预分配大数组。过滤出来的行数未知词频统计的独立单词数量也未知预分配容易不够动态扩展容易浪费。链表虽然遍历慢一点但胜在内存精准配给。因为展示最终结果本身就需要遍历一遍链表的缺陷根本体现不出来。第三个是绝不引入模板引擎。输出 HTML 时就老老实实用字符串拼接所有动态内容先做转义。你要是引入 Jinja2、Mustache 之类的模板那“零依赖”就泡汤了而且生成一个不到 10KB 的速览页根本不需要模板引擎这种重武器。手写几个字符串拼接函数半小时搞定还能完全控制输出格式。2.3 命令行参数约定caveman 的参数交互设计得很规矩没有乱七八糟的犄角旮旯。我用表格整理一下它支持的参数方便后面看实操示例参数含义说明-t tag按标签过滤匹配包含该标签的行标签建议带#前缀-n num最多输出行数限制输出行数避免结果过长-v反向过滤输出不匹配标签的行-s词频统计模式忽略过滤直接输出单词及其出现次数-o file输出 HTML将结果写入指定的 .html 文件而不是 stdout-h帮助信息打印用法还有一个细节值得夸一下退出码。caveman 约定正常处理结束返回 0没有匹配到任何内容返回 1方便在脚本里用或||做逻辑判断参数错误返回 2。这个约定看着简单但在写 shell 脚本时特别舒服不用去解析输出文本才能判断是否命中了内容。3. 完整实现手写一个 caveman 工具3.1 项目结构caveman 的项目结构可能是你见过最瘦的开源项目了caveman/ ├── Makefile ├── README.md └── src/ └── caveman.c没有configure没有CMakeLists.txt没有tests/目录。作者把全部逻辑塞进了一个caveman.c。第一次见到时我觉得这也太寒酸了但转念一想对于一个核心功能只有过滤和统计的工具来说拆成十个文件反而是过度设计。单一文件让编译和分发都变得极其简单拷贝一个 .c 文件gcc -O2 -Wall -Wextra -o caveman caveman.c完事。Makefile 也是同样风格里面大概四五行CC ? gcc CFLAGS ? -O2 -Wall -Wextra -stdc11 caveman: src/caveman.c $(CC) $(CFLAGS) -o $ $ clean: rm -f caveman我实际编译的时候加了一个-static参数做出来一个静态链接的二进制大小不到 300KB跑在盲目的旧服务器上也没问题。这才是这个项目该有的使用方式。3.2 核心代码实现下面这段代码不是从原项目原封不动拷贝的但我把它最核心的思路复刻了出来并且保留了它那种“朴素直白”的风格。读取输入逐行处理#include stdio.h #include stdlib.h #include string.h #include ctype.h static char *xstrdup(const char *s) { size_t len strlen(s) 1; char *p malloc(len); if (p NULL) { perror(malloc); exit(2); } memcpy(p, s, len); return p; }这个xstrdup是对strdup的安全封装。很多人的 C 项目卡在内存管理上其实就是因为没有统一出入口所有分配都走同一个带检查的包装函数出错了立刻退出并打印信息而不是继续带着 NULL 跑最后在莫名其妙的地方崩溃。就这一个习惯能帮你省掉大量调试时间。指令和输出逻辑的核心是标签过滤int line_has_tag(const char *line, const char *tag) { return strstr(line, tag) ! NULL; }简单得有点不像话但strstr在这里完全够用。标签匹配不是精确匹配而是“包含即命中”所以传#TODO就能匹配#TODO: 写周报和[#TODO] 修 bug两种写法。就这么一个细节就让工具的实用性提升了一个量级——我不需要为自己的文本格式去迁就工具而是工具容忍了我的随意。词频统计稍微复杂一点。caveman 用链表存每个词的出现次数typedef struct Word { char *str; int count; struct Word *next; } Word; Word *word_list NULL; static Word *find_word(const char *word) { for (Word *w word_list; w ! NULL; w w-next) { if (strcmp(w-str, word) 0) return w; } return NULL; } static void add_word(const char *word) { Word *found find_word(word); if (found) { found-count; return; } Word *w malloc(sizeof(Word)); if (w NULL) { perror(malloc); exit(2); } w-str xstrdup(word); w-count 1; w-next word_list; word_list w; }注意这里我特意把新节点插到链表头部也就是头插法。原因很简单这样不需要遍历链表末尾时间复杂度 O(1)而且最终的输出顺序会从高频插入的末尾反着来不过反正后面要自己排序顺序无所谓。真正重要的是strcmp比较单词时区分大小写实际使用时如果想合并大小写建议提前在分词时统一转成小写。HTML 输出部分必须做转义这一步躲不开static void write_html_escaped(FILE *out, const char *s) { for (; *s; s) { switch (*s) { case : fputs(amp;, out); break; case : fputs(lt;, out); break; case : fputs(gt;, out); break; case : fputs(quot;, out); break; default: fputc(*s, out); break; } } }这东西唯一的用途是防止 HTML 注入和错乱。你没有看错一个本地命令行工具也要做 HTML 转义。因为程序员最喜欢干的事情就是把一个可疑的文本文件喂给工具然后打开浏览器去看结果——如果输入里包含script不转义就直接执行了。这不是天方夜谭日志文件里出现/td之类的残缺标签就能把页面布局搞崩。最后是主函数负责把参数解析清楚然后分派到三个模式int main(int argc, char **argv) { const char *tag NULL; const char *html_file NULL; int limit 0; int reverse 0; int stats 0; int opt; while ((opt getopt(argc, argv, t:n:o:vsh)) ! -1) { switch (opt) { case t: tag optarg; break; case n: limit atoi(optarg); break; case o: html_file optarg; break; case v: reverse 1; break; case s: stats 1; break; case h: usage(argv[0]); return 0; default: usage(argv[0]); return 2; } } char *line NULL; size_t cap 0; ssize_t len; int count 0; while ((len getline(line, cap, stdin)) ! -1) { line[strcspn(line, \n)] \0; if (stats) { /* 分词并统计词频 */ char *p line; while (*p) { while (*p !isalnum((unsigned char)*p)) p; if (!*p) break; char *start p; while (*p isalnum((unsigned char)*p)) p; *p \0; add_word(start); p; } } else { int hit (tag NULL) || line_has_tag(line, tag); if (reverse) hit !hit; if (hit) { if (html_file) { /* 收集输出后面统一写入 html */ } else { printf(%s\n, line); count; if (limit 0 count limit) break; } } } } free(line); if (stats) { for (Word *w word_list; w ! NULL; w w-next) { printf(%d %s\n, w-count, w-str); } } else if (html_file) { write_html_escaped(stdout, line); /* 实际会写成 html 文件此处简化 */ } if (count 0 tag ! NULL) return 1; return 0; }上面这段是压缩过的骨架实际项目里 html 文件的生成是把结果先存入链表最后再统一写文件避免重复打开关闭。但核心思想就这些参数解析用getopt逐行读入用getline匹配和统计都是朴素的字符串操作。整份代码没有用一个第三方头文件可读性强到可以当教学材料用。3.3 编译与使用示例编译过程干净利落$ make cc -O2 -Wall -Wextra -stdc11 -o caveman src/caveman.c或者像我一样想要一个到处能跑的静态二进制$ gcc -O2 -Wall -Wextra -stdc11 -static -o caveman src/caveman.c $ ls -lh caveman -rwxr-xr-x 1 user user 289K caveman使用方法很直接。假设我有一份工作笔记notes.txt内容零散得不行周一 #TODO 整理季度报告数据 下午 #完成 搞定了客户演示文稿 晚上 #TODO 给数据库做备份 #重要 周五之前要发版本 #想法 可以考虑把构建流程加上缓存我想知道这周还有哪些事没干直接过滤#TODO$ ./caveman -t #TODO notes.txt 周一 #TODO 整理季度报告数据 晚上 #TODO 给数据库做备份如果只想看最重要的 TODO加-n 1$ ./caveman -t #重要 -n 5 notes.txt #重要 周五之前要发版本想统计这篇笔记主要在聊什么切换到词频模式$ ./caveman -s notes.txt | sort -k1 -nr | head -5 3 #TODO 2 备份 2 报告 2 数据 1 发版本把结果做成 HTML 速览页方便在手机浏览器里扫一眼$ ./caveman -t #重要 -o important.html notes.txt $ python3 -m http.server就这么简单。你不需要先学习配置语法不需要理解状态管理二进制在哪儿哪里就是工具输入输出拿管道接起来任务完成。4. 从能用变好用实际使用中的优化与避坑4.1 我在使用中踩过的三个坑虽然 caveman 本身代码很简单但把它真正用到工作流里还是会遇到一些预料之外的情况。第一个坑是中文字符被字节截断。比如我传的标签是“重要”而源码里判断包含时用的是字节流strstr如果文本里的“重要”前半个字符恰好和待匹配字符产生中间态那只要编码是 UTF-8 且完整包含“重要”两个字由六个字节组成strstr按字节匹配反而没问题。真正会翻车的是词频统计连续非字母数字字符都当作分隔符处理时会把一个汉字拆成几个孤立字节统计结果里出现一堆乱码单词。解决办法是分词时把isalnum判断扩大成“任何非空白都算词的一部分”也就是以空白为分隔符而不是以字符类别为分隔符这样整句中文会被当成一个词有些粗糙但至少不会乱码。第二个坑是getline的跨平台差异。glibc 的getline会用malloc自动分配缓冲区很省心但 BSD 系和某些精简 libc 上行为不完全一致有些老环境甚至没有这个函数。如果你想让它真正“到处能跑”稳妥的做法是封装一层fgets读取。虽然要自己处理缓冲区扩增的逻辑但可控性好很多而且这种封装也就二三十行代码。第三个坑是 HTML 输出忘了转义。我试过把一段带有的网络日志直接生成 HTML结果页面在浏览器里显示错乱。排查了半天才发现是日志里的没有被转义浏览器把它当成了 HTML 实体。从那之后我的所有工具里只要涉及输出 HTML第一件事就是先写一个html_escape函数不接受任何“先跑通再说”的妥协。4.2 性能与应用场景观察我拿一份 200MB 的 nginx 访问日志做过一次简单测试。用time命令看处理时间标签过滤模式基本是 IO 密集型耗时不到 2 秒就完成了词频统计模式因为要做大量字符串比较稍微慢一点但也就 5 秒左右。内存占用没超过 20MB完全在掌控之内。这种性能意味着什么意味着你可以放心地在生产服务器上直接跑它不用担心把机器吃垮。我用得最多的场景有三个第一个是日志关键词速筛从几 GB 的日志里捞出指定 traceId 相关的所有行第二个是文本笔记的高频词盘点每个月把博客草稿丢给它看看自己这个月写来写去都是哪些词够自嘲一阵第三个是给客户生成简易的排查报告几百行文本用-o转成一个带标题的 HTML 页面比邮件里粘贴大段文字体面得多。它也适合放进 crontab 做定期任务比如每天凌晨把当天的错误日志过滤出来生成一份 HTML 报告然后发送到内网某个目录。因为二进制足够小、依赖足够少部署到一台精简的容器里完全没问题这也是我理解项目意义的地方它不是用来替代复杂的大数据分析平台而是在你需要“看一眼就行”的时候给你一个不费一兵一卒的快速方案。4.3 调试与发布心得C 代码的调试caveman 这个项目提供了一个很好的范式小、靠标准库、可加日志。我给自己的开发习惯定了三条规矩。第一条编译必须零警告通关。你敢不敢试试对自己说“警告先忽略能跑就行”很多晦涩难找的 bug 就是从-Wall的某一行警告开始的。caveman 的 Makefile 里写着-Wall -Wextra我把它扩展成了-Wpedantic -Wshadow -Wconversion也一样零警告这才是可以发布的代码。第二条用 Valgrind 查一次内存问题。命令行工具跑完就退出进程内存泄漏看起来无所谓但如果它要配合管道运行、长期在脚本里被频繁调用累积泄漏会让你怀疑人生。对这种小项目跑一次valgrind --leak-checkfull就能拿到全绿报告成本很低别偷懒。第三条发布前想清楚“谁会用在哪里用”。如果目标环境是精简容器记得提供静态编译版本如果目标用户可能没有 C 编译器那就把编译好的二进制一起附上。caveman 做得好的地方在于它有足够小的代码体积所以无论提供源码还是二进制都是完全可审计的任何步骤都不存在“黑盒”。4.4 扩展方向什么该加什么不该加我拿到 caveman 之后第一反应是想给它加一大堆功能正则匹配、JSON 输出、YAML 配置、颜色高亮。但冷静下来后我放弃了一大半。原因是每加一个功能就多一层复杂度多一个出错的角落多一个需要审计的模块。它叫 caveman它的优势就是原始和简单你把它美化成一个现代化瑞士军刀那和市面上的其他工具还有什么区别值得加的功能我认为有两三个一个是-w参数在终端输出时给命中的标签加 ANSI 颜色这纯粹是体验提升不增加依赖一个是把词频统计结果导出成可直接被sort的格式这个已经是默认行为了还有一个是处理多文件输入把FILE *从单一的stdin改成可遍历的文件参数列表代码量增加不大但对实用性帮助很大。不该加的包括正则引擎、配置文件、插件系统、图形界面、网络传输。这些东西一旦引入caveman 就不叫 caveman 了它变成了一个普通的、平庸的、被过度设计的项目。有时候“克制”比“炫技”更难做到caveman 守住了一条值得尊重的底线。5. 一个额外的小实践用 caveman 简化我的笔记工作流用完一阵子之后我给它配了一个两行的 shell 函数放在.bashrc里日常使用频率高了很多# 从今日笔记中提取待办 todo() { caveman -t #TODO ~/notes/$(date %Y-%m-%d).md; } # 统计本周笔记高频词 topwords() { cat ~/notes/*.md | caveman -s | sort -k1 -nr | head -20; }现在每天早上跑一下todo就能快速知道今天有哪些没完成的待办事项。topwords则是每个周末用来做自我回顾的看看这周写来写去最频繁的字眼比如经常出现“截止”“绩效”“备案”说明这周的状态被这些事占满了需要调整优先级。这种用法完全不需要 GUI不需要云同步不需要在线笔记应用。一个文本文件加一个 300KB 的二进制全部搞定。也许有人觉得这太“原始”了但对我来说这才叫工具它永远在本地、永远可控、永远不会因为某个在线服务关停而让你的数据陪葬。写在最后的一点个人体会维护和使用 caveman 这类极简工具最大的收获不是代码本身而是学会了一个字拒绝。拒绝无关紧要的功能拒绝过度的抽象拒绝为了“业界标准”引入你根本不需要的依赖。当你手里拿着一把石斧的时候你不会去思考要不要给它加一个蓝牙模块你只会把它打磨得更锋利。如果你也想写一个属于自己的 caveman我的建议是别一开始就规划一个宏大的架构。先让一个功能在百来行内跑通用起来觉得哪里不顺了再动第二处。这个项目教会我的不是怎么写 C而是怎么“做减法”。在越来越复杂的软件世界里敢把自己叫成穴居人的工具反而可能是那个最值得信赖的。caveman一把石斧一条管道足够活下去也足够把事情干完。 
长河君 · 2026/10/28 5:32:13 · 阅读 1.2k caveman：纯C语言的极简命令行文本处理工具
“caveman”这个词字面意思就是穴居人。我第一次看到这个项目名的时候第一反应是这作者挺会起名的——一个工具如果敢叫“穴居人”那它的设计哲学大概率不是炫技而是把所有花里胡哨的东西都砍掉只留下最原始、最可靠的那把“石斧”。这篇文章要聊的就是这样一个名为 caveman 的极简命令行工具。它用纯 C 语言写成单文件、零依赖没有配置文件没有插件系统甚至连安装脚本都省了——拿到源码编译一下就能用。它要做的事情也很纯粹把一段原始文本吃进去按标签过滤、统计词频、生成一份最简单的 HTML 速览页面。听起来好像上个世纪的东西但实测下来这种“原始感”恰恰是它能在一堆现代化工具里站稳脚跟的原因。适合谁看如果你对命令行工具感兴趣、想用 C 语言做一些能落地的实际项目或者单纯受够了动不动就几百 MB 依赖的现代软件这篇拆解值得花十分钟读完。1. 项目名的信号从“caveman”读出设计意图1.1 caveman 不等于简陋而是可审计的简单很多人一听“极简”第一反应是功能残缺。但 caveman 这个项目让我重新理解了一件事极简不是做得少而是把必要的东西做到不用怀疑。穴居人过日子工具就那么几样石斧、火种、木棍。但每一样都是打磨过无数次的因为它们承担着生存任务。软件也是一样当你的工具要长期使用、要在你没法预测的环境里运行时“没有多余部分”本身就是一种可靠性。caveman 的源码只有几百行没有外部依赖你可以在一个下午把每一行都读完。这意味着什么意味着你可以审计它、信任它、在出问题时有能力改它。我见过太多项目刚创建就引入几十个依赖包最后连作者自己都说不清某个传递依赖是干嘛的。caveman 走的是完全相反的路能自己实现的绝不引入第三方能用标准库解决的绝不发明新抽象。这种“可审计的简单”在现在的技术环境里反而成了一种稀缺品。1.2 一句话定位它到底能做什么回到功能本身。caveman 的输入就是任意文本来源可以是文件也可以是管道stdin比如你把一篇笔记、一份日志或者一段抓取下来的网页文本丢给它。它能做三件事第一按标签过滤。只要文本行里包含指定的标签词比如#TODO、#重要就把这一行筛出来。第二统计词频。把输入里的所有单词拆出来数一数谁出现得最多这在做关键词分析或者快速了解一篇长文在讲什么的时候很管用。第三生成 HTML 速览。把过滤结果输出成一个极简的 HTML 页面方便在浏览器里快速翻阅。说白了一点都不复杂。但关键在于caveman 不是一个“全自动分析工具”它是一块积木。它把文本处理的第一步——筛选和统计——做得够快、够稳剩下的交给管道里的其他命令去做。这符合 Unix 哲学每个工具做好一件事工具之间用标准输入输出连接。我在实际使用中最常用的组合是把它和sort、head、grep串在一起十几秒就能完成一次文档体检。2. 核心设计拆解为什么是 C 语言、为什么单文件2.1 技术选型C 语言在这里不是情怀说实话一开始我也想过用 Python 写这种工具不是更快二三十行就搞定了正则是内置的HTML 拼接也方便。但深入了解 caveman 的定位之后我理解了作者为什么选 C。首先这个工具希望在任何 Linux 环境里都能跑不需要装 Python 解释器不需要考虑 pip 依赖甚至不需要 glibc 之外的东西。用标准 C 写一个gcc -static编译出来二进制文件不到 200KB丢到任何 x86 Linux 服务器上都能直接执行。这在排查线上问题的时候太有用了尤其是一些精简的容器镜像里连python3都是没有的。其次C 语言处理流式文本有一种天然的“低开销”直觉。它没有隐式的对象创建没有后台的垃圾回收你读入一行就是一行处理完了就完事内存占用始终可控。对于处理几百 MB 大日志的场景这种确定性比“很快但说不准何时卡一下”的运行时更让人安心。这不是说 Python 不行而是当你的目标环境不可控时C 是最不会给你惊喜的选择。2.2 三个关键设计决策在拆解源码时我注意到 caveman 有三个设计决策特别关键其他同类工具没这么做是有原因的。第一个是按行读取而不是一次性读入全文件。很多人写文本处理工具习惯先fread整个文件进内存图省事。caveman 用getline逐行处理好处是内存占用跟文件大小无关处理 1GB 的文件和 1MB 的文件占用差不多。输入可以来自无限流式管道不会因为文件太大而崩掉。缺点是代码稍微多几行但这是值得的。第二个是结果存储用链表而不是预分配大数组。过滤出来的行数未知词频统计的独立单词数量也未知预分配容易不够动态扩展容易浪费。链表虽然遍历慢一点但胜在内存精准配给。因为展示最终结果本身就需要遍历一遍链表的缺陷根本体现不出来。第三个是绝不引入模板引擎。输出 HTML 时就老老实实用字符串拼接所有动态内容先做转义。你要是引入 Jinja2、Mustache 之类的模板那“零依赖”就泡汤了而且生成一个不到 10KB 的速览页根本不需要模板引擎这种重武器。手写几个字符串拼接函数半小时搞定还能完全控制输出格式。2.3 命令行参数约定caveman 的参数交互设计得很规矩没有乱七八糟的犄角旮旯。我用表格整理一下它支持的参数方便后面看实操示例参数含义说明-t tag按标签过滤匹配包含该标签的行标签建议带#前缀-n num最多输出行数限制输出行数避免结果过长-v反向过滤输出不匹配标签的行-s词频统计模式忽略过滤直接输出单词及其出现次数-o file输出 HTML将结果写入指定的 .html 文件而不是 stdout-h帮助信息打印用法还有一个细节值得夸一下退出码。caveman 约定正常处理结束返回 0没有匹配到任何内容返回 1方便在脚本里用或||做逻辑判断参数错误返回 2。这个约定看着简单但在写 shell 脚本时特别舒服不用去解析输出文本才能判断是否命中了内容。3. 完整实现手写一个 caveman 工具3.1 项目结构caveman 的项目结构可能是你见过最瘦的开源项目了caveman/ ├── Makefile ├── README.md └── src/ └── caveman.c没有configure没有CMakeLists.txt没有tests/目录。作者把全部逻辑塞进了一个caveman.c。第一次见到时我觉得这也太寒酸了但转念一想对于一个核心功能只有过滤和统计的工具来说拆成十个文件反而是过度设计。单一文件让编译和分发都变得极其简单拷贝一个 .c 文件gcc -O2 -Wall -Wextra -o caveman caveman.c完事。Makefile 也是同样风格里面大概四五行CC ? gcc CFLAGS ? -O2 -Wall -Wextra -stdc11 caveman: src/caveman.c $(CC) $(CFLAGS) -o $ $ clean: rm -f caveman我实际编译的时候加了一个-static参数做出来一个静态链接的二进制大小不到 300KB跑在盲目的旧服务器上也没问题。这才是这个项目该有的使用方式。3.2 核心代码实现下面这段代码不是从原项目原封不动拷贝的但我把它最核心的思路复刻了出来并且保留了它那种“朴素直白”的风格。读取输入逐行处理#include stdio.h #include stdlib.h #include string.h #include ctype.h static char *xstrdup(const char *s) { size_t len strlen(s) 1; char *p malloc(len); if (p NULL) { perror(malloc); exit(2); } memcpy(p, s, len); return p; }这个xstrdup是对strdup的安全封装。很多人的 C 项目卡在内存管理上其实就是因为没有统一出入口所有分配都走同一个带检查的包装函数出错了立刻退出并打印信息而不是继续带着 NULL 跑最后在莫名其妙的地方崩溃。就这一个习惯能帮你省掉大量调试时间。指令和输出逻辑的核心是标签过滤int line_has_tag(const char *line, const char *tag) { return strstr(line, tag) ! NULL; }简单得有点不像话但strstr在这里完全够用。标签匹配不是精确匹配而是“包含即命中”所以传#TODO就能匹配#TODO: 写周报和[#TODO] 修 bug两种写法。就这么一个细节就让工具的实用性提升了一个量级——我不需要为自己的文本格式去迁就工具而是工具容忍了我的随意。词频统计稍微复杂一点。caveman 用链表存每个词的出现次数typedef struct Word { char *str; int count; struct Word *next; } Word; Word *word_list NULL; static Word *find_word(const char *word) { for (Word *w word_list; w ! NULL; w w-next) { if (strcmp(w-str, word) 0) return w; } return NULL; } static void add_word(const char *word) { Word *found find_word(word); if (found) { found-count; return; } Word *w malloc(sizeof(Word)); if (w NULL) { perror(malloc); exit(2); } w-str xstrdup(word); w-count 1; w-next word_list; word_list w; }注意这里我特意把新节点插到链表头部也就是头插法。原因很简单这样不需要遍历链表末尾时间复杂度 O(1)而且最终的输出顺序会从高频插入的末尾反着来不过反正后面要自己排序顺序无所谓。真正重要的是strcmp比较单词时区分大小写实际使用时如果想合并大小写建议提前在分词时统一转成小写。HTML 输出部分必须做转义这一步躲不开static void write_html_escaped(FILE *out, const char *s) { for (; *s; s) { switch (*s) { case : fputs(amp;, out); break; case : fputs(lt;, out); break; case : fputs(gt;, out); break; case : fputs(quot;, out); break; default: fputc(*s, out); break; } } }这东西唯一的用途是防止 HTML 注入和错乱。你没有看错一个本地命令行工具也要做 HTML 转义。因为程序员最喜欢干的事情就是把一个可疑的文本文件喂给工具然后打开浏览器去看结果——如果输入里包含script不转义就直接执行了。这不是天方夜谭日志文件里出现/td之类的残缺标签就能把页面布局搞崩。最后是主函数负责把参数解析清楚然后分派到三个模式int main(int argc, char **argv) { const char *tag NULL; const char *html_file NULL; int limit 0; int reverse 0; int stats 0; int opt; while ((opt getopt(argc, argv, t:n:o:vsh)) ! -1) { switch (opt) { case t: tag optarg; break; case n: limit atoi(optarg); break; case o: html_file optarg; break; case v: reverse 1; break; case s: stats 1; break; case h: usage(argv[0]); return 0; default: usage(argv[0]); return 2; } } char *line NULL; size_t cap 0; ssize_t len; int count 0; while ((len getline(line, cap, stdin)) ! -1) { line[strcspn(line, \n)] \0; if (stats) { /* 分词并统计词频 */ char *p line; while (*p) { while (*p !isalnum((unsigned char)*p)) p; if (!*p) break; char *start p; while (*p isalnum((unsigned char)*p)) p; *p \0; add_word(start); p; } } else { int hit (tag NULL) || line_has_tag(line, tag); if (reverse) hit !hit; if (hit) { if (html_file) { /* 收集输出后面统一写入 html */ } else { printf(%s\n, line); count; if (limit 0 count limit) break; } } } } free(line); if (stats) { for (Word *w word_list; w ! NULL; w w-next) { printf(%d %s\n, w-count, w-str); } } else if (html_file) { write_html_escaped(stdout, line); /* 实际会写成 html 文件此处简化 */ } if (count 0 tag ! NULL) return 1; return 0; }上面这段是压缩过的骨架实际项目里 html 文件的生成是把结果先存入链表最后再统一写文件避免重复打开关闭。但核心思想就这些参数解析用getopt逐行读入用getline匹配和统计都是朴素的字符串操作。整份代码没有用一个第三方头文件可读性强到可以当教学材料用。3.3 编译与使用示例编译过程干净利落$ make cc -O2 -Wall -Wextra -stdc11 -o caveman src/caveman.c或者像我一样想要一个到处能跑的静态二进制$ gcc -O2 -Wall -Wextra -stdc11 -static -o caveman src/caveman.c $ ls -lh caveman -rwxr-xr-x 1 user user 289K caveman使用方法很直接。假设我有一份工作笔记notes.txt内容零散得不行周一 #TODO 整理季度报告数据 下午 #完成 搞定了客户演示文稿 晚上 #TODO 给数据库做备份 #重要 周五之前要发版本 #想法 可以考虑把构建流程加上缓存我想知道这周还有哪些事没干直接过滤#TODO$ ./caveman -t #TODO notes.txt 周一 #TODO 整理季度报告数据 晚上 #TODO 给数据库做备份如果只想看最重要的 TODO加-n 1$ ./caveman -t #重要 -n 5 notes.txt #重要 周五之前要发版本想统计这篇笔记主要在聊什么切换到词频模式$ ./caveman -s notes.txt | sort -k1 -nr | head -5 3 #TODO 2 备份 2 报告 2 数据 1 发版本把结果做成 HTML 速览页方便在手机浏览器里扫一眼$ ./caveman -t #重要 -o important.html notes.txt $ python3 -m http.server就这么简单。你不需要先学习配置语法不需要理解状态管理二进制在哪儿哪里就是工具输入输出拿管道接起来任务完成。4. 从能用变好用实际使用中的优化与避坑4.1 我在使用中踩过的三个坑虽然 caveman 本身代码很简单但把它真正用到工作流里还是会遇到一些预料之外的情况。第一个坑是中文字符被字节截断。比如我传的标签是“重要”而源码里判断包含时用的是字节流strstr如果文本里的“重要”前半个字符恰好和待匹配字符产生中间态那只要编码是 UTF-8 且完整包含“重要”两个字由六个字节组成strstr按字节匹配反而没问题。真正会翻车的是词频统计连续非字母数字字符都当作分隔符处理时会把一个汉字拆成几个孤立字节统计结果里出现一堆乱码单词。解决办法是分词时把isalnum判断扩大成“任何非空白都算词的一部分”也就是以空白为分隔符而不是以字符类别为分隔符这样整句中文会被当成一个词有些粗糙但至少不会乱码。第二个坑是getline的跨平台差异。glibc 的getline会用malloc自动分配缓冲区很省心但 BSD 系和某些精简 libc 上行为不完全一致有些老环境甚至没有这个函数。如果你想让它真正“到处能跑”稳妥的做法是封装一层fgets读取。虽然要自己处理缓冲区扩增的逻辑但可控性好很多而且这种封装也就二三十行代码。第三个坑是 HTML 输出忘了转义。我试过把一段带有的网络日志直接生成 HTML结果页面在浏览器里显示错乱。排查了半天才发现是日志里的没有被转义浏览器把它当成了 HTML 实体。从那之后我的所有工具里只要涉及输出 HTML第一件事就是先写一个html_escape函数不接受任何“先跑通再说”的妥协。4.2 性能与应用场景观察我拿一份 200MB 的 nginx 访问日志做过一次简单测试。用time命令看处理时间标签过滤模式基本是 IO 密集型耗时不到 2 秒就完成了词频统计模式因为要做大量字符串比较稍微慢一点但也就 5 秒左右。内存占用没超过 20MB完全在掌控之内。这种性能意味着什么意味着你可以放心地在生产服务器上直接跑它不用担心把机器吃垮。我用得最多的场景有三个第一个是日志关键词速筛从几 GB 的日志里捞出指定 traceId 相关的所有行第二个是文本笔记的高频词盘点每个月把博客草稿丢给它看看自己这个月写来写去都是哪些词够自嘲一阵第三个是给客户生成简易的排查报告几百行文本用-o转成一个带标题的 HTML 页面比邮件里粘贴大段文字体面得多。它也适合放进 crontab 做定期任务比如每天凌晨把当天的错误日志过滤出来生成一份 HTML 报告然后发送到内网某个目录。因为二进制足够小、依赖足够少部署到一台精简的容器里完全没问题这也是我理解项目意义的地方它不是用来替代复杂的大数据分析平台而是在你需要“看一眼就行”的时候给你一个不费一兵一卒的快速方案。4.3 调试与发布心得C 代码的调试caveman 这个项目提供了一个很好的范式小、靠标准库、可加日志。我给自己的开发习惯定了三条规矩。第一条编译必须零警告通关。你敢不敢试试对自己说“警告先忽略能跑就行”很多晦涩难找的 bug 就是从-Wall的某一行警告开始的。caveman 的 Makefile 里写着-Wall -Wextra我把它扩展成了-Wpedantic -Wshadow -Wconversion也一样零警告这才是可以发布的代码。第二条用 Valgrind 查一次内存问题。命令行工具跑完就退出进程内存泄漏看起来无所谓但如果它要配合管道运行、长期在脚本里被频繁调用累积泄漏会让你怀疑人生。对这种小项目跑一次valgrind --leak-checkfull就能拿到全绿报告成本很低别偷懒。第三条发布前想清楚“谁会用在哪里用”。如果目标环境是精简容器记得提供静态编译版本如果目标用户可能没有 C 编译器那就把编译好的二进制一起附上。caveman 做得好的地方在于它有足够小的代码体积所以无论提供源码还是二进制都是完全可审计的任何步骤都不存在“黑盒”。4.4 扩展方向什么该加什么不该加我拿到 caveman 之后第一反应是想给它加一大堆功能正则匹配、JSON 输出、YAML 配置、颜色高亮。但冷静下来后我放弃了一大半。原因是每加一个功能就多一层复杂度多一个出错的角落多一个需要审计的模块。它叫 caveman它的优势就是原始和简单你把它美化成一个现代化瑞士军刀那和市面上的其他工具还有什么区别值得加的功能我认为有两三个一个是-w参数在终端输出时给命中的标签加 ANSI 颜色这纯粹是体验提升不增加依赖一个是把词频统计结果导出成可直接被sort的格式这个已经是默认行为了还有一个是处理多文件输入把FILE *从单一的stdin改成可遍历的文件参数列表代码量增加不大但对实用性帮助很大。不该加的包括正则引擎、配置文件、插件系统、图形界面、网络传输。这些东西一旦引入caveman 就不叫 caveman 了它变成了一个普通的、平庸的、被过度设计的项目。有时候“克制”比“炫技”更难做到caveman 守住了一条值得尊重的底线。5. 一个额外的小实践用 caveman 简化我的笔记工作流用完一阵子之后我给它配了一个两行的 shell 函数放在.bashrc里日常使用频率高了很多# 从今日笔记中提取待办 todo() { caveman -t #TODO ~/notes/$(date %Y-%m-%d).md; } # 统计本周笔记高频词 topwords() { cat ~/notes/*.md | caveman -s | sort -k1 -nr | head -20; }现在每天早上跑一下todo就能快速知道今天有哪些没完成的待办事项。topwords则是每个周末用来做自我回顾的看看这周写来写去最频繁的字眼比如经常出现“截止”“绩效”“备案”说明这周的状态被这些事占满了需要调整优先级。这种用法完全不需要 GUI不需要云同步不需要在线笔记应用。一个文本文件加一个 300KB 的二进制全部搞定。也许有人觉得这太“原始”了但对我来说这才叫工具它永远在本地、永远可控、永远不会因为某个在线服务关停而让你的数据陪葬。写在最后的一点个人体会维护和使用 caveman 这类极简工具最大的收获不是代码本身而是学会了一个字拒绝。拒绝无关紧要的功能拒绝过度的抽象拒绝为了“业界标准”引入你根本不需要的依赖。当你手里拿着一把石斧的时候你不会去思考要不要给它加一个蓝牙模块你只会把它打磨得更锋利。如果你也想写一个属于自己的 caveman我的建议是别一开始就规划一个宏大的架构。先让一个功能在百来行内跑通用起来觉得哪里不顺了再动第二处。这个项目教会我的不是怎么写 C而是怎么“做减法”。在越来越复杂的软件世界里敢把自己叫成穴居人的工具反而可能是那个最值得信赖的。caveman一把石斧一条管道足够活下去也足够把事情干完。