Search / Snapshots / Sync / UI

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

GET /search（免 Max）

交互式

• 找书唯一路：scope=documents 拿 bookmd5（书不在任何集里亦可搜到；无列全库文档端点）。
• truncated:true = 窗口没够到，加词重搜，勿断言无此书。新卡约 10s 索引延迟（刚 submit 搜不到自己正常）。

POST /snapshots/{id}/restore（需 Max + confirm，真 dry-run）

交互式 · 危险纪律

• 整集回过去（最重）。须展示版本（时间/说明）获同意。自动先打回退前保护点（一并告知）。
• 目标集正开着 409（切走再试）。文档目录不在覆盖范围。不带 confirm 回 422 预览。USER_EDITS_PRESENT 时展示 changedNodes 获同意后 force:true。

旧同步诊断（旧 CloudKit + iCloud Documents，两通道独立）

任一完成≠另一完成。五个端点免 Max、需 Bearer。

GET /sync/legacy/status

交互式

• 隐私白名单快照（无正文/文档名/账号/record id）。errorCount 为历史数；suspended 看 suspensionNeedsAttention（false 可为正常增量暂停）；当前周期错误看 suspensionErrorCount。

GET /sync/legacy/events

交互式

• 用 lastSequence 续取；hasMore 续取；historyTruncated:true 勿称中间完整；尾部无事件时 cursorAdvancedPastGap:true 防死循环；cursorAhead:true 重置游标。双设备各用独立 base+token+nonce，sequence 不交叉。

POST /sync/legacy/recheck

交互式

• 复用既有核对，不 reset/删/覆盖/改冲突；但可能应用待处理远端变更。accepted 仅受理，记 operationId/startSequence 后读 events/status。

POST /sync/legacy/inventory

交互式

• 只读分页观察，非权威（observed 仅本轮未见；possible_mismatch 须按 record ID 核验；不自动修/传/删）。仅 Bridge 启用时显式触发；独立低优先级非蜂窝队列；关 Bridge 即关。回执须明示 observeOnly；仍耗配额。
• 脚本：tools/mn_legacy_sync_lab.py + doc/agent/mn_legacy_sync_lab.md（见规程包）。

GET /ui-state（免 Max）／POST /ui-state/apply（需 Max）

交互式 · 交互式 · 危险纪律

• 工作场景书签。差量补丁（缺键保持；GET 整包可改后发回）。{_jsonvalueType} 包装值原样带回。
• 异步（~1.5s），queued:true 仅提交，~2s 后 GET 对账所发键。三态 accepted/conditional/rejected（play 与 doclayerid:"new" 拒收）。
• 缺 topicid 注入当前集；无开集拒绝。持久副作用改前告知（全局偏好/脏同步/任意 URL）。已知限制：含 immersive 的 pin 恢复顺序 bug。