Docs
文档目录

版本管理

这是什么 / 何时用

2.8.0 起知识库支持多版本:以 READY 版本为源创建工作副本(异步复制为隔离 DRAFT)→ 就绪检查通过后 Seal 为只读 READY → Publish 切换为当前激活版本,Rollback 则恢复保留的回滚目标;未启用版本化的库先走 Adoption 采纳。所有写路径携带预期修订号做并发保护,操作类变更为异步(幂等键 + 轮询)。产品语义与 Console 入口见版本管理(产品手册)。

使用骨架

  1. 列出与读取:listVersions(knowledgeBaseId, limit, cursor, status, role)(limit、cursor、status、role 均可选) 分页取版本(status 过滤 draft / ready,role 过滤 current / rollback / none),getVersion 读单个版本;列表不包含仍在物化的工作副本。

  2. 创建工作副本:createVersion({ knowledgeBaseId, sourceVersionId, expectedSourceVersionRevision, expectedBindingRevision, label, description, retryOf })(description、retryOf 均可选) 返回 KnowledgeBaseWorkingCopyOperation——校验成功前 DRAFT 不可见,用 listWorkingCopyOperations / getWorkingCopyOperation 轮询,cancelWorkingCopyOperation 请求取消。

  3. 就绪检查与封存:getVersionReadiness 返回 sealable 与阻塞原因;sealVersion(携带 expectedDefinitionRevision + expectedVersionRevision + 幂等键)把 DRAFT 置为 READY,不自动发布。

  4. 发布与回滚:publishVersion / rollbackVersion(均携带 expectedBindingRevision + expectedVersionRevision)原子切换 currentVersionId / rollbackVersionId,返回 KnowledgeBaseVersion。

  5. 删除:deleteVersion({ knowledgeBaseId, versionId, expectedVersionRevision }) 发起不可逆异步清理,返回 KnowledgeBaseVersionDeleteOperation;getVersionDeleteOperation 轮询至 completed。CURRENT / ROLLBACK 角色的版本不可删除。

  6. 采纳:createVersionAdoption({ knowledgeBaseId, expectedBindingRevision, retryOf })(retryOf 可选) 为未版本化库启动采纳(返回 202 + operation);listVersionAdoptions / getVersionAdoption 查询,cancelVersionAdoption(携带 expectedOperationRevision)仅在版本标记开始前可取消。

关键参数与返回

错误与边界

各语言调用示例

主链:创建工作副本 → 轮询操作 → seal → publish。各卡 expectedBindingRevision 等修订号取自最近一次读取的库与版本对象。

// 1) 创建工作副本(源版本与库的修订号取自最近一次读取)
const op = await kb.createVersion({
    knowledgeBaseId: base.$id,
    sourceVersionId: readyVersion.$id,
    expectedSourceVersionRevision: readyVersion.versionRevision,
    expectedBindingRevision: base.bindingRevision,
    label: 'v2-改写稿',
});
// 2) 轮询操作直至终态 succeeded / failed / cancelled(DRAFT 校验成功后才可见)
let st = await kb.getWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
// 取消:await kb.cancelWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id, expectedOperationRevision: st.operationRevision });
const draft = await kb.getVersion({ knowledgeBaseId: base.$id, versionId: st.result.versionId });
// 3) 就绪检查通过后 seal 为 READY(幂等键按平台约定装载)
const readiness = await kb.getVersionReadiness({ knowledgeBaseId: base.$id, versionId: draft.$id });
if (readiness.sealable) {
    await kb.sealVersion({
        knowledgeBaseId: base.$id,
        versionId: draft.$id,
        expectedDefinitionRevision: readiness.definitionRevision,
        expectedVersionRevision: readiness.versionRevision,
    });
}
// 4) publish 切换当前激活版本(旧当前版本自动成为回滚目标)
await kb.publishVersion({
    knowledgeBaseId: base.$id,
    versionId: draft.$id,
    expectedBindingRevision: base.bindingRevision,
    expectedVersionRevision: draft.versionRevision,
});