games-development-ai/docs/architecture/架构/生成引擎/agentic运行时架构图说.md

tier2 agentic 运行时架构图说

🚧 评审版 · 9 张图（6 svg + 3 mermaid）· 已纳入创始人 4 问校正（见 §5）。 这是什么：tier2 自治富游戏生成轨——agentic 这条线的「看图入口」。把「编排 → 启动 → 调用 → 运行时 → 返回结果」整条生命周期、它在系统里的位置、内部怎么转，用一套图讲清。复杂重要的用 svg/png 高保真大图，简单的用 mermaid。颗粒度面向 vibecoding。 给谁看：判断「整个 agentic 架构是不是想要的那个」的创始人；照图实现的工程师 / vibecoding 的人。

---

0. 阅读约定与同步纪律

• 映射的设计档：本图说不另立设计，只把《自治富游戏引擎》《tier2 四层工程架构》《tier2 实现详设》《agentic 集成架构》画出来。运行时机制以 agentscope 2.0.3 源码实证为准（/root/oss/agentscope，逐条核过）。
• 同步纪律（创始人要求）：设计一变动，本图说与对应 svg 必须同步更新，图脚注注明版本。已并入 wave 收口清单。
• 产物形式：svg 入仓（GitHub/编辑器直接渲染矢量），png 在 mini-desktop 转（6c6g 禁 chrome、无转换器）。

1. 全图通用图例

生产维度（大厂生产环境关心）：安全（Workspace 隔离/密钥/产物消毒）、可观测（Event System → OTel → Studio）、可靠（四熔断/checkpoint/HITL/durable/fallback）、成本（预算软刹+硬杀/quota 台账）、数据（AgentState/落库/哈希）、伸缩（多实例/多租户/会话隔离）、质量（三层校验）。

复用边界（二维 · 见图 6）：来源（官方现成 vs 自建）× 共享范围（两线公共 vs tier2 私有）。⚠️「公共组件」是自建的共享件、不是现成的。

2. 图集

图 A · 生成两阶段（工作室设计 → 单写实现）

整个生成是两阶段。阶段 1 是游戏工作室——用 AgentScope 的 Agent Team（星形）：一个 leader agent 分析并拆解用户意图，spawn 出玩法/关卡/数值机制/UI/音乐音效/特效/资产等多个专业设计 worker 并行发散（基于玩法模板 prompt + 工程初始化模板），结果经 TeamSay 汇回 leader（worker 之间不互连），leader 收敛成一份结构化设计（GDD + 各维度设计 + 工程骨架）。阶段 2 是单写实现——把这份设计交给单写 agent，它在 ReAct 循环里独自把代码写出来（运行时内部见图 3）、过三层校验、产出结构化游戏源项目。设计用多 agent 是因为各专业发散、不共享代码状态；实现用单写是因为多系统共享同一套代码与约定，并行写几乎必然不一致（曾把 Flappy 拆并行写，背景跑成了马里奥）。

图 1 · 系统全景 / 部署

tier2 agentic 是独立 service，game-cloud 经官方 Agent Service 的 REST + SSE 调它；它经 new-api（统一出口、协议不锁）调模型，用 Workspace（Local/Docker/E2B）干活，把会话/产物落到 Redis/MySQL/OSS，trace 导出 Studio。它与 SAA 廉价线运行期零耦合，两线只在「计费/送审/feed/验收基线」这些公共组件上交汇。

图 2 · 调用时序（cloud ↔ agentic）

tier2 不自造 API，直接用官方 Agent Service：POST /sessions 建 durable 会话并触发 run，GET /sessions/{id}/events 订阅 SSE。运行时每步（thinking/tool/result）作为 Event 经 SSE 流式推 cloud，断线重连可 replay 缓冲。中途可 HITL（确认/编辑工具参数）再精确恢复，也可取消。产物落库后回完成 event（verdict + 产物引用）。

图 3 · 运行时内部架构（AgentScope 真实对象结构）

这张按 AgentScope 真实对象结构画（纠正了上一版把 environment 当「被调用的旁边数据面」的错）。核心是 Agent——一个无状态 ReAct 引擎，它通过构造参数持有 model（M3）/toolkit/middlewares/state（AgentState）等。Workspace 是 Agent 的执行环境，但它沿两条轴「注入」Agent：① 它的工具/MCP/skills 被 get_toolkit 装进 Toolkit 给 Agent；② 它本身作为 offloader（管 context 卸载）给 Agent。所以 Agent 持有 Workspace 引用，不是嵌在 Workspace 里；真正「跑在 Workspace 里」的是 MCP 进程、skills、卸载文件。还有一条关键的生产事实：Agent 实例非常驻——Agent Service 每次 run 现组装一个 Agent、跑完即弃，一切可变态都在可持久化的 AgentState（落 Redis），所以天然可中断、可恢复、可水平扩。验收是三层（见下）。而「四层（environment/harness/context/prompt）」只是职责视角，叠在这个真实结构上，不是并列模块。

图 4 · 单写者 ReAct 循环流程（一轮迭代）

把图 3 中心那个循环展开成一轮：组装 context → reason 调 M3 → 判断「调工具还是收尾」→ 调工具就去 Workspace 写码/构建/真跑、CDP 取证、过三层校验，没过回 repair。模型产纯文本即收尾、出产物。右侧四熔断任一触发即优雅收尾，每轮 checkpoint。

图 5 · 编排与配置结构

「编排」= 写一次代码骨架（create_app + 组装 Agent 的 model/toolkit/middleware/memory/react_config），「配置」= 三类外置（机制硬代码、安全/构建走版本化审计、策略热改不发版）。

flowchart TB
  APP["create_app(FastAPI)<br/>REST + SSE · 多租户 · durable"]
  subgraph 编排["编排（代码骨架 · 建一次）"]
    AG["Agent"]
    AG --> M["model：AnthropicChatModel(M3)"]
    AG --> TK["toolkit：Workspace 工具 + CDP 探针"]
    AG --> MW["middlewares：预算软刹(官方) + 超时/卡死/硬杀(自建)"]
    AG --> MEM["memory：ReMe / AgentState.context"]
    AG --> RC["react_config：max_iters"]
  end
  subgraph 配置["配置外置（三类）"]
    H["硬代码·机制<br/>门断言 / 熔断 / 权限上限"]
    V["版本化·审计<br/>依赖锁 / 引擎版本 / 构建 profile / 沙箱类型"]
    HOT["热配置·策略<br/>prompt / 模型路由 / 阈值 / RAG 源"]
  end
  APP --> AG
  HOT -. 改配置不发版 .-> AG

图 6 · 复用边界（来源 × 共享范围）

两个维度：来源（官方现成 vs 自建）× 共享范围（两线公共 vs tier2 私有）。左列是 AgentScope 官方现成（列全，十几组：Event/Agent/Model/Context/Tool/MCP/Permission/Middleware/Workspace/State/Agent Service/Agent Team/Embedding/Formatter/Skill），直接用、不算 tier2 资产。右上是自建的两线公共件（九门/三层校验/CDP 探针/计费/送审/feed/trace 契约）——它们是自建的、只是两线共享，不是现成的。右下是 tier2 私有自建（通用治理 6 项 + 游戏专属 2 项）。还标了「官方没有」（无 RAG/无 evaluate/A2A 仅基座）和「该删」（token 计量/软预算/结构化调用/OTel/经验召回/多 agent 总线——都改用官方），把自研面缩到最小。

图 7 · 产物与契约

返回的是结构化源项目（改源不改包、重新构建），由源项目契约钉住文件树/构建/依赖/落库；过程由 trace 契约记录。

flowchart TB
  subgraph SP["tier2 源项目契约（落库取回）"]
    direction LR
    ID["类型标记"] --- TREE["文件树 manifest<br/>+ 入口文件"] --- BUILD["构建 profile<br/>+ 依赖锁"] --- HASH["内容哈希"] --- DBAPI["落库 / 寻址<br/>MySQL + OSS"]
  end
  subgraph TR["trace 契约（可观测）"]
    direction LR
    CORE["公共核心子集<br/>traceId / step / cost / verdict / ts"] --- EXT["扩展段 JSON<br/>tier2：推理 / 动作 / 观察"]
  end
  SP -.->|改源不改包·重新构建·长生命周期| OUT["可维护的 Phaser 源工程"]

图 8 · 关键类图

classDiagram
  class Agent { +reply() +react_config +middlewares }
  class ReActConfig { +max_iters }
  class Toolkit { +register_tool_function() }
  class MiddlewareBase { +on_reasoning() +on_model_call() }
  class ReplyBudgetControlMiddleware
  class TimeoutMiddleware
  class StuckDetectMiddleware
  class AnthropicChatModel { +thinking_enable +credential.base_url }
  class AgentState { +cur_iter +context }
  class WorkspaceBase
  Agent --> ReActConfig
  Agent --> Toolkit
  Agent --> MiddlewareBase
  Agent --> AnthropicChatModel
  Agent --> AgentState
  Agent ..> WorkspaceBase : offloader（轴②）
  WorkspaceBase ..> Toolkit : 资源注入（轴①）
  MiddlewareBase <|-- ReplyBudgetControlMiddleware
  MiddlewareBase <|-- TimeoutMiddleware
  MiddlewareBase <|-- StuckDetectMiddleware
  WorkspaceBase <|-- LocalWorkspace
  WorkspaceBase <|-- DockerWorkspace
  WorkspaceBase <|-- E2BWorkspace
  note for Agent "无状态引擎 · 每 run 现组装（非常驻）· 状态全在 AgentState"
  note for TimeoutMiddleware "自建"
  note for StuckDetectMiddleware "自建"

3. 图清单与状态

#	图	形式	状态
A	生成两阶段（工作室→单写）	svg	✅ 新增
1	系统全景 / 部署	svg	✅
2	调用时序（cloud↔agentic）	svg	✅
3	运行时内部（真实对象结构）	svg	✅ 重画
4	单写 ReAct 循环流程	svg	✅
5	编排与配置	mermaid	✅
6	reuse 边界（二维）	svg	✅ 重做
7	产物与契约	mermaid	✅
8	关键类图	mermaid	✅

4. 三层校验（创始人定义）

层	内容	处置	工具包
L1 硬约束	编译报错 / 启动报错 / 运行错误日志	必须解决 · 循环	确定性：构建日志 / console error / CDP 错误捕获（九门多数落此）
L2 设计符合	玩法/关卡实现 vs 最新设计、UI 缺组件	尽量解决	设计符合度校验（部分九门：机制进展）
L3 效果	特效 / 画面美观 / 好不好玩	只评分不解决	M3 视觉软检（绝不阻塞、绝不拒发）

迭代原则：初期只识别硬问题（L1），L2/L3 渐进完善；绝不让效果问题阻塞真问题；用户可经 HITL 发消息要求继续解决任意层。

5. 关键校正记录（创始人 4 问 · 2026-06-22）

1. 补两阶段：原图只画了单写 agent；补「工作室多 agent 设计（Agent Team 星形）→ 单写实现」两阶段（图 A）。单写约束只管「写代码」那步。
2. environment 嵌套纠错：environment = Workspace 是 Agent 的执行环境，沿两轴（资源→Toolkit / offloader）注入 Agent；Agent 持有引用、非嵌套；Agent 实例非常驻（图 3 重画）。
3. 验收改三层：L1 必须 / L2 尽量 / L3 只评分，不同工具包，初期只做 L1（§4、图 3/4）。
4. 复用边界二维：来源 × 共享范围；官方能力列全；自建严格核对（该删的改用官方）；公共组件 = 自建 ∩ 共享（图 6）。

6. 术语映射（图里词 → AgentScope 2.0 官方）

图里词	AgentScope 2.0 官方
environment / 沙箱工作站	Workspace（LocalWorkspace / DockerWorkspace / E2BWorkspace），经 Toolkit + offloader 双轴接入 Agent
API / Session 层	Agent Service（REST + SSE，/sessions 等；Agent 非常驻）
可观测	Event System（typed stream）→ TracingMiddleware → Studio
熔断	Middleware 洋葱（on_reasoning/on_model_call…）
checkpoint	AgentState（pydantic）+ StorageBase（Redis）
工作室多 agent	Agent Team（leader-worker 星形 · TeamCreate/AgentCreate/TeamSay）