# Design Principles ## Positioning `biliup-next` 以 OpenClaw 的设计哲学为指引，但不复制它的产品形态。 本项目的核心目标不是做聊天代理系统，而是构建一个面向本地视频流水线的控制面驱动系统。 因此我们借鉴的是方法论： - 单体优先 - 控制面优先 - 配置与扩展元数据优先 - 严格校验 - 本地优先 - 可读、可审计、可替换 ## Principle 1: Modular Monolith First 系统优先采用模块化单体架构，而不是微服务。 原因： - 当前问题主要来自边界混乱，而不是部署扩展性不足 - 单机部署和 systemd 管理仍然是核心场景 - 统一配置、任务状态和日志比进程拆分更重要 约束： - 所有模块运行在同一系统边界内 - 模块之间通过抽象接口和统一模型交互 - 不得通过随意脚本调用形成隐式耦合 ## Principle 2: Control Plane First 功能模块不是系统中心，控制面才是系统中心。 控制面负责： - 配置管理 - 任务状态管理 - 模块与插件注册 - 手动操作入口 - 日志与诊断 数据面负责： - 执行转录 - 执行识歌 - 执行切歌 - 执行上传 - 执行评论和合集归档 任何新增功能，都必须先回答： - 它如何进入控制面 - 它的状态如何呈现 - 它的配置如何管理 - 它失败后如何恢复 ## Principle 3: Schema-First Configuration 配置必须先有 schema，再有实现和 UI。 要求： - 所有配置项先定义在 schema - 所有配置项有默认值、校验规则和说明 - UI 基于 schema 生成 - CLI 和 API 使用同一套字段定义 禁止： - 在模块里私自增加隐藏配置常量 - UI 和代码维护不同字段名 - 配置错误仍然带病启动 ## Principle 4: Manifest-First Extensibility 扩展能力先注册元数据，再执行运行时代码。 manifest 负责描述： - 插件是谁 - 提供什么能力 - 需要什么配置 - 入口在哪 - 是否可启用 这样控制面可以在不执行插件代码时完成： - 能力发现 - 配置渲染 - 可用性检查 - 兼容性检查 ## Principle 5: Registry Over Direct Coupling 模块和插件必须通过统一 registry 接入。 例如： - transcriber registry - song detector registry - publisher registry - collection strategy registry 核心模块只依赖接口，不依赖具体 provider。 这意味着： - 更换 Groq 为其他转录器不影响任务引擎 - 更换 Codex 为其他识歌器不影响控制面 - 更换 biliup 为其他上传方式不影响领域模型 ## Principle 6: Local-First And Human-Readable 系统优先本地运行，本地保存，本地可读。 要求： - 主状态存储可本地访问 - 日志保存在本地 - 配置保存在本地 - 关键元数据可被开发者直接理解 这不意味着只靠文件系统。 建议做法： - SQLite 保存结构化状态 - 文件系统保存产物 - JSON / YAML 保存配置 - 文本日志保存审计和错误 ## Principle 7: Strict Validation 系统不能接受“差不多能跑”的配置和模块状态。 启动或配置变更前，应验证： - schema 是否合法 - 可执行依赖是否存在 - 必要凭证是否存在 - provider 是否可初始化 - 插件 manifest 是否正确 失败时： - 保留旧运行态 - 返回明确错误 - 不进入半失效状态 ## Principle 8: Single Source Of Truth 任务状态必须有统一来源。 不得同时依赖： - flag 文件推断状态 - 日志推断状态 - 目录结构推断状态 正确做法： - 数据库记录任务状态 - 文件系统存放任务产物 - 日志记录过程和诊断 三者职责分离，不互相替代。 ## Principle 9: Replaceability With Stable Core 可替换的是 provider，不可随意漂移的是核心模型。 稳定核心包括： - Task - TaskStep - Artifact - PublishRecord - CollectionBinding - Settings 这些模型一旦定义，应保持长期稳定，避免每新增一个模块就改核心语义。 ## Principle 10: Observability Is A First-Class Feature 可观测性不是补丁，而是正式能力。 管理台必须能够回答： - 当前有哪些任务 - 每个任务在哪一步 - 最近一次失败是什么 - 当前启用的 provider 是谁 - 当前配置是否有效 - 哪个模块健康异常 如果系统不能快速回答这些问题，说明设计不完整。 ## Principle 11: Backward-Compatible Migration 重构必须与旧系统并行推进。 要求： - 原项目继续运行 - 新项目只在 `./biliup-next` 演进 - 先搭文档和骨架 - 再逐步迁移模块 - 最后切换生产入口 禁止： - 直接在旧系统里边修边重构 - 在未定义状态模型前大规模搬代码 ## Principle 12: Documentation Before Expansion 任何新的模块、插件、控制面能力，在动手实现前都要先回答： - 它属于哪个层 - 它的输入输出是什么 - 它如何配置 - 它如何注册 - 它如何被 UI 展示 - 它如何失败和恢复 如果这些问题没有写清楚，就不应进入实现阶段。 ## Summary `biliup-next` 的核心方向不是“把旧脚本改漂亮”，而是： - 建立一个本地优先、控制面驱动、模块边界清晰的系统 - 让配置、模块、状态、操作和诊断都回到统一模型之下 - 让未来扩展建立在 schema、manifest、registry 和稳定领域模型之上