# Marginnote Dev Docs

> Marginnote 开发文档

## 开始

- [简介](https://dev.marginnote.com.cn/zh/introduction.md)
- [使用 AI 辅助创作](https://dev.marginnote.com.cn/zh/ai-dev.md)

## 基础

- [场景插件基础](https://dev.marginnote.com.cn/zh/plugin-base.md)
- [使用 MNRails 创建你的插件项目](https://dev.marginnote.com.cn/zh/mnrails.md)
- [使用 window.mn 与MN进行交互](https://dev.marginnote.com.cn/zh/sdk.md)
- [为插件设置图标](https://dev.marginnote.com.cn/zh/logo.md)
- [UI 控制](https://dev.marginnote.com.cn/zh/ui.md)
- [数据交互](https://dev.marginnote.com.cn/zh/data-interact.md)
- [事件系统](https://dev.marginnote.com.cn/zh/events.md)

## 模板配置

- [最小打包](https://dev.marginnote.com.cn/zh/basic-package.md)

## 深入插件

- [最佳实践](https://dev.marginnote.com.cn/zh/best-practice.md)
- [网络请求限制](https://dev.marginnote.com.cn/zh/network.md)
- [卡片与摘录菜单命令](https://dev.marginnote.com.cn/zh/menu-commands.md)
- [使用 MN 内置 AI](https://dev.marginnote.com.cn/zh/use-inner-ai.md)
- [面板之外](https://dev.marginnote.com.cn/zh/jsaddon.md)

## API 参考

- [AI 生成提醒](https://dev.marginnote.com.cn/zh/api-ai-warning.md)

### 能力与状态

- [获取能力清单](https://dev.marginnote.com.cn/api-reference/能力与状态/获取能力清单.md): 返回 MarginNote 实际注册的全部路由，以及各主题的上限与语义。
- [获取运行状态](https://dev.marginnote.com.cn/api-reference/能力与状态/获取运行状态.md): 返回 App 名称与版本、接口版本、注册的路由条数、路由目录校验值，以及运行规程的版本与哈希。
- [获取运行时规程](https://dev.marginnote.com.cn/api-reference/能力与状态/获取运行时规程.md): 返回一份 Markdown 文档，内容是 MarginNote 写给接入方的运行时规程：连接与鉴权、各接口的 Request Body 写法、 以及一批使用上的陷阱。 整张路由表里只有该接口返回 Markdown，因此 `mn.api` 无法读取。`mn.api` 相当于 `fetch('/bridge/v1' + path, opts).then(r => r.json())`，始终按 JSON 解析， Markdown 会让 `mn.api` 抛出 `SyntaxError`。读取该接口须改用 `fetch`。
- [获取操作上下文](https://dev.marginnote.com.cn/api-reference/能力与状态/获取操作上下文.md): 返回当前打开的学习集与文档、当前页、选中的卡与焦点卡。与 `GET /ui-state` 的分工： 该接口返回整理过的语义，`/ui-state` 返回界面自己的键值。

### 插件辅助

- [获取本机 helper skill](https://dev.marginnote.com.cn/api-reference/插件辅助/获取本机-helper-skill.md): 返回本机 Agent 可安装的 MarginNote Bridge helper skill 内容与安装提示。该接口只读，不安装文件。
- [获取 shell 刷新脚本](https://dev.marginnote.com.cn/api-reference/插件辅助/获取-shell-刷新脚本.md): 返回用于刷新本机 helper skill 的 shell 脚本。响应不是 JSON，要用 `fetch` 按文本读取。
- [获取 PowerShell 刷新脚本](https://dev.marginnote.com.cn/api-reference/插件辅助/获取-powershell-刷新脚本.md): 返回用于刷新本机 helper skill 的 PowerShell 脚本。响应不是 JSON，要用 `fetch` 按文本读取。
- [列出已配对设备](https://dev.marginnote.com.cn/api-reference/插件辅助/列出已配对设备.md): 返回本机已配对设备的摘要。该响应不包含令牌材料，只用于让调用方知道本机记录过哪些设备。

### 卡片与摘录

- [批量获取卡片](https://dev.marginnote.com.cn/api-reference/卡片与摘录/批量获取卡片.md): 按 id 一次读多张卡：标题与预览、文本项、二进制项、样式级别、标签、插件保存的字段、 以及内容的来源。
- [更新卡片插件字段](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新卡片插件字段.md): 把插件自己的数据写到卡片上，单次上限为 200 张卡与 50 个键。值写 `null` 表示删掉该键。
- [更新卡片标签](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新卡片标签.md): 一次给多张卡加标签、摘标签或替换标签，一次最多 200 张卡、100 个标签。 每个标签写一条完整的叶子路径，层级之间用 `/` 分隔。
- [更新卡片样式级别](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新卡片样式级别.md): 改摘录的颜色与样式级别，单次上限为 200 张卡。颜色编号取 0 到 15，每一个编号的实际颜色随 学习集色板变化，用 `GET /study-sets/{topicid}/note-palette` 读当前这套色板。 样式级别取 -1 到 2，管的是来源摘录的样式，不是脑图卡片本身的底色。
- [复制卡片分支](https://dev.marginnote.com.cn/api-reference/卡片与摘录/复制卡片分支.md): 把所选的根卡连同该卡在脑图上的全部下层复制到目标父卡下，单次上限为 50 个根。
- [移动卡片](https://dev.marginnote.com.cn/api-reference/卡片与摘录/移动卡片.md): 在学习集内部换父卡，不改内容、不删卡。单次合计上限为 50 张。
- [折叠或展开脑图节点](https://dev.marginnote.com.cn/api-reference/卡片与摘录/折叠或展开脑图节点.md): 只改脑图上的显示状态，不动内容。单次上限为 200 张卡。这是开销最小的写操作， 但仍然会在撤销栈上占一步。
- [定位卡片](https://dev.marginnote.com.cn/api-reference/卡片与摘录/定位卡片.md): 把界面切到该卡，并连带切到该卡所属的学习集、卡组或文档。同一张卡被多个学习集引用时， 用 `topicid` 指定打开的学习集。
- [创建摘录](https://dev.marginnote.com.cn/api-reference/卡片与摘录/创建摘录.md): 用一把摘录工具或一个划线快捷项，在文档的指定位置摘一条。摘录走模板配置的流程， 摘出来的卡带上工具配置好的标签、颜色与 AI 归属。
- [列出卡片可用插件命令](https://dev.marginnote.com.cn/api-reference/卡片与摘录/列出卡片可用插件命令.md): 返回该卡当前菜单上可用的插件命令，以及插件存在该卡上的字段。
- [打开作答纸](https://dev.marginnote.com.cn/api-reference/卡片与摘录/打开作答纸.md): 打开该题卡的图片底图批注稿，也就是作答纸，或者继续已有的一份。
- [列出卡片留白带](https://dev.marginnote.com.cn/api-reference/卡片与摘录/列出卡片留白带.md): 按追加顺序返回该卡下面的留白带，每一项返回该条带在文档里的位置、是否折叠、高度、 是否带笔迹，以及是否正在使用。
- [创建留白带](https://dev.marginnote.com.cn/api-reference/卡片与摘录/创建留白带.md): 在该卡下面追加一条留白带。MarginNote 无法建立时返回 `409`，响应里带一个稳定的原因码， 例如没有选区、插入被拒、物理保存失败。该情形不得视为已经建立。
- [更新留白带](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新留白带.md): 折叠、展开或改高一条留白带。带高限定在 50 到 4000 之间。
- [定位留白带](https://dev.marginnote.com.cn/api-reference/卡片与摘录/定位留白带.md): 先把该条带展开，再把文档翻到该条带所在页。该操作只在该文档正开在屏幕上时成立， 否则返回 `409 DOCUMENT_NOT_ON_SCREEN`。
- [列出卡片批注](https://dev.marginnote.com.cn/api-reference/卡片与摘录/列出卡片批注.md): 返回该卡的全部批注，包含作答纸类，同时返回当前版本号。更新与删除批注都要携带该版本号。
- [添加批注](https://dev.marginnote.com.cn/api-reference/卡片与摘录/添加批注.md): 追加一条批注。正文整条写成一个指向别处的应用内链接时，该条批注成为真正的双向链接。
- [折叠或展开卡片批注](https://dev.marginnote.com.cn/api-reference/卡片与摘录/折叠或展开卡片批注.md): 修改一条或多条批注的折叠状态。该接口改的是批注列表里的 Comment 级状态，不是脑图分支的 `collapsed` / `mindclose` 状态。
- [更新批注](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新批注.md): 改写第 `index` 条批注。序号从 1 起，序号 0 是卡片自身正文，指向该序号的请求返回 `422`。
- [删除批注](https://dev.marginnote.com.cn/api-reference/卡片与摘录/删除批注.md): 删除第 `index` 条批注。序号从 1 起。`expectedPrefix` 是该条批注当前内容的前 32 个字， 读完到写之间内容已变则返回 `409 COMMENT_CHANGED`。
- [一次提交多步卡片改动](https://dev.marginnote.com.cn/api-reference/卡片与摘录/一次提交多步卡片改动.md): 一个动作要改动多项时使用该接口：改标题、加批注、删批注、摘标签、记插件字段，写在一次提交里 提交，在撤销栈上只占一步。
- [将分支折叠为子脑图](https://dev.marginnote.com.cn/api-reference/卡片与摘录/将分支折叠为子脑图.md): 把该卡的整个分支折成一张子脑图。带 `undo` 传 `true` 时恢复为普通分支。
- [合并子卡](https://dev.marginnote.com.cn/api-reference/卡片与摘录/合并子卡.md): 把子卡的内容并进该卡，等同于卡片菜单上的合并分支。默认只并直接子卡， 带 `recursive` 时连整棵子树一起并。
- [提交作答判定](https://dev.marginnote.com.cn/api-reference/卡片与摘录/提交作答判定.md): 把本次作答的判定写下来：是否掌握，以及错因。
- [获取卡片渲染图](https://dev.marginnote.com.cn/api-reference/卡片与摘录/获取卡片渲染图.md): 把标题、正文、摘录图、插图与手写合成一张完整的卡片长图或一份 PDF。
- [更新卡片正文](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新卡片正文.md): 改该卡的正文。留白实体的正文也用该接口写入，目标传 `kind` 为留白的那一项的 id。
- [更新卡片标题](https://dev.marginnote.com.cn/api-reference/卡片与摘录/更新卡片标题.md): 改该卡的标题。字段名是 `text`，不是 `title`。清空标题传空串。
- [获取卡片媒体文件](https://dev.marginnote.com.cn/api-reference/卡片与摘录/获取卡片媒体文件.md): 按 `contentId` 取回卡片上某一项二进制内容的原始字节。`contentId` 取自 `POST /notes/batch-get` 响应里 `items[].parts[].contentId`。

### 导出与 Anki

- [获取 Anki 导出能力](https://dev.marginnote.com.cn/api-reference/导出与-anki/获取-anki-导出能力.md): 返回 Anki 导出相关的格式、上限、作业与上传路由。具体 request/response 字段随宿主版本扩展， 调用前应优先读取该接口。
- [查询 Anki 作业](https://dev.marginnote.com.cn/api-reference/导出与-anki/查询-anki-作业.md): 查询 Anki 导出、预览、校验或检查作业的状态。作业产物是会话内对象，重启或清理后可能返回 `404`。
- [下载 Anki 作业产物](https://dev.marginnote.com.cn/api-reference/导出与-anki/下载-anki-作业产物.md): 下载 Anki 作业生成的产物。带 `name` 查询参数指定产物名，例如 `collection.apkg`。 响应不是 JSON，页面里要用 `fetch` 原语读取 Blob。
- [查询文档导出计划](https://dev.marginnote.com.cn/api-reference/导出与-anki/查询文档导出计划.md): 查询 `POST /documents/{bookmd5}/export-plan` 创建的导出计划状态。计划是会话内对象， 重启或清理后可能返回 `404`。
- [取消文档导出计划](https://dev.marginnote.com.cn/api-reference/导出与-anki/取消文档导出计划.md): 取消正在准备的文档导出计划。已完成或不存在的计划可能返回错误对象。
- [丢弃文档导出计划](https://dev.marginnote.com.cn/api-reference/导出与-anki/丢弃文档导出计划.md): 丢弃导出计划及其会话内状态。该操作不会修改文档或学习集。
- [下载文档导出文件](https://dev.marginnote.com.cn/api-reference/导出与-anki/下载文档导出文件.md): 下载文档导出的产物。响应不是 JSON，页面里要用 `fetch` 原语读取 Blob。

### 手写会话

- [列出已打开的学习窗口](https://dev.marginnote.com.cn/api-reference/手写会话/列出已打开的学习窗口.md): 列出当前打开的学习窗口。每项返回窗口身份、场景身份与该窗口打开的学习集。
- [获取手写能力清单](https://dev.marginnote.com.cn/api-reference/手写会话/获取手写能力清单.md): 调用手写会话的其他路由之前须先读取该接口，确认 MarginNote 支持的子能力。
- [获取手写上下文](https://dev.marginnote.com.cn/api-reference/手写会话/获取手写上下文.md): 返回该面板所对的窗口与学习集，以及当前可见的各个工作面。该结果是观察所得，不构成保存或切题的许可， 因此响应里的 `readOnly` 为真、`mutationAuthority` 为假。
- [查询留白与焦点存储身份](https://dev.marginnote.com.cn/api-reference/手写会话/查询留白与焦点存储身份.md): 只读诊断：读某张本地题卡的来源候选、本地合并留白与焦点存储身份。
- [解析题卡来源](https://dev.marginnote.com.cn/api-reference/手写会话/解析题卡来源.md): 只读诊断：传入一道题，返回该题的来源候选、本地合并留白与焦点存储身份。 同样不创建、不认领、不折叠。
- [查询手写层租约](https://dev.marginnote.com.cn/api-reference/手写会话/查询手写层租约.md): 只读诊断：返回未收尾的临时手写层占用。上一次操作失联时先读该接口，再决定是否走恢复流程。
- [压缩手写层](https://dev.marginnote.com.cn/api-reference/手写会话/压缩手写层.md): 收拢手写层的租约存储。只丢弃所属会话已经记录退出的、彻底了结的租约；笔迹、卡片与留白 不受影响。
- [保存焦点画布的笔迹](https://dev.marginnote.com.cn/api-reference/手写会话/保存焦点画布的笔迹.md): 将当前焦点根画布上的笔迹保存为快照。该接口只作用于当前焦点根画布，不写入整份编辑器，也不切换题目。
- [保存文档页上的笔迹](https://dev.marginnote.com.cn/api-reference/手写会话/保存文档页上的笔迹.md): 把文档阅读器里可见页画布上的笔迹存成快照，连续阅读与翻页模式都支持。
- [查询笔迹保存结果](https://dev.marginnote.com.cn/api-reference/手写会话/查询笔迹保存结果.md): 用提交时的 `requestId` 查同一笔操作的最终结果。
- [查询练习准备清单](https://dev.marginnote.com.cn/api-reference/手写会话/查询练习准备清单.md): 读这台设备上这本学习集的练习准备清单。该清单是准备记录，不代表已经进入作答。
- [保存练习准备选择](https://dev.marginnote.com.cn/api-reference/手写会话/保存练习准备选择.md): 保存这本学习集的练习准备选择。该接口只记录本次意图，不展开留白，不切层，不导航， 也不修改学习集。
- [查询练习会话记录](https://dev.marginnote.com.cn/api-reference/手写会话/查询练习会话记录.md): 读这台设备上的练习会话记录：每一趟、每次尝试、每次浏览，以及暂停与历史。 没有记录时返回空数组，状态码仍为 `200`。
- [查询作答预览](https://dev.marginnote.com.cn/api-reference/手写会话/查询作答预览.md): 以只读方式取某一趟作答中已退出的尝试的专用层中已保存的笔迹，可以附带一张有 尺寸上限的预览图。
- [创建练习会话](https://dev.marginnote.com.cn/api-reference/手写会话/创建练习会话.md): 基于已保存的练习准备清单创建一趟练习会话记录。该族接口的返回是进程内状态， 不能替代重新读取 `POST /writing/session-read`。
- [预留下一次练习尝试](https://dev.marginnote.com.cn/api-reference/手写会话/预留下一次练习尝试.md): 为当前练习会话预留一次尝试。响应只表示该次命令的处理结果；之后应按 `requestId` 或重新读取会话记录确认。
- [取消练习会话](https://dev.marginnote.com.cn/api-reference/手写会话/取消练习会话.md): 取消当前练习会话或指定运行记录。取消之后应重新读取会话状态。
- [暂停练习会话](https://dev.marginnote.com.cn/api-reference/手写会话/暂停练习会话.md): 暂停当前练习会话。该命令只写会话记录，不代表当前画布已经保存。
- [恢复练习会话](https://dev.marginnote.com.cn/api-reference/手写会话/恢复练习会话.md): 恢复之前暂停的练习会话。恢复后仍需看 `ready` 与 `canSwitch` 判断当前是否能切题。
- [结束练习会话](https://dev.marginnote.com.cn/api-reference/手写会话/结束练习会话.md): 将当前练习会话标记为完成。完成状态应以重新读取的会话记录为准。
- [记录练习评估](https://dev.marginnote.com.cn/api-reference/手写会话/记录练习评估.md): 为当前练习会话或指定尝试记录评估结果。字段细节以运行时 `GET /guide` 为准。
- [对齐练习会话记录](https://dev.marginnote.com.cn/api-reference/手写会话/对齐练习会话记录.md): 将练习会话记录与当前窗口观察到的状态对齐。该操作可能返回需要调用方重新读取的状态。
- [进入焦点卡作答](https://dev.marginnote.com.cn/api-reference/手写会话/进入焦点卡作答.md): 从当前窗口进入焦点卡作答流程。是否真的可进入由运行时的 `ready`、`canSwitch` 与返回结果决定。
- [准备留白作答空间](https://dev.marginnote.com.cn/api-reference/手写会话/准备留白作答空间.md): 为留白作答准备空间，但不等同于已经进入留白页。后续结果看 `POST /writing/transition-result`。
- [进入留白作答](https://dev.marginnote.com.cn/api-reference/手写会话/进入留白作答.md): 进入题目对应的留白作答位置。该接口可能触发窗口转场，调用后应查询转场结果。
- [开始焦点卡分层练习](https://dev.marginnote.com.cn/api-reference/手写会话/开始焦点卡分层练习.md): 在受控练习层里开始焦点卡作答。该族接口可能保留手写层租约，失败后不要盲目重试。
- [开始留白分层练习](https://dev.marginnote.com.cn/api-reference/手写会话/开始留白分层练习.md): 在受控练习层里开始留白作答。调用前应先读取写作能力与当前窗口上下文。
- [恢复练习手写层](https://dev.marginnote.com.cn/api-reference/手写会话/恢复练习手写层.md): 将受控练习层恢复到当前窗口。恢复是否完成看转场结果，不要仅凭 HTTP 状态码判断。
- [在练习会话中开始焦点卡作答](https://dev.marginnote.com.cn/api-reference/手写会话/在练习会话中开始焦点卡作答.md): 会话版焦点卡开始命令，会同时关联练习会话记录。字段细节以运行时 `GET /guide` 为准。
- [在练习会话中开始留白作答](https://dev.marginnote.com.cn/api-reference/手写会话/在练习会话中开始留白作答.md): 会话版留白开始命令，会同时关联练习会话记录。字段细节以运行时 `GET /guide` 为准。
- [恢复练习会话手写层](https://dev.marginnote.com.cn/api-reference/手写会话/恢复练习会话手写层.md): 恢复某次练习会话关联的手写层。调用后应重新读取会话记录或查询转场结果。
- [在练习会话中进入焦点卡作答](https://dev.marginnote.com.cn/api-reference/手写会话/在练习会话中进入焦点卡作答.md): 会话版焦点卡进入命令。该路由只应由当前练习面板在自己的窗口里调用。
- [在练习会话中进入留白作答](https://dev.marginnote.com.cn/api-reference/手写会话/在练习会话中进入留白作答.md): 会话版留白进入命令。该路由只应由当前练习面板在自己的窗口里调用。
- [退出当前练习尝试](https://dev.marginnote.com.cn/api-reference/手写会话/退出当前练习尝试.md): 退出当前练习尝试并记录可恢复状态。退出不等于笔迹一定已经持久化，之后应读取会话记录。
- [查询作答转场结果](https://dev.marginnote.com.cn/api-reference/手写会话/查询作答转场结果.md): 用发起转场时的 `requestId` 查询结果。查不到记录时不代表转场没有发生，只说明本进程没有这笔记录。

### 学习集与卡组

- [获取学习集脑图](https://dev.marginnote.com.cn/api-reference/学习集与卡组/获取学习集脑图.md): 读整个学习集的脑图结构、标题与逻辑属性。
- [列出子脑图](https://dev.marginnote.com.cn/api-reference/学习集与卡组/列出子脑图.md): 列出该学习集里的子脑图，顺序与界面一致。子脑图可以嵌套， 深度大于 0 表示这张卡套在别的子脑图里，`parentPath` 从外到内列出祖先。
- [列出文档笔记本](https://dev.marginnote.com.cn/api-reference/学习集与卡组/列出文档笔记本.md): 列出该学习集引用的文档笔记本。
- [列出学习集文档](https://dev.marginnote.com.cn/api-reference/学习集与卡组/列出学习集文档.md): 列出该学习集里的文档。没有列出全库文档的接口，跨学习集查找文档要用搜索接口。
- [获取标签树](https://dev.marginnote.com.cn/api-reference/学习集与卡组/获取标签树.md): 读整个学习集的标签：实际存储的标签、扁平展开的层级、嵌套的层级树。
- [获取色板](https://dev.marginnote.com.cn/api-reference/学习集与卡组/获取色板.md): 读该学习集实际使用的那套摘录色板。
- [列出快照](https://dev.marginnote.com.cn/api-reference/学习集与卡组/列出快照.md): 列出快照，用于核对打点是否生效。
- [列出复习卡组](https://dev.marginnote.com.cn/api-reference/学习集与卡组/列出复习卡组.md): 列出复习卡组。卡组与学习集是两种对象，id 不通用，因此列学习集的接口不返回卡组。
- [列出卡组复习卡](https://dev.marginnote.com.cn/api-reference/学习集与卡组/列出卡组复习卡.md): 列出卡组里的复习卡。每项返回复习卡本身、该卡对应的背面卡片，以及背面卡片是否存在（见 `sourceAlive` 字段）。

### 文档与页面

- [列出文档摘录](https://dev.marginnote.com.cn/api-reference/文档与页面/列出文档摘录.md): 列出这本书上当前的全部摘录，并标出位置重复的段。
- [获取文档目录](https://dev.marginnote.com.cn/api-reference/文档与页面/获取文档目录.md): 读文档的章节目录与各自的页范围，用于按章取内容。
- [获取文档页文本](https://dev.marginnote.com.cn/api-reference/文档与页面/获取文档页文本.md): 按页范围读文本。没有文本层时 MarginNote 会先渲染再识别，因此该接口可能较慢。
- [获取页面注释面](https://dev.marginnote.com.cn/api-reference/文档与页面/获取页面注释面.md): 读该页上的视觉注释面：手写、插入的留白、按选择生成的留白，以及这些内容与 MarginNote 记录的对应关系。
- [获取页面媒体文件](https://dev.marginnote.com.cn/api-reference/文档与页面/获取页面媒体文件.md): 按 `contentId` 取回某一页上某项二进制内容的原始字节，例如手写与留白的合成图。 `contentId` 取自 `GET /documents/{bookmd5}/pages/{index}/parts`。
- [获取文档同步状态](https://dev.marginnote.com.cn/api-reference/文档与页面/获取文档同步状态.md): 核对该文档的数据库引用、云端范围、本地与云端映射、下载队列与陈旧映射。
- [扫描目录候选](https://dev.marginnote.com.cn/api-reference/文档与页面/扫描目录候选.md): 在端上渲染、识别并跑版面模型，找出可以作为目录条目的标题候选。该接口开销较大， 扫描件上大约每页三秒。

### 查找

- [搜索资料库](https://dev.marginnote.com.cn/api-reference/查找/搜索资料库.md): 在整个资料库里搜索，匹配分卡片、学习集与文档。用 `scope` 限定匹配的类别。
- [列出文档文件夹](https://dev.marginnote.com.cn/api-reference/查找/列出文档文件夹.md): 列出文档文件夹。文件夹是文档根目录下的真实目录，层级用 `/` 分隔，根目录传空串。
- [列出学习集](https://dev.marginnote.com.cn/api-reference/查找/列出学习集.md): 列出资料库里的学习集。该接口不列复习卡组，卡组要用另一个接口列出。

### 界面与模板

- [获取界面状态](https://dev.marginnote.com.cn/api-reference/界面与模板/获取界面状态.md): 返回当前界面状态的键值。插件常用的键包括当前学习集的标识、当前焦点卡的标识、 当前文档的内容标识，以及是否处在沉浸态。
- [获取沉浸模板](https://dev.marginnote.com.cn/api-reference/界面与模板/获取沉浸模板.md): 读取当前模板的完整内容：模板摘要、各插件的可用状态与配置、摘录工具、划线快捷项、 复习入组规则、模板预设，以及声明的 AI 任务。
- [列出沉浸模板](https://dev.marginnote.com.cn/api-reference/界面与模板/列出沉浸模板.md): 列出可以切换的全部模板，每项返回标识、名称、是否内置与是否当前在用。

### 任务包与同步诊断

- [列出任务包](https://dev.marginnote.com.cn/api-reference/任务包与同步诊断/列出任务包.md): 列出现存的拆书任务包，包含运行中的作业，以及 App 重启后留在磁盘上的目录。各条目的字段含义见 `BundleEntry`。
- [列出任务包文件](https://dev.marginnote.com.cn/api-reference/任务包与同步诊断/列出任务包文件.md): 不带 `path` 时列出包内文件。带 `path` 时返回该文件的原始内容，路径相对包根，层级用 `/` 分隔。
- [查询旧同步事件](https://dev.marginnote.com.cn/api-reference/任务包与同步诊断/查询旧同步事件.md): 按本设备的序号增量读取同步事件。一次取 1 到 200 条，默认 50 条。
- [获取旧同步状态](https://dev.marginnote.com.cn/api-reference/任务包与同步诊断/获取旧同步状态.md): 读整机的旧同步诊断快照。响应里不含笔记正文、文档名、账号与云端记录标识。

## Other

- [AGENTS](https://dev.marginnote.com.cn/AGENTS.md)

## OpenAPI Specs

- [plugin-api](/openapi/plugin-api.yaml)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [English (2 pages)](https://dev.marginnote.com.cn/_llms/en.txt): Documentation for English.


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