从终端碎片化到配置驱动：CLI-Anything 通用命令调度器设计与实践

1. 终端碎片化把我逼疯之后CLI-Anything 做了什么如果只是记不住命令我的解决方案顶多是一张 cheatsheet。真正让我坐不住的是另一个事实团队里每接入一个新工具终端里就多一套参数方言。docker 有--rmkubectl 有-ngit 有--onelinecurl 有-sS和一大堆 Header更别说那些只在特定项目里存在的内部脚本。它们单个看都不难难的是每次切换上下文都要重新把参数捡起来。我统计过自己一个上午的终端操作真正干活的时间不到三分之一剩下时间都在翻历史命令、查 man page、问隔壁同事。这个现象不是我一个人有新来的同学更严重。他们不敢碰线上环境不是因为不会用服务器而是因为“不知道该敲什么”。于是我开始琢磨能不能让终端操作沉淀成一种可以执行、可以分享、可以带参数复用的形式CLI-Anything 就是在这个念头下写出来的。简单说CLI-Anything 是一个配置驱动的通用命令行工具。它不打算取代 git、docker、kubectl而是给这些散落的操作套一个统一入口。你写好一份 YAML 配方描述一个任务包含哪几步、需要哪些参数CLI-Anything 负责解析参数、按顺序执行步骤、处理超时和错误。最终表现是无论是cli-anything run kill-port --port 8080还是直接输入“端口 8080”这种关键词你都不需要再背命令。这篇文章我打算把它的设计思路、核心实现和踩过的坑完整讲一遍适合运维、后端开发和所有经常泡终端的人参考。1.1 每个工具都在发明自己的参数方言工具一多参数风格之间的割裂就特别明显。git 提交用-mdocker 起容器用--namessh 指定端口用-p而本地 grep 指定上下文又用-C。同一个字母在不同工具里含义完全不同这不是记忆问题是“第一性”问题——你没法用类比推理去猜一个新工具的用法只能查。我见过太多人卡在“为什么我照抄的 docker 命令报错”最后发现是容器名冲突或者镜像名拼错。这种问题非常消耗耐心尤其在线上故障处理时你希望的是“一键执行”而不是在紧张状态下现查参数。命令行工具的本质是帮人把意图变成动作可一旦参数体系碎片化工具反而成了动作和意图之间的噪音。1.2 所谓沉淀流程只是把命令贴进 wiki团队常见的做法是把操作写进 Wiki“部署步骤1. 构建镜像…… 2. push…… 3. ssh 到服务器…… 4. docker-compose pull up -d”。听上去规范实际上一周后命令就过期了。环境变量变了、镜像仓库换了、服务器 IP 变了文档里还是老地址。新人照着操作第一步就报错。文档型 runbook 的最大问题是不可执行。写的人和读的人对同一段命令的理解可能有偏差而且没人敢改因为改了之后不知道会不会影响别人。我后来定的原则是沉淀必须落到可执行的配方里Wiki 只写背景和注意事项操作一律跑 CLI-Anything。文档负责解释“为什么”配方负责定义“怎么做”。1.3 我的解法把“记住怎么做”变成“告诉配置”CLI-Anything 的用法分三层。第一层是直接执行cli-anything run kill-port --port 8080。第二层是模糊匹配输入cli-anything 端口 8080工具根据配方里的 keywords 和描述自动找到 kill-port 并执行。第三层是写脚本把多个配方串成新的中层配方解决“先备份再迁移”这种复合流程。这个设计让三类人都能受益熟悉命令的老人可以快速写配方不太熟悉细节的新人只要会描述需求想自动化的人可以把配方当作可编程积木。这篇文章后面讲的实现都是围绕这三层用法展开的。2. 整体设计一个配置驱动、执行器兜底的通用命令调度器2.1 核心理念配方是数据执行才是代码我刻意把配置和执行拆开是因为过去见过太多工具把业务逻辑写死在 Python 文件里。业务逻辑写死的后果是每次加一个任务都要改代码、走测试、重新部署。而配置驱动之后加一个任务只是加一个 YAML 文件执行器本身可以保持最小化。打个比方CLI-Anything 是厨房配方是菜谱。厨师不负责发明菜只负责按步骤做菜菜谱写好之后换谁来做都能做出一样的菜。关键是菜谱要足够清晰什么原料、什么火候、先做什么后做什么。如果一份配方写得像一篇散文执行器再聪明也救不回来。2.2 仓库布局和模块边界项目结构被我控制在很小的范围因为工具本身不该复杂cli_anything/ ├── recipes/ # 配方库每个任务一个 YAML │ ├── dev.yaml │ ├── ops.yaml │ └── report.yaml ├── src/ │ ├── cli.py # 参数解析与交互入口 │ ├── config.py # 载入/合并配方 │ ├── resolver.py # 占位符与参数校验 │ ├── runner.py # 步骤执行器子进程管理 │ ├── matcher.py # 关键词匹配 │ └── plugins/ # 插件注册表与内置插件 ├── pyproject.toml └── recipes.example.yaml模块边界就一句话config 不知道命令怎么执行runner 不知道参数从哪来resolver 只负责字符串变换。新写一个功能时尽量只动一个模块别让职责交叉。比如一开始我把参数校验放在 cli.py 里后来发现同一个配方被关键词匹配调用时绕过了校验出过线上事故。从那以后校验统一收进 resolver。2.3 为什么配置层选 YAML选 YAML 有几个现实原因。首先团队里非 Python 背景的人也能看懂注释、缩进、列表都直观。其次 YAML 支持 anchor公共参数可以复用避免复制粘贴。TOML 语法更严格但表达能力弱一些JSON 完全不适合手写配置一个逗号错位就让人崩溃。当然 YAML 也有坑后面第五节我会专门讲引号和转义。这里先说结论把 YAML 当数据格式看别把它当脚本语言用。不要在 recipe 里写复杂逻辑逻辑放 Python 步骤里。配方只负责声明“有哪些步骤、需要哪些参数”至于步骤内部怎么做可以用type: python写一小段内嵌脚本也可以用系统命令去执行。3. 核心框架实现配方解析、参数注入与子进程执行3.1 配方 schema最小可用字段一份配方由几个基本字段构成name、description、keywords、params、steps。我加过也删过不少字段最后留下来的就是这些再加一个可选的 env 和 timeout。字段越多写配方的人越烦这是我在实践中总结出来的教训。字段类型必填说明namestring是唯一任务名比如 kill-portdescriptionstring是一句话描述会出现在帮助和匹配结果里keywordsarray否关键词/同义词用于自然语言匹配paramsmap否参数声明类型、默认值、是否必填、帮助文案stepsarray是按顺序执行的步骤列表envmap否为整个任务注入的额外环境变量timeoutint否单步骤默认超时秒数默认 60比如一个清理 Git 本地分支的配方name: git-clean-branches description: 清理本地已合并的 Git 分支 keywords: [分支, 清理, 合并, branch, clean] params: remote: type: string required: false default: origin help: 远端名称 steps: - name: 获取已合并分支 command: [git, branch, --merged, {{remote}}] capture: merged - name: 打印待清理分支 type: python script: | for line in context[merged].splitlines(): branch line.strip().lstrip(* ) if branch in (master, main, develop): continue print(branch)这里有一个关键设计步骤之间通过 context 传递数据。前一步的capture会把 stdout 存进 context后一步要么用{{变量}}注入命令要么在 Python 步骤里通过context[变量]读取。command可以写成字符串也可以写成列表写成列表时默认走 arglist 模式不经过 shell安全系数高很多。3.2 占位符解析只替换不 eval配方里参数用{{name}}包裹支持{{name|path}}、{{name|int}}这种简单过滤器。实现只有一条红线绝不 eval 任何用户输入所有参数都必须经过类型校验和字符串化。import re from pathlib import Path def resolve(raw: str, params: dict) - str: def _repl(m): expr m.group(1).strip() name, _, transform expr.partition(|) value params.get(name.strip()) if value is None: raise KeyError(f缺少参数: {name}) if transform path: value str(Path(value).expanduser()) elif transform int: value str(int(value)) else: value str(value) return value return re.sub(r\{\{\s*([^}]?)\s*\}\}, _repl, raw)配合参数声明里的 typeresolver 在替换前先做一轮校验。int 类型直接int(value)list 类型按逗号拆分bool 类型只认 true/false/1/0。校验失败时报错要带参数名和期望类型别只丢一个 ValueError。我见过很多工具在这里翻车用户看到KeyError: port根本不知道自己在哪儿拼错了但改成“参数 port 必须是整数你传的是 abc”之后几乎不用教。3.3 执行器子进程、超时与进程组执行器是整个工具里最容易出 bug 的部分。我踩过的坑包括ssh 命令杀掉父进程后留下孤儿进程、日志输出无限增长吃满内存、命令失败后后续步骤继续跑。最终实现定型如下import os import shlex import signal import subprocess def run_step(step, context, timeout60): cmd step[command] if isinstance(cmd, str) and not step.get(shell): cmd shlex.split(cmd) proc subprocess.Popen( cmd, stdoutsubprocess.PIPE, stderrsubprocess.STDOUT, textTrue, cwdstep.get(cwd), envstep.get(env), start_new_sessionTrue, ) try: out, _ proc.communicate(timeouttimeout) except subprocess.TimeoutExpired: os.killpg(proc.pid, signal.SIGKILL) raise TimeoutError(f步骤超时: {step[name]}) if proc.returncode ! 0 and not step.get(ignore_error): raise RuntimeError(f步骤失败({proc.returncode}): {out[-2000:]}) return outstart_new_session让子进程成为进程组组长超时时killpg才能把整个进程树带走。否则你八点半执行一个批量任务九点发现它卡住第二天服务器上还有一堆僵尸 ssh 进程占着连接。Windows 上这段逻辑要换成CREATE_NEW_PROCESS_GROUP和taskkill /T原理一致杀的不只是顶层的 shell而是整棵进程树。3.4 关键词匹配不依赖外部服务的自然语言入口关键词匹配模块我刻意做得很轻默认完全离线。配方里的 keywords 和 description 会被拆成词集合用户输入也被拆成同样的集合通过交集打分和名称相似度排序。命中的配方不止一条时把前三条列出来让用户选而不是直接执行。这个确认动作能避免很多误操作。from difflib import SequenceMatcher import re def match(input_text: str, recipes: list) - list: tokens set(re.findall(r[0-9a-zA-Z\u4e00-\u9fff], input_text.lower())) scored [] for r in recipes: words set(r.get(keywords, [])) words.update(r[description].lower().split()) words.update(r[name].split(-)) score len(tokens words) score max(SequenceMatcher(None, input_text.lower(), r[name]).ratio() * 2, 0) scored.append((score, r)) scored.sort(keylambda x: -x[0]) return [r for s, r in scored if s 0]如果以后想接大模型只需要在 match 之前加一个可选的远程接口让它返回配方名规则匹配做兜底。但默认安装不请求任何外部服务这是我在设计时坚持的一点工具的日常路径必须完全可控不能因为某个模型服务不可用就把整条命令链卡死。4. 三个能直接抄作业的配方杀端口、批量巡检、周报生成4.1 一键释放占用端口这个配方是所有人都能用上的尤其在本地开发环境。后端服务一多8080、3306 这些端口经常被残留进程占住。传统做法是lsof -i:8080查到 PID再kill两行命令来回折腾。放进 CLI-Anything 后长这样name: kill-port description: 释放被占用端口 keywords: [端口, 占用, 释放, kill, port] params: port: type: int required: false default: 8080 help: 需要释放的端口 steps: - name: 查找占用进程 command: [sh, -c, lsof -ti:{{port}} || true] ignore_error: true capture: pid - name: 结束进程 command: [kill, {{pid}}] when: {{pid}}这里的关键是|| true。lsof 没找到进程时返回非零退出码如果不加这层执行器会直接判定步骤失败后面的清理逻辑根本走不到。ignore_error是第二道保险但我在配方规范里坚持两个都用一个保证 shell 返回码正常一个保证执行器层面不拦截。Windows 用户把查找命令换成netstat -ano | findstr :{{port}}然后接taskkill /PID {{pid}} /F。4.2 批量 SSH 巡检批量巡检是我最早写的配方之一。那时候团队有七八台服务器每天都要手动登录看负载和磁盘。写成一个配方后每天只需要跑一次命令name: batch-inspect description: 批量巡检服务器负载与磁盘 keywords: [巡检, 服务器, 磁盘, 负载, ssh] params: hosts: type: list required: true help: 逗号分隔的主机列表例如 web01,db01 timeout: type: int default: 20 steps: - name: 分发巡检任务 type: python script: | import subprocess from concurrent.futures import ThreadPoolExecutor def check(host): cmd [ssh, -o, ConnectTimeout5, -o, BatchModeyes, host, uptime df -h / | tail -1] ret subprocess.run(cmd, capture_outputTrue, textTrue, timeoutparams[timeout]) return host, ret.returncode, ret.stdout.strip(), ret.stderr.strip() with ThreadPoolExecutor(max_workers8) as ex: for host, code, out, err in ex.map(check, params[hosts].split(,)): print(f {host} ({code}) ) print(out or err)BatchModeyes是为了避免交互式输密码导致卡死强制走密钥认证。并发数我一般控制在 8超过 20 很容易触发目标机器的连接限制。巡检结果默认打到终端你也可以在步骤里追加写入文件。这里我给配方加了timeout参数防止某个主机网络黑洞把整个任务拖死。4.3 Git 提交周报周报这个需求很微妙很多团队都是人工凑的。我用 CLI-Anything 写了一个配方从所有仓库拉取本周提交按作者和主题聚合成 TSV。步骤里直接内嵌 Python 脚本逻辑清晰也不依赖额外安装name: weekly-report description: 输出本周所有仓库的提交周报 keywords: [周报, 提交, git, report] params: repos: type: list required: false default: . help: 逗号分隔的仓库目录 days: type: int default: 7 steps: - name: 聚合提交记录 type: python script: | import subprocess import datetime repos params.get(repos, .).split(,) since datetime.date.today() - datetime.timedelta(daysparams[days]) for repo in repos: cmd [git, -C, repo.strip(), log, f--since{since}, --pretty%an|%s] out subprocess.run(cmd, capture_outputTrue, textTrue, checkFalse).stdout for line in out.splitlines(): author, subject line.split(|, 1) print(f{author}\t{subject})输出就是一个干净的制表符分隔表可以直接粘到周报文档里。如果你愿意还可以在 hooks 里挂一个通知插件跑完自动推到群聊。这就是配方复用的价值同一个数据可以既落终端又落消息不用写两套逻辑。5. 在真实终端里踩出来的四个坑5.1 YAML 的引号不等于 shell 的引号最常见的误用是有人写command: echo hello {{name}}以为 YAML 引号会把整个字符串传给 shell。实际发生的是 YAML 先解析成字符串echo hello {{name}}然后如果走 arglist 模式它会被 shlex.split 拆成echo、hello、ALICE这种错误片段。正确做法有三种。第一尽量用列表形式写 command就不需要猜引号。第二确实需要管道、重定向时显式shell: true并且把 shell 语法当作 shell 来写。第三参数值用 resolver 输出的变量承接不要在 YAML 里手工拼引号。我把这个原则写进了项目的 recipe 规范文档下面这个表格贴在文档最前面写法结果评价[echo, {{name}}]原样传参推荐无 shell 解析echo {{name}}单引号会进入参数文本有隐患参数内部引号会破坏语义echo {{name}}配合shell: true正常 shell 输出可用但参数未做转义时很危险5.2 任何参数都不该直接拼进 shell无论你是把参数拼成字符串再 subprocess.run还是用 f-string 拼命令都是在给注入漏洞留后门。--author{{author}}里的 author 如果是alice --date-filterevil后果可能超出预期。我给自己定了三条纪律优先传参数列表shell: true的步骤必须是内部受信脚本不允许接外部用户输入所有参数在 resolver 里做白名单校验。枚举型参数只允许 choices 列表里的值字符串参数过滤;|$()这些字符。这不是小题大做而是因为 CLI-Anything 存在的意义就是让更多人执行更复杂的命令入口变宽的同时必须把边界焊死。5.3 路径分隔符和编码问题Windows 用户会感觉全世界都在跟自己作对。YAML 双引号里的反斜杠会触发转义C:\Users可能变成C:Users。我的做法是recipe 里路径全部用正斜杠运行时在 resolver 的path过滤器里统一转成平台原生路径。Python 的 pathlib 在 Windows 上接收正斜杠毫无压力但 shell 接收时要注意空格路径所以能用列表参数就不用 shell 拼接。编码问题更隐蔽。Windows 上很多老工具输出 GBKPython 默认按 UTF-8 解码会直接抛 UnicodeDecodeError。我在 runner 里给 stdout 和 stderr 统一加了errorsreplace宁可出现乱码字符也不能让任务中断。关键输出再单独用PYTHONIOENCODINGutf-8保证落盘文件干净。后来我把这个设置做成了配置项因为有的内部工具确实需要 GBK 输出硬转反而得到一堆乱码。5.4 超时与输出缓冲别让日志刷爆内存第一次做批量巡检时我忘了限制输出大小一个三万行的日志直接把 CI 机器内存打满。从那以后 runner 有两个默认行为要么流式输出并按行数截断要么捕获输出时只保留末尾 N 字节。截断时必须在日志里明确写一行[output truncated at 2000 chars]否则排查问题时你会以为命令本身没输出。另一个相关问题是管道阻塞。如果你把输出重定向到管道但没人读子进程会卡在写操作上。所以我默认总是用 communicate 收完整输出需要实时日志时再进入 streaming 模式绝不让子进程的输出落在一个没人消费的缓冲区里。超时时间也分两层配方可以给全局默认超时单个步骤可以覆盖。设置原则是宁短勿长因为真正的长任务应该走后台插件而不是阻塞式命令。6. 从个人工具到团队工具插件、钩子与安全降级6.1 插件协议JSON inJSON out插件本质上是一个独立进程通过标准输入接收 JSON标准输出返回 JSON。定义这个协议之前我试过直接把插件 import 进主进程结果一旦插件抛异常整个 CLI 崩掉。独立进程的好处是隔离性和语言无关任何语言都能写插件。配置里注册plugins: notify: command: [python3, ~/.cli-anything/plugins/notify.py]插件本身很简单import json import sys def main(): data json.load(sys.stdin) if data[action] describe: print(json.dumps({name: notify, version: 1.0.0})) return topic data[params][topic] # 在这里调用内部通知服务 print(json.dumps({code: 0, sent: topic})) if __name__ __main__: main()主进程读取插件 stdout 并解析 JSON解析失败时把原始 stdout 打进错误日志方便定位协议问题。插件的价值在于把“干活”和“通知”解耦核心执行链不被外部副作用拖慢这也是我从一次通知服务超时导致整个发布流程挂掉之后悟出来的。6.2 钩子出问题的时候找得到人插件负责“主动做事”钩子负责“在关键节点被通知”。我支持三个事件点before_all、after_all、on_failure每个事件点可以声明调用哪些插件。配置长这样hooks: before_all: - notify --topic 任务 {{name}} 开始 after_all: - notify --topic 任务 {{name}} 完成 on_failure: - notify --topic 任务 {{name}} 失败: {{error}}为什么强调钩子因为团队工具和个人玩具的差距就在可追溯性。批量任务一旦挂掉你得能回答三个问题谁在什么时间跑的、跑到哪一步失败的、失败原因是什么。钩子里塞一个追加写入本地日志或内部消息的插件就能把这三件事串起来。我见过太多团队工具功能很全但一发生问题所有人都靠猜就是因为缺了这层“事件记录器”。6.3 配方共享git 仓库就是配方市场配方的复用能力比代码强得多。我们团队把 recipes 目录单独抽成 git 仓库每个配方都是一个小文件提交信息里写清改动原因。新成员 clone 到本地跑cli-anything list就能看到全部可用任务。配方版本的演进靠 git 历史出问题可以回滚到上一个版本。这里有个小技巧在配方里加source字段指向责任人。这个字段平时没用一旦配方被改坏或过期git blame 加 source 能三分钟定位到该找谁而不是在群里问“这个脚本谁写的”。source 字段也倒逼配方作者保持克制因为一旦写了大而全的复杂配方维护责任就落在他头上。6.4 安全降级--dry-run、二次确认和危险命令黑名单默认情况下我不会让 CLI-Anything 在执行前静默跳过确认。对于改动型配方执行前会打印完整参数并等一次回车--yes可以跳过这一步多用于 CI。--dry-run只打印将要执行的步骤和渲染后的命令不真正执行这条在调试配方时尤其救命。内置还有一个危险命令识别渲染后的命令如果匹配rm -rf、mkfs、drop table、truncate等模式无论是否--yes都必须额外输入danger才能放行。这个黑名单我放在独立配置文件里团队可以自己扩充因为不同的业务对“危险”的定义完全不同。对数据库团队来说drop table是要命的事但对一个玩具项目来说可能只是测试用例。7. 折腾一年后我最想留下的五句话7.1 对工程本身我最后的三个坚持第一工具的体验上限由错误信息决定。新人用你的工具报错时看到“KeyError: port”和看到“参数 port 必须是整数你传的是 abc”是两种完全不同的心态。我在 resolver 里的每一处校验都写人话提示这是最值得投入时间的地方。第二配方文件是代码要评审、要测试、要版本控制。我见过同事图省事在服务器上直接改配方三个月后没人知道线上跑的是什么版本。后来我们规定一切改动走 gitCI 里跑一遍--dry-run做冒烟测试。第三参数校验宁可严不可松。越权、误删、越界这些事故大多不是工具没做而是校验太宽松。把 choices、range、regex 能用上就用上别相信“使用者都是懂的”。7.2 对团队使用我最后的两条提醒第四不要试图覆盖所有场景。CLI-Anything 的价值不是替代每个人的肌肉记忆而是把最高频、最容易出错的 20% 操作固化下来。其余场景保留cli-anything raw逃生舱让用户能直接执行原始命令而不是逼他硬凹成配方。一个工具如果让人感觉“被绑架”它离被删除就不远了。第五入口统一之后文档反而更重要了。工具把操作变简单但“为什么这么做”仍然要写清楚。我会在每条配方的描述里带上背景链接让一键执行的人至少知道自己在做什么。毕竟再好的配方也只是把怎么做自动化了而为什么做这种判断力永远只能由人来补。现在每天早上我打开终端先跑一条cli-anything daily把巡检、周报、缓存清理一次做完。当初那个“终端太乱”的念头最后真的变成了一个每天都在用的东西。