feat: professionalize control plane and standalone delivery

2026-04-07 10:46:30 +08:00
parent d0cf1fd0df
commit 862db502b0
100 changed files with 8313 additions and 1483 deletions
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@ -129,6 +129,12 @@ paths:
      responses:
        "201":
          description: task created
+  /webhooks/full-video-uploaded:
+    post:
+      summary: 接收原视频上传成功后的完整版 BV webhook
+      responses:
+        "202":
+          description: accepted
  /tasks/{taskId}:
    get:
      summary: 查询任务详情
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -166,14 +166,18 @@ biliup-next/

 ```text
 created
-  -> ingested
+  -> running
  -> transcribed
+  -> running
  -> songs_detected
+  -> running
  -> split_done
+  -> running
  -> published
+  -> running
  -> commented
+  -> running
  -> collection_synced
-  -> completed
 ```

 失败状态不结束任务，而是转入：
@ -194,5 +198,6 @@ created
 - 外部依赖不可直接在业务模块中调用 shell 或 HTTP
 - 配置统一由 `core.config` 读取
 - 管理端展示的数据优先来自数据库，不直接从日志推断
+- 工作区 flag 只表达交付副作用和产物标记，不作为 task 主状态事实源
 - 配置系统必须 schema-first
 - 插件系统必须 manifest-first
--- a/docs/cold-start-checklist.md
+++ b/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`
--- a/docs/design-principles.md
+++ b/docs/design-principles.md
@ -169,6 +169,11 @@ manifest 负责描述：

 三者职责分离，不互相替代。

+补充：
+
+- 工作区 flag 可以保留，用于表示某些外部动作已经发生，例如评论、合集、上传等副作用完成。
+- 但这些 flag 不应被提升为 task 主状态本身。
+
 ## Principle 9: Replaceability With Stable Core

 可替换的是 provider，不可随意漂移的是核心模型。
--- a/docs/frontend-implementation-checklist.md
+++ b/docs/frontend-implementation-checklist.md
@ -0,0 +1,335 @@
+# Frontend Implementation Checklist
+
+## Goal
+
+把当前 `biliup-next` 已有的后端能力，整理成前端可直接开发的任务清单。
+
+这份清单面向前端开发，不讨论后端架构，只回答 3 个问题：
+
+1. 先做哪些页面最值钱
+2. 每个页面要拆哪些组件
+3. 每个组件依赖哪些接口和字段
+
+## Priority
+
+建议按这个顺序推进：
+
+1. 任务列表页状态升级
+2. 任务详情页
+3. 手工绑定完整版 BV
+4. Session 合并 / 重绑
+5. 设置页常用配置强化
+
+## Milestone 1: 任务列表页状态升级
+
+目标：
+
+- 用户一眼看懂任务是在运行、等待、失败还是完成
+- 不需要理解内部状态机字段
+
+### 页面任务
+
+- 把当前任务列表中的内部状态替换成用户态状态
+- 在任务列表中增加“当前步骤”列
+- 在任务列表中增加“下次重试时间”列
+- 在任务列表中增加“分P BV / 完整版 BV”列
+- 在任务列表中增加“评论 / 合集 / 清理”状态列
+
+### 组件任务
+
+- `TaskStatusBadge`
+  - 输入：`task.status`, `task.retry_state`, `steps`
+  - 输出：`已接收 / 上传中 / 等待B站可见 / 需人工处理 / 已完成`
+- `TaskStepBadge`
+  - 输入：`steps`
+  - 输出当前步骤文案
+- `TaskDeliverySummary`
+  - 输入：`delivery_state`, `session_context`
+  - 输出：
+    - 分P BV
+    - 完整版 BV
+    - 评论状态
+    - 合集状态
+    - 清理状态
+
+### 接口依赖
+
+- `GET /tasks`
+
+### 建议后端字段
+
+- 现有可直接使用：
+  - `status`
+  - `retry_state`
+  - `delivery_state`
+  - `session_context`
+- 建议前端先本地派生：
+  - `display_status`
+  - `current_step`
+
+## Milestone 2: 任务详情页
+
+目标：
+
+- 用户不看日志也能知道这个任务发生了什么
+- 用户能在单任务页完成最常见修复动作
+
+### 页面任务
+
+- 新建任务详情页 Hero 区
+- 新建步骤时间线
+- 新建交付结果卡片
+- 新建 Session 信息卡片
+- 新建产物列表卡片
+- 新建历史动作卡片
+- 新建错误说明卡片
+
+### 组件任务
+
+- `TaskHero`
+  - 标题
+  - 用户态状态
+  - 当前步骤
+  - 下次重试时间
+- `TaskTimeline`
+  - ingest -> collection_b 全步骤
+- `TaskDeliveryPanel`
+  - 分P `BV`
+  - 完整版 `BV`
+  - 分P链接
+  - 完整版链接
+  - 合集状态
+- `TaskSessionPanel`
+  - `session_key`
+  - `streamer`
+  - `room_id`
+  - `segment_started_at`
+  - `segment_duration_seconds`
+  - `context_source`
+- `TaskArtifactsPanel`
+  - source_video
+  - subtitle_srt
+  - songs.json
+  - songs.txt
+  - clip_video
+- `TaskActionsPanel`
+  - 运行
+  - 重试
+  - 重置
+  - 绑定完整版 BV
+
+### 接口依赖
+
+- `GET /tasks/<id>`
+- `GET /tasks/<id>/steps`
+- `GET /tasks/<id>/artifacts`
+- `GET /tasks/<id>/history`
+- `GET /tasks/<id>/timeline`
+- `GET /tasks/<id>/context`
+
+### 操作接口依赖
+
+- `POST /tasks/<id>/actions/run`
+- `POST /tasks/<id>/actions/retry-step`
+- `POST /tasks/<id>/actions/reset-to-step`
+
+## Milestone 3: 手工绑定完整版 BV
+
+目标：
+
+- 用户在前端直接补 `full_video_bvid`
+- 不需要再手工写 `full_video_bvid.txt`
+
+### 页面任务
+
+- 在任务详情页增加“绑定完整版 BV”表单
+- 显示当前已绑定 BV
+- 显示绑定来源：
+  - fallback
+  - task_context
+  - meta_sidecar
+  - webhook
+
+### 组件任务
+
+- `BindFullVideoForm`
+  - 输入框：`BV...`
+  - 提交按钮
+  - 成功反馈
+  - 错误反馈
+
+### 接口依赖
+
+- `POST /tasks/<id>/bind-full-video`
+
+### 交互要求
+
+- 提交前本地校验 `BV[0-9A-Za-z]+`
+- 成功后刷新：
+  - `GET /tasks/<id>`
+  - `GET /tasks/<id>/context`
+
+## Milestone 4: Session 合并 / 重绑
+
+目标：
+
+- 用户能处理“同一场多个断流片段”
+- 用户能统一给整个 session 重绑完整版 BV
+
+### 页面任务
+
+- 在任务详情页显示当前任务所属 session
+- 增加“查看同 session 任务”入口
+- 增加“合并到现有 session”弹窗
+- 增加“整个 session 重绑完整版 BV”表单
+
+### 组件任务
+
+- `SessionSummaryCard`
+  - `session_key`
+  - task count
+  - 当前 `full_video_bvid`
+- `SessionTaskList`
+  - 列出该 session 下所有任务
+- `MergeSessionDialog`
+  - 输入目标 `session_key`
+  - 选择任务
+- `RebindSessionForm`
+  - 输入新的完整版 `BV`
+
+### 接口依赖
+
+- `GET /sessions/<session_key>`
+- `POST /sessions/<session_key>/merge`
+- `POST /sessions/<session_key>/rebind`
+
+### 交互要求
+
+- 合并成功后刷新：
+  - 当前任务详情
+  - session 详情
+  - 任务列表
+- 如果目标 session 已有 `full_video_bvid`
+  - 前端提示“合并后会继承该完整版 BV”
+
+## Milestone 5: 设置页常用配置强化
+
+目标：
+
+- 用户无需直接改 JSON 就能调优常用行为
+
+### 页面任务
+
+- 在设置页高亮常用 ingest/session 配置
+- 在设置页高亮 comment 重试配置
+- 在设置页高亮 cleanup 配置
+
+### 应优先暴露的配置
+
+- `ingest.session_gap_minutes`
+- `ingest.meta_sidecar_enabled`
+- `ingest.meta_sidecar_suffix`
+- `comment.max_retries`
+- `comment.base_delay_seconds`
+- `cleanup.delete_source_video_after_collection_synced`
+- `cleanup.delete_split_videos_after_collection_synced`
+
+### 接口依赖
+
+- `GET /settings`
+- `GET /settings/schema`
+- `PUT /settings`
+
+## Common UX Rules
+
+### 状态文案
+
+- `failed_retryable` 不显示“失败”
+- 优先显示：
+  - `等待自动重试`
+  - `等待B站可见`
+  - `正在处理中`
+  - `需人工处理`
+
+### 错误提示
+
+错误提示统一分成 2 行：
+
+- 原因
+- 建议动作
+
+例如：
+
+- 原因：视频刚上传，B站暂未可见
+- 建议：系统会自动重试，无需人工处理
+
+### 操作反馈
+
+所有写操作都要有：
+
+- loading 态
+- 成功 toast
+- 错误 toast
+
+### 刷新策略
+
+这些动作成功后必须自动刷新详情数据：
+
+- `retry-step`
+- `reset-to-step`
+- `bind-full-video`
+- `session merge`
+- `session rebind`
+
+## Suggested Frontend Types
+
+建议前端统一定义这些类型：
+
+```ts
+type TaskDisplayStatus =
+  | "accepted"
+  | "processing"
+  | "waiting_retry"
+  | "waiting_visibility"
+  | "manual_action"
+  | "done";
+
+type TaskSessionContext = {
+  task_id: string;
+  session_key: string | null;
+  streamer: string | null;
+  room_id: string | null;
+  source_title: string | null;
+  segment_started_at: string | null;
+  segment_duration_seconds: number | null;
+  full_video_bvid: string | null;
+  split_bvid: string | null;
+  context_source: string;
+  video_links: {
+    split_video_url: string | null;
+    full_video_url: string | null;
+  };
+};
+```
+
+## Suggested Build Order Inside Frontend Repo
+
+建议按这个顺序拆 PR：
+
+1. 状态映射工具函数
+2. 任务列表页文案升级
+3. 任务详情页 Session/Delivery 面板
+4. 绑定完整版 BV 表单
+5. Session 合并 / 重绑弹窗
+6. 设置页常用配置高亮
+
+## Definition Of Done
+
+这一轮前端完成的标准建议是：
+
+- 用户可以在任务列表页看懂所有任务当前状态
+- 用户可以在任务详情页看到分P/完整版 BV 和链接
+- 用户可以手工绑定完整版 BV
+- 用户可以把多个任务合并为同一个 session
+- 用户可以给整个 session 重绑完整版 BV
+- 用户不需要 ssh 登录机器改 txt 文件
--- a/docs/frontend-product-integration.md
+++ b/docs/frontend-product-integration.md
@ -0,0 +1,383 @@
+# Frontend Product Integration
+
+## Goal
+
+从用户视角，把当前 `biliup-next` 的任务状态机包装成可操作、可理解的控制面。
+
+这份文档面向前端与后端联调，目标不是描述内部实现，而是明确：
+
+- 前端应该有哪些页面
+- 每个页面需要哪些字段
+- 当前后端已经提供了哪些接口
+- 哪些字段/接口还需要补
+
+## User Goals
+
+用户最关心的不是数据库状态，而是这 6 件事：
+
+1. 视频有没有被接收
+2. 现在卡在哪一步
+3. 这是自动等待还是需要人工处理
+4. 上传后的分P BV 和完整版 BV 是什么
+5. 评论和合集有没有完成
+6. 失败后应该点哪里恢复
+
+因此，前端不应该直接暴露 `created/transcribed/failed_retryable` 这类内部状态，而应该提供一层用户可理解的派生展示。
+
+## Information Architecture
+
+建议前端固定成 4 个一级页面：
+
+1. 总览页
+2. 任务列表页
+3. 任务详情页
+4. 设置页
+
+可选扩展页：
+
+5. 日志页
+6. Webhook / Sidecar 调试页
+
+## Page Spec
+
+### 1. 总览页
+
+目标：让用户在 10 秒内知道系统是否正常、当前队列是否卡住。
+
+核心模块：
+
+- 任务摘要卡片
+  - 运行中
+  - 等待自动重试
+  - 需人工处理
+  - 已完成
+- 最近 10 个任务
+  - 标题
+  - 用户态状态
+  - 当前步骤
+  - 下次重试时间
+- 运行时摘要
+  - API 服务状态
+  - Worker 服务状态
+  - stage 目录文件数
+  - 最近一次调度结果
+- 风险提示
+  - cookies 缺失
+  - 磁盘空间不足
+  - Groq/Codex/Biliup 不可用
+
+现有接口可复用：
+
+- `GET /health`
+- `GET /doctor`
+- `GET /tasks?limit=100`
+- `GET /runtime/services`
+- `GET /scheduler`
+
+### 2. 任务列表页
+
+目标：批量查看任务，快速定位失败或等待中的任务。
+
+表格建议字段：
+
+- 任务标题
+- 用户态状态
+- 当前步骤
+- 完成进度
+- 下次重试时间
+- 分P BV
+- 完整版 BV
+- 评论状态
+- 合集状态
+- 清理状态
+- 最近更新时间
+
+筛选项建议：
+
+- 全部
+- 运行中
+- 等待自动重试
+- 需人工处理
+- 已完成
+- 仅显示未完成评论
+- 仅显示未完成合集
+- 仅显示未清理文件
+
+现有接口可复用：
+
+- `GET /tasks`
+
+建议新增的派生字段：
+
+- `display_status`
+- `current_step`
+- `progress_percent`
+- `split_bvid`
+- `full_video_bvid`
+- `session_key`
+- `session_binding_state`
+
+### 3. 任务详情页
+
+目标：让用户不看日志也能处理单个任务。
+
+建议布局：
+
+- Hero 区
+  - 标题
+  - 用户态状态
+  - 当前步骤
+  - 下次重试时间
+  - 主要操作按钮
+- 步骤时间线
+  - ingest
+  - transcribe
+  - song_detect
+  - split
+  - publish
+  - comment
+  - collection_a
+  - collection_b
+- 交付结果区
+  - 分P BV
+  - 完整版 BV
+  - 分P 链接
+  - 完整版链接
+  - 合集 A / B 链接
+- Session 信息区
+  - session_key
+  - streamer
+  - room_id
+  - segment_started_at
+  - segment_duration_seconds
+  - 是否由 sidecar 提供
+  - 是否由时间连续性自动归并
+- 文件与产物区
+  - source_video
+  - subtitle_srt
+  - songs.json
+  - songs.txt
+  - clip_video
+- 历史动作区
+  - run
+  - retry-step
+  - reset-to-step
+- 错误与建议区
+  - 错误码
+  - 错误摘要
+  - 系统建议动作
+
+现有接口可复用：
+
+- `GET /tasks/<id>`
+- `GET /tasks/<id>/steps`
+- `GET /tasks/<id>/artifacts`
+- `GET /tasks/<id>/history`
+- `GET /tasks/<id>/timeline`
+- `POST /tasks/<id>/actions/run`
+- `POST /tasks/<id>/actions/retry-step`
+- `POST /tasks/<id>/actions/reset-to-step`
+
+建议新增接口：
+
+- `GET /tasks/<id>/context`
+
+### 4. 设置页
+
+目标：把常用配置变成可理解、可搜索、可修改的产品设置，而不是裸 JSON。
+
+优先展示的用户级配置：
+
+- `ingest.session_gap_minutes`
+- `ingest.meta_sidecar_enabled`
+- `ingest.meta_sidecar_suffix`
+- `comment.max_retries`
+- `comment.base_delay_seconds`
+- `cleanup.delete_source_video_after_collection_synced`
+- `cleanup.delete_split_videos_after_collection_synced`
+- `collection.season_id_a`
+- `collection.season_id_b`
+
+现有接口可复用：
+
+- `GET /settings`
+- `GET /settings/schema`
+- `PUT /settings`
+
+## User-Facing Status Mapping
+
+前端必须提供一层用户态状态，不要直接显示内部状态。
+
+建议映射：
+
+- `created` -> `已接收`
+- `transcribed` -> `已转录`
+- `songs_detected` -> `已识歌`
+- `split_done` -> `已切片`
+- `published` -> `已上传`
+- `commented` -> `评论完成`
+- `collection_synced` -> `已完成`
+- `failed_retryable` + `step=comment` -> `等待B站可见`
+- `failed_retryable` 其他 -> `等待自动重试`
+- `failed_manual` -> `需人工处理`
+- 任一步 `running` -> `<步骤名>处理中`
+
+建议步骤名展示：
+
+- `ingest` -> `接收视频`
+- `transcribe` -> `转录字幕`
+- `song_detect` -> `识别歌曲`
+- `split` -> `切分分P`
+- `publish` -> `上传分P`
+- `comment` -> `发布评论`
+- `collection_a` -> `加入完整版合集`
+- `collection_b` -> `加入分P合集`
+
+## API Integration
+
+### Existing APIs That Frontend Should Reuse
+
+- `GET /tasks`
+- `GET /tasks/<id>`
+- `GET /tasks/<id>/steps`
+- `GET /tasks/<id>/artifacts`
+- `GET /tasks/<id>/history`
+- `GET /tasks/<id>/timeline`
+- `POST /tasks/<id>/actions/run`
+- `POST /tasks/<id>/actions/retry-step`
+- `POST /tasks/<id>/actions/reset-to-step`
+- `GET /settings`
+- `GET /settings/schema`
+- `PUT /settings`
+- `GET /runtime/services`
+- `POST /runtime/services/<service>/<action>`
+- `POST /worker/run-once`
+
+### Recommended New APIs
+
+#### `GET /tasks/<id>/context`
+
+用途：给任务详情页和 session 归并 UI 提供上下文。
+
+返回建议：
+
+```json
+{
+  "task_id": "xxx",
+  "session_key": "王海颖:20260402T2203",
+  "streamer": "王海颖",
+  "room_id": "581192190066",
+  "source_title": "王海颖唱歌录播 04月02日 22时03分",
+  "segment_started_at": "2026-04-02T22:03:00+08:00",
+  "segment_duration_seconds": 4076.443,
+  "full_video_bvid": "BV1uH9wBsELC",
+  "binding_source": "meta_sidecar"
+}
+```
+
+#### `POST /tasks/<id>/bind-full-video`
+
+用途：用户在前端手工补绑完整版 BV。
+
+请求：
+
+```json
+{
+  "full_video_bvid": "BV1uH9wBsELC"
+}
+```
+
+#### `POST /sessions/<session_key>/merge`
+
+用途：把多个任务手工归并到同一个 session。
+
+请求：
+
+```json
+{
+  "task_ids": ["why-2205", "why-2306"]
+}
+```
+
+#### `POST /sessions/<session_key>/rebind`
+
+用途：修改 session 级完整版 BV。
+
+请求：
+
+```json
+{
+  "full_video_bvid": "BV1uH9wBsELC"
+}
+```
+
+## Derived Fields For UI
+
+后端最好直接给前端这些派生字段，减少前端自行拼状态：
+
+- `display_status`
+- `display_step`
+- `progress_percent`
+- `split_bvid`
+- `full_video_bvid`
+- `video_links`
+- `delivery_state`
+- `retry_state`
+- `session_context`
+- `actions_available`
+
+其中 `actions_available` 建议返回：
+
+```json
+{
+  "run": true,
+  "retry_step": true,
+  "reset_to_step": true,
+  "bind_full_video": true,
+  "merge_session": true
+}
+```
+
+## Delivery State Contract
+
+任务列表和详情页都依赖统一的交付状态模型。
+
+建议结构：
+
+```json
+{
+  "split_bvid": "BV1GoDPBtEUg",
+  "full_video_bvid": "BV1uH9wBsELC",
+  "split_video_url": "https://www.bilibili.com/video/BV1GoDPBtEUg",
+  "full_video_url": "https://www.bilibili.com/video/BV1uH9wBsELC",
+  "comment_split_done": false,
+  "comment_full_done": false,
+  "collection_a_done": false,
+  "collection_b_done": false,
+  "source_video_present": true,
+  "split_videos_present": true
+}
+```
+
+## Suggested Frontend Build Order
+
+按实际价值排序：
+
+1. 任务列表页状态文案升级
+2. 任务详情页增加交付结果和重试说明
+3. 详情页增加 session/context 区块
+4. 设置页增加 session 归并相关配置
+5. 增加“手工绑定完整版 BV”操作
+6. 增加“合并 session”操作
+
+## MVP Scope
+
+如果只做一轮最小交付，建议先完成：
+
+- 用户态状态映射
+- 单任务详情页
+- `GET /tasks/<id>/context`
+- 手工绑定 `full_video_bvid`
+- 前端重试/重置按钮统一化
+
+这样即使 webhook 和自动 session 归并后面再完善，用户也已经能在前端完整处理问题。
--- a/docs/professionalization-roadmap-2026-04-06.md
+++ b/docs/professionalization-roadmap-2026-04-06.md
@ -0,0 +1,178 @@
+# biliup-next Professionalization Roadmap - 2026-04-06
+
+## 目标
+
+把 `biliup-next` 从“方向正确的重构工程”推进到“边界清晰、契约稳定、可持续演进的专业级本地控制面系统”。
+
+本路线图以当前仓库中已经明确吸收的 OpenClaw 设计哲学为参照：
+
+- modular monolith
+- control-plane first
+- schema-first
+- manifest-first
+- registry over direct coupling
+- single source of truth
+
+重点不是重复这些口号，而是把它们继续落实到真实代码和工程制度中。
+
+## 维度一：平台边界
+
+### 当前差距
+
+- provider 内仍大量直接调用 `subprocess` 和 `requests`
+- adapter / provider / module service 的边界还不够硬
+- 外部依赖的超时、重试、错误翻译和观测没有统一制度
+
+### 目标状态
+
+- 外部命令和外部 HTTP 都通过稳定 adapter 层进入系统
+- provider 只消费标准化 adapter 能力和统一错误语义
+- 超时、重试、限流、日志和诊断在 adapter 层具备统一约束
+
+### 改进事项
+
+- 为 `ffmpeg`、`codex`、`biliup`、Bili API、Groq 定义统一 adapter 接口
+- 将 provider 中的直接 `subprocess.run()` 和 `requests` 逐步下沉到 adapter
+- 统一 adapter 错误模型，减少 provider 自己拼接临时错误码
+- 为 adapter 增加可观测上下文，例如 command name、target、duration、attempt
+
+### 完成标志
+
+- 业务模块不再直接拼 shell/http 调用
+- adapter 成为唯一外部依赖入口
+
+## 维度二：领域模型
+
+### 当前差距
+
+- 核心规则分散在 `task_engine`、`task_policies`、`task_actions`、provider 和部分工作区文件
+- 文档已有 domain model，但还没有形成更稳定的应用服务/领域服务边界
+- `task`、`session`、`full_video_bvid` 这类跨模块关系仍有隐式规则
+
+### 目标状态
+
+- task lifecycle、retry policy、session binding、delivery side effects 都有清晰归属
+- 领域规则主要存在于少数稳定模块，而不是散落在控制器和 provider 中
+- “谁负责写什么状态”有明确制度
+
+### 改进事项
+
+- 明确 `Task`、`TaskContext`、`SessionBinding` 的边界和 ownership
+- 把 `full_video_bvid`、session 归并、评论/合集副作用收敛成独立领域服务
+- 评估是否引入显式 domain event 或最小事件记录层
+- 为状态迁移建立更显式的 transition table 或 policy object
+
+### 完成标志
+
+- 关键规则不再分散在多个入口函数中重复实现
+- task/session/delivery 的事实源和写入职责稳定
+
+## 维度三：接口契约
+
+### 当前差距
+
+- API handler 仍承担较多 payload 组装和视图拼接工作
+- OpenAPI 与真实控制面细节还不够同步
+- 内部领域模型与外部 API 视图没有充分分层
+
+### 目标状态
+
+- API 对外暴露稳定 DTO，而不是直接拼内部模型
+- handler 更薄，组装逻辑集中在 service / presenter / serializer 层
+- 契约变更可追踪、可校验
+
+### 改进事项
+
+- 为 task detail、task list、session detail、timeline 建立稳定 serializer
+- 清理 API handler 中的重复组装逻辑
+- 更新 `docs/api/openapi.yaml`，让其覆盖真实控制面接口
+- 明确哪些字段属于内部实现细节，不直接暴露给前端
+
+### 完成标志
+
+- handler 只做路由、鉴权、输入解析和响应返回
+- API 文档与真实返回结构保持同步
+
+## 维度四：测试体系
+
+### 当前差距
+
+- 已有最小回归测试，但仍偏重纯逻辑
+- repository、API、provider 契约、端到端场景覆盖不足
+
+### 目标状态
+
+- 核心编排、存储、API、adapter 都有分层测试
+- 关键重构不需要依赖手工回归
+
+### 改进事项
+
+- 新增 repository 的 SQLite 集成测试
+- 为 API handler 增加最小接口行为测试
+- 为 adapter/provider 增加契约测试和失败场景测试
+- 保留现有纯逻辑 unittest，继续增加 smoke 回归脚本
+
+### 完成标志
+
+- 至少形成：
+  - 逻辑单元测试
+  - SQLite 集成测试
+  - API 行为测试
+  - smoke / regression 流程
+
+## 维度五：运维成熟度
+
+### 当前差距
+
+- 已有 doctor、logs、systemd 控制和 workspace 隔离
+- 但健康度、指标、审计、恢复机制还不够体系化
+
+### 目标状态
+
+- 控制面不仅能“看到状态”，还能帮助判断风险和恢复问题
+- 运行问题可以靠结构化信号而不是人工翻日志定位
+
+### 改进事项
+
+- 区分 health / readiness / degraded
+- 规范结构化日志字段
+- 为 task/step 增加最小指标视图
+- 完善审计事件分类
+- 明确数据库/配置变更/运行资产的迁移与回滚流程
+
+### 完成标志
+
+- 常见运行问题可以靠控制面和标准日志定位
+- 关键操作具备审计和回滚说明
+
+## 推荐优先顺序
+
+1. 平台边界
+2. 领域模型
+3. 接口契约
+4. 测试体系
+5. 运维成熟度
+
+## 下一批优先项
+
+### Priority A
+
+- 为 `biliup`、Bili API 和 `codex` 建立统一 adapter 边界
+- 把 `task_actions` 中与 session/delivery 相关的规则继续抽成稳定服务
+- 为 task list / task detail / session detail 提供 serializer 层
+
+### Priority B
+
+- 新增 repository SQLite 集成测试
+- 新增 API 行为测试
+- 更新 OpenAPI 契约
+
+### Priority C
+
+- 设计 health/readiness/degraded 模型
+- 规范日志和审计字段
+
+## 备注
+
+- 这份路线图描述的是“距离专业化还有哪些结构性工作”，不是说当前系统不可用。
+- 当前项目已经具备正确方向；接下来的重点是把设计哲学继续固化为代码边界、测试制度和运维约束。
--- a/docs/refactor-plan-2026-04-06.md
+++ b/docs/refactor-plan-2026-04-06.md
@ -0,0 +1,134 @@
+# biliup-next Refactor Plan - 2026-04-06
+
+## 目标
+
+围绕当前重构项目已暴露出的状态一致性、数据一致性、运行稳定性和控制面性能问题，分阶段推进改造，优先修复会影响真实运行结果的问题，再收敛模型和技术债。
+
+## 改造原则
+
+- 先修正单一事实源，再优化展示层。
+- 先修正状态机真实行为，再修正文档和 UI 映射。
+- 先处理运行稳定性，再处理性能和结构整理。
+- 每一阶段都要求有可验证的验收结果，避免只做“结构看起来更好”。
+
+## 阶段划分
+
+### Phase 1: 状态与事实源收敛
+
+目标：
+
+- 让 task 具备真实可用的 `running` 语义。
+- 让 `full_video_bvid` 只有一套权威写入路径。
+- 消除“数据库状态”和“工作区文件状态”互相覆盖的问题。
+
+任务：
+
+- 在 step 开始执行时同步更新 task 运行态。
+- 明确 task 完成后 task 状态如何从 `running` 返回业务态。
+- 统一 `bind/rebind/webhook/ingest` 对 `full_video_bvid` 的读写入口。
+- 明确 `task_contexts`、`session_bindings`、`full_video_bvid.txt` 的职责。
+
+验收标准：
+
+- 控制台能正确筛选和显示运行中的任务。
+- 手工绑定、session 重绑、webhook 注入后，新旧任务读取到相同 BV。
+- 不再出现新任务 ingest 继承旧 BV 的情况。
+
+### Phase 2: 运行稳定性加固
+
+目标：
+
+- 让 API 与 worker 并行运行时的 SQLite 行为可控。
+- 降低锁冲突、脏状态和半成功写入风险。
+
+任务：
+
+- 为 SQLite 连接增加 `busy_timeout`、`WAL`、`foreign_keys=ON`。
+- 检查高频 repo 写入点，减少不必要的小事务。
+- 梳理关键写路径是否需要合并成原子操作。
+
+验收标准：
+
+- API 和 worker 并行运行时，不再轻易触发数据库锁错误。
+- 关键任务状态写入具备基本原子性，不出现“步骤更新了、任务没更新”一类半状态。
+
+### Phase 3: 控制面装配与查询优化
+
+目标：
+
+- 去掉 API 请求路径上的重复初始化。
+- 解决 `/tasks` 列表的全量扫描和 N+1 查询问题。
+
+任务：
+
+- 将 `ensure_initialized()` 从“每次请求即装配”改为更稳定的应用级初始化方式。
+- 收敛 provider/registry 生命周期，避免每次请求重复扫描 manifest 和实例化 provider。
+- 优化任务列表接口，把可下推的过滤逻辑下推到 repository 或持久化层。
+- 减少列表查询时对工作区文件的逐条读取。
+
+验收标准：
+
+- 常规 API 请求不再重复做全量装配。
+- 大量任务下的列表页和筛选页响应明显改善。
+
+### Phase 4: 状态机与文档对齐
+
+目标：
+
+- 让文档状态机、代码状态机、控制面展示口径一致。
+
+任务：
+
+- 决定是否保留 `ingested`、`completed`、`cancelled`。
+- 明确 flag 文件在系统中的角色。
+- 如果数据库是任务状态唯一来源，则把 delivery flag 降级为产物或外部副作用标记。
+- 更新状态机文档、控制面展示文案和开发约束。
+
+验收标准：
+
+- 文档中的状态集合与代码中的状态集合一致。
+- UI 不再依赖不存在或含义不稳定的 task 状态。
+
+### Phase 5: 回归测试与维护收尾
+
+目标：
+
+- 为核心编排逻辑补回归保护。
+- 降低后续重构再次引入状态漂移的概率。
+
+任务：
+
+- 新增 `tests/`。
+- 优先覆盖：
+  - `task_engine`
+  - `task_policies`
+  - `task_actions`
+  - `retry_meta`
+  - `task_reset`
+- 决定 classic 控制台的保留策略。
+
+验收标准：
+
+- 核心状态流转具备最小自动化回归覆盖。
+- 控制台维护策略明确，不再长期双线漂移。
+
+## 推荐执行顺序
+
+1. Phase 1
+2. Phase 2
+3. Phase 3
+4. Phase 4
+5. Phase 5
+
+## 本轮起步范围
+
+本轮先从以下子项开始：
+
+- Phase 1.1: task `running` 状态落地
+- Phase 1.2: `full_video_bvid` 写路径统一
+- Phase 2.1: SQLite 连接配置加固
+
+## 过程记录
+
+- 2026-04-06：完成代码审查，确认当前优先问题集中在 task 运行态缺失、`full_video_bvid` 多源不一致、SQLite 并发配置不足、重复初始化、列表查询 N+1、状态机文档与实现漂移、测试缺失。
+- 2026-04-06：将问题整理为本改造计划，按阶段拆分，并确定先做状态一致性与运行稳定性。
--- a/docs/state-machine.md
+++ b/docs/state-machine.md
@ -2,7 +2,7 @@

 ## Goal

-定义 `biliup-next` 的任务状态机，取代旧系统依赖 flag 文件、日志和目录结构推断状态的方式。
+定义 `biliup-next` 当前实现使用的任务状态机，并明确数据库状态与工作区 flag 的职责边界。

 状态机目标：

@ -23,14 +23,13 @@
 ### Core Statuses

 - `created`
- `ingested`
+- `running`
 - `transcribed`
 - `songs_detected`
 - `split_done`
 - `published`
 - `commented`
 - `collection_synced`
- `completed`

 ### Failure Statuses

@ -39,8 +38,7 @@

 ### Terminal Statuses

- `completed`
- `cancelled`
+- `collection_synced`
 - `failed_manual`

 ## Step Status
@ -117,16 +115,26 @@

 ```text
 created
-  -> ingested
+  -> running
  -> transcribed
+  -> running
  -> songs_detected
+  -> running
  -> split_done
+  -> running
  -> published
+  -> running
  -> commented
+  -> running
  -> collection_synced
-  -> completed
 ```

+说明：
+
+- `running` 是任务级瞬时状态，表示当前已有某个 step 被 claim 并正在执行。
+- 当该 step 成功结束后，task 会回到对应业务状态，例如 `transcribed`、`split_done`、`published`。
+- 当前实现中未使用 `ingested`、`completed`、`cancelled` 作为 task 状态。
+
 ### Failure Transition

 任何步骤失败后：
@ -158,10 +166,10 @@ created
 - `collection_a` 可作为独立步骤存在
 - 任务整体完成不必强依赖 `collection_a` 成功

-建议：
+当前实现：

- `completed` 表示主链路完成
- `collection_synced` 表示所有合集同步完成
+- `collection_synced` 表示当前任务已经完成既定收尾流程。
+- `collection_a` / `collection_b` 仍作为独立 step 存在，但系统暂未额外引入 `completed` 状态。

 ## Retry Strategy

@ -196,6 +204,27 @@ created
 - 错误信息
 - 重试次数

+## Flags And Files
+
+工作区中的 flag 文件仍然存在，但它们不是 task 主状态的权威来源。
+
+当前职责划分：
+
+- 数据库：
+  - task 状态
+  - step 状态
+  - 重试信息
+  - 结构化上下文
+- 工作区文件与 flag：
+  - 外部副作用是否已执行
+  - 产物是否已落地
+  - 评论/合集等交付标记
+
+换句话说：
+
+- “任务现在处于什么状态”以数据库为准。
+- “某个外部动作是否已经做过”可以由工作区 flag 辅助表达。
+
 ## UI Expectations

 UI 至少需要直接展示：
@ -209,4 +238,4 @@ UI 至少需要直接展示：
 ## Non-Goals

 - 不追求一个任务多个步骤完全并发执行
- 不允许继续依赖 flag 文件作为权威状态来源
+- 不把工作区 flag 文件当作 task 主状态来源
--- a/docs/todo-2026-04-06.md
+++ b/docs/todo-2026-04-06.md
@ -0,0 +1,196 @@
+# biliup-next Todo - 2026-04-06
+
+## 今日待办
+
+### P0
+
+- 修正任务级 `running` 状态缺失问题。
+  - 当前 step 会进入 `running`，但 task 不会进入 `running`，导致控制台“处理中”筛选、优先级判断和注意力状态失真。
+  - 相关位置：
+    - `src/biliup_next/app/task_engine.py`
+    - `src/biliup_next/app/api_server.py`
+    - `src/biliup_next/modules/*/service.py`
+
+- 收敛 `full_video_bvid` 的单一事实源。
+  - 当前 `task_contexts`、`session_bindings`、`session/full_video_bvid.txt` 三处状态可能不一致。
+  - `rebind_session_full_video_action()` 没有同步更新 `session_bindings`，后续新任务 ingest 仍可能继承旧 BV。
+  - 相关位置：
+    - `src/biliup_next/app/task_actions.py`
+    - `src/biliup_next/modules/ingest/service.py`
+    - `src/biliup_next/infra/task_repository.py`
+
+- 补强 SQLite 并发配置。
+  - 当前 API 与 worker 可并行运行，但数据库连接仍是最基础配置，缺少 `busy_timeout`、`WAL`、`foreign_keys=ON` 等保护。
+  - 后续任务量或并发操作增加时，容易出现 `database is locked` 一类问题。
+  - 相关位置：
+    - `src/biliup_next/infra/db.py`
+
+### P1
+
+- 消除 API 路径上的重复初始化。
+  - `ensure_initialized()` 目前会重复执行配置加载、DB 初始化、插件扫描和 provider 实例化。
+  - API 每次请求都可能再次触发整套装配，后续会拖慢控制面并增加维护成本。
+  - 相关位置：
+    - `src/biliup_next/app/bootstrap.py`
+    - `src/biliup_next/app/api_server.py`
+
+- 优化 `/tasks` 的全量扫描和 N+1 查询。
+  - 当前 `attention/delivery` 过滤会先拉最多 5000 条任务，再逐条补 task payload、step、context 和文件系统状态。
+  - 任务规模上来后会明显拖慢列表页和筛选体验。
+  - 相关位置：
+    - `src/biliup_next/app/api_server.py`
+    - `src/biliup_next/infra/task_repository.py`
+
+- 收敛文档状态机与代码实现。
+  - 文档中存在 `ingested`、`completed`、`cancelled`，并声明不再依赖 flag 文件作为权威状态。
+  - 实际实现中这些状态并未完整落地，评论/合集完成态仍依赖多个 flag 文件。
+  - 需要统一“文档模型”和“代码真实状态机”，避免后续继续漂移。
+  - 相关位置：
+    - `docs/state-machine.md`
+    - `src/biliup_next/app/api_server.py`
+    - `src/biliup_next/modules/comment/providers/bilibili_top_comment.py`
+    - `src/biliup_next/modules/collection/providers/bilibili_collection.py`
+
+### P2
+
+- 为状态机、重试和手工干预流程补测试。
+  - 当前仓库没有看到 `tests/` 或自动化回归覆盖。
+  - 优先覆盖：
+    - `task_engine`
+    - `task_policies`
+    - `task_actions`
+    - `retry_meta`
+    - `task_reset`
+
+- 明确两套控制台的维护策略。
+  - 当前 React 控制台和 classic 控制台并存。
+  - 需要决定 classic 是长期保留、冻结维护，还是逐步退役。
+
+## 备注
+
+- 以上问题来自 2026-04-06 对 `biliup-next` 当前重构实现的代码审查。
+- 优先顺序按“状态一致性 / 数据一致性 / 运行稳定性 / 控制面性能 / 可维护性”排列。
+
+## 过程记录
+
+- 2026-04-06：完成首轮代码审查，确认当前优先问题。
+- 2026-04-06：基于问题清单拆出分阶段改造计划，见 `docs/refactor-plan-2026-04-06.md`。
+- 2026-04-06：确定首批执行范围为 task `running` 状态落地、`full_video_bvid` 写路径统一、SQLite 连接加固。
+- 2026-04-06：已完成首轮代码改造。
+  - task 在 step 被 claim 后会进入 `running`。
+  - `bind/rebind/webhook` 已统一复用 `full_video_bvid` 持久化路径。
+  - SQLite 连接已增加 `foreign_keys`、`busy_timeout`、`WAL`、`synchronous=NORMAL`。
+  - 已执行 `python -m compileall biliup-next/src/biliup_next` 验证语法通过。
+- 2026-04-06：已完成第二轮控制面改造。
+  - `ensure_initialized()` 已改为进程内复用，避免 API 请求重复装配全套应用状态。
+  - `PUT /settings` 后会主动失效并重建缓存状态，避免新旧配置混用。
+  - `/tasks` 列表已改为批量预取 task context 和 steps，减少列表页 N+1 查询。
+  - 已再次执行 `python -m compileall biliup-next/src/biliup_next` 验证语法通过。
+- 2026-04-06：已完成状态机文档对齐。
+  - `state-machine.md` 与 `architecture.md` 已改成当前代码真实状态集合：`created/running/transcribed/songs_detected/split_done/published/commented/collection_synced/failed_*`。
+  - 已明确 `ingested/completed/cancelled` 当前未落地，不再作为现阶段实现口径。
+  - 已明确工作区 flag 仅表示交付副作用和产物标记，不作为 task 主状态事实源。
+- 2026-04-06：已补最小回归测试集。
+  - 新增 `tests/test_task_engine.py`
+  - 新增 `tests/test_retry_meta.py`
+  - 新增 `tests/test_task_actions.py`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 7 个测试全部通过。
+- 2026-04-06：已继续收口 `task_actions` 的写路径。
+  - `rebind_session_full_video_action()` 不再重复 upsert session binding。
+  - `merge_session_action()` 在继承 `full_video_bvid` 时已复用统一持久化路径。
+  - 已补对应测试，当前测试数为 8，全部通过。
+- 2026-04-06：已补第二层状态流转测试。
+  - 新增 `tests/test_task_policies.py`
+  - 新增 `tests/test_task_runner.py`
+  - 已覆盖 disabled step fallback、publish 重试调度、reset 后回退状态、step claim 后 task 进入 `running`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 12 个测试全部通过。
+- 2026-04-06：已完成一轮 API 代码清理。
+  - `api_server.py` 新增批量 task payload 组装 helper。
+  - `/tasks` 与 `/sessions/:session_key` 已复用同一套 task payload 预取与组装逻辑。
+  - 已重新执行测试，当前 12 个测试全部通过。
+- 2026-04-06：已整理专业化路线图。
+  - 新增 `docs/professionalization-roadmap-2026-04-06.md`
+  - 按平台边界、领域模型、接口契约、测试体系、运维成熟度五个维度拆解后续改进方向。
+  - 已明确下一批优先项为 adapter 边界、session/delivery 领域服务收敛、serializer 层、SQLite/API 测试与 OpenAPI 对齐。
+- 2026-04-06：已开始落最小 adapter 边界。
+  - 新增 `infra/adapters/codex_cli.py`
+  - 新增 `infra/adapters/biliup_cli.py`
+  - 新增 `infra/adapters/bilibili_api.py`
+  - `codex`、`biliup_cli`、`bilibili_top_comment`、`bilibili_collection` provider 已改为依赖 adapter
+  - 已执行 unittest 与 `python -m compileall biliup-next/src/biliup_next`，当前验证通过。
+- 2026-04-06：已开始落 serializer 层。
+  - 新增 `app/serializers.py`
+  - task list / task detail / session detail 的 payload 组装已从 `api_server.py` 抽到 `ControlPlaneSerializer`
+  - `api_server.py` 进一步收敛为路由、鉴权和响应控制
+  - 已执行 unittest 与 `python -m compileall biliup-next/src/biliup_next`，当前验证通过。
+- 2026-04-06：已继续收口 serializer 层。
+  - task timeline 的组装逻辑已从 `api_server.py` 抽到 `ControlPlaneSerializer.timeline_payload()`
+  - `api_server.py` 中 task 详情相关展示逻辑继续变薄
+  - 已重新执行 unittest 与 `python -m compileall biliup-next/src/biliup_next`，当前验证通过。
+- 2026-04-06：已补 serializer 层测试。
+  - 新增 `tests/test_serializers.py`
+  - 已覆盖 task payload、session payload、timeline payload 的控制面展示契约
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 15 个测试全部通过。
+- 2026-04-06：已补 repository 的 SQLite 集成测试。
+  - 新增 `tests/test_task_repository_sqlite.py`
+  - 已覆盖 `query_tasks`、批量 context/steps 查询、`session_bindings` upsert 与 fallback 读取
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 18 个测试全部通过。
+- 2026-04-06：已补 API 行为测试。
+  - 扩展 `tests/test_api_server.py`
+  - 已覆盖 `GET /tasks`、`GET /tasks/:id/timeline`、`GET /sessions/:session_key`、`PUT /settings`
+  - 已覆盖 control token 鉴权分支
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+- 2026-04-06：已继续补执行面 API 行为测试。
+  - `tests/test_api_server.py` 已新增 `POST /tasks`、`POST /tasks/:id/actions/run`、`POST /tasks/:id/actions/retry-step`、`POST /tasks/:id/actions/reset-to-step`
+  - 已覆盖写操作成功分支与 `missing step_name` 参数校验
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 28 个测试全部通过。
+- 2026-04-06：已补人工干预相关 API 行为测试。
+  - `tests/test_api_server.py` 已新增 `POST /tasks/:id/bind-full-video`、`POST /sessions/:session_key/rebind`、`POST /sessions/:session_key/merge`、`POST /webhooks/full-video-uploaded`
+  - 已覆盖成功分支、参数校验，以及 `TASK_NOT_FOUND/SESSION_NOT_FOUND` 的状态码映射
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 37 个测试全部通过。
+- 2026-04-06：已补运行面 API 行为测试。
+  - `tests/test_api_server.py` 已新增 `POST /worker/run-once`、`POST /scheduler/run-once`、`POST /runtime/services/:name/:action`、`POST /stage/import`
+  - 已覆盖 action record 落库、副作用返回值、`invalid action` 和 `missing source_path` 错误分支
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 43 个测试全部通过。
+- 2026-04-06：已补剩余控制面 GET 与上传接口测试。
+  - `tests/test_api_server.py` 已新增 `GET /history`、`GET /modules`、`GET /scheduler/preview`、`GET /settings/schema`、`POST /stage/upload`
+  - `stage/upload` 成功分支已通过 patch `cgi.FieldStorage` 固定最小 handler 契约，避免 multipart 解析细节导致测试脆弱
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 49 个测试全部通过。
+- 2026-04-06：已开始收口 session / delivery 领域服务。
+  - 新增 `app/session_delivery_service.py`，承接 `bind/rebind/merge/webhook` 的核心规则与持久化路径
+  - `app/task_actions.py` 已改为薄封装，仅保留 `ensure_initialized()`、审计记录与 service 调用
+  - 新增 `tests/test_session_delivery_service.py`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 51 个测试全部通过。
+- 2026-04-06：已继续收口 task control 领域服务。
+  - 新增 `app/task_control_service.py`，承接 `run/retry/reset` 编排
+  - `app/task_actions.py` 已进一步变薄，`run_task_action/retry_step_action/reset_to_step_action` 改为纯 service 封装 + 审计
+  - 新增 `tests/test_task_control_service.py`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 54 个测试全部通过。
+- 2026-04-06：已将 POST 路径分发从 API handler 中下沉。
+  - 新增 `app/control_plane_post_dispatcher.py`，统一承接 POST 路径的用例分发、状态码映射和运行面 action record
+  - `app/api_server.py` 的 `do_POST()` 已收敛为请求解析、dispatcher 调用和响应写出
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 54 个测试全部通过。
+- 2026-04-06：已补 dispatcher 直测。
+  - 新增 `tests/test_control_plane_get_dispatcher.py`
+  - 新增 `tests/test_control_plane_post_dispatcher.py`
+  - 已覆盖 dispatcher 层的状态码映射、过滤逻辑、运行面 action record 与创建任务冲突映射
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 62 个测试全部通过。
+- 2026-04-06：已开始做可迁移交付清理。
+  - `config/settings.json` 与 `config/settings.staged.json` 已替换为 standalone 默认模板，不再携带本机绝对路径和真实密钥
+  - `runtime/cookies.json` 与 `runtime/upload_config.json` 已替换为可分发模板
+  - 新增 `docs/cold-start-checklist.md`
+  - `README.md` 已补充冷启动入口说明
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 63 个测试全部通过。