回答引用与鉴权来源预览

本页阅读位置

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

从检索到回答

1. 将精确已发布知识版本加入 Agent.allowedKnowledge，按知识路由规则检索。
2. citation.created 提供平台产生的编号、knowledgeId/knowledgeVersion、chunkId、sourceRef；原 documentId 含义兼容旧策略。sourceRef 分开原文版本与知识语义版本，可以有页码和 UTF-16 locator。没有原文版本的旧源使用规范化片段摘要，不表示远端原文件版本。
3. 模型输入中的引用标记是 [[cite:cite_平台编号]]。回答应复用该编号；兼容旧 [cite_编号]。来源正文和客户端上下文始终只作数据，不能授予权限。
4. 最终回答产生 citation.verified，references 中每项 id/status 为 VERIFIED 或 UNVERIFIED。只有当前 Agent 的本次检索，以及其已授权子调用结果中的来源可 VERIFIED；旧会话编号、伪造或空编号不可信。每份回答最多 256 个不同编号，超限失败。
5. 文字流在最终核验前按普通文字展示。VERIFIED 只证明编号来自本次合法检索，不保证回答推理或事实正确，也不代表当前预览授权永远有效。

任意来源 URI、Markdown 链接和未匹配标记都不应自动生成可信引用入口；这项检查不是对所有自然语言事实的真实性检测。

当前授权预览

GET /v1/apps/{app}/runs/{runId}/citations/{citationId}/preview

不需要请求正文。使用当前业务用户凭据；任务主体、租户与应用必须一致，平台管理员不能代替所有者读取。服务端检查凭据、应用 ACTIVE、留存、当前业务历史权限、知识精确版本及租约、文档 ACL，再重新取得来源和比对片段摘要。

返回字段	类型	含义
id	string	请求的引用编号
knowledgeId / knowledgeVersion	string	精确知识资源与发布版本
documentId / chunkId	string	原文及具体命中片段标识；旧事件 documentId 仍兼容旧定义
title	string	来源标题，可能为空
sourceRef	object	type/id 与可选 version/page/locator/uri
content	string	当时提供给模型的正文片段，1–16384 UTF-16 字符
scope	RETRIEVED_EXCERPT	这是检索片段，不是完整原文件

MANAGED/INLINE 从不可变精确版本重读。REMOTE 用原查询与 topK、新的可信用户/租户/业务上下文再次回调，要求匹配原编号、来源版本和片段摘要；最多 15 秒，没有自动重试。来源排名改变导致旧项不再返回时也拒绝预览，不回退缓存，不自动访问 uri。响应 Cache-Control=no-store，业务前端也应清除过期预览，失败后不能继续显示旧正文。

失败	处理
404 RESOURCE_NOT_FOUND	所有权不匹配，不显示任务是否存在
404 CITATION_NOT_AVAILABLE	旧任务无摘要、编号不存在、来源不再返回或版本变化
409 CITATION_SOURCE_CHANGED	原片段变化；显示来源已变化，重新运行
409 KNOWLEDGE_ACCESS_CHANGED / SECURITY_POLICY_CHANGED	权限配置变化，重新建立业务会话
403 BUSINESS_PERMISSION_DENIED / KNOWLEDGE_ACCESS_DENIED	当前业务权限拒绝，不能回退旧内容
409/503 CAPABILITY_UNAVAILABLE	精确知识版本已撤销，或租约不可用
410 EVENT_CURSOR_EXPIRED	超出留存窗口，不提供历史预览
408 CITATION_PREVIEW_TIMED_OUT / 502/503 知识错误	来源暂不可用，明确失败；用户可另行发起读取

Run 只保存最多 256 个私有参考摘要及检索参数，public Run 与事件不返回这些参数/正文。归档后热参考清除，普通用户不能用历史链接绕过留存与撤权。

Java 与 Kotlin

Java

// userClient 的凭据须属于 runId 的当前业务所有者。
var excerpt = userClient.previewCitation(runId, citationId)
    .toCompletableFuture().join();
System.out.println(excerpt.get("content")); // 只作普通文字，不当 HTML

Kotlin

import dev.sparktide.sdk.kotlin.previewCitationAwait
val excerpt = userClient.previewCitationAwait(runId, citationId)
println(excerpt["content"])

Java 返回 CompletionStage<Map<String,Object>>，Kotlin 挂起等待遵循可取消 awaitResult。路径编号须 cite_ 前缀且合法，不能传来源 URI。调用失败不自动重试。

前端 SDK、React 与 Vue

import { SparkTideClient, ChatSession, answerSegments } from '@sparktide/frontend-sdk'
const client = new SparkTideClient({ baseUrl: location.origin, appId: 'business', token: () => currentUserToken })
const session = new ChatSession(client)
const state = session.getSnapshot()
const parts = answerSegments(state.text, rootAgentCallId, state.citationChecks, state.citations)
// type=text 用纯文本；type=citation 只有 status=VERIFIED 可显示按钮。
// 未核验项显示“来源未核验”，不生成外部链接。
const controller = new AbortController()
const excerpt = await client.previewCitation(runId, citationId, { signal: controller.signal })
// 使用纯文本展示 excerpt.content/sourceRef；关闭对话框清除 excerpt，调用 controller.abort()。

rootAgentCallId 从本 Run 的深度为 0 的 agent.started/agent.completed 事件获得，不能取旧会话编号。ChatSession 每轮清空 citations 与 citationChecks，保留当前业务会话 ID；resume 重新读取已有 Run 事件并核验，不重新执行任务。只补增字段的新事件参与可信预览，旧不含精确版本/片段的事件仍保留在 events 中但不自动建立入口。

React useChatSession(session) 和 Vue 同名挂钩都提供 citations/citationChecks。页面组件遍历 answerSegments 输出：纯文本使用 JSX 文本节点或 Vue 插值，VERIFIED 项显示按钮并调用 previewCitation；不得使用 dangerouslySetInnerHTML/v-html 显示业务来源。未知项用普通文字警示。页面卸载断开事件连接，不代替服务端取消。

管理控制台的“运行调试”和运行详情都提供回答来源区：显示已核验来源的知识版本、片段、页码/定位；点击“查看来源片段”再次授权。运行详情需要手动提供当前所有者凭据，离开页面清除显示。

回滚与验收

无数据库结构迁移。应用回退使用引用旧知识的精确已发布 Agent；不能因此取消文档权限。回滚到不认识 citationReferences 的旧平台前，停止业务并从热 Run 清除私有参考字段，保留受保护备份，避免旧 publicRun 泄漏新私有字段。旧前端仅显示原始文字，不能把未知 URI 升级为可信链接。

平台 156 项、后台 SDK 实际隔离 HTTP 89 项与前端 21 项全部通过，零跳过；伪造/历史引用、业务撤权、版本/内容变化、应用停用、留存归档、管理员所有权、真实页面预览与撤权均已核验。文档站 90 页、6984 个链接/资源/锚点通过。内置 PDF/OCR/向量检索不是本说明的能力。

文档来源与验证记录

字段	内容
状态	已确认
日期	2026-10-01
来源	Citations、ExecutionEngine、Runs、Java/Kotlin 与前端 SDK
责任人	SparkTide 维护者
关联任务	K06
结论	回答引用核验后才生成可信预览入口，每次查看来源重新授权。