声明式注册与启动发布

本页阅读位置

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

选择注册方式

推荐用类型化 RegistrationManifest 声明模型、配置和智能体，@AgentTool / @AgentKnowledge 接入实际业务 Bean；YAML 可用于已有固定能力配置。它们按 kind/id/version 合并，重复项直接报错。非 Spring 项目使用 Java 清单或 Kotlin DSL。一个清单最多 64 项，身份是应用管理凭据，不能通过定义扩展到其他应用或公共模型。

默认用 ApplicationBootstrap 在受控初始化作业创建应用，类型化清单声明提供商、模型、绑定、配置和智能体。完整链路见 业务后台 SDK。下文保留已有 YAML/手动管理资源的兼容示例。配置业务回调的可信 origin、密钥引用及所属应用授权。回调凭据与平台管理凭据独立，通过环境或 Secret 注入。

推荐的 Spring 声明与生产发布

完整清单 Bean 从后台教程复制。managedBy 与 deployment.source 使用相同的稳定归属；相同版本内容变化需创建新语义版本，不无痕覆盖旧版本。

sparktide:
  deployment:
    mode: PRODUCTION
    source: orders-service
    auto-sync: false

启动完成后，在受控发布程序读取 SparkTideRegistration.registrationReport()，处理无效、归属冲突和修订变化，再显式调用 release("发布原因").toCompletableFuture().join()。这些是后台管理方法，不向浏览器暴露。

开发显式使用 DEVELOPMENT / auto-sync=true 才在预检后同步发布。chat.enabled 与能力注册独立，聊天网关可以关闭 sparktide.enabled 并不持有管理凭据。默认入口已有不同版本时，不通过自动启动覆盖它，先使用 SDK 的受控入口切换并同步配置。

Spring Boot YAML

下例使用已有已发布的 binding@1.0.0，以及项目中的 @AgentTool(name="query-device") Bean；没有该 Bean 时去掉 allowedTools 引用。全部未发布依赖必须放入 definitions 或由注解提供，集合之外的依赖需已发布。

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
  callback-port: 8089
  auto-register: true
  deployment:
    mode: PRODUCTION
    source: business-service
    auto-sync: false
  default-agent:
    id: monitor-agent
    version: 1.0.0
  definitions:
    - kind: model-profiles
      id: profile
      version: 1.0.0
      definition:
        binding: { id: binding, version: 1.0.0 }
        maxOutputTokens: 1024
    - kind: agents
      id: monitor-agent
      version: 1.0.0
      definition:
        systemPrompt: 根据业务权限查询设备并回答问题。
        modelProfile: { id: profile, version: 1.0.0 }
        allowedTools:
          - { id: query-device, version: 1.0.0 }
        entryPolicy: { mode: APPLICATION }

字段保持平台定义原有大小写；列表、嵌套 Schema 与 JSON 字段使用实际 YAML 类型，布尔值不用引号。Schema 的 required/enum 保持数组，properties 保持对象，数字字段名仍是字段名。空对象的 properties 按平台对象方言规范化为空对象。

配置	默认	行为
enabled	false	显式启用 Starter
auto-register	true	false 仅读取差异计划，不注册、发布、监听回调或续租
deployment.mode / auto-sync	PRODUCTION / false	开发显式 DEVELOPMENT / true；生产显式 release(reason)，禁止启动发布
definitions	空集合	当前应用的精确版本定义；可以只有 YAML 而没有注解
default-agent	省略	首次启用空入口；已有相同入口不修改，不同入口拒绝自动覆盖

只生成计划使用 auto-register: false。生产发布作业查看 registrationReport 后显式调用 SparkTideRegistration.release(reason)；非 Spring 使用 DeclaredApplication.publish(reason)。开发自动同步需 DEVELOPMENT + auto-sync=true；旧 publish=true 仅在显式开发模式兼容，生产启动会拒绝。代码清单须保持相同 source，旧人工定义不可自动认领。

已有入口升级时先省略 default-agent，发布新版本，再在平台管理中明确切换入口。不会因为旧部署重启而覆盖管理员已切换的默认入口。应用配置在启动过程中发生变更也会拒绝发布。

差异报告与就绪

status	意义	自动执行
CREATE	精确版本不存在	创建草稿
UNCHANGED_DRAFT	相同定义的草稿	保留，等待发布
UNCHANGED_PUBLISHED	相同定义已发布	保留；整批已发布且入口相同则不再创建发布记录
CONFLICT	相同版本定义不同	停止，升级版本或在管理端明确修改
REVOKED	版本已撤销	停止，创建新版本

通过 Spring Bean SparkTideRegistration 读取 registrationReport()、publication()、capabilitiesReady() 与 lastLeaseFailure()。isRunning 表示生命周期已启动；capabilitiesReady 还要求清单全部已发布、启用实际注册且未记录续租异常。它是本地配置/续租状态，不能替代平台实时授权、应用状态或真实模型健康。

人工发布或撤销之后调用 refreshRegistration().toCompletableFuture().join() 仅读回报告并更新就绪。发生续租异常后保持保守的未就绪状态，修复连接并重启确认；不把一次读取当作续租恢复证据。

SDK 示例

Java

var manifest = new RegistrationManifest(List.of(
    new CapabilityDefinition("model-profiles", "profile", "1.0.0",
        Map.of("binding", Map.of("id", "binding", "version", "1.0.0"),
            "maxOutputTokens", 1024))
));
var plan = manifest.prepare(client).toCompletableFuture().join(); // 仅读取
System.out.println(plan.report());
if (!plan.valid()) throw new IllegalStateException("配置冲突，停止部署");
var drafts = plan.registerDrafts().toCompletableFuture().join();
var bundle = drafts.bundle(null, "发布经审核的业务配置");
// 如有本地远程回调，在提交发布之前挂载、首次续租；发布流程见批次预检与发布。

Kotlin

import dev.sparktide.sdk.kotlin.*
val manifest = registrationManifest {
    resource("model-profiles", "profile", "1.0.0", mapOf(
        "binding" to mapOf("id" to "binding", "version" to "1.0.0"),
        "maxOutputTokens" to 1024
    ))
}
val plan = manifest.prepare(client).awaitResult()
check(plan.valid()) { "配置冲突：${plan.report()}" }
val drafts = plan.registerDrafts().awaitResult()

Java 示例说明：

client 是应用管理身份的 PlatformClient。定义按构造时快照冻结。执行前重读所有精确版本，修订变化停止；不会自动调用 update 覆盖已有定义。平台仍会验证完整定义、归属、密钥和依赖。

故障、升级与关闭

草稿注册是多个请求，失败可能留下未发布草稿；最终发布使用平台事务，不会暴露半批发布集合。预检失败修正原因后重新准备计划。提交响应不确定时先核对发布记录；不承诺跨系统 exactly-once，也不自动重放业务副作用。

关闭会停止回调与租约心跳，已发布版本不自动撤销，其他副本仍能续租。生产保持 auto-sync=false，关闭能力注册可设 sparktide.enabled=false；关闭新聊天入口设 chat.enabled=false。恢复旧默认入口使用 SDK 或显式管理操作，保留发布记录和业务执行账本。

文档来源与验证记录

字段	内容
状态	已确认
日期	2026-09-30
来源	RegistrationManifest、RegistrationPlan、Starter、平台 V9 发布合同
责任人	SparkTide 维护者
关联任务	B08、B07
结论	注解与 YAML 共用差异计划，拒绝覆盖配置，整批预检后发布
证据	只读计划、并发修订、重复启动、失败预检、租约顺序、实际 YAML 类型与本地实际平台测试