1. 为什么我要做 CLI-Anything 这个项目先说结论CLI-Anything 不是一个具体的软件而是我最近半年在反复打磨的一套“命令行通用化”方案。过去我们写终端命令习惯是记一堆 alias或者一个项目一个 Makefile再或者干脆把所有脚本堆在~/bin里。时间一长命令多了以后就出现三个尴尬第一自己写的命令自己都忘记叫什么第二新同事接手项目不知道有哪些快捷操作第三同一个操作在不同机器上的执行方式完全不一样。CLI-Anything 的目标是把“任何你想执行的操作”都收敛成一条统一规则下的命令比如clia run deploy --env staging基层是外部脚本、curl 请求、Python 函数还是系统自带工具都不重要用户看到的永远是同一个入口。我最早有这个想法是因为团队里每个后端工程师维护自己的开发环境时都有一套“祖传 alias”。A 同学部署测试环境敲dpstB 同学用./scripts/deploy_test.shC 同学直接rsync -avz --delete ./dist rootxxx:/srv/www。这些其实都是同一个动作把打包产物送到测试机。操作方式分裂以后排查问题时特别痛苦。CLI-Anything 的第一个版本很简单就是把这堆散装命令收进一个 YAML 配置文件里给每条命令起一个名字然后通过统一入口去调度。后来我逐渐意识到这种“统一入口 配置驱动”的思路其实可以覆盖所有命令行场景不只是部署。这个项目适合谁适合运维、后端开发、数据分析师、以及任何一天要在终端里切换七八种工具的人。也适合团队内部做工程效率基建让“谁都可以通过几个简单命令完成重复性较高的操作”。如果你只是个人用那它也能省掉你维护 alias 的时间把命令固化到仓库里跟着项目走机器再也不用靠“记忆”来跑任务了。2. 核心思路统一入口、配置驱动、插件兜底2.1 为什么不用 shell alias、Makefile 或者 jq 包装脚本我并不是没经历过 shell alias 阶段。~/.bashrc里写一行alias upcd ~/work/myapp git pull npm install npm run dev看起来很快。但 alias 有几个硬伤它保存在每个开发者自己的 bashrc 里没法跟项目走参数处理很弱传参要么写 shell 函数要么得靠read交互Windows 上的 Git Bash / PowerShell 又是不兼容的另一套。Makefile 相对好一些但 Make 的缩进、Tab、伪目标这些语法对非 Unix 出身的人不友好而且真正要处理复杂参数时只能用 shell 语法硬写。CLI-Anything 的定位不是取代 shell而是在 shell 之上做一层“任务定义层”。它允许你将每条命令声明为 YAML 里的一个任务带描述、参数、工作目录、环境变量、命令模板执行时统一走clia run task。这样一来命令天然具备自文档能力clia list一下所有能跑的东西一目了然。团队协作时配置文件直接提交进仓库代码评审也能看到谁改了哪个命令冲突还能 diff比互相交流 alias 方便太多了。2.2 配置驱动是核心但不是唯一模式我最初的设计是纯配置也就是“所有任务都是外部命令”。后来发现有些高频操作用命令表达很别扭比如需要动态读取 JSON、需要在多个 API 之间做条件判断、需要把上一步的返回值交给下一步。如果强行用 shell 字符串拼会变成一坨魔鬼脚本。于是我在架构里引入了第二层插件模式。配置文件里可以声明某任务由哪个 Python 插件函数执行插件收到一个包含参数、工作目录、环境变量、日志对象的上下文对象ctx然后自由发挥。这样设计有一个很实际的好处简单任务用配置复杂任务写代码但入口和参数风格统一。对外表现都是clia run taskname --param value对内可以是subprocess.run调命令也可以是 Python 函数逻辑。用久了以后你会发现很多脚本根本没必要包装成 CLI写个插件函数比处理 argparse 和 main 函数省一半代码。2.3 执行层的三个关键决定第一个决定是默认用subprocess.run的列表参数形式而不是拼一整条 shell 字符串再执行。原因很简单列表形式不会经过 shell 解析特殊字符、空格、引号、$、反引号都不会因为用户的误输入被意外执行既安全又干净。那配置里写的命令模板到底是字符串还是数组呢我采用的方案是配置里写字符串内部用shlex.split()切分成数组这样兼顾了配置文件的可读性和执行时的安全性。第二个决定是环境变量控制。每个任务都可以设置独立的env和cwd而且允许“继承 覆盖”两个层次。比如全局环境变量是默认值任务级可以覆盖同一个键。执行器在启动子进程之前构造环境变量先复制一份父进程的环境再更新配置里的值。这个细节看似不起眼实际坑特别多后面章节详细聊。第三个决定是退出码和错误信息。任何被调用的外部工具退出码非零统一向上传递除非配置里显式声明ignore_error: true否则clia run自己也用非零退出码结束。这样就能在 CI 流水线里把 CLI-Anything 当作普通命令用不用再做额外的包装。3. Python 为主、Node/Go 为辅语言选型的实际考量选 Python不是说 Go、Node 不能做而是我对 Python 的生态最熟而且 Python 解释器的“零编译”特性非常适合这类配置驱动的框架。你要给团队发一个工具最怕对方装完还要编译半天Python 只要有解释器就能跑甚至能用pipx一把装。Node 我也考虑过npm 生态和 shell 交互本身也没问题但要在 Windows 和 Linux 上做到一致体验还是 Python 的subprocess更顺手一点。CLI-Anything 的实际项目结构是clia/ ├── cli.py # 入口负责解释 clia run/list/make ├── loader.py # 加载 YAML 配置合并默认值 ├── resolver.py # 参数解析、校验、占位符替换 ├── executor.py # 执行插件函数或外部命令 ├── plugins/ │ ├── __init__.py │ └── sample.py ├── tasks.yaml # 任务定义示例 └── pyproject.toml入口文件很简单用argparse解析的顶层命令没有引入 Click因为 Click 在嵌套自定义命令时反而限制了我的自由度。clia run是所有任务的总入口clia list展示任务清单clia make用来生成一个新的任务模板。还有一个隐性命令clia doctor用来检查环境变量、配置文件路径、插件目录是否正常排查问题的时候特别管用。4. 实操实现从配置文件到任务执行器4.1 任务配置格式先给你能直接抄的版本下面是我随手写的一个tasks.yaml片段覆盖了三种典型场景外部命令、带参数的模板命令、插件函数。version: 1 global: cwd: ~/work/myapp env: PYTHONUNBUFFERED: 1 NODE_ENV: development shell: false default_timeout: 120 tasks: dev: description: 启动本地开发服务 command: npm run dev cwd: ~/work/myapp/web clean: description: 清理构建缓存 command: rm -rf node_modules dist cache ignore_error: true fetch_order: description: 查询订单详情 command: curl -s http://localhost:8080/api/order/{order_id} args: - name: order_id required: true type: int env: NODE_ENV: 使用方式clia run dev clia run fetch_order --order_id 1024第一眼你可能觉得这看起来和普通脚本没区别。但关键在于它把参数定义从 shell 参数解析的泥潭里拉出来了。order_id在配置里声明为int执行前会做类型校验输入字符串自动转整数如果没传直接报错并提示必填参数。这个能力推广到复杂脚本后能省掉大量手写参数解析逻辑。4.2 参数占位符和解析器实现既然配置里命令行是字符串到底怎么把{order_id}替换成真实值我早期的版本是直接str.replace但很快踩了坑参数名可能和命令里其他花括号冲突。后来我改成显式的{{order_id}}双花括号语法内部调string.Formatter来做字段解析。这样不仅支持{order_id}还能支持{order_id!r}、{order_id:04d}这类格式化能力等于白送了一个微型模板引擎。# resolver.py import shlex from string import Formatter def resolve_command(command_template, params): fmt Formatter() # 先把花括号里出现的字段全部匹一遍再替换为参数值 result fmt.format(command_template, **params) return shlex.split(result)这里的细节是如果参数值本身包含空格shlex.split会把空格当分隔符导致命令截断。所以模板里应尽量对参数值使用!r或自行加引号这一点已经在 CLIA-Anything 的文档里标红提醒。我的建议是值中能不带空格就不带必须带空格时在插件层先转义或使用临时文件传参。4.3 执行器外部命令和插件分流执行器是整个框架的心脏。它维护了一个职责链校验参数 → 合并环境变量 → 判定任务类型 → 如果是外部命令走_run_external如果是插件走_run_plugin→ 捕获输出 → 返回退出码。核心代码如下# executor.py import os import subprocess from pathlib import Path class Executor: def __init__(self, config, plugins_dirplugins): self.config config self.plugins_dir Path(plugins_dir) def _merge_env(self, task_env): env os.environ.copy() global_env self.config.get(global, {}).get(env, {}) env.update({k: str(v) for k, v in global_env.items()}) env.update({k: str(v) for k, v in task_env.items()}) return env def _run_external(self, task, params, cwd, timeout): cmd resolve_command(task[command], params) env self._merge_env(task.get(env, {})) result subprocess.run( cmd, cwdcwd, envenv, shellself.config[global][shell], timeouttimeout, textTrue, capture_outputTrue, ) if result.stdout: print(result.stdout, end) if result.stderr: print(result.stderr, end, filesys.stderr) return result.returncode def _run_plugin(self, plugin_func, ctx): try: return plugin_func(ctx) except Exception as exc: print(fplugin error: {exc}, filesys.stderr) return 1有个容易被忽略的问题subprocess.run的textTrue默认使用当前区域编码Windows 下 PowerShell 输出可能是 UTF-16Linux 下是 UTF-8。如果日志里有中文经常会出现UnicodeDecodeError。我的处理是强制encodingutf-8, errorsreplace宁可看到替换符也不要崩溃。4.4 插件怎么写请看这个示例插件是一个非常朴素的协议一个可调用对象接收ctx返回退出码。ctx对象里至少包含 params、task、env、logger 四个成员。# plugins/sample.py def run(ctx): name ctx.params.get(name, world) ctx.logger.info(fhello, {name}) return 0配置文件对应tasks: hello: plugin: sample.run description: 打印打招呼信息 args: - name: name required: false default: world插件路径可以用plugins.sample.run或sample.run框架会先尝试在当前插件目录找模块再尝试完整导入。这个设计解决了一个实际问题当你需要在一个任务里调用另一个任务时不用重新subprocess启动自身直接在插件里 import executor 模块再调用同一个执行函数即可。内部调用省掉了进程启动开销连续跑几十个批量任务时速度快很多。5. 常见问题排查与避坑手册5.1 命令明明存在却提示 command not found这是刚引入 CLI-Anything 时最容易遇到的问题。尤其是用cwd切到某个目录后相对路径下的命令解释不了。排查思路分三步在对应cwd下手动执行一遍原始命令先排除项目本身的问题。确认这个命令是“外部程序”还是“shell 内置函数”。比如cd、source、export就是 shell 内置用subprocess.run列表模式根本执行不了。遇到要改环境变量的任务必须写插件或显式加shell: true我个人不推荐后者因为拼接字符串有注入风险。检查 PATH 继承。Windows 上注意用户 PATH 和系统 PATH 合并后os.environ.copy()拿到的 PATH 可能和你终端里echo $env:PATH不一样。我建议在doctor检查里直接列出最终 PATH一眼就能看出哪个环节被吞了。5.2 子进程环境变量设置不生效比如你在任务里设置了NODE_ENVproduction但 Node 应用读到的还是development。八成原因是环境变量是在任务级配置里写入的但脚本里又用dotenv从文件重新加载了一遍后者覆盖了前者。还有一种是你在_merge_env里更新了 env但subprocess.run传的是envenv按理说不应该丢。唯一例外是 Windows 上大小写不敏感的问题PATH和Path在 Windows 里等同但 dict 里又是两个 key更新了PathPATH可能没同步导致命令找不到。所以在 Windows 合并 PATH 时我会对Path、PATH两个键都赋同一个值。5.3 参数里的特殊字符被无情拆解你传--keyword foo bar通过shlex.split后foo 和 bar 已经合并成一个 token 了没问题。但如果模板里写的是--keyword{keyword}那keyword会被替换成foo bar然后shlex.split把它拆成--keywordfoo和bar两个 token。这就是我踩过的经典坑。解决办法是模板里写--keyword{keyword}或者在插件里用pipes.quote/shlex.quote给参数加引号。在 Windows 上更麻烦引号规则和 POSIX 不一样所以我在内置模板里提供了一组参数装饰器标记style: windows-safe的字段会用subprocess.list2cmdline做序列化。5.4 必须重视退出码和超时curl命令经常出现外部服务超时但 curl 本身因为重试等原因退出码是 0这导致 CI 误判为成功。CLI-Anything 对超时的默认策略是外部命令按配置的default_timeout跑超过直接TimeoutExpired强制杀进程并返回 124。这个设计和timeout命令保持了一致。我建议所有网络类的任务都显式声明timeout: 30或更小避免某个请求卡住后整个流程吊死在容器里。从运行现场来看CLI-Anything 在_run_external里会检查result.timed_out标志不过 Python 3.9 之后TimeoutExpired会带stdout/stderr我直接捕获异常并打印非常直观。5.5 Windows 兼容性说不完的细节我在 Linux/macOS 上跑得好好的到 Windows 上就翻车。主要几类问题shlex.split的 POSIX 模式和 Windows 命令行规则不同。我内部用posixFalse但处理引号又诡异。.bat、.cmd文件不能在subprocess.run里直接执行需要调cmd.exe /c。cwd路径分隔符和~展开不一致。PowerShell 是默认 shell 时shell: true的语法又变了。我的务实方案不追求所有任务跨平台CLI-Anything 允许在配置目录里放tasks.windows.yamlWindows 平台优先加载它能识别的任务定义。同名任务在 Windows 下覆盖为.bat命令在 Unix 下保持.sh命令。这个妥协让实现复杂度大降也让真正需要跨平台的任务数量大幅减少。6. 让 CLI-Anything 更好用补全、日志和团队协作一个只有run和list的框架还不够顺手我后来又加了三个功能。clia complete输出 shell 补全脚本。你可以在.bashrc里加一行source (clia complete bash)这样敲clia run再按 Tab所有任务名都会自动补全。实现方法是遍历 YAML 里的任务名生成complete -W单词补全工作量不大但对日常使用体验提升极大。团队里总有不喜欢敲完整命令的人补全是让他们接受这个工具的关键一步。日志输出我做了两级普通运行时只打印子进程 stdout调试时用CLIA_DEBUG1可以看到参数解析结果、env 合并结果、resolver 的中间状态。这些内容平时用不到但一旦出了问题没有 debug 日志基本等于盲人摸象。最后是团队协作。我把tasks.yaml放在仓库的ops/clia/目录下然后给clia增加了一个--project参数让它自动从当前目录向上查找项目名并加载对应的配置目录。这样每个项目都能自带一套 CLI 入口新人进来拉完代码直接clia list就能了解所有可用的开发、测试、部署命令。配合我们后面做的clia sync甚至还能把私有云上一批任务清单同步到本地CMDB 记录一次终端里到处复用。跑了几次团队内推广后我最大的心得是做这类通用框架千万不要一上来就把功能做满。把配置格式、执行器、插件协议这三个地基打牢剩下的补全、同步、自动生成文档都是锦上添花而且后续改起来也不会伤害到已经用的同学。CLI-Anything 目前还在持续迭代接下来打算加入更多预处理钩子比如任务执行前自动检查 Docker 是否启动、Node 版本是否满足相当于在入口处加一道“环境体检”。这个方向我觉得比堆砌新命令行语法更有价值。
