submit、快照、安装辅助、界面状态、目录写入的 confirm 与调用纪律

危险 / 半危险端点纪律

这些不是普通错误处理，而是 Agent 调用纪律。发之前先读本页，再看各分域参考。运行时永远优先：清单里有而规程没写的可用，规程有而清单没有的别调。参数、Schema、多语言示例、Try-it 见左侧各分组交互页，本页只讲纪律。

端点	Max	Confirm	真 dry-run	发即后果
`POST /bundles/{id}/submit`	✅	无门，发即 commit	否	整树导入/替换，存 `preImportSnapshotId`
`POST /study-sets/{id}/snapshots`（打点）	✅	无门，发即执行	否（复用时回 `created:false`）	新建或复用版本点，批量写前必打
`POST /install/code`（安装辅助）	—	无门	否	只读语义，不轮换 token；刷新规程走 `GET /guide`
`POST /ui-state/apply`	✅	无门，发即提交	否（`queued:true` 仅提交）	差量补丁异步生效，约 2s 后 GET 对账
`POST /documents/{id}/toc`（写/切目录）	✅	`confirm:true`（JSON）	是（不带回 422 + `wouldWrite`）	改文档本身，多学习集立即可见，快照救不了
`POST /library/documents/upload`	✅	`confirm=1`（query，非 body）	否	文件字节已传完才确认，直接带最省流量

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

提交前向用户复述「拆了哪章、多少张卡、导入到哪个学习集」。
别拿它试参数：校验 bundle 用 GET /bundles 看 state，不要空发一次 submit。
并发重复提交 409 SUBMIT_IN_FLIGHT：等 retryAfterSeconds 后查 GET /bundles，多半已导完。
submit 后必对回执：parsed.headings ≠ importedCards = 丢卡；excerptsTotal ≠ excerptsAnchored 看 failedExcerpts[]；excerptStatsTruncated:true 时数不可作依据。
修订环 = 改同一 bundle 的 result.md 重 submit（整树替换）；导错用响应里的 preImportSnapshotId 经 POST /snapshots/{id}/restore 回退（USER_EDITS_PRESENT 时展示 changedNodes 获同意后 force:true）。

Body 只有 {description}（不加 Agent: 前缀）。批量写、移动、整理前先打点。
内容无变化时复用既有版本点（0.18+ 回 created:false + warnings）；旧服务端无此字段时回读列表核条数。复用点仍可作回退基线。
打点本身不毁数据，但回退（POST /snapshots/{id}/restore，需 confirm:true，真 dry-run）是重操作：须展示版本时间/说明获同意；目标集正开着 409 STUDY_SET_IN_USE 时切走再试。

语义是差量补丁：state 缺的键保持现状。想只关一个面板就只发那一个键。
响应 queued:true 仅表示已提交，约 2s 后再 GET /ui-state 对账发过的键。
三态：accepted / conditional（依赖缺失静默跳过）/ rejected（play 与 doclayerid:new 拒收）。
副作用键改前告知：theme/panelratio 写全局偏好，immersive 弄脏同步，researchurl 加载任意 URL。

只拆一两章走轻量路径（不写目录）；用户明确要目录或整书多轮需骨架才写，且先告知「改文档、多集可见」并获同意。
页码须递增，level 0–7（越级静默钳，看 adjustedLevels）。落 AI 目录位，原目录无损。
唯一回退口：{"useOriginal":true,"confirm":true} 切回原始，{"useAI":true,"confirm":true} 切回 AI。快照救不了目录。没有 toc-revert 端点。
不带 confirm 先打一次拿 wouldWrite 预览，再带 confirm 写。