# tier2 agentic 运行时架构图说
> 🚧 评审版 · **全套 8 张已出**（5 张 svg 大图 + 3 张 mermaid）。
> **这是什么**：tier2 自治富游戏生成轨——agentic 这条线的「看图入口」。把「编排 → 启动 → 调用 → 运行时 → 返回结果」这条生命周期，以及它在整体里的位置、内部怎么转，用一套架构图讲清。复杂重要的用 svg/png 高保真大图，简单的用 mermaid。颗粒度面向 vibecoding——看图能照着实现。
> **给谁看**：要判断「整个 agentic 架构是不是想要的那个」的创始人；要照图实现的工程师 / vibecoding 的人。
---
## 0. 阅读约定与同步纪律
- **映射的设计档**：本图说不另立设计，只把以下四份「画出来」——《[自治富游戏引擎](自治富游戏引擎.md)》（范式）、《[tier2 四层工程架构](tier2四层工程架构.md)》（四层切分）、《[tier2 实现详设](tier2实现详设.md)》（契约 / spike runbook）、《[agentic 集成架构](agentic集成架构.md)》（控制 / 管理面）。所有运行时机制以 **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 那种可视化拖拽，但策略层可配热改、不必每次改代码重部署。
```mermaid
flowchart TB
APP["create_app(FastAPI)
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["硬代码·机制
门断言 / 熔断 / 权限上限"]
V["版本化·审计
依赖锁 / 引擎版本 / 构建 profile / 沙箱类型"]
HOT["热配置·策略
prompt / 模型路由 / 阈值 / RAG 源"]
end
APP --> AG
HOT -. 改配置不发版 .-> AG
```
### 图 6 · 复用边界全景（官方 / 自建 / 公共）
把「优先用官方」这条原则画成三色边界：左列是 AgentScope 生态直接用的（循环/工具/中间件/M3 接入/沙箱/服务化/记忆/可观测/HITL/结构化产出，一大列），中列是 tier2 真正要自建的（超时/卡死/硬杀熔断、金额成本、签名案例库、引擎 manifest、源项目契约、fixtures——都挂在官方扩展点或薄层上），右列是两条生成线共享、不进 tier2 私有的公共组件（验收基线/计费/送审/feed/trace 契约/new-api）。一眼看出自研面其实很小。
### 图 7 · 产物与契约
返回的产物不是一个打包 blob，而是一个**结构化源项目**（改源不改包、重新构建），由 tier2 源项目契约钉住其文件树/构建/依赖/落库；过程则由 trace 契约记录（公共核心子集 + 各线自己的扩展段）。
```mermaid
flowchart TB
subgraph SP["tier2 源项目契约（落库取回）"]
direction LR
ID["类型标记"] --- TREE["文件树 manifest
+ 入口文件"] --- BUILD["构建 profile
+ 依赖锁"] --- HASH["内容哈希"] --- DBAPI["落库 / 寻址
MySQL + OSS"]
end
subgraph TR["trace 契约（可观测）"]
direction LR
CORE["公共核心子集
traceId / step / cost / verdict / ts"] --- EXT["扩展段 JSON
tier2：推理 / 动作 / 观察"]
end
SP -.->|改源不改包·重新构建·长生命周期| OUT["可维护的 Phaser 源工程"]
```
### 图 8 · 关键类图
让 vibecoding 的人知道用哪些类、怎么组合：实线类是 AgentScope 官方的，`<<自建>>` 标注的是 tier2 挂在官方基类上写的。
```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
+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） |