0ff4d8cc48
- 内网凭据档补 new-api 协议端点(/v1/messages + /v1/chat/completions)+ 接入铁律(协议/SDK 不锁) - rules/security 加模型接入统一出口红线;skill cheap-model 纠正旧「唯一 OpenAI 兼容出口」口径 - 新增 agentic运行时架构图说.md + assets/03-运行时内部架构.svg(金样板,基于 agentscope 2.0.3 源码实证) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
63 lines
7.8 KiB
Markdown
63 lines
7.8 KiB
Markdown
# tier2 agentic 运行时架构图说
|
||
|
||
> 🚧 评审版 · **金样板阶段**：图 3（运行时内部架构）已出 svg 样板，其余图待风格确认后批量补。
|
||
> **这是什么**：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、无 rsvg/cairosvg）。
|
||
|
||
## 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 视觉软检） |
|
||
|
||
另有一套**复用边界图例**贯穿全图，让 vibecoding 的人一眼知道哪些是「直接用现成的」、哪些要「自己写」：**实线框 = AgentScope 生态官方现成直接用；虚线框 = tier2 自建（挂在官方 Middleware 或薄层上）；双线框 = 两条生成线共享的公共组件**。
|
||
|
||
## 2. 图 3 · 运行时内部架构（金样板）
|
||
|
||
|
||
|
||
这张图回答你一直没看到的那块——**agentic 运行时内部到底怎么转**。从外到内读：
|
||
|
||
整台机器是一个**独立进程的 service**（AgentScope 2.0.3，用官方 `create_app` 起成一个多租户、多会话的 FastAPI 服务），运行期与现有 SAA 廉价线零耦合。`game-cloud`（Java）通过一条 HTTP 接口把生成请求（一句话 brief + play_spec）发进来，API/Session 层据此建一个会话、起一个异步长任务，并把 runId 立即返回——因为造一款富游戏是长时任务，这里天然要会话、可中断（HITL）、可取消、会话之间互相隔离。
|
||
|
||
请求进入后，核心是中间那个**单写者 ReAct 循环**：只有一个 Agent 持全局视图、独自写整个工程（经营游戏多系统共享状态，拆并行几乎必然不一致）。这个循环本身是 AgentScope 官方现成的——`Agent` + `ReActConfig(max_iters)`，不需要我们自建。它每一轮做四件事：**推理**（调 M3 模型）、**调工具**（在沙箱里写码、构建、真跑）、**观测**（收回产物和截图）、**验收裁决**（过 / 修 / 熔断）。模型某一轮产出纯文本、不再调工具，就是它认为「做完了」；到迭代上限或熔断触发，则优雅收尾。没过的轮次走 repair 回环，同一个 agent 继续修——不拆并行。
|
||
|
||
把这个循环「关进笼子」的是外面那圈 **Middleware 洋葱**。预算软刹是官方现成的 `ReplyBudgetControlMiddleware`（到额就注入提示、逼模型收尾）；但生产真正要的「超时、卡死探测、超额即硬性熔断（fail-closed）」官方没有，得我们照官方 middleware 的写法自建，挂在同样的扩展点上。一条贯穿的铁律标在图里：**确定性的归机器、绝不让 LLM 给自己打分；M3 的视觉软检永远只观测、不放行也不拒发**（防 Goodhart）。
|
||
|
||
循环向外连三处。向右是 **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 的子集，走热配置。
|
||
|
||
循环跑出来的产物，由右下的**双层验收门**判定：确定性硬门（九门 + 跨表联动 + 经济门，公共 CDP harness，零 LLM 自评，定 pass/fail）是机制地板；M3 视觉软检只产观测和告警，绝不参与「算不算完成」。最底下是**运行时基础设施**——会话状态 checkpoint 到 Redis（可中断恢复）、结构化游戏源项目落库到 MySQL+OSS（带内容哈希）、全程可观测经 TracingMiddleware → OpenTelemetry → Studio。全绿的产物落库后，runId 对应的结果就能被 game-cloud 取回、进 feed。
|
||
|
||
## 3. 图清单与进度
|
||
|
||
以你的 5 步生命周期为主轴 + 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 | 待出 |
|
||
|
||
> 金样板（图 3）的风格 / 颗粒度 / 生产维度标注经创始人确认后，再按此清单批量补全其余 7 张，并统一转 png 入仓。
|