生产级 LLM Agent 的「七大防坑铁律」：CAS 乐观锁、双通道输出分离与历史快照脱水

一、 为什么玩具级 Agent 架构上不了生产环境？

在简单的聊天机器人场景中，大模型只是在追加纯文本消息（Append-Only Text）。但在 苏诺之音 的多轮音乐与 MV 创作工作台中，Agent 与人类创作者是在共同编辑同一份复杂的业务状态树（包含歌词段落、曲风标签、角色资产库、几十个分镜头的起止时间与关键帧状态）。

如果直接套用“把完整状态塞进 Prompt → 让 LLM 返回新状态 → 覆盖数据库”的粗放模式，在生产环境中必然引发灾难。为此，我们在工程底座上确立了不可妥协的七大架构防坑铁律：

二、 深度拆解核心铁律与工程实现

铁律 1 & 2：CAS 乐观并发锁（Compare-And-Swap）与三方合并自愈

当 Agent 正在后台花费 15 秒生成第 5~10 号分镜脚本时，用户在前端界面手动修改了第 2 号分镜的歌词或画面描述。此时如果 Agent 完成任务后直接执行整表 UPDATE，用户的手动修改就会被瞬间静默抹除！

为了彻底根除这一“幽灵覆盖”，苏诺之音在所有状态变更接口强制实施基于 revision 版本号的 CAS 乐观锁，并在发生版本冲突时返回 HTTP 409 REVISION_CONFLICT，触发前端可视化三方合并（3-Way Merge）弹窗：

核心数据库原子更新逻辑如下：

// 基于 Revision 版本号的 CAS 乐观锁原子更新实现
export async function commitProjectPatchWithCAS(params: {
  projectId: string;
  expectedRevision: number;
  patchFieldPaths: string[];
  nextStatePayload: Record<string, unknown>;
}) {
  const { projectId, expectedRevision, patchFieldPaths, nextStatePayload } = params;

  // 仅当数据库当前 revision 严格等于 expectedRevision 时才允许更新并自增版本号
  const updatedRows = await db
    .update(mvProjectsTable)
    .set({
      stateJson: nextStatePayload,
      revision: sql`${mvProjectsTable.revision} + 1`,
      updatedAt: new Date(),
    })
    .where(
      and(
        eq(mvProjectsTable.id, projectId),
        eq(mvProjectsTable.revision, expectedRevision)
      )
    )
    .returning({ newRevision: mvProjectsTable.revision });

  if (updatedRows.length === 0) {
    const latestRecord = await db.query.mvProjectsTable.findFirst({
      where: eq(mvProjectsTable.id, projectId),
    });
    throw new RevisionConflictError({
      code: 'REVISION_CONFLICT',
      status: 409,
      clientBaseRevision: expectedRevision,
      serverCurrentRevision: latestRecord?.revision ?? -1,
      conflictingPaths: patchFieldPaths,
      serverSnapshot: latestRecord?.stateJson,
    });
  }

  return updatedRows[0];
}

铁律 3：双通道输出分离（LLM 语义增量 vs 后端确定性持久化）

严禁让大模型在 Tool Call 中一次性回传包含几十个分镜完整 URL 与元数据的巨型 JSON。正确的架构是将输出拆分为两条正交管道：

• 通道 A（LLM 语义增量通道）：模型仅输出本次变更的最小语义增量（如 shotId: "shot_03", revisedPrompt: "..."），体量控制在数百 Token 以内，响应极快且绝不会因输出截断而损坏 JSON 结构；
• 通道 B（后端确定性执行通道）：后端工具函数接收轻量级增量后，在内存中进行确定性的树结构合并、Schema 校验与数据库持久化，并通过 SSE 事件流将精确的 StateDelta 推送给前端。

铁律 4：历史消息快照脱水（Context Dehydration，节省 90% Token）

在长达 20 轮的多轮创作会话中，如果每一轮 Tool Result 都把完整的项目快照（动辄 8,000+ Tokens）保留在历史消息数组里，第 15 轮对话的单次请求输入就会突破 12 万 Tokens，不仅响应延迟飙升，还会导致模型注意力被过期历史快照严重干扰。

苏诺之音实现了历史快照自动脱水中间件（Snapshot Dehydrator）：

• 对于历史轮次（turnIndex < currentTurn - 1）中的大型工具返回值，自动将其剥离为一行紧凑摘要：[Dehydrated Snapshot: rev=14, shots=18, status=STAGE3_READY]；
• 仅在当前最新轮次的 System Context 中注入唯一一份与数据库实时同步的 LatestAuthoritativeState，使多轮上下文体积恒定收敛，Token 消耗降低 90% 以上。

铁律 5 ~ 7：无限画布非阻塞交互、流式保活与生命周期门禁

在前端工作台体验上，苏诺之音 Agent 工作台配合无限画布（Infinite Canvas）实现了非阻塞异步流转——即使某个重型音频/视频任务仍在后台合成，创作者依然可以在画布上自由拖拽比对历史版本、使用一键“自动排列”规整卡片，且后台任务严格绑定 Run 生命周期令牌，彻底杜绝超时僵尸任务回写污染最新画布。

三、 架构演进前后核心指标对比