微信读书笔记 → IMA 笔记流水线（通用版）
Overview
把微信读书书籍的笔记（划线、想法/书评）抓取下来，整理成带多级目录、锚点链接、想法对应原文的 Markdown，写入 IMA 笔记本，并可同步加入 IMA 知识库。整条流水线已封装在 scripts/pipeline.py，支持分步执行或一键完成。
本 skill 不写死任何个性化信息：所有凭证走环境变量，所有 ID（笔记本 folder_id、知识库 kb_id）通过参数传入或按名字动态查找，笔记本/知识库名称均为可被覆盖的参数默认值，可直接发布到 skillhub 供任意用户使用。
When to use
- 用户说"把《XXX》的笔记整理/导出到 IMA"、"把这本书的划线想法写成笔记"、"写入某个笔记本"
- 用户说"把这篇笔记加入知识库"
- 意图对象同时涉及「微信读书笔记」与「IMA 笔记/知识库」的跨系统搬运
Prerequisites（凭证配置，用户自行提供）
| 系统 | 环境变量 | 回退文件（跨平台 ~ 即用户主目录） |
|---|---|---|
| 微信读书 | WEREAD_API_KEY（格式 wrk-xxxx） |
~/.config/weread/api_key |
| IMA | IMA_OPENAPI_CLIENTID / IMA_OPENAPI_APIKEY |
~/.config/ima/client_id + api_key |
若未配置，脚本会明确报错并提示如何设置，再调用任何 API。不要在 skill 内写死 key 或路径。
目标笔记本 / 知识库（参数化，不写死）
- 笔记本：用
--folder-id <ID>显式传入；或传--notebook-name <名称>由list_notebook按名查找（默认示例名读书笔记，请替换为用户自己的笔记本名）。 - 知识库：用
--kb-id <ID>显式传入（最稳妥）；或传--kb-name <名称>由search_knowledge_base+get_addable_knowledge_base_list合并查找（默认示例名阅读笔记）。 - 若按名查找失败，脚本会报错并提示用户复制真实 ID 用
--folder-id/--kb-id传入。个人自建知识库可能不在可搜索/可添加列表中，因此显式传 ID 是最可靠的方式。
Workflow
scripts/pipeline.py 提供子命令，可分步也可 all 一键串联。中间产物（chapters.json / bookmarks.json / reviews.json / notes.md / *_result.json）默认写在 --work-dir（默认当前目录，可用参数改到任意目录）。
Step 1 — 解析 bookId（书名 → bookId）：仅从书架查找，不联网搜索
若用户只给了书名，用 /shelf/sync 在用户书架里按书名匹配 bookId；已有 bookId 则跳过。
> 为什么不用 /store/search（用户明确要求）：搜索是全网检索，同名的书成堆（《第一性原理》能搜出 8 本），
> 且搜索返回的 bookId 未必是用户真正划线那本——实测《技术革命与金融资本》搜索返回数字版 3300197961（0 划线），
> 而书架里的 CB_DX20LU0MsFdy73K71GDnu5y4 才有 58 划线。书架里装的才是用户实际阅读的副本，
> 未读过的同名干扰书不会出现在书架上，因此只查书架可同时解决"同名泛滥"和"划线挂错版本"两个问题。
find_in_shelf() 的行为：
- 书架命中唯一一条 → 直接用它。
- 命中多条 → 逐个调 /book/bookmarklist 比对划线数，取划线最多的那条副本（规避"数字版 vs CB_ 出品版"）。
- 全部候选与划线数会写入 shelf_match.json，便于人工复核。
- 书架查不到 → 明确报错，提示确认该书在书架中或用 --book-id 显式传入。不要改用网络搜索兜底。
Step 2 — 抓取数据（fetch）
python scripts/pipeline.py fetch --book-id <BOOK_ID> [--book-title "<书名>"] [--work-dir DIR]
调用微信读书 Agent Gateway（https://i.weread.qq.com/api/agent/gateway，Header Authorization: Bearer $WEREAD_API_KEY）：
- /book/chapterinfo → 多级目录（含 level / parentUid / chapterUid，必须用此接口取目录层级，不要用 /book/bookmarklist 的扁平 chapters）
- /book/bookmarklist → 划线（markText / range / chapterUid）
- /review/list/mine → 想法（review 对象内嵌在 reviews[].review，含 content / range / chapterUid；chapterUid=0 表示书评级）
Step 3 — 整理为 Markdown（build）
python scripts/pipeline.py build --book-title "<书名>" [--work-dir DIR]
按下方「格式规范」生成 notes.md。
Step 4 — 写入 IMA 笔记本（write）
python scripts/pipeline.py write \
--folder-id <FOLDER_ID> [--notebook-name "<笔记本名>"] \
--note-title "<笔记标题>" [--work-dir DIR]
调用 POST https://ima.qq.com/openapi/note/v1/import_doc，body {"content_format":1, "content":<md>, "folder_id":<笔记本id>}。返回 note_id。
Step 5 — 加入知识库（可选，kb）
python scripts/pipeline.py kb \
--note-id <NOTE_ID> --kb-id <KB_ID> [--kb-name "<知识库名>"] \
--note-title "<标题>" [--work-dir DIR]
调用 POST https://ima.qq.com/openapi/wiki/v1/add_knowledge，body {"media_type":11, "note_info":{"content_id":<note_id>}, "title":<笔记标题>, "knowledge_base_id":<kb_id>}。
一键完成（all）
python scripts/pipeline.py all \
--book-id <BOOK_ID> --book-title "<书名>" \
--folder-id <FOLDER_ID> [--notebook-name "<笔记本名>"] \
--kb-id <KB_ID> [--kb-name "<知识库名>"] [--work-dir DIR]
all 会自动串联 fetch→build→write，并在提供了 --kb-id / --kb-name 时继续加入知识库。
格式规范（Critical — 严格遵循，曾因违背重做）
- 保持标题层级：IMA 支持 4 级标题（h2/h3/h4）。一级章用
##、二级章用###，不得为"简化"降低层级。 - 目录用锚点链接：正文开头是目录，格式
- [章节标题](#slug)，按level缩进（level-1个空格）。slug = 标题去首尾空白、小写、空格转连字符、仅保留字母数字与连字符（get_anchor）。 - 划线用引用块：每条划线写为
> 原文。 - 想法必须配原文：想法
review含range时，先在正文该章节下用> 原文展示对应划线，再写**我的想法：** <内容>；range为空（如书评级chapterUid=0）则不放原文，归入文末「书评」段。 - 书评段：所有
chapterUid=0的想法汇总到文末## 书评，每条**我的想法：** <内容>。 - 同章去重：同一章节内
markText去空白后完全相同的划线只展示一次（想法匹配到的原文不计入此去重）。
Pitfalls（注意事项）
- Windows GBK 乱码：Python
print中文到控制台会乱码。脚本把人类可读结果与摘要写入 JSON 文件（*_result.json），stdout 只输出 OK / 数字 ID；查看详情用 Read 工具读 JSON。 - 知识库按名查找可能失败：个人自建知识库有时不在
search_knowledge_base/get_addable_knowledge_base_list返回中。此时让用户复制真实知识库 ID 用--kb-id显式传入即可。 - review 嵌套结构：
/review/list/mine返回reviews[]，每条是{"review": {...}}；取rv["review"]再读字段。 - 无 range 的书评：书评级想法常以
topicRanges=["0-0"]出现、无普通range字段，按规范归入「书评」段，不代表匹配失败。 - 列表接口分页与 limit：IMA 列表类接口
limit有上限（笔记本列表 20、知识库列表 20），必须用分页参数遍历；脚本已内置分页处理。 - API 版本提示：微信读书回包若含
upgrade_info，先完成其指引的技能升级再继续。
Resources
scripts/pipeline.py— 全流程脚本（fetch / build / write / kb / all 子命令，自包含，凭证按环境变量优先级读取，ID 全部参数化）。
