AI工具的另一个用途:轻松将OneNote笔记转到Obsidian

把多年积累的 OneNote 笔记迁移到 Obsidian，常见的问题集中在几个地方：父页面与子页面被打散，图片导入后无法显示，附件混在一起，同名笔记互相覆盖，正文前还多了一大段不需要的属性。

围绕这些问题，我们在一批实际笔记的迁移中逐步确定了一套AI智能体的转换规则：一个页面对应一个 Markdown 文件；有子页面就创建同名文件夹；图片和附件使用相对路径；笔记正文不添加 YAML 属性。

下面把这套规则完整说明，供有同类迁移需求的读者参考。

一个 .one 文件通常对应一个分区，其中可能包含多个页面。转换时，要先识别分区中的页面及其关系，再分别生成 Markdown。

基本映射如下：

能够可靠取得笔记本名称时，可以保留这一层目录；只有独立分区文件、无法确定笔记本来源时，就保留已知结构，不补造笔记本名称。

默认转换最新页面快照，历史版本不混入当前笔记。需要保留历史记录时，应另行归档。

父子页面关系直接体现在文件夹中。

例如，“儿童评测小程序”下面有一个子页面“反馈”，转换后的结构为：

父页面自己的正文保存在“儿童评测小程序。md”中，子页面“反馈。md”与它放在同一个文件夹里。

如果“反馈”下面还有子页面，就继续递归建立文件夹：

具体遵循三条规则：

父子关系依据源文件中的结构和页面标识恢复，不根据标题相似度猜测。

每篇 Markdown 直接从原文正文开始，不添加 title、aliases、tags、source、parent、创建时间或修改时间等 YAML 属性。

页面标题用作文件名，默认不在正文开头额外重复插入一个 H1 标题。原文本来就有的正文标题则正常保留。

来源信息仍需保留，但统一放到转换报告中。

报告记录原始页面 ID、来源分区、父子关系、取得的原始时间，以及页面 ID 与输出路径之间的映射。这样，日常阅读时只看到正文，后续核对时也能找到来源。

原文中本来就存在的代码、配置和 YAML 示例不属于“新增属性”，应照原文保留。

图片目录采用下面的组织方式：

不同笔记各有自己的附件子目录，即使都使用 image-001.png，也不会因为重名而覆盖。

图片在正文中的引用使用标准 Markdown 相对路径：

这里的 ./ 表示“当前 Markdown 文件所在的目录”。尖括号用于包住路径，减少空格等字符造成的解析歧义。

本次采用的目录名是 assets，写法是 ./assets/。它与名为 .assets 的隐藏目录不同。

复杂 HTML 表格中的图片，使用相对路径作为 img 的 src；普通正文图片使用 Markdown 图片语法。

调整父子页面目录后，必须以笔记的新位置重新计算路径。只移动 Markdown、保留旧引用，会造成图片失联。日后移动一组笔记时，也应一起移动对应的 assets 目录。

能够提取的 PDF、文本、Office 文档以及其他嵌入文件，都保存到本地，并在正文原位置建立链接。例如：

命名和存放遵循以下规则：

图片还要检查实际格式。原始文件名标成 PNG，文件内容却可能是 TIFF；扩展名需要与实际格式一致。

对于本次遇到的 TIFF、BMP 等图片，保留原始文件，并另生成 PNG 预览供阅读使用。多页图片如果只生成首帧预览，需要在报告中说明，原文件仍完整保留。

页面标题优先用于文件名，但需要清理路径分隔符、控制字符和可能造成链接歧义的字符，并控制名称长度。

同一目录中存在同名页面时，可以追加原始页面 ID 的短后缀，例如：

处理冲突时，也要考虑大小写和字符规范化差异，避免文件在不同系统之间移动后发生碰撞。

图片、附件和父页面文件夹同样需要检查名称冲突。文件名因兼容性要求发生变化时，应在报告中保留映射；正文内容不随文件名一起改写。

转换时保留原文，不自动润色、扩写、总结，也不根据正文猜测标签。

常规内容按以下方式处理：

OneNote 的自由布局还需要单独处理。多个文本容器、浮动图片和并排内容，在转换为线性正文时应尽量保持阅读顺序。无法可靠判断顺序，或字体、颜色、位置无法等效保留时，需要记录限制。

跨页面链接不能只看标题。不同分区里可能都有“反馈”“会议记录”或“开发计划”。

处理时先建立页面索引：

目标能够唯一确定时，再生成指向实际文件的内部链接；页面被移动到新文件夹后，相关链接也要同步更新。

正文图片统一采用相对路径。页面之间的内部链接可以保留 Wiki 链接，但同名页面必须用路径明确区分。

外部网页链接继续保留。对于已删除页面、未提供的分区或无法确定目标的 OneNote 链接，保留原始地址并写入待检查清单，不生成猜测出来的目标。

本次采用的是已经确认的 ./assets/笔记名/ 规则，没有读取目标 Vault 中 Custom Attachment Location 的实际配置。

因此，当前交付说明的是“转换包采用了什么目录规则”，不能据此声称已经与某个现有 Vault 的插件设置完全一致。

后续需要适配插件时，应核对实际生效的附件目录、命名和移动规则，再调整输出或插件设置。不能仅凭安装了插件，就假定它正在使用某个路径模板。

转换过程不直接修改现有 Vault，先生成完整的新目录：

报告中的原始结构、页面映射、附件哈希及问题清单，与正式笔记分开保存，不必全部导入 Vault。

重复转换时，使用页面 ID、来源和文件哈希识别对应内容。当前做法是在独立目录重新生成新版，再检查差异；不把自动合并用户编辑内容当作已经具备的能力。

如果已经导入过旧版，应先检查旧笔记是否有个人修改，再安排替换。旧版和新版同时导入同一 Vault，容易产生重复笔记。

验收至少包括以下检查：

文件引用通过检查，与所有内容完全保真，是两项不同的结论。

下面这份提示词已合并我们最终确认的全部规则，可以直接复制使用。

请将指定目录中的 OneNote .one 文件转换为可直接导入 Obsidian 的完整文件包。请实际完成转换、验证和打包，不要只提供方案或示例。

未指定文件时，默认递归处理当前工作目录中的全部原始 .one 文件，排除工具目录、临时目录和以前生成的转换结果。以下规则以最终输出要求为准。

一、基本要求

1. 一个 OneNote 页面对应一个独立的 Markdown 文件，不把整个分区合并成一篇笔记。
2. 保留已知的原始目录、分区组、分区及页面关系。
3. 默认转换最新页面快照，历史版本不混入当前正文。
4. 保留原文，不擅自润色、扩写、总结、翻译、删减或推断标签。
5. 不修改原始 .one 文件，不直接修改现有 Obsidian Vault。
6. 图片和附件必须尽可能提取到本地，不能只留下指向临时目录的引用。
7. 无法解析或无法准确还原的内容，必须记录到转换报告中，不静默丢弃，不把失败计为成功。
8. 优先在本地完成处理。未经明确授权，不向第三方服务上传笔记、图片或附件；不要在日志和回复中展示笔记里的密钥等敏感内容。

二、目录结构：父子页面递归归组

依据源文件中的页面 ID 和真实父子关系组织目录，不根据标题相似度猜测关系。

具体规则：

• 没有父页面、也没有子页面的独立页面，放在所属分区目录中。
• 有子页面的页面，创建与该页面同名的文件夹。
• 父页面自己的 Markdown 放入这个文件夹。
• 子页面的 Markdown 也放入父页面文件夹。
• 如果子页面还有下一级页面，继续递归创建同名子文件夹。
• 每篇笔记的图片和附件放在该 Markdown 所在目录的 assets/笔记文件名/ 下，笔记文件名不包含 .md 扩展名。

例如，“儿童评测小程序”包含子页面“反馈”，应转换为：

产品开发/└── 儿童评测小程序/    ├── 儿童评测小程序.md    ├── 反馈.md    └── assets/        ├── 儿童评测小程序/        │   └── image-001.png        └── 反馈/            └── image-001.png

如果“反馈”还有子页面“第一轮反馈”，应转换为：

产品开发/└── 儿童评测小程序/    ├── 儿童评测小程序.md    ├── 反馈/    │   ├── 反馈.md    │   ├── 第一轮反馈.md    │   └── assets/    │       ├── 反馈/    │       └── 第一轮反馈/    └── assets/        └── 儿童评测小程序/

只能从独立分区文件取得部分来源结构时，保留能够确认的层级，不虚构笔记本名称。

三、笔记不添加任何 YAML 属性

所有生成的 Markdown 笔记直接从原文正文开始，不添加 YAML Front Matter，包括但不限于：

• title
• aliases
• tags
• source
• notebook
• section
• onenote_page_id
• onenote_page_level
• parent
• created
• modified

页面标题优先用作文件名，默认不额外在正文开头重复插入 H1 标题。原文本来存在的正文标题应保留。

原始页面 ID、创建时间、修改时间、父子关系和来源路径统一保存在独立转换报告中。

注意：原文中的 YAML 示例、代码、配置和分隔线属于正文，不得误删。

四、图片全部使用相对路径

普通正文图片使用标准 Markdown 图片语法，不使用 Wiki 图片嵌入，不使用绝对磁盘路径，也不使用依赖 Vault 根目录的图片路径。

示例：

![图片说明](<./assets/反馈/image-001.png>)

要求：

1. 路径相对于引用它的 Markdown 文件。
2. 目录名使用 assets，完整写法是 ./assets/；除非另有要求，不改成 .assets/。
3. 使用 / 作为路径分隔符。
4. 路径包含空格等字符时，使用有效的 Markdown 路径写法，例如用尖括号包住目标路径。
5. 有原始图片说明时尽量保留，不凭空编写说明。
6. 复杂 HTML 表格中的图片，可以使用 HTML img，但 src 同样必须是相对于当前 Markdown 的路径。
7. 目录重组后，重新计算并检查所有图片引用，不能只移动文件而保留旧路径。

五、附件提取、命名与图片格式

能够提取的 PDF、文本、Office 文档、音视频及其他嵌入文件，应保存为本地附件，并在原文对应位置建立相对链接。

例如：

[需求说明](<./assets/反馈/需求说明.pdf>)

命名规则：

• 尽量保留有意义的原始文件名。
• 无意义的随机名称，可以改为 image-001.png、attachment-001.pdf 等顺序名称。
• 同一笔记内的附件名称必须唯一。
• 不同内容的同名文件不得覆盖。
• 同一笔记内完全相同的附件，可以通过文件哈希识别并复用。
• 不强制跨笔记合并附件，以便每组笔记可以独立移动。

图片格式要求：

• 根据文件实际内容核验格式，不能只相信原始扩展名。
• 扩展名与实际格式不一致时，修正扩展名并同步更新引用。
• 对需要兼容预览的 TIFF、BMP 等图片，保留原始文件，并生成 PNG 预览供正文显示。
• 多页图片如果只显示首帧预览，必须在报告中说明，原文件完整保留。
• 图片转换或预览失败时保留原件并报告，不生成损坏的占位图片。

六、文件名与冲突处理

页面文件名和分组文件夹尽量保留原标题，同时处理非法字符、路径分隔符、控制字符、链接歧义字符和名称长度限制。

还需考虑大小写及 Unicode 规范化造成的跨系统冲突。

同一目标目录存在同名页面时，可追加原始页面 ID 的短后缀，例如：

AI Agent.mdAI Agent--95579DEB.md

确定最终目录结构后再处理冲突，不因其他目录存在同名页面就无必要地追加后缀。

图片、附件和文件夹也要检查冲突。所有名称变更和处理结果记录在报告中。

七、正文与排版

在不改变原意和信息顺序的前提下：

• 标题转换为对应层级的 Markdown 标题。
• 保留粗体、斜体、删除线和高亮。
• 保留有序列表、无序列表及嵌套关系。
• 待办状态只有在能够可靠识别时才转换，不猜测完成状态。
• 代码使用围栏代码块，连续代码段尽量合并，不猜测编程语言。
• 简单表格优先使用 Markdown；复杂表格必要时使用 HTML，并检查其中的图片和链接。
• 数学公式只有在能够可靠识别时才转换为公式语法，不能根据截图猜写。
• 手写内容优先保留可提取图像，OCR 仅作为明确启用后的可选步骤。
• 音视频能提取时建立本地文件引用，无法提取时记录原因。

对于多个文本容器、浮动图片和并排内容，尽量保持原始阅读顺序。无法确定顺序，或字体、颜色、绝对位置无法等效保留时，在报告中说明。

空白页面仍保留独立 Markdown 文件，不自行填入说明性正文。

八、内部页面链接

先为全部输入分区建立完整页面索引：

来源分区 + 原始页面 ID → 最终 Markdown 路径

再统一处理跨页面、跨分区链接。

• 目标能够唯一确定时，转换为指向实际文件的内部链接。
• 页面链接可以使用 Obsidian Wiki 语法，同名页面用路径区分。
• 文件夹重组后同步更新相关链接。
• 能可靠映射页面内锚点时才保留对应跳转，无法保留时报告。
• 外部网页链接保留原地址。
• 无法确定目标的 OneNote 链接，保留原始地址并记录，不根据标题生成猜测链接。

图片和普通附件仍按照前述规则使用相对路径。

九、插件兼容

默认采用本提示词确认的 ./assets/笔记文件名/ 规则。

如果提供了目标 Vault 的附件插件配置，先检查它与本规则是否一致，并说明差异；未经明确要求，不修改插件配置，也不擅自改变已经确认的输出规则。

没有读取和验证实际插件配置时，不声称已经完全适配该插件。

十、安全导入与重复转换

• 在独立输出目录生成完整结果，再进行验证和打包。
• 不覆盖现有 Vault 中的文件。
• 不覆盖用户已经编辑过的 Markdown。
• 使用来源、原始页面 ID 和文件哈希建立稳定映射，检查重复与冲突。
• 再次转换时，生成独立新版或采用明确验证过的更新策略，不直接向旧目录追加出一套重复笔记。
• 未实现可靠的增量更新或用户修改合并时，明确说明，不把重新导出描述成自动同步。

如果已有上一次转换结果，应优先依据报告中的页面映射重新组织目录，避免无必要地改写已经确认的正文。

十一、转换报告

报告独立于正式笔记，至少包含：

1. 输入文件列表、原始路径和文件哈希。
2. 各分区的页面数量、成功数量及失败数量。
3. 页面 ID、来源、原始层级、父子关系与最终路径映射。
4. 能够取得的原始创建和修改时间，不伪造缺失时间。
5. 图片、附件和预览文件数量，以及附件哈希。
6. 文件命名冲突、名称变更及处理记录。
7. 内部链接成功转换数量与未解决清单。
8. 无法解析、无法还原或可能损失的信息。
9. 自由布局、复杂表格、多页图片等需要人工抽查的页面。
10. 本地引用、图片格式、正文覆盖及压缩包完整性检查结果。

报告中的问题应能定位到来源分区和页面 ID。

十二、交付前验证

请实际执行检查，并区分“文件和引用有效”与“内容完全保真”：

• 每个输入分区均有明确处理结果。
• 每个可解析页面均有对应 Markdown，没有未说明的漏页。
• 所有父子页面按递归文件夹规则归组。
• 没有新增 YAML 属性，没有擅自插入正文或改写原文。
• 图片全部使用有效相对路径，没有 Wiki 图片嵌入或绝对磁盘路径。
• 本地图片、附件和已转换页面链接均能找到目标文件。
• 原图和预览能够解码，图片格式与扩展名一致。
• 导出附件与提取原件的哈希一致。
• 源 .one 文件未被修改。
• 目录重组前后，除必要的引用目标变更外，正文和附件内容保持一致。
• ZIP 压缩包通过完整性检查。

文本片段数量一致、附件数量一致或渲染成功，都不能单独作为“原始 OneNote 已完全无损转换”的证明。没有进行逐页视觉比对时，应如实说明。

十三、最终交付

交付一个完整 ZIP，结构清晰，例如：

OneNote-Obsidian/├── Vault/│   └── OneNote 导入/│       └── 来源目录、分区和父子页面文件夹├── 转换报告/│   ├── 转换报告.md│   ├── manifest.json│   └── validation.json└── 使用说明.md

如需保留源结构 JSON、原始页面索引或更多校验记录，将它们放在转换报告目录中，不混入正式笔记正文。

使用说明应交代：

• 如何将 Vault 作为独立 Obsidian 库打开。
• 如何将笔记复制到现有 Vault。
• 如何一起移动笔记文件夹及附件。
• 已导入旧版时如何避免重复和覆盖个人修改。

最后简要返回：

• ZIP 下载链接。
• 实际转换的分区数和页面数。
• 父页面分组文件夹数量。
• 图片、附件及兼容预览数量。
• 已通过的验证项目。
• 尚未解决的问题和需要人工抽查的内容。

请根据实际文件动态统计，不沿用示例中的数量；遇到局部失败时继续完成能够安全处理的部分，并在报告和最终回复中明确列出未完成内容。