1. 从命令行越来越乱说起1.1 脚本越攒越多命令越记越乱做开发这些年我的命令行经历大致分了三个阶段。第一阶段是刚入行电脑里干干净净系统自带的ls、cd、grep就够用第二阶段开始接触各种效率工具Git 别名配了一大堆随手往/usr/local/bin里丢脚本第三阶段直接失控了——~/.zshrc里 alias 堆了上百行~/bin和~/scripts两个目录里躺着各种语言的脚本有 Python 写的批量改文件名工具有 Node 写的小爬虫有 Shell 写的日志清理程序还有编译好的 Go 二进制。每次想找个工具都得先ll ~/scripts看一眼再回忆当初是怎么调用的那个脚本是python3 rename_files.py --dir xxx还是直接./rename_files.py -d xxx完全记不住。这个阶段最大的问题不是工具少而是工具多到已经没有规律了。不同脚本的调用约定不一样有的直接执行、有的要加语言前缀、有的只吃环境变量、有的还要先 source 一个配置文件。新装的工具又容易和已有命令撞名今天装了个tldr明天发现之前写过同名脚本后者直接被遗忘了。我做过几次大扫除把脚本统一改用#!/usr/bin/env头、补上--help、整理目录但一到两个星期之后就故态复萌。因为整理规则是靠自觉的没有一个强制机制让所有工具用同一种方式被调用、被查看、被补全。CLI-Anything就是在这个背景下出现的——它不是把某个脚本重写一遍而是给所有零散命令做一个统一的注册中心和入口让任何语言写的命令行工具都能通过同一个入口被找到、被运行、被自动补全。1.2 统一入口而不是再造一套工具搞清楚CLI-Anything要解决什么问题比急着写代码更重要。我的目标非常明确不重新实现任何现有工具的能力文件批处理还是原来的 Python 脚本日志分析还是原来的 Go 程序只解决发现和调用两件事用一条命令列出所有已注册的工具用一条规则把所有工具的参数透传给它底层的真实命令让新增一个工具的成本接近零改一行配置文件、加一个软链接就算注册完成自动补全从一开始就支持注册了新命令之后下一次敲 Tab 就应该能补出来。换句话说CLI-Anything的定位是命令的命令。它不是 shell不接管进程管理它是 shell 和真实脚本之间的一层薄薄的调度层。最开始我用纯 Bash 写了一个能跑就行的版本后来逐渐演进成 Python 写的入口 配置文件驱动 各 shell 补全脚本配合的架构这个演进过程里踩了不少坑后面慢慢说。2. 设计之前先想清楚要管什么、怎么管2.1 按命令来源分类而不是按语言分类架构设计的第一个决策是给要管理的命令分类。方法有很多种按语言分最容易但这没有意义按使用频率分也有点主次不分。我最终按命令来源分了三类理由是它们的管理方式和失败模式完全不同类型例子管理重点原生二进制编译好的 Go/ Rust 程序、下载的单文件工具文件在哪个路径、版本怎么更新脚本Python/Shell/Node 脚本解释器路径、参数解析约定要不要统一组合命令多条命令的串联、带固定参数的别名定义顺序、依赖的退出码原生二进制一般不需要入口做太多事找到路径、加执行权限、透传参数就行。脚本稍微麻烦一点因为系统里可能有多个 Python 版本有的脚本要在虚拟环境里跑有的脚本依赖当前目录的环境变量这些都是入口层需要考虑的边界。组合命令最容易本质上就是一行字符串但要注意特殊字符的转义和引号处理。2.2 一个 manifest 描述所有命令CLI-Anything的管理方式是维护一个 YAML 格式的 manifest 文件记录每条命令的元信息commands: tidy: type: script exec: python3 script: ~/scripts/tidy_files.py args: [--dry-run] desc: 按规则整理当前目录文件默认只预览 tags: [file, cleanup] ports: type: binary exec: ~/tools/portmon desc: 列出当前占用端口及对应进程 deploy: type: combo exec: git push origin main ssh prod bash -s ~/scripts/deploy.sh cwd: true desc: 推送代码并执行生产部署每条命令声明它的类型、真实可执行文件、默认参数和用途说明。CLI-Anything读取这份 manifest 之后对外提供一个统一的调用入口ca tidy就等价于执行python3 ~/scripts/tidy_files.py --dry-runca ports就直接运行~/tools/portmon。这里有个细节值得注意exec字段不一定只是程序名也可以是需要解释器参与的命令行片段。对于 combo 类型我干脆允许整条写入因为组合命令本身就不是一个程序能表达的。2.3 统一调用协议牺牲花哨换可预期对各种命令做了一层薄薄的协议约束是CLI-Anything能稳定工作的关键。协议只有四条所有来自入口的参数按原始顺序透传给底层命令不做任何智能重排底层命令的退出码原样返回ca xxx的退出码就是xxx的退出码标准输入不被占用ca xxx input.txt和直接运行底层命令效果一致输出不做任何格式化处理脚本说什么就是什么。这四条协议乍看好像什么都没做实际上她们是后面所有功能的稳定地基。透了才能保持一致不格式化才能让脚本原有的管道行为不被打乱。有些 CLI 管理工具喜欢自己包一层颜色高亮、统一输出格式结果底层命令一旦有 ANSI 转义或者依赖输出重定向就各种失灵。我全部不做反而省心。2.4 命名冲突的优先级规则脚本多了之后撞名是绕不开的问题。CLI-Anything的规则很简单用户当前 shell 的 alias 优先级最高因为那是最主动、最本地的定义manifest 里注册的命令次之系统 PATH 里的同名命令兜底但入口会输出一条警告。举例来说你~/.zshrc里alias llls -l是直接生效的 shell 别名CLI-Anything不会去覆盖它如果 manifest 里注册了 docker而系统 PATH 里也有 docker入口执行时会提醒你可能想用的是 /usr/bin/docker 而不是 ~/bin/mydocker。这个规则在最开始没有是后来实测中碰到问题加进去的后面踩坑部分会展开讲。3. 核心实现注册、发现、透传、补全3.1 自动发现已有脚本而不是要求手动登记如果让用户把所有命令手动编进 manifest那这个工具大概率会被弃用。所以CLI-Anything做了两层自动发现。第一层是目录扫描。我约定~/commands作为推荐目录任何放在这一层的可执行文件启动时会被自动读取提取文件名作为候选命令名文件头部如果写了ca-desc注释会被解析为描述信息文件头部如果写了ca-args则会被拼到默认参数里。#!/usr/bin/env python3 # ca-desc 按月份归档 Downloads 中的安装包 # ca-tags archive,downloads第二层是历史命令分析。CLI-Anything提供一个ca adopt子命令读取 zsh 的历史记录找出高频出现的命令片段动态猜测哪些是非标准命令即不在 PATH 中、也不是当前 shell 内建命令然后给用户一个建议登记列表。第一次跑的时候它会把你历史里 60 多个命令全部列出来标注高概率是自定义脚本可能是系统命令无法判断用户勾选之后自动生成 manifest 条目。这层能力大大降低了迁移成本。我没有要求任何人先整理完目录再开始用而是装好之后直接ca adopt一把梭从历史记录里找回那些曾经用过但已经忘了在哪的命令。3.2 参数透传的实现与边界处理参数透传听起来简单做起来全是细节。最朴素的做法入口程序直接subprocess.run([...] sys.argv[2:])但这样马上会遇到几个问题。第一个问题参数里带-怎么办如果用户执行ca tidy -n入口自身并不解析-n它不认识这个参数直接原样拼到子命令参数列表后面。这个策略简单、安全、符合预期。但-n如果恰好是入口自己需要的参数呢比如入口定义了--list用来列出所有命令用户同时又有一个叫list的脚本想给它传--format参数就不会有冲突因为入口只在第一个非--参数出现前尝试匹配自己的选项其余全部交给子命令。# 核心调度逻辑简化 def main(): args sys.argv[1:] if not args: print_help() return cmd_name args[0] if cmd_name --list: list_commands() return entry load_manifest()[cmd_name] if entry is None: suggest_similar(cmd_name) return 127 rest args[1:] if entry.args: rest entry.args rest result subprocess.run( build_command(entry, rest), checkFalse, ) sys.exit(result.returncode)第二个问题某些参数是否应该由入口吃掉比如ca --debug xxx我一开始支持了全局调试开关结果发现--debug在真实脚本里经常是被子命令使用的参数这就在入口和子命令之间造成了歧义。权衡再三我把入口自己的参数全部收敛成单字母短参数-l列表、-h帮助、-r刷新缓存凡是双横线开头的都默认属于子命令。这彻底消除了歧义也符合普通用户不会记一整套入口级参数的心理习惯。3.3 自动补全让每个子命令都能 Tab 出来命令行工具的体验分水岭很大程度上在于补全。zsh 的补全机制强大但第一次配置很容易劝退。CLI-Anything的做法是自动生成各 shell 的补全脚本并且在命令注册表变化时主动通知刷新。zsh 补全的核心概念是_arguments和compdef。为了让每个子命令都能补全入口生成一个_ca补全函数文件里面的内容大致是#compdef ca _ca() { local -a commands commands( tidy:按规则整理当前目录文件 ports:列出端口占用 deploy:推送代码并执行部署 ) if (( CURRENT 2 )); then _describe command commands else # 子命令参数交给真实的命令自己补全 compset -P * fi } compdef _ca ca这个脚本的核心技巧在于if (( CURRENT 2 ))分支第一次 Tab 只补命令名后续参数层面则让位给真实脚本自己的补全逻辑。有些脚本没有补全系统会落到默认的文件名补全虽然不算完美但总比没有强。在 bash 里实现相对简单用complete -F _ca ca再加上一个简单的单词列表提取函数就够了。鱼 shell 有更优雅的声明式补全但考虑到用户基数我还是重点适配了 zsh 和 bash。3.4 帮助系统一屏看懂所有命令自动补全解决找得着帮助系统解决看得懂。ca -h的输出格式我打磨了很久Usage: ca command [args...] Commands: tidy 按规则整理当前目录文件 (script, file/cleanup) ports 列出当前占用端口及对应进程 (binary) deploy 推送代码并执行生产部署 (combo, deploy) ...和 2 个已隐藏命令: 运行 ca --all 查看隐藏命令的逻辑是带hidden: true标签的命令默认不显示但它们依然可以被执行这是为了给那些自己常用但不希望别人看到的工具留的口子。同时输出末尾还带上了命令数量统计一眼就知道当前注册了多少工具。帮助系统还要处理命令不存在但很像某个已注册命令的情况。我用了一个简单的编辑距离匹配算法ca tid拼错了会提示你是不是想运行 tidy。这个小功能被很多朋友夸过实际上代码量极小但很提升好感度。4. 几个关键选型背后的为什么4.1 为什么用软链接而不是整体接管 PATH一开始我考虑过更激进的方案把~/commands整个目录加进 PATH再靠入口做命名空间隔离。但这个方案有致命问题——PATH 里的命令会被所有程序看到没法控制而且一旦目录里有不可执行文件或 Mac 特有的_前缀元数据文件会污染补全和 tab 列表。更重要的是移除非常麻烦用户把目录从 PATH 里删掉之后之前依赖它的脚本会全部失效。软链接方案优雅得多。入口启动时在~/.local/bin下为每条在 manifest 里标记了global: true的命令创建一个指向自身入口的软链接文件名就是子命令名。这样系统 PATH 里只多出~/.local/bin这一条路径而所有已注册命令通过软链接调用时入口根据os.path.basename(sys.argv[0])自动判断应该调度哪个子命令。移除某个子命令时只要删掉软链接不影响任何现有配置。这个设计让CLI-Anything的安装和卸载都变得非常干净。4.2 为什么用 YAML 描述而不是写死在代码里如果命令清单写在入口程序的字典里每次加命令都要改代码、重新部署这就违背了让新工具接入成本接近零的目标。YAML 的好处是声明式、易读、方便版本管理和 diff。你新增一个命令只是加三行配置git diff 一眼就能看出来改了哪里如果命令清单是二进制里的 dictdiff 就完全没法做。不过 YAML 也有它的坑。最典型的是手滑写错了缩进整个 manifest 解析失败所有命令都不可用。为此我对解析代码做了容错读 YAML 失败时回退到昨天的自动备份每次启动都会把当前 manifest 复制一份带时间戳的副本并提示用户检查语法错误。这个回退机制在实测中救了我好几次。4.3 为什么统一走 shim而不是直接指向真实脚本入口本身是一个 shim壳层调度器这是刻意的选择。如果不经过入口直接软链接到真实脚本功能也能跑通但你就失去了几个关键能力无法统一做命令存在性检查和各命令的健康检查无法在调用时自动注入按 manifest 定义的环境变量比如PYTHONPATH或AWS_PROFILE无法统计使用频率和各命令的失败率。统一走 shim 虽然多了一次进程加载的损耗但换来的是所有命令行为的可观测性和一致性。在性能敏感的场景下可以用.ca-direct前缀绕过入口我在文档里明确建议只有像git、docker这样高频且自身带补全的工具才值得直连。4.4 不同 shell 的支持策略CLI-Anything早期版本优先支持 zsh因为 zsh 补全体系更完整compdef、_describe、compadd都是现成能力生成脚本的体验非常好。后来收到反馈说 bash 用户也想用我补了 bash 版本用的是COMPREPLY数组逻辑简单很多但也能覆盖基本需求。鱼 shell 没有专门适配原因只有一个维护成本。鱼 shell 的补全是自动基于 man page 生成的很多脚本没有规范的 man效果不好掌控。与其做一半支持不如先明确不支持。这样一个版本只维护两套补全生成逻辑质量可控。如果哪天社区有需求再单独拆个插件也不迟。5. 实测中踩过的坑与避坑建议5.1 自动补全不刷新改了 manifest 却补不出来第一个大坑出现在补全机制上线后增加了一个新命令马上执行ca xxx是能跑的但 Tab 补全里就是看不到。排查半天问题出在 zsh 的补全缓存上。compinit默认会把补全函数缓存到~/.zcompdump如果补全脚本的内容没有变化它不会重新读取。解决方法是引入一个版本戳机制CLI-Anything每次启动时把 manifest 的最后修改时间写进补全脚本头部的一个变量compinit看到这个变量值变化就强制重建缓存。实际实现时可以更简单粗暴一点——提供一个ca refresh命令直接执行rm ~/.zcompdump* exec zsh重置当前会话。我在文档里特别强调如果你改了 manifest 发现补全没变先跑ca refresh不要怀疑人生。5.2 软链接在 dotfiles 同步里的麻烦软链接方案还有一个深坑很多人的~/.local/bin是符号链接到 dotfiles 仓库的比如用stow或chezmoi管理。这时候入口在~/.local/bin下再创建软链接就会出现符号链接指向符号链接的复杂情况一旦仓库目录移动一整批软链接同时失效。我的做法是把生成软链接的目录改成~/.cache/clia-shims这个目录是用户级的不进 dotfiles。ca link命令负责把需要的命令软链接到这里用户在 shell rc 文件里再加export PATH$HOME/.cache/clia-shims:$PATH即可。这样就算 dotfiles 仓库整个删掉重来生成的软链接也不受影响反而是重建一次软链接的幂等操作重跑ca link --all就恢复了。5.3 子命令参数以-开头时入口的解析会搞混第三个坑是参数解析的边界问题。入口启动时需要用sys.argv判断子命令名这本身没问题但如果用户想执行一个叫-foo的命令那它会被当成选项来解析。实际中不会有人真的给命令命名为负数开头但有一种情况很常见用户不小心多敲了一个空格ca - tidy入口只会看到-。这个问题的处理方式是只要第一个参数是-或--入口就输出帮助信息并提示子命令名不能以横线开头。这比默默接受要好得多因为错误 100% 是用户打错了命令名而不是子命令里真的有一个横线。更复杂的参数透传问题比如子命令自己需要一个--来终止解析则完全交给底层命令入口不做任何干预。5.4 Windows 下的兼容性问题CLI-Anything最初是 Mac/Linux 项目但后来有几个同事在 Windows 上跑暴露了一堆兼容性问题。最典型的三个路径分隔符manifest 里写的/路径在 Windows 下直接失效必须统一用Path对象解析存储时保持仓库内用/运行时动态转换执行权限Windows 没有 chmod 概念脚本的exec字段要显式写解释器路径否则无法直接执行软链接Windows 的符号链接创建需要管理员权限替代方案是生成.cmd批处理文件。我也没法保证 Windows 体验和 Unix 完全一致所以官方文档里明确写了Windows 支持为实验性质建议在 WSL 中使用。有时候承认边界比假装全平台可用要负责。5.5 性能入口调用延迟的取舍用 shim 方案做调度肯定比直接执行脚本慢一点点。实测下来入口解析 manifest、构建参数、启动子进程的总耗时大概 15ms放在交互式命令行场景里体感完全无感但如果命令被反复调用数千次比如在循环脚本里15ms 的损耗就会累计成可见的差距。针对这个问题我做了两个优化。一是 manifest 增量解析启动时用 mtime 判断配置文件是否有变化没变化就直接用缓存的 Python pickle 对象解析耗时从 12ms 降到 3ms。二是为高频子命令提供直连模式配置里标了direct: true的命令入口直接变成一行字符串拼接不再走 manifest 检查。直连模式牺牲了动态注入能力但对git这种超大使用频率的命令收益非常明显。6. 落地之后工作流发生了什么变化6.1 现在的日常操作装好CLI-Anything之后我的命令行习惯有了很明显的改变。过去找脚本靠翻目录的惯性动作没有了现在就是敲ca -l一屏之内看到所有可用工具按 tag 过滤也很方便。新增工具的路径变得极短写脚本、加两行 manifest、ca refresh、直接 Tab 补全完事。最直观的变化是脚本之间的互相调用也变得可控了。过去如果我需要在 A 脚本里调用 B 脚本一种是subprocess.Popen(python3 ~/scripts/b.py)路径写死另一种是依赖 PATH但很容易在换机器时忘记把~/scripts加进 PATH。现在统一走ca b入口本身就是 PATH 的一部分而且入口会自动处理解释器和默认参数A 脚本只需要关心业务逻辑。这让几十个脚本之间的耦合度明显降低。6.2 可以继续扩展的方向CLI-Anything目前的版本已经稳定用了几个月源码大概一千行出头。后续扩展方向我心里有几个待办按优先级排如下子命令的远程执行支持如果家里服务器和笔记本都装了CLI-Anything能不能通过ca deploy --remote在远端执行本地命令命令运行统计与周报模式统计这周哪个工具跑得最频繁输出一个简单的排行榜方便发现该优化的高频操作插件市场概念提供一个ca install github:user/repo的能力从 Git 仓库拉取别人写好的命令注册模块结合日志分析把失败率高的命令自动标记出来提醒用户检查脚本是否还能正常工作。这几个方向上插件市场是工作量最大但收益也最可能爆发的。目前只是手头项目还不敢轻易承诺只能说如果社区反馈热烈会优先考虑做。6.3 写在最后的体会整个项目做下来技术挑战其实不大真正的门槛是忍住什么都往里塞。一开始我总想给CLI-Anything加终端 UI、加插件系统、加图形化管理面板后来每条功能都砍掉了因为发现用户真正需要的是一个足够薄、足够稳定的调度层而不是另一个需要学习的复杂系统。这也是我在所有命令行工具项目上越来越深的体会好工具的边界往往比它拥有的功能更能定义它的质量。如果你也在攒了一堆脚本之后觉得命令乱成一团不妨先花一个周末搭一个类似的统一入口别追求大而全先把找命令、跑命令、补全三件事理顺了你会发现在命令行上的实际效率提升比装的工具数量多得多。
