---
name: saa-graph-orchestration
description: "远期备查:SAA 图编排已降最低优先级、非生成主线(生成已统一 AgentScope)。仅当给 SAA 适配器布线或做远期「框架可换」可插拔验证时照本备查——依赖集/new-api baseUrl 剥 /v1/checkpoint saved_at 三承重坑;切勿据它起新生成主线。"
---

# SAA 图编排 playbook（远期适配备查 · HJ-AGI-002）

> **status：远期备查（SAA 降最低优先级）。** 生成框架已于 2026-06-25 统一收敛 **AgentScope**（三档按 AI 参与深度分），**SAA（Spring AI Alibaba v1.1.2.2）不再是生成主线**，只留作远期「框架可换」的可插拔适配验证目标。既有 SAA 图代码仍在 `game-cloud/game-module-aigc/game-module-aigc-server/.../saa/`（`SaaStudioGraph.java` 是唯一布线源；`SaaGraphDispatcher.java` 类仍在，但仅 `aigc.executor.dispatcher=saa` opt-in 时才派发、非现行主线——现行生成主派发 = `service/executor/GenerationDispatcher`〔默认 `dispatcher=http`〕经 worker 线投递到 Python worker）。给 SAA 适配器布线或做远期「框架可换」验证时照本备查；**不要按它起新的生成主线**。
> 迁移设计（9 步计划/拓扑/坑）见 `git show 6d2f8789^:docs/agent-specs/_archive/2026-06-15-python-to-SAA-migration-design.md`（已随 _archive 清理删除、git 定位）；SAA 能力/API dossier 与编排图说已收敛进 SoT 后删除，见 `git show ce7a4850^:docs/architecture/架构/生成引擎/SAA编排.md`。全量坑与决策见记忆 `saa-agentic-infra-decision`。

---

## 保留的承重坑与要点（远期布线仍会撞）

- **依赖集（最小证成集，别贪"完整推荐集"）**：`game-module-aigc/game-module-aigc-server/pom.xml` 引 **3 个 BOM**（`spring-ai-bom:1.1.2` / `spring-ai-alibaba-bom:1.1.2.2` / `spring-ai-alibaba-extensions-bom:1.1.2.2`，仅管版本、不引 spring-boot-dependencies）+ **3 个直接依赖**（`spring-ai-alibaba-graph-core`〔图引擎 + `MysqlSaver` + observation 机芯全在此〕/ `spring-ai-alibaba-starter-graph-observation`〔仅 Boot 自动配置层〕/ `spring-ai-starter-model-openai`〔接 new-api〕）。**别引** `agent-framework`（ReactAgent/asNode，与「done 由九门确定性门定、不让 LLM 自评」冲突）、`builtin-nodes`（脱 BOM 钉死 1.1.2.2、拖 tika 全家桶）、SAA 的 Boot BOM（让项目 3.5.14 胜，同 minor 补丁前向兼容）、`RedisSaver`（避 Redisson 3.22↔4.4 冲突）。**铁律**：动 pom 删依赖前先 `dependency:tree` / 读 jar 核类的模块归属（`MysqlSaver`、`GraphObservationLifecycleListener` 都在 `graph-core`）。

- **接 new-api：baseUrl 剥 `/v1` 坑**：Spring AI 自拼 `completionsPath=/v1/chat/completions`，故 `OpenAiApi.baseUrl` 必须是 **host 根、不带 `/v1`**（`http://100.64.0.8:3000`）；`.env` 的 `NEWAPI_BASE_URL` 常带 `/v1`，两侧通用须 Java 侧 `stripV1Suffix` 剥之，否则 404 `/v1/v1/...`。五角色（design/code/fix/player_text/player_vision）共用一个 `OpenAiApi`、仅 `defaultOptions.model/temperature` 异；全走 new-api 单一 key，自动入 `newapi_cost`（logs.quota）计费平面。

- **checkpoint `saved_at` 无 tiebreaker 坑（实证）**：`MysqlSaver.saved_at` 是**秒级 TIMESTAMP**，load checkpoint 的 SQL 仅 `ORDER BY saved_at DESC`、**无 tiebreaker**——一次 interrupt 在同秒落多条 checkpoint（`__START__→n1` 与 `n1→n2`），默认 `resume()`（取"最新"）**非确定**地选其一 → 续跑点漂移、节点重放。**修法（不改框架）**：用 `getStateHistory` 按内容（`StateSnapshot.node()=="n1"`）确定性选中断点、取其稳定 `config().checkPointId()`，用**显式 checkPointId** 续跑（走 saver by-id 精确分支，绕开 `saved_at` 排序）。另两条：resume 实例**不要再挂 `interruptBefore`**（`previousNodeId` 非 null 会再停该点、后续节点永不执行）；`releaseThread(false)` 才能长期续跑；表 `GRAPH_CHECKPOINT`/`GRAPH_THREAD` 是引擎私有大写 DDL、生产懒建、与 Flyway 零撞名。