Markdown DB Engine 系统架构

产品定义

Markdown DB Engine 是一个以 Markdown 保存正式业务记录的内容型嵌入式数据库。它向应用提供一致查询、事务修改、Schema、索引、关系、权限和事件，同时允许人、Obsidian、编辑器与 Agent 在数据库外自由修改 Markdown Workspace，再通过受检查的 Merge 原子提交变化。

系统面向文章、知识、CMS、Agent Memory 与项目档案等十万以内 Record 的本地与单机内容场景。它不是 Git 内容同步服务、Markdown 网站生成器、高频事件存储、分析型表格系统或高并发分布式数据库。

两类数据状态

系统只有两类业务数据状态：

应用、TS SDK、本地 Server、Web UI
                 ↕
          Runtime Database
                 ↕ update / merge
      Markdown Workspace（可有多个）
                 ↕
      人、Agent、Obsidian、编辑器

Runtime Database

Runtime Database 是唯一正式运行状态和应用 IO 中心。查询、写入、事务、Schema、权限、索引、并发控制、事件与恢复都以它为准。

正式业务 Record 使用 Markdown 保存。索引、WAL、Catalog、凭据和恢复元数据可以使用更适合数据库实现的内部格式，但不能替代正式 Markdown Record。

Markdown Workspace

Workspace 是 Runtime Database 数据的外部可编辑副本。一个数据库可以对应任意数量且无需注册的 Workspace；任何人都可以复制 Markdown 数据，或者通过 SDK、CLI 和 Web UI 创建 Workspace。

Workspace 持有者不自动获得数据库权限。Workspace 可以暂时包含无法解析的 Markdown、无效 Schema、重复 ID、断裂关系和并发冲突，只有通过鉴权并完成 Merge 检查的 Changeset 才能进入 Runtime Database。

Workspace 之间不能派生或互相合并，也不形成 Branch 或用户可操作的 Revision 树。每个 Workspace 只直接与 Runtime Database 进行 Update 和 Merge。

核心不变量

应用只读取 Runtime Database 已提交状态。
未 Merge 的 Workspace 变化对运行时查询完全不可见。
Workspace 的自由编辑不依赖数据库进程、专用 Tool 或实时监听。
Runtime API 写入与 Workspace Merge 共享同一个事务、Schema、约束和索引更新路径。
一个 Merge Plan 只有整体合法后才能提交；提交结果只能是全部成功或全部失败。
同一 Runtime Database 同一时间只有一个 Writer Host，多 Reader 可以读取一致快照。
Record 的身份、版本、权限和冲突不依赖它所在的文件、布局或分区。
索引损坏或丢失后可以从正式 Markdown、Schema 和必要 Catalog 重建。
Git、云盘、对象存储和 Workspace 传输方式不参与数据库事务语义。
内容型 Collection 默认一个 Document 文件对应一条 Record；任何多 Record 文件都必须具有明确容量上限。
Workspace 可以只投影特定查询或 Record 范围；范围外缺失不能产生删除语义。
可读性由发现、寻址、有界上下文、局部修改、Diff 和恢复共同构成，不由 Markdown 扩展名单独保证。

完整能力组成

Collection、Record、Schema、Reference 与稳定 UUID；
单记录与多记录 Markdown Layout；
字段分区与容量分区；
属性、唯一、全文和关系索引；
Snapshot Read、Serializable Write、WAL 与崩溃恢复；
类型安全 Query/Mutation API 与跨 Collection 事务；
多个无需注册的 Workspace；
Based Workspace 三方 Update 与 Merge；
Unbased Workspace 交互式导入；
Merge Plan、冲突选择、删除影响与原子提交；
内置用户、简单角色、Credentials、审计和只读系统表投影；
Embedded TypeScript SDK、本地 Server、HTTP API、事件流、CLI 与 Web UI。

详细设计分别见：

仓库模块边界

仓库采用 Core 包与交付应用分离的结构：

packages/core  ← 唯一的数据库内核与 Embedded TypeScript SDK
       ↑
apps/server    ← Local Server、HTTP JSON API、SSE、Web 静态资源托管
apps/cli       ← md-db-engine 统一命令行与 Local Server 启动适配器
apps/web       ← 通过 Local Server API 使用数据库的管理界面

Core 负责 Runtime 文件、事务、WAL、索引、Workspace、Merge、权限与审计的领域语义。所有 apps 只能经由 Core 的公开 API 或 Server 的版本化 HTTP API 操作数据，不能拥有第二条文件读写路径。

产品边界

数据库负责

运行时数据一致性、事务、查询、索引和恢复；
Runtime Database 与 Workspace 之间的 Update、Merge 与冲突处理；
Markdown Record 的安全解析、格式保留和局部修改；
身份、Schema、关系、权限和审计；
嵌入式与本地 Server 两种访问形态。

数据库不负责

Git、GitHub 或其他版本控制；
Workspace 文件怎样备份、传输或多人共享；
多节点共识、分布式事务和远程高可用集群；
把任意二进制资产直接作为 Markdown Record 保存；
自动把未提交 Workspace 变化实时写入 Runtime Database；
个人网站、CMS、Agent Memory 等上层应用的业务逻辑；
完整兼容 MySQL、PostgreSQL 或 SQLite 的 SQL 与网络协议。