games-development-ai/docs/agent-specs/agentic编排-SAA.md

agentic 编排 · SAA · canonical（子系统 SoT）

类型=canonical 活档（子系统单一事实源）· 更新 2026-06-17 取代=7 份历史 spec（目标架构-review / 能力 API dossier / form① e2e-runplan / round2 verdict / round3 verdict / 组B trace 接线-execution / agent-loop-v1 退役登记；已 FOLD 删或归档，见 git 历史与 _archive/） 读法=读本档即知现行真相；深落地（拓扑/全部坑/file:line）见 .agents/skills/saa-graph-orchestration.md；API 逐键源码旁证见 dossier；决策史见 git。

---

0. 现状一句话 + 决策口径（结论先行）

现行 = Spring AI Alibaba（SAA，GA v1.1.2.2）裸 StateGraph 编排——game-cloud agentic 生成编排基建，决策 ID HJ-AGI-002（演进自 HJ-AGI-001「agentic 基建=AgentScope」）。三条口径锚定：

1. short-term = SAA-only / long-term = AgentScope 降 premium 独立轨（极高质量·宽预算·独立 App，与生产解耦）。
2. 生产逻辑藏在 job/callback 契约#6 之后（GenerationDispatcher 接口），框架可换；"done" 由九门确定性门裁定、不让 LLM 自评；模型只走单一 new-api 成本/凭证层。
3. 当前状态 = 16 节点 studio 已建并合入 dev/2.0.0（render·classify·design·generate·validate·scaffold·asset·build·play·player·nreview·modify·escalate·repair·emit·giveup；裸图确定性编排=接法A，已建约七成、是躯干）；dispatcher=saa 进程内派发路真跑全链（form① + 真全图 e2e 首证 SaaFullGraphE2eTest）；trace split-brain 真库已闭合（703e462c）。两条产线状态须分清：现默认产线 = iife/GameConfig 路（SaaFullGraphE2eTest 成功率 60%、U7 worker→SAA cutover 按门未切）；gameDefinition 真结构化 studio = 已双证（2026-06-18，见 §7）、产线化中替换它。SAA 现由本 session 独家开发（协调红线解除）。剩余 = 双证 PoC 产线化（plan docs/plans/2026-06-18-001）+ W-G1 开闸门 + F1/F3/F5 follow-up。

现行真相基准对齐（AGENTS §3 / tech-decisions §4）：玩法模板未废待建（=品类 prompt 模板，主 agent 调度子 agent 用，非代码非节点；废的是游戏模板/填参线）· LittleJS（Tier1）· new-api 网关 · 命名空间 com.wanxiang.huijing · 对外品牌绘境AI。

---

1. 为什么是 SAA-only（决策理由 · 精炼）

1. 本项目绝大多数 agentic 活 = 确定性多步「编排型」（生成主线 / 五资产 / 远期 mode-C），只有少数 Tier-3「自治型」（多 agent 开发组）才需嵌入式 agent。故主干用裸图编排，不用 ReactAgent/FlowAgent（那是给「LLM+工具自治」的）。
2. SAA 自带完整 agentic（StateGraph + ReactAgent + ReactAgent.asNode() + FlowAgent.subAgents + 子图 SubGraphNode + Mysql/RedisSaver + A2A/MCP/Admin），子 agent 调用是 SAA 原生能力——生产不需也不嵌 AgentScope，回归 HJ-AGI-001「只养一套基建」初衷。
3. 双评审（Codex+Opus）源码证伪外部「asNode 嵌 2.0」建议：asNode() 在 SAA spring-ai-alibaba-starter-agentscope，绑 agentscope-core 1.0.9、只代理单个 ReActAgent；本地 agentscope-java 是 2.0.0-SNAPSHOT——把 2.0 嵌进 1.0.9 接缝属未验证路径。AgentScope 开源贡献作独立轨、与生产解耦。

---

2. 现行架构（图 + 四类负载映射）

flowchart LR
  subgraph GC[game-cloud 单体]
    JOB[job/callback 契约#6\n稳定接缝·框架可换]
  end
  subgraph SAA[SAA StateGraph 编排主干 · GA v1.1.2.2]
    direction TB
    N1[render] --> N2[generate\nGameConfig]
    N2 --> N3{schema 校验}
    N3 -- 不合法 --> NR
    N3 -- 合法 --> N4[scaffold] --> N5[build] --> N6[play\n九门真玩 harness]
    N6 -- 门失败/player软门 --> NR
    N6 -- 门通过 --> N7[emit]
    NR[repair 受约束 LLM 节点] --> N2
  end
  subgraph EXT[复用既有确定性 harness（子进程）]
    BUILD[esbuild/node]
    PLAY[CDP 九门 play.cdp.cjs]
  end
  subgraph STORE[已部署存储·零新基建]
    MY[(MySQL)]
    RD[(Redis)]
  end
  JOB --> SAA
  N5 -. shell .-> BUILD
  N6 -. shell .-> PLAY
  SAA -. state checkpoint .-> MY
  SAA -. session/短期记忆 .-> RD

要点：确定性门（九门）= 图的条件边，由 harness 真玩裁定 done；build/play 复用既有 harness 零重写；repair 起步是受约束 LLM 节点；state checkpoint 到 MySQL+Redis，Phase1 零新基建。

上图 = 现默认产线（iife/GameConfig 路）的精简骨架——generate 产 iife factorySrc、build 不读结构化源。目标态 = gameDefinition 真结构化 studio：16 节点全图（render·classify·design·generate·validate·scaffold·asset·build·play·player·nreview·modify·escalate·repair·emit·giveup）已建并合入 dev/2.0.0，generate 改产声明式 gameDefinition（entities/components/scenes/rules + behaviors 各带逻辑 JS，用运行时访问约定 rt）、build 改走 build-from-source（gameDefinition→装配→engineBundle，九门 harness 零改）。该路已双证（§7）、产线化中替换 iife 路；全图拓扑/8 契约/救场阶梯权威见 固定游戏架构与SAA-agentic-studio-execution，产线化执行计划见 plan 2026-06-18-001。

四类工作负载映射：

工作负载	主力	形态
游戏生成主线（MVP 关键）	SAA 裸图	编排为主 + repair 节点
五资产生成（美术/音乐等）	SAA Sequential / Parallel Agent	工具/模型调用流水
Tier-3 多 agent 开发组（远期·高阶层）	AgentScope asNode() 嵌入	开放式自治，外层图卡预算与门
mode-C 用户编排（远期单列）	SAA Admin（前端形态待定）	可视化工作流面

基建按消费者驱动分期：MVP 期零新中间件（仅 MySQL+Redis）；Nacos / RocketMQ / Sentinel = future-state，待真实首个消费者（Tier-3 自治组 ∧ MVP 闭环已上线）才上，不预铺控制面。

---

3. 六条不变量（硬约束，任何阶段不破）

1. 单一 new-api 成本/凭证层：模型 key 与用量计费只有一处权威（new-api + newapi_cost），SAA/AgentScope 都读它。
2. "done" 由确定性门裁定：九门真玩 harness 是验收唯一权威，禁止 LLM 自评（反 Goodhart）。
3. 写工具幂等：幂等键 = sessionId+step（worker 侧 = traceId）；循环/重试不得产生重复副作用或重复计费。
4. 成本/迭代上限：每次生成有 max-iters 与 max-cost-per-run 天花板。
5. 框架可换：生成逻辑藏在 job/callback 契约之后，换框架不改业务契约。
6. 日历优先：完成 MVP 的约束是 ICP/支付/广告日历闸门，本平台线在其下，必须时间盒、不得拖垮 MVP 闭环。

---

4. 落地接入要点（指针为主，细节指向 skill）

• 依赖集：只引 3 BOM（spring-ai-bom:1.1.2 + spring-ai-alibaba-bom:1.1.2.2 + -extensions-bom:1.1.2.2）+ spring-ai-alibaba-graph-core + spring-ai-openai。别引 SAA 的 Boot BOM（让项目 3.5.14 胜出，避 3.5.8 冲突）、别引 RedisSaver（避 Redisson 3.x↔4.x）、别引 agent-framework/builtin-nodes。只加到 game-module-aigc-server/pom.xml，不动根 POM。
• 模型：每节点一个 OpenAiChatModel bean，共用一个 OpenAiApi，仅 defaultOptions.model 不同，节点按 @Qualifier 取；baseUrl 指 new-api（须 stripV1）。
• checkpoint：MysqlSaver 作唯一权威 saver（一张图只能注册一个）+ RunnableConfig.threadId(traceId) + releaseThread(false) 才能长期续跑。坑：saved_at 无 tiebreaker → 续跑须显式传 checkPointId。
• reactive↔blocking：invoke() 自带阻塞（内部 .block()）→ 必在后台线程池跑（禁 Tomcat/Reactor 线程），图执行不包大事务，跑完单独短事务落库。
• 生产派发：GenerationDispatcher 接口（http worker | SaaGraphDispatcher 进程内灰度切，默认 http 非破坏）。落地实现 = SaaStudioGraph.java（唯一布线源）/ SaaGraphDispatcher.java。

深落地与全部坑（HumanNode 已废 / 无 streamEvents / supervisor 未实现 / Semaphore(1) 串行守端口 4320·9222 等）→ .agents/skills/saa-graph-orchestration.md，不在此重复；API 逐键源码证据见 dossier（API 速查 / 能力矩阵 / 接入部署 / 用法范式）。

---

5. 两条治理铁律（split-brain 防线）

1. 「worker succeeded ≠ 准予发布」：SAA worker 出口只产『机制可玩』（过九门 = succeeded），发布裁决（跨创意查重 / 对抗 P0 合规 / 金丝雀）归 batch 治理层或 W-G1 落库门 + GP9。saa 切生产前硬前置：worker 无对抗 P0 安全门，须 GP9 接管（否则 saa 路生成的游戏无合规二审即入 feed）；查重平移 D9 落库门须继承 orchestrator _dedup_gate 的 title/theme NFKC+casefold 归一化口径，防语义漂移。
2. 「多派发路·回调可观测字段每路都 set」：trace_json/readiness_score 若只在部分回调构造点 set，换 dispatcher 即静默丢字段（SAA 进程内路曾恒 NULL，组B 9d/D11/D9 在 SAA 路静默失效）。修法 = 派发器回调点字节兼容镜像 worker _extract_trace 抽 camelCase 子集 setTrace（snake→camel 命门：stage_fail→stageFail 等；SAA attempt 本无 guards/sevenGatePass 不伪造；additive + best-effort + 复用 aigc.trace.enabled 开关）。已闭合：703e462c 真库验证——task141 trace_json 非空 / readiness=74；task145 开关关 trace_json NULL（字节零变）；进程内非 HTTP 非 HMAC。

---

6. 与 agent-loop-v1 编排器的边界（继任关系）

SAA 继任的是 per-job worker 躯体（Python wg1/gen-worker 的 design→九门→player），不是 agent-loop-v1/orchestrator 的 batch 治理外壳（跨创意查重 / JSONL 账本幂等重放 / 八项预算闸 / 四条熔断 / 发布段金丝雀 / 换模型抽检）——两者职责不重叠。

退役分两段：

• A 段（worker 冻结，近期可执行）：form① e2e 通过 ∧ 对比测试确认 SAA 不残废 → 冻结 Python wg1/gen-worker 作对比基线。
• B 段（batch 治理层退役，须等替身）：须 W-G1 替身全部就位——D12 控制平面 v0 + 落库组（9d trace / D11 就绪分 / D9 反同质化）+ GP9 合规门 + 「成批驱动 dispatcher=saa 并裁决发布」的新 batch 入口 → run_batch.py/judge.py/ledger.py 整体退役（移 _archive 或迁 tools/ 后冻结）。

红线：B 段四条未全绿前，严禁删 orchestrator——它是当前唯一可用的「批跑 + 真玩取证 + 发布裁决」工具（merge-prod-20 / batch-002b 实证），被 11 处活资产引用。judge D1/D2/D7/D9 核心判据（runnableOk=九门）已以契约迁入 worker；ledger 幂等/续跑直接退役（SAA traceId+checkpoint+watchdog 全覆盖且更强）；预算闸 per-job 项已迁、跨批项留治理层。

---

7. 现状清单（done / 在飞 / 待办 follow-up）

done：

• 迁移 spike 全链跑通（首款 breakout 九门 9/9）+ 对比首轮 SAA 平手或更优。
• form① e2e 真库通过（隔离实例 dispatcher=saa，进程内九门→handleCallback→入 feed）。
• trace split-brain 真库闭合（703e462c + a09a03e9；round3 verdict）。
• 依赖/编译/checkpoint 真恢复门全绿（门 A–F）。
• 16 节点 studio 全图已建并合入 dev/2.0.0（固定架构图 5 新节点 classify/asset/modify/escalate/nreview + 救场阶梯 + 8 契约冻结）；真全图 e2e 首证 SaaFullGraphE2eTest（现 iife 路成功率 60%、零 prod bug，U7 cutover 按门未切）。
• 真结构化地基双证成立（2026-06-18）：① spike=便宜模型对 source-project.schema.json 产连贯 gameDefinition 92-100%（¥0.011/款，behaviors 带真逻辑 JS）；② build 段=gameDefinition→build-from-source→真浏览器过九门（deepseek-v4-flash 满分、便宜模型 3/4 款过门，截图实证）。"改源不改包 / 可维护源项目 / LLM as 工作室" 代码级成立；产出 运行时访问约定 v0（rt 对象：getEntity/spawn/input/time-random 受控/score-win-lose latch/fx 真调引擎=满 F 门）+ build-from-source 装配 PoC。

在飞（本 session 独家开发）：

• gameDefinition 真结构化 studio 产线化（plan docs/plans/2026-06-18-001 U1-U4,已合 dev/2.0.0）：U1 运行时约定 2D 适配器契约 / U2 build-from-source 产线化 / U3 generate 真产 gameDefinition / U4 模型可靠性兜底。（原 U5 ReAct 演进=接法B，2026-06-18 移出 001 → 归本轨，见下。）
• 接法B（ReAct 自治 loop）= 演进方向 = P2 / Phase-1.5 agent-native 轨：给 generate/repair 装真 tools 长成 ReactAgent（写源/build/跑九门/读错/改 config-asset）；九门兜底化解铁律张力——自治在门内、裁决在门外（review §10.5 已留口）。先接法A（已建七成、躯干）稳地基，后接法B 增量演进、不返工。
  • ★归位（创始人 2026-06-18）：原 plan 001 的 U5「ReAct 演进」已移出 001 → 归本轨（延期任务不算 001；001 = U1-U4）。003（P1 串行线）退路作 contingency 引用——升档 + prompt/gatespec 修（remaining 语义/asset/c4）不达 80% 才升级到 ReAct。U5 原设计正文（ReactAgent.asNode/tools 包装/ToolCallLimitHook/依赖坑 SAA-Boot 版本/便宜模型 tool-use 待实测）见 001 git 历史 + saa-agentic-infra-decision。
• W-G1 开闸验收门（与上并行）。

待办 follow-up：

• F3 = SAA cost 折¥（v0 只落 tokens、cost 整段省略，token≠¥；现 efficiency 取中性 0.5）。
• F5 = 组B ReadinessScorer.scoreFirstPlay 把嵌套 H_progress 喂 asBool 恒 false 的既存 bug（HTTP/SAA 同病，firstPlay 永卡 0.5），另立票改读 guards.H_progress.pass，本线不动（改会破字节兼容）。
• F1 = 路③ AigcGenerateExecutor 旧进程内路薄轨迹（旧四模板已清除 W-CLEAN，当前不活跃）；F2 = SAA 路接 D9 去重（独立 spec）。
• 早期 boot SAA fast-fail 冷启预热（首 2~3 个 dispatch 瞬态 fail，第 4 个起稳态；建议 dispatch 加预热/重试）。
• 对比 VERDICT 固化 tech-decisions §4（待扩对比样本量）。

readiness 真值随真跑质量浮动：repairs=5 → stability 降、cost 缺 → efficiency 中性，故 readiness=74 低于 HTTP 路 96——是真值反映，非缺陷。