> ## Documentation Index
> Fetch the complete documentation index at: https://dev.marginnote.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 合并子卡

> 把子卡的内容并进该卡，等同于卡片菜单上的合并分支。默认只并直接子卡，
带 `recursive` 时连整棵子树一起并。

并非所有子卡都会被并入：拒绝接收的卡原样留在树上，数量看响应里的 `notMergedCount`；
摘要卡与子脑图根卡会被自动跳过，原因在 `skipped` 里。

响应里的 `willMerge` 是本次计划并入的卡，可据此先检查再决定是否提交。




## OpenAPI

````yaml /openapi/plugin-api.yaml post /notes/{noteid}/merge-branch
openapi: 3.1.0
info:
  title: 场景插件 API
  summary: 场景插件在网页面板里可以调用的接口。
  description: >
    场景插件的面板是一个网页。页面里向 `/bridge/v1` 发请求，就能读写 MarginNote 里的数据。

    请求由 MarginNote 处理，与外部命令行工具共用同一套处理代码。外部工具要带令牌，面板不必带。

    面板页面从 `mnpanel://panel/index.html` 加载，因此 `fetch('/bridge/v1' + path)`
    属于同源请求。


    面板调用受这些条件约束：


    - 请求不带令牌，本文件也不声明安全方案。

    - 页面能调用哪些接口，取决于两份名单。模板里的 `plugins` 名单和沉浸态决定面板能不能建好，
      网页面板白名单决定页面能调哪些接口。不在白名单里的请求返回 `403`，
      错误码为 `IN_PROCESS_NOT_ALLOWED`。
    - `GET /capabilities` 里的 `requiresMax` 只约束外部 Agent。面板的请求在 MarginNote 进程内处理，
      不受令牌、订阅状态与跨设备批准的限制，能否调用只看该路径是否在白名单内。
    - 写操作里的 `addon`，MarginNote 会改写为当前面板所属插件的 id；`confirm` 由 MarginNote 补上。
      页面填的值不会生效。

    用 `mn.api(path, opts)` 读取数据。该方法始终将 Response Body 按 JSON 解析，相当于

    `fetch('/bridge/v1' + path, opts).then(r => r.json())`。


    响应的内容不是 JSON 的接口，改用 `fetch`：


    - `GET /guide` 返回 Markdown 正文。

    - `GET /notes/{noteid}/render` 返回卡片长图或 PDF。

    - `GET /documents/{bookmd5}/pages/{index}/content/{contentId}` 返回图片。

    - `GET /bundles/{bundleId}/files` 带 `?path=` 时返回该文件的原始字节。


    调用失败时 Promise 不会进入 reject。MarginNote 把错误对象

    `{"error":{"code":"…","message":"…"}}` 当作 Response Body 返回，因此结果落在 resolve 里。

    判断调用结果看响应里是否带 `error`，写操作另看响应里的 `persisted`。


    接口清单、各项上限与 Request Body 结构随 MarginNote 的版本变化，运行时以 `GET /capabilities` 与

    `GET /guide` 返回的内容为准。
  version: '0.91'
servers: []
security: []
tags:
  - name: 能力与状态
    description: 读取 MarginNote 的能力、版本与当前上下文。调用其他接口之前先读这组。
  - name: 卡片与摘录
    description: 卡片的读取与写入、摘录的创建、批注、标签、元数据与留白。
  - name: 手写会话
    description: 手写层、作答纸、练习准备清单与会话记录的读取与提交。
  - name: 学习集与卡组
    description: 学习集结构、脑图树、子脑图、色板、快照与复习卡组。
  - name: 文档与页面
    description: 文档目录、页文本、页内注释面、摘录清单与同步诊断。
  - name: 导出与 Anki
    description: 文档导出计划、导出文件、Anki 导出能力、作业与产物。
  - name: 查找
    description: 跨库搜索、文件夹列表与学习集列表。
  - name: 界面与模板
    description: 读取当前界面状态与沉浸模板。
  - name: 插件辅助
    description: 面板辅助脚本、已配对设备与本机 helper 信息。
  - name: 任务包与同步诊断
    description: 拆书任务包与旧 CloudKit 同步诊断。
paths:
  /notes/{noteid}/merge-branch:
    post:
      tags:
        - 卡片与摘录
      summary: 合并子卡
      description: |
        把子卡的内容并进该卡，等同于卡片菜单上的合并分支。默认只并直接子卡，
        带 `recursive` 时连整棵子树一起并。

        并非所有子卡都会被并入：拒绝接收的卡原样留在树上，数量看响应里的 `notMergedCount`；
        摘要卡与子脑图根卡会被自动跳过，原因在 `skipped` 里。

        响应里的 `willMerge` 是本次计划并入的卡，可据此先检查再决定是否提交。
      operationId: postNotesNoteidMergeBranch
      parameters:
        - $ref: '#/components/parameters/Noteid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeBranchRequest'
            examples:
              directOnly:
                summary: 只合并直接子卡
                value:
                  confirm: true
              recursive:
                summary: 连同整棵子树一起合并
                value:
                  recursive: true
                  confirm: true
      responses:
        '200':
          description: 响应。可能还有未列出的字段。
          content:
            application/json:
              schema:
                type: object
                properties:
                  willMerge:
                    type: array
                    description: 将要合并的每一个子卡。
                    items:
                      type: object
                      additionalProperties: true
                  notMergedCount:
                    type: number
                    description: 被拒收、原样留在树上的数量。
                  skipped:
                    type: array
                    description: 自动跳过的卡与原因。
                    items:
                      type: object
                      additionalProperties: true
              examples:
                assembled:
                  summary: 构造示例，未实测
                  value:
                    willMerge:
                      - noteid: 8AEDDBF9-BDD8-4D91-AC31-5DEAC8DF1DA1
                        title: (1.2)
                    notMergedCount: 0
                    skipped: []
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-codeSamples:
        - lang: javascript
          label: 合并分支
          source: |
            await mn.api('/notes/' + noteid + '/merge-branch', {
              method: 'POST',
              body: { recursive: true, confirm: true }
            });
components:
  parameters:
    Noteid:
      name: noteid
      in: path
      required: true
      description: >-
        卡片的 noteid。取自卡片命令响应的 `noteid`、`POST /notes/batch-get` 响应里
        `items[].noteid`，或 `GET /ui-state` 的 `state.focusnoteid`。
      schema:
        type: string
  schemas:
    MergeBranchRequest:
      type: object
      required:
        - confirm
      properties:
        recursive:
          type: boolean
          description: 连整棵子树一起合并。默认只合并直接子卡。
        confirm:
          type: boolean
          description: 必填。该接口的 `confirm` 排在业务校验之前。
    ErrorEnvelope:
      type: object
      description: >-
        失败时的 Response Body。MarginNote 将其当作正常 Response Body 返回，因此落在 resolve 里而不是
        reject 里。
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误码。判断写入是否发生看该字段，不看 HTTP 状态码。
        message:
          type: string
          description: 人可读的说明。文案随 MarginNote 的版本变化，不要用该字段做分支判断。
        retryable:
          type: boolean
          description: >-
            是否明确可以稍后再试。只有外部调用的响应带该字段，面板本地调用的响应只有 `code` 与
            `message`。该布尔值表达不了结果未定，这类情况按各接口的说明处理，例如手写会话族看响应里的
            `layerLeaseUnresolved`。
        details:
          type: object
          description: >-
            附加事实。例如 `SCAN_BUSY` 带 `retryAfterSeconds`，`HASHTAG_ROUTE_REQUIRED` 带
            `writeRoute`。
          additionalProperties: true
  responses:
    UnprocessableEntity:
      description: 字段合法但组合不成立，例如缺少 `confirm`、序号越界、或写入顺序违反约定。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            confirmRequired:
              summary: 没有带 confirm
              value:
                error:
                  code: CONFIRM_REQUIRED
                  message: 本次调用会改动数据，需要带 confirm。
            invalidOrder:
              summary: 写入顺序不成立
              value:
                error:
                  code: INVALID_ORDER
                  message: deleteComment 必须排在 removeHashtags 之前。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.