Bundles（拆书）

参数、Schema、多语言示例、Try-it 见各端点交互页（左侧 Bundles 分组）。本页只保留判据与陷阱。

POST /bundles/prepare（免 Max，无 confirm 门）

交互式

• segments：PDF 页序，≤60 实际页（非跨度）；0.18+ 可非连续；重叠乱序自动合并排序；更旧要求连续。
• preset 四选一（白名单外 422）；anchorMode 先 pages[?blocks=1] 探针实测再选；同书可按章混用。
• cardStyle.defaultFillIndex -1..2（不填色选 2；逐卡 [style:]，colorIndex 先读 note-palette；0 非无填充）。
• 未知字段忽略（ignoredFields 明示；成功≠意图生效）。
• async:true（>~10 页必用）。此时目录还在写，勿读。参数错同步回 404/422。
• 单飞：一次一 prepare；429 别再发（看 runningJob/retryAfterSeconds；刚 discard 重发亦然，等取消检查点）。同步小包同样受单飞管辖；被并发 discard 则 409。
• prepare 时少发 pages/toc-candidates（内存峰值叠加，保守）。错配 0.18+ 回 warnings：停下改组合重 prepare。

GET /bundles（免 Max）

交互式

• ?origin=bridge 只看自建；?since= 按类型时间过滤（长作业不因旧时间消失）。version/rootNoteId 仅 prepared|imported；progress 仅 preparing；running 仅作业；无 title/preset/origin。
• 轮询约 15s：preparing 转述进度；prepared 进拆书；failed 修后重来；放弃则 discard。
• jobId 非 null ≠ 本会话活作业（含重启残留）。
• 落点：外部导出文件夹优先；未配置落沙盒容器（缺完全磁盘访问读不了，让用户选导出文件夹）。包内 .bridge/.imported/import-receipt.json 勿动；结果写 result.md（markdown_outline，≤6 级）。

GET /bundles/{id}/files（免 Max）

交互式

• 列包文件；?path= 取单文件原始内容（curl -o 落盘）。跨设备读包与交回靠它。

POST /bundles/{id}/submit（需 Max，无 confirm 门，发即 commit）

交互式 · 危险纪律

• 别拿它试参数，校验用 GET /bundles。提交前复述「哪章、多少卡、进哪个集」。
• withBlank / excerptMode 整包粒度；dictionary 包与 [block:] 包恒合并（产品语义，不可覆盖；看 receipt 确认）。跨设备另带 resultMarkdown。
• 回执必对：preImportSnapshotId 存上下文；headings≠importedCards = 丢卡；excerptsTotal≠excerptsAnchored = 未定位（看 failedExcerpts，多为改写原文或扫描页无矩形）；excerptStatsTruncated:true 则数不可作依据。
• [[标题]] 为合并卡（对方消失），非建链接（dictionary 包剥文本亦勿写）。
• 修订环：改同一 bundle result.md 重 submit = 整树替换；并发重发 409（等查 state，多半已导完）。

POST /bundles/{id}/focus（免 Max，无门）

交互式

• 聚焦结果。异步，事后 /context 对账。

POST /bundles/{id}/discard（免 Max，无门，幂等）

交互式

• 删磁盘工作目录（已导入卡片不受影响）。对 preparing = 取消（cancelledJob 非 null 为真取消）。放弃拆书或 submit 确认无误后顺手清。