Agent 预览与提升

目标

把一个 Agent 在 Sandbox 里完成的工作，从”可变的工作区状态”冻结成一个不可变的 Source Artifact，生成候选预览，再经过外部确认，显式提升为正式的 Project/Resource 部署。

适用场景

用户让 Agent 在 Sandbox 里生成或修改一个应用，需要先预览效果再决定是否上线。
需要保证”预览看到的内容”和”最终部署的内容”逐字节一致，不允许中途被悄悄替换。

前置条件

Sandbox 处于 ready 状态，且没有正在执行的 Run——Capture 只在这个条件下才被允许。
已知目标 Project、Environment 和 Destination。

输入与默认值

输入	说明
`sourceRoot`	Sandbox 内要捕获的相对路径
`expectedArtifactDigest`	调用方期望的 Artifact 内容摘要，用于防止中途被替换
`target`	提升的目标：Project id、Environment id、Destination id、Resource 名称

CLI / SDK 操作步骤

// 1. 捕获：验证相对路径、文件数量和总大小，为每个文件计算 digest，
//    并用有序安全 manifest 计算出一个 Source Artifact digest
const artifact = await appaloft.sandboxes.sourceArtifacts.create({ sandboxId, sourceRoot: "app" });

// 2. 生成候选预览：后续预览只读取 Artifact Store，不会再读取可变的 live workspace
const preview = await appaloft.sandboxes.candidatePreviews.create({ artifactId: artifact.data.artifactId });

// 3. 生成提升计划：绑定 artifact digest、已验证的候选、目标和过期时间
const plan = await appaloft.sandboxes.promotions.plan({
  sandboxId,
  artifactId: artifact.data.artifactId,
  expectedArtifactDigest: artifact.data.digest,
  candidatePreviewId: preview.data.previewId,
  target: { projectId, environmentId, destinationId, resourceName: "Generated app" },
});

// 4. 接受提升：这是外部控制面动作，Sandbox 内的 Runtime/Harness 身份不能自我批准
await appaloft.sandboxes.promotions.accept({
  promotionId: plan.data.promotionId,
  expectedArtifactDigest: artifact.data.digest,
  idempotencyKey: crypto.randomUUID(),
});

预期输出与状态

产品集成应该默认停在 plan 这一步：先把候选 URL 和精确 digest 展示给用户，只有外部控制面的显式确认动作才能调用 accept：

if (preview.data.artifactDigest !== artifact.data.digest) {
  throw new Error("digest mismatch");
}

if (userConfirmedPromotion) {
  await appaloft.sandboxes.promotions.accept({
    promotionId: plan.data.promotionId,
    expectedArtifactDigest: artifact.data.digest,
    idempotencyKey: crypto.randomUUID(),
  });
}

验证

Accept 成功后会创建 Resource 和首次 Deployment；持久化的工作流会保存这两者的 Checkpoint，即使中途重启也不会重复创建已经记录的 Resource。接下来可以按部署生命周期的验证方式确认部署已经就绪。

回滚 / 恢复

如果两次读取到的 Artifact digest 不一致（digest mismatch），说明工作区内容在捕获后被改变过——应该重新执行捕获流程，而不是强行继续提升一个可能不一致的候选。

目标