init biliup-next

docs/design-principles.md

@@ -0,0 +1,238 @@
+# 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 和稳定领域模型之上