有道云笔记 → ima 笔记 完整迁移技能

将有道云笔记完整迁移到 ima 笔记模块，包括笔记内容和内嵌图片。核心思路是：
导出 → 转格式 → 清理 → 下载远程图 → base64 嵌入 → 导入 ima 笔记。

base64 嵌入是关键——ima 导入 md 后会将文件打散为独立条目，相对路径的图片引用会断链。
把图片编码为 data:image/png;base64,... 内联到 md 中，文件自包含，导入后图片直接显示。

执行指引（给 AI Agent）

本技能有 2 个步骤需要人工操作（Step 1 获取 4 个 cookie + 设置导出目录、Step 7 导入 ima），5 个步骤是脚本自动执行。
执行时遵循以下原则：

1. 先告知全流程：开始前向用户概述 7 个步骤，说明哪些需要人工、哪些自动，让用户有预期
2. 人工步骤主动提醒：遇到人工步骤时，给出详细的分步操作指引（下方已写明），等用户完成后确认再继续
3. 自动步骤直接执行：脚本步骤直接运行，执行完展示结果摘要
4. 每步完成后汇报：每完成一步，简要说一句结果（处理了多少文件、有无异常），再进入下一步

前置条件

• Python 3.10+，需安装 markdownify、requests：
  bash pip install markdownify requests
• youdaonote-pull（GitHub: DeppWang/youdaonote-pull）：有道云笔记批量导出工具

完整流程（7 步）

Step 1: 导出有道云笔记【人工 + 自动】

此步骤分两部分：用户手动获取 cookie（人工），然后运行导出脚本（自动）。

1a. 人工获取 cookie + 设置导出目录（提醒用户操作）

向用户给出以下操作指引，等用户完成并确认后再执行 1b：

> 请先告诉我你想把笔记导出到哪个目录？（例如 D:\WorkBuddy\有道云笔记导出）
>
> 然后按以下步骤获取有道云笔记的 cookie：
>
> 1. 用 Chrome/Edge 浏览器打开 https://note.youdao.com 并登录你的有道云笔记账号
> 2. 登录成功后，按 F12 打开开发者工具
> 3. 切换到 Application（应用）标签页 → 左侧展开 Cookies → 点击 https://note.youdao.com
> 4. 在 cookie 列表中找到以下 4 个值，逐个双击 Value 列复制：
>
> | Cookie 名称 | 用途 |
> |-------------|------|
> | YNOTE_CSTK | youdaonote-pull 导出认证 |
> | YNOTE_LOGIN | youdaonote-pull 导出认证 |
> | YNOTE_SESS | youdaonote-pull 导出认证 |
> | NTES_YD_SESS | 下载远程图片认证（Step 5 用） |
>
> 5. 把导出目录路径和这 4 个 cookie 值发给我，我来帮你配置并运行导出

注意事项提醒用户：
- cookie 有时效性，获取后尽快使用（一般几小时到一天内有效）
- NTES_YD_SESS 容易被忽略，但它对后续下载远程图片至关重要，务必一起复制
- 如果 cookie 列表里看不到 NTES_YD_SESS，尝试在笔记中打开一篇含图片的笔记后再刷新
- 如果找不到某个值，尝试在笔记中随便打开一篇笔记后再刷新页面

1b. 配置并运行 youdaonote-pull（自动）

收到用户的导出目录路径和 4 个 cookie 值后，配置 youdaonote-pull 的 config.json：

{
  "local_dir": "<用户指定的导出目录绝对路径>",
  "ydnote_dir": "",
  "smms_secret": "",
  "cookies": {
    "YNOTE_CSTK": "<用户提供的值>",
    "YNOTE_LOGIN": "<用户提供的值>",
    "YNOTE_SESS": "<用户提供的值>"
  }
}

同时创建 cookies.json（供 Step 5 下载远程图片使用，包含全部 4 个 cookie）：

{
  "cookies": [
    ["YNOTE_CSTK", "<用户提供的值>", "note.youdao.com", "/"],
    ["YNOTE_LOGIN", "<用户提供的值>", "note.youdao.com", "/"],
    ["YNOTE_SESS", "<用户提供的值>", "note.youdao.com", "/"],
    ["NTES_YD_SESS", "<用户提供的值>", "note.youdao.com", "/"]
  ]
}

然后运行导出：

python pull.py

导出后的目录结构：

导出目录/
├── 分类文件夹/
│   ├── 笔记标题.note    ← 有道云原生格式（实际是 HTML）
│   ├── 笔记标题.md      ← pull 工具已转换的（部分）
│   ├── images/
│   │   └── HEX32前缀_图片名.png   ← 附件图片带 32 位 HEX 前缀
│   └── attachments/
│       └── HEX32前缀_文件名.pdf   ← 附件也带前缀

Step 2: 转换 .note 为 .md

有道云的 .note 文件本质是 HTML，ima 无法识别。用 scripts/convert_note_to_md.py 转换：

python scripts/convert_note_to_md.py "导出目录绝对路径"

• 使用 markdownify 库将 HTML 转为 Markdown
• 已有 .md 的会跳过，不会重复转换
• 空内容笔记会添加占位文本

Step 3: 清理文件名（去 HEX 前缀 + 修空格）

有道云导出的附件/图片文件名带有 32 位 HEX 前缀（如 a1b2c3d4e5f6...设计图.png），
需要去除并同步更新 md 中的引用。

去 HEX 前缀（含重名冲突处理 + md 引用同步更新）：

python scripts/rename_files_v2.py "导出目录绝对路径"

• 自动检测 images/ 和 attachments/ 目录下的 HEX 前缀文件
• 重名冲突自动加 _1、_2 后缀
• 同步更新所有 .md 文件中的引用路径

修空格文件名（空格会导致 ima 渲染断链）：

python scripts/fix_spaces.py "导出目录绝对路径"

• 将文件名中的空格替换为下划线
• 同步更新 .md 引用

Step 4: 校验引用完整性

python scripts/check_refs.py "导出目录绝对路径"

• 扫描所有 .md 的 images/ 和 attachments/ 引用
• 检查引用文件是否实际存在
• 检测 URL 编码残留（如 %20）
• 输出断链列表，根据报告手动修复

Step 5: 下载有道云远程图片【自动】

部分笔记中的图片存储在有道云服务器上（URL 格式 https://note.youdao.com/yws/res/...），
需要下载到本地。这一步必须在 base64 嵌入之前完成。

cookie 已在 Step 1 一次性获取，cookies.json 已在 Step 1b 创建好，直接运行：

python scripts/download_remote_images.py "导出目录绝对路径" "cookies.json路径"

• 扫描所有 md 中的 note.youdao.com 远程图片 URL
• 用 cookies 认证下载，保存到对应目录的 images/ 下
• 自动嗅探图片格式（PNG/JPG/GIF/BMP/WEBP）
• 下载后将 md 中的远程 URL 替换为本地 images/ 引用
• 输出 remote_dl_results.json 记录成功/失败

常见问题：
- 返回 500 / 登录页 → NTES_YD_SESS cookie 缺失或过期，需重新获取
- 部分历史图片无法下载 → 可能是 Confluence 迁移遗留，服务端已无源文件，可放弃

Step 6: Base64 嵌入所有图片

这是让 md 文件"自包含"的关键步骤。将 md 引用的所有本地图片编码为 base64 data URI，
直接内联到 md 文本中。嵌入后 md 不再依赖外部图片文件。

python scripts/embed_all_images.py "导出目录绝对路径"

• 扫描所有 ](images/ 引用，将图片读取为二进制 → base64 编码 → 替换为 data:image/xxx;base64,...
• 嵌入前自动创建 .noembed.bak 备份（原始 md 保留）
• 支持常见格式：PNG、JPG、GIF、BMP、WEBP
• 输出统计：嵌入文件数、图片总数、原始图片总大小、缺失文件列表

验证：嵌入完成后，用本地 Markdown 编辑器打开任意 md，确认图片正常显示。

Step 7: 批量导入 ima 笔记【人工】

此步骤需要用户在 ima 客户端手动操作。向用户给出以下详细指引：

7a. 提醒用户先建文件夹

> 请先在 ima 笔记中建好对应文件夹：
>
> 打开 ima → 左侧切换到「笔记」模块 → 按导出的目录结构新建文件夹，例如：
> - 目录1/文件1
> - 目录2/文件2
> - 目录3/文件3
> - ...（根据实际目录结构）
>
> 建好后告诉我，我给你分批导入的清单。

7b. 生成分批导入清单（自动）

根据导出目录的 md 文件数量，自动生成分批清单（每批 ≤ 100 个文件），以表格形式展示给用户：

> 请按以下分批导入，每批操作方式相同：
>
> | 批次 | 目录 | 文件数 |
> |------|------|--------|
> | 1 | xxx | N |
> | 2 | xxx | N |
> | ... | ... | ... |
>
> 每批操作步骤：
> 1. 在 ima 笔记中进入对应文件夹
> 2. 点击「新建笔记」旁的 下拉箭头 → 「导入」→「导入 Markdown 文件」
> 3. 在文件选择窗口中，定位到导出目录的对应子文件夹
> 4. Ctrl+A 全选 该文件夹下的所有 .md 文件 → 点击打开
> 5. 等待导入完成，确认笔记数量和图片显示正常
> 6. 进入下一个文件夹，重复以上步骤

7c. 导入后验证提醒

> 导入完成后请检查：
> - 随机打开 2-3 篇笔记，确认图片正常显示
> - 确认笔记可以编辑（点击编辑按钮，能进入编辑状态）
> - 如果图片不显示，检查是否导入到了「知识库」而非「笔记」——知识库条目只读，需转成笔记

注意事项提醒用户：
- 导入到「笔记」而非「知识库」——知识库条目只读，需逐篇转成笔记才能编辑
- 单次最多 100 个 md 文件，单文件 ≤ 10MB
- base64 嵌入的 md 导入后图片直接显示，无需额外上传图片
- 如果 md 文件超过 10MB（大量 base64 图片），需要在导入前拆分或压缩图片

备份文件清理

embed_all_images.py 会生成 .noembed.bak 备份文件。确认嵌入无误后可移至独立目录：

# 创建备份目录
mkdir -p "导出目录/md_backup"

# 移动所有 .bak 文件（保留原目录结构）
find "导出目录" -name "*.noembed.bak" -exec sh -c '
  dest="导出目录/md_backup/$(dirname "{}" | sed "s|导出目录/||")"
  mkdir -p "$dest"
  mv "{}" "$dest/"
' \;

脚本执行顺序总结

Step 1: 【人工】设置导出目录 + 获取 4 个 cookie → 【自动】配置 + pull.py 导出
Step 2: 【自动】convert_note_to_md.py <ROOT>     # .note → .md
Step 3: 【自动】rename_files_v2.py <ROOT>        # 去 HEX 前缀
        【自动】fix_spaces.py <ROOT>             # 修空格
Step 4: 【自动】check_refs.py <ROOT>             # 校验引用
Step 5: 【自动】download_remote_images.py <ROOT> <cookies>  # 下载远程图片（cookie 已在 Step 1 获取）
Step 6: 【自动】embed_all_images.py <ROOT>       # base64 嵌入
Step 7: 【人工】按分批清单导入 ima 笔记（≤100 个/批）

脚本说明

所有脚本均接受命令行参数 <ROOT>（导出目录绝对路径），便于复用。
download_remote_images.py 额外接受 <cookies_path> 参数。