**版本：202601**

# 批量执行编辑操作

**POST** `/openapi/2026-01/themes/edit-sessions/:oseid/files/:doc_id/operations`

一次请求批量执行多条编辑操作；每条操作独立执行、独立保存，某条失败不影响其他条目。

## 请求

**Path参数**

- `oseid` string (required)

  编辑会话 ID
- `doc_id` string (required)

  会话内文件的文档 ID

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `operations` object[] (required)

  一次批量执行的主题操作列表（有序）。单条独立生效、独立落库，某条失败不影响其它条。详见 `ThemeOperation`。

  *   Array \[

  - `op` string (required)

    要执行的操作，取值之一：`add_section`、`remove_section`、`move_section`、`replace_props`、`set_visibility`、`append_array_item`、`remove_array_item`、`move_array_item`、`update_slot`、`replace_global`、`set_script_visibility`。
  - `target` string

    目标卡片或 block 的路径，具体含义随 `op` 而定。定位卡片时传其 section id；定位内部 block 时使用点号路径，如 `sec1.blocks.0`（更深层为 `sec1.blocks.0.blocks.2`）。也接受带 `sections.` 前缀的形式（`sections.sec1.blocks.0`）——与 AI 卡片 `instances` 返回的路径同一语法。
  - `value` GoogleProtobufValue

    新的卡片、block 或 blocks 数组内容。适用于 `add_section`、`append_array_item`、`update_slot`。
  - `props` object

    要合并写入的 settings 字段。适用于 `replace_props`、`replace_global`。
  - `visible` boolean

    目标的可见性：true 显示，false 隐藏。适用于 `set_visibility`、`set_script_visibility`。不传等同于 `false`（隐藏），而不是「保持不变」——请务必显式传值。
  - `position` string

    相对参照卡片的位置：`before` 或 `after`。`add_section` 的参照是 `target`；`move_section` 的参照是 `move_target`（此时 `target` 是被移动的卡片）。
  - `move_target` string

    作为移动参照的卡片 id，目标将被放置到它旁边。适用于 `move_section`。
  - `section_id` string

    指定新 section 的实例 id。适用于 `add_section`；可选——不传由服务端生成。id 已存在且 type 相同时幂等成功。
  *   \]

```json
{
  "operations": [
    {
      "op": "string",
      "target": "string",
      "props": {},
      "visible": true,
      "position": "string",
      "move_target": "string",
      "section_id": "string"
    }
  ]
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `data` object[]

    各条操作的执行结果。

    *   Array \[

    - `op` string

      操作类型，回显对应请求项中的 `op`。
    - `result` string

      该操作的结果：成功时为 `success`，否则为错误码（可能带 `:详情` 后缀）。
    *   \]

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "data": [
      {
        "op": "string",
        "result": "string"
      }
    ]
  }
}
```