cua：一个命令行文本片段管理小工具的设计与实现

cua 是我最近做的命令行小工具名字来自我敲键盘时冒出来的第一感觉——短、响、干脆像有人把抽屉拉开又合上的那一声。它解决的问题很小但特别烦人代码里那些反复出现的片段为什么每次都要重新去翻数据库连接串、正则表达式、部署命令、git 提交信息模板这些内容我明明存过却经常要花几十分钟重新搜索一遍。于是我用一个周末写了 cua专门做一件事把常用的文本片段快速存下来再更快地复制回去。这篇文章记录需求、设计、实现和踩坑的完整过程关键代码和取舍理由都放在下面。如果你也想给自己做一个十分钟能跑通的效率工具可以拿它当参考。1. 为什么我会被一个三字母命令套牢开局痛点与命名由来1.1 这个场景你们多半也遇到过大概在半年多前我接到一个维护老服务的活儿。那次排查问题需要在服务器上拼一串参数复杂的启动命令里面包含数据库地址、缓存节点、日志路径还有一个带转义的正则表达式。我先是在搜索引擎里搜了一圈看到好几篇互相矛盾的文档又去翻自己本地那个叫 snippets.md 的笔记文件文件已经积累了上百条内容CtrlF 翻了几轮才找到一段半年前的记录复制粘贴之后发现里面还混着行号和多余的换行导致命令直接执行失败。那一刻我就意识到问题不在于我懒而在于“存”和“取”这两个动作被严重割裂。笔记软件适合写长文章不适合放零散代码片段聊天记录里的代码可以用但前提是你还能记得是哪一天、哪个群新建文档就更不现实我总不能为了存一个正则表达式新建一个页面。我想要的是这样一类工具操作足够快快到可以让我愿意为一条三行代码付出哪怕五秒钟的保存时间查找足够快快到让我不再依赖浏览器的搜索历史。后来我尝试过几个现成的片段管理软件要么太重要装客户端、账号、同步服务要么太轻只是把所有的文本塞进一个大文件连最基本的按名称搜索都做不好。于是我开始认真考虑自己写一个。核心需求其实就三条第一能用命令行直接操作因为写代码的时候我已经在终端里了第二数据必须是我能看懂的文件不能是某个私有格式的数据库第三复制结果要进系统剪贴板而不是让我再手动选中一遍。1.2 cua 这个名字是怎么来的项目一开始的代号是 “snippet-cli”名字太长打起来也累在终端里敲了两天就觉得烦。有一天我在想这个工具的核心动作其实就是“把片段从口袋里掏出来”那一瞬间脑子里蹦出一个拟声词 cua像抽屉开关的声音也像按键按下的声音。我试着在终端里敲了三个字母确认手感和节奏都好就决定用它。当然为了在跟同事介绍时不至于被追问“cua 到底是什么意思”我后来凑了一个还算能讲得通的展开Clipboard Utility for All即面向所有人的剪贴板工具。但说实话这个名字是事后硬凑的真正的原因就是短、好记、不容易撞名。在项目启动前我特意执行了一下which cua确认系统里没有同名命令然后就把这个名字焊死了。这里也提个建议给工具取名一定要先查一次命令是否被占用避免安装到你电脑上时和系统里的程序冲突。1.3 边界它不做什么cua 的定位不是笔记软件也不是密码管理器更不是 TODO 管理。它的边界非常清楚只处理纯文本片段不做富文本不搞标签系统不为每个片段维护标题、作者、创建时间这些元数据。原因也很直接任何额外的概念都会增加使用者的决策成本。笔记软件要你思考该建哪个笔记本、打哪些标签而 cua 把决策压缩为一步给你想存的内容起一个文件名字存进去完事。我见过不少同类项目最后变得难用都是因为功能越加越多支持了图片、支持了 Markdown 渲染、支持了团队共享结果用户存一个片段要考虑的事情比写代码本身还多。所以我在写 cua 的时候给自己立了一条规矩任何功能如果不能在我按下回车之后的五秒钟内感受到价值就先不做。后面所有的实现包括存储、匹配、复制全都是围绕这条规矩展开的。2. 片段即文件cua 的存储模型与设计取舍2.1 为什么不选数据库一个“偷懒”的决策最开始我以为该用 SQLite毕竟片段管理天然适合结构化存储可以做标签、做全文索引、统计使用频率。但仔细想了一圈之后我放弃了数据库回到最原始的方式每个片段就是一个独立的纯文本文件。这个决策看起来“偷懒”实际算下来是最省事的方案。原因有几点。首先是规模一个普通开发者的常用片段撑死也就几百条这个规模用文件系统完全没压力根本不需要数据库的索引能力。其次是可迁移性文本文件放哪儿都认得用 U 盘拷走、用专门工具同步、甚至是打包发到另一台机器都不会遇到格式问题。第三是生态文件存好之后我可以用 ripgrep、grep、find、编辑器自带的全局搜索去翻它们这意味着 cua 哪怕有一天本身挂了我的数据也永远可以用基础工具读到。对比项纯文本文件SQLite 数据库初始化成本零一个目录搞定需要建表、写连接逻辑备份/版本管理git、压缩包均可需要导出为其他格式检索能力依赖文件名和全文扫描自带索引适合超大片段库查看便利性任何编辑器都能直接看需要命令行或图形工具适用规模几百条以内上万条、需要复杂查询时后来实际跑起来也证明这个选择带来的额外红利是我可以很方便地在片段目录里执行git init把整个片段库纳入版本管理。这样即使某一次批量修改出了问题也能回滚到上一份快照。如果你准备做类似的工具我的建议是不要急着引入数据库先想想你的数据规模到底有多大。2.2 文件名即标签cua 的片段存储目录默认是~/.cua/snippets/里面允许再建一层子目录作为分类。我的实际目录结构长这样~/.cua/ snippets/ deploy/ docker-compose-postgres.yml nginx-ssl-conf.txt python/ regex-uuid.txt sqlalchemy-async-session.txt misc/ ssh-tunnel.txt config.toml每个文件的文件名就是它的标签。文件名的格式我强制推荐用 kebab-case也就是全小写、单词之间用短横线连接例如docker-compose-postgres.yml。为什么不用空格或下划线因为空格在终端世界里会带来无穷无尽的引号问题下划线在模糊匹配时又不如短横线容易拆词。cua 在add的时候会自动把用户输入的名称做规范化处理空格、大写、特殊符号都会被转成短横线这样我手动创建的片段无论多随意最终落到磁盘上的文件名一定符合规则。分类目录我控制在两层以内一层是分类名一层是文件名。层级做得越深使用者的心理负担就越重最后的结果往往是懒得分类、把东西乱丢。如果你只有几十个片段我建议干脆连分类目录都省略全部平铺在 snippets 目录下靠文件名把含义表达清楚就够了。2.3 片段内容的格式约定片段的正文就是纯文本。不过为了在列表展示和实际复制之间做区分我约定了一个非常轻量的规则如果文件的第一行以#开头那么这一行被视为描述信息在list命令里显示但不会被复制到剪贴板。比如一个 shell 配置片段# 生成安全的随机令牌 openssl rand -base64 32当cua list展示时你会看到一行“生成安全的随机令牌”这时你一眼就知道这段内容是干嘛的当cua copy执行时它只会复制第二行的实际命令描述行会被自动剥离。如果某个片段本身就是一段以#开头的代码比如 Python 注释、Shell 注释那它也只会影响列表显示不影响复制结果因为复制时剥离规则只判断第一行。实际上这个小约定是我在写笔记时顺手加上的。早期版本会把描述和正文一起复制进剪贴板结果我粘贴到终端里总要多删一行非常恼火。后来加了剥离逻辑这个问题就彻底消失了。你也可以理解为cua 把每个片段文件都当成一个极简的“标题正文”结构标题来自文件名描述来自第一行注释剩下的全是内容。3. 从 stdin 到剪贴板的完整链路核心命令与关键实现3.1 存储目录解析与测试友好性cua 是用 Python 3.9 写的主要理由是不需要编译、跨平台行为一致而且标准库就能完成大部分工作。依赖只有一个 pyperclip 用来读写系统剪贴板列表渲染用的 rich 是可选项。核心代码的第一步是确定存储根目录我让它优先读取环境变量CUA_HOME没有设置时才落到~/.cuaimport os from pathlib import Path def get_store() - Path: root Path(os.environ.get(CUA_HOME, Path.home() / .cua)) snippets root / snippets snippets.mkdir(parentsTrue, exist_okTrue) return snippets这里特别说一下为什么要做CUA_HOME这个环境变量。如果所有路径都写死成~/.cua测试时会污染真实数据而且每次跑测试都要想办法清理有了环境变量测试里只要把它指向一个临时目录再往临时目录里写文件测试结束后自动销毁互不干扰。这也是一个可以复制到其他小工具里的通用设计凡是会在磁盘上留下数据的程序都应该允许用户通过环境变量或参数指定数据目录。3.2 add 命令从管道和剪贴板两种方式取数据cua add的目标是让“保存一个片段”的操作时间压缩到三秒以内。设计上它支持两种数据来源如果终端有标准输入正在往管道里传内容就读取标准输入否则就读取系统剪贴板。具体逻辑是这样的import sys def read_payload(): if not sys.stdin.isatty(): return sys.stdin.read() import pyperclip text pyperclip.paste() if not text.strip(): raise SystemExit(error: stdin is empty and clipboard is empty) return text这个逻辑解决了一个问题在用cat查看某个文件、或者在浏览器里复制了一串代码之后我可以立刻切回终端执行cua add docker-compose-postgres它会把剪贴板里的内容变成一个新片段不用再打开编辑器粘贴保存。习惯之后保存一个片段的成本几乎可以忽略不计。如果你在编写类似的工具我建议一定要支持 stdin因为这种无意识的零成本保存才是你愿意长期坚持使用的前提。对于已经存在的同名片段默认行为是直接覆盖覆盖前打印一行警告。这个设计一开始遭到我自己的怀疑生怕误删内容但真实使用中发现同一名称的片段往往就是同一类内容的迭代版本覆盖带来的收益大于风险。如果你希望严格模式可以加一个全局参数--no-clobber遇到同名文件时直接报错退出。3.3 grab 的模糊匹配思路cua 的查找命令有两个cua list用于浏览全部cua grab用于按关键词快速找到片段。grab 是我用得最多、也是实现时最讲究的命令。它的核心思路是把用户的查询词转成一个“按顺序匹配字符”的正则表达式比如输入pgconn它需要能匹配到文件pg-conn-string.txt。实现里我做了一个叫 compile_fuzzy 的函数它会忽略掉短横线和下划线把用户输入的每个字符看作必须按顺序出现的线索import re def compile_fuzzy(query: str) - re.Pattern: compact_query query.replace(-, ).replace(_, ).lower() parts [] for i, ch in enumerate(compact_query): if i 0: parts.append(r.*?) parts.append(re.escape(ch)) return re.compile(.join(parts), re.IGNORECASE)匹配时不但检查原始文件名也检查去掉短横线之后的紧凑版本所以pgconn能命中pg-conn-string.txtsqlalchemy也能命中带分类前缀的长文件名。如果你用过编辑器里的模糊查找就会觉得这个体验很自然不需要记全名不需要管分隔符只要记住几个关键字母就够了。很多人以为模糊匹配很难其实在片段文件名这种短文本上一个如此简单的正则就够用了完全没有必要引入复杂的编辑距离算法。3.4 copy 和 edit高频操作要快找到片段之后最关键的动作就是复制。cua copy key会先走与 grab 相同的匹配逻辑然后读取文件内容、剥离描述行、写入系统剪贴板。这里的核心代码非常短def cmd_copy(name: str): store get_store() matches search_files(store, name) if not matches: raise SystemExit(ferror: no snippet matched: {name}) snippet load_snippet(store, matches[0]) import pyperclip pyperclip.copy(snippet[body]) print(fcopied {matches[0].name} to clipboard)edit命令则负责打开编辑器修改片段内容。它会优先使用$EDITOR环境变量指定的编辑器默认回退到viimport subprocess def cmd_edit(name: str): store get_store() matches search_files(store, name) if not matches: raise SystemExit(ferror: no snippet matched: {name}) editor os.environ.get(EDITOR, vi) subprocess.run([editor, str(matches[0])])这里有个细节编辑完成后我没有做任何文件变更检测因为编辑器保存后内容自然落在文件里后续再 grab 或 copy 时就会读到新内容。这种设计让 edit 命令变得非常简单也符合 Unix 工具的哲学程序只负责找到文件并打开保存由编辑器负责。如果你要学习这个项目的代码建议从这三条命令开始读它们各自解决了存取链路的一个环节。3.5 一个最小测试矩阵为了确保这些命令在改动后不会坏掉我给 cua 写了一套极简的测试核心就是利用CUA_HOME临时目录。下面这段测试覆盖了最常用的 add 和 grab 链路import importlib.util import io import os import sys import tempfile from pathlib import Path def test_add_and_grab(): with tempfile.TemporaryDirectory() as tmp: os.environ[CUA_HOME] tmp old_stdin sys.stdin sys.stdin io.StringIO(hello world) try: cua importlib.import_module(cua) cua.call([add, hello]) match cua.search_files(cua.get_store(), hello) assert len(list(match)) 1 body cua.load_snippet(cua.get_store(), list(match)[0])[body] assert body hello world finally: sys.stdin old_stdin测试并不复杂但它能保证最基本的添加、文件名规范化和搜索逻辑在重构后仍然可用。对于个人项目来说这已经足够让我安心地随意修改代码而不用担心哪一次顺手删掉了某个功能。如果你嫌写测试麻烦至少也要保证每个命令在干净临时目录里能打出 help 信息。4. 真实使用中才会撞上的四个坑编码、远程、空格与同步4.1 名称里的空格终端世界的隐形炸弹第一个坑是在我用了大概一周之后踩中的。某次我想存一个 docker 命令片段顺手在终端里执行了cua add docker compose up -d。结果它把“docker compose up -d”这一整串空格都保留成了文件名的一部分于是磁盘上出现了一个名字里带四个空格的怪异文件。接下来所有跟它相关的操作都要打引号列表里显示也对不齐最后我只能手动去目录里重命名。为了解决这个问题我在 add 命令里加入了强制规范化无论用户输入什么名字都会先转为小写然后把连续空格转成短横线再过滤掉除字母、数字、短横线、点号之外的字符。所以上面那条命令实际上会存成docker-compose-up-d.txt而这个文件里存的内容是“docker compose up -d”这条命令本身。规范化的规则也在 grab 返回结果时采用保证两边逻辑一致。这条经验让我明白在命令行工具里宁可替用户做一点看似武断的决策也不要让用户为随后的引号问题买单。4.2 编码问题Windows 和旧终端下的中文乱码第二个坑是编码。cua 最初在 macOS 上跑得很顺但换到一台 Windows 机器上之后凡是包含中文的片段保存后再读取全都变成了乱码。原因很简单Python 在 Windows 上读写文本文件时默认编码可能是系统区域设置对应的编码而不是 UTF-8。中文系统下常见的是 GBK用 GBK 写入、再被其他工具按 UTF-8 读取自然就乱了。解决办法是在所有文件读写操作里显式指定编码为 UTF-8并且在读取时容忍无法解码的字节def read_text(path: Path) - str: return path.read_text(encodingutf-8, errorsreplace) def write_text(path: Path, content: str) - None: path.write_text(content, encodingutf-8)errorsreplace的意思是遇到无法识别的字节时不要抛出异常而是替换成占位字符这样至少保证不会因为一个坏字节导致整个命令崩掉。另外在 Windows 终端里显示中文时建议设置环境变量PYTHONIOENCODINGutf-8让标准输出也使用 UTF-8。这个坑对你的用户来说可能没有意义但只要你的工具要跨平台分发就必须在一开始就统一编码策略。4.3 远程终端里没有剪贴板必须学会优雅降级第三个坑是远程会话。我有相当一部分时间是在连接服务器操作这时候如果执行cua copypyperclip 通常会报错因为远程 Linux 环境里没有剪贴板协议也没有安装 xclip、xsel 之类的辅助工具。有些情况下即使做了 X11 转发剪贴板也可能连不上总之远程和剪贴板之间经常是彻底的失败。我在实现里加了一个环境检测当检测到当前会话来自远程连接时copy命令自动降级为直接打印内容到终端并额外显示一个提示告诉你这段应该手动选择复制def cmd_copy(name: str): snippet find_and_load(name) if os.environ.get(SSH_CONNECTION): print(snippet[body]) print(# (remote session: clipboard unavailable, copy this manually)) return import pyperclip pyperclip.copy(snippet[body]) print(fcopied {name})用环境变量来做判断算不上什么高深技巧但它很实用本地会话不会误伤远程会话又能正常工作。如果你在 tmux、容器或远程开发环境里也用这个工具建议你也考虑类似的降级方案。工具本身的能力边界不是死的在受限环境里能不能给出一个可用的替代方案往往决定了你是否愿意继续使用它。4.4 多台机器之间的同步文件化红利与敏感内容提醒第四个坑是多设备同步。因为 cua 的数据就是纯文本文件我直接把它们交给一个私有 git 仓库管理。在~/.cua目录里初始化仓库每次内容变更后手动提交一次。这样我在办公室电脑上新增的片段回到家里拉一下最近的变更就能看到遇到误删除还能从 git 历史里恢复。如果你不想用 git用任何支持增量同步的私有工具数同步目录也可以。但这里必须提醒一句cua 里保存的内容很可能包含敏感信息比如内网数据库地址、带访问密钥的配置、临时生成的密码。这些东西一旦被推到公共仓库就是严重事故。我的做法是在~/.cua下放一个.gitignore把secret-*这类特别命名的文件排除在外另外对少数真正敏感的片段用 gpg 单独加密后再保存需要复制时先手动解密。同步便利和安全永远是个权衡建议你先把“哪些片段可以同步”想清楚再决定是否开启这项功能。5. 把 cua 变成肌肉记忆工作流整合与进阶玩法5.1 在编辑器里直接取片段cua 最舒服的上手方式是在编辑器里直接调用。比如在 vim 里我经常用:r !cua grab db-url把某段配置直接读进当前文件在 neovim 里还可以把这段调用再包一层快捷键。这样我在写代码时不需要离开编辑器也不需要切到终端去复制粘贴已经把 cua 当成了输入法之外的另一种“补全来源”。也许有人会问编辑器不是已经有 snippets 插件了吗确实有但那些插件通常绑定特定语言需要维护复杂的触发词配置。cua 的优势是完全通用只要内容是我曾经存过的东西不管它是 shell 命令、SQL 语句还是配置文件我都能用同一套记忆方式把它抓回来。它不是一个代码补全插件而是一个朴素的文本仓库正是这种朴素让它能融入各种工具链。5.2 给 fuzzy finder 当数据源如果你还嫌 cua 的命令行交互不够直观可以把它的列表输出接给一个 fuzzy finder 类的交互式选择器比如 fzf。我常用的一行组合命令是这样的cua list --with-description | fzf --preview cua grab {} --bind enter:become(cua copy {})这条命令会先展示所有片段名称和描述预览窗口里显示选中片段的具体内容按下回车就直接复制到剪贴板。原本需要先猜关键词再跑 grab 的操作变成了上下移动加回车整个过程基本不需要记忆任何片段名。这也让我进一步体会到命令行工具之间通过纯文本协作是多么高效。cua 输出的是人可读的列表fuzzy finder 负责交互选择两者都没有为此专门开发任何接口。5.3 我打算继续加的三件小事用了一段时间之后我给自己列了一个很小的待办清单都是能明确提升使用体验的改进方向而不是功能堆叠。第一是模板变量。在片段里保留{{date}}、{{host}}这样的占位符复制时用当前日期或环境变量替换。这样那些“带日期的提交说明”“带服务器名的部署命令”就不用每次手动改一遍。第二是使用频率统计。每次 copy 成功后在片段文件名旁边加一个计数文件列表时按热度排序这样最常用的片段永远排在最前面。第三是 git 快照自动提交。如果检测到片段目录已经是一个 git 仓库就在每次增删改之后自动打一个提交免去手动提交的负担。这三件事我都刻意控制在很小的范围内。做 cua 这个工具最大的体会就是越是小工具越要克制把一条命令打磨到每天用上几十次比做一个拥有一百个功能但没人记得住的软件有意义得多。如果你也想给自己做一把顺手的小工具不要从完美设计开始从你每天最烦躁的那个操作开始。