osynic_serializer 0.1.3

# OsynicSerializer Interactive CLI - 使用指南


## 🎉 欢迎使用改进的交互式 CLI


你的 `osynic-serializer` 现在支持 **完全交互式模式**，就像 Vite、Create-React-App 一样！

## 📚 使用方式


### 方式 1️⃣：完全交互式（最推荐新手）


```bash
osynic-sl
```

然后：
1. 选择输出格式（songs 或 sets）- 使用 ↑↓ 箭头键选择，Enter 确认
2. 选择算法（osudb 或 folder）
3. 确认或输入 osu! 路径
4. 输入输出文件夹路径（默认 ./output）
5. 程序自动处理并保存结果

**效果：**
```
🎵 OsynicSerializer - Interactive Mode

📋 Select output JSON type:
  songs
❯ sets

🔧 Select serialization algorithm:
❯ osudb (Database - Recommended)
  folder (Direct scan)

📁 Detected osu! installation at: C:\Users\YourName\AppData\Local\osu!
Use this path? (y/n)
❯ Yes

📁 Enter output directory path: [./output]
❯ (直接按 Enter)

⏳ Processing...

✅ Total beatmapsets after diff: 2450
📄 Output file: ./output/sets_dm_250405010203.json
```

### 方式 2️⃣：部分指定（混合模式）


如果你已经知道某些参数，可以直接指定：

```bash
# 只指定输出格式，其他由交互式提示

osynic-sl -t songs

# 只指定算法

osynic-sl -a folder

# 指定多个参数

osynic-sl -t sets -a osudb
```

这样只会提示缺失的参数。

### 方式 3️⃣：完整命令行（脚本/自动化）


如果你需要在脚本中使用或完全自动化，指定所有参数来跳过交互提示：

```bash
osynic-sl -t songs -a osudb -p "C:\Users\YourUser\AppData\Local\osu!" -o "./output"
```

完全兼容所有原有脚本！

## 🔧 参数说明（针对脚本使用）


| 参数          | 短写 | 说明             | 可选值             |
| ------------- | ---- | ---------------- | ------------------ |
| `--algorithm` | `-a` | 序列化算法       | `osudb` / `folder` |
| `--json-type` | `-t` | 输出 JSON 格式   | `songs` / `sets`   |
| `--path`      | `-p` | osu! 安装路径    | 任意有效路径       |
| `--output`    | `-o` | 输出目录         | 任意有效路径       |
| `--diff`      | `-d` | 差量对比文件路径 | 任意有效路径       |
| `--help`      | `-h` | 显示帮助         | -                  |
| `--version`   | `-V` | 显示版本         | -                  |

## 💡 常见使用场景


### 场景 1️⃣：我是新用户，完全不知道怎么使用


```bash
# 什么都别想，就跑这个命令

osynic-sl

# 然后就按照屏幕提示做选择即可

```

### 场景 2️⃣：我已经用过这个工具，知道参数了


```bash
# 全部指定，一步完成，适合脚本和自动化

osynic-sl -t songs -a osudb -p "C:\my\osu\path" -o "./backup"
```

### 场景 3️⃣：我想要 sets 格式，但不知道其他参数


```bash
# 指定 JSON 类型，其他用交互式提示

osynic-sl -t sets
```

### 场景 4️⃣：我需要进行差量对比


```bash
# 混合使用，specify 差量文件

osynic-sl -t songs -d "./remote/songs.json"

# 然后程序会提示输入 osu! 路径和输出目录

```

## 🎯 特色功能


### 🔍 智能路径检测


程序会自动检测你的 osu! 安装位置，然后：
```
📁 Detected osu! installation at: C:\Users\...\AppData\Local\osu!
Use this path? (y/n)
```

- **选择 Yes (y)**: 使用检测到的路径 ✅
- **选择 No (n)**: 手动输入自定义路径 ✨

### 🎨 友好的用户界面


每个步骤都有清晰的 emoji 图标：
- 🎵 - 标题和主要提示
- 📋 - JSON 类型选择
- 🔧 - 算法选择
- 📁 - 路径和目录相关
- ✅ - 成功和完成
- 📄 - 输出文件信息

### ⌨️ 键盘导航


在选择菜单中：
- **↑ ↓** - 在选项间移动
- **Enter** - 确认选择
- **Esc** - 取消（在某些情况下）

### 💾 智能文件名


输出文件会自动添加时间戳，避免覆盖：
```
songs_dm_250405010203.json
sets_m_250405010213.json
diff_songs_dm_250405010220.json
```

## 📋 高级用法


### 批处理脚本示例


```batch
@echo off
REM 导出 songs 格式
osynic-sl -t songs -o ./export

REM 导出 sets 格式用于对比
osynic-sl -t sets -o ./export

REM 进行差量对比
osynic-sl -t sets -d "./remote/sets.json" -o ./missing_beatmaps

echo 完成!
```

### PowerShell 脚本示例


```powershell
# 定义 osu! 路径

$osuPath = "$env:USERPROFILE\AppData\Local\osu!"

# 导出所有谱面

osynic-sl -t songs -p $osuPath -o "./backup_$(Get-Date -Format 'yyyyMMdd')"

# 检查是否成功

if ($LASTEXITCODE -eq 0) {
    Write-Host "✅ 导出成功！"
} else {
    Write-Host "❌ 导出失败！"
}
```

### Linux/Mac 脚本示例


```bash
#!/bin/bash


OSU_PATH="$HOME/.osu/drive_c/users/$USER/AppData/Local/osu!"
OUTPUT_DIR="./backup_$(date +%Y%m%d)"

# 运行导出

osynic-sl -t songs -p "$OSU_PATH" -o "$OUTPUT_DIR"

if [ $? -eq 0 ]; then
    echo "✅ Export successful!"
    ls -lh "$OUTPUT_DIR"
else
    echo "❌ Export failed!"
    exit 1
fi
```

## 🐛 故障排除


### 问题 1️⃣：找不到 osu! 安装


**症状：** 程序提示 "osu! path not found"

**解决：**
1. 手动输入你的 osu! 路径
2. 确保路径存在且可读
3. 尝试使用绝对路径而不是相对路径

```bash
# ❌ 可能不工作

osynic-sl -p ".\osu!"

# ✅ 应该可以工作

osynic-sl -p "C:\Games\osu!"
```

### 问题 2️⃣：权限被拒绝


**症状：** "Permission denied" 或类似错误

**解决：**
- 确保你有读取 osu! 文件夹的权限
- 尝试以管理员身份运行
- Windows: 右键 -> "Run as administrator"

### 问题 3️⃣：输出文件为空或数据不完整


**症状：** 生成的 JSON 文件很小或缺少数据

**解决：**
1. 确保 osu! 安装路径正确
2. 尝试使用 `folder` 算法而不是 `osudb`
3. 检查 osu! 数据库是否完整
4. 尝试在 osu! 中按 F5 重建数据库

```bash
# 尝试用 folder 模式

osynic-sl -t songs -a folder -p "C:\path\to\osu!"
```

## 📊 输出示例


### Songs 格式输出

```json
[
  {
    "song_id": 1985060,
    "artist_name": "Artist Name",
    "mapper_name": "Mapper Name",
    "song_name": "Song Title",
    "no_video": false
  },
  {
    "song_id": 1997071,
    "artist_name": "Another Artist",
    "mapper_name": "Other Mapper",
    "song_name": "Another Song",
    "no_video": true
  }
]
```

### Sets 格式输出

```json
{
  "beatmapset_ids": [
    "114514",
    "1919810",
    "1538879"
  ]
}
```

## ✨ 新功能 vs 旧功能对比


| 功能         | 旧版本       | 新版本          |
| ------------ | ------------ | --------------- |
| 交互式提示   | ❌            | ✅               |
| 智能路径检测 | ❌            | ✅               |
| 默认参数     | 需要完整指定 | 智能提示        |
| 初学者友好度 | 低           | 高              |
| 脚本兼容性   | ✅            | ✅ （100% 兼容） |
| 键盘导航     | ❌            | ✅               |
| Emoji 反馈   | ❌            | ✅               |

## 🚀 快速参考


```bash
# 完全交互式

osynic-sl

# 交互式 + 指定 JSON 类型

osynic-sl -t songs
osynic-sl -t sets

# 完整命令（非交互，适合脚本）

osynic-sl -t songs -a osudb -p "C:\path\osu!" -o "./out"

# 帮助信息

osynic-sl --help

# 版本信息

osynic-sl --version
```

## 📞 获取帮助


1. 查看帮助：`osynic-sl --help`
2. 查看项目: https://github.com/osynicite/osynic_serializer
3. 查看文档: `README.md` 和 `INTERACTIVE_CLI_DEMO.md`

---

**祝你使用愉快！** 🎵

如果你喜欢这个工具，记得给项目 Star ⭐！