SuperAPI AI 工具集

npx-cli

编程与开发

查看项目

更新于 10-15 23:43

技能介绍

用途:本技能指导从零创建并发布可通过 npx 执行的 CLI 工具,以 Bun 作为主要运行时与工具链,但构建产物面向 Node.js 运行时的 npm/npx 用户。适用场景包括新建 CLI 工具、构建 npx 可执行二进制、设置参数解析、子命令与终端交互体验、发布到 npm,以及为已有库包添加 CLI。不适用于仅构建无 CLI 的库、构建非发布型应用或 monorepo(本技能面向单包仓库)。

主要能力:工具链约定使用 Bun 作为运行时与包管理器、Bunup 作为打包器(支持库与 CLI 双入口及 .d.ts)、citty 做参数解析(约 3KB、TypeScript 原生、自动帮助、runMain())、picocolors 处理终端颜色、Vitest 做测试、Changesets 做版本管理、Biome v2 与 ESLint 做格式化与类型感知检查,发布使用 npm publish --provenance。

使用方式:可通过脚手架脚本创建项目,命令为 bun run <skill-path>/scripts/scaffold.ts ./my-cli --name my-cli --bin my-cli --description "What this CLI does" --author "Your Name" --license MIT,支持 --bin、--cli-only、--no-eslint 选项。随后执行 bun install 并添加依赖。项目结构区分“库+CLI”双入口与仅 CLI 两种模式,CLI 入口为薄包装,业务逻辑放在可导入模块中以便单测。构建后可用 node ./dist/cli.js --help 本地验证,用 bunx changeset 与 bun run release 走发布流程。

关键限制:发布的 bin 文件必须使用 #!/usr/bin/env node 而非 bun;bin 指向 dist/ 中的编译后 JavaScript,不得指向 TypeScript 源码;需保证 bin 文件可执行;构建以 Node.js 为目标;package.json 使用 "type": "module",types 须位于 exports 各条件首位,files 仅列 dist。错误处理不应暴露原始堆栈,退出码约定成功 0、错误 1、参数错误 2、SIGINT 130。Bun 特有注意:bun build 不生成 .d.ts、不做语法降级,bun publish 不支持 --provenance 且使用 NPM_CONFIG_TOKEN。