{"openapi":"3.1.0","info":{"title":"Doco Open API","version":"1.9.0","description":"Doco 知识库、结构化读取、带新鲜度证明的搜索、显式关系、四层可追溯摘要、人机审核的显式概念层、多语言文档与机器翻译候选、文档正文、块、版本、块级变更水位、变更事件和附件开放 API。标准正文格式为 Tiptap/ProseMirror JSON。"},"servers":[{"url":"https://example.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Auth"},{"name":"Identity"},{"name":"Events"},{"name":"Search"},{"name":"Relations"},{"name":"Summaries"},{"name":"Concepts"},{"name":"KnowledgeBases"},{"name":"Folders"},{"name":"Documents"},{"name":"Translation"},{"name":"Content"},{"name":"Versions"},{"name":"Blocks"},{"name":"Attachments"}],"paths":{"/auth/device/code":{"post":{"tags":["Auth"],"security":[],"operationId":"requestDeviceCode","description":"设备授权流程第一步（CLI 登录）：申请 device_code 与 user_code，无需 Bearer。","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","maxLength":80},"scopes":{"type":["string","array"],"items":{"type":"string"},"description":"read_write（默认）、read_only 或权限数组"}}}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/auth/device/token":{"post":{"tags":["Auth"],"security":[],"operationId":"pollDeviceToken","description":"设备授权流程第二步：CLI 轮询换取 Token（RFC 8628 §3.4 用 POST，凭据不走 URL）。用户确认前返回 400 authorization_pending，过快返回 400 slow_down。签发的 Token 默认 90 天有效。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string"}}}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/me":{"get":{"tags":["Identity"],"operationId":"getCurrentCaller","responses":{"200":{"$ref":"#/components/responses/Success"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/me/quota":{"get":{"tags":["Identity"],"operationId":"getCurrentCallerQuota","description":"当前工作区的配额与用量自查（知识库数、文档与文件夹数、单文档字符上限等）","responses":{"200":{"$ref":"#/components/responses/Success"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/events":{"get":{"tags":["Events"],"operationId":"streamDocumentEvents","description":"使用 Server-Sent Events 推送当前用户可访问工作区中的文档创建、元数据修改、\n正文更新和删除事件。首次连接只接收连接后的新事件；断线重连时通过\nLast-Event-ID 续传。游标已超过保留期时先发送 sync.required。\n","parameters":[{"$ref":"#/components/parameters/LastEventId"},{"in":"query","name":"document_set_id","description":"只监听指定 Document Set 的事件","schema":{"type":"string"}},{"in":"query","name":"locale","description":"只监听指定语言版本的事件","schema":{"type":"string"}}],"responses":{"200":{"description":"文档变更事件流","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"text/event-stream":{"schema":{"type":"string","examples":["id: 42\nevent: document.content.updated\ndata: {\"document_id\":\"doc_123\",\"event_id\":42}\n\n"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search":{"get":{"tags":["Search"],"operationId":"searchDocuments","description":"使用 SQLite FTS5 按标题或正文搜索；正文命中返回稳定 block_id 与可读摘要。","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"knowledge_base_id","schema":{"type":"integer","minimum":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"搜索结果","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"request_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search/v2":{"get":{"tags":["Search"],"operationId":"searchDocumentsV2","description":"带查询级投影水位与完整性证明的搜索。仅返回 indexed_version 与正文\nsource_version 一致的命中；projection.complete=false 表示至少一篇可见文档\n的索引陈旧或缺失，调用方不得据此断言“知识不存在”。\n","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"mode","schema":{"type":"string","enum":["topk","exhaustive"],"default":"topk"}},{"in":"query","name":"knowledge_base_id","schema":{"type":"integer","minimum":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"in":"query","name":"cursor","description":"exhaustive 模式返回的版本绑定不透明游标","schema":{"type":"string"}},{"in":"query","name":"locale","description":"指定 BCP 47 语言版本，all 表示全部版本","schema":{"type":"string"}},{"in":"query","name":"include_summary","description":"显式请求时为每条结果附带文档摘要","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"带投影水位的搜索响应","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/SearchV2Response"},"request_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/relation-types":{"get":{"tags":["Relations"],"operationId":"listRelationTypes","description":"列出 v1 注册谓词。首批固定为 refers_to、supports、depends_on、contradicts。","responses":{"200":{"$ref":"#/components/responses/Success"},"403":{"$ref":"#/components/responses/Error"}}}},"/relations":{"post":{"tags":["Relations"],"operationId":"createRelation","description":"从稳定来源块创建显式类型关系；两端文档和块在创建时均进行权限与存在性校验。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationCreateInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/relations/{id}":{"delete":{"tags":["Relations"],"operationId":"deleteRelation","description":"删除手工关系；inline 关系必须通过编辑来源正文中的链接删除。","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/concepts":{"get":{"tags":["Concepts"],"operationId":"listConcepts","description":"完整枚举当前知识库中的显式概念；候选不会混入。响应 complete=true 只声明显式概念清单完整。","parameters":[{"in":"query","name":"knowledge_base_id","required":true,"schema":{"type":"integer"}},{"in":"query","name":"document_id","schema":{"type":"string"}},{"in":"query","name":"q","description":"按规范名或别名过滤","schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/Success"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Concepts"],"operationId":"createConcept","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConceptCreateInput"}}}},"responses":{"201":{"$ref":"#/components/responses/ConceptSuccess"},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/concepts/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Concepts"],"operationId":"getConcept","description":"旧概念 ID 已合并时解析到规范概念，并保留 requested_id。","responses":{"200":{"$ref":"#/components/responses/ConceptSuccess"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Concepts"],"operationId":"updateConcept","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConceptUpdateInput"}}}},"responses":{"200":{"$ref":"#/components/responses/ConceptSuccess"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/concepts/{id}/sources":{"post":{"tags":["Concepts"],"operationId":"addConceptSource","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConceptEvidenceInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/concepts/{id}/relations":{"post":{"tags":["Concepts"],"operationId":"addConceptRelation","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConceptRelationInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/concepts/{id}/merge":{"post":{"tags":["Concepts"],"operationId":"mergeConcept","description":"合并后旧 URI 继续解析到规范概念，别名、来源、关系与合并历史保留。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConceptMergeInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/concepts/{id}/traverse":{"get":{"tags":["Concepts"],"operationId":"traverseConcept","description":"在指定毫秒时间点按 [valid_from, valid_to) 语义遍历当前有效的显式概念关系。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"at","schema":{"type":"integer"}},{"in":"query","name":"direction","schema":{"type":"string","enum":["outgoing","incoming","both"],"default":"both"}},{"in":"query","name":"predicate","schema":{"type":"string","enum":["alias_of","broader_than","related_to","evidenced_by"]}}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/concept-candidates":{"get":{"tags":["Concepts"],"operationId":"listConceptCandidates","description":"候选是可重建派生结果，不属于显式概念清单，complete 仅描述当前候选查询执行完整。","parameters":[{"in":"query","name":"knowledge_base_id","required":true,"schema":{"type":"integer"}},{"in":"query","name":"candidate_id","description":"精确读取单个候选并取得 ETag","schema":{"type":"string"}},{"in":"query","name":"document_id","schema":{"type":"string"}},{"in":"query","name":"review_status","schema":{"enum":["pending","accepted","rejected","all"],"default":"pending"}}],"responses":{"200":{"$ref":"#/components/responses/Success"},"403":{"$ref":"#/components/responses/Error"}}}},"/concept-candidates/extract":{"post":{"tags":["Concepts"],"operationId":"extractConceptCandidates","description":"按需从文档标题和显式链接锚文本确定性生成候选；不会调用模型或自动转为显式概念。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document_id"],"properties":{"document_id":{"type":"string"}}}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/concept-candidates/{id}/accept":{"post":{"tags":["Concepts"],"operationId":"acceptConceptCandidate","description":"来源仍为 current 时新建概念，或通过 concept_id 并入已有概念；审核以 WHERE pending 原子防双审。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"concept_id":{"type":"string"},"reason":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/concept-candidates/{id}/reject":{"post":{"tags":["Concepts"],"operationId":"rejectConceptCandidate","description":"拒绝记录保留，同一来源与抽取器版本的 fingerprint 不会反复生成新候选。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/summary-jobs/{id}":{"get":{"tags":["Summaries"],"operationId":"getSummaryJob","description":"查询异步模型摘要任务。来源变化或摘要在运行期间被钉住时，任务以 obsolete 结束。","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/knowledge-bases":{"get":{"tags":["KnowledgeBases"],"operationId":"listKnowledgeBases","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"$ref":"#/components/responses/ListSuccess"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["KnowledgeBases"],"operationId":"createKnowledgeBase","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/knowledge-bases/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["KnowledgeBases"],"operationId":"getKnowledgeBase","responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["KnowledgeBases"],"operationId":"updateKnowledgeBase","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["KnowledgeBases"],"operationId":"deleteKnowledgeBase","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm_id"],"properties":{"confirm_id":{"type":"string"}}}}}},"responses":{"204":{"description":"已删除"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/knowledge-bases/{id}/tree":{"get":{"tags":["KnowledgeBases"],"operationId":"getKnowledgeBaseTree","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"include_summary","schema":{"type":"boolean","default":false}}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/knowledge-bases/{id}/summary":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Summaries"],"operationId":"getKnowledgeBaseSummary","parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"tags":["Summaries"],"operationId":"saveKnowledgeBaseSummary","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryWriteInput"}}}},"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/knowledge-bases/{id}/summary/rebuild":{"post":{"tags":["Summaries"],"operationId":"rebuildKnowledgeBaseSummary","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryRebuildInput"}}}},"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"202":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/knowledge-bases/{id}/export":{"get":{"tags":["KnowledgeBases"],"operationId":"exportKnowledgeBase","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"ZIP 文件","content":{"application/zip":{"schema":{"type":"string","contentEncoding":"binary"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/folders":{"post":{"tags":["Folders"],"operationId":"createFolder","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/folders/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Folders"],"operationId":"getFolder","responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Folders"],"operationId":"updateFolder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Folders"],"operationId":"deleteFolder","responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/Error"}}}},"/folders/{id}/children":{"get":{"tags":["Folders"],"operationId":"getFolderChildren","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/folders/{id}/summary":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Summaries"],"operationId":"getFolderSummary","parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"tags":["Summaries"],"operationId":"saveFolderSummary","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryWriteInput"}}}},"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/folders/{id}/summary/rebuild":{"post":{"tags":["Summaries"],"operationId":"rebuildFolderSummary","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryRebuildInput"}}}},"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"202":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/documents":{"get":{"tags":["Documents"],"operationId":"listDocuments","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"knowledge_base_id","schema":{"type":"string"}},{"in":"query","name":"folder_id","schema":{"type":"string"}},{"in":"query","name":"updated_since","description":"增量同步：仅返回 updated_at 不早于该时刻的文档（ISO 8601 或毫秒时间戳，含边界）","schema":{"type":"string"}},{"in":"query","name":"sort","description":"排序方式；updated_at 按更新时间倒序（游标随之变化）","schema":{"type":"string","enum":["updated_at"]}},{"in":"query","name":"locale","description":"指定语言版本","schema":{"type":"string"}},{"in":"query","name":"include_variants","description":"是否返回目标语言文档","schema":{"type":"boolean","default":false}}],"responses":{"200":{"$ref":"#/components/responses/ListSuccess"},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Documents"],"operationId":"createDocument","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreateInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Documents"],"operationId":"getDocument","responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Documents"],"operationId":"updateDocument","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Documents"],"operationId":"deleteDocument","responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/path":{"get":{"tags":["Documents"],"operationId":"getDocumentPath","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/document-sets/{id}":{"get":{"tags":["Translation"],"operationId":"getDocumentTranslationSet","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translations":{"get":{"tags":["Translation"],"operationId":"listDocumentTranslations","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Translation"],"operationId":"addDocumentTranslation","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationCreateInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translation/activate":{"post":{"tags":["Translation"],"operationId":"activateDocumentTranslation","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationActivateInput"}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translations/{targetDocId}":{"patch":{"tags":["Translation"],"operationId":"updateDocumentTranslation","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"targetDocId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationUpdateInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Translation"],"operationId":"deleteDocumentTranslation","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"targetDocId","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"已删除目标语言版本"},"409":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translation/deactivate":{"post":{"tags":["Translation"],"operationId":"deactivateDocumentTranslation","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translations/{targetDocId}/prepare":{"post":{"tags":["Translation"],"operationId":"prepareDocumentTranslation","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"targetDocId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translation-units":{"get":{"tags":["Translation"],"operationId":"listTranslationUnits","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"target_document_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translation-units/{unitId}":{"patch":{"tags":["Translation"],"operationId":"reviewTranslationUnit","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"unitId","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationUnitReviewInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translation-audit":{"get":{"tags":["Translation"],"operationId":"listTranslationAudit","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/translation-jobs":{"post":{"tags":["Translation"],"operationId":"createTranslationJob","description":"创建异步机器翻译候选。候选不会直接写入目标 YDoc，必须经过 apply 且带目标文档 If-Match。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationJobCreateInput"}}}},"responses":{"202":{"$ref":"#/components/responses/Success"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Error"}}}},"/translation-jobs/{id}":{"get":{"tags":["Translation"],"operationId":"getTranslationJob","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}},"/translation-jobs/{id}/apply":{"post":{"tags":["Translation"],"operationId":"applyTranslationJob","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationJobApplyInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/changes":{"get":{"tags":["Documents"],"operationId":"getDocumentChanges","description":"获取覆盖开放 API 与 Hocuspocus/Yjs 写入的顶层块变更水位。首次不传 after\n返回当前 manifest 与基线游标；后续传回该游标可获取 added、removed、modified、moved。\n派生链陈旧、重建或游标超出保留窗口时返回 sync_required=true，调用方必须重新读取基线。\n","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"after","description":"上次响应返回的不透明文档变更游标","schema":{"type":"string"}},{"in":"query","name":"limit","description":"单页最多返回的变更批次数","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"块级变更水位或基线","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/DocumentChanges"},"request_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{id}/outline":{"get":{"tags":["Content"],"operationId":"getDocumentOutline","description":"按稳定标题块 ID 返回层级、标题路径与顶层块闭区间；重复标题与空标题不影响定位。","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"文档结构大纲","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/DocumentOutline"},"request_id":{"type":"string"}}}}}},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/read":{"get":{"tags":["Content"],"operationId":"readDocumentWindow","description":"按稳定块 around 或 token 预算读取局部正文。next_cursor 与文档版本和查询参数绑定；\n正文变化后旧游标返回 409 read_cursor_stale。单个块超过预算时仍返回该块并标记 budget_exceeded。\n","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"view","schema":{"type":"string","enum":["markdown","tiptap-json","plain-text","outline"],"default":"markdown"}},{"in":"query","name":"around","description":"任意顶层或嵌套稳定 block_id","schema":{"type":"string"}},{"in":"query","name":"max_tokens","schema":{"type":"integer","minimum":64,"maximum":50000,"default":4000}},{"in":"query","name":"context_before","schema":{"type":"integer","minimum":0,"maximum":100,"default":2}},{"in":"query","name":"context_after","schema":{"type":"integer","minimum":0,"maximum":100,"default":4}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"description":"局部读取结果","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/DocumentRead"},"request_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/relations":{"get":{"tags":["Relations"],"operationId":"listDocumentRelations","description":"查询文档正向、反向或双向显式关系；每条关系返回来源块、来源版本、投影新鲜度和 dangling 状态。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"direction","schema":{"type":"string","enum":["outgoing","incoming","both"],"default":"both"}},{"in":"query","name":"predicate","schema":{"type":"string","enum":["refers_to","supports","depends_on","contradicts"]}}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/summary":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Summaries"],"operationId":"getDocumentSummary","parameters":[{"in":"query","name":"block_id","description":"传稳定标题块 ID 时读取章节摘要","schema":{"type":"string"}},{"in":"query","name":"query","description":"返回不持久化的确定性 query-focused summary","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"tags":["Summaries"],"operationId":"saveDocumentSummary","parameters":[{"$ref":"#/components/parameters/IfMatch"},{"in":"query","name":"block_id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryWriteInput"}}}},"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/summary/rebuild":{"post":{"tags":["Summaries"],"operationId":"rebuildDocumentSummary","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"in":"query","name":"block_id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryRebuildInput"}}}},"responses":{"200":{"$ref":"#/components/responses/SummarySuccess"},"202":{"$ref":"#/components/responses/Success"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/content":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Content"],"operationId":"getDocumentContent","parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["tiptap-json","markdown","html"],"default":"tiptap-json"}},{"in":"query","name":"annotate","description":"仅 format=markdown 有效：anchors 在每个顶层块前注入 <!--@block=<id>--> 锚点（标题附 slug），写回时按锚点保留块 ID","schema":{"type":"string","enum":["anchors"]}}],"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"}}},"put":{"tags":["Content"],"operationId":"replaceDocumentContent","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentInput"}},"application/vnd.doco.document+json":{"schema":{"$ref":"#/components/schemas/ContentInput"}}}},"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/versions":{"get":{"tags":["Versions"],"operationId":"listDocumentVersions","description":"列出开放 API 写入前自动保存的版本快照，按 seq 从新到旧返回，不包含快照 blob。","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"文档版本列表","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentVersion"}},"request_id":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{id}/versions/{seq}/rollback":{"post":{"tags":["Versions"],"operationId":"rollbackDocumentVersion","description":"将指定快照的正文恢复为当前内容；回滚本身也会先保存当前版本。","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"seq","required":true,"schema":{"type":"integer","minimum":1}},{"$ref":"#/components/parameters/RequiredIfMatch"}],"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{id}/blocks":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Blocks"],"operationId":"listBlocks","parameters":[{"in":"query","name":"recursive","schema":{"type":"boolean","default":false}}],"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Blocks"],"operationId":"insertBlocks","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockInsertInput"}}}},"responses":{"201":{"$ref":"#/components/responses/ContentSuccess"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/blocks/{blockId}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"blockId","required":true,"schema":{"type":"string","pattern":"^block_[0-9A-HJKMNP-TV-Z]{26}$"}}],"get":{"tags":["Blocks"],"operationId":"getBlock","responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Blocks"],"operationId":"updateBlock","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node":{"$ref":"#/components/schemas/TiptapNode"},"attrs":{"type":"object"},"content":{"type":"array","items":{"$ref":"#/components/schemas/TiptapNode"}}}}}}},"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Blocks"],"operationId":"deleteBlock","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/batch":{"post":{"tags":["Blocks"],"operationId":"batchDocumentOperations","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchInput"}}}},"responses":{"200":{"$ref":"#/components/responses/ContentSuccess"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/attachments":{"post":{"tags":["Attachments"],"operationId":"uploadAttachment","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document_id","file"],"properties":{"document_id":{"type":"string"},"file":{"type":"string","contentEncoding":"binary"}}}}}},"responses":{"201":{"$ref":"#/components/responses/Success"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/attachments/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Attachments"],"operationId":"downloadAttachment","responses":{"200":{"description":"附件二进制内容","content":{"application/octet-stream":{"schema":{"type":"string","contentEncoding":"binary"}}}},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Attachments"],"operationId":"deleteAttachment","parameters":[{"in":"query","name":"force","schema":{"type":"boolean","default":false}}],"responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/attachments/{id}/metadata":{"get":{"tags":["Attachments"],"operationId":"getAttachmentMetadata","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"doco_<token_id>_<secret>"}},"parameters":{"ResourceId":{"in":"path","name":"id","required":true,"schema":{"type":"string"}},"Cursor":{"in":"query","name":"cursor","schema":{"type":["string","null"]}},"Limit":{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"IdempotencyKey":{"in":"header","name":"Idempotency-Key","schema":{"type":"string","maxLength":128}},"LastEventId":{"in":"header","name":"Last-Event-ID","description":"上次已处理的 SSE 事件 ID，用于断线续传","schema":{"type":"integer","minimum":0}},"IfMatch":{"in":"header","name":"If-Match","schema":{"type":"string","examples":["\"sha256:abc\""]}},"RequiredIfMatch":{"in":"header","name":"If-Match","required":true,"description":"当前文档的 ETag，防止回滚覆盖并发编辑","schema":{"type":"string","examples":["\"sha256:abc\""]}}},"headers":{"RequestId":{"schema":{"type":"string"},"description":"服务端或调用方提供的请求 ID"},"ETag":{"schema":{"type":"string"},"description":"当前文档、摘要、概念或候选的资源版本"},"RateLimitLimit":{"schema":{"type":"integer"}},"RateLimitRemaining":{"schema":{"type":"integer"}},"RateLimitReset":{"schema":{"type":"integer"}},"RetryAfter":{"schema":{"type":"integer"}}},"responses":{"Success":{"description":"成功","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"ListSuccess":{"description":"分页列表","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"ContentSuccess":{"description":"正文或块操作成功","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"SummarySuccess":{"description":"带摘要自身版本 ETag 的成功响应","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/ResourceSummary"},"request_id":{"type":"string"}}}}}},"ConceptSuccess":{"description":"带概念自身版本 ETag 的成功响应","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/Concept"},"request_id":{"type":"string"}}}}}},"Error":{"description":"错误","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"超过限频","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"SuccessEnvelope":{"type":"object","required":["data","request_id"],"properties":{"data":{},"request_id":{"type":"string"}}},"ListEnvelope":{"type":"object","required":["data","page","request_id"],"properties":{"data":{"type":"array","items":{}},"page":{"$ref":"#/components/schemas/Page"},"request_id":{"type":"string"}}},"Page":{"type":"object","required":["cursor","next_cursor","has_more"],"properties":{"cursor":{"type":["string","null"]},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}},"ErrorEnvelope":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"request_id":{"type":"string"}}},"NameInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200}}},"DocumentSet":{"type":"object","required":["id","uri","source_document_id","source_locale","fallback_locale","available_locales","variants"],"properties":{"id":{"type":"string","pattern":"^docset_"},"uri":{"type":"string","format":"uri"},"source_document_id":{"type":"string"},"source_locale":{"type":"string"},"fallback_locale":{"type":"string"},"available_locales":{"type":"array","items":{"type":"string"}},"source":{"type":["object","null"],"additionalProperties":true},"variants":{"type":"array","items":{"$ref":"#/components/schemas/LocalizedDocument"}}}},"LocalizedDocument":{"type":"object","required":["id","title","locale","variant_role","workflow_status","document_set_id","translation_freshness"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"locale":{"type":"string"},"variant_role":{"enum":["source","translation"]},"workflow_status":{"enum":["draft","in_review","published"]},"document_set_id":{"type":"string"},"document_set_uri":{"type":"string","format":"uri"},"translation_freshness":{"enum":["current","outdated","unknown"]},"translation_status_counts":{"type":"object","additionalProperties":{"type":"integer"}},"translated_from_document_id":{"type":["string","null"]},"translated_from_version":{"type":["string","null"]}}},"TranslationActivateInput":{"type":"object","required":["source_locale"],"properties":{"source_locale":{"type":"string","description":"BCP 47 标签"},"target_locales":{"type":"array","items":{"type":"string"}},"create_mode":{"enum":["blank","copy_structure"],"default":"blank"}}},"TranslationCreateInput":{"type":"object","required":["locale"],"properties":{"locale":{"type":"string"},"create_mode":{"enum":["blank","copy_structure"],"default":"blank"}}},"TranslationUpdateInput":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"workflow_status":{"enum":["draft","in_review","published"]}}},"TranslationUnitReviewInput":{"type":"object","required":["target_document_id","review_status"],"properties":{"target_document_id":{"type":"string"},"review_status":{"enum":["current","ignored"]},"target_block_ids":{"type":"array","items":{"type":"string"}}}},"FolderInput":{"type":"object","properties":{"name":{"type":"string"},"knowledge_base_id":{"type":["string","integer"]},"parent_id":{"type":["string","integer","null"]}}},"DocumentCreateInput":{"type":"object","required":["title"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"knowledge_base_id":{"type":["string","integer"]},"folder_id":{"type":["string","integer","null"]},"document_type":{"enum":["document","spreadsheet"],"default":"document"},"heading_numbered":{"type":"boolean"},"background_color":{"type":"string"},"collapsed_block_ids":{"type":"array","items":{"type":"string"}},"content":{"$ref":"#/components/schemas/ContentInput"}}},"DocumentUpdateInput":{"type":"object","properties":{"title":{"type":"string"},"knowledge_base_id":{"type":["string","integer"]},"folder_id":{"type":["string","integer","null"]},"heading_numbered":{"type":"boolean"},"background_color":{"type":"string"},"collapsed_block_ids":{"type":"array","items":{"type":"string"}}}},"DocumentVersion":{"type":"object","required":["seq","created_at","created_by","size"],"properties":{"seq":{"type":"integer","minimum":1},"created_at":{"type":"integer","description":"Unix 毫秒时间戳"},"created_by":{"type":["string","null"]},"size":{"type":"integer","minimum":0,"description":"Yjs 快照字节数"}}},"BlockManifestEntry":{"type":"object","required":["block_id","position","type","hash","text_excerpt"],"properties":{"block_id":{"type":"string"},"position":{"type":"integer","minimum":0},"type":{"type":"string"},"hash":{"type":"string"},"text_excerpt":{"type":"string"}}},"BlockChange":{"type":"object","required":["op","block_id","type","text_excerpt","old_position","new_position","cursor","source_version","changed_at"],"properties":{"op":{"enum":["added","removed","modified","moved"]},"block_id":{"type":"string"},"type":{"type":"string"},"text_excerpt":{"type":"string"},"old_position":{"type":["integer","null"]},"new_position":{"type":["integer","null"]},"moved":{"type":"boolean","description":"modified 与相对顺序移动同时发生时为 true"},"cursor":{"type":"string"},"source_version":{"type":"string"},"changed_at":{"type":"integer"}}},"DocumentChanges":{"type":"object","required":["document_id","cursor","source_version","freshness","complete","sync_required","changes"],"properties":{"document_id":{"type":"string"},"cursor":{"type":["string","null"]},"source_version":{"type":["string","null"]},"freshness":{"enum":["current","stale","missing"]},"complete":{"type":"boolean"},"sync_required":{"type":"boolean"},"baseline":{"type":"boolean"},"manifest":{"type":"array","items":{"$ref":"#/components/schemas/BlockManifestEntry"}},"changes":{"type":"array","items":{"$ref":"#/components/schemas/BlockChange"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"SearchResult":{"type":"object","required":["document_id","title","knowledge_base_id","document_type","block_id","matched_in","snippet","updated_at"],"properties":{"document_id":{"type":"string"},"title":{"type":"string"},"knowledge_base_id":{"type":"integer"},"folder_id":{"type":["integer","null"]},"document_type":{"enum":["document","spreadsheet"]},"locale":{"type":["string","null"]},"document_set_id":{"type":["string","null"]},"document_set_uri":{"type":["string","null"],"format":"uri"},"block_id":{"type":["string","null"],"description":"正文命中时为对应顶层稳定块 ID；标题命中时为空"},"matched_in":{"enum":["title","content"]},"snippet":{"type":["string","null"],"description":"正文命中的上下文摘要"},"updated_at":{"type":["integer","null"]}}},"SearchProjection":{"type":"object","required":["watermark","document_count","current_document_count","stale_document_count","stale_document_ids","freshness","complete"],"properties":{"watermark":{"type":"string"},"document_count":{"type":"integer","minimum":0},"current_document_count":{"type":"integer","minimum":0},"stale_document_count":{"type":"integer","minimum":0},"stale_document_ids":{"type":"array","maxItems":100,"items":{"type":"string"}},"freshness":{"enum":["current","stale"]},"complete":{"type":"boolean"}}},"SearchV2Result":{"type":"object","required":["document_id","document_uri","title","path","path_text","block_id","heading_path","context","match_count","score","score_explanation","source_version","indexed_version","freshness"],"properties":{"document_id":{"type":"string"},"document_uri":{"type":"string","format":"uri"},"title":{"type":"string"},"knowledge_base_id":{"type":"integer"},"folder_id":{"type":["integer","null"]},"document_type":{"enum":["document","spreadsheet"]},"locale":{"type":["string","null"]},"document_set_id":{"type":["string","null"]},"document_set_uri":{"type":["string","null"],"format":"uri"},"path":{"type":"array","items":{"type":"object","required":["id","name","type"],"properties":{"id":{"type":["string","integer"]},"name":{"type":"string"},"type":{"enum":["knowledge_base","folder","document"]}}}},"path_text":{"type":"string"},"block_id":{"type":["string","null"]},"block_type":{"type":["string","null"]},"position":{"type":["integer","null"]},"heading_path":{"type":"array","items":{"type":"string"}},"matched_in":{"enum":["title","content"]},"context":{"type":"object","required":["before","match","after"],"properties":{"before":{"type":["string","null"]},"match":{"type":"string"},"after":{"type":["string","null"]}}},"match_count":{"type":"integer","minimum":1},"score":{"type":"number"},"score_explanation":{"type":"object","additionalProperties":true},"source_version":{"type":["string","null"]},"indexed_version":{"type":["string","null"]},"indexed_at":{"type":"integer"},"freshness":{"const":"current"},"updated_at":{"type":["integer","null"]},"summary":{"$ref":"#/components/schemas/ResourceSummary","description":"仅 include_summary=true 时存在"}}},"SearchV2Response":{"type":"object","required":["query","mode","results","page","projection"],"properties":{"query":{"type":"string"},"mode":{"enum":["topk","exhaustive"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchV2Result"}},"page":{"type":"object","required":["has_more","next_cursor"],"properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"projection":{"$ref":"#/components/schemas/SearchProjection"}}},"OutlineSection":{"type":"object","required":["block_id","level","title","heading_path","parent_block_id","start_position","end_position","start_block_id","end_block_id","block_count"],"properties":{"block_id":{"type":["string","null"]},"level":{"type":"integer","minimum":1,"maximum":6},"title":{"type":"string"},"heading_path":{"type":"array","items":{"type":"string"}},"parent_block_id":{"type":["string","null"]},"start_position":{"type":"integer","minimum":0},"end_position":{"type":"integer","minimum":0},"start_block_id":{"type":["string","null"]},"end_block_id":{"type":["string","null"]},"block_count":{"type":"integer","minimum":1}}},"DocumentOutline":{"type":"object","required":["document_id","version","block_count","heading_count","preamble","sections"],"properties":{"document_id":{"type":"string"},"version":{"type":"string"},"block_count":{"type":"integer","minimum":0},"heading_count":{"type":"integer","minimum":0},"preamble":{"type":["object","null"]},"sections":{"type":"array","items":{"$ref":"#/components/schemas/OutlineSection"}}}},"DocumentRead":{"type":"object","required":["document_id","version","view"],"properties":{"document_id":{"type":"string"},"version":{"type":"string"},"view":{"enum":["markdown","tiptap-json","plain-text","outline"]},"document_uri":{"type":"string","format":"uri"},"range":{"type":"object","additionalProperties":true},"estimated_tokens":{"type":"integer","minimum":0},"max_tokens":{"type":"integer","minimum":64},"budget_exceeded":{"type":"boolean"},"truncated":{"type":"boolean"},"omitted_ranges":{"type":"array","items":{"type":"object","required":["from_position","to_position"],"properties":{"from_position":{"type":"integer"},"to_position":{"type":"integer"}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"content":{"type":"string"},"document":{"$ref":"#/components/schemas/TiptapDocument"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/OutlineSection"}}}},"RelationEndpoint":{"type":"object","required":["uri","document_id","block_id","document"],"properties":{"uri":{"type":"string","format":"uri"},"document_id":{"type":"string"},"block_id":{"type":["string","null"]},"document":{"type":["object","null"],"properties":{"id":{"type":"string"},"title":{"type":"string"}}}}},"DocumentRelation":{"type":"object","required":["id","predicate","origin","source","target","anchor_text","source_version","evidence_freshness","projection_freshness","status","created_at"],"properties":{"id":{"type":"string"},"predicate":{"enum":["refers_to","supports","depends_on","contradicts"]},"origin":{"enum":["inline","manual"]},"source":{"$ref":"#/components/schemas/RelationEndpoint"},"target":{"$ref":"#/components/schemas/RelationEndpoint"},"anchor_text":{"type":"string"},"source_version":{"type":"string"},"evidence_freshness":{"enum":["current","stale"]},"projection_freshness":{"enum":["current","stale"]},"status":{"enum":["valid","dangling_source_document","dangling_source_block","dangling_target_document","dangling_target_block"]},"created_by":{"type":["string","null"]},"created_at":{"type":"integer"}}},"RelationCreateInput":{"type":"object","required":["source_document_id","source_block_id","target_uri"],"properties":{"source_document_id":{"type":"string"},"source_block_id":{"type":"string","pattern":"^block_[0-9A-HJKMNP-TV-Z]{26}$"},"target_uri":{"type":"string","examples":["doco://doc/doc_123#block=block_01JXYZ0123456789ABCDEFGHJK"]},"predicate":{"enum":["refers_to","supports","depends_on","contradicts"],"default":"refers_to"},"anchor_text":{"type":"string","maxLength":500}}},"ConceptEvidence":{"type":"object","properties":{"document_id":{"type":"string"},"block_id":{"type":["string","null"]},"source_version":{"type":["string","null"]},"current_version":{"type":["string","null"]},"excerpt":{"type":"string"},"freshness":{"enum":["current","stale","dangling_evidence_document","dangling_evidence_block","dangling_document","dangling_block","unanchored"]}}},"ConceptRelation":{"type":"object","required":["id","subject_concept_id","predicate","object","temporal_status","origin"],"properties":{"id":{"type":"string"},"subject_concept_id":{"type":"string"},"predicate":{"enum":["alias_of","broader_than","related_to","evidenced_by"]},"object":{"type":"object","required":["kind","id","uri"],"properties":{"kind":{"enum":["concept","document","block"]},"id":{"type":"string"},"block_id":{"type":["string","null"]},"uri":{"type":"string"}}},"evidence":{"anyOf":[{"$ref":"#/components/schemas/ConceptEvidence"},{"type":"null"}]},"valid_from":{"type":["integer","null"]},"valid_to":{"type":["integer","null"],"description":"排他上界，区间语义为 [valid_from, valid_to)"},"temporal_status":{"enum":["current","future","expired"]},"origin":{"enum":["manual","candidate"]}}},"Concept":{"type":"object","required":["id","uri","knowledge_base_id","name","aliases","status","version"],"properties":{"id":{"type":"string","pattern":"^concept_[0-9A-HJKMNP-TV-Z]{26}$"},"uri":{"type":"string","examples":["doco://concept/concept_01JXYZ0123456789ABCDEFGHJK"]},"knowledge_base_id":{"type":"integer"},"name":{"type":"string","minLength":1,"maxLength":200},"normalized_name":{"type":"string"},"description":{"type":"string","maxLength":10000},"aliases":{"type":"array","items":{"type":"string"}},"alias_objects":{"type":"array","items":{"type":"object","required":["id","alias","normalized_alias","origin"],"properties":{"id":{"type":"string"},"alias":{"type":"string"},"normalized_alias":{"type":"string"},"origin":{"enum":["manual","candidate","merge"]}}}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ConceptLabel"}},"canonical_document_id":{"type":["string","null"]},"status":{"enum":["active","merged","archived"]},"merged_into_concept_id":{"type":["string","null"]},"requested_id":{"type":"string","description":"使用已合并旧 ID 查询时存在"},"version":{"type":"string","examples":["concept:3"]},"relations":{"type":"array","items":{"$ref":"#/components/schemas/ConceptRelation"}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"ConceptCreateInput":{"type":"object","required":["knowledge_base_id","name"],"properties":{"knowledge_base_id":{"type":"integer"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":10000},"aliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ConceptLabelInput"}},"canonical_document_id":{"type":"string"},"source_document_id":{"type":"string"},"source_block_id":{"type":"string"},"source_version":{"type":"string"},"source_excerpt":{"type":"string","maxLength":2000},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ConceptEvidenceInput"}},"valid_from":{"type":"integer"},"valid_to":{"type":"integer"}}},"ConceptUpdateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":10000},"aliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ConceptLabelInput"}},"canonical_document_id":{"type":["string","null"]},"base_version":{"type":"string","description":"If-Match 的请求体备用形式"}}},"ConceptLabel":{"type":"object","required":["locale","name","description","origin"],"properties":{"locale":{"type":"string","description":"BCP 47 标签"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":10000},"origin":{"enum":["manual","machine"]},"created_by":{"type":["string","null"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"ConceptLabelInput":{"type":"object","required":["locale","name"],"properties":{"locale":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":10000},"origin":{"enum":["manual","machine"],"default":"manual"}}},"TranslationJobCreateInput":{"type":"object","required":["target_document_id"],"properties":{"target_document_id":{"type":"string","description":"具体目标语言文档 ID"},"unit_ids":{"type":"array","maxItems":100,"items":{"type":"string"}}}},"TranslationJobApplyInput":{"type":"object","properties":{"unit_ids":{"type":"array","maxItems":100,"items":{"type":"string"}},"base_target_version":{"type":"string","description":"If-Match 的请求体备用形式"}}},"ConceptEvidenceInput":{"type":"object","required":["document_id"],"properties":{"document_id":{"type":"string"},"block_id":{"type":"string"},"excerpt":{"type":"string","maxLength":2000},"valid_from":{"type":"integer"},"valid_to":{"type":"integer"},"base_version":{"type":"string"}}},"ConceptRelationInput":{"type":"object","required":["predicate"],"properties":{"predicate":{"enum":["alias_of","broader_than","related_to"]},"target_concept_id":{"type":"string","description":"与 target_uri 二选一"},"target_uri":{"type":"string","description":"与 target_concept_id 二选一"},"evidence_document_id":{"type":"string"},"evidence_block_id":{"type":"string"},"evidence_excerpt":{"type":"string","maxLength":2000},"source_version":{"type":"string"},"valid_from":{"type":"integer"},"valid_to":{"type":"integer"},"base_version":{"type":"string"}}},"ConceptMergeInput":{"type":"object","required":["target_concept_id","base_target_version"],"properties":{"target_concept_id":{"type":"string"},"base_target_version":{"type":"string"},"reason":{"type":"string","maxLength":1000},"base_version":{"type":"string"}}},"ConceptCandidate":{"type":"object","required":["id","label","fingerprint","source","extractor","extractor_version","confidence","review_status","version"],"properties":{"id":{"type":"string"},"knowledge_base_id":{"type":"integer"},"kind":{"enum":["concept","alias","relation"]},"label":{"type":"string"},"fingerprint":{"type":"string"},"source":{"$ref":"#/components/schemas/ConceptEvidence"},"extractor":{"enum":["document-title","inline-anchor"]},"extractor_version":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"review_status":{"enum":["pending","accepted","rejected"]},"accepted_concept_id":{"type":["string","null"]},"review_reason":{"type":["string","null"]},"version":{"type":"string","examples":["concept-candidate:2"]}}},"SummaryCoverage":{"type":"object","required":["complete","document_count","included_document_count","omitted_document_count"],"properties":{"complete":{"type":"boolean"},"document_count":{"type":"integer","minimum":0},"included_document_count":{"type":"integer","minimum":0},"omitted_document_count":{"type":"integer","minimum":0},"source_versions":{"type":"array","items":{"type":"object","additionalProperties":true}},"matched_block_count":{"type":"integer","minimum":0}}},"ResourceSummary":{"type":"object","required":["scope","target_uri","target_id","summary","source_version","current_source_version","source_block_ids","source_document_ids","coverage","status","freshness","pinned","generator","summary_version"],"properties":{"id":{"type":["string","null"]},"scope":{"enum":["section","document","folder","knowledge_base"]},"target_uri":{"type":"string","format":"uri"},"target_id":{"type":"string"},"target_block_id":{"type":["string","null"]},"query":{"type":"string","description":"仅 query-focused summary 存在"},"summary":{"type":"string","maxLength":4000},"source_version":{"type":"string"},"current_source_version":{"type":"string"},"source_block_ids":{"type":"array","items":{"type":"string"}},"source_document_ids":{"type":"array","items":{"type":"string"}},"coverage":{"$ref":"#/components/schemas/SummaryCoverage"},"status":{"enum":["ready","stale","fallback","error"]},"freshness":{"enum":["current","stale"]},"pinned":{"type":"boolean"},"generator":{"enum":["manual","deterministic","deterministic-query","model"]},"summary_version":{"type":"string"},"error":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_at":{"type":["integer","null"]},"updated_at":{"type":["integer","null"]}}},"SummaryWriteInput":{"type":"object","required":["summary","base_source_version"],"properties":{"summary":{"type":"string","minLength":1,"maxLength":4000},"pinned":{"type":"boolean","default":true},"block_id":{"type":"string"},"base_source_version":{"type":"string"},"base_summary_version":{"type":"string","description":"If-Match 的请求体备用形式"}}},"SummaryRebuildInput":{"type":"object","required":["base_source_version"],"properties":{"generator":{"enum":["deterministic","model"],"default":"model"},"block_id":{"type":"string"},"base_source_version":{"type":"string"}}},"ContentInput":{"oneOf":[{"type":"object","required":["format","document"],"properties":{"format":{"const":"tiptap-json"},"document":{"$ref":"#/components/schemas/TiptapDocument"}}},{"type":"object","required":["format","content"],"properties":{"format":{"const":"markdown"},"content":{"type":"string","maxLength":10485760}}},{"type":"object","required":["format","content"],"properties":{"format":{"const":"html"},"content":{"type":"string","maxLength":10485760}}}]},"TiptapDocument":{"type":"object","required":["type"],"properties":{"type":{"const":"doc"},"content":{"type":"array","items":{"$ref":"#/components/schemas/TiptapNode"}}}},"TiptapNode":{"oneOf":[{"$ref":"#/components/schemas/TextNode"},{"$ref":"#/components/schemas/ParagraphNode"},{"$ref":"#/components/schemas/HeadingNode"},{"$ref":"#/components/schemas/ImageNode"},{"$ref":"#/components/schemas/GenericBlockNode"}],"discriminator":{"propertyName":"type"}},"BlockAttrs":{"type":"object","required":["id"],"properties":{"id":{"type":"string","pattern":"^block_[0-9A-HJKMNP-TV-Z]{26}$"},"textAlign":{"type":["string","null"]}},"additionalProperties":true},"TextNode":{"type":"object","required":["type","text"],"properties":{"type":{"const":"text"},"text":{"type":"string"},"marks":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"enum":["bold","italic","strike","code","underline","link","textStyle","highlight"]},"attrs":{"type":"object"}}}}}},"ParagraphNode":{"type":"object","required":["type"],"properties":{"type":{"const":"paragraph"},"attrs":{"$ref":"#/components/schemas/BlockAttrs"},"content":{"type":"array","items":{"$ref":"#/components/schemas/TiptapNode"}}}},"HeadingNode":{"type":"object","required":["type"],"properties":{"type":{"const":"heading"},"attrs":{"allOf":[{"$ref":"#/components/schemas/BlockAttrs"},{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":6}}}]},"content":{"type":"array","items":{"$ref":"#/components/schemas/TiptapNode"}}}},"ImageNode":{"type":"object","required":["type","attrs"],"properties":{"type":{"const":"image"},"attrs":{"allOf":[{"$ref":"#/components/schemas/BlockAttrs"},{"type":"object","properties":{"attachmentId":{"type":["string","null"]},"src":{"type":"string"},"alt":{"type":["string","null"]},"title":{"type":["string","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"align":{"enum":["left","center","right"]}}}]}}},"GenericBlockNode":{"type":"object","required":["type"],"properties":{"type":{"enum":["blockquote","horizontalRule","hardBreak","codeBlock","bulletList","orderedList","listItem","taskList","taskItem","table","tableRow","tableHeader","tableCell","mermaidBlock","plantUMLBlock","calloutBlock","spreadsheetBlock"]},"attrs":{"$ref":"#/components/schemas/BlockAttrs"},"content":{"type":"array","items":{"$ref":"#/components/schemas/TiptapNode"}}}},"Position":{"type":"object","oneOf":[{"required":["after_block_id"],"properties":{"after_block_id":{"type":"string"}}},{"required":["before_block_id"],"properties":{"before_block_id":{"type":"string"}}},{"required":["parent_block_id"],"properties":{"parent_block_id":{"type":"string"},"child_index":{"type":"integer","minimum":0}}},{"required":["document_start"],"properties":{"document_start":{"const":true}}},{"required":["document_end"],"properties":{"document_end":{"const":true}}},{"required":["after_heading"],"properties":{"after_heading":{"type":"string","description":"按标题文本定位（精确优先，退化包含匹配），插入到该顶层标题块之后；无匹配返回 422 heading_not_found"}}}]},"BlockInsertInput":{"type":"object","required":["position","nodes"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"nodes":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/TiptapNode"}}}},"BatchInput":{"type":"object","required":["base_version","operations"],"properties":{"base_version":{"type":"string"},"operations":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["op"],"properties":{"op":{"enum":["insert","replace","delete"]},"block_id":{"type":"string","description":"replace/delete 的目标块"},"node":{"$ref":"#/components/schemas/TiptapNode"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/TiptapNode"}},"after_block_id":{"type":"string","description":"insert 定位——该块之后"},"before_block_id":{"type":"string","description":"insert 定位——该块之前"},"parent_block_id":{"type":"string","description":"insert 定位——父块（配合 child_index）"},"child_index":{"type":"integer","minimum":0},"document_start":{"const":true},"document_end":{"const":true},"after_heading":{"type":"string","description":"insert 定位——按标题文本（精确优先，退化包含匹配），无匹配返回 422"},"position":{"$ref":"#/components/schemas/Position","description":"insert 定位的等价对象写法（与扁平定位字段二选一）"}}}}}}}}}