CLI-Anything：用声明式配置自动生成命令行工具的工程实践

CLI-Anything这个名字，是我给自己折腾了大半年的一个工具项目起的。起因特别朴素：团队里每个人手里都有一堆“只有自己能看懂”的脚本，查数据库的、调接口的、跑批处理的、甚至还有定时发群消息的。脚本一多，问题就来了——换个人就不会用，参数格式全靠猜，输出结果五花八门，有的打印表格，有的吐JSON，有的直接往日志文件里怼。我当时就在想，能不能反过来，把“写脚本”这件事标准化：你只需要声明这个任务是什么、收什么参数、去哪里执行、结果怎么输出，剩下的由一套统一框架去生成真正的命令行入口。这就是CLI-Anything的雏形：一个将任意任务描述文件转换为可用CLI命令的通用工具。它适合谁用？适合那些手里攒了一堆脚本、想统一命令入口但又不想重写所有逻辑的人，也适合刚接触CLI设计、想搞清楚“命令和参数是怎么被抽象出来”的开发者。这篇文章，我会把整个项目的设计思路、核心实现、踩坑过程都摊开讲。

1. 从“一堆脚本”到“统一入口”：CLI-Anything想解决的问题

1.1 每个工具都有自己的脾气

先说个真实场景。我们组之前维护着上百个内部脚本，有Python写的，有Shell写的，还有几个是某个同事用Node临时搓出来的。每个脚本的调用方式都完全不同：

# 查用户信息 python query_user.py --uid 12345 # 查订单，参数名却叫 id python query_order.py -i 67890 # 跑数据修复，要改配置文件 bash fix_data.sh --env prod --batch 20240601

麻烦的不只是记不住参数名。有些脚本读环境变量，有些脚本依赖一个“默认在当前目录找config.ini”的隐式约定，还有些脚本根本不校验参数——传错了就报一个“KeyError: 'uid'”，你完全不知道是参数名错了还是后端接口挂了。每次有人拿着同事的脚本问“这个怎么跑”，对方都要现场回忆三分钟。

这个问题本质上是接口设计缺失：脚本的边界是乱的，输入不统一，输出不统一，错误处理不统一。而CLI工具天然适合承担“统一入口”的角色——它把输入抽象成命令和参数，把输出抽象成标准输出和退出码，把错误抽象到stderr。只不过大多数人写CLI还是顺着脚本的思路写，没有把这层抽象提炼出来。

1.2 核心抽象：任务描述文件

CLI-Anything的核心想法，是把“一个任务”描述成一份独立的声明式文件。不管你是要调HTTP接口、查数据库、跑一个本地脚本，还是给远端发一条消息，这个文件的结构都一致：

• 元信息：任务名、描述、分组。
• 参数定义：每个参数的名字、类型、是否必填、默认值、提示语。
• 执行方式：类型（http / db / shell / plugin），以及对应的连接配置和请求模板。
• 输出约定：字段映射、格式（json / table / raw）、是否隐藏敏感字段。

换句话说，CLI-Anything不再要求你写一遍命令解析逻辑，而是要求你回答四个问题：这个命令叫什么？它接收什么？它去做什么？它产出什么？这四个问题一旦有了标准答案，CLI入口、参数校验、输出格式化这些重复劳动就可以全部自动化。

拿“查用户信息”举例，以前是一个Python脚本，现在是一段YAML：

name: query-user description: 查询用户基本信息 type: http method: GET url: "https://api.example.internal/users/{id}" params: - name: id type: integer required: true help: 用户ID - name: verbose type: boolean default: false help: 是否显示完整字段 output: format: table fields: [id, display_name, email, status]

这段配置就是全部“代码”。CLI-Anything读取之后，会自动生成一个名为query-user的子命令，支持--id和--verbose两个参数，自动校验id必须是整数，自动调用HTTP接口，自动把返回JSON按字段列表输出成表格。

1.3 一个能复用的执行模型

这套设计背后其实是一个非常简单的执行模型，整个运行过程可以用一句话概括：命令行入口 → 参数绑定 → 执行器 → 输出格式化。

所有任务都跑在这条流水线上，差异只体现在“执行器”这一段。HTTP任务走HTTP执行器，数据库任务走数据库执行器，本地脚本任务走Shell执行器。因为流水线是固定的，所以框架可以做大量通用的事情：

• 参数校验、缺省值填充、类型转换。
• 执行超时控制、重试、并发限制。
• 统一的退出码（0成功，1参数错误，2执行失败，3超时）。
• 基于终端类型自动切换输出格式，管道输出JSON，人看输出表格。

这也是我后来选型时反复权衡的依据：与其做一个“更聪明的脚本框架”，不如做一个“更会下蛋的CLI生成器”。CLI-Anything不需要理解业务逻辑，它只需要把业务逻辑藏在配置之后，把交互、校验、输出这些烦心事都接管过来。

2. 系统边界与核心技术选型

2.1 薄入口，厚配置

第一个技术决策就是“薄入口”。CLI-Anything的入口层面只做三件事：加载配置、解析命令、分发给执行器。它不包含任何具体业务代码——连“怎么发HTTP请求”都不写在入口里，而是放在执行器模块中。

这样做的原因是，如果入口代码里堆满了业务分支，那它最终还是会变成原来的一百个脚本，只不过换了个壳子。薄入口意味着所有任务都是数据，而数据可以被管理、被校验、被版本化。你甚至可以给每个任务配上owner和SLA，这就不是一般脚本框架能做到的了。

实现上，入口就是一组标准库调用，主流程写成纯函数，不依赖任何全局状态：

# cli_anything/main.py import click from click import Command, Group def main(config_path: str): registry = load_registry(config_path) group = Group() for task_name, task_config in registry.tasks.items(): group.add_command(build_command(task_name, task_config)) group()

2.2 配置格式选型：YAML vs JSON

配置格式我纠结过很久。JSON的好处是机器可读、解析快、schema工具成熟，缺点是手写体验太差：注释没法定，写错一个逗号整份文件挂掉。YAML的好处是上手成本极低，人人都能写，嵌套结构看起来更清晰，还能用---把多个任务放在一个文件里。但YAML也有坑：缩进错误是运行时才发现，类型推断规则偶尔反直觉，比如version: 1.0会被解析成字符串，id: 001还会被当成十进制整数丢掉前导零。

最终我选了YAML，但配套做了严格的schema校验。任务配置必须经过校验才能注册，不能拿“能跑就行”将就。校验用JSON Schema做，定义好任务描述文件的完整结构，包括参数类型枚举、必填字段、类型约束等。

{ "type": "object", "required": ["name", "type", "params"], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "type": { "enum": ["http", "db", "shell", "plugin"] }, "params": { "type": "array", "items": { "type": "object", "required": ["name", "type"], "properties": { "name": { "type": "string" }, "type": { "enum": ["string", "integer", "float", "boolean", "list", "file"] } } } } } }

这个schema看起来不起眼，但它在项目后期救了我很多次。随着任务配置从十几个涨到上百个，手写错误大幅增加——参数名拼错、类型写错、缩进错位。没有校验，这些错误要到命令执行时才会炸出来；有了校验，加载阶段就直接报“任务query-user第3个参数type字段不合法，期望值是integer/float/boolean之一”。

2.3 执行器与连接器的分离

执行器是CLI-Anything里最需要设计清楚的部分。我一开始想得很简单：每种任务类型写一个执行器类，比如HttpExecutor、DbExecutor、ShellExecutor。但写着写着发现不对，HTTP执行器内部还要区分调用内部API和外部API，数据库执行器又要区分MySQL、PostgreSQL、ClickHouse。

这时候我意识到需要把“执行逻辑”和“连接方式”拆开。执行器只负责一件事：拿到参数，调用底层能力，返回结构化结果。连接器负责具体的协议对接。

比如HTTP执行器的核心逻辑是：url模板填充、请求头组装、超时与重试、状态码判断。具体怎么发请求，交给连接器，比如httpx.AsyncClient包装成HTTP连接器。这样新增一个任务类型时，大部分情况下你只需要写一个新的连接器，执行器能复用。

# cli_anything/connectors/http_connector.py class HttpConnector: def __init__(self, base_url: str, timeout: float = 5.0): self.base_url = base_url.rstrip("/") self.timeout = timeout def request(self, method: str, path: str, params: dict, headers: dict | None = None): import httpx with httpx.Client(timeout=self.timeout) as client: resp = client.request(method, f"{self.base_url}/{path.lstrip('/')}", params=params, headers=headers) resp.raise_for_status() return resp.json()

2.4 为什么最终选了插件化

有段时间我琢磨：既然CLI-Anything目标是“Anything”，那我不可能把所有执行器都内置吧？HTTP、DB、Shell、RPC、消息队列、文件操作……每一种都要写、要维护，永远追不上需求。于是我把执行器设计成了插件机制。

插件是一个Python包，暴露一个register接口，向框架注册自己支持的连接器类型和参数schema：

# cli_anything_redis/plugin.py from cli_anything.plugin import register_executor def register(config): register_executor("redis", RedisExecutor, schema=REDIS_CONFIG_SCHEMA)

框架启动时扫描配置里声明的插件目录，逐个加载。核心只保留HTTP和Shell执行器，其他按需安装。这个设计让项目从“我一个人维护的工具”变成了“团队里谁需要谁就扩展”的平台。后来同事加了一个飞书消息执行器，总共不到一百行代码，连框架代码都没动。

插件化的代价是调试变难了一点，尤其是插件里的异常容易把主流程的堆栈搞乱。我的处理方式是给插件调用包一层统一的异常边界，把插件抛出的任意异常转成PluginExecutionError，附带插件名和自定义错误消息，这样用户看到的错误不是一坨堆栈，而是“插件redis执行出错：连接超时”。

3. 动手实现一个可用的最小版本

3.1 配置加载与校验

最小版本的配置加载就三步：读YAML、校验schema、构建任务注册表。

# cli_anything/loader.py import yaml from pathlib import Path def load_registry(config_path: str): raw = yaml.safe_load(Path(config_path).read_text(encoding="utf-8")) tasks = raw.get("tasks", []) if not isinstance(tasks, list): raise ConfigError("配置文件的tasks必须是列表") registry = TaskRegistry() for task in tasks: validate_task(task) registry.register(task["name"], task) return registry

这里有个容易忽略的细节：yaml.safe_load不要换成yaml.load。虽然你自己的配置文件可以信任，但一旦配置目录要被团队成员共享，保不准有人往里面塞了一个!!python/object标签，直接执行任意代码。safe_load能挡掉这类风险。

校验我用了jsonschema库，上面的schema例子就是实际用的。校验失败的错误信息会把出错路径打印出来，定位起来非常快，比YAML自己报的“line 12 column 3”好用十倍。

3.2 动态生成CLI命令

CLI-Anything用的是Python的click库来构建命令行。click支持命令组（Group）和命令（Command），关键是它还允许你动态添加参数。每个任务配置里的参数定义，都会被转换成对应的click option。

import click def build_command(task_name: str, task_config: dict) -> click.Command: params = [] for p in task_config.get("params", []): option_name = f"--{p['name']}" kwargs = { "type": map_click_type(p.get("type", "string")), "required": p.get("required", False), "default": p.get("default"), "help": p.get("help", ""), } params.append(click.Option([option_name], **kwargs)) @click.pass_context def callback(ctx, **kwargs): executor = create_executor(task_config) result = executor.execute(kwargs, ctx=ctx) print_formatted(result, task_config.get("output", {})) cmd = click.Command(name=task_name, params=params, callback=callback) cmd.short_help = task_config.get("description", "") return cmd

这段代码有几个关键点：

• click.Option手动构造解决了动态参数问题。你不需要在函数签名里写死形参，而是通过params列表传给click.Command。
• @click.pass_context让回调能拿到全局上下文，比如-v全局verbose开关、--config覆盖路径等，这些信息放在ctx.meta里传递。
• 类型映射map_click_type需要你自己写，把配置里的integer映射到click.INT，把boolean映射到click.BOOL，list映射到click.Tuple等。

提示：click里布尔类型的默认行为是“出现即True”，所以别给布尔参数配默认值True然后还想用--no-verbose关闭，click不会自动帮你生成反向选项，需要手动再注册一个--no-{name}。

3.3 执行器实现与错误处理

执行器的统一接口是execute(params, ctx) -> Any。它接收已经校验过的参数，返回一个Python对象，这个对象交给输出层去格式化。执行器内部不关心用户看到什么，只管把结果拿回来。

class ExecutorBase: def execute(self, params: dict, ctx): raise NotImplementedError

HTTP执行器的逻辑要处理URL模板填充、请求参数、响应包装：

class HttpExecutor(ExecutorBase): def __init__(self, config): self.connector = create_connector(config.get("connector", {})) self.method = config.get("method", "GET").upper() self.url_template = config.get("url") self.header_template = config.get("headers", {}) def execute(self, params, ctx): url = self.url_template.format(**params) headers = {k: v.format(**params) for k, v in self.header_template.items()} if self.method == "GET": resp = self.connector.request("GET", url, params=params, headers=headers) else: body = {k: v for k, v in params.items() if k in config["body_fields"]} resp = self.connector.request(self.method, url, json=body, headers=headers) return resp

错误处理是这里容易忽视的点。一个HTTP调用可能失败在DNS解析、连接超时、读超时、4xx、5xx，每种情况的用户提示都应该不同。裸抛异常肯定不行，用户看到的会是一行“ConnectError: [Errno -2] Name or service not known”，根本不知道是自己参数传错了还是网络问题。

我用了一个错误分类器：

• ParamValidationError：参数校验失败，退出码1。
• ConnectTimeoutError、ReadTimeoutError：网络超时，退出码3，提示“连接目标服务超时，请确认网络或稍后重试”。
• HTTPStatusError：目标接口返回4xx/5xx，退出码2，带上状态码和响应body前200个字符。
• 其他未预期异常：退出码4，提示“未预期的异常，请附带上方堆栈信息反馈给维护者”。

这样一个用户看到退出码，马上就知道怎么处理：1是自检参数，2是找接口owner，3是网络问题，4才是找框架问题。

3.4 输出格式化

输出格式是CLI工具易用性的胜负手。CLI-Anything最开始只支持JSON输出，结果被同事吐槽“我看命令结果还得拿jq再处理一下”。后来实现了三种输出模式：

• json：完整数据，适合管道和自动化脚本调用。
• table：人看，自动截取配置声明的字段，宽度自适应终端。
• raw：原样输出，适合文本类接口或shell脚本直接消费。

自动探测模式是我最喜欢的：如果标准输出是管道（不是终端），默认json；如果是终端，默认table。这背后用到了一个技巧：sys.stdout.isatty()。

def detect_output_mode(terminal_default="table", pipe_default="json"): try: if sys.stdout.isatty(): return terminal_default return pipe_default except Exception: return pipe_default

表格输出自己没有造轮子，直接用了rich库的Table，它能把字段对齐这种事情做到“开了挂”的水平，而且终端宽度自适应。关键是自定义fields映射：配置一个output.fields列表，表头就是字段名，值从JSON结果里按路径提取。支持user.name这样的点号路径写法，用一个小函数递归取嵌套字段。

3.5 一个能跑的完整示例

把上面几个部分拼起来，就能跑通一个最简单的HTTP任务：

tasks: - name: query-user description: 查询用户 type: http connector: base_url: "https://api.example.internal" timeout: 5 method: GET url: "/users/{id}" params: - name: id type: integer required: true output: format: table fields: [id, display_name, email]

然后启动：

python -m cli_anything --config ./tasks.yaml query-user --id 888

成功输出一张表格，失败输出一条带退出码的友好错误信息。从配置到可运行，前后代码量不超过600行。这个最小版本已经能覆盖掉团队里近一半的“查一下XX信息”类需求。

4. 落地过程中的坑与排查链路

4.1 参数类型推断：看似简单，坑最深

CLI-Anything的第一个大坑出在最不起眼的参数类型转换上。一开始我把参数类型转换全权交给click的type参数，结果遇到两个问题。

第一个问题是布尔参数。配置里写verbose是boolean，默认false，用户命令行敲--verbose，click传进回调的还是False——因为click对布尔参数的处理是“存在即True”，不存在就用默认值。这和我预期行为一致，但有个反常识的情况：如果用户想显式传False，他得写--verbose=false，而click默认的BOOL类型根本不认这种写法。我得自定义一个FlexibleBoolType才能同时支持--verbose、--verbose=true、--verbose false三种写法。

第二个问题是整数参数被YAML悄悄转换。配置里写timeout: 5，YAML解析出来的是整数5，没问题。但要是写timeout: 0.5，解析出来是浮点0.5，click的INT类型直接拒绝。可这个参数如果定义成float，用户传--timeout 5又会被转成5.0，下游模板拼接时变成5.0，和预期不符。后来我统一走“参数定义里显式声明type，加载配置时不信任YAML推断的类型”，所有参数值一律以schema里声明的type为准做强制转换。

排查这段问题时，最有用的工具是给参数绑定过程加了一个--debug-params隐藏参数，打印出最终传给执行器的类型、值和来源，一眼就能看出是YAML解析问题还是click转换问题。

4.2 输出格式的兼容性问题

第二个坑比较憋屈——输出格式早期只有JSON，被团队里偏爱看表格的人反复喷。后来加了table，又引来了新问题：table模式下，如果字段在结果里不存在，rich表会直接空着，看着像数据丢了。

排查链路是这样的：有个任务的配置里写了fields: [id, name, address]，结果返回数据里没有address字段。用户跑完说“地址没了”，以为数据丢在传输过程中。我一看，address根本没从接口返回，是上游接口把字段改名成了mailing_address。

我给输出层加了两个能力：

• 字段解析失败提示：当配置的字段路径无法在结果中找到时，输出一行警告到stderr，但表格照常渲染，数据不全时用户能立刻知道“不是工具丢了，是上游没给”。
• 字段别名：配置里可以写fields: [{name: address, alias: mailing_address}]，将接口的mailing_address映射为表格里的address列。

所以现在的字段配置支持三种写法：纯字符串、点号路径、带alias的对象。这看起来只是个小功能，但避免了很多“工具把数据弄丢了”的误解。

4.3 超时与并发控制：从单线程脚本到并发执行的蜕变

CLI-Anything一开始是同步阻塞模型，每次命令只做一个任务。但很快有人提出：我要一次查一百个用户，谁能让我在命令行里发个循环？

这个需求本质上是并发控制。我考虑了两种方案：一种是CLI层直接提供一个--parallel N参数，利用asyncio.gather并发执行同一任务多次；另一种是任务配置里支持bulk模式，一个命令内部循环处理多个参数组。

最终两种都做了，因为场景不同：--parallel适合“任意参数组合各执行一遍”，bulk模式适合“一次命令内部循环遍历”。

并发带来的坑是超时必须可控。同步模型里一个请求卡住最多卡住当前命令行；并发模型里一百个请求卡住，可能占满连接池。解决方案是给执行器强制加默认超时：HTTP连接器默认5秒，Shell执行器默认30秒，数据库连接器默认10秒；同时限制最大并发数，默认10。让--parallel 100真正并发100个连接是会打爆连接池的，所以我加了中间件，用信号量把实际并发压到配置的上限，剩余的任务排队。

另一个容易踩的坑是键盘中断。用户在并发执行时按Ctrl+C，asyncio的task会收到CancelledError，但如果执行器内部的HTTP调用不响应取消，整个进程会挂住。处理方式是捕获KeyboardInterrupt后强制取消所有task，再给连接器挂一个asyncio.timeout兜底，确保取消逻辑一定能触发。

4.4 兼容旧脚本：从wrap到替换

最后一个大坑是历史包袱。CLI-Anything做得再好，团队里还有几百个现存脚本，不可能全体一次性迁移。硬推新工具的结果一般是：新工具吃灰，老脚本继续跑。

我给CLI-Anything加了一个wrap模式，专门用来过渡。做法是在配置文件里声明一个shell任务，把原来的命令原封不动地包进来：

tasks: - name: legacy-fix-data description: 旧版数据修复脚本（兼容模式） type: shell command: "bash /opt/legacy/fix_data.sh" env: ENV_MODE: "production" params: - name: batch type: string required: true output: format: raw

wrap模式的执行器只是把参数拼进command模板，其他什么都不做。这样旧脚本的用户能用一个统一入口去调用，命令名、参数风格都逐渐规范起来，但底层还是老逻辑，风险可控。等某个脚本的迁移条件成熟了，再把type从shell改成http或db，入口命令不变，用户无感。

这个兼容层的价值，不是技术上的，而是组织上的。没有它，CLI-Anything就很难在团队里落地，因为“迁移有风险”会立在任何技术优势面前。先把入口统一了，让用户可以忍受，再逐步替换核心逻辑，是更实际的上线路径。

5. 从个人工具到团队基础设施

5.1 把内部API封装成CLI

CLI-Anything用得最多的地方，是把内部API封装成命令行工具。以前前端同事想查一个订单状态，得打开Swagger UI，找到对应接口，填一堆headers，还要自己分析返回的嵌套JSON。现在只需要一行：

cli-anything order-status --order-id SO-20240601-001

配置上也只是声明了一个HTTP任务，指向内部订单服务的GET接口。后端接口改字段了，前端同事根本不用感知——改动都发生在配置文件的output.fields映射里。

这类封装的价值在于降低了API的使用门槛。接口文档再完善，也要求使用者理解HTTP语义；CLI把交互简化到了“记一个命令名和几个参数”，即使是不熟悉curl的人也能立刻上手。

5.2 定时任务与告警联动

CLI工具和cron是天生的搭档。CLI-Anything的命令都是标准CLI，可以被crontab直接调用，退出码和stderr信息就是天然的监控信号。

我们后来在配置里加了一个schedule字段，配合一个守护进程自动把任务注册到系统的cron或K8s CronJob上：

tasks: - name: daily-sync-report type: shell command: "python /opt/reports/daily.py" schedule: cron: "0 9 * * *" notify_on_failure: - type: http url: "https://alert.example.internal/api/v1/events"

这样每天早上9点自动跑日报生成，失败时自动触发告警，成功时静默。因为所有输出都走了统一的格式化层，日志文件格式也一致，从命令行手动执行到定时任务切换，用户不需要额外写脚本逻辑。

5.3 配置仓库化与Code Review

当任务配置超过几百个时，CLI-Anything实际上已经变成了“配置即代码”的一部分。我们把所有的YAML任务配置放进了Git仓库，每次新增或修改走MR评审，CI里跑一遍schema校验和样例命令冒烟测试。

这里有一个很实际的收益：因为任务是声明式的，评审者在MR里能直观地看到参数定义和执行方式，比评审一段命令式shell脚本容易得多。一个参数类型写错了、一个连接器配置超时太长，在代码评审阶段就能抓出来，不用等线上出故障。

我还写了几个静态检查规则，比如：

• 所有HTTP任务必须声明timeout，不允许默认无限等待。
• 所有数据库任务必须显式声明只读或写，写操作需要额外审批字段。
• 所有任务必须有description，不允许生成一行“无描述”的命令。

这些规则一开始纯靠口头约定执行，后来发现完全没约束力——人总是先写能跑的功能，再补文档。所以我把规则做进了CI校验里，不满足就直接拦截。从那以后，新任务的质量稳定了很多。

5.4 演进方向

CLI-Anything做到这个程度，几个明显的演进方向已经浮出来了。第一个是远程执行，把本地CLI包装成远程服务，通过配置下发和命令代理，让团队在本地敲的命令可以安全地在跳板机或容器里执行。第二个是自动补全增强，针对动态生成的CLI生成shell补全脚本，zsh/bash/fish都全覆盖。

还有一个方向是我个人特别看好的：基于CLI工具做自动化测试。因为每个任务都有标准化的参数定义和退出码，编写自动化测试的成本大大降低——你不需要mock一个CLI进程，直接调用任务配置和模拟执行器就行。

最后说说我自己的体会。CLI-Anything不是那种“写出来就惊艳所有人”的项目，它笨重、简单、甚至有点“笨”——核心思想就是一份配置、一套流水线。但它解决了真实世界里最纠缠的问题：把散落各处的信息收拢到一处，把重复的交互抽象成一致协议。如果你手里也有上百个脚本和一堆“只有看得懂的人会用”的内部工具，我建议你别急着写下一个工具，先试试把任务描述清楚，让CLI框架替你处理剩下的事情。这个方向，大概率不会让你失望。