旧笔记搬迁实录:把多年散落的文档批量导进本地知识库
旧笔记搬迁实录:把多年散落的文档批量导进本地知识库
搬家最难的不是搬,而是搬完之后发现标题丢了、时间戳全变成今天、图片指向一个已经不存在的文件夹。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 不做任何去重。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 & 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="…""这条本地扩展的实际后果。
最后做三项可验证的核对,比"感觉导完了"可靠得多:
- 数量对齐。 源目录的
.md文件数(排除被同名的.mark重复计数)应等于库里新增文档数。docs/里出现的每个.xml都对应一篇,没有例外。 - 标题自查。 导入后在主页网格里扫一遍空标题。空标题只有两种来源:文件名不是合法 UTF-8 被整篇跳过(列表里根本看不到),或者 XML 解析失败被
unwrap_or_default()变成白页(能看到但没内容)。第二种情况必须回去用xmllint定位。 - 引用抽样。 随便打开一篇曾被别的文档
@过的笔记,看底部的「反向引用」有没有内容。空的就说明 doc-id 没对上,属于上面说的那类断链。
搬迁这件事的真相是:能批量复制的是文件,需要重建的是关系——时间戳、父子层级、跨文档引用,三者分布在 mtime、index.json 和 doc-id 三个不同的地方,quiet.md 一个都不会替你迁移。把这三处想清楚,剩下的就是几条 cp 和一次 touch。
