> ## 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. # 获取旧同步状态 > 读整机的旧同步诊断快照。响应里不含笔记正文、文档名、账号与云端记录标识。 旧同步分两条通道：一条携带学习集结构与学习数据，另一条携带普通原始文档字节。 两条会先后完成，其中一条完成不证明另一条也完成。 `cloudKit.errorCount` 是本进程保留的历史诊断数。状态为暂停时要看 `cloudKit.suspensionNeedsAttention`，该字段为假可以是正常增量拉取的临时暂停，为真才 表示本轮暂停里出过错。本轮的错误次数读 `cloudKit.suspensionErrorCount`，不要用历史总数代替。 ## OpenAPI ````yaml /openapi/plugin-api.yaml get /sync/legacy/status 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: /sync/legacy/status: get: tags: - 任务包与同步诊断 summary: 获取旧同步状态 description: | 读整机的旧同步诊断快照。响应里不含笔记正文、文档名、账号与云端记录标识。 旧同步分两条通道：一条携带学习集结构与学习数据，另一条携带普通原始文档字节。 两条会先后完成，其中一条完成不证明另一条也完成。 `cloudKit.errorCount` 是本进程保留的历史诊断数。状态为暂停时要看 `cloudKit.suspensionNeedsAttention`，该字段为假可以是正常增量拉取的临时暂停，为真才 表示本轮暂停里出过错。本轮的错误次数读 `cloudKit.suspensionErrorCount`，不要用历史总数代替。 operationId: getSyncLegacyStatus responses: '200': description: 整机的同步诊断快照。云端分组的错误计数与暂停标志有据，其余子字段未取到。 content: application/json: schema: $ref: '#/components/schemas/LegacySyncStatusResponse' examples: assembled: summary: 云端分组构造示例，其余子字段为占位 value: cloudKit: state: suspended errorCount: 12 suspensionNeedsAttention: true suspensionErrorCount: 3 documents: placeholder: true diagnostic: placeholder: true measured: summary: 实测于 2026-10-07，App 0.91 value: documents: studySetDocumentSyncEnabled: true scanReason: '' coverage: excludedTopicWithoutNotesCount: 101 unknownBookConfigCount: 1 schema: 1 excludedLocalOnlyTopicCount: 2 externalProviderOnlyCount: 0 referencedDocumentCount: 1 blankNotebookCount: 0 iCloudPresenceUnverifiedCount: 0 specialDocumentCount: 1 generatedAt: 1791365214.6506371 linkedDocumentCount: 0 availableOnDeviceCount: 0 activeTopicCount: 104 missingDocumentCount: 0 specialDocumentUnresolvedCount: 1 localOnlyDocumentCount: 0 publishedToICloudCount: 0 scope: definite_cloudkit_topics_with_notes notebookOnlyLocalDocumentCount: 0 channel: 0 inScopeTopicCount: 1 embeddedCloudKitAssetCount: 0 specialDocumentPresentCount: 0 status: complete staleCloudMappingCount: 0 iCloudReportedUploadedCount: 0 ordinaryPhysicalDocumentCount: 0 pendingICloudUploadCount: 0 manualScopeUnverifiedTopicCount: 0 ordinaryNeedsAttentionCount: 0 manualScopeUnverifiedDocumentCount: 0 definiteScopeDocumentCount: 1 potentialRepairCandidateCount: 0 iCloudUploadErrorCount: 0 containerAvailable: 1 recheckOperation: null urlInitialized: true placeholderCount: 0 pendingUbiquitousItemCount: 0 scanState: complete enabled: true lastScanAt: 1791365214.648463 recheckInFlight: false downloadQueueCount: 0 status: needs_attention cloudKit: suspensionActivity: '' resumePending: false downloadingTopicCount: 0 status: idle failedFetchRecordCount: 0 needsFetch: 0 lastFetchHadNoData: false inventory: authoritative: false generation: 0 observeOnly: true queryComplete: false status: not_run verified: false initialFetchPending: false accountStatus: 1 authenticated: true suspensionErrorCount: 0 longLivedOperationPending: false pendingTopicCount: 0 errorCount: 0 enabled: true suspendCount: 0 scheduledRetryCount: 0 pendingDocumentHashCount: 0 needsSync: false suspensionNeedsAttention: false conflictCount: 0 bufferedApplyRecordCount: 0 suspended: false needsBookMetadataSync: false diagnostic: activeRuns: cloudkit: status: skipped id: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 lastEventAt: 1791365343.301554 phase: notebook_upload event: cloudkit_upload_finished startedAt: 1791365215.948278 documents: status: complete id: 0D89718C-87A8-4B5C-A1BA-5C7D7C826275 lastEventAt: 1791365214.6520848 phase: icloud_documents event: document_coverage_reconciled startedAt: 1791365214.64847 recentEvents: - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365214.90275 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: true pendingCount: 2 reason: suspend_counter_incremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 458 status: paused build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365214.902766 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: true pendingCount: 3 reason: suspend_counter_incremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 459 status: paused build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365214.90277 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: true pendingCount: 4 reason: suspend_counter_incremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 460 status: paused build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365214.903276 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: true pendingCount: 3 reason: suspend_counter_decremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 461 status: paused build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365214.9940848 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: true pendingCount: 2 reason: suspend_counter_decremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 462 status: paused build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365215.77558 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: true pendingCount: 1 reason: suspend_counter_decremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 463 status: paused build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365215.778368 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_fetch_started phase: fetch_changes details: source: incremental_token appVersion: 4.5.0 sequence: 464 status: running build: '45058' - run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365215.940711 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_fetch_finished phase: fetch_changes details: bookConfigRecordCount: 0 mediaRecordCount: 0 errorCode: 0 deletedCount: 2 changedCount: 8 errorDomain: '' otherRecordCount: 6 moreComing: false noteRecordCount: 0 topicRecordCount: 2 appVersion: 4.5.0 sequence: 466 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365215.948278 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_fetch_started phase: fetch_changes details: source: incremental_token appVersion: 4.5.0 sequence: 467 status: running build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.069344 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_fetch_finished phase: fetch_changes details: bookConfigRecordCount: 0 mediaRecordCount: 0 topicRecordCount: 2 errorCode: 0 changedCount: 8 errorDomain: '' otherRecordCount: 6 moreComing: false noteRecordCount: 0 deletedCount: 2 appVersion: 4.5.0 sequence: 470 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.153444 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_preapply_backup_finished phase: apply_buffer details: result: protection_version_available snapshotCreated: true durationMs: 45 appVersion: 4.5.0 sequence: 473 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.2654052 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_token_stage_finished phase: cursor_persistence details: result: token_staged_with_pending_changes appVersion: 4.5.0 sequence: 482 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.276351 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_apply_save_finished phase: apply_buffer details: result: database_and_apply_buffer_saved appVersion: 4.5.0 sequence: 484 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.284607 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_suspension_changed phase: suspension details: initialFetchPending: false pendingCount: 0 reason: suspend_counter_decremented longLivedOperationPending: false resumePending: false appVersion: 4.5.0 sequence: 486 status: resumed build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.4267879 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_upload_finished phase: book_tags_upload details: savedCount: 0 errorCode: 0 errorDomain: '' deletedCount: 0 appVersion: 4.5.0 sequence: 488 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365311.469534 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_upload_finished phase: notebook_upload details: savedCount: 3 errorCode: 0 errorDomain: '' deletedCount: 0 appVersion: 4.5.0 sequence: 489 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365311.488318 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_apply_save_finished phase: apply_buffer details: result: database_and_apply_buffer_saved appVersion: 4.5.0 sequence: 491 status: complete build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365343.294983 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_upload_finished phase: notebook_upload details: reason: study_set_not_synced appVersion: 4.5.0 sequence: 493 status: skipped build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365343.298184 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_upload_finished phase: notebook_upload details: reason: study_set_not_synced appVersion: 4.5.0 sequence: 494 status: skipped build: '45058' - run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365343.301554 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_upload_finished phase: notebook_upload details: reason: study_set_not_synced appVersion: 4.5.0 sequence: 495 status: skipped build: '45058' sequence: 495 activeIssues: [] lastIssue: firstSeenAt: 1788746173.537715 ticket: 787122ac5b06 event: cloudkit_fetch_finished lane: cloudkit phase: fetch_changes reason: '' errorDomain: CKErrorDomain lastSeenAt: 1788747197.50435 occurrences: 6 severity: error errorCode: 4 status: failed updatedAt: 1791365343.301554 pipeline: page: run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.4178472 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: legacy_sync_checkpoint phase: pipeline_observation details: observeOnly: true pageFingerprint: 0a7271077ad16f1b1a19fa5aaa2f348a component: page operation: E7CACA61-C0D7-4137-B735-68494BD44C33 nextTokenFingerprint: c643f8b62fb6d95f92a890ca84a6b9eb deletedCount: 2 moreComing: false previousTokenFingerprint: 7e2d6a89255a758c60c840cb1a7ae68e durationMs: 348.53516664588824 result: callback_exit needKeys: true changedCount: 8 uptime: 156503.1931581667 appVersion: 4.5.0 sequence: 487 status: returned build: '45058' buffer: run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.264827 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: legacy_sync_checkpoint phase: pipeline_observation details: uptime: 156503.301324 result: applied_in_memory operation: 224343BB-48C1-4C86-B16B-9FE3BF408230 recordCount: 2 skippedTopicCount: 0 component: buffer durationMs: 87.34741667285562 observeOnly: true appVersion: 4.5.0 sequence: 481 status: returned build: '45058' lifecycle: run: A380A527-3A29-40E5-B176-6A248710B983 timestamp: 1791365213.682653 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: legacy_sync_checkpoint phase: pipeline_observation details: component: lifecycle result: app_foreground uptime: 156500.80652658333 appVersion: 4.5.0 sequence: 454 status: observed build: '45058' save: run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365311.488342 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: legacy_sync_checkpoint phase: pipeline_observation details: component: save operation: 7A163D1A-FCB5-4D3C-AD14-308C92794059 uptime: 156598.60262695834 result: save_call_succeeded observeOnly: true durationMs: 8.710208348929882 appVersion: 4.5.0 sequence: 492 status: returned build: '45058' backup: run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365216.153475 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: legacy_sync_checkpoint phase: pipeline_observation details: uptime: 156503.23184762502 result: created operation: A395BF07-89D2-4753-8EDE-25D10EF9736E contextHasChanges: false component: backup durationMs: 45.47745833406225 observeOnly: true topicFingerprint: 9cba754d30a57c122d2713ecce359134 appVersion: 4.5.0 sequence: 474 status: returned build: '45058' lastEvent: run: 473E5D58-49CA-46FA-A5F8-FDFF3CDD4581 timestamp: 1791365343.301554 lane: cloudkit schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 event: cloudkit_upload_finished phase: notebook_upload details: reason: study_set_not_synced appVersion: 4.5.0 sequence: 495 status: skipped build: '45058' lastCompleteSyncAt: 0 schema: 2 session: EA92DD99-04D9-4887-B75A-746457751BC1 generatedAt: 1791365390.7249131 bridgeApiVersion: '0.91' journal: currentBytes: 210509 rotatedBytes: 0 checkpointEvidence: pending: 0 durationsIncludeBackgroundTime: true fingerprintScope: process_session dropped: 0 privacy: containsAccountIdentifiers: false containsDocumentNames: false containsNoteContent: false containsRecordIdentifiers: false environment: platform: ios channel: 0 appVersion: 4.5.0 build: '45058' x-codeSamples: - lang: javascript label: 判断暂停是否需要处理 source: | const r = await mn.api('/sync/legacy/status'); const ck = r.cloudKit || {}; if (ck.state === 'suspended' && ck.suspensionNeedsAttention) { mn.log('本轮暂停里出错 ' + ck.suspensionErrorCount + ' 次'); } components: schemas: LegacySyncStatusResponse: type: object description: 整机的同步诊断快照。不含笔记正文、文档名、账号与云端记录标识。 properties: cloudKit: type: object properties: errorCount: type: number description: 本进程保留的历史诊断数。 suspensionNeedsAttention: type: boolean description: 状态为暂停时必须看该项。为 `false` 时暂停可能只是正常的增量拉取间歇。 suspensionErrorCount: type: number description: 本轮暂停里的错误次数。不要用历史总数代替。 additionalProperties: true documents: type: object additionalProperties: true diagnostic: type: object additionalProperties: true ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.