Workspace CLI

工作空间管理 CLI 工具，用于初始化、扫描和管理工作空间下的多个 Git 项目。

安装

npm install -g @wanggangqi/workspace-cli

或者使用 npx：

npx @wanggangqi/workspace-cli init

功能特性

• 🚀 快速初始化工作空间
• 🔍 自动扫描 Git 项目
• 📁 分组管理项目
• 📝 智能项目描述
• 🔄 批量克隆仓库
• 🌿 分支信息管理
• 🌐 一键初始化 Nginx 环境（多空间隔离）

前置要求

• Node.js >= 14.0.0
• PowerShell 7+ (pwsh) - 用于执行 Nginx 管理脚本

安装 PowerShell 7

Windows:

# 使用 winget
winget install Microsoft.PowerShell.7

# 或使用 Chocolatey
choco install powershell-core

macOS:

brew install --cask powershell

Linux:

# Ubuntu/Debian
sudo apt install powershell

# 或其他发行版，参考：https://learn.microsoft.com/zh-cn/powershell/scripting/install/installing-powershell

安装完成后，使用 pwsh 命令验证安装。

命令说明

wsc init 或 workspace-cli init

初始化工作空间，创建 .workspace/config.json 配置文件。

# 在当前目录初始化工作空间
workspace-cli init

# 创建新目录并初始化为工作空间
workspace-cli init my-workspace

参数说明：

• directory (可选): 要创建的工作空间目录名称。如果不指定，则在当前目录初始化；如果指定，则创建该目录并初始化。

默认配置： 初始化时会自动从包自带的 config.json 加载默认配置：

• 平台组 - 包含预配置的仓库列表（erdcloud-plat-frontend, erdcloud-plat-plugins-frontend 等）
• other - 未分组（空列表）

使用示例：

# 创建一个新项目空间
workspace-cli init plat-workspace
cd plat-workspace

wsc scan 或 workspace-cli scan

扫描工作空间下的所有 Git 项目，并更新到配置文件中。

# 交互式扫描（默认）
workspace-cli scan

# 非交互式，自动添加到 other 分组
workspace-cli scan --no-interactive

说明：

• 自动向上查找 .workspace/config.json，在工作空间根目录下扫描
• 对于新发现的项目，会交互式询问分组和描述
• 对于已存在的项目，会自动更新分支信息

wsc list 或 workspace-cli list

列出工作空间中的所有项目。

# 列出所有项目
workspace-cli list

# 只列出指定分组的项目
workspace-cli list -g 平台组

wsc add 或 workspace-cli add

添加项目到工作空间（项目名自动从 URL 提取，克隆后自动获取分支）。

# 基本用法
workspace-cli add http://gitlab.example.com/repo.git

# 指定分支克隆
workspace-cli add http://gitlab.example.com/repo.git -b develop

# 指定分组和别名
workspace-cli add http://gitlab.example.com/repo.git \
  --group 平台组 \
  --description "平台前端项目" \
  --alias plat

参数说明：

• -b, --branch - 指定克隆分支
• -g, --group - 指定分组
• -d, --description - 项目描述
• -a, --alias - 项目别名

wsc alias 或 workspace-cli alias

为项目设置别名，方便快速操作常用项目。

# 为项目设置别名
workspace-cli alias erdcloud-plat-frontend plat

# 通过别名操作项目
workspace-cli open plat

别名可用于 open、remove 等命令。

wsc unalias 或 workspace-cli unalias

移除项目别名。

# 移除别名（可使用项目名或别名）
workspace-cli unalias plat

wsc open 或 workspace-cli open

使用编辑器打开项目。

# 使用 VS Code 打开项目（默认）
workspace-cli open plat

# 使用 Trae 打开项目
workspace-cli open plat --editor trae

# 使用 WebStorm 打开项目
workspace-cli open plat --editor webstorm

# 使用项目名打开
workspace-cli open erdcloud-plat-frontend -e code

参数说明：

• -e, --editor - 指定编辑器，支持：code (VS Code)、trae、webstorm

wsc remove 或 workspace-cli remove

从工作空间移除项目。

workspace-cli remove test-materials

wsc clone 或 workspace-cli clone

克隆配置文件中所有的仓库到当前目录。

# 克隆所有仓库
workspace-cli clone

# 只克隆指定分组的仓库
workspace-cli clone -g 平台组

wsc nginx 或 workspace-cli nginx

管理 nginx 配置和启动，用于本地开发环境。支持多空间隔离，每个工作空间拥有独立的 nginx 实例。

wsc nginx init

初始化当前工作空间的 nginx 环境。自动下载 nginx Windows 绿色版，复制所有配置文件，解决多空间 nginx 冲突问题。

# 初始化 nginx（默认版本 1.24.0）
wsc nginx init

# 指定 nginx 版本
wsc nginx init -v 1.26.0

# 指定代理后端地址（默认 http://192.168.10.189）
wsc nginx init -p http://192.168.1.100:8080

# 跳过下载，只生成配置文件
wsc nginx init --skip-download

功能说明：

1. 自动分配独立端口：扫描同一目录下的其他工作空间，自动分配未被使用的端口段（默认从 50000 开始，每个空间间隔 1000）

2. 下载 nginx：从 nginx.org 自动下载 Windows 绿色版

3. 生成配置结构：

   • .workspace/nginx/nginx-{version}/ - nginx 程序目录
   • .workspace/nginx/conf.d/ - 项目配置文件目录（自动复制所有 .conf 文件）
   • .workspace/nginx/logs/ - 独立日志目录

4. 复制管理脚本：复制并修改 nginx-config/ 下的 PowerShell 脚本

   • start-nginx.ps1 - 启动脚本（使用工作空间的 nginx）
   • stop-nginx.ps1 - 停止脚本
   • reload-nginx.ps1 - 重载配置脚本
   • status-nginx.ps1 - 状态检查脚本

5. 替换配置占位符：自动替换配置文件中的占位符

   • <workspaceDir> → 工作空间根目录路径
   • <proxyTarget> → 代理后端接口地址（默认 http://192.168.10.189）

配置文件更新：

初始化后会在 .workspace/config.json 中添加 nginx 配置：

{
  "nginx": {
    "version": "1.24.0",
    "basePort": 50000,
    "proxyTarget": "http://192.168.10.189",
    "installed": true,
    "binDir": "...",
    "configDir": "...",
    "logsDir": "...",
    "configs": [...]
  }
}

访问方式：

配置完成后，直接通过 IP + 端口访问：

• http://127.0.0.1:5006 （具体端口取决于配置）

无需配置 hosts 文件。

nginx 配置示例：

在 nginx-config/ 目录下的 .conf 文件可以使用以下占位符：

server {
    listen 5006;
    server_name 127.0.0.1;

    location / {
        root <workspaceDir>/dist;  # 将替换为工作空间根目录
        index index.html;
    }

    location /api {
        proxy_pass <proxyTarget>;  # 将替换为 http://192.168.10.189
    }
}

配置完成后，直接通过 IP + 端口访问：

• http://127.0.0.1:5006 （具体端口取决于配置）

wsc nginx start

启动当前工作空间的 nginx。

wsc nginx start

wsc nginx stop

停止当前工作空间的 nginx。

wsc nginx stop

wsc nginx reload

重新加载当前工作空间的 nginx 配置。

wsc nginx reload

wsc nginx status

查看当前工作空间的 nginx 状态。

wsc nginx status

wsc nginx list

列出所有可用的 nginx 配置模板。

wsc nginx list

多空间隔离机制：

| 空间 | 基础端口 | 进程隔离 | | ----------- | -------- | -------- | | workspace-a | 50000 | 独立进程 | | workspace-b | 51000 | 独立进程 | | workspace-c | 52000 | 独立进程 |

注意事项：

• 每个工作空间的 nginx 使用独立的 pid 文件，避免进程冲突
• 配置文件通过 include 加载 conf.d/ 下的所有 .conf 文件
• 启动前会自动检查配置是否正确
• 停止时只停止当前工作空间的 nginx 进程

完整使用流程：

# 1. 创建工作空间
wsc init my-project --ai claude-code
cd my-project

# 2. 初始化 nginx
wsc nginx init

# 3. 启动当前空间的 nginx
wsc nginx start

# 4. 查看状态
wsc nginx status

# 5. 修改配置后重载
wsc nginx reload

# 6. 停止 nginx
wsc nginx stop

或者直接使用 PowerShell 脚本：

# 使用 PowerShell Core (pwsh) 执行（需要安装 PowerShell 7+）
pwsh -ExecutionPolicy Bypass -File .workspace/nginx/start-nginx.ps1
pwsh -ExecutionPolicy Bypass -File .workspace/nginx/stop-nginx.ps1
pwsh -ExecutionPolicy Bypass -File .workspace/nginx/reload-nginx.ps1
pwsh -ExecutionPolicy Bypass -File .workspace/nginx/status-nginx.ps1

注意： 需要安装 PowerShell 7+（pwsh），Windows 自带的 Windows PowerShell 5.1 可能不兼容。

配置文件结构

.workspace/config.json：

{
  "version": "1.0",
  "groups": {
    "平台组": {
      "code": "plat",
      "description": "平台相关仓库集合",
      "repos": [
        {
          "name": "erdcloud-plat-frontend",
          "url": "http://gitlab.example.com/erdcloud-plat-frontend.git",
          "descriptions": ["平台前端", "plat前端"],
          "branch": "develop"
        }
      ]
    }
  },
  "nginx": {
    "version": "1.24.0",
    "basePort": 50000,
    "installed": true,
    "binDir": ".workspace/nginx/nginx-1.24.0",
    "configDir": ".workspace/nginx/conf.d",
    "logsDir": ".workspace/nginx/logs",
    "configs": [{ "name": "5006_plat", "file": "5006_plat.conf", "port": 5006 }]
  }
}

License

MIT