1. 项目整体设计与命名哲学1.1 项目代号从哪来为什么叫caveman做这个小项目的时候我花在起名字上的时间比预想的多。最初想了十几个候选代号什么NoteHubTinyMind之类看起来都很现代、很互联网。但产品形态越清晰这些名字就越不对劲。最后动手做第一版原型那天我在纸上画了一张使用流程图整张图只有三个箭头存进去、找出来、结束。看着这张图脑子里突然蹦出一个词caveman——穴居人原始人。这名字一下就对了。caveman这个词用在软件项目上通常不是什么好话。它经常被人用来形容代码质量差、只会复制粘贴、不懂设计模式的开发者。但我觉得原始人背后其实藏着一个更值得琢磨的意象原始人没有那么多工具他手里只有一块石头、一根木棍但他能靠这两样东西活下来。我的项目就是想做成这样的东西——只保留最必要的功能每个功能都硬得能锤碎核桃其他乱七八糟的全砍掉。这个项目不是某个大厂出的产品也不是要跟别人竞争的框架它是我给自己写的极简命令行工具集代号就叫caveman。核心价值一句话概括用最少的外部依赖、最少的操作步骤完成个人知识碎片的收集、定位与回顾并且保证五年后这台机器上的文件还能打开、还能用、还能改。适合谁参考两类人。第一类是日常需要处理大量笔记、书签、待办信息但已经厌倦了臃肿笔记软件的人第二类是正在做自己的小工具、小脚本但控制不好功能边界的开发者。这个项目里我走过的弯路、砍功能的过程会比最终代码本身更有参考价值。1.2 三个设计原则用完即走、单文件交付、老机器友好任何软件在动手写第一行代码之前设计原则都是最重要的东西。没有原则功能做三个月能发散出四十个最后还是个四不像。caveman在设计之初就定了三条硬规矩后续所有功能决策都用这三条来当尺子。第一条用完即走。工具不应该获得用户的注意力它应该被使用然后被遗忘。搜索一个东西敲完命令三秒钟出结果看一眼关掉该干嘛干嘛。不做常驻后台不做开机自启不做消息推送。很多所谓效率工具本质上是在培养用户的依赖习惯让你每天打开它、花时间在里面整理这种工具做得再精致也是时间黑洞。第二条单文件交付。整个工具的代码打包成一个可执行文件不依赖安装过程不需要配置环境变量不需要数据库服务。拷贝到任何一台电脑上双击就能跑。为什么这么较真因为我被各种软件的环境问题折磨过太多次。Python升级了某个库不兼容了Node版本更新后依赖树崩了CentOS和Ubuntu的包管理行为不一样了这些破事在工具层面统统不应该出现。单文件交付意味着没有任何安装环节也就没有环境问题可言。第三条老机器友好。工具本身要能在五年前的低配机器上流畅运行。这是一条自动筛选原则——它逼着开发者跟那些花里胡哨的功能说再见。富文本编辑器砍掉。实时协作砍掉。AI自动摘要砍掉。这些功能不是不好而是它们天生跟轻量打架。一条命令、一个文本检索、一个结果列表这套东西用十年前的技术栈都能写得飞快。三条原则定了之后我意识到一件有意思的事很多时候你以为你在做软件设计其实你在做减法练习。caveman的整个开发过程有一半时间花在说服自己这个功能真的不能要上面。1.3 极简不等于简陋两个概念的边界这里必须说清楚一个误会极简不代表简陋。没做过减法的人容易把极简当成偷工减料实际完全是两回事。极简是功能经过筛选每个被保留下来的功能都打磨到足够好简陋是功能没想清楚该做的事没做到位。我用一个对比表格说明区别评价维度极简caveman的目标简陋必须避免的陷阱功能数量少而精每个功能解决一个明确问题少但残缺每个功能解决一半问题交互成本符合直觉不需要读文档就能用操作路径不连续用到一半卡住边界情况报错信息清晰知道怎么修复静默失败或抛出来自底层库的报错扩展能力留有合理的扩展接口结构写死想加功能只能推倒重来维护成本零依赖或极少依赖升级风险低依赖隐晦的全局状态升级随时炸caveman的功能数量控制在五个以内但每个功能都覆盖完整的使用路径。比如保存这个功能看起来只是往数据库里插一行记录实际上包含了去重、标签解析、时间戳记录、格式校验四件事。功能可以少但每个功能不能有短板。这一点想明白了后面所有的技术选型就都顺了。2. 核心功能拆解与关键技术选型2.1 功能范围定义做什么与不做什么动手之前我先列了两张清单。第一张写这个工具要做什么第二张写这个工具坚决不做什么。两张清单一样重要甚至后者更重要。要做的有五件事记录接受纯文本输入自动附加时间戳和来源标签。检索按关键词、标签、日期范围三种方式定位内容。回顾随机或按标签抽取一条历史记录用来做记忆强化。导出将全部记录导出为单个HTML文件方便分享和长期保存。自检检查数据库完整性修复异常索引。坚决不做的有五件事不做云同步、不做富文本格式、不做待办状态管理、不做移动端、不做多用户权限。每一项都有理由。比如不做待办状态管理因为收藏的内容和要做的事情是两种完全不同的心智模型混在一起会让工具的性质变得模糊。caveman的定位是收件箱不是任务管理系统。这个功能范围花了很久才确定下来。一开始我也犯过老毛病想着加上任务提醒该多好加上阅读进度追踪该多好加上浏览器插件又该多好。直到我承认一个事实我需要的不是更多的入口而是一个足够干净的出口——信息进来之后能快速被找到。2.2 存储方案为什么是SQLite而不是JSON或MySQL存储层是整个工具的心脏这个选择必须谨慎。我对比了三个方案。方案AJSON文件。最简单人类可读用一个列表存数据追加就往数组里push一条。缺点是数据量上来之后每次都要全量读写一百条记录无所谓一万条记录就开始有明显的卡顿感。更麻烦的是并发写入会互相覆盖虽然命令行工具基本不会并发但这个风险始终让人不踏实。方案BMySQL/PostgreSQL。功能强大支持完善可变现的搜索索引方案一大堆。但问题是这个工具是单机命令行的引入一个数据库服务意味着使用者必须先装MySQL还要处理监听端口、账号权限、字符集配置这些问题。这跟单文件交付的原则正面冲突。方案CSQLite。完美匹配需求。它是一个嵌入式关系型数据库数据存放在单个文件里不需要任何服务端进程Python标准库原生支持不需要安装第三方包支持SQL查询所以检索能力远超JSON方案。选SQLite还有一个隐性好处它的数据文件本身就是跨平台的。Linux环境下生成的数据库文件拷到Windows上工具一样能读。后期如果caveman要继续做导出、统计、批量操作SQL能做的事比JSON多得多。SQLite官方文档第一句话说大多数情况下SQLite就是最好的方案——在单机命令行工具这个领域这句话不是广告是事实。实际测试了一组数据一万条记录全量检索的时间在30毫秒级别添加一条记录在5毫秒级别的响应完全感知不到延迟。这个测试结果当时就坚定了用SQLite的信心。2.3 交互方式设计命令行的人机工程学caveman是命令行工具命令行的设计直接决定用户是用它还是放弃它。我参考了Git和Taskwarrior的设计经验把交互规则定成三条第一动词开头。所有操作都是动作对象的结构caveman add 这是一条记录、caveman find 关键词、caveman tags。从输入到执行不需要思考动词即意图。第二输入最少。有默认值就不让用户填参有自动检测就不让用户指定。比如添加记录时默认使用当前时间用户不需要额外输入现在这个参数搜索时默认搜索所有字段用户不需要指定搜标题还是搜正文。第三输出可读。结果列表使用对齐的表格高亮命中的关键词末尾统计显示结果数量。错误信息必须说明发生了什么建议怎么做。这里有一个设计细节分享一下。find命令的模糊匹配逻辑我一开始打算让用户手动指定匹配模式比如前缀匹配后缀匹配包含匹配。但测试了两天后发现这种灵活性根本没人用真实的使用场景里用户想搜react就会输入react想搜docker就输入docker直接把输入当子串去匹配就够了。于是我把所有匹配统一成全字段子串匹配用户侧少了一个选择题代码侧也少了一个分支判断。好的交互设计是把用户需要做的决定数量降下来。2.4 技术栈选型零第三方依赖的底气技术栈的选择跟整个项目的调性高度相关。caveman最终用的是Python标准库加SQLite驱动没有安装任何第三方依赖。Python的sqlite3模块是内置于标准库的argparse管命令行参数解析datetime管时间处理这三个模块加在一起就覆盖了全部需求。为什么不引入更现代的工具比如用Click做命令行框架、用SQLAlchemy做ORM、用Rich做终端美化这些库确实能让代码更好看但代价是安装体积、升级风险、兼容性维护三座大山。一个只有几百行代码的小工具引入SQLAlchemy之后光ORM的映射配置就要写几十行属于典型的杀鸡用牛刀。零依赖还有一个极端好处这个工具永远不会遇到依赖冲突的问题。无论运行环境里的其他软件装了什么、卸载了什么、升级了什么caveman的行为都不变。这种确定感在写工具类软件时非常重要——工具的本质是提高确定性如果工具自身都不确定那就没有存在的意义了。3. 实操过程与核心环节实现3.1 从仓库到首版开发环境的搭建与目录结构实际操作层面我建议从一张干净的桌面开始。不要在已经跑了几十个服务的机器上开发这类工具环境越干净后期打包出来的产物越可靠。我在开发机上做的事很简单确认Python版本是3.8以上因为我要用subprocess.run的新特性确认文件系统支持SQLite的WAL模式现在基本都支持然后建一个目录开始写。目录结构如下caveman/ ├── caveman.py # 主程序单文件 ├── tests/ │ ├── test_add.py # 添加功能的单元测试 │ ├── test_find.py # 搜索功能的单元测试 │ └── test_export.py # 导出功能的单元测试 ├── docs/ │ └── usage.md # 使用说明 └── README.md我故意把tests目录放在项目根部而不是更深的层级是为了让一个从未接触过这个项目的人在30秒内看到这里有测试这个事实。测试必须被看到藏在src/tests/tests/里的测试等于不存在。开发顺序上我先把数据库层写出来——也就是连接、建表、插入、查询这四个基础操作。这四件事是地基地基落定之后上面的命令解析、输出格式化都只是拿来填墙的砖。想验证数据库层是否可靠最简单的办法是跑一组边界测试插入空字符串会怎样插入超长文本会怎样搜索一个不存在的词会怎样删除空数据库会怎样。这组测试跑完数据库层的稳定性心里就有底了。3.2 数据库设计与建表语句数据库设计是caveman里最需要认真对待的一环。表结构如果设计得不好后面加功能必然要重构。caveman的库表很简单总共两张表记录表和标签表。记录表表名叫entriesCREATE TABLE IF NOT EXISTS entries ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, source TEXT DEFAULT manual, created_at TEXT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_entries_created ON entries(created_at);标签表表名叫tagsCREATE TABLE IF NOT EXISTS tags ( id INTEGER PRIMARY KEY AUTOINCREMENT, entry_id INTEGER NOT NULL, tag TEXT NOT NULL, FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE ); CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);有两个设计考量值得说明。第一标签单独建表而不是在entries表里加一个tags字段存逗号分隔的字符串。这是为了支持按标签反查记录。如果是逗号分隔查询所有带python标签的记录就得先把每行取出来再在应用层做字符串切割效率低且代码丑。用关联表之后一句SQL就能解决索引还能加速。第二created_at存的是ISO 8601格式的字符串而不是Unix时间戳整数。ISO格式有个好处它对人类可读打开数据库文件直接用肉眼就能看到这条记录是什么时候存的。排序上ISO字符串按字典序就是时间序不会出现大小比较的问题。这种字符串格式的缺点是需要转格式才能做复杂的日期运算但caveman里日期运算很轻量两条SQL就能覆盖完全够用。建表语句在程序启动时执行一次IF NOT EXISTS保证幂等性无论执行多少次都不会报错损坏数据。这个习惯在开发工具时值得保持所有初始化操作都应该幂等。用户可能在任何奇怪的时机误点运行程序不应该因为重复初始化而炸掉。3.3 核心命令的实现与参数设计接下来是三个核心命令的实现。第一个是add命令它负责把一条记录写入数据库import argparse import sqlite3 import sys from datetime import datetime DB_PATH ~/.caveman.db def cmd_add(args): content args.content if not content or len(content) 2: print(错误内容至少需要2个字符, filesys.stderr) return 1 conn sqlite3.connect(DB_PATH) cursor conn.cursor() now datetime.now().isoformat(timespecseconds) cursor.execute( INSERT INTO entries (content, source, created_at) VALUES (?, ?, ?), (content, args.source, now), ) entry_id cursor.lastrowid for tag in args.tags: cursor.execute( INSERT INTO tags (entry_id, tag) VALUES (?, ?), (entry_id, tag), ) conn.commit() conn.close() print(f已保存ID{entry_id}) return 0这里用了?占位符的参数化查询而不是字符串拼接SQL。这个习惯必须养成字符串拼接SQL不仅是安全漏洞还会在内容里有引号时直接让程序崩溃。参数化查询同时解决了这两个问题。add命令还设计了--source和--tag两个可选参数。--source用来标记来源比如memo表示手机备忘录转存book表示读书笔记idea表示随手灵感。--tag可以重复传递给一条记录加多个标签。这些元数据在后续的筛选检索中会发挥大作用。第二个核心命令是finddef cmd_find(args): conn sqlite3.connect(DB_PATH) cursor conn.cursor() keyword args.keyword like f%{keyword}% query SELECT e.id, e.content, e.created_at, GROUP_CONCAT(t.tag, ,) as tag_list FROM entries e LEFT JOIN tags t ON t.entry_id e.id WHERE e.content LIKE ? OR e.source LIKE ? OR t.tag LIKE ? GROUP BY e.id ORDER BY e.created_at DESC LIMIT ? cursor.execute(query, (like, like, like, args.limit)) rows cursor.fetchall() for row in rows: print(f[{row[2]}] #{row[0]}) print(f {row[1]}) if row[3]: print(f 标签: {row[3]}) print() print(f共 {len(rows)} 条结果) conn.close() return 0搜索逻辑的核心是LIKE模糊匹配默认限制返回50条避免刷屏。这里GROUP_CONCAT把多条标签合并到一行避免一个条目出现多行重复。这个小技巧在处理一对多关系时非常好用推荐记下来。第三个核心命令是导出def cmd_export(args): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute(SELECT id, content, source, created_at FROM entries ORDER BY created_at DESC) rows cursor.fetchall() conn.close() html_parts [!DOCTYPE htmlhtmlheadmeta charsetutf-8titlecaveman 导出/title/headbody] for row in rows: html_parts.append(fh3{row[3]}/h3p{escape(row[1])}/ppsmall来源: {row[2]}/small/p) html_parts.append(/body/html) with open(args.output, w, encodingutf-8) as f: f.write(\n.join(html_parts)) print(f已导出 {len(rows)} 条记录到 {args.output}) return 0导出的HTML用最简单的内联样式不依赖外部CSS文件。为什么这样设计因为导出的文件可能被保存到U盘、发到微信、用邮件传给朋友如果CSS是外部引用的接收方打开时样式就崩了。单文件、内联样式、UTF-8编码这三个条件保证导出的文件在任何设备上打开都是可读的。导出功能的目的是数据逃离而不是展示酷炫的界面。主程序入口用argparse组织子命令。这个模块虽然用起来要写几行样板代码但它的--help提示是自动生成的用户输入caveman --help就能看到所有可用命令和参数说明。对命令行工具来说帮助文档就是用户文档这个能力不可或缺。3.4 打包发布让工具变成全局命令写完成功能还剩最后一步让caveman在终端里可以用单命令调用而不是每次都要写python3 /path/to/caveman.py。Linux和macOS环境下可以创建一个软链或者在PATH目录里放一个启动脚本。我自己用的是在/usr/local/bin/caveman写一个三行脚本#!/usr/bin/env python3 import sys sys.path.insert(0, /opt/caveman) from caveman import main sys.exit(main())然后给脚本执行权限整个安装过程就完成了。没有复杂的安装向导没有图形界面没有注册系统服务总共三步。Windows用户的做法略有不同会把caveman.py目录加入环境变量PATH然后写一个caveman.bat批处理文件做转发。本质上思路一样都是让系统能在任意目录找到执行入口。发布时我还会做一件事跑一遍完整的冒烟测试。从添加一条记录到搜索它到打标签到导出HTML再到用另一台没有Python环境的机器打开导出的文件全流程走一遍。工具应该让用户稳定、预期一致地完成每个操作发布前的冒烟测试就是保证稳定这个承诺的最后一道防线。4. 常见问题排查与避坑实录4.1 数据库文件损坏意外断电与WAL模式做caveman的过程中踩过的最大一个坑是数据库文件的损坏问题。有一次在写入过程中电脑突然断电重启之后整个数据库打不开了。SQLite抛出来的错误是database disk image is malformed这意味着数据库文件已经彻底损坏连打开都做不到。排查之后发现问题的根源在于SQLite默认的日志模式是DELETE模式它在每次事务提交时都要做一次文件的大面积写操作断电时容易造成文件不一致。解决办法是开启WAL模式Write-Ahead Logging。WAL模式把写操作先放到一个独立的日志文件里定期合并回主文件这种机制对意外断电的容忍度要高得多。开启方式很简单只需要在创建连接后执行一行cursor.execute(PRAGMA journal_modeWAL)这个PRAGMA语句是持久性的设置一次之后数据库文件会一直保持WAL模式不需要每次启动都执行。这个坑给我的教训是工具类软件必须默认对意外场景有弹性断电、杀进程、拔出U盘这些都是真实世界中必然发生的事。设计阶段花一点时间考虑如果这里失败了会怎样比出了问题再修复的成本低得多。4.2 中文搜索的编码与匹配问题第二个典型的坑来自中文环境的编码。caveman的搜索依赖SQLite的LIKE操作符而在默认配置下SQLite的LIKE只对ASCII字符做大小写不敏感匹配对中文则无所谓大小写问题看起来没问题。但实际使用中发现一个奇怪的现象有些中文内容明明包含关键词LIKE却搜不出来。深入排查后发现问题出在Python字符串的编码处理上。当命令行参数从sys.argv进入时如果终端环境的PYTHONIOENCODING没有设为UTF-8某些特殊字符会被错误解码导致传给SQL的查询条件跟实际输入不一致。症状表现为普通中文正常但生僻字和特殊符号会搜索失败。解决方法是程序启动时在入口处显式设置标准输出和标准错误的编码import sys if hasattr(sys.stdout, reconfigure): sys.stdout.reconfigure(encodingutf-8) sys.stderr.reconfigure(encodingutf-8)reconfigure是Python 3.7之后的标准库方法能直接修改已打开流的默认编码。加上这行代码之后中文搜索的异常就消失了。这类问题通常在开发机上永远不会暴露因为开发者的终端环境早就配置好了UTF-8但换到用户的机器上就会变成怎么就坏了。处理方式就是在开发时就假设目标环境是最麻烦的。4.3 依赖膨胀的诱惑从顺手加一个到坚决不加这是我在整个项目里学到的最大一课一定要单独拿出来讲。开发caveman的过程中我每隔几天就会冒出一个新念头如果能出一个漂亮的终端UI就好了如果能自动从网页提取标题就好了如果能生成统计图表就好了。每个念头单独看都很有吸引力。但我给自己定了一条规矩新功能提出后先放进待定清单里等两周再回头看。两周后如果仍然觉得非加不可才允许考虑。这条规矩救了我。事实是清单里的点子两周后有90%会自动消失——因为它们并不是真正的痛点只是开发者的创作冲动在作祟。剩下的10%里又有大部分能找到更轻的解决方案根本不需要新增功能来实现。我亲眼见过很多开源项目是怎么变得臃肿的作者说我先加个小功能小功能引进来一个小依赖小依赖又要求某个版本的另一个依赖半年之后当初的轻量工具变成一个需要半小时安装配置的重型框架。项目死亡的方式不是被黑掉而是被一点点喂胖到失去自理能力。caveman拒绝这种死法。4.4 快速问题速查表为了帮助其他想复刻这种极简工具风格的开发者我把踩过的坑整理成下面的速查表按优先级排列问题现象可能原因解决方案数据库报malformed错误意外断电、强制杀进程开启WAL模式定期备份数据库文件中文搜索无结果显示编码未显式设置程序入口处设置stdout/stderr编码为UTF-8运行时提示模块找不到软链接或PATH配置不完整检查启动脚本中的sys.path使用绝对路径命令运行非常缓慢数据量大且缺少索引按查询字段创建索引添加LIMIT限制导出HTML打开是乱码HTML缺少charset声明确保head中包含UTF-8的meta标签查询结果出现重复行JOIN导致一对多膨胀使用GROUP_CONCAT或者SELECT DISTINCT插入内容时单引号报错字符串拼接SQL导致改用参数化查询禁止任何形式的字符串拼接这张表不覆盖所有情况但覆盖了这个工具最可能遇到的七种问题。排查的顺序建议从前到后先确认文件完整再确认编码配置然后看索引和查询逻辑。90%以上的问题都能在这一层解决。5. 回顾机制让工具从仓库变成伙伴前面说了caveman的五个核心功能其中有一个我觉得值得展开讲讲就是回顾这个功能。它最初差点被我砍掉后来成为整个项目里我最喜欢的功能。回顾的机制不复杂就是随机抽取一条历史记录。命令很简单caveman recall它从全部条目里随机选一条展示出来。也可以加一个--tag python参数只在某个标签范围内抽取。用途是碎片时间的自我复盘——早上打开终端敲一下caveman recall随机弹出一条半年前记下的东西可能是读书笔记的一句话可能是一个没来得及做的想法也可能就是当天的灵光一闪。这个功能的原型版本只花了二十分钟就写完了但它给我的使用感受完全超出了投入产出比。它的价值在于改变了工具的使用模式CRUD类工具严格来说是让人存东西然后找东西的但随机回顾把工具变成了一个信息时间胶囊。你不再只是存储和索取你还会重新遇到你以为早就忘了的东西。技术上随机抽取的实现也很简单cursor.execute(SELECT content, created_at FROM entries ORDER BY RANDOM() LIMIT 1)一行SQL搞定。但因为数据量小完全不担心性能。能用一行SQL解决的事情就不用搭推荐系统。如果你想做一个类似的工具我强烈建议把回顾或随机抽查类功能纳入进来。它成本极低但会以你意料之外的方式改变你记录的习惯——知道自己某天会随机翻到这些记录你的写作方式都会变得更认真。6. 最后几个值得带走的小技巧这章是我做caveman整个过程中总结出来的一些散装经验它们不构成体系但每一条都在实际操作中帮过我的忙。第一给数据文件做自动备份。caveman的数据库文件就一个我写了一个极简的备份函数每次add成功提交事务后顺带把当前文件复制一份带时间戳的副本到备份目录。一条记录、一个副本多出来的成本微乎其微但数据丢失这种灾难就再也不担心了。日常用笔记软件的人也应该养成类似习惯定期导出备份比信任任何云服务都可靠。第二工具的配置量要趋近于零。caveman没有配置文件DB_PATH这个常量写死在程序里。你可能想加个-c config.yaml来让用户配置路径但仔细想想哪个正常用户会需要同时使用两个笔记库配置项存在的意义是解决真实的差异化需求不是为了显得高级。第三代码行数不该成为改进目标。有些开发者喜欢炫耀我只用300行代码就实现了XX功能。行数可以作为参考但不应成为目标。为了压缩行数把可读性牺牲掉这种极简是走偏了。caveman的代码总量确实不大但我写的时候优先保证的是每段代码读一遍就懂行数是结果不是目的。第四把删除看得和添加一样重要。开发caveman的日子里我做的最多的一件事是删除功能——删除没用的参数、删除不会走的代码分支、删除自我感动的过度设计。好的工具是雕出来的先把石头削掉大部分留下来的才是真正有用的躯干。对所有做工具、做产品的人这句话都适用。caveman这个项目现在还活着我的日常笔记、书签、灵感都流进那个小小的SQLite文件里。它不会自动帮我整理不会主动推送提醒不提供任何社交分享按钮。它只是在需要的时候被我敲一下把我要的东西找出来然后安静地等下次被使用。这恰恰是我当初给它起名叫caveman时想要的——像原始人手里的石头粗粝、可靠但足够迎战任何一场意外。