> ## 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. # 获取手写上下文 > 返回该面板所对的窗口与学习集，以及当前可见的各个工作面。该结果是观察所得，不构成保存或切题的许可， 因此响应里的 `readOnly` 为真、`mutationAuthority` 为假。 面板可以直接传空对象，窗口与身份由 MarginNote 注入，只能看到本面板所在的窗口。 不要自行传入窗口身份以指向其他窗口。窗口不在、学习集已换、窗口已关，都会拒绝。 工作面里可能出现内部留白页，那不是 PDF 页序，不要传给按页取内容的接口。 ## OpenAPI ````yaml /openapi/plugin-api.yaml post /writing/context 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: /writing/context: post: tags: - 手写会话 summary: 获取手写上下文 description: | 返回该面板所对的窗口与学习集，以及当前可见的各个工作面。该结果是观察所得，不构成保存或切题的许可， 因此响应里的 `readOnly` 为真、`mutationAuthority` 为假。 面板可以直接传空对象，窗口与身份由 MarginNote 注入，只能看到本面板所在的窗口。 不要自行传入窗口身份以指向其他窗口。窗口不在、学习集已换、窗口已关，都会拒绝。 工作面里可能出现内部留白页，那不是 PDF 页序，不要传给按页取内容的接口。 operationId: postWritingContext requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/WritingContextRequest' examples: panelSide: summary: 面板直接传空对象 value: {} responses: '200': description: 窗口与工作面。可能还有未列出的字段。 content: application/json: schema: $ref: '#/components/schemas/WritingContextResponse' examples: assembled: summary: 构造示例，未实测 value: schemaVersion: 1 readOnly: true consistency: live-window-observation window: windowId: 3F1A2B40-9C1D-4E2F-8A3B-5C6D7E8F9012 topicid: 77012CA0-48E8-4D29-B5F5-1EEA927AE086 origin: transport: panel ownerID: mn.cardpractice surfaces: [] ready: false mutationAuthority: false measured: summary: 实测于 2026-10-07，App 0.91 value: readOnly: true schemaVersion: 1 window: topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D sceneActivationState: 0 keyWindow: true sceneId: 5FFEE5A5-56F7-4E9F-9EF1-0D25B7DE53C4 windowId: 287538A6-9249-4FD6-B026-493466471716 hidden: false origin: ownerID: mn.apiprobe templateID: u-api-probe transport: panel consistency: live-window-observation warnings: - >- Observation only: not a save receipt, writable-ready token or session lease; state may change after return. - >- Document pages, loaded focus owner and requested focus owner are separate facts. Do not infer a question from selection. - >- Dirty/saving flags are diagnostic only; false does not prove that edits or pending formula/media work have been persisted. ready: false surfaces: - kind: document state: currentSurfacePage: 1 visiblePages: - visibleInWindow: - 0 - 805.427625734728 - 702 - 116.57237426527195 storagePage: 1 continuousBindingLoaded: false bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 continuousCommitTarget: topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D layerId: '' surfacePages: - 1 physicalPages: - storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 surfacePage: 1 storagePage: 1 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 frameInWindow: - 0 - 805.427625734728 - 702 - 168.9633027432585 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 pagedCommitTarget: pageNo: 1 storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storagePage: 1 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 layerId: '' topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D surfacePage: 1 blank: false pageCanvas: saveInFlight: false loadInFlight: false pencilCanvas: false dirty: false toolInUse: false ready: false - visibleInWindow: - 0 - 30 - 702 - 482.92762573472805 storagePage: 1 continuousBindingLoaded: false bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 continuousCommitTarget: topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D layerId: '' surfacePages: - 1 physicalPages: - storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 surfacePage: 1 storagePage: 1 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 frameInWindow: - 0 - -311.5 - 702 - 824.427625734728 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 pagedCommitTarget: pageNo: 1 storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storagePage: 1 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 layerId: '' topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D surfacePage: 1 blank: false pageCanvas: saveInFlight: false loadInFlight: false pencilCanvas: false dirty: false toolInUse: false ready: false - visibleInWindow: - 0 - 0 - 0 - 0 storagePage: 2 continuousBindingLoaded: false bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 continuousCommitTarget: topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D layerId: '' surfacePages: - 2 physicalPages: - storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 surfacePage: 2 storagePage: 2 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 frameInWindow: - 0 - 974.3909284779866 - 702 - 993.3909284779866 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 pagedCommitTarget: pageNo: 2 storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storagePage: 2 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 layerId: '' topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D surfacePage: 2 blank: false pageCanvas: saveInFlight: false loadInFlight: false pencilCanvas: false dirty: false toolInUse: false ready: false - visibleInWindow: - 0 - 512.927625734728 - 702 - 292.5 storagePage: 65795 continuousBindingLoaded: false bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 continuousCommitTarget: topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D layerId: '' surfacePages: - 65795 physicalPages: - storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 surfacePage: 65795 storagePage: 65795 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 frameInWindow: - 0 - 512.927625734728 - 702 - 292.5 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 pagedCommitTarget: pageNo: 65795 storageBookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storagePage: 65795 bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 layerId: '' topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D surfacePage: 65795 blank: true pageCanvas: saveInFlight: false loadInFlight: false pencilCanvas: false dirty: false toolInUse: false ready: false loadInFlight: false bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 ready: false continuousCanvas: false topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D pdfLoaded: true storageTopicId: B1F2A354-125A-4384-A271-C0B829AB9E09 dirtySurfacePages: [] toolInUse: false overlayLayerId: null saveInFlight: false activeLayerId: '' bindTextImageToLayer: false surfaceId: 8D01BA73-1CF6-4E6B-BCF1-9378B108C16B hiddenByHierarchy: false - kind: focus state: rootLoadInFlight: 0 visualFocusNoteId: null rootCanvasOwnerMatches: false readOnly: false filtered: false ready: false pencilCanvas: false dirty: false toolInUse: false topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D geometry: coordinateSpace: window-points scrollBounds: - 76921 - 76934.5 - 768 - 923 surfaceRect: - 702 - 0 - 768 - 923 canvasBounds: - 0 - 0 - 1250000 - 1250000 rootCards: [] occlusionChecked: false zoomScale: 0.12354458123445511 explicitBindingPresent: false loadedBinding: topicid: null noteid: null overlayLayerId: null activeLayerId: '' explicitBindingNoteId: null saveRootCandidateId: null rootBindingLoaded: false saveInFlight: 0 surfaceId: BDE030D4-4A6C-400E-B988-02A4B6A20307 hiddenByHierarchy: false capturedAt: 1791366872.646882 bridgeApiVersion: '0.91' mutationAuthority: false x-codeSamples: - lang: javascript label: 获取当前窗口与学习集 source: > // 不需要填窗口，MarginNote 会自己注入 const ctx = await mn.api('/writing/context', { method: 'POST', body: {} }); if (ctx.error) { mn.log(ctx.error.code); return; } const topicid = ctx.window.topicid; components: schemas: WritingContextRequest: type: object description: 面板可以直接传空对象，窗口与身份由 MarginNote 注入。 properties: windowId: type: string expectedTopicId: type: string WritingContextResponse: type: object description: 该面板所对的窗口与学习集。该结果只是观察所得，不构成保存或切题的许可。 properties: schemaVersion: type: number readOnly: type: boolean description: 固定为 `true`。 consistency: type: string window: type: object properties: windowId: type: string topicid: type: string origin: type: object properties: transport: type: string description: 面板是 `panel`。 ownerID: type: string surfaces: type: array description: 当前可见的各个工作面。 items: type: object additionalProperties: true ready: type: boolean mutationAuthority: type: boolean surfacePage: type: string storagePage: type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.