Documentation · v0.3.0
从任务开始，需要时深入原理
先选择快速开始、迁移 Vault、Workspace 协作或搭建应用。所有页面直接来自仓库docs/，是项目的单一事实源，并且和发布包一起验证。
使用指南7
快速开始
本指南使用 Markdown DB Engine `0.3.0` 创建本地 Runtime Database，并通过 Web UI 查看和管理内容。需要 Node.js 22 或更高版本。
迁移 Obsidian Vault
迁移采用 `scan → 人工 Config → preview → apply`。Scan 和 Preview 不修改 Vault；Apply 需要显式确认，并且先在 Vault 外部建立原字节备份。
Workspace 协作
Workspace 是可以交给 Obsidian、编辑器或 Agent 自由修改的 Markdown 目录。Runtime Database 不监听 Workspace；所有变更都需要先生成 Merge Plan，再显式 Apply。
搭建应用
应用只查询 Runtime Database，不读取正在编辑的 Workspace。根据部署方式选择 Embedded 或 Remote，两者返回相同的高层 `RuntimeDatabase` API。
CLI 参考
`md-db-engine --help` 列出稳定命令；`--json` 适合脚本和 Agent，失败时返回结构化错误对象和非零退出码。
运维与恢复
一个 Runtime Database 同时只能由一个 Writer Host 管理。Local Server 运行时，Web UI、CLI 和应用应该连接它的 endpoint：
Agent Skills
Markdown DB Engine 提供两个项目级 Skill，使支持 Skills 的 Coding Agent 可以执行完整工作流，而不要求用户逐条输入 CLI 命令。
产品参考3
产品愿景
Markdown DB Engine 是一个以 Markdown 保存正式业务记录的内容型数据库。它像 SQLite 一样为本地应用提供查询、Schema、索引、事务和一致性，同时允许人、Obsidian、编辑器与 AI Agent 在数据库之外直接修改可读的 Markdown Workspace。
完整产品能力
Markdown DB Engine 必须作为独立数据库向应用提供：
个人数字展示平台
个人数字展示平台是 Markdown DB Engine 的上层应用示例，不参与定义数据库内核。它展示普通 Web 应用怎样通过 Runtime Database 管理文章、项目、Skill、Agent 和社交账号，同时允许用户通过 Workspace 使用 Obsidian 与 Agent 批量维护内容。
架构参考7
系统架构
Markdown DB Engine 是一个以 Markdown 保存正式业务记录的内容型嵌入式数据库。它向应用提供一致查询、事务修改、Schema、索引、关系、权限和事件，同时允许人、Obsidian、编辑器与 Agent 在数据库外自由修改 Markdown Workspace，再通过受检查的 Merge 原子提交变化。
数据模型与 Markdown 布局
数据库使用 Collection 与 Record 作为统一逻辑模型：
运行时与事务
数据库核心是嵌入式本地引擎。TypeScript 应用可以直接打开数据库目录；本地 Server 也可以作为 Writer Host 打开数据库，并向 Web UI 与其他语言提供 API。
Workspace 与 Merge
一个 Runtime Database 可以对应任意数量的 Workspace。Workspace 无需向数据库注册，可以通过 SDK、CLI、Web UI、普通文件复制或其他外部方式创建。
安全模型
Workspace 是不可信输入。任何人都可以复制、查看和修改 Workspace，但只有通过 Runtime Database 鉴权和权限检查的操作才能查询受保护数据或提交 Merge。
接口与交付形态
Embedded SDK、本地 Server API、CLI 和 Web UI 共享同一领域接口与错误模型。任何交付界面都不能直接修改 Runtime 文件或跳过事务、权限和 Merge Plan。
ADR：技术栈决策
阶段一技术栈与接口边界的架构决策记录：测试先行、TypeScript 全栈、单一 Runtime 事实源与交付应用边界。