我把为知笔记迁移过程做成了一个 Windows 一键程序

它解决什么问题

旧版为知笔记的数据不只是正文。网页剪藏通常包含大量图片、CSS 背景、按钮、图标和附件；有道云笔记又区分原生笔记与网页剪藏，不能把 Markdown 源码直接塞进编辑器里。

一键程序把流程拆成几个明确阶段：

1. 检查为知笔记是否已经完整离线下载。
2. 从本地 index.db 和 .ziw 导出 Markdown。
3. 删除正文未引用的网站外壳资源。
4. 按 75% 质量压缩需要保留的图片。
5. 使用官方 YoudaoNote CLI 创建原生笔记或网页剪藏。
6. 自动建立“为知笔记 / 原顶级目录”的两级结构。
7. 对每条笔记显式执行目录移动。
8. 最后重新分页读取云端，根据 fileId 逐项对账。

为什么不能只看“创建成功”

实际迁移中遇到过一个很隐蔽的问题：CLI 返回了 fileId，并不代表笔记已经位于目标文件夹。某些原生笔记创建成功后，目录参数没有按预期生效。

因此程序不依赖创建接口中的目录参数。每条笔记创建后都会额外执行一次 move，全部导入完成后再读取云端目录。如果检查点中的 fileId 不在预期目录，程序会自动补充移动。

这一步是整个程序最重要的保险。它避免了“脚本显示 5000 条成功，客户端文件夹却只有 3000 多条”的假完成状态。

图片压缩策略

程序默认使用 75% 质量，并按格式选择合适的编码器：

• PNG：pngquant
• JPEG：mozjpeg
• GIF：gifsicle
• WebP：cwebp

如果单篇笔记的图片总量仍然超过官方接口能够接受的范围，程序会继续限制长边尺寸。超大 GIF 可以转换为 75% 质量的动态 WebP。

如果官方接口经过重试仍拒绝整篇图片请求，程序不会让整条笔记消失，而是降级保存可读正文，并明确提示图片仍完整保存在本地 Markdown 导出目录。所有降级情况都会进入最终报告。

支持暂停和断点续传

几千条笔记的迁移可能持续数小时，程序不会把“完整运行一次”当作前提。

每成功处理一条笔记，就立即把 fileId、目标目录和完成时间写入检查点。按 Ctrl+C 时，程序会在当前单条操作结束后暂停。再次双击启动器，会跳过已经完成的笔记继续运行。

检查点覆盖以下阶段：

• Markdown 导出
• 有道目录创建
• 笔记创建与图片上传
• 补充移动
• 最终验证

防止重复导入

默认情况下，如果有道云笔记里已经存在非空的同名根目录，程序会直接停止，而不是继续创建副本。

只有明确传入复用参数时，程序才会使用已有目录。即使选择复用，最终报告也会区分本次迁移的正确 fileId 与目录中原有的其他内容，不会按标题猜测或自动删除用户已有笔记。

企业微信进度通知

长任务还支持企业微信机器人通知。通知模块是一个独立工具，Webhook 只保存在用户级私密配置中，不会写入迁移项目和日志。

默认通知规则是：

• 每增加 100 个操作推送一次；
• 或每 5 分钟推送一次；
• 暂停、异常和完成时强制推送；
• 守护程序发现任务退出时，自动从检查点重启并通知。

Windows 下怎么使用

项目提供一个双击启动器：

一键迁移.cmd

首次使用有道官方 CLI 时，按照提示完成一次配置即可。以后双击启动器就会自动检测数据源和已有检查点。

也可以只做只读检查：

node src/one-click.js --dry-run

只读检查不会创建云端目录或笔记。

当前验证结果

程序已经完成以下验证：

• 6 个核心单元测试全部通过；
• 使用一条真实为知笔记完成 Markdown 导出测试；
• 自动识别到完整的 5009 条恢复数据；
• 5009/5009 笔记和 325/325 附件通过完整性预检；
• 官方 YoudaoNote CLI 连接和云端只读列表验证成功；
• 源码扫描未发现博客密码或企业微信密钥泄漏。

因为当前有道账号已经完成迁移，所以没有再次执行全量云端测试。程序检测到目标目录非空时会主动停止，这正是防重复机制应该有的表现。

最后

“一键”不是把所有命令塞进一个批处理文件，而是把迁移中的失败方式都变成程序可以识别和恢复的状态。

真正可靠的一键迁移，至少要做到：源数据完整、输出可长期保存、云端创建可恢复、目录位置可验证、重复执行不会破坏已有结果。这个程序的目标就是把这些约束变成默认行为，而不是依赖操作者每一步都不出错。