feat: professionalize control plane and standalone delivery

docs/cold-start-checklist.md

@@ -0,0 +1,79 @@
+# 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`