先说个场景：你电脑里是不是也躺着一堆脚本，build.sh、deploy.py、cleanup.js，名字各异，位置分散，时间一长自己都忘了哪个是干嘛的？我前几年就处在这种状态里，每次要发个版本，得先翻终端历史回忆命令，再跑到对应目录执行脚本，遇到参数忘了还得打开文件看两眼。后来我干脆做了个项目，把所有零散操作统一收进一个命令行工具里，取名CLI-Anything。这个项目本质上是一个“统一入口 + 插件扩展”的CLI工具箱，把打开仓库、快速建分支、生成提交说明、清理Docker、跑测试并汇总结果这类高频操作，都做成一条条可组合的命令。它不重造命令轮子，而是把我已有的、以及以后会新增的工具统一管理起来，解决的是“脚本散落、上下文切换、重复劳动”这三个真问题。
如果你也被一堆临时脚本搞得头大，或者想让团队里新来的同事少背几页命令文档，又或者单纯想研究CLI工具怎么做，这个项目的拆解思路都值得参考。下面我从设计、选型、实现到踩坑，完整说一遍。
1. 先想清楚：这个项目的“Anything”到底指什么
1.1 万物皆可CLI的底层逻辑
很多人第一次听到“CLI-Anything”这个名字，下意识以为是要用命令行替代图形界面做所有事。其实我的本意没这么激进，核心逻辑只有一个：凡是能被“输入一行文本并回车”完成的操作，都比“打开窗口→找菜单→点按钮”更容易被自动化、被记录、被共享。
这里有个很实在的类比。遥控器上几十个按钮，你常用的永远是那几个，但每次换个设备还得重新学习布局；命令行更像是直接念菜名，你只要知道菜名和该放什么料，就能立刻得到结果，而且这份“菜单”还能保存下来发给别人。CLI-Anything做的事情就是把这些“菜名”统一收进一本你自己的菜谱里。
之所以要做成“统一入口”，是因为开发工作流里有大量上下文切换损耗。我前一秒在编辑器里改代码，后一秒要切到终端查日志，再切回来看测试结果，每次切换都要重拾上下文。如果所有操作都通过同一个CLI入口触达，我只需要记住一个工具名，后接不同子命令，心智负担会小很多。
还有一点很多人会忽略：CLI操作天然是“可追踪”的。你通过GUI点了什么，过两周可能完全想不起来；但你在终端敲过的每一条命令，都在历史记录里留着。这对复盘工作效率、排查环境问题帮助巨大。CLI-Anything做命令的时候就刻意保留了原始输入的可读性，而不是封装成看不懂的哈希调用。
1.2 范围控制：什么都做 = 什么都不做
设计这个项目时我最大的教训就是：不要一开始就试图把“Anything”变成“Everything”。什么都做，最后往往什么都做不精。
我最初脑暴过一堆功能：管理邮件、查天气、记账、发消息……后来全部砍掉了，只保留与“开发工作流强相关”的能力。CLI-Anything的定位最终收敛为一句话：开发者个人工作流的总闸，而不是又一个重型任务系统。
收敛之后，我明确了几个典型场景：
- 打开常用项目目录或远程仓库地址，不用每次拼完整路径。
- 从当前分支快速拉一个新的开发分支，命名风格统一。
- 执行测试并汇总结果，失败时给出关键错误片段。
- 清理Docker的悬空镜像和停止的容器，带确认提示。
- 随手记录一条TODO，存到统一的配置目录里，下次打开就是这个月的清单。
- 在任何目录下查看当前项目已经配置好的常用命令，不用翻README。
这样做的好处是，每个命令都有明确的边界。使用者能预判“这条命令会做什么”，也敢放心加自己的插件。项目本身只提供一个轻量的壳，真正的业务逻辑全部由命令或插件承载。
所以，CLI-Anything适合两类人：第一类是个人开发者，想把散乱的shell脚本、常用操作整理成一套干净的命令；第二类是小团队里的工具维护者，想给成员提供一个统一的入口，减少沟通成本。如果你是大厂基建团队，需要的是完整的内部平台，而不是这种个人工具，那这个项目的定位就不太合适了。
2. 方案选型与整体设计
2.1 技术栈怎么定：为什么选 Node.js
CLI工具的技术栈选择，基本绕不开 Node.js、Go、Python、Rust这几类。我给CLI-Anything选型时有几个硬性条件：跨平台、生态里现成的命令解析库成熟、用户装依赖不痛苦、二次开发门槛低。
最终选了 Node.js + TypeScript。核心原因有三点。
第一，Node.js生态里处理命令行参数、子进程、文件操作的库非常成熟，commander、yargs、execa、chalk这些组合起来，能省掉大量底层兼容性工作。我用commander做参数解析，它天然支持子命令、选项、帮助文档自动生成，这对一个“命令聚合器”来说太关键了。
第二，Node.js的模块机制天然适合插件化设计。CommonJS动态require一个目录下的多个模块非常方便，插件作者只需要按约定导出几个字段，主程序就能识别并注册。这对快速扩展命令非常友好。
第三，团队或社区贡献插件的门槛低。只要会写Node，谁都能往CLI-Anything里加一条命令，不需要额外学习语言。相比之下，Go写CLI虽然性能好、分发简单，但插件动态加载比较麻烦，一般需要重新编译；Python打包分发又容易遇到环境问题。
我把备选方案简单列了个表：
| 方案 | 优势 | 劣势 | 适合场景 |
|---|---|---|---|
| Node.js | 生态丰富，插件动态加载容易，开发效率高 | 单文件分发不如Go/Rust方便 | 以插件生态为核心的CLI工具 |
| Go | 编译单二进制，分发极方便，启动快 | 动态插件难做，需要重新编译 | 系统级工具、运维命令 |
| Python | 上手快，脚本风格自然，数据科学生态好 | 依赖管理头疼，解释器版本兼容麻烦 | 内部工具、数据分析相关CLI |
| Rust | 性能强，无运行时依赖 | 开发速度慢，学习曲线陡 | 对性能和资源占用有极致要求的CLI |
实际用下来，Node.js版本的选择也很重要。建议在项目里声明Node >= 18，因为从18开始，核心API对现代JavaScript特性的支持比较稳定，fetch也可以直接用，做插件请求外部接口时能少装一个依赖。
2.2 核心模块划分
CLI-Anything的代码结构，我按职责分成了六块。这个划分是改了三轮之后稳定下来的，给项目加功能时基本不用改骨架。
- cli入口：负责初始化
commander程序，注册全局选项，挂载各个命令模块。 - command注册模块：内置命令都放在
src/commands/下，每个命令一个文件，导出name、description、action等信息，然后由注册器统一挂到program上。 - plugin loader：负责扫描插件目录，读取插件声明，把插件里定义的命令动态注册进去。这是”Anything“的扩展点。
- config manager：负责全局配置、项目配置的读取和合并，提供
get/set/reset接口。配置内容包含用户偏好、路径映射、启用哪些插件等。 - logger模块：封装输出逻辑，统一处理普通信息、成功提示、警告、错误，以及是否开启颜色输出。
- util模块：包括子进程执行封装、路径规范化、JSON读写、Git命令封装等。所有命令共享这些能力，避免每个插件都自己实现一遍。
模块之间是单向依赖：cli入口依赖注册模块，注册模块依赖plugin loader和config manager，util被所有模块依赖。我刻意避免搞成过度设计，没有引入依赖注入容器，因为这个规模的项目用容器反而增加理解成本。
2.3 命令表的取舍：内置命令 vs 插件命令
CLI-Anything的命令分两层：内置命令是开箱即用的，插件命令由用户或第三方提供。我内置的命令非常克制，只保留了五类：
| 命令 | 作用 | 是否默认内置 |
|---|---|---|
cli-anything help | 查看所有命令、插件、配置项的帮助 | 是 |
cli-anything version | 输出版本号，方便排查环境 | 是 |
cli-anything config get/set | 查看或修改配置文件 | 是 |
cli-anything plugin list/add/remove | 管理插件 | 是 |
cli-anything todo add/list/done | 简单的TODO记录，存到用户目录 | 是 |
剩下的全部通过插件提供。第一版里我很快写完了内置命令，然后开始做常用插件：git-branch、docker-clean、run-tests、open-project等。插件的价值在于，我可以随时加一个实验性质的功能，两个星期后不好用就删掉，完全不污染主程序。
这个取舍逻辑是：内置命令必须满足“稳定的、跨场景的、几乎所有用户都需要”的特征；插件命令则允许“实验性的、个性化的、团队定制的”内容。把这两者混在一起，命令表很快会失控，帮助文档也会变成一堵墙。
3. 从零搭一个CLI-Anything
3.1 最小可用的命令骨架
动手写代码的第一步是搭一个最小的命令骨架：安装依赖、建入口、注册help命令。我用的依赖很少，核心就commander和chalk，子进程封装先用Node内置的child_process跑通，后续再决定要不要换execa。
package.json里最关键的是bin字段：
{ "name": "cli-anything", "version": "0.1.0", "bin": { "cli-anything": "./bin/cli-anything.js" }, "files": [ "bin", "dist" ], "scripts": { "build": "tsc", "dev": "tsx src/index.ts" }, "dependencies": { "chalk": "^5.3.0", "commander": "^11.1.0" }, "devDependencies": { "@types/node": "^20.0.0", "tsx": "^4.0.0", "typescript": "^5.0.0" }, "engines": { "node": ">=18" } }入口文件长这样：
#!/usr/bin/env node import { Command } from 'commander'; import { loadBuiltinCommands } from './commands'; import { loadPlugins } from './plugin/loader'; import { getProgramInfo } from './config'; const program = new Command(); program .name('cli-anything') .description('Unified CLI toolbox for everyday developer workflows') .version(getProgramInfo().version, '-v, --version', 'output the current version'); // 注册内置命令 loadBuiltinCommands(program); // 加载插件命令 loadPlugins(program); program.parse(process.argv);这里有几个细节容易踩坑，我单独说一下。
commander的.version()如果不显式指定-v，默认只支持-V，很多人习惯用-v，所以我会显式传参。帮助命令--help是自动生成的，不需要自己写，但为了让命令说明更清晰，每个子命令我都会认真写description，这会在cli-anything help里整体展示，比临时翻代码友好得多。
还有process.argv的解析时机问题。program.parse(process.argv)必须在所有命令注册完之后调用，否则commander会认为用户输入的命令没注册，直接报“unknown command”。这个顺序我一开始就踩过，后面模块多了反而容易复发。
此时，cli-anything已经能执行--help和--version了。但整个CLI还没有真正“业务能力”，下一步是建立插件机制，让所有扩展命令能动态接入。
3.2 插件机制怎么做：别用继承，用协议
插件机制是我在整个项目里最看重的一部分。设计目标是：任何人拿到项目后，不需要改动主程序代码，就能新增一条命令。
我采用的方案很简单：扫描插件目录，读取每个子目录下的manifest.json，按约定的协议把命令注册到program上。这里说的“协议”，其实就是一组字段约定，包括命令名、描述、参数、执行函数入口。
插件目录结构约定为：
~/.cli-anything/plugins/my-plugin/ ├── manifest.json └── index.jsmanifest.json内容示例：
{ "name": "my-plugin", "version": "1.0.0", "description": "A demo plugin for CLI-Anything", "entry": "./index.js", "commands": [ { "name": "hello", "description": "Say hello to the given name", "options": [ { "flag": "-n, --name <name>", "description": "your name" } ] } ] }主程序里的加载器伪代码如下：
import fs from 'node:fs'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { Command } from 'commander'; export function loadPlugins(program: Command) { const pluginsRoot = getPluginsRoot(); if (!fs.existsSync(pluginsRoot)) return; const entries = fs.readdirSync(pluginsRoot, { withFileTypes: true }); for (const entry of entries) { if (!entry.isDirectory()) continue; const manifestPath = path.join(pluginsRoot, entry.name, 'manifest.json'); if (!fs.existsSync(manifestPath)) continue; const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')); const pluginModule = require(manifest.entry); const cmdRegistrar = pluginModule.register; if (typeof cmdRegistrar !== 'function') { console.warn(`Plugin ${manifest.name} is missing register() function`); continue; } for (const cmdDef of manifest.commands) { const sub = program.command(cmdDef.name); sub.description(cmdDef.description); for (const opt of cmdDef.options ?? []) { sub.option(opt.flag, opt.description); } sub.action((...args) => cmdRegistrar(cmdDef.name, args, { manifest })); } } }我把插件执行函数统一约定为register(commandName, args, context)，而不是像内置命令那样各写各的。原因是：动态加载的模块，入口越统一越好，主程序不需要猜插件内部暴露了什么接口。插件作者只需要遵循一个函数签名，就能接入所有能力：拿命令参数、读取上下文的配置、调用主程序提供的工具函数。
第一版其实试过更“优雅”的方案：让每个插件引入主程序导出的PluginBase类并继承。架构上是标准的策略模式，但实际操作起来相当别扭。插件作者必须先搞懂主程序里的基类，还得处理版本不一致时的兼容问题，明明是几行脚本的事，被框架挡住。后来我彻底抛弃继承，改用“协议+入口函数”，插件的接入成本降到最低，实测下来，团队里让一个刚学Node两周的同事加插件也很顺利。
一个插件的index.js大概长这样：
const chalk = require('chalk'); function register(commandName, args, context) { if (commandName === 'hello') { const opts = args.at(-1) ?? {}; const who = opts.name || 'world'; console.log(`${chalk.green('Hello')}, ${who}!`); context.getConfig(); // 通过context访问配置 } } module.exports = { register };这里有个小约定：commander的action回调会把用户选项作为最后一个参数传进来，所以args.at(-1)通常是当前命令解析后的选项对象，前面的参数则是位置参数。插件开发者不需要关心这个细节，因为register接收的参数已经封装好了，只要文档里写明“最后一个参数是选项对象”就行。
3.3 配置与状态管理：两级优先级
CLI工具最怕“配置混乱”。我的设计是两级配置：全局配置放在~/.cli-anything/config.json，项目级配置放在项目目录下的.cli-anything文件夹里。
配置优先级是：项目级 > 全局 > 默认。这样同一个命令，在个人全局环境里有一套默认行为，进入某公司项目时如果项目里定义了特定配置，则自动覆盖。比如open-project命令，全局配置里存放的是个人常用仓库路径；团队项目里设置了projects.teamRepo = "git@github.com:team/repo.git"，那在项目目录下执行时，就会优先打开团队仓库。
config manager的核心实现不复杂，但要注意不要重复读取文件。我的做法是启动时缓存一次，所有命令共享同一个配置对象，运行时修改只在退出前写回文件。
import fs from 'node:fs'; import path from 'node:path'; import os from 'node:os'; let cachedConfig: any = null; const GLOBAL_CONFIG_PATH = path.join(os.homedir(), '.cli-anything', 'config.json'); export function getConfig() { if (cachedConfig) return cachedConfig; const globals = readJsonSafe(GLOBAL_CONFIG_PATH); const projectConfig = readProjectConfig(); cachedConfig = deepMerge(globals, projectConfig); return cachedConfig; } export function setConfig(key: string, value: any) { const config = getConfig(); setNested(config, key, value); writeJson(GLOBAL_CONFIG_PATH, config); } export function readProjectConfig() { const localPath = path.join(process.cwd(), '.cli-anything', 'config.json'); return readJsonSafe(localPath, {}); } export function resetConfigCache() { cachedConfig = null; }配置内容不只是用户偏好，还包括一些状态数据。例如todo add命令会把TODO列表写入~/.cli-anything/todos.json，这部分不走config，避免配置文件越来越大。区分“偏好型配置”和“数据型状态”很重要，否则一个JSON文件会越写越乱，最终谁也分不清哪些是用户可改的配置、哪些是程序自动维护的数据。
3.4 打包与分发：npm link之后还有哪些方式
CLI-Anything起步阶段，我直接用npm link软链到全局，方便本地开发调试。这种方式的优点是不需要反复安装，改一行代码立刻生效；缺点是团队成员没法用，换机器也要重新link。
要让别人能用，最标准的做法是发布到npm，用户执行npm i -g cli-anything。如果只是在公司内部分发，可以搭个私有npm源，或者干脆把项目目录打包发给同事，再让他们手动npm link。
这里我想多说一个点：如果你嫌npm安装太慢，或者不想让用户费劲装Node环境，可以用esbuild把项目打包成单文件，再用pkg或bun build --compile产出各平台的可执行二进制。但我实测下来，二进制化的坑不少：原生模块要单独处理、动态require会被打包器误判、插件机制在二进制环境下需要调整加载路径。对于这个项目，我最终没有默认走二进制路线，而是保留npm分发，把“二进制构建”作为可选的团队内部优化项。
分发还有一个经常被忽略的问题：PATH路径。npm全局安装后，可执行文件通常落在/usr/local/bin或%APPDATA%\npm，如果用户的PATH里没有这些目录，命令就无法直接执行。排查这类问题，先执行npm config get prefix确认全局安装目录，再检查PATH里是否包含该目录。Windows上还容易遇到执行策略限制，需要调整PowerShell的ExecutionPolicy。
4. 实操中的问题与排查实录
4.1 首次运行最常遇到的三类问题
我把项目分享给几个朋友试用后，收集到的问题总共有三类，基本可以覆盖大多数CLI工具的首发烂摊子。
第一类是环境差异。最典型的是Windows控制台默认编码是GBK/CP936，当CLI输出中文或emoji符号时，会遇到乱码或终端宽度计算错误。我最初的解决方案是检测到Windows环境时输出ASCII风格的成功/失败标识，避免使用特殊符号；后来要求用户执行chcp 65001切UTF-8编码，这样日志能正常显示，但这个改动只影响当前终端会话，自动化脚本里还要额外处理。
第二类是commander的参数解析行为不符合预期。比如用户输入cli-anything todo add -m "buy milk"时，-m是--message的别名，有时会被解析成布尔标志，字符串没传进去。排查方法很简单：在action回调里打印args数组，看最后一个选项对象里到底有没有message字段。这类问题多半是定义option时漏了<value>占位符，sub.option('-m, --message <text>', '...')一定不能省<text>。
第三类是插件加载失败但毫无提示。我最初只在插件目录不存在时静默返回，后来发现如果manifest.json里写的entry路径不存在，或者register不是函数，日志只有一行[warn]，很容易被淹没。后来我把所有插件加载异常统一收集起来，在cli-anything plugin list里直接展示加载失败的原因，排查效率高了很多。
4.2 一个完整排查案例：命令输出在CI里乱码
有一次用户反馈，在Jenkins里跑cli-anything run-tests，日志里的中文乱码，且测试通过但CI步骤却判定失败。
我排查的时候先看退出码。CLI在run-tests命令执行完测试后，process.exitCode被设置成了1，即使测试全部通过。原因在于我用execa或child_process执行外部测试命令时，没有正确传递子进程的退出码。spawn的子进程退出后，父进程默认继续执行，如果我不显式process.exit(code)，commander的action结束后进程正常退出码是0，但我的代码里在错误处理分支错误地设置了exitCode。
修复方式是：封装一个runProcess工具函数，统一等待子进程退出，并把退出码原样返回；命令的action同步返回这个码。这样就不会出现“CI里命令退出码漂移”的怪问题。
中文乱码的根因则是两处：一处是Windows CI执行机上PowerShell的默认输出编码不对，我让用户在Jenkins脚本里先执行[Console]::OutputEncoding = [System.Text.Encoding]::UTF8；另一处是我自己的CLI往stdout输出时没做编码强制。Node.js向管道输出时默认UTF-8，但如果外部程序输出GBK字节流，Node不会自动转码，最终管道里就是混合编码。解决办法是在runProcess里显式指定编码为utf8，对非UTF8输出则用iconv-lite转码，避免链路污染。
4.3 常见问题速查表
把这个项目从设计到落地期间，我遇到的问题浓缩成一个速查表，方便后来人快速定位。
| 问题 | 原因 | 解法 |
|---|---|---|
| 命令安装后找不到 | npm全局bin目录不在PATH里 | npm config get prefix，把对应目录加入PATH |
| Windows下中文乱码 | 终端编码非UTF-8 | 切换代码页chcp 65001，或在CI里设置控制台输出编码 |
| 子进程退出码丢失 | 没有把子进程退出码映射到CLI | 封装runProcess，统一读取并返回exitCode |
| 插件不生效 | 插件目录路径被解析错 | 检查全局/项目插件根目录，加载异常汇总到plugin list |
| option的value变成true | 定义选项时忘了<value>占位符 | 补全--message <text> |
| 执行外部命令时引号被吞 | shell拼接命令时转义不当 | 使用spawn传数组参数，不用shell: true拼字符串 |
| 配置文件改动不生效 | 配置缓存未失效 | 修改配置后调用resetConfigCache() |
| 大型目录下扫描慢 | 插件扫描遍历了node_modules | 跳过隐藏目录和node_modules等约定目录 |
这里单独说第6条，因为太容易踩了。如果你用spawn直接传字符串命令，遇到路径里有空格、引号、通配符时会非常痛苦。我的习惯是永远传参数数组，例如spawn('git', ['-C', projectPath, 'status', '--short'])，绝不把用户输入拼进shell命令再交给shell: true执行，否则分分钟变成命令注入漏洞。
4.4 给命令保留“无交互逃生通道”
最后分享一个我特别想强调的实操经验：任何需要交互确认的命令，都要留一个--yes或--dry-run选项。
比如docker-clean插件，默认执行时先列出将要删除的容器和镜像，并询问Are you sure?。但我发现脚本、CI或 alias 场景下完全没法交互，所以加了--yes跳过询问。类似地，run-tests的命令加了--dry-run，只打印将要执行的命令，不做任何实际改动。这个设计看似多几行代码，但让命令从“只能人肉执行”升级为“可编程调用”，是CLI工具实用性的关键。
还有一个小技巧：每个重要命令的action开始时打印当前配置的关键部分，比如[config] using todo file: ~/.cli-anything/todos.json。这在用户觉得“命令怎么没按预期执行”时，能立刻判断是否加载了错误的配置，比写多少文档都管用。
我在实际操作中最大的体会是，CLI-Anything真正省下的不只是几次敲键盘的时间。它让我的工作流变得可描述、可复用、可交接。我把常用源码仓库映射、发布流程、环境清理这些长期靠肌肉记忆的事情，变成了一条条一看就懂的命令，新同事上手时不再需要我坐在旁边口头教一小时。如果你也想做类似的工具，我的建议很直接：初始版本只内置三四个命令就够了，但插件化设计从第一天就要做进去，因为后期重构的成本大概率比你想象的高；每一个命令都要能做到“非交互执行”，这样你才敢放心把它写进自动化脚本里。
