ColorOS 便签备份提取工具

把手机「备份与恢复 / 手机搬家」出来的 com.coloros.note（ColorOS 便签）备份，导出成：

• v0.2（默认）Obsidian 仓库：每条笔记一个 .md + 附件目录 + 索引.md MOC 页
• v0.1（兼容）单个 Markdown：全部笔记塞进一个 notes.md

用法

cd ~/Backup

# 默认：自动挑最新备份（Data/<时间戳>/），导出成 vault/
python3 tools/coloros_note_export.py

# 生成 Dataview 视图页 + 首次写 .obsidian/app.json（已有配置不覆盖）
python3 tools/coloros_note_export.py --dataview --obsidian-config

# 重新导出时清理改名/删除留下的孤儿文件（只删本工具产出的）
python3 tools/coloros_note_export.py --dataview --prune

# 其他常用参数
python3 tools/coloros_note_export.py -o ~/便签库        # 指定 vault 位置
python3 tools/coloros_note_export.py --no-attachments   # 不抽附件
python3 tools/coloros_note_export.py --sort title       # 按标题排序
python3 tools/coloros_note_export.py --dry-run          # 只打印统计，不落盘
python3 tools/coloros_note_export.py --format single -o out.md   # v0.1 单文件模式
python3 tools/coloros_note_export.py -b Data/2026-01-01-000000   # 指定某次备份

产物结构（vault 模式）

vault/
  索引.md                    # MOC：统计表 + 最近 20 条 + 按文件夹 + 全部（按年月折叠）
  Dataview 视图.md           # 可选，--dataview 生成，需 Dataview 插件
  笔记/
    2026-11-05 会议纪要 项目排期讨论.md
    ...                      # 每条笔记一个文件，文件名 = 日期前缀 + 净化后的标题
  附件/
    <笔记ID>/<附件ID>_thumb.png
  .coloros-export.json       # 导出清单（--prune 依据，Obsidian 不显示）
  .obsidian/app.json         # 可选，--obsidian-config 生成

每条笔记的 frontmatter：

---
title: 测试笔记
created: 2026-11-05T09:12:00        # 可被 Obsidian Date 属性识别
updated: 2026-11-05T09:20:41
tags: [便签, 有附件]                # 回收站里的会打 #回收站
attachments: 2
source: coloros-note
guid: c77d170b-...
aliases: ["原始标题（含被净化的字符时才有）"]
---

设计取舍：

• 文件名带日期前缀，Obsidian 侧栏按时间天然有序；标题过长截断 40 字，全文在 title 与正文里。
• 扁平 笔记/，不按备份里的文件夹建子目录（备份只有一个「我的收藏」），文件夹写在 frontmatter 的 folder 并在索引页分组。
• 图片用 ![[附件/...]] 嵌入，Obsidian 原生解析；单文件模式才用 ![](...)。
• 不伪造双链：备份里没有笔记之间的关联关系，除了 MOC 页本来就会链接全部笔记（于是在每篇的 backlinks 里能看到「索引」），不额外编造 [[…]]。

备份结构映射

备份里的东西	含义	工具怎么用
Data/<时间戳>/	每次备份一个目录	自动取名字最大的（最新）
Note/rich_note	全部笔记的 JSON 列表，正文在 rawText（HTML）	转 Markdown / 每篇一个文件
Note/folder	文件夹	frontmatter folder + 索引分组
Note/todo、Note/paint_note/	待办 / 手写	只在索引页报数量
Note/encrypt_rich_note	加密笔记（密文）	报数量，不导出
Note/files/file_backup.zip	附件：/files/<笔记ID>/<附件ID>_thumb.png	解到 附件/，正文嵌入
backup_config_new.db	version 表：机型 / ColorOS / Android；EncryptInfo	写进索引页与笔记页脚
Note/data_source_info	包名 / 便签版本 / ROM	同上
Note/share_preference/*	Java 序列化的界面偏好	忽略
.Preview/<时间戳>.preview	备份预览（数字串）	忽略

转换规则（rawText → Markdown）

• <br> → 换行；<div>/<p> → 段落；<head><meta> 粘贴残留丢弃
• <li> → - ，<ol start=n> → 1./2./…
• <img src="<attachmentId>"> → ![[附件/…]]（vault）/ ![图片](attachments/…)（single），缺附件时输出引用块提示
• <a href> → [文字](url)； /& 等实体 unescape
• 正文行首的 #、```、--- 转义成字面文本 —— 便签里这些只是字符，不是 Markdown 结构

校准过的坑

1. 备份目录会被新备份覆盖：手机再备份一次，Data/ 下旧时间戳目录就消失，所以每次自动重新定位最新目录，不写死路径。
2. rawText 是 HTML，text 不是等价纯文本（实测数百条里两者全不相同，text 更短、会丢内容），优先 rawText。
3. <img src> 就是 attachmentId，zip 里按 /files/<笔记ID>/<附件ID>_thumb.png 存放；手机备份只带缩略图（原图需另取）。
4. 标题可能来自正文回退：summaryTitle 为空的笔记，若正文第一行是图片，早期版本会把 ![[附件/…]] 当标题 → 现在回退时先剥掉图片/嵌入语法。
5. 标题里带引号（如 "下载"目录）会破坏单文件模式的 <a id="…"> 锚点 → slug 用字符黑名单剔除。
6. wikilink 别名不能含 | [ ]，索引页里统一净化，否则链接会断。
7. --prune 的三条判据：上一版清单差集、笔记/ 下带 source: coloros-note 但不在本次输出的文件、附件/ 下不在清单里的文件 —— 绝不碰用户自己写的笔记。
8. 只读打开 sqlite 要用 immutable=1，否则会往备份目录写 -wal/-shm，污染原始备份。

版本

• v0.2：Obsidian 仓库模式（默认）、索引 MOC、Dataview 视图、.obsidian 配置、--prune 清单清理；单文件模式保留为 --format single。
• v0.1：单个 notes.md + attachments/。

隐私

• 全程离线：只用标准库读写本地备份目录，不联网、不上传任何内容。
• 不打印笔记正文；.coloros-export.json 只记录文件名与附件路径。
• 手机备份里的加密笔记是密文，工具无法也不尝试解密。

许可

MIT