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

tier2 agentic 运行时架构图说

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

---

0. 阅读约定与同步纪律

• 映射设计档：本图说只把《自治富游戏引擎》《tier2 四层工程架构》《tier2 实现详设》《agentic 集成架构》画出来。机制以 agentscope 2.0.2 源码实证为准（/root/oss/agentscope，逐条核过）。
• 同步纪律：设计一变动，本图说与对应 svg 必须同步更新（已并入 wave 收口清单）。
• 产物：svg 入仓（GitHub/编辑器渲染矢量），png 在 mini-desktop 转。
• 细节族图说（本图说之下的放大层）：本篇是整轨的「看图入口」（9 张总览图）；要看某一面的逐项细节，下钻这八份按族拆的细节图说（全八族已建，共 32 张细图，均为本总览的逐项放大、deepen 不 duplicate）：
  • A 族 · 运行时形态——Agent Service 与 session 三路径、Agent 非常驻 + AgentState、Workspace 双轴注入、Middleware 洋葱。
  • C 族 · 单写 ReAct 循环——ReAct 一轮 / 多轮自治、M3 Anthropic 原生接法、四道熔断 + 预算闸、承 amodel-gen 范式。
  • D 族 · 三层校验与九门——三层校验全景、九门逐门、富游戏专属门、advisory 分级 + Goodhart 隔离、CDP 探针 Phaser 重写。
  • E 族 · 能力面（skills 与 prompt）——toolkit 九工具、引擎能力包五件套、prompt 两阶段角色、A-model 4 插件复用。
  • F 族 · 源项目契约与装载——源项目契约七要素四组、第二装载分支、finish 工具共用 schema。
  • G 族 · 0号 spike runbook——建设五步 + 生死门、mini-肥鹅靶子、模型矩阵 + 跑序、过门阈值 + 采集字段、两段实施 + 退路树。
  • B 族 · 控制面与管理面——控制面四组件、反锁死五协议、预算三层强制、管理面三 phase。
  • H 族 · 观测与成本——trace 统一契约、观测管道（Event→OTel→Studio）、成本台账。

1. 全图通用图例

生产维度：安全 / 可观测 / 可靠 / 成本 / 数据 / 伸缩 / 质量（标在对应组件）。 复用边界（二维 · 图 6）：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。⚠️公共组件是自建的共享件、非现成。 自治范式：骨架 = 自治 loop（怎么走）+ task/goal 清单（走向哪、走到哪）+ Agent Team 动态调度（谁来走），没有 workflow DAG（见图 A 注 + §5b）。

2. 图集

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

两阶段。阶段 1 工作室用 Agent Team 星形：leader 分析+拆解用户意图、AgentCreate 出玩法/关卡/数值/UI/音乐/特效/资产设计 worker 发散，TeamSay 汇 leader 收敛成设计结论。这阶段是只读 + 对话——设计 worker 用 PermissionMode.EXPLORE 只读已有工程代码 + 工程内设计文档（迭代已有游戏时），并与用户跨 session 多轮对话。阶段 2 单写实现：① 模板代码初始化是这阶段的工具（从模板铺工程骨架）② 把阶段 1 每个设计 agent 的结论写成工程内文档 ③ 单写 agent 写代码 ④ 三层校验 ⑤ 产出。闭环：阶段 2 写进 repo 的文档/代码 → 下次迭代阶段 1 只读它再设计（设计文档 in repo、改源不改包，正是「游戏=长生命周期项目」）。设计用多 agent（发散/专业），实现用单写（防并行写冲突）。

图 1 · 系统全景 / 部署

tier2 agentic 是独立 service，game-cloud 经官方 Agent Service（REST + SSE）调它；service 内是「工作室 Agent Team → 单写」；它经 new-api 调模型、用 Workspace 干活、落 Redis/MySQL/OSS、trace 进 Studio；与 SAA 廉价线运行期零耦合，只在公共组件（计费/送审/feed/验收基线）交汇。

图 2 · 调用时序（含 session 初始化与两阶段）

tier2 不自造 API，直接用官方 Agent Service。POST /sessions 建 durable 会话，初始化三种加载入口：① 续接之前会话（取 SessionRecord.state 历史，resume）② 加载已有游戏工程（Workspace.workdir 指向已有目录 → 迭代）③ 新建（阶段 2 模板初始化工具铺模板）。之后 阶段 1 工作室（leader 只读设计、AgentCreate worker、TeamSay 收敛、设计写 repo 文档）→ 阶段 2 单写（ReAct loop：reason M3 / act Workspace / CDP 三层校验 / checkpoint）。每步 Event 经 SSE 流给 cloud（断线可 replay）+ OTel→Studio；可 HITL、可取消；产物落库后回完成 event。

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

按 AgentScope 真实结构画。核心是 Agent——无状态 ReAct 引擎，构造参数持有 model（M3）/toolkit/middlewares/state。Workspace 是执行环境，沿两轴注入 Agent：① 工具/MCP/skills → get_toolkit → Toolkit；② 本身作 offloader。所以 Agent 持有 Workspace 引用、不嵌在里面；真正「跑在 Workspace 里」的是 MCP 进程/skills/文件。Agent 实例非常驻——每 run 现组装、跑完即弃，状态全在可持久化 AgentState（含 context 工作记忆、cur_iter、tasks_context）。goal/进度 = 输入（brief/play_spec/GDD）为目标 + AgentState.tasks_context 拆 TODO、逐项 TaskCreate/Update 追踪（像 todo）。验收三层。四层（environment/harness/context/prompt）只是职责视角，叠在真实结构上。

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

一轮：组装 context → reason 调 M3 → 判断「调工具 or 收尾」→ 调工具去 Workspace 写码/构建/真跑、CDP 取证、过三层校验，没过 repair。模型产纯文本即收尾。四熔断任一触发优雅收尾，每轮 checkpoint。

图 5 · 编排与配置结构

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

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

图 6 · 复用边界（来源 × 共享 · 自建项标载体类型）

二维：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。左列官方现成（十几组，直接用、非 tier2 资产）。右上自建的两线公共件（九门/三层校验/CDP/计费/送审/feed/trace，自建但共享）。右下 tier2 私有自建。每个自建项标了载体类型——用 AgentScope 哪种扩展点做：Tool（工具函数）/ Middleware（hook 拦截）/ Skill（SKILL.md）/ Prompt（指令）/ Memory（ReMe）/ Schema（契约）/ 框架外独立。还标了「官方没有」（RAG/evaluate/A2A 基座）和「该删→改官方」6 项。

图 7 · 产物与契约

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 +tasks_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	系统全景（含 Team）	svg	✅
2	调用时序（session 三路径 + 两阶段）	svg	✅
3	运行时内部（真实结构 + goal/task）	svg	✅
4	单写 ReAct 循环流程（三层）	svg	✅
5	编排与配置	mermaid	✅
6	reuse 边界（二维 + 载体类型）	svg	✅
7	产物与契约	mermaid	✅
8	关键类图	mermaid	✅

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

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

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

5. 校正记录（创始人反馈 · 2026-06-22）

1. 两阶段 + 职责闭环：工作室多 agent 设计（Agent Team 星形）→ 单写实现（图 A）。阶段 1 只读（EXPLORE）+ 跨 session 对话 + 修改意图设计；阶段 2 写工程内文档 + 模板初始化工具 + 写代码；设计文档 in repo 闭环。
2. environment 嵌套纠错：Workspace 是执行环境、沿两轴注入 Agent；Agent 持有引用、非嵌套；Agent 非常驻（图 3）。
3. 三层校验：L1 必须 / L2 尽量 / L3 只评分，不同工具包，初期只 L1（§4、图 3/4）。
4. 复用边界二维 + 载体类型：来源 × 共享；官方能力列全；自建严格核对（6 项改官方）；公共=自建∩共享；每个自建项标用什么 AgentScope 扩展点做（图 6）。
5. goal/task：目标 = 输入(brief/GDD) + AgentState.tasks_context（TaskCreate/Update 拆 TODO 追踪），补进图 3。
6. workflow 范式：AgentScope 无显式 workflow DAG，tier2 是自治 loop + task/goal + Agent Team 动态调度（图 A 注）。
7. 图 1/2 加 Team + session 三路径：续会话 / 加载已有工程 / 加载模板（图 1、图 2）。

5b. 未来需求（记录 · 待讨论）

• 给用户使用的 workflow 能力（2026-06-22 记）：未来提供 workflow 编排能力给用户 / 创作者使用（可视化编排场景）。当前 tier2 自身不需要 workflow（自治 agent 范式）。这是未来产品场景，以后单独讨论，此处仅登记。

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

图里词	AgentScope 2.0 官方
environment / 沙箱	Workspace（Local/Docker/E2B），经 Toolkit + offloader 双轴接入 Agent
API / Session 层	Agent Service（REST + SSE，Agent 非常驻）
工作室多 agent	Agent Team（leader-worker 星形 · TeamCreate/AgentCreate/TeamSay）
goal / 任务追踪	AgentState.tasks_context + TaskCreate/Get/List/Update 工具
可观测	Event System（typed stream）→ TracingMiddleware → Studio
熔断	Middleware 洋葱（on_reasoning/on_model_call…）
checkpoint	AgentState（pydantic）+ StorageBase（Redis）