CLI-Anything：统一命令行入口，让所有脚本一键管理

上周我又一次经历了自己给自己添堵的名场面：想找一条半年前跑过的数据迁移脚本，翻了十几屏终端历史没找到，又去翻项目文档也没记录，最后只能凭模糊记忆重新拼了一遍。类似的场景我猜大家都不陌生——自己的工具越攒越多，它们散落在全局 bin 目录、项目 scripts 里、dotfiles 中，有些干脆是某次临时操作留下的孤本。

所以我动手做了CLI-Anything。它不是一个"又一个命令行工具"，而是一个可插拔的命令行聚合入口：把任意脚本、任意语言、任意接口，全部变成anything <子命令>下的一个插件。项目起名 Anything 不是噱头，而是它真的什么都能收——Node 写的、Python 写的、纯 bash 拼的、甚至是一段远程 API 调用，只要能跑，就能挂进来。

这篇文章我会把它的设计思路、插件协议、核心实现和踩过的坑完整写出来。适合谁看？三类人：手头积攒了各种小脚本但从来没归档的开发者；想在团队里统一分发内部工具而不想每次口头传文件的工程师；以及想把 AI 能力和现有命令行工具串起来的人。

1. 从"命令一团糟"到统一入口：CLI-Anything 到底在解决什么

1.1 散落工具的三宗罪

先说痛点。我复盘了自己过去一年的终端使用习惯，发现手上的工具有三种形态：全局安装的 CLI 工具、项目里定义的 npm scripts、以及一堆躺在某处的一次性 shell 脚本。它们的共同问题是没有统一入口。

举几个真实场景。同事给我传了个内部发布脚本，我把它丢进 /tmp，跑完一次就忘了，下次要用只能再找他要。我自己的项目脚手架脚本存在 ~/scripts 下，每次新建项目都要先想一遍"那个脚本到底叫啥来着"。还有一类工具是组合型的——"先 lint 再单测最后构建"，每次都要手动敲三条命令，敲错一个参数就白跑一轮。

这就是第一宗罪：无统一入口。第二宗罪是无发现机制。全局 bin 下的命令装多了，连自己都记不全；第三宗罪是共享靠口头，团队里每个人维护着自己的一份脚本，版本漂移、参数不一致是常态。

1.2 改造前后的真实对照

我做了一张表，用来跟团队描述这个项目的价值，也分享给你参考：

注意最后一行，CLI-Anything 里的插件不一定是"自己实现功能"，它完全可以是一个调度器，把现有命令按顺序编排起来。这一点后面在实战案例里会专门展开。

1.3 三个硬性设计目标

带着上面的痛点，我给 CLI-Anything 定了三个设计目标，后面所有实现都围绕它们展开：

第一，插件协议必须语言无关。我不能规定插件只能用 Node 写，否则和再造一个 npm scripts 有什么区别。一个插件只要是"一个目录 + 一个声明文件 + 一个可执行入口"，CLI 就该能把它跑起来。

第二，命令解析由元数据驱动。插件的名称、参数、用途全部声明化。这样anything help可以自动生成帮助文档，模糊搜索有据可查，甚至未来做自然语言入口，AI 也能读懂插件清单。

第三，输出必须可组合。命令行生态最值钱的东西是管道（pipe）。我要求插件在非交互模式下输出 JSON，这样anything db:q "select ..." | anything ai:explain这种组合才可能成立。

2. 插件协议设计：凭什么把别人的脚本也变成你的子命令

2.1 一个插件就是一个目录

插件的最小单位是一个目录，放在~/.anything/plugins/下面。目录里有三样东西：声明文件plugin.json、入口脚本、以及插件自己需要的任何资源文件。目录名不重要，真正起作用的是plugin.json里的name字段。

~/.anything/plugins/banner/ ├── plugin.json └── run.js

plugin.json是插件的身份证，字段如下：

为什么参数要声明化？因为这样别人不需要看源码就能自动获得帮助。anything help banner会打印出每个参数名、类型、是否必填、用途。普通脚本把参数约定写在自己脑子里，CLI-Anything 把约定写成了数据。

2.2 两个最小插件，用不同语言写

先看一个 Node 插件的完整代码。plugin.json：

{ "name": "banner", "description": "输出一个带颜色的横幅文字", "version": "0.1.0", "runner": "node", "entry": "run.js", "parameters": [ { "name": "text", "type": "string", "required": true, "description": "要展示的文字内容" } ] }

run.js：

const chalk = require('chalk'); const index = process.argv.indexOf('--text'); const text = process.argv[index + 1]; console.log(chalk.bold.cyan(`== ${text} ==`));

注意这里插件直接读取process.argv拿参数。CLI-Anything 不会替插件解析参数再传对象，而是把用户输入原样透传给插件进程。这样对插件作者零约束：你想用process.argv、yargs、还是自己手写解析都行。

再看一个同功能但用 Python 写的插件。plugin.json里只改两个字段：

{ "runner": "python", "entry": "run.py" }

run.py：

import sys flag = "--text" idx = sys.argv.index(flag) text = sys.argv[idx + 1] print(f"== {text} ==")

命令还是anything banner --text "hello"，CLI 内部做的事情是：读plugin.json拿到 runner 和 entry，然后 spawn 对应的解释器进程。CLI 完全不需要关心插件是什么语言写的，这就是"Anything"字面意义的实现基础。

2.3 用元数据动态生成命令行

CLI 入口文件的核心逻辑是遍历所有插件，为每个插件动态注册子命令。我用 Commander 实现，核心代码如下：

const { program } = require('commander'); const { loadPlugins } = require('./registry'); const plugins = loadPlugins(); for (const plugin of plugins) { const cmd = program .command(plugin.name) .description(plugin.description); for (const param of plugin.parameters || []) { const flag = `--${param.name} <${param.type}>`; cmd.option(flag, param.description, param.default); } cmd.action(async (options) => { await runPlugin(plugin, options); }); } program.parse(process.argv);

这段代码的核心在于：插件本身不写任何命令行解析代码。参数列表来自plugin.json，Commander 负责生成--text、--host、--port这类 flag，用户拿到的帮助信息也完全由元数据驱动。插件只需要在入口里把自己关心的参数从process.argv里抠出来用。

为什么这样设计？因为大部分脚本项目里，真正复杂的不是业务逻辑，而是 CLI 外壳：解析参数、处理帮助、做校验。把这些全部收敛到框架里，写插件的人只需要关心"给定参数，输出结果"这件事。插件协议越薄，愿意往里塞东西的人就越多。

3. 插件发现与模糊查找：只记得半个命令也能跑起来

3.1 插件从哪来：三个搜索层级

CLI-Anything 的插件搜索路径有三个层级，按优先级从高到低排列：

1. 项目级：.anything/plugins/目录，从当前目录逐级向上查找。存放这个项目专属的工具，比如数据库连接脚本、项目脚手架。
2. 用户级：~/.anything/plugins/目录。个人通用的工具，比如 git 辅助脚本、文档生成器。
3. 全局级：/usr/local/lib/anything/plugins或 npm 全局安装的插件包。通常是团队分发的工具集。

冲突处理规则是：项目级的同名插件覆盖用户级和全局级。理由很好理解——同一个命令deploy:prod，在 A 项目里可能是部署静态站点，在 B 项目里可能是同步数据库，按项目隔离才是最符合直觉的。

3.2 模糊匹配：打错名字也能找到工具

我早期遇到过一个问题：插件多了之后，用户压根记不住确切名字。ops:health写成opshealth、qa:all写成qa，都是常见操作。所以我把模糊匹配做进了入口逻辑。

实现思路有两种，我最终选择了组合方案：

const Fuse = require('fuse.js'); function findPlugin(keyword) { const exact = plugins.find(p => p.name === keyword); if (exact) return exact; const fuse = new Fuse(plugins, { keys: ['name', 'description'], threshold: 0.4 }); return fuse.search(keyword).slice(0, 1)[0]?.item || null; }

先用精确匹配，找不到就上模糊搜索。搜索的 key 不仅有name，还有description。这意味着用户可以用"查数据库"这种自然语言去搜，也能搜到db:q这个插件。这比死记命令名友好太多。

3.3 交互式选择：多个候选时让用户挑

模糊搜索还有一个衍生问题：命中多个插件时，到底执行哪个？我的做法是命中唯一时直接执行，命中多个时进入交互选择。交互列表长这样：

$ anything health ? 你要运行哪个插件？ ops:health 检查所有线上服务健康状态 team:health 查看团队例行任务状态 > net:health 网络连通性检测

这里有一个必须注意的细节：交互式选择只能在 TTY 下启用。如果是在 CI 脚本里通过管道调用anything health，交互提示会让整个任务卡死。实现方式是检测process.stdout.isTTY，非 TTY 环境下直接报错并列出所有候选，让用户在脚本里写明确名称。

3.4 帮助体系：让工具自己会说话

anything list列出全部插件及其一句话描述；anything help <name>显示某个插件的完整参数说明；anything alias <name> <短名>给常用插件设置短别名。这三条命令构成一个自解释的发现体系。

我见过太多内部工具死在"没有文档"上。CLI-Anything 的做法是在框架层强制插件作者写description和参数说明，从机制上杜绝"裸奔脚本"。写帮助这件事，不应该靠自觉，应该靠协议。

4. 把日常操作变成插件的五个实战案例

4.1 脚手架：create:component

前端项目里最常见的重复劳动是新建组件。三四个文件、一段样板代码、还要手动改 import。我把它做成了插件：

// run.js const fs = require('fs'); const path = require('path'); const arg = (name) => { const idx = process.argv.indexOf(`--${name}`); return idx > -1 ? process.argv[idx + 1] : null; }; const cwd = process.cwd(); const name = arg('name'); const type = arg('type') || 'component'; if (!name) { console.error('用法: anything create:component --name <组件名>'); process.exit(1); } const template = `// ${type}: ${name}\nexport function ${name}() {\n return null;\n}\n`; const dir = path.join(cwd, 'src', type + 's', name); fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, 'index.js'), template); fs.writeFileSync(path.join(dir, 'style.css'), `/* ${name} styles */\n`); console.log(`已创建 ${type}：${name}`);

价值点不在模板多精美，而在于新成员进项目不需要读文档。anything list看到create:component，help里写着参数说明，5 分钟就能上手。脚手架类工具是插件的天然场景，因为它的输入输出非常规整。

4.2 数据库查询：db:q

我又做了一系列一次性数据查询脚本，全都没有归档。后来干脆做成db:q插件，参数从plugin.json声明，入口用 mysql2 执行 SQL，表格输出：

const mysql = require('mysql2/promise'); const getArg = (name) => { const idx = process.argv.indexOf(`--${name}`); return idx > -1 ? process.argv[idx + 1] : undefined; }; (async () => { const conn = await mysql.createConnection({ host: getArg('host') || '127.0.0.1', user: getArg('user') || 'root', password: getArg('password') || '', database: getArg('db') || 'app', }); const [rows] = await conn.query(getArg('sql')); console.table(rows); await conn.end(); })();

这个插件的实际价值不只是执行 SQL，而是让连接参数变成记忆友好的命令。原来每次都要回忆"这台机器的数据库密码到底是啥来着"，现在anything help db:q全部写清楚。配合 JSON 输出模式，还能把查询结果直接抛给下一个分析工具。

4.3 质量门禁：qa:all

我前面说过，插件可以是编排器。qa:all是最典型的例子，它自己一行业务代码都没有，只是把三个命令按顺序执行：

const { spawn } = require('cross-spawn'); const steps = [ ['npx', ['eslint', 'src']], ['npx', ['jest', '--ci']], ['npm', ['run', 'build']], ]; (async () => { for (const [cmd, args] of steps) { const result = spawn(cmd, args, { stdio: 'inherit' }); const code = await new Promise(resolve => result.on('close', resolve)); if (code !== 0) { console.error(`步骤失败: ${cmd} ${args.join(' ')}`); process.exit(code); } } console.log('全部检查通过'); })();

为什么这个值得做？因为人类不擅长执行多步且中途可能失败的任务。手敲eslint通过之后，大概率忘了跑测试。编排型插件把"成功的路径"固化下来，每次都是同一套可靠流程。

4.4 健康检查：ops:health

这个插件针对"有没有想过从终端快速看一遍所有服务状态"的需求。它并行请求配置里的一组接口，输出每个服务的可达性和响应时间：

const endpoints = [ { name: '订单中心', url: 'https://api.example.com/orders/health' }, { name: '用户中心', url: 'https://api.example.com/users/health' }, { name: '网关', url: 'https://api.example.com/gateway/health' }, ]; (async () => { const results = await Promise.allSettled( endpoints.map(async ({ name, url }) => { const start = Date.now(); const res = await fetch(url, { signal: AbortSignal.timeout(3000) }); return { name, status: res.status, ms: Date.now() - start }; }) ); for (const r of results) { if (r.status === 'fulfilled') { console.log(`${r.value.name}: ${r.value.status} (${r.value.ms}ms)`); } else { console.log(`${r.reason?.message}: 超时或不可达`); process.exitCode = 1; } } })();

关键细节是process.exitCode = 1。这样anything ops:health在现代 CI 流水线里可以直接作为检查节点使用，失败即中断发布。

4.5 AI 提交信息：ai:commit

最后一个案例想说明：外部 API 也可以是一个插件。ai:commit读取 git diff，调用大模型接口生成提交信息：

const { execSync } = require('child_process'); const diff = execSync('git diff --staged').toString().slice(0, 8000); const apiKey = process.env.ANYTHING_AI_KEY; if (!apiKey) { console.error('未找到 ANYTHING_AI_KEY 环境变量'); process.exit(1); } const response = await fetch('https://api.example-llm.com/v1/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'turbo-text', prompt: `根据以下 diff 生成一句提交信息：\n${diff}`, }), }); const data = await response.json(); console.log(data.choices[0].text.trim());

这里有两个实践心得：一是 API Key 从环境变量读取，绝对不写进插件代码或plugin.json，避免一不留神提交到公共仓库；二是 diff 长度截断到 8000 字符，防止超长 diff 变成昂贵的 token 消耗。把 AI 能力做成插件后，团队里的任何人都能用一条命令获得结构清晰的提交信息，不用自己配环境、调参数。

5. 执行器背后的六个坑：我为此重写了三遍 spawn 逻辑

5.1 参数拼接导致的引号地狱

我最初的实现偷懒，用字符串拼接来组装子进程命令：

// 错误示范 const command = `python run.py --text="${text}"`; execSync(command);

这个写法在参数里出现空格、引号、特殊字符时立刻崩溃。比如--text "Hello World"会被拆成两个参数。后来我全部改成数组传参，把命令行交给 spawn，由系统负责正确的参数分隔：

// 正确做法 const { spawn } = require('cross-spawn'); spawn('python', ['run.py', '--text', text], { stdio: 'inherit' });

教训很简单：永远不要自己拼命令字符串。只要参数来自用户输入，拼接就是注入漏洞的温床。数组传参既安全又能正确处理空格。

5.2 直接 spawn('bash') 让 Windows 用户原地爆炸

第一版很多插件作者默认写spawn('bash', [...])。在 macOS 和 Linux 上好好的，一到 Windows 就ENOENT。因为 Windows 根本没有/bin/bash。解决方案是用cross-spawn统一处理跨平台差异，并且对 JS 插件默认用process.execPath来启动 Node，而不是写死node：

const { spawn } = require('cross-spawn'); function runPlugin(plugin, args) { const runnerMap = { node: process.execPath, python: process.platform === 'win32' ? 'python' : 'python3', bash: process.platform === 'win32' ? 'bash' : 'bash', }; const executable = runnerMap[plugin.runner]; return spawn(executable, [plugin.entry, ...formatArgs(args)], { stdio: 'inherit', }); }

注意 Python 在 Windows 上是python，在 Unix 系经常是python3，这个差异如果不处理，同样的插件跨平台就神秘失效。这类细节属于"不做不知道，做了才崩溃"的类型。

5.3 非 TTY 环境下交互输出把 CI 打崩

有段时间我们在 CI 里调用某个原本交互式的插件，结果流水线直接挂起，等到超时。原因前面提过：插件 detect 到输入来自管道，依然弹出了选择列表，一旦没有人类去选择，就永远卡住。

为此我建立了一条约定：框架通过环境变量ANYTHING_NON_INTERACTIVE=1通知插件当前处于非交互模式。插件拿到这个变量就去掉交互提示，直接输出结果。同时框架侧在!process.stdout.isTTY时自动设置该变量。Convention over configuration，所有插件默认遵守。

5.4 npm link 导致命令更新不生效

CLI-Anything 本身用 npm 全局安装，开发期我用npm link做本地调试。踩过的坑是：发布新版本后执行npm i -g cli-anything，命令倒是更新了，但插件相关文件还是旧的。原因是 npm link 创建的符号链接指向开发目录，全局安装覆盖不到。

排查方式很简单：which anything看命令实际路径，如果在开发目录下，就是 link 残留。重置方式：

npm rm -g cli-anything npm i -g cli-anything

给所有 CLI 工具开发者的提醒：npm link很方便，但发布前一定要在干净环境里验证全新安装，不要默认 link 环境等于发布环境。

5.5 长时间任务没有输出，用户以为进程死了

最典型的例子是qa:all，跑构建可能一分钟没任何输出。用户体验极差——不是卡死，是没反馈。我加了一个朴素的节流输出机制：

let lastOutput = Date.now(); const interval = setInterval(() => { if (Date.now() - lastOutput > 3000) { process.stderr.write(`仍在运行，已等待 ${(Date.now() - lastOutput) / 1000} 秒...\n`); } }, 3000); child.on('stdout', () => { lastOutput = Date.now(); }); child.on('close', () => clearInterval(interval));

注意节流日志写入的是stderr而不是 stdout（原因见下一个坑）。这个机制虽然简单，但救了很多次"看起来没反应"的误判。

5.6 stdout 被日志污染，JSON 管道彻底报废

最后这个坑让我重写了半套日志系统。现象是：用户写anything db:q --sql "..." | anything ai:explain，下游插件收到的不是 JSON 而是夹杂着正在连接数据库...这类日志的脏数据。

解决方案是建立严格的输出通道约定：

• 插件的正式结果（JSON、文本、表格）走stdout；
• 日志、进度条、诊断信息走stderr；
• 框架标记outputType: json时，stdout 只允许出现一条完整的 JSON 对象。

实现层面，框架通过环境变量把输出模式传给插件，插件侧约定：process.stderr.write用于一切附带信息，console.log只用于业务结果。这一条约定让"任意插件任意组合"成为可能，也让 CLI-Anything 保住了 Unix 哲学最后一点尊严。

6. 从本机到团队：自然语言入口、远程执行与后续想象

6.1 让自然语言成为入口的第一步

模糊搜索已经允许用描述性关键词找插件，更进一步是让用户直接说一句话，由框架匹配意图并执行。我在实验分支里写了一个很薄的实现：把用户输入交给本地模型，让它输出一个 JSON 意图（哪些插件最匹配、参数怎么填）。

$ anything ask "帮我看看线上服务都正常吗" # 内部意图解析: { plugin: "ops:health", args: {} } # 随后自动执行 anything ops:health

目前这个实验还很糙，但方向是对的。当插件清单本身是结构化元数据时，AI 读取这份清单的成本极低。未来 CLI 的价值可能不在于"记住命令"，而在于"理解意图"。

6.2 插件的分发与安装

CLI-Anything 的插件分发简单粗暴：一个 Git 仓库就是一个插件源。anything install <git-url>会 clone 到用户级插件目录、校验plugin.json、然后注册。团队内部工具的分发成本从"口头传文件 + 手动配置环境"降低到"一条命令装好"。

一个负责任的安全提醒：从远程安装插件等于执行远程代码。我在实现里默认拦截了不带--trust参数的安装，并要求仓库域名出现在可信列表中。任何 CLI 生态的插件分发都必须面对供应链风险，CLI-Anything 目前的选择是透明提示 + 用户显式确认，而不是假装看不见风险。

6.3 远程执行：一条命令管所有机器

借助 SSH，一个插件可以指定在远程机器上运行：anything ops:health --host prod-server-1。实现上，框架检测到--host参数后，把插件的运行过程包装成远程命令：

ssh user@host "cd ~/.anything/plugins/ops && python run.py --host prod-server-1"

我没有做更花哨的功能，一个能用的远程执行 + 同样的 JSON 输出约定已经覆盖了绝大多数运维场景。这个能力配合定时任务，就能实现"每天早上 9 点自动检查所有服务器的磁盘占用，异常时推送到群聊"这类实用自动化。

6.4 我自己现在的使用习惯

最后分享几个真实的使用习惯。首先，我给anything设了一个超短别名a，敲a db:q --sql "select * from users limit 5"比敲完整命令省太多事。其次，我把整个~/.anything目录纳入 dotfiles 管理，新机器一条安装脚本就能重建全部环境。第三，我给自己定了一个规矩：任何脚本只要用过两次以上，就立刻转成插件归档，绝不让它沦为又一个 /tmp 孤儿。

这三个习惯不复杂，但它们让 CLI-Anything 真正变成了我的工作台。工具的价值不在于堆积，而在于当你需要某个能力时，入口足够可靠、足够快。CLI-Anything 往这个方向走了一大步，而它最让我满意的设计，始终是那条最简单的协议：任何语言的任何脚本，放进插件目录，就拥有了统一的入口、帮助、搜索和分发。