biliup-next/docs/config-system.md

Config System

Design Goal

配置系统不是辅助功能，而是新系统的控制面基础设施。

目标：

• 所有运行参数有统一来源
• 配置可被严格校验
• 配置可被 UI、CLI、文件三种方式修改
• 配置变更可审计
• 无效配置不得直接污染运行态

Design Principles

借鉴 OpenClaw 的做法，配置系统采用 schema-first 设计。

核心原则：

• 所有配置项必须先声明在 schema 中
• 所有模块只能通过配置服务读取配置
• UI 表单由 schema 驱动渲染
• 保存前必须校验
• 校验失败不允许生效
• 配置有版本和变更记录

Config Sources

1. Default Config

系统默认值，由代码内置或默认配置文件提供。

2. Active Config

当前生效的正式配置。

建议位置：

• biliup-next/config/settings.json

3. Staged Config

用户在 UI 或 CLI 中提交、但尚未生效的待校验配置。

建议位置：

• biliup-next/config/settings.staged.json

4. Schema

定义配置结构、类型、默认值、枚举范围、校验规则和 UI 元信息。

建议位置：

• biliup-next/config/settings.schema.json

Config Flow

User edits config
  -> Write staged config
  -> Validate against schema
  -> Run dependency checks
  -> If valid: promote to active
  -> If invalid: keep current active config

Validation Layers

1. Schema Validation

检查：

• 类型
• 必填字段
• 枚举值
• 数值范围
• 字段格式

2. Semantic Validation

检查：

• 路径是否存在
• 可执行文件是否可用
• season id 是否合法
• 依赖组合是否冲突

3. Runtime Validation

检查：

• provider 是否可初始化
• 凭证是否存在
• 外部连接是否可用

Suggested Config Groups

runtime

• workspace_dir
• database_path
• log_level
• scan_interval_seconds

paths

• stage_dir
• backup_dir
• session_dir
• cookies_file
• upload_config_file

ingest

• provider
• min_duration_seconds
• ffprobe_bin
• yt_dlp_cmd
• allowed_extensions

transcribe

• provider
• groq_api_key
• max_file_size_mb
• ffmpeg_bin

song_detect

• provider
• codex_cmd
• qwen_cmd
• poll_interval_seconds

split

• ffmpeg_bin
• poll_interval_seconds

publish

• provider
• biliup_path
• cookie_file
• retry_count
• retry_schedule_minutes
• retry_backoff_seconds

comment

• enabled
• max_retries
• base_delay_seconds
• poll_interval_seconds

Upload And Comment Templates

paths.upload_config_file 指向 runtime/upload_config.json。这个文件不只控制 biliup upload 的标题、简介、动态和标签，也控制 B 站置顶评论格式。

投稿字段在 template 中：

{
  "template": {
    "title": "【{streamer} (歌曲纯享版)】 {date} 共{song_count}首歌",
    "description": "{streamer} {date} 歌曲纯享版。\n\n完整歌单与时间轴见置顶评论。\n直播完整版：{current_full_video_link}\n上次直播：{previous_full_video_link}",
    "tag": "可爱,王海颖,唱歌,音乐",
    "dynamic": "{streamer} {date} 歌曲纯享版已发布。\n直播完整版：{current_full_video_link}"
  }
}

评论字段在 comment_template 中：

{
  "comment_template": {
    "split_header": "当前视频：歌曲纯享版：只保留本场直播中的歌曲片段，歌单见下方。\n直播完整版：{current_full_video_link} （完整录播，含聊天/互动/完整流程）\n上次纯享：{previous_pure_video_link} （上一场歌曲纯享版）",
    "full_header": "当前视频：直播完整版：保留本场完整录播内容，歌曲时间轴见下方。\n歌曲纯享版：{current_pure_video_link} （只听歌曲看这里）\n上次完整版：{previous_full_video_link} （上一场完整录播）",
    "split_part_header": "P{part_index}:",
    "full_part_header": "P{part_index}:",
    "split_song_line": "{song_index}. {title}{artist_suffix}",
    "split_text_song_line": "{song_index}. {song_text}",
    "full_timeline_line": "{song_index}. {line_text}"
  }
}

可用变量：

• streamer：主播名。
• date：从文件名解析出来的日期和时间。
• song_count：识别到的歌曲数量。
• songs_list：songs.txt 原始歌单内容。
• daily_quote / quote_author：随机引用文本。
• current_full_video_bvid / current_full_video_link：本场直播完整版 BV 和链接。
• current_pure_video_bvid / current_pure_video_link：本场歌曲纯享版 BV 和链接。
• previous_full_video_bvid / previous_full_video_link：上一场直播完整版 BV 和链接。
• previous_pure_video_bvid / previous_pure_video_link：上一场歌曲纯享版 BV 和链接。
• part_index：评论中的 P1/P2/P3 分段序号。
• song_index：全局歌曲序号。
• title / artist / artist_suffix：从 songs.json 生成纯享歌单时使用。
• song_text：从 songs.txt 兜底生成纯享歌单时使用，通常不含时间戳。
• line_text：完整版时间轴的原始行，通常包含时间戳。

评论头部模板有一条额外规则：如果某一行包含空链接变量，例如 {previous_full_video_link} 为空，这一整行会自动跳过，避免发出空链接提示。

Docker 部署时 ./runtime 是宿主机挂载目录。镜像更新不会覆盖已有 runtime/upload_config.json，因此调整文案或评论格式时应修改宿主机上的这个文件，然后重启容器。

collection

• enabled
• season_id_a
• season_id_b
• allow_fuzzy_full_video_match
• append_collection_a_new_to_end
• append_collection_b_new_to_end

UI Strategy

管理台不手写业务表单，而是由 schema 驱动生成配置界面。

每个配置项除了类型信息，还应有：

• title
• description
• group
• ui:widget
• ui:secret
• ui:order

这样可以让配置页面和底层配置保持同源。

Audit Trail

每次配置变更都应记录：

• 修改人
• 修改时间
• 修改前值
• 修改后值
• 校验结果
• 是否已生效

Non-Goals

• 不追求兼容任意格式的配置文件
• 不允许模块私自定义一份独立配置入口
• 不允许 UI 和代码维护两套不同的字段定义