先交代一下背景。我这边日常工作里维护着几十个脚本有处理图片的、拉报表的、清理日志的、调内部接口发通知的各脚本的参数风格完全不一样有的用--input有的用-i有的直接读环境变量还有的连个帮助文档都不写。时间一长我自己都记不住每个脚本该怎么调了。后来我想明白一件事——缺的不是脚本而是一个能把“任何东西”都统一成标准命令行入口的工具。于是就有了 CLI-Anything 这个项目它把任意可执行的东西Shell 脚本、Python 函数、HTTP 接口、定时任务统一注册成标准 CLI 子命令配上统一的参数解析、自动补全、帮助文档和输出格式。核心就是一句话Anything interactiveanything CLI。这东西适合谁只要你的日常里有“要跟一堆脚本、API、定时任务打交道”的场景它都能帮你把乱糟糟的命令行世界收敛成一个清晰、带补全、带帮助的统一入口。接下来我把它从设计思路到落地细节完整拆开讲。1. 项目诉求与设计思路1.1 我在实际工作中遇到的痛点先说几个真实场景。我有个图片批处理脚本当初是别人离职时留下来的。它接收一个目录把里面所有 JPG 转成 WebP 并压缩但参数定义混乱到离谱宽度用-w质量用-q输入目录却用环境变量INPUT_DIR输出目录又要靠位置参数传。你得翻源码才能搞明白怎么调。团队里新来的同学跑一次这个脚本光参数问题就能卡半天。这种问题不是个例。公司内部有个报表服务提供了一套 HTTP API我时不时要从命令行拉数据做分析每次都得现场拼 curl 命令写 header、写 query、处理 JSON 响应。一套流程下来十分钟过去了而且很容易拼错参数名返回一个 400 错误你还得回头慢慢排查。再有一个日志清理的定时任务散落在三台服务器上靠 crontab 各自维护规则不统一有的保留 7 天有的保留 30 天有的根本没设过期策略。你想查看任务对不对得挨台机器登录进去crontab -l效率极低。这些问题本质上是同一个没有一个统一的入口来管理和调度这些散装能力。脚本也好、API 也好、定时任务也好它们都是“能力”但暴露给使用者的方式是割裂的。我需要一个薄薄的一层把这些能力全部收拢到一个命令后面。1.2 核心架构三层分离CLI-Anything 的架构我做了三层分离分别叫描述层、执行层和表现层。描述层做的事情是“声明”。你用一份 YAML 文件描述一个命令叫什么、有哪些参数、参数类型是什么、要不要必填、执行体是什么。这一层不关心具体逻辑只关心“怎么描述清楚一个命令”。执行层做的事情是“调用”。它根据描述层的信息去找到对应的执行体可能是一个本地脚本可能是一段内嵌 Python 函数可能是一个 HTTP 请求也可能是一个定时任务。执行层负责把参数传进去把执行体跑起来拿到结果返回给上层。表现层做的事情是“输出”。它决定结果以什么格式展示给用户默认是人类可读的彩色文本--output json时输出结构化数据--silent时完全不输出只留下退出码。这样既适合人看也适合被其他程序调用。这个分层思路其实借鉴了 Web 开发的 MVC 模式。我把它称作“快递站模式”——描述层是面单执行层是快递员表现层是前台。用户只需要写好面单YAML剩下的配送和签收流程都不用关心。1.3 为什么不直接用一个现成框架肯定有人会问Python 里有 argparse、click、typerNode 里有 commander、yargs为什么还要自己造我也不是没试过直接用它们但实际用下来有几个问题绕不过去。用 argparse 写一个脚本的 CLI 没问题但你需要在每个脚本里都写一遍参数定义代码没有一个全局的“命令注册中心”。脚本一多你想从顶层看看到底有哪些命令、各自什么参数没有任何一个地方能回答这个问题。click 和 typer 用装饰器方案写起来很爽但有个隐含约束你必须把代码改造成它们的风格等于把一个脚本工具变成了一个“click 应用”。对存量脚本来说改造成本很高而且强绑定语言生态。今天你用 Python 写明天来了一个 Go 写的二进制工具click 也帮不上忙。我想要的模式是“注册式”的脚本还是原来的脚本API 还是原来的 API我不改它们的内部实现只在 CLI-Anything 里做一层登记把参数映射关系、执行方式、输出格式声明清楚就行。这样不仅对存量代码零侵入而且可以混和管理各种语言写的东西。一个 YAML 文件里你可以同时注册 Shell 脚本、Python 模块、HTTP 接口和系统命令。这是单一语言框架很难做到的。2. 核心细节解析与实操要点2.1 参数解析引擎怎么设计参数解析是 CLI 工具的命门也是体验好坏最明显的分水岭。我见过不少工具参数规则自己在代码里硬编码使用者完全猜不到。CLI-Anything 里做了两件事声明式参数定义 统一优先级规则。声明式参数定义的意思是参数长什么样在 YAML 里一眼就能看全。下面是一个典型的参数声明commands: image-resize: handler: ./scripts/resize.sh args: input: flag: --input short: -i type: string required: true help: 输入目录路径 width: flag: --width short: -w type: int default: 800 help: 输出图片宽度 quality: flag: --quality short: -q type: int default: 82 range: [1, 100] help: 压缩质量1-100每个参数都明确声明了类型、默认值、是否必填、取值范围和帮助文案。类型系统直接复用了 Python 的基础类型但做了一层特殊处理布尔类型支持--verbose直接出现和不出现两种状态列表类型支持--tag a --tag b这种重复出现的方式枚举类型可以限定合法值范围选错直接报错。这里我想认真讲一下参数优先级这也是很多人容易踩坑的地方。CLI-Anything 统一了一套规则默认值 配置文件 环境变量 命令行参数。也就是说参数的值会先从默认值取起然后如果环境变量里有对应的CLIA_QUALITY90就覆盖默认值最后如果命令行里显式传了--quality 95那环境变量也算数。这四条级别对应了不同的使用场景默认值适配“这个工具开箱即用的基准配置”配置文件适配“不同项目有不同偏好”环境变量适配“容器化和 CI 场景里动态注入”命令行参数适配“单次执行的强烈意图”。这种规则理解成本极低我用一句话就能给团队讲明白后出现的赢。2.2 子命令路由与嵌套CLI-Anything 的命令组织是树状结构。根命令下面是二级命令二级命令下面还可以挂三级命令。比如clia image resize --input ./assets --width 800 clia image convert --input a.png --output b.jpg clia data report --month 2025-01 clia data query --sql select * from orders这种嵌套结构不是拍脑袋设计的它对应了现实中的功能归属分类图片相关的放一组数据相关的放一组运维相关的放一组。每个分组有自己的命名空间参数不会互相干扰。注册机制是每个子命令都通过 YAML 里的commands节点挂载命令路径从根开始逐层展开。实现上我用了一个前缀树Trie来保存命令路径这样即使命令数量达到几百个匹配效率也完全没问题。树状结构带来的一个额外好处是可以实现只对某个子树生效的全局参数。比如你在data这一层声明了--format参数那么data report和data query都能用如果你声明在根上所有命令都能用。这种“局部全局参数”在组织大规模命令时非常实用。但嵌套结构也有代价——用户容易迷路。为此我做了三个补丁一个动态补全机制你输入clia d再按 Tab会提示data一个clia tree命令把所有命令层级打印成一棵树一个clia docs命令直接生成一份 Markdown 格式的完整使用文档。这三个功能组合起来基本消除了“不知道有什么命令”的问题。2.3 输出格式与错误处理CLI 工具的输出直接决定了它能否被其他程序安全调用。这里有个很容易被忽略的设计标准输出和标准错误必须严格分离。程序正常结果走 stdout日志和错误信息走 stderr。我在设计 CLI-Anything 时把这个原则写进了规范任何 handler 的输出如果不遵循这条就会被拦截层重新分流。输出格式方面内置了三套模式clia image-resize --input ./assets --width 800 # 默认人读模式 clia image-resize --input ./assets --width 800 --output json # JSON 模式 clia image-resize --input ./assets --width 800 --silent # 静默模式人读模式会有彩色输出、进度条、耗时统计JSON 模式输出纯结构化数据方便 jq 或其他程序接着处理静默模式下什么都不输出只有退出码能说明结果。这三种模式对应了三种典型场景人临时跑一跑、程序自动调一调、脚本里批量执行。错误处理统一走退出码规范0 表示成功1 表示业务性失败比如参数校验没过、目标文件不存在2 表示环境性失败比如依赖缺失、权限不足130 表示用户主动中断。这个规范让 CI 程序可以精准区分“是程序的问题还是环境的问题”排查效率能快不少。还有一个心得CLI 工具一定要提供--debug参数。很多隐蔽问题藏在日志里光看错误信息根本定位不了。我把 debug 模式设计成打开后自动打印完整的执行上下文加载了哪个配置、环境变量里有什么、参数最终解析成了什么值、执行体返回了什么。这一层“黑匣子”信息在实际排查中帮了大忙。3. 实操用 CLI-Anything 构建第一个工具3.1 安装与初始化新建虚拟环境后直接装包pip install cli-anything装好之后clia命令会被安装到系统路径。先用clia init在当前目录生成基础结构clia init执行完会生成一个clia.yaml和一个commands/目录。clia.yaml是主配置commands/目录用来放独立的命令描述文件。我倾向于把每个命令拆成独立文件放在commands/下主配置只保留全局设置和分组信息这样可以避免 YAML 文件越来越臃肿。初始化完成后先跑一下clia tree应该能看到一个空的命令树。此时框架已经就绪可以开始注册命令了。3.2 封装本地脚本图片处理命令我的图片处理脚本是 shell 写的内容大致是遍历输入目录里的 JPG用 cwebp 转成 WebP。原来跑它要记住一长串环境变量和位置参数。现在我把它注册成 CLI-Anything 的一个子命令。先在commands/image-resize.yaml里写下命令描述command: image-resize description: 批量压缩图片为 WebP 格式 handler: ./scripts/resize.sh args: input: flag: --input short: -i type: string required: true width: flag: --width short: -w type: int default: 1280 quality: flag: --quality short: -q type: int default: 80注意 handler 路径写的是相对路径。CLI-Anything 支持相对路径但会以配置文件所在目录为基准解析这样不管你在哪个目录执行clia image-resize都能找到脚本不会出现“跑命令时找不到脚本”的尴尬情况。这是我从踩坑里学到的如果按当前工作目录解析你在别的目录跑同一命令就废了。参数怎么传给 handlerCLI-Anything 的做法是除了命令行参数外还会把参数通过环境变量注入给子进程。脚本里直接用$INPUT_DIR、$WIDTH、$QUALITY就能取到值。这意味着原来的脚本几乎不用改动。这也是整个设计里我觉得最值的地方——存量脚本零改造接入。实测一下clia image-resize --input ./photos --width 800输出会显示处理了多少张图片、总共压缩了多少体积、平均耗时多少。这种带反馈的输出体验比原来“脚本默默跑完然后什么都不说”强太多。3.3 封装外部 API内部报表接口HTTP 接口的封装是另一个高频场景。公司内部报表服务暴露了一个 GET 接口路径是/api/report/monthly需要传month参数和一个X-API-Key请求头。原来的调用方式是拼 curl现在注册成命令command: report-monthly description: 拉取月度报表数据 http: url: https://report.internal.example.com/api/report/monthly method: GET headers: X-API-Key: ${API_KEY} params: month: type: string required: true output: json${API_KEY}的写法表示这个值从环境变量API_KEY里取。CLI-Anything 不会把密钥明文存进配置文件这样clia.yaml可以被安全地提交进代码仓库。执行时命令行参数--month 2025-01会被自动拼接到 URL 的 query string 上响应体如果是 JSON框架会用表格形式展示第一层结构方便人看。加了--output json后直接透传原始 JSON方便我继续用 jq 处理。这个能力极其通用。把经常手动 curl 的接口都注册一遍之后我基本告别了手写 API 请求。以前十分钟的活现在三秒钟敲一条命令还能自动补全。3.4 挂载定时任务日志清理日志清理任务原本散落在 crontab 里现在我把它也收拢进 CLI-Anything。命令描述长这样command: logs-clean description: 清理超过 N 天的日志文件 handler: ./scripts/clean_logs.sh schedule: 0 3 * * * args: days: flag: --days type: int default: 14 target-dir: flag: --dir type: string default: /var/log/myapp加了schedule字段后这个命令除了可以被手动执行还能被 CLI-Anything 内置的调度器接管。执行clia run-schedule后它会按 cron 表达式自动触发logs-clean命令。统一的好处是你可以在一个地方看到所有定时任务的注册情况而不需要挨台机器登录去crontab -l。调试定时任务时有个小技巧clia logs-clean --days 7 --dry-run加一个--dry-run参数脚本只打印“将要删除哪些文件”不真正执行删除。这个参数并不需要命令本身做什么特殊处理——它会被通过环境变量传给 handler脚本里检查$DRY_RUN是否为 true 即可。凡是涉及破坏性操作的命令我都建议预留这种“演习模式”能避免大量线上事故。4. 常见问题与排查技巧实录4.1 参数别名冲突我踩到的第一个坑是全局参数和子命令参数撞车。框架内置了--output全局参数我某个业务命令也想用到--output这个参数名作为业务语义。结果执行时发现框架把用户输入的--output json解释成了输出格式业务参数永远拿不到值。解决办法框架启动时会扫描所有已注册参数发现冲突就直接报错不允许启动。同时提供参数命名空间前缀类似cmd_output这种带分组前缀的长参数名。我建议在业务命令里避免使用框架预留的参数名至少避开output、debug、silent、config这几个。4.2 跨平台路径与编码问题CLI-Anything 在 Windows 和 Linux 上表现差异不小。最典型的问题是脚本里用/bin/bash写死了解释器路径在 Windows 上找不到。其次是文件路径分隔符脚本里硬编码了/Windows 上直接失效。我处理的经验是命令描述里增加一个shell字段缺省时 Windows 用cmdLinux 用bash同时框架提供TMPDIR、SEP这类路径代换变量在传给 handler 之前根据当前系统替换成正确的值。还有编码问题。在 Windows 上如果脚本输出的是 UTF-8 中文默认控制台的 GBK 编码容易导致乱码。框架为脚本启动时设置了PYTHONIOENCODINGutf-8和PYTHONUTF81两个环境变量能规避大部分编码问题。但根本的解法还是在脚本内部显式export LANGen_US.UTF-8不要依赖系统默认值。4.3 超时处理与重试HTTP 接口或定时任务有时会卡住很长时间尤其网络不稳定的时候。CLI-Anything 为每条命令都设了默认超时时间本地脚本 60 秒HTTP 请求 20 秒超时后强制终止并返回 124 退出码。后面我加了一个--retry参数在 HTTP 命令上支持重试策略默认指数退避最多重试 3 次。不同命令的超时需求不一样。图片批处理跑 1000 张图60 秒压根不够这时可以在命令描述里显式声明timeout: 600调大超时。比较难排查的一种问题是 handler 内部有子进程主进程被杀掉了子进程还在后台继续跑导致重试时新旧任务互相打架。我后来做了进程组隔离强制终止时连同整个进程组一起杀掉这个才算真正解决。4.4 动态补全失效自动补全是 CLI-Anything 的一个爽点但也经常被环境干扰。最开始的实现方式是注册一个eval脚本挂在 shell 的PROMPT_COMMAND上但在 zsh 下效果不稳定有时会报command not found: complete。后来查明原因CLI-Anything 的补全脚本用到了 bash 的complete内建函数而 zsh 用的是compdef两者机制有本质区别。解决方式是分环境检测写入.bashrc时生成 bash 版本写入.zshrc时生成 zsh 兼容版本。还有一类补全失效是路径问题。某些场景下你需要补全的是远程服务器上的路径而不是本地路径。CLI-Anything 支持在参数描述里声明completions: path或completions: dir来指定本地路径补全远程路径目前没有做内置支持建议以子命令隔离这种场景。补全机制我只能做到“大多数情况好用”因为远程环境千差万别想做到完全一致的成本太高。5. 进阶玩法与扩展思路5.1 在 CI/CD 流水线里使用CLI-Anything 的命令天然可以被 CI 系统调用因为输出规范、退出码明确、支持静默模式。我在团队的 CI 流水线里接了几个命令构建前跑代码格式检查构建后跑镜像压缩部署后跑接口 smoke test。在 CI 里最推荐的做法是clia pipeline lint --changed-only clia pipeline smoke-test --endpoint ${ENDPOINT}--changed-only这个参数被传递进脚本后脚本用git diff --name-only HEAD~1找出变更文件再做过滤可以大幅缩短 lint 时间。CI 环境里环境变量很多CLI-Anything 的“环境变量可以覆盖默认参数”这个设计在此时特别顺手——你不需要改任何命令调用方式只需要在 CI 配置里把变量灌好执行时自动生效。5.2 交互模式与组合命令纯命令行交互键的人会觉得不够友好有些任务需要连续回答多个问题。为此我加了一个交互辅助模式不带参数执行某个命令时如果检测到终端是交互式的会逐项提示输入缺失的必填参数输入完再确认一次然后执行。比如clia image-resize如果输入目录没给它就会问请输入输入目录路径。用户输入后还会问请输入输出宽度默认800。这种模式对偶尔用一次命令的人很友好不需要记参数名。更进一步我做了“组合命令”功能。多个命令可以串联成一条新命令用一个 YAML 节点声明执行顺序和参数透传规则。比如部署流程可以组合成build - test - deploy - smoke-test四步其中每一步失败则中断后续。这样一条命令完成整个发布流程非常顺滑。但我要提醒一点组合命令要谨慎使用。它虽然省事但会让错误排查复杂化因为失败时要知道是哪一步出了问题。组合命令的输出建议加步骤前缀比如[1/4] build、[2/4] test这样定位问题快得多。5.3 安全问题权限与敏感信息CLI 工具往往容易忽视安全但一旦涉及真实生产环境这个问题躲不掉。CLI-Anything 的权限模型分三层命令层级权限、参数层级权限和执行时权限。命令层级权限解决“哪些人能执行哪些命令”的问题。在命令描述里声明permissions: [admin, dev]再在全局配置里映射用户名到角色只有角色匹配的用户才能执行。这个机制在共享服务器上特别有用——普通成员可以看书签命令只有运维能用生产发布命令。参数层级权限解决“同一个命令但敏感参数受限”的问题。比如logs-clean命令所有人可以执行但--target-dir /var/log不能由非管理员传入。这层用参数描述里的required-role: admin实现非管理员传了就直接拒绝。敏感信息这块最稳妥的做法是把密钥放系统的密钥管理服务里CLI-Anything 启动时从那个服务拉取到内存再注入子进程。如果实在没有条件用密钥服务退而求其次的做法是至少设置文件权限 0600并且密钥不入库。千万别在 YAML 里明文放任何敏感凭据。6. 关于后续扩展的想法我看到不少人对这种通用 CLI 封装有类似需求这里还有几个值得继续改进的方向。一个是把命令执行历史记录下来方便后续做审计和回溯——出了问题知道谁在什么时候执行过什么命令对生产环境来说是刚需另一个是提供一个 Web 端面板把命令树展开成图形界面操作让不习惯命令行的同事也能用上同一套工具。目前这两个我都在尝试整合逐步在内部团队铺开。CLI-Anything 的核心价值其实不在某一个功能点上而在于把散落各处的东西收敛成一个统一的操作入口这带来的心智负担下降是实打实的。我自己的体会是这类封装工具的推广要和团队习惯结合起来不要一上来就把所有东西都搬进去先挑两三个高频脚本做接入试点让大家尝到“少记参数、能补全、有输出”的甜头再逐步铺开。工具永远是辅助最终要服务的人才是关键。
统一脚本、API与定时任务：用CLI-Anything打造标准命令行入口
先交代一下背景。我这边日常工作里维护着几十个脚本有处理图片的、拉报表的、清理日志的、调内部接口发通知的各脚本的参数风格完全不一样有的用--input有的用-i有的直接读环境变量还有的连个帮助文档都不写。时间一长我自己都记不住每个脚本该怎么调了。后来我想明白一件事——缺的不是脚本而是一个能把“任何东西”都统一成标准命令行入口的工具。于是就有了 CLI-Anything 这个项目它把任意可执行的东西Shell 脚本、Python 函数、HTTP 接口、定时任务统一注册成标准 CLI 子命令配上统一的参数解析、自动补全、帮助文档和输出格式。核心就是一句话Anything interactiveanything CLI。这东西适合谁只要你的日常里有“要跟一堆脚本、API、定时任务打交道”的场景它都能帮你把乱糟糟的命令行世界收敛成一个清晰、带补全、带帮助的统一入口。接下来我把它从设计思路到落地细节完整拆开讲。1. 项目诉求与设计思路1.1 我在实际工作中遇到的痛点先说几个真实场景。我有个图片批处理脚本当初是别人离职时留下来的。它接收一个目录把里面所有 JPG 转成 WebP 并压缩但参数定义混乱到离谱宽度用-w质量用-q输入目录却用环境变量INPUT_DIR输出目录又要靠位置参数传。你得翻源码才能搞明白怎么调。团队里新来的同学跑一次这个脚本光参数问题就能卡半天。这种问题不是个例。公司内部有个报表服务提供了一套 HTTP API我时不时要从命令行拉数据做分析每次都得现场拼 curl 命令写 header、写 query、处理 JSON 响应。一套流程下来十分钟过去了而且很容易拼错参数名返回一个 400 错误你还得回头慢慢排查。再有一个日志清理的定时任务散落在三台服务器上靠 crontab 各自维护规则不统一有的保留 7 天有的保留 30 天有的根本没设过期策略。你想查看任务对不对得挨台机器登录进去crontab -l效率极低。这些问题本质上是同一个没有一个统一的入口来管理和调度这些散装能力。脚本也好、API 也好、定时任务也好它们都是“能力”但暴露给使用者的方式是割裂的。我需要一个薄薄的一层把这些能力全部收拢到一个命令后面。1.2 核心架构三层分离CLI-Anything 的架构我做了三层分离分别叫描述层、执行层和表现层。描述层做的事情是“声明”。你用一份 YAML 文件描述一个命令叫什么、有哪些参数、参数类型是什么、要不要必填、执行体是什么。这一层不关心具体逻辑只关心“怎么描述清楚一个命令”。执行层做的事情是“调用”。它根据描述层的信息去找到对应的执行体可能是一个本地脚本可能是一段内嵌 Python 函数可能是一个 HTTP 请求也可能是一个定时任务。执行层负责把参数传进去把执行体跑起来拿到结果返回给上层。表现层做的事情是“输出”。它决定结果以什么格式展示给用户默认是人类可读的彩色文本--output json时输出结构化数据--silent时完全不输出只留下退出码。这样既适合人看也适合被其他程序调用。这个分层思路其实借鉴了 Web 开发的 MVC 模式。我把它称作“快递站模式”——描述层是面单执行层是快递员表现层是前台。用户只需要写好面单YAML剩下的配送和签收流程都不用关心。1.3 为什么不直接用一个现成框架肯定有人会问Python 里有 argparse、click、typerNode 里有 commander、yargs为什么还要自己造我也不是没试过直接用它们但实际用下来有几个问题绕不过去。用 argparse 写一个脚本的 CLI 没问题但你需要在每个脚本里都写一遍参数定义代码没有一个全局的“命令注册中心”。脚本一多你想从顶层看看到底有哪些命令、各自什么参数没有任何一个地方能回答这个问题。click 和 typer 用装饰器方案写起来很爽但有个隐含约束你必须把代码改造成它们的风格等于把一个脚本工具变成了一个“click 应用”。对存量脚本来说改造成本很高而且强绑定语言生态。今天你用 Python 写明天来了一个 Go 写的二进制工具click 也帮不上忙。我想要的模式是“注册式”的脚本还是原来的脚本API 还是原来的 API我不改它们的内部实现只在 CLI-Anything 里做一层登记把参数映射关系、执行方式、输出格式声明清楚就行。这样不仅对存量代码零侵入而且可以混和管理各种语言写的东西。一个 YAML 文件里你可以同时注册 Shell 脚本、Python 模块、HTTP 接口和系统命令。这是单一语言框架很难做到的。2. 核心细节解析与实操要点2.1 参数解析引擎怎么设计参数解析是 CLI 工具的命门也是体验好坏最明显的分水岭。我见过不少工具参数规则自己在代码里硬编码使用者完全猜不到。CLI-Anything 里做了两件事声明式参数定义 统一优先级规则。声明式参数定义的意思是参数长什么样在 YAML 里一眼就能看全。下面是一个典型的参数声明commands: image-resize: handler: ./scripts/resize.sh args: input: flag: --input short: -i type: string required: true help: 输入目录路径 width: flag: --width short: -w type: int default: 800 help: 输出图片宽度 quality: flag: --quality short: -q type: int default: 82 range: [1, 100] help: 压缩质量1-100每个参数都明确声明了类型、默认值、是否必填、取值范围和帮助文案。类型系统直接复用了 Python 的基础类型但做了一层特殊处理布尔类型支持--verbose直接出现和不出现两种状态列表类型支持--tag a --tag b这种重复出现的方式枚举类型可以限定合法值范围选错直接报错。这里我想认真讲一下参数优先级这也是很多人容易踩坑的地方。CLI-Anything 统一了一套规则默认值 配置文件 环境变量 命令行参数。也就是说参数的值会先从默认值取起然后如果环境变量里有对应的CLIA_QUALITY90就覆盖默认值最后如果命令行里显式传了--quality 95那环境变量也算数。这四条级别对应了不同的使用场景默认值适配“这个工具开箱即用的基准配置”配置文件适配“不同项目有不同偏好”环境变量适配“容器化和 CI 场景里动态注入”命令行参数适配“单次执行的强烈意图”。这种规则理解成本极低我用一句话就能给团队讲明白后出现的赢。2.2 子命令路由与嵌套CLI-Anything 的命令组织是树状结构。根命令下面是二级命令二级命令下面还可以挂三级命令。比如clia image resize --input ./assets --width 800 clia image convert --input a.png --output b.jpg clia data report --month 2025-01 clia data query --sql select * from orders这种嵌套结构不是拍脑袋设计的它对应了现实中的功能归属分类图片相关的放一组数据相关的放一组运维相关的放一组。每个分组有自己的命名空间参数不会互相干扰。注册机制是每个子命令都通过 YAML 里的commands节点挂载命令路径从根开始逐层展开。实现上我用了一个前缀树Trie来保存命令路径这样即使命令数量达到几百个匹配效率也完全没问题。树状结构带来的一个额外好处是可以实现只对某个子树生效的全局参数。比如你在data这一层声明了--format参数那么data report和data query都能用如果你声明在根上所有命令都能用。这种“局部全局参数”在组织大规模命令时非常实用。但嵌套结构也有代价——用户容易迷路。为此我做了三个补丁一个动态补全机制你输入clia d再按 Tab会提示data一个clia tree命令把所有命令层级打印成一棵树一个clia docs命令直接生成一份 Markdown 格式的完整使用文档。这三个功能组合起来基本消除了“不知道有什么命令”的问题。2.3 输出格式与错误处理CLI 工具的输出直接决定了它能否被其他程序安全调用。这里有个很容易被忽略的设计标准输出和标准错误必须严格分离。程序正常结果走 stdout日志和错误信息走 stderr。我在设计 CLI-Anything 时把这个原则写进了规范任何 handler 的输出如果不遵循这条就会被拦截层重新分流。输出格式方面内置了三套模式clia image-resize --input ./assets --width 800 # 默认人读模式 clia image-resize --input ./assets --width 800 --output json # JSON 模式 clia image-resize --input ./assets --width 800 --silent # 静默模式人读模式会有彩色输出、进度条、耗时统计JSON 模式输出纯结构化数据方便 jq 或其他程序接着处理静默模式下什么都不输出只有退出码能说明结果。这三种模式对应了三种典型场景人临时跑一跑、程序自动调一调、脚本里批量执行。错误处理统一走退出码规范0 表示成功1 表示业务性失败比如参数校验没过、目标文件不存在2 表示环境性失败比如依赖缺失、权限不足130 表示用户主动中断。这个规范让 CI 程序可以精准区分“是程序的问题还是环境的问题”排查效率能快不少。还有一个心得CLI 工具一定要提供--debug参数。很多隐蔽问题藏在日志里光看错误信息根本定位不了。我把 debug 模式设计成打开后自动打印完整的执行上下文加载了哪个配置、环境变量里有什么、参数最终解析成了什么值、执行体返回了什么。这一层“黑匣子”信息在实际排查中帮了大忙。3. 实操用 CLI-Anything 构建第一个工具3.1 安装与初始化新建虚拟环境后直接装包pip install cli-anything装好之后clia命令会被安装到系统路径。先用clia init在当前目录生成基础结构clia init执行完会生成一个clia.yaml和一个commands/目录。clia.yaml是主配置commands/目录用来放独立的命令描述文件。我倾向于把每个命令拆成独立文件放在commands/下主配置只保留全局设置和分组信息这样可以避免 YAML 文件越来越臃肿。初始化完成后先跑一下clia tree应该能看到一个空的命令树。此时框架已经就绪可以开始注册命令了。3.2 封装本地脚本图片处理命令我的图片处理脚本是 shell 写的内容大致是遍历输入目录里的 JPG用 cwebp 转成 WebP。原来跑它要记住一长串环境变量和位置参数。现在我把它注册成 CLI-Anything 的一个子命令。先在commands/image-resize.yaml里写下命令描述command: image-resize description: 批量压缩图片为 WebP 格式 handler: ./scripts/resize.sh args: input: flag: --input short: -i type: string required: true width: flag: --width short: -w type: int default: 1280 quality: flag: --quality short: -q type: int default: 80注意 handler 路径写的是相对路径。CLI-Anything 支持相对路径但会以配置文件所在目录为基准解析这样不管你在哪个目录执行clia image-resize都能找到脚本不会出现“跑命令时找不到脚本”的尴尬情况。这是我从踩坑里学到的如果按当前工作目录解析你在别的目录跑同一命令就废了。参数怎么传给 handlerCLI-Anything 的做法是除了命令行参数外还会把参数通过环境变量注入给子进程。脚本里直接用$INPUT_DIR、$WIDTH、$QUALITY就能取到值。这意味着原来的脚本几乎不用改动。这也是整个设计里我觉得最值的地方——存量脚本零改造接入。实测一下clia image-resize --input ./photos --width 800输出会显示处理了多少张图片、总共压缩了多少体积、平均耗时多少。这种带反馈的输出体验比原来“脚本默默跑完然后什么都不说”强太多。3.3 封装外部 API内部报表接口HTTP 接口的封装是另一个高频场景。公司内部报表服务暴露了一个 GET 接口路径是/api/report/monthly需要传month参数和一个X-API-Key请求头。原来的调用方式是拼 curl现在注册成命令command: report-monthly description: 拉取月度报表数据 http: url: https://report.internal.example.com/api/report/monthly method: GET headers: X-API-Key: ${API_KEY} params: month: type: string required: true output: json${API_KEY}的写法表示这个值从环境变量API_KEY里取。CLI-Anything 不会把密钥明文存进配置文件这样clia.yaml可以被安全地提交进代码仓库。执行时命令行参数--month 2025-01会被自动拼接到 URL 的 query string 上响应体如果是 JSON框架会用表格形式展示第一层结构方便人看。加了--output json后直接透传原始 JSON方便我继续用 jq 处理。这个能力极其通用。把经常手动 curl 的接口都注册一遍之后我基本告别了手写 API 请求。以前十分钟的活现在三秒钟敲一条命令还能自动补全。3.4 挂载定时任务日志清理日志清理任务原本散落在 crontab 里现在我把它也收拢进 CLI-Anything。命令描述长这样command: logs-clean description: 清理超过 N 天的日志文件 handler: ./scripts/clean_logs.sh schedule: 0 3 * * * args: days: flag: --days type: int default: 14 target-dir: flag: --dir type: string default: /var/log/myapp加了schedule字段后这个命令除了可以被手动执行还能被 CLI-Anything 内置的调度器接管。执行clia run-schedule后它会按 cron 表达式自动触发logs-clean命令。统一的好处是你可以在一个地方看到所有定时任务的注册情况而不需要挨台机器登录去crontab -l。调试定时任务时有个小技巧clia logs-clean --days 7 --dry-run加一个--dry-run参数脚本只打印“将要删除哪些文件”不真正执行删除。这个参数并不需要命令本身做什么特殊处理——它会被通过环境变量传给 handler脚本里检查$DRY_RUN是否为 true 即可。凡是涉及破坏性操作的命令我都建议预留这种“演习模式”能避免大量线上事故。4. 常见问题与排查技巧实录4.1 参数别名冲突我踩到的第一个坑是全局参数和子命令参数撞车。框架内置了--output全局参数我某个业务命令也想用到--output这个参数名作为业务语义。结果执行时发现框架把用户输入的--output json解释成了输出格式业务参数永远拿不到值。解决办法框架启动时会扫描所有已注册参数发现冲突就直接报错不允许启动。同时提供参数命名空间前缀类似cmd_output这种带分组前缀的长参数名。我建议在业务命令里避免使用框架预留的参数名至少避开output、debug、silent、config这几个。4.2 跨平台路径与编码问题CLI-Anything 在 Windows 和 Linux 上表现差异不小。最典型的问题是脚本里用/bin/bash写死了解释器路径在 Windows 上找不到。其次是文件路径分隔符脚本里硬编码了/Windows 上直接失效。我处理的经验是命令描述里增加一个shell字段缺省时 Windows 用cmdLinux 用bash同时框架提供TMPDIR、SEP这类路径代换变量在传给 handler 之前根据当前系统替换成正确的值。还有编码问题。在 Windows 上如果脚本输出的是 UTF-8 中文默认控制台的 GBK 编码容易导致乱码。框架为脚本启动时设置了PYTHONIOENCODINGutf-8和PYTHONUTF81两个环境变量能规避大部分编码问题。但根本的解法还是在脚本内部显式export LANGen_US.UTF-8不要依赖系统默认值。4.3 超时处理与重试HTTP 接口或定时任务有时会卡住很长时间尤其网络不稳定的时候。CLI-Anything 为每条命令都设了默认超时时间本地脚本 60 秒HTTP 请求 20 秒超时后强制终止并返回 124 退出码。后面我加了一个--retry参数在 HTTP 命令上支持重试策略默认指数退避最多重试 3 次。不同命令的超时需求不一样。图片批处理跑 1000 张图60 秒压根不够这时可以在命令描述里显式声明timeout: 600调大超时。比较难排查的一种问题是 handler 内部有子进程主进程被杀掉了子进程还在后台继续跑导致重试时新旧任务互相打架。我后来做了进程组隔离强制终止时连同整个进程组一起杀掉这个才算真正解决。4.4 动态补全失效自动补全是 CLI-Anything 的一个爽点但也经常被环境干扰。最开始的实现方式是注册一个eval脚本挂在 shell 的PROMPT_COMMAND上但在 zsh 下效果不稳定有时会报command not found: complete。后来查明原因CLI-Anything 的补全脚本用到了 bash 的complete内建函数而 zsh 用的是compdef两者机制有本质区别。解决方式是分环境检测写入.bashrc时生成 bash 版本写入.zshrc时生成 zsh 兼容版本。还有一类补全失效是路径问题。某些场景下你需要补全的是远程服务器上的路径而不是本地路径。CLI-Anything 支持在参数描述里声明completions: path或completions: dir来指定本地路径补全远程路径目前没有做内置支持建议以子命令隔离这种场景。补全机制我只能做到“大多数情况好用”因为远程环境千差万别想做到完全一致的成本太高。5. 进阶玩法与扩展思路5.1 在 CI/CD 流水线里使用CLI-Anything 的命令天然可以被 CI 系统调用因为输出规范、退出码明确、支持静默模式。我在团队的 CI 流水线里接了几个命令构建前跑代码格式检查构建后跑镜像压缩部署后跑接口 smoke test。在 CI 里最推荐的做法是clia pipeline lint --changed-only clia pipeline smoke-test --endpoint ${ENDPOINT}--changed-only这个参数被传递进脚本后脚本用git diff --name-only HEAD~1找出变更文件再做过滤可以大幅缩短 lint 时间。CI 环境里环境变量很多CLI-Anything 的“环境变量可以覆盖默认参数”这个设计在此时特别顺手——你不需要改任何命令调用方式只需要在 CI 配置里把变量灌好执行时自动生效。5.2 交互模式与组合命令纯命令行交互键的人会觉得不够友好有些任务需要连续回答多个问题。为此我加了一个交互辅助模式不带参数执行某个命令时如果检测到终端是交互式的会逐项提示输入缺失的必填参数输入完再确认一次然后执行。比如clia image-resize如果输入目录没给它就会问请输入输入目录路径。用户输入后还会问请输入输出宽度默认800。这种模式对偶尔用一次命令的人很友好不需要记参数名。更进一步我做了“组合命令”功能。多个命令可以串联成一条新命令用一个 YAML 节点声明执行顺序和参数透传规则。比如部署流程可以组合成build - test - deploy - smoke-test四步其中每一步失败则中断后续。这样一条命令完成整个发布流程非常顺滑。但我要提醒一点组合命令要谨慎使用。它虽然省事但会让错误排查复杂化因为失败时要知道是哪一步出了问题。组合命令的输出建议加步骤前缀比如[1/4] build、[2/4] test这样定位问题快得多。5.3 安全问题权限与敏感信息CLI 工具往往容易忽视安全但一旦涉及真实生产环境这个问题躲不掉。CLI-Anything 的权限模型分三层命令层级权限、参数层级权限和执行时权限。命令层级权限解决“哪些人能执行哪些命令”的问题。在命令描述里声明permissions: [admin, dev]再在全局配置里映射用户名到角色只有角色匹配的用户才能执行。这个机制在共享服务器上特别有用——普通成员可以看书签命令只有运维能用生产发布命令。参数层级权限解决“同一个命令但敏感参数受限”的问题。比如logs-clean命令所有人可以执行但--target-dir /var/log不能由非管理员传入。这层用参数描述里的required-role: admin实现非管理员传了就直接拒绝。敏感信息这块最稳妥的做法是把密钥放系统的密钥管理服务里CLI-Anything 启动时从那个服务拉取到内存再注入子进程。如果实在没有条件用密钥服务退而求其次的做法是至少设置文件权限 0600并且密钥不入库。千万别在 YAML 里明文放任何敏感凭据。6. 关于后续扩展的想法我看到不少人对这种通用 CLI 封装有类似需求这里还有几个值得继续改进的方向。一个是把命令执行历史记录下来方便后续做审计和回溯——出了问题知道谁在什么时候执行过什么命令对生产环境来说是刚需另一个是提供一个 Web 端面板把命令树展开成图形界面操作让不习惯命令行的同事也能用上同一套工具。目前这两个我都在尝试整合逐步在内部团队铺开。CLI-Anything 的核心价值其实不在某一个功能点上而在于把散落各处的东西收敛成一个统一的操作入口这带来的心智负担下降是实打实的。我自己的体会是这类封装工具的推广要和团队习惯结合起来不要一上来就把所有东西都搬进去先挑两三个高频脚本做接入试点让大家尝到“少记参数、能补全、有输出”的甜头再逐步铺开。工具永远是辅助最终要服务的人才是关键。
