From e6d87dc4f5849f118fbfc92d8e2013c275ef6c0d Mon Sep 17 00:00:00 2001 From: zizi Date: Mon, 22 Jun 2026 07:32:36 +0000 Subject: [PATCH] =?UTF-8?q?docs(agentic):=20=E8=A1=A5=E5=85=A8=20tier2=20?= =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=97=B6=E6=9E=B6=E6=9E=84=E5=9B=BE=E9=9B=86?= =?UTF-8?q?(=E5=9B=BE1/2/4/6=20svg=20+=20=E5=9B=BE5/7/8=20mermaid)=20+=20?= =?UTF-8?q?=E5=AE=98=E6=96=B9=E6=9C=AF=E8=AF=AD=E6=A0=A1=E5=87=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 svg: 01-系统全景 / 02-调用时序 / 04-ReAct循环流程 / 06-reuse边界全景 - 图说 md 补全 8 图 + 图5/7/8 mermaid + 术语映射 - 校准官方术语: Agent Service(REST+SSE) / Workspace(Local/Docker/E2B) / Event System(agentscope 2.0.3 源码实证) Co-Authored-By: Claude Opus 4.8 (1M context) --- .../架构/生成引擎/agentic运行时架构图说.md | 184 ++++++++++++++---- .../架构/生成引擎/assets/01-系统全景.svg | 116 +++++++++++ .../架构/生成引擎/assets/02-调用时序.svg | 95 +++++++++ .../架构/生成引擎/assets/04-ReAct循环流程.svg | 98 ++++++++++ .../架构/生成引擎/assets/06-reuse边界全景.svg | 71 +++++++ 5 files changed, 530 insertions(+), 34 deletions(-) create mode 100644 docs/architecture/架构/生成引擎/assets/01-系统全景.svg create mode 100644 docs/architecture/架构/生成引擎/assets/02-调用时序.svg create mode 100644 docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg create mode 100644 docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg diff --git a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md index f1c1a7e5..4c5f7cb8 100644 --- a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md +++ b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md @@ -1,6 +1,6 @@ # tier2 agentic 运行时架构图说 -> 🚧 评审版 · **金样板阶段**：图 3（运行时内部架构）已出 svg 样板，其余图待风格确认后批量补。 +> 🚧 评审版 · **全套 8 张已出**（5 张 svg 大图 + 3 张 mermaid）。 > **这是什么**：tier2 自治富游戏生成轨——agentic 这条线的「看图入口」。把「编排 → 启动 → 调用 → 运行时 → 返回结果」这条生命周期，以及它在整体里的位置、内部怎么转，用一套架构图讲清。复杂重要的用 svg/png 高保真大图，简单的用 mermaid。颗粒度面向 vibecoding——看图能照着实现。 > **给谁看**：要判断「整个 agentic 架构是不是想要的那个」的创始人；要照图实现的工程师 / vibecoding 的人。 @@ -8,55 +8,171 @@ ## 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、无 rsvg/cairosvg）。 +- **映射的设计档**：本图说不另立设计，只把以下四份「画出来」——《[自治富游戏引擎](自治富游戏引擎.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. 生产维度图例（大厂生产环境关心的领域） +## 1. 全图通用图例 -架构图不只画「功能怎么连」，还要让人一眼看到「生产环境怎么保证它可靠、可观测、安全、可扩展、成本可控」。所以每张图都带这套**生产维度标注**，相关组件上挂对应标签： +每张图都带两套贯穿标注： -| 维度 | 在架构里的落点 | +**生产维度（大厂生产环境关心的领域）**——架构图不只画「功能怎么连」，还要让人一眼看到生产环境怎么保证它可靠、可观测、安全、可扩展、成本可控： + +| 维度 | 落点 | |---|---| -| **安全** | 沙箱隔离、密钥（`NEWAPI_KEY`）只走 env 不入库、forbidden-import 守门、LLM 产物消毒 | -| **可观测** | TracingMiddleware → OpenTelemetry → Studio（trace / token / cost） | -| **可靠** | 四熔断、checkpoint 中断恢复、HITL 中断/恢复、超时与重试 | -| **成本** | 预算闸（token 软刹 + 金额硬杀）、new-api quota 台账 | -| **数据** | 会话状态（Redis）、产物落库（MySQL+OSS）、内容哈希校验 | -| **伸缩** | `create_app` 多实例、多租户、会话隔离 | -| **质量** | 双层验收门（确定性硬门 + M3 视觉软检） | +| 安全 | 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 视觉软检） | -另有一套**复用边界图例**贯穿全图，让 vibecoding 的人一眼知道哪些是「直接用现成的」、哪些要「自己写」：**实线框 = AgentScope 生态官方现成直接用；虚线框 = tier2 自建（挂在官方 Middleware 或薄层上）；双线框 = 两条生成线共享的公共组件**。 +**复用边界**：**实线 = AgentScope 生态官方现成直接用；虚线 = tier2 自建（挂官方 Middleware 或薄层）；双线 = 两条生成线共享的公共组件**。 -## 2. 图 3 · 运行时内部架构（金样板） +## 2. 图集 + +### 图 1 · 系统全景 / 部署 + +![图1 系统全景](assets/01-系统全景.svg) + +最高层定位：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） + +![图2 调用时序](assets/02-调用时序.svg) + +你最关心的「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 · 运行时内部架构 ![图3 运行时内部架构](assets/03-运行时内部架构.svg) -这张图回答你一直没看到的那块——**agentic 运行时内部到底怎么转**。从外到内读： +运行时内部怎么转：中心是**单写者 ReAct 循环**（官方 `Agent` + `ReActConfig`，一个 agent 持全局、独自写，不并行拆），每轮推理→调工具→观测→验收，没过走 repair 回环。外圈 **Middleware 洋葱**关熔断（预算软刹是官方现成的，超时/卡死/fail-closed 硬杀自建挂上去）。循环向右连 environment 沙箱工作站（写码/构建/真跑，CDP 探针是公共件）、向下连 M3（Anthropic 原生 thinking）、左下挂记忆（ReMe）。产物经**双层验收门**判定（确定性硬门定 pass/fail、零 LLM 自评；M3 软检只观测）。底部是 checkpoint / 落库 / 可观测三件生产基础设施。 -整台机器是一个**独立进程的 service**（AgentScope 2.0.3，用官方 `create_app` 起成一个多租户、多会话的 FastAPI 服务），运行期与现有 SAA 廉价线零耦合。`game-cloud`（Java）通过一条 HTTP 接口把生成请求（一句话 brief + play_spec）发进来，API/Session 层据此建一个会话、起一个异步长任务，并把 runId 立即返回——因为造一款富游戏是长时任务，这里天然要会话、可中断（HITL）、可取消、会话之间互相隔离。 +### 图 4 · 单写者 ReAct 循环流程（一轮迭代） -请求进入后，核心是中间那个**单写者 ReAct 循环**：只有一个 Agent 持全局视图、独自写整个工程（经营游戏多系统共享状态，拆并行几乎必然不一致）。这个循环本身是 AgentScope 官方现成的——`Agent` + `ReActConfig(max_iters)`，不需要我们自建。它每一轮做四件事：**推理**（调 M3 模型）、**调工具**（在沙箱里写码、构建、真跑）、**观测**（收回产物和截图）、**验收裁决**（过 / 修 / 熔断）。模型某一轮产出纯文本、不再调工具，就是它认为「做完了」；到迭代上限或熔断触发，则优雅收尾。没过的轮次走 repair 回环，同一个 agent 继续修——不拆并行。 +![图4 ReAct循环流程](assets/04-ReAct循环流程.svg) -把这个循环「关进笼子」的是外面那圈 **Middleware 洋葱**。预算软刹是官方现成的 `ReplyBudgetControlMiddleware`（到额就注入提示、逼模型收尾）；但生产真正要的「超时、卡死探测、超额即硬性熔断（fail-closed）」官方没有，得我们照官方 middleware 的写法自建，挂在同样的扩展点上。一条贯穿的铁律标在图里：**确定性的归机器、绝不让 LLM 给自己打分；M3 的视觉软检永远只观测、不放行也不拒发**（防 Goodhart）。 +把图 3 中心那个循环展开成一轮的控制流：组装 context → reason 调 M3 → 判断「调工具还是收尾」。调工具就去 Workspace 写码/构建/真跑、CDP 取证、过双层验收；没过回 repair 重组 context 再来。模型某轮直接产纯文本（不调工具）就是收尾、出产物。右侧四熔断任一触发即优雅收尾，每轮 checkpoint。 -循环向外连三处。向右是 **environment 沙箱工作站**——agent 在这里用 Filesystem 写多文件源码、用 CODE 跑 esbuild 构建、用 Browser 起 headless 真跑加截图。这里有个关键的生产现实：官方 Browser 沙箱不暴露底层 `page.evaluate`，而 tier2 的确定性验收探针（注入输入、读帧、像素回读、活动 hash）全靠它，所以 **CDP 探针是一块公共组件**（双线框），靠同容器的 `run_shell_command` 自驱补上。向下是 **Model**——官方 `AnthropicChatModel`，开 thinking（thinking_enable + budget，thinking 自然分离），baseUrl 指向 new-api 的 `/v1/messages` 端点、用 `NEWAPI_KEY`，统一出口、协议不锁。左下是 **context 运行时载荷**——记忆用官方 ReMe（持久 + 检索 + 压缩），其中「按签名精确命中 debug 案例库」官方没有、是一层自建薄层；prompt 是 context 的子集，走热配置。 +### 图 5 · 编排与配置结构 -循环跑出来的产物，由右下的**双层验收门**判定：确定性硬门（九门 + 跨表联动 + 经济门，公共 CDP harness，零 LLM 自评，定 pass/fail）是机制地板；M3 视觉软检只产观测和告警，绝不参与「算不算完成」。最底下是**运行时基础设施**——会话状态 checkpoint 到 Redis（可中断恢复）、结构化游戏源项目落库到 MySQL+OSS（带内容哈希）、全程可观测经 TracingMiddleware → OpenTelemetry → Studio。全绿的产物落库后，runId 对应的结果就能被 game-cloud 取回、进 feed。 +「编排 agentic」= 写一次代码骨架（`create_app` 起服务 + 组装 Agent 的 model/toolkit/middleware/memory/react_config），「配置」= 三类外置（机制硬代码、安全/构建走版本化审计、策略热改不发版）。不是 Dify 那种可视化拖拽，但策略层可配热改、不必每次改代码重部署。 -## 3. 图清单与进度 +```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 +``` -以你的 5 步生命周期为主轴 + 3 张横切补全： +### 图 6 · 复用边界全景（官方 / 自建 / 公共） -| # | 图 | 讲清什么 | 形式 | 状态 | +![图6 reuse边界全景](assets/06-reuse边界全景.svg) + +把「优先用官方」这条原则画成三色边界：左列是 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 | 系统全景 / 部署 | agentic 是独立 service，cloud 经 HTTP 调它；连 new-api / 沙箱 / 存储 / Studio | svg | 待出 | -| 2 | 调用时序（cloud ↔ agentic） | 发起 → 建 session → 异步长任务 → 进度/取消 → 产出落库 → 回 verdict | svg | 待出 | -| **3** | **运行时内部架构（四层 + 组件）** | 运行时怎么转：单写者循环 / 沙箱 / 熔断 / M3 / 记忆 / 验收 / 可观测 | **svg** | **✅ 金样板** | -| 4 | 单写者 ReAct 循环流程 | 一轮：组 context → 调 M3 → 决策 → 写码/构建/真跑 → 观测 → 验收 → 过/修/熔断 | svg | 待出 | -| 5 | 编排与配置结构 | `create_app` 骨架 + Agent 组装 + 三类配置（硬代码/版本化/热改） | mermaid | 待出 | -| 6 | reuse 边界全景 | AgentScope 现货 / 自建 / 公共组件 三色边界 | svg | 待出 | -| 7 | 产物与契约 | 源项目契约 + trace 契约 | mermaid | 待出 | -| 8 | 关键类图 | AgentScope 类 + tier2 自建类 | mermaid | 待出 | +| 1 | 系统全景 / 部署 | 定位 | svg | ✅ | +| 2 | 调用时序（cloud ↔ agentic） | 启动 + 调用 + 返回 | svg | ✅ | +| 3 | 运行时内部架构 | 运行时 | svg | ✅ | +| 4 | 单写者 ReAct 循环流程 | 运行时动态 | svg | ✅ | +| 5 | 编排与配置结构 | 编排 + 配置 | mermaid | ✅ | +| 6 | reuse 边界全景 | 复用边界 | svg | ✅ | +| 7 | 产物与契约 | 返回形态 | mermaid | ✅ | +| 8 | 关键类图 | 实现 | mermaid | ✅ | -> 金样板（图 3）的风格 / 颗粒度 / 生产维度标注经创始人确认后，再按此清单批量补全其余 7 张，并统一转 png 入仓。 +## 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） | diff --git a/docs/architecture/架构/生成引擎/assets/01-系统全景.svg b/docs/architecture/架构/生成引擎/assets/01-系统全景.svg new file mode 100644 index 00000000..baccb011 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/01-系统全景.svg @@ -0,0 +1,116 @@ + + + + + + + + 图 1 · 系统全景 / 部署 + tier2 agentic 是独立 service，game-cloud 经 HTTP API 调用；运行期与 SAA 廉价线零耦合；模型统一经 new-api。 + + + + game-cloud（Java · 调用方 + 公共组件宿主） + + 生成请求编排（dispatcher） + + 计费台账（读 new-api quota）〔公共〕 + + 送审 / 审核台〔公共〕 + + feed / 发布〔公共〕 + + CDP 验收基线（公共 harness）〔公共·双线〕 + 九门确定性验收，两线共享，泛化 Phaser + 公共组件 = 两条生成线共享，不进 tier2 私有 + 安全 + 质量 + + + + tier2 agentic service　〔主角〕 + 独立进程 / 容器 · AgentScope 2.0.3 · create_app(FastAPI) + + Agent Service（REST + SSE） + 多租户 · 会话 · HITL · 取消 · /sessions /chat /schedule + + 单写者 ReAct 循环（详见图 3） + Agent + ReActConfig + Middleware 熔断 + 四层载荷 + + Model 适配 → new-api + + Workspace（Local/Docker/E2B） + + checkpoint / 记忆 + + 可观测（OTel 导出） + 安全 + 伸缩 + 可靠 + 可观测 + 内部运行时怎么转 → 图 3；调用时序 → 图 2 + + + + new-api 网关（统一出口·协议不锁） + /v1/messages（M3 Anthropic 原生） · /v1/chat/completions（OpenAI） + NEWAPI_KEY 驱动 · quota 计费 + 成本 + + + 上游模型 + MiniMax-M3（主） / deepseek-v4-flash·pro / Opus·Fable（基线） + + + Workspace 工作站（Local / Docker / E2B） + Filesystem(写 src/) · CODE(esbuild) · Browser(headless) + + CDP 探针〔公共〕同容器 run_shell_command 自驱 + 安全 + + + AgentScope Studio（可观测 dashboard） + OTel trace 可视化：reasoning / tool-call / token / cost + as_studio · :3000(UI) / :4317(OTLP) + 观测 + + + + 持久化　〔数据〕 + Redis（会话 / checkpoint） + MySQL（产物元 / 业务） + OSS（产物文件 · 内容哈希） + + + + SAA 廉价线（Tier0/1 · Java） + 现行生成主线；与本 service 运行期零耦合 · 可删 + 两线只经公共组件（计费/送审/feed/验收基线）交汇 + + + + REST POST /sessions + + SSE event-stream（可恢复） + + + 模型调用 /v1/messages + + + 写码/构建/真跑 + + OTel trace + + 会话 / 产物落库 + + + 复用边界： + 实线〔官方现成〕 + 虚线〔自建/零耦合〕 + 双线〔公共组件〕 + 映射：agentic集成架构.md · tier2四层工程架构.md　|　基于 agentscope 2.0.3 源码实证　|　设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/02-调用时序.svg b/docs/architecture/架构/生成引擎/assets/02-调用时序.svg new file mode 100644 index 00000000..1d65574c --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/02-调用时序.svg @@ -0,0 +1,95 @@ + + + + + + + + 图 2 · 调用时序（cloud ↔ agentic） + cloud 直接用官方 Agent Service：REST 建会话 + SSE 收流式 Event；durable session 可恢复、可取消、支持 HITL。蓝色虚线 = SSE 事件流。 + + + + game-cloud（Java） + 调用方 + + Agent Service〔官方〕 + REST + SSE · 多租户 · durable + + 运行时（单写者循环） + Agent + Middleware + + 依赖 + new-api · Workspace · 存储 · Studio + + + + + + + + + + ① POST /sessions（brief + play_spec） + + ② 201 · session_id（durable 持久会话） + + ③ GET /sessions/{id}/events（SSE 订阅） + + ④ 启动单写者 run + + + + ReAct 循环 ×N（每轮详见图 3 / 图 4） + + + ⑤ reason → new-api（M3 /v1/messages，thinking） + + ⑥ thinking + tool/text（Event） + + ⑦ act → Workspace（写码 / esbuild / headless 真跑） + + ⑧ CDP 探针 → verdict〔公共〕 + + ⑨ 未过 → repair 回环 + + ⑩ checkpoint → Redis（durable，可恢复） + + ⑪ Event（thinking / tool / result） + + ⑫ SSE event-stream（resumable：断线 replay buffered） + + ⑬ OTel trace → Studio + + + + HITL（可选）：运行时挂起 → RequireUserConfirm（经 SSE 推 cloud）→ cloud POST /sessions/{id} 确认/编辑参数 → 从暂停处精确恢复 + + + ⑭ 产物落库 → MySQL + OSS（内容哈希） + + ⑮ 完成 event：verdict + 产物引用 + + ⑯ 取产物 → 进 feed + + + + 异常 / 生产路径： + 超时/熔断 → 优雅收尾(ExceedMaxItersEvent) · cloud 取消 session · provider 瞬时失败 graceful fallback · /schedule 定时 run · /credential 托管密钥 + + + REST 请求 / 同步动作 + SSE 事件流（Event System · 异步 / 可恢复） + 可靠 + 数据 + 可观测 + 安全 + durable/取消/fallback=可靠 · checkpoint/落库=数据 · Event/SSE/OTel=可观测 · HITL/credential=安全 + + 映射：agentic集成架构.md · tier2实现详设.md　|　基于 agentscope 2.0.3 官方 Agent Service（/sessions + SSE）源码实证　|　设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg b/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg new file mode 100644 index 00000000..3efa5c63 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg @@ -0,0 +1,98 @@ + + + + + + + + 图 4 · 单写者 ReAct 循环流程（一轮迭代） + 官方 Agent + ReActConfig 内置循环；收尾 = 模型产纯文本(不调工具)；四熔断任一触发即优雅收尾；每轮 checkpoint。 + + + + START：brief + play_spec + + + 组装 context + prompt + 源项目视图 + 记忆 + 预算 + + + reason：调 M3（thinking 分离） + AnthropicChatModel → new-api /v1/messages + + + 调工具？ + tool / 纯文本 + + + act：调工具（Workspace） + 写多文件 → esbuild → headless 真跑 + + + observe：收产物 + 截图 + CDP 探针取证（公共） + + + 双层验收门 + 确定性硬门 pass/fail（零 LLM 自评） + + M3 视觉软检（只观测） + + + 产出：结构化游戏源项目 + → 落库 MySQL + OSS（内容哈希） + + + + repair 回环 + 同一 agent 续修 + + + checkpoint + AgentState → Redis（每轮） + + + + 四熔断（任一触发 → 优雅收尾） + ① 步数硬顶 max_iters　〔官方〕 + ② 预算闸：软刹〔官方〕+ 硬杀〔自建〕 + ③ 卡死语义探测　〔自建〕 + ④ 双层超时（wall-clock）　〔自建〕 + 自建项均挂官方 Middleware 扩展点 + （on_reasoning / on_model_call） + 收尾 = ExceedMaxItersEvent → 优雅返回 + + + + + + + 是 · 调工具 + + + + 全绿 + + + + 否 · 纯文本 = 收尾 + + + + 未过 + + repair 回环 → 重组 context + + + + + + + + + 〔官方〕= AgentScope 现成　〔自建〕= 挂官方 Middleware 自写　|　映射：tier2四层工程架构.md §4 · 自治富游戏引擎.md　|　设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg b/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg new file mode 100644 index 00000000..40a34950 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg @@ -0,0 +1,71 @@ + + + + + + 图 6 · 复用边界全景（官方 / 自建 / 公共） + 原则：能用 AgentScope 官方现成就不自研；自建一律挂官方扩展点 / 薄层；公共组件两条生成线共享、不进 tier2 私有。 + + + + AgentScope 生态官方现成 + 〔实线 · 直接用〕 + + · Agent + ReActConfig（多轮循环 + 步数熔断） + · Toolkit（工具注册 · execute_shell/python） + · Middleware 洋葱（ReplyBudgetControl 预算软刹） + · AnthropicChatModel + Formatter（M3 thinking） + · AgentState（checkpoint 状态对象） + · Workspace（Local / Docker / E2B 沙箱） + · Agent Service（REST + SSE · 多租户 · durable） + · Event System（text/thinking/tool/result 流） + · TracingMiddleware（OpenTelemetry 埋点） + · ReMe（持久记忆 + 检索 + 压缩） + · Studio（可观测 dashboard） + · Permission System + HITL（中断 / 恢复） + · generate_structured_output（结构化产出） + · Schedule / Credential（定时 · 托管密钥） + + + + + tier2 自建 + 〔虚线 · 挂官方扩展点 / 薄层〕 + + · 超时熔断 middleware（wall-clock） + · 卡死语义探测 middleware + · fail-closed 硬杀（超额强制停） + · 金额（¥）成本累计（官方只到 token） + · debug 案例库（签名精确匹配薄层） + · 引擎能力包 manifest（Phaser） + · tier2 源项目契约 + 文件树 / 构建 profile / 依赖锁 / 落库寻址 + · mini-肥鹅 spike fixtures + · agent 收尾接线 → 产结构化游戏定义 + · Phaser 引擎适配（第一版硬编码） + + + + + 公共组件 + 〔双线 · 两条生成线共享〕 + + · CDP 验收基线（九门 harness 泛化 Phaser） + · 计费台账（读 new-api quota） + · 送审 / 审核台 + · feed / 发布 + · trace 契约（公共核心子集 + 扩展段） + · new-api 网关（统一出口 · 协议不锁） + + + 为什么这些是公共： + 两条生成线（SAA 廉价线 + tier2 富游戏） + 产物都要计费、送审、进同一个 feed， + 都靠同一套确定性验收基线判能不能玩。 + → 抽出共享，不在 tier2 私有里重复造。 + + 映射：tier2四层工程架构.md §8 · agentic集成架构.md　|　基于 agentscope 2.0.3 源码实证　|　设计变动须同步本图 +