244 lines
5.5 KiB
Markdown
244 lines
5.5 KiB
Markdown
# 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 和稳定领域模型之上
|