diff --git a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md index 4c5f7cb8..813b5ece 100644 --- a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md +++ b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md @@ -1,64 +1,58 @@ # tier2 agentic 运行时架构图说 -> 🚧 评审版 · **全套 8 张已出**（5 张 svg 大图 + 3 张 mermaid）。 -> **这是什么**：tier2 自治富游戏生成轨——agentic 这条线的「看图入口」。把「编排 → 启动 → 调用 → 运行时 → 返回结果」这条生命周期，以及它在整体里的位置、内部怎么转，用一套架构图讲清。复杂重要的用 svg/png 高保真大图，简单的用 mermaid。颗粒度面向 vibecoding——看图能照着实现。 -> **给谁看**：要判断「整个 agentic 架构是不是想要的那个」的创始人；要照图实现的工程师 / vibecoding 的人。 +> 🚧 评审版 · **9 张图**（6 svg + 3 mermaid）· 已纳入创始人 4 问校正（见 §5）。 +> **这是什么**：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、无转换器）。 +- **映射的设计档**：本图说不另立设计，只把《[自治富游戏引擎](自治富游戏引擎.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/落库/哈希）、伸缩（多实例/多租户/会话隔离）、质量（三层校验）。 -**生产维度（大厂生产环境关心的领域）**——架构图不只画「功能怎么连」，还要让人一眼看到生产环境怎么保证它可靠、可观测、安全、可扩展、成本可控： - -| 维度 | 落点 | -|---|---| -| 安全 | 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 或薄层）；双线 = 两条生成线共享的公共组件**。 +**复用边界（二维 · 见图 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`（Java）通过官方 **Agent Service 的 REST 端点 + SSE 事件流**调它；它向上经 **new-api 网关**（统一出口、协议不锁）调模型，向内用 **Workspace**（Local/Docker/E2B 沙箱）干活，把会话/产物落到 Redis/MySQL/OSS，并把 trace 导出到 Studio。它与现行 **SAA 廉价线运行期零耦合**——两条生成线只在「计费 / 送审 / feed / 验收基线」这些**公共组件**上交汇。 +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) -你最关心的「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。 +**tier2 不自造 API，直接用官方 Agent Service**：`POST /sessions` 建 durable 会话并触发 run，`GET /sessions/{id}/events` 订阅 SSE。运行时每步（thinking/tool/result）作为 Event 经 SSE 流式推 cloud，**断线重连可 replay 缓冲**。中途可 HITL（确认/编辑工具参数）再精确恢复，也可取消。产物落库后回完成 event（verdict + 产物引用）。 -### 图 3 · 运行时内部架构 +### 图 3 · 运行时内部架构（AgentScope 真实对象结构） ![图3 运行时内部架构](assets/03-运行时内部架构.svg) -运行时内部怎么转：中心是**单写者 ReAct 循环**（官方 `Agent` + `ReActConfig`，一个 agent 持全局、独自写，不并行拆），每轮推理→调工具→观测→验收，没过走 repair 回环。外圈 **Middleware 洋葱**关熔断（预算软刹是官方现成的，超时/卡死/fail-closed 硬杀自建挂上去）。循环向右连 environment 沙箱工作站（写码/构建/真跑，CDP 探针是公共件）、向下连 M3（Anthropic 原生 thinking）、左下挂记忆（ReMe）。产物经**双层验收门**判定（确定性硬门定 pass/fail、零 LLM 自评；M3 软检只观测）。底部是 checkpoint / 落库 / 可观测三件生产基础设施。 +**这张按 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 重组 context 再来。模型某轮直接产纯文本（不调工具）就是收尾、出产物。右侧四熔断任一触发即优雅收尾，每轮 checkpoint。 +把图 3 中心那个循环展开成一轮：组装 context → reason 调 M3 → 判断「调工具还是收尾」→ 调工具就去 Workspace 写码/构建/真跑、CDP 取证、过**三层校验**，没过回 repair。模型产纯文本即收尾、出产物。右侧四熔断任一触发即优雅收尾，每轮 checkpoint。 ### 图 5 · 编排与配置结构 -「编排 agentic」= 写一次代码骨架（`create_app` 起服务 + 组装 Agent 的 model/toolkit/middleware/memory/react_config），「配置」= 三类外置（机制硬代码、安全/构建走版本化审计、策略热改不发版）。不是 Dify 那种可视化拖拽，但策略层可配热改、不必每次改代码重部署。 +「编排」= 写一次代码骨架（`create_app` + 组装 Agent 的 model/toolkit/middleware/memory/react_config），「配置」= 三类外置（机制硬代码、安全/构建走版本化审计、策略热改不发版）。 ```mermaid flowchart TB @@ -68,7 +62,7 @@ flowchart TB AG --> M["model：AnthropicChatModel(M3)"] AG --> TK["toolkit：Workspace 工具 + CDP 探针"] AG --> MW["middlewares：预算软刹(官方) + 超时/卡死/硬杀(自建)"] - AG --> MEM["memory：ReMe"] + AG --> MEM["memory：ReMe / AgentState.context"] AG --> RC["react_config：max_iters"] end subgraph 配置["配置外置（三类）"] @@ -80,15 +74,15 @@ flowchart TB HOT -. 改配置不发版 .-> AG ``` -### 图 6 · 复用边界全景（官方 / 自建 / 公共） +### 图 6 · 复用边界（来源 × 共享范围） ![图6 reuse边界全景](assets/06-reuse边界全景.svg) -把「优先用官方」这条原则画成三色边界：左列是 AgentScope 生态直接用的（循环/工具/中间件/M3 接入/沙箱/服务化/记忆/可观测/HITL/结构化产出，一大列），中列是 tier2 真正要自建的（超时/卡死/硬杀熔断、金额成本、签名案例库、引擎 manifest、源项目契约、fixtures——都挂在官方扩展点或薄层上），右列是两条生成线共享、不进 tier2 私有的公共组件（验收基线/计费/送审/feed/trace 契约/new-api）。一眼看出自研面其实很小。 +**两个维度**：来源（官方现成 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 · 产物与契约 -返回的产物不是一个打包 blob，而是一个**结构化源项目**（改源不改包、重新构建），由 tier2 源项目契约钉住其文件树/构建/依赖/落库；过程则由 trace 契约记录（公共核心子集 + 各线自己的扩展段）。 +返回的是**结构化源项目**（改源不改包、重新构建），由源项目契约钉住文件树/构建/依赖/落库；过程由 trace 契约记录。 ```mermaid flowchart TB @@ -105,74 +99,74 @@ flowchart TB ### 图 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 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 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. 图清单与状态 -| # | 图 | 覆盖步骤 | 形式 | 状态 | -|---|---|---|---|---| -| 1 | 系统全景 / 部署 | 定位 | svg | ✅ | -| 2 | 调用时序（cloud ↔ agentic） | 启动 + 调用 + 返回 | svg | ✅ | -| 3 | 运行时内部架构 | 运行时 | svg | ✅ | -| 4 | 单写者 ReAct 循环流程 | 运行时动态 | svg | ✅ | -| 5 | 编排与配置结构 | 编排 + 配置 | mermaid | ✅ | -| 6 | reuse 边界全景 | 复用边界 | svg | ✅ | -| 7 | 产物与契约 | 返回形态 | mermaid | ✅ | -| 8 | 关键类图 | 实现 | mermaid | ✅ | +| # | 图 | 形式 | 状态 | +|---|---|---|---| +| A | 生成两阶段（工作室→单写） | svg | ✅ 新增 | +| 1 | 系统全景 / 部署 | svg | ✅ | +| 2 | 调用时序（cloud↔agentic） | svg | ✅ | +| 3 | 运行时内部（真实对象结构） | svg | ✅ 重画 | +| 4 | 单写 ReAct 循环流程 | svg | ✅ | +| 5 | 编排与配置 | mermaid | ✅ | +| 6 | reuse 边界（二维） | svg | ✅ 重做 | +| 7 | 产物与契约 | mermaid | ✅ | +| 8 | 关键类图 | mermaid | ✅ | -## 4. 术语映射（图 3 沿用旧词，此处对齐官方） +## 4. 三层校验（创始人定义） -图 3（先出的金样板）用了「沙箱 / API-Session / 可观测」等旧词，与 AgentScope 2.0 官方术语对应如下，后续若重绘图 3 一并对齐： +| 层 | 内容 | 处置 | 工具包 | +|---|---|---|---| +| **L1 硬约束** | 编译报错 / 启动报错 / 运行错误日志 | **必须解决 · 循环** | 确定性：构建日志 / console error / CDP 错误捕获（九门多数落此） | +| **L2 设计符合** | 玩法/关卡实现 vs 最新设计、UI 缺组件 | **尽量解决** | 设计符合度校验（部分九门：机制进展） | +| **L3 效果** | 特效 / 画面美观 / 好不好玩 | **只评分不解决** | M3 视觉软检（绝不阻塞、绝不拒发） | -| 图里旧词 | AgentScope 2.0 官方 | +**迭代原则**：初期只识别硬问题（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 官方 | |---|---| -| 沙箱工作站 | **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` …） | +| 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） | diff --git a/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg b/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg new file mode 100644 index 00000000..f590167f --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg @@ -0,0 +1,94 @@ + + + + + + + + 图 A · 生成两阶段：工作室（多 agent 设计）→ 单写（实现） + AgentScope Agent Team 星形：leader 拆解+调度，多专业设计 worker 发散；再交单写 agent 实现。设计用多 agent（发散·专业分工），实现用单写（防并行写冲突）。 + + + + 阶段 1 · 游戏工作室（Agent Team 星形） + + + 一句话 brief + play_spec + + + leader agent + 意图分析 + 拆解 + + 调度 + 收敛 + + + + + 玩法设计 worker + 关卡设计 worker + 数值/机制设计 worker + UI 设计 worker + 音乐 / 音效设计 worker + 特效设计 worker + 资产设计 worker + + + + + + + + + + + · 基于玩法模板 prompt + 工程初始化模板 + · worker 不互连（星形）· + TeamSay 收发汇 leader + + + leader 收敛 → 结构化设计 + GDD（玩法/胜负/机制）+ 关卡/数值表 + UI 规格 + 音乐音效/特效设计 + + 资产清单 + 工程骨架初始化（玩法模板代码脚手架） + Agent Team 工具：TeamCreate / AgentCreate（派生 worker）/ TeamSay / TeamDelete · 经 MessageBus 异步驱动 + + + + 移交结构化设计 + + 工程骨架 + + + + 阶段 2 · 单写实现 + + + 结构化设计（GDD + 各维度 + 工程骨架） + 阶段 1 的产物，作为单写 agent 的输入 + + + 单写 agent（实现） + ReAct 循环写代码（运行时内部 → 图 3） + + + 三层校验（L1 必须 / L2 尽量 / L3 评分） + 未过 → repair 回环 + + + 产出：结构化游戏源项目 + → 落库 MySQL + OSS + + + + + + + + 为什么这样分两阶段： + · 设计阶段是发散、各专业不共享代码状态 → 多 agent 并行最优 + · 实现阶段多系统共享同一套代码/约定 → 单写防不一致 + 　（曾把 Flappy 拆并行写，背景跑成了马里奥） + + 映射：自治富游戏引擎.md（单写者）· tier2实现详设.md · agentic集成架构.md　|　基于 agentscope 2.0.3 Agent Team 源码实证　|　设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg b/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg index 746ca143..54dad230 100644 --- a/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg +++ b/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg @@ -1,209 +1,120 @@ - + - - - - - - + + + + 图 3 · 运行时内部架构（AgentScope 真实对象结构） + Agent 是无状态引擎、持有 Workspace（双轴注入）；Agent 实例非常驻（每 run 现组装）；验收三层。四层(environment/harness/context/prompt)为职责视角，叠在真实结构上。 - - 图 3 · tier2 agentic 运行时内部架构（金样板） - 单写者 ReAct 循环 · 四层（environment / harness / context / prompt） · 标注大厂生产维度 · 颗粒度面向 vibecoding + + Agent Service（FastAPI · 多租户 · durable）　—　Agent 实例非常驻：每 run 现组装 → 跑完即弃，状态全在可持久化 AgentState - - - tier2 agentic service　·　独立进程（运行期零耦合 SAA）　·　AgentScope 2.0.3　·　create_app(FastAPI · 多租户 · 多会话) + + + game-cloud + + ChatService：取 AgentRecord(模板) + SessionRecord.state + → 现组装 Agent → 跑完写回 state（Agent 非常驻） + + REST /sessions + + SSE（可恢复） - - - game-cloud - (Java · 调用方) + + + Agent · 无状态 ReAct 引擎（每 run 现组装）　〔官方〕 - - API / Session 层 - 建 session · 异步长任务 · HITL 中断/恢复 · 取消 · 会话隔离 - 伸缩 - 可靠 + + model：AnthropicChatModel(M3 thinking) + → new-api /v1/messages + NEWAPI_KEY + + toolkit：内置工具 + 游戏工具 + 写多文件 / esbuild / headless / CDP 探针 - - HTTP POST /generate (brief+play_spec) + + middlewares（6-hook 洋葱） + 预算软刹〔官方〕+ 超时/卡死/硬杀〔自建〕 + + state：AgentState　〔一切可变态·可持久化〕 + context / cur_iter / permission / tool / tasks - - - harness 控制面　·　单写者 ReAct 循环 + + offloader = Workspace（context 卸载）　·　PermissionEngine（用 state.permission_context · 驱动 HITL） - - - Middleware 洋葱链 - 预算软刹 ReplyBudgetControlMiddleware〔官方〕 ｜ 超时 / 卡死 / fail-closed 硬杀〔自建〕 - 成本·可靠 + + ReAct 循环（max_iters，默认 20） + ① reason + ② act + ③ observe + ④ 验收 + + + + + 未过 → repair 回环（同一 agent） + · 收尾 = 产纯文本（不调工具）；到 max_iters / 熔断 → 优雅收尾（ExceedMaxItersEvent） + · 四熔断：步数(官方) / 预算(软刹官方+硬杀自建) / 卡死探测(自建) / 双超时(自建) + + 铁律：确定性归机器、绝不让 LLM 自评；L3 效果软检永不放行/拒发（防 Goodhart） + 可靠安全数据 - - - Agent · ReActConfig(max_iters，默认 20)　〔官方〕 + + + Workspace = Agent 执行环境 + Local / Docker / E2B　〔官方〕 + 安全 + .mcp（MCP 进程） + skills（动态） + data（卸载文件） + sessions（上下文） + 双轴注入 Agent： + ① 资源(tools/MCP/skills) → get_toolkit → Toolkit + ② 本身作 offloader（context 卸载） + → Agent 持有 Workspace 引用，不是嵌在里面 + 真正『跑在 Workspace 里』= MCP 进程 / skills / 文件 - - - ① reason - 推理(调 M3) + + ①资源→Toolkit + + ②offloader - - ② act - 调工具(沙箱) + + + 三层校验（不同工具包） + 质量 + + L1 硬约束：编译 / 启动 / 运行报错 + → 必须解决 · 循环 · 确定性工具（构建日志 / console error / CDP 错误捕获） + + L2 设计符合：玩法/关卡实现 vs 最新设计、UI 缺组件 + → 尽量解决 · 设计符合度校验工具 + + L3 效果：特效 / 画面美观 / 好不好玩 + → 只评分不解决 · M3 软检 · 绝不阻塞；初期只做 L1，L2/L3 渐进；用户可 HITL 要求继续解决任意层 - - ③ observe - 收产物+截图 + + + Event System（可观测） + 观测 + reply_stream → AgentEvent(text / thinking / tool / result) + → SSE 流给 cloud（可恢复 · 见图 2）+ TracingMiddleware → OTel → Studio - - ④ 验收裁决 - 过 / 修 / 熔断 - - - - - - - 未过 → repair 回环（同一 agent 持全局，不并行拆） - - · 收尾 = 模型产纯文本（不再调工具）；到 max_iters / 熔断触发 → 优雅收尾(ExceedMaxItersEvent) - · 四熔断：步数(max_iters·官方) / 预算(软刹官方+硬杀自建) / 卡死探测(自建) / 双超时(自建) - · 长程一致性：checkpoint(AgentState) + 半轮副作用幂等 - - 铁律：确定性归机器、绝不让 LLM 给自己打分；M3 软检永远不放行/不拒发（防 Goodhart） - - - - environment · 沙箱工作站（AgentScope sandbox） - 安全 - - - Filesystem - 写多文件 src/ 工程 - - - CODE - esbuild 构建 / shell - - - Browser - headless 真跑 + 截图 - - - CDP 探针　〔公共组件·双线〕 - 注入输入 / 帧 delta / 像素回读 / 活动 hash - - - 引擎能力包（Phaser，第一版硬编码） - 能装载工具 / RAG / skill；Pixi 后置抽接口 - - · 沙箱隔离 = 安全边界；官方 Browser 沙箱不暴露 page.evaluate → CDP 探针靠同容器 run_shell_command 自驱（自建） - · 硬代码=沙箱接线/权限硬上限；版本化审计=依赖锁/引擎版本/构建 profile；热配置=资源软配额 - - - - Model · AnthropicChatModel(M3)　〔官方〕 - 成本 - thinking_enable + thinking_budget（thinking 分离）→ AnthropicCredential.base_url = new-api `/v1/messages` + NEWAPI_KEY - 统一出口=new-api（协议不锁，Anthropic 原生）；约束 max_tokens > thinking_budget；自动配 AnthropicChatFormatter - - - - context · 运行时载荷 - 数据 - - - Memory（ReMe）〔官方〕 - 持久 + 向量/BM25 检索 + 压缩 - - - debug 案例库　〔自建·虚线〕 - 签名精确匹配，命中省一次 LLM - - - 源项目视图 / GDD - 错误史 / 预算状态 / 当前 src 切片 - - - prompt（⊂ context） - sys_prompt + agent skills（热配置） - - - - 双层验收门 - 质量 - - - ① 确定性硬门　〔公共组件·双线〕　→ 定 pass/fail · 零 LLM 自评 - 九门(引擎无关重写) + 跨表联动门 + 经济门 + latch；公共 CDP harness（泛化 Phaser） - - - ② M3 视觉软检 - 看好不好看 / 像不像题面 → 只产观测·告警·HITL 升级；绝不放行、绝不单独拒发 - - - - 运行时基础设施（production） - - - checkpoint：AgentState → Redis（可中断/恢复）〔数据·可靠〕 - - - 产物：结构化游戏源项目 → 落库 MySQL + OSS（内容哈希）〔数据〕 - - - 可观测：TracingMiddleware → OpenTelemetry → Studio(:3000)〔可观测〕 - - - - 进生成循环 - - - act - - 观测 - - - reason 调 M3 - - - 真跑产物 + 截图 → 验收 - - - 组装 context 载荷 → harness - - - 全绿 → 落库 / 观测 + + + 四层 = 职责视角（叠在上面的真实结构上，非并列模块） + environment = Workspace（执行环境：工作目录 + 工具 + 沙箱）　　harness = Agent ReAct 循环 + Middleware（控制面） + context = AgentState.context + 自动压缩 + offload　　prompt = sys_prompt + agent skills（热配置） - 生产维度图例（大厂生产环境关心） - - 安全：沙箱隔离 / 密钥(NEWAPI_KEY) / forbidden-import / 产物消毒 - 可观测：trace / token / cost → Studio - 可靠：四熔断 / checkpoint 恢复 / HITL - 成本：预算闸 + quota 台账 - 数据：状态(Redis) / 产物落库(MySQL+OSS) / 内容哈希 - 伸缩：create_app 多实例 / 多租户 / 会话隔离 - 质量：双层验收门（确定性 + 软检） - - - 复用边界图例 - - - 实线〔官方〕= AgentScope 生态现成直接用 - - 虚线〔自建〕= tier2 自己写（挂官方 Middleware / 薄层） - - 双线〔公共〕= 两条生成线共享的公共组件 - - - 映射设计档：自治富游戏引擎.md / tier2四层工程架构.md / tier2实现详设.md / agentic集成架构.md　|　基于 agentscope 2.0.3 源码实证　|　设计变动须同步本图 + 复用边界： + 实线〔官方〕 + 虚线〔自建〕 + 生产维度：可靠 / 安全 / 数据 / 可观测 / 质量（标在对应组件角） + 映射：tier2四层工程架构.md · 自治富游戏引擎.md　|　基于 agentscope 2.0.3 源码实证（Agent 双轴持有 Workspace · Agent 非常驻 · Middleware 洋葱）　|　设计变动须同步本图 diff --git a/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg b/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg index 3efa5c63..3a6ef01e 100644 --- a/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg +++ b/docs/architecture/架构/生成引擎/assets/04-ReAct循环流程.svg @@ -38,9 +38,9 @@ CDP 探针取证（公共） - 双层验收门 - 确定性硬门 pass/fail（零 LLM 自评） - + M3 视觉软检（只观测） + 三层校验 + L1 编译/运行 · L2 设计符合 + L3 效果（只评分·不阻塞） 产出：结构化游戏源项目 diff --git a/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg b/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg index 40a34950..ee303293 100644 --- a/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg +++ b/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg @@ -1,71 +1,75 @@ - + - - 图 6 · 复用边界全景（官方 / 自建 / 公共） - 原则：能用 AgentScope 官方现成就不自研；自建一律挂官方扩展点 / 薄层；公共组件两条生成线共享、不进 tier2 私有。 + + 图 6 · 复用边界（来源 × 共享范围） + 两个维度：来源（AgentScope 官方现成 vs 自建）× 共享范围（两线公共 vs tier2 私有）。关键纠正：「公共组件」其实是自建的共享件，不是现成的。 - - - AgentScope 生态官方现成 - 〔实线 · 直接用〕 + + + AgentScope 官方现成 + 〔实线 · 直接用 · 不算 tier2 自建资产〕 - · 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（定时 · 托管密钥） + · Message & Event System（typed stream：text/thinking/tool/result） + · Agent（无状态 ReAct 引擎 + 工具并发执行） + · ReActConfig(max_iters) + ModelConfig(fallback 回退) + · Model（9 provider + thinking + generate_structured_output） + · Context（自动压缩 + offload + tool 结果截断） + · Tool（Toolkit + 内置工具 + ToolGroup + 并发标志） + · MCP 集成（stdio / HTTP） + · Permission System（5 mode + HITL 中断/恢复） + · Middleware（6 hook + 内置 Budget/Mem0/Tracing/TTS） + · Workspace（Local / Docker / E2B 执行环境） + · State / Session（AgentState + 持久化 Redis/PG） + · Agent Service（REST + SSE · 8 router · storage · MessageBus） + · Schedule（cron）+ Credential（托管密钥） + · Agent Team（leader-worker 多 agent · 星形） + · Embedding / Formatter / Skill / Exception + + + 官方没有（别误判去找）： + · 无独立 RAG / 向量检索层（仅 Mem0 / ReMe 长期记忆） + · 无 evaluate / benchmark 模块（1.x 的已移除） + · A2A 仅基座（AG-UI 有成品 AGUIProtocolMiddleware） + 该删（之前误标自建 → 改用官方）： + token 计量 / 软预算 / 结构化调用 / OTel / 经验存储召回 / 多 agent 总线 + + + + 自建 · 两线公共 + 〔双线 · 两条生成线共享 · 是自建的、不是现成〕 + + · 确定性九门（在真浏览器真玩一遍判能不能玩） + · 三层校验工具：L1 编译/运行错误 · L2 设计符合度 · L3 效果评分 + · CDP 低层探针（注入输入 / 帧 delta / 像素回读 / 活动 hash） + · 计费台账（读 new-api quota → ¥） + · 送审 / 审核台　·　feed / 发布 + · trace 契约（公共核心子集 + 各线扩展段） + + 为什么公共：两条生成线产物都要计费/送审/进同一 feed、都靠同一套确定性验收判能玩 → 抽共享，不重复造。 + + + + 自建 · tier2 私有 + 〔虚线 · 挂官方扩展点 / 薄层〕 + 通用 agent 治理层（框架不提供）： + + · 墙钟超时 + fail-closed 硬熔断（官方只软刹） + · 卡死 / 无进展探测 + · ¥成本台账（挂 ModelCallEndEvent · token×单价） + · finish 接线（自治跑完 → 吐结构化游戏定义） + · 错误签名精确命中层（ReMe 当存储/召回底座） + · 两阶段编排策略（Agent Team leader 的拆解+调度提示） + + 游戏专属（与框架正交）： + + · Phaser 引擎适配 / 能力包 + · tier2 源项目契约（建议与 finish schema 共用一份，避免漂移） - - - 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 源码实证　|　设计变动须同步本图 + 映射：tier2四层工程架构.md §8 · agentic集成架构.md　|　基于 agentscope 2.0.3 源码逐项核对（哪些官方已有/哪些真自建）　|　设计变动须同步本图