批次预检与发布

业务接入默认通过后台 SDK 声明与发布，见业务后台 SDK。以下管理流程用于查看、调试及显式治理；代码声明的资源显示来源，不能从管理页无痕修改。

适用范围

需要应用管理员或平台管理员身份；一个批次 1–64 个精确版本，整个依赖图最多 256 项。公共供应商和模型需在平台管理入口先发布。批次只处理资源发布和可选默认入口切换，不调用模型或业务工具。

SDK 发布路径

常规业务在代码中定义 RegistrationManifest，用稳定 managedBy 标识归属。Spring 启动合并模型、注解工具与知识清单；开发显式 DEVELOPMENT / auto-sync=true，生产 PRODUCTION / auto-sync=false。

生产受控发布程序读取 SparkTideRegistration.registrationReport()，检查后调用 release(reason)。纯 JVM 程序使用 DeclaredApplication.inspect() 和 publish(reason)。完整参数与错误见声明式注册与发布。

需要切换已发布的默认入口时，先通过 PlatformClient.application() 读取 revision，再调用 defaultAgent(id, version, revision)，发生冲突先核查当前配置。教程附带完整 selectAgent 命令。随后让配置中的默认版本与新入口保持一致，不依赖启动隐式覆盖。

回滚选择仍处于 PUBLISHED 的旧版本并同步业务声明；不复活 REVOKED、不删除运行历史或账本。下面是可选控制台操作与底层合同。

控制台操作

在各能力目录保存所有草稿；草稿的完整 JSON 可引用同批草稿的精确版本。
打开「发布管理」，勾选本批草稿，选择默认入口或保持原入口，填写发布说明。
点击「检查依赖与修订」。修复所有提示，包括无效 Schema、缺失或撤销的依赖、委托边界、循环依赖、过期租约；资源变化后重新载入和预检。
预检通过后确认整批发布。记录显示实际发布修订、原默认入口和新默认入口；发布成功后查看详情。
网络异常时保持页面和输入，再次确认使用同一幂等请求标识。刷新或变更输入前先核对发布记录。

HTTP 接入

所有路径前缀 /v1/apps/{app}。预检 POST /release-plans，提交 POST /releases；查询 GET /releases?limit=50&offset=0，详情 GET /releases/{releaseId}。

json

{
  "resources": [
    {"kind":"tools","id":"query-device","version":"1.0.0","revision":1},
    {"kind":"agents","id":"monitor-agent","version":"1.1.0","revision":2}
  ],
  "defaultAgent":{"id":"monitor-agent","version":"1.1.0"},
  "reason":"上线监测设备查询能力"
}

预检返回 valid/planHash/applicationRevision/dependencyCount/errors。错误项包含 resource/code/message；无效计划 planHash=null，不允许提交。提交正文与预检一致，必须携带：

请求头	取值
If-Match	预检的 applicationRevision，带双引号
X-Release-Plan	预检的 64 位小写 SHA256
Idempotency-Key	同一次发布稳定的 1–128 位 ASCII 字母、数字、下划线、点、冒号或连字符

同管理主体、同应用、同键和相同正文/预检头复用原记录；正文或头不同返回 409 IDEMPOTENCY_CONFLICT。应用或草稿修订变化返回 412；依赖变化或不可用返回 409 RELEASE_PLAN_CHANGED / RELEASE_INVALID，重新预检后使用新键。

发布与回退

同一事务核对所有修订、验证所有依赖、更新草稿状态、更新可选默认入口、写发布记录与审计。任何数据库写入失败整批回退。已发布资源可以作为批次成员，保持原修订，不重新发布。

已成功发布的版本不可编辑。回退时在智能体列表把默认入口切回 previousDefaultAgent 的已发布版本；如果该版本已撤销，则发布修正版。原执行计划不随切换改动，已有业务副作用不自动回滚。停用或归档应用保持原状态；仅初次 DRAFT 应用设置默认入口变为 ACTIVE。

升级前备份数据库，V9 增加发布记录表。回退程序保留新增表，停止使用新入口即可；不要手工删除历史记录或修改已发布定义。

文档来源与验证记录

字段	内容
状态	已确认
日期	2026-09-30
来源	ReleaseBundles、Api、V9 迁移、PlatformIntegrationTest
责任人	SparkTide 维护者
关联任务	G05、B08
结论	同一应用的依赖草稿可在一个事务内发布，并保留可查询的发布记录
证据	草稿链、修订冲突、依赖撤销、数据库故障回滚、幂等与生命周期测试

批次预检与发布 ​

适用范围 ​

SDK 发布路径 ​

控制台操作 ​