知识提供器与自动注册

本页阅读位置

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

Kotlin 业务知识

kotlin

import dev.sparktide.sdk.AgentKnowledge
import dev.sparktide.sdk.KnowledgeQuery
import dev.sparktide.sdk.KnowledgeContext
import dev.sparktide.sdk.KnowledgeResult
import dev.sparktide.sdk.kotlin.KnowledgeProvider

@AgentKnowledge(name = "project-documents", description = "检索项目业务文档")
class ProjectKnowledgeProvider(private val documents: DocumentService) : KnowledgeProvider {
    override suspend fun retrieve(request: KnowledgeQuery, context: KnowledgeContext): KnowledgeResult {
        return documents.searchAuthorized(request.query(), context.userId(), context.tenantId(), request.topK())
    }
}

DocumentService 是业务已有服务，应返回 KnowledgeResult(List<KnowledgeDocument>)。每篇文档包含 id、text、title、source、tenantId。查询 topK 为 1..10，结果最多 100 篇，每篇文本最多 16384 字符。Provider 必须应用业务用户数据权限，回调适配器进一步在截断前过滤不匹配租户。空租户表示应用共享文档，不应将私人文档标为空租户。

Java 使用 dev.sparktide.sdk.KnowledgeProvider 的普通 retrieve 方法。Kotlin 使用上述 suspend 接口。身份由平台认证的回调提供，用户 Context 无权覆盖。错误不会返回伪造的空检索成功；过期回调返回 408，未分类 Provider 异常返回 503/KNOWLEDGE_UNAVAILABLE；拒绝和超时使用明确分类。

非 Spring 项目

Java 使用 new AnnotatedKnowledge(providerBean, endpoint, secretRef)；Kotlin 使用 annotatedKnowledge(providerBean, endpoint, secretRef)。将 resource.callback(appId, credentialSupplier) 挂载到该 endpoint 对应的 HTTP 路径，随后 resource.register(client) 创建草稿，显式发布 knowledge 并加入 Agent allowedKnowledge。回调密钥至少 32 字符，必须通过 HTTPS 或可信反向代理传输。

Spring Boot 自动接入

构建并发布到 Maven Local 后，Java 业务添加 dev.sparktide:sdk-spring-boot-starter:0.1.0-SNAPSHOT。Kotlin 业务额外添加 dev.sparktide:sdk-kotlin:0.1.0-SNAPSHOT。Starter 针对当前 Spring Boot 4.0.8 / Java 17 基线构建；不把未验证的 Boot 2/3 兼容性写成支持。

yaml

sparktide:
  enabled: true
  platform-url: ${SPARKTIDE_BASE_URL}
  app-id: monitor
  token: ${SPARKTIDE_APP_ADMIN_TOKEN}
  public-base-url: https://business.example.com/agent
  callback-token: ${SPARKTIDE_CALLBACK_TOKEN}
  secret-ref: MONITOR_CALLBACK_KEY
  ledger-directory: /var/lib/monitor/sparktide-ledger
  bind-address: 127.0.0.1
  callback-port: 8089
  callback-threads: 8
  lease-ttl-seconds: 30
  publish: false

将注解类作为 Spring Bean 注册，构造器注入原业务服务。SDK 不反射创建第二个业务实例。
将 public-base-url 下的请求转发到回调监听端口，保留完整路径。自动生成的路径为 /agent/tools/{name}/{version} 和 /agent/knowledge/{name}/{version}。端口独立于业务主端口。
在平台配置该 HTTPS origin、secret 名称、secret origin 与 SPARKTIDE_SECRET_APPLICATIONS=MONITOR_CALLBACK_KEY=monitor。密钥值必须与 callback-token 一致。
启动服务。Starter 校验定义和差异计划、注册草稿、挂载回调并首次续租；任一步失败会使启动失败并释放本地端口。
在 SDK 清单中将知识引用授予智能体，生产发布作业显式 release(reason)；开发显式 DEVELOPMENT + auto-sync=true 时整批预检并原子发布。详见声明式注册与启动发布。

默认 enabled 为 false。重复相同版本和定义由平台注册幂等处理，改变已发布内容必须升级版本。自动注册定义带 leaseRequired，服务停止后不再续租，租约过期后平台拒绝调用；不会撤销已发布版本或清除幂等账本。可通过 SparkTideRegistration.lastLeaseFailure() 读取续租异常。

不要解除业务安全代理。当前 Starter 遇到 AOP 代理能力 Bean 会拒绝启动，使用无代理的薄能力适配 Bean，内部调用带事务或鉴权的业务 Service，可保留原有拦截链。回调采用有界线程池；长任务须遵守截止时间，Java 同步方法的外部副作用不能被线程中断回滚。

普通 Kotlin 数据类

工具输入输出可直接使用普通 data class，不再要求 @JvmRecord。支持公开主构造函数、嵌套数据类、枚举、有限 List、字符串、布尔与数值。省略带默认值的参数会使用默认值；可空字段通过省略表达，输出 null 字段省略。显式 null、未知字段、递归类型、未解析泛型和任意 Map 均拒绝，避免声明 Schema 与执行规则不一致。

故障与回退

启动失败可能已在平台写入部分草稿，检查相同 id/version 的状态后修正配置再启动，不自动撤销已发布能力。平台鉴权失败、资源冲突、密钥归属错误都应修正原因，不关闭鉴权。回退时关闭 Starter，恢复显式挂载和注册，继续使用原账本目录。数据库或文件系统恢复前先停止回调写入。

新版已支持 KnowledgeItem/source/score/metadata 和 mandatoryFilters/appliedFilters；上方旧结果构造器仍兼容无强制条件。受限文档接入及错误 API 见外部知识协议与权限过滤。

文档来源与验证记录

字段	内容
状态	已确认：接口与配置；验证结果见项目状态
日期	2026-09-29
来源	AnnotatedKnowledge、DataClassCodec、SparkTideRegistration
责任人	项目维护者
关联任务	完整产品落地

知识提供器与自动注册 ​

Kotlin 业务知识 ​

非 Spring 项目 ​

Spring Boot 自动接入 ​