万物皆可CLI：用YAML声明式配置统一封装HTTP服务的命令行工具

作为一个常年泡在终端里的人，我有个执念：凡是每天要操作超过三次的东西，都应该给它配一个命令行入口。很多项目火起来，靠的就是把高频操作从图形界面里解放出来——比如用gh命令替代在网页上点GitHub。但现实是，大部分服务和工具并没有官方CLI，要么只有残缺的API，要么只有个简陋的Web界面。所以过去两年，我一直在维护一个叫CLI-Anything的框架，专门把这些“没有CLI的东西”用声明式配置封装成统一风格的命令行工具。这个项目解决的核心痛点很简单：你不需要为每一个服务写一套独立的Python/Node脚本，而是写一份YAML配置，CLI-Anything负责把它变成带参数解析、帮助文本、鉴权管理和自然语言入口的标准CLI。

这篇文章我会把CLI-Anything的设计思路、核心模块、一次完整的从零接入实例，还有我在实际维护中踩过的坑，一次性讲清楚。不管你是想给团队内部系统做个命令行工具，还是单纯想周末把家里那台NAS的下载任务塞进终端，这篇都适用。

1. 项目整体设计与思路拆解

1.1 为什么我觉得“万物皆可CLI”

先说说这个项目的起点。我发现一个奇怪的现象：开发者的效率工具几乎都在终端里，但各种业务系统、家用设备、在线服务的管理方式却仍然被网页和App绑架。下载任务得打开Web UI，服务器监控得登录面板，内部工单系统得点浏览器书签。这不是不能用，而是效率差距太大——终端的优势不是好看，而是可以被组合、被脚本化、被批量执行。你在终端里可以做这样的事：nas add-magnet http://xxx，然后它的输出会自动进入shell的管道，被下一步脚本消费。这在图形界面里几乎不可能实现。

所以CLI-Anything最初的定位就是：一个把任何HTTP API、Web页面操作或本地脚本统一适配为子命令的通用框架。它不做具体的业务，只做“包装”这件事。你给它一份描述文件，告诉它服务端点和参数规则，它就把那些能力暴露成服务名 动作 参数这样的标准命令。这个思路类似Ansible的思想——用声明式描述替代命令式编写，但又比Ansible轻得多，完全面向单机个人效率场景。

1.2 核心方案选型：为什么用声明式配置而不是写代码

在设计CLI-Anything初期，我其实先尝试过另一种方式：提供一个Python基类，让使用者为每个服务写一个继承类，重写execute方法。这种方法灵活，但有一个致命问题——每接入一个服务，你就多了一段需要测试和维护的代码。而且对非Python开发者来说，这个门槛不低。

后来我推倒重来，改成了配置文件驱动。核心决策是：把“命令树结构”和“HTTP请求细节”从代码里剥离出来。一份配置长这样：

service: nas base_url: http://192.168.1.100:6800/jsonrpc auth: type: token token_env: ARIA2_TOKEN commands: - name: add method: POST path: /api/downloads params: url: type: string required: true help: "磁力链接或直链地址" dir: type: string required: false default: /data/downloads help: "保存目录"

这份配置没有任何业务逻辑，它只描述“怎么调用”和“长什么样”。CLI-Anything读取后会做三件事：构建子命令解析器、生成帮助文档、执行HTTP请求并格式化输出。这个设计的优点在于——配置本身就是文档，新接入服务时不需要读源码，改完配置立即生效，甚至可以动态重载。当你需要接入第5个、第10个服务时，这个优势会被放大得特别明显。

1.3 命名空间与命令树：避免工具之间的“地盘冲突”

CLI-Anything还有一个重要设计：它支持将多个服务组合在一起统一调用。你可以在一个入口下挂载不同服务的全部命令。比如我习惯用anything作为总入口，然后每个服务作为一级子命令。

anything nas add-magnet http://xxx anything cloud sync-photos anything nas list-tasks anything pm2 restart blog

实现方式是配置合并。每个服务可以单独写一个配置文件，放在~/.config/cli-anything/services/目录下，主程序启动时会扫描该目录并自动合并命令树。这个设计意味着团队里不同成员可以维护各自负责的配置文件，互不干扰，最后在各自本地组合出一个统一的“总控终端”。

这里有一个细节点值得注意：主程序没有硬编码任何服务名，而是从配置文件的service字段动态读取。这天然支持了命名空间隔离——例如两个服务都定义了list命令，但在不同的命名空间下就不会冲突。我见过太多工具把命令名硬编码在代码里，结果扩展一个模块就要改主程序，非常不利于演进。

2. 核心模块拆解与实现细节

2.1 命令树自动构建：从YAML到argparse

CLI-Anything的命令树构建是整个项目的骨架。它用的是Python自带的argparse，但没有直接把配置照搬到argparse，而是先建立了一个中间表示层。

中间表示层其实是一个嵌套的字典结构，以服务名为根，命令为二级节点，参数为三级节点。构建步骤可以拆成四层：

1. 读取所有配置文件的service段，生成根解析器。
2. 遍历每个服务的commands字段，为每条命令创建子解析器。
3. 根据params的类型声明（string/int/boolean/choice/enum）自动推断传参方式。
4. 生成统一的--help文本，但允许配置覆盖默认帮助描述。

关键的设计取舍是我没有采用动态导入插件的方式。很多类似项目做成“插件式”，要求每个服务必须是一个Python包。这增加了自定义成本，所以我拒绝了这个方案。在CLI-Anything里，哪怕你不会写Python，也能新接入一个服务。

类型系统是这里最容易出错的部分。配置声明了type: int，传参时就会自动做数值校验；声明了type: choice，命令行参数补全时会列出可选值。这个类型映射层整体上承担了“配置可读性”和“运行时安全性”之间的桥梁。我推荐所有字段都显式声明类型，而不是依赖默认的string，否则后面做参数提示和校验时会漏掉很多错误。

2.2 HTTP适配器：把REST API请求映射为本地函数调用

CLI-Anything的HTTP适配器设计，是整个框架真正的主体部分。它把“命令调用”翻译成“HTTP请求”，再把“JSON响应”格式化成“终端表格”。这个过程里最核心的是模板变量解析。

模板变量解析解决的是“RESTful路径参数”问题。看这个例子：

commands: - name: delete-task method: POST path: /api/tasks/{task_id}/delete params: task_id: type: string required: true help: "任务ID"

用户输入anything nas delete-task "abc123"后，适配器会做三步处理：

1. 将路径中的{task_id}替换为用户传入的值。
2. 将剩余参数拼接到query string，如果method是POST，把参数序列化成JSON body。
3. 将请求头加上认证信息，由auth配置段提供。

关于请求体和响应处理，这里要补充一个实操细节：不要把响应的JSON原文直接打印出来。默认的终端输出应该是摘要化的表格。CLI-Anything内置了一个简单但很实用的响应模板机制，类似Go语言的text/template。你可以配置输出哪些字段、用什么对齐方式、是否把嵌套JSON展开成多行。很多工具人项目做到“能调通API”就结束了，但CLI工具的体验好不好，最终拼的就是输出美化这个环节。

2.3 认证与上下文：token、cookie和密钥的持久化

CLI接入内部系统时，第一道门槛就是认证。CLI-Anything实现了三种认证方式：静态Token、动态登录、请求头注入。静态Token最简单，直接在配置里引用环境变量名，但很多服务需要先POST一次认证接口换取session，这就是动态登录的场景。

动态登录的配置如下：

auth: type: login login_path: /api/auth/login credentials: username_env: MYAPP_USER password_env: MYAPP_PASS session_store: ~/.local/state/cli-anything/sessions/myapp.json

处理逻辑是：第一次执行命令前检测本地session文件，如果不存在或已过期，则自动调用login接口，把返回的cookie或token写入session文件。这其中有几个关键细节值得展开：

• session文件必须设置权限为600，因为它包含明文cookie。
• 登录接口的响应字段名可以配置，例如token_field: data.token，用点号路径解析嵌套字段。
• 支持preemptive_refresh: true选项，在token剩余有效期不足10分钟时自动重新登录，避免请求执行到一半突然401导致命令失败。

我强烈建议所有接入服务都优先支持动态登录而不是静态Token。因为静态Token一旦泄露，等于把服务的钥匙随便钥匙环上挂着。动态登录至少让凭证只在本地存在，并且可以设置过期时间。

2.4 自然语言入口：当大模型遇上命令行

CLI-Anything后期加的一个相对创新的功能是自然语言入口。初衷是：虽然CLI很高效，但记不住命令和参数永远是痛点。于是我把大模型的解析能力直接编译进系统里——输入的不是严格语法，而是口语化的意图描述。

anything "帮我把那个最新的磁力链接加到下载列表"

这个功能本质上是一个“意图到命令树节点”的映射。它的实现思路是：把已经加载的命令树序列化成JSON schema，然后构造一个prompt，要求大模型输出结构化的命令调用。这里的技巧是不要让大模型自由发挥参数，而是让它先输出JSON，再经过校验后交给解析器执行。

{ "service": "nas", "command": "add", "params": { "url": "magnet:?xt=urn:btih:xxxx", "dir": "/data/downloads/incoming" } }

校验层很关键：如果意图不明确或参数缺失，它不会瞎编，而是返回一个交互式提问，让用户补齐。这种“先识别命令，再严格校验”的方式，避免了凭空生成不存在的子命令的问题。对不常用但偶尔要用的命令，这个自然语言入口非常顺手。不过我也得说句实话：它依赖模型和网络，稳定性远远不如纯本地解析，所以它只是辅助路径，不是主路径。核心操作还是应该靠命令树本身。

3. 实操演示：把Aria2的下载任务接入CLI-Anything

3.1 场景设定与准备工作

这一节我用一个完整的真实案例走一遍流程：对接Aria2的JSON-RPC接口，把“添加磁力链接”“查询任务列表”“暂停/恢复任务”这三个高频操作变成本地CLI命令。选择Aria2的原因有两个：一是它的HTTP接口是标准的JSON-RPC，协议简单；二是能非常直观地展示CLI-Anything如何处理POST请求、方法名映射和复杂响应的格式化。

第一步是确认环境。CLI-Anything需要Python 3.9+，安装方式很简单：pip install cli-anything。Aria2需要开启RPC服务，启动时加参数--enable-rpc=true --rpc-listen-all=true --rpc-secret=mysecret。这里提醒一下：RPC端口默认6800，如果暴露到公网，一定要用防火墙限制来源IP，否则别人可以直接往你的下载器里塞任务。

3.2 编写Aria2服务的配置文件

先看完整配置：

service: aria2 base_url: http://127.0.0.1:6800/jsonrpc auth: type: token token_env: ARIA2_RPC_SECRET header_key: Authorization header_template: "Basic {token}" rpc_method_field: method commands: - name: add rpc_method: aria2.addUri params: urls: type: list required: true help: "下载链接列表" options: type: object required: false help: "下载选项，如 {'dir': '/data/downloads'}" output: - task_id: result - status: "已提交" - name: list rpc_method: aria2.tellActive output_table: true output_columns: - gid - status - totalLength - completedLength - name: pause rpc_method: aria2.pause params: gid: type: string required: true help: "任务ID（从list获取）"

这里说明几个配置要点。rpc_method_field指定JSON-RPC请求体中存放方法名的字段，默认是method，如果对接其他RPC服务可能是action或operation，需要按实际情况调整。auth段的header_template支持把token包装成特定格式的请求头。

urls类型为list时，CLI-Anything支持两种传参方式：命令行里用逗号分隔"http://a,http://b"，或者重复传参--urls http://a --urls http://b，内部统一解析成列表。

output段是做响应映射的。result是Aria2返回的gid字段，映射到本地的task_id。output_table: true则让list命令的结果自动对齐成表格，字段名直接取JSON响应中result数组里对象的键。

在这个配置里有一条安全细节必须强调：token_env的值是环境变量的名称，不是token本身。也就是说你的配置文件里不会出现任何密钥明文，token从环境变量读取。我建议在~/.bashrc或~/.zshrc里用export ARIA2_RPC_SECRET=$(secret-tool lookup aria2-rpc)这种方式管理，而不是硬编码。

3.3 运行CLI-Anything并验证命令

配置文件放到~/.config/cli-anything/services/aria2.yaml之后，直接在主程序目录执行：

anything

会看到自动生成的帮助信息，列出了所有已加载的服务和命令。然后测试添加任务：

anything aria2 add "magnet:?xt=urn:btih:abcd1234" --dir "/data/downloads/movies"

closer大致的执行流程是：CLI-Anything读取配置，解析参数，构造JSON-RPC请求，携带Authorization头，POST到http://127.0.0.1:6800/jsonrpc，然后解析响应并输出。终端上会看到类似这样的输出：

task_id: 12345678abcdef status: 已提交

验证列表命令：

anything aria2 list

输出会根据配置映射成表格。这里有个我一直坚持的细节：响应字段名保持原样，不做“智能”翻译。totalLength就是totalLength，而不是强行变成总大小。原因很简单：CLI工具的首要目标是精确和可靠，中文字段映射放在配置里是一个显式动作，如果引擎自动翻译反而容易产生误导。

3.4 进阶：把组合操作封装为一条自定义指令

单条命令对接完之后，下一个自然需求是组合操作。比如“看一下下载列表里有哪些任务已经完成”——这在Aria2里其实要查两个接口：tellActive和tellStopped。CLI-Anything支持一种简单的编组脚本。

composite: - name: list-all steps: - command: aria2 list - command: aria2 list-stopped

引擎会把两个子命令的输出合并到一处，用分隔线隔开。这种“组合命令”非常适合那些固定要执行多步的运维场景。我常用的一个例子是重启服务并查看日志：先执行重启命令，然后tail日志的最后100行。把这两步写成组合命令后，就从两条命令加管道，简化成了一行。根据我自己的经验，组合命令功能虽然简单，但它解决了“把操作流程固化为工具”这一核心需求，真正把CLI从单次操作工具升级成了流程工具。

4. 常见问题与排查技巧实录

4.1 参数类型推断导致的“差之毫厘，谬以千里”

CLI-Anything在最初版本有个设计失误：如果配置里没写type，默认当作字符串处理。这在大多数场景没问题，但遇到数字型参数就翻车了。比如Aria2的pause命令，gid从接口里拿到时是字符串类型，但如果某个服务的接口要求数字ID，引擎把"9527"当字符串传过去就会报错或产生不可预期行为。

排查这类问题的经验是：在所有接口对接初期，先抓包看请求体。CLI-Anything支持--dump-request开关，会把即将发出的HTTP请求原样打印出来。对照接口文档看一遍，类型对不对、字段名对不对、嵌套结构对不对，一眼就能发现。这个开关给我省下的排查时间不可估量。如果对比后仍然不对，再去检查配置文件的类型声明。

4.2 认证过期：命令跑到一半突然401

动态登录模式最典型的坑是token过期时效。很多内部系统默认access token有效期只有15分钟，而CLI-Anything默认只在启动时校验一次session。如果你开着终端挂了好久，突然执行一条命令，可能就会收到401。

我在auth段加了以下机制来缓解：

auth: type: login session_store: ~/.local/state/cli-anything/sessions/myapp.json retry_on_401: true

retry_on_401的作用是：如果请求返回401，引擎会自动重新登录一次，然后用新session重放请求。这个重试只做一次，避免陷入无限循环。要注意的是，重放请求必须保证幂等性。对于POST创建类操作，重放可能导致重复创建，因此在重试前会检查请求是否是幂等的，非幂等请求只报错不重试。

4.3 命令嵌套层级过多，记忆成本过高

还有一个容易忽视的问题：命令树设计。很多使用者接入服务时习惯把路径映射成很深的层级，比如anything server production docker compose restart。CLI确实是树状结构没错，但如果一层一层拆得过多，用户记不住，命令行补全也救不了——因为没有人愿意敲那么多层级。

我自己设计命令树时有一个经验法则：在一条命令里，服务名加动作不要超过三个词。能合并成子命令的就尽量合并。例如上面的命令，就应该设计成anything server-compose restart --env prod。配置时可以在commands节点的name里用驼峰或连字符来承载一部分上下文，从而减少层级。命令是给人用的，简化永远是第一优先级。

4.4 常见问题速查表

现象	可能原因	解决办法
命令找不到服务	配置文件没放在services目录，或文件名与service不一致	检查配置文件位置，确认service字段唯一
请求401	Token过期、动态登录失败、header格式不对	开启--dump-request抓包；检查header_template
输出是JSON原始字符串	没配置output或output_table	按响应结构增加output映射或表格字段
参数传了但不生效	参数名与接口字段名不一致	对照接口文档检查schema字段的path与params键名
命令执行非常慢	动态登录每次请求都触发或超时设置过长	查看session是否持久化；设置timeout: 5（秒）

4.5 高亮：安全配置的三个“一定要”

最后单独把安全相关的经验拉出来说，是因为这里出过真实事故。一位使用者把token直接写进了配置文件，然后顺手把配置推到了GitHub仓库，等于直接把内部系统的钥匙公开了。

1. 一定不要把任何密钥明文写入配置文件，一律用token_env引用环境变量。
2. 一定不要把配置文件目录纳入任何同步盘。CLI-Anything的目录最好放在~/.config/cli-anything/，并且用chmod把整个目录权限设为700。
3. 一定不要在配置里使用过大的超时值。timeout我建议默认设成5秒，即使调API，10秒也足够了。过长的超时等于允许恶意请求长时间占用连接资源。

安全这块没有“够了”的时候。工具只要在本地落地，配置文件的暴露风险就会一直存在，与其事后补救，不如一开始就把安全习惯嵌入配置习惯。每次新接入一个服务，我建议把安全清单当成测试用例一样过一遍。

5. 我在实际维护中积累的三个体会

这个项目我从零写到现在也维护了两年多，最后分享几条没有写进官方文档的体会。

第一个是：CLI工具的生命力不在于它支持多少功能，而在于它能不能让你形成肌肉记忆。当一个命令敲了十遍以上，就会从“回忆”变成“本能”。我用了两个月之后，anything aria2 add这套命令已经完全不需要想，像是手指自己会弹一样。好的CLI设计应该追求这个效果。

第二个是：不要为了抽象而抽象。CLI-Anything早期有个middleware体系，看起来很高大上，实际上90%的场景根本用不到。后来我砍掉了大部分middleware接口，改成了最原始的步骤钩子，反而代码维护起来轻松很多。很多工具项目死于过度架构，这句话做开源之后体会更深刻了。如果你的配置使用者根本不需要扩展Java式的插件体系，那就一定不要提供——因为你一旦提供，就有半分之五十的机会要去兼容那些没人用的扩展点。

第三个是：就算有了自然语言入口，命令行语法的学习仍然是值得的。大模型解析确实让门槛低了很多，但它依然是概率性的，永远不会像语法解析一样确定。CLI-Anything给我的最大收获，是让我重新审视了“人机交互”这件事——图形界面提供了低门槛，但命令行提供了可控性。最好的方案不是二选一，而是像这个项目做的一样，同时保留两条路，让用户在场景之间自由切换。

如果以后有时间，我打算给CLI-Anything加上配置的可视化调试界面，以及更完善的shell补全脚本生成器。但目前这个状态，它已经是我日常效率工具箱里打开率最高的工具了。