SDK 来源引用
启用实验性引用元数据，按最终消息中的 UTF-16 区间关联来源。
Citations 为助手回答中的文本区间关联支持来源，可用于脚注、行内引用或来源列表。此能力仍属实验性，选项、事件字段及提供商覆盖范围可能变化，不在兼容性保证范围内。
启用并提供可引用材料
创建会话时设置 enableCitations: true；重启后恢复会话，也要在恢复选项中重新设置。仅打开选项不会强制每次回答都有引用，应用必须把 citations 当作可选数据。
来源可以是附件文档，或工具结果的实验性 citableSources 数组。工具来源项包含 id、content，以及可选 title、url、path；它们随工具结果持久化，可跨会话恢复，由 runtime 生成的引用标记为 client。
使用 Anthropic 提供商且启用引用时，文件附件作为开启 citations 的 document blocks 发送。例如应用可以通过 blob 附件提供 Base64 PDF、mimeType: "application/pdf" 和显示名称；附件基本形状见图片与附件输入。不要由此推断所有提供商对 PDF 或工具来源的支持相同。
等最终消息，再添加引用标记
引用出现在最终 assistant.message 的 data.citations，不出现在 assistant.message_delta。流式阶段可以先显示正文，完整消息到达后再按最终文本放置来源标记：
session.on((event) => {
if (event.type !== "assistant.message" || !event.data.citations) return;
const { sources, spans } = event.data.citations;
const sourceById = new Map(sources.map((source) => [source.id, source]));
for (const span of spans) {
const text = event.data.content.slice(span.startIndex, span.endIndex);
for (const reference of span.references) {
const source = sourceById.get(reference.sourceId);
console.log(text, source?.title ?? source?.url ?? source?.path ?? source?.id);
}
}
});不要用增量字符串的局部位置解释最终 span，也不要因为没有引用就认定会话失败。
数据结构与偏移单位
sources 是去重的来源数组；spans 描述回答中的哪些区间引用了哪些来源。同一来源支持多段文字时，不必重复创建来源记录。
| 层级 | 字段 | 含义 |
|---|---|---|
| 来源 | id | 当前 turn 范围内的稳定标识 |
| 来源 | provider | anthropic、openai 或 client |
| 来源 | title、url、path | 可选显示标题、网页 URL、相对代理工作区根目录的文件路径 |
| 文本区间 | startIndex、endIndex | 最终 content 中从零开始、左含右不含的 UTF-16 code units 偏移 |
| 文本区间 | references | 支持该区间的引用项 |
| 引用项 | sourceId | 关联 sources 中的 id |
| 引用项 | citedText、location | 可选原文及来源位置 |
| 引用项 | providerMetadata | 可选提供商原生关联数据，按不透明数据处理 |
TypeScript、Java、.NET 字符串使用 UTF-16，可按上述单位切片。Python 字符串按 Unicode code point 索引，Go 和 Rust 为 UTF-8，不能直接把这些偏移当本语言字符或字节位置。
来源位置 location.type 可为 char、page、block，分别使用 startIndex/endIndex、startPage/endPage、startBlock/endBlock。这里不把回答 span 的偏移规则未经核实地外推为所有来源位置类型的单位和边界约定。
能力边界
provider 记录引用来自 Anthropic、OpenAI，还是 runtime 从工具结果生成；枚举存在不代表每个模型均能返回引用。未支持的提供商可能没有 citations payload。公共代码匹配或 IP duplication 的引用也不属于这一接口，不能用它替代代码匹配策略。