{T}

CLI 工具开发与开源项目规范

概述

CLI 工具是工程化能力的直接体现——把重复性操作（备份、初始化、构建）固化成一条命令。本文以 VS Code 插件批量管理工具 VSEXT 为例，拆解一个 CLI 从"调用现成命令"到"发布为全局命令"的实现思路，再系统梳理开源项目的两条命脉：README 文档规范与开源协议选择，最后给出目录结构、package.json、.gitignore、CHANGELOG 的落地模板。

学习目标

  • 用 child_process + 现成命令快速拼出一个实用 CLI
  • 通过 package.json 的 bin 字段把脚本发布为全局命令
  • 写出结构完整、无废话的 README（含国际化）
  • 依据"是否允许闭源 / 是否需要专利保护"选对开源协议
  • 用 Keep a Changelog 规范维护版本变更

一、CLI 工具开发：以 VSEXT 为例

痛点：VS Code 插件重装系统后要逐个装、团队插件配置难统一。VSEXT 用两个命令解决：vsextd 导出已装插件为 .vsix，vsexti 批量离线安装。

核心思路是"组合现成能力"，而非从零造轮子：

javascript
// 1. 列出已安装插件（复用 VS Code 自带命令）
const list = execSync('code --list-extensions').toString().split('\n').filter(Boolean);
 
// 2. 逐个下载 .vsix（拼 Marketplace 下载地址）
list.forEach((ext) => { /* 拉取 vspackage 到 downloads/ */ });
 
// 3. 批量安装离线包
fs.readdirSync('./downloads').forEach((f) =>
  execSync(`code --install-extension ./downloads/${f}`)
);

要让 vsextd / vsexti 成为全局命令，关键是 package.json 的 bin：

json
{
  "bin": {
    "vsextd": "./bin/vsextd.js",
    "vsexti": "./bin/vsexti.js"
  },
  "scripts": { "build": "tsc", "test": "jest" },
  "license": "MIT"
}

入口脚本首行需 #!/usr/bin/env node，本地调试用 npm link 把命令挂到全局。

二、README 文档规范

一份合格的开源 README 应包含：一句话定位、简介、特性、安装、快速开始、使用场景、开发指引、贡献方式、许可证。AI 可以据此快速起草，但务必人工校对，去掉营销腔和无意义堆砌。

国际化用独立文件 + 顶部语言切换链接：

markdown
[English](./README.md) | [中文](./README_CN.md)

命名约定：README.md（默认英文）、README_CN.md、README_JP.md 等，互不覆盖。

三、开源协议选择

协议决定别人能拿你的代码做什么。核心差异在"是否允许闭源"与"修改后是否要开源"：

协议允许闭源需保留声明专利条款适用
MIT是是无大多数项目，最宽松
Apache 2.0是是有需要专利保护
BSD是是无近似 MIT
LGPL是（仅库）是无类库，允许闭源调用
GPL否是无强制衍生开源（Copyleft）
AGPL否是无网络服务也受约束

选择逻辑：希望衍生作品也开源 → GPL；否则需要专利保护 → Apache 2.0；都不需要 → MIT（默认推荐）。MIT 唯一硬性要求是保留版权与许可声明。VS Code 里装 Choose a License 插件可一键生成 LICENSE 文件。

四、项目结构规范

plaintext
project/
├── .github/              # Issue/PR 模板
├── src/                  # 源码
├── tests/                # 测试
├── docs/                 # 文档
├── .gitignore            # Git 忽略
├── .npmignore            # NPM 发布忽略
├── LICENSE               # 协议
├── README.md             # 英文说明
├── README_CN.md          # 中文说明
├── package.json
├── tsconfig.json
└── CHANGELOG.md          # 变更日志

.gitignore 至少要忽略 node_modules/、dist/、.env、.DS_Store、coverage/。CHANGELOG 推荐 Keep a Changelog 格式，按版本分组、用 Added / Changed / Fixed 分类：

markdown
## [1.2.0] - 2026-03-08
### Added
- 新增进度条显示
### Fixed
- 修复 Windows 路径问题

常见问题

Q: 个人小工具该选什么协议？

默认 MIT。它几乎无限制（可商用、可闭源、可改名再分发），唯一义务是保留原始版权与许可声明，传播成本最低，也不会给后续使用者制造法律风险。

Q: CLI 入口脚本为什么要 #!/usr/bin/env node？

这是 shebang，告诉系统在用 shell 直接执行该文件时，用 node 解释器运行它。没有这行，npm install -g 后全局命令无法正常启动。配合 package.json 的 bin 字段，npm 会在安装时把它链接到 PATH 下的可执行入口。

延伸阅读