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

tier2 agentic 运行时架构图说

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

---

0. 阅读约定与同步纪律

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

1. 全图通用图例

每张图都带两套贯穿标注：

生产维度（大厂生产环境关心的领域）——架构图不只画「功能怎么连」，还要让人一眼看到生产环境怎么保证它可靠、可观测、安全、可扩展、成本可控：

维度	落点
安全	Workspace 沙箱隔离、密钥（NEWAPI_KEY）只走 env 不入库、forbidden-import、产物消毒
可观测	Event System（typed stream）→ TracingMiddleware → OpenTelemetry → Studio
可靠	四熔断、checkpoint 中断恢复、HITL、durable session、provider fallback
成本	预算闸（token 软刹 + 金额硬杀）、new-api quota 台账
数据	会话状态（Redis）、产物落库（MySQL+OSS）、内容哈希
伸缩	create_app 多实例、多租户、会话隔离
质量	双层验收门（确定性硬门 + M3 视觉软检）

复用边界：实线 = AgentScope 生态官方现成直接用；虚线 = tier2 自建（挂官方 Middleware 或薄层）；双线 = 两条生成线共享的公共组件。

2. 图集

图 1 · 系统全景 / 部署

最高层定位：tier2 agentic 是一个独立 service，game-cloud（Java）通过官方 Agent Service 的 REST 端点 + SSE 事件流调它；它向上经 new-api 网关（统一出口、协议不锁）调模型，向内用 Workspace（Local/Docker/E2B 沙箱）干活，把会话/产物落到 Redis/MySQL/OSS，并把 trace 导出到 Studio。它与现行 SAA 廉价线运行期零耦合——两条生成线只在「计费 / 送审 / feed / 验收基线」这些公共组件上交汇。

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

你最关心的「cloud 怎么调 agentic API」。关键是 tier2 不自造 API，直接用官方 Agent Service：cloud 用 POST /sessions 建一个 durable 会话并触发 run，再用 GET /sessions/{id}/events 订阅一条 SSE 事件流。运行时每一步（thinking / tool / result）作为 Event 经 SSE 流式推给 cloud；这条流是可恢复的——断线重连会 replay 已缓冲的事件。中途可挂起做 HITL（让人确认/编辑工具参数）再精确恢复，也可随时取消 session。产物落库后，cloud 收到完成 event（verdict + 产物引用），取回进 feed。

图 3 · 运行时内部架构

运行时内部怎么转：中心是单写者 ReAct 循环（官方 Agent + ReActConfig，一个 agent 持全局、独自写，不并行拆），每轮推理→调工具→观测→验收，没过走 repair 回环。外圈 Middleware 洋葱关熔断（预算软刹是官方现成的，超时/卡死/fail-closed 硬杀自建挂上去）。循环向右连 environment 沙箱工作站（写码/构建/真跑，CDP 探针是公共件）、向下连 M3（Anthropic 原生 thinking）、左下挂记忆（ReMe）。产物经双层验收门判定（确定性硬门定 pass/fail、零 LLM 自评；M3 软检只观测）。底部是 checkpoint / 落库 / 可观测三件生产基础设施。

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

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

图 5 · 编排与配置结构

「编排 agentic」= 写一次代码骨架（create_app 起服务 + 组装 Agent 的 model/toolkit/middleware/memory/react_config），「配置」= 三类外置（机制硬代码、安全/构建走版本化审计、策略热改不发版）。不是 Dify 那种可视化拖拽，但策略层可配热改、不必每次改代码重部署。

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"]
    AG --> RC["react_config：max_iters"]
  end
  subgraph 配置["配置外置（三类）"]
    H["硬代码·机制<br/>门断言 / 熔断 / 权限上限"]
    V["版本化·审计<br/>依赖锁 / 引擎版本 / 构建 profile / 沙箱类型"]
    HOT["热配置·策略<br/>prompt / 模型路由 / 阈值 / RAG 源"]
  end
  APP --> AG
  HOT -. 改配置不发版 .-> AG

图 6 · 复用边界全景（官方 / 自建 / 公共）

把「优先用官方」这条原则画成三色边界：左列是 AgentScope 生态直接用的（循环/工具/中间件/M3 接入/沙箱/服务化/记忆/可观测/HITL/结构化产出，一大列），中列是 tier2 真正要自建的（超时/卡死/硬杀熔断、金额成本、签名案例库、引擎 manifest、源项目契约、fixtures——都挂在官方扩展点或薄层上），右列是两条生成线共享、不进 tier2 私有的公共组件（验收基线/计费/送审/feed/trace 契约/new-api）。一眼看出自研面其实很小。

图 7 · 产物与契约

返回的产物不是一个打包 blob，而是一个结构化源项目（改源不改包、重新构建），由 tier2 源项目契约钉住其文件树/构建/依赖/落库；过程则由 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 · 关键类图

让 vibecoding 的人知道用哪些类、怎么组合：实线类是 AgentScope 官方的，<<自建>> 标注的是 tier2 挂在官方基类上写的。

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
    +thinking_budget
    +credential.base_url
  }
  class AgentState {
    +cur_iter
    +context
  }
  class WorkspaceBase
  Agent --> ReActConfig
  Agent --> Toolkit
  Agent --> MiddlewareBase
  Agent --> AnthropicChatModel
  Agent --> AgentState
  MiddlewareBase <|-- ReplyBudgetControlMiddleware
  MiddlewareBase <|-- TimeoutMiddleware
  MiddlewareBase <|-- StuckDetectMiddleware
  WorkspaceBase <|-- LocalWorkspace
  WorkspaceBase <|-- DockerWorkspace
  WorkspaceBase <|-- E2BWorkspace
  note for TimeoutMiddleware "自建"
  note for StuckDetectMiddleware "自建"

3. 图清单与状态

#	图	覆盖步骤	形式	状态
1	系统全景 / 部署	定位	svg	✅
2	调用时序（cloud ↔ agentic）	启动 + 调用 + 返回	svg	✅
3	运行时内部架构	运行时	svg	✅
4	单写者 ReAct 循环流程	运行时动态	svg	✅
5	编排与配置结构	编排 + 配置	mermaid	✅
6	reuse 边界全景	复用边界	svg	✅
7	产物与契约	返回形态	mermaid	✅
8	关键类图	实现	mermaid	✅

4. 术语映射（图 3 沿用旧词，此处对齐官方）

图 3（先出的金样板）用了「沙箱 / API-Session / 可观测」等旧词，与 AgentScope 2.0 官方术语对应如下，后续若重绘图 3 一并对齐：

图里旧词	AgentScope 2.0 官方
沙箱工作站	Workspace（LocalWorkspace / DockerWorkspace / E2BWorkspace）
API / Session 层	Agent Service（REST + SSE，/sessions 等）
可观测（OTel）	Event System（typed stream）→ TracingMiddleware → Studio
熔断（Middleware）	Middleware 洋葱（on_reasoning / on_model_call …）
checkpoint	AgentState（pydantic）+ StorageBase（Redis）