games-development-ai/docs/agent-specs/2026-06-15-SAA-AgentScope-agent平台-目标架构-review.md

SAA + AgentScope Agent 平台 · 目标架构（评审版）

决策 ID：HJ-AGI-002（演进自 HJ-AGI-001「agentic 基建 = AgentScope」） 日期：2026-06-15 · 状态：评审版 v2（已过 Codex + Opus 双评审，见 §10） · 双评审 verdict = 需重议 → 已修订为「带修改采纳」 · 两项前置决策待创始人拍板（见 §10-决策 D1/D2） 适用范围：game-cloud agentic 编排基建的生产目标架构 + 分期落地路径 关联：[.agents/knowledge/tech-decisions.md]、docs/agent-specs/2026-06-12-agentic基建框架选型-review.md、本轮 spike 执行稿（2026-06-15-SAA-AgentScope-spike-execution.md，定稿后产出）

---

0. 结论先行（给决策）

1. 主干 = Spring AI Alibaba（SAA，v1.1.2.2 稳定/GA）的 Graph 编排。自治节点用 SAA 自带的 ReactAgent（tool+Hook+HITL+中断恢复，已测 OpenAI/DeepSeek）经 ReactAgent.asNode() 入图；子 agent 调用用 FlowAgent.subAgents/子图（SubGraphNode）——均 SAA 原生。生产默认 SAA-only、养一个框架（2026-06-15 源码实证，见 §10-D2）。AgentScope 嵌入降为"未来若 SAA ReactAgent 不够再议"；对 agentscope 的开源贡献作独立轨道、与生产解耦。
2. 本项目绝大多数 agentic 活是"编排型"（生成主线 / 五资产 / 远期 mode-C），只有少数"自治型"（Tier-3 多 agent 开发组）才下沉成嵌入式 AgentScope 节点。
3. 基建按消费者驱动分期上：Phase1 只用已部署的 MySQL + Redis（零新中间件） → Phase2 拓扑成型时上 Nacos/A2A/RocketMQ/Sentinel → Phase3 mode-C 可视化面。
4. 落地顺序：先 lili-mac spike 验 SAA（kill-criteria 见 §7）；MVP 闭环期间继续跑现有执行器、互不干扰；spike 通过且不压日历闸门，再迁生成主线。
5. 不变量（§6）：共用 new-api 单一成本/凭证层；"done"由确定性门（九门真玩）裁定、不让 LLM 自评；写工具幂等；生成逻辑藏在 job 契约后（框架可换）；完成 MVP 的约束是日历闸门，平台建设不得拖垮 MVP 闭环。

---

1. 背景与触发

• 起于"是否对用户开放 agent 编排"的讨论，逐步收敛到 agentic 基建的 Java 化 + 编排框架选型。
• 期间核实并纠正了外部建议的四处误判（见 §9），所有关键结论均有据（仓内取证 + 联网核实 + 已 clone 源码到 /root/oss/）。
• 现状（已核实）：
  • 生成主线 = game-module-aigc 内 AigcGenerateExecutor + 自研薄客户端 ExecutorLlmClient → new-api（硬编码 7 步，无图/DSL 编排）。
  • 另有隔离 Python worker（L1 裸路 + L2 Python AgentScope 2.0.1，编排均手写）。
  • staging 实际只跑 redis:7 + mysql:8.4.8；Nacos/RocketMQ/Sentinel/Seata/Gateway/XXL-Job 未部署。

---

2. 目标 / 非目标

目标

• 用真正的图/DSL 编排取代硬编码生成流程，且可观测、可 checkpoint / 失败恢复。
• 选定面向生产云拓扑（Spring Cloud Alibaba）的 agentic 主干框架，Java 原生、消除 Python↔Java 跨进程缝。
• 为远期 Tier-3 自治开发组、mode-C 用户编排预留生长路径——无孤儿设计（每能力带入口/失败路/验收）。

非目标（本轮明确不做）

• 不现在搭微服务舰队、不预先部署 Nacos/RocketMQ/Sentinel/Seata。
• 不把 MVP 闭环切换到新框架（先并行 spike，证后再迁）。
• 不决定 mode-C 的 C 端编排前端形态（远期单列）。
• 不使用 Dify（项目已降级、无存量工作流，DSL 导入对我们 moot）。

---

3. 推荐方案

3.1 架构：全局可控、局部自治

flowchart LR
  subgraph GC[game-cloud（Spring Boot 单体 / 未来微服务）]
    EXE[现有 AigcGenerateExecutor\n（MVP 闭环保留, 不动）]
    JOB[job/callback 契约\n（稳定接缝, 框架可换）]
  end

  subgraph SAA[SAA Graph 编排主干 · GA v1.1.2.2]
    direction TB
    N1[render prompt] --> N2[LLM 生成 GameConfig]
    N2 --> N3{schema 校验}
    N3 -- 不合法 --> NR
    N3 -- 合法 --> N4[scaffold 脚手架]
    N4 --> N5[build 工具节点]
    N5 --> N6[play 工具节点\n九门真玩]
    N6 -- 门失败 --> NR
    N6 -- 门通过 --> N7[emit]
    NR["repair 节点\n（可升级为 AgentScopeAgent.asNode<br/>= 嵌入式自治体）"] --> N2
  end

  subgraph EXT[复用：既有确定性 harness（子进程工具）]
    BUILD[esbuild/node 构建脚本]
    PLAY[CDP 九门真玩 harness]
  end

  subgraph STORE[已部署存储（Phase1 零新基建）]
    MY[(MySQL)]
    RD[(Redis)]
  end

  JOB --> SAA
  N5 -. shell .-> BUILD
  N6 -. shell .-> PLAY
  SAA -. Graph state checkpoint .-> MY
  SAA -. session/短期记忆 .-> RD

要点：

• 确定性门（九门）= 图的条件边，由 harness 真玩裁定"done"，不让 LLM 自评（反 Goodhart）。
• build/play 复用既有 harness（子进程工具节点），零重写；generate/validate/scaffold 进入 SAA 图。
• repair 节点起步是受约束的 LLM 节点；需要开放式修复时升级为 AgentScopeAgent.asNode() 的嵌入自治体——这是 hybrid 的落点。

3.2 四类工作负载映射

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

3.3 为什么主干是 SAA（而非 AgentScope-java 或纯自研）

• SAA v1.1.2.x 是 GA；agentscope-java 2.0 仅 RC → 生产主干用 GA 的 SAA，把 RC 风险**关进"可选的嵌入节点"**而非主干。
• SAA Graph 状态可 checkpoint 到 MySQL/Redis/PostgreSQL/Oracle/MongoDB/File——其中 MySQL+Redis 我们已在跑，Phase1 零新基建。
• Spring-native，贴 game-cloud（Spring Boot）与生产 Spring Cloud Alibaba 目标；Nacos/A2A/MCP 原生，待 Phase2 自然接入。
• SAA 提供 AgentScopeAgent.asNode()（在 SAA 的 spring-ai-alibaba-starter-agentscope 模块）把 AgentScope 的 ReActAgent 嵌进 SAA 图。⚠️双评审源码证伪：该官方接缝当前绑定 agentscope-core 1.0.9（稳定线），既非 agentscope-runtime-java、也非 2.0；且只代理单个 ReActAgent，不直接适配 §3.2 的 Tier-3 多 agent 自治组。把 2.0(-SNAPSHOT) 嵌进去属未经官方验证的路径——见 §10，hybrid 降为独立后置 spike（Phase 1.5），不与主干同批。

3.4 分期落地（消费者驱动，不预铺控制面）

flowchart LR
  P1[Phase1 · MVP 期\n零新基建] --> P2[Phase2 · 生产拓扑成型] --> P3[Phase3 · mode-C]
  P1 -.- P1d["SAA 图编排生成主线<br/>state 仅 MySQL+Redis<br/>挂 job 契约后<br/>共用 new-api 成本层"]
  P2 -.- P2d["部署 Nacos→A2A+MCP-registry+发现<br/>嵌 AgentScope 跑 Tier-3 自治组<br/>RocketMQ 事件触发 · Sentinel 限流"]
  P3 -.- P3d["SAA Admin 可视化面<br/>C 端编排前端形态另定"]

---

4. 关键取舍

• 引入 Spring AI + SAA 依赖（本仓今天零 spring-ai）——成本有界，且与生产栈同向；收益是 GA 编排 + 持久化 + 生态。
• 单看 MVP 生成流，上图框架是轻度过度设计；真正理由是生产拓扑 + mode-C + 可恢复性这条轨迹。→ 用"藏在 job 契约后、先 spike、不压日历"三条控制其代价。
• reactive↔blocking 边界：SAA / AgentScope 近期都转向 Flux 响应式核心（程度待 spike 实证）——保持"独立 worker / job 契约"边界，规避在全阻塞的 Spring MVC 舰队里硬塞响应式岛。

---

5. 影响面 / 兼容性 / 风险

• 影响面：新增 agentic 编排栈；game-cloud 增 Spring AI/SAA 依赖；生成逻辑迁移（藏契约后）。MVP 闭环不动（保留现有执行器）。
• 风险与缓解：
  1. SAA 学习曲线 / 响应式核心 → spike 先证小流；保持边界。
  2. agentscope-java 2.0 RC 稳定性 → 限定在可选嵌入节点，主干用 GA。
  3. Spring AI 栈引入成本 → 与生产 Spring Cloud Alibaba 同向，非沉没。
  4. 日历风险（平台建设挤占 MVP）→ 不变量第 5 条 + 分期 + 时间盒。
• 回滚：spike 任一 kill-criterion 挂 → 回落现有 Java 执行器 + 已 spike 的 Python worker（两者都在跑），零损失。

---

6. 不变量（硬约束，任何阶段不破）

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

---

7. 验收标准（= lili-mac spike 的 kill-criteria）

门	判据
A 模型	SAA ChatModel 指向 new-api（OpenAI 兼容）+ 便宜模型可调通出 JSON
B 持久化	图状态仅靠 MySQL+Redis checkpoint/恢复，零新中间件
C 接缝	图节点能 shell 调既有 build + 九门 harness 并读回 JSON
D 真玩	跑通一款金样游戏端到端真玩（four-piece 证据，见 game-e2e-cdp-harness）
E hybrid	AgentScopeAgent.asNode() 嵌一个自治修复节点跑通，验证 SAA↔AgentScope 接缝

红线：权威真玩门必须在 mini-desktop（x86） 复跑后才能下生产结论；lili-mac（ARM）只作快迭代证据。

---

8. 待确认项（创始人拍板）

1. MVP 闭环是否上线前迁 SAA，还是上线后？（建议：上线后，先并行 spike）
2. Nacos 部署时机？（建议：Tier-3/A2A 真正启动时，不预铺）
3. mode-C 的 C 端编排前端形态（远期单列，本轮不决）。
4. agentscope-java 贡献：提供 GitHub 账号以便设 fork remote（fork→分支→PR）。

---

9. 附：已核实事实 & 已纠正误判（自包含，防止重蹈）

已核实

• SAA：GA，最新稳定 v1.1.2.2（已 clone /root/oss/spring-ai-alibaba，POM <revision>1.1.2.2）；Graph runtime；内置 Sequential/Parallel/Routing/Loop Agent；持久化 MySQL/Redis/PG/Oracle/Mongo/File；Admin 可视化 + Dify DSL 导入；A2A-over-Nacos；JDK17。
• agentscope-java：稳定线 1.0.12；本地 clone 的 main HEAD <revision> 实为 2.0.0-SNAPSHOT（非 RC，比 RC 更易漂移）。agentscope-harness 是 agent 工作区/文件系统基建（≠ 本项目"九门真玩"确定性验收 harness，二者无复用关系，防误读）。AgentScopeAgent.asNode() 不在 agentscope-runtime-java，而在 SAA 的 spring-ai-alibaba-starter-agentscope，绑 agentscope-core 1.0.9（双评审证伪原稿表述）。

已纠正误判（外部建议）

1. AgentScope Java 2.0 非 GA（曾被误称已 GA）。
2. 本 fork 无 yudao-module-ai、零 spring-ai 依赖（曾被误称已存在）→ SAA 是新引入而非扩展。
3. SAA README 未"叫你改用 AgentScope"；SAA 自身横跨 agentic+workflow，AgentScope 作为可嵌节点。
4. Dify DSL 导入对本项目 moot（无存量工作流）。

---

10. 双评审结论与 v2 修订（2026-06-15 · Codex + Opus）

双评审 verdict：两方独立均判「需重议」（非照单采纳）。评审在我提供的 /root/oss clone 源码上验出一处承重事实错误 + 一道缺失门 + 两记战略挑战。据此修订，文档状态降为「带修改采纳」，并上浮两项创始人前置决策。

P0（已接受，必改）

• P0-1 asNode 事实错误（源码证伪）：asNode() 在 SAA spring-ai-alibaba-starter-agentscope，绑 agentscope-core 1.0.9，且只代理单个 ReActAgent；本地 agentscope-java 是 2.0.0-SNAPSHOT（非 RC）。→ §3.3/§9 已就地更正；"hybrid 是官方集成层不是拼凑"的定性收回——把 2.0 嵌进 1.0.9 接缝是未验证路径。
• P0-2 缺依赖启动门：SAA 1.1.2.2 ⇒ Spring AI 1.1.2 + Boot 3.5.8；本项目 Boot 3.5.9/3.5.14 + SCA 2025.0.0.0、零 spring-ai。功能 demo 过 ≠ 在 game-cloud 依赖树能起。→ 新增门 F。
• P0-3（战略）图编排是否过度设计：实测执行器确为「线性 + 1 次重试」，图的分支/并行/checkpoint 核心价值当前几无消费者；现执行器已有完整失败恢复（CAS 认领+watchdog+幂等回调+预算墙）。迁移理由实为押注「mode-C + 生产微服务拓扑」两个未来时。→ 上浮为决策 D1。

P1（已接受，含一处我的校正）

• 基线选错：正确对照不是「硬编码执行器 vs SAA 图」，而是「已 spike 的 Python AgentScope worker 演进 vs Java SAA hybrid」。→ spike 增对照臂。【校正】Python worker 是正确对照基线且已 spike，但 Opus"已在产派发面"属高估——本轮早先取证 workerUrl 默认空、dispatchGeneric 未配置即判 failed，其当前是否真接线随配置而定，对照臂须先确认其现状。
• hybrid 隐藏复杂度：agentscope-core 2.0 深度响应式（72 文件引 reactor），asNode 内含 block() 时序坑；叠进阻塞单体=养「两套半」。→ E 门判据升级为「失败路径可控可观测」，且 hybrid 拆出主干。
• repair 自治节点孤儿：升级为自治体缺失败/回滚/预算归属路。→ Phase1 repair 仅保留受约束 LLM 节点；自治化延到 Phase1.5 且须补三件套（失败路+预算归属+与九门交互）。

v2 修订（已并入方案）

1. spike 拆相：Phase 1 = 纯 SAA 图主干（无 asNode），过门 A/B/C/D + 新 F；Phase 1.5 = hybrid（asNode），先解版本归属（D2），E 门记录 reactive↔blocking 失败模式；hybrid 不阻塞主干。
2. 新增门 F（依赖/启动）：game-cloud 实引 SAA BOM/starter，跑 mvn dependency:tree + 最小 ApplicationContext 启动 + huijing-server 编译门；明确哪个 BOM 管 Boot 版本（3.5.8 vs 3.5.9/3.5.14）。
3. 门 A/B 细化：A 加「JSON schema 输出」实测；B 改为「同 MySQL 8.4.8 + Redis 7，崩溃后按 threadId 恢复到正确节点」的真恢复实测（不止类存在）。
4. 对照臂：同款金样，「Python worker 演进」vs「SAA hybrid」同口径比工时/稳定性/运维；hybrid 不显著胜出 → 不迁移为默认。
5. §6 软控制 → 硬闸门：① spike 绝对时间盒（超时按 kill 处理）；② MVP 闭环（ICP/支付/广告链路）未交付前禁碰任何 Phase2 基建，违反等同破不变量；③ 给「是否压日历」可观测判据（关键路径 battle 是否因平台线滑期）。
6. §3.4 触发可证伪化：Phase2 触发 = "Tier-3 自治组有真实首个消费者 ∧ MVP 闭环已上线"；Phase3 同理给客观事件。
7. §5 回滚措辞：Phase1 低成本可逆；Phase2 起基建可逆性显著下降（非"零损失"）。
8. reactive 边界：长图一律走 job/worker 边界 + 后台线程池；线程池/超时/取消/checkpoint 恢复纳入验收。

评审肯定（避免过度否定）：SAA 的 Graph/Node/Edge、MysqlSaver/RedisSaver、Sequential/Parallel/Routing/Loop、ChatModel 自定义 baseUrl 接 new-api——均源码证实成立；job/callback 契约=框架可换+回滚路是全稿最硬的一块。

上浮创始人前置决策

• D1（战略，本质商业判断）：迁移理由是押注 mode-C + 生产拓扑。①spike-to-decide（Phase1 纯 SAA + 对照臂，时间盒，结果说话——推荐）/ ②defer（MVP 先用现路，待真消费者再上 SAA）/ ③直接 commit。
• D2（版本归属）→【2026-06-15 创始人追问后源码实证解决】：SAA 自带完整 agentic——ReactAgent（tool+Hook+HITL+中断恢复，已测 OpenAI/DeepSeek，spring-ai-alibaba-agent-framework/.../ReactAgent.java）+ ReactAgent.asNode()（第296行）+ FlowAgent.subAgents（List<Agent>）+ 子图 SubGraphNode。子 agent 调用是 SAA 原生能力，不需 AgentScope。→ 改判：生产 = SAA-only（养一个框架、回归 HJ-AGI-001 初衷、P0-1 版本错配消失）；AgentScope 嵌入降为"未来 SAA ReactAgent 不够时再议"；agentscope 开源贡献=独立轨道。唯一待确认：是否仍要在生产里 dogfood AgentScope 作为贡献载体（默认否=SAA-only）。