跳到主要内容
Markdown DB Engine

完整产品能力

Runtime Database

Markdown DB Engine 必须作为独立数据库向应用提供：

  • 数据库创建、打开、关闭、完整性检查和备份；
  • Collection、Record、Schema、Index 与 Reference；
  • 一致查询、运行时 Mutation 和跨 Collection Transaction；
  • 单 Writer Host 与多 Reader Snapshot；
  • WAL、回滚、崩溃恢复和索引重建；
  • 已提交事务事件；
  • 内置用户、角色、Credential 和审计。

Credential 包含 Password、API Token 与有到期时间的 Session。所有 Credential 都可以撤销；Token 与 Session 明文只在创建时显示，Workspace、Audit 和普通管理查询均不能返回凭据或 Hash。

应用不读取正在编辑的 Workspace，也不直接修改 Runtime Database 物理文件。

Markdown 物理数据

正式业务 Record 使用 Markdown 保存，并支持：

  • 一个文件一条正文型 Record；
  • 一个 GFM Table 保存多条扁平 Record；
  • 一个 YAML fenced block 保存多条嵌套 Record；
  • 同一 Collection 跨多个文件分区；
  • 按字段、Record 数和文件大小分区；
  • Properties、正文、注释和未触及格式的尽量保留；
  • 从正式 Markdown 与 Schema 重建索引。

内容型 Collection 默认采用一个文件一条正文型 Record。GFM Table 与 YAML Records 是小型辅助数据布局，Schema 必须为它们声明 maxRecordsPerFile 与 maxBytesPerFile；达到上限后必须创建新分区，不能继续扩展成需要整体读取和重写的超大文件。

每条 Record 拥有全局唯一 UUID。Record 身份、版本、权限和冲突不依赖路径或文件布局。

普通 Document Record 固定包含 title 系统字段，并默认使用安全规范化后的标题作为正式 Markdown 和新导出 Workspace 的文件名。同一 Collection 内的标题在完成文件名转换、Unicode 规范化和大小写折叠后必须保持唯一；冲突会被拒绝，不会添加 UUID 后缀。修改标题只移动文件，不改变 Record 身份。不同 Collection 可以使用同名标题；Table、Records 和内置系统 Collection 保持聚合文件或系统路径规则。

Schema 与关系

Schema 支持：

  • 强类型字段、required、nullable 和 default；
  • strict 与 open Collection；
  • enum、数组和嵌套对象；
  • UUID Reference；
  • 普通、唯一、复合、全文和关系索引；
  • restrict、cascade、setNull 和 remove 删除策略；
  • Schema 与数据在一个 Merge Plan 中原子变更。

Schema 可以通过 Runtime API、Web UI 或 Workspace 修改，但进入 Runtime Database 前必须验证完整目标状态。

多 Workspace

一个 Runtime Database 可以对应任意数量的 Workspace。Workspace：

  • 无需向数据库注册；
  • 可以由 SDK、CLI、Web UI 或普通文件复制产生；
  • 可以由人、Obsidian、编辑器和 Agent 自由修改；
  • 可以暂时违反 Markdown 格式、Schema、唯一约束和关系；
  • 不获得数据库权限，也不携带 Credential；
  • 不与其他 Workspace 派生或互相 Merge。

Based Workspace 携带经过完整性保护的 Merge 基线；Unbased Workspace 通过交互式导入进入数据库。

Workspace 可以是完整数据副本，也可以是按照 Collection、查询、UUID 集合或分区导出的 Scoped Workspace。Manifest 必须记录范围与基线：范围之外缺少的 Record 不表示删除，也不能进入删除候选；范围内的删除仍需经过版本、权限、Reference 和冲突检查。

Update

Update 把 Runtime Database 当前数据合并到 Workspace。它：

  • 不修改 Runtime Database；
  • 不静默覆盖 Workspace 变化；
  • 自动应用没有冲突的 Runtime 变化；
  • 按字段、Record、Body、Schema 和删除类型展示冲突；
  • 允许逐项或批量选择 Runtime、Workspace 或手动结果；
  • 检测并处理损坏的 Workspace 隐藏目录。

Merge

Merge 将 Workspace 文件变化转换为数据库 Changeset。完整流程包括：

  • 识别新增、修改、删除、移动、重命名和分区变化；
  • 解析 Document、Table 和 Records Layout；
  • 检查 UUID、Schema、字段、索引、Reference 和删除影响；
  • 检查 Runtime 并发修改与权限；
  • 检查只读系统表和受保护操作；
  • 生成可查看、可调整且机器可读的 Merge Plan；
  • 允许用户排除候选变化或选择冲突结果后重新生成 Plan；
  • 只有 Plan 整体合法时才允许 Apply；
  • Apply 作为一笔 Runtime Transaction 全部提交或全部失败。

Merge 失败不能修改 Runtime Database，也不能丢失 Workspace 内容。

Query 与 Mutation

数据库提供类型安全的 Collection/Document API：

  • UUID 与条件读取；
  • 嵌套字段、数组、范围和集合运算；
  • 字段投影、稳定排序和游标分页；
  • 全文、Reference 与反向关系查询；
  • Insert、Replace、Patch、Delete 和批量 Changeset；
  • 跨 Collection Transaction；
  • optimistic concurrency control；
  • 查询计划与索引诊断。

SQL 不是产品核心契约，可以通过兼容适配器提供，但不能限制 Markdown Document 与 Workspace 能力。

权限

数据库使用简单角色：

  • Owner：全部数据、Schema、Merge、用户和维护权限；
  • Editor：查询、运行时修改、Update 和 Merge；
  • Reader：查询和导出 Workspace。

用户表可以向 Workspace 导出不含 Credential 的只读投影。权限与 Credential 只能通过经过鉴权的 Web UI 或 API 修改，不能通过 Markdown Merge 修改。

交付界面

完整产品提供：

  • Embedded TypeScript SDK；
  • 连接本地 Server 的 Remote TypeScript SDK；
  • Versioned HTTP JSON API；
  • 事务提交事件流；
  • 支持人类与 Agent 的 CLI；
  • 类似 phpMyAdmin 的 Web UI。

Web UI 覆盖数据、Schema、Index、Query、Transaction、Workspace、Merge、冲突、用户、权限、审计、WAL、锁、备份和健康状态，不承担主要 Markdown 正文编辑。

候选 npm 包同时导出 Embedded SDK、Local Server 与 CLI Entry。Backup 创建可以独立打开的 Snapshot；Restore 始终写入新的目标目录，并且只有在完整性检查通过以后才返回成功。

初始化已有目录

已有 Obsidian Vault 或混合型 Markdown 知识库通过一次性的 Scan、Preview、Apply 创建数据库。Scan 只读统计目录、字段、已有身份和资源，并生成预填 Collection、Schema、include/exclude Config；Preview 允许用户反复调整规则，展示明确 eligible、pending 和确切 Frontmatter Patch，不修改知识库；Apply 先在知识库外建立原字节备份，只为 eligible 文件增加缺失的 UUIDv7、Collection 与 title，然后原子创建 Runtime Database、Schema 和 Based Workspace。

迁移 Config 在成功后不参与日常 Merge。Signed Manifest 保存受管 Record 集合；没有 collection 的模板、绘图、报告与普通 Markdown 可以继续留在同一个 Vault，不会被解析成 Record。新 Markdown 使用 collection 明确加入 Merge 发现；缺少 id 和 title 时由 Merge Plan 生成 UUIDv7 并使用文件名，Apply 成功后再写回文件。任何推断都不能在用户确认前修改文件，pending 文件也不能在 Apply 过程中被临时跳过后形成部分事务。

产品边界

Markdown DB Engine 面向十万以内 Record 的本地和单机数据场景。它不负责：

  • Git、GitHub、云盘或 Workspace 文件协作；
  • 多节点共识、分布式事务与远程高可用；
  • 上层网站、CMS 或 Agent 产品业务；
  • 将任意二进制内容直接存入 Markdown；
  • 自动监听并提交 Workspace 变化；
  • 完整兼容其他数据库的全部协议与运维系统。
  • 使用单个 JSON、YAML、XML、Markdown Table 或 Records 文件承载并直接编辑数千条 Record；
  • 高频日志、遥测、订单流水和分析型宽表等以机器吞吐为主要目标的数据负载。