托管文档分块与版本运维

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

使用顺序

1. 在“知识库”创建来源为“托管文档”的草稿，选择分块策略并保存。
2. 打开“管理托管文档”，输入正文或选择 UTF-8 .txt/.md 文件；每篇最多 65536 UTF-16 字符、文件最多 256 KiB。
3. “预览分块”检查片段正文及起止坐标，预览不保存，也不读取已有文档正文。
4. 选择重复处理策略后保存；多文件导入每批最多 25 篇、总正文最多 1048576 字符，可修改各文件导入标识。导入标识须唯一，中文文件名自动建议英文字符标识，请确认后使用。
5. 核对每条索引结果和文档租户、访问规则，再发布知识版本。把精确版本加入 Agent.allowedKnowledge，发布 Agent 后使用。

范围是托管文本索引；PDF/OCR 文件解析、Embedding/向量、语义重排各有独立能力要求，不能把本操作当成这些能力已经上线。

分块配置

{
  "mode":"MANAGED",
  "chunking":{
    "strategy":"MARKDOWN",
    "maxChars":2000,
    "overlapChars":0,
    "preserveParagraphs":true,
    "preserveCodeBlocks":true
  }
}

字段	默认与限制	使用建议
chunking 缺省	保留原 2000 字符固定分块	旧知识版本行为不变
strategy	CHARACTER / PARAGRAPH / MARKDOWN，默认 CHARACTER	Markdown 根据 ATX 标题和围栏代码组织片段
maxChars	默认 2000，128–8192	按模型窗口和文本结构调整
overlapChars	默认 0，最多 maxChars/2	仅 CHARACTER；另外两种必须为 0
preserveParagraphs	非 CHARACTER 默认 true	超长段落拒绝；显式 false 才允许拆开；CHARACTER 必须 false
preserveCodeBlocks	MARKDOWN 默认 true	超长代码块拒绝；显式 false 才允许拆开；其他策略必须 false

MARKDOWN 支持行首不超过 3 个空格、1–6 个 # 的 ATX 标题，以及至少 3 个相同反引号或波浪线围栏；不是完整 Markdown AST 解析器。未闭合围栏报 DOCUMENT_FORMAT_INVALID；超过片段上限的受保护段落/代码报 CHUNK_BOUNDARY_TOO_LARGE。降低保护范围是显式选择，不会静默截断原文。非重叠片段拼接等于原文，偏移为 UTF-16 startOffset（含）至 endOffset（不含），不是字节数。

修改已导入草稿的分块策略后，原片段不会自动改写。重新上传各原文（或从已发布源版本重建）；存在旧策略片段时，发布及批次发布预检返回 KNOWLEDGE_INDEX_STALE。不同文档不得以混合策略发布成同一配置版本。批次发布预检还绑定原文与索引摘要，预检后的任何文档变化使旧计划失效（RELEASE_PLAN_CHANGED），需重新预检确认。

文档版本与重复导入

字段/策略	行为
Knowledge.version	人工发布的语义版本，例如 1.1.0；固定 Agent 依赖指向它
documentVersion	规范化 id/text/title/source/tenantId 的 SHA-256；修改元信息也会改变
contentHash	原文文本的 UTF-8 SHA-256
chunkingHash	有效分块策略 SHA-256；与原文版本分离
UPSERT（默认）	有相同 ID 时更新草稿；原文版本及策略相同返回 UNCHANGED，不重复写入
SKIP	相同 ID 已存在时返回 SKIPPED，保留原文及索引
REJECT	相同 ID 已存在时返回 DOCUMENT_EXISTS
expectedDocumentVersion	单篇/批次文档可设置，必须匹配当前原文版本；不匹配或原文不存在报 412 DOCUMENT_VERSION_MISMATCH

批次内不允许重复 ID。SKIP 不意味着策略已经一致；草稿更改策略后仍需 UPSERT 重新索引。单篇 UPSERT 未提供 expectedDocumentVersion 时会覆盖草稿同 ID，协作编辑建议提供条件版本。

SDK 示例

Java

var chunking = DocumentChunking.builder()
    .strategy(DocumentChunking.Strategy.MARKDOWN)
    .maxChars(2000).build();
client.register("knowledge", "project-docs", "1.0.0",
    Map.of("mode", "MANAGED", "chunking", chunking.definition()))
    .toCompletableFuture().join();
var document = new ManagedDocument("install", "# Install\n部署说明", "部署指南", "", "tenant-a");
var preview = client.previewDocument("project-docs", "1.0.0", document)
    .toCompletableFuture().join();
var imported = client.importDocuments("project-docs", "1.0.0",
    List.of(document), true, DocumentDuplicatePolicy.UPSERT)
    .toCompletableFuture().join();
// 管理凭据可以导入本次提供的原文；租户限制仍作用于实际检索与原文重建。
client.publish("knowledge", "project-docs", "1.0.0").toCompletableFuture().join();

Kotlin

import dev.sparktide.sdk.*
import dev.sparktide.sdk.kotlin.*

val config = documentChunking {
    strategy = DocumentChunking.Strategy.MARKDOWN
    maxChars = 2000
}
client.register("knowledge", "project-docs", "1.0.0") {
    field("mode", "MANAGED")
    field("chunking", config.definition())
}.awaitResult()
val document = managedDocument("install") {
    title = "部署指南"
    text = "# Install\n部署说明"
    tenantId = "tenant-a"
}
val preview = client.previewDocument("project-docs", "1.0.0", document).awaitResult()
val imported = client.importDocuments("project-docs", "1.0.0",
    listOf(document), true, DocumentDuplicatePolicy.UPSERT).awaitResult()

Java 示例说明：

完整类型来自 dev.sparktide.sdk.*，集合来自 java.util.*。client 使用应用管理凭据，SDK 不代替平台授权；预览和批次响应都是 Map<String,Object>，必须检查批次 status 和 items，HTTP 200 不意味着每篇成功。

Kotlin 示例说明：

批次需要逐篇条件版本或重复策略时，可使用 importDocuments(id, version, Map<String,Object> request) 传入完整批次请求；服务端再次验证所有字段。

Java 核心无 Kotlin 依赖，Kotlin 使用相同输入约束并提供 DSL/协程等待。取消本地等待不代表回滚服务器已完成导入；读取文档摘要或以相同内容 UPSERT 核对结果。

批量事务与错误

默认 atomic:true：先预检全部文档；任何一条失败则 REJECTED，错误项 FAILED，其他项 NOT_IMPORTED，零写入。atomic:false：每篇独立事务，返回 PARTIAL 和逐项结果，不自动重试。发布状态变化可能造成剩余项失败，已经完成的独立写入保留。已有相同内容返回 UNCHANGED、明确跳过返回 SKIPPED。

结果包含 atomic/status/items/indexed/unchanged/skipped/failed；明细包含 id/status，成功项的版本/片段数，失败项的 error.code/message，不含正文。请求本身格式错误（重复或无效 ID、超限、未知批次字段）直接返回结构化 HTTP 错误。原子整批容量超限用 DOCUMENT_LIMIT_EXCEEDED；单篇/逐项容量超限返回 INVALID_REQUEST。每知识版本最多 1000 篇。

新版本重建与回退

1. 保留已发布源版本，例如 project-docs@1.0.0。
2. 创建相同知识资源的 1.1.0 草稿，保存目标分块策略。
3. 选来源版本及最多 25 个文档 ID，按批次重建；上方重复策略和原子设置同样生效。
4. 多次提交不同批次可覆盖全部原文；UPSERT 重复重建相同原文/策略返回 UNCHANGED，支持增量操作。修改原文则使用正常导入，不改写源版本。
5. 核对新索引摘要并发布目标知识版本，创建引用它的新 Agent 版本，验证后切换默认入口。需要回退时切换回引用旧知识的已发布 Agent。

var rebuilt = client.rebuildDocuments("project-docs", "1.1.0", "1.0.0",
    List.of("install"), true, DocumentDuplicatePolicy.UPSERT)
    .toCompletableFuture().join();

源必须是同一知识资源的不同 PUBLISHED MANAGED 版本；目标必须 DRAFT。原文读取需要当前租户及文档访问规则共同允许，平台管理员也不绕过，缺失或无权文档统一 DOCUMENT_NOT_AVAILABLE。含 tenant-a 原文要求实际凭据具有该租户的 APP_ADMIN 身份并符合文档规则；全局管理员没有该租户身份不能代替它读取。可从列表获取已知原文标识，但列表不返回正文。

重建保留 documentVersion，改变 chunkingHash/片段；源索引与历史 Run 引用不改写。显式新分块策略的托管引用包含原文 documentId、sourceRef.id/version 和 UTF-16 locator；sourceRef.version 为原文摘要版本，不是知识语义版本。旧策略继续保留旧片段 ID 引用行为。配置 knowledgeRouting 的 Agent 还提供 knowledgeVersion；未配置路由时固定知识版本可从 Run.agent 精确 Agent 发布版本的 allowedKnowledge 追溯。

HTTP API 与 SDK 方法

基础路径：/v1/apps/{app}/knowledge/{id}/versions/{version}/documents，所有接口需要管理身份和应用作用域。

操作	HTTP	Java/Kotlin 方法
单篇导入	POST 基础路径，ManagedDocumentImport	ingest，支持类型化文档及条件原文版本
列表（无正文）	GET 基础路径	documents
只读输入预览	POST /preview，ManagedDocumentContent	previewDocument
批量导入	POST /batch，documents/atomic/duplicatePolicy	importDocuments
新草稿重建	POST /rebuild，sourceVersion/documentIds/atomic/duplicatePolicy	rebuildDocuments
草稿删除	DELETE /	deleteDocument；已发布版本拒绝删除

管理页面和 SDK 都遵循同一平台契约。平台返回字段以公开 OpenAPI 为准，不自行下载外部 source 地址，不把来源字符串当成经过验证的预览链接。

验证证据

平台 clean build 150 项、后台 SDK 配置隔离平台的 clean build 87 项全部通过，无跳过；预览零写入、批次事务、幂等重复、条件版本、重建权限与旧引用、策略失配和发布预检内容变化均有行为验证。独立 HTTP 与管理页面验证通过；文档站 89 页及 6809 个链接/资源/锚点通过。没有真实向量索引、PDF/OCR 或外部语义服务的验收证据。

文档来源与验证记录

字段	内容
状态	已确认
日期	2026-10-01
来源	DocumentChunking、Knowledge、PlatformClient 与管理控制台
责任人	SparkTide 维护者
关联任务	K04
结论	先预览原文，按明确重复策略导入；在新知识草稿重建，验证后发布并切换智能体引用。