你有没有遇到过这种状态：电脑里堆着几十个脚本，有Python写的、有Shell写的、还有几段早忘了出处的Node小工具。想重新用的时候先得回忆它们放在哪、有什么参数、依赖装没装。我刚接触命令行自动化那几年就是这样，后来我花了几个晚上做了一个统一入口，把所有零散的脚本、任务、接口调用全部收敛到同一条命令下面。这个项目我把它叫作CLI-Anything——一个让“任何东西”都能变成命令行工具的小框架。
CLI-Anything 不是某个单一功能的轮子，而是一套把工具、脚本、API、甚至大模型能力统一收敛到命令行入口的实现方案。它能帮你把重复工作变成一条命令，把散落各处的脚本收拢成一致的调用体验，把人工操作变成可记录、可组合、可自动化的流水线。这篇文章适合正在做自动化改造、写内部工具、或者受够了碎片化脚本的开发者阅读。你可以直接抄走核心架构和实现思路，再按需扩展自己的动作库。
1. 为什么是CLI：从脚本碎片化到统一入口的价值回归
先聊一个反直觉的结论：在图形界面越来越强的今天，命令行依然是自动化场景里最值得投资的技术入口。窗口再好看，它难以被另一个程序直接调用，难以组合成管道，难以在无人值守时稳定执行。真正需要“把事情自动做掉”的场景，最后落地的形态几乎都和命令行有关。
1.1 碎片化脚本的代价
多数团队走到某个阶段都会遇到脚本失控的问题。运维脚本在A机器上，数据清洗脚本在B仓库，批量重命名工具是同事随手发的Python文件，定时任务散落在cron里。你最需要的不是再写一个脚本，而是有一个地方能统一描述“我有哪些能力、怎么调用它们、有没有副作用”。
CLI-Anything 正是冲着这个问题去的。它强调“Anything”，不是说要把所有功能都塞进一个二进制文件里，而是把入口统一在一处、把注册机制打开、把约定固定下来。插件可以是任何语言写的可执行程序，只要是能通过标准输入输出和命令行参数交流的东西，都能被纳入这套体系。
1.2 命令行的三个本质优势
第一，可组合。命令行工具天然支持管道和参数传递，你可以把“爬取内容”和“转换格式”拆成两步，再串成一条流水线。第二，可记录。命令历史、日志、脚本文件本身都是执行过的证据，哪天想复盘“我到底对数据做了什么”，看命令记录比翻操作录屏省力得多。第三，可远程。SSH到一台服务器上，没有图形界面可用，CLI就是最稳定的交互方式。
这三个优势在人工智能工具越来越流行的当下反而被放大了。模型调用需要明确的工具定义，CLI工具恰好可以作为一种“可描述、可调用”的执行单元接入到模型的工作流中。后面我会单独讲这块。
1.3 CLI-Anything 的定位边界
这套框架不是终端模拟器，也不是高级Shell的替代品。它的核心定位是“企业内部或个人的动作总线”，让使用者通过一套统一的规则快速定义新动作，并安全地暴露给需要的人或程序调用。
举个边界例子：文件处理、数据转换、服务健康检查、定时生成报告，这些适合放进来。而频繁交互的数据库客户端、编辑器这类工具，强行做成CLI反而降低效率。做框架设计时先想清楚哪些“Anything”值得收进来，哪些应该留在原处，比急着写代码更重要。
2. 核心架构拆解：一个入口、三类模块
CLI-Anything 的架构不复杂，核心思想可以用一句话概括：用统一的命令解析层接收请求，用注册表来完成路由，用插件机制来扩展能力边界。整体上分成三类模块：入口解析层、动作注册表、执行与安全模块。
2.1 入口解析层：所有操作的统一大门
这一层负责把用户在终端里敲入的命令，解析成结构化参数。比如用户输入cli-anything logs clean --days 7 --dry-run，解析层需要识别出动作名是logs clean，参数是days=7和dry-run=true。
实现上可以选择成熟的命令行解析库，Python推荐 Click 或 Argparse，Node 生态可选 Commander，Go 有 Cobra。原则是：不要自己造参数解析的轮子，把精力留给动作本身。
入口层还要负责一个容易被忽略的事：命令补全。配置好 Shell 自动补全后，用户敲一个前缀就能看到候选动作和参数提示，这会把“统一入口”的体验拉到很高的水平。Click 自带click-completion之类的扩展，基本配置一次就能在 zsh 和 bash 里生效。
2.2 动作注册表：框架的大脑
注册表解决的是“这个动作到底在哪、由谁执行”的问题。每接入一个新任务，就在注册表里登记一份元信息：动作名、描述、参数定义、执行方式、权限级别。
我把注册表设计成了一张 TOML 格式的配置文件加一个内存索引。TOML 文件负责持久化，让每个新动作都像填表一样容易添加；内存索引负责运行时快速查找，避免每次执行都解析一遍配置。
下表是我实际使用的一张注册表示例，字段可以直接套用：
| 字段 | 说明 | 示例 |
|---|---|---|
name | 动作唯一名称 | logs clean |
description | 简短描述，会显示在帮助信息中 | 清理指定天数的旧日志 |
exec | 实际执行命令 | python3 -m tools.log_cleaner |
args | 参数声明列表 | days: int=7, dry_run: bool=false |
permission | 所需权限等级 | user/admin/root |
timeout | 超时时间，防止任务卡死 | 60s |
注册机制最大的价值是“可发现性”。有了这张表，团队成员不用猜你有哪些脚本，敲一句cli-anything list就能看到所有可用动作。我在实践中发现，这东西对团队效率的提升比想象中明显得多。
2.3 执行与安全模块：守门员角色
执行模块负责按注册表信息拉起真实进程，并转发参数。这里有两个关键设计。第一，所有参数在传给真实进程前要做校验，禁止将用户输入的原始字符串直接拼进Shell命令，这个我后面会专门展开讲。第二，每个动作声明自己的权限级别，框架根据执行者身份做拦截。比如“删除服务器日志”和“查询日志条数”不应该拥有同样的权限。
安全模块还要支持--dry-run全局参数，这个参数在任何动作上都可以加。加了之后框架只打印“将要执行的命令和影响范围”，不实际执行。这个习惯如果从一开始就建立，会在后续接入AI时救你无数次。
3. 把“任何东西”变成可调用命令：核心实现细讲
架构说清楚后，就到了动手环节。我用 Python 做了一套最小可用的 CLI-Anything 实现，包括项目结构、注册机制、参数解析和执行引擎。你完全可以照这个基础自己扩展。
3.1 项目骨架与统一入口
一个合理的目录结构大约是这样：
cli-anything/ ├── pyproject.toml ├── cli.py ├── registry.toml └── actions/ ├── __init__.py ├── log_cleaner.py ├── docs_generator.py └── health_checker.pycli.py就是所有人面对的入口文件。它读取registry.toml，初始化 Click 命令组，再把注册表中的每个动作映射为 Click 命令。这样写的好处是：用户新增动作完全不用改cli.py本身，只需要在registry.toml里加一段声明，再在actions/目录下放一个实现文件。
3.2 注册表驱动命令生成
我用一段精简代码演示核心逻辑。注意它不是完整实现，但思路可以直接迁移：
import click import tomllib from pathlib import Path REGISTRY_PATH = Path(__file__).parent / "registry.toml" def load_registry(): with open(REGISTRY_PATH, "rb") as f: return tomllib.load(f) @click.group() def cli(): """CLI-Anything 统一入口""" def build_command(action): """根据注册表元信息动态构造 Click 命令""" @click.command(name=action["name"].split()[-1]) def cmd(): subprocess.call(action["exec"].split()) return cmd registry = load_registry() for action in registry["actions"]: cli.add_command(build_command(action)) if __name__ == "__main__": cli()这只是一个雏形。实际做的时候，参数声明也必须从注册表读出来，动态构造click.option，才能真正实现“改配置即加命令”。我已经跑通这套流程，完整版的build_command会解析args字段里的类型和默认值，再映射到 Click 的参数模型上。
3.3 动作实现的标准协议
为了让所有动作都能被框架统一调度，我建议每个动作实现成可以被命令行单独运行的小程序，使用结构化输出。比如日志清理工具，它的标准接口长这样：
usage: log_cleaner.py --days=7 [--dry-run] [--path=...]为什么要强调“可以被单独运行”？因为调试时直接执行这个动作比每次都走一遍主入口要快得多。框架只需要负责组装参数和捕获输出即可。
为了避免子动作的输出污染主程序的判断逻辑，我推荐两个约定：普通提示输出走 stdout，机器可读的结果统一输出成 JSON 结构。比如清理完成后输出{"deleted_files": 120, "freed_mb": 34.5}，主程序就可以基于这个结果做后续通知或记录。
3.4 真正的执行引擎长什么样
如果只是简单转发命令，这套框架和写一堆 alias 没区别。执行引擎的价值在于四个附加能力：
- 统一日志记录：每次执行的动作名、参数、耗时、退出码都追加到
~/.cli-anything/history.log - 超时控制：设置超时时间，超过时间杀掉子进程并标记失败，防止个别动作卡住终端
- 输出捕获与预览：把子进程的 stdout 和 stderr 捕获起来，超过阈值只显示摘要
- 干跑模式：预先生成完整的执行计划，但不真正调用
这四个能力中，干跑模式和统一日志尤其重要。统一日志让我可以随时回答“这个环境今天被谁改过、跑过什么命令”；干跑模式则让高风险操作在执行前多一道人工确认的环节。
注意：把执行引擎和动作实现分开，可以避免每次新增动作都要动主框架。执行引擎是通用的，动作实现是插拔的，这是整个 CLI-Anything 能够“Anything”的关键。
4. 接入AI出口：让自然语言也能驱动命令行工具
CLI-Anything 如果止步于手动敲命令，就还停留在“脚本收集器”的阶段。真正让它变得现代且好用的，是我后来做的 AI 接入层。这也是我一开始设计“命令可发现、参数可描述、执行有边界”的原因：所有这些都是为了让大模型能够安全地调用这套工具。
4.1 让模型认识你的工具
接入 AI 的起点，是把注册表里的动作转换成模型能理解的结构化描述。你可以将每个动作的信息生成一个 JSON，包含动作名、功能说明、参数含义和使用样例。这个大列表就是“工具说明书”。
例如日志清理的动作可以这样描述：
{ "name": "logs_clean", "description": "清理超过指定天数的日志文件", "parameters": { "days": {"type": "integer", "default": 7}, "dry_run": {"type": "boolean", "default": true} } }把这个 JSON 列表放到模型 API 的工具调用参数中，模型就可以在需要时主动询问“要不要清理一下日志”，或者在你用自然语言提出需求后，自动组合出对应的命令行动作调用。
4.2 三种自然语言驱动方案对比
我在项目中试过三种方案，分别有不同适用场景：
| 方案 | 原理 | 适用场景 | 优缺点 |
|---|---|---|---|
| 关键词映射 | 将自然语言分词后匹配动作名和参数 | 本地优先、避免外部 API 依赖 | 实现简单，但语义理解有限 |
| 语义路由 | 用向量数据库或本地 embedding 匹配用户意图与动作描述 | 动作库较大且描述较规范时 | 需要维护 embedding 索引，增大磁盘占用 |
| LLM 函数调用 | 调用大模型 API，传入工具定义，让模型返回结构化调用参数 | 需要理解复杂意图时 | 最灵活，但每次调用都有成本和时延 |
我的实际建议是“三级联动”：先尝试关键词匹配，匹配不上时用语义路由兜底，实在不行才调用 LLM 函数调用。这样绝大多数高频命令可以不经过大模型，省下的时延和成本非常可观。
4.3 安全漏斗：AI 建议、人来执行
接入 AI 最大的风险不是模型答错，而是模型生成的命令被直接执行带来的破坏。我给自己定了一条铁律：AI 的产出只能是“建议”，必须经过确认漏斗才能进入执行引擎。
流程是：模型根据用户意图生成动作调用参数，框架将其可视化地展示成“将要执行：cli-anything logs clean --days 7 --dry-run”，然后等待用户按y确认。如果要做成无人值守的自动执行，也必须限定在白名单动作和沙箱环境中。
这个细节值得你从一开始就想清楚，否则你的 CLI-Anything 会变成一个隐患而不是生产力工具。
5. 实测案例：三个我天天在用的 CLI-Anything 插件
理论说得再多，不如看几个实际跑起来的例子。我目前日常高频使用的插件有三个，每个都产出了真实价值，而且都是在半天内写完并接入注册表的。
5.1 日志与临时文件清理
第一个插件是logs clean和tmp prune，解决的是服务器磁盘被日志打爆的问题。检测脚本每天早上通过定时任务执行，如果发现磁盘占用超过 80%，就自动生成一条清理计划并发送到运维群。
动作实现逻辑不复杂：遍历指定目录，找修改时间超过 N 天的.log和.tmp文件，按大小排序后，输出准备删除的文件列表。配合--dry-run参数，可以在执行前人工确认。这个插件一个月大约能清理出 20GB 到 50GB 空间，核心价值是“不再需要 SSH 上去敲一串 find 命令”。
5.2 批量接口健康检查
第二个插件是health check，批量检查多个服务的 HTTP 接口是否正常。我给它配置了一个 JSON 文件，里面记录每个服务的名称、URL、期望状态码和超时时间。
cli-anything health check --env=prod --concurrency=10执行后插件会并发请求，收集结果，输出一个简短的 Markdown 表格。如果有关键服务失败，执行引擎会追加一条失败标记，方便后续接告警。它能发现的问题比普通 ping 多得多，比如接口返回 500、响应时间超过阈值、证书即将过期等。
这个插件最大的启示是：CLI-Anything 不仅适合管理本地脚本，也适合把团队成员需要重复执行的“查询类操作”封装成统一命令，比如查线上配置、查版本信息、查延迟分布。
5.3 从代码注释生成项目文档
第三个插件是docs gen，它的功能是扫描代码仓库中的关键函数和注释，结合文件结构，生成一份初步的 Markdown 文档。这对需要维护内部项目的团队帮助很大，新人入职时跑一条命令就能拿到项目概览。
实现上用的是正则加简单分词，老实说离真正的智能还有距离，但作为“第一版草稿”已经足够好。配合 AI 接入层后效果更佳：模型阅读源码后补全说明文字，再交由人工润色。这个插件让“文档长期没人写”变成了“文档每天自动更新底稿”。
6. 必须面对的坑：转义、权限与依赖的实战笔记
最后这部分专门写给已经决定要动手做的人。CLI-Anything 这类工具，表面上是很好玩的上层封装，实际工程化之后会碰上一堆真实问题。我踩过的坑，希望你能提前绕开。
6.1 参数转义与通配符陷阱
最经典的问题：用户在参数里传了一个带空格的路径，或者一个包含*的字符串，如果你直接用 f-string 拼命令，轻则参数失效，重则执行了完全不同的命令。我在 6.2 会专门讲安全，哪怕只从功能完整性角度来看，转义也是一个绕不过的坎。
解决方案是“禁止拼接 Shell 字符串”。如果你的动作实现是 Python 或 Node 程序，尽量用subprocess.run(args_list)直接传参数列表，让系统替你解决转义。如果是调用现成的其他 CLI 工具，也要显式指定参数，而不是通过shlex.join后再交给 shell。
6.2 命令注入：框架最致命的安全风险
现在必须把话说重一点。只要你的工具被两个人以上使用，或者计划接入 AI，命令注入就是你首先要堵的死角。攻击方式通常是精心构造参数值，比如恶意传一个--path="; rm -rf /"之类的字符串，如果你的执行层把它拼进 shell，后果不堪设想。
防御手段按顺序有三层：
- 参数列表化，不走 shell
- 对动作名称做白名单校验，杜绝“用户传入任意命令”的设计
- 权限分级，高风险动作必须走二次确认
我把这三条写进了代码评审纪律里。凡是新提交的动作实现，第一关先看参数有没有经过--dry-run，第二关看它有没有权限校验，缺一不可。
提示：永远不要提供“直接执行用户输入字符串”的通用命令。如果确实有临时执行脚本的需求，也要设计成只能从指定目录读取脚本，而不是接收任意路径。
6.3 跨平台路径与运行时依赖
如果你的工作环境横跨 Linux 和 macOS，很多细节会出问题。比如/tmp在 macOS 上的语义和 Linux 不同，路径大小写敏感也不一样，find命令的参数更是千奇百怪。解决思路是：凡是涉及文件系统操作的动作，尽量用语言内置的Path类处理路径，而不是依赖 shell 命令。
依赖管理同样容易失控。每个插件如果都依赖不同的第三方库，最终会演变成环境冲突。我的做法是：每个动作目录里放一个requirements-action.txt，按动作隔离虚拟环境。虽然占一点磁盘空间，但能让“加了新插件不破坏老插件”这个承诺始终成立。
6.4 测试与回归策略
CLI-Anything 的测试我推荐两条路。第一，框架层用快照测试，把注册表解析后的命令树序列化成文本，任何改动造成意外变化都会在测试中暴露。第二，动作层用“黄金文件”测试，将输出结果与预期 JSON 进行 diff。
更重要的是保持“不真实调外部服务”的测试习惯：健康检查插件要允许传入本地 Mock 服务地址，日志清理插件要允许在一个临时目录里创建假文件。等真实环境出了问题再调试，分析成本高得多。
我在做测试时还养成了一个习惯，就是定期翻看history.log，观察哪些动作被高频调用、哪些动作从未被调用。从未被调用的动作通常是重复造轮子的产物，该删就删，保持框架轻量。
最后再分享一点我的实际体会
做完 CLI-Anything 之后，我最大的感受不是“写了多少行代码”，而是工作方式被悄悄改变了。以前想给团队提供新能力，需要写文档、教操作、解释依赖环境；现在只需要加一条注册记录，再补一个动作实现，大家用一条命令就能完成。看见cli-anything list里列出的动作越来越多，有一种“工具箱越来越衬手”的真实感。
如果你也想动手做一套，我的建议是从最小用例开始。不要一开始就规划几十个动作，先挑一件你每周都会重复三遍以上的事，把它接入框架，养成“所有操作都从统一入口走”的习惯。等习惯成型后再慢慢扩展，才会真正体会到这套模式的价值。
