迁移 Obsidian Vault

迁移采用 scan → 人工 Config → preview → apply。Scan 和 Preview 不修改 Vault；Apply 需要显式确认，并且先在 Vault 外部建立原字节备份。

示例 Vault

公开示例位于 example/obsidian-vault/vault/，只包含虚构文章和合成 SVG：

vault/
├── Knowledge/
├── Projects/
├── Journal/
├── Templates/
└── assets/

目录用于 Obsidian 导航，不必映射成同名 Collection。示例 Config 把 Knowledge/ 和 Projects/ 都映射到一个 documents Collection，并且排除 Journal/ 与 Templates/。

1. Scan：只读观察

把报告与建议 Config 写到 Vault 外部：

md-db-engine init scan ./example/obsidian-vault/vault \
  --output ./migration-review

检查 migration-review/init-report.md，然后编辑 migration-review/mddb.init.yaml。Scan 的目录建议只是起点；应该由用户决定哪些目录属于同一业务 Collection。

2. 人工编辑 Config

一个适合示例 Vault 的 Config：

formatVersion: 1
collections:
  documents:
    include:
      - "Knowledge/**/*.md"
      - "Projects/**/*.md"
    schema:
      strict: false
      fields:
        title: string
        status: string
        tags: array
        body: markdown
exclude:
  - "Journal/**"
  - "Templates/**"

include 决定一次性导入集合，Schema 决定 Runtime 验证规则。Config 在迁移完成后不再参与日常 Merge。

3. Preview：反复确认

md-db-engine init preview ./example/obsidian-vault/vault \
  --config ./migration-review/mddb.init.yaml \
  --plan ./migration-review/migration-plan.json \
  --json

检查 eligible、pending、Collection 分布和每个文件将增加的 Frontmatter 字段。存在歧义时修改 Config，再次执行 Preview。不要手工修改 Plan；Vault 变化后应该重新生成。

4. Apply：备份后迁移

md-db-engine init apply ./example/obsidian-vault/vault \
  --plan ./migration-review/migration-plan.json \
  --database ./databases/knowledge.mddb \
  --yes \
  --json

Apply 为 eligible 文件增加缺失的 id、collection 和 title，但不移动文件、不重命名文件，也不改写正文。成功后，原 Vault 成为带签名 .mddb/ 基线的 Based Workspace；Runtime Database 位于 ./databases/knowledge.mddb。

图片和其他资源

图片、PDF、Canvas 和附件继续保存在 Vault 中。Markdown 内的 Obsidian 引用保持不变，所以用 Obsidian 打开迁移后的 Vault 时仍能显示资源。Runtime Database 只管理被选中的 Markdown Record，不复制二进制资源。

Pending 和恢复

pending 文件不会被部分导入，也不会阻止其他 eligible 文件形成明确计划。修正规则后可以在 Apply 前重新 Preview。Apply 失败会恢复 Vault 原字节并且不发布半成品 Runtime；成功结果会返回外部 Backup 路径。不要把 Backup 放进原 Vault。