**版本：202607**

# 主题会话

通过编辑会话编辑主题，与后台主题编辑器一致

编辑会话（ID 为 `oseid`）即打开一次主题编辑器。会话内的改动与其他会话相互隔离，保存草稿后才会生效；保存时会检查草稿在会话开始后是否被改动过。

提供创建编辑会话、检查冲突、保存草稿，读写会话文件与批量编辑，读取与更新主题全局配置（主题设置与页头、页尾等全局卡片），操作页面上的卡片（查询模板已添加卡片、查询卡片详情、设置卡片与块属性、新增与删除块、从页面移除卡片），在会话中新建卡片（查询会话卡片库，创建与管理 AI 卡片，查询高级卡片详情，保存高级卡片到会话；AI 卡片是用 liquid 代码新建的 block 卡片，每次写操作都可撤销），以及查询、启用、停用应用嵌入与 script tag 等接口。 查询可添加卡片与管理自定义卡片模板，见「主题卡片」。

- [创建主题编辑会话](/zh-CN/api/theme-edit-session-create) `POST /openapi/2026-07/themes/:theme_id/edit-sessions`: 为指定主题开启编辑会话（返回 oseid）。

- [检查编辑会话冲突](/zh-CN/api/theme-edit-session-conflict) `GET /openapi/2026-07/themes/edit-sessions/:oseid/conflict`: 检查会话开始后，草稿是否已被其他会话修改。

- [保存编辑会话为草稿](/zh-CN/api/theme-edit-session-promote) `POST /openapi/2026-07/themes/edit-sessions/:oseid/promote`: 将编辑会话保存为草稿。

- [查询编辑会话文件](/zh-CN/api/theme-edit-session-file-get) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id`: 读取编辑会话中的单个文件。

- [更新编辑会话文件](/zh-CN/api/theme-edit-session-file-update) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id`: 用传入的卡片配置整体覆盖编辑会话中的模板文件，列表里没有的卡片会被删除；只改局部请用「批量执行编辑操作」。

- [批量执行编辑操作](/zh-CN/api/theme-edit-session-batch-operations) `POST /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/operations`: 一次请求批量执行多条编辑操作；每条操作独立执行、独立保存，某条失败不影响其他条目。

- [查询主题全局配置](/zh-CN/api/theme-global-config) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/global`: 返回编辑会话内主题设置的当前值，以及各一级栏目的配置定义。

- [更新主题全局配置](/zh-CN/api/theme-global-config-update) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/global`: 局部更新编辑会话内主题的全局配置：只传要改的设置项（一条或多条）。默认更新主题设置；传 `section_id` 可更新页头、页尾、公告栏、购物车抽屉等全局卡片。

- [查询模板已添加卡片列表](/zh-CN/api/theme-section-cards-list) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/sections`: 返回编辑会话内某模板上已添加的全部卡片，含页头、页尾等全局卡片组。

- [查询卡片详情](/zh-CN/api/theme-section-card-detail) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/sections/:section_id`: 用当前配置渲染指定卡片，返回渲染后的 HTML、卡片配置与配置定义，不修改数据；也可以查页头、页尾等全局卡片。

- [设置卡片属性](/zh-CN/api/theme-section-set-props) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/props`: 在编辑会话中，将属性写入/合并到某张卡片的 settings。

- [设置卡片内块属性](/zh-CN/api/theme-section-set-slot) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/slot`: 在编辑会话中，将属性写入/合并到某张卡片内指定块的 settings。

- [新增卡片内的块](/zh-CN/api/theme-section-add-block) `POST /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/blocks`: 在编辑会话中，向某张卡片追加/插入一个块。

- [删除卡片内的块](/zh-CN/api/theme-section-remove-block) `DELETE /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/blocks`: 在编辑会话中，按下标删除某张卡片内的一个块。

- [从页面移除卡片](/zh-CN/api/theme-section-remove) `DELETE /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id`: 在编辑会话中，从页面移除某张卡片。

- [查询编辑会话卡片库](/zh-CN/api/theme-edit-session-card-list) `GET /openapi/2026-07/themes/edit-sessions/:oseid/card-list`: 返回主题里可用的卡片：普通卡片（`card_list`、`block_list`）取已发布的版本；AI 卡片单独放在 `gen_list`，含会话中新建、还没放到页面或还没保存的卡片，每项带 `saved` 表示是否已保存到草稿。

- [查询 AI 卡片详情](/zh-CN/api/theme-gen-block-detail) `GET /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: 返回 AI 卡片在当前会话中的文件信息和使用情况（是否已保存、被引用的次数等）；传 `with_content=true` 时附带卡片源码。

- [创建 AI 卡片](/zh-CN/api/theme-gen-block-create) `POST /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: 在编辑会话中用 liquid 代码（必须含 `{% schema %}` 标签）创建一张 AI 卡片。响应里的 `settings` 是卡片的完整默认配置，可以直接用来把卡片放到页面上。

- [删除 AI 卡片](/zh-CN/api/theme-gen-block-delete) `DELETE /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: 删除 AI 卡片，并把它从主题的所有页面上移除。

- [更新 AI 卡片](/zh-CN/api/theme-gen-block-update) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: 用新的源码和完整配置更新 AI 卡片。卡片没被使用或只用在一处时直接修改（`branched=false`）；用在多处时会另建一张新卡片来承载这次修改（`branched=true`），需要用返回的 `settings` 替换目标位置上的卡片。

- [撤销 AI 卡片操作](/zh-CN/api/theme-gen-block-revert) `POST /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks/revert`: 按 `revert_id`（任意一次创建、更新、删除或撤销的响应里都有）把卡片恢复到那次操作之前的状态；撤销也会返回新的 `revert_id`，可以反复撤销和重做。

- [查询高级卡片详情](/zh-CN/api/theme-pb-single-blocks) `GET /openapi/2026-07/themes/page-builder/blocks`: 按 `source_ids` 批量获取高级卡片的名称、完整 block `type` 与默认 `settings`，即把卡片放到页面上所需的信息。

- [保存高级卡片](/zh-CN/api/theme-pb-block-save) `POST /openapi/2026-07/themes/page-builder/blocks`: 基于高级卡片模板应用编辑操作（`ops`）并保存为新卡片，再把它放到编辑会话中的目标位置；`event_type` 不是 `theme` 时只保存卡片，不放到页面上。

- [查询应用嵌入列表](/zh-CN/api/theme-apps-list) `GET /openapi/2026-07/themes/apps`: 返回店铺已安装应用提供的嵌入卡片（app-embed）和注入的 script tag。

- [启用应用嵌入](/zh-CN/api/theme-app-enable) `POST /openapi/2026-07/themes/edit-sessions/:oseid/apps/enable`: 在编辑会话中启用指定的 app-embed 或 script tag。

- [禁用应用嵌入](/zh-CN/api/theme-app-disable) `POST /openapi/2026-07/themes/edit-sessions/:oseid/apps/disable`: 在编辑会话中禁用指定的 app-embed 或 script tag。