> ## 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. # 列出文档摘录 > 列出这本书上当前的全部摘录，并标出位置重复的段。 每一项里有两个 id：`noteid` 指向文档笔记本里的记录，`cardNoteId` 指向脑图上的卡片。 插件状态记在后者上。 条数超过上限时 `truncated` 为真。只要重复段时带 `duplicatesOnly=1`。 ## OpenAPI ````yaml /openapi/plugin-api.yaml get /documents/{bookmd5}/excerpts 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: /documents/{bookmd5}/excerpts: get: tags: - 文档与页面 summary: 列出文档摘录 description: | 列出这本书上当前的全部摘录，并标出位置重复的段。 每一项里有两个 id：`noteid` 指向文档笔记本里的记录，`cardNoteId` 指向脑图上的卡片。 插件状态记在后者上。 条数超过上限时 `truncated` 为真。只要重复段时带 `duplicatesOnly=1`。 operationId: getDocumentsBookmd5Excerpts parameters: - $ref: '#/components/parameters/Bookmd5' - $ref: '#/components/parameters/StudySetQuery' - $ref: '#/components/parameters/DuplicatesOnly' responses: '200': description: 摘录清单。可能还有未列出的字段。 content: application/json: schema: $ref: '#/components/schemas/DocumentExcerptsResponse' examples: assembled: summary: 构造示例，未实测 value: bookmd5: >- 8daef026f17a04db9b325c86366419936de1ef8b454218998990a3cef6f467a7 title: The Quiet Case for Walkable Streets total: 128 topicCount: 2 duplicates: [] items: - noteid: 8BD59972-D471-4BF0-A244-9F6F2B9F99F1 cardNoteId: B9F3696A-AF8A-43B2-A8A2-2791717F1695 topicid: 77012CA0-48E8-4D29-B5F5-1EEA927AE086 page: 12 startpos: 1432 endpos: 1510 text: 把街道还给行人的地方，店面反而活了下来。 truncated: false measured: summary: 实测于 2026-10-07，App 0.91 value: topicCount: 4 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 next: >- 'Duplicates listed above sit at the SAME page and coordinates: the user taps the topmost one and gets a card the plugin does not know. This is what a re-run of a sample/import builder leaves behind — deleting a study set deliberately keeps the document''s highlights, so re-excerpting the same PDF stacks them. Delete the extra noteIds with POST /notes/delete (keep one per spot) before shipping anything.' title: The Quiet Case for Walkable Streets total: 13 duplicates: - topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D page: 1 count: 2 noteIds: - B9F3696A-AF8A-43B2-A8A2-2791717F1695 - 5E9D4187-3293-40BC-A6A1-5BF72FA13DFA spot: 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|| bridgeApiVersion: '0.91' items: - noteid: 99A91FEF-B502-4F79-86BD-44AC3BFCF48F topicTitle: The Quiet Case for Walkable Streets endpos: 248.40,425.63 cardNoteId: 137226A6-920E-4F21-AF74-A0858BC547C3 text: issue spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|220.88,440.50|248.40,425.63 page: 1 startpos: 220.88,440.50 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: B6F5A9D8-0A5E-4F74-923D-5D33A813AE7A topicTitle: The Quiet Case for Walkable Streets endpos: 209.10,148.16 cardNoteId: 32D27A0A-B87F-4C82-8290-15A6813B3CC8 text: NIMBY spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|169.05,161.78|209.10,148.16 page: 1 startpos: 169.05,161.78 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 809EB5F0-728B-4ED6-BF6D-FE1381CBB259 topicTitle: The Quiet Case for Walkable Streets endpos: 473.55,695.10 cardNoteId: E215719E-A108-44AE-A287-0A2CA6F89153 text: capabilities spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|413.50,708.48|473.55,695.10 page: 2 startpos: 413.50,708.48 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: B9F3696A-AF8A-43B2-A8A2-2791717F1695 topicTitle: The Quiet Case for Walkable Streets endpos: '' cardNoteId: B9F3696A-AF8A-43B2-A8A2-2791717F1695 text: 这一支下面是用「外刊生词」模板从这篇文章里收出来的词卡。 spot: 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|| page: 1 startpos: '' topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 5E9D4187-3293-40BC-A6A1-5BF72FA13DFA topicTitle: The Quiet Case for Walkable Streets endpos: '' cardNoteId: 5E9D4187-3293-40BC-A6A1-5BF72FA13DFA text: |- 这个学习集是「外刊生词」模板的样例：一篇英文短文，加上用这个模板收出来的十张词卡。 点脑图上任意一张词卡，会跳回文章里那个词划线的地方。卡片正文两行：音标，和… spot: 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|| page: 1 startpos: '' topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: C783D245-E336-4963-A2D8-F1F726663781 topicTitle: The Quiet Case for Walkable Streets endpos: 286.25,183.29 cardNoteId: 7105E353-4E09-49A7-BFBC-2889B5134926 text: >- It is that a street forced to do every job at once ends up doing all of them bad… spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|334.97,215.84|286.25,183.29 page: 2 startpos: 334.97,215.84 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 7FC5FCAC-35A1-4E5C-A3AF-33C8DCA3F554 topicTitle: The Quiet Case for Walkable Streets endpos: 103.37,734.13 cardNoteId: 564C041B-7771-444E-B909-C59AA30327E7 text: charge spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|67.33,749.00|103.37,734.13 page: 2 startpos: 67.33,749.00 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: DC720DB6-BEE2-4401-813A-DA3D342203D3 topicTitle: The Quiet Case for Walkable Streets endpos: 126.52,334.94 cardNoteId: 4B7B59E7-A933-4BDE-8808-23D922B0CE73 text: granularity spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|67.33,348.69|126.52,334.94 page: 2 startpos: 67.33,348.69 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 014358D4-7A44-47C2-8921-6EE1CB6C3EC5 topicTitle: The Quiet Case for Walkable Streets endpos: 116.39,279.93 cardNoteId: 732476FF-4F7A-42EC-8F42-71C0B6BDA91D text: proposed spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|67.33,294.80|116.39,279.93 page: 1 startpos: 67.33,294.80 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 0242E560-419F-4584-8D92-FD496C6EB98F topicTitle: The Quiet Case for Walkable Streets endpos: 213.07,319.33 cardNoteId: 45F0EE7B-F443-4DEB-AABC-360969DD9AC5 text: Groningen spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|1|157.20,333.83|213.07,319.33 page: 1 startpos: 157.20,333.83 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 5CDD84C2-C481-4515-B3C3-D54E2015AA71 topicTitle: The Quiet Case for Walkable Streets endpos: 445.10,435.67 cardNoteId: E3FBABD9-A3FA-4334-B86C-9900FF0D33CC text: walkability spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|386.72,449.05|445.10,435.67 page: 2 startpos: 386.72,449.05 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: EC2810CB-F256-4699-82E6-BB865427A680 topicTitle: The Quiet Case for Walkable Streets endpos: 508.55,282.53 cardNoteId: A2B013C1-831E-43CD-903F-92AFCA3DFF9D text: tone spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|483.50,297.03|508.55,282.53 page: 2 startpos: 483.50,297.03 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D - noteid: 08FC5C02-8D4D-4475-91C7-7253945D9BCC topicTitle: The Quiet Case for Walkable Streets endpos: 275.54,588.43 cardNoteId: D9BCBAC6-6C3D-45BE-B698-BE7EDA23136A text: similarities spot: >- 449C1665-E0DD-4A20-9E67-2B0D451F746D|2|217.16,601.81|275.54,588.43 page: 2 startpos: 217.16,601.81 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D x-codeSamples: - lang: javascript label: 列出该文档上的摘录 source: > const r = await mn.api('/documents/' + bookmd5 + '/excerpts?studySet=' + topicid); mn.log(r.total, r.truncated); // 插件状态记在 cardNoteId 上 const ids = r.items.map(x => x.cardNoteId).filter(Boolean); components: parameters: Bookmd5: name: bookmd5 in: path required: true description: >- 文档的内容标识。取自 `GET /study-sets/{topicid}/documents` 响应里各项的 `bookmd5`、`GET /ui-state` 的 `state.bookmd5`，或 `GET /search?scope=documents`。 schema: type: string StudySetQuery: name: studySet in: query required: false description: >- 限定某个学习集。在 `GET /documents/{bookmd5}/pages/{index}/parts` 上只调整旧留白映射的解析优先级，不按学习集过滤。 schema: type: string DuplicatesOnly: name: duplicatesOnly in: query required: false description: 只返回重复段，不返回逐条摘录。 schema: type: integer enum: - 1 schemas: DocumentExcerptsResponse: type: object properties: bookmd5: type: string title: type: string total: type: number topicCount: type: number duplicates: type: array description: 位置重复的段。 items: type: object properties: page: type: number count: type: number noteIds: type: array items: type: string items: type: array items: type: object properties: noteid: type: string cardNoteId: type: string description: 脑图上的卡片。插件状态记在该卡上，不记在文档笔记本那一条上。 topicid: type: string topicTitle: type: string page: type: number startpos: type: - number - string endpos: type: - number - string text: type: string truncated: type: boolean description: 条数超过上限时为 `true`。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.