d8adc3d0d4
2.0.3 从未发布到 PyPI(最新 2.0.2),requirements.txt 的 ==2.0.3 不可安装。已在 mini-desktop venv 实装 2.0.2 并冒烟:Agent/ReActConfig/Toolkit/FunctionTool/Anthropic*/MCP(Stdio+Http)/create_app(Agent Service)/AgentState/workspace/middleware/event/skill 全在——设计依赖符号对 2.0.2 成立。 活层(docs/tier2/.agents)agentscope 2.0.3→2.0.2:文档+SVG+requirements.txt+knowledge facts(改名 agentscope-2.0.2-facts.md);npm lockfile 第三方 2.0.3 未动。复验 SVG 32 张全过。 注:6c6g 克隆 /root/oss/agentscope 实为 2.0.3-dev(领先 PyPI),与 2.0.2 架构一致(符号已对)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
188 lines
14 KiB
Markdown
188 lines
14 KiB
Markdown
# tier2 agentic 运行时架构图说
|
||
|
||
> 🚧 评审版 · **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.2 源码实证**为准（`/root/oss/agentscope`，逐条核过）。
|
||
- **同步纪律**：设计一变动，本图说与对应 svg 必须同步更新（已并入 wave 收口清单）。
|
||
- **产物**：svg 入仓（GitHub/编辑器渲染矢量），png 在 mini-desktop 转。
|
||
- **细节族图说（本图说之下的放大层）**：本篇是整轨的「看图入口」（9 张总览图）；要看某一面的逐项细节，下钻这八份按族拆的细节图说（全八族已建，共 32 张细图，均为本总览的逐项放大、deepen 不 duplicate）：
|
||
- [A 族 · 运行时形态](tier2细节图说-A-运行时形态.md)——Agent Service 与 session 三路径、Agent 非常驻 + AgentState、Workspace 双轴注入、Middleware 洋葱。
|
||
- [C 族 · 单写 ReAct 循环](tier2细节图说-C-单写ReAct循环.md)——ReAct 一轮 / 多轮自治、M3 Anthropic 原生接法、四道熔断 + 预算闸、承 amodel-gen 范式。
|
||
- [D 族 · 三层校验与九门](tier2细节图说-D-三层校验与九门.md)——三层校验全景、九门逐门、富游戏专属门、advisory 分级 + Goodhart 隔离、CDP 探针 Phaser 重写。
|
||
- [E 族 · 能力面（skills 与 prompt）](tier2细节图说-E-能力面skills与prompt.md)——toolkit 九工具、引擎能力包五件套、prompt 两阶段角色、A-model 4 插件复用。
|
||
- [F 族 · 源项目契约与装载](tier2细节图说-F-源项目契约与装载.md)——源项目契约七要素四组、第二装载分支、finish 工具共用 schema。
|
||
- [G 族 · 0号 spike runbook](tier2细节图说-G-spike-runbook.md)——建设五步 + 生死门、mini-肥鹅靶子、模型矩阵 + 跑序、过门阈值 + 采集字段、两段实施 + 退路树。
|
||
- [B 族 · 控制面与管理面](tier2细节图说-B-控制面与管理面.md)——控制面四组件、反锁死五协议、预算三层强制、管理面三 phase。
|
||
- [H 族 · 观测与成本](tier2细节图说-H-观测与成本.md)——trace 统一契约、观测管道（Event→OTel→Studio）、成本台账。
|
||
|
||
## 1. 全图通用图例
|
||
|
||
**生产维度**：安全 / 可观测 / 可靠 / 成本 / 数据 / 伸缩 / 质量（标在对应组件）。
|
||
**复用边界（二维 · 图 6）**：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。⚠️公共组件是**自建的共享件、非现成**。
|
||
**自治范式**：骨架 = 自治 loop（怎么走）+ task/goal 清单（走向哪、走到哪）+ Agent Team 动态调度（谁来走），**没有 workflow DAG**（见图 A 注 + §5b）。
|
||
|
||
## 2. 图集
|
||
|
||
### 图 A · 生成两阶段（工作室设计 → 单写实现）
|
||
|
||
|
||
|
||
两阶段。**阶段 1 工作室**用 Agent Team 星形：leader 分析+拆解用户意图、`AgentCreate` 出玩法/关卡/数值/UI/音乐/特效/资产设计 worker 发散，TeamSay 汇 leader 收敛成设计结论。**这阶段是只读 + 对话**——设计 worker 用 `PermissionMode.EXPLORE` **只读已有工程代码 + 工程内设计文档**（迭代已有游戏时），并与用户**跨 session 多轮对话**。**阶段 2 单写实现**：① **模板代码初始化是这阶段的工具**（从模板铺工程骨架）② 把阶段 1 每个设计 agent 的结论**写成工程内文档** ③ 单写 agent 写代码 ④ 三层校验 ⑤ 产出。**闭环**：阶段 2 写进 repo 的文档/代码 → 下次迭代阶段 1 只读它再设计（设计文档 in repo、改源不改包，正是「游戏=长生命周期项目」）。设计用多 agent（发散/专业），实现用单写（防并行写冲突）。
|
||
|
||
### 图 1 · 系统全景 / 部署
|
||
|
||
|
||
|
||
tier2 agentic 是独立 service，game-cloud 经官方 **Agent Service（REST + SSE）**调它；service 内是「工作室 Agent Team → 单写」；它经 new-api 调模型、用 Workspace 干活、落 Redis/MySQL/OSS、trace 进 Studio；与 SAA 廉价线**运行期零耦合**，只在公共组件（计费/送审/feed/验收基线）交汇。
|
||
|
||
### 图 2 · 调用时序（含 session 初始化与两阶段）
|
||
|
||
|
||
|
||
**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 真实对象结构）
|
||
|
||
|
||
|
||
按 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 循环流程（一轮迭代）
|
||
|
||
|
||
|
||
一轮：组装 context → reason 调 M3 → 判断「调工具 or 收尾」→ 调工具去 Workspace 写码/构建/真跑、CDP 取证、过三层校验，没过 repair。模型产纯文本即收尾。四熔断任一触发优雅收尾，每轮 checkpoint。
|
||
|
||
### 图 5 · 编排与配置结构
|
||
|
||
「编排」= 写一次代码骨架（`create_app` + 组装 Agent），「配置」= 三类外置（机制硬代码 / 安全·构建版本化审计 / 策略热改不发版）。
|
||
|
||
```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["硬代码·机制：门断言 / 熔断 / 权限上限"]
|
||
V["版本化·审计：依赖锁 / 引擎版本 / 构建 profile / 沙箱类型"]
|
||
HOT["热配置·策略：prompt / 模型路由 / 阈值 / RAG 源"]
|
||
end
|
||
APP --> AG
|
||
HOT -. 改配置不发版 .-> AG
|
||
```
|
||
|
||
### 图 6 · 复用边界（来源 × 共享 · 自建项标载体类型）
|
||
|
||
|
||
|
||
二维：来源（官方现成 vs 自建）× 共享（两线公共 vs tier2 私有）。左列官方现成（十几组，直接用、非 tier2 资产）。右上自建的**两线公共件**（九门/三层校验/CDP/计费/送审/feed/trace，自建但共享）。右下 tier2 私有自建。**每个自建项标了载体类型**——用 AgentScope 哪种扩展点做：`Tool`（工具函数）/ `Middleware`（hook 拦截）/ `Skill`（SKILL.md）/ `Prompt`（指令）/ `Memory`（ReMe）/ `Schema`（契约）/ 框架外独立。还标了「官方没有」（RAG/evaluate/A2A 基座）和「该删→改官方」6 项。
|
||
|
||
### 图 7 · 产物与契约
|
||
|
||
```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 +tasks_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 | 系统全景（含 Team） | svg | ✅ |
|
||
| 2 | 调用时序（session 三路径 + 两阶段） | svg | ✅ |
|
||
| 3 | 运行时内部（真实结构 + goal/task） | svg | ✅ |
|
||
| 4 | 单写 ReAct 循环流程（三层） | svg | ✅ |
|
||
| 5 | 编排与配置 | mermaid | ✅ |
|
||
| 6 | reuse 边界（二维 + 载体类型） | svg | ✅ |
|
||
| 7 | 产物与契约 | mermaid | ✅ |
|
||
| 8 | 关键类图 | mermaid | ✅ |
|
||
|
||
## 4. 三层校验（创始人定义）
|
||
|
||
| 层 | 内容 | 处置 | 工具包 |
|
||
|---|---|---|---|
|
||
| **L1 硬约束** | 编译/启动/运行错误日志 | **必须解决 · 循环** | 确定性：构建日志/console/CDP 错误捕获（九门多数落此） |
|
||
| **L2 设计符合** | 玩法/关卡实现 vs 设计、UI 缺组件 | **尽量解决** | 设计符合度校验（部分九门：机制进展） |
|
||
| **L3 效果** | 特效/美观/好不好玩 | **只评分不解决** | M3 视觉软检（绝不阻塞/拒发） |
|
||
|
||
**迭代原则**：初期只识别硬问题（L1），L2/L3 渐进；**绝不让效果问题阻塞真问题**；用户可经 HITL 要求继续解决任意层。
|
||
|
||
## 5. 校正记录（创始人反馈 · 2026-06-22）
|
||
|
||
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**（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） |
|