> ## 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. # 获取学习集脑图 > 读整个学习集的脑图结构、标题与逻辑属性。 节点是扁平数组，父子关系靠每一项的 `parent` 自行组合，没有嵌套的下层数组。 要按文档顺序排列时带 `sort=document`。不要自行按页码排序：摘录与摘题产出的卡自身没有 页码，页码在该题的摘录子笔记上。带该参数时由 MarginNote 排序，判据与界面上的按页码排序逐字一致， 并给每个节点补上 `docPage` 与 `docBookmd5`。排序在切片之前对整条序列做，跨页顺序因此是对的。 翻页用 `limit` 与 `cursor`，响应里的 `nextCursor` 为 `null` 表示已到末尾。 达到遍历上限时 `walkLimitReached` 为真，为真时才表示读到末页也取不全。 ## OpenAPI ````yaml /openapi/plugin-api.yaml get /study-sets/{topicid}/tree 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: /study-sets/{topicid}/tree: get: tags: - 学习集与卡组 summary: 获取学习集脑图 description: | 读整个学习集的脑图结构、标题与逻辑属性。 节点是扁平数组，父子关系靠每一项的 `parent` 自行组合，没有嵌套的下层数组。 要按文档顺序排列时带 `sort=document`。不要自行按页码排序：摘录与摘题产出的卡自身没有 页码，页码在该题的摘录子笔记上。带该参数时由 MarginNote 排序，判据与界面上的按页码排序逐字一致， 并给每个节点补上 `docPage` 与 `docBookmd5`。排序在切片之前对整条序列做，跨页顺序因此是对的。 翻页用 `limit` 与 `cursor`，响应里的 `nextCursor` 为 `null` 表示已到末尾。 达到遍历上限时 `walkLimitReached` 为真，为真时才表示读到末页也取不全。 operationId: getStudySetsTopicidTree parameters: - $ref: '#/components/parameters/Topicid' - $ref: '#/components/parameters/TreeRoot' - $ref: '#/components/parameters/TreeLimit' - $ref: '#/components/parameters/TreeCursor' - $ref: '#/components/parameters/SortDocument' - $ref: '#/components/parameters/WithNotes' responses: '200': description: 脑图。节点是扁平数组，父子关系靠 `parent` 字段表示。 content: application/json: schema: $ref: '#/components/schemas/TreeResponse' examples: recordedPlain: summary: 真机实录（MarginNote 0.61，2026-09-18 录制）；实录只保留开头部分 value: topicid: 77012CA0-48E8-4D29-B5F5-1EEA927AE086 bridgeApiVersion: '0.61' nodeTotal: 15 nodes: - noteid: BCC8D945-7585-425A-9FDF-E24C6503F628 parent: null depth: 0 folded: false hasInk: false title: 一元一次方程与百分数·练习A isReference: 0 preview: 一元一次方程与百分数·练习A childCount: 0 kind: framework - noteid: 055E30EF-A59E-44AC-9459-997EEB5481A6 parent: null depth: 0 folded: false hasInk: false title: 理工公式对照材料 isReference: 0 preview: 理工公式对照材料 childCount: 1 kind: framework - noteid: 8AEDDBF9-BDD8-4D91-AC31-5DEAC8DF1DA1 parent: 055E30EF-A59E-44AC-9459-997EEB5481A6 depth: 1 folded: false hasInk: false title: (1.2) isReference: 1 preview: (1.2) childCount: 0 kind: card nextCursor: null recordedByDocument: summary: >- 真机实录，带 sort=document：顶层多出 sort，节点多出 docPage 与 docBookmd5；实录只保留开头部分 value: topicid: 77012CA0-48E8-4D29-B5F5-1EEA927AE086 bridgeApiVersion: '0.61' nodeTotal: 15 sort: document nodes: - noteid: CFF32D75-D896-44C3-A1E0-440310573274 parent: null depth: 0 folded: false hasInk: false title: 理工公式对照材料 · 样例 isReference: 0 preview: 理工公式对照材料 · 样例 docBookmd5: >- 8daef026f17a04db9b325c86366419936de1ef8b454218998990a3cef6f467a7 childCount: 1 kind: card - noteid: 055E30EF-A59E-44AC-9459-997EEB5481A6 parent: null depth: 0 folded: false hasInk: false title: 理工公式对照材料 isReference: 0 preview: 理工公式对照材料 docBookmd5: >- 8daef026f17a04db9b325c86366419936de1ef8b454218998990a3cef6f467a7 childCount: 1 kind: framework - preview: (1.2) isReference: 1 noteid: 8AEDDBF9-BDD8-4D91-AC31-5DEAC8DF1DA1 docBookmd5: >- 8daef026f17a04db9b325c86366419936de1ef8b454218998990a3cef6f467a7 parent: 055E30EF-A59E-44AC-9459-997EEB5481A6 hasInk: false folded: false title: (1.2) docPage: 1 depth: 1 kind: card childCount: 0 nextCursor: null measured: summary: 实测于 2026-10-07，App 0.91 value: topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D bridgeApiVersion: '0.91' nodeTotal: 16 sort: document nodes: - noteid: 4BA97E67-BC2B-458C-893C-EF7E9AA836C2 parent: null depth: 0 folded: false hasInk: false title: The Quiet Case for Walkable Streets isReference: false preview: The Quiet Case for Walkable Streets docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 childCount: 1 kind: card - noteid: 288F88A3-2388-4043-87A3-1E60EB380B9C parent: null depth: 0 folded: false hasInk: false title: The Quiet Case for Walkable Streets isReference: false preview: The Quiet Case for Walkable Streets docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 childCount: 1 kind: framework - preview: issue; issued; issuing; issues isReference: false noteid: 137226A6-920E-4F21-AF74-A0858BC547C3 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: issue; issued; issuing; issues docPage: 1 depth: 2 kind: card childCount: 0 - preview: propose; proposed; proposing; proposes isReference: false noteid: 732476FF-4F7A-42EC-8F42-71C0B6BDA91D docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: propose; proposed; proposing; proposes docPage: 1 depth: 2 kind: card childCount: 0 - preview: '' isReference: true noteid: D3085422-2CB9-4B68-A78D-DEE351CF9C38 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: 288F88A3-2388-4043-87A3-1E60EB380B9C hasInk: false folded: false title: '' docPage: 1 depth: 1 kind: card childCount: 0 - preview: 收到的生词 isReference: false noteid: B9F3696A-AF8A-43B2-A8A2-2791717F1695 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: 4BA97E67-BC2B-458C-893C-EF7E9AA836C2 hasInk: false folded: false title: 收到的生词 docPage: 1 depth: 1 kind: card childCount: 12 - preview: NIMBY; nimbys isReference: false noteid: 32D27A0A-B87F-4C82-8290-15A6813B3CC8 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: NIMBY; nimbys docPage: 1 depth: 2 kind: card childCount: 0 - preview: 读我：这份样例怎么看 isReference: false noteid: 5E9D4187-3293-40BC-A6A1-5BF72FA13DFA docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: 读我：这份样例怎么看 docPage: 1 depth: 2 kind: card childCount: 0 - preview: Groningen isReference: false noteid: 45F0EE7B-F443-4DEB-AABC-360969DD9AC5 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: Groningen docPage: 1 depth: 2 kind: card childCount: 0 - preview: charge; charged; charging; charges isReference: false noteid: 564C041B-7771-444E-B909-C59AA30327E7 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: charge; charged; charging; charges docPage: 2 depth: 2 kind: card childCount: 0 - preview: capability; capabilities isReference: false noteid: E215719E-A108-44AE-A287-0A2CA6F89153 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: capability; capabilities docPage: 2 depth: 2 kind: card childCount: 0 - preview: similarity; similarities isReference: false noteid: D9BCBAC6-6C3D-45BE-B698-BE7EDA23136A docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: similarity; similarities docPage: 2 depth: 2 kind: card childCount: 0 - preview: walkability isReference: false noteid: E3FBABD9-A3FA-4334-B86C-9900FF0D33CC docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: walkability docPage: 2 depth: 2 kind: card childCount: 0 - preview: granularity isReference: false noteid: 4B7B59E7-A933-4BDE-8808-23D922B0CE73 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: granularity docPage: 2 depth: 2 kind: card childCount: 0 - preview: tone isReference: false noteid: A2B013C1-831E-43CD-903F-92AFCA3DFF9D docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: tone docPage: 2 depth: 2 kind: card childCount: 0 - preview: a street forced to do every job at once isReference: false noteid: 7105E353-4E09-49A7-BFBC-2889B5134926 docBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parent: B9F3696A-AF8A-43B2-A8A2-2791717F1695 hasInk: false folded: false title: a street forced to do every job at once docPage: 2 depth: 2 kind: card childCount: 0 nextCursor: null x-codeSamples: - lang: javascript label: 按文档顺序列出卡片 source: > // 不要自行按 startPage 排序，页码在摘录子笔记上，卡自身没有页码 const tree = await mn.api('/study-sets/' + topicid + '/tree?sort=document'); const cards = tree.nodes; mn.log(tree.nodeTotal, tree.nextCursor, tree.truncated); // 翻下一页时把 nextCursor 带返回去 if (tree.nextCursor) { const more = await mn.api('/study-sets/' + topicid + '/tree?sort=document&cursor=' + tree.nextCursor); } components: parameters: Topicid: name: topicid in: path required: true description: >- 学习集的 topicid。取自 `GET /ui-state` 的 `state.topicid`、`GET /library/study-sets`，或 `GET /writing/context` 响应里的 `window.topicid`。 schema: type: string TreeRoot: name: root in: query required: false description: 指定子脑图根卡的 noteid，只读其中一张。取自 `GET /study-sets/{topicid}/sub-maps`。 schema: type: string TreeLimit: name: limit in: query required: false description: 一次返回的节点数上限。 schema: type: integer minimum: 1 maximum: 5000 default: 5000 TreeCursor: name: cursor in: query required: false description: 下一页的起点，取上一页响应里的 `nextCursor`。 schema: type: string SortDocument: name: sort in: query required: false description: 按文档顺序排列。排序在分页切片之前对整条序列做，跨页顺序因此是对的。 schema: type: string enum: - document WithNotes: name: withNotes in: query required: false description: 带 `withNotes=1` 时，一并返回每个标签下直接存有该条完整路径的卡片 id。 schema: type: integer enum: - 1 schemas: TreeResponse: type: object description: | 整个学习集的脑图。节点是扁平数组，父子关系由每项的 `parent` 写出，没有嵌套的 children。 翻页时带 `limit` 与 `cursor`；要按文档顺序排列时带 `sort=document`，此时顶层多出 `sort`， 节点上多出 `docPage` 与 `docBookmd5`。 properties: topicid: type: string bridgeApiVersion: type: string nodeTotal: type: number description: 整棵树的节点数。翻页之前该数值已经可用。 nodes: type: array items: $ref: '#/components/schemas/TreeNode' nextCursor: type: - string - 'null' description: 下一页的起点。为 `null` 表示已到末尾。 truncation: type: boolean walkLimitReached: type: boolean description: 撞上了遍历硬顶。只有该字段为 `true` 才表示即使读到末页也取不全。 truncated: type: boolean description: 该响应不是全部：还有下一页，或撞上了硬顶。 sort: type: string description: 只在带 `sort=document` 时出现。 TreeNode: type: object properties: noteid: type: string parent: type: - string - 'null' description: 父卡的 noteid。根节点为 `null`。 depth: type: number childCount: type: number title: type: string preview: type: string description: 显示标题，没有标题时取正文首段。超过 64 个 UTF-16 单位时以省略号结尾。 kind: type: string folded: type: boolean hasInk: type: boolean isReference: type: - boolean - integer description: 该卡是引用卡。较早的 MarginNote 在该项上给 `1` 与 `0`，按真值判断。 subMapId: type: string description: 该卡所属的子脑图，取值是该子脑图根卡的 noteid。 docPage: type: number description: 文档页码。只在带 `sort=document` 时出现，由 MarginNote 补出来。 docBookmd5: type: string description: 页码所属的文档。只在带 `sort=document` 时出现。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.