diff --git a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md index 813b5ece..f495cb6e 100644 --- a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md +++ b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md @@ -1,22 +1,22 @@ # tier2 agentic 运行时架构图说 -> 🚧 评审版 · **9 张图**（6 svg + 3 mermaid）· 已纳入创始人 4 问校正（见 §5）。 -> **这是什么**：tier2 自治富游戏生成轨——agentic 这条线的「看图入口」。把「编排 → 启动 → 调用 → 运行时 → 返回结果」整条生命周期、它在系统里的位置、内部怎么转，用一套图讲清。复杂重要的用 svg/png 高保真大图，简单的用 mermaid。颗粒度面向 vibecoding。 +> 🚧 评审版 · **9 张图**（6 svg + 3 mermaid）· 已纳入创始人两轮共 8 点反馈校正（见 §5）。 +> **这是什么**：tier2 自治富游戏生成轨——agentic 这条线的「看图入口」。把「编排 → 启动 → 调用 → 运行时 → 返回」整条生命周期、它在系统里的位置、内部怎么转，用一套图讲清。复杂重要的 svg 大图，简单的 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、无转换器）。 +- **映射设计档**：本图说只把《[自治富游戏引擎](自治富游戏引擎.md)》《[tier2 四层工程架构](tier2四层工程架构.md)》《[tier2 实现详设](tier2实现详设.md)》《[agentic 集成架构](agentic集成架构.md)》画出来。机制以 **agentscope 2.0.3 源码实证**为准（`/root/oss/agentscope`，逐条核过）。 +- **同步纪律**：设计一变动，本图说与对应 svg 必须同步更新（已并入 wave 收口清单）。 +- **产物**：svg 入仓（GitHub/编辑器渲染矢量），png 在 mini-desktop 转。 ## 1. 全图通用图例 -**生产维度**（大厂生产环境关心）：安全（Workspace 隔离/密钥/产物消毒）、可观测（Event System → OTel → Studio）、可靠（四熔断/checkpoint/HITL/durable/fallback）、成本（预算软刹+硬杀/quota 台账）、数据（AgentState/落库/哈希）、伸缩（多实例/多租户/会话隔离）、质量（三层校验）。 - -**复用边界（二维 · 见图 6）**：来源（**官方现成** vs **自建**）× 共享范围（**两线公共** vs **tier2 私有**）。⚠️「公共组件」是**自建的共享件、不是现成的**。 +**生产维度**：安全 / 可观测 / 可靠 / 成本 / 数据 / 伸缩 / 质量（标在对应组件）。 +**复用边界（二维 · 图 6）**：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。⚠️公共组件是**自建的共享件、非现成**。 +**自治范式**：骨架 = 自治 loop（怎么走）+ task/goal 清单（走向哪、走到哪）+ Agent Team 动态调度（谁来走），**没有 workflow DAG**（见图 A 注 + §5b）。 ## 2. 图集 @@ -24,35 +24,35 @@ ![图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 工作室**用 Agent Team 星形：leader 分析+拆解用户意图、`AgentCreate` 出玩法/关卡/数值/UI/音乐/特效/资产设计 worker 发散，TeamSay 汇 leader 收敛成设计结论。**这阶段是只读 + 对话**——设计 worker 用 `PermissionMode.EXPLORE` **只读已有工程代码 + 工程内设计文档**（迭代已有游戏时），并与用户**跨 session 多轮对话**。**阶段 2 单写实现**：① **模板代码初始化是这阶段的工具**（从模板铺工程骨架）② 把阶段 1 每个设计 agent 的结论**写成工程内文档** ③ 单写 agent 写代码 ④ 三层校验 ⑤ 产出。**闭环**：阶段 2 写进 repo 的文档/代码 → 下次迭代阶段 1 只读它再设计（设计文档 in repo、改源不改包，正是「游戏=长生命周期项目」）。设计用多 agent（发散/专业），实现用单写（防并行写冲突）。 ### 图 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/验收基线」这些**公共组件**上交汇。 +tier2 agentic 是独立 service，game-cloud 经官方 **Agent Service（REST + SSE）**调它；service 内是「工作室 Agent Team → 单写」；它经 new-api 调模型、用 Workspace 干活、落 Redis/MySQL/OSS、trace 进 Studio；与 SAA 廉价线**运行期零耦合**，只在公共组件（计费/送审/feed/验收基线）交汇。 -### 图 2 · 调用时序（cloud ↔ agentic） +### 图 2 · 调用时序（含 session 初始化与两阶段） ![图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 + 产物引用）。 +**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 真实对象结构） ![图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）」只是**职责视角**，叠在这个真实结构上，不是并列模块。 +按 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 循环流程（一轮迭代） ![图4 ReAct循环流程](assets/04-ReAct循环流程.svg) -把图 3 中心那个循环展开成一轮：组装 context → reason 调 M3 → 判断「调工具还是收尾」→ 调工具就去 Workspace 写码/构建/真跑、CDP 取证、过**三层校验**，没过回 repair。模型产纯文本即收尾、出产物。右侧四熔断任一触发即优雅收尾，每轮 checkpoint。 +一轮：组装 context → reason 调 M3 → 判断「调工具 or 收尾」→ 调工具去 Workspace 写码/构建/真跑、CDP 取证、过三层校验，没过 repair。模型产纯文本即收尾。四熔断任一触发优雅收尾，每轮 checkpoint。 ### 图 5 · 编排与配置结构 -「编排」= 写一次代码骨架（`create_app` + 组装 Agent 的 model/toolkit/middleware/memory/react_config），「配置」= 三类外置（机制硬代码、安全/构建走版本化审计、策略热改不发版）。 +「编排」= 写一次代码骨架（`create_app` + 组装 Agent），「配置」= 三类外置（机制硬代码 / 安全·构建版本化审计 / 策略热改不发版）。 ```mermaid flowchart TB @@ -66,24 +66,22 @@ flowchart TB AG --> RC["react_config：max_iters"] end subgraph 配置["配置外置（三类）"] - H["硬代码·机制
门断言 / 熔断 / 权限上限"] - V["版本化·审计
依赖锁 / 引擎版本 / 构建 profile / 沙箱类型"] - HOT["热配置·策略
prompt / 模型路由 / 阈值 / RAG 源"] + H["硬代码·机制：门断言 / 熔断 / 权限上限"] + V["版本化·审计：依赖锁 / 引擎版本 / 构建 profile / 沙箱类型"] + HOT["热配置·策略：prompt / 模型路由 / 阈值 / RAG 源"] end APP --> AG HOT -. 改配置不发版 .-> AG ``` -### 图 6 · 复用边界（来源 × 共享范围） +### 图 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 总线——都改用官方），把自研面缩到最小。 +二维：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。左列官方现成（十几组，直接用、非 tier2 资产）。右上自建的**两线公共件**（九门/三层校验/CDP/计费/送审/feed/trace，自建但共享）。右下 tier2 私有自建。**每个自建项标了载体类型**——用 AgentScope 哪种扩展点做：`Tool`（工具函数）/ `Middleware`（hook 拦截）/ `Skill`（SKILL.md）/ `Prompt`（指令）/ `Memory`（ReMe）/ `Schema`（契约）/ 框架外独立。还标了「官方没有」（RAG/evaluate/A2A 基座）和「该删→改官方」6 项。 ### 图 7 · 产物与契约 -返回的是**结构化源项目**（改源不改包、重新构建），由源项目契约钉住文件树/构建/依赖/落库；过程由 trace 契约记录。 - ```mermaid flowchart TB subgraph SP["tier2 源项目契约（落库取回）"] @@ -109,7 +107,7 @@ classDiagram class TimeoutMiddleware class StuckDetectMiddleware class AnthropicChatModel { +thinking_enable +credential.base_url } - class AgentState { +cur_iter +context } + class AgentState { +cur_iter +context +tasks_context } class WorkspaceBase Agent --> ReActConfig Agent --> Toolkit @@ -133,13 +131,13 @@ classDiagram | # | 图 | 形式 | 状态 | |---|---|---|---| -| A | 生成两阶段（工作室→单写） | svg | ✅ 新增 | -| 1 | 系统全景 / 部署 | svg | ✅ | -| 2 | 调用时序（cloud↔agentic） | svg | ✅ | -| 3 | 运行时内部（真实对象结构） | svg | ✅ 重画 | -| 4 | 单写 ReAct 循环流程 | svg | ✅ | +| A | 生成两阶段（工作室→单写·闭环） | svg | ✅ | +| 1 | 系统全景（含 Team） | svg | ✅ | +| 2 | 调用时序（session 三路径 + 两阶段） | svg | ✅ | +| 3 | 运行时内部（真实结构 + goal/task） | svg | ✅ | +| 4 | 单写 ReAct 循环流程（三层） | svg | ✅ | | 5 | 编排与配置 | mermaid | ✅ | -| 6 | reuse 边界（二维） | svg | ✅ 重做 | +| 6 | reuse 边界（二维 + 载体类型） | svg | ✅ | | 7 | 产物与契约 | mermaid | ✅ | | 8 | 关键类图 | mermaid | ✅ | @@ -147,26 +145,34 @@ classDiagram | 层 | 内容 | 处置 | 工具包 | |---|---|---|---| -| **L1 硬约束** | 编译报错 / 启动报错 / 运行错误日志 | **必须解决 · 循环** | 确定性：构建日志 / console error / CDP 错误捕获（九门多数落此） | -| **L2 设计符合** | 玩法/关卡实现 vs 最新设计、UI 缺组件 | **尽量解决** | 设计符合度校验（部分九门：机制进展） | -| **L3 效果** | 特效 / 画面美观 / 好不好玩 | **只评分不解决** | M3 视觉软检（绝不阻塞、绝不拒发） | +| **L1 硬约束** | 编译/启动/运行错误日志 | **必须解决 · 循环** | 确定性：构建日志/console/CDP 错误捕获（九门多数落此） | +| **L2 设计符合** | 玩法/关卡实现 vs 设计、UI 缺组件 | **尽量解决** | 设计符合度校验（部分九门：机制进展） | +| **L3 效果** | 特效/美观/好不好玩 | **只评分不解决** | M3 视觉软检（绝不阻塞/拒发） | -**迭代原则**：初期只识别硬问题（L1），L2/L3 渐进完善；**绝不让效果问题阻塞真问题**；用户可经 HITL 发消息要求继续解决任意层。 +**迭代原则**：初期只识别硬问题（L1），L2/L3 渐进；**绝不让效果问题阻塞真问题**；用户可经 HITL 要求继续解决任意层。 -## 5. 关键校正记录（创始人 4 问 · 2026-06-22） +## 5. 校正记录（创始人反馈 · 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）。 +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**（LocalWorkspace / DockerWorkspace / E2BWorkspace），经 Toolkit + offloader 双轴接入 Agent | -| API / Session 层 | **Agent Service**（REST + SSE，`/sessions` 等；Agent 非常驻） | +| 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） | -| 工作室多 agent | **Agent Team**（leader-worker 星形 · TeamCreate/AgentCreate/TeamSay） | diff --git a/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg b/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg index f590167f..1195028f 100644 --- a/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg +++ b/docs/architecture/架构/生成引擎/assets/00-生成两阶段.svg @@ -1,94 +1,94 @@ - + + - - 图 A · 生成两阶段：工作室（多 agent 设计）→ 单写（实现） - AgentScope Agent Team 星形：leader 拆解+调度，多专业设计 worker 发散；再交单写 agent 实现。设计用多 agent（发散·专业分工），实现用单写（防并行写冲突）。 + + 图 A · 生成两阶段：工作室（只读·设计）→ 单写（写文档·实现） + 阶段 1 多 agent 只读设计 + 跨 session 对话；阶段 2 单写实现 + 把设计写成工程内文档。设计文档 in repo，下次迭代阶段 1 再只读它 → 闭环（游戏=长生命周期项目）。 - - - 阶段 1 · 游戏工作室（Agent Team 星形） + + + 用户（跨 session 多轮对话：新建 / 迭代已有游戏） - - 一句话 brief + play_spec + + + 阶段 1 · 工作室（只读 · 对话 · 设计） + PermissionMode.EXPLORE 只读　·　Agent Team 星形 - - leader agent - 意图分析 + 拆解 - + 调度 + 收敛 + + leader + 意图分析 + 拆解 + + 调度 + 收敛 - + + 跨 session 对话 - - 玩法设计 worker - 关卡设计 worker - 数值/机制设计 worker - UI 设计 worker - 音乐 / 音效设计 worker - 特效设计 worker - 资产设计 worker + 玩法设计 worker + 关卡设计 worker + 数值 / 机制设计 worker + UI 设计 worker + 音乐 / 音效设计 worker + 特效设计 worker · 资产设计 worker - - - - - - - - + + + + - · 基于玩法模板 prompt + 工程初始化模板 - · worker 不互连（星形）· - TeamSay 收发汇 leader + + leader 收敛 → 各 agent 设计结论（修改意图 / 新建） + 只读已有工程代码 + 工程内设计文档/结论（迭代时）→ 产出 GDD / 各维度设计 + worker 不互连（星形）· TeamSay 汇 leader + Agent Team 工具：TeamCreate / AgentCreate / TeamSay / TeamDelete - - leader 收敛 → 结构化设计 - GDD（玩法/胜负/机制）+ 关卡/数值表 + UI 规格 + 音乐音效/特效设计 - + 资产清单 + 工程骨架初始化（玩法模板代码脚手架） - Agent Team 工具：TeamCreate / AgentCreate（派生 worker）/ TeamSay / TeamDelete · 经 MessageBus 异步驱动 + + + 阶段 2 · 单写实现（写文档 · 初始化 · 写代码） + 可写权限　·　单写 agent + + + ① 模板代码初始化（工具：从模板铺工程骨架） + + ② 写工程内文档（记录每个设计 agent 的结论） + + ③ 单写 agent · ReAct 写代码（运行时 → 图 3） + + ④ 三层校验（L1 必须 / L2 尽量 / L3 评分）· 未过 repair + + ⑤ 产出结构化游戏源项目 + + + + + + 模板初始化是阶段 2 的工具（不是阶段 1）；每个设计结论落 repo 文档，供下次迭代只读 - - 移交结构化设计 - + 工程骨架 + + 移交设计结论 - - - 阶段 2 · 单写实现 + + + 游戏工程仓 repo（长生命周期 · 改源不改包） + 源代码　+　设计文档（in repo：每个设计 agent 的结论） + → 阶段 2 写入；阶段 1 下次迭代只读它做修改设计 + 闭环：写 → 读 → 再设计 → 再写 - - 结构化设计（GDD + 各维度 + 工程骨架） - 阶段 1 的产物，作为单写 agent 的输入 + + ① 阶段1 只读 + 代码 + 文档 + + ② 阶段2 写 + 文档 + 代码 - - 单写 agent（实现） - ReAct 循环写代码（运行时内部 → 图 3） - - - 三层校验（L1 必须 / L2 尽量 / L3 评分） - 未过 → repair 回环 - - - 产出：结构化游戏源项目 - → 落库 MySQL + OSS - - - - - - - - 为什么这样分两阶段： - · 设计阶段是发散、各专业不共享代码状态 → 多 agent 并行最优 - · 实现阶段多系统共享同一套代码/约定 → 单写防不一致 - 　（曾把 Flappy 拆并行写，背景跑成了马里奥） - - 映射：自治富游戏引擎.md（单写者）· tier2实现详设.md · agentic集成架构.md　|　基于 agentscope 2.0.3 Agent Team 源码实证　|　设计变动须同步本图 + workflow：两阶段 = Agent Team 动态调度 + 自治 loop，非 workflow DAG（AgentScope 无显式 workflow 原语）；「给用户用的 workflow 能力」是未来需求、另议（图说 §5b）。 + 建 session 三种加载入口（续会话 / 加载已有工程 / 加载模板）见图 2。　映射：自治富游戏引擎.md · agentic集成架构.md · generation-lifecycle-project-model　|　设计变动须同步本图 diff --git a/docs/architecture/架构/生成引擎/assets/01-系统全景.svg b/docs/architecture/架构/生成引擎/assets/01-系统全景.svg index baccb011..770f88b5 100644 --- a/docs/architecture/架构/生成引擎/assets/01-系统全景.svg +++ b/docs/architecture/架构/生成引擎/assets/01-系统全景.svg @@ -39,8 +39,8 @@ Agent Service（REST + SSE） 多租户 · 会话 · HITL · 取消 · /sessions /chat /schedule - 单写者 ReAct 循环（详见图 3） - Agent + ReActConfig + Middleware 熔断 + 四层载荷 + 工作室 Agent Team → 单写实现（图 A / 3） + 阶段1 leader+设计worker(星形) · 阶段2 单写 agent Model 适配 → new-api diff --git a/docs/architecture/架构/生成引擎/assets/02-调用时序.svg b/docs/architecture/架构/生成引擎/assets/02-调用时序.svg index 1d65574c..87730d24 100644 --- a/docs/architecture/架构/生成引擎/assets/02-调用时序.svg +++ b/docs/architecture/架构/生成引擎/assets/02-调用时序.svg @@ -1,95 +1,76 @@ - + - - 图 2 · 调用时序（cloud ↔ agentic） - cloud 直接用官方 Agent Service：REST 建会话 + SSE 收流式 Event；durable session 可恢复、可取消、支持 HITL。蓝色虚线 = SSE 事件流。 + + 图 2 · 调用时序（cloud ↔ agentic · 含 session 初始化与两阶段） + cloud 用官方 Agent Service（REST + SSE）。建 session 三种加载入口；阶段 1 工作室 Agent Team 设计 → 阶段 2 单写实现。蓝虚线 = SSE 事件流。 - - game-cloud（Java） - 调用方 - - Agent Service〔官方〕 - REST + SSE · 多租户 · durable - - 运行时（单写者循环） - Agent + Middleware - - 依赖 - new-api · Workspace · 存储 · Studio + game-cloud + Agent Service〔官方〕REST+SSE · durable · Team + 运行时（Team + 单写） + 依赖：new-api·Workspace·存储 - - - - - + + + + - - - ① POST /sessions（brief + play_spec） - - ② 201 · session_id（durable 持久会话） - - ③ GET /sessions/{id}/events（SSE 订阅） - - ④ 启动单写者 run + + ① POST /sessions（brief + play_spec · mode：新建/迭代/续接） - - - ReAct 循环 ×N（每轮详见图 3 / 图 4） + + + ② session 初始化（三选一加载） + · 续接之前会话：取 SessionRecord.state（历史对话 + 上次进度，durable resume） + · 加载已有游戏工程：Workspace.workdir 指向已有工程目录（→ 迭代/修改） + · 新建：阶段 2 用模板初始化工具把游戏模板铺进 Workspace + （durable session + Workspace workdir 都是官方现成） - - ⑤ 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 + + ③ 201 · session_id + SSE 订阅 + + + + 阶段 1 · 工作室（Agent Team 星形 · 只读 EXPLORE） + ④ 启动 leader（意图分析 + 拆解） + ⑤ leader 只读 workspace（已有代码 + 工程内文档） + ⑥ AgentCreate 设计 worker（玩法/关卡/数值/UI/音乐/特效/资产） + ⑦ TeamSay 汇 leader → 收敛设计结论（GDD/各维度） + ⑧ 设计结论写入 repo 文档（供下次只读） + + + + 阶段 2 · 单写实现（ReAct loop ×N · 每轮详见图 3 / 图 4） + ⑨ 模板初始化（新建时铺工程骨架） + ⑩ reason → new-api（M3 /v1/messages，thinking） + ⑪ act → Workspace（写码 / esbuild / headless 真跑） + ⑫ CDP 探针 → 三层校验（L1 必须 / L2 尽量 / L3 评分） + ⑬ checkpoint → Redis（durable） + ⑭ Event（thinking/tool/result） + ⑮ SSE event-stream（resumable · 断线 replay）+ OTel→Studio - - HITL（可选）：运行时挂起 → RequireUserConfirm（经 SSE 推 cloud）→ cloud POST /sessions/{id} 确认/编辑参数 → 从暂停处精确恢复 + + HITL（任意阶段）：挂起 → RequireUserConfirm（SSE 推 cloud）→ cloud POST /sessions/{id} 确认/编辑 → 精确恢复；用户可要求继续解决 L1/L2/L3 任意层 - - ⑭ 产物落库 → MySQL + OSS（内容哈希） - - ⑮ 完成 event：verdict + 产物引用 - - ⑯ 取产物 → 进 feed + ⑯ 产物落库 → MySQL + OSS（内容哈希） + ⑰ 完成 event：verdict + 产物引用 + ⑱ 取产物 → 进 feed - - 异常 / 生产路径： - 超时/熔断 → 优雅收尾(ExceedMaxItersEvent) · cloud 取消 session · provider 瞬时失败 graceful fallback · /schedule 定时 run · /credential 托管密钥 + + 异常 / 生产：超时·熔断→优雅收尾 · cloud 取消 session · provider 失败 graceful fallback · /schedule 定时 · /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）源码实证　|　设计变动须同步本图 + REST 请求 / 动作 + SSE 事件流（可恢复） + 映射：agentic集成架构.md · tier2实现详设.md｜基于 agentscope 2.0.3 Agent Service + Agent Team 源码实证｜设计变动须同步本图 diff --git a/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg b/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg index 54dad230..e93fe4c9 100644 --- a/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg +++ b/docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg @@ -109,7 +109,7 @@ 四层 = 职责视角（叠在上面的真实结构上，非并列模块） environment = Workspace（执行环境：工作目录 + 工具 + 沙箱）　　harness = Agent ReAct 循环 + Middleware（控制面） - context = AgentState.context + 自动压缩 + offload　　prompt = sys_prompt + agent skills（热配置） + context = AgentState.context + tasks_context（goal→TODO 追踪 · TaskCreate/Update）+ 压缩/offload　　prompt = sys_prompt + agent skills 复用边界： diff --git a/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg b/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg index ee303293..59c474dc 100644 --- a/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg +++ b/docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg @@ -1,75 +1,79 @@ - + - - 图 6 · 复用边界（来源 × 共享范围） - 两个维度：来源（AgentScope 官方现成 vs 自建）× 共享范围（两线公共 vs tier2 私有）。关键纠正：「公共组件」其实是自建的共享件，不是现成的。 + + 图 6 · 复用边界（来源 × 共享范围 · 自建项标载体类型） + 维度：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。自建项后的〔徽章〕= 用 AgentScope 哪种扩展点做（看明白在哪做什么）。公共组件是自建的共享件、非现成。 - - AgentScope 官方现成 - 〔实线 · 直接用 · 不算 tier2 自建资产〕 + + AgentScope 官方现成（直接用） - · 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 + · Message & Event System（typed stream） + · Agent（无状态 ReAct 引擎 + 工具并发） + · ReActConfig(max_iters) + ModelConfig(fallback) + · Model（9 provider + thinking + 结构化输出） + · Context（自动压缩 + offload + 截断） + · 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 + tasks_context） + · Agent Service（REST + SSE · 8 router · MessageBus） + · Agent Team（leader-worker 星形多 agent） + · Schedule（cron）+ Credential（托管密钥） + · Embedding / Formatter / Skill / Exception - - 官方没有（别误判去找）： - · 无独立 RAG / 向量检索层（仅 Mem0 / ReMe 长期记忆） - · 无 evaluate / benchmark 模块（1.x 的已移除） - · A2A 仅基座（AG-UI 有成品 AGUIProtocolMiddleware） - 该删（之前误标自建 → 改用官方）： - token 计量 / 软预算 / 结构化调用 / OTel / 经验存储召回 / 多 agent 总线 + + 官方没有（别误判去找）： + · 无独立 RAG / 向量检索（仅 Mem0 / ReMe 长期记忆） + · 无 evaluate 模块 · A2A 仅基座 + 该删（之前误标自建 → 改官方）： + token 计量 / 软预算 / 结构化调用 / OTel / + 经验存储召回 / 多 agent 总线 + 官方能力是「框架给的」，不算 tier2 自建资产 - - 自建 · 两线公共 - 〔双线 · 两条生成线共享 · 是自建的、不是现成〕 + + 自建 · 两线公共（自建的共享件，非现成） - · 确定性九门（在真浏览器真玩一遍判能不能玩） - · 三层校验工具：L1 编译/运行错误 · L2 设计符合度 · L3 效果评分 - · CDP 低层探针（注入输入 / 帧 delta / 像素回读 / 活动 hash） - · 计费台账（读 new-api quota → ¥） - · 送审 / 审核台　·　feed / 发布 - · trace 契约（公共核心子集 + 各线扩展段） + · 确定性九门（真浏览器真玩判能玩）　〔Tool + 独立 harness〕 + · 三层校验工具：L1 编译/运行 · L2 设计符合 · L3 效果　〔Tool〕 + · CDP 低层探针（注入/帧/像素/hash）　〔Tool / 脚本〕 + · 计费台账（new-api quota → ¥）　〔Middleware〕 + · 送审 / 审核台 · feed / 发布　〔框架外独立服务〕 + · trace 契约（核心子集 + 扩展段）　〔Schema〕 - 为什么公共：两条生成线产物都要计费/送审/进同一 feed、都靠同一套确定性验收判能玩 → 抽共享，不重复造。 + 为什么公共：两线产物都要计费/送审/进同一 feed、都靠同一套确定性验收判能玩 → 抽共享、不重复造。 + 为什么不是现成：AgentScope 不提供游戏验收/计费/发行，这些是项目自建、只是两线共用。 - - 自建 · tier2 私有 - 〔虚线 · 挂官方扩展点 / 薄层〕 - 通用 agent 治理层（框架不提供）： + + 自建 · tier2 私有（挂官方扩展点 / 薄层） + 通用 agent 治理层： - · 墙钟超时 + fail-closed 硬熔断（官方只软刹） - · 卡死 / 无进展探测 - · ¥成本台账（挂 ModelCallEndEvent · token×单价） - · finish 接线（自治跑完 → 吐结构化游戏定义） - · 错误签名精确命中层（ReMe 当存储/召回底座） - · 两阶段编排策略（Agent Team leader 的拆解+调度提示） + · 超时 / 卡死 / fail-closed 硬熔断　〔Middleware：on_reasoning/on_model_call〕 + · ¥成本台账　〔Middleware：订阅 ModelCallEndEvent〕 + · finish 接线（吐结构化游戏定义）　〔Tool：参数 schema=源项目契约〕 + · 错误签名精确命中层　〔Tool + Memory(ReMe) 底座〕 + · 两阶段编排策略　〔Prompt：leader 调度 + Agent Team 工具〕 - 游戏专属（与框架正交）： + 游戏专属（与框架正交）： - · Phaser 引擎适配 / 能力包 - · tier2 源项目契约（建议与 finish schema 共用一份，避免漂移） + · Phaser 引擎适配 / 能力包　〔Skill：SKILL.md + Tool：写/构建〕 + · tier2 源项目契约（与 finish schema 共用一份）　〔Schema〕 - 映射：tier2四层工程架构.md §8 · agentic集成架构.md　|　基于 agentscope 2.0.3 源码逐项核对（哪些官方已有/哪些真自建）　|　设计变动须同步本图 + + + 载体类型（AgentScope 扩展点）： + Tool=工具函数　Middleware=hook 拦截　Skill=SKILL.md　Prompt=指令　Memory=ReMe　Schema=契约数据　独立=框架外 + + 映射：tier2四层工程架构.md §8 · agentic集成架构.md　|　基于 agentscope 2.0.3 源码逐项核对（官方已有/真自建 + 载体类型）　|　设计变动须同步本图