wusum-fantastic-utils

前端项目运维 CLI 工具集：一键发布、压缩打包、Swagger 生成 TypeScript、远程备份、AI Skills 管理。

前置要求

• Node.js >= 18.0.0
• 操作系统: Windows（推荐 PowerShell）、Linux、macOS
• Git（sk 命令需要）
• 使用密钥登录时，需确保对 id_rsa 私钥文件有读取权限

⚠️ 重要: 本工具为全局 CLI 工具，不支持在项目内局部安装。

安装

# npm
npm install wusum-fantastic-utils -g

# cnpm
cnpm install wusum-fantastic-utils -g

# yarn
yarn global add wusum-fantastic-utils

# pnpm
pnpm add wusum-fantastic-utils -g

验证安装：

dp -v

配置文件

新建一个 YAML 文件（如 config.yaml）：

myProject:
  local_dist_dir: 'D:/work/my-project/dist'        # 本地打包产物目录（必填）
  project_api_dir: 'D:/work/my-project/src/services' # API文件输出目录（st命令用）
  project_name: 'MY_PROJECT'                        # 项目别名，用于压缩包命名（必填）
  swagger_json_http_url:                            # Swagger在线地址（st命令用，支持数组）
    - 'https://api.example.com/v3/api-docs'
  server:                                           # 服务器配置（dp/bk命令用）
    ip: '192.168.1.100'
    port: '22'
    user: 'root'
    password: ''                                    # 密码与私钥二选一
    privateKeyPath: 'C:/Users/xxx/.ssh/id_rsa'     # SSH私钥绝对路径
    server_dir: '/xh22sc/my-project/web'            # 远程部署目录，必须以 /xh22sc/ 开头

多服务器配置（发布到多台）：

server:
  - ip: '192.168.1.100'
    port: '22'
    user: 'root'
    privateKeyPath: 'C:/Users/xxx/.ssh/id_rsa'
    server_dir: '/xh22sc/my-project/web'
  - ip: '192.168.1.101'
    port: '22'
    user: 'root'
    privateKeyPath: 'C:/Users/xxx/.ssh/id_rsa'
    server_dir: '/xh22sc/my-project/web'

设置配置文件路径

首次使用前，需设置配置文件路径（5 个命令共用）：

dp set config ./config.yaml

查看配置：

# 查看所有项目
dp get config

# 查看指定项目
dp get config myProject

# 查看当前配置文件路径
dp get config path

命令使用

dp — 项目发布

通过 SSH 将本地 dist 发布到远程服务器。

| 子命令 | 说明 | |--------|------| | dp -h | 查看帮助 | | dp -v | 查看版本 | | dp set config <path> | 设置配置文件路径 | | dp get config [projectName/path] | 查看配置 | | dp <projectName> | 交互式选择发布方式 | | dp <projectName> -t all | 全量更新（删除远程所有内容后上传完整dist） | | dp <projectName> -t part | 部分更新（仅替换顶层文件，保留子目录） |

示例：

dp myProject       # 交互选择
dp myProject -t all   # 全量更新
dp myProject -t part  # 部分更新

🔒 远程目录必须位于 /xh22sc/ 路径下，否则会拒绝执行。

发布流程：连接 SSH → 本地压缩 → 上传 → 清理远程目录 → 解压 → 删除远程 zip → 删除本地 zip

zp — 压缩打包

将本地 dist 压缩为 zip/tar，输出到桌面。

| 子命令 | 说明 | |--------|------| | zp -h | 查看帮助 | | zp -v | 查看版本 | | zp set config <path> | 设置配置文件路径 | | zp get config [projectName/path] | 查看配置 | | zp <projectName> | 交互式选择压缩格式 | | zp <projectName> -t zip | zip 格式（默认） | | zp <projectName> -t tar | tar 格式 |

示例：

zp myProject       # 交互选择
zp myProject -t zip
zp myProject -t tar

输出命名：{project_name}@{YYYY-MM-DD_HH_mm_ss}.zip，如 MY_PROJECT@2024-07-27_14_30_00.zip

st — Swagger 转 TypeScript

从 Swagger/OpenAPI JSON 自动生成 TypeScript 类型和 HTTP 客户端。

| 子命令 | 说明 | |--------|------| | st -h | 查看帮助 | | st -v | 查看版本 | | st set config <path> | 设置配置文件路径 | | st get config [projectName/path] | 查看配置 | | st <projectName> | 交互式选择生成模式 | | st <projectName> -t types | 仅生成类型定义（services.d.ts） | | st <projectName> -t clients | 仅生成 HTTP 客户端（services.all.ts） | | st <projectName> -t full | 同时生成类型和客户端 |

示例：

st myProject           # 交互选择
st myProject -t types
st myProject -t clients
st myProject -t full

输出位置：配置文件中的 project_api_dir 目录

💡 swagger_json_http_url 支持数组，可合并多个 Swagger 源。

bk — 远程备份

在远程服务器上备份项目目录。

| 子命令 | 说明 | |--------|------| | bk -h | 查看帮助 | | bk -v | 查看版本 | | bk set config <path> | 设置配置文件路径 | | bk get config [projectName/path] | 查看配置 | | bk <projectName> | 交互式选择备份类型 | | bk <projectName> -t dir | 复制目录：cp -r folder folder-{timestamp} | | bk <projectName> -t zip | zip 压缩 | | bk <projectName> -t gz | tar.gz 压缩 | | bk <projectName> -t xz | tar.xz 压缩 | | bk <projectName> -t tar | tar 归档 |

示例：

bk myProject       # 交互选择
bk myProject -t gz

🔒 远程目录必须位于 /xh22sc/ 路径下。

sk — AI Skills 管理

下载和安装 AI 开发助手 Skills。

| 子命令 | 说明 | |--------|------| | sk -h | 查看帮助 | | sk -v | 查看版本 | | sk get | 下载 Skills 压缩包到桌面 | | sk set claude | 安装到 Claude（~/.claude/） | | sk set kimi | 安装到 Kimi（~/.kimi/skills/ + KIMI.md） | | sk set cursor | 安装到 Cursor（~/.cursor/skills/） | | sk set opencode | 安装到 OpenCode（~/.config/opencode/） |

示例：

sk get
sk set claude
sk set kimi
sk set cursor
sk set opencode

安装路径对照：

| 目标 | 安装路径 | 说明 | |------|----------|------| | Claude | ~/.claude/ | 完整复制仓库全部内容 | | Kimi | ~/.kimi/skills/ + ~/.kimi/KIMI.md | 仅复制 skills 子目录，CLAUDE.md 重命名为 KIMI.md | | Cursor | ~/.cursor/skills/ | 仅复制 skills 子目录（Cursor 只读取 skills 目录下的 SKILL.md） | | OpenCode | ~/.config/opencode/ | 完整复制仓库全部内容 |

快速上手示例

# 1. 全局安装
npm install wusum-fantastic-utils -g

# 2. 创建 config.yaml 并填写项目信息

# 3. 设置配置路径
dp set config ./config.yaml

# 4. 开始使用
dp myProject      # 发布
zp myProject      # 压缩
st myProject      # 生成 TS
bk myProject      # 备份