Merge dev/2.0.0: agentscope 2.0.2 版本订正入设计分支

.agents/README.md

@@ -31,7 +31,7 @@
 | `knowledge/tech-decisions.md` | 技术栈与关键选型理由 |
 | `knowledge/mvp-scope-and-milestones.md` | MVP 的 55 项 P0 产品功能范围、里程碑与验收指标 |
 | `knowledge/glossary.md` | 术语表 |
-| `knowledge/agentscope-2.0.3-facts.md` | AgentScope 2.0.3 真实架构速查（tier2 agentic 底座 · 3 路源码实证，免重查） |
+| `knowledge/agentscope-2.0.2-facts.md` | AgentScope 2.0.2 真实架构速查（tier2 agentic 底座 · 3 路源码实证，免重查） |
 
 **rules/**
 

.agents/knowledge/agentscope-2.0.2-facts.md

@@ -1,13 +1,13 @@
-# AgentScope 2.0.3 真实架构速查（tier2 agentic 底座）
+# AgentScope 2.0.2 真实架构速查（tier2 agentic 底座）
 
-> 本地源码 `/root/oss/agentscope`（**2.0.3，重构版、非 1.x**）。tier2 富游戏自治线选定它做底座。**API 拿不准先读源码**（源码 > context7 > 记忆）。本速查由 3 路源码调研实证（2026-06-22），用来免去下次重查。
+> 本地源码 `/root/oss/agentscope`（**2.0.2，重构版、非 1.x**）。tier2 富游戏自治线选定它做底座。**API 拿不准先读源码**（源码 > context7 > 记忆）。本速查由 3 路源码调研实证（2026-06-22），用来免去下次重查。
 
 ## 对象关系（谁持有谁 —— 别画错嵌套）
 - **Agent = 无状态 ReAct 引擎**：构造参数持有 `model` / `toolkit` / `middlewares` / `state(AgentState)` / `react_config`。一切可变态在 `AgentState`（`context` 工作记忆 / `cur_iter` / `tasks_context` / `permission_context` …），Agent 本体无状态。
 - **Workspace = Agent 的执行环境**（`LocalWorkspace`/`DockerWorkspace`/`E2BWorkspace`），**沿两轴注入 Agent**：① 它的 tools/MCP/skills 经 `get_toolkit(workspace=)` 合并进 `Toolkit`；② 它本身作 `offloader=`（context 卸载）。**Agent 持有 Workspace 引用、不是嵌在里面**；真正“跑在 Workspace 里”的是 MCP 进程/skills/文件。
 - **Agent 非常驻**：Agent Service 每次 run 现组装一个 Agent、跑完即弃，状态全在可持久化 `AgentState`（落 Redis）。天然可中断/恢复/水平扩。
 
-## API 纠偏（这些 1.x 旧假设在 2.0.3 已不存在）
+## API 纠偏（这些 1.x 旧假设在 2.0.2 已不存在）
 - 无独立 `ReActAgent` → 统一 `Agent` + `ReActConfig`（`max_iters` 默认 **20**）。
 - 拦截 = **Middleware 洋葱**（6 hook：`on_reply`/`on_reasoning`/`on_acting`/`on_model_call`/`on_system_prompt`/`on_compress_context`），**不是 agent hooks**。
 - 状态 = pydantic `AgentState`，**不是 `state_dict()` / `Session` 类**。
@@ -19,7 +19,7 @@
 
 ## 模型 / 记忆 / 熔断 / 观测
 - **模型**：9 个 provider ChatModel，各配对 Formatter（别混）。`AnthropicChatModel` + `AnthropicCredential.base_url`（可指自定义网关）+ `thinking_enable`/`thinking_budget`（thinking 分离；**`max_tokens` 须 > `thinking_budget`**）。结构化产出 = `model.generate_structured_output(structured_model=)`（强制工具 + schema 校验 + 重试；开 thinking 时 Anthropic 降级为非强制、需兜底）。
-- **记忆**：官方内置 = `Mem0Middleware`（mem0 后端）。**`ReMe` 是 agentscope-ai 的独立框架**（`/root/oss/ReMe`，功能更贴 debug 案例库，但 2.0.3 不开箱、要经 middleware 扩展点自接）。
+- **记忆**：官方内置 = `Mem0Middleware`（mem0 后端）。**`ReMe` 是 agentscope-ai 的独立框架**（`/root/oss/ReMe`，功能更贴 debug 案例库，但 2.0.2 不开箱、要经 middleware 扩展点自接）。
 - **熔断**：官方 `ReplyBudgetControlMiddleware` 只“软刹”（注入提示 + `tool_choice=none`、只数 token、不抛错）。**超时 / 卡死探测 / fail-closed 硬杀 / ¥金额台账 = 自建 Middleware**（挂 `on_reasoning`/`on_model_call`；¥台账订阅 `ModelCallEndEvent`）。
 - **观测**：`TracingMiddleware` → OpenTelemetry → Studio（`as_studio` :3000 UI / :4317 OTLP）；需自己用标准 OTel SDK 注册 `TracerProvider`（无 init 糖）。
 - **goal/task**：`AgentState.tasks_context` + `TaskCreate/Get/List/Update` 工具（拆 TODO 逐项追踪）。

docs/architecture/架构/生成引擎/agentic运行时架构图说.md

@@ -8,7 +8,7 @@
 
 ## 0. 阅读约定与同步纪律
 
-- **映射设计档**：本图说只把《[自治富游戏引擎](自治富游戏引擎.md)》《[tier2 四层工程架构](tier2四层工程架构.md)》《[tier2 实现详设](tier2实现详设.md)》《[agentic 集成架构](agentic集成架构.md)》画出来。机制以 **agentscope 2.0.3 源码实证**为准（`/root/oss/agentscope`，逐条核过）。
+- **映射设计档**：本图说只把《[自治富游戏引擎](自治富游戏引擎.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）：

docs/architecture/架构/生成引擎/agentic集成架构.md

@@ -53,13 +53,13 @@ flowchart TB
 
 ## tier2 接入面:官方 Agent Service + Agent Team
 
-在讲控制面四个组件怎么接 tier2 之前,得先说清 tier2 这条线的接入面长什么样 —— 它不是我们自造的,是 AgentScope 2.0.3 的官方 service 层,源码逐条核过(`agentscope/app/`)。这层既是 cloud 调 tier2 的入口(控制面在这之上加治理),也是 tier2 内部多 agent 协作的底座(管理面对它的拓扑做可视化)。把它讲清,控制面/管理面才不会去重复造轮子。
+在讲控制面四个组件怎么接 tier2 之前,得先说清 tier2 这条线的接入面长什么样 —— 它不是我们自造的,是 AgentScope 2.0.2 的官方 service 层,源码逐条核过(`agentscope/app/`)。这层既是 cloud 调 tier2 的入口(控制面在这之上加治理),也是 tier2 内部多 agent 协作的底座(管理面对它的拓扑做可视化)。把它讲清,控制面/管理面才不会去重复造轮子。
 
 **service 化 / 控制面接入**:tier2 不自造 API,直接用官方 **Agent Service**。它由 `create_app` 拉起一个 FastAPI 应用,对外是 REST + SSE,内置八个 router 全部核过 —— `/sessions`(会话)、`/chat`(对话)、`/schedule`(定时任务)、`/credential`(托管密钥)、`/workspace`(执行环境)、`/model`、`/tts_model`、外加 agent 管理面。它天生多租户、durable session(会话状态 `AgentState` 落库可恢复),底下用一套 **MessageBus(Redis 实现)** 撑起分布式协作:Redis Stream 做事件 replay 日志、pub/sub 做唤醒广播、还有分布式锁(`acquire_lock`)和取消信令(`session_publish_cancel` / `task_publish_cancel`)。`/schedule` 提供 cron 式定时触发,`/credential` 把各类模型密钥托管起来。所以 cloud 接 tier2 的真实姿势是:经 REST `POST /sessions` 建一个 durable 会话、再经 SSE 收事件流;SSE 流可恢复 —— 断线后靠 MessageBus 的 replay 日志补发,不丢中间过程。这正好兜住了"外部服务/异步任务要考虑超时、失败、断线"的可靠性要求。
 
 会话初始化有三条路径(对应"游戏=长生命周期项目"的三种入场):① 续接之前的会话 —— 取 `SessionRecord.state` 历史 resume;② 加载一个已有工程 —— `Workspace.workdir` 指向已存在的游戏目录,迭代它;③ 新建 —— 用模板初始化工具铺出工程骨架。
 
-**多 agent 管理面 / Agent Team**:这里有个关键的版本事实必须钉死,否则会照着过时的认知去设计。AgentScope 2.0.3 已经删掉了进程内的 `MsgHub` / `pipeline` 那套同步编排原语 —— 多 agent 协作不再是"在一个进程里串 pipeline",而是部署态的 **Agent Team**:由一个 leader session 用 `TeamCreate` / `AgentCreate` / `TeamSay` / `TeamDelete` 这几个工具,星形地调度若干 worker session(源码 `agentscope/app/_tools/` 核过)。这套调度有两条硬约束源自框架本身:worker 之间不互相评审、只对 leader 汇报(星形,非网状);worker 被 leader 创建后立即开干,干完经 MessageBus 的 inbox/wakeup 机制异步通知 leader,leader 不必轮询等待。tier2 的两阶段流程(阶段 1 工作室多 agent 发散设计 → 阶段 2 单写 agent 实现)就跑在这套 Agent Team 上 —— 阶段 1 的 leader 用 AgentCreate 拉起玩法/关卡/数值/UI 等设计 worker、TeamSay 收敛,阶段 2 收敛成单写以防并行写冲突。管理面要可视化的"多 agent 拓扑",渲染的就是这套部署态 Team 的运行时自报结构,而不是另持一份拓扑模型。
+**多 agent 管理面 / Agent Team**:这里有个关键的版本事实必须钉死,否则会照着过时的认知去设计。AgentScope 2.0.2 已经删掉了进程内的 `MsgHub` / `pipeline` 那套同步编排原语 —— 多 agent 协作不再是"在一个进程里串 pipeline",而是部署态的 **Agent Team**:由一个 leader session 用 `TeamCreate` / `AgentCreate` / `TeamSay` / `TeamDelete` 这几个工具,星形地调度若干 worker session(源码 `agentscope/app/_tools/` 核过)。这套调度有两条硬约束源自框架本身:worker 之间不互相评审、只对 leader 汇报(星形,非网状);worker 被 leader 创建后立即开干,干完经 MessageBus 的 inbox/wakeup 机制异步通知 leader,leader 不必轮询等待。tier2 的两阶段流程(阶段 1 工作室多 agent 发散设计 → 阶段 2 单写 agent 实现)就跑在这套 Agent Team 上 —— 阶段 1 的 leader 用 AgentCreate 拉起玩法/关卡/数值/UI 等设计 worker、TeamSay 收敛,阶段 2 收敛成单写以防并行写冲突。管理面要可视化的"多 agent 拓扑",渲染的就是这套部署态 Team 的运行时自报结构,而不是另持一份拓扑模型。
 
 ## 四个组件
 
@@ -79,7 +79,7 @@ prompt 和 models 这两层是线A的阶段2-3,本设计只引用、不重排,
 
 运行轨迹记的是每次生成发生了什么 —— 每步推理、每次工具调用、每次 LLM 输入输出、每道门裁决、每次成本。消灭 split-brain(轨迹分散在各条派发路上)的真口径是"每条派发路诚实镜像它真有的字段、没有的绝不编造",不是"强求两条线字段对齐" —— tier2 的 ReAct"想-做-看"和 SAA 16 个节点的阶段裁决本就不同构,强求对齐是错的。统一轨迹的目标是:同一张表,一个公共核心子集(traceId、step、cost、verdict、timestamp),各轨把独有的放进一个 JSON 扩展列(SAA 放阶段、修复轮次、门裁,tier2 放推理、动作、观察)。它要落成一份真契约,放 `contracts/trace/`,作为契约组的新一类 additive 立位(这一位当前还没建,随 spike 或控制面 phase-1 落地时再新立、别当现成),内容含字段定义、schema 版本、脱敏规则、两条线 adapter 怎么映射,以及一条要选边的策略 —— 轨迹写不进去时阻塞生成还是 best-effort 丢弃告警(默认 best-effort 不阻塞主流程,但计入告警)。
 
-这份 trace 契约是数据口径,不是采集机制;采集机制两条线各按自己的框架来。tier2 这条线尤其不必自己埋点,因为 AgentScope 2.0.3 本身就有一套完整的 typed Event System:Agent 每跑一步都吐出强类型事件流 —— `TextBlock*`(文本)、`ThinkingBlock*`(思考)、`ToolCall*`(工具调用)、`ToolResult*`(工具结果)、`ModelCallStart/End`(模型调用,带 token 用量)、`ReplyStart/End`(一轮回复边界)等,源码逐条核过(`agentscope/event/_event.py`)。这条事件流经官方 `TracingMiddleware` 转成 OpenTelemetry 的 span(`agentscope/middleware/_tracing/_trace.py` 直接调真 OTel SDK),最终汇进 AgentScope Studio 可视化。也就是说,tier2 写轨迹的真实接法是:订阅 Event System、用 TracingMiddleware→OTel 这条官方管道,再加一层 adapter 把这些事件按公共核心子集+扩展段映射进 `contracts/trace/` 那张统一表。SAA 那条 Java 线则按它自己的节点裁决埋点、走同一份契约的 adapter。两条线机制各异、契约一致,正是"接口对称、内容不对称"在可观测面的落点。
+这份 trace 契约是数据口径,不是采集机制;采集机制两条线各按自己的框架来。tier2 这条线尤其不必自己埋点,因为 AgentScope 2.0.2 本身就有一套完整的 typed Event System:Agent 每跑一步都吐出强类型事件流 —— `TextBlock*`(文本)、`ThinkingBlock*`(思考)、`ToolCall*`(工具调用)、`ToolResult*`(工具结果)、`ModelCallStart/End`(模型调用,带 token 用量)、`ReplyStart/End`(一轮回复边界)等,源码逐条核过(`agentscope/event/_event.py`)。这条事件流经官方 `TracingMiddleware` 转成 OpenTelemetry 的 span(`agentscope/middleware/_tracing/_trace.py` 直接调真 OTel SDK),最终汇进 AgentScope Studio 可视化。也就是说,tier2 写轨迹的真实接法是:订阅 Event System、用 TracingMiddleware→OTel 这条官方管道,再加一层 adapter 把这些事件按公共核心子集+扩展段映射进 `contracts/trace/` 那张统一表。SAA 那条 Java 线则按它自己的节点裁决埋点、走同一份契约的 adapter。两条线机制各异、契约一致,正是"接口对称、内容不对称"在可观测面的落点。
 
 配置审计日志记的是谁、什么时候、改了哪条配置、为什么。这条线现在完全没有,是新建的。它的最小数据模型至少含:谁改的、从哪改的(UI 还是直接改 Git / DB)、改了什么(前后 diff)、配置版本号、谁批的、何时生效、回滚到哪个版本、影响了哪些生成任务。这里有一个要选边、不能既要又要的决策:UI 改配置,直接写运行时(DB 直写)还是建 Git PR(GitOps)?
 
@@ -98,7 +98,7 @@ flowchart TD
 
 D12 是已经存在的件,本设计只复用、不改。它把配额、并发限制、背压保护、降级开关、记账骨架,焊在生成任务入口前 —— 代码里 SAA 的提交和重试两条路都过它,默认关闭、零行为变更进主干,开闸前创始人显式打开。它有两点边界:现在只覆盖 SAA,tier2 接进来的入口、预算扣减、并发释放、失败补偿还要补;它的记账是骨架不是真计费(只是门结构加配置键,不是成本核算)。
 
-这接上引擎设计里那道"花到上限就拒绝执行"的预算闸 —— 它现在不是现成能力。要先讲清官方给了什么、缺什么:AgentScope 2.0.3 自带 `ReplyBudgetControlMiddleware`,但它只做软刹 —— 累计加权 token 到阈值后,往 Agent 上下文注入一句提示、并把下一步的 `tool_choice` 强制成 `none` 让它收尾(源码 `agentscope/middleware/_budget.py` 核过),它只数 token、不换算金额、更不会硬拒。这对失控成本不够:tier2 自治多轮 ReAct 的成本风险是真的(一次失控循环能烧掉数美元),软刹只是"提醒它别再调工具",刹不住一个已经在烧钱的循环。
+这接上引擎设计里那道"花到上限就拒绝执行"的预算闸 —— 它现在不是现成能力。要先讲清官方给了什么、缺什么:AgentScope 2.0.2 自带 `ReplyBudgetControlMiddleware`,但它只做软刹 —— 累计加权 token 到阈值后,往 Agent 上下文注入一句提示、并把下一步的 `tool_choice` 强制成 `none` 让它收尾(源码 `agentscope/middleware/_budget.py` 核过),它只数 token、不换算金额、更不会硬拒。这对失控成本不够:tier2 自治多轮 ReAct 的成本风险是真的(一次失控循环能烧掉数美元),软刹只是"提醒它别再调工具",刹不住一个已经在烧钱的循环。
 
 所以硬熔断(fail-closed)和 ¥ 金额台账都得自建,而且自建有现成载体 —— 同样是 Middleware。AgentScope 的中间件洋葱能在 `on_model_call` 这类钩子上拦截,自建一个预算 Middleware:它订阅 `ModelCallEndEvent`(源码已确认这事件带每次模型调用的 token 用量),把 token 乘上 new-api 的单价换算成 ¥ 累进台账,一旦越过硬上限就直接抛错 fail-closed、终止本次生成,而不是像官方那样只注入提示。要落三层强制:worker 本地的 token / 成本预测先闸、网关配额二闸(D12 那道)、任务 deadline 三闸,并定义取价不可达时的策略(直接失败,还是降级到纯 token 上限)。这套强制预算建成前,tier2 不规模化跑、只在严格时间盒的实验里跑。
 
@@ -124,7 +124,7 @@ phase-3 叫"完整可视化建图",是远期。拖拽改拓扑、可视化编 ag
 
 ## 关于 workflow 编排:tier2 不需要,但登记一条未来需求
 
-这里要先澄清一个容易混的概念。AgentScope 2.0.3 里没有显式的 workflow DAG 或编排原语 —— tier2 的运行范式是自治 loop(怎么走)+ task/goal 清单(`AgentState.tasks_context`,走向哪、走到哪)+ Agent Team 动态调度(谁来走),没有一张预先画死的工作流图。所以前面管理面 phase-3 那个"完整可视化建图、拖拽改拓扑"指的是给我们自己运维用的、对运行时拓扑的可视化,不是给用户编 workflow 的产品能力,两者别混。
+这里要先澄清一个容易混的概念。AgentScope 2.0.2 里没有显式的 workflow DAG 或编排原语 —— tier2 的运行范式是自治 loop(怎么走)+ task/goal 清单(`AgentState.tasks_context`,走向哪、走到哪)+ Agent Team 动态调度(谁来走),没有一张预先画死的工作流图。所以前面管理面 phase-3 那个"完整可视化建图、拖拽改拓扑"指的是给我们自己运维用的、对运行时拓扑的可视化,不是给用户编 workflow 的产品能力,两者别混。
 
 在此登记一条**未来产品需求**(2026-06-22 记):未来要给用户 / 创作者提供 workflow 编排能力(可视化地编排生成场景)。这是一个面向 C 端创作者的产品场景,跟控制面/管理面这层平台治理是两回事。明确一点:**当前 tier2 自身不需要 workflow** —— 自治 agent 范式靠 loop + task/goal + Team 调度就够了,不靠预定义 DAG。这条只作登记、占位,具体形态以后单独讨论,本设计不展开、不投入。
 

docs/architecture/架构/生成引擎/assets/01-系统全景.svg

@@ -34,7 +34,7 @@
   <!-- tier2 agentic service -->
   <rect x="440" y="90" width="470" height="400" rx="12" fill="#f0fdf4" stroke="#16a34a" stroke-width="2.5"/>
   <text x="456" y="113" class="t h2">tier2 agentic service　〔主角〕</text>
-  <text x="456" y="132" class="mut xs">独立进程 / 容器 · AgentScope 2.0.3 · create_app(FastAPI)</text>
+  <text x="456" y="132" class="mut xs">独立进程 / 容器 · AgentScope 2.0.2 · create_app(FastAPI)</text>
   <rect x="458" y="144" width="434" height="46" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="1.6"/>
   <text x="468" y="166" class="t sm">Agent Service（REST + SSE）</text>
   <text x="468" y="183" class="mut xs">多租户 · 会话 · HITL · 取消 · /sessions /chat /schedule</text>
@@ -112,5 +112,5 @@
   <rect x="160" y="616" width="34" height="20" rx="5" fill="#fff" stroke="#16a34a" stroke-width="2"/><text x="202" y="631" class="t xs">实线〔官方现成〕</text>
   <rect x="360" y="616" width="34" height="20" rx="5" fill="#fff" stroke="#475569" stroke-width="1.8" stroke-dasharray="6 4"/><text x="402" y="631" class="t xs">虚线〔自建/零耦合〕</text>
   <rect x="580" y="616" width="34" height="20" rx="5" fill="#fff" stroke="#2563eb" stroke-width="2.8"/><text x="622" y="631" class="t xs">双线〔公共组件〕</text>
-  <text x="40" y="668" class="mut xs">映射：agentic集成架构.md · tier2四层工程架构.md　|　基于 agentscope 2.0.3 源码实证　|　设计变动须同步本图</text>
+  <text x="40" y="668" class="mut xs">映射：agentic集成架构.md · tier2四层工程架构.md　|　基于 agentscope 2.0.2 源码实证　|　设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/02-调用时序.svg

@@ -72,5 +72,5 @@
 
   <line x1="60" y1="1140" x2="110" y2="1140" class="req" marker-end="url(#arrow)"/><text x="118" y="1144" class="t xs">REST 请求 / 动作</text>
   <line x1="300" y1="1140" x2="350" y2="1140" class="sse" marker-end="url(#arrowB)"/><text x="358" y="1144" class="t xs">SSE 事件流（可恢复）</text>
-  <text x="640" y="1144" class="mut xs">映射：agentic集成架构.md · tier2实现详设.md｜基于 agentscope 2.0.3 Agent Service + Agent Team 源码实证｜设计变动须同步本图</text>
+  <text x="640" y="1144" class="mut xs">映射：agentic集成架构.md · tier2实现详设.md｜基于 agentscope 2.0.2 Agent Service + Agent Team 源码实证｜设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/03-运行时内部架构.svg

@@ -116,5 +116,5 @@
   <rect x="170" y="886" width="34" height="20" rx="5" fill="#fff" stroke="#16a34a" stroke-width="2"/><text x="212" y="901" class="t xs">实线〔官方〕</text>
   <rect x="320" y="886" width="34" height="20" rx="5" fill="#fff" stroke="#475569" stroke-width="1.8" stroke-dasharray="6 4"/><text x="362" y="901" class="t xs">虚线〔自建〕</text>
   <text x="480" y="901" class="mut xs">生产维度：可靠 / 安全 / 数据 / 可观测 / 质量（标在对应组件角）</text>
-  <text x="50" y="958" class="mut xs">映射：tier2四层工程架构.md · 自治富游戏引擎.md　|　基于 agentscope 2.0.3 源码实证（Agent 双轴持有 Workspace · Agent 非常驻 · Middleware 洋葱）　|　设计变动须同步本图</text>
+  <text x="50" y="958" class="mut xs">映射：tier2四层工程架构.md · 自治富游戏引擎.md　|　基于 agentscope 2.0.2 源码实证（Agent 双轴持有 Workspace · Agent 非常驻 · Middleware 洋葱）　|　设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/06-reuse边界全景.svg

@@ -75,5 +75,5 @@
   <text x="634" y="820" class="t xs" font-weight="700">载体类型（AgentScope 扩展点）：</text>
   <text x="634" y="842" class="xs"><tspan fill="#2563eb" font-weight="700">Tool</tspan>=工具函数　<tspan fill="#ea580c" font-weight="700">Middleware</tspan>=hook 拦截　<tspan fill="#7c3aed" font-weight="700">Skill</tspan>=SKILL.md　<tspan fill="#16a34a" font-weight="700">Prompt</tspan>=指令　<tspan fill="#0891b2" font-weight="700">Memory</tspan>=ReMe　<tspan fill="#64748b" font-weight="700">Schema</tspan>=契约数据　<tspan fill="#334155" font-weight="700">独立</tspan>=框架外</text>
 
-  <text x="40" y="922" class="mut xs">映射：tier2四层工程架构.md §8 · agentic集成架构.md　|　基于 agentscope 2.0.3 源码逐项核对（官方已有/真自建 + 载体类型）　|　设计变动须同步本图</text>
+  <text x="40" y="922" class="mut xs">映射：tier2四层工程架构.md §8 · agentic集成架构.md　|　基于 agentscope 2.0.2 源码逐项核对（官方已有/真自建 + 载体类型）　|　设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/t2-A-01-AgentService与session三路.svg

@@ -32,7 +32,7 @@
 
   <!-- ② 官方 Agent Service -->
   <rect x="318" y="142" width="800" height="118" rx="10" fill="#eff6ff" stroke="#2563eb" stroke-width="1.6"/>
-  <text x="336" y="172" class="box">官方 Agent Service · AgentScope 2.0.3</text>
+  <text x="336" y="172" class="box">官方 Agent Service · AgentScope 2.0.2</text>
   <rect x="336" y="184" width="48" height="20" rx="5" fill="#2563eb"/><text x="360" y="198" class="bj" text-anchor="middle">现成</text>
   <text x="394" y="200" class="mut xs">= create_app 拉起的 FastAPI(REST + SSE);tier2 不自造 API,接官方的。</text>
   <text x="336" y="228" class="mut xs">天生多租户 + durable session:会话状态 AgentState 落库可恢复(配 StorageBase 落 Redis)。</text>

docs/architecture/架构/生成引擎/assets/t2-A-02-Agent非常驻与AgentState.svg

@@ -19,8 +19,8 @@
 
   <!-- 状态约定条:整图待建 -->
   <rect x="40" y="74" width="1400" height="46" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；但 AgentState / StorageBase 的结构与字段已按 AgentScope 2.0.3 源码逐条核过。</text>
-  <text x="58" y="114" class="mut xs">实线 = 现行已落（官方 AgentScope 2.0.3 现成件：AgentState 模型 / StorageBase / RedisStorage）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（非常驻装配、每轮 checkpoint 落 Redis、resume 续跑）。</text>
+  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；但 AgentState / StorageBase 的结构与字段已按 AgentScope 2.0.2 源码逐条核过。</text>
+  <text x="58" y="114" class="mut xs">实线 = 现行已落（官方 AgentScope 2.0.2 现成件：AgentState 模型 / StorageBase / RedisStorage）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（非常驻装配、每轮 checkpoint 落 Redis、resume 续跑）。</text>
 
   <!-- 生产维度徽章 -->
   <rect x="40" y="134" width="200" height="26" rx="7" fill="#fff" stroke="#cbd5e1" stroke-width="1.2"/>
@@ -32,7 +32,7 @@
   <rect x="40" y="180" width="440" height="298" rx="11" fill="#fff" stroke="#64748b" stroke-width="1.6" stroke-dasharray="6 4"/>
   <text x="60" y="210" class="box">Agent · 无状态 ReAct 引擎</text>
   <rect x="60" y="222" width="58" height="20" rx="5" fill="#7c3aed"/><text x="89" y="236" class="bj" text-anchor="middle">待建</text>
-  <text x="128" y="237" class="mut xs">（引擎本体 = 官方 AgentScope 2.0.3）</text>
+  <text x="128" y="237" class="mut xs">（引擎本体 = 官方 AgentScope 2.0.2）</text>
 
   <text x="60" y="266" class="t sm">实例非常驻 = 不是长跑进程</text>
   <text x="60" y="288" class="mut xs">每次 run：现组装 → 跑完即弃，不留活对象。</text>
@@ -63,7 +63,7 @@
   <!-- ============ 中:AgentState 结构(实线·官方现成模型) ============ -->
   <rect x="540" y="180" width="468" height="298" rx="11" fill="#fff" stroke="#334155" stroke-width="1.6"/>
   <text x="560" y="210" class="box">AgentState · pydantic 模型</text>
-  <rect x="560" y="222" width="86" height="20" rx="5" fill="#16a34a"/><text x="603" y="236" class="bj" text-anchor="middle">2.0.3 现成</text>
+  <rect x="560" y="222" width="86" height="20" rx="5" fill="#16a34a"/><text x="603" y="236" class="bj" text-anchor="middle">2.0.2 现成</text>
   <text x="656" y="237" class="mut xs mono">agentscope/state/_state.py</text>
 
   <!-- 三个核心字段卡片 -->
@@ -101,7 +101,7 @@
 
   <!-- StorageBase / Redis -->
   <rect x="1088" y="324" width="334" height="52" rx="8" fill="#f0fdf4" stroke="#16a34a" stroke-width="1.3"/>
-  <rect x="1102" y="334" width="86" height="20" rx="5" fill="#16a34a"/><text x="1145" y="348" class="bj" text-anchor="middle">2.0.3 现成</text>
+  <rect x="1102" y="334" width="86" height="20" rx="5" fill="#16a34a"/><text x="1145" y="348" class="bj" text-anchor="middle">2.0.2 现成</text>
   <text x="1196" y="349" class="t xs mono">StorageBase</text>
   <text x="1102" y="370" class="mut xs">配 StorageBase 抽象 · RedisStorage 落 Redis</text>
 
@@ -151,5 +151,5 @@
   <text x="58" y="734" class="mut xs">每轮落盘与半轮幂等两条硬约束，以及 resume 续跑落到 SessionRecord.state 与 cur_iter 续接的具体链路——这些总览图 3/8 未展开。Agent↔Workspace 两轴注入见总览图 3，本图不重画。</text>
 
   <!-- 脚注 -->
-  <text x="40" y="772" class="mut xs">映射：docs/architecture/架构/生成引擎/tier2实现详设.md §运行时形态（Agent 非常驻 + AgentState + checkpoint）· agentic集成架构.md §tier2 接入面（durable session / SessionRecord.state）· agentic运行时架构图说.md 图3 运行时内部 + 图8 类图（放大）· AgentScope 2.0.3 源码 state/_state.py + app/storage（已核）｜ 状态：现（AgentState/StorageBase=官方现成）/ 建（tier2 非常驻装配 + 每轮 checkpoint + resume）｜ 设计变动须同步本图</text>
+  <text x="40" y="772" class="mut xs">映射：docs/architecture/架构/生成引擎/tier2实现详设.md §运行时形态（Agent 非常驻 + AgentState + checkpoint）· agentic集成架构.md §tier2 接入面（durable session / SessionRecord.state）· agentic运行时架构图说.md 图3 运行时内部 + 图8 类图（放大）· AgentScope 2.0.2 源码 state/_state.py + app/storage（已核）｜ 状态：现（AgentState/StorageBase=官方现成）/ 建（tier2 非常驻装配 + 每轮 checkpoint + resume）｜ 设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/t2-A-03-Workspace双轴注入.svg

@@ -19,8 +19,8 @@
 
   <!-- 状态约定条:整图待建 -->
   <rect x="40" y="74" width="1400" height="46" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；双轴注入结构本身（AgentScope 2.0.3 源码已逐条核过）可信。</text>
-  <text x="58" y="114" class="mut xs">实线 = 官方 AgentScope 2.0.3 现成件（Agent / Workspace / Toolkit / get_toolkit / offloader / 三实现，直接用）；虚线（stroke-dasharray 6 4）= tier2 专属待建（注入工具集 / 沙箱底座选型）。</text>
+  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；双轴注入结构本身（AgentScope 2.0.2 源码已逐条核过）可信。</text>
+  <text x="58" y="114" class="mut xs">实线 = 官方 AgentScope 2.0.2 现成件（Agent / Workspace / Toolkit / get_toolkit / offloader / 三实现，直接用）；虚线（stroke-dasharray 6 4）= tier2 专属待建（注入工具集 / 沙箱底座选型）。</text>
 
   <!-- ============ 左:Agent 本体 ============ -->
   <rect x="40" y="156" width="300" height="316" rx="12" fill="#fff" stroke="#334155" stroke-width="1.6"/>
@@ -135,5 +135,5 @@
   <text x="58" y="796" class="mut xs">tier2 不凭空自建 environment 数据面:在官方 Workspace 抽象上挂 tier2 要的工具与资源即可;沙箱底座（Local/Docker/E2B 与 D5 选型）解决「在哪跑、隔离多强」。</text>
 
   <!-- 脚注 -->
-  <text x="40" y="844" class="mut xs">映射：docs/architecture/架构/生成引擎/agentic运行时架构图说.md 图3（运行时内部·双轴注入）＋ 图8（类图 WorkspaceBase）· tier2实现详设.md §运行时形态 · tier2四层工程架构.md §3（environment 层·载体=Workspace·D5 沙箱底座待验）· agentscope 2.0.3 源码（_agent.py：104 offloader / _toolkit.py：27 get_toolkit / workspace/_base.py：36 三实现）｜ 状态：现（官方 AgentScope 现成件）/ 建（tier2 注入工具集 ＋ D5 沙箱底座选型）/ 缓（E2B 远端强隔离=更长期层）｜ 设计变动须同步本图</text>
+  <text x="40" y="844" class="mut xs">映射：docs/architecture/架构/生成引擎/agentic运行时架构图说.md 图3（运行时内部·双轴注入）＋ 图8（类图 WorkspaceBase）· tier2实现详设.md §运行时形态 · tier2四层工程架构.md §3（environment 层·载体=Workspace·D5 沙箱底座待验）· agentscope 2.0.2 源码（_agent.py：104 offloader / _toolkit.py：27 get_toolkit / workspace/_base.py：36 三实现）｜ 状态：现（官方 AgentScope 现成件）/ 建（tier2 注入工具集 ＋ D5 沙箱底座选型）/ 缓（E2B 远端强隔离=更长期层）｜ 设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/t2-A-04-Middleware洋葱.svg

@@ -13,11 +13,11 @@
   </defs>
   <rect x="0" y="0" width="1480" height="940" fill="#f8fafc"/>
   <text x="40" y="38" class="t h1">图 A4 · Middleware 洋葱（横切关注点挂载点）（族 A）</text>
-  <text x="40" y="60" class="mut sm">AgentScope 2.0.3 的 MiddlewareBase 在 Agent 执行的若干钩子上层层拦截（洋葱式）；tier2 把成本刹车 / 硬熔断 / 可观测统一挂在这套洋葱上，不另起机制、不散落进业务逻辑。</text>
+  <text x="40" y="60" class="mut sm">AgentScope 2.0.2 的 MiddlewareBase 在 Agent 执行的若干钩子上层层拦截（洋葱式）；tier2 把成本刹车 / 硬熔断 / 可观测统一挂在这套洋葱上，不另起机制、不散落进业务逻辑。</text>
 
   <!-- 状态约定条 -->
   <rect x="40" y="74" width="1400" height="46" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；洋葱 hook 机制（MiddlewareBase 5 钩子，AgentScope 2.0.3 源码已核）可信。</text>
+  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；洋葱 hook 机制（MiddlewareBase 5 钩子，AgentScope 2.0.2 源码已核）可信。</text>
   <text x="58" y="114" class="mut xs">实线 = 承袭现行已落（官方 ReplyBudgetControlMiddleware 软刹 / 官方 TracingMiddleware 观测 / D12 治理门）；虚线（stroke-dasharray 6 4）= tier2 专属待建（硬熔断三件做成 MiddlewareBase 子类）。</text>
 
   <!-- ============ 左:洋葱本体(同心环) ============ -->
@@ -61,7 +61,7 @@
   <text x="730" y="200" class="box">① 官方 ReplyBudgetControlMiddleware · 预算软刹</text>
   <rect x="730" y="210" width="48" height="20" rx="5" fill="#16a34a"/><text x="754" y="224" class="bj" text-anchor="middle">成本</text>
   <rect x="784" y="210" width="60" height="20" rx="5" fill="#15803d"/><text x="814" y="224" class="bj" text-anchor="middle">现成·实线</text>
-  <text x="858" y="225" class="mut xs">挂 on_reply + on_reasoning;AgentScope 2.0.3 自带,直接用。</text>
+  <text x="858" y="225" class="mut xs">挂 on_reply + on_reasoning;AgentScope 2.0.2 自带,直接用。</text>
   <text x="730" y="252" class="t sm">on_reply 里按 ModelCallEndEvent 累计加权 token → 越阈值后,</text>
   <text x="730" y="274" class="t sm">on_reasoning 里注入收尾提示 + 强制 tool_choice=none 让它收尾。</text>
   <text x="730" y="298" class="mut xs">只数 token、不换算金额、更不硬拒 —— 刹不住一个已经在烧钱的失控循环（见 B3）。</text>
@@ -91,7 +91,7 @@
   <text x="730" y="540" class="box">③ 官方 TracingMiddleware · 可观测</text>
   <rect x="730" y="550" width="60" height="20" rx="5" fill="#0ea5e9"/><text x="760" y="564" class="bj" text-anchor="middle">可观测</text>
   <rect x="796" y="550" width="60" height="20" rx="5" fill="#15803d"/><text x="826" y="564" class="bj" text-anchor="middle">现成·实线</text>
-  <text x="870" y="565" class="mut xs">挂 on_reply / on_model_call / on_acting;AgentScope 2.0.3 自带。</text>
+  <text x="870" y="565" class="mut xs">挂 on_reply / on_model_call / on_acting;AgentScope 2.0.2 自带。</text>
   <text x="730" y="592" class="t sm">把 typed Event 流（ThinkingBlock / ToolCall / ModelCallStart/End …）转成 OpenTelemetry span。</text>
   <text x="730" y="616" class="mut xs">直接调真 OTel SDK → 汇进 AgentScope Studio 可视化;tier2 再加一层 adapter 映射进统一 trace 契约（见 H2）。</text>
   <text x="730" y="636" class="mut xs">tier2 写轨迹不必自己埋点 —— 复用这条官方 Event→OTel 管道。</text>
@@ -100,7 +100,7 @@
   <rect x="40" y="666" width="640" height="110" rx="10" fill="#f0fdf4" stroke="#16a34a" stroke-width="1.6"/>
   <text x="58" y="694" class="t sm" font-weight="700">洋葱 = tier2 横切关注点的统一挂载点</text>
   <text x="58" y="718" class="mut xs">成本（软刹 / ¥ 硬闸）· 超时 · 卡死 · 观测 全挂同一套洋葱,</text>
-  <text x="58" y="738" class="mut xs">不散落进业务逻辑、不另立机制 —— 这是 2.0.3 给的扩展点。</text>
+  <text x="58" y="738" class="mut xs">不散落进业务逻辑、不另立机制 —— 这是 2.0.2 给的扩展点。</text>
   <text x="58" y="760" class="mut xs">三层成本强制:worker 本地预测先闸 → D12 网关配额二闸 → 任务 deadline 三闸。</text>
 
   <!-- 关系:洋葱 → D12 (已有件·实线) -->
@@ -111,6 +111,6 @@
   <text x="730" y="762" class="mut xs">D12 现只覆盖 SAA;tier2 接入的入口 / 预算扣减 / 并发释放 / 失败补偿待补（D12 边界,见集成架构 §D12）。</text>
 
   <!-- 脚注 -->
-  <text x="40" y="812" class="mut xs">映射：docs/architecture/架构/生成引擎/agentic集成架构.md §D12 运行治理门（on_model_call / ModelCallEndEvent 软刹缺口与自建硬熔断）· tier2实现详设.md §建设五步第三步「成本强制」· agentscope 2.0.3 源码 middleware/_base.py（4 onion + 1 transformer 钩子）· _budget.py（软刹机制）· _tracing/_trace.py（Event→OTel）｜ 状态：建（tier2 待建·洋葱 hook 2.0.3 已核;软刹 / trace 官方现成,硬熔断自建）｜ 设计变动须同步本图</text>
+  <text x="40" y="812" class="mut xs">映射：docs/architecture/架构/生成引擎/agentic集成架构.md §D12 运行治理门（on_model_call / ModelCallEndEvent 软刹缺口与自建硬熔断）· tier2实现详设.md §建设五步第三步「成本强制」· agentscope 2.0.2 源码 middleware/_base.py（4 onion + 1 transformer 钩子）· _budget.py（软刹机制）· _tracing/_trace.py（Event→OTel）｜ 状态：建（tier2 待建·洋葱 hook 2.0.2 已核;软刹 / trace 官方现成,硬熔断自建）｜ 设计变动须同步本图</text>
   <text x="40" y="832" class="mut xs">（放大总览图 8 关键类图的 MiddlewareBase 一支:ReplyBudgetControlMiddleware 现成,TimeoutMiddleware / StuckDetectMiddleware 自建 —— 本图把它们各自挂哪个钩子、做什么逐项展开,不重画类图。）</text>
 </svg>

docs/architecture/架构/生成引擎/assets/t2-B-01-控制面四组件.svg

@@ -42,7 +42,7 @@
   <rect x="40" y="312" width="236" height="118" rx="10" fill="#fff" stroke="#64748b" stroke-width="1.5" stroke-dasharray="6 4"/>
   <text x="58" y="340" class="box">tier2 · 自治富游戏</text>
   <rect x="58" y="352" width="48" height="20" rx="5" fill="#7c3aed"/><text x="82" y="366" class="bj" text-anchor="middle">待建</text>
-  <text x="58" y="394" class="mut xs">单写 ReAct（AgentScope 2.0.3）</text>
+  <text x="58" y="394" class="mut xs">单写 ReAct（AgentScope 2.0.2）</text>
   <text x="58" y="412" class="mut xs">读配置/写轨迹已设计 · 过门待接</text>
 
   <!-- ============ 控制面/管理面 容器 ============ -->

docs/architecture/架构/生成引擎/assets/t2-B-03-预算三层强制.svg

@@ -20,7 +20,7 @@
   <!-- 状态约定条 -->
   <rect x="40" y="74" width="1400" height="62" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="58" y="98" class="t sm">整图状态 = 现（官方软刹现成）＋ 建（硬熔断 ＋ 三层强制自建待落）。tier2 整轨待 0号 spike 验证、尚未落代码。</text>
-  <text x="58" y="116" class="mut xs">实线 = 现行已落（官方 AgentScope 2.0.3 ReplyBudgetControlMiddleware / D12 运行治理门 / new-api 计费平面）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（预算 Middleware 硬熔断 / 三层强制闸）。</text>
+  <text x="58" y="116" class="mut xs">实线 = 现行已落（官方 AgentScope 2.0.2 ReplyBudgetControlMiddleware / D12 运行治理门 / new-api 计费平面）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（预算 Middleware 硬熔断 / 三层强制闸）。</text>
   <text x="58" y="132" class="mut xs">徽章:成本（#16a34a）＝预算核算面 · 安全（#dc2626）＝fail-closed 截断面。</text>
 
   <!-- ============ 上半:软刹 vs 硬熔断 两框对照 ============ -->
@@ -30,7 +30,7 @@
   <rect x="40" y="178" width="688" height="262" rx="11" fill="#fff" stroke="#334155" stroke-width="1.6"/>
   <text x="58" y="208" class="box">官方软刹 · ReplyBudgetControlMiddleware</text>
   <rect x="58" y="220" width="48" height="20" rx="5" fill="#334155"/><text x="82" y="234" class="bj" text-anchor="middle">现成</text>
-  <rect x="114" y="220" width="170" height="20" rx="5" fill="#16a34a"/><text x="199" y="234" class="bj" text-anchor="middle">AgentScope 2.0.3 自带</text>
+  <rect x="114" y="220" width="170" height="20" rx="5" fill="#16a34a"/><text x="199" y="234" class="bj" text-anchor="middle">AgentScope 2.0.2 自带</text>
   <text x="58" y="264" class="t sm">机制:累计加权 token 到阈值后 —</text>
   <text x="58" y="288" class="mut xs">① 往 Agent 上下文注入一句提示（「别再调工具、收尾」）;</text>
   <text x="58" y="310" class="mut xs">② 把下一步 <tspan class="mono">tool_choice</tspan> 强制成 <tspan class="mono">none</tspan>，逼它结束。</text>

docs/architecture/架构/生成引擎/assets/t2-C-01-单写ReAct循环.svg

@@ -62,7 +62,7 @@
   <!-- tier2 态:虚线(待建) -->
   <rect x="60" y="520" width="280" height="288" rx="10" fill="#fff" stroke="#64748b" stroke-width="1.4" stroke-dasharray="6 4"/>
   <text x="78" y="548" class="lbl">tier2 富游戏线（待建 · fork 起步）</text>
-  <text x="78" y="572" class="t sm">max_iters 放开（2.0.3 默认 20）</text>
+  <text x="78" y="572" class="t sm">max_iters 放开（2.0.2 默认 20）</text>
   <text x="78" y="592" class="mut xs">把多轮自治从外层 repair 循环</text>
   <text x="78" y="608" class="mut xs">搬进 Agent 内部 ReAct 循环</text>
   <!-- tier2 内循环示意 -->
@@ -77,7 +77,7 @@
   <line x1="64" y1="646" x2="82" y2="646" stroke="#64748b" stroke-width="1.4" stroke-dasharray="6 4" marker-end="url(#ahd)"/>
   <text x="200" y="748" class="mut xs" text-anchor="middle">无状态 Agent（统一 Agent 类）</text>
   <text x="200" y="766" class="mut xs" text-anchor="middle">reasoning-acting 循环内建驱动</text>
-  <rect x="78" y="780" width="244" height="20" rx="5" fill="#7c3aed"/><text x="200" y="794" class="bj" text-anchor="middle">独立锁 AgentScope 2.0.3 · 独立演进</text>
+  <rect x="78" y="780" width="244" height="20" rx="5" fill="#7c3aed"/><text x="200" y="794" class="bj" text-anchor="middle">独立锁 AgentScope 2.0.2 · 独立演进</text>
 
   <!-- ============ 中:ReAct 一轮(核心) ============ -->
   <text x="700" y="184" class="lbl" text-anchor="middle">ReAct 一轮（想一步 · 调一个工具 · 看结果）</text>

docs/architecture/架构/生成引擎/assets/t2-C-02-M3原生接法.svg

@@ -16,7 +16,7 @@
 
   <!-- 状态约定条:整图待建 -->
   <rect x="40" y="74" width="1400" height="46" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；接法本身（官方 AnthropicChatModel，AgentScope 2.0.3 源码已核）可信。</text>
+  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；接法本身（官方 AnthropicChatModel，AgentScope 2.0.2 源码已核）可信。</text>
   <text x="58" y="114" class="mut xs">实线 = 现行已落（new-api 计费平面 / NEWAPI_KEY 出口）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（M3 原生接法、thinking 分离、工具循环）。</text>
 
   <!-- ============ 主链路(横向) ============ -->
@@ -25,13 +25,13 @@
   <text x="58" y="190" class="box">tier2 agent</text>
   <rect x="58" y="202" width="58" height="20" rx="5" fill="#7c3aed"/><text x="87" y="216" class="bj" text-anchor="middle">待建</text>
   <text x="58" y="244" class="mut xs">单写 ReAct agent</text>
-  <text x="58" y="262" class="mut xs">（AgentScope 2.0.3）</text>
+  <text x="58" y="262" class="mut xs">（AgentScope 2.0.2）</text>
 
   <!-- ② AnthropicChatModel -->
   <rect x="318" y="160" width="268" height="120" rx="10" fill="#fff" stroke="#64748b" stroke-width="1.5" stroke-dasharray="6 4"/>
   <text x="336" y="190" class="box">AnthropicChatModel</text>
   <rect x="336" y="202" width="58" height="20" rx="5" fill="#7c3aed"/><text x="365" y="216" class="bj" text-anchor="middle">待建</text>
-  <text x="336" y="244" class="mut xs">AgentScope 2.0.3 官方模型类</text>
+  <text x="336" y="244" class="mut xs">AgentScope 2.0.2 官方模型类</text>
   <text x="336" y="262" class="mut xs">构造不传 formatter → 自动配对</text>
   <text x="336" y="278" class="mut xs mono">AnthropicChatFormatter</text>
 
@@ -80,7 +80,7 @@
   <text x="531" y="396" class="t sm mono">thinking_enable / thinking_budget</text>
   <text x="531" y="424" class="mut xs">硬约束：max_tokens ＞ thinking_budget</text>
   <text x="531" y="444" class="mut xs">budget 缺省取 max_tokens 的一半。</text>
-  <text x="531" y="466" class="mut xs">若 budget ≥ max_tokens：2.0.3 自动把</text>
+  <text x="531" y="466" class="mut xs">若 budget ≥ max_tokens：2.0.2 自动把</text>
   <text x="531" y="486" class="mut xs">max_tokens 抬到 budget+1024 — 别依赖兜底，显式设对。</text>
 
   <!-- 要点③ 完整 response/历史保留 -->
@@ -107,5 +107,5 @@
   <text x="58" y="752" class="mut xs">不论走哪条端点，计量都收口到 new-api 的 quota 口径（per-model 折¥）— 一个计费平面，成本可对账。</text>
 
   <!-- 脚注 -->
-  <text x="40" y="804" class="mut xs">映射：docs/architecture/架构/生成引擎/tier2实现详设.md §模型矩阵与样本量（M3 行接法说明）· 项目记忆 m3-agentic-anthropic-protocol（Anthropic 原生 thinking ＋ 工具循环）｜ 状态：建（M3 接法走官方 AnthropicChatModel，AgentScope 2.0.3 已核）｜ 设计变动须同步本图</text>
+  <text x="40" y="804" class="mut xs">映射：docs/architecture/架构/生成引擎/tier2实现详设.md §模型矩阵与样本量（M3 行接法说明）· 项目记忆 m3-agentic-anthropic-protocol（Anthropic 原生 thinking ＋ 工具循环）｜ 状态：建（M3 接法走官方 AnthropicChatModel，AgentScope 2.0.2 已核）｜ 设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/t2-C-03-四道熔断.svg

@@ -26,7 +26,7 @@
   <text x="58" y="254" class="gate">① 步数硬顶 · 防靠运气擦边</text>
   <text x="58" y="282" class="t sm">每系统 build-修复步数上限；整局 ≤ max_iters</text>
   <text x="58" y="312" class="mut xs">建议★ 单系统 ≤ 8 轮、整局 ≤ 40 轮；超 max_iters 即判不收敛</text>
-  <text x="58" y="332" class="mut xs">走 AgentScope ReActConfig.max_iters（2.0.3 默认 20，tier2 放开）</text>
+  <text x="58" y="332" class="mut xs">走 AgentScope ReActConfig.max_iters（2.0.2 默认 20，tier2 放开）</text>
   <text x="58" y="352" class="mut xs">防模型靠多轮反复试错把门擦边混过，而非真收敛</text>
   <rect x="58" y="370" width="42" height="22" rx="5" fill="#16a34a"/><text x="79" y="385" class="bj" text-anchor="middle">可靠</text>
   <rect x="108" y="370" width="42" height="22" rx="5" fill="#16a34a"/><text x="129" y="385" class="bj" text-anchor="middle">成本</text>

docs/architecture/架构/生成引擎/assets/t2-C-04-多轮范式承amodel.svg

@@ -20,7 +20,7 @@
   <!-- 状态约定条 -->
   <rect x="40" y="74" width="1400" height="58" rx="10" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.6"/>
   <text x="58" y="100" class="t sm">整图状态 = 建（范式承 A-model 已落 / tier2 fork 演进、待 0号 spike）。</text>
-  <text x="58" y="120" class="mut xs">实线 = 现行已落（wg1 studio.py 单轮 + repair · amodel-gen 多轮 JS harness，均 working reference）；虚线 = tier2 专属、待建（Python·AgentScope 2.0.3 多轮自治造 Phaser 富游戏）。</text>
+  <text x="58" y="120" class="mut xs">实线 = 现行已落（wg1 studio.py 单轮 + repair · amodel-gen 多轮 JS harness，均 working reference）；虚线 = tier2 专属、待建（Python·AgentScope 2.0.2 多轮自治造 Phaser 富游戏）。</text>
   <rect x="1322" y="86" width="100" height="22" rx="5" fill="#15803d"/><text x="1372" y="101" class="bj" text-anchor="middle">质量</text>
 
   <!-- 三态演进带 -->
@@ -52,7 +52,7 @@
   <rect x="1024" y="182" width="416" height="190" rx="10" fill="#faf5ff" stroke="#7c3aed" stroke-width="1.8" stroke-dasharray="6 4"/>
   <text x="1042" y="210" class="gate">③ tier2 · Phaser 富游戏</text>
   <rect x="1300" y="194" width="124" height="20" rx="5" fill="#7c3aed"/><text x="1362" y="208" class="bj" text-anchor="middle">tier2 待建（虚线）</text>
-  <text x="1042" y="236" class="t sm">Python · AgentScope 2.0.3 多轮自治</text>
+  <text x="1042" y="236" class="t sm">Python · AgentScope 2.0.2 多轮自治</text>
   <text x="1042" y="262" class="mut xs">放开 max_iters → Agent 内 ReAct 多轮</text>
   <text x="1042" y="282" class="mut xs">reason → act 写源 → 读 verdict → 再 reason</text>
   <text x="1042" y="302" class="mut xs">种子仍是 studio.py（Python）</text>
@@ -100,7 +100,7 @@
   <text x="58" y="640" class="t sm">边界说明 · fork 演进而非返工（创始人 2026-06-23 裁：两线分立、不收敛）</text>
   <text x="58" y="668" class="mut xs">复用躯干：tier2 复用 studio 那套多角色 prompt 与生成域（design / code / fix）的躯干，把「多轮」从外层 repair 循环搬进 Agent 内部 ReAct（max_iters 放开）。</text>
   <text x="58" y="690" class="mut xs">接法 A（七成已建）是接法 B（ReAct 自治）的躯干 evolve——是 fork 起步、独立演进、运行期零依赖现有 worker，不是推倒重来。</text>
-  <text x="58" y="712" class="mut xs">种子归属：种子仍是 studio.py（Python · 框架接缝 6 符号在 2.0.3 兼容、版本钉级别）；amodel-gen 只作 working reference（JS · 参照循环范式，不照搬）。</text>
+  <text x="58" y="712" class="mut xs">种子归属：种子仍是 studio.py（Python · 框架接缝 6 符号在 2.0.2 兼容、版本钉级别）；amodel-gen 只作 working reference（JS · 参照循环范式，不照搬）。</text>
   <text x="58" y="734" class="mut xs">重写面（≠平移）：validate / run / prompt / roles 是 LittleJS 专属，按 Phaser 重写、工作量约等于 net-new——别被「6 符号兼容」误导成「整个 U2 是平移」。</text>
   <rect x="58" y="748" width="1364" height="44" rx="8" fill="#faf5ff" stroke="#7c3aed" stroke-width="1.3" stroke-dasharray="6 4"/>
   <text x="74" y="770" class="t xs">tier2 待建（虚线）：amodel-gen 合并 dev/2.0.0 后，循环范式以合并后版本为参照系重取；多轮 ReAct / Workspace / Service 是 net-new 的真功夫（Phase B）。</text>

docs/architecture/架构/生成引擎/assets/t2-E-03-prompt两阶段角色.svg

@@ -17,12 +17,12 @@
   </defs>
   <rect x="0" y="0" width="1480" height="940" fill="#f8fafc"/>
   <text x="40" y="38" class="t h1">图 E3 · prompt 两阶段角色（族 E）</text>
-  <text x="40" y="60" class="mut sm">阶段 1 工作室设计用 Agent Team 多 agent 发散 + 专业分工；阶段 2 收敛到单写实现防并行写冲突。内部拓扑照 AgentScope 2.0.3 真 API 画。</text>
+  <text x="40" y="60" class="mut sm">阶段 1 工作室设计用 Agent Team 多 agent 发散 + 专业分工；阶段 2 收敛到单写实现防并行写冲突。内部拓扑照 AgentScope 2.0.2 真 API 画。</text>
 
   <!-- 状态约定条 -->
   <rect x="40" y="72" width="1400" height="56" rx="10" fill="#f1f5f9" stroke="#64748b" stroke-width="1.4" stroke-dasharray="6 4"/>
   <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码，故 tier2 专属新机制一律画虚线（待建）；承袭现行已落的（九门 harness / A-model）画实线。</text>
-  <text x="58" y="118" class="mut xs">虚线框 + 「建」小标 = tier2 待建；实线框 = 现行已落。Agent Team 与单写 ReAct 的内部拓扑均照 AgentScope 2.0.3 源码实证（/root/oss/agentscope 逐条核过）。</text>
+  <text x="58" y="118" class="mut xs">虚线框 + 「建」小标 = tier2 待建；实线框 = 现行已落。Agent Team 与单写 ReAct 的内部拓扑均照 AgentScope 2.0.2 源码实证（/root/oss/agentscope 逐条核过）。</text>
   <!-- 维度徽章 -->
   <rect x="1196" y="40" width="58" height="20" rx="5" fill="#15803d"/><text x="1225" y="54" class="bj" text-anchor="middle">质量</text>
   <rect x="1262" y="40" width="86" height="20" rx="5" fill="#7c3aed"/><text x="1305" y="54" class="bj" text-anchor="middle">伸缩·多agent</text>
@@ -79,11 +79,11 @@
   <text x="778" y="204" class="t sm">worker 只拿到 TeamSay —— 只能把结果报回 leader。</text>
   <text x="778" y="228" class="t sm">禁止 worker 之间互评 / 互相喊话，所有协调都过 leader 这个中心。</text>
   <rect x="778" y="244" width="644" height="64" rx="8" fill="#fef2f2" stroke="#dc2626" stroke-width="1.3"/>
-  <text x="794" y="268" class="t xs" font-weight="700">2.0.3 删掉了进程内的 MsgHub / pipeline。</text>
+  <text x="794" y="268" class="t xs" font-weight="700">2.0.2 删掉了进程内的 MsgHub / pipeline。</text>
   <text x="794" y="290" class="mut xs">进程内多 agent 协作那套没有了，只剩部署态的 Agent Team（TeamCreate / AgentCreate / TeamSay）。</text>
   <rect x="778" y="320" width="160" height="22" rx="5" fill="#dc2626"/><text x="858" y="335" class="bj" text-anchor="middle">禁 worker 互喊话</text>
   <rect x="946" y="320" width="160" height="22" rx="5" fill="#7c3aed"/><text x="1026" y="335" class="bj" text-anchor="middle">只剩部署态 Agent Team</text>
-  <text x="778" y="364" class="mut xs">工作室建在这套 Agent Team 上，不去找已不存在的 MsgHub。多 agent 边界照 2.0.3 源码核过，免照旧版资料踩坑。</text>
+  <text x="778" y="364" class="mut xs">工作室建在这套 Agent Team 上，不去找已不存在的 MsgHub。多 agent 边界照 2.0.2 源码核过，免照旧版资料踩坑。</text>
 
   <!-- ===== 阶段 2：单写实现 ===== -->
   <rect x="760" y="400" width="680" height="248" rx="12" fill="#faf5ff" stroke="#7c3aed" stroke-width="1.6" stroke-dasharray="6 4"/>
@@ -126,5 +126,5 @@
   <text x="58" y="714" class="mut xs">「单写者」专指阶段 2 写代码环节，不是整轨只一个 agent：阶段 1 设计用多 agent 要发散 + 专业分工，阶段 2 实现收敛到单写要防并行写冲突。</text>
   <text x="58" y="738" class="mut xs">承袭实线 = 九门 harness / A-model（现行已落，见 D2）；tier2 专属新机制（Agent Team 星形 / 单写 ReAct 多轮）= 虚线待建，待 0号 spike 验证。</text>
 
-  <text x="40" y="922" class="mut xs">映射：tier2实现详设.md §「运行时形态：两阶段、service 化与 session 三路径」 · 自治富游戏引擎.md §「换一种生成方式」+§「谁在写：单写者 ReAct」 ｜ 状态：建（阶段1 Agent Team / 阶段2 单写，2.0.3 API 已核）｜ 设计变动须同步本图</text>
+  <text x="40" y="922" class="mut xs">映射：tier2实现详设.md §「运行时形态：两阶段、service 化与 session 三路径」 · 自治富游戏引擎.md §「换一种生成方式」+§「谁在写：单写者 ReAct」 ｜ 状态：建（阶段1 Agent Team / 阶段2 单写，2.0.2 API 已核）｜ 设计变动须同步本图</text>
 </svg>

docs/architecture/架构/生成引擎/assets/t2-G-01-建设五步与spike门.svg

@@ -24,7 +24,7 @@
   <!-- 状态约定条:整图待建 -->
   <rect x="40" y="74" width="1400" height="46" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；故 tier2 专属新机制（spike 门、五步路径、隐藏硬工作）一律画虚线。</text>
-  <text x="58" y="114" class="mut xs">实线 = 承袭现行已落（AgentScope 2.0.3 官方件 / SAA 廉价线 / L1 九门 / W-CH-α 渠道路）；虚线（stroke-dasharray 6 4）= 待建；远期紫 = 远期不投核心循环（Cocos）。</text>
+  <text x="58" y="114" class="mut xs">实线 = 承袭现行已落（AgentScope 2.0.2 官方件 / SAA 廉价线 / L1 九门 / W-CH-α 渠道路）；虚线（stroke-dasharray 6 4）= 待建；远期紫 = 远期不投核心循环（Cocos）。</text>
 
   <!-- ====================== 左主干:五步纵列 ====================== -->
   <text x="40" y="156" class="t sm" font-weight="700">建设主干（纵向五步 · spike 门插在第二步与第三步之间）</text>
@@ -33,7 +33,7 @@
   <rect x="40" y="172" width="700" height="74" rx="10" fill="#fff" stroke="#64748b" stroke-width="1.5" stroke-dasharray="6 4"/>
   <rect x="58" y="186" width="78" height="20" rx="5" fill="#7c3aed"/><text x="97" y="200" class="bj" text-anchor="middle">第一步 · 建</text>
   <text x="148" y="201" class="box">搭 AgentScope、完成集成</text>
-  <text x="58" y="228" class="mut xs">agent ＋ 循环的运行时底座（统一 Agent 类 · max_iters 放开为 Agent 内 ReAct 多轮）。从 L2 studio 编排演进，非 L1 裸 openai 主线；tier2 独立锁 2.0.3、fork 起步。</text>
+  <text x="58" y="228" class="mut xs">agent ＋ 循环的运行时底座（统一 Agent 类 · max_iters 放开为 Agent 内 ReAct 多轮）。从 L2 studio 编排演进，非 L1 裸 openai 主线；tier2 独立锁 2.0.2、fork 起步。</text>
 
   <!-- 第二步 -->
   <rect x="40" y="262" width="700" height="74" rx="10" fill="#fff" stroke="#64748b" stroke-width="1.5" stroke-dasharray="6 4"/>

docs/architecture/架构/生成引擎/assets/t2-G-04-过门阈值与采集字段.svg

@@ -55,7 +55,7 @@
   <rect x="58" y="380" width="58" height="20" rx="5" fill="#15803d"/><text x="87" y="394" class="bj" text-anchor="middle">质量</text>
   <text x="126" y="395" class="t sm">≤ max_iters（<tspan class="star">★</tspan> 单系统 ≤ 8 轮 · 整局 ≤ 40 轮）</text>
   <text x="58" y="420" class="mut xs">来源：防靠运气擦边；超 max_iters 即判不收敛。</text>
-  <text x="58" y="438" class="mut xs">对照第一步 AgentScope 2.0.3 ReActConfig.max_iters 默认 20；tier2 自治放开。</text>
+  <text x="58" y="438" class="mut xs">对照第一步 AgentScope 2.0.2 ReActConfig.max_iters 默认 20；tier2 自治放开。</text>
 
   <!-- ④ 长程一致性 -->
   <rect x="755" y="342" width="685" height="118" rx="9" fill="#fff" stroke="#64748b" stroke-width="1.4" stroke-dasharray="6 4"/>

docs/architecture/架构/生成引擎/assets/t2-H-02-观测管道.svg

@@ -19,7 +19,7 @@
 
   <!-- 状态约定条 -->
   <rect x="40" y="74" width="1290" height="46" rx="9" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码。Event System / TracingMiddleware / OTel / Studio 是 AgentScope 2.0.3 官方现成件（源码已核），adapter 为自建。</text>
+  <text x="58" y="98" class="t sm">整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码。Event System / TracingMiddleware / OTel / Studio 是 AgentScope 2.0.2 官方现成件（源码已核），adapter 为自建。</text>
   <text x="58" y="114" class="mut xs">实线 = 官方现成件 / SAA 廉价线已落 / 已有件；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（订阅事件流、adapter、统一 trace 契约位）。</text>
 
   <!-- 可观测徽章 -->

docs/architecture/架构/生成引擎/tier2四层工程架构.md

@@ -1,21 +1,21 @@
 # tier2 四层工程架构
 
-> 🚧 评审版 · **已纳入 AGENTS.md §6.8 Codex+Opus 双评审发现并修订**;**并据《[agentic 运行时架构图说](agentic运行时架构图说.md)》(基于 agentscope 2.0.3 源码实证)做了一次架构校正(2026-06-22),用现行真相 supersede 了若干旧表述,见各节内说明**;残留跨档项见 §11。基于《[tier2 实现详设](tier2实现详设.md)》,尚未落代码;过了 0号 spike 才进建设。
+> 🚧 评审版 · **已纳入 AGENTS.md §6.8 Codex+Opus 双评审发现并修订**;**并据《[agentic 运行时架构图说](agentic运行时架构图说.md)》(基于 agentscope 2.0.2 源码实证)做了一次架构校正(2026-06-22),用现行真相 supersede 了若干旧表述,见各节内说明**;残留跨档项见 §11。基于《[tier2 实现详设](tier2实现详设.md)》,尚未落代码;过了 0号 spike 才进建设。
 
 > **这是什么**:tier2 自治富游戏轨作为一个**独立 AgentScope 模块**的内部工程架构 —— 拆成 **environment / harness / context / prompt** 四层,逐层说清职责、边界、复用 AgentScope 的哪些能力、**哪些是硬代码、哪些可配置**、是复用/启用/新建。
-> **重要校正(2026-06-22)**:这四层**不是 AgentScope 的真实对象结构,而是一个"职责视角"** —— 它叠在 AgentScope 2.0.3 的真实结构(Agent / Workspace / Toolkit / Middleware / AgentState / Agent Service)之上。读本档时请始终带着这层对应关系:environment 这个职责对应的真实载体是 **Workspace**(它沿两轴注入 Agent,Agent 持有它的引用、并不嵌在它里面);harness 这个职责对应的是 **Agent 的 ReAct 循环原语 + Middleware 洋葱 + 自建验收门**;context / prompt 则是组装进模型窗口的运行时载荷与离线指令。术语逐项映射见图说 §6。
+> **重要校正(2026-06-22)**:这四层**不是 AgentScope 的真实对象结构,而是一个"职责视角"** —— 它叠在 AgentScope 2.0.2 的真实结构(Agent / Workspace / Toolkit / Middleware / AgentState / Agent Service)之上。读本档时请始终带着这层对应关系:environment 这个职责对应的真实载体是 **Workspace**(它沿两轴注入 Agent,Agent 持有它的引用、并不嵌在它里面);harness 这个职责对应的是 **Agent 的 ReAct 循环原语 + Middleware 洋葱 + 自建验收门**;context / prompt 则是组装进模型窗口的运行时载荷与离线指令。术语逐项映射见图说 §6。
 > **给谁看**:要搭这个独立模块的工程师;拿它去 ce-plan 排执行的人;评审四层切分、硬/软边界、复用契约是否成立的人。
-> **与邻档关系**:《[自治富游戏引擎](自治富游戏引擎.md)》给内核范式(O2 约束自治、Phaser/Pixi 选型、效果验收),《[tier2 实现详设](tier2实现详设.md)》给源项目契约+0号 spike runbook+建设五步+退路树,《[agentic 集成架构](agentic集成架构.md)》给两线共用的控制/管理面,《[agentic 运行时架构图说](agentic运行时架构图说.md)》给整条生命周期的看图入口 + agentscope 2.0.3 源码实证的术语映射。**本档只回答:这个独立模块内部怎么按四层职责把地基搭起来** —— 是建设五步第一、二步(底座 + 配置外置)的工程落点,不重排那几份。
+> **与邻档关系**:《[自治富游戏引擎](自治富游戏引擎.md)》给内核范式(O2 约束自治、Phaser/Pixi 选型、效果验收),《[tier2 实现详设](tier2实现详设.md)》给源项目契约+0号 spike runbook+建设五步+退路树,《[agentic 集成架构](agentic集成架构.md)》给两线共用的控制/管理面,《[agentic 运行时架构图说](agentic运行时架构图说.md)》给整条生命周期的看图入口 + agentscope 2.0.2 源码实证的术语映射。**本档只回答:这个独立模块内部怎么按四层职责把地基搭起来** —— 是建设五步第一、二步(底座 + 配置外置)的工程落点,不重排那几份。
 
 ---
 
 ## 1. 三个定调:独立模块 + 复用契约 + 四层职责视角
 
-### 1.1 独立模块,SAA 可删,独立锁定 AgentScope 2.0.3
+### 1.1 独立模块,SAA 可删,独立锁定 AgentScope 2.0.2
 
 tier2 是一个**独立的 AgentScope 模块**:自己的运行环境、依赖、工具、演进节奏,对现有 SAA 廉价线(game-cloud 里 Java 写的 16 节点 StateGraph)**运行期零耦合**。这把《自治富游戏引擎》那条最硬边界("tier2 任何改动不许碰、不许回归现有廉价线")推到逻辑终点。
 
-因为是独立 env、独立锁版,tier2 **把 AgentScope 版本钉死在 2.0.3**,与 SAA 线不强制同版,规避破坏式升级的版本耦合(2.0 是对 1.x 的破坏式重写)。本档后文一切 AgentScope API 都以 **2.0.3 源码实证**为准(`/root/oss/agentscope`,逐条核过):**没有独立的 `ReActAgent` 类**——统一是 `Agent` + `ReActConfig`(`max_iters` 默认 20);拦截扩展点是 **`MiddlewareBase` 洋葱**(6 个 hook:`on_reasoning` / `on_reply` / `on_acting` / `on_model_call` / `on_compress_context` / `on_system_prompt`),**不是 agent hooks**;状态载体是 **pydantic `AgentState`**(含 `cur_iter` / `context` / `tasks_context`),**不是 1.x 的 `state_dict` / Session**;**`agentscope.init(studio_url=…)` 不存在**——可观测走纯 OTel(`TracingMiddleware`)。⚠️ 这几条 supersede 了本档早稿里"2.0.1"、"`ReActAgent`"、"`state_dict` checkpoint"、"`Studio` trace / `agentscope.init`"的旧假设。
+因为是独立 env、独立锁版,tier2 **把 AgentScope 版本钉死在 2.0.2**,与 SAA 线不强制同版,规避破坏式升级的版本耦合(2.0 是对 1.x 的破坏式重写)。本档后文一切 AgentScope API 都以 **2.0.2 源码实证**为准(`/root/oss/agentscope`,逐条核过):**没有独立的 `ReActAgent` 类**——统一是 `Agent` + `ReActConfig`(`max_iters` 默认 20);拦截扩展点是 **`MiddlewareBase` 洋葱**(6 个 hook:`on_reasoning` / `on_reply` / `on_acting` / `on_model_call` / `on_compress_context` / `on_system_prompt`),**不是 agent hooks**;状态载体是 **pydantic `AgentState`**(含 `cur_iter` / `context` / `tasks_context`),**不是 1.x 的 `state_dict` / Session**;**`agentscope.init(studio_url=…)` 不存在**——可观测走纯 OTel(`TracingMiddleware`)。⚠️ 这几条 supersede 了本档早稿里"2.0.1"、"`ReActAgent`"、"`state_dict` checkpoint"、"`Studio` trace / `agentscope.init`"的旧假设。
 
 **对外暴露方式 = service 化、用官方 Agent Service,不自造 API**(2026-06-22 校正):tier2 是一个独立 service,game-cloud 经它调用;但它**不自己手搓 REST/会话层**,而是直接用 AgentScope 官方的 **Agent Service** —— `create_app` 起 FastAPI,自带 **REST + SSE**(流式 event,断线可 replay)、多租户、durable 会话。会话初始化有三条加载入口:① 续接之前会话(取历史 resume)② 加载已有游戏工程(`Workspace.workdir` 指向已有目录 → 迭代)③ 新建(阶段 2 模板初始化工具铺模板)。这条与"Agent 非常驻"一致:Service 收到一次 run 请求才现组装 Agent,状态落 `AgentState`。
 
@@ -25,7 +25,7 @@ tier2 是一个**独立的 AgentScope 模块**:自己的运行环境、依赖、
 
 双评审最重的一组发现(Opus B1/M2/M4、Codex M1/M6)是:本档曾把"上游库有某 API"或"框架理论提供某能力"笼统写成"复用",夸大了地基的现成度。**2026-06-22 校正进一步把复用判断收敛成一张二维坐标**(supersede 早稿那种把"复用/边界"扁平列举的画法):
 
-- **维度一·来源**:官方现成(AgentScope 2.0.3 自带) vs 自建(tier2 或两线团队自己写)。
+- **维度一·来源**:官方现成(AgentScope 2.0.2 自带) vs 自建(tier2 或两线团队自己写)。
 - **维度二·共享**:两线公共(SAA 廉价线与 tier2 都用) vs tier2 私有。
 
 由这两维交叉出关键结论:**"公共组件 = 自建 ∩ 共享" —— 它们是团队自建的、被两线共用的件(九门 / 三层校验 / CDP / 计费 / 送审 / feed / trace),不是现成的官方能力**。别把"框架里有"误当成"公共组件"。完整二维全景见图说图 6,本节只点出对四层地基影响最大的一条校正:
@@ -41,7 +41,7 @@ tier2 是一个**独立的 AgentScope 模块**:自己的运行环境、依赖、
 | 经验召回 | 拟自建案例库 | `ReMe`(经验/记忆框架) |
 | 多 agent 总线 | 拟自建协调 | `Agent Team`(`TeamCreate`/`AgentCreate`/`TeamSay`) |
 
-> ⚠️ 一处实证差异、需创始人确认:在 `/root/oss/agentscope` 2.0.3 源码里,**树内捆绑的长期记忆后端是 `mem0` middleware**;"经验召回 `ReMe`"是 AgentScope 生态里独立的记忆框架,本档沿用图说(SoT)的 `ReMe` 口径登记。落地选 `ReMe` 还是树内 `mem0`,留 spike 前小验证 + 创始人定。
+> ⚠️ 一处实证差异、需创始人确认:在 `/root/oss/agentscope` 2.0.2 源码里,**树内捆绑的长期记忆后端是 `mem0` middleware**;"经验召回 `ReMe`"是 AgentScope 生态里独立的记忆框架,本档沿用图说(SoT)的 `ReMe` 口径登记。落地选 `ReMe` 还是树内 `mem0`,留 spike 前小验证 + 创始人定。
 
 **官方"没有"的(别误指望):无 RAG / 向量检索的现成检索管线(只有 `embedding/` 模型封装,不含 retriever);无 `evaluate` 评测模块;A2A 仅有基座、非成品。** 这三项要么自建、要么按需引第三方。
 
@@ -55,8 +55,8 @@ flowchart TB
     subgraph B["② 一次性种子拷贝(运行期零依赖)"]
         B1["studio.py 的 AgentScope 用法 → 拷贝起步、独立演进、不回写"]
     end
-    subgraph C["③ tier2 自有依赖(独立 env · 锁 2.0.3)"]
-        C1["agentscope core 2.0.3(Agent/ReActConfig/AgentState/Middleware/Workspace/skills)"]
+    subgraph C["③ tier2 自有依赖(独立 env · 锁 2.0.2)"]
+        C1["agentscope core 2.0.2(Agent/ReActConfig/AgentState/Middleware/Workspace/skills)"]
         C2["agentscope-runtime 沙箱 = 待验证候选(见 §3 · 当前全仓零引用)"]
     end
     subgraph D["④ 运行期禁止依赖(forbidden-import 守门)"]
@@ -68,10 +68,10 @@ flowchart TB
 
 - **① 外部包复用**:`cost.py`、`_client.py` 是稳定 IO 边界,真·仓内现成。但复用要**纯函数/显式传参** —— endpoint / key / model / pricing / quota / retry / timeout 全显式传入,**禁止沿用共享全局状态**(否则会暗中继承 SAA/L2 的模型路由与预算表,"SAA 可删"就成空话)。
 - **② 种子拷贝**:`studio.py` 的写法拷来起步,但运行期不 import 现有 worker。
-- **③ tier2 自有依赖**:agentscope core 是 tier2 **自己 env 里独立安装、锁 2.0.3** 的(用户定调"独立周边环境")——所以它**不是"与 SAA 共享的复用底座"**。`agentscope-runtime` 是**独立 PyPI 包、当前全仓零引用**,降级为**待验证候选**(§3)。
+- **③ tier2 自有依赖**:agentscope core 是 tier2 **自己 env 里独立安装、锁 2.0.2** 的(用户定调"独立周边环境")——所以它**不是"与 SAA 共享的复用底座"**。`agentscope-runtime` 是**独立 PyPI 包、当前全仓零引用**,降级为**待验证候选**(§3)。
 - **④ 禁止依赖**:加一道 **forbidden-import 检查**(§11 跨档 TODO,CI 侧),从机制上保证运行期不碰 SAA。
 
-> 这条契约直接消解了 v1 的内部不一致("§1.1 说复用三样、§8 却列四样"):**真·外部复用只有 cost.py + _client.py;agentscope 2.0.3 是 tier2 自有依赖;runtime 是候选;studio.py 是种子拷贝;且上表 6 项从"自建"上修为"用官方"。**
+> 这条契约直接消解了 v1 的内部不一致("§1.1 说复用三样、§8 却列四样"):**真·外部复用只有 cost.py + _client.py;agentscope 2.0.2 是 tier2 自有依赖;runtime 是候选;studio.py 是种子拷贝;且上表 6 项从"自建"上修为"用官方"。**
 
 ### 1.3 四层是"职责视角",叠在 AgentScope 真实对象结构上
 
@@ -79,7 +79,7 @@ flowchart TB
 
 其一,**"environment / harness / context / prompt 四层"不是业界主流原话**。主流(2025-2026)是**三层嵌套**:`prompt ⊂ context ⊂ harness`,environment 通常并进 harness 当"对外数据面"(Deepset:*"Prompt engineering is a subset of context engineering"*;Anthropic context engineering 定义见 §验证状态 来源)。本档把它拆四层,是为了对"单写者 ReAct + 跑确定性门"这种模块讲得更清晰。
 
-其二(**校正 · supersede 早稿"把 harness 劈成数据面 + 控制面、两面互相 act/观测"的画法**):这四层**不是 AgentScope 的真实对象,而是一个职责视角**,叠在 2.0.3 的真实结构之上。早稿那张"harness 全域里 harness 控制面 ↔ environment 数据面互相调用"的图,容易让人误以为 environment 是一个被 harness 调用的并列数据面 —— **这与源码不符**。真实结构是:
+其二(**校正 · supersede 早稿"把 harness 劈成数据面 + 控制面、两面互相 act/观测"的画法**):这四层**不是 AgentScope 的真实对象,而是一个职责视角**,叠在 2.0.2 的真实结构之上。早稿那张"harness 全域里 harness 控制面 ↔ environment 数据面互相调用"的图,容易让人误以为 environment 是一个被 harness 调用的并列数据面 —— **这与源码不符**。真实结构是:
 
 - **environment 这个职责的真实载体 = `Workspace`**(Local/Docker/E2B),它是 **Agent 的执行环境**,沿**两轴注入 Agent**:① 把资源(tools / MCP / skills)经 `get_toolkit` 汇成 **`Toolkit`** 交给 Agent;② 它本身作为 **offloader**(上下文/工具结果卸载)挂在 Agent 上。
 - 所以 **Agent 持有 Workspace 的引用,Agent 并不嵌在 Workspace 里、Workspace 也不"调用"Agent**。真正"跑在 Workspace 里"的是 MCP 进程 / skills / 文件这些资源。
@@ -139,13 +139,13 @@ flowchart TB
     style BREAK fill:#f5b7b1
 ```
 
-> 一处现状必须诚实(双评审 M1):仓内 `studio.py:159` 是 `ReActConfig(max_iters=1)` —— **当前是单轮、靠外层 repair 循环兜**,不是多轮自治 ReAct。2.0.3 里 `ReActConfig.max_iters` 默认 20,所以"门内任意迭代 + 步数硬顶"这层**是要放开 max_iters + 新建循环控制的,不是复用现成**;复用的只是 `Agent` + `ReActConfig` 这个原语。
+> 一处现状必须诚实(双评审 M1):仓内 `studio.py:159` 是 `ReActConfig(max_iters=1)` —— **当前是单轮、靠外层 repair 循环兜**,不是多轮自治 ReAct。2.0.2 里 `ReActConfig.max_iters` 默认 20,所以"门内任意迭代 + 步数硬顶"这层**是要放开 max_iters + 新建循环控制的,不是复用现成**;复用的只是 `Agent` + `ReActConfig` 这个原语。
 
 ---
 
 ## 3. environment 层(载体 = Workspace)—— agent 的工作站(候选底座待验)
 
-**校正(2026-06-22)**:environment 这个职责在 AgentScope 2.0.3 里的真实载体是 **`Workspace`** —— 它是 Agent 的执行环境,沿两轴注入 Agent(① 资源经 `get_toolkit` → `Toolkit`;② 本身作 offloader),`WorkspaceBase` 已有 **Local / Docker / E2B** 三实现。所以本层不是凭空"自建一个数据面",而是**在 `Workspace` 这个官方抽象上挂 tier2 要的工具与资源**;Agent 持有它的引用、并不嵌在里面。下面讨论的"给 agent 一台游戏工作站"(写多文件源码、构建、真浏览器跑、截图、查资产与文档),落地就是配 / 扩 `Workspace` 及其 Toolkit。
+**校正(2026-06-22)**:environment 这个职责在 AgentScope 2.0.2 里的真实载体是 **`Workspace`** —— 它是 Agent 的执行环境,沿两轴注入 Agent(① 资源经 `get_toolkit` → `Toolkit`;② 本身作 offloader),`WorkspaceBase` 已有 **Local / Docker / E2B** 三实现。所以本层不是凭空"自建一个数据面",而是**在 `Workspace` 这个官方抽象上挂 tier2 要的工具与资源**;Agent 持有它的引用、并不嵌在里面。下面讨论的"给 agent 一台游戏工作站"(写多文件源码、构建、真浏览器跑、截图、查资产与文档),落地就是配 / 扩 `Workspace` 及其 Toolkit。
 
 `Workspace` 自带的三实现解决"在哪跑、文件/shell 隔离"的问题,但**确定性硬门要的"真浏览器低层探针"是否够用,仍是承重前提、需先验**(双评审 B1/M7):一个候选是引 `agentscope-runtime` 的 `SandboxService`(CODE/Filesystem/Browser 三沙箱 + `sandbox_tool_adapter`)补浏览器探针;但 ——`agentscope-runtime` **当前全仓零引用、是独立 PyPI 包**,且 `requirements-l2.txt` 注释明写"本期只引 base、不引 service/storage"。所以它是**新增的待验证候选依赖,不是现成复用底座**;"上游有这个 API"(Context7 可查)**不等于**"装得进 tier2、挂得成 Toolkit、跑得了 esbuild + headless、且撑得住确定性探针"。
 
@@ -188,9 +188,9 @@ flowchart LR
 
 ## 4. harness 层 —— 控制面与三层校验(本模块重心)
 
-harness 是把模型变成 agent 的循环与脚手架:控制流、工具分发、校验门、熔断、checkpoint、可观测。tier2 的 harness **启用 AgentScope 2.0.3 的循环原语**(`Agent` + `ReActConfig`),拦截 / 预算 / 可观测**尽量挂在官方 `MiddlewareBase` 洋葱与官方 middleware 上**,**自己重写的只是验收门**。
+harness 是把模型变成 agent 的循环与脚手架:控制流、工具分发、校验门、熔断、checkpoint、可观测。tier2 的 harness **启用 AgentScope 2.0.2 的循环原语**(`Agent` + `ReActConfig`),拦截 / 预算 / 可观测**尽量挂在官方 `MiddlewareBase` 洋葱与官方 middleware 上**,**自己重写的只是验收门**。
 
-> 用词分级与 API 校正(双评审 M2 + 2026-06-22):checkpoint、记忆、skills、trace 这些**仓内代码一个都没用过**,是 agentscope 2.0.3 **框架提供、tier2 首次接通、行为待验**(2.0 是对 1.x 破坏式重写),本档一律标"**启用(待验)**",区别于 cost.py/_client.py 的"复用(已在跑)"。同时把早稿的 API 假设按 2.0.3 源码纠正:拦截扩展点是 **`MiddlewareBase` 洋葱(6 hook)**、不是 agent hooks;checkpoint 状态是 **pydantic `AgentState`**(`cur_iter`/`context`/`tasks_context`)落 StorageBase(Redis)、**不是 `state_dict`**;可观测是 **`TracingMiddleware`(纯 OTel)**、**不是 `Studio` trace / `agentscope.init(studio_url)`(后者不存在)**。
+> 用词分级与 API 校正(双评审 M2 + 2026-06-22):checkpoint、记忆、skills、trace 这些**仓内代码一个都没用过**,是 agentscope 2.0.2 **框架提供、tier2 首次接通、行为待验**(2.0 是对 1.x 破坏式重写),本档一律标"**启用(待验)**",区别于 cost.py/_client.py 的"复用(已在跑)"。同时把早稿的 API 假设按 2.0.2 源码纠正:拦截扩展点是 **`MiddlewareBase` 洋葱(6 hook)**、不是 agent hooks;checkpoint 状态是 **pydantic `AgentState`**(`cur_iter`/`context`/`tasks_context`)落 StorageBase(Redis)、**不是 `state_dict`**;可观测是 **`TracingMiddleware`(纯 OTel)**、**不是 `Studio` trace / `agentscope.init(studio_url)`(后者不存在)**。
 
 ### 4.1 三层校验:L1 硬约束 + L2 设计符合 + L3 效果软检(创始人定义 · M3 绝不阻塞)
 
@@ -260,7 +260,7 @@ flowchart LR
 
 ## 5. context 层 —— 运行时载荷
 
-context 是某步推理在窗口里组装的一切经策展的动态信息(prompt 是其子集)。它在 2.0.3 真实结构里就是 `AgentState.context`(工作记忆)+ 每步经 `formatter` 逐模型组装进窗口的载荷。tier2 这层**启用 AgentScope 的记忆/组装能力(待验)**:短期工作记忆(`AgentState.context`)、长期**经验召回用官方 `ReMe`**(2026-06-22 校正:经验/debug 案例库从"自建"改用官方记忆框架;⚠️树内捆绑后端实为 `mem0`,选型见 §1.2 注 + spike 前定)、`formatter` 逐模型组装;结构化输出走官方 `generate_structured_output`(model 层),不自建 schema 校验。工程上要设计的是**装什么、何时压**:
+context 是某步推理在窗口里组装的一切经策展的动态信息(prompt 是其子集)。它在 2.0.2 真实结构里就是 `AgentState.context`(工作记忆)+ 每步经 `formatter` 逐模型组装进窗口的载荷。tier2 这层**启用 AgentScope 的记忆/组装能力(待验)**:短期工作记忆(`AgentState.context`)、长期**经验召回用官方 `ReMe`**(2026-06-22 校正:经验/debug 案例库从"自建"改用官方记忆框架;⚠️树内捆绑后端实为 `mem0`,选型见 §1.2 注 + spike 前定)、`formatter` 逐模型组装;结构化输出走官方 `generate_structured_output`(model 层),不自建 schema 校验。工程上要设计的是**装什么、何时压**:
 
 ```mermaid
 flowchart LR
@@ -291,7 +291,7 @@ flowchart LR
 
 ## 6. prompt 层 —— 离线编写的指令(⊂ context)
 
-prompt 是塑造模型行为的**编写指令文本**:静态、离线写、版本化。tier2 这层**启用 AgentScope 2.0.3 的 `sys_prompt` 增广、`formatter`、以及原生 skills 机制(均待验)**。校正(2026-06-22):2.0.3 的 skills **不是 agent 级 `register_agent_skill` 注册**(早稿 API 名有误,源码无此函数),而是**挂在 `Workspace` 上的资源** —— `WorkspaceBase.add_skill(skill_path)` / `list_skills()` 加载带 `SKILL.md`(frontmatter 含 name)的技能目录,再经 `get_toolkit` 注入 Agent。也就是说 prompt 层的"skill"这一面,落地是配 Workspace 的 skill 目录,与 §3 environment 同源(都在 Workspace 上),正好对应 §6.1 的"一个 manifest、三层各持一面"。
+prompt 是塑造模型行为的**编写指令文本**:静态、离线写、版本化。tier2 这层**启用 AgentScope 2.0.2 的 `sys_prompt` 增广、`formatter`、以及原生 skills 机制(均待验)**。校正(2026-06-22):2.0.2 的 skills **不是 agent 级 `register_agent_skill` 注册**(早稿 API 名有误,源码无此函数),而是**挂在 `Workspace` 上的资源** —— `WorkspaceBase.add_skill(skill_path)` / `list_skills()` 加载带 `SKILL.md`(frontmatter 含 name)的技能目录,再经 `get_toolkit` 注入 Agent。也就是说 prompt 层的"skill"这一面,落地是配 Workspace 的 skill 目录,与 §3 environment 同源(都在 Workspace 上),正好对应 §6.1 的"一个 manifest、三层各持一面"。
 
 ### 6.1 引擎能力包:一个 manifest,三层各持一面(消除跨层泄漏)
 
@@ -385,12 +385,12 @@ flowchart LR
     subgraph REUSE["复用(已在跑)"]
         R1["cost.py · _client.py(显式传参 · 禁读 SAA 配置)"]
     end
-    subgraph OFF["官方现成(2.0.3 自带 · 6 项改用官方)"]
+    subgraph OFF["官方现成(2.0.2 自带 · 6 项改用官方)"]
         F1["ChatUsage 计量 · ReplyBudgetControlMiddleware 软预算"]
         F2["generate_structured_output · TracingMiddleware(OTel)"]
         F3["ReMe 经验召回 · Agent Team 多 agent 总线"]
     end
-    subgraph OWN["tier2 自有依赖(独立锁 2.0.3)"]
+    subgraph OWN["tier2 自有依赖(独立锁 2.0.2)"]
         O1["agentscope core(Agent/ReActConfig/AgentState/Middleware/Workspace · 启用待验)"]
         O2["agentscope-runtime(浏览器探针候选·待验·见 §3)"]
     end
@@ -465,4 +465,4 @@ flowchart LR
 
 ---
 
-> **验证状态**:评审版,未落代码,**已纳入 Codex+Opus §6.8 双评审发现并修订**,并据《agentic 运行时架构图说》(基于 **agentscope 2.0.3 源码实证**,`/root/oss/agentscope` 逐条核过)做了 2026-06-22 架构校正(B1+5/9 MAJOR + minors 档内已修,跨档见 §11)。本次校正的 API 事实均经源码复核:`_version.py = 2.0.3`;无 `ReActAgent`(`agent/_agent.py:93 class Agent` + `agent/_config.py:123 class ReActConfig`,`max_iters` 默认 20);`MiddlewareBase` 6 hook(`middleware/_base.py`);`AgentState(BaseModel)`(`state/_state.py:141`,含 `tasks_context`/`cur_iter`/`context`);`WorkspaceBase`(Local/Docker/E2B)+ `Offloader` + `get_toolkit`(`app/_service/_toolkit.py`)证 Workspace 两轴注入、Agent 持引用非嵌套;`create_app→FastAPI`(`app/_app.py:33`)= 官方 Agent Service;`ReplyBudgetControlMiddleware`/`TracingMiddleware`/`generate_structured_output`/`ChatUsage`/Agent Team(`_team_create`/`_agent_create`/`_team_say`)均在树;skills 经 `WorkspaceBase.add_skill`(无 `register_agent_skill`);`__init__.py` 无 `init(studio_url)`。**一处差异**:树内长期记忆后端是 `mem0` middleware,图说(SoT)以 `ReMe` 口径登记经验召回——选型待 spike 前定(§1.2 注)。"主流四层"经 web 研究核(主流实为 `prompt⊂context⊂harness` 三层嵌套、environment 并入 harness;本档四层据校正重定位为**叠在 AgentScope 真实对象结构上的职责视角**,来源 Anthropic context-engineering、Deepset、SWE-bench harness 等,完整 dossier 见研究留痕)。仓内实证:`studio.py:159 ReActConfig(max_iters=1)`、`requirements-l2.txt` 只引 agentscope base、`agentscope-runtime` 全仓零引用、`contracts/trace/` 不存在。硬/软、机制/策略边界承《自治富游戏引擎》与生成引擎设计主文档既有裁定。
+> **验证状态**:评审版,未落代码,**已纳入 Codex+Opus §6.8 双评审发现并修订**,并据《agentic 运行时架构图说》(基于 **agentscope 2.0.2 源码实证**,`/root/oss/agentscope` 逐条核过)做了 2026-06-22 架构校正(B1+5/9 MAJOR + minors 档内已修,跨档见 §11)。本次校正的 API 事实均经源码复核:`_version.py = 2.0.2`;无 `ReActAgent`(`agent/_agent.py:93 class Agent` + `agent/_config.py:123 class ReActConfig`,`max_iters` 默认 20);`MiddlewareBase` 6 hook(`middleware/_base.py`);`AgentState(BaseModel)`(`state/_state.py:141`,含 `tasks_context`/`cur_iter`/`context`);`WorkspaceBase`(Local/Docker/E2B)+ `Offloader` + `get_toolkit`(`app/_service/_toolkit.py`)证 Workspace 两轴注入、Agent 持引用非嵌套;`create_app→FastAPI`(`app/_app.py:33`)= 官方 Agent Service;`ReplyBudgetControlMiddleware`/`TracingMiddleware`/`generate_structured_output`/`ChatUsage`/Agent Team(`_team_create`/`_agent_create`/`_team_say`)均在树;skills 经 `WorkspaceBase.add_skill`(无 `register_agent_skill`);`__init__.py` 无 `init(studio_url)`。**一处差异**:树内长期记忆后端是 `mem0` middleware,图说(SoT)以 `ReMe` 口径登记经验召回——选型待 spike 前定(§1.2 注)。"主流四层"经 web 研究核(主流实为 `prompt⊂context⊂harness` 三层嵌套、environment 并入 harness;本档四层据校正重定位为**叠在 AgentScope 真实对象结构上的职责视角**,来源 Anthropic context-engineering、Deepset、SWE-bench harness 等,完整 dossier 见研究留痕)。仓内实证:`studio.py:159 ReActConfig(max_iters=1)`、`requirements-l2.txt` 只引 agentscope base、`agentscope-runtime` 全仓零引用、`contracts/trace/` 不存在。硬/软、机制/策略边界承《自治富游戏引擎》与生成引擎设计主文档既有裁定。

docs/architecture/架构/生成引擎/tier2实现详设.md

@@ -4,7 +4,7 @@
 
 > **这是什么**:tier2 自治富游戏轨的实现详设 —— 怎么对接、怎么建、怎么部署、怎么跑、怎么测、怎么验。
 > **给谁看**:要动手搭 tier2 的工程师,以及拿这份去跑 0号 spike、据结果裁 go/no-go 的人。
-> **看图入口**:整轨的生命周期与对象结构画在《[agentic 运行时架构图说](agentic运行时架构图说.md)》,本档与它同步。**框架机制以 AgentScope 2.0.3 源码实证为准**(`/root/oss/agentscope`,逐条核过):tier2 独立锁 2.0.3、从 fork 起步独立演进。
+> **看图入口**:整轨的生命周期与对象结构画在《[agentic 运行时架构图说](agentic运行时架构图说.md)》,本档与它同步。**框架机制以 AgentScope 2.0.2 源码实证为准**(`/root/oss/agentscope`,逐条核过):tier2 独立锁 2.0.2、从 fork 起步独立演进。
 
 ## 第一批工程定义:源项目契约
 
@@ -30,15 +30,15 @@ tier2 这条 ReAct 轨每跑一次,要把"想一步、调一个工具、看结
 
 ## 运行时形态:两阶段、service 化与 session 三路径
 
-要动手搭 tier2,先得在脑子里钉死它跑起来长什么样——下面这几条是照 AgentScope 2.0.3 源码实证过的实现契约,完整的看图入口在《agentic 运行时架构图说》,本节只交代建设要落到代码上的那几条硬事实。
+要动手搭 tier2,先得在脑子里钉死它跑起来长什么样——下面这几条是照 AgentScope 2.0.2 源码实证过的实现契约,完整的看图入口在《agentic 运行时架构图说》,本节只交代建设要落到代码上的那几条硬事实。
 
-**先是 service 化:tier2 不自造 API,直接用官方 Agent Service。** AgentScope 2.0.3 自带一个 FastAPI 工厂 `create_app`,给的就是 REST + SSE + durable session + MessageBus 这一整套——建会话 `POST /sessions`、流式回放、跨进程消息总线都现成。game-cloud 经它调 tier2,断线还能 replay。所以这层别自己写,接官方的。**与之配套的一条关键事实:Agent 实例非常驻。** 它不是一个长跑的进程,而是每次 run 现组装、跑完即弃,所有状态都落在可持久化的 `AgentState`(pydantic 模型,含 `context` 工作记忆、`cur_iter` 当前轮次、`tasks_context` 任务清单)里。这直接决定了 checkpoint 怎么做——不是去序列化一个活对象,而是存取这份 `AgentState`(配 StorageBase,落 Redis)。
+**先是 service 化:tier2 不自造 API,直接用官方 Agent Service。** AgentScope 2.0.2 自带一个 FastAPI 工厂 `create_app`,给的就是 REST + SSE + durable session + MessageBus 这一整套——建会话 `POST /sessions`、流式回放、跨进程消息总线都现成。game-cloud 经它调 tier2,断线还能 replay。所以这层别自己写,接官方的。**与之配套的一条关键事实:Agent 实例非常驻。** 它不是一个长跑的进程,而是每次 run 现组装、跑完即弃,所有状态都落在可持久化的 `AgentState`(pydantic 模型,含 `context` 工作记忆、`cur_iter` 当前轮次、`tasks_context` 任务清单)里。这直接决定了 checkpoint 怎么做——不是去序列化一个活对象,而是存取这份 `AgentState`(配 StorageBase,落 Redis)。
 
 **session 初始化有三条加载路径,建设时三条都要支持。** 一是续接之前的会话:从 `SessionRecord.state` 取回历史,resume 着往下跑;二是加载一份已有的游戏工程:把 `Workspace.workdir` 指向那个已存在的目录,进入迭代模式(对应"游戏=长生命周期项目,改源不改包");三是新建:由阶段 2 的模板初始化工具从模板铺一套工程骨架起手。三条路径汇到同一个 Agent 装配点,只是初始 state / workdir 不同。
 
 **再是两阶段,以及"单写者"到底指哪一阶段——这点容易误读。** tier2 的生成分两阶段。**阶段 1 是工作室设计,用 Agent Team 星形多 agent**:一个 leader 分析并拆解用户意图,经 `AgentCreate` 拉起玩法 / 关卡 / 数值 / UI / 音乐 / 特效 / 资产等设计 worker 去发散,再经 `TeamSay` 把各路结论汇回 leader 收敛成设计结论。这一阶段是**只读 + 对话**——设计 worker 用 `PermissionMode.EXPLORE` 只读已有工程代码和工程内设计文档(迭代已有游戏时),并与用户**跨 session 多轮对话**,不写代码。**阶段 2 才是单写实现**:模板初始化工具铺骨架 → 把阶段 1 每个设计 agent 的结论写成工程内文档 → 单写 agent(单个 Agent 跑 ReAct 多轮)写代码 → 三层校验 → 产出。设计用多 agent 是要发散和专业分工,实现收敛到单写是要防并行写冲突。**所以"建设/spike 里说的单写者"专指阶段 2 的写代码环节,不是说整轨只有一个 agent。**
 
-这里要特别记一条 2.0.3 的多 agent 边界,免得照旧版资料踩坑:**2.0.3 删掉了进程内的 MsgHub / pipeline 编排,进程内多 agent 协作那套没有了**;留下的只有部署态的 Agent Team——`TeamCreate` / `AgentCreate` / `TeamSay` 这套工具,且是 leader-worker 星形拓扑:worker 只拿到 `TeamSay`(只能把结果报回 leader),**禁止 worker 之间互评 / 互相喊话**,所有协调都过 leader 这个中心。阶段 1 的工作室就建在这套 Agent Team 上,而不是去找已经不存在的 MsgHub。
+这里要特别记一条 2.0.2 的多 agent 边界,免得照旧版资料踩坑:**2.0.2 删掉了进程内的 MsgHub / pipeline 编排,进程内多 agent 协作那套没有了**;留下的只有部署态的 Agent Team——`TeamCreate` / `AgentCreate` / `TeamSay` 这套工具,且是 leader-worker 星形拓扑:worker 只拿到 `TeamSay`(只能把结果报回 leader),**禁止 worker 之间互评 / 互相喊话**,所有协调都过 leader 这个中心。阶段 1 的工作室就建在这套 Agent Team 上,而不是去找已经不存在的 MsgHub。
 
 ## 三层校验(L1/L2/L3)
 
@@ -76,11 +76,11 @@ flowchart TD
     S4 -.补齐.-> H4
 ```
 
-**第一步,搭起 AgentScope、完成集成。** 这是 agent 和循环的运行时底座,锁定 AgentScope 2.0.3 的真实 API:一个统一的 `Agent` 类(无状态 ReAct 引擎),构造时持有 model / toolkit / middlewares / state,自治多轮由它内建的 reasoning-acting 循环驱动,轮数上限走 `ReActConfig.max_iters`(2.0.3 默认 20)。tier2 是真自治富游戏轨,要的正是这种"在 Agent 内部跑多轮、自己 reason→act→读结果→再 reason"的形态。
+**第一步,搭起 AgentScope、完成集成。** 这是 agent 和循环的运行时底座,锁定 AgentScope 2.0.2 的真实 API:一个统一的 `Agent` 类(无状态 ReAct 引擎),构造时持有 model / toolkit / middlewares / state,自治多轮由它内建的 reasoning-acting 循环驱动,轮数上限走 `ReActConfig.max_iters`(2.0.2 默认 20)。tier2 是真自治富游戏轨,要的正是这种"在 Agent 内部跑多轮、自己 reason→act→读结果→再 reason"的形态。
 
 这点上 tier2 要和仓内 WG1 那条便宜线划清:WG1 的 `agent_loop/studio.py` 当前是 `ReActConfig(max_iters=1)` 的单轮调用 + 外层 `for attempt in range(max_repairs)` 的 repair 重试循环——单写、单轮、靠外层喂错重跑,那是 L1/L2 廉价档为压单价采的形态(L1 生产主线明确不引 AgentScope,框架 token 膨胀会吃掉便宜档单价)。tier2 复用的是 studio 那套多角色 prompt 与生成域(design/code/fix)的躯干,但把"多轮自治"从外层 repair 循环搬进 Agent 内部的 ReAct 循环(`max_iters` 放开),是 fork 起步、不是照搬。
 
-**tier2 独立锁 2.0.3,从 fork 起步、独立演进**:它在 AgentScope 2.0.3 上立轨,与 WG1 廉价线各自演进,不强求两条线跟同一份 AgentScope 版本走。这层地基值得建,而且它和下一步的配置外置回头还能服务现有 Tier0/1 线。
+**tier2 独立锁 2.0.2,从 fork 起步、独立演进**:它在 AgentScope 2.0.2 上立轨,与 WG1 廉价线各自演进,不强求两条线跟同一份 AgentScope 版本走。这层地基值得建,而且它和下一步的配置外置回头还能服务现有 Tier0/1 线。
 
 **第二步,把配置外置做实。** 让 prompt、编排、模型这些模型的全部输入都可配置、不发版可改(声明式为主、带脚本逃生口),并把一切挂上可回溯的轨迹。这一步的实现归线A的阶段2-3,本档引用、不重排。
 
@@ -135,7 +135,7 @@ flowchart LR
 |---|---|---|
 | 主力便宜档 | deepseek-v4-flash | 现行 Tier0/1 打底模型,tier2 自治的主力候选 |
 | 强便宜档 | deepseek-v4-pro | 现行救场档,测"贵一档便宜模型"是否显著抬过门率 |
-| 中等 agentic 档 | MiniMax-M3 | 这批最能打,**先用它证路**(见下"跑序")。接法走官方 `AnthropicChatModel` + `AnthropicChatFormatter`(构造模型时不传 formatter 即自动配对一个 `AnthropicChatFormatter`,无需手接),`AnthropicCredential.base_url` 指向 new-api 的 Anthropic 端点(即 `/v1/messages`),从而吃到原生的 Anthropic 协议 + agentic 工具循环;开 `thinking_enable` / `thinking_budget` 拿 thinking 分离,**注意 Anthropic 强约束 `max_tokens` 须严格大于 `thinking_budget`**(`thinking_budget` 缺省取 `max_tokens // 2`;若设得 ≥ `max_tokens`,2.0.3 的 `AnthropicChatModel` 会把 `max_tokens` 自动抬到 `budget + 1024`——别依赖这个兜底,显式设对) |
+| 中等 agentic 档 | MiniMax-M3 | 这批最能打,**先用它证路**(见下"跑序")。接法走官方 `AnthropicChatModel` + `AnthropicChatFormatter`(构造模型时不传 formatter 即自动配对一个 `AnthropicChatFormatter`,无需手接),`AnthropicCredential.base_url` 指向 new-api 的 Anthropic 端点(即 `/v1/messages`),从而吃到原生的 Anthropic 协议 + agentic 工具循环;开 `thinking_enable` / `thinking_budget` 拿 thinking 分离,**注意 Anthropic 强约束 `max_tokens` 须严格大于 `thinking_budget`**(`thinking_budget` 缺省取 `max_tokens // 2`;若设得 ≥ `max_tokens`,2.0.2 的 `AnthropicChatModel` 会把 `max_tokens` 自动抬到 `budget + 1024`——别依赖这个兜底,显式设对) |
 | 强模型基线 | Opus / Fable | 只跑 1~2 款作"路通不通"的上限基线,不进成本评估 |
 
 模型这一层统一从 new-api 出口走(`baseUrl` + `NEWAPI_KEY`,凭据见 `docs/内网凭据与端点.md`),协议 / SDK 不锁死——M3 这档走 Anthropic 原生端点是因为"用对它"要的就是原生 thinking + 工具循环,便宜档照旧走各自端点即可;all roads 收口到 new-api 一个计费平面。

docs/architecture/架构/生成引擎/tier2细节图说-A-运行时形态.md

@@ -19,9 +19,9 @@ status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontm
 
 A 族讲的是 tier2 富游戏自治生成线的运行时骨架——从 cloud 怎么经官方 Agent Service 接进来,到 agent 实例非常驻、状态全外置到 AgentState,再到 Workspace 沿两轴注入 agent,最后到成本与观测怎么统一挂在 middleware 洋葱上。这四件事是同一条运行轨的四个切面:图 A1 画接入面(cloud 怎么进、session 三条路怎么汇),图 A2 画 agent 的生命周期与断点续跑(非常驻怎么靠 AgentState + checkpoint 落实),图 A3 纠一个最容易踩的误解(Workspace 不是包着 agent、而是注入 agent),图 A4 画横切关注点的统一挂载点(成本刹车 / 硬熔断 / 观测挂在哪)。
 
-这四张图映射四份属主设计档加 AgentScope 2.0.3 源码。运行时形态的总口径出自《tier2 实现详设》的「运行时形态:两阶段、service 化与 session 三路径」一节,接入面的逐 router 与 MessageBus 细节出自《agentic 集成架构》的「tier2 接入面」与「D12 运行治理门」两节,所有结构性事实——八个 router、AgentState 三字段、WorkspaceBase 三实现、MiddlewareBase 五钩子——都按 AgentScope 2.0.3 源码逐条核过(`agentscope/app/`、`state/_state.py`、`workspace/`、`middleware/`)。frontmatter 记了这四份的当前 commit hash,作为防漂移门——其中任一份动了运行时口径,本图说与对应 SVG 必须同步改。
+这四张图映射四份属主设计档加 AgentScope 2.0.2 源码。运行时形态的总口径出自《tier2 实现详设》的「运行时形态:两阶段、service 化与 session 三路径」一节,接入面的逐 router 与 MessageBus 细节出自《agentic 集成架构》的「tier2 接入面」与「D12 运行治理门」两节,所有结构性事实——八个 router、AgentState 三字段、WorkspaceBase 三实现、MiddlewareBase 五钩子——都按 AgentScope 2.0.2 源码逐条核过(`agentscope/app/`、`state/_state.py`、`workspace/`、`middleware/`)。frontmatter 记了这四份的当前 commit hash,作为防漂移门——其中任一份动了运行时口径,本图说与对应 SVG 必须同步改。
 
-整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,代码一行没落。所以读 A 族时,「待建」是默认状态,绝不能因为图画得齐整就误以为运行时已经搭起来了。但「待建」不等于「全凭空想」——A 族里有一大块是 AgentScope 2.0.3 已经提供的现成件:官方 Agent Service(`create_app` 拉起的 FastAPI)、MessageBus(Redis 实现)、AgentState 模型与 StorageBase、WorkspaceBase 三实现、官方两个 middleware(预算软刹与 tracing),这些都现成、不用自造,图里用实线画。tier2 自己要做的是把这些现成件接成一条富游戏自治线:接官方 service、做非常驻装配与每轮 checkpoint、在官方 Workspace 抽象上挂 tier2 要的工具与资源、把硬熔断三件做成 MiddlewareBase 子类——这部分用虚线画。看图时记住这条对照:**实线 = 现行已落 / AgentScope 2.0.3 官方现成件,可以直接信;虚线(stroke-dasharray 6 4)= tier2 专属、待 0号 spike 验证后才落代码的接线。** 个别图上还有远期紫,标的是「设计已出但排在更长期层级」的元素(如 E2B 远端强隔离),不是 spike 期的投入项。
+整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,代码一行没落。所以读 A 族时,「待建」是默认状态,绝不能因为图画得齐整就误以为运行时已经搭起来了。但「待建」不等于「全凭空想」——A 族里有一大块是 AgentScope 2.0.2 已经提供的现成件:官方 Agent Service(`create_app` 拉起的 FastAPI)、MessageBus(Redis 实现)、AgentState 模型与 StorageBase、WorkspaceBase 三实现、官方两个 middleware(预算软刹与 tracing),这些都现成、不用自造,图里用实线画。tier2 自己要做的是把这些现成件接成一条富游戏自治线:接官方 service、做非常驻装配与每轮 checkpoint、在官方 Workspace 抽象上挂 tier2 要的工具与资源、把硬熔断三件做成 MiddlewareBase 子类——这部分用虚线画。看图时记住这条对照:**实线 = 现行已落 / AgentScope 2.0.2 官方现成件,可以直接信;虚线(stroke-dasharray 6 4)= tier2 专属、待 0号 spike 验证后才落代码的接线。** 个别图上还有远期紫,标的是「设计已出但排在更长期层级」的元素(如 E2B 远端强隔离),不是 spike 期的投入项。
 
 A 族是《agentic 运行时架构图说》的放大层,不是它的替代。那份总览图说里的图 1(系统全景)、图 2(调用时序)、图 3(运行时内部)、图 5(编排配置)、图 8(关键类图)给的是整体结构,A 族只把「运行时形态」这一面逐字段放大——总览图 3 把 Agent 与 Workspace 的整体结构画在一处,A 族则把非常驻装配、AgentState 三字段、双轴注入的两条轴、middleware 五钩子各自挂什么,一项一项展开。凡总览图已画清的整体结构,A 族不重画,只在脚注里指回去。这是 deepen 而非 duplicate:总览看轮廓,A 族看施工。
 
@@ -29,11 +29,11 @@ A 族是《agentic 运行时架构图说》的放大层,不是它的替代。那
 
 A 族四张图共用一套视觉语言,先在这里讲清,后面每张图不再重复。
 
-**线型承担状态语义。** 实线框 / 实线箭头 = 现行已落或 AgentScope 2.0.3 官方现成件(官方 Agent Service、MessageBus、AgentState、StorageBase、WorkspaceBase 三实现、官方 ReplyBudgetControlMiddleware 与 TracingMiddleware、D12 运行治理门),这些可以直接复用、不用自造。虚线框 / 虚线箭头(`stroke-dasharray 6 4`)= tier2 专属待建机制(非常驻装配、每轮 checkpoint 落 Redis、session 三路接线、注入工具集、D5 沙箱底座选型、硬熔断三件子类),还要写还要验。远期紫(紫框 / 紫底)= 设计已出但排在更长期层级的元素,典型是 E2B 远端强隔离对齐的多租户 / premium 层,不是 spike 期投入项。
+**线型承担状态语义。** 实线框 / 实线箭头 = 现行已落或 AgentScope 2.0.2 官方现成件(官方 Agent Service、MessageBus、AgentState、StorageBase、WorkspaceBase 三实现、官方 ReplyBudgetControlMiddleware 与 TracingMiddleware、D12 运行治理门),这些可以直接复用、不用自造。虚线框 / 虚线箭头(`stroke-dasharray 6 4`)= tier2 专属待建机制(非常驻装配、每轮 checkpoint 落 Redis、session 三路接线、注入工具集、D5 沙箱底座选型、硬熔断三件子类),还要写还要验。远期紫(紫框 / 紫底)= 设计已出但排在更长期层级的元素,典型是 E2B 远端强隔离对齐的多租户 / premium 层,不是 spike 期投入项。
 
 **徽章标的是这块内容服务哪个生产维度。** 绿色的 **可靠**(断点续跑不丢、半轮副作用幂等)、**成本**(压住自治多轮的烧钱)、蓝色的 **可观测**(每步推理 / 工具调用可对账)、灰色的 **数据**(状态可持久化落库)、红色的 **安全**(沙箱隔离 = 写码真跑的信任边界)、紫色的 **伸缩**(远端沙箱撑多租户)。这些维度落到 A 族的具体接点上:可靠落在 SSE 可恢复与 resume 续跑,成本落在 middleware 洋葱的预算软刹与硬熔断,可观测落在 Workspace 统一面与官方 Event→OTel 管道,数据落在 AgentState→StorageBase 落库,安全落在 Workspace 三实现的隔离强度梯度。
 
-**状态码四个,贯穿生成引擎子树。** **现** = 现行已建在跑或 AgentScope 2.0.3 官方现成;**接** = 设计已出、代码待接线;**建** = tier2 立项后要新建、当前待 spike;**缓** = 收窄后缓做 / 更长期层级。A 族绝大多数 tier2 自有元素是「建」,官方现成件是「现」,E2B 远端强隔离这类更长期项是「缓」。
+**状态码四个,贯穿生成引擎子树。** **现** = 现行已建在跑或 AgentScope 2.0.2 官方现成;**接** = 设计已出、代码待接线;**建** = tier2 立项后要新建、当前待 spike;**缓** = 收窄后缓做 / 更长期层级。A 族绝大多数 tier2 自有元素是「建」,官方现成件是「现」,E2B 远端强隔离这类更长期项是「缓」。
 
 ## 2 图集
 
@@ -41,7 +41,7 @@ A 族四张图共用一套视觉语言,先在这里讲清,后面每张图不再
 
 ![图 A1 Agent Service 与 session 三路径](assets/t2-A-01-AgentService与session三路.svg)
 
-cloud 这边要调 tier2 生成一款富游戏,第一个要回答的问题是「接口在哪、长什么样」。这张图给的答案是:tier2 不自造这层 API,直接用 AgentScope 2.0.3 的官方 Agent Service。它是 `create_app` 拉起的一个 FastAPI 应用,对外是 REST 加 SSE,天生多租户、天生 durable session,源码在 `agentscope/app/` 里逐条核过。图中央那条横向三段链路就是 cloud 接 tier2 的真实姿势——game-cloud 经 REST `POST /sessions` 建一个会话,再经 SSE 收事件流;tier2 的单写 ReAct agent 跑在这层 service 之上。这么接的理由很直接:一个现成、已经把多租户和可恢复会话都做好的 service 摆在那里,自己重写一遍既慢又容易漏,不如直接用官方的,把力气省下来花在富游戏怎么造上。
+cloud 这边要调 tier2 生成一款富游戏,第一个要回答的问题是「接口在哪、长什么样」。这张图给的答案是:tier2 不自造这层 API,直接用 AgentScope 2.0.2 的官方 Agent Service。它是 `create_app` 拉起的一个 FastAPI 应用,对外是 REST 加 SSE,天生多租户、天生 durable session,源码在 `agentscope/app/` 里逐条核过。图中央那条横向三段链路就是 cloud 接 tier2 的真实姿势——game-cloud 经 REST `POST /sessions` 建一个会话,再经 SSE 收事件流;tier2 的单写 ReAct agent 跑在这层 service 之上。这么接的理由很直接:一个现成、已经把多租户和可恢复会话都做好的 service 摆在那里,自己重写一遍既慢又容易漏,不如直接用官方的,把力气省下来花在富游戏怎么造上。
 
 图中段那排八个 router 和底下那行 MessageBus,是把「这层现成到什么程度」摆出来给人看清。八个 router——`/sessions`、`/chat`、`/schedule`、`/credential`、`/workspace`、`/model`、`/tts_model`、外加 agent 管理面——覆盖了一条生成线要用到的会话、对话、定时触发、模型密钥托管、执行环境、模型选择这一整套,全是框架现成件。底座是 MessageBus 的 Redis 实现,它撑起四样分布式协作能力:Redis Stream 做事件 replay 日志(晚到的订阅者能回放、不丢中间过程),pub/sub 做唤醒广播(worker 干完异步通知 leader、不必轮询),分布式锁保证同一会话同一时刻只被一个进程跑,取消信令支持中途叫停。这套底座直接决定了那条绿色的「SSE 可恢复」要点带能成立——cloud 收事件流时掉了线,重连后从 replay 日志续读、不必从头重跑,这正好兜住了「外部服务 / 异步任务要考虑超时、失败、断线」这条可靠性要求。一次富游戏生成可能跑很久,断线重连不丢进度是必须的,而这件事官方已经给了。
 
@@ -51,11 +51,11 @@ cloud 这边要调 tier2 生成一款富游戏,第一个要回答的问题是「
 
 ![图 A2 Agent 非常驻 + AgentState + checkpoint](assets/t2-A-02-Agent非常驻与AgentState.svg)
 
-这张图回答「tier2 的 agent 实例到底怎么活、断了怎么续」。结论先放在最前面:agent 是一个无状态的 ReAct 引擎,实例非常驻——它不是一个长跑的进程,而是每次 run 现组装、跑完即弃,不留活对象。图左侧那条「现组装 → 跑 ReAct 多轮 → 跑完即弃」的生命周期三态画的就是这件事:构造时持有 model / toolkit / middlewares / state,跑若干轮 ReAct(`cur_iter` 自增),跑完对象就销毁了。这不是一个随意的实现选择,而是 AgentScope 2.0.3 service 化的天然形态——service 要多租户、要能横向起多个进程处理不同会话,就不能让 agent 在某个进程的内存里长期活着。
+这张图回答「tier2 的 agent 实例到底怎么活、断了怎么续」。结论先放在最前面:agent 是一个无状态的 ReAct 引擎,实例非常驻——它不是一个长跑的进程,而是每次 run 现组装、跑完即弃,不留活对象。图左侧那条「现组装 → 跑 ReAct 多轮 → 跑完即弃」的生命周期三态画的就是这件事:构造时持有 model / toolkit / middlewares / state,跑若干轮 ReAct(`cur_iter` 自增),跑完对象就销毁了。这不是一个随意的实现选择,而是 AgentScope 2.0.2 service 化的天然形态——service 要多租户、要能横向起多个进程处理不同会话,就不能让 agent 在某个进程的内存里长期活着。
 
-图左下角那条「关键推论」是整张图的逻辑枢纽:既然没有常驻进程可以序列化,所有「下一轮还要用」的东西就都得外置到一份可持久化的状态里。这就引出图中段那个实线框的 AgentState——它是 AgentScope 2.0.3 自带的 pydantic 模型(源码 `agentscope/state/_state.py`),三个核心字段把一次生成的全部活记忆装了进去:`context` 是工作记忆,即喂进 LLM 的未压缩对话上下文;`cur_iter` 是当前轮次,记 ReAct 循环走到了第几轮;`tasks_context` 是任务清单,即拆解后的子任务表。图里那条蓝色说明带点出了 goal 和进度是怎么追踪的——目标来自输入(brief / play_spec / GDD),进度靠 `tasks_context` 逐项 TaskCreate / TaskUpdate 追踪,像一张会随生成推进不断勾选的 todo list。AgentState 是官方现成的(实线),tier2 直接用它装状态,不自己另造一套状态模型。
+图左下角那条「关键推论」是整张图的逻辑枢纽:既然没有常驻进程可以序列化,所有「下一轮还要用」的东西就都得外置到一份可持久化的状态里。这就引出图中段那个实线框的 AgentState——它是 AgentScope 2.0.2 自带的 pydantic 模型(源码 `agentscope/state/_state.py`),三个核心字段把一次生成的全部活记忆装了进去:`context` 是工作记忆,即喂进 LLM 的未压缩对话上下文;`cur_iter` 是当前轮次,记 ReAct 循环走到了第几轮;`tasks_context` 是任务清单,即拆解后的子任务表。图里那条蓝色说明带点出了 goal 和进度是怎么追踪的——目标来自输入(brief / play_spec / GDD),进度靠 `tasks_context` 逐项 TaskCreate / TaskUpdate 追踪,像一张会随生成推进不断勾选的 todo list。AgentState 是官方现成的(实线),tier2 直接用它装状态,不自己另造一套状态模型。
 
-图右侧那个虚线框的 checkpoint,是这张图最该破除的一个直觉误解:checkpoint 不是去序列化一个活对象。直觉上「保存进度」像是把正在跑的 agent 冻起来存盘,但 agent 非常驻、根本没有活进程可存——checkpoint 在 tier2 里的真实含义是存 / 取那份 AgentState。它配 AgentScope 2.0.3 现成的 StorageBase 抽象、用 RedisStorage 落 Redis(StorageBase 实线现成,每轮 checkpoint 这件 tier2 接线虚线待建)。两条硬约束写在右下角:一是每轮 checkpoint,`cur_iter` 每自增一轮就落一次 state,粒度细到能从任意一轮断点续上;二是半轮副作用须幂等无脏,因为续跑可能在一轮的中间断掉重来,如果半轮里那些副作用不幂等,重跑就会脏数据,所以这是一条要在长程一致性里专门采集字段去验的可靠性约束。
+图右侧那个虚线框的 checkpoint,是这张图最该破除的一个直觉误解:checkpoint 不是去序列化一个活对象。直觉上「保存进度」像是把正在跑的 agent 冻起来存盘,但 agent 非常驻、根本没有活进程可存——checkpoint 在 tier2 里的真实含义是存 / 取那份 AgentState。它配 AgentScope 2.0.2 现成的 StorageBase 抽象、用 RedisStorage 落 Redis(StorageBase 实线现成,每轮 checkpoint 这件 tier2 接线虚线待建)。两条硬约束写在右下角:一是每轮 checkpoint,`cur_iter` 每自增一轮就落一次 state,粒度细到能从任意一轮断点续上;二是半轮副作用须幂等无脏,因为续跑可能在一轮的中间断掉重来,如果半轮里那些副作用不幂等,重跑就会脏数据,所以这是一条要在长程一致性里专门采集字段去验的可靠性约束。
 
 图底那条蓝带把「非常驻 + AgentState」这条机理直接接到了实用价值上:它决定了 tier2 怎么做断点续跑。resume 不是什么特殊机制,就是图 A1 里 session 路径①的具体落实——从 StorageBase 读回上次的 AgentState,把它作为初始 state 注入新组装的非常驻引擎,引擎据此重建工作记忆与 `cur_iter`,然后从那一轮续接 ReAct 循环往下跑,已经完成的 TODO 不重做。一句话:非常驻不是缺陷,而是把「断点续跑」从难题变成了「读回 state 再装配」这件平常事。本图是总览图 3(运行时内部)和图 8(类图)的逐字段放大——总览把 Agent 与 Workspace 的整体结构画在一处,本图只取非常驻、AgentState 三字段、checkpoint 存 state 非存活对象这一面展开,Agent 与 Workspace 的双轴关系见图 A3,本图不重画。
 
@@ -75,7 +75,7 @@ cloud 这边要调 tier2 生成一款富游戏,第一个要回答的问题是「
 
 ![图 A4 Middleware 洋葱(横切关注点挂载点)](assets/t2-A-04-Middleware洋葱.svg)
 
-让 agent 自治生成游戏,光有 agent 和执行环境还不够——还得能在它跑的过程中刹住烧钱、超时硬切、把每一步都记下来,而且这些横切的事不能散落进业务逻辑里各写各的。这张图回答的就是这些横切关注点统一挂在哪。答案是 AgentScope 2.0.3 的 MiddlewareBase 洋葱:它在 agent 执行的若干钩子上层层拦截,每一层用 `next_handler()` 把下一层包在中间,外层裹内层,所以叫洋葱。tier2 把成本刹车、硬熔断、可观测全挂在这套洋葱上,不另起机制、不散落进业务代码——这是框架给的扩展点,直接用。
+让 agent 自治生成游戏,光有 agent 和执行环境还不够——还得能在它跑的过程中刹住烧钱、超时硬切、把每一步都记下来,而且这些横切的事不能散落进业务逻辑里各写各的。这张图回答的就是这些横切关注点统一挂在哪。答案是 AgentScope 2.0.2 的 MiddlewareBase 洋葱:它在 agent 执行的若干钩子上层层拦截,每一层用 `next_handler()` 把下一层包在中间,外层裹内层,所以叫洋葱。tier2 把成本刹车、硬熔断、可观测全挂在这套洋葱上,不另起机制、不散落进业务代码——这是框架给的扩展点,直接用。
 
 图左侧那组同心环画的是四个 onion 钩子,从外到内各裹住 agent 执行的一层。最外环 `on_reply` 是一整次回复的进出边界;往里 `on_reasoning` 裹推理 / 模型调用阶段;再往里 `on_acting` 只裹单次工具执行那层 I/O(`toolkit.call_tool`);最内环 `on_model_call` 拦截裸模型 API 调用——这一环是钱算在哪的地方,因为它能读到 `ModelCallEndEvent` 带的 token 用量(`input_tokens` / `output_tokens`),成本台账和 trace 的 token 都从这一环取。洋葱框外下方那个单独的框是第五个钩子 `on_system_prompt`,它和前四个不同,不是前后包裹,而是顺序变换——多个 middleware 串成一条管线,各拿上一个的输出去改 system prompt 串,所以它是 transformer 而非 onion。四个 onion 加一个 transformer 共五个挂载点,按源码 `_base.py` 逐条核过,未实现的钩子运行时自动跳过。看懂这五个钩子各裹哪一层,才能回答「某个横切关注点该挂哪个钩子」。
 

docs/architecture/架构/生成引擎/tier2细节图说-B-控制面与管理面.md

@@ -67,7 +67,7 @@ B 族用一套统一的徽章、线型和状态码,先在这里讲清,后面每
 
 ![图 B3 预算三层强制](assets/t2-B-03-预算三层强制.svg)
 
-引擎设计里那道「花到上限就拒绝执行」的预算闸,现在不是现成能力,这张图把它单独深挖。要先看清官方给了什么、缺什么,图上半部分就是这个对照。AgentScope 2.0.3 自带 `ReplyBudgetControlMiddleware`,但它只做软刹——累计加权 token 到阈值后,往 Agent 上下文注入一句提示(别再调工具、收尾)、并把下一步的 `tool_choice` 强制成 `none` 让它结束,它只数 token、不换算金额、更不会硬拒。这对失控成本不够:tier2 自治多轮 ReAct 一次失控循环能烧掉数美元,软刹只是「提醒它别再调工具」,刹不住一个已经在烧钱的循环——提示不等于截断。
+引擎设计里那道「花到上限就拒绝执行」的预算闸,现在不是现成能力,这张图把它单独深挖。要先看清官方给了什么、缺什么,图上半部分就是这个对照。AgentScope 2.0.2 自带 `ReplyBudgetControlMiddleware`,但它只做软刹——累计加权 token 到阈值后,往 Agent 上下文注入一句提示(别再调工具、收尾)、并把下一步的 `tool_choice` 强制成 `none` 让它结束,它只数 token、不换算金额、更不会硬拒。这对失控成本不够:tier2 自治多轮 ReAct 一次失控循环能烧掉数美元,软刹只是「提醒它别再调工具」,刹不住一个已经在烧钱的循环——提示不等于截断。
 
 所以硬熔断和金额台账都得自建,而且自建有现成载体——同样是 AgentScope 的中间件洋葱。图右半部分画的是这个自建件:在 `on_model_call` 这类钩子上拦截,订阅 `ModelCallEndEvent`(源码已确认这事件带每次模型调用的 token 用量),把 token 乘上 new-api 的单价换算成金额累进台账,一旦越过硬上限就直接抛错 fail-closed、终止本次生成,而不是像官方那样只注入提示。金额台账加硬拒这两件,正是官方软刹做不到、故必须自建的。软刹和硬熔断这两种处置力度叠在同一个中间件洋葱里——一个数 token 提醒,一个折金额硬拒。
 

docs/architecture/架构/生成引擎/tier2细节图说-C-单写ReAct循环.md

@@ -35,7 +35,7 @@ C 族把生成引擎子树里三份设计档画成图：写者形态与四道熔
 
 这张图回答「谁在写富游戏、以什么节奏写」。写者是一个单写者 ReAct agent。ReAct 指 agent「想一步、调一个工具、看结果、再想下一步」的循环——图中央那个 reason→act→observe 的三角就是这个节奏，它的反面是「一次把整个游戏的答案写完」。富游戏工程跨十几个源文件、多个系统互相接线，一次写完几乎不可能对，所以必须让 agent 每观测一次就回头重想，在循环里把游戏逼出来。
 
-图左侧的两态并列是这张图最该让人看出的东西：tier2 和现行 WG1 廉价线的真正差别，不在 prompt、不在生成域，而在「多轮自治放在哪一层」。WG1 现行用的是 `ReActConfig(max_iters=1)` 的单轮调用，加一个外层 `for attempt in range(max_repairs)` 的重试循环——生成一次，外层把错误喂回去重跑一次，单写、单轮。它故意这么做，是为了压住便宜档的单价：L1 生产主线明确不引 AgentScope，因为框架本身的 token 膨胀会吃掉便宜档那点利润空间。tier2 则把 `max_iters` 放开（AgentScope 2.0.3 默认 20），把「多轮」从外层 repair 循环搬进 Agent 内部的 ReAct 循环——同一套多角色 prompt 和生成域躯干复用，但自治的位置变了。这就是为什么左下角那块 tier2 态画虚线、还标着「独立锁 AgentScope 2.0.3、独立演进」：它从 WG1 fork 起步，但锁自己的框架版本、独立往前走，不强求两条线跟同一份 AgentScope。
+图左侧的两态并列是这张图最该让人看出的东西：tier2 和现行 WG1 廉价线的真正差别，不在 prompt、不在生成域，而在「多轮自治放在哪一层」。WG1 现行用的是 `ReActConfig(max_iters=1)` 的单轮调用，加一个外层 `for attempt in range(max_repairs)` 的重试循环——生成一次，外层把错误喂回去重跑一次，单写、单轮。它故意这么做，是为了压住便宜档的单价：L1 生产主线明确不引 AgentScope，因为框架本身的 token 膨胀会吃掉便宜档那点利润空间。tier2 则把 `max_iters` 放开（AgentScope 2.0.2 默认 20），把「多轮」从外层 repair 循环搬进 Agent 内部的 ReAct 循环——同一套多角色 prompt 和生成域躯干复用，但自治的位置变了。这就是为什么左下角那块 tier2 态画虚线、还标着「独立锁 AgentScope 2.0.2、独立演进」：它从 WG1 fork 起步，但锁自己的框架版本、独立往前走，不强求两条线跟同一份 AgentScope。
 
 中下那个虚线笼子是另一处要点——agent 的自治不是放任。它被关在一圈验收门里迭代：读引擎文档和资产 → 写源文件 → esbuild 构建 → headless 无头快检 → 九门 L1 真浏览器真玩 → 读 verdict → 没过就改、改完回到写源。这里有一条画成实线的关键节点：九门 L1 那一格。一款游戏算不算过关，不靠模型自己说，靠在真浏览器里真玩一遍——这套确定性判定继承自现行九门，铁律是绝不让 LLM 给自己打分。LLM 一旦进验收当裁判，会学会把游戏优化成「让裁判说好」而不是「真的好」，门就废了。所以图里九门那一格是实线（承袭现行已落），而它前后的写源、改、快检都是虚线（tier2 内循环待建）——确定性的判定承袭旧机制，自治的写法是新的。
 
@@ -47,9 +47,9 @@ C 族把生成引擎子树里三份设计档画成图：写者形态与四道熔
 
 ![图 C2 M3 Anthropic 原生接法](assets/t2-C-02-M3原生接法.svg)
 
-这张图回答「中等 agentic 档的 MiniMax-M3 怎么接进 tier2 的 agent」。主链路从左到右一条线：tier2 agent → AnthropicChatModel → AnthropicCredential.base_url → MiniMax-M3。读这条链要抓两个事实。一是接法本身可信——它走 AgentScope 2.0.3 的官方模型类 AnthropicChatModel，构造时不传 formatter 就会自动配对一个 AnthropicChatFormatter，无需手接，这套已经逐条核过 2.0.3 源码。二是出口统一——AnthropicCredential 的 base_url 指向 new-api 的 Anthropic 端点（即 `/v1/messages`），模型计费统一从 new-api 这一个平面走。链路上的箭头里，agent 到模型那几跳画虚线（tier2 待建），但 new-api 计费出口画实线（现行已落）。
+这张图回答「中等 agentic 档的 MiniMax-M3 怎么接进 tier2 的 agent」。主链路从左到右一条线：tier2 agent → AnthropicChatModel → AnthropicCredential.base_url → MiniMax-M3。读这条链要抓两个事实。一是接法本身可信——它走 AgentScope 2.0.2 的官方模型类 AnthropicChatModel，构造时不传 formatter 就会自动配对一个 AnthropicChatFormatter，无需手接，这套已经逐条核过 2.0.2 源码。二是出口统一——AnthropicCredential 的 base_url 指向 new-api 的 Anthropic 端点（即 `/v1/messages`），模型计费统一从 new-api 这一个平面走。链路上的箭头里，agent 到模型那几跳画虚线（tier2 待建），但 new-api 计费出口画实线（现行已落）。
 
-中间三个要点框讲「用对 M3」要满足的三件事，它们合起来定义了 M3 的正确用法。其一，走 Anthropic 原生协议加 agentic 工具循环——不是 OpenAI 式的单次 JSON 填空，而是让 agent 在循环里调工具写源、build、跑门、读 verdict、改，多轮自治收敛。其二，thinking 分离：开 `thinking_enable` / `thinking_budget` 拿到推理与答案分离，这里有一条硬约束——max_tokens 必须严格大于 thinking_budget，budget 缺省取 max_tokens 的一半；如果把 budget 设得不小于 max_tokens，2.0.3 会自动把 max_tokens 抬到 budget+1024，但别依赖这个兜底，显式设对。其三，完整 response 和历史保留：每轮把 thinking / text / tool_use 所有块原样回传入历史，不剥、不丢、不只抠 JSON——这样 M3 的交错思维（Interleaved Thinking）才不失效，才发挥得出最佳 agentic 性能。
+中间三个要点框讲「用对 M3」要满足的三件事，它们合起来定义了 M3 的正确用法。其一，走 Anthropic 原生协议加 agentic 工具循环——不是 OpenAI 式的单次 JSON 填空，而是让 agent 在循环里调工具写源、build、跑门、读 verdict、改，多轮自治收敛。其二，thinking 分离：开 `thinking_enable` / `thinking_budget` 拿到推理与答案分离，这里有一条硬约束——max_tokens 必须严格大于 thinking_budget，budget 缺省取 max_tokens 的一半；如果把 budget 设得不小于 max_tokens，2.0.2 会自动把 max_tokens 抬到 budget+1024，但别依赖这个兜底，显式设对。其三，完整 response 和历史保留：每轮把 thinking / text / tool_use 所有块原样回传入历史，不剥、不丢、不只抠 JSON——这样 M3 的交错思维（Interleaved Thinking）才不失效，才发挥得出最佳 agentic 性能。
 
 图中间那条红框是这张图的命门，也是为什么它值得单独画一张：旧用法是 60% 失败的最深根因，而且是用法错、不是模型天花板。错用法等于三连违反——关掉 thinking、单次 JSON 填空、失败就从头重生成。把一个 agentic 加交错思维的模型当成一次性填空机来用，等于把它最强的那部分能力全关掉了。这处误读还连着另一处：max_tokens 是「输出上限」、不是 512K 的上下文窗——输出可以抬到小于 128K 给 thinking 加答案用，输入窗 512K 不受它限。
 
@@ -77,7 +77,7 @@ C 族把生成引擎子树里三份设计档画成图：写者形态与四道熔
 
 中间那三块是 amodel-gen 留给 tier2 的三件可复用范式，每件都配了一个紫色虚线小条，标明 tier2 在哪个工作单元复用它。done 门——agent 自己 reason 判「够了」才终止，不靠外层固定轮数，tier2 在 U2 复用为多轮 ReAct（finish 工具收尾吐出 src/ 源工程）。check/build 快反馈——每轮先跑便宜的检查再决定下一步，拿快反馈喂下一轮而不是等重门才纠错，tier2 在 U7 复用为「写源 → build → headless 快检 → L1 门」的闭环。历史压缩——多文件富游戏迭代轮数多、上下文长，压缩历史让长程多轮不撑爆窗口，tier2 在 U7 复用为长程一致性（12 个以上文件的工程过程中无 checkpoint 丢失）。
 
-图底那条蓝带是这张图最该读透的部分，它讲清一处极易被误导的边界——「fork 演进」不等于「整轨是平移」。tier2 复用 studio 那套多角色 prompt 和生成域躯干，把「多轮」从外层 repair 搬进 Agent 内部 ReAct，这层确实是 fork 加版本钉级别的轻活：种子 `studio.py` 用到的 AgentScope 框架接缝（6 个符号）在 2.0.3 全兼容，零签名改。但别被「6 符号兼容」误导——studio.py 拖着的 `validate.py` / `run.py` / `prompt.py` / `roles.py` 是 LittleJS 专属，按 Phaser 重写、工作量约等于全新写（net-new）。最典型的是 validate 的硬规则：它对 LittleJS 要求「禁 import、单 export default 工厂」，这套规则对 Phaser 多文件源工程完全反转。所以真正的功夫不在框架接缝，而在这些重写面加 net-new 的多轮 ReAct / Workspace / Service（Phase B）。
+图底那条蓝带是这张图最该读透的部分，它讲清一处极易被误导的边界——「fork 演进」不等于「整轨是平移」。tier2 复用 studio 那套多角色 prompt 和生成域躯干，把「多轮」从外层 repair 搬进 Agent 内部 ReAct，这层确实是 fork 加版本钉级别的轻活：种子 `studio.py` 用到的 AgentScope 框架接缝（6 个符号）在 2.0.2 全兼容，零签名改。但别被「6 符号兼容」误导——studio.py 拖着的 `validate.py` / `run.py` / `prompt.py` / `roles.py` 是 LittleJS 专属，按 Phaser 重写、工作量约等于全新写（net-new）。最典型的是 validate 的硬规则：它对 LittleJS 要求「禁 import、单 export default 工厂」，这套规则对 Phaser 多文件源工程完全反转。所以真正的功夫不在框架接缝，而在这些重写面加 net-new 的多轮 ReAct / Workspace / Service（Phase B）。
 
 这条边界还连着一处口径的精确化（创始人 2026-06-23 裁）：两线分立、不收敛。旧的边界叫「能力档（声明式 vs 自治）」，但 A-model 分支已经让廉价线也走向自治写真 JS，所以旧口径过时了。新口径是「引擎 / 表现层复杂度档」——A-model 吃 LittleJS 轻量经营档，tier2 吃 Phaser 重表现富游戏档。两条线各吃各的市场、各跑各的运行时，运行期零依赖。amodel-gen 合并 dev/2.0.0 之后，tier2 的循环范式以合并后版本为参照系重取，种子仍是 Python 的 `studio.py`，amodel-gen 只作 JS 参照、不照搬。
 
@@ -86,6 +86,6 @@ C 族把生成引擎子树里三份设计档画成图：写者形态与四道熔
 | # | 图名 | 形式 | 状态 | 覆盖内容 |
 |---|---|---|---|---|
 | C1 | 单写 ReAct 循环 | SVG | 建（演进自 WG1 studio.py） | reason→act→observe 三角；WG1 单轮+repair vs tier2 内多轮两态并列；验收门笼子（读文档→写源→build→快检→九门 L1→verdict→改）；九门实线承袭、自治内循环虚线待建；单写者只指阶段 2、阶段 1 仍多 agent；底部四道熔断红框引子 |
-| C2 | M3 Anthropic 原生接法 | SVG | 建（接法走官方 AnthropicChatModel，2.0.3 已核） | 主链路 agent→AnthropicChatModel→base_url 指 new-api→MiniMax-M3；用对 M3 三要点（原生协议+工具循环 / thinking 分离 / 完整 response 保留）；红框警示旧用法=60% 失败最深根因；new-api 统一计费平面、协议不锁死 |
+| C2 | M3 Anthropic 原生接法 | SVG | 建（接法走官方 AnthropicChatModel，2.0.2 已核） | 主链路 agent→AnthropicChatModel→base_url 指 new-api→MiniMax-M3；用对 M3 三要点（原生协议+工具循环 / thinking 分离 / 完整 response 保留）；红框警示旧用法=60% 失败最深根因；new-api 统一计费平面、协议不锁死 |
 | C3 | 四道熔断 + 预算闸 | SVG | 建（软刹官方现成、三道硬熔断+强制硬闸自建待落） | 四道熔断（步数硬顶 / 预算闸 / 卡死探测 / 双层超时）；预算闸=官方软刹实线 best-effort、非强制硬闸（设计缝）；卡死探测防 Goodhart；中间件洋葱叠加机制；spike 阶段先只挂官方软刹的退路 |
 | C4 | 多轮自治范式（承 amodel-gen） | SVG | 建（范式承 A-model 已落、tier2 fork 演进待建） | 三态演进带（studio.py 单轮 → amodel-gen 多轮 → tier2 Phaser 富游戏）；三件可复用范式（done 门 / check-build 快反馈 / 历史压缩）映射 U2/U7；fork 演进≠平移（6 符号兼容是版本钉、validate/run/prompt/roles 是 net-new 重写）；两线分立不收敛、边界精确为引擎/表现层复杂度档 |

docs/architecture/架构/生成引擎/tier2细节图说-E-能力面skills与prompt.md

@@ -80,7 +80,7 @@ E 族里只有图 E4 涉及第三种状态。它讲的是 tier2 怎么接住 Mac
 
 为什么设计用多 agent、实现用单写,这是两阶段角色最该讲清的道理。设计阶段要的是发散和专业分工,多个 worker 各管一个方面、把可能性铺开,leader 再收敛,这时候多 agent 是优势。实现阶段恰恰相反:经营游戏的多个系统共享同一套状态和约定,如果拆给并行 agent 同时写,几乎必然写出互相不一致的结果,所以实现必须收敛到单写、由一个 agent 持有整个工程的全局视图。图里那个红框拓扑铁律点出了星形的硬约束——worker 只拿到 TeamSay、只能把结果报回 leader,禁止 worker 之间互评或互相喊话,所有协调都过 leader 这个唯一的中心。
 
-红框里还钉了一条容易踩坑的事实:AgentScope 2.0.3 删掉了进程内的 MsgHub 和 pipeline 编排,进程内多 agent 协作那套已经没有了,留下的只有部署态的 Agent Team(TeamCreate / AgentCreate / TeamSay)。工作室必须建在这套 Agent Team 上,而不是去找一个已经不存在的 MsgHub。图里阶段 1 和阶段 2 的内部拓扑都是照 2.0.3 源码逐条核过画的(`/root/oss/agentscope`),就是为了免得照旧版资料把架构画错。
+红框里还钉了一条容易踩坑的事实:AgentScope 2.0.2 删掉了进程内的 MsgHub 和 pipeline 编排,进程内多 agent 协作那套已经没有了,留下的只有部署态的 Agent Team(TeamCreate / AgentCreate / TeamSay)。工作室必须建在这套 Agent Team 上,而不是去找一个已经不存在的 MsgHub。图里阶段 1 和阶段 2 的内部拓扑都是照 2.0.2 源码逐条核过画的(`/root/oss/agentscope`),就是为了免得照旧版资料把架构画错。
 
 底部那条蓝带补一句血缘:prompt 生成域承袭现行 studio.py 的多角色 prompt(design / code / fix),tier2 复用它的多角色 prompt 和生成域躯干,是 fork 起步、独立演进,不是照搬。整图的 tier2 专属机制(Agent Team 星形、单写 ReAct 多轮)都画虚线待建,承袭现行的(九门 harness、A-model)画实线。
 
@@ -106,5 +106,5 @@ E 族里只有图 E4 涉及第三种状态。它讲的是 tier2 怎么接住 Mac
 |---|---|---|---|---|
 | E1 | 单写 agent 的 toolkit(阶段 2 · skill 清单) | SVG | 建(演进自 wg1 studio.py) | 九个工具的目的/边界/产出 · 三类角色(核心环 / 取证 / 起手收尾) · 自治内循环形态 · 三条工具边界铁律(单写独占 / finish 共用 schema / 验收零自评) |
 | E2 | 引擎能力包 manifest(五件套) | SVG | 建(第一版 Phaser 硬编码 · 通用接口待第二引擎) | 引擎=动态加载的能力包而非固定底座 · skill/tool/mcp/rag/脚手架五件套各管一面 · 换引擎=换工具集非架构重写 · 克制警示(不为一个实现先建抽象) |
-| E3 | prompt 两阶段角色 | SVG | 建(阶段 1 Agent Team / 阶段 2 单写 · 2.0.3 API 已核) | 阶段 1 工作室 Agent Team 星形(多 agent 发散+专业分工·只读+对话) · 阶段 2 单写 ReAct(防并行写冲突) · leader-worker 拓扑铁律 · 2.0.3 删 MsgHub 只剩部署态 Agent Team |
+| E3 | prompt 两阶段角色 | SVG | 建(阶段 1 Agent Team / 阶段 2 单写 · 2.0.2 API 已核) | 阶段 1 工作室 Agent Team 星形(多 agent 发散+专业分工·只读+对话) · 阶段 2 单写 ReAct(防并行写冲突) · leader-worker 拓扑铁律 · 2.0.2 删 MsgHub 只剩部署态 Agent Team |
 | E4 | A-model 4 插件复用 | SVG | 接(复用 A-model 资产 · 合并后对账) | 两线边界(引擎/表现层复杂度档) · 四插件契约复用+渲染按 Phaser 重做 · sim-business 配方复用 · 九门基线 driver 感知分级范式复用 · 源项目契约维持独立 schema |

docs/architecture/架构/生成引擎/tier2细节图说-H-观测与成本.md

@@ -25,7 +25,7 @@ H 族讲的是 tier2 富游戏自治生成线怎么被看见、怎么被算账
 
 这三张图映射四份源档。统一 trace 契约的实现接点出自《tier2 实现详设》的「统一 trace 契约的实现接点」节,它讲 tier2 这一侧怎么把 ReAct 三段填进契约。契约的完整治理口径——为什么消灭 split-brain 是「诚实镜像各自字段」而不是「强求对齐」、接口对称内容不对称怎么成立、观测管道的官方件链路、D12 预算闸缺什么——出自《agentic 集成架构》的「观测/审计仓」与「D12 运行治理门」两节。采集指标的字段定义(`cost_rmb` / `tokens_by_model`)出自《tier2 实现详设》的「采集指标字段表」。成本取证那条要补 `RecordingChatModel(AnthropicChatModel)` 变体的接点出自 `tier2/HANDOFF.md` 的「U7 成本取证」。frontmatter 记了这四份的当前 commit hash,作为防漂移门——其中任一份动了观测或成本的口径,本图说与对应 SVG 必须同步改。
 
-整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,代码一行没落。所以 H 族里凡是 tier2 专属的机制——统一 trace 契约的 `contracts/trace/` 立位、tier2 这条线的 adapter、Anthropic 路的录制变体——都是设计已出、尚未落地的状态,用虚线画。但这三张图都不是纯虚的,各有一段实打实的现行底座撑着。可观测面的官方件(Event System、TracingMiddleware、OTel、Studio)是 AgentScope 2.0.3 的现成件,源码已逐条核过,tier2 直接订阅、不必自造,这部分用实线画,表的是「官方现成、直接可用」。成本面的 new-api quota 计费平面是早已部署在跑的权威成本源,`cost.py` 读 `logs.quota` 折人民币是仓内 `newapi-billing-plane-integration` 已落的能力,这部分也用实线,表的是「现行已落」。SAA 廉价线那条 Java 线的节点裁决埋点同样是现行已跑的。看图时记住这条对照:**实线 = 现行已落或官方现成件(SAA 节点裁决埋点 / AgentScope 官方观测管道 / new-api quota 计费平面);虚线(短划线)= tier2 专属、待 0号 spike 验证后才落代码的新机制。** 个别图上还有一抹远期紫,标的是 `contracts/trace/` 这一类还没建的 additive 契约立位——它不是已有件、也不只是 tier2 私有,而是随 spike 或控制面 phase-1 才新立的契约位,别当现成。
+整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,代码一行没落。所以 H 族里凡是 tier2 专属的机制——统一 trace 契约的 `contracts/trace/` 立位、tier2 这条线的 adapter、Anthropic 路的录制变体——都是设计已出、尚未落地的状态,用虚线画。但这三张图都不是纯虚的,各有一段实打实的现行底座撑着。可观测面的官方件(Event System、TracingMiddleware、OTel、Studio)是 AgentScope 2.0.2 的现成件,源码已逐条核过,tier2 直接订阅、不必自造,这部分用实线画,表的是「官方现成、直接可用」。成本面的 new-api quota 计费平面是早已部署在跑的权威成本源,`cost.py` 读 `logs.quota` 折人民币是仓内 `newapi-billing-plane-integration` 已落的能力,这部分也用实线,表的是「现行已落」。SAA 廉价线那条 Java 线的节点裁决埋点同样是现行已跑的。看图时记住这条对照:**实线 = 现行已落或官方现成件(SAA 节点裁决埋点 / AgentScope 官方观测管道 / new-api quota 计费平面);虚线(短划线)= tier2 专属、待 0号 spike 验证后才落代码的新机制。** 个别图上还有一抹远期紫,标的是 `contracts/trace/` 这一类还没建的 additive 契约立位——它不是已有件、也不只是 tier2 私有,而是随 spike 或控制面 phase-1 才新立的契约位,别当现成。
 
 本族是 [agentic运行时架构图说](agentic运行时架构图说.md) 的放大层,deepen 不 duplicate。运行时图说的图 7「产物与契约」只点了 trace 契约的两段结构(公共核心子集 + tier2 扩展段),它的术语映射节(图 6)只把「可观测 = Event System → TracingMiddleware → Studio」点了一行。H 族把这两点逐项展开:H1 把对称核心五字段加两轨扩展段逐项摊开、画出 adapter 双轨怎么汇进契约;H2 把官方观测管道的四节点链路加七类强类型事件逐个画清;H3 把运行时图说没细讲的成本折算链路独立成图。要看 tier2 整轨的全貌从运行时图说进,要看观测与成本这一面的细节看这里。
 
@@ -35,7 +35,7 @@ H 族用一套统一的徽章和线型,先在这里讲清,后面每张图不再
 
 **生产维度徽章**标的是这块东西服务于哪个非功能目标:蓝色 **可观测** = 让一次生成的全过程能被看见、被反查;绿色 **成本** = 让每款的花费能被算准、被对账;灰色 **数据** = 落进采集字段的那些列。H 族主要落在可观测和成本这两维上。
 
-**状态徽章**标的是单块组件的成熟度,跟整图状态条配合读:绿色 **现行 / 已落 / 廉价线已落 / 承现行** = 这块东西现在就在跑(new-api quota 平面、SAA 节点裁决埋点、`cost.py` 读 quota);蓝色 **官方 / 官方 typed / 标准** = AgentScope 2.0.3 或 OpenTelemetry 的现成件,直接订阅即用;紫色 **待建 / 待补 / 待立 / 契约位待建 / additive 待立** = tier2 专属、尚未落代码的新机制或新契约位。
+**状态徽章**标的是单块组件的成熟度,跟整图状态条配合读:绿色 **现行 / 已落 / 廉价线已落 / 承现行** = 这块东西现在就在跑(new-api quota 平面、SAA 节点裁决埋点、`cost.py` 读 quota);蓝色 **官方 / 官方 typed / 标准** = AgentScope 2.0.2 或 OpenTelemetry 的现成件,直接订阅即用;紫色 **待建 / 待补 / 待立 / 契约位待建 / additive 待立** = tier2 专属、尚未落代码的新机制或新契约位。
 
 **线型**承担状态语义。实线框 = 现行已落或官方现成件,虚线框(短划线 `stroke-dasharray 6 4`)= tier2 专属待建。实线箭头 = 现行已有的链路或官方件之间的转移,虚线箭头 = tier2 待建的订阅 / 映射流程。
 
@@ -61,7 +61,7 @@ H 族用一套统一的徽章和线型,先在这里讲清,后面每张图不再
 
 ![图 H2 tier2 观测管道](assets/t2-H-02-观测管道.svg)
 
-H1 给了 tier2 adapter 走官方管道这一句结论,这张图把那条管道逐节点展开,要破除的误解是「tier2 写轨迹得自己埋点」。事实正相反:AgentScope 2.0.3 本身带一套完整的 typed Event System,tier2 只订阅、不自造,再走官方的 TracingMiddleware → OTel 管道汇进 Studio,最后才加一层自建 adapter 映射进统一契约。
+H1 给了 tier2 adapter 走官方管道这一句结论,这张图把那条管道逐节点展开,要破除的误解是「tier2 写轨迹得自己埋点」。事实正相反:AgentScope 2.0.2 本身带一套完整的 typed Event System,tier2 只订阅、不自造,再走官方的 TracingMiddleware → OTel 管道汇进 Studio,最后才加一层自建 adapter 映射进统一契约。
 
 横向那条主链路是四个官方现成件接成的(图里全用实线、蓝色官方徽章,源码已核)。第一节 **Agent Event System**:ReAct agent 每跑一步就吐出一套强类型事件流,框架自带,不必自己埋点(源码 `agentscope/event/_event.py`)。第二节 **TracingMiddleware**:这个中间件直接调真 OTel SDK 的 `start_as_current_span`,把事件转成 span、挂上 attributes 和 status(源码 `middleware/_tracing/_trace.py`)。第三节 **OpenTelemetry span**:标准链路追踪 span,分 agent / llm / tool 三类 span_name,带 OK / ERROR 状态——这是真 OTel SDK 而非 mock,所以可以对接任何标准后端。第四节 **AgentScope Studio**:开箱即用的可视化,逐步呈现推理、工具调用、模型用量、一轮回复的边界,不必自造前端。一句话:tier2 写轨迹 = 订阅事件 + 官方 OTel 管道 + 一层 adapter。
 

docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md

@@ -12,7 +12,7 @@ status: 草案 · 已纳入 Codex+Opus 双评审并修订
 
 ## Problem Frame
 
-tier2 这条线的"要造什么"已经想透并经 2026-06-20 对抗审查拍板：用约束自治（O2）的单写 ReAct agent，在一圈确定性验收门里把现有廉价流水线做不出的多系统富游戏（合成、经营、挂机）逼出来；引擎选 Phaser/Pixi（过无头硬筛、按 AI 作者视角取生态厚度）；底座锁 AgentScope 2.0.3；验收按创始人定义的三层校验走。这些结论分别落在《[自治富游戏引擎](../architecture/架构/生成引擎/自治富游戏引擎.md)》《[tier2 四层工程架构](../architecture/架构/生成引擎/tier2四层工程架构.md)》《[tier2 实现详设](../architecture/架构/生成引擎/tier2实现详设.md)》《[agentic 集成架构](../architecture/架构/生成引擎/agentic集成架构.md)》和图说五份档里。
+tier2 这条线的"要造什么"已经想透并经 2026-06-20 对抗审查拍板：用约束自治（O2）的单写 ReAct agent，在一圈确定性验收门里把现有廉价流水线做不出的多系统富游戏（合成、经营、挂机）逼出来；引擎选 Phaser/Pixi（过无头硬筛、按 AI 作者视角取生态厚度）；底座锁 AgentScope 2.0.2；验收按创始人定义的三层校验走。这些结论分别落在《[自治富游戏引擎](../architecture/架构/生成引擎/自治富游戏引擎.md)》《[tier2 四层工程架构](../architecture/架构/生成引擎/tier2四层工程架构.md)》《[tier2 实现详设](../architecture/架构/生成引擎/tier2实现详设.md)》《[agentic 集成架构](../architecture/架构/生成引擎/agentic集成架构.md)》和图说五份档里。
 
 还没解决的是整体实现方案本身。它现在散在五份档里，各自把自己那片讲深，却没有一条把"先做什么、后做什么、什么时候才值得投重型组件"串起来的主轴；《自治富游戏引擎》还停在旧的"双层校验 / 九门"措辞，落后图说与实现详设一个版本；四层档 §11 还挂着六条跨档对齐 TODO 没收口。
 
@@ -26,9 +26,9 @@ tier2 这条线的"要造什么"已经想透并经 2026-06-20 对抗审查拍板
 
 - **起步只跑单写实现（阶段 2），工作室 Agent Team（阶段 1）后置；这是范围裁剪、不是永久颠倒。** 早期迭代先把单个写者 agent 的 ReAct 多轮循环 + L1 校验跑通，最快拿到"M3+mmx 能不能产出过门的 mini-肥鹅"这个真信号。生产态正式流程仍是阶段 1 工作室设计 → 阶段 2 单写实现；起步只跑阶段 2，是 spike / 早期证路对范围的裁剪，证据出来后恢复阶段 1。
 
-- **集成方法论 = 用 agentscope-skill 逐条源码核对"复用 vs 自建"，并含一项版本迁移。** 集成阶段不靠记忆里的 API 印象动手，而是用 `.claude/skills/agentscope-skill`：读已 clone 的源码（`/root/oss/agentscope`，2.0.3）、查真实签名、浏览 `examples/` 的装配样例。集成的离线权威 = 该 skill 现含的 AgentScope 2.0 官方文档镜像（`references/v2-building-blocks` / `v2-deploy` / `studio-rest-api`，snapshot 2026-06-22）+ 源码；**注意该 skill 的 SKILL.md 正文示例仍是 1.x（`ReActAgent` / `MsgHub`），2.0.3 已无/已删，别照抄——v2 镜像 + 源码才是权威**。还要特别认一项工作：种子 `studio.py` 现依赖 `agentscope==2.0.1`，fork 起步包含一项从 2.0.1 迁到 2.0.3 的 API 适配（参照四层档 §验证状态已列的纠偏清单），不是纯拷贝放开 max_iters 就能跑。
+- **集成方法论 = 用 agentscope-skill 逐条源码核对"复用 vs 自建"，并含一项版本迁移。** 集成阶段不靠记忆里的 API 印象动手，而是用 `.claude/skills/agentscope-skill`：读已 clone 的源码（`/root/oss/agentscope`，2.0.2）、查真实签名、浏览 `examples/` 的装配样例。集成的离线权威 = 该 skill 现含的 AgentScope 2.0 官方文档镜像（`references/v2-building-blocks` / `v2-deploy` / `studio-rest-api`，snapshot 2026-06-22）+ 源码；**注意该 skill 的 SKILL.md 正文示例仍是 1.x（`ReActAgent` / `MsgHub`），2.0.2 已无/已删，别照抄——v2 镜像 + 源码才是权威**。还要特别认一项工作：种子 `studio.py` 现依赖 `agentscope==2.0.1`，fork 起步包含一项从 2.0.1 迁到 2.0.2 的 API 适配（参照四层档 §验证状态已列的纠偏清单），不是纯拷贝放开 max_iters 就能跑。
 
-- **沙箱用自带 Workspace；浏览器探针对 Phaser 是重写、且是 spike 前置阻断项。** 2.0.3 自带 `Workspace`（`Local/Docker/E2B`），代码、构建、shell 隔离开箱即用，不是阻断项。L1 确定性门要的"浏览器真跑 + 低层探针"不在内置里，接仓内现成 CDP harness（`play.cdp.cjs`）——但其探针硬编码 LittleJS 专属选择器与帧源，对 Phaser 是**重写适配层、不是参数化**；这条路径可行性（含 BrowserSandbox 是否够用、不够则自建薄沙箱）是属主标记的 **spike 前置阻断项**，须在迭代开跑前出结论。
+- **沙箱用自带 Workspace；浏览器探针对 Phaser 是重写、且是 spike 前置阻断项。** 2.0.2 自带 `Workspace`（`Local/Docker/E2B`），代码、构建、shell 隔离开箱即用，不是阻断项。L1 确定性门要的"浏览器真跑 + 低层探针"不在内置里，接仓内现成 CDP harness（`play.cdp.cjs`）——但其探针硬编码 LittleJS 专属选择器与帧源，对 Phaser 是**重写适配层、不是参数化**；这条路径可行性（含 BrowserSandbox 是否够用、不够则自建薄沙箱）是属主标记的 **spike 前置阻断项**，须在迭代开跑前出结论。
 
 - **先出硬证据，再建重机器。** 即便采用"先集成再迭代"的顺序，仍把"便宜档 n≥30 的硬门通过"摆在投入重型组件（完整配置外置、控制面、第二装载分支、ReMe、工作室 Agent Team）之前。M3 单款跑通只是软门（证路），不等于便宜模型自治可投——这是把"最深赌注在最便宜时验"保留为可判定的硬约束，而非口头信心。
 
@@ -56,7 +56,7 @@ flowchart TB
 **起步 · 集成与环境（无论生成证据如何都要做）**
 
 - R1. AgentScope 集成（pre-spike 档）：起步只用 `Agent` + `ReActConfig` + `Workspace` 跑本地/脚本 runner，**不上**官方 Agent Service / Agent Team / 配置外置（承《实现详设》spike 最小版"先不上 service"）。Agent Service（REST + SSE + durable session）移到硬门通过后的生产接入阶段。
-- R2. 单写循环演进 + 版本迁移：以种子 `studio.py`（现 `agentscope==2.0.1`、`ReActConfig(max_iters=1)` + 外层 repair）fork 起步，含一项 2.0.1→2.0.3 API 适配，并把多轮自治从外层 repair 搬进 Agent 内 ReAct（放开 `max_iters`）；运行期零依赖现有 worker。
+- R2. 单写循环演进 + 版本迁移：以种子 `studio.py`（现 `agentscope==2.0.1`、`ReActConfig(max_iters=1)` + 外层 repair）fork 起步，含一项 2.0.1→2.0.2 API 适配，并把多轮自治从外层 repair 搬进 Agent 内 ReAct（放开 `max_iters`）；运行期零依赖现有 worker。
 - R3. Phaser 浏览器探针路径（pre-spike 阻断验证）：Workspace 自带沙箱解决代码/构建/shell；L1 门要的浏览器真跑低层探针接现成 CDP harness（`play.cdp.cjs`），其探针为 LittleJS 专属（`#game-engine`、`window.__engine.snapshot().frame`、帧判据、像素阈值），对 Phaser 是**重写适配层**。此路径可行性（含 BrowserSandbox 是否够用、不够则自建薄沙箱 + Phaser driver 重写工作包）是属主标记的 **spike 前置阻断项**，须在迭代开跑前出结论。
 - R4. mini-肥鹅 fixture（迭代靶子 + spike 产物目录范本）：按《实现详设》规格预建经营骨架工程（三系统 + 耦合点、先天过 boot，12 物品 / 6 合成链 / 5 订单 / 2 货币）。spike 产物以 `Workspace.workdir` 本地多文件工程形态存在、由 harness 直接在该目录构建 + 真跑，**不走正式源项目契约 / 落库**（落库取回随重机器后置）。
 - R5. mmx 资产管线（最简形态）：起步把 mmx-cli 接成**单写 agent 可调的资产工具**（进 Toolkit、有 tool schema、与 M3 同在一个 ReAct 回路）产美术与音乐；用量计入成本台账。
@@ -106,7 +106,7 @@ flowchart TB
 ## Dependencies / Assumptions
 
 - 模型出口依赖 new-api 网关（`baseUrl` + `NEWAPI_KEY`，凭据见 `docs/内网凭据与端点.md`）；M3 走其 Anthropic 端点，便宜档走各自端点，all roads 收口到一个计费平面。
-- 依赖 mmx-cli（美术 / 音乐资产管线，创始人已亲验拍板）、仓内现成 CDP harness（`play.cdp.cjs`）、已 clone 的 AgentScope 2.0.3 源码（`/root/oss/agentscope`）。种子 `studio.py` 现钉 `agentscope==2.0.1`，迁移成本计入起步。
+- 依赖 mmx-cli（美术 / 音乐资产管线，创始人已亲验拍板）、仓内现成 CDP harness（`play.cdp.cjs`）、已 clone 的 AgentScope 2.0.2 源码（`/root/oss/agentscope`）。种子 `studio.py` 现钉 `agentscope==2.0.1`，迁移成本计入起步。
 - 真跑与 e2e 在 mini-desktop（权威构建、x86 同构）；6c6g 本机禁 chrome，不在本机跑浏览器。
 - 假设 Workspace 自带沙箱 + 重写后的 Phaser CDP 探针足够覆盖 L1 确定性探针——这是 spike 前置阻断验证（R3）要先证的。
 - 假设便宜 / 中等模型自治可达——这是全线最大的未验证假设，正是迭代要证的赌注。务必把它与"2026-06-18 已证便宜模型产 Tier0/1 声明式数据壳过门"硬区分：后者已证、是另一档；tier2 的 Phaser 富游戏自治零证据，历史 Fable+Phaser 只证形态。
@@ -127,6 +127,6 @@ flowchart TB
 ## Sources / Research
 
 - 属主设计档：`docs/architecture/架构/生成引擎/` 下《自治富游戏引擎》《tier2 四层工程架构》《tier2 实现详设》《agentic 集成架构》《agentic 运行时架构图说》（含 9 图）与《生成引擎图说》总入口。
-- 框架实证：AgentScope 2.0.3 源码 `/root/oss/agentscope`；速查 `.agents/knowledge/agentscope-2.0.3-facts.md`；集成方法论 + v2 离线权威 `.claude/skills/agentscope-skill`（含 AgentScope 2.0 官方文档镜像 `references/v2-*.md` + `studio-rest-api.md`，snapshot 2026-06-22；SKILL.md 正文示例为 1.x、勿照抄）。仓内实证：种子依赖 `wg1/gen-worker/requirements-l2.txt`（`agentscope==2.0.1`）、`wg1/gen-worker/worker/agent_loop/studio.py:159`（`ReActConfig(max_iters=1)`）、CDP 探针 `play.cdp.cjs`（LittleJS 专属硬编码）。
+- 框架实证：AgentScope 2.0.2 源码 `/root/oss/agentscope`；速查 `.agents/knowledge/agentscope-2.0.2-facts.md`；集成方法论 + v2 离线权威 `.claude/skills/agentscope-skill`（含 AgentScope 2.0 官方文档镜像 `references/v2-*.md` + `studio-rest-api.md`，snapshot 2026-06-22；SKILL.md 正文示例为 1.x、勿照抄）。仓内实证：种子依赖 `wg1/gen-worker/requirements-l2.txt`（`agentscope==2.0.1`）、`wg1/gen-worker/worker/agent_loop/studio.py:159`（`ReActConfig(max_iters=1)`）、CDP 探针 `play.cdp.cjs`（LittleJS 专属硬编码）。
 - 廉价线对照：`引擎与运行时.md`（装载契约 / CDP harness 门坑）、`固定游戏架构.md`、`设计合理性裁决.md`（tier2 另起一轨的判决理由）。
 - 关键记忆：`saa-agentic-infra-decision`、`m3-agentic-anthropic-protocol`、`generation-lifecycle-project-model`、`true-structured-foundation-proven`（Tier0/1 声明式数据壳已证、与 tier2 硬区分）、`mmx-asset-pipeline`、`tiered-engine-cocos-decision`。

docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md

@@ -1,16 +1,16 @@
 ---
-title: "feat: tier2 富游戏自治生成线实现方案（AgentScope 2.0.3 + Phaser）"
+title: "feat: tier2 富游戏自治生成线实现方案（AgentScope 2.0.2 + Phaser）"
 type: feat
 status: active
 date: 2026-06-22
 origin: docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md
 ---
 
-# feat: tier2 富游戏自治生成线实现方案（AgentScope 2.0.3 + Phaser）
+# feat: tier2 富游戏自治生成线实现方案（AgentScope 2.0.2 + Phaser）
 
 ## Summary
 
-把 tier2 富游戏自治生成线从设计落成可执行序列：先在新顶层 `tier2/` 搭起一个独立的 AgentScope 2.0.3 Python 模块（fork 现有廉价线种子 worker、单写起步、本地 runner、不上 Agent Service），再用 M3 写代码逻辑、mmx 产美术音乐，在三层校验（初期只焊 L1）的笼子里连续迭代生成引擎。顺序连续、判据离散——M3 证路是软门、便宜档 n≥30 是硬门、退路树沿用《tier2 实现详设》的数字触发线，只有硬门通过才投入重机器（工作室 Agent Team、第二装载分支、配置外置、控制面、ReMe）。Phase A（集成+环境+迭代）写成可立即执行的详细单元；Phase B（重机器）写成纲要、显式 gated 在 B 门后。
+把 tier2 富游戏自治生成线从设计落成可执行序列：先在新顶层 `tier2/` 搭起一个独立的 AgentScope 2.0.2 Python 模块（fork 现有廉价线种子 worker、单写起步、本地 runner、不上 Agent Service），再用 M3 写代码逻辑、mmx 产美术音乐，在三层校验（初期只焊 L1）的笼子里连续迭代生成引擎。顺序连续、判据离散——M3 证路是软门、便宜档 n≥30 是硬门、退路树沿用《tier2 实现详设》的数字触发线，只有硬门通过才投入重机器（工作室 Agent Team、第二装载分支、配置外置、控制面、ReMe）。Phase A（集成+环境+迭代）写成可立即执行的详细单元；Phase B（重机器）写成纲要、显式 gated 在 B 门后。
 
 ## Problem Frame
 
@@ -24,7 +24,7 @@ tier2 就是这条轨：用约束自治（O2）的单写 ReAct agent + Phaser
 
 - **代码落点 = 新顶层 `tier2/`**：独立模块、与 `wg1/`（廉价线 Python worker）并列、与 game-cloud 的 Java SAA 线运行期零耦合。理由：origin 定 tier2 为"独立 AgentScope 模块、SAA 可删、运行期零依赖"；物理隔离 + forbidden-import 守门把这条落地。这是可调整的——若改为 `wg1/` 下或别的根，全部 `**Files:**` 路径随之平移。
 
-- **锁 AgentScope 2.0.3；但「迁移=版本钉」只对 AgentScope 框架接缝成立，种子业务模块链要按 Phaser 重写**：迁移面取证证明种子用到的 AgentScope 框架符号（`Agent`/`ReActConfig`/`UserMsg`/`OpenAICredential`/`OpenAIChatModel` + duck-typed `ChatUsage`）在 2.0.3 全兼容、0 改签名——**这层确实是版本钉**（`requirements` 钉 `2.0.3`）。**但 `studio.py` 拖着的业务模块链（`validate.py`/`run.py`/`roles.py`/`prompt.py`）是 LittleJS 专属、要按 Phaser 重写、工作量≈net-new**：`validate` 的硬规则（禁 import / 禁 littlejsengine / 必须单 `export default` 工厂）对 Phaser 多文件 `src/` 工程**完全反转**；`run` 的 `scaffold`/`build`/`play` 是 LittleJS 单包 iife 形态；`roles.DESIGN_SYSTEM` 全是声明式壳 few-shot。别让"框架符号兼容"误导成"整个 U2 是平移"。真正的 AgentScope 新功夫另在 net-new 的多轮 ReAct / Workspace / Service（Phase B）。
+- **锁 AgentScope 2.0.2；但「迁移=版本钉」只对 AgentScope 框架接缝成立，种子业务模块链要按 Phaser 重写**：迁移面取证证明种子用到的 AgentScope 框架符号（`Agent`/`ReActConfig`/`UserMsg`/`OpenAICredential`/`OpenAIChatModel` + duck-typed `ChatUsage`）在 2.0.2 全兼容、0 改签名——**这层确实是版本钉**（`requirements` 钉 `2.0.2`）。**但 `studio.py` 拖着的业务模块链（`validate.py`/`run.py`/`roles.py`/`prompt.py`）是 LittleJS 专属、要按 Phaser 重写、工作量≈net-new**：`validate` 的硬规则（禁 import / 禁 littlejsengine / 必须单 `export default` 工厂）对 Phaser 多文件 `src/` 工程**完全反转**；`run` 的 `scaffold`/`build`/`play` 是 LittleJS 单包 iife 形态；`roles.DESIGN_SYSTEM` 全是声明式壳 few-shot。别让"框架符号兼容"误导成"整个 U2 是平移"。真正的 AgentScope 新功夫另在 net-new 的多轮 ReAct / Workspace / Service（Phase B）。
 
 - **顺序软、判据硬**：先集成+环境再连续迭代（顺序连续，不设建设前的离散生死门），但生成证据的判据保持离散可判定——A 门 = M3 证路（软，创始人试玩判"有肥鹅味的可玩雏形"）；B 门 = 便宜/强便宜档 deepseek-v4 跑 n≥30，过门率/单款成本/收敛/失败分布达《tier2 实现详设》阈值（硬）；退路树沿用《tier2 实现详设》数字触发线（v4-pro<40%→更模板化 / 某系统装不出→补骨架 / 全线<20%→便宜模型天花板换档），达任一触发线即转退路、不再调参。双评审揪出"软化顺序时别把判据也软化"是本计划最要紧的一条纠正。
 
@@ -69,8 +69,8 @@ tier2 就是这条轨：用约束自治（O2）的单写 ReAct agent + Phaser
 ```mermaid
 flowchart TB
   subgraph PA["Phase A · 集成+环境+生成迭代（立即可执行）"]
-    U1["U1 tier2 独立模块骨架<br/>落点 tier2/ · 锁 2.0.3 · 复用 client/cost · forbidden-import"]
-    U2["U2 fork 种子 → 2.0.3 + Agent 内多轮 ReAct<br/>放开 max_iters · 两阶段角色(起步只单写)"]
+    U1["U1 tier2 独立模块骨架<br/>落点 tier2/ · 锁 2.0.2 · 复用 client/cost · forbidden-import"]
+    U2["U2 fork 种子 → 2.0.2 + Agent 内多轮 ReAct<br/>放开 max_iters · 两阶段角色(起步只单写)"]
     U3["U3 Phaser 浏览器探针路径(前置阻断验证)<br/>沙箱底座小验证 + CDP harness 为 Phaser 重写"]
     U4["U4 mini-肥鹅 Phaser 靶子<br/>经营骨架+耦合点+数据表schema+资产占位"]
     U5["U5 mmx 资产管线接成 agent 工具"]
@@ -104,7 +104,7 @@ flowchart TB
 **起步 · 集成与环境（无论生成证据如何都要做）**
 
 - R1. AgentScope 集成 pre-spike 档：起步只用 `Agent`+`ReActConfig`+`Workspace` 本地 runner，不上 Agent Service / Agent Team / 配置外置。→ U1, U2
-- R2. 单写循环演进 + 版本钉：fork 种子，`agentscope` 钉 2.0.3，多轮自治从外层 repair 搬进 Agent 内 ReAct（放开 `max_iters`），运行期零依赖现有 worker。→ U2
+- R2. 单写循环演进 + 版本钉：fork 种子，`agentscope` 钉 2.0.2，多轮自治从外层 repair 搬进 Agent 内 ReAct（放开 `max_iters`），运行期零依赖现有 worker。→ U2
 - R3. Phaser 浏览器探针路径前置阻断验证：Workspace 解决代码/构建/shell；L1 门要的浏览器真跑低层探针接 CDP harness，对 Phaser 是重写；底座可行性须迭代开跑前出结论。→ U3
 - R4. mini-肥鹅 fixture（迭代靶子 + spike 产物目录范本）：经营骨架（三系统+耦合点、先天过 boot），产物以 `Workspace.workdir` 本地多文件工程形态、harness 直接构建+真跑，不走正式契约/落库。→ U4
 - R5. mmx 资产管线最简形态：接成单写 agent 可调资产工具。→ U5
@@ -142,45 +142,45 @@ flowchart TB
 
 ### U1. tier2 独立模块骨架 + 依赖 + 复用 + forbidden-import 守门
 
-- **Goal**：在 `tier2/` 立起一个独立 AgentScope 2.0.3 Python 模块骨架，含独立依赖、对 `_client.py`/`cost.py` 的显式传参复用接缝、以及禁运行期 import SAA 的 CI 守门。这是其余单元的地基。
+- **Goal**：在 `tier2/` 立起一个独立 AgentScope 2.0.2 Python 模块骨架，含独立依赖、对 `_client.py`/`cost.py` 的显式传参复用接缝、以及禁运行期 import SAA 的 CI 守门。这是其余单元的地基。
 - **Requirements**：R1, R7, R20
 - **Dependencies**：无
 - **Files**：
-  - `tier2/gen-worker/requirements.txt`（新建：`agentscope==2.0.3` + `phaser` 工具链所需 + `pyyaml`；不复用 `wg1/gen-worker/requirements-l2.txt` 的 2.0.1）
+  - `tier2/gen-worker/requirements.txt`（新建：`agentscope==2.0.2` + `phaser` 工具链所需 + `pyyaml`；不复用 `wg1/gen-worker/requirements-l2.txt` 的 2.0.1）
   - `tier2/gen-worker/worker/cost_reuse.py`（新建：薄包装，显式传 endpoint/key/pricing/quota，内部转调 `wg1/gen-worker/worker/cost.py:compute`——纯函数可直接复用）
   - `tier2/gen-worker/worker/client_reuse.py`（新建：薄包装，显式传 endpoint/key/model/retry/timeout，禁读 `_client.py` 模块级 `BASE_URL`/全局）
   - `tier2/.agent`（新建：模块目标/边界/红线声明，参照 `game-runtime/games/_wg1-gen/.agent`）
   - `tier2/ci/check-forbidden-import.sh`（新建：参照 `.agents/tools/check-deadlinks.sh` 形制，扫 `tier2/` 禁 import `wg1.*` 运行态 / SAA 配置 / L2 模型路由）
-  - `tier2/README.md`（新建：指向本 plan + origin + agentscope-2.0.3-facts）
-- **Approach**：tier2 自有 env、独立锁 2.0.3。复用边界严格走"显式传参"——`cost.compute()` 已是纯函数直接调。**注意 agent 循环真正消费的不是 `_client.chat()`（那是 L1 裸路、agent 不调），而是 `_client` 的模块级 `BASE_URL` + `get_api_key()` + import 副作用（`.env` 加载 + 必须在 import agentscope 前设 NO_PROXY 代理旁路——`config.py:11` 注释明示是 spike 头号坑）**。所以要显式参数化的是 endpoint/key 来源 + 显式、有序地处理那个代理旁路副作用，而非包装 `chat()`。forbidden-import 脚本进 CI（pre-spike 验收项）。
+  - `tier2/README.md`（新建：指向本 plan + origin + agentscope-2.0.2-facts）
+- **Approach**：tier2 自有 env、独立锁 2.0.2。复用边界严格走"显式传参"——`cost.compute()` 已是纯函数直接调。**注意 agent 循环真正消费的不是 `_client.chat()`（那是 L1 裸路、agent 不调），而是 `_client` 的模块级 `BASE_URL` + `get_api_key()` + import 副作用（`.env` 加载 + 必须在 import agentscope 前设 NO_PROXY 代理旁路——`config.py:11` 注释明示是 spike 头号坑）**。所以要显式参数化的是 endpoint/key 来源 + 显式、有序地处理那个代理旁路副作用，而非包装 `chat()`。forbidden-import 脚本进 CI（pre-spike 验收项）。
 - **Patterns to follow**：`wg1/gen-worker/worker/cost.py:compute`（纯函数范本）、`game-runtime/games/_wg1-gen/.agent`（模块隔离声明）、`.agents/tools/check-deadlinks.sh`（CI 脚本形制）
 - **Test scenarios**：
   - `tier2/ci/check-forbidden-import.sh` 对一个故意 `import wg1...` 的样例文件返回非零（守门生效）；对干净 tier2 代码返回零。
   - `cost_reuse` 用显式传入的 pricing/qpu/usd_rate 调 `compute`，结果与直接调 `wg1` `cost.compute` 一致（复用未走样）。
   - `client_reuse` 在未设模块级 `BASE_URL` 时仍能用显式 endpoint 工作（证不依赖全局）。
-- **Verification**：`pip install -r tier2/gen-worker/requirements.txt` 成功且 `agentscope.__version__ == "2.0.3"`；forbidden-import CI 在干净树通过、对违例样例失败；复用包装的单测绿。
+- **Verification**：`pip install -r tier2/gen-worker/requirements.txt` 成功且 `agentscope.__version__ == "2.0.2"`；forbidden-import CI 在干净树通过、对违例样例失败；复用包装的单测绿。
 
-### U2. fork 种子 worker → 2.0.3 + Agent 内多轮自治 ReAct
+### U2. fork 种子 worker → 2.0.2 + Agent 内多轮自治 ReAct
 
-- **Goal**：以 `wg1/gen-worker/worker/agent_loop/studio.py` 为种子拷贝到 `tier2/`，版本钉 2.0.3（代码零签名改），把多轮自治从外层 repair 循环搬进 Agent 内 ReAct（放开 `max_iters`），并按两阶段重写角色 prompt（起步只单写阶段 2）。
+- **Goal**：以 `wg1/gen-worker/worker/agent_loop/studio.py` 为种子拷贝到 `tier2/`，版本钉 2.0.2（代码零签名改），把多轮自治从外层 repair 循环搬进 Agent 内 ReAct（放开 `max_iters`），并按两阶段重写角色 prompt（起步只单写阶段 2）。
 - **Requirements**：R1, R2
 - **Dependencies**：U1
 - **Files**（标注 **fork**=框架接缝可平移 / **重写**=LittleJS 专属、按 Phaser 重做、工作量≈net-new）：
   - `tier2/gen-worker/worker/agent_loop/studio.py`（**fork**：编排骨架可平移；`_agent_reply` 的 `ReActConfig(max_iters=1)` 放开为多轮，外层 `for attempt in range(max_repairs)` 改为 Agent 内 reason→act→读结果→再 reason）
-  - `tier2/gen-worker/worker/agent_loop/config.py`（**fork**：保留 `RecordingChatModel.__call__` 成本取证覆写——2.0.3 仍命中；清 `config.py:30-32` 关于 DeepSeek cache 的过时注释）
+  - `tier2/gen-worker/worker/agent_loop/config.py`（**fork**：保留 `RecordingChatModel.__call__` 成本取证覆写——2.0.2 仍命中；清 `config.py:30-32` 关于 DeepSeek cache 的过时注释）
   - `tier2/gen-worker/worker/validate.py`（**重写**：现 `extract_code` 只认单 ```js 块、`validate` 硬规则=禁 import / 禁 littlejsengine / 必须单 `export default` 工厂——对 Phaser 多文件 `src/` 工程完全反转，重写为多文件抽取 + Phaser 工程校验）
   - `tier2/gen-worker/worker/run.py`（**重写**：`scaffold`/`build`/`play` 三件是 LittleJS 单包 iife 形态，换成 Phaser 多文件 scaffold + 构建 + Phaser CDP harness 接线）
   - `tier2/gen-worker/worker/prompt.py`（**重写**：`build_messages` 按 Phaser 工程 + 两阶段重组）
   - `tier2/gen-worker/worker/agent_loop/roles.py`（**重写**：`DESIGN_SYSTEM` 全是 LittleJS 声明式壳 + gatespec/tap-targets few-shot，按 Phaser 富游戏 + 单写实现角色重写；阶段 1 工作室角色留 Phase B）
-- **Approach**：fork-为-起点、独立演进、运行期零依赖现有 worker、不回写（origin §1.1）。**分清两层**：AgentScope 框架接缝（`studio.py`/`config.py` 的 6 符号）据迁移取证是版本钉、零签名改，重点回归验证 `RecordingChatModel.__call__` 仍被 Agent 经 `await model(...)` 命中（成本取证命脉）；**但 `validate`/`run`/`prompt`/`roles` 是 LittleJS 专属业务逻辑、需按 Phaser 重写（≈net-new），按"6 符号兼容"排期会严重低估**。多轮 ReAct 也是 net-new（种子是单轮），用 2.0.3 `Agent`+`ReActConfig(max_iters=N)`。
+- **Approach**：fork-为-起点、独立演进、运行期零依赖现有 worker、不回写（origin §1.1）。**分清两层**：AgentScope 框架接缝（`studio.py`/`config.py` 的 6 符号）据迁移取证是版本钉、零签名改，重点回归验证 `RecordingChatModel.__call__` 仍被 Agent 经 `await model(...)` 命中（成本取证命脉）；**但 `validate`/`run`/`prompt`/`roles` 是 LittleJS 专属业务逻辑、需按 Phaser 重写（≈net-new），按"6 符号兼容"排期会严重低估**。多轮 ReAct 也是 net-new（种子是单轮），用 2.0.2 `Agent`+`ReActConfig(max_iters=N)`。
 - **Execution note**：先为"Agent 内多轮 ReAct 写源→build→读 verdict→再 reason"写一个最小集成测试（mock 模型 + 假 verdict），证循环骨架跑通，再接真 M3。
 - **Patterns to follow**：`wg1/gen-worker/worker/agent_loop/studio.py`（种子，run_studio@230 / _agent_reply@153 / repair@266 / 五接线点@270-300）、`config.py:RecordingChatModel`（usage 取证）
 - **Test scenarios**：
   - Agent 内多轮：mock 模型先返回"调写工具"再返回"纯文本收尾"，循环正确在收尾终止、产出 src/。
   - `max_iters` 硬顶：mock 模型永远调工具，循环在 `max_iters` 处停（不无限）。
-  - `RecordingChatModel.__call__` 在 2.0.3 被命中：跑一轮真/mock 模型，断言 per-call usage（input/output/cache_input tokens）被捕获。
-  - 版本钉：`agentscope.__version__ == "2.0.3"` 且 6 个框架符号 import 不报错。
-  - 消息形态复验（2.0.3）：`UserMsg(name, content=str)` 仍把 str 包成 `TextBlock`、`agent.reply` 返回 block-list `Msg`（这层是形态契约、不在 6 符号 import 面内）。
+  - `RecordingChatModel.__call__` 在 2.0.2 被命中：跑一轮真/mock 模型，断言 per-call usage（input/output/cache_input tokens）被捕获。
+  - 版本钉：`agentscope.__version__ == "2.0.2"` 且 6 个框架符号 import 不报错。
+  - 消息形态复验（2.0.2）：`UserMsg(name, content=str)` 仍把 str 包成 `TextBlock`、`agent.reply` 返回 block-list `Msg`（这层是形态契约、不在 6 符号 import 面内）。
 - **Verification**：最小集成测试绿；一轮 mock 端到端（组 context→reason→act 写 src/→读 verdict→收尾）跑通；usage 捕获非空。**注意：6 符号 import 通过≠迁移完成**——`validate`/`run`/`prompt`/`roles` 的 Phaser 重写另有各自验收（不被本单元的框架接缝绿误判为"迁移已完成"）。
 
 ### U3. Phaser 浏览器探针路径（spike 前置阻断验证 + CDP harness 重写）
@@ -226,7 +226,7 @@ flowchart TB
 - **Files**：
   - `tier2/gen-worker/worker/tools/mmx_asset_tool.py`（新建：包装 mmx-cli 为 AgentScope `Tool` 工具函数，参数 schema = 资产类型/描述/规格；产物落 `Workspace.workdir` 资产目录）
 - **Approach**：最简形态——mmx 作 agent 同一 ReAct 回路里可调的资产工具（符合"一台游戏工作站"范式），而非旁路并行管线。用量 quota 计入 `cost_reuse` 台账。资产产物进 fixture 的 `_assets/` 同构目录。
-- **Patterns to follow**：memory `mmx-asset-pipeline`（mmx-cli 用法、quota 对账）、AgentScope 2.0.3 `Toolkit(tools=[...])` + `Tool` 工具函数（见 agentscope-skill v2-building-blocks）
+- **Patterns to follow**：memory `mmx-asset-pipeline`（mmx-cli 用法、quota 对账）、AgentScope 2.0.2 `Toolkit(tools=[...])` + `Tool` 工具函数（见 agentscope-skill v2-building-blocks）
 - **Test scenarios**：
   - mmx 工具被 agent 调用一次，产出资产文件落 workdir、且 quota 计入台账。
   - 工具失败（mmx 不可达/超时）返回结构化错误，agent 能据此降级（不崩循环）。
@@ -337,8 +337,8 @@ flowchart TB
 - **最大风险（全线 go/no-go 所系）**：便宜/中等模型自治写 56% 表现层能否稳定达 B 门阈值——零证据，正是 U7 迭代要验的赌注。务必与"2026-06-18 已证便宜模型产 Tier0/1 声明式数据壳过门"硬区分：后者已证、是另一档（gameDefinition 数据壳）；tier2 的 Phaser 富游戏自治零证据，历史 Fable+Phaser 只证形态。
 - **前置阻断（U3）**：Phaser 浏览器探针路径可行性（agentscope-runtime BrowserSandbox 够不够，不够回落自建薄沙箱）须在 U7 迭代开跑前出结论，否则 spike 跑不起来。
 - **运行环境切分（逐单元 · 6c6g 搭骨架 / Mac·mini-desktop 跑调优）**：6c6g 禁 chrome（exit 144）、本机零依赖，凡需真跑 chrome/headless+esbuild 的验证必在 mini-desktop。逐单元归属——**6c6g 可完成**：U1（pip install / 纯函数复用单测 / forbidden-import CI）、U2（mock 模型集成测试 / 版本钉 / 消息形态复验）、U4 与 U5 的骨架与 schema 文件创建。**必须 mini-desktop 真跑**：U3（`page.evaluate`/CDP 探针矩阵真验）、U4（mini-肥鹅 构建+真跑过 boot 门）、U6（门对过门页 pass/空壳页 fail 真验）、U7（M3 smoke / 四熔断真触发 / 闭环端到端 / n≥30）。即"项目初始化（骨架+mock 级）"在 6c6g 完成、"运行调优（真跑迭代）"转交 Mac。
-- **外部依赖**：new-api 网关（`baseUrl`+`NEWAPI_KEY`，凭据见 `docs/内网凭据与端点.md`，M3 走 Anthropic 端点）；mmx-cli（创始人已亲验）；已 clone 的 AgentScope 2.0.3 源码 `/root/oss/agentscope`。
-- **版本风险**：tier2 独立锁 2.0.3，不随廉价线（2.0.1）走；2.0 系列内部 API 仍在变（参照 agentscope-skill 的 v2 离线镜像 + 源码为权威，SKILL.md 正文示例是 1.x 勿照抄）。
+- **外部依赖**：new-api 网关（`baseUrl`+`NEWAPI_KEY`，凭据见 `docs/内网凭据与端点.md`，M3 走 Anthropic 端点）；mmx-cli（创始人已亲验）；已 clone 的 AgentScope 2.0.2 源码 `/root/oss/agentscope`。
+- **版本风险**：tier2 独立锁 2.0.2，不随廉价线（2.0.1）走；2.0 系列内部 API 仍在变（参照 agentscope-skill 的 v2 离线镜像 + 源码为权威，SKILL.md 正文示例是 1.x 勿照抄）。
 
 ---
 
@@ -362,7 +362,7 @@ flowchart TB
 
 - Origin：`docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md`（R1-R21、已定决策、已过 Codex+Opus 双评审）。
 - 属主设计档：`docs/architecture/架构/生成引擎/` 下《tier2 四层工程架构》（§9 spike-grade 7 前置物、§11 T4 forbidden-import）、《tier2 实现详设》（0 号 spike runbook/模型矩阵/过门判据/采集字段/退路树/源项目契约七要素）、《自治富游戏引擎》（O2/引擎选型/三层校验）、《agentic 集成架构》（控制面/D12/trace）、《agentic 运行时架构图说》。
-- 子代理研究（本计划）：repo 文件级定位（种子 `studio.py` run_studio@230 / `ReActConfig(max_iters=1)`@158 / repair@266 / 五接线点；`_client.py`/`cost.py` 复用边界；`play.cdp.cjs`@1131 探针；Tier0/1 装载契约边界；`wanglanmei-ref` 12 文件经营样板）；AgentScope 2.0.1→2.0.3 迁移面取证（6 符号全兼容、迁移=版本钉+注释清理非 API 重写）。
+- 子代理研究（本计划）：repo 文件级定位（种子 `studio.py` run_studio@230 / `ReActConfig(max_iters=1)`@158 / repair@266 / 五接线点；`_client.py`/`cost.py` 复用边界；`play.cdp.cjs`@1131 探针；Tier0/1 装载契约边界；`wanglanmei-ref` 12 文件经营样板）；AgentScope 2.0.1→2.0.2 迁移面取证（6 符号全兼容、迁移=版本钉+注释清理非 API 重写）。
 - A-model 分支（Tier1 agentic 优化 · 复用 / 边界源，见「与 A-model 分支的关系」节）：`feat/mac-amodel-foundation` 的 `game-runtime/tools/amodel-gen/*.mjs`（JS ReAct+M3 循环范式）、`game-runtime/src/plugins/{scene-fsm,hud-ui,session-score,timer-scheduler}/api.d.ts`（引擎无关零语义契约）、`.agents/skills/agentic-amodel-generation.md` + `docs/agent-specs/2026-06-22-amodel-3layer-boundaries-review.md`（3 层边界 + sim-business 配方）、`contracts/agent-loop/source-project.schema.json`（oneOf 1.0/2.0）。
-- 框架权威：`/root/oss/agentscope`（2.0.3 源码）；`.agents/knowledge/agentscope-2.0.3-facts.md`（速查）；agentscope-skill 的 `references/v2-building-blocks.md`/`v2-deploy.md`（v2 离线镜像，集成权威；SKILL.md 正文 1.x 勿照抄）。
+- 框架权威：`/root/oss/agentscope`（2.0.2 源码）；`.agents/knowledge/agentscope-2.0.2-facts.md`（速查）；agentscope-skill 的 `references/v2-building-blocks.md`/`v2-deploy.md`（v2 离线镜像，集成权威；SKILL.md 正文 1.x 勿照抄）。
 - 关键记忆：`saa-agentic-infra-decision`、`m3-agentic-anthropic-protocol`、`generation-lifecycle-project-model`、`true-structured-foundation-proven`（Tier0/1 数据壳已证、与 tier2 硬区分）、`mmx-asset-pipeline`、`tiered-engine-cocos-decision`。

tier2/HANDOFF.md

@@ -6,14 +6,14 @@
 
 - **WHAT 需求**（已过 Codex+Opus 双评审、合入 dev/2.0.0）：`docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md`。
 - **HOW 计划**（已过双评审、本分支 `docs/tier2-plan`）：`docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md`。10 个单元，Phase A（U1-U7，到 A/B 证据门）写成可立即执行的详细单元，Phase B（U8-U10）是 B 门通过后才投的纲要。
-- **项目初始化骨架**（本目录 `tier2/`）：模块 `.agent` 边界声明、`README.md`、`gen-worker/requirements.txt`（锁 `agentscope==2.0.3`）、`ci/check-forbidden-import.sh`（运行期零碰 SAA 的守门）。
-- **框架权威**：`/root/oss/agentscope`（2.0.3 源码）+ `.agents/knowledge/agentscope-2.0.3-facts.md`（速查）+ agentscope-skill 的 `references/v2-*.md`（v2 离线镜像）。⚠️ 该 skill 的 SKILL.md 正文示例是 1.x（`ReActAgent`/`MsgHub`），勿照抄。
+- **项目初始化骨架**（本目录 `tier2/`）：模块 `.agent` 边界声明、`README.md`、`gen-worker/requirements.txt`（锁 `agentscope==2.0.2`）、`ci/check-forbidden-import.sh`（运行期零碰 SAA 的守门）。
+- **框架权威**：`/root/oss/agentscope`（2.0.2 源码）+ `.agents/knowledge/agentscope-2.0.2-facts.md`（速查）+ agentscope-skill 的 `references/v2-*.md`（v2 离线镜像）。⚠️ 该 skill 的 SKILL.md 正文示例是 1.x（`ReActAgent`/`MsgHub`），勿照抄。
 
 ## 接着做（按计划 Phase A）
 
 照 plan 的 U1-U7 实现。几条评审已经替你压实、别再走弯路：
 
-- **U2 是重头**：种子 `wg1/gen-worker/worker/agent_loop/{studio.py,config.py}` 的 AgentScope 框架接缝（6 个符号）与 2.0.3 兼容、是版本钉级别；但它拖着的 `validate.py`/`run.py`/`prompt.py`/`roles.py` 是 **LittleJS 专属**（`validate` 的「禁 import / 单 export default 工厂」规则对 Phaser 多文件工程完全反转），这几件要按 Phaser **重写、工作量≈net-new**，别按「fork+钉版本」排期。
+- **U2 是重头**：种子 `wg1/gen-worker/worker/agent_loop/{studio.py,config.py}` 的 AgentScope 框架接缝（6 个符号）与 2.0.2 兼容、是版本钉级别；但它拖着的 `validate.py`/`run.py`/`prompt.py`/`roles.py` 是 **LittleJS 专属**（`validate` 的「禁 import / 单 export default 工厂」规则对 Phaser 多文件工程完全反转），这几件要按 Phaser **重写、工作量≈net-new**，别按「fork+钉版本」排期。
 - **U3 是前置阻断**：先做沙箱底座小验证（agentscope-runtime BrowserSandbox 是否暴露足够 `page.evaluate`/CDP，不够则回落复用 `play.cdp.cjs` 路），再把 CDP 探针为 Phaser **重写**（`#game-engine` 选择器 / `__engine.frame` 帧源 / boot 信号全换）。这道结论出来前，U7 的生成迭代跑不起来。
 - **U7 成本取证**：M3 走 `AnthropicChatModel`，所以成本台账要补一个 `RecordingChatModel(AnthropicChatModel)` 变体——现有的只覆盖 OpenAI 路，不补则 A 门 M3 成本抓不到。
 - **判据离散**：A 门 = M3 产物先确定性过 L1（机器判）+ 创始人试玩（软）两段与；B 门 = 便宜档 n≥30 达《tier2 实现详设》阈值（硬）才转 Phase B。

tier2/README.md

@@ -2,7 +2,7 @@
 
 这是绘境 AI 的第二条游戏生成线。它和现有的超休闲廉价线（`wg1/` + LittleJS）解耦并存、运行期零耦合：廉价线用便宜模型往声明式数据壳里填空、做单局几何色块小游戏；tier2 则给一个 AI agent 一台完整的游戏工作站——读文档、写多个 Phaser 源文件、构建、在真浏览器里真玩验收、看截图、查资产——让它在一圈确定性验收门的笼子里反复迭代，把现有产线做不出的多系统富游戏（合成、经营、挂机这类肥鹅美食街档）逼出来。
 
-底座是 AgentScope 2.0.3（独立锁版、独立 env），引擎选 Phaser/Pixi（过无头硬筛、按 AI 作者视角取生态厚度）。生成范式是约束自治（O2）：把一款游戏拆成数据表、系统骨架、表现层三层，用骨架和插件 API 锁住系统层最难的部分，把便宜模型的火力集中到必须写的约 56% 表现层，再用三层校验和四道熔断把自治关在笼子里。
+底座是 AgentScope 2.0.2（独立锁版、独立 env），引擎选 Phaser/Pixi（过无头硬筛、按 AI 作者视角取生态厚度）。生成范式是约束自治（O2）：把一款游戏拆成数据表、系统骨架、表现层三层，用骨架和插件 API 锁住系统层最难的部分，把便宜模型的火力集中到必须写的约 56% 表现层，再用三层校验和四道熔断把自治关在笼子里。
 
 整条线最深、也最没证过的赌注是：便宜或中等模型的自治 agent 能不能稳定写出那 56% 的表现层。所以建设按「顺序软、判据硬」走——先把集成和环境搭扎实，再用 M3（写代码逻辑）+ mmx（产美术音乐）连续迭代；但生成证据的判据保持离散可判定：M3 证路是软门、便宜档 n≥30 是硬门、退路树沿用数字触发线，只有硬门通过才投入重机器。
 
@@ -12,8 +12,8 @@
 - **怎么建（照这个动手）**：`docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md`（HOW，10 单元，Phase A 详 / Phase B 纲要）。
 - **接手须知**：`HANDOFF.md`（本次 6c6g 初始化交付了什么、Mac 接着做什么、环境切分）。
 - **模块边界与红线**：`.agent`。
-- **AgentScope 2.0.3 真实 API**：`.agents/knowledge/agentscope-2.0.3-facts.md`（拿不准先读 `/root/oss/agentscope` 源码 + agentscope-skill 的 `references/v2-*.md` 离线镜像；该 skill 的 SKILL.md 正文示例是 1.x，勿照抄）。
+- **AgentScope 2.0.2 真实 API**：`.agents/knowledge/agentscope-2.0.2-facts.md`（拿不准先读 `/root/oss/agentscope` 源码 + agentscope-skill 的 `references/v2-*.md` 离线镜像；该 skill 的 SKILL.md 正文示例是 1.x，勿照抄）。
 
 ## 现状
 
-2026-06-22 在 6c6g 完成项目初始化：模块骨架、独立依赖（`agentscope==2.0.3`）、governance、forbidden-import CI 就位。实现与运行调优转交 Mac / mini-desktop（真跑需 chrome/headless+esbuild，6c6g 禁 chrome）。
+2026-06-22 在 6c6g 完成项目初始化：模块骨架、独立依赖（`agentscope==2.0.2`）、governance、forbidden-import CI 就位。实现与运行调优转交 Mac / mini-desktop（真跑需 chrome/headless+esbuild，6c6g 禁 chrome）。

tier2/gen-worker/requirements.txt

@@ -1,8 +1,8 @@
 # tier2 富游戏自治生成线 · Python worker 依赖
 # 独立锁版，不复用 wg1/gen-worker 的 agentscope==2.0.1。
-# 框架接缝据迁移取证与 wg1 种子兼容；锁 2.0.3 的理由见
+# 框架接缝据迁移取证与 wg1 种子兼容；锁 2.0.2 的理由见
 # docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md（KTD2）。
-agentscope==2.0.3
+agentscope==2.0.2
 openai>=2.41.1        # 便宜档（deepseek-v4 等）走 OpenAI 兼容端点（new-api）
 json-repair          # 脏 JSON 兜底（承袭裸路）
 pyyaml               # 模型路由 models.yaml