# biliup-next Cold Start Checklist

目标：在一台没有旧环境残留的新机器上，把 `biliup-next` 启动到“可配置、可 doctor、可进入控制面”的状态。

## 1. 基础环境

- 安装 `python3`
- 安装 `ffmpeg` 和 `ffprobe`
- 如需完整歌曲识别，安装 `codex`
- 如需完整上传链路，准备 `biliup` 可执行文件

## 2. 获取项目

```bash
git clone <your-repo> biliup
cd biliup/biliup-next
```

## 3. 一键初始化

```bash
bash setup.sh
```

初始化完成后，项目会自动生成：

- `config/settings.json`
- `config/settings.staged.json`
- `runtime/cookies.json`
- `runtime/upload_config.json`
- `data/workspace/*`

注意：

- 这些文件默认都是模板或占位内容
- 此时项目应当已经能执行 `doctor`，但不代表上传链路已经可用

## 4. 填写真实运行资产

- 编辑 `runtime/cookies.json`
- 编辑 `runtime/upload_config.json`
- 把 `biliup` 放到 `runtime/biliup`，或在 `settings.json` 里改成系统路径
- 填写 `transcribe.groq_api_key`
- 按机器实际情况调整 `song_detect.codex_cmd`
- 按需要填写 `collection.season_id_a` / `collection.season_id_b`

## 5. 验收

```bash
./.venv/bin/biliup-next doctor
./.venv/bin/biliup-next init-workspace
./.venv/bin/biliup-next serve --host 127.0.0.1 --port 8787
bash cold-start-smoke.sh
```

浏览器打开：

```text
http://127.0.0.1:8787/
```

验收通过标准：

- `doctor` 输出可读，缺失项只剩你尚未填写的外部依赖
- 控制面可以打开
- `Settings` 页可正常保存
- `stage` 目录可导入或上传文件
- `cold-start-smoke.sh` 能完整通过

## 6. 完整链路前检查

在开始真实处理前，确认以下项目已经真实可用：

- `runtime/cookies.json`
- `runtime/upload_config.json`
- `publish.biliup_path`
- `song_detect.codex_cmd`
- `transcribe.groq_api_key`
- `collection.season_id_a` / `collection.season_id_b`