# tier2 agentic 运行时架构图说

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

---

## 0. 阅读约定与同步纪律

- **映射的设计档**：本图说不另立设计，只把《[自治富游戏引擎](自治富游戏引擎.md)》《[tier2 四层工程架构](tier2四层工程架构.md)》《[tier2 实现详设](tier2实现详设.md)》《[agentic 集成架构](agentic集成架构.md)》画出来。运行时机制以 **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 · 生成两阶段（工作室设计 → 单写实现）

![图A 生成两阶段](assets/00-生成两阶段.svg)

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

### 图 1 · 系统全景 / 部署

![图1 系统全景](assets/01-系统全景.svg)

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）

![图2 调用时序](assets/02-调用时序.svg)

**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 真实对象结构）

![图3 运行时内部架构](assets/03-运行时内部架构.svg)

**这张按 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 循环流程（一轮迭代）

![图4 ReAct循环流程](assets/04-ReAct循环流程.svg)

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

### 图 5 · 编排与配置结构

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

```mermaid
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 · 复用边界（来源 × 共享范围）

![图6 reuse边界全景](assets/06-reuse边界全景.svg)

**两个维度**：来源（官方现成 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 契约记录。

```mermaid
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 · 关键类图

```mermaid
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） |