旧笔记搬迁实录:把多年散落的文档批量导进本地知识库

原创2026-11-05 20:25:301,606 阅读

旧笔记搬迁实录:把多年散落的文档批量导进本地知识库

搬家最难的不是搬,而是搬完之后发现标题丢了、时间戳全变成今天、图片指向一个已经不存在的文件夹。quiet.md 目前是 0.1.4 的 Beta 版,社区讨论还不多,很多行为边界只能从源码里读出来。这篇文章把它的导入链路完整拆一遍:哪些步骤是应用替你做的,哪些必须自己先做,哪些坑会在"看起来导入成功"之后才爆发。

先看清终点:这个知识库到底是什么结构

quiet.md 的库不是数据库,就是一个普通文件夹,默认在 ~/Documents/Quiet.md(可用环境变量 QUIET_MD_HOME 指到别处)。目录布局写在 docs/FORMAT.md 里,实现见 crates/core/src/store.rs:

Quiet.md/
├── format.json          {"format": 1}
├── index.json           文档 id → Meta
├── index.json.bak       上一版 index.json
├── .lock                写索引时的 flock
├── docs/<id>.xml        每篇文档一份 DocxXML
├── assets/              图片、附件
└── trash/

这里有两个必须先记住的结论。

第一,元数据和内容分居两处。 置顶、收藏、父文档、页宽这些都在 index.json 的 Meta 里,不在 XML 里。所以"把 XML 复制过去"能搬内容,但搬不动层级关系。

第二,文档 id 是文件名。 Store::list() 遍历 docs/,用 file_stem() 当 id:

let Some(id) = p.file_stem().and_then(|s| s.to_str()).map(str::to_string) else { continue };
let Ok(xml) = std::fs::read_to_string(&p) else { continue };
let doc = docxml::parse(&xml).unwrap_or_default();

这段代码里藏着本次搬迁最重要的两个特性,后面会分别展开:文件名即文档身份,以及 unwrap_or_default() 会把解析失败的 XML 静默变成空白文档。

两条导入通道,选错会丢时间戳

quiet.md 有两个入口,行为完全不同。

入口 A:应用内导入。 主菜单的「导入为文档…」或主页的上传卡片,走 src/transfer.rs 的 import_files。它一次可以选多个文件,接受 md / markdown / mark / txt / xml:

const MARKDOWN_EXTS: [&str; 4] = ["md", "markdown", "mark", "txt"];

let made = match ext.as_str() {
    e if MARKDOWN_EXTS.contains(&e) => markdown_document(p)
        .map_err(anyhow::Error::from)
        .and_then(|doc| self.store.create_from(&doc)),
    "xml" => self.store.import(p),
    _ => Err(anyhow::anyhow!("文件格式不支持")),
};

而 create_from 的第一行就是:

let id = uuid::Uuid::new_v4().to_string();

也就是说:每篇文档都拿一个新 uuid,created 和 modified 都是 now()。十年的笔记搬进来,全部显示"今天创建"。另外,一批文件里只要有一个失败,只会弹一句「导入失败,请检查文件格式」,不会告诉你失败的是哪一个;导入结束后只打开最后一个文件。

入口 B:直接放进 docs/。 FORMAT.md 明确写了"手放的文件也会出现"。这条路更原始,但更适合批量迁移:

应用内导入 直接放 docs/
文档 id 随机 uuid 文件名(去掉 .xml)
created / modified 导入时刻 文件 mtime
支持格式 Markdown、DocxXML 仅 DocxXML
解析失败 报错 静默变空白文档
保留跨文档引用 否(id 变了) 是(id 可控)

第三行和第五行是决定性的。先看 mtime 这一条——list() 里对新出现的文件这样建 Meta:

let m = e.metadata().ok()
    .and_then(|m| m.modified().ok())
    .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
    .map(|d| d.as_secs())
    .unwrap_or_else(now);
Meta { created: m, modified: m, ..Default::default() }

所以想让十年前的笔记保留原来的日期,只需要在拷贝前把 mtime 打回原始时间:

cp ~/old-notes/2019/架构评审.xml /tmp/quiet-dry/docs/
touch -d "2019-03-02 10:24:00" /tmp/quiet-dry/docs/架构评审.xml

文档树仍然会按"最近修改"排序(sort() 用 Reverse(meta.modified)),但至少文件本身的时间线是真的。反过来,用应用内导入,这个信息就永久丢失了。

如果你要迁移的是 Markdown,只能走进口 A;DocxXML 优先选入口 B。

quiet.md 主页:左侧是文档树,右侧按网格排列库里的全部笔记

批量导入前的去重与清洗清单

先说结论:quiet.md 不做任何去重。create_from 每次都生成新 uuid,同一篇笔记导两次就是两篇,标题一样、内容一样、id 不同。去重必须在导入前完成。

基于 crates/core/src/paste.rs 的 Markdown 解析器行为,下面几项是真正会出问题的:

BOM。 markdown_document 里有一行 text.trim_start_matches('\u{feff}'),Windows 上带 BOM 的 UTF-8 文件能正常处理。但如果 BOM 出现在拼接后的中间位置,或者文件是 UTF-16,String::from_utf8_lossy 会静默替换成替换字符,标题里就出现一堆 �。

YAML front matter。 解析器不认识它。title: 周报 会变成正文段落,而第一行的 --- 会被 divider() 判定为分割线,最终得到"一条分割线 + 几行属性文字"。Obsidian、Hexo、Hugo 的库几乎全是这种结构,务必先剥掉。

[[wikilink]]。 md_inline 只认 文本,且 link_ok 白名单是 http:// / https:// / mailto: / ftp://。双链语法不匹配,会原样留在正文里变成纯文本——看起来"没坏",但所有链接都失效了。迁移前转成标准 Markdown 链接,或者留到导入后用应用内的 @文档 重新挂。

管道表格的列数约束。 pipe_table 要求表头单元格数严格等于分隔行的单元格数:

let ncols = header.len();
if ncols != seps.len() { return None; }

差一列,整张表退化成普通段落。手工维护的老笔记里这非常常见。

代码围栏必须闭合。 md_blocks 遇到未闭合的 ``` 会一直吃到文件末尾,把后面的所有内容并进代码块。~~~ 也支持,混用不同字符的围栏不会被识别为闭合。

首个 H1 与文件名重复会被删除,这是有意的:

if blocks.first().is_some_and(|b| matches!(b.kind, BlockKind::Heading { level: 1, .. })
    && b.text.text.trim() == stem) {
    blocks.remove(0);
}

标题取自 file_stem,所以文件名本身就是标题。文件名写成 周报-2024-03-02.md,标题就是这一整串;想要干净的标题,得先改文件名。

一个能在十分钟内跑完整个库的预检脚本:

#!/usr/bin/env python3
import hashlib, pathlib, re, sys

EXTS = {".md", ".markdown", ".mark", ".txt"}
root = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else ".")

seen, total, bad = {}, 0, 0
for p in sorted(root.rglob("*")):
    if p.suffix.lower() not in EXTS or not p.is_file():
        continue
    total += 1
    raw = p.read_bytes()
    text = raw.decode("utf-8", "replace").lstrip("\ufeff")
    lines = text.splitlines()
    issues = []
    if raw.startswith(b"\xef\xbb\xbf"):
        issues.append("BOM")
    if b"\r\n" in raw:
        issues.append("CRLF")
    if lines and lines[0].strip() == "---":
        issues.append("front-matter")
    if "[[" in text:
        issues.append(f"wikilink x{text.count('[[')}")
    first = next((l for l in lines if l.strip()), "")
    if first.startswith("# ") and first[2:].strip() != p.stem.strip():
        issues.append("H1!=filename")
    key = hashlib.sha1(re.sub(r"\s+", "", text).encode()).hexdigest()
    if key in seen:
        issues.append(f"duplicate of {seen[key]}")
    else:
        seen[key] = p.name
    if issues:
        bad += 1
    print(f"{p}\t{', '.join(issues) or 'ok'}")

print(f"\n{total} files, {bad} need attention", file=sys.stderr)

如果搬的是 DocxXML,先做一次良构性检查。quick-xml 不接受坏 XML,而 list() 会把解析失败变成空文档,你只会看到一堆没有标题的白页:

for f in docs/*.xml; do xmllint --noout "$f" || echo "BROKEN $f"; done

合法的块写法可以参考 crates/core/tests/fixtures/all-blocks.xml,这个 fixture 是"读入再写出必须逐字节不变"的测试基准,也是各类 block 的规范样例。

正式动手前,建议先演练一遍。仓库自带一个生成器 tools/promo/gen_library.py,能造出一个含表格、分栏、高亮块、代码块的假库:

python3 tools/promo/gen_library.py /tmp/quiet-dry
QUIET_MD_HOME=/tmp/quiet-dry ./target/release/quiet_md

QUIET_MD_HOME 会同时改变库根目录和 assets/ 位置,整个演练过程不会碰到真实数据。批量拷贝时最好退出应用,避免索引写入与目录扫描交错。

中文文件名、空格与特殊字符

这一块最容易出"看不见的错"。

非 UTF-8 文件名会被静默跳过。 前面那段 file_stem().and_then(|s| s.to_str()) 里的 to_str() 在文件名不是合法 UTF-8 时返回 None,continue 之后这篇文档根本不进列表。macOS 上从旧 HFS+ 盘、Windows 上从 GBK 环境拷来的文件,这里会静默丢文档。搬完一定要核对数量。

没有 Unicode 规范化。 依赖清单(Cargo.toml)里没有任何 normalization 相关的 crate,标题比较、搜索匹配全部是直接的字符串操作。macOS 文件名习惯用 NFD(é 拆成 e + 组合符),Windows 多是 NFC。从 macOS 拷出来的库,标题看起来一模一样,但你在搜索框里输入的 NFC 字符串匹配不上 NFD 的标题。实践上要么全库统一成 NFC 再导入(python3 -c "import unicodedata,sys;print(unicodedata.normalize('NFC',sys.stdin.read()))" 之类的清洗),要么接受部分标题搜不到。

空格与百分号编码是成对处理的。 Markdown 导入时 resolve_images 会先 percent_decode 再和文件所在目录拼接:

let path = match src.strip_prefix("file://") {
    Some(p) => PathBuf::from(percent_decode(p)),
    None => base.join(percent_decode(src)),
};

导出方向相反,markdown.rs 在拼接图片和附件链接时做 .replace(' ', "%20")。所以 图 这种带空格的相对路径是能走通的。

但要留意:导出只转义空格和右括号,代码是 .replace(' ', "%20").replace(')', "%29")。文件名里如果含 # 或 ?,写进 Markdown 链接后会被下游当作片段标识或查询串,链接就指向了别的东西。这类文件名在迁移前重命名是最省事的。

标题转文件名时只替换三个字符。 transfer.rs 里:

fn file_name(doc: &Document) -> String {
    display_title(&doc.title.text).replace(['/', ':', '\\'], "_")
}

/、:、\ 会被换成下划线,这是导出时用的。导入方向不做任何文件名清洗,文件名原样成为标题,包括全角冒号、书名号、emoji。

Windows 上图片不会被收编。 这是代码路径上的真实不对称。localize_pasted_images 判断本地图片的条件是:

} else if src.starts_with('/') {
    image_block_from_file(Path::new(src.as_str()))
} else {
    return true;   // 原样保留
}

macOS / Linux 的绝对路径以 / 开头,会被复制进 assets/ 并改写 src;Windows 的 C:\Users\...\img.png 不以 / 开头,会被 return true 原样留下。resolve_images 已经把相对路径全部转成了绝对路径,所以在 Windows 上导入 Markdown,图片全部是指向原目录的绝对引用——原来那个文件夹一删,图全断。要么在 macOS/Linux 上完成 Markdown 导入,要么导入后逐张重新插入,要么先把图片批量转成 data: URI(这条路径是支持的,会被解码后写入 assets/)。

导入后的目录重整与断链修复

内容进来了,还有两件事没做完:层级和引用。

目录结构在 index.json 里,导入不负责搬运。 Meta.parent 是父文档 id,order 是同级排序键(最近一次移动的毫秒数),缺省时按 created 排。应用内导入或手放文件,新文档全部落在顶层。

重整有两种做法。手工做法是在侧栏用「移动到」:set_parent 会把 order 写成当前毫秒,所以移动过的文档排在同级末尾,符合"刚整理完"的直觉。批量做法的前提是你能从旧目录结构推算出父子关系,那就关掉应用、直接写 index.json,给每篇补上 parent。写之前注意两点:index.json 每次保存前会把旧版复制成 .bak,解析失败时会回退并提示,所以写坏了不至于全丢;format.json 里的 format 不能乱改,当它大于程序常量 FORMAT(当前为 1)时,应用会直接提示"请升级后再编辑"。

跨文档引用会全断——这是最隐蔽的一处。 应用内的 @文档 在 DocxXML 里长这样:

<cite type="doc" doc-id="abc" file-type="docx">A &amp; B</cite>

doc-id 是目标文档的 id,而反向引用是按 id 匹配的:Document::doc_links() 收集目标 id,Links 侧再用 id 去查 docs 列表。从飞书导出的文档之间如果互相引用,doc-id 记的是飞书那边的 id;一旦走应用内导入,每篇都换了新 uuid,这些 cite 就指向了库里不存在的 id——文档照样打开,正文里那句引用看起来也正常,但反向引用面板永远是空的,点击也跳不过去。

修复思路取决于你走哪条通道:

  • 走入口 B(手放 XML)时,把文件名设成原始 doc-id,即 docs/abc.xml。list() 用文件 stem 当 id,这样库内 id 与 cite 里的 doc-id 天然对齐,引用直接复活。
  • 走入口 A 时,id 由 uuid::Uuid::new_v4() 决定,无法预设。只能导入后在应用里重新用 @文档 插入一遍引用,旧的那段 cite 会被当作未知行内元素保留(Inline 的 xml 原文保留机制),不会报错,但也不会工作。

同理,<source path="..."> 这类本地附件引用保留的是绝对路径,见 image_path:绝对路径直接返回,相对路径才拼到库根目录。搬完库如果换了位置,走相对路径的图片仍能显示(相对库根解析),绝对路径的则全部失效。这正是 FORMAT.md 里"图片和附件的本地文件写成 path="…""这条本地扩展的实际后果。

最后做三项可验证的核对,比"感觉导完了"可靠得多:

  1. 数量对齐。 源目录的 .md 文件数(排除被同名的 .mark 重复计数)应等于库里新增文档数。docs/ 里出现的每个 .xml 都对应一篇,没有例外。
  2. 标题自查。 导入后在主页网格里扫一遍空标题。空标题只有两种来源:文件名不是合法 UTF-8 被整篇跳过(列表里根本看不到),或者 XML 解析失败被 unwrap_or_default() 变成白页(能看到但没内容)。第二种情况必须回去用 xmllint 定位。
  3. 引用抽样。 随便打开一篇曾被别的文档 @ 过的笔记,看底部的「反向引用」有没有内容。空的就说明 doc-id 没对上,属于上面说的那类断链。

搬迁这件事的真相是:能批量复制的是文件,需要重建的是关系——时间戳、父子层级、跨文档引用,三者分布在 mtime、index.json 和 doc-id 三个不同的地方,quiet.md 一个都不会替你迁移。把这三处想清楚,剩下的就是几条 cp 和一次 touch。

登录后查看全文
quiet-md