从一周之内来回切换十多个工具、把团队里各种零散脚本攒成一个大杂烩仓库，到最后自己动手做了一个统一入口的 CLI 工具箱，“CLI-Anything”这个项目就这么被逼出来了。它不是什么重框架，也不依赖什么神秘技术，核心思路就是在终端里搞定日常高频操作：查天气、记待办、取剪贴板图片、生成二维码、批量重命名、快速打开项目目录……所有东西收敛成一个命令入口，你在任何一台机器上装上它，就能按同一套心智模型做事情。
这篇文章就把整个项目的来龙去脉写透：为什么要做它、技术栈怎么选、核心模块怎么落地、插件机制怎么设计、以及我在实际开发中踩过的坑和排查链路。不管你是想把零散脚本收拾利索的开发者，还是想给自己团队搭一套内部效率工具的运维或技术负责人，这篇都值得看完再动手。
1. 从“工具碎片化”的崩溃现场，到CLI-Anything的目标边界
1.1 痛点复盘：真正难受的不是“没有工具”，而是“工具太多”
这个项目的起点有点狼狈。当时我手头同时维护几个服务端项目和一个前端项目，协作工具还不统一：A 组习惯用 Jira，B 组用飞书表格，发版要看 GitLab 流水线，线上日志在 Kibana 里查，配置文件散落在三个仓库里，每次排查问题都要开一堆标签页，并在终端、浏览器、IDE 之间来回切换。
更难受的是，我自己那台开发机上积累了一堆“一次性脚本”：curl某个接口拿状态码、grep一段时间内的日志、用 node 脚本把 CSV 转成 JSON、再写个 awk 统计某个字段。坦白讲，这些脚本每一段都能用，但彼此之间没有统一入口。今天要用的时候，我可能得花好几分钟回忆“上次那个统计脚本放在哪个目录下了”。时间一长，情绪成本比时间成本还高。
这种碎片化其实是很典型的工程问题：单个工具都有自己的场景，但工具之间的切换和记忆成本，已经超过了工具本身带来的效率。CLI 工具的天然优势就是“只留一个入口、一切皆命令”，它能把我们反复做的高频动作固定成肌肉记忆。
1.2 给“Anything”划边界：不是什么都做，而是高频、轻量、可脚本化
CLI-Anything 这个名字听起来很狂，好像什么都要管。但没有边界的功能集合，大概率会做成又一个什么都做不好的半成品。我需要先确定它的能力边界和取舍原则。
我给自己定的三条标准是这样的：
- 高频：每天或每周至少会用到一次的操作才值得收进来，一年用两次的靠后站。
- 轻量：数据交互尽量通过终端文本完成，不要让用户在一个微型 GUI 里去点按钮。
- 可脚本化：操作的结果要能被复制、被管道处理、被其他脚本消费，否则不如直接打开对应软件。
举个例子，“查看今天的天气”这种功能，放进 CLI 里价值非常高，因为它本来就是一条网络请求加 JSON 解析的事，而打开天气 App 还要经过解锁屏幕、点图标、看广告。但“写文档”就不适合做成 CLI，即使做成也只会是个劣质的 Markdown 编辑器。
1.3 最小原型：先跑通一个命令，再谈模块化
第一版原型其实弱得可怜，只有一个cli-anything hello命令，输出一句问候语，加一个读取配置文件的演示。整个代码没有超过 40 行：
npm init -y npm install commander#!/usr/bin/env node const { program } = require('commander'); program .name('cli-anything') .description('一个基于 Node.js 的万能 CLI 工具箱') .version('0.1.0'); program .command('hello') .description('输出欢迎信息') .action(() => { console.log('hello from cli-anything'); }); program.parse();当时我刻意没有急着写“看起来有用”的功能。先跑通命令注册、参数解析、帮助文档渲染这些 CLI 的地基，后面加功能模块的时候就只需要关心模块本身的业务逻辑了。这也是我想提醒每一个想自己写 CLI 工具的人：别一上来就堆功能，先把命令框架和配置骨架搭干净，后面每一个模块都会轻松很多。
2. 技术选型与架构设计：为什么是 Node.js，以及命令注册机制怎么写
2.1 选型对比：Node.js、Python 和 Go，我最终选了哪个
CLI 工具箱的骨架技术栈其实就那几条路：Node.js、Python、Go。这三类我都写过一点小工具，所以这轮对比不是凭想象，而是基于实际体感。
| 维度 | Node.js | Python | Go |
|---|---|---|---|
| 依赖安装与分发 | npm 生态成熟，npm link本地调试方便 | pip 环境容易乱，打包成单文件需要 PyInstaller | 交叉编译单二进制非常好，但编译期略长 |
| 第三方 CLI 框架 | commander、yargs 都很成熟 | click、typer 体验不错 | cobra 是经典选择 |
| JSON / 配置处理 | 原生 JSON 支持，读写都是顺手的事 | 需要 json 模块，写起来稍微绕 | 需要定义结构体，严谨但偏重 |
| 团队上手成本 | 前端团队普遍熟悉，几乎无学习成本 | 后端和运维熟悉，也可以 | 编译语言，门槛稍高 |
| 生态里有没有现成的库 | 图片处理、二维码生成、HTTP 请求等库都很齐全 | 同样丰富 | 相比前两者略少 |
最终选 Node.js 的核心原因其实是“心智负担最小”：配置就用 JSON，脚本跑起来不用考虑 Python 的虚拟环境，npx和npm link让本地安装调试非常顺滑，而且我所在团队本身就是前端技术栈，后续想让别人也贡献力量，几乎不用额外培训。如果你的团队是运维偏多，那 Python 版本会更顺；如果你追求极致的单文件分发，那 Go 肯定是最优解。没有绝对答案，只有适合你的答案。
2.2 项目目录结构：让新增一个命令只需要改一个文件
我见过很多 CLI 工具，所有代码堆在一个index.js里，跑起来没问题，但维护两三个月之后，改个参数都提心吊胆。CLI-Anything 从一开始就按“命令即模块”的方式组织：
cli-anything/ ├── bin/ │ └── index.js # 入口，只负责注册命令和加载模块 ├── src/ │ ├── commands/ # 每一个子命令一个文件 │ │ ├── weather.js │ │ ├── todo.js │ │ ├── image.js │ │ └── qr.js │ ├── core/ │ │ ├── config.js # 配置读写与校验 │ │ └── registry.js # 命令注册中心 │ └── utils/ │ ├── http.js # 带超时和重试的请求封装 │ └── file.js # 原子写入、路径处理等 ├── plugins/ # 第三方扩展插件目录 ├── package.json └── README.md入口文件bin/index.js的逻辑非常直白：扫描src/commands目录，拿到每个命令文件的描述信息，然后注册到 commander 里。我用了一个极简的registry.js来做这件事：
// src/core/registry.js const fs = require('fs'); const path = require('path'); function loadCommands() { const commandsDir = path.join(__dirname, '../commands'); const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.js')); const commands = {}; for (const file of files) { const name = path.basename(file, '.js'); commands[name] = require(path.join(commandsDir, file)); } return commands; } module.exports = { loadCommands };然后入口文件里这样用：
// bin/index.js const { program } = require('commander'); const { loadCommands } = require('../src/core/registry'); const commands = loadCommands(); for (const [name, cmd] of Object.entries(commands)) { const sub = program.command(name); cmd.register(sub); } program.parse();每个命令模块只需要暴露一个有register方法的对象，这样“新增一个命令”就简化为“在 commands 目录下新建一个文件，实现 register 方法”。不需要改任何公共代码，也不会因为某一个命令的报错影响其他命令的加载。
2.3 配置系统设计：默认值、用户配置和运行时参数，三层叠加
CLI 工具箱最容易忽视却最关键的部分就是配置系统。用户可能希望“天气命令默认查北京”，又可能希望在运行时临时查上海，还可能改过一个全局配置文件。这套逻辑用三层配置叠加来解决：
- 默认配置：内置在代码里，写清楚每个参数的兜底值。
- 用户配置：读取
~/.cli-anything/config.json，覆盖默认值。 - 运行时参数：通过
--city shanghai传入，优先级最高。
我当时用了一个很简单的mergeConfig函数，同时用 zod 做了参数校验。这里需要注意的是：用户配置文件如果写错了，不能直接让整个工具崩溃，而是应该给出清晰的错误提示，并回退到默认配置。CLI 工具的容错性直接影响用户对它的信任度。
3. 核心功能模块的落地实现：天气、待办、图片和二维码
3.1 weather 模块：网络请求加上兜底逻辑，而不是只调一个 API
天气模块是典型“看起来简单，做起来要想清楚”的功能。最直接的实现就是调一个天气 API，然后JSON.parse输出。但实际操作中，你会遇到两个问题：网络可能超时、输入的城市名可能不规范。所以我把这个模块拆成三层：
第一层，输入规范化。用户可能输入beijing、北京、北京市，甚至拼音。要做城市名映射，避免每次遗忘全称。第二层，请求封装。统一走自研的http.js，设置超时、自动重试一次。第三层，输出格式。终端输出要简洁，还要支持--json参数输出原始 JSON，方便其他脚本消费。
// src/commands/weather.js const { httpGet } = require('../utils/http'); async function fetchWeather(city) { const url = `https://api.example.com/weather?city=${encodeURIComponent(city)}`; const data = await httpGet(url, { timeout: 5000, retries: 1 }); return { city: data.city, temperature: data.temperature, condition: data.condition, }; } function register(program) { program .command('weather') .description('查询某个城市的当前天气') .option('-c, --city <city>', '城市名称，如北京', '上海') .option('-j, --json', '输出原始 JSON') .action(async (opts) => { try { const result = await fetchWeather(opts.city); if (opts.json) { console.log(JSON.stringify(result)); } else { console.log(`当前 ${result.city}：${result.temperature}℃，${result.condition}`); } } catch (err) { console.error(`查询天气失败：${err.message}`); process.exit(1); } }); } module.exports = { register };这里有一个我后来觉得特别重要的细节：公共 HTTP 工具里，一定要区分“业务错误”和“网络错误”。天气 API 返回 404、500，和网络超时是完全不同的问题。如果混在一起提示，用户根本不知道该去查城市名还是查网络。我在http.js里将错误对象都挂上了type字段，这样每个命令模块就能给出更精准的错误提示。
3.2 todo 模块：JSON 文件持久化，以及“原子写入”的教训
待办事项模块要解决的问题是：我需要一个比手机备忘录更快、比记事本文件更结构化的记录方式。CLI-Anything 用本地 JSON 文件存储待办，命令包括add、list、done、delete。
持久化文件放在了用户主目录下：
const path = require('path'); const os = require('os'); const dataFile = path.join(os.homedir(), '.cli-anything', 'todos.json');所有操作都是先读文件、改内存里的数组、再写回文件。但这里有一个必须在生产级工具里处理的细节：原子写入。如果程序执行到一半断电或被杀掉，直接把 JSON 原文件写破，那用户所有待办数据就全毁了。
我采用的方案是：先写临时文件，写入成功后rename覆盖原文件。因为rename在同一文件系统内是原子操作，不会出现半个文件的状态：
// src/utils/file.js const fs = require('fs'); const path = require('path'); function atomicWriteJson(filePath, data) { const tmp = `${filePath}.${process.pid}.tmp`; fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8'); fs.renameSync(tmp, filePath); } module.exports = { atomicWriteJson };有了这个函数，todo 模块写文件只需要一行atomicWriteJson(dataFile, todos)。团队里后来有人接手这个项目，提了一个 issue 说“为什么写个待办还要这么绕”，我把这行 rename 的原因讲清楚之后，他反而去给自己其他脚本补了同样逻辑。数据文件的安全，从来不是等坏了再修的事。
3.3 image 模块：把剪贴板里的图片直接存成文件
这个模块是我的高频需求：工作中经常要截个图发给同事、贴进文档，但在服务器环境或纯终端工作流里，打开图片编辑器再保存就很痛苦。于是我想做一条命令：cli-anything image save --name screenshot.png，把当前系统剪贴板里的图片保存到指定路径。
在 macOS 上可以用pngpaste这样的辅助工具，跨平台一点的做法是用社区维护的 clipboard 解析库。核心逻辑不复杂：
- 读取系统剪贴板，判断内容类型是否为图片。
- 如果第一步拿到的数据是 Buffer，直接写入目标路径。
- 提供
--clipboard参数，保存成功之后自动把文件路径复制回剪贴板，方便立刻粘贴给别人。
这里踩过一个真实的坑：某些 Linux 桌面环境下，剪贴板图片数据不是一次就能读完整的，需要循环读取多次并拼接。如果没做这一层“等待数据稳定”的处理，经常拿到半张图。后来我在代码里加了一个小循环：每 100 毫秒尝试读取一次，最多重试 10 次，只有连续两次内容相同时才认为数据稳定。这个方案很土，但实测稳定可靠。
3.4 qr 模块：把终端信息变成手机能扫的二维码
二维码模块的实用场景特别多：把服务器地址传给手机、把 WiFi 配置分享给同事、把一个长 JSON 配置转到手机扫码读取。终端里生成二维码，如果不想依赖 GUI 库，最直接的办法是输出到终端字符画，或者输出一个二维码图片文件。
CLI-Anything 的实现是这样的：
const QRCode = require('qrcode'); function register(program) { program .command('qr') .description('生成二维码，可选输出到终端或保存为图片') .argument('<text>', '编码的内容') .option('-o, --output <file>', '保存为图片文件') .action(async (text, opts) => { if (opts.output) { await QRCode.toFile(opts.output, text); console.log(`二维码已保存到 ${opts.output}`); } else { const terminal = await QRCode.toString(text, { type: 'terminal' }); console.log(terminal); } }); } module.exports = { register };这可能是整个项目里代码量最少、但用户反馈最好的模块之一。因为它的价值不在于技术复杂度，而在于“把信息从电脑传递到手机”这个动作被压缩到了一行命令里。以前我要么装第三方传文件工具、要么开聊天软件传给自己，现在只要复制文本然后跑一条命令，手机扫码即可。
4. 插件机制：从固定命令集合，进化成真正的“Anything”
4.1 契约定得越薄越好：每个插件就是一个可以注册命令的文件
CLI 工具发展到一定阶段，一定会有人问：我可不可以自己扩展命令？如果每一个自定义命令都要改主仓库然后重新发布，那这个工具就失去了“Anything”的意义。
所以我在设计插件机制时定了一个很薄的契约：一个插件本质上就是一个遵守规则的 Node.js 模块，它导出register(program)方法，package.json 里写上cli-anything-plugin关键字。主程序在启动时扫描两类位置：
- 内置的
src/commands目录。 - 用户配置文件里指定的
pluginsDir目录。
扫描到之后，通过require加载，然后调用它的register方法。没有复杂的依赖注入、没有插件生命周期，就这十几行代码。薄契约最大的好处是降低参与者门槛，任何人都可以在半小时内写一个自己的插件。
4.2 插件扫描与动态注册的实现细节
扫描逻辑和内置命令的加载几乎一样，唯一区别是路径不同。考虑到用户可能安装了大量插件，我还会在加载时做一层“防崩溃隔离”：用try...catch单独包裹每个插件的加载过程，任何一个插件报错，只在终端打一条警告，并不影响主程序启动和其他插件运行。
// src/core/plugin.js function loadPlugins(pluginsDir) { if (!fs.existsSync(pluginsDir)) return []; const results = []; const files = fs.readdirSync(pluginsDir).filter((f) => f.endsWith('.js')); for (const file of files) { try { const plugin = require(path.join(pluginsDir, file)); results.push(plugin); } catch (err) { console.warn(`插件加载失败：${file}，原因：${err.message}`); } } return results; }这里我特意没有用动态import()或更复杂的模块联邦机制，原因很简单：对于个人和团队内部工具，文件系统扫描加require已经足够可靠；引入花哨的插件加载框架只会增加心智负担和故障面。
4.3 被忽略的细节：插件里的依赖版本冲突
插件机制上线两周后，我收到了一个很典型的报错：某插件用了commander的最新版，而我主程序用的是旧版，Node.js 的模块解析机制导致插件拿到的是主程序的commander实例，于是报了版本不匹配。这个问题排查了很久，最后发现根因是我把commander同时放在了主程序的dependencies和插件自己的dependencies里。
解决方案其实不复杂：要么约定所有插件都使用主程序提供的program实例，不要自己 import 新的commander；要么在主程序里做一次版本对齐检查。我选了第一种，并在插件文档里加了一条醒目的约定：“你的插件只需要接收program参数，不要自己引入命令行框架。”这个约定让插件 API 更稳定，也避免了依赖冲突。
5. 踩坑实录：从执行权限到网络兜底，完整排查链路分享
5.1 在 Windows 上跑不起cli-anything：PowerShell 执行策略的锅
我把项目丢到 GitHub 之后，第一个外部的 issue 来自一个 Windows 用户：在 PowerShell 里输入cli-anything，提示“无法加载文件，因为在此系统上禁止运行脚本”。
这个问题的根因很清晰：PowerShell 默认的执行策略是Restricted，禁止运行任何.ps1脚本，而 npm 全局安装的命令本质上是通过一个 shell 脚本桥接启动的。排查链路就是三步：
- 先用
npm ls -g确认包确实装到了全局。 - 直接执行
node C:\AppData\Roaming\npm\node_modules\cli-anything\bin\index.js，如果能跑，说明代码没问题，问题出在 shim 层。 - 执行
Get-ExecutionPolicy，确认执行策略。
最终解决方法是建议用户运行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，并解释这条策略的含义：只禁止未签名的远程脚本，本地脚本不受影响。这是比较安全的放宽方式，不建议直接改成Unrestricted。这个问题的处理方式后来直接写进了 README 的 FAQ，因为这个情况实在太普遍了。
5.2 天气模块的“超时”排查：是网络还是 API 限制？
第一次集中使用天气模块的时候，我连续几次遇到“查询失败”。第一反应以为是网络问题，但同样的时间段内curl一样的 API 却可以正常返回。
于是我把排查拆成了三层：
- 抓原始错误信息：打印
err.message，发现是socket hang up。 - 对比手动请求和 CLI 请求的差异：包括请求头、代理设置、连接复用逻辑。
- 查 API 服务商的文档，发现是免费层限制了单个 IP 每分钟的请求次数，我早上的循环测试触发了限频。
这个问题最终是靠两层解决：请求头里设置了一个自定义的User-Agent（部分服务商对默认 UA 会做更严格的限频），同时在代码里增加了遇到 429 状态码时的退避等待逻辑。核心教训是：CLI 工具里调用第三方 API，必须把“限频”当成一类常规错误来处理，而不是笼统地报“网络错误”。后来我还给http.js加了一个全局的小型令牌桶，对用户高频重复调用做前置拦截，避免触发服务商限频。
5.3 待办文件被写坏的半夜现场：从半个 JSON 到原子写入
有一次我在测试 todo 的删除功能，连续快速跑了十几条命令，突然发现todos.json里出现了一个只有半个对象的内容。当时我没有立刻怀疑程序逻辑，而是先去看进程：是不是有多个命令同时启动，导致两个进程同时读写同一个文件？
排查后确认：确实存在并发写入。原因是我用了Promise.all并行执行几个待办命令的测试脚本，两个 Node 进程同时writeFileSync，最后一个写的内容把前一个覆盖就算了，问题是在极端情况下，写文件中途进程切换，文件被写成了半截状态。
修复方案就是我在 3.2 节里提到的原子写入，临时文件加 rename。但这里有一个容易被忽略的补充点：临时文件的命名一定要唯一。我当时用的是todos.json.${process.pid}.tmp，如果测试脚本在一个进程里同时发起多次写入，单靠 pid 是不够的，还得带上时间戳或自增序号。后来我把命名改成了${process.pid}-${Date.now()}.tmp，问题才彻底消失。
5.4 参数校验全靠手写？不，用 zod 做运行时校验
CLI 工具的输入是用户直接敲的字符串，所以参数校验很重要。一开始我在每个命令里手写 if/else，后来发现代码重复率越来越高，错误提示也不统一。
改用 zod 之后，每个命令的校验逻辑变成声明式：
const schema = z.object({ city: z.string().min(1, '城市名不能为空'), days: z.number().int().min(1).max(14), });这样有两个好处：一是校验规则一目了然，二是 zod 的错误信息天然带中文自定义提示，用户能直接看懂。更重要的是，zod 的错误对象是结构化的，我可以在入口处统一捕获，以统一的格式打印出来。不是每个参数场景都需要这么重的校验，但对于需要收 user 输入的 CLI，这一层投入绝对值得。
6. 实测体验、优化调整与后续扩展方向
6.1 连续使用 15 天的体感数据与反馈
工具大概在用了两周之后，我统计了一下命令行工具的使用情况：每天平均触发 20 次左右，其中待办命令占了大头，天气和二维码次之。最意外的是image save的使用频率，因为平时截图真的太频繁了。
有几个细节让我意识到这个方向是对的：
- 我渐渐不再去翻旧脚本目录了，因为 cli-anything 的
list子命令能直接列出所有可用命令和帮助信息。 - 同事开始来问“这个命令怎么装”，而不是继续用自己零散的脚本。
- 有几次在服务器终端环境里需要查资料、生成二维码，一条命令解决，免去了本地装一堆图形工具的麻烦。
这些反馈说明：CLI 工具的价值不取决于功能多不多，而取决于它是不是能让人形成“肌肉记忆”。形成肌肉记忆的前提是入口统一、响应快、输出稳定。
6.2 可以继续扩展的方向：消息推送、模板生成、云剪切板
CLI-Anything 的插件机制铺好之后，我脑子里马上闪过几个可以后续做的方向。
第一个是“消息推送”：在长任务结束时通过 Server酱或企业微信机器人推一条通知到手机。很多 CI 流水线已经支持这种能力，但个人命令行工具，尤其是本地跑的脚本，很少能顺手推消息。如果做进 cli-anything，用户在脚本里可以一行命令完成通知，不用再各自配置 webhook。
第二个是“模板生成”：团队新建项目时，需要初始化目录结构、配置文件、README 框架。这些完全是模板渲染的事，做成命令比手动创建文件高效得多。而且模板文件本身可以放进一个独立的仓库，用插件机制加载，团队内部维护起来非常灵活。
第三个是“云剪切板”：在电脑 A 上复制一条配置，在电脑 B 上拉取。基于最简单的键值对存储接口就能实现，CLI 命令可以做clip write <key>和clip read <key>两个子命令。这个功能对经常在几台机器之间切换的开发者来说，比传文件工具更方便。
6.3 给想动手做 CLI 工具的人几条实在的建议
最后分享几条我在这个项目上沉淀下来的经验，都是踩过坑之后才真正理解的东西：
- 先做单命令原型，再做框架抽象。我在实际写第一个可用命令之前，花了太多时间在目录结构上，其实应该先用一个命令把整条链路跑通，比如命令行解析到输出打印。
- 帮助信息要写到“小白也能看懂”。别默认用户看过你的 README，每个命令的
--help输出应该自带示例，这是降低使用门槛最便宜的方式。 - 错误输出要走 stderr，不要跟正常结果混在 stdout 里。否则别人用管道处理你的输出时，会把错误信息当成有效数据。
- 为每一个新命令预设
--json输出开关。这是最简单的“可脚本化”设计，成本几乎为零，但能大大扩展工具的适用场景。 - 发布前至少要在一台干净机器上走一遍安装和卸载流程。很多依赖问题只在全新环境下暴露，只在自己的开发机上测是永远测不出来的。
回过头来看，CLI-Anything 最值钱的不是某一条命令的实现，而是把“想用命令行做任何事”的冲动，变成了一套有边界、能扩展、敢长期依赖的工具骨架。如果你也在被各种工具切来切去搞得不耐烦，不妨从一条最简单的命令开始，把它养成你自己的“Anything”。
