npm package: @mrbaoquan/pano-cli
Description: krpano 全景项目 CLI 工具 — 一键创建、构建、发布全景漫游
Author: qz-360
Latest version: 2.2.0

# @mrbaoquan/pano-cli

krpano 全景项目 CLI 工具 — 一键创建、构建、预览、发布全景漫游。

## 安装

```bash
npm install -g @mrbaoquan/pano-cli
```

## 更新

```bash
npm update -g @mrbaoquan/pano-cli
```

## 快速开始

```bash
# 1. 设置全局 krpano 路径（只需一次）
pano config --global --krpano "F:\path\to\krpano-1.20.12"

# 2. 创建项目
pano create my-tour

# 3. 将全景图 .jpg 放入 panoramas/ 下的子文件夹
#    如: panoramas/1-展厅A/  panoramas/2-展厅B/

# 4. 初始化工程（自动生成 vtour 目录、瓦片、XML）
cd my-tour
pano init

# 5. 本地预览
pano serve
```

> 所有命令支持在**项目根目录**或 **vtour/** 目录下运行。

---

## 命令参考

### `pano create <name>`

创建新全景项目骨架。

```bash
pano create my-tour
```

交互式提示输入 krpanotools 路径（已设置全局配置时回车即可使用全局值）。

创建的目录结构：

```
my-tour/
├── vtour/
│   ├── scenes.config.json    # 项目配置
│   ├── tour.xml              # krpano 主配置
│   ├── hotspots/             # 热点数据
│   └── WORKFLOW.md           # 工作流说明
├── panoramas/default/        # 全景图存放目录
├── .gitignore
└── README.md
```

---

### `pano init`

首次初始化工程。自动完成：

- 扫描 `panoramas/` 目录结构，同步 groups 到 `scenes.config.json`
- 调用 krpanotools 生成 vtour 基础文件（tour.html、skin/、plugins/）
- 复制内置 panohper UI 库
- 生成全部场景瓦片
- 生成 scenes.xml 和 skin/groups.xml

```bash
pano init
```

> 如已存在 `tour.html` 会跳过，需重新初始化请先删除相关文件。

---

### `pano sync [--force]`

增量同步：扫描新增全景图、生成瓦片、更新 XML。

```bash
pano sync          # 仅处理新增图片
pano sync --force  # 强制重新生成所有瓦片
```

---

### `pano xml`

仅更新 XML（不生成瓦片），适用于修改分组、标题后快速刷新。

```bash
pano xml
```

---

### `pano editor`

进入编辑模式 — 将场景内联到 tour.xml，方便在 krpano 编辑器中拖拽热点。

```bash
pano editor
```

---

### `pano save`

保存编辑模式中的热点修改，恢复 include 模式。

```bash
pano save
```

---

### `pano serve [-p <port>] [--edit]`

启动本地 HTTP 预览服务器。

```bash
pano serve            # 默认端口 8090
pano serve -p 3000    # 指定端口
pano serve --edit     # 开启可视化编辑器
pano serve -e -p 8092 # 指定端口 + 编辑器
```

自动处理端口冲突（向上递增尝试）。

**`--edit` 编辑模式** 会在浏览器中注入编辑器面板，无需插件即可完成以下操作：

| 功能 | 说明 |
| --- | --- |
| 设为默认视角 | 保存当前视角（ath/atv/fov）到 `sceneOverrides` |
| 热点管理 | 添加、编辑、删除场景热点（跳转/链接），保存至 `hotspots/*.xml` |
| 排序管理 | 拖拽调整分组顺序及组内场景顺序，保存后重新生成 XML |
| 生成 XML | 重新扫描并生成 `scenes.xml` + `skin/groups_data.xml` |

---

### `pano config [options]`

查看或修改配置。

```bash
# 查看项目配置
pano config

# 设置项目 krpanotools 路径
pano config --krpano "F:\path\to\krpano"

# 设置全景图源目录
pano config --source "../panoramas"

# 查看全局配置
pano config --global

# 设置全局 krpanotools 路径（所有项目共享）
pano config --global --krpano "F:\path\to\krpano"
```

**配置优先级**：项目 `scenes.config.json` > 全局 `~/.pano-cli/config.json`

---

### `pano clean`

清除旧瓦片数据（已删除场景对应的 .tiles 目录）。

```bash
pano clean
```

---

### `pano publish [--oss]`

打包发布文件。

```bash
pano publish         # 本地打包
pano publish --oss   # 瓦片路径指向 OSS
```

使用 `--oss` 时需在 `scenes.config.json` 中配置 `ossBaseUrl` 和 `ossBucket`。

---

### `pano dev <module> <path>`

链接本地模块仓库进行开发（如 panohper UI 库）。

```bash
# 链接本地 panohper 仓库
pano dev panohper ../panohper

# 查看链接状态
pano dev --status

# 恢复为内置版本
pano dev --reset panohper
```

---

## 全局选项

| 选项            | 说明             |
| --------------- | ---------------- |
| `-v, --verbose` | 详细输出         |
| `-q, --quiet`   | 仅显示警告和错误 |
| `-V, --version` | 显示版本号       |

---

## scenes.config.json

```jsonc
{
  "krpanoToolsPath": "", // krpano 安装目录（可省略，使用全局配置）
  "panoSourceDir": "../panoramas", // 全景图源目录（相对 vtour/）
  "startScene": "展馆外观", // 默认起始场景名

  "ossBaseUrl": "https://xxx.com", // OSS 基础 URL（publish --oss 时使用）
  "ossBucket": "oss://bucket/path", // OSS 存储路径

  "groups": [
    // 分组（pano init/sync 自动生成；scenes 字段由排序编辑器写入）
    {
      "name": "展厅A",
      "folders": ["1-展厅A"],
      "scenes": ["panorama1", "panorama2"] // 可选：显式指定组内场景顺序
    }
  ],

  "sceneOverrides": {
    // 场景标题覆盖（也可在编辑器中通过「设为默认视角」写入 ath/atv/fov）
    "原始文件名": { "title": "自定义标题", "ath": 0, "atv": 0, "fov": 90 },
  },
}
```

> `groups` 由 `pano init` / `pano sync` 自动扫描 `panoramas/` 目录生成，无需手动配置。
> 文件夹名前缀数字会自动去除作为分组名（如 `0-展馆外观` → `展馆外观`）。
> `groups[].scenes` 由**排序编辑器**（`pano serve --edit`）写入，控制该组内场景在 XML 中的顺序。

---

## 典型工作流

```
1. pano create my-tour          # 创建项目
2. 放入全景图到 panoramas/      # 按子文件夹分组
3. pano init                    # 初始化（生成瓦片 + XML）
4. pano serve --edit            # 预览 + 可视化编辑
   ├── 设为默认视角              # 调整每个场景的初始视角
   ├── 热点管理                  # 添加/编辑/删除跳转热点
   ├── 排序管理                  # 调整分组和场景顺序
   └── 生成 XML                 # 应用所有改动
5. pano publish                 # 打包发布
```

**新增场景**：放入图片 → `pano sync`
**修改标题**：编辑 sceneOverrides → `pano xml`
**新增分组**：在 panoramas/ 下创建文件夹并放入图片 → `pano sync`
**调整顺序**：`pano serve --edit` → 排序管理 → 保存 → 生成 XML

---

## 依赖

- **Node.js** >= 18
- **krpano** 1.20+（需自行购买，用于瓦片生成）

## License

MIT