5.5 KiB
5.5 KiB
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 文件推断状态
- 日志推断状态
- 目录结构推断状态
正确做法：
- 数据库记录任务状态
- 文件系统存放任务产物
- 日志记录过程和诊断
三者职责分离，不互相替代。
补充：
- 工作区 flag 可以保留，用于表示某些外部动作已经发生，例如评论、合集、上传等副作用完成。
- 但这些 flag 不应被提升为 task 主状态本身。
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 和稳定领域模型之上