pangu-vis-cli

盘古可视化图表开发工具链 - 一站式图表创建、开发、打包、上传解决方案

简介

pangu-vis-cli 是一个专为盘古可视化平台设计的命令行工具，提供图表包的创建、开发调试、打包构建、上传发布等完整工作流支持。通过简洁的命令，开发者可以快速创建标准化的图表项目，进行本地开发调试，并一键打包上传至泰合社区。

核心价值：

• 🚀 快速初始化 - 一键创建标准化图表项目模板
• 🔧 开发友好 - 本地开发环境自动配置
• 📦 智能打包 - 版本管理、自动压缩、依赖优化
• 📤 便捷发布 - 认证上传至图表社区
• ⚙️ 灵活配置 - 自动化行为可自定义

特性

• ✅ 支持 8 种图表类型（折线图、柱状图、饼图、表格、地图、文本、指标、交互）
• ✅ 可选 TypeScript 支持
• ✅ 交互式命令行提示
• ✅ 自动版本同步（base.json ↔ package.json）
• ✅ 并发打包优化
• ✅ tar.gz 压缩包生成
• ✅ 用户认证与 token 管理
• ✅ 自动更新检测
• ✅ 跨平台支持（macOS / Windows / Linux）

安装

macOS

# 全局安装
sudo npm install -g pangu-vis-cli

# 或使用 pnpm
sudo pnpm install -g pangu-vis-cli

Windows

# 全局安装（管理员权限）
npm install -g pangu-vis-cli

# 或使用 pnpm
pnpm install -g pangu-vis-cli

Linux

# 全局安装
sudo npm install -g pangu-vis-cli

# 或使用 pnpm
sudo pnpm install -g pangu-vis-cli

验证安装

# 查看版本
pv -v
# 或
pvis -v

快速开始

创建第一个图表项目：

# 创建图表包
pv create my-line-chart

# 进入项目目录（根据提示）
cd packages/components/my-line-chart

# 启动开发环境
pnpm dev

完整工作流：

# 1. 创建图表包
pv create my-chart

# 2. 开发调试
cd packages/components/my-chart
pnpm dev

# 3. 打包构建（在图表包目录）
pv build

# 4. 用户认证
pv auth

# 5. 上传发布
pv upload my-chart_v1.0.0.tar.gz

命令详解

pv create - 创建图表包

创建新的图表项目模板。

别名：pv c

用法：

pv create <project-name>
pv c <project-name>

交互式选项：

1. 图表类型选择：

   • line - 折线图
   • bar - 柱状图
   • pie - 饼图
   • form - 表格
   • map - 地图
   • text - 文本
   • indicator - 指标
   • interaction - 交互
   • other - 其他

2. TypeScript 支持：

   • yes - 启用 TypeScript
   • no - 使用 JavaScript（默认）

3. 图表命名规则：

   • 必须以小写字母开头
   • 仅允许小写字母、数字、下划线
   • 推荐添加自定义前缀防止冲突

示例：

# 创建折线图（交互式）
pv create custom_line_chart

# 创建柱状图并启用 TypeScript
pv create custom_bar_chart
# 在交互提示中选择 "bar" 类型，启用 TS

创建目录结构：

• 在图表库根目录下：packages/components/<project-name>/
• 在 tailored 目录下：packages/tailored/<project-name>/

自动执行：

• 复制模板文件
• 配置图表类型和名称
• 安装项目依赖（pnpm install）

pv build - 单个图表打包

打包单个图表组件为 tar.gz 压缩包，准备上传。

别名：pv b

用法：

pv build                  # 打包当前目录图表
pv build <path>           # 打包指定路径图表

参数：

• <path> - 图表包路径（相对或绝对）

示例：

# 在图表包目录下执行
cd packages/components/my-chart
pv build

# 指定路径打包
pv build packages/components/my-chart

打包流程：

1. 版本同步（base.json ↔ package.json）
2. 执行 pnpm build
3. 生成产物目录：<chart-name>_v<version>/
4. 可选删除 es/ 目录（根据配置）
5. 过滤无用文件（.git, .vscode, .DS_Store）
6. 打包为 tar.gz：<chart-name>_v<version>.tar.gz
7. 可选删除打包目录（根据配置 autoRemove）
8. 可选自动上传（根据配置 autoUpload）

产物文件：

my-chart_v1.0.0.tar.gz

pv dev - 启动开发环境

启动图表包的本地开发服务器。

别名：pv d

用法：

pv dev              # 启动当前目录开发环境
pv dev <path>       # 启动指定路径开发环境

参数：

• <path> - 图表包路径

示例：

# 在图表包目录下执行
cd packages/components/my-chart
pv dev

# 指定路径启动
pv dev packages/components/my-chart

自动检测：

• 查找 package.json 中的 dev 或 serve 脚本
• 执行 pnpm dev 或 pnpm serve
• 实时预览图表开发效果

pv upload - 上传图表包

上传打包后的 tar.gz 文件至泰合社区服务器。

别名：pv u

前置条件：需先通过 pv auth 进行用户认证。

用法：

pv upload                      # 上传当前目录所有 .tar.gz 文件
pv upload <file.tar.gz>        # 上传指定 tar.gz 文件
pv upload <path>               # 上传指定目录下的所有 .tar.gz 文件

参数：

• <file.tar.gz> - tar.gz 文件路径
• <path> - 目录路径

示例：

# 用户认证（首次）
pv auth

# 上传当前目录所有 tar.gz
pv upload

# 上传指定文件
pv upload my-chart_v1.0.0.tar.gz

# 上传指定目录下的所有 tar.gz
pv upload dist/

认证要求：

• 未登录时自动触发认证流程
• 需输入泰合社区用户名和密码
• token 自动保存，后续无需重复登录

pv auth - 用户认证

登录泰合社区，获取上传权限。

别名：pv a

用法：

pv auth                    # 交互式登录
pv auth <user> <password>  # 命令行登录

参数：

• <user> - 泰合社区用户名
• <password> - 泰合社区密码

示例：

# 交互式登录（推荐）
pv auth
# 按提示输入用户名和密码

# 命令行登录
pv auth myuser mypassword

认证流程：

1. 输入用户名和密码（密码经 MD5 加密）
2. 请求服务器 token
3. 保存认证信息至本地配置文件

认证信息存储位置：

~/.pangu-vis-store/.cli_store

认证失败处理：

• 失败后可重试（最多 3 次）
• 失败 3 次后提示稍后尝试

pv tar - tar 打包工具

通用的 tar.gz 打包命令，可打包任意目录或文件。

别名：pv t

用法：

pv tar <targetDir> <name> [distDir] [distName]

参数：

• <targetDir> - 目标目录（必需）
• <name> - 打包文件名（必需）
• <distDir> - 输出目录（可选，默认为 targetDir）
• <distName> - 输出文件名（可选，默认为 name）

示例：

# 打包当前目录下的 dist 为 dist.tar.gz
pv tar ./dist dist

# 打包并指定输出目录
pv tar ./dist dist ./output

# 打包并指定输出文件名
pv tar ./dist dist ./output my-dist

pv config - 配置管理

配置 CLI 工具的自动化行为。

别名：pv set

用法：

pv config

交互式配置项：

| 配置项 | 说明 | 默认值 | | -------------- | ------------------------------ | ------------ | | autoUpload | 图表打包后是否自动上传泰合社区 | no (false) | | autoRemove | 打包后是否自动删除打包目录 | yes (true) | | autoRemoveEs | 打包后是否移除 es 目录 | yes (true) |

示例：

pv config
# 按提示选择配置项

配置文件位置：

~/.pangu-vis-store/.cli_store

配置文件格式：

{
  "user": "your-username",
  "password": "your-password",
  "token": "your-token",
  "autoUpload": false,
  "autoRemove": true,
  "autoRemoveEs": true
}

pv update - CLI 更新

检查并更新 CLI 工具至最新版本。

别名：pv up

用法：

pv update

更新流程：

1. 检查 npm 是否有新版本
2. 提示是否更新
3. 执行全局安装：npm i -g pangu-vis-cli
4. macOS/Linux 自动启用 sudo（如需）

示例：

# 检查更新
pv update

# 已是最新版本提示
当前版本已是最新！

# 有新版本时提示
是否更新Cli工具？ yes/no

自动检查：

• CLI 每次执行命令时自动检查更新（24小时内只检查一次）
• 检测到新版本时提示用户更新

配置

配置文件位置

CLI 配置信息存储在用户主目录：

~/.pangu-vis-store/.cli_store

配置项说明

| 配置项 | 类型 | 说明 | 默认值 | | -------------- | ------- | ----------------------- | ------- | | user | string | 泰合社区用户名 | '' | | password | string | 泰合社区密码（MD5加密） | '' | | token | string | 认证 token | '' | | autoUpload | boolean | 打包后自动上传 | false | | autoRemove | boolean | 打包后删除打包目录 | true | | autoRemoveEs | boolean | 打包后删除 es 目录 | true |

修改配置

方法 1：交互式配置

pv config

方法 2：手动编辑 编辑 ~/.pangu-vis-store/.cli_store 文件。

清除认证

如需重新登录，删除配置文件中的 token 字段：

# 编辑配置文件
vi ~/.pangu-vis-store/.cli_store

# 删除 token 行后重新认证
pv auth

使用示例

示例 1：创建并发布折线图

完整流程演示：

# 1. 创建折线图项目
pv create custom_line_chart
# 选择：折线图、不使用 TypeScript

# 2. 进入项目目录（根据提示）
cd packages/components/custom_line_chart

# 3. 启动开发环境
pnpm dev
# 在浏览器中开发调试图表

# 4. 开发完成后，打包图表
pv build
# 生成：custom_line_chart_v1.0.0.tar.gz

# 5. 用户认证
pv auth
# 输入泰合社区用户名和密码

# 6. 上传发布
pv upload custom_line_chart_v1.0.0.tar.gz
# 上传成功提示

示例 2：自动化配置

配置打包后自动上传：

# 配置自动上传
pv config
# 选择：autoUpload = yes

# 以后打包会自动上传
pv build my-chart
# 打包完成后自动上传，无需手动执行 pv upload

命令速查表

| 命令 | 别名 | 说明 | 是否需要认证 | | ----------- | -------- | ------------ | ------------------------ | | pv create | pv c | 创建图表包 | 可选（登录可注册图表ID） | | pv pack | pv pk | 图表库打包 | ❌ | | pv build | pv b | 单个图表打包 | ❌ | | pv dev | pv d | 启动开发环境 | ❌ | | pv upload | pv u | 上传图表包 | ✅ | | pv auth | pv a | 用户认证 | ❌ | | pv tar | pv t | tar 打包工具 | ❌ | | pv config | pv set | 配置管理 | ❌ | | pv update | pv up | CLI 更新 | ❌ |

常见问题

1. 安装失败或权限不足

macOS/Linux：

sudo npm install -g pangu-vis-cli

Windows： 以管理员身份运行终端，再执行安装命令。

2. 登录认证失败

• 检查用户名和密码是否正确
• 确认泰合社区账号已激活
• 失败 3 次后需稍后再试

3. 图表包名称重复

• 使用自定义前缀避免冲突
• 遵循命名规则：小写字母开头，仅允许字母、数字、下划线

4. 打包产物找不到

• 检查配置 autoRemove 是否为 yes
• 打包产物默认在图表包目录下
• 使用 pv tar 手动指定输出目录

5. 上传失败

• 确认已通过 pv auth 认证
• 检查网络连接（泰合社区服务器）
• 确认 tar.gz 文件格式正确

6. 版本号不同步

• CLI 自动同步 base.json 和 package.json 版本
• 手动修改版本时需同时更新两个文件
• 或使用 pv build 自动同步

7. 开发环境启动失败

• 确认已安装 pnpm
• 检查 package.json 中是否有 dev 或 serve 脚本
• 安装依赖：pnpm install

许可证

MIT License

Copyright (c) 2023 Jaxon

作者

Jaxon

如有问题或建议，请联系作者或在项目仓库提交 Issue。

最后更新：2026-06-17 版本：1.0.0