标准工作流

参数见交互式 API。这里记录跨端点的顺序。

拆书

curl -s "$BASE/library/study-sets?query=高数" -H "$AUTH"
curl -s "$BASE/study-sets/{topicid}/documents" -H "$AUTH"
curl -s "$BASE/documents/{bookmd5}/outline" -H "$AUTH"

curl -s -X POST "$BASE/bundles/prepare" -H "$AUTH" -H 'Content-Type: application/json' -d '{
  "topicid":"…","bookmd5":"…",
  "segments":[{"startPage":96,"endPage":132,"title":"第三章"}],
  "preset":"book-breakdown","anchorMode":"page_text",
  "title":"拆第三章，术语保留英文",
  "cardStyle":{"defaultFillIndex":2},"async":true}'

curl -s "$BASE/bundles?origin=bridge" -H "$AUTH"

curl -s -X POST "$BASE/bundles/{bundleId}/submit" -H "$AUTH" \
  -H 'Content-Type: application/json' -d '{"targetParentNoteId":"<可选>"}'

每次 prepare 不超过 60 页，按实际页数计算。整书按章多轮。修订时修改 result.md 后重新 submit，整树替换。导错时用 preImportSnapshotId 经 POST /snapshots/{id}/restore 回退。

preset 与 anchorMode

组合错误时静默退化，不报错。

• 叙述体：book-breakdown 配 page_text
• 条文或手册：source-structure 配任意 anchorMode
• 试卷或习题：exam-general 配 block。题答配对依赖块的 role，配 page_text 等于没选 preset
• 词典：dictionary 配 page_text

startPage、endPage 与 /pages 的 start、end、outline 的 startPage 同为 PDF 页序，从 1 开始计数，与印刷页码无关。segments 可非连续。

目录

• 只拆一两章时不写目录。读印刷目录页计算偏移，回读正文确定章界。
• 需要目录或整书多轮需要稳定骨架时走生成或升级。写入前说明改文档且多集可见，确认后带 confirm:true 写入。
• toc-candidates 单次不超过 60 页，约 3 秒每页，45 秒预算。超限按 nextStart 续扫。并发上限 2，与 pages 共享，超限返回 429 SCAN_BUSY。
• 写 POST /documents/{md5}/toc 时页码递增，level 取 0 到 7。越级会被静默钳制，看 adjustedLevels。写入落到 AI 目录位，原目录无损。
• 回退方式：{"useOriginal":true,"confirm":true} 切回原始，{"useAI":true,"confirm":true} 切回 AI。快照不覆盖目录。
• 写入后用 GET /outline 验证，hasToc 为 true。

整理与修订

• 读取已有脑图：tree 加 batch-get。texts 稀疏，parts 为全量视觉顺序。texts 为空时先看 parts。
• 整理时生成新图，prepare 加 submit，原图不动。引用旧卡时写 marginnote4app://note/{noteid} 链接文本。
• 移动：POST /notes/move。单次不超过 50 个，整批一个撤销组。确认逐卡方案后执行。只改父子关系，不调兄弟顺序与坐标。
• 复制：POST /notes/copy。reference 同步内容，clone 独立。整棵分支快照，不超过 50 个根。
• 合并：POST /notes/{id}/merge-branch。默认合并直接子卡，recursive:true 合并整棵子树。先 dry-run 查看 willMerge。合并后对方消失，与链接不同。
• 子脑图：sub-maps 列出，tree?root= 读取，fold-into-sub-map 折叠或展回。折叠需要子节点。
• 折叠：POST /notes/fold。单次不超过 200 个，开销最小的写入。叶子节点跳过。
• 删除卡：POST /notes/delete。单次不超过 50 个，同集。只删点名卡，子卡接到祖父或升为顶层。先打快照，确认子卡去向。outcome 为 deleted 表示删除，为 hidden 表示隐藏。
• 删集：POST /study-sets/{id}/delete。expectedTitle 与库中值完全一致。默认隐藏卡片、保留划线、自动打快照。preDeleteSnapshotId 用于回退。
• 评论、标题、正文：comments 追加，整条 note URL 形成双向链接。comments/{index} 改写或删除，index 取 1 到 N，附 expectedPrefix。title 与 text 改写附 expectedPrefix。摘录卡改文会导致文字与原文脱钩，提前说明。
• hashtag：读 batch-get.hashtags 或集的 study-sets/{id}/hashtags。写 POST /notes/hashtags，使用完整叶路径。remove 默认精确匹配，replace 空数组表示清空，确认后执行。写完回读。
• 样式：POST /notes/metadata。colorIndex 取 0 到 15，fillIndex 取 -1 到 2。先读 note-palette。
• 复习卡组：decks 新建与列出，decks/{id}/cards 新增与列出。sourceNoteId 必填。question 与 questionContentId 互斥。挖空写在 question。重复新增为更新。删单卡用 /notes/delete。删整组用 /study-sets/{deckId}/delete，keepHighlights 为 false 时删干净。
• 快照：批量写前打快照。复用时返回 created:false，仍可作基线。回退前确认版本。目标集打开时返回 STUDY_SET_IN_USE，关闭后再试。
• 文档进出：upload 以字节加 query 方式上传，confirm=1，看 addedToStudySet 与 warnings。study-sets/{id}/documents 新增看 becameMainDocument。study-sets/{id}/documents/{id}/delete 移除前先 dry-run 查看 notesLosingSource，并保存 preRemoveSnapshotId。library/documents/{id}/delete 仅干净撤销，否则返回 409。
• 导航：notes/{id}/focus、study-sets/{id}/open、decks/{id}/open。没有 confirm。跳转抢占屏幕，异步执行，之后用 GET /context 确认。读取当前状态用 GET /context。
• 界面：GET /ui-state 读取，POST /ui-state/apply 写入差量补丁。异步执行，queued 为 true 表示已提交，约 2 秒后用 GET /ui-state 确认。