“cua”这个词最近在网上挺常见不少人拿它当拟声词用形容“唰一下”“嗖一下”就完成了。我做的这个小项目也叫“cua”但它是正经的命令行工具——我把自己平时反复在做的那些文件整理、项目初始化、数据归档操作全部收拢成一条条短命令。以前要手动敲一堆 mv、mkdir、tar、find现在敲一个 cua 加个动作词就够了。这套东西适合谁说实话只要你的日常工作里有一丁点重复性文件操作都值得参考。开发者可以拿它当脚手架和自动化脚本的入口运维可以拿它做日常巡检和归档的快捷方式内容创作者也能用它批量改名、打包素材。整个项目没有引入任何重框架就是 Python 脚本加 JSON 配置跑起来非常轻。下面我把整个项目从设计思路到具体实现再到踩过的坑一次讲清楚。1. 项目定位与整体设计思路1.1 为什么做一个叫“cua”的命令行工具先说说名字。我取“cua”这个名字就是想表达“唰一下就把事情办完”的体验。命令行工具有个老问题功能强大了命令就变长参数就变多。本来是想省事结果每次都要翻帮助文档。我的目标很简单任何高频操作最多敲一个命令加一两个参数不能再多。市面上的自动化工具其实分两类。一类是 Ansible、SaltStack 这种重型的配置管理工具适合管理服务器集群对个人电脑来说太重了。另一类是各种“快捷指令类”App但图形界面的自动化始终隔了一层没法覆盖终端里的场景。命令行用户真正需要的是一个能把 Shell 脚本、Python 脚本、系统命令组合起来并且统一入口的东西。“cua”就是干这个的。项目的核心不复杂一个 Python 写的入口脚本加上若干功能模块再用一个 JSON 文件管理配置。命令结构统一是cua 动作 目标 [参数]。比如cua rename . --from 2024 --to 2025就是把当前目录文件名里的 2024 换成 2025cua pack ./work -o ~/Archive就是把工作目录按规则打包归档。1.2 方案选型为什么不用 Shell 脚本一把梭最早我确实是用一堆 Shell 脚本实现的但很快发现几个痛点。第一个痛点参数解析。Shell 里解析--from、--to、--dry-run这类带值参数getopts 能写但语法别扭遇到参数带空格更是要小心翼翼地加引号。Python 的 argparse 是现成的解析规则清晰报错信息还友好能省一大半时间。第二个痛点跨平台。虽然我主要在 macOS 和 Linux 上跑但也希望这套工具放到 Windows Git Bash 里能干活。Shell 脚本里到处是find、grep、sed三个平台的 GNU 和 BSD 版本行为还有差异调试起来非常崩溃。Python 的 os、shutil、pathlib 标准库是跨平台一致的写一遍到处能跑。第三个痛点组合能力。归档这个动作往往不是单一的“打包”而是“改完名 → 清理临时文件 → 压缩 → 移动到归档目录”。Shell 脚本也能做但命令之间传参需要一堆全局变量时间长了根本不敢改。用 Python 模块的话每个动作就是一个函数可以安全地组合调用逻辑清楚得多。所以最终的技术栈非常简单Python 3 做主体配置文件用 JSON系统通知等平台能力用 subprocess 调用系统自带命令。没有任何第三方依赖拿到任何一台装有 Python 3 的机器就能跑。2. 核心机制与配置设计2.1 命令路由插件化模块加载“cua”能有十几个动作全靠一套简单的插件机制。项目目录下有一个modules文件夹每个功能模块就是一个.py文件比如rename.py、pack.py、clean.py。入口脚本启动时会扫描这个文件夹把每个模块里约定的register(subparsers)函数注册到 argparse 的子命令上。这样做的好处一是加新命令不用改入口代码往modules里丢一个新文件就行二是每个模块独立维护不需要关心别人怎么写模块之间通过标准输入输出或者临时文件交互耦合非常低。模块注册的约定也很简单每个模块需要提供两个东西一个是register(subparsers)函数用来声明命令名称和参数另一个是run(args)函数参数解析完成后会被调用。入口脚本只做三件事加载模块、解析参数、调用对应的run(args)。2.2 配置文件的组织方式配置文件放在~/.cua/config.json里面存的是那些“每个机器都不太一样”的路径和偏好。比如默认的归档目录、打包时要忽略的目录名、文件重命名的默认规则等。我刻意没有用 YAML原因只有一个JSON 是 Python 标准库自带支持解析完全零依赖。虽然 YAML 可读性更好但为了配置格式去装一个 PyYAML对一个“零依赖”项目来说不划算。配置内容也不算复杂JSON 嵌套两层完全够用。{ archive_dir: ~/Archive, working_root: ~/work, pack: { include: [*.md, *.pdf, *.png, *.jpg], exclude: [*.tmp, *.log, .DS_Store], name_pattern: {project}_{date}.tar.gz }, rename: { default_from: ^IMG_, default_to: photo_ }, notify: { enabled: true } }入口脚本启动时先加载配置然后传给run(args)模块不需要自己去读配置文件避免每个模块重复实现一套路径处理逻辑。2.3 参数设计与命令组合参数设计的核心原则是短、可预测、安全。短是指常用的参数都提供简写比如-o表示目标目录-r表示递归-n表示试运行。可预测是指所有模块统一支持--dry-run先告诉你“我准备做什么”确认无误再真正执行。安全是指删除类操作都设计成先移动到系统回收站而不是直接物理删除这样误操作还有后悔药吃。命令组合方面我在入口层做了一个非常小的改进就是允许用cua pack ./work cua notify 打包完成这种形式直接串联命令。你可能会说这和 Shell 自己的有什么区别区别在于cua的所有命令都自动解析了配置里的默认参数而且提供了统一的错误码。组合起来之后每个命令的输出也更规范方便脚本做后续判断。3. 实操过程从零搭建完整项目3.1 项目目录结构与入口脚本我的项目目录长这样~/.cua/ ├── cua # 入口脚本可执行 ├── config.json # 配置文件 └── modules/ ├── __init__.py ├── rename.py # 批量重命名 ├── pack.py # 打包归档 ├── clean.py # 清理临时文件 ├── notify.py # 系统通知 └── new.py # 初始化项目骨架cua这个入口脚本本身就是一个 Python 文件第一行写死 shebang通过软链接放到~/.local/bin里面终端任意路径都能直接调用。入口脚本的核心代码其实很短#!/usr/bin/env python3 import argparse import importlib import json import os import pkgutil CONFIG_PATH os.path.expanduser(~/.cua/config.json) def load_config(): if os.path.exists(CONFIG_PATH): with open(CONFIG_PATH, encodingutf-8) as f: return json.load(f) return {} def main(): parser argparse.ArgumentParser(progcua, description一键搞定高频文件操作) subparsers parser.add_subparsers(destcommand, requiredTrue) modules_dir os.path.join(os.path.dirname(os.path.abspath(__file__)), modules) config load_config() for mod_info in pkgutil.iter_modules([modules_dir]): mod importlib.import_module(fmodules.{mod_info.name}) if hasattr(mod, register): mod.register(subparsers) args parser.parse_args() args.config config mod importlib.import_module(fmodules.{args.command}) if hasattr(mod, run): return mod.run(args) parser.print_help() if __name__ __main__: sys.exit(main())这里有个细节我用了pkgutil.iter_modules而不是自己去os.listdir是因为前者只会识别真正的 Python 包文件能天然过滤掉__pycache__这类临时文件少写一段过滤逻辑。3.2 第一个实战模块批量重命名批量重命名是我用得最多的功能。写稿、处理素材、整理下载文件场景里全是IMG_0234.JPG、微信图片_20250310_123456.png这种乱七八糟的文件名。需求无非三种替换关键词、加日期前缀、按顺序编号。我在rename.py里做成了三个子参数--find和--replace处理替换--prefix加前缀--numbered按序号重命名还配了一个--recursive递归处理子目录。import os import re from pathlib import Path def register(subparsers): p subparsers.add_parser(rename, help批量重命名文件) p.add_argument(target, nargs?, default., help目标目录) p.add_argument(--find, help查找的文本) p.add_argument(--replace, default, help替换成的文本) p.add_argument(--prefix, help文件名前缀) p.add_argument(--numbered, actionstore_true, help按序号重命名) p.add_argument(--recursive, -r, actionstore_true, help递归处理子目录) p.add_argument(--dry-run, -n, actionstore_true, help只预览不执行) p.set_defaults(handlerrename) def run(args): base Path(args.target).expanduser().resolve() if not base.is_dir(): print(f目录不存在: {base}) return 1 pattern None if args.find: pattern re.compile(re.escape(args.find)) count 0 files sorted(base.rglob(*) if args.recursive else base.iterdir()) for item in files: if not item.is_file(): continue new_name None if pattern: new_name pattern.sub(args.replace, item.name) if args.prefix: new_name args.prefix (new_name or item.name) if args.numbered: new_name f{count:03d}_{item.name} if new_name and new_name ! item.name: new_path item.with_name(new_name) if args.dry_run: print(f重命名: {item.name} - {new_name}) else: item.rename(new_path) count 1 print(f完成共处理 {count} 个文件) return 0一个容易忽略的坑加了--numbered又用了--find时最终文件名是先把关键词替换了再编号还是先编号再替换我在代码里固定了顺序先替换再加前缀最后编号。顺带说一句这个顺序应该写进命令帮助文本里否则用户每次都得猜。--dry-run是这类批处理命令的救命稻草。批量操作文件最怕的就是执行到一半发现规则写错了。有了预览模式先跑一遍看输出清单确认无误再真正执行能避免大量因为手滑导致的数据混乱。3.3 场景级模块一键归档打包归档这个模块是我认为“cua”最能体现价值的模块。它把一条平时需要多个步骤的操作压缩成了一条命令。以前的流程是进入工作目录、筛选文件、建文件夹、复制、压缩、移动归档目录每一步都可能出错。现在只需要cua pack ./work -o ~/Archive。pack.py实现的关键点是这样的import os import shutil import tarfile import tempfile from datetime import datetime from pathlib import Path def register(subparsers): p subparsers.add_parser(pack, help打包归档目录) p.add_argument(target, help要打包的目录) p.add_argument(-o, --output, help归档目录默认读取配置) p.add_argument(--include, nargs*, help要包含的文件模式) p.add_argument(--exclude, nargs*, help要排除的文件模式) p.add_argument(-n, --dry-run, actionstore_true, help只预览不执行) p.add_argument(--no-archive, actionstore_true, help归档但不打包) p.set_defaults(handlerpack) def run(args): src Path(args.target).expanduser().resolve() config_pack args.config.get(pack, {}) include args.include or config_pack.get(include, [*]) exclude args.exclude or config_pack.get(exclude, []) archive_dir Path(args.output or args.config.get(archive_dir, ~/Archive)).expanduser().resolve() archive_dir.mkdir(parentsTrue, exist_okTrue) project_name src.name date_str datetime.now().strftime(%Y%m%d) output_name f{project_name}_{date_str}.tar.gz output_path archive_dir / output_name files_to_pack [] for rule in include: files_to_pack.extend(src.glob(rule)) if exclude: files_to_pack [f for f in files_to_pack if not any(f.match(rule) for rule in exclude)] if not files_to_pack: print(没有匹配到任何文件) return 1 if args.dry_run: print(f将归档 {len(files_to_pack)} 个文件到 {output_path}) for f in files_to_pack: print(f {f.relative_to(src)}) return 0 with tarfile.open(output_path, w:gz) as tar: for f in files_to_pack: tar.add(f, arcnamef.relative_to(src)) print(f归档完成: {output_path}) return 0这一段代码里最实用的技巧是archive_dir.mkdir(parentsTrue, exist_okTrue)。如果归档目录还不存在提前创建避免最后tarfile.open因为父目录不存在直接抛异常。归档路径不存在是特别常见的问题路径越深越容易漏mkdir 一下最保险。还有一个经验打包的时候用arcnamef.relative_to(src)去掉绝对路径前缀。很多人第一次写 tar 打包都直接tar.add(f)结果打出来的压缩包从根目录开始解压的时候文件路径特别深非常不方便。我必须在arcname上做处理保证压缩包里的结构就是工作目录的相对结构。3.4 系统通知与定时任务联动notify模块是额外加的一个小功能但实用性意外地高。打包是耗时操作哪怕只有几秒钟人也会走神去做别的事。如果打包完成之后能弹一个系统通知就能极大减少“傻等”的时间。跨平台的通知方案我选的是用系统自带命令import platform import subprocess def register(subparsers): p subparsers.add_parser(notify, help发送系统通知) p.add_argument(title, help通知标题) p.add_argument(message, nargs?, default, help通知内容) p.set_defaults(handlernotify) def run(args): system platform.system() if system Darwin: script fdisplay notification {args.message} with title {args.title} subprocess.run([osascript, -e, script], checkFalse) elif system Linux: subprocess.run([notify-send, args.title, args.message], checkFalse) elif system Windows: subprocess.run([msg, %username%, f{args.title} {args.message}], shellTrue, checkFalse) print(通知已发送) return 0这里不装第三方通知库是因为系统自带命令已经够用而且通知功能属于“锦上添花”不值得为它引入依赖。Mac 上用osascriptLinux 桌面环境用notify-sendWindows 上用msg三个平台各一行命令就能解决。配合定时任务使用时cua的威力才真正体现出来。Linux/macOS 上写一行 crontab0 22 * * * cd ~/work/project cua pack . -o ~/Archive cua notify 每日归档 项目文件已打包晚上十点自动打包完成后弹通知整个过程完全无人值守。我连续跑了两周每天定时归档一次都没出过问题。这个场景特别适合那种每天产生大量临时文件、但又不希望手动整理的人。4. 常见问题与排查技巧实录4.1 命令找不到第一反应先查 PATH新装完“cua”最容易遇到的就是终端提示cua: command not found。这个问题九成是软链接没有放进 PATH 目录里。检查方法很简单ls -l ~/.local/bin/cua echo $PATH确保~/.local/bin在 PATH 里。如果不在就在.bashrc或.zshrc里加一行export PATH$HOME/.local/bin:$PATH还有一种情况是入口脚本没有可执行权限。我写过一次之后重新 clone忘了chmod x cua结果终端报的是Permission denied。说到底Python 脚本的 shebang 写对了还不够必须配合可执行权限才能被直接调用。4.2 路径带空格的经典大坑Shell 用户最容易踩的坑就是路径里有空格。就算“cua”内部用 Python 的 Path 对象处理路径调用方式也得注意。正确的做法是加引号cua rename ~/My Documents/project --find old --replace new另外在模块代码内部凡是调用subprocess的地方参数必须用列表传比如subprocess.run([tar, -czf, str(output_path), ...])绝对不要拼出一个字符串然后用shellTrue去执行。列表传参会自动处理路径里的空格和特殊字符这是 Python 官方文档明确推荐的用法。4.3 日志文件一次都没匹配上打包模块刚写好时我遇到一个很怪的问题include规则配置了[*.md, *.pdf]但运行 cua pack 时提示“没有匹配到任何文件”。排查了很久才发现Path.glob(*.md)只能匹配当前目录底下的文件不会递归子目录。如果希望递归匹配应该用src.rglob(*.md)。但这里有一个矛盾打包完整工作目录时不同层级的文件都要包含使用简单的glob会漏全部使用rglob又可能把node_modules里数万个文件都打进去。我的解决办法是默认用rglob但 exclude 规则里必须配置node_modules、__pycache__、.git这类目录打包前先过滤一遍。4.4 删除操作必须有的“后悔药”清理临时文件模块里我坚持了两条原则第一默认只删后缀明确的临时文件比如.tmp、.cache、__pycache__这类一眼就知道没用的第二删除操作统一走回收站而不是直接shutil.rmtree。macOS 上可以用trash命令移动文件到回收站Linux 可以安装trash-cli都没有的话就退而求其次在项目目录下建一个.trash文件夹把要删的文件移进去。这样即使删错了也能从回收站或者.trash目录里翻回来。加上--dry-run的支持清理操作的安全性做到了当前设计下的最高水平。问题现象可能原因排查/解决方案command not foundPATH 缺失或软链接失效检查~/.local/bin与 PATH 配置Permission denied脚本无执行权限chmod x ~/.cua/cua文件没被匹配到使用 glob 而非 rglob确认是否需要递归匹配路径带空格报错参数被 Shell 分割路径加引号subprocess 用列表传参打包路径很深未使用 arcname 处理相对路径打包时设置arcnamef.relative_to(src)误删文件直接物理删除改为移入回收站支持 --dry-run5. 经验总结与后续扩展方向写“cua”这段时间我最大的体会是自动化工具的价值不在于代码多精巧而在于是否真正贴合自己的使用习惯。市面上成熟工具很多但没有一个能完全理解“我每周五下午要把 work 目录打包然后给团队发个消息”这种需求。自己动手做一个小工具把重复动作收敛成一条命令带来的效率提升是立竿见影的。还有一个小技巧分享给你模块的register函数里给每个参数写清楚 help 文本然后入口脚本再加上--help补全。这样即使你哪个月没用某个功能只要敲cua rename --help就能立刻想起来参数怎么传。别小看这个习惯命令行工具冷落一两个星期后记忆是真的会模糊的。后续我打算给它加一个“模板市场”的功能每个模块都可以导出一个配置模板比如“前端项目初始化模板”“论文素材归档模板”。这样换新电脑时不用一条条重建配置导入模板就行。如果你也经常被重复的文件操作困扰不妨照这个思路自己搭一个从最简单的单个模块入手就行用起来你就会知道每天省下来那十几分钟累积起来其实非常可观。